Yibi AI 故事機系統架構 (System Architecture)

版本: 1.2 | 日期: 2026-06-15（裝置通訊改 HTTPS event-driven，移除 MQTT/EMQX，對齊 ADR-0010）依據: E01-E17 Feature Specifications；裝置通訊依 ADR-0010（drop MQTT for HTTPS events + offline-first）

註：圖中部分 feature 編號為舊版（早於 openspec ENN 重編號），對應現況以 docs/openspec/specs/ 為準。

1. 系統架構圖

                                  [ 使用者與裝置層 ]
          +--------------------------------------------------------------------------+
          |                                                                          |
          |   父母端 (Parents) — 主要介面                           孩子與硬體           |
          |  +----------------+      +----------------+      +------------------+    |
          |  | Mobile (Flutter|      | Web (React)    |      |  IoT Device      |    |
          |  | iOS/Android)   |      | (E01,E02,E06)  |      |  (E07, E08)      |    |
          |  | (E10 - 主要)   |      | (補充操作)      |      |                  |    |
          |  +-------+--------+      +--------+-------+      +---------+--------+    |
          |          |                        |                        |             |
          +----------|------------------------|------------------------|-------------+
                     | REST API (HTTPS)       | REST API (HTTPS)       | HTTPS events + WSS
                     v                        v                        v
          +--------------------------------------------------------------------------+
          | [ 邏輯與 API 層 - Backend (FastAPI) ]                                    |
          |                                                                          |
          |  +--------------------------------------------------------------------+  |
          |  |  API Gateway / App Server                                          |  |
          |  |  - Auth & Multi-tenant Isolation (E01)                              |  |
          |  |  - Child Profiles & Onboarding (E02)                                |  |
          |  |  - Content Library & Audio Proxy (E06)                             |  |
          |  |  - Device & Token Management (E07)                                 |  |
          |  |  - Admin CMS (E11)                                                 |  |
          |  +----------------------------------+---------------------------------+  |
          |                                     |                                    |
          |  +----------------------------------v---------------------------------+  |
          |  |  Generation Job Worker (Celery)                                    |  |
          |  |  - Story Engine (E03): Gemini LLM + Google TTS                     |  |
          |  |  - Music Engine (E04): Gemini LLM + Mureka API                     |  |
          |  |  - Activity Engine (E05): Gemini LLM                               |  |
          |  |  - E12 Milestones Enrichment (Developmental Science)               |  |
          |  +--------------------------------------------------------------------+  |
          |                                                                          |
          +------------------+------------------+-------------------+----------------+
                             |                  |                   |
          +------------------|------------------|-------------------|----------------+
          | [ 基礎設施與儲存層 ]                 |                   |                |
          |                                     |                   |                |
          | +-------------------+      +--------v----------+      +-v--------------+ |
          | | PostgreSQL 16     |      | Redis 7           |      | GCS / Local FS | |
          | | (Relational Data) |      | (Real-time Status)|      | (MP3 Files)    | |
          | +-------------------+      +-------------------+      +----------------+ |
          |                                                                          |
          | +-------------------+      +-------------------+      +----------------+ |
          | | Device Events     |      | Firebase (FCM)    |      | External APIs  | |
          | | (HTTPS -> API)    |      | (Push Notify)     |      | (Gemini,Mureka)| |
          | +-------------------+      +-------------------+      +----------------+ |
          +--------------------------------------------------------------------------+

          [ 開發工具 ]
          +-------------------------+
          | IoT Simulator (Go)      |
          | (E09 - 模擬裝置行為)      |
          +-------------------------+

2. 分層說明

2.1 使用者與裝置層 (User & Device Layer)

Mobile App (Flutter) — 主要介面: 年輕家長幾乎全程透過手機管理孩子內容，為 App-first 策略的核心。支援帳號管理、孩子檔案設定、內容瀏覽播放、QR Code 掃描綁定裝置、遠端播放控制及推播通知 (FCM)。
Web Portal (React + TypeScript): 補充操作介面，提供桌面端帳號管理與內容瀏覽，使用情境較少。
IoT Device (電容觸控 + WiFi): 實體故事機，透過電容觸控物件查詢播放清單，並以 HTTPS POST /events 上報狀態、於回應取得雲端待辦指令 (pending_actions)；live-chat 期間改用 WSS 雙向通訊。offline-first，無 broker 依賴。

