qipai/docs/mqtt-protocol-mapping.md

MQTT 协议映射

M06-C 已按 V5.4 中固化的厂商协议字段实现适配器、上行解析、命令关联、消息幂等与死信。仓库当前未找到总纲点名的两份 PDF 原件，因此尚不能完成 PDF 页码级复核；不得把此状态写成“PDF 已阅读”。

设备	Topic/命令	方向	字段	状态
4G 智能门禁控电箱	/devicesend/{DeviceID}、/devicewill/{DeviceID}、/deviceaccept/{DeviceID}	双向	basicInfo/mqttConfig/startVoice/task/taskconfig、ConctolPower、Crldoor、PlayTTS/stopTTS、CrlLED、task/addtask/canceltask	PARTIAL
Sub-1G 智能门锁	经父控制箱使用相同三个 Topic	双向	AddDevice、CtrlDevice；open/close/setkey/delkey/setcard/delcard/factoryreset	PARTIAL
4G 智慧插座	/devicesend/{DeviceID}、/devicewill/{DeviceID}、/deviceaccept/{DeviceID}	双向	basicInfo/workInfo、on/off、localtask、clearTask	PARTIAL

M06-A ACL 基线

客户端	允许发布	允许订阅	状态
设备客户端 qipai-device-{DeviceID}，用户名等于 DeviceID	/devicesend/{DeviceID}、/devicewill/{DeviceID}	/deviceaccept/{DeviceID}	模板已固定，生产未应用
后端服务 qipai_backend_prod	/deviceaccept/+	/devicesend/+、/devicewill/+	模板已固定，生产未应用
普通客户端	禁止 $SYS/#、#、+/#	禁止未显式允许主题	模板已生成

后端 MQTT.js 固定使用 MQTT 3.1（protocolVersion: 3）、QoS 1、持久会话、自动重连，并在每次连接成功后显式恢复两个上行订阅。单条应用消息默认限制为 64 KiB。

M06-C 消息规则

• 命令 ID 只允许 1-13 位数字，默认生成 10 位秒时间戳加 3 位滚动序号。
• 下发先写 qipai_iot_commands=PENDING，MQTT 发布成功后转 PUBLISHED，有效 ACK 才转 ACKED。
• fail/busy/unconfirm/timeout/full 统一转 FAILED 并保留厂商结果码；超时扫描可把未回包命令转 TIMEOUT。
• 上行先校验 Topic、资产 DeviceID 和 JSON；异常 Topic、未知设备、非法 JSON/字段进入 qipai_iot_dead_letters。
• QoS 1 重复消息命中唯一键后只增加 receive_count，不重复执行 ACK、状态快照或后续业务副作用。
• 原始 JSON 与标准化 JSON 分开保存；协议字段大小写和拼写不得在适配器外重新拼装。