AGENTS.md

AI Agent 指南 (AGENTS)

此為在通用考試題庫應用程式存放區中運作的 AI Agent 權威指南。本文件概述了您的目標、技術環境、核心開發慣例、嚴格的規範以及標準作業程序，以確保一致且高品質的開發貢獻。

1. 角色與目標

• 您的角色：您是一位專家級 Flutter 與後端開發 AI 助理。
• 您的目標：您的首要目標是根據提供的規格，建立、擴展並維護一個具備離線優先 (offline-first) 功能的完整考試題庫應用程式，並保持嚴謹的架構標準與高效能。

2. 技術堆疊 (Technology Stack)

本專案採用精密的多重資料庫架構與離線優先設計。

3. 核心開發慣例

• Git 工作流程：遵循標準的 功能分支 (Feature branch) -> 發起 PR (Pull Request) -> 主分支 (Main) 流程。請勿直接提交 (commit) 至 main 分支。
• 建置設定：
  • 維持建置檔案中指定之特定 NDK 版本與 JVM 目標。
  • 確保嚴格定義 ProGuard/R8 規則，避免誤刪經由反射 (reflection) 使用的程式碼。
• 使用者介面效能：
  • 偏好使用 ValueListenableBuilder 或特定的 Provider 來處理高頻率更新 (例如考試計時器)，以防止整個 Widget 樹重建。
  • 實作 Base64 與本機檔案系統的圖片快取機制。
• 本地化 (Localization)：
  • 廣泛透過 tr() 函式使用 easy_localization。
  • 絕對不要在 UI 中寫死 (hardcode) 字串。每個面向使用者的文字都必須具備本地化金鑰。
• 程式碼註解：所有的原始碼註解與說明文件 (docstrings) 必須以英文撰寫。

4. 嚴格規範 (Hard Rules)

1. GIT 中禁止存放機密資訊：絕對不允許提交 API 金鑰、服務帳戶 (Service Accounts) 或 .env 設定檔。
2. 嚴格執行本地化：所有面向使用者的字串必須透過本地化框架處理。
3. 遵循資料庫綱要：資料庫遷移 (migrations) 與實體修改必須嚴格遵守綱要參考文件 (請參閱 03-data-models.md)。
4. 測試優先：在提交 (commit) 或發起 PR 之前，所有自動化測試都必須在本機端順利通過。請勿破壞建置環境。

5. 標準作業流程

在指派實作功能時，請遵循以下標準循環：

1. 閱讀規格：檢閱相關的產品需求文件 (PRD) 與資料模型 (Data Models)。
2. 計畫：參考系統設計文件 (SDD) 制定技術實作計畫。
3. 實作：撰寫 Dart 程式碼，遵守 Repository 模式與狀態管理規範。
4. 測試：撰寫並執行單元測試 (Unit Tests) 與 Widget 測試。
5. 部署：遵循部署慣例 (必要時更新 CI/CD 管線)。

6. AI Agent 文件導覽地圖

為有效導覽此存放區，請根據您目前的任務使用此路由指南：

• 「我需要了解產品願景或功能」 -> 閱讀 PRD
• 「我需要建立或修改資料庫」 -> 閱讀 docs/02-sdd/zh-TW/04-database-design.md 與 docs/08-database/
• 「我需要實作某項功能」 -> 閱讀 BDD 情境 -> SDD 元件規格 -> 測試規格
• 「我需要了解物件綱要 (Schemas)」 -> 閱讀 docs/02-sdd/zh-TW/03-data-models.md
• 「我需要設定部署或建置版本 (Flavors)」 -> 閱讀 docs/07-deployment/