更新readme文档
This commit is contained in:
@@ -1,41 +1,97 @@
|
|||||||
# TJWater Server (FastAPI)
|
# 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/
|
TJWaterServerBinary/
|
||||||
main.py # FastAPI 入口（lifespan、CORS、路由挂载）
|
├── app/
|
||||||
api/
|
│ ├── main.py # FastAPI 应用入口（Lifespan, Middleware）
|
||||||
v1/
|
│ ├── api/v1/ # API 接口路由与端点定义
|
||||||
router.py # API 路由汇总（/api/v1 前缀）
|
│ ├── algorithms/ # 核心算法模块（模拟、清洗、泄漏识别等）
|
||||||
endpoints/ # 业务接口实现（auth、simulation、scada 等）
|
│ ├── auth/ # 认证相关逻辑与依赖
|
||||||
endpoints/network/ # 管网要素与特性接口
|
│ ├── core/ # 核心配置、安全与工具类
|
||||||
endpoints/components/ # 组件/控制相关接口
|
│ ├── domain/ # 领域模型与 Schema 定义
|
||||||
services/ # 业务服务层（simulation、tjnetwork 等）
|
│ ├── infra/ # 基础设施层
|
||||||
infra/
|
│ │ ├── audit/ # 审计日志模块
|
||||||
db/ # 数据库访问层（timescaledb / postgresql / influxdb）
|
│ │ ├── cache/ # 缓存与 Redis 客户端
|
||||||
cache/ # 缓存与 Redis 客户端
|
│ │ └── db/ # 数据库访问层 (PostgreSQL/TimescaleDB/InfluxDB)
|
||||||
algorithms/ # 算法与分析模块
|
│ ├── services/ # 业务逻辑服务层
|
||||||
core/ # 配置与安全相关
|
│ └── utils/ # 通用工具函数
|
||||||
configs/
|
├── resource/ # 静态资源与模型文件
|
||||||
project_info.yml # 默认工程配置（启动时自动打开）
|
├── scripts/ # 运维与启动脚本
|
||||||
scripts/
|
├── tests/ # 单元与集成测试
|
||||||
run_server.py # Uvicorn 启动脚本
|
├── requirements.txt # Python 依赖列表
|
||||||
tests/ # 测试
|
└── readme.md # 项目说明文档
|
||||||
```
|
```
|
||||||
|
|
||||||
## 启动方式
|
## 🚀 快速开始
|
||||||
|
|
||||||
1. 安装依赖（示例）：
|
### 1. 环境要求
|
||||||
```bash
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
2. 启动服务：
|
|
||||||
```bash
|
|
||||||
python scripts/run_server.py
|
|
||||||
```
|
|
||||||
|
|
||||||
默认监听：`http://0.0.0.0:8000`
|
- Python 3.10+
|
||||||
API 前缀：`/api/v1`（见 `app/main.py` 与 `app/api/v1/router.py`）
|
- 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`
|
||||||
|
|||||||
Reference in New Issue
Block a user