docs(iot): 建设设备接入、物模型及联动策略主干规范

2026-04-06 23:01:39 +08:00
parent dec2b06d74
commit 4337a5e3f1
4 changed files with 178 additions and 6 deletions
--- a/开发者文档/03-IoT领域/00-IoT领域总览.md
+++ b/开发者文档/03-IoT领域/00-IoT领域总览.md
@@ -1,8 +1,32 @@
-# IoT领域总览
+# 00-IoT领域总览

-## 目标与面向读者
-下一阶段的核心业务，聚焦于物联网设备的接入、控制与数据分析。
+本文档是 AIOT 平台 IoT（物联网）领域的核心入口。
+当前阶段，研发重心正从 Ops（人工作业）向 IoT（设备物联）全面转移。

-## 核心模块
- **设备接入层**：待补充协议（MQTT/HTTP等）说明。
- **物模型设计**：待补充设备属性、事件、服务定义。
+## 一、当前建设重心
+
+IoT 领域不再是停留在 PPT 上的规划，而是当前正在落地的战场。我们必须解决三个核心问题：
+1. **设备怎么连上来**：设备注册、认证、保活心跳、MQTT 报文解析。
+2. **数据长什么样**：定义统一的“物模型”，让后端业务逻辑不需要去管设备底层是透传的 Hex 还是非标的 JSON。
+3. **数据怎么用**：如何将冷冰冰的设备遥测数据，通过规则引擎转化为业务系统（Ops）关心的“告警事件”并触发工单。
+
+## 二、架构解耦原则（铁律）
+
+在阅读和编写下属文档时，必须时刻牢记：**“南向屏蔽，北向统一”**。
+
+- **南向（面向设备）**：允许混乱。允许存在 MQTT、HTTP、TCP 各种协议；允许 payload 千奇百怪。
+- **北向（面向业务）**：必须干净。所有向 Ops 抛出的事件、所有存储到数据库的属性，必须是经过「物模型」标准转换后的统一格式。
+- **绝对禁止**：在工单、保洁等业务 Service 里直接引入诸如 `MqttClient`，或者直接去 parse 设备的原始报文。
+
+## 三、核心文档阅读指引
+
+请按顺序阅读以下标准设计：
+
+1. **[[01-设备接入与控制主链路.md]]**
+   - 关注网络层和会话层。定义了设备从开机到上线、数据上报和接收指令的全过程（Mermaid 时序图）。
+2. **[[02-物模型标准设计.md]]**
+   - 关注数据表示层。定义了“属性（Property）”、“事件（Event）”和“服务（Service）”的三要素规范，以及设备影子的机制。
+3. **[[03-规则引擎与联动策略.md]]**
+   - 关注业务逻辑层。说明了大量传感器数据如何经过防抖、过滤，最终安全地跨域调用 Ops 接口生成维修/应急工单。
+
+> ⚠️ 注意：本目录下的规范即代表开发契约，开发进行代码结构设计和数据库表设计时，必须与之对齐。
--- a/开发者文档/03-IoT领域/01-设备接入与控制主链路.md
+++ b/开发者文档/03-IoT领域/01-设备接入与控制主链路.md
@@ -0,0 +1,59 @@
+# 01-设备接入与控制主链路
+
+IoT 系统的命脉在于可靠的通信机制。本链路基于 MQTT 协议，设计了设备从上线建连到数据双向交互的完整闭环。
+
+## 一、设备接入完整交互时序图
+
+```mermaid
+sequenceDiagram
+    participant Device as IoT设备
+    participant Gateway as MQTT Broker(网关)
+    participant IoTModule as module-iot(业务后服务)
+
+    == 第一阶段：设备注册与认证 ==
+    Device->>Gateway: CONNECT (Client ID, User, Password)
+    activate Gateway
+    Gateway->>IoTModule: 鉴权 Hook (校验 Token/秘钥)
+    IoTModule-->>Gateway: 鉴权通过
+    Gateway-->>Device: CONNACK (连接接受)
+    deactivate Gateway
+    
+    Device->>Gateway: SUBSCRIBE (Topic: /down/device/{id})
+    Gateway-->>Device: SUBACK
+    
+    == 第二阶段：保活与状态同步 ==
+    loop 心跳周期 (如 30s)
+        Device->>Gateway: PINGREQ
+        Gateway-->>Device: PINGRESP
+    end
+    
+    == 第三阶段：数据上报 (Telemetry) ==
+    Device->>Gateway: PUBLISH (Topic: /up/telemetry/{id}, Payload: JSON)
+    Gateway->>IoTModule: 消息路由/桥接
+    IoTModule->>IoTModule: 根据设备品类物模型进行解析
+    IoTModule->>IoTModule: 属性落库 / 存入时序数据库
+    
+    == 第四阶段：指令下发 (Command) ==
+    IoTModule->>Gateway: PUBLISH (Topic: /down/device/{id}, Payload: 控制指令)
+    Gateway->>Device: 推送下行消息
+    activate Device
+    Device->>Device: 执行硬件动作 (如关阀门)
+    Device->>Gateway: PUBLISH (Topic: /up/reply/{id}, Payload: 执行结果)
+    deactivate Device
+    Gateway->>IoTModule: 结果回调
+    IoTModule->>IoTModule: 更新指令状态及设备影子
+```
+
+## 二、通信链路设计红线与规范
+
+### 1. QoS (服务质量) 策略
+- **数据上报 (Telemetry)**：推荐使用 **QoS 0**。传感器高频数据允许丢失单点，追求高吞吐量；若属于关键状态跳变（如火警触发），必须使用 **QoS 1**。
+- **指令下发 (Command)**：强制使用 **QoS 1**。云端下发的开关门、断电指令必须确保到达，依靠 MQTT 协议级 ACK 进行重传保证。
+
+### 2. 异常断连与重连退避
+- 硬件网络天然不可靠。设备端在断连后，重连机制必须包含**指数退避（Exponential Backoff）加随机抖动（Jitter）算法**。
+- **严禁**：断网后设备以固定的 1 秒频率死循环重连。这将在基站恢复或 Broker 重启时引发“重连风暴”，直接导致网关雪崩。
+
+### 3. 上下线状态管理
+- 严禁通过轮询设备或单纯依赖心跳报文在业务代码里算超时。
+- 必须依赖 MQTT Broker 的 **连接/断开 Webhook (或遗嘱消息 Will Message)** 机制，由 Broker 主动回调 `module-iot` 通知设备上下线，业务侧被动更新 DB 状态。
--- a/开发者文档/03-IoT领域/02-物模型标准设计.md
+++ b/开发者文档/03-IoT领域/02-物模型标准设计.md
@@ -0,0 +1,52 @@
+# 02-物模型标准设计
+
+如果你让一个做业务的程序员去处理设备发来的 `01 03 00 00 00 01 84 0A` (Modbus RTU)，他会崩溃。
+**物模型（Thing Specification）**的作用就是把物理世界的设备抽象成程序员能看懂的“对象”。
+
+## 一、物模型三要素 (Property, Event, Service)
+
+所有接入 AIOT 平台的设备，无论是摄像头、烟感还是水表，都必须在这三层结构下被抽象。
+
+### 1. 属性 (Property)
+描述设备的运行状态（通常是只读或可读写的连续数据）。
+- **示例**：当前温度 (25.5℃)、工作模式 (Auto)、电池电量 (80%)。
+- **特点**：业务系统随时可以查询，云端需维护一份最新的副本（设备影子）。
+
+### 2. 事件 (Event)
+设备在运行期间主动向云端发出的瞬时通知。
+事件分为三个等级：
+- **INFO (信息)**：如“设备重启完成”。
+- **WARN (告警)**：如“网络延迟过高”。
+- **ERROR (故障)**：如“传感器短路”，此类事件通常直接触发规则引擎派生 Ops 工单。
+
+### 3. 服务 (Service) / 指令
+云端向设备下发的要求设备执行某个动作的操作，且该操作通常需要硬件执行完毕后返回结果。
+- **示例**：开门 (openDoor)、设置重启定时 (setRebootTimer)。
+- **与属性的区别**：设置温度阈值是“写属性”，要求设备清空历史记录是“调服务”。服务更像是一个 RPC 调用。
+
+## 二、标准 JSON Payload 规范
+
+网关接收到底层报文后，无论是何种私有协议，经过“协议解析脚本”后，推送到业务主逻辑的 JSON 必须符合以下规范：
+
+```json
+{
+  "device_id": "SN_12345678",
+  "timestamp": 1712419200000,
+  "type": "property_report",
+  "data": {
+    "temperature": 26.5,
+    "humidity": 45,
+    "battery_level": 88
+  }
+}
+```
+
+## 三、设备影子 (Device Shadow) 机制
+
+**痛点**：由于设备可能休眠（如 NB-IoT 水表一天只醒一次），App 用户如果在这个时候去点“开阀”或者查询状态，是无法立刻得到设备回应的。
+
+**解法：设备影子**
+- 云端在 Redis/MySQL 中永久维护一份该设备最后一次上报的属性镜像。
+- 用户查询时：直接返回“影子”中的数据。
+- 用户下发控制时：指令先更新到“影子”的期望值（Expected Value）中，并缓存指令。
+- 当休眠设备下一次唤醒并上报心跳时，云端比对影子的“实际值”和“期望值”，发现不一致，立刻将缓存的控制指令下发给设备。
--- a/开发者文档/03-IoT领域/03-规则引擎与联动策略.md
+++ b/开发者文档/03-IoT领域/03-规则引擎与联动策略.md
@@ -0,0 +1,37 @@
+# 03-规则引擎与联动策略
+
+有了设备接入和物模型后，IoT 系统算跑通了单机，但 AIOT 的威力在于**联动**。
+本章节描述大量无序的设备数据如何安全、有效地转化为 Ops 系统的工单任务。
+
+## 一、数据洪流与防抖过滤
+
+在将设备异常转化为实际告警或工单之前，**防抖（Debounce）与收敛**是第一道防线。
+
+### 1. 为什么要做防抖？
+如果一个温湿度传感器发生故障，它可能会以 1 秒 1 次的频率疯狂上报 `[ERROR] 探头短路`。如果不做拦截直接联动 Ops，安保大叔的手机一分钟内会被弹 60 个“派单通知”，系统也会因为瞬间的数据库写入被压死。
+
+### 2. 规则引擎防抖策略
+- **时间窗口去重**：同一台设备的同一种事件（如烟感报警），在 5 分钟内无论上报多少次，规则引擎只向后置业务流抛出**一次**告警事件。
+- **状态跳变判断**：只有当属性值从“正常阈值”跨越到“告警阈值”的那个瞬间（Edge Trigger），才触发规则。一直在告警线以上的数据点不重复触发。
+
+## 二、IoT 到 Ops 的正向联动链路
+
+从设备端发现问题，到现场人员赶到处理。
+
+1. **规则命中**：设备上报数据解析出 `water_leak = true`，触发 `规则ID=102: 水管漏水告警`。
+2. **事件转换**：规则引擎组装一个标准的「内部系统事件（Internal Event）」，包含 `设备ID`、`发生时间`、`发生物理位置（查设备表获得）`、`告警级别`。
+3. **跨域调用**：`module-iot` 通过内部 API（禁止通过外网网关）调用 `module-ops` 的 `生成紧急工单` 接口。
+4. **接力执行**：Ops 系统接管，按照其内部的抢单、强推播逻辑（参见 [[../02-Ops领域/03-安保业务核心链路.md]]），将任务压给最近的安保或维修工。
+
+## 三、Ops 到 IoT 的逆向状态闭环（反写）
+
+仅仅把单派出去是不够的，还需要实现信息闭环，防止 IoT 控制台和 Ops 控制台两张皮。
+
+### 1. 告警状态解绑
+- IoT 侧的告警大屏上，该设备的告警状态会亮起红灯。
+- 这盏红灯何时熄灭？不能仅仅依赖传感器下一次上报“正常”（因为传感器可能坏死）。
+- **必须由 Ops 侧驱动**：当维修工人在手机 App 上提交了现场修复照片，并将维修工单流转为 `COMPLETED` 状态时，Ops 系统回调 IoT 的接口，将对应的那条告警记录状态变更为【人工已解除】。
+
+### 2. 现场反控配合
+- 维修工到达现场处理故障时，由于控制箱被锁，他可以在 App 的工单详情页，点击「临时断电调试」。
+- 这个点击动作，穿透 Ops 域，直接调用 IoT 领域的“服务下发（Service Call）”接口，实现对现场断路器的远程切断。这证明了我们在架构中采用统一后端底座的优越性。