需求文档写到什么程度才算合格一份能直接开工的PRD模板「文档我发你了你看下没什么问题就开工吧。」我打开那份文档一共十二行是一份功能名称列表。一、我收到过最离谱的一份需求文档那是去年接的一个售后工单系统。产品在飞书上给我发来一段话标题叫「工单系统需求」正文是这样的工单创建工单列表工单分配工单处理工单统计十二行五个功能点没有一个字提到字段、状态、权限。我问他工单有哪些状态他说「就正常的状态啊」。我问正常是什么他说「你看着设计就行你是专业的」。我当时还真就看着设计了。我按自己的理解做了五个状态、三个角色两星期做完上线。然后验收会上运营问了六个问题我一个都答不上来客户三天不回复工单能自动关吗处理人离职了他的工单怎么办两个人同时点「抢单」算谁的工单关了之后客户又来找是重开还是新建超时没处理的工单谁会收到通知导出来的统计报表按创建时间算还是按关闭时间算那次验收会开了两个小时最后结论是「先按现在的用有问题再说」。我心里清楚这句话的意思是后面有得改。果然后面两个月我改了三轮第一轮加自动关闭第二轮加离职转派第三轮加并发抢单的锁。三轮加起来又是十几天。如果这六件事在开工前被写进文档那十几天根本不会存在。事后我反复想这件事发现问题不在产品不靠谱而在我们俩对需求文档这四个字的理解完全不一样。他觉得需求文档是我要什么东西的清单我觉得需求文档是怎么做的依据。中间差的那部分就是我后来自己瞎猜、又猜错的那部分。所以这篇文章我想讲清楚一件事一份需求文档写到什么程度才算能开工。二、先定义能开工三条判据五条硬标准我现在判断一份需求文档合不合格就看三件事开发能不能不问任何问题直接写第一行代码。如果写的过程中还要去确认这个字段必填吗不合格。测试能不能照着文档写出用例。如果测试需要来问你这个场景预期结果是什么不合格。验收的时候有没有可对照的东西。如果验收会上出现我以为你知道不合格。落到实处我总结成五条硬标准标准具体要求缺了会怎样字段有定义每个字段的类型、长度、是否必填、枚举值前后端理解不一致联调吵架状态有流转状态清单 允许的路径 不可逆的终态状态判断散落在代码里加一个状态改一周异常有分支每个操作失败、超时、并发时的处理规则线上出问题时临时拍脑袋边界有数值分页上限、导出上限、超时时间、最大长度慢 SQL 拖垮库或者 OOM权限有矩阵角色 × 操作 的允许/禁止表越权操作出事无法追责这五条里只要缺一条这份文档在我这儿就是草稿不是文档。三、一份能直接开工的 PRD 模板下面这份模板是我现在用的拿售后工单系统做例子。你可以直接抄走改我逐段说为什么每一段都不能省。文档名称售后工单系统需求文档 版本v1.2 状态待评审 ## 0. 修订记录 | 版本 | 日期 | 修改人 | 修改内容 | 影响范围 | |---|---|---|---|---| | v1.0 | 2026-03-01 | 产品 | 初稿 | 全部 | | v1.2 | 2026-03-08 | 我 | 补充异常流程与数据字典 | 第4、5节 | ## 1. 背景与目标 客服团队目前用群聊 Excel 跟进售后问题工单易丢失、无法统计响应时长。 本期目标工单全流程线上化可追踪、可统计 SLA 达成率。 不解决的问题明确不做不对接电话客服系统、不做客户自助门户、不做智能派单算法。 ## 2. 名词表 | 名词 | 定义 | |---|---| | 工单 | 一次客户售后请求的完整记录 | | SLA | 从工单创建到首次响应/解决的时间承诺 | | 重开 | 已关闭工单因客户再次反馈而回到处理中 | ## 3. 角色与权限矩阵 | 操作 | 客服 | 客服主管 | 客户 | |---|---|---|---| | 创建工单 | ✓ | ✓ | ✓ | | 抢单/认领 | ✓ | ✓ | ✗ | | 转派他人 | 仅本人名下 | ✓ | ✗ | | 强制关闭 | ✗ | ✓ | ✗ | | 重开 | ✗ | ✓ | ✓限本人工单7天内 | ## 4. 状态与流转 状态清单待分配 / 处理中 / 待客户回复 / 已解决 / 已关闭 | 当前状态 | 可流转到 | 触发条件 | 操作者 | |---|---|---|---| | 待分配 | 处理中 | 抢单或指派 | 客服、主管 | | 处理中 | 待客户回复 | 回复客户并挂起 | 处理人 | | 待客户回复 | 处理中 / 已关闭 | 客户回复 / 超 72 小时未回复自动关闭 | 客户、系统 | | 处理中 | 已解决 | 提交解决方案 | 处理人 | | 已解决 | 已关闭 / 处理中 | 客户确认 / 客户不认可 | 客户 | | 已关闭 | 处理中 | 7 天内客户重开 | 客户 | 不可逆终态已关闭超过 7 天后不可再重开只能新建工单。 ## 5. 功能需求每个功能含六要素 ### 5.1 工单创建 - 描述客户提交售后请求生成工单 - 前置条件客户已登录 - 正常流程填写表单 → 校验 → 生成工单号 → 进入待分配 → 通知客服组 - 异常流程 - E1 表单校验失败逐字段返回错误保留已填内容 - E2 同一客户 5 分钟内提交相同标题拦截并提示已有工单号幂等键客户ID 标题MD5 - E3 附件上传失败工单仍创建成功附件标记为上传失败允许重试 - 边界与约束标题 2-100 字描述最多 2000 字附件最多 5 个单个 ≤ 10MB - 验收标准按 E1/E2/E3 各一条用例正常流程一条用例 ### 5.2 工单抢单 - 描述客服从未分配工单中认领一条 - 正常流程点击认领 → 校验工单仍为待分配 → 写入处理人 → 状态置为处理中 - 异常流程 - E1 并发抢单以数据库乐观锁 version 为准后到者返回「已被认领」 - E2 工单已被抢提示并刷新列表 - 边界与约束单客服同时处理中工单上限 20 条超出禁止认领 - 验收标准并发 10 个请求抢同一工单有且仅有 1 个成功 其余功能同结构略 ## 6. 数据字典 | 字段 | 类型 | 必填 | 说明 | 约束 | |---|---|---|---|---| | ticket_no | VARCHAR(32) | 是 | 工单号 | 唯一规则 GD年月日6位序列 | | title | VARCHAR(100) | 是 | 标题 | 2-100 字 | | priority | TINYINT | 是 | 优先级 | 0-P0 / 1-P1 / 2-P2 / 3-P3默认 2 | | status | VARCHAR(20) | 是 | 状态 | 见第 4 节枚举 | | assignee_id | BIGINT | 否 | 处理人 | 待分配时为空 | | sla_deadline | DATETIME | 是 | 首次响应截止时间 | 创建时间 优先级对应时长 | | closed_time | DATETIME | 否 | 关闭时间 | 关闭时写入 | ## 7. 非功能性需求 - 性能工单列表分页查询响应时间不高于 500ms单表数据量 50 万以内 - 并发抢单接口需保证同一工单仅一人成功 - 审计状态变更、转派、强制关闭全量写操作日志 - 数据保留工单数据保留 3 年日志保留 1 年 ## 8. 验收用例清单 | 用例编号 | 场景 | 预期结果 | |---|---|---| | TC-001 | 客户提交标题为空 | 提示标题不能为空不生成工单 | | TC-002 | 两个客服同时抢单 | 1 成功 1 失败失败方提示已被认领 | | TC-003 | 客户 72 小时未回复 | 工单自动关闭状态为已关闭 | ## 9. 待确认项 | 问题 | 负责人 | 状态 | |---|---|---| | P0 工单的 SLA 时长是多少 | 运营 | 待确认 | | 处理人离职后工单是否自动释放 | HR 系统对接人 | 已确认自动转派主管 |这份模板里有几段是我后来加上的也是最容易被忽略的第 0 节修订记录。看起来最没用实际救过我一次。需求改到第三版的时候前端拿着 v1.0 的截图来问我为什么和实现对不上我翻修订记录两分钟就说清了。第 1 节里的不做清单。这是最容易被砍掉、也最该写的一段。需求文档只写要做什么等于默认没写的都要做。明确写清楚本期不做什么能挡掉一半的临时加需求。第 5 节的六要素。描述、前置条件、正常流程、异常流程、边界与约束、验收标准——六个缺一不可。我以前写需求只写前三个结果异常处理和边界全靠开发自己猜。第 6 节数据字典。这是 Java 后端最该盯紧的一节也是我最容易跟产品吵起来的一节。因为它要求对方给出确定的类型和取值而产品往往觉得这个你们自己定就行。我的做法是自己先写一版再拿去让他确认比反过来问效率高得多。第 9 节待确认项。很多人觉得文档里留待确认项是丢人的事恰恰相反。把我不知道明明白白写出来比让它藏在正文里、等开发到一半才暴露出来强一百倍。我的经验是一份合格的需求文档待确认项通常在三到八条之间一条都没有反而说明写得太粗。这套模板用下来一份中等规模模块的需求文档大概六到十页。听起来不少但这里面有将近一半是表格真正要写的句子没几句填表的时间远少于后面改代码的时间。四、五种最常见的不合格需求文档我这些年见过的需求文档不合格的方式出奇地一致基本逃不出下面五种。4.1 只有正常流程没有异常流程这是最普遍的一种。文档里写着用户提交工单系统生成工单写得很顺。但提交失败呢重复提交呢附件传一半断了呢我的处理办法是给每个操作强制配异常编号。E1、E2、E3 一路编下去编不出来就说明这个地方没想清楚。上面模板里 5.1 那节就是这么写的。这个习惯还有个副作用是好的异常流程写完测试用例也就写完了几乎是 1:1 对应。还有一个容易被忽略的点异常流程要写清楚系统应该做什么而不只是提示失败。「上传失败请重试」是给用户看的提示不是给开发看的规则。真正要写的是上传失败时工单仍然创建成功附件标记为失败状态并允许重试——也就是失败之后数据处于什么状态、还能不能补救。4.2 只有功能名没有数据字典“工单要有优先级”——这是功能名。“优先级是 TINYINT取值 0/1/2/3 分别对应 P0/P1/P2/P3默认 2”——这是数据字典。数据字典缺失的后果是前后端各写各的。前端以为优先级返回字符串后端存的是数字前端以为时间是时间戳后端返回的是格式化字符串。等联调才发现改起来要动两层。数据字典我一般直接写成建表语句让文档和代码一一对应CREATETABLEticket(idBIGINTNOTNULLAUTO_INCREMENTCOMMENT主键,ticket_noVARCHAR(32)NOTNULLCOMMENT工单号 GDyyyymmdd6位序列,titleVARCHAR(100)NOTNULLCOMMENT标题 2-100字,descriptionVARCHAR(2000)DEFAULTNULLCOMMENT问题描述,customer_idBIGINTNOTNULLCOMMENT客户ID,priorityTINYINTNOTNULLDEFAULT2COMMENT优先级 0-P0 1-P1 2-P2 3-P3,statusVARCHAR(20)NOTNULLCOMMENT状态 见状态机定义,assignee_idBIGINTDEFAULTNULLCOMMENT处理人待分配时为空,sla_deadlineDATETIMENOTNULLCOMMENT首次响应截止时间,closed_timeDATETIMEDEFAULTNULLCOMMENT关闭时间,versionINTNOTNULLDEFAULT0COMMENT乐观锁版本号,create_timeDATETIMENOTNULLDEFAULTCURRENT_TIMESTAMP,update_timeDATETIMENOTNULLDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP,PRIMARYKEY(id),UNIQUEKEYuk_ticket_no(ticket_no),KEYidx_status_assignee(status,assignee_id),KEYidx_customer_create(customer_id,create_time))ENGINEInnoDBDEFAULTCHARSETutf8mb4COMMENT售后工单表;注意version那个字段。它不是从功能里推出来的是从两个人同时抢单怎么办这个异常流程里推出来的。异常流程会反向决定表结构这也是为什么异常流程不能省。4.3 只有支持XX没有边界数值“支持导出”——导出多少条导出的过程中超时了怎么办导出的文件多久过期“支持批量操作”——一次最多多少条中途失败是整体回滚还是跳过失败的我在文档里现在但凡看到支持就在后面跟一个括号写数值。上面模板里写的是标题 2-100 字、附件最多 5 个单个 ≤ 10MB、单人处理中工单上限 20 条、客户 72 小时未回复自动关闭。这些数字有一半是我拍的但拍出来的数字也比没有数字强因为拍的数字可以讨论、可以改空白只能靠猜。4.4 没有权限矩阵谁能操作这种事写在正文里一定会漏。必须做成矩阵行是操作、列是角色每个格子只能是允许或禁止。我上面那份模板里的矩阵一共五行三列十五个格子。写的时候你会发现有些格子你自己都不知道答案——比如客服能不能转派别人的工单。这种格子就是待确认项去找人问别自己填。4.5 没有验收标准也没有本期不做这两件事其实是同一件事的反面一个是怎样算做完一个是哪些不算这期的活。没有验收标准的项目验收会上就会变成各说各话。我现在写验收标准的原则是必须可测——「响应要快」不合格「列表查询响应时间不高于 500ms」才合格。五、用/需求分析生成之后我必补的六个地方现在我接到需求会先让/需求分析出一份初稿它会在项目docs目录下生成需求文档和业务设计文档。这一步上一篇讲过不重复。这里我想说的是初稿到能开工之间永远差着一段人工补齐的距离。我列一下每次必补的东西以及为什么 AI 补不了。模块AI 生成的默认内容我必补的部分为什么必须自己补异常流程覆盖常见失败场景偏通用业务特有的失败分支离职转派、重复投诉它不知道你们公司的特殊情况数据字典类型和长度基本合理精度、枚举取值、唯一键规则精度跟业务单价/量级强相关权限矩阵角色划分清晰操作粒度偏粗逐级拆到按钮级补上谁能转派别人的组织架构只有你知道边界数值多数不写或写得很保守分页上限、导出上限、超时时长、并发上限数值要跟运维和历史数据对齐非功能需求有性能、安全等条目换成可测的具体数值和口径响应快没法验收不做清单基本不写本期明确不做的范围只有你知道排期砍了谁补齐这些大概占我整个需求分析时间的三成另外七成是思考和找人确认。这个比例我觉得挺健康——AI 负责把骨架搭出来并且不遗漏通用项我负责往里填只有我知道的东西。我举个具体的例子。/需求分析给工单系统生成的初稿里权限部分只写了「客服、客服主管、客户」三个角色每个角色一句话描述。这不够用因为客服能不能转派别人的工单这种格子是空的。我把它拆成操作 × 角色的矩阵十五个格子其中三个我当场答不上来第二天找主管确认后才填上。这三个格子要是没被摊开摆到表格里就会变成我脑子里的一个默认值然后在某天变成一个生产事故。还有一个我每次都会补的地方跟已有系统的衔接。AI 生成的文档是站在从零开始的视角写的但真实项目从来不是从零开始。工单系统要读客户信息那客户数据在哪个库工单通知要发到企业微信那现有的消息中心接口是什么这些衔接点不写进文档开发到一半就会卡住去问人。补齐之后还有一步把最终文档回喂给后续环节。我执行/前后端设计的时候会明确指向这份改过的文档路径这样生成的数据库设计和接口设计才是基于确认后的结论而不是基于初稿。这一步不做前面全白改。六、开工前的十分钟自检文档写完我不急着建表会花十分钟过一遍下面这份清单。有任何一条答不上来就回去补文档不写代码。每个功能的异常流程是不是都有编号编号能不能对上验收用例数据字典里有没有哪个字段的必填是空的状态机里有没有标出不可逆的终态涉及并发的操作是不是都定了谁赢所有支持XX后面是不是都跟了数值权限矩阵里有没有空格子本期不做的清单有没有发给需求方确认过这份文档一个刚来一周的新人能不能照着写代码第 8 条是我最看重的。文档写完我会假设自己是个不了解业务的人重读一遍凡是读着要停下来想的地方就是要补的地方。补完之后把文档里的约束翻译成代码层的校验让规则在编译和运行期都能拦住DatapublicclassTicketCreateDTO{NotBlank(message标题不能为空)Size(min2,max100,message标题长度为 2-100 字)privateStringtitle;Size(max2000,message问题描述最多 2000 字)privateStringdescription;NotNull(message客户ID不能为空)privateLongcustomerId;NotNull(message优先级不能为空)Min(value0,message优先级取值非法)Max(value3,message优先级取值非法)privateIntegerpriority;Size(max5,message附件最多 5 个)privateListStringattachments;}这段东西没有任何技术含量但它存在的意义是需求文档里那条标题 2-100 字不再只是一行字谁违反它都会在接口层被拦下来。文档和代码对得上返工才不会发生。七、写在最后我以前特别抗拒写文档觉得那是给领导看的、跟写代码没关系的事。后来被返工搞怕了才慢慢接受一个现实文档不是写给别人的是写给三个月后的你自己的——那个版本的你已经忘了当时为什么这么设计只能靠文档回忆。AI 出来之后写文档这件事的门槛低了很多。一份结构完整、覆盖了通用项的需求文档初稿现在几分钟就能拿到。但这也带来一个新的风险太容易拿到一份看起来很完整的文档以至于你忘了检查它缺什么。我现在的做法是拿到初稿先挑刺按那五条硬标准一条一条过把缺的东西补齐再往下走。多花的那点时间换回来的是后面不用返工。说句扎心的实话大部分人不是不会写需求文档是从来没被人要求过——所以也就从来没人告诉过他他写的那份不合格。下一篇回到实操拿到这份能开工的文档之后怎么把它变成数据库设计和接口设计。