# Docx 设计文档 vs API 文档 差异对比

> 对比范围：`SHOPEE_010_出库集波V1.2.docx`（设计文档） vs `SHOPEE_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` 需上游配合写入，文档应说明前提条件 |
