17 KiB
排车流程修复规划
本规划覆盖海外仓预排、客户排车、共享车次、PDA 拣货出库、派送及撤销之间的衔接。目标是修复取消后的占用死路、派送状态旁路、换标漏排及合托来源识别，补齐与服务端一致的前端操作入口。
2026-10-18 用户明确：当前规划对话只维护文档和分工，由指定的三个修复对话实施。本文是修改目标、文件边界和验收要求，不表示修复完成。部署状态、实际验证结果和未关闭环境验收项继续唯一维护在测试环境主契约及适用的统一认证与服务通信契约。
一、保持的业务主链
- 从入仓单或已确认可出库的换标货选择托盘，创建预排分组和客户排车单。
- 同起运仓的客户排车关联共享车次，分配车辆、司机和卸货站；跨客户共车保留各自库存与费用归属。
- 每张客户排车单分别完成调度审核，PDA 才能拣货并逐明细核平。
- 转派送可在待发车、拣货中或待发车就绪阶段执行，须早于发车；生成一张出库单和按目的地拆分的派送单，费用按原覆盖及外接约定复核。
- 确认实际装载并通过理货审核，PDA 按车次统一发车；任一子单失败，全车事务回滚。
- 签收或真实退回核平后结案，车辆、司机分别记录实际结束事实并释放。
本批保留预约稳定批次、逐票分配、工作事项通知、真实来源、客户隔离和仓绑定，不改为独立排车直接发车，不引入自动路线优化或换标分批履约新功能。
二、必须修复的问题与落点
下列路径中的 java/ 指 ../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/，admin/ 指 ../../apps/admin-web/src/modules/overseas-warehouse/。行号以评估时源码为定位参考，开工以当前符号和实际调用核对。
DR-01 取消出库后释放排车并重新安排
触发与后果： 未拣货排车转派送，解除车次关联并取消出库后，出库记录仍关联排车。排车取消和移托只判断出库记录存在，再次转派送又重放旧取消单，形成占用死路。
主要修改位置：
java/delivery/service/DeliveryTransferService.java：cancelOutbound、transferResolved、replayTransfer。java/delivery/mapper/OutboundOrderMapper.java：findByDispatch、lockByDispatch及直接消费者。java/dispatch/service/DispatchService.java：cancel、requirePalletEditingAllowed、草稿正式锁释放。java/dispatch/fleet/DispatchFleetAdapter.java和java/dispatch/pda/service/DispatchPdaWorkflowService.java：核对取消单不可被发车、结案查询当作有效单据。admin/pages/OutboundsView.vue、admin/pages/DispatchesView.vue：取消顺序、下一步和失败提示。
本批目标： 先解除未执行车次关联，再取消出库，最后取消原排车并释放占用；货物可通过新预排重新安排。保留原取消单据、来源、费用处理与操作历史，不删除历史以绕过关联。不要求复用已取消排车重新生成出库；相同请求重放必须明确返回原取消结果，不能提示重新建单成功。活动关联判断与历史查询应分清语义，不能全局过滤取消记录后破坏审计。
通过条件： 完整执行上述顺序后，原活动排车锁和有效预约运输占用释放，原单据仍可追溯；同货物可重新预排。重复取消不重复撤销费用、不释放新排车占用；已有拣货、发车、其他客户或仍有车次关联时正确拒绝并保持事务不变量。财务作废仍以 Finance 确认结果为准。
DR-02 派送状态必须服从实际出库事实
触发与后果： 发车未自动进入派送中时，派送仍为 WAIT_DELIVERY，普通状态编辑允许直接改 CANCELLED。后续签收、退回和车次结案均受阻；提前取消派送也可能未被发车门禁发现。
主要修改位置：
java/customervisit/service/CustomerVisitService.java：updateDeliveryStatus。java/delivery/model/DeliveryStatusPolicy.java：人工状态转移和allowedActions。java/delivery/service/DeliveryTransferService.java：统一取消入口及列表/详情能力返回。java/dispatch/fleet/DispatchFleetAdapter.java：manifest、completion。java/dispatch/pda/service/DispatchPdaWorkflowService.java：发车前一致性复核。admin/pages/DeliveryOrdersView.vue、对应 API/类型及直接测试。
本批目标： 取消统一经未执行出库的聚合命令，不能由普通派送状态编辑单独制造取消终态。已出库/发车禁止直接取消；开始派送、拒签应核对实际出库事实。发车要求关联派送完整且均可执行。签收仍由合法签收资料触发，拒签仍经真实退回处理，不开放人工直接完成或任意恢复终态。
通过条件： 未出库提前开始/拒签、已发车取消均被后端拒绝且页面不提供误导入口；并发取消与发车只能有一个合法结果，不能出现已发车加取消派送。正常签收、部分退回、签收后另退货、车次结案和原键重放保持原语义。
DR-03 普通换标必须完整选择本申请托盘
触发与后果： 一张普通换标单有两托，只选一托也能预排；服务端随后把整张申请改为 PRE_DISPATCH_CREATED，剩余托盘从候选中消失。
主要修改位置：
java/dispatch/service/DispatchService.java：preArrangeRelabel。java/dispatch/mapper/DispatchCandidateMapper.java：relabelAvailable、markRelabelPreDispatched、restoreRelabelPreDispatch。admin/components/SmartDispatchDialog.vue：换标候选、提交检查和提示。
本批最小修复目标： 沿用当前整单状态机，普通换标与退货换标均须一次选择本申请全部应排托盘。服务端锁定申请后重新计算完整集合并校验，前端提示不能替代服务端检查。拒绝部分选择时不得建排车、推进申请或残留占用；不在本批扩展换标分批发运。
通过条件： 两托选一托拒绝且零副作用；完整两托成功；重复托盘、候选变更、不同申请混选正确拒绝；取消原未执行排车后可完整重排。确认前后并发提交只能产生一张有效排车。
DR-04 合托后按真实来源绑定外接货和约定运费
已确认代码缺口： 候选的入仓码为展示性单来源，箱数却为整托实际库存；sourceCargo 和外接运费预览继续用这组值识别原承运登记。同客户、同目的地的普通货与外接货合托后，存在漏识别外接来源或误报实收量不符的风险。实际整条混托发运后果尚需组合测试证明。
主要修改位置：
java/dispatch/fleet/DispatchFleetAdapter.java：sourceCargo。java/fleet/trip/FleetBookingReservations.java：bindIncoming。java/fleet/trip/FleetBookingFreight.java：preview。java/delivery/service/DeliveryTransferService.java：externalFreight。- 按实际引用核对已有
DispatchFeeCargoMapper、库存组成与拣货来源接口；需要持久查询时按现有分层新增最小 Repository/Mapper，不跨库读取。 java/palletops/service/PdaPalletOperationService.java只在证据证明需要维护承运实收的拆合托约束时修改，不扩展通用库内业务。
本批目标： 先用可执行测试固化普通来源/外接来源分别成为展示来源的两种场景。绑定和运费按实际客户、来源、目的地和本次箱数核对，展示入仓码不能替代真实组成。承运托盘证据因拆合托变化时，给出已有业务可执行的重新核对路径，不放宽承诺车次和完整实收量限制。
通过条件： 外接承诺不得遗漏或错误跨车绑定；逐来源数量守恒，容量不重复占位；约定运费不遗漏、不重复发布，普通货仍执行其独立费用规则。不能只修展示名称或把无法识别的外接货当普通货静默通过。
前端还须核对 overseas-master-data/components/TripBookingPanel.vue 的实收确认入口：服务端允许尚未绑定排车的 RECEIVED 重新核对时，页面应按相同状态、权限和车次限制开放，并复用现有确认接口、当前版本和新请求键。拆合托后的新实托、重量/体积及原承诺须重新核验，不因仅扩大按钮可见条件就认定整链完成。
DR-05 页面动作与服务端门禁一致
主要修改位置： admin/pages/DispatchesView.vue 的 canEdit/canCancel/canTransfer、移托和车次跳转；admin/pages/DispatchDetailView.vue、admin/api/dispatches.ts 及必要 DTO；派送/出库页面只沿受影响操作跟进。
本批目标： 已绑定车次、已有有效出库、已拣货等限制在进入写操作前明确展示，提供处理原车次/出库的准确入口。优先消费已有服务端能力；缺失时由后端统一补充最小动作资格与阻断原因，前端不得另建一套状态机。转派送成功重放不应冒称新生成单据。
通过条件： 列表、详情和服务端一致；只有列表权限的用户保持只读；已取消、已关联、已转派送和并发刷新场景不能出现误导性的成功提示。保留已确认页面承载方式和操作列位置。
DR-06 换标草稿锁定与恢复必须真实
主要修改位置： admin/components/SmartDispatchDialog.vue 的移入/移除、关闭重开、草稿查询错误处理及“已锁定”提示；如接入统一换标草稿锁，由后端任务独占对应 DispatchService、DTO、Mapper 和契约实现。
本批目标： 不再对仅存浏览器的换标选择显示服务端已锁定。后端先明确是否能在现有统一草稿模型中锁定该来源，再由前端接入；未持久化的选择必须明确其状态，不增加第二套占用协议。草稿读取失败显示独立错误和重试，不得用空数组伪装无草稿并丢失原选择。
通过条件： 普通、退货、换标三个来源的展示与实际锁行为相符；刷新/关窗/重开、超时、锁冲突和查询失败时原选择及占用可解释、可恢复或明确释放；后端最终防重复能力仍保留。
三、需先证实的来源边界
RETURN_RELABEL 拣货以 returnCartonId 记账，而 ExceptionOrderService.appendDispatchPickSources 跳过无 inventoryPositionId 的拣货记录。独立审查任务应核实是否存在当前正式替代入口，并尝试用组合测试证明拒签后能否取回原箱来源。
如确认缺口，由后端任务在既有异常退回链中补真实来源、客户/数量校验及原子入账，前端只接入同一候选契约；不可虚构普通库存仓位替代退货箱。尚未证实前不登记为普通排车全局故障，也不扩展一整套新退货流程。
PLAN 提前预排能力、自动配车优化、换标分批和页面全面重做不在本批实施范围；发现相关事实时只记录依赖或另列业务决策。
四、三个对话的唯一分工
所有任务固定使用 TEST 项目 c64729ff-6710-43c6-8ef2-d84e9666cc1e、host local、工作目录 C:/Users/BY-OY/Desktop/code/chongchong-global，保持当前分支。任务身份与授权集中维护在独立任务协作登记。
| 对话 | 唯一职责 | 写入范围与交付 |
|---|---|---|
| 排车修复 | 后端实现和代码集成负责人 | DR-01 至 DR-06 涉及的 Lastleg 生产代码、直接测试、DTO/OpenAPI及必要数据库结构定义；先修前三项，再收口已证明的来源问题。唯一维护共享后端文件、后端契约和必要公共测试支撑；组织串行 Maven 检查。不得修改前端或本规划。 |
| 排车修复-2 | Admin/PDA 前端实现 | 本文列出的海外仓页面、组件、API/类型和相邻测试；必要时沿公开入口修改车次组件、海外 PDA 门禁消费。先修独立草稿错误提示，再接入稳定后端契约。不修改后端和共享基础样式，不扩大到预约页面。 |
| 排车修复-3 | 独立审查和连续场景回归 | 只读审查后端/前端差异；唯一可新增或修改 baiyue-firstleg/lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/service/DispatchRepairWorkflowTest.java。该文件先核实不存在其他写入者；不改生产代码、已有测试、共享 fixture、POM、SQL或前端。回归使用现有测试框架与真实被测行为，不能用替身把待验证门禁模拟为成功。 |
当前规划对话唯一维护本规划、协作登记和最小文档路由，读取三个对话的交付，不接管代码、SQL或构建。各执行者在自己的对话报告；可只读查看本批另外两个指定对话的进展及冻结交付，避免等待已经具备的输入。本轮未授权它们主动向其他对话发消息，接口与测试窗口由规划对话转达。独立审查不等于真实环境验收。
文件重叠与并行事项
- 先读取各自适用 AGENTS 和当前差异，保留所有未提交修改。
DispatchService、DeliveryTransferService、DispatchFleetAdapter等后端热点始终只由“排车修复”写入；前端热点只由“排车修复-2”写入；独立组合测试只由“排车修复-3”写入。 - 本批最新分工仅适用于本文缺陷，不接管预约核心、工作事项、来源同步性能或其他在行任务。不得删除已有预约批次分配和工作通知接线。
- 派工时已知“预约”对话正在执行固定 18 文件的提交、TEST Lastleg 发布及有限采样。其环境授权不传递给本批。开工重新核对活动写者、实际差异和构建进程；与活动任务重叠的文件或共享构建先保持只读，继续无冲突工作并报告精确范围，不能覆盖或使用全目录暂存混入其发布。
- 后端 Maven 仅由“排车修复”执行，运行前确认没有其他任务占用同一后端构建目录；独立测试作者交付代码后停止写入，负责人再统一编译执行。Admin检查由“排车修复-2”执行，避免同应用并行全量构建。
- 公共 IAM、统一 SQL、Gateway、根导航等共享入口不因本次派工自动转移写权。若确需调整，先交付精确变更提案，由规划对话协调唯一写者后再由代码负责人落实；规划对话自身不修改这些文件。
- 不创建新用户可见对话、分支、worktree 或项目副本；不复制依赖，不提交或推送，不启动本地服务，不执行 SQL、真实 HTTP、部署或环境数据修改。
五、依赖顺序与交付门槛
- 后端先冻结取消路径、人工派送动作、整单换标集合校验及最小能力字段；前端可先处理不依赖接口的错误提示和误导文案；审查任务先建立连续场景与缺口清单。
- 前端只按实际后端契约接入；新增/改名/删除接口或访问域时，由后端同步 Controller、DTO、OpenAPI、权限及 Gateway 合同，不以 Mock 通过代替真实契约。
- 三个执行者交付精确文件清单、修改行为、验证命令和限制。审查绑定稳定差异/哈希；审查期间相关文件停止修改，发现由原唯一写者修复。 候选冻结是复审交接点，不能代替本批完成。有已知失败时区分测试夹具、生产缺陷和环境待验，交给唯一写者继续处理；不得删除有效正向断言或把仍可离线验证的事项全部转成环境待验。测试作者先修自有夹具并明确停止写入，后端负责人再运行；各自阶段结果与下一依赖在本对话明示。
- 至少覆盖 DR-01 至 DR-03 的完整连续场景，以及 DR-04 两种合托来源、DR-05 状态/权限一致、DR-06 草稿失败恢复。失败、重放、并发和客户隔离不只检查最后状态，还要检查单据、占用、库存和费用副作用。
- 后端负责人运行受影响测试及会编译测试源码的检查，前端运行相邻测试、类型检查和应用要求的完整门禁；API/Mapper/索引变化按适用指引补门禁。未改输入不重复跑无关检查。
- 本地实现、离线测试、独立审查、环境部署、真实 HTTP 和人工视觉验收分别报告。页面视觉留待用户提供 1920×1080、100% 截图；本轮不自行生成“视觉通过”结论。未经后续环境授权，不安排部署或写入式验收脚本执行。
六、执行者回报格式
每个对话在自身最终回复列明：处理的 DR 编号；实际改动文件与关键行为；接口/Schema/权限是否变化；已运行命令和结果；独立审查发现与未处理项；需要其他写者配合的精确文件或契约；建议部署单元及尚未执行的环境验收。不要把计划写成已实现，不复制密钥、Token、环境凭据或客户数据。