document-types.md

# 文档类型策略

每种文档类型对应不同的**目标受众、分析重点、章节结构和写作规范**。生成前必须明确类型。

SDLC 链路对应关系：
```
BRD/MRD (立项) → PRD (需求) → HLD/DDD (架构) → LLD (详设) → 编码指南 (实现) → 测试文档 BDD/TDD/SIT/E2E/UAT (验证) → 运营手册 (运维) → SLI/SLO (稳定性) → CI/CD (发布)
```

---

## 类型 A0：BRD / MRD（商业需求 / 市场需求文档）

**目标受众**：决策层、投资人、业务负责人  
**核心问题**：为什么做这件事？做了能解决什么业务问题？边界在哪里？  
**从代码提取**：系统的核心能力范围（路由/功能清单） + 未覆盖的场景（注释中的 TODO/限制说明） + 价值产出（业务数据结构推断的商业模型）

### 章节结构

```
# [产品名] 商业需求文档

## 1. 背景与机会
  - 当前存在什么业务痛点（从代码注释/README 推断，或标注 〔INFER〕）
  - 目标市场与用户群体

## 2. 产品目标
  - 核心价值主张（1-3句）
  - 成功指标（可量化的业务目标，如"减少X% 的人工操作"）

## 3. 功能范围概览
  - 在范围内（从路由/功能清单整理）
  - 明确不在范围内（从代码限制、TODO、错误处理边界推断）

## 4. 干系人分析
  - 角色列表（从权限枚举推断）+ 核心诉求

## 5. 风险与假设
  - 已识别风险
  - 关键假设（需要人类确认的 〔INFER〕 条目）

## 6. 待裁决问题
```

### 写作规范
- 语言业务化，禁用技术术语（替换规则同运营手册，参见 [references/document-structure.md](./references/document-structure.md)；常见替换：API→接入方式、Token→令牌、Webhook→回调通知）
- 大量使用 `〔INFER〕` 标注（因为商业意图往往不直接写在代码里）
- 每个推断附上来源（"从认证模块的角色定义推断"）

---

## 类型 A：运营手册（Operations Manual）

**目标受众**：不懂技术的管理员、操作员、运营人员  
**核心问题**：这个功能是什么、怎么用、会影响什么、有什么风险  
**从代码提取**：UI 文案 → 表单字段 → 业务规则 → 副作用 → 权限

### 章节结构

```
# [系统名] 管理员操作手册

## 关于本手册
  1. 系统是什么（定位图：Mermaid graph LR，展示系统在业务中的角色）
  2. 核心设计理念（表格：理念 | 含义 | 对操作人员的影响）
  3. 如何使用本手册（Mermaid flowchart，引导不同角色找到入口）

## 第N章 [模块名]

  ### 🔗 功能前置条件与依赖链路        ← 每章必须，不可省略
  ### 📊 功能配置全局影响追踪矩阵      ← 每章必须，不可省略（4列，含算法/策略列）

  ### [问题式标题]？
    - 功能说明（1句）
    - 💡 设计背景（痛点，推断不出时省略）
    - 操作步骤 + Mermaid 流程图
    - 系统状态影响（生效时机、影响范围）
    - ⚠️ 危险 / 📌 注意（按等级标注）
    - 业务规则（公式/条件/上下限）
    - 关联影响表
    - 🔧 已知局限

## 附录（按系统实际情况决定）
```

### 写作规范

- **语言**：口语化，禁用技术术语（术语替换规则见下方）
- **格式**：问答式，每个功能是一个"问题"
- **🔗 前置链路写法**：`[上游模块] ➔ [上游模块] ➔ **[当前]** ➔ [下游模块]`，注明"深N层"
- **📊 影响矩阵第4列**：`**策略名称**：底层机制说明（1-2句）`，不可只写"影响计费"

**术语替换**（操作手册专用）：

| 禁止 | 替换 |
|------|------|
| API / 接口 | 调用方式 / 接入方式 |
| Token | 令牌 / 凭证 |
| JSON | 配置内容 |
| HTTP / 请求 | 操作 / 访问 |
| 数据库 | 系统数据 |
| 缓存 | 临时记录 |
| 中间件 | （描述效果，不提中间件） |
| Webhook | 回调通知 |
| 正则 | 匹配规则 |

---

## 类型 B：PRD 需求文档（Product Requirements Document）

**目标受众**：产品经理、研发负责人、验收方  
**核心问题**：系统应该做什么、边界在哪里、验收标准是什么  
**从代码提取**：已有功能 → 反推需求 → 识别隐含规则 → 找出缺失或不完整的部分

### 章节结构

