FTC25009/docs/superpowers/specs/2026-07-16-dense-outbound-relocation-dispatch-design.md

密集库出库补偿、移库与指定通道作业设计

1. 目标

在不改变现有入库流程和非密集库出库规则的前提下，完成以下能力：

1. 出库作业下发 WCS 失败后自动补偿，最多自动重试 5 次，耗尽后支持人工下发。
2. 所有 03 密集库出库与移库作业在下发前都必须是所在通道当前最外侧作业。
3. 指定托盘和指定货位出库遇到遮挡时，自动生成 in_or_out=23 的移库作业。
4. KPI 货位平面图支持按通道、数量和目标通道生成同层移库作业。
5. 新增指定通道出库菜单，按通道组查看库存并按端头托盘数量生成出库作业。
6. 入库、普通出库、指定货位/通道出库和移库使用不同的 WCS 接口配置。

2. 现状约束

• 后端为 RuoYi Maven 多模块项目，出库作业与入库作业共用 mydo_job、mydo_job_detail。
• 作业归档过程存在 INSERT ... SELECT *，直接给 mydo_job 增加字段会同步影响活动表、归档表和多个存储过程。
• 03 仓的一个通道由同一排、同一层、同一通道带的 group_coding 标识。
• bas_cargo_area_config.direction_type 是入库由深到浅的货位选择方向：方向 1 为列号从小到大，方向 2 为列号从大到小。
• 当前出库代码错误复用了 sendPutawayTask 配置键；本设计改为按作业类型路由。
• 当前 WCS 模拟开关默认开启，真实联调时必须显式关闭。

3. 总体架构

采用“业务作业 + WCS 下发记录”的 Outbox 结构：

• mydo_job 继续保存业务作业，不增加补偿字段。
• 新表 wcs_job_dispatch 与作业一一关联，保存下发状态、重试次数、错误、时间和并发版本。
• OutboundDispatchService 是所有出库、指定货位、指定通道和移库作业下发 WCS 的唯一入口。
• DenseLaneService 负责密集库通道顺序、遮挡托盘、最外侧资格和移库目标货位选择。
• RelocationJobService 负责自动/人工移库作业生成和 WCS 完成后的库存搬移。
• Quartz 每分钟调用 WcsOutboundRetryTask.retryFailedJobs() 执行自动补偿。

所有入口统一调用同一套下发资格检查，前端按钮、定时重试和分配后即时下发不能绕过密集库最外侧规则。

4. WCS 下发记录

新增表 wcs_job_dispatch：

字段	类型	说明
job_id	nvarchar(255) PK	对应作业 ID
dispatch_status	nvarchar(20)	PENDING、SENDING、BLOCKED、RETRY_WAIT、SUCCESS、EXHAUSTED
auto_retry_count	int	已执行的自动重试次数，范围 0 至 5
manual_retry_count	int	人工下发次数
last_error	nvarchar(1000)	最后一次失败或等待原因
last_attempt_time	datetime2	最后一次实际调用 WCS 时间
next_retry_time	datetime2	下次允许自动重试时间
success_time	datetime2	下发成功时间
version_no	int	并发抢占版本
create_time	datetime2	创建时间
update_time	datetime2	更新时间

初次下发失败不计入自动重试次数，状态设为 RETRY_WAIT、auto_retry_count=0。定时任务每调用一次前递增自动重试次数，失败达到 5 次后设为 EXHAUSTED。人工下发只递增 manual_retry_count，不重置自动重试次数，也不会重新进入自动队列。

密集库作业因不是当前最外侧而未调用 WCS 时，不计失败、不增加重试次数，记录统一设为 BLOCKED 并写入等待原因。外侧作业完成后立即唤醒同通道 BLOCKED 记录；定时任务每分钟复查一次 BLOCKED 记录作为异常恢复兜底。

通过原子状态更新把记录抢占为 SENDING，防止定时任务、人工按钮和业务线程并发重复下发。超过发送超时时间仍为 SENDING 的记录允许重新进入补偿流程。WCS 以 taskNo 作为幂等键；重复报文必须返回同一任务的成功确认。

5. 下发状态流转

5.1 分配后即时下发

1. 出库分配或作业生成事务提交。
2. 创建 PENDING 下发记录。
3. 调用统一下发服务。
4. 资格不满足：转为 BLOCKED，业务接口返回作业已生成、等待外侧作业完成。
5. WCS 调用失败：记录 RETRY_WAIT，业务接口返回作业已生成、WCS 下发失败并进入补偿队列。
6. WCS 调用成功：记录 SUCCESS，作业状态改为 3，执行阶段改为 1，写入开始时间。

分配成功后不因 WCS 网络失败回滚库存预占和作业生成，避免操作员重复分配。数据库分配失败仍按现有事务回滚。

5.2 自动重试

• Quartz 每分钟扫描 RETRY_WAIT 且 auto_retry_count < 5、next_retry_time <= 当前时间 的记录，同时复查 BLOCKED 作业是否已经成为最外侧。
• 每批按创建时间处理，单批数量可配置，默认 100。
• 重新执行作业存在性、作业状态、密集库最外侧和 WCS 路由检查。
• 网络或业务失败采用固定 1 分钟间隔；第 5 次失败转为 EXHAUSTED。
• BLOCKED 复查和最外侧资格不满足都不消耗重试次数。

