# 文档统一汇总

## 目标

把 `docs/` 下当前分散的需求、计划、评估和模块说明，统一收敛到一份入口文档里维护。

## 维护原则

- 以主题归档，不以项目目录分拆主线内容。
- 目录中的历史子文档保留为参考，不作为新的主入口。
- 已落地内容和待实现内容要分开写，避免计划和现状混在一起。
- 代码、配置、迁移脚本和文档必须保持一致。

## 当前主线

### 出库集波 V1.2

当前已经整理并落地的内容：

- 新增 `wave_rule` 和 `shopee_wave` 两张表。
- 新增 `WaveRule`、`ShopeeWave` 实体和对应 service。
- `Wave` 新增 `waveRule`。
- `shipment_header` 新增 `cutOffTime`、`purchaseTime`、`orderTime`、`shopeeWave`、`kickOutWave`。
- `archive_shipment_header` 和 `deleted_shipment_header` 同步补齐上述字段。
- `wcs_sorting_wall_cell` 新增 `waveRule` 和 `currentWaveRule`。
- `wcs_work_station_pick_task_header` 新增 `shopeeWave`、`waveRule`。
- `wcs_sorting_wall` 明细页的 `waveRule` 已改为多选下拉，支持多规则逗号分隔保存。
- `wave_rule` 匹配能力已落地基础链路，当前 `WaveRuleMatchService` 已支持以 `workstationId + 出库类型` 按规则逐条查单并返回格口分配结果；当前版本已接入基础订单池查询、规则优先级、订单优先级排序和 `WAVE_RULE_FIELD_MATCHING` 字典字段匹配。
- 可用出库单查找逻辑已和格口分配链路一起维护，`WAVE_RULE_FIELD_MATCHING` 当前支持 `identifier=shipment_header字段`、`value1=wave_rule字段`、`value2=匹配条件`，并支持 `IN`、`=`、`LE` 操作符；`Include / Exclude / Only`、SKU 维度聚合和区间高级语义仍待补齐。
- 出库单分配成功后，当前已能回写 `shipment_header.shopeeWave`、占用格口并记录 `currentWaveRule` / `shopeeWaveCode`，再批量加入内部波次并异步提交运行；计划任务轮询补单和 Flow Pick 本地换箱换波闭环已落地，库存不足踢单清绑定已在 `wms-wave` 回池链路处理，上游撤单接口仍待联调。
- 集波完成后，需要从 `shopee_wave` 里取出与出库单类型一致的 `waveType` 号段，请求上游做合波校验；当前已有 ESS 校验调用入口和失败订单基础解析，真实接口契约仍待联调确认。
- 当前集波运行已调用内部波次 `run`，该方法只异步提交 `wms.wave` 队列消息，`WaveRuleMatchService` 不解析同步运行结果；库存不足踢单由 `wms-wave` 回池流程清空 Shopee 绑定，不记录 `kickOutWave`，上游撤单仍待接口联调。
- 波次运行成功后，需要把 `shopee_wave` 号段绑定到出库单头 `shopeeWave`、任务头 `shopeeWave` / `waveRule`，并把当前 `waveRule` 回写到 `wave` 表，同时把 `shopee_wave.status` 更新为 `200` 使用中；当前仅部分链路已落地。
- 上墙优先级已按 `wavePriority` 从高到低排序，同规则内已按出库单优先级和时间字段排序；`WAVE_RULE_FIELD_MATCHING` 基础字段匹配已实现。
- 同一规则命中的订单池内部，再按 `shipment_header.priority`、`shipment_header.cutOffTime`、`shipment_header.purchaseTime`、`shipment_header.orderTime` 做抓单优先级排序，其中后面三个时间维度均越早越优先。
- 命中规则后，再绑定对应 `wave_rule` 的分拣墙槽口，槽口绑定关系跟随规则，不随订单数量变化而改变。
- 集波后绑定的槽口需要落到任务表或波次表中，作为拣货执行衔接依据。
- `SSSQ` 单品单件已接入 `low_threshold` 系统参数的低阈值判断；槽口已有 `shopeeWaveCode` 时，低于阈值允许继续补单，达到或超过阈值则跳过该格口补单。
- `SSSQ` 单品单件已补齐槽口放满后的本地封箱换波闭环：以 `wave_rule.maxShipments` 作为满槽阈值，剩余未完成订单重新取 Shopee 波次并回写任务头、出库单头和格口；真实 Flow Pick 接口、失败后恢复订单池、取消任务下发和 AGV 取消回库仍待联调。
- 计划任务补单入口 `pollReplenishment/pollReplenishmentOnce` 已落地，并按 `SSSQ` 与非 `SSSQ` 分两条线处理：`SSSQ` 低于 `low_threshold` 时触发补单，非 `SSSQ` 按 `maxShipments` 缺口补单，并复用 ESS 合波校验失败产生的 `kickOutWave` 过滤。
- 推拣货任务与推出库单分流已在 WES 侧落地：推拣货任务同步上游波次号段，按“一单一波一槽口”处理且不补单；推出库单继续走标准集波链路，待上游推单接口联调。
- 同工作站不混做不同订单类型已在后端入口落地：集波前通过已占用格口关联 Shopee 波次反查当前工作站作业出库类型，发现其它类型时返回 `MSG_WRM_0014` 并记录系统处理日志。
- 出库单结构分类 `shipmentCategory1` 已按 `SSSQ`、`SSAQ`、`MSAQ`、`MSSQ` 口径自动分析，其中 `SSSQ` 与 `Same SKU Same Qty` 视为同一逻辑。

