From 27e8ccfc2bb3cd60650cc257a6b2f7f22f98bdd2 Mon Sep 17 00:00:00 2001 From: stu2not Date: Sun, 20 Sep 2026 11:57:20 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=AD=A3012=E6=B3=A8=E5=86=8C?= =?UTF-8?q?=E5=92=8C006=E7=BB=91=E5=AE=9A=E5=8D=8F=E8=AE=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture/02-device-bootstrap.md | 41 +++++++++--------------- docs/architecture/03-binding-flow.md | 34 ++++++++++++++++---- 2 files changed, 44 insertions(+), 31 deletions(-) diff --git a/docs/architecture/02-device-bootstrap.md b/docs/architecture/02-device-bootstrap.md index c6746af..b1d06fa 100644 --- a/docs/architecture/02-device-bootstrap.md +++ b/docs/architecture/02-device-bootstrap.md @@ -1,12 +1,12 @@ -# Device Bootstrap And Binding Receipt +# Device Registration ## Purpose -The device-level bootstrap/binding handshake maps a factory IMEI to Banban's -internal `device_id` and `serial_number`. Its successful `msg_id=012` response -is the device binding success receipt and includes the associated ICCID for -downstream SIM/traffic binding. Devices do not need to know those IDs before -the first handshake. +The device registration handshake maps a factory IMEI to Banban's internal +`device_id` and `serial_number`. `msg_id=012` is the device registration +request and response. It is not the user/device binding success receipt and +does not represent the `msg_id=006` binding flow. Devices do not need to know +the assigned IDs before the first registration handshake. ## Flow @@ -22,7 +22,7 @@ sequenceDiagram participant Auth as device_auth Factory->>Mapping: Insert imei, device_id, serial_number, status=pending - Device->>MQTT: Publish device/{imei}/event msg_id=012 binding request + Device->>MQTT: Publish device/{imei}/event msg_id=012 registration request MQTT->>Handler: Deliver identity init event Handler->>Init: initialize_by_imei(imei) Init->>Mapping: SELECT mapping by imei @@ -40,38 +40,29 @@ sequenceDiagram Handler-->>MQTT: device/{imei}/event_resp status=failed end Init->>Mapping: UPDATE status=activated, activated_at=now - Handler-->>MQTT: device/{imei}/event_resp binding success receipt - MQTT-->>Device: Receive device_id, device_sn, and iccid + Handler-->>MQTT: device/{imei}/event_resp registration success + MQTT-->>Device: Receive device_id and device_sn end ``` -## Binding Success Receipt +## Registration Response -When the IMEI mapping and its authoritative ICCID association are available, -the handler returns the device binding success receipt on `msg_id=012`: +When the IMEI mapping is available, the handler returns the registration +response on `msg_id=012`: ```json { "msg_id": "012", "params": { "device_id": "TalkingQ_ZHWK00002110", - "device_sn": "TQ_ZHWK000000002110", - "iccid": "898604E91123D1334901" + "device_sn": "TQ_ZHWK000000002110" } } ``` -The `iccid` value is the canonical, full ICCID used by the downstream SIM and -traffic service. It must come from an authoritative IMEI-to-ICCID provisioning -record or a validated device report; it must not be derived from the IMEI. -Successful device binding requires a non-empty, valid ICCID. If the ICCID -cannot be resolved or fails consistency validation, the handler must return -the existing `msg_id=012` failure response instead of returning a partial -success. - -Adding `params.iccid` is an additive response-field change. Devices that ignore -unknown JSON fields remain compatible, while strict firmware parsers need a -protocol/version capability check before this response is enabled for them. +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. ## Data Model diff --git a/docs/architecture/03-binding-flow.md b/docs/architecture/03-binding-flow.md index 032a401..1a5b1be 100644 --- a/docs/architecture/03-binding-flow.md +++ b/docs/architecture/03-binding-flow.md @@ -6,11 +6,12 @@ The mini-program binding flow validates an active `device_auth` row before it creates a pending bind session. Final binding is completed after the device returns an NFC card UUID. -This is the user/NFC binding flow and is separate from the device-level -`msg_id=012` bootstrap/binding handshake documented in -`02-device-bootstrap.md`. The `msg_id=012` success receipt assigns the device -identity and returns `iccid`; this flow binds that device to a mini-program -user and optional child through the NFC card exchange. +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. ```mermaid sequenceDiagram @@ -42,7 +43,7 @@ sequenceDiagram API-->>Mini: bind_token, expires_at end - Device->>MQTT: NFC response / card UUID + Device->>MQTT: msg_id=006 binding success / card UUID / ICCID MQTT->>Binding: finalize_nfc_bind(device_id, card_uuid) Binding->>DAO: load latest pending bind session Binding->>Card: activate_card(card_uuid, device_id) @@ -51,6 +52,27 @@ sequenceDiagram Binding->>DAO: mark session completed ``` +## Binding Success Receipt + +The successful device-binding receipt uses `msg_id=006` and includes the +authoritative ICCID: + +```json +{ + "msg_id": "006", + "params": { + "device_id": "TalkingQ_ZHWK00002110", + "device_sn": "TQ_ZHWK000000002110", + "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. + ## Related Tables ```mermaid