91 lines
2.6 KiB
Markdown
91 lines
2.6 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.
|
|
|
|
```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: NFC response / card 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
|
|
```
|
|
|
|
## 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
|
|
|
|
- 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`
|