init

SHOPEE_010_出库集波V1.2_Docx_vs_API_对比.md

@@ -1,154 +0,0 @@
-# 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` 需上游配合写入，文档应说明前提条件 |

SHOPEE_010_出库集波V1.2_WaveRuleMatchService_功能完成度分析.md

@@ -1,346 +0,0 @@
-# WaveRuleMatchService 功能完成度分析
-
-对照来源：`C:\Users\zoe\Downloads\SHOPEE_010_出库集波V1.2.docx`
-
-代码范围：`C:\work\gitlab\shopee\wes-loghub\wms-wave\src\main\groovy\com\ittx\wms\wave\service\hairo\WaveRuleMatchService.groovy`
-
-更新日期：2026-06-02
-
-本文只维护 `WaveRuleMatchService` 对照最终需求仍未完成、未闭环或需要接口确认的功能。已落地且逻辑清晰的实现只在“已明确口径”中简要记录，不再作为待办展开。
-
-## 已明确口径
-
-- 首次集波入口保留 `ResponseMessage`。
-- 错误分支继续返回 `ResponseMessageFactory.error(...)`。
-- 首次集波成功只返回 `ResponseMessageFactory.success()`，不返回分配明细数据。
-- 首次集波不维护 `allocatedRows` 汇总。
-- 一波一单、缺货补满、空格口分配的执行结果通过系统处理日志记录。
-- 当前未保留 `pollReplenishment/pollReplenishmentOnce` 计划任务入口；补缺口能力收口在首次集波入口的 `fillShortageCells(...)`。
-- 一波一单规则已按当前确认口径修正：`XSCK + ticketType=1`、`ticketType=5`、`pickType=1`、`RT(ticketType=6)` 均进入一波一单，RT 不使用 Shopee 波次号。
-- `fillShortageCells(...)` 不返回 `rows`，只执行缺货补满副作用并记录系统处理日志。
-- `findShortageCells(...)` 已改为直接 SQL 查询 `wcs_sorting_wall_cell`。
-- `findShortageCells(...)` 限制 `useStatus = IDLE`、`shopeeWaveCode` 有值、`currentWaveRule = rule.code`。
-- `findCells(Long workStationId)` 已改为直接 SQL 查询 `wcs_sorting_wall_cell`。
-- 单品单件 `calcCellNeedQty(...)` 已改为只统计未拣货任务对应的出库单数量。
-- 非单品单件补单按 `maxShipments - 当前 Shopee wave 单量` 计算缺口。
-- `low_threshold` 只用于单品单件 wave rule 的补单触发判断。
-- 同一规则内抓单排序已按 `shipment_header.priority`、`cutOffTime`、`purchaseTime`、`orderTime`、`id` 处理。
-- `WAVE_RULE_FIELD_MATCHING` 已实现基础字段映射，字典口径为：`identifier` 是出库单字段，`value1` 是 `wave_rule` 字段，`value2` 是操作符。
-- ESS 校验失败单据已有基础 `kickOutWave` 记录能力。
-- 首次集波入口已有 Redis 工作站锁；Shopee 波次绑定使用波次号维度 Redis 锁。
-- 同工作站不混做不同订单类型已在入口层落地：Redis 锁前通过 `USED` 格口的 `shopeeWaveCode` 反查 `shipment_header.shipmentType`，发现其它出库类型时记录系统处理日志并返回 `MSG_WRM_0014`。
-- `WaveService#run` 是异步提交队列消息，当前服务不解析同步库存不足踢单结果。
-- 库存不足踢单不记录 `kickOutWave`，由 `wms-wave` 回池链路清空 Shopee 绑定并预留上游撤单接口。
-
-## P0 主链路缺口
-
-### 1. 计划任务轮询补单入口待恢复
-
-docx 要求：
-
-- 计划任务轮询正在作业的工作站和槽口。
-- 单品单件低于 `low_threshold` 时触发补单。
-- 非单品单件未达到 `maxShipments` 时触发补单。
-- 推拣货任务后续无需补单。
-
-当前代码：
-
-- 未保留 `pollReplenishment(...)`。
-- 未保留 `pollReplenishmentOnce(...)`。
-- 未保留 `replenishCell(...)`、`findPickingWorkstations(...)`、`findReplenishmentCells(...)`。
-- 已有 `fillShortageCells(...)`，但只在首次集波入口中执行，用于当前工作站已绑定 Shopee 波次格口的缺口补满。
-- 不保留新增测试类；后台轮询入口、工作站/格口扫描、逐格口补单派发仍需按最终调度策略恢复。
-
-仍需细化点：
-
-- 需要按系统参数控制是否启用、轮询间隔和仓库范围。
-- 需要恢复后台调度入口，并复用 `fillShortageCells/assignToCell` 现有补缺口能力。
-- 需要结合真实波次状态、连续空轮条件和接口响应做联调细化。
-
-当前实现口径：
-
-- 现有补缺口业务收口在 `fillShortageCells(...)`。
-- 后续如恢复计划任务，建议继续复用工作站 Redis 锁，避免和人工首次集波入口并发抢格口。
-
-### 2. 一波一单规则已按当前确认口径修正，剩余 ticketType 字典待补齐
-
-docx 要求：
-
-- 销售出库任务一波一单。
-- MTO 任务一波一单。
-- RT 一波一单。
-- 按单拣选单据一波一单。
-
-当前代码：
-
-- 常量已覆盖 `TICKET_TYPE_XSCK_TASK = 1`。
-- 常量已覆盖 `TICKET_TYPE_MTO_TASK = 5`。
-- 常量已覆盖 `TICKET_TYPE_RT = 6`。
-- `appendSingleWaveFilter(...)` 覆盖 `pickType = 1`、`ticketType in (1,5,6)`。
-- `appendBatchWaveFilter(...)` 排除 `pickType in (1,2)` 和 `ticketType in (1,5,6)`。
-- RT 按 `ticketType = 6` 整体一波一单，不使用 Shopee 波次号。
-- 不保留新增测试类；MTO `ticketType=5`、RT `ticketType=6` 仍需结合真实数据联调验证。
-
-未完成点：
-
-- 需要按最新数据字典确认 `ticketType` 1-7 的完整值域。
-- RT 已确认按 `ticketType = 6` 特殊处理“不使用 Shopee 波次号”，仍需真实数据验证。
-
-当前实现口径：
-
-- `appendSingleWaveFilter(...)` 覆盖按单拣选、XSCK 任务、MTO 任务、RT。
-- `appendBatchWaveFilter(...)` 同步排除 pickType 一波一单和当前出库类型下的一波一单 ticketType。
-
-### 3. 推拣货任务分流方法未接入首次集波主入口
-
-docx 要求：
-
-- 推拣货任务由上游同步 Shopee 波次号段。
-- WES 不走取号逻辑。
-- 根据出库类型和 wave rule 抓取该订单。
-- 一单一波次一槽口。
-- 后续无需补单。
-
-当前代码：
-
-- 当前未保留 `assignPickingTaskSingleWaves(...)`。
-- 当前未保留 `findPickingTaskShipments(...)`。
-- 当前未保留 `isPickingTaskReplenishmentCell(...)`。
-- 普通批量抓单 `appendBatchWaveFilter(...)` 排除了 `pickType = 2`。
-- 一波一单 `appendSingleWaveFilter(...)` 未包含 `pickType = 2`。
-
-未完成点：
-
-- 推拣货任务当前不会进入首次集波主链路。
-- 需要恢复或新增主入口分流。
-- 成功、失败、无数据均只记录系统处理日志，不返回明细数据。
-
-建议实现口径：
-
-- 在首次集波入口中增加推拣货任务分流。
-- 分流顺序建议放在普通空格口批量分配之前。
-- 推拣货任务继续不参与后续补单。
-
-### 4. 同工作站不混做不同订单类型已落地，待联调验证
-
-docx 要求：
-
-- 用户选择出库类型后，同一个工作站不会混做不同类型。
-
-当前代码：
-
-- `findBestMatchedRuleByWorkStationAndOutboundType(...)` 已在 Redis 锁前调用 `hasDifferentActiveShipmentType(...)`。
-- `findActiveWorkstationShipmentTypes(...)` 通过 `wcs_sorting_wall_cell` 已占用 `USED` 格口关联 `shopeeWaveCode`，反查 `shipment_header.shopeeWave` 和 `shipment_header.shipmentType`。
-- 如果当前工作站已有其它出库类型，记录系统处理日志并返回 `MSG_WRM_0014`。
-
-仍需验证点：
-
-- 需要用真实格口、Shopee 波次和出库单数据验证 SQL 关联是否覆盖全部正在作业场景。
-- 前端仍需配合做出库类型选择限制和提示。
-
-当前实现口径：
-
-- 优先按 `wcs_sorting_wall_cell` 已占用格口关联 `shopeeWaveCode` 反查 `shipment_header.shipmentType`。
-- 返回明确错误码 `MSG_WRM_0014`，并记录系统处理日志。
-
-## P1 上游接口和异常闭环
-
-### 5. Shopee 波次号段申请接口未实现
-
-docx 要求：
-
-- `shopee_wave` 每天向上游申请波次号段。
-- 本地号段用完后继续请求上游。
-
-当前代码：
-
-- `acquireUnusedShopeeWave(...)` 只从本地 `shopee_wave` 表取 `status = 100` 的号段。
-- 本地号段为空时直接返回空。
-- 方法旁已有 TODO 注释。
-
-未完成点：
-
-- 需要接入上游号段申请接口。
-- 需要明确请求参数、返回结构、失败重试策略。
-- 需要明确申请后如何落库以及状态初始值。
-
-### 6. Shopee 波次绑定接口仍是占位
-
-docx 要求：
-
-- 用 Shopee wave + 抓取单号请求上游校验是否允许集在一波。
-- 当前确认口径为上游绑定接口只有整批成功或整批失败。
-- 失败单据写入 `shipment_header.kickOutWave`。
-- 后续同 Shopee wave 补单时过滤这些单据。
-
-当前代码：
-
-- `bindShipmentShopeeWave(...)` 已有批量绑定和失败单据 `kickOutWave` 记录逻辑。
-- `bindShipmentShopeeWave(...)` 内使用 Shopee 波次号维度 Redis 锁控制并发。
-- 获取锁后会重新检查 `shopee_wave` 号段是否仍可用。
-- `requestShopeeWaveBind(...)` 是真实上游绑定接口预留位置。
-- 当前按整批成功/整批失败处理：失败整批写 `kickOutWave`，成功整批写 `shipment_header.shopeeWave` 并同步 `shopee_wave.pickType/groupKey/status`。
-
-未完成点：
-
-- 真实 ESS service、方法名、请求 DTO、响应 DTO 未确认。
-- 真实接口成功/失败判断字段未确认。
-- 生产环境接口缺失时是否允许放行需要确认。
-
-建议实现口径：
-
-- 接入正式接口后只补齐 `requestShopeeWaveBind(...)`。
-- 响应解析只保留整批成功/失败字段。
-- 生产环境接口缺失时建议失败并记录系统处理日志，不建议静默全部通过。
-
-### 7. Flow Pick 封箱和换箱换波接口仍是占位
-
-docx 要求：
-
-- 单品单件满槽后先封箱。
-- 请求 Flow Pick 换箱接口。
-- 上游校验 OK 后，剩余订单切到新 Shopee 波次。
-- 上游校验不 OK 时，订单回订单池，取消任务下发，通知 AGV 取消回库。
-
-当前代码：
-
-- `changeFlowPickWave(...)` 已有本地流程。
-- `requestFlowPickSealBox(...)` 动态调用 `sealBox`。
-- `requestFlowPickChangeBox(...)` 动态调用 `changeBoxWave`。
-- `essFlowPickService == null` 时本地继续。
-- `handleFlowPickChangeWaveFailure(...)` 只记录系统处理日志。
-- `isFlowPickCellFull(...)` 仍以 `maxShipments` 作为满槽判断。
-
-未完成点：
-
-- Flow Pick 封箱正式接口未接入。
-- Flow Pick 换箱正式接口未接入。
-- 换箱失败后的订单回池、任务取消、AGV 取消回库未实现。
-- 满槽判断还不是 WCS 真实物理满箱信号。
-
-### 8. 库存不足踢单和上游撤单闭环未完全落在当前链路
-
-docx 要求：
-
-- 波次运行如果有库存不足的单据，直接踢单。
-- 请求上游撤单接口，告知上游集波剔除的单号。
-- 库存不足踢单后进入后续补单逻辑。
-
-当前代码：
-
-- `addShipmentsToInternalWave(...)` 调用 `WaveService#run`。
-- `WaveService#run` 是异步提交队列消息，当前服务不解析同步踢单结果。
-- 相关清空绑定和踢单通知逻辑已有部分转移到 `wms-wave` 模块。
-
-未完成点：
-
-- 需要联调确认库存不足踢单由 `ShipmentAllocationService` 完整处理。
-- 库存不足踢单不记录 `kickOutWave`，只清空 Shopee 集波绑定并预留上游撤单接口。
-- 需要接入真实上游撤单接口。
-
-建议实现口径：
-
-- `WaveRuleMatchService` 保持触发和补单职责。
-- 库存不足踢单、清绑定、上游撤单优先由 `wms-wave` 的踢单流程统一处理。
-- 当前服务只需要能识别踢单后的缺口并由计划任务补单。
-
-### 9. 库存最优分配规则未在当前服务闭环
-
-docx 要求：
-
-- 集波后自动运行波次。
-- 库存最优分配规则：到期日先进先出，其次工作站点位与库存点位半径最小，同半径低层货位优先。
-
-当前代码：
-
-- `WaveRuleMatchService` 只创建内部波次、加入出库单、调用 `WaveService#run`。
-- 当前服务没有库存分配策略参数。
-
-未完成点：
-
-- 需要确认库存分配规则是否已在 `wms-wave` 模块实现。
-- 如果需要当前服务传入工作站点位或策略参数，需要补充调用契约。
-- 需要联调验证实际分配结果符合 docx 优先级。
-
-## P1 订单池过滤和配置口径
-
-### 10. cancel、挂起、异常单据过滤口径待确认
-
-docx 要求：
-
-- 集波抓单只抓正常单据。
-- 上游取消、cancel、挂起、标记异常的单据都不抓。
-
-当前代码：
-
-- 基础 SQL 过滤包含 `leadingSts = 100`。
-- 基础 SQL 过滤包含 `trailingSts = 100`。
-- 基础 SQL 过滤包含 `processType = NORMAL`。
-- 基础 SQL 过滤包含 `waveId = 0`。
-
-未完成点：
-
-- 需要确认 cancel、挂起、异常是否全部映射进现有状态字段。
-- 如果存在独立字段或独立 processType，需要补 SQL 过滤。
-- 需要补最小验证用例覆盖异常单据不入池。
-
-### 11. `WAVE_RULE_FIELD_MATCHING` 生产配置值域仍需锁定
-
-docx 要求：
-
-- 数据字典 `WAVE_RULE_FIELD_MATCHING`。
-- 标识为出库单字段。
-- `value1` 为 `wave_rule` 表字段。
-- `value2` 设置匹配条件，例如包含、等于，配置 `in`、`=`。
-
-当前代码：
-
-- `toRuleFieldMapping(...)` 已按 `identifier = shipment_header 字段`、`value1 = wave_rule 字段` 转换。
-- 已有字段白名单。
-- 已支持 `IN`、`EQ`、`LE`。
-- 操作符有 normalize 逻辑。
-
-未完成点：
-
-- 需要在生产配置文档或初始化 SQL 中固定值域。
-- 需要明确是否允许中文“包含/等于/小于等于”。
-- 需要明确是否只允许 `IN`、`EQ`、`LE`，还是支持更多操作符。
-
-建议配置口径：
-
-- `identifier`：`shipment_header` 字段名。
-- `value1`：`wave_rule` 字段名。
-- `value2`：`IN`、`EQ`、`LE`。
-
-## P2 代码结构和可维护性
-
-### 12. 一波一单方法命名已收敛
-
-当前代码：
-
-- `assignSingleShipmentWaves(...)` 承担通用一波一单分流。
-- 方法内部处理按单拣选、销售出库任务、MTO 任务、RT 等候选。
-- RT 不使用 Shopee 波次号的特殊口径仍保留在流程说明中。
-
-仍需关注点：
-
-- RT 不使用 Shopee 波次号的特殊逻辑单独封装。
-- 推拣货任务仍保留独立方法，因为它使用上游预写 Shopee 波次号。
-
-## 非 WaveRuleMatchService 主责但仍需联动
-
-- `wave_rule` 维护界面需要支持新增、修改规则。
-- 分播墙明细界面需要支持 `waveRule` 多选绑定。
-- 出库单界面按单拣选按钮需要只允许订单池 100 状态单据更新 `pickType = 1/null`。
-- 出库单下发后自动分析 `shipmentCategory1`。
-- 拣货任务头 `shopeeWave`、`waveRule` 字段需要和 `RunWave` 流程回写联调。
-- `shopee_wave` 每日号段申请接口需要落库。
-- WCS/AGV 取消任务和取消回库接口需要联调。
-
-## 建议推进顺序
-
-1. 接入推拣货任务首次集波分流。
-2. 接入真实 ESS 集波校验接口。
-3. 接入 Shopee 波次号段申请接口。
-4. 接入 Flow Pick 封箱、换箱接口和失败回滚。
-5. 与 `wms-wave` 联调库存不足踢单上游撤单和库存最优分配。