2.2 邏輯與 API 層 (Application Layer)

FastAPI Backend:
- 多租戶隔離: 以「家庭 (Family)」為最小隔離單位，JWT 認證中包含 family_id。
- 音訊代理 (Audio Proxy): 透過後端串流 GCS 音訊，保護原始儲存路徑並統一權限檢查。
- 內容 CMS: 管理自製 (Curated) 與授權 (Licensed) 內容，並負責工廠出貨前的裝置預註冊 (CSV Import)。
Job Worker (Celery):
- 採用 Celery 分散式任務佇列，API Server 下達任務到 Redis，Worker 獨立執行。處理耗時較長的 Gemini 文本生成、TTS 語音合成及 Mureka 音樂生成任務，支援任務重試與橫向擴展。

2.3 生成引擎層 (AI Engines & Science)

E03/E04/E05 Engines: 核心 AI 生成邏輯，將孩子偏好轉換為結構化 Prompt。
E12 Developmental Milestones: 發展科學資料層，根據月齡自動調整語言複雜度與發展目標建議，動態強化 (Enrich) Prompt 品質。

2.4 基礎設施與儲存層 (Infrastructure Layer)

PostgreSQL: 核心關聯式資料庫，儲存使用者、家庭、孩子、裝置、Token 及統一內容表 (contents)。
Redis: 用於任務進度查詢、裝置在線狀態 (由 HTTPS 事件更新的 TTL)。
Google Cloud Storage (GCS): 目前 production 儲存所有音訊檔案 (MP3)，供 Web Proxy 與裝置 Signed URL 下載使用（STORAGE_PROVIDER=gcs）。
- 規劃中的雙軌策略 (ADR-0014, proposed): 公開共享內容（source_type curated/licensed）目標改用 Cloudflare R2 + CDN（零 egress，公開 URL）；family 私有內容（ai_generated / ai_custom）維持 GCS Signed URL。路由依「公開 vs 私有」非「AI 生成 vs 人工」。R2 provider 已實作但尚未上線（待 issue #368/#369）。見 docs/adr/0014-media-storage-r2-for-curated-gcs-signed-for-ugc.md。
裝置通訊 (HTTPS Event-Driven): 裝置以 HTTPS POST /events 上報狀態並於回應取得 pending_actions；live-chat 期間以 WSS 低延遲雙向通訊。offline-first 設計，無 MQTT broker（ADR-0010 起 EMQX 已退役）。

3. 關鍵數據流 (Key Data Flows)

內容生成流: 父母設定偏好 → 觸發 Job → Worker 呼叫 Gemini/Mureka → 儲存至 contents 表 → 裝置下次 POST /events 時於回應取得 sync pending_action。
播放控制流: 父母點擊 Web 播放按鈕 → REST API 寫入 pending_action → 裝置下次 POST /events 於回應取得指令 → 從 GCS 下載音訊。
實體觸發流: 孩子放上觸控物件 → 裝置讀取電容觸控物件 ID → 向 API 查詢 playlist → 取得 GCS Signed URL → 開始播放。

4. 技術選型摘要

面向	選擇	理由
後端框架	FastAPI	非同步效能優異，與 Python AI 生態系整合度高
資料庫	PostgreSQL 16	支援 JSONB 彈性擴展，處理多租戶關聯穩定
裝置通訊	HTTPS Event-Driven + WSS	offline-first，無 broker 依賴；裝置主動 `POST /events` 取得 pending_actions，live-chat 用 WSS 低延遲（ADR-0010）
AI 模型	Gemini 2.0 Flash	結構化輸出 (JSON Mode) 強大，中文敘事品質優
音訊合成	Google Cloud TTS	聲音自然，支援多角色音色標記
音樂合成	Mureka API	專注兒童音樂生成，API 成熟

Yibi AI 故事機系統架構 (System Architecture)

On this page