```
# [系统名] 产品需求文档

## 1. 背景与目标
  - 系统解决的核心问题（1-2段）
  - 目标用户画像（表格：角色 | 主要使用场景 | 核心诉求）
  - 核心价值主张

## 2. 功能范围
  - 功能全景图（Mermaid mindmap 或 graph）
  - 在范围内 / 不在范围内（明确边界）

## 3. 功能需求（每个功能模块一节）
  ### 3.N [功能名]
  - 用户故事：作为[角色]，我希望[做什么]，以便[获得什么]
  - 功能描述
  - 业务规则（可量化的条件/公式/约束）
  - 异常场景处理
  - 验收标准（可测试的条件列表）

## 4. 非功能需求
  - 性能要求
  - 安全要求
  - 兼容性要求

## 5. 待确认问题清单
  （分析过程中发现的模糊点、矛盾点）
```

### 写作规范

- 语言面向产品/业务侧，避免技术实现词汇；当必须提及技术概念时，括号内补充业务含义（如"令牌（用户调用凭据）"）
- 每条验收标准必须**可测试**（有输入、有预期输出）
- 业务规则用**结构化条件**描述：`当[条件]时，系统应[行为]`
- 不确定的地方列入"待确认问题清单"，不猜测
- 引用已有代码时，描述**行为**而非实现（"系统限制每分钟最多操作100次"而非"rate limiter"）

---

## 类型 C：HLD 概要设计（High-Level Design）

**目标受众**：架构师、技术负责人、跨团队协作的开发者  
**核心问题**：系统由哪些部分组成、各部分如何交互、关键设计决策是什么  
**从代码提取**：目录结构 → 模块边界 → 依赖关系 → 关键数据流 → 技术选型

### 章节结构

```
# [系统名] 概要设计文档

## 1. 系统概述
  - 系统定位与职责（1段）
  - 系统上下文图（Mermaid C4-style：外部系统 ↔ 本系统 ↔ 数据存储）

## 2. 架构总览
  - 架构风格（分层/微服务/事件驱动/...）
  - 分层架构图（Mermaid graph TD）
  - 请求处理主链路（Mermaid sequenceDiagram）

## 3. 模块划分
  每个模块一节：
  ### 3.N [模块名]
  - 职责说明（1-3句）
  - 对外接口概览（输入/输出，不展开实现）
  - 依赖的其他模块
  - 关键设计约束

## 4. 数据模型概览
  - 核心实体关系图（Mermaid erDiagram）
  - 重要字段说明（非全量，只说关键字段）

## 5. 关键设计决策（ADR 风格）
  每条决策：
  - 决策标题
  - 背景（为什么需要做这个决策）
  - 选项对比（表格：方案 | 优点 | 缺点）
  - 采用方案 + 理由
  - 后果（trade-off）

## 6. 跨切面关注点
  - 认证与授权机制
  - 错误处理策略
  - 日志与可观测性
  - 配置管理方式
```

### 写作规范

- 图优先：每个模块必须有 Mermaid 图，文字是补充
- 决策要说**理由**，不能只写"选用了X方案"
- 不展开实现细节（实现在 LLD），聚焦"是什么"和"为什么"

---

## 类型 D：LLD 详细设计（Low-Level Design）

**目标受众**：实现该模块的开发者  
**核心问题**：具体怎么实现、接口是什么、数据结构是什么、异常如何处理  
**从代码提取**：函数签名 → 数据结构 → 流程逻辑 → 状态机 → 错误处理路径

### 章节结构

```
# [系统名 / 模块名] 详细设计文档

## 1. 模块概述
  - 在系统中的位置（承接哪个 HLD 模块）
  - 职责边界

## 2. 接口设计（每个对外接口一节）
  ### [接口名]
  - 用途（1句）
  - 输入参数（表格：参数名 | 类型 | 必填 | 说明 | 约束）
  - 输出（结构说明）
  - 错误码（表格：错误码 | 触发条件 | 调用方处理建议）

## 3. 数据结构
  - 核心数据结构定义（伪代码或类图）
  - 字段约束说明
  - 重要枚举值含义

## 4. 核心流程（每个主要流程一节）
  ### [流程名]
  - Mermaid flowchart（包含分支、异常路径）
  - 关键步骤说明
  - 并发/事务注意事项

## 5. 状态机（如有）
  - Mermaid stateDiagram-v2
  - 各状态说明 + 转换触发条件

## 6. 异常处理策略
  - 异常分类（可恢复 / 不可恢复）
  - 每类异常的处理方式

## 7. 性能与限制
  - 预期规模（数据量、并发量）
  - 已知性能瓶颈
  - 设计边界（超出什么范围会失效）
```

