docs/海外仓业务/车辆管理原型梳理与任务规划.md

# 车辆管理原型梳理与任务规划

> 文档状态：原型盘点、首版执行确认与开发增量记录；更新时间：2026-10-07。
> 规划对象：Admin「车辆管理」及其与排车、海外派送、车队报价的衔接能力。
> 本文用于确定范围、现状和任务依赖，不代表代码已经完成、已经部署或已经通过真实环境验收。
> 开发已按后续授权推进；当前源码增量与未完成项见第 10 节。文档 Review、局部测试、真实部署和页面验收分别记录，不相互替代。
> Review 状态：2026-10-02 已完成本次连续 5 轮核对、修订与复查，记录见第 9 节。原型事实、源码现状和候选设计已分别标明；业务决策仍见第 4 节，不等于功能开发或环境验收完成。
> 后续业务确认：2026-10-02 用户明确“外接”为自有货物未装满时承接顺路外部货物，审核先展示详情并提供通过/打回；司机证照 30 天内到期但仍有效时允许派车并提醒，预计任务结束前过期则禁止。已确认部分与出车/金额建议见第 4.1 节，追加边界 Review 见第 4.4 节；不把建议标为用户已确认。

## 本轮首版执行确认（2026-10-02）

用户明确“按你的建议执行，我们先做一个版本出来，再优化和修改；验证可以宽一些”。本次确认替代下文先前标记为待答的首版选择：外接货先送我方起运仓，运营接洽并在后台登记；调度通过后拣货、理货通过后发车；车次采用独立列表和详情、计划居中弹框、其余操作在详情分区；维修/故障/救援增加“更新处理”。原运费按每票实际覆盖范围引用，另行确认的新增项目才计费；源码说明见第10.9节，当前部署、真实验收与未关闭项目统一见[测试环境单机部署与配置契约](../测试环境单机部署与配置契约.md)及[统一认证与服务通信契约](../统一认证与服务通信契约.md)。

首版驾驶证为必需资质，体检/培训/保险日期先作档案记录。输入校验保留必需业务数据、权限、客户归属、防重复、实际容量及已确认的证照到期规则；普通说明、地址等选填字段宽松处理，常规动作使用标准审计说明，不要求用户重复填写。原型未覆盖的上述操作已有本轮授权，不再重复等待确认。

第 4.7 节保留此前受阻时的核对经过；其“待答”状态已由本次确认解除，原目标恢复实施。实现、部署和真实验收仍分别核对，用户批准方案不代表功能已经完成。

2026-10-03 财务追加确认：用户在“车辆管理｜成本与财务闭环”独立任务明确“请按你的建议来处理先”，确认维修/救援按公司车辆成本登记，不自动形成客户应收；保留CNY/USD原币，按业务月份汇率折算CNY入账。首版允许未付款费用作废重建，已付款费用禁止直接改写或作废，退款冲销后续单独确认。此项解除第4节第6项中维修/救援财务归属的待答状态；保养/加油等其他来源不据此自动扩大。费用登记、入账和付款须分别体现真实状态，不能以运维处理完成替代付款。当前实现仍由专项接入，部署及验收以两份正式主契约为准。

## 2026-10-07 增量：内部拼车需求池与三种交货方式

本功能进入文档审核与开发准备后，首版范围、接口决策、五轮审核和验证门禁统一维护在[内部拼车需求池首版开发契约](内部拼车需求池首版开发契约.md)。以下增量保留需求演变与完整业务方向，不覆盖新契约的统一我仓上车边界。

本节记录本轮需求和接入建议，不代表新功能已经实现或部署。用户先明确三种交货方式，随后提出前期先做“我仓上车”、暂不做顺路直送，以减少工作量；最新首版建议见下段，三种方式保留为完整业务方向。现有车次主链验收不能作为需求池及沿途提货已经跑通的证据。

### 最新首版收敛建议：统一我仓上车

用户提出首期只做我仓上车、顺路直送暂不做。推荐首版交付内部需求池、销售意向与报价、调度确认占位、本土订单关联，以及复用现有真实到仓收货至装车签收的闭环。所有本期实际发运货物须先进入我仓，不增加沿途提货站、非仓库货物来源或行驶途中接货确认，也不修改现有“始发前外接货已实收并关联发运”的门禁。

客户自行送仓与我方提货回仓均可最终进入该流程。为控制首版工作量，建议我方提货回仓暂由运营在线下安排，系统仅记录交货方式、预计到仓及备注，从实际到仓后开始收货；这不代表系统已有提货任务派车、提货交接或提货成本闭环。若要求提货过程也全部在线处理，再纳入下方B阶段。

下方A/B/C顺序为完整方案储备，当前推荐先实施A；B独立提货回仓作业、C沿途直送留待后续范围确认。阶段A仍须验证真实外接货与自有货同车、客户隔离、占位转实载不重复扣减、取消释放及不重复收费；不能以发布余位列表代替完整送仓拼车链。当前仅调整方案，未据此开始代码或环境变更。

### 用户已确认

- 调度已约车并安排自有货后，需将去向、时间和可接余位集中展示给销售。例如去目的地 A 的车有30托位，自有货占18托位，还能寻找12托位的外接货。
- 首期需求池只面向内部员工，销售查看后自行联系外部客户；不在此范围内建设客户公开运力市场。
- 完整业务需要逐票选择三种交货方式：客户送到我方起运仓；我方上门提货后回我仓；我方沿途提货后直接送对应目的仓。随后用户提出首版先统一我仓上车，沿途直送暂缓；不再将三种系统执行闭环同时作为推荐首版范围。
- 本土业务现有下单入口承接成交业务，需求池位于下单前，先让销售知道哪趟车、去哪里、何时出发、能接多少货。

### 建议的业务承载与流程（待按实际交互细化）

建议新增内部「拼车需求池」，由车次提供路线、发车时间和容量事实。调度核对计划后发布可接货需求，销售按起运区域、目的地、时间和交货方式筛选，并登记客户意向；调度确认承运后占位，再关联正式客户订单和该车次，按交货方式履约。询价不占位，已确认预订扣减可接容量，沿用现有外接预订规则；是否提供有时限的临时留位另行定义，不默认新增。

| 交货方式 | 建议履约路径 | 必须保留的实际事实 |
| --- | --- | --- |
| 客户送仓 | 客户送到我仓 → 实际收货、测量及入库 → 绑定干线车次 → 拣货、装车 → 目的仓签收 | 到仓实收、库内库存和出库事实 |
| 我方提货回仓 | 安排提货任务 → 客户地点交接 → 运回我仓 → 实际收货、测量及入库 → 干线装车 → 目的仓签收 | 提货交接与到仓收货分别记录；提货车辆和干线车辆可不同，费用不可重复收取 |
| 沿途提货直送 | 安排本车提货站 → 到站交接、核量及装车确认 → 按路线送目的仓 → 签收 | 客户地点实收和车上货物事实；不虚构我仓入库、库位、仓库托盘或仓库出库单 |

需求池建议展示：车次号、起运仓/区域、已有途经及卸货站、计划发车与最晚交货时间、整车容量、自有货预计占位、外接已确认占位、可接托位、剩余重量/体积、允许交货方式、调度联系人、接货状态。客户意向需记录销售负责人、客户、提货地址（需要提货时）、目的地、预计托位/重量/体积、交货时间和报价。客户业务单据、预订与车次建立明确关联，销售无需重新录入另一套容量。

### 容量与变更建议

- 30−18=12仅适用于同一运输区间且重量、体积也允许的情况。客户占8托位并确认后，同一区间余4托位；不同销售同时确认时必须由服务端避免超卖。
- 沿途提货按“提货站至卸货站”逐段预留容量。计划阶段即占用对应未来区间，不能等实提才扣可售余位；实际车上数量则在提货交接后增加、卸货签收后减少。
- 示例：我仓带18托去 A，途经 B 提12托一起送 A；我仓→B 实载18托，B→A实载30托。若这12托已确认，B→A余位已为0，不能再对该区间承诺12托。
- 回仓提货独立核对提货任务运力；回仓后的干线预订也需占位，同一批货不能在同一车次被预订和实际装载重复扣减。
- 自有货、车辆容量或路线变化后重新核对有效余位；容量计划失效时展示“待调度核对”并停止新承运确认，不能把未知显示成有空位。超出原已发布路线的提卸点需调度调整路线并复核承诺。
- 需求发布、暂停接单、满位、取消及发车后接单规则属于需求池状态，不混同车次运输状态。首期是否允许车辆出发后再接新的沿途订单，尚未确认；已在出发前确认的沿途提货必须正常执行。

### 当前源码与缺口

| 部分 | 当前核对事实 | 本次需补齐 |
| --- | --- | --- |
| 车次与容量 | Admin `TripsView.vue`已有车次列表；详情 `capacity-plan` 返回有效计划和扣除外接后的逐段余位，列表没有面向销售的余位发布入口 | 跨车次需求池查询、发布/暂停/关闭、销售意向及责任人；服务端统一返回有效可接运力 |
| 外接预订 | `TripBookingPanel.vue`及`bookingTypes.ts`已有询价、确认承运、实收、关联发运和取消 | 从需求池带入车次与路线，扩展逐票交货方式、提货站和交接事实 |
| 容量算法 | `TripCapacityPolicy.Booking`支持提货/卸货站区间；当前`FleetBookingReservations.add`固定从站点0占位 | 将真实提货站接入预订、计划变更和发车/到站复验，不能仅在页面增加选项 |
| 来货及库存 | `FleetIncomingAdapter.create`固定`CUSTOMER_DELIVERY`并调用仓储转运来货流程，实收证据来自本仓托盘 | 保留客户送仓链；增加提货回仓任务衔接，以及不经仓的沿途提货直送履约来源 |
| 本土下单关联 | 当前正式菜单名称是「本土卡车」「本土散板」；外接预订的当前来货链是仓储转运，不证明已经关联这两类订单 | 明确每票对应的业务单据及单一收费来源；从需求池转单携带预订和车次关联，禁止重复下单、占位或收费 |

验收应分别覆盖三种交货方式，并验证：30托位/自有18托位/外接12托位、并发确认不超卖、不同提卸区间、不足或超量实收、货物及路线变更、取消释放、回仓两段运输关联、直送不产生虚假仓库库存、签收回传与收费不重复。此前灰度FBA自有货主链通过，不替代这些新增场景。

### 推荐实现方案：沿现有车次接入（设计建议，非已实现）

建议仍在 Lastleg 现有车辆与本土业务内实现，复用统一 Gateway/Auth、客户隔离、File 和 Finance。不新增独立撮合服务，不复制一套车次、库存或财务账。

**页面和职责。** 在「车辆管理」增加「拼车需求池」，销售可直接进入；车次详情增加“发布拼车需求”及关联入口。需求池每条需求关联唯一车次，展示可接运输区间，余位实时来自服务端有效容量与已确认预订，不让销售手填剩余托数。建议车次先待发布，调度确认路线、时间和可承诺容量后发布；自有货或预订变化自动更新余位，计划失效则暂停承诺。多站路线不能只展示一个没有运输区间的“剩余12托”。

销售负责登记客户意向、选择三种交货方式、报价与跟进；调度负责发布、确认路线及承运占位、安排提货和车辆；仓库负责实际过仓货的收货、拣货与出库。销售看运力及自己获授权的客户资料，不因需求池访问而获得同车其他客户货物、成本或全部司机资料。发布、询价登记、确认占位及提货确认采用独立写权限，不把销售统一授为车次管理员。

**单据关联。** 建议采用“车次 → 发布需求 → 客户意向/预订 → 本土业务订单 → 履约任务”的关联。复用外接预订的询价和承运确认；内部销售成交时在同一业务动作中关联或生成本土散板/本土卡车单据，不要求再去两个页面各下一单。已有本土订单也可选符合路线的车次进行匹配，一票可依法分段运输但同一段货物不可重复占位。同一客户委托可以对应提货回仓和干线配送两段任务，仍保持同一业务来源与可追踪费用。

本土单据记录客户委托、交货方式、货物及已确认交易条件；预订记录该订单在哪个车次、哪个提卸区间占多少位；任务记录谁在何时、何处实际接货和交货。报价预算、确认成交价与财务应收/实收分别处理；预订、提货任务和最终派送引用同一已确认费用来源，新增提货费须独立确认，不能因生成新任务再收一次原运费。当前 `LocalLooseboardRequests`/`UsTruckOrderRequests` 没有这套车次关联，须连同平台和客户消费者更新正式合同。

**三种方式如何进入执行。**

1. 客户送仓：关联既有来货流程；PDA 实收、核量确认后，将已确认预订占位转换为实际发运货物占位，不能两份同时扣容量。
2. 提货回仓：从客户订单派生提货任务，记录地址、预约窗口、联系人、承运车辆、实际提货数量和交接附件；可由另一趟车执行。回我仓须重新完成真实收货事实，再承接原干线预订。提货成功不等于仓库收货成功。
3. 沿途直送：同车次添加有顺序的提货站和卸货站，增加不依赖仓库托盘的运输货物来源。出发前可保留尚未提取但已确认的后续站货物；当前站必须装车的货物仍需就绪。到提货站后核对实际托位、重量、体积及交接证据，通过下一段容量校验才允许继续；超量、少到、未到和改目的地由调度处理，不能自动超载或将未提货标成已承运。

首版建议由调度在后台维护提货任务并录入实际交接结果及附件，仓库 PDA 继续承载过仓作业；司机专用移动作业入口另定交互，不把仓库 PDA 的仓库绑定权限直接放宽为司机跨地点权限。若需司机现场自行操作，须作为同一履约任务的授权入口接入，而非另一套运输状态。

**必须修改的核心门禁。** `FleetTripExecutionService` 当前从仓库排车明细生成实际装载，并在 `hasConfirmed` 为真时阻止发车（外接货尚未关联实际发运货物）。新增沿途直送后，要按站点区分“此站应装货”和“后续待提货”，分别核对当前装载、未来预留、已发生运输段及未完成交接；不能直接删除既有外接未就绪门禁。全车结案须包含直送货签收结果，不能只检查原仓库派送单。已完成站点和历史实载不可通过修改计划重写。

**建议实施顺序与交付边界。**

| 阶段 | 交付物 | 验收重点 |
| --- | --- | --- |
| A：销售可用的需求池 | 车次发布与集中查询、线路/时间/余位筛选、销售意向、确认占位及本土订单关联；沿用送仓履约 | 30托位自有18托位，确认外接8托位后余4；多销售并发确认拒绝超卖；旧容量失效不可继续接单；已有订单匹配不重复下单/收费 |
| B：提货回仓 | 提货任务、车辆安排、交接与回仓收货、同单两段运输关联 | 提货与入仓分开确认；提货车和干线车不同；货量差异重新核量；预订与实收不重复扣位 |
| C：沿途提货直送 | 提卸站点、非仓库运输货物、分段装载与提货确认、签收/结案及统一费用来源 | 后续提货不阻断合法始发；沿途每段不超载；未提货/部分提货/改配有处理记录；不生成虚假本仓库存；直送未结束不得整车结案 |

A/B/C 为完整方案依赖顺序，按用户后续提出的收敛方向，当前推荐首版先交付A并用包含自有货和外接货的真实车次验收；这不证明B独立提货任务或C沿途直送已实现。各后续阶段单独确认范围、实施和验收。未实现的交货方式不得在可成交页面提供虚假的成功路径。

待进一步确定的业务选择仅保留会改变执行边界的项目：出发后是否允许新增外接订单、是否允许销售临时留位及有效期、提货操作是否首版由司机本人在移动端完成。以上建议未被标记为用户已确认；本节不改变已确认的内部需求池和三种交货方式。

## 1. 读取范围与事实优先级

本次原型输入是用户提供的外部文件：

`C:\Users\BY-OY\Documents\WXWork\1688854456873012\Cache\File\2026-09\新版.html`

文件读取时间为 2026-09-30。它不属于仓库事实源，文中的示例数据、模拟状态和按钮反馈只用于说明页面意图。新版文件把车辆管理拆成多个页面和弹窗，不能只按“车辆列表”一个页面排任务。

本次连续复核的原型快照 SHA-256：`D12B35F5363ED9B67A33E9D12D542DD902628BC946F75519BC7DDC049D94CD65`。行号只对应这一文件版本；后续原型变更需重新核对交互，不能仅凭同名函数认定行为相同。

实现范围按以下顺序核对：当前对话确认和正式契约，现有 Controller/OpenAPI/权限/SQL，当前 Admin 路由和页面，原型与参考资料。原型出现的功能需要补齐服务端契约和验收证据后才算有效实现。

当前架构使用统一 Gateway、统一 Auth 会话和统一测试环境。后续新增接口应沿“浏览器实际路径 → 统一 Gateway → Controller → OpenAPI → 权限”核对，不按旧资料中的独立海外 Gateway 建立第二套入口。

## 2. 原型实际包含的页面

### 2.1 页面入口总表