当前仍待实现的内容：

- `WAVE_RULE_FIELD_MATCHING` 的 `Include / Exclude / Only`、SKU 维度聚合和区间高级语义。
- ESS 合波校验真实接口契约联调；当前已有常见失败订单结构的基础解析，新增测试类已按要求删除，后续以真实联调验证为准。
- 上游号段申请、库存不足踢单上游撤单接口和任务头字段完整回写验证。
- 轮询补单已具备计划任务入口、USED 格口扫描、`SSSQ`/非 `SSSQ` 分支、ESS 校验和失败过滤能力；后续仍需按真实波次状态、连续空轮条件和接口响应做联调细化。
- 单品单件 `SSSQ`，也就是 `Same SKU Same Qty`，的动态加单和换箱换波已落地本地闭环；真实 Flow Pick 封箱/换箱接口失败处理仍待联调。
- 推拣货任务和推出库单的上游推单接口联调。
- 上游接口联动与异常回退。

## 主题汇总

### 基础数据与规则

- 规则表：`wave_rule`
- 波次号段表：`shopee_wave`
- 规则优先级：`wavePriority`
- 数据字典：`WAVE_RULE_FIELD_MATCHING`
- 最大订单数：
  - `wave_master.maxShipments`：`wave_master` 内部字段，只用于波次创建阶段的截单，不参与可用出库单查找逻辑；未配置时默认最多取 100 单，且必须满足 `minShipments` 才会创建波次。
  - `wave_rule.maxShipments`：规则级单次抓单上限，当前已在 `WaveRuleMatchService#findAvailableShipments` 中作为候选单数量限制使用。
  - `shopee_wave.status`：状态值使用 `100/200/900`，分别表示未使用、使用中、使用完成。
  - `low_threshold`：`WAVE` 系统参数，仅 `SSSQ` 单品单件 wave rule 使用，默认 `0` 表示不启用低阈值拦截。

### 出库单与任务字段

- 出库单：`cutOffTime`、`purchaseTime`、`orderTime`、`shopeeWave`、`kickOutWave`
- 出库单头结构分类：`shipmentCategory1`
- 波次：`waveRule`
- 工作站任务头：`shopeeWave`、`waveRule`
- 分拨墙格口：`waveRule`、`currentWaveRule`、`shopeeWaveCode`
- 波次匹配引擎：`wms-automation/WaveRuleMatchService`（当前主入口为 `workstationId + 出库类型`，按规则逐条查单、按格口绑定 Shopee 波次并返回分配结果）

### 主题文档

- [Shopee Automation Vendor 接入协议手册出库模块映射 WES 字段 V1.2](出库单接口文档/Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md)
- [Shopee 出库接口 WES 字段映射实现计划](superpowers/plans/2026-06-04-shopee-outbound-api-wes-mapping.md)
- [出库集波改动计划](SHOPEE_010_出库集波V1.2_改动计划.md)
- [待办事项](SHOPEE_010_出库集波V1.2_待办事项.md)
- [工时评估拆分](SHOPEE_010_出库集波_工时评估拆分.md)

## 模块对应

- `wms-wave`：波次规则、号段管理、波次主流程。
- `wms-wave-config`：波次规则配置与静态定义。
- `wms-shipping`：出库单头字段扩展。
- `wms-task`：任务相关波次字段。
- `wms-automation`：分拨墙和工作站任务联动字段。

## 当前状态

- 计划文档已同步当前真实状态，已落地内容与待重建内容已分开。
- `WaveRuleMatchService` 当前已承担规则查询、基础订单池查单、`WAVE_RULE_FIELD_MATCHING` 字典基础匹配、格口分配、Shopee 波次绑定、ESS 拒单基础解析、轮询补单和 `SSSQ` Flow Pick 本地换箱换波；高级字段语义和真实上游接口仍需继续补齐。
- 出库单候选查询与格口候选查询拆开维护，避免把查单和查格口混为一体。
- 代码字段和迁移脚本已补齐基础结构。
- 当前使用 JDK 25 执行 `:wms-automation:compileGroovy` 作为主验证方式；不保留新增测试类，Gradle problems report 文件冲突时需使用 `--no-problems-report`。