1b4f3a7bbe
Some checks failed
CD Pipeline / deploy (push) Failing after 59s
- 建立 Gitea Actions CD pipeline (.gitea/workflows/cd.yaml) - 部署模式: rsync Python 檔案至 188 → docker restart (volume mount) - Dockerfile/requirements 變動時自動重建 Docker image - 部署通知: Telegram (開始/成功/失敗) - 健康檢查: https://mo.wooo.work/health (最多 5 次重試) - 同步最新 CLAUDE.md / ADR-008 / memory (2026-04-19) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
382 lines
6.6 KiB
Markdown
382 lines
6.6 KiB
Markdown
# 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/)
|