# PRD 草案格式模板

创建新需求草案、重建正文结构或需要参考需求项写法时使用本文件。项目已有模板时优先使用项目模板；本文件只作为通用兜底模板和写法示例。硬性规则以 `prd-draft-document-spec.md` 为准。

## 草案包目录模板

适用场景：目标落点是 `.ai-transition/prd-draft`，且需求包含复杂业务闭环、外部协议、客户材料、非业务方案、性能建议或多轮决策记录。

```text
.ai-transition/prd-draft/<capability-domain>/<slug>/
  <topic-slug>-prd.md
  decisions.md
  acceptance.md
  references/
```

- `<topic-slug>-prd.md`：唯一主需求草案，文件名应包含可检索的业务主题；目录名过宽时使用更具体的业务短横线名，例如 `erp-integration-prd.md`。
- `decisions.md`：确认结论、冲突、取舍、待确认事项和覆盖记录。
- `acceptance.md`：验收补充和边界补充；简单需求可写“以主草案为准”。
- `references/`：外部协议、客户材料、历史说明、性能建议、接口草稿、来源摘录等强依赖参考材料。
- 默认不创建 `flows/`、`rules/` 等额外目录；确需拆分时，在同一草案包内新增辅助文档，并从主草案使用相对路径引用。

## 草案包配套文件模板

### decisions.md

````md
# decisions

## 已确认
- 无

## 待确认事项
- 无

## 冲突与取舍
- 状态：none
- 冲突：无
- 影响：无
- 当前结论：无

## 覆盖记录
- 允许覆盖：否
- 确认人：无
- 确认时间：无
- 覆盖范围：无
- 确认依据：无
````

### acceptance.md

````md
# acceptance

## 验收补充
- 无；以主草案的验收或业务闭环要求为准。

## 边界补充
- 无
````

### references/README.md

````md
# references

本目录存放当前需求草案强依赖的外部协议、客户材料、历史说明、性能建议、接口草稿或来源摘录。

- 材料必须脱敏、裁剪或摘要化。
- 不把用户机器绝对路径作为唯一依据。
- 非业务方案只能作为参考来源，不代表 `../<topic-slug>-prd.md` 已确认对应实现。
````

### references/performance-notes.md

````md
# performance-notes

## 来源摘要
- 来源：<客户材料、历史说明、评审结论或会话讨论>
- 背景：<为什么提出性能、容量、稳定性或恢复要求>

## 可转译业务约束
- <响应时限、同步完成时限、高峰期可用性、一致性、重复提交处理或异常恢复结果>

## 非确定实现参考
- <方案名称或来源摘录>：<只保留逻辑思路、适用前提和主要取舍，不扩写成技术设计>
- 本节不代表主草案已确认具体实现；主草案只引用已转译的业务目标、约束或验收口径。
````

## 通用正文骨架

````md
# <主题> 需求草案

- **阶段** 需求草案阶段
- **状态** 制定中
- **锚点** <需求文档路径或需求主题>
- **关联文档** <如需要引用其他文档，使用相对当前文档的路径，例如 `./protocol.md` 或 `../main-flow.md`；不要写用户机器绝对路径>
- **关联材料** <草案包中优先写 `./references/<file>.md`；没有则写“无”>

## 目标与范围
- 目标：<本需求要解决的业务问题和成功状态>
- 范围内：<明确包含的业务对象、流程、角色或场景>
- 范围外：<明确不处理的内容，避免需求外溢；不记录同一轮未确认推演中被否定的临时方案>

## 业务闭环
- 参与方：<用户、管理员、系统、外部方等>
- 触发条件：<什么情况下开始>
- 输入或前置条件：<需要什么信息或状态>
- 处理规则：<业务判断、校验、流转和限制>
- 输出结果：<成功、失败、取消、异常后的结果>
- 状态和生命周期：<状态变化、结束条件、历史保留>
- 权限和可见范围：<谁能看、谁能改、谁能触发>
- 边界和异常：<空数据、重复、失败、撤销、兼容等>

## 需求项
- <需求项名称>：<已确认需求内容>
- 数据项 <名称>：<业务含义、来源、生成方式、使用规则>
- 业务约束 <名称>：<由外部非业务方案转译来的业务目标、响应时限、一致性或可用性要求；不写 Redis、MQ、缓存等实现方案>
- 待确认：<不阻塞主链路但后续需要确认的问题>
````

## 整篇文档模板

### 流程文档模板

适用场景：需求主题以触发、步骤、链路、状态流转、分支异常为核心。只填用户已确认的信息，不带入具体业务、具体页面、具体模块或未经确认的示例。

