更新readme文档

readme.md

@@ -1,41 +1,97 @@
 # TJWater Server (FastAPI)
 
-基于 FastAPI 的水务业务服务端，提供模拟计算、SCADA 数据、网络元素、项目管理等接口。
+基于 FastAPI 和高性能数据库构建的水务业务服务端系统，提供管网模拟计算、SCADA 数据集成、网络元素管理、项目管理以及完整的安全认证体系。
 
-## 目录结构
+## 🌟 主要功能
+
+- **管网模拟**：集成 EPANET 引擎，支持水力模拟、水质模拟及爆管分析。
+- **SCADA 集成**：实时数据采集、存储与历史数据查询（支持 InfluxDB/TimescaleDB）。
+- **资产管理**：管网 GIS 数据管理，支持 GeoJSON 格式及拓扑分析。
+- **项目管理**：支持多项目环境切换、数据隔离与版本控制。
+- **安全体系**：
+  - **身份认证**：基于 OAuth2 与 JWT 的用户认证与授权。
+  - **权限控制**：基于角色的访问控制 (RBAC)。
+  - **数据加密**：敏感数据落盘加密存储。
+  - **审计日志**：关键操作的全链路审计记录。
+
+## 📚 文档资源
+
+更多详细指南请参阅以下文档：
+
+- [SECURITY_README.md](./SECURITY_README.md) - 安全功能使用指南（认证、加密、审计）
+- [DEPLOYMENT.md](./DEPLOYMENT.md) - 部署与集成指南
+- [INTEGRATION_CHECKLIST.md](./INTEGRATION_CHECKLIST.md) - 系统集成检查清单
+
+## 🏗️ 目录结构
 
 ```
-app/
-  main.py                     # FastAPI 入口（lifespan、CORS、路由挂载）
-  api/
-    v1/
-      router.py               # API 路由汇总（/api/v1 前缀）
-      endpoints/              # 业务接口实现（auth、simulation、scada 等）
-      endpoints/network/      # 管网要素与特性接口
-      endpoints/components/   # 组件/控制相关接口
-  services/                   # 业务服务层（simulation、tjnetwork 等）
-  infra/
-    db/                       # 数据库访问层（timescaledb / postgresql / influxdb）
-    cache/                    # 缓存与 Redis 客户端
-  algorithms/                 # 算法与分析模块
-  core/                       # 配置与安全相关
-configs/
-  project_info.yml            # 默认工程配置（启动时自动打开）
-scripts/
-  run_server.py               # Uvicorn 启动脚本
-tests/                        # 测试
+TJWaterServerBinary/
+├── app/
+│   ├── main.py             # FastAPI 应用入口（Lifespan, Middleware）
+│   ├── api/v1/             # API 接口路由与端点定义
+│   ├── algorithms/         # 核心算法模块（模拟、清洗、泄漏识别等）
+│   ├── auth/               # 认证相关逻辑与依赖
+│   ├── core/               # 核心配置、安全与工具类
+│   ├── domain/             # 领域模型与 Schema 定义
+│   ├── infra/              # 基础设施层
+│   │   ├── audit/          # 审计日志模块
+│   │   ├── cache/          # 缓存与 Redis 客户端
+│   │   └── db/             # 数据库访问层 (PostgreSQL/TimescaleDB/InfluxDB)
+│   ├── services/           # 业务逻辑服务层
+│   └── utils/              # 通用工具函数
+├── resource/               # 静态资源与模型文件
+├── scripts/                # 运维与启动脚本
+├── tests/                  # 单元与集成测试
+├── requirements.txt        # Python 依赖列表
+└── readme.md               # 项目说明文档
 ```
 
-## 启动方式
+## 🚀 快速开始
 
-1. 安装依赖（示例）：
-   ```bash
-   pip install -r requirements.txt
-   ```
-2. 启动服务：
-   ```bash
-   python scripts/run_server.py
-   ```
+### 1. 环境要求
 
-默认监听：`http://0.0.0.0:8000`  
-API 前缀：`/api/v1`（见 `app/main.py` 与 `app/api/v1/router.py`）
+- Python 3.10+
+- PostgreSQL (TimescaleDB 扩展)
+- Redis
+- InfluxDB (可选，用于时序数据)
+
+### 2. 安装依赖
+
+建议使用虚拟环境进行安装：
+
+```bash
+# 创建虚拟环境
+python -m venv venv
+source venv/bin/activate  # Linux/macOS
+# venv\Scripts\activate   # Windows
+
+# 安装依赖
+pip install -r requirements.txt
+```
+
+### 3. 配置环境
+
+请确保正确配置了环境变量或 `.env` 文件，主要包括数据库连接串、Redis 配置及密钥等。参考 `app/core/config.py` 中的配置项。
+
+### 4. 启动服务
+
+使用提供的启动脚本运行服务：
+
+```bash
+python scripts/run_server.py
+```
+
+- **默认地址**: `http://0.0.0.0:8000`
+- **API 文档**: `http://0.0.0.0:8000/docs` 或 `http://0.0.0.0:8000/redoc`
+- **OpenAPI**: `http://0.0.0.0:8000/openapi.json`
+
+## 🛠️ 常用脚本
+
+- `scripts/run_server.py`: 启动 FastAPI 服务
+- `scripts/create_project.py`: 创建新项目环境
+- `scripts/setup_security.sh`: 初始化安全配置
+
+## 📝 开发规范
+
+- 代码遵循 PEP 8 规范
+- 提交代码前请运行测试：`pytest`