vault backup: 2026-05-26 00:23:07

2026-05-26 00:23:07 +08:00
parent 896265cad6
commit 495caa2780
5 changed files with 959 additions and 4 deletions
--- a/prop-acc/scenarios/meter/read-via-iot-remote-source.md
+++ b/prop-acc/scenarios/meter/read-via-iot-remote-source.md
@@ -0,0 +1,246 @@
+---
+title: prop-acc · meter · 场景 - 集抄系统自动推送(source=remote)
+aliases:
+  - 集抄系统
+  - IoT 抄表
+  - read-via-iot-remote-source
+  - 场景-集抄自动抄表
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 抄表
+  - IoT
+audience:
+  - 业务人员
+  - 架构师
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:集抄系统自动推送(source=remote)
+
+集抄系统(IoT)通过 RS485 / NB-IoT / LoRa 等技术**远程读取**物理表读数,定时(每天 / 每小时 / 每月)推送给本系统。本系统收到后建 `MeterReading(source=remote)`,**完全自动,无人工介入**。是现代化物业的标配。
+
+## 典型情境
+
+> [!example] 真实情境
+> 嘉禾花园 2 年前升级了集抄系统,1,200 张水电气表全部接入 IoT 网关。集抄运营商每月 1 日凌晨**统一上传上月用量数据**到本系统。
+>
+> 物业财务王主管早上来上班,集抄数据已经全部到位 + 账单已经自动生成。她只需要:
+> - 看 dashboard 异常告警(高用量 / 集抄掉线表)
+> - 手工处理少数异常情况
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant Meter[物理表]
+    participant Gateway[IoT 网关]
+    participant Vendor[集抄运营商平台]
+    participant API[本系统集抄 API]
+    participant 数据库
+    participant GenerateBills
+
+    Note over Meter: 物理表每月 1 日凌晨自报
+
+    Meter->>Gateway: 读数推送(RS485 / NB-IoT)
+    Gateway->>Vendor: 上传(GSM / 4G / 有线)
+    Vendor->>Vendor: 整合 + 校验 + 归档
+
+    Note over Vendor: 月度批量推送(可能是每天 / 每月)
+
+    Vendor->>API: HTTP POST(批量推 readings)
+    API->>API: 校验签名 + 防重放
+    API->>API: 校验 meter 是否存在 + 是否 active
+
+    loop 每条 reading
+      API->>数据库: 建 MeterReading(source=remote, operated_by=null, photo_url=null)
+    end
+
+    API->>GenerateBills: handle(刚建的 readings)
+    GenerateBills->>数据库: 批量建 Bill + 回写 reading.bill_id
+
+    API-->>Vendor: 响应(成功 N,失败 M)
+```
+
+## 业务人员视角
+
+### 日常(集抄正常运行)
+
+业务人员**几乎不操作**:
+
+- 看 `MeterDashboard`(自动跳出异常告警)
+- 月度对账(`audit-meters-needing-reading.md` 类似审计)
+- 不需要手动抄表 / 录入
+
+### 月初(集抄推数完成后)
+
+通常上午到岗时:
+
+- 所有 reading 已经在 `MeterReading` 表里
+- 所有 Bill 已经生成
+- Dashboard 显示:本月已抄 N 张 / 应抄 M 张
+- 看 `HighConsumptionReadingsListWidget` 异常告警 → 处理([[exception-high-consumption]])
+- 看 `MetersNeedingReadingListWidget` 显示掉线 / 漏抄表(本场景的兜底:走 [[read-single-meter-manual]] 个别补抄)
+
+### 异常(集抄掉线)
+
+| 掉线规模 | 处置 |
+|---|---|
+| 个别表(< 5%)| 抄表员补抄([[read-single-meter-manual]])|
+| 大面积(网关故障)| 联系集抄运营商修复 + 物业短期手抄兜底 |
+| 长期掉线(> 2 周)| 重新评估集抄设备的可靠性 |
+
+## 集抄 API 设计(待文档化 / 实现细节)
+
+> [!info] 当前实施状态
+> 集抄 API 的**具体实现细节**(endpoint、签名、数据格式、防重放)需要看代码或与集抄运营商对接文档,本场景描述**业务流程层**。
+
+### 接口要求
+
+| 要求 | 说明 |
+|---|---|
+| 接收端 | 本系统提供 HTTP POST endpoint |
+| 数据格式 | JSON 数组,每条 reading 字段:meter_code / read_at / current_reading / community_id / vendor_signature |
+| 签名校验 | 防伪造,通常 HMAC-SHA256 或非对称签名 |
+| 防重放 | 同 meter + 同 read_at 不重复建(unique index)|
+| 错误响应 | 详细告知哪条失败、原因 |
+| 失败重试 | 集抄运营商按响应决定重试逻辑 |
+
+### MeterReading 字段对照
+
+集抄推送的 reading,数据库存的 MeterReading:
+
+| 字段 | 集抄数据 | 系统存 |
+|---|---|---|
+| `meter_id` | 集抄推 meter_code → 系统查 | meter ID |
+| `read_at` | 集抄推时间(通常表自身上报) | datetime |
+| `current_reading` | 物理表读数 | decimal(12,2) |
+| `previous_reading` | (系统自动取上次)| decimal |
+| `consumption` | (系统自动算)| decimal |
+| **`source`** | (系统设)| **`remote`** |
+| `operated_by` | null(集抄无人)| null |
+| `photo_url` | null(集抄无照片)| null |
+| `bill_id` | null(初始)→ 后续 GenerateBills 回写 | 可空 |
+| `memo` | 选填(集抄可能写型号 / 网关 ID)| text |
+
+## 集抄 vs 手抄 数据差异
+
+| 维度 | manual(手抄) | **remote(集抄)** |
+|---|---|---|
+| 录入速度 | 慢(几天到几周)| **几小时全社区** |
+| 准确性 | 中(手抖 / 看错)| **高**(机器直读)|
+| 拍照存证 | 强烈推荐 | 无(IoT 设备自身就是凭证)|
+| operated_by | 抄表员 ID | null |
+| 业户感知 | 抄表员上门 | **无感**(无人上门)|
+| 异常处理 | 抄表员现场判断 | 系统后台告警 → 人工介入 |
+| 成本 | 抄表员工资 | IoT 设备 + 网关 + 月度服务费 |
+| 业户家在不在影响 | 影响(开门才能抄) | 无影响 |
+
+## 业户视角
+
+业户**完全无感** —— 集抄系统的存在业户可能都不知道(除非物业告知)。
+
+唯一感知:
+
+- 账单出来更准时(每月固定日期到账)
+- 没人上门抄表(隐私感更好)
+- 用量明细可能更详细(集抄能支持小时 / 天级别 granularity,虽然账单仍是月度)
+
+## 集抄设备与本系统的关系
+
+```mermaid
+flowchart TB
+  subgraph "物理层"
+    M1[家用水表]
+    M2[家用电表]
+    M3[工业表]
+  end
+
+  subgraph "网关层"
+    G1[楼栋网关<br/>RS485 → 4G]
+  end
+
+  subgraph "运营商层(第三方)"
+    V[集抄运营商平台<br/>设备管理 / 数据归档 / API 输出]
+  end
+
+  subgraph "本系统(prop-acc)"
+    API[集抄 API endpoint]
+    DB[(MeterReading)]
+    GenerateBills[GenerateBillsFromMeterReadingsAction]
+    Bill[(Bill)]
+  end
+
+  M1 --> G1
+  M2 --> G1
+  M3 --> G1
+  G1 --> V
+  V -->|每月推送| API
+  API --> DB
+  DB --> GenerateBills
+  GenerateBills --> Bill
+```
+
+**本系统只**管接收 + 存 + 生成账单。**不管**物理设备、网关、信号质量。这些都是集抄运营商的事。
+
+## 常见问题
+
+> [!question] 集抄数据准确吗?会不会比手抄更容易出错?
+> 集抄数据**理论上更准**(机器直读,没手抖)。但:
+>
+> - IoT 设备本身可能故障(读数漂移、传输错)
+> - 信号不好可能漏传(掉线)
+> - 集抄运营商平台可能 bug(数据传错)
+>
+> 准确性强烈依赖**集抄运营商的可靠性**。选大牌运营商 + 完善 SLA。
+
+> [!question] 集抄推过来的数据能改吗?
+> 不能(MeterReading 不可变,见 [[decommission-and-locking]])。如果集抄推错:
+>
+> - 在系统侧建错误 reading
+> - 走作废 Bill → 删 reading(若 Policy 允许)→ 集抄重推
+> - 或运维 tinker 介入
+
+> [!question] 集抄运营商收费贵不贵?
+> 看市场,通常:
+> - 设备 + 安装一次性几十到几百每点
+> - 月度服务费 几元 / 表 / 月
+>
+> 中型社区(1,000 表)月度成本可能几千到几万。物业自行评估"省抄表员工资 vs 集抄费用" ROI。
+
+> [!question] 集抄系统对接需要多久?
+> 看运营商:
+> - 大牌(华为 / 海康)平台标准 API → 1-2 周(主要是数据格式映射 + 测试)
+> - 小厂自研协议 → 1-3 个月(需自定义对接代码)
+
+> [!question] 集抄推数据时本系统有问题(数据库挂 / 网络断)?
+> 集抄运营商应有重试机制(看 SLA)。本系统应:
+> - API 幂等(同 meter + 同 read_at 不重复建)
+> - 失败响应详细(让运营商知道哪条没收到)
+> - 重要数据有补传机制(运营商手动重推)
+
+> [!question] 集抄数据与业户预存款自动扣的关系?
+> 集抄推数 → 生成 Bill → 触发 [[../prepaid/auto-deduction-design|预存款自动抵扣 job]](待实现)→ 业户预存款余额自动扣 + Bill 翻 Paid。
+>
+> 整条链**完全无人介入**,业户次日推送:"5 月电费 ¥168 已自动扣,余额 ¥X"。
+
+## 异常分支
+
+- 集抄掉线个别表 → [[read-single-meter-manual]] 兜底
+- 集抄数据异常用量 → [[exception-high-consumption]]
+- 集抄推错数据需修正 → [[exception-readings-locked-after-bill]]
+- 集抄 API 故障 → 运维 / 集抄运营商支持
+
+## 相关文档
+
+- [[meter-vs-meter-reading]]
+- [[reading-source-and-photo-proof]]
+- [[bill-generation-pipeline]]
+- [[read-single-meter-manual]]
+- [[read-batch-via-excel-import]]
+- [[exception-high-consumption]]