docs: 更正012注册和006绑定协议

This commit is contained in:
stu2not
2026-09-20 11:57:20 +08:00
parent 75fd3d86c4
commit 27e8ccfc2b
2 changed files with 44 additions and 31 deletions
+16 -25
View File
@@ -1,12 +1,12 @@
# Device Bootstrap And Binding Receipt
# Device Registration
## Purpose
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.
The device registration handshake maps a factory IMEI to Banban's internal
`device_id` and `serial_number`. `msg_id=012` is the device registration
request and response. It is not the user/device binding success receipt and
does not represent the `msg_id=006` binding flow. Devices do not need to know
the assigned IDs before the first registration handshake.
## Flow
@@ -22,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 binding request
Device->>MQTT: Publish device/{imei}/event msg_id=012 registration request
MQTT->>Handler: Deliver identity init event
Handler->>Init: initialize_by_imei(imei)
Init->>Mapping: SELECT mapping by imei
@@ -40,38 +40,29 @@ sequenceDiagram
Handler-->>MQTT: device/{imei}/event_resp status=failed
end
Init->>Mapping: UPDATE status=activated, activated_at=now
Handler-->>MQTT: device/{imei}/event_resp binding success receipt
MQTT-->>Device: Receive device_id, device_sn, and iccid
Handler-->>MQTT: device/{imei}/event_resp registration success
MQTT-->>Device: Receive device_id and device_sn
end
```
## Binding Success Receipt
## Registration Response
When the IMEI mapping and its authoritative ICCID association are available,
the handler returns the device binding success receipt on `msg_id=012`:
When the IMEI mapping is available, the handler returns the registration
response on `msg_id=012`:
```json
{
"msg_id": "012",
"params": {
"device_id": "TalkingQ_ZHWK00002110",
"device_sn": "TQ_ZHWK000000002110",
"iccid": "898604E91123D1334901"
"device_sn": "TQ_ZHWK000000002110"
}
}
```
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 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
protocol/version capability check before this response is enabled for them.
The ICCID belongs to the later `msg_id=006` device-binding success receipt,
not to this registration response. The registration response only establishes
the device identity needed by the binding flow.
## Data Model
+28 -6
View File
@@ -6,11 +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.
This is the `msg_id=006` device-binding flow and is separate from the device
registration handshake documented in `02-device-bootstrap.md`. `msg_id=012`
only registers the device identity. `msg_id=006` starts and completes binding
the device to a mini-program user and optional child through the NFC card
exchange; its successful receipt carries the ICCID needed by the downstream
SIM/traffic service.
```mermaid
sequenceDiagram
@@ -42,7 +43,7 @@ sequenceDiagram
API-->>Mini: bind_token, expires_at
end
Device->>MQTT: NFC response / card UUID
Device->>MQTT: msg_id=006 binding success / card UUID / ICCID
MQTT->>Binding: finalize_nfc_bind(device_id, card_uuid)
Binding->>DAO: load latest pending bind session
Binding->>Card: activate_card(card_uuid, device_id)
@@ -51,6 +52,27 @@ sequenceDiagram
Binding->>DAO: mark session completed
```
## Binding Success Receipt
The successful device-binding receipt uses `msg_id=006` and includes the
authoritative ICCID:
```json
{
"msg_id": "006",
"params": {
"device_id": "TalkingQ_ZHWK00002110",
"device_sn": "TQ_ZHWK000000002110",
"iccid": "898604E91123D1334901"
}
}
```
The ICCID must come from the authoritative IMEI-to-ICCID provisioning record
or a validated device report. It must not be derived from the IMEI. If the
binding response cannot provide a valid ICCID, the binding result must not be
reported as a complete success.
## Related Tables
```mermaid