# Device Bootstrap Flow

## Purpose

Device bootstrap maps a factory IMEI to Banban's internal `device_id` and
`serial_number`, and returns the associated ICCID for downstream SIM/traffic
binding. Devices do not need to know those IDs before first bootstrap.

## Flow

```mermaid
sequenceDiagram
  autonumber
  participant Factory as Factory Excel / import CSV
  participant Mapping as device_imei_mapping
  participant Device as TalkingQ device
  participant MQTT as MQTT broker
  participant Handler as TalkingQMQTTService
  participant Init as device_identity_initializer
  participant Auth as device_auth

  Factory->>Mapping: Insert imei, device_id, serial_number, status=pending
  Device->>MQTT: Publish device/{imei}/event msg_id=012
  MQTT->>Handler: Deliver identity init event
  Handler->>Init: initialize_by_imei(imei)
  Init->>Mapping: SELECT mapping by imei
  alt mapping missing or incomplete
    Init-->>Handler: DeviceIdentityInitializationError
    Handler-->>MQTT: device/{imei}/event_resp status=failed
  else mapping found
    Init->>Auth: SELECT device_auth by device_id
    alt no auth row
      Init->>Auth: INSERT device_id, serial_number, is_active=1
    else auth row exists and serial matches
      Init->>Auth: UPDATE is_active=1
    else serial mismatch
      Init-->>Handler: device_auth serial_number conflict
      Handler-->>MQTT: device/{imei}/event_resp status=failed
    end
    Init->>Mapping: UPDATE status=activated, activated_at=now
    Handler-->>MQTT: device/{imei}/event_resp with device_id, device_sn, and iccid
    MQTT-->>Device: Receive assigned identity
  end
```

## Successful Response

When the IMEI mapping and its authoritative ICCID association are available,
the handler returns the assigned identity and ICCID in the `msg_id=012`
response:

```json
{
  "msg_id": "012",
  "params": {
    "device_id": "TalkingQ_ZHWK00002110",
    "device_sn": "TQ_ZHWK000000002110",
    "iccid": "898604E91123D1334901"
  }
}
```

The `iccid` value is the canonical, full ICCID used by the downstream SIM and
traffic service. It must come from an authoritative IMEI-to-ICCID provisioning
record or a validated device report; it must not be derived from the IMEI.
Successful bootstrap requires a non-empty, valid ICCID. If the ICCID cannot
be resolved or fails consistency validation, the handler must return the
existing `msg_id=012` failure response instead of returning a partial success.

Adding `params.iccid` is an additive response-field change. Devices that ignore
unknown JSON fields remain compatible, while strict firmware parsers need a
protocol/version capability check before this response is enabled for them.

## Data Model

```mermaid
erDiagram
  device_imei_mapping {
    int id PK
    varchar imei UK
    varchar device_id UK
    varchar serial_number
    varchar status
    datetime activated_at
    datetime created_at
    datetime updated_at
  }

  device_auth {
    int id PK
    varchar device_id UK
    varchar serial_number
    varchar batch_id
    tinyint is_active
    datetime created_at
    datetime updated_at
  }

  device_imei_mapping ||--o| device_auth : activates
```

## Current ID Style

```text
device_id:     TalkingQ_ZHWK00002001
serial_number: TQ_ZHWK000000002001
```

## Source Anchors

- Bootstrap handler: `talkingq-url/handlers/mqtt_handler.py`
- Identity initializer: `talkingq-url/services/device_identity_initializer.py`
- Import script: `talkingq-url/scripts/import_device_imei_mapping.py`
- Tables: `database/talkingq_shared_schema.sql`