Etusivu Tutki Apua
Kirjaudu sisään
WangKang
/
emoon-backend
1
0
Fork 0
Tiedostot Ongelmat 0 Pull-pyynnöt 0 Wiki
Puu: d2eb419dfa
Haarat Tagit
emoon-backend
/
docs
/
文档中心.md

文档中心.md 12 KB
Historia Raaka

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/

专题目录推荐结构：

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

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

文件命名规则

需求专题目录使用 feature_id，便于机器检索和排序；专题内正式文档文件名使用中文， 便于团队成员直接阅读。不要用 prd.md、outline-design.md、test-result.md 这类英文缩写文件名表达文档类型。

推荐文件名：

生命周期阶段 推荐文件名
专题索引 专题索引.md
需求录入 需求录入.md
需求文档 需求文档.md
概要设计 概要设计.md
详细设计 详细设计.md
接口说明 接口说明.md，或更具体的中文名称
开发进度 开发进度.md，或放入 dev-progress/ 下的中文文件
测试计划 测试计划.md
测试结果 测试结果.md
会议纪要 meeting-notes/<会议主题>.md

doc_id、type、status、创建时间和关联关系必须写入 Front Matter， 不要塞进文件名。

编号规则

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>/专题索引.md
  • 需求录入.md

需求录入.md 至少回答：

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

阶段门禁：

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

Agent 下一步判断：

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

1. 需求澄清

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

必须产出：

  • 需求文档.md

需求文档.md 至少回答：

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

阶段门禁：

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

Agent 下一步判断：

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

2. 概要设计

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

建议产出：

  • 概要设计.md

必须覆盖：

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

阶段门禁：

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

Agent 下一步判断：

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

3. 详细设计

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

建议产出：

  • 详细设计.md

必须覆盖：

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

阶段门禁：

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

Agent 下一步判断：

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

4. 架构决策

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

触发 ADR 的条件：

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

产出位置：

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

阶段门禁：

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

5. 接口契约

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

建议产出：

  • 接口说明.md
  • docs/api/openapi/<name>.openapi.yaml

必须覆盖：

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

阶段门禁：

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

6. 开发进度

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

建议产出：

  • 开发进度.md

必须记录：

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

阶段门禁：

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

7. 测试计划

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

必须产出：

  • 测试计划.md

必须覆盖：

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

阶段门禁：

  • 没有 测试计划.md，不得宣称需求完成
  • 没有回归范围，不能进入上线判断

8. 测试结果

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

必须产出：

  • 测试结果.md

必须记录：

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

阶段门禁：

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

9. 上线和归档

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

必须更新：

  • 专题 专题索引.md
  • 开发进度.md
  • 测试结果.md
  • 相关 ADR、接口、工程规约

归档要求：

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

Agent 工作方式

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

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

Agent 回复建议格式：

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

跳过规则

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

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

示例：

## 流程裁剪

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

模板

历史文档

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