water-management-system/docs/design-spec.md

供水生产管理平台设计规格

版本信息

• 版本: 1.1.0
• 更新日期: 2026-06-15
• 更新内容: 修复PM退回问题，补充单元测试和完整业务逻辑实现

1. 项目架构

1.1 技术栈

• 框架: Spring Boot 3.2.0
• 数据库: PostgreSQL 16 + H2 (测试)
• ORM: Spring Data JPA
• 安全: Spring Security
• 文档: SpringDoc OpenAPI
• 监控: Actuator + Prometheus
• 任务调度: Quartz

1.2 模块结构

src/main/java/com/waterquality/
├── controller/          # REST API 控制器层
├── service/           # 业务逻辑服务层
├── repository/        # 数据访问层
├── entity/            # JPA 实体类
├── dto/               # 数据传输对象
└── WaterQualityApplication.java  # 主应用类

2. 核心功能模块

2.1 水质管控模块

2.1.1 站点管理

• 实体: WaterQualityStation
• 功能: 管理所有水质监测站点
• 接口:
  • 创建/更新/删除站点
  • 查询活跃站点
  • 按类型筛选站点
  • 按位置搜索站点

2.1.2 药剂投加管理

• 实体: ChemicalDosing
• 功能: 管理絮凝剂、消毒剂等药剂投加记录
• 接口:
  • 创建投加记录
  • 查询站点药剂投加记录
  • 按药剂类型查询
  • 按时间范围查询

2.1.3 工艺监控

• 实体: ProcessParameter
• 功能: 监控关键工艺参数
• 接口:
  • 记录工艺参数
  • 自动计算参数状态（NORMAL/WARNING/ALARM）
  • 查询参数报警阈值
  • 历史数据查询

2.2 报警管理中心

2.2.1 报警管理

• 实体: Alarm
• 功能: 管理水质报警的全生命周期
• 接口:
  • 创建报警
  • 确认报警
  • 解决报警
  • 按状态/级别查询
  • 未确认/未解决报警查询

2.2.2 报警状态流转

ACTIVE → ACKNOWLEDGED → RESOLVED

3. 数据库设计

3.1 核心表结构

水质监测站点表 (water_quality_station)

- id: 主键
- station_name: 站点名称
- location: 地理位置
- station_type: 站点类型（WQ-01, WQ-02, WQ-03等）
- description: 描述信息
- is_active: 是否活跃
- created_at/updated_at: 时间戳

药剂投加记录表 (chemical_dosing)

- id: 主键
- station_id: 关联站点ID
- chemical_type: 药剂类型
- dosage: 投加量
- unit: 单位
- dosing_time: 投加时间
- operator: 操作员
- notes: 备注
- is_active: 是否活跃
- created_at/updated_at: 时间戳

工艺参数表 (process_parameter)

- id: 主键
- station_id: 关联站点ID
- parameter_type: 参数类型
- value: 参数值
- unit: 单位
- upper_limit: 上限
- lower_limit: 下限
- alarm_threshold: 报警阈值
- status: 状态（NORMAL/WARNING/ALARM）
- measurement_time: 测量时间
- created_at/updated_at: 时间戳

报警记录表 (water_quality_alarm)

- id: 主键
- station_id: 关联站点ID
- alarm_type: 报警类型
- alarm_level: 报警级别
- alarm_message: 报警消息
- alarm_time: 报警时间
- acknowledge_time: 确认时间
- resolve_time: 解决时间
- status: 状态（ACTIVE/ACKNOWLEDGED/RESOLVED）
- operator: 操作员
- acknowledge_notes: 确认备注
- resolve_notes: 解决备注
- created_at/updated_at: 时间戳

3.2 索引策略

• 所有外键建立索引
• 常用查询字段建立索引
• 时间相关字段建立索引
• 状态字段建立索引

4. API 设计

4.1 响应格式

所有API统一返回格式：

{
  "success": true,
  "message": "操作成功",
  "data": {},
  "timestamp": 1678901234567
}

4.2 分页规范

• 使用 Page<T> 对象处理分页
• 默认页码：1
• 默认页大小：20
• 最大页大小：100

4.3 错误处理

• 全局异常处理器
• 参数校验失败统一处理
• 数据库异常统一处理
• 业务异常统一处理

5. 安全设计

5.1 认证授权

• JWT Token 认证
• 角色基础访问控制
• 方法级安全注解

5.2 数据安全

• 敏感字段加密
• SQL注入防护
• XSS攻击防护
• CSRF防护

6. 性能优化

6.1 数据库优化

• 连接池配置
• 批量操作优化
• 查询优化
• 索引优化

6.2 缓存策略

• Redis 热点数据缓存
• 查询结果缓存
• 会话缓存

6.3 异步处理

• 异步任务处理
• 消息队列处理
• 定时任务处理

7. 监控与运维

7.1 应用监控

• 健康检查
• 性能监控
• 日志监控
• 告警机制

7.2 数据库监控

• 连接池监控
• 查询性能监控
• 锁等待监控
• 空间使用监控

8. 测试策略

8.1 单元测试

• JUnit 5
• Mockito
• 覆盖率要求：80%+

8.2 集成测试

• Spring Boot Test
• 数据库测试
• API测试

8.3 端到端测试

• 完整业务流程测试
• 异常场景测试
• 性能测试

9. 部署方案

9.1 容器化部署

• Docker
• Docker Compose
• Kubernetes

9.2 环境配置

• 开发环境
• 测试环境
• 生产环境

9.3 配置管理

• 环境变量
• 配置文件
• 配置中心

10. 后续迭代计划

10.1 短期计划（1-2周）

• 完善前端界面
• 添加报表功能
• 集成消息通知
• 添加数据导入导出

10.2 中期计划（1-3个月）

• 移动端适配
• 大屏展示
• 数据分析功能
• AI 水质预测

10.3 长期计划（3-6个月）

• 微服务架构重构
• 多租户支持
• 国际化支持
• 第三方系统集成

11. 代码规范

11.1 编码规范

• 遵循 Google Java Style
• 使用 Lombok 减少样板代码
• 合理使用设计模式

11.2 文档规范

• 详细的API文档
• 代码注释规范
• README 文档

11.3 版本控制

• Git Flow 工作流
• 代码审查机制
• 持续集成

12. 依赖管理

12.1 核心依赖

• Spring Boot 3.2.0
• Spring Data JPA
• PostgreSQL Driver
• Lombok
• MapStruct

12.2 测试依赖

• JUnit 5
• Mockito
• Spring Boot Test

12.3 工具依赖

• Flyway
• Maven Compiler Plugin
• Surefire Plugin

---

注意: 本文档随着项目开发持续更新，请确保查看最新版本。