SDD

04-database-design.md

type: "system_design_document"
title: "資料庫設計"
description: "MockExam 專案的詳細資料庫架構、結構描述設計、安全規則與同步策略。"
audience: ["AI Agents", "Human Developers"]

資料庫設計規格書

概述

本文件詳細說明 MockExam 開源專案的資料庫架構。其設計目的在於同時服務 AI 代理（作為可解析的架構定義）與人類工程師（提供架構脈絡）。

[!NOTE]
此通用架構支援任何認證考試。例如，在 CCNA 題庫應用中，資料庫結構可以輕鬆容納網路拓撲、子網路問題、路由器設定等考題，但整體設計是完全無關特定廠商的 (vendor-agnostic)。

1. 資料庫選擇與角色定位

應用程式採用多資料庫架構，以滿足不同的營運需求：

1. Firebase RTDB: 作為即時同步層與主要的使用者元資料儲存區。負責處理細粒度的安全規則與輕量級索引節點（如 approvedKeys），以降低記憶體佔用。
2. Supabase PostgreSQL: 主要的關聯式儲存區。利用 pgvector 儲存 AI 嵌入向量（支援語意搜尋），並強制執行嚴格的資料列層級安全 (RLS)。作為繁重運算查詢的記錄系統。
3. MongoDB Atlas: 作為行動裝置 (Android/iOS) 直連的文件儲存區，並為 Web 客戶端提供 Cloudflare Worker 代理。非常適合靈活的類 JSON 題目結構。
4. PowerSync (SQLCipher): 提供本地優先 (Local-first) 的加密離線快取。使用基於角色的同步儲存桶 (sync buckets)，確保使用者只下載授權存取的題目。

決策矩陣

2. Firebase RTDB 結構描述

即時資料庫的結構旨在避免深層資料巢狀，最佳化查詢效能。

結構定義

• users/{uid}

  • username (String): 使用者顯示名稱。
  • role (String): 列舉值 admin | viewer | pending | internalTester | publicTester | guest。
  • picture (String): 頭像 URL。
  • expiryDate (String/Timestamp): 帳號或訂閱到期日。
  • activeDeviceId (String): 目前綁定的裝置識別碼。
  • allowedPlatforms (List): 例如 ["android", "ios", "web"]。
  • allowedDatabases (List): 使用者可切換的資料庫。
  • requireBioAuth (Boolean): 生物辨識強制標記。
  • premiumProductId (String): 目前啟用的訂閱層級。
  • premiumPurchaseDate (Timestamp): 購買日期。
  • showTestAds (Boolean): 內部測試人員是否顯示測試廣告。

• examsMetadata/{examId}

  • id (String): 測驗識別碼。
  • vendor (String): 例如 "Cisco", "AWS"。
  • title (String): 測驗標題。
  • lastUpdated (Timestamp): 最後修改日期。
  • questionCount (Number): 題庫總題數。
  • isApproved (Boolean): 顯示開關。

• {examId}/{questionKey}

  • 標準 Question 模型欄位：id, examId, type (SINGLE_CHOICE, MULTIPLE_CHOICE, DRAG_AND_DROP, SIMULATION), title, options, correctAnswer, explanation, topic, isApproved, images, learnEnglish, videoUrl, videoStatus。在網路考題中，主題 (topic) 可能涵蓋路由器、交換器、IP 位址與預設閘道等。

• approvedKeys/{examId}/{questionId}

  • boolean: 輕量級索引。原因：防止低階 Android 裝置在獲取大量考題清單時發生 JVM 記憶體不足 (OOM)。客戶端先獲取這些鍵值，再進行分頁獲取完整物件。

• discussions/{examId}/{questionId}

  • 特定問題的評論討論串。

• restrictedDefaults

  • 角色的系統預設值：例如 {"watermarkOpacity": {"admin": 0.0, "guest": 0.8}}。

• systemConfig

  • 動態設定，如 defaultProvider 與全域維護模式。

• transactions/{uid} 與 systemTransactions/{transactionId}

  • 付款驗證與歷史紀錄。

• testAdDeviceIds

  • 授權接收測試廣告的裝置識別碼清單。

3. Firebase 安全規則 (database.rules.json)

安全架構強制執行零信任資料存取。

詳細規則解析