````md
# <主题>流程需求草案

适用对象：<阅读或执行对象>
关联文档：`./<关联文档>.md`

## 流程目标
- <流程需要达成的业务结果>

## 参与方
- <参与方>：<职责>

## 前置条件
- <流程开始前必须满足的条件>

## 主流程
1. <步骤 1>
2. <步骤 2>
3. <步骤 3>

## 分支与异常
- <条件或异常>：<处理结果>

## 状态与生命周期
- <状态或阶段>：<进入条件、退出条件和结果>

## 边界要求
- <重复、失败、取消、历史、权限或其他边界>

## 禁止事项
- 禁止 <会破坏流程闭环的行为>

## 待确认
- 待确认：<不阻塞主流程但后续需要明确的事项>
````

### 要求文档模板

适用场景：需求主题以适用对象、执行约束、交付约束、验收约束、禁止事项为核心。少写背景解释，多写可执行、可判断、可验收的规则。

````md
# <主题>要求

适用对象：<执行或交付对象>
关联文档：`./<关联文档>.md`

## <要求分组 1>
- 必须 <可执行、可判断、可验收的要求>
- 不允许 <不可接受的行为或结果>

## <要求分组 2>
- <要求内容>

## 边界与异常
- <边界或异常场景>：<要求结果>

## 禁止事项
- 禁止 <明确不允许的行为>

## 待确认
- 待确认：<不影响当前主链路但后续需要确认的事项>
````

## 模板选择

| 用户表达 | 需求写法 | 使用模板 |
|:---|:---|:---|
| 需要记录、维护、展示某类信息 | 业务数据对象和数据项 | 数据对象 |
| 给已有信息增加来源、规则或使用方式 | 修改既有业务对象 | 修改数据对象 |
| 多值、多对多、明细、记录、绑定关系 | 独立业务记录或关联关系 | 关联记录 |
| 状态、类型、来源、分类、等级等值域 | 业务值域和状态含义 | 值域 |
| 唯一、审核、校验、默认值、权限范围 | 业务规则 | 规则 |
| 触发、步骤、链路、流转、时序、分支异常 | 从触发到结果的完整链路 | 流程文档 |
| 要求、交付要求、对接要求、执行要求、验收要求 | 面向执行对象的可验收约束 | 要求文档 |
| 展示、查询、筛选、排序、统计、聚合口径 | 展示或统计规则 | 展示统计 |
| 跨角色、跨系统或跨模块协作 | 协作或集成需求 | 集成 |

## 方案分层写法

| 用户表达 | 写入位置 | 写法 |
|:---|:---|:---|
| 定义何时开始、何时结束、何时有效或失效 | 主草案 | 写成业务规则、状态生命周期或边界要求 |
| 定义异常归类、失败结果、恢复条件、补偿结果 | 主草案 | 写成分支异常、失败结果或验收口径 |
| 提出响应时限、峰值压力、可用性、一致性目标 | 主草案 | 写成业务约束和验收要求 |
| 提出 Redis、MQ、缓存、索引、异步任务、部署等做法 | `references/` 或 `decisions.md` | 写成参考来源或决策背景，主草案只保留业务目标 |
| 同一方案同时包含业务判定和实现建议 | 拆分处理 | 业务判定进主草案，实现建议进参考材料，取舍进决策记录 |

## 写法规则

- 生成的需求草案应优先匹配项目已有结构，不强行使用本模板标题。
- 不把正文拆成没有内容的固定分区。
- 选择流程文档或要求文档时，优先保持短、清楚、规则明确；不强行补齐通用正文骨架的所有章节。
- 模板占位只代表信息类型，不代表真实业务；不得把占位或示例扩展成未经确认的业务内容。
- 用户说“表、结构体、数据模型、model、字段、列、属性”时，先归一为业务需求；涉及保存或维护的数据，按业务数据对象和数据项表达。
- 不写 SQL、ORM、字段类型、索引、唯一约束、API path 或 request/response schema。
- 关联协议、关联主流程、关联文档等引用必须使用可迁移写法；同目录用 `./xxx.md`，跨目录用相对当前文档的 `../xxx/yyy.md`，Markdown 路径使用 `/`。
- 草案包内强依赖材料优先放入 `references/`，并在主草案中用 `./references/<file>.md` 引用。
- 连接轮次、状态生命周期、重复提交判定、异常恢复条件等业务判定必须写进主草案，但不得绑定具体服务状态、缓存键、队列、任务或代码结构。
- Redis、MQ、缓存、索引、分库分表、异步任务等非业务方案只能作为参考来源或决策背景，正文需求必须转译成可验收的业务约束。
- 未确认内容写在最相关的需求语境下，标记为 `需补` 或 `待确认`。