SHOPEE_010_出库集波V1.2_待办事项.md

@@ -1,252 +0,0 @@
-# SHOPEE_010 出库集波 V1.2 待办事项
-
-本文按 `C:\Users\zoe\Downloads\SHOPEE_010_出库集波V1.2.docx` 重新整理，状态以当前代码实现为准。
-
-## 一、当前已落地
-
-| 模块 | 已落地内容 | 说明 |
-| --- | --- | --- |
-| 基础表 | `wave_rule`、`shopee_wave` | 已通过 `V3_1_2_3__shopee_outbound_wave_create.sql` 创建基础表，并合入 `groupKey` 字段；`ticketType` 保留用于单据细分。 |
-| 规则实体 | `WaveRule`、`ShopeeWave` | `WaveRule` 已删除 `orderStructure`、`maxSkuPiecesPerOrder`、`mixModeMaxSkuPiecesFilter` 字段。 |
-| 波次字段 | `wave.waveRule` | 内部波次记录当前命中的 wave rule。 |
-| 出库单字段 | `ticketType`、`pickType`、`groupKey`、`cutOffTime`、`purchaseTime`、`orderTime`、`shopeeWave`、`waveRule`、`kickOutWave` | `ticketType` 用于单据细分，`pickType` 用于拣选类型，`groupKey` 用于同波次特征一致性。 |
-| 格口字段 | `wcs_sorting_wall_cell.waveRule`、`currentWaveRule`、`shopeeWaveCode` | 支持格口绑定多个 wave rule，并记录当前执行规则和 Shopee 波次号。 |
-| 任务头字段 | `wcs_work_station_pick_task_header.shopeeWave`、`waveRule` | 字段已补齐，完整回写链路仍需结合任务生成结果验证。 |
-| 系统参数 | `WAVE/low_threshold` | 仅单品单件 wave rule 使用，低于阈值触发补单判断。 |
-| 工作站入口 | `findBestMatchedRuleByWorkStationAndOutboundType` | 支持工作站编码入口和 workstationId 入口。 |
-| 并发控制 | Redis 锁 | 锁粒度为仓库、工作站、出库类型，避免同一工作站并发重复集波。 |
-| 工作站类型隔离 | `hasDifferentActiveShipmentType` | 入口层已校验同工作站不可混做不同出库类型，命中时记录系统处理日志并返回 `MSG_WRM_0014`。 |
-| 规则优先级 | `wavePriority desc` | 高优先级规则不足 `maxShipments` 时仍优先消费该规则下可匹配订单。 |
-| 抓单排序 | `priority`、`cutOffTime`、`purchaseTime`、`orderTime` | 同一规则内按优先级和时间排序，时间越早越优先。 |
-| 波次类型口径 | `wave_rule.waveType`、`shopee_wave.waveType`、`shipment_header.shipmentCategory1` | 三者已确认为同一维度，规则筛单和 Shopee 号段取号均按 `shipmentCategory1` 编码处理。 |
-| 字典匹配 | `WAVE_RULE_FIELD_MATCHING` | 当前口径为 `identifier=shipment_header字段`、`value1=wave_rule字段`、`value2=匹配条件`。 |
-| Shopee 波次绑定 | `bindShipmentShopeeWave` | 上游绑定接口成功后整批写入 `shipment_header.shopeeWave`，失败后整批写入 `kickOutWave`。 |
-| ESS 拒单记录 | `kickOutWave` | ESS 拒绝单据写入 `shipment_header.kickOutWave`，同 Shopee 波次后续抓单过滤。 |
-| 内部波次 | 创建、加单、运行 | 已调用 `WaveService#createInternalWave`、`ShipmentHeaderService#addMultipleToWave`、`WaveService#run` 异步提交运行。 |
-| 验证方式 | 编译、静态检查、真实业务联调 | 不保留新增测试类；一波一单、轮询补单和同工作站出库类型隔离以编译和真实联调验证为准。 |
-| Shopee 绑定接口占位 | `requestShopeeWaveBind` | 预留真实接口调用位置，当前按整批成功/整批失败处理，不做部分成功解析。 |
-| 字段白名单 | `ALLOWED_RULE_FIELDS` / `ALLOWED_SHIPMENT_FIELDS` | shipment_header 白名单 30+ 字段，wave_rule 白名单 16 字段，防止 SQL 拼接注入。 |
-| 格口三层级匹配策略 | sameCurRuleCells / ruleCells / emptyCells | 优先复用同规则已绑定格口，再匹配规则配置格口，最后分配空闲格口。 |
-| 一波一单 | `assignSingleShipmentWaves` | 按单拣选、销售出库任务、MTO 任务、RT 等一波一单候选按一单一个内部波次处理；RT 不使用 Shopee 波次号。 |
-| 一波一单候选 | `findSingleShipmentWaveShipments` | 按单拣选(`pickType=1`)、销售出库任务(`ticketType=1`)、MTO 任务(`ticketType=5`)、RT(`ticketType=6`) 均按一波一单处理。 |
-| 按单拣选过滤 | `appendBatchWaveFilter` | 批量集波在 SQL 层排除 `pickType=1` 单据。 |
-| Flow Pick 换箱换波本地闭环 | `changeFlowPickWave` | 封箱/换箱接口动态调用占位，未接入时本地执行换波回写和格口切换。 |
-| Shopee 波次号回退 | `rollbackClaimedShopeeWaveIfUnused` | 新号段已抢占但未被任何订单引用时恢复为未使用。 |
-| 旧波次自动完成 | `markShopeeWaveCompletedIfNoOpenTask` | 旧波次无未完成任务时标记为完成状态。 |
-| 推拣货任务过滤 | `appendBatchWaveFilter` | `pickType=2` 标识推拣货任务，当前普通批量集波排除该类单据；上游预写入波次的独立分流待接口口径确认。 |
-| 异常订单过滤 | `buildAvailableShipmentSql` | 在基础 SQL 中增加 `cancelTime/holdTime` 过滤，取消/挂起异常单据不进入抓单池。 |
-
-## 二、数据字典配置口径
-
-`WAVE_RULE_FIELD_MATCHING` 是 docx 中“波次规则字段匹配”的落地方式。
-
-| 字段 | 含义 | 例子 |
-| --- | --- | --- |
-| `recordType` | 固定字典类型 | `WAVE_RULE_FIELD_MATCHING` |
-| `warehouseCode` | 仓库编码 | 优先当前仓，未配置时读取 `*` |
-| `identifier` | 出库单字段，即 `shipment_header` 字段 | `userDef1`、`shipmentCategory1`、`priority` |
-| `value1` | 规则字段，即 `wave_rule` 字段 | `channelId`、`shopId`、`urgentFlag` |
-| `value2` | 匹配条件 | `IN`、`=`、`EQ`、`LE`、`<=` |
-
-当前支持的匹配条件：
-
-| `value2` | 含义 |
-| --- | --- |
-| `IN` | `shipment_header.identifier in (wave_rule.value1 多选值)` |
-| `=` / `EQ` / `EQUAL` / `EQUALS` | `shipment_header.identifier = wave_rule.value1` |
-| `LE` / `<=` / `LESS_OR_EQUAL` | `shipment_header.identifier <= wave_rule.value1` |
-
-当前白名单：
-
-| 类型 | 允许字段 |
-| --- | --- |
-| `shipment_header` 字段 | `shipmentType`、`ticketType`、`pickType`、`sourcePlatform`、`sourceErp`、`erpOrderType`、`route`、`carrierCode`、`shipmentSubType`、`shipmentCategory1-8`、`shipToCountry`、`shipToState`、`shipToCity`、`shipToDistrict`、`shipToTown`、`shipToCountryCode`、`shipToStateCode`、`shipToCityCode`、`shipToDistrictCode`、`shipToTownCode`、`hostCompanyCode`、`storeCode`、`shipObjType`、`requestedDeliveryType`、`priority`、`userDef1-8` |
-| `wave_rule` 字段 | `channelId`、`fulfillmentChainId`、`orderSize`、`skuSizeType`、`categoryLevel1Id`、`shopGroup`、`shopId`、`urgentFlag`、`outerPackaging`、`outerPackagingId`、`deliveryRegion`、`fragile`、`liquid`、`highValue`、`battery`、`danger` |
-
-配置示例：
-
-| warehouseCode | recordType | identifier | value1 | value2 | 说明 |
-| --- | --- | --- | --- | --- | --- |
-| `*` | `WAVE_RULE_FIELD_MATCHING` | `userDef1` | `channelId` | `IN` | 出库单 `userDef1` 匹配规则 `channelId` 多选值。 |
-| `*` | `WAVE_RULE_FIELD_MATCHING` | `priority` | `urgentFlag` | `LE` | 出库单优先级小于等于规则 `urgentFlag`。 |
-| `WH01` | `WAVE_RULE_FIELD_MATCHING` | `userDef7` | `shopId` | `=` | 仓库级配置优先于 `*`。 |
-
-## 三、待实现功能
-
-### 3.1 上游接口
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 待实现 | Shopee WMS 初始化 `wave_rule` 接口 | docx 要求上游初始化波次规则，WES 支持维护和新增。 |
-| 待实现 | Shopee 波次号段申请接口 | `shopee_wave` 数据应由上游下发保存，每天号段用完后继续申请。 |
-| 待确认 | ESS 合波校验正式契约 | 当前有动态调用和常见响应解析，需按真实请求/响应结构收敛。 |
-| 待实现 | 库存不足踢单上游撤单接口 | `WaveService#run` 为异步提交，库存不足踢单由 `wms-wave` 回池链路清空 Shopee 绑定且不记录 `kickOutWave`；仍需对接上游撤单接口。 |
-| 占位待联调 | Flow Pick 换箱接口 | `WaveRuleMatchService` 中 `requestFlowPickSealBox/requestFlowPickChangeBox` 已动态调用占位；本地换波闭环（字段回写/格口切换）已实现，待真实接口接入和联调。 |
-| 待确认 | 推拣货任务与推出库单区分标识 | docx 要求两类单据入口分流，上游需提供标识。 |
-
-### 3.2 Wave Rule 字段与页面能力
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 待实现 | Dropdown 字段支持 All、多选、模糊搜索 | 涉及 `channelId`、`fulfillmentChainId`、`orderSize`、`shopGroup`、`shopId` 等字段。 |
-| 待实现 | Input 字段支持输入多个值 | 如 `shop_id` 文本输入。 |
-| 待实现 | `Include / Exclude / Only` 语义 | docx 中 `SKU Size`、`L1 Category` 等 SKU 维度字段需要该语义；当前 `WAVE_RULE_FIELD_MATCHING` 只支持 IN/EQ/LE，无 Include/Exclude/Only。 |
-| 待实现 | `Urgent Flag` 区间输入(BETWEEN) | docx 示例为 `3-99`，当前只有 `LE`（小于等于）操作符，需新增 BETWEEN 匹配条件支持。 |
-| 待实现 | `Max SKU Pieces Per Order` | 不恢复为 `WaveRule` 字段，后续应基于 `shipment_detail` 聚合判断。 |
-| 待实现 | `Mix Mode Max SKU Pieces Filter` | 仅 MSAQ 规则使用，不恢复为 `WaveRule` 字段，后续基于明细聚合判断。 |
-| 已落地 | `wave_rule.waveType` 与 `shopee_wave.waveType` 口径 | 已确认同一维度，取号不再使用外层出库单类型，改为按已筛出单据的 `shipmentCategory1` 获取 Shopee 波次号段。 |
-
-### 3.3 基础数据初始化
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 待实现 | Channel 初始化 | 下拉展示 ID + Name，如 `(100004)SPX`。 |
-| 待实现 | Fulfillment Chain 初始化 | 下拉展示 ID + Name。 |
-| 待实现 | L1 Category 初始化 | 变动枚举，同步自 Shopee WMS。 |
-| 待实现 | Shop Group 初始化 | 变动枚举，同步自 Shopee WMS。 |
-| 待实现 | Shop 初始化 | 支持下拉和文本输入。 |
-| 待实现 | Outer Consumable ID 初始化 | 下拉展示外包材 ID + Name。 |
-| 待实现 | 出库单接口字段落库 | Shopee 匹配字段需按 `WAVE_RULE_FIELD_MATCHING.identifier` 落到现有字段或 `userDef1-8`。 |
-
-### 3.4 订单结构分析
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 已落地 | `shipmentCategory1` 自动回填 | 用于 wave rule 匹单。 |
-| 待验证 | 真实订单样例验证 | 需用 Shopee 样例确认 `SSSQ/SSAQ/MSAQ/MSSQ` 编码。 |
-| 待实现（P1） | 异常边界处理 | 当前只通过 `processType='NORMAL'` 过滤；取消、挂起、异常、短配等具体状态需显式排除，避免非正常单据误入订单池。 |
-
-docx 结构编码：
-
-| 结构 | 编码 | 含义 |
-| --- | --- | --- |
-| `SSSQ` | `1` | 单 SKU 单件。 |
-| `Same SKU Same Qty` | `2` | 与 SSSQ 同逻辑口径。 |
-| `MSAQ` | `3` | 多 SKU 多件。 |
-| `SSAQ` | `4` | 单 SKU 多件。 |
-| `MSSQ` | `5` | 多品单件。 |
-
-### 3.5 工作站集波
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 已落地 | 工作站 + 出库类型入口 | 当前可按工作站匹配规则和格口。 |
-| 已落地 | Redis 锁 | 防止同一工作站同类型重复集波。 |
-| 已落地 | 格口多规则绑定 | `wcs_sorting_wall_cell.waveRule` 多值逗号分隔。 |
-| 已落地 | 按 `wavePriority` 高到低抓单 | 高优先级规则不足 `maxShipments` 仍先消费。 |
-| 已落地 | 同规则内订单优先级排序 | `priority desc`，时间越早越优先。 |
-| 待实现 | 用户权限和出库类型绑定 | 登录工作站只能选择当前用户有权限的出库类型。 |
-| 已落地 / 待前端联调 | 同工作站不混做不同订单类型 | 后端入口已通过 `USED` 格口关联 Shopee 波次反查当前作业出库类型，发现其它类型返回 `MSG_WRM_0014`；前端仍需补选择约束和提示。 |
-| 待确认 | 未绑定 waveRule 的格口是否默认所有规则 | docx 有该口径；当前代码 `matchEmptyCells` 已处理空规则格口作为兜底，但业务上是否启用需确认。 |
-
-### 3.6 合波校验与 Shopee 波次绑定
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 已落地 | 抢占未使用 Shopee 波次号 | 按 `status=100` 更新为 `200`，避免并发重复取号。 |
-| 已落地 | 先写 `shipment_header.shopeeWave` 再加入内部波次 | 符合前置要求。 |
-| 已落地 | ESS 拒单写 `kickOutWave` | 支持多个 wave 号逗号分隔。 |
-| 已落地 | 同 Shopee 波次补单过滤 `kickOutWave` | 后续该波次抓单过滤被拒订单。 |
-| 待验证 | ESS 真实响应结构 | 当前支持常见 ID、单号、Map 结构，需联调验证。 |
-| 已落地 | 合波校验不通过后持续补单重试策略 | 格口内候选池循环和计划任务轮询补单均复用 `kickOutWave` 过滤。 |
-
-### 3.7 内部波次与波次运行
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 已落地 | 创建内部波次 | 当前通过 `WaveService#createInternalWave` 创建。 |
-| 已落地 | 批量加入内部波次 | 当前调用 `ShipmentHeaderService#addMultipleToWave`。 |
-| 已落地 | 加入后直接运行 | 当前调用 `WaveService#run` 异步提交 `wms.wave` 队列消息。 |
-| 待实现 | 库存最优分配规则对齐 | docx 要求先到期先出/先进先出，其次工作站点位与库存点位半径最小，同半径低层优先。 |
-| 已明确 | 波次运行结果不在当前服务同步解析 | `WaveService#run` 是异步提交，`WaveRuleMatchService` 只判断提交是否成功。 |
-| 待实现（P0） | 库存不足踢单通知上游撤单 | 库存不足回池不记录 `kickOutWave`，需在 `wms-wave` 回池链路对接上游撤单接口。 |
-| 待验证 | 任务头字段完整回写 | `wcs_work_station_pick_task_header.shopeeWave`、`waveRule` 需结合任务生成结果验证。 |
-
-### 3.8 Flow Pick 单品单件动态加单与换箱换波
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 已落地 | `low_threshold` 基础判断 | 仅单品单件规则使用。 |
-| 已落地 | 首次集波内补缺口 | 当前在首次集波入口中调用 `fillShortageCells`，对已绑定 Shopee 波次的空闲格口按 `low_threshold/maxShipments` 补满。 |
-| 已落地 | 槽口放满换箱触发 | 当前以单品单件 `wave_rule.maxShipments` 作为满槽阈值；达到后进入 Flow Pick 换箱换波流程。 |
-| 已落地 | 放满后剩余订单换波 | 查询当前工作站、旧 Shopee 波次、当前 `waveRule` 下未完成拣货任务订单，并重新取同单据类型的 Shopee 波次号段。 |
-| 已落地 | Flow pick 换箱接口占位 | `WaveRuleMatchService` 通过可选 `essFlowPickService.sealBox/changeBoxWave` 承接真实接口；接口未接入时记录系统处理日志并执行本地换波闭环。 |
-| 已落地 | 换波成功后字段回写 | 批量更新剩余订单任务头和出库单头 `shopeeWave`，新 `shopee_wave.status=200`，格口切换到新 `shopeeWaveCode/currentWaveRule`。 |
-| 待联调（P1） | 换波失败回滚 | 当前 `handleFlowPickChangeWaveFailure` 只记录系统处理日志并回退未使用的新 Shopee 波次状态；恢复订单池、取消任务下发、通知 AGV 取消回库待真实接口接入。 |
-
-### 3.9 计划任务轮询补单
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 待实现 | 计划任务入口 | 当前已删除 `pollReplenishment/pollReplenishmentOnce`；如需后台轮询补单，需按最终调度策略重新接入计划任务入口。 |
-| 已落地 | 首次集波内扫描可补格口 | 当前 `fillShortageCells` 通过 `findShortageCells` 查询空闲、已绑定 Shopee 波次且 `currentWaveRule` 匹配的格口。 |
-| 已落地 | 单品单件补单 | `calcCellNeedQty` 支持未拣货数量低于 `low_threshold` 时按 `wave_rule.maxShipments` 抓单。 |
-| 已落地 | 非单品单件补单 | `calcCellNeedQty` 支持统计当前 Shopee 波次已绑定订单数并按 `maxShipments` 计算缺口。 |
-| 已落地 | 补单后 ESS 校验 | `fillShortageCells` 复用 `assignToCell` 和 `bindShipmentShopeeWave`。 |
-| 部分落地 | 补单失败过滤 | 被 ESS 拒绝的单继续写 `kickOutWave`，同波次后续抓单过滤；库存不足踢单不写 `kickOutWave`。 |
-| 已落地 | 补单成功自动加内部波次并运行 | 单格口补单成功后创建内部波次，调用 `addMultipleToWave` 和 `WaveService#run` 异步提交运行。 |
-
-### 3.10 推拣货任务与推出库单分流
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 待实现 | 推拣货任务分流（`pickType=2`） | 当前普通批量集波已通过 `appendBatchWaveFilter` 排除 `pickType=2`，独立分流入口待按上游推单口径恢复。 |
-| 待实现 | 推拣货任务一单一波一槽口 | 需在独立分流入口中实现每单占一个空闲格口、创建独立内部波次且不走补单逻辑。 |
-| 已落地 | 推出库单继续标准集波 | 不受影响，推拣货任务分流后剩余订单继续标准集波链路。 |
-| 已落地 | 异常订单过滤增强 | `buildAvailableShipmentSql` 增加 `cancelTime/holdTime` 过滤，取消/挂起单据不进入抓单池。 |
-| 待联调 | 上游推单接口对接 | `pickType=2` + `shopeeWave` 预写入需上游在推单时写入；WES 侧当前仅完成普通批量过滤，独立分流待恢复。 |
-
-### 3.11 按单拣选与单据类型补充
-
-| 状态 | 待办 | 说明 |
-| --- | --- | --- |
-| 已落地 | 出库单界面新增“更新按单拣选”按钮 | 支持多选出库单，点击后弹窗选择“是/否”。 |
-| 已落地 | 限制只允许更新订单池状态单 | 仅 `shipment_header` 处于订单池 `100` 状态的单据可更新。 |
-| 已落地 | 回写 `shipment_header.pickType` | 选择“是”时更新为 `1`，选择“否”时清空。 |
-| 已落地 | 集波抓单过滤按单拣选单据 | 工作站普通 Shopee 集波已过滤 `pickType=1` 的单据。 |
-| 已落地 | 按单拣选一波一单 | `pickType=1` 的单据当前进入 `assignSingleShipmentWaves`，按一单一波一格口处理。 |
-| 部分落地 | 单据类型细分处理 | `shipmentType` 包含 `XSCK`、`MTO`、`RTS`、`RT`；当前已在 Shopee 集波入口排除 `RT`。 |
-| 部分落地 | `ticketType` 细分处理 | 字段和页面展示已补齐；`ticketType` 为数字枚举，当前代码已处理 `1=销售出库任务`、`5=MTO任务`、`6=RT` 分流一波一单。 |
-| 已落地 | 一波一单规则 | 销售出库任务(`XSCK+ticketType=1`)、MTO任务(`ticketType=5`)、RT(`ticketType=6`)、按单拣选单据均按 1 单创建 1 个内部波次；销售出库任务/MTO任务仍走 Shopee 波次校验，RT 不取 Shopee 波次。 |
-| 部分落地 | RT 库内流程 | 当前 RT 已按一单一个内部波次运行且不取 Shopee 波次；实际外部库内接口如需对接仍待补充。 |
-
-## 四、验证待办
-
-| 状态 | 验证项 | 说明 |
-| --- | --- | --- |
-| 未执行 | `:wms-wave:compileGroovy` | 本轮仅同步文档，按要求不额外执行编译验证。 |
-| 不适用 | WaveRuleMatchService 新增测试类 | 已按要求删除新增测试类，后续不再新增或修改测试类。 |
-| 待验证 | 真实规则匹配 | 用真实 `wave_rule` 和出库单字段验证 `IN`、`=`、`LE`。 |
-| 待验证 | Shopee 波次绑定接口 | 用真实接口验证 `requestShopeeWaveBind` 成功/失败口径。 |
-| 待验证 | `kickOutWave` 过滤 | 验证同 Shopee 波次二次补单不再抓被拒单。 |
-| 待验证 | 内部波次运行后字段回写 | 验证出库单、任务头、wave、shopee_wave 状态一致。 |
-| 待验证 | 按单拣选分流 | 验证 `pickType=1` 单据不会被普通集波抓取，且可通过 `assignSingleShipmentWaves` 一波一单处理。 |
-| 待验证 | RT 类型分流 | 验证 `RT` 不取 Shopee 波次号、不调用出库上游接口，改走库内流程。 |
-| 待执行 | Flow Pick 换箱换波完整链路 | 验证 `changeFlowPickWave` 满槽→封箱→取号→回写→旧波次完成的本地闭环。 |
-| 待执行 | 库存不足踢单处理验证 | 验证 `wms-wave` 回池时清空 `shopeeWave/waveRule`、不写 `kickOutWave`，并在接口接入后通知上游撤单。 |
-| 待执行 | `rollbackClaimedShopeeWaveIfUnused` 校验 | 验证新 Shopee 波次号段在绑定失败后正确恢复为未使用。 |
-| 待验证 | `matchEmptyCells` 兜底逻辑 | 若业务启用未绑定 waveRule 格口默认所有规则，需验证兜底匹配正确性。 |
-| 待执行 | 同工作站不混做不同订单类型验证 | 验证已占用格口存在其它 `shipmentType` 时入口返回错误并写系统处理日志，同类型或空工作站可继续集波。 |
-
-## 五、建议优先级（基于 docx + 代码交叉分析）
-
-| 优先级 | 事项 | 代码现状 |
-| --- | --- | --- |
-| **P0 🔥** | 补齐库存不足踢单上游撤单 | `WaveService#run` 异步提交，不在 `WaveRuleMatchService` 解析结果；需在 `wms-wave` 回池链路接入上游撤单接口。 |
-| **P0 🔥** | Shopee 波次绑定接口正式契约对接 & 联调 | `requestShopeeWaveBind` 预留真实接口调用位置，需真实 ESS/WMS 联调收敛。 |
-| **P1** | Flow Pick 换箱接口正式对接 + 失败回滚 | `requestFlowPickSealBox/requestFlowPickChangeBox` 动态调用占位；`handleFlowPickChangeWaveFailure` 仅为日志，未实现 AGV 回库/订单池恢复。 |
-| **P1** | 推拣货任务分流 + 上游推单接口联调 | 当前普通批量已排除 `pickType=2`，独立分流入口和上游推单写入 `pickType=2` + `shopeeWave` 待联调恢复。 |
-| **P1** | 用户权限+出库类型绑定 | 工作站安全控制，当前代码无用户权限校验逻辑。 |
-| **P1** | 异常订单过滤（取消/挂起/异常/短配） | 当前只靠 `processType='NORMAL'` 过滤，精度不够。 |
-| **P1** | 按单拣选一波一单联调 | `pickType=1` 当前走 `assignSingleShipmentWaves`，仍需真实数据验证一单一波一格口。 |
-| **P1** | Shopee 波次号段申请接口 | 当前只从已落库表取号，无上游申请逻辑。 |
-| **P1** | Shopee WMS 初始化 wave_rule 接口 | 上游初始化波次规则，WES 支持维护新增。 |
-| **P2** | Urgent Flag 区间输入(BETWEEN) | 当前只有 LE 操作符，需新增 BETWEEN 匹配条件。 |
-| **P2** | Include / Exclude / Only 语义 | SKU 维度字段需要该语义，当前字典只支持 IN/EQ/LE。 |
-| **P2** | Max SKU Pieces / Mix Mode Filter | 不恢复为 WaveRule 字段，需基于 `shipment_detail` 聚合判断。 |
-| **P2** | 库存最优分配规则（到期日/半径/低层优先） | 分配算法增强，docx 明确要求。 |
-| **P2** | Flow Pick 失败回滚完善（AGV 取消回库/订单池恢复） | 当前仅日志占位。 |
-| **P2** | 计划任务轮询补单按真实波次状态和连续空轮条件细化 | 调度入口已落地，后续按真实波次状态、连续空轮条件和接口响应做细化。 |
-| **P3** | 基础数据同步接口（Channel/Fulfillment Chain/Shop 等） | 管理页面能力，非核心链路。 |
-| **P3** | Dropdown 多选/模糊搜索、Input 多值 | 前端组件能力。 |
-| **P3** | ticketType 值 2/4/5/6/7 含义补齐 | 当前明确处理 1、5、6，其他值域说明仍需补齐。 |

