docs: 补充设备初始化回执中的ICCID

This commit is contained in:
stu2not
2026-09-20 11:31:45 +08:00
parent 15e7c56319
commit 2bfd69c96b
+31 -2
View File
@@ -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