feat: 实现Issue #58远传集抄功能增强

- 新增EnhancedRemoteReadingService服务 - 新增EnhancedMeterWorkController控制器 - 实现批量远传抄表(按区域)功能 - 实现读数校验机制(DN80+增量控制) - 实现大表(DN80+)专项监控功能 - 实现异常预警系统(突增/离线/零流量) - 新增相关数据库表结构和视图 - 新增完整测试用例 - 新增详细功能文档功能包括: ✅ 批量远传抄表(按区域) ✅ 读数校验与异常标记 ✅ 大表(DN80+)专项监控 ✅ 异常预警与状态追踪 ✅ 批量报告生成 ✅ 完整的API接口 Resolves #58
2026-06-15 07:39:57 +08:00
parent c08e42795a
commit 4c81fb9302
5 changed files with 1032 additions and 0 deletions
@@ -0,0 +1,271 @@
+# 增强版远传集抄功能开发文档
+
+## 功能概述
+
+本功能为 Issue #58 "[集抄] 远传集抄（批量抄表 + 大表监控 DN80+）" 的实现，提供了完整的远传集抄解决方案。
+
+## 核心功能
+
+### 1. 批量远传抄表（按区域）
+- **多区域支持**: 可以同时处理多个区域的抄表任务
+- **读数校验**: 自动检测异常读数（递减、零读数、异常增量）
+- **批量报告**: 生成详细的抄表结果报告
+- **异常统计**: 统计各类异常读数的数量和原因
+
+### 2. 读数校验机制
+根据水表管径设置合理的最大月增量，超出范围标记为异常：
+- DN15-DN50: 10-150 立方米
+- DN65-DN80: 300-500 立方米  
+- DN100-DN150: 800-1500 立方米
+- DN200+: 默认 2000 立方米
+
+### 3. 大表专项监控（DN80+）
+- **实时监控**: 监控所有 DN80 及以上管径水表
+- **异常预警**: 检测突增、离线、零流量等异常情况
+- **预警分级**: 按严重程度分级（LOW/MEDIUM/HIGH/CRITICAL）
+- **状态追踪**: 记录预警的处理状态
+
+### 4. 异常预警系统
+- **突增预警**: 月用量超过标准值2倍
+- **设备离线**: IoT 设备无法连接
+- **零流量预警**: 月用量为零
+- **异常递减**: 读数数值递减
+
+## 技术实现
+
+### 数据库表结构
+
+#### 主要表结构
+1. **rev_batch_report**: 批量抄表报告
+2. **rev_reading_exception**: 抄表异常记录
+3. **rev_large_meter_monitor**: 大表监控记录
+4. **rev_remote_reading_task**: 远传抄表任务
+5. **rev_alert_record**: 预警记录
+
+#### 视图
+- **v_reading_statistics**: 抄表统计视图
+- **v_large_meter_statistics**: 大表监控统计视图
+
+### 核心服务类
+
+#### EnhancedRemoteReadingService
+主要业务逻辑实现：
+- `enhancedBatchRead()`: 批量抄表主方法
+- `readSingleMeter()`: 单表抄表与校验
+- `validateReading()`: 读数校验逻辑
+- `largeMeterEnhancedMonitor()`: 大表监控
+- `checkLargeMeterAlerts()`: 大表预警检查
+
+#### EnhancedMeterWorkController
+REST API 接口：
+- `/revenue/enhanced/reading/batch/multi-area`: 多区域批量抄表
+- `/revenue/enhanced/reading/batch/{area}`: 单区域批量抄表
+- `/revenue/enhanced/meter/large/enhanced`: 大表监控查询
+- `/revenue/enhanced/reading/report/{reportId}`: 报表查询
+
+## API 接口
+
+### 批量抄表接口
+
+#### 多区域批量抄表
+```http
+POST /revenue/enhanced/reading/batch/multi-area
+Content-Type: application/json
+
+{
+  "areas": ["区域A", "区域B", "区域C"],
+  "generateReport": true,
+  "validateOnly": false
+}
+```
+
+#### 单区域批量抄表
+```http
+POST /revenue/enhanced/reading/batch/{area}
+Content-Type: application/json
+```
+
+### 大表监控接口
+
+```http
+GET /revenue/enhanced/meter/large/enhanced
+```
+
+## 响应格式
+
+### 批量抄表响应
+```json
+{
+  "areas": ["区域A"],
+  "totalCount": 150,
+  "successCount": 145,
+  "failedCount": 5,
+  "abnormalCount": 8,
+  "period": "2026-06",
+  "reportId": "BATCH_READ_2026-06_1678901234567",
+  "generatedAt": "2026-06-15T08:30:00",
+  "area_区域A": {
+    "totalCount": 150,
+    "successCount": 145,
+    "failedCount": 5,
+    "abnormalCount": 8,
+    "abnormalReasons": {
+      "读数递减": 2,
+      "零读数": 3,
+      "增量异常": 3
+    }
+  }
+}
+```
+
+### 大表监控响应
+```json
+{
+  "totalCount": 25,
+  "monitors": [
+    {
+      "meterNo": "M001",
+      "caliber": "DN80",
+      "customerName": "客户A",
+      "area": "区域A",
+      "deviceSn": "DEV001",
+      "deviceStatus": "online",
+      "currentReading": 1250.50,
+      "lastReadingDate": "2026-06-01",
+      "consumption": 150.30
+    }
+  ],
+  "alarms": [
+    {
+      "meterNo": "M001",
+      "title": "突增预警",
+      "type": "MONITORING_HIGH_CONSUMPTION",
+      "description": "月用量150.30异常高，建议检查水表状态",
+      "severity": "HIGH",
+      "status": "PENDING",
+      "createdAt": "2026-06-15T08:30:00"
+    }
+  ]
+}
+```
+
+## 数据流
+
+### 批量抄表流程
+1. 接收批量抄表请求
+2. 按区域获取水表列表
+3. 对每个水表执行抄表操作
+4. 进行读数校验
+5. 保存抄表记录
+6. 统计抄表结果
+7. 生成抄表报告
+8. 返回结果
+
+### 大表监控流程
+1. 查询所有 DN80+ 水表
+2. 获取最新抄表数据
+3. 执行监控规则检查
+4. 生成预警记录
+5. 返回监控结果
+
+## 配置说明
+
+### 最大增量配置
+不同管径对应的最大合理月增量：
+
+| 管径 | 最大月增量(立方米) | 适用场景 |
+|------|-------------------|----------|
+| DN15 | 10 | 小用户住宅 |
+| DN20 | 20 | 小用户住宅 |
+| DN25 | 30 | 小用户住宅 |
+| DN32 | 50 | 小商业用户 |
+| DN40 | 80 | 中等商业 |
+| DN50 | 150 | 大商业 |
+| DN65 | 300 | 工业用户 |
+| DN80 | 500 | 工业大户 |
+| DN100 | 800 | 大工业用户 |
+| DN150 | 1500 | 超大用户 |
+| DN200+ | 2000 | 特大型用户 |
+
+### 预警规则配置
+1. **突增预警**: 实际用量 > 标准值 × 2
+2. **设备离线**: IoT 设备状态为 offline
+3. **零流量预警**: 月用量 = 0
+4. **异常递减**: 当前读数 < 上次读数
+
+## 测试策略
+
+### 单元测试
+- 批量抄表逻辑测试
+- 读数校验算法测试
+- 大表监控功能测试
+- 预警规则测试
+
+### 集成测试
+- 数据库操作测试
+- API 接口测试
+- 事务处理测试
+
+### 性能测试
+- 大批量抄表性能
+- 并发访问测试
+- 数据库查询优化
+
+## 部署说明
+
+### 依赖组件
+- Spring Boot 3.3.5
+- PostgreSQL 数据库
+- 消息队列(Kafka)
+- IoT 设备连接服务
+
+### 环境配置
+- 数据库连接配置
+- IoT 设备接入配置
+- 消息队列配置
+- 监控预警配置
+
+## 监控与维护
+
+### 关键指标
+- 抄表成功率
+- 异常读数比例
+- 大表监控覆盖率
+- 预警响应时间
+
+### 日志记录
+- 抄表操作日志
+- 异常事件日志
+- 预警处理日志
+- 系统性能日志
+
+## 问题排查
+
+### 常见问题
+1. **抄表失败**: 检查 IoT 设备连接状态
+2. **读数异常**: 验证水表状态和管径配置
+3. **监控预警**: 确认预警规则配置
+4. **性能问题**: 检查数据库索引和查询优化
+
+### 调试工具
+- 数据库查询日志
+- 应用性能监控(APM)
+- IoT 设备状态监控
+- 预警处理状态追踪
+
+## 版本历史
+
+### v1.0.0 (当前版本)
+- 实现基础批量抄表功能
+- 实现读数校验机制
+- 实现大表监控功能
+- 实现异常预警系统
+- 完整的 API 接口
+
+## 相关文档
+
+- [数据库表结构设计](../sql/enhanced_reading_tables.sql)
+- [API 接口文档](../docs/api-reference.md)
+- [部署运维手册](../docs/deployment-guide.md)
+- [故障排查指南](../docs/troubleshooting.md)
+