SHOPEE_010_出库集波V1.2_改动计划.md

@@ -1,710 +0,0 @@
-# SHOPEE_010 出库集波 V1.2 改动计划
-
-## 一、文档目的
-
-本文档用于把《SHOPEE_010_出库集波V1.2.docx》中的需求先整理成可执行的改动计划，再按代码模块落地。
-
-目标是先明确：
-
-- 要改什么
-- 改到哪些模块
-- 先后顺序怎么排
-- 每一步怎么验证
-
-## 二、需求背景
-
-本需求围绕“出库集波”展开，核心是把 Shopee WES 的波次规则、波次号段、订单筛选、工作站集波、补单、踢单、换箱换波和执行联动串成一套闭环流程。
-
-从原文看，主要涉及以下能力：
-
-- 新增和维护 wave rule
-- 新增波次号段表 `shopee_wave`
-- 按订单属性自动分析订单类型
-- 工作站按订单类型和 wave rule 集波
-- 按优先级抓单、补单、踢单
-- 单品单件波次的动态加单和换箱换波
-- 绑定分拨墙槽口和 wave rule
-- 与上游接口做波次校验和号段申请
-
-## 三、需求拆分
-
-### 3.1 基础数据与规则配置
-
-需要补齐 wave rule 的规则配置能力，包括：
-
-- 新增 `wave_rule` 表
-- 支持波次规则字段配置
-- 支持初始化和后续新增、修改 wave rule
-- 支持优先级 `wavePriority`
-- 支持规则级最大订单数 `wave_rule.maxShipments`
-- 支持规则字段和出库单字段匹配
-
-### 3.2 波次号段管理
-
-需要新增波次号段表 `shopee_wave`，用于：
-
-- 按天向上游申请号段
-- 用完后继续请求上游
-- 记录号段状态
-- 记录波次类型、编号和使用状态
-
-### 3.3 订单分析与规则匹配
-
-需要在出库单下发后自动分析订单：
-
-- 单 SKU 单件 `SSSQ`，也就是 `Same SKU Same Qty`
-- 单 SKU 多件 `SSAQ`
-- 多 SKU 多件 `MSAQ`
-- 多品单件 `MSSQ`
-
-分析结果要写入出库单头部字段 `shipmentCategory1`，用于 wave rule 匹单。
-
-当前代码侧已落地的口径是：
-
-- 出库单明细发生变化后，自动重新统计并回填 `shipmentCategory1`
-- `WaveRule.orderStructure` 已删除，波次规则当前按 `wave_rule.waveType` 与 `shipment_header.shipmentCategory1` 编码做基础匹配
-- 现阶段按代码内已有的四类结构值落地，且 `SSSQ` 与 `Same SKU Same Qty` 视为同一逻辑，保持和既有波次类型一致
-
-### 3.4 工作站集波
-
-工作站需要支持：
-
-- 按用户权限过滤可选订单类型
-- 按订单类型先命中 wave rule，再按 rule 条件筛单集波
-- 按工作站槽口绑定的 wave rule 集波
-- 若槽口未绑定 wave rule，则按全量规则优先级匹单
-
-### 3.4.1 按用户权限过滤可选订单类型
-
-这里的“可选订单类型”指的是前端/接口层可让用户选择的 `shipmentType`，不是波次执行后的结果集。权限控制要尽量前置，避免把未授权的订单类型传进后续波次匹配流程。
-
-当前设计口径如下：
-
-- 参考 `preference_user_right` 的关系模型，单独新增一张波次订单类型权限表来维护数据，不再复用旧表。
-- 建议新表名为 `shipment_type_user_right`，按“订单类型 + 用户”维度保存授权关系，字段语义可以参考 `preference_user_right`，但表名和业务语义要更专用，避免和首选项权限混淆。
-- 新表字段建议为 `shipmentTypeId`、`userCode`、`created`、`createdBy`，其中 `shipmentTypeId` 对应 `config_detail.id`，`userCode` 对应当前用户，唯一约束建议按 `shipmentTypeId + userCode` 控制。
-- 新表中的订单类型值对应出库类型字典主键，来源统一按系统内 `SHIPMENT_TYPE` 配置字典取值，也就是和 `shipment_header.shipmentType` 对应的那套出库类型字典。
-- `userCode` 对应当前登录用户，过滤结果只展示该用户已授权的订单类型。
-- 用户没有对应授权记录时，默认不展示该订单类型，不做“全量兜底放开”。
-- 前端下拉或多选控件先按权限过滤可选项，再把过滤后的 `shipmentType` 传给波次匹配接口。
-- 后端进入 `WaveRuleMatchService` 之前应当已经完成权限过滤；该服务只负责按已选 `shipmentType` 做规则和格口候选匹配，不再重复做用户权限判断。
-- 权限维护侧可以参考现有“首选项权限”页面交互，但底层读写的是新建的波次订单类型权限表。
-
-建议的接口链路如下：
-
-1. 前端进入集波或波次规则配置页面时，先获取当前用户可见的出库类型列表。
-2. 服务端根据当前用户查询 `shipment_type_user_right` 表，取出已授权的订单类型主键。
-3. 将命中的订单类型主键映射回 `SHIPMENT_TYPE` 字典，返回可选 `shipmentType` 列表。
-4. 用户只能在这个列表里选择订单类型，然后再进入后续波次规则匹配。
-
-当前代码状态说明：
-
-- `WaveRuleMatchService` 已拆分为 `workstationId + 出库类型` 的主入口，旧的工作台编码入口保留兼容。
-- 该入口当前已按规则逐条查单并返回格口分配结果，后续仍需补齐更完整的字段匹配和执行衔接。
-
-### 3.5 抓单、补单、踢单
-
-需要实现三类执行动作：
-
-- 抓单：按规则和优先级从订单池取单
-- 补单：在波次未满时补齐订单
-- 踢单：库存不足或上游校验失败时剔除订单
-- 轮询补单：在波次创建后按固定间隔回查订单池，持续补入仍然满足规则且未满载的订单，直到达到补单上限或等待窗口结束
-
-### 3.6 单品单件特殊流程
-
-单品单件 `SSSQ` 场景需要额外支持：
-
-- 动态加单
-- 槽口封箱后换箱换波
-- 补单和踢单解耦
-- 尽量保持槽口满载
-
-### 3.7 上游接口联动
-
-需要补齐与上游的接口逻辑，包括：
-
-- 申请波次号段
-- 校验波次是否允许合波
-- 踢单时回调撤单
-- 初始化 wave rule
-
-### 3.8 分拨墙与槽口绑定
-
-需要扩展分拨墙格口与 wave rule 的绑定能力：
-
-- `wcs_sorting_wall_cell` 增加 `waveRule`
-- 支持多规则绑定，多个规则用逗号分隔
-- 支持界面多选下拉更新，取值来自 `wave_rule` 表
-
-### 3.9 号段申请与上游合波校验
-
-集波完成后，系统需要从 `shopee_wave` 表里取一个与当前出库单类型一致的 `waveType` 号段，向上游请求校验这批单据是否允许集在一波中。
-
-当前需求口径如下：
-
-- 从 `shopee_wave` 中选择 `waveType` 与出库单类型一致的波次号段。
-- 以该波次号段作为本次集波和上游校验的唯一波次标识。
-- 调用上游接口，确认当前候选单是否允许合波。
-- 如果上游返回不允许集在一起的订单，则该批单据不能直接成波。
-- 若当前批次单量少于一波最大订单数，不在这里强行补单重试，而是交给后面的轮询补单逻辑处理。
-- 补单逻辑要和各流程解耦，推荐在工作站开始作业后再补单，避免把上游合波校验和补单耦合到一起。
-
-当前代码状态说明：
-
-- 上游合波校验接口还需要后续梳理接口契约后再落实现。
-- 这一节先把业务口径写清楚，补单动作统一放到后文轮询补单逻辑中维护。
-
-### 3.10 格口分配逻辑
-
-这里的“格口分配”不是给格口动态生成一条规则，而是把当前工作站下可执行的格口和对应 wave rule 组装成可直接消费的分配结果，供后续流程继续决策。
-
-当前理解和代码侧约束如下：
-
-- 先按工作站查询可用分播墙，再按分播墙查询格口。
-- 只保留启用状态且使用状态为 `IDLE` 的格口。
-- `waveRule` 是格口自身的绑定约束，表示该格口能接收的规则范围，不是运行时临时分配出来的结果。
-- `currentWaveRule` 是格口当前正在使用的规则字段，用来记录本次实际分配到的 `waveRule`，便于补单和执行衔接。
-- `shopeeWaveCode` 记录的是格口和 Shopee 波次号段的关联，不承担规则分配职责。
-- 这里不反查格口当前绑定的出库单，也不在本层做出库单候选筛选。
-- 当前代码会先按仓库和出库类型查启用波次规则，再按规则逐条查单、查格口，形成“格口 + 命中规则 + 可用出库单”的分配结果。
-- 如果格口配置了多个 `waveRule`，按逗号、中文逗号或分号拆分后做匹配，命中的规则优先回填到返回结果里。
-
-当前代码状态说明：
-
-- `WaveRuleMatchService` 已实现分配入口：
-  - `findBestMatchedRuleByWorkStationAndOutboundType(String warehouseCode, String workStation, String shipmentType)`
-  - `findBestMatchedRuleByWorkStationAndOutboundType(Long workstationId, String shipmentType)`
-- 工作站控制器已暴露同名接口，可直接通过 `wms/automation/wcsWorkStation/findBestMatchedRuleByWorkStationAndOutboundType` 调用该服务。
-- 服务内部先查启用中的波次规则，再按规则逐条查可用出库单和可用格口，最终返回 `ResponseMessage` 包装的分配结果。
-- `assignCellNumbers` 已改成单规则处理，当前会先查出库单，再查格口，并按格口顺序回填命中的订单候选。
-- 返回结果中每个格口会带上 `matchedRule`、`availableShipments`，并保留 `sortingWallId`、`sortingWallCode`、`workStationId`、`col`、`tier`、`shopeeWaveCode`、`currentWaveRule` 等基础字段。
-- 当前已经接入基础出库单查询、排序和 `WAVE_RULE_FIELD_MATCHING` 字典基础匹配；高级字段语义仍待补齐。
-
-### 3.11 `maxShipments` 逻辑
-
-`maxShipments` 需要拆成两层理解，不能混成一个字段口径：
-
-- `wave_master.maxShipments`：波次内部表字段，只用于波次创建阶段的截单控制，不参与本节可用出库单查找逻辑。
-  - 波次创建时，会先按 `shipmentFilterCode` 对出库单做候选筛选。
-  - 然后再按 `maxShipments` 截断候选单量。
-  - 如果 `maxShipments > 0`，则按该值限制单次创建波次时可取出的最大出库单数量。
-  - 如果 `maxShipments <= 0`，当前实现默认最多取 `100` 单。
-  - 候选单量最终仍需满足 `minShipments`，否则本次不创建波次。
-- `wave_rule.maxShipments`：规则级单次抓单上限。
-  - 当前已在规则表和配置页中保留。
-  - 规则匹配链路已开始接入，当前查单逻辑会消费该字段作为单次抓单上限。
-  - 后续如需调整上限口径，只修改规则层，不要和其他内部表字段混用。
-
-当前代码状态说明：
-
-- 波次主流程在创建阶段会读取 `wave_master.maxShipments`，但这里的可用出库单查找逻辑不直接依赖它。
-- `wave_rule.maxShipments` 当前已在 `findAvailableShipments` 中消费，作为当前规则的单次抓单上限。
-- 文档中出现 `maxShipments` 时，必须注明它属于哪一层，避免歧义。
-
-### 3.12 可用出库单查找逻辑
-
-格口候选和出库单候选是两条独立链路，不能把“查格口”当成“查单”。
-
-当前需要补齐的可用出库单查找逻辑如下：
-
-- 先从出库单池里查候选单，再判断是否满足当前波次规则。
-- 候选单要同时满足仓库、出库类型、订单结构、状态、锁定状态和规则字段匹配条件。
-- 当前代码已接入仓库、出库类型、`shipmentCategory1`、在池状态、锁定状态、`wave_rule.maxShipments` 和 `WAVE_RULE_FIELD_MATCHING` 字典字段匹配。
-- 规则字段匹配重点包括：
-  - `channel_id`
-  - `fulfillment_chain_id`
-  - `order_structure`
-  - `order_size` / `max_order_size`
-  - `sku_size_type`
-  - `category_level_1_id`
-  - `shop_group`
-  - `shop_id`
-  - `urgent_flag`
-  - `outer_packaging`
-  - `delivery_region`
-  - `is_fragile`
-  - `is_liquid`
-  - `is_high_value`
-  - `with_battery`
-  - `is_danger`
-  - `max SKU Pieces Per Order`
-  - `Mix Mode Max SKU Pieces Filter`
-- 多值字段默认支持按“包含”筛选；需要排除或仅保留某些值时，按字段配置约定转换成 `include` / `exclude` / `only` 口径。
-- `order_structure` 仍以 `shipmentCategory1` 为实际落字段做匹配，`SSSQ` 与 `Same SKU Same Qty` 视为同一逻辑。
-- `wave_master` 是内部表，不参与这里的可用出库单查找逻辑。
-- 规则层的 `wave_rule.maxShipments` 已在 `WaveRuleMatchService#findAvailableShipments` 中作为当前规则的单次抓单上限使用。
-
-当前代码状态说明：
-
-- 这条“可用出库单查找”逻辑已经开始落到 `WaveRuleMatchService#findAvailableShipments`。
-- `WaveRuleMatchService` 现在已同时负责规则遍历、订单池基础查单和格口分配，但还没有覆盖所有字段匹配条件。
-- 后续如果要进一步细化为“规则命中后再查单”，应继续在当前服务或独立查询服务里补齐，不要和格口状态、任务回写混写。
-
-### 3.13 出库单分配后的处理
-
-出库单分配不是最终结果，而是进入波次执行前的准备阶段。
-
-当前需要把分配后的动作单独拆开维护，避免只做“查到单”却没有后续状态闭环。
-
-分配成功后，建议按以下顺序处理：
-
-- 固化波次和规则关联，保证本次分配对应的 `wave_rule`、波次号段和业务单据能串起来。
-- 回写出库单的波次关联状态，例如 `shopeeWave`、`kickOutWave` 等字段，防止同一单再次被其他波次重复占用。
-- 回写工作站任务头的波次信息，例如 `shopeeWave`、`waveRule`，让执行层知道当前任务属于哪一条波次链路。
-- 同步分拨墙/格口占用状态，并把当前正在使用的规则写入 `wcs_sorting_wall_cell.currentWaveRule`，确保补单和执行层能识别当前槽口实际使用的规则。
-- 触发后续执行动作，包括拣货、集波、补单和必要的执行校验。
-
-如果分配后发现库存不足、规则冲突、上游校验失败或并发占用失败，则需要进入踢单或回流流程：
-
-- 已分配单据从当前波次中移除。
-- 恢复单据的可分配状态，重新回到候选池。
-- 记录失败原因，供后续重试或人工排查。
-
-当前代码状态说明：
-
-- 当前文档层面先把“分配后动作”拆出来，后续再按模块补实现。
-- 分配后的状态回写和执行联动，不应混在格口候选或出库单查找逻辑里。
-
-### 3.14 集波后自动运行波次
-
-集波完成后，系统需要自动进入波次运行阶段，而不是停留在“已分配未执行”的中间状态。
-
-当前流程建议按以下顺序执行：
-
-- 先基于 `wave_rule` 对出库单十几个规则属性做完全匹配，确认当前波次可运行。
-- 再执行库存最优分配逻辑：
-  - 优先先到期先出，保证先进先出。
-  - 其次按工作站点位与库存点位半径最小的库存优先。
-  - 同半径内，低层货位优先。
-- 运行成功后，回写波次和任务关联字段：
-  - 将 `shopee_wave` 的波次号段绑定到拣货任务头 `shopeeWave` 字段。
-  - 同时绑定到出库单头 `shopeeWave` 字段。
-  - 将当前 `waveRule` 记录到 `wave` 表的 `waveRule` 字段。
-  - 同步记录到拣货任务头 `waveRule` 字段，供拣货执行衔接使用。
-  - 将 `shopee_wave.status` 更新为 `200`，表示使用中。
-- 如果运行过程中发现库存不足的单据，直接踢单：
-  - 调用上游撤单接口，通知上游本次集波剔除的单号。
-  - 该类库存不足踢单也要进入后续轮询补单逻辑，不直接结束整条波次链路。
-- 运行成功后，波次进入执行态，后续继续衔接拣货、补单、踢单和执行校验。
-
-当前代码状态说明：
-
-- `WaveRuleMatchService#addShipmentsToInternalWave` 当前已在批量加入内部波次后调用 `WaveService#run`。
-- `WaveService#run` 是异步提交队列消息，`WaveRuleMatchService` 不解析同步踢单结果。
-- 库存不足踢单由 `wms-wave` 回池链路处理，回池时清空 `shipment_header.shopeeWave/waveRule`，不记录 `kickOutWave`。
-- 库存不足踢单后的上游撤单接口仍待接入，补单由后续轮询按格口缺口继续处理。
-
-### 3.15 上墙优先级与字段匹配
-
-波次上墙和抓单时，优先级和字段匹配需要按照统一口径执行，不能把“先匹规则”写成“先按数量抓单”。
-
-当前需求口径如下：
-
-- 先看 `wave_rule` 表的优先级字段 `wavePriority`，数字越大优先级越高。
-- 按 `wavePriority` 从高到低排序，优先抓取满足 `wave_rule` 的订单。
-- 抓单时同时参考 `wave_rule.maxShipments`，按规则设定的最大订单数进行截断。
-- 如果高优先级 `wave_rule` 的订单池暂时不足 `maxShipments`，也要优先匹配该高优先级规则下能拿到的单，不因为数量不满就降级到低优先级规则。
-- 规则命中的订单池内部，还要按订单下发优先级继续排序：
-  - 先看 `shipment_header.priority`，数字越大优先级越高。
-  - 同一优先级下，先看 `shipment_header.cutOffTime`，按时间到分钟维度越早越优先。
-  - 再看 `shipment_header.purchaseTime`，按时间到小时维度越早越优先。
-  - 最后看 `shipment_header.orderTime`，按订单创建时间越早越优先。
-- 抓单前需要先做字段匹配，只有 `wave_rule` 字段与出库单字段匹配上的单子，才进入后续抓单优先级判断。
-- 命中规则后，再绑定该 `wave_rule` 对应的分拣墙槽口，槽口绑定关系优先跟随规则而不是跟随订单数量变化。
-- 字段匹配规则统一走数据字典 `WAVE_RULE_FIELD_MATCHING`，用于声明：
-  - 出库单字段
-  - `wave_rule` 表字段
-  - 匹配条件类型，例如 `包含`、`等于`
-  - 对应的运算符口径，例如 `in`、`=`
-
-字段匹配的执行含义：
-
-- 先按 `WAVE_RULE_FIELD_MATCHING` 逐项判断出库单是否满足规则字段。
-- 匹配上的单子，再进入优先级排序和抓单数量控制。
-- 订单下发优先级只在同一规则命中的候选单之间生效，不改变 `wavePriority` 的规则排序结果。
-- 不同字段可以有不同匹配条件，不要把所有字段强制当成同一种比较方式。
-- `wave_rule.maxShipments` 只控制当前规则最多抓多少单，当前已在可用出库单查询中作为 `limit` 使用。
-
-当前代码状态说明：
-
-- 当前代码已按 `wavePriority` 做规则排序，并按 `shipment_header.priority`、`cutOffTime`、`purchaseTime`、`orderTime` 做同规则内候选单排序。
-- `WaveRuleMatchService#findAvailableShipments` 已接入 `WAVE_RULE_FIELD_MATCHING`，按 `identifier` 读取实际 `shipment_header` 字段，按 `value1` 读取 `wave_rule` 字段，按 `value2` 执行 `IN`、`=` 或 `LE` 匹配。
-- `WAVE_RULE_FIELD_MATCHING` 已作为统一数据字典维护，当前无同名默认映射；未配置有效 `identifier/value1` 或不在白名单内的配置会被忽略。
-
-### 3.16 槽口绑定与拣货衔接
-
-集波后，除了按 `waveRule` 选出可用格口候选外，还需要把绑定结果和拣货执行设计衔接起来。
-
-当前需求口径如下：
-
-- 集波后绑定对应 `wcs_sorting_wall_cell.waveRule` 设定相同规则的槽口。
-- 绑定的槽口需要记录在任务表或波次表中，作为拣货执行衔接依据。
-- 绑定记录不是重新生成规则，而是把当前波次命中的槽口固化下来，供后续拣货执行使用。
-- `wcs_sorting_wall_cell` 里的 `waveRule` 负责表达槽口可接收的规则范围。
-- `shopeeWave`、`waveRule` 等字段负责把波次、任务和槽口串起来，避免执行阶段再重新推导。
-
-当前代码状态说明：
-
-- 现有 `wcs_sorting_wall_cell` 已具备 `waveRule`、`currentWaveRule` 和 `shopeeWaveCode` 这类基础关联字段。
-- 后续如果需要更强的执行衔接能力，可以在任务表或波次表补充槽口记录字段，但文档口径先统一为“绑定结果需要可落库”。
-- 这一节和上墙优先级不是同一件事，上墙优先级负责“选哪条规则、抓哪些单”，槽口绑定负责“这些单最终落到哪个执行槽口”。
-
-### 3.17 单品单件动态加单与换箱换波
-
-`SSSQ` 单品单件场景需要支持波次动态加单和踢单，因为这类货品体积不固定，槽口要求是“尽量放满为止”。
-
-当前需求口径如下：
-
-- 仅 `SSSQ` 场景使用单独的动态加单阈值参数 `low_threshold`。
-- `low_threshold` 用于在槽口未放满时触发轮询补单。
-- 当前代码已新增 `WAVE/low_threshold` 系统参数，默认值为 `0`；当格口已有 `shopeeWaveCode` 且当前 Shopee 波次已绑定出库单量低于该阈值时，允许继续补单，达到或超过阈值时跳过该格口补单。
-- 计划任务形式的统一入口 `pollReplenishment/pollReplenishmentOnce` 已落地，复用 `WaveRuleMatchService#replenishCell` 处理 `low_threshold` 和已有 Shopee 波次格口的补单。
-- 如果按当前波次分配后，例如 30 单一波只分到了 27 单，但槽口还没放满，则需要继续加单。
-- 如果槽口已经放满，则先封箱，再进入换波流程。
-- 未分拣的单据需要按踢单逻辑重新回到订单池。
-
-换箱换波的处理口径如下：
-
-- 当 `SSSQ` 波次槽口已满但当前波次还没跑完时，剩余订单需要重新取一个与单据类型一致的 `shopee_wave` 波次号段。
-- 这个场景走 `flow pick` 的换箱接口，不是上文 1.7 的上游合波校验接口。
-- 上游校验通过后：
-  - 将剩余订单的拣货任务头 `shopeeWave` 更新为新波次号段。
-  - 同时更新出库单头 `shopeeWave`。
-  - 同步更新 `shopee_wave.status` 为 `200` 使用中。
-  - 因为剩余订单数量通常不足规则最大订单数，所以仍要继续走轮询补单逻辑。
-- 上游校验不通过时：
-  - 对订单执行拦截取消出库，恢复到正常订单池逻辑。
-  - 取消对应任务下发。
-  - 同时给 AGV 下发取消回库指令。
-
-当前代码状态说明：
-
-- 这一节仅针对 `SSSQ` 单品单件场景。
-- 轮询补单、换箱换波、踢单和 AGV 取消回库要保持解耦，但共享同一套候选回流思想。
-- 当前 `low_threshold` 已限定只影响 `SSSQ` 单品单件 wave rule，不扩散到其他 wave rule。
-- 当前实现以 `wave_rule.maxShipments` 作为满槽触发阈值；满槽后查询当前工作站、旧 Shopee 波次、当前 `waveRule` 下未完成任务订单，重新获取同单据类型 Shopee 波次号段，并批量回写任务头、出库单头和格口 `shopeeWaveCode`。
-- 当前通过可选 `essFlowPickService.sealBox/changeBoxWave` 承接 Flow Pick 真实接口；接口未接入时记录系统处理日志并执行 WES 本地状态闭环。
-- 换波失败时不会删除 `shopee_wave` 数据；新号段未被引用时仅回退状态为未使用。恢复订单池、取消任务下发、AGV 取消回库仍等待真实接口联调。
-
-### 3.18 轮询补单逻辑
-
-轮询补单由计划任务持续扫描，不和集波主流程、上游合波校验、换箱换波强耦合。
-
-#### 3.18.1 `SSSQ` 单品单件轮询补单
-
-当前口径如下：
-
-- 当工作站对应单品单件 `waveRule` 的槽口未完成订单数低于系统参数 `low_threshold` 时，触发补单。
-- 补单时，拿工作站对应订单类型以及该槽口的 `waveRule` 去订单池抓单。
-- 抓单优先级与上文 `3.15` 中一致。
-- 一次性补 `wave_rule.maxShipments` 指定的最大订单数，实际接入后由补单服务消费该字段。
-- 抓到的单据用该槽口的 `shopeeWave + 单号` 请求上游接口验证是否可以继续合波。
-- 上游校验 `ok` 时，WES 自动加入波次运行，与上文 `3.14` 逻辑一致。
-- 上游校验 `不 ok` 时，重新在订单池继续抓单再请求上游校验。
-- 已抓取但不符合的单子，需要过滤出当前波次号外。
-- 单子可能被多个波次号请求上游校验失败，技术实现时需要支持多次踢单记录，`kickOutWave` 可用逗号分隔保存。
-
-#### 3.18.2 非 `SSSQ` 场景轮询补单
-
-当前口径如下：
-
-- 轮询扫描正在作业的各工作站和各槽口。
-- 统计当前槽口绑定的 wave 订单数是否满足 `wave_rule.maxShipments`，该字段当前先按配置口径记录。
-- 统计范围包含该槽口当前波次进行中、已完成、未开始的单子。
-- 将汇总结果与 `wave_rule.maxShipments` 比较，若缺少 `X` 单，则去订单池抓 `X` 单。
-- 抓单时仍按上文 `3.15` 的抓单优先级执行。
-- 抓到的单据按该槽口的 `shopeeWave + 单号` 请求上游接口验证是否可以继续合波。
-- 上游校验 `ok` 时，WES 自动加入波次运行，与上文 `3.14` 逻辑一致。
-- 上游校验 `不 ok` 时，重新在订单池继续抓单再请求上游校验。
-- 已抓取不符合的单子需要从当前波次号外过滤掉。
-- 被 ESS 合波校验拒绝的单子，需要在 `shipment_header.kickOutWave` 里记录 Shopee wave 号，多个 wave 号用逗号隔开，后续该波次号再次抓单时过滤；库存不足踢单不记录 `kickOutWave`。
-
-当前代码状态说明：
-
-- 当前已落地计划任务形式的轮询补单入口 `pollReplenishment/pollReplenishmentOnce`，并复用单格口补单方法 `WaveRuleMatchService#replenishCell`。
-- 当前入口复用 `findPickingWorkstations`、`findReplenishmentCells`，用于扫描正在作业的工作站和已绑定 Shopee 波次的 `USED` 格口，并逐格口触发补单。
-- 当前格口分配链路和轮询补单链路均具备“ESS 校验失败写 `kickOutWave`、再次抓单时过滤同 Shopee 波次”的基础能力，并已支持常见失败订单 ID、单号和 Map 结构解析；真实 ESS 响应契约仍待接口联调确认。
-- `SSSQ` 与非 `SSSQ` 场景的补单策略不同，但都要保持“先抓单、再上游校验、失败过滤、重新抓单”的闭环。
-
-### 3.19 推拣货任务与推出库单的区别
-
-`Shopee` 推送过来的单据分两类，后续流程不能混用：
-
-#### 3.19.1 推拣货任务
-
-推拣货任务是“命中人工 + 自动化区”的单子，特点如下：
-
-- 推送时会同步推上游波次号段，不需要上文的取号逻辑。
-- WES 按推送的拣货任务建立出库单。
-- 再按上文的集波逻辑，结合工作站、出库类型和 `wave_rule` 抓单。
-- 这类订单按“1 单跑 1 个波次”处理，且后续无需补单。
-- 这类订单区分标识待梳理接口后提供。
-- 这类单子统一按“1 拣货单 1 波次 1 槽口”设计，不走轮询补单逻辑。
-
-#### 3.19.2 推出库单
-
-推出库单是“纯命中自动化区”的单子，特点如下：
-
-- 这类单子不走推拣货任务的特殊流程。
-- 按上文的正常集波流程处理。
-- 按波次号段申请、上游合波校验、槽口绑定、轮询补单等标准链路执行。
-- 这类单据仍需遵守 `wave_rule`、`wavePriority`、`maxShipments`、`low_threshold` 等通用规则。
-
-当前代码状态说明：
-
-- 推拣货任务和推出库单需要在入口层就分开，不要进入同一套补单或取号逻辑。
-- 推拣货任务的区分标识目前还待接口梳理后补充。
-- 后续实现时，推拣货任务以“一单一波一槽口”为核心约束，推出库单继续走标准集波链路。
-
-## 四、模块映射
-
-### 4.1 `wms-wave`
-
-建议作为波次规则和波次号段的主实现模块，承接：
-
-- `wave_rule` 配置
-- `shopee_wave` 号段管理
-- wave rule 优先级
-- 波次最大订单数
-- 波次运行与状态流转
-
-已落地的代码改动：
-
-- 新增 `WaveRule` 实体和 `WaveRuleService`
-- 新增 `ShopeeWave` 实体和 `ShopeeWaveService`
-- `Wave` 新增 `waveRule`
-- 新增 Flyway 脚本创建 `wave_rule` 与 `shopee_wave`
-
-### 4.2 `wms-shipping`
-
-承接出库单和订单头字段变更，包括：
-
-- 出库单类型
-- `shipment_header.priority`
-- `shipment_header.cutOffTime`
-- `shipment_header.purchaseTime`
-- `shipment_header.orderTime`
-- `shipmentCategory1`
-- `kickOutWave`
-- `shopeeWave`
-
-已落地的代码改动：
-
-- `ShipmentHeader` 新增 `cutOffTime`、`purchaseTime`、`orderTime`
-- `ShipmentHeader` 新增 `shopeeWave`、`kickOutWave`
-- `shipment_header`、`archive_shipment_header`、`deleted_shipment_header` 的 table 配置同步补齐
-- Flyway 脚本同步补齐三张表字段
-
-### 4.3 `wms-task`
-
-承接拣货任务、任务头字段和集波后的执行联动，包括：
-
-- 拣货任务头 `shopeeWave`
-- 拣货任务头 `waveRule`
-- 单品单件动态加单
-- 任务和波次执行衔接
-
-已落地的代码改动：
-
-- `WcsWorkStationPickTaskHeader` 新增 `shopeeWave`、`waveRule`
-- `wcs_work_station_pick_task_header` table 配置同步补齐
-
-### 4.4 `wms-core-wave`
-
-承接波次相关核心算法，比如：
-
-- wave rule 匹单逻辑
-- 优先级排序
-- 订单池筛选
-- 波次运行前后的核心判定
-- 当前波次创建顺序已经调整为“先查 `wave_rule`，再按规则条件查出库单”
-
-### 4.5 `wms-core-task`
-
-承接任务执行相关的核心能力，包括：
-
-- 任务生成和执行约束
-- 拣货和波次联动
-- 任务优先级衔接
-
-### 4.6 `wms-common`
-
-承接共用基础能力，包括：
-
-- 数据字典 `WAVE_RULE_FIELD_MATCHING`
-- 通用枚举
-- 共享字段定义
-- 通用规则封装
-
-### 4.7 `wms-automation`
-
-承接自动化区和 AGV 联动能力，包括：
-
-- 任务取消
-- 取消回库指令
-- 自动化区单据的执行边界
-
-已落地的代码改动：
-
-- `WcsSortingWallCell` 新增 `waveRule`
-- `WcsSortingWallCell` 新增 `currentWaveRule`
-- `WcsSortingWallCell` 现已支持保存 `shopeeWaveCode`
-- `UpdateSortingWallCellCmd` 新增 `waveRule`
-- `UpdateSortingWallCellCmd` 新增 `currentWaveRule`
-- `WcsSortingWallCellService` 已支持更新 `waveRule`
-- `WcsSortingWallCellService` 已支持更新 `currentWaveRule`
-- `wcs_sorting_wall_cell` table 配置和 Flyway 脚本已同步补齐
-
-### 4.8 `wms-inventory`
-
-承接库存相关判定和库存不足场景依赖：
-
-- 库存不足踢单
-- 可用库存优先分配
-- 库存点位和工作站半径联动
-
-### 4.9 配置模块
-
-建议同步更新以下配置模块：
-
-- `wms-wave-config`
-- `wms-shipping-config`
-- `wms-task-config`
-- `wms-inventory-config`
-
-用于承接规则枚举、静态配置和界面配置项。
-
-## 五、实施计划
-
-### 第 1 步：补规则和表结构
-
-先完成以下内容：
-
-- `wave_rule` 表设计和字段补齐
-- `shopee_wave` 表设计和字段补齐
-- 分拨墙槽口表 `wcs_sorting_wall_cell` 增加 `waveRule`
-- 出库单头和任务头字段补齐
-
-这一阶段的目标是把所有需求依赖的字段和持久化基础先补齐。
-
-状态：已完成。
-
-### 第 2 步：补基础规则引擎
-
-再完成：
-
-- wave rule 字段匹配
-- 波次优先级排序
-- 订单类型识别
-- 出库单筛选规则
-- 分拨墙槽口 wave rule 匹配
-
-这一阶段的目标是让系统能够判断“哪些单能进哪条规则”。
-
-状态：基础能力已落地，高级语义待实现。
-当前已能按规则逐条查单并返回格口分配结果，已接入基础排序、`maxShipments` 截断、`waveType/shipmentCategory1` 匹配和 `WAVE_RULE_FIELD_MATCHING` 字典基础匹配。
-
-### 第 3 步：补集波主流程
-
-然后实现：
-
-- 工作站按订单类型和规则集波
-- 号段申请
-- 波次生成
-- 波次绑定出库单和任务
-- 集波后自动运行
-
-备注：
-
-- 由于完整波次级规则引擎仍在重建阶段，波次主流程仍沿用原有 `shipmentFilterCode` 过滤逻辑。
-
-这一阶段的目标是跑通主链路。
-
-状态：基础主链路已落地，接口闭环待实现。
-当前已具备创建内部波次、批量加入内部波次、异步提交运行、基础字段回写和 ESS 拒单基础解析能力；上游号段申请、真实 ESS 响应契约、库存不足踢单上游撤单和任务头字段完整闭环仍待补齐。
-
-### 第 4 步：补补单与踢单
-
-随后实现：
-
-- 轮询补单
-- 轮询补单建议拆成以下几层：
-- 第一层先判断波次是否仍处于允许补单的状态，避免已锁定、已释放、已关闭的波次继续被补。
-- 第二层按波次规则重新拉取订单池候选单，必须同时满足规则匹配、状态可用、未被其他波次占用。
-- 第三层按波次剩余容量和订单优先级决定是否补入，补入后同步刷新波次统计和订单池状态。
-- 第四层若连续若干轮没有新增候选单，则提前结束轮询，避免空转。
-- 第五层若补单过程中发生库存不足、规则冲突或并发锁失败，应立即停止当前轮询，并保留已成功补入的结果。
-- 库存不足踢单
-- 上游校验失败踢单
-- 失败单据回流订单池
-
-这一阶段的目标是让系统在异常情况下还能稳定收敛。
-
-状态：待实现。
-
-### 第 5 步：补单品单件特殊逻辑
-
-最后补单品单件特殊流程：
-
-- 动态加单
-- 换箱换波
-- 封箱后的波次切换
-- 仅对 `SSSQ` 生效的补单/换波策略
-
-这一阶段的目标是把高频特殊场景单独收口。
-
-状态：待实现。
-
-## 六、验证计划
-
-### 6.1 规则验证
-
-- 验证 wave rule 字段映射是否正确
-- 验证规则优先级排序是否正确
-- 验证多选、包含、等于等匹配条件是否正确
-
-### 6.2 数据验证
-
-- 验证 `wave_rule` 表和 `shopee_wave` 表的增删改查
-- 验证出库单、任务头字段是否能正确落库
-- 验证分拨墙槽口与 wave rule 的绑定关系
-
-### 6.3 流程验证
-
-- 验证集波主流程是否能从订单池成功抓单
-- 验证补单流程是否能触发
-- 验证踢单流程是否能正确回流
-- 验证单品单件换箱换波是否符合预期
-
-### 6.4 联动验证
-
-- 验证上游号段申请
-- 验证上游校验失败时的回退逻辑
-- 验证自动化区取消回库指令
-
-### 6.5 当前验证结果
-
-- 已完成 JSON 表配置静态校验。
-- 已完成字段名和迁移脚本的人工一致性校对。
-- 当前环境缺少 `gradlew` 和全局 `gradle`，未执行仓库级编译。
-
-## 七、风险点
-
-- wave rule 字段多、匹配条件多，容易出现规则解释不一致。
-- 单品单件和非单品单件的补单逻辑不同，容易产生分支遗漏。
-- 上游接口未完全明确时，接口契约和失败处理需要先留好扩展点。
-- 出库单、任务、波次、槽口四者之间的状态同步需要严格控制。
-
-## 八、建议落地顺序
-
-1. 先补表结构和字段。
-2. 再补规则匹配和基础算法。
-3. 然后补主集波流程。
-4. 再补补单、踢单和异常回退。
-5. 最后补单品单件特殊流程。
-
-## 九、下一步建议
-
-- 如果你要，我可以继续把这份计划拆成“按模块的开发任务清单”。
-- 如果你要，我也可以继续把这份计划细化成“接口级别”的需求拆分文档。

