water-management-system/docs/enhanced-remote-reading-feature.md

# 增强版远传集抄功能开发文档

## 功能概述

本功能为 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)