## 需求项模板库

### 数据对象

适用场景：用户提出创建、记录、维护或使用某类业务信息的需求。

````md
## <业务对象>信息
- 需要维护 <业务对象> 信息，用于 <业务目的>。
- 数据项 <名称>：来源于 <来源>，用于 <使用场景>。
- 数据项 <业务标识>：由 <生成方> 生成，作为 <业务对象> 的业务唯一标识，不允许重复。
- <名称> 的获取方式、更新时机和来源缺失时的处理方式需补。
- <业务标识> 的生成规则、重复冲突处理方式和生成失败提示需补。
````

### 修改数据对象

适用场景：用户提出调整既有业务对象、业务属性、数据来源或数据项生命周期的需求。

````md
## <业务对象>信息调整
- 需要调整 <业务对象> 信息，变更原因是 <原因>。
- 复用既有 <业务对象> 信息承载。
- 新增数据项 <名称>：来源于 <来源>，用于 <使用场景>。
- 调整数据项 <名称>：来源由原规则改为 <新规则>。
- 停用数据项 <名称>：不再由业务流程使用，历史数据处理方式需补。
- 本次调整对既有数据的兼容、补齐和异常处理方式需补。
````

### 关联记录

适用场景：用户描述多值、多对多、明细记录、操作记录、绑定关系等独立存在的数据。

````md
## <对象A>与<对象B>关联关系
- 需要维护 <对象A> 与 <对象B> 的关联关系，用于 <业务目的>。
- 数据项 <对象A>：关联到 <对象A> 信息，来源于 <来源>。
- 数据项 <对象B>：关联到 <对象B> 信息，来源于 <来源>。
- 同一个 <对象A> 是否允许关联多个 <对象B> 需补。
- 同一个 <对象B> 是否允许关联多个 <对象A> 需补。
- 关联关系的创建、解除、重复提交和历史保留规则需补。
````

### 值域

适用场景：用户提出用于分类、阶段、来源、等级或模式判断的值域需求。

````md
## <业务值域>
- <业务值域> 用于表达 <业务对象> 在 <场景> 中的分类或阶段。
- 已确认值包括：<值 1>、<值 2>。
- 每个值的业务含义、可见范围和是否参与流程分支需补。
- 如果该值域只用于筛选、展示或统计，需明确写明“不参与业务分支和状态流转”。
````

### 规则

适用场景：用户提出约束、校验、默认规则、权限范围或状态流转规则，不一定新增数据承载对象。

````md
## <业务规则>
- <业务对象> 需要满足 <规则内容>。
- 规则触发条件：<触发条件>。
- 规则通过结果：<成功结果>。
- 规则不通过结果：<失败提示、拦截、回退或人工处理>。
- 历史数据、重复提交、异常中断和人工修正方式需补。
````

### 流程

适用场景：用户提出有触发、处理、结果、分支或异常的链路需求。

````md
## <业务流程>
- 触发方：<用户、系统、外部方或后台任务>。
- 触发条件：<何时触发>。
- 输入内容：<所需信息、文件、状态或外部结果>。
- 处理规则：<校验、转换、流转、人工介入或系统处理规则>。
- 成功结果：<成功后的业务状态、可见结果和通知>。
- 失败结果：<失败后的状态、提示、重试、保留或回退规则>。
- 重复提交、部分成功、异常中断和历史兼容策略需补。
````

### 展示统计

适用场景：用户提出展示、查询、筛选、排序、统计或聚合口径需求。

````md
## <展示或统计规则>
- <对象> 需要展示的数据项包括：<数据项>。
- 支持筛选的数据项包括：<数据项>。
- 支持排序的数据项包括：<数据项>。
- 统计口径：<统计范围、时间口径、去重方式或聚合规则>。
- 默认展示范围、默认排序、空结果和无权限时的处理方式需补。
- 本需求只表达展示和查询口径，不定义 API path、request/response schema 或 SQL 实现。
````

### 集成

适用场景：用户提出跨角色、跨系统、跨模块或跨组织协作需求。

````md
## <集成需求>
- 对接方：<外部系统、平台、模块或组织角色>。
- 业务目的：<为什么需要对接>。
- 触发条件：<何时交换信息或触发协作>。
- 交换内容：<业务数据项和业务含义，不写请求响应 schema>。
- 成功结果：<双方状态或业务结果>。
- 失败结果：<失败提示、重试、人工处理、补偿或保留策略>。
- 权限、审计、幂等、重复通知和异常恢复方式需补。
````