11 KiB
11 KiB
Docx 设计文档 vs API 文档 差异对比
对比范围：
SHOPEE_010_出库集波V1.2.docx（设计文档） vsSHOPEE_010_出库集波V1.2_findBestMatchedRule_API.md（API 文档）对比基准：docx 中与
findBestMatchedRule接口直接相关的需求，逐条对照 API 文档覆盖情况和代码落地情况。
图例
| 标记 | 含义 |
|---|---|
| ✅ 已覆盖 | API 文档已描述，代码已实现 |
| ⚠️ 部分覆盖 | API 文档提及但不够完整，或代码实现与 docx 有偏差 |
| ❌ 未覆盖 | docx 有要求但 API 文档未提及，或代码未实现 |
| 🔲 N/A | 不适用于 API 文档范围（前端/页面/非本接口） |
一、请求与参数
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 1.1 | 用户选择出库类型（销售出库、调拨、RTS、RT），用户权限控制选择类型 | API 入口参数 shipmentType 支持 XSCK/MTO/RTS/RT，但未提及用户权限校验 |
⚠️ 部分覆盖 — 参数已支持，权限校验代码未实现（待办事项 P1） |
| 1.2 | 同一个工作站不会混做不同类型 | API 文档需补充该约束；代码入口已通过 USED 格口关联 Shopee 波次反查当前工作站出库类型 |
⚠️ 部分覆盖 — 后端入口已返回 MSG_WRM_0014，前端约束和提示待补 |
| 1.3 | 登录工作站校验用户权限，用户权限跟订单类型绑定 | API 文档未提及用户权限校验 | ❌ 未覆盖 — 待办事项 P1 |
| 1.4 | 工作站编码或 workstationId 均可 | API 文档 workStation 支持编码或数字 ID（代码 findEnabledWorkStation 兼容两者） |
✅ 已覆盖 |
二、出库单类型与分流
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 2.1 | shipmentType：XSCK、MTO、RTS、RT |
API 文档出库类型表已列出四种 | ✅ 已覆盖 |
| 2.2 | 销售出库细分 ticketType：销售出库任务、销售出库订单 |
API 文档提及 ticketType=1 任务一波一单 |
✅ 已覆盖 |
| 2.3 | MTO 细分 ticketType：MTO任务、MTO出库订单 |
API 文档提及 ticketType=3 任务一波一单 |
✅ 已覆盖 |
| 2.4 | RT 单子不需要参与出库等接口，不使用上游波次号，走库内流程 | API 文档 RT 处理方式已描述 | ✅ 已覆盖 |
| 2.5 | 集波区分几种单据类型：XSCK、MTO、RTS、RT | API 文档已列出 | ✅ 已覆盖 |
| 2.6 | 推拣货任务（命中人工+自动化区）与推出库单（纯命中自动化区）区别：上游同步波次号段，无需取号逻辑 | API 文档推拣货任务 stationType=2 已描述 |
✅ 已覆盖 |
| 2.7 | 拣货任务 1 单跑 1 个波次，1拣货单1波次1槽口，后续无需补单 | API 文档已描述一单一波一槽口 | ✅ 已覆盖 |
| 2.8 | 推拣货任务区分标识待梳理接口后提供 | API 文档用 stationType=2 作为标识，但上游推单接口未联调 |
⚠️ 已实现待联调 |
| 2.9 | 推出库单按上文进行集波即可 | API 文档标准集波流程已描述 | ✅ 已覆盖 |
三、规则匹配与优先级
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 3.1 | 按 wave_rule 表优先级 wavePriority 排序集波（数字越大优先级越高） |
API 文档「上墙优先级」已描述 wavePriority desc |
✅ 已覆盖 |
| 3.2 | 如果工作站有槽口未绑定 wave rule 默认所有规则都可以按优先级去依次匹单 | API 文档格口三层级中 emptyCells 兜底，但「业务上是否启用」标注待确认 |
⚠️ 部分覆盖 — 代码已实现 matchEmptyCells，业务口径待确认 |
| 3.3 | 抓单优先级：shipment_header.priority → cutOffTime → purchaseTime → orderTime |
API 文档已完整描述 | ✅ 已覆盖 |
| 3.4 | priority 数字越大优先级越高 |
API 文档已描述 | ✅ 已覆盖 |
| 3.5 | cutOffTime、purchaseTime、orderTime 越早越优先 |
API 文档已描述 | ✅ 已覆盖 |
| 3.6 | 高优先级规则不足 maxShipments 时仍优先消费当前规则 |
API 文档未显式提及，但代码 assignCellNumbers 中有 logPriorityRuleConsumption 处理 |
⚠️ API 文档未提及此容错逻辑 |
四、格口分配
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 4.1 | 分拨墙槽口需支持 1 口绑定多波次规则 9+ | API 文档格口 waveRule 多值逗号分隔 |
✅ 已覆盖 |
| 4.2 | 格口分配：优先用 currentWaveRule 相同的格口，其次 waveRule 匹配，最后空闲格口 |
API 文档三层级分配策略已描述 | ✅ 已覆盖 |
| 4.3 | 集波后绑定对应 wcs_sorting_wall_cell 表 waveRule 设定相同规则的槽口 |
API 文档格口分配后写 currentWaveRule |
✅ 已覆盖 |
| 4.4 | 格口返回视图需分播墙上下文 | API 文档响应包含 sortingWallId / sortingWallCode |
✅ 已覆盖 |
五、Shopee 波次绑定
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 5.1 | Shopee 波次号段由上游接口提前落库 | API 文档提及从 shopee_wave 表 status=100 取号，未描述申请接口 |
❌ 未覆盖 — 待办事项 P1（号段申请接口） |
| 5.2 | 按 status=100 抢占为 200，避免并发重复取号 |
API 文档已描述 | ✅ 已覆盖 |
| 5.3 | 出库单头写入 shopeeWave |
API 文档 bindShipmentToShopeeWave 已描述 |
✅ 已覆盖 |
| 5.4 | 任务头写入 shopeeWave、waveRule |
API 文档相关表已列出，但回写链路待验证 | ⚠️ 部分覆盖 — 代码已写回，结果验证待执行 |
| 5.5 | Shopee 波次号段用完后继续申请 | API 文档未提及用完续号逻辑 | ❌ 未覆盖 — 待办事项 P1 |
| 5.6 | ESS 请求校验是否允许集入同一个 Shopee 波次 | API 文档已描述 | ✅ 已覆盖 |
| 5.7 | ESS 拒绝单据写入 kickOutWave，同波次后续过滤 |
API 文档已描述 | ✅ 已覆盖 |
六、内部波次与运行
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 6.1 | 集波后自动运行波次 | API 文档 addShipmentsToInternalWave → WaveService#run 异步提交队列消息 |
✅ 已覆盖 |
| 6.2 | 内部波次记录 waveRule |
API 文档已描述 | ✅ 已覆盖 |
| 6.3 | 波次运行如果有库存不足的单据直接踢单，需请求上游撤单接口 | API 文档未明确异步回池职责 | ⚠️ 部分覆盖 — wms-wave 回池链路清 Shopee 绑定且不写 kickOutWave，上游撤单接口待接入 |
| 6.4 | 库存最优分配逻辑：先到期先出→半径最小→低层优先 | API 文档未提及 | ❌ 未覆盖 — P2 |
| 6.5 | 波次运行成功将波次号绑定在拣货任务头 shopeeWave + 出库单头 shopeeWave |
API 文档相关表已列出 | ✅ 已覆盖 |
七、订单结构（shipmentCategory1）
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 7.1 | 出库单自动分析订单结构，打在 shipmentCategory1：SSSQ=1、SSAQ=4、MSAQ=3、MSSQ=5、Same SKU Same Qty=2 |
API 文档提及 shipmentCategory1 用于波次类型匹配，但未列出编码映射表 |
⚠️ 部分覆盖 — 编码表在待办事项文档中，API 文档未包含 |
| 7.2 | wave_rule.waveType 与 shopee_wave.waveType 口径一致 |
API 文档已描述 | ✅ 已覆盖 |
八、并发与异常
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 8.1 | 同一工作站同一出库类型不能重复集波 | API 文档 Redis 锁已描述 | ✅ 已覆盖 |
| 8.2 | 集波抓单只抓标记为正常的单据（cancel、挂起、标记异常的单子都不抓） | API 文档异常过滤条件已列出（cancelTime/holdTime/processType） |
✅ 已覆盖 |
| 8.3 | 订单池 100 状态单据才允许参与集波 | API 文档 leadingSts=100 / trailingSts=100 |
✅ 已覆盖 |
九、Flow Pick 单品单件
| # | Docx 要求 | API 文档 | 状态 |
|---|---|---|---|
| 9.1 | 单品单件 wave rule 支持动态加单或踢单 | API 文档仅提及补单机制，踢单由 wms-wave 异步回池链路处理 |
⚠️ 部分覆盖 — 加单已实现，库存不足踢单上游撤单待接入 |
| 9.2 | low_threshold 低阈值补单 |
API 文档已描述 | ✅ 已覆盖 |
| 9.3 | 槽口放满封箱再换波次 | API 文档已描述 Flow Pick 满槽换箱换波 | ✅ 已覆盖 |
| 9.4 | 换箱换波需调用上游换箱接口（区别于普通合波校验） | API 文档未提及 Flow Pick 接口对接状态 | ⚠️ 部分覆盖 — 代码已占位待联调 |
十、页面/前端能力（不适用 API 文档）
| # | Docx 要求 | 说明 | 状态 |
|---|---|---|---|
| 10.1 | 出库单界面新增按钮：更新按单拣选 | 页面功能，非 API 范围 | 🔲 N/A |
| 10.2 | Dropdown 支持 All、多选、模糊搜索 | 规则配置页面 | 🔲 N/A |
| 10.3 | Input 支持输入多个值 | 规则配置页面 | 🔲 N/A |
| 10.4 | Include / Exclude / Only 语义 |
规则配置页面 | 🔲 N/A |
| 10.5 | Max SKU Pieces Per Order |
非 WaveRule 字段，需基于 shipment_detail 聚合 |
🔲 N/A |
| 10.6 | Mix Mode Max SKU Pieces Filter |
MSAQ 规则，需基于明细聚合 | 🔲 N/A |
汇总
| 分类 | 总数 | ✅ 已覆盖 | ⚠️ 部分覆盖 | ❌ 未覆盖 | 🔲 N/A |
|---|---|---|---|---|---|
| 一、请求与参数 | 4 | 1 | 1 | 2 | 0 |
| 二、出库单类型与分流 | 9 | 7 | 1 | 0 | 0 |
| 三、规则匹配与优先级 | 6 | 4 | 2 | 0 | 0 |
| 四、格口分配 | 4 | 4 | 0 | 0 | 0 |
| 五、Shopee 波次绑定 | 7 | 5 | 1 | 1 | 0 |
| 六、内部波次与运行 | 5 | 3 | 0 | 2 | 0 |
| 七、订单结构 | 2 | 1 | 1 | 0 | 0 |
| 八、并发与异常 | 3 | 3 | 0 | 0 | 0 |
| 九、Flow Pick | 4 | 2 | 2 | 0 | 0 |
| 十、页面能力 | 6 | 0 | 0 | 0 | 6 |
| 合计 | 50 | 30 (60%) | 8 (16%) | 5 (10%) | 6 (12%) |
关键缺口（❌ 未覆盖）
| # | 缺口 | 影响 | 优先级 |
|---|---|---|---|
| 1 | 库存不足踢单上游撤单接口 | 波次运行后如库存不足，wms-wave 已负责回池和清 Shopee 绑定，但仍无法通知上游撤单 |
P0 |
| 2 | 用户权限 + 出库类型绑定 | 工作站用户可越权选择无权操作的单据类型 | P1 |
| 3 | Shopee 波次号段申请接口 & 用完续号 | 号段只能被动消耗，无法主动申请新号段 | P1 |
| 4 | 库存最优分配规则（到期日/半径/低层） | 当前无库存分配算法，docx 明确要求 | P2 |
API 文档可补充项
| # | 建议补充 | 原因 |
|---|---|---|
| 1 | 高优先级规则不足 maxShipments 时仍优先消费的容错说明 |
当前代码行为与直觉相反，文档应解释 |
| 2 | shipmentCategory1 编码映射表（SSSQ=1 / SSAQ=4 / MSAQ=3 / MSSQ=5 / Same SKU Same Qty=2） |
docx 明确列出，API 文档未包含 |
| 3 | Flow Pick 换箱换波接口对接状态说明 | 当前代码已占位待联调，文档应注明 |
| 4 | 推拣货任务上游推单接口联调说明 | stationType=2 需上游配合写入，文档应说明前提条件 |