| 原型页面/入口 | 原型位置 | 页面职责与主要内容 | 当前原型行为 | 规划判断 |
| --- | --- | --- | --- | --- |
| 排车列表 `outbound-vehicle` | 菜单 `新版.html:1452`；页面 `4474-4486` | 装车前/装车中/装车后三阶段；装车前再分车辆信息、调度审核、理货员审核；按排车单号、车牌、车辆状态筛选；展示司机、电话、托车公司、预约号、派送单、托数、装车时间、FBA/车辆预约等 | 以原型数据和已有页面脚本渲染，审核、附件、轨迹等动作主要是页面演示 | 与正式排车模块连接，不能复制出第二套排车状态或车辆快照 |
| 排车详情 `outbound-vehicle-detail` | 页面 `9433-9445` | 排车单号、状态、车辆/排车信息，以及关联订单明细（订单号、重量、托数、目的 FBA 仓、体积、集装箱号） | 由原型数据渲染关联订单表和详情字段 | 复用现有 `/overseas-warehouse/dispatches/:dispatchNo` 与 `DispatchDetailView.vue`；车辆管理入口只做跳转，不新建排车详情 |
| 排车编辑/审核/订单选择弹窗 | `modal-outbound-vehicle-edit` `12338+`；`modal-outbound-vehicle-audit` `12396`；`modal-outbound-vehicle-rejected` `12397`；`modal-outbound-vehicle-order-select` `12411+` | 维护车辆、司机、预约和路线；上传附件；调度/理货员审核、驳回原因；选择待派送订单 | 表单、附件和审核结果主要写入原型内存并弹 Toast | 归入 VM-04a：复用现有详情/编辑，审核须补提交、通过、驳回、重提及权限/版本契约；普通编辑不代表已提交审核 |
| 车辆列表 `vehicle` | 菜单 `1453`；页面 `8819-8886` | 国内/海外区域页签；自有/外派归属页签；按车牌、司机、车型和状态筛选；新增、导出；两类车辆不同表格列；列表下方预留配送进度和运营记录 | 列表数据在 `ownVehiclesData`/`dispatchVehiclesData` 内存数组中；新增、编辑、删除、状态校验和提示均在浏览器内完成；配送进度卡片在页面 CSS 中隐藏，运营卡片在详情时被移动 | 车辆主数据沿用当前真实模块；新增字段和运营记录需先定服务端归属 |
| 车辆新增/编辑 `modal-vehicle-edit` | `8890-8935` | 归属、车牌、车型、油耗、当前公里码、电话、外派单位、区域、状态、停运原因、FBA 仓、发车时间、预计到达时间；自有车辆编辑时附带保养和加油字段 | 必填校验、派送中/停运中条件校验和本地数组更新；图片字段是字符串或示例文本 | 不直接照搬字段；公里/迈数、司机绑定、运单关联和附件归属需形成正式模型 |
| 车辆详情 `vehicle-detail` | 页面 `9024-9051` | 车辆概览、保养及加油、维修记录、紧急故障、应急救援、异常管理六个页签；概览含车辆信息和派送订单明细；各扩展页签可新增记录 | 详情由本地数组拼装派送订单；更换历史缺页面容器；维修/故障/救援/异常共用未按车辆隔离的数组，部分保存字段错配 | 当前真实车辆详情只承载车辆主数据，服务端明确不含派送履约/更换历史；扩展页签必须逐项立项 |
| 司机管理 `driver-management` | 菜单 `1454`；页面 `8798-8805` | 司机总数、即将到期、驾照过期 KPI；“当前可派”卡片在源码中保留但被 CSS 隐藏；资质提醒；按姓名/手机/司机编号、状态、归属、资质筛选；司机档案表；新增、查看、编辑、删除、驾驶证附件查看 | `driverManagementData` 内存数组；根据当前日期计算驾照到期；缺附件或未审核显示待补件；资格阻断只显示提示，未联动排车保存；保存和删除只更新数组并弹 Toast/confirm | 需要独立司机主数据、资质状态机、附件和派车资格接口，不能把司机字段继续塞进车辆表 |
| 司机详情 `driver-management-detail` | 页面 `8807-8813` | 基础信息、驾驶资质、证照与派车状态；查看驾驶证附件 | 由司机内存数据拼装 | 需要真实详情 API；资格结果必须由服务端返回，页面只展示 |
| 司机新增/编辑 `modal-driver-edit` | `8815-8816` | 姓名、电话、归属、仓库、车型、语言/区域；驾照类型/编号/签发/到期；体检、培训/安全、保险到期；审核状态；驾驶证和其它附件上传 | 强制上传驾驶证后才允许保存；文件使用 data URL 暂存 | 文件应接经评审的上传与附件归属能力，司机资格审核和附件归属需进入正式契约 |
| 自有业务 `vehicle-own-business` | 菜单 `1455`；页面 `8757-8762` | 日期范围、排车单号/车牌/FBA 仓、任务状态、仓库筛选；今日排车、装车完成、派送中、派送完成 KPI；任务明细含预约、车辆、司机、提货仓、目的仓、托数、油耗、价格、装车/到达时间 | `vehicleBusinessRecords` 内存数组；KPI 和总价/单价在浏览器计算；可查看详情、上传现场/油耗图片和实际迈数 | 应消费正式排车/派送事实和服务端 KPI；不能把业务履约复制为车辆主数据记录 |
| 自有业务详情 `vehicle-own-business-detail` | 页面 `8764-8774` | 任务与车辆信息、路线货物与现场凭证、操作记录三页签；显示预设路线、GPS、ETA、油耗、费用预算和证据清单 | 详情字段、时间线、路线和证据状态为脚本拼装；上传仅修改内存对象 | 需要与排车、PDA、派送和文件服务建立稳定关联；GPS/路线告警先确认是否纳入本轮 |
| 外配业务 `vehicle-outsourced-business` | 菜单 `1456`；页面 `8778-8796` | 待外配托数、今天外配托数、在途车辆 KPI；合作车队/异常任务卡片被 CSS 隐藏；按任务号/车队/车牌/FBA 仓和任务状态筛选；展示总托数、自有成本、自有托数/单价、外接托数/金额/单价、ETA、状态 | 与自有业务共用 `vehicleBusinessRecords`；部分操作调用自有业务详情和上传照片逻辑；示例成本、托数和报价在浏览器渲染 | 用户已明确外接为利用自有货运输的剩余运力承接顺路外部货物；原型名称保留作追溯，后续建议改称外接业务，详见第 4.1 节 |
| 出车记录 `vehicle-trip-record` | 菜单 `1457`；页面 `8941-8987` | 时间区间统计四张图（托数、派送仓库、价格、托均价）；按车牌/提货仓/派送仓、车辆类型、日期筛选；添加、编辑、导出Excel占位按钮；删除函数未发现页面调用；装车/派送完成时间、用时、托数、价格、托均价、油耗、图片附件 | `vehicleTripRecords` 内存数组；派送用时、托均价和图表汇总由浏览器计算；图片使用 data URL；时间校验只在前端；导出仅弹 Toast | 先定义出车记录来源和唯一性，再决定独立事实表还是由派送单投影；“板/托”“公里/迈”“油耗单位”必须统一 |
| 派送车队报价 `delivery-fleet-quote` | 通用菜单 `1527`；页面 `8989-9021` | 按发货城市、目的 FBA 仓、车队、提货方式、状态筛选；新增/编辑、启停、删除、导出；CSV 模板下载、预览校验、批量导入 | `deliveryFleetQuoteData` 内存数组；校验必填、非负价格和“城市+仓点+迈数+车队”重复组合；导入只写浏览器数组 | 先按第 4.1 节区分外接销售价与车队采购价，再定客户/供应商关联；CSV 导入需服务端校验和重复处理规则 |

### 2.2 车辆列表和详情的字段与交互

配套弹窗也属于本轮原型范围：车辆运营记录 `modal-vehicle-ops-record`（`8937`）、车辆详情扩展记录 `modal-vehicle-detail-add`（`8938`）、司机证照查看 `modal-driver-license-view`（`8816`）、出车记录 `modal-vehicle-trip`（`8966`）以及车队报价编辑/导入 `modal-delivery-fleet-quote`、`modal-delivery-fleet-quote-import`（`9009`、`9021`）。它们不单独扩成新的业务页面，分别随 VM-02、VM-03、VM-05、VM-06 的正式契约开放。

车辆列表在原型中有两套列：

- 自有车辆：车牌、车型、油耗、当前迈数、联系人、联系电话、状态、操作。
- 外派车辆：操作、车牌、车型、外派单位、联系电话、托数。

区域页签和归属页签同时存在，形成两个主切换维度；原型还把车辆配送进度、运营属性、保养加油和路线告警放在同一页面结构中。当前代码已按正式接口将区域降为查询条件，只保留自有/外派归属页签，并把操作列固定在第一列；该布局有现有原型矩阵记录的历史确认作为依据；若本轮重新确认布局则更新相应合同，代码现状本身不覆盖新需求。

新增/编辑弹窗的原型校验包括：车牌、车型、油耗、公里码必填；状态为“派送中”时要求 FBA 仓、发车时间和预计到达时间；状态为“停运中”时要求停运原因。上述校验目前只是原型脚本行为，最终规则要由服务端状态机确认。

新版车辆详情实际有“派送订单明细”；更换历史仍保留 `renderVehicleFleetHistory` 函数，但它读取的 `vehicle-detail-history-body` 仅在该函数中出现，未找到页面容器，不能算作当前可见分区。当前真实车辆主数据合同排除派送履约及车辆更换历史：Controller 注释排除前者，OpenAPI 的车辆详情 `GET /{id}` 明确排除两者。现有 Admin 详情仍保留这两块边界提示。若新增真实历史查询，需先确定订单/排车查询与更换历史的归属，不能把旧页面提示当作新版已经提供该功能。

运营扩展也存在未闭合交互：`vehicleDetailExtraRecords` 是按记录类型保存的全局数组，保存/渲染未带车辆标识；`openVehicleDetailAdd` 生成描述和处理人等字段，而维修/救援保存分支读取不存在的 `vda-item`、`vda-place`，会丢失录入信息。救援列表列名为“付款状态”，弹窗却选“待处理/处理中/已完成”。此外，车辆属性和路线告警面板在打开车辆详情时被隐藏，不能把源码内预留字段全部当成当前可操作需求。正式设计应分别确认记录归属、各类型字段、处理状态和付款状态。

### 2.3 原型中明确出现的规则冲突

| 主题 | 原型表现 | 需要冻结的正式口径 |
| --- | --- | --- |
| 距离单位 | 车辆列表弹窗使用 km；运营卡片、路线和车队报价使用 miles/迈数 | 车辆里程、路线距离和报价距离分别定义单位；接口禁止以字段名猜单位 |
| 托数单位 | 出车记录表头初始写“板数”，脚本又改成“托数”；外配业务使用总托数/外接托数 | 统一业务词和字段名；托盘数量与板数不能在前端静默换算 |
| 油耗单位 | 百公里油耗使用 L/100km，加油记录示例使用 gal，出车记录油耗使用 L | 定义车辆档案、加油事实、出车消耗的单位与换算责任，服务端返回展示单位 |
| 车辆合作方术语 | 原型混用“外派车辆、外配业务、合作车队、车队渠道、托/拖车公司” | 冻结用户可见词和服务端枚举/字段映射，避免把司机、承运商、车队和拖车供应商当成同一对象 |
| 车辆与排车关系 | 车辆列表有配送 FBA、发车时间和 ETA；排车列表也维护车牌、司机、预约和状态 | 车辆主档只保存可复用属性；排车/派送保存任务快照和执行事实，避免双写状态 |
| 删除 | 车辆、司机、车队报价有删除操作；出车删除只有未接入函数 | 分对象确定删除、停用、作废或更正语义；没有合同的动作不开放，不能自动用停用/作废替代 |
| GPS/路线 | 原型写“GPS 轨迹监控已启用”、路线偏离和 ETA 告警 | 先确认已有设备/轨迹来源和告警服务；没有正式来源时只能展示待接入状态 |
| 资格阻断 | 页面用日期、附件和审核标识显示资格与阻断提示，未形成排车拦截 | 临近到期规则已确认：30 天内仍有效允许并提醒，预计任务结束前过期禁派；由服务端返回资格和原因。核验时点及时间边界建议见第 4.4 节 |

### 2.4 原型统计与报价口径

原型中的金额和统计还需注意以下差异（均为原型事实，不自动成为正式口径）：

- `renderVehicleBusiness` 的“今日排车数”实际取筛选后的行数，不独立限定今天；外配“今日外配任务”被脚本改名为“今天外配托数”，对应数字仍是静态值。正式 KPI 需明确日期字段、仓库时区、筛选范围、单位及聚合粒度。
- `renderVehicleTripCharts` 的“派送仓库”总数是去重仓库数，图中各仓的值却是出车记录条数；托均价是总价格除以总托数，并非各行单价的简单平均。正式报表应明确两个指标的名称，混币种不能直接求和；原型同时以列表日期和统计日期过滤，需要确认正式查询与图表是否共用范围。
- 车队报价 `validateDeliveryFleetQuoteDraft` 允许三种价格仅填一种，空值表示未报价，0 是允许输入的数值；CSV 确认导入会跳过无效/重复行并插入有效行。正式合同须确认沿用部分成功还是整批原子提交，不能把空值转换成免费报价，也不能默认原型为全成功导入。

## 3. 当前代码、接口和数据现状

### 3.1 已具备的车辆主数据能力

当前 Admin 和 Lastleg 已经有一套真实车辆主数据能力，不能按旧缺口文档中的“车辆缺失”处理：

| 层次 | 当前入口 | 已有能力 |
| --- | --- | --- |
| Admin 导航 | `apps/admin-web/src/core/navigation/adminNavigation.ts:120-126` | 车辆管理下已有“排车列表”和“车辆列表”；车辆列表路由为 `/overseas-master-data/vehicles` |
| Admin 页面 | `apps/admin-web/src/modules/overseas-master-data/pages/VehiclesView.vue`、`VehicleDetailView.vue` | 真实分页、关键词/归属/区域/状态筛选、查看详情、新增、编辑、状态变更、CSV 导出；操作列固定在左侧 |
| Admin 路由/权限 | `apps/admin-web/src/modules/overseas-master-data/routes.ts`、`permissions.ts` | 车辆列表和详情使用 `vehicle:list`；创建、编辑、状态、导出权限独立 |
| 后端 Controller | `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/masterdata/vehicle/adapter/in/web/PlatformVehicleController.java` | 列表、详情、创建、编辑、状态、导出；编辑和状态使用 `recordVersion` 乐观锁 |
| OpenAPI | `baiyue-firstleg/lastleg-service/src/main/resources/openapi/overseas-master-data-v1.yaml` | `/api/platform/v1/last-leg/master-data/vehicles` 的 GET/POST、`/export` GET、`/{id}` GET/PUT、`/{id}/status` PATCH |
| 数据库 | `baiyue-firstleg/lastleg-service/src/main/resources/db/lastleg.sql` | `ll_vehicle`，车牌唯一；保存区域、归属、状态、里程、油耗、司机/外派单位、电话、备注和版本 |
| IAM | `baiyue-firstleg/iam/src/main/resources/db/lastleg-permissions.sql` | `platform:overseas-master-data:vehicle:{list,create,edit,status,export}` |
| 测试源码入口 | Lastleg 车辆 Controller/Application/SQL/OpenAPI 合同测试；Admin 车辆 API、挂载、视图和写行为测试 | 已定位到测试文件；本次未运行这些功能测试，文件存在不代表当前全部通过，也不证明部署或整套车辆管理完成 |

当前车辆主数据接口字段包括车牌、车型、百公里油耗、当前里程、司机/外派单位、电话、区域、车辆归属、状态、备注、记录版本和更新时间。本轮已增加最大标准托位、最大载重kg和可用容积m³，三项同填正数或全空待确认；车次分配不接受未知容量。服务端不提供车辆删除端点，当前 Admin 不展示删除动作。

需要保留的已有规则：车辆创建/编辑将车牌去除首尾空格并转大写，数据库对车牌做全表唯一约束；编辑时公里数不得小于原值；编辑和状态操作检查 `recordVersion`。当前状态为 `IN_SERVICE/在役`、`DISPATCHED/外派中`、`MAINTENANCE/维修中`、`INACTIVE/停用`、`RETURNED/已归还`，与原型“空闲/派送中/停运中”并不一一对应。`changeStatus` 只校验枚举与版本，没有按当前派车任务检查状态迁移；不能据此宣称已经实现车辆占用和释放。出处为 `VehicleApplicationService.create/update/changeStatus`、Admin `presentation.ts` 和 `ll_vehicle` 唯一索引。

### 3.2 原型范围与当前实现的差距

| 能力 | 当前状态 | 结论 |
| --- | --- | --- |
| 车辆主档列表/详情/新增/编辑/状态/导出 | 已有真实前后端合同 | 作为基线复用；先补字段和状态确认，再决定是否扩表 |
| 车辆运营属性（初始里程、停放位置、司机绑定、租赁状态） | 原型 `vehicleAttributeData` 和隐藏面板中预留 | 缺正式 DTO、表和权限；不能写入浏览器本地状态后宣称完成 |
| 保养与加油 | 已有独立车辆运维记录模型、文件归属、版本及历史，Admin 按车辆分页查询并接入新增/编辑和图片读取；实现边界见第 10.1 节 | 本地实现不代表环境已部署；不自动改车辆里程、占用或财务付款 |
| 维修、紧急故障、应急救援、异常管理 | 已接逐车新增/展示，异常支持编辑；修复原型字段错配并分离处理与付款状态，见第 10.2 节 | 维修/故障/救援后续更新入口仍待承载方式确认；财务闭环及真实环境验收未完成 |
| 司机主数据与资质 | 已新增司机后端、文件接入、Admin 列表/详情/编辑/审核/证照预览，补齐真实仓库关联与可选资质日期；车次分配、调时和整车 PDA 发车均复核资格；本地验证见第 10 节 | 实际命令的源码已接入，真实部署及 HTTP/PDA 验收尚未完成，不能以独立资格预览代替发车校验 |
| 自有/外接业务工作台（原型名外配） | 现有正式排车/派送模块存在，但没有原型同名工作台 | 已确认顺路拼载业务；建议按共享行程关联各客户单据，工作台展示自有/外接货物分项，详见第 4.1 节 |
| 车辆详情中的派送订单/更换历史 | 新版有派送订单展示，更换历史缺容器；车辆详情尚未接入两类记录，页面引导从现有排车/派送管理查看派送事实，明确更换记录未接入 | 车次已有改派历史，但不等于车辆详情已有跨车次履历；后续补真实查询，不以说明文字代替功能 |
| 出车记录与统计 | 原型本地数组和浏览器图表 | 需要确定事实来源、唯一键、费用归属、油耗证据和统计口径 |
| 派送车队报价 | 原型内存数组、CSV 解析和浏览器校验 | 先区分外接销售报价与车队采购报价，再决定模型复用和客户/供应商关联，不能将外接收入建成供应商应付 |
| 车辆管理新增菜单 | 当前源码已注册排车列表、车辆列表和司机管理，司机详情使用独立路由 | 自有业务、外接业务、出车记录等菜单继续随对应正式接口接入；源码注册不表示环境已发布 |

