jw-beauty/docs/design/05-IoT设备注册与MQTT消息规范.md

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 结构和消息处理链路。