# 文档生命周期流程

## 新需求流程

1. 创建 `feature_id`
2. 创建 `docs/initiatives/<feature_id>/专题索引.md`
3. 创建 `需求录入.md`，记录需求来源和初步判断
4. 创建 `需求文档.md`，状态为 `draft`
5. 需求评审后将 `需求文档.md` 状态改为 `approved`
6. 创建 `概要设计.md`，明确总体方案和模块边界
7. 复杂需求创建 `详细设计.md`
8. 必要时创建 ADR
9. 涉及接口时创建 `接口说明.md` 或关联 `docs/api/openapi/`
10. 开发中维护 `开发进度.md`
11. 验收前创建或更新 `测试计划.md`
12. 验收后创建或更新 `测试结果.md`
13. 上线或交付后更新专题 `专题索引.md` 状态

## 文档与 Git 分支联动

`master` 是稳定基线，禁止直接提交。新需求使用以下主流程：

```text
docs/<feature_id> -> master
master -> feature/<feature_id> -> master
master -> docs/<feature_id>-closeout -> master
```

1. 在 `docs/<feature_id>` 完成需求、设计、测试计划和开发计划并通过 PR 合入 `master`。
2. `ready_for_development` Gate 通过后，从已记录的 `origin/master` 提交创建并推送唯一的共享 `feature/<feature_id>` 分支。
3. 团队成员直接向共享 feature 分支提交；不强制任务分支、提交格式或提交粒度。
4. 已推送的共享 feature 分支禁止 rebase 和 force-push，只能通过 merge 同步 `master`。
5. 最终评审前必须合入最新 `origin/master` 并重新执行规定验证。
6. `ready_for_merge` Gate 通过后，以 PR 和 merge commit 合入 `master`，不 squash、不 rebase。
7. 使用 `docs/<feature_id>-closeout` 更新合并 SHA、最终状态、测试结论和遗留项。

### `ready_for_development` Gate

- 需求录入和需求文档已批准，验收标准、非目标完整。
- 按触发条件要求的概要设计、详细设计、ADR、接口和安全文档已批准。
- 测试计划已批准，开发实施计划可执行。
- 专题索引没有阻塞性待确认项。
- 工作区干净，已确认与 `origin/master` 的同步关系。
- 专题索引已记录分支名和准确的基线提交 SHA。

Gate 未通过时不得创建或推送 feature 分支。

### `ready_for_merge` Gate

- feature 分支已合入最新 `origin/master`，没有未解决冲突。
- 需求、验收标准、实现和必需文档一致。
- 已执行测试计划，测试结果记录通过项、失败项、遗留风险和结论。
- 改动模块的 Maven 编译、测试及适用的架构测试已通过。
- 不存在阻塞缺陷、安全问题或未处理的接口契约差异。
- feature 到 master 的 PR 已通过人工评审。

提交格式、提交数量和历史整洁度不作为 Gate。

### 并行、变更与异常

- feature 分支不得互相合并。跨需求依赖记录 `feature_id`，依赖先进入 `master`；必要时使用不得直接合入 `master` 的一次性 `integration/<feature-a>-<feature-b>` 分支联调。
- 普通调整在 feature 分支同步文档；范围、验收、接口、数据、安全或架构发生实质变化时，暂停相关实现、更新文档并重新过 Gate。
- 暂停需求标记为 `paused` 并保留远程 feature 分支；恢复时同步 `master` 并重新检查 Gate。
- 取消需求标记为 `cancelled`，未完成代码不得合入 `master`。
- 生产紧急故障可从 `master` 创建 `hotfix/<short-name>`，最低要求为故障描述、修复范围和验证结果；仍通过 PR 合入，事后补齐或关联需求记录。

### 自动化权限

Agent 可以自动检查分支、工作区、远程同步状态、文档状态和 Gate，也可以生成推荐名称和命令。创建分支、提交、push、创建或合并 PR、删除分支及其他远程变更必须获得用户明确授权；不得自动合并 `master`、force-push 或删除远程分支。

## 评审规则

| 文档 | 最低评审要求 |
|---|---|
| `prd` | 产品或业务负责人确认范围、非目标、验收标准 |
| `design` | 技术负责人确认模块边界、依赖、数据模型和风险 |
| `outline-design` | 技术负责人确认总体方案、模块边界和主调用链路 |
| `detailed-design` | 开发负责人确认数据模型、异常、安全和测试策略 |
| `api` | 前后端或外部系统联调方确认路径、Schema、错误码 |
| `adr` | 架构负责人确认决策、备选方案和后果 |
| `standard` | 团队负责人确认执行方式和检查方式 |
| `test-plan` | 开发和测试共同确认验收项 |
| `test-result` | 开发和测试共同确认失败项、遗留问题和最终结论 |

## Pull Request 要求

涉及以下任一情况时，PR 必须同步更新文档：

- 新增或变更业务能力
- 修改外部接口路径、参数、Schema、错误码
- 修改模块依赖、模块边界或工程约束
- 修改鉴权、权限、脱敏、日志或密钥处理
- 修改部署方式、运行参数或故障处理流程

PR 描述中应包含：

```text
Feature ID: FEAT-YYYYMM-NNN-short-name
Docs: PRD-YYYYMM-NNN, DES-YYYYMM-NNN
```

## 历史文档迁移

历史文档迁移分批进行：

1. 只补 Front Matter，不移动文件
2. 新需求引用到历史文档时，补充 `doc_id` 和 `status`
3. 确认没有外部链接依赖后，再移动到新目录
4. 移动后在原位置保留迁移说明或索引链接

## AI 使用规则

AI 处理需求或代码前，应优先查找：

1. `feature_id` 对应的 `docs/initiatives/<feature_id>/专题索引.md`
2. `related_docs` 中的录入、需求、设计、接口、ADR、测试文档
3. `related_modules` 对应代码模块
4. `docs/standards/` 和 `docs/architecture/` 中的约束文档

当用户没有提供 `feature_id` 时，AI 应基于关键词、模块名、接口名和 `tags` 检索候选文档，
并在执行前说明采用的上下文。

如果缺少前置文档，AI 必须先警示，再说明可选路径：

- 补齐前置文档
- 记录跳过原因后继续
- 将当前任务降级为探索或草案