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
+5 -3
View File
@@ -60,9 +60,10 @@ response on `msg_id=012`:
}
```
The ICCID belongs to the later `msg_id=006` device-binding success receipt,
not to this registration response. The registration response only establishes
the device identity needed by the binding flow.
The current V2.0 registration response does not carry an ICCID. Any ICCID
addition belongs to the separate `msg_id=006` binding-response extension; the
registration response only establishes the device identity needed by the
binding flow.
## Data Model
@@ -101,6 +102,7 @@ serial_number: TQ_ZHWK000000002001
## Source Anchors
- MQTT protocol V2.0: `talkingq-url/docs/mqtt协议_V2.0.txt`
- Bootstrap handler: `talkingq-url/handlers/mqtt_handler.py`
- Identity initializer: `talkingq-url/services/device_identity_initializer.py`
- Import script: `talkingq-url/scripts/import_device_imei_mapping.py`
+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`