qipai/docs/mqtt-protocol-mapping.md

MQTT 协议映射

M06-C/E-R1 已依据 V5.6 中完成的两份厂商协议原件审计，校正控制箱、Sub-1G 门锁与智慧插座的 Wire JSON、上行结果、事件、脱敏和离线处理。旧 powerW/temperature/overLoad 假字段已从生产告警逻辑删除，仅保留负向 fixture 证明其不会触发保护告警。

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

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。
• 结果按命令判别：task 接受 ok/busy/fail/unconfirm，CtrlDevice 接受 ok/fail/timeout/full，PlayTTS 接受 ok/paraerror；其他已知结果还包括 error/update。
• 未知或不属于当前命令的结果保存原值并标准化为 UNKNOWN_VENDOR_RESULT，命令转 FAILED，同时写协议告警和死信；不得让消费进程崩溃或误判成功。
• 上行先校验 Topic、资产 DeviceID 和消息边界；异常 Topic、未知设备、非法 JSON/字段进入 qipai_iot_dead_letters。/devicewill/{DeviceID} 明确兼容原始文本 close，此情形直接更新离线状态，不作为非法 JSON。
• QoS 1 重复消息命中唯一键后只增加 receive_count，不重复执行 ACK、状态快照或后续业务副作用。
• 原始 JSON 与标准化 JSON 分开保存；record.content 和门锁密码/卡号 value 在持久化前只保留 SHA-256 与脱敏尾号，协议字段大小写和拼写不得在适配器外重新拼装。

M06-C-R1 精确出站映射

领域输入	Canonical Wire	约束
TTS volume/firstPlay/loop/speaker/style/speed/intonation	action=PlayTTS + vol/firstPlay/loop/speaker/style/speed/intona/id	vol 0-10、firstPlay 0/1、speaker 0-5、style 0-2、speed/intona 0-10
配对等待 timeout	action=AddDevice,time,id	首个无 subtype/subID 的 ok 只表示进入配对窗口；最终包才将命令 ACK 并固化拓扑
门锁动作	action=CtrlDevice,subtype,subID,order,id[,value]	subtype 仅 14/15；密码按连续 6 位分组，卡号按连续 8 位十六进制分组；卡号发送大写

delkey/delcard value=all 与 factoryreset 仅平台管理员加固定确认短语可下发；凭据管理至少要求门店管理员权限。magstate、taskfinish、Poweron、connected 和 record 均按事件处理，不进入命令 ACK。

M06-E-R1 智慧插座精确映射

领域输入/上行	Canonical Wire/领域字段	规则
读取本地任务	read=localtask,slotNum,taskNum	taskNum=0 仅表示读取全部；另支持 canonical read=mqttConfig
mode/time/weekdays/action	cyctype/actiontime/weekdata/tasktype	once/daycyc/weekcyc；时间固定 HHmm；weekdata 固定周一至周日 7 位 0/1
保护 DTO + 设备型号/能力	setting=protectOff	maxCurrent/maxPower 按 10A/16A/63A 分级校验；自停功率不得高于最大功率
keyOff	setting=parameter,...,KeyOff,id	接收兼容 keyOff/KeyOff，发送只用 KeyOff
`onOff/vol/cur/pow/temp	temperature/energy`	switchOn/voltage/current/power/temperature/energy

special.closeReason 1/2 是本地按键操作，不生成保护告警；3/4/5/6/7 分别映射 SOCKET_PULL_OUT_STOP/SOCKET_CHARGE_FULL_STOP/SOCKET_OVERPOWER/SOCKET_OVERCURRENT/SOCKET_OVERTEMPERATURE。emptyPower、returnFactory、清空全部任务以及其他危险维护命令要求平台管理员和固定确认短语，复位口令只保存哈希与脱敏值。