5.3 人工下发

• 出库作业管理对 PENDING、RETRY_WAIT、EXHAUSTED 的未完成作业显示“手动下发 WCS”。
• 操作前弹出确认框，展示自动重试次数和最后错误。
• 人工下发仍执行密集库最外侧校验。
• 失败后保持原自动状态或 EXHAUSTED，更新错误和人工次数；成功后转为 SUCCESS。

6. 密集库最外侧规则

仅仓库 03 且货位存在非空 group_coding 时应用密集库规则。

• 同通道范围：warehouse_id + group_coding，group_coding 已包含排和层。
• 方向 1：入库从小列到大列，当前最外侧为所有占用/预占货位中的最大列。
• 方向 2：入库从大列到小列，当前最外侧为所有占用/预占货位中的最小列。
• 方向 3：按距离两侧边界较近者优先，同距离取较小列。
• 占用范围包括状态 2（满）、3（入库分配）、4（出库/移库分配）且托盘码非空的货位。

资格检查以事务中的实时货位数据为准，不能使用页面缓存。若同一最外侧托盘已经存在状态 2/3 的活动作业，只允许该作业继续，其他作业等待。

7. 遮挡处理与自动移库

7.1 触发范围

• 出库单分配明确指定库存明细、库存主记录或托盘时。
• 指定货位出库选择 03 仓密集库货位时。
• 指定托盘前存在其他占用托盘时。

7.2 遮挡托盘判定

按第 6 节的出库顺序，位于目标托盘外侧的占用托盘均为遮挡托盘。

• 遮挡托盘已有活动出库作业时，不再生成移库作业；该出库作业自然成为前置动作。
• 遮挡托盘没有活动出库/移库作业时，按从外到内顺序生成移库作业。
• 目标出库作业可以同时生成，但只有所有外侧货位释放后才具备下发资格。

7.3 自动移库目标

目标货位必须满足：

• 同仓库、同层、不同 group_coding。
• 状态为 1、未锁定、无托盘码。
• 符合托盘类型允许仓库和货位类型规则。
• 符合原通道的存储模式、项目号或物料相容规则。
• 不得被其他活动作业预占。

候选通道优先沿用现有入库规则：优先已有相容库存的通道，再按占用数量和通道编码选择；通道内按入库方向选择最深可用货位。生成作业后将源货位置为 4，目标货位置为 3 并预留托盘码。

8. 移库作业

• in_or_out=23，任务号调用 util_serial_task '23'。
• 主作业的 cargo_space_id 为源货位，target_cargo_space_id 为目标货位。
• 每个托盘生成一个移库主作业；按库存明细生成对应 mydo_job_detail，保留库存、批次、项目号和数量追溯。
• 移库作业使用独立 WCS 路由，不进入 PDA 出库确认列表。

WCS 完成移库回调后，在一个数据库事务内：

1. 锁定移库作业、源货位、目标货位和托盘库存。
2. 校验作业类型为 23、作业已下发、源目标仍与作业一致。
3. 将该托盘所有 bas_stock.cargo_space_id 更新为目标货位。
4. 源货位置为 1 并清空托盘码，目标货位置为 2 并保留托盘码。
5. 作业及明细归档并从活动表删除。
6. 事务提交后触发同源通道下一条等待作业的资格检查和即时下发。

重复完成回调通过活动/归档作业查询实现幂等，已完成时返回成功。

9. KPI 货位平面图指定移库

仅在 03 密集库视图显示“指定移库”命令。弹窗包含：

• 当前层，只读。
• 源通道选择，只列出当前层有满货位的通道。
• 移库托盘数量，范围 1 至源通道当前可移动托盘数。
• 目标通道选择，只列出当前层具有足够相容空位的其他通道。
• 外侧托盘预览，展示托盘码、源货位、库存明细和总数量。

提交时后端重新锁定并验证通道、层、数量、库存与目标容量，按外到内选择源托盘并生成移库作业。页面数据只用于预览，不作为作业生成依据。

10. 指定货位出库

现有非密集库逻辑保持不变。03 密集库指定货位出库调整为：

1. 锁定目标货位和通道。
2. 计算外侧遮挡托盘。
3. 为没有活动出库作业的遮挡托盘生成移库作业。
4. 生成目标托盘的指定货位出库作业及下发记录。
5. 先尝试下发当前最外侧移库/出库作业；目标作业等待通道逐步清空。

11. 指定通道出库

在出库管理下新增“指定通道出库”菜单和权限：

• out:denseLaneOutbound:list
• out:denseLaneOutbound:preview
• out:denseLaneOutbound:generate

列表仅查询 03 仓 group_coding 非空且至少存在一个状态 2 满货位的通道，展示：

• 通道组编码、货区、排、层和方向。
• 满托盘数量、可出库托盘数量、库存总数量。
• 聚合库存摘要和可展开库存明细。
• 当前最外侧托盘及货位。

