docs: 以MQTT V2协议校正注册绑定说明

This commit is contained in:
stu2not
2026-09-20 11:59:51 +08:00
parent 27e8ccfc2b
commit 4e91a534aa
2 changed files with 32 additions and 15 deletions
+27 -12
View File
@@ -10,8 +10,8 @@ This is the `msg_id=006` device-binding flow and is separate from the device
registration handshake documented in `02-device-bootstrap.md`. `msg_id=012`
only registers the device identity. `msg_id=006` starts and completes binding
the device to a mini-program user and optional child through the NFC card
exchange; its successful receipt carries the ICCID needed by the downstream
SIM/traffic service.
exchange. The current V2.0 receipt contains the NFC card UUID; carrying an
ICCID is a proposed extension described below.
```mermaid
sequenceDiagram
@@ -43,7 +43,7 @@ sequenceDiagram
API-->>Mini: bind_token, expires_at
end
Device->>MQTT: msg_id=006 binding success / card UUID / ICCID
Device->>MQTT: device/{imei}/response msg_id=006 status/data.uuid
MQTT->>Binding: finalize_nfc_bind(device_id, card_uuid)
Binding->>DAO: load latest pending bind session
Binding->>Card: activate_card(card_uuid, device_id)
@@ -52,26 +52,40 @@ sequenceDiagram
Binding->>DAO: mark session completed
```
## Binding Success Receipt
## Binding Response (V2.0)
The successful device-binding receipt uses `msg_id=006` and includes the
authoritative ICCID:
The current V2.0 protocol defines the successful `msg_id=006` response as:
```json
{
"msg_id": "006",
"params": {
"device_id": "TalkingQ_ZHWK00002110",
"device_sn": "TQ_ZHWK000000002110",
"status": "success",
"data": {
"uuid": "53D22B6DA20001"
}
}
```
The V2.0 response does not define an `iccid` field. Adding ICCID to the
binding receipt is therefore a protocol extension that requires coordinated
firmware and backend changes. A compatible proposal is to add it under
`data`, while preserving the existing `status` and `data.uuid` fields:
```json
{
"msg_id": "006",
"status": "success",
"data": {
"uuid": "53D22B6DA20001",
"iccid": "898604E91123D1334901"
}
}
```
The ICCID must come from the authoritative IMEI-to-ICCID provisioning record
or a validated device report. It must not be derived from the IMEI. If the
binding response cannot provide a valid ICCID, the binding result must not be
reported as a complete success.
or a validated device report; it must not be derived from the IMEI. This
proposed field is not part of the current V2.0 contract until both sides
accept and implement the extension.
## Related Tables
@@ -112,6 +126,7 @@ erDiagram
## Source Anchors
- MQTT protocol V2.0: `talkingq-url/docs/mqtt协议_V2.0.txt`
- Mini-program bind page: `banban-mini/src/pages/bind/index.tsx`
- Binding service: `talkingq-url/banban/service/binding.py`
- Binding DAO: `talkingq-url/banban/dao/binding.py`