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/           本地管网数据读写与转换，交付镜像中必须封装
scripts/compile.py    Cython 封装脚本
infra/docker/         Docker Compose 编排
tests/                后端测试

本地开发

推荐使用已有 conda 环境：

conda run -n server python -m pytest tests -q
conda run -n server python scripts/run_server.py

本地调试不要在正常工作树执行源码删除命令。

客户版镜像打包

交付镜像标签通常为：

docker build -t tjwater-server:latest .

Dockerfile 会在 builder 阶段执行：

python scripts/compile.py
python scripts/compile.py --delete-source

源码删除只发生在 Docker 构建层内，不会删除本地工作树源码。详细封装、验证和 Windows 导出说明见：

DELIVERY_PACKAGING_NOTES.md

封装范围

scripts/compile.py 默认封装：

app/services
app/native/wndb
app/algorithms
app/infra/epanet/epanet.py

交付镜像中这些核心目录不应残留未编译的 .py 源码，应以 .so 扩展模块运行。

验证命令

构建后检查镜像：

docker image ls tjwater-server

检查核心源码是否已删除、FastAPI 入口是否可导入：

docker run --rm --entrypoint sh tjwater-server:latest -c "\
printf 'core_py_count='; \
find /app/app/services /app/app/native/wndb /app/app/algorithms /app/app/infra/epanet/epanet.py -name '*.py' 2>/dev/null | wc -l; \
printf 'core_so_count='; \
find /app/app/services /app/app/native/wndb /app/app/algorithms /app/app/infra/epanet -name '*.so' 2>/dev/null | wc -l; \
python -c 'import app.main; print(\"import_app_main=ok\")'"

期望结果：

core_py_count=0
core_so_count=<非零>
import_app_main=ok

部署注意

客户交付时不要把本地 ../../app 挂载到容器 /app/app，否则会覆盖镜像内已封装代码。交付 compose 文件应使用构建好的镜像，只挂载必要的运行数据和配置。

安全规则

不要提交 .env、生产凭据、客户数据、数据库 dump、日志、生成缓存、临时交付压缩包或本地运行目录。客户版仓库不应加入内部实验、调试工具或非交付源码材料。