依現況更新 app_docs 內所有檔案的內容

2026 iThome 鐵人賽

Build on Google AI

將考國際證照的應用程式變成開源系列第 66 篇

18th鐵人賽

alanliang

2026-09-07 19:22:30

38 瀏覽

分享至

Listed directory app_docs
Viewed AI_AGENT_DOC_RULES.md:1-31
Ran command: git status; git log -n 5 --oneline
Viewed README.md:1-27
Viewed 01-%E6%96%B0%E6%89%8B%E9%9B%B6%E5%9F%BA%E7%A4%8E%E5%85%A8%E5%9C%96%E6%96%87%E6%8C%87%E5%8D%97.md:1-90
Viewed 02-%E9%96%8B%E7%99%BC%E8%80%85%E8%88%87%E9%80%B2%E9%9A%8E%E5%AE%89%E8%A3%9D%E5%BB%BA%E7%BD%AE%E6%8C%87%E5%8D%97.md:1-82
Viewed 03-Google-Cloud-Run%E9%83%A8%E7%BD%B2%E7%B6%AD%E9%81%8B%E6%8C%87%E5%8D%97.md:1-77
Viewed 04-Cloud-Run%E4%B8%80%E9%8D%B5%E8%87%AA%E5%8B%95%E5%8C%96%E7%99%BC%E5%B8%83%E8%88%87%E9%9B%B6%E5%9F%BA%E7%A4%8E%E5%AF%A6%E6%88%B0%E6%8C%87%E5%8D%97.md:1-227
Viewed pubspec.yaml:1-60
Viewed pubspec.yaml:61-89
Listed directory lib
Listed directory data
Listed directory services
Listed directory data
Listed directory datasources
Listed directory views
Viewed auth_service.dart:1-75
Viewed ai_service.dart:1-60
Viewed ai_service.dart:60-115
Viewed ai_service.dart:480-540
Viewed ai_service.dart:345-375
Viewed ai_service.dart:245-285
Viewed ai_service.dart:300-340
Viewed ai_service.dart:285-302
Searched for files: auth
Viewed auth_controller.dart:1-60
Viewed app_user.dart:1-60
Viewed app_user.dart:61-140
Viewed deploy.ps1:1-18
Viewed deploy_cloud_run.ps1:1-60
Viewed deploy.env.example:1-32
Ran command: flutter test
Created c:\alan\google cloud app\OpenPassExam\app_docs\README.md
Checked task Run flutter test
Edited README.md
Edited 01-%E6%96%B0%E6%89%8B%E9%9B%B6%E5%9F%BA%E7%A4%8E%E5%85%A8%E5%9C%96%E6%96%87%E6%8C%87%E5%8D%97.md
Edited 02-%E9%96%8B%E7%99%BC%E8%80%85%E8%88%87%E9%80%B2%E9%9A%8E%E5%AE%89%E8%A3%9D%E5%BB%BA%E7%BD%AE%E6%8C%87%E5%8D%97.md
Edited 03-Google-Cloud-Run%E9%83%A8%E7%BD%B2%E7%B6%AD%E9%81%8B%E6%8C%87%E5%8D%97.md
Edited 04-Cloud-Run%E4%B8%80%E9%8D%B5%E8%87%AA%E5%8B%95%E5%8C%96%E7%99%BC%E5%B8%83%E8%88%87%E9%9B%B6%E5%9F%BA%E7%A4%8E%E5%AF%A6%E6%88%B0%E6%8C%87%E5%8D%97.md
Edited AI_AGENT_DOC_RULES.md
Ran command: git status
Viewed README.md:1-60
Edited README.md
Ran command: git status

已依照 OpenPassExam 專案的最新架構與實作現況，全面修訂並更新了 app_docs/ 目錄內的所有文件，並同步校準專案根目錄的導覽索引。

📋 本次文檔更新重點彙整

