146 lines
17 KiB
Markdown
146 lines
17 KiB
Markdown
# 排车流程修复规划
|
||
|
||
本规划覆盖海外仓预排、客户排车、共享车次、PDA 拣货出库、派送及撤销之间的衔接。目标是修复取消后的占用死路、派送状态旁路、换标漏排及合托来源识别，补齐与服务端一致的前端操作入口。
|
||
|
||
2026-10-18 用户明确：当前规划对话只维护文档和分工，由指定的三个修复对话实施。本文是修改目标、文件边界和验收要求，不表示修复完成。部署状态、实际验证结果和未关闭环境验收项继续唯一维护在[测试环境主契约](../测试环境单机部署与配置契约.md)及适用的[统一认证与服务通信契约](../统一认证与服务通信契约.md)。
|
||
|
||
## 一、保持的业务主链
|
||
|
||
1. 从入仓单或已确认可出库的换标货选择托盘，创建预排分组和客户排车单。
|
||
2. 同起运仓的客户排车关联共享车次，分配车辆、司机和卸货站；跨客户共车保留各自库存与费用归属。
|
||
3. 每张客户排车单分别完成调度审核，PDA 才能拣货并逐明细核平。
|
||
4. 转派送可在待发车、拣货中或待发车就绪阶段执行，须早于发车；生成一张出库单和按目的地拆分的派送单，费用按原覆盖及外接约定复核。
|
||
5. 确认实际装载并通过理货审核，PDA 按车次统一发车；任一子单失败，全车事务回滚。
|
||
6. 签收或真实退回核平后结案，车辆、司机分别记录实际结束事实并释放。
|
||
|
||
本批保留预约稳定批次、逐票分配、工作事项通知、真实来源、客户隔离和仓绑定，不改为独立排车直接发车，不引入自动路线优化或换标分批履约新功能。
|
||
|
||
## 二、必须修复的问题与落点
|
||
|
||
下列路径中的 `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`，保持当前分支。任务身份与授权集中维护在[独立任务协作登记](../独立任务协作登记.md)。
|
||
|
||
| 对话 | 唯一职责 | 写入范围与交付 |
|
||
| --- | --- | --- |
|
||
| 排车修复 | 后端实现和代码集成负责人 | 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、部署或环境数据修改。
|
||
|
||
## 五、依赖顺序与交付门槛
|
||
|
||
1. 后端先冻结取消路径、人工派送动作、整单换标集合校验及最小能力字段；前端可先处理不依赖接口的错误提示和误导文案；审查任务先建立连续场景与缺口清单。
|
||
2. 前端只按实际后端契约接入；新增/改名/删除接口或访问域时，由后端同步 Controller、DTO、OpenAPI、权限及 Gateway 合同，不以 Mock 通过代替真实契约。
|
||
3. 三个执行者交付精确文件清单、修改行为、验证命令和限制。审查绑定稳定差异/哈希；审查期间相关文件停止修改，发现由原唯一写者修复。
|
||
候选冻结是复审交接点，不能代替本批完成。有已知失败时区分测试夹具、生产缺陷和环境待验，交给唯一写者继续处理；不得删除有效正向断言或把仍可离线验证的事项全部转成环境待验。测试作者先修自有夹具并明确停止写入，后端负责人再运行；各自阶段结果与下一依赖在本对话明示。
|
||
4. 至少覆盖 DR-01 至 DR-03 的完整连续场景，以及 DR-04 两种合托来源、DR-05 状态/权限一致、DR-06 草稿失败恢复。失败、重放、并发和客户隔离不只检查最后状态，还要检查单据、占用、库存和费用副作用。
|
||
5. 后端负责人运行受影响测试及会编译测试源码的检查，前端运行相邻测试、类型检查和应用要求的完整门禁；API/Mapper/索引变化按适用指引补门禁。未改输入不重复跑无关检查。
|
||
6. 本地实现、离线测试、独立审查、环境部署、真实 HTTP 和人工视觉验收分别报告。页面视觉留待用户提供 1920×1080、100% 截图；本轮不自行生成“视觉通过”结论。未经后续环境授权，不安排部署或写入式验收脚本执行。
|
||
|
||
## 六、执行者回报格式
|
||
|
||
每个对话在自身最终回复列明：处理的 DR 编号；实际改动文件与关键行为；接口/Schema/权限是否变化；已运行命令和结果；独立审查发现与未处理项；需要其他写者配合的精确文件或契约；建议部署单元及尚未执行的环境验收。不要把计划写成已实现，不复制密钥、Token、环境凭据或客户数据。
|