生成弹窗要求选择整托数量和适配出库口。后端按当前外侧顺序选择前 N 个未被活动作业占用的托盘，返回预览供确认，确认后每托生成一个指定出库作业和完整作业明细。任何托盘状态变化都会使旧预览失效，提交时重新校验并返回明确冲突信息。

12. WCS 路由

配置增加独立键并允许通过环境变量覆盖：

external:
  systems:
    WCS:
      apis:
        sendPutawayTask: ${WCS_PUTAWAY_PATH:/wcs/api/receiveWmsJob}
        sendRetrieveTask: ${WCS_OUTBOUND_PATH:/wcs/api/receiveWmsOutJob}
        sendLocationOutboundTask: ${WCS_LOCATION_OUTBOUND_PATH:/wcs/api/receiveWmsLocationOutJob}
        sendRelocationTask: ${WCS_RELOCATION_PATH:/wcs/api/receiveWmsMoveJob}

路由规则：

• in_or_out < 20：sendPutawayTask。
• in_or_out = 20：sendLocationOutboundTask，覆盖指定货位和指定通道整托出库。
• in_or_out = 23：sendRelocationTask。
• 其他 in_or_out >= 20：sendRetrieveTask。

所有接口继续按作业所属仓库解析独立 WCS 根地址。

13. UI 设计

沿用现有 Vue 2、Element UI 和 RuoYi 页面密度：

• 出库作业列表增加“WCS 下发状态”“自动重试”“最后错误”列；错误使用 tooltip，避免撑高表格。
• “手动下发 WCS”使用发送图标和确认对话框，仅对允许状态显示。
• KPI 平面图在密集库工具栏增加移库命令，使用紧凑表单弹窗，不改变平面图颜色体系。
• 指定通道出库采用筛选栏、通道表格和单层生成弹窗；库存明细使用表格展开行，不嵌套装饰卡片。

14. 数据库迁移

新增一份可重复执行的 SQL Server 迁移脚本，包含：

• 创建 wcs_job_dispatch、状态/重试索引和字段说明。
• 确认 bas_task_no 存在 ID 23，存在则保留当前序号，不存在则补充移库类型。
• 新增指定通道出库菜单、按钮权限和角色授权兼容处理。
• 新增 Quartz 任务记录，调用 wcsOutboundRetryTask.retryFailedJobs，Cron 为每分钟一次，禁止并发。
• 为密集库通道、活动作业和下发扫描补充必要索引，创建前检查同名索引。

迁移不修改或删除现有业务数据，可重复执行。

15. 错误处理

• WCS 网络失败、超时、非成功响应和报文序列化失败均写入下发记录。
• 最外侧不满足、前置作业未完成和目标货位状态变化属于等待/并发冲突，不消耗自动重试次数。
• 自动移库目标不足时，原出库分配整体失败，不生成部分移库作业。
• 人工指定移库目标容量或相容性不足时，整个请求回滚。
• 移库完成时源目标或库存不一致，事务回滚并返回明确错误，不做部分库存搬移。
• 菜单生成作业时预览已过期，返回刷新提示，不自动替换为其他托盘。

16. 测试与验收

16.1 后端单元与 Mapper 测试

• 首次失败进入补偿队列且自动次数为 0。
• 自动重试恰好最多执行 5 次，第 5 次失败后耗尽。
• 人工下发超过 5 次仍可调用，但不会恢复自动队列。
• 调度并发抢占只有一个调用者成功。
• 非最外侧作业不调用 WCS且不增加重试次数。
• 方向 1、方向 2 的最外侧和遮挡集合正确。
• 指定托盘/货位遮挡时按外到内生成类型 23 作业。
• 自动目标同层、不同通道、相容且按入库规则选深位。
• 移库完成原子更新库存、源目标货位并归档。
• 指定通道预览与生成只选择端头 N 个托盘。
• 20、23 和普通出库分别命中正确 WCS 配置键。

16.2 前端验证

• 出库作业列表正确显示状态、次数、错误和人工按钮权限。
• KPI 指定移库只能选择同层目标通道，数量和容量校验提示明确。
• 指定通道出库列表、展开明细、预览数量和生成确认可用。
• 生产构建通过，桌面和常用窄屏下表格、弹窗无文字遮挡。

16.3 集成场景

1. 构造 WCS 连续失败，验证初次调用加 5 次自动重试后耗尽。
2. 人工恢复下发，验证成功状态和作业状态更新。
3. 在方向 1 和方向 2 通道各构造三托遮挡，验证下发顺序为外到内。
4. 指定最内托盘出库，验证先生成并完成两个移库作业，再下发目标出库。
5. KPI 指定跨通道同层移库，验证库存和货位一致。
6. 指定通道出库 N 托，验证只选择端头 N 托及其完整库存。
7. 验证非 03 仓原有自动、手动和指定货位出库不受影响。

17. 需求覆盖

原需求	设计章节
失败标记、5 次重试、定时器、人工下发、最外侧校验	4、5、6
指定托盘遮挡自动移库，类型 23	7、8
KPI 平面图指定同层移库	9
出库 WCS 地址区分	12
指定货位出库遮挡移库	10
指定通道出库菜单与端头 N 托	11