1. 先弄清楚这份文档到底是写给谁看的

WMS仓库管理系统需求规格说明书，我前后写过四版，第一版被业务方批了七十多条意见，最后一版只改了十一处就签字过审。差别不在文笔，而在我终于搞清楚了这份文档的读者是三类完全不同的人，他们关心的东西几乎没有交集。写说明书这件事，本质上不是“把需求记录清楚”，而是“让三方在同一份文字上达成一个可以验收的共识”。

三类人分别是：业务方，也就是仓库主管和计划、采购、客服这些下游使用者，他们只关心“我的活怎么干、异常怎么办、出问题谁负责”；开发方，关心字段、状态、边界条件、并发和异常分支；测试方，关心每一条需求能不能变成一个可执行的验证用例。第一版说明书之所以被骂，是因为我写成了给开发看的技术文档，业务方读了三页就放下了，等到验收的时候他们才发现“我要的其实不是这个”。

所以这份文档的第一个设计决策就出来了：用业务语言描述动作，用技术语言描述约束，两者分离但互相索引。业务流程章节不出现表名字段名，接口与数据章节不出现“大概、尽量、视情况”这类模糊词。听起来简单，但我见过大量文档把这两者搅在一起，最后业务方看不懂流程，开发抓不住约束。

1.1 一份说明书要解决的其实是三拨人的分歧

具体到WMS这个领域，分歧点特别密集。举个最常见的：业务方说“收货要快”，开发听到的是“界面响应要快”，实际业务方想说的是“从卸货到上架不能超过四小时，因为月台只有六个位”。这两个理解的实现成本差了一个数量级。需求规格说明书的价值，就是在这种地方把“快”这个形容词钉死成“月台占用时长≤4小时、单车卸货≤40分钟、收货单录入≤90秒”。

我在实际项目里养成一个习惯，需求调研时随身带一张“形容词清单”，凡是听到快、准、稳、实时、自动、灵活这类词，当场追问三个问题：跟什么比快？慢了会怎样？谁来判定达标？追问出来的答案直接写进文档的“指标定义”小节。这个方法救过我一次——某仓储企业要求“库存实时同步”，追问下来才知道他们的“实时”是指班次结束前同步就行，一天四次足够，硬做成秒级同步会白白增加一倍接口开发和运维成本。

另一个高频分歧是“灵活”。业务方要“策略灵活配置”，如果照抄进文档，开发会做成一个大而全的规则引擎，最后没人会用。我的处理方式是把“灵活”拆成可枚举的场景清单：上架策略几种、拣选策略几种、分配规则几种，每种给出参数范围和默认值。文档里写清楚“本期支持A/B/C三种，D场景走人工指定”，把边界画出来，比写十页“系统应具备高度灵活性”有用一百倍。

1.2 文档骨架的取舍：把“策略”从“流程”里剥出来

标准的需求规格说明书模板通常是“引言、总体描述、功能需求、非功能需求、接口需求、附录”，这个骨架没错，但直接套用在WMS上会很别扭。原因是WMS的功能流程高度同质化——几乎所有仓库都是收货、上架、拣货、复核、发货、盘点这几步，真正拉开差距的是每一步背后的策略和异常分支。

我的做法是把骨架改成“流程主干+策略挂件”两层结构：主干章节只描述标准路径，每个流程节点下面挂一个“策略与参数”小节，再挂一个“异常分支”小节。这样写有三个好处：业务方读主干就能确认“我的活是不是这么干的”；开发读策略小节能拿到明确的参数表；测试读异常分支能直接生成用例。

这里有个实操细节值得说：流程主干一定要配状态机图，但不要用流程图。流程图表达的是“顺序”，状态机表达的是“任意时刻这个东西处于什么状态、能往哪走”。WMS里最典型的坑是“一张入库单既可能部分收货又可能被取消，取消后已上架的货怎么回退”，纯流程图根本画不出来，状态迁移表一行一行列清楚，开发和测试都省事。我给每个核心单据（入库单、出库单、盘点单、移库单）都配一张状态迁移表，表头固定为“当前状态、触发动作、前置条件、目标状态、副作用”，副作用那一列专门写库存变动、消息推送、单据生成，这一列写全了，后期联调问题能少一半。

2. 需求调研阶段：怎么把仓库里的话翻译成文档语言

坐在会议室里问“你们需要什么功能”，得到的永远是“要好用、要准确、要能查”。真正有效的信息在仓库现场，在拣货员骂娘的那一瞬间。我调研WMS的习惯是至少跟三班：早班开工的头两小时、下午出库高峰、夜班盘点或补货。三个时段看到的问题完全不同，早班暴露的是收货拥堵和月台调度，下午暴露的是拣选路径和缺货，夜班暴露的是账实差异和批次混乱。