### 3.3 与现有排车和车队能力的边界

现有海外排车正式入口是 `apps/admin-web/src/modules/overseas-warehouse/`，后端入口在 Lastleg `dispatch/`；排车状态、PDA 拣货、发车门禁、转派送和派送完成属于排车/派送链路。目的港码头车队选择属于货柜聚合的码头拖车链路，使用供应商主档和独立权限。车辆主数据只维护车辆档案和可复用属性，不能成为排车状态或码头车队事实的第二个写入口。

### 3.4 已验证的现有执行顺序

本节记录共享车次接入前的执行链，作为继承关系与缺口的对比依据；当前车次增量以第 10 节为准。不表示已经完成真实环境验收，也不把新增原型审核作为既有前置条件。

1. **预排车**：候选列表可跨客户查询，但单次创建排车须选同一客户、同一海外仓的托盘。不能把“跨客户可查看”理解为“一张排车单允许跨客户混装”。依据：`DispatchService.resolveCustomerScopeForPallets`、`requireSingleCustomerScope` 和 `preArrange` 的仓库校验。
2. **维护本次排车信息**：当前请求保存车牌、司机姓名/电话、承运商名称、预约和预计时间等文本/快照；未形成车辆档案 ID、司机档案 ID 关联及资格门禁。车辆档案状态不等于本次排车状态。
3. **发车前完成两组条件**：现场 PDA 完成拣货并核平箱数；后台在允许阶段执行“转派送”。转派送可早于拣货完成，但货物必须已收货并绑定实物托盘，且必须早于发车。两组条件不是必须按固定先后完成的串行操作。
4. **转派送生成单据**：一张排车单对应一张出库单，派送单按目的地分组。FBA 仓是常见分组；当前 `DeliveryTransferService.deliveryGroupKey` 也处理私人地址与邮编，并以目的仓编码或 ID 分组，不能将能力范围仅写成 FBA。此时出库单为 `WAIT_OUTBOUND`，生成派送单本身不表示车辆已出发。
5. **PDA 发车**：当前 `DispatchPdaWorkflowService.requireVehicle` 只检查车牌非空；还检查绑定仓、拣货任务完成、全部箱数核平、排车为 `READY_TO_DEPART`、出库单为 `WAIT_OUTBOUND`。通过后扣减对应已拣库存，出库单变为 `OUTBOUNDED`，排车变为 `DEPARTED`。没有现成的车辆主档可用性、司机证照或两级审核门禁，不能将“车牌非空”表述为“车辆与司机完整合规”。
6. **目的地分别签收**：`DeliveryDocumentService.save` 在有效状态下把非空 `RECEIPT` 资料保存进正式快照，才自动完成当前派送单；单纯上传文件不触发完成。一张派送单完成不代表其他目的地同时完成，也不自动证明新增的“整次出车记录”已经结案。

并发与快照边界也有现状差异：车辆主档有 `recordVersion`，但 `DispatchRequests.Update` 没有客户端期望版本，`DispatchService.update` 使用行锁且仅允许 `PENDING_DEPARTURE` 编辑；行锁不等于能识别用户提交的过期表单。转派送会把当时的车牌/司机等信息保存到派送单，后续修改排车是否同步、是否重新审核必须单独规定。排车取消、移除托盘、出库取消是不同命令，不能将其理解为任意阶段一键撤销整条链路。新增审核和改派须同时定义并发版本、审核依据快照和关联单据处理规则。

现有执行链为：**预排车 → 维护车牌等任务信息 →〔PDA 拣货核平 + 发车前转派送〕→ PDA 发车出库 → 各目的地分别签收**。司机资质、两级审核、运维、行程汇总与自有/外配工作台如何接入，属于本次新增设计。

### 3.5 本次排查发现与纠正

以下原型行号均指第 1 节的外部 `新版.html`，通过静态脚本核对，未作浏览器视觉验收。

| 严重程度 | 先前表述的问题 | 本次核对结果与处理 |
| --- | --- | --- |
| 高 | 把“调度审核 → 理货员审核”直接接在现有 PDA 流程前，且任务写成只复用现有审核 API | 原型 `18589-18599` 确实演示调度通过转理货审核、理货通过进入装车中；已检查的 dispatch Controller/DTO/Service 没有对应审核命令。普通排车编辑 `18804-18829` 也没有重置审核阶段/驳回状态，只有散板上下文分支写待调度审核。原型本身的提交与驳回重提尚未闭合；需新增审核契约，并确定与 PDA 开工/发车的关系，不能直接复用不存在的 API |
| 高 | 把司机页面显示“已阻断派车”当成真实业务阻断 | `openDriverDetail`（`22702`）只生成提示文字，且将“即将到期”也显示为阻断，与“30 天提醒”文案不一致；排车保存未联查司机档案，当前服务端也未关联司机资格。资格计算、临近到期是否阻断、提交和发车时是否重新核验需要分别定义 |
| 高 | 把自有/外配页理解为排车生成后的现成视图，把外接金额直接解释为车队应付 | `vehicleBusinessRecords`（`22627+`）是独立示例数组；排车用另一组 `outboundVehicleData`，出车统计又用 `vehicleTripRecords`。现有脚本没有证明三者自动同步。外配行同时含自有托数/成本、外接托数/金额，且示例混用人民币与美元；只能说明原型要展示这些列，不能据此决定货源、承运关系、应收/应付或财务自动入账 |
| 中 | 把出车记录的删除函数算成可用按钮，并把导出写成原型未要求的可选扩展 | `8953` 有“导出Excel”按钮，但只弹 Toast；`renderVehicleTripRecords`（`22953`）行操作只渲染编辑；`deleteVehicleTripRecord`（`23057`）仅找到定义，未找到调用入口。更正为：新增/编辑可演示，导出是占位交互，删除存在未接入函数 |
| 中 | 默认无 DELETE 就提供停用/作废，且一律按车辆主数据合同处理 | 车辆主档当前无 DELETE；排车则有 DELETE 路径承载取消，HTTP 方法不能代表物理删除。新司机、运维、出车记录的停用、作废、删除或更正须各定生命周期，不能凭缺少端点自行增加替代动作 |
| 中 | 直接描述“司机/车辆资格齐全 → 发车”，并遗漏单客户同仓与私人地址派送 | 当前实际条件和单据关系以第 3.4 节为准。完整资格校验是新增工作；“转派送在发车前”这一结论经代码复核仍成立 |

## 4. 业务决策与剩余边界

以下为决策清单，按受影响工作包分别冻结；已有代码规则不因列入讨论而自动失效。无关问题未定不阻止已确认部分的实现；未定业务不能由页面本地字段代填：

1. 本轮是否一次纳入新版原型的司机管理、自有业务、外配业务、出车记录和派送车队报价，还是先完成车辆主档的第二阶段增强。
2. 国内车辆和海外车辆是否共用同一车辆主档；区域是否只是查询维度，还是决定所属仓、时区、单位和可派送范围。
3. 自有车辆、外派车辆和租赁车辆的归属枚举；外派车队、司机和车辆之间是否允许一对多历史绑定。
4. 车辆状态、排车状态、司机资格状态和派送状态分别由哪个服务维护，哪些状态可以相互阻断；现有五种车辆状态与原型三种状态如何映射。两级审核状态应与拣货/装车/发车的实际执行状态分别定义，不能用审核通过伪造现场开始时间。
5. 已确认采用 30 天临近到期提醒及第 20 项禁派规则。尚需确定必需资质清单和审核角色：驾驶证之外的体检、培训/安全、保险是否全部必填，不能由原型字段自动推为必需。
6. 车辆运维记录是否要进入财务费用池；保养、加油、维修和救援费用的币种、汇率、税费、结算单关联和付款状态由谁确认。
7. GPS/路线/ETA 的设备和数据来源；如果没有正式来源，原型中的轨迹、路线偏离和自动告警是否延期。
8. 按用户要求已将“一次实际出车对应一个车次，多条货物明细，出车记录自动汇总”写入方案基线，见第 4.1 节；人工历史补录、车次中途换车和取消分支的规则在开发合同中细化。
9. 已将外接应收/实收、本趟直接成本和自有/外接成本分摊分别展示写入方案。尚需确定成交价按托还是按整单、实际数量变化后的改价、币种/税费和结算引用；计算结果由服务端输出，人工更正保留原因。
10. 根据已确认外接含义，外接报价是面向委托方的销售报价，应关联客户/委托方，不能强制当作供应商采购价。原型“派送车队报价”是否另用于向外部车队采购运力、是否纳入首期仍需明确；若是采购价才关联供应商。两类报价各定适用路线、计价单位、币种、有效期、版本及导入匹配规则。
11. 司机证照、车辆运维照片、出车图片和签收凭证分别归属哪个文件业务范围、保留多久、谁有下载权限；允许的大小、MIME 类型、预览和下载规则是什么。
12. 分别定义车辆、司机、运维和出车记录的停用、作废、删除或更正语义及权限。车辆主档当前无删除端点；不能将这一现状推为所有新对象的永久规则，也不能默认创造作废接口。
13. 跨区域日期、时区和工作日边界如何计算；车辆、排车、派送和统计接口返回的时间采用什么时区。
14. 平台客户数据隔离和角色范围：车辆、司机、车队、报价及附件是平台级共享，还是按客户/仓库限制可见和可操作范围。
15. 司机和车辆是否允许多仓、多司机或多车队绑定；绑定是否保留有效期、历史和并发冲突记录。
16. 当前车牌在车辆表内全局唯一且编辑里程不能回退；是否调整唯一作用域、如何处理换牌/里程录错需要明确决策。新增状态迁移、占用/释放、冲突与更正审计须显式设计，不能无意取消已有约束。
17. 车队报价 CSV 模板的当前字段格式、单批上限、失败行处理、重复行策略和导入幂等键；不预设旧模板兼容层。
18. 出车记录原型已包含导出Excel入口，但尚未生成真实文件；需确认正式导出格式、字段、权限、范围上限及统计口径。
19. 已确认审核首期只展示详情并提供通过/打回，不预设业务检查清单；建议沿原型保留调度/理货两级并记录人员、时间、意见，打回必填原因。拣货/发车的阻断时点、改派后重审和跨单快照同步仍需在接口设计中明确；通过审核不自动代表开始装车。
20. 已确认：临近 30 天到期但仍有效时允许派车并提醒，预计任务结束前会过期则禁派；必需资料缺失、未审核、已过期禁派。提交/审核/发车的复核时点、预计结束时间缺失处理和临时换司机规则在接口设计中落实。
21. 已确认外接是利用承运自有货物的车辆剩余运力，顺路承接别人的货；属于货源/承运任务来源维度，不等于外包给其他车队。当前单客户排车规则是实现现状，新需求需要同车关联不同委托方的货物，推荐的行程与客户单据关系见第 4.1 节。
22. KPI 的“今日”、统计日期、去重仓库数、出车次数、托均价分别采用什么口径；列表/图表是否共用筛选条件。车队报价空值与零价、导入部分成功与整批失败的规则须同时定清。

### 4.1 本轮业务确认与出车方案建议

**已确认**：本模块管理车辆，同时安排自己的货物运输；车辆存在顺路剩余运力时承接外部货物，称为“外接”。一趟车可同时含自有业务货物和外接货物。原型“外配业务”的名称和外包承运暗示需要据此调整，建议用户可见名称改为“外接业务”；车辆归属（自有/外派/租赁）与货源类型分别记录，不从其中一个自动推导另一个。

**已确认**：审核先以详情展示、审核通过、打回为范围，不做未经确认的逐项业务检查表。建议保留原型两级入口，打回时填写原因，修改后重新提交；记录审核人、时间、意见和本次审核版本。司机资格不能因人工点通过就跳过服务端已确认的禁派规则。

**已确认的司机资格规则**：必需资料缺失、未审核、已过期时禁止派车。对于 30 天内到期但尚有效的证照，用户已明确选择“允许并提醒，任务结束前会过期则禁止”。计划预计结束时间用于派车校验，改派或时间变更后重新计算资格；缺少预计结束时间时不能直接判定满足该规则。具体必需资质清单和时间边界在合同中明确，不自动扩大为原型全部证照。

本次按用户“请写入后继续 Review”的要求，将该确认整理为以下判定表。表内“允许”仅表示通过此项证照校验，仍须满足车辆、审核、装载等其他派车条件：

| 证照与任务情况 | 判定 | 依据 |
| --- | --- | --- |
| 仍有效、超过 30 天到期，且有效期覆盖预计司机任务结束 | 通过此项证照校验，无临近到期提醒 | 按已确认的 30 天提醒窗口及任务全程有效要求推导 |
| 仍有效、30 天内到期，且有效期覆盖预计司机任务结束 | 允许，并展示到期提醒 | 用户明确确认 |
| 当前仍有效，但预计司机任务结束前会过期，无论是否已进入 30 天提醒期 | 禁止派车，需更换合格司机或更新并审核证照 | 用户明确确认；不能只检查“今天是否过期” |
| 必需资料缺失、未审核或已过期 | 禁止派车 | 前述已确认资格前提 |
| 未填写预计司机任务结束时间 | 草稿可保存，正式派车前要求补齐 | 第 4.4 节执行建议；不能默认为证照覆盖任务 |

证照有效截止日、时区及恰好触及截止时刻的处理仍按第 4.4 节明确，不以本表推定法定有效时刻。

下面的“一车次、多明细、分别签收、成本汇总”方案已按用户“写入后继续 Review”的要求纳入文档设计基线；表中明确标为首期建议的范围以及第 4.2 节问题仍待确认。方案写入本身不表示功能已实现，也不将未确认的边界自动定案；后续源码进度见第 10 节。

| 对象 | 建议口径 | 主要原因 |
| --- | --- | --- |
| 运输行程/车次 | 一次实际出车对应一个稳定业务编号，记录车辆、司机、起终点、计划/实际发车及完成时间；车次计划创建时即可建记录，发车后继续补齐实际事实，同一趟多目的地不拆成多次出车 | 能按真实运行统计，避免一车送多个仓被重复计次数 |
| 货物明细 | 行程下关联多条自有/外接承运明细；每条有委托方、来源单据、提卸货点、托数、重量、体积和约定费用。自有业务货物也保留原客户归属 | 同车可拼载，客户订单、库存、附件和费用保持各自归属 |
| 执行单据 | 在现有客户排车/出库/派送单之上建立共享行程关联，现有单据保持客户/仓库边界；行程只统筹物理车辆、路线和发车，不复制客户库存账 | 不直接解除现有单客户校验，也不把所有货假挂在同一个客户下 |
| 外接履约来源 | 首期建议人工录入外接委托和承运明细、分配到行程；进入本仓的外接货走真实收货/库存流程，异地提货须有独立交接证据，不虚构已入仓事实 | “接单”和“已收货”是不同事件；是否首期支持沿途提货应明确范围 |
| 剩余运力 | 先检查托位、限重和容积，预留外接货后立即占用；多点提卸按每一段在车货量核算，不能只看整趟总托数 | 防止同一空位重复出售或沿途超载；可用托数不是唯一条件 |
| 行程完成 | 所有承运明细均送达签收，或异常已按明确终态处理后，结束本次行程；一个目的地签收不完成整车。车辆是否可再次调度还需检查占用、位置和故障状态 | 支持多目的地、拒收/退回；不将付款完成或必须回原仓作为派送完成条件 |
| 出车记录 | 从行程及各客户执行单据自动汇总；人工只补充实际里程、油耗、凭证及有权限的更正，保留原因和历史 | 避免再建一张自由填写、与实际运输脱节的出车统计表 |
| 收入 | 外接货的约定运费属于向委托方收取的运输收入，区分报价、确认应收和实收；自有业务订单的原有运费不能在车辆模块重复计收 | 能分析外接贡献，同时防止重复计费 |
| 成本 | 行程记录实际燃油、司机本趟费用、通行费、停车及其他直接费用；保养、保险等固定费用后续按明确规则分摊，账务仍走 Finance | 先得到可核对的单趟直接成本，避免把未分摊成本的结果叫完整利润 |

价格展示建议替换笼统“价格”为“外接应收、外接实收、本趟直接成本、自有货分摊成本、外接货分摊成本”。同路线、同规格可先按托数分摊直接成本；距离/占位差异较大时另定按占用空间与里程的规则。分摊值用于运营分析，不等于新增客户应付，也不自动生成正式账单。

示例（统一币种、同路线同规格）：一车容量 30 托，自有货 20 托，外接 10 托，外接确认运费 300，本趟直接成本 600。按托数分摊，自有货成本 400、外接成本 200，外接在该分摊口径下贡献 100；不包含固定费用，不能称为整趟净利润。托均收入只用外接收入除外接托数，整趟托均直接成本用本趟直接成本除全部实运托数，两个指标不得混用。

接入影响：当前“一张排车 → 一张出库 → 多目的地派送”仍是客户执行单据的现状；推荐增加的共享行程可能关联多组此类单据。必须另定按车统一发车的校验、失败重试和各客户状态推进协议；不能因新增行程就假定现有接口支持一次多客户出库。“空位放出去”首期建议由运营登记可接运力和外接预订，公开发布、在线接单或撮合平台需另行明确，不自动扩大本轮范围。

### 4.2 本轮 Review 后仍影响开发范围的问题

无需重新确认第 4.1 节已明确的外接含义、简化审核交互和司机临近到期规则。下面的问题按影响排序，建议均未冒充用户确认：

