优化

AGENTS.md

@@ -133,9 +133,9 @@
 - 后端同样遵守根指引中的“开发数据和上传文件可丢弃”边界：不得为现有开发库孤儿文件、旧文件归属或历史部分失败新增删除补偿接口、兼容复用、回填或清理链路；只修复当前正式上传与持久化路径，既有开发文件由人工重新上传。
 - 通用配置在 `config/nacos/test/`；服务日志、上传文件、`target/`、`reports/` 不属于源码。
 - 后端本地验证默认使用 `scripts/backend-check.ps1`，必须显式指定 `-Modules`，不传模块直接拒绝；命令及参数见 `scripts/README.md` 的“后端分层检查”。入口自动经 `local-check.ps1` 限流，`-DryRun` 只检查选择范围，不代表测试通过。
-- 开发迭代使用 `-Mode Focused -Tests <精确测试类名>`，覆盖修改行为及直接调用点；Java 签名变化至少使用 `-Mode Compile` 编译生产与测试源码（等价于 `mvn -pl <modules> -am test-compile`）。单服务行为变更收尾使用默认 `Module` 模式执行该服务及上游依赖测试；跨服务 DTO、接口或事件变化必须显式列入生产者和受影响消费者。`-am` 只补上游构建依赖，不自动包含下游服务或 HTTP/事件消费者；不能以单类测试代替模块收尾。
+- 局部逻辑使用 `-Mode Focused -Tests <精确测试类名>`，覆盖修改行为及必要边界即可交付，不因收尾再跑 `Module`。Java 签名变化须覆盖生产与测试源码编译；定向测试已编译时不重复跑 `-Mode Compile`。只有影响扩及服务内多个行为且定向覆盖不足才选 `Module`，先说明原因。跨服务 DTO、接口或事件变化显式列入生产者和实际消费者；`-am` 仅补上游构建依赖，不自动包含下游或 HTTP/事件消费者。
 - 仅注释/文档调整不触发 Java 回归；脚本调整执行受影响脚本测试和登记合同。API、Mapper、AGENTS 等静态合同仍按各自触发条件执行。纯重构也应覆盖受影响行为，不能只用编译宣称回归通过。`-Dmaven.test.skip=true` 跳过测试编译，不得作为签名变更交付验证。
-- 全仓回归只在以下情况触发：根 POM/统一依赖版本/聚合拓扑/测试基础配置变化；公共认证、序列化、基础模型等影响广泛且不能可靠限定消费者；跨多域批次集成验收；用户明确要求全量回归。使用 `scripts/backend-full-regression.ps1`，保留当前 CI 全量验证。普通单服务任务、单次提交或对话收尾不自动触发全仓；已明确消费者的公共或跨服务变更按受影响模块验证。同批同一相关输入只跑一次，输入变化后补跑受影响范围，触及上述全量条件再重跑全量。
+- 全仓回归仅用于已确认影响广泛且定向覆盖不足的公共依赖/聚合拓扑/认证/序列化/基础模型变化，或用户要求的全量/跨域集成验收；先说明具体影响，不能因未查清范围而全跑。根 POM、依赖或测试配置改动先按实际影响选编译或测试，不一律全仓。入口为 `scripts/backend-full-regression.ps1`，CI 全量保留。普通提交、单服务任务或对话收尾不触发；有效结果复用，输入变化只补跑受影响范围。
 - 不以缩短耗时为由删除金额、库存、权限隔离、状态流转、幂等和并发测试；冗余测试须根据重复场景及维护成本单独评估。不要在本地启动 Java/Nacos/数据库，除非用户明确要求。
 - 同一批 `AGENTS.md` 索引修改完成后从后端根统一运行一次 `./scripts/agents-index-contract.ps1`；脚本只读源码目录和指定指引，不访问 HTTP、数据库或部署环境。
 - Mapper 注册静态合同为 `scripts/mapper-scan-contract.mjs`、`mapper-scan-contract.test.mjs`：自动发现聚合模块、生产 `*Mapper` 接口、服务启动类和分散扫描配置，不启动 Spring、不连接数据库；遗漏注解、扫描根漂移或重新引入子域扫描时直接失败并输出类与文件路径。

Jenkinsfile

@@ -161,7 +161,8 @@ pipeline {
         choice(name: 'ENVIRONMENT', choices: environmentChoicesForJob(env.JOB_BASE_NAME), description: '部署环境')
         booleanParam(name: 'DEPLOY', defaultValue: false, description: '各服务构建成功后是否独立部署')
         booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试执行（仍编译测试源码）')
-        string(name: 'IMAGE_REPOSITORY', defaultValue: '', description: '必须填写已核实的共享镜像仓库地址 host[:port]/owner/image')
+        // 地址由当前 Job 配置提供；参数声明刷新时保留已配置值，不将环境地址写入源码。
+        string(name: 'IMAGE_REPOSITORY', defaultValue: params.IMAGE_REPOSITORY ?: '', description: '沿用当前 Job 已配置的镜像仓库地址；首次配置或更换仓库时填写 host[:port]/owner/image')
         string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
         choice(name: 'DOWNSTREAM_JOB_PREFIX', choices: downstreamJobPrefixChoicesForJob(env.JOB_BASE_NAME), description: '由当前总控 Job 固定的单服务 Job 前缀')
     }

Jenkinsfile.service

@@ -49,7 +49,8 @@ pipeline {
         booleanParam(name: 'ALLOW_SAME_CONTRACT_ROLLBACK', defaultValue: false, description: '仅确认相同协议与Schema时允许回滚；架构切换保持关闭')
         booleanParam(name: 'DEPLOY', defaultValue: false, description: '构建成功后是否部署本服务')
         booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试')
-        string(name: 'IMAGE_REPOSITORY', defaultValue: '', description: '必须填写已核实的共享镜像仓库基础路径，不包含服务名和标签')
+        // 独立构建沿用本 Job 配置，总控调度时保留其明确传入的地址。
+        string(name: 'IMAGE_REPOSITORY', defaultValue: params.IMAGE_REPOSITORY ?: '', description: '沿用当前 Job 已配置的镜像仓库基础路径，不包含服务名和标签；首次配置或更换仓库时填写')
         string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
     }
 

deploy/sql/海外区域统一增量-MySQL8.sql

