diff --git a/docs/architecture/02-device-bootstrap.md b/docs/architecture/02-device-bootstrap.md index 759185c..a32b003 100644 --- a/docs/architecture/02-device-bootstrap.md +++ b/docs/architecture/02-device-bootstrap.md @@ -3,7 +3,8 @@ ## Purpose Device bootstrap maps a factory IMEI to Banban's internal `device_id` and -`serial_number`. Devices do not need to know those IDs before first bootstrap. +`serial_number`, and returns the associated ICCID for downstream SIM/traffic +binding. Devices do not need to know those IDs before first bootstrap. ## Flow @@ -37,11 +38,39 @@ 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 and device_sn + Handler-->>MQTT: device/{imei}/event_resp with device_id, device_sn, and iccid MQTT-->>Device: Receive assigned identity end ``` +## Successful Response + +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: + +```json +{ + "msg_id": "012", + "params": { + "device_id": "TalkingQ_ZHWK00002110", + "device_sn": "TQ_ZHWK000000002110", + "iccid": "898604E91123D1334901" + } +} +``` + +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. + +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. + ## Data Model ```mermaid