| 问题 | 为什么影响实现 | 建议首期口径 | 影响任务 |
| --- | --- | --- | --- |
| 外接货交到我方起运仓，还是需要司机沿途去别处提货？ | 前者可用现有仓库真实收货和 PDA 出库；后者增加路线站点、提货交接、分段容量及未入本仓的履约来源 | 首期先接送到本起运仓的货，多目的地派送；沿途提货另开范围。若沿途提货是核心业务，则在本轮纳入，不能伪造入库绕过 | VM-05、VM-04a、VM-07b |
| 外接委托方是否已是系统客户，谁付款？ | 单据、库存和应收需要稳定的客户及付款归属；货物原货主、委托运输的人、付款方可能不同 | 外接单选已有客户/委托企业，联系人独立记录；新委托方先按现有客户建档。是否需要工作台账号按实际需要处理，不强制外接人在线下单 | VM-00、VM-05、VM-06 |
| 两级审核分别在什么作业时点生效？ | “详情 + 通过/打回”的界面已定，但阻止拣货还是阻止发车会影响 PDA | 建议调度通过后允许开始拣货，理货通过且实际拣货核平后允许发车；审核记录与实际作业状态分开。关键货物/车辆/司机变化重审，但不回滚已经发生的拣货事实 | VM-04a、VM-07b |
| 外接运费按托数还是整单报价？货到后数量变化怎么办？ | 决定报价明细、成交金额、补差价与取消收费；原型单价和总价不能互相覆盖 | 首期支持按托/整单两种计价，保存成交价快照；实收数量与预订不同先重新核量并确认金额，不静默改价或放行超载。等待费/额外提货费等单独登记原因和确认 | VM-05、VM-06 |
| 外接预订何时占位、撤单后何时释放？ | 未确认询价不能永久占满车辆，已装车货物也不能通过取消按钮从库存中消失 | 询价不占位，确认承运后占位；发车前未执行的撤单释放，已拣/已装走正式撤回或退仓动作；发车后拒收/退回走异常处理。临时留位的超时和取消费另定 | VM-05、VM-04a |
| 是否首期承接超规格托盘、散货或特殊货物？ | “空 10 托”只对明确规格有效；现有 Admin 车型为大车 30 托/40000 LB、小车 15 托/10000 LB，不代表任意车辆都适用 | 首期建议标准托盘普通货，至少核验托数/规格、重量和体积；实际车辆容量独立维护，超规格/散货另确认计价与占位方式。重量未确认前不能按可用托数直接承诺承运 | VM-01、VM-05、VM-06 |

其他实现细节由合同设计给出具体方案，不把所有技术选择都退回给业务：同一客户执行单及同一批待发运货物不能重复绑定有效行程；不将这一限制扩大为原始客户订单永远不能按现有规则分批履约。行程与各客户执行单据保留稳定关联；整车发车需先校验所有本次发运明细就绪，保证重试不重复扣库存；客户只可见自己的货物、凭证和费用。车辆/司机的调度占用、变更历史与附件读取权限纳入相应后端门禁。

### 4.3 本轮发现的现有接口差距与修订

1. **转派送强制收费与“不重复收费”冲突**：`DeliveryRequests.Transfer.fees` 非空；`DeliveryTransferService.validateTransferFees` 要求存在正数 `DELIVERY_FEE`，地板/混装还要求装车费，购买预约要求预约费；`transferResolved` 会调用 `feeSources.publishApproved`。因此新行程不能无条件逐客户重放这套新增费用流程。建议新增明确的费用来源/覆盖关系，支持引用已确认费用与登记本次新增费用，Finance 为唯一账务事实；具体字段随 API 合同确定，不用零元或虚构费用绕过现有校验。
2. **一个平台行程不能等同于一张客户排车单**：现有 `DispatchService` 保留单客户、同仓校验，新行程统筹多个客户执行单据。需要验证某客户准备失败时整车不误发、重试不重复执行、取消只影响指定承运明细，不把平台行程 ID 当成客户归属。
3. **计划数量、实收数量与占用容量需分开**：接单时的预订不等于已到货；按实际装载检查每段托位、重量和体积。外接临时加货或少到货会改变余位和成交金额，不能让页面自行修改原出库事实。
4. **行程完成、车辆可派、费用结清为三个状态**：货物签收完成不自动代表已收到运费，也不必等待回到原仓才完成运输；车辆释放还需考虑位置、故障和下一任务时间。一次行程中途换车应保留交接/换车历史，不将原记录直接改成另一车牌而丢失追踪。

追加源码核对：转派送原先在同请求键、已转换排车及唯一键竞争三条重放路径直接返回旧结果，修改金额后可能表现为成功但仍沿用旧费用。本轮已在 `ll_outbound_order.request_hash` 保存首次业务请求摘要；仅请求键不同而业务内容一致可以重放，费用、计划时间、装载等内容不同则拒绝，原单据及已发布费用保持原事实。该修复解决请求重放误报，不代表第 1 项的费用覆盖引用已经实现。现有 Lastleg 费用查询按业务单据返回已登记来源，Finance 事件接收接口也不提供“该费用覆盖本票尾程哪些服务”的证明；后续须按实际承运明细、来源版本和明确服务范围设计引用，不能拿同客户任意已收费记录或总运费金额直接判定派送/装车/预约已包含。

本节区分接口差距与追加修复，实际实现范围和验证结果见第 10 节；未注明已实现的方案不能视作完成。第 9 节五轮 Review 是此前版本的记录，本节是随后业务确认后的追加核对。

### 4.4 司机规则写入后的追加 Review

本节记录 2026-10-02 本轮文档 Review。已确认业务规则保持第 4.1 节原意；下列边界是实现建议，不代表现有接口已经具备，也不把法定证照效力作推定。

**司机资格的执行建议：**

- 草稿可先保存缺失信息；正式分配司机、提交审核、审核通过、发车时由服务端重新计算资格。缺少预计任务结束时间时提示补齐，不允许通过正式派车/发车校验。
- 提醒按证照配置的有效时区和当地日期计算，剩余有效天数为 0～30 天时提醒。证照只有日期时，建议记录其当地有效截止日；截止日当天计划结束是否允许，取决于明确的有效截止时刻，不能由浏览器时区或固定加 24 小时推算。日期边界、夏令时和恰好到期时刻须覆盖测试。
- “预计任务结束”应覆盖该司机本次实际承担的驾驶任务；若还需返程、转场，不能仅以最后一票货物的预计签收时间代替。行程派送完成与司机任务结束分别记录。
- 更换司机、替换必需证照或调整预计结束时间时重新校验；证照关键内容修改后建议重新审核。普通联系人信息修正不应无条件推翻整车审核，重审字段由合同列明。
- 已在途时发现延误将跨过证照有效期，应提醒调度并登记处置/换司机；不得自动撤销已发车事实、回滚库存或将整趟标为已完成。实际交接保留时间、地点、双方司机和凭证。

**本轮优先澄清的业务问题：**

| 问题 | 当前结论与建议 | 不明确会产生的影响 |
| --- | --- | --- |
| 外接货从哪里装车？ | 已确认首版送到我方起运仓；沿途提货留待后续版本优化。对应第 4.2 节首项 | 影响真实收货、交接证据、路线站点及 PDA 范围 |
| “空位放出去”是否需要客户可见的发布入口？ | 已确认首版运营线下找货、后台登记余位和外接订单；客户工作台在线发布/申请留待后续版本，不以后台登记冒充线上接单 | 仅做后台登记不能被描述为已经完成线上发布或接单 |
| 两级审核卡在哪个节点？ | 已确认详情、通过/打回交互及首版时点：调度通过后开始拣货，实际核平且理货通过后允许发车 | 影响审核详情中的数量来源，以及 PDA 开工/发车门禁 |
| 哪些司机证照属于必需资料？ | 首版按驾驶证作为基础必需项执行，体检、培训/安全、保险先记录日期，不自动设为必填；这是本轮产品范围，不推定法定资质结论 | 影响缺件、未审核和过期的禁派范围；不能只确认到期算法而遗漏适用证照清单 |

这四项按本轮用户“按建议执行、先做首版”的确认推进。其余仍按第 4.2 节保留明确建议：已有客户/委托方建档、按托或整单成交快照、确认承运后占位、标准托盘普通货。未经确认不写成最终业务事实；这些问题只约束相关工作包，不重复询问外接含义或 30 天到期规则。已确认部分可继续细化和开发，但不能据此判定外接、审核及司机资格的整条流程已经冻结。

### 4.5 本次追加 Review：装载、占用与异常分支

本节是对本文方案的一致性 Review，不代表新增代码或环境验收。第 4.4 节范围问题继续待答；以下给出合同设计建议，避免重复增加业务确认问题。

| 发现的缺口或歧义 | 建议补齐的规则 | 对应任务与验收 |
| --- | --- | --- |
| 按客户货物明细直接累加托数，可能把多客户合托计算成多个实物托盘 | 装载以实物托盘和实际占用的标准托位核算；客户货量、收费托数和物理占位分别记录。同一实物托盘的重量、体积只统计一次，客户货物归属保留；不同卸货站点的货物是否允许同托须明确现场拆托方式，首期建议拆成可独立卸货的实物托盘 | VM-05：两客户同托不重复占位、不重复计重；客户费用仍分别核算 |
| 一票未到齐或被打回时，其他货已就绪，整车如何继续 | 任一当前发运明细未就绪均阻止整车发车。若要剔除该票，先完成有权限的改计划及必要撤拣/退仓，重新核算容量、费用和审核，再统一发车；不能靠忽略失败的客户单局部推进 | VM-04a、VM-05：一票失败全车不误发；剔除已拣货物不丢失库存与作业事实 |
| “货送完”与“司机任务结束”不同，过早释放会重复派车 | 货物履约结束、车辆释放和司机释放分别判断；司机仍承担返程或转场时继续占用。允许提前建下一车次计划，但正式分配须检查资源占用；换车/换司机保留交接事实 | VM-02、VM-05：全部签收但司机尚在任务中，不能分配重叠任务；不因费用未结清而无限占用 |
| 文档“一张客户单不能分配两车”的措辞过宽 | 防重复约束落在客户执行单与实际待发运货量上；原订单如按现有业务规则拆成不同批次，不因共享车次设计一律禁止分批。新增拆单能力不在本条自动承诺 | VM-04a、VM-05：重复发同一批货被阻断，合法独立批次不误拦 |

审核被打回后应展示原因并允许修改重提，已经完成的现场动作保留。装载或费用变化后，应分别确认新的装载依据与成交金额，不能用一次“审核通过”同时代表收货完成、货物发车和客户付款。

### 4.6 本次复核：承运承诺、审核范围与部分拒收

本次按“写入后继续 Review”的要求复核第 4.1 节：司机临近到期判定已经写入，继续按用户明确确认执行，不再次征求相同决定。以下三项是补充方案，尚未获得业务确认，不代表现有功能已实现；它们细化第 4.2、4.5 节，不替代其中仍待确认的范围。

| 需要补齐的边界 | 建议处理方式 | 对应任务与验收场景 |
| --- | --- | --- |
| 自有货优先是否允许挤掉已经确认的外接货 | 建议自有货在对外确认承运前优先安排；外接一经确认就占用承诺运力。之后自有货增加导致超量，应由调度协商改期、改车或撤单并留存结果，再释放或调整预留，不能自动取消外接或超载发车。外接预留与实际装载关联替换，不能在到货后把同一票重复计算两次 | VM-04b、VM-05：余位已确认给外接后新增自有货，提示容量冲突；外接从预订转实收时占位不翻倍；撤单按是否已拣/已装分别处理 |
| 审核通过究竟覆盖哪些单据和数据，修改后哪些审核失效 | 建议客户执行单保留各自调度审核，整车理货确认覆盖本次全部发运明细及装载版本；整车发车同时核对两者。增减货物、换车、换司机、改路线或延长任务后使受影响的通过记录失效，并重新检查资格、装载与容量；历史审核和已发生作业事实保留。联系人或纯备注修正不触发无关重审。审核所属对象仍需与第 4.4 节的审核时点一并确认 | VM-04a、VM-05、VM-07b：客户 A 通过不能代替客户 B 通过；旧页面提交旧版本不能批准新装载；改司机后不能沿用旧司机资格结果 |
| 多点派送中只有部分货物拒收，是否可以直接结束整车 | 建议已经签收的明细保留完成事实，拒收部分记录数量、位置、责任人和后续处置，保持未结案，直到有真实退回签收或经明确流程确认的交接终态。仅填写异常说明或关闭工单不能代替货物交接；需重派的货物另关联后续任务，不能通过改签收数量消除差异。货物结案之后仍分别判断车辆和司机是否结束任务 | VM-05：两站已签收、一站拒收时不能完成整车；部分退回的数量须与实发和已签收数量核平；异常说明保存不自动释放资源、不重复收取原运输费用 |

需要优先获得业务答复的四项已统一列入第 4.4 节：外接货装车地点、余位是否面向客户在线发布、两级审核生效节点、必需资质清单。“30 天提醒”已经确认，不等于驾驶证以外的体检、培训和保险都成为必填门禁。未决项仅约束相关工作包，不能据此宣布全模块已经具备开发或验收条件。

### 4.7 首版确认前的决策依赖记录（已由本轮确认解除待答状态）

2026-10-02 再次按当前路由、交互矩阵、车次发车服务与费用来源接口核对：核心业务及新增交互选择连续多轮仍未收到答复。已确认规则的实现和本地回归保留；不能用继续修局部缺陷或重复跑测试，代替下面的流程决策。当前未满足整模块交付条件。

| 待答入口 | 直接受影响的工作 | 当前证据与边界 |
| --- | --- | --- |
| 第 4.4 节：外接货装车地点、余位发布方式 | VM-04b、VM-05 的外接委托、收货/沿途提货、客户申请和占位流程 | 共同起运仓的客户执行单车次已有后端，但不是完整外接接单能力；不能据此排除沿途提货或 Client 发布需求 |
| 第 4.4 节：两级审核生效时点、必需资质清单 | VM-02、VM-04a 的正式派车、拣货、发车门禁 | 当前资格校验不代表审核节点已实现，也不能默认驾驶证以外所有证照都不需要校验 |
| Admin `PROTOTYPE_MATRIX.md`：车次页面承载方式 | VM-07b 的计划、分配、关联排车、装载、结案和资源释放入口 | 当前 `routes.ts` 无车次操作路由；新 PDA 发车已要求车次关联，缺少平台入口时不能按可操作闭环发布整个车辆包 |
| 同一矩阵：维修/故障/救援更新处理入口 | VM-03 的持续处理流程 | 原型只定义新增；服务端可更正记录，但页面仍未开放未经选择的新增行操作 |
| 第 4.3 节：原运费的服务覆盖与来源引用 | VM-04a、VM-05、VM-06 的不重复计费和费用展示 | 建议每票明确已含哪些服务并关联原费用来源；只对另行确认的新增项目计收。本节记录初始差距；现已接入按实际货物确认原费用覆盖，源码与验证见第10.9节 |

上述答复到齐或逐项明确后，按对应工作包继续实现；未答部分保持待确认，不代填为“通过”或通过旧行为回退发布。部署授权仍有效，不需要再次申请同范围授权；源码、配套 Schema/权限、操作入口和真实 HTTP 必须一起核对，环境状态继续只以两份正式部署/通信契约为准。

## 5. 任务拆分与依赖顺序

VM-00 的交付不是只列问题：对第 4 节每项记录“已确认现行规则 / 本轮采用方案 / 后置 / 待业务确认”、适用工作包及确认依据。司机资格和审核决策约束 VM-02/VM-04a；已确认的自有/外接含义与已写入的行程/金额设计基线约束 VM-04b/VM-05；第 4.2 节未决范围分别跟进；运维字段和附件约束 VM-03；报价匹配和导入约束 VM-06。未获得用户决策的项保留待确认，不由本轮 Review 代为批准。

以下是候选工作包，不是已批准排期。P0 表示本方案的前置工作，P1 表示后续候选实现，Gate 表示交付门禁；具体纳入范围在 VM-00 冻结。各包只同步实际受影响的前端、后端、OpenAPI、权限、SQL、测试与文档，避免重复安排页面工作。

