TJWaterServerBinary/readme.md

TJWater Server (FastAPI)

基于 FastAPI 和高性能数据库构建的水务业务服务端系统，提供管网模拟计算、SCADA 数据集成、网络元素管理、项目管理以及完整的安全认证体系。

🌟 主要功能

• 管网模拟：集成 EPANET 引擎，支持水力模拟、水质模拟及爆管分析。
• SCADA 集成：实时数据采集、存储与历史数据查询（支持 InfluxDB/TimescaleDB）。
• 资产管理：管网 GIS 数据管理，支持 GeoJSON 格式及拓扑分析。
• 项目管理：支持多项目环境切换、数据隔离与版本控制。
• 安全体系：
  • 身份认证：基于 OAuth2 与 JWT 的用户认证与授权。
  • 权限控制：基于角色的访问控制 (RBAC)。
  • 数据加密：敏感数据落盘加密存储。
  • 审计日志：关键操作的全链路审计记录。

📚 文档资源

更多详细指南请参阅以下文档：

• SECURITY_README.md - 安全功能使用指南（认证、加密、审计）
• DEPLOYMENT.md - 部署与集成指南
• INTEGRATION_CHECKLIST.md - 系统集成检查清单

🏗️ 目录结构

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. 环境要求

• Python 3.10+
• PostgreSQL (TimescaleDB 扩展)
• Redis
• InfluxDB (可选，用于时序数据)

2. 安装依赖

建议使用虚拟环境进行安装：

# 创建虚拟环境
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. 启动服务

使用提供的启动脚本运行服务：

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