集波/SHOPEE_010_出库集波V1.2_WaveRuleMatchService_流程文档.md

@@ -4,7 +4,7 @@
 >
 > 本文档描述该服务的**当前代码流程**，按调用入口到出口的完整链路展开，包括主流程、分流流程、补缺口流程、回滚流程和详细的规则匹配机制。
 >
-> 需求标准来源：`C:\work\gitlab\shopee\ttx-project-doc\集波\SHOPEE_010_出库集波V1.2.docx`，当前同步到 V1.4 口径：`wave_rule.waveType` 与 `shipment_header.orderStructure` 包含关系、同一 `groupKey` 集波约束、字段匹配字典规则。
+> 需求标准来源：`C:\work\gitlab\shopee\ttx-project-doc\集波\SHOPEE_010_出库集波V1.2.docx`，当前同步到 V1.4 口径：`wave_rule.waveType` 与 `shipment_header.orderStructure` 包含关系、同一 `groupKey` 集波约束、字段匹配字典规则、`Max SKU Pieces Per Order` / `Mix Mode Max SKU Pieces Filter` 标准要求、`multi_attr_list` 全包含匹配要求。
 
 ---
 
@@ -49,6 +49,7 @@
 | 规则类型匹配 | `wave_rule.waveType` 通过 `resolveMatchedOrderStructures` 转换为可抓的 `orderStructure` 集合 |
 | 字段匹配 | 通过 `WAVE_RULE_FIELD_MATCHING` 字典追加 `wave_rule` 字段与 `shipment_header` 字段的 `IN/EQ/LE` 条件 |
 | 同波约束 | 首次抓单会先按最早候选单解析 `groupKey`；补缺口时按当前 `shopee_wave.groupKey` 过滤，保证同一 Shopee 波次只集相同 `groupKey` |
