# TJWaterServerBinary 内部后端

`TJWaterServerBinary` 是 TJWater 内部版 Python 后端，基于 FastAPI 提供认证、项目、管网、模拟、爆管、漏损、SCADA、地图服务集成和命令行工具能力。该仓库用于内部开发和完整功能维护。

## 技术栈

- Python 3.12
- FastAPI / Uvicorn
- Pydantic / SQLAlchemy / psycopg
- Redis、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/           本地管网数据读写与转换
cli/                  tjwater-cli 命令行工具
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 配置和变量展开。

## CLI

CLI 位于 `cli/tjwater_cli`，说明见：

```text
cli/README.md
```

修改 CLI 参数、输出结构或后端接口适配时，应同步更新 CLI 测试和文档。

## 开发规范

- Python 文件、函数、变量、Pydantic 字段、JSON body 字段和 query 参数使用 `snake_case`。
- Python 类和 Pydantic 模型使用 `PascalCase`。
- 新 HTTP 路径使用 `kebab-case`，例如 `/api/v1/pressure-status/analyze`。
- 优先复用现有 FastAPI/service/repository 边界。
- 不要把临时数据、数据库 dump、日志或本地运行产物纳入提交。

## 测试与发布

提交前根据改动范围运行最小有效测试：

```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 和仓库变量中。