emoon-backend/docs

Docs as Code 生命周期手册

本手册是团队的“文档型项目经理”。当一个需求从想法进入团队协作后， 必须用文档记录它的编号、讨论、需求、设计、决策、开发进度、测试结果和最终状态。

本手册的目标不是增加形式负担，而是在缺少专职产品、项目经理、设计和测试角色时， 用可版本化、可追溯、可被 Agent 阅读的文档补齐流程。

适用场景

以下场景必须先阅读本手册，再决定下一步产出：

• 新需求、新专题、新模块、新接口开始前
• 用户问“下一步该做什么”
• 用户要求补需求、补设计、补 ADR、补测试记录
• 准备进入编码，但需求或设计文档不完整
• 准备验收、上线或归档
• Agent 不确定某个需求当前处于哪个阶段

核心原则

1. 一个需求只有一个主线编号：feature_id
2. 每一篇正式文档都有唯一编号：doc_id
3. 同一需求的所有阶段文档放在同一个专题目录下
4. 文档状态必须显式记录，不能只靠文件名判断
5. 允许跳过低价值文档，但必须在专题索引中写明原因
6. 进入编码前，至少要有需求边界、设计边界和验收口径
7. 涉及架构取舍、模块边界、接口契约、安全合规时，必须留痕

目录入口

新需求、项目、专题统一放入：

docs/initiatives/<feature_id>/

feature_id 格式：

FEAT-YYYYMM-NNN-short-name

示例：

docs/initiatives/FEAT-202606-001-unified-entry-client/

专题目录推荐结构：

README.md                  # 专题索引和当前状态
intake.md                  # 需求录入和初步判断
prd.md                     # 需求文档
outline-design.md          # 概要设计
detailed-design.md         # 详细设计
api.md                     # 接口说明或 OpenAPI 链接
dev-progress.md            # 开发进度和阶段记录
test-plan.md               # 测试计划和验收方案
test-result.md             # 测试结果和遗留问题
meeting-notes/             # 会议纪要
assets/                    # 专题私有图片和附件

不是每个需求都必须拥有所有文档。缺省规则是：可以裁剪，但必须说明裁剪原因。

编号规则

feature_id 是需求主线编号：

FEAT-YYYYMM-NNN-short-name

doc_id 是单篇文档编号：

<TYPE>-YYYYMM-NNN

常用类型：

type	编号前缀	文档
intake	INT	需求录入
prd	PRD	需求文档
outline-design	ODS	概要设计
detailed-design	DDS	详细设计
design	DES	通用技术设计
api	API	接口说明
adr	ADR	架构决策记录
dev-progress	DEV	开发进度
test-plan	TST	测试计划
test-result	TRS	测试结果
meeting	MTG	会议纪要
standard	STD	工程规约
runbook	RUN	运维手册
research	RSH	调研材料
prompt	PMT	AI Prompt 或智能体配置

元数据

正式文档必须包含 Front Matter：

---
doc_id: PRD-202606-001
feature_id: FEAT-202606-001-unified-entry-client
type: prd
title: 统一入口客户端需求说明
status: draft
owner: 张三
created_at: 2026-06-16
updated_at: 2026-06-16
reviewers: []
related_docs:
  - INT-202606-001
related_modules:
  - emoon-openplatform
  - emoon-admin
tags:
  - 统一入口
  - 终端客户端
---

状态取值：

status	含义
draft	草稿
reviewing	评审中
approved	已确认
implemented	已实现或已落地
deprecated	已废弃
superseded	已被其他文档替代

更完整的分类和元数据规则见：

• 文档分类
• 元数据规范
• 生命周期流程

生命周期阶段

0. 需求录入

目标：把“想做什么”变成可追踪的需求主线。

必须产出：

• feature_id
• docs/initiatives/<feature_id>/README.md
• intake.md

intake.md 至少回答：

• 问题来源是什么
• 谁会使用
• 触发场景是什么
• 预期收益是什么
• 是否有明确截止时间
• 是否涉及外部系统、硬件、医院现场或第三方

阶段门禁：

• 没有 feature_id，不得创建后续正式文档
• 没有 intake.md，不得直接进入详细设计或编码

Agent 下一步判断：

• 如果只有口头想法，先创建 feature_id 和 intake.md
• 如果已有历史文档，先为历史文档补 doc_id 和 feature_id

1. 需求澄清

目标：把需求边界说清楚，避免直接用代码表达模糊需求。

必须产出：

• prd.md

prd.md 至少回答：

• 背景和目标
• 用户与场景
• 功能需求
• 非功能需求
• 非目标
• 验收标准
• 风险和依赖

阶段门禁：

• 没有验收标准，不得进入编码
• 没有非目标，需求容易失控，必须警示
• 涉及接口或外部系统时，必须标记后续需要 api.md

Agent 下一步判断：

• 如果 prd.md 不存在，先引导补 PRD
• 如果 PRD 没有验收标准，先补验收标准
• 如果 PRD 有争议，先产出会议纪要或待确认问题，不急于编码

2. 概要设计

目标：说明“用什么整体方案解决”，先定边界，再定细节。

建议产出：

• outline-design.md

必须覆盖：

• 总体方案
• 模块边界
• 主调用链路
• 数据流
• 外部系统依赖
• 关键风险

阶段门禁：

• 修改模块职责、跨模块依赖或公共能力时，必须补概要设计
• 涉及重大架构取舍时，必须创建 ADR

Agent 下一步判断：

• 如果需求影响多个模块，先补概要设计
• 如果只是小范围修复，可以在专题 README.md 说明跳过概要设计的原因

3. 详细设计

目标：把概要方案细化到开发可执行的程度。

建议产出：

• detailed-design.md

必须覆盖：

• 数据表和字段
• 状态机
• 接口入参出参
• 领域对象和服务职责
• 异常、幂等、重试、降级
• 鉴权、权限、脱敏、日志
• 测试策略

阶段门禁：

• 涉及数据模型变更时，必须补详细设计
• 涉及鉴权、脱敏、密钥、日志时，必须补安全说明
• 涉及对外接口时，必须补 api.md 或 OpenAPI

Agent 下一步判断：

• 如果设计缺少异常和安全章节，要先警示
• 如果实现方案会改变工程约束，先补 ADR 或工程规约说明

4. 架构决策

目标：记录不可轻易逆转的技术选择。

触发 ADR 的条件：

• 改变模块边界或依赖方向
• 引入新中间件、新协议、新外部系统
• 改变对外接口长期契约
• 在多个可行方案中选择其一
• 为性能、安全、可维护性做重要取舍

产出位置：

docs/adr/ADR-YYYYMM-NNN-short-title.md

阶段门禁：

• 命中 ADR 条件但没有 ADR 时，Agent 必须警示
• ADR 不替代设计文档，只记录决策、备选方案和后果

5. 接口契约

目标：让前后端、外部系统和 Agent 都能按同一契约协作。

建议产出：

• api.md
• docs/api/openapi/<name>.openapi.yaml

必须覆盖：

• 接口路径和方法
• 鉴权方式
• 请求和响应 Schema
• 错误码
• 幂等和重试约定
• 联调记录

阶段门禁：

• 只改代码不改接口文档，属于流程缺口
• OpenAPI 和说明文档冲突时，以 OpenAPI 为准，并修正文档

6. 开发进度

目标：记录实现过程中的范围变化、阶段结果和遗留问题。

建议产出：

• dev-progress.md

必须记录：

• 开发任务拆分
• 已完成内容
• 未完成内容
• 范围变更
• 阻塞项
• 关联 PR 或提交

阶段门禁：

• 需求范围变化时，必须同步更新 PRD 或记录变更原因
• 设计和实现不一致时，必须更新设计文档或记录偏差

7. 测试计划

目标：在验收前明确“怎样算通过”。

必须产出：

• test-plan.md

必须覆盖：

• 验收范围
• 测试环境
• 测试数据
• 用例列表
• 回归范围
• 不覆盖风险

阶段门禁：

• 没有 test-plan.md，不得宣称需求完成
• 没有回归范围，不能进入上线判断

8. 测试结果

目标：记录真实验证结果，而不是只说“已测”。

必须产出：

• test-result.md

必须记录：

• 执行时间
• 执行人或 Agent
• 环境和版本
• 通过项
• 失败项
• 遗留问题
• 最终结论

阶段门禁：

• 测试失败项未关闭时，专题状态不得标记为 implemented
• 自动化测试无法运行时，必须记录原因和人工替代验证

9. 上线和归档

目标：让需求最终状态可追踪。

必须更新：

• 专题 README.md
• dev-progress.md
• test-result.md
• 相关 ADR、接口、工程规约

归档要求：

• 专题 README.md 写明最终状态
• 关联文档状态更新为 implemented、deprecated 或 superseded
• 遗留问题进入 .scratch/<feature>/ 或后续 feature_id

Agent 工作方式

当用户要求推进某个需求时，Agent 必须按以下顺序检查：

1. 是否提供或能识别 feature_id
2. 是否存在 docs/initiatives/<feature_id>/README.md
3. 当前已有哪几类文档
4. 每篇文档的 status 是否允许进入下一阶段
5. 是否命中 ADR、接口、安全、测试等强制产物条件
6. 下一步应该产出哪一篇文档
7. 如果用户要求跳过，是否需要警示并记录跳过原因

Agent 回复建议格式：

当前阶段：需求澄清
已有文档：README.md、intake.md
缺口：prd.md 缺失，无法进入概要设计
下一步：产出 prd.md
建议动作：先补背景、目标、非目标、验收标准
警示：如果直接写设计或代码，需求边界不可追踪

跳过规则

允许跳过某些阶段，但必须满足：

• 在专题 README.md 的“流程裁剪”部分写明原因
• 说明风险
• 说明由哪个文档替代
• 说明是否需要后补

示例：

## 流程裁剪

| 阶段 | 是否跳过 | 原因 | 风险 | 替代记录 |
|---|---|---|---|---|
| 概要设计 | 是 | 单模块文案修复 | 低 | PRD 验收标准 |

模板

• 专题索引模板
• 需求录入模板
• 需求文档模板
• 概要设计模板
• 详细设计模板
• 接口说明模板
• 开发进度模板
• 测试验收模板
• 测试结果模板
• 会议纪要模板

历史文档

现有历史文档暂不强制移动。新文档必须按本规范创建；历史文档在发生实质修改、 被新需求引用、或进入归档整理时，逐步补充 Front Matter 并迁移到合适位置。