# 文档生命周期流程

## 新需求流程

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` 状态

## 评审规则

| 文档 | 最低评审要求 |
|---|---|
| `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 必须先警示，再说明可选路径：

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