diff --git a/docs/architecture/02-device-bootstrap.md b/docs/architecture/02-device-bootstrap.md index a32b003..c6746af 100644 --- a/docs/architecture/02-device-bootstrap.md +++ b/docs/architecture/02-device-bootstrap.md @@ -1,10 +1,12 @@ -# Device Bootstrap Flow +# Device Bootstrap And Binding Receipt ## Purpose -Device bootstrap maps a factory IMEI to Banban's internal `device_id` and -`serial_number`, and returns the associated ICCID for downstream SIM/traffic -binding. Devices do not need to know those IDs before first bootstrap. +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. ## Flow @@ -20,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 + Device->>MQTT: Publish device/{imei}/event msg_id=012 binding request MQTT->>Handler: Deliver identity init event Handler->>Init: initialize_by_imei(imei) Init->>Mapping: SELECT mapping by imei @@ -38,16 +40,15 @@ sequenceDiagram Handler-->>MQTT: device/{imei}/event_resp status=failed end Init->>Mapping: UPDATE status=activated, activated_at=now - Handler-->>MQTT: device/{imei}/event_resp with device_id, device_sn, and iccid - MQTT-->>Device: Receive assigned identity + Handler-->>MQTT: device/{imei}/event_resp binding success receipt + MQTT-->>Device: Receive device_id, device_sn, and iccid end ``` -## Successful Response +## Binding Success Receipt When the IMEI mapping and its authoritative ICCID association are available, -the handler returns the assigned identity and ICCID in the `msg_id=012` -response: +the handler returns the device binding success receipt on `msg_id=012`: ```json { @@ -63,9 +64,10 @@ response: 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 bootstrap 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. +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 diff --git a/docs/architecture/03-binding-flow.md b/docs/architecture/03-binding-flow.md index 96a1fbb..032a401 100644 --- a/docs/architecture/03-binding-flow.md +++ b/docs/architecture/03-binding-flow.md @@ -6,6 +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. + ```mermaid sequenceDiagram autonumber