# 产品需求文档（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 需求有对应验收标准
- [ ] 非功能需求已逐项确认或标注「不涉及」
- [ ] 接口与数据变更已标注破坏性影响
- [ ] 图表可渲染、链接可访问
- [ ] 命名与存放符合本规范