# Git 工作流程規範

## 🌳 分支策略

### 主要分支
```
main (production)
  ├── develop (開發整合)
  │   ├── feature/[feature-name]
  │   ├── fix/[bug-description]
  │   └── refactor/[component-name]
  └── hotfix/[urgent-fix]
```

### 分支說明

| 分支類型 | 命名規則 | 用途 | 合併目標 |
|---------|---------|------|---------|
| `main` | main | 生產環境代碼 | - |
| `develop` | develop | 開發整合分支 | main |
| `feature/*` | feature/user-auth | 新功能開發 | develop |
| `fix/*` | fix/login-error | Bug 修復 | develop |
| `refactor/*` | refactor/api-structure | 代碼重構 | develop |
| `hotfix/*` | hotfix/critical-bug | 緊急修復 | main + develop |

## 📝 Commit 規範

### Commit Message 格式
```
<type>(<scope>): <subject>

<body>

<footer>
```

### Type 類型
- `feat`: 新功能
- `fix`: Bug 修復
- `docs`: 文檔更新
- `style`: 代碼格式（不影響功能）
- `refactor`: 重構
- `perf`: 性能優化
- `test`: 測試相關
- `chore`: 構建過程或輔助工具的變動
- `revert`: 回退

### 範例
```bash
feat(auth): add Google OAuth login

- Implement Google OAuth provider
- Add login button component
- Update auth configuration

Closes #123
```

### Commit 指令範例
```bash
# 功能開發
git commit -m "feat(flashcard): add AI generation feature"

# Bug 修復
git commit -m "fix(auth): resolve token expiration issue"

# 文檔更新
git commit -m "docs(api): update endpoint documentation"

# 代碼重構
git commit -m "refactor(components): extract reusable card component"

# 性能優化
git commit -m "perf(api): optimize database queries"
```

## 🔄 開發流程

### 1. 開始新功能
```bash
# 從 develop 創建新分支
git checkout develop
git pull origin develop
git checkout -b feature/flashcard-generation

# 開發過程中定期提交
git add .
git commit -m "feat(flashcard): implement basic structure"
```

### 2. 完成功能並提交 PR
```bash
# 推送分支
git push origin feature/flashcard-generation

# 在 GitHub 上創建 Pull Request
# PR 標題: [Feature] Flashcard Generation
# PR 描述: 詳細說明功能內容和測試方式
```

### 3. Code Review 流程
- 至少需要 1 位 reviewer 審核
- 通過所有自動化測試
- 解決所有 review comments
- 確認無衝突後合併

### 4. 合併後清理
```bash
# 刪除本地分支
git branch -d feature/flashcard-generation

# 刪除遠端分支
git push origin --delete feature/flashcard-generation
```

## 🚀 發布流程

### 1. 準備發布
```bash
# 從 develop 合併到 main
git checkout main
git pull origin main
git merge --no-ff develop
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin main --tags
```

### 2. 熱修復流程
```bash
# 從 main 創建 hotfix
git checkout main
git checkout -b hotfix/critical-error

# 修復並提交
git commit -m "fix: resolve critical production error"

# 合併回 main 和 develop
git checkout main
git merge --no-ff hotfix/critical-error
git checkout develop
git merge --no-ff hotfix/critical-error

# 清理分支
git branch -d hotfix/critical-error
```

## 📋 PR 模板

創建 `.github/pull_request_template.md`:

```markdown
## 📋 描述
簡要描述這個 PR 的內容

## 🎯 類型
- [ ] 🚀 新功能 (Feature)
- [ ] 🐛 Bug 修復 (Bugfix)
- [ ] 📝 文檔 (Documentation)
- [ ] 🎨 樣式 (Styling)
- [ ] 🔧 重構 (Refactoring)
- [ ] ⚡ 性能優化 (Performance)
- [ ] ✅ 測試 (Test)
- [ ] 🔨 構建 (Build)
- [ ] 🔄 CI/CD (CI)
- [ ] ⏪ 回退 (Revert)

## 🔗 相關 Issue
Closes #(issue number)

## ✅ 檢查清單
- [ ] 代碼已自測
- [ ] 已添加/更新測試
- [ ] 已更新相關文檔
- [ ] 符合代碼規範
- [ ] 無 TypeScript 錯誤
- [ ] 已在本地測試

## 📸 截圖（如適用）
如有 UI 變更，請附上截圖

## 📝 測試步驟
1. 步驟一
2. 步驟二
3. 預期結果

## 💬 備註
其他需要說明的內容
```

## 🛡️ 保護規則

### Main 分支保護
- 禁止直接推送
- 需要 PR review
- 需要通過 CI/CD 測試
- 需要最新的 develop 分支

### Develop 分支保護
- 需要 PR review
- 需要通過測試
- 自動刪除已合併的分支

## 📊 Git 常用命令

### 日常操作
```bash
# 查看狀態
git status

# 查看差異
git diff
git diff --staged

# 查看歷史
git log --oneline --graph --all

# 暫存當前工作
git stash
git stash pop

# 修改最後一次提交
git commit --amend

# 交互式重新整理提交
git rebase -i HEAD~3
```

### 分支操作
```bash
# 查看所有分支
git branch -a

# 切換分支
git checkout branch-name
git switch branch-name  # Git 2.23+

# 創建並切換
git checkout -b new-branch
git switch -c new-branch  # Git 2.23+

# 合併分支
git merge branch-name
git merge --no-ff branch-name  # 保留合併記錄

# 刪除分支
git branch -d branch-name  # 本地
git push origin --delete branch-name  # 遠端
```

### 同步操作
```bash
# 獲取最新代碼
git fetch origin
git pull origin branch-name

# 推送代碼
git push origin branch-name

# 強制推送（謹慎使用）
git push --force-with-lease origin branch-name
```

## 🚨 緊急情況處理

### 回退提交
```bash
# 回退但保留修改
git reset --soft HEAD~1

# 回退並放棄修改
git reset --hard HEAD~1

# 創建回退提交
git revert HEAD
```

### 解決衝突
```bash
# 合併時遇到衝突
git status  # 查看衝突文件
# 手動編輯解決衝突
git add .
git commit -m "resolve: merge conflicts"
```

### 恢復誤刪
```bash
# 查看 reflog
git reflog

# 恢復到特定提交
git reset --hard HEAD@{2}
```

## 📚 最佳實踐

1. **頻繁提交**：小步快跑，每個提交只做一件事
2. **寫好 Commit Message**：清晰描述做了什麼和為什麼
3. **定期同步**：每天開始工作前先 pull 最新代碼
4. **Code Review**：認真審核他人代碼，虛心接受建議
5. **保持分支簡潔**：完成後及時刪除無用分支
6. **測試後再提交**：確保代碼可運行再推送
7. **使用 .gitignore**：不要提交無關文件