# 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`