265 lines
7.8 KiB
Markdown
265 lines
7.8 KiB
Markdown
# 产品需求文档（PRD）规范
|
||
|
||
> 本规范用于约束 ForcePilot 平台产品需求文档（Product Requirements Document，简称 PRD）的编写、评审与维护，确保需求表达清晰、可追溯、可验收。
|
||
|
||
---
|
||
|
||
## 1. 目的与适用范围
|
||
|
||
### 1.1 目的
|
||
- 统一 PRD 的结构、粒度与写作风格，降低沟通成本
|
||
- 明确需求从提出到交付的文档化要求，支撑研发、测试、设计协同
|
||
- 为后续的需求变更管理、验收与回溯提供基线
|
||
|
||
### 1.2 适用范围
|
||
- 适用于 ForcePilot 平台所有新增功能、功能优化、重构类需求
|
||
- Bug 修复、文案调整等小改动可使用精简版 PRD（见第 7 节）
|
||
- 紧急线上故障修复可先口头/IM 沟通，事后补齐文档
|
||
|
||
---
|
||
|
||
## 2. 文档基本信息
|
||
|
||
每份 PRD 必须包含以下元信息：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| 文档标题 | 简洁明确，体现功能主体与意图 |
|
||
| 文档版本 | 采用 `v主版本.次版本`，如 v1.0、v1.1 |
|
||
| 作者 | 姓名 + 工号/账号 |
|
||
| 创建日期 | YYYY-MM-DD |
|
||
| 最后更新日期 | YYYY-MM-DD |
|
||
| 状态 | 草稿 / 评审中 / 已确认 / 已归档 |
|
||
| 关联需求 | 关联的需求 ID、Issue 链接或 PR 链接 |
|
||
| 评审人 | 产品、研发、测试、设计等关键评审人 |
|
||
|
||
---
|
||
|
||
## 3. PRD 标准结构
|
||
|
||
一份完整的 PRD 应按以下顺序组织章节，无内容的章节标注「不涉及」并保留标题：
|
||
|
||
1. 背景与目标
|
||
2. 名词解释
|
||
3. 用户与场景
|
||
4. 功能需求
|
||
5. 非功能需求
|
||
6. 交互与设计要求
|
||
7. 数据与接口需求
|
||
8. 验收标准
|
||
9. 排期与里程碑
|
||
10. 风险与依赖
|
||
11. 变更记录
|
||
|
||
---
|
||
|
||
## 4. 各章节编写规范
|
||
|
||
### 4.1 背景与目标
|
||
- **背景**：说明需求来源（用户反馈、业务目标、技术债等），避免空泛描述
|
||
- **目标**：使用可度量的指标或明确的终态描述，避免「提升体验」这类无法验证的表述
|
||
- **非目标**：明确本次不做的事项，防止范围蔓延
|
||
|
||
### 4.2 名词解释
|
||
- 列出文档中出现的领域术语、缩写、业务概念
|
||
- 与既有文档/代码中的术语保持一致，避免同义多词
|
||
|
||
### 4.3 用户与场景
|
||
- 明确目标用户角色（如：知识库管理员、普通使用者、API 调用方）
|
||
- 描述典型使用场景，采用「作为…我希望…以便…」的用户故事格式
|
||
- 复杂流程需配流程图或时序图
|
||
|
||
### 4.4 功能需求
|
||
- 采用**需求项编号**（如 FR-01、FR-02），便于评审与追溯
|
||
- 每个需求项包含：
|
||
- 需求描述
|
||
- 输入 / 输出
|
||
- 业务规则
|
||
- 异常与边界情况
|
||
- 优先级（P0 / P1 / P2）
|
||
- 禁止将多个独立功能合并为一个需求项
|
||
- 涉及权限的需求需明确角色与权限矩阵
|
||
|
||
### 4.5 非功能需求
|
||
按需覆盖以下维度，无要求时显式标注「不涉及」：
|
||
- 性能（响应时间、吞吐量、并发数）
|
||
- 可用性（SLA、容灾）
|
||
- 安全性（鉴权、数据加密、审计）
|
||
- 兼容性（浏览器、API 版本、依赖服务版本）
|
||
- 可观测性（日志、指标、告警）
|
||
- 国际化与无障碍
|
||
|
||
### 4.6 交互与设计要求
|
||
- 引用原型图/设计稿链接，避免在 PRD 中重复描述视觉细节
|
||
- 明确关键交互逻辑（如：loading 态、空态、错误态、确认弹窗）
|
||
- 与设计规范文档保持一致
|
||
|
||
### 4.7 数据与接口需求
|
||
- 涉及新增/变更的数据模型需列出字段说明
|
||
- 接口需求需说明：路径、方法、入参、出参、错误码
|
||
- 与既有 API 规范保持一致，避免破坏性变更；如必须破坏需显式标注并给出迁移方案
|
||
|
||
### 4.8 验收标准
|
||
- 每个 P0/P1 功能需求必须对应至少一条可执行的验收标准
|
||
- 验收标准应可被测试用例直接覆盖，避免主观表述
|
||
- 推荐使用 Given-When-Then 格式
|
||
|
||
### 4.9 排期与里程碑
|
||
- 列出关键节点：设计完成、开发完成、联调完成、测试完成、上线
|
||
- 标注负责人与预期日期，日期变更需同步更新变更记录
|
||
|
||
### 4.10 风险与依赖
|
||
- 识别技术依赖、外部服务依赖、资源依赖
|
||
- 识别潜在风险并给出应对策略
|
||
|
||
### 4.11 变更记录
|
||
- 每次文档修订需追加一行：版本、日期、修改人、修改内容摘要
|
||
- 已确认状态的文档变更需重新触发评审
|
||
|
||
---
|
||
|
||
## 5. 写作与格式规范
|
||
|
||
### 5.1 语言风格
|
||
- 使用简洁的书面中文，避免口语化与歧义
|
||
- 使用「必须 / 应当 / 可以」区分强制、推荐、可选级别
|
||
- 术语统一，避免中英文混用造成的歧义
|
||
|
||
### 5.2 Markdown 格式
|
||
- 标题层级不超过四级（`####`）
|
||
- 表格用于结构化数据，列表用于步骤或枚举
|
||
- 代码、字段名、接口路径使用反引号包裹
|
||
- 流程图、时序图使用 Mermaid 语法，确保可渲染
|
||
|
||
### 5.3 图表规范
|
||
- 所有图表需有图题与编号（如：图 1 用户登录流程）
|
||
- 截图需标注来源与版本，避免使用过期截图
|
||
- 图表中的文字应可被复制检索，关键流程图优先使用 Mermaid
|
||
|
||
### 5.4 链接规范
|
||
- 引用内部文档使用相对路径
|
||
- 引用代码位置使用可点击的文件链接
|
||
- 外部链接需注明访问日期或版本
|
||
|
||
---
|
||
|
||
## 6. 优先级定义
|
||
|
||
| 级别 | 含义 | 验收要求 |
|
||
| --- | --- | --- |
|
||
| P0 | 必须完成，阻塞上线 | 必须有验收标准与测试用例 |
|
||
| P1 | 应当完成，影响主流程 | 必须有验收标准 |
|
||
| P2 | 可以完成，体验优化 | 可简化验收 |
|
||
|
||
---
|
||
|
||
## 7. 精简版 PRD
|
||
|
||
适用于改动范围小、影响面有限的需求，至少包含：
|
||
|
||
1. 背景与目标（1-2 句）
|
||
2. 功能需求（编号 + 描述 + 优先级）
|
||
3. 验收标准
|
||
4. 排期
|
||
|
||
---
|
||
|
||
## 8. 评审与维护流程
|
||
|
||
### 8.1 评审流程
|
||
1. 作者完成草稿，状态置为「评审中」
|
||
2. 产品、研发、测试、设计分别评审，提出问题在文档中批注
|
||
3. 作者汇总意见并修订，更新版本号
|
||
4. 全部意见 resolved 后，状态置为「已确认」，进入开发
|
||
|
||
### 8.2 变更管理
|
||
- 已确认的 PRD 如需变更，必须更新「变更记录」并通知相关方
|
||
- 涉及范围、排期、验收标准的变更需重新评审
|
||
- 开发过程中发现的需求偏差，应在变更记录中记录并同步
|
||
|
||
### 8.3 归档
|
||
- 功能上线且验收通过后，PRD 状态置为「已归档」
|
||
- 归档文档不再修改，后续迭代新建版本或新文档
|
||
|
||
---
|
||
|
||
## 9. 存放与命名规范
|
||
|
||
### 9.1 存放位置
|
||
- PRD 文档统一存放于 `docs/vibe/<版本号>/需求文档/` 目录下
|
||
- 关联的设计稿、原型图链接至 `docs/vibe/<版本号>/原型图/` 目录
|
||
|
||
### 9.2 命名规范
|
||
- 文件名格式：`<模块>-<功能>-PRD-v<版本>.md`
|
||
- 示例：`knowledgebase-import-PRD-v1.0.md`
|
||
- 全部使用小写英文与连字符，避免空格与中文文件名
|
||
|
||
---
|
||
|
||
## 10. 模板速查
|
||
|
||
```markdown
|
||
# <功能名称> 产品需求文档
|
||
|
||
| 字段 | 内容 |
|
||
| --- | --- |
|
||
| 文档版本 | v1.0 |
|
||
| 作者 | |
|
||
| 创建日期 | |
|
||
| 最后更新日期 | |
|
||
| 状态 | 草稿 |
|
||
| 关联需求 | |
|
||
| 评审人 | |
|
||
|
||
## 1. 背景与目标
|
||
### 1.1 背景
|
||
### 1.2 目标
|
||
### 1.3 非目标
|
||
|
||
## 2. 名词解释
|
||
|
||
## 3. 用户与场景
|
||
|
||
## 4. 功能需求
|
||
### FR-01 <需求标题>
|
||
- 描述：
|
||
- 输入：
|
||
- 输出：
|
||
- 业务规则：
|
||
- 异常与边界：
|
||
- 优先级：P0
|
||
|
||
## 5. 非功能需求
|
||
|
||
## 6. 交互与设计要求
|
||
|
||
## 7. 数据与接口需求
|
||
|
||
## 8. 验收标准
|
||
- AC-01：Given… When… Then…
|
||
|
||
## 9. 排期与里程碑
|
||
|
||
## 10. 风险与依赖
|
||
|
||
## 11. 变更记录
|
||
| 版本 | 日期 | 修改人 | 摘要 |
|
||
| --- | --- | --- | --- |
|
||
| v1.0 | | | 初稿 |
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 检查清单
|
||
|
||
PRD 提交评审前，作者需逐项确认：
|
||
|
||
- [ ] 文档元信息完整
|
||
- [ ] 目标可度量，非目标已明确
|
||
- [ ] 功能需求已编号且粒度合理
|
||
- [ ] 每个 P0/P1 需求有对应验收标准
|
||
- [ ] 非功能需求已逐项确认或标注「不涉及」
|
||
- [ ] 接口与数据变更已标注破坏性影响
|
||
- [ ] 图表可渲染、链接可访问
|
||
- [ ] 命名与存放符合本规范
|