+| V1.4 新增 SKU 件数过滤 | `Max SKU Pieces Per Order`、`Mix Mode Max SKU Pieces Filter` 是 docx 标准要求；当前 `WaveRule` 域和匹单 SQL 未见对应落地字段，列为待实现 |
 
 **三种分流入口：**
 
@@ -143,6 +144,12 @@ hasDifferentActiveShipmentType(warehouseCode, workstationId, shipmentType)
 - 拒绝时记录系统处理日志，并返回 `MSG_WRM_0014`。
 - 该校验位于 Redis 锁之前，避免无效请求占用集波锁。
 
+### 3.4 工作站出库类型权限
+
+标准要求：登录工作站时按用户权限控制可选择的出库类型，配置后工作站只能下拉选择该用户有权限的单据类型。
+
+当前实现/待实现：`WaveRuleMatchService` 已做同一工作站不同出库类型隔离；用户与出库类型的权限绑定仍是 TODO，不能在本文档中描述为已落地。
+
 ---
 
 ## 4. 一波一单分流流程
@@ -215,6 +222,7 @@ for each WaveRule:
 | 当前状态 | 普通批量集波已过滤 `pickType=2` |
 | 待实现 | 独立分流入口、一单一波一槽口、内部波次运行 |
 | 补单 | 后续仍按“不走补单逻辑”处理 |
