完善设备端体验与微信校验支持

docs/architecture/02-device-bootstrap.md

@@ -0,0 +1,85 @@
+# Device Bootstrap Flow
+
+## Purpose
+
+Device bootstrap maps a factory IMEI to Banban's internal `device_id` and
+`serial_number`. 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 and device_sn
+    MQTT-->>Device: Receive assigned identity
+  end
+```
+
+## 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`