banban/docs/architecture/03-binding-flow.md

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; its successful receipt carries the ICCID needed by the downstream SIM/traffic service.

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: 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)
  Binding->>Bindings: create active binding
  Binding->>History: write bind audit history
  Binding->>DAO: mark session completed

Binding Success Receipt

The successful device-binding receipt uses msg_id=006 and includes the authoritative ICCID:

{
  "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

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