| 编号 | 优先级 | 工作包与主要交付物 | 建议实现归属 | 依赖 |
| --- | --- | --- | --- | --- |
| VM-00 | P0 | 冻结范围、术语、单位、状态机、车辆/司机/排车边界、删除策略、文件和权限模型、各事实的服务归属与模块命名；形成确认版字段表和页面清单 | 产品/业务 + 后端/前端共同评审 | 无 |
| VM-01 | P0 | 车辆主档对齐：确认现有 `ll_vehicle` 字段；按 VM-00 结果决定是否补齐初始里程、停放位置、司机/车队关系、租赁状态、停运原因等主档字段；FBA、发车时间、ETA 和任务快照不得预设写入车辆表；按影响更新 DTO、OpenAPI、SQL、Mapper 和权限，向 VM-07a 交付字段合同；保留 `recordVersion` | Lastleg masterdata + Admin overseas-master-data | VM-00 |
| VM-02 | P0 | 司机主数据：司机档案、归属/仓库、驾照和资质日期、审核状态、附件、`canDispatch`/阻断原因；列表、详情、新增/编辑、到期提醒和独立权限；接入现有文件上传与附件归属契约，不把 data URL 当持久化方案 | Lastleg 新司机域 + 现有文件能力/IAM + Admin | VM-00；与 VM-01 并行 |
| VM-03 | P1 | 车辆运营记录：保养、加油、维修、紧急故障、救援费用、异常；记录版本、操作人、附件、里程阈值、核验/处理状态和费用边界；按车辆标识隔离记录，逐类型定义字段及处理/付款状态，向 VM-07a 交付 API | Lastleg 车辆模块（服务归属由 VM-00 确认） + Admin | VM-00、VM-01、附件/文件归属契约；可先做契约阶段 |
| VM-04a | P0 | 排车执行扩展：两级审核、驳回重提、车/司机关联与资格校验；定义 PDA 门禁、期望版本、审核后改派、转派送快照及取消联动；处理正数派送费必填与费用引用/不重复入账的差距（第 4.3 节）；复用已有命令并补齐缺失契约 | Lastleg dispatch/delivery；Admin/PDA 为直接消费者 | VM-00 相关决策；车/司机联动依赖 VM-01、VM-02 |
| VM-04b | P1 | 自有/外接工作台：按已确认顺路拼载含义展示货物明细、余位和预订；推荐按共享行程统计次数，自有货成本与外接应收分别展示。按第 4.1 节行程基线补齐数据关系与查询，GPS/自动财务入账按范围决定 | Lastleg dispatch/delivery；Finance 为账务权威 | VM-00 相关决策；依赖 VM-05 的行程合同；若消费审核/资格字段，再依赖 VM-04a |
| VM-05 | P0 | 行程与出车记录（已写入方案基线）：以一次实际出车为粒度关联多个客户执行单据，区分自有/外接货源；设计分段运力预留、统一发车与重试、各站点签收和异常终态；出车记录自动汇总并提供授权补充/更正与导出，不以统计页替代行程执行模型 | Lastleg 内的行程模块与既有 dispatch/delivery 协作；不预设新微服务 | VM-00 明确第 4.2 节提货/预订/计价范围；车辆关联依赖 VM-01，资格与审核依赖 VM-02/VM-04a 对应合同 |
| VM-06 | P1 | 报价：先区分外接销售报价与原型车队采购报价，按确认范围实现；外接关联委托方，采购关联供应商；明确路线、计价单位、币种、生效版本、启停、重复约束及 CSV 导入导出。外接承运明细保留成交价快照，报价后续修改不覆盖已确认成交金额 | Lastleg 业务报价 + 客户/供应商目录，Finance 为账务权威 | VM-00 确认报价用途；不以采购报价完成作为人工外接接单前置条件 |
| VM-07a | P1 | 现有车辆主档页面收口：按正式字段/状态更新 `VehiclesView.vue`、`VehicleDetailView.vue`、表单和 `routes.ts` 描述；清理“派送订单/更换记录已具备”的陈旧文案；运维/异常页签仅在 VM-03 契约就绪后开放；把排车列表继续指向现有正式排车路由 | Admin overseas-master-data | VM-00、VM-01；开放运维页签时再依赖 VM-03 |
| VM-07b | P1 | 新页面正式接入：更新 `adminNavigation.ts`、模块 routes、权限守卫、排车审核/司机/业务/出车/报价页面与弹窗，补齐加载/空态/错误态/无权限态；不复制排车页面 | Admin 前端 | VM-00 相关决策；分别依赖 VM-02、VM-04a/VM-04b、VM-05、VM-06 对应合同 |
| VM-08 | Gate | 质量与验收收口：前端定向测试、后端 Controller/Application/SQL/OpenAPI/IAM 合同、Gateway 路由合同；1920×1080/100% 页面人工验收证据；字段、状态、权限、附件和异常场景回归 | 前后端共同 | 各工作包完成后 |

### 5.1 建议的并行边界

VM-01～VM-06 负责业务合同与服务端实现，页面由 VM-07a/VM-07b 对应承接；表内提及页面是验收范围，不重复建立两份前端任务。

- 后端可以将 VM-02（司机）与 VM-06（车队报价）并行；两者分别定义司机资格和已确认用途的报价，不共享未确认的自由文本字段。
- VM-03 的记录模型可以先做契约和表设计，但在 VM-01 未冻结车辆主档主键、单位和附件边界前，不应开始页面联调。
- VM-04a 与 VM-04b 分别估算和验收；工作台只读部分不等待整套审核完成。PDA 若因新审核/资格门禁调整，应沿既有排车执行接口及应用指引修改，作为 VM-04a 直接消费端验证。
- VM-07a 可在现有车辆主档合同确认后先行收口；VM-07b 按各自 API、权限和错误码就绪情况并行接入。原型页面不能直接复制到 `src/prototype/` 作为正式功能。

## 6. 验收清单

以下是未来实现的验收要求，本次文档 Review 不表示这些功能或测试已经完成。只对本轮实际纳入的工作包执行对应验收。

### 6.1 合同和权限

- 车辆主档的列表、详情、创建、编辑、状态、导出路径与统一 Gateway、Controller、OpenAPI、权限逐项一致。
- 车辆、司机、运维记录、出车、车队报价分别定义权限资源；每类列表权限包含详情只读，写入与已纳入的导出权限独立，由服务端鉴权。
- 浏览器长整型 ID 按字符串透传；车辆主档沿用 `recordVersion`。新增审核/改派命令明确期望版本、幂等和错误码；现有排车编辑缺少客户端版本校验，若本轮涉及该命令则同步补合同与受影响调用，不能把这一缺口写成已完成。
- 页面只开放有正式合同的动作；HTTP DELETE 不等于物理删除，取消、作废、停用、更正各按对象生命周期校验并保留对应审计。

### 6.2 页面和业务

- 车辆列表支持归属、区域、关键词和状态查询，操作列固定在第一列；空态、加载失败、无权限和导出失败可恢复。
- 排车详情/编辑复用现有路由；新增审核必须验收提交、逐级通过、驳回重提、修改后重审及 PDA 门禁。各客户执行单据的单客户同仓限制、收货后转派送和发车前置条件均由服务端校验；平台行程可关联多客户单据，不能把子单限制直接套在行程上。
- 车辆详情只展示服务端真实返回的主数据；派送订单、更换历史、运维记录和异常页签只有在对应接口存在时开放。
- 路由标题、描述和页面实际数据范围一致；未提供派送履约/更换历史时不得用路由描述暗示已具备。
- 司机过期、待补件、待审核和不可派状态由服务端资格结果驱动；到期提醒不能只由浏览器当前日期计算。
- 自有/外接业务按顺路拼载口径取数；一车多个客户/目的地不重复统计出车次数。外接报价、应收、实收和车辆成本分别记录，自有业务原有收费不重复计收。按行程方案验证各客户单据与库存隔离、每段容量占用、重复预订/取消和统一发车重试。
- 出车记录的用时、托均价、油耗和图表总计使用统一单位和服务端统计口径；筛选条件由服务端参与分页和统计。
- 车队报价导入能展示逐行校验结果、重复组合和失败原因；导入具备幂等或明确的重复处理规则。
- 报价区分未报价与零价；导入按确认策略检验部分成功/整批失败及重试重复行。统计验证筛选范围、仓库数与出车次数、加权托均价、零托数和多币种分组，页面数值和导出一致。
- 司机列表/详情的到期提醒与实际命令阻断一致；审核后变更车辆或司机、临近到期、已过期、缺件、未审核分别验证，不能仅验收提示文案。
- 司机资格补验到期前第 30/31 天、到期当天/次日、计划结束恰好触及有效截止时刻、跨时区/夏令时、缺少预计结束时间及预计结束延后；所用预计结束覆盖司机承担的返程/转场。已在途发生风险只进入告警与处置，不回滚出库事实。
- 运维记录须验证车辆 A 的新增/编辑不影响车辆 B；维修项目/地点、救援项目/地点等已确认字段保存后能正确回显；处理状态和付款状态分别读写，不以共用弹窗导致字段丢失。
- 签收上传与资料保存分别验证：上传未保存不得完成派送；多目的地仅完成当前单，出车汇总按确认规则结案。原型装车完成时间与发车时间混写不得直接作为正式用时口径。
- 保留现有车牌规范化/唯一性、里程不可回退、主档版本冲突规则；新增占用及资格门禁后分别覆盖维修/停用车辆、过期司机、重复派车、审核后改派及取消。尚未确认的新状态不以页面标签代替正式迁移。
- 费用验收覆盖已收费自有业务、外接新增运费、混装/预约附加费、同车多客户及失败重试；每个真实收费来源只入账一次，不以 0 元占位或额外虚构一笔派送费通过校验。行程分摊只是运营分析，不重复发布客户账务费用。
- 预订数量与实收数量变化须重新核量和确认金额；已拣/已发运不能通过简单取消释放为未发生业务。拒收、退回、中途换车应保留关联与证据，分别核对行程结束、车辆释放和费用结清。

### 6.3 工程与人工证据

- 前端运行受影响模块定向测试和类型检查；后端运行车辆/司机/运维/报价相关单元与合同测试；跨服务接口变化补跑 Gateway 路由合同。
- Admin 视觉按 1920×1080、浏览器缩放 100% 检查，至少覆盖列表、详情、弹窗、附件、空态和错误态截图。
- 真实 HTTP、部署、数据库写入和 Jenkins 不在本规划文档中默认执行；需在对应环境获得明确授权后单独验收。

## 7. 当前不纳入本轮的实现承诺

- 不把外部 `新版.html` 复制进正式 Admin 页面，也不把原型内存数据、data URL 附件或 Toast 成功提示当作实现证据。
- 不为兼容旧原型同时保留第二套车辆接口、旧字段别名、双写或独立海外 Gateway。
- 不在未确认 GPS 数据源、路线告警规则和财务归属前实现自动轨迹告警、自动 ETA 或费用结算。
- 不把司机、保养、加油、出车和车队报价数据塞进 `ll_vehicle` 作为临时扩展；每类事实先确定权威归属和生命周期。
- 不通过车辆主档页面推进排车、PDA 拣货、发车、派送完成或码头提柜状态。

## 8. 现状证据入口

- Admin 现有车辆实现：`apps/admin-web/src/modules/overseas-master-data/`。
- Admin 现有原型核对：`apps/admin-web/src/modules/overseas-master-data/PROTOTYPE_MATRIX.md`、`CONTRACT_GAPS.md`。
- Admin 当前导航：`apps/admin-web/src/core/navigation/adminNavigation.ts`。
- Lastleg 车辆 Controller、应用层和持久化：`baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/masterdata/vehicle/`；详情排除说明见 `adapter/in/web/PlatformVehicleController.java:49-53`。
- Lastleg OpenAPI：`baiyue-firstleg/lastleg-service/src/main/resources/openapi/overseas-master-data-v1.yaml`；车辆详情排除说明见 `:158-160`。
- Lastleg 车辆表：`baiyue-firstleg/lastleg-service/src/main/resources/db/lastleg.sql` 中的 `ll_vehicle`。
- 车辆权限：`baiyue-firstleg/iam/src/main/resources/db/lastleg-permissions.sql`。
- 文件能力参考：`baiyue-firstleg/file/`（具体业务类型、大小/MIME 和权限仍需在 VM-00 冻结）。
- 现有排车/派送：`apps/admin-web/src/modules/overseas-warehouse/`、`baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/` 和 `delivery/`。
- 海外仓业务页面 ID 与路由索引：`docs/海外仓业务/README.md`（其中架构入口描述以当前统一 Gateway/Auth 正式契约为准）。

## 9. 本次连续 Review 记录

以下轮次从用户要求连续复核后重新计数，每轮在上一轮修订结果上继续；修复对象为本规划文档，原型和业务代码缺陷仅作为事实记录与候选任务。

| 轮次 | 核对范围 | 发现及文档修复 | 复查证据 |
| --- | --- | --- | --- |
| 第 1 轮 | 原型页面、可达按钮、记录读写 | 更换历史无容器；运维扩展未按车隔离；维修/救援表单与保存字段错配；处理/付款状态混用；隐藏面板不能算可操作功能。已修订第 2 节及对应范围判断 | 原型 `9024-9051`、`23196-23202`、`23240-23277`；精确搜索历史容器仅命中函数引用，扩展记录读写无车辆键 |
| 第 2 轮 | 服务端流程、状态与并发边界 | 补齐车牌规范化/全表唯一、里程不可回退；明确五种主档状态不等于原型三状态；纠正“所有编辑已有版本校验”，记录排车编辑缺期望版本；补转派送后快照变更/取消联动决策。已同步第 3、4、6 节 | `VehicleApplicationService.create/update/changeStatus`、`presentation.ts`、`DispatchRequests.Update`、`DispatchService.update/removeItem/cancel`、`DeliveryTransferService.transferResolved`；逐项核对方法体后记录现状，未声称新增约束已实现 |
| 第 3 轮 | 决策、任务依赖与验收对应 | 拆分 VM-04a 执行扩展和 VM-04b 查询工作台，取消出车统计对整套新审核的无条件依赖；明确 VM-07a/VM-07b 承担 Admin 页面，PDA 门禁变化归 VM-04a；新增逐车运维隔离/字段回显验收；VM-00 按工作包交付决策结果，未决问题不阻断无关部分 | 复查全部 VM 编号引用均有定义，前端与服务端分工可对应；第 1/2 轮发现已落到任务或验收；因仍发现实质依赖问题，扩展为 5 轮 |
| 第 4 轮 | 指标、报价与证据措辞交叉核对 | 修正“今日”标签与实际取数、仓库数与出车次数混用；补托均价、空报价/零报价、导入部分成功口径；将测试文件存在与测试通过明确区分。已补原型差异、决策 22 和验收 | `renderVehicleBusiness`、`renderVehicleTripCharts`、`validateDeliveryFleetQuoteDraft`、`confirmDeliveryFleetQuoteImport`；定向枚举测试源码，仅记录入口不报告运行通过 |
| 第 5 轮 | 全文一致性与交付审计 | 将原型统计说明移回原型章节，修正审查记录中未拆分的旧任务简称；逐项核对前四轮修订、命名页面/弹窗、决策编号、任务引用和证据路径。未发现新的阻断性文档问题 | 第 1 节原型哈希复核；页面/弹窗 ID 与原型定义对应；任务定义、依赖与引用检查；第 8 节证据入口存在；Markdown 表列和章节检查。本次不运行功能测试，不宣称原型缺陷或业务功能已修复 |

## 10. 开发增量与后续接入（2026-10-02）

### 独立任务拆分与交接（2026-10-03，已确认四任务协作）

用户已确认创建三个用户可见独立任务，加当前对话共四个一起处理，目标为车辆全流程跑通。三个专项为①车辆成本与财务闭环；②车辆报价与运营统计；③车辆在途异常与改派；当前对话负责车辆总控、集成部署与跨模块验收。稳定task_id及授权边界唯一维护在[测试环境独立任务协作登记](../独立任务协作登记.md)的“车辆管理四任务协作”段。其他旧任务仍不自动恢复。

| 独立任务 | 唯一实现范围 | 交接边界 |
| --- | --- | --- |
| 车辆成本与财务闭环 | Lastleg `fleet/trip/FleetTripCost*`、`PlatformFleetTripCostController`及直接测试/合同；后续Finance车辆成本领域与Admin独立成本组件/API | 接续当前未提交草稿：成本登记、更正、按币种汇总、DEPART实物依据及同路线托位分摊。源码test-compile及新增持久化/现有分摊政策定向测试通过；尚需API权限/合同门禁、前端、部署及真实HTTP。未执行SQL、部署或真实成本HTTP。维修救援按公司成本还是客户分摊的问题仍待用户答复，不能擅自把车辆自身费用挂给客户。Finance共享账单/结算入口修改须先列明路径交总控协调 |
| 车辆报价与运营统计 | 新的Lastleg `fleet/quote/`、`fleet/reporting/`及各自测试/合同；Admin独立报价/出车运营页面、组件/API | 报价区分外接销售与车队采购；统计基于实际车次、发运及原费用来源，一趟多目的地只计一次出车。成本通过上一任务正式契约读取，不复制成本表或估算成财务实付。不得改写车次执行命令 |
| 车辆在途异常与改派 | Lastleg车次执行/改派/结案、实际调用到的dispatch和资源边界；Admin异常操作组件及海外PDA直接操作页面 | 保留原客户单据、库存、费用和历史；涉及共享FleetTrip模型或PDA入口时先申报精确文件，独占写入后实施；不以发车前换车冒充在途交接完成 |

总控保留共享 `TripDetailView.vue`、路由、导航、权限定义、IAM权限种子、模块/统一SQL和主契约的集成写权限；独立任务提供明确的接入清单，不同时修改这些文件。Maven构建、Jenkins、数据库结构准备及共享真实HTTP/浏览器验收窗口由总控串行安排；工作在当前目录和当前分支，不创建worktree，不提交他人的未完成改动。当前成本草稿涉及的5份SQL/数据库说明文件亦暂由总控持有，不随成本实现自动转交。

成本交接追加：Admin `api/tripCosts.ts`、`components/TripCostPanel.vue`及直接测试已接草稿，`TripDetailView.vue`按页签懒加载，`permissions.ts`增加两项成本写权限；680px登记/更正和1080px历史弹框，编辑先取最新版本，不变内容不写入，未知创建响应保留原幂等键重试。金额与分摊按币种分别显示，未登记/未分摊不补零。模块103项测试通过；未将本地草稿视为已部署或真实页面验收完成。

本节仅记录本功能源码与本地检查，不维护环境部署状态。环境部署、已验证场景和未关闭验收项仍以根指引指定的两份主契约为唯一入口。整体开发目标保持第 5、6 节全范围，以下局部成果不能作为完成依据。

