# **文心閣 Flutter App 開發規範**
📌 **目標**：開發一款針對國中教育會考的學習 App，包含 **倒數計時、Google 登入、離線功能**，確保效能優化、良好的使用者體驗，並適用於多設備。

## **1. 環境與工具**
### ✅ **Flutter 環境**
- 使用 **Flutter 3.27.4**
- 使用 **Dart 3.6.2**
- 如個人有多版本需求，建議使用 `fvm` (Flutter Version Manager) 管理 Flutter 版本：

  fvm use stable

### ✅ **必要工具**
- **UI 框架**：`Wenxin Vision`
- **圖表**：`fl_chart`（用於學習數據視覺化）
- **本地儲存**：`hive` 或 `sqflite`（離線功能）

---

## **2. 功能規劃**
### ✅ **核心功能**
1. **倒數計時**
- 設定倒數計時（顯示距離會考天數）
- 支援通知提醒
2. **學習題庫**
- 可在線/離線作答
- 題目分類（科目、難度）
- 記錄答題進度
3. **Google 登入**
- 使用 Google oauth2 api
- 允許訪客模式
4. **成績與進度分析**
- 圖表呈現錯題統計
- 每日/每週進度追蹤
5. **離線模式**
- 本地儲存練習記錄（使用 `hive` 或 `sqflite`）
- 自動同步至 Firebase（當網路恢復時）
6. **其他**
- UI 支援深色模式
- 可設定提醒與每日學習目標

---

## **3. 專案架構**
📌 **使用 Feature-based 架構**（適合擴展）

lib/
├── core/                # 核心功能（API, Database, Utils）
│   ├── api/
│   ├── database/
│   ├── utils/
│   ├── theme.dart
├── features/            # 功能模組
│   ├── auth/            # 登入功能
│   │   ├── presentation/
│   │   ├── application/
│   │   ├── domain/
│   │   ├── data/
│   ├── countdown/       # 倒數計時
│   ├── quiz/            # 練習功能
│   ├── profile/         # 使用者資料
│   ├── settings/        # 設定
├── common/              # 可重用組件
│   ├── widgets/
│   ├── styles/
├── main.dart            # 入口點

---

## **4. 程式碼規範**
### ✅ **命名規範**
| 類型 | 規則 |
|-----------|------|
| 變數/函式 | `camelCase`（例：`getUserName()`） |
| 類別/Widget | `PascalCase`（例：`HomeScreen`） |
| 檔案 | `snake_case.dart`（例：`user_profile_screen.dart`） |
| 常數 | `SCREAMING_SNAKE_CASE`（例：`MAX_RETRY_COUNT`） |

### ✅ **Dart/Flutter 規範**
- **使用 `const`** 優化效能
- **避免 `dynamic`，明確定義型別**
- **使用 `freezed` 來處理 API 數據模型**
- **錯誤處理**：所有 API 請求與離線存取需有 `try-catch`

---

## **5. 版本控制 (Git)**
### ✅ **Git Flow**
- `main`：正式版本
- `develop`：開發分支
- `feature/{功能名稱}`：新功能開發
- `bugfix/{修復名稱}`：修復錯誤

### ✅ **Commit 規範**
使用 [Conventional Commits](https://www.conventionalcommits.org/)，例如：

feat(auth): 新增 Google 登入功能
fix(countdown): 修正倒數計時錯誤
refactor(quiz): 優化答題邏輯

---

## **6. 測試 (Testing)**
### ✅ **測試類型**
- **單元測試 (Unit Test)**：測試商業邏輯
- **小組件測試 (Widget Test)**：測試 UI 行為
- **整合測試 (Integration Test)**：測試完整流程（登入、做題、儲存）

### ✅ **測試工具**
- `flutter_test`（內建測試框架）

### ✅ **測試命令**

flutter test

---

## **8. 離線模式(待確認)**
📌 **考量點**
- 題庫與作答記錄可本地儲存
- 使用 `hive` 或 `sqflite` 儲存練習進度
- 當裝置恢復網路時，自動同步 API

📌 **實作方式**

Future<void> saveQuizProgress(QuizData data) async {
  final box = await Hive.openBox<QuizData>('quiz_progress');
  await box.put(data.id, data);
}

---

## **9. 發佈與版本管理**
### ✅ **Flutter Build**
- `flutter build apk --release`
- `flutter build ios --release`

### **✅ 版本規範**
### **格式**

MAJOR.MINOR.PATCH-[標籤].[編號]

- `[標籤]` 可以是 `alpha`, `beta`, `rc` 等
- `[編號]` 是測試版的遞增數字（如 `1.2.3-beta.1`）

### **版本示例**
| 版本號 | 說明 |
|--------|------|
| `1.0.0-alpha.1` | **內部測試版 (Alpha)**，可能有許多錯誤，僅限開發團隊使用 |
| `1.0.0-alpha.2` | **內部測試版第二次更新**，修正 Alpha 1 的問題 |
| `1.0.0-beta.1` | **封閉測試版 (Beta)**，功能完整但可能有錯誤 |
| `1.0.0-beta.2` | **Beta 版修正與改進** |
| `1.0.0-rc.1` | **候選版本 (Release Candidate, RC)**，接近正式版，可能修正少量問題 |
| `1.0.0` | **正式版本 (Stable)**，發布給所有用戶 |

---

## **10. 版本發佈流程**
1. **開發新功能**

   git tag -a v1.0.0-alpha.1 -m "Alpha 1 release"
   git push origin v1.0.0-alpha.1

2. **進入 Beta 測試**

   git tag -a v1.0.0-beta.1 -m "Beta 1 release"
   git push origin v1.0.0-beta.1

3. **修正問題後進入 RC 階段 **

   git tag -a v1.0.0-rc.1 -m "Release Candidate 1"
   git push origin v1.0.0-rc.1

4. **正式發佈**

   git tag -a v1.0.0 -m "Stable release"
   git push origin v1.0.0

---

## **11. 在 Flutter 中指定版本**
Flutter 的 `pubspec.yaml` 允許你使用預發佈版本，例如：

version: 1.0.0-beta.1

當發佈正式版時，改為：

version: 1.0.0