Prd

PRD（书标：总体说明 + 用例）

按苏杰《人人都是产品经理》中「一份实际的 PRD 模板」（图 3-7）和「现实中的 UC 模板」（表 3-1）撰写。PRD 是需求人员写给开发看的文档。原则：字不如表，表不如图。一份 PRD 只装逻辑相关的一包功能；一个项目可以有多份 PRD。

PRD 不代替 BRD、技术设计、界面规范、交互规范、文案规范或 Demo。视觉、交互、文案在 UC 中引用，不在正文展开。

专业 UML 只用 PlantUML。出图用本机 java -jar plantuml.jar。没有 Java 或 jar 时先配置环境再出图；仅当用户明确拒绝配置时，才只写源码、不出 SVG。禁止用 Mermaid、D2 或模型位图顶替 UML。

任务

1. 阅读用户描述和已有资料，按「需求打包」把逻辑相关的功能点收进这一份 PRD。
2. 范围不清时先问：本 PRD 覆盖哪些功能、其余需求在哪、有哪些角色和周边系统。信息够就直接写。
3. 需要出图时，按「PlantUML 与 Java 环境」探测；缺 Java/jar 则安装或下载，除非用户已明确拒绝配置环境。
4. 按下方目录生成或更新 PRD。UML 图写 PlantUML 源码；能渲染则导出 SVG，按「布局与成图验收」检查后插入文档。
5. 按用户指定路径保存；未指定时保存为 tasks/prd-[功能名].md（功能名 kebab-case）。
6. 只创建或更新 PRD，不开始实现、不拆开发任务。用户只要评审或建议时，不改文件。

更新已有 PRD 前先读全文，保留有效内容和真实修订记录。没有发生过的修订、评审、日期、作者不要编。

环境安装过程写在 agent 步骤里，不要写进 PRD 正文。

PRD 结构

目录固定为书中图 3-7。没有内容的小节整节删除，不要写「无」凑目录，不要为空表凑行。作者说模板可裁：用不到的栏删掉，缺了再加。写作说明、图种教学、环境安装只留在本 skill 里，不要写进生成的 PRD。

1. 总体说明
   1.1 修订历史
   1.2 项目概述
   1.3 功能范围
   1.4 用户范围
   1.5 词汇表
   1.6 非功能需求
   1.7 其他说明
2. UC 部分
   2.1 整体说明（用例图必有；类图、状态图按需要）
   2.2 UC 正文
       UC_<用例名称>：<用例ID>

Markdown 标题：# PRD：… → ## 1. 总体说明 → ### 1.1 … → ## 2. UC 部分 → ### 2.1 整体说明 → ### 2.2 UC 正文 → #### UC_<名称>：<ID>。

书中模板附录「对单个 UC 的说明」是作者写给自己的注释，不要印进生成的 PRD。有 Demo 或规范时，把链接写在对应 UC 的「界面描述」里。

1. 总体说明

1.1 修订历史

表格：日期、版本号、说明、作者。首次成文记一笔即可。

1.2 项目概述

写背景、意义、目的、目标，以及读懂本文所需的业务领域知识。可指向 Kick Off 材料。

若本 PRD 不是该项目的全部需求，必须说明：这份覆盖什么，其他需求在哪。

1.3 功能范围

给出本 PRD 的业务逻辑图（顶层、简洁）。用 PlantUML。文字补上：

• 系统中角色的职责
• 与周边系统的关系
• 全局商业规则
• 本 PRD 明确不包含的功能（指向其它 PRD 或写「本期不做」）

不要在这里展开某个按钮怎么点。

1.4 用户范围

本 PRD 涉及的角色、外部系统，各用一两句话说明。

1.5 词汇表

专有词汇、术语、缩写。没有则整节删除。

1.6 非功能需求

性能、数据监控等。有依据才写阈值。书中做法：为新功能设监控点；上线后由 PD 做数据分析，验证是否达到预期商业目标。

非功能不写进 UC，只放本节。没有监控方案不要编造指标。

1.7 其他说明

不属于以上各节、又需要交代的内容。没有则整节删除。范围或主路径仍缺、问不到的，标在这里，按已知部分出草稿。不要在这里写 PlantUML/Java 安装过程或「如何读本图」。

2. UC 部分

总体说明之后进入用例。先画本 PRD 中全部用例的关系，再逐个写 UC。2.1 的图不涉及某个用例的内部细节。

这些图从顶层业务逻辑图细化而来。类图是领域描述，不是数据库表。状态图必须包含失败/离开，不能只有成功一条线。

单个 UC 内部的时序图、活动图放在该 UC 的「流程描述」里，不要塞进 2.1。

2.2 每个 UC 的正文（表 3-1）

UC 是写给开发看的最基本文档，从场景（Scenario）细化而来。一个 UC 写一个任务。新人、新业务时，「增加 / 删除 / 修改」宜拆成三个 UC；老人、老业务可以用一个「管理 xx」。

编号：UC_<用例名称>：<用例ID>，例如 UC_点菜：UC_ordermeal。ID 经常可省略，关系不大。已有编号更新时不改。

#### UC_<用例名称>：<用例ID>

**用例概述**

| 栏 | 内容 |
|---|---|
| 业务描述 | 商业目标、用户目的：为什么要做这个 UC |
| 需求描述 | 产品需求：这个 UC 要实现哪些功能点 |
| 行为者 | 该用例的 Actor |
| 前置条件 | 触发这个用例的前提 |
| 后置条件 | 用例完成后的后续状态或动作 |
| 其他说明 | 针对这个 UC 的特殊说明；没有则删掉这一行 |

**界面描述**（无界面则删除本段，不要空表）

- UI 示意图：<页面名称>
- Demo 截图与 Demo 文件地址
- 界面元素——表单：名称、类型\|长度、必填、默认值、规则
- 界面元素——列表：名称、类型\|长度、排序、规则
- 界面元素——按钮：名称、规则

**业务规则**

整条 UC 的通用规则写这里（如限制条件）。某一步的私有规则写在该步流程中，不堆在这里。

**流程描述**

分主干、分支、异常三种。描述由什么事件触发，用户与系统如何交互。**尽量用 PlantUML 时序图或活动图，文字可选。**

- 流程 1（主流程）：<流程名称>
- 触发事件：
- 时序图或活动图（PlantUML）
- 步骤表：步骤 \| 用户 \| 系统 \| 规则
- 分支流程 1-1 …

UC 语言要求：无歧义、完整、一致、可测试。例如「小明和两个部门的同事一起去餐馆」——「两个」修饰部门还是同事，有歧义，不要这样写。

PlantUML 与 Java 环境

UML 与业务逻辑图一律 PlantUML，围栏用 plantuml：

```plantuml
@startuml
...
@enduml
```

不要用 Mermaid、D2 画用例图、类图、状态图、时序图、活动图。

约定路径

tools/plantuml.jar     jar（项目根或本 skill 目录，先查项目）
diagrams/*.puml        从 PRD 抽出的源码副本（可选；PRD 围栏是权威）
diagrams/*.svg         出图
tasks/prd-<name>.md    文档默认位置

出图命令：

java -jar tools/plantuml.jar -tsvg diagrams/<name>.puml

生成的 SVG 插在对应源码下方：![](diagrams/<name>.svg)。源码与图都保留：源码可改，图供阅读。

布局与成图验收

目标是在保留业务复杂度和 UML 表达能力的前提下，让每条关系可追踪。简单图使用自然布局；出现密集交叉、重叠、标签遮挡或长距离绕线时，再进行布局优化。不得仅为排版删减关系、合并用例、拆图替代完整关系图，或省略异常路径。

语义不变量：优化前后核对节点 ID、名称、系统边界与业务分组，以及每条关系的端点、方向、类型、标签、条件、多重性和角色名。排版不得改变这些内容；发现语义问题时单独依据需求判断，不混入布局修改。include、extend 按业务含义使用，不因连线方便相互替换，也不把页面入口或操作先后直接认定为包含或扩展关系。

布局策略：

• 优先调整整体方向、节点分区与顺序，再调整间距、局部连线方向和标签。按关联紧密程度安排节点，不机械地按声明顺序排成长列；共享节点的位置结合全部连线选择，不固定放正中。
• 参与者可分置系统边界两侧，靠近其主要关联用例。布局分区不新增有业务含义的包或边界；不通过重复节点、合并连线或虚构中间节点美化图形。
• 可用方向提示和少量隐藏连线辅助布局。隐藏约束集中放在源码中明确注释的布局区域，不计入业务关系核对；避免过多约束导致绕线或布局僵化。
• 曲线、折线、直角线按渲染效果选择，不全局强制某种线型。不假定方向提示能精确控制路线，也不假定直角线会自动处理好标签。必要时内部比较少量布局候选，不要求用户逐一选版。
• 允许适度扩大画布，为标签和箭头留空间；不能通过缩小字号或把整图过度缩放来掩盖拥挤。保留 PlantUML 为图形来源，修改后重新渲染，不直接修补 SVG 造成源码与成图不一致。

按图种选择重点：

验收与停止条件：

1. 本机渲染后查看完整图及密集区域，并检查其在 PRD 实际展示宽度下的可读性。可后台将 SVG 渲染为临时图片供检查，不使用桌面截图。
2. 检查是否有线穿过无关节点、文字或标签互相遮挡、箭头难以识别，以及多条线重叠到无法分别追踪。语法成功不代表视觉验收通过；无法查看成图时如实说明未完成视觉验收。
3. 取舍顺序：语义完整 → 标签与箭头可读 → 减少交叉和重叠 → 缩短绕线 → 画布紧凑。复杂图不要求零交叉，但每条关系的起终点、类型和标签必须能辨认。
4. 有明确可读性问题时针对性调整并重新渲染；达到上述要求即停止，不为对称或紧凑反复重排。若布局限制仍使关系无法辨认，保留全部内容并说明具体限制，不以删减内容冒充优化完成。

探测

不抢桌面焦点，只用命令行：

1. java -version（建议 11+）
2. tools/plantuml.jar 是否存在；也可搜项目内已有 plantuml.jar
3. 渲染若报 Graphviz/dot 相关错误，再查 dot -V

缺则配置（默认执行）

用户未明确拒绝时，缺什么补什么：

仅当用户明确说过例如：不装 Java、不要本机环境、不要下载 jar、不要改电脑、只用源码不出图——才跳过安装。没说清 ≠ 拒绝。

跳过安装时：PRD 仍写 PlantUML 源码；回复中说明「未本机出图，因用户不配置环境」。不要改用其它图语言。

用户拒绝本机环境、但又要求必须出图时，才可用公共渲染（plantuml.com 或 Kroki）作为最后退路，并说明源码会离开本机。默认不要走公共接口。

不要用 pip install plantuml 当引擎：那些包只是客户端，离线画图仍要 Java 或远程服务。

出图失败

保留源码，记录原因（语法 / 缺 jar / 缺 Graphviz），修正后重试。禁止改写成 Mermaid 或改成模型生成的 PNG 作为唯一图源。

写作规则

• 先打包再成文：逻辑不相关的功能点另开 PRD，在 1.2 / 1.3 互相引用。
• 先范围后用例：没有功能范围、用户范围，不要直接堆 UC。
• 先关系后细节：2.1 只画用例怎么连；校验、字段、逐步操作写在对应 UC。
• 用例图最关键：简单功能可以没有类图、状态图，不能没有用例图。
• 业务逻辑图要短：给老板也能看完；细节下放到 UC。
• 不把设计稿写进需求（书中对写 UC 的注释，只约束写法，不写入生成稿）：
  • 页面大小、颜色、字体、字号 → Demo
  • 表格对齐等界面细则 → 界面规范（有则在「界面描述」放链接）
  • 出错提示方式等 → 交互规范
  • 提示文案原文 → 文案规范
  • 没有 Demo/规范：不在 UC 正文用文字代替视觉稿，也不在文末复读上述四条
• 不为凑模板编造功能、阈值、负责人、日期、审批。
• 不为凑附录编造 Demo 链接或规范文档。
• 生成稿不要出现写作教学，例如：「最为关键」「下述图只表达用例之间的关系」「本示例」「字不如表」、注 1～4、Java/jar 安装说明。这些只在本 skill 里。

输出

• 格式：Markdown（.md）
• 默认路径：tasks/prd-[功能名].md
• 图：PlantUML 源码必有；环境允许则另有 SVG
• 保存后在回复中给出路径、本 PRD 未覆盖的需求（若 1.2 有声明）、本机是否已用 jar 出图

检查清单

保存前检查：

• 目录是「总体说明 + UC 部分」；没有的节已删除；没有注 1～4、「最为关键」、「本示例」等写作注释
• 修订历史真实；未编造日期、作者、评审
• 本 PRD 若不是全部需求，1.2 / 1.3 已写清覆盖什么、其余在哪
• 功能范围含业务逻辑图、角色职责、周边系统、全局规则
• 有用例图；需要时有类图、状态图；2.1 里没有单个 UC 的逐步操作
• 每个 UC 按表 3-1；无界面则无界面空表；通用规则与步骤私有规则已分开
• 流程有主干；该有的分支/异常已写；优先有时序图或活动图
• UML 均为 PlantUML，未用 Mermaid 或 D2 顶替
• 已探测 Java/jar；缺则已配置，或已记录用户明确拒绝配置
• 未拒绝配置时，已尝试 java -jar plantuml.jar -tsvg 并插入 SVG（失败则保留源码并说明原因）
• 布局优化前后节点及关系语义一致；未通过删减内容、虚构分组或替换关系类型改善排版
• 已按「布局与成图验收」检查实际成图；关系可追踪，标签和箭头可读，未以过度缩放掩盖拥挤（无法视觉检查时已说明）
• 视觉/交互/文案未写入 UC 正文；有 Demo/规范则只在界面描述放链接，无则不编附录四注
• 未开始实现代码或拆开发任务

示例（书中「小明下馆子」，仅示范结构）

输入（虚构）： 小明到馆子点菜、等待、吃菜。点菜时可接受服务员推荐。上菜太慢可以离开。结账、外卖不在本 PRD。

# PRD：小明下馆子

## 1. 总体说明

### 1.1 修订历史

| 日期 | 版本 | 说明 | 作者 |
|---|---|---|---|
| （成文日） | 0.1 | 初稿 | （作者） |

### 1.2 项目概述

小明进馆子后要能点菜并吃到菜。本 PRD 覆盖进店后的点菜、等待、吃菜；**不含结账与外卖**，结账见其它需求文档（尚未指定路径）。

目的：把「人、点菜单、菜」和点菜者可做的事说清楚，供开发实现堂食点餐主路径。

### 1.3 功能范围

```plantuml
@startuml
start
:进店;
:点菜;
:等待;
if (菜已上桌且是我的?) then (是)
  :吃菜;
  stop
else (上菜太慢)
  :离开;
  stop
endif
@enduml
```

- 点菜者：点菜、吃菜；点菜时可接受推荐。
- 周边：厨房出菜（本 PRD 不展开后厨系统，只消费「菜已上桌且是我的」）。
- 全局规则：一份点菜单属于一位点菜者；未上菜前处于等待。
- 不含：结账、外卖、排队取号。

### 1.4 用户范围

- 点菜者：进店用餐的人（示例中的小明）。
- 服务员：仅在「推荐」扩展用例中出现。

### 1.5 词汇表

| 词 | 含义 |
|---|---|
| 点菜单 | 点菜者与所点菜之间的一次关联记录 |
| 等待 | 已点菜、尚未确认「菜已上桌且是我的」 |

## 2. UC 部分

### 2.1 整体说明

**类图**

```plantuml
@startuml
class 人 {
  -姓名
  -到达时间
}
class 点菜单 {
  -姓名
  -菜名
  -点菜时间
}
class 菜 {
  -菜名
  -价格
  -分量
  -成分
}
人 "0..*" --> 点菜单
点菜单 --> "0..*" 菜
@enduml
```

**用例图**

```plantuml
@startuml
left to right direction
actor 点菜者
usecase 点菜
usecase 吃菜
usecase "服务员推荐" as 推荐
点菜者 --> 点菜
点菜者 --> 吃菜
推荐 .> 点菜 : <<extend>>
@enduml
```

**状态图**

```plantuml
@startuml
[*] --> 点菜
点菜 --> 等待
等待 --> 等待 : 仍在等
等待 --> 吃菜 : 菜来了且是我的
等待 --> [*] : 上菜太慢等不及
吃菜 --> [*]
@enduml
```

### 2.2 UC 正文

#### UC_点菜：UC_ordermeal

**用例概述**

| 栏 | 内容 |
|---|---|
| 业务描述 | 小明工作一周辛苦了，周末晚上想吃一顿好的犒劳自己 |
| 需求描述 | 去餐厅点几个菜，生成点菜单，进入等待 |
| 行为者 | 点菜者（小明）；扩展路径中有服务员 |
| 前置条件 | 点菜者已在馆子内，尚未完成此次点菜 |
| 后置条件 | 存在该点菜者的点菜单，服务员接受订单后进入等待（厨房侧后续动作不在本 UC 展开） |
**业务规则**

1. 点菜单关联点菜者与所点菜。
2. 未选定任何菜则不生成点菜单。

**流程描述**

- 流程 1（主流程）：完成点菜
- 触发事件：点菜者提出点菜

```plantuml
@startuml
actor 点菜者
participant 服务员
participant 厨师
点菜者 -> 服务员 : 点菜
服务员 -> 厨师 : 下单
厨师 -> 厨师 : 烧菜
厨师 --> 服务员 : 出菜
服务员 --> 点菜者 : 上菜
@enduml
```

| 步骤 | 用户 | 系统 | 规则 |
|---|---|---|---|
| 1 | 提出点菜 | 进入点菜 | — |
| 2 | 选定菜 | 记录菜名 | 可走扩展「服务员推荐」 |
| 3 | — | 生成点菜单（姓名、菜名、点菜时间） | 至少一道菜 |
| 4 | — | 进入等待 | — |

- 扩展：`<<extend>>` UC_服务员推荐
- 异常：未选定任何菜，不生成点菜单，不进入等待

#### UC_服务员推荐

**用例概述**

| 栏 | 内容 |
|---|---|
| 业务描述 | 点菜时可能需要建议，降低选菜成本 |
| 需求描述 | 服务员给出推荐，点菜者可采纳或忽略 |
| 行为者 | 服务员、点菜者 |
| 前置条件 | 正在 UC_点菜 的选定菜步骤 |
| 后置条件 | 点菜者仍处于选定菜 |
| 其他说明 | 推荐不是点菜的必经步骤（extend） |

**业务规则**

推荐失败或点菜者不听，不影响主路径自选。

**流程描述**

- 触发事件：点菜过程中出现推荐

| 步骤 | 用户 | 系统 | 规则 |
|---|---|---|---|
| 1 | 服务员给出推荐 | 展示推荐 | 非必须 |
| 2 | 采纳或忽略 | 回到选定菜 | — |

#### UC_吃菜

**用例概述**

| 栏 | 内容 |
|---|---|
| 业务描述 | 点到的菜要能吃到 |
| 需求描述 | 确认菜已上桌且是自己的之后食用 |
| 行为者 | 点菜者 |
| 前置条件 | 点菜单处于等待，且菜已上桌、是该点菜者的 |
| 后置条件 | 该次点菜–等待路径结束 |
| 其他说明 | 等待中若上菜太慢，不进入本用例，状态直接结束 |

**业务规则**

只能吃点菜单上属于自己的菜。

**流程描述**

- 触发事件：点菜者确认「菜终于来了，是我的」

| 步骤 | 用户 | 系统 | 规则 |
|---|---|---|---|
| 1 | 确认是自己的菜 | — | 否则不能吃 |
| 2 | 吃菜 | 本次路径结束 | — |

- 异常：等待中上菜太慢、点菜者等不及 → 不进入本 UC（见状态图）