docs: 明确012为设备绑定成功回执

This commit is contained in:
stu2not
2026-09-20 11:50:21 +08:00
parent 2bfd69c96b
commit 75fd3d86c4
2 changed files with 21 additions and 13 deletions
+15 -13
View File
@@ -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
+6
View File
@@ -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