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. The current V2.0 receipt contains the NFC card UUID; carrying an ICCID is a proposed extension described below.

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 V2.0 protocol defines the successful msg_id=006 response as:

{
  "msg_id": "006",
  "status": "success",
  "data": {
    "uuid": "53D22B6DA20001",
    "iccid": "898604E91123D1334901"
  }
}

The ICCID must come from the authoritative IMEI-to-ICCID provisioning record The iccid field is now part of the documented 006 success receipt. It must come from the authoritative IMEI-to-ICCID provisioning record or a validated device report; it must not be derived from the IMEI. Firmware and backend runtime support still need to be deployed together before this field can be relied on in production.

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

• 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