文檔名稱	主要更新內容
📖 app_docs/README.md	1. 補齊專案最新核心技術全貌：Firebase Auth Google 帳號一鍵登入、全站 7 級角色權限 (RBAC Matrix)、Gemini 3.8/3.7/2.5 多模型平滑降級級聯、Gemma 4 端側離線引擎、BYOK 多金鑰輪替池與熔斷機制、Cloud Run 部署管線。2. 更新所有文檔索引及摘要說明。
📖 app_docs/01-新手零基礎全圖文指南.md	1. 增加 Google 帳號一鍵登入與訪客模式體驗步驟說明。2. 更新 AI 智慧家教為 Gemini 3.8 / 3.7 Flash，並支援輸入多組金鑰（支援 `AQ...` 與 `AIzaSy...` 格式）實現免費額度倍數擴充。3. 補充 Gemma 4 端側離線引擎無縫接管說明。4. 新增根目錄 `.\deploy.ps1` 快捷指令與 429 配額耗盡處理 Q&A。
💻 app_docs/02-開發者與進階安裝建置指南.md	1. 新增環境依賴說明：Microsoft OpenJDK 21 LTS 鎖定版本、Android NDK、Firebase 核心套件清單。2. 詳解專案分層架構（Controllers、Core、Data、Services、Views）。3. 完整納入全站 7 級 RBAC 角色權限矩陣對照表。4. 包含代碼靜態分析 (`flutter analyze`) 與全量單元測試 (`flutter test`) 驗證流程。
☁️ app_docs/03-Google-Cloud-Run部署維運指南.md	1. 統一對齊映像庫與服務名稱預設值（`openpassexam-repo`、`openpassexam-web`）。2. 徹底消除寫死的專案 ID，全面落實佔位符與機密分離政策。3. 新增關鍵維運步驟：Firebase 授權網域 (Authorized Domains) 設定教學，確保 Cloud Run 上線後 Google 帳號可順暢登入。4. 補充多階段容器化架構、流量分流切換與一鍵版本回滾 (Rollback) 指令。
🚀 app_docs/04-Cloud-Run一鍵自動化發布與零基礎實戰指南.md	1. 對齊根目錄快捷腳本 `.\deploy.ps1` 與零基礎引導發布流程。2. 獨立章節說明 Firebase 授權網域 (Authorized Domains) 設定。3. 強化 BYOK 多金鑰輪替池與熔斷機制的資安優勢。4. 修正服務名稱、映像庫與成本預算守門員指令。
🤖 app_docs/AI_AGENT_DOC_RULES.md	1. 擴充台灣標準專業技術術語對照表（快取、管線、無伺服器、執行緒、身分驗證、授權等）。2. 新增「規則 4：功能變更與文檔同步原則 (Documentation Sync)」，規範未來 AI 協作時的同步機制。
📄 README.md (專案根目錄)	同步校準 `app_docs/` 的索引連結，補齊 `04-Cloud-Run一鍵自動化發布與零基礎實戰指南.md`，保持全站指引一致。

🛡️ 規範合規驗證

台灣繁體中文 (zh-TW)：嚴格採用台灣軟體與雲端標準術語（如：伺服器、連接埠、存放庫/儲存庫、封包、路由表、快取等）。
零機密外洩 (Zero-Leakage Policy)：所有手冊皆採用佔位符（YOUR_PROJECT_ID 等）或引導本機使用 deploy.env，絕無敏感金鑰或專案 ID 外洩。
測試驗證：專案現有 58 項單元測試全數順利通過（All tests passed）。

Ran command: git status
Ran command: git remote -v
Ran command: git add README.md app_docs/
Ran command: git status
Ran command: git commit -m "docs: 全面同步更新 app_docs 應用程式手冊與 README 索引至最新架構現況"
Ran command: git push origin main
Ran command: git status

已成功將本次更新的所有文檔與設定變更提交並推送至 GitHub 存放庫！🎉