### 写作规范

- 接口必须有**完整的错误码表**
- 流程图必须包含**异常路径**（不只是 happy path）
- 并发场景要明确说明是否需要加锁/事务

---

## 类型 E：编码指南（Coding Guide）

**目标受众**：向项目贡献代码的开发者  
**核心问题**：代码该怎么写、有什么约定、踩坑要注意什么  
**从代码提取**：现有代码模式 → 命名规范 → 工具配置 → 注释规范 → 关键约束

### 章节结构

```
# [系统名] 编码指南

## 1. 开发环境
  - 依赖与版本要求
  - 初始化步骤
  - 常用命令

## 2. 项目结构说明
  - 目录树（只到2-3层）+ 每层的职责说明
  - 新文件应该放哪里的决策规则

## 3. 代码规范
  ### 命名约定（表格：类型 | 规范 | 示例）
  ### 文件组织约定
  ### 注释规范

## 4. 模块实现规范（每个核心模块一节）
  - 正确的实现模式（代码示例）
  - 禁止的模式（反例 + 原因）
  - 常见陷阱

## 5. 关键依赖使用规范
  （项目中有特殊约定的第三方库：如"必须用 common.Marshal 而非 json.Marshal"）

## 6. 测试规范
  - 测试文件命名与位置
  - 必须覆盖的测试类型
  - Mock 约定

## 7. 提交与 CR 规范
  - commit message 格式
  - CR checklist
```

### 写作规范

- 用**示例代码**说明，不要只写规则文字
- 反例要注明**为什么不对**，不只是"不要这样做"
- 从现有代码归纳规范，不发明不存在的约定

---

## 类型 F：测试文档（Test Document）

**目标受众**：QA 工程师、开发者做自测  
**核心问题**：需要测什么、边界在哪里、怎么验证  
**从代码提取**：业务规则 → 校验逻辑 → 状态转换 → 错误处理 → 权限边界

### 章节结构

```
# [系统名 / 模块名] 测试文档

## 1. 测试范围
  - 包含哪些模块/功能
  - 不包含什么（明确边界）
  - 测试环境要求

## 2. 功能测试用例（每个功能模块一节）
  ### [功能名]
  用例表格：
  | 用例ID | 场景描述 | 前置条件 | 操作步骤 | 预期结果 | 优先级 |

## 3. 边界与异常测试
  - 输入边界值（最小/最大/空/null）
  - 权限边界（越权访问、无权操作）
  - 状态边界（未初始化、已完成、已删除 等状态下的操作）
  - 并发场景（如有）

## 4. 集成测试点
  - 模块间交互的关键路径
  - 外部依赖的 mock 策略

## 5. 回归测试清单
  （按优先级排序的核心场景，每次发版必测）

## 6. 已知问题与测试局限
  - 已知 bug 或不稳定行为
  - 无法自动化测试的场景
```

### 写作规范

- 每条用例必须有**明确的预期结果**（不能写"正常运行"）
- 边界值必须来自**代码中实际的校验逻辑**（不能凭感觉）
- 优先级：P0 = 核心流程不可用；P1 = 主要功能异常；P2 = 边缘场景

---

## 类型 G：DDD / 领域设计文档

**目标受众**：架构师、领域专家、后端开发  
**核心问题**：核心域是什么、领域边界怎么划、聚合根和领域事件是什么  
**从代码提取**：实体/聚合类 → 领域事件定义 → 服务边界 → 不变量约束 → 值对象

### 章节结构

```
# [系统名] 领域设计文档

## 1. 战略设计
  - 核心域 / 支撑域 / 通用域划分（表格 + Mermaid graph）
  - 限界上下文地图（Mermaid graph，含上下文关系类型：ACL/OHS/PL/CF）

## 2. 战术设计（每个限界上下文一节）
  ### [上下文名]
  - 聚合根与实体（Mermaid classDiagram）
  - 值对象列表（表格：名称 | 属性 | 不变量）
  - 领域事件（表格：事件名 | 触发条件 | 携带数据 | 消费方）
  - 领域服务（跨聚合的操作）
  - 资源库接口（数据访问契约，不含实现）

## 3. 通用语言词汇表
  （项目特定术语 → 业务含义，消除二义性）

## 4. 待裁决问题
  （模型设计的争议点，需领域专家确认）
```

### 写作规范
- 术语要有**定义**，消除歧义（"订单"在这里指什么）
- 聚合边界划分要说明**为什么**（一致性边界 / 业务规则边界）
- 从代码推断的领域模型大量使用 `〔INFER〕`，需领域专家校准