+| 取号 | 标准要求推拣货任务使用上游同步的 Shopee 波次号，WES 不走取号逻辑 |
 
 ---
 
@@ -314,6 +322,7 @@ appendWaveTypeOrderStructureFilter(sql, params, rule)
 - `wave_rule.waveType` 是规则侧单选类型，不直接等值匹配订单结构，而是通过上表转换成可包含的订单结构集合。
 - `appendWaveTypeOrderStructureFilter` 同时用于普通批量候选和一波一单候选，保证入口一致。
 - 未识别的 `waveType` 不追加订单结构条件；此场景通常表示规则数据异常，应通过规则主数据维护修正。
+- docx 中同时出现 `SSSQ` 与 `SSSQ(Same SKU same Qty)` 两个名称，其中编码 `2` 映射到 `MSAQ`；命名含义按 docx 待确认，当前实现按编码表执行。
 
 ### 6.4 订单池 SQL 基础条件
 
@@ -356,6 +365,8 @@ WHERE warehouseCode = :warehouseCode
 | 2 | `matchRuleCells` | `currentWaveRule` 为空 且 `waveRule` 逗号分隔匹配 rule.code | 中 |
 | 3 | `matchEmptyCells` | `currentWaveRule` 和 `waveRule` 均为空 | 兜底 |
 
