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

docs/architecture/01-system-overview.md

@@ -0,0 +1,69 @@
+# System Overview
+
+## Runtime Architecture
+
+```mermaid
+flowchart LR
+  subgraph WeChat["WeChat Ecosystem"]
+    Mini["banban-mini\nTaro WeChat mini-program"]
+    WxLogin["WeChat login / phone APIs"]
+    WxMP["WeChat Official Account\nnotifications and bind"]
+  end
+
+  subgraph Edge["Public Edge"]
+    Domain["banban.api.talkingq.com"]
+    Nginx["Nginx / TLS"]
+  end
+
+  subgraph Backend["talkingq-url FastAPI backend"]
+    Main["main.py\nFastAPI app + lifespan"]
+    AuthMW["banban auth middleware"]
+    BanbanRouter["banban routers\nchildren, devices, binding, chat,\nlocation, alarms, firmware, roles,\nwechat-mp"]
+    MqttSvc["TalkingQMQTTService"]
+    Scheduler["TaskScheduler\ncleanup and periodic tasks"]
+    StaticAssets["/assets static files"]
+  end
+
+  subgraph Data["Stateful Services"]
+    MySQL["MySQL\nshared banban schema"]
+    COS["Tencent COS\nmessage audio files"]
+    MQTT["MQTT broker"]
+  end
+
+  subgraph DeviceSide["Device Side"]
+    Device["TalkingQ device"]
+    NFC["NFC card"]
+  end
+
+  subgraph External["External Providers"]
+    MapSvc["Map / reverse geocoding provider"]
+    SMS["SMS provider"]
+  end
+
+  Mini -->|HTTPS /banban/*| Domain --> Nginx --> Main
+  Main --> AuthMW --> BanbanRouter
+  Main --> StaticAssets
+  Main --> Scheduler
+  Main --> MqttSvc
+  BanbanRouter --> MySQL
+  MqttSvc --> MQTT
+  Device -->|device/{id}/event,response| MQTT
+  MQTT -->|subscribed messages| MqttSvc
+  MqttSvc --> MySQL
+  Device --> NFC
+  BanbanRouter --> COS
+  MqttSvc --> COS
+  BanbanRouter --> WxLogin
+  BanbanRouter --> WxMP
+  BanbanRouter --> SMS
+  MqttSvc --> MapSvc
+```
+
+## Source Anchors
+
+- Mini-program API base and services: `banban-mini/src/services/*`
+- FastAPI startup and router registration: `talkingq-url/main.py`
+- Banban route aggregation: `talkingq-url/banban/routers/*`
+- MQTT service and device message handlers: `talkingq-url/handlers/mqtt_handler.py`
+- Shared database schema: `database/talkingq_shared_schema.sql`
+- Runtime database initialization: `talkingq-url/database/init_db.py`