docs: 编写中文 README

README.md

@@ -0,0 +1,97 @@
+# 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 和仓库变量中。