+标准要求：分播墙明细界面中 `wcs_sorting_wall_cell.waveRule` 取值来自 `wave_rule`，支持多选，多个规则中间用逗号隔开。当前 `matchRuleCells` 通过逗号拆分匹配当前规则编码。
+
 ### 7.2 格口抢占
 
 ```
@@ -439,6 +450,8 @@ bindShipmentShopeeWave(warehouseCode, shipmentIds, shopeeWaveCode)
 
 正式接口契约确认后，只需补齐 `requestShopeeWaveBind` 的真实调用；当前不再保留柔性拒单解析方法。
 
+标准要求补充：销售 `create_picking_task`、RTS-MTO 下发/变更等上游链路需要带入或校验 Shopee 波次号；当前服务侧保留统一合波校验入口，真实 create_picking_task / RTS-MTO 接口契约仍待接入验证。
+
 ---
 
 ## 9. 内部波次创建与运行
@@ -470,6 +483,8 @@ addShipmentsToInternalWave(shipmentIds, waveId)
 
 库存不足踢单由 `wms-wave` 回池链路处理：回池时清空出库单头 `shopeeWave/waveRule`，不记录 `kickOutWave`；上游撤单接口仍需在回池链路接入。
 
+标准要求：库存分配优先按效期/先到期先出与 FIFO，其次按工作站点位与库存点位半径最小，同半径内低层货位优先；库存不足单据需踢单并通知上游撤单。当前本文只记录集波服务入口与回池清理口径，库存最优分配和上游撤单通知不应描述为 `WaveRuleMatchService` 已完成。
+
 ---
 
 ## 10. 回滚机制
@@ -582,6 +597,8 @@ calcCellNeedQty(warehouseCode, rule, cell, shopeeWaveCode)
 
 `isFlowPickCellFull`：单品单件 + `countShopeeShipments >= maxShipments`
 
+标准要求：Flow Pick 包含 SSSQ、MSSQ 规则；RTS/MTO 下发单据因按行拆单，也按 Flow Pick 处理。当前服务中的满槽换箱判断以单品单件规则为主，RTS/MTO Flow Pick 细分触发口径按 docx 待确认。
+
 ### 12.2 流程
 
 ```
@@ -684,7 +701,16 @@ changeFlowPickWave(workstation, cell, rule):
 **规则字段（16）：**
 `channelId`, `fulfillmentChainId`, `orderSize`, `skuSizeType`, `categoryLevel1Id`, `shopGroup`, `shopId`, `urgentFlag`, `outerPackaging`, `outerPackagingId`, `deliveryRegion`, `fragile`, `liquid`, `highValue`, `battery`, `danger`
 
-### 13.5 执行流程
+### 13.5 V1.4 新增/待确认匹单字段
+
+| 标准字段/规则 | 标准要求 | 当前实现/待实现 |
+|---------------|----------|-----------------|
+| `Max SKU Pieces Per Order` | 单订单任一 SKU 件数大于规则阈值时，该订单排除出当前 wave rule，转给低优先级的大件数规则 | 当前 `WaveRule` 域与 `appendRuleFieldMatching` 未见对应字段/SQL，待实现 |
+| `Mix Mode Max SKU Pieces Filter` | 仅 Mix-mode/MSAQ 规则生效，排除单 SKU 件数过高的混合订单，避免混合波次槽位过度丰富 | 当前未见对应字段/SQL，待实现 |
+| SKU 主档字段匹配 | docx 要求 API 列为 SKU 的规则字段需与单据所有明细 SKU 主档字段匹配，全部匹配才能进该规则 | 当前字段匹配 SQL 只处理单头/扩展字段；明细 SKU 全量匹配待实现或待接入 |
+| `multi_attr_list` | docx 要求多值字段用逗号存储时必须全包含；按示例，规则 `A,B,C` 可匹配单据 `A,B`，规则 `B,C` 不匹配单据 `A,B` | 当前 `channelId/fulfillmentChainId` 逗号字段按任一值命中；全包含方向按 docx 待确认，当前待调整 |
+
+### 13.6 执行流程
 
 ```
 resolveRuleFieldMappings(warehouseCode)
@@ -842,8 +868,12 @@ fillShortageCells
 | 上墙优先级 | `findEnabledRules` 按 `wavePriority desc, id asc`；高优先级不足 `maxShipments` 仍优先消费 | 已落地 |
 | 抓单优先级 | `priority desc`、`cutOffTime asc`、`purchaseTime asc`、`orderTime asc`、`id asc` | 已落地 |
 | `wave_rule.maxShipments` | `resolveShipmentLimit` 使用规则级 `maxShipments`，默认 30 | 已落地 |
+| `wcs_sorting_wall_cell.waveRule` 多选 | 逗号分隔匹配当前规则编码 | 已落地 |
 | `WAVE_RULE_FIELD_MATCHING` | `appendRuleFieldMatching` 按字典追加 `IN/EQ/LE` 条件 | 已落地 |
 | `kickOutWave` 过滤 | `appendKickOutFilter` 对同一 Shopee 波次过滤已拒单 | 已落地 |
+| `Max SKU Pieces Per Order` | 标准字段已同步到文档，当前未见字段/SQL | 待实现 |
+| `Mix Mode Max SKU Pieces Filter` | 标准字段已同步到文档，当前未见字段/SQL | 待实现 |
+| `multi_attr_list` 全包含 | 当前逗号字段按任一值命中；docx 示例方向已记录 | 待调整，按 docx 待确认 |
 
 ### 15.2 waveType/orderStructure 标准映射
 
@@ -860,10 +890,13 @@ fillShortageCells
 | 标准需求点 | 当前实现状态 | 后续落点 |
 |------------|--------------|----------|
 | Shopee 合波校验真实接口 | `requestShopeeWaveBind` 为预留入口，当前只保留整批成功/失败契约 | 接口契约明确后补真实调用 |
+| create_picking_task / RTS-MTO 上游校验 | 标准要求与 Shopee 波次获取、合波校验衔接；当前仅有服务侧统一预留入口 | 真实接口契约确认后接入 |
 | 库存不足踢单通知上游撤单 | 当前由回池链路清空 `shopeeWave/waveRule`，上游撤单接口仍待接入 | `wms-wave` 回池链路 |
 | 计划任务轮询补单 | 原 `pollReplenishment/pollReplenishmentOnce` 已删除；当前补缺口在首次集波入口 `fillShortageCells` 执行 | 如需后台轮询，需恢复独立计划任务入口 |
 | 推拣货任务一单一波一槽口 | 普通批量已过滤 `pickType=2`，独立分流入口当前未保留 | 待恢复 `pickType=2 + shopeeWave` 专用分流 |
 | Flow Pick 封箱/换箱接口 | 本地流程已有占位方法，真实 ESS/AGV 接口未接入 | `requestFlowPickSealBox` / `requestFlowPickChangeBox` / `handleFlowPickChangeWaveFailure` |
+| 工作站用户权限控制出库类型 | 当前只校验工作站启用、仓库和不同出库类型隔离 | 用户权限与出库类型绑定仍待实现 |
+| 库存最优分配策略 | docx 要求效期/FIFO、工作站/库存半径、低层货位优先 | 属库存分配链路，本文不标记为 `WaveRuleMatchService` 已落地 |
 
 ## 附录：TODO 清单（代码内标注）
 

集波/SHOPEE_010_出库集波V1.2_findBestMatchedRule_API.md

@@ -1,6 +1,10 @@
 # 出库集波规则匹配 API 文档
 
 > 对应实现：`WaveRuleMatchController#findBestMatchedRule` → `WaveRuleMatchService#findBestMatchedRuleByWorkStationAndOutboundType`
+>
+> 需求标准来源：`C:\work\gitlab\shopee\ttx-project-doc\集波\SHOPEE_010_出库集波V1.2.docx`（V1.4，2026-06-04 逻辑修改 / 匹单字段逻辑更新）。
+>
+> 需求标准来源：`SHOPEE_010_出库集波V1.2.docx`，已同步 V1.4「匹单字段逻辑更新」口径；未落地项在本文中明确标记为“标准要求/当前实现/待实现”。
 
 ---
 
@@ -11,7 +15,7 @@
 1. 根据**工作站 + 出库类型**找出当前可用的分播墙格口
 2. 按规则优先级查找订单池中符合条件的出库单
 3. 完成 Shopee 波次绑定、ESS 校验、内部波次创建与运行
-4. 返回「格口 + 命中规则 + 波次」的分配结果
+4. 当前实现成功后返回 `ResponseMessageFactory.success()`，不返回「格口 + 命中规则 + 波次」明细
 
 ---
 
