195 lines
38 KiB
Markdown
195 lines
38 KiB
Markdown
# 排车列表统一作业改造契约
|
||
|
||
本契约规定排车列表五阶段、整车与客户货物归属、派送安排及 Admin 和海外 PDA 的共同目标。2026-10-19 用户确认一张排车单代表一趟车，并指定当前对话为本批总控；经逐项问答确定本契约的业务和界面基线，再下发三个任务做技术准备，共同接口冻结后才解锁生产代码实现。本契约描述目标及实施边界，不表示代码、部署或真实验收已完成；部署与真实验收事实仍维护在两份环境主契约。
|
||
|
||
本批规则优先于旧车次独立列表及多张客户排车关联共享车次的交互说明。旧缺陷修复规划仅用于核对已修复行为，不覆盖本批目标。
|
||
|
||
## 一 用户已确认的业务目标
|
||
|
||
1. 排车列表一次覆盖装车前、装车中、装车后、派送中、派送完成五个阶段。
|
||
2. 一张排车单就是一趟车，允许同车多个客户、多个目的仓；各票货物、库存、单据和费用必须保留真实客户归属。
|
||
3. 装车前包含车辆信息、调度审核、理货员审核；维护车辆信息后提交调度审核，再经理货员审核进入装车中。
|
||
4. 装车完成与实际发车是两个动作，均允许后台和 PDA 确认；两端使用相同服务端规则、版本和防重复约束。
|
||
5. 装车完成进入装车后；后台在装车后、实际发车前办理安排派送，核对派送信息及各客户费用，按客户和目的仓拆分派送单。派送安排完成后才允许后台或 PDA 确认发车。
|
||
6. 实际发车进入派送中；全部正常派送签收完成后自动汇总派送完成。拒收、退回等作为异常，先线下人工处理，不自动视为正常签收完成，不在本批新建线上异常闭环或伪造库存恢复、签收、账务结果。
|
||
7. 本批聚焦排车列表、详情、直接关联操作及必要生产者和消费者。车辆列表、司机管理、自有业务、外配业务、出车记录的整页改造后续逐页处理。
|
||
8. 同时支持先选同一起运仓的可排货物/托盘再生成排车单，以及先创建空排车单再添加货物；空单不能伪造货物、拣货、装车或发车事实。
|
||
9. 车辆和司机既可从已有档案选择，也允许临时填写外配车辆和司机；临时填写不伪造车辆或司机档案关联，不自行创建主档。
|
||
10. 后台确认装车完成必须以PDA真实拣货核平为前提。后台不提供替代PDA的拣货数量补录来绕过此条件；PDA和后台均可确认装车完成及实际发车的既有确认保持。
|
||
11. 用户随后澄清本次“新增预约”是预约日历的功能需求，先与本批排车改造分开整理。本批不新增日历预约创建或独立约车流程；排车保留已有FBA预约关联；用户随后对车辆预约权威来源问题答复“那就不要”，因此排车取消车辆预约字段、关联操作及公开协议，不再等待或新建该权威提供者。此前确认的先保存后关联意见保留为日历需求输入，不作为本批扩大实现范围的授权。
|
||
12. 用户进一步明确“本批支持整托同车”：两张换标单已合到同一实托时，整托进入同一排车主单，物理托盘及容量只计一次，各换标单的箱数、客户及扫码归属分别保留。不得只装第一来源、借第一客户承载其他来源，或把同一实托拆成两张排车绕过排他占用；此确认取代该场景的待决定状态及仅作前置拦截的候选方案。
|
||
13. 用户进一步确认：换标已由客户确认完成、关联出库单尚未扫码时，只取消本次出库安排，保留已完成的换标成果，退回待安排。不得将已确认换标申请一并作废；取消须清除本次有效出库关联，保持真实客户、原换标成果及重新安排资格。此规则不放开已扫码取消或新增回库流程，整车取消仍遵循既有阶段、版本和零扫码门禁。
|
||
|
||
## 二 原型依据与详情四块
|
||
|
||
原型为用户提供的新版 HTML，页面 `page-outbound-vehicle`、`page-outbound-vehicle-detail`，以及本轮最新排车详情截图。HTML 位于用户提供的本机原型路径，实施者沿本契约和目标模块矩阵定向读取，不扫描原型其他模块。截图最新确认优先于前一条“三块”的描述。
|
||
|
||
排车详情继续使用独立页面、页头排车单号、状态和返回入口。用户在最新确认中明确将下列四块分别作为四个彩色图标页签，样式沿用现有后台横向页签；此确认取代此前同页四分区的布局描述。原型灰色卡片仅保留业务字段依据，具体字号、密度、底色、边线与页签使用现有公共规范。不新增路线或操作记录页签：
|
||
|
||
| 分区 | 截图字段或列 | 布局 |
|
||
| --- | --- | --- |
|
||
| 车辆信息 | 车牌号、司机、联系电话、拖车公司名称、车辆状态 | 第一个彩色图标页签；紧凑字段布局 |
|
||
| 排车信息 | 路线、发车时间、预计到达时间、FBA预约 | 第二个彩色图标页签；紧凑字段布局 |
|
||
| 单据信息 | 排车单号、关联派送单、创建时间、更新时间、备注 | 第三个彩色图标页签；多单号完整展示 |
|
||
| 关联订单明细 | 订单号、重量kg、托数、目的FBA仓、体积m³、集装箱号 | 第四个彩色图标页签；通栏只读表格 |
|
||
|
||
页签复用当前详情的 `density-element-tabs`、`density-tab-icon` 及公共密度令牌，保留图标、激活底色、下划线、字号和间距的一致规则；页面不另写第二套页签样式。图标优先从现有对应语义复用，具体映射在逐操作矩阵中列明。新增、编辑和审核等操作按新版原型对应弹框分别核对，详情四页签不授权改变弹框承载方式。
|
||
|
||
原型示例编号、路线示例、日期和数量仅作为样式及字段参考，不写入真实数据或作为缺失值回退。长编号和多派送单不能省略成内部ID；缺失显示“—”。样式沿现行高密度规范，保持上述业务分组。真实视觉验收由用户在1920×1080、100%缩放下提供截图。
|
||
|
||
## 三 现有附加能力的保留边界
|
||
|
||
用户明确要求外接预订、计划容量、直接成本、在途交接、车辆和司机任务结束等能力先保留，后续再接入。本批不删除这些能力及实现，不把它们新增为排车详情分区或页签，不扩展为全面车队产品改版。
|
||
|
||
排车主流程不再要求用户先进入独立车次管理建立或关联车次。车辆管理侧栏中的“车次管理”通过hidden退出菜单，日常作业从“排车列表”进入；原车次详情路由与外接预订、容量、成本、交接、资源结束等附加代码先保留。“出车记录”是实际发车后的运营查询入口，继续保留，不与独立车次管理一起移除。既有容量、资源占用、司机证照和客户隔离等必要服务端校验须随主流程保留。技术模型收敛方案由后端提出，总控核对并冻结后实施；不能仅改页面名称而继续要求用户执行旧的多单关联流程，也不能因暂不展示资源任务结束而自动释放车辆或司机。
|
||
|
||
原附加能力的直接引用若与新主流程冲突，先列明精确调用点，由总控裁定最小接线；不自行删除旧附加能力或重做其他整页。
|
||
|
||
### 下发基线与问题处理
|
||
|
||
上述三项新增规则已经由用户逐项确认，准备任务按确认结果提出技术设计。原型未定义或代码与已确认规则冲突时，执行者列出具体场景、当前行为和最小建议交总控处理，不自行添加业务限制、删除能力或改变用户操作。
|
||
|
||
所有任务以本契约、目标模块指引、用户新版原型和最新详情/样式截图为共同输入；不把旧车次交互、历史缺陷修复终点或演示值改写成本批规则。
|
||
|
||
## 四 实施任务与唯一写者
|
||
|
||
所属项目为测试环境 `c64729ff-6710-43c6-8ef2-d84e9666cc1e`，host为local，工作区为 `C:/Users/BY-OY/Desktop/code/chongchong-global`。全部任务留在当前工作区和分支；不创建worktree、分支、项目副本或复制依赖。
|
||
|
||
总控为当前对话 `01a15230-a9d6-7503-a8a9-d70691df49e5`。旧排车对话已归档、派工未送达；用户随后明确新建三个独立任务。依后端工作量采用两个后端和一个Admin/PDA联合前端任务。技术准备和两后端交接点修订已经完成；本轮按第九节分阶段解锁，未解锁的预约在途文件及额外提供者仍保持只读。新批次不继承上一批发布、SQL或环境验收授权。
|
||
|
||
| 对话与task_id | 本批唯一职责 | 文件写入边界 |
|
||
| --- | --- | --- |
|
||
| 排车后端 `01a1524f-4f11-70c2-8a46-8e06e73a2d86` | 排车主单与货物客户归属、建单/加货、五阶段、审核、装车/发车共同执行规则；后端Maven唯一执行者 | Lastleg `dispatch/`、`fleet/trip/`及实际直接引用的Repository、Mapper、DTO与测试，`FleetBookingFreight.java`除外；不写`delivery/`及`financefee/`。后端共同接口设计文档由本任务唯一维护；File等提供者先列触点由总控分配 |
|
||
| 排车派送与费用后端 `01a1524f-56a9-7320-a5fd-8ff76fa4356b` | 装车后安排派送、按客户和目的仓拆单、费用归属/覆盖/发布及正常签收汇总事实 | Lastleg `delivery/`、必要`financefee/`、`fleet/trip/FleetBookingFreight.java`及对应测试；不写`DispatchService`、排车DTO/Mapper、`FleetTripExecutionService`。先在独占设计文件提出给主流程的事实查询与事务约定 |
|
||
| 排车前端与PDA `01a1524f-52c7-7cc3-9b08-d34ad24c172a` | Admin排车列表、四页签详情、直接弹框、API/类型、PDA装车/发车及直接测试 | Admin `overseas-warehouse`排车页面/API/类型/直接组件、`overseas-master-data`经核实的直接触点；海外PDA `src/pages/dispatch/`、`src/api/fulfillment.js`、`src/stores/fulfillment.js`及直接测试/组件。预约日历在途文件先只读列明接线，不覆盖；不写Java |
|
||
| 当前总控 | 业务范围、共同契约、任务协调、共享文件及集成检查 | 本契约、协作登记、必要索引；最终共享导航/根路由/权限/统一SQL/Gateway接线；修改前核对相关文件现有写者 |
|
||
|
||
任何任务不递归委派、不新建对话、不跨项目操作、不覆盖其他未提交修改。执行者在自身对话报告，由总控读取；收到派工不自动获得向其他对话发消息的授权。两个后端不并写同一Java类、DTO或Mapper；共同OpenAPI、权限及SQL由总控按各自提案集成。
|
||
|
||
## 五 就绪顺序与交付要求
|
||
|
||
1. 主流程后端提供共同接口和数据设计：整车编号与明细客户归属、五阶段及异常事实、每阶段可操作资格、审核/装车/发车请求、版本/幂等、历史与权限、结构变更及直接消费者。派送后端并行提出按客户目的仓拆单、费用与签收事实接口；两者先对齐主单/明细、动作资格、完成事实、事务边界与锁顺序。API路径和模型未冻结前，不让下游按猜测实现。
|
||
2. 前端任务同步完成Admin逐操作原型矩阵、字段缺口，以及PDA真实拣货、装车完成、发车和两端竞争的接口差异及回归场景。此时可并行只读分析，各任务在自身对话交付准备结果；不启动真实环境验收脚本。
|
||
3. 总控核对共同设计后更新本契约的接口补充，明确解锁各实现任务。技术例行选择不再请用户重复批准；遇到改变业务行为或截图分组的问题及时向用户确认。
|
||
4. 两个后端各自实现与自身测试，前端统筹Admin及PDA实现与测试；同一文件一个写者，后端Maven由主流程后端统一串行执行并覆盖另一后端的直接测试。共享导航/SQL/权限等由总控统一集成。
|
||
5. 交付需包含实际差异、直接消费者、已执行检查、未验证项及待发布单元。代码通过、真实HTTP通过、人工页面及PDA真机通过分别记录，不互相替代。
|
||
|
||
## 六 必须覆盖的验证
|
||
|
||
- 同一仓多个客户、多个目的仓装一车；同一目的仓不同客户的派送及费用不串客户，客户只读只能访问自己的货物和单据。
|
||
- 调度审核与理货员审核的正常通过、驳回与重提；未通过不能进入装车，改货物或关键资源后旧审核不得误用。
|
||
- 装车完成与发车分离，未安排派送不得发车；后台与PDA对同一版本同时操作只产生一次合法结果，未知结果按原请求键核对和重试。
|
||
- 全部正常签收才汇总派送完成；部分签收仍未完成，异常不伪造完成、退库或费用结算。
|
||
- 普通入仓、换标/退货来源、同托多来源及既有预约批次/工作事项的直接调用不丢来源、不重复扣库存或收费；保留上一批修复约束。
|
||
- 加载、空态、错误、无权限、附件预览及四页签长编号展示；不逐行查询列表详情或附件。
|
||
- 后端受影响测试与测试源码编译、网关路由合同、必要Mapper扫描；Admin类型检查/直接及全量测试/构建；PDA测试及H5/App资源编译按实际改动执行。
|
||
|
||
本批授权覆盖代码开发及必要离线检查。没有本轮额外授权，不提交推送、不部署、不执行环境SQL、不操作测试业务数据、不启动本地Java/Nacos/数据库。环境主契约只在存在真实证据时维护，不把本契约作为发布完成证明。
|
||
|
||
## 七 技术准备的共同对齐要求
|
||
|
||
三份独占准备文档不能代替本契约或自动解锁生产实现。准备阶段的共同对齐要求如下；本轮已按第九节明确解锁的范围进入实现，其他范围仍只读。
|
||
|
||
1. 公开写命令的版本字段统一为 `recordVersion`，包括安排派送；`expectedVersion` 如有需要仅作内部参数含义，不形成第二套公开字段或兼容别名。
|
||
2. 严格命令请求摘要与派送安排业务摘要分开：原键不能改操作者、动作、单号、原版本或载荷；另一请求键也不能重复创建同车派送或重复发布费用。全局唯一安排事实与跨操作者授权/重放边界须在两稿使用一致定义。
|
||
3. PDA已经形成的真实库存扣减与拣货来源只执行一次。安排、装车完成及实际发车不得二次扣库存；派送稿中的 `picked→shipped` 必须明确究竟更新单据计数还是执行库存命令，不能留下两种解释。
|
||
4. 正常签收资料保存维持派送到来源的原事务链，不能持子锁回头申请整车父锁。采用持久可恢复的待汇总事实，在提交后由主流程取得父锁读取已提交真实签收；两稿明确记录、消费、重试/重扫及测试的唯一写者。
|
||
5. 安排、发车、取消及扫码的实际锁点须沿代码逐一核对，明确父记录、资源、排车、客户出库/派送、来源、库存之间的具体顺序。不能各自保留一条相反序列，也不能仅靠文档宣称已无死锁。
|
||
6. 临时外配取证、实载核对、零扫码变更和客户旧创建入口按第八节用户已确认规则实施；日历新增预约按第十节留待独立整理，不再派给本批。未确认的新业务行为继续单列问题交总控，不自行扩大范围、加必填、放松校验或删除能力。
|
||
|
||
## 八 用户已确认的执行细则
|
||
|
||
用户明确回复“四项都按建议执行”，以下四项自本轮起作为开发基线；不再重复请求相同业务确认。
|
||
|
||
| 事项 | 确定规则 | 决策影响 |
|
||
| --- | --- | --- |
|
||
| 临时外配取证 | 建单人补齐本趟车辆容量、司机证照和预计任务结束，由调度审核核实；空单可先保存，审核前补齐 | 临时输入、证据上传、资格快照及审核必填；不自动建车辆或司机主档 |
|
||
| 实际装载核对 | 在确认装车弹框接入既有实载核对，有依据的实际数据自动带出，缺项再确认；保持PDA真实拣货核平前置 | 实载来源/字段/弹框及双端核验；不新增第五个详情页签，不代填拣货箱数 |
|
||
| 零扫码变更 | 保留原排车单号，显式退回装车前，修改后两级审核重提 | 新审核轮次、权限和历史；已经扫码的退装/回库不在本批新增 |
|
||
| 客户直接创建派送 | 本批整车安排仅由平台执行，客户继续查看自己的派送单，移除旧客户直接创建这类派送入口 | 派送后端移除对应Merchant创建写入口；前端任务按第九节更新Client直接消费者，保留本客户读取及合法资料操作 |
|
||
| 换标合托同车 | 同一实托可承载两张换标单的逻辑运输来源并整托同车；各来源真实箱数、客户及扫码归属保留，托盘和实际容量只计一次 | 同车内物理占用共享、跨车排他；候选、整托完整性、扫码归属、实际装载及派送/来源状态的直接契约须一致，不能只放开重复托盘校验 |
|
||
|
||
工程事项仍由总控负责：公开版本字段、请求摘要与业务摘要、真实库存扣减点、子单与来源锁序、签收持久提醒的写入和消费职责等不要求用户裁定技术细节。尚未核实的资源/预约提供者反向锁点必须在实现前补齐证据，不能用业务确认替代代码和并发验证。
|
||
|
||
## 九 工程基线与首批实现解锁
|
||
|
||
本节为总控在用户确认业务后下发的工程基线，优先于三份准备稿中仍标“待用户裁定”、旧版本字段或相反锁序的段落。精确Java/TypeScript记录、端口签名及对外Schema由唯一接口提供者先产出，消费者读取实际骨架后接入，不自行补第三套协议。
|
||
|
||
1. 采纳主流程稿的真整车主单：`ll_dispatch_order`不再以单客户头部代表全车；客户归属保留在真实货物/来源/子单。主单自动一对一关联Fleet资源记录，保留附加能力，不要求用户建立多张客户排车或操作旧绑定流程。派送采用每客户一张出库单、每客户每目的地一张派送单；公开返回完整数组，不保留单个outboundNo别名。
|
||
2. 公共主单`status=ACTIVE|CANCELLED`，`stage=BEFORE_LOADING|LOADING|AFTER_LOADING|DELIVERING|DELIVERED`，审核子流程按主流程稿第3节；取消不是第六阶段。公开版本唯一`recordVersion`，0合法。Admin/PDA均以dispatchNo识别本车；车辆/司机主档和临时填写分别使用明确mode，用户可先保存空单，审核前补齐已确认依据。
|
||
3. 公网前缀继续`/api/platform/v1/last-leg/dispatches`和`/api/pda/v1/last-leg/dispatches`。主流程API/查询统计/四页签对象采用主流程稿第4节语义，派送组合GET及整车POST采用派送稿第3节语义，依用户第八节补实载确认、零扫码退回重审及临时证据。详情仅vehicleInfo/dispatchInfo/documents/orderDetails四块；不把接口提案当已上线。
|
||
4. 采用全局唯一idempotencyKey的共同持久命令账本，绑定原主体/动作/排车及严格commandHash；同键不得换主体或载荷。安排业务另有整车唯一事实及arrangementBusinessHash，当前有权限的主体用新键、当前版本引用同一已安排业务，不再生成单据或收费；`replayed`与`alreadyArranged`语义分开。原动作结果不可变，前端随后GET当前事实。
|
||
5. 共同根锁按已核对Fleet顺序为trip→涉及的车辆主档→司机/资源→dispatch；不采用准备稿早期trip→dispatch→资源的相反序列。扫码只走来源→库存链且不取派送锁；安排/发车先收齐全部客户出库/派送锁，再取得来源/费用锁；签收保持delivery→来源→持久信号、始终不回头申请父锁。装车/安排/发车不重复执行扫码已完成的库存SHIP。未核实的预约/资源提供者交集仍须补源码和竞争测试，不宣称已证明全域无死锁。
|
||
6. 共享契约只定义在`dispatch/port/`的DTO/接口，主流程后端唯一写入。采用DispatchExecutionPort、DispatchDeliveryPort、DispatchCompletionPort及明确的提醒数据访问端口；实现分别归dispatch和delivery，不跨域共享Entity或注入对方具体Controller/Service。派送任务保存持久信号及数据访问实现，主流程负责有界消费/退避/重扫；主阶段CAS和本次已核对信号确认在同一汇总事务中完成，失败回滚，错误记录在回滚后独立短事务更新。
|
||
7. 平台新增排车、确认装车完成和确认实际发车分别使用`platform:overseas-warehouse:dispatch:create`、`platform:overseas-warehouse:dispatch:loading-complete`、`platform:overseas-warehouse:dispatch:depart`，列表/详情仍为dispatch:list，两级审核沿用既有独立审核权限。整车草稿及选货候选GET统一使用dispatch:list，草稿全部写动作统一使用dispatch:create；前端既有入仓单选货建排车入口同样核对排车查看与新建权限，不再依赖旧入仓单智能排车权限，不增加OR别名或通过补授旧权限绕过。客户仅保留本客户派送读取，不再登记或默认授予`merchant:warehouse:delivery:create`；海外PDA继续使用其独立作业角色、权限和仓绑定，不通过后台按钮权限进入作业。正式权限目录和角色关联以IAM源码及国内统一基线为准。
|
||
|
||
### 首批解锁和停止点
|
||
|
||
| 任务 | 当前允许实施 | 依赖与停止点 |
|
||
| --- | --- | --- |
|
||
| 排车后端 | 先产出公共枚举、DTO/端口精确骨架及对应编译合同，然后实施主单/来源模型、版本幂等、五阶段和审核/装车/发车本域逻辑与测试 | 公共骨架完成在自身对话提交文件/签名/哈希供总控读取；下游按骨架接入。不得擅改delivery或预约在途文件；共同SQL/OpenAPI/权限提供精确提案交总控集成 |
|
||
| 排车派送与费用后端 | 实施本域分组/单据/费用/持久提醒模型、Repository/Mapper及测试；实际整车适配读取主流程公开骨架后接入；按已确认规则移除旧merchant创建写入口 | 不更改主流程公共骨架，缺字段交总控；不执行Maven，稳定交付点把用例交主流程统一运行。不承担日历新增预约设计或实现，不抢写预约提供者 |
|
||
| 排车前端与PDA | 四页签独立详情、五阶段列表/动作弹框与双端请求按实际公共DTO接入；同时移除Client这类派送创建直接消费 | Client范围为order-management的DeliveryOrderCreateView.vue、api/deliveryOrders.ts及真实入口/直接测试，修改前读Client指引；共享路由/导航交总控。预约页面与adminDensity.test.ts在途改动保持，不承担日历新增预约矩阵；不猜API或临时兼容旧版本 |
|
||
|
||
所有任务先保留现场未提交修改；各自独占文件内可开展生产代码和必要离线验证，不提交、不部署、不执行环境SQL或真实HTTP。后端Maven仍由主流程唯一执行，测试前核对另一后端的文件稳定；中间编译/单测结果不代表全链完成。
|
||
|
||
### 当前并行收口分工
|
||
|
||
用户检查发现仅主后端执行后，总控核对两个已交付任务及实际文件，复用三个既有任务推进剩余接线，不新建任务。以下为有限实施包，覆盖对应文件的此前只读等待，不接管日历新增预约：
|
||
|
||
- 派送后端暂接File证据登记，唯一写入`file/src/main/java/com/baiyue/file/service/BusinessFileCategory.java`、新增`file/src/test/java/com/baiyue/file/service/DispatchEvidenceFileTest.java`及`file/src/main/resources/openapi/dispatch-evidence-v1.yaml`。仅登记主后端实际网关已使用的`OVERSEAS_DISPATCH_VEHICLE_EVIDENCE`和`OVERSEAS_DISPATCH_DRIVER_EVIDENCE`，平台0/整车内部主键归属，沿既有PDF/JPG/PNG、10MiB和内容签名规则；不改通用存储/Controller，不放宽其他类型。代码和用例就绪后交主后端串行执行File检查，仍不独占运行Maven。
|
||
- 前端任务取得三个既有排车消费者及同名测试的唯一写权：`appointment-calendar/WorkDispatchForm.vue`、`WorkExistingDispatchForm.vue`、`WorkSharedTripForm.vue`及三个`.test.ts`。只收敛整车创建/加货/已有单跳转和原命令恢复，消除旧客户子单/共车协议及真实类型断点；不改新增预约、WorkDetailPanel、日历面板、planningApi或公共密度测试。上述六文件移交前已核对无未提交差异；若实际遇到新写入立即停止该文件并报告。
|
||
- 总控继续集成时确认旧草稿生产链尚未收敛，主后端明确释放有限草稿包，交由既有派送后端任务唯一维护：`dispatch/entity/DispatchDraft.java`、`DispatchDraftContainer.java`、对应两个Mapper、`SmartDispatchController.java`及新增专用草稿Service/Repository/Mapper、命令持久记录和直接测试。候选仍委托主后端真实提供者；按已冻结PlanningModels及前端真实调用处理草稿版本、拥有者、来源占用及全部容器原子转换，不保留单客户旧协议。共享port、AggregateService、DispatchSourceMapper、旧DispatchService不移交；必要本域桥接由主后端写入。原派送生产及File文件仍冻结，SQL/OpenAPI交总控，草稿任务不启动Maven。
|
||
- 主后端继续唯一维护上述草稿移交包以外的`dispatch/`、`fleet/trip/`和共享端口，补审核/装发、实际来源、PDA、Fleet一对一收敛及真实读写合同；不新增页面或业务规则。主后端保留唯一Maven执行权，按稳定输入覆盖File和派送用例。前端冻结后的只读差异核对已发现Long数量/附件大小字符串造成的真实阻断，总控仅解除其原有独占范围冻结以修正响应边界、直接消费者和真实wire回归；ID/版本继续无损，不改共享解析器、DataTable、导航或新增预约。
|
||
- 总控直接承担共享数据库基线、OpenAPI、权限及根入口收口，其他任务不写这些文件；File上述独占契约除外。索引/AGENTS最终统一维护，避免另建重复状态文档。
|
||
|
||
### 换标同实托多来源的实施冻结
|
||
|
||
用户已确认本批支持整托同车。本次按真实物理托盘与逻辑运输来源分层：同一车内共享物理占用，来源分别保留客户、换标业务号、原货源与可拣贡献；跨车及跨草稿容器继续物理排他。只移除一条来源不得提前释放仍有其余来源的实托，取消、草稿失效/转换及零扫码重审沿同一完整集合执行，不通过第一条来源或FIFO推断其他来源。
|
||
|
||
候选由服务端返回完整选择组及组成版本，使用未被页面筛选截断的事实闭包，兼顾既有整申请规则；前端不按当前可见相同托盘码自行拼组。正式Create/AddCargo保留显式逐来源选择并在服务端复核全组；草稿单来源动作须服务端一次命令原子处理完整组，不能用前端循环多个写请求代替整组一致性。PDA保留逐明细精确扫码，展示明确换标业务号及该来源可拣位置/额度，全部逻辑来源核平后才允许装车；不新增整托一键多次扫码或自动补拣数量。
|
||
|
||
LoadingPreview及实际容量按每实托一行，逻辑箱数、来源状态与费用分别按真实归属保留。整托实测重量/体积不复制到每逻辑来源；业务份额只使用实际来源证据，缺少证据保持未知，不按箱数推件数或平均分摊重量。主流程先产出字段级公共骨架及唯一接口设计，前端以实际Java记录对齐；来源贡献的仓库生产者/移动触点及精确DDL由主流程提出，总控核对现有写者后逐文件分配。共享SQL/OpenAPI仍由总控集成，Maven仍由主流程唯一执行；此前普通流程通过结果不覆盖本次新增模型。
|
||
|
||
来源贡献的直接验证按主流程明确释放的有限边界并行：派送专项唯一新增`lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/service/DispatchItemSourcePersistenceTest.java`，验证冻结贡献、逐明细/客户/位置消费、已消费额度、HOLD合计及事务回滚；该文件移交前主流程确认未创建、未写入。`DispatchItemSourceService`、Repository、Mapper、Entity及公共port仍由主流程唯一维护，派送专项不并修生产；提供者受控输入的组件测试不能代替真实provider与主流程的组合回归，Maven仍只由主流程执行。
|
||
|
||
### 实托组成冻结的共同串行点
|
||
|
||
当前运输组成须排除已由既有换标作废事务结束的申请历史，不沿其旧明细指针扩展实托闭包；真实库存位置仍完整保留，残余HOLD没有当前来源贡献解释时继续阻断。活跃、尚未取得排车资格的申请仍参加完整性核对。普通纯SKU的既有履约资格和库存生命周期保持原规则。
|
||
|
||
草稿纯释放和续租入口（UNSELECT、RELEASE、CREATE_CONTAINER、REMOVE_CONTAINER）须先按原草稿冻结实托集合取得共同Serial，再读取逻辑和物理占用，并在等待后复核原租约；不重新要求当前来源业务资格。SELECT、SNAPSHOT及CONVERT继续遵循既有资源、申请、订单到Serial的完整锁序，不把Serial提前到来源锁之前。到期接管与原草稿动作共享该串行点，不能分别采用逻辑成员到物理占用、物理占用到逻辑成员的相反锁序。
|
||
|
||
主流程已提出且总控冻结窄协议：`inventory/port/PhysicalPalletSerialPort.java`仅提供`void lock(List<Long> warehousePalletIds)`。永久表`ll_physical_pallet_guard`仅有真实全局`warehouse_pallet_id`主键与首次`created_at DATETIME(3)`，没有客户、状态、TTL或运输owner。调用方事务内对去重升序实托执行保留原时间的主键upsert及逐行FOR UPDATE，空目标也取得同一串行点；未关联实托的计划不伪造ID。
|
||
|
||
原有资源/主单父锁之后，预读完整源目标组成，稳定取得全部申请、真实订单，再取得全部实托串行行，重读组成，最后库存及运输claim。新增申请、订单或实托必须整笔冲突，不能持锁后追加无序集合。仓内移动、原托保留、return/unbound都覆盖普通库存、原生退货及空目标；不得给仓内作业新增暂扣资格限制。退货远端physical.apply须置于门禁之后，原业务失败补偿在共同串行锁仍持有时完成。
|
||
|
||
本有限包文件分配：既有B专项唯一新增inventory下上述port、`service/PhysicalPalletSerialService.java`、`repository/PhysicalPalletSerialRepository.java`、`mapper/PhysicalPalletSerialMapper.java`和对应真实Mapper/H2持久化测试，不修改排车/草稿消费者。主流程A唯一接入正式排车与草稿，并仍唯一维护公共排车模型及执行Maven。既有内部`native_fleet_script`唯一修改`palletops/service/PdaPalletOperationService.java`、其原直接测试，按必要最小范围修改本域Repository/Mapper及新增`PdaPalletDispatchFreezePersistenceTest.java`，不写inventory共同实现或dispatch/relabel提供者。SQL两基线与初始化合同总控唯一维护。各包先读取最近指引，交付准确SHA与未验证项；不得增加HTTP、状态协议或迁移。
|
||
|
||
草稿后续接线按主流程明确交接再次细分：B唯一维护`DispatchDraftService.java`、`DispatchDraftRepository.java`、`DispatchDraftClaimMapper.java`、`DispatchDraftPersistenceTest.java`四文件，A确认当前未写且暂停这四文件；A保留完整来源解析、正式主流程、PDA及公共模型。B以`selectionGroup(warehouse, selection)`读取完整组，以`lockDraftSources(warehouse, 全部组成员)`锁定并复核，选择、解除、布局、释放、到期与转换不得拆开同一完整组；按物理实托共享claim并只计一次容量，按逻辑来源保留真实客户及箱数。源版本与组成必须服务端核验，不增加前端循环写或公开协议别名。永久串行点的草稿接入由该B四文件包消费A来源锁方法，覆盖上段原先由A统一接draft的安排，其他边界不变。`DispatchItemSourcePersistenceTest.java`仍B唯一维护，按A明确新增`relabel_round_key VARCHAR(128) NOT NULL`同步手写建表并保持原16场景；SQL仍根维护。
|
||
|
||
### 既有预约接线的本轮授权
|
||
|
||
2026-10-19用户明确批准按《排车列表派送费用接口设计》第13节接线，新增预约不动。本段覆盖下列既有消费者的此前只读限制，不接管日历新增预约或建立车辆预约权威表。
|
||
|
||
- 派送后端唯一维护`appointmentwork/AppointmentWorkDispatchPort`、`inboundplan/work/AppointmentWorkDispatchBinding`、`AppointmentWorkDispatchMapper`、`AppointmentWorkDispatchCandidates`、`FbaAppointmentExecutionAdapter`、`FbaAppointmentTransportAdapter`、`inboundplan/mapper/InboundFbaAppointmentQueryMapper`，以及原`FbaAppointmentTransportPort`、`FbaReceivingService`和实际受影响的直接测试。先产出批量预锁和仅替换本次明细的薄合同供主流程消费；不写主流程公共port或AggregateService。
|
||
- 主后端继续唯一维护`dispatch/port/`和主流程，给既有批次候选引用、分配补权威`recordVersion`（0合法、缺失及同批混版本拒绝），提供版本化的窄内部原预约变更命令；负责创建、加货以及草稿全批转换在来源锁之前预锁完整批次集合。另取得`ExceptionOrderService`及其直接测试的最小适配权，仅修正新共享PDA任务接口消费并保留明细/扫码/订单按真实客户隔离，不新增异常功能。
|
||
- 前端只在原排车模型/API/wire/弹框、三个已授权既有Work排车表单及直接测试内，按实际Java合同透传批次版本；原冻结候选仅对此接线解除冻结，其他部分保持。不得猜版本、补0或改日历新增预约、面板、planningApi及公共密度文件。
|
||
- 批次分配采用本次触及明细的增量替换，保留其他客户与未变明细的原分配，并以整车有效总量复核。统一锁序为全部父trip/资源/dispatch及必要的全部客户outbound、delivery，再全部既有批次、来源及实物/库存占用，协调guard在业务锁与变更之后；不能形成来源→批次反序。原命令身份、两级审核失效、主版本、零真实扫码、完整实物及整事务回滚规则不变，不补回退役Fleet绑定/移货别名。
|
||
- 用户最新明确取消排车的车辆预约：删除页面展示/输入、Update引用字段、详情字段、对应公开类型和拒绝占位分支，FBA预约不变；不保留旧字段别名或空字段，也不新增车辆预约表、创建API或日历业务。此前“保留权威关联、未定位时拒绝”的安排被本次裁定替代。
|
||
|
||
共享SQL、OpenAPI、权限仍由总控集成，Maven仍由主后端唯一执行；不增加任务、不部署、不执行环境SQL或真实业务写入。
|
||
|
||
本轮收口为减少串行等待，总控独占适配四个实际旧查询消费者：`exceptionorder/mapper/ReturnCartonStockReceiptMapper`、`inventory/mapper/ReturnStockReceiptMapper`、`delivery/mapper/DeliverySourceEvidenceMapper`、根`mapper/CustomerOrderProgressMapper`，并补齐同一旧任务客户头引用的`delivery/mapper/DeliveryOperationMapper.returnReceipts`，及直接查询测试`CustomerOrderProgressMapperTest`、`DeliverySourceEvidenceMapperTest`、`SharedDispatchReturnQueryTest`。仅消除已退出的主单/任务客户头、旧状态及发车列依赖，保留真实明细/扫码/订单/派送客户隔离与原数量规则；派送任务不并写移交的查询Mapper。原前端写者同步`CapacityInquiryTable`、`CapacityInquiryDialog`两处同一外接入车API的当前新建权限，保留其他三项独立权限。派送任务另独占`ReturnCartonReturnPersistenceTest`及主后端随后明确释放的`DispatchRepairWorkflowTest`的新模型夹具和构造器适配，主后端不并写该文件；现有归箱、逐SKU恢复、幂等、客户隔离、回滚和真实结案断言保留。总控另精确接手已交付19文件包内`FbaAppointmentPersistenceTest`、`FbaReceivingPersistenceTest`的transport.apply父命令键测试签名收敛，派送任务不并写这两个测试；其他17文件保持冻结。总控另唯一维护`DeliveryTransferService`及其直接测试：PDA解析改用真实整车Repository并保留绑定仓，取消出库不再被整车自动创建的唯一Fleet关系误阻断；ACTIVE/装车前/零真实扫码发运、子单未执行与费用门禁保留。本轮总控还收敛实际旧模型的直接查询消费者：`DispatchFeeCargoMapper`及`DispatchFeeCargoMapperTest`、`PlatformDispatchOutboundContractTest`；无生产调用的`DispatchCargoSourceQuery`删除，原真实来源断言转到现行FleetAdapter。另由总控唯一修改`LastlegOrderMapper.findDispatchStatuses`、`InventoryCommandMapper.shipmentSources`、`InboundPlanQueryMapper.SCHEDULED_DISPATCH`、`AppointmentImpactRelationMapper.dispatches`及四份直接查询测试；仅调整共享头身份/阶段，明细客户、真实库存命令、仓库及取消边界继续核验，不改预约创建。`FleetAppointmentImpactMapper`由主后端单写同一模型的绑定查询，双方不并写。没有新增异常、库存、外接或预约业务。
|
||
|
||
### 本轮测试环境实施授权补充
|
||
|
||
用户随后明确授权总控部署测试环境、操作测试数据库、调用真实HTTP，并使用内置浏览器登录验收样式、交互及请求量；Admin/Client按1920×1080，国内/海外PDA按390×848。此前仅离线检查、默认不部署和由用户截图的限制在此精确范围内由新授权取代。目标仍为本契约所属TEST项目及当前排车改造，不接管日历新增预约，不操作开发或生产环境。总控统一协调发布、SQL及环境写入，先核对匹配源码、结构、权限和现有运行版本，执行后按实际证据维护环境主契约；部署成功、HTTP通过和浏览器验收分别记录。
|
||
|
||
本轮换标出库取消修正的唯一实现者为总控内部`native_capacity_consumers`，只写`DeliveryTransferService.java`、`DeliveryCancellationRepository.java`及`ReturnOutboundClosureTest.java`；覆盖原生箱及普通仓托，保留原配送方式、已确认成果及库存事实，TRUCK退回待排车，其他方式退回待独立安排。不把非TRUCK来源改成TRUCK、不重跑换标完工确认或新增旧独立出库安排API。非TRUCK再次独立安排入口的接线尚不属于本次取消修正，不以取消持久化成功推定再次安排已完成。后端其他写者冻结这三文件，Maven仍由主后端统一执行。
|
||
|
||
## 十 日历新增预约的范围分离
|
||
|
||
用户澄清“新增预约”应放在预约日历，并指定由对话 `01a15231-2507-7802-8015-34b01f5eb2c4` 处理，明确本总控不用接管。三个排车任务不修改预约日历的新增预约表单、权威预约模型或预约新建API，也不承担其设计和矩阵；本批只处理整车改造确实影响的既有预约读取/关联消费者，有限接线写权见第九节，不自行接管新增预约或跨对话派工。
|
||
|
||
此前关于FBA预约可先保存、后关联真实货物和排车，以及车辆可先独立预约、后关联排车的答复仅保留为日历需求输入，其后续规则和实现由用户指定对话处理；此处不继续整理日历方案、不创建新任务、不跨对话转派，也不删除已经存在的预约功能或关联。
|