# MOMO Pro System - Git 開發規範

> 最後更新：2026-01-29

---

## 🌿 分支策略

### 分支類型

```
main                    # 生產分支 (受保護)
├── develop             # 開發整合分支
├── feature/*           # 功能開發分支
├── hotfix/*            # 緊急修復分支
├── release/*           # 發布準備分支
└── bugfix/*            # 錯誤修復分支
```

### 分支命名規範

| 類型 | 格式 | 範例 |
|------|------|------|
| 功能 | `feature/<issue-id>-<description>` | `feature/123-add-ai-history` |
| 修復 | `bugfix/<issue-id>-<description>` | `bugfix/456-fix-login-error` |
| 緊急 | `hotfix/<date>-<description>` | `hotfix/20260129-fix-crawler` |
| 發布 | `release/v<version>` | `release/v2.0.0` |

### Git Flow 流程

```mermaid
gitGraph
    commit id: "init"
    branch develop
    commit id: "dev-1"
    branch feature/123-new-feature
    commit id: "feat-1"
    commit id: "feat-2"
    checkout develop
    merge feature/123-new-feature
    branch release/v2.0
    commit id: "bump version"
    checkout main
    merge release/v2.0 tag: "v2.0.0"
    checkout develop
    merge release/v2.0
```

---

## 📝 Commit 規範

### Commit Message 格式

```
<type>(<scope>): <subject>

<body>

<footer>
```

### 類型 (Type)

| 類型 | 說明 | 範例 |
|------|------|------|
| `feat` | 新功能 | `feat(ai): 新增文案收藏功能` |
| `fix` | 錯誤修復 | `fix(auth): 修復登入驗證問題` |
| `docs` | 文件變更 | `docs: 更新 API 文件` |
| `style` | 程式碼格式 | `style: 格式化程式碼` |
| `refactor` | 重構 | `refactor(db): 重構資料庫連線` |
| `test` | 測試 | `test: 新增用戶 API 測試` |
| `chore` | 維護 | `chore: 更新依賴套件` |
| `perf` | 效能優化 | `perf(query): 優化商品查詢效能` |
| `ci` | CI/CD | `ci: 修復 GitLab pipeline` |

### 範圍 (Scope)

| 範圍 | 說明 |
|------|------|
| `auth` | 認證授權 |
| `ai` | AI 功能 |
| `crawler` | 爬蟲 |
| `dashboard` | 商品看板 |
| `sales` | 業績分析 |
| `vendor` | 廠商管理 |
| `user` | 用戶管理 |
| `notif` | 通知 |
| `db` | 資料庫 |
| `ui` | 介面 |
| `api` | API |

### 範例

```
feat(ai): 新增 Gemini 網路搜尋功能

- 整合 Gemini 1.5 Flash API
- 支援即時網路資訊查詢
- 新增用量追蹤記錄

Closes #234
```

```
fix(vendor): 修復郵件發送重複問題

發送郵件時未正確更新狀態，導致重複發送。
加入狀態檢查邏輯，確保不會重複處理。

Fixes #567
```

---

## 🔄 Merge Request 規範

### MR 標題格式

```
[類型] 簡短描述 (#issue)
```

範例：
- `[feat] 新增 AI 文案收藏功能 (#234)`
- `[fix] 修復登入驗證問題 (#567)`

### MR 描述模板

```markdown
## 變更說明
簡述此 MR 的變更內容。

## 變更類型
- [ ] 新功能 (feat)
- [ ] 錯誤修復 (fix)
- [ ] 重構 (refactor)
- [ ] 文件 (docs)
- [ ] 其他

## 測試
- [ ] 本地測試通過
- [ ] 單元測試通過
- [ ] UI 測試通過

## 截圖 (如適用)
貼上相關截圖。

## 關聯 Issue
Closes #issue_number
```

### 審核清單

- [ ] 程式碼符合專案風格
- [ ] 無明顯 Bug
- [ ] 有適當的錯誤處理
- [ ] 有必要的測試
- [ ] 文件已更新

