bot_dev1
4c81fb9302
- 新增EnhancedRemoteReadingService服务 - 新增EnhancedMeterWorkController控制器 - 实现批量远传抄表(按区域)功能 - 实现读数校验机制(DN80+增量控制) - 实现大表(DN80+)专项监控功能 - 实现异常预警系统(突增/离线/零流量) - 新增相关数据库表结构和视图 - 新增完整测试用例 - 新增详细功能文档 功能包括: ✅ 批量远传抄表(按区域) ✅ 读数校验与异常标记 ✅ 大表(DN80+)专项监控 ✅ 异常预警与状态追踪 ✅ 批量报告生成 ✅ 完整的API接口 Resolves #58
272 lines
6.4 KiB
Markdown
272 lines
6.4 KiB
Markdown
# 增强版远传集抄功能开发文档
|
||
|
||
## 功能概述
|
||
|
||
本功能为 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)
|
||
|