| 工作包 | 当前源码与验证证据 | 尚需完成 |
| --- | --- | --- |
| VM-01 车辆容量与占用约束 | `ll_vehicle` 和既有车辆API、列表/详情/编辑/CSV补齐托位、载重kg、容积m³。三项同填或全空；未知容量不能分配到车次。CSV使用车牌作为业务标识。车辆应用层通过 `VehicleAssignmentGuard` 在车辆行锁内检查占用，车次占用时禁止直接改车牌/车型/区域/归属/容量及状态，备注、电话、合法里程修正保留现有能力 | 实际运维故障、中途换车及车辆释放与签收的联动继续接入；车辆页面真实环境视觉验收待执行 |
| VM-02 司机后端基础 | Lastleg `fleet/driver/` 新增司机与不可变历史表、列表/详情、创建/编辑、启停、审核、打回重提、驾驶证上传/读取、资格预览；写入使用行锁与版本条件，关键身份/证照变化和替换附件重新待审。OpenAPI `fleet-drivers-v1.yaml`；IAM 六项独立权限；模块与统一 SQL 同步。补齐可驾驶车型、语言/服务区域、体检/培训/保险日期；所属仓库引用国内公共有效目录并保存编码/名称快照 | 其他资质是否必需不由原型自动推定；派车命令源码已接入（见 VM-04a），真实环境验收未完成。当前启停与证照审核状态不冒充行程“任务中”状态 |
| 司机文件 | File 新增 `FLEET_DRIVER_LICENSE`，固定平台 0 与司机复合归属，非空 PDF/JPG/PNG、最大 10MiB、MIME/签名验证；Lastleg仅允许当前或历史已关联附件读取；上传不会通过审核。Admin 居中弹框预览图片/PDF，关闭释放Blob并忽略迟到响应 | 文件服务真实 HTTP、权限负向及1920×1080视觉验收未完成 |
| VM-03 / VM-07a 车辆运维 | Lastleg `fleet/maintenance/` 提供保养、加油、维修、故障、救援、异常逐车分页、创建、更正和历史；两表为 `ll_fleet_vehicle_record` / `ll_fleet_vehicle_record_history`，接口 `fleet-vehicle-records-v1.yaml`。Admin按原型接入六类记录，保养/加油680px、其他四类620px居中表单；保养加油图片按原型在新标签页查看 | 维修/故障/救援的更新处理行操作已开放，异常编辑已接入。`VehicleCareModels.Incident.reportedCost`只保存申报金额；`VehicleCareService.response`对维修/救援固定返回`UNLINKED`，构造依赖及Controller没有财务关联命令，不能把记录保存或处理完成解释为已入账/付款。财务关联须补真实费用来源和Finance状态读取；删除/作废语义仍未定。环境证据见正式主契约 |
| 司机 Admin 页面/API | `DriversView.vue`、`DriverDetailView.vue`、编辑与预览弹框已接真实 API，注册导航和路由；统一 HTTP、长整型 ID 字符串、版本透传、multipart、业务错误追踪。列表一次请求包含分页和同筛选统计；后台按各证照时区分组，在只读重复读事务中取数；详情历史按需加载。修改预计结束时间或档案后提示重新校验，不伪造资格结论 | 真实页面请求量、样式/交互、部署验收未完成；客户端与PDA仍随车次/承运流程接入 |
| VM-04a 派车门禁 | 车次分配/改派与PDA整车发车均调用 `DriverService.requireDispatchable`，在事务内锁司机并复核资格与真实证照文件；延长任务时间同样重新校验。PDA返回整车门禁与30天到期提醒，预计结束前过期阻断 | 本地事务测试已覆盖发车资格，真实HTTP未验收；审核时点已按本轮首版确认落地，见调度/理货审核增量 |
| VM-05 车次计划与占用 | `fleet/trip/` 新增幂等创建、分页/详情、改计划、车/司机分配与改派、取消、历史接口；OpenAPI `fleet-trips-v1.yaml`，表 `ll_fleet_trip` / `ll_fleet_resource_assignment` / `ll_fleet_trip_history`。创建可先不分配资源；分配锁车辆和司机，唯一资源键防重复占用，失败回滚，取消释放锁行且保留历史 | 客户排车、整车发车和结案接入见下列增量；外接承运明细、正式页面、异常处置及费用闭环继续实施，创建计划不等于已出车 |
| VM-05 客户排车关联 | 新表 `ll_fleet_trip_dispatch` 以排车单为唯一有效关联；同起运仓可关联多个客户，客户归属取原单。新增带车次版本的关联/解除接口；`FleetDispatchGateway` 由dispatch适配器实现，同事务同步排车与尚未执行派送单的车/司机快照，不覆盖到达时间。关联后子排车禁止独立编辑/移托/取消，转派送禁止另填不同车辆司机；已拣货禁止直接解除或变更路线，发车前允许统一换车/司机或保持路线调整时间，保留全部拣货事实并清除旧装载确认。替换车辆检查已确认载荷，司机重新核验预计任务覆盖，失败整批回滚；取消车次前先解除关联。历史同时保存车次与关联清单 | 关联箱数不冒充实物托位；已拣货后的撤回、在途换车换司机及交接异常仍需补齐，发车前改派不等于完成全部异常处置 |
| VM-05 实际装载与整车发车 | `FleetTripExecutionService` 新增装载依据读取/确认，按实物托盘去重计量并调用分段容量政策；同托不同目的地要求先拆托，卸货站匹配来源目的键，确认记录来源hash、车次版本、实测值、人员和历史。PDA原发车入口提交车次版本，锁车次/资源及全部客户执行单；事务内逐单执行出库后统一变为IN_TRANSIT，失败整批回滚、同键重放整车结果。PDA显示车次、单数、到期提醒，发车后刷新真实状态 | 当前覆盖共同起运仓、已关联客户执行单；外接询价及预订占位已接入，来货/实际发运关联已接入源码；审核和Admin车次及装载页面已接入源码，结案/释放见下一行。H2使用真实排车/出库Mapper与事务，订单归属服务在此集成测试中隔离，实库及真实库存/费用闭环仍须HTTP验证 |
| VM-05 货物结案与资源任务结束 | `FleetTripCompletionService` 读取每票派送的签收或真实退回终态，核对数量覆盖本次实发，并冻结结案依据；退回时间读取RETURN_COMPLETED操作事实，不取可变updatedAt。车次COMPLETED只代表货物结案，车辆/司机继续分别占用；带幂等键、版本和实际结束时间/地点的独立命令释放指定资源，车辆同时确认在役/维修/停用/已归还状态。历史失败回滚资源释放及车辆状态，原请求重放不影响下一车次 | 不自动结清运费，也不重写派送/库存。当前处理正常签收及已完成退回；途中换车、货物部分撤回等异常流程继续补足，真实环境未验收 |
| Admin车次页面/API | `tripTypes.ts`、`api/trips.ts` 接入28个查询/写命令及独立权限；`TripsView.vue`、`TripDetailView.vue` 注册列表/详情路由，1080px `TripPlanDialog` 维护计划；`TripAssignmentPanel`、`TripLoadingPanel` 在详情分区维护资源与实测装载，货物结案、车辆/司机结束任务分别确认。列表一次分页请求，历史/装载/结案检查按需加载；未填写的说明使用标准动作说明 | 已按本轮确认接入首版，车次管理导航由总控集成；调度/理货审核、外接询价和占位已接入详情，外接来货/发运关联已接入，费用覆盖及环境验收仍须完成。真实环境操作与1920×1080视觉验收未完成 |
| VM-05 装载与成本政策 | `fleet/domain/TripCapacityPolicy`提供分段容量；新增未发布`FleetTripCostService`已调用`TripCostAllocationPolicy`，按不可变DEPART的实测标准托位及外接实收归属分摊。支持燃油、司机、通行、停车和其他直接成本，CNY/USD分别汇总；成本及当时整趟分摊保存历史，零金额与未登记区分，未发车/不同卸货站/归属未核平明确不自动分摊。Java持久化、并发幂等、回滚、权限和合同共13项通过，网关5项、初始化11项通过 | 当前是后端草稿，Admin成本工作台、完整发布门禁、结构准备、真实HTTP及页面验证尚未完成。运营登记不等于Finance入账或已付，不据此算完整利润。多路线分摊、成本统计及财务关联仍需完成；维修救援自身费用归属等待用户选择。环境事实继续见正式主契约 |
| VM-07a 车辆详情履约关联 | `VehicleDetailView.vue`已接`VehicleFulfillmentTable.vue`的派送与更换记录；Lastleg `VehicleFulfillmentService`/`VehicleFulfillmentMapper`提供车辆范围的分页查询。计划派送归当前车辆，实际发车后归DEPART快照车辆；换车按相邻ASSIGN快照保留原/新车辆、司机和当时排车成员，不按车牌猜归属。派送关联同时核对客户和排车身份 | 源码接通不代表部署或视觉验收完成；真实环境结论见两份正式主契约。没有车次关联的旧单不补猜历史；操作人姓名未写入现有快照时显示“—”，不把内部ID作为姓名展示。当前只读投影不等于完成在途换车命令 |

结案追加边界：原派送已签收后另发起退货，原运输按已有签收事实结案，不把后续退货改写为已完成，也不让原车辆因未及时点结案而被再次挂起；未签收的拒收/退回仍须实际退回完成证据。派送资料首次保存RECEIPT前新增关联出库单OUTBOUNDED校验，未出库时可以准备BOL/装车资料，但不能提前触发签收完成。已有LocalDateTime执行事实按服务端作业时区转换为车次Instant，避免直接当UTC导致完成时间偏移；车次自身存储继续使用UTC。

当前车次资源采用一个车辆/司机同时占用一个未释放车次的规则；其他未来计划可以先建立而不分配资源，不以预计时间已过自动释放仍未结束的任务。已实现计划、分配、客户排车关联、装载确认、整车发车、货物结案及分别结束资源任务；已装货后的取消、途中换车和其他异常处置仍须补足，不能用计划取消接口代替退仓或签收。

载重数据追加修正：`DispatchCandidateMapper` 不再用计费材积重填补毛重，来源不齐全时分摊毛重为空；该值属于计划分摊，实际装载仍须核验。`DispatchService`、出库托盘与出库/派送合计保留未知毛重，任一来源未知不展示部分重量合计。Admin 预排与排车详情显示待确认/空值，不把材积重或缺失值0当作载重。模块和统一SQL相应重量列已改为可空；尚未执行环境SQL。

司机区域复核修正：正式分配原本只接受海外司机，但分配后可以通过司机档案编辑把区域改为国内，原发车门禁只核验证照与姓名。现已在 PDA 发车预览和事务内正式发车共用区域/身份判断；档案变为国内后整车阻断，出库、车次版本及发车流水不推进，纠正档案后可用原失败请求继续。此规则复用已有海外车次范围，不把自由文本“可驾驶车型”自动解释为正式准驾车型匹配规则；车型匹配标准仍需单独明确。

共享派送服务回归修正：Lastleg 全量首次暴露 `ReturnOutboundPdaPersistenceTest` 四项失败，核对发现已有 PDA 契约要求逐退货箱扫码，但服务仍合并全部箱唛且忽略扫码载荷。现改为每个真实退货箱一条明细，详情返回箱码扫码行且不虚构托盘/仓位；扫码与重放严格核对指定箱码，执行前重新核对客户、仓库、来源退货单，日志写入失败时库存和任务同事务回滚。这是退货库存再次出库的既有链路修复，不等同于车辆拒收后退回入仓流程。

本次已运行的本地检查（按增量保留；同一门禁以最后一次明确结果为准）：

- Lastleg 9 个定向测试类累计 45 项通过：三项领域政策、司机服务、文件元数据归属、数据库事务/并发/跨时区统计分页、API/SQL 契约、真实方法权限拦截、公共仓库目录。最近一轮司机相关 7 类 33 项通过；未变化的两项车次政策复用此前结果。
- File 3 个定向测试类共 27 项通过：新增证照格式与归属，以及现有业务文件存储/服务回归。
- 数据库行为测试使用 H2 与当前建表定义；仅将 JSON 列替换为 H2 可读的文本用于本地绑定验证，不等于 MySQL 实库验证。已验证历史失败回滚、清空可选字段、同版本并发只有一次成功。
- Admin 新增 API 6 项、司机交互 9 项通过；覆盖分页/筛选每次单请求、历史按需读取、只读权限、审核版本、上传失败后重试不重复建档、预览释放以及预计时间变化后清除旧资格展示。`pnpm build --logLevel warn`（含类型检查）通过；全量 `pnpm test` 268 个测试文件、2160 项通过。自动测试不替代真实服务或视觉验收。
- 车辆/车次增量：车次持久化9项、API/SQL2项、权限1项，车辆应用5项、SQL1项、Controller权限1项通过。覆盖重复/并发创建、车辆并发抢占、缺容量/缺证照、改派失败保持旧安排、延期跨证照到期、历史失败全事务回滚、取消释放与车辆主档占用门禁。
- 客户排车关联增量：车次持久化扩展为15项，使用真实H2/MyBatis及事务代理验证跨客户关联、同仓限制、并发一单抢占、历史失败回滚、派送快照同步与清空、已开工改派整批回滚。连同API/权限、排车、PDA、转派送、SQL中文注释及OpenAPI回归共106项通过。Gateway与初始化合同14项通过，Mapper扫描313个通过；fleet/车辆定向依赖3项通过，完整依赖检查及AGENTS登记旧断言仍未通过。未执行环境SQL或部署，此结果不能证明MySQL并发或真实HTTP行为。
- 实际装载/整车发车增量：车次持久化扩展为21项，覆盖两客户同托只计一次、重复/缺失测量与超重、目的站不符、装载后来源改变、某票未就绪、第二票失败全事务回滚、发车时证照复核、跨仓/旧版本、并发同键仅一次执行；连同子单PDA、转派送、订单归属及API/权限/SQL定向回归共118项通过。海外PDA全量167项通过；H5与App资源编译通过（不是APK真机验收）。车次验收助手及两个主消费模块、脚本文档合同67项通过；新助手通过正式API创建测试车辆/司机/证照/车次，实测数据明确标为受控测试输入，不用SQL补状态；这些脚本尚未运行真实HTTP。PDA列表门禁按车次复用查询，仍须在真实环境检查请求量与耗时。
- 结案/资源释放与Admin接口增量：车次持久化扩展为27项，连同结案API/权限、车辆状态、派送资料/Controller/合同及SQL中文注释回归共58项通过；覆盖货物结案不释放资源、任务分别结束、维修状态与释放一起回滚、司机过期仍能结束旧任务、旧重放不释放新占用、退回须有真实终态操作证据、签收后新退货不重开原运输、未出库拒绝签收但允许准备BOL。Admin车次API新增6项通过；全量271文件2172项通过，类型检查及构建通过。Gateway与初始化基线14项、fleet/车辆依赖3项、313个Mapper扫描通过；全局门禁未关闭项仍按下文保留。本轮未运行共享环境SQL、部署或真实HTTP。
- 载重修正补跑候选SQL、预排/排车服务、转派送、出库/派送SQL及前端实际重量/排车详情检查；SQL计算回归覆盖完全未知、部分未知及完整毛重来源。当前前端全量 `pnpm test --maxWorkers 4` 为269文件、2163项通过；先前默认并发全量出现财务页面单例5秒超时，该单例独立复验通过，随后以4个worker全量通过，未修改超时阈值或财务代码。
- Gateway 路由合同 5 项、Mapper 扫描合同、统一 SQL 初始化基线 9 项及 fleet 切片定向依赖检查通过。司机 API 复用统一 Gateway 的现有 Lastleg 路由，无新增网关配置。
- 完整 Lastleg 依赖检查已修复并通过 10 项：退役 `LastlegSecurity*` 投影改为禁止恢复或引用；25 条现有跨域类引用逐条记录理由，不授权同切片其他消费者。`DeliveryDocumentSnapshot` 移到应用服务包，消除 DTO/model 包循环；新增依赖、通配放行、车辆应用层反向引用和新增包循环均有失败测试。钱包 Outbox 的粗粒度切片聚合环仍作为耦合报告保留，不声称切片全图无环；边界说明见 Lastleg 内部模块化基线。快照工具移动后的派送服务、资料、Controller 与长 ID 回归 66 项通过。
- 车次 HTTP 验收脚本补齐结案和独立资源释放：通过正式分配命令验证结案仍占用、单独结束车辆不释放司机、资源再分配后重放旧结束命令不清除新占用。无货核对计划最终正式取消并保留历史；失败保留原请求和资源，不自动重造。两处测试车辆创建已补必填 `status=IN_SERVICE`，避免仅凭宽松模拟响应误报可运行。助手及两个直接消费模块 70 项、Gateway 5 项通过，脚本文档 4 项与三个脚本语法检查通过；仍未执行真实 HTTP。
- 车次 HTTP 验收助手追加发车前改派：仅对 `prepareFleetTrip` 本轮创建的车次执行，首次确认装载后新建等容量车辆和合格替班司机，正式改派并回查货物/客户关联、拣货数量、路线及到达时间保持一致，旧装载失效、旧版本请求拒绝且无写入，再确认新装载并返回最终发车版本。原请求、前后快照和替换资源保存在报告 `reassignment` 中；未知结果保留 `CHECKING`，不自动重试。字符串版本按整数比较，覆盖 9→10 边界。留存车次仅按原入口确认装载，不补造或改派其资源。助手 18 项、两个直接消费者及脚本文档合计 85 项离线通过；这不是已执行的真实 HTTP 或页面验收。
- 脚本文档合同 4 项通过；本次指引更新后的 AGENTS 索引合同失败，5 项均涉及测试独立任务登记必须为空的旧断言。本功能未修改或清空任务登记，也未据此自动派工；该全局检查仍未通过，不计作司机索引已完成整体验收。
- 发车前改派完整回归：`mvn -pl lastleg-service -am test -q` 成功，Lastleg 报告 1081 项，1079 项通过、2 项跳过、0 失败/错误；跳过的是 `CargoDiscardMysqlAcceptanceTest` 和 `TaillegRealConsumerAcceptanceTest`，不能计作真实环境验证。车次事务测试现为 33 项，新增发车前已拣货改派、同路线延期、容量不足/证照覆盖不足拒绝、历史失败回滚，以及改派与发车并发只能一个成功；验证拣货、到达时间、客户归属保留，旧装载确认失效并可重新确认后发车。Lastleg 依赖 10 项、Gateway 路由 5 项通过；AGENTS 索引仍有前述 5 项登记旧断言失败。本轮未改海外 PDA，不将先前其 21 项定向结果描述为本轮回归；未部署车辆功能，未执行测试环境 SQL、真实 HTTP 或浏览器验收。