---

## 类型 H：测试文档扩展（BDD / SIT / E2E / UAT）

> 对应不同测试阶段，在类型 F 基础上扩展，选择对应节填写。

**BDD（行为驱动开发）**：从代码提取用户故事，补全 Given-When-Then 格式：
```
场景：[业务场景名]
  Given [前置状态]
  When  [用户执行什么操作]
  Then  [系统应该产生什么结果]
  And   [额外断言]
```
来源：单元测试文件 + 业务规则代码（倒推场景描述）

**SIT（系统集成测试）**：关注模块间交互路径：
- 识别系统的主要集成点（调用外部服务、消息队列、数据库事务）
- 每个集成点：正常路径 + 超时/失败的降级策略
- 来源：HTTP client 调用、队列消费者、事务边界代码

**E2E（端到端测试）**：关注完整业务流程：
- 从路由/导航定义梳理主要用户旅程（Happy Path）
- 每条旅程：起点状态 → 操作序列 → 终点状态 → 验证点
- 来源：路由定义 + 权限配置 + 业务状态机

**UAT（用户验收测试）**：面向业务方，语言非技术化：
- 把 E2E 测试用例翻译为业务语言
- 验收标准来自 PRD/BRD 的验收条件
- 每条用例附"业务价值"说明（帮助业务方理解为什么要测这条）

---

## 类型 I：SLI / SLO / 监控文档

**目标受众**：SRE、运维工程师、技术负责人  
**核心问题**：服务的可靠性目标是什么、用什么指标度量、告警阈值是多少  
**从代码提取**：日志埋点 → 指标上报 → 健康检查 → 错误率计算 → 超时配置

### 章节结构

```
# [系统名] 可观测性与 SLO 文档

## 1. 服务依赖拓扑
  - Mermaid graph（展示服务、数据库、外部依赖、消息队列的关系）
  - 关键路径标注（哪条路径宕机会影响核心业务）

## 2. SLI 指标定义
  表格：指标名 | 计算方式 | 数据来源（日志/指标/Trace）| 采集频率

## 3. SLO 目标
  表格：服务 | SLI | 目标值 | 错误预算（月）| 责任方

## 4. 告警规则
  表格：告警名 | 触发条件 | 严重度 | 通知渠道 | 响应 SLA | 处理手册链接

## 5. 关键大盘（Dashboard）
  - 推荐监控面板布局（分层：基础设施层 → 服务层 → 业务层）
  - 每个面板的核心指标

## 6. 事故响应指南
  - 常见故障模式 + 排查思路（Mermaid flowchart）
  - 降级策略与回滚步骤
```

### 写作规范
- SLO 目标必须是**可测量的百分比或具体数值**（不能写"高可用"）
- 告警规则必须附**处理手册链接或内联处理步骤**，不能只报警不指导
- 从代码提取：超时配置值 → 用于设置告警阈值基准；错误码 → 用于定义错误率 SLI

---

## 类型 J：CI/CD 流水线文档

**目标受众**：DevOps 工程师、开发者、发布管理员  
**核心问题**：代码怎么从提交到上线、每个环节做了什么、出问题怎么回滚  
**从代码提取**：`.github/workflows/`、`Jenkinsfile`、`Makefile`、`Dockerfile`、`docker-compose.yml`、k8s 配置

### 章节结构

```
# [系统名] CI/CD 流水线文档

## 1. 流水线总览
  - Mermaid flowchart（从 git push 到生产部署的完整流程）
  - 各环境说明（表格：环境名 | 用途 | 部署触发条件 | 访问限制）

## 2. CI 阶段（每个 Job 一节）
  - 触发条件
  - 执行步骤（列表）
  - 通过条件（什么情况下阻塞合并）
  - 产出物（构建制品、测试报告等）

## 3. CD 阶段
  - 部署策略（蓝绿/滚动/金丝雀）
  - 环境提升规则（什么条件才能进入下一个环境）
  - 健康检查与自动回滚条件

## 4. 配置与密钥管理
  - 环境变量来源（不写值，只写来源位置）
  - 密钥轮换流程

## 5. 回滚手册
  - 触发回滚的条件
  - 具体操作步骤（命令级别）
  - 数据库迁移的回滚注意事项

## 6. 常见故障排查
  - 流水线失败的常见原因 + 解决方法（表格）
```

### 写作规范
- 步骤要**命令级别**，不写"部署到服务器"这种模糊描述
- 回滚手册要**可在生产压力下直接执行**，不能含糊
- 不写密钥值，只写"从 Vault/环境变量/配置中心 读取"