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

docs/architecture/06-alarm-and-notification-flow.md

@@ -0,0 +1,75 @@
+# Alarm And Notification Flow
+
+## Device Alarm To User Notification
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Device as TalkingQ device
+  participant MQTT as MQTT broker
+  participant Handler as TalkingQMQTTService
+  participant Alarm as Alarm service
+  participant Location as Location snapshot
+  participant DB as device_alarm_events
+  participant Banner as system banner polling
+  participant Mini as banban-mini
+  participant WxMP as WeChat Official Account
+  participant SMS as SMS provider
+
+  Device->>MQTT: alarm event msg_id=010
+  MQTT->>Handler: deliver alarm payload
+  Handler->>Alarm: create alarm event
+  Alarm->>Location: attach current location snapshot if available
+  Alarm->>DB: insert device_alarm_events
+  Alarm->>WxMP: schedule/send template notification if bound
+  Alarm->>SMS: send SMS if phone notification is enabled
+  Banner->>DB: poll latest/new alarm
+  Mini->>Banner: show banner / alarm history on device home
+  Handler-->>MQTT: alarm event_resp
+```
+
+## Supporting Notification Bind
+
+```mermaid
+flowchart TD
+  Mini["banban-mini management page"]
+  Phone["WeChat phone authorization"]
+  WxBind["WeChat MP bind start/status"]
+  Backend["talkingq-url wechat-mp routers/services"]
+  Parent["parents / parent_wechat_* tables"]
+  Notify["wechat_mp_notification_service"]
+
+  Mini --> Phone --> Backend --> Parent
+  Mini --> WxBind --> Backend --> Parent
+  Parent --> Notify
+```
+
+## Key Tables
+
+```mermaid
+erDiagram
+  device_auth ||--o{ device_alarm_events : reports
+  children ||--o{ device_alarm_events : alarm_owner
+  parents ||--o{ parent_wechat_accounts : mp_account
+  parents ||--o{ parent_wechat_identities : wx_identity
+  parents ||--o{ wechat_mp_bind_states : bind_state
+
+  device_alarm_events {
+    int id PK
+    varchar device_id FK
+    int child_id FK
+    varchar source_msg_id
+    decimal location_lat
+    decimal location_lng
+    datetime location_updated_at
+    datetime created_at
+  }
+```
+
+## Source Anchors
+
+- Alarm schema: `database/talkingq_shared_schema.sql`
+- Alarm location refresh tests: `talkingq-url/tests/test_alarm_gps_location_refresh.py`
+- System banner client: `banban-mini/src/services/system-banner.ts`
+- Device home alarm UI: `banban-mini/src/pages/device/index.tsx`
+- WeChat MP notification service: `talkingq-url/banban/service/wechat_mp_notification.py`