• users 節點:
  • 寫入: 僅限管理員 (auth.token.admin == true)，限制對 role, expiryDate, allowedPlatforms 的修改。
  • 讀取: 僅限自身讀取 ($uid === auth.uid)，管理員則具備全域讀取權限。
• {examId} 節點:
  • 索引: .indexOn": "isApproved"。
  • 依角色讀取:
    • admin / viewer / internalTester: 讀取全部。
    • publicTester / pending: 僅在 data.child('isApproved').val() == true 時讀取。
    • guest: 僅在 isApproved == true 且 questionNumber <= 10 時讀取。
• 單一題目讀取:
  • 在項目層級評估上述相同條件。
• discussions 節點:
  • guest: 完全排除（無讀寫權限）。
  • pending: 存取權限取決於待定使用者的 restrictedDefaults 設定旗標。
• restrictedDefaults / approvedKeys / systemConfig:
  • 讀取: 所有已驗證使用者。
  • 寫入: 僅限管理員。

4. Supabase PostgreSQL 結構描述

Supabase 負責關聯式映射與向量嵌入。

核心資料表

• questions
  • 包含標準欄位 + embedding vector(768) 用於相似度搜尋。
  • learn_english (Boolean)
  • video_url (Text)
  • video_status (Enum)

RLS 政策 (Row Level Security)

• 讀取: 基於 JWT 聲明的角色讀取。管理員讀取全部；公開使用者讀取 isApproved = true。
• 寫入: 嚴格僅限管理員（透過 JWT 驗證）。

觸發器與邊緣函數 (Edge Functions)

• 觸發器: tr_profile_update_protection 防止使用者在 auth.users 資料表中直接修改其 JWT 角色或敏感元資料。
• 邊緣函數:
  • generate-exam-video（在參考實作中為 generate-ccna-video）
  • get-db-secret
  • get-question / get-question-list
  • manage-discussion / manage-question
  • migrate-from-mongodb

資料庫遷移 (Migrations)

資料庫利用 8 個遷移步驟，從最初的資料表建立、啟用 pgvector，一直發展到最終的影片元資料支援。

5. MongoDB Atlas 結構描述

MongoDB 的架構設計為文件導向的備用方案與 Web API 後端。

• Questions 集合: 直接對應至 Dart Question 模型欄位。
• Discussions 集合: 巢狀評論子文件。
• Web 架構: 由於 MongoDB 直連驅動程式無法在 Web 上無縫運作，因此部署了 Cloudflare Worker API 代理。Web 客戶端呼叫 Worker，由 Worker 處理驗證並安全地與 MongoDB 互動。

6. PowerSync 結構描述與同步規則

PowerSync 透過加密的 SQLite 資料庫提供離線優先功能。

powersync_rules.yaml 詳細資訊

• Bucket (儲存桶): questions_by_role
  • 利用 token_parameters.role 決定同步範圍。
  • 特權角色 (admin, viewer, internalTester): 同步 SELECT * FROM questions。
  • 標準角色 (pending, publicTester): 同步 SELECT * FROM questions WHERE isApproved = true。
  • 訪客角色 (guest): 同步 SELECT * FROM questions WHERE isApproved = true AND questionNumber <= 10。
• Bucket (儲存桶): discussions
  • 完全排除 guest 角色同步討論，以節省本機儲存空間並強制執行限制。

7. Repository Factory 路由邏輯

應用程式使用工廠模式 (Factory Pattern) 動態路由資料請求。

flowchart TD
    A["請求資料 (examId)"] --> B{"是否為 Mock Repository?"}
    B -- 是 --> C["回傳 Mock Repository"]
    B -- 否 --> D{"usePowerSync 或\nexamId 包含 'powersync'?"}
    
    D -- 是 --> E["回傳 PowerSync Repository"]
    D -- 否 --> F{"examId 開頭為 'mongodb-'?"}
    
    F -- 是 --> G["回傳 MongoDB Repository"]
    F -- 否 --> H{"examId 開頭為 'supabase-'?"}
    
    H -- 是 --> I["回傳 Supabase Repository"]
    H -- 否 --> J{"檢查 _defaultProvider\n(systemConfig)"}
    
    J -- "firebase" --> K["回傳 Firebase Repository"]
    J -- "supabase" --> I
    J -- "mongodb" --> G
    J -- "powersync" --> E

透過管理員面板控制動態提供者切換，經由 systemConfig 廣播更新，無需更新應用程式即可將使用者無縫轉移至不同資料庫。

