134 lines
4.0 KiB
Markdown
134 lines
4.0 KiB
Markdown
# Binding Flow
|
|
|
|
## Device Binding
|
|
|
|
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 `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. The current V2.0 receipt contains the NFC card UUID; carrying an
|
|
ICCID is a proposed extension described below.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
participant Parent as Parent in mini-program
|
|
participant Mini as banban-mini bind page
|
|
participant API as /banban/bind APIs
|
|
participant Binding as BindingService
|
|
participant DAO as BindingDAO
|
|
participant Auth as device_auth
|
|
participant MQTT as TalkingQMQTTService
|
|
participant Device as TalkingQ device
|
|
participant Card as cards
|
|
participant Bindings as device_bindings
|
|
participant History as device_bind_history
|
|
|
|
Parent->>Mini: Scan QR or open bind URL
|
|
Mini->>API: start_bind(device_id, serial_number, child_id)
|
|
API->>Binding: start_bind(user_id, device_id, serial_number, child_id)
|
|
Binding->>Auth: get_device_auth(device_id)
|
|
alt device missing, inactive, or serial mismatch
|
|
Binding-->>API: BindingError
|
|
API-->>Mini: 4xx error
|
|
else device is bindable
|
|
Binding->>DAO: ensure no active device binding
|
|
Binding->>DAO: create device_bind_session
|
|
Binding->>MQTT: send_bind_nfc_command(msg_id=006)
|
|
MQTT-->>Device: device/{device_id}/command
|
|
API-->>Mini: bind_token, expires_at
|
|
end
|
|
|
|
Device->>MQTT: device/{imei}/response msg_id=006 status/data.uuid
|
|
MQTT->>Binding: finalize_nfc_bind(device_id, card_uuid)
|
|
Binding->>DAO: load latest pending bind session
|
|
Binding->>Card: activate_card(card_uuid, device_id)
|
|
Binding->>Bindings: create active binding
|
|
Binding->>History: write bind audit history
|
|
Binding->>DAO: mark session completed
|
|
```
|
|
|
|
## Binding Response (V2.0)
|
|
|
|
The current V2.0 protocol defines the successful `msg_id=006` response as:
|
|
|
|
```json
|
|
{
|
|
"msg_id": "006",
|
|
"status": "success",
|
|
"data": {
|
|
"uuid": "53D22B6DA20001"
|
|
}
|
|
}
|
|
```
|
|
|
|
The V2.0 response does not define an `iccid` field. Adding ICCID to the
|
|
binding receipt is therefore a protocol extension that requires coordinated
|
|
firmware and backend changes. A compatible proposal is to add it under
|
|
`data`, while preserving the existing `status` and `data.uuid` fields:
|
|
|
|
```json
|
|
{
|
|
"msg_id": "006",
|
|
"status": "success",
|
|
"data": {
|
|
"uuid": "53D22B6DA20001",
|
|
"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. This
|
|
proposed field is not part of the current V2.0 contract until both sides
|
|
accept and implement the extension.
|
|
|
|
## Related Tables
|
|
|
|
```mermaid
|
|
erDiagram
|
|
parents ||--o{ children : owns
|
|
parents ||--o{ device_bindings : owns
|
|
children ||--o{ device_bindings : current_child
|
|
device_auth ||--o{ device_bindings : device
|
|
device_auth ||--o{ device_bind_sessions : pending_bind
|
|
device_auth ||--o{ cards : card_owner_device
|
|
device_bindings ||--o{ device_bind_history : audit
|
|
|
|
device_auth {
|
|
varchar device_id UK
|
|
varchar serial_number
|
|
tinyint is_active
|
|
}
|
|
|
|
device_bindings {
|
|
int binding_id PK
|
|
varchar device_id FK
|
|
int owner_user_id FK
|
|
int child_id FK
|
|
int status
|
|
}
|
|
|
|
device_bind_sessions {
|
|
int id PK
|
|
varchar bind_token UK
|
|
varchar device_id FK
|
|
int initiator_user_id
|
|
int target_child_id
|
|
int status
|
|
datetime expires_at
|
|
}
|
|
```
|
|
|
|
## Source Anchors
|
|
|
|
- MQTT protocol V2.0: `talkingq-url/docs/mqtt协议_V2.0.txt`
|
|
- Mini-program bind page: `banban-mini/src/pages/bind/index.tsx`
|
|
- Binding service: `talkingq-url/banban/service/binding.py`
|
|
- Binding DAO: `talkingq-url/banban/dao/binding.py`
|
|
- MQTT bind command handling: `talkingq-url/handlers/mqtt_handler.py`
|