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

docs/architecture/04-voice-and-im-flow.md

@@ -0,0 +1,74 @@
+# Voice And IM Flow
+
+## Parent Voice Message To Device
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Parent as Parent
+  participant Mini as Chat detail page
+  participant API as /banban chat APIs
+  participant Audio as Upload / audio handling
+  participant COS as Tencent COS
+  participant IM as IM service / DAO
+  participant DB as im_conversations + im_messages
+  participant Pending as device_pending_voice_messages
+  participant MQTT as MQTT broker
+  participant Device as TalkingQ device
+
+  Parent->>Mini: Long press "press to leave message"
+  Mini->>Mini: Taro.getRecorderManager records mp3/aac
+  Mini->>API: upload voice file + metadata
+  API->>Audio: validate and store audio
+  Audio->>COS: upload message audio
+  COS-->>Audio: media_file_key / public URL
+  API->>IM: create parent voice IM message
+  IM->>DB: upsert conversation and insert message
+  IM->>Pending: create pending voice delivery row
+  API-->>Mini: message item with media URL
+
+  Device->>MQTT: device/{device_id}/event msg_id=005 NFC listen
+  MQTT->>API: MQTT handler receives event
+  API->>Pending: find pending voice for card/device
+  API-->>MQTT: device/{device_id}/event_resp with audio URL(s)
+  MQTT-->>Device: Play pending audio
+  API->>Pending: mark delivered / increment delivery count
+```
+
+## Device / Child Voice Into IM
+
+```mermaid
+flowchart TD
+  Device["Device short press / voice upload\nmsg_id=011 or compatibility path"]
+  MQTT["TalkingQMQTTService"]
+  Upload["Audio upload / archive service"]
+  Resolve["Resolve bound owner and child\nfrom device_bindings"]
+  IM["IM service"]
+  Tables["im_conversations\nim_messages"]
+  Mini["banban-mini chat list/detail"]
+
+  Device --> MQTT --> Upload --> Resolve --> IM --> Tables
+  Tables -->|GET chat APIs| Mini
+```
+
+## Audio Domain Notes
+
+```mermaid
+flowchart LR
+  Message["im_messages.media_file_key"]
+  Presenter["present_message_item / chat service"]
+  URL["mediaUrl returned to mini-program"]
+  Player["Taro InnerAudioContext"]
+  COS["COS downloadFile legal domain"]
+
+  Message --> Presenter --> URL --> Player
+  URL --> COS
+```
+
+## Source Anchors
+
+- Chat detail recording/playback: `banban-mini/src/pages/chat/detail/index.tsx`
+- Chat service client: `banban-mini/src/services/chat.ts`
+- Backend IM service and DAO: `talkingq-url/banban/service/im.py`, `talkingq-url/banban/dao/im.py`
+- Audio upload and COS: `talkingq-url/handlers/audio_file_handler.py`, `talkingq-url/banban/service/device_audio_cache.py`
+- Pending voice table: `database/talkingq_shared_schema.sql`