8. 跨資料庫同步策略

為了維持 4 個資料儲存區之間的一致性，我們採用了持續同步策略。

flowchart LR
    Admin["管理員面板"] -->|寫入| Supabase["Supabase (主節點)"]
    
    Supabase -->|Python 指令碼\nsync_supabase_to_firebase.py| Firebase["Firebase RTDB"]
    Supabase -->|同步指令碼| MongoDB["MongoDB Atlas"]
    
    Supabase <-->|雙向同步\n(背景)| PowerSyncService["PowerSync 服務"]
    PowerSyncService <-->|SQLCipher 加密| LocalSQLite["本機 SQLite (客戶端)"]
    
    Client["行動裝置客戶端"] -->|即時事件| Firebase

1. Supabase → Firebase RTDB: 排程指令碼 (sync_supabase_to_firebase.py) 將核准的題目與元資料推播至 Firebase 以提供快速讀取存取。
2. Supabase → MongoDB: 透過 Webhooks/Cron 進行 Web 代理管道的同步。
3. PowerSync ↔ Supabase: PowerSync 原生處理雙向同步。本機客戶端變更（例如離線筆記）會排入佇列，並在恢復連線時推播至 Supabase。

05-security-architecture.md

type: "system_design_document"
title: "安全架構"
description: "MockExam 開源專案的全面安全架構、威脅模型與縱深防禦策略。"
audience: ["AI Agents", "Human Developers", "Security Auditors"]

安全架構規格書

概述

本文件詳細說明 MockExam 專案的極致細節安全架構。它詳述了保護優質內容（例如：認證考試題庫）免於智慧財產權盜竊與未授權存取的縱深防禦 (Defense-in-depth) 機制。

[!NOTE]
此安全架構可保護任何認證考試內容的智慧財產權，無論考題是關於雲端架構、程式設計或網路技術（例如，在 CCNA 題庫應用中關於路由器設定或封包分析的考題）。

1. 安全威脅模型

本應用程式旨在減輕考試與教育平台常見的數個關鍵攻擊向量：

• 螢幕擷取 / 錄影 (Screen Capture / Recording): 使用者嘗試截圖或錄製付費考題。
• 螢幕分享 / 投放 (Screen Sharing / Casting): 使用者將畫面分享至外部裝置或遠端工具。
• 裝置竄改 (Device Manipulation): 使用已 Root、越獄 (Jailbroken) 或模擬器裝置來擷取 App 記憶體或規避限制。
• 時間竄改 (Time Manipulation): 更改裝置時間以繞過訂閱到期日。
• 權限提升 (Privilege Escalation): 攔截或修改本機變數，試圖從 guest 升級為 admin 或 premium。
• 資料擷取 (Data Extraction): 擷取 API 金鑰、MongoDB 連線字串或原始 SQLite 資料庫檔案。

2. 安全層級堆疊

縱深防禦策略建立在 10 層以上的堆疊架構之上。

flowchart TD
    subgraph "應用程式安全堆疊"
        A["驗證綁定 (單一裝置 ID)"] --> B["權限驗證 (JWT 與 RTDB 規則)"]
        B --> C["時間服務 (NTP 驗證)"]
        C --> D["API 金鑰服務 (加密儲存)"]
        D --> E["資料庫層級安全 (RLS 與 SQLCipher)"]
        
        subgraph "客戶端環境保護"
            F["Root 與越獄偵測"]
            G["模擬器與 VPN 偵測"]
            H["FLAG_SECURE (防截圖)"]
            I["防螢幕投放 (輪詢偵測)"]
            J["動態浮水印系統"]
            K["Web 專屬 (禁右鍵、防開發者工具)"]
        end
        
        E --> Client["客戶端應用程式"]
        Client -.-> F
        Client -.-> G
        Client -.-> H
        Client -.-> I
        Client -.-> J
        Client -.-> K
    end

3. 裝置安全偵測 (DeviceSecurityService)

DeviceSecurityService 主動對執行階段環境進行特徵分析。

