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

Voice And IM Flow

Parent Voice Message To Device

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

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

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