huachuang/docs/superpowers/specs/2026-08-05-empty-box-transport-design.md

空木箱出入库设计规格

目标

在 WMS 中增加空木箱入库、出库及任务回调能力。木箱规格统一读取 wms_boxtype，实际木箱保存在 wmw_boxinfo，仓位通过锁类型避免并发重复分配。

方案比较

1. SQL 完成全部选位与锁定：数据库往返少，但同规格同排、新排回退和并发重试会形成复杂 SQL，后续调整策略困难。
2. 加载全部仓位后由 Java 选位：规则直观，但仓位量增长后内存和数据库传输成本较高。
3. SQL 筛选有限候选排，Java 执行优先级，条件更新抢锁：兼顾性能、并发安全和规则可维护性。

采用方案 3。Mapper XML 只返回少量候选排或候选木箱，Service 按优先级逐个尝试条件更新；更新行数为 0 时继续下一个候选。

数据模型

木箱规格表 wms_boxtype

字段为：

• id：主键。
• material_code：木箱规格编码，业务唯一。
• material_name：规格名称。
• lash_num：捆扎次数。
• box_length、box_width、box_height：长、宽、高。

空木箱业务只通过 material_code 接收规格，名称、尺寸和捆扎次数均从该表读取，不信任调用方传入的规格属性。

木箱实例表 wmw_boxinfo

保留现有字段，并增加：

• status：0 待入库、1 在库、2 已出库。
• out_time：实际出库完成时间，未出库时为空。

insert_time 表示实际入库完成时间。创建入库任务时先生成待入库记录；任务完成后写入实际入库时间并改为在库。出库完成后保留记录，更新状态和出库时间。

仓位锁

在字典 wms_lock_type 增加：

• 8：木箱入库锁。
• 9：木箱出库锁。

锁定时将任务预占码写入 task_code，任务创建成功后替换为任务 ID。完成或取消时必须同时清空 task_code 并恢复未锁定状态。

模块边界

• nl-module-wms-api：提供其他模块可调用的 EmptyBoxApi、请求对象和响应对象。
• nl-module-wms-server：提供控制器、规格和木箱 Mapper、仓位候选 SQL、空木箱领域服务及 EmptyBoxTask。
• nl-module-task-api：复用现有任务创建、下发和目的点未完成任务数接口，不修改任务模块内部业务。
• nl-module-base-api：复用编码生成接口，通过规则编码 BOX_CODE 生成木箱编码。

任务回调类只转发 taskId，完成与取消的事务逻辑封装在空木箱 Service 中。

入库流程

1. 接口接收 deviceCode 和 materialCode，校验木箱规格存在。
2. 查询候选排：第一优先级为已经存放同规格空木箱、没有其他规格木箱和实载载具且仍有空仓位的排；第二优先级为整排没有载具的排。
3. 每个候选排只查询一个可用仓位，使用 lock_type = 1、载具为空作为条件更新为木箱入库锁。并发抢锁失败时尝试下一候选。
4. 调用 BOX_CODE 生成木箱编码，根据规格表属性插入状态为待入库的 wmw_boxinfo。
5. 创建并下发任务：起点为 deviceCode，终点为目标仓位编码，载具编码为新木箱编码，业务处理器为 EMPTYBOXTASK。
6. 任务完成后，将木箱编码绑定至仓位，数量置为 1，仓位解锁；木箱状态改为在库并写入实际入库时间。
7. 任务取消后解锁仓位，并物理删除对应的待入库木箱记录。

任一步骤异常都回滚本地事务；远程任务创建或下发失败时抛出业务异常，依赖现有任务回滚接口处理已创建任务。

出库流程

1. 接口接收 materialCode，只查询状态为在库、已绑定可用仓位且仓位未锁定的同规格木箱。
2. 按 insert_time 升序、box_id 升序取得有限候选，逐条通过条件更新增加木箱出库锁；并发抢锁失败时继续下一条。
3. 当前临时出库点为 ZXQ_01 和 ZXQ_02。负载计算为“对应点位未完成任务数 + 点位当前占用库存数”，选择负载较小的点位，相同则选择 ZXQ_01。
4. 点位占用库存数暂由 WMS 内部扩展方法获取。代码保留清晰扩展标记，后续替换为 LMS 接口同时返回候选出库点及其占用情况，不改变空木箱业务主流程。
5. 创建并下发任务：起点为木箱所在仓位，终点为选定出库点，载具编码为木箱编码。
6. 任务完成后解锁仓位并清空载具编码和数量；木箱状态改为已出库并写入 out_time，历史记录保留。
7. 任务取消后只解除仓位锁，木箱记录仍为在库且继续绑定原仓位。

对外接口

• 入库创建：请求包含 deviceCode、materialCode；响应包含 taskId、boxNo、targetStructCode。
• 出库创建：请求包含 materialCode；响应包含 taskId、boxNo、destinationPoint。

服务端管理接口复用相同请求和响应语义。所有参数使用注解校验，对外 API 类型放在 WMS API 模块。

一致性与异常

• 未找到规格、候选排、空仓位或可出库木箱时抛出明确的 ServiceException。
• 仓位锁使用带原状态条件的更新保证并发安全，不使用“先查后无条件更新”。
• 木箱完成或取消回调必须按任务 ID 精确匹配一个锁定仓位；匹配数量异常时拒绝静默成功。
• 重复完成或重复取消属于幂等冲突，抛出业务异常以暴露任务状态不一致。
• 所有查询和更新 SQL 写入 Mapper XML，不使用 @Select、@Update。

验收范围

• 同规格排存在空位时优先入同排；不存在时选择整排为空的排。
• 不同规格空木箱和带组盘记录的载具不会被安排在同一排。
• 入库创建、完成、取消均正确维护木箱状态和仓位锁。
• 出库严格按实际入库时间先进先出，并在并发条件下不会重复选择木箱。
• 出库点按任务数和占用库存数综合负载选择，并在响应中返回目的点。
• 出库完成后木箱历史记录仍可查询，仓位已清空。
• WMS 模块编译通过，Mapper XML 可正常加载。