97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# TJWaterServerBinary 内部后端
|
|
|
|
`TJWaterServerBinary` 是 TJWater 内部版 Python 后端，基于 FastAPI 提供认证、项目、管网、模拟、爆管、漏损、SCADA 和地图服务集成能力。该仓库用于内部开发和完整功能维护。
|
|
|
|
## 技术栈
|
|
|
|
- Python 3.12
|
|
- FastAPI / Uvicorn
|
|
- Pydantic / SQLAlchemy / psycopg
|
|
- PostgreSQL、PostGIS、TimescaleDB
|
|
- WNTR、EPANET、Cython、科学计算与空间分析依赖
|
|
- pytest
|
|
|
|
## 目录结构
|
|
|
|
```text
|
|
app/main.py FastAPI 入口
|
|
app/api/ HTTP API 路由
|
|
app/auth/ 认证和权限上下文
|
|
app/core/ 配置、日志和基础设施初始化
|
|
app/domain/ 领域模型和 Pydantic schema
|
|
app/infra/ 数据库、EPANET 和外部集成
|
|
app/services/ 业务服务编排
|
|
app/algorithms/ 管网算法、模拟、爆管、漏损、清洗和健康分析
|
|
app/native/ 本地管网数据读写与转换
|
|
tests/ 后端测试
|
|
resources/ SQL、模板和示例资源
|
|
infra/docker/ Docker Compose 编排
|
|
```
|
|
|
|
## 本地开发
|
|
|
|
推荐使用已有 conda 环境：
|
|
|
|
```bash
|
|
conda run -n server python -m pytest tests/unit tests/auth -q
|
|
conda run -n server uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
如需要进入环境：
|
|
|
|
```bash
|
|
conda activate server
|
|
```
|
|
|
|
## 常用命令
|
|
|
|
```bash
|
|
conda run -n server python -m pytest tests -q
|
|
conda run -n server python scripts/run_server.py
|
|
docker build -t tjwater-server:local .
|
|
docker compose -f infra/docker/docker-compose.yml config
|
|
```
|
|
|
|
- `pytest`：运行自动化测试。
|
|
- `scripts/run_server.py`：使用项目脚本启动服务。
|
|
- `docker build`：构建后端镜像。
|
|
- `docker compose config`：检查 compose 配置和变量展开。
|
|
|
|
## 开发规范
|
|
|
|
- Python 文件、函数、变量、Pydantic 字段、JSON body 字段和 query 参数使用 `snake_case`。
|
|
- Python 类和 Pydantic 模型使用 `PascalCase`。
|
|
- 新 HTTP 路径使用 `kebab-case`，例如 `/api/v1/pressure-status/analyze`。
|
|
- 优先复用现有 FastAPI/service/repository 边界。
|
|
- 不要把临时数据、数据库 dump、日志或本地运行产物纳入提交。
|
|
|
|
## 项目数据库路由
|
|
|
|
项目级 REST 请求通过 `X-Project-Id` 解析元数据中的数据库配置：
|
|
|
|
- `biz_data` DSN 用于管网业务数据；版本模板固定由 `WNDB_TEMPLATE_DB_NAME` 配置（当前为 `tjwater_v2_template`），模拟临时库沿用该 DSN 的主机、端口与凭据，仅替换数据库名。
|
|
- `iot_data` DSN 用于 TimescaleDB，始终使用元数据配置的完整 DSN，不再从项目代码推导数据库名。
|
|
- 元数据、业务库和 TimescaleDB 可以部署在同一主机，也可以分别部署。
|
|
|
|
使用模板复制或临时方案库的模拟功能时，`biz_data` 账号必须具备数据库创建和删除权限；只有显式删除项目时才会终止该项目的现有数据库会话，普通复制不会主动中断复制源会话。
|
|
|
|
## 测试与发布
|
|
|
|
提交前根据改动范围运行最小有效测试：
|
|
|
|
```bash
|
|
conda run -n server python -m pytest tests/unit tests/auth -q
|
|
```
|
|
|
|
发布镜像前建议运行：
|
|
|
|
```bash
|
|
docker build -t tjwater-server:local .
|
|
```
|
|
|
|
Gitea 包工作流位于 `.gitea/workflows/package.yml`，通常由 tag 触发构建、推送镜像并通知部署 webhook。
|
|
|
|
## 安全规则
|
|
|
|
不要提交 `.env`、客户数据、数据库 dump、日志、生成缓存、`db_inp/`、`temp/`、`data/` 或本地密钥。CI/CD 凭据应放在 Gitea secrets 和仓库变量中。
|