# 需求文档范本

创建人员：<创建人员>  
文件职责：提供正式需求文档的通用结构范本，帮助需求 AI 写出可实现、可审核、不过度加码的需求文档。  
管理规范/模板：../../common/pro-doc/需求规范.md；../../common/pro-doc/需求文档范本.md。  
引用文件：需求规范.md；需求设计.md；需求审计报告.md；../../common/dev-doc/编码规范.md。  
记录方式：范本文档；需求文档结构变化时更新，具体项目复制后按项目内容填写。

## 1. 文档目标

说明本需求要解决什么问题。

```text
<一句话说明需求目标。>
```

## 2. 背景和来源

来源类型：聊天记录 / 需求设计 / 实验结论 / 案例分析结论 / 人工反馈 / 其他  
来源位置：<相对路径或聊天摘要>  

关键聊天要求：

```text
<必须记录会影响需求目标、边界、验收的聊天要求。>
```

背景：

```text
<为什么需要这个需求。>
```

## 3. 需求范围

做：

1. <要做事项>

不做：

1. <明确不做事项>

## 3A. 需求上游一致性检查

上游需求文档：

| 文档 | 是否存在 | 路径 | 检查结论 |
|---|---|---|---|
| 需求方案文档 | 是 / 否 / 不适用 | <路径> | <一致 / 有冲突 / 待补> |
| 架构文档 | 是 / 否 / 不适用 | <路径> | <一致 / 有冲突 / 待补> |
| 模块说明文档 | 是 / 否 / 不适用 | <路径> | <一致 / 有冲突 / 待补> |
| 核心流程文档 | 是 / 否 / 不适用 | <路径> | <一致 / 有冲突 / 待补> |
| 需求总纲 | 是 / 否 | <路径> | <一致 / 有冲突 / 待补> |

一致性结论：

```text
<需求是否和需求方案、三大文档、需求总纲一致；是否有冲突；是否有漏写。>
```

如果上游文档不存在，说明原因：

```text
<例如：本需求是少量修改，不需要需求方案；本需求是轻量首版交付，不需要三大文档。>
```

## 4. 模块职责

模块名称：<模块名>  
模块定位：<生产模块 / 只读 helper / 审计模块 / sidecar / 其他>  

职责：

1. <职责 1>

不得做：

1. <不得做事项>

## 5. 上下游关系

上游：

| 上游产物 | 来源 | 必需 | 说明 |
|---|---|---|---|
| <产物> | <路径或模块> | 是 / 否 | <说明> |

下游：

| 下游产物或模块 | 消费内容 | 是否主链 | 说明 |
|---|---|---|---|
| <下游> | <内容> | 是 / 否 | <说明> |

## 6. 输入合同

| 字段 / 文件 | 类型 | 必需 | 口径 | 备注 |
|---|---|---|---|---|
| <字段> | <类型> | 是 / 否 | <定义> | <备注> |

## 7. 输出合同

| 字段 / 文件 | 类型 | 必需 | 口径 | 备注 |
|---|---|---|---|---|
| <字段> | <类型> | 是 / 否 | <定义> | <备注> |

## 8. 核心处理流程

1. <步骤 1>
2. <步骤 2>
3. <步骤 3>

如果流程较长，必须说明：

1. 哪些步骤是主链。
2. 哪些步骤是 sidecar / helper。
3. 哪些步骤可以跳过或单独运行。
4. 哪些步骤失败会阻断主链。

## 9. 状态和枚举

| 字段 | 允许值 | 含义 |
|---|---|---|
| <字段> | <枚举> | <含义> |

## 10. 验收方式

验收必须轻重分层，不得为了严谨把外围诊断塞进主流程。

主链验收：

1. 必需输入存在。
2. 必需字段存在。
3. 关键 key 合法。
4. 输出可读。
5. 行数明显合理。
6. 上下游 handoff 不断。

只读 helper 或外部审计：

1. <如有复杂校验，在 helper 中做。>

不作为阻断：

1. <不影响主链结果的诊断项。>

## 11. 重跑和恢复

重跑原则：

1. 何时必须从原始输入重跑。
2. 何时允许从中间快照重跑。
3. 复用产物前检查哪些字段、行数、key、配置和版本。
4. 失败产物如何标记。

## 12. 性能和扩展

如存在明显性能风险，记录性能方案或性能边界。

如果没有明确性能瓶颈，可以写“不需要单独性能优化方案”。

扩展点：

1. <可能频繁变更的字段、规则或接口。>

## 13. 审核记录

| 审核 ID | 审核人 | 结论 | 说明 |
|---|---|---|---|
| <AUDIT-ID> | <审核人> | 通过 / 驳回 / 有条件通过 | <说明> |