ks-prd-draft/references/prd-draft-format-template.md

PRD 草案格式模板

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

草案包目录模板

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

.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

# decisions

## 已确认
- 无

## 待确认事项
- 无

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

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

acceptance.md

# acceptance

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

## 边界补充
- 无

references/README.md

# references

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

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

references/performance-notes.md

# performance-notes

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

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

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

通用正文骨架

# <主题> 需求草案

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

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

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

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

整篇文档模板

流程文档模板

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

# <主题>流程需求草案

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

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

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

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

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

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

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

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

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

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

要求文档模板

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

# <主题>要求

适用对象：<执行或交付对象>
关联文档：`./<关联文档>.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、缓存、索引、分库分表、异步任务等非业务方案只能作为参考来源或决策背景，正文需求必须转译成可验收的业务约束。
• 未确认内容写在最相关的需求语境下，标记为 需补 或 待确认。

需求项模板库

数据对象

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

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

修改数据对象

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

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

关联记录

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

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

值域

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

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

规则

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

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

流程

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

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

展示统计

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

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

集成

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

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