@@ -50,6 +54,23 @@ POST wms/automation/waveRuleMatch/findBestMatchedRule
 | `RTS` | RTS 出库 | 标准批量集波 |
 | `RT` | RT 出库 | 一波一单，不使用 Shopee 波次号，走库内流程 |
 
+### 标准要求补充
+
+- `wave_rule.wavePriority` 先决定上墙优先级，`maxShipments` 决定抓单数量；即使高优规则订单不足，也要优先匹高优规则的单。
+- 同一规则内抓单优先级按 `shipment_header.priority` 降序、`cutOffTime` 升序、`purchaseTime` 升序、`orderTime` 升序。
+- `shipment_header.orderStructure` 若为空，出库单下发后需自动分析并写回：`SSSQ=1`、`SSAQ=2`、`MSAQ=3`。
+- `wave_rule.waveType` 与 `shipment_header.orderStructure` 按 docx 表格做包含关系匹配，表中命名/编码有歧义处保留原文并按 docx 待确认。
+- 匹单还要求 `shipment_header.groupKey` 一致才能集在一起。
+- `multi_attr_list` 采用全包含匹配：规则值 `A,B,C` 对单据 `A,B` 可匹配；规则值 `B,C` 对单据 `A,B` 不匹配。
+- `wcs_sorting_wall_cell.waveRule` 支持多选，多个规则逗号分隔。
+- 工作站选择出库类型受用户权限控制，同一工作站不混做不同出库类型。
+- 仅抓正常单据，取消/挂起/异常单不抓。
+- `shipment_header.pickType=1/0` 仅允许在订单池 `100` 状态切换。
+- `XSCK`、`MTO`、`RTS`、`RT` 的 `ticketType` 映射按 docx 口径分别为：销售任务 `1` / 销售订单 `2`，MTO 任务 `5` / MTO 订单 `4`，RTS `3`，RT `6`。
+- 推拣货任务标准要求为：上游同步 wave 号段，WES 不走取号逻辑，1 拣货单 1 波次 1 槽口，不走补单。
+- Flow Pick 标准要求覆盖 `SSSQ/MSSQ` 以及 RTS/MTO 下发单据；满槽换箱换波走 Flow Pick 换箱接口。
+- 集波后需按单据类型取得 `shopee_wave` 并请求上游校验：销售 create_picking_task 走 3.2.7，RTS/MTO 走 3.3.6；失败订单后续通过补单/踢单处理。
+
 ---
 
 ## 响应
@@ -74,6 +95,10 @@ POST wms/automation/waveRuleMatch/findBestMatchedRule
 }
 ```
 
+> 标准要求：返回格口 + 命中规则 + 波次分配明细。
+>
+> 当前实现：成功时通常仅返回 `ResponseMessageFactory.success()`，不保证返回上述明细；若调用链未产出分配结果，请以 success 为准。
+
 | 响应字段 | 类型 | 说明 |
 |----------|------|------|
 | `shipmentId` | Long | 已集波出库单 ID |
@@ -113,6 +138,7 @@ POST wms/automation/waveRuleMatch/findBestMatchedRule
 | `MSG_WRM_0010` | 当前规则下无可匹配出库单 | 订单池无符合条件的出库单 |
 | `MSG_WRM_0011` | 规则或工作站为空 | 内部校验 |
 | `MSG_WRM_0012` | 工作站正在集波中 | Redis 锁获取失败，同一工作站同一出库类型正在集波 |
+| `MSG_WRM_0014` | 工作站已有其它出库类型作业 | 同一工作站已存在其它 `shipmentType` 的占用格口/波次 |
 
 ---
 
@@ -125,9 +151,11 @@ POST /findBestMatchedRule
 │
 ├─ 2. 工作站校验 (存在 / 启用 / 仓库匹配)
 │
-├─ 3. Redis 锁 (仓库+工作站+出库类型, 防重复集波)
+├─ 3. 同工作站出库类型隔离 (不允许一个工作站混做不同 shipmentType)
 │
-├─ 4. 查询启用波次规则 (按 wavePriority desc)
+├─ 4. Redis 锁 (仓库+工作站+出库类型, 防重复集波)
+│
+├─ 5. 查询启用波次规则 (按 wavePriority desc)
 │
 ├─ [分支 A] 一波一单
 │   └─ assignSingleShipmentWaves
@@ -139,22 +167,22 @@ POST /findBestMatchedRule
 │
 └─ [分支 C] 空格口首次分配 (逐规则按优先级循环)
     │
-    ├─ 5. 查可用格口 (三层级):
+    ├─ 6. 查可用格口 (三层级):
     │   ├─ sameCurRuleCells — currentWaveRule 同当前规则
     │   ├─ ruleCells — waveRule 配置匹配当前规则
     │   └─ emptyCells — 完全空闲格口
     │
-    ├─ 6. 按规则查询出库单:
+    ├─ 7. 按规则查询出库单:
     │   ├─ 一波一单候选项 (pickType=1 / ticketType 任务 / RT)
     │   └─ 批量集波候选项 (排除一波一单)
     │
-    ├─ 7. 创建内部波次 (WaveService#createInternalWave)
+    ├─ 8. 创建内部波次 (WaveService#createInternalWave)
     │
-    ├─ 8. 格口循环处理:
+    ├─ 9. 格口循环处理:
     │   ├─ 已有波次号 → 补单缺口判断
     │   └─ 无波次号 → 抢占 Shopee 波次号 (acquireUnusedShopeeWave)
     │
-    ├─ 9. assignToCell:
+    ├─ 10. assignToCell:
 │   ├─ pickCellShipmentIds — 按格口缺口截断候选单
     │   ├─ ensureCellReadyForWave — 先抢占格口 (USED)
     │   ├─ bindShipmentShopeeWave — ESS 绑定校验
@@ -162,7 +190,7 @@ POST /findBestMatchedRule
     │   │   └─ 失败 → 写入 kickOutWave, 同波次后续过滤
 │   └─ addShipmentsToInternalWave → WaveService#run
 │
-    └─ 10. 成功返回 ResponseMessageFactory.success()，不返回格口分配明细
+    └─ 11. 成功返回 ResponseMessageFactory.success()，不返回格口分配明细
 ```
 
 ---
@@ -179,6 +207,19 @@ POST /findBestMatchedRule
    - 同购买时间按 `orderTime` 越早越优先
    - 同时间按 `id` 升序兜底
 
+### V1.4 标准要求与当前实现
+
+| 标准要求 | 当前实现/待实现 |
+|----------|-----------------|
+| 修改历史 V1.4：匹单字段逻辑更新 | 本文按 docx V1.4 同步 `waveType/orderStructure`、`groupKey`、规则字段匹配和新增字段说明 |
+| `wave_rule` 字段按 WES 小驼峰与 base 字段命名规范维护 | 当前规则域已包含 `waveType`、`wavePriority`、`maxShipments` 及多项规则属性；主数据字段命名以代码和迁移为准 |
+| 新增/强调 `Max SKU Pieces Per Order` | 标准要求：单订单任一 SKU 件数超过阈值时排除本规则；当前 `WaveRule`/匹单 SQL 未见对应规则字段，待实现 |
+| 新增/强调 `Mix Mode Max SKU Pieces Filter` | 标准要求：仅 Mix-mode/MSAQ 规则使用，用于排除单 SKU 件数过高的混合订单；当前未见对应匹单实现，待实现 |
+| 出库单 `orderStructure` 为空时自动分析 | 当前由订单明细分析后写入 `shipment_header.orderStructure`：`SSSQ=1`、`SSAQ=2`、`MSAQ=3` |
+| 工作站出库类型权限控制 | 标准要求：登录工作站按用户权限下拉可选出库类型；当前服务已做同工作站不同出库类型隔离，用户权限绑定仍为待实现 |
+| Shopee 波次号获取与上游合波校验 | 当前 `acquireUnusedShopeeWave` 抢占 `shopee_wave` 未使用号段；`requestShopeeWaveBind` 是上游校验预留入口，create_picking_task / RTS-MTO 真实接口契约仍待接入 |
+| 库存最优分配与库存不足踢单 | 标准要求：效期/FIFO、工作站与库存点位半径优先、同半径低层货位优先；当前集波入口只触发 `WaveService#run`，库存不足踢单回池与上游撤单通知仍需在库存/回池链路接入 |
+
 ### 格口分配优先级
 
 | 优先级 | 格口类型 | 条件 |
@@ -187,6 +228,8 @@ POST /findBestMatchedRule
 | 2 | `ruleCells` | `currentWaveRule` 为空且 `waveRule` 匹配当前规则 |
 | 3（兜底） | `emptyCells` | `currentWaveRule` 和 `waveRule` 均为空 |
 
+> 标准要求：`wcs_sorting_wall_cell.waveRule` 支持分播墙明细界面多选，一个格口可绑定多个 `wave_rule`，多个规则用逗号分隔存储；当前匹配按逗号拆分后判断是否包含当前规则编码。
+
 ### 一波一单处理
 
 以下单据类型按一波一单处理（每次集波只取 1 单，创建独立内部波次）：
@@ -198,6 +241,15 @@ POST /findBestMatchedRule
 | MTO 任务 | `ticketType=5` | 一波一单 |
 | RT | `ticketType=6` | 不使用 Shopee 波次号 |
 
+### 订单结构与 Flow Pick
+
+| 项 | 标准要求 | 当前实现/说明 |
+|----|----------|---------------|
+| `waveType/orderStructure` 包含关系 | 按 docx 表：`SSSQ(1)->SSSQ(1)`、`MSSQ(5)->SSSQ(1)`、`SSAQ(4)->SSSQ/SSAQ(1/2)`、`SSSQ(Same SKU same Qty)(2)->MSAQ(3)`、`MSAQ(3)->SSSQ/SSAQ/MSAQ(1/2/3)` | 当前通过 `appendWaveTypeOrderStructureFilter` 固定过滤。`SSSQ(Same SKU same Qty)` 与 `SSSQ` 命名相近，按 docx 待确认 |
+| `groupKey` | 同一 Shopee 波次只能集相同 `shipment_header.groupKey` 特征值订单 | 当前首次抓单按首个候选单确定 `groupKey`，补单按 `shopee_wave.groupKey` 过滤 |
+| Flow Pick | 标准定义：SSSQ/MSSQ 为 Flow Pick，RTS/MTO 下发单据也按 Flow Pick 处理 | 当前已有 Flow Pick 换箱换波本地流程与接口占位，真实 ESS/AGV 接口待接入 |
+| 推拣货任务 | 上游推送 Shopee 波次号，WES 不走取号逻辑；1 拣货任务 / 1 波次 / 1 槽口；不走补单 | 当前普通批量已过滤 `pickType=2`，专用分流入口待恢复 |
+
 ### 字段匹配
 
 通过数据字典 `WAVE_RULE_FIELD_MATCHING` 配置出库单字段与规则字段的匹配关系：
@@ -213,11 +265,17 @@ POST /findBestMatchedRule
 - **出库单字段**（30+）：`shipmentType`、`ticketType`、`pickType`、`sourcePlatform`、`sourceErp`、`route`、`carrierCode`、`shipToCountry`、`userDef1-8` 等
 - **规则字段**（16）：`channelId`、`fulfillmentChainId`、`orderSize`、`skuSizeType`、`categoryLevel1Id`、`shopGroup`、`shopId`、`urgentFlag`、`outerPackaging`、`deliveryRegion`、`fragile`、`liquid`、`highValue`、`battery`、`danger` 等
 
+补充口径：
+
+- 标准要求：只对 `wave_rule` 中对应订单类型列标记 `Y` 的字段做匹配；SKU 来源字段需与单据所有明细 SKU 主档字段全部匹配。
+- 标准要求：`multi_attr_list` 多值字段匹配时按 docx 示例为“规则值全包含单据值”，例如规则 `A,B,C` 可匹配单据 `A,B`，规则 `B,C` 不匹配单据 `A,B`；该包含方向按 docx 待确认。
+- 当前实现：逗号多值字段目前按任一值命中生成条件，`multi_attr_list` 全包含匹配仍待调整。
+
 ### 并发控制
 
 Redis 分布式锁，锁 Key：`wave_rule_match:{warehouseCode}:{workstationId}:{shipmentType}`
 
-同一工作站 + 同一出库类型同时只有一个请求能进入集波流程。
+同一工作站 + 同一出库类型同时只有一个请求能进入集波流程；同一工作站如果已有其它出库类型作业，入口直接拒绝，避免混做。
 
 ### 异常过滤
 
@@ -250,7 +308,7 @@ Redis 分布式锁，锁 Key：`wave_rule_match:{warehouseCode}:{workstationId}:
 
 | 表名 | 说明 | 关键字段 |
 |------|------|----------|
-| `wave_rule` | 波次规则 | `code`, `waveType`, `wavePriority`, `maxShipments`, `status`, `channelId`, `shopId` 等 |
+| `wave_rule` | 波次规则 | `code`, `waveType`, `wavePriority`, `maxShipments`, `status`, `channelId`, `shopId` 等；V1.4 标准新增 `Max SKU Pieces Per Order`、`Mix Mode Max SKU Pieces Filter` 待实现 |
 | `shopee_wave` | Shopee 波次号段 | `code`, `waveType`, `warehouseCode`, `pickType`, `groupKey`, `flow_pick`, `status` (100=未使用, 200=使用中, 900=使用完成) |
 | `shipment_header` | 出库单头 | `shopeeWave`, `kickOutWave`, `ticketType`, `pickType`, `groupKey`, `orderStructure`, `waveId` |
 | `wcs_sorting_wall_cell` | 分播墙格口 | `waveRule`, `currentWaveRule`, `shopeeWaveCode`, `useStatus` |