• Root / 越獄偵測 (SafeDevice.isJailBroken): 立即封鎖所有角色的存取。已 Root 的裝置被視為不可信任。
• 模擬器偵測 (SafeDevice.isRealDevice): 立即封鎖所有角色的存取，以防止自動化爬蟲擷取。
• 開發者模式偵測 (SafeDevice.isDevelopmentModeEnable): 封鎖非管理員使用者。（例外：internal_testing 測試通道免除此檢查）。
• 虛擬定位偵測 (SafeDevice.isMockLocation): 封鎖非管理員使用者。
• VPN 偵測 (CheckVpnConnection.isVpnActive()): 封鎖非管理員使用者，以防止地理位置欺騙與網路封包檢查。

環境免除條件:

• Web 平台略過行動裝置專屬檢查。
• 偵錯模式 (Debug mode) 編譯版本略過環境檢查。
• 傳回包含違規清單與多國語言錯誤訊息的 SecurityResult 模型。

4. 螢幕安全保護 (SecureScreenService)

防止資料被視覺化擷取。

• 防截圖 (Anti-Screenshot): 在 Android 上利用原生 MethodChannel 應用 FLAG_SECURE，防止作業系統在截圖或最近使用應用程式切換器預覽中渲染該 App。
• 螢幕分享 / 投放偵測: 實作 3 秒輪詢間隔以偵測次要顯示器或活躍的投放工作階段。若偵測到，則畫面會模糊並暫停。
• 覆疊層 / 點擊劫持保護 (Tapjacking Protection): 確保監控 FLAG_WINDOW_IS_OBSCURED 以防止惡意覆疊層。
• 管理員免除: 管理員角色可繞過防截圖限制，以利於偵錯與內容管理。

5. 動態浮水印系統 (EnhancedSecurityWatermark)

針對作業系統層級防截圖較弱的平台（例如 Web、Desktop），會在整個應用程式上覆蓋動態浮水印。

• Canvas 渲染: 自訂 Flutter 畫布 (Painter)，斜向渲染使用者的 UID 與 Email。
• 依角色設定透明度 (Per-Role Opacity): 可透過 restricted_defaults_screen 設定。
  • 管理員可將透明度設為 0.0 (隱形)。
  • 訪客的透明度可能會設為 0.8 (高度可見)。
• 持久性: 浮水印在 MaterialApp builder 層級注入，確保其涵蓋所有路由、對話方塊與底部選單 (bottom sheets)。

6. NTP 時間驗證 (TimeService)

防止使用者透過手動更改裝置時鐘來繞過訂閱限制。

• NTP 查詢: 使用 NTP.getNtpOffset() 從網路時間伺服器獲取真實時間。
• 回溯偵測 (Rollback Detection): 將目前 NTP 時間與歷史最高時間戳記進行比較。
• 容忍緩衝: 允許 1 分鐘的漂移緩衝以因應網路延遲。
• 持久儲存: 使用 FlutterSecureStorage 儲存 secure_time_last_known 時間戳記。
• 狀態機: 產生 TimeValidationStatus (valid, rollbackDetected, error)。若偵測到時間回溯，則立即鎖定帳號。

7. 單一裝置登入 (Auth Binding)

防止帳號共用。

• 追蹤: activeDeviceId 記錄於 Firebase users/{uid} 中。
• AuthWrapper 比較: 在 7 步驗證鏈期間，AuthWrapper 會檢查裝置的硬體 ID 是否與資料庫相符。
• 不符行為: 強制登出並重新導向至 UnauthorizedScreen (未授權畫面)。
• 重設: 只有管理員有能力重設使用者綁定的裝置 ID。

8. 防止權限提升 (Privilege Escalation Prevention)

針對使用者權限的零信任架構。

• Firebase RTDB 規則: role, expiryDate 與 allowedPlatforms 欄位透過後端規則鎖定。即使客戶端被入侵，也無法寫入這些欄位。
• 建立新使用者: 註冊時，後端僅允許將初始角色設為 pending 或 guest。
• Supabase 觸發器: tr_profile_update_protection 會在使用者嘗試直接在資料庫中更新自己的 JWT 角色聲明或訂閱日期時，明確引發 SQL 例外。

9. 基於角色的安全矩陣

10. Web 平台安全 (WebSecurityWrapper)

由於瀏覽器的開放性，Web 需要特定的 DOM 層級干預。

• 內容選單 (Context Menu): 透過 JS 互操作性原生停用右鍵點擊。
• 文字選取: CSS 與 JS 監聽器完全停用文字選取功能。
• 開發者工具偵測: 數學輪詢以偵測控制台是否開啟（測量視窗與視埠高度差異）。
• 快速鍵封鎖: 攔截並封鎖 Ctrl+S (儲存)、Ctrl+P (列印) 以及 F12 (開發者工具)。

