fix(booking): TEST optional arrival release candidate

Exact deployed baseline plus four reviewed files. Focused cancellation tests: 40 passed.

deploy/sql/README.md

@@ -54,6 +54,8 @@
 
 排车内部散板需求发布选项由 `lastleg-service/src/main/resources/db/dispatch-capacity-demand.sql` 提供精确结构变更：仅向 `ll_dispatch_order` 新增默认勾选的 `publish_looseboard_demand` 列，Lastleg与海外空库基线同步。该文件不是自动启动脚本；执行须单独授权，不能重放完整空库文件，不新增业务数据回填或清理。实际执行与部署状态仍归测试环境主契约。
 
+订舱委/实资料在 `firstleg/src/main/resources/db/phase3-ocean-booking-schema.sql` 与国内统一空库基线同步维护：订舱主表增加条款、包装、品名、唛头和委/实三项货量，关系方增加邮箱、税号；已放舱主表触发器仅允许实际货量及更新审计元数据变化，运输、预报和创建信息冻结。匹配发布单元为 Firstleg 与 Admin；Print 继续使用现有模板。本轮只准备初始化定义，不执行 SQL、不回填测试存量、不提供新旧兼容。已有测试库须另行审阅、授权结构更新，不能重放完整空库基线。
+
 ## 唯一入口与区域边界
 
 V13 收货覆盖由 `lastleg-service/src/main/resources/db/appointment-receiving.sql` 提供四表：独立收货预约、当前/历史客户成员、待确认变化和不可变覆盖版本；同步 Lastleg 与海外空库基线。有效外部约号唯一性归收货预约的目的仓与约号，批次头表不再独立占用约号。部署前必须核对四表及旧头表唯一索引；本批只准备基线，不提供测试存量回填或自动重置。旧 `reset-test-fba-appointments.sql` 已拒绝存在这些新表的环境，不能用于重放 V13 初始化。实际 SQL 与部署须逐项授权。

deploy/sql/头程数据库统一增量-MySQL8.sql

@@ -3442,7 +3442,7 @@ CREATE TABLE fl_mojia_measurement_receipt (
 CREATE TABLE fl_ocean_booking (
   id bigint unsigned NOT NULL COMMENT '海运订舱ID',
   booking_no varchar(40) NOT NULL COMMENT '平台海运订舱编号',
-  status varchar(24) NOT NULL DEFAULT 'DRAFT' COMMENT '订舱状态：DRAFT草稿、RELEASED已发布且永久只读',
+  status varchar(24) NOT NULL DEFAULT 'DRAFT' COMMENT '订舱状态：DRAFT草稿、RELEASED已放舱，运输快照冻结且实货量受控补录',
   customer_id bigint unsigned DEFAULT NULL COMMENT '客户ID和数据隔离键',
   customer_name varchar(128) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '客户名称快照',
   channel_code varchar(64) DEFAULT NULL COMMENT '订舱计划物流渠道组编码快照',
@@ -3465,6 +3465,17 @@ CREATE TABLE fl_ocean_booking (
   estimated_sailing_at datetime(3) DEFAULT NULL COMMENT '当前确认预计开船时间',
   estimated_arrival_at datetime(3) DEFAULT NULL COMMENT '当前确认预计到港时间',
   remark varchar(1000) DEFAULT NULL COMMENT '平台内部备注',
+  freight_term VARCHAR(64) NULL COMMENT '运费条款',
+  service_term VARCHAR(64) NULL COMMENT '运输条款',
+  package_unit VARCHAR(16) NULL COMMENT '包装单位：CARTONS、PCS或PALLETS',
+  cargo_description VARCHAR(1000) NULL COMMENT '货物品名及托运要求',
+  marks_and_nos VARCHAR(1000) NULL COMMENT '唛头和号码',
+  declared_package_count INT UNSIGNED NULL COMMENT '订舱预报件数（委）',
+  declared_gross_weight_kg DECIMAL(15,3) NULL COMMENT '订舱预报毛重kg（委）',
+  declared_volume_cbm DECIMAL(15,3) NULL COMMENT '订舱预报体积cbm（委）',
+  actual_package_count INT UNSIGNED NULL COMMENT '客服手工实货件数',
+  actual_gross_weight_kg DECIMAL(15,3) NULL COMMENT '客服手工实货毛重kg',
+  actual_volume_cbm DECIMAL(15,3) NULL COMMENT '客服手工实货体积cbm',
   created_by bigint unsigned NOT NULL COMMENT '创建操作人ID',
   created_by_name varchar(64) DEFAULT NULL COMMENT '创建操作人姓名快照',
   created_at datetime(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '订舱记录创建时间',
@@ -3479,6 +3490,14 @@ CREATE TABLE fl_ocean_booking (
   KEY idx_ocean_booking_voyage (vessel_name,voyage_no,updated_at),
   CONSTRAINT chk_ocean_booking_carrier_code CHECK (((carrier_code is null) or (carrier_code in (_utf8mb4'MATSON',_utf8mb4'SML',_utf8mb4'ZIM',_utf8mb4'COSCO',_utf8mb4'EMC',_utf8mb4'HEDE',_utf8mb4'OTHER')))),
   CONSTRAINT chk_ocean_booking_customer CHECK ((customer_id > 0)),
+  CONSTRAINT chk_ocean_booking_cargo CHECK (
+    (package_unit IS NULL OR package_unit IN ('CARTONS','PCS','PALLETS'))
+    AND (declared_package_count IS NULL OR declared_package_count BETWEEN 1 AND 999999999)
+    AND (actual_package_count IS NULL OR actual_package_count BETWEEN 1 AND 999999999)
+    AND (declared_gross_weight_kg IS NULL OR declared_gross_weight_kg > 0)
+    AND (actual_gross_weight_kg IS NULL OR actual_gross_weight_kg > 0)
+    AND (declared_volume_cbm IS NULL OR declared_volume_cbm > 0)
+    AND (actual_volume_cbm IS NULL OR actual_volume_cbm > 0)),
   CONSTRAINT chk_ocean_booking_schedule CHECK (((estimated_sailing_at is null) or (estimated_arrival_at is null) or (estimated_arrival_at >= estimated_sailing_at))),
   CONSTRAINT chk_ocean_booking_status CHECK ((status in (_utf8mb4'DRAFT',_utf8mb4'RELEASED')))
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='独立海运订舱聚合；柜次仍由fl_container_booking承载';
@@ -3565,6 +3584,8 @@ CREATE TABLE fl_ocean_booking_party (
   address varchar(1000) DEFAULT NULL COMMENT '关系方地址快照',
   contact_name varchar(128) DEFAULT NULL COMMENT '关系方联系人快照',
   contact_phone varchar(64) DEFAULT NULL COMMENT '关系方联系电话快照',
+  contact_email VARCHAR(255) NULL COMMENT '关系方联系邮箱',
+  tax_no VARCHAR(128) NULL COMMENT '关系方税号',
   PRIMARY KEY (id),
   UNIQUE KEY uk_ocean_booking_party (ocean_booking_id,party_type),
   CONSTRAINT fk_ocean_booking_party FOREIGN KEY (ocean_booking_id) REFERENCES fl_ocean_booking (id) ON DELETE CASCADE,
@@ -6026,9 +6047,49 @@ CREATE TRIGGER trg_ocean_allocation_before_insert BEFORE INSERT ON fl_ocean_book
   END IF;
 END$$
 
-CREATE TRIGGER trg_ocean_booking_before_update BEFORE UPDATE ON fl_ocean_booking FOR EACH ROW BEGIN
-  IF OLD.status = 'RELEASED' THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱订舱不可修改';
+CREATE TRIGGER trg_ocean_booking_before_update BEFORE UPDATE ON fl_ocean_booking FOR EACH ROW
+BEGIN
+  -- 已放舱只允许实货量及其审计元数据变化，运输和预报快照保持冻结。
+  IF OLD.status = 'RELEASED' AND NOT (
+    (NEW.id <=> OLD.id)
+    AND (NEW.booking_no <=> OLD.booking_no)
+    AND (NEW.status <=> OLD.status)
+    AND (NEW.customer_id <=> OLD.customer_id)
+    AND (NEW.customer_name <=> OLD.customer_name)
+    AND (NEW.channel_code <=> OLD.channel_code)
+    AND (NEW.channel_name <=> OLD.channel_name)
+    AND (NEW.warehouse_id <=> OLD.warehouse_id)
+    AND (NEW.warehouse_name <=> OLD.warehouse_name)
+    AND (NEW.bill_of_lading_no <=> OLD.bill_of_lading_no)
+    AND (NEW.shipping_company_id <=> OLD.shipping_company_id)
+    AND (NEW.shipping_company_name <=> OLD.shipping_company_name)
+    AND (NEW.carrier_code <=> OLD.carrier_code)
+    AND (NEW.booking_agent_id <=> OLD.booking_agent_id)
+    AND (NEW.booking_agent_name <=> OLD.booking_agent_name)
+    AND (NEW.vessel_name <=> OLD.vessel_name)
+    AND (NEW.voyage_no <=> OLD.voyage_no)
+    AND (NEW.departure_port_code <=> OLD.departure_port_code)
+    AND (NEW.departure_port_name <=> OLD.departure_port_name)
+    AND (NEW.destination_port_code <=> OLD.destination_port_code)
+    AND (NEW.destination_port_name <=> OLD.destination_port_name)
+    AND (NEW.place_of_delivery <=> OLD.place_of_delivery)
+    AND (NEW.estimated_sailing_at <=> OLD.estimated_sailing_at)
+    AND (NEW.estimated_arrival_at <=> OLD.estimated_arrival_at)
+    AND (NEW.remark <=> OLD.remark)
+    AND (NEW.freight_term <=> OLD.freight_term)
+    AND (NEW.service_term <=> OLD.service_term)
+    AND (NEW.package_unit <=> OLD.package_unit)
+    AND (NEW.cargo_description <=> OLD.cargo_description)
+    AND (NEW.marks_and_nos <=> OLD.marks_and_nos)
+    AND (NEW.declared_package_count <=> OLD.declared_package_count)
+    AND (NEW.declared_gross_weight_kg <=> OLD.declared_gross_weight_kg)
+    AND (NEW.declared_volume_cbm <=> OLD.declared_volume_cbm)
+    AND (NEW.created_by <=> OLD.created_by)
+    AND (NEW.created_by_name <=> OLD.created_by_name)
+    AND (NEW.created_at <=> OLD.created_at)
+    AND NEW.version = OLD.version + 1
+  ) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱运输资料不可修改，仅允许补录实货量';
   END IF;
   IF OLD.status <> NEW.status AND NOT (
        (OLD.status='DRAFT' AND NEW.status='RELEASED')) THEN

finance/src/main/java/com/baiyue/finance/mapper/FinanceFeeSourceReadMapper.java

@@ -0,0 +1,60 @@
+package com.baiyue.finance.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import java.util.List;
+import java.util.Map;
+
+/** 费用池按稳定来源读取当前版本，历史快照保留在同一费用的操作记录中。 */
+@Mapper
+public interface FinanceFeeSourceReadMapper {
+    String GENERATED = "(EXISTS(SELECT 1 FROM fin_bill_line bl WHERE bl.source_id=f.id AND bl.source_version=f.source_fee_version))";
+    String STATUS = "CASE WHEN f.status='AVAILABLE' AND " + GENERATED + " THEN 'BILLED' ELSE f.status END";
+    String BUSINESS_DATE = "CAST(JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.businessDate')) AS DATE)";
+    String FILTER = " FROM fin_fee_source f WHERE 1=1 " +
+        "<if test=\"status == null or status != 'SUPERSEDED'\">" +
+        " AND f.status&lt;&gt;'SUPERSEDED' AND NOT EXISTS(SELECT 1 FROM fin_fee_source newer" +
+        " WHERE newer.source_system=f.source_system AND newer.source_type=f.source_type" +
+        " AND newer.source_fee_id=f.source_fee_id AND newer.source_fee_version&gt;f.source_fee_version)" +
+        "</if>" +
+        "<if test='customerId != null'> AND f.customer_id=#{customerId}</if>" +
+        "<if test='direction != null'> AND f.direction=#{direction}</if>" +
+        "<if test='reviewStatus != null'> AND f.review_status=#{reviewStatus}</if>" +
+        "<if test='status != null'> AND " + STATUS + "=#{status}</if>" +
+        "<if test='statementGenerated != null'> AND " + GENERATED + "=#{statementGenerated}</if>" +
+        "<if test='dateFrom != null'> AND " + BUSINESS_DATE + "&gt;=#{dateFrom}</if>" +
+        "<if test='dateTo != null'> AND " + BUSINESS_DATE + "&lt;=#{dateTo}</if>" +
+        "<if test='keyword != null'> AND (f.source_no LIKE CONCAT('%',#{keyword},'%')" +
+        " OR f.fee_item_name LIKE CONCAT('%',#{keyword},'%')" +
+        " OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.customerName')) LIKE CONCAT('%',#{keyword},'%')" +
+        " OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.inboundCode')) LIKE CONCAT('%',#{keyword},'%')" +
+        " OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.containerNo')) LIKE CONCAT('%',#{keyword},'%')" +
+        " OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.supplierName')) LIKE CONCAT('%',#{keyword},'%'))</if>";
+
+    /** 筛选和计数共用当前版本条件，不能先分页再去重。 */
+    @Select("<script>SELECT COUNT(*)" + FILTER + "</script>")
+    long count(Map<String, Object> filters);
+
+    /** 应收、应付分别展示当前快照；同名但来源费用号不同的费用不合并。 */
+    @Select("<script>SELECT f.*," + GENERATED + " statement_generated," + STATUS + " effective_status" + FILTER +
+        " ORDER BY " + BUSINESS_DATE + " DESC,f.id DESC LIMIT #{limit} OFFSET #{offset}</script>")
+    List<Map<String, Object>> list(Map<String, Object> filters);
+
+    String LINEAGE = " FROM fin_fee_source anchor JOIN fin_fee_source f ON f.source_system=anchor.source_system" +
+        " AND f.source_type=anchor.source_type AND f.source_fee_id=anchor.source_fee_id" +
+        " AND f.customer_id=anchor.customer_id AND f.direction=anchor.direction" +
+        " AND f.source_fee_version&lt;=anchor.source_fee_version";
+
+    /** 旧版本链接只读取当时及此前快照，不把后续调整倒灌到历史单据。 */
+    @Select("<script>SELECT f.id,f.source_fee_version,f.amount,f.currency_code,f.created_at" + LINEAGE +
+        " WHERE anchor.id=#{id} AND anchor.customer_id=#{customerId}" +
+        " AND f.source_system IN ('FIRSTLEG','LASTLEG') ORDER BY f.source_fee_version,f.id</script>")
+    List<Map<String, Object>> versions(@Param("customerId") long customerId, @Param("id") long id);
+
+    /** 按来源身份串起历次审核和操作，客户与方向边界不能被同名费用跨越。 */
+    @Select("<script>SELECT a.id,a.created_at,a.action,a.operator_name_snapshot,a.reason,a.before_data,a.after_data" + LINEAGE +
+        " JOIN fin_audit_log a ON a.tenant_id=f.customer_id AND a.resource_type='FIN_FEE_SOURCE' AND a.resource_id=f.id" +
+        " WHERE anchor.id=#{id} AND anchor.customer_id=#{customerId} ORDER BY a.created_at DESC,a.id DESC</script>")
+    List<Map<String, Object>> audits(@Param("customerId") long customerId, @Param("id") long id);
+}

finance/src/main/java/com/baiyue/finance/repository/FinanceFeeSourceReadRepository.java

@@ -0,0 +1,145 @@
+package com.baiyue.finance.repository;
+
+import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceSummary;
+import com.baiyue.finance.dto.FinancePhase1Dtos.OperationLog;
+import com.baiyue.finance.mapper.FinanceFeeSourceReadMapper;
+import com.baiyue.finance.service.FinanceEventException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.springframework.stereotype.Repository;
+import org.springframework.util.LinkedCaseInsensitiveMap;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.sql.Timestamp;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/** 费用当前投影及操作历史；版本记录只读，不覆盖账单引用的不可变快照。 */
+@Repository
+public class FinanceFeeSourceReadRepository {
+    private final FinanceFeeSourceReadMapper mapper;
+    private final ObjectMapper json;
+
+    /** 注入正式持久化入口与费用快照解析器。 */
+    public FinanceFeeSourceReadRepository(FinanceFeeSourceReadMapper mapper, ObjectMapper json) {
+        this.mapper = mapper;
+        this.json = json;
+    }
+
+    /** 组装统一查询参数，让计数和分页使用相同来源身份与筛选条件。 */
+    public Map<String, Object> filters(Long customerId, String direction, String status, String reviewStatus,
+                                      Boolean generated, LocalDate from, LocalDate to, String keyword, int page, int size) {
+        Map<String, Object> values = new HashMap<>();
+        values.put("customerId", customerId); values.put("direction", direction); values.put("status", status);
+        values.put("reviewStatus", reviewStatus); values.put("statementGenerated", generated);
+        values.put("dateFrom", from); values.put("dateTo", to); values.put("keyword", keyword);
+        values.put("limit", size); values.put("offset", (page - 1) * size);
+        return values;
+    }
+
+    /** 计数只包含所筛选的当前费用，历史状态专项查询除外。 */
+    public long count(Map<String, Object> filters) { return mapper.count(filters); }
+
+    /** 当前费用映射沿用原币、数量、客户等正式字段。 */
+    public List<FeeSourceSummary> list(Map<String, Object> filters) {
+        return mapper.list(filters).stream().map(this::summary).toList();
+    }
+
+    /** 由不可变版本追加同步历史，并串联同一费用所有既有审计记录。 */
+    public List<OperationLog> logs(long customerId, long id) {
+        List<OperationLog> result = new ArrayList<>();
+        Map<String, Object> previous = null;
+        for (Map<String, Object> raw : mapper.versions(customerId, id)) {
+            Map<String, Object> row = row(raw);
+            String version = "来源版本 " + row.get("source_fee_version");
+            String amount = amount(row) + " " + row.get("currency_code");
+            // 同步时间与原业务操作者不能混用，原业务审批仍以来源系统记录为准。
+            result.add(new OperationLog(time(row.get("created_at")),
+                previous == null ? "FEE_SOURCE_PUBLISHED" : "FEE_SOURCE_VERSION_ADJUST",
+                "系统同步", "SUCCESS", previous == null ? version + "；金额 " + amount
+                    : "来源版本 " + previous.get("source_fee_version") + " → " + row.get("source_fee_version")
+                        + "；金额 " + amount(previous) + " → " + amount));
+            previous = row;
+        }
+        // 金额差分仍按版本升序计算；展示先反转版本，同毫秒时稳定排序保留新版本在前。
+        java.util.Collections.reverse(result);
+        for (Map<String, Object> raw : mapper.audits(customerId, id)) {
+            Map<String, Object> row = row(raw);
+            String remark = text(row.get("reason"));
+            JsonNode before = parse(row.get("before_data"));
+            JsonNode after = parse(row.get("after_data"));
+            if (before.hasNonNull("amount") && after.hasNonNull("amount")
+                && before.path("amount").decimalValue().compareTo(after.path("amount").decimalValue()) != 0) {
+                remark = (remark == null ? "" : remark + "；") + "金额 " + before.path("amount").asText()
+                    + " → " + after.path("amount").asText() + " " + after.path("currency").asText("CNY");
+            }
+            result.add(new OperationLog(time(row.get("created_at")), text(row.get("action")),
+                text(row.get("operator_name_snapshot")), "SUCCESS", remark));
+        }
+        // 时间排序保持同毫秒版本的新到旧顺序，以及 Mapper 返回的审计 ID 倒序。
+        result.sort(Comparator.comparing(OperationLog::occurredAt, Comparator.nullsLast(Comparator.reverseOrder())));
+        return List.copyOf(result);
+    }
+
+    /** 将持久化快照转换为费用列表 DTO，不从其他客户或来源补齐业务事实。 */
+    private FeeSourceSummary summary(Map<String, Object> raw) {
+        Map<String, Object> row = row(raw);
+        JsonNode snapshot = parse(row.get("source_snapshot"));
+        BigDecimal amount = decimal(row.get("amount"));
+        BigDecimal originalAmount = first(decimal(text(snapshot, "originalAmount")), amount);
+        BigDecimal quantity = decimal(text(snapshot, "chargeableQuantity"));
+        BigDecimal unitPrice = first(decimal(text(snapshot, "unitPrice")), quantity != null && quantity.signum() > 0
+            ? originalAmount.divide(quantity, 6, RoundingMode.HALF_UP) : null);
+        return new FeeSourceSummary(number(row.get("id")), text(row.get("source_system")), text(row.get("source_type")),
+            first(text(row.get("source_no")), text(snapshot, "sourceBusinessId")), number(row.get("source_fee_id")),
+            ((Number) row.get("source_fee_version")).intValue(), text(row.get("direction")), number(row.get("customer_id")),
+            text(snapshot, "customerName"), positiveLong(text(snapshot, "supplierId")), text(snapshot, "supplierName"),
+            nullableLong(row.get("order_id")), nullableLong(row.get("inbound_id")), text(snapshot, "inboundCode"),
+            nullableLong(row.get("container_id")), text(snapshot, "containerNo"),
+            first(date(text(snapshot, "businessDate")), LocalDate.of(1970, 1, 1)), text(row.get("fee_item_name")),
+            quantity, text(snapshot, "quantityUnit"), unitPrice, date(text(snapshot, "periodStart")), date(text(snapshot, "periodEnd")),
+            amount, text(row.get("currency_code")), first(text(snapshot, "originalCurrency"), text(row.get("currency_code"))),
+            originalAmount, first(decimal(text(snapshot, "exchangeRate")), BigDecimal.ONE), text(snapshot, "exchangeRateMonth"),
+            first(text(row.get("review_status")), "DRAFT"), text(row.get("effective_status")),
+            Boolean.TRUE.equals(row.get("statement_generated")) || row.get("statement_generated") instanceof Number value && value.intValue() != 0);
+    }
+
+    /** 保留不同数据库驱动的列名大小写读取语义。 */
+    private static Map<String, Object> row(Map<String, Object> source) {
+        Map<String, Object> result = new LinkedCaseInsensitiveMap<>(); result.putAll(source); return result;
+    }
+    /** 解析不可变快照，损坏数据失败关闭。 */
+    private JsonNode parse(Object value) {
+        try { return value == null ? json.createObjectNode() : json.readTree(value.toString()); }
+        catch (Exception failure) { throw new FinanceEventException("FIN-DATA-500", "费用来源快照损坏"); }
+    }
+    /** 格式化记录金额，保留定点精度。 */
+    private static String amount(Map<String, Object> row) { return decimal(row.get("amount")).toPlainString(); }
+    /** 读取驱动返回的标准时间。 */
+    private static LocalDateTime time(Object value) { return value instanceof Timestamp time ? time.toLocalDateTime() : (LocalDateTime) value; }
+    /** 读取数字主键，仅用于数据引用。 */
+    private static long number(Object value) { return ((Number) value).longValue(); }
+    /** 保留未关联的可空引用。 */
+    private static Long nullableLong(Object value) { return value == null ? null : number(value); }
+    /** 只接受合法的正整型供应商引用。 */
+    private static Long positiveLong(String value) {
+        try { long parsed = Long.parseLong(value); return parsed > 0 ? parsed : null; }
+        catch (NumberFormatException failure) { return null; }
+    }
+    /** 读取可空金额，不经过浮点转换。 */
+    private static BigDecimal decimal(Object value) { return value == null ? null : new BigDecimal(value.toString()); }
+    /** 读取可空业务日期。 */
+    private static LocalDate date(String value) { return value == null ? null : LocalDate.parse(value); }
+    /** 保持空字段的缺失语义。 */
+    private static String text(Object value) { return value == null || value.toString().isBlank() ? null : value.toString(); }
+    /** 读取快照字段。 */
+    private static String text(JsonNode node, String field) { return node.path(field).isNull() || node.path(field).isMissingNode() ? null : text(node.path(field).asText()); }
+    /** 优先使用来源字段，其次使用已有正式默认值。 */
+    private static <T> T first(T value, T fallback) { return value == null ? fallback : value; }
+}

finance/src/main/java/com/baiyue/finance/service/FinancePhase1OperationService.java

@@ -1,10 +1,10 @@
 package com.baiyue.finance.service;
 
+import com.baiyue.finance.repository.FinanceFeeSourceReadRepository;
 import com.baiyue.finance.dto.FinancePhase1Dtos.AccountSummary;
 import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceDetail;
 import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceSummary;
 import com.baiyue.finance.dto.FinancePhase1Dtos.LedgerEntry;
-import com.baiyue.finance.dto.FinancePhase1Dtos.OperationLog;
 import com.baiyue.finance.dto.FinancePhase1Dtos.PageEnvelope;
 import com.baiyue.finance.dto.FinancePhase1Dtos.ReviewRequest;
 import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceActionRequest;
@@ -44,19 +44,19 @@ public class FinancePhase1OperationService {
     private final ObjectMapper objectMapper;
     private final FirstlegFeeSourceClient firstleg;
     private final String internalToken;
+    private final FinanceFeeSourceReadRepository feeSources;
 
+    /** 注入费用来源查询及现有业务依赖。 */
     @Autowired
     public FinancePhase1OperationService(JdbcTemplate jdbc, ObjectMapper objectMapper,
                                          FirstlegFeeSourceClient firstleg,
-                                         @Value("${baiyue.security.internal-service-token}") String internalToken) {
+                                         @Value("${baiyue.security.internal-service-token}") String internalToken,
+                                         FinanceFeeSourceReadRepository feeSources) {
         this.jdbc = jdbc;
         this.objectMapper = objectMapper;
         this.firstleg = firstleg;
         this.internalToken = internalToken;
-    }
-
-    public FinancePhase1OperationService(JdbcTemplate jdbc, ObjectMapper objectMapper) {
-        this(jdbc, objectMapper, null, "");
+        this.feeSources = feeSources;
     }
 
     public PageEnvelope<AccountSummary> listDerivedCustomerAccounts(int page, int pageSize, String customerName, String status) {
@@ -163,6 +163,7 @@ public class FinancePhase1OperationService {
         return PageEnvelope.success(List.copyOf(projected.subList(from, to)), page, pageSize, projected.size());
     }
 
+    /** 按同一来源费用的当前版本分页，调整历史不重复计入客户应收应付。 */
     public PageEnvelope<FeeSourceSummary> listFinanceFeeSources(int page, int pageSize, Long customerId,
                                                                  String direction, String sourceStatus,
                                                                  String reviewStatus,
@@ -178,34 +179,9 @@ public class FinancePhase1OperationService {
             List.of("DRAFT", "PENDING", "APPROVED", "REJECTED"), "审核状态无效");
         String normalizedSourceStatus = normalized(sourceStatus,
             List.of("AVAILABLE", "LOCKED", "BILLED", "SETTLED", "VOIDED", "SUPERSEDED"), "费用来源状态无效");
-        String generatedSql = "EXISTS(SELECT 1 FROM fin_bill_line bl WHERE bl.source_id=f.id AND bl.source_version=f.source_fee_version)";
-        String effectiveStatusSql = "CASE WHEN f.status='AVAILABLE' AND " + generatedSql + " THEN 'BILLED' ELSE f.status END";
-        String businessDateSql = "STR_TO_DATE(JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.businessDate')),'%Y-%m-%d')";
-        StringBuilder where = new StringBuilder(" FROM fin_fee_source f WHERE 1=1");
-        List<Object> args = new ArrayList<>();
-        if (customerId != null) { where.append(" AND f.customer_id=?"); args.add(customerId); }
-        if (normalizedDirection != null) { where.append(" AND f.direction=?"); args.add(normalizedDirection); }
-        if (normalizedReview != null) { where.append(" AND f.review_status=?"); args.add(normalizedReview); }
-        if (normalizedSourceStatus != null) { where.append(" AND ").append(effectiveStatusSql).append("=?"); args.add(normalizedSourceStatus); }
-        if (statementGenerated != null) { where.append(" AND ").append(generatedSql).append("=?"); args.add(statementGenerated); }
-        if (businessDateFrom != null) { where.append(" AND ").append(businessDateSql).append(">=?"); args.add(businessDateFrom); }
-        if (businessDateTo != null) { where.append(" AND ").append(businessDateSql).append("<=?"); args.add(businessDateTo); }
-        String normalizedKeyword = blankToNull(keyword);
-        if (normalizedKeyword != null) {
-            where.append(" AND (f.source_no LIKE CONCAT('%',?,'%') OR f.fee_item_name LIKE CONCAT('%',?,'%')")
-                .append(" OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.customerName')) LIKE CONCAT('%',?,'%')")
-                .append(" OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.inboundCode')) LIKE CONCAT('%',?,'%')")
-                .append(" OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.containerNo')) LIKE CONCAT('%',?,'%')")
-                .append(" OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.supplierName')) LIKE CONCAT('%',?,'%'))");
-            for (int i = 0; i < 6; i++) args.add(normalizedKeyword);
-        }
-        Long total = jdbc.queryForObject("SELECT COUNT(*)" + where, Long.class, args.toArray());
-        List<Object> queryArgs = new ArrayList<>(args);
-        queryArgs.add(pageSize); queryArgs.add((page - 1) * pageSize);
-        String select = "SELECT f.*," + generatedSql + " statement_generated," + effectiveStatusSql + " effective_status" +
-            where + " ORDER BY " + businessDateSql + " DESC,f.id DESC LIMIT ? OFFSET ?";
-        List<FeeSourceSummary> rows = jdbc.query(select, (rs, n) -> summary(rs), queryArgs.toArray());
-        return PageEnvelope.success(rows, page, pageSize, total == null ? 0 : total);
+        Map<String, Object> filters = feeSources.filters(customerId, normalizedDirection, normalizedSourceStatus,
+            normalizedReview, statementGenerated, businessDateFrom, businessDateTo, blankToNull(keyword), page, pageSize);
+        return PageEnvelope.success(feeSources.list(filters), page, pageSize, feeSources.count(filters));
     }
 
     public FeeSourceDetail getFinanceFeeSource(long feeSourceId) {
@@ -339,6 +315,7 @@ public class FinancePhase1OperationService {
         return after;
     }
 
+    /** 读取指定不可变版本，并附带同客户同方向的费用调整历史。 */
     private FeeSourceDetail detail(ResultSet rs) throws SQLException {
         JsonNode snapshot = parse(rs.getString("source_snapshot"));
         long id = rs.getLong("id");
@@ -356,33 +333,7 @@ public class FinancePhase1OperationService {
             amount, rs.getString("currency_code"), firstText(text(snapshot, "originalCurrency"), rs.getString("currency_code")), originalAmount,
             firstDecimal(decimal(snapshot, "exchangeRate"), BigDecimal.ONE), text(snapshot, "exchangeRateMonth"),
             defaultString(rs.getString("review_status"), "DRAFT"), status, generated,
-            rs.getString("review_reason"), rs.getString("source_hash"), rs.getInt("operation_version"), logs(rs.getLong("customer_id"), id));
-    }
-
-    private FeeSourceSummary summary(ResultSet rs) throws SQLException {
-        JsonNode snapshot = parse(rs.getString("source_snapshot"));
-        boolean generated = rs.getBoolean("statement_generated");
-        BigDecimal quantity = decimal(snapshot, "chargeableQuantity");
-        BigDecimal amount = money(rs, "amount");
-        BigDecimal originalAmount = firstDecimal(decimal(snapshot, "originalAmount"), amount);
-        BigDecimal unitPrice = firstDecimal(decimal(snapshot, "unitPrice"), quantity != null && quantity.signum() > 0
-            ? originalAmount.divide(quantity, 6, java.math.RoundingMode.HALF_UP) : null);
-        return new FeeSourceSummary(rs.getLong("id"), rs.getString("source_system"), rs.getString("source_type"),
-            firstText(rs.getString("source_no"), text(snapshot, "sourceBusinessId")), rs.getLong("source_fee_id"), rs.getInt("source_fee_version"),
-            rs.getString("direction"), rs.getLong("customer_id"), text(snapshot, "customerName"),
-            jsonLong(snapshot, "supplierId"), text(snapshot, "supplierName"), nullableLong(rs, "order_id"),
-            nullableLong(rs, "inbound_id"), text(snapshot, "inboundCode"), nullableLong(rs, "container_id"),
-            text(snapshot, "containerNo"), date(snapshot, "businessDate"), rs.getString("fee_item_name"),
-            quantity, text(snapshot, "quantityUnit"), unitPrice, nullableDate(snapshot, "periodStart"), nullableDate(snapshot, "periodEnd"),
-            amount, rs.getString("currency_code"), firstText(text(snapshot, "originalCurrency"), rs.getString("currency_code")), originalAmount,
-            firstDecimal(decimal(snapshot, "exchangeRate"), BigDecimal.ONE), text(snapshot, "exchangeRateMonth"),
-            defaultString(rs.getString("review_status"), "DRAFT"),
-            rs.getString("effective_status"), generated);
-    }
-
-    private List<OperationLog> logs(long customerId, long id) {
-        return jdbc.query("SELECT created_at,action,operator_name_snapshot,reason FROM fin_audit_log WHERE tenant_id=? AND resource_type='FIN_FEE_SOURCE' AND resource_id=? ORDER BY created_at DESC,id DESC", (rs, n) ->
-            new OperationLog(time(rs, "created_at"), rs.getString("action"), rs.getString("operator_name_snapshot"), "SUCCESS", rs.getString("reason")), customerId, id);
+            rs.getString("review_reason"), rs.getString("source_hash"), rs.getInt("operation_version"), feeSources.logs(rs.getLong("customer_id"), id));
     }
 
     private Long reserve(long customerId, long operatorId, String operation, String key, String method, String path, Object body) {

finance/src/test/java/com/baiyue/finance/FinanceContractTest.java

@@ -17,6 +17,7 @@ class FinanceContractTest {
             .getAnnotation(org.springframework.scheduling.annotation.EnableScheduling.class));
     }
 
+    /** 固定财务访问域与账单关联键，查询迁入 Mapper 后仍核对真实来源记录。 */
     @Test
     void controllersUseFrozenFinancePaths() throws Exception {
         assertEquals("/api/platform/finance/v1", PlatformFinanceController.class.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class).value()[0]);
@@ -40,7 +41,8 @@ class FinanceContractTest {
         assertTrue(controller.contains("costSnapshotClient.loadingPlan") && controller.contains("createCost(request.customerId(), user.userId(), internal, volumes, key)"));
         assertTrue(service.contains("validateVoucherFiles(tenantId, request.voucherFileIds())"));
         String operations = Files.readString(Path.of("src/main/java/com/baiyue/finance/service/FinancePhase1OperationService.java"));
-        assertTrue(operations.contains("bl.source_id=f.id"));
+        String feeReads = Files.readString(Path.of("src/main/java/com/baiyue/finance/mapper/FinanceFeeSourceReadMapper.java"));
+        assertTrue(feeReads.contains("bl.source_id=f.id"));
         assertTrue(operations.contains("Boolean.class, id, rs.getInt(\"source_fee_version\")"));
         assertFalse(operations.contains("bl.source_id=f.source_fee_id"));
         String unified = Files.readString(Path.of("../deploy/sql/头程数据库统一增量-MySQL8.sql"));

finance/src/test/java/com/baiyue/finance/FinanceFeeSourceReadMapperTest.java

@@ -0,0 +1,141 @@
+package com.baiyue.finance;
+
+import com.baiyue.finance.mapper.FinanceFeeSourceReadMapper;
+import com.baiyue.finance.repository.FinanceFeeSourceReadRepository;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.session.Configuration;
+import org.apache.ibatis.session.SqlSessionFactoryBuilder;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.datasource.DriverManagerDataSource;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** 隔离数据库执行正式 Mapper，验证版本归并与历史不会改变金额和客户归属。 */
+public class FinanceFeeSourceReadMapperTest {
+    /** 应收和应付均以来源身份替换当前展示，同名费用、其他来源类型和系统保持独立。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"RECEIVABLE", "PAYABLE"})
+    void currentProjectionAndHistoryKeepStableFeeIdentity(String direction) {
+        var data = new DriverManagerDataSource("jdbc:h2:mem:fee-current-" + UUID.randomUUID() + ";MODE=MySQL", "sa", "");
+        var jdbc = new JdbcTemplate(data);
+        // 保持一个会话存活；Mapper 使用同一隔离数据库，绝不访问共享测试环境。
+        try (var connection = data.getConnection()) {
+            jdbc.execute("CREATE ALIAS JSON_EXTRACT FOR 'com.baiyue.finance.FinanceFeeSourceReadMapperTest.jsonExtract'");
+            jdbc.execute("CREATE ALIAS JSON_UNQUOTE FOR 'com.baiyue.finance.FinanceFeeSourceReadMapperTest.jsonUnquote'");
+            jdbc.execute("CREATE TABLE fin_fee_source(id BIGINT PRIMARY KEY,source_system VARCHAR(32),source_type VARCHAR(32),source_fee_id BIGINT,source_fee_version INT,customer_id BIGINT,direction VARCHAR(16),source_no VARCHAR(64),fee_item_name VARCHAR(100),amount DECIMAL(20,6),currency_code VARCHAR(3),review_status VARCHAR(16),status VARCHAR(16),source_snapshot VARCHAR(2000),order_id BIGINT,inbound_id BIGINT,container_id BIGINT,created_at TIMESTAMP)");
+            jdbc.execute("CREATE TABLE fin_bill_line(source_id BIGINT,source_version INT)");
+            jdbc.execute("CREATE TABLE fin_audit_log(id BIGINT PRIMARY KEY,tenant_id BIGINT,resource_type VARCHAR(32),resource_id BIGINT,action VARCHAR(64),operator_name_snapshot VARCHAR(64),reason VARCHAR(100),before_data VARCHAR(1000),after_data VARCHAR(1000),created_at TIMESTAMP)");
+            insert(jdbc, 1, "FIRSTLEG", "INBOUND_FEE", 700, 1, 9, direction, "SUPERSEDED", "100.00");
+            insert(jdbc, 2, "FIRSTLEG", "INBOUND_FEE", 700, 2, 9, direction, "AVAILABLE", "120.00");
+            insert(jdbc, 3, "FIRSTLEG", "INBOUND_FEE", 701, 1, 9, direction, "AVAILABLE", "80.00");
+            insert(jdbc, 4, "FIRSTLEG", "INBOUND_FEE", 702, 1, 9, direction, "AVAILABLE", "50.00");
+            insert(jdbc, 5, "FIRSTLEG", "INBOUND_FEE", 702, 2, 9, direction, "VOIDED", "70.00");
+            insert(jdbc, 6, "LASTLEG", "INBOUND_FEE", 700, 1, 9, direction, "AVAILABLE", "33.00");
+            insert(jdbc, 7, "FIRSTLEG", "CONTAINER_FEE", 700, 1, 9, direction, "AVAILABLE", "44.00");
+            insert(jdbc, 8, "FIRSTLEG", "INBOUND_FEE", 703, 1, 10, direction, "AVAILABLE", "55.00");
+            jdbc.update("INSERT INTO fin_audit_log VALUES(1,9,'FIN_FEE_SOURCE',1,'FEE_SOURCE_REVIEW_APPROVE','审核员','原费用审核',NULL,NULL,'2026-10-21 10:01:30')");
+            jdbc.update("INSERT INTO fin_audit_log VALUES(2,9,'FIN_FEE_SOURCE',2,'FEE_SOURCE_ADJUST','财务员','更正费用','{\"amount\":100}','{\"amount\":120,\"currency\":\"CNY\"}','2026-10-21 10:03:00')");
+            jdbc.update("INSERT INTO fin_audit_log VALUES(3,9,'FIN_FEE_SOURCE',3,'FEE_SOURCE_ADJUST','其他费用','不能合并',NULL,NULL,'2026-10-21 10:04:00')");
+            jdbc.update("INSERT INTO fin_audit_log VALUES(4,10,'FIN_FEE_SOURCE',1,'FEE_SOURCE_ADJUST','其他客户','不能越界',NULL,NULL,'2026-10-21 10:04:00')");
+
+            var configuration = new Configuration(new Environment("test", new JdbcTransactionFactory(), data));
+            configuration.addMapper(FinanceFeeSourceReadMapper.class);
+            try (var session = new SqlSessionFactoryBuilder().build(configuration).openSession()) {
+                var repository = new FinanceFeeSourceReadRepository(session.getMapper(FinanceFeeSourceReadMapper.class), new ObjectMapper());
+                var filters = repository.filters(9L, direction, null, "APPROVED", false,
+                    LocalDate.of(2026, 10, 1), LocalDate.of(2026, 10, 31), "操作费", 1, 20);
+                assertThat(repository.count(filters)).isEqualTo(5);
+                var rows = repository.list(filters);
+                assertThat(rows).extracting(row -> row.feeSourceId()).containsExactly(7L, 6L, 5L, 3L, 2L);
+                assertThat(rows.stream().map(row -> row.amount()).reduce(BigDecimal.ZERO, BigDecimal::add))
+                    .isEqualByComparingTo("347.00");
+                assertThat(rows).allSatisfy(row -> {
+                    assertThat(row.direction()).isEqualTo(direction);
+                    assertThat(row.customerId()).isEqualTo(9);
+                    assertThat(row.supplierId()).isEqualTo(79);
+                    assertThat(row.inboundCode()).isEqualTo("IN-9");
+                    assertThat(row.businessDate()).isEqualTo(LocalDate.of(2026, 10, 21));
+                    assertThat(row.originalAmount()).isEqualByComparingTo("200");
+                    assertThat(row.unitPrice()).isEqualByComparingTo("20");
+                });
+                filters.put("limit", 2);
+                filters.put("offset", 2);
+                assertThat(repository.count(filters)).isEqualTo(5);
+                assertThat(repository.list(filters)).extracting(row -> row.feeSourceId()).containsExactly(5L, 3L);
+                filters.put("limit", 20); filters.put("offset", 0); filters.put("status", "AVAILABLE");
+                assertThat(repository.count(filters)).isEqualTo(4);
+                assertThat(repository.list(filters)).extracting(row -> row.feeSourceId()).doesNotContain(4L, 5L);
+                filters.put("status", "SUPERSEDED");
+                assertThat(repository.list(filters)).extracting(row -> row.feeSourceId()).containsExactly(1L);
+
+                var logs = repository.logs(9, 2);
+                assertThat(logs).hasSize(4);
+                assertThat(logs).extracting(log -> log.action()).containsExactly(
+                    "FEE_SOURCE_ADJUST", "FEE_SOURCE_VERSION_ADJUST", "FEE_SOURCE_REVIEW_APPROVE", "FEE_SOURCE_PUBLISHED");
+                assertThat(logs.get(0).remark()).isEqualTo("更正费用；金额 100 → 120 CNY");
+                assertThat(logs.get(1).remark()).contains("来源版本 1 → 2", "100.000000 → 120.000000 CNY");
+                assertThat(logs).noneSatisfy(log -> assertThat(log.operatorName()).startsWith("其他"));
+                assertThat(repository.logs(9, 2)).isEqualTo(logs);
+                assertThat(repository.logs(9, 1)).hasSize(2);
+                assertThat(repository.logs(10, 2)).isEmpty();
+                // 同毫秒必须先展示新版本；审计仍按 ID 倒序，不能反转金额差分或突破旧版本锚点。
+                jdbc.update("UPDATE fin_fee_source SET created_at='2026-10-21 10:03:00.123' WHERE id IN (1,2)");
+                jdbc.update("UPDATE fin_audit_log SET created_at='2026-10-21 10:03:00.123' WHERE id IN (1,2)");
+                jdbc.update("INSERT INTO fin_audit_log VALUES(6,9,'FIN_FEE_SOURCE',2,'FEE_SOURCE_REVIEW_APPROVE','审核员','同毫秒后审计',NULL,NULL,'2026-10-21 10:03:00.123')");
+                session.clearCache();
+                var sameTimeLogs = repository.logs(9, 2);
+                assertThat(sameTimeLogs).extracting(log -> log.action()).containsExactly(
+                    "FEE_SOURCE_VERSION_ADJUST", "FEE_SOURCE_PUBLISHED", "FEE_SOURCE_REVIEW_APPROVE",
+                    "FEE_SOURCE_ADJUST", "FEE_SOURCE_REVIEW_APPROVE");
+                assertThat(sameTimeLogs.get(0).remark()).contains("来源版本 1 → 2", "100.000000 → 120.000000 CNY");
+                assertThat(sameTimeLogs.get(1).remark()).contains("来源版本 1；金额 100.000000 CNY");
+                assertThat(sameTimeLogs.subList(2, 5)).extracting(log -> log.remark()).containsExactly(
+                    "同毫秒后审计", "更正费用；金额 100 → 120 CNY", "原费用审核");
+                assertThat(repository.logs(9, 2)).isEqualTo(sameTimeLogs);
+                assertThat(repository.logs(9, 1)).extracting(log -> log.action()).containsExactly(
+                    "FEE_SOURCE_PUBLISHED", "FEE_SOURCE_REVIEW_APPROVE");
+                assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM fin_fee_source", Long.class)).isEqualTo(8);
+                jdbc.update("INSERT INTO fin_bill_line VALUES(2,2)");
+                filters.put("status", "BILLED"); filters.put("statementGenerated", true);
+                assertThat(repository.count(filters)).isEqualTo(1);
+                assertThat(repository.list(filters)).extracting(row -> row.feeSourceId()).containsExactly(2L);
+
+                // 财务内部费用原地改金额，其历史只取真实审计，不能伪造旧时间的同步金额。
+                insert(jdbc, 9, "FINANCE", "MANUAL", 700, 1, 9, direction, "AVAILABLE", "120.00");
+                jdbc.update("INSERT INTO fin_audit_log VALUES(5,9,'FIN_FEE_SOURCE',9,'FEE_SOURCE_ADJUST','财务员','更正人工费用','{\"amount\":100}','{\"amount\":120,\"currency\":\"CNY\"}','2026-10-21 10:05:00')");
+                assertThat(repository.logs(9, 9)).singleElement().satisfies(log -> {
+                    assertThat(log.action()).isEqualTo("FEE_SOURCE_ADJUST");
+                    assertThat(log.remark()).isEqualTo("更正人工费用；金额 100 → 120 CNY");
+                });
+            }
+        } catch (java.sql.SQLException failure) { throw new AssertionError(failure); }
+    }
+
+    /** 准备具有相同名称、不同稳定来源的隔离费用快照。 */
+    private static void insert(JdbcTemplate jdbc, long id, String system, String type, long fee, int version,
+                               long customer, String direction, String status, String amount) {
+        jdbc.update("INSERT INTO fin_fee_source(id,source_system,source_type,source_fee_id,source_fee_version,customer_id,direction,source_no,fee_item_name,amount,currency_code,review_status,status,source_snapshot,created_at) VALUES(?,?,?,?,?,?,?,'IN-9','操作费',?,'CNY','APPROVED',?,?,?)",
+            id, system, type, fee, version, customer, direction, new BigDecimal(amount), status,
+            "{\"businessDate\":\"2026-10-21\",\"supplierId\":79,\"inboundCode\":\"IN-9\",\"chargeableQuantity\":10,\"originalAmount\":200}",
+            java.sql.Timestamp.valueOf("2026-10-21 10:0" + version + ":00"));
+    }
+
+    /** H2 仅补足 MySQL JSON 读取函数，实际筛选、关联和分页仍执行正式 SQL。 */
+    public static String jsonExtract(String value, String path) throws Exception {
+        var node = new ObjectMapper().readTree(value).path(path.substring(2));
+        return node.isMissingNode() || node.isNull() ? null : node.toString();
+    }
+
+    /** 对测试 JSON 标量解引号，保持 MySQL 空值语义。 */
+    public static String jsonUnquote(String value) throws Exception {
+        return value == null ? null : new ObjectMapper().readTree(value).asText();
+    }
+}

finance/src/test/java/com/baiyue/finance/FinancePhase1OperationBehaviorTest.java

@@ -9,10 +9,13 @@ import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceDetail;
 import com.baiyue.finance.dto.FinancePhase1Dtos.PageEnvelope;
 import com.baiyue.finance.service.FinanceEventException;
 import com.baiyue.finance.service.FinancePhase1OperationService;
+import com.baiyue.finance.repository.FinanceFeeSourceReadRepository;
 import com.baiyue.finance.service.FinanceCustomerAccountService;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springframework.jdbc.core.JdbcTemplate;
@@ -40,6 +43,9 @@ import static org.mockito.Mockito.lenient;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.times;
 
 @ExtendWith(MockitoExtension.class)
 class FinancePhase1OperationBehaviorTest {
@@ -81,18 +87,20 @@ class FinancePhase1OperationBehaviorTest {
         assertThat(response.page().total()).isEqualTo(1);
     }
 
+    /** 无效客户在进入持久化查询前拒绝。 */
     @Test
     void ledgerRejectsInvalidCustomerBeforeAnyQuery() {
-        FinancePhase1OperationService service = new FinancePhase1OperationService(mock(JdbcTemplate.class), objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(mock(JdbcTemplate.class), objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
         assertThatThrownBy(() -> service.listDerivedCustomerAccountLedger(0, 1, 20, null, null, null))
             .isInstanceOf(FinanceEventException.class)
             .extracting(error -> ((FinanceEventException) error).code()).isEqualTo("FIN-REQ-400");
     }
 
+    /** 保留客户账户汇总的固定分页与金额口径。 */
     @Test
     void accountListReturnsFixedPagedDto() {
         AccountJdbc jdbc = new AccountJdbc();
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         PageEnvelope<FinancePhase1Dtos.AccountSummary> result =
             service.listDerivedCustomerAccounts(1, 20, "客户9", "ACTIVE");
@@ -112,10 +120,11 @@ class FinancePhase1OperationBehaviorTest {
         assertThat(jdbc.accountListSql).doesNotContain("CAST(c.customer_id AS CHAR)");
     }
 
+    /** 所有派生流水查询保留目标客户范围。 */
     @Test
     void ledgerQueriesEveryDerivedSourceWithinCustomerScope() {
         AccountJdbc jdbc = new AccountJdbc();
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         PageEnvelope<FinancePhase1Dtos.LedgerEntry> result =
             service.listDerivedCustomerAccountLedger(9L, 1, 20, null, null, null);
@@ -128,58 +137,24 @@ class FinancePhase1OperationBehaviorTest {
             .contains("fin_settlement_payment", "transaction_type='PAYMENT'", "s.direction='PAYABLE'"));
     }
 
+    /** 所有筛选在服务端进入同一版本投影，不在分页后按费用名称去重。 */
     @Test
-    void feeSourceListUsesFormalFieldsAndAllActiveFilters() throws Exception {
-        JdbcTemplate jdbc = mock(JdbcTemplate.class);
-        when(jdbc.queryForObject(startsWith("SELECT COUNT(*) FROM fin_fee_source"), eq(Long.class), any(Object[].class)))
-            .thenReturn(1L);
-        when(jdbc.query(startsWith("SELECT f.*"), any(RowMapper.class), any(Object[].class))).thenAnswer(invocation -> {
-            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
-            ResultSet rs = mock(ResultSet.class);
-            when(rs.getLong("id")).thenReturn(88L);
-            when(rs.getLong("source_fee_id")).thenReturn(9001L);
-            when(rs.getInt("source_fee_version")).thenReturn(3);
-            when(rs.getLong("customer_id")).thenReturn(9L);
-            when(rs.getLong("order_id")).thenReturn(19L);
-            when(rs.getLong("inbound_id")).thenReturn(29L);
-            when(rs.getLong("container_id")).thenReturn(39L);
-            when(rs.getString("source_system")).thenReturn("FIRSTLEG");
-            when(rs.getString("source_type")).thenReturn("INBOUND_FEE");
-            when(rs.getString("source_no")).thenReturn("IN-9");
-            when(rs.getString("direction")).thenReturn("RECEIVABLE");
-            when(rs.getString("fee_item_name")).thenReturn("入库操作费");
-            when(rs.getString("currency_code")).thenReturn("CNY");
-            when(rs.getString("review_status")).thenReturn("APPROVED");
-            when(rs.getString("effective_status")).thenReturn("AVAILABLE");
-            when(rs.getString("source_snapshot")).thenReturn("{\"customerName\":\"客户9\",\"supplierId\":\"79\",\"supplierName\":\"供应商A\",\"inboundCode\":\"IN-9\",\"containerNo\":\"CONT-9\",\"businessDate\":\"2026-08-11\",\"chargeableQuantity\":\"10\"}");
-            when(rs.getBigDecimal("amount")).thenReturn(new BigDecimal("120.00"));
-            when(rs.getBoolean("statement_generated")).thenReturn(false);
-            return List.of(mapper.mapRow(rs, 0));
-        });
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
-
+    void feeSourceListUsesFormalFieldsAndAllActiveFilters() {
+        var reads = mock(FinanceFeeSourceReadRepository.class);
+        var filters = java.util.Map.<String, Object>of("query", "current");
+        when(reads.filters(9L, "RECEIVABLE", "AVAILABLE", "APPROVED", false,
+            LocalDate.of(2026, 8, 1), LocalDate.of(2026, 8, 31), "IN-9", 2, 50)).thenReturn(filters);
+        when(reads.list(filters)).thenReturn(List.of());
+        when(reads.count(filters)).thenReturn(3L);
+        var service = new FinancePhase1OperationService(mock(JdbcTemplate.class), objectMapper(), null, "", reads);
         var result = service.listFinanceFeeSources(2, 50, 9L, "receivable", "available", "approved",
             false, LocalDate.of(2026, 8, 1), LocalDate.of(2026, 8, 31), "IN-9");
-
-        assertThat(result.page()).satisfies(meta -> {
-            assertThat(meta.page()).isEqualTo(2);
-            assertThat(meta.pageSize()).isEqualTo(50);
-            assertThat(meta.total()).isEqualTo(1);
-        });
-        assertThat(result.data()).singleElement().satisfies(source -> {
-            assertThat(source.sourceSystem()).isEqualTo("FIRSTLEG");
-            assertThat(source.sourceBusinessId()).isEqualTo("IN-9");
-            assertThat(source.inboundCode()).isEqualTo("IN-9");
-            assertThat(source.containerNo()).isEqualTo("CONT-9");
-            assertThat(source.supplierId()).isEqualTo(79L);
-            assertThat(source.supplierName()).isEqualTo("供应商A");
-            assertThat(source.reviewStatus()).isEqualTo("APPROVED");
-            assertThat(source.businessDate()).isEqualTo(LocalDate.of(2026, 8, 11));
-            assertThat(source.statementGenerated()).isFalse();
-        });
-        verify(jdbc).query(startsWith("SELECT f.*"), any(RowMapper.class), any(Object[].class));
+        assertThat(result.page().total()).isEqualTo(3);
+        assertThat(result.page().page()).isEqualTo(2);
+        verify(reads).list(filters);
     }
 
+    /** 流水返回业务单号和操作者快照。 */
     @Test
     void ledgerReturnsStableBusinessTypeDocumentAndOperatorNameSnapshot() throws Exception {
         JdbcTemplate jdbc = mock(JdbcTemplate.class);
@@ -197,7 +172,7 @@ class FinancePhase1OperationBehaviorTest {
         });
         when(jdbc.query(startsWith("SELECT id,receipt_no"), any(RowMapper.class), eq(9L))).thenReturn(List.of());
         when(jdbc.query(startsWith("SELECT id,cost_no"), any(RowMapper.class), eq(9L))).thenReturn(List.of());
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         PageEnvelope<FinancePhase1Dtos.LedgerEntry> result =
             service.listDerivedCustomerAccountLedger(9L, 1, 20, null, null, null);
@@ -211,18 +186,20 @@ class FinancePhase1OperationBehaviorTest {
         });
     }
 
+    /** 保留费用审核状态读取。 */
     @Test
     void approvedFeeCannotBeEditedAsDraft() throws Exception {
         JdbcTemplate jdbc = feeSourceJdbc("REJECTED", false, 2);
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         assertThat(service.getFinanceFeeSource(88L).reviewStatus()).isEqualTo("REJECTED");
     }
 
+    /** 费用详情保持原客户与来源版本。 */
     @Test
     void feeSourceDetailUsesFixedDtoAndRealCustomerScope() throws Exception {
         FinancePhase1OperationService service = new FinancePhase1OperationService(
-            feeSourceJdbc("APPROVED", true, 2), objectMapper());
+            feeSourceJdbc("APPROVED", true, 2), objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         FeeSourceDetail detail = service.getFinanceFeeSource(88L);
 
@@ -232,10 +209,11 @@ class FinancePhase1OperationBehaviorTest {
         assertThat(detail.reviewStatus()).isEqualTo("APPROVED");
     }
 
+    /** 业务来源费用必须回到所属系统调整。 */
     @Test
     void firstlegFeeEditAndAdjustAreBlockedInsteadOfMutatingFinanceCopy() throws Exception {
         JdbcTemplate jdbc = feeSourceJdbc("REJECTED", false, 1);
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         var request = new FinancePhase1Dtos.FeeSourceEditRequest(
             new BigDecimal("120.00"), "更正金额", 1);
@@ -247,6 +225,7 @@ class FinancePhase1OperationBehaviorTest {
             (Object[]) any());
     }
 
+    /** 头程作废等待权威来源事件，不能直接改财务副本。 */
     @Test
     void voidingNyexx2608180003DelegatesToFirstlegAndWaitsForEvent() throws Exception {
         JdbcTemplate jdbc = feeSourceJdbc("APPROVED", false, 2);
@@ -257,7 +236,7 @@ class FinancePhase1OperationBehaviorTest {
             .thenReturn(ApiResponse.success(new FirstlegFeeSourceClient.CommandResult(
                 "INBOUND_FEE", 700L, 3, "VOIDED", false)));
         FinancePhase1OperationService service = new FinancePhase1OperationService(
-            jdbc, objectMapper(), firstleg, "internal-token");
+            jdbc, objectMapper(), firstleg, "internal-token", mock(FinanceFeeSourceReadRepository.class));
 
         FeeSourceDetail result = service.voidFinanceFeeSource(88L, 71L, "finance",
             "void-key", new FinancePhase1Dtos.FeeSourceActionRequest("测试作废", 2));
@@ -278,6 +257,7 @@ class FinancePhase1OperationBehaviorTest {
             (Object[]) any());
     }
 
+    /** 审核以当前操作版本更新并追加同一记录的审计。 */
     @Test
     void reviewUsesExpectedVersionAndReturnsUpdatedDetail() throws Exception {
         JdbcTemplate jdbc = mock(JdbcTemplate.class);
@@ -289,7 +269,6 @@ class FinancePhase1OperationBehaviorTest {
             return List.of(mapper.mapRow(resultSet(review, false, version), 0));
         });
         when(jdbc.queryForObject(startsWith("SELECT COUNT(*)>0"), eq(Boolean.class), eq(88L), eq(3))).thenReturn(false);
-        when(jdbc.query(startsWith("SELECT created_at,action"), any(RowMapper.class), eq(9L), eq(88L))).thenReturn(List.of());
         when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L),
             eq("FEE_SOURCE_REVIEW"), eq("review-key"))).thenReturn(List.of());
         when(jdbc.update(startsWith("INSERT INTO fin_idempotency_record"), eq(9L), eq(71L),
@@ -301,7 +280,7 @@ class FinancePhase1OperationBehaviorTest {
             eq(71L), eq("操作人 71"), any(), any())).thenReturn(1);
         when(jdbc.update(startsWith("UPDATE fin_idempotency_record SET status='SUCCEEDED'"),
             eq(88L), eq(9L), eq(71L), eq("FEE_SOURCE_REVIEW"), eq("review-key"))).thenReturn(1);
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         FeeSourceDetail result = service.reviewFinanceFeeSource(88L, 71L, "review-key",
             new FinancePhase1Dtos.ReviewRequest("APPROVE", "核对无误", 0));
@@ -311,6 +290,51 @@ class FinancePhase1OperationBehaviorTest {
         verify(jdbc).update(startsWith("UPDATE fin_fee_source SET review_status="), eq("APPROVED"), eq("核对无误"), eq(88L), eq(0));
     }
 
+    /** 财务内部应收应付调整原费用记录，重复提交不能新增费用或重复记审计。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"RECEIVABLE", "PAYABLE"})
+    void manualAdjustmentUpdatesOriginalFeeOnceAndChecksVersionAndFrozenState(String direction) throws Exception {
+        var jdbc = mock(JdbcTemplate.class);
+        var service = spy(new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class)));
+        var beforeJson = objectMapper().createObjectNode().put("feeSourceId", 88).put("sourceSystem", "FINANCE")
+            .put("sourceType", "MANUAL").put("sourceFeeId", 700).put("sourceVersion", 1).put("customerId", 9)
+            .put("direction", direction).put("amount", 100).put("currency", "CNY").put("operationVersion", 2)
+            .put("reviewStatus", "APPROVED").put("sourceStatus", "AVAILABLE").put("statementGenerated", false);
+        var before = objectMapper().treeToValue(beforeJson, FeeSourceDetail.class);
+        var after = objectMapper().treeToValue(beforeJson.deepCopy().put("amount", 120)
+            .put("operationVersion", 3).put("reviewStatus", "DRAFT"), FeeSourceDetail.class);
+        doReturn(before, after).when(service).getFinanceFeeSource(88L);
+        lenient().when(jdbc.update(startsWith("UPDATE fin_fee_source SET amount="), eq(new BigDecimal("120.00")), eq(88L), eq(2), eq("APPROVED")))
+            .thenReturn(1, 0);
+        var request = new FinancePhase1Dtos.FeeSourceEditRequest(new BigDecimal("120.00"), "调整金额", 2);
+        var result = service.editFinanceFeeSource(88, 71, "adjust-once", request, true);
+        assertThat(result.feeSourceId()).isEqualTo(88);
+        assertThat(result.sourceFeeId()).isEqualTo(700);
+        assertThat(result.direction()).isEqualTo(direction);
+        assertThat(result.amount()).isEqualByComparingTo("120");
+        assertThat(result.operationVersion()).isEqualTo(3);
+        var hash = org.mockito.ArgumentCaptor.forClass(String.class);
+        verify(jdbc).update(startsWith("INSERT INTO fin_idempotency_record"), eq(9L), eq(71L),
+            eq("FEE_SOURCE_ADJUST"), eq("adjust-once"), hash.capture());
+        lenient().when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L), eq("FEE_SOURCE_ADJUST"), eq("adjust-once")))
+            .thenReturn(List.of(java.util.Map.of("request_hash", hash.getValue(), "status", "SUCCEEDED", "result_resource_id", 88L)));
+        assertThat(service.editFinanceFeeSource(88, 71, "adjust-once", request, true)).isEqualTo(after);
+        verify(jdbc, times(1)).update(startsWith("UPDATE fin_fee_source SET amount="), eq(new BigDecimal("120.00")), eq(88L), eq(2), eq("APPROVED"));
+        verify(jdbc, times(1)).update(startsWith("INSERT INTO fin_audit_log"), eq(9L), eq("FIN_FEE_SOURCE"), eq(88L),
+            eq("FEE_SOURCE_ADJUST"), eq("调整金额"), anyString(), anyString(), eq(71L), anyString(), any(), any());
+        verify(jdbc, never()).update(startsWith("INSERT INTO fin_fee_source"), any(Object[].class));
+        assertThatThrownBy(() -> service.editFinanceFeeSource(88, 71, "adjust-once",
+            new FinancePhase1Dtos.FeeSourceEditRequest(new BigDecimal("121.00"), "调整金额", 2), true))
+            .isInstanceOf(FinanceEventException.class).hasMessageContaining("Idempotency-Key已用于其他请求");
+        assertThatThrownBy(() -> service.editFinanceFeeSource(88, 71, "stale-version", request, true))
+            .isInstanceOf(FinanceEventException.class).hasMessageContaining("状态或版本");
+        doReturn(objectMapper().treeToValue(beforeJson.deepCopy().put("statementGenerated", true), FeeSourceDetail.class))
+            .when(service).getFinanceFeeSource(88L);
+        assertThatThrownBy(() -> service.editFinanceFeeSource(88, 71, "frozen", request, true))
+            .isInstanceOf(FinanceEventException.class).hasMessageContaining("已生成单据");
+    }
+
+    /** 准备指定来源版本的费用查询，不再模拟已迁入 Mapper 的审计查询。 */
     private static JdbcTemplate feeSourceJdbc(String reviewStatus, boolean included, int version) throws Exception {
         JdbcTemplate jdbc = mock(JdbcTemplate.class);
         when(jdbc.query(startsWith("SELECT * FROM fin_fee_source"), any(RowMapper.class), (Object[]) any())).thenAnswer(invocation -> {
@@ -318,7 +342,6 @@ class FinancePhase1OperationBehaviorTest {
             return List.of(mapper.mapRow(resultSet(reviewStatus, included, version), 0));
         });
         when(jdbc.queryForObject(startsWith("SELECT COUNT(*)>0"), eq(Boolean.class), eq(88L), eq(3))).thenReturn(false);
-        when(jdbc.query(startsWith("SELECT created_at,action"), any(RowMapper.class), eq(9L), eq(88L))).thenReturn(List.of());
         lenient().when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L),
             eq("FEE_SOURCE_SETTLEMENT"), eq("include-key"))).thenReturn(List.of());
         return jdbc;

firstleg/docs/business-index.md

@@ -79,8 +79,8 @@
 - 客户箱规配置必须恰好保持四档且默认算法在四行一致；`ADD` 以实测尺寸为基准对三个维度分别增加命中箱规的尺寸值，`MULTIPLY` 使用当前客户唯一默认计费规则，并由服务端按规则中的规格档位选择系数。测量行必须保存实际尺寸、选用规则和算法快照，页面不得自行重算后覆盖服务端结果；计价使用用户确认的重量/体积选择值并纳入幂等请求哈希。
 - 报关、订舱和拖车引用的供应商必须通过 `WarehouseSupplierSnapshotService` 按 ID 向 Warehouse 校验：报关使用 `CUSTOMS`，订舱使用 `BOOKING`（不区分国内/国外 scope），国内拖车使用 `TRUCKING + truckingScope=DOMESTIC`，清关提柜/目的港码头拖车使用 `TRUCKING + truckingScope=OVERSEAS`；供应商必须为 `ACTIVE`。请求中的名称只能作为一致性提示，持久化名称必须来自 Warehouse 快照，禁止用自由文本绕过 ID、类别或启用状态校验。修改任一供应商引用 DTO、OpenAPI 或内部客户端时，必须同步检查三条业务链、Warehouse `supplier-v1.yaml`、数据库快照字段和对应契约测试。
 - Order 渠道变更门禁必须检查装柜或后续状态、PDA task、预装、分柜及同柜组兼容性；任何不确定结果均失败关闭。`ORDER_DECLARATION_UPDATED_V1` 消费必须校验订单号/入仓码归属，永久保留 `eventId + payload hash` 幂等历史并按版本单调更新申报投影；不得覆盖仓库实测、箱码、测量审核或已确认费用。
-- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后永久只读。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
-- 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。
+- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后运输、预报货量、三方和柜型需求只读；仅三项实际货量允许通过 `OceanBookingService.updateActualCargo` 按编辑权限、版本、幂等键和原因补录并保存前后审计快照。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
+- 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。预计到港为可选计划，不作为放舱必填项；填写时不得早于预计开船时间。
 - 订舱号遵循 `../../../docs/业务单据编号契约.md`；不得以实体 ID 拼接生成。提单号在订舱主表全局唯一，柜次表只保存快照；真实集装箱号只在同一订舱内唯一，不同提单允许复用。放舱不要求真实柜号，也不得为满足放舱校验伪造柜号。
 - 订舱列表 `containerCount` 固定为该订舱全部柜型需求 `quantity` 之和，与真实柜关联/解除无关；关联候选只返回 `RELEASED`、剩余数量大于 0 且 `warehouseId + channelCode + containerType` 精确匹配的需求，由服务端集合查询 ACTIVE 分配量。前端不得扇出详情计算或用已关联柜数覆盖该字段，最终关联命令仍须重验目标货柜可修改性。
 - 拖车预约是平台级订舱聚合，不是客户或柜次资源：请求、实体、查询、响应和附件不得恢复 `customerId/customerName`，公开 DTO 也不得出现 `containerBookingId/loadingPlanId/cabinetNo/containerNo`。创建候选只返回有提单号、ACTIVE `BOOKING_CONFIRMATION` 或 `BILL_OF_LADING` 且没有非终态拖车单的 `RELEASED` 订舱；创建或编辑只冻结订舱仓库/提单与 TRUCKING/DOMESTIC 国内拖车供应商快照。每订舱通过查询锁与唯一约束最多一张非终态预约，重复创建返回现有派车单号；PDA 装柜完成不得改变拖车状态；只有订舱全部柜型需求均已关联且每柜全部入仓绑定确认国内离仓，才自动完成（含草稿/晚提交）。离仓、拖车创建/编辑/操作统一先锁订舱，完成状态、`AUTO_COMPLETE` 历史、按实装体积守恒分摊的柜次应付及 Finance Outbox 同事务落库；取消/异常单不自动恢复，已有有效或完成单不得重复创建。应付拖车费仅人民币 RMB（财务快照为 CNY），固定使用 `FEE_TYPE_108`，关联 ACTIVE/TRUCKING/DOMESTIC 供应商，零金额不生成费用；正金额缺归属、有效体积或费用配置时失败关闭，不丢费、不伪造均分。手工 DEPART/COMPLETE 动作已移除。附件使用 `tenantId=0 + TRUCK_APPOINTMENT_ATTACHMENT + appointmentId`，提单文件继续归订舱。

firstleg/src/main/java/com/baiyue/firstleg/mapper/LoadingCompletionCommandMapper.java

@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.LoadingCompletionCommandEntity;
 import org.apache.ibatis.annotations.Insert;
 import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Options;
 import org.apache.ibatis.annotations.Param;
 import org.apache.ibatis.annotations.Select;
 import org.apache.ibatis.annotations.Update;
@@ -55,28 +56,34 @@ public interface LoadingCompletionCommandMapper extends BaseMapper<LoadingComple
     int claim(@Param("id") long id, @Param("worker") String worker,
               @Param("leaseUntil") LocalDateTime leaseUntil);
 
+    /** 只有尚未过期的当前所有者可以续租，过期执行者必须重新领取。 */
     @Update("""
         UPDATE fl_loading_completion_command SET lease_until=#{leaseUntil},updated_at=CURRENT_TIMESTAMP(3)
          WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
         """)
     int renew(@Param("id") long id, @Param("worker") String worker,
               @Param("leaseUntil") LocalDateTime leaseUntil);
 
+    /** 完成落库必须仍持有有效租约，拒绝过期或已易主的旧执行者。 */
     @Update("""
         UPDATE fl_loading_completion_command
            SET command_status='COMPLETED',completed_at=CURRENT_TIMESTAMP(3),updated_at=CURRENT_TIMESTAMP(3),
                lease_owner=NULL,lease_until=NULL,failure_stage=NULL,failure_code=NULL,
                failure_request_id=NULL,failure_trace_id=NULL
          WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
         """)
     int complete(@Param("id") long id, @Param("worker") String worker);
 
+    /** 失败回执也受当前有效租约保护，不能覆盖新执行者的状态。 */
     @Update("""
         UPDATE fl_loading_completion_command
            SET command_status=#{status},next_retry_at=#{nextRetryAt},updated_at=CURRENT_TIMESTAMP(3),
                lease_owner=NULL,lease_until=NULL,failure_stage=#{stage},failure_code=#{code},
                failure_request_id=#{requestId},failure_trace_id=#{traceId}
          WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
         """)
     int fail(@Param("id") long id, @Param("worker") String worker, @Param("status") String status,
              @Param("nextRetryAt") LocalDateTime nextRetryAt, @Param("stage") String stage,
@@ -97,13 +104,32 @@ public interface LoadingCompletionCommandMapper extends BaseMapper<LoadingComple
     String checkpoint(@Param("commandId") long commandId, @Param("tenantId") long tenantId,
                       @Param("inboundId") long inboundId);
 
+    /** 检查点事务锁住当前有效租约，与并发重新领取互斥。 */
+    @Options(useCache = false, flushCache = Options.FlushCachePolicy.TRUE)
+    @Select("""
+        SELECT id FROM fl_loading_completion_command
+         WHERE id=#{commandId} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
+         FOR UPDATE
+        """)
+    Long lockCheckpointLease(@Param("commandId") long commandId, @Param("worker") String worker);
+
+    /** 在已锁定的命令行上重验有效租约；检查点只能前进，不能被迟到写入降级。 */
     @Insert("""
         INSERT INTO fl_loading_completion_checkpoint
           (command_id,tenant_id,inbound_id,owner_sequence,checkpoint_stage)
-        VALUES (#{commandId},#{tenantId},#{inboundId},#{sequence},#{stage})
-        ON DUPLICATE KEY UPDATE checkpoint_stage=VALUES(checkpoint_stage),updated_at=CURRENT_TIMESTAMP(3)
+        SELECT id,#{tenantId},#{inboundId},#{sequence},#{stage}
+          FROM fl_loading_completion_command
+         WHERE id=#{commandId} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
+        ON DUPLICATE KEY UPDATE checkpoint_stage=CASE
+          WHEN checkpoint_stage='INBOUND_COMPLETED' OR #{stage}='INBOUND_COMPLETED'
+            THEN 'INBOUND_COMPLETED'
+          WHEN checkpoint_stage='SETTLED' OR #{stage}='SETTLED' THEN 'SETTLED'
+          ELSE 'READY' END,updated_at=CURRENT_TIMESTAMP(3)
         """)
-    int checkpointCompleted(@Param("commandId") long commandId, @Param("tenantId") long tenantId,
+    int checkpointCompleted(@Param("commandId") long commandId, @Param("worker") String worker,
+                            @Param("tenantId") long tenantId,
                             @Param("inboundId") long inboundId, @Param("sequence") int sequence,
                             @Param("stage") String stage);
 }

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/controller/PlatformOceanBookingController.java

@@ -126,6 +126,17 @@ public class PlatformOceanBookingController {
     @PutMapping("/{oceanBookingId}") @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:edit')")
     @BusinessAudit(event="OCEAN_BOOKING_UPDATE_DRAFT", resourceType="OCEAN_BOOKING", resourceId="#oceanBookingId", description="编辑海运订舱草稿")
     public ApiResponse<Detail> updateDraft(@AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long oceanBookingId, @RequestHeader("Idempotency-Key") String key, @Valid @RequestBody UpdateRequest request) { validateOptionalCustomer(user, request.data().customerId()); return ApiResponse.success(service.updateDraft(oceanBookingId, user.userId(), user.username(), key, request)); }
+    /** 客服在放舱后补录实货量，沿用订舱编辑权限并记录审计。 */
+    @PutMapping("/{oceanBookingId}/actual-cargo")
+    @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:edit')")
+    @BusinessAudit(event="OCEAN_BOOKING_UPDATE_ACTUAL_CARGO", resourceType="OCEAN_BOOKING", resourceId="#oceanBookingId", description="补录订舱实际货量")
+    public ApiResponse<Detail> updateActualCargo(@AuthenticationPrincipal AuthenticatedUser user,
+        @PathVariable @Positive long oceanBookingId, @RequestHeader("Idempotency-Key") String key,
+        @Valid @RequestBody ActualCargoRequest request) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(service.updateActualCargo(oceanBookingId, user.userId(), user.username(), key, request));
+    }
+
     @DeleteMapping("/{oceanBookingId}") @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:delete')")
     @BusinessAudit(event="OCEAN_BOOKING_DELETE_DRAFT", resourceType="OCEAN_BOOKING", resourceId="#oceanBookingId", description="删除海运订舱草稿")
     public ApiResponse<Void> deleteDraft(@AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long oceanBookingId, @RequestHeader("Idempotency-Key") String key, @Valid @RequestBody ActionRequest request) { FirstlegScopeGuard.platform(user); service.deleteDraft(oceanBookingId, user.userId(), user.username(), key, request); return ApiResponse.success(null); }

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/dto/OceanBookingDtos.java

@@ -45,10 +45,12 @@ public final class OceanBookingDtos {
                                 String customerName, String warehouseName, String channelName) {}
 
     public record PartyRequest(@NotBlank @Size(max = 24) String partyType,
-                               @NotBlank @Size(max = 255) String partyName,
+                               @NotNull @Size(max = 255) String partyName,
                                @Size(max = 1000) String address,
                                @Size(max = 128) String contactName,
-                               @Size(max = 64) String contactPhone) {}
+                               @Size(max = 64) String contactPhone,
+                               @jakarta.validation.constraints.Email @Size(max = 255) String contactEmail,
+                               @Size(max = 128) String taxNo) {}
 
     public record ContainerRequirementRequest(@NotBlank @Size(max = 32) String containerType,
                                    @NotBlank @Size(max = 32) String containerKind,
@@ -76,7 +78,31 @@ public final class OceanBookingDtos {
                             LocalDateTime estimatedArrivalAt,
                             @Size(max = 1000) String remark,
                             @Valid @Size(max = 3) List<PartyRequest> parties,
-                            @Valid @Size(max = 20) List<ContainerRequirementRequest> containerRequirements) {}
+                            @Valid @Size(max = 20) List<ContainerRequirementRequest> containerRequirements,
+                            @Size(max = 64) String freightTerm,
+                            @Size(max = 64) String serviceTerm,
+                            @Pattern(regexp = "CARTONS|PCS|PALLETS") String packageUnit,
+                            @Size(max = 1000) String cargoDescription,
+                            @Size(max = 1000) String marksAndNos,
+                            @Min(1) @Max(999999999) Integer declaredPackageCount,
+                            @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                            @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal declaredGrossWeightKg,
+                            @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                            @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal declaredVolumeCbm,
+                            @Min(1) @Max(999999999) Integer actualPackageCount,
+                            @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                            @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualGrossWeightKg,
+                            @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                            @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualVolumeCbm) {}
+
+    /** 放舱后的受控实货量补录，不接收运输资料。 */
+    public record ActualCargoRequest(@NotNull @Min(0) Integer expectedVersion,
+                                    @Min(1) @Max(999999999) Integer actualPackageCount,
+                                    @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                                    @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualGrossWeightKg,
+                                    @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                                    @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualVolumeCbm,
+                                    @NotBlank @Size(max = 1000) String reason) {}
 
     public record CreateRequest(@NotNull @Min(0) Integer expectedVersion,
                                 @Valid @NotNull DraftData data) {}

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/entity/OceanBookingEntity.java

@@ -40,6 +40,17 @@ public class OceanBookingEntity {
     private LocalDateTime estimatedSailingAt;
     private LocalDateTime estimatedArrivalAt;
     private String remark;
+    private String freightTerm;
+    private String serviceTerm;
+    private String packageUnit;
+    private String cargoDescription;
+    private String marksAndNos;
+    private Integer declaredPackageCount;
+    private java.math.BigDecimal declaredGrossWeightKg;
+    private java.math.BigDecimal declaredVolumeCbm;
+    private Integer actualPackageCount;
+    private java.math.BigDecimal actualGrossWeightKg;
+    private java.math.BigDecimal actualVolumeCbm;
     private Long createdBy;
     private String createdByName;
     @TableField(fill = FieldFill.INSERT) private LocalDateTime createdAt;

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/entity/OceanBookingPartyEntity.java

@@ -17,4 +17,6 @@ public class OceanBookingPartyEntity {
     private String address;
     private String contactName;
     private String contactPhone;
+    private String contactEmail;
+    private String taxNo;
 }

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/mapper/OceanBookingMapper.java

@@ -25,8 +25,17 @@ public interface OceanBookingMapper extends BaseMapper<OceanBookingEntity> {
         """)
     int touchDraft(@Param("id") long id, @Param("expectedVersion") int expectedVersion,
                    @Param("operatorId") long operatorId, @Param("operatorName") String operatorName);
-    @Update("UPDATE fl_ocean_booking SET customer_id=#{value.customerId},customer_name=#{value.customerName},channel_code=#{value.channelCode},channel_name=#{value.channelName},warehouse_id=#{value.warehouseId},warehouse_name=#{value.warehouseName},bill_of_lading_no=#{value.billOfLadingNo},shipping_company_id=#{value.shippingCompanyId},shipping_company_name=#{value.shippingCompanyName},carrier_code=#{value.carrierCode},booking_agent_id=#{value.bookingAgentId},booking_agent_name=#{value.bookingAgentName},vessel_name=#{value.vesselName},voyage_no=#{value.voyageNo},departure_port_code=#{value.departurePortCode},departure_port_name=#{value.departurePortName},destination_port_code=#{value.destinationPortCode},destination_port_name=#{value.destinationPortName},place_of_delivery=#{value.placeOfDelivery},estimated_sailing_at=#{value.estimatedSailingAt},estimated_arrival_at=#{value.estimatedArrivalAt},remark=#{value.remark},updated_by=#{operatorId},updated_by_name=#{operatorName},version=version+1,updated_at=NOW() WHERE id=#{id} AND status='DRAFT' AND version=#{version}")
+    @Update("UPDATE fl_ocean_booking SET customer_id=#{value.customerId},customer_name=#{value.customerName},channel_code=#{value.channelCode},channel_name=#{value.channelName},warehouse_id=#{value.warehouseId},warehouse_name=#{value.warehouseName},bill_of_lading_no=#{value.billOfLadingNo},shipping_company_id=#{value.shippingCompanyId},shipping_company_name=#{value.shippingCompanyName},carrier_code=#{value.carrierCode},booking_agent_id=#{value.bookingAgentId},booking_agent_name=#{value.bookingAgentName},vessel_name=#{value.vesselName},voyage_no=#{value.voyageNo},departure_port_code=#{value.departurePortCode},departure_port_name=#{value.departurePortName},destination_port_code=#{value.destinationPortCode},destination_port_name=#{value.destinationPortName},place_of_delivery=#{value.placeOfDelivery},estimated_sailing_at=#{value.estimatedSailingAt},estimated_arrival_at=#{value.estimatedArrivalAt},remark=#{value.remark},freight_term=#{value.freightTerm},service_term=#{value.serviceTerm},package_unit=#{value.packageUnit},cargo_description=#{value.cargoDescription},marks_and_nos=#{value.marksAndNos},declared_package_count=#{value.declaredPackageCount},declared_gross_weight_kg=#{value.declaredGrossWeightKg},declared_volume_cbm=#{value.declaredVolumeCbm},actual_package_count=#{value.actualPackageCount},actual_gross_weight_kg=#{value.actualGrossWeightKg},actual_volume_cbm=#{value.actualVolumeCbm},updated_by=#{operatorId},updated_by_name=#{operatorName},version=version+1,updated_at=NOW() WHERE id=#{id} AND status='DRAFT' AND version=#{version}")
     int updateDraft(@Param("id") long id, @Param("value") OceanBookingEntity value, @Param("version") int version, @Param("operatorId") long operatorId, @Param("operatorName") String operatorName);
+    /** 已放舱补实只更新白名单字段，保留乐观锁及状态门禁。 */
+    @Update("""
+        UPDATE fl_ocean_booking SET actual_package_count=#{value.actualPackageCount},
+          actual_gross_weight_kg=#{value.actualGrossWeightKg},actual_volume_cbm=#{value.actualVolumeCbm},
+          updated_by=#{operatorId},updated_by_name=#{operatorName},updated_at=CURRENT_TIMESTAMP(3),version=version+1
+        WHERE id=#{value.id} AND status='RELEASED' AND version=#{version}
+        """)
+    int updateActualCargo(@Param("value") OceanBookingEntity value, @Param("version") int version,
+                          @Param("operatorId") long operatorId, @Param("operatorName") String operatorName);
     @Delete("DELETE FROM fl_ocean_booking WHERE id=#{id} AND status='DRAFT' AND version=#{version}")
     int deleteDraft(@Param("id") long id, @Param("version") int version);
     @Select("""

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/repository/OceanBookingRepository.java

@@ -54,6 +54,10 @@ public class OceanBookingRepository {
     public int touchDraft(long id, int version, long operatorId, String operatorName) {
         return bookings.touchDraft(id, version, operatorId, operatorName);
     }
+    /** 只更新已放舱订舱的实际货量，运输快照保持冻结。 */
+    public int updateActualCargo(OceanBookingEntity value, int version, long operatorId, String operatorName) {
+        return bookings.updateActualCargo(value, version, operatorId, operatorName);
+    }
     public int deleteDraft(long id, int version) {
         return bookings.deleteDraft(id, version);
     }

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingPrintService.java

@@ -46,7 +46,7 @@ public class OceanBookingPrintService {
         String fileName = booking.getBookingNo() + "-" + suffix + ".pdf";
         PrintPdfClient.FreightA4PdfRequest request = new PrintPdfClient.FreightA4PdfRequest(
             template, A4, fileName, List.of(new PrintPdfClient.FreightDocument(
-                fields(template, detail), List.of(emptyCargo()))));
+                fields(template, detail), List.of(cargo(template, booking)))));
         try {
             ResponseEntity<byte[]> response = print.generateFreightA4Documents(internalToken, requestId, request);
             MediaType contentType = response.getHeaders().getContentType();
@@ -75,14 +75,21 @@ public class OceanBookingPrintService {
         fields.put("portOfLoading", first(booking.getDeparturePortName(), booking.getDeparturePortCode()));
         fields.put("portOfDischarge", first(booking.getDestinationPortName(), booking.getDestinationPortCode()));
         fields.put("placeOfDelivery", text(booking.getPlaceOfDelivery()));
-        fields.put("serviceTerm", "");
-        fields.put("freightTerm", "");
-        fields.put("totalPackagesInWords", "");
+        fields.put("serviceTerm", text(booking.getServiceTerm()));
+        fields.put("freightTerm", text(booking.getFreightTerm()));
+        Integer count = SHIPPING_INSTRUCTION.equals(template) ? booking.getDeclaredPackageCount() : booking.getActualPackageCount();
+        fields.put("totalPackagesInWords", packageWords(count, booking.getPackageUnit()));
         if (SHIPPING_INSTRUCTION.equals(template)) {
             fields.put("toCompany", text(booking.getBookingAgentName()));
             fields.put("jobNumber", text(booking.getBookingNo()));
             fields.put("etdDate", date(booking.getEstimatedSailingAt()));
-            fields.put("cargoQuantity", "");
+            fields.put("cargoQuantity", detail.containerRequirements().stream()
+                .map(value -> value.getQuantity() + "*" + value.getContainerType()).collect(Collectors.joining(" + ")));
+            OceanBookingPartyEntity shipper = parties.get("SHIPPER");
+            fields.put("picName", shipper == null ? "" : text(shipper.getContactName()));
+            fields.put("picTel", shipper == null ? "" : text(shipper.getContactPhone()));
+            fields.put("apName", text(booking.getBookingAgentName()));
+            fields.put("printDate", java.time.LocalDate.now(java.time.ZoneId.of("Asia/Shanghai")).toString());
             fields.put("carrier", text(booking.getShippingCompanyName()));
             fields.put("bookingAgent", text(booking.getBookingAgentName()));
             fields.put("remark", text(booking.getRemark()));
@@ -98,8 +105,43 @@ public class OceanBookingPrintService {
         return fields;
     }
 
-    private static PrintPdfClient.CargoRow emptyCargo() {
-        return new PrintPdfClient.CargoRow("—", "—", "—", "—", "—", "—");
+    /** 两类单据严格分别读取委、实数据，不以柜型容量或预报量代替实装量。 */
+    private static PrintPdfClient.CargoRow cargo(String template, OceanBookingEntity booking) {
+        boolean declared = SHIPPING_INSTRUCTION.equals(template);
+        Integer count = declared ? booking.getDeclaredPackageCount() : booking.getActualPackageCount();
+        BigDecimal weight = declared ? booking.getDeclaredGrossWeightKg() : booking.getActualGrossWeightKg();
+        BigDecimal volume = declared ? booking.getDeclaredVolumeCbm() : booking.getActualVolumeCbm();
+        return new PrintPdfClient.CargoRow(display(booking.getMarksAndNos()), count == null ? "—" : count.toString(),
+            display(booking.getPackageUnit()), display(booking.getCargoDescription()),
+            weight == null ? "—" : weight.setScale(3, java.math.RoundingMode.HALF_UP).toPlainString() + " KGS",
+            volume == null ? "—" : volume.setScale(3, java.math.RoundingMode.HALF_UP).toPlainString() + " CBM");
+    }
+
+    /** 打印空字段使用统一占位符。 */
+    private static String display(String value) { return text(value).isEmpty() ? "—" : text(value); }
+
+    /** 件数大写跟随所选数据和包装单位生成，未录入时明确留空。 */
+    private static String packageWords(Integer count, String unit) {
+        if (count == null || !org.springframework.util.StringUtils.hasText(unit)) return "";
+        String packaging = count == 1 ? switch (unit) {
+            case "CARTONS" -> "CARTON";
+            case "PALLETS" -> "PALLET";
+            case "PCS" -> "PIECE";
+            default -> unit;
+        } : ("PCS".equals(unit) ? "PIECES" : unit);
+        return "SAY " + words(count) + " " + packaging + " ONLY";
+    }
+
+    /** 将受件数范围约束的正整数转换为英文数量。 */
+    private static String words(int value) {
+        String[] small = {"ZERO", "ONE", "TWO", "THREE", "FOUR", "FIVE", "SIX", "SEVEN", "EIGHT", "NINE", "TEN",
+            "ELEVEN", "TWELVE", "THIRTEEN", "FOURTEEN", "FIFTEEN", "SIXTEEN", "SEVENTEEN", "EIGHTEEN", "NINETEEN"};
+        String[] tens = {"", "", "TWENTY", "THIRTY", "FORTY", "FIFTY", "SIXTY", "SEVENTY", "EIGHTY", "NINETY"};
+        if (value < 20) return small[value];
+        if (value < 100) return tens[value / 10] + (value % 10 == 0 ? "" : " " + words(value % 10));
+        int divisor = value >= 1000000 ? 1000000 : value >= 1000 ? 1000 : 100;
+        String scale = divisor == 1000000 ? "MILLION" : divisor == 1000 ? "THOUSAND" : "HUNDRED";
+        return words(value / divisor) + " " + scale + (value % divisor == 0 ? "" : " " + words(value % divisor));
     }
 
     private static String requirementSummary(List<OceanBookingContainerRequirementEntity> values) {
@@ -110,7 +152,8 @@ public class OceanBookingPrintService {
     private static String party(OceanBookingPartyEntity value) {
         if (value == null) return "";
         return List.of(text(value.getPartyName()), text(value.getAddress()),
-                join(value.getContactName(), value.getContactPhone())).stream()
+                join(value.getContactName(), value.getContactPhone()), text(value.getContactEmail()),
+                text(value.getTaxNo()).isEmpty() ? "" : "TAX NO: " + text(value.getTaxNo())).stream()
             .filter(part -> !part.isEmpty()).collect(Collectors.joining("\n"));
     }
 

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingService.java

@@ -145,6 +145,26 @@ public class OceanBookingService {
         addHistory(id, OceanBookingStatus.DRAFT.name(), OceanBookingStatus.DRAFT.name(), action, null, before, after, operatorId, operatorName);
         return complete(id, operatorId, action, key, detail(after));
     }
+    /** 放舱后仅补录实货量，版本、幂等结果和修改前后快照在同一事务保存。 */
+    @Transactional
+    public Detail updateActualCargo(long id, long operatorId, String name, String key, ActualCargoRequest request) {
+        String action = "UPDATE_ACTUAL_CARGO";
+        Detail replay = claimOrReplay(id, operatorId, action, key, hash(action, id, request));
+        if (replay != null) return replay;
+        OceanBookingEntity before = requiredVersionForUpdate(id, request.expectedVersion());
+        requireStatus(before, OceanBookingStatus.RELEASED);
+        if (!StringUtils.hasText(request.reason())) throw badRequest("请填写实货量补录或修正原因");
+        validateCargo(request.actualPackageCount(), request.actualGrossWeightKg(), request.actualVolumeCbm());
+        OceanBookingEntity after = objectMapper.convertValue(before, OceanBookingEntity.class);
+        after.setActualPackageCount(request.actualPackageCount());
+        after.setActualGrossWeightKg(request.actualGrossWeightKg());
+        after.setActualVolumeCbm(request.actualVolumeCbm());
+        if (repository.updateActualCargo(after, request.expectedVersion(), operatorId, name) != 1) throw concurrent();
+        OceanBookingEntity saved = required(id);
+        addHistory(id, before.getStatus(), saved.getStatus(), action, request.reason(), before, saved, operatorId, name);
+        return complete(id, operatorId, action, key, detail(saved));
+    }
+
     @Transactional
     public void deleteDraft(long id, long operatorId, String operatorName, String key, ActionRequest request) {
         String action = "DELETE_DRAFT";
@@ -209,7 +229,18 @@ public class OceanBookingService {
     private OceanBookingEntity requiredVersionForUpdate(long id, int version) { OceanBookingEntity value = repository.findForUpdate(id); if (value == null) throw new BizException(ResultCode.NOT_FOUND, "订舱单不存在"); if (!Integer.valueOf(version).equals(value.getVersion())) throw concurrent(); return value; }
     private static void requireStatus(OceanBookingEntity value, OceanBookingStatus status) { if (!status.name().equals(value.getStatus())) throw conflict("订舱状态不允许当前操作"); }
 
+    /** 未采集使用空值；已填写的件数、重量和体积必须为正数且不超出存储精度。 */
+    private static void validateCargo(Integer count, java.math.BigDecimal weight, java.math.BigDecimal volume) {
+        if (count != null && (count < 1 || count > 999999999)) throw badRequest("货物件数必须为1到999999999的整数");
+        for (java.math.BigDecimal number : new java.math.BigDecimal[] {weight, volume}) {
+            if (number != null && (number.signum() <= 0 || number.scale() > 3
+                || number.precision() - number.scale() > 12)) throw badRequest("货物重量和体积必须为正数，最多12位整数和3位小数");
+        }
+    }
+
     private void validateDraftStructure(DraftData data) {
+        validateCargo(data.declaredPackageCount(), data.declaredGrossWeightKg(), data.declaredVolumeCbm());
+        validateCargo(data.actualPackageCount(), data.actualGrossWeightKg(), data.actualVolumeCbm());
         boolean hasCustomerId = data.customerId() != null;
         boolean hasCustomerName = StringUtils.hasText(data.customerName());
         if (!hasCustomerId && hasCustomerName) throw badRequest("客户名称不能脱离客户ID提交");
@@ -231,17 +262,19 @@ public class OceanBookingService {
         }
     }
     private static void validateRange(LocalDateTime from, LocalDateTime to) { if (from != null && to != null && to.isBefore(from)) throw badRequest("预计到港时间不能早于预计开船时间"); }
+    /** 放舱核对必要运输资料；预计到港为可选计划，不阻断放舱。 */
     private static void validateRelease(OceanBookingEntity booking, List<OceanBookingPartyEntity> parties,
                                         List<OceanBookingContainerRequirementEntity> requirements) {
         if (!StringUtils.hasText(booking.getChannelCode()) || booking.getWarehouseId() == null
             || !StringUtils.hasText(booking.getBillOfLadingNo()) || !StringUtils.hasText(booking.getVesselName())
             || !StringUtils.hasText(booking.getVoyageNo()) || booking.getEstimatedSailingAt() == null
-            || booking.getEstimatedArrivalAt() == null || booking.getShippingCompanyId() == null
+            || booking.getShippingCompanyId() == null
             || (!StringUtils.hasText(booking.getDeparturePortName()) && !StringUtils.hasText(booking.getDeparturePortCode()))
             || (!StringUtils.hasText(booking.getDestinationPortName()) && !StringUtils.hasText(booking.getDestinationPortCode()))
             || !StringUtils.hasText(booking.getPlaceOfDelivery())
             || !StringUtils.hasText(booking.getCarrierCode())
             || booking.getBookingAgentId() == null || parties == null || parties.size() != 3
+            || (parties != null && parties.stream().anyMatch(party -> !StringUtils.hasText(party.getPartyName())))
             || requirements == null || requirements.isEmpty()) throw badRequest("订舱资料尚未填写完整，无法发布");
         validateRange(booking.getEstimatedSailingAt(), booking.getEstimatedArrivalAt());
     }
@@ -298,6 +331,17 @@ public class OceanBookingService {
         v.setPlaceOfDelivery(trim(d.placeOfDelivery()));
         v.setEstimatedSailingAt(d.estimatedSailingAt()); v.setEstimatedArrivalAt(d.estimatedArrivalAt());
         v.setRemark(trim(d.remark()));
+        v.setFreightTerm(trim(d.freightTerm()));
+        v.setServiceTerm(trim(d.serviceTerm()));
+        v.setPackageUnit(trim(d.packageUnit()));
+        v.setCargoDescription(trim(d.cargoDescription()));
+        v.setMarksAndNos(trim(d.marksAndNos()));
+        v.setDeclaredPackageCount(d.declaredPackageCount());
+        v.setDeclaredGrossWeightKg(d.declaredGrossWeightKg());
+        v.setDeclaredVolumeCbm(d.declaredVolumeCbm());
+        v.setActualPackageCount(d.actualPackageCount());
+        v.setActualGrossWeightKg(d.actualGrossWeightKg());
+        v.setActualVolumeCbm(d.actualVolumeCbm());
     }
 
     private void requireUniqueBillOfLadingNo(String billOfLadingNo, Long excludedId) {
@@ -370,7 +414,7 @@ public class OceanBookingService {
         return normalized;
     }
 
-    private static List<OceanBookingPartyEntity> parties(long id, List<PartyRequest> requests) { if (requests == null) return List.of(); return requests.stream().map(r -> { OceanBookingPartyEntity v = new OceanBookingPartyEntity(); v.setId(IdWorker.getId()); v.setOceanBookingId(id); v.setPartyType(r.partyType().trim().toUpperCase()); v.setPartyName(r.partyName().trim()); v.setAddress(trim(r.address())); v.setContactName(trim(r.contactName())); v.setContactPhone(trim(r.contactPhone())); return v; }).toList(); }
+    private static List<OceanBookingPartyEntity> parties(long id, List<PartyRequest> requests) { if (requests == null) return List.of(); return requests.stream().map(r -> { OceanBookingPartyEntity v = new OceanBookingPartyEntity(); v.setId(IdWorker.getId()); v.setOceanBookingId(id); v.setPartyType(r.partyType().trim().toUpperCase()); v.setPartyName(r.partyName().trim()); v.setAddress(trim(r.address())); v.setContactName(trim(r.contactName())); v.setContactPhone(trim(r.contactPhone())); v.setContactEmail(trim(r.contactEmail())); v.setTaxNo(trim(r.taxNo())); return v; }).toList(); }
     private static List<OceanBookingContainerRequirementEntity> requirements(long id, List<ContainerRequirementRequest> requests) { if (requests == null) return List.of(); int[] sort = {0}; return requests.stream().map(r -> { var specification = ContainerSpecificationCatalog.requireMatch(r.containerType(), r.capacityCbm(), r.maxWeightKg()); OceanBookingContainerRequirementEntity v = new OceanBookingContainerRequirementEntity(); v.setId(IdWorker.getId()); v.setOceanBookingId(id); v.setContainerType(specification.containerType()); v.setContainerKind(r.containerKind().trim().toUpperCase()); v.setCapacityCbm(specification.capacityCbm()); v.setMaxWeightKg(specification.maxWeightKg()); v.setQuantity(r.quantity()); v.setSortNo(sort[0]++); return v; }).toList(); }
     private WarehouseMasterDataClient.Warehouse requireDomesticTransitWarehouse(long warehouseId) {
         try {

firstleg/src/main/java/com/baiyue/firstleg/portschedule/service/AppointmentForecastService.java

@@ -11,16 +11,27 @@ import java.util.stream.Collectors;
 @Service
 public class AppointmentForecastService {
     public record Forecast(Long containerBookingId,AppointmentForecastMapper.Fact latest,
-                           AppointmentForecastMapper.Fact previous,String timeBasis) { }
+                           AppointmentForecastMapper.Fact previous,String timeBasis,
+                           java.time.LocalDateTime portArrivalAt) { }
     private final AppointmentForecastMapper mapper;
-    public AppointmentForecastService(AppointmentForecastMapper mapper){this.mapper=mapper;}
+    private final com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository sources;
+    /** 读取船节点及日历权威到港来源，不从调用端接收推算日期。 */
+    public AppointmentForecastService(AppointmentForecastMapper mapper,
+        com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository sources) {
+        this.mapper=mapper; this.sources=sources;
+    }
+    /** 返回明确来源柜的到港事实，保留未知日期。 */
     public List<Forecast> batch(List<Long> ids) {
         if(ids==null || ids.isEmpty() || ids.size()>200 || ids.stream().anyMatch(id->id==null || id<=0)
             || new HashSet<>(ids).size()!=ids.size()) throw new ResponseStatusException(HttpStatus.BAD_REQUEST,"每批须提供1至200个不重复的柜次");
         var facts=mapper.latest(ids).stream().collect(Collectors.groupingBy(AppointmentForecastMapper.Fact::containerBookingId));
+        var arrivals=sources.byIds(ids).stream().collect(Collectors.toMap(
+            com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource::containerBookingId,
+            java.util.function.Function.identity()));
         return ids.stream().map(id->{
             var rows=facts.getOrDefault(id,List.of());
-            return new Forecast(id,rows.isEmpty()?null:rows.get(0),rows.size()<2?null:rows.get(1),"SOURCE_LOCAL_UNSPECIFIED");
+            return new Forecast(id,rows.isEmpty()?null:rows.get(0),rows.size()<2?null:rows.get(1),"SOURCE_LOCAL_UNSPECIFIED",
+                arrivals.containsKey(id)?arrivals.get(id).arrivalAt():null);
         }).toList();
     }
 }

firstleg/src/main/java/com/baiyue/firstleg/repository/LoadingCompletionCommandRepository.java

@@ -4,6 +4,7 @@ import com.baiyue.firstleg.entity.LoadingCompletionCommandEntity;
 import com.baiyue.firstleg.mapper.LoadingCompletionCommandMapper;
 import jakarta.annotation.Resource;
 import org.springframework.stereotype.Repository;
+import org.springframework.transaction.annotation.Transactional;
 
 import java.time.LocalDateTime;
 import java.util.List;
@@ -12,6 +13,9 @@ import java.util.List;
 public class LoadingCompletionCommandRepository {
     @Resource private LoadingCompletionCommandMapper mapper;
 
+    /** 按事务提交后的命令标识读取唯一完成请求。 */
+    public LoadingCompletionCommandEntity command(long id) { return mapper.selectById(id); }
+
     public int insert(LoadingCompletionCommandEntity command) { return mapper.insertCommand(command); }
     public LoadingCompletionCommandEntity operation(String operationId) { return mapper.findByOperation(operationId); }
     public LoadingCompletionCommandEntity active(long taskId) { return mapper.findActiveByTask(taskId); }
@@ -28,7 +32,13 @@ public class LoadingCompletionCommandRepository {
     public String checkpoint(long commandId, long tenantId, long inboundId) {
         return mapper.checkpoint(commandId, tenantId, inboundId);
     }
-    public void checkpoint(long commandId, long tenantId, long inboundId, int sequence, String stage) {
-        mapper.checkpointCompleted(commandId, tenantId, inboundId, sequence, stage);
+    /** 命令行锁覆盖租约检查与检查点写入，旧执行者不能在租约易主后覆盖新结果。 */
+    @Transactional
+    public boolean checkpoint(long commandId, String worker, long tenantId, long inboundId,
+                              int sequence, String stage) {
+        if (mapper.lockCheckpointLease(commandId, worker) == null) return false;
+        int written = mapper.checkpointCompleted(commandId, worker, tenantId, inboundId, sequence, stage);
+        // 同阶段重放可能被驱动计为零行；命令行仍被本事务锁住，重验租约区分幂等与过期拒绝。
+        return written > 0 || mapper.lockCheckpointLease(commandId, worker) != null;
     }
 }

firstleg/src/main/java/com/baiyue/firstleg/service/LoadingCompletionWorker.java

@@ -9,37 +9,77 @@ import jakarta.annotation.Resource;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.core.task.TaskExecutor;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.event.TransactionalEventListener;
 
 import java.time.LocalDateTime;
 import java.util.UUID;
+import java.util.concurrent.RejectedExecutionException;
 
-/** Lease-based recovery worker for PDA completion commands. */
+/** 事务提交后立即处理 PDA 完成命令，并按持久化租约定时恢复。 */
 @Service
 public class LoadingCompletionWorker {
     private static final Logger log = LoggerFactory.getLogger(LoadingCompletionWorker.class);
     private static final int MAX_ATTEMPTS = 5;
-    private final String workerId = "pda-completion-" + UUID.randomUUID();
 
     @Resource private LoadingCompletionCommandRepository commands;
     @Resource private LoadingPickRepository picks;
     @Resource private LoadingPickService loadingPicks;
+    @Resource(name = "applicationTaskExecutor") private TaskExecutor completionExecutor;
 
-    @Scheduled(fixedDelayString = "${baiyue.firstleg.pda-completion.fixed-delay-ms:2000}")
-    public void dispatch() {
-        for (LoadingCompletionCommandEntity candidate : commands.due(10)) {
-            if (!commands.claim(candidate.getId(), workerId, LocalDateTime.now().plusMinutes(10))) {
-                continue;
-            }
-            try {
-                loadingPicks.processCompletion(candidate, workerId);
-            } catch (RuntimeException exception) {
-                handleFailure(candidate, exception);
-            }
+    /** 唤醒只发生在受理事务提交后，异步执行不延长 HTTP 受理请求。 */
+    @TransactionalEventListener
+    public void accepted(LoadingPickService.CompletionAccepted accepted) {
+        try {
+            completionExecutor.execute(() -> dispatchAccepted(accepted));
+        } catch (RejectedExecutionException exception) {
+            // 执行器繁忙或关闭时保留持久化命令，仍由定时扫描领取，不能影响已提交回执。
+            log.warn("pda_completion_wakeup_deferred commandId={}", accepted.commandId(), exception);
         }
     }
 
-    private void handleFailure(LoadingCompletionCommandEntity command, RuntimeException exception) {
+    /** 唤醒与恢复共用原子领取；同一命令不会被两个执行入口重复结算。 */
+    private void dispatchAccepted(LoadingPickService.CompletionAccepted accepted) {
+        try {
+            LoadingCompletionCommandEntity command = commands.command(accepted.commandId());
+            if (command != null) process(command, "immediate", accepted.acceptedAtNanos());
+        } catch (RuntimeException exception) {
+            log.warn("pda_completion_wakeup_failed commandId={}", accepted.commandId(), exception);
+        }
+    }
+
+    /** 扫描到期或租约过期命令，覆盖唤醒丢失、进程重启及失败退避恢复。 */
+    @Scheduled(fixedDelayString = "${baiyue.firstleg.pda-completion.fixed-delay-ms:2000}")
+    public void dispatch() {
+        for (LoadingCompletionCommandEntity candidate : commands.due(10)) {
+            process(candidate, "scheduled", System.nanoTime());
+        }
+    }
+
+    /** 保留租约、检查点和失败恢复语义，记录领取及实际处理耗时。 */
+    private void process(LoadingCompletionCommandEntity command, String source, long queuedAt) {
+        // 每次领取使用独立所有者，避免旧执行线程在租约过期、同进程重新领取后继续写入。
+        String leaseOwner = "pda-completion-" + UUID.randomUUID();
+        if (!commands.claim(command.getId(), leaseOwner, LocalDateTime.now().plusMinutes(10))) return;
+        long started = System.nanoTime();
+        boolean succeeded = false;
+        log.info("pda_completion_started commandId={} taskId={} source={} wakeupMs={}",
+            command.getId(), command.getPickTaskId(), source, (started - queuedAt) / 1_000_000);
+        try {
+            loadingPicks.processCompletion(command, leaseOwner);
+            succeeded = true;
+        } catch (RuntimeException exception) {
+            handleFailure(command, leaseOwner, exception);
+        } finally {
+            log.info("pda_completion_finished commandId={} taskId={} source={} durationMs={} succeeded={}",
+                command.getId(), command.getPickTaskId(), source, (System.nanoTime() - started) / 1_000_000,
+                succeeded);
+        }
+    }
+
+    /** 确定性失败关闭任务，其余故障按原退避与最大次数恢复。 */
+    private void handleFailure(LoadingCompletionCommandEntity command, String leaseOwner, RuntimeException exception) {
         Throwable cause = exception instanceof LoadingPickService.CompletionProcessingException
             && exception.getCause() != null ? exception.getCause() : exception;
         String stage = exception instanceof LoadingPickService.CompletionProcessingException staged
@@ -53,7 +93,7 @@ public class LoadingCompletionWorker {
         int attempt = command.getAttemptCount() == null ? 1 : command.getAttemptCount() + 1;
         boolean terminal = isDeterministicLocalBusinessFailure(stage, cause) || attempt >= MAX_ATTEMPTS;
         LocalDateTime retryAt = LocalDateTime.now().plusSeconds(Math.min(300L, 15L << Math.min(attempt - 1, 4)));
-        boolean recorded = commands.fail(command.getId(), workerId, terminal ? "FAILED" : "RETRYABLE", retryAt,
+        boolean recorded = commands.fail(command.getId(), leaseOwner, terminal ? "FAILED" : "RETRYABLE", retryAt,
             stage, code, requestId, traceId);
         if (terminal && recorded) {
             picks.failCompletion(command.getPickTaskId());
@@ -63,6 +103,7 @@ public class LoadingCompletionWorker {
             command.getOperationId(), stage, code, requestId, traceId, attempt, terminal, cause);
     }
 
+    /** 仅将已明确不可重试的本地业务门禁判为终态。 */
     private static boolean isDeterministicLocalBusinessFailure(String stage, Throwable cause) {
         if (!(cause instanceof BizException business)) {
             return false;

firstleg/src/main/java/com/baiyue/firstleg/service/LoadingPickService.java

@@ -56,6 +56,7 @@ import jakarta.annotation.Resource;
 import org.springframework.dao.DuplicateKeyException;
 import org.springframework.stereotype.Service;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.transaction.support.TransactionTemplate;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.util.StringUtils;
@@ -87,6 +88,8 @@ public class LoadingPickService {
     @Resource
     private LoadingCompletionCommandRepository completionCommands;
     @Resource
+    private ApplicationEventPublisher completionEvents;
+    @Resource
     private TransactionTemplate completionTransaction;
     @Resource
     private SmartLoadingRepository smartLoadingRepository;
@@ -552,6 +555,7 @@ public class LoadingPickService {
                     || !completionCommands.resume(replay.getId()) || repository.resumeCompletion(taskId) != 1) {
                     throw conflict("装柜完成命令状态已变化，请刷新后重试");
                 }
+                completionEvents.publishEvent(new CompletionAccepted(replay.getId(), System.nanoTime()));
             }
             return view(requiredTask(taskId), null);
         }
@@ -598,9 +602,14 @@ public class LoadingPickService {
         if (repository.acceptCompletion(taskId, task.getVersion()) != 1) {
             throw conflict("PDA任务版本已变化，请刷新后复核");
         }
+        // 提交后立即唤醒仍经持久化租约领取；回滚不得触发结算，定时扫描继续负责故障恢复。
+        completionEvents.publishEvent(new CompletionAccepted(command.getId(), System.nanoTime()));
         return view(requiredTask(taskId), null);
     }
 
+    /** 本进程事务提交后的唤醒信号，权威命令和恢复事实仍保存在数据库。 */
+    public record CompletionAccepted(long commandId, long acceptedAtNanos) {}
+
     private void requireCompletionContainerNumber(long taskId) {
         ContainerBookingEntity booking = repository.activeBookingByTask(taskId);
         if (booking == null || !StringUtils.hasText(booking.getContainerNo())) {
@@ -613,7 +622,7 @@ public class LoadingPickService {
         }
     }
 
-    /** Called only by the completion worker, after its durable lease has committed. */
+    /** 仅在持久化租约领取成功后执行，远程结算不占用受理事务。 */
     public void processCompletion(LoadingCompletionCommandEntity command, String worker) {
         long taskId = command.getPickTaskId();
         inboundHoldGuard.requireTaskNotHeld(taskId);
@@ -625,55 +634,55 @@ public class LoadingPickService {
             .toList();
         if (owners.isEmpty()) throw new CompletionProcessingException("OWNER_DISCOVERY", conflict("PDA任务未关联有效入库单"));
         List<GroupSnapshot> taskGroups = coloadGroups(owners);
-        runCompletionStage("CABINET_EVIDENCE", () ->
+        runCompletionStage(taskId, "CABINET_EVIDENCE", () ->
             cabinetEvidenceService.requireComplete(task.getContainerBookingId()));
-        runCompletionStage("COMPLETED_EVENT_READY", () ->
+        runCompletionStage(taskId, "COMPLETED_EVENT_READY", () ->
             loadingListService.requireCompletedEventReady(task.getLoadingPlanId()));
 
-        // Phase 1 is read-only: cabinet evidence is checked once, then every owner must pass its business gates
-        // before any warehouse resource or inbound status can be changed. This prevents a later customer gate from
-        // leaving earlier customers partially completed.
+        // 全柜所有客户先通过只读门禁，再开始资源结算，避免后续客户失败造成前序客户局部完成。
         for (int index = 0; index < owners.size(); index++) {
             requireCompletionLease(command.getId(), worker);
             LoadingPickItemMapper.InboundOwner owner = owners.get(index);
             String checkpoint = completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId());
             if (!checkpointAtLeast(checkpoint, "SETTLED")) {
-                runCompletionStage("OWNER_READY", () -> loadingDeliveryService.requirePdaCompletionReady(
+                runCompletionStage(taskId, "OWNER_READY", () -> loadingDeliveryService.requirePdaCompletionReady(
                     owner.tenantId(), owner.inboundId()));
                 if (!checkpointAtLeast(checkpoint, "READY")) {
-                    requireCompletionLease(command.getId(), worker);
-                    completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(),
+                    recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(),
                         index + 1, "READY");
                 }
             }
         }
 
-        // Phase 2 is recoverable by per-owner checkpoints and stable idempotency keys. It starts only after the
-        // complete cabinet passed phase 1, while prior deployments' completed checkpoints remain safely resumable.
+        // 全柜门禁通过后，按客户检查点和稳定幂等键逐步结算，已完成的检查点可安全续做。
         for (int index = 0; index < owners.size(); index++) {
             requireCompletionLease(command.getId(), worker);
             LoadingPickItemMapper.InboundOwner owner = owners.get(index);
             String checkpoint = completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId());
             if (!checkpointAtLeast(checkpoint, "SETTLED")) {
-                runCompletionStage("WAREHOUSE_SETTLEMENT", () -> settlementService.settleOwner(
+                runCompletionStage(taskId, "WAREHOUSE_SETTLEMENT", () -> settlementService.settleOwner(
                     taskId, owner.inboundId(), command.getOperatorId(), command.getOperatorName()));
-                requireCompletionLease(command.getId(), worker);
-                completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(), index + 1, "SETTLED");
+                recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(), index + 1, "SETTLED");
             }
             if (!checkpointAtLeast(checkpoint, "INBOUND_COMPLETED")) {
-                runCompletionStage("INBOUND_COMPLETE", () -> loadingDeliveryService.completeAfterPdaSettlement(
+                runCompletionStage(taskId, "INBOUND_COMPLETE", () -> loadingDeliveryService.completeAfterPdaSettlement(
                     owner.tenantId(), owner.inboundId(),
                     command.getOperatorId(), command.getOperatorName(),
                     "PDA-" + command.getOperationId() + '-' + owner.inboundId(), command.getRemark()));
-                requireCompletionLease(command.getId(), worker);
-                completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(), index + 1,
+                recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(), index + 1,
                     "INBOUND_COMPLETED");
             }
         }
-        completionTransaction.executeWithoutResult(ignored -> finalizeCompletion(command, worker, task, taskGroups));
+        long transactionStarted = System.nanoTime();
+        try {
+            completionTransaction.executeWithoutResult(ignored -> finalizeCompletion(command, worker, task, taskGroups));
+        } finally {
+            log.info("pda_completion_transaction taskId={} durationMs={}", taskId,
+                (System.nanoTime() - transactionStarted) / 1_000_000);
+        }
     }
 
-    /** Final Firstleg convergence only; all remote owner settlement calls have completed before this short transaction. */
+    /** 远程结算完成后，仅在短事务内收敛 Firstleg 本地完成事实。 */
     private void finalizeCompletion(LoadingCompletionCommandEntity command, String worker,
                                     LoadingPickTaskEntity task, List<GroupSnapshot> taskGroups) {
         long taskId = task.getId();
@@ -688,11 +697,11 @@ public class LoadingPickService {
             insertOperation(taskId, command.getOperationId(), command.getRequestHash(), "COMPLETE_LOADING",
                 command.getOperatorId(), command.getOperatorName());
         }
-        runCompletionStage("PLAN_COMPLETE", () -> loadingListService.finishFromPda(task.getLoadingPlanId(), taskId,
+        runCompletionStage(taskId, "PLAN_COMPLETE", () -> loadingListService.finishFromPda(task.getLoadingPlanId(), taskId,
             command.getOperatorId(), command.getOperatorName()));
-        runCompletionStage("COMPLETED_EVENT", () -> loadingListService.publishCompletedEvent(task.getLoadingPlanId()));
+        runCompletionStage(taskId, "COMPLETED_EVENT", () -> loadingListService.publishCompletedEvent(task.getLoadingPlanId()));
         for (GroupSnapshot group : taskGroups) {
-            runCompletionStage("COLOAD_CONSUME", () -> coloadGroups.consumeWholeGroup(group.groupId(),
+            runCompletionStage(taskId, "COLOAD_CONSUME", () -> coloadGroups.consumeWholeGroup(group.groupId(),
                 task.getLoadingPlanId(), "PDA-CONSUME-" + hash(command.getOperationId() + '|'
                     + group.groupId()).substring(0, 48), command.getOperatorId(), command.getOperatorName()));
         }
@@ -750,6 +759,14 @@ public class LoadingPickService {
         }
     }
 
+    /** 检查点失去当前有效租约时立即停止，不再推进后续客户或柜次。 */
+    private void recordCompletionCheckpoint(long commandId, String worker, long tenantId, long inboundId,
+                                            int sequence, String stage) {
+        if (!completionCommands.checkpoint(commandId, worker, tenantId, inboundId, sequence, stage)) {
+            throw new CompletionProcessingException("LEASE_LOST", conflict("装柜完成命令租约已变化"));
+        }
+    }
+
     private static void requireSameCompletionCommand(LoadingCompletionCommandEntity command, long taskId,
                                                      String requestHash, long operatorId) {
         if (command == null || !Long.valueOf(taskId).equals(command.getPickTaskId())
@@ -764,11 +781,18 @@ public class LoadingPickService {
         return checkpoint != null && stages.indexOf(checkpoint) >= stages.indexOf(target);
     }
 
-    private static void runCompletionStage(String stage, Runnable action) {
+    /** 记录实际阶段耗时，区分业务处理与调度、前端刷新等待。 */
+    private static void runCompletionStage(long taskId, String stage, Runnable action) {
+        long started = System.nanoTime();
+        boolean succeeded = false;
         try {
             action.run();
+            succeeded = true;
         } catch (RuntimeException exception) {
             throw new CompletionProcessingException(stage, exception);
+        } finally {
+            log.info("pda_completion_stage taskId={} stage={} durationMs={} succeeded={}",
+                taskId, stage, (System.nanoTime() - started) / 1_000_000, succeeded);
         }
     }
 

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/mapper/ContainerCalendarSourceMapper.java

@@ -9,6 +9,25 @@ import java.util.List;
 
 @Mapper
 public interface ContainerCalendarSourceMapper {
+    /** 按明确来源柜读取与预约日历相同的到港事实，实际到港优先。 */
+    @Select("""
+        <script>
+        SELECT c.id containerBookingId,c.cabinet_no cabinetNo,c.container_no containerNo,
+          c.vessel_name vesselName,c.voyage_no voyageNo,c.destination_port_name destinationPortName,
+          c.destination_warehouse_code destinationWarehouseCode,
+          COALESCE(n.actual_at,c.actual_port_arrival_at,c.estimated_port_arrival_at) arrivalAt,
+          CASE WHEN COALESCE(n.actual_at,c.actual_port_arrival_at) IS NOT NULL THEN 'ACTUAL' ELSE 'ESTIMATED' END arrivalType
+        FROM fl_container_booking c
+        LEFT JOIN fl_carrier_schedule_node_fact n ON n.id=(
+          SELECT f.id FROM fl_carrier_schedule_node_fact f WHERE f.container_booking_id=c.id
+            AND f.standard_node='ARRIVED_DESTINATION_PORT' AND f.actual_at IS NOT NULL
+          ORDER BY f.observed_at DESC,f.id DESC LIMIT 1)
+        WHERE c.record_status='ACTIVE' AND c.id IN
+        <foreach collection='ids' item='id' open='(' separator=',' close=')'>#{id}</foreach>
+        </script>
+        """)
+    List<ContainerCalendarSource> byIds(@Param("ids") List<Long> ids);
+
     /** 同时选出到港、缺日期和可能还柜的有效出仓柜，最终日期由业务服务复核。 */
     @Select("""
         SELECT c.id containerBookingId,c.cabinet_no cabinetNo,c.container_no containerNo,

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/repository/ContainerCalendarSourceRepository.java

@@ -11,6 +11,8 @@ public class ContainerCalendarSourceRepository {
     private final ContainerCalendarSourceMapper mapper;
     /** 使用本服务 Mapper 读取日历所需柜级来源。 */
     public ContainerCalendarSourceRepository(ContainerCalendarSourceMapper mapper) { this.mapper = mapper; }
+    /** 内部批量读取明确柜次，日期口径与平台日历一致。 */
+    public List<ContainerCalendarSource> byIds(List<Long> ids) { return mapper.byIds(ids); }
     /** 到港前移两天覆盖默认到仓，直送还柜候选额外留一天覆盖夏令时。 */
     public List<ContainerCalendarSource> sources(LocalDate from, LocalDate to) {
         return mapper.sources(from.atStartOfDay(), from.minusDays(2).atStartOfDay(),

firstleg/src/main/java/com/baiyue/firstleg/workflow/WorkflowTabService.java

@@ -27,7 +27,7 @@ public class WorkflowTabService {
  if(facts.stream().noneMatch(f->f.tenantId()==fee.tenantId() && f.orderId()==fee.orderId())) throw unavailable("费用确认事实不属于本批入仓来源");
  result.putIfAbsent(fee.orderId()+":"+fee.mainStatus(),fee);
  }
- var sources=facts.stream().filter(f->f.departed() || f.clearanceUploaded()).map(f->new WorkflowFacts.Source(f.tenantId(),f.inboundId())).distinct().toList();
+ var sources=facts.stream().filter(WorkflowFacts.Fact::departed).map(f->new WorkflowFacts.Source(f.tenantId(),f.inboundId())).distinct().toList();
  Map<String,WorkflowFacts.Overseas> overseas=new HashMap<>();
  if(!sources.isEmpty()) {
  try {
@@ -61,11 +61,11 @@ public class WorkflowTabService {
  Set<String> keys=new LinkedHashSet<>();
  if("MEASURE_PENDING".equals(process) && "PENDING".equals(f.reviewStatus())) keys.add("MEASUREMENT_REVIEW");
  boolean signed="DELIVERED".equals(process);
- // 报关完成即进入待清关；不再等待船期接口补齐实际离港节点。
- boolean clearanceStage=f.customsCompleted() || f.departed() || f.clearanceUploaded();
+ // 人工补录或船司查询的实际开船节点才推进阶段，报关完成和提前上传资料不能代替开船。
+ boolean clearanceStage=f.departed();
  if(!clearanceStage && !signed) {
  if(f.missingCustoms()) keys.add("WAIT_CUSTOMS_DOCS");
- if(f.exportCustomsReady()) keys.add("EXPORT_CUSTOMS");
+ if(f.exportCustomsReady() || f.customsCompleted()) keys.add("EXPORT_CUSTOMS");
  }
  if(signed) keys.add("SIGNED");
  if(clearanceStage && !signed) {

firstleg/src/main/resources/db/phase3-ocean-booking-schema.sql

@@ -4,7 +4,7 @@ USE baiyue_firstleg;
 CREATE TABLE IF NOT EXISTS fl_ocean_booking (
   id BIGINT UNSIGNED NOT NULL COMMENT '海运订舱ID',
   booking_no VARCHAR(40) NOT NULL COMMENT '平台海运订舱编号',
-  status VARCHAR(24) NOT NULL DEFAULT 'DRAFT' COMMENT '订舱状态：DRAFT草稿、RELEASED已发布且永久只读',
+  status VARCHAR(24) NOT NULL DEFAULT 'DRAFT' COMMENT '订舱状态：DRAFT草稿、RELEASED已放舱，运输快照冻结且实货量受控补录',
   customer_id BIGINT UNSIGNED NULL COMMENT '可选客户ID快照',
   customer_name VARCHAR(128) NULL COMMENT '可选客户名称快照',
   channel_code VARCHAR(64) NULL COMMENT '订舱计划物流渠道组编码快照',
@@ -27,6 +27,17 @@ CREATE TABLE IF NOT EXISTS fl_ocean_booking (
   estimated_sailing_at DATETIME(3) NULL COMMENT '当前确认预计开船时间',
   estimated_arrival_at DATETIME(3) NULL COMMENT '当前确认预计到港时间',
   remark VARCHAR(1000) NULL COMMENT '平台内部备注',
+  freight_term VARCHAR(64) NULL COMMENT '运费条款',
+  service_term VARCHAR(64) NULL COMMENT '运输条款',
+  package_unit VARCHAR(16) NULL COMMENT '包装单位：CARTONS、PCS或PALLETS',
+  cargo_description VARCHAR(1000) NULL COMMENT '货物品名及托运要求',
+  marks_and_nos VARCHAR(1000) NULL COMMENT '唛头和号码',
+  declared_package_count INT UNSIGNED NULL COMMENT '订舱预报件数（委）',
+  declared_gross_weight_kg DECIMAL(15,3) NULL COMMENT '订舱预报毛重kg（委）',
+  declared_volume_cbm DECIMAL(15,3) NULL COMMENT '订舱预报体积cbm（委）',
+  actual_package_count INT UNSIGNED NULL COMMENT '客服手工实货件数',
+  actual_gross_weight_kg DECIMAL(15,3) NULL COMMENT '客服手工实货毛重kg',
+  actual_volume_cbm DECIMAL(15,3) NULL COMMENT '客服手工实货体积cbm',
   created_by BIGINT UNSIGNED NOT NULL COMMENT '创建操作人ID',
   created_by_name VARCHAR(64) NULL COMMENT '创建操作人姓名快照',
   created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '订舱记录创建时间',
@@ -44,6 +55,14 @@ CREATE TABLE IF NOT EXISTS fl_ocean_booking (
     ('DRAFT','RELEASED')),
   CONSTRAINT chk_ocean_booking_carrier_code CHECK
     (carrier_code IS NULL OR carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER')),
+  CONSTRAINT chk_ocean_booking_cargo CHECK (
+    (package_unit IS NULL OR package_unit IN ('CARTONS','PCS','PALLETS'))
+    AND (declared_package_count IS NULL OR declared_package_count BETWEEN 1 AND 999999999)
+    AND (actual_package_count IS NULL OR actual_package_count BETWEEN 1 AND 999999999)
+    AND (declared_gross_weight_kg IS NULL OR declared_gross_weight_kg > 0)
+    AND (actual_gross_weight_kg IS NULL OR actual_gross_weight_kg > 0)
+    AND (declared_volume_cbm IS NULL OR declared_volume_cbm > 0)
+    AND (actual_volume_cbm IS NULL OR actual_volume_cbm > 0)),
   CONSTRAINT chk_ocean_booking_schedule CHECK
     (estimated_sailing_at IS NULL OR estimated_arrival_at IS NULL OR estimated_arrival_at >= estimated_sailing_at)
 ) ENGINE=InnoDB COMMENT='独立海运订舱聚合；柜次仍由fl_container_booking承载';
@@ -110,6 +129,8 @@ CREATE TABLE IF NOT EXISTS fl_ocean_booking_party (
   address VARCHAR(1000) NULL COMMENT '关系方地址快照',
   contact_name VARCHAR(128) NULL COMMENT '关系方联系人快照',
   contact_phone VARCHAR(64) NULL COMMENT '关系方联系电话快照',
+  contact_email VARCHAR(255) NULL COMMENT '关系方联系邮箱',
+  tax_no VARCHAR(128) NULL COMMENT '关系方税号',
   PRIMARY KEY (id),
   UNIQUE KEY uk_ocean_booking_party (ocean_booking_id,party_type),
   CONSTRAINT fk_ocean_booking_party FOREIGN KEY (ocean_booking_id) REFERENCES fl_ocean_booking(id) ON DELETE CASCADE,
@@ -211,8 +232,47 @@ DROP TRIGGER IF EXISTS trg_ocean_booking_before_update;
 DELIMITER $$
 CREATE TRIGGER trg_ocean_booking_before_update BEFORE UPDATE ON fl_ocean_booking FOR EACH ROW
 BEGIN
-  IF OLD.status = 'RELEASED' THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱订舱不可修改';
+  -- 已放舱只允许实货量及其审计元数据变化，运输和预报快照保持冻结。
+  IF OLD.status = 'RELEASED' AND NOT (
+    (NEW.id <=> OLD.id)
+    AND (NEW.booking_no <=> OLD.booking_no)
+    AND (NEW.status <=> OLD.status)
+    AND (NEW.customer_id <=> OLD.customer_id)
+    AND (NEW.customer_name <=> OLD.customer_name)
+    AND (NEW.channel_code <=> OLD.channel_code)
+    AND (NEW.channel_name <=> OLD.channel_name)
+    AND (NEW.warehouse_id <=> OLD.warehouse_id)
+    AND (NEW.warehouse_name <=> OLD.warehouse_name)
+    AND (NEW.bill_of_lading_no <=> OLD.bill_of_lading_no)
+    AND (NEW.shipping_company_id <=> OLD.shipping_company_id)
+    AND (NEW.shipping_company_name <=> OLD.shipping_company_name)
+    AND (NEW.carrier_code <=> OLD.carrier_code)
+    AND (NEW.booking_agent_id <=> OLD.booking_agent_id)
+    AND (NEW.booking_agent_name <=> OLD.booking_agent_name)
+    AND (NEW.vessel_name <=> OLD.vessel_name)
+    AND (NEW.voyage_no <=> OLD.voyage_no)
+    AND (NEW.departure_port_code <=> OLD.departure_port_code)
+    AND (NEW.departure_port_name <=> OLD.departure_port_name)
+    AND (NEW.destination_port_code <=> OLD.destination_port_code)
+    AND (NEW.destination_port_name <=> OLD.destination_port_name)
+    AND (NEW.place_of_delivery <=> OLD.place_of_delivery)
+    AND (NEW.estimated_sailing_at <=> OLD.estimated_sailing_at)
+    AND (NEW.estimated_arrival_at <=> OLD.estimated_arrival_at)
+    AND (NEW.remark <=> OLD.remark)
+    AND (NEW.freight_term <=> OLD.freight_term)
+    AND (NEW.service_term <=> OLD.service_term)
+    AND (NEW.package_unit <=> OLD.package_unit)
+    AND (NEW.cargo_description <=> OLD.cargo_description)
+    AND (NEW.marks_and_nos <=> OLD.marks_and_nos)
+    AND (NEW.declared_package_count <=> OLD.declared_package_count)
+    AND (NEW.declared_gross_weight_kg <=> OLD.declared_gross_weight_kg)
+    AND (NEW.declared_volume_cbm <=> OLD.declared_volume_cbm)
+    AND (NEW.created_by <=> OLD.created_by)
+    AND (NEW.created_by_name <=> OLD.created_by_name)
+    AND (NEW.created_at <=> OLD.created_at)
+    AND NEW.version = OLD.version + 1
+  ) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱运输资料不可修改，仅允许补录实货量';
   END IF;
   IF OLD.status <> NEW.status AND NOT (
        (OLD.status='DRAFT' AND NEW.status='RELEASED')) THEN

firstleg/src/main/resources/openapi/appointment-forecasts-internal-v1.yaml

@@ -34,6 +34,7 @@ paths:
                       properties:
                         containerBookingId: {type: string}
                         timeBasis: {type: string, enum: [SOURCE_LOCAL_UNSPECIFIED]}
+                        portArrivalAt: {type: string, format: date-time, nullable: true, description: 与预约日历相同的权威到港当地时间，最新有效实际到港优先，其次柜资料实际到港及预计到港；未知保持空}
                         latest: {$ref: '#/components/schemas/Fact'}
                         previous: {$ref: '#/components/schemas/Fact'}
         '401': {description: 内部身份缺失、错误或服务端未配置}

firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml

@@ -1,8 +1,8 @@
 openapi: 3.0.3
 info:
   title: Ocean Booking API
-  version: 2.1.0
-  description: Booking-owned files use File businessType OCEAN_BOOKING_DOCUMENT and businessId=oceanBookingId. Release requires at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file. Released bookings and their file links are permanently read-only.
+  version: 2.2.0
+  description: Booking-owned files use File businessType OCEAN_BOOKING_DOCUMENT and businessId=oceanBookingId. Release requires at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file. Released transport and declared cargo snapshots and file links are read-only. Manual actual cargo may be supplemented with version, idempotency and audit reason.
 paths:
   /api/platform/v1/ocean-bookings:
     get:
@@ -29,6 +29,14 @@ paths:
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}}}
       responses: {'200': {description: Deleted}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/actual-cargo:
+    put:
+      summary: Supplement manual actual cargo on a RELEASED booking
+      description: Only actual package count, gross weight and volume may change. Transport and declared cargo remain frozen. Requires expectedVersion, Idempotency-Key and a reason; saves before/after audit snapshots atomically. Null means not recorded, never zero or a fallback to declared cargo.
+      x-permission: platform:firstleg:ocean-booking:edit
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActualCargoRequest'}}}}
+      responses: {'200': {description: Updated RELEASED detail}, '409': {description: State or version conflict}}
   /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
     post:
       summary: Validate and permanently release a DRAFT
@@ -89,7 +97,7 @@ paths:
   /api/platform/v1/ocean-bookings/{oceanBookingId}/prints/shipping-instruction:
     get:
       summary: Render the current saved booking as an export shipping instruction PDF
-      description: Firstleg maps the authoritative saved aggregate (DRAFT or RELEASED, with missing fields displayed as —) to SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1 and synchronously proxies the generated PDF. Container requirements are not treated as actual cargo quantity, weight, volume, marks, packaging, or goods descriptions.
+      description: Firstleg maps the authoritative saved aggregate (DRAFT or RELEASED, with missing fields displayed as —) to SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1 and synchronously proxies the generated PDF. Cargo uses saved declared values; container requirements describe requested containers only. Count in words is generated from the declared count and packageUnit.
       x-permission: platform:firstleg:ocean-booking:list
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}]
       responses:
@@ -97,7 +105,7 @@ paths:
   /api/platform/v1/ocean-bookings/{oceanBookingId}/prints/bill-of-lading-confirmation:
     get:
       summary: Render the current saved booking as a bill-of-lading confirmation PDF
-      description: Firstleg maps the authoritative saved aggregate (DRAFT or RELEASED, with missing fields displayed as —) to BILL_OF_LADING_CONFIRMATION_A4_V1 and synchronously proxies the generated PDF. Container requirements remain a container summary and are not treated as actual cargo facts.
+      description: Firstleg maps the authoritative saved aggregate (DRAFT or RELEASED, with missing fields displayed as —) to BILL_OF_LADING_CONFIRMATION_A4_V1 and synchronously proxies the generated PDF. Cargo uses saved manually entered actual values only; missing actual data displays — and never falls back to declared values. This is a confirmation copy; the externally issued bill of lading remains an uploaded attachment.
       x-permission: platform:firstleg:ocean-booking:list
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}]
       responses:
@@ -192,12 +200,33 @@ components:
         destinationPortName: {type: string, nullable: true}
         placeOfDelivery: {type: string, nullable: true}
         estimatedSailingAt: {type: string, format: date-time, nullable: true}
-        estimatedArrivalAt: {type: string, format: date-time, nullable: true}
+        estimatedArrivalAt: {type: string, format: date-time, nullable: true, description: 可选预计到港时间；放舱不要求填写，填写时不得早于预计开船时间}
         remark: {type: string, nullable: true}
+        freightTerm: {type: string, maxLength: 64, nullable: true, description: 运费条款；新建页面默认FREIGHT PREPAID}
+        serviceTerm: {type: string, maxLength: 64, nullable: true, description: 运输条款；新建页面默认CY-CY}
+        packageUnit: {type: string, enum: [CARTONS, PCS, PALLETS], nullable: true}
+        cargoDescription: {type: string, maxLength: 1000, nullable: true}
+        marksAndNos: {type: string, maxLength: 1000, nullable: true}
+        declaredPackageCount: {type: integer, minimum: 1, maximum: 999999999, nullable: true}
+        declaredGrossWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
+        declaredVolumeCbm: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
+        actualPackageCount: {type: integer, minimum: 1, maximum: 999999999, nullable: true}
+        actualGrossWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
+        actualVolumeCbm: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
         parties: {type: array, nullable: true, items: {$ref: '#/components/schemas/PartyRequest'}}
         containerRequirements: {type: array, nullable: true, items: {$ref: '#/components/schemas/ContainerRequirementRequest'}}
-    PartyRequest: {type: object, required: [partyType, partyName], properties: {partyType: {type: string, enum: [SHIPPER, CONSIGNEE, NOTIFY_PARTY]}, partyName: {type: string}, address: {type: string, nullable: true}, contactName: {type: string, nullable: true}, contactPhone: {type: string, nullable: true}}}
+    PartyRequest: {type: object, required: [partyType, partyName], properties: {partyType: {type: string, enum: [SHIPPER, CONSIGNEE, NOTIFY_PARTY]}, partyName: {type: string}, address: {type: string, nullable: true}, contactName: {type: string, nullable: true}, contactPhone: {type: string, nullable: true}, contactEmail: {type: string, format: email, maxLength: 255, nullable: true}, taxNo: {type: string, maxLength: 128, nullable: true}}}
     ContainerRequirementRequest: {type: object, required: [containerType, containerKind, quantity, capacityCbm, maxWeightKg], properties: {containerType: {type: string, enum: [40GP, 40HQ, 45HQ], default: 40HQ}, containerKind: {type: string}, quantity: {type: integer, minimum: 1}, capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: 统一实装上限；40GP=58、40HQ=68、45HQ=86}, maxWeightKg: {type: number, enum: [19500], description: 统一货重上限}}}
+    ActualCargoRequest:
+      type: object
+      additionalProperties: false
+      required: [expectedVersion, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        reason: {type: string, minLength: 1, maxLength: 1000}
+        actualPackageCount: {type: integer, minimum: 1, maximum: 999999999, nullable: true}
+        actualGrossWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
+        actualVolumeCbm: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
     ReleaseRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
     ActionRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
     DocumentType: {type: string, enum: [BOOKING_CONFIRMATION, BILL_OF_LADING]}
@@ -311,6 +340,8 @@ components:
       required: [oceanBooking, parties, containerRequirements, containers, documents, histories]
       properties:
         oceanBooking:
+          allOf:
+            - {$ref: '#/components/schemas/DraftData'}
           type: object
           properties:
             bookingNo: {type: string, pattern: '^OB[0-9]{12}$', example: OB202608180001, description: 平台订舱号；按北京时间创建日逐日编号}

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/controller/PlatformOceanBookingControllerContractTest.java

@@ -32,6 +32,7 @@ class PlatformOceanBookingControllerContractTest {
             Map.entry("uploadDocument", "platform:firstleg:ocean-booking:edit"),
             Map.entry("invalidateDocument", "platform:firstleg:ocean-booking:edit"),
             Map.entry("create", "platform:firstleg:ocean-booking:create"),
+            Map.entry("updateActualCargo", "platform:firstleg:ocean-booking:edit"),
             Map.entry("updateDraft", "platform:firstleg:ocean-booking:edit"),
             Map.entry("deleteDraft", "platform:firstleg:ocean-booking:delete"),
             Map.entry("release", "platform:firstleg:ocean-booking:release"));
@@ -47,6 +48,24 @@ class PlatformOceanBookingControllerContractTest {
         });
     }
 
+    @Test
+    @SuppressWarnings("unchecked")
+    void actualCargoContractExposesOnlySupplementFieldsAndReusesEditPermission() throws Exception {
+        assertThat(method("updateActualCargo").getAnnotation(org.springframework.web.bind.annotation.PutMapping.class).value())
+            .containsExactly("/{oceanBookingId}/actual-cargo");
+        Map<String, Object> document = new org.yaml.snakeyaml.Yaml().load(
+            Files.readString(Path.of("src/main/resources/openapi/ocean-bookings-v1.yaml")));
+        var paths = (Map<String, Object>) document.get("paths");
+        var endpoint = (Map<String, Object>) paths.get("/api/platform/v1/ocean-bookings/{oceanBookingId}/actual-cargo");
+        var operation = (Map<String, Object>) endpoint.get("put");
+        assertThat(operation).containsEntry("x-permission", "platform:firstleg:ocean-booking:edit");
+        var schemas = (Map<String, Object>) ((Map<String, Object>) document.get("components")).get("schemas");
+        var request = (Map<String, Object>) schemas.get("ActualCargoRequest");
+        assertThat((Map<String, Object>) request.get("properties")).containsOnlyKeys(
+            "expectedVersion", "reason", "actualPackageCount", "actualGrossWeightKg", "actualVolumeCbm");
+        assertThat((java.util.List<String>) request.get("required")).contains("expectedVersion", "reason");
+    }
+
     @Test
     void pathVariablesUseExplicitAggregateNames() {
         assertThat(Arrays.stream(PlatformOceanBookingController.class.getDeclaredMethods())

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/repository/OceanBookingMapperContractTest.java

@@ -46,6 +46,16 @@ class OceanBookingMapperContractTest {
             .doesNotContain("CONFIRMED", "CHANGE_PENDING", "CANCELLED", "SUBMITTED", "FAILED");
     }
 
+    @Test
+    void releasedSupplementSqlCannotWriteTransportOrDeclaredCargo() throws Exception {
+        String sql = String.join("\n", OceanBookingMapper.class.getDeclaredMethod("updateActualCargo",
+            com.baiyue.firstleg.oceanbooking.entity.OceanBookingEntity.class, int.class, long.class, String.class)
+            .getAnnotation(Update.class).value());
+        assertThat(sql).contains("status='RELEASED' AND version=#{version}", "version=version+1",
+            "actual_package_count=#{value.actualPackageCount}", "actual_gross_weight_kg=#{value.actualGrossWeightKg}", "actual_volume_cbm=#{value.actualVolumeCbm}")
+            .doesNotContain("bill_of_lading_no=", "vessel_name=", "declared_", "warehouse_id=", "package_unit=");
+    }
+
     @Test
     void linkCandidatesUsesOneBoundedSetQueryAndExactRemainingSemantics() throws Exception {
         String sql = String.join("\n", OceanBookingMapper.class.getDeclaredMethod("selectLinkCandidates",

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/repository/OceanBookingSqlContractTest.java

@@ -27,8 +27,8 @@ class OceanBookingSqlContractTest {
             .contains("MODIFY COLUMN customer_name VARCHAR(128) NULL COMMENT '可选客户名称快照'")
             .contains("UNIQUE KEY uk_ocean_booking_bill_of_lading (bill_of_lading_no)")
             .contains("ADD UNIQUE KEY uk_ocean_booking_bill_of_lading (bill_of_lading_no)")
-            .doesNotContain("service_term")
-            .doesNotContain("freight_term")
+            .contains("service_term", "declared_package_count", "actual_package_count")
+            .contains("freight_term", "contact_email", "tax_no")
             .contains("carrier_code VARCHAR(16) NULL COMMENT '船司标准编码")
             .contains("carrier_code IS NULL OR carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER')")
             .contains("container_booking_id BIGINT UNSIGNED NOT NULL COMMENT '明确引用现有柜次ID'")
@@ -49,7 +49,7 @@ class OceanBookingSqlContractTest {
     void enforcesStateIdempotencyAndAuditContracts() throws Exception {
         assertThat(sql())
             .contains("OLD.status='DRAFT' AND NEW.status='RELEASED'")
-            .contains("OLD.status = 'RELEASED'")
+            .contains("OLD.status = 'RELEASED'", "NEW.declared_package_count <=> OLD.declared_package_count", "NEW.bill_of_lading_no <=> OLD.bill_of_lading_no", "NEW.version = OLD.version + 1")
             .contains("UNIQUE KEY uk_ocean_operation (operator_id,operation,idempotency_key)")
             .contains("request_hash CHAR(64) NOT NULL")
             .contains("<> 'RELEASED' THEN")

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingPrintServiceTest.java

@@ -49,7 +49,7 @@ class OceanBookingPrintServiceTest {
         assertThat(document.fields()).containsEntry("jobNumber", "OB-1")
             .containsEntry("shipper", "Shipper\nAddress")
             .containsEntry("oceanVesselVoyage", "Vessel / V001")
-            .containsEntry("cargoQuantity", "—")
+            .containsEntry("cargoQuantity", "2*40HQ")
             .containsEntry("totalPackagesInWords", "—")
             .containsKeys("toCompany", "consignee", "notifyParty", "cargoQuantity",
                 "portOfLoading", "portOfDischarge", "placeOfDelivery", "totalPackagesInWords");
@@ -95,6 +95,39 @@ class OceanBookingPrintServiceTest {
             .containsEntry("totalPackagesInWords", "—");
     }
 
+    @Test void routesDeclaredAndActualCargoSeparatelyAndGeneratesWords() {
+        Detail detail = detail("RELEASED");
+        var booking = detail.oceanBooking();
+        booking.setPackageUnit("CARTONS"); booking.setDeclaredPackageCount(500); booking.setActualPackageCount(480);
+        booking.setDeclaredGrossWeightKg(new BigDecimal("15000")); booking.setDeclaredVolumeCbm(new BigDecimal("68"));
+        booking.setActualGrossWeightKg(new BigDecimal("14320.125")); booking.setActualVolumeCbm(new BigDecimal("65.321"));
+        booking.setCargoDescription("HOUSEHOLD GOODS"); booking.setMarksAndNos("N/M");
+        booking.setServiceTerm("CY-CY"); booking.setFreightTerm("FREIGHT PREPAID");
+        detail.parties().get(0).setContactEmail("ops@example.test"); detail.parties().get(0).setTaxNo("TEST-TAX");
+        when(bookings.detail(10L)).thenReturn(detail);
+        when(print.generateFreightA4Documents(any(), any(), any()))
+            .thenReturn(ResponseEntity.ok().contentType(MediaType.APPLICATION_PDF).body(new byte[]{1}));
+        service.shippingInstruction(10L, "split"); service.billConfirmation(10L, "split");
+        var capture = ArgumentCaptor.forClass(PrintPdfClient.FreightA4PdfRequest.class);
+        verify(print, times(2)).generateFreightA4Documents(any(), any(), capture.capture());
+        var declared = capture.getAllValues().get(0).documents().get(0);
+        var actual = capture.getAllValues().get(1).documents().get(0);
+        assertThat(declared.cargoRows().get(0).quantity()).isEqualTo("500");
+        assertThat(declared.cargoRows().get(0).grossWeight()).isEqualTo("15000.000 KGS");
+        assertThat(declared.fields()).containsEntry("totalPackagesInWords", "SAY FIVE HUNDRED CARTONS ONLY")
+            .containsEntry("serviceTerm", "CY-CY").containsEntry("freightTerm", "FREIGHT PREPAID");
+        assertThat(declared.fields().get("shipper")).contains("ops@example.test", "TAX NO: TEST-TAX");
+        assertThat(actual.cargoRows().get(0).quantity()).isEqualTo("480");
+        assertThat(actual.cargoRows().get(0).grossWeight()).isEqualTo("14320.125 KGS");
+        assertThat(actual.cargoRows().get(0).measurement()).isEqualTo("65.321 CBM");
+        assertThat(actual.fields()).containsEntry("totalPackagesInWords", "SAY FOUR HUNDRED EIGHTY CARTONS ONLY");
+        booking.setActualPackageCount(null); booking.setActualGrossWeightKg(null); booking.setActualVolumeCbm(null);
+        service.billConfirmation(10L, "missing");
+        verify(print).generateFreightA4Documents(any(), eq("missing"), capture.capture());
+        assertThat(capture.getValue().documents().get(0).cargoRows().get(0).quantity()).isEqualTo("—");
+        assertThat(capture.getValue().documents().get(0).fields()).containsEntry("totalPackagesInWords", "—");
+    }
+
     private static Detail detail(String status) {
         OceanBookingEntity booking = new OceanBookingEntity();
         booking.setId(10L); booking.setBookingNo("OB-1"); booking.setStatus(status);

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingServiceTest.java

@@ -231,6 +231,26 @@ class OceanBookingServiceTest {
         verify(repository, times(1)).transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin");
     }
 
+    /** 不录预计到港仍可放舱，其余资料及附件门禁保持有效。 */
+    @Test
+    void releasesWithoutEstimatedArrival() {
+        stubMasterData();
+        OceanBookingEntity draft = completeBooking("DRAFT", 3);
+        OceanBookingEntity released = completeBooking("RELEASED", 4);
+        draft.setEstimatedArrivalAt(null);
+        released.setEstimatedArrivalAt(null);
+        when(repository.find(1L)).thenReturn(draft, released);
+        when(repository.parties(1L)).thenReturn(parties());
+        when(repository.requirements(1L)).thenReturn(List.of(requirement()));
+        when(repository.transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin")).thenReturn(1);
+
+        Detail result = service.release(1L, 9L, "admin", "release-no-arrival", new ReleaseRequest(3, "确认放舱"));
+
+        assertThat(result.oceanBooking().getStatus()).isEqualTo("RELEASED");
+        assertThat(result.oceanBooking().getEstimatedArrivalAt()).isNull();
+        verify(documents).requireActiveValidDocument(draft);
+    }
+
     @Test
     void rejectsCarrierSnapshotMismatchAndUnassociatedBookingAgent() {
         stubMasterData();
@@ -386,6 +406,91 @@ class OceanBookingServiceTest {
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
     }
 
+    @Test
+    void supplementsReleasedActualCargoWithVersionAndBeforeAfterAudit() {
+        OceanBookingEntity before = completeBooking("RELEASED", 3);
+        before.setDeclaredPackageCount(500);
+        before.setActualPackageCount(450);
+        AtomicReference<OceanBookingEntity> stored = new AtomicReference<>(before);
+        when(repository.find(1L)).thenAnswer(invocation -> stored.get());
+        when(repository.updateActualCargo(any(), eq(3), eq(9L), eq("admin"))).thenAnswer(invocation -> {
+            OceanBookingEntity after = invocation.getArgument(0);
+            after.setVersion(4); stored.set(after); return 1;
+        });
+        var request = new ActualCargoRequest(3, 480, new BigDecimal("14000.125"), new BigDecimal("65.321"), "修正实装货量");
+        var result = service.updateActualCargo(1L, 9L, "admin", "actual-save", request);
+        assertThat(result.oceanBooking().getActualPackageCount()).isEqualTo(480);
+        assertThat(result.oceanBooking().getDeclaredPackageCount()).isEqualTo(500);
+        assertThat(result.oceanBooking().getBillOfLadingNo()).isEqualTo("BL-001");
+        assertThat(before.getActualPackageCount()).isEqualTo(450);
+        var history = ArgumentCaptor.forClass(com.baiyue.firstleg.oceanbooking.entity.OceanBookingStatusHistoryEntity.class);
+        verify(repository).insert(history.capture());
+        assertThat(history.getValue().getAction()).isEqualTo("UPDATE_ACTUAL_CARGO");
+        assertThat(history.getValue().getBeforeSnapshot()).contains("\"actualPackageCount\":450");
+        assertThat(history.getValue().getAfterSnapshot()).contains("\"actualPackageCount\":480");
+        assertThat(history.getValue().getReason()).isEqualTo("修正实装货量");
+        verify(repository, never()).updateDraft(any(), anyInt(), anyLong(), any());
+        verify(repository, never()).replaceRequirements(anyLong(), any());
+        verifyNoInteractions(documents, priceBooks, suppliers, warehouses);
+    }
+
+    @Test
+    void rejectsActualCargoOnDraftOrStaleVersionAndRequiresReason() {
+        OceanBookingEntity value = completeBooking("DRAFT", 3);
+        when(repository.find(1L)).thenReturn(value);
+        var request = new ActualCargoRequest(3, 100, null, null, "补录");
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-draft", request)).isInstanceOf(BizException.class);
+        value.setStatus("RELEASED");
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-stale",
+            new ActualCargoRequest(2, 100, null, null, "补录"))).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-no-reason",
+            new ActualCargoRequest(3, 100, null, null, " "))).isInstanceOf(BizException.class).hasMessageContaining("原因");
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-negative",
+            new ActualCargoRequest(3, 100, new BigDecimal("-1"), null, "补录"))).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-precision",
+            new ActualCargoRequest(3, 100, null, new BigDecimal("1.0001"), "补录"))).isInstanceOf(BizException.class);
+        when(repository.updateActualCargo(any(), anyInt(), anyLong(), any())).thenReturn(0);
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-concurrent", request)).isInstanceOf(BizException.class);
+        verify(repository, never()).insert(any(com.baiyue.firstleg.oceanbooking.entity.OceanBookingStatusHistoryEntity.class));
+    }
+
+    @Test
+    void replayedActualCargoDoesNotWriteAgain() throws Exception {
+        var request = new ActualCargoRequest(3, 100, null, null, "补录");
+        var replay = new Detail(completeBooking("RELEASED", 4), List.of(), List.of(), List.of(), List.of(), List.of());
+        var operation = new OceanBookingOperationEntity();
+        operation.setRequestHash(hash("UPDATE_ACTUAL_CARGO", 1L, request));
+        operation.setStatus("SUCCESS"); operation.setResultJson(objectMapper.writeValueAsString(replay));
+        when(repository.claimOperation(1L, 9L, "UPDATE_ACTUAL_CARGO", "actual-replay", operation.getRequestHash())).thenReturn(false);
+        when(repository.operation(9L, "UPDATE_ACTUAL_CARGO", "actual-replay")).thenReturn(operation);
+        assertThat(service.updateActualCargo(1L, 9L, "admin", "actual-replay", request).oceanBooking().getVersion()).isEqualTo(4);
+        verify(repository, never()).updateActualCargo(any(), anyInt(), anyLong(), any());
+    }
+
+    @Test
+    void savesUnnamedPartyContactDraftButRequiresNamesBeforeRelease() throws Exception {
+        var tree = (com.fasterxml.jackson.databind.node.ObjectNode) objectMapper.valueToTree(partialDraft(null));
+        tree.putArray("parties").addObject().put("partyType", "SHIPPER").put("partyName", "")
+            .put("contactEmail", "ops@example.test").put("taxNo", "TEST-TAX");
+        stubCreatedDraft();
+        service.create(9L, "admin", "partial-party", new CreateRequest(0, objectMapper.treeToValue(tree, DraftData.class)));
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<List<com.baiyue.firstleg.oceanbooking.entity.OceanBookingPartyEntity>> capture = ArgumentCaptor.forClass(List.class);
+        verify(repository).replaceParties(anyLong(), capture.capture());
+        assertThat(capture.getValue()).singleElement().satisfies(party -> {
+            assertThat(party.getContactEmail()).isEqualTo("ops@example.test");
+            assertThat(party.getTaxNo()).isEqualTo("TEST-TAX");
+        });
+        var draft = completeBooking("DRAFT", 3);
+        when(repository.find(1L)).thenReturn(draft);
+        var parties = parties(); parties.get(0).setPartyName("");
+        when(repository.parties(1L)).thenReturn(parties);
+        when(repository.requirements(1L)).thenReturn(List.of(requirement()));
+        assertThatThrownBy(() -> service.release(1L, 9L, "admin", "missing-party", new ReleaseRequest(3, null)))
+            .isInstanceOf(BizException.class).hasMessageContaining("尚未填写完整");
+        verify(repository, never()).transition(anyLong(), any(), any(), anyInt(), anyLong(), any());
+    }
+
     private AtomicReference<OceanBookingEntity> stubCreatedDraft() {
         AtomicReference<OceanBookingEntity> inserted = new AtomicReference<>();
         doAnswer(invocation -> { inserted.set(invocation.getArgument(0)); return null; })
@@ -412,7 +517,7 @@ class OceanBookingServiceTest {
 
     private static DraftData partialDraft(String remark) {
         return new DraftData(null, null, null, null, null, null, null, null, null, null,
-            null, null, null, null, null, null, null, null, null, remark, null, null);
+            null, null, null, null, null, null, null, null, null, remark, null, null, null, null, null, null, null, null, null, null, null, null, null);
     }
 
     private static DraftData completeDraft() {
@@ -420,11 +525,11 @@ class OceanBookingServiceTest {
             81L, null, "VESSEL", "V001", "CNSZX", "深圳", "USLAX", "洛杉矶",
             "LAX", LocalDateTime.of(2026, 9, 1, 0, 0),
             LocalDateTime.of(2026, 9, 20, 0, 0), null,
-            List.of(new PartyRequest("SHIPPER", "发货人", null, null, null),
-                new PartyRequest("CONSIGNEE", "收货人", null, null, null),
-                new PartyRequest("NOTIFY_PARTY", "通知人", null, null, null)),
+            List.of(new PartyRequest("SHIPPER", "发货人", null, null, null, null, null),
+                new PartyRequest("CONSIGNEE", "收货人", null, null, null, null, null),
+                new PartyRequest("NOTIFY_PARTY", "通知人", null, null, null, null, null)),
             List.of(new ContainerRequirementRequest("40HQ", "DRY", 2,
-                new BigDecimal("68"), new BigDecimal("19500"))));
+                new BigDecimal("68"), new BigDecimal("19500"))), null, null, null, null, null, null, null, null, null, null, null);
     }
 
     private static OceanBookingEntity completeBooking(String status, int version) {

firstleg/src/test/java/com/baiyue/firstleg/portschedule/service/AppointmentForecastServiceTest.java

@@ -9,8 +9,20 @@ import static org.assertj.core.api.Assertions.*;
 import static org.mockito.Mockito.*;
 
 class AppointmentForecastServiceTest {
+    /** 无船期预计观察时仍返回日历所用的柜级到港事实，供海外统一推算日期。 */
+    @Test void returnsTheCalendarArrivalEvenWhenLatestForecastIsAbsent() {
+        var mapper=mock(AppointmentForecastMapper.class);
+        var sources=mock(com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository.class);
+        var arrival=LocalDateTime.of(2026,10,30,23,30);
+        when(sources.byIds(List.of(1L))).thenReturn(List.of(
+            new com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource(1L,"D0001","CONT1",
+                null,null,null,null,arrival,"ACTUAL")));
+        var result=new AppointmentForecastService(mapper,sources).batch(List.of(1L));
+        assertThat(result.get(0).latest()).isNull();
+        assertThat(result.get(0).portArrivalAt()).isEqualTo(arrival);
+    }
     @Test void preservesMissingForecastAndSourceLocalTimesWithoutSynthesizingEta() {
-        var mapper=mock(AppointmentForecastMapper.class);var service=new AppointmentForecastService(mapper);
+        var mapper=mock(AppointmentForecastMapper.class);var service=new AppointmentForecastService(mapper,mock(com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository.class));
         var observed=LocalDateTime.of(2026,10,10,12,0);
         var latest=new AppointmentForecastMapper.Fact(1L,20L,"carrier","REF",observed,null,null);
         var previous=new AppointmentForecastMapper.Fact(1L,10L,"carrier","REF-OLD",observed.minusDays(1),observed.plusDays(5),null);
@@ -21,7 +33,7 @@ class AppointmentForecastServiceTest {
         verify(mapper).latest(List.of(1L,2L));verifyNoMoreInteractions(mapper);
     }
     @Test void rejectsInvalidBatchesAndMissingOrBlankInternalCredentials() {
-        var mapper=mock(AppointmentForecastMapper.class);var service=new AppointmentForecastService(mapper);
+        var mapper=mock(AppointmentForecastMapper.class);var service=new AppointmentForecastService(mapper,mock(com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository.class));
         for(var ids:List.of(List.<Long>of(),List.of(1L,1L),List.of(-1L),Collections.nCopies(201,1L)))
             assertThatThrownBy(()->service.batch(ids)).isInstanceOf(org.springframework.web.server.ResponseStatusException.class);
         assertThatThrownBy(()->service.batch(null)).isInstanceOf(org.springframework.web.server.ResponseStatusException.class);

firstleg/src/test/java/com/baiyue/firstleg/repository/LoadingCompletionCheckpointLeaseTest.java

@@ -0,0 +1,190 @@
+package com.baiyue.firstleg.repository;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean;
+import com.baiyue.firstleg.mapper.LoadingCompletionCommandMapper;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mybatis.spring.SqlSessionTemplate;
+import org.springframework.aop.framework.ProxyFactory;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.datasource.DataSourceTransactionManager;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.transaction.annotation.AnnotationTransactionAttributeSource;
+import org.springframework.transaction.interceptor.TransactionInterceptor;
+
+import java.sql.SQLException;
+import java.time.LocalDateTime;
+import java.util.UUID;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.AdditionalAnswers.delegatesTo;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+
+/** 用真实 Mapper SQL、事务代理和独立连接验证完成检查点的租约隔离。 */
+class LoadingCompletionCheckpointLeaseTest {
+    private JdbcDataSource dataSource;
+    private JdbcTemplate jdbc;
+    private LoadingCompletionCommandMapper mapper;
+    private LoadingCompletionCommandRepository commands;
+
+    /** 每个用例使用独立内存数据库，不访问共享环境。 */
+    @BeforeEach
+    void setup() throws Exception {
+        dataSource = new JdbcDataSource();
+        dataSource.setURL("jdbc:h2:mem:completion-lease-" + UUID.randomUUID()
+            + ";MODE=MySQL;DB_CLOSE_DELAY=-1;LOCK_TIMEOUT=1000");
+        jdbc = new JdbcTemplate(dataSource);
+        jdbc.execute("""
+            CREATE TABLE fl_loading_completion_command(
+              id BIGINT PRIMARY KEY,command_status VARCHAR(16),lease_owner VARCHAR(128),lease_until TIMESTAMP,
+              attempt_count INT,next_retry_at TIMESTAMP,updated_at TIMESTAMP,completed_at TIMESTAMP,
+              failure_stage VARCHAR(40),failure_code VARCHAR(32),failure_request_id VARCHAR(64),failure_trace_id VARCHAR(64))
+            """);
+        jdbc.execute("""
+            CREATE TABLE fl_loading_completion_checkpoint(
+              command_id BIGINT,tenant_id BIGINT,inbound_id BIGINT,owner_sequence INT,checkpoint_stage VARCHAR(24),
+              updated_at TIMESTAMP,PRIMARY KEY(command_id,tenant_id,inbound_id))
+            """);
+        jdbc.update("""
+            INSERT INTO fl_loading_completion_command(id,command_status,lease_owner,lease_until,attempt_count,next_retry_at)
+            VALUES(900,'PROCESSING','old-owner',DATEADD('HOUR',1,CURRENT_TIMESTAMP),1,CURRENT_TIMESTAMP)
+            """);
+        var configuration = new MybatisConfiguration();
+        configuration.setMapUnderscoreToCamelCase(true);
+        configuration.addMapper(LoadingCompletionCommandMapper.class);
+        var factory = new MybatisSqlSessionFactoryBean();
+        factory.setDataSource(dataSource);
+        factory.setConfiguration(configuration);
+        mapper = new SqlSessionTemplate(factory.getObject()).getMapper(LoadingCompletionCommandMapper.class);
+        commands = repository(mapper);
+    }
+
+    /** 生产 Repository 的注解事务必须真实生效，覆盖锁定与写入两条 SQL。 */
+    private LoadingCompletionCommandRepository repository(LoadingCompletionCommandMapper targetMapper) {
+        var target = new LoadingCompletionCommandRepository();
+        ReflectionTestUtils.setField(target, "mapper", targetMapper);
+        var proxy = new ProxyFactory(target);
+        proxy.addAdvice(new TransactionInterceptor(new DataSourceTransactionManager(dataSource),
+            new AnnotationTransactionAttributeSource()));
+        return (LoadingCompletionCommandRepository) proxy.getProxy();
+    }
+
+    /** 模拟原执行者续租后暂停，租约过期并被新执行者领取推进，再恢复旧线程。 */
+    @Test
+    void pausedOldOwnerCannotDowngradeTheNewOwnersCompletedCheckpoint() throws Exception {
+        var renewed = new CountDownLatch(1);
+        var resumeOldOwner = new CountDownLatch(1);
+        var executor = Executors.newSingleThreadExecutor();
+        try {
+            var oldWrite = executor.submit(() -> {
+                assertThat(commands.renew(900, "old-owner", LocalDateTime.now().plusMinutes(10))).isTrue();
+                renewed.countDown();
+                assertThat(resumeOldOwner.await(10, TimeUnit.SECONDS)).isTrue();
+                return commands.checkpoint(900, "old-owner", 101, 50, 1, "READY");
+            });
+            assertThat(renewed.await(10, TimeUnit.SECONDS)).isTrue();
+            jdbc.update("UPDATE fl_loading_completion_command SET lease_until=DATEADD('SECOND',-1,CURRENT_TIMESTAMP) WHERE id=900");
+            assertThat(commands.claim(900, "new-owner", LocalDateTime.now().plusMinutes(10))).isTrue();
+            assertThat(commands.checkpoint(900, "new-owner", 101, 50, 1, "INBOUND_COMPLETED")).isTrue();
+            resumeOldOwner.countDown();
+            assertThat(oldWrite.get(10, TimeUnit.SECONDS)).isFalse();
+            assertThat(mapper.checkpointCompleted(900, "old-owner", 101, 50, 1, "SETTLED")).isZero();
+            assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("INBOUND_COMPLETED");
+            assertThat(jdbc.queryForObject("SELECT lease_owner FROM fl_loading_completion_command WHERE id=900", String.class))
+                .isEqualTo("new-owner");
+        } finally {
+            resumeOldOwner.countDown();
+            executor.shutdownNow();
+        }
+    }
+
+    /** 锁定后的实际写入前，独立数据库连接仍不能取得同一命令行的锁。 */
+    @Test
+    void commandRowRemainsLockedAcrossTheLeaseCheckAndCheckpointInsert() {
+        LoadingCompletionCommandMapper observed = mock(LoadingCompletionCommandMapper.class, delegatesTo(mapper));
+        doAnswer(call -> {
+            assertThatThrownBy(() -> {
+                try (var connection = dataSource.getConnection();
+                     var statement = connection.prepareStatement("SELECT id FROM fl_loading_completion_command WHERE id=900 FOR UPDATE NOWAIT")) {
+                    statement.executeQuery().close();
+                }
+            }).isInstanceOf(SQLException.class)
+                .satisfies(error -> assertThat(((SQLException) error).getErrorCode()).isEqualTo(50200));
+            return mapper.checkpointCompleted(call.getArgument(0), call.getArgument(1), call.getArgument(2),
+                call.getArgument(3), call.getArgument(4), call.getArgument(5));
+        }).when(observed).checkpointCompleted(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString());
+        assertThat(repository(observed).checkpoint(900, "old-owner", 101, 50, 1, "READY")).isTrue();
+        assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("READY");
+    }
+
+    /** 初次锁定检查后若租约失效，实际 INSERT 也必须拒绝，不能仅依赖前一次检查。 */
+    @Test
+    void checkpointInsertRechecksLeaseValidityAfterTheInitialLock() {
+        LoadingCompletionCommandMapper observed = mock(LoadingCompletionCommandMapper.class, delegatesTo(mapper));
+        doAnswer(call -> {
+            jdbc.update("UPDATE fl_loading_completion_command SET lease_until=DATEADD('SECOND',-1,CURRENT_TIMESTAMP) WHERE id=900");
+            return mapper.checkpointCompleted(call.getArgument(0), call.getArgument(1), call.getArgument(2),
+                call.getArgument(3), call.getArgument(4), call.getArgument(5));
+        }).when(observed).checkpointCompleted(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString());
+        assertThat(repository(observed).checkpoint(900, "old-owner", 101, 50, 1, "READY")).isFalse();
+        assertThat(commands.checkpoint(900, 101, 50)).isNull();
+    }
+
+    /** 驱动将已持久化的幂等重放计为零行时，仍须以锁内当前有效租约确认。 */
+    @Test
+    void zeroAffectedRowsCanConfirmAnIdempotentCheckpointUnderTheSameValidLease() {
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "READY")).isTrue();
+        LoadingCompletionCommandMapper observed = mock(LoadingCompletionCommandMapper.class, delegatesTo(mapper));
+        doAnswer(call -> {
+            mapper.checkpointCompleted(call.getArgument(0), call.getArgument(1), call.getArgument(2),
+                call.getArgument(3), call.getArgument(4), call.getArgument(5));
+            return 0;
+        }).when(observed).checkpointCompleted(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString());
+        assertThat(repository(observed).checkpoint(900, "old-owner", 101, 50, 1, "READY")).isTrue();
+        assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("READY");
+    }
+
+    /** 已过期但尚未被重新领取的所有者也不能写检查点、续租或写命令终态。 */
+    @Test
+    void expiredLeaseCannotWriteCheckpointRenewFailOrComplete() {
+        jdbc.update("UPDATE fl_loading_completion_command SET lease_until=DATEADD('SECOND',-1,CURRENT_TIMESTAMP) WHERE id=900");
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "READY")).isFalse();
+        assertThat(mapper.checkpointCompleted(900, "old-owner", 101, 50, 1, "READY")).isZero();
+        assertThat(commands.renew(900, "old-owner", LocalDateTime.now().plusMinutes(10))).isFalse();
+        assertThat(commands.fail(900, "old-owner", "FAILED", LocalDateTime.now(), "LEASE_LOST", "A0409", null, null)).isFalse();
+        assertThat(commands.complete(900, "old-owner")).isFalse();
+        assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM fl_loading_completion_checkpoint", Integer.class)).isZero();
+        assertThat(jdbc.queryForObject("SELECT command_status FROM fl_loading_completion_command WHERE id=900", String.class))
+            .isEqualTo("PROCESSING");
+    }
+
+    /** 同一当前所有者的重复或迟到阶段也只能保持或推进，不能降低完成检查点。 */
+    @Test
+    void validOwnerCheckpointStagesAreMonotonic() {
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "SETTLED")).isTrue();
+        commands.checkpoint(900, "old-owner", 101, 50, 1, "READY");
+        assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("SETTLED");
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "INBOUND_COMPLETED")).isTrue();
+        commands.checkpoint(900, "old-owner", 101, 50, 1, "SETTLED");
+        commands.checkpoint(900, "old-owner", 101, 50, 1, "READY");
+        assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("INBOUND_COMPLETED");
+    }
+
+    /** 完成或失败后的命令不允许追加检查点，即使所有者与租期字段仍有旧值。 */
+    @Test
+    void terminalCommandCannotAcceptAnotherCheckpoint() {
+        jdbc.update("UPDATE fl_loading_completion_command SET command_status='COMPLETED' WHERE id=900");
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "READY")).isFalse();
+        assertThat(mapper.checkpointCompleted(900, "old-owner", 101, 50, 1, "READY")).isZero();
+    }
+}

firstleg/src/test/java/com/baiyue/firstleg/repository/LoadingCompletionOwnerPersistenceTest.java

@@ -31,6 +31,8 @@ class LoadingCompletionOwnerPersistenceTest {
         jdbc.execute("CREATE TABLE fl_loading_plan_item(id BIGINT,loading_plan_id BIGINT,account_id BIGINT,inbound_id BIGINT,deleted INT,package_count INT)");
         jdbc.execute("CREATE TABLE fl_loading_pick_item(id BIGINT,pick_task_id BIGINT,loading_plan_item_id BIGINT,item_status VARCHAR,picked_package_count INT)");
         jdbc.execute("CREATE TABLE fl_loading_completion_checkpoint(command_id BIGINT,tenant_id BIGINT,inbound_id BIGINT,owner_sequence INT,checkpoint_stage VARCHAR(24),updated_at TIMESTAMP,PRIMARY KEY(command_id,tenant_id,inbound_id))");
+        jdbc.execute("CREATE TABLE fl_loading_completion_command(id BIGINT PRIMARY KEY,command_status VARCHAR(16),lease_owner VARCHAR(128),lease_until TIMESTAMP)");
+        jdbc.update("INSERT INTO fl_loading_completion_command VALUES(900,'PROCESSING','owner-test',DATEADD('HOUR',1,CURRENT_TIMESTAMP))");
         jdbc.update("INSERT INTO fl_loading_pick_task VALUES(20,10)");
         row(1, 101, 50, 3, "PARTIAL", 2, 10, 0);
         row(2, 101, 50, 1, "SKIPPED", 0, 10, 0); // same source SKU history
@@ -76,11 +78,11 @@ class LoadingCompletionOwnerPersistenceTest {
 
     @Test
     void completedActualCheckpointsAreReadBackUnchangedAndSkippedReadyCheckpointIsNotACompletionOwner() {
-        checkpoints.checkpointCompleted(900, 101, 50, 1, "READY");
-        checkpoints.checkpointCompleted(900, 101, 50, 1, "SETTLED");
-        checkpoints.checkpointCompleted(900, 101, 50, 1, "INBOUND_COMPLETED");
-        checkpoints.checkpointCompleted(900, 202, 60, 2, "INBOUND_COMPLETED");
-        checkpoints.checkpointCompleted(900, 303, 70, 3, "READY");
+        checkpoints.checkpointCompleted(900, "owner-test", 101, 50, 1, "READY");
+        checkpoints.checkpointCompleted(900, "owner-test", 101, 50, 1, "SETTLED");
+        checkpoints.checkpointCompleted(900, "owner-test", 101, 50, 1, "INBOUND_COMPLETED");
+        checkpoints.checkpointCompleted(900, "owner-test", 202, 60, 2, "INBOUND_COMPLETED");
+        checkpoints.checkpointCompleted(900, "owner-test", 303, 70, 3, "READY");
         assertThat(checkpoints.checkpoint(900, 101, 50)).isEqualTo("INBOUND_COMPLETED");
         assertThat(checkpoints.checkpoint(900, 202, 60)).isEqualTo("INBOUND_COMPLETED");
         assertThat(checkpoints.checkpoint(900, 303, 70)).isEqualTo("READY");

firstleg/src/test/java/com/baiyue/firstleg/service/LoadingCompletionWorkerTest.java

@@ -8,22 +8,124 @@ import com.baiyue.firstleg.repository.LoadingPickRepository;
 import org.junit.jupiter.api.Test;
 import org.springframework.boot.test.mock.mockito.MockBean;
 import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.task.TaskExecutor;
+import org.springframework.transaction.TransactionDefinition;
+import org.springframework.transaction.annotation.EnableTransactionManagement;
+import org.springframework.transaction.support.AbstractPlatformTransactionManager;
+import org.springframework.transaction.support.DefaultTransactionStatus;
+import org.springframework.transaction.support.TransactionTemplate;
+import org.mockito.ArgumentCaptor;
 
 import java.time.LocalDateTime;
 import java.util.List;
+import java.util.concurrent.RejectedExecutionException;
 
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
-@SpringJUnitConfig(LoadingCompletionWorker.class)
+@SpringJUnitConfig({LoadingCompletionWorker.class, LoadingCompletionWorkerTest.TransactionEvents.class})
 class LoadingCompletionWorkerTest {
+    /** 与生产事务装配一致，注册事务事件工厂，避免普通事件工厂立即调用监听器。 */
+    @Configuration
+    @EnableTransactionManagement
+    static class TransactionEvents {}
+
     @MockBean private LoadingCompletionCommandRepository commands;
     @MockBean private LoadingPickRepository picks;
     @MockBean private LoadingPickService loadingPicks;
+    @MockBean(name = "applicationTaskExecutor") private TaskExecutor completionExecutor;
     @jakarta.annotation.Resource private LoadingCompletionWorker worker;
+    @jakarta.annotation.Resource private ApplicationEventPublisher events;
+
+    /** 真实事务同步回调必须在提交后才将完成工作交给执行器。 */
+    @Test
+    void committedAcceptanceStartsImmediatelyThroughTheDurableLease() {
+        LoadingCompletionCommandEntity command = command(0);
+        when(commands.command(900L)).thenReturn(command);
+        when(commands.claim(eq(900L), any(String.class), any(LocalDateTime.class))).thenReturn(true);
+        transactions().executeWithoutResult(status -> {
+            events.publishEvent(new LoadingPickService.CompletionAccepted(900L, System.nanoTime()));
+            verify(completionExecutor, never()).execute(any());
+            verify(loadingPicks, never()).processCompletion(any(), any());
+        });
+
+        ArgumentCaptor<Runnable> work = ArgumentCaptor.forClass(Runnable.class);
+        verify(completionExecutor).execute(work.capture());
+        verify(loadingPicks, never()).processCompletion(any(), any());
+        work.getValue().run();
+
+        verify(commands).claim(eq(900L), any(String.class), any(LocalDateTime.class));
+        verify(loadingPicks).processCompletion(eq(command), any(String.class));
+    }
+
+    /** 回滚后的命令没有权威落库事实，不允许唤醒或执行结算。 */
+    @Test
+    void rolledBackAcceptanceNeverSchedulesCompletion() {
+        transactions().executeWithoutResult(status -> {
+            events.publishEvent(new LoadingPickService.CompletionAccepted(900L, System.nanoTime()));
+            status.setRollbackOnly();
+        });
+        verify(completionExecutor, never()).execute(any());
+        verify(commands, never()).command(900L);
+    }
+
+    /** 即时唤醒不能绕过定时执行者已取得的租约。 */
+    @Test
+    void immediateWakeupDoesNotProcessAnAlreadyLeasedCommand() {
+        when(commands.command(900L)).thenReturn(command(0));
+        worker.accepted(new LoadingPickService.CompletionAccepted(900L, System.nanoTime()));
+        ArgumentCaptor<Runnable> work = ArgumentCaptor.forClass(Runnable.class);
+        verify(completionExecutor).execute(work.capture());
+        work.getValue().run();
+        verify(loadingPicks, never()).processCompletion(any(), any());
+    }
+
+    /** 执行器拒绝时受理不报错，定时扫描仍可从原命令恢复。 */
+    @Test
+    void rejectedWakeupLeavesScheduledRecoveryAvailable() {
+        doThrow(new RejectedExecutionException("busy")).when(completionExecutor).execute(any());
+        LoadingCompletionCommandEntity command = command(0);
+        when(commands.due(10)).thenReturn(List.of(command));
+        when(commands.claim(eq(900L), any(String.class), any(LocalDateTime.class))).thenReturn(true);
+        worker.accepted(new LoadingPickService.CompletionAccepted(900L, System.nanoTime()));
+        worker.dispatch();
+        verify(loadingPicks).processCompletion(eq(command), any(String.class));
+    }
+
+    /** 同进程重领已到期命令也必须更换所有者，旧线程不能续租或落库。 */
+    @Test
+    void everyClaimUsesAnIndependentLeaseOwner() {
+        LoadingCompletionCommandEntity command = command(0);
+        when(commands.due(10)).thenReturn(List.of(command));
+        when(commands.claim(eq(900L), any(String.class), any(LocalDateTime.class))).thenReturn(true);
+        worker.dispatch();
+        worker.dispatch();
+        ArgumentCaptor<String> owners = ArgumentCaptor.forClass(String.class);
+        verify(loadingPicks, times(2)).processCompletion(eq(command), owners.capture());
+        assertThat(owners.getAllValues()).doesNotHaveDuplicates();
+    }
+
+    /** 隔离数据库依赖，仅用 Spring 的真实事务同步机制核对提交、回滚边界。 */
+    private static TransactionTemplate transactions() {
+        return new TransactionTemplate(new AbstractPlatformTransactionManager() {
+            /** 为每次测试提供独立事务对象。 */
+            @Override protected Object doGetTransaction() { return new Object(); }
+            /** 测试事务不访问数据库。 */
+            @Override protected void doBegin(Object transaction, TransactionDefinition definition) {}
+            /** 让 Spring 正常触发提交同步回调。 */
+            @Override protected void doCommit(DefaultTransactionStatus status) {}
+            /** 让 Spring 正常触发回滚同步回调。 */
+            @Override protected void doRollback(DefaultTransactionStatus status) {}
+        });
+    }
 
     @Test
     void transientFailureIsReleasedForBackoffRetry() {

firstleg/src/test/java/com/baiyue/firstleg/service/LoadingPickServiceTest.java

@@ -50,6 +50,9 @@ import org.mockito.InOrder;
 import org.mockito.ArgumentCaptor;
 import org.springframework.boot.test.mock.mockito.MockBean;
 import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.test.context.event.RecordApplicationEvents;
+import org.springframework.test.context.event.ApplicationEvents;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.transaction.TransactionStatus;
 import org.springframework.transaction.support.TransactionTemplate;
 
@@ -77,7 +80,9 @@ import static org.mockito.Mockito.clearInvocations;
 import static org.assertj.core.api.Assertions.assertThat;
 
 @SpringJUnitConfig(LoadingPickService.class)
+@RecordApplicationEvents
 class LoadingPickServiceTest {
+    @Autowired private ApplicationEvents completionEvents;
     @MockBean
     private LoadingPickRepository repository;
     @MockBean
@@ -154,6 +159,8 @@ class LoadingPickServiceTest {
         when(repository.activeBookingByTask(20L)).thenReturn(booking);
         when(completionCommands.insert(any())).thenReturn(1);
         when(completionCommands.renew(anyLong(), anyString(), any(java.time.LocalDateTime.class))).thenReturn(true);
+        when(completionCommands.checkpoint(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString()))
+            .thenReturn(true);
         when(repository.acceptCompletion(anyLong(), anyInt())).thenReturn(1);
         when(repository.inboundOwners(anyLong())).thenReturn(List.of(
             new LoadingPickItemMapper.InboundOwner(101L, 50L)));
@@ -931,6 +938,7 @@ class LoadingPickServiceTest {
         assertThat(replay.taskStatus()).isEqualTo("COMPLETING");
         verify(repository, never()).taskForUpdate(20L);
         verify(completionCommands, times(1)).insert(any());
+        assertThat(completionEvents.stream(LoadingPickService.CompletionAccepted.class).count()).isEqualTo(1);
         verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingListService, never()).finishFromPda(anyLong(), anyLong(), anyLong(), anyString());
     }
@@ -997,6 +1005,8 @@ class LoadingPickServiceTest {
 
         assertThat(result.workflowStatus()).isEqualTo("PROCESSING");
         verify(completionCommands).resume(902L);
+        assertThat(completionEvents.stream(LoadingPickService.CompletionAccepted.class)
+            .map(LoadingPickService.CompletionAccepted::commandId)).containsExactly(902L);
         verify(repository).resumeCompletion(20L);
         verify(completionCommands, never()).insert(any());
     }
@@ -1089,7 +1099,7 @@ class LoadingPickServiceTest {
         verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingDeliveryService, never()).completeAfterPdaSettlement(anyLong(), anyLong(), anyLong(), anyString(), anyString(), anyString());
         verify(completionCommands, never()).checkpoint(eq(931L), eq(303L), eq(70L));
-        verify(completionCommands, never()).checkpoint(eq(931L), anyLong(), anyLong(), anyInt(), anyString());
+        verify(completionCommands, never()).checkpoint(eq(931L), anyString(), anyLong(), anyLong(), anyInt(), anyString());
         verify(loadingListService).publishCompletedEvent(10L);
         verify(completionCommands).complete(931L, "worker-completed-checkpoints");
     }
@@ -1109,6 +1119,31 @@ class LoadingPickServiceTest {
         verify(loadingListService, never()).publishCompletedEvent(anyLong());
     }
 
+    /** 任一检查点被租约拒绝后都不得继续下一业务步骤或最终完成柜次。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"READY", "SETTLED", "INBOUND_COMPLETED"})
+    void lostLeaseAtCheckpointStopsFurtherCompletion(String rejectedStage) {
+        LoadingPickTaskEntity completing = task();
+        completing.setTaskStatus("COMPLETING");
+        when(repository.task(20L)).thenReturn(completing);
+        when(completionCommands.checkpoint(eq(940L), eq("old-owner"), eq(101L), eq(50L), eq(1), eq(rejectedStage)))
+            .thenReturn(false);
+
+        assertThatThrownBy(() -> service.processCompletion(completionCommand(940L, "lost-checkpoint"), "old-owner"))
+            .isInstanceOf(LoadingPickService.CompletionProcessingException.class)
+            .satisfies(error -> assertThat(((LoadingPickService.CompletionProcessingException) error).stage())
+                .isEqualTo("LEASE_LOST"));
+        if ("READY".equals(rejectedStage)) {
+            verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
+        }
+        if (!"INBOUND_COMPLETED".equals(rejectedStage)) {
+            verify(loadingDeliveryService, never()).completeAfterPdaSettlement(anyLong(), anyLong(), anyLong(),
+                anyString(), anyString(), anyString());
+        }
+        verify(loadingListService, never()).finishFromPda(anyLong(), anyLong(), anyLong(), anyString());
+        verify(completionCommands, never()).complete(anyLong(), anyString());
+    }
+
     @Test
     void anEntirelySkippedTaskCannotCreateACompletionCommand() {
         when(repository.taskForUpdate(20L)).thenReturn(task());
@@ -1271,8 +1306,8 @@ class LoadingPickServiceTest {
         verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingDeliveryService, never()).completeAfterPdaSettlement(anyLong(), anyLong(), anyLong(),
             anyString(), anyString(), anyString());
-        verify(completionCommands).checkpoint(904L, 101L, 50L, 1, "READY");
-        verify(completionCommands, never()).checkpoint(eq(904L), anyLong(), anyLong(), anyInt(),
+        verify(completionCommands).checkpoint(904L, "worker-failure", 101L, 50L, 1, "READY");
+        verify(completionCommands, never()).checkpoint(eq(904L), anyString(), anyLong(), anyLong(), anyInt(),
             eq("SETTLED"));
         verify(repository, never()).insert(any(LoadingPickOperationEntity.class));
         verify(loadingListService, never()).finishFromPda(anyLong(), anyLong(), anyLong(), anyString());
@@ -1300,7 +1335,7 @@ class LoadingPickServiceTest {
         verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingDeliveryService, never()).completeAfterPdaSettlement(anyLong(), anyLong(), anyLong(),
             anyString(), anyString(), anyString());
-        verify(completionCommands, never()).checkpoint(anyLong(), anyLong(), anyLong(), anyInt(), anyString());
+        verify(completionCommands, never()).checkpoint(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString());
         verify(repository, never()).insert(any(LoadingPickOperationEntity.class));
         verify(loadingListService, never()).finishFromPda(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingListService, never()).publishCompletedEvent(anyLong());

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

@@ -46,6 +46,8 @@ class ContainerCalendarSourceMapperTest {
             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());
+            var explicit = session.getMapper(ContainerCalendarSourceMapper.class).byIds(java.util.List.of(1L,2L));
+            assertEquals(calendar,explicit);
             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");

firstleg/src/test/java/com/baiyue/firstleg/workflow/WorkflowBoundaryTest.java

@@ -36,8 +36,8 @@ class WorkflowBoundaryTest {
         assertThatThrownBy(()->service.rows(List.of(inbound))).isInstanceOf(BizException.class).hasCause(failure);
     }
 
-    /** 未记录离港时，报关完成即可待清关；上传清关资料后也必须查询精确海外来源。 */
-    @Test void completedCustomsAndClearanceUploadDoNotWaitForDeparture() {
+    /** 报关完成或提前上传资料仍留在出口报关，实际开船后才查询精确海外来源。 */
+    @Test void completedCustomsAndClearanceUploadWaitForActualDeparture() {
         var repository=mock(WorkflowFactRepository.class);
         var downstream=mock(LastlegWorkflowClient.class);
         var service=new WorkflowTabService(repository,downstream);
@@ -45,12 +45,21 @@ class WorkflowBoundaryTest {
         inbound.setOrderId(101L);inbound.setProcessStatus("LOADED");
         when(repository.facts(List.of(1L))).thenReturn(List.of(
             new WorkflowFacts.Fact(11,1,101,"APPROVED",false,false,false,true,true)));
-        assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("SAILING_CLEARANCE");
+        assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("EXPORT_CUSTOMS");
         verifyNoInteractions(downstream);
         when(repository.facts(List.of(1L))).thenReturn(List.of(
             new WorkflowFacts.Fact(11,1,101,"APPROVED",false,true,false,true,true)));
+        assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("EXPORT_CUSTOMS");
+        verifyNoInteractions(downstream);
+        when(repository.facts(List.of(1L))).thenReturn(List.of(
+            new WorkflowFacts.Fact(11,1,101,"APPROVED",true,false,false,true,true)));
         when(downstream.read(any(),any())).thenReturn(ApiResponse.success(List.of(
             new WorkflowFacts.Overseas(11,1,false,false,false,false))));
+        assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("SAILING_CLEARANCE");
+        verify(downstream).read(any(),eq(new WorkflowFacts.Request(List.of(new WorkflowFacts.Source(11,1)))));
+        clearInvocations(downstream);
+        when(repository.facts(List.of(1L))).thenReturn(List.of(
+            new WorkflowFacts.Fact(11,1,101,"APPROVED",true,true,false,true,true)));
         assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("WAIT_UNLOAD","WAIT_DISPATCH");
         verify(downstream).read(any(),eq(new WorkflowFacts.Request(List.of(new WorkflowFacts.Source(11,1)))));
     }

firstleg/src/test/java/com/baiyue/firstleg/workflow/WorkflowBusinessTest.java

@@ -3,7 +3,7 @@ import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.*;
 /** 取消回显、分柜隔离和资料页签回归。 */
 class WorkflowBusinessTest {
-    /** 报关完成进入待清关，清关资料保存后才进入拆柜与排车待办。 */
+    /** 实际开船前保留出口报关，实际开船后再按清关资料进入海外待办。 */
     @Test void customsDocumentsDepartureAndClearanceDriveTabs() {
         var missing=new WorkflowFacts.Fact(11,1,101,"APPROVED",false,false,true,false,false);
         var uploaded=new WorkflowFacts.Fact(11,1,101,"APPROVED",false,false,false,true,false);
@@ -18,9 +18,9 @@ class WorkflowBusinessTest {
         assertThat(WorkflowTabService.classify(uploaded,"LOADED",null))
             .contains("EXPORT_CUSTOMS").doesNotContain("WAIT_CUSTOMS_DOCS","SAILING_CLEARANCE","WAIT_UNLOAD");
         assertThat(WorkflowTabService.classify(completed,"LOADED",null))
-            .containsExactly("SAILING_CLEARANCE");
+            .containsExactly("EXPORT_CUSTOMS");
         assertThat(WorkflowTabService.classify(uploadedBeforeDeparture,"LOADED",pendingUnload))
-            .containsExactly("WAIT_UNLOAD","WAIT_DISPATCH");
+            .containsExactly("EXPORT_CUSTOMS");
         assertThat(WorkflowTabService.classify(departed,"LOADED",pendingUnload))
             .containsExactly("SAILING_CLEARANCE");
         assertThat(WorkflowTabService.classify(cleared,"LOADED",pendingUnload))

lastleg-service/docs/business-index.md

@@ -22,10 +22,10 @@
 |---|---|
 | 内部模块化基线与依赖分析 | `docs/lastleg-internal-modularization-baseline.md`、`scripts/analyze-lastleg-dependencies.mjs`、`scripts/analyze-lastleg-dependencies.test.mjs`、`src/test/resources/architecture/lastleg-slice-dependencies.json`；只约束本服务内部包依赖，不改变部署单元或数据库边界 |
 | 事件接收、平台订单列表/详情、柜级进度、目的仓调整 | `src/main/java/com/baiyue/lastleg/controller/LastlegOrderController.java`；`/api/platform/v1/last-leg/orders/container-summaries` 按 `sourceContainerBookingId` 服务端聚合全柜订单、入仓码、有效计划及托盘资源异常并分页返回全部稳定来源柜，已完成计划转换的柜仍保留用于接柜仓查询与修改；单票手工计划保存后，整柜最后一票齐全时自动生成并绑定全柜托盘码，一票柜立即生成，`resourcePendingPlanCount` 只作为失败重试事实；`/{sourceContainerBookingId}` 返回柜内全部订单/入仓码/计划状态且不受订单分页截断；`plannedArrivalAt` 只取装柜完成事件 `estimatedWarehouseArrivalAt` 冻结到 `ll_order.estimated_warehouse_at` 的正式事实，按其升序、null 最后、稳定柜 ID 排序；目的仓调整仅接受国内 Warehouse Service 平台公共 `ACTIVE + FBA` 主档，写入前由 `service/FbaWarehouseValidator.java` 经内部只读目录校验 ID/编码/名称一致 |
-| 尾程订单完整计划、柜级到仓时间、暂扣与人工节点 | `controller/LastlegOrderController.java`、`service/LastlegOrderCommandService.java`、`inboundplan/service/InboundPlanService.java`、`dto/LastlegOrderCommandDtos.java`；Admin 清关提柜列表通过 `/orders/container-arrival-times/query` 批量读取整柜预计/实际到仓，预计时间在任何入库计划生成前按柜级版本与幂等键人工维护并原子同步全柜 `ll_order.estimated_warehouse_at`，实际时间只取海外 PDA 会话首次 `receiving_at`。单票计划写入校验订单版本、客户范围、订单冻结入仓码、稳定接柜仓 ID、当前仓库主档与幂等键；预计到仓日期不接受计划请求输入，必须锁定来源柜全部订单的 `estimated_warehouse_at`，缺失或同柜不一致时阻断，人工与自动计划统一写其日期；一件代发人工计划必须逐托沿用不可变头程封托的 DP 托盘码和箱数，托数及各托箱数均不得重新分配，禁止保存无法绑定真实资源的半成品计划；接柜仓编码/名称以该 ID 当前目录快照为准，不要求订单残留旧展示快照。暂扣/解除写不可变历史并发布 `InboundOrderDetainedOutboxService`；新增暂扣只允许完成入库且尚未进入出库流程的订单，解除暂扣不受该状态限制；暂扣只阻断排车和出库，不阻断入库计划或入库作业。人工节点必须一次提交固定八行完整快照且至少一个时间，首次保存后永久使用 `MANUAL` 来源，不得回退柜级节点或反向修改头程船节点 |
+| 尾程订单完整计划、柜级到仓时间、暂扣与人工节点 | `controller/LastlegOrderController.java`、`service/LastlegOrderCommandService.java`、`inboundplan/service/InboundPlanService.java`、`dto/LastlegOrderCommandDtos.java`；Admin 清关提柜列表通过 `/orders/container-arrival-times/query` 批量读取整柜预计/实际到仓，预计时间在任何入库计划生成前按柜级版本与幂等键人工维护并原子同步全柜 `ll_order.estimated_warehouse_at`，实际时间只取海外 PDA 会话首次 `receiving_at`。单票计划写入校验订单版本、客户范围、订单冻结入仓码、稳定接柜仓 ID、当前仓库主档与幂等键；预计到仓日期不接受计划请求输入，必须锁定来源柜，并由 `ContainerWarehouseArrivalService` 统一解析：人工维护日期或已有计划冻结日期优先，未维护未建计划时读取 Firstleg 权威到港当地日期加两个自然日；缺失或同柜不一致时阻断，清关提柜、日历和人工/自动计划统一使用 `plannedDate`，默认日期不补零点，首个计划创建后按已有计划日期冻结；一件代发人工计划必须逐托沿用不可变头程封托的 DP 托盘码和箱数，托数及各托箱数均不得重新分配，禁止保存无法绑定真实资源的半成品计划；接柜仓编码/名称以该 ID 当前目录快照为准，不要求订单残留旧展示快照。暂扣/解除写不可变历史并发布 `InboundOrderDetainedOutboxService`；新增暂扣只允许完成入库且尚未进入出库流程的订单，解除暂扣不受该状态限制；暂扣只阻断排车和出库，不阻断入库计划或入库作业。人工节点必须一次提交固定八行完整快照且至少一个时间，首次保存后永久使用 `MANUAL` 来源，不得回退柜级节点或反向修改头程船节点 |
 | 客户尾程订单列表与详情 | `controller/MerchantLastlegOrderController.java`；客户范围只取认证身份，稳定类型/状态见 `model/LastlegOrderType.java`、`LastlegOrderStatus.java` |
 | 装柜完成事件消费 | `service/LoadingCompletedConsumer.java`；当前生产信封为 `FIRST_LEG_LOADING_PLAN_COMPLETED` V3，消费端除冻结 V2 货物事实外，按 `sourceContainerBookingId` 幂等投影物理柜五类国内装柜照片；FBA 可按箱数且不生成逐箱作业账，OVERSEAS 必须逐箱校验并生成箱级事实；V1/V2 仅用于历史事件读取 |
-| 尾程单号生成 | `service/LastlegOrderNoGenerator.java` |
+| 尾程单号生成 | `service/LastlegOrderNoGenerator.java`、`service/LastlegDocumentNumberGenerator.java`；头程来源使用14位 `WC + yyyyMMdd + 四位流水`，建单经 `service/LoadingCompletedConsumer.java` 在来源柜锁内复用已有号，正式格式见工作区 `docs/业务单据编号契约.md` |
 | 订单查询与更新 | `service/LastlegOrderService.java` |
 | 业务 Inbox | `entity/LastlegEventInbox.java`、`mapper/LastlegEventInboxMapper.java` |
 | 尾程订单、明细、状态历史 | `entity/LastlegOrder.java`、`LastlegOrderDetail.java`、`LastlegOrderStatusHistory.java` 及对应 Mapper |
@@ -112,7 +112,7 @@
 ## 事件建单规则
 
 - 只接受冻结契约支持的事件类型和版本；校验事件 ID、租户、区域、Payload 哈希及必要字段。
-- 同一实际集装箱 `containerNo` 生成一个共享业务尾程单号；`payload.orders` 每项按 `sourceInboundId` 独立落一条雪花 ID `ll_order`，并保存对应明细和初始状态历史。整柜操作不使用 `cabinetNo`。
+- 同一冻结来源柜 `sourceContainerBookingId` 共用一个14位 `WC + yyyyMMdd + 四位流水` 尾程单号；首个交接事件在来源柜行锁内取号，后续客户或跨日交接复用该柜已保存的编号，事件重放不取新号。不同来源柜复用真实集装箱号时仍分别编号；`payload.orders` 每项按 `sourceInboundId` 独立落一条雪花 ID `ll_order`，并保存对应明细和初始状态历史。真实 `containerNo` 继续保留作实箱快照，`cabinetNo` 仅为柜次展示，不替代稳定来源柜身份。
 - `ONE_CLICK_DROPSHIP` 每个来源入仓单必须携带一个或多个不可变来源托盘快照；每托按 SKU 携带箱数、数量和箱唛。校验订单汇总一致、托盘号/SKU/箱唛唯一后，按托建立档案及 SKU 库存，并建立箱唛和流水。仓库实物托盘由 Warehouse API 分配，不得覆盖来源托盘快照。
 - 其他订单类型建立入仓单维度的尾程订单与冻结明细，并保留头程推荐托数；尾程入仓计划至少按推荐托数生成计划托盘，PDA 再把箱级事实绑定到海外仓实物托盘。
 - 整个事件消费在一个事务内完成；任意订单失败时不得留下部分订单。

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentplanning/AppointmentForecastClient.java

@@ -11,7 +11,7 @@ public interface AppointmentForecastClient {
     record Request(List<Long> containerBookingIds) { }
     record Fact(Long containerBookingId,Long factId,String providerCode,String sourceReference,
                 LocalDateTime observedAt,LocalDateTime estimatedAt,LocalDateTime actualAt) { }
-    record Forecast(Long containerBookingId,Fact latest,Fact previous,String timeBasis) { }
+    record Forecast(Long containerBookingId,Fact latest,Fact previous,String timeBasis,LocalDateTime portArrivalAt) { }
     @PostMapping("/internal/firstleg/appointment-forecasts/batch")
     ApiResponse<List<Forecast>> batch(@RequestHeader("X-Internal-Service-Token") String token,@RequestBody Request request);
 }

lastleg-service/src/main/java/com/baiyue/lastleg/calendar/WarehouseCalendarMapper.java

@@ -12,24 +12,31 @@ public interface WarehouseCalendarMapper {
     @Select("""
         <script>
         SELECT * FROM (
-          SELECT o.source_container_booking_id sourceContainerBookingId,MAX(o.container_no) containerNo,
+          SELECT o.source_container_booking_id sourceContainerBookingId,
+            MAX(NULLIF(JSON_UNQUOTE(JSON_EXTRACT(e.payload_json,'$.cabinetNo')),'null')) cabinetNo,
+            MAX(o.container_no) containerNo,
             CASE WHEN COUNT(DISTINCT o.overseas_warehouse_id)=1 THEN MAX(o.overseas_warehouse_name) END warehouseName,
             CASE WHEN COUNT(DISTINCT o.overseas_warehouse_id)=1 THEN MAX(o.overseas_warehouse_code) END warehouseCode,
             CASE WHEN COUNT(o.estimated_warehouse_at)=COUNT(*) AND COUNT(DISTINCT o.estimated_warehouse_at)=1
-              AND (MAX(o.arrival_time_version)>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))
+              AND MAX(o.arrival_time_version)>0
               THEN MAX(o.estimated_warehouse_at) END plannedAt,
             (SELECT MIN(s.receiving_at) FROM ll_receiving_container_session s
               WHERE s.source_container_booking_id=o.source_container_booking_id) actualAt,
             CASE WHEN COUNT(DISTINCT o.arrival_time_version)=1 THEN MAX(o.arrival_time_version) ELSE -1 END 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) planCount,
-            FALSE canEdit
-          FROM ll_order o WHERE o.source_container_booking_id IS NOT NULL
+            FALSE canEdit,
+            (SELECT CASE WHEN COUNT(p.planned_arrival_date)=COUNT(*) AND COUNT(DISTINCT p.planned_arrival_date)=1
+              THEN MAX(p.planned_arrival_date) END 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) plannedDate,
+            FALSE isDefault
+          FROM ll_order o LEFT JOIN ll_loading_event_inbox e ON e.event_id=o.source_event_id
+          WHERE o.source_container_booking_id IS NOT NULL
           GROUP BY o.source_container_booking_id
         ) c WHERE
           (c.plannedAt &gt;= #{from} AND c.plannedAt &lt; #{to})
+          OR (c.plannedDate &gt;= DATE(#{from}) AND c.plannedDate &lt; DATE(#{to}))
           <if test="ids != null and !ids.isEmpty()">
             OR c.sourceContainerBookingId IN
             <foreach collection="ids" item="id" open="(" separator="," close=")">#{id}</foreach>

lastleg-service/src/main/java/com/baiyue/lastleg/calendar/WarehouseCalendarModels.java

@@ -14,7 +14,7 @@ public final class WarehouseCalendarModels {
     private WarehouseCalendarModels() { }
     public record Query(@NotNull LocalDate from, @NotNull LocalDate to,
         @NotNull @Size(max = 2000) List<@NotBlank @Pattern(regexp = "[1-9][0-9]*") String> sourceContainerBookingIds) { }
-    public record Entry(String sourceContainerBookingId, String containerNo, String warehouseName,
+    public record Entry(String sourceContainerBookingId, String cabinetNo, String containerNo, String warehouseName,
         String warehouseCode, LocalDateTime plannedAt, LocalDateTime actualAt, int version,
-        long planCount, boolean canEdit) { }
+        long planCount, boolean canEdit, LocalDate plannedDate, boolean isDefault) { }
 }

lastleg-service/src/main/java/com/baiyue/lastleg/calendar/WarehouseCalendarService.java

@@ -10,8 +10,10 @@ import java.util.List;
 @Service
 public class WarehouseCalendarService {
     private final WarehouseCalendarRepository repository;
+    private final com.baiyue.lastleg.service.ContainerWarehouseArrivalService arrivals;
     /** 装配日历只读仓储查询。 */
-    public WarehouseCalendarService(WarehouseCalendarRepository repository) { this.repository = repository; }
+    public WarehouseCalendarService(WarehouseCalendarRepository repository,
+        com.baiyue.lastleg.service.ContainerWarehouseArrivalService arrivals) { this.repository = repository; this.arrivals=arrivals; }
     /** 明确权限、版本与计划冻结资格；不以默认计划改写真实到仓时间。 */
     public List<WarehouseCalendarModels.Entry> calendar(WarehouseCalendarModels.Query query, boolean canEdit) {
         if (query.from() == null || query.to() == null || !query.to().isAfter(query.from())
@@ -20,8 +22,16 @@ public class WarehouseCalendarService {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "日历范围须为1至42天，来源柜不能重复");
         var rows = repository.calendar(query);
         if (rows.size() > 2000) throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "到仓记录过多，请缩小日期范围");
-        return rows.stream().map(row -> new WarehouseCalendarModels.Entry(row.sourceContainerBookingId(), row.containerNo(),
-            row.warehouseName(), row.warehouseCode(), row.plannedAt(), row.actualAt(), row.version(), row.planCount(),
-            canEdit && row.version() >= 0 && row.planCount() == 0 && row.actualAt() == null)).toList();
+        var resolved=arrivals.resolve(rows.stream().map(WarehouseCalendarModels.Entry::sourceContainerBookingId).toList())
+            .stream().collect(java.util.stream.Collectors.toMap(
+                com.baiyue.lastleg.dto.ContainerArrivalTimeView::sourceContainerBookingId,java.util.function.Function.identity()));
+        return rows.stream().map(row -> {
+            var arrival=resolved.get(row.sourceContainerBookingId());
+            if(arrival==null) throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE,"来源柜到仓日期读取不完整");
+            return new WarehouseCalendarModels.Entry(row.sourceContainerBookingId(), row.cabinetNo(), row.containerNo(),
+                row.warehouseName(), row.warehouseCode(), row.plannedAt(), row.actualAt(), row.version(), row.planCount(),
+                canEdit && row.version() >= 0 && row.planCount() == 0 && row.actualAt() == null,
+                arrival.plannedDate(),arrival.isDefault());
+        }).toList();
     }
 }

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

@@ -30,7 +30,7 @@ public final class DispatchCommands {
 
     public record Update(Long recordVersion, String idempotencyKey, Vehicle vehicle, Driver driver,
                            Instant plannedDepartureAt, Instant estimatedArrivalAt,
-                           String remark, Boolean publishLooseboardDemand) {
+                           String remark, Boolean publishLooseboardDemand, Maintenance maintenance) {
         /** 缺版本与有效版本零必须区分。 */
         public Update { recordVersion = requireVersion(recordVersion); if (publishLooseboardDemand == null) throw new IllegalArgumentException("请明确是否发布散板需求"); }
     }

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

@@ -1,5 +1,7 @@
 package com.baiyue.lastleg.dispatch.port;
 
+import com.fasterxml.jackson.annotation.JsonFormat;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import java.math.BigDecimal;
 import java.time.Instant;
 import java.time.LocalDate;
@@ -42,7 +44,37 @@ public final class DispatchContracts {
     public record DriverSnapshot(ResourceMode mode, Long driverId, String name, String phone,
                                  DriverEvidence evidence) { }
 
-    public record Resources(VehicleSnapshot vehicle, DriverSnapshot driver) { }
+    /** 本趟可空维护资料，不替代正式预约或实际发车事实。 */
+    public record Maintenance(@JsonFormat(shape = JsonFormat.Shape.STRING)
+                              @JsonDeserialize(using = DispatchMaintenanceDateDeserializer.class)
+                              LocalDate plannedDeliveryDate, String deliveryMethod, String pickupMethod,
+                              String loadType, String fleetEmail, String vehicleType,
+                              String appointmentAccount, String appointmentNo) {
+        /** 空白统一为空；只约束已填写的选项及长度，不阻止空草稿保存。 */
+        public Maintenance {
+            deliveryMethod = option(deliveryMethod, "派送方式", "FBA自提", "客户自提", "卡派打托", "卡派地板", "快递", "外配");
+            pickupMethod = option(pickupMethod, "提卸方式", "一提一卸", "一提多卸");
+            loadType = option(loadType, "装载类型", "托盘", "地板", "混装");
+            vehicleType = option(vehicleType, "车辆类型", "厢式货车", "平板车", "集装箱卡车");
+            fleetEmail = limited(fleetEmail, "车队邮箱", 254);
+            appointmentAccount = limited(appointmentAccount, "预约账号", 128);
+            appointmentNo = limited(appointmentNo, "本趟预约号", 128);
+        }
+        /** 选项按正式文案保存，拒绝未知值而不猜测业务含义。 */
+        private static String option(String value, String label, String... allowed) {
+            String normalized = limited(value, label, 128);
+            if (normalized != null && !List.of(allowed).contains(normalized)) throw new IllegalArgumentException(label + "无效");
+            return normalized;
+        }
+        /** 统一文本空值及长度边界，不把补充资料写入备注或车牌。 */
+        private static String limited(String value, String label, int max) {
+            String normalized = value == null || value.isBlank() ? null : value.trim();
+            if (normalized != null && normalized.length() > max) throw new IllegalArgumentException(label + "最多" + max + "字符");
+            return normalized;
+        }
+    }
+
+    public record Resources(VehicleSnapshot vehicle, DriverSnapshot driver, Maintenance maintenance) { }
 
     public record Destination(String key, String type, String warehouseId, String warehouseCode,
                                String warehouseName, String address, String postalCode,

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

@@ -0,0 +1,29 @@
+package com.baiyue.lastleg.dispatch.port;
+
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.core.JsonToken;
+import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
+import java.io.IOException;
+import java.time.LocalDate;
+import java.time.format.DateTimeParseException;
+
+/** 本趟补充日期允许清空，但不能将时间串或不存在的日期截断、修正为有效日期。 */
+public final class DispatchMaintenanceDateDeserializer extends StdDeserializer<LocalDate> {
+    /** 仅绑定维护资料的可空日期，不改变其他业务日期解析规则。 */
+    public DispatchMaintenanceDateDeserializer() { super(LocalDate.class); }
+
+    /** 空白归空，其余只接受四位年、两位月日的严格ISO日期。 */
+    @Override
+    public LocalDate deserialize(JsonParser parser, DeserializationContext context) throws IOException {
+        if (!parser.hasToken(JsonToken.VALUE_STRING)) return (LocalDate) context.handleUnexpectedToken(LocalDate.class, parser);
+        String value = parser.getText().trim();
+        if (value.isEmpty()) return null;
+        try {
+            if (!value.matches("\\d{4}-\\d{2}-\\d{2}")) throw new DateTimeParseException("日期格式无效", value, 0);
+            return LocalDate.parse(value);
+        } catch (DateTimeParseException failure) {
+            return (LocalDate) context.handleWeirdStringValue(LocalDate.class, value, "计划派送日期须为有效的YYYY-MM-DD");
+        }
+    }
+}

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

@@ -36,7 +36,7 @@ public final class DispatchViews {
                             boolean pickingReconciled, boolean arranged,
                             Map<Action, Gate> actions) { }
 
-    public record VehicleInfo(VehicleSnapshot vehicle, DriverSnapshot driver) { }
+    public record VehicleInfo(VehicleSnapshot vehicle, DriverSnapshot driver, Maintenance maintenance) { }
 
     public record FbaAppointment(String batchKey, String batchNo, String appointmentNo,
                                   String destinationKey, String destinationWarehouseCode,

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

@@ -310,7 +310,7 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         row.setDispatchReviewJson(write(pending(0))); row.setLoadingReviewJson(write(pending(0)));
         var photos=request.driver()==null || request.driver().evidence()==null?List.<Long>of():request.driver().evidence().photoFileIds();
         if(!photos.isEmpty())verifyEvidence(id,com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER_PHOTO,photos);
-        Resources resources=resources(shell,photos); row.setResourcesJson(write(resources));
+        Resources resources=resources(shell,photos,null); row.setResourcesJson(write(resources));
         row.setVehiclePlate(resources.vehicle()==null ? null : resources.vehicle().plate());
         row.setPlannedDepartureAt(utc(request.plannedDepartureAt())); row.setEstimatedArrivalAt(utc(request.estimatedArrivalAt()));
         row.setItemCount(0); row.setPalletCount(0); row.setPackageCount(0); row.setPickedPackageCount(0); row.setShippedPackageCount(0);
@@ -373,13 +373,14 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         var replay=commands.replay(actor,number,identity);if(replay.isPresent())return replay.get();requireEditing(row,request.recordVersion());
         if(trim(request.reason())==null)throw bad("取消原因不能为空");
         if(repository.realPicked(row.getId())!=0 || repository.outbounds(row.getId()).stream().anyMatch(o->!"CANCELLED".equals(o.status())))throw conflict("本车已有真实执行或关联出库，不能取消");
-        var items=repository.cargo(row.getId());lockExecutionSources(row,items);appointments.lock(repository.batches(row.getId()),List.of());appointments.remove(row.getId(),items);sourceRules.releaseWholeRelabel(items);
+        // 撤销的是本车运输占用，不重新要求货物已实收或满足装车条件；真实执行仍由前面的零扫码及出库门禁保护。
+        var items=repository.cargo(row.getId());sourceRules.lockCancellationSources(row.getOverseasWarehouseId(),items);appointments.lock(repository.batches(row.getId()),List.of());appointments.remove(row.getId(),items);sourceRules.releaseWholeRelabel(items);
         releaseSources(row,actor,items,now());
         fleet.cancelDispatchShell(number,actor.operatorId(),request.reason());row.setStatus(Status.CANCELLED.name());invalidate(row,"排车已取消");
         return saveCommand(row,actor,identity,request.reason());
     }
 
-    /** 旧新资源身份一次锁齐，编辑关键依据后两级审核均失效，普通备注不篡改旧审核。 */
+    /** 旧新资源身份一次锁齐，资料和本趟照片随正式资源快照保存，原审核失效规则保留。 */
     @Transactional(isolation=Isolation.READ_COMMITTED)
     public CommandResult update(Actor actor,String number,DispatchCommands.Update request) {
         requirePlatform(actor);
@@ -391,8 +392,10 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         // 本趟司机照片随资源维护保存，逐个核对本车及照片类别。
         var photos=request.driver()==null || request.driver().evidence()==null?List.<Long>of():request.driver().evidence().photoFileIds();
         if(!photos.isEmpty())verifyEvidence(row.getId(),com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER_PHOTO,photos);
+        var vehiclePhotos=request.vehicle()==null?null:request.vehicle().evidenceFileIds();
+        if(vehiclePhotos!=null && !vehiclePhotos.isEmpty())verifyEvidence(row.getId(),com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.VEHICLE,vehiclePhotos);
         var actual=fleet.dispatchResources(number,fleetVehicle(request.vehicle()),fleetDriver(request.driver()));
-        row.setResourcesJson(write(resources(actual,photos)));row.setVehiclePlate(actual.vehicle()==null?null:actual.vehicle().plate());
+        row.setResourcesJson(write(resources(actual,photos,request.maintenance())));row.setVehiclePlate(actual.vehicle()==null?null:actual.vehicle().plate());
         row.setPlannedDepartureAt(utc(request.plannedDepartureAt()));row.setEstimatedArrivalAt(utc(request.estimatedArrivalAt()));row.setRemark(request.remark());
         row.setPublishLooseboardDemand(request.publishLooseboardDemand());
         if(!Objects.equals(before,basis(row)))invalidate(row,"车辆、司机或计划信息已修改");
@@ -675,12 +678,12 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         var capacity=v.capacity();if(capacity==null || capacity.palletSpaces()==null || capacity.palletSpaces()<=0 || capacity.maxLoadKg()==null || capacity.maxLoadKg().signum()<=0 || capacity.maxVolumeCbm()==null || capacity.maxVolumeCbm().signum()<=0)throw bad("请补齐车辆真实托位、载重及容积");
         var e=d.evidence();if(e==null || e.expectedTaskEndAt()==null || row.getPlannedDepartureAt()==null || !e.expectedTaskEndAt().isAfter(instant(row.getPlannedDepartureAt())) || !e.expectedTaskEndAt().isAfter(Instant.now()))throw bad("预计任务结束须晚于发车及当前时间");
         if(trim(e.licenseNo())==null || e.licenseExpiresOn()==null || e.licenseExpiresOn().isBefore(e.expectedTaskEndAt().atZone(ZoneOffset.UTC).toLocalDate()))throw bad("司机证照须覆盖预计任务结束日期");
-        if(v.mode()==ResourceMode.EXTERNAL)verifyEvidence(row.getId(),com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.VEHICLE,v.evidenceFileIds());
+        if(v.mode()==ResourceMode.EXTERNAL || v.evidenceFileIds()!=null && !v.evidenceFileIds().isEmpty())verifyEvidence(row.getId(),com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.VEHICLE,v.evidenceFileIds());
         if(d.mode()==ResourceMode.EXTERNAL)verifyEvidence(row.getId(),com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER,e.fileIds());
         if(!e.photoFileIds().isEmpty())verifyEvidence(row.getId(),com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER_PHOTO,e.photoFileIds());
         var actual=fleet.dispatchResources(row.getDispatchNo(),new FleetExecutionModels.DispatchVehicle(v.mode().name(),v.vehicleId(),v.plate(),v.carrierName(),capacity.palletSpaces(),capacity.maxLoadKg(),capacity.maxVolumeCbm(),v.evidenceFileIds()),
             new FleetExecutionModels.DispatchDriver(d.mode().name(),d.driverId(),d.name(),d.phone(),e.licenseNo(),e.licenseExpiresOn(),e.fileIds(),e.expectedTaskEndAt()));
-        if(!Objects.equals(hashes.source(r),hashes.source(resources(actual,e.photoFileIds()))))throw conflict("车辆或司机主档已变化，请重新保存并提交审核");
+        if(!Objects.equals(hashes.source(r),hashes.source(resources(actual,e.photoFileIds(),r.maintenance()))))throw conflict("车辆或司机主档已变化，请重新保存并提交审核");
     }
     /** 从客服提交到真实扫码共用预约及时间复验，保留预排但不放行未确认货物。 */
     void requireReviewAppointment(DispatchAggregate row) {
@@ -763,6 +766,7 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
     }
 
     /** 一次读取真实全部客户明细和单据，客户端不暴露整车入口。 */
+    /** 四页签读取同一资源快照，维护资料和本趟车辆照片不回退为主档或备注。 */
     @Transactional(readOnly=true,isolation=Isolation.REPEATABLE_READ)
     public DispatchViews.Detail detail(Actor actor, String number) {
         var row=required(actor,number,false); var cargo=repository.cargo(row.getId());
@@ -778,7 +782,7 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
             d.status(),d.packageCount(),d.palletCount())).toList();
         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()),
+            reviews(row),counts(row),reconciled(row),actions(actor,row),new DispatchViews.VehicleInfo(resources.vehicle(),resources.driver(),resources.maintenance()),
             new DispatchViews.DispatchInfo(row.getRoute(),instant(row.getPlannedDepartureAt()),instant(row.getDepartedAt()),instant(row.getEstimatedArrivalAt()),appointments,batchRefs,exceptionRecords(row)),
             documents,orderDetails(cargo),Boolean.TRUE.equals(row.getPublishLooseboardDemand()));
     }
@@ -1000,12 +1004,12 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         return List.copyOf(result);
     }
 
-    /** 合并Fleet权威资源与本趟司机照片，照片不写入司机主档。 */
-    private static Resources resources(FleetExecutionModels.DispatchShell shell,List<Long> photos) {
+    /** 合并Fleet权威资源、本趟照片和维护资料，不写入车辆或司机主档。 */
+    private static Resources resources(FleetExecutionModels.DispatchShell shell,List<Long> photos,Maintenance maintenance) {
         var v=shell.vehicle(); var d=shell.driver();
         return new Resources(v==null?null:new VehicleSnapshot(ResourceMode.valueOf(v.mode()),v.vehicleId(),v.plate(),v.carrierName(),shell.vehicleStatus(),
             new Capacity(v.palletSpaces(),v.maxLoadKg(),v.maxVolumeCbm()),v.evidenceFileIds()),d==null?null:new DriverSnapshot(ResourceMode.valueOf(d.mode()),d.driverId(),d.name(),d.phone(),
-            new DriverEvidence(d.licenseNo(),d.licenseExpiresOn(),d.evidenceFileIds(),d.expectedTaskEndAt(),photos)));
+            new DriverEvidence(d.licenseNo(),d.licenseExpiresOn(),d.evidenceFileIds(),d.expectedTaskEndAt(),photos)),maintenance);
     }
 
     /** 主档选择不接受请求覆盖其车牌和容量。 */

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

@@ -382,6 +382,18 @@ public class DispatchService {
         });
     }
 
+    /** 取消只锁本车待释放的申请与原实托，不以当前库存、实收或组托完整性作为撤销安排的资格。 */
+    @Transactional(propagation=org.springframework.transaction.annotation.Propagation.MANDATORY)
+    public void lockCancellationSources(String warehouse,List<DispatchItem> items) {
+        if(warehouse==null || warehouse.isBlank())throw new IllegalArgumentException("取消排车仍须明确起运仓库");
+        var applications=items.stream().filter(i->"RELABEL_ORDER".equals(i.getSourceBusinessType()))
+            .map(DispatchItem::getSourceBusinessNo).collect(Collectors.toCollection(TreeSet::new));
+        // 先锁实际需要恢复预占的换标申请，再取得共同实托串行点；计划来源不伪造实托或查询库存。
+        if(!applications.isEmpty())lockRelabelApplications(applications);
+        var pallets=items.stream().map(DispatchItem::getWarehousePalletId).filter(Objects::nonNull).distinct().sorted().toList();
+        if(!pallets.isEmpty())palletSerial.lock(pallets);
+    }
+
     /** 执行沿用全车申请/订单→共同实托串行顺序；库存变化不重新解释原冻结贡献。 */
     @Transactional(propagation=org.springframework.transaction.annotation.Propagation.MANDATORY)
     public RelabelDispatchSourcePort.Snapshot lockExecutionSources(String warehouse,List<DispatchItem> items) {

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/transport/TransportReviewPhotos.java

@@ -25,7 +25,7 @@ public class TransportReviewPhotos {
     }
     /** 读取已保存资源；空排车还没有照片。 */
     public Resources resources(DispatchAggregate row) {
-        if(row.getResourcesJson()==null)return new Resources(null,null);
+        if(row.getResourcesJson()==null)return new Resources(null,null,null);
         try{return json.readValue(row.getResourcesJson(),Resources.class);}
         catch(Exception e){throw new IllegalStateException("取货照片快照读取失败",e);}
     }

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/transport/TransportTaskProjection.java

@@ -109,21 +109,21 @@ public class TransportTaskProjection implements com.baiyue.lastleg.fleet.pickup.
         history.setOperationType(action);history.setFromStatus(from);history.setToStatus(target);history.setOperatorId(operator);history.setIdempotencyKey(key);
         history.setRemark(reason);history.setCreatedAt(order.getUpdatedAt());trucks.insertHistory(history);
     }
-    /** 主单仅展示真实主档分配，不伪造临时证照或仓库装载事实。 */
+    /** 主单展示真实主档分配，并保留本趟维护资料及同一资源的照片。 */
     private void resources(DispatchAggregate row,FleetTripEntity trip) {
         var old=readResources(row);
         row.setVehiclePlate(trip.getVehiclePlate());row.setResourcesJson(write(new Resources(
             trip.getVehicleId()==null?null:new VehicleSnapshot(ResourceMode.MASTER,trip.getVehicleId(),trip.getVehiclePlate(),null,null,new Capacity(trip.getMaxPalletSpaces(),trip.getMaxLoadKg(),trip.getMaxVolumeCbm()),
                 old.vehicle()!=null && Objects.equals(old.vehicle().vehicleId(),trip.getVehicleId())?old.vehicle().evidenceFileIds():List.of()),
             trip.getDriverId()==null?null:new DriverSnapshot(ResourceMode.MASTER,trip.getDriverId(),trip.getDriverName(),trip.getDriverPhone(),
-                old.driver()!=null && Objects.equals(old.driver().driverId(),trip.getDriverId())?old.driver().evidence():null))));
+                old.driver()!=null && Objects.equals(old.driver().driverId(),trip.getDriverId())?old.driver().evidence():null),old.maintenance())));
     }
-    /** 照片变更单独纳入主单版本和审核依据，资源分配失败时由外层事务一起回滚。 */
+    /** 照片变更纳入主单版本和审核依据，保留原维护资料，失败由外层事务一起回滚。 */
     public void savePhotos(String number,String operator,List<Long> vehiclePhotos,DriverEvidence driverPhotos) {
         var row=roots.lock(number);var old=readResources(row);var v=old.vehicle();var d=old.driver();
         if(v==null || d==null)throw new IllegalStateException("请先完成车辆司机分配");
         var next=new Resources(new VehicleSnapshot(v.mode(),v.vehicleId(),v.plate(),v.carrierName(),v.vehicleStatus(),v.capacity(),vehiclePhotos),
-            new DriverSnapshot(d.mode(),d.driverId(),d.name(),d.phone(),driverPhotos));
+            new DriverSnapshot(d.mode(),d.driverId(),d.name(),d.phone(),driverPhotos),old.maintenance());
         if(next.equals(old))return;
         long version=row.getRecordVersion();row.setResourcesJson(write(next));row.setRecordVersion(version+1);
         row.setUpdatedAt(LocalDateTime.now(ZoneOffset.UTC));row.setReviewState("DRAFT");row.setReviewBasisHash(null);row.setStage("BEFORE_LOADING");
@@ -134,7 +134,7 @@ public class TransportTaskProjection implements com.baiyue.lastleg.fleet.pickup.
     }
     /** 状态投影只保留同一资源的已保存照片，不能在运输流转中清空审核证据。 */
     private Resources readResources(DispatchAggregate row) {
-        if(row.getResourcesJson()==null)return new Resources(null,null);
+        if(row.getResourcesJson()==null)return new Resources(null,null,null);
         try{return json.readValue(row.getResourcesJson(),Resources.class);}
         catch(Exception e){throw new IllegalStateException("运输资源照片读取失败",e);}
     }

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

@@ -8,5 +8,7 @@ public record ContainerArrivalTimeView(
     LocalDateTime estimatedWarehouseArrivalAt,
     LocalDateTime actualWarehouseArrivalAt,
     int version,
-    long planCount
+    long planCount,
+    java.time.LocalDate plannedDate,
+    boolean isDefault
 ) { }

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/trip/FleetTripService.java

@@ -301,7 +301,7 @@ public class FleetTripService {
         return new FleetExecutionModels.DispatchShellLock(trip.getId(),trip.getTripNo(),trip.getWarehouseId().toString());
     }
 
-    /** 已持父级全部身份锁后，复验资源实际资格；快照不信任请求中的主档名称和容量。 */
+    /** 复验主档资格与名称容量；本趟已由排车核验归属的车辆照片保持独立，不被主档重建清空。 */
     @Transactional(propagation = org.springframework.transaction.annotation.Propagation.MANDATORY)
     public FleetExecutionModels.DispatchShell dispatchResources(String dispatchNo,FleetExecutionModels.DispatchVehicle vehicle,
         FleetExecutionModels.DispatchDriver driver) {
@@ -315,7 +315,7 @@ public class FleetTripService {
             var assignment=repository.resource("VEHICLE",actual.id());
             if(assignment!=null && assignment.tripId()!=trip.getId())throw conflict("车辆已被其他车次占用");
             vehicle=new FleetExecutionModels.DispatchVehicle("MASTER",actual.id(),actual.plateNumber(),actual.driverOrDispatchCompany(),
-                actual.maxPalletSpaces(),actual.maxLoadKg(),actual.maxVolumeCbm(),List.of());vehicleStatus=actual.status();
+                actual.maxPalletSpaces(),actual.maxLoadKg(),actual.maxVolumeCbm(),vehicle.evidenceFileIds()==null?List.of():List.copyOf(vehicle.evidenceFileIds()));vehicleStatus=actual.status();
         } else if(vehicle!=null && (!"EXTERNAL".equals(vehicle.mode()) || vehicle.vehicleId()!=null)) throw bad("临时车辆不得关联车辆档案");
         if(driver!=null && "MASTER".equals(driver.mode())) {
             if(driver.driverId()==null)throw bad("请选择司机档案");

lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/mapper/InboundPlanOrderMapper.java

@@ -79,11 +79,6 @@ public interface InboundPlanOrderMapper {
     String findSourceContainerBookingId(@Param("customerId") String customerId,
                                         @Param("orderId") Long orderId);
 
-    @Select("SELECT estimated_warehouse_at FROM ll_order " +
-        "WHERE source_container_booking_id=#{sourceContainerBookingId} ORDER BY customer_id,id")
-    List<LocalDateTime> containerEstimatedWarehouseTimes(
-        @Param("sourceContainerBookingId") String sourceContainerBookingId);
-
     @Select("SELECT order_type FROM ll_order WHERE customer_id=#{customerId} AND id=#{orderId} LIMIT 1")
     String findOrderType(@Param("customerId") String customerId,
                          @Param("orderId") Long orderId);

lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/service/InboundPlanService.java

@@ -69,6 +69,7 @@ public class InboundPlanService {
     @Resource private LastlegOrderCommandRecordMapper commandMapper;
     @Resource private LastlegSourcePalletMapper sourcePalletMapper;
     @Resource private ObjectMapper objectMapper;
+    @Resource private com.baiyue.lastleg.service.ContainerWarehouseArrivalService warehouseArrival;
 
     public List<String> sourcePalletNos(String customerId, long orderId, String orderType) {
         return "ONE_CLICK_DROPSHIP".equals(orderType)
@@ -775,20 +776,13 @@ public class InboundPlanService {
         }
     }
 
+    /** 计划日期使用与清关和预约日历相同的权威解析，不以约仓时间代替。 */
     private LocalDate requiredContainerPlannedArrivalDate(String sourceContainerBookingId) {
         String bookingId = trimToNull(sourceContainerBookingId);
         if (bookingId == null) {
             throw new ResponseStatusException(HttpStatus.CONFLICT, "尾程订单未绑定来源柜，无法取得预计到仓时间");
         }
-        List<LocalDateTime> values = orderMapper.containerEstimatedWarehouseTimes(bookingId);
-        if (values == null || values.isEmpty() || values.stream().anyMatch(Objects::isNull)) {
-            throw new ResponseStatusException(HttpStatus.CONFLICT, "来源柜预计到仓时间缺失，请先补齐柜级时间");
-        }
-        LocalDateTime expected = values.get(0);
-        if (values.stream().anyMatch(value -> !Objects.equals(expected, value))) {
-            throw new ResponseStatusException(HttpStatus.CONFLICT, "来源柜预计到仓时间不一致，请先修正柜级时间");
-        }
-        return expected.toLocalDate();
+        return warehouseArrival.requiredDate(bookingId);
     }
 
     private void requirePlanContainer(InboundPlan plan, String containerNo) {

lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/work/FbaAppointmentExecutionAdapter.java

@@ -39,7 +39,8 @@ public class FbaAppointmentExecutionAdapter implements FbaAppointmentExecutionPo
         var members=members(input);if(members.isEmpty()) throw bad("请选择需要重新预约的客户");
         var before=read(batches(members));var selected=selected(before,members);
         var tripNos=tripNos(selected);var numbers=dispatchNos(selected);
-        amendments.lockExistingAppointmentDispatches(new Actor(operator,ActorMode.PLATFORM,null),numbers);
+        // 尚未排车的客户仍需核对完整执行版本，但没有原排车资源需要加锁。
+        if(!numbers.isEmpty()) amendments.lockExistingAppointmentDispatches(new Actor(operator,ActorMode.PLATFORM,null),numbers);
         for(var number:numbers) {
             dispatches.completion(number,true);
             dispatches.lockForPlanning(number);

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

@@ -210,19 +210,26 @@ 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("SELECT DISTINCT order_no FROM ll_order WHERE source_container_booking_id=#{bookingId} " +
+        "AND source_region='FIRSTLEG' ORDER BY order_no")
+    List<String> containerOrderNumbers(@Param("bookingId") String bookingId);
+
+    /** 人工时间与计划冻结日期分别返回；默认日期由共用业务解析器读取权威到港后生成。 */
     @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)) " +
+        "AND MAX(o.arrival_time_version)&gt;0 " +
         "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," +
         "(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 " +
+        "WHERE po.source_container_booking_id=o.source_container_booking_id) AS planCount," +
+        "(SELECT CASE WHEN COUNT(p.planned_arrival_date)=COUNT(*) AND COUNT(DISTINCT p.planned_arrival_date)=1 " +
+        "THEN MAX(p.planned_arrival_date) END 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 plannedDate,FALSE AS isDefault " +
         "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/java/com/baiyue/lastleg/repository/ContainerWarehouseArrivalRepository.java

@@ -0,0 +1,16 @@
+package com.baiyue.lastleg.repository;
+
+import com.baiyue.lastleg.dto.ContainerArrivalTimeView;
+import com.baiyue.lastleg.mapper.LastlegOrderMapper;
+import org.springframework.stereotype.Repository;
+import java.util.List;
+
+/** 柜级人工到仓与已有入库计划日期的唯一数据库读取入口。 */
+@Repository
+public class ContainerWarehouseArrivalRepository {
+    private final LastlegOrderMapper mapper;
+    /** 复用本库柜级事实查询。 */
+    public ContainerWarehouseArrivalRepository(LastlegOrderMapper mapper) { this.mapper=mapper; }
+    /** 保留同柜版本及计划数量，不把缺失时间转换成零点。 */
+    public List<ContainerArrivalTimeView> find(List<String> ids) { return mapper.findContainerArrivalTimes(ids); }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/repository/LastlegOrderNumberRepository.java

@@ -0,0 +1,21 @@
+package com.baiyue.lastleg.repository;
+
+import com.baiyue.lastleg.mapper.LastlegOrderMapper;
+import org.springframework.stereotype.Repository;
+import java.util.List;
+
+/** 读取来源柜已经分配的业务尾程号，不按客户拆分柜级身份。 */
+@Repository
+public class LastlegOrderNumberRepository {
+    private final LastlegOrderMapper mapper;
+
+    /** 复用所属服务订单 Mapper。 */
+    public LastlegOrderNumberRepository(LastlegOrderMapper mapper) { this.mapper = mapper; }
+
+    /** 调用方已持有来源柜门禁行锁，同柜的后续客户事件沿用首个尾程号。 */
+    public String findContainerOrderNo(String bookingId) {
+        List<String> values = mapper.containerOrderNumbers(bookingId);
+        if (values.size() > 1) throw new IllegalStateException("同一来源柜存在多个尾程业务编号");
+        return values.isEmpty() ? null : values.get(0);
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/service/ContainerWarehouseArrivalService.java

@@ -0,0 +1,67 @@
+package com.baiyue.lastleg.service;
+
+import com.baiyue.lastleg.appointmentplanning.AppointmentForecastClient;
+import com.baiyue.lastleg.dto.ContainerArrivalTimeView;
+import com.baiyue.lastleg.repository.ContainerWarehouseArrivalRepository;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.web.server.ResponseStatusException;
+import java.time.LocalDate;
+import java.util.List;
+import java.util.HashMap;
+import java.util.Map;
+
+/** 清关列表、预约日历与入库计划共用的到仓日期解析。 */
+@Service
+public class ContainerWarehouseArrivalService {
+    private final ContainerWarehouseArrivalRepository repository;
+    private final AppointmentForecastClient forecasts;
+    private final String token;
+
+    /** 到港事实只从 Firstleg 权威来源读取，人工与计划日期只访问本库。 */
+    public ContainerWarehouseArrivalService(ContainerWarehouseArrivalRepository repository,
+        AppointmentForecastClient forecasts,@Value("${baiyue.security.internal-service-token:}") String token) {
+        this.repository=repository; this.forecasts=forecasts; this.token=token;
+    }
+
+    /** 人工时间及计划冻结日期优先，其余按最新到港当地日期加两个自然日。 */
+    public List<ContainerArrivalTimeView> resolve(List<String> ids) {
+        if(ids.isEmpty()) return List.of();
+        var rows=repository.find(ids);
+        var pending=rows.stream().filter(row->row.version()==0 && row.planCount()==0
+            && row.estimatedWarehouseArrivalAt()==null).map(row->Long.valueOf(row.sourceContainerBookingId())).toList();
+        Map<Long,LocalDate> defaults=new HashMap<>();
+        for(int start=0;start<pending.size();start+=200) {
+            var batch=pending.subList(start,Math.min(start+200,pending.size()));
+            var response=forecasts.batch(token,new AppointmentForecastClient.Request(batch));
+            if(response==null || !response.successful() || response.data()==null || response.data().size()!=batch.size())
+                throw unavailable();
+            var seen=new java.util.HashSet<Long>();
+            for(var fact:response.data()) {
+                if(fact==null || !batch.contains(fact.containerBookingId()) || !seen.add(fact.containerBookingId())) throw unavailable();
+                if(fact.portArrivalAt()!=null) defaults.put(fact.containerBookingId(),fact.portArrivalAt().toLocalDate().plusDays(2));
+            }
+        }
+        return rows.stream().map(row->{
+            boolean automatic=row.version()==0 && row.planCount()==0 && row.estimatedWarehouseArrivalAt()==null;
+            LocalDate date=row.estimatedWarehouseArrivalAt()!=null?row.estimatedWarehouseArrivalAt().toLocalDate()
+                :automatic?defaults.get(Long.valueOf(row.sourceContainerBookingId())):row.plannedDate();
+            return new ContainerArrivalTimeView(row.sourceContainerBookingId(),row.estimatedWarehouseArrivalAt(),
+                row.actualWarehouseArrivalAt(),row.version(),row.planCount(),date,automatic && date!=null);
+        }).toList();
+    }
+
+    /** 生成计划沿用同一解析结果，缺失或不一致时阻断，不改写来源事实。 */
+    public LocalDate requiredDate(String id) {
+        var rows=resolve(List.of(id));
+        if(rows.size()!=1 || rows.get(0).version()<0 || rows.get(0).plannedDate()==null)
+            throw new ResponseStatusException(HttpStatus.CONFLICT,"来源柜预计到仓日期缺失或不一致，请先核对柜级时间");
+        return rows.get(0).plannedDate();
+    }
+
+    /** 来源失败必须明确提示，不能用本地旧快照伪造默认日期。 */
+    private ResponseStatusException unavailable() {
+        return new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE,"来源柜到港日期暂不可读取，请稍后重试");
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/service/LastlegDocumentNumberGenerator.java

@@ -10,7 +10,7 @@ import java.util.Set;
 /** 按北京时间生成两至四位前缀、八位日期和四位日流水。 */
 @Component
 public class LastlegDocumentNumberGenerator {
-    private static final Set<String> PREFIXES = Set.of("IP", "CK", "DFCK", "HBCK", "THCK", "DL", "EX", "CD", "TB", "ZY", "TH", "THHB", "RR", "RB", "HX", "YY", "TR", "LB", "CG", "PR", "PJ", "PF", "PN", "PX", "PG", "CT", "FB", "FO", "VR");
+    private static final Set<String> PREFIXES = Set.of("WC", "IP", "CK", "DFCK", "HBCK", "THCK", "DL", "EX", "CD", "TB", "ZY", "TH", "THHB", "RR", "RB", "HX", "YY", "TR", "LB", "CG", "PR", "PJ", "PF", "PN", "PX", "PG", "CT", "FB", "FO", "VR");
     private final DocumentSequenceRepository sequences;
     private final Clock clock;
 

lastleg-service/src/main/java/com/baiyue/lastleg/service/LastlegOrderNoGenerator.java

@@ -1,14 +1,9 @@
 package com.baiyue.lastleg.service;
 
 import org.springframework.stereotype.Component;
-import java.nio.charset.StandardCharsets;
-import java.security.MessageDigest;
-import java.security.NoSuchAlgorithmException;
-import java.time.LocalDate;
-import java.time.format.DateTimeFormatter;
 import java.util.Locale;
 
-/** 海外单据类型映射；头程来源尾程号与实物箱码保持本次确认的范围边界。 */
+/** 海外单据类型映射；业务单号统一使用本服务日流水。 */
 @Component
 public class LastlegOrderNoGenerator {
     private final LastlegDocumentNumberGenerator documents;
@@ -21,6 +16,7 @@ public class LastlegOrderNoGenerator {
     /** 明确业务类型对应的前缀，未知类型不再截断名称或使用内部 ID 回退。 */
     public String next(String businessType) {
         String prefix = switch (businessType) {
+            case "LASTLEG" -> "WC";
             case "ONE_CLICK_DROPSHIP" -> "DFCK";
             case "OUTBOUND" -> "CK";
             case "RELABEL_OUTBOUND" -> "HBCK";
@@ -45,16 +41,4 @@ public class LastlegOrderNoGenerator {
         return "BX-" + Long.toString(id, 36).toUpperCase(Locale.ROOT);
     }
 
-    /** 独立尾程编号尚未确认，头程装柜来源继续使用原有分组编号。 */
-    public String forContainerNo(String containerNo) {
-        if (containerNo == null || containerNo.isBlank()) throw new IllegalArgumentException("containerNo is required");
-        try {
-            byte[] digest = MessageDigest.getInstance("SHA-256").digest(containerNo.trim().getBytes(StandardCharsets.UTF_8));
-            long suffix = java.nio.ByteBuffer.wrap(digest, 0, 8).getLong();
-            return "FL-WH-" + LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE) + "-"
-                + String.format(Locale.ROOT, "%06d", Math.floorMod(suffix, 1_000_000));
-        } catch (NoSuchAlgorithmException exception) {
-            throw new IllegalStateException("SHA-256 is unavailable", exception);
-        }
-    }
 }

lastleg-service/src/main/java/com/baiyue/lastleg/service/LastlegOrderService.java

@@ -85,6 +85,7 @@ public class LastlegOrderService {
     @Resource private InventoryCommandService inventory;
     @Resource private ReceivingWarehouseOperationMapper receivingWarehouseOperations;
     @Resource private ContainerArrivalTimeOperationMapper containerArrivalTimeOperations;
+    @Resource private ContainerWarehouseArrivalService warehouseArrival;
     @Resource private WarehouseResourceGateway warehouseResourceGateway;
     @Resource private ContainerShippingGateMapper containerShippingGates;
     @Resource private ReturnOrderReferenceResolver returnOrderReferences;
@@ -202,6 +203,7 @@ public class LastlegOrderService {
             orderMapper.findContainerProgressItems(bookingId));
     }
 
+    /** 清关列表读取统一解析的柜级日期，默认推算不写入订单。 */
     @Transactional(readOnly = true)
     public List<ContainerArrivalTimeView> containerArrivalTimes(
         LastlegOrderRequests.ContainerArrivalTimeQuery request) {
@@ -210,7 +212,7 @@ public class LastlegOrderService {
         if (bookingIds.size() != request.sourceContainerBookingIds().size()) {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "来源柜预订ID不能重复");
         }
-        return orderMapper.findContainerArrivalTimes(List.copyOf(bookingIds));
+        return warehouseArrival.resolve(List.copyOf(bookingIds));
     }
 
     @Transactional
@@ -254,8 +256,9 @@ public class LastlegOrderService {
         return requireContainerArrivalTime(bookingId);
     }
 
+    /** 保存后沿同一读取入口返回人工日期、版本和计划冻结事实。 */
     private ContainerArrivalTimeView requireContainerArrivalTime(String bookingId) {
-        List<ContainerArrivalTimeView> values = orderMapper.findContainerArrivalTimes(List.of(bookingId));
+        List<ContainerArrivalTimeView> values = warehouseArrival.resolve(List.of(bookingId));
         if (values.size() != 1) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "来源柜不存在");
         if (values.get(0).version() < 0) {
             throw new ResponseStatusException(HttpStatus.CONFLICT, "柜内预计到仓时间版本不一致");

lastleg-service/src/main/java/com/baiyue/lastleg/service/LoadingCompletedConsumer.java

@@ -44,12 +44,14 @@ public class LoadingCompletedConsumer {
     @Resource private InboundPlanCartonMapper cartonMapper;
     @Resource private ObjectMapper objectMapper;
     @Resource private LastlegOrderNoGenerator orderNoGenerator;
+    @Resource private com.baiyue.lastleg.repository.LastlegOrderNumberRepository orderNumbers;
     @Resource private DropshipOrderService dropshipOrders;
     @Resource private InventoryCommandService inventory;
     @Resource private ContainerShippingGateMapper shippingGates;
     @Resource private LastlegSourcePalletMapper sourcePallets;
     @Resource private ContainerLoadingEvidenceMapper loadingEvidence;
 
+    /** 校验交接身份并在柜级锁内为各客户的冻结入仓单建立同柜尾程记录。 */
     @Transactional(isolation = Isolation.READ_COMMITTED)
     public DeliveryAck consume(EventEnvelope envelope) {
         envelope.requireValid();
@@ -94,7 +96,9 @@ public class LoadingCompletedConsumer {
         // Seeding the shipping version from the loading-plan version makes a valid first node
         // (aggregateVersion=0) look stale whenever the loading plan has a higher version.
         JsonNode rawOrders = envelope.payload().path("orders");
-        String orderNo = orderNoGenerator.forContainerNo(payload.containerNo());
+        // 来源柜行锁覆盖跨客户交接事件，首票取号，后续票沿用同柜已落库编号。
+        String orderNo = orderNumbers.findContainerOrderNo(sourceContainerBookingId);
+        if (orderNo == null) orderNo = orderNoGenerator.next("LASTLEG");
         for (int index = 0; index < payload.orders().size(); index++) {
             var source = payload.orders().get(index);
             JsonNode rawSource = rawOrders.isArray() && index < rawOrders.size() ? rawOrders.get(index) : objectMapper.createObjectNode();

lastleg-service/src/main/resources/openapi/appointment-calendar-warehouse-v1.yaml

@@ -8,8 +8,8 @@ paths:
       description: >-
         仅平台，同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
         返回所选来源柜，以及查询区间内已人工维护或已有入库计划的到仓记录，支持跨月人工改期。
-        同柜多个客户合并一条。plannedAt只有整柜时间一致且人工维护版本大于0或已经建计划时才有值。
-        未人工维护、未建计划的日历默认日期由到港来源加2个自然日；此只读接口不写入库计划、不补造时刻。
+        同柜多个客户合并一条。plannedAt只有整柜时间一致且人工维护版本大于0时才有值；仅日期的冻结计划通过plannedDate返回。
+        plannedDate/isDefault由与清关提柜和入库计划共用的服务端解析器返回，默认按权威到港当地日期加2个自然日；此只读接口不写入库计划、不补造时刻。
         actualAt只读PDA首次收货时间，不替换计划日期。
         具备原尾程订单编辑权限、版本一致、无入库计划且未实际到仓时canEdit=true。
         保存复用overseas-business-v1的整柜expected-arrival入口和原版本、幂等键、冻结门禁。
@@ -41,10 +41,13 @@ paths:
                       type: object
                       properties:
                         sourceContainerBookingId: {type: string}
+                        cabinetNo: {type: string, nullable: true, description: 来源交接冻结的柜次号，作为日历主标识}
                         containerNo: {type: string, nullable: true}
                         warehouseName: {type: string, nullable: true}
                         warehouseCode: {type: string, nullable: true}
                         plannedAt: {type: string, format: date-time, nullable: true}
+                        plannedDate: {type: string, format: date, nullable: true, description: 人工日期、已生成计划冻结日期或权威默认日期}
+                        isDefault: {type: boolean, description: 仅当前未维护未建计划且有默认日期时为true}
                         actualAt: {type: string, format: date-time, nullable: true}
                         version: {type: integer, minimum: -1}
                         planCount: {type: integer, minimum: 0}

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

@@ -3582,7 +3582,9 @@ components:
       required: [sourceContainerBookingId, version, planCount]
       properties:
         sourceContainerBookingId: { type: string }
-        estimatedWarehouseArrivalAt: { type: string, format: date-time, nullable: true, description: 人工维护或入库计划冻结的整柜时间；未维护未建计划时为空，由页面按到港当地日期加两个自然日展示默认日期 }
+        estimatedWarehouseArrivalAt: { type: string, format: date-time, nullable: true, description: 人工维护的整柜时间；默认日期及只有日期的冻结计划不补造时间 }
+        plannedDate: { type: string, format: date, nullable: true, description: 与日历和入库计划共用的服务端日期，人工或冻结日期优先，否则按权威到港当地日期加两个自然日 }
+        isDefault: { type: boolean, description: 未人工维护未建计划时使用权威到港推算日期 }
         actualWarehouseArrivalAt: { type: string, format: date-time, nullable: true, description: 海外 PDA 首次开始收货时间 }
         version: { type: integer, minimum: -1, description: -1表示柜内时间版本不一致 }
         planCount: { type: integer, format: int64, minimum: 0, description: 整柜已有入库计划数量；非零时禁止默认推算及改期 }
@@ -4022,6 +4024,11 @@ components:
         remark:
           type: string
           nullable: true
+        maintenance:
+          allOf:
+          - $ref: '#/components/schemas/DispatchMaintenance'
+          nullable: true
+          description: 本趟可空补充资料，八字段均可空；空白字符串规范为null，不替代正式FBA预约或实际发车时间。
       required:
       - publishLooseboardDemand
       - recordVersion
@@ -4558,7 +4565,7 @@ components:
           items: { $ref: '#/components/schemas/LastlegOrderManualNode' }
     ManualInboundPlanRequest:
       type: object
-      description: 单票人工计划只能使用所属柜已冻结的接柜仓；接柜仓变更必须通过柜级接口完成。预计到仓日期由服务端读取来源柜冻结的 estimatedWarehouseArrivalAt，同柜所有计划保持一致，不接受人工提交。
+      description: 单票人工计划只能使用所属柜已冻结的接柜仓；接柜仓变更必须通过柜级接口完成。预计到仓日期由共用服务端解析器返回 plannedDate：人工时间或已有计划冻结日期优先，其余按 Firstleg 权威到港当地日期加两个自然日；同柜所有计划保持一致，不接受人工提交，不补造默认时间。
       required: [customerId, orderId, expectedOrderVersion, palletCount, palletType, assigned, mergeRequired, urgent]
       properties:
         customerId: { type: string, pattern: '^[1-9][0-9]*$' }
@@ -5390,6 +5397,43 @@ components:
       - name
       - phone
       - evidence
+    DispatchMaintenance:
+      type: object
+      x-java-record: DispatchContracts.Maintenance
+      description: 保存于排车resourcesJson.maintenance的唯一正式资料结构，不新增费用金额或审核门禁。
+      properties:
+        plannedDeliveryDate:
+          type: string
+          format: date
+          nullable: true
+        deliveryMethod:
+          type: string
+          enum: [FBA自提, 客户自提, 卡派打托, 卡派地板, 快递, 外配]
+          nullable: true
+        pickupMethod:
+          type: string
+          enum: [一提一卸, 一提多卸]
+          nullable: true
+        loadType:
+          type: string
+          enum: [托盘, 地板, 混装]
+          nullable: true
+        fleetEmail:
+          type: string
+          maxLength: 254
+          nullable: true
+        vehicleType:
+          type: string
+          enum: [厢式货车, 平板车, 集装箱卡车]
+          nullable: true
+        appointmentAccount:
+          type: string
+          maxLength: 128
+          nullable: true
+        appointmentNo:
+          type: string
+          maxLength: 128
+          nullable: true
     DispatchResources:
       type: object
       x-java-record: DispatchContracts.Resources
@@ -5402,6 +5446,11 @@ components:
           allOf:
           - $ref: '#/components/schemas/DispatchDriverSnapshot'
           nullable: true
+        maintenance:
+          allOf:
+          - $ref: '#/components/schemas/DispatchMaintenance'
+          nullable: true
+          description: 本趟可空补充资料，八字段均可空；空白字符串规范为null，不替代正式FBA预约或实际发车时间。
       required:
       - vehicle
       - driver
@@ -6356,6 +6405,11 @@ components:
           allOf:
           - $ref: '#/components/schemas/DispatchDriverSnapshot'
           nullable: true
+        maintenance:
+          allOf:
+          - $ref: '#/components/schemas/DispatchMaintenance'
+          nullable: true
+          description: 本趟可空补充资料，八字段均可空；空白字符串规范为null，不替代正式FBA预约或实际发车时间。
       required:
       - vehicle
       - driver

lastleg-service/src/test/java/com/baiyue/lastleg/appointmentplanning/AppointmentImpactPersistenceTest.java

@@ -26,7 +26,7 @@ class AppointmentImpactPersistenceTest {
         return new AppointmentForecastClient.Fact(1L,revision,"CARRIER","REF",LocalDateTime.of(2026,10,10,12,0).plusMinutes(revision),LocalDateTime.of(2026,10,day,9,0),null);
     }
     static void observe(AnnotationConfigApplicationContext c,long revision,int day) {
-        when(c.getBean(AppointmentForecastClient.class).batch(anyString(),any())).thenReturn(ApiResponse.success(List.of(new AppointmentForecastClient.Forecast(1L,fact(revision,day),fact(1,15),"SOURCE_LOCAL_UNSPECIFIED"))));
+        when(c.getBean(AppointmentForecastClient.class).batch(anyString(),any())).thenReturn(ApiResponse.success(List.of(new AppointmentForecastClient.Forecast(1L,fact(revision,day),fact(1,15),"SOURCE_LOCAL_UNSPECIFIED",null))));
     }
     static AppointmentImpactService.Command command(AppointmentImpactService.View row,String key,String action) {
         return new AppointmentImpactService.Command(row.version(),row.forecastToken(),key,action,"已联系收货方核实，保留原预约另行跟进","再次核对",null);

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

@@ -11,11 +11,21 @@ import java.time.LocalDateTime;
 import java.util.List;
 import static org.junit.jupiter.api.Assertions.*;
 
-class WarehouseCalendarMapperTest {
+public class WarehouseCalendarMapperTest {
+    /** H2 测试替身按真实 JSON 内容读取柜次，不把样例值写死到 SQL。 */
+    public static String jsonExtract(String json,String path) throws Exception {
+        return json==null?null:new com.fasterxml.jackson.databind.ObjectMapper().readTree(json).path(path.substring(2)).toString();
+    }
+    /** 测试替身复用 JSON 解码语义。 */
+    public static String jsonUnquote(String value) throws Exception {
+        return value==null?null:new com.fasterxml.jackson.databind.ObjectMapper().readTree(value).asText();
+    }
     /** 同柜跨客户不重复，人工改期与已建计划日期分别保留。 */
     @Test void deduplicatesCustomersPreservesManualAndFrozenDatesAndFindsCrossMonthRescheduling() throws Exception {
         var ds = new JdbcDataSource(); ds.setURL("jdbc:h2:mem:warehouse-calendar;MODE=MySQL;DB_CLOSE_DELAY=-1");
         try (var connection=ds.getConnection(); var sql=connection.createStatement()) {
+            sql.execute("CREATE ALIAS JSON_EXTRACT FOR 'com.baiyue.lastleg.calendar.WarehouseCalendarMapperTest.jsonExtract'");
+            sql.execute("CREATE ALIAS JSON_UNQUOTE FOR 'com.baiyue.lastleg.calendar.WarehouseCalendarMapperTest.jsonUnquote'");
             sql.execute("CREATE TABLE ll_order(id BIGINT,customer_id VARCHAR,source_container_booking_id VARCHAR,container_no VARCHAR," +
                 "overseas_warehouse_id VARCHAR,overseas_warehouse_name VARCHAR,overseas_warehouse_code VARCHAR," +
                 "estimated_warehouse_at TIMESTAMP,arrival_time_version INT)");
@@ -26,6 +36,12 @@ class WarehouseCalendarMapperTest {
                 "(3,'A','2','CONT2','W','Warehouse','W','2026-11-10 09:00:00',2)," +
                 "(4,'A','3','CONT3','W','Warehouse','W','2026-11-12 09:00:00',0)");
             sql.execute("INSERT INTO ll_inbound_plan VALUES(4,'A')");
+            sql.execute("ALTER TABLE ll_order ADD source_event_id VARCHAR");
+            sql.execute("ALTER TABLE ll_inbound_plan ADD planned_arrival_date DATE");
+            sql.execute("UPDATE ll_inbound_plan SET planned_arrival_date='2026-11-12'");
+            sql.execute("CREATE TABLE ll_loading_event_inbox(event_id VARCHAR,payload_json VARCHAR)");
+            sql.execute("INSERT INTO ll_loading_event_inbox VALUES('source-1','{\"cabinetNo\":\"D0001\"}')");
+            sql.execute("UPDATE ll_order SET source_event_id='source-1' WHERE source_container_booking_id='1'");
         }
         var config=new MybatisConfiguration(); config.setEnvironment(new Environment("test",new JdbcTransactionFactory(),ds));
         config.addMapper(WarehouseCalendarMapper.class);
@@ -34,9 +50,11 @@ class WarehouseCalendarMapperTest {
             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("D0001",rows.get(0).cabinetNo());
             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());
-            // 清关提柜与日历必须读取相同的人工/冻结事实，默认日期由前端统一推算。
+            assertEquals(1,rows.get(2).planCount()); assertNull(rows.get(2).plannedAt());
+            assertEquals(java.time.LocalDate.of(2026,11,12),rows.get(2).plannedDate());
+            // 清关提柜与日历读取相同冻结事实，默认日期由共用服务端解析器返回。
             var customs=session.getMapper(LastlegOrderMapper.class).findContainerArrivalTimes(List.of("1","2","3"));
             assertEquals(3,customs.size());
             for(var calendar:rows) {

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

@@ -10,10 +10,15 @@ import static org.mockito.Mockito.*;
 class WarehouseCalendarServiceTest {
     /** 读取资格不代替写权限，已有入库计划仍冻结时间。 */
     @Test void keepsReadAccessSeparateFromWriteAndFreezesExistingPlans() {
-        var repository=mock(WarehouseCalendarRepository.class); var service=new WarehouseCalendarService(repository);
+        var repository=mock(WarehouseCalendarRepository.class);
+        var arrivals=mock(com.baiyue.lastleg.service.ContainerWarehouseArrivalService.class);
+        var service=new WarehouseCalendarService(repository,arrivals);
         var query=new WarehouseCalendarModels.Query(LocalDate.of(2026,11,1),LocalDate.of(2026,12,1),List.of("1"));
-        var open=new WarehouseCalendarModels.Entry("1","CONT","Warehouse","W",null,null,0,0,false);
-        var frozen=new WarehouseCalendarModels.Entry("2","CONT2","Warehouse","W",null,null,1,1,false);
+        var open=new WarehouseCalendarModels.Entry("1","D0001","CONT","Warehouse","W",null,null,0,0,false,null,false);
+        var frozen=new WarehouseCalendarModels.Entry("2","D0002","CONT2","Warehouse","W",null,null,1,1,false,null,false);
+        when(arrivals.resolve(List.of("1","2"))).thenReturn(List.of(
+            new com.baiyue.lastleg.dto.ContainerArrivalTimeView("1",null,null,0,0,LocalDate.of(2026,11,2),true),
+            new com.baiyue.lastleg.dto.ContainerArrivalTimeView("2",null,null,1,1,LocalDate.of(2026,11,3),false)));
         when(repository.calendar(query)).thenReturn(List.of(open,frozen));
         assertTrue(service.calendar(query,true).get(0).canEdit()); assertFalse(service.calendar(query,true).get(1).canEdit());
         assertTrue(service.calendar(query,false).stream().noneMatch(WarehouseCalendarModels.Entry::canEdit));

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

@@ -93,7 +93,7 @@ public class DispatchAggregatePersistenceTest {
         var resources=e.f.json.readValue(row.getResourcesJson(),DispatchContracts.Resources.class);
         var d=resources.driver();var proof=d.evidence();
         var next=new DispatchContracts.Resources(resources.vehicle(),new DispatchContracts.DriverSnapshot(d.mode(),d.driverId(),d.name(),d.phone(),
-            new DispatchContracts.DriverEvidence(proof.licenseNo(),proof.licenseExpiresOn(),proof.fileIds(),proof.expectedTaskEndAt(),proof.photoFileIds(),81L)));
+            new DispatchContracts.DriverEvidence(proof.licenseNo(),proof.licenseExpiresOn(),proof.fileIds(),proof.expectedTaskEndAt(),proof.photoFileIds(),81L)), null);
         e.f.db.update("UPDATE ll_dispatch_order SET task_type='PICKUP', resources_json=? WHERE dispatch_no=?",e.f.json.writeValueAsString(next),number);
         var kind=com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER;
         var uploaded=new com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.File(91L,"pickup.png","image/png",3L);
@@ -167,7 +167,7 @@ public class DispatchAggregatePersistenceTest {
         String dispatch(ResourceMode mode,Long driverId,List<Long> ids) throws Exception {
             var created=f.tx.execute(t->f.service.create(f.actor,f.create("evidence-"+UUID.randomUUID(),List.of())));
             var resource=new DispatchContracts.Resources(null,new DispatchContracts.DriverSnapshot(mode,driverId,"测试司机","123456789",
-                new DispatchContracts.DriverEvidence("TEST-LICENSE",LocalDate.of(2099,1,1),ids,Instant.parse("2098-01-01T00:00:00Z"),List.of())));
+                new DispatchContracts.DriverEvidence("TEST-LICENSE",LocalDate.of(2099,1,1),ids,Instant.parse("2098-01-01T00:00:00Z"),List.of())), null);
             f.db.update("UPDATE ll_dispatch_order SET resources_json=? WHERE dispatch_no=?",f.json.writeValueAsString(resource),created.dispatchNo());return created.dispatchNo();
         }
         /** File内容固定为离线测试字节；真实复合归属由既有两个HTTP网关合同分别覆盖。 */
@@ -201,10 +201,55 @@ public class DispatchAggregatePersistenceTest {
         verifyNoInteractions(facts,sources,serial);
     }
 
+    /** 有货取消只释放原安排；未实收计划和已有实托都不重验当前货物资格，也不扣减或恢复库存。 */
+    @org.junit.jupiter.params.ParameterizedTest
+    @org.junit.jupiter.params.provider.ValueSource(booleans={true,false})
+    void cancellationReleasesOriginalClaimsWithoutRequiringCurrentCargoReadiness(boolean planned) throws Exception {
+        var f=new Fixture();var a=f.source(1,"101",501,"ONT8",10);var b=f.source(2,"101",502,"ONT8",10);
+        if(planned)for(var row:f.candidates.values())row.warehousePalletId(null).sourceStage("PLAN");
+        var created=f.tx.execute(t->f.service.create(f.actor,f.create("cargo-cancel",List.of(a,b))));
+        var root=f.repository.find(created.dispatchNo());
+        var originalCargo=f.db.queryForList("SELECT * FROM ll_dispatch_item ORDER BY id");
+        var rules=new DispatchService();var facts=mock(com.baiyue.lastleg.relabel.port.RelabelDispatchSourcePort.class);
+        var sources=mock(DispatchSourceRepository.class);var serial=mock(com.baiyue.lastleg.inventory.port.PhysicalPalletSerialPort.class);
+        org.springframework.test.util.ReflectionTestUtils.setField(rules,"relabelSources",facts);
+        org.springframework.test.util.ReflectionTestUtils.setField(rules,"wholeSources",sources);
+        org.springframework.test.util.ReflectionTestUtils.setField(rules,"palletSerial",serial);
+        when(facts.snapshot(anyString(),anyList())).thenThrow(new IllegalArgumentException("当前货物不满足装车条件"));
+        org.springframework.test.util.ReflectionTestUtils.setField(f.service,"sourceRules",rules);
+        var request=new DispatchCommands.ReasonCommand(created.recordVersion(),"cancel-cargo-original","仅撤销运输安排");
+        var cancelled=f.tx.execute(t->f.service.cancel(f.actor,created.dispatchNo(),request));
+        assertThat(cancelled.status()).isEqualTo(Status.CANCELLED);
+        assertThat(f.tx.execute(t->f.service.cancel(f.actor,created.dispatchNo(),request)).replayed()).isTrue();
+        assertThat(f.db.queryForList("SELECT * FROM ll_dispatch_item ORDER BY id")).isEqualTo(originalCargo);
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_pallet_lock WHERE status='ACTIVE'",Long.class)).isZero();
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_physical_pallet_lock WHERE status='ACTIVE'",Long.class)).isZero();
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_inventory_ledger",Long.class)).isZero();
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_command WHERE idempotency_key='cancel-cargo-original'",Long.class)).isOne();
+        assertThat(f.db.queryForObject("SELECT status FROM ll_fleet_trip WHERE id=?",String.class,root.getTripId())).isEqualTo("CANCELLED");
+        verifyNoInteractions(facts,sources);
+        if(planned)verifyNoInteractions(serial);else {verify(serial).lock(List.of(501L,502L));verifyNoMoreInteractions(serial);}
+    }
+
+    /** 撤销安排不校验装车就绪，但真实扫码和旧版本仍阻断且不释放原占用。 */
+    @Test void cancellationStillRejectsStaleVersionAndRealPickWithZeroHeaderCounts() throws Exception {
+        var f=new Fixture();var source=f.source(1,"101",501,"ONT8",10);
+        var created=f.tx.execute(t->f.service.create(f.actor,f.create("guarded-cancel",List.of(source))));
+        var stale=new DispatchCommands.ReasonCommand(created.recordVersion()+1,"stale-cancel","旧版本不能释放占用");
+        assertThatThrownBy(()->f.tx.execute(t->f.service.cancel(f.actor,created.dispatchNo(),stale))).hasMessageContaining("版本已变化");
+        long item=f.db.queryForObject("SELECT id FROM ll_dispatch_item",Long.class);
+        f.db.update("INSERT INTO ll_dispatch_pda_pick(customer_id,dispatch_item_id,packages)VALUES('101',?,1)",item);
+        var request=new DispatchCommands.ReasonCommand(created.recordVersion(),"picked-cancel","不能隐去真实扫码");
+        assertThatThrownBy(()->f.tx.execute(t->f.service.cancel(f.actor,created.dispatchNo(),request))).hasMessageContaining("真实执行");
+        assertThat(f.db.queryForObject("SELECT status FROM ll_dispatch_order",String.class)).isEqualTo("ACTIVE");
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_pallet_lock WHERE status='ACTIVE'",Long.class)).isOne();
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_command WHERE action='CANCEL'",Long.class)).isZero();
+    }
+
     /** 空单编辑保留零货量与版本命令，不借编辑隐式制造可装车来源。 */
     @Test void emptyShellEditPreservesZeroCargoAndVersionedReplay() throws Exception {
         var f=new Fixture();var created=f.tx.execute(t->f.service.create(f.actor,f.create("empty-edit",List.of())));
-        var request=new DispatchCommands.Update(0L,"empty-edit-original",null,null,null,null,"空单补充备注", true);
+        var request=new DispatchCommands.Update(0L,"empty-edit-original",null,null,null,null,"空单补充备注", true, null);
         var saved=f.tx.execute(t->f.service.update(f.actor,created.dispatchNo(),request));
         assertThat(saved.stage()).isEqualTo(Stage.BEFORE_LOADING);assertThat(saved.counts().packageCount()).isZero();
         assertThat(saved.recordVersion()).isGreaterThan(created.recordVersion());
@@ -244,7 +289,7 @@ public class DispatchAggregatePersistenceTest {
     }
     @Test void updateSavesCurrentVehiclePlanAndReplayWithoutAnyVehicleAppointmentField() throws Exception {
         var f=new Fixture();var input=f.configured("update-without-vehicle-appointment",List.of(f.source(1,"101",501,"ONT8",3)));var created=f.tx.execute(t->f.service.create(f.actor,input));
-        var arrival=input.plannedDepartureAt().plusSeconds(3600);var request=new DispatchCommands.Update(created.recordVersion(),"update-current-plan",input.vehicle(),input.driver(),input.plannedDepartureAt(),arrival,"调整本趟计划", true);
+        var arrival=input.plannedDepartureAt().plusSeconds(3600);var request=new DispatchCommands.Update(created.recordVersion(),"update-current-plan",input.vehicle(),input.driver(),input.plannedDepartureAt(),arrival,"调整本趟计划", true, null);
         var saved=f.tx.execute(t->f.service.update(f.actor,created.dispatchNo(),request));assertThat(saved.recordVersion()).isGreaterThan(created.recordVersion());
         var detail=f.tx.execute(t->f.service.detail(f.actor,created.dispatchNo()));assertThat(detail.dispatchInfo().estimatedArrivalAt()).isEqualTo(arrival);assertThat(detail.documents().remark()).isEqualTo("调整本趟计划");
         var publicJson=f.json.valueToTree(detail);assertThat(publicJson.path("dispatchInfo").has("vehicleAppointment")).isFalse();assertThat(publicJson.path("dispatchInfo").has("fbaAppointments")).isTrue();

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

@@ -186,7 +186,7 @@ class DispatchBolReadPersistenceTest {
             db.execute("CREATE TABLE ll_inbound_fba_appointment(id BIGINT PRIMARY KEY,appointment_no VARCHAR(64),confirmation_no VARCHAR(128))");
             db.execute("CREATE TABLE ll_inbound_fba_appointment_item(id BIGINT PRIMARY KEY,appointment_id BIGINT NOT NULL,source_key VARCHAR(160) NOT NULL,customer_id VARCHAR(128) NOT NULL,order_id BIGINT,fba_warehouse_code VARCHAR(128) NOT NULL,UNIQUE(appointment_id,source_key))");
             var config=new MybatisConfiguration();config.addMapper(DispatchBolMapper.class);var factory=new MybatisSqlSessionFactoryBean();factory.setDataSource(ds);factory.setConfiguration(config);factory.afterPropertiesSet();var mapper=new SqlSessionTemplate(factory.getObject()).getMapper(DispatchBolMapper.class);
-            var roots=mock(DispatchAggregateRepository.class);var row=new DispatchAggregate();row.setId(1L);row.setDispatchNo("DP-ONE");row.setOverseasWarehouseId("9");row.setResourcesJson(new ObjectMapper().writeValueAsString(new DispatchContracts.Resources(null,null)));when(roots.find("DP-ONE")).thenReturn(row);
+            var roots=mock(DispatchAggregateRepository.class);var row=new DispatchAggregate();row.setId(1L);row.setDispatchNo("DP-ONE");row.setOverseasWarehouseId("9");row.setResourcesJson(new ObjectMapper().writeValueAsString(new DispatchContracts.Resources(null,null, null)));when(roots.find("DP-ONE")).thenReturn(row);
             service=new DispatchBolReadService(roots,new DispatchBolRepository(mapper),new ObjectMapper());
             tx=new TransactionTemplate(new DataSourceTransactionManager(ds));tx.setReadOnly(true);tx.setIsolationLevel(TransactionDefinition.ISOLATION_REPEATABLE_READ);
         }

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

@@ -17,7 +17,7 @@ class DispatchCapacityDemandPersistenceTest {
         var service=new DispatchCapacityDemandService(f.repository,f.json);
         assertThat(service.page(query()).records()).extracting(DispatchCapacityDemands.Demand::dispatchNo).containsExactly(created.dispatchNo());
         assertThat(f.service.detail(f.actor,created.dispatchNo()).publishLooseboardDemand()).isTrue();
-        var update=new DispatchCommands.Update(created.recordVersion(),"pool-disable",null,null,null,null,null,false);
+        var update=new DispatchCommands.Update(created.recordVersion(),"pool-disable",null,null,null,null,null,false, null);
         var saved=f.tx.execute(s->f.service.update(f.actor,created.dispatchNo(),update));
         assertThat(f.service.detail(f.actor,created.dispatchNo()).publishLooseboardDemand()).isFalse();
         assertThat(service.page(query()).total()).isZero();

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

@@ -0,0 +1,178 @@
+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 com.baiyue.lastleg.dispatch.port.DispatchTypes.ResourceMode;
+import com.baiyue.lastleg.masterdata.vehicle.application.port.out.VehicleRepository;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Optional;
+
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+/** 维护资料与车辆照片经真实聚合、Fleet资源解析、持久化及审核往返。 */
+class DispatchMaintenancePersistenceTest {
+    /** 主档和临时车辆均保留本趟照片与八项资料，不能被Fleet主档重建吞掉。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"MASTER", "EXTERNAL"})
+    void maintenanceAndVehiclePhotosSurviveReplayAndBothReviews(String mode) throws Exception {
+        var f = new DispatchAggregatePersistenceTest.Fixture();
+        var input = f.configured("maintenance-create", List.of(f.source(1, "101", 501, "ONT8", 3)));
+        var created = f.tx.execute(t -> f.service.create(f.actor, input));
+        var vehicle = vehicle(f, mode, List.of(301L));
+        var maintenance = new Maintenance(LocalDate.of(2026, 11, 1), " FBA自提 ", "一提多卸", "混装",
+            " fleet@example.test ", "厢式货车", " account ", " appointment ");
+        var request = new DispatchCommands.Update(created.recordVersion(), "maintenance-save", vehicle, input.driver(),
+            input.plannedDepartureAt(), input.estimatedArrivalAt(), "保留原备注", true, maintenance);
+        var saved = f.tx.execute(t -> f.service.update(f.actor, created.dispatchNo(), request));
+        assertThat(f.tx.execute(t -> f.service.update(f.actor, created.dispatchNo(), request)).replayed()).isTrue();
+        f.approve(saved);
+        var detail = f.tx.execute(t -> f.service.detail(f.actor, created.dispatchNo()));
+        assertThat(detail.vehicleInfo().maintenance()).isEqualTo(maintenance);
+        assertThat(detail.vehicleInfo().maintenance().appointmentAccount()).isEqualTo("account");
+        assertThat(detail.vehicleInfo().vehicle().evidenceFileIds()).containsExactly(301L);
+        assertThat(detail.dispatchInfo().plannedDepartureAt()).isEqualTo(input.plannedDepartureAt());
+        assertThat(detail.dispatchInfo().departedAt()).isNull();
+        var persisted = f.json.readValue(f.repository.find(created.dispatchNo()).getResourcesJson(), Resources.class);
+        assertThat(persisted.maintenance()).isEqualTo(maintenance);
+        assertThat(persisted.vehicle().evidenceFileIds()).containsExactly(301L);
+        assertThat(f.repository.find(created.dispatchNo()).getRemark()).isEqualTo("保留原备注");
+        verify(files(f), atLeastOnce()).metadata(f.repository.find(created.dispatchNo()).getId(), DispatchEvidenceGateway.Kind.VEHICLE, 301L);
+        if (mode.equals("MASTER")) {
+            assertThat(detail.vehicleInfo().vehicle().plate()).isEqualTo("MASTER-71");
+            assertThat(detail.vehicleInfo().vehicle().capacity().palletSpaces()).isEqualTo(15);
+        }
+    }
+
+    /** 跨车、跨分类及失效照片的提供者拒绝必须整体回滚，MASTER同样不能绕过。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"跨车", "错分类", "已失效"})
+    void invalidVehiclePhotoCannotChangeDraft(String reason) throws Exception {
+        var f = new DispatchAggregatePersistenceTest.Fixture();
+        var input = f.configured("invalid-vehicle-create", List.of());
+        var created = f.tx.execute(t -> f.service.create(f.actor, input));
+        var before = f.db.queryForMap("SELECT resources_json,record_version FROM ll_dispatch_order WHERE dispatch_no=?", created.dispatchNo());
+        var dispatchId = f.repository.find(created.dispatchNo()).getId();
+        doThrow(new IllegalArgumentException(reason)).when(files(f)).metadata(dispatchId, DispatchEvidenceGateway.Kind.VEHICLE, 301L);
+        var request = new DispatchCommands.Update(created.recordVersion(), "invalid-vehicle-save", vehicle(f, "MASTER", List.of(301L)),
+            input.driver(), input.plannedDepartureAt(), null, null, true, null);
+        assertThatThrownBy(() -> f.tx.execute(t -> f.service.update(f.actor, created.dispatchNo(), request))).hasMessageContaining(reason);
+        assertThat(f.db.queryForMap("SELECT resources_json,record_version FROM ll_dispatch_order WHERE dispatch_no=?", created.dispatchNo())).isEqualTo(before);
+        assertThat(f.db.queryForObject("SELECT COUNT(*) FROM ll_dispatch_command WHERE idempotency_key='invalid-vehicle-save'", Long.class)).isZero();
+    }
+
+    /** 维护整体为空或八字段为空均可保存空草稿，清空资料不会制造实际发车或正式预约。 */
+    @Test void emptyMaintenanceCanBeSavedAndCleared() throws Exception {
+        var f = new DispatchAggregatePersistenceTest.Fixture();
+        var created = f.tx.execute(t -> f.service.create(f.actor, f.create("empty-maintenance", List.of())));
+        var empty = f.json.readValue("{\"plannedDeliveryDate\":\" \",\"deliveryMethod\":\" \",\"pickupMethod\":\"\",\"loadType\":\" \",\"fleetEmail\":\" \",\"vehicleType\":\"\",\"appointmentAccount\":\" \",\"appointmentNo\":\"\"}", Maintenance.class);
+        assertThat(empty).isEqualTo(new Maintenance(null, null, null, null, null, null, null, null));
+        var saved = f.tx.execute(t -> f.service.update(f.actor, created.dispatchNo(), new DispatchCommands.Update(
+            created.recordVersion(), "empty-maintenance-save", null, null, null, null, null, true, empty)));
+        f.tx.execute(t -> f.service.update(f.actor, created.dispatchNo(), new DispatchCommands.Update(
+            saved.recordVersion(), "empty-maintenance-clear", null, null, null, null, null, true, null)));
+        var detail = f.tx.execute(t -> f.service.detail(f.actor, created.dispatchNo()));
+        assertThat(detail.vehicleInfo().maintenance()).isNull();
+        assertThat(detail.dispatchInfo().departedAt()).isNull();
+    }
+
+    /** 文本仅限约定选项和长度，ISO日期不能接受时间串或不存在的日期。 */
+    @Test void maintenanceRejectsUnknownOptionsAndOverlongText() throws Exception {
+        var json = new DispatchAggregatePersistenceTest.Fixture().json;
+        for (String field : List.of("deliveryMethod", "pickupMethod", "loadType", "vehicleType")) {
+            assertThatThrownBy(() -> json.treeToValue(json.createObjectNode().put(field, "未知"), Maintenance.class))
+                .hasRootCauseInstanceOf(IllegalArgumentException.class);
+        }
+        for (String field : List.of("fleetEmail", "appointmentAccount", "appointmentNo")) {
+            int max = field.equals("fleetEmail") ? 254 : 128;
+            assertThat(json.treeToValue(json.createObjectNode().put(field, "a".repeat(max)), Maintenance.class)).isNotNull();
+            assertThatThrownBy(() -> json.treeToValue(json.createObjectNode().put(field, "a".repeat(max + 1)), Maintenance.class))
+                .hasRootCauseInstanceOf(IllegalArgumentException.class);
+        }
+        for (String date : List.of("2026-10-32", "2026-02-29", "2026-10-21T10:00:00", "2026/10/21")) {
+            assertThatThrownBy(() -> json.treeToValue(json.createObjectNode().put("plannedDeliveryDate", date), Maintenance.class)).isInstanceOf(com.fasterxml.jackson.core.JsonProcessingException.class);
+        }
+        var parsed = json.treeToValue(json.createObjectNode().put("plannedDeliveryDate", "2026-10-21"), Maintenance.class);
+        assertThat(parsed.plannedDeliveryDate()).isEqualTo(LocalDate.of(2026, 10, 21));
+        assertThat(json.valueToTree(parsed).path("plannedDeliveryDate").asText()).isEqualTo("2026-10-21");
+    }
+
+    /** 取货资源投影和照片保存同样保留正式维护资料，不能在重建快照时掉字段。 */
+    @Test void transportResourceRebuildAndPhotoSaveKeepMaintenance() throws Exception {
+        var f = new DispatchAggregatePersistenceTest.Fixture();
+        var input = f.configured("projection-maintenance-create", List.of());
+        var created = f.tx.execute(t -> f.service.create(f.actor, input));
+        var maintenance = new Maintenance(LocalDate.of(2026, 11, 1), "外配", "一提一卸", "地板", null, "平板车", null, "AP-LOCAL");
+        f.tx.execute(t -> f.service.update(f.actor, created.dispatchNo(), new DispatchCommands.Update(created.recordVersion(),
+            "projection-maintenance-save", vehicle(f, "MASTER", List.of(301L)), input.driver(), input.plannedDepartureAt(), null, null, true, maintenance)));
+        var projection = new com.baiyue.lastleg.dispatch.transport.TransportTaskProjection(f.repository,
+            mock(com.baiyue.lastleg.dispatch.transport.TransportTaskRepository.class),
+            mock(com.baiyue.lastleg.trucking.repository.UsTruckOrderRepository.class), mock(DispatchNumberGenerator.class), f.json);
+        var resources = f.json.readValue(f.repository.find(created.dispatchNo()).getResourcesJson(), Resources.class);
+        f.tx.executeWithoutResult(t -> projection.savePhotos(created.dispatchNo(), f.actor.operatorId(), List.of(302L), resources.driver().evidence()));
+        var row = f.repository.find(created.dispatchNo());
+        assertThat(f.json.readValue(row.getResourcesJson(), Resources.class).maintenance()).isEqualTo(maintenance);
+        var trip = new com.baiyue.lastleg.fleet.trip.FleetTripEntity();
+        trip.setVehicleId(71L); trip.setVehiclePlate("MASTER-71");
+        ReflectionTestUtils.invokeMethod(projection, "resources", row, trip);
+        var rebuilt = f.json.readValue(row.getResourcesJson(), Resources.class);
+        assertThat(rebuilt.maintenance()).isEqualTo(maintenance);
+        assertThat(rebuilt.vehicle().evidenceFileIds()).containsExactly(302L);
+    }
+
+    /** 请求、资源与详情共用可空维护结构；文档中的每个选项都必须被正式DTO接受。 */
+    @Test void openApiPublishesSymmetricNullableMaintenanceContract() throws Exception {
+        var json = new com.fasterxml.jackson.databind.ObjectMapper().findAndRegisterModules();
+        com.fasterxml.jackson.databind.JsonNode root;
+        try (var input = getClass().getResourceAsStream("/openapi/overseas-business-v1.yaml")) {
+            root = json.valueToTree(new org.yaml.snakeyaml.Yaml().load(input));
+        }
+        var schemas = root.path("components").path("schemas");
+        for (String name : List.of("DispatchUpdate", "DispatchResources", "DispatchVehicleInfo")) {
+            var field = schemas.path(name).path("properties").path("maintenance");
+            assertThat(field.path("nullable").asBoolean()).isTrue();
+            assertThat(field.path("allOf").get(0).path("$ref").asText()).isEqualTo("#/components/schemas/DispatchMaintenance");
+            for (var required : schemas.path(name).path("required")) assertThat(required.asText()).isNotEqualTo("maintenance");
+        }
+        var schema = schemas.path("DispatchMaintenance");
+        var fields = schema.path("properties");
+        assertThat(fields.size()).isEqualTo(Maintenance.class.getRecordComponents().length);
+        assertThat(schema.path("required").isMissingNode()).isTrue();
+        for (var field : Maintenance.class.getRecordComponents()) {
+            assertThat(fields.path(field.getName()).path("nullable").asBoolean()).isTrue();
+            for (var value : fields.path(field.getName()).path("enum")) {
+                assertThat(json.treeToValue(json.createObjectNode().put(field.getName(), value.asText()), Maintenance.class)).isNotNull();
+            }
+        }
+        assertThat(fields.path("plannedDeliveryDate").path("format").asText()).isEqualTo("date");
+        assertThat(fields.path("fleetEmail").path("maxLength").asInt()).isEqualTo(254);
+        assertThat(fields.path("appointmentAccount").path("maxLength").asInt()).isEqualTo(128);
+        assertThat(fields.path("appointmentNo").path("maxLength").asInt()).isEqualTo(128);
+    }
+
+    /** 主档请求只携带身份与本趟照片，名称及容量必须仍取权威主档。 */
+    private static DispatchCommands.Vehicle vehicle(DispatchAggregatePersistenceTest.Fixture f, String mode, List<Long> photos) {
+        if (mode.equals("MASTER")) {
+            var vehicles = (VehicleRepository) ReflectionTestUtils.getField(f.nativeFleetService, "vehicles");
+            var actual = new VehicleRepository.VehicleSnapshot(71L, "MASTER-71", null, null, 0L, "主档车队", null,
+                "OVERSEAS", "OWNED", "IN_SERVICE", null, 0L, null, null, 15, new BigDecimal("10000"), new BigDecimal("50"));
+            when(vehicles.findById(71L)).thenReturn(Optional.of(actual));
+            return new DispatchCommands.Vehicle(ResourceMode.MASTER, 71L, "不能覆盖主档", null, null, photos);
+        }
+        return new DispatchCommands.Vehicle(ResourceMode.EXTERNAL, null, "EXTERNAL-71", "本趟车队",
+            new Capacity(15, new BigDecimal("10000"), new BigDecimal("50")), photos);
+    }
+
+    /** 附件提供者仍执行本车及分类边界；只隔离外部File服务。 */
+    private static DispatchEvidenceGateway files(DispatchAggregatePersistenceTest.Fixture f) {
+        return (DispatchEvidenceGateway) ReflectionTestUtils.getField(f.service, "evidence");
+    }
+}

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

@@ -83,7 +83,7 @@ class DispatchResourcePhotosPersistenceTest {
         var e = d.evidence();
         var driver = new DispatchCommands.Driver(d.mode(), d.driverId(), d.name(), d.phone(),
             new DispatchContracts.DriverEvidence(e.licenseNo(), e.licenseExpiresOn(), e.fileIds(), e.expectedTaskEndAt(), photos));
-        return new DispatchCommands.Update(version, key, input.vehicle(), driver, input.plannedDepartureAt(), input.estimatedArrivalAt(), "维护照片", true);
+        return new DispatchCommands.Update(version, key, input.vehicle(), driver, input.plannedDepartureAt(), input.estimatedArrivalAt(), "维护照片", true, null);
     }
 
     /** 只替代外部附件提供者，资源、命令和事务仍走真实服务。 */

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

@@ -88,7 +88,7 @@ class DispatchReviewWorkflowPersistenceTest {
             long item=f.db.queryForObject("SELECT id FROM ll_dispatch_item WHERE plan_pallet_id=3",Long.class);
             var removed=f.tx.execute(s->f.service.removeCargo(f.actor,created.dispatchNo(),item,new DispatchCommands.ReasonCommand(addedAgain.recordVersion(),"remove","调整目的仓")));
             var resources=f.configured("updated-resources",List.of());
-            var updated=f.tx.execute(s->f.service.update(f.actor,created.dispatchNo(),new DispatchCommands.Update(removed.recordVersion(),"update-vehicle",resources.vehicle(),resources.driver(),resources.plannedDepartureAt().plusSeconds(60),null,"客服更正", true)));
+            var updated=f.tx.execute(s->f.service.update(f.actor,created.dispatchNo(),new DispatchCommands.Update(removed.recordVersion(),"update-vehicle",resources.vehicle(),resources.driver(),resources.plannedDepartureAt().plusSeconds(60),null,"客服更正", true, null)));
             var detail=f.service.detail(f.actor,created.dispatchNo());
             var retained=loading?detail.reviews().loadingReview():detail.reviews().dispatchReview();
             assertThat(detail.reviewState()).isEqualTo(ReviewState.DRAFT);

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

@@ -57,6 +57,35 @@ class DispatchServiceTest {
         assertThatThrownBy(()->service.lockExecutionSources("9",List.of(item))).hasMessageContaining("完整实托来源已变化");
         verify(facts).snapshot("9",List.of(501L));verifyNoInteractions(sources,palletSerial);
     }
+    /** 未实收计划撤销不依赖实托、当前货源资格或库存，执行链仍保留独立严格校验。 */
+    @Test void cancellationOfPlannedCargoNeedsNoPhysicalOrInventoryFacts(){
+        var item=new com.baiyue.lastleg.dispatch.entity.DispatchItem();item.setPlanPalletId(1L);item.setSourceStage("PLAN");
+        service.lockCancellationSources("9",List.of(item));
+        service.lockCancellationSources("9",List.of());
+        verifyNoInteractions(facts,sources,palletSerial,relabels,measurements);
+    }
+    /** 已有实托只按原身份取得升序串行锁，不因货物数量或新来源变化阻断释放本车占用。 */
+    @Test void physicalCancellationLocksOriginalPalletsWithoutReadingCurrentStock(){
+        var a=new com.baiyue.lastleg.dispatch.entity.DispatchItem();a.setWarehousePalletId(502L);
+        var b=new com.baiyue.lastleg.dispatch.entity.DispatchItem();b.setWarehousePalletId(501L);
+        service.lockCancellationSources("9",List.of(a,b,a));
+        verify(palletSerial).lock(List.of(501L,502L));verifyNoMoreInteractions(palletSerial);
+        verifyNoInteractions(facts,sources,relabels,measurements);
+    }
+    /** 换标恢复预占仍先锁齐本车申请再锁原实托，不锁入后来新增的其他申请。 */
+    @Test void relabelCancellationLocksSelectedApplicationsBeforeOriginalPallets(){
+        var a=new com.baiyue.lastleg.dispatch.entity.DispatchItem();a.setSourceBusinessType("RELABEL_ORDER");a.setSourceBusinessNo("RL-2");a.setWarehousePalletId(502L);
+        var b=new com.baiyue.lastleg.dispatch.entity.DispatchItem();b.setSourceBusinessType("RELABEL_ORDER");b.setSourceBusinessNo("RL-1");b.setWarehousePalletId(501L);
+        org.springframework.transaction.support.TransactionSynchronizationManager.initSynchronization();
+        try {
+            service.lockCancellationSources("9",List.of(a,b));
+            var order=inOrder(facts,palletSerial);order.verify(facts).lockApplications(List.of("RL-1","RL-2"));order.verify(palletSerial).lock(List.of(501L,502L));
+            verifyNoMoreInteractions(facts,palletSerial);verifyNoInteractions(sources,relabels,measurements);
+        } finally {
+            for(var synchronization:org.springframework.transaction.support.TransactionSynchronizationManager.getSynchronizations())synchronization.afterCompletion(0);
+            org.springframework.transaction.support.TransactionSynchronizationManager.clearSynchronization();
+        }
+    }
     @Test void anotherOperatorsDraftIsRejectedBeforeAnyCandidateRead(){
         assertThatThrownBy(()->service.candidatePage("operator",new DispatchPlanningModels.CandidateQuery("9",null,null,null,"PLAN","foreign",1,20,"ALL"))).hasMessageContaining("草稿");verifyNoInteractions(sources);
     }

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/transport/TransportReviewPhotosTest.java

@@ -55,13 +55,13 @@ class TransportReviewPhotosTest {
     /** 换司机后旧人像不允许重复绑定。 */
     @Test void rejectsPhotosCarriedFromAnotherDriver() throws Exception {
         row.setResourcesJson(json.writeValueAsString(new Resources(null,new DriverSnapshot(ResourceMode.MASTER,5L,"原司机","000",
-            new DriverEvidence(null,null,List.of(23L),null,List.of(22L))))));
+            new DriverEvidence(null,null,List.of(23L),null,List.of(22L))), null)));
         assertThatThrownBy(()->service.validate(row,trip,request(new ReviewAttachments(List.of(21L),List.of(22L),List.of(24L)),null))).hasMessageContaining("重新上传");
     }
     /** 审核复验已保存证据，照片后续失效也不能通过。 */
     @Test void reviewRevalidatesPersistedPhotoOwnership() throws Exception {
         row.setResourcesJson(json.writeValueAsString(new Resources(new VehicleSnapshot(ResourceMode.MASTER,1L,"TEST",null,null,null,List.of(21L)),
-            new DriverSnapshot(ResourceMode.MASTER,2L,"司机","000",new DriverEvidence(null,null,List.of(23L),null,List.of(22L))))));
+            new DriverSnapshot(ResourceMode.MASTER,2L,"司机","000",new DriverEvidence(null,null,List.of(23L),null,List.of(22L))), null)));
         service.verifyReview(row,trip);verify(files).metadata(10L,VEHICLE,21L);
         when(files.metadata(10L,DRIVER,23L)).thenThrow(new IllegalArgumentException("附件失效"));
         assertThatThrownBy(()->service.verifyReview(row,trip)).hasMessageContaining("附件失效");

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

@@ -40,7 +40,7 @@ class OwnedBusinessScopePersistenceTest {
         when(reader.detail(any(),anyString())).thenAnswer(call->{
             var s=baseline.repository.source(call.getArgument(1));var r=baseline.codec.read(s.getResourcesJson(),DispatchContracts.Resources.class);
             return new DispatchViews.Detail(s.getDispatchNo(),"DELIVERY",DispatchTypes.Status.ACTIVE,DispatchTypes.Stage.valueOf(s.getStage()),s.getRecordVersion(),
-                DispatchTypes.ReviewState.APPROVED,null,null,true,Map.of(),new DispatchViews.VehicleInfo(r.vehicle(),r.driver()),null,null,List.of(),true);
+                DispatchTypes.ReviewState.APPROVED,null,null,true,Map.of(),new DispatchViews.VehicleInfo(r.vehicle(),r.driver(), null),null,null,List.of(),true);
         });
         queries=tx(new OwnedBusinessQueryService(baseline.repository,baseline.projection,baseline.codec,reader));
         var commands=tx(new OwnedBusinessCommandService(baseline.repository,baseline.codec));
@@ -67,7 +67,7 @@ class OwnedBusinessScopePersistenceTest {
         var original=OwnedBusinessFixtures.source();
         var resources=baseline.codec.read(original.getResourcesJson(),DispatchContracts.Resources.class);
         var vehicle=new DispatchContracts.VehicleSnapshot(DispatchTypes.ResourceMode.valueOf(mode),"MASTER".equals(mode)?7L:null,"TEST-OUT-"+id,carrier,"IN_SERVICE",resources.vehicle().capacity(),List.of());
-        String snapshot=baseline.codec.write(new DispatchContracts.Resources(vehicle,resources.driver()));
+        String snapshot=baseline.codec.write(new DispatchContracts.Resources(vehicle,resources.driver(), null));
         String load=original.getLoadingConfirmationJson().replace("\"warehousePalletId\":31","\"warehousePalletId\":"+(31+id));
         baseline.jdbc.update("""
             INSERT INTO ll_dispatch_order SELECT ?,?,trip_id,status,?,record_version,planned_departure_at,loading_completed_at,departed_at,delivery_completed_at,

lastleg-service/src/test/java/com/baiyue/lastleg/inboundplan/service/InboundPlanServiceTest.java

@@ -58,12 +58,14 @@ class InboundPlanServiceTest {
     @Mock WarehouseResourceGateway warehouseGateway;
     @Mock LastlegOrderCommandRecordMapper commandMapper;
     @Mock LastlegSourcePalletMapper sourcePalletMapper;
+    @Mock com.baiyue.lastleg.service.ContainerWarehouseArrivalService warehouseArrival;
 
     private InboundPlanService service;
 
     @BeforeEach
     void setUp() {
         service = new InboundPlanService();
+        ReflectionTestUtils.setField(service,"warehouseArrival",warehouseArrival);
         ReflectionTestUtils.setField(service, "planMapper", planMapper);
         ReflectionTestUtils.setField(service, "lineMapper", lineMapper);
         ReflectionTestUtils.setField(service, "palletMapper", palletMapper);
@@ -95,8 +97,8 @@ class InboundPlanServiceTest {
                 "100", 2L, "BOOKING-1", "193000000000200003")));
         org.mockito.Mockito.lenient().when(orderMapper.findSourceContainerBookingId(any(), anyLong()))
             .thenReturn("BOOKING-1");
-        org.mockito.Mockito.lenient().when(orderMapper.containerEstimatedWarehouseTimes(any()))
-            .thenReturn(List.of(LocalDateTime.of(2026, 9, 15, 8, 0)));
+        org.mockito.Mockito.lenient().when(warehouseArrival.requiredDate(any()))
+            .thenReturn(java.time.LocalDate.of(2026, 9, 15));
     }
 
     @Test
@@ -176,15 +178,16 @@ class InboundPlanServiceTest {
     void manualPlanRejectsMissingOrInconsistentContainerArrivalTime() {
         ManualInboundPlanRequest request = new ManualInboundPlanRequest("100", 2L, 0,
             2, "STANDARD", true, true, true, "优先收货");
-        when(orderMapper.containerEstimatedWarehouseTimes("BOOKING-1")).thenReturn(List.of());
+        when(warehouseArrival.requiredDate("BOOKING-1")).thenThrow(new ResponseStatusException(org.springframework.http.HttpStatus.CONFLICT,"来源柜预计到仓时间缺失，请先补齐柜级时间"));
 
         ResponseStatusException missing = assertThrows(ResponseStatusException.class,
             () -> service.convertManual(request, "manual-missing-arrival", "900"));
         assertEquals(409, missing.getStatusCode().value());
         assertEquals("来源柜预计到仓时间缺失，请先补齐柜级时间", missing.getReason());
 
-        when(orderMapper.containerEstimatedWarehouseTimes("BOOKING-1")).thenReturn(List.of(
-            LocalDateTime.of(2026, 9, 15, 8, 0), LocalDateTime.of(2026, 9, 16, 8, 0)));
+        org.mockito.Mockito.doThrow(new ResponseStatusException(
+            org.springframework.http.HttpStatus.CONFLICT,"来源柜预计到仓时间不一致，请先修正柜级时间"))
+            .when(warehouseArrival).requiredDate("BOOKING-1");
         ResponseStatusException inconsistent = assertThrows(ResponseStatusException.class,
             () -> service.convertManual(request, "manual-inconsistent-arrival", "900"));
         assertEquals(409, inconsistent.getStatusCode().value());

lastleg-service/src/test/java/com/baiyue/lastleg/inboundplan/work/FbaAppointmentExecutionAdapterTest.java

@@ -52,6 +52,33 @@ class FbaAppointmentExecutionAdapterTest {
         assertThrows(org.springframework.web.server.ResponseStatusException.class,()->adapter.lockAndInspect(List.of(),"empty","operator"));
         verifyNoInteractions(mapper,amendments,dispatches);
     }
+    /** 有真实客户货物但尚未排车时，可按当前完整版本登记预约，不调用原排车锁。 */
+    @Test void unassignedCustomerCanRebookWithoutLockingAnEmptyDispatchScope() {
+        when(mapper.transportRows(List.of(batch),List.of())).thenReturn(List.of());
+        var current=adapter.inspect(List.of(b));
+        var locked=adapter.lockAndInspect(List.of(b),current.version(),"operator");
+        assertEquals(current.version(),locked.version());
+        assertFalse(locked.members().get(0).completed());assertTrue(locked.members().get(0).canRebook());
+        verifyNoInteractions(amendments,dispatches);
+    }
+    /** 无排车不免除乐观锁，过期的完整执行版本仍须拒绝。 */
+    @Test void unassignedCustomerStillRequiresTheCurrentCompleteExecutionVersion() {
+        when(mapper.transportRows(List.of(batch),List.of())).thenReturn(List.of());
+        var error=assertThrows(org.springframework.web.server.ResponseStatusException.class,
+            ()->adapter.lockAndInspect(List.of(b),"stale-version","operator"));
+        assertEquals(409,error.getStatusCode().value());
+        verifyNoInteractions(amendments,dispatches);
+    }
+    /** 首读无排车、复核时已关联排车，必须拒绝并要求刷新，不能沿空范围放行。 */
+    @Test void dispatchAssociatedDuringTheEmptyScopeRecheckInvalidatesTheVersion() {
+        when(mapper.transportRows(List.of(batch),List.of())).thenReturn(List.of(),List.of(),List.of(row("B","BEFORE_LOADING","PLANNED")));
+        var prior=adapter.inspect(List.of(b));
+        var error=assertThrows(org.springframework.web.server.ResponseStatusException.class,
+            ()->adapter.lockAndInspect(List.of(b),prior.version(),"operator"));
+        assertEquals(409,error.getStatusCode().value());
+        verifyNoInteractions(amendments);
+        verify(dispatches,never()).completion(anyString(),eq(true));verify(dispatches,never()).lockForPlanning(anyString());
+    }
     /** 同车总发运量不能替代本客户的真实签收数量。 */
     @Test void onePhysicalDispatchUsesCustomerEvidenceInsteadOfTheWholeCarShipmentTotal() {
         var rows=List.of(new AppointmentWorkDispatchMapper.TransportRow(1,"D-ONE","A","ACTIVE","DELIVERING",2L,200,200,LocalDateTime.of(2026,10,1,12,0),11,101,100,"RECEIVED",batch,"ORDER:1","FBA:ONT8",100,"T-ONE",2L,"IN_TRANSIT",201L,"OUTBOUNDED","COMPLETED"),

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

@@ -0,0 +1,67 @@
+package com.baiyue.lastleg.service;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.lastleg.appointmentplanning.AppointmentForecastClient;
+import com.baiyue.lastleg.dto.ContainerArrivalTimeView;
+import com.baiyue.lastleg.repository.ContainerWarehouseArrivalRepository;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.server.ResponseStatusException;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.List;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+import static org.mockito.ArgumentMatchers.*;
+
+class ContainerWarehouseArrivalServiceTest {
+    private final ContainerWarehouseArrivalRepository repository=mock(ContainerWarehouseArrivalRepository.class);
+    private final AppointmentForecastClient forecasts=mock(AppointmentForecastClient.class);
+    private final ContainerWarehouseArrivalService service=new ContainerWarehouseArrivalService(repository,forecasts,"internal-test");
+
+    /** 默认日期跨月按当地自然日推进，展示和计划创建必须读取同一结果。 */
+    @Test void defaultsAcrossMonthAndUsesExactlyTheSameDateForPlanning() {
+        when(repository.find(List.of("1"))).thenReturn(List.of(new ContainerArrivalTimeView("1",null,null,0,0,null,false)));
+        when(forecasts.batch(anyString(),any())).thenReturn(ApiResponse.success(List.of(
+            new AppointmentForecastClient.Forecast(1L,null,null,"SOURCE_LOCAL_UNSPECIFIED",LocalDateTime.of(2026,10,30,23,30)))));
+        var result=service.resolve(List.of("1")).get(0);
+        assertEquals(LocalDate.of(2026,11,1),result.plannedDate());
+        assertNull(result.estimatedWarehouseArrivalAt());
+        assertTrue(result.isDefault());
+        assertEquals(result.plannedDate(),service.requiredDate("1"));
+    }
+
+    /** 人工维护优先，已生成计划后的日期不再随到港变化重新计算。 */
+    @Test void manualAndFrozenDatesNeverReadNewForecasts() {
+        var manual=LocalDateTime.of(2026,11,3,9,30);
+        when(repository.find(List.of("1","2"))).thenReturn(List.of(
+            new ContainerArrivalTimeView("1",manual,null,1,0,null,false),
+            new ContainerArrivalTimeView("2",null,null,0,1,LocalDate.of(2026,11,4),false)));
+        var result=service.resolve(List.of("1","2"));
+        assertEquals(manual.toLocalDate(),result.get(0).plannedDate());
+        assertEquals(LocalDate.of(2026,11,4),result.get(1).plannedDate());
+        assertFalse(result.get(1).isDefault());
+        verifyNoInteractions(forecasts);
+    }
+
+    /** 真实未知日期不补零点，提供方漏行也不能当作完整空事实。 */
+    @Test void unknownAndIncompleteProviderResultsBlockPlanCreation() {
+        when(repository.find(List.of("1"))).thenReturn(List.of(new ContainerArrivalTimeView("1",null,null,0,0,null,false)));
+        when(forecasts.batch(anyString(),any())).thenReturn(ApiResponse.success(List.of(
+            new AppointmentForecastClient.Forecast(1L,null,null,"SOURCE_LOCAL_UNSPECIFIED",null))));
+        assertNull(service.resolve(List.of("1")).get(0).plannedDate());
+        assertEquals(409,assertThrows(ResponseStatusException.class,()->service.requiredDate("1")).getStatusCode().value());
+        when(forecasts.batch(anyString(),any())).thenReturn(ApiResponse.success(List.of()));
+        assertEquals(503,assertThrows(ResponseStatusException.class,()->service.requiredDate("1")).getStatusCode().value());
+    }
+
+    /** 同柜版本或已建计划日期冲突时不能被默认到港算法覆盖。 */
+    @Test void inconsistentOrMissingFrozenDatesRemainBlocked() {
+        for(var row:List.of(new ContainerArrivalTimeView("1",null,null,-1,0,null,false),
+            new ContainerArrivalTimeView("1",null,null,1,0,null,false),
+            new ContainerArrivalTimeView("1",null,null,0,2,null,false))) {
+            when(repository.find(List.of("1"))).thenReturn(List.of(row));
+            assertThrows(ResponseStatusException.class,()->service.requiredDate("1"));
+        }
+        verifyNoInteractions(forecasts);
+    }
+}

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

@@ -8,7 +8,7 @@ class LastlegOrderNoGeneratorTest {
     /** 各作业类型使用不同前缀，同类型第二次调用必须递增。 */
     @Test void routesEveryOperationalTypeToItsDailySequence() {
         var generator=TestDocumentNumbers.orders();
-        Map.ofEntries(Map.entry("OUTBOUND","CK"),Map.entry("ONE_CLICK_DROPSHIP","DFCK"),
+        Map.ofEntries(Map.entry("LASTLEG","WC"),Map.entry("OUTBOUND","CK"),Map.entry("ONE_CLICK_DROPSHIP","DFCK"),
             Map.entry("RELABEL_OUTBOUND","HBCK"),Map.entry("RETURN_OUTBOUND","THCK"),
             Map.entry("DELIVERY","DL"),Map.entry("TRUCK","TR"),Map.entry("LOOSEBOARD","LB"),
             Map.entry("EXCEPTION","EX"),Map.entry("DISCARD","CD"),Map.entry("INBOUND_PLAN","IP"),
@@ -19,12 +19,4 @@ class LastlegOrderNoGeneratorTest {
             });
         assertThrows(IllegalArgumentException.class,()->generator.next("UNKNOWN"));
     }
-    /** 头程来源尾程号未纳入独立改号，保持同柜分组关系。 */
-    @Test void actualContainerNumberRemainsStableAndShared() {
-        var generator=TestDocumentNumbers.orders();
-        assertTrue(generator.forContainerNo("MSCU6639870").matches("FL-WH-\\d{8}-\\d{6}"));
-        assertEquals(generator.forContainerNo("MSCU6639870"),TestDocumentNumbers.orders().forContainerNo("MSCU6639870"));
-        assertNotEquals(generator.forContainerNo("MSCU6639870"),generator.forContainerNo("CSQU3054383"));
-        assertThrows(IllegalArgumentException.class,()->generator.forContainerNo(" "));
-    }
 }

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

@@ -117,7 +117,7 @@ class LastlegOrderServiceTest {
     void setUp() {
         com.baomidou.mybatisplus.core.metadata.TableInfoHelper.initTableInfo(
             new org.apache.ibatis.builder.MapperBuilderAssistant(new org.apache.ibatis.session.Configuration(), ""), LastlegOrder.class);
-        service = new LastlegOrderService();
+        service = new LastlegOrderService(); ReflectionTestUtils.setField(service,"warehouseArrival", new ContainerWarehouseArrivalService(new com.baiyue.lastleg.repository.ContainerWarehouseArrivalRepository(orders), org.mockito.Mockito.mock(com.baiyue.lastleg.appointmentplanning.AppointmentForecastClient.class), "test"));
         ReflectionTestUtils.setField(service, "transferQuantities", transferQuantities);
         ReflectionTestUtils.setField(service, "returnOrderReferences", returnOrderReferences);
         ReflectionTestUtils.setField(service, "orderMapper", orders);
@@ -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, 0)));
+            new ContainerArrivalTimeView("BOOKING-1", estimatedAt, null, 1, 0, estimatedAt.toLocalDate(), false)));
 
         ContainerArrivalTimeView result = service.changeExpectedWarehouseArrival("BOOKING-1", "arrival-1",
             new LastlegOrderRequests.ChangeExpectedWarehouseArrival(estimatedAt, 0, null), "admin");

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

@@ -2,11 +2,42 @@ package com.baiyue.lastleg.service;
 import com.baiyue.common.event.*; import com.baiyue.lastleg.entity.*; import com.baiyue.lastleg.mapper.*; import com.baiyue.lastleg.dropship.dto.DropshipRequests; import com.baiyue.lastleg.dropship.service.DropshipOrderService; import com.baiyue.lastleg.inboundplan.entity.InboundPlanCarton; import com.baiyue.lastleg.inboundplan.mapper.InboundPlanCartonMapper; import com.baiyue.lastleg.inventory.command.dto.InventoryCommandRequests; import com.baiyue.lastleg.inventory.command.service.InventoryCommandService; import com.fasterxml.jackson.databind.*; import org.junit.jupiter.api.*; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.*; import org.springframework.test.util.ReflectionTestUtils; import java.math.BigDecimal; import java.time.Instant; import java.util.*; import static org.junit.jupiter.api.Assertions.*; import static org.mockito.ArgumentMatchers.*; import static org.mockito.Mockito.*;
 @ExtendWith(org.mockito.junit.jupiter.MockitoExtension.class)
 class LoadingCompletedConsumerTest {
+ /** 两个来源柜复用同一实箱时仍各自取号，不能把历史箱号当本次柜身份。 */
+ @Test void reusedPhysicalContainerKeepsDistinctSourceBookingNumbers() {
+   when(sequences.next("WC")).thenReturn("WC202610210001","WC202610210002");
+   EventEnvelope first=event(); service.consume(first);
+   com.fasterxml.jackson.databind.node.ObjectNode payload=first.payload().deepCopy();
+   payload.put("containerBookingId","book-2");
+   EventEnvelope second=new EventEnvelope("123e4567-e89b-12d3-a456-426614174099",first.eventType(),first.eventVersion(),
+       first.occurredAt(),first.tenantId(),first.aggregateType(),first.aggregateId(),first.aggregateVersion(),
+       first.handoverVersion(),first.traceId(),first.correlationId(),null,payload,
+       EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(payload)));
+   service.consume(second);
+   ArgumentCaptor<LastlegOrder> captured=ArgumentCaptor.forClass(LastlegOrder.class);
+   verify(orders,times(4)).insert(captured.capture());
+   assertEquals(2,captured.getAllValues().stream().map(LastlegOrder::getOrderNo).distinct().count());
+   verify(orders).containerOrderNumbers("book-1"); verify(orders).containerOrderNumbers("book-2");
+ }
+ /** 同柜后续客户交接沿用首票编号，不再次占用日流水。 */
+ @Test void reusesTheExistingContainerNumberWithoutAllocatingAgain() {
+   when(orders.containerOrderNumbers(anyString())).thenReturn(List.of("WC202610200001"));
+   service.consume(event());
+   ArgumentCaptor<LastlegOrder> captured=ArgumentCaptor.forClass(LastlegOrder.class);
+   verify(orders,times(2)).insert(captured.capture());
+   assertTrue(captured.getAllValues().stream().allMatch(order->"WC202610200001".equals(order.getOrderNo())));
+   verify(sequences,never()).next(anyString());
+ }
+ /** 同柜身份不一致必须停止，不能挑选任一旧号继续生成订单。 */
+ @Test void rejectsConflictingContainerBusinessNumbers() {
+   when(orders.containerOrderNumbers(anyString())).thenReturn(List.of("WC202610200001","WC202610200002"));
+   assertThrows(IllegalStateException.class,()->service.consume(event()));
+   verify(orders,never()).insert(any(LastlegOrder.class));
+ }
  private final Map<String,String> frozenContainerNos=new HashMap<>();
  @Mock LastlegEventInboxMapper inbox; @Mock LastlegOrderMapper orders; @Mock LastlegInboundOrderMapper inboundOrders; @Mock LastlegOrderDetailMapper details; @Mock LastlegOrderStatusHistoryMapper histories; @Mock InboundPlanCartonMapper cartons; @Mock DropshipOrderService dropshipOrders; @Mock InventoryCommandService inventory; @Mock com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper shippingGates; @Mock com.baiyue.lastleg.inboundplan.pda.mapper.ContainerLoadingEvidenceMapper loadingEvidence; @Mock LastlegDocumentNumberGenerator sequences; ObjectMapper json=new ObjectMapper().findAndRegisterModules(); LoadingCompletedConsumer service;
- @BeforeEach void setup(){ service=new LoadingCompletedConsumer(); ReflectionTestUtils.setField(service,"inboxMapper",inbox); ReflectionTestUtils.setField(service,"orderMapper",orders); ReflectionTestUtils.setField(service,"inboundOrderMapper",inboundOrders); ReflectionTestUtils.setField(service,"detailMapper",details); ReflectionTestUtils.setField(service,"historyMapper",histories); ReflectionTestUtils.setField(service,"cartonMapper",cartons); ReflectionTestUtils.setField(service,"dropshipOrders",dropshipOrders); ReflectionTestUtils.setField(service,"inventory",inventory); ReflectionTestUtils.setField(service,"shippingGates",shippingGates); ReflectionTestUtils.setField(service,"loadingEvidence",loadingEvidence); ReflectionTestUtils.setField(service,"objectMapper",json); LastlegOrderNoGenerator generator=new LastlegOrderNoGenerator(sequences);  ReflectionTestUtils.setField(service,"orderNoGenerator",generator);  lenient().doAnswer(i->{ LastlegOrder o=i.getArgument(0); o.setId(Math.abs(o.getSourceInboundId().hashCode())+1L); return 1; }).when(orders).insert(any(LastlegOrder.class)); lenient().when(orders.lockContainerNumbers(anyString())).thenReturn(List.of()); lenient().when(shippingGates.initialize(anyString(),anyString(),anyString(),anyLong(),anyLong())).thenAnswer(i->{ String key=i.getArgument(0); String value=i.getArgument(2); return frozenContainerNos.putIfAbsent(key,value)==null?1:0; }); lenient().when(shippingGates.lock(anyString())).thenAnswer(i->{ String key=i.getArgument(0); String value=frozenContainerNos.get(key); if(value==null)return null; var gate=new com.baiyue.lastleg.shipping.entity.ContainerShippingGate(); gate.setContainerBookingId(key); gate.setContainerNo(value); return gate; }); }
-  @Test void createsPendingOrdersAndInTransitSnapshotsWithoutInboundPlans(){ EventEnvelope event=event(); assertEquals(com.baiyue.common.event.DeliveryAck.Outcome.APPLIED, service.consume(event).outcome()); assertThrows(NoSuchFieldException.class,()->LoadingCompletedConsumer.class.getDeclaredField("inboundPlans")); verify(orders,times(2)).insert(any(LastlegOrder.class)); ArgumentCaptor<InventoryCommandRequests.InTransit> inTransit=ArgumentCaptor.forClass(InventoryCommandRequests.InTransit.class); verify(inventory,times(2)).registerInTransit(eq("100"),eq("SYSTEM"),inTransit.capture()); assertEquals(Set.of("RK1","RK2"),inTransit.getAllValues().stream().map(InventoryCommandRequests.InTransit::inboundOrderNo).collect(java.util.stream.Collectors.toSet())); verify(details,times(2)).insert(any(LastlegOrderDetail.class)); verify(histories,times(2)).insert(any(LastlegOrderStatusHistory.class)); ArgumentCaptor<LastlegOrder> c=ArgumentCaptor.forClass(LastlegOrder.class); verify(orders,times(2)).insert(c.capture()); assertEquals(Set.of("in-1","in-2"),c.getAllValues().stream().map(LastlegOrder::getSourceInboundId).collect(java.util.stream.Collectors.toSet())); assertTrue(c.getAllValues().stream().allMatch(o->"PENDING_ASSIGNMENT".equals(o.getCurrentStatus()))); assertTrue(c.getAllValues().stream().allMatch(o->o.getInboundOrderNo()==null)); assertTrue(c.getAllValues().stream().allMatch(o->o.getId()!=null)); assertTrue(c.getAllValues().stream().allMatch(o->"MSCU6639870".equals(o.getContainerNo()))); assertTrue(c.getAllValues().stream().allMatch(o->"FBA".equals(o.getDestinationType()))); assertTrue(c.getAllValues().stream().allMatch(o->"Customer 100".equals(o.getCustomerName()))); assertTrue(c.getAllValues().stream().allMatch(o->"ow-1".equals(o.getSourceWarehouseId())&&"193000000000200003".equals(o.getOverseasWarehouseId())&&"US-LAX-01".equals(o.getOverseasWarehouseCode())&&"洛杉矶仓".equals(o.getOverseasWarehouseName())&&Integer.valueOf(0).equals(o.getReceivingWarehouseVersion()))); ArgumentCaptor<LastlegInboundOrder> snapshots=ArgumentCaptor.forClass(LastlegInboundOrder.class); verify(inboundOrders,times(2)).insert(snapshots.capture()); assertTrue(snapshots.getAllValues().stream().allMatch(o->"100".equals(o.getCustomerId())&&"FBA".equals(o.getDestinationType()))); assertEquals(1,c.getAllValues().stream().map(LastlegOrder::getOrderNo).distinct().count()); assertTrue(c.getAllValues().get(0).getOrderNo().matches("FL-WH-[0-9]{8}-[0-9]{6}")); }
-  @Test void oneContainerWith15InboundRowsSharesOneStableContainerOrderNumber(){ EventEnvelope source=event(); com.fasterxml.jackson.databind.node.ObjectNode node=source.payload().deepCopy(); com.fasterxml.jackson.databind.node.ArrayNode rows=json.createArrayNode(); for(int index=1;index<=15;index++){ com.fasterxml.jackson.databind.node.ObjectNode row=node.path("orders").get(0).deepCopy(); row.put("sourceInboundId","in-"+index).put("rootInboundId","root-"+index).put("sourceOrderId","order-"+index).put("sourceOrderNo","FL-"+index).put("rootOrderId","root-order-"+index).put("inboundCode","RK-"+index); rows.add(row); } node.set("orders",rows); String hash=EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(node)); EventEnvelope fifteen=new EventEnvelope("123e4567-e89b-12d3-a456-426614174015",source.eventType(),source.eventVersion(),source.occurredAt(),source.tenantId(),source.aggregateType(),source.aggregateId(),source.aggregateVersion(),source.handoverVersion(),source.traceId(),source.correlationId(),source.causationId(),node,hash); assertEquals(com.baiyue.common.event.DeliveryAck.Outcome.APPLIED, service.consume(fifteen).outcome()); ArgumentCaptor<LastlegOrder> captured=ArgumentCaptor.forClass(LastlegOrder.class); verify(orders,times(15)).insert(captured.capture()); assertEquals(1,captured.getAllValues().stream().map(LastlegOrder::getOrderNo).distinct().count()); assertTrue(captured.getAllValues().get(0).getOrderNo().matches("^FL-WH-\\d{8}-\\d{6}$")); verifyNoInteractions(sequences); }
+ @BeforeEach void setup(){ service=new LoadingCompletedConsumer(); ReflectionTestUtils.setField(service,"inboxMapper",inbox); ReflectionTestUtils.setField(service,"orderMapper",orders); ReflectionTestUtils.setField(service,"orderNumbers",new com.baiyue.lastleg.repository.LastlegOrderNumberRepository(orders)); lenient().when(sequences.next("WC")).thenReturn("WC202610210001"); ReflectionTestUtils.setField(service,"inboundOrderMapper",inboundOrders); ReflectionTestUtils.setField(service,"detailMapper",details); ReflectionTestUtils.setField(service,"historyMapper",histories); ReflectionTestUtils.setField(service,"cartonMapper",cartons); ReflectionTestUtils.setField(service,"dropshipOrders",dropshipOrders); ReflectionTestUtils.setField(service,"inventory",inventory); ReflectionTestUtils.setField(service,"shippingGates",shippingGates); ReflectionTestUtils.setField(service,"loadingEvidence",loadingEvidence); ReflectionTestUtils.setField(service,"objectMapper",json); LastlegOrderNoGenerator generator=new LastlegOrderNoGenerator(sequences);  ReflectionTestUtils.setField(service,"orderNoGenerator",generator);  lenient().doAnswer(i->{ LastlegOrder o=i.getArgument(0); o.setId(Math.abs(o.getSourceInboundId().hashCode())+1L); return 1; }).when(orders).insert(any(LastlegOrder.class)); lenient().when(orders.lockContainerNumbers(anyString())).thenReturn(List.of()); lenient().when(shippingGates.initialize(anyString(),anyString(),anyString(),anyLong(),anyLong())).thenAnswer(i->{ String key=i.getArgument(0); String value=i.getArgument(2); return frozenContainerNos.putIfAbsent(key,value)==null?1:0; }); lenient().when(shippingGates.lock(anyString())).thenAnswer(i->{ String key=i.getArgument(0); String value=frozenContainerNos.get(key); if(value==null)return null; var gate=new com.baiyue.lastleg.shipping.entity.ContainerShippingGate(); gate.setContainerBookingId(key); gate.setContainerNo(value); return gate; }); }
+  @Test void createsPendingOrdersAndInTransitSnapshotsWithoutInboundPlans(){ EventEnvelope event=event(); assertEquals(com.baiyue.common.event.DeliveryAck.Outcome.APPLIED, service.consume(event).outcome()); assertThrows(NoSuchFieldException.class,()->LoadingCompletedConsumer.class.getDeclaredField("inboundPlans")); verify(orders,times(2)).insert(any(LastlegOrder.class)); ArgumentCaptor<InventoryCommandRequests.InTransit> inTransit=ArgumentCaptor.forClass(InventoryCommandRequests.InTransit.class); verify(inventory,times(2)).registerInTransit(eq("100"),eq("SYSTEM"),inTransit.capture()); assertEquals(Set.of("RK1","RK2"),inTransit.getAllValues().stream().map(InventoryCommandRequests.InTransit::inboundOrderNo).collect(java.util.stream.Collectors.toSet())); verify(details,times(2)).insert(any(LastlegOrderDetail.class)); verify(histories,times(2)).insert(any(LastlegOrderStatusHistory.class)); ArgumentCaptor<LastlegOrder> c=ArgumentCaptor.forClass(LastlegOrder.class); verify(orders,times(2)).insert(c.capture()); assertEquals(Set.of("in-1","in-2"),c.getAllValues().stream().map(LastlegOrder::getSourceInboundId).collect(java.util.stream.Collectors.toSet())); assertTrue(c.getAllValues().stream().allMatch(o->"PENDING_ASSIGNMENT".equals(o.getCurrentStatus()))); assertTrue(c.getAllValues().stream().allMatch(o->o.getInboundOrderNo()==null)); assertTrue(c.getAllValues().stream().allMatch(o->o.getId()!=null)); assertTrue(c.getAllValues().stream().allMatch(o->"MSCU6639870".equals(o.getContainerNo()))); assertTrue(c.getAllValues().stream().allMatch(o->"FBA".equals(o.getDestinationType()))); assertTrue(c.getAllValues().stream().allMatch(o->"Customer 100".equals(o.getCustomerName()))); assertTrue(c.getAllValues().stream().allMatch(o->"ow-1".equals(o.getSourceWarehouseId())&&"193000000000200003".equals(o.getOverseasWarehouseId())&&"US-LAX-01".equals(o.getOverseasWarehouseCode())&&"洛杉矶仓".equals(o.getOverseasWarehouseName())&&Integer.valueOf(0).equals(o.getReceivingWarehouseVersion()))); ArgumentCaptor<LastlegInboundOrder> snapshots=ArgumentCaptor.forClass(LastlegInboundOrder.class); verify(inboundOrders,times(2)).insert(snapshots.capture()); assertTrue(snapshots.getAllValues().stream().allMatch(o->"100".equals(o.getCustomerId())&&"FBA".equals(o.getDestinationType()))); assertEquals(1,c.getAllValues().stream().map(LastlegOrder::getOrderNo).distinct().count()); assertTrue(c.getAllValues().get(0).getOrderNo().matches("WC[0-9]{8}[0-9]{4}")); }
+  @Test void oneContainerWith15InboundRowsSharesOneStableContainerOrderNumber(){ EventEnvelope source=event(); com.fasterxml.jackson.databind.node.ObjectNode node=source.payload().deepCopy(); com.fasterxml.jackson.databind.node.ArrayNode rows=json.createArrayNode(); for(int index=1;index<=15;index++){ com.fasterxml.jackson.databind.node.ObjectNode row=node.path("orders").get(0).deepCopy(); row.put("sourceInboundId","in-"+index).put("rootInboundId","root-"+index).put("sourceOrderId","order-"+index).put("sourceOrderNo","FL-"+index).put("rootOrderId","root-order-"+index).put("inboundCode","RK-"+index); rows.add(row); } node.set("orders",rows); String hash=EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(node)); EventEnvelope fifteen=new EventEnvelope("123e4567-e89b-12d3-a456-426614174015",source.eventType(),source.eventVersion(),source.occurredAt(),source.tenantId(),source.aggregateType(),source.aggregateId(),source.aggregateVersion(),source.handoverVersion(),source.traceId(),source.correlationId(),source.causationId(),node,hash); assertEquals(com.baiyue.common.event.DeliveryAck.Outcome.APPLIED, service.consume(fifteen).outcome()); ArgumentCaptor<LastlegOrder> captured=ArgumentCaptor.forClass(LastlegOrder.class); verify(orders,times(15)).insert(captured.capture()); assertEquals(1,captured.getAllValues().stream().map(LastlegOrder::getOrderNo).distinct().count()); assertTrue(captured.getAllValues().get(0).getOrderNo().matches("^WC\\d{8}\\d{4}$")); verify(sequences).next("WC"); }
   @Test void rejectsMissingOwnerSnapshotBeforeAnyLastlegWrite(){ EventEnvelope source=event(); com.fasterxml.jackson.databind.node.ObjectNode node=source.payload().deepCopy(); ((com.fasterxml.jackson.databind.node.ObjectNode)node.path("orders").get(0)).put("customerName"," "); String hash=EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(node)); EventEnvelope missing=new EventEnvelope(source.eventId(),source.eventType(),source.eventVersion(),source.occurredAt(),source.tenantId(),source.aggregateType(),source.aggregateId(),source.aggregateVersion(),source.handoverVersion(),source.traceId(),source.correlationId(),source.causationId(),node,hash); IllegalArgumentException error=assertThrows(IllegalArgumentException.class,()->service.consume(missing)); assertTrue(error.getMessage().contains("尾程事件负载无效")||error.getMessage().contains("货主快照")); verify(inbox,never()).insert(any(LastlegEventInbox.class)); verify(orders,never()).insert(any(LastlegOrder.class)); }
  @Test void freezesFormalPlannedWarehouseArrivalFromLoadingEvent(){ EventEnvelope source=event(); JsonNode node=source.payload().deepCopy(); ((com.fasterxml.jackson.databind.node.ObjectNode)node).put("estimatedWarehouseArrivalAt","2026-10-03T09:00"); String hash=EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(node)); EventEnvelope changed=new EventEnvelope(source.eventId(),source.eventType(),source.eventVersion(),source.occurredAt(),source.tenantId(),source.aggregateType(),source.aggregateId(),source.aggregateVersion(),source.handoverVersion(),source.traceId(),source.correlationId(),source.causationId(),node,hash); service.consume(changed); ArgumentCaptor<LastlegOrder> captor=ArgumentCaptor.forClass(LastlegOrder.class); verify(orders,times(2)).insert(captor.capture()); assertTrue(captor.getAllValues().stream().allMatch(order->java.time.LocalDateTime.of(2026,10,3,9,0).equals(order.getEstimatedWarehouseAt()))); }
  @Test void loadingCreatesAwaitingPickupReadyGateWithoutPollutingShippingVersion(){ service.consume(event()); verify(shippingGates).initialize("book-1","","MSCU6639870",0L,1L); }

scripts/README.md

@@ -1,5 +1,7 @@
 # 后端脚本管理与全量 HTTP 验收索引
 
+`procurement-sample-test-env.mjs` 复用固定客户后只读取钱包，不再创建充值流水；执行前要求现有可用余额至少 3 元（货款 1 元加运费冻结 2 元），不足或余额字段异常即停止。仍会创建本轮采购业务与附件，不复用历史完成单据。
+
 `dispatch-loading-flow-test-env.mjs` 是 TEST 固定客户两托一车的定向 HTTP 验收入口，验证实收入库、确认预约、审核、扫码拣货、五张装车图片的 Admin 读取、自动出库派送及原请求幂等。默认只预览；显式 `--execute --run-id <唯一标识> --warehouse-id <起运仓> --destination-warehouse-id <FBA仓> --test-image <明确标注TEST的PNG>` 写入业务测试记录，通过 `node --env-file="<统一TEST配置>"` 读取凭据和固定客户。报告位于 `reports/dispatch-loading-<run-id>/`，保留失败前的请求和业务数据；同标识拒绝重跑，先核对原请求再决定恢复。`--resume-report <原报告>` 仅用于已明确收到编辑 A0400、仍为零拣货草稿的原单，保留原车与原司机，回查状态后补齐编辑字段继续；未知写入结果不能使用此恢复入口。默认停用本次临时 PDA 账号；`--keep-pda-for-ui` 仅在成功后将临时登录资料保存到系统临时目录供页面验收，页面结束后必须停用账号。所有 HTTP 会话结束时注销，不执行 SQL、删除、重置或部署。新增入口验证运行语法检查和 `script-documentation-contract.test.mjs`，经 `local-check.ps1`。
 
 Admin/Client TEST 回归统一配置 `ADMIN_TEST_FIXED_CUSTOMER_ID` 与 `MERCHANT_TEST_USERNAME/PASSWORD`，复用指定 ACTIVE 客户；独立 Admin runner 同样读取这些显式环境变量。Client 默认不再注册审核、修改固定客户资料/账号、创建成员角色或通知，也不运行余额/渠道共享配置及缺第二客户的隔离场景；这些范围列为 skipped，`fullCoverage=false`，执行范围通过不代表全量覆盖。Admin 排除的主档生命周期范围见模块 README。业务单据及附件仍按本轮证据需要新增；不自动清理历史记录。

scripts/admin-test-env-acceptance.mjs

@@ -642,6 +642,9 @@ export class AcceptanceRun {
       this.options.fixedCustomerId ||= process.env.ADMIN_TEST_FIXED_CUSTOMER_ID || ''
       this.options.merchantUsername ||= process.env.MERCHANT_TEST_USERNAME || ''
       this.options.merchantPassword ||= process.env.MERCHANT_TEST_PASSWORD || ''
+      this.options.fixedPdaActors ??= JSON.parse(process.env.ADMIN_TEST_OVERSEAS_PDA_ACTORS || '[]')
+      this.options.fixedDomesticDenyActor ??= JSON.parse(process.env.ADMIN_TEST_DOMESTIC_DENY_ACTOR || 'null')
+      this.options.fixedFleetResources ??= JSON.parse(process.env.ADMIN_TEST_FLEET_RESOURCES || '[]')
     }
     const markerNamespace = String(options.markerNamespace || '').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 12)
     this.marker = `${options.environment === 'gray' ? 'GRAY' : 'ADMIN'}-API-${new Date().toISOString().replace(/\D/g, '').slice(0, 17)}${markerNamespace ? `-${markerNamespace}` : ''}`
@@ -665,6 +668,7 @@ export class AcceptanceRun {
     if (this.options.environment !== 'test') return
     const pathname = new URL(path, 'https://acceptance.invalid').pathname.replace(/\/$/, '')
     if (String(method).toUpperCase() === 'POST' && (pathname === '/api/platform/v1/iam/tenants'
+      || pathname === '/api/auth/register'
       || /^\/api\/platform\/v1\/iam\/tenants\/[^/]+\/(archive|submit-review)$/.test(pathname))) {
       throw new Error('TEST 固定客户模式禁止创建、归档客户或重提资质；请复用已配置客户')
     }

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

@@ -1,5 +1,17 @@
 # Admin 测试环境 HTTP 模块
 
+固定客户车队履约通过显式环境文件的 `ADMIN_TEST_FLEET_RESOURCES` JSON 数组配置已有资源，每项为 `vehicleId`、`driverId`（十进制字符串）。助手只读核验海外自有在役车辆、已审核启用司机及截至预期任务结束的派车资格，不创建车辆/司机、不上传或重审证照。当前 runner 中尚未完成资源释放的组合不得重复分配；全部占用或缺配置直接阻断，失败资源保持占用待排查。复用车辆按审核后真实车牌查询，并以本轮排车号核对唯一 Fleet 绑定，不能把历史同车次记录当作当前证据。跨 runner 仍须串行，真实占用、仓与容量由正式分配接口最终校验。本规则不减少必要的业务排车与履约证据，也不覆盖车辆或司机主档生命周期。
+
+国内整柜权限拒绝探针通过显式环境文件的 `ADMIN_TEST_DOMESTIC_DENY_ACTOR` JSON 对象配置 `membershipId`、`username`、`password`。固定客户模式在业务写入前核对既有 ACTIVE 平台账号及实际 A0403 拒绝响应，结束退出本轮会话；缺配置或权限不符直接阻断，不创建角色、账号或重置密码。实际凭据不得写入仓库或报告。
+
+固定 PDA 账号取得会话后即占用；权限核验失败也检查退出结果。退出被拒绝或请求异常会记录失败并保留占用，禁止本轮再次分配该账号，同时继续尝试退出其他账号。不将退出未知结果视为清理成功。
+
+固定海外 PDA 账号池通过显式环境文件的 `ADMIN_TEST_OVERSEAS_PDA_ACTORS` JSON 数组配置，每项为 `membershipId`、`warehouseId`、`username`、`password`，不得将实际值写入仓库或报告。同仓双操作员场景需要两个不同账号；当前 runner 按 membershipId 占用并在退出会话成功后释放。使用前核对 ACTIVE、平台身份、PDA 角色及仓绑定；缺失或不匹配直接阻断，不创建或修复账号。复用账号只注销本轮会话，不停用、不改绑、不清空角色；仓绑定撤销生命周期明确列为未验收。该占用只在当前 runner 内有效，仍须遵守共享环境造数串行规则。
+
+固定客户下，报关、装柜、订舱级拖车和车队报价复用启用供应商；按 CUSTOMS/BOOKING/TRUCKING 类别、MATSON 船司及国内/海外拖车范围核验列表和详情。缺少匹配供应商时阻断，不自动创建或重新启用；车队报价结束只停用本轮报价，不停用复用供应商。
+
+固定客户模式下，PDA 换标只核验现有可用余额至少 0.01 元（本场景换标费用），不自动补款；采购样本专项要求现有可用余额至少 3 元（货款 1 元加运费冻结 2 元），不自动充值。海外采购合作仓从正式候选复用，退出时不得停用复用仓。固定客户及本轮入仓计划查询覆盖后续分页；混托专项缺第二固定客户时，在首次下单和测量前阻断。以上前置检查不替代服务端执行时的实时余额、资格与版本校验。
+
 固定客户编排也将 `customers`、`supplemental-boundaries` 明确记为跳过，不运行建客或边界仓库/库位生命周期。Finance 供应商按启用状态与费用类别查询复用，详情变化或无候选时阻断，不补建；海外入仓费用只允许关联本轮 PDA `generatedPlanIds` 内且客户、批次均匹配的计划，禁止回退历史计划。混合报关柜缺第二固定客户时在准备订单和装柜前阻断。
 
 固定客户模式下，默认编排排除 `system`、`master-data`、`suppliers`、`notifications`、`pricing`、`phase4-overseas-master-data`、`phase4-overseas-wallet-and-pallet-cost` 的生命周期写入，报告使用 skipped 和 coverage gap，不计模块通过。海外仓模块复用现有仓及只读资源，缺仓直接阻断；不自动创建库位/托盘。业务订单与履约证据仍按批次创建，不能将历史已完成单据当作本轮新证据。其他业务模块内嵌的权限探针账号及专用业务资源仍可能创建，当前模式不代表零新增数据。
@@ -78,7 +90,7 @@ OCR模块必须通过`ADMIN_TEST_OCR_IMAGE`显式指定本轮图片，不依赖
 
 头程提交、平台编辑与取消按首次原始详情版本冻结请求。原键原载荷重放成功；同键异载荷、旧版本及新键重复操作分别核验拒绝后事实不变。Platform 编辑使用平台权限与显式客户范围，客户 Token 不得调用。
 
-`fleet-trip-fulfillment.mjs` 是内部整车验收助手，不是独立入口。一张原生排车单对应一趟车；五期与F40通过正式API维护本轮车辆、司机及证照，提交并通过调度/理货两级审核，再读取该排车唯一自动生成的Fleet资源记录。PDA拣货核平后，显式确认装车完成，再由平台安排全车客户目的地派送，最后使用当前主单版本发车；不再独立创建、绑定或审核Fleet车次。实载托位、重量、体积及卸货站须有本轮真实来源证据，不能使用计费量或固定值；ID和版本无损保留，Long箱数字符串仅在安全数量边界归一化。资源及文件ID留在报告，失败保留原命令。直接调用者也须同步消费原生DTO及该顺序；合同通过不代表HTTP或PDA硬件验收。
+`fleet-trip-fulfillment.mjs` 是内部整车验收助手，不是独立入口。一张原生排车单对应一趟车；通过正式 API 准备资源与两级审核，读取唯一自动生成的 Fleet 记录。PDA 拣货及来源核验通过后，读取本车五个装车照片框，复用已保存文件，仅为缺失框上传标明 TEST 的合成 PNG，再绑定、原键重放并回读；上传前保存检查点与文件摘要，未知结果停写，不自动重新上传。照片在 LOADING 保存不得提前发车；AFTER_LOADING 最后一个缺失框保存后须进入 DELIVERING。资料齐全后重新读取主单资格与实载清单，再确认装车并核对自动生成的派送，不再调用手工安排派送或发车。实载数据由服务端返回，重量和体积缺失保持未知，不以请求中的测量值或计费量替代。PDA 上传及绑定始终保留原账号会话；ID 和版本无损保留，资源及文件留在报告。直接调用者须消费当前 DTO；离线合同通过不代表真实 HTTP、实物照片或 PDA 硬件验收。
 
 `prepareFleetTrip` 对零扫码的装车中排车，须先显式退回装车前再维护资源并重走两级审核；已扫码时不能重排。`confirmFleetLoading` 验证已扫码编辑被拒绝且主单与实际货物零漂移，然后按真实装载预览/实测回执发送装车完成命令；PDA成功后，平台使用同一原键原载荷重放，必须保持原结果和版本。报告`createdResources.fleetTrips[].reassignment`保留原请求、前后快照及拒绝证据；未知写结果停止，不自动换键重造。装车返回版本不替代发车前重新读取的公共版本。
 
@@ -257,7 +269,7 @@ export async function run(context) {
 | 仓储转运审核 | `phase4-overseas-client-services` 调用内部 `warehouse-transfer-review.mjs` | 本轮资质客户 Token、PDA 完成柜来源订单；另通过客户 API 创建独立新到仓转运对照票 | 平台显式 customerId；客户 Token 无审核权限；缺作用域/非法决定拒绝且状态不漂移；已有库存 APPROVED/PENDING_ASSIGNMENT；新到仓 APPROVE→WAIT_PDA_RECEIVING/WAIT_DELIVERY，REJECT→REJECTED/CANCELLED；同决定重放、反向审核冲突、客户详情回查；空驳回原因应 A0400 并保持待审核 |
 | 智能预排真实草稿柜 | `phase4-overseas-dispatch` | `phase4-overseas-pda-operations` 后本轮实际收货托盘 | 草稿柜创建、明确 draftContainerId 绑定、结构回查、unlock 恢复候选、删除柜释放锁、重建柜预排；保留同草稿重锁、其他草稿冲突、旧载荷预排冲突与 release 合同 |
 | 排车托盘移除 | `phase4-overseas-dispatch` | 同一本轮托盘先创建独立移除对照排车，移除后才进入主链预排 | DELETE 明细后箱数/托数/明细归零；重复删除 A0404；正式锁释放后候选恢复。空对照排车保留，不借历史排车 |
-| 排车编辑、BOL、后台转派送 | `phase5-overseas-fulfillment` | `phase4-overseas-dispatch` 生成的主链排车 | 复用车辆编辑和客户转派送；新增 BOL content-type 与 %PDF- 签名检查；后台同载荷转派送复用同一出库/派送业务号；生成出库后移除托盘 A0409 且数量和身份不漂移；原 PDA 拣货/发车、派送、异常和回访继续执行 |
+| 排车编辑、BOL、自动派送 | `phase5-overseas-fulfillment` | 本轮主链排车 | 核对车辆编辑、BOL 文件、PDA 拣货、五框资料及装车自动生成出库/派送；双端回读阶段版本、客户归属和数量，库存与 SHIP 零重复扣减；继续逐单签收、异常和回访 |
 | 退货签收与合箱 | `phase4-overseas-return-receipt` | 本轮退货预报及临时 PDA，不使用历史100单 | 已有分批签收、超收、幂等、数量守恒、库存与计费批次、合箱；不重复编排 |
 | PDA 收货、换标托盘及采购资金 | `phase4-overseas-pda`、`phase4-overseas-pda-operations`、`phase4-overseas-wallet-and-pallet-cost` | 原本轮收货与钱包前置 | 复用已有收货、换标拆托、出库衔接和采购冻结/结算/释放，不新增旁路写库 fixture |
 
@@ -320,7 +332,7 @@ export async function run(context) {
 | 海外业务 HTTP：采购创建/备注/审核边界，卡车与散板状态及取消 | `phase4-overseas-business.mjs` | `phase4-overseas-business-contract.test.mjs` |
 | 海外主数据 HTTP 生命周期 | `phase4-overseas-master-data.mjs`；车辆新建、详情、修改及列表均核对实际托位/载重/容积，修改使用不同容量值，CSV 同时核对修改后的值与业务车牌号；缺失或猜测容量形成阻断，finally 停用本轮资源。内部助手 `vehicle-care.mjs` 验证保养/加油创建重放、版本冲突、历史、单位、照片重放和字节下载，并逐类验证维修/故障/救援/异常项目地点回显、处理人、完成处理及费用/付款独立；另建本轮车辆验证跨车读取/修改/照片拒绝，结束停用隔离车辆并保留记录。报告在 `phase4OverseasMasterData.vehicle.care`，错误地以处理完成推定付款必须阻断；无SQL或旧数据修复，不作独立入口 | `phase4-overseas-master-data-contract.test.mjs` |
 | 目的港码头拖车与船节点终态 | `phase5-terminal-drayage.mjs`（PDA 卸柜前复用 `ACTIVE + TRUCKING + truckingScope=OVERSEAS` 主数据完成选车队、预约和实际提柜，卸柜后完成实际还柜，并覆盖四命令幂等/历史）、`phase4-carrier-nodes.mjs`（PDA 前补录至 `PICKUP_READY`；拖车完成后只读核验 `PICKED_UP/EMPTY_RETURNED` 和停止语义） | `phase5-terminal-drayage-contract.test.mjs`、`phase4-carrier-nodes-contract.test.mjs`；不再由船节点脚本直接伪造提柜和还柜 |
-| 海外排车、出库、派送、异常与回访 HTTP 生命周期 | `phase5-overseas-fulfillment.mjs`（复用本轮海外仓已收货托盘和预排单，正式创建临时 PDA 操作员并在 `finally` 停用；覆盖排车编辑、按 FBA 目的仓转出库/拆分派送单、PDA 全量拣货/发车、逐单签收资料保存自动完成、头程入仓与订单跨区回推、客户回访、人工异常及派送退回） | `phase5-overseas-fulfillment-contract.test.mjs` |
+| 海外排车、出库、派送、异常与回访 HTTP 生命周期 | `phase5-overseas-fulfillment.mjs`（本轮已收货托盘和排车，PDA 拣货、资料齐全后装车自动发车、只读单据守恒、签收与回推；固定 PDA 账号退出会话） | `phase5-overseas-fulfillment-contract.test.mjs` |
 | 初始化基线（仅离线） | — | `initialization-baseline-contract.test.mjs` |
 
 `phase4-overseas-inbound-operations.mjs` 的内部 `prepareAppointmentFixture` 可由已核对的本轮最小正式 API 流程复用：必须传入真实转换所得的入仓计划和同仓明细，至少两箱才执行拆分合并；两箱验证 `2 → 1 + 1 → 2`，不补造货量。完整 Admin 模块仍按上表四箱参数及统一依赖运行，不能为缩减造数而伪造生产者矩阵或跳过前置事实。
@@ -347,7 +359,7 @@ node scripts/admin-test-env-acceptance.mjs --gateway <test-gateway> --modules ph
 
 只有已登记在 `../admin-test-env-acceptance.mjs` 的 `CONFIGURED_MODULES` 中的名称才能用于 `--modules`；目录中存在同名 `.mjs` 不代表总入口已注册。新增或改名 HTTP 模块时必须同步总入口、依赖展开、离线入口合同和本表；尚未注册的实验脚本不得写成可执行验收入口。
 
-海外仓出库与派送履约链定向入口为 `--modules phase5-overseas-fulfillment`。依赖展开固定从本轮国内货柜履约装柜完成、海外仓业务跨区接柜和海外 PDA 实收入库生成真实库存，再由海外仓业务智能预排创建 marker 专属 `PENDING_DEPARTURE` 排车。海外仓出库与派送模块只消费该本轮排车，先补齐车辆与司机，原子转为一张 `WAIT_OUTBOUND` 出库单和按 FBA 目的仓拆分的 `WAIT_DELIVERY` 派送单，随后使用绑定同一海外仓的临时 PDA 身份执行全量拣货和发车，使出库单进入 `OUTBOUNDED`；最后逐张派送单保存签收文件自动完成，轮询核对头程入仓单与统一订单跨区回推，并覆盖回访、人工异常与退回海外仓。所有幂等重放都核对业务单号或数量不漂移，真实前置不足必须形成 deployment blocker，临时 PDA 身份无论成功失败都由正式 IAM 状态接口停用。
+海外仓出库与派送履约链定向入口为 `--modules phase5-overseas-fulfillment`，只消费本轮国内装柜、海外接柜与 PDA 实收形成的排车和库存。正式资源及两级审核就绪后，由绑定同仓的 PDA 逐来源拣货，补齐五框装车资料，再确认装车；服务端自动生成客户出库与派送并发车。五期、F40、运力池和保留样本专项统一使用 `readAutomaticDispatchDelivery`、`verifyAutomaticDeparture` 只读核对单据、双端阶段/版本及客户数量，禁止重复调用手工转派送或发车。装车重放由共享助手核验，之后独立回查库存和 SHIP 不重复扣减，再逐单签收并验证头程回推。固定账号只退出本轮会话；非固定专项账号按原生命周期清理。前置不足明确失败，不能借历史单据冒充本轮自动发车。
 
 该模块同时核对拣货、发车和重放期间库存及 SHIP 流水只扣一次；同一派送退回异常经接收、证据上传、处理完成后必须生成真实恢复库存及 `RETURN_STOCK_IN` 流水，原键重放不重复入账。PROCESSING 续跑必须保留原异常、原目标托盘、原证据和幂等键，缺失即阻断，不另建异常替代。客户签收文件验证下载真实字节，并通过本轮独立 SIGNED-B 客户验证隔离，凭据不入报告。分片完成门禁只接受同一订单的多个有效入仓分片；不同订单、多目的仓或已经完成的分片不能代替此条件，缺少生产者时仍报告覆盖阻断。
 

scripts/admin-test-env-modules/domestic-container-contract.test.mjs

@@ -3,6 +3,30 @@ import assert from 'node:assert/strict'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { verifyPermissionDenial } from './domestic-container.mjs'
+
+test('fixed denial actor never creates, resets or disables accounts and always logs out', async () => {
+  for (const deniedCode of ['A0403', '200']) {
+    const calls = []
+    const actor = { membershipId: '123', username: 'deny-fixture', password: 'fixture-password' }
+    const context = { options: { fixedCustomerId: '456', fixedDomesticDenyActor: actor },
+      async request(method, path) {
+        calls.push({ method, path })
+        const data = path.includes('/iam/users?') ? { total: 1, records: [{ ...actor, tenantId: '0', status: 'ACTIVE' }] }
+          : path === '/api/auth/login' ? { accessToken: 'fixture-token', refreshToken: 'fixture-refresh' } : {}
+        return { http: 200, body: { code: path.includes('/inventories?') ? deniedCode : '200', data }, requestId: 'test', traceId: 'test' }
+      }, apiSuccess(_module, _label, response) { return response.body.data }, assert() {},
+    }
+    if (deniedCode === 'A0403') await verifyPermissionDenial(context, 'RUN', '789', 'CONTAINER')
+    else await assert.rejects(verifyPermissionDenial(context, 'RUN', '789', 'CONTAINER'), /实际权限不符/)
+    assert.equal(calls.at(-1).path, '/api/auth/logout')
+    assert.ok(calls.every(call => call.method === 'GET' || ['/api/auth/login', '/api/auth/logout'].includes(call.path)))
+  }
+})
+
+test('missing fixed denial account blocks without requesting a phone or making HTTP calls', async () => {
+  await assert.rejects(verifyPermissionDenial({ options: { fixedCustomerId: '123' } }, 'RUN', '789', 'CONTAINER'), /禁止自动创建/)
+})
 
 const here = path.dirname(fileURLToPath(import.meta.url))
 const moduleSource = fs.readFileSync(path.join(here, 'domestic-container.mjs'), 'utf8')

scripts/admin-test-env-modules/domestic-container.mjs

@@ -131,6 +131,7 @@ export async function run(context) {
   if (!warehouse) throw new Error('缺少启用的平台国内仓，整柜验收无法继续')
   const warehouseId = id(warehouse.id)
   const containerNo = `DCA${marker}`.slice(0, 32).toUpperCase()
+  if (context.options?.fixedCustomerId) await verifyPermissionDenial(context, marker, warehouseId, containerNo)
   const now = new Date().toISOString().slice(0, 19)
 
   await verifyValidationBoundaries(context, warehouseId, marker, now)
@@ -222,11 +223,38 @@ export async function run(context) {
 
   await verifyExtendedInventoryScenarios(context, warehouseId, marker, now)
 
-  await verifyPermissionDenial(context, marker, warehouseId, containerNo)
+  if (!context.options?.fixedCustomerId) await verifyPermissionDenial(context, marker, warehouseId, containerNo)
   context.createdResources.domesticContainer = { warehouseId, inventoryId, containerNo, permissions: PERMISSIONS }
 }
 
-async function verifyPermissionDenial(context, marker, warehouseId, containerNo) {
+export async function verifyPermissionDenial(context, marker, warehouseId, containerNo) {
+  if (context.options?.fixedCustomerId) {
+    const actor = context.options.fixedDomesticDenyActor
+    if (!actor?.username || !actor.password || !/^[1-9]\d*$/.test(id(actor.membershipId))) {
+      throw Error('缺少固定整柜权限拒绝账号，禁止自动创建用户或角色')
+    }
+    let user
+    for (let page = 1; ; page++) {
+      const response = await context.request('GET', `/api/platform/v1/iam/users?page=${page}&size=100&keyword=${encodeURIComponent(actor.username)}`)
+      const result = context.apiSuccess(MODULE, '查询固定权限拒绝账号', response)
+      user = result?.records?.find(item => id(item.membershipId) === id(actor.membershipId) && item.username === actor.username)
+      if (user || !result?.records?.length || page * Number(result.size || 100) >= Number(result.total || 0)) break
+    }
+    if (user?.status !== 'ACTIVE' || id(user.tenantId) !== '0') throw Error('固定权限拒绝账号必须为启用的平台账号')
+    const login = await context.request('POST', '/api/auth/login', { loginId: actor.username, password: actor.password }, '')
+    const session = context.apiSuccess(MODULE, '登录固定权限拒绝账号', login)
+    if (!session?.accessToken || !session.refreshToken) throw Error('固定权限拒绝账号未返回完整会话')
+    try {
+      const denied = await context.request('GET', `${BASE}/inventories?page=1&size=20&warehouseId=${warehouseId}&containerNo=${containerNo}`, undefined, session.accessToken)
+      expectCode(context, '固定无整柜权限用户被拒绝', denied, 'A0403')
+      if (denied.http !== 200 || String(denied.body?.code) !== 'A0403') throw Error('固定探针账号实际权限不符，停止整柜造数')
+    } finally {
+      const logout = await context.request('POST', '/api/auth/logout', { refreshToken: session.refreshToken }, session.accessToken)
+      context.apiSuccess(MODULE, '退出固定权限拒绝账号会话，不停用账号或角色', logout)
+      if (!succeeded(logout)) throw Error('固定权限拒绝账号退出失败')
+    }
+    return
+  }
   const phone = await context.findAvailablePhone(MODULE)
   const roleCode = `DC_DENY_${marker}`.slice(0, 64)
   const username = `dc_deny_${marker}`.slice(0, 64).toLowerCase()

scripts/admin-test-env-modules/dropship-mixed-palletization-contract.test.mjs

@@ -1,6 +1,11 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
+import { run } from './dropship-mixed-palletization.mjs'
+
+test('single fixed customer blocks before first order or measurement', async () => {
+  await assert.rejects(run({ options: { fixedCustomerId: '123' } }), /停止下单和测量造数/)
+})
 
 const source = readFileSync(new URL('./dropship-mixed-palletization.mjs', import.meta.url), 'utf8')
 const orders = readFileSync(new URL('./orders.mjs', import.meta.url), 'utf8')

scripts/admin-test-env-modules/dropship-mixed-palletization.mjs

@@ -8,6 +8,7 @@ const OPTIONS = { scenario: MODULE, deploymentBlocker: true }
 
 // 正式下单和测量产生两客户三票，再用 PDA 公网接口逐箱混托并保留全部证据。
 export async function run(context) {
+  if (context.options?.fixedCustomerId) throw new Error('混托需要第二个固定客户，停止下单和测量造数')
   const originalMarker = context.marker
   const savedContext = { ...context.context }
   const originalManualCount = context.options.prepareDropshipManualCount

scripts/admin-test-env-modules/finance-full-fixtures-contract.test.mjs

@@ -14,8 +14,8 @@ test('fixed customer supplier selection paginates and never creates a fallback',
     async request(method, path) {
       calls.push({ method, path })
       const data = path.includes('/123?') ? supplier : path.includes('page=2')
-        ? { records: [supplier], total: 101 }
-        : { records: Array.from({ length: 100 }, () => ({ id: '99', status: 'ACTIVE', category: 'BOOKING' })), total: 101 }
+        ? { records: [supplier], size: 20, total: 21 }
+        : { records: Array.from({ length: 20 }, () => ({ id: '99', status: 'ACTIVE', category: 'BOOKING' })), size: 20, total: 21 }
       return { body: { data } }
     },
     apiSuccess(_module, _name, response) { return response.body.data },
@@ -30,6 +30,22 @@ test('fixed customer supplier selection paginates and never creates a fallback',
 })
 
 const here = path.dirname(fileURLToPath(import.meta.url))
+test('reused suppliers must match carrier and trucking scope in both list and detail', async () => {
+  for (const criteria of [{ carrierCode: 'MATSON' }, { truckingScope: 'OVERSEAS' }]) {
+    const good = { id: '123', category: 'BOOKING', status: 'ACTIVE', carrierCodes: ['MATSON'], truckingScope: 'OVERSEAS' }
+    let detail = good
+    const context = { options: { fixedCustomerId: '456' }, marker: 'REUSE',
+      async request(method, path) {
+        assert.equal(method, 'GET')
+        return { body: { data: path.includes('/123?') ? detail : { records: [
+          { ...good, id: '999', carrierCodes: [], truckingScope: 'DOMESTIC' }, good], total: 2 } } }
+      }, apiSuccess(_module, _name, response) { return response.body.data }, addStep() {},
+    }
+    assert.equal((await loadSupplier(context, 'BOOKING', criteria)).id, '123')
+    detail = { ...good, carrierCodes: [], truckingScope: 'DOMESTIC' }
+    assert.equal(await loadSupplier(context, 'BOOKING', criteria), null)
+  }
+})
 const source = fs.readFileSync(path.join(here, 'finance-full-fixtures.mjs'), 'utf8')
 
 test('finance fixture module is independently exported and marker isolated', () => {

scripts/admin-test-env-modules/finance-full-fixtures.mjs

@@ -258,23 +258,25 @@ async function loadPublishedAutomaticFee(context, resource) {
     actualWeightKg: responseWeightKg, actualVolumeCbm: responseVolumeCbm }
 }
 
-export async function loadSupplier(context, category) {
+export async function loadSupplier(context, category, { carrierCode, truckingScope } = {}) {
   if (context.financeFixtureHooks?.loadSupplier) return context.financeFixtureHooks.loadSupplier(context, category)
   if (context.options?.fixedCustomerId) {
+    const matches = item => id(item?.id) && item.status === 'ACTIVE' && (!category || item.category === category)
+      && (!carrierCode || item.carrierCodes?.includes(carrierCode)) && (!truckingScope || item.truckingScope === truckingScope)
     for (let page = 1; ; page += 1) {
       const response = await request(context, 'GET', `/api/platform/v1/suppliers?tenantId=0&status=ACTIVE&page=${page}&size=100`)
       const data = context.apiSuccess(MODULE, '读取可复用的现有供应商', response, '', OPTIONS)
       if (!data) return null
       const records = rows(data)
-      const candidate = records.find(item => id(item?.id) && item.status === 'ACTIVE' && (!category || item.category === category))
+      const candidate = records.find(matches)
       if (candidate) {
         const detailResponse = await request(context, 'GET', `/api/platform/v1/suppliers/${encodeURIComponent(candidate.id)}?tenantId=0`)
         const detail = context.apiSuccess(MODULE, '核对复用供应商状态与类别', detailResponse, '', OPTIONS)
-        if (id(detail?.id) === id(candidate.id) && detail?.status === 'ACTIVE' && (!category || detail.category === category)) return detail
+        if (id(detail?.id) === id(candidate.id) && matches(detail)) return detail
         blocker(context, '复用供应商已变化', '候选详情不匹配，不创建替代供应商')
         return null
       }
-      if (!records.length || page * 100 >= Number(data.total ?? records.length)) break
+      if (!records.length || page * Number(data.size || 100) >= Number(data.total ?? records.length)) break
     }
     blocker(context, '缺少可复用供应商', `需要 ACTIVE ${category || '任意类别'} 供应商；禁止自动创建`)
     return null

scripts/admin-test-env-modules/fleet-cross-customer-acceptance-contract.test.mjs

@@ -1,3 +1,4 @@
+import { LOADING_PHOTO_SLOTS } from './fleet-trip-fulfillment.mjs'
 import test from 'node:test'
 import assert from 'node:assert/strict'
 import { readFile } from 'node:fs/promises'
@@ -49,6 +50,7 @@ function model(fault = '') {
         }
         return response({...prior.result,replayed:true})
       }
+      if (method === 'GET' && path.endsWith('/loading-documents')) return response({ dispatchNo: 'DS-ONE', stage: 'LOADING', complete: true, photos: LOADING_PHOTO_SLOTS.map((slot, index) => ({ slot, fileId: String(index + 1) })) })
       if (path === '/api/platform/v1/last-leg/fleet/trips/TRIP') return response(trip)
       if (path === '/api/platform/v1/last-leg/dispatches/DS-ONE/items') return response({dispatchNo:'DS-ONE',recordVersion:nativeVersion,items:items()})
       if (path === '/api/platform/v1/last-leg/dispatches/DS-ONE') {

scripts/admin-test-env-modules/fleet-external-dispatch-acceptance-contract.test.mjs

@@ -1,3 +1,4 @@
+import { LOADING_PHOTO_SLOTS } from './fleet-trip-fulfillment.mjs'
 import test from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
@@ -86,6 +87,7 @@ function fixture(fault = '', nativeMode = false) {
       if (method === 'GET' && normalized === `${BASE}/DS-OWN` && path.startsWith(PDA)) return response({ ...data, items: items.map((i, n) => ({ ...i, positions: [{ positionId: `6${n}`, availablePackages: i.scheduledPackages }] })) })
       if (method === 'GET' && normalized.endsWith('/items')) return response({ dispatchNo: data.dispatchNo, recordVersion: data.recordVersion, status: 'ACTIVE', stage: data.stage, items: cargo })
       if (method === 'GET' && normalized.endsWith('/route')) return response({ dispatchNo: data.dispatchNo, recordVersion: data.recordVersion, stops: tripProof.stops })
+      if (method === 'GET' && path.endsWith('/loading-documents')) return response({ dispatchNo: 'DS-OWN', stage: 'LOADING', complete: true, photos: LOADING_PHOTO_SLOTS.map((slot, index) => ({ slot, fileId: String(index + 1) })) })
       if (method === 'GET' && normalized.endsWith('/loading')) return response({ ...data, manifestHash: 'c'.repeat(64), loadingComplete: { allowed: true }, pallets: items.map((i, n) => ({ ...i, ...(fault === 'missing-measurements' ? {} : { palletSpaces: n === 2 ? 2 : 1, weightKg: n === 2 ? 37 : 10, volumeCbm: n === 2 ? 0.7 : 0.2, deliveryIndex: nativeMode || n === 2 ? 1 : n + 1,
         evidence: [['palletSpaces', n === 2 ? 2 : 1], ['weightKg', n === 2 ? 37 : 10], ['volumeCbm', n === 2 ? 0.7 : 0.2]].map(([field, value]) => ({ field, value, actual: true, sourceType: 'MEASURED', sourceBusinessNo: i.inboundCode, observedAt: '2026-10-19T01:00:00Z' })) }) })) })
       if (method === 'GET') { assert.ok(normalized === `${BASE}/DS-OWN` || normalized === `${BASE}/DS-FULL`, raw); return response(data) }
@@ -95,7 +97,7 @@ function fixture(fault = '', nativeMode = false) {
       if (path.endsWith('/items')) { assert.equal(stage, 'BEFORE_LOADING'); assert.equal(body.cargo.length, 1); items.push(external); recordVersion++; fleetVersion++; if (fault === 'unknown-add') return { http: 0, body: null }; return remember(ack('ADD_CARGO')) }
       if (path.endsWith('/submit-review') || path.endsWith('/dispatch-review') || path.endsWith('/loading-review')) { if (path.endsWith('/loading-review') && fault !== 'review-not-applied') { review = true; stage = 'LOADING' }; recordVersion++; return remember(ack('REVIEW')) }
       if (path.endsWith('/pick')) { assert.ok(token); const itemId = path.split('/').at(-2); items.find(i => i.dispatchItemId === itemId).pickedPackages += body.packages; recordVersion++; return remember(ack('PICK')) }
-      if (path.endsWith('/loading-complete')) { assert.equal(items.every(i => i.pickedPackages === i.scheduledPackages), true); stage = 'DELIVERING'; recordVersion++; return remember(ack('LOADING_COMPLETE', { confirmedLoad: { manifestHash: body.manifestHash, pallets: body.measurements } })) }
+      if (path.endsWith('/loading-complete')) { assert.equal(items.every(i => i.pickedPackages === i.scheduledPackages), true); stage = 'DELIVERING'; recordVersion++; return remember(ack('LOADING_COMPLETE', { confirmedLoad: { manifestHash: body.manifestHash, pallets: items.map((item, index) => ({ warehousePalletId: item.warehousePalletId, palletSpaces: 1, weightKg: index === 2 ? 37 : 10, volumeCbm: index === 2 ? 0.7 : 0.2, deliveryIndex: nativeMode || index === 2 ? 1 : index + 1 })) } })) }
       throw Error(`Unexpected ${method} ${raw}`)
     } }
   const options = nativeMode ? {pickerToken:'OFFLINE-ONLY'} : {coverageCase:currentCase,pickerToken:'OFFLINE-ONLY'}

scripts/admin-test-env-modules/fleet-quotes-operations-contract.test.mjs

@@ -6,6 +6,21 @@ import { run, runQuoteSession, verifyOperations, requireCurrentFixture, fixtureC
 import { AcceptanceRun } from '../admin-test-env-acceptance.mjs'
 
 const copy = value => structuredClone(value)
+test('fixed quote supplier is reused without creation or deactivation', async () => {
+  const { context } = harness(), request = context.request.bind(context), writes = []
+  context.options = { fixedCustomerId: '101' }
+  const supplier = { id: '901', name: 'Existing', category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' }
+  context.request = async (method, path, ...args) => {
+    if (path.includes('/suppliers')) {
+      if (method !== 'GET') writes.push({ method, path })
+      return { http: 200, body: { code: '200', data: path.includes('/901') ? supplier : { records: [supplier], total: 1 } } }
+    }
+    return request(method, path, ...args)
+  }
+  await run(context)
+  assert.equal(context.createdResources.fleetQuoteAcceptance.supplierReused, true)
+  assert.deepEqual(writes, [])
+})
 function harness(fault) {
   const marker = 'FLEET-CURRENT-RUN', tripNo = 'TR-CURRENT', departedAt = '2026-10-03T01:00:00Z'
   const rows = new Map(), histories = new Map(), commands = new Map(), measuredKeys = new Map(), calls = []

scripts/admin-test-env-modules/fleet-quotes-operations.mjs

@@ -227,10 +227,14 @@ async function execute(context, { scope, writeMeasured = false, idempotencyNames
     }
     if (scope === 'QUOTES_ONLY') {
     const customer = requireQuoteCustomer(context)
-    const supplier = await command('POST', '/api/platform/v1/suppliers?tenantId=0', {
+    const supplier = context.options?.fixedCustomerId
+      ? await (await import('./finance-full-fixtures.mjs')).loadSupplier(context, 'TRUCKING', { truckingScope: 'OVERSEAS' })
+      : await command('POST', '/api/platform/v1/suppliers?tenantId=0', {
       name: `车辆报价验收-${context.marker}`, category: 'TRUCKING', truckingScope: 'OVERSEAS', carrierCodes: [], status: 'ACTIVE', remark: context.marker,
       region: 'TEST', legalRepresentative: '测试法人', contactName: '测试联系人', phone: '19900000000', email: 'fleet-acceptance@example.com', settlementPeriod: 'MONTHLY_30',
     }, '新建本轮海外车队供应商')
+    if (!supplier) throw new Error('缺少现有海外拖车供应商，不自动创建')
+    proof.supplierReused = Boolean(context.options?.fixedCustomerId)
     proof.supplierId = id(supplier.id ?? supplier)
     check('供应商返回明确标识', null, /^\d+$/.test(proof.supplierId))
     const day = new Date().toISOString().slice(0, 10)
@@ -311,7 +315,7 @@ async function execute(context, { scope, writeMeasured = false, idempotencyNames
         if (row.status === 'ACTIVE') await command('PATCH', `${QUOTES}/${encode(no)}/status`, { recordVersion: row.recordVersion, status: 'INACTIVE' }, '停用本轮专用报价并保留历史')
       } catch (error) { cleanupErrors.push(error.message) }
     }
-    if (proof.supplierId && !context.quoteRequestOutcomeUnknown) {
+    if (proof.supplierId && !proof.supplierReused && !context.quoteRequestOutcomeUnknown) {
       try {
         const path = `/api/platform/v1/suppliers/${encode(proof.supplierId)}`
         const response = await request('PATCH', `${path}/status?tenantId=0`, { status: 'INACTIVE' })