---

## ⚙️ CI/CD Pipeline

### Pipeline 階段

```yaml
stages:
  - test        # 單元測試
  - build       # 構建映像
  - push        # 推送 Registry
  - deploy      # 部署 K8s
```

### 觸發條件

| 分支 | 觸發動作 |
|------|---------|
| `main` | 自動部署到生產 |
| `develop` | 自動測試 + 構建 |
| `feature/*` | 自動測試 |
| `hotfix/*` | 自動測試 + 構建 |

### Pipeline 配置

```yaml
# .gitlab-ci.yml
test:
  stage: test
  script:
    - pip install -r requirements.txt
    - pytest tests/ -v
  rules:
    - if: $CI_MERGE_REQUEST_ID

build:
  stage: build
  script:
    - docker build -t $IMAGE_TAG .
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_BRANCH == "develop"

deploy:
  stage: deploy
  script:
    - kubectl rollout restart deployment/momo-app -n momo
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  when: manual
```

### 自動修復

Pipeline 失敗時觸發自動修復：

| 失敗階段 | 修復動作 |
|---------|---------|
| test | 系統健康檢查、診斷報告 |
| build | Harbor 重啟、磁碟清理 |
| deploy | Pod 重啟、Secret 重建 |

---

## 🏷️ 版本號規範

### Semantic Versioning

```
MAJOR.MINOR.PATCH
```

| 版位 | 說明 | 範例 |
|------|------|------|
| MAJOR | 不相容 API 變更 | 2.0.0 |
| MINOR | 新功能 (向後相容) | 2.1.0 |
| PATCH | Bug 修復 | 2.1.1 |

### 版本標籤

```bash
# 建立版本標籤
git tag -a v2.0.0 -m "Release version 2.0.0"

# 推送標籤
git push origin v2.0.0
```

### CHANGELOG 格式

```markdown
# Changelog

## [2.0.0] - 2026-01-29

### Added
- AI 文案生成功能
- 趨勢爬蟲模組

### Changed
- 重構用戶權限系統

### Fixed
- 修復登入驗證問題

### Removed
- 移除舊版報表功能
```

---

## 🔒 分支保護

### main 分支規則

- ✅ 禁止直接推送
- ✅ 需要 Merge Request
- ✅ 需要 1 位審核者
- ✅ CI Pipeline 必須通過
- ✅ 禁止強制推送

### develop 分支規則

- ✅ 需要 Merge Request
- ✅ CI Pipeline 必須通過

---

## 📋 開發流程

### 1. 開始開發

```bash
# 更新 develop
git checkout develop
git pull origin develop

# 建立功能分支
git checkout -b feature/123-new-feature
```

### 2. 開發中

```bash
# 定期提交
git add .
git commit -m "feat(scope): 描述"

# 同步 develop (避免衝突)
git fetch origin
git rebase origin/develop
```

### 3. 提交 MR

```bash
# 推送分支
git push origin feature/123-new-feature

# 在 GitLab 建立 Merge Request
```

### 4. 審核與合併

- 等待 CI 通過
- 請求代碼審核
- 審核通過後合併

### 5. 清理

```bash
# 刪除本地分支
git branch -d feature/123-new-feature

# 刪除遠端分支 (GitLab 會自動刪除)
```

---

## 🚀 發布流程

### 1. 建立發布分支

```bash
git checkout develop
git pull
git checkout -b release/v2.0.0
```

### 2. 更新版本

```bash
# 更新版本號
# 更新 CHANGELOG
git commit -m "chore: bump version to 2.0.0"
```

### 3. 合併到 main

```bash
git checkout main
git merge release/v2.0.0
git tag -a v2.0.0 -m "Release v2.0.0"
git push origin main --tags
```

### 4. 合併回 develop

```bash
git checkout develop
git merge release/v2.0.0
git push origin develop
```

---

## 📚 相關資源

- [Conventional Commits](https://www.conventionalcommits.org/)
- [Semantic Versioning](https://semver.org/)
- [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/)