- Admin 编辑会话修复：司机与车辆运维编辑器按打开状态和业务对象隔离请求；切换司机/车辆、关闭或卸载后，旧保存/上传结果不得覆盖新表单、触发成功提示或继续上传后续附件。运维不确定创建结果的幂等请求仅供原车辆/原记录范围重试，不带入另一车辆。已发出的保存命令仍以服务端结果为准，不自动回滚档案。两组复现与回归共 22 项通过，Admin 全量 273 文件、2189 项通过，类型检查及构建通过。车辆详情说明改为业务可读提示；本轮无布局或新增操作入口变更，也未进行真实页面验收。
- 转派送重放修复：三条变更金额的重放路径先复现失败，再修正为摘要校验；另验证只换请求键且内容完全相同不重复创建或发布费用。复用现有请求摘要列，无新增表/列；模块和统一 SQL 仅同步该列的用途注释，未执行环境 DDL。完整 Lastleg 回归更新为 1090 项：1088 通过、2 项环境测试跳过、0 失败/错误；转派送服务 48 项、车次事务 33 项均通过，Gateway/依赖 15 项、初始化合同 10 项通过。该次回归包含当前共享工作区的退货记账增量，退货发布事实仍由正式环境契约维护；不将其算作车辆功能已发布。
- 首版车次页面接入：模块/密度定向88项通过，新增四项关键页面流程验证分页不逐行请求、只读详情与按需历史、创建不确定结果复用原请求、实物托盘去重及人工测量提交；类型检查与构建通过。首轮Admin全量274文件2193项中2192通过、1项输入提示合同失败，补齐6处提示后该合同与新流程合计5项复验通过；未将此描述为又跑了一次全量全绿。共享导航由总控集成并单独验证14项。AGENTS索引仍有5项旧任务登记断言失败；本轮无环境部署、SQL或真实HTTP/视觉验收。

接续顺序：Admin车次/装载操作入口与自有/外接委托预订 → 审核、逐站签收/异常及资源释放 → 运维/报价/统计与费用闭环 → 按授权部署测试环境、真实 HTTP、指定视口样式/交互及请求量验收。第 4.4 节按本轮首版确认执行；审核源码增量见第10.3节；外接接单和费用覆盖仍须继续实现。当前尚无部署或真实HTTP/浏览器验收完成证据，不以本地测试代替这些交付项。

### 10.1 保养及加油接入的实施边界

本增量沿原型已经定义的车辆详情页签及居中弹框推进 VM-03、VM-07a，未代替仍待答复的车次工作台承载选择。

- 记录固定绑定车辆内部主键，使用独立 `VR-` 业务编号并保留建档时车牌快照；更换其他车辆路径不能读取、修改或下载原车附件。创建按车辆、操作人和请求键去重，更正保留版本、原因及完整历史。
- 里程明确选择公里或英里；加油量明确选择升、美制加仑或英制加仑，不把原型含义不明的 `gal` 自动按某种加仑入库。上次、记录时、下次保养里程使用同一明确单位；下次里程须大于上次，但可低于记录时里程，以保留已经超过计划保养里程的真实情况。不默认套用每一万迈阈值。
- 发生时间使用带偏移的实际时间，保存为 UTC，不得填写未来记录；历史记录里程可以低于当前车辆主档里程。运维保存不更新主档公里码、车辆可派状态或财务，核验状态仅记录“待核验/已核验”。维修、救援处理与付款状态仍按原未决项单独设计。
- 照片类型 `FLEET_VEHICLE_RECORD_PHOTO` 固定平台与记录归属，仅非空 JPG/PNG、每张最大10MiB，每条最多20张。先保存记录再逐张上传；已上传结果保留，失败重试沿用原图片请求键。File校验文件签名，Lastleg核对复合归属，图片内容接口的HTTP200 JSON错误不能作为图片返回。
- 页面进入“保养及加油”页签才分别请求两类分页；不逐行预读详情或图片。编辑时读取该记录最新版本，保存使用命令返回值更新当前行；创建后刷新当前类型列表。上传失败不重复创建记录，明确的参数错误允许改正，未知创建结果保留原请求内容和键供重试。图片按原型在新标签页查看，关闭或页面卸载释放临时地址。
- 只读沿用 `vehicle:list`；新建、更正、上传分别为 `vehicle:record-create/record-edit/record-upload`。无新增菜单、Gateway配置或独立服务。部署涉及 Admin、Lastleg、File，以及 IAM三项权限和Lastleg两表的最新初始化定义；本轮没有执行这些环境操作。
- HTTP编排已接入 `phase4-overseas-master-data.mjs` 的内部 `vehicle-care.mjs` 助手：验证创建重放、版本冲突、不可变历史、单位、照片重放及字节一致，另建本轮车辆验证跨车拒绝并在结束时停用；保留原记录、照片与失败证据，不执行SQL或修复历史造数。离线合同包含故意跨车泄露时必须阻断的反向场景；真实HTTP尚未运行。

本增量验证：Lastleg完整回归1073项（1071通过、2项环境测试跳过），File完整216项通过；新增运维持久化/权限/接口/文件归属10项及File图片策略1项包含在其中。Admin全量273文件、2181项通过，含类型检查的生产构建通过。IAM权限目录补齐原遗漏的司机6项和新增运维3项常量，目录规模68项；IAM相关12项与Lastleg权限/API补验4项通过，不改变既有仓库角色授权。Gateway、初始化、依赖24项及315个Mapper注册检查通过；运维HTTP编排离线7项、脚本文档4项通过。初始化源当前为国内223表、海外143表、385项权限及566条角色授权，未向环境执行。AGENTS索引检查仍有同一组5项任务登记旧断言失败，未修改或清空登记表。

当前交付仍缺维修/故障/救援后续处理入口确认、车次页面及未决外接/审核范围、报价/运营统计/费用闭环，以及实际部署、真实HTTP、指定视口视觉交互与请求量验收；不能以运维局部接入或自动检查通过宣布车辆管理整体完成。

### 10.2 维修、故障、救援及异常增量

2026-10-03 编辑规则补充：服务端采用 NON_NULL 响应，空的里程单位、核验状态及事件选填字段可不返回；Admin `api/vehicleCare.ts` 将这些字段统一初始化为空值，再进入编辑表单，避免将保养默认值提交到维修/救援记录。打开已保存记录后没有修改内容时，保存不产生更正命令或新版本；脏数据比较以同一个表单快照序列化，不受响应字段排列顺序影响。真实环境结论继续只维护在正式部署契约。

运维独立回归已接入 Admin 正式验收入口的可选模块 `fleet-vehicle-care`，复用六类运维助手并创建本轮车辆。覆盖历史、照片、版本、跨车隔离，以及正金额/零金额与付款事实分离；失败保留记录和原始证据，结束停用专用车辆。该回归不表示公司车辆成本已经接入 Finance。

本次继续使用同一记录、权限和历史合同，扩展 `REPAIR/BREAKDOWN/RESCUE/EXCEPTION` 四类，不新建第二套车辆或费用台账。

- 维修及救援项目、地点分别保存；原型弹框读写错配已由明确字段替代。故障/异常保存描述、处理人和处理状态；异常另有轨迹、超时、派送、车辆故障四类分类。保养加油字段与这四类事件字段互斥，不能在共享表单内悄悄串写。
- 处理状态为待处理、处理中、已完成；处理中或已完成须填写实际处理人，系统操作人另行留痕。更正仍须版本和原因，保留此前字段和金额快照。事件处理不自动改变车辆主档状态、解除车次占用或完成货物履约；这些联动尚不能被宣称已经具备。
- 维修/救援费用是本条运维申报金额，允许未登记或明确零值；登记金额须有有效币种，运维保存本身不进行汇率换算或自动入财务。当前服务端对维修/救援返回只读 `paymentStatus=UNLINKED`，页面显示“未关联财务”；处理完成不能生成已付款事实。公司车辆成本及入账规则已按文首2026-10-03追加确认实施，正式Finance关联与状态读取尚待接入。
- 页面按原型新增四个详情页签，只加载当前车辆当前页签；四类新增及异常编辑均用原620px居中弹框。原型没有维修/故障/救援后续行操作，已发出“列表更新处理、复用居中弹框”或“仅登记结果”的选择，等待答复期间不添加新行操作。未给四类事件新增原型未定义的照片预览或删除入口。
- HTTP验收助手已覆盖四类新增、处理完成、重新读取项目/地点/处理人、分类型列表；补充“处理完成被错误映射为已付款必须失败”的反向测试。该助手只通过正式接口处理本轮测试资源，不把离线模拟结果写成真实HTTP已验收。

本次验证结果：Lastleg全量1076项，1074通过、2项环境测试跳过、0失败/错误；运维持久化扩展为9项。Admin全量273文件2185项通过，类型检查与生产构建通过；新增前端回归验证项目/地点独立提交、异常编辑不提前修改原行、零费用与付款状态分别展示、未确认行操作不开放。IAM相关12项通过；Gateway/初始化/HTTP编排22项及依赖/脚本文档14项通过。无新增表、权限码或Gateway配置，初始化表数和角色授权数不变；更新了六类枚举和权限显示名称。AGENTS索引仍为同组5项任务登记旧断言失败；本次未部署、未执行环境SQL或真实HTTP，也未完成浏览器视觉和请求量验收。



### 10.3 首版调度与理货审核

排车列表以服务端分页参数 `stage` 展示全部、装车前、装车中、装车后及已取消：装车前对应 `PENDING_DEPARTURE`，装车中对应 `PICKING/READY_TO_DEPART/PARTIAL_READY_TO_DEPART`（含拣货完成待发车），装车后对应 `DEPARTED/PARTIAL_DEPARTED`。阶段与具体状态筛选取交集，不按当前页数据做本地分组。阶段不表示审核通过或实际装载确认。

二级页签为“车辆信息／调度审核／理货员审核”，位于执行阶段与查询区之间。二级页签切换当前阶段下的信息和操作视图，保留筛选、分页及服务端总数，不对当前页记录做审核状态过滤；审核视图集中展示对应审核状态、打回原因、时间和进入审核的操作。三种视图独立保存列设置。

平台列表同一响应批量返回关联车次、每单调度审核及整车理货审核的状态、打回原因和审核时间；未关联显示“未关联车次”，不伪造待审或已通过。具有车次列表权限可从列表进入车次“分配与货物”或“实际装载”，审核仍沿车次独立写权限及版本门禁。列表只读信息沿排车列表权限，前端不逐行查询车次。


按本轮确认实现两级简化审核：每张客户排车单独立调度审核，通过后才能产生新的PDA拣货或完成命令；整车实物装载确认后，再做理货审核，通过后才能整车发车。操作只有通过和打回，通过意见选填，打回原因必填；不增加审核清单、提交队列或不同审核人限制。

- 车次详情的客户排车行展示审核状态、原因和时间，支持详情跳转、通过、打回；实际装载分区提供整车理货审核。两个写权限为`platform:fleet:trip:dispatch-review`和`platform:fleet:trip:loading-review`，只读沿用车次列表权限。
- 调度审核保存于`ll_fleet_trip_dispatch.review_json`，理货审核保存于`ll_fleet_trip.loading_review_json`，为空表示待审；历史保存各次审核快照。新增两列，无新增表。
- 换车、换司机或改路线/时间后相关调度审核、理货审核和装载确认重新待处理，保留全部已发生的拣货事实；仅修改备注不触发重审。重新确认实载、关联变更或重新审核调度单后理货审核待审。客户A审核通过不能替代客户B。
- PDA展示当前单`canPick/pickBlockReason`，发车继续由服务端整车门禁决定。已经成功的同键拣货重放返回原结果，不因后续重审而重复扣库存。未知网络结果不得生成新的物理作业事实。
- HTTP验收助手已接准备阶段调度审核、发车前改派后的重新审核以及最终理货审核；发车使用最终审核返回的新版本。留存场景也须已有合法调度审核，不绕过门禁补写旧单。

统一初始化SQL已同步两列，海外保持144表；IAM模块及头程统一基线已同步5107247/5107248两个按钮权限，并授权平台管理员。当前本地Admin定向94项、类型检查及生产构建通过，新增两条API路径的6项补验通过；海外PDA定向15项及H5构建通过；Gateway/依赖/HTTP助手/脚本文档37项通过。Lastleg全量1093项首次为1089通过、2项环境测试跳过，2项新增字段/权限合同失败在统一SQL同步后已定向补验通过；补验含Fleet API/权限3项及IAM权限4项。初始化合同10项通过，精确计数为387权限、568角色授权。没有重复运行已经通过且输入未变化的行为测试。AGENTS索引仍有原5项任务登记清空旧断言失败，未擅自清空已授权登记。没有将这些本地结果视为部署或实际页面验收完成。


### 10.4 外接运力前置与收货链核对

外接货送到我方起运仓，继续使用既有仓储转运的真实收货链；`WarehouseTransferService.createAndSubmit`在未引用旧入仓时建立本次新来货来源，PDA测量/托盘绑定/完成写入真实库存，客户确认后形成可排车来源。当前本土卡车`receivePallets`仅更新其订单托盘业务记录，不能拿该状态当作库存实收完成。外接登记与该链的正式关联仍须实现，不能仅凭此复用判断宣称外接履约已接通。

本轮增加车次“计划容量”页签和`/capacity-plan`读写：在自有货尚未拣货时，按真实托盘输入预计托位、重量、体积及卸货站，服务端按每段核算剩余容量。共享实托只计一次；缺失来源、超容量、旧版本或货物hash变化拒绝提交。计划容量与实际装载的卸货站只允许选择与托盘货物 `destinationKey` 一致的已匹配站点，不以显示名称判定同一目的地。未匹配时明确提示到“分配与货物”执行“按货物匹配卸货站”；同一托盘含不同目的地标识时提示先拆托，保存的旧卸货站索引失配时不继续沿用。保存计划不会生成实载、通过审核、扣库存或发车；发车前继续单独核对实测装载。改车、改司机、计划或关联变化使计划容量待重核，纯备注保留；历史保存当时计划依据。

新增`ll_fleet_trip.planned_load_json`一列，没有新增表、权限或服务。已有trip:list/edit分别承担查询及保存权限。GET的`planValid`只表示当前货物来源与已核对计划一致；无计划或来源变化时不展示过时余位。外接预订尚未占用该余位，后续须在同一车次锁内结合已确认预订计算，不允许把这个单独查询当作已实现防重复出售。

后续接入的直接入口已核对：IAM `/internal/iam/finance-customers`支持按客户ID精确读取有效客户，`/internal/iam/tenants/{tenantId}/order-eligibility`提供下单资格；不以采购历史去重列表代替客户主档。平台代外接客户登记和确认收货仍须建立明确命令及权限，不能要求无工作台账号的委托方假登录操作。费用覆盖和新增项目收费继续按第4.3节完成，不伪造零金额费用绕过现有转派送条件。

本地验证：Admin定向96项、类型检查和生产构建通过；Gateway与Lastleg依赖合同15项通过。Lastleg全量1095项首次为1092通过、2项环境测试跳过、1项统一SQL字段同步合同失败；总控同步统一海外列后Fleet API/Schema两项定向补验通过，初始化合同10项通过，海外保持144表、权限与角色授权数量不变。计划容量行为2项已通过，包括拣货前计划、实托去重、资源变化失效、旧来源拒绝及不覆盖实际装载。AGENTS索引仍为此前5项任务登记清空旧断言失败，未清空登记或放宽断言。真实部署、HTTP及页面验收仍须后续执行。


### 10.5 外接登记与承运占位（2026-10-03）

已增加车次内外接询价列表、登记/编辑、只读详情、确认承运与取消入口，后台使用1080px居中表单。登记先填有效客户、既有路线卸货站及箱数；预计托位/重量/体积、价格和联系说明可以后补。首版自送到车次起运仓，联系人不要求特定电话格式。按标准托位或整单记录报价，约定运费仅为商业约定，不自动生成应收、实收或费用入账。

- `ll_fleet_external_booking`保存稳定FB业务号、客户编号/名称快照、货物与报价、版本及请求摘要。DRAFT询价不占位；CONFIRMED在父车次行锁内确认承运并占位；CANCELLED释放尚未执行的预订。历史直接进入既有车次历史的`externalBookings`快照，没有另外建重复台账。
- 客户候选及精确建档校验读取IAM当前有效客户主档，正式登记与确认承运核对客户下单资格；失败时不创建假客户，也不以采购历史去重列表替代。新增只读Feign使用内部服务身份，不发送浏览器Token。
- 确认承运核对仍有效的自有货容量计划、全部已确认外接预订及本次申请，每段托位/重量/容积任一超限拒绝。计划容量响应`availableSegments`扣除已确认外接占位；询价与取消不占位。自有货重新测算也不能挤占已确认外接容量，换小车须能容纳两者；同车换司机不要求为此额外先重填容量。
- 创建、确认、取消按原请求键和内容重放，不重复占位/释放；更新同时核对车次和预订版本。界面保留未知结果的原请求，刷新查到确认/取消事实后解除待重试状态；只读用户可看详情，不能执行写操作。
- 新增四项写权限为`platform:fleet:trip:booking-create/edit/confirm/cancel`，IAM资源使用总控核对后的5107260..63（5107250..52已被车辆运维占用），父5107240。模块与统一海外基线当前145表，权限391项、角色关联572条，未向环境执行。

本批仍未实现外接来货单创建/关联、实测差异重新确认、外接货与客户排车关系和费用覆盖入账。已确认但未关联实际发运的预订会明确阻止整车发车；不能用“确认承运”冒充已收货或已发运。后续须补齐这条连接后才能作为完整外接版本部署验收。

本地检查：Lastleg全量1099项（1097通过、2项环境测试跳过）；新增外接占位行为含登记重放、确认后扣减/取消恢复、超卖拒绝、自有货增量不得侵占预订和历史快照。客户目录两项验证精确客户与资格、依赖失败关闭。Admin定向原99项中只读测试因将说明文字误当按钮失败，已改为核对真实按钮并补充详情/编辑，四项面板测试通过；最新类型检查及生产构建通过；同车只换司机无需额外容量重填的收尾变更经FleetTripPersistence39项补验通过。Gateway/切片依赖通过；同步依赖已精确登记新IAM只读边及此前遗漏的运维文件HTTP调用，10项合同通过；316个Mapper扫描通过。真实环境、页面视口及请求量验收尚未执行。


