# 需求生命周期与 Git 协作说明

本文面向开发同事和 AI，说明一个需求如何从提出、设计、开发、测试走到稳定分支。
详细 Gate 规则以同目录的 [SKILL.md](SKILL.md) 和仓库
[生命周期流程](../../../docs/governance/生命周期流程.md) 为准。

## 核心原则

- `master` 是稳定基线，禁止直接提交。
- 一个需求使用一个 `feature_id` 和一个共享 feature 分支。
- 需求和设计先进入 `master`，通过开发 Gate 后再拉 feature 分支。
- 已推送的共享 feature 分支只允许 merge，不允许 rebase 或 force-push。
- feature 分支通过测试和评审后，以 merge commit 合入 `master`。
- 团队不强制普通提交格式、提交粒度或个人任务分支。

## 完整生命周期

```mermaid
flowchart TD
    A["提出需求并分配 feature_id"] --> B["docs/FEAT-... 编写需求、设计、测试与开发计划"]
    B --> C{"文档评审通过?"}
    C -->|否| B
    C -->|是| D["通过 PR 合入 master"]
    D --> E{"ready_for_development Gate"}
    E -->|未通过| B
    E -->|通过| F["从已记录的 origin/master SHA 创建 feature/FEAT-..."]
    F --> G["团队在共享 feature 分支开发"]
    G --> H["合入最新 origin/master 并执行测试"]
    H --> I{"ready_for_merge Gate"}
    I -->|未通过| G
    I -->|通过| J["feature PR 以 merge commit 合入 master"]
    J --> K["docs/FEAT-...-closeout 记录合并 SHA 与最终结论"]
    K --> L["需求完成并删除远程 feature 分支"]
```

## 分支关系

```mermaid
gitGraph
    commit id: "稳定 master"
    branch docs/FEAT
    checkout docs/FEAT
    commit id: "需求与设计"
    commit id: "测试与开发计划"
    checkout main
    merge docs/FEAT id: "文档评审通过"
    branch feature/FEAT
    checkout feature/FEAT
    commit id: "开发提交 A"
    commit id: "开发提交 B"
    checkout main
    commit id: "其他稳定变更"
    checkout feature/FEAT
    merge main id: "同步 master"
    commit id: "测试结果"
    checkout main
    merge feature/FEAT id: "需求合并"
    branch docs/FEAT-closeout
    checkout docs/FEAT-closeout
    commit id: "收尾记录"
    checkout main
    merge docs/FEAT-closeout id: "生命周期完成"
```

图中的 `main` 表示本仓库实际使用的 `master`。部分 Mermaid 渲染器将主线固定显示为
`main`，不影响真实分支名称。

## 分支命名

| 用途 | 名称 |
|---|---|
| 需求和设计文档 | `docs/FEAT-YYYYMM-NNN-short-name` |
| 共享开发 | `feature/FEAT-YYYYMM-NNN-short-name` |
| 合并后收尾 | `docs/FEAT-YYYYMM-NNN-short-name-closeout` |
| 生产紧急修复 | `hotfix/<short-name>` |
| 跨需求临时联调 | `integration/<feature-a>-<feature-b>` |

## 开始开发

开发负责人确认 `ready_for_development` Gate 通过后，记录准确的
`origin/master` 基线 SHA，再创建共享分支：

```bash
git fetch origin
git switch master
git pull --ff-only origin master
git switch -c feature/FEAT-YYYYMM-NNN-short-name
git push -u origin feature/FEAT-YYYYMM-NNN-short-name
```

创建分支和 push 必须获得明确授权。不要从尚未同步的本地 `master` 创建需求分支。

## 日常开发

首次拉取共享分支：

```bash
git fetch origin
git switch --track origin/feature/FEAT-YYYYMM-NNN-short-name
```

已有本地分支时，在开始工作和 push 前同步团队提交：

```bash
git switch feature/FEAT-YYYYMM-NNN-short-name
git pull --no-rebase origin feature/FEAT-YYYYMM-NNN-short-name
```

完成一个可工作的改动后正常提交和推送：

```bash
git add <本次相关文件>
git commit -m "简要说明本次改动"
git push origin feature/FEAT-YYYYMM-NNN-short-name
```

普通提交信息不要求固定前缀。不要使用 `git push --force`，也不要对已共享的 feature
分支执行 rebase。

## 同步 master

最终评审前必须把最新稳定代码合入 feature 分支：

```bash
git fetch origin
git switch feature/FEAT-YYYYMM-NNN-short-name
git merge origin/master
```

解决冲突后重新执行改动模块的编译、测试和适用的架构测试。同步完成后再 push feature
分支并发起 `feature/FEAT-... -> master` PR。

## 两个硬 Gate

### 进入开发 `ready_for_development`

- 需求录入和 PRD 已批准，验收标准与非目标明确。
- 必需的概要设计、详细设计、ADR、接口和安全文档已批准。
- 测试计划已批准，开发计划可执行。
- 没有阻塞性待确认项。
- 已确认 `origin/master` 并记录基线 SHA。

### 合入稳定分支 `ready_for_merge`

- 已合入最新 `origin/master`，不存在未解决冲突。
- 需求、设计、实现和接口契约一致。
- 测试结果已记录，规定的编译、测试和架构检查通过。
- 没有阻塞缺陷、安全问题或接口差异。
- feature 到 master 的 PR 已通过人工评审。

## 特殊情况

- **需求暂停**：专题状态改为 `paused`，保留 feature 分支；恢复时重新同步
  `master` 并检查 Gate。
- **需求取消**：专题状态改为 `cancelled`，未完成代码不得合入 `master`。
- **需求实质变化**：暂停相关实现，更新需求或设计并重新过 Gate；独立范围建立新的
  `feature_id`。
- **跨需求依赖**：feature 分支不得互相合并。依赖需求先合入 `master`；确需并行联调时
  使用一次性 integration 分支，该分支不能直接合入 `master`。
- **生产紧急修复**：使用 `hotfix/<short-name>`，至少记录故障、修复范围和验证结果，
  仍通过 PR 合入 `master`，事后补齐需求记录。

## AI 执行边界

AI 可以自动检查文档、分支、工作区、远程同步状态和 Gate，也可以给出推荐命令。
创建分支、提交、push、创建或合并 PR、删除远程分支前，必须获得用户明确授权。