refactor: migrate to Tencent Cloud backend
这个提交包含在：
Guoguo
@@ -0,0 +1,156 @@
|
||||
# IoT 设备注册与 MQTT 消息规范
|
||||
|
||||
基于 `软件系统说明.docx` 整理。本文档用于固定当前已知的 IoT 与 MQTT 事实，并列出设备接入、消息定义和云端处理前必须补齐的规格项。
|
||||
|
||||
本文档不虚构未被文档确认的 topic、payload 或接入流程。
|
||||
|
||||
## 已确认事实
|
||||
|
||||
- 设备接入平台：`Tencent Cloud IoT Hub`
|
||||
- 设备通过 `MQTT over TLS` 连接 IoT Hub
|
||||
- 已知上报主题：`$iot/{product_id}/{device_name}/telemetry`
|
||||
- 已知事件主题：`$iot/{product_id}/{device_name}/event`
|
||||
- 云端业务组件包含：`SCF`、`MySQL`、`Redis`、`CLS`、`CMQ`
|
||||
- 护理记录存在异步写入路径
|
||||
- 云函数职责中包含：设备注册、动态获取 `DeviceSecret`
|
||||
|
||||
## 已知接入边界
|
||||
|
||||
从当前文档可确认以下边界：
|
||||
|
||||
- 设备端不是直接写业务数据库，而是先接入 IoT Hub
|
||||
- 云端至少存在一条设备消息 -> 云端处理 -> 数据落库的链路
|
||||
- 设备身份认证依赖 `DeviceSecret`
|
||||
- 系统同时存在实时设备通信和异步消息处理
|
||||
|
||||
## 设备接入流程的最小骨架
|
||||
|
||||
当前文档没有给出完整时序，但从已知信息可整理出一条最小流程骨架：
|
||||
|
||||
1. 设备具备 `product_id` 和 `device_name`
|
||||
2. 设备获取或持有 `DeviceSecret`
|
||||
3. 设备通过 `MQTT over TLS` 连接 IoT Hub
|
||||
4. 设备向指定 topic 上报 telemetry 和 event
|
||||
5. 云端处理消息并执行日志、异步、入库等后续动作
|
||||
|
||||
## 待补齐的设备注册流程
|
||||
|
||||
当前最大缺口是 `DeviceSecret` 和设备注册流程，至少需要明确：
|
||||
|
||||
- 设备是在生产阶段预注册，还是首次使用时动态注册
|
||||
- `DeviceSecret` 是一次性签发还是可轮换
|
||||
- `DeviceSecret` 由谁调用云函数获取：生产工具、设备端、小程序端，还是后台系统
|
||||
- 设备首次上线是否需要激活
|
||||
- 设备注册与用户绑定是否是两个独立阶段
|
||||
- 设备换绑、禁用、报废时如何处理 IoT 身份
|
||||
|
||||
## MQTT topic 已知信息
|
||||
|
||||
### 遥测主题
|
||||
|
||||
- Topic：`$iot/{product_id}/{device_name}/telemetry`
|
||||
- 作用：设备业务数据上报
|
||||
|
||||
当前缺失：
|
||||
|
||||
- payload 结构
|
||||
- 上报频率
|
||||
- 是否包含治疗过程数据
|
||||
- 是否包含传感器原始数据
|
||||
|
||||
### 事件主题
|
||||
|
||||
- Topic：`$iot/{product_id}/{device_name}/event`
|
||||
- 作用：设备事件上报
|
||||
|
||||
当前缺失：
|
||||
|
||||
- 事件类型枚举
|
||||
- 事件触发条件
|
||||
- 事件 payload
|
||||
- 错误事件与普通事件的区分
|
||||
|
||||
## 必须补齐的消息规范
|
||||
|
||||
### 1. Telemetry 消息
|
||||
|
||||
至少需要确认：
|
||||
|
||||
- 消息体格式：JSON、二进制或其他格式
|
||||
- 核心字段
|
||||
- 时间戳字段
|
||||
- 设备状态字段
|
||||
- 治疗相关字段
|
||||
- 是否包含批量数据
|
||||
- 是否需要签名或序列号
|
||||
|
||||
### 2. Event 消息
|
||||
|
||||
至少需要确认：
|
||||
|
||||
- 事件类型枚举
|
||||
- 事件等级
|
||||
- 事件时间
|
||||
- 事件附加上下文
|
||||
- 是否需要重试
|
||||
|
||||
### 3. 下行控制消息
|
||||
|
||||
当前文档没有明确写出下行 topic，但若系统需要远程控制或同步状态，必须明确：
|
||||
|
||||
- 是否存在云端 -> 设备的下发 topic
|
||||
- 是否存在应答 topic
|
||||
- 远程指令的触发方：小程序、后台、云端任务
|
||||
- 指令时效和超时规则
|
||||
|
||||
## 消息处理链路待确认
|
||||
|
||||
当前只知道使用 `CMQ` 异步处理，至少需要明确：
|
||||
|
||||
- IoT Hub 消息如何进入云函数或消息队列
|
||||
- 哪些消息同步处理，哪些消息异步处理
|
||||
- 护理记录异步写入的触发条件
|
||||
- 失败重试策略
|
||||
- 死信消息处理策略
|
||||
- 日志打点字段
|
||||
|
||||
## 建议补充的消息模板
|
||||
|
||||
后续可以按以下模板补齐实际 payload。
|
||||
|
||||
### Telemetry 模板
|
||||
|
||||
| 字段 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 待定义 | 待定义 | 待定义 | 待定义 |
|
||||
|
||||
### Event 模板
|
||||
|
||||
| 字段 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 待定义 | 待定义 | 待定义 | 待定义 |
|
||||
|
||||
## 设备状态建议先澄清的枚举
|
||||
|
||||
后续设计时建议先统一这些状态的定义：
|
||||
|
||||
- 未注册
|
||||
- 已注册未激活
|
||||
- 已激活未绑定
|
||||
- 已绑定
|
||||
- 在线
|
||||
- 离线
|
||||
- 禁用
|
||||
- 故障
|
||||
|
||||
## 待确认问题
|
||||
|
||||
- `DeviceSecret` 是否通过云函数动态返回给设备
|
||||
- 小程序在设备注册链路中扮演什么角色
|
||||
- 设备是否需要主动上报固件版本、硬件版本、电量、错误状态
|
||||
- `telemetry` 和 `event` 的边界如何划分
|
||||
- 后台是否需要通过云端下发控制指令
|
||||
|
||||
## 当前结论
|
||||
|
||||
当前说明已足够确定 IoT 接入方式和两个基础 MQTT topic，但远不足以支持设备接入开发。最先要补的是设备注册流程、`DeviceSecret` 生命周期、payload 结构和消息处理链路。
|
||||
在新工单中引用
屏蔽一个用户