emoon-backend/docs/governance/生命周期流程.md

文档生命周期流程

新需求流程

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 是稳定基线，禁止直接提交。新需求使用以下主流程：

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 描述中应包含：

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 必须先警示，再说明可选路径：

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