@@ -429,6 +429,7 @@ CREATE TABLE ll_dispatch_order (
   review_state VARCHAR(32) NOT NULL DEFAULT 'DRAFT' COMMENT '审核子流程当前状态',
   review_round BIGINT NOT NULL DEFAULT 0 COMMENT '当前审核轮次',
   review_basis_hash CHAR(64) NULL COMMENT '本审核轮次核对的货物和资源依据摘要',
+  exceptions_json JSON NULL COMMENT '派送异常登记记录及图片引用，不改变派送及库存状态',
   dispatch_review_json JSON NULL COMMENT '当前调度审核事实快照',
   loading_review_json JSON NULL COMMENT '当前理货审核事实快照',
   resources_json JSON NULL COMMENT '本趟主档或临时车辆司机的真实资源快照',

file/src/main/java/com/baiyue/file/service/BusinessFileCategory.java

@@ -11,6 +11,7 @@ enum BusinessFileCategory {
     FLEET_TRIP_OPERATION_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     OVERSEAS_DISPATCH_VEHICLE_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     OVERSEAS_DISPATCH_DRIVER_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
+    OVERSEAS_DISPATCH_EXCEPTION_EVIDENCE(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     OVERSEAS_DISPATCH_LOADING_PHOTO(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     OVERSEAS_DISPATCH_FUEL_PHOTO(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
@@ -79,9 +80,9 @@ enum BusinessFileCategory {
                 && tenantId != 0) {
             throw new BizException(ResultCode.BAD_REQUEST, "排车运营照片必须归属平台");
         }
-        if ((this == OVERSEAS_DISPATCH_VEHICLE_EVIDENCE || this == OVERSEAS_DISPATCH_DRIVER_EVIDENCE || this == OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE)
+        if ((this == OVERSEAS_DISPATCH_VEHICLE_EVIDENCE || this == OVERSEAS_DISPATCH_DRIVER_EVIDENCE || this == OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE || this == OVERSEAS_DISPATCH_EXCEPTION_EVIDENCE)
                 && tenantId != 0) {
-            throw new BizException(ResultCode.BAD_REQUEST, "排车车辆及司机证据必须归属平台");
+            throw new BizException(ResultCode.BAD_REQUEST, "排车证据必须归属平台");
         }
         if (this == FLEET_TRIP_OPERATION_EVIDENCE && tenantId != 0) {
             throw new BizException(ResultCode.BAD_REQUEST, "出车实测凭证必须归属平台");

file/src/main/resources/openapi/dispatch-evidence-v1.yaml

@@ -6,7 +6,7 @@ info:
     复用 InternalBusinessFileController 的现有通用内部入口，不新增公开文件路由。
     三类证据均固定平台 tenantId=0，businessId 为排车内部正数 Long ID 的十进制表示，
     不使用车辆 ID、司机 ID、车牌或客户 ID。车辆与司机证据分别使用
-    OVERSEAS_DISPATCH_VEHICLE_EVIDENCE、OVERSEAS_DISPATCH_DRIVER_EVIDENCE、OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE，不可互换。司机本人照片DRIVER_PHOTO仅支持JPG/PNG；其他两类沿PDF/JPG/PNG。
+    OVERSEAS_DISPATCH_VEHICLE_EVIDENCE、OVERSEAS_DISPATCH_DRIVER_EVIDENCE、OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE，不可互换。司机本人照片DRIVER_PHOTO和排车异常图片EXCEPTION仅支持JPG/PNG；其他两类沿PDF/JPG/PNG。
     File 校验内部服务令牌、平台归属、正数业务 ID、文件非空、最大 10MiB（10485760 字节，包含边界）、
     PDF/JPG/PNG MIME 及对应内容签名。元数据和下载按 tenantId、businessType、businessId、fileId
     联合查询 ACTIVE 且未删除文件，错车或错类别均视为归属不匹配，下载前完成归属校验。
@@ -126,7 +126,7 @@ components:
       description: 正数Long的十进制字符串，值不得超过9223372036854775807
     DispatchEvidenceType:
       type: string
-      enum: [OVERSEAS_DISPATCH_VEHICLE_EVIDENCE, OVERSEAS_DISPATCH_DRIVER_EVIDENCE, OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE]
+      enum: [OVERSEAS_DISPATCH_VEHICLE_EVIDENCE, OVERSEAS_DISPATCH_DRIVER_EVIDENCE, OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE, OVERSEAS_DISPATCH_EXCEPTION_EVIDENCE]
     MetadataEnvelope:
       type: object
       required: [code, data]

file/src/test/java/com/baiyue/file/service/DispatchEvidenceFileTest.java

@@ -30,6 +30,7 @@ import static org.mockito.Mockito.*;
 
 class DispatchEvidenceFileTest {
     private static final String VEHICLE = "OVERSEAS_DISPATCH_VEHICLE_EVIDENCE";
+    private static final String EXCEPTION = "OVERSEAS_DISPATCH_EXCEPTION_EVIDENCE";
     private static final String PHOTO = "OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE";
     private static final String DRIVER = "OVERSEAS_DISPATCH_DRIVER_EVIDENCE";
     private static final int MAX_BYTES = 10 * 1024 * 1024;
@@ -43,7 +44,7 @@ class DispatchEvidenceFileTest {
 
     /** 三类证据只接受平台与有效排车内部 ID，非法输入不得访问数据库或磁盘。 */
     @ParameterizedTest
-    @ValueSource(strings = {VEHICLE, DRIVER, PHOTO})
+    @ValueSource(strings = {VEHICLE, DRIVER, PHOTO, EXCEPTION})
     void requiresPlatformAndPositiveDispatchIdBeforeAccess(String type) {
         var files = mock(FileObjectMapper.class);
         var storage = mock(BusinessFileStorage.class);
@@ -65,9 +66,10 @@ class DispatchEvidenceFileTest {
         verifyNoInteractions(files, storage);
     }
 
-    /** 司机本人照片使用独立平台类别，只保存真实图片，拒绝PDF和伪造图片。 */
-    @org.junit.jupiter.api.Test void driverPhotoAcceptsOnlyRealImages() throws Exception {
-        var storage=storage();var category=BusinessFileCategory.require(PHOTO);
+    /** 司机照片与异常图片使用独立平台类别，拒绝PDF和伪造图片。 */
+    @ParameterizedTest @ValueSource(strings = {PHOTO, EXCEPTION})
+    void photoAcceptsOnlyRealImages(String type) throws Exception {
+        var storage=storage();var category=BusinessFileCategory.require(type);
         for(var format:new String[]{"jpeg","png"}) {
             var upload=new MockMultipartFile("file","driver."+format,"image/"+format,image(format));
             var saved=storage.store(0,"71",upload,category);
@@ -162,7 +164,7 @@ class DispatchEvidenceFileTest {
 
     /** 元数据和下载均逐列带全复合键；错车、错类别、错文件不得读取存储内容。 */
     @ParameterizedTest
-    @ValueSource(strings = {VEHICLE, DRIVER, PHOTO})
+    @ValueSource(strings = {VEHICLE, DRIVER, PHOTO, EXCEPTION})
     void metadataAndDownloadEnforceEveryScopeKeyBeforeReading(String type) throws Exception {
         var files = mock(FileObjectMapper.class);
         var storage = mock(BusinessFileStorage.class);

firstleg/src/main/java/com/baiyue/firstleg/portschedule/mapper/CarrierScheduleQueryMapper.java

@@ -63,6 +63,7 @@ public interface CarrierScheduleQueryMapper extends BaseMapper<CarrierScheduleQu
         """)
     CarrierScheduleQueryEntity findByContainerBookingId(@Param("containerBookingId") long containerBookingId);
 
+    /** 到港与日历统一取最新观测的实际记录，后续修正为更早时间时不能被历史最大值覆盖。 */
     @Select("""
         <script>
         SELECT b.id AS containerBookingId,q.id AS queryId,q.version AS queryVersion,
@@ -70,7 +71,7 @@ public interface CarrierScheduleQueryMapper extends BaseMapper<CarrierScheduleQu
                current.actual_at AS latestActualAt,
                MAX(CASE WHEN f.standard_node='DEPARTED_WAREHOUSE' THEN f.actual_at END) AS departedWarehouseAt,
                MAX(CASE WHEN f.standard_node='DEPARTED_ORIGIN_PORT' THEN f.actual_at END) AS departedOriginPortAt,
-               MAX(CASE WHEN f.standard_node='ARRIVED_DESTINATION_PORT' THEN f.actual_at END) AS arrivedDestinationPortAt,
+               MAX(arrival.actual_at) AS arrivedDestinationPortAt,
                MAX(CASE WHEN f.standard_node='PICKUP_READY' THEN f.actual_at END) AS pickupReadyAt,
                MAX(CASE WHEN f.standard_node='PICKED_UP' THEN f.actual_at END) AS pickedUpAt,
                MAX(CASE WHEN f.standard_node='EMPTY_RETURNED' THEN f.actual_at END) AS emptyReturnedAt
@@ -81,6 +82,10 @@ public interface CarrierScheduleQueryMapper extends BaseMapper<CarrierScheduleQu
                  ORDER BY f2.observed_at DESC,f2.id DESC LIMIT 1)
           LEFT JOIN fl_carrier_schedule_query q ON q.id=current.query_id
           LEFT JOIN fl_carrier_schedule_node_fact f ON f.container_booking_id=b.id AND f.actual_at IS NOT NULL
+          LEFT JOIN fl_carrier_schedule_node_fact arrival ON arrival.id=(
+                SELECT a.id FROM fl_carrier_schedule_node_fact a
+                 WHERE a.container_booking_id=b.id AND a.standard_node='ARRIVED_DESTINATION_PORT' AND a.actual_at IS NOT NULL
+                 ORDER BY a.observed_at DESC,a.id DESC LIMIT 1)
          WHERE b.id IN
          <foreach collection="containerBookingIds" item="id" open="(" separator="," close=")">#{id}</foreach>
          GROUP BY b.id,q.id,q.version,q.status,current.standard_node,current.actual_at

firstleg/src/test/java/com/baiyue/firstleg/portschedule/repository/CarrierScheduleQuerySqlContractTest.java

@@ -44,8 +44,9 @@ class CarrierScheduleQuerySqlContractTest {
         }
     }
 
+    /** 保留批量读取，实际到港与日历采用相同的最新观测顺序。 */
     @Test
-    void batchesActualContainerFactsWithoutEstimatedOrPerNodeQueries() throws Exception {
+    void batchesActualContainerFactsWithLatestObservedArrivalAndWithoutEstimatedTimes() throws Exception {
         String sql = String.join("\n", CarrierScheduleQueryMapper.class
             .getMethod("selectContainerActualFacts", List.class)
             .getAnnotation(Select.class).value());
@@ -55,13 +56,16 @@ class CarrierScheduleQuerySqlContractTest {
             .contains("f.actual_at IS NOT NULL")
             .contains("MAX(CASE WHEN f.standard_node='DEPARTED_WAREHOUSE'")
             .contains("MAX(CASE WHEN f.standard_node='DEPARTED_ORIGIN_PORT'")
-            .contains("MAX(CASE WHEN f.standard_node='ARRIVED_DESTINATION_PORT'")
+            .contains("MAX(arrival.actual_at) AS arrivedDestinationPortAt")
+            .contains("a.standard_node='ARRIVED_DESTINATION_PORT' AND a.actual_at IS NOT NULL")
+            .contains("ORDER BY a.observed_at DESC,a.id DESC LIMIT 1")
+            .doesNotContain("MAX(CASE WHEN f.standard_node='ARRIVED_DESTINATION_PORT'")
             .contains("MAX(CASE WHEN f.standard_node='PICKUP_READY'")
             .contains("MAX(CASE WHEN f.standard_node='PICKED_UP'")
             .contains("MAX(CASE WHEN f.standard_node='EMPTY_RETURNED'")
             .contains("ORDER BY b.id")
             .doesNotContain("estimated_at");
-        assertThat(count(sql, "fl_carrier_schedule_node_fact")).isEqualTo(3);
+        assertThat(count(sql, "fl_carrier_schedule_node_fact")).isEqualTo(5);
         assertThat(count(sql, "SELECT f2.id FROM fl_carrier_schedule_node_fact f2")).isEqualTo(1);
     }
 

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/mapper/ContainerCalendarSourceMapperTest.java

@@ -2,6 +2,7 @@ package com.baiyue.firstleg.terminaldrayage.mapper;
 
 import com.baomidou.mybatisplus.core.MybatisConfiguration;
 import com.baomidou.mybatisplus.core.MybatisSqlSessionFactoryBuilder;
+import com.baiyue.firstleg.portschedule.mapper.CarrierScheduleQueryMapper;
 import org.apache.ibatis.mapping.Environment;
 import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
 import org.h2.jdbcx.JdbcDataSource;
@@ -10,6 +11,51 @@ import java.time.LocalDateTime;
 import static org.junit.jupiter.api.Assertions.*;
 
 class ContainerCalendarSourceMapperTest {
+    /** 后续观测可将实际到港修正为更早日期，两入口须取同一条最新实际记录。 */
+    @Test
+    void usesLatestObservedArrivalIncludingSameObservationIdTieBreakAcrossBothEntrypoints() throws Exception {
+        var ds = new JdbcDataSource();
+        ds.setURL("jdbc:h2:mem:arrival-source-correction;MODE=MySQL;DB_CLOSE_DELAY=-1");
+        try (var connection = ds.getConnection(); var sql = connection.createStatement()) {
+            sql.execute("CREATE TABLE fl_container_booking(id BIGINT PRIMARY KEY,cabinet_no VARCHAR,container_no VARCHAR," +
+                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_warehouse_code VARCHAR," +
+                "actual_port_arrival_at TIMESTAMP,estimated_port_arrival_at TIMESTAMP,unloading_completed_at TIMESTAMP,record_status VARCHAR)");
+            sql.execute("CREATE TABLE fl_terminal_drayage(container_booking_id BIGINT,actual_empty_return_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_carrier_schedule_query(id BIGINT,version INT,status VARCHAR)");
+            sql.execute("CREATE TABLE fl_carrier_schedule_node_fact(id BIGINT,query_id BIGINT,container_booking_id BIGINT," +
+                "standard_node VARCHAR,actual_at TIMESTAMP,observed_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_direct_delivery_unloading(container_booking_id BIGINT,actual_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_outbound_dispatch(container_booking_id BIGINT,confirmed_at TIMESTAMP,reversed_at TIMESTAMP,status VARCHAR)");
+            sql.execute("INSERT INTO fl_container_booking(id,cabinet_no,estimated_port_arrival_at,record_status) VALUES " +
+                "(1,'D1','2026-10-29 08:00:00','ACTIVE'),(2,'D2','2026-10-29 08:00:00','ACTIVE')");
+            sql.execute("INSERT INTO fl_carrier_schedule_query VALUES(1,0,'READY'),(2,0,'READY')");
+            sql.execute("INSERT INTO fl_outbound_dispatch SELECT id,'2026-10-01 00:00:00',NULL,'WAITING_FOR_LOADING' FROM fl_container_booking");
+            sql.execute("INSERT INTO fl_carrier_schedule_node_fact VALUES " +
+                "(1,1,1,'ARRIVED_DESTINATION_PORT','2026-10-23 14:00:00','2026-10-24 14:00:00')," +
+                "(2,1,1,'ARRIVED_DESTINATION_PORT','2026-10-21 14:00:00','2026-10-25 14:00:00')," +
+                "(3,1,1,'ARRIVED_DESTINATION_PORT',NULL,'2026-10-26 14:00:00')," +
+                "(4,2,2,'ARRIVED_DESTINATION_PORT','2026-10-24 14:00:00','2026-10-25 14:00:00')," +
+                "(5,2,2,'ARRIVED_DESTINATION_PORT','2026-10-22 14:00:00','2026-10-25 14:00:00')");
+        }
+        var config = new MybatisConfiguration();
+        config.setEnvironment(new Environment("test", new JdbcTransactionFactory(), ds));
+        config.addMapper(ContainerCalendarSourceMapper.class);
+        config.addMapper(CarrierScheduleQueryMapper.class);
+        try (var session = new MybatisSqlSessionFactoryBuilder().build(config).openSession()) {
+            var from = LocalDateTime.parse("2026-10-01T00:00:00");
+            var calendar = session.getMapper(ContainerCalendarSourceMapper.class).sources(from, from.minusDays(2), from.minusDays(4), from.plusMonths(1));
+            var workbench = session.getMapper(CarrierScheduleQueryMapper.class).selectContainerActualFacts(java.util.List.of(1L, 2L));
+            assertEquals(2, calendar.size());
+            assertEquals(2, workbench.size());
+            for (int index = 0; index < calendar.size(); index++) {
+                var expected = LocalDateTime.parse(index == 0 ? "2026-10-21T14:00:00" : "2026-10-22T14:00:00");
+                assertEquals(expected, calendar.get(index).arrivalAt());
+                assertEquals("ACTUAL", calendar.get(index).arrivalType());
+                assertEquals(expected, workbench.get(index).arrivedDestinationPortAt());
+                assertEquals(calendar.get(index).arrivalAt().plusDays(2).toLocalDate(), workbench.get(index).arrivedDestinationPortAt().plusDays(2).toLocalDate());
+            }
+        }
+    }
     /** 使用实际 Mapper 核对跨月默认日期候选、缺日期与真实出仓边界。 */
     @Test
     void selectsShiftedArrivalUndatedAndOlderReturnCandidatesWithoutInactiveOrUndepartedContainers() throws Exception {

lastleg-service/AGENTS.md

@@ -77,7 +77,7 @@
 | 整车调度与理货审核 | `dispatch/controller/DispatchAggregateController.java` → `dispatch/service/DispatchAggregateService.java` 的提交及两级审核；同一排车先调度审核、再理货审核，通过后才允许真实扫码。资源、货物或路线关键变更使原依据失效；零扫码显式退回后重新审核，不复用旧客户子单审核状态 |
 | 外接询价、确认占位及取消 | `fleet/trip/PlatformFleetBookingController.java`、`FleetBookingService.java`、`FleetBookingReservations.java`；客户从`fleet/customer/`读取IAM有效主档与资格，询价不占位，确认后与自有货计划共同校验逐段容量。约定金额不代表应收/实收，`FleetBookingIncomingGateway`由`transfer/fleet/FleetIncomingAdapter`实现来货登记/实收确认，排车关联通过`FleetDispatchGateway.sourceCargo`核对实收来源 |
 | 拣货前计划容量与逐段余位 | `FleetTripExecutionService.capacityPlan/confirmCapacityPlan`、`/fleet/trips/{tripNo}/capacity-plan`；保存自有货的计划值，不检查拣货完成、不推进审核或扣库存；`planValid`校验当前货物hash，不把计划值当实测值，资源/计划/关联变更后须重新核对 |
-| 实物装载、逐段容量与双端整车发车 | 两端`dispatches/{dispatchNo}/loading-complete`统一调用`dispatch/service/DispatchLoadingDepartureService.java`，同一事务复用实载确认、派送单准备及发车，成功直接`DELIVERING`；请求携带唯一`recordVersion`，原键恢复最终结果。公开手工安排派送、`/depart`入口已移除；内部`AFTER_LOADING`和步骤命令只用于事务编排。真实PDA拣货须核平，不重复库存SHIP，Fleet容量和资源资格仍复核；未知费用不补零、不阻塞发运，真实已明确外接报价沿原费用来源防重 |
+| 实物装载、逐段容量与双端整车发车 | 两端`dispatches/{dispatchNo}/loading-complete`统一调用`dispatch/service/DispatchLoadingDepartureService.java`，实载确认成功进入`AFTER_LOADING`；请求携带唯一`recordVersion`，原键恢复原装车后结果。`dispatch/service/DispatchLoadingDocumentService.java`复用整车附加照片与账本，平台/PDA均经`loading-documents`保存；五框齐全的最后一次绑定与派送准备、发车同事务，成功`DELIVERING`。公开手工安排派送、`/depart`入口仍不开放。真实PDA拣货须核平，不重复库存SHIP，Fleet容量和资源资格仍复核；未知费用不补零、不阻塞发运，真实已明确外接报价沿原费用来源防重 |
 | 车次货物结案、车辆和司机分别释放 | `fleet/trip/FleetTripCompletionService.java`、`FleetCompletionModels.java`；平台 `/fleet/trips/{tripNo}/completion`、`/complete`、`/resources/release`，独立complete/release权限。结案核对所有派送终态与实发数量；实际任务结束时间/地点及车辆结束状态单独记录，不以结案或收款自动释放资源 |
 | 跨服务 HTTP 客户端装配 | `config/LastlegRestClientFactory.java` |
 | 数据库基线、表索引与中文注释契约 | `src/main/resources/db/lastleg.sql` |

lastleg-service/docs/lastleg-internal-modularization-baseline.md

@@ -28,6 +28,10 @@
 
 `fleet.ownedbusiness`只为原排车装车后的自有车辆组合运营资料。五条精确引用限`OwnedBusinessModels→DispatchViews`、`OwnedBusinessProjection→DispatchContracts`、`OwnedBusinessQueryService→DispatchContracts/DispatchTypes/DispatchDetailReader`，均为`dispatch.port`公开事实或只读应用端口；不增加`fleet→dispatch-delivery`通用许可，不共享原排车实体、Mapper或具体Service。原详情适配器在dispatch内部委托唯一提供者。`DispatchAggregateService→OwnedBusinessOwnershipCapture`仅在原装车事务捕获归属，不能反向调用运营查询；捕获失败随原确认回滚。反向合同拒绝具体持久化/Service引用、其他消费者借用端口许可及任何包循环。
 
+### 装车资料触发派送边界（2026-10-21）
+
+`DispatchLoadingDocumentService`、`DispatchLoadingDepartureService`及平台/PDA两个装车资料Controller只引用`fleet.ownedbusiness.port.DispatchLoadingPhotoPort`的公开照片、版本、绑定请求和结果。`DispatchLoadingPhotoAdapter`在车队内部复用原附加表、上传账本和文件校验，不反向调用排车服务。排车服务持整车父锁，在装车确认或资料保存后核对两项条件，同一事务推进派送并记录原结果。结构门禁仅开放上述四类到此端口的精确引用，不开放车队Service、Repository或Mapper，也不新增包循环。
+
 ### 外配业务原排车详情读取边界（2026-10-21）
 
 `OutsourcedBusinessModels → DispatchViews` 仅组合既有 `dispatch.port` 公开详情。依赖登记与已有外配反向合同同步，不开放 `fleet→dispatch-delivery` 通用许可；原排车实体、Mapper、具体 Service 及其他消费者仍由门禁拒绝。

lastleg-service/scripts/analyze-lastleg-dependencies.test.mjs

@@ -72,6 +72,11 @@ test('fleet stays a business slice and its policies have no infrastructure depen
       && edge.target === 'com.baiyue.lastleg.fleet.exception.FleetHandoverPdaQuery'
     || edge.source === 'com.baiyue.lastleg.dispatch.service.DispatchAggregateService'
       && edge.target === 'com.baiyue.lastleg.fleet.ownedbusiness.port.OwnedBusinessOwnershipCapture'
+    || ['com.baiyue.lastleg.dispatch.service.DispatchLoadingDocumentService',
+      'com.baiyue.lastleg.dispatch.service.DispatchLoadingDepartureService',
+      'com.baiyue.lastleg.dispatch.controller.DispatchLoadingDocumentController',
+      'com.baiyue.lastleg.dispatch.pda.controller.PdaDispatchLoadingDocumentController'].includes(edge.source)
+      && edge.target === 'com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort'
     || [
       'TransportTaskModels->pickup.FleetPickupModels', 'TransportTaskModels->trip.FleetTripModels',
       'TransportTaskProjection->trip.FleetTripEntity', 'TransportTaskProjection->trip.TransportTripChanged',

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchAggregateController.java

@@ -77,6 +77,12 @@ public class DispatchAggregateController {
     public ApiResponse<CommandResult> loadingComplete(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@RequestBody DispatchCommands.LoadingComplete request) {
         return ApiResponse.success(loadingDeparture.complete(DispatchActorFactory.platform(user),dispatchNo,request));
     }
+    /** 派送异常登记不触发签收或退货入库。 */
+    @PostMapping("/{dispatchNo}/exceptions")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<CommandResult> markException(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@RequestBody DispatchCommands.MarkException request) {
+        return ApiResponse.success(service.markException(DispatchActorFactory.platform(user),dispatchNo,request));
+    }
     /** 本车证据先上传；维护和当前待审权限分别由服务端核验，引用随对应命令保存。 */
     @PostMapping(value="/{dispatchNo}/evidence/{kind}",consumes=org.springframework.http.MediaType.MULTIPART_FORM_DATA_VALUE)
     @PreAuthorize("hasAnyAuthority('platform:overseas-warehouse:dispatch:edit','platform:fleet:trip:dispatch-review','platform:fleet:trip:loading-review')")

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchLoadingDocumentController.java

@@ -0,0 +1,60 @@
+package com.baiyue.lastleg.dispatch.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.dispatch.controller.DispatchActorFactory;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort.*;
+import com.baiyue.lastleg.dispatch.service.DispatchLoadingDocumentService;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.*;
+import org.springframework.http.*;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+/** 平台排车装车资料入口，与另一端共用五框和自动派送门禁。 */
+@RestController
+@Validated
+@RequestMapping("/api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents")
+public class DispatchLoadingDocumentController {
+    private final DispatchLoadingDocumentService service;
+    /** Controller只负责会话与输入映射，所有资料和状态规则归服务。 */
+    public DispatchLoadingDocumentController(DispatchLoadingDocumentService service){this.service=service;}
+    /** 读取本车已保存照片，不以设备缓存作为上传事实。 */
+    @GetMapping
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")
+    public ApiResponse<Documents> get(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo) {
+        return ApiResponse.success(service.get(DispatchActorFactory.platform(user),dispatchNo));
+    }
+    /** 上传先记录原请求，成功回执后再保存本车槽位引用。 */
+    @PostMapping(value="/{slot}/uploads",consumes=MediaType.MULTIPART_FORM_DATA_VALUE)
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Photo> upload(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable Slot slot,
+        @RequestParam @Size(min=8,max=128) String idempotencyKey,@RequestPart("file") MultipartFile file) {
+        return ApiResponse.success(service.upload(DispatchActorFactory.platform(user),dispatchNo,slot,idempotencyKey,file));
+    }
+    /** 最后一框保存成功时自动进入派送中，不新增人工发车按钮。 */
+    @PutMapping("/{slot}")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Documents> bind(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,
+        @PathVariable Slot slot,@Valid @RequestBody BindPhoto request) {
+        return ApiResponse.success(service.bind(DispatchActorFactory.platform(user),dispatchNo,slot,request));
+    }
+    /** 原上传仅允许当前有权限的原操作者恢复。 */
+    @GetMapping("/uploads/{idempotencyKey}")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Photo> recover(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable String idempotencyKey) {
+        return ApiResponse.success(service.recover(DispatchActorFactory.platform(user),dispatchNo,idempotencyKey));
+    }
+    /** 每次预览核对本车当前绑定，文件不得跨车跨仓读取。 */
+    @GetMapping("/{slot}/files/{fileId}/content")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")
+    public ResponseEntity<byte[]> content(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable Slot slot,@PathVariable @Positive long fileId) {
+        var value=service.content(DispatchActorFactory.platform(user),dispatchNo,slot,fileId);
+        return ResponseEntity.ok().cacheControl(CacheControl.noStore()).contentType(MediaType.parseMediaType(value.photo().contentType()))
+            .header("X-Content-Type-Options","nosniff").body(value.content());
+    }
+}
+

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/SmartDispatchController.java

@@ -26,7 +26,7 @@ public class SmartDispatchController {
     /** 读取实际候选，不在草稿域复制来源筛选逻辑。 */
     @GetMapping("/candidates")
     @PreAuthorize("hasAuthority('"+OverseasPermissions.DISPATCH_LIST+"')")
-    public ApiResponse<CandidateList> candidates(@AuthenticationPrincipal AuthenticatedUser user,@RequestParam String warehouseId,
+    public ApiResponse<CandidateList> candidates(@AuthenticationPrincipal AuthenticatedUser user,@RequestParam(required=false) String warehouseId,
         @RequestParam(required=false)List<Long> planIds,@RequestParam(required=false)String orderNo,
         @RequestParam(required=false)String destinationWarehouseCode,@RequestParam(required=false)String sourceStage,@RequestParam(required=false)String draftToken,
         @RequestParam(defaultValue="1")int page,@RequestParam(defaultValue="20")int size,@RequestParam(defaultValue="ALL")String warehouseTab) {

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/entity/DispatchAggregate.java

@@ -24,6 +24,7 @@ public class DispatchAggregate {
     private String dispatchReviewJson;
     private String loadingReviewJson;
     private String resourcesJson;
+    private String exceptionsJson;
     private String vehiclePlate;
     private String route;
     private LocalDateTime plannedDepartureAt;

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/gateway/DispatchEvidenceGateway.java

@@ -4,7 +4,7 @@ import org.springframework.web.multipart.MultipartFile;
 
 /** 车辆、司机及审核补充证据属于本张整车，不能借司机主档或客户文件授权。 */
 public interface DispatchEvidenceGateway {
-    enum Kind { VEHICLE, DRIVER, DRIVER_PHOTO }
+    enum Kind { VEHICLE, DRIVER, DRIVER_PHOTO, EXCEPTION }
     record File(Long fileId,String fileName,String contentType,long sizeBytes) { }
     /** 上传只写本车、本类证据。 */
     File upload(long dispatchId,Kind kind,String operator,MultipartFile file);

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/gateway/HttpDispatchEvidenceGateway.java

@@ -83,9 +83,9 @@ public class HttpDispatchEvidenceGateway implements DispatchEvidenceGateway {
             || !supportedType(kind,value.contentType()) || value.sizeBytes()==null || value.sizeBytes()<=0 || value.sizeBytes()>MAX)throw invalid();
         return new File(value.fileId(),value.fileName(),value.contentType(),value.sizeBytes());
     }
-    /** 司机本人照片只接受图片；车辆和驾驶证沿现有PDF/图片证据规则。 */
+    /** 司机本人照片与异常证据只接受图片；车辆和驾驶证沿现有PDF/图片证据规则。 */
     private static boolean supportedType(Kind kind,String contentType) {
-        return TYPES.contains(Objects.toString(contentType,"")) && (kind!=Kind.DRIVER_PHOTO || !"application/pdf".equals(contentType));
+        return TYPES.contains(Objects.toString(contentType,"")) && ((kind!=Kind.DRIVER_PHOTO && kind!=Kind.EXCEPTION) || !"application/pdf".equals(contentType));
     }
     /** 无效证据不能作为已核实资料。 */
     private static ResponseStatusException invalid(){return new ResponseStatusException(HttpStatus.BAD_REQUEST,"证据须为本车有效PDF、JPG或PNG，最大10MiB");}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchAggregateMapper.java

@@ -94,11 +94,11 @@ public interface DispatchAggregateMapper {
         UPDATE ll_dispatch_order SET status=#{r.status},stage=#{r.stage},record_version=#{r.recordVersion},
           review_state=#{r.reviewState},review_round=#{r.reviewRound},review_basis_hash=#{r.reviewBasisHash},
           dispatch_review_json=#{r.dispatchReviewJson},loading_review_json=#{r.loadingReviewJson},
-          cargo_hash=#{r.cargoHash},cargo_revision=#{r.cargoRevision},resources_json=#{r.resourcesJson},vehicle_plate=#{r.vehiclePlate},planned_departure_at=#{r.plannedDepartureAt},
+          exceptions_json=#{r.exceptionsJson},cargo_hash=#{r.cargoHash},cargo_revision=#{r.cargoRevision},resources_json=#{r.resourcesJson},vehicle_plate=#{r.vehiclePlate},planned_departure_at=#{r.plannedDepartureAt},
           estimated_arrival_at=#{r.estimatedArrivalAt},remark=#{r.remark},loading_completed_at=#{r.loadingCompletedAt},
           loading_completion_hash=#{r.loadingCompletionHash},loading_confirmation_json=#{r.loadingConfirmationJson},arrangement_key=#{r.arrangementKey},
           arrangement_business_hash=#{r.arrangementBusinessHash},departed_at=#{r.departedAt},
-          delivery_completed_at=#{r.deliveryCompletedAt},picked_package_count=#{r.pickedPackageCount},
+          delivery_completed_at=#{r.deliveryCompletedAt},package_count=#{r.packageCount},pallet_count=#{r.palletCount},picked_package_count=#{r.pickedPackageCount},
           shipped_package_count=#{r.shippedPackageCount},updated_at=#{r.updatedAt}
         WHERE id=#{r.id} AND record_version=#{version}
         """)

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchCandidatePageMapper.java

@@ -50,7 +50,8 @@ public interface DispatchCandidatePageMapper {
         }
         /** 仓库页签也是服务端筛选，分页后不能再用本地筛选伪装完整结果。 */
         private static String filtered(boolean count) {
-            return " FROM ("+rows(count)+") candidates WHERE overseasWarehouseId=#{query.warehouseId}"
+            return " FROM ("+rows(count)+") candidates WHERE 1=1"
+                +"<if test='query.warehouseId != null'> AND overseasWarehouseId=#{query.warehouseId}</if>"
                 +"<if test='query.destinationWarehouseCode != null'> AND fbaWarehouseCode=#{query.destinationWarehouseCode}</if>"
                 +"<if test=\"query.warehouseTab == 'LAX'\"> AND LOWER(CONCAT(COALESCE(overseasWarehouseCode,''),' ',COALESCE(overseasWarehouseName,''))) REGEXP 'lax|洛杉矶|los angeles'</if>"
                 +"<if test=\"query.warehouseTab == 'NYC'\"> AND LOWER(CONCAT(COALESCE(overseasWarehouseCode,''),' ',COALESCE(overseasWarehouseName,''))) REGEXP 'nyc|jfk|(^|[^a-z])ny([^a-z]|$)|纽约|new[ -]?york'</if>";

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchSourceMapper.java

@@ -93,6 +93,11 @@ public interface DispatchSourceMapper {
     @Select("SELECT p.id FROM ll_inbound_plan_pallet p JOIN ll_inbound_plan ip ON ip.id=p.plan_id WHERE p.id=#{id} AND ip.customer_id=#{customer} FOR UPDATE")
     Long lockPlanPallet(@Param("customer") String customer, @Param("id") Long id);
 
+    /** 原计划完成实收后才能把预排估算替换为实际整托数量，避免收货中提前锁定半托。 */
+    @Select("SELECT COUNT(*) FROM ll_inbound_plan_pallet p JOIN ll_inbound_plan ip ON ip.id=p.plan_id AND ip.customer_id=p.customer_id "
+        + "WHERE p.id=#{id} AND p.customer_id=#{customer} AND ip.status IN ('COMPLETED','PENDING_RECONCILIATION')")
+    int receivedPlanCompleted(@Param("customer") String customer,@Param("id") Long id);
+
     /** 退回来源仍使用本票实际实收，不借普通入仓别名。 */
     @Select("SELECT id FROM ll_return_stock_receipt WHERE id=#{id} AND customer_id=#{customer} FOR UPDATE")
     Long lockReturn(@Param("customer") String customer, @Param("id") Long id);

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/controller/DispatchPdaController.java

@@ -57,7 +57,7 @@ public class DispatchPdaController {
         return ApiResponse.success(workflow.loading(DispatchActorFactory.pda(user),dispatchNo));
     }
 
-    /** 真实扫码核平后确认装车即发车，两端使用同一事务命令。 */
+    /** 真实扫码核平后确认装车进入装车后，两端共用同一命令并等待五张装车照片。 */
     @PostMapping("/{dispatchNo}/loading-complete")
     public ApiResponse<DispatchContracts.CommandResult> loadingComplete(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@RequestBody DispatchCommands.LoadingComplete request) {
         return ApiResponse.success(loadingDeparture.complete(DispatchActorFactory.pda(user),dispatchNo,request));

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/controller/PdaDispatchLoadingDocumentController.java

@@ -0,0 +1,60 @@
+package com.baiyue.lastleg.dispatch.pda.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.dispatch.controller.DispatchActorFactory;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort.*;
+import com.baiyue.lastleg.dispatch.service.DispatchLoadingDocumentService;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.*;
+import org.springframework.http.*;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+/** 绑定仓PDA装车资料入口，与另一端共用五框和自动派送门禁。 */
+@RestController
+@Validated
+@RequestMapping("/api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents")
+public class PdaDispatchLoadingDocumentController {
+    private final DispatchLoadingDocumentService service;
+    /** Controller只负责会话与输入映射，所有资料和状态规则归服务。 */
+    public PdaDispatchLoadingDocumentController(DispatchLoadingDocumentService service){this.service=service;}
+    /** 读取本车已保存照片，不以设备缓存作为上传事实。 */
+    @GetMapping
+    @PreAuthorize("hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR')")
+    public ApiResponse<Documents> get(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo) {
+        return ApiResponse.success(service.get(DispatchActorFactory.pda(user),dispatchNo));
+    }
+    /** 上传先记录原请求，成功回执后再保存本车槽位引用。 */
+    @PostMapping(value="/{slot}/uploads",consumes=MediaType.MULTIPART_FORM_DATA_VALUE)
+    @PreAuthorize("hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR')")
+    public ApiResponse<Photo> upload(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable Slot slot,
+        @RequestParam @Size(min=8,max=128) String idempotencyKey,@RequestPart("file") MultipartFile file) {
+        return ApiResponse.success(service.upload(DispatchActorFactory.pda(user),dispatchNo,slot,idempotencyKey,file));
+    }
+    /** 最后一框保存成功时自动进入派送中，不新增人工发车按钮。 */
+    @PutMapping("/{slot}")
+    @PreAuthorize("hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR')")
+    public ApiResponse<Documents> bind(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,
+        @PathVariable Slot slot,@Valid @RequestBody BindPhoto request) {
+        return ApiResponse.success(service.bind(DispatchActorFactory.pda(user),dispatchNo,slot,request));
+    }
+    /** 原上传仅允许当前有权限的原操作者恢复。 */
+    @GetMapping("/uploads/{idempotencyKey}")
+    @PreAuthorize("hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR')")
+    public ApiResponse<Photo> recover(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable String idempotencyKey) {
+        return ApiResponse.success(service.recover(DispatchActorFactory.pda(user),dispatchNo,idempotencyKey));
+    }
+    /** 每次预览核对本车当前绑定，文件不得跨车跨仓读取。 */
+    @GetMapping("/{slot}/files/{fileId}/content")
+    @PreAuthorize("hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR')")
+    public ResponseEntity<byte[]> content(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable Slot slot,@PathVariable @Positive long fileId) {
+        var value=service.content(DispatchActorFactory.pda(user),dispatchNo,slot,fileId);
+        return ResponseEntity.ok().cacheControl(CacheControl.noStore()).contentType(MediaType.parseMediaType(value.photo().contentType()))
+            .header("X-Content-Type-Options","nosniff").body(value.content());
+    }
+}
+

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/port/DispatchCommands.java

@@ -73,6 +73,13 @@ public final class DispatchCommands {
         public LoadingComplete { recordVersion = requireVersion(recordVersion); }
     }
 
+    /** 派送异常仅登记事实，不改变派送、签收或库存。 */
+    public record MarkException(Long recordVersion, String idempotencyKey, ExceptionType exceptionType,
+                                ReturnDirection returnDirection, String description, List<Long> imageFileIds) {
+        /** 必填版本用于阻止过期页面覆盖当前排车。 */
+        public MarkException { recordVersion = requireVersion(recordVersion); }
+    }
+
     public record Depart(Long recordVersion, String idempotencyKey, String remark) {
         /** 实际发车不得接受缺省版本。 */
         public Depart { recordVersion = requireVersion(recordVersion); }

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/port/DispatchTypes.java

@@ -9,6 +9,8 @@ public final class DispatchTypes {
     public enum Stage { BEFORE_LOADING, LOADING, AFTER_LOADING, DELIVERING, DELIVERED }
     public enum ReviewState { DRAFT, DISPATCH_PENDING, DISPATCH_REJECTED, LOADING_PENDING, LOADING_REJECTED, APPROVED }
     public enum ReviewStatus { NOT_SUBMITTED, PENDING, APPROVED, REJECTED }
+    public enum ExceptionType { REFUSED, PARTIAL_RECEIPT, VEHICLE_EXCEPTION }
+    public enum ReturnDirection { OVERSEAS_WAREHOUSE, OTHER }
     public enum Decision { APPROVED, REJECTED }
     public enum ResourceMode { MASTER, EXTERNAL }
     public enum ActorMode { PLATFORM, PDA }
@@ -18,6 +20,6 @@ public final class DispatchTypes {
     public enum Effect { APPLIED, EXISTING }
     public enum Action {
         CREATE, EDIT, ADD_CARGO, REMOVE_CARGO, CANCEL, SUBMIT_REVIEW, DISPATCH_REVIEW,
-        LOADING_REVIEW, RETURN_TO_REVIEW, PICK, LOADING_COMPLETE, ARRANGE_DELIVERY, DEPART
+        LOADING_REVIEW, RETURN_TO_REVIEW, PICK, LOADING_COMPLETE, ARRANGE_DELIVERY, DEPART, MARK_EXCEPTION
     }
 }

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/port/DispatchViews.java

@@ -44,7 +44,11 @@ public final class DispatchViews {
 
     public record DispatchInfo(String route, Instant plannedDepartureAt, Instant departedAt,
                                  Instant estimatedArrivalAt, List<FbaAppointment> fbaAppointments,
-                                 List<BatchReference> appointmentBatches) { }
+                                 List<BatchReference> appointmentBatches, List<ExceptionRecord> exceptions) { }
+
+    /** 排车级异常记录；退货去向只描述安排，不产生退货入库事实。 */
+    public record ExceptionRecord(ExceptionType exceptionType, ReturnDirection returnDirection,
+                                  String description, List<Long> imageFileIds, Instant occurredAt) { }
 
     public record Documents(String dispatchNo, List<DispatchDeliveryModels.OutboundReference> outbounds,
                               List<DispatchDeliveryModels.DeliveryReference> deliveries,

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/repository/DispatchSourceRepository.java

@@ -74,6 +74,8 @@ public class DispatchSourceRepository {
     public Long lockOrder(String customer, Long id) { return source.lockOrder(customer,id); }
     /** 锁定真实计划托盘根。 */
     public Long lockPlan(String customer, Long id) { return source.lockPlanPallet(customer,id); }
+    /** 只读核对原计划已经结束实际收货。 */
+    public boolean receivedPlanCompleted(String customer,Long id){return source.receivedPlanCompleted(customer,id)==1;}
     /** 锁定实际退回收据根。 */
     public Long lockReturn(String customer, Long id) { return source.lockReturn(customer,id); }
     /** 真实库存数量及版本。 */

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchAggregateService.java

@@ -146,7 +146,8 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
     @Transactional(readOnly=true,isolation=Isolation.REPEATABLE_READ)
     public DispatchPlanningModels.CandidateList candidates(Actor actor,DispatchPlanningModels.CandidateQuery query) {
         requirePlatform(actor);
-        if(query==null || query.warehouseId()==null || !query.warehouseId().matches("[1-9][0-9]*")) throw bad("请选择真实海外起运仓");
+        // 未指定起运仓时按区域浏览；写入草稿仍由来源确定唯一真实起运仓。
+        if(query==null || query.warehouseId()!=null && !query.warehouseId().matches("[1-9][0-9]*")) throw bad("起运仓筛选无效");
         if(query.planIds()!=null && (query.planIds().size()>500 || query.planIds().stream().anyMatch(id->id==null || id<=0))) throw bad("计划筛选不合法");
         if(query.page()<1 || query.size()<1 || query.size()>50 || !Set.of("ALL","LAX","NYC").contains(Objects.toString(query.warehouseTab(),"")))throw bad("候选分页或仓库页签不合法");
         var normalized=new DispatchPlanningModels.CandidateQuery(query.warehouseId(),query.planIds(),trim(query.orderNo()),
@@ -238,7 +239,12 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
     /** 上传只返回本车证据；待审按当前审核权限授权，客服阶段按维护权限授权。 */
     public com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.File uploadEvidence(Actor actor,String number,
         com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind kind,org.springframework.web.multipart.MultipartFile file) {
-        requirePlatform(actor);var row=required(actor,number,false);requireEditing(row,row.getRecordVersion());
+        requirePlatform(actor);var row=required(actor,number,false);
+        if(kind==com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.EXCEPTION) {
+            requireExceptionAllowed(actor,row,row.getRecordVersion());
+            return evidence.upload(row.getId(),kind,actor.operatorId(),file);
+        }
+        requireEditing(row,row.getRecordVersion());
         Action permission = ReviewState.DISPATCH_PENDING.name().equals(row.getReviewState()) ? Action.DISPATCH_REVIEW
             : ReviewState.LOADING_PENDING.name().equals(row.getReviewState()) ? Action.LOADING_REVIEW : Action.EDIT;
         if(!hasPermission(actor,permission))throw new BizException(ResultCode.FORBIDDEN,"无当前阶段附件上传权限");
@@ -534,7 +540,7 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
             List.copyOf(pallets),row.getLoadingConfirmationJson()==null?null:read(row.getLoadingConfirmationJson(),ConfirmedLoad.class),gate,List.copyOf(missing));
     }
 
-    /** 内部实载步骤：扫码核平后保存装载证据，中间装车后状态由外层同事务继续推进发车。 */
+    /** 实载确认：扫码核平后保存装载证据并进入装车后，五张装车资料齐全再推进派送。 */
     @Transactional(isolation=Isolation.READ_COMMITTED)
     public CommandResult loadingComplete(Actor actor,String number,DispatchCommands.LoadingComplete request) {
         required(actor,number,false);fleet.lockDispatchShell(number);var row=required(actor,number,true);
@@ -663,6 +669,40 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         for(var id:ids)evidence.metadata(dispatch,kind,id);
     }
 
+    /** 仅派送中登记异常；原键重试先恢复，避免追加重复记录。 */
+    @Transactional(isolation=Isolation.READ_COMMITTED)
+    public CommandResult markException(Actor actor,String number,DispatchCommands.MarkException request) {
+        var row=lockPlatform(actor,number);
+        if(!hasPermission(actor,Action.MARK_EXCEPTION))throw new BizException(ResultCode.FORBIDDEN,"无标记异常权限");
+        var identity=identity(actor,number,Action.MARK_EXCEPTION,request.recordVersion(),request.idempotencyKey(),request);
+        var replay=commands.replay(actor,number,identity);if(replay.isPresent())return replay.get();
+        requireExceptionAllowed(actor,row,request.recordVersion());
+        if(request.exceptionType()==null)throw bad("请选择异常类型");
+        var description=trim(request.description());
+        if(description!=null && description.length()>1000)throw bad("异常说明不能超过1000字");
+        var ids=request.imageFileIds()==null?List.<Long>of():request.imageFileIds();
+        if(ids.size()>20 || ids.stream().anyMatch(id->id==null || id<=0) || ids.stream().distinct().count()!=ids.size())throw bad("异常图片引用无效或超过20张");
+        // 文件须属于本车异常类别，不能借用其他车辆或审核附件。
+        for(var id:ids)evidence.metadata(row.getId(),com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.EXCEPTION,id);
+        var records=new ArrayList<>(exceptionRecords(row));
+        records.add(new DispatchViews.ExceptionRecord(request.exceptionType(),request.returnDirection(),description,List.copyOf(ids),Instant.now()));
+        row.setExceptionsJson(write(records));
+        return saveCommand(row,actor,identity,description);
+    }
+
+    /** 异常登记复用排车维护权限；版本、任务类型与阶段由服务端再次核验。 */
+    private void requireExceptionAllowed(Actor actor,DispatchAggregate row,long version) {
+        if(!hasPermission(actor,Action.MARK_EXCEPTION))throw new BizException(ResultCode.FORBIDDEN,"无标记异常权限");
+        if(row.getRecordVersion()!=version)throw conflict("排车版本已变化，请刷新后再标记异常");
+        if(!actions(actor,row).get(Action.MARK_EXCEPTION).allowed())throw conflict("仅派送中的仓库派送排车可以标记异常");
+    }
+
+    /** 尚未登记时为空集合，已登记记录按保存顺序完整回看。 */
+    private List<DispatchViews.ExceptionRecord> exceptionRecords(DispatchAggregate row) {
+        if(row.getExceptionsJson()==null)return List.of();
+        return Arrays.asList(read(row.getExceptionsJson(),DispatchViews.ExceptionRecord[].class));
+    }
+
     /** 同一只读快照返回分页、总数和基集分布，不能在前端过滤当前页。 */
     @Transactional(readOnly=true,isolation=Isolation.REPEATABLE_READ)
     public DispatchViews.Page page(Actor actor, DispatchViews.Query query) {
@@ -699,7 +739,7 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         var documents=new DispatchViews.Documents(number,repository.outbounds(row.getId()),deliveries,instant(row.getCreatedAt()),instant(row.getUpdatedAt()),row.getRemark());
         return new DispatchViews.Detail(number,row.getTaskType()==null?"DELIVERY":row.getTaskType(),Status.valueOf(row.getStatus()),Stage.valueOf(row.getStage()),row.getRecordVersion(),ReviewState.valueOf(row.getReviewState()),
             reviews(row),counts(row),reconciled(row),actions(actor,row),new DispatchViews.VehicleInfo(resources.vehicle(),resources.driver()),
-            new DispatchViews.DispatchInfo(row.getRoute(),instant(row.getPlannedDepartureAt()),instant(row.getDepartedAt()),instant(row.getEstimatedArrivalAt()),appointments,batchRefs),
+            new DispatchViews.DispatchInfo(row.getRoute(),instant(row.getPlannedDepartureAt()),instant(row.getDepartedAt()),instant(row.getEstimatedArrivalAt()),appointments,batchRefs,exceptionRecords(row)),
             documents,orderDetails(cargo));
     }
 
@@ -817,6 +857,7 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         for(var action:Action.values()) {
             if(action==Action.ARRANGE_DELIVERY || action==Action.DEPART)continue;
             boolean state=switch(action) {
+                case MARK_EXCEPTION -> active && stage==Stage.DELIVERING;
                 case CREATE -> actor.mode()==ActorMode.PLATFORM;
                 case EDIT,ADD_CARGO,REMOVE_CARGO,CANCEL -> active && stage==Stage.BEFORE_LOADING && n(row.getPickedPackageCount())==0;
                 case SUBMIT_REVIEW -> active && stage==Stage.BEFORE_LOADING && n(row.getPickedPackageCount())==0 && canSubmitReview(row.getReviewState());

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchCommandCodec.java

@@ -73,7 +73,7 @@ public final class DispatchCommandCodec {
             case DEPART -> DispatchResults.Departed.class;
             case ARRANGE_DELIVERY -> DispatchDeliveryModels.ArrangementResult.class;
             case CREATE, EDIT, ADD_CARGO, REMOVE_CARGO, CANCEL, SUBMIT_REVIEW,
-                 DISPATCH_REVIEW, LOADING_REVIEW, RETURN_TO_REVIEW -> DispatchResults.Saved.class;
+                 DISPATCH_REVIEW, LOADING_REVIEW, RETURN_TO_REVIEW, MARK_EXCEPTION -> DispatchResults.Saved.class;
         };
     }
 

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchLoadingDepartureService.java

@@ -3,13 +3,14 @@ package com.baiyue.lastleg.dispatch.service;
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import com.baiyue.lastleg.dispatch.port.*;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.*;
 import java.util.List;
 import static com.baiyue.lastleg.dispatch.port.DispatchContracts.*;
 import static com.baiyue.lastleg.dispatch.port.DispatchTypes.*;
 
-/** 两端装车完成即发车：所有中间状态只存在于同一事务，原请求只恢复最终结果。 */
+/** 装车与资料可并行完成，两项齐全时在当前事务自动推进派送。 */
 @Service
 public class DispatchLoadingDepartureService {
     private final DispatchAggregateService workflow;
@@ -17,38 +18,52 @@ public class DispatchLoadingDepartureService {
     private final DispatchDepartureService departure;
     private final DispatchCommandLedger commands;
     private final DispatchCommandHasher hashes;
+    private final DispatchLoadingPhotoPort documents;
 
     /** 复用装车、派送和发车的真实规则，不另建库存或运输状态实现。 */
     public DispatchLoadingDepartureService(DispatchAggregateService workflow,DispatchDeliveryPort delivery,
-        DispatchDepartureService departure,DispatchCommandLedger commands,DispatchCommandHasher hashes) {
+        DispatchDepartureService departure,DispatchCommandLedger commands,DispatchCommandHasher hashes,
+        DispatchLoadingPhotoPort documents) {
         this.workflow=workflow;this.delivery=delivery;this.departure=departure;this.commands=commands;this.hashes=hashes;
+        this.documents=documents;
     }
 
-    /** 原键恢复先于阶段校验；任一步失败均回滚装载、子单、费用、发车与全部账本。 */
+    /** 原请求记录最终阶段；重放不重复装车、创建派送或发车。 */
     @Transactional(isolation=Isolation.READ_COMMITTED)
     public CommandResult complete(Actor actor,String number,DispatchCommands.LoadingComplete request) {
         workflow.requireLoadingPermission(actor);
         var context=workflow.lockForArrangement(actor,number);
         var identity=new CommandIdentity(Action.LOADING_COMPLETE,request.idempotencyKey(),request.recordVersion(),
             hashes.command(actor,Action.LOADING_COMPLETE,number,request.recordVersion(),request));
-        var replay=commands.replay(actor,number,identity);if(replay.isPresent())return replay.get();
-        // 先取得本车单据锁再申请真实来源锁，后续所有步骤保持同一个整车父锁。
-        delivery.departureFacts(context,true);
+        var original=workflow.replay(context,actor,identity);if(original.isPresent())return original.get();
         var loaded=workflow.loadingComplete(actor,number,new DispatchCommands.LoadingComplete(request.recordVersion(),
             stepKey(number,request.idempotencyKey(),"LOAD"),request.manifestHash(),request.measurements(),request.remark()));
-        context=workflow.preview(actor,number);
-        String arrangementKey=stepKey(number,request.idempotencyKey(),"ARRANGE");
+        var ready=DispatchLoadingDocumentService.complete(documents.read(context.dispatchId()).photos());
+        var finalState=ready?departAfterDocuments(actor,number,request.idempotencyKey()):loaded;
+        var result=new CommandResult(number,Action.LOADING_COMPLETE,request.idempotencyKey(),finalState.recordVersion(),
+            finalState.status(),finalState.stage(),finalState.occurredAt(),finalState.effect(),finalState.counts(),loaded.result(),false,false);
+        commands.append(context.dispatchId(),actor,identity,result);
+        return result;
+    }
+
+    /** 仅供装车资料齐全的保存事务调用；派送准备和发车失败回滚最后一张绑定。 */
+    @Transactional(propagation=Propagation.MANDATORY,isolation=Isolation.READ_COMMITTED)
+    public CommandResult departAfterDocuments(Actor actor,String number,String key) {
+        var context=workflow.lockForArrangement(actor,number);
+        if(context.stage()!=Stage.AFTER_LOADING || context.status()!=Status.ACTIVE)
+            throw new BizException(ResultCode.CONFLICT,"当前阶段不能按装车资料推进派送");
+        // 先取得本车单据锁再申请真实来源锁，后续所有步骤保持同一个整车父锁。
+        delivery.departureFacts(context,true);
+        String arrangementKey=stepKey(number,key,"ARRANGE");
         var fact=delivery.prepareForDeparture(context,actor,arrangementKey);
         var arrangementIdentity=new CommandIdentity(Action.ARRANGE_DELIVERY,arrangementKey,context.recordVersion(),
             hashes.source(List.of(number,actor.operatorId(),context.recordVersion(),fact.arrangementBusinessHash())));
         var arranged=workflow.recordArrangement(context,actor,arrangementIdentity,fact,false);
         var departed=departure.depart(actor,number,new DispatchCommands.Depart(arranged.recordVersion(),
-            stepKey(number,request.idempotencyKey(),"DEPART"),request.remark()));
-        if(departed.stage()!=Stage.DELIVERING || !(loaded.result() instanceof DispatchResults.Loaded))
+            stepKey(number,key,"DEPART"),"五张装车照片已齐全，自动进入派送中"));
+        if(departed.stage()!=Stage.DELIVERING)
             throw new BizException(ResultCode.CONFLICT,"装车发运结果未核平");
-        var result=new CommandResult(number,Action.LOADING_COMPLETE,request.idempotencyKey(),departed.recordVersion(),
-            departed.status(),departed.stage(),departed.occurredAt(),Effect.APPLIED,departed.counts(),loaded.result(),false,false);
-        commands.append(context.dispatchId(),actor,identity,result);return result;
+        return departed;
     }
 
     /** 固定长度内部键绑定原请求和步骤，不向客户端暴露中间命令作为恢复入口。 */

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchLoadingDocumentService.java

@@ -0,0 +1,85 @@
+package com.baiyue.lastleg.dispatch.service;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.lastleg.dispatch.port.DispatchContracts.Actor;
+import com.baiyue.lastleg.dispatch.port.DispatchContracts.Context;
+import com.baiyue.lastleg.dispatch.port.DispatchTypes.*;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort.*;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+import java.util.*;
+
+/** Admin/PDA按整车共用装车资料；通过车队公开端口保存照片，不读取其持久化。 */
+@Service
+public class DispatchLoadingDocumentService {
+    public static final List<Slot> SLOTS=List.of(Slot.values());
+    private final DispatchAggregateService workflow;
+    private final DispatchLoadingDepartureService departure;
+    private final DispatchLoadingPhotoPort photos;
+    /** 装车资料与履约原子编排留在排车域，车队只提供照片事实。 */
+    public DispatchLoadingDocumentService(DispatchAggregateService workflow,DispatchLoadingDepartureService departure,DispatchLoadingPhotoPort photos) {
+        this.workflow=workflow;this.departure=departure;this.photos=photos;
+    }
+    /** GET只读，PDA每次按可信主体重验冻结仓。 */
+    @Transactional(readOnly=true,isolation=Isolation.REPEATABLE_READ)
+    public Documents get(Actor actor,String number) {
+        require(actor,false);var context=context(actor,number,false);return documents(context,photos.read(context.dispatchId()),allowed(actor,true));
+    }
+    /** 上传先记原请求意图，不提前绑定或推进派送。 */
+    public Photo upload(Actor actor,String number,Slot slot,String key,MultipartFile file) {
+        require(actor,true);var context=context(actor,number,false);return photos.upload(context.dispatchId(),actor.operatorId(),slot,key,file);
+    }
+    /** 原操作者仍须有权限且满足本车绑定仓范围，不能跨账号恢复。 */
+    public Photo recover(Actor actor,String number,String key) {
+        require(actor,true);var context=context(actor,number,false);return photos.recover(context.dispatchId(),actor.operatorId(),key);
+    }
+    /** 锁顺序为车次、排车、附加行；第五张绑定与派送发车共同提交或回滚。 */
+    @Transactional(isolation=Isolation.READ_COMMITTED)
+    public Documents bind(Actor actor,String number,Slot slot,BindPhoto request) {
+        require(actor,true);var context=context(actor,number,true);
+        var replay=photos.replayBind(context.dispatchId(),actor.operatorId(),slot,request);if(replay!=null)return replay;
+        var state=photos.bind(context.dispatchId(),actor.operatorId(),slot,request);
+        if(context.stage()==Stage.AFTER_LOADING && complete(state.photos())) {
+            departure.departAfterDocuments(actor,number,request.idempotencyKey());context=workflow.preview(actor,number);
+        }
+        var result=documents(context,state,true);
+        photos.recordBind(context.dispatchId(),actor.operatorId(),slot,request,result);return result;
+    }
+    /** 当前引用由照片提供者再次核验，拒绝未绑定或其他车文件。 */
+    @Transactional(readOnly=true)
+    public Download content(Actor actor,String number,Slot slot,long fileId) {
+        require(actor,false);var context=context(actor,number,false);return photos.content(context.dispatchId(),slot,fileId);
+    }
+    /** 装车中可同步上传；后续阶段仍须有真实装载证据，仓隔离沿用主流程。 */
+    private Context context(Actor actor,String number,boolean lock) {
+        var value=lock?workflow.lockForArrangement(actor,number):workflow.preview(actor,number);
+        if(value.status()!=Status.ACTIVE || !Set.of(Stage.LOADING,Stage.AFTER_LOADING,Stage.DELIVERING,Stage.DELIVERED).contains(value.stage())
+            || value.stage()!=Stage.LOADING && (value.loadingCompletedAt()==null || value.loadingCompletionHash()==null))
+            throw new BizException(ResultCode.CONFLICT,"进入装车中后才能管理装车资料");
+        return value;
+    }
+    /** 对外同时返回资料版本与当前排车阶段，二者不互相替代。 */
+    private Documents documents(Context context,State state,boolean editable) {
+        return new Documents(context.dispatchNo(),state.recordVersion(),Long.toString(context.recordVersion()),context.stage().name(),editable,complete(state.photos()),state.photos());
+    }
+    /** 按五个固定框核齐，不能用总数或重复槽位代替。 */
+    static boolean complete(List<Photo> photos) {
+        return SLOTS.stream().allMatch(slot->photos.stream().anyMatch(p->p.slot()==slot && p.fileId()!=null && !p.fileId().isBlank()));
+    }
+    /** 平台list与edit分离，PDA使用既有作业角色和绑定仓。 */
+    private void require(Actor actor,boolean write) {
+        if(actor==null || actor.operatorId()==null || !allowed(actor,write))throw new BizException(ResultCode.FORBIDDEN,"无装车资料操作权限");
+    }
+    /** 权限取当前会话，不为PDA补造平台权限。 */
+    private boolean allowed(Actor actor,boolean write) {
+        var auth=SecurityContextHolder.getContext().getAuthentication();if(auth==null || actor==null)return false;
+        var authorities=auth.getAuthorities().stream().map(a->a.getAuthority()).toList();
+        return actor.mode()==ActorMode.PDA?actor.boundWarehouseId()!=null && authorities.contains("lastleg:pda:operate")
+            && authorities.contains("ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR")
+            :authorities.contains("platform:overseas-warehouse:dispatch:"+(write?"edit":"list"));
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchPdaQueryService.java

@@ -87,7 +87,7 @@ public class DispatchPdaQueryService {
             if(!sourceValid)actions.put(Action.PICK,new Gate(false,"SOURCE_COMPOSITION_CHANGED","换标来源实际位置或累计剩余额度已变化，请回平台核对"));
             if(!complete)actions.put(Action.LOADING_COMPLETE,new Gate(false,"PICKING_INCOMPLETE","逐项真实拣货来源尚未核平"));
             else actions.put(Action.PICK,new Gate(false,"PICKING_RECONCILED","本车全部来源已核平，请显式确认装车"));
-            var counts=new Counts(n(root.getItemCount()),n(root.getPalletCount()),n(root.getPackageCount()),n(root.getPickedPackageCount()),n(root.getShippedPackageCount()));
+            var counts=new Counts(n(root.getItemCount()),n(root.getPalletCount()),detail.stream().mapToLong(DispatchViews.PdaItem::scheduledPackages).sum(),n(root.getPickedPackageCount()),n(root.getShippedPackageCount()));
             // 整车作业直接以排车业务号识别；真实客户子taskId只在服务端审计保存。
             result.add(new DispatchViews.PdaTask(root.getDispatchNo(),root.getDispatchNo(),root.getOverseasWarehouseId(),Status.valueOf(root.getStatus()),Stage.valueOf(root.getStage()),root.getRecordVersion(),workflow.reviews(root),workflow.resources(root),counts,complete,List.copyOf(detail),Collections.unmodifiableMap(actions)));
         }
@@ -95,36 +95,11 @@ public class DispatchPdaQueryService {
     }
     /** 预排首次扫码前只解析原计划实收仓位，不在GET补写实托；真正绑定仍由pick锁内重验。 */
     private List<DispatchViews.Position> receivedPlanPositions(Actor actor,DispatchItem item,List<DispatchItem> items) {
-        if(!Objects.equals(actor.boundWarehouseId(),item.getOverseasWarehouseId()))return List.of();
-        var rows=sources.selectedPlan(item.getCustomerId(),item.getPlanPalletId());
-        if(rows.size()!=1)return List.of();
-        var actual=rows.get(0);
-        if(!"RECEIVED".equals(actual.sourceStage()) || actual.warehousePalletId()==null
-            || !Objects.equals(actual.planPalletId(),item.getPlanPalletId())
-            || !Objects.equals(actual.customerId(),item.getCustomerId())
-            || !Objects.equals(actual.overseasWarehouseId(),item.getOverseasWarehouseId())
-            || !Objects.equals(actual.packageCount(),item.getPackageCount())
-            || !Objects.equals(actual.destinationType(),item.getDestinationType())
-            || !Objects.equals(actual.fbaWarehouseCode(),item.getFbaWarehouseCode())
-            || !Objects.equals(actual.deliveryAddress(),item.getDeliveryAddress()))return List.of();
-        var originalOrders=sources.sourceOrders(item.getCustomerId(),null,item.getPlanPalletId());
-        if(originalOrders.isEmpty() || !new HashSet<>(originalOrders).containsAll(
-            sources.sourceOrders(item.getCustomerId(),actual.warehousePalletId(),item.getPlanPalletId())))return List.of();
-        // 同托跨客户、换标及整申请来源必须全部已在原车；不能把新合托货物暴露为原计划可拣库存。
-        var group=sourceRules.selectionGroup(actor.boundWarehouseId(),new DispatchCommands.CargoSelection(
-            SourceType.INBOUND_PLAN,item.getPlanPalletId(),null,null,actual.warehousePalletId(),null));
-        if(!group.complete() || group.sources().stream().noneMatch(s->Objects.equals(s.sourceKey(),item.getSourceKey())))return List.of();
-        for(var member:group.sources()) {
-            var selected=items.stream().filter(i->Objects.equals(i.getSourceKey(),member.sourceKey())).findFirst().orElse(null);
-            if(selected==null || !Objects.equals(selected.getCustomerId(),member.customerId())
-                || n(selected.getPackageCount())!=member.packages())return List.of();
-        }
-        var stock=sources.stock(item.getCustomerId(),actual.warehousePalletId(),false);
-        if(stock.stream().anyMatch(p->!Objects.equals(p.warehouseId(),actor.boundWarehouseId())
-            || !Objects.equals(p.palletId(),actual.warehousePalletId()))
-            || stock.stream().mapToLong(p->p.availablePackages()).sum()!=n(item.getPackageCount()))return List.of();
-        return stock.stream().filter(p->p.availablePackages()>0)
-            .map(p->new DispatchViews.Position(p.id(),p.balanceId(),p.availablePackages(),p.allocatedPackages(),p.pickedPackages())).toList();
+        var received=DispatchReceivedPlan.resolve(actor.boundWarehouseId(),item,items,sources,sourceRules);
+        if(received.isEmpty())return List.of();
+        // 只修改本次投影对象，不在GET更新排车、版本或库存。
+        item.setPackageCount(received.get().source().packageCount());
+        return received.get().positions();
     }
     /** 仓和操作者均来自受信身份，不接收请求自报。 */
     private static void require(Actor actor){if(actor==null || actor.mode()!=ActorMode.PDA || actor.operatorId()==null || actor.boundWarehouseId()==null)throw new BizException(ResultCode.FORBIDDEN,"仅绑定仓作业人员可读取PDA作业");}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchPickingService.java

@@ -27,6 +27,7 @@ public class DispatchPickingService {
     @jakarta.annotation.Resource private DispatchPhysicalClaimService physicalClaims;
     @jakarta.annotation.Resource private DispatchItemSourceService relabelSources;
     @jakarta.annotation.Resource private DispatchService sourceRules;
+    @jakarta.annotation.Resource private com.baiyue.lastleg.fleet.trip.FleetTripExecutionService fleet;
     private final DispatchAggregateService workflow;private final DispatchAggregateRepository repository;private final DispatchSourceRepository sources;
     private final DispatchPickingRepository picking;private final DispatchPickOrderAttributionService attribution;
     private final InventoryCommandService inventory;private final ReturnRelabelDispatchStock returns;
@@ -101,33 +102,44 @@ public class DispatchPickingService {
             new Counts(row.getItemCount(),row.getPalletCount(),row.getPackageCount(),row.getPickedPackageCount(),row.getShippedPackageCount()),new DispatchResults.Picked(itemId,request.positionId(),returnCartonId,request.packages(),before+request.packages(),complete),false,false);
         commands.append(row.getId(),actor,identity,result);return result;
     }
-    /** 原计划自然收货只补齐同一来源实托，数量/客户/目的地变化必须回到平台核对。 */
+    /** 首拣将本车已实收原计划按真实整托数量绑定，保持原审核身份并与扣货同事务回滚。 */
     private void materialize(com.baiyue.lastleg.dispatch.entity.DispatchAggregate row,DispatchItem item,Actor actor,List<DispatchItem> items) {
         long dispatch=row.getId();
         if(item.getWarehousePalletId()!=null) {
             relabelSources.validateFrozen(row,items,sourceRules.lockExecutionSources(row.getOverseasWarehouseId(),items));return;
         }
-        if(item.getPlanPalletId()==null)throw conflict("本来源尚未关联真实实托");
-        var orders=sources.sourceOrders(item.getCustomerId(),null,item.getPlanPalletId());
-        if(orders.isEmpty())throw conflict("原计划缺少真实订单组成");
-        var rows=sources.selectedPlan(item.getCustomerId(),item.getPlanPalletId());
-        if(rows.size()!=1)throw conflict("请先完成本来源实际入仓收货");var actual=rows.get(0);
-        if(actual.warehousePalletId()==null || !Objects.equals(actual.customerId(),item.getCustomerId()) || !Objects.equals(actual.overseasWarehouseId(),item.getOverseasWarehouseId())
-            || !Objects.equals(actual.packageCount(),item.getPackageCount()) || !Objects.equals(actual.destinationType(),item.getDestinationType())
-            || !Objects.equals(actual.fbaWarehouseCode(),item.getFbaWarehouseCode()) || !Objects.equals(actual.deliveryAddress(),item.getDeliveryAddress()))throw conflict("原计划实收数量、仓或目的地已变化，请先回平台核对");
-        if(!new HashSet<>(orders).containsAll(sources.sourceOrders(item.getCustomerId(),actual.warehousePalletId(),item.getPlanPalletId())))throw conflict("实托新增了未审核的来源订单");
-        item.setWarehousePalletId(actual.warehousePalletId());
+        var received=new LinkedHashMap<DispatchItem,DispatchReceivedPlan.Fact>();
+        for(var candidate:items)DispatchReceivedPlan.resolve(actor.boundWarehouseId(),candidate,items,sources,sourceRules)
+            .ifPresent(fact->received.put(candidate,fact));
+        if(!received.containsKey(item))throw conflict("该托盘尚未完成可拣实收，或原来源、目的地、库存占用已变化，请刷新核对");
+        // 同车同实托的多个原计划一次绑定，避免首拣把其他已审核成员误判为新增货物。
+        for(var entry:received.entrySet()) {
+            entry.getKey().setWarehousePalletId(entry.getValue().source().warehousePalletId());
+            entry.getKey().setPackageCount(entry.getValue().source().packageCount());
+        }
         relabelSources.validateFrozen(row,items,sourceRules.lockExecutionSources(row.getOverseasWarehouseId(),items));
-        if(sources.lockPlan(item.getCustomerId(),item.getPlanPalletId())==null)throw conflict("原计划来源已变化");
-        var fresh=sources.selectedPlan(item.getCustomerId(),item.getPlanPalletId());
-        if(fresh.size()!=1 || !Objects.equals(actual.warehousePalletId(),fresh.get(0).warehousePalletId()) || !Objects.equals(actual.packageCount(),fresh.get(0).packageCount()))throw conflict("原计划实托组成已变化，请回平台核对");
-        var at=LocalDateTime.ofInstant(Instant.now(),ZoneOffset.UTC);sources.stock(item.getCustomerId(),actual.warehousePalletId(),true);
-        var pallets=new ArrayList<Long>();repository.cargo(dispatch).stream().map(DispatchItem::getWarehousePalletId).filter(Objects::nonNull).forEach(pallets::add);pallets.add(actual.warehousePalletId());
-        var physical=physicalClaims.reserve(new DispatchPhysicalClaimService.Owner(row.getOverseasWarehouseId(),dispatch,null,null,actor.operatorId(),null),pallets,at).get(actual.warehousePalletId());
-        try{if(sources.materialize(dispatch,item.getCustomerId(),item.getPlanPalletId(),actual.warehousePalletId(),physical,at)!=1)throw conflict("原计划来源占用已变化");}
-        catch(DuplicateKeyException occupied){throw conflict("实托已经被其他来源安排占用");}
-        item.setPalletNo(actual.palletNo());item.setSourceStage("RECEIVED");
-        if(picking.materialize(item)!=1)throw conflict("本来源实际实托未保存");
+        for(var candidate:received.keySet().stream().sorted(Comparator.comparing(DispatchItem::getPlanPalletId)).toList()) {
+            if(sources.lockPlan(candidate.getCustomerId(),candidate.getPlanPalletId())==null)throw conflict("原计划来源已变化");
+            var fresh=sources.selectedPlan(candidate.getCustomerId(),candidate.getPlanPalletId());
+            if(fresh.size()!=1 || !DispatchReceivedPlan.sameIdentity(candidate,fresh.get(0))
+                || !Objects.equals(candidate.getWarehousePalletId(),fresh.get(0).warehousePalletId())
+                || !Objects.equals(candidate.getPackageCount(),fresh.get(0).packageCount()))throw conflict("实收托盘已变化，请刷新后重新扫码");
+        }
+        var at=LocalDateTime.ofInstant(Instant.now(),ZoneOffset.UTC);
+        var pallets=items.stream().map(DispatchItem::getWarehousePalletId).filter(Objects::nonNull).distinct().sorted().toList();
+        var physical=physicalClaims.reserve(new DispatchPhysicalClaimService.Owner(row.getOverseasWarehouseId(),dispatch,null,null,actor.operatorId(),null),pallets,at);
+        for(var entry:received.entrySet()) {
+            var candidate=entry.getKey();var actual=entry.getValue().source();
+            try{if(sources.materialize(dispatch,candidate.getCustomerId(),candidate.getPlanPalletId(),actual.warehousePalletId(),physical.get(actual.warehousePalletId()),at)!=1)throw conflict("原计划来源占用已变化");}
+            catch(DuplicateKeyException occupied){throw conflict("实托已经被其他排车占用");}
+            candidate.setPalletNo(actual.palletNo());candidate.setSourceStage("RECEIVED");
+            if(picking.materialize(candidate)!=1)throw conflict("本来源实际实托未保存");
+        }
+        row.setPackageCount(Math.toIntExact(items.stream().mapToLong(DispatchItem::getPackageCount).sum()));
+        var stops=items.stream().map(i->new com.baiyue.lastleg.fleet.trip.FleetExecutionModels.DispatchStop(
+            i.getDestinationWarehouseName(),i.getDeliveryAddress(),workflow.destination(i).key()))
+            .collect(java.util.stream.Collectors.toMap(com.baiyue.lastleg.fleet.trip.FleetExecutionModels.DispatchStop::destinationKey,s->s,(a,b)->a,TreeMap::new)).values().stream().toList();
+        fleet.updateDispatchCargo(row.getDispatchNo(),row.getPackageCount(),stops);
     }
     /** 库存幂等键分别标识一次实际动作，业务单号始终使用本车号。 */
     private static InventoryCommandRequests.Move move(DispatchCommands.Pick request,String dispatch,String reference,String key){return new InventoryCommandRequests.Move(request.positionId(),request.packages(),reference,dispatch,null,key,request.remark());}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchReceivedPlan.java

@@ -0,0 +1,56 @@
+package com.baiyue.lastleg.dispatch.service;
+
+import com.baiyue.lastleg.dispatch.entity.DispatchItem;
+import com.baiyue.lastleg.dispatch.model.DispatchPalletCandidate;
+import com.baiyue.lastleg.dispatch.port.*;
+import com.baiyue.lastleg.dispatch.repository.DispatchSourceRepository;
+import java.util.*;
+import static com.baiyue.lastleg.dispatch.port.DispatchTypes.SourceType;
+
+/** 预排来源只冻结货物身份；自然实收的逐托箱数由真实库存提供，查询和首拣共用此规则。 */
+final class DispatchReceivedPlan {
+    record Fact(DispatchPalletCandidate source, List<DispatchViews.Position> positions) { }
+
+    /** 仅解析原车完整来源，禁止把新客户、新订单或冻结货物混入实收数量。 */
+    static Optional<Fact> resolve(String warehouse, DispatchItem item, List<DispatchItem> items,
+                                  DispatchSourceRepository sources, DispatchService rules) {
+        if(item.getWarehousePalletId()!=null || item.getPlanPalletId()==null
+            || !Objects.equals(warehouse,item.getOverseasWarehouseId()))return Optional.empty();
+        if(!sources.receivedPlanCompleted(item.getCustomerId(),item.getPlanPalletId()))return Optional.empty();
+        var rows=sources.selectedPlan(item.getCustomerId(),item.getPlanPalletId());
+        if(rows.size()!=1)return Optional.empty();
+        var actual=rows.get(0);
+        if(!sameIdentity(item,actual) || actual.packageCount()==null || actual.packageCount()<=0)return Optional.empty();
+        var original=sources.sourceOrders(item.getCustomerId(),null,item.getPlanPalletId());
+        if(original.isEmpty() || !new HashSet<>(original).containsAll(
+            sources.sourceOrders(item.getCustomerId(),actual.warehousePalletId(),item.getPlanPalletId())))return Optional.empty();
+        var group=rules.selectionGroup(warehouse,new DispatchCommands.CargoSelection(
+            SourceType.INBOUND_PLAN,item.getPlanPalletId(),null,null,actual.warehousePalletId(),null));
+        if(!group.complete() || group.sources().stream().noneMatch(s->Objects.equals(s.sourceKey(),item.getSourceKey())))return Optional.empty();
+        for(var member:group.sources()) {
+            var selected=items.stream().filter(i->Objects.equals(i.getSourceKey(),member.sourceKey())).findFirst().orElse(null);
+            if(selected==null || !Objects.equals(selected.getCustomerId(),member.customerId()))return Optional.empty();
+            // 原计划的估算箱数不限制实收；已经绑定或换标的冻结贡献仍严格核对。
+            if((selected.getWarehousePalletId()!=null || selected.getPlanPalletId()==null)
+                && (selected.getPackageCount()==null || selected.getPackageCount().longValue()!=member.packages()))return Optional.empty();
+        }
+        var stock=sources.stock(item.getCustomerId(),actual.warehousePalletId(),false);
+        if(stock.stream().anyMatch(p->!Objects.equals(p.warehouseId(),warehouse)
+            || !Objects.equals(p.palletId(),actual.warehousePalletId()) || p.holdPackages()!=0
+            || p.allocatedPackages()!=0 || p.pickedPackages()!=0)
+            || stock.stream().mapToLong(p->p.availablePackages()).sum()!=actual.packageCount())return Optional.empty();
+        return Optional.of(new Fact(actual,stock.stream().filter(p->p.availablePackages()>0)
+            .map(p->new DispatchViews.Position(p.id(),p.balanceId(),p.availablePackages(),p.allocatedPackages(),p.pickedPackages())).toList()));
+    }
+
+    /** 箱数允许随自然实收变化，客户、原计划、起运仓和目的地必须保持原身份。 */
+    static boolean sameIdentity(DispatchItem item,DispatchPalletCandidate actual) {
+        return "RECEIVED".equals(actual.sourceStage()) && actual.warehousePalletId()!=null
+            && Objects.equals(actual.planPalletId(),item.getPlanPalletId())
+            && Objects.equals(actual.customerId(),item.getCustomerId())
+            && Objects.equals(actual.overseasWarehouseId(),item.getOverseasWarehouseId())
+            && Objects.equals(actual.destinationType(),item.getDestinationType())
+            && Objects.equals(actual.fbaWarehouseCode(),item.getFbaWarehouseCode())
+            && Objects.equals(actual.deliveryAddress(),item.getDeliveryAddress());
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dto/ContainerArrivalTimeView.java

@@ -7,5 +7,6 @@ public record ContainerArrivalTimeView(
     String sourceContainerBookingId,
     LocalDateTime estimatedWarehouseArrivalAt,
     LocalDateTime actualWarehouseArrivalAt,
-    int version
+    int version,
+    long planCount
 ) { }

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/outsourcedbusiness/service/OutsourcedBusinessService.java

@@ -37,7 +37,7 @@ public class OutsourcedBusinessService {
     public HistoryPage history(OwnedBusinessModels.Actor actor,String number,Integer page,Integer size) {
         var result=queries.history(actor,number,page,size,SCOPE);
         return new HistoryPage(result.records().stream().map(h->new History(h.eventSource(),h.recordVersion(),h.dispatchRecordVersion(),h.action(),h.operatorName(),
-            h.occurredAt(),h.reason(),h.operations()==null?null:operations(h.operations()),h.photos().stream().map(this::photo).toList())).toList(),result.page(),result.size(),result.total());
+            h.occurredAt(),h.reason(),h.operations()==null?null:operations(h.operations()),h.photos().stream().filter(p->"LOADING".equals(p.category())).map(this::photo).toList())).toList(),result.page(),result.size(),result.total());
     }
     /** 外配只生成金额和到达的规范内部请求，不接收归属或隐藏油耗写入。 */
     public Detail save(OwnedBusinessModels.Actor actor,String number,SaveOperations request) {
@@ -71,11 +71,11 @@ public class OutsourcedBusinessService {
     }
     /** 回执公开形状不带内部里程、油耗或油耗照片摘要。 */
     private Detail detail(OwnedBusinessModels.Detail detail) {
-        return new Detail(row(detail.row(),projection.carrierName(detail)),detail.dispatch(),detail.cargo(),detail.photos().stream().map(this::photo).toList());
+        return new Detail(row(detail.row(),projection.carrierName(detail)),detail.dispatch(),detail.cargo(),detail.photos().stream().filter(p->"LOADING".equals(p.category())).map(this::photo).toList());
     }
     /** 临时车辆合法保留空vehicleId；承运商缺失保留null供页面显示破折号。 */
     private Row row(OwnedBusinessModels.Row r,String carrierName) {
-        if(!java.util.Set.of("OWNED","DISPATCHED").contains(r.vehicle().ownership()) || r.photoSummary().fuelCount()!=0)throw conflict("外配运营快照的车辆归属或照片不合法");
+        if(!java.util.Set.of("OWNED","DISPATCHED").contains(r.vehicle().ownership()))throw conflict("外配运营快照的车辆归属或照片不合法");
         return new Row(r.dispatchNo(),r.stage(),r.plannedDepartureAt(),r.loadingCompletedAt(),r.departedAt(),r.deliveryCompletedAt(),r.origin(),
             new Vehicle(r.vehicle().vehicleId(),r.vehicle().plate(),r.vehicle().ownership(),carrierName==null || carrierName.isBlank()?null:carrierName),r.driver(),r.destinations(),
             r.actualPalletCount(),operations(r.operations()),r.unitPrice(),r.recordVersion(),r.dispatchRecordVersion(),new PhotoSummary(r.photoSummary().loadingCount()),r.actions(),r.sourceIssues());
@@ -85,7 +85,7 @@ public class OutsourcedBusinessService {
         if(ops.actualDistanceMiles()!=null || ops.fuelConsumptionLitresPer100Km()!=null)throw conflict("外配业务不能包含里程或油耗登记");
         return new Operations(ops.money(),ops.arrivals());
     }
-    /** 外配照片枚举只有五框，异常油耗历史不能借复用向外输出。 */
+    /** 外配照片枚举只有五框，排车油耗图片保留在共用记录中但不在外配入口输出。 */
     private Photo photo(OwnedBusinessModels.Photo p) {
         SCOPE.requireSlot(p.slot());return new Photo(PhotoSlot.valueOf(p.slot().name()),p.category(),p.fileId(),p.fileName(),p.contentType(),p.sizeBytes(),p.uploadedAt(),p.savedAt());
     }

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/controller/DispatchVehicleDocumentController.java

@@ -0,0 +1,76 @@
+package com.baiyue.lastleg.fleet.ownedbusiness.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessModels.*;
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessScope;
+import com.baiyue.lastleg.fleet.ownedbusiness.service.*;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.*;
+import org.springframework.http.*;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+import java.util.List;
+
+/** 排车资料入口复用车队原照片记录；签收及BOL仍由派送单管理。 */
+@RestController
+@Validated
+@RequestMapping("/api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents")
+public class DispatchVehicleDocumentController {
+    private static final OwnedBusinessScope SCOPE=OwnedBusinessScope.DISPATCH;
+    private final OwnedBusinessQueryService queries;
+    private final OwnedBusinessPhotoService photos;
+    private final OwnedBusinessSupport access;
+    /** 沿已有服务复用来源校验、文件归属、版本和命令账本。 */
+    public DispatchVehicleDocumentController(OwnedBusinessQueryService queries,OwnedBusinessPhotoService photos,OwnedBusinessSupport access) {
+        this.queries=queries;this.photos=photos;this.access=access;
+    }
+    public record Documents(String dispatchNo,String recordVersion,boolean editable,List<Photo> photos) {}
+    /** 只输出油耗资料，避免把车队签收照片当作派送签收文件。 */
+    private Documents documents(Detail value) {
+        return new Documents(value.row().dispatchNo(),value.row().recordVersion(),value.row().actions().upload().allowed(),
+            value.photos().stream().filter(p->"FUEL".equals(p.category())).toList());
+    }
+    /** 排车列表权限包含车辆资料只读，不扩大派送单客户访问权限。 */
+    @GetMapping
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")
+    public ApiResponse<Documents> get(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo) {
+        return ApiResponse.success(documents(queries.detail(access.actor(user,SCOPE),dispatchNo,SCOPE)));
+    }
+    /** 上传和引用保存分开，沿原请求键防止重传。 */
+    @PostMapping(value="/{slot}/uploads",consumes=MediaType.MULTIPART_FORM_DATA_VALUE)
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Photo> upload(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable PhotoSlot slot,
+        @RequestParam @Size(min=8,max=128) String idempotencyKey,@RequestPart("file") MultipartFile file) {
+        return ApiResponse.success(photos.upload(access.actor(user,SCOPE),dispatchNo,slot,idempotencyKey,file,SCOPE));
+    }
+    /** 只更新既有附加资料版本，不修改排车阶段或签收状态。 */
+    @PutMapping("/{slot}")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Documents> bind(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable PhotoSlot slot,@Valid @RequestBody BindPhoto request) {
+        return ApiResponse.success(documents(photos.bind(access.actor(user,SCOPE),dispatchNo,slot,request,SCOPE)));
+    }
+    /** 预览只读取本车当前已经绑定的照片。 */
+    @GetMapping("/{slot}/files/{fileId}/content")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")
+    public ResponseEntity<byte[]> content(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable PhotoSlot slot,@PathVariable @Positive long fileId) {
+        var value=photos.content(access.actor(user,SCOPE),dispatchNo,slot,fileId,null,SCOPE);
+        return ResponseEntity.ok().cacheControl(CacheControl.noStore()).contentType(MediaType.parseMediaType(value.photo().contentType()))
+            .header("X-Content-Type-Options","nosniff").body(value.content());
+    }
+    /** 恢复仅返回油耗上传结果，不通过排车入口暴露其他运营命令。 */
+    @GetMapping("/uploads/{idempotencyKey}")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Photo> recover(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable String idempotencyKey) {
+        var actor=access.actor(user,SCOPE);
+        access.require(actor,SCOPE.uploadPermission());
+        var command=photos.command(actor,dispatchNo,idempotencyKey,SCOPE);
+        if(!"UPLOAD_PHOTO".equals(command.action()) || !"SUCCEEDED".equals(command.state()) || command.result()==null)
+            throw OwnedBusinessSupport.conflict("原上传结果尚未确认，请保留原请求稍后核对");
+        var value=access.read(access.write(command.result()),Photo.class);SCOPE.requireSlot(value.slot());
+        return ApiResponse.success(value);
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/model/OwnedBusinessScope.java

@@ -7,7 +7,8 @@ import com.baiyue.common.core.api.ResultCode;
 /** 仅服务端固定入口选择的作用域；不得成为浏览器请求字段或权限别名。 */
 public enum OwnedBusinessScope {
     OWNED(false,"platform:fleet:owned-business:"),
-    OUTSOURCED(true,"platform:fleet:outsourced-business:");
+    OUTSOURCED(true,"platform:fleet:outsourced-business:"),
+    DISPATCH(false,"platform:overseas-warehouse:dispatch:");
     private final boolean pooledCargo;
     private final String prefix;
     /** 业务入口按是否实际接入拼车货物分类，与车辆归属独立。 */
@@ -19,9 +20,9 @@ public enum OwnedBusinessScope {
     /** 运营写权限独立，外配权限不映射成自有权限。 */
     public String editPermission(){return prefix+"edit";}
     /** 照片写权限独立，不扩大到原排车。 */
-    public String uploadPermission(){return prefix+"upload";}
+    public String uploadPermission(){return prefix+(this==DISPATCH?"edit":"upload");}
     /** 外配只支持装车五框，服务调用同样不能绕过。 */
-    public void requireSlot(PhotoSlot slot){if(slot==null || this==OUTSOURCED && !"LOADING".equals(slot.category()))throw new BizException(ResultCode.BAD_REQUEST,"当前业务不支持该照片框");}
+    public void requireSlot(PhotoSlot slot){if(slot==null || this==OUTSOURCED && !"LOADING".equals(slot.category()) || this==DISPATCH && !"FUEL".equals(slot.category()))throw new BizException(ResultCode.BAD_REQUEST,"当前业务不支持该照片框");}
     /** 不存在只显示当前业务归属，不泄露内部身份。 */
-    public BizException missing(){return new BizException(ResultCode.NOT_FOUND,"排车单不存在或不属于当前"+(this==OWNED?"自有业务":"外配任务"));}
+    public BizException missing(){return new BizException(ResultCode.NOT_FOUND,this==DISPATCH?"排车单不存在":"排车单不存在或不属于当前"+(this==OWNED?"自有业务":"外配任务"));}
 }

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/port/DispatchLoadingPhotoPort.java

@@ -0,0 +1,29 @@
+package com.baiyue.lastleg.fleet.ownedbusiness.port;
+
+import jakarta.validation.constraints.*;
+import java.util.List;
+import org.springframework.web.multipart.MultipartFile;
+
+/** 整车装车资料公开端口；排车只组合资料事实，不读取车队持久化实现。 */
+public interface DispatchLoadingPhotoPort {
+    enum Slot { LOADING_SCENE, LOADING_LIST, PRE_DEPARTURE_CHECK, DRIVER_LICENSE, RECEIPT }
+    record Photo(Slot slot,String category,String fileId,String fileName,String contentType,String sizeBytes,String uploadedAt,String savedAt) {}
+    record BindPhoto(@NotBlank String recordVersion,@NotBlank @Size(min=8,max=128) String idempotencyKey,@NotBlank String fileId) {}
+    record State(String recordVersion,List<Photo> photos) {}
+    record Documents(String dispatchNo,String recordVersion,String dispatchRecordVersion,String stage,boolean editable,boolean complete,List<Photo> photos) {}
+    record Download(Photo photo,byte[] content) {}
+    /** 只读取原整车附加资料版本与五框，不初始化记录。 */
+    State read(long dispatchId);
+    /** 上传保存原请求意图；不提前计入已保存照片。 */
+    Photo upload(long dispatchId,String operator,Slot slot,String key,MultipartFile file);
+    /** 仅原操作者可恢复原上传结果。 */
+    Photo recover(long dispatchId,String operator,String key);
+    /** 先校验原槽位、完整载荷与操作者；无原成功命令时返回null。 */
+    Documents replayBind(long dispatchId,String operator,Slot slot,BindPhoto request);
+    /** 调用者已持排车父锁；保存照片、资料版本及历史但不单独提交事务。 */
+    State bind(long dispatchId,String operator,Slot slot,BindPhoto request);
+    /** 与绑定及自动发车共同提交完整原结果。 */
+    void recordBind(long dispatchId,String operator,Slot slot,BindPhoto request,Documents result);
+    /** 文件只可从本车当前已绑定槽位下载。 */
+    Download content(long dispatchId,Slot slot,long fileId);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/service/DispatchLoadingPhotoAdapter.java

@@ -0,0 +1,124 @@
+package com.baiyue.lastleg.fleet.ownedbusiness.service;
+
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.lastleg.fleet.ownedbusiness.gateway.*;
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessModels;
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessModels.PhotoSlot;
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessRows;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort;
+import com.baiyue.lastleg.fleet.ownedbusiness.repository.OwnedBusinessRepository;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+import java.io.IOException;
+import java.time.Instant;
+import java.util.*;
+import static com.baiyue.lastleg.fleet.ownedbusiness.service.OwnedBusinessSupport.*;
+
+/** 在原照片表和命令账本实现装车资料端口，不反向调用排车履约服务。 */
+@Service
+public class DispatchLoadingPhotoAdapter implements DispatchLoadingPhotoPort {
+    private final OwnedBusinessRepository repository;
+    private final OwnedBusinessCommandService commands;
+    private final OwnedBusinessProjection projection;
+    private final OwnedBusinessSupport codec;
+    private final OwnedBusinessFileGateway files;
+    /** 复用现有照片、版本、历史及文件归属校验。 */
+    public DispatchLoadingPhotoAdapter(OwnedBusinessRepository repository,OwnedBusinessCommandService commands,
+        OwnedBusinessProjection projection,OwnedBusinessSupport codec,OwnedBusinessFileGateway files) {
+        this.repository=repository;this.commands=commands;this.projection=projection;this.codec=codec;this.files=files;
+    }
+    public record Binding(Slot slot,BindPhoto request) {}
+    /** GET只读；首次保存前资料版本为0。 */
+    @Override public State read(long id) {
+        var row=repository.record(id);
+        return new State(row==null?"0":row.getRecordVersion().toString(),projection.photos(row).stream()
+            .filter(p->"LOADING".equals(p.category())).map(this::publicPhoto).toList());
+    }
+    /** 先落稳定上传意图，再请求File；未知结果不允许换键重传。 */
+    @Override public Photo upload(long id,String operator,Slot slot,String key,MultipartFile multipart) {
+        codec.key(key);var originalSlot=slot(slot);
+        if(multipart==null || multipart.isEmpty() || multipart.getSize()>HttpOwnedBusinessFileGateway.MAX_SIZE)throw bad("照片须为非空JPG/PNG，最大10MiB");
+        byte[] bytes;try{bytes=multipart.getBytes();}catch(IOException failure){throw bad("无法读取待上传照片");}
+        var payload=new OwnedBusinessFileGateway.Upload(multipart.getOriginalFilename(),multipart.getContentType(),bytes);
+        HttpOwnedBusinessFileGateway.validate(payload);
+        var identity=new OwnedBusinessPhotoService.UploadIdentity(originalSlot,payload.fileName(),payload.contentType(),bytes.length,codec.digest(bytes));
+        var reservation=commands.reserveUpload(id,operator(operator),key,identity);
+        if(!reservation.created())return uploaded(reservation.command());
+        try {
+            var result=photo(originalSlot,files.upload(id,originalSlot,operator,payload));
+            commands.finishUpload(reservation.command(),"SUCCEEDED",result,null);return publicPhoto(result);
+        } catch(RuntimeException failure) {
+            try{commands.finishUpload(reservation.command(),"UNKNOWN_RESULT",null,"DISPATCH_LOADING_UPLOAD_UNKNOWN");}
+            catch(RuntimeException recording){failure.addSuppressed(recording);}
+            throw conflict("照片上传结果未知，请保留原请求键核对");
+        }
+    }
+    /** 上传结果仅限本车原操作者及装车槽位。 */
+    @Override public Photo recover(long id,String operator,String key) {
+        codec.key(key);var command=commands.existing(id,key,operator(operator));
+        if(command==null)throw new BizException(ResultCode.NOT_FOUND,"未找到本车原上传请求");return uploaded(command);
+    }
+    /** 完整原结果先于当前资料版本比较，防止重复推进。 */
+    @Override public Documents replayBind(long id,String operator,Slot slot,BindPhoto request) {
+        validate(slot,request);var old=commands.existing(id,request.idempotencyKey(),operator(operator));
+        if(old==null)return null;
+        commands.same(old,"BIND_LOADING_DOCUMENT",codec.version(request.recordVersion()),new Binding(slot,request));
+        if(!"SUCCEEDED".equals(old.getStatus()))throw conflict("原资料保存结果尚未确认");return codec.read(old.getResultJson(),Documents.class);
+    }
+    /** 父排车锁由调用者持有；附加版本竞争与最后一张发车失败沿外层事务回滚。 */
+    @Override @Transactional(propagation=Propagation.MANDATORY,isolation=Isolation.READ_COMMITTED)
+    public State bind(long id,String operator,Slot slot,BindPhoto request) {
+        validate(slot,request);long version=codec.version(request.recordVersion());var originalSlot=slot(slot);
+        var verified=photo(originalSlot,files.metadata(id,originalSlot,codec.version(request.fileId())));
+        var seed=new OwnedBusinessRows.Record();seed.setId(IdWorker.getId());seed.setDispatchId(id);
+        seed.setCreatedBy(operator);seed.setUpdatedBy(operator);seed.setCreatedAt(codec.utc(Instant.now()));seed.setUpdatedAt(seed.getCreatedAt());
+        var row=repository.lock(seed);
+        if(row==null || row.getRecordVersion()==null || row.getRecordVersion()!=version)throw conflict("装车资料已被其他操作更新，请刷新后核对");
+        var photos=new EnumMap<PhotoSlot,OwnedBusinessModels.Photo>(PhotoSlot.class);for(var p:projection.photos(row))photos.put(p.slot(),p);
+        photos.put(originalSlot,new OwnedBusinessModels.Photo(originalSlot,originalSlot.category(),verified.fileId(),verified.fileName(),verified.contentType(),verified.sizeBytes(),verified.uploadedAt(),Instant.now().toString()));
+        row.setPhotosJson(codec.write(List.copyOf(photos.values())));row.setRecordVersion(Math.addExact(version,1));row.setUpdatedBy(operator);row.setUpdatedAt(codec.utc(Instant.now()));
+        if(repository.update(row,version)!=1)throw conflict("装车资料版本竞争失败");
+        var history=new OwnedBusinessRows.History();history.setId(IdWorker.getId());history.setDispatchId(id);history.setRecordVersion(row.getRecordVersion());
+        history.setAction("BIND_LOADING_DOCUMENT");history.setOperatorId(operator);history.setReason("保存装车照片 "+(slot.ordinal()+1));history.setOccurredAt(row.getUpdatedAt());
+        history.setSnapshotJson(codec.write(new OwnedBusinessModels.Snapshot(projection.operations(row),projection.photos(row),operator)));repository.history(history);
+        return read(id);
+    }
+    /** 保存调用者提供的最终阶段，命令与资料、派送同事务提交。 */
+    @Override @Transactional(propagation=Propagation.MANDATORY)
+    public void recordBind(long id,String operator,Slot slot,BindPhoto request,Documents result) {
+        commands.success(id,operator(operator),request.idempotencyKey(),"BIND_LOADING_DOCUMENT",codec.version(request.recordVersion()),new Binding(slot,request),result);
+    }
+    /** 下载仅允许当前已保存引用，不接受未绑定上传或其他车文件。 */
+    @Override public Download content(long id,Slot slot,long fileId) {
+        var originalSlot=slot(slot);var photo=projection.photos(repository.record(id)).stream()
+            .filter(p->p.slot()==originalSlot && String.valueOf(fileId).equals(p.fileId())).findFirst()
+            .orElseThrow(()->new BizException(ResultCode.NOT_FOUND,"本车未绑定该装车照片"));
+        return new Download(publicPhoto(photo),files.content(id,originalSlot,fileId));
+    }
+    /** 原五框技术名保持文件归属，拒绝油耗框作为装车资料。 */
+    private PhotoSlot slot(Slot slot){if(slot==null)throw bad("请选择有效的装车照片框");return PhotoSlot.valueOf(slot.name());}
+    /** 版本0合法，文件编号必须为正且请求键不得缺失。 */
+    private void validate(Slot slot,BindPhoto request) {
+        slot(slot);if(request==null)throw bad("照片绑定请求缺失");codec.key(request.idempotencyKey());codec.version(request.recordVersion());
+        if(codec.version(request.fileId())<=0)throw bad("文件编号无效");
+    }
+    /** 账本只消费可信操作者；平台/PDA权限在排车入口复核。 */
+    private OwnedBusinessModels.Actor operator(String operator){return new OwnedBusinessModels.Actor(operator,operator,Set.of());}
+    /** 回执必须是已知成功上传，其他类别或未明确结果不得充数。 */
+    private Photo uploaded(OwnedBusinessRows.Command command) {
+        if(!"UPLOAD_PHOTO".equals(command.getAction()) || !"SUCCEEDED".equals(command.getStatus()) || command.getResultJson()==null)throw conflict("原上传结果尚未确认，请保留原请求");
+        var value=codec.read(command.getResultJson(),OwnedBusinessModels.Photo.class);
+        if(!"LOADING".equals(value.category()))throw bad("原上传不是装车照片");return publicPhoto(value);
+    }
+    /** 外部事实仅投影照片字段，不暴露持久化记录。 */
+    private Photo publicPhoto(OwnedBusinessModels.Photo photo) {
+        return new Photo(Slot.valueOf(photo.slot().name()),photo.category(),photo.fileId(),photo.fileName(),photo.contentType(),photo.sizeBytes(),photo.uploadedAt(),photo.savedAt());
+    }
+    /** 上传回执不伪造保存时间。 */
+    private OwnedBusinessModels.Photo photo(PhotoSlot slot,OwnedBusinessFileGateway.Evidence value) {
+        return new OwnedBusinessModels.Photo(slot,slot.category(),Long.toString(value.fileId()),value.fileName(),value.contentType(),Long.toString(value.sizeBytes()),value.uploadedAt(),null);
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/service/OwnedBusinessProjection.java

@@ -53,8 +53,7 @@ public class OwnedBusinessProjection {
         var resources=codec.read(source.getResourcesJson(),Resources.class);
         if(resources.vehicle()==null)throw OwnedBusinessSupport.conflict("原车辆快照缺失");
         var ops=operations(record);var photos=photos(record);int pallets=palletCount(source);
-        if(scope==OwnedBusinessScope.OUTSOURCED && (ops.actualDistanceMiles()!=null || ops.fuelConsumptionLitresPer100Km()!=null
-            || photos.stream().anyMatch(p->!"LOADING".equals(p.category()))))throw OwnedBusinessSupport.conflict("外配运营记录含不支持的里程、油耗或照片");
+        if(scope==OwnedBusinessScope.OUTSOURCED && (ops.actualDistanceMiles()!=null || ops.fuelConsumptionLitresPer100Km()!=null))throw OwnedBusinessSupport.conflict("外配运营记录含不支持的里程、油耗或照片");
         var arrivals=new HashMap<String,String>();for(var a:ops.arrivals())arrivals.put(a.destinationKey(),a.actualArrivedAt());
         var destinations=new LinkedHashMap<String,Destination>();
         for(var item:cargo) {

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/service/OwnedBusinessQueryService.java

@@ -93,9 +93,10 @@ public class OwnedBusinessQueryService {
         if(source.getOwnedVehicleOwnership()==null)throw conflict("本单缺少装车时车辆归属证据，不能归入"+(scope==OwnedBusinessScope.OWNED?"自有":"外配")+"业务");
         if(!Set.of("OWNED","DISPATCHED").contains(source.getOwnedVehicleOwnership()))throw conflict("装车车辆归属不合法");
         if(source.getPooledCargo()==null)throw conflict("本单缺少实际拼车分类依据");
-        if(scope.isPooledCargo()!=source.getPooledCargo())throw scope.missing();
+        if(scope!=OwnedBusinessScope.DISPATCH && scope.isPooledCargo()!=source.getPooledCargo())throw scope.missing();
         if(!"ACTIVE".equals(source.getStatus()) || source.getStage()==null || !Set.of("AFTER_LOADING","DELIVERING","DELIVERED").contains(source.getStage())
             || source.getLoadingCompletedAt()==null || source.getLoadingConfirmationJson()==null)throw conflict("本单尚无合法装车完成事实");
+        if(scope==OwnedBusinessScope.DISPATCH && !Set.of("DELIVERING","DELIVERED").contains(source.getStage()))throw conflict("仅派送中和配送完成可管理车辆资料");
         var resource=codec.read(source.getResourcesJson(),DispatchContracts.Resources.class).vehicle();
         boolean master=resource!=null && resource.mode()!=null && "MASTER".equals(resource.mode().name()) && "MASTER".equals(source.getOwnedResourceMode())
             && resource.vehicleId()!=null && Objects.equals(source.getOwnedVehicleId(),resource.vehicleId());

lastleg-service/src/main/java/com/baiyue/lastleg/mapper/LastlegOrderMapper.java

@@ -210,12 +210,19 @@ public interface LastlegOrderMapper extends BaseMapper<LastlegOrder> {
     @Select("SELECT * FROM ll_order WHERE source_container_booking_id=#{sourceContainerBookingId} ORDER BY customer_id,id FOR UPDATE")
     List<LastlegOrder> lockContainerOrders(@Param("sourceContainerBookingId") String sourceContainerBookingId);
 
+    /** 人工时间及计划冻结时间优先；返回计划数量供各页面统一判断默认日期。 */
     @Select("<script>SELECT o.source_container_booking_id AS sourceContainerBookingId," +
         "CASE WHEN COUNT(o.estimated_warehouse_at)=COUNT(*) AND COUNT(DISTINCT o.estimated_warehouse_at)=1 " +
+        "AND (MAX(o.arrival_time_version)&gt;0 OR EXISTS(SELECT 1 FROM ll_inbound_plan p " +
+        "JOIN ll_order po ON po.id=p.source_order_id AND po.customer_id=p.customer_id " +
+        "WHERE po.source_container_booking_id=o.source_container_booking_id)) " +
         "THEN MAX(o.estimated_warehouse_at) ELSE NULL END AS estimatedWarehouseArrivalAt," +
         "(SELECT MIN(s.receiving_at) FROM ll_receiving_container_session s " +
         "WHERE s.source_container_booking_id=o.source_container_booking_id AND s.receiving_at IS NOT NULL) AS actualWarehouseArrivalAt," +
-        "CASE WHEN COUNT(DISTINCT o.arrival_time_version)=1 THEN MAX(o.arrival_time_version) ELSE -1 END AS version " +
+        "CASE WHEN COUNT(DISTINCT o.arrival_time_version)=1 THEN MAX(o.arrival_time_version) ELSE -1 END AS version," +
+        "(SELECT COUNT(*) FROM ll_inbound_plan p JOIN ll_order po " +
+        "ON po.id=p.source_order_id AND po.customer_id=p.customer_id " +
+        "WHERE po.source_container_booking_id=o.source_container_booking_id) AS planCount " +
         "FROM ll_order o WHERE o.source_container_booking_id IN " +
         "<foreach collection='bookingIds' item='id' open='(' separator=',' close=')'>#{id}</foreach> " +
         "GROUP BY o.source_container_booking_id</script>")

lastleg-service/src/main/resources/db/lastleg.sql

@@ -1907,6 +1907,7 @@ CREATE TABLE IF NOT EXISTS ll_dispatch_order (
   review_state VARCHAR(32) NOT NULL DEFAULT 'DRAFT' COMMENT '审核子流程当前状态',
   review_round BIGINT NOT NULL DEFAULT 0 COMMENT '当前审核轮次',
   review_basis_hash CHAR(64) NULL COMMENT '本审核轮次核对的货物和资源依据摘要',
+  exceptions_json JSON NULL COMMENT '派送异常登记记录及图片引用，不改变派送及库存状态',
   dispatch_review_json JSON NULL COMMENT '当前调度审核事实快照',
   loading_review_json JSON NULL COMMENT '当前理货审核事实快照',
   resources_json JSON NULL COMMENT '本趟主档或临时车辆司机的真实资源快照',

lastleg-service/src/main/resources/openapi/dispatch-loading-documents-v1.yaml

@@ -0,0 +1,394 @@
+openapi: 3.0.3
+info:
+  title: 排车装车资料（Admin/PDA共用）
+  version: 1.0.0
+  description: LOADING阶段即可同步上传并保存五个整车照片框；照片齐全不会提前发车。装车确认时资料已齐则直接进入DELIVERING，否则进入AFTER_LOADING，最后一次绑定自动生成派送并进入DELIVERING。触发推进的装车确认或照片绑定与派送同事务，失败保留先前已保存资料。复用车队照片记录，技术槽位仅表示照片1至5，不代表驾驶证审核或真实签收。PDA每次核验Token冻结仓，平台list只读、edit写；原键仅原操作者恢复。
+security:
+- bearerAuth: []
+paths:
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents:
+    get:
+      operationId: getDispatchLoadingDocuments
+      summary: 读取本车装车资料或原上传结果
+      x-permission-code: platform:overseas-warehouse:dispatch:list
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Documents'
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents:
+    get:
+      operationId: getDispatchLoadingDocumentsPda
+      summary: 读取本车装车资料或原上传结果
+      x-permission-code: lastleg:pda:operate
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Documents'
+      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}/uploads:
+    post:
+      operationId: uploadDispatchLoadingPhoto
+      summary: 上传整车装车照片，尚未绑定
+      x-permission-code: platform:overseas-warehouse:dispatch:edit
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Photo'
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required:
+              - file
+              - idempotencyKey
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: 非空JPG/PNG，最大10MiB
+                idempotencyKey:
+                  type: string
+                  minLength: 8
+                  maxLength: 128
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}/uploads:
+    post:
+      operationId: uploadDispatchLoadingPhotoPda
+      summary: 上传整车装车照片，尚未绑定
+      x-permission-code: lastleg:pda:operate
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Photo'
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required:
+              - file
+              - idempotencyKey
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: 非空JPG/PNG，最大10MiB
+                idempotencyKey:
+                  type: string
+                  minLength: 8
+                  maxLength: 128
+      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}:
+    put:
+      operationId: bindDispatchLoadingPhoto
+      summary: 保存装车照片；五框齐全时自动进入派送中
+      x-permission-code: platform:overseas-warehouse:dispatch:edit
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Documents'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BindPhoto'
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}:
+    put:
+      operationId: bindDispatchLoadingPhotoPda
+      summary: 保存装车照片；五框齐全时自动进入派送中
+      x-permission-code: lastleg:pda:operate
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Documents'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BindPhoto'
+      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}/files/{fileId}/content:
+    get:
+      operationId: readDispatchLoadingPhoto
+      summary: 读取本车装车资料或原上传结果
+      x-permission-code: platform:overseas-warehouse:dispatch:list
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      - $ref: '#/components/parameters/fileId'
+      responses:
+        '200':
+          description: no-store图片内容
+          content:
+            image/jpeg:
+              schema:
+                type: string
+                format: binary
+            image/png:
+              schema:
+                type: string
+                format: binary
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}/files/{fileId}/content:
+    get:
+      operationId: readDispatchLoadingPhotoPda
+      summary: 读取本车装车资料或原上传结果
+      x-permission-code: lastleg:pda:operate
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      - $ref: '#/components/parameters/fileId'
+      responses:
+        '200':
+          description: no-store图片内容
+          content:
+            image/jpeg:
+              schema:
+                type: string
+                format: binary
+            image/png:
+              schema:
+                type: string
+                format: binary
+      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents/uploads/{idempotencyKey}:
+    get:
+      operationId: recoverDispatchLoadingPhoto
+      summary: 读取本车装车资料或原上传结果
+      x-permission-code: platform:overseas-warehouse:dispatch:edit
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/idempotencyKey'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Photo'
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents/uploads/{idempotencyKey}:
+    get:
+      operationId: recoverDispatchLoadingPhotoPda
+      summary: 读取本车装车资料或原上传结果
+      x-permission-code: lastleg:pda:operate
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/idempotencyKey'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Photo'
+      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  parameters:
+    dispatchNo:
+      name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
+    slot:
+      name: slot
+      in: path
+      required: true
+      schema:
+        type: string
+        enum: &id001
+        - LOADING_SCENE
+        - LOADING_LIST
+        - PRE_DEPARTURE_CHECK
+        - DRIVER_LICENSE
+        - RECEIPT
+    fileId:
+      name: fileId
+      in: path
+      required: true
+      schema:
+        type: string
+    idempotencyKey:
+      name: idempotencyKey
+      in: path
+      required: true
+      schema:
+        type: string
+  schemas:
+    Photo:
+      type: object
+      required:
+      - slot
+      - fileId
+      - fileName
+      - contentType
+      - sizeBytes
+      - uploadedAt
+      properties:
+        slot:
+          type: string
+          enum: *id001
+        category:
+          type: string
+          enum:
+          - LOADING
+        fileId:
+          type: string
+        fileName:
+          type: string
+        contentType:
+          type: string
+        sizeBytes:
+          type: string
+        uploadedAt:
+          type: string
+        savedAt:
+          type: string
+          nullable: true
+    Documents:
+      type: object
+      required:
+      - dispatchNo
+      - recordVersion
+      - editable
+      - photos
+      - dispatchRecordVersion
+      - stage
+      - complete
+      properties:
+        dispatchNo:
+          type: string
+        recordVersion:
+          type: string
+        editable:
+          type: boolean
+        photos:
+          type: array
+          items:
+            $ref: '#/components/schemas/Photo'
+        dispatchRecordVersion:
+          type: string
+        stage:
+          type: string
+          enum:
+          - LOADING
+          - AFTER_LOADING
+          - DELIVERING
+          - DELIVERED
+        complete:
+          type: boolean
+          description: 五个固定框各有一张已保存照片
+    BindPhoto:
+      type: object
+      required:
+      - recordVersion
+      - idempotencyKey
+      - fileId
+      properties:
+        recordVersion:
+          type: string
+          pattern: ^(0|[1-9][0-9]*)$
+        idempotencyKey:
+          type: string
+          minLength: 8
+          maxLength: 128
+        fileId:
+          type: string

lastleg-service/src/main/resources/openapi/dispatch-vehicle-documents-v1.yaml

@@ -0,0 +1,242 @@
+openapi: 3.0.3
+info:
+  title: 排车车辆资料
+  version: 1.0.0
+  description: 仅平台有效排车DELIVERING/DELIVERED可用；兼容有无拼车货物，沿装车归属证据校验。共享原车队照片、版本、命令与历史，不新建附件存储。派送文件仍使用delivery-orders
+    documents；不把车队RECEIPT照片当签收。列表权限只读，排车edit独立写；恢复还需list。
+security:
+- bearerAuth: []
+paths:
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents:
+    get:
+      operationId: getDispatchVehicleDocuments
+      summary: 读取本车油耗图片；复用车队附加记录
+      x-permission-code: platform:overseas-warehouse:dispatch:list
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Documents'
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents/{slot}/uploads:
+    post:
+      operationId: uploadDispatchVehiclePhoto
+      summary: 准备本车油耗图片；尚未绑定保存
+      x-permission-code: platform:overseas-warehouse:dispatch:edit
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Photo'
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required:
+              - file
+              - idempotencyKey
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: 非空JPG/PNG，最大10MiB
+                idempotencyKey:
+                  type: string
+                  minLength: 8
+                  maxLength: 128
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents/{slot}:
+    put:
+      operationId: bindDispatchVehiclePhoto
+      summary: 按附加版本绑定原上传文件，不改变排车或签收状态
+      x-permission-code: platform:overseas-warehouse:dispatch:edit
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Documents'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BindPhoto'
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents/{slot}/files/{fileId}/content:
+    get:
+      operationId: readDispatchVehiclePhoto
+      summary: 只读取本车当前绑定图片
+      x-permission-code: platform:overseas-warehouse:dispatch:list
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/slot'
+      - $ref: '#/components/parameters/fileId'
+      responses:
+        '200':
+          description: no-store图片内容
+          content:
+            image/jpeg:
+              schema:
+                type: string
+                format: binary
+            image/png:
+              schema:
+                type: string
+                format: binary
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents/uploads/{idempotencyKey}:
+    get:
+      operationId: recoverDispatchVehiclePhoto
+      summary: 只恢复当前操作者原油耗上传成功结果，未知结果拒绝重传
+      x-permission-code: platform:overseas-warehouse:dispatch:edit
+      parameters:
+      - $ref: '#/components/parameters/dispatchNo'
+      - $ref: '#/components/parameters/idempotencyKey'
+      responses:
+        '200':
+          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Photo'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  parameters:
+    dispatchNo:
+      name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
+    slot:
+      name: slot
+      in: path
+      required: true
+      schema:
+        type: string
+        enum:
+        - FUEL_START
+        - FUEL_END
+    fileId:
+      name: fileId
+      in: path
+      required: true
+      schema:
+        type: string
+    idempotencyKey:
+      name: idempotencyKey
+      in: path
+      required: true
+      schema:
+        type: string
+  schemas:
+    Photo:
+      type: object
+      required:
+      - slot
+      - fileId
+      - fileName
+      - contentType
+      - sizeBytes
+      - uploadedAt
+      properties:
+        slot:
+          type: string
+          enum:
+          - FUEL_START
+          - FUEL_END
+        category:
+          type: string
+          enum:
+          - FUEL
+        fileId:
+          type: string
+        fileName:
+          type: string
+        contentType:
+          type: string
+        sizeBytes:
+          type: string
+        uploadedAt:
+          type: string
+        savedAt:
+          type: string
+          nullable: true
+    Documents:
+      type: object
+      required:
+      - dispatchNo
+      - recordVersion
+      - editable
+      - photos
+      properties:
+        dispatchNo:
+          type: string
+        recordVersion:
+          type: string
+        editable:
+          type: boolean
+        photos:
+          type: array
+          items:
+            $ref: '#/components/schemas/Photo'
+    BindPhoto:
+      type: object
+      required:
+      - recordVersion
+      - idempotencyKey
+      - fileId
+      properties:
+        recordVersion:
+          type: string
+          pattern: ^(0|[1-9][0-9]*)$
+        idempotencyKey:
+          type: string
+          minLength: 8
+          maxLength: 128
+        fileId:
+          type: string

lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml

@@ -920,7 +920,8 @@ paths:
       parameters:
       - name: warehouseId
         in: query
-        required: true
+        description: 可选真实起运仓；未指定时按 warehouseTab 跨仓分页浏览，草稿及建单仍要求同一起运仓。
+        required: false
         schema:
           type: string
       - name: planIds
@@ -1682,10 +1683,53 @@ paths:
       required: true
       schema:
         type: string
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/exceptions:
+    post:
+      summary: 登记派送异常
+      description: 权限 platform:overseas-warehouse:dispatch:edit；仅有效仓库派送单DELIVERING可登记，保存后阶段不变，不产生退货、签收或库存变化。原键重试恢复原结果。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - $ref: '#/components/schemas/DispatchCommandResult'
+                    nullable: true
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DispatchMarkException'
+    parameters:
+    - name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
   /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-complete:
     post:
-      summary: 确认装车完成并自动进入派送中
-      description: 权限 platform:overseas-warehouse:dispatch:loading-complete。 原请求在同一事务完成实载确认、全车派送单生成及发车；成功action为LOADING_COMPLETE、stage为DELIVERING，result保留真实Loaded装车证据。任一步失败整体回滚，重试原键恢复最终结果，不另行安排派送或确认发车。
+      summary: 确认装车完成，资料齐全时自动进入派送中
+      description: 权限 platform:overseas-warehouse:dispatch:loading-complete。 装车中可通过loading-documents同步保存五张装车照片。原请求保存实载确认；成功action为LOADING_COMPLETE，资料已齐时stage为DELIVERING，未齐时为AFTER_LOADING，result保留真实Loaded装车证据。装车确认与资料齐全两项均完成时自动生成派送并发车；触发该次推进的装车确认或最后一次绑定与派送同事务回滚，先前已保存照片保留。重试装车原键保持原最终阶段结果，当前阶段另行读取。
       security:
       - bearerAuth: []
       responses:
@@ -1880,7 +1924,7 @@ paths:
   /api/platform/v1/last-leg/dispatches/{dispatchNo}/evidence/{kind}:
     post:
       summary: 上传本趟车辆或司机证据
-      description: 客服阶段使用 platform:overseas-warehouse:dispatch:edit；调度待审/理货待审分别使用 platform:fleet:trip:dispatch-review / platform:fleet:trip:loading-review，无需维护车辆权限。VEHICLE和DRIVER支持PDF/JPG/PNG，DRIVER_PHOTO仅JPG/PNG，非空且不超过10MiB；平台、本车、类型复合归属。审核补充附件随ReviewCommand保存，不修改资源，不重启审核。
+      description: 客服阶段使用 platform:overseas-warehouse:dispatch:edit；调度待审/理货待审分别使用 platform:fleet:trip:dispatch-review / platform:fleet:trip:loading-review，无需维护车辆权限。VEHICLE和DRIVER支持PDF/JPG/PNG，DRIVER_PHOTO和EXCEPTION仅JPG/PNG；EXCEPTION仅派送中使用排车edit权限，引用随异常登记保存。非空且不超过10MiB；平台、本车、类型复合归属。审核补充附件随ReviewCommand保存，不修改资源，不重启审核。
       security:
       - bearerAuth: []
       responses:
@@ -1935,6 +1979,7 @@ paths:
         - VEHICLE
         - DRIVER
         - DRIVER_PHOTO
+        - EXCEPTION
   /api/platform/v1/last-leg/dispatches/{dispatchNo}/evidence/{kind}/{fileId}:
     get:
       summary: 读取本车证据元数据
@@ -1981,6 +2026,7 @@ paths:
         - VEHICLE
         - DRIVER
         - DRIVER_PHOTO
+        - EXCEPTION
     - name: fileId
       in: path
       required: true
@@ -2024,6 +2070,7 @@ paths:
         - VEHICLE
         - DRIVER
         - DRIVER_PHOTO
+        - EXCEPTION
     - name: fileId
       in: path
       required: true
@@ -3503,12 +3550,13 @@ components:
         remark: { type: string, maxLength: 500, nullable: true }
     ContainerArrivalTimeView:
       type: object
-      required: [sourceContainerBookingId, version]
+      required: [sourceContainerBookingId, version, planCount]
       properties:
         sourceContainerBookingId: { type: string }
-        estimatedWarehouseArrivalAt: { type: string, format: date-time, nullable: true }
+        estimatedWarehouseArrivalAt: { type: string, format: date-time, nullable: true, description: 人工维护或入库计划冻结的整柜时间；未维护未建计划时为空，由页面按到港当地日期加两个自然日展示默认日期 }
         actualWarehouseArrivalAt: { type: string, format: date-time, nullable: true, description: 海外 PDA 首次开始收货时间 }
-        version: { type: integer, minimum: 0 }
+        version: { type: integer, minimum: -1, description: -1表示柜内时间版本不一致 }
+        planCount: { type: integer, format: int64, minimum: 0, description: 整柜已有入库计划数量；非零时禁止默认推算及改期 }
     ContainerPlanProgressDetail:
       type: object
       required: [summary, orders]
@@ -5142,6 +5190,7 @@ components:
       - LOADING_COMPLETE
       - ARRANGE_DELIVERY
       - DEPART
+      - MARK_EXCEPTION
     DispatchGate:
       type: object
       x-java-record: DispatchContracts.Gate
@@ -6314,6 +6363,10 @@ components:
           items:
             $ref: '#/components/schemas/DispatchBatchReference'
           nullable: true
+        exceptions:
+          type: array
+          items:
+            $ref: '#/components/schemas/DispatchExceptionRecord'
       required:
       - route
       - plannedDepartureAt
@@ -6321,6 +6374,7 @@ components:
       - estimatedArrivalAt
       - fbaAppointments
       - appointmentBatches
+      - exceptions
     DispatchDocuments:
       type: object
       x-java-record: DispatchViews.Documents
@@ -7940,5 +7994,66 @@ components:
       - sourceInboundOrderNo
       - sourceInboundCode
       - productQuantity
+
+    DispatchExceptionType:
+      type: string
+      enum: [REFUSED, PARTIAL_RECEIPT, VEHICLE_EXCEPTION]
+      description: 拒收、部分签收、车辆异常。
+    DispatchReturnDirection:
+      type: string
+      enum: [OVERSEAS_WAREHOUSE, OTHER]
+      description: 退回海外仓、其他；仅登记去向，不自动退货入库。
+    DispatchMarkException:
+      type: object
+      x-java-record: DispatchCommands.MarkException
+      required: [recordVersion, idempotencyKey, exceptionType]
+      properties:
+        recordVersion:
+          oneOf:
+          - type: string
+            pattern: ^[0-9]+$
+          - type: integer
+            minimum: 0
+        idempotencyKey:
+          type: string
+        exceptionType:
+          $ref: '#/components/schemas/DispatchExceptionType'
+        returnDirection:
+          allOf:
+          - $ref: '#/components/schemas/DispatchReturnDirection'
+          nullable: true
+        description:
+          type: string
+          maxLength: 1000
+          nullable: true
+        imageFileIds:
+          type: array
+          maxItems: 20
+          uniqueItems: true
+          items:
+            type: string
+            pattern: ^[1-9][0-9]*$
+    DispatchExceptionRecord:
+      type: object
+      x-java-record: DispatchViews.ExceptionRecord
+      required: [exceptionType, returnDirection, description, imageFileIds, occurredAt]
+      properties:
+        exceptionType:
+          $ref: '#/components/schemas/DispatchExceptionType'
+        returnDirection:
+          allOf:
+          - $ref: '#/components/schemas/DispatchReturnDirection'
+          nullable: true
+        description:
+          type: string
+          nullable: true
+        imageFileIds:
+          type: array
+          items:
+            type: string
+        occurredAt:
+          type: string
+          format: date-time
+
   securitySchemes:
     bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }

lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml

@@ -253,8 +253,8 @@ paths:
         type: string
   /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-complete:
     post:
-      summary: 确认装车完成并自动进入派送中
-      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。只用整车recordVersion和全载荷幂等键；扫码执行真实库存SHIP，装车完成和发车不重复SHIP。错误或结果未知保留原请求核对。 原请求在同一事务完成实载确认、全车派送单生成及发车；成功action为LOADING_COMPLETE、stage为DELIVERING，result保留真实Loaded装车证据。任一步失败整体回滚，重试原键恢复最终结果，不另行安排派送或确认发车。
+      summary: 确认装车完成，资料齐全时自动进入派送中
+      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。只用整车recordVersion和全载荷幂等键；扫码执行真实库存SHIP，装车完成和发车不重复SHIP。错误或结果未知保留原请求核对。 装车中可通过loading-documents同步保存五张装车照片。原请求保存实载确认；成功action为LOADING_COMPLETE，资料已齐时stage为DELIVERING，未齐时为AFTER_LOADING，result保留真实Loaded装车证据。装车确认与资料齐全两项均完成时自动生成派送并发车；触发该次推进的装车确认或最后一次绑定与派送同事务回滚，先前已保存照片保留。重试装车原键保持原最终阶段结果，当前阶段另行读取。
       security:
       - bearerAuth: []
       responses:

lastleg-service/src/test/java/com/baiyue/lastleg/calendar/WarehouseCalendarMapperTest.java

@@ -2,6 +2,7 @@ package com.baiyue.lastleg.calendar;
 
 import com.baomidou.mybatisplus.core.MybatisConfiguration;
 import com.baomidou.mybatisplus.core.MybatisSqlSessionFactoryBuilder;
+import com.baiyue.lastleg.mapper.LastlegOrderMapper;
 import org.apache.ibatis.mapping.Environment;
 import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
 import org.h2.jdbcx.JdbcDataSource;
@@ -28,12 +29,23 @@ class WarehouseCalendarMapperTest {
         }
         var config=new MybatisConfiguration(); config.setEnvironment(new Environment("test",new JdbcTransactionFactory(),ds));
         config.addMapper(WarehouseCalendarMapper.class);
+        config.addMapper(LastlegOrderMapper.class);
         try(var session=new MybatisSqlSessionFactoryBuilder().build(config).openSession()) {
             var rows=session.getMapper(WarehouseCalendarMapper.class).calendar(LocalDateTime.parse("2026-11-01T00:00:00"),LocalDateTime.parse("2026-12-01T00:00:00"),List.of("1"));
             assertEquals(3,rows.size());
             assertEquals("1",rows.get(0).sourceContainerBookingId()); assertNull(rows.get(0).plannedAt());
             assertEquals(2,rows.get(1).version()); assertEquals("2026-11-10T09:00",rows.get(1).plannedAt().toString());
             assertEquals(1,rows.get(2).planCount()); assertNotNull(rows.get(2).plannedAt());
+            // 清关提柜与日历必须读取相同的人工/冻结事实，默认日期由前端统一推算。
+            var customs=session.getMapper(LastlegOrderMapper.class).findContainerArrivalTimes(List.of("1","2","3"));
+            assertEquals(3,customs.size());
+            for(var calendar:rows) {
+                var arrival=customs.stream().filter(row -> row.sourceContainerBookingId().equals(calendar.sourceContainerBookingId())).findFirst().orElseThrow();
+                assertEquals(calendar.plannedAt(),arrival.estimatedWarehouseArrivalAt());
+                assertEquals(calendar.actualAt(),arrival.actualWarehouseArrivalAt());
+                assertEquals(calendar.version(),arrival.version());
+                assertEquals(calendar.planCount(),arrival.planCount());
+            }
         }
     }
 }

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/SmartDispatchOpenApiContractTest.java

@@ -38,6 +38,9 @@ class SmartDispatchOpenApiContractTest {
         assertThat(map(paths.get(base+"/drafts"))).containsKey("get");
         var candidate=map(map(paths.get(base+"/candidates")).get("get"));
         var parameterNames=((List<?>)candidate.get("parameters")).stream().map(SmartDispatchOpenApiContractTest::map).map(p->p.get("name")).toList();
+        var warehouseParameter=((List<?>)candidate.get("parameters")).stream().map(SmartDispatchOpenApiContractTest::map)
+            .filter(p->"warehouseId".equals(p.get("name"))).findFirst().orElseThrow();
+        assertThat(warehouseParameter.get("required")).isEqualTo(false);
         assertThat(parameterNames).contains("warehouseId","destinationWarehouseCode","draftToken","page","size","warehouseTab").doesNotContain("customerId","fbaWarehouseCode");
         assertThat(map(map(schemas.get("DispatchCandidateList")).get("properties")).keySet())
             .containsExactlyInAnyOrder("candidates","snapshotAt","complete","total","page","size","pages");

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/controller/SmartDispatchControllerTest.java

@@ -45,6 +45,16 @@ class SmartDispatchControllerTest {
             .andExpect(status().isOk());
         verify(aggregate).candidates(actor,new CandidateQuery("92",null,null,"LAX9",null,null,1,20,"ALL"));verifyNoInteractions(planning);
     }
+    /** 区域入口无需隐藏默认仓，全部与城市均由服务端分页。 */
+    @Test void candidateHttpQueryAllowsRegionalBrowsingWithoutWarehouse()throws Exception {
+        var mvc=MockMvcBuilders.standaloneSetup(controller).setCustomArgumentResolvers(new AuthenticationPrincipalArgumentResolver()).build();
+        SecurityContextHolder.getContext().setAuthentication(new UsernamePasswordAuthenticationToken(platform(),null,List.of()));
+        for(String tab:List.of("ALL","LAX","NYC")) {
+            mvc.perform(get("/api/platform/v1/last-leg/dispatches/candidates").param("warehouseTab",tab)).andExpect(status().isOk());
+            verify(aggregate).candidates(actor,new CandidateQuery(null,null,null,null,null,null,1,20,tab));
+        }
+        verifyNoInteractions(planning);
+    }
     /** 每个写入都将冻结DTO原样传递，拥有者只能来自认证主体。 */
     @Test void allDraftRoutesDelegateFrozenVersionedRequests(){
         var create=new CreateDraft("create","92");var container=new CreateContainer(0L,"container","d",15);

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/gateway/HttpDispatchEvidenceGatewayTest.java

@@ -45,6 +45,15 @@ class HttpDispatchEvidenceGatewayTest {
         var pdf=new HttpDispatchEvidenceGateway.Metadata(3L,0L,"OVERSEAS_DISPATCH_DRIVER_PHOTO_EVIDENCE","9","driver.pdf","application/pdf",128L);
         assertThatThrownBy(()->HttpDispatchEvidenceGateway.verified(new HttpDispatchEvidenceGateway.Envelope("200",pdf),9,DispatchEvidenceGateway.Kind.DRIVER_PHOTO,3L)).isInstanceOf(ResponseStatusException.class);
     }
+    /** 异常图片独立归属本车，审核照片及PDF均不能用作异常图片。 */
+    @Test void exceptionImagesRejectOtherKindsCarsAndPdf() {
+        var photo=new HttpDispatchEvidenceGateway.Metadata(3L,0L,"OVERSEAS_DISPATCH_EXCEPTION_EVIDENCE","9","exception.png","image/png",128L);
+        assertThat(HttpDispatchEvidenceGateway.verified(new HttpDispatchEvidenceGateway.Envelope("200",photo),9,DispatchEvidenceGateway.Kind.EXCEPTION,3L).fileId()).isEqualTo(3L);
+        assertThatThrownBy(()->HttpDispatchEvidenceGateway.verified(new HttpDispatchEvidenceGateway.Envelope("200",photo),10,DispatchEvidenceGateway.Kind.EXCEPTION,3L)).isInstanceOf(ResponseStatusException.class);
+        assertThatThrownBy(()->HttpDispatchEvidenceGateway.verified(new HttpDispatchEvidenceGateway.Envelope("200",photo),9,DispatchEvidenceGateway.Kind.DRIVER_PHOTO,3L)).isInstanceOf(ResponseStatusException.class);
+        var pdf=new HttpDispatchEvidenceGateway.Metadata(3L,0L,"OVERSEAS_DISPATCH_EXCEPTION_EVIDENCE","9","exception.pdf","application/pdf",128L);
+        assertThatThrownBy(()->HttpDispatchEvidenceGateway.verified(new HttpDispatchEvidenceGateway.Envelope("200",pdf),9,DispatchEvidenceGateway.Kind.EXCEPTION,3L)).isInstanceOf(ResponseStatusException.class);
+    }
     /** 客户、旧主档或缺失媒体类型均拒绝，不因为文件本身存在而放行。 */
     @Test void rejectsForeignTenantMasterScopeAndMalformedMetadata() {
         for(var value:java.util.List.of(

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/service/DispatchExceptionPersistenceTest.java

@@ -0,0 +1,89 @@
+package com.baiyue.lastleg.dispatch.service;
+
+import com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway;
+import com.baiyue.lastleg.dispatch.port.DispatchCommands;
+import com.baiyue.lastleg.dispatch.port.DispatchContracts;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.security.authentication.TestingAuthenticationToken;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.test.util.ReflectionTestUtils;
+import java.util.List;
+import static com.baiyue.lastleg.dispatch.port.DispatchTypes.*;
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+/** 通过真实Mapper和事务验证异常登记，不把登记事实解释成签收或退货。 */
+class DispatchExceptionPersistenceTest {
+    /** 登记使用排车独立维护权限。 */
+    @BeforeEach void authorize() { SecurityContextHolder.getContext().setAuthentication(new TestingAuthenticationToken("operator-test","","platform:overseas-warehouse:dispatch:edit")); }
+    /** 清除线程身份，避免影响其他权限回归。 */
+    @AfterEach void clear() { SecurityContextHolder.clearContext(); }
+
+    /** 每种原型类型均可保存，原键重试不追加，最终完成后仍恢复原结果。 */
+    @Test void recordsAllTypesAndReplaysWithoutChangingDeliveryFacts() throws Exception {
+        var f=new DispatchAggregatePersistenceTest.Fixture();var no=create(f);long version=0;
+        var before=f.db.queryForMap("SELECT stage,shipped_package_count,departed_at,review_state FROM ll_dispatch_order");
+        for(var type:ExceptionType.values()) {
+            var body=new DispatchCommands.MarkException(version,"exception-"+type,type,ReturnDirection.OVERSEAS_WAREHOUSE,"真实异常",List.of());
+            var saved=f.tx.execute(t->f.service.markException(f.actor,no,body));
+            var replay=f.tx.execute(t->f.service.markException(f.actor,no,body));
+            assertThat(saved.stage()).isEqualTo(Stage.DELIVERING);assertThat(replay.replayed()).isTrue();
+            assertThat(replay.recordVersion()).isEqualTo(saved.recordVersion());version=saved.recordVersion();
+        }
+        var records=f.service.detail(f.actor,no).dispatchInfo().exceptions();assertThat(records).hasSize(3);
+        assertThat(records).allSatisfy(r->{assertThat(r.description()).isEqualTo("真实异常");assertThat(r.occurredAt()).isNotNull();});
+        assertThat(f.db.queryForMap("SELECT stage,shipped_package_count,departed_at,review_state FROM ll_dispatch_order")).isEqualTo(before);
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_inventory_ledger",Long.class)).isZero();
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_history WHERE action='MARK_EXCEPTION'",Long.class)).isEqualTo(3);
+        var first=new DispatchCommands.MarkException(0L,"exception-REFUSED",ExceptionType.REFUSED,ReturnDirection.OVERSEAS_WAREHOUSE,"真实异常",List.of());
+        f.db.update("UPDATE ll_dispatch_order SET stage='DELIVERED'");
+        assertThat(f.tx.execute(t->f.service.markException(f.actor,no,first)).replayed()).isTrue();
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,new DispatchCommands.MarkException(0L,"exception-REFUSED",ExceptionType.REFUSED,null,"改了内容",List.of())))).isInstanceOf(RuntimeException.class);
+        assertThat(f.service.detail(f.actor,no).dispatchInfo().exceptions()).hasSize(3);
+    }
+
+    /** 非派送阶段、过期版本、只读身份、PDA及运输任务不能登记。 */
+    @Test void rejectsWrongStageVersionPermissionAndTask() throws Exception {
+        var f=new DispatchAggregatePersistenceTest.Fixture();var no=create(f);var body=request(0,"blocked",List.of());
+        for(var stage:List.of("BEFORE_LOADING","LOADING","AFTER_LOADING","DELIVERED")) {
+            f.db.update("UPDATE ll_dispatch_order SET stage=?",stage);
+            assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,body))).hasMessageContaining("仅派送中");
+        }
+        f.db.update("UPDATE ll_dispatch_order SET stage='DELIVERING'");
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,request(9,"stale",List.of())))).hasMessageContaining("版本");
+        SecurityContextHolder.getContext().setAuthentication(new TestingAuthenticationToken("operator-test","","platform:overseas-warehouse:dispatch:list"));
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,body))).hasMessageContaining("权限");
+        authorize();f.db.update("UPDATE ll_dispatch_order SET task_type='LOCAL_TRUCK'");
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,body))).hasMessageContaining("仅派送中");
+        f.db.update("UPDATE ll_dispatch_order SET task_type='DELIVERY',status='CANCELLED'");
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,body))).hasMessageContaining("仅派送中");
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(new DispatchContracts.Actor("pda",ActorMode.PDA,"9"),no,body))).hasMessageContaining("仅平台");
+        assertThat(f.db.queryForObject("SELECT record_version FROM ll_dispatch_order",Long.class)).isZero();
+    }
+
+    /** 图片严格核对当前车和类别；附件失败或缺类型不保存任何业务记录。 */
+    @Test void verifiesImageOwnershipAndKeepsFailedRequestUnchanged() throws Exception {
+        var f=new DispatchAggregatePersistenceTest.Fixture();var no=create(f);var id=f.repository.find(no).getId();
+        var files=mock(DispatchEvidenceGateway.class);ReflectionTestUtils.setField(f.service,"evidence",files);
+        when(files.metadata(id,DispatchEvidenceGateway.Kind.EXCEPTION,91L)).thenThrow(new IllegalArgumentException("文件不属于当前车"));
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,request(0,"files",List.of(91L))))).hasMessageContaining("不属于");
+        assertThat(f.service.detail(f.actor,no).dispatchInfo().exceptions()).isEmpty();
+        var missingType=new DispatchCommands.MarkException(0L,"no-type",null,null,null,List.of());
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,missingType))).hasMessageContaining("请选择异常类型");
+        assertThatThrownBy(()->f.tx.execute(t->f.service.markException(f.actor,no,request(0,"duplicates",List.of(91L,91L))))).hasMessageContaining("图片引用");
+        doReturn(new DispatchEvidenceGateway.File(91L,"现场.png","image/png",10L)).when(files).metadata(id,DispatchEvidenceGateway.Kind.EXCEPTION,91L);
+        f.tx.execute(t->f.service.markException(f.actor,no,request(0,"files",List.of(91L))));
+        assertThat(f.service.detail(f.actor,no).dispatchInfo().exceptions().get(0).imageFileIds()).containsExactly(91L);
+        verify(files,times(2)).metadata(id,DispatchEvidenceGateway.Kind.EXCEPTION,91L);
+    }
+
+    /** 创建真实排车后仅以SQL模拟已发车前置，不声称此用例执行装车流程。 */
+    private String create(DispatchAggregatePersistenceTest.Fixture f) {
+        var created=f.tx.execute(t->f.service.create(f.actor,f.configured("create",List.of())));
+        f.db.update("UPDATE ll_dispatch_order SET stage='DELIVERING',shipped_package_count=3,departed_at=CURRENT_TIMESTAMP");return created.dispatchNo();
+    }
+    /** 构造类型必填、其余选填的最小登记请求。 */
+    private DispatchCommands.MarkException request(long version,String key,List<Long> images) { return new DispatchCommands.MarkException(version,key,ExceptionType.VEHICLE_EXCEPTION,null,null,images); }
+}

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/service/DispatchLoadingDeparturePersistenceTest.java

@@ -1,6 +1,15 @@
 package com.baiyue.lastleg.dispatch.service;
 
 import com.baiyue.lastleg.dispatch.mapper.*;
+import com.baiyue.lastleg.fleet.ownedbusiness.service.*;
+import com.baiyue.lastleg.fleet.ownedbusiness.gateway.OwnedBusinessFileGateway;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort.BindPhoto;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort.Documents;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort.Slot;
+import com.baiyue.lastleg.fleet.ownedbusiness.mapper.*;
+import com.baiyue.lastleg.fleet.ownedbusiness.repository.OwnedBusinessRepository;
+import java.nio.file.*;
+import java.util.regex.Pattern;
 import com.baiyue.lastleg.dispatch.pda.service.DispatchPdaWorkflowService;
 import com.baiyue.lastleg.dispatch.port.*;
 import com.baiyue.lastleg.dispatch.repository.*;
@@ -19,43 +28,53 @@ import static org.assertj.core.api.Assertions.*;
 import static org.mockito.Mockito.*;
 import static org.mockito.ArgumentMatchers.*;
 
-/** 装完即发车的共同事务、原键最终结果及跨端竞争使用真实根单据和版本。 */
+/** 装车后五框门禁、保存发车共同事务及跨端竞争使用真实单据和版本。 */
 class DispatchLoadingDeparturePersistenceTest {
     /** 每例恢复隔离身份，不影响其他服务权限测试。 */
     @AfterEach void clearSecurity(){SecurityContextHolder.clearContext();}
 
-    /** 一次确认完成全部客户发运；原键重放返回派送中，不再生成子单或执行来源。 */
-    @Test void loadingCompletesAllCustomersAndReplaysOnlyFinalResult() throws Exception {
+    /** 装车完成不发车，第五张保存自动发车，旧装车键保持原装车后结果。 */
+    @Test void loadingWaitsForFivePhotosThenDepartsOnce() throws Exception {
         authorize();var f=new Fixture();
         var result=f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("complete")));
-        assertThat(result.action()).isEqualTo(Action.LOADING_COMPLETE);assertThat(result.stage()).isEqualTo(Stage.DELIVERING);
-        assertThat(result.counts().shippedPackageCount()).isEqualTo(8);assertThat(result.result()).isInstanceOf(DispatchResults.Loaded.class);
+        assertThat(result.action()).isEqualTo(Action.LOADING_COMPLETE);assertThat(result.stage()).isEqualTo(Stage.AFTER_LOADING);
+        assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_delivery_order",Long.class)).isZero();
+        for(int i=0;i<4;i++)assertThat(f.bind(i,f.f.actor).stage()).isEqualTo("AFTER_LOADING");
+        assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_delivery_order",Long.class)).isZero();
+        var fifth=f.bind(4,new Actor("picker",ActorMode.PDA,"9"));assertThat(fifth.stage()).isEqualTo("DELIVERING");
+        assertThat(fifth.complete()).isTrue();assertThat(fifth.photos()).hasSize(5);
+        var replayPhoto=f.f.tx.execute(s->f.documents.bind(new Actor("picker",ActorMode.PDA,"9"),f.number,Slot.RECEIPT,new BindPhoto("4","photo-bind-4","1004")));
+        assertThat(replayPhoto).isEqualTo(fifth);
+        assertThat(result.counts().shippedPackageCount()).isZero();assertThat(result.result()).isInstanceOf(DispatchResults.Loaded.class);
         assertThat(f.f.db.queryForList("SELECT status FROM ll_outbound_order",String.class)).containsExactly("OUTBOUNDED","OUTBOUNDED");
         assertThat(f.f.db.queryForList("SELECT status FROM ll_delivery_order",String.class)).containsExactly("DELIVERING","DELIVERING");
         assertThat(f.f.db.queryForObject("SELECT status FROM ll_fleet_trip",String.class)).isEqualTo("IN_TRANSIT");
         assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_pda_pick",Long.class)).isEqualTo(2);
-        assertThat(f.f.db.queryForObject("SELECT result_json FROM ll_dispatch_command WHERE idempotency_key='complete'",String.class)).contains("DELIVERING");
+        assertThat(f.f.db.queryForObject("SELECT result_json FROM ll_dispatch_command WHERE idempotency_key='complete'",String.class)).contains("AFTER_LOADING");
         var replay=f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("complete")));
         assertThat(replay.replayed()).isTrue();assertThat(replay.recordVersion()).isEqualTo(result.recordVersion());assertThat(replay.result()).isEqualTo(result.result());
-        assertThat(f.f.tx.execute(s->f.f.service.command(f.f.actor,f.number,"complete")).stage()).isEqualTo(Stage.DELIVERING);
+        assertThat(f.f.tx.execute(s->f.f.service.command(f.f.actor,f.number,"complete")).stage()).isEqualTo(Stage.AFTER_LOADING);
         verify(f.delivery,times(1)).prepareForDeparture(any(),any(),anyString());verify(f.sourceWorkflow,times(1)).departWholeSources(any(),any(),any(),any());
         assertThat(f.f.service.actions(f.f.actor,f.f.repository.find(f.number))).doesNotContainKeys(Action.ARRANGE_DELIVERY,Action.DEPART);
         assertThatThrownBy(()->f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("stale-new")))).hasMessageContaining("版本或审核阶段");
     }
 
-    /** 任一后续步骤失败都恢复装车中，已提交的真实拣货保持，不留下中间装车或子单。 */
-    @Test void preparationAndDepartureFailuresRollBackTheEntireLoadingCommand() throws Exception {
+    /** 派送失败回滚第五张绑定，保留已确认装车和前四张资料，原文件可重试。 */
+    @Test void preparationAndDepartureFailuresRollBackTheFifthPhoto() throws Exception {
         authorize();
         for(boolean failPreparation:List.of(true,false)) {
             var f=new Fixture();
+            f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("complete")));
+            for(int i=0;i<4;i++)f.bind(i,f.f.actor);
             if(failPreparation)doThrow(new IllegalStateException("模拟单据准备失败")).when(f.delivery).prepareForDeparture(any(),any(),anyString());
             else doThrow(new IllegalStateException("模拟来源发运失败")).when(f.sourceWorkflow).departWholeSources(any(),any(),any(),any());
-            assertThatThrownBy(()->f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("failed")))).isInstanceOf(IllegalStateException.class);
-            var row=f.f.repository.find(f.number);assertThat(row.getStage()).isEqualTo("LOADING");assertThat(row.getRecordVersion()).isEqualTo(f.version);
-            assertThat(row.getLoadingCompletionHash()).isNull();assertThat(row.getArrangementKey()).isNull();assertThat(row.getDepartedAt()).isNull();
+            assertThatThrownBy(()->f.bind(4,f.f.actor)).isInstanceOf(IllegalStateException.class);
+            var row=f.f.repository.find(f.number);assertThat(row.getStage()).isEqualTo("AFTER_LOADING");assertThat(row.getRecordVersion()).isEqualTo(f.version+1);
+            assertThat(row.getLoadingCompletionHash()).isNotNull();
+            assertThat(f.documents.get(f.f.actor,f.number).photos()).hasSize(4);assertThat(row.getArrangementKey()).isNull();assertThat(row.getDepartedAt()).isNull();
             assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_outbound_order",Long.class)).isZero();
             assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_delivery_order",Long.class)).isZero();
-            assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_command WHERE action IN ('LOADING_COMPLETE','ARRANGE_DELIVERY','DEPART')",Long.class)).isZero();
+            assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_command WHERE action IN ('ARRANGE_DELIVERY','DEPART')",Long.class)).isZero();
             assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_pda_pick",Long.class)).isEqualTo(2);
             assertThat(f.f.db.queryForObject("SELECT status FROM ll_fleet_trip",String.class)).isEqualTo("PLANNED");
         }
@@ -68,12 +87,12 @@ class DispatchLoadingDeparturePersistenceTest {
         var bad=new DispatchCommands.LoadingComplete(f.version,"bad-manifest","changed",f.measurements,null);
         assertThatThrownBy(()->f.f.tx.execute(s->f.service.complete(pda,f.number,bad))).hasMessageContaining("真实装载清单已变化");
         verify(f.delivery,never()).prepareForDeparture(any(),any(),anyString());
-        var result=f.f.tx.execute(s->f.service.complete(pda,f.number,f.request("pda")));assertThat(result.stage()).isEqualTo(Stage.DELIVERING);
+        var result=f.f.tx.execute(s->f.service.complete(pda,f.number,f.request("pda")));assertThat(result.stage()).isEqualTo(Stage.AFTER_LOADING);
         SecurityContextHolder.getContext().setAuthentication(new TestingAuthenticationToken("picker","","ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR"));
         assertThatThrownBy(()->f.f.tx.execute(s->f.service.complete(pda,f.number,f.request("pda")))).hasMessageContaining("装车完成权限");
     }
 
-    /** 同一版本后台/PDA同时确认只有一条完整链提交，不会产生半车或重复派送。 */
+    /** 同一版本后台/PDA同时确认只有一次装车提交，资料未齐不发车。 */
     @Test void concurrentAdminAndPdaCompleteOnlyOneDeparture() throws Exception {
         authorize();var f=new Fixture();var start=new CountDownLatch(1);var workers=Executors.newFixedThreadPool(2);
         try {
@@ -81,20 +100,99 @@ class DispatchLoadingDeparturePersistenceTest {
             var b=workers.submit(()->f.tryComplete(start,new Actor("picker",ActorMode.PDA,"9"),"pda"));
             start.countDown();assertThat(List.of(a.get(25,TimeUnit.SECONDS),b.get(25,TimeUnit.SECONDS))).containsExactlyInAnyOrder(true,false);
         } finally {workers.shutdownNow();}
-        assertThat(f.f.repository.find(f.number).getStage()).isEqualTo("DELIVERING");
-        verify(f.delivery,times(1)).prepareForDeparture(any(),any(),anyString());verify(f.sourceWorkflow,times(1)).departWholeSources(any(),any(),any(),any());
+        assertThat(f.f.repository.find(f.number).getStage()).isEqualTo("AFTER_LOADING");
+        verify(f.delivery,never()).prepareForDeparture(any(),any(),anyString());verify(f.sourceWorkflow,never()).departWholeSources(any(),any(),any(),any());
     }
 
-    /** 仅配置装车完成及PDA既有角色权限，不授予人工派送、发车权限。 */
+    /** 装车中可上传，装车前与跨仓拒绝，平台只读权限不能保存照片。 */
+    @Test void loadingDocumentsEnforceStageWarehouseAndWritePermission() throws Exception {
+        authorize();var f=new Fixture();
+        assertThat(f.documents.get(f.f.actor,f.number).stage()).isEqualTo("LOADING");
+        f.f.db.update("UPDATE ll_dispatch_order SET stage='BEFORE_LOADING'");
+        assertThatThrownBy(()->f.documents.get(f.f.actor,f.number)).hasMessageContaining("进入装车中后");
+        f.f.db.update("UPDATE ll_dispatch_order SET stage='LOADING'");
+        f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("complete")));
+        assertThatThrownBy(()->f.documents.get(new Actor("picker",ActorMode.PDA,"99"),f.number)).hasMessageContaining("当前绑定仓");
+        assertThatThrownBy(()->f.f.tx.execute(s->f.documents.bind(f.f.actor,f.number,null,new BindPhoto("0","wrong-slot","1000")))).hasMessageContaining("装车照片框");
+        SecurityContextHolder.getContext().setAuthentication(new TestingAuthenticationToken("reader","","platform:overseas-warehouse:dispatch:list"));
+        assertThat(f.documents.get(f.f.actor,f.number).editable()).isFalse();
+        assertThatThrownBy(()->f.bind(0,f.f.actor)).hasMessageContaining("无装车资料操作权限");
+    }
+
+    /** 两端同版本竞争第五张，仅一个绑定和一次真实派送成功。 */
+    @Test void concurrentFifthPhotoCannotDispatchTwice() throws Exception {
+        authorize();var f=new Fixture();f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("complete")));
+        for(int i=0;i<4;i++)f.bind(i,f.f.actor);
+        var start=new CountDownLatch(1);var workers=Executors.newFixedThreadPool(2);
+        try {
+            var results=new ArrayList<Future<Boolean>>();
+            for(String key:List.of("admin-last","pda-last"))results.add(workers.submit(()->{
+                authorize();try {start.await(5,TimeUnit.SECONDS);var actor=key.startsWith("pda")?new Actor("picker",ActorMode.PDA,"9"):f.f.actor;
+                    f.f.tx.execute(s->f.documents.bind(actor,f.number,Slot.RECEIPT,new BindPhoto("4",key,"1004")));return true;
+                }catch(com.baiyue.common.core.exception.BizException expected){return false;}
+                finally {SecurityContextHolder.clearContext();}
+            }));
+            start.countDown();assertThat(List.of(results.get(0).get(25,TimeUnit.SECONDS),results.get(1).get(25,TimeUnit.SECONDS))).containsExactlyInAnyOrder(true,false);
+        } finally {workers.shutdownNow();}
+        verify(f.delivery,times(1)).prepareForDeparture(any(),any(),anyString());
+        assertThat(f.documents.get(f.f.actor,f.number).photos()).hasSize(5);
+        assertThat(f.f.repository.find(f.number).getStage()).isEqualTo("DELIVERING");
+    }
+
+    /** 资料先齐不能提前发车；确认装车后直接派送，原键返回相同最终结果。 */
+    @Test void photosReadyBeforeLoadingConfirmationDepartAndReplayOnce() throws Exception {
+        authorize();var f=new Fixture();
+        for(int i=0;i<5;i++)assertThat(f.bind(i,f.f.actor).stage()).isEqualTo("LOADING");
+        verify(f.delivery,never()).prepareForDeparture(any(),any(),anyString());
+        var result=f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("ready-complete")));
+        assertThat(result.action()).isEqualTo(Action.LOADING_COMPLETE);
+        assertThat(result.stage()).isEqualTo(Stage.DELIVERING);assertThat(result.counts().shippedPackageCount()).isEqualTo(8);
+        assertThat(result.result()).isInstanceOf(DispatchResults.Loaded.class);
+        var replay=f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("ready-complete")));
+        assertThat(replay.replayed()).isTrue();assertThat(replay.stage()).isEqualTo(Stage.DELIVERING);
+        assertThat(replay.recordVersion()).isEqualTo(result.recordVersion());assertThat(replay.result()).isEqualTo(result.result());
+        assertThat(f.f.tx.execute(s->f.f.service.command(f.f.actor,f.number,"ready-complete")).stage()).isEqualTo(Stage.DELIVERING);
+        verify(f.delivery,times(1)).prepareForDeparture(any(),any(),anyString());
+        verify(f.sourceWorkflow,times(1)).departWholeSources(any(),any(),any(),any());
+    }
+
+    /** 资料先齐时派送失败回滚本次装车确认，五张已保存照片保留供原请求重试。 */
+    @Test void readyDocumentsSurviveFailedLoadingAndOriginalRequestCanRetry() throws Exception {
+        authorize();var f=new Fixture();for(int i=0;i<5;i++)f.bind(i,f.f.actor);
+        doThrow(new IllegalStateException("模拟发运失败")).when(f.sourceWorkflow).departWholeSources(any(),any(),any(),any());
+        assertThatThrownBy(()->f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("retry-ready")))).hasMessageContaining("模拟发运失败");
+        assertThat(f.f.repository.find(f.number).getStage()).isEqualTo("LOADING");
+        assertThat(f.documents.get(f.f.actor,f.number).complete()).isTrue();
+        assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_delivery_order",Long.class)).isZero();
+        assertThat(f.f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_command WHERE idempotency_key='retry-ready'",Long.class)).isZero();
+        doNothing().when(f.sourceWorkflow).departWholeSources(any(),any(),any(),any());
+        assertThat(f.f.tx.execute(s->f.service.complete(f.f.actor,f.number,f.request("retry-ready"))).stage()).isEqualTo(Stage.DELIVERING);
+    }
+
+    /** 最后一张照片与装车确认同时提交，不论谁先拿父锁均只发车一次。 */
+    @Test void lastPhotoAndLoadingConfirmationCanFinishConcurrently() throws Exception {
+        authorize();var f=new Fixture();for(int i=0;i<4;i++)f.bind(i,f.f.actor);
+        var start=new CountDownLatch(1);var workers=Executors.newFixedThreadPool(2);
+        try {
+            var load=workers.submit(()->f.tryComplete(start,f.f.actor,"concurrent-load"));
+            var photo=workers.submit(()->{authorize();try {start.await(5,TimeUnit.SECONDS);return f.bind(4,new Actor("picker",ActorMode.PDA,"9"));}finally{SecurityContextHolder.clearContext();}});
+            start.countDown();assertThat(load.get(25,TimeUnit.SECONDS)).isTrue();assertThat(photo.get(25,TimeUnit.SECONDS)).isNotNull();
+        } finally {workers.shutdownNow();}
+        assertThat(f.f.repository.find(f.number).getStage()).isEqualTo("DELIVERING");
+        verify(f.delivery,times(1)).prepareForDeparture(any(),any(),anyString());
+        verify(f.sourceWorkflow,times(1)).departWholeSources(any(),any(),any(),any());
+    }
+
+    /** 配置资料与装车权限及PDA既有角色，不授予人工派送、发车权限。 */
     private static void authorize(){SecurityContextHolder.getContext().setAuthentication(new TestingAuthenticationToken("operator","",
-        "platform:overseas-warehouse:dispatch:loading-complete","lastleg:pda:operate","ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR"));}
+        "platform:overseas-warehouse:dispatch:list","platform:overseas-warehouse:dispatch:edit","platform:overseas-warehouse:dispatch:loading-complete","lastleg:pda:operate","ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR"));}
 
     /** 主流程与发车使用真实SQL，派送提供者受控写入真实子单来验证共同回滚。 */
     private static final class Fixture {
         final DispatchAggregatePersistenceTest.Fixture f=new DispatchAggregatePersistenceTest.Fixture();
         final DispatchDeliveryPort delivery=mock(DispatchDeliveryPort.class);
         final DispatchPdaWorkflowService sourceWorkflow=mock(DispatchPdaWorkflowService.class);
-        final DispatchLoadingDepartureService service;final String number;final long version;final String manifest;
+        final DispatchLoadingDepartureService service;final DispatchLoadingDocumentService documents;final String number;final long version;final String manifest;
         final List<LoadingMeasurement> measurements;
         /** 创建两客户货物并走真实两级审核、真实拣货归属，不伪造已装车状态。 */
         Fixture() throws Exception {
@@ -126,7 +224,23 @@ class DispatchLoadingDeparturePersistenceTest {
             var hashes=new DispatchCommandHasher(f.json);
             var sources=new DispatchSourceRepository(mock(DispatchCandidateMapper.class),mock(ReturnDispatchCandidateMapper.class),f.session.getMapper(DispatchSourceMapper.class));
             var departure=new DispatchDepartureService(f.service,f.repository,sources,delivery,sourceWorkflow,f.fleet,ledger,hashes,f.json);
-            service=new DispatchLoadingDepartureService(f.service,delivery,departure,ledger,hashes);
+            f.session.getConfiguration().addMapper(OwnedBusinessMapper.class);
+            String schema=Files.readString(Path.of("src/main/resources/db/lastleg.sql"));
+            for(String suffix:List.of("record","command","history")) {
+                var matcher=Pattern.compile("(?s)CREATE TABLE IF NOT EXISTS ll_fleet_owned_business_"+suffix+" \\(.*?;").matcher(schema);
+                assertThat(matcher.find()).isTrue();
+                f.db.execute(matcher.group().replace(" JSON"," LONGTEXT").replace(" COLLATE utf8mb4_bin","").replaceFirst("(?s) ENGINE=InnoDB.*?;$",";"));
+            }
+            var records=new OwnedBusinessRepository(f.session.getMapper(OwnedBusinessMapper.class),mock(OwnedBusinessQueryMapper.class));
+            var codec=new OwnedBusinessSupport(f.json);var files=mock(OwnedBusinessFileGateway.class);
+            when(files.metadata(anyLong(),any(),anyLong())).thenAnswer(call->new OwnedBusinessFileGateway.Evidence(call.getArgument(2),"loading.png","image/png",12,"2026-10-21T00:00:00Z"));
+            var photos=new DispatchLoadingPhotoAdapter(records,new OwnedBusinessCommandService(records,codec),new OwnedBusinessProjection(codec),codec,files);
+            service=new DispatchLoadingDepartureService(f.service,delivery,departure,ledger,hashes,photos);
+            documents=new DispatchLoadingDocumentService(f.service,service,photos);
+        }
+        /** 每张照片保留独立版本与幂等键，复用真实附加记录保存事务。 */
+        Documents bind(int index,Actor actor) {
+            return f.tx.execute(s->documents.bind(actor,number,DispatchLoadingDocumentService.SLOTS.get(index),new BindPhoto(Integer.toString(index),"photo-bind-"+index,Long.toString(1000L+index))));
         }
         /** 每次请求沿用最初真实测量和版本，便于验证竞争及原键恢复。 */
         DispatchCommands.LoadingComplete request(String key){return new DispatchCommands.LoadingComplete(version,key,manifest,measurements,"实装发车");}

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/service/DispatchPickingPersistenceTest.java

@@ -23,6 +23,44 @@ import static org.mockito.Mockito.*;
 
 /** 根版本、幂等、真实客户作业与扫码持久化；库存/归属应用命令在此明确模拟，另由原域直接测试验证。 */
 class DispatchPickingPersistenceTest {
+    /** 数量可自然同步不代表能接管其他车的实际托盘。 */
+    @Test void receivedPalletClaimedByAnotherDispatchCannotBePicked() throws Exception {
+        var fixture=new Picking(true);fixture.receivedPlans(9,11);
+        fixture.f.db.update("UPDATE ll_dispatch_physical_pallet_lock SET dispatch_order_id=999 WHERE warehouse_pallet_id=501");
+        assertThatThrownBy(()->fixture.f.tx.execute(s->fixture.service.pick(fixture.actor,fixture.number,fixture.item,
+            new DispatchCommands.Pick(fixture.version,"occupied-pallet",11L,9,0,null,null))))
+            .isInstanceOf(com.baiyue.common.core.exception.BizException.class).hasMessageContaining("占用");
+        verify(fixture.inventory,never()).ship(any(),any(),any());
+        assertThat(fixture.f.db.queryForList("SELECT package_count FROM ll_dispatch_item ORDER BY customer_id",Integer.class)).containsExactly(10,10);
+    }
+    /** 预排两托10+10、实收9+11，首次扫码同步真实数量并保留原审核，原键重放不重复扣货。 */
+    @Test void receivedPalletCountsReplaceEstimatesAtomically() throws Exception {
+        var fixture=new Picking(true);fixture.receivedPlans(9,11);
+        var firstRequest=new DispatchCommands.Pick(fixture.version,"received-nine",11L,9,0,null,null);
+        var first=fixture.f.tx.execute(s->fixture.service.pick(fixture.actor,fixture.number,fixture.item,firstRequest));
+        assertThat(fixture.f.db.queryForList("SELECT package_count FROM ll_dispatch_item ORDER BY customer_id",Integer.class)).containsExactly(9,11);
+        assertThat(fixture.f.db.queryForObject("SELECT package_count FROM ll_dispatch_order",Integer.class)).isEqualTo(20);
+        assertThat(fixture.f.db.queryForObject("SELECT review_state FROM ll_dispatch_order",String.class)).isEqualTo("APPROVED");
+        var replay=fixture.f.tx.execute(s->fixture.service.pick(fixture.actor,fixture.number,fixture.item,firstRequest));
+        assertThat(replay.replayed()).isTrue();
+        var second=fixture.f.tx.execute(s->fixture.service.pick(fixture.actor,fixture.number,fixture.secondItem,
+            new DispatchCommands.Pick(first.recordVersion(),"received-eleven",12L,11,0,null,null)));
+        assertThat(((DispatchResults.Picked)second.result()).pickingReconciled()).isTrue();
+        verify(fixture.inventory,times(2)).ship(anyString(),eq("picker"),any());
+        assertThat(fixture.f.db.queryForObject("SELECT SUM(available_packages) FROM ll_inventory_position",Long.class)).isZero();
+    }
+
+    /** 实收绑定后扣货失败必须同时回滚数量、绑定、总数和原审核。 */
+    @Test void receivedQuantityAndBindingRollBackWhenStockWriteFails() throws Exception {
+        var fixture=new Picking(true);fixture.receivedPlans(8,11);
+        doThrow(new IllegalStateException("库存命令失败")).when(fixture.inventory).ship(anyString(),anyString(),any());
+        assertThatThrownBy(()->fixture.f.tx.execute(s->fixture.service.pick(fixture.actor,fixture.number,fixture.item,
+            new DispatchCommands.Pick(fixture.version,"receipt-rollback",11L,8,0,null,null)))).isInstanceOf(IllegalStateException.class);
+        assertThat(fixture.f.db.queryForList("SELECT package_count FROM ll_dispatch_item ORDER BY customer_id",Integer.class)).containsExactly(10,10);
+        assertThat(fixture.f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_item WHERE warehouse_pallet_id IS NOT NULL",Long.class)).isZero();
+        assertThat(fixture.f.db.queryForObject("SELECT package_count FROM ll_dispatch_order",Integer.class)).isEqualTo(20);
+        assertThat(fixture.f.db.queryForObject("SELECT record_version FROM ll_dispatch_order",Long.class)).isEqualTo(fixture.version);
+    }
     /** 原键在后续版本仍恢复原结果，不能重复调用SHIP或创建第二条真实扫码。 */
     @Test void sameKeyShipsOnceAndLastPickDoesNotConfirmLoading() throws Exception {
         var fixture=new Picking();var request=new DispatchCommands.Pick(fixture.version,"pda-pick-original",11L,3,6,null,"实际扫码");
@@ -68,6 +106,7 @@ class DispatchPickingPersistenceTest {
         final DispatchAggregatePersistenceTest.Fixture f=new DispatchAggregatePersistenceTest.Fixture();
         final InventoryCommandService inventory=mock(InventoryCommandService.class);final DispatchPickOrderAttributionService attribution=mock(DispatchPickOrderAttributionService.class);
         final DispatchPickingService service;final String number;final long item,version;final Long secondItem;
+        final DispatchSourceRepository sources;
         final DispatchContracts.Actor actor=new DispatchContracts.Actor("picker",ActorMode.PDA,"9");
         /** 建立真实客户来源、作业表、扫码表与可以参与回滚的库存行。 */
         Picking() throws Exception {this(false);}
@@ -94,10 +133,33 @@ class DispatchPickingPersistenceTest {
             doAnswer(call->{com.baiyue.lastleg.inventory.command.dto.InventoryCommandRequests.Move move=call.getArgument(2);f.db.update("UPDATE ll_inventory_position SET available_packages=available_packages-?,version=version+1 WHERE id=? AND customer_id=?",move.packages(),move.positionId(),call.getArgument(0));return null;}).when(inventory).ship(anyString(),eq("picker"),any());
             doAnswer(call->{String customer=call.getArgument(0);DispatchPdaPick pick=call.getArgument(1);long order="101".equals(customer)?9001L:9002L;long receipt="101".equals(customer)?1L:2L;f.db.update("INSERT INTO ll_dispatch_pda_pick_order(id,customer_id,pick_id,order_id,receipt_id,packages,product_quantity)VALUES(?,?,?,?,?,?,?)",pick.getId(),customer,pick.getId(),order,receipt,pick.getPackages(),pick.getProductQuantity());return List.of(new DispatchPickOrderAttributionService.OrderPackages(order,pick.getPackages()));})
                 .when(attribution).attribute(anyString(),any(DispatchPdaPick.class),isNull());
-            var sources=new DispatchSourceRepository(mock(DispatchCandidateMapper.class),mock(ReturnDispatchCandidateMapper.class),f.session.getMapper(DispatchSourceMapper.class));
+            sources=spy(new DispatchSourceRepository(mock(DispatchCandidateMapper.class),mock(ReturnDispatchCandidateMapper.class),f.session.getMapper(DispatchSourceMapper.class)));
             var commands=new DispatchCommandLedger(new DispatchCommandRepository(f.session.getMapper(DispatchCommandMapper.class)),new DispatchCommandCodec(f.json));
             service=new DispatchPickingService(f.service,f.repository,sources,new DispatchPickingRepository(session.getMapper(DispatchPdaTaskMapper.class),session.getMapper(DispatchPdaPickMapper.class),session.getMapper(InventoryPositionMapper.class),session.getMapper(DispatchItemMapper.class)),attribution,inventory,mock(ReturnRelabelDispatchStock.class),commands,new DispatchCommandHasher(f.json),f.json);
             for(var field:List.of("physicalClaims","relabelSources","sourceRules"))org.springframework.test.util.ReflectionTestUtils.setField(service,field,org.springframework.test.util.ReflectionTestUtils.getField(f.service,field));
+            org.springframework.test.util.ReflectionTestUtils.setField(service,"fleet",f.fleet);
+        }
+        /** 来源查询在此隔离，实收同步仍使用真实主单、明细、库存及车次事务。 */
+        void receivedPlans(int first,int second) {
+            f.db.update("UPDATE ll_dispatch_item SET warehouse_pallet_id=NULL,source_stage='PLAN',package_count=10");
+            f.db.update("UPDATE ll_dispatch_order SET package_count=20");
+            var rules=(DispatchService)org.springframework.test.util.ReflectionTestUtils.getField(service,"sourceRules");
+            for(int n=1;n<=2;n++) {
+                long plan=n,pallet=500+n;String customer=n==1?"101":"102";int count=n==1?first:second;
+                f.candidates.get(plan).packageCount(count);
+                f.db.update("UPDATE ll_inventory_position SET available_packages=? WHERE id=?",count,10+n);
+                doReturn(List.of(f.candidates.get(plan))).when(sources).selectedPlan(customer,plan);
+                doReturn(true).when(sources).receivedPlanCompleted(customer,plan);
+                doReturn(List.of(9000+plan)).when(sources).sourceOrders(customer,null,plan);
+                doReturn(List.of(9000+plan)).when(sources).sourceOrders(customer,pallet,plan);
+                doReturn(plan).when(sources).lockPlan(customer,plan);
+                doReturn(1).when(sources).materialize(anyLong(),eq(customer),eq(plan),eq(pallet),anyLong(),any());
+            }
+            when(rules.selectionGroup(anyString(),any())).thenAnswer(call->{
+                var selected=(DispatchCommands.CargoSelection)call.getArgument(1);long plan=selected.planPalletId();var row=f.candidates.get(plan);
+                return new DispatchPlanningModels.SelectionGroup("group","version",List.of(new DispatchPlanningModels.SelectionGroupSource(
+                    selected,"PLAN:"+plan,row.customerId(),row.customerName(),"INBOUND_PLAN","PLAN-"+plan,row.packageCount())),List.of(),true,List.of());
+            });
         }
         /** 使用实际实体属性建最小测试表，不修改或声称验证正式DDL。 */
         private static String sqlType(Class<?> type){return type==Long.class?"BIGINT":type==Integer.class?"INT":type==LocalDateTime.class?"TIMESTAMP(3)":"VARCHAR(20000)";}

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/service/DispatchPlanPdaReadPersistenceTest.java

@@ -17,6 +17,22 @@ import static org.mockito.ArgumentMatchers.*;
 
 /** 真实PDA任务投影衔接原计划；来源提供者隔离，GET不得写绑定或库存。 */
 class DispatchPlanPdaReadPersistenceTest {
+    /** 完成状态查询走真实Mapper，未完成或其他客户的计划不能被当作本托实收。 */
+    @Test void completionGateUsesOriginalCustomerAndPlan() throws Exception {
+        var f=new Fixture();
+        f.f.db.execute("CREATE TABLE ll_inbound_plan(id BIGINT,customer_id VARCHAR(64),status VARCHAR(64))");
+        f.f.db.execute("CREATE TABLE ll_inbound_plan_pallet(id BIGINT,plan_id BIGINT,customer_id VARCHAR(64))");
+        f.f.db.update("INSERT INTO ll_inbound_plan VALUES(1,'101','IN_PROGRESS')");
+        f.f.db.update("INSERT INTO ll_inbound_plan_pallet VALUES(2,1,'101')");
+        var mapper=f.f.session.getMapper(com.baiyue.lastleg.dispatch.mapper.DispatchSourceMapper.class);
+        assertThat(mapper.receivedPlanCompleted("101",2L)).isZero();
+        for(var status:List.of("COMPLETED","PENDING_RECONCILIATION")) {
+            f.f.db.update("UPDATE ll_inbound_plan SET status=?",status);
+            assertThat(mapper.receivedPlanCompleted("101",2L)).isOne();
+            assertThat(mapper.receivedPlanCompleted("other",2L)).isZero();
+            assertThat(mapper.receivedPlanCompleted("101",3L)).isZero();
+        }
+    }
     /** 已实收原计划直接提供首拣仓位，查询不推进原车版本或写入实托。 */
     @Test void receivedPlanExposesPositionWithoutMaterializing() throws Exception {
         var f=new Fixture();var before=f.dbState();
@@ -28,15 +44,23 @@ class DispatchPlanPdaReadPersistenceTest {
         verify(f.sources,never()).materialize(anyLong(),anyString(),anyLong(),anyLong(),anyLong(),any());
         verify(f.rules,never()).lockExecutionSources(anyString(),anyList());
     }
-    /** 在途、预留托盘和实收数量漂移均不成为可拣库存。 */
+    /** 在途和来源身份变化均不成为可拣库存。 */
     @Test void unreceivedOrChangedPlanHasNoPositions() throws Exception {
         var f=new Fixture();var row=f.f.candidates.get(1L);
         row.sourceStage("PLAN");assertThat(f.read().items().get(0).positions()).isEmpty();
-        row.sourceStage("RECEIVED");row.packageCount(2);assertThat(f.read().items().get(0).positions()).isEmpty();
-        row.packageCount(3);row.overseasWarehouseId("99");assertThat(f.read().items().get(0).positions()).isEmpty();
+        row.sourceStage("RECEIVED");row.overseasWarehouseId("99");assertThat(f.read().items().get(0).positions()).isEmpty();
         row.overseasWarehouseId("9");row.customerId("other");assertThat(f.read().items().get(0).positions()).isEmpty();
         verify(f.sources,never()).stock(anyString(),anyLong(),anyBoolean());
     }
+    /** 自动预分配的10+10不约束实收9+11；查询给出实际数量且不改数据库。 */
+    @Test void plannedTenAndTenProjectsReceivedNineAndEleven() throws Exception {
+        var f=new Fixture(true);var before=f.dbState();
+        var task=f.read();
+        assertThat(task.items()).extracting(DispatchViews.PdaItem::scheduledPackages).containsExactly(9L,11L);
+        assertThat(task.items()).allSatisfy(i->assertThat(i.positions()).isNotEmpty());
+        assertThat(task.counts().packageCount()).isEqualTo(20);
+        assertThat(f.dbState()).isEqualTo(before);
+    }
     /** 原计划不能吸收新的订单或未经原车审核的同托来源。 */
     @Test void changedOrdersOrAdditionalPalletSourceBlocksFirstPick() throws Exception {
         var f=new Fixture();
@@ -53,11 +77,18 @@ class DispatchPlanPdaReadPersistenceTest {
     @Test void actualStockMustMatchWarehousePalletAndQuantity() throws Exception {
         var f=new Fixture();
         for(var stock:List.of(new Stock(11,21,501L,"99",3,0,0,0,1),
-            new Stock(11,21,502L,"9",3,0,0,0,1),new Stock(11,21,501L,"9",2,0,0,0,1))) {
+            new Stock(11,21,502L,"9",3,0,0,0,1),new Stock(11,21,501L,"9",2,0,0,0,1),
+            new Stock(11,21,501L,"9",3,1,0,0,1),new Stock(11,21,501L,"9",3,0,1,0,1))) {
             when(f.sources.stock("101",501L,false)).thenReturn(List.of(stock));
             assertThat(f.read().items().get(0).positions()).isEmpty();
         }
     }
+    /** 收货尚未结束时不把当前部分实收数量当成整托最终数量。 */
+    @Test void receivingPlanDoesNotExposePartialPallet() throws Exception {
+        var f=new Fixture();when(f.sources.receivedPlanCompleted("101",1L)).thenReturn(false);
+        assertThat(f.read().items().get(0).positions()).isEmpty();
+        verify(f.sources,never()).stock(anyString(),anyLong(),anyBoolean());
+    }
     /** 复用真实排车及PDA Mapper，模拟原计划来源快照。 */
     private static final class Fixture {
         final DispatchAggregatePersistenceTest.Fixture f=new DispatchAggregatePersistenceTest.Fixture();
@@ -65,9 +96,13 @@ class DispatchPlanPdaReadPersistenceTest {
         final DispatchService rules=mock(DispatchService.class);
         final DispatchPdaQueryService queries;final String number;
         /** 原车已审核，只清除自然收货尚未补写的实托字段。 */
-        Fixture() throws Exception {
-            var selection=f.source(1,"101",501,"ONT8",3);
-            var created=f.tx.execute(s->f.service.create(f.actor,f.configured("plan-pda-read",List.of(selection))));
+        Fixture() throws Exception {this(false);}
+        /** 同一客户两托先预排再实收，模拟计划拆分与真实入托数量不同。 */
+        Fixture(boolean twoPallets) throws Exception {
+            var selection=f.source(1,"101",501,"ONT8",twoPallets?10:3);
+            var selections=new java.util.ArrayList<DispatchCommands.CargoSelection>();selections.add(selection);
+            if(twoPallets)selections.add(f.source(2,"101",502,"ONT8",10));
+            var created=f.tx.execute(s->f.service.create(f.actor,f.configured("plan-pda-read",selections)));
             f.approve(created);number=created.dispatchNo();
             f.db.update("UPDATE ll_dispatch_item SET warehouse_pallet_id=NULL,source_stage='PLAN'");
             f.db.execute("CREATE TABLE ll_inventory_position(id BIGINT,customer_id VARCHAR(64),balance_id BIGINT,pallet_id BIGINT,overseas_warehouse_id VARCHAR(64),available_packages BIGINT,hold_packages BIGINT,allocated_packages BIGINT,picked_packages BIGINT)");
@@ -76,12 +111,28 @@ class DispatchPlanPdaReadPersistenceTest {
             queries=new DispatchPdaQueryService(new DispatchPdaReadRepository(new SqlSessionTemplate(factory.getObject()).getMapper(DispatchWholePdaReadMapper.class)),f.service);
             ReflectionTestUtils.setField(queries,"sources",sources);ReflectionTestUtils.setField(queries,"sourceRules",rules);
             when(sources.selectedPlan("101",1L)).thenReturn(List.of(f.candidates.get(1L)));
+            when(sources.receivedPlanCompleted(anyString(),anyLong())).thenReturn(true);
             when(sources.sourceOrders("101",null,1L)).thenReturn(List.of(9001L));
             when(sources.sourceOrders("101",501L,1L)).thenReturn(List.of(9001L));
             when(sources.stock("101",501L,false)).thenReturn(List.of(new Stock(11,21,501L,"9",3,0,0,0,1)));
             when(rules.selectionGroup(anyString(),any())).thenReturn(new DispatchPlanningModels.SelectionGroup(
                 "group","version",List.of(new DispatchPlanningModels.SelectionGroupSource(
                     selection,"PLAN:1","101","测试客户","INBOUND_PLAN","PLAN-1",3)),List.of(),true,List.of()));
+            if(twoPallets) {
+                for(int n=1;n<=2;n++) {
+                    long plan=n,pallet=500+n;int count=n==1?9:11;
+                    f.candidates.get(plan).packageCount(count);
+                    when(sources.selectedPlan("101",plan)).thenReturn(List.of(f.candidates.get(plan)));
+                    when(sources.sourceOrders("101",null,plan)).thenReturn(List.of(9000+plan));
+                    when(sources.sourceOrders("101",pallet,plan)).thenReturn(List.of(9000+plan));
+                    when(sources.stock("101",pallet,false)).thenReturn(List.of(new Stock(10+n,20+n,pallet,"9",count,0,0,0,1)));
+                }
+                when(rules.selectionGroup(anyString(),any())).thenAnswer(call->{
+                    var selected=(DispatchCommands.CargoSelection)call.getArgument(1);long plan=selected.planPalletId();
+                    return new DispatchPlanningModels.SelectionGroup("group","version",List.of(new DispatchPlanningModels.SelectionGroupSource(
+                        selected,"PLAN:"+plan,"101","测试客户","INBOUND_PLAN","PLAN-"+plan,plan==1?9:11)),List.of(),true,List.of());
+                });
+            }
         }
         /** 读取正式PDA入口。 */
         DispatchViews.PdaTask read(){return f.tx.execute(s->queries.task(new DispatchContracts.Actor("picker",ActorMode.PDA,"9"),number));}

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/service/DispatchRegionalCandidatesTest.java

@@ -0,0 +1,47 @@
+package com.baiyue.lastleg.dispatch.service;
+
+import com.baiyue.lastleg.dispatch.mapper.DispatchCandidatePageMapper;
+import com.baiyue.lastleg.dispatch.port.DispatchContracts.Actor;
+import com.baiyue.lastleg.dispatch.port.DispatchPlanningModels.CandidateQuery;
+import com.baiyue.lastleg.dispatch.port.DispatchTypes.ActorMode;
+import org.apache.ibatis.session.Configuration;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.util.ReflectionTestUtils;
+import java.util.*;
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+/** 区域候选的读取范围与单仓写入职责分离，不依赖测试环境数据。 */
+class DispatchRegionalCandidatesTest {
+    /** 真实服务接受不指定仓的三种区域，保留服务端分页总数；非法仓和区域仍拒绝。 */
+    @Test void serviceAcceptsRegionalQueriesAndRejectsMalformedScopes() {
+        var sources=mock(DispatchService.class);var appointments=mock(DispatchAppointmentAllocations.class);
+        var service=new DispatchAggregateService(null,null,sources,null,null,null,new com.fasterxml.jackson.databind.ObjectMapper());
+        ReflectionTestUtils.setField(service,"appointments",appointments);
+        var actor=new Actor("7",ActorMode.PLATFORM,null);
+        when(sources.candidatePage(eq("7"),any())).thenReturn(new DispatchService.CandidatePage(List.of(),41));
+        when(sources.selectionGroups(List.of())).thenReturn(Map.of());when(appointments.candidates(List.of())).thenReturn(Map.of());
+        for(String tab:List.of("ALL","LAX","NYC")) {
+            var query=new CandidateQuery(null,null,null,null,null,null,2,20,tab);
+            var result=service.candidates(actor,query);
+            assertThat(result.total()).isEqualTo(41);assertThat(result.page()).isEqualTo(2);assertThat(result.pages()).isEqualTo(3);
+            verify(sources).candidatePage("7",query);
+        }
+        assertThatThrownBy(()->service.candidates(actor,new CandidateQuery("bad",null,null,null,null,null,1,20,"ALL"))).hasMessageContaining("起运仓筛选无效");
+        assertThatThrownBy(()->service.candidates(actor,new CandidateQuery(null,null,null,null,null,null,1,20,"bad"))).hasMessageContaining("仓库页签不合法");
+    }
+    /** 解析实际Mapper动态SQL，统计和分页采用相同区域条件，单仓消费者继续绑定真实仓。 */
+    @Test void countAndPageUseOptionalWarehouseAndTheSameRegionPredicate() {
+        var config=new Configuration();config.addMapper(DispatchCandidatePageMapper.class);
+        for(String method:List.of("count","page")) for(String tab:List.of("ALL","LAX","NYC")) for(String warehouse:List.of("ALL_WAREHOUSES","321")) {
+            var query=new CandidateQuery(warehouse.equals("321")?warehouse:null,null,null,null,null,null,1,20,tab);
+            var sql=config.getMappedStatement(DispatchCandidatePageMapper.class.getName()+"."+method).getBoundSql(Map.of("query",query,"offset",0)).getSql();
+            if(query.warehouseId()==null)assertThat(sql).doesNotContain("overseasWarehouseId=?");
+            else assertThat(sql).contains("overseasWarehouseId=?");
+            if(tab.equals("LAX"))assertThat(sql).contains("REGEXP 'lax|洛杉矶|los angeles'");
+            if(tab.equals("NYC"))assertThat(sql).contains("REGEXP 'nyc|jfk|");
+            if(tab.equals("ALL"))assertThat(sql).doesNotContain("REGEXP 'lax|", "REGEXP 'nyc|");
+            if(method.equals("page"))assertThat(sql).contains("LIMIT ? OFFSET ?");
+        }
+    }
+}

lastleg-service/src/test/java/com/baiyue/lastleg/fleet/ownedbusiness/DispatchVehicleDocumentTest.java

@@ -0,0 +1,76 @@
+package com.baiyue.lastleg.fleet.ownedbusiness;
+
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.lastleg.dispatch.port.DispatchDetailReader;
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessModels.*;
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessScope;
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessRows;
+import com.baiyue.lastleg.fleet.ownedbusiness.repository.OwnedBusinessRepository;
+import com.baiyue.lastleg.fleet.ownedbusiness.service.*;
+import com.baiyue.lastleg.fleet.outsourcedbusiness.service.OutsourcedBusinessService;
+import com.baiyue.lastleg.fleet.ownedbusiness.controller.DispatchVehicleDocumentController;
+import com.baiyue.lastleg.fleet.ownedbusiness.gateway.OwnedBusinessFileGateway;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.server.ResponseStatusException;
+import org.junit.jupiter.api.Test;
+import java.util.*;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+/** 排车资料复用同一车辆照片记录，不扩大旧入口或改变履约状态。 */
+class DispatchVehicleDocumentTest {
+    /** 无拼车和实际拼车都能在派送后读取；原车队分类和冻结装车门禁继续生效。 */
+    @Test void dispatchScopeAcceptsBothCargoGroupsOnlyAfterDeparture() {
+        var repo=mock(OwnedBusinessRepository.class);var codec=OwnedBusinessFixtures.codec();
+        var queries=new OwnedBusinessQueryService(repo,new OwnedBusinessProjection(codec),codec,mock(DispatchDetailReader.class));
+        var source=OwnedBusinessFixtures.source();when(repo.source(source.getDispatchNo())).thenReturn(source);
+        assertThrows(BizException.class,()->queries.requireScoped(source.getDispatchNo(),OwnedBusinessScope.DISPATCH));
+        for(boolean pooled:List.of(false,true))for(String stage:List.of("DELIVERING","DELIVERED")) {
+            source.setPooledCargo(pooled);source.setStage(stage);
+            assertSame(source,queries.requireScoped(source.getDispatchNo(),OwnedBusinessScope.DISPATCH));
+        }
+        assertThrows(BizException.class,()->queries.requireOwned(source.getDispatchNo()));
+        source.setOwnedLoadingCompletionHash("other-load");
+        assertThrows(BizException.class,()->queries.requireScoped(source.getDispatchNo(),OwnedBusinessScope.DISPATCH));
+        verify(repo,never()).update(any(),anyLong());
+    }
+    /** 排车入口只接受油耗图片；签收和装车文件仍走派送单，旧外配仍不能上传油耗。 */
+    @Test void scopesKeepIndependentWritePermissionsAndPhotoCategories() {
+        var scope=OwnedBusinessScope.DISPATCH;
+        assertEquals("platform:overseas-warehouse:dispatch:list",scope.listPermission());
+        assertEquals("platform:overseas-warehouse:dispatch:edit",scope.uploadPermission());
+        for(var slot:PhotoSlot.values()) {
+            if(slot.category().equals("FUEL")) { assertDoesNotThrow(()->scope.requireSlot(slot));assertThrows(BizException.class,()->OwnedBusinessScope.OUTSOURCED.requireSlot(slot)); }
+            else assertThrows(BizException.class,()->scope.requireSlot(slot));
+        }
+        var actor=new Actor("reader","只读",Set.of(scope.listPermission()));
+        var row=new OwnedBusinessProjection(OwnedBusinessFixtures.codec()).row(OwnedBusinessFixtures.source(),null,OwnedBusinessFixtures.cargo(),List.of(),actor,scope);
+        assertFalse(row.actions().upload().allowed());
+    }
+    /** 油耗与车队装车照片共存，排车补充油耗不破坏外配业务读取。 */
+    @Test void sharedFuelPhotosDoNotInvalidateOutsourcedProjection() {
+        var codec=OwnedBusinessFixtures.codec();var record=new OwnedBusinessRows.Record();record.setRecordVersion(3L);record.setArrivalsJson("[]");
+        record.setPhotosJson(codec.write(List.of(new Photo(PhotoSlot.FUEL_START,"FUEL","77","fuel.png","image/png","9","2026-10-21T00:00:00Z","2026-10-21T00:00:00Z"))));
+        var projection=new OwnedBusinessProjection(codec);var source=OwnedBusinessFixtures.source();source.setPooledCargo(true);source.setStage("DELIVERED");
+        var row=projection.row(source,record,OwnedBusinessFixtures.cargo(),List.of(),OwnedBusinessFixtures.actor(),OwnedBusinessScope.OUTSOURCED);
+        assertEquals(1,row.photoSummary().fuelCount());assertEquals("3",row.recordVersion());assertEquals(8L,source.getRecordVersion());assertEquals("DELIVERED",source.getStage());
+        assertEquals("77",projection.photos(record).get(0).fileId());
+        var queries=mock(OwnedBusinessQueryService.class);
+        when(queries.detail(any(),eq(source.getDispatchNo()),eq(OwnedBusinessScope.OUTSOURCED)))
+            .thenReturn(new Detail(row,null,List.of(),projection.photos(record)));
+        var outsourced=new OutsourcedBusinessService(queries,mock(OwnedBusinessRecordService.class),mock(OwnedBusinessPhotoService.class),projection,codec);
+        assertTrue(outsourced.detail(OwnedBusinessFixtures.actor(),source.getDispatchNo()).photos().isEmpty());
+    }
+    /** 新入口读写权限独立；服务层同样拒绝仅查看账号和车队权限绕入。 */
+    @Test void controllerAndPhotoServiceKeepDispatchWriteBoundary() throws Exception {
+        assertEquals("hasAuthority('platform:overseas-warehouse:dispatch:list')",Arrays.stream(DispatchVehicleDocumentController.class.getMethods())
+            .filter(m->m.getName().equals("get")).findFirst().orElseThrow().getAnnotation(PreAuthorize.class).value());
+        for(String name:List.of("upload","bind","recover"))assertEquals("hasAuthority('platform:overseas-warehouse:dispatch:edit')",Arrays.stream(DispatchVehicleDocumentController.class.getMethods())
+            .filter(m->m.getName().equals(name)).findFirst().orElseThrow().getAnnotation(PreAuthorize.class).value());
+        var queries=mock(OwnedBusinessQueryService.class);var repo=mock(OwnedBusinessRepository.class);var files=mock(OwnedBusinessFileGateway.class);var codec=OwnedBusinessFixtures.codec();
+        var service=new OwnedBusinessPhotoService(queries,mock(OwnedBusinessRecordService.class),repo,mock(OwnedBusinessCommandService.class),new OwnedBusinessProjection(codec),codec,files);
+        for(var actor:List.of(new Actor("read","只读",Set.of(OwnedBusinessScope.DISPATCH.listPermission())),OwnedBusinessFixtures.actor()))
+            assertThrows(ResponseStatusException.class,()->service.upload(actor,"PC-1",PhotoSlot.FUEL_START,"upload-original",null,OwnedBusinessScope.DISPATCH));
+        verifyNoInteractions(files,repo,queries);
+    }
+}

lastleg-service/src/test/java/com/baiyue/lastleg/service/LastlegOrderServiceTest.java

@@ -148,7 +148,7 @@ class LastlegOrderServiceTest {
         when(orders.countContainerPlans("BOOKING-1")).thenReturn(0L);
         when(orders.updateContainerExpectedWarehouseArrival("BOOKING-1", estimatedAt, 0)).thenReturn(2);
         when(orders.findContainerArrivalTimes(List.of("BOOKING-1"))).thenReturn(List.of(
-            new ContainerArrivalTimeView("BOOKING-1", estimatedAt, null, 1)));
+            new ContainerArrivalTimeView("BOOKING-1", estimatedAt, null, 1, 0)));
 
         ContainerArrivalTimeView result = service.changeExpectedWarehouseArrival("BOOKING-1", "arrival-1",
             new LastlegOrderRequests.ChangeExpectedWarehouseArrival(estimatedAt, 0, null), "admin");

scripts/AGENTS.md

@@ -11,7 +11,7 @@
 | 类别 | 正式入口 | 管理边界 |
 |---|---|---|
 | 本机重型检查限流 | `local-check.ps1` | 所有工作目录、对话共用两个用户级执行名额；PowerShell 7，状态/超时/并发与 Job Object 回收规则见外层 `docs/AI工程执行与协作约束.md`；只读状态不申请重型名额 |
-| 后端分层检查 | `backend-check.ps1` | 默认指定模块回归，支持测试源码编译和精确测试类；必填模块，自动接入重型限流；全量触发条件见后端根指引，参数及副作用见 README |
+| 后端分层检查 | `backend-check.ps1` | 局部任务显式选 Focused；模式缺省为 Module，不是日常必跑；必填模块并接入限流，范围见后端根指引，参数见 README |
 | 测试/灰度单票验收 | `prod-release-acceptance.mjs`、`prod-release-delivery-stage.mjs`、内部 `prod-release-order-stage.mjs` | 显式 test/gray、统一 Gateway/accessToken；同一票义乌到洛杉矶、前置同时核对东莞；full-flow 串行覆盖买单FBA正常链至签收回传及车次资源释放，保留分阶段入口与独立检查点；不调用测试造数模块，不创建账号/主档或删除数据；配置和边界见 README |
 | Admin 全量 HTTP 验证 | `admin-test-env-acceptance.mjs` | 通过显式环境文件运行统一 TEST Gateway/会话，拒绝旧海外网关参数；默认模块覆盖平台全链路，定向验证使用 `--modules`，模块注册和依赖以总入口及 `admin-test-env-modules/README.md` 为准 |
 | Client 全量 HTTP 验证 | `client-test-env-acceptance.mjs` | 通过显式环境文件运行统一 TEST Gateway/会话，拒绝旧海外网关参数；覆盖客户工作台完整链路，`client-phase2-test-env-acceptance.mjs` 只是入库测量与计费专项，不替代全量入口 |

scripts/README.md

@@ -458,13 +458,13 @@ Admin/Client HTTP 脚本的离线合同只验证脚本结构、参数和模块
 .\scripts\backend-check.ps1 -Modules order -Mode Compile
 # 开发迭代：精确类名，支持逗号分隔和全限定名。
 .\scripts\backend-check.ps1 -Modules common-core -Mode Focused -Tests ApiResponseTest
-# 单服务收尾：指定模块及上游依赖测试。
+# 服务级影响且定向覆盖不足：指定模块及上游依赖测试。
 .\scripts\backend-check.ps1 -Modules order
-# 跨服务收尾：显式列出受影响生产者、消费者。
+# 跨服务模块回归：显式列出受影响生产者、消费者。
 .\scripts\backend-check.ps1 -Modules 'order,firstleg'
 ```
 
-三种模式均使用根 reactor 的 `-pl <modules> -am`，不会安装制品到本地仓库，不默认 `clean`。`Compile` 运行 `test-compile`；`Focused`/`Module` 运行 `test`。`-am` 只补上游构建依赖，HTTP/事件下游消费者须由调用者显式列入。公共模块变更也须核对下游，不能只测试公共模块自身。Focused 只用于迭代，不能替代有行为变化时的模块收尾；API、Mapper、索引等相关静态合同仍按其规则单独执行。
+三种模式均使用根 reactor 的 `-pl <modules> -am`，不会安装制品到本地仓库，不默认 `clean`。`Compile` 运行 `test-compile`；`Focused`/`Module` 运行 `test`。`-am` 只补上游构建依赖，HTTP/事件下游消费者须显式列入。局部逻辑使用 `Focused` 覆盖修改行为及必要边界即可交付，不因收尾改跑 `Module`；模块回归只用于定向覆盖不足的服务级影响。公共模块按实际消费者验证。模式缺省值为 `Module`，局部任务须显式选 `Focused`；API、Mapper、索引合同按各自条件执行。
 
 Focused 不接受通配符或方法选择，每个类必须唯一命中所选模块的 `src/test/java`。为允许上游无同名测试，Maven 设置 `surefire.failIfNoSpecifiedTests=false`，随后逐类核对本轮更新的 Surefire XML；报告缺失、陈旧、全部跳过或含失败均不能通过，避免零测试假绿。
 

scripts/admin-test-env-acceptance.mjs

@@ -57,6 +57,8 @@ export function planA0LocationIsolation(locations, requiredSlots = 1,
 }
 
 const MODULE_DEPENDENCIES = new Map([
+  ['inbound-weight-ocr', ['orders']],
+  ['orders', ['merchant-qualification-fixture']],
   ['phase5-root-fulfillment', ['merchant-qualification-fixture']],
   ['pda-loading-link-regression', ['merchant-qualification-fixture']],
   ['phase4-overseas-return-followups', ['phase4-overseas-return-receipt']],

scripts/admin-test-env-modules/README.md

@@ -4,7 +4,9 @@
 
 固定托盘造数中，`inbound-measurement.mjs` 只复用 `TP-001`、`YW-TP-002` 指定池中的现有托盘；一只可复用，不要求两只同时存在，两只均缺失才阻断，不自动选择池外托盘。仅明确设置内部 `allowAnyExistingPallet` 的通用场景可读取当前仓库已有资源；两者均不创建托盘。
 
-OCR模块必须通过`ADMIN_TEST_OCR_IMAGE`显式指定本轮图片，不依赖个人桌面路径。合成称重测试图只证明上传、识别响应及人工确认协议，不代表现场称重照片或设备验收。费用项目模块按受控编码验证112条正式基线，合法扩展项目保留并单独核对分页和筛选。散板普通状态接口仅验证取消及非法派车拒绝，原单须出现在待匹配需求池；需求池接车到签收另列覆盖缺口，不以手工跳状态冒充履约。
+OCR模块必须通过`ADMIN_TEST_OCR_IMAGE`显式指定本轮图片，不依赖个人桌面路径；定向运行自动展开客户资质及订单前置。识别失败的空字段允许省略，但识别成功必须有有效重量与单位；人工修正和确认分别增加版本。合成称重测试图只证明上传、识别响应及人工确认协议，不代表现场称重照片或设备验收。费用项目模块按受控编码验证112条正式基线，合法扩展项目保留并单独核对分页和筛选。散板普通状态接口仅验证取消及非法派车拒绝，原单须出现在待匹配需求池；需求池接车到签收另列覆盖缺口，不以手工跳状态冒充履约。
+
+预约工作查询在本轮业务写入后，仅对服务端明确返回的 A0409“预约批次或运输关联已变化，服务端正在协调完整工作清单”或“已开船工作范围变化，请先完成服务端同步”每 5 秒重读，最多等待 240 秒；超时保留失败，其他错误不重试。这是后台完整扫描的就绪等待，不是页面响应性能验收，也不触发同步写接口。
 
 先运行 `node scripts/acceptance-overview.mjs`（后端根目录，无网络）查看当前默认与可选模块。范围来自真实注册表；本文件描述各模块用途与依赖，不代表所有模块默认执行或已通过。报告解读及跨端/专项边界见 [总索引](../README.md#先看范围再看证据)，最新运行状态只查外层部署契约。
 

scripts/admin-test-env-modules/appointment-work-contract.test.mjs

@@ -1,7 +1,26 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
 import { readFileSync } from 'node:fs'
-import { run } from './appointment-work.mjs'
+import { run, readAfterSynchronization } from './appointment-work.mjs'
+
+test('同步就绪只重试明确协调状态，超限及其他错误原样保留', async () => {
+  const coordinating = {http:200,body:{code:'A0409',message:'预约批次或运输关联已变化，服务端正在协调完整工作清单'}}
+  const success = {http:200,body:{code:'200',data:{}}}
+  let calls = 0
+  assert.equal(await readAfterSynchronization({request:async()=>++calls === 1 ? coordinating : success}, '/summary', {attempts:3,delay:async()=>{}}),success)
+  assert.equal(calls,2)
+  const scopeChanged = {http:200,body:{code:'A0409',message:'已开船工作范围变化，请先完成服务端同步'}}
+  calls=0
+  assert.equal(await readAfterSynchronization({request:async()=>++calls===1?scopeChanged:success}, '/summary', {attempts:3,delay:async()=>{}}),success)
+  assert.equal(calls,2)
+  calls=0
+  assert.equal(await readAfterSynchronization({request:async()=>{calls++;return coordinating}}, '/summary', {attempts:3,delay:async()=>{}}),coordinating)
+  assert.equal(calls,3)
+  const other={http:500,body:{code:'S0500'}}
+  assert.equal(await readAfterSynchronization({request:async()=>other}, '/summary', {delay:async()=>assert.fail('must not retry')}),other)
+  const conflict={http:200,body:{code:'A0409',message:'预约版本冲突'}}
+  assert.equal(await readAfterSynchronization({request:async()=>conflict}, '/summary', {delay:async()=>assert.fail('must not retry unrelated conflict')}),conflict)
+})
 
 const entry = readFileSync(new URL('../admin-test-env-acceptance.mjs', import.meta.url), 'utf8')
 const moduleSource = readFileSync(new URL('./appointment-work.mjs', import.meta.url), 'utf8')

scripts/admin-test-env-modules/appointment-work.mjs

@@ -1,3 +1,18 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+
+export async function readAfterSynchronization(context, path, { attempts = 49, delay = () => sleep(5000) } = {}) {
+  let response
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    response = await context.request('GET', path)
+    const coordinating = response.http === 200 && String(response.body?.code) === 'A0409'
+      && ['预约批次或运输关联已变化，服务端正在协调完整工作清单',
+        '已开船工作范围变化，请先完成服务端同步'].includes(response.body?.message)
+    if (!coordinating || attempt === attempts) return response
+    await delay()
+  }
+  return response
+}
+
 function count(value) {
   const number = Number(value)
   return Number.isFinite(number) ? number : NaN
@@ -15,7 +30,7 @@ export async function run(context) {
   const from = shanghaiDate(-7)
   const to = shanghaiDate(7)
 
-  const calendarResponse = await context.request('GET', `${base}/calendar?from=${from}&to=${to}`)
+  const calendarResponse = await readAfterSynchronization(context, `${base}/calendar?from=${from}&to=${to}`)
   const calendar = context.apiSuccess(module, '查询预约工作日历', calendarResponse)
   const days = Array.isArray(calendar?.days) ? calendar.days : []
   const dayTotal = days.reduce((sum, day) => sum + Number(day?.total || 0), 0)
@@ -29,14 +44,14 @@ export async function run(context) {
       `date=${day?.date || 'missing'},total=${day?.total ?? 'missing'},typeTotal=${typeTotal}`)
   }
 
-  const summaryResponse = await context.request('GET', `${base}/summary`)
+  const summaryResponse = await readAfterSynchronization(context, `${base}/summary`)
   const summary = context.apiSuccess(module, '查询预约工作汇总', summaryResponse)
   const summaryFields = ['all', 'followToday', 'overdue', 'undated', 'review']
   context.assert(module, '工作汇总五项计数完整', summaryResponse,
     summaryFields.every((field) => Number.isFinite(Number(summary?.[field]))),
     summaryFields.map((field) => `${field}=${summary?.[field] ?? 'missing'}`).join(','))
 
-  const pageResponse = await context.request('GET', `${base}/items?view=ALL&page=1&size=20`)
+  const pageResponse = await readAfterSynchronization(context, `${base}/items?view=ALL&page=1&size=20`)
   const page = context.apiSuccess(module, '查询预约工作事项首页', pageResponse)
   const records = Array.isArray(page?.records) ? page.records : []
   const total = count(page?.total)

scripts/admin-test-env-modules/inbound-weight-ocr-contract.test.mjs

@@ -1,8 +1,10 @@
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import test from 'node:test'
+import { normalizeModuleOrder } from '../admin-test-env-acceptance.mjs'
 
 import {
+  validRecognition, sameOptionalWeight, confirmedVersion,
   confirmedNetSummary,
   isTransientGatewayFailure,
   normalizeWeightPalletOptionPage,
@@ -14,7 +16,22 @@ import {
   workspaceWeightMatchesBaseline,
 } from './inbound-weight-ocr.mjs'
 
+test('OCR failure permits absent optional values but recognition requires a valid weight; correction and confirmation each advance version', () => {
+  assert.equal(validRecognition({ recognitionStatus: 'FAILED' }), true)
+  assert.equal(validRecognition({ recognitionStatus: 'RECOGNIZED' }), false)
+  assert.equal(validRecognition({ recognitionStatus: 'RECOGNIZED', weightValue: 45, weightUnit: 'KG', confidence: 0.9 }), true)
+  assert.equal(validRecognition({ recognitionStatus: 'RECOGNIZED', weightValue: 45, weightUnit: 'KG', confidence: 2 }), false)
+  assert.equal(sameOptionalWeight(undefined, null), true)
+  assert.equal(sameOptionalWeight(undefined, 0), false)
+  assert.equal(sameOptionalWeight(5, 6), false)
+  assert.equal(confirmedVersion(3, false), 4)
+  assert.equal(confirmedVersion(3, true), 5)
+})
+
 test('retries only transient gateway failures for the unauthenticated upload probe', () => {
+  const modules = normalizeModuleOrder(['inbound-weight-ocr'])
+  assert.ok(modules.indexOf('merchant-qualification-fixture') < modules.indexOf('orders'))
+  assert.ok(modules.indexOf('orders') < modules.indexOf('inbound-weight-ocr'))
   assert.equal(isTransientGatewayFailure({ http: 0 }), true)
   assert.equal(isTransientGatewayFailure({ http: 502 }), true)
   assert.equal(isTransientGatewayFailure({ http: 503 }), true)

scripts/admin-test-env-modules/inbound-weight-ocr.mjs

@@ -22,6 +22,22 @@ function closeNumber(actual, expected, tolerance = 0.0005) {
   return Number.isFinite(Number(actual)) && Math.abs(Number(actual) - Number(expected)) < tolerance
 }
 
+export function validRecognition(result) {
+  if (!result || !OCR_STATUSES.has(result.recognitionStatus)) return false
+  if (result.confidence != null && (!Number.isFinite(Number(result.confidence)) || Number(result.confidence) < 0 || Number(result.confidence) > 1)) return false
+  if (result.recognitionStatus === 'FAILED') return result.weightValue == null
+  return result.weightValue != null && Number(result.weightValue) > 0
+    && normalizedGrossKg(result.weightValue, result.weightUnit) != null
+}
+
+export function sameOptionalWeight(actual, expected) {
+  return actual == null || expected == null ? actual == null && expected == null : closeNumber(actual, expected)
+}
+
+export function confirmedVersion(version, hasAdjustment) {
+  return Number(version) + (hasAdjustment ? 2 : 1)
+}
+
 function palletSnapshotComplete(pallet) {
   return Boolean(id(pallet?.palletId))
     && typeof pallet?.palletCode === 'string' && pallet.palletCode.length > 0
@@ -254,10 +270,7 @@ async function createUploadedResult(context, target, pallet, image, overrides =
     Boolean(fileId) && typeof upload?.fileId === 'string',
     `fileIdType=${typeof upload?.fileId}, status=${upload?.recognitionStatus ?? 'missing'}`, SCENARIO_OPTIONS)
   context.assert(MODULE, 'OCR 上传响应字段完整且置信度受限', uploadResponse,
-    upload && OCR_STATUSES.has(upload.recognitionStatus)
-      && Object.hasOwn(upload, 'weightValue') && Object.hasOwn(upload, 'weightUnit')
-      && Object.hasOwn(upload, 'confidence')
-      && (upload.confidence == null || (Number(upload.confidence) >= 0 && Number(upload.confidence) <= 1)),
+    validRecognition(upload),
     `status=${upload?.recognitionStatus ?? 'missing'}, hasWeight=${upload?.weightValue != null}, confidence=${upload?.confidence ?? 'null'}`,
     SCENARIO_OPTIONS)
   if (!fileId) throw new Error('称重图片上传未返回 fileId，无法登记和清理测试资源')
@@ -269,8 +282,7 @@ async function createUploadedResult(context, target, pallet, image, overrides =
     const retry = context.apiSuccess(MODULE, '重试当前称重图片 OCR', retryResponse,
       `fileId=${fileId}`, SCENARIO_OPTIONS)
     context.assert(MODULE, 'OCR 重试保持文件身份并返回识别契约', retryResponse,
-      id(retry?.fileId) === fileId && OCR_STATUSES.has(retry?.recognitionStatus)
-        && Object.hasOwn(retry || {}, 'weightValue') && Object.hasOwn(retry || {}, 'confidence'),
+      id(retry?.fileId) === fileId && validRecognition(retry),
       `sameFile=${id(retry?.fileId) === fileId}, status=${retry?.recognitionStatus ?? 'missing'}`,
       SCENARIO_OPTIONS)
     if (retry) recognized = retry
@@ -474,8 +486,8 @@ export async function run(context) {
     const registeredRow = registered.workspace?.weightResults?.find((row) => id(row.id) === original.resultId)
     context.assert(MODULE, '工作区保留本轮 OCR 原值且未覆盖历史结果', registered.response,
       registeredRow && !baselineIds.has(original.resultId)
-        && closeNumber(registeredRow.ocrWeightValue, original.result.ocrWeightValue)
-        && registeredRow.ocrWeightUnit === original.result.ocrWeightUnit,
+        && sameOptionalWeight(registeredRow.ocrWeightValue, original.result.ocrWeightValue)
+        && (registeredRow.ocrWeightUnit ?? null) === (original.result.ocrWeightUnit ?? null),
       `resultFound=${Boolean(registeredRow)}, baselineCount=${baselineIds.size}, currentCount=${registered.workspace?.weightResults?.length ?? 'n/a'}`,
       SCENARIO_OPTIONS)
 
@@ -506,7 +518,7 @@ export async function run(context) {
     const confirmedTare = Number(confirmed?.palletTareWeightKg)
     const confirmedNet = Number(confirmed?.netWeightKg)
     context.assert(MODULE, '确认结果返回托盘快照、毛重和去皮净重', confirmResponse,
-      confirmed?.recognitionStatus === 'CONFIRMED' && Number(confirmed?.version) === original.version + 1
+      confirmed?.recognitionStatus === 'CONFIRMED' && Number(confirmed?.version) === confirmedVersion(original.version, !canConfirmOriginal)
         && id(confirmed?.palletId) === id(pallet.palletId)
         && confirmed?.palletCode === pallet.palletCode && confirmed?.palletType === pallet.palletType
         && closeNumber(confirmed?.palletCapacityCbm, pallet.capacityCbm)

scripts/admin-test-env-modules/merchant-qualification-fixture-contract.test.mjs

@@ -53,7 +53,7 @@ test('商户夹具通过正式 File 和 IAM 审核流程建立下单资格', ()
   assert.match(fixture, /MERCHANT_TEST_PASSWORD/)
   assert.match(fixture, /context\.options\?\.customerName/)
   assert.match(fixture, /tenantName/)
-  assert.match(fixture, /expectedProcurementPrefix: customerName \? null : 'QLYSXDKH'/)
+  assert.doesNotMatch(fixture, /expectedProcurementPrefix/)
   assert.match(acceptance, /administrator-phone-availability\?phone=/)
   assert.match(acceptance, /attempt < 100/)
   assert.doesNotMatch(acceptance, /phoneSequence % 10/)

scripts/admin-test-env-modules/merchant-qualification-fixture.mjs

@@ -120,10 +120,8 @@ export async function run(context, { publishEnvironment = true } = {}) {
   }
   context.context.merchantQualificationFixture = {
     tenantId, tenantName, username, password, marker: context.marker,
-    expectedProcurementPrefix: customerName ? null : 'QLYSXDKH',
   }
   context.createdResources.merchantQualificationFixture = {
     tenantId, tenantName, username, marker: context.marker,
-    expectedProcurementPrefix: customerName ? null : 'QLYSXDKH',
   }
 }

scripts/admin-test-env-modules/pda-audit-sailing-contract.test.mjs

@@ -111,4 +111,8 @@ test('船期日历模块注册为默认模块并核对月历、渠道、模板
   assert.ok(ctx.calls[3].path.includes('/sailing-assignments/exceptions'))
   assert.ok(ctx.calls[4].path.endsWith('/11'))
   assert.ok(ctx.calls[5].path.endsWith('/999999999999999'))
+  delete sailing.etaAt
+  await runSailingCalendar(ctx)
+  sailing.etaAt = 'invalid-eta'
+  await assert.rejects(runSailingCalendar(ctx), /月历记录、汇总与筛选选项结构完整/)
 })

scripts/admin-test-env-modules/phase3-container-overview.mjs

@@ -103,7 +103,7 @@ export async function run(context) {
   const clearance = await context.request('GET', `${CONTAINERS}/${encodeURIComponent(containerId)}/clearance`)
   context.assert(MODULE, '国内未出仓时目的港清关不生成国外工作台数据', clearance,
     clearance.http === 200 && String(clearance?.body?.code) === 'A0404'
-      && String(clearance?.body?.message || '').includes('国外工作台货柜不存在'),
+      && clearance?.body?.message === '货柜尚未离仓或实际开船，不能维护目的港清关资料',
     `HTTP=${clearance.http}, code=${clearance?.body?.code ?? 'missing'}, containerBookingId=${containerId}`, OPTIONS)
   const customs = await context.request('GET', `/api/platform/v1/first-leg/loading-lists/${encodeURIComponent(planId)}/customs?warehouseId=${encodeURIComponent(warehouseId)}`)
   if (fixture?.finalStatus === 'LOADED') {

scripts/admin-test-env-modules/phase3-container-regression-contract.test.mjs

@@ -55,6 +55,7 @@ test('overview regression requires workflowStatus and distinguishes 100 percent
 test('pre-departure overview rejects destination workbench documents explicitly', () => {
   assert.match(overviewAcceptance, /国内未出仓时 \$\{documentType\} 不生成国外工作台数据/)
   assert.match(overviewAcceptance, /国内未出仓时目的港清关不生成国外工作台数据/)
+  assert.match(overviewAcceptance, /货柜尚未离仓或实际开船，不能维护目的港清关资料/)
   assert.match(overviewAcceptance, /国外工作台货柜不存在/)
 })
 

scripts/admin-test-env-modules/phase4-overseas-business-contract.test.mjs

@@ -207,7 +207,8 @@ function fixture(options = {}) {
 test('module is context injected, blocks missing prerequisites and excludes forbidden surfaces', () => {
   assert.match(source, /export async function run\(context\)/)
   assert.doesNotMatch(source, /https?:\/\/|process\.env|fetch\(/)
-  assert.doesNotMatch(source, /addCoverageGap|coverageGap\(/)
+  assert.equal((source.match(/addCoverageGap\(/g) || []).length, 1)
+  assert.match(source, /looseboard-pool-fulfillment/)
   assert.match(source, /deploymentBlocker: true/)
   assert.match(source, /contactPhone: '\d+'/)
   assert.doesNotMatch(source, /contactPhone: '\+[^']+'/)

scripts/admin-test-env-modules/phase4-overseas-master-data-contract.test.mjs

@@ -5,6 +5,28 @@ import test from 'node:test'
 import { run, vehicleCapacityMatches } from './phase4-overseas-master-data.mjs'
 import { run as runCare } from './fleet-vehicle-care.mjs'
 
+test('平台用户手机号已存在只换号重试，未知创建结果不得重发', async () => {
+  for (const collision of [true, false]) {
+    const { context } = fakeContext({ softAssertions: true })
+    const original = context.request.bind(context)
+    const phones = []
+    let sequence = 0
+    context.findAvailablePhone = async () => `1380000${String(++sequence).padStart(4, '0')}`
+    context.request = async (method, path, body, ...rest) => {
+      if (method === 'POST' && path === '/api/platform/v1/iam/users') {
+        phones.push(body.phone)
+        if (phones.length === 1) return collision
+          ? {http:200,body:{code:'A0409',message:'手机号已存在'}}
+          : {http:500,body:{code:'S0500'}}
+      }
+      return original(method,path,body,...rest)
+    }
+    await run(context)
+    assert.equal(phones.length, collision ? 2 : 1)
+    if (collision) assert.notEqual(phones[0],phones[1])
+  }
+})
+
 test('运维专项接受NON_NULL真实响应但仍完成全部六类记录和两车停用', async () => {
   const { context, state } = fakeContext()
   const request = context.request.bind(context)

scripts/admin-test-env-modules/phase4-overseas-master-data.mjs

@@ -375,13 +375,19 @@ async function verifyCanonicalPermissionDenial(context, resource) {
   if (!roleId) throw new Error('无主数据权限角色未返回ID')
   resource.permissionProbe = { roleId, membershipId: null, roleStatus: 'ACTIVE', userStatus: null }
 
-  const phone = await context.findAvailablePhone(MODULE)
   const username = `p4_md_deny_${suffix}`.slice(0, 64).toLowerCase()
   const password = `P4md${suffix.slice(-8)}A1!`
-  const userResponse = await context.request('POST', '/api/platform/v1/iam/users', {
-    username, displayName: `四期主数据拒绝-${suffix}`, phone,
-    email: `${username}@example.com`, tenantId: '0', roleIds: [roleId], password, status: 'ACTIVE',
-  })
+  let userResponse
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const phone = await context.findAvailablePhone(MODULE)
+    userResponse = await context.request('POST', '/api/platform/v1/iam/users', {
+      username, displayName: `四期主数据拒绝-${suffix}`, phone,
+      email: `${username}@example.com`, tenantId: '0', roleIds: [roleId], password, status: 'ACTIVE',
+    })
+    // 客户管理员候选检查不覆盖平台用户；仅明确未创建的手机号冲突允许换号。
+    if (!(userResponse.http === 200 && String(userResponse.body?.code) === 'A0409'
+      && userResponse.body?.message === '手机号已存在')) break
+  }
   const user = requireData(context, '创建无主数据权限用户', userResponse)
   const membershipId = asId(user?.membershipId)
   if (!membershipId) throw new Error('无主数据权限用户未返回membershipId')

scripts/admin-test-env-modules/phase4-overseas-wallet-and-pallet-cost-contract.test.mjs

@@ -10,9 +10,10 @@ const pda = readFileSync(new URL('./phase4-overseas-pda.mjs', import.meta.url),
 test('采购单号按北京时间日期执行精确合同', () => {
   const instant = new Date('2026-09-05T16:30:00.000Z')
   assert.equal(beijingDate(instant), '20260906')
-  assert.equal(matchesProcurementNo('QLYSXDKH202609060001', 'QLYSXDKH', instant), true)
-  assert.equal(matchesProcurementNo('QLYSXDKH202609050001', 'QLYSXDKH', instant), false)
-  assert.equal(matchesProcurementNo('QLYSXDKH20260906001', 'QLYSXDKH', instant), false)
+  assert.equal(matchesProcurementNo('CG202609060001', instant), true)
+  assert.equal(matchesProcurementNo('CG202609050001', instant), false)
+  assert.equal(matchesProcurementNo('CG20260906001', instant), false)
+  assert.equal(matchesProcurementNo('QLYSXDKH202609060001', instant), false)
 })
 
 test('钱包闭环覆盖充值、授信、采购冻结结算和换标结算释放', () => {

scripts/admin-test-env-modules/phase4-overseas-wallet-and-pallet-cost.mjs

@@ -28,9 +28,8 @@ export function beijingDate(now = new Date()) {
   return `${parts.year}${parts.month}${parts.day}`
 }
 
-export function matchesProcurementNo(orderNo, prefix, now = new Date()) {
-  return typeof prefix === 'string' && prefix.length > 0
-    && new RegExp(`^${prefix}${beijingDate(now)}\\d{4}$`).test(String(orderNo || ''))
+export function matchesProcurementNo(orderNo, now = new Date()) {
+  return new RegExp(`^CG${beijingDate(now)}\\d{4}$`).test(String(orderNo || ''))
 }
 
 async function poll(action, predicate, attempts = 60, intervalMs = 1_000) {
@@ -133,8 +132,8 @@ async function procurementFlow(context, fixture, token, warehouseId) {
       customerName: fixture.tenantName, customerToken: token, warehouseId, upload,
       readWallet: async () => { const result = await platformAccount(context, customerId); if (!success(result.response) || !result.account) throw new Error('本轮客户钱包查询失败'); return result.account } })
     assert(context, '采购正常全链路及资金完成', null, proof.status === 'PASSED', `orderNo=${proof.orderNo}`)
-    assert(context, '采购单号日期和客户前缀正确', null,
-      fixture.expectedProcurementPrefix ? matchesProcurementNo(proof.orderNo, fixture.expectedProcurementPrefix) : /^[A-Z0-9]{1,8}\d{8}\d{4}$/.test(proof.orderNo), `orderNo=${proof.orderNo}`)
+    assert(context, '采购单号为CG加北京时间日期和流水', null,
+      matchesProcurementNo(proof.orderNo), `orderNo=${proof.orderNo}`)
     return { orderNo: proof.orderNo, walletBusinessNos: proof.walletBusinessNos, settledAmountCny: proof.settledAmountCny }
   } finally {
     for (const check of context.createdResources.procurementSample?.checks || []) assert(context, check.label, null, check.passed)

scripts/agents-index-contract.ps1

@@ -141,6 +141,10 @@ $backendAgentsPath = Join-Path $backendRoot 'AGENTS.md'
 $rootAgents = Read-RequiredText $rootAgentsPath
 $businessIndexPath = Join-Path $workspaceRoot 'docs/业务快速索引.md'
 $businessIndex = Read-RequiredText $businessIndexPath
+$businessRulesPath = Join-Path $workspaceRoot 'docs/业务实现边界.md'
+$businessRules = Read-RequiredText $businessRulesPath
+# 业务断言检查实际正文，不再要求导航表复制规则；路由校验仍使用短索引。
+$businessFacts = $businessIndex + "`n" + $businessRules
 Assert-Contains $rootAgents 'docs/业务快速索引.md' '根按需业务索引入口'
 Assert-MarkdownLinks $rootAgentsPath $rootAgents '根导航与文档链接'
 Assert-MarkdownTableUnique $businessIndexPath '## 业务快速路由表' 0 '详细业务路由表'
@@ -153,6 +157,10 @@ $adminIndex = Read-RequiredText $adminIndexPath
 $adminAgents = $adminEntry + "`n" + $adminIndex
 $adminOverseasAgentsPath = Join-Path $workspaceRoot 'apps/admin-web/src/modules/overseas-warehouse/AGENTS.md'
 $adminOverseasAgents = Read-RequiredText $adminOverseasAgentsPath
+# 页面细则归入既有业务正文；只读取对应子节，保留原有字段和状态断言。
+$adminInboundPageRules = [regex]::Match($businessRules, '(?ms)^### Admin 入仓计划页面约束\r?\n(?<body>.*?)(?=^#{1,3} |\z)').Groups['body'].Value
+$checked++
+if (-not $adminInboundPageRules) { Add-Failure '缺少 Admin 入仓计划页面约束正文' }
 Assert-Contains $adminAgents 'src/modules/overseas-warehouse/AGENTS.md' 'Admin 海外仓按需指引入口'
 Assert-MarkdownTableUnique $adminOverseasAgentsPath '## 页面与业务快速索引' 0 'Admin 海外仓模块表'
 $clientEntry = Read-RequiredText $clientAgentsPath
@@ -241,7 +249,8 @@ $lookupSamples = @(
 $lookupCharacters = 0
 foreach ($alias in @(
     @{ Term = '转运打托'; Entry = 'apps/pda-overseas-uniapp/src/pages/warehouse-transfer/warehouse-transfer.vue' },
-    @{ Term = '转运驳回'; Entry = 'apps/admin-web/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue' },
+    @{ Term = '转运通过'; Entry = 'apps/admin-web/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue' },
+    @{ Term = '转运驳回'; Entry = 'apps/admin-web/src/modules/overseas-warehouse/api/warehouseTransfers.ts' },
     @{ Term = '退税资料'; Entry = 'apps/client-web/src/modules/first-leg/components/CustomsDocumentsDialog.vue' },
     @{ Term = '订单审核'; Entry = 'apps/admin-web/src/modules/unified-orders/' },
     @{ Term = 'PDA 出库'; Entry = 'apps/pda-overseas-uniapp/src/pages/dispatch/dispatch.vue' },
@@ -273,6 +282,125 @@ Write-Host "定向检索样本：$($lookupSamples.Count) 项，命中行共 $loo
 $scriptsAgents = Read-RequiredText (Join-Path $backendRoot 'scripts/AGENTS.md')
 $engineeringConstraints = Read-RequiredText (Join-Path $workspaceRoot 'docs/AI工程执行与协作约束.md')
 $docsIndex = Read-RequiredText (Join-Path $workspaceRoot 'docs/README.md')
+
+# 只检查明确列出的当前入口和迁移正文，不递归扫描历史资料。
+$overseasDocEntryPath = Join-Path $workspaceRoot 'docs/海外仓业务/README.md'
+$overseasDocEntry = Read-RequiredText $overseasDocEntryPath
+$overseasDocRulesPath = Join-Path $workspaceRoot 'docs/海外仓业务/业务规则.md'
+$overseasDocRules = Read-RequiredText $overseasDocRulesPath
+$financeDocEntryPath = Join-Path $workspaceRoot 'docs/财务管理/README.md'
+$financeDocEntry = Read-RequiredText $financeDocEntryPath
+$financeP1Path = Join-Path $workspaceRoot 'docs/财务管理/财务对账结算P1闭环.md'
+$financeP1 = Read-RequiredText $financeP1Path
+foreach ($document in @(
+    @{ Name = '业务导航'; Path = $businessIndexPath; Text = $businessIndex; Limit = 12500 },
+    @{ Name = '文档总入口'; Path = (Join-Path $workspaceRoot 'docs/README.md'); Text = $docsIndex; Limit = 3500 },
+    @{ Name = '海外仓文档入口'; Path = $overseasDocEntryPath; Text = $overseasDocEntry; Limit = 2000 },
+    @{ Name = '财务文档入口'; Path = $financeDocEntryPath; Text = $financeDocEntry; Limit = 1800 },
+    @{ Name = 'Admin 海外仓指引'; Path = $adminOverseasAgentsPath; Text = $adminOverseasAgents; Limit = 8000 }
+)) {
+    Assert-MarkdownLinks $document.Path $document.Text $document.Name
+    $checked++
+    if (($document.Text -replace "`r`n", "`n").Length -gt $document.Limit) {
+        Add-Failure "$($document.Name) 超出入口预算 $($document.Limit)，请将正文归回主题主文档"
+    }
+}
+foreach ($document in @(
+    @{ Name = '跨端实现边界'; Path = $businessRulesPath; Text = $businessRules },
+    @{ Name = '海外仓业务正文'; Path = $overseasDocRulesPath; Text = $overseasDocRules },
+    @{ Name = '财务当前闭环'; Path = $financeP1Path; Text = $financeP1 }
+)) { Assert-MarkdownLinks $document.Path $document.Text $document.Name }
+Assert-TableRowWidth $businessIndexPath '## 业务快速路由表' 260 '详细业务导航表'
+$businessRouteSection = (($businessIndex -split '(?m)^## 业务快速路由表\r?$', 2)[1] -split '(?m)^## ', 2)[0]
+# 同一规则可供多个终端入口复用；校验实际正文链接，不要求路由名称复制正文标题。
+$businessRuleSections = [regex]::Matches($businessRules, '(?ms)^## (?<name>[^\r\n]+)\r?\n(?<body>.*?)(?=^## |\z)')
+foreach ($topic in $businessRuleSections) {
+    $name = $topic.Groups['name'].Value
+    $slug = [regex]::Replace($name.Trim().ToLowerInvariant(), '[^\p{L}\p{M}\p{N}_\s-]', '') -replace '\s+', '-'
+    $target = '业务实现边界.md#' + $slug
+    $hasRoute = $businessRouteSection.Contains('](' + $target + ')')
+    if (-not $hasRoute) {
+        # 已有正式正文时允许索引直接跳转，避免为覆盖率强加一层摘要。
+        $sourceLine = [regex]::Match($topic.Groups['body'].Value, '(?m)^范围依据：[^\r\n]+')
+        $sourceLink = [regex]::Match($sourceLine.Value, '\[[^\]]+\]\((?<target>[^)]+)\)')
+        $hasRoute = $sourceLink.Success -and $businessRouteSection.Contains('](' + $sourceLink.Groups['target'].Value + ')')
+    }
+    $checked++
+    if (-not $hasRoute) { Add-Failure "业务正文或其正式依据缺少导航入口：$name" }
+}
+Assert-Contains $rootAgents '备选导航' '索引不是串行读取清单'
+Assert-Contains $rootAgents '命中正文即停止扩展' '正文命中后的读取停止条件'
+Assert-Contains $financeDocEntry '财务对账结算P1闭环.md#客户资金账户' '当前资金账户正文入口'
+Assert-NotContains $financeDocEntry '钱包不做' '财务入口不混入历史排除范围'
+Assert-Contains $financeP1 '首批固定为 CNY' '资金账户币种规则迁入现行正文'
+Assert-Contains $financeP1 '充值先归还已用授信或负余额' '资金账户充值规则迁入现行正文'
+Assert-Contains $financeP1 '新账户默认授信为 `0.00`' '资金账户默认授信规则迁入现行正文'
+# 入口存在不足以证明动作存在：核对弹框实际调用与 API 结论，避免将接口能力当成按钮。
+$transferReviewUi = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-web/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue')
+$transferReviewApi = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-web/src/modules/overseas-warehouse/api/warehouseTransfers.ts')
+$transferUiRow = @($adminOverseasAgents -split '\r?\n' | Where-Object { $_.StartsWith('| 仓储转运审核、审核通过 |') })
+$transferApiRow = @($adminOverseasAgents -split '\r?\n' | Where-Object { $_.StartsWith('| 转运驳回、REJECT 接口能力 |') })
+$checked++
+if ($transferUiRow.Count -ne 1 -or $transferApiRow.Count -ne 1) {
+    Add-Failure '转运审核的界面入口与 API 能力必须分别定位'
+} else {
+    Assert-Contains $transferUiRow[0] 'components/WarehouseTransferReviewDialog.vue' '转运通过界面入口'
+    Assert-Contains $transferUiRow[0] 'APPROVE' '转运通过界面结论'
+    Assert-Contains $transferApiRow[0] 'api/warehouseTransfers.ts' '转运驳回 API 入口'
+    Assert-Contains $transferApiRow[0] 'REJECT' '转运 API 驳回结论'
+    Assert-Matches $transferReviewUi 'reviewWarehouseTransfer\([^)]*,\s*[''"]APPROVE[''"](?:\s*,[^)]*)?\s*\)' '转运通过真实调用'
+    Assert-Matches $transferReviewApi 'decision\s*:\s*[''"]APPROVE[''"]\s*\|\s*[''"]REJECT[''"]' '转运 API 允许的结论'
+    if ($transferReviewUi -match 'reviewWarehouseTransfer\([^)]*,\s*[''"]REJECT[''"]') {
+        Assert-NotContains $transferUiRow[0] '无驳回按钮' '转运界面能力变化后更新指引'
+        Assert-Contains $transferUiRow[0] 'REJECT' '转运界面新增驳回后更新指引'
+    } else {
+        Assert-Contains $transferUiRow[0] '无驳回按钮' '转运界面不能虚构驳回动作'
+        Assert-NotContains $transferUiRow[0] 'REJECT' '转运界面与 API 能力分开'
+    }
+}
+Assert-Contains $adminOverseasAgents 'baiyue-firstleg/print/AGENTS.md' '托盘模板指向 Print 权威入口'
+Assert-NotContains $adminOverseasAgents 'INBOUND_MARK_V1' 'Admin 不复制箱唛模板为托盘模板'
+$adminOverseasVerification = [regex]::Match($adminOverseasAgents, '(?ms)^## 验证\r?\n(?<body>.*?)(?=^## |\z)').Groups['body'].Value
+$checked++
+if (-not $adminOverseasVerification -or ($adminOverseasVerification -replace '\r', '').Length -gt 800) {
+    Add-Failure 'Admin 海外仓验证节须存在且不超过800字符，业务正文应归回按需条款'
+}
+
+$docLookupCharacters = 0
+$walletRuleTarget = '财务管理/财务对账结算P1闭环.md#客户资金账户'
+$docLookupSamples = @(
+    @{ Key = '客户头程订单批量导入'; Text = $businessIndex; Column = 1; Entry = 'apps/client-web/src/modules/first-leg/AGENTS.md' },
+    @{ Key = '仓储转运审核、转运通过'; Text = $businessIndex; Column = 2; Entry = 'apps/admin-web/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue' },
+    @{ Key = '转运驳回、REJECT'; Text = $businessIndex; Column = 2; Entry = 'apps/admin-web/src/modules/overseas-warehouse/api/warehouseTransfers.ts' },
+    @{ Key = '平台资金账户、充值审核、手工充扣与授信'; Text = $businessIndex; Column = 1; Entry = 'apps/admin-web/src/modules/finance/AGENTS.md'; Rules = $walletRuleTarget },
+    @{ Key = '客户资金账户、余额、授信与充值申请'; Text = $businessIndex; Column = 1; Entry = 'apps/client-web/src/modules/finance/AGENTS.md'; Rules = $walletRuleTarget },
+    @{ Key = '服务端资金账户、授信、冻结、结算与业务扣费'; Text = $businessIndex; Column = 1; Entry = 'baiyue-firstleg/finance/AGENTS.md'; Rules = $walletRuleTarget },
+    @{ Key = '海外仓库主档、名称、地址与能力'; Text = $businessIndex; Column = 1; Entry = 'apps/admin-web/src/modules/warehouses/AGENTS.md'; Rules = '业务实现边界.md#海外仓库与通用资料' },
+    @{ Key = '海外仓库主档、名称、地址与能力'; Text = $businessIndex; Column = 1; Entry = 'baiyue-firstleg/warehouse/AGENTS.md'; Rules = '业务实现边界.md#海外仓库与通用资料' },
+    @{ Key = '海外库位、托盘与资源锁'; Text = $businessIndex; Column = 1; Entry = 'baiyue-firstleg/warehouse-overseas-service/AGENTS.md'; Rules = '业务实现边界.md#海外仓库与通用资料' },
+    @{ Key = '客户统计与运营指标'; Text = $businessIndex; Column = 1; Entry = 'apps/admin-web/src/modules/customers/AGENTS.md' },
+    @{ Key = '平台日志、操作日志、审计日志与操作人缺失'; Text = $businessIndex; Column = 1; Entry = 'apps/admin-web/src/modules/audit/AGENTS.md' },
+    @{ Key = '客户账单、客户对账单、账单确认'; Text = $businessIndex; Column = 2; Entry = 'apps/client-web/src/modules/finance/views/FinanceBillsView.vue' },
+    @{ Key = '客户资金账户、充值、授信、冻结与业务扣费'; Text = $financeDocEntry; Column = 1; Entry = '财务对账结算P1闭环.md#客户资金账户' },
+    @{ Key = '海外排车、出库与派送改造'; Text = $overseasDocEntry; Column = 1; Entry = '排车列表统一作业改造契约.md' },
+    @{ Key = '本土卡车与散板表单'; Text = $overseasDocEntry; Column = 1; Entry = '业务规则.md#本土散板简化下单' }
+)
+foreach ($sample in $docLookupSamples) {
+    $hits = @($sample.Text -split '\r?\n' | Where-Object { $_.StartsWith('| ' + $sample.Key + ' |') })
+    $checked++
+    if ($hits.Count -ne 1) { Add-Failure "文档路由样本必须唯一命中：$($sample.Key)"; continue }
+    # 代码入口与规则正文分别核对，不能靠其他列碰巧包含目标路径通过。
+    $cells = @($hits[0].Trim('|').Split('|') | ForEach-Object { $_.Trim() })
+    if ($sample.Column -ge $cells.Count) { Add-Failure "文档路由样本缺少目标列：$($sample.Key)"; continue }
+    Assert-Contains $cells[$sample.Column] $sample.Entry "文档路由样本 $($sample.Key)"
+    if ($sample.Rules) {
+        if ($cells.Count -lt 3) { Add-Failure "文档路由样本缺少规则正文：$($sample.Key)"; continue }
+        Assert-Contains $cells[2] $sample.Rules "文档正文样本 $($sample.Key)"
+    }
+    $docLookupCharacters += $hits[0].Length
+}
+Write-Host "文档路由样本：$($docLookupSamples.Count) 项，命中行共 $docLookupCharacters 字符（不含上层指引或按需正文，不代表端到端耗时）。"
+
 $testTaskRegistry = Read-RequiredText (Join-Path $workspaceRoot 'docs/独立任务协作登记.md')
 $devTaskRegistry = Read-RequiredText (Join-Path $workspaceRoot 'docs/开发环境独立任务协作登记.md')
 $mapperScanContract = Read-RequiredText (Join-Path $backendRoot 'scripts/mapper-scan-contract.mjs')
@@ -282,7 +410,7 @@ Assert-Contains $rootAgents '源码结构、接口与 DTO、字段、状态机
 Assert-Contains $rootAgents '数据库记录、上传文件、缓存、会话、消息、搜索索引和其他运行状态均视为可丢弃' '根开发运行状态范围'
 Assert-Contains $rootAgents '后端 MyBatis Mapper 新增、移动或扫描遗漏' '根 Mapper 快速入口'
 Assert-Contains $rootAgents 'node scripts/mapper-scan-contract.mjs' '根 Mapper 静态门禁'
-Assert-Contains $businessIndex '脚本管理、全量验证与测试造数' '根脚本管理快速入口'
+Assert-Contains $businessFacts '脚本管理、全量验证与测试造数' '根脚本管理快速入口'
 Assert-Contains $rootAgents 'baiyue-firstleg/scripts/AGENTS.md' '根脚本最近指引'
 Assert-Contains $engineeringConstraints '禁止为旧代码、旧调用或开发环境存量保留旧接口/旧字段别名' '工程无兼容执行规则'
 Assert-Contains $engineeringConstraints '不授权自动重置数据库、删除数据/文件、执行 SQL、部署或修改环境' '无兼容安全边界'
@@ -340,7 +468,7 @@ foreach ($businessDocsEntry in @(
     'docs/国内货柜履约/README.md',
     'docs/海外仓业务/README.md'
 )) {
-    Assert-Contains $businessIndex $businessDocsEntry "根业务域入口 $businessDocsEntry"
+    Assert-Contains $businessFacts $businessDocsEntry "根业务域入口 $businessDocsEntry"
 }
 foreach ($removedPhaseDocsEntry in @('docs/一期/', 'docs/二期/', 'docs/三期/', 'docs/四期/')) {
     Assert-NotContains $rootAgents $removedPhaseDocsEntry "根已删除阶段目录 $removedPhaseDocsEntry"
@@ -348,18 +476,18 @@ foreach ($removedPhaseDocsEntry in @('docs/一期/', 'docs/二期/', 'docs/三
 Assert-NotContains $rootAgents '不含出库和派送' '根海外仓全流程范围'
 
 # 新增稳定业务能力必须从根表和目标部署单元直接命中。
-Assert-Contains $businessIndex '入库扣货、解除与凭证' '根入库扣货路由'
+Assert-Contains $businessFacts '入库扣货、解除与凭证' '根入库扣货路由'
 Assert-Contains $adminAgents '入库扣货、解除与凭证历史' 'Admin 入库扣货路由'
 Assert-Contains $backendAgents '入库单扣货、解除、凭证与履约门禁' '后端入库扣货路由'
-Assert-Contains $businessIndex '客户资金账户、充值、授信与业务扣费' '根客户资金账户路由'
+Assert-Contains $businessFacts '客户资金账户、充值、授信与业务扣费' '根客户资金账户路由'
 Assert-Contains $adminAgents '客户资金账户与柜级公共费用分摊' 'Admin 客户资金账户路由'
 Assert-Contains $clientAgents '客户资金账户、授信与充值申请' 'Client 客户资金账户路由'
 Assert-Contains $backendAgents '客户资金账户、充值、授信、冻结、结算与跨区资金指令' '后端客户资金账户路由'
-Assert-Contains $businessIndex '顶层授权快照' '根海外顶层授权快照'
+Assert-Contains $businessFacts '顶层授权快照' '根海外顶层授权快照'
 Assert-Contains $backendAgents '顶层授权快照' '后端海外顶层授权快照'
-Assert-Contains $businessIndex '目的港码头拖车与还空预警' '根目的港码头拖车路由'
-Assert-Contains $businessIndex '与订舱级拖车预约是不同生命周期' '根两类拖车边界'
-Assert-Contains $businessIndex '尾程订单控制与柜级入仓计划转换' '根尾程订单控制路由'
+Assert-Contains $businessFacts '目的港码头拖车与还空预警' '根目的港码头拖车路由'
+Assert-Contains $businessFacts '与订舱级拖车预约是不同生命周期' '根两类拖车边界'
+Assert-Contains $businessFacts '尾程订单控制与柜级入仓计划转换' '根尾程订单控制路由'
 Assert-Contains $adminAgents '目的港码头拖车与还空预警' 'Admin 目的港码头拖车路由'
 Assert-Contains $adminAgents '尾程订单控制与柜级入仓计划转换' 'Admin 尾程订单控制路由'
 Assert-Contains $backendAgents '目的港码头拖车与还空预警' '后端目的港码头拖车路由'
@@ -385,7 +513,7 @@ $firstlegAgents = $firstlegEntry + "`n" + $firstlegIndex
 $lastlegAgents = $lastlegEntry + "`n" + $lastlegIndex
 $warehouseAgents = Read-RequiredText (Join-Path $backendRoot 'warehouse/AGENTS.md')
 $coloadOpenApi = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/resources/openapi/coload-groups-v1.yaml')
-Assert-Contains $businessIndex 'modules/unified-orders/api/coLoadGroups.ts' '根同柜不可拆组入口'
+Assert-Contains $businessFacts 'modules/unified-orders/api/coLoadGroups.ts' '根同柜不可拆组入口'
 Assert-Contains $adminAgents '成员数是入仓片段数，不等于订单票数' 'Admin 同柜成员语义'
 Assert-Contains $backendAgents 'loading/coload/controller/PlatformColoadGroupController.java' '后端同柜不可拆组入口'
 Assert-Contains $firstlegAgents '服务端允许待审核、待测量/测量中、待分柜及装柜中订单' 'Firstleg 同柜建组边界'
@@ -409,7 +537,7 @@ Assert-Contains $lastlegAgents '/api/platform/v1/last-leg/inbound-plans/convert-
 # 本轮新增的批量下单、测量计费、智能装柜、账单联查与导出重试必须从最近指引直达。
 $fileAgents = Read-RequiredText (Join-Path $backendRoot 'file/AGENTS.md')
 $financeAgents = Read-RequiredText (Join-Path $backendRoot 'finance/AGENTS.md')
-Assert-Contains $businessIndex '客户头程订单批量导入' '根批量下单快速路由'
+Assert-Contains $businessFacts '客户头程订单批量导入' '根批量下单快速路由'
 Assert-Contains $orderAgents 'MerchantBatchImportService.java' 'Order 批量导入入口'
 Assert-Contains $orderAgents '仓库目录必须翻页读取全部候选' 'Order 批量模板全量仓库约束'
 Assert-Contains $clientAgents '中文批量导入' 'Client 批量导入入口'
@@ -435,7 +563,7 @@ $orderDeclarationService = Read-RequiredText (Join-Path $backendRoot 'order/src/
 $unifiedOrderQueryService = Read-RequiredText (Join-Path $backendRoot 'order/src/main/java/com/baiyue/order/service/UnifiedOrderQueryService.java')
 $firstlegDeclarationService = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/java/com/baiyue/firstleg/service/OrderDeclarationSyncService.java')
 $adminDeclarationEditor = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-web/src/modules/unified-orders/components/OrderDeclarationEditorDialog.vue')
-Assert-Contains $businessIndex '平台修改客户原始申报与履约渠道' '根订单申报快速路由'
+Assert-Contains $businessFacts '平台修改客户原始申报与履约渠道' '根订单申报快速路由'
 Assert-Contains $adminAgents '客户原始申报资料编辑与渠道变更' 'Admin 订单申报快速路由'
 Assert-Contains $backendAgents '平台修改客户原始申报、履约渠道变更与跨服务同步' '后端订单申报快速路由'
 Assert-Contains $orderAgents '平台版本化修改客户原始申报' 'Order 申报编辑入口'
@@ -448,7 +576,7 @@ Assert-Contains $orderDeclarationService 'ORDER_DECLARATION_UPDATED_V1' 'Order
 Assert-Contains $firstlegDeclarationService 'mapper.byEvent(event.tenantId(), event.eventId())' 'Firstleg 申报 eventId 幂等'
 Assert-Contains $firstlegDeclarationService 'event.version() < current.orderVersion()' 'Firstleg 申报版本单调性'
 Assert-Contains $adminDeclarationEditor '仓库/PDA 实测数据不会被覆盖' 'Admin 申报事实边界提示'
-Assert-Contains $businessIndex '统一列表仍固定显示 `PENDING_REVIEW` 并提供审核动作' '根待审核订单优先状态'
+Assert-Contains $businessFacts '统一列表仍固定显示 `PENDING_REVIEW` 并提供审核动作' '根待审核订单优先状态'
 Assert-Contains $orderAgents '统一主状态/下一动作仍固定为 `PENDING_REVIEW/APPROVE_ORDER`' 'Order 待审核优先状态'
 Assert-Contains $unifiedOrderQueryService 'order.getStatus() == OrderStatus.SUBMITTED' 'Order 待审核状态判断'
 Assert-Contains $unifiedOrderQueryService 'pendingReview ? "PENDING_REVIEW" : completed ? "COMPLETED" : summary.mainStatus()' 'Order 待审核主状态优先于完成态与履约投影'
@@ -461,14 +589,14 @@ $fbaPricingService = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/mai
 $inboundFeeDetailService = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/java/com/baiyue/firstleg/service/InboundFeeDetailService.java')
 $adminUnifiedOrdersApi = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-web/src/modules/unified-orders/api/unifiedOrders.ts')
 $adminCarrierRatesView = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-web/src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue')
-Assert-Contains $businessIndex '头程订单、批量审核预览与入仓码关系' '根批量审核预览路由'
+Assert-Contains $businessFacts '头程订单、批量审核预览与入仓码关系' '根批量审核预览路由'
 Assert-Contains $adminAgents '订单列表、批量审核预览、详情、商品图片与入库费用' 'Admin 批量审核预览路由'
 Assert-Contains $backendAgents '平台订单批量审核预览' '后端批量审核预览路由'
 Assert-Contains $orderAgents '平台批量审核预览' 'Order 批量审核预览入口'
 Assert-Contains $orderOpenApi '/api/platform/v1/orders/first-leg/batch-review-preview:' 'Order 批量审核预览 OpenAPI'
 Assert-Contains $batchReviewPreviewService '固定两次批量查询生成审核弹窗快照' 'Order 批量审核禁止逐票查询'
 Assert-Contains $adminUnifiedOrdersApi '/platform/v1/orders/first-leg/batch-review-preview' 'Admin 批量审核预览 API'
-Assert-Contains $businessIndex '客户专属报价、柜级阶梯运费与费用调整' '根客户专属报价路由'
+Assert-Contains $businessFacts '客户专属报价、柜级阶梯运费与费用调整' '根客户专属报价路由'
 Assert-Contains $adminAgents '客户专属价格簿、柜级阶梯运费与受控调价' 'Admin 客户专属报价路由'
 Assert-Contains $backendAgents '客户专属价格簿、柜级阶梯运费与受控调价' '后端客户专属报价路由'
 Assert-Contains $firstlegAgents '客户专属价格簿、柜级阶梯运费与调价边界' 'Firstleg 客户专属报价入口'
@@ -485,8 +613,8 @@ Assert-Path 'baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/pricing/
 # 海外异常处理必须贯通证据、原出库来源和库存恢复，不能退化为仅修改派送状态。
 $exceptionOrderService = Read-RequiredText (Join-Path $backendRoot 'lastleg-service/src/main/java/com/baiyue/lastleg/exceptionorder/service/ExceptionOrderService.java')
 $inventoryCommandService = Read-RequiredText (Join-Path $backendRoot 'lastleg-service/src/main/java/com/baiyue/lastleg/inventory/command/service/InventoryCommandService.java')
-Assert-Contains $businessIndex '海外出库、排车、派送、异常与回访' '根海外异常库存恢复路由'
-Assert-Contains $businessIndex 'exceptionorder/' '根海外异常服务入口'
+Assert-Contains $businessFacts '海外出库、排车、派送、异常与回访' '根海外异常库存恢复路由'
+Assert-Contains $businessFacts 'exceptionorder/' '根海外异常服务入口'
 Assert-Contains $lastlegIndex '退回海外仓须把实收按原出库来源恢复到服务端校验的真实托盘/库位' 'Lastleg 海外异常库存恢复规则'
 Assert-Contains $adminOverseasAgents '库存恢复、异常完成与派送 `RETURNED` 由服务端原子推进' 'Admin 海外异常原子边界'
 Assert-Contains $backendAgents '海外异常退回、库存恢复与客户回访' '后端海外异常库存恢复路由'
@@ -503,9 +631,9 @@ $pendingReviewOrderService = Read-RequiredText (Join-Path $backendRoot 'order/sr
 $merchantInboundBillingService = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/java/com/baiyue/firstleg/service/MerchantInboundBillingService.java')
 $clientSession = Read-RequiredText (Join-Path $workspaceRoot 'apps/client-web/src/api/session.ts')
 $clientHttp = Read-RequiredText (Join-Path $workspaceRoot 'apps/client-web/src/api/http.ts')
-Assert-Contains $businessIndex '`PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING`' '根智能装柜四态候选'
-Assert-Contains $businessIndex '能否加入以服务端 `canAssign` 为准' '根智能装柜资格边界'
-Assert-Contains $businessIndex '人工加入允许跨渠道，智能推荐仍按柜次渠道' '根智能装柜渠道边界'
+Assert-Contains $businessFacts '`PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING`' '根智能装柜四态候选'
+Assert-Contains $businessFacts '能否加入以服务端 `canAssign` 为准' '根智能装柜资格边界'
+Assert-Contains $businessFacts '人工加入允许跨渠道，智能推荐仍按柜次渠道' '根智能装柜渠道边界'
 Assert-Contains $backendAgents '/pending-review-assignments' '后端待审核装柜占位入口'
 Assert-Contains $backendAgents '/unpicked-items' '后端未拣整批移除入口'
 Assert-Contains $firstlegAgents '任一成员已拣则整组保留' 'Firstleg 同柜组整批移除边界'
@@ -516,7 +644,7 @@ Assert-Contains $firstlegOpenApi '/api/platform/v1/first-leg/smart-loading/plans
 Assert-Contains $firstlegOpenApi '/api/platform/v1/first-leg/smart-loading/plans/{planId}/unpicked-items:' '未拣整批移除 OpenAPI'
 Assert-Contains $pendingReviewOrderService 'orders.pendingReviewPage' 'Order 待审核候选权威查询'
 Assert-Contains $pendingReviewOrderService '"PENDING_REVIEW"' 'Order 待审核候选状态映射'
-Assert-Contains $businessIndex '客户入库结果与头程费用确认' '根客户入库费用确认入口'
+Assert-Contains $businessFacts '客户入库结果与头程费用确认' '根客户入库费用确认入口'
 Assert-Contains $firstlegAgents 'expectedFeeVersion' 'Firstleg 客户费用版本确认'
 Assert-Contains $clientAgents 'components/InboundBillingPanel.vue' 'Client 入库费用确认入口'
 Assert-Contains $firstlegOpenApi '/api/merchant/v1/first-leg/orders/{orderId}/inbound-billing/confirm:' '客户费用确认 OpenAPI'
@@ -536,7 +664,7 @@ $smartLoadingService = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/m
 $inboundSchema = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/resources/db/phase2-inbound-schema.sql')
 $adminWeightPanel = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-web/src/modules/inbounds/weight/components/WeightOcrPanel.vue')
 $clientOrdersView = Read-RequiredText (Join-Path $workspaceRoot 'apps/client-web/src/modules/first-leg/views/FirstLegOrdersView.vue')
-Assert-Contains $businessIndex '称重确认、整票库位块与部分拣货资源结算' '根称重库位块路由'
+Assert-Contains $businessFacts '称重确认、整票库位块与部分拣货资源结算' '根称重库位块路由'
 Assert-Contains $backendAgents '称重确认、整票库位块与 PDA 资源结算' '后端称重库位块路由'
 Assert-Contains $firstlegAgents 'MeasurementLocationOccupationService.java' 'Firstleg 称重库位块入口'
 Assert-Contains $firstlegAgents '最新测量批次的正数 `totalVolumeCbm/originalVolumeCbm` 取较大值' 'Firstleg 库位块测量批次体积选择'
@@ -556,7 +684,7 @@ Assert-Contains $inboundSchema 'UNIQUE KEY uk_pallet_allocation_weight (tenant_i
 Assert-Contains $adminWeightPanel 'row.locationCode' 'Admin 称重卡片库位消费'
 Assert-Contains $adminWeightPanel 'putawayStatusLabel(row.slotStatus)' 'Admin 称重卡片槽位状态'
 Assert-NotContains $adminWeightPanel 'class="putaway-guide"' 'Admin 已移除整票预留引导区'
-Assert-Contains $businessIndex '`totalPackageCount/remainingPackageCount`' '根智能装柜暂估数量'
+Assert-Contains $businessFacts '`totalPackageCount/remainingPackageCount`' '根智能装柜暂估数量'
 Assert-Contains $firstlegAgents '`totalPackageCount/remainingPackageCount`' 'Firstleg 智能装柜暂估数量'
 Assert-Contains $adminAgents '`totalPackageCount/remainingPackageCount`' 'Admin 智能装柜暂估数量'
 Assert-Contains $firstlegOpenApi 'required: [id, packageCount, totalPackageCount, remainingPackageCount' '智能装柜计划数量 OpenAPI'
@@ -575,7 +703,7 @@ $iamMemberService = Read-RequiredText (Join-Path $backendRoot 'iam/src/main/java
 $adminCustomersView = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-web/src/modules/customers/pages/CustomersView.vue')
 $clientCompanyProfile = Read-RequiredText (Join-Path $workspaceRoot 'apps/client-web/src/modules/tenant-management/views/CompanyProfileView.vue')
 $clientMembersView = Read-RequiredText (Join-Path $workspaceRoot 'apps/client-web/src/modules/tenant-management/views/MembersView.vue')
-Assert-Contains $businessIndex '公司联系电话/邮箱是企业资料，不作为成员登录标识' '根企业联系人边界'
+Assert-Contains $businessFacts '公司联系电话/邮箱是企业资料，不作为成员登录标识' '根企业联系人边界'
 Assert-Contains $adminAgents '公司联系电话只作企业联系信息，不修改管理员/成员登录手机号' 'Admin 企业联系人边界'
 Assert-Contains $clientAgents '成员登录手机号可选，修改时同步 Auth、撤销该账号会话并审计' 'Client 成员登录手机号边界'
 Assert-Contains $authAgents '登录标识与企业联系人解耦' 'Auth 登录标识入口'
@@ -589,7 +717,7 @@ Assert-Contains $clientCompanyProfile '不会修改任何成员的登录手机
 Assert-Contains $clientMembersView '用于该成员手机号登录；修改后会同步认证账号并退出该成员现有会话' 'Client 成员登录手机号提示'
 $fileAgents = Read-RequiredText (Join-Path $backendRoot 'file/AGENTS.md')
 $qualificationOpenApi = Read-RequiredText (Join-Path $backendRoot 'file/src/main/resources/openapi/qualification-required-package-v1.yaml')
-Assert-Contains $businessIndex '法人身份证选填，可在已有营业执照后单独补传或替换' '根法人身份证单独上传语义'
+Assert-Contains $businessFacts '法人身份证选填，可在已有营业执照后单独补传或替换' '根法人身份证单独上传语义'
 Assert-Contains $fileAgents '法人身份证选填，客户可在已有营业执照后通过 `/api/merchant/v1/files/qualifications` 单独新增或替换' 'File 法人身份证单独上传入口'
 Assert-Contains $qualificationOpenApi '/api/merchant/v1/files/qualifications:' '客户单文件资质 OpenAPI'
 Assert-Contains $qualificationOpenApi 'LEGAL_PERSON_ID 可在已有营业执照后单独新增或替换' '客户法人身份证单独上传契约'
@@ -605,8 +733,8 @@ $adminLastMileOrders = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-w
 $loadingListsOpenApi = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/resources/openapi/loading-lists-v1.yaml')
 $pdaLoadingApi = Read-RequiredText (Join-Path $workspaceRoot 'apps/pda-uniapp/api/pda-loading.js')
 $cabinetEvidenceService = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/java/com/baiyue/firstleg/loading/service/CabinetLoadingEvidenceService.java')
-Assert-Contains $businessIndex '拖车预约由 `RELEASED` 订舱拥有，不按客户、柜次、装柜计划或真实柜号归属' '根订舱级拖车语义'
-Assert-Contains $businessIndex '证据以 `taskId + warehouseId` 进入任务专用 API' '根柜级证据入口'
+Assert-Contains $businessFacts '拖车预约由 `RELEASED` 订舱拥有，不按客户、柜次、装柜计划或真实柜号归属' '根订舱级拖车语义'
+Assert-Contains $businessFacts '证据以 `taskId + warehouseId` 进入任务专用 API' '根柜级证据入口'
 Assert-Contains $adminAgents '订舱级拖车预约' 'Admin 拖车快速入口'
 Assert-Contains $adminAgents '不选择或提交客户、柜次、装柜计划或真实集装箱号' 'Admin 拖车订舱级边界'
 Assert-Contains $backendAgents '订舱级拖车' '后端拖车快速入口'
@@ -634,7 +762,7 @@ Assert-Contains $lastlegOrderCommandService '必须提交完整8行人工时间
 Assert-Contains $lastlegOrderCommandService '尾程订单已进入出库流程，不能新增暂扣' '尾程暂扣出库门禁实现'
 Assert-Contains $adminLastMileOrders '/platform/v1/last-leg/orders/${encodeURIComponent(orderId)}/hold' 'Admin 尾程暂扣入口'
 Assert-Contains $adminLastMileOrders '/platform/v1/last-leg/orders/${encodeURIComponent(orderId)}/manual-nodes' 'Admin 尾程人工节点入口'
-Assert-Contains $adminOverseasAgents '入仓码只读展示并提交订单冻结值' 'Admin 尾程计划冻结入仓码边界'
+Assert-Contains $adminInboundPageRules '入仓码只读展示并提交订单冻结值' 'Admin 尾程计划冻结入仓码边界'
 Assert-Contains $lastlegAgents '接柜仓编码/名称以该 ID 当前目录快照为准' 'Lastleg 稳定接柜仓身份边界'
 Assert-Contains $lastlegOrderCommandService '同一幂等键不能用于不同请求' '尾程命令请求哈希重放边界'
 Assert-Contains $loadingListsOpenApi '且真实集装箱号已经补录' '确认预装真实柜号门禁'
@@ -645,7 +773,7 @@ Assert-Contains $adminAgents '确认预装和创建 PDA 任务前必须补齐' '
 Assert-Contains $pdaAgents '当前 `taskId + warehouseId` 走任务专用 API' '国内 PDA 柜级证据入口'
 Assert-Contains $pdaLoadingApi '/first-leg/pda-loading/tasks/${encodeURIComponent(taskId)}/evidence?warehouseId=' '国内 PDA 证据查询 API'
 Assert-NotContains $pdaLoadingApi '/inbounds/${encodeURIComponent(inboundId)}/loading/evidence' '国内 PDA 旧入仓证据 API'
-Assert-Contains $businessIndex '上传以幂等键绑定包含文件内容的请求哈希' '根装柜证据上传重放边界'
+Assert-Contains $businessFacts '上传以幂等键绑定包含文件内容的请求哈希' '根装柜证据上传重放边界'
 Assert-Contains $firstlegAgents '完全重放返回当前视图且不得再次上传 File' 'Firstleg 装柜证据重放边界'
 Assert-Contains $cabinetEvidenceService 'uploadHash(warehouseId, expectedVersion, evidenceType, sealNo, remark, multipart)' '装柜证据上传请求哈希'
 Assert-Contains $cabinetEvidenceService 'digest.update(multipart.getBytes())' '装柜证据文件内容哈希'
@@ -819,7 +947,7 @@ foreach ($overseasFulfillmentRoute in @(
 foreach ($overseasFulfillmentRootEntry in @(
     'OutboundsView.vue', 'DeliveryOrdersView.vue', 'ExceptionOrdersView.vue', 'CustomerVisitsView.vue'
 )) {
-    Assert-Contains $businessIndex $overseasFulfillmentRootEntry '根海外履约正式业务路由'
+    Assert-Contains $businessFacts $overseasFulfillmentRootEntry '根海外履约正式业务路由'
 }
 Assert-Contains $adminAgents '海外排车、出库与派送' 'Admin 海外出库派送入口'
 Assert-Contains $adminAgents '海外异常退回与客户回访' 'Admin 海外异常回访入口'
@@ -936,8 +1064,8 @@ $containerCustomsOpenApi = Read-RequiredText (Join-Path $backendRoot 'firstleg/s
 $adminContainerCustomsApi = Read-RequiredText (Join-Path $workspaceRoot 'apps/admin-web/src/modules/container-loading/api/platformContainerCustoms.ts')
 $clientContainerCustomsApi = Read-RequiredText (Join-Path $workspaceRoot 'apps/client-web/src/modules/first-leg/api/customs.ts')
 $customsFileOpenApi = Read-RequiredText (Join-Path $backendRoot 'file/src/main/resources/openapi/customs-file-and-export-v1.yaml')
-Assert-Contains $businessIndex 'ContainerCustomsPanel.vue' '根整柜报关 Admin 入口'
-Assert-Contains $businessIndex 'CustomsDocumentsDialog.vue' '根整柜报关 Client 入口'
+Assert-Contains $businessFacts 'ContainerCustomsPanel.vue' '根整柜报关 Admin 入口'
+Assert-Contains $businessFacts 'CustomsDocumentsDialog.vue' '根整柜报关 Client 入口'
 Assert-Contains $adminAgents 'components/ContainerCustomsPanel.vue' 'Admin 整柜报关入口'
 Assert-Contains $adminAgents 'complete-all-buy' 'Admin 全买单柜入口'
 Assert-Contains $clientAgents 'components/CustomsDocumentsDialog.vue' 'Client 退税报关资料入口'
@@ -980,16 +1108,16 @@ Assert-Contains $lastlegBusinessOpenApi '/api/platform/v1/last-leg/inbound-plans
 Assert-Contains $lastlegBusinessOpenApi 'snapshotVersion' 'Lastleg 整柜计划快照版本'
 Assert-Contains $lastlegBusinessOpenApi 'snapshotHash' 'Lastleg 整柜计划快照哈希'
 Assert-Contains $lastlegBusinessOpenApi 'sourceContainerBookingId' 'Lastleg 稳定来源柜身份'
-Assert-Contains $adminOverseasAgents '/orders/container-summaries' 'Admin 柜级摘要目标入口'
-Assert-Contains $businessIndex '尾程订单控制与柜级入仓计划转换' '根柜级计划入口'
+Assert-Contains $adminInboundPageRules '/orders/container-summaries' 'Admin 柜级摘要目标入口'
+Assert-Contains $businessFacts '尾程订单控制与柜级入仓计划转换' '根柜级计划入口'
 Assert-Contains $backendAgents '分页返回全部稳定来源柜' '后端全柜工作台范围'
-Assert-Contains $adminOverseasAgents '服务端分页返回全部稳定来源柜' 'Admin 全柜工作台范围'
+Assert-Contains $adminInboundPageRules '服务端分页返回全部稳定来源柜' 'Admin 全柜工作台范围'
 Assert-Contains $lastlegAgents '分页返回全部稳定来源柜' 'Lastleg 全柜工作台范围'
 Assert-Contains $lastlegBusinessOpenApi '返回全部稳定来源柜' 'Lastleg 全柜工作台 OpenAPI'
-Assert-Contains $adminOverseasAgents 'ACTIVE + FBA' 'Admin FBA 权威仓候选'
-Assert-Contains $adminOverseasAgents '/inbound-plans/convert-container' 'Admin 整柜转换目标入口'
-Assert-Contains $adminOverseasAgents '/inbound-plans/container-preview' 'Admin 整柜预览目标入口'
-Assert-Contains $adminOverseasAgents '同一 `snapshotVersion/snapshotHash` 原样提交' 'Admin 整柜快照确认边界'
+Assert-Contains $adminInboundPageRules 'ACTIVE + FBA' 'Admin FBA 权威仓候选'
+Assert-Contains $adminInboundPageRules '/inbound-plans/convert-container' 'Admin 整柜转换目标入口'
+Assert-Contains $adminInboundPageRules '/inbound-plans/container-preview' 'Admin 整柜预览目标入口'
+Assert-Contains $adminInboundPageRules '同一 `snapshotVersion/snapshotHash` 原样提交' 'Admin 整柜快照确认边界'
 Assert-Contains $adminLastMileApi '/orders/container-summaries' 'Admin 柜级摘要真实调用'
 Assert-Contains $adminLastMileApi '/platform/v1/last-leg/inbound-plans/container-preview' 'Admin 柜级预览真实调用'
 Assert-NotContains $adminLastMileApi '/orders/pending-containers' 'Admin 旧柜级摘要调用'
@@ -1027,12 +1155,12 @@ $financeEventConsumer = Read-RequiredText (Join-Path $backendRoot 'finance/src/m
 $financePhase1Service = Read-RequiredText (Join-Path $backendRoot 'finance/src/main/java/com/baiyue/finance/service/FinancePhase1OperationService.java')
 $overseasFinancePhase0ContractPath = Join-Path $workspaceRoot 'docs/财务管理/海外仓费用统一接入阶段0技术契约.md'
 $overseasFinancePhase0Contract = Read-RequiredText $overseasFinancePhase0ContractPath
-Assert-Contains $businessIndex '财务管理与柜级公共费用分摊' '根柜费分摊快速路由'
-Assert-Contains $businessIndex '海外业务费用来源与客户财务' '根海外费用快速路由'
+Assert-Contains $businessFacts '财务管理与柜级公共费用分摊' '根柜费分摊快速路由'
+Assert-Contains $businessFacts '海外业务费用来源与客户财务' '根海外费用快速路由'
 Assert-Contains $adminAgents '财务、客户资金账户与柜级公共费用分摊' 'Admin 柜费分摊快速路由'
 Assert-Contains $backendAgents '柜级公共费用跨客户分摊' '后端柜费分摊快速路由'
 Assert-Contains $backendAgents '海外业务费用来源跨区入池' '后端海外费用快速路由'
-Assert-Contains $businessIndex '海外仓费用统一接入阶段0技术契约.md' '根海外费用阶段 0 按需入口'
+Assert-Contains $businessFacts '海外仓费用统一接入阶段0技术契约.md' '根海外费用阶段 0 按需入口'
 Assert-Contains $financeAgents '海外仓费用统一接入阶段0技术契约.md' 'Finance 海外费用阶段 0 按需入口'
 Assert-Contains $lastlegAgents '海外仓费用统一接入阶段0技术契约.md' 'Lastleg 海外费用阶段 0 按需入口'
 Assert-Contains $lastlegAgents '不能因文档存在宣称已实现' '阶段 0 设计与代码事实边界'
@@ -1066,16 +1194,16 @@ Assert-Contains $financeBusinessClient '/internal/finance/v1/business-fee-source
 Assert-Contains $financeBusinessClient '/internal/finance/v1/wallet-command-events' 'Finance 资金内部入口'
 Assert-Contains $financeAgents '`eventId + payloadHash` 防重放冲突' 'Finance 海外事件幂等边界'
 Assert-Contains $financeAgents '`PAYABLE + DIRECT_PAID` 审核版本必须生成 `BUSINESS_DIRECT_PAID`' 'Finance 直接已付隔离边界'
-Assert-Contains $businessIndex '入库扣货、解除与凭证' '根入库扣货快速路由'
+Assert-Contains $businessFacts '入库扣货、解除与凭证' '根入库扣货快速路由'
 Assert-Contains $adminAgents '入库扣货、解除与凭证历史' 'Admin 入库扣货快速路由'
 Assert-Contains $backendAgents '入库单扣货、解除、凭证与履约门禁' '后端入库扣货快速路由'
 Assert-Contains $firstlegAgents '入库单扣货、履约门禁与凭证' 'Firstleg 入库扣货入口'
-Assert-Contains $businessIndex '客户资金账户、充值、授信与业务扣费' '根客户钱包快速路由'
+Assert-Contains $businessFacts '客户资金账户、充值、授信与业务扣费' '根客户钱包快速路由'
 Assert-Contains $backendAgents '客户资金账户、充值、授信、冻结、结算与跨区资金指令' '后端客户钱包快速路由'
 Assert-Contains $lastlegAgents '海外业务资金指令与结果' 'Lastleg 跨区钱包入口'
 Assert-Contains $lastlegAgents '拆柜打托成本与客户应收分摊' 'Lastleg 拆柜打托费用入口'
 Assert-Contains $clientAgents '换标申请必须提交正数 CNY `chargeAmount`' 'Client 换标钱包金额边界'
-Assert-Contains $businessIndex '统一认证与服务通信契约.md' '根统一认证契约入口'
+Assert-Contains $businessFacts '统一认证与服务通信契约.md' '根统一认证契约入口'
 Assert-Contains $backendAgents '各端共用 Gateway 和 Redis 会话' '后端统一认证目标'
 $unifiedCommunication = Read-RequiredText (Join-Path $workspaceRoot 'docs/统一认证与服务通信契约.md')
 Assert-Contains $unifiedCommunication 'JWT 不携带角色或权限集合' '统一 JWT 最小身份边界'

scripts/test-environment-pipeline-contract.test.mjs

@@ -17,7 +17,8 @@ const serviceCompose = (await readFile(new URL('../deploy/docker-compose.yml', i
 
 test('both pipelines reject the placeholder registry from failed build 662 before Maven or Docker', () => {
   for (const source of [coordinatorPipeline, pipeline]) {
-    assert.match(source, /string\(name: 'IMAGE_REPOSITORY', defaultValue: ''/)
+    assert.match(source, /string\(name: 'IMAGE_REPOSITORY', defaultValue: params\.IMAGE_REPOSITORY \?: ''/,
+      'declarative parameter refresh must retain this job\'s configured registry instead of resetting it')
     const guard = source.match(/(?:requestedRepository|imageRepository)\.tokenize\('\/'\)\[0\] ==~ \/\(\?i\)([^\n]+)\//)
     assert.ok(guard, 'registry host must reject reserved example domains')
     const reservedHost = new RegExp(`^(?:${guard[1]})$`, 'i')