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

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

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

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