Codex
52 lines
5.1 KiB
Markdown
52 lines
5.1 KiB
Markdown
# 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` | 十进制字符串规范化，不用浮点累计；temp 优先，冲突写协议告警/死信 |
|
||
|
||
`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`、清空全部任务以及其他危险维护命令要求平台管理员和固定确认短语，复位口令只保存哈希与脱敏值。
|