11. API 金鑰安全

保護關鍵基礎設施憑證免受逆向工程攻擊。

• ApiKeyService: 記憶體內快取，持久儲存委派給 FlutterSecureStorage（Android 上為 AES 加密，iOS 上為 Keychain）。
• 金鑰輪替 (Key Rotation): 金鑰可透過 Firebase systemConfig 動態輪替。
• 注入 (Injection): 基礎金鑰在編譯時期透過 --dart-define 注入，完全避免在版本控制中出現硬編碼字串。
• Worker 委派: 高度敏感字串（如 MongoDB 連線 URI、GitHub API Tokens）絕對不會隨附於客戶端。它們僅存在於 Cloudflare Worker 環境中。

12. 跨平台安全支援矩陣

06-ai-engine.md

AI 引擎架構與實作規範

AI 代理程式提醒 (AI Agent Note): 本文件描述 AiGeneratorService 與 GemmaLocalService 類別，此為認證考試平台雙引擎 AI 架構的核心。修改提示詞生成、LLM 整合或本地端推論設定時請參考此文件。

1. AI 引擎架構概覽

本應用程式採用雙引擎 AI 架構，提供高精確度的解析與離線使用的便利性，確保準備任何認證考試（如練習題庫測驗）的使用者，在任何網路狀態下皆能取得 AI 導師的協助。

graph TD
    A["使用者請求 (User Request)"] --> B{"模式選擇 (Mode Selection)"}
    B -- "'cloud' / 'auto'" --> C["AiGeneratorService (雲端 API)"]
    B -- "'local'" --> D["GemmaLocalService (本地端設備)"]
    
    C -- "網路錯誤 (Network Error)" --> E{"允許降級備援? (Fallback Allowed?)"}
    E -- "是 ('auto')" --> D
    E -- "否 ('cloud')" --> F["拋出例外 (Throw Exception)"]
    
    C -- "成功 (Success)" --> G["顯示結果 (Display Result)"]
    D -- "成功 (Success)" --> G

• 雲端 API 服務 (AiGeneratorService): 運用雲端運算（如 Gemini）處理複雜邏輯、動態專家角色建立以及影片腳本生成。
• 本地端引擎 (GemmaLocalService): 提供離線、低延遲且具隱私保護的推論服務，採用輕量級的 LiteRT-LM 模型。
• 自動降級備援機制 (Auto-fallback): 當雲端服務無法連線或發生 API 錯誤時，系統會自動切換至本地端引擎。

2. 雲端 AI 服務 (AiGeneratorService)

雲端服務採用 REST API 整合模式，不綁定特定 SDK，可靈活適配任何 LLM 供應商。

動態專家角色建構 (getDynamicExpertPersona)

根據 examId、topic 與 title 關鍵字動態建構專家角色。

• 舉例來說，在 CCNA 測驗應用中，會初始化為「網路路由/交換/資安專家」。
• 若關鍵字顯示為 Google Cloud 或 Android，則轉換為「GCP 架構專家」。
• 偵測到 AWS、Kubernetes 或程式設計術語時，會自動派發對應領域的專家角色。
• 支援多語系角色樣板 (en, zh_TW, zh_CN, ja)，確保回應自然且符合文化習慣。

解析生成提示詞設計 (Explanation Generation Prompt)

• 輸入 (Input): 題目、選項、正確答案、考試領域。
• 輸出 (Output): 結構化的 Markdown 解析，包含循序漸進的推理過程。

英語學習功能 (generateLearnEnglishForQuestion)

設計用於協助非母語人士理解考試題目。

• 三大單元: grammar_analysis (文法解析)、speedrun_tips (速解技巧)、vocabulary_analysis (單字解析)。
• TTS 發音連結: 使用自訂協定 tts://speak?text=URL_ENCODED_TEXT 呼叫應用程式內建語音。
• 字典與翻譯連結: 劍橋字典使用 [📖] 圖示，Google 翻譯使用 [🌐] 圖示。
• 全形符號安全機制 (Full-width Symbol Safety): 嚴禁在內容主體中使用半形字元如 []()|" 以防 Markdown 解析錯誤，強制替換為全形符號（【】（）｜「」）。
• 五大基本句型: 強制依據 S+V, S+V+O, S+V+C, S+V+IO+DO, S+V+O+OC 進行句構分析。
• 專有名詞: 針對 zh-TW 語系，採用台灣標準英語文法術語。

向量嵌入生成 (Vector Embedding Generation)

生成 768 維度的嵌入表示 (如 Gemini Embeddings) 以提供語意搜尋功能。這些資料儲存於 Supabase 的 pgvector 欄位中，讓使用者能依概念搜尋練習題庫，而非僅限於精確的關鍵字比對。

3. 本地端 AI 引擎 (GemmaLocalService)

提供全離線推論功能。

• 模型規格: gemma-4-E2B-it.litertlm (約 1.7GB)。
• 下載機制: 採用 HTTP 串流下載，透過 StreamController<double> 廣播進度。
• 檔案驗證: 強制檢查檔案大小 > 500MB，確保模型下載完整。
• 安全替換: 下載時存為暫存檔 (.tmp)，成功完成後才重新命名為最終檔名。

LiteRT-LM 引擎初始化

// Initialize LiteRT-LM for Gemma
FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  modelFileType: ModelFileType.litertlm,
  preferredBackend: PreferredBackend.gpu, // Hardware acceleration
  maxTokens: 1024,
);

上下文視窗管理 (Context Window Management) (極度重要)

為避免行動裝置上的 JVM OutOfMemory (OOM) 錯誤，嚴格的上下文管理是必要的。

• 保留限制: 對話歷史紀錄僅保留最後 4 則訊息。
• 字數截斷: 每則訊息最多截斷至 150 個字元。
• 系統提示詞 (System Instruction): 包含題目、選項、正確答案，以及截斷的解析 (最多 150 字元)。
• 連線偵測: 透過 InternetAddress.lookup('google.com') 判斷是否需要觸發備援邏輯。

4. 雙模式切換邏輯 (Dual-Mode Switching Logic)

flowchart TD
    Start["呼叫 getExplanationTutor()"] --> ModeCheck{"檢查請求模式"}
    ModeCheck -- "'cloud'" --> CloudOnly["執行 AiGeneratorService"]
    ModeCheck -- "'local'" --> LocalOnly["執行 GemmaLocalService"]
    ModeCheck -- "'auto' (預設)" --> AutoCloud["執行 AiGeneratorService"]
    
    AutoCloud --> IsSuccess{"是否成功?"}
    IsSuccess -- "是" --> Return["回傳結果"]
    IsSuccess -- "否 (網路/API錯誤)" --> AutoLocal["執行 GemmaLocalService"]
    AutoLocal --> Return

5. 在地化提示詞策略 (Localization Prompt Strategy) (極度重要)

核心原則: 絕對不要在輕量級（如 2B 參數）模型的系統提示詞 (System Instruction) 中混合多種語言。否則會嚴重降低效能，導致模型產生幻覺或以錯誤語言回應。

• 語言偵測: 從 context.locale 取得以設定 _langCode。
• 各語言系統提示詞樣板:
  • en: 嚴格的英文專家角色。
  • zh_TW: 台灣繁體中文。針對網路/IT領域，嚴格使用台灣在地術語（例如：路由器、交換器、封包、子網路、連接埠、IP 位址、預設閘道）。
  • zh_CN: 簡體中文術語。
  • ja: 日文 IT 術語。
• 歡迎訊息: 在建立聊天對話時，根據語言動態在地化歡迎訊息。

6. AI 影片生成管線 (AI Video Generation Pipeline)

1. 腳本生成: 透過雲端 API 依據題目與解析生成影片腳本。
2. 影片合成: 將腳本送交影片合成工作流 (例如 HeyGen, Synthesia API)。
3. YouTube 整合: 透過整合服務自動上傳完成的影片。
4. 狀態機 (videoStatus): 狀態變換流程為 null -> generating -> completed (或 failed)。

7. 翻譯服務 (Translation Service)

• 方法: 使用 translateText() 動態翻譯使用者查詢或特定的練習測驗內容。
• 優先級: 首選雲端 API (Gemini/OpenAI) 進行高品質的語境翻譯。
• 備援: 若離線，則備援至本地端引擎 (Gemma 4)。
• 支援方向: en ↔ zh_TW, zh_CN, ja。