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 ## Purpose
Device bootstrap maps a factory IMEI to Banban's internal `device_id` and The device-level bootstrap/binding handshake maps a factory IMEI to Banban's
`serial_number`, and returns the associated ICCID for downstream SIM/traffic internal `device_id` and `serial_number`. Its successful `msg_id=012` response
binding. Devices do not need to know those IDs before first bootstrap. 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 ## Flow
@@ -20,7 +22,7 @@ sequenceDiagram
participant Auth as device_auth participant Auth as device_auth
Factory->>Mapping: Insert imei, device_id, serial_number, status=pending 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 MQTT->>Handler: Deliver identity init event
Handler->>Init: initialize_by_imei(imei) Handler->>Init: initialize_by_imei(imei)
Init->>Mapping: SELECT mapping by imei Init->>Mapping: SELECT mapping by imei
@@ -38,16 +40,15 @@ sequenceDiagram
Handler-->>MQTT: device/{imei}/event_resp status=failed Handler-->>MQTT: device/{imei}/event_resp status=failed
end end
Init->>Mapping: UPDATE status=activated, activated_at=now Init->>Mapping: UPDATE status=activated, activated_at=now
Handler-->>MQTT: device/{imei}/event_resp with device_id, device_sn, and iccid Handler-->>MQTT: device/{imei}/event_resp binding success receipt
MQTT-->>Device: Receive assigned identity MQTT-->>Device: Receive device_id, device_sn, and iccid
end end
``` ```
## Successful Response ## Binding Success Receipt
When the IMEI mapping and its authoritative ICCID association are available, When the IMEI mapping and its authoritative ICCID association are available,
the handler returns the assigned identity and ICCID in the `msg_id=012` the handler returns the device binding success receipt on `msg_id=012`:
response:
```json ```json
{ {
@@ -63,9 +64,10 @@ response:
The `iccid` value is the canonical, full ICCID used by the downstream SIM and 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 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. 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 Successful device binding requires a non-empty, valid ICCID. If the ICCID
be resolved or fails consistency validation, the handler must return the cannot be resolved or fails consistency validation, the handler must return
existing `msg_id=012` failure response instead of returning a partial success. 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 Adding `params.iccid` is an additive response-field change. Devices that ignore
unknown JSON fields remain compatible, while strict firmware parsers need a 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 creates a pending bind session. Final binding is completed after the device
returns an NFC card UUID. 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 ```mermaid
sequenceDiagram sequenceDiagram
autonumber autonumber