# Git 分支策略（简化版 GitFlow）

本文档是项目分支流的**唯一事实源**。决策背景与理由见 [decisions/0005-branching-strategy.md](decisions/0005-branching-strategy.md)。

## 分支角色

| 分支 | 从哪拉 | merge 回 | 用途 |
|------|--------|----------|------|
| `main` | — | — | 可发布稳定版；只经 `dev`（或 `hotfix`）进入，不直接收 feature |
| `dev` | `main` | — | 集成点；所有 feature 先合到这里 |
| `feature/<name>` | `dev` | `dev` | 单一功能/模块开发，完成后合回 dev |
| `hotfix/<name>` | `main` | `main` + `dev` | 线上紧急修复（按需，当前阶段少用） |

> 当前不引入 `release/*`：基础建设阶段收益低。进入正式发布周期后再升级（见 ADR-0005「后果」）。

## 完整流程

```text
main ───────────────────────────────●  稳定/可发布（只经 dev 或 hotfix 进入）
                                     ▲ merge（需你确认）
dev  ──●────●────●───────────────────┘  集成点（接收所有 feature）
       │    │    │
  feature/  feature/  feature/        从 dev 拉，merge 回 dev
  auth      checkin   plan
```

## 命名约定

- `feature/<name>` 的 `<name>` 与 `feature/<name>/` 模块目录名一致（如 `feature/auth`）；非模块功能用 kebab-case 短名（如 `feature/onboarding-flow`）。
- `<name>` 一律 kebab-case：小写、短横线分隔，不混用下划线。

## 各分支规则

- **feature**：从 dev 拉 → 开发 → 跑 `bash scripts/verify.sh` → merge 回 dev。一次 feature 一个主题。
- **dev**：集成点，保持可构建；合入前必须通过完整验证。
- **main**：只放可发布状态；进入 main 必须经人工确认。

## 自动化边界

| 动作 | Claude 行为 |
|------|-------------|
| 从 dev 拉 `feature/<name>` | ✅ 自动 |
| 按 `type(scope): description` 提交 | ✅ 自动 |
| 跑 `scripts/verify.sh` 作为「完成」证据 | ✅ 自动 |
| merge 回 `dev` | ⚠️ 默认先给 diff，确认后合 |
| merge 到 `main` | ❌ 永远先问你，绝不自动 |
| rebase / force-push | ❌ 需显式确认 |
| 删除远程分支 | ⚠️ 确认后执行 |

## 操作清单

```bash
# 开始一个 feature（以 auth 为例）
git checkout dev && git pull
git checkout -b feature/auth

# ...开发、按 type(scope): description 提交...

# 完成后合并回 dev
bash scripts/verify.sh                    # 必须先通过
git checkout dev && git pull
git merge --no-ff feature/auth            # --no-ff 保留 feature 边界，便于追溯
git push origin dev

# dev 稳定后合入 main（需你确认）
git checkout main && git pull
git merge --no-ff dev
git push origin main
# 发布时按需打 tag：git tag -a v0.x.y -m "..." && git push origin --tags
```

## 关联

- 决策记录：[decisions/0005-branching-strategy.md](decisions/0005-branching-strategy.md)
- 提交格式：[conventions.md](conventions.md)
- 构建与发布：[deployment.md](deployment.md)