01-design-system.md

UI/UX 設計系統

1. 色彩系統

MockExam 應用程式採用基於 Material Design 的色彩系統。

• 主要色彩 (Primary): Material 藍色/靛藍色調 (#3F51B5 / #2196F3)。用於主要操作、應用程式列和活動狀態。
• 次要色彩 (Secondary): 藍綠色/綠色 (#009688 / #4CAF50)。用於成功狀態、正確答案和正面回饋。
• 錯誤色彩 (Error): 紅色調 (#F44336)。用於錯誤答案、錯誤訊息和破壞性操作。
• 表面色彩 (Surface):
  • 淺色模式: #FFFFFF 用於卡片，#F5F5F5 用於背景。
  • 深色模式: #1E1E1E 用於卡片，#121212 用於背景。
• 角色專屬點綴色:
  • 系統管理員 (Admin): 紫色 (#9C27B0)
  • VIP/進階會員: 琥珀色/金色 (#FFC107)
  • 測試人員: 橘色 (#FF9800)

2. 字體排版

字體排版遵循平台預設，以實現最大可讀性和在地化支援 (特別是繁體中文)。

• 字體家族: 系統預設 (例如 Android 上的 Roboto/Noto Sans TC，iOS 上的蘋方)。
• 尺寸縮放:
  • 12sp: 說明文字、小型次要文字
  • 14sp: 內文、次要清單項目
  • 16sp: 主要內文、考題內容
  • 18sp: 副標題、按鈕文字
  • 20sp: 對話框標題、AppBar 標題
  • 24sp: 標題
  • 32sp: 大型顯示數字 (如分數、倒數計時器)
• 字重:
  • 標準 (400) 用於內文
  • 中等 (500) 用於按鈕和副標題
  • 粗體 (700) 用於標題和關鍵指標

3. 間距與網格

應用程式使用 8px 基礎網格系統以確保對齊的一致性。

• 標準內距 (Padding): 8px (微小), 12px (緊湊), 16px (標準), 24px (擴展), 32px (大型)。
• 卡片外距 (Margin): 8px (密集清單) 或 16px (獨立卡片)。
• 版面外距: 標準行動裝置螢幕使用 16px 水平外距。

4. 元件庫

標準化元件確保視覺一致性並加速開發。

按鈕 (Buttons)

• ElevatedButton: 主要操作 (例如「提交試卷」、「購買進階版」)。
• TextButton: 次要操作 (例如「取消」、「略過」)。
• OutlinedButton: 替代操作 (例如「複習錯題」)。
• IconButton: 工具列、應用程式列和內聯操作。

卡片 (Cards)

• QuestionCard: 顯示考題及其選項。
• ExamCard: 顯示模擬考詮釋資料 (供應商、領域、題數)。
• StatCard: 顯示儀表板指標 (總作答數、正確率)。

對話框 (Dialogs)

• AlertDialog: 標準確認或警告訊息。
• ConfirmDialog: 雙操作對話框 (是/否)。
• InputDialog: 需要使用者輸入文字的對話框 (例如自訂模擬考設定)。

提示列 (SnackBar)

• 成功: 綠色背景，用於成功操作 (例如「設定已儲存」)。
• 錯誤: 紅色背景，用於失敗 (例如「網路錯誤」)。
• 資訊: 深灰色/藍色背景，用於中性更新。

底部表單 (BottomSheet)

• 設定 (Settings): 快速調整設定。
• 匯出 (Export): 匯出資料的選項。
• 篩選 (Filter): QuestionSearchScreen 的進階篩選選項。

02-screen-specifications.md

畫面規格

本文件概述了認證考試題庫應用程式中的 26 個主要畫面。

1. LoginScreen (登入畫面)

• 路由: /login
• 目的: 驗證使用者身分。
• 版面配置: 頂部標誌，置中登入按鈕 (Google/Email/訪客)，底部有隱藏的審查員模式切換。
• 元素: 登入提供者按鈕、審查員模式切換 (長按標誌顯示)。
• 資料: Firebase Auth。
• 導航: 成功後前往 AuthWrapper。
• 角色: 所有未驗證使用者。

2. AuthWrapper (驗證包裝器)

• 路由: /wrapper (隱藏)
• 目的: 執行 7 步驟驗證鏈的中央安全閘道。
• 版面配置: 無 (顯示啟動畫面或載入動畫)。
• 元素: CircularProgressIndicator。
• 資料: AppUser 狀態、裝置資訊、安全服務。
• 導航: 前往 DashboardScreen、UnauthorizedScreen 或特定的封鎖畫面。
• 角色: 所有使用者。

3. DashboardScreen (儀表板畫面)

• 路由: /dashboard
• 目的: 考試選擇、統計數據和個人資料的主中心。
• 版面配置: 頂部應用程式列包含個人資料，橫向統計卡片，垂直可用領域/考試清單，浮動管理員操作按鈕。
• 元素: StatCard, ExamCard, BottomNavigationBar。
• 資料: 使用者進度、可用考試。
• 導航: 前往 ExamListScreen, MockExamSetupScreen, NotesListScreen。
• 角色: admin, viewer, internalTester, publicTester (Pending/Guest 受限)。

4. ExamListScreen (考試清單畫面)

• 路由: /exam-list
• 目的: 顯示供練習的主題或領域 (如 Domain 1-6)。
• 版面配置: 帶有進度指示器的主題 ListView。
• 元素: 帶有 LinearProgressIndicator 的 ListTile。
• 資料: 考試分類儲存庫。
• 導航: 前往 ExamScreen。
• 角色: 所有已驗證使用者 (Guest 受限)。

5. ExamScreen (考試畫面)

• 路由: /exam
• 目的: 核心練習介面。
• 版面配置: 可捲動的考題文字、選項清單、操作列 (提交/下一題)，以及隱藏的 AI 家教抽屜。
• 元素: QuestionCard、選項核取方塊/單選按鈕、可展開的解析、AI 家教抽屜。
• 資料: 考題儲存庫、AI 服務。
• 導航: 返回 ExamListScreen。
• 角色: 所有有效角色。

6. MockExamSetupScreen (模擬考設定畫面)

• 路由: /mock-setup
• 目的: 設定計時模擬考。
• 版面配置: 包含題數、時間限制和資料庫來源選擇之滑桿/輸入框的表單。
• 元素: 滑桿、下拉選單、開始按鈕。
• 資料: 本機設定。
• 導航: 前往 MockExamScreen。
• 角色: admin, viewer, internalTester。

7. MockExamScreen (模擬考畫面)

• 路由: /mock-exam
• 目的: 具有嚴格計時器的完整考試模擬。
• 版面配置: 固定頂部列顯示倒數計時器、考題內容、分頁底部列。
• 元素: 計時器小工具 (僅數字重建)、考題 UI。
• 資料: 選定的考試題目。
• 導航: 結束後前往 MockExamReportScreen。
• 角色: admin, viewer, internalTester。

8. MockExamReportScreen (模擬考報告畫面)

• 路由: /mock-report
• 目的: 顯示模擬考後的分數和分析。
• 版面配置: 頂部大型圓形分數、按領域劃分的細項、待複習考題清單。
• 元素: 圓形百分比指示器、長條圖、ListView。
• 資料: 模擬考結果。
• 導航: 返回 DashboardScreen 或 ExamScreen (複習模式)。
• 角色: admin, viewer, internalTester。

9. WrongQuestionsReviewScreen (錯題複習畫面)

• 路由: /wrong-questions
• 目的: 複習答錯的考題。
• 版面配置: 可篩選的錯題清單。
• 元素: 篩選晶片、考題摘要卡片。
• 資料: 使用者歷史記錄資料庫。
• 導航: 前往 ExamScreen (特定考題)。
• 角色: admin, viewer, internalTester。

10. QuestionSearchScreen (考題搜尋畫面)

• 路由: /search
• 目的: 考題的多重篩選和向量搜尋。
• 版面配置: 搜尋列、篩選晶片列、搜尋結果清單。
• 元素: TextField, FilterBottomSheet, 醒目提示文字結果。
• 資料: 向量資料庫 / 本機搜尋索引。
• 導航: 前往 ExamScreen。
• 角色: VIP/Premium, admin。

11. QuestionEditorScreen (考題編輯器畫面)

• 路由: /admin/editor
• 目的: 考題的管理員 CRUD 操作。
• 版面配置: 複雜的表單，包含文字編輯器、圖片上傳器、選項切換。
• 元素: TextFormFields, ImagePicker, ReorderableList。
• 資料: 考題資料庫 (寫入)。
• 導航: 返回 DashboardScreen。
• 角色: admin。

12. UserManagementScreen (使用者管理畫面)

• 路由: /admin/users
• 目的: 管理員使用者管理。
• 版面配置: 帶有搜尋功能的使用者資料表或清單。
• 元素: 搜尋列、使用者清單、角色下拉選單、封鎖按鈕。
• 資料: AppUser 資料庫。
• 導航: 無。
• 角色: admin。

13. RestrictedDefaultsScreen (受限預設設定畫面)

• 路由: /admin/settings
• 目的: 管理員系統設定。
• 版面配置: 包含全域功能切換開關的表單。
• 元素: SwitchListTile、儲存按鈕。
• 資料: 遠端設定 / 系統設定。
• 導航: 無。
• 角色: admin。

14. ApprovalStatusScreen (審核狀態畫面)

• 路由: /pending-approval
• 目的: 向等待管理員核准的使用者顯示。
• 版面配置: 置中圖示和訊息，重新整理按鈕。
• 元素: 狀態文字、重新整理 IconButton。
• 資料: AppUser 狀態。
• 導航: 無 (阻擋進入)。
• 角色: pending。

15. PremiumManagementScreen (進階管理畫面)

• 路由: /premium
• 目的: 訂閱方案和購買。
• 版面配置: 定價層級卡片、功能比較清單。
• 元素: PricingCard、訂閱 ElevatedButton。
• 資料: RevenueCat / Google Play Billing。
• 導航: 返回上一頁。
• 角色: 所有 (除了 admin)。

16. TransactionHistoryScreen (交易記錄畫面)

• 路由: /transactions
• 目的: 個人交易記錄。
• 版面配置: 依時間排序的過去購買清單。
• 元素: TransactionListTile。
• 資料: TransactionRecord。
• 導航: 無。
• 角色: 所有購買者。

17. AdminTransactionReportScreen (管理員交易報告畫面)

• 路由: /admin/revenue
• 目的: 管理員營收報告。
• 版面配置: 顯示隨時間變化之營收的圖表。
• 元素: LineChart、摘要卡片。
• 資料: 聚合的 TransactionRecord。
• 導航: 無。
• 角色: admin。

18. NotesListScreen (筆記清單畫面)

• 路由: /notes
• 目的: 學習筆記清單。
• 版面配置: 筆記文件的網格或清單。
• 元素: NoteCard、建立 FAB。
• 資料: 本機/遠端筆記資料庫。
• 導航: 前往 NoteViewerScreen。
• 角色: 所有已驗證使用者。

19. NoteViewerScreen (筆記檢視器畫面)

• 路由: /note-view
• 目的: Markdown 筆記閱讀器。
• 版面配置: 豐富文字 Markdown 渲染。
• 元素: Markdown 小工具。
• 資料: 筆記內容。
• 導航: 返回。
• 角色: 所有已驗證使用者。

20. AppWebViewScreen (應用程式網頁檢視畫面)

• 路由: /webview
• 目的: 帶有浮水印的嵌入式瀏覽器，用於外部連結。
• 版面配置: 帶有覆蓋層的全螢幕網頁檢視。
• 元素: WebView、動態浮水印覆蓋層。
• 資料: URL。
• 導航: 返回。
• 角色: 所有。

21. DeviceSecurityScreen (裝置安全畫面)

• 路由: /security-violation
• 目的: 安全違規顯示 (例如 NTP 時間不符)。
• 版面配置: 警告圖示，說明文字。
• 元素: ErrorCard。
• 資料: 安全服務。
• 導航: 阻擋進入。
• 角色: 所有。

22. RootDetectedScreen (偵測到 Root 畫面)

• 路由: /root-detected
• 目的: Root/越獄裝置警告。
• 版面配置: 警告圖示，一般錯誤。
• 元素: 文字。
• 資料: Root 偵測服務。
• 導航: 阻擋進入。
• 角色: 所有。

23. EmulatorBlockedScreen (模擬器封鎖畫面)

• 路由: /emulator-blocked
• 目的: 模擬器警告。
• 版面配置: 警告圖示。
• 元素: 文字。
• 資料: 模擬器偵測。
• 導航: 阻擋進入。
• 角色: 所有 (除了測試人員)。

24. ObscuredBlockerScreen (遮蔽封鎖畫面)

• 路由: /tapjacking-blocked
• 目的: 點擊劫持 (Tapjacking) 覆蓋層封鎖器。
• 版面配置: 全螢幕封鎖，包含關於螢幕覆蓋層的警告。
• 元素: 警告文字。
• 資料: WindowManager 服務。
• 導航: 阻擋進入。
• 角色: 所有。

25. UnauthorizedScreen (未授權畫面)

• 路由: /unauthorized
• 目的: 拒絕存取 (過期/錯誤裝置/錯誤平台)。
• 版面配置: 錯誤訊息和原因。
• 元素: 詳細文字，聯絡支援按鈕。
• 資料: AppUser 限制。
• 導航: 阻擋進入。
• 角色: 受限使用者。

26. AdblockDetectedScreen (偵測到廣告攔截畫面)

• 路由: /adblock-warning
• 目的: 給免費使用者的廣告攔截警告。
• 版面配置: 要求移除廣告攔截或升級進階版的訊息。
• 元素: 警告文字，進階升級按鈕。
• 資料: 廣告服務狀態。
• 導航: 繼續或升級。
• 角色: guest, viewer (如果需要廣告)。

03-interaction-patterns.md

互動模式

1. 導航模式

• AuthWrapper 閘道: 所有初始應用程式啟動都會透過 AuthWrapper 路由。它作為一個隱藏的狀態機，在路由到實際目的地之前處理啟動畫面、初始化和安全檢查。
• 堆疊導航 (Stack Navigation): 標準階層導航使用 Navigator.push() 進入子頁面 (例如 Dashboard -> ExamList -> ExamScreen)。
• 狀態保留: 返回導航 (Navigator.pop()) 保留前一個畫面的狀態，以防止不必要地重新擷取資料。

2. 載入狀態

• 初始載入: 在關鍵阻塞操作 (例如應用程式啟動、登入) 期間，顯示置中的 CircularProgressIndicator。
• 骨架屏載入 (Skeleton Loading): 用於清單 (例如 ExamListScreen, DashboardScreen 統計數據)，在擷取資料時提供感知效能。
• 錯誤狀態: 在內容應顯示的位置根據上下文顯示，帶有清晰的錯誤訊息和「重試」按鈕。
• 空白狀態: 如果清單為空 (例如沒有錯題)，則顯示友善的插圖和指引文字 (例如「太棒了！您沒有需要複習的錯題。」)。

3. 動畫與轉場

• 頁面轉場: 標準 MaterialPageRoute 轉場 (根據平台向上/向左滑動) 以提供熟悉感。
• 選項選擇: 點擊選擇題選項會觸發細微的背景醒目提示淡入和漣漪效果。
• 計時器更新: MockExamScreen 上的倒數計時器使用在地化的狀態建構器 (State Builder)，每秒僅更新文字小工具，避免整個頁面重建和 UI 閃爍。
• AI 聊天: AI 家教抽屜中的訊息會向上滑動並淡入，模仿自然的通訊應用程式。

4. 手勢

• 拖放 (Drag-and-Drop): 對於互動式模擬題，使用者可以拖曳項目並將其放入指定的目標區域。
• 滑動導航: 可以啟用左右水平滑動，以便在練習模式中的考題之間移動。
• 長按 (Long Press): 長按選項或術語可能會調出工具提示或定義。
• 下拉更新 (Pull-to-Refresh): 適用於標準清單畫面 (如 NotesListScreen 或 TransactionHistoryScreen)，以手動同步資料。

5. 響應式版面配置

• 行動裝置直向: 預設單欄版面配置，針對垂直捲動進行最佳化。
• 行動裝置橫向: 切換到並排版面配置 (考題在左，選項在右) 以最大化螢幕可用空間並減少捲動。
• 平板電腦: 對於設定或筆記清單等畫面，使用主從式版面配置 (Master-Detail layout)。
• 網頁版: 限制主內容區域的最大寬度 (例如 maxWidth: 800px) 並將其置中，以防止文字行過長，確保可讀性。