Files
ttx-project-doc/SHOPEE_010_出库集波V1.2_待办事项.md
T

23 KiB
Raw Blame History

SHOPEE_010 出库集波 V1.2 待办事项

本文按 C:\Users\zoe\Downloads\SHOPEE_010_出库集波V1.2.docx 重新整理,状态以当前代码实现为准。

一、当前已落地

模块 已落地内容 说明
基础表 wave_ruleshopee_wave 已通过 V3_1_2_3__shopee_outbound_wave_create.sql 创建基础表,并合入 groupKey 字段;ticketType 保留用于单据细分。
规则实体 WaveRuleShopeeWave WaveRule 已删除 orderStructuremaxSkuPiecesPerOrdermixModeMaxSkuPiecesFilter 字段。
波次字段 wave.waveRule 内部波次记录当前命中的 wave rule。
出库单字段 ticketTypepickTypegroupKeycutOffTimepurchaseTimeorderTimeshopeeWavewaveRulekickOutWave ticketType 用于单据细分,pickType 用于拣选类型,groupKey 用于同波次特征一致性。
格口字段 wcs_sorting_wall_cell.waveRulecurrentWaveRuleshopeeWaveCode 支持格口绑定多个 wave rule,并记录当前执行规则和 Shopee 波次号。
任务头字段 wcs_work_station_pick_task_header.shopeeWavewaveRule 字段已补齐,完整回写链路仍需结合任务生成结果验证。
系统参数 WAVE/low_threshold 仅单品单件 wave rule 使用,低于阈值触发补单判断。
工作站入口 findBestMatchedRuleByWorkStationAndOutboundType 支持工作站编码入口和 workstationId 入口。
并发控制 Redis 锁 锁粒度为仓库、工作站、出库类型,避免同一工作站并发重复集波。
工作站类型隔离 hasDifferentActiveShipmentType 入口层已校验同工作站不可混做不同出库类型,命中时记录系统处理日志并返回 MSG_WRM_0014
规则优先级 wavePriority desc 高优先级规则不足 maxShipments 时仍优先消费该规则下可匹配订单。
抓单排序 prioritycutOffTimepurchaseTimeorderTime 同一规则内按优先级和时间排序,时间越早越优先。
波次类型口径 wave_rule.waveTypeshopee_wave.waveTypeshipment_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#createInternalWaveShipmentHeaderService#addMultipleToWaveWaveService#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 字段 userDef1shipmentCategory1priority
value1 规则字段,即 wave_rule 字段 channelIdshopIdurgentFlag
value2 匹配条件 IN=EQLE<=

当前支持的匹配条件:

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 字段 shipmentTypeticketTypepickTypesourcePlatformsourceErperpOrderTyperoutecarrierCodeshipmentSubTypeshipmentCategory1-8shipToCountryshipToStateshipToCityshipToDistrictshipToTownshipToCountryCodeshipToStateCodeshipToCityCodeshipToDistrictCodeshipToTownCodehostCompanyCodestoreCodeshipObjTyperequestedDeliveryTypepriorityuserDef1-8
wave_rule 字段 channelIdfulfillmentChainIdorderSizeskuSizeTypecategoryLevel1IdshopGroupshopIdurgentFlagouterPackagingouterPackagingIddeliveryRegionfragileliquidhighValuebatterydanger

配置示例:

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 换箱接口 WaveRuleMatchServicerequestFlowPickSealBox/requestFlowPickChangeBox 已动态调用占位;本地换波闭环(字段回写/格口切换)已实现,待真实接口接入和联调。
待确认 推拣货任务与推出库单区分标识 docx 要求两类单据入口分流,上游需提供标识。

3.2 Wave Rule 字段与页面能力

状态 待办 说明
待实现 Dropdown 字段支持 All、多选、模糊搜索 涉及 channelIdfulfillmentChainIdorderSizeshopGroupshopId 等字段。
待实现 Input 字段支持输入多个值 shop_id 文本输入。
待实现 Include / Exclude / Only 语义 docx 中 SKU SizeL1 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.waveTypeshopee_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.shopeeWavewaveRule 需结合任务生成结果验证。

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 复用 assignToCellbindShipmentShopeeWave
部分落地 补单失败过滤 被 ESS 拒绝的单继续写 kickOutWave,同波次后续抓单过滤;库存不足踢单不写 kickOutWave
已落地 补单成功自动加内部波次并运行 单格口补单成功后创建内部波次,调用 addMultipleToWaveWaveService#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 包含 XSCKMTORTSRT;当前已在 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,其他值域说明仍需补齐。