10-ui-components.md

UI 元件 (UI Components)

1. 系統概述 (AI Agent Context)

本文件概述了認證考試 (certification exam) 應用程式的 UI 元件清單與架構。它將可重複使用的元件分類，並詳細說明其內部狀態、屬性以及在應用程式中的具體角色。

2. 元件清單 (Component Inventory)

核心元件 (Core Widgets)

• QuestionOptionsWidget (48.7 KB): 渲染單選或複選選項，並包含各種互動狀態。
  • 屬性 (Props): question, selectedAnswers, isSubmitted, onAnswerSelected
  • 狀態 (States): default (預設), selected (已選), correct (正確), incorrect (錯誤), disabled (停用)
  • 複選 (Multiple choice): 實作核取方塊 (checkbox) 樣式的多選邏輯。
• QuestionView (7.7 KB): 顯示題目主標題與相關媒體。
  • 處理富文本 (rich text) 渲染、Base64 內嵌圖片以及網路圖片。
  • 包含題型指示器標籤。
• DiscussionWidget (12.0 KB): 提供具備 CRUD 功能的留言討論介面。
  • 顯示留言列表及按讚按鈕。
  • 包含新增留言表單。
  • 實作基於角色的存取控制（排除 guest 訪客使用者）。

考試專用元件 (Exam-Specific Widgets - widgets/exam/)

• AiTutorPanel (45.4 KB): 側邊抽屜式的聊天面板，提供對話式 AI 輔助。
  • 模式選擇器 (自動 / 雲端 / 本機端)。
  • 支援 Markdown 渲染的聊天記錄。
  • 包含發送按鈕的輸入欄位。
  • 匯出為 .md 檔案的功能，用於儲存對話。
  • 根據當前語系進行語言感知的上下文初始化。
• ExplanationView (60.8 KB): 多頁籤式的題目解析顯示介面。
  • Markdown 渲染的解析文字。
  • 多語言解析的語言頁籤（例如 EN/ZH）。
  • 內嵌 AI 產生器對話方塊，用於處理缺失的解析。
  • 影片播放器整合。
• AiVideoGeneratorWidget (27.8 KB): 用於生成及預覽 AI 影片內容的介面。
• ResultComparisonView (14.4 KB): 顯示使用者答案與正確答案的視覺化比較。
• QuestionExportView (12.4 KB): 處理將題目及其詳細資訊匯出為 Markdown 或 PDF。
• TutorVideoPlayer (8.9 KB): 專為 AI 輔導影片量身打造的自訂影片播放器。
• FullScreenVideoPage (6.3 KB): 全螢幕影片播放覆疊頁面。
• PlatformImageIo/Web: 圖片載入的跨平台抽象層（處理 Web 與 Native 平台的限制）。
• AudioContextHelper: 音訊上下文與播放工作階段的跨平台管理。

安全防護元件 (Security Widgets)

• EnhancedSecurityWatermark (5.9 KB): 產生基於 Canvas 的動態浮水印，包含使用者 ID，以嚇阻螢幕錄影與分享行為。
• SecurityWatermark (4.0 KB): 用於標準安全需求的基本覆疊式浮水印。
• GlobalErrorBoundary (4.8 KB): 全域錯誤捕捉 UI，包覆整個應用程式以防止未處理的 UI 例外造成嚴重的崩潰 (crashes)。
• WebSecurityWrapper (4.0 KB): 停用右鍵單擊和 DOM 檢查工具，提供基本的 Web 防網頁爬蟲 (anti-scraping) 保護。

廣告元件 (Advertising Widgets)

• BannerAdWidget (4.2 KB): 整合 AdMob 橫幅廣告，具備健全的錯誤處理和備用 UI。
• NativeAdCardWidget (2.9 KB): 在內容動態消息中無縫顯示原生廣告。
• WebAdView/Stub: 用於 Web 平台編譯時安全地替換 (stub) 或處理廣告視圖的轉接器 (adapters)。

3. 元件架構模式 (Widget Architecture Patterns)

• StatelessWidget 與 StatefulWidget 的使用指南: 當狀態由外部管理時（例如透過 Provider），優先使用 StatelessWidget。StatefulWidget 嚴格保留用於本機 UI 狀態（例如動畫、捲動控制器或暫時的輸入欄位）。
• Consumer / Selector: 廣泛用於將 UI 元件綁定至 ChangeNotifier 的更新。Selector 用於監聽特定屬性，以將不必要的重建降至最低，維持高效能。
• 基於鍵值的識別 (Key-based Identity): 將 ValueKey 或 ObjectKey 應用於列表中的項目（如選項或留言），以確保在列表變動期間有最佳的渲染效能與狀態保存。

11-automation-scripts.md

自動化腳本 (Automation Scripts)

1. 系統概述 (AI Agent Context)

本文件描述了在認證考試 (certification exam) 專案中使用的各種自動化腳本，這些腳本旨在簡化資料庫管理、部署、AI 生成以及程式碼維護工作。

2. Python 腳本

classify_questions_ai.py (~25 KB)

• 用途: 利用 AI 自動將未分類的題目歸類到特定領域。
• 先決條件: Python 3.9+、google-generativeai、supabase、pymongo、requests。
• 用法: python scripts/classify_questions_ai.py
• 運作方式:
  1. 從 Supabase 擷取未分類的題目（例如套用 topic=1 過濾器）。
  2. 對照本機快取 (classified_ids.json) 檢查，防止重複處理。
  3. 將題目內容連同特定的分類提示 (prompt) 傳送至 Gemini API。
  4. 將結果寫回 Supabase、MongoDB 以及 Firebase RTDB。
  5. 更新本機快取。
• 設定: 需要在 .env 中提供 API 金鑰和資料庫憑證。
• 速率限制 (Rate Limiting): 內建 API 呼叫之間的延遲，以遵守配額限制。
• 恢復功能: classified_ids.json 快取可讓腳本在中斷後安全地從上次的位置重新啟動。

generate_ai_explanations.py (~43 KB)

• 用途: 批次產生題庫的多語言 AI 解析。
• 產生內容: 建立解析文字和 learn_english 分析。
• 支援功能: 增量產生，跳過已產生解析的題目。
• 輸出: 更新 Supabase 記錄並將變更同步至 Firebase。

generate_question_embeddings.py (~11 KB)

• 用途: 產生 768 維的向量嵌入 (vector embeddings)，以支援語意搜尋功能。
• 模型: Gemini Embeddings。
• 儲存: 將向量儲存至 Supabase 的 pgvector 欄位，以進行快速的餘弦相似度 (cosine similarity) 查詢。

sync_supabase_to_firebase.py (~12 KB)

• 用途: 促成從 Supabase PostgreSQL 資料庫到 Firebase RTDB 的零成本資料同步。
• 欄位映射 (Field Mapping): 自動將 snake_case 資料庫欄位轉換為 camelCase JSON 屬性。
• 包含項目: 產生 approvedKeys 索引節點，以最佳化客戶端擷取效能。

deploy_play_store.py (~13 KB)

• 用途: 使用 Google Play Developer API 進行自動化 Google Play 商店部署。
• 必備條件: play-store-credentials.json, service-account.json。
• 發布軌道 (Tracks): 支援推播至內部測試 (Internal)、封閉測試 (Closed) 和正式版 (Production) 軌道。

實用工具腳本

• delete_anonymous_auth.py (~4 KB): 清理過期的匿名 Firebase Auth 帳戶，以維護資料庫衛生。
• get_latest_version.py / get_active_releases.py: 查詢 Google Play 商店以管理並自動遞增應用程式版本。

3. PowerShell 腳本

這些腳本主要在 Windows 環境中用於建置自動化。

• build_aab_internal.ps1: 建置 Android 應用程式套件 (AAB) 並部署至內部測試軌道。
• build_aab_closed.ps1: 建置 AAB 並部署至封閉測試軌道。
• build_aab_production.ps1: 建置 AAB 並部署至正式版軌道。
• build_web.ps1 / build_web_internal.ps1: 編譯 Flutter Web 應用程式。
• 功能: 所有建置腳本均支援 -AutoY（略過手動確認）和 -AutoDeploy（自動上傳至 Play 商店）。
• 版本自動遞增: 內部呼叫 get_latest_version.py，以確保建置前有正確的版本號。

4. Node.js 腳本

• check_supabase_coverage.js: 驗證 Supabase 實例中的資料涵蓋範圍和完整性。
• generate_pages.js / generate_static_notes.js: 處理靜態網站產生，用於文件或基於網頁的筆記。
• sync_explanations.js: 在不同環境之間同步解析資料。

5. Dart 移轉腳本

• migrate_to_supabase.dart / migrate_direct_dart.dart: 用於將資料從 MongoDB 移轉至 Supabase 的公用腳本。
• fix_mongodb_exam_ids.dart / diagnose_mongodb.dart: 用於 MongoDB 資料庫維護和資料修復的工具。

6. 腳本環境需求

執行此自動化套件，主機電腦必須具備：

• Python 3.9+ 及所需的 pip 套件。
• Node.js 18+ 及所需的 npm 套件。
• PowerShell 7+（用於 Windows 建置腳本）。
• 針對每個腳本特定的資料庫和 API 連線，設定適當的環境變數 (.env)。