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

2026-07-07 16:58:05 +08:00
parent b4fef6d2e0
commit 937e3023fc
38 changed files with 3377 additions and 51 deletions
--- a/docs/architecture/03-binding-flow.md
+++ b/docs/architecture/03-binding-flow.md
@@ -0,0 +1,90 @@
+# 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.
+
+```mermaid
+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: NFC response / card 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
+```
+
+## Related Tables
+
+```mermaid
+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`