跟班的时候我不带笔记本，带手机和一张A4纸。手机拍现场的单据、看板、手写标记、货架标签，A4纸画布局和动线。回来之后再整理成文档素材。这个顺序不能反，先访谈后跟班，访谈得到的是“他们认为的问题”，跟班得到的是“实际发生的问题”，两者经常对不上。某快消品牌的仓库主管坚信自己的拣货效率瓶颈在系统查询慢，我跟了一个下午发现真正的瓶颈是拣货员每单要横跨三个区，走了两百多米，系统查询那两秒根本不算什么。

2.1 现场跟单：盯住三个时段和四类单据

三个时段之外，还要盯四类单据：纸质拣货单、手工补货单、异常登记本、交接班记录。前两类告诉你标准流程怎么跑，后两类告诉你不标准的情况有多少。异常登记本尤其值钱，那是仓库自己记录的问题流水，翻一个月就能统计出高频异常类型，直接变成文档里的异常分支清单。

整理阶段我会做一件事：把现场拍到的所有单据字段抄成一张表，和业务方口头描述的字段做比对。差异往往出现在三个地方——手写补充字段（说明系统缺字段）、划掉的字段（说明系统字段没用）、以及同一含义的多种叫法（说明后续要做数据字典）。某项目里“批次号”在现场有四种叫法，如果不统一，接口对接时必然出错。

2.2 从口述到结构化：场景表的六列写法

口述转结构化，我用一张固定六列的场景表：场景编号、触发条件、参与角色、前置状态、操作步骤、结束判定。这张表是整份说明书的原材料，后面所有功能章节都是从它展开的。

这张表填完，一个中等规模仓库通常有120到200个场景。数量听起来多，但真正复杂的只有二十来个，其余都是变体。我的做法是先按域分组，每组挑三个最复杂的场景写详细，其余用“同XX场景，差异在于……”的方式引用，文档长度能压下来三分之一，可读性反而上升。

注意：场景表一定要让业务方逐行签字确认，尤其是“结束判定”那一列。这一列是后期验收争议的最大来源，写“上架完成”四个字，业务方理解的是货放到架上，开发理解的是系统状态变更，两者中间可能差了一次人工复核。

3. 核心业务域的规格拆解

WMS的功能域拆法各家不同，我习惯按“单据流+库存流”两条线切：单据流是入库、出库、移库、盘点、调整，库存流是可用量、锁定量、在途量、批次维度。两条线交叉的地方就是最容易出问题的地方，也就是文档必须写细的地方。

下面按我实际写文档的顺序展开，每个域给一份可直接抄的结构。

3.1 入库域：把预约、收货、质检、上架拆成四段

入库看起来是“货来了收进来”，实际是一条很长的链：供应商或承运商预约到货时间、月台分配、卸货、清点、质检、上架、回单。链条上每一段都可能卡住，卡住的原因又各不相同。文档里我把入库拆成四段独立规格，每段有自己的状态和异常出口。

第一段是到货预约。要写清楚预约粒度（按车还是按单）、时间窗长度（我一般设30分钟一个窗）、超额预约怎么处理、爽约怎么记录。这里有个容易被忽略的参数：月台数量与时间窗的匹配关系。假设月台6个，单车平均占用40分钟，那么理论上一小时能处理9车，如果按30分钟一个窗放行，每小时最多放12车就会排队。文档里要明确写出这个换算，并给出建议放行量，否则上线第一周月台必堵。

第二段是收货清点。核心是差异处理规则：实收与应收不一致时，允许的差异比例是多少、超过比例走什么流程、部分收货后单据状态怎么变。我一般建议设置三档：差异率≤1%直接收，1%到5%需要主管确认，超过5%转异常处理单。这三档必须写进文档，不能留给现场自由裁量。

第三段是质检。要不要质检、抽检比例、不合格品放哪个库位、能否让步接收，这些是业务规则，必须由业务方给值，开发不能自己定。文档里用一张规则表列出来，留空让业务方填。

第四段是上架。这是策略密集区，见下面的策略表。

上架策略最容易写错的地方是冲突优先级。上面五条策略同时命中一个库位时听谁的？文档里必须给出优先级顺序和冲突时的降级规则，否则开发会自己拍一个顺序，上线后现场发现货放得莫名其妙。

3.2 出库域：波次、分配、拣选、复核的规格怎么写

出库是WMS里最复杂的一块，复杂度来自订单的组合爆炸。文档写法上我建议按“订单池—波次—任务—复核—发货”五级展开，每一级写清楚输入、输出和约束。