### 10.6 外接真实来货、实收确认与排车关联（2026-10-03）

本轮把预订连接到已有仓储转运/PDA真实收货流程，未另建库存账：

1. 已确认承运的预订由运营生成来货单，固定预订客户、起运仓、箱数及既有卸货站；首版客户自送。该操作创建并提交、审核原来货流程，只形成待PDA收货，不写实收库存；私人地址必须与原约定卸货键一致。
2. 仓库通过现有PDA转运测量、托盘绑定及完成流程写入实际库存。车次后台按需查询实托、箱数、重量、体积及receiptHash；尚未完成测量不能确认实收。
3. 运营明确核对实托占用托位和约定单价；实际数量变化会重新计算约定金额，同时按实际载荷替换原预留并重验余位。原来货确认成功且实测摘要未变后，预订才进入RECEIVED；库存不会重复写入。失败保留原报价/预留，不能先将未完成确认标成成功。
4. 来货库存经现有预排生成客户排车单，再在车次外接行关联。服务端核对客户、同一起运仓、来货来源、实托、整批实收数量及目的地。通用车次绑定入口也执行该检查，不能将已承诺货物挂到另一车次；同一排车可携带多票合法来源，每票分别核对。
5. 关联成功后预订进入BOUND，预订容量转由实际关联货物计量；容量计划/实际装载和理货审核重新待核对。后台刷新车次成员及审核状态。后续仍逐客户调度审核、PDA拣货、实际装载及整车理货审核后发车。解除未开工排车关联回到RECEIVED并恢复预留；已拣货沿既有正式撤回边界处理。

取消未执行预订仅释放承运位置，已生成来货单和已入库货物保留，不据此删除库存。预订保存来货号、排车号、实测证据及各命令请求键/摘要；原请求重放返回当前事实，不重复创建来货或关联。四个新增读写接口继续使用现有booking-edit/booking-confirm与trip:list，绑定还需trip:edit。总控已同步原预订表新增字段/索引及RECEIVED/BOUND状态，仍145表、391权限和572角色关联，未执行环境SQL。

实现入口为`FleetBookingIncomingGateway`、`transfer/fleet/FleetIncomingAdapter`和`FleetBookingService`；按精确端口引用接入，没有放宽转运切片对车队实现的依赖。沿实际收货路径移除了把内部客户ID拼成展示名称的回退，未知名称显示“—”。前端承载为`TripBookingFulfillmentDialog`，普通交货说明选填，来货和实收详情只在打开时读取。

验证：Lastleg全量1102项（1100通过、2项环境测试跳过、0失败），后续实收确认必须返回可排车状态的收尾约束已通过42项定向补验；Admin模块及密度103项通过，外接关联后刷新成员/审核的交互补验通过，类型检查及构建通过。Gateway/精确依赖15项、初始化10项通过。仍缺原运费覆盖/新增费用正式接入、其余运营闭环和真实环境全链验收，不能以预订与收货连接宣告完整车辆模块已交付。

### 10.7 外接实收报价接入派送费用（2026-10-03）

外接运费已从报价展示接到正式费用发布：排车转派送打开时读取一次`GET /dispatches/{dispatchNo}/external-freight`，复用dispatch:list只读权限；服务端核对每票真实来货、所属客户、绑定车次、目的地及完整实托箱数，返回报价版本、计价量、原币金额与货物/报价摘要。查询不会创建费用。提交沿原transfer-delivery写权限，并携带externalFreightHash；实收、报价版本或来源改变时重新核对。

- 转派送在现有事务内，按每票外接实际卸货目的地关联对应派送单，发布`OVERSEAS_DELIVERY_FEE`应收及现有费用Outbox，由Finance消费形成账务事实。约定金额、计价量、单价、实际入仓码和预订业务号随费用与操作记录保留。当前仅证明本地调用接通，未证明真实Finance已接收。
- 全部货物为已确认外接时不再要求手工填派送费，且服务端禁止重复派送应收；混合排车只要求其余货物的派送费，手工派送费归其余货物对应派送单。装车和购买预约仍单独登记。原头程运费是否已覆盖这些服务，尚未接入，不能据此宣布全部不重复收费需求完成。
- 明确约定零运费保留预订版本与派送操作事实，不伪造零金额财务费用。为与当前正式费用和汇率能力一致，确认承运仅支持CNY/USD；询价可先保存，非支持币种在承运确认时提示调整。USD正式发布仍须业务月份有效汇率。
- 既有出库唯一约束及请求摘要保证原请求重放只返回原派送单，换操作人重试也不再发布外接费用。外接预订必须先完成真实车次关联，不能从普通转派送绕过实收/承运确认。取消出库后的费用作废/更正及再次安排仍须继续接通，不将取消物流单据视为账务自动撤销。

本地验证：后端5类107项通过，覆盖报价/来源核对、分目的地费用归属、零约定、陈旧摘要/重复派送应收拒绝和换操作人重试；Admin排车交互/API/原型合同45项通过，类型检查与生产构建通过。Gateway 5项、Lastleg精确依赖10项通过，未放宽依赖基线；AGENTS索引仍有原5项登记清空旧断言失败。无新增表、权限码、Gateway配置或Finance事件结构，未执行SQL、部署、真实HTTP或视觉验收。后续优先完成每票原费用来源及服务覆盖、取消账务处理，再继续其他运营闭环与环境验收。
### 10.8 出库取消与费用撤销确认（2026-10-03）

首版取消顺序明确为：未拣货时先解除车次关联，再取消出库；仍需在原排车列表取消排车以释放该排车占用。取消不代替实物退仓或已执行货物撤回。后端按dispatch→outbound顺序锁定，并核对排车本身未拣货/发车，避免出库快照仍为待出库时误取消正在执行的货物。来源订单从本次转派送历史恢复真实原状态，显式清空已取消的出库/派送关联并递增版本，不统一写成RECEIVED；取消原因完整留在派送操作记录。

费用处理沿用现有Lastleg费用来源与可靠Outbox：

- 取消仅对本派送当前已审核有效的DELIVERY_FEE应收申请作废；装车、买约、供应商成本及其他待核对费用保留。物流取消成功不代表账务已作废。
- 作废请求先保持原来源ACTIVE，返回PENDING_FINANCE；只有Finance对同一事件ID与载荷摘要返回APPLIED/DUPLICATE，才在投递审计、Outbox完成、来源VOIDED同一事务内落账。拒绝、未知结果或确认落账失败都不能假作废；拒绝/耗尽显示FINANCE_ATTENTION，已确认显示CONFIRMED。
- VOID投递等待原版本发布成功，未满足前置的撤销在队列LIMIT之前排除，避免前50条未就绪撤销堵住后续正常费用。过期PROCESSING继续沿既有租约恢复。费用调整在来源行锁后按READ_COMMITTED核对未决撤销，不能用旧快照漏过撤销申请。
- 重新安排发运按客户及实际入仓码核对原派送应收最新版本；原费用未确认作废时不能再次发布。即使原预订已取消，仍保留其真实来货/实收的财务来源关联。新发运以预订和新排车共同形成费用请求键，原出库重放依旧只返回原结果，不重复收费。
- 派送详情和直接复用该费用接口的货柜费用面板区分待财务确认、待财务处理与已作废；待确认/待处理不开放调整或重复作废。查询批量读取确认状态，不逐行发HTTP请求；财务结算、已出账拒绝和后续人工处理仍以Finance事实为准。

本批没有新增数据库列/表、权限或事件协议；复用现有V1完整快照、严格匹配ACK与原投递审计，不表示海外费用阶段0全部完成。共享初始化基线由总控新增废弃审核权限后为海外145表、392权限、573角色关联，本批未改共享SQL。自有货原运费服务覆盖、其余车辆运营能力与真实环境全链验收仍未完成。

本地验证：最终7类69项通过，其中6项Spring/MyBatis/H2测试验证费用确认与投递审计原子提交/失败回滚、陈旧确认拒绝、原发布等待、队列不饥饿以及原费用最新版本去重；之前费用/派送10类76项已通过。契约严格解析发现智能排车候选的两处重复重量字段，已移除重复定义并通过2项合同补验。Admin派送/出库与货柜费用32项通过，类型检查及生产构建通过；Gateway/依赖15项通过。AGENTS索引原5项登记清空旧断言仍未关闭，未清空登记。没有部署、环境SQL、真实Finance撤销HTTP、指定视口视觉或请求量完成证据。

### 10.9 原运费按本次实际货物确认服务覆盖（2026-10-03）

当前部署及真实环境验收结论统一查阅[测试环境单机部署与配置契约](../测试环境单机部署与配置契约.md)和[统一认证与服务通信契约](../统一认证与服务通信契约.md)，本节保留实现说明与当批本地验证边界。车辆专项编排入口为 `baiyue-firstleg/scripts/fleet-test-env-acceptance.mjs`，按真实自有货与外接来货执行费用覆盖、容量预留、PDA实收、并车、约定运费、逐单拣货、整车发车、逐目的地签收及资源分别释放。库存来源核对采用余额明细、实物位置及不可变流水；实收使用 `receivedPackages`；命令重放对比持久化后的业务记录。失败保留原命令和原样本，只允许显式核对的阶段继续，终态对账仅作只读请求；Finance消费入池与生产者ACK分别取证。具体命令与边界见该仓库 `scripts/admin-test-env-modules/README.md`。

已接通读取、运营确认、转派送校验、快照保存与详情展示。此节更新第4.3节初始差距，不把历史“尚未实现”记录作为当前实现状态。

1. 打开转派送时，并行读取一次外接约定运费和一次原费用覆盖预览，不逐行发请求。`DispatchFeeCargoMapper`按实物库存组成及本次已拣数量逐票还原，同仓/客户/排车隔离，并按计划托盘限制其真实来源；核平每条排车箱数后，使用真实尾程订单冻结的头程入仓ID，避免把合托展示的MIN入仓码当成整托来源。
2. `FinanceFeeCoverageClient`批量调用Finance内部只读`delivery-fee-coverage/sources`，仅返回该客户、这些原入仓单的FIRSTLEG已审核有效应收最新版本；作废/替代/其他客户/应付不能作为覆盖依据。AVAILABLE和SETTLED均可作为原费用事实，不把AVAILABLE显示为已付款；来源柜号不能伪装成入仓码。无匹配来源为空，调用失败或范围不一致明确报错，不能伪造已包含。
3. 平台运营在原1120px转派送弹框内，针对各票原费用明确勾选本次已含派送、装车或买约；不按费用名称、总金额或同客户其他费用自动推断。提交原费用ID、版本、hash及当前货物/目的地摘要后重新读取并核对。只有全部相关货物都已覆盖的服务才免新增应收；只覆盖其中一票时，仍须填写其余货物/服务的新费用。外接货仍按已确认实收报价生成对应运费，不能借“引用原费用”抹掉外接价格。
4. 原费用不复制入账、不做金额抵扣、不伪造零金额费用，也不直接把原全程运费总额算成本车收入。新增应收只对应未覆盖范围；多来源时不把MIN订单或已覆盖票冒充唯一收费来源。客户应收与供应商应付独立，同项目收付使用不同费用请求键；服务已含只免相应新增应收，不消除真实供应商成本。
5. `ll_outbound_order.fee_coverage_json`保存确认时实际货物、原费用版本与明确服务、操作人和时间；详情只展示当前派送所属货物的引用。原费用后续财务更正不自动改写旧发运确认，也不自动追加收费；业务更正按取消未执行单据后重新确认等正式流程处理。原成功命令重放保持原快照；无引用的null/空数组具有相同业务摘要，客户接口不能自行声明原费用覆盖。

模块和统一海外初始化已同步这一可空JSON列，没有新增表、权限或费用事件协议；普通无引用发运该列为空。发布单元包含Finance、Lastleg与Admin；Gateway沿已有路由，内部Finance入口不公开。当前服务图新增的是Lastleg→Finance只读请求边，接口实际只到Finance本库；已用单独合同约束该查询无下游调用、无账务写入。静态服务级最长链上界因此变为6跳，仍如实记录既有超两跳风险，不把服务级组合图冒充本接口实际链长。

本批只证明费用覆盖源码及本地行为，仍须真实Finance/Lastleg部署与来源引用、旧版本冲突、全覆盖/部分覆盖、取消重排和页面请求量验收。车辆运维财务关联、运营统计/报价及在途异常等未完成工作继续按原工作包推进，不据此缩小车辆管理整体目标。

本地验证：Finance与Lastleg聚合回归构建成功，Finance 223项全部通过；Lastleg 1142项中1140通过、2项环境测试跳过，0失败/错误。Admin费用覆盖相关4文件31项通过，类型检查及生产构建通过；最后的加载提示调整另经类型检查通过。Gateway、切片和同步依赖合同合计26项、初始化合同10项通过，Mapper扫描317项通过。AGENTS索引当前1094项全部通过，前述历史批次记录的5项旧断言失败已不再是当前阻塞。验证日志位于Lastleg的target/fleet-coverage-*本地输出，本批未据此宣称测试环境部署、真实HTTP、页面视觉或请求量验收完成。

### 10.10 报价、运营统计、在途交接与公司车辆成本集成（2026-10-03）

报价库按采购/销售区分供应商与客户，提供版本历史、启停、删除和整批原子CSV导入；未知价格与零价分别保存。通用菜单接入`/overseas-master-data/fleet-quotes`，不复用海外仓仓储报价。外接预订已接入可选销售报价来源，来源版本与本次成交金额分别冻结，不以原报价替代实际约定运费。

报价选用增量：候选提供端按客户、起运城市、目的仓码、币种、计价方式及服务日期筛选启用销售报价；缺价不按零价处理，不自动选择最低价或将整车价当拼载成交价。预订接入按起运仓正式详情的城市/时区和计划出发时刻生成条件，复用Warehouse已有内部详情接口，不从仓名、国家或浏览器时区推断。引用为可选项，私人地址或缺少明确仓资料可继续手填成交价。来源版本及原报价保存于独立`quote_source_json`，与本次成交单价/数量/总金额分开；确认承运前复核所选版本和有效性，承运确认后的实收改价保留原来源。实现沿`FleetBookingService`、`FleetBookingQuoteContext`及Admin `TripBookingPanel.vue`；部署及真实费用闭环仍须以主契约证据判断。

车辆菜单的出车记录`/overseas-master-data/trip-operations`从不可变DEPART汇总，每趟一次；图表与列表使用相同筛选和币种口径。实际里程/油耗只作独立补充更正，不改发车、结案或财务事实。成本通过服务内有界批量Summary读取，没有记录、无权限和未查询分别展示，不把约定外接金额当应收或收款。

实测凭证为选填PDF/JPG/PNG，单文件10MiB、每版最多20份，独立类型`FLEET_TRIP_OPERATION_EVIDENCE`按平台及车次归属。上传只创建不可变文件，保存实测记录才冻结引用；移除当前引用不删除历史，预览按当前或历史版本按需鉴权读取。上传结果未知时停止重传，可先不绑定该附件继续保存；实测内容保存重试仍使用同一请求键、版本及内容。

2026-10-05用户确认首版运营页展示Finance应收/实收：只展示Finance能够明确归属该车次的权威金额，按币种分别核对并可追溯来源；没有明确归属或付款分配的部分显示“待分配”，不能当作零元或已收。既有账单级核销不按未经确认的比例分配给车次，不把整账单金额或外接约定金额当作本车次应收/实收。成本与付款、客户应收与实收分别保持各自财务含义，不重复创建费用或资金流水。

车次详情按需显示在途交接面板，后台确认实际交接；按实际剩余货物核验接替资源，只更新未完成派送，原DEPART、库存和费用不重写。原车辆与司机各自确认实际任务结束后释放；PDA首版只读展示当前履约资源。退回处置沿`exceptionorder/`的开始处理、证据、分批实收和取消命令，真实退回流水生成独立重派凭据；通过`RETURN_RECEIPT`候选和预排进入新PDA发运，不改原实发/签收。逐来源全签才回传国内完成事件，签后退回重送不重复计数。后端可执行不等于Admin处置页面已完整接入，当前页面与环境验收缺口见测试环境主契约。已拣未发撤拣/退仓撤回和余货拆给多辆车的交接不由这条退回重派链代替。

同托退回来源按实际逐订单拣货归属核算；出库托盘明细上的主入仓码不能排除同托其他来源。排车明细与原出库明细使用物理托盘、原入仓码、目的仓和订单引用的冻结快照唯一关联；存在多个匹配时明确拒绝歧义，不能取首条猜测。退回凭据、新拣货和签收仍分别保留原来源、实际数量及时间，审核或异常工单状态不能替代实际实收与签收证据。

派送列表和详情统一返回数据库冻结的实际签收箱数 `signedPackages`：未知返回 `null`，零和正整数保留原值，不以发货箱数代替。签收时间按服务执行时区记录，完成事件转换为同一时刻的 UTC；国内完成记录与事件时刻保持一致，不能把本地时间直接标为 UTC。退回重派核平使用实际签收箱数，并保持原派送签收数量和时间不变。

公司车辆费用沿文首已确认口径进入Finance独立费用、历史和付款表，引用平台财务主体，不写入客户费用池、账单或钱包。CompanyVehicleCostSubmitted完整快照经既有Outbox直接投递Finance，匹配ACK只代表接收，入账/实际付款分别执行。费用和付款使用VC/VP业务号，公司凭证限定平台及费用归属。维修/救援页面已接来源提交、财务状态查询、入账、未付作废及付款凭证；查询、入账、作废、付款和上传独立授权。已付款不能直接作废或改写来源金额，未付款可作废重建；零申报金额可记录但不伪造实际付款。跨服务与受限账号的真实验收仍按两份主契约分别关闭。

源码合同见`fleet-quotes-v1.yaml`、`fleet-operations-v1.yaml`、`fleet-handovers-v1.yaml`、`fleet-trip-costs-v1.yaml`及Finance的`finance-vehicle-costs-v1.yaml`。代码、初始化基线、发布和真实验收分开核对；环境证据仅维护于两份正式主契约。