離線 AI 模型跨平台管理、三層 AI 階層調度與多使用者 CRUD 權限架構落實驗證報告

離線 AI 模型跨平台管理、三層 AI 階層調度與多使用者 CRUD 權限架構落實驗證報告

本報告總結針對使用者的四項核心需求所完成的深度架構升級、程式碼實作與驗證結果。

1. 離線 AI 模型下載現況與管理中心建立

勘查結果

• 原先現況：App 內原本僅有端側模擬推論方法，未提供實體模型下載介面，設定中僅有 BYOK 金鑰對話框。
• 全新落地實作：
  • 新增 offline_model_manager.dart：建立跨平台端側離線 AI 模型管理器。
  • 在 settings_screen.dart 建立**「端側離線 AI 模型管理中心 (第 1 優先推論)」**卡片，具備：
    • 顯示目前模型規格（Google Gemma 4 (2B) LiteRT 或 Chrome Built-in Gemini Nano）
    • 平台技術環境說明（Web 支援 Chrome Built-in AI / WebGPU；Android 支援 Google LiteRT NPU 加速）
    • 下載進度條（LinearProgressIndicator，顯示 0% ~ 100% 動態進度）
    • 空間釋放與本機模型刪除按鈕
    • 「啟用離線模型為第 1 優先」開關（即時控制 preferOffline）

2. 離線 AI 模型跨平台 (Web, Android 等) 執行架構

3. 三層 AI 優先調度機制 (Three-Tier Priority Cascade)

在 ai_service.dart 與 ai_model_config.dart 中完成重構：

graph TD
    Request["使用者提問 / 考題解析請求"] --> CheckOffline{"【第 1 優先】<br>離線優先開啟 且 本機模型就緒？<br>(或目前處於離線狀態)"}
    CheckOffline -- 是 (預設模式) --> LocalInfer["⚡ 端側離線推論<br>(Gemma 4 2B / Chrome Nano)<br>• 0 網路流量 • 0 延遲 • 100% 隱私 • 4096 Tokens"]
    
    CheckOffline -- 否 (或強制雲端) --> CloudPrimary["🚀 【第 2 優先】<br>雲端最新 Google 多模態模型<br>(Gemini 3.8 Flash)<br>支援思考預算、拓撲圖片多模態辨識"]
    
    CloudPrimary --> PrimaryCheck{"呼叫狀態"}
    PrimaryCheck -- 成功 (200 OK) --> ReturnPrimary["過濾思考標籤後輸出旗艦解析"]
    PrimaryCheck -- 失敗 (429限流/503/逾時) --> CloudFallback["🛡️ 【第 3 優先 (備用)】<br>主流最穩定多模態模型<br>(Gemini 2.5 Flash / Gemini 1.5 Pro)"]
    CloudFallback --> FallbackSuccess["無縫平滑返回穩定備用解析"]

4. 考試科目、考題與討論區的多使用者個人化 CRUD 權限控管

4.1 資料結構擴充

• Question (question.dart)：
  • 新增 creatorId: String（建立者 UID，官方題為 'system'）
  • 新增 creatorName: String?（建立者暱稱）
  • 新增 isOwner(currentUid) 與 canEdit(currentUid, isAdmin) 方法。
• ExamSubject (exam_subject.dart)：
  • 新增 creatorId: String?、creatorName: String? 與 isOwner、canEdit。
• QuestionComment (question_comment.dart)：
  • 全新討論區留言模型，具備 authorId, authorName, content, createdAt, updatedAt 與 isAuthor、canEdit。

4.2 權限與安全驗證實現

1. 考題存取控制 (question_repository.dart)：
   • saveQuestion 與 deleteQuestion 加入 currentUserId 檢查：若嘗試修改或刪除他人建立之考題，立即攔截並拋出 Exception('【權限不足】：您不是此考題的建立者，僅能進行讀取...')。
2. 考題討論區存取控制 (discussion_repository.dart & discussion_controller.dart)：
   • 任何登入學員均可發表新留言與閱讀討論。
   • 僅留言原作者（authorId == currentUserId）或系統管理員可以編輯或刪除該則留言；嚴禁竄改他人發言。
3. 刷題畫面直覺呈現 (practice_screen.dart & question_discussion_sheet.dart)：
   • AppBar 整合「💬 考題討論區」入口與建立者本人「✏️ 編輯考題」快捷按鈕。
   • 考題上方顯示權限識別標章（⭐ 您是本題建立者 或 👤 建立者：其他使用者 (唯讀)）。
   • 討論區彈窗中，只有自己的留言右上角會出現「編輯 / 刪除」選項。
4. 雲端安全規則落實：
   • 提供正式的 firestore.rules（Cloud Firestore 安全規則）。
   • 提供正式的 supabase_rls_policies.sql（Supabase PostgreSQL Row Level Security 政策）。

5. 自動化測試驗證結果

flutter analyze
# 結果：No issues found! (0 warnings, 0 errors)

flutter test
# 結果：All 34 tests passed! (包含 4 項全新離線調度與所有權隔離單元測試)

• 離線模型管理器狀態與下載流程測試 ➔ ✅ 通過
• AiService 三層調度：第 1 優先應執行端側離線推論 ➔ ✅ 通過
• 考題建立者擁有 CRUD 權限，非建立者僅能 Read (Update / Delete 攔截) ➔ ✅ 通過
• 考題討論區留言：僅原作者或管理員可修改/刪除留言，其他人唯讀 ➔ ✅ 通過