波次策略要参数化描述。常见的维度有：订单类型、承运商、截单时间、区域、SKU重合度、订单行数。文档里不要写“系统应支持灵活波次”，而是列一张波次规则表，每行一条规则，写清触发条件、包含订单范围、生成的任务类型。比如“规则W03：截单时间前2小时，同一承运商、订单行数≤5的订单合并为一个波次，波次内订单数上限80”。这种写法开发和业务都能看懂，测试也能直接验。

分配规则的规格要写三件事：分配顺序（先分配什么订单）、库存来源优先级（从哪个库位、哪个批次取）、缺货处理（部分分配还是整单挂起）。缺货处理是争议高发区，我一般建议默认整单挂起、可配置为部分分配，并在文档里明确“部分分配后剩余数量是否保留占用”。

拣选环节要写清任务粒度（按单、按区、按SKU合并）、路径生成方式（系统排序还是人工排序）、拣选确认方式（扫码、按键、语音）。这里有个实操经验：拣选确认的字段一定要包含库位码和SKU码双重校验，只扫SKU会出现“扫了正确的货但从错误的库位拿的”这种情况，账实很快就乱了。

复核与发货要写清称重、装箱、面单打印、交接签收四个动作的责任人和异常出口。发货确认这一步一定要有“库存扣减时点”的明确定义，是复核完成扣减还是交接完成扣减，两者差异会导致发货途中的库存归属不清。

3.3 库存模型：为什么必须把“可用、锁定、在途”分开写

库存这块，文档里如果只写“系统应准确记录库存数量”，等于什么都没写。必须把库存拆成多个维度，每个维度定义清楚计算口径和变动时机。

维度定义完，还要写清楚变动时序。比如一笔出库，分配时锁定加、可用减，复核时物理减、锁定减。如果文档里不把这个时序写死，开发很可能在发货时才扣物理库存，中间那段时间可用库存是虚高的，客服会卖出去不存在的货。

批次和效期管理要单独成节。写清楚批次号的生成规则、是否允许混批、效期预警的提前天数、临期品能否出库的规则。效期预警天数这个参数一定要业务方给，我见过设7天的，也见过设90天的，取决于品类周转速度。

3.4 盘点与差异处理：把“账实不符”当成正常需求写

新手写文档最容易把盘点写成“生成盘点单、录入实盘数、生成差异、调整库存”四步了事。实际盘点最难的是盘点期间的作业冻结。盘的时候能不能收货、能不能发货、能不能移库，这四种组合各有各的代价，文档里必须让业务方明确选择。

我一般给三个方案让业务方选：全仓冻结（准确但停业）、分区循环盘点（不停业但复杂）、动碰盘点（只盘有变动的库位，最快但覆盖不全）。选哪个写进文档，配套写清楚冻结的粒度（按库区、按库位、按SKU）和解除条件。

差异处理要写阈值和审批链。差异率在千分之几以内直接调整，超过就走审批，超过某个比例触发复盘。这些数字必须写进文档，并注明“由业务方在配置中维护”，避免硬编码。

3.5 接口清单：把“对接ERP”翻译成字段级契约

“与上游系统对接”这七个字在文档里毫无价值。接口部分我按三张表写：接口清单表、字段映射表、异常与重试规则表。

接口清单表每行一个接口，写清方向、触发方式、频率、数据量级、超时要求、失败处理。字段映射表至少覆盖主数据（商品、供应商、客户、仓库、库位）和单据（入库单、出库单、库存快照）。异常重试规则表写清哪些错误可重试、重试次数、重试间隔、超过次数后的告警对象。

给一个入库单接口的契约示例，实际文档里这种片段会配上完整的字段说明：

{ "docNo": "ASN202405130001", "warehouseCode": "WH01", "supplierCode": "SUP0093", "expectedArrival": "2024-05-13T09:30:00", "lines": [ { "lineNo": 1, "skuCode": "SKU10231", "expectedQty": 600, "unit": "PCS", "batchNo": "B202405", "productionDate": "2024-05-02", "expiryDate": "2025-05-01" } ] }

字段说明里必须写清楚哪些字段是必填、长度上限、编码规则、是否允许重复推送（幂等键是哪个）。幂等这一条特别重要，很多对接事故就是上游超时重推导致重复入库。

4. 非功能需求：最容易被跳过却最容易翻车的部分

功能需求写得多细都不算过分，但真正决定系统能不能上生产的，是非功能需求。我见过功能全部验收通过、上线第三天因为并发拣选卡死而回滚的项目。非功能需求写不好，通常不是不会写，是不知道怎么把“要快”变成可测量的数。

我的写法是每个非功能项都写成“指标+测量方法+不达标的处理”。只有指标没有测量方法，验收时就要扯皮；只有指标没有处理方案，开发会假装看不见。

4.1 性能指标怎么算才不算拍脑袋

性能指标必须从业务量倒推，不能拍。推算过程要写进文档，让评审的人能复核。

以出库拣选为例。假设日均出库订单8000单，其中60%集中在上午9点到11点这两个小时，也就是4800单/2小时=2400单/小时=0.67单/秒。平均每单5行，即3.3行/秒。考虑大促翻倍和未来两年增长，留三倍余量，取10行/秒作为系统处理能力目标。拣选员单次扫码确认平均耗时1.5秒，峰值在线拣选员120人，那么扫码确认这个动作的并发要求是80次/秒。

把这些推导过程写成表格放进文档，评审会上没人能反驳，开发也知道该往哪个方向优化。

注意P95这个写法。只写“平均响应时间”是没有意义的，平均值会把慢请求藏起来。文档里统一用P95和P99，并注明采样窗口和样本量。

4.2 数据一致性与并发控制要写到实现层面

库存扣减的并发问题是WMS的经典事故点。两个拣选员同时确认同一个库位的最后10件货，如果处理不当就会出现负库存。文档里要明确写清并发控制的策略层级，不能只写“保证不超卖”。

我的写法是分三层描述：业务层用锁定量做前置拦截，分配时先锁后扣；应用层用版本号或分布式锁控制同一库位同一SKU的并发更新；数据层用行锁加约束兜底，库存字段加非负约束。三层都要写，任何一层缺失都可能出问题。

一致性还要写清跨系统场景。与上游系统之间是强一致还是最终一致，最终一致的允许延迟是多少，出现不一致时以谁为准，对账机制是什么频率、差异怎么处理。这些必须落成文字，否则出问题时各方互相甩锅。

4.3 权限、审计与可追溯不能只写一句“应有日志”

权限要按角色和数据范围两层写。角色是功能权限，数据范围是能看哪个仓库、哪个库区、哪个客户的数据。两层不分开写，开发大概率只做菜单权限，结果A仓的人能看到B仓的库存。

审计要写清哪些操作必须留痕、留哪些字段、保存多久、谁能查。WMS里必须留痕的操作我列了一张最小清单：库存调整、单据作废、价格或规则参数变更、权限变更、强制出库、盘点差异确认。每条留痕至少包含操作人、时间、操作前后值、原因备注。

可追溯性则要写清正向和反向两条链路：从一批货能查到它进了哪些订单，从一个订单能查到用了哪些批次的货。这条需求如果前期不写，后期补的代价极大，因为需要在出入库明细里预留关联字段。

5. 落地写法：验收标准与用例编号怎么配合

需求写完不算完，能不能验收才是关键。我给每条功能需求都强制配一条验收标准，格式用Given-When-Then。这个格式的好处是把前置条件、动作、预期结果三段分开，测试可以直接拿去用，业务方也能读懂。

举个实际的例子。需求“出库单分配时若可用库存不足，应按配置决定整单挂起或部分分配”，对应的验收标准写成：给定可用库存50件、订单需求80件、配置为整单挂起；当触发分配；则订单状态变为待补货，锁定量为0，可用库存仍为50。再补一条配置为部分分配时的验收标准，锁定量为50，订单剩余30件进入待补货队列。

5.1 用例矩阵：用正交表压缩测试组合

WMS的测试组合是爆炸式的，订单类型×承运商×库存状态×批次属性，随便一乘就是几百种。文档里如果只列需求不列组合，测试会挑简单的验，复杂的漏掉。我的做法是在文档附录放一张用例矩阵，用正交思路挑组合。

这张表放进文档，评审时业务方一眼就能看出“紧急出库优先出临期”这条规则他们没提过，当场就能补。这比后期测试阶段发现要省太多事。

5.2 字段字典与状态码约定要前置

字段字典这件事，很多团队放到详细设计阶段做，结果需求文档里同一个字段有三种叫法，开发各写各的，联调时对不上。我的做法是需求文档里就附一份核心字段字典，只覆盖跨模块共用的字段，模块内部字段留给设计阶段。

字典至少包含：字段中文名、英文名、类型、长度、是否必填、取值范围、业务含义。特别要标注的是枚举值，比如单据状态、库存状态、异常类型，这些枚举一旦定下来，全系统统一，不允许各模块自定义。

状态码我建议用两段式：模块前缀+两位数字，比如入库单状态IN01到IN09，出库单OU01到OU12。文档里给出完整的状态码表，包含状态名和允许的迁移，这张表就是我前面说的状态迁移表，两处引用同一份，避免不一致。

6. 评审、变更与上线切换的方案设计

文档写完只是开始，评审和变更是后半程的主战场。评审组织得好，问题在前面暴露；组织不好，评审会变成朗读会，念两小时没人提意见。

我的评审节奏是三段式。第一段是业务走查，只请业务方，逐条过场景表和验收标准，不谈技术。第二段是技术评审，只请开发和测试，重点过接口、状态机、并发和异常分支。第三段是联合确认，三方一起，只过前两段遗留的争议项。三段分开的好处是每段的讨论深度够，混在一起业务方会被技术细节带跑。

6.1 变更控制：把“加个功能”变成可评估的流程

需求变更是必然的，尤其是WMS这种贴近现场的系统，上线前现场一定会提新想法。文档里要预留变更控制章节，写清楚变更的提出方式、评估维度、决策人和生效方式。

评估维度我固定四项：影响范围（涉及哪些模块和接口）、工作量估算、对已验收功能的影响、上线时间影响。四项都填完才能进入决策，避免一句“这个很小很快的”就把变更塞进来。我见过一个“很小”的变更——出库单加一个备注字段——最后牵扯到接口改造、报表调整、权限配置三处，花了六天。

变更生效方式也要写清：哪些变更走配置、哪些走版本发布。参数类的变更应当走配置，比如上架策略的权重、效期预警天数，这些如果每次都要发版，运维会被拖死。文档里单独列一张可配置参数清单，标注参数名、默认值、取值范围、生效时机、修改权限，这张表后期会变成运维手册的核心。

6.2 上线切换：数据迁移和并行方案

切换方案在需求文档里的位置容易被忽略，但它是上线风险的最大来源。至少要写清三件事：初始库存怎么来、存量单据怎么处理、并行期多长。

初始库存的导入方式，我一般建议按库位+SKU+批次三个维度做盘点后导入，导入前先冻结作业，导入后抽样复核，复核比例不低于5%。存量未完结单据要么全部作废重开，要么按状态映射迁移，这个选择必须由业务方拍板，文档里写明选择结果和理由。

并行期我建议至少两周，新旧系统同时记录，每天对账。对账口径要提前定义：按SKU对总量、按库位对明细、按批次对效期。差异超过阈值（比如千分之一）就停下来查，不能带着差异往前跑。

注意：切换方案里一定要写回滚条件。什么情况下判定切换失败、由谁决策回滚、回滚需要多长时间、回滚期间的数据怎么处理。这些写在文档里显得啰嗦，真出事的时候能救命。

7. 常见问题与排查技巧实录

这一节是我从几个项目的事故记录里整理出来的，都是文档没写清导致的。

7.1 库存对不上的六条典型链路

库存差异是WMS最高频的问题，根因往往不在库存模块本身，而在上下游的动作时序。

排查方法上，我的习惯是先看流水再看余额。余额是计算结果，流水是事实。把某个SKU某段时间的所有出入库流水拉出来，按时间排序，逐笔累加，和余额对不上就说明有流水缺失或重复。这个动作看起来笨，但比翻代码快得多。

7.2 需求歧义清单：写文档时自查用

我把几年下来被追问最多的歧义点整理成一张自查清单，写完文档逐条过一遍，能省掉大量返工。

• “系统应支持多仓库”——支持几个？仓之间库存是否共享？跨仓调拨算不算？
• “支持批次管理”——批次是收货时生成还是上游下发？允许混批存放吗？
• “自动分配库存”——分配失败是挂起还是拆单？拆分粒度是什么？
• “实时同步”——秒级还是分钟级？允许延迟多少？不一致时以谁为准？
• “权限可控”——控到菜单、按钮还是数据行？跨仓查询怎么管？
• “支持报表”——哪些报表、字段有哪些、导出格式、数据时效？
• “异常告警”——告警渠道、告警对象、告警频次限制、恢复通知？

每条歧义后面跟一句“必须由业务方确认”并留签字位，这是我在文档里保留的唯一一种“空着让人填”的写法。其他所有地方我都不允许留空，留空就是给后期埋雷。

最后分享一个我自己一直在用的小技巧：文档写完先别急着发，隔一天再读一遍，专门读那些带“应、需、要”的句子，把每句都换成“谁来判定这句话做到了”。凡是换不出来的，说明这句需求写得虚，回去重新写。这个方法听着土，但每次都能揪出十几处含糊表述，比开三次评审会都管用。