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

## 版本信息
- **版本**: 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)
```sql
- id: 主键
- station_name: 站点名称
- location: 地理位置
- station_type: 站点类型（WQ-01, WQ-02, WQ-03等）
- description: 描述信息
- is_active: 是否活跃
- created_at/updated_at: 时间戳
```

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

#### 工艺参数表 (process_parameter)
```sql
- 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)
```sql
- 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统一返回格式：
```json
{
  "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

---

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