docs: 建立需求文档生命周期规范

.agents/skills/docs-lifecycle-manager/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: docs-lifecycle-manager
+description: Guide the emoon-backend team through its Docs as Code requirement lifecycle. Use when starting a new requirement, assigning or checking a feature_id, deciding the next document to produce, auditing lifecycle gaps, warning about skipped requirement/design/ADR/API/test documents, or acting as a document-based project manager before coding, testing, acceptance, or archive work.
+---
+
+# Docs Lifecycle Manager
+
+Use this skill as the project-manager layer for requirements in this repository.
+It keeps a requirement moving through documented stages before the team jumps into code.
+
+## Required Context
+
+Always read these files first:
+
+1. `docs/README.md`
+2. `docs/governance/doc-taxonomy.md`
+3. `docs/governance/doc-metadata.md`
+4. `docs/governance/doc-lifecycle.md`
+
+If the user provides a `feature_id`, read:
+
+```text
+docs/initiatives/<feature_id>/README.md
+```
+
+Then read every existing document referenced by that initiative index.
+
+## Lifecycle Order
+
+Use this order when inspecting or advancing a requirement:
+
+1. Intake: `intake.md`
+2. Requirement: `prd.md`
+3. Outline design: `outline-design.md`
+4. Detailed design: `detailed-design.md`
+5. ADR: `docs/adr/ADR-*.md` when triggered
+6. API contract: `api.md` or `docs/api/openapi/*.yaml` when triggered
+7. Development progress: `dev-progress.md`
+8. Test plan: `test-plan.md`
+9. Test result: `test-result.md`
+10. Archive: update initiative `README.md`
+
+Small changes may skip some stages only when the initiative `README.md` records the skipped stage,
+reason, risk, replacement record, and whether follow-up is required.
+
+## Triage Procedure
+
+When the user asks what to do next:
+
+1. Identify or create the `feature_id`.
+2. Locate the initiative directory.
+3. Inventory existing lifecycle documents and their `status`.
+4. Compare the inventory against the lifecycle order.
+5. Check trigger conditions for mandatory ADR, API, security, and test documents.
+6. Report the current stage, missing prerequisites, next document, and warning if the requested action skips required context.
+
+Use this response shape:
+
+```text
+当前阶段：...
+已有文档：...
+缺口：...
+下一步：...
+建议动作：...
+警示：...
+```
+
+## Gate Rules
+
+Warn before continuing when any rule is violated:
+
+- No `feature_id`: do not create later-stage documents.
+- No `intake.md`: do not jump to detailed design or code.
+- No `prd.md`: do not start design.
+- PRD has no acceptance criteria: do not code.
+- Multi-module impact: require outline design or an explicit skip record.
+- Data model, security, exception handling, or deployment changes: require detailed design.
+- Module boundary, dependency direction, long-lived contract, middleware, or major tradeoff: require ADR.
+- External or frontend-facing interface change: require API document and OpenAPI when applicable.
+- No `test-plan.md`: do not claim completion.
+- No `test-result.md`: do not mark the initiative `implemented`.
+
+## Document Creation
+
+Prefer repository templates under `docs/templates/`:
+
+- `initiative-readme-template.md`
+- `intake-template.md`
+- `prd-template.md`
+- `outline-design-template.md`
+- `detailed-design-template.md`
+- `api-template.md`
+- `dev-progress-template.md`
+- `test-plan-template.md`
+- `test-result-template.md`
+- `meeting-note-template.md`
+
+When creating a document:
+
+1. Copy the relevant template structure.
+2. Fill Front Matter with `doc_id`, `feature_id`, `type`, `title`, `status`, `owner`, `created_at`, and `updated_at`.
+3. Link previous-stage documents in `related_docs`.
+4. Add affected code modules to `related_modules`.
+5. Update the initiative `README.md` document index.
+
+## Output Rules
+
+Be strict about lifecycle gaps, but do not block useful exploration.
+
+If prerequisites are missing, offer one of three paths:
+
+- 补齐前置文档
+- 记录跳过原因后继续
+- 将当前任务降级为探索或草案
+
+Do not silently skip documentation stages.

.agents/skills/docs-lifecycle-manager/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Docs Lifecycle Manager"
+  short_description: "Guide a requirement through the team's Docs as Code lifecycle."
+  default_prompt: "Use this skill to inspect the current requirement documents, identify lifecycle gaps, and tell me the next document or decision to produce."

.gitignore

@@ -59,7 +59,11 @@ logs
 .qoder
 .claude
 openspec
-.agents
+.agents/*
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/docs-lifecycle-manager/
+!.agents/skills/docs-lifecycle-manager/**
 
 back-info/*
 .env

AGENTS.md

@@ -16,6 +16,12 @@
 
 单上下文布局：`CONTEXT.md` + `docs/adr/`。详见 `docs/agents/domain.md`。
 
+### Docs lifecycle
+
+需求生命周期以 `docs/README.md` 为总入口，并由 `.agents/skills/docs-lifecycle-manager/` 提供 Agent 执行规则。
+当用户提出新需求、询问下一步、要求补需求/设计/ADR/API/测试文档、或准备跳过文档直接编码时，
+必须先按该生命周期检查当前阶段和缺口。
+
 ## 工程约束速查
 
 所有 AI 编程工具写代码前先读取以下文档：
@@ -32,6 +38,7 @@
 
 | 场景 | 自动执行/提议的 Skill | 说明 |
 |------|---------------------|------|
+| 新需求录入/需求生命周期推进/询问下一步产出 | `docs-lifecycle-manager` | 先检查 `feature_id`、阶段文档和缺口 |
 | 写新功能/新模块/新接口 | `tdd` | 先写测试→红→绿→重构 |
 | 修改现有代码/重构 | `tdd` + `review` | 先读现有测试，改代码，跑全量测试，再 review diff |
 | 用户要求审查代码 | `review` | 读取 diff，检查正确性/安全性/测试覆盖 |

docs/README.md

@@ -0,0 +1,450 @@
+# Docs as Code 生命周期手册
+
+本手册是团队的“文档型项目经理”。当一个需求从想法进入团队协作后，
+必须用文档记录它的编号、讨论、需求、设计、决策、开发进度、测试结果和最终状态。
+
+本手册的目标不是增加形式负担，而是在缺少专职产品、项目经理、设计和测试角色时，
+用可版本化、可追溯、可被 Agent 阅读的文档补齐流程。
+
+## 适用场景
+
+以下场景必须先阅读本手册，再决定下一步产出：
+
+- 新需求、新专题、新模块、新接口开始前
+- 用户问“下一步该做什么”
+- 用户要求补需求、补设计、补 ADR、补测试记录
+- 准备进入编码，但需求或设计文档不完整
+- 准备验收、上线或归档
+- Agent 不确定某个需求当前处于哪个阶段
+
+## 核心原则
+
+1. 一个需求只有一个主线编号：`feature_id`
+2. 每一篇正式文档都有唯一编号：`doc_id`
+3. 同一需求的所有阶段文档放在同一个专题目录下
+4. 文档状态必须显式记录，不能只靠文件名判断
+5. 允许跳过低价值文档，但必须在专题索引中写明原因
+6. 进入编码前，至少要有需求边界、设计边界和验收口径
+7. 涉及架构取舍、模块边界、接口契约、安全合规时，必须留痕
+
+## 目录入口
+
+新需求、项目、专题统一放入：
+
+```text
+docs/initiatives/<feature_id>/
+```
+
+`feature_id` 格式：
+
+```text
+FEAT-YYYYMM-NNN-short-name
+```
+
+示例：
+
+```text
+docs/initiatives/FEAT-202606-001-unified-entry-client/
+```
+
+专题目录推荐结构：
+
+```text
+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` 是需求主线编号：
+
+```text
+FEAT-YYYYMM-NNN-short-name
+```
+
+`doc_id` 是单篇文档编号：
+
+```text
+<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：
+
+```yaml
+---
+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` | 已被其他文档替代 |
+
+更完整的分类和元数据规则见：
+
+- [文档分类](governance/doc-taxonomy.md)
+- [元数据规范](governance/doc-metadata.md)
+- [生命周期流程](governance/doc-lifecycle.md)
+
+## 生命周期阶段
+
+### 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 的条件：
+
+- 改变模块边界或依赖方向
+- 引入新中间件、新协议、新外部系统
+- 改变对外接口长期契约
+- 在多个可行方案中选择其一
+- 为性能、安全、可维护性做重要取舍
+
+产出位置：
+
+```text
+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 回复建议格式：
+
+```text
+当前阶段：需求澄清
+已有文档：README.md、intake.md
+缺口：prd.md 缺失，无法进入概要设计
+下一步：产出 prd.md
+建议动作：先补背景、目标、非目标、验收标准
+警示：如果直接写设计或代码，需求边界不可追踪
+```
+
+## 跳过规则
+
+允许跳过某些阶段，但必须满足：
+
+- 在专题 `README.md` 的“流程裁剪”部分写明原因
+- 说明风险
+- 说明由哪个文档替代
+- 说明是否需要后补
+
+示例：
+
+```markdown
+## 流程裁剪
+
+| 阶段 | 是否跳过 | 原因 | 风险 | 替代记录 |
+|---|---|---|---|---|
+| 概要设计 | 是 | 单模块文案修复 | 低 | PRD 验收标准 |
+```
+
+## 模板
+
+- [专题索引模板](templates/initiative-readme-template.md)
+- [需求录入模板](templates/intake-template.md)
+- [需求文档模板](templates/prd-template.md)
+- [概要设计模板](templates/outline-design-template.md)
+- [详细设计模板](templates/detailed-design-template.md)
+- [接口说明模板](templates/api-template.md)
+- [开发进度模板](templates/dev-progress-template.md)
+- [测试验收模板](templates/test-plan-template.md)
+- [测试结果模板](templates/test-result-template.md)
+- [会议纪要模板](templates/meeting-note-template.md)
+
+## 历史文档
+
+现有历史文档暂不强制移动。新文档必须按本规范创建；历史文档在发生实质修改、
+被新需求引用、或进入归档整理时，逐步补充 Front Matter 并迁移到合适位置。

docs/governance/doc-lifecycle.md

@@ -0,0 +1,75 @@
+# 文档生命周期流程
+
+## 新需求流程
+
+1. 创建 `feature_id`
+2. 创建 `docs/initiatives/<feature_id>/README.md`
+3. 创建 `intake.md`，记录需求来源和初步判断
+4. 创建 `prd.md`，状态为 `draft`
+5. 需求评审后将 `prd.md` 状态改为 `approved`
+6. 创建 `outline-design.md`，明确总体方案和模块边界
+7. 复杂需求创建 `detailed-design.md`
+8. 必要时创建 ADR
+9. 涉及接口时创建 `api.md` 或关联 `docs/api/openapi/`
+10. 开发中维护 `dev-progress.md`
+11. 验收前创建或更新 `test-plan.md`
+12. 验收后创建或更新 `test-result.md`
+13. 上线或交付后更新专题 `README.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>/README.md`
+2. `related_docs` 中的录入、需求、设计、接口、ADR、测试文档
+3. `related_modules` 对应代码模块
+4. `docs/standards/` 和 `docs/architecture/` 中的约束文档
+
+当用户没有提供 `feature_id` 时，AI 应基于关键词、模块名、接口名和 `tags` 检索候选文档，
+并在执行前说明采用的上下文。
+
+如果缺少前置文档，AI 必须先警示，再说明可选路径：
+
+- 补齐前置文档
+- 记录跳过原因后继续
+- 将当前任务降级为探索或草案

docs/governance/doc-metadata.md

@@ -0,0 +1,75 @@
+# 文档元数据规范
+
+所有新建正式文档必须使用 Markdown Front Matter。
+
+## 必填字段
+
+```yaml
+---
+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
+---
+```
+
+## 推荐字段
+
+```yaml
+reviewers:
+  - 李四
+related_docs:
+  - DES-202606-001
+related_modules:
+  - emoon-openplatform
+  - emoon-admin
+tags:
+  - 统一入口
+  - 终端客户端
+supersedes:
+superseded_by:
+source:
+```
+
+## 字段说明
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `doc_id` | 是 | 单篇文档唯一编号 |
+| `feature_id` | 否 | 所属需求、项目、专题；非专题类文档可为空 |
+| `type` | 是 | 文档类型，取值见 `doc-taxonomy.md` |
+| `title` | 是 | 文档标题 |
+| `status` | 是 | 生命周期状态 |
+| `owner` | 是 | 当前负责人 |
+| `created_at` | 是 | 创建日期，格式 `YYYY-MM-DD` |
+| `updated_at` | 是 | 最近实质更新日期，格式 `YYYY-MM-DD` |
+| `reviewers` | 否 | 评审人 |
+| `related_docs` | 否 | 关联文档 `doc_id` 列表 |
+| `related_modules` | 否 | 关联代码模块 |
+| `tags` | 否 | 检索标签 |
+| `supersedes` | 否 | 当前文档替代的旧文档 |
+| `superseded_by` | 否 | 替代当前文档的新文档 |
+| `source` | 否 | 来源链接、会议、外部资料 |
+
+## 状态
+
+| status | 含义 |
+|---|---|
+| `draft` | 草稿 |
+| `reviewing` | 评审中 |
+| `approved` | 已确认 |
+| `implemented` | 已实现或已落地 |
+| `deprecated` | 已废弃 |
+| `superseded` | 已被其他文档替代 |
+
+## 规则
+
+- 标题不承载编号、日期和状态，这些信息放在 Front Matter。
+- `doc_id` 一旦发布，不应复用给其他文档。
+- 文档发生实质内容变更时必须更新 `updated_at`。
+- 废弃文档不删除，改为 `deprecated` 或 `superseded`，并说明替代文档。
+- 涉及接口、架构边界、鉴权、脱敏、模块依赖的变更，必须补充关联文档。

docs/governance/doc-taxonomy.md

@@ -0,0 +1,77 @@
+# 文档分类
+
+## 组织原则
+
+文档按“需求/项目专题”聚合，按 `type` 元数据分类。
+
+目录不是唯一分类依据。稳定关联依赖以下字段：
+
+- `feature_id`：需求、项目、专题主线
+- `doc_id`：单篇文档唯一编号
+- `type`：文档类型
+- `status`：文档生命周期状态
+- `related_docs`：关联文档
+- `related_modules`：关联代码模块
+
+## 一级目录
+
+| 目录 | 用途 |
+|---|---|
+| `docs/initiatives/` | 需求、项目、专题主线文档 |
+| `docs/adr/` | 架构决策记录 |
+| `docs/api/` | 对外接口契约、OpenAPI、联调说明 |
+| `docs/architecture/` | 长期有效的系统架构和模块边界 |
+| `docs/standards/` | 工程规约、编码规范、架构红线 |
+| `docs/operations/` | 部署、运维、故障处理、Runbook |
+| `docs/templates/` | 文档模板 |
+| `docs/assets/` | 全局图片和附件 |
+| `docs/governance/` | 文档治理规则 |
+
+现有 `docs/需求文档/`、`docs/架构文档/`、`docs/接口文档/` 可作为历史目录保留，
+后续按批次迁移。
+
+## 文档类型
+
+| type | 编号前缀 | 用途 |
+|---|---:|---|
+| `intake` | `INT` | 需求录入、初步判断、来源记录 |
+| `prd` | `PRD` | 需求文档、业务目标、范围、验收口径 |
+| `outline-design` | `ODS` | 概要设计、总体方案、模块边界 |
+| `detailed-design` | `DDS` | 详细设计、数据模型、异常、安全和实现细节 |
+| `design` | `DES` | 技术设计、模块设计、数据模型、时序和边界 |
+| `api` | `API` | 接口说明、联调说明、OpenAPI 关联 |
+| `adr` | `ADR` | 架构决策记录 |
+| `dev-progress` | `DEV` | 开发进度、范围变化、阻塞项和阶段记录 |
+| `standard` | `STD` | 工程规约、编码规范、架构约束 |
+| `meeting` | `MTG` | 会议纪要、评审记录 |
+| `test-plan` | `TST` | 测试计划、验收方案、回归清单 |
+| `test-result` | `TRS` | 测试结果、失败项、遗留问题和结论 |
+| `runbook` | `RUN` | 部署、运维、故障处理步骤 |
+| `research` | `RSH` | 调研、竞品、技术预研 |
+| `prompt` | `PMT` | AI Prompt、智能体配置、Dify/FastGPT 提示词 |
+
+## 编号规则
+
+`feature_id`：
+
+```text
+FEAT-YYYYMM-NNN-short-name
+```
+
+`doc_id`：
+
+```text
+<TYPE>-YYYYMM-NNN
+```
+
+示例：
+
+```text
+FEAT-202606-001-unified-entry-client
+PRD-202606-001
+DES-202606-001
+API-202606-001
+MTG-202606-001
+```
+
+同一 `feature_id` 下可以有多篇不同 `type` 的文档。`doc_id` 必须全仓库唯一。

docs/templates/api-template.md

@@ -0,0 +1,48 @@
+---
+doc_id: API-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: api
+title: 接口说明标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs:
+  - PRD-YYYYMM-NNN
+  - DES-YYYYMM-NNN
+related_modules: []
+tags: []
+---
+
+# 接口说明标题
+
+## 契约位置
+
+- OpenAPI: `docs/api/openapi/<name>.openapi.yaml`
+
+## 接口列表
+
+| 方法 | 路径 | 说明 | 状态 |
+|---|---|---|---|
+| `POST` | `/api/example` | 示例接口 | draft |
+
+## 鉴权
+
+说明认证方式、权限要求和调用方身份。
+
+## 请求和响应
+
+以 OpenAPI 为准。本文只记录联调说明、特殊约定和示例。
+
+## 错误码
+
+| 错误码 | 含义 | 处理建议 |
+|---|---|---|
+|  |  |  |
+
+## 联调记录
+
+| 日期 | 参与方 | 结论 |
+|---|---|---|
+| YYYY-MM-DD |  |  |

docs/templates/design-template.md

@@ -0,0 +1,61 @@
+---
+doc_id: DES-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: design
+title: 技术设计标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs:
+  - PRD-YYYYMM-NNN
+related_modules: []
+tags: []
+---
+
+# 技术设计标题
+
+## 背景和目标
+
+说明本设计对应的需求、目标和约束。
+
+## 总体方案
+
+描述核心方案、模块分工和调用关系。
+
+## 模块边界
+
+| 模块 | 职责 | 不负责 |
+|---|---|---|
+| `emoon-xxx` |  |  |
+
+## 数据模型
+
+说明新增或变更的数据表、字段、状态机和数据流。
+
+## 接口和集成
+
+说明内部接口、外部接口、消息、任务和第三方系统依赖。
+
+## 安全和合规
+
+说明鉴权、权限、脱敏、日志、密钥、审计等处理。
+
+## 异常和降级
+
+说明失败场景、重试、幂等、补偿和降级策略。
+
+## 备选方案
+
+| 方案 | 优点 | 缺点 | 结论 |
+|---|---|---|---|
+| 方案 A |  |  |  |
+
+## 测试策略
+
+说明单元测试、集成测试、架构测试和回归范围。
+
+## 待确认问题
+
+- 问题

docs/templates/detailed-design-template.md

@@ -0,0 +1,56 @@
+---
+doc_id: DDS-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: detailed-design
+title: 详细设计标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs:
+  - PRD-YYYYMM-NNN
+  - ODS-YYYYMM-NNN
+related_modules: []
+tags: []
+---
+
+# 详细设计标题
+
+## 实现范围
+
+说明本设计覆盖的代码模块、接口、任务和数据变更。
+
+## 数据模型
+
+说明新增或变更的数据表、字段、索引、状态机。
+
+## 服务和对象职责
+
+| 类或组件 | 职责 | 备注 |
+|---|---|---|
+|  |  |  |
+
+## 接口细节
+
+说明内部接口、外部接口、消息、任务和参数约定。
+
+## 异常处理
+
+说明失败场景、错误码、重试、幂等、补偿和降级。
+
+## 安全和合规
+
+说明鉴权、权限、脱敏、日志、密钥、审计。
+
+## 配置和部署
+
+说明配置项、环境变量、开关、迁移脚本和部署注意事项。
+
+## 测试策略
+
+说明单元测试、集成测试、架构测试和回归范围。
+
+## 待确认问题
+
+- 问题

docs/templates/dev-progress-template.md

@@ -0,0 +1,44 @@
+---
+doc_id: DEV-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: dev-progress
+title: 开发进度标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs:
+  - PRD-YYYYMM-NNN
+  - ODS-YYYYMM-NNN
+related_modules: []
+tags: []
+---
+
+# 开发进度标题
+
+## 任务拆分
+
+| 任务 | 模块 | 状态 | 负责人 | 备注 |
+|---|---|---|---|---|
+|  |  | open |  |  |
+
+## 阶段记录
+
+| 日期 | 进展 | 风险 | 下一步 |
+|---|---|---|---|
+| YYYY-MM-DD |  |  |  |
+
+## 范围变更
+
+| 日期 | 变更 | 原因 | 是否同步 PRD/设计 |
+|---|---|---|---|
+|  |  |  |  |
+
+## 阻塞项
+
+- 阻塞项
+
+## 关联提交或 PR
+
+- 提交或 PR 链接

docs/templates/initiative-readme-template.md

@@ -0,0 +1,47 @@
+---
+feature_id: FEAT-YYYYMM-NNN-short-name
+title: 专题标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+tags:
+  - 标签
+---
+
+# 专题标题
+
+## 目标
+
+说明这个需求、项目或专题要解决的问题。
+
+## 文档索引
+
+| 类型 | 文档 | 状态 |
+|---|---|---|
+| 需求录入 | [intake.md](intake.md) | draft |
+| 需求 | [prd.md](prd.md) | draft |
+| 概要设计 | [outline-design.md](outline-design.md) | draft |
+| 详细设计 | [detailed-design.md](detailed-design.md) | draft |
+| 接口 | [api.md](api.md) | draft |
+| 开发进度 | [dev-progress.md](dev-progress.md) | draft |
+| 测试验收 | [test-plan.md](test-plan.md) | draft |
+| 测试结果 | [test-result.md](test-result.md) | draft |
+
+## 关联代码模块
+
+- `emoon-xxx`
+
+## 关联决策
+
+- `ADR-YYYYMM-NNN`
+
+## 当前状态
+
+记录当前推进状态、阻塞项和下一步动作。
+
+## 流程裁剪
+
+| 阶段 | 是否跳过 | 原因 | 风险 | 替代记录 |
+|---|---|---|---|---|
+| 概要设计 | 否 |  |  |  |

docs/templates/intake-template.md

@@ -0,0 +1,50 @@
+---
+doc_id: INT-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: intake
+title: 需求录入标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs: []
+related_modules: []
+tags: []
+---
+
+# 需求录入标题
+
+## 来源
+
+说明需求来自客户、医院现场、内部产品判断、技术债、故障复盘或其他来源。
+
+## 问题
+
+说明当前遇到的问题或机会。
+
+## 用户和场景
+
+说明谁会使用、在什么场景下触发。
+
+## 预期收益
+
+说明完成后希望改善什么指标、体验或交付能力。
+
+## 初步范围
+
+- 可能包含的内容
+- 明确不包含的内容
+
+## 依赖和风险
+
+- 外部系统
+- 硬件设备
+- 医院现场流程
+- 数据、安全或权限
+
+## 下一步
+
+- 补充 PRD
+- 组织需求评审
+- 进入探索

docs/templates/meeting-note-template.md

@@ -0,0 +1,42 @@
+---
+doc_id: MTG-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: meeting
+title: 会议主题
+status: approved
+owner: 记录人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs: []
+related_modules: []
+tags: []
+---
+
+# 会议主题
+
+## 基本信息
+
+| 项 | 内容 |
+|---|---|
+| 时间 | YYYY-MM-DD HH:mm |
+| 参会人 |  |
+| 记录人 |  |
+
+## 结论
+
+- 结论 1
+
+## 决策
+
+- 决策 1
+
+## 待办
+
+| 事项 | 负责人 | 截止时间 | 状态 |
+|---|---|---|---|
+|  |  |  | open |
+
+## 讨论记录
+
+记录关键争议、备选方案和未决问题。

docs/templates/outline-design-template.md

@@ -0,0 +1,54 @@
+---
+doc_id: ODS-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: outline-design
+title: 概要设计标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs:
+  - PRD-YYYYMM-NNN
+related_modules: []
+tags: []
+---
+
+# 概要设计标题
+
+## 背景
+
+说明本设计对应的需求和主要约束。
+
+## 总体方案
+
+说明核心方案、关键组件和主流程。
+
+## 模块边界
+
+| 模块 | 职责 | 不负责 |
+|---|---|---|
+| `emoon-xxx` |  |  |
+
+## 主调用链路
+
+说明用户请求、系统调用、外部系统交互的主路径。
+
+## 数据流
+
+说明关键数据从哪里来、到哪里去、在哪里持久化。
+
+## 外部依赖
+
+- HIS
+- Dify/FastGPT
+- 终端设备
+- 其他系统
+
+## 风险
+
+- 风险和待确认问题
+
+## 是否需要 ADR
+
+说明是否存在重大架构取舍，以及是否需要创建 ADR。

docs/templates/prd-template.md

@@ -0,0 +1,57 @@
+---
+doc_id: PRD-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: prd
+title: 需求标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs: []
+related_modules: []
+tags: []
+---
+
+# 需求标题
+
+## 背景
+
+说明业务背景、问题来源和现状约束。
+
+## 目标
+
+- 目标 1
+- 目标 2
+
+## 非目标
+
+- 本次不做的事项
+
+## 用户和场景
+
+说明目标用户、触发场景和核心流程。
+
+## 需求范围
+
+### 功能需求
+
+- 功能点
+
+### 非功能需求
+
+- 性能、稳定性、安全、兼容性等要求
+
+## 验收标准
+
+- Given/When/Then 或可验证的验收项
+
+## 风险和依赖
+
+- 外部系统、数据、权限、设备、排期等依赖
+
+## 变更记录
+
+| 日期 | 变更 | 负责人 |
+|---|---|---|
+| YYYY-MM-DD | 创建 | 负责人 |

docs/templates/test-plan-template.md

@@ -0,0 +1,44 @@
+---
+doc_id: TST-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: test-plan
+title: 测试验收方案标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs:
+  - PRD-YYYYMM-NNN
+  - DES-YYYYMM-NNN
+related_modules: []
+tags: []
+---
+
+# 测试验收方案标题
+
+## 验收范围
+
+说明本次验收覆盖和不覆盖的范围。
+
+## 测试环境
+
+说明环境、账号、数据、外部依赖和版本。
+
+## 验收用例
+
+| 编号 | 场景 | 步骤 | 预期结果 | 状态 |
+|---|---|---|---|---|
+| TST-001 |  |  |  | draft |
+
+## 回归范围
+
+- 需要回归的模块和接口
+
+## 风险
+
+- 未覆盖风险和后续补测计划
+
+## 结论
+
+说明是否通过验收，以及遗留问题。

docs/templates/test-result-template.md

@@ -0,0 +1,48 @@
+---
+doc_id: TRS-YYYYMM-NNN
+feature_id: FEAT-YYYYMM-NNN-short-name
+type: test-result
+title: 测试结果标题
+status: draft
+owner: 负责人
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+reviewers: []
+related_docs:
+  - TST-YYYYMM-NNN
+related_modules: []
+tags: []
+---
+
+# 测试结果标题
+
+## 执行信息
+
+| 项 | 内容 |
+|---|---|
+| 执行日期 | YYYY-MM-DD |
+| 执行人或 Agent |  |
+| 环境 |  |
+| 版本或提交 |  |
+
+## 执行结果
+
+| 用例编号 | 场景 | 结果 | 备注 |
+|---|---|---|---|
+| TST-001 |  | pass |  |
+
+## 自动化验证
+
+记录 Maven、单元测试、集成测试、架构测试等命令和结果。
+
+## 失败项
+
+- 失败项、影响和处理结论
+
+## 遗留问题
+
+- 遗留问题和后续跟踪方式
+
+## 最终结论
+
+说明是否通过验收，是否允许上线或归档。