test(lastleg): isolate photo table DDL from subsequent rent migrations

User-authorized fixed-source promotion; deployment and data preservation verified separately.

common-event-contract/src/main/java/com/baiyue/common/event/ContainerNumbers.java

@@ -2,15 +2,11 @@ package com.baiyue.common.event;
 
 import java.util.Locale;
 
-/** Canonical physical container number used by cross-region business facts. */
+/** 跨服务业务事实使用的真实集装箱号，只规范化空白和大小写，不校验 ISO 格式。 */
 public final class ContainerNumbers {
-    private static final int[] LETTER_VALUES = {
-        10, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 23, 24,
-        25, 26, 27, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38
-    };
-
     private ContainerNumbers() { }
 
+    /** 柜号必须非空；统一移除格式空白并转大写，保留业务录入值。 */
     public static String normalizeRequired(String value) {
         if (value == null || value.isBlank()) {
             throw new IllegalArgumentException("containerNo is required");
@@ -19,21 +15,13 @@ public final class ContainerNumbers {
         value.codePoints().filter(codePoint -> !Character.isWhitespace(codePoint)
             && !Character.isSpaceChar(codePoint)).forEach(compact::appendCodePoint);
         String normalized = compact.toString().toUpperCase(Locale.ROOT);
-        if (!normalized.matches("[A-Z]{3}[UJZ][0-9]{7}")) {
-            throw new IllegalArgumentException("containerNo must comply with ISO 6346");
-        }
-        int sum = 0;
-        for (int index = 0; index < 10; index++) {
-            char current = normalized.charAt(index);
-            int number = Character.isDigit(current) ? current - '0' : LETTER_VALUES[current - 'A'];
-            sum += number * (1 << index);
-        }
-        if (normalized.charAt(10) - '0' != sum % 11 % 10) {
-            throw new IllegalArgumentException("containerNo must comply with ISO 6346 check digit");
+        if (normalized.isEmpty()) {
+            throw new IllegalArgumentException("containerNo is required");
         }
         return normalized;
     }
 
+    /** 冻结事实必须已规范化，避免生产与消费端的快照或哈希发生漂移。 */
     public static String requireCanonical(String value) {
         String normalized = normalizeRequired(value);
         if (!normalized.equals(value)) {

common-event-contract/src/main/java/com/baiyue/common/event/WalletSettlementReference.java

@@ -1,4 +1,13 @@
 package com.baiyue.common.event;
 
-/** Finance-issued identity of a successful consumption, carried by its immutable fee source. */
-public record WalletSettlementReference(String commandEventId, String holdId, String ledgerId) { }
+/** 成功扣款凭据；资金业务身份独立于费用对应的实际服务订单。 */
+public record WalletSettlementReference(String commandEventId, String holdId, String ledgerId,
+    @com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)
+    String walletBusinessType,
+    @com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)
+    String walletBusinessNo) {
+    /** 原有资金身份与服务订单一致的来源继续使用原三项凭据。 */
+    public WalletSettlementReference(String commandEventId, String holdId, String ledgerId) {
+        this(commandEventId, holdId, ledgerId, null, null);
+    }
+}

common-event-contract/src/main/java/com/baiyue/common/event/package-info.java

@@ -1,4 +1,11 @@
 /**
  * 国内与海外业务单元共享的稳定事件契约。
+ *
+ * <p>海外费用的 walletSettlement 引用成功扣款的 commandEventId、holdId、ledgerId。
+ * 独立资金流程另外携带 walletBusinessType、walletBusinessNo：人工费用为
+ * OVERSEAS_MANUAL_FEE / 来源费用ID-冻结次数，仓租为 STORAGE_RENT / 出库预占ID。
+ * 外层 businessType、businessNo 始终表示实际服务订单，不能替换为资金流程编号。
+ * Finance 同时核对冻结、实扣流水、成功指令结果及客户金额，一个 hold 只能关联一个费用来源。
+ * 资金身份与服务订单一致的既有引用省略这两个字段，保持既有快照哈希。</p>
  */
 package com.baiyue.common.event;

common-event-contract/src/test/java/com/baiyue/common/event/ContainerNumbersTest.java

@@ -1,20 +1,41 @@
 package com.baiyue.common.event;
 
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 class ContainerNumbersTest {
+    /** 规范化仍保持确定性，事件只能接受已冻结的规范值。 */
     @Test
-    void normalizesWhitespaceAndCaseButCanonicalFactsRequireExactIso6346Value() {
+    void normalizesWhitespaceAndCaseButCanonicalFactsRequireExactValue() {
         assertThat(ContainerNumbers.normalizeRequired(" zcsu 7881970 ")).isEqualTo("ZCSU7881970");
-        assertThat(ContainerNumbers.requireCanonical("ZCSU7881970")).isEqualTo("ZCSU7881970");
         assertThatThrownBy(() -> ContainerNumbers.requireCanonical("zcsu7881970"))
             .hasMessageContaining("normalized");
-        assertThatThrownBy(() -> ContainerNumbers.normalizeRequired("ZCSU7881971"))
-            .hasMessageContaining("check digit");
-        assertThatThrownBy(() -> ContainerNumbers.normalizeRequired("CAB-260831-0001"))
-            .hasMessageContaining("ISO 6346");
+        assertThatThrownBy(() -> ContainerNumbers.requireCanonical(" JZXH10231043 "))
+            .hasMessageContaining("normalized");
+    }
+
+    /** 非 ISO 柜号可以作为事件事实，不在下游重新阻断。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "ZCSU7881971", "MSCA6639870", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void acceptsNonIsoNumber(String containerNo) {
+        assertThat(ContainerNumbers.normalizeRequired(" " + containerNo.toLowerCase(java.util.Locale.ROOT) + " "))
+            .isEqualTo(containerNo);
+        assertThat(ContainerNumbers.requireCanonical(containerNo)).isEqualTo(containerNo);
+    }
+
+    /** 规范化前后均不得将空白柜号作为业务事实。 */
+    @ParameterizedTest
+    @NullAndEmptySource
+    @ValueSource(strings = {"   ", "\u00a0\u3000"})
+    void rejectsMissingNumber(String containerNo) {
+        assertThatThrownBy(() -> ContainerNumbers.normalizeRequired(containerNo))
+            .isInstanceOf(IllegalArgumentException.class).hasMessageContaining("required");
+        assertThatThrownBy(() -> ContainerNumbers.requireCanonical(containerNo))
+            .isInstanceOf(IllegalArgumentException.class).hasMessageContaining("required");
     }
 }

common-event-contract/src/test/java/com/baiyue/common/event/WalletSettlementReferenceTest.java

@@ -0,0 +1,22 @@
+package com.baiyue.common.event;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+class WalletSettlementReferenceTest {
+    private final ObjectMapper json = new ObjectMapper();
+
+    @Test
+    void oldReferencesRetainExactHashShape() throws Exception {
+        String original = "{\"commandEventId\":\"c1\",\"holdId\":\"9\",\"ledgerId\":\"72\"}";
+        var reference = json.readValue(original, WalletSettlementReference.class);
+        assertThat(json.readTree(json.writeValueAsString(reference))).isEqualTo(json.readTree(original));
+    }
+
+    @Test
+    void dedicatedFundingIdentitySurvivesRoundTrip() throws Exception {
+        var reference = new WalletSettlementReference("c1", "9", "72", "STORAGE_RENT", "445");
+        assertThat(json.readValue(json.writeValueAsString(reference), WalletSettlementReference.class)).isEqualTo(reference);
+    }
+}

deploy/sql/20261022-海外费用仓租数据库变更汇总.md

@@ -0,0 +1,39 @@
+# 海外费用与仓租数据库定义汇总
+
+本次功能的数据库定义已统一到下面两份 SQL，五份重复版本脚本和两份专项汇总 SQL 已移除。仅整理文件，未连接数据库、执行 SQL 或部署。
+
+## 两个统一入口
+
+| 文件 | 相关数据库 | 本次内容 |
+|---|---|---|
+| [头程数据库统一增量-MySQL8.sql](头程数据库统一增量-MySQL8.sql) | `baiyue_iam` | 海外费用管理菜单及默认平台管理员授权；保留既有财务编辑、审核按钮和授权 |
+| [海外区域统一增量-MySQL8.sql](海外区域统一增量-MySQL8.sql) | `baiyue_lastleg` | 资金与仓租四表、费用关联及换标快照、审核人名称、采购退款请求幂等字段与唯一索引 |
+
+两份文件虽然名称包含“增量”，仍只用于对应区域的空库初始化。新增列、索引和约束直接维护在最终 `CREATE TABLE` 中，菜单及授权使用初始化种子；不追加存量改造、权限版本回填或动态迁移段。目标 schema 必须为空，按文件原有初始化流程执行；不能向已有业务库重放。
+
+本次不再提供这项功能的独立升级脚本。已有库升级必须按实际结构和明确授权另行准备、审阅受控增量，不能把删除重复文件理解为已有库已完成升级。
+
+## 海外表和字段
+
+| 类型 | 表 / 字段 | 用途 |
+|---|---|---|
+| 新表 | `ll_finance_fee_funding` | 人工费用冻结、审核扣款、释放及财务流水引用 |
+| 新表 | `ll_storage_rent_lot` | 实际入库计租原批次、数量及入库时间 |
+| 新表 | `ll_storage_rent_inbound` | 头程每次实收凭证去重，关联同单同仓计租批次 |
+| 新表 | `ll_storage_rent_share` | 库存与原计租批次份额关联，保留原库龄 |
+| 新表 | `ll_storage_rent_preparation` | 出库计租快照、汇率、资金预占及实际出库记录 |
+| 可空字段 | `ll_destuff_pallet_cost_allocation.fee_source_id` | `BIGINT NULL`，允许人工审核后关联海外费用来源 |
+| 字段 | `ll_return_sku_conversion.storage_rent_shares_json` | `LONGTEXT NULL`，退货 SKU 换标的原仓租份额快照 |
+| 字段 | `ll_finance_fee_source.reviewer_name` | `VARCHAR(255) NULL`，审核人名称快照 |
+| 字段 | `ll_overseas_procurement_fee.idempotency_key` | `VARCHAR(128) NULL`，采购退款请求幂等键 |
+| 唯一索引 | `uk_ll_procurement_refund_request(order_id,purpose,idempotency_key)` | 同一采购订单、用途和退款请求去重 |
+
+## 国内菜单和权限
+
+海外业务 → 海外费用管理，菜单 ID `5117200`、权限 `platform:overseas-fee:list`、路由 `/overseas-business/fees`；默认仅授予 `PLATFORM_ADMIN`。编辑和审核分别复用 `platform:finance:fee-source:edit` 与 `platform:finance:fee-source:review`，列表权限不包含写操作。国内基线已包含两项既有按钮及管理员授权。
+
+已有库的 [费用写权限修复](overseas-fee-canonical-write-permissions-repair.sql) 是单独的定向补丁，继续保留原适用条件和授权边界，不是结构升级或菜单初始化入口。其他独立修复脚本与历史迁移不在本次清理范围。
+
+费用项目继续使用 Firstleg 现有目录及 `FEE_TYPE_077 / 仓储费`，不重复插入项目、不批量覆盖客户专价、不回填历史仓租或费用、不修改钱包余额。
+
+配套服务、页面、配置及验收边界见 [首版发布验收](../../lastleg-service/docs/overseas-fees-storage-rent-release.md)。

deploy/sql/README.md

@@ -1,5 +1,19 @@
 # 单测试环境数据库空库初始化
 
+车辆与司机档案照片复用：先执行 `lastleg-fleet-resource-photos.sql` 新增照片版本表，再配套发布 File、Lastleg 和 Admin。车辆详情／司机详情维护照片，排车保存时复制缺失照片为当趟证据；已有照片不被后续档案替换覆盖。驾驶证统一接受 PDF/JPG/PNG。源基线与海外空库基线已同步；本次未执行环境 SQL 或部署。
+
+放舱后预计到港窄维护需要配套更新 `trg_ocean_booking_before_update`：仅从冻结比较中移除 `estimated_arrival_at`，其余运输、预报、关系方及柜型冻结不变。定义已同步 `firstleg/src/main/resources/db/phase3-ocean-booking-schema.sql` 与国内统一基线；已有 TEST 需另行审阅并授权替换该触发器，不重放空库文件，不回填数据。本轮只准备定义，未执行 SQL 或部署。
+
+货柜关联已放舱订舱时不再限制 ISO 柜号格式，Firstleg 模块基线与国内统一空库基线已移除 `chk_container_booking_iso6346`，保留同订舱柜号唯一键。既有 TEST 发布前需核对并单独授权移除该约束：`ALTER TABLE baiyue_firstleg.fl_container_booking DROP CHECK chk_container_booking_iso6346;`。配套发布 Firstleg 与 Admin；不重放空库初始化、不修改业务数据。本次仅准备源码与 SQL 定义，未执行环境 SQL 或部署。
+
+`overseas-storage-rent-zero-fee-repair.sql` 为免费仓租的定向结构修复，固定 `baiyue_lastleg.ll_finance_fee_source`：先检查列类型、既有金额约束及存量行，再以单次原子 ALTER 仅放行自动应收仓租的原币及结算双零金额和空汇率，其余费用仍须正额及有效汇率。不更新费用、余额或库存；禁止重放空库初始化。源码基线与海外统一空库基线同步。脚本待审阅执行，文件存在不代表已执行。
+
+`overseas-fee-remark-add.sql` 为海外人工费用说明的独立结构增量，固定目标 `baiyue_lastleg.ll_finance_fee_source`，仅在缺失时增加允许为空的 `fee_remark VARCHAR(500)`，保留旧费用与审核记录，不回填、不扣款、不改菜单。Lastleg 源基线与海外统一空库基线已同步；已有开发库须逐项授权执行本脚本后才能加载配套 Lastleg 版本。文件准备不表示已执行。
+
+`finance-overseas-fee-hash-width-repair.sql` 用于明确授权的本机开发环境海外费用推送修复，固定目标 `baiyue_finance`。先核对 `fin_inbox_event.payload_hash`、`fin_fee_source.source_hash` 两列；仅将不足71位的长度扩至71位，兼容 `sha256:` 前缀，保留空值约束和字符集排序规则，不更新业务数据。缺列、异常类型或小于64位时停止；已有足够长度则跳过。使用独立连接、遇错停止，执行后回查结构，再通过原费用事件重试验证，禁止重新生成费用或扣款。脚本包含执行后移除的专用校验过程；创建或执行失败须停止，不扩大修复范围。文件准备不表示已执行。
+
+`warehouse-supplier-query-structure-repair.sql` 用于明确授权的本机开发环境供应商查询结构修复，固定目标 `baiyue_warehouse`：仅在缺失时新增 `wh_supplier.trucking_scope`，并按当前模块基线创建缺失的 `wh_supplier_carrier` 空表。结构存在则跳过，不更新供应商类别、费用或资金，不推断历史拖车的国内/海外归属。使用独立连接、遇错停止，执行后回查结构并通过正式供应商列表 API 验证；不需要重启服务。文件准备不表示已获授权或已执行。
+
 仓储转运到仓取货、本土卡车接入现有排车的**可重复执行汇总SQL**为 `lastleg-dispatch-transport-tasks.sql`，文件内固定 `USE baiyue_lastleg`，对已存在字段、表安全跳过。新增 `ll_dispatch_order.task_type` 字段、`ll_dispatch_truck_task`、`ll_dispatch_transport_create`、`ll_dispatch_transport_command` 三张表，并确保既有正式排车单号日流水表存在；不回填或删除业务数据。前置是目标库已具备现有整车排车主表、FleetTrip、取货任务及本土卡车原单结构。按序先执行此 SQL，再配套发布 Lastleg 与 Admin；取消释放有效原单关联、完成保留关联。`migrations/overseas/baiyue_lastleg/V32__dispatch_transport_tasks.sql` 是迁移系统中的新增结构记录。本次仅在已授权本机执行并验收，不代表远端已部署。
 
 排车单号使用`PCyyyyMMdd0001`，日期取`Asia/Shanghai`，全平台跨客户/仓库共用独立日流水。`ll_dispatch_daily_sequence`同步Lastleg源基线与海外空库基线；已有结构的定向新增入口为`lastleg-dispatch-daily-sequence.sql`，只建序列表，不改已有业务号、不回填历史、不重放空库初始化。源码和DDL须配套发布；文件存在不表示已执行或部署。流水在独立短事务分配，回滚或取消不复用，四位范围每日0001至9999，准确单量以主单统计为准。
@@ -65,7 +79,7 @@ V13 收货覆盖由 `lastleg-service/src/main/resources/db/appointment-receiving
 | 区域 | 完整入口 | 服务 schema | 表数 |
 |---|---|---|---:|
 | 国内 | `头程数据库统一增量-MySQL8.sql` | `baiyue_auth`、`baiyue_iam`、`baiyue_order`、`baiyue_warehouse`、`baiyue_firstleg`、`baiyue_file`、`baiyue_audit`、`baiyue_finance` | 229 |
-| 海外 | `海外区域统一增量-MySQL8.sql` | `baiyue_lastleg`、`baiyue_lastlag_warehouse` | 234 |
+| 海外 | `海外区域统一增量-MySQL8.sql` | `baiyue_lastleg`、`baiyue_lastlag_warehouse` | 238 |
 
 
 - 所有服务位于同一测试环境；两份文件只分组组织服务 schema，不代表两个部署区域。`baiyue_lastlag_warehouse` 保留当前正式的 `lastlag` 拼写。
@@ -88,7 +102,7 @@ V13 收货覆盖由 `lastleg-service/src/main/resources/db/appointment-receiving
 5. DDL 隐式提交，不可整体回滚。失败后停止并保留错误；经另行授权准备空库后从头执行，不针对半初始化库追加迁移或从失败行续跑。
 6. Firstleg 测量项与拆分项互为外键：建空表期间暂设会话 `foreign_key_checks=0`，随后立即恢复 `1`，再插入种子。失败时关闭连接。两边外键完整保留在 CREATE TABLE 内。
 
-成功时只在最末输出一行 `initialization_status=PASS`，并带 `region=CN/OVERSEAS`、`initialized_tables=229/234`。必须同时确认客户端退出码 0；忽略错误后出现的 PASS 不算成功。
+成功时只在最末输出一行 `initialization_status=PASS`，并带 `region=CN/OVERSEAS`、`initialized_tables=229/238`。必须同时确认客户端退出码 0；忽略错误后出现的 PASS 不算成功。
 
 ## 平台管理员密码
 
@@ -188,3 +202,9 @@ node --test scripts/admin-test-env-modules/initialization-baseline-contract.test
 ## 统一业务单号
 
 编号规则见 `../../../docs/业务单据编号契约.md`。Order、Warehouse、Lastleg 空库基线新增各自的 `ord_document_sequence`、`wh_document_sequence`、`ll_document_sequence`；Firstleg 与 Finance 复用本库编号表。Lastleg 空库基线移除无生产调用的客户日序列、逻辑秒时钟及旧尾程日序列表，保留排车日序列。采购费用新增可空 `idempotency_key` 及订单/用途/请求键唯一约束，用于退款重放，业务号统一使用 PF。此处只准备基线，不执行 SQL、回填或删除测试存量。
+
+海外费用与仓租首版统一维护在 `头程数据库统一增量-MySQL8.sql` 的 IAM 菜单/管理员授权种子及 `海外区域统一增量-MySQL8.sql` 的最终建表定义中。海外基线包含资金与仓租四表、拆柜成本可空费用引用、退货 SKU 换标仓租快照、审核人名称，以及采购退款请求幂等字段和唯一索引；同步模块源基线、国内权限种子及海外空库 238 表，复用现有 `FEE_TYPE_077 / 仓储费`，不新增费用项目种子。发布须同时更新 Firstleg、Lastleg、Admin 与海外 PDA；规则、配置及资金验收见 [首版发布验收](../../lastleg-service/docs/overseas-fees-storage-rent-release.md)。仅整理文件，未执行 SQL 或部署。
+
+本次重复的五份版本脚本和两份专项汇总 SQL 已移除，内容清单见 [20261022-海外费用仓租数据库变更汇总](20261022-海外费用仓租数据库变更汇总.md)。两份统一文件仍只用于空库初始化，不能向已有业务库重放；本次不再提供这项功能的独立升级脚本，已有库升级须另按实际结构和明确授权准备、审阅增量。其他独立修复补丁及历史迁移保持各自适用边界。
+
+采购方向扩展：`migrations/overseas/baiyue_lastleg/V34__procurement_direction.sql` 先于匹配 Lastleg 版本执行，为采购单增加 `procurement_direction`；历史订单默认海外采购回国内，不修改既有实物和资金记录。国内采购通过既有国内仓目录选起运收货仓；源基线与统一空库基线同步。本地验证不表示测试库已执行或服务已发布。

deploy/sql/finance-overseas-fee-hash-width-repair.sql

@@ -0,0 +1,75 @@
+-- 本机开发环境海外费用推送结构修复。固定目标：baiyue_finance。
+-- 仅将两个既有摘要字段不足 71 位的长度扩至 71；不改数据、费用、账单或余额。
+-- 保留原字段的空值约束、字符集及排序规则；缺表、缺列或异常字段类型时拒绝执行。
+-- 执行须单独授权。使用独立连接、遇错停止；不得以本文件代替完整数据库初始化。
+USE baiyue_finance;
+
+-- 执行前只读核对；sha256: 前缀 7 位加摘要 64 位，共 71 位。
+SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE,
+       CHARACTER_SET_NAME, COLLATION_NAME
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = 'baiyue_finance'
+  AND ((TABLE_NAME = 'fin_inbox_event' AND COLUMN_NAME = 'payload_hash')
+    OR (TABLE_NAME = 'fin_fee_source' AND COLUMN_NAME = 'source_hash'));
+
+DELIMITER $$
+CREATE PROCEDURE finance_fee_hash_width_repair_20261023()
+BEGIN
+    DECLARE checked_columns INT DEFAULT 0;
+    DECLARE column_index INT DEFAULT 0;
+    DECLARE target_table VARCHAR(64);
+    DECLARE target_column VARCHAR(64);
+    DECLARE current_length BIGINT;
+    DECLARE nullable_value VARCHAR(3);
+    DECLARE charset_value VARCHAR(64);
+    DECLARE collation_value VARCHAR(64);
+    DECLARE comment_value TEXT;
+
+    IF DATABASE() <> 'baiyue_finance' THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '目标必须是 baiyue_finance';
+    END IF;
+    SELECT COUNT(*) INTO checked_columns
+    FROM information_schema.COLUMNS
+    WHERE TABLE_SCHEMA = 'baiyue_finance' AND DATA_TYPE IN ('char', 'varchar')
+      AND CHARACTER_MAXIMUM_LENGTH >= 64
+      AND COLUMN_DEFAULT IS NULL AND EXTRA = ''
+      AND ((TABLE_NAME = 'fin_inbox_event' AND COLUMN_NAME = 'payload_hash')
+        OR (TABLE_NAME = 'fin_fee_source' AND COLUMN_NAME = 'source_hash'));
+    IF checked_columns <> 2 THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '摘要字段缺失或类型异常，停止修复';
+    END IF;
+
+    WHILE column_index < 2 DO
+        SET target_table = IF(column_index = 0, 'fin_inbox_event', 'fin_fee_source');
+        SET target_column = IF(column_index = 0, 'payload_hash', 'source_hash');
+        SELECT CHARACTER_MAXIMUM_LENGTH, IS_NULLABLE, CHARACTER_SET_NAME, COLLATION_NAME, COLUMN_COMMENT
+          INTO current_length, nullable_value, charset_value, collation_value, comment_value
+        FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA = 'baiyue_finance' AND TABLE_NAME = target_table
+          AND COLUMN_NAME = target_column;
+        IF current_length < 71 THEN
+            SET @finance_fee_hash_width_ddl = CONCAT(
+                'ALTER TABLE baiyue_finance.`', target_table, '` MODIFY COLUMN `', target_column,
+                '` VARCHAR(71) CHARACTER SET ', charset_value, ' COLLATE ', collation_value,
+                IF(nullable_value = 'YES', ' NULL', ' NOT NULL'),
+                ' COMMENT ', QUOTE(comment_value));
+            PREPARE finance_fee_hash_width_stmt FROM @finance_fee_hash_width_ddl;
+            EXECUTE finance_fee_hash_width_stmt;
+            DEALLOCATE PREPARE finance_fee_hash_width_stmt;
+        END IF;
+        SET column_index = column_index + 1;
+    END WHILE;
+END$$
+DELIMITER ;
+
+CALL finance_fee_hash_width_repair_20261023();
+DROP PROCEDURE finance_fee_hash_width_repair_20261023;
+SET @finance_fee_hash_width_ddl = NULL;
+
+-- 执行后两列长度均应至少为 71；结构已正确时不执行 ALTER。
+SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE,
+       CHARACTER_MAXIMUM_LENGTH >= 71 AS width_ok
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = 'baiyue_finance'
+  AND ((TABLE_NAME = 'fin_inbox_event' AND COLUMN_NAME = 'payload_hash')
+    OR (TABLE_NAME = 'fin_fee_source' AND COLUMN_NAME = 'source_hash'));

deploy/sql/lastleg-fleet-resource-photos.sql

@@ -0,0 +1,16 @@
+-- 仅新增车辆及司机档案照片版本表，可重复执行，不回填业务数据。
+USE baiyue_lastleg;
+
+CREATE TABLE IF NOT EXISTS ll_fleet_resource_photo (
+  resource_kind VARCHAR(16) NOT NULL COMMENT '档案类型：车辆或司机',
+  resource_id BIGINT NOT NULL COMMENT '车辆或司机档案标识',
+  record_version BIGINT NOT NULL COMMENT '照片版本，从一递增',
+  file_id BIGINT NOT NULL COMMENT '文件服务照片标识',
+  file_name VARCHAR(512) NOT NULL COMMENT '照片原始文件名',
+  content_type VARCHAR(64) NOT NULL COMMENT '照片媒体类型',
+  size_bytes BIGINT NOT NULL COMMENT '照片字节数',
+  created_by VARCHAR(64) NOT NULL COMMENT '上传操作人标识',
+  created_at DATETIME(3) NOT NULL COMMENT '上传时间（UTC）',
+  PRIMARY KEY (resource_kind, resource_id, record_version),
+  UNIQUE KEY uk_fleet_resource_photo_file (resource_kind, resource_id, file_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆及司机档案照片版本记录';

deploy/sql/migrations/overseas/baiyue_lastleg/V34__fleet_resource_photos.sql

@@ -0,0 +1,14 @@
+
+CREATE TABLE IF NOT EXISTS ll_fleet_resource_photo (
+  resource_kind VARCHAR(16) NOT NULL COMMENT '档案类型：车辆或司机',
+  resource_id BIGINT NOT NULL COMMENT '车辆或司机档案标识',
+  record_version BIGINT NOT NULL COMMENT '照片版本，从一递增',
+  file_id BIGINT NOT NULL COMMENT '文件服务照片标识',
+  file_name VARCHAR(512) NOT NULL COMMENT '照片原始文件名',
+  content_type VARCHAR(64) NOT NULL COMMENT '照片媒体类型',
+  size_bytes BIGINT NOT NULL COMMENT '照片字节数',
+  created_by VARCHAR(64) NOT NULL COMMENT '上传操作人标识',
+  created_at DATETIME(3) NOT NULL COMMENT '上传时间（UTC）',
+  PRIMARY KEY (resource_kind, resource_id, record_version),
+  UNIQUE KEY uk_fleet_resource_photo_file (resource_kind, resource_id, file_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆及司机档案照片版本记录';

deploy/sql/migrations/overseas/baiyue_lastleg/V34__procurement_direction.sql

@@ -0,0 +1,9 @@
+-- 先于新版本 Lastleg 上线执行。历史订单保持海外采购回国内，不改数量、资金或交寄事实。
+SET @procurement_direction_ddl = IF(
+  (SELECT COUNT(*) FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE()
+    AND TABLE_NAME = 'll_overseas_procurement_order' AND COLUMN_NAME = 'procurement_direction') = 0,
+  'ALTER TABLE ll_overseas_procurement_order ADD COLUMN procurement_direction VARCHAR(32) NOT NULL DEFAULT ''OVERSEAS_TO_DOMESTIC'' COMMENT ''采购方向：海外采购回国内/国内采购发海外''',
+  'SELECT 1');
+PREPARE procurement_direction_stmt FROM @procurement_direction_ddl;
+EXECUTE procurement_direction_stmt;
+DEALLOCATE PREPARE procurement_direction_stmt;

deploy/sql/overseas-fee-canonical-write-permissions-repair.sql

@@ -0,0 +1,121 @@
+-- 海外费用既有写按钮最小修复；MySQL 8，目标只能是 baiyue_iam。
+-- 仅恢复基线 5105024/5105025 及既有 4000001 PLATFORM_ADMIN 缺失授权。
+-- 不创建角色/成员，不授予其他角色，不新增 overseas-fee:edit/review 别名。
+-- 在支持 DELIMITER、遇错停止的客户端同连接整份执行；执行期间暂停相关角色权限维护。
+-- 不在其他未提交事务中调用。所有业务DML及subject版本变更同事务，任何异常回滚。
+USE baiyue_iam;
+SET NAMES utf8mb4;
+SELECT DATABASE() AS target_database;
+
+DROP PROCEDURE IF EXISTS repair_overseas_fee_canonical_write;
+DELIMITER $$
+CREATE PROCEDURE repair_overseas_fee_canonical_write()
+BEGIN
+  DECLARE locked_role BIGINT;
+  DECLARE changed_rows BIGINT DEFAULT 0;
+  DECLARE EXIT HANDLER FOR SQLEXCEPTION
+  BEGIN
+    ROLLBACK;
+    RESIGNAL;
+  END;
+
+  START TRANSACTION;
+  IF DATABASE()<>'baiyue_iam' THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Wrong schema: expected baiyue_iam';
+  END IF;
+  IF (SELECT COUNT(*) FROM iam_role WHERE id=4000001 AND tenant_id=0 AND app_code='PLATFORM'
+      AND role_code='PLATFORM_ADMIN' AND role_type='SYSTEM' AND status='ACTIVE' AND deleted=0)<>1
+      OR EXISTS(SELECT 1 FROM iam_role WHERE role_code='PLATFORM_ADMIN' AND id<>4000001) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Existing PLATFORM_ADMIN identity/status mismatch; no role will be created';
+  END IF;
+  SELECT id INTO locked_role FROM iam_role WHERE id=4000001 FOR UPDATE;
+
+  -- 新建缺失按钮使用当前客户应收父菜单；只接受已核对的既有财务菜单，不修复其他菜单。
+  IF (SELECT COUNT(*) FROM iam_permission WHERE id=5105041 AND tenant_id=0 AND app_code='PLATFORM'
+      AND permission_type='MENU' AND permission_code='platform:finance:customer-arap:list'
+      AND status='ACTIVE' AND deleted=0)<>1
+      OR EXISTS(SELECT 1 FROM iam_permission WHERE permission_code='platform:finance:customer-arap:list' AND id<>5105041) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Existing customer AR/AP parent menu is missing or mismatched';
+  END IF;
+  IF EXISTS(SELECT 1 FROM iam_permission WHERE
+      (id=5105024 AND NOT(permission_code<=>'platform:finance:fee-source:review'))
+      OR (id=5105025 AND NOT(permission_code<=>'platform:finance:fee-source:edit'))
+      OR (permission_code='platform:finance:fee-source:review' AND id<>5105024)
+      OR (permission_code='platform:finance:fee-source:edit' AND id<>5105025)
+      OR (id IN(5105024,5105025) AND (tenant_id<>0 OR app_code<>'PLATFORM'
+          OR permission_type<>'BUTTON' OR built_in<>1 OR parent_id NOT IN(5105000,5105041)
+          OR route_path IS NOT NULL
+          OR NOT(http_method<=>IF(id=5105024,'POST','PUT'))))) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Canonical fee button identity/type/metadata conflict';
+  END IF;
+  IF EXISTS(SELECT 1 FROM iam_permission child LEFT JOIN iam_permission parent ON parent.id=child.parent_id
+      WHERE child.id IN(5105024,5105025) AND (parent.id IS NULL OR parent.tenant_id<>0
+      OR parent.app_code<>'PLATFORM' OR parent.permission_type<>'MENU' OR parent.status<>'ACTIVE' OR parent.deleted<>0
+      OR NOT(parent.permission_code<=>IF(child.parent_id=5105000,'platform:finance','platform:finance:customer-arap:list')))) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Existing fee button parent is invalid';
+  END IF;
+  IF EXISTS(SELECT 1 FROM iam_role_permission WHERE permission_id IN(5105024,5105025) AND tenant_id<>0)
+      OR EXISTS(SELECT 1 FROM iam_membership_role mr LEFT JOIN iam_membership m ON m.id=mr.membership_id
+          WHERE mr.role_id=4000001 AND (mr.tenant_id<>0 OR m.id IS NULL OR m.tenant_id<>0)) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Existing canonical permission or administrator membership scope mismatch';
+  END IF;
+  -- 恢复停用/缺失资源也会恢复其他角色的旧授权；这种情况必须单独核对，不能随本补丁扩权。
+  IF EXISTS(SELECT 1 FROM iam_role_permission rp LEFT JOIN iam_permission p ON p.id=rp.permission_id
+      WHERE rp.permission_id IN(5105024,5105025) AND rp.role_id<>4000001
+      AND (p.id IS NULL OR p.status<>'ACTIVE' OR p.deleted<>0)) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Restoring fee button would affect another role; review separately';
+  END IF;
+
+  INSERT INTO iam_permission
+    (id,tenant_id,app_code,permission_type,parent_id,permission_code,permission_name,route_path,http_method,sort_no,status,built_in,deleted)
+  SELECT 5105024,0,'PLATFORM','BUTTON',5105041,'platform:finance:fee-source:review','审核财务费用来源',NULL,'POST',150,'ACTIVE',1,0
+  WHERE NOT EXISTS(SELECT 1 FROM iam_permission WHERE id=5105024);
+  SET changed_rows=changed_rows+ROW_COUNT();
+  INSERT INTO iam_permission
+    (id,tenant_id,app_code,permission_type,parent_id,permission_code,permission_name,route_path,http_method,sort_no,status,built_in,deleted)
+  SELECT 5105025,0,'PLATFORM','BUTTON',5105041,'platform:finance:fee-source:edit','编辑财务费用来源',NULL,'PUT',160,'ACTIVE',1,0
+  WHERE NOT EXISTS(SELECT 1 FROM iam_permission WHERE id=5105025);
+  SET changed_rows=changed_rows+ROW_COUNT();
+  UPDATE iam_permission SET status='ACTIVE',deleted=0
+  WHERE id IN(5105024,5105025) AND (status<>'ACTIVE' OR deleted<>0);
+  SET changed_rows=changed_rows+ROW_COUNT();
+  INSERT INTO iam_role_permission(tenant_id,role_id,permission_id,created_at)
+  SELECT 0,4000001,p.id,CURRENT_TIMESTAMP(3) FROM iam_permission p WHERE p.id IN(5105024,5105025)
+    AND NOT EXISTS(SELECT 1 FROM iam_role_permission rp WHERE rp.role_id=4000001 AND rp.permission_id=p.id);
+  SET changed_rows=changed_rows+ROW_COUNT();
+
+  -- 只有真实变更才推进版本；枚举所有既有管理员成员，不依赖当前登录用户，也不遗漏停用成员。
+  IF changed_rows>0 THEN
+    INSERT INTO iam_security_subject_version(auth_user_id,permission_version)
+    SELECT DISTINCT u.auth_user_id,1 FROM iam_user u
+    JOIN iam_membership m ON m.user_id=u.id AND m.tenant_id=0
+    JOIN iam_membership_role mr ON mr.membership_id=m.id AND mr.tenant_id=m.tenant_id AND mr.role_id=4000001
+    WHERE u.auth_user_id IS NOT NULL
+    ON DUPLICATE KEY UPDATE permission_version=permission_version+1;
+  END IF;
+  IF (SELECT COUNT(*) FROM iam_role_permission rp JOIN iam_permission p ON p.id=rp.permission_id
+      WHERE rp.role_id=4000001 AND rp.tenant_id=0 AND p.id IN(5105024,5105025)
+      AND p.tenant_id=0 AND p.app_code='PLATFORM' AND p.permission_type='BUTTON'
+      AND p.status='ACTIVE' AND p.deleted=0)<>2 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Canonical fee write grants incomplete; repair rolled back';
+  END IF;
+  COMMIT;
+  SELECT changed_rows AS repaired_catalog_or_grant_rows;
+END$$
+DELIMITER ;
+CALL repair_overseas_fee_canonical_write();
+DROP PROCEDURE repair_overseas_fee_canonical_write;
+
+-- 核验1：必须恰好两行，角色4000001、tenant=0、BUTTON、ACTIVE、deleted=0。
+SELECT r.id AS role_id,r.role_code,rp.tenant_id,p.id AS permission_id,p.permission_code,
+       p.permission_type,p.status,p.deleted
+FROM iam_role r JOIN iam_role_permission rp ON rp.role_id=r.id
+JOIN iam_permission p ON p.id=rp.permission_id
+WHERE r.id=4000001 AND p.id IN(5105024,5105025) ORDER BY p.id;
+-- 核验2：仅查看既有管理员主体与当前版本，不创建或切换任何成员角色。
+SELECT DISTINCT u.auth_user_id,m.id AS membership_id,u.status AS user_status,m.status AS membership_status,
+       COALESCE(sv.permission_version,0) AS permission_version
+FROM iam_user u JOIN iam_membership m ON m.user_id=u.id AND m.tenant_id=0
+JOIN iam_membership_role mr ON mr.membership_id=m.id AND mr.tenant_id=m.tenant_id AND mr.role_id=4000001
+LEFT JOIN iam_security_subject_version sv ON sv.auth_user_id=u.auth_user_id
+ORDER BY u.auth_user_id,m.id;

deploy/sql/overseas-fee-remark-add.sql

@@ -0,0 +1,19 @@
+-- 海外人工费用说明字段。仅修改 baiyue_lastleg.ll_finance_fee_source 的结构。
+-- 执行需单独授权；使用独立连接、遇错停止。先执行本脚本，再加载配套 Lastleg 代码。
+-- 无业务数据回填、费用重建、资金操作或菜单变更。已有字段时跳过新增。
+USE baiyue_lastleg;
+
+SET @overseas_fee_remark_ddl = (
+  SELECT IF(EXISTS(
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = DATABASE() AND table_name = 'll_finance_fee_source' AND column_name = 'fee_remark'
+  ), 'SELECT ''fee_remark already exists'' AS result',
+     'ALTER TABLE ll_finance_fee_source ADD COLUMN fee_remark VARCHAR(500) NULL COMMENT ''费用说明，补收或重复作业原因'' AFTER fee_item_name')
+);
+PREPARE overseas_fee_remark_stmt FROM @overseas_fee_remark_ddl;
+EXECUTE overseas_fee_remark_stmt;
+DEALLOCATE PREPARE overseas_fee_remark_stmt;
+
+SELECT table_schema, table_name, column_name, column_type, is_nullable, column_comment
+FROM information_schema.columns
+WHERE table_schema = 'baiyue_lastleg' AND table_name = 'll_finance_fee_source' AND column_name = 'fee_remark';

deploy/sql/overseas-storage-rent-zero-fee-repair.sql

@@ -0,0 +1,73 @@
+-- 固定目标本机 baiyue_lastleg，只修复自动免费仓租结构，不更新业务数据。
+-- 使用独立连接、遇错停止；先核对既有表结构，不能重放空库初始化。
+USE baiyue_lastleg;
+SELECT COLUMN_NAME,COLUMN_TYPE,IS_NULLABLE FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME='ll_finance_fee_source'
+  AND COLUMN_NAME IN ('amount','original_amount','exchange_rate','created_by','fee_item_code','direction');
+
+-- 上次 CALL 前置检查失败可能遗留本专用过程，仅清理本脚本自己的过程后重建。
+DROP PROCEDURE IF EXISTS storage_rent_zero_fee_repair_20261023;
+DELIMITER $$
+CREATE PROCEDURE storage_rent_zero_fee_repair_20261023()
+BEGIN
+    DECLARE checked_columns INT DEFAULT 0;
+    DECLARE checked_constraints INT DEFAULT 0;
+    DECLARE rate_type VARCHAR(64);
+    DECLARE rate_comment TEXT;
+    DECLARE rate_default TEXT;
+    DECLARE rate_default_sql TEXT;
+    IF DATABASE()<>'baiyue_lastleg' THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='目标必须为 baiyue_lastleg';
+    END IF;
+    SELECT COUNT(*) INTO checked_columns FROM information_schema.COLUMNS
+    WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME='ll_finance_fee_source'
+      AND ((COLUMN_NAME IN ('amount','original_amount') AND DATA_TYPE='decimal' AND IS_NULLABLE='NO')
+        OR (COLUMN_NAME='exchange_rate' AND DATA_TYPE='decimal' AND EXTRA='')
+        OR (COLUMN_NAME IN ('created_by','fee_item_code','direction') AND DATA_TYPE='varchar' AND IS_NULLABLE='NO'));
+    SELECT COUNT(*) INTO checked_constraints FROM information_schema.TABLE_CONSTRAINTS
+    WHERE CONSTRAINT_SCHEMA=DATABASE() AND TABLE_NAME='ll_finance_fee_source'
+      AND CONSTRAINT_NAME='chk_ll_finance_fee_amount' AND CONSTRAINT_TYPE='CHECK';
+    IF checked_columns<>6 OR checked_constraints<>1 THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='费用源表字段或金额约束异常，停止修复';
+    END IF;
+    -- 增加新约束前只读检查；人工费用仍须正额且有效汇率，防止意外放宽。
+    IF EXISTS (SELECT 1 FROM ll_finance_fee_source
+        WHERE NOT ((amount>0 OR (amount=0 AND original_amount=0 AND created_by='STORAGE_RENT' AND fee_item_code='FEE_TYPE_077' AND direction='RECEIVABLE'))
+          AND ((exchange_rate IS NOT NULL AND exchange_rate>0) OR (exchange_rate IS NULL AND amount=0 AND original_amount=0 AND created_by='STORAGE_RENT' AND fee_item_code='FEE_TYPE_077' AND direction='RECEIVABLE')))) THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='存在不满足新约束的费用，停止且不改数据';
+    END IF;
+    SELECT COUNT(*) INTO checked_constraints FROM information_schema.TABLE_CONSTRAINTS
+    WHERE CONSTRAINT_SCHEMA=DATABASE() AND TABLE_NAME='ll_finance_fee_source'
+      AND CONSTRAINT_NAME='chk_ll_finance_fee_exchange_rate' AND CONSTRAINT_TYPE='CHECK';
+    IF checked_constraints=0 THEN
+        -- 保留真实已有列的精度和备注，不把存量 DECIMAL(18,8) 收窄到基线精度。
+        SELECT COLUMN_TYPE,COLUMN_COMMENT,COLUMN_DEFAULT INTO rate_type,rate_comment,rate_default
+        FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME='ll_finance_fee_source' AND COLUMN_NAME='exchange_rate';
+        IF rate_type NOT REGEXP '^decimal[(][0-9]+,[0-9]+[)]$' THEN
+            SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='汇率列不是预期定点数类型，停止修复';
+        END IF;
+        IF LOCATE('自动零元仓租可空',rate_comment)=0 THEN
+            SET rate_comment=CONCAT(rate_comment,'，自动零元仓租可空');
+        END IF;
+        -- 保留既有数值默认值（例如1.00000000）；拒绝表达式或非数值默认值。
+        IF rate_default IS NOT NULL AND rate_default NOT REGEXP '^-?[0-9]+([.][0-9]+)?$' THEN
+            SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='汇率默认值不是预期数值，停止修复';
+        END IF;
+        SET rate_default_sql=IF(rate_default IS NULL,' DEFAULT NULL',CONCAT(' DEFAULT ',rate_default));
+        -- 单次原子 ALTER 同步调整可空性与两项约束，原币及结算列完全不改。
+        SET @storage_rent_zero_fee_ddl=CONCAT(
+          'ALTER TABLE baiyue_lastleg.ll_finance_fee_source DROP CHECK chk_ll_finance_fee_amount, ',
+          'MODIFY COLUMN exchange_rate ',rate_type,' NULL',rate_default_sql,' COMMENT ',QUOTE(rate_comment),', ',
+          'ADD CONSTRAINT chk_ll_finance_fee_amount CHECK(amount>0 OR (amount=0 AND original_amount=0 AND created_by=''STORAGE_RENT'' AND fee_item_code=''FEE_TYPE_077'' AND direction=''RECEIVABLE'')), ',
+          'ADD CONSTRAINT chk_ll_finance_fee_exchange_rate CHECK((exchange_rate IS NOT NULL AND exchange_rate>0) OR (exchange_rate IS NULL AND amount=0 AND original_amount=0 AND created_by=''STORAGE_RENT'' AND fee_item_code=''FEE_TYPE_077'' AND direction=''RECEIVABLE''))');
+        PREPARE storage_rent_zero_fee_stmt FROM @storage_rent_zero_fee_ddl;
+        EXECUTE storage_rent_zero_fee_stmt;
+        DEALLOCATE PREPARE storage_rent_zero_fee_stmt;
+        SET @storage_rent_zero_fee_ddl=NULL;
+    END IF;
+END$$
+DELIMITER ;
+CALL storage_rent_zero_fee_repair_20261023();
+DROP PROCEDURE storage_rent_zero_fee_repair_20261023;
+SHOW CREATE TABLE ll_finance_fee_source;

deploy/sql/warehouse-supplier-query-structure-repair.sql

@@ -0,0 +1,40 @@
+-- 供应商查询缺失结构修复。MySQL 8；仅用于本次明确授权的本机开发库。
+-- 固定目标 baiyue_warehouse；不修改供应商、费用、余额或授信数据。
+-- 已有结构安全跳过；不推断历史拖车供应商的国内/海外类别。
+-- DDL 会隐式提交，请在独立连接以遇错停止模式整份执行。
+USE baiyue_warehouse;
+SET NAMES utf8mb4;
+SELECT DATABASE() AS target_database;
+
+-- 先确认正式供应商主表存在；不存在时 ALTER 会报错并停止，不创建第二份主档。
+SET @supplier_query_column_ddl = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns
+          WHERE table_schema = 'baiyue_warehouse'
+            AND table_name = 'wh_supplier' AND column_name = 'trucking_scope'),
+  'SELECT ''trucking_scope 已存在，跳过'' AS structure_result',
+  'ALTER TABLE baiyue_warehouse.wh_supplier ADD COLUMN trucking_scope VARCHAR(16) NULL COMMENT ''拖车类型：DOMESTIC国内拖车、OVERSEAS海外车队；非拖车为空'' AFTER category'
+);
+PREPARE supplier_query_statement FROM @supplier_query_column_ddl;
+EXECUTE supplier_query_statement;
+DEALLOCATE PREPARE supplier_query_statement;
+
+-- 正式列表还会读取船司关联；若未初始化，仅按当前模块基线建立空表。
+CREATE TABLE IF NOT EXISTS wh_supplier_carrier (
+  supplier_id BIGINT UNSIGNED NOT NULL COMMENT 'BOOKING供应商ID',
+  tenant_id BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '平台公共作用域，固定为0',
+  carrier_code VARCHAR(16) NOT NULL COMMENT '船司标准编码',
+  created_by BIGINT UNSIGNED NULL COMMENT '创建人ID',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  PRIMARY KEY (supplier_id,carrier_code),
+  KEY idx_wh_supplier_carrier_code (tenant_id,carrier_code,supplier_id),
+  CONSTRAINT chk_wh_supplier_carrier_tenant CHECK (tenant_id = 0),
+  CONSTRAINT chk_wh_supplier_carrier_code CHECK (carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER'))
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='BOOKING供应商与标准船司编码多对多关联';
+
+-- 执行后只核对结构，不读取供应商联系信息。
+SELECT table_name, column_name, column_type, is_nullable
+FROM information_schema.columns
+WHERE table_schema = 'baiyue_warehouse'
+  AND ((table_name = 'wh_supplier' AND column_name = 'trucking_scope')
+       OR table_name = 'wh_supplier_carrier')
+ORDER BY table_name, ordinal_position;

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

@@ -1,4 +1,5 @@
 -- CN 当前纯空库初始化入口（文件名沿用原入口，不提供增量升级语义）。
+-- 海外费用菜单及平台管理员授权统一在本文件 IAM 种子中维护，不再单列本次版本或专项菜单脚本。
 -- MySQL 8.0+；只允许目标测试环境的服务 schema 为空，已有表立即报错；禁止 --force/遇错继续。
 -- 字段、索引、约束及注释直接定义在 CREATE TABLE 内；不回填、不清理、不改造存量。
 -- 国内 IAM 管理两区域权限；海外不访问国内库。执行方法及系统种子清单见同目录 README.md。
@@ -1484,7 +1485,6 @@ CREATE TABLE fl_container_booking (
   KEY idx_container_booking_voyage (voyage_no,updated_at),
   KEY idx_container_booking_transit_summary (actual_sailing_at,actual_warehouse_arrival_at,ocean_booking_id,container_type),
   CONSTRAINT chk_container_booking_capacity CHECK (((capacity_cbm is null) or (capacity_cbm > 0))),
-  CONSTRAINT chk_container_booking_iso6346 CHECK (((container_no is null) or regexp_like(container_no,_utf8mb4'^[A-Z]{3}[UJZ][0-9]{7}$'))),
   CONSTRAINT chk_container_booking_pickup_code CHECK (((pickup_code is null) or regexp_like(pickup_code,_utf8mb4'^[0-9]{1,64}$'))),
   CONSTRAINT chk_container_booking_record_status CHECK ((record_status in (_utf8mb4'ACTIVE',_utf8mb4'MERGED'))),
   CONSTRAINT chk_container_booking_source CHECK ((source_type in (_utf8mb4'SIMULATION',_utf8mb4'OCEAN_BOOKING'))),
@@ -6049,7 +6049,7 @@ END$$
 
 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)
@@ -6074,7 +6074,6 @@ BEGIN
     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)
@@ -6089,7 +6088,7 @@ BEGIN
     AND (NEW.created_at <=> OLD.created_at)
     AND NEW.version = OLD.version + 1
   ) THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱运输资料不可修改，仅允许补录实货量';
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱仅允许维护预计到港及补录实货量';
   END IF;
   IF OLD.status <> NEW.status AND NOT (
        (OLD.status='DRAFT' AND NEW.status='RELEASED')) THEN
@@ -8460,4 +8459,8 @@ CREATE TABLE wh_document_sequence (
   CONSTRAINT chk_wh_document_sequence_value CHECK (current_value > 0)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='业务单据每日独立原子流水';
 
+-- 海外费用查询菜单；编辑、审核继续使用独立财务按钮授权。
+USE baiyue_iam;
+INSERT INTO iam_permission (id,tenant_id,app_code,permission_type,parent_id,permission_code,permission_name,route_path,http_method,sort_no,status,built_in,created_at,updated_at,deleted) VALUES (5117200,0,'PLATFORM','MENU',0,'platform:overseas-fee:list','海外费用管理','/overseas-business/fees','GET',890,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
+INSERT INTO iam_role_permission (role_id,permission_id,tenant_id,created_at) VALUES (4000001,5117200,0,CURRENT_TIMESTAMP(3));
 SELECT 'PASS' AS initialization_status, 'CN' AS region, 229 AS initialized_tables;

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

@@ -1,4 +1,5 @@
 -- OVERSEAS 当前纯空库初始化入口（文件名沿用原入口，不提供增量升级语义）。
+-- 海外费用资金、仓租四表、审核人名称快照、采购退款请求幂等字段及唯一索引均在本文件最终建表定义中维护。
 -- MySQL 8.0+；只允许目标测试环境的服务 schema 为空，已有表立即报错；禁止 --force/遇错继续。
 -- 字段、索引、约束及注释直接定义在 CREATE TABLE 内；不回填、不清理、不改造存量。
 -- 国内 IAM 管理两区域权限；海外不访问国内库。执行方法及系统种子清单见同目录 README.md。
@@ -314,7 +315,7 @@ CREATE TABLE ll_destuff_pallet_cost_allocation (
   customer_id varchar(128) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '客户ID',
   actual_volume_cbm decimal(20,6) NOT NULL COMMENT '客户实收体积',
   allocated_amount decimal(20,2) NOT NULL COMMENT '客户分摊金额',
-  fee_source_id bigint NOT NULL COMMENT '海外费用来源ID',
+  fee_source_id bigint DEFAULT NULL COMMENT '人工审核后关联的海外费用来源ID',
   created_at datetime(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
   PRIMARY KEY (id),
   UNIQUE KEY uk_ll_destuff_customer (cost_id,customer_id),
@@ -417,7 +418,7 @@ CREATE TABLE ll_dispatch_order (
   id BIGINT NOT NULL COMMENT '整车排车主单内部主键',
   dispatch_no VARCHAR(64) NOT NULL COMMENT '真实排车业务号',
   task_type VARCHAR(32) NOT NULL DEFAULT 'DELIVERY' COMMENT '任务类型：仓库派送、到仓取货、本土卡车',
-  publish_looseboard_demand TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否向内部散板需求池发布余位',
+  publish_looseboard_demand TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否向内部散板需求池发布余位',
   trip_id BIGINT NOT NULL COMMENT '本趟唯一车辆资源记录ID',
   overseas_warehouse_id VARCHAR(128) NOT NULL COMMENT '真实起运海外仓ID',
   overseas_warehouse_code VARCHAR(128) NULL COMMENT '起运海外仓编码快照',
@@ -947,6 +948,7 @@ CREATE TABLE ll_finance_fee_source (
   warehouse_id bigint DEFAULT NULL COMMENT '关联海外仓ID',
   fee_item_code varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '费用项目编码快照',
   fee_item_name varchar(200) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '费用项目名称快照',
+  fee_remark varchar(500) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '费用说明，补收或重复作业原因',
   direction varchar(16) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT 'RECEIVABLE应收或PAYABLE应付',
   supplier_id bigint DEFAULT NULL COMMENT '应付供应商ID',
   supplier_name varchar(200) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '应付供应商名称快照',
@@ -962,7 +964,7 @@ CREATE TABLE ll_finance_fee_source (
   amount decimal(20,6) NOT NULL COMMENT '人民币结算金额',
   original_currency char(3) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '业务原币种，支持CNY或USD',
   original_amount decimal(20,6) NOT NULL COMMENT '业务原币金额',
-  exchange_rate decimal(20,6) NOT NULL COMMENT '原币折算人民币汇率，人民币固定为1',
+  exchange_rate decimal(20,6) DEFAULT NULL COMMENT '原币折算人民币汇率，人民币固定为1，自动零元仓租可空',
   exchange_rate_month char(7) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '汇率月份yyyy-MM',
   chargeable_quantity decimal(20,6) DEFAULT NULL COMMENT '计费数量，如箱数、托数、体积或天数',
   quantity_unit varchar(32) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '计费数量单位',
@@ -974,6 +976,7 @@ CREATE TABLE ll_finance_fee_source (
   source_status varchar(16) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT 'ACTIVE、SUPERSEDED或VOIDED',
   review_reason varchar(500) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '审核或作废原因',
   reviewer_id varchar(128) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '审核人ID',
+  reviewer_name varchar(255) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '审核人名称快照',
   reviewed_at datetime(3) DEFAULT NULL COMMENT '审核时间',
   created_by varchar(128) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '创建人ID',
   updated_by varchar(128) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '最后更新人ID',
@@ -984,7 +987,8 @@ CREATE TABLE ll_finance_fee_source (
   KEY idx_ll_finance_fee_customer (customer_id,source_status,created_at),
   KEY idx_ll_finance_fee_business (business_type,business_no,created_at),
   KEY idx_ll_finance_fee_container_customer (container_booking_id,customer_id,source_status,created_at),
-  CONSTRAINT chk_ll_finance_fee_amount CHECK ((amount > 0)),
+  CONSTRAINT chk_ll_finance_fee_exchange_rate CHECK((exchange_rate IS NOT NULL AND exchange_rate>0) OR (exchange_rate IS NULL AND amount=0 AND original_amount=0 AND created_by='STORAGE_RENT' AND fee_item_code='FEE_TYPE_077' AND direction='RECEIVABLE')),
+  CONSTRAINT chk_ll_finance_fee_amount CHECK(amount>0 OR (amount=0 AND original_amount=0 AND created_by='STORAGE_RENT' AND fee_item_code='FEE_TYPE_077' AND direction='RECEIVABLE')),
   CONSTRAINT chk_ll_finance_fee_currency CHECK ((currency = _utf8mb4'CNY')),
   CONSTRAINT chk_ll_finance_fee_direction CHECK ((direction in (_utf8mb4'RECEIVABLE',_utf8mb4'PAYABLE'))),
   CONSTRAINT chk_ll_finance_fee_original_currency CHECK ((original_currency in (_utf8mb4'CNY',_utf8mb4'USD'))),
@@ -2122,6 +2126,7 @@ CREATE TABLE ll_overseas_procurement_file (
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='海外采购签收文件及费用凭证';
 
 CREATE TABLE ll_overseas_procurement_order (
+  procurement_direction VARCHAR(32) NOT NULL DEFAULT 'OVERSEAS_TO_DOMESTIC' COMMENT '采购方向：海外采购回国内/国内采购发海外',
   id bigint NOT NULL COMMENT '主键ID',
   customer_id varchar(128) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '客户租户ID',
   customer_name varchar(255) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '客户名称快照',
@@ -4593,6 +4598,7 @@ CREATE TABLE ll_return_sku_conversion (
  quantity BIGINT NOT NULL COMMENT '实际完成转换件数',
  status VARCHAR(32) NOT NULL COMMENT 'APPLIED待客户确认/CONFIRMED已确认/REVERSED退回冲回',
  ownership_json LONGTEXT NOT NULL COMMENT '本次转换件数的来源退货单快照，供精确冲回',
+ storage_rent_shares_json LONGTEXT NULL COMMENT '原仓租批次迁移快照',
  completed_at DATETIME(3) NOT NULL COMMENT '实物SKU转换时间',
  confirmed_at DATETIME(3) NULL COMMENT '客户确认时间',
  reversed_at DATETIME(3) NULL COMMENT '退回冲回时间',
@@ -4987,4 +4993,131 @@ CREATE TABLE ll_document_sequence (
   CONSTRAINT chk_ll_document_sequence_value CHECK (current_value > 0)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='业务单据每日独立原子流水';
 
-SELECT 'PASS' AS initialization_status, 'OVERSEAS' AS region, 234 AS initialized_tables;
+-- 海外费用资金及实收仓租。
+-- 海外人工费用资金编排。金额与余额以 Finance 钱包为唯一事实，本表仅记录指令及回执状态。
+CREATE TABLE ll_finance_fee_funding (
+  source_fee_id BIGINT NOT NULL COMMENT '关联海外费用稳定来源ID',
+  customer_id VARCHAR(128) NOT NULL COMMENT '费用所属客户隔离标识',
+  collection_mode VARCHAR(16) NOT NULL COMMENT '客户收费方式：BILL账单结算，WALLET余额及授信',
+  wallet_status VARCHAR(32) NOT NULL COMMENT '资金进度：待冻结、已冻结、待扣款、已扣款、待释放及失败状态',
+  wallet_business_no VARCHAR(128) NULL COMMENT '本次冻结使用的独立业务编号，重提使用新编号',
+  command_event_id VARCHAR(64) NULL COMMENT '当前待处理资金指令事件ID',
+  wallet_hold_id VARCHAR(64) NULL COMMENT 'Finance确认的资金冻结记录ID',
+  wallet_ledger_id VARCHAR(64) NULL COMMENT 'Finance确认的已扣资金流水ID',
+  command_version BIGINT NOT NULL DEFAULT 0 COMMENT '资金指令单调递增版本，防止重试重复入账',
+  error_message VARCHAR(500) NULL COMMENT '最新资金失败原因，成功后清空',
+  command_history JSON NOT NULL COMMENT '已发资金指令及核验结果哈希，识别重复和错序回执',
+  created_at DATETIME(3) NOT NULL COMMENT '资金编排创建UTC时间',
+  updated_at DATETIME(3) NOT NULL COMMENT '资金编排最近变更UTC时间',
+  PRIMARY KEY (source_fee_id),
+  KEY idx_ll_fee_funding_customer_state (customer_id, wallet_status),
+  KEY idx_ll_fee_funding_command (command_event_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='海外人工费用资金冻结、审核扣款及释放编排';
+
+CREATE TABLE IF NOT EXISTS ll_storage_rent_inbound (
+  receipt_id bigint NOT NULL COMMENT '实际入库凭证主键，防止重复累计计租数量',
+  lot_id bigint NOT NULL COMMENT '头程同单同仓计租批次主键',
+  quantity decimal(24,12) NOT NULL COMMENT '本次实收追加计租箱数',
+  created_at datetime(3) NOT NULL COMMENT '计租登记时间，采用协调世界时',
+  PRIMARY KEY (receipt_id),
+  KEY idx_storage_rent_inbound_lot (lot_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='头程实收计租幂等登记';
+
+CREATE TABLE ll_storage_rent_lot (
+  id bigint NOT NULL COMMENT '原批次主键',
+  source_key varchar(80) NOT NULL COMMENT '实收来源幂等键',
+  customer_id varchar(32) NOT NULL COMMENT '客户标识',
+  customer_name varchar(255) DEFAULT NULL COMMENT '客户名称',
+  warehouse_id varchar(32) NOT NULL COMMENT '海外仓标识',
+  warehouse_name varchar(255) DEFAULT NULL COMMENT '海外仓名称',
+  business_type varchar(32) NOT NULL COMMENT '原入库业务类型',
+  business_id bigint NOT NULL COMMENT '原入库业务主键',
+  business_no varchar(128) NOT NULL COMMENT '原入库业务单号',
+  order_id bigint DEFAULT NULL COMMENT '尾程订单主键',
+  inbound_code varchar(128) DEFAULT NULL COMMENT '入仓码',
+  balance_id bigint DEFAULT NULL COMMENT '普通库存余额主键',
+  batch_no varchar(128) DEFAULT NULL COMMENT '原实收批次',
+  sku_code varchar(128) DEFAULT NULL COMMENT '商品编码',
+  rule_code varchar(32) NOT NULL COMMENT '仓租规则',
+  original_quantity decimal(24,12) NOT NULL COMMENT '实收原始数量',
+  remaining_quantity decimal(24,12) NOT NULL COMMENT '未出库原始数量',
+  original_units decimal(24,12) DEFAULT NULL COMMENT '原批次计费体积或托数',
+  inbound_at datetime(3) NOT NULL COMMENT '实际入库时间',
+  created_at datetime(3) NOT NULL COMMENT '创建时间',
+  updated_at datetime(3) NOT NULL COMMENT '更新时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_storage_rent_lot_source (source_key),
+  KEY idx_storage_rent_stock (balance_id,batch_no),
+  KEY idx_storage_rent_customer (customer_id,warehouse_id,inbound_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='实收计租原批次';
+
+CREATE TABLE ll_storage_rent_share (
+  balance_id bigint DEFAULT NULL COMMENT '普通库存当前余额，退货箱份额为空',
+  batch_no varchar(128) DEFAULT NULL COMMENT '普通库存当前批次，换标搬移保持原计租批次引用',
+  id bigint NOT NULL COMMENT '份额主键',
+  lot_id bigint NOT NULL COMMENT '原计租批次主键',
+  customer_id varchar(32) NOT NULL COMMENT '客户标识',
+  warehouse_id varchar(32) NOT NULL COMMENT '海外仓标识',
+  carton_mark varchar(255) DEFAULT NULL COMMENT '当前箱唛',
+  sku_code varchar(128) DEFAULT NULL COMMENT '商品编码',
+  quantity decimal(24,12) NOT NULL COMMENT '剩余商品数量',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_storage_rent_return_share (lot_id,carton_mark,sku_code),
+  UNIQUE KEY uk_storage_rent_stock_share (lot_id,balance_id,batch_no),
+  KEY idx_storage_rent_carton (customer_id,warehouse_id,carton_mark),
+  KEY idx_storage_rent_share_stock (customer_id,warehouse_id,balance_id,batch_no)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='当前库存与原计租批次份额';
+
+CREATE TABLE ll_storage_rent_preparation (
+  id bigint NOT NULL COMMENT '预校验主键',
+  warehouse_id varchar(32) NOT NULL COMMENT '作业海外仓',
+  customer_id varchar(32) NOT NULL COMMENT '费用客户',
+  mode varchar(32) NOT NULL COMMENT '扫码类型',
+  execution_no varchar(128) NOT NULL COMMENT '实际作业单号',
+  request_key varchar(255) NOT NULL COMMENT '原扫码幂等键',
+  request_hash varchar(64) NOT NULL COMMENT '原扫码内容哈希',
+  attempt int NOT NULL COMMENT '冻结尝试次数',
+  business_type varchar(32) NOT NULL COMMENT '本次应收业务类型',
+  business_id bigint NOT NULL COMMENT '本次应收业务主键',
+  business_no varchar(128) NOT NULL COMMENT '本次应收业务单号',
+  status varchar(32) NOT NULL COMMENT '资金与扫码状态',
+  plan_json json NOT NULL COMMENT '原批次计费不可变快照',
+  original_amount decimal(24,12) NOT NULL COMMENT '原币仓租金额，币种见计费快照',
+  amount decimal(24,12) NOT NULL COMMENT '人民币结算金额',
+  exchange_rate decimal(24,12) NULL COMMENT '冻结确认汇率，免费出库为空',
+  exchange_rate_month varchar(7) NOT NULL COMMENT '汇率月份',
+  freeze_event_id varchar(128) DEFAULT NULL COMMENT '冻结指令事件',
+  settle_event_id varchar(128) DEFAULT NULL COMMENT '扣款指令事件',
+  release_event_id varchar(128) DEFAULT NULL COMMENT '解冻指令事件',
+  release_status varchar(32) DEFAULT NULL COMMENT '解冻回执状态，失败后由恢复任务重发',
+  wallet_version bigint NOT NULL COMMENT '同一预占资金命令版本，重试使用新版本保留审计',
+  hold_id varchar(128) DEFAULT NULL COMMENT '财务冻结主键',
+  ledger_id varchar(128) DEFAULT NULL COMMENT '财务扣款流水',
+  error_message varchar(1000) DEFAULT NULL COMMENT '资金处理结果',
+  source_fee_id bigint DEFAULT NULL COMMENT '财务费用来源主键',
+  created_at datetime(3) NOT NULL COMMENT '预校验时间',
+  consumed_at datetime(3) DEFAULT NULL COMMENT '实际扫描出库时间',
+  updated_at datetime(3) NOT NULL COMMENT '更新时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_storage_rent_request (warehouse_id,mode,request_key,attempt),
+  KEY idx_storage_rent_execution (mode,execution_no,status),
+  KEY idx_storage_rent_business (customer_id,business_no),
+  KEY idx_storage_rent_recovery (status,updated_at),
+  KEY idx_storage_rent_release (release_status,updated_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='仓租扫码资金预占与结算快照';
+
+CREATE TABLE ll_fleet_resource_photo (
+  resource_kind VARCHAR(16) NOT NULL COMMENT '档案类型：车辆或司机',
+  resource_id BIGINT NOT NULL COMMENT '车辆或司机档案标识',
+  record_version BIGINT NOT NULL COMMENT '照片版本，从一递增',
+  file_id BIGINT NOT NULL COMMENT '文件服务照片标识',
+  file_name VARCHAR(512) NOT NULL COMMENT '照片原始文件名',
+  content_type VARCHAR(64) NOT NULL COMMENT '照片媒体类型',
+  size_bytes BIGINT NOT NULL COMMENT '照片字节数',
+  created_by VARCHAR(64) NOT NULL COMMENT '上传操作人标识',
+  created_at DATETIME(3) NOT NULL COMMENT '上传时间（UTC）',
+  PRIMARY KEY (resource_kind, resource_id, record_version),
+  UNIQUE KEY uk_fleet_resource_photo_file (resource_kind, resource_id, file_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆及司机档案照片版本记录';
+
+SELECT 'PASS' AS initialization_status, 'OVERSEAS' AS region, 240 AS initialized_tables;

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

@@ -7,6 +7,8 @@ import java.util.Arrays;
 
 /** File-owned storage policy. Business visibility and lifecycle remain in the calling service. */
 enum BusinessFileCategory {
+    FLEET_VEHICLE_PHOTO(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
+    FLEET_DRIVER_PHOTO(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     FLEET_DRIVER_LICENSE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     FLEET_TRIP_OPERATION_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     OVERSEAS_DISPATCH_VEHICLE_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
@@ -90,7 +92,7 @@ enum BusinessFileCategory {
         if (this == FINANCE_VEHICLE_VOUCHER && tenantId != 0) {
             throw new BizException(ResultCode.BAD_REQUEST, "公司车辆付款凭证必须归属平台");
         }
-        if (this == FLEET_VEHICLE_RECORD_PHOTO && tenantId != 0) {
+        if ((this == FLEET_VEHICLE_RECORD_PHOTO || this == FLEET_VEHICLE_PHOTO || this == FLEET_DRIVER_PHOTO) && tenantId != 0) {
             throw new BizException(ResultCode.BAD_REQUEST, "车辆运维照片必须归属平台");
         }
         if (this == FLEET_DRIVER_LICENSE && tenantId != 0) {

file/src/main/resources/openapi/fleet-resource-photo-v1.yaml

@@ -0,0 +1,88 @@
+openapi: 3.0.3
+info:
+  title: 车辆与司机档案照片内部文件契约
+  version: 1.0.0
+  description: >-
+    复用InternalBusinessFileController，固定平台tenantId=0、businessType=FLEET_VEHICLE_PHOTO或FLEET_DRIVER_PHOTO、
+    businessId=对应车辆或司机内部ID。Lastleg负责档案存在性、列表/维护权限、版本关联和历史可见性；
+    File校验内部服务令牌、平台复合归属、真实非空文件、MIME与签名。最大10MiB，仅JPG/PNG。
+    上传只生成不可变对象，不改变驾驶证审核结论，不生成公开URL，排车保存时复制为本趟证据，后续档案替换不改历史排车。
+security:
+  - InternalServiceToken: []
+paths:
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+    post:
+      summary: 上传车辆或司机档案照片
+      parameters:
+        - {name: X-Operator-Id, in: header, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file: {type: string, format: binary}
+      responses:
+        '200': {$ref: '#/components/responses/Metadata'}
+        '403': {description: 内部服务令牌无效}
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}/{fileId}:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+      - {$ref: '#/components/parameters/FileId'}
+    get:
+      summary: 校验归属并读取元数据
+      responses:
+        '200': {$ref: '#/components/responses/Metadata'}
+        '403': {description: 内部服务令牌无效}
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}/{fileId}/content:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+      - {$ref: '#/components/parameters/FileId'}
+    get:
+      summary: 校验归属并下载真实文件
+      responses:
+        '200':
+          description: 文件内容，业务错误按JSON code识别
+          content:
+            image/jpeg: {schema: {type: string, format: binary}}
+            image/png: {schema: {type: string, format: binary}}
+        '403': {description: 内部服务令牌无效}
+components:
+  securitySchemes:
+    InternalServiceToken: {type: apiKey, in: header, name: X-Internal-Service-Token}
+  parameters:
+    TenantId: {name: tenantId, in: path, required: true, schema: {type: string, enum: ['0']}}
+    BusinessType: {name: businessType, in: path, required: true, schema: {type: string, enum: [FLEET_VEHICLE_PHOTO, FLEET_DRIVER_PHOTO]}}
+    BusinessId: {name: businessId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+    FileId: {name: fileId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+  responses:
+    Metadata:
+      description: 统一响应；业务成功code为200，复合归属不匹配按业务错误返回
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              code: {type: string}
+              message: {type: string, nullable: true}
+              data:
+                type: object
+                properties:
+                  fileId: {type: string}
+                  tenantId: {type: string, enum: ['0']}
+                  businessType: {type: string, enum: [FLEET_VEHICLE_PHOTO, FLEET_DRIVER_PHOTO]}
+                  businessId: {type: string}
+                  fileName: {type: string}
+                  sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+                  contentType: {type: string, enum: [image/jpeg, image/png]}
+                  sizeBytes: {type: integer, format: int64, minimum: 1, maximum: 10485760}

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

@@ -0,0 +1,16 @@
+package com.baiyue.file.service;
+
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.*;
+
+class FleetResourcePhotoCategoryTest {
+    @Test void profilePhotosOnlyAllowPlatformImagesAndPositiveResourceIdentities() {
+        for(var category : new BusinessFileCategory[]{BusinessFileCategory.FLEET_VEHICLE_PHOTO,BusinessFileCategory.FLEET_DRIVER_PHOTO}) {
+            category.validateOwner(0);
+            assertThatThrownBy(() -> category.validateOwner(1)).hasMessageContaining("平台");
+            assertThat(category.formatPolicy()).isEqualTo(BusinessFileCategory.FormatPolicy.IMAGE);
+            assertThat(category.maxSizeBytes()).isEqualTo(10L*1024*1024);
+            assertThatThrownBy(() -> category.storageBusinessId("not-a-resource")).isInstanceOf(RuntimeException.class);
+        }
+    }
+}

finance/AGENTS.md

@@ -23,7 +23,7 @@
 | 客户只读账单、收款与应收 API | `controller/ClientFinanceController.java`，统一前缀 `/api/client/finance/v1` |
 | 订单与客户账户、费用来源审核与结算纳入 | `controller/FinancePhase1OperationController.java`、`service/FinancePhase1OperationService.java` |
 | 客户财务账户汇总 | `service/FinanceCustomerAccountService.java`、`client/IamCustomerClient.java`；客户主档事实仍归 IAM |
-| 客户资金账户、授信与充值 | `controller/ClientFinanceWalletController.java`、`controller/PlatformFinanceWalletController.java`、`controller/InternalFinanceWalletController.java`、`service/FinanceWalletService.java`、`dto/FinanceWalletDtos.java`；支持静态收款码、截图申请、平台审核、手工充扣、授信配置及供业务模块使用的冻结/结算/释放，第三方支付回调尚未接入 |
+| 客户资金账户、授信与充值 | `controller/ClientFinanceWalletController.java`、`controller/PlatformFinanceWalletController.java`、`controller/InternalFinanceWalletController.java`、`service/FinanceWalletService.java`、`dto/FinanceWalletDtos.java`；支持静态收款码、截图申请、平台审核、手工充扣、授信配置及供业务模块使用的冻结/结算/释放；原消费关联退款契约见 `src/main/resources/openapi/finance-wallet-refund-v1.yaml`，第三方支付回调尚未接入 |
 | 客户对账单 | `controller/ReconciliationStatementController.java`、`service/ReconciliationStatementService.java` |
 | 应收款月度统计 | `controller/ReceivableStatisticsController.java`、`service/ReceivableStatisticsService.java`、`dto/ReceivableStatisticsDtos.java`；按结算单生成月份和客户汇总 CNY 正式应收结算单 |
 | 应收/应付结算单 | `controller/FinanceSettlementController.java`、`service/FinanceSettlementService.java` |

finance/src/main/java/com/baiyue/finance/controller/PlatformFinanceWalletController.java

@@ -7,11 +7,16 @@ import com.baiyue.finance.dto.FinanceWalletDtos.CreditLimitRequest;
 import com.baiyue.finance.dto.FinanceWalletDtos.RechargeReviewRequest;
 import com.baiyue.finance.dto.FinancePhase1Dtos.PageEnvelope;
 import com.baiyue.finance.dto.FinanceWalletDtos.RechargeRequest;
+import com.baiyue.finance.dto.FinanceWalletDtos.WalletRefundRequest;
 import com.baiyue.finance.service.FinanceWalletService;
+import java.nio.charset.StandardCharsets;
+import java.util.UUID;
+import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.web.bind.annotation.*;
+import org.springframework.web.server.ResponseStatusException;
 
 @RestController
 @RequestMapping("/api/platform/finance/v1")
@@ -62,4 +67,25 @@ public class PlatformFinanceWalletController {
     @GetMapping("/recharge-requests/{requestId}/voucher")
     @PreAuthorize("hasAuthority('platform:finance:customer-account:list')")
     public ResponseEntity<byte[]> voucher(@PathVariable long requestId) { return service.voucher(requestId); }
+
+    /** 退款必须由平台财务针对原消费发起，复用资金服务的账户锁及累计可退上限。 */
+    @PostMapping("/accounts/{customerId}/ledger/{ledgerId}/refunds")
+    @PreAuthorize("hasAuthority('platform:finance:customer-account:adjust')")
+    public ApiResponse<?> refund(@AuthenticationPrincipal AuthenticatedUser user,
+                                 @PathVariable long customerId, @PathVariable long ledgerId,
+                                 @RequestHeader("Idempotency-Key") String idempotencyKey,
+                                 @RequestBody WalletRefundRequest request) {
+        if (user == null || user.userId() == null || !"PLATFORM".equals(user.appCode()) || !Long.valueOf(0L).equals(user.tenantId())) {
+            throw new ResponseStatusException(HttpStatus.FORBIDDEN, "仅平台财务可操作退款");
+        }
+        if (request == null || idempotencyKey == null || idempotencyKey.isBlank()
+            || idempotencyKey.trim().length() > 128) throw new IllegalArgumentException("退款请求及幂等键必填且幂等键不超过128字符");
+        if (request.reason() == null || request.reason().isBlank() || request.reason().length() > 500)
+            throw new IllegalArgumentException("退款原因必填且不超过500字符");
+        // 技术退款引用由客户和幂等键确定；资金流水号仍由正式 AC 编号生成器分配。
+        String refundNo = "MANUAL_REFUND:" + UUID.nameUUIDFromBytes(
+            (customerId + ":" + idempotencyKey.trim()).getBytes(StandardCharsets.UTF_8));
+        return FinanceResponses.success(service.refundConsumption(customerId, ledgerId, refundNo,
+            idempotencyKey.trim(), request.amount(), user.userId(), user.displayName(), request.reason().trim()));
+    }
 }

finance/src/main/java/com/baiyue/finance/dto/FinanceWalletDtos.java

@@ -54,6 +54,9 @@ public final class FinanceWalletDtos {
 
     public record WalletHoldActionRequest(String remark) { }
 
+    /** 关联原消费退款，原因必填，原流水保持不可变。 */
+    public record WalletRefundRequest(BigDecimal amount, String reason) { }
+
     public record WalletHold(long holdId, long customerId, String businessType,
                              String businessNo, BigDecimal amount,
                              BigDecimal actualFrozenAmount, BigDecimal creditFrozenAmount,

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

@@ -135,6 +135,7 @@ public class BusinessFeeSourceEventService {
             positive(value.walletSettlement().holdId(), "walletSettlement.holdId");
             positive(value.walletSettlement().ledgerId(), "walletSettlement.ledgerId");
             if (blank(value.walletSettlement().commandEventId())) throw error("FIN-EVT-012", "缺少原资金命令引用");
+            walletIdentity(value);
         } else if ("OVERSEAS_PROCUREMENT_FEE".equals(value.sourceType()) && "RECEIVABLE".equals(value.direction())) {
             throw error("FIN-EVT-012", "采购应收必须引用成功实扣资金，不能进入待收费池");
         }
@@ -154,7 +155,7 @@ public class BusinessFeeSourceEventService {
                 throw error("FIN-EVT-012", "应付来源供应商快照不一致");
             validateSettlement(value);
         } else if (!blank(value.supplierId()) || !blank(value.supplierName()) || !blank(value.supplierCategory())
-            || !blank(value.settlementMode()) || value.paidAt() != null
+            || value.settlementMode() != null && !Set.of("BILL", "WALLET").contains(value.settlementMode()) || value.paidAt() != null
             || !blank(value.paymentMethod()) || !blank(value.paymentReferenceNo())
             || (value.paymentVoucherFileIds() != null && !value.paymentVoucherFileIds().isEmpty())) {
             throw error("FIN-EVT-012", "应收来源不得携带供应商或付款事实");
@@ -202,9 +203,10 @@ public class BusinessFeeSourceEventService {
             long customerId = positive(source.customerId(), "customerId");
             long holdId = positive(reference.holdId(), "holdId");
             long ledgerId = positive(reference.ledgerId(), "ledgerId");
+            String[] identity = walletIdentity(source);
             List<Map<String, Object>> rows = jdbc.queryForList(
                 "SELECT l.amount,c.result_json FROM fin_wallet_hold h JOIN fin_wallet_ledger l ON l.id=h.action_ledger_id AND l.customer_id=h.customer_id JOIN fin_wallet_command_inbox c ON c.event_id=? AND c.status='SUCCEEDED' WHERE h.id=? AND l.id=? AND h.customer_id=? AND h.business_type=? AND h.business_no=? AND h.status='SETTLED' AND l.change_type='CONSUMPTION' FOR UPDATE",
-                reference.commandEventId(), holdId, ledgerId, customerId, source.businessType(), source.businessNo());
+                reference.commandEventId(), holdId, ledgerId, customerId, identity[0], identity[1]);
             if (rows.size() != 1 || !(rows.get(0).get("amount") instanceof java.math.BigDecimal amount)
                 || amount.negate().compareTo(source.totalAmount()) != 0) {
                 throw error("FIN-EVT-017", "费用来源与成功扣款的客户、业务或金额不匹配");
@@ -218,8 +220,8 @@ public class BusinessFeeSourceEventService {
                 || !reference.holdId().equals(result.path("walletHoldId").asText())
                 || !reference.ledgerId().equals(result.path("walletLedgerId").asText())
                 || result.path("customerId").asLong() != customerId
-                || !source.businessType().equals(result.path("businessType").asText())
-                || !source.businessNo().equals(result.path("businessNo").asText())
+                || !identity[0].equals(result.path("businessType").asText())
+                || !identity[1].equals(result.path("businessNo").asText())
                 || result.path("amount").decimalValue().compareTo(source.totalAmount()) != 0) {
                 throw error("FIN-EVT-017", "费用来源引用的资金结果不匹配");
             }
@@ -234,6 +236,25 @@ public class BusinessFeeSourceEventService {
             feeSourceId);
     }
 
+    /** 独立锁款仅接收已约定的人工费用或仓租身份，不能借此挂接任意业务扣款。 */
+    private String[] walletIdentity(BusinessFeeSourceChangedV1 source) {
+        var reference = source.walletSettlement();
+        String type = reference.walletBusinessType(), no = reference.walletBusinessNo();
+        if (type == null && no == null) return new String[]{source.businessType(), source.businessNo()};
+        if (blank(type) || blank(no) || !"LASTLEG".equals(source.sourceSystem()))
+            throw error("FIN-EVT-017", "资金业务引用不完整");
+        if ("OVERSEAS_MANUAL_FEE".equals(type)) {
+            if ("FEE_TYPE_077".equals(source.feeItemCode())
+                || !no.matches(java.util.regex.Pattern.quote(source.sourceFeeId()) + "-[1-9][0-9]*"))
+                throw error("FIN-EVT-017", "人工费用资金引用与来源不匹配");
+        } else if ("STORAGE_RENT".equals(type)) {
+            if (!"FEE_TYPE_077".equals(source.feeItemCode()))
+                throw error("FIN-EVT-017", "仓租资金引用与费用项目不匹配");
+            positive(no, "walletBusinessNo");
+        } else throw error("FIN-EVT-017", "不支持的独立资金业务引用");
+        return new String[]{type, no};
+    }
+
     private void materializeDirectPaidCost(String system, long feeId, BusinessFeeSourceChangedV1 value) {
         jdbc.update("INSERT INTO fin_cost(tenant_id,cost_no,cost_type,cost_origin,source_system,source_type,source_fee_id,source_fee_version,source_hash,order_id,inbound_id,container_id,warehouse_id,supplier_id,supplier_name_snapshot,fee_item_code,fee_item_name,currency_code,cost_amount,voucher_file_ids,paid_at,payment_method,payment_reference_no,status,confirmed_at,created_by,created_by_name,updated_by) VALUES(?,?,'SOURCE_DIRECT_PAID','BUSINESS_DIRECT_PAID',?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,'CONFIRMED',CURRENT_TIMESTAMP(3),0,'系统',0)",
             positive(value.customerId(), "customerId"), "DIRECT-" + system + '-' + value.sourceType() + '-' + feeId + "-V" + value.sourceVersion(),

finance/src/main/resources/openapi/finance-wallet-refund-v1.yaml

@@ -0,0 +1,61 @@
+openapi: 3.0.3
+info:
+  title: 平台资金账户关联退款
+  version: 1.0.0
+  description: 原消费保持不可变；退款记录关联原消费流水号，累计退款不得超过原消费金额，包含业务退款事件已退金额。
+paths:
+  /api/platform/finance/v1/accounts/{customerId}/ledger/{ledgerId}/refunds:
+    post:
+      operationId: refundWalletConsumption
+      summary: 原消费关联退款
+      description: 仅平台 tenantId=0 且具有 platform:finance:customer-account:adjust 权限可操作。账户行锁串行校验累计可退金额，无需前端提交账户版本。优先归还已用授信，再增加实际余额。相同键同请求返回原流水；相同键不同原消费或金额失败。非成功消费、跨客户原流水、超额退款均拒绝。
+      security:
+        - bearerAuth: []
+      parameters:
+        - {name: customerId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: ledgerId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [amount, reason]
+              properties:
+                amount: {type: number, minimum: 0.01, maximum: 999999999999.99, multipleOf: 0.01}
+                reason: {type: string, minLength: 1, maxLength: 500, description: 必填退款原因，不得仅空白}
+      responses:
+        '200':
+          description: 统一响应 code=200 成功；业务失败使用 FIN-REQ-400、FIN-WALLET-404、FIN-IDEMPOTENCY-CONFLICT 或 FIN-WALLET-REFUND-EXCEEDED 等业务码。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    $ref: '#/components/schemas/RefundLedgerEntry'
+        '403': {description: 非平台主体或缺少调账权限}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
+  schemas:
+    RefundLedgerEntry:
+      type: object
+      description: 完整返回 FinanceWalletDtos.WalletLedgerEntry，资金余额字段沿用账户流水协议。
+      properties:
+        ledgerId: {type: string}
+        businessNo: {type: string, description: 新退款流水正式 AC 单号}
+        changeType: {type: string, enum: [REFUND]}
+        amount: {type: number, description: 实际退款正金额}
+        sourceType: {type: string, enum: [BUSINESS_REFUND]}
+        sourceNo: {type: string, description: 客户及幂等键派生的稳定技术退款引用}
+        referenceNo: {type: string, description: 原消费流水 businessNo，用于关联及累计可退校验}
+        operatorName: {type: string, nullable: true}
+        remark: {type: string, description: 退款原因}
+        actualBalanceAfter: {type: number}
+        frozenBalanceAfter: {type: number}
+        availableBalanceAfter: {type: number}
+        creditUsedAfter: {type: number}
+        availableCreditAfter: {type: number}

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

@@ -286,4 +286,82 @@ class BusinessFeeSourceEventServiceTest {
             base.aggregateType(), base.aggregateId(), base.aggregateVersion(), null, base.traceId(), base.correlationId(), null,
             payload, EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(payload)));
     }
+
+    @Test
+    void manualConsumptionUsesDedicatedFundingIdentityWhilePreservingServiceOrder() {
+        verifyDedicatedConsumption("OVERSEAS_MANUAL_FEE", "701-2", "FEE_TYPE_071");
+    }
+
+    @Test
+    void rentConsumptionUsesPreparationIdentityWhilePreservingServiceOrder() {
+        verifyDedicatedConsumption("STORAGE_RENT", "445", "FEE_TYPE_077");
+    }
+
+    @Test
+    void dedicatedFundingCannotReferenceAnotherManualFeeOrWrongFeeItem() {
+        assertThatThrownBy(() -> service.consume(dedicatedEvent("OVERSEAS_MANUAL_FEE", "702-1", "FEE_TYPE_071")))
+            .hasMessageContaining("来源不匹配");
+        assertThatThrownBy(() -> service.consume(dedicatedEvent("STORAGE_RENT", "445", "FEE_TYPE_071")))
+            .hasMessageContaining("项目不匹配");
+        noFinancialWrites();
+    }
+
+    @Test
+    void dedicatedConsumptionCannotReuseHoldAlreadyLinkedToAnotherSource() {
+        stubDedicatedConsumption("STORAGE_RENT", "445");
+        when(jdbc.queryForList(startsWith("SELECT id FROM fin_fee_source WHERE wallet_hold_id="),
+            eq(Long.class), eq(9L), eq(901L))).thenReturn(List.of(902L));
+        assertThatThrownBy(() -> service.consume(dedicatedEvent("STORAGE_RENT", "445", "FEE_TYPE_077")))
+            .hasMessageContaining("已关联其他费用");
+        verify(jdbc, never()).update(startsWith("UPDATE fin_fee_source SET wallet_hold_id="), any(Object[].class));
+    }
+
+    @Test
+    void dedicatedConsumptionRejectsResultFromDifferentFundingBusiness() {
+        stubDedicatedConsumption("STORAGE_RENT", "445");
+        when(jdbc.queryForList(startsWith("SELECT l.amount,c.result_json"), eq("command-1"), eq(9L), eq(72L),
+            eq(10001L), eq("STORAGE_RENT"), eq("445"))).thenReturn(List.of(Map.of(
+                "amount", new BigDecimal("-120.00"), "result_json", """
+                    {"result":"SUCCEEDED","operation":"SETTLE","commandEventId":"command-1",
+                     "walletHoldId":"9","walletLedgerId":"72","customerId":10001,
+                     "businessType":"STORAGE_RENT","businessNo":"446","amount":120.00}
+                    """)));
+        assertThatThrownBy(() -> service.consume(dedicatedEvent("STORAGE_RENT", "445", "FEE_TYPE_077")))
+            .hasMessageContaining("资金结果不匹配");
+    }
+
+    private void verifyDedicatedConsumption(String type, String no, String item) {
+        stubDedicatedConsumption(type, no);
+        EventEnvelope event = dedicatedEvent(type, no, item);
+        service.consume(event);
+        verify(jdbc).update(startsWith("UPDATE fin_fee_source SET wallet_hold_id="), eq(9L), eq(901L), eq(10001L));
+        assertThat(event.payload().path("businessType").asText()).isEqualTo("WAREHOUSE_SERVICE");
+        assertThat(event.payload().path("businessNo").asText()).isEqualTo("PO-US-001");
+    }
+
+    private void stubDedicatedConsumption(String type, String no) {
+        when(jdbc.queryForObject(startsWith("SELECT id FROM fin_fee_source"), eq(Long.class),
+            eq("LASTLEG"), eq("OVERSEAS_WAREHOUSE_FEE"), eq(701L), eq(1))).thenReturn(901L);
+        ObjectNode result = json.createObjectNode();
+        result.put("result", "SUCCEEDED").put("operation", "SETTLE").put("commandEventId", "command-1")
+            .put("walletHoldId", "9").put("walletLedgerId", "72").put("customerId", 10001)
+            .put("businessType", type).put("businessNo", no).put("amount", new BigDecimal("120.00"));
+        when(jdbc.queryForList(startsWith("SELECT l.amount,c.result_json"), eq("command-1"), eq(9L), eq(72L),
+            eq(10001L), eq(type), eq(no))).thenReturn(List.of(Map.of(
+                "amount", new BigDecimal("-120.00"), "result_json", result.toString())));
+    }
+
+    private EventEnvelope dedicatedEvent(String type, String no, String item) {
+        EventEnvelope base = eventWithoutInbound();
+        ObjectNode payload = base.payload().deepCopy();
+        payload.put("feeItemCode", item);
+        payload.putObject("walletSettlement").put("commandEventId", "command-1").put("holdId", "9")
+            .put("ledgerId", "72").put("walletBusinessType", type).put("walletBusinessNo", no);
+        payload.putNull("action"); payload.putNull("sourceHash");
+        payload.put("sourceHash", EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(payload)));
+        payload.put("action", "PUBLISHED");
+        return new EventEnvelope(base.eventId(), base.eventType(), base.eventVersion(), base.occurredAt(), base.tenantId(),
+            base.aggregateType(), base.aggregateId(), base.aggregateVersion(), null, base.traceId(), base.correlationId(), null,
+            payload, EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(payload)));
+    }
 }

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

@@ -0,0 +1,54 @@
+package com.baiyue.finance;
+
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.finance.controller.PlatformFinanceWalletController;
+import com.baiyue.finance.dto.FinanceWalletDtos.WalletRefundRequest;
+import com.baiyue.finance.service.FinanceWalletService;
+import org.junit.jupiter.api.Test;
+import org.springframework.security.access.prepost.PreAuthorize;
+import java.math.BigDecimal;
+import java.util.Set;
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+/** 平台退款入口鉴权、必填原因和稳定幂等引用的回归。 */
+class PlatformFinanceWalletRefundControllerTest {
+    private final FinanceWalletService service = mock(FinanceWalletService.class);
+    private final PlatformFinanceWalletController controller = new PlatformFinanceWalletController(service);
+    private final WalletRefundRequest request = new WalletRefundRequest(new BigDecimal("12.00"), "退回多收费用");
+
+    /** 客户即使携带同名权限也不能借平台入口操作他人资金。 */
+    @Test void nonPlatformPrincipalsAreDeniedBeforeWalletAccess() {
+        for (var user : new AuthenticatedUser[]{null, user("CLIENT", 9L), user("PLATFORM", 9L)})
+            assertThatThrownBy(() -> controller.refund(user, 9, 1, "key", request))
+                .isInstanceOf(org.springframework.web.server.ResponseStatusException.class);
+        verifyNoInteractions(service);
+    }
+
+    /** 同一客户请求键生成同一退款引用，实际防重与金额上限仍由资金事务执行。 */
+    @Test void authorizedCallsUseStableReferenceAndExistingAdjustPermission() throws Exception {
+        controller.refund(user("PLATFORM", 0L), 9, 1, " key ", request);
+        controller.refund(user("PLATFORM", 0L), 9, 1, "key", request);
+        var reference = org.mockito.ArgumentCaptor.forClass(String.class);
+        verify(service, times(2)).refundConsumption(eq(9L), eq(1L), reference.capture(), eq("key"),
+            eq(request.amount()), eq(7L), isNull(), eq(request.reason()));
+        assertThat(reference.getAllValues()).allSatisfy(value -> assertThat(value).startsWith("MANUAL_REFUND:"));
+        assertThat(reference.getAllValues().get(0)).isEqualTo(reference.getAllValues().get(1));
+        assertThat(PlatformFinanceWalletController.class.getMethod("refund", AuthenticatedUser.class,
+            long.class, long.class, String.class, WalletRefundRequest.class).getAnnotation(PreAuthorize.class).value())
+            .isEqualTo("hasAuthority('platform:finance:customer-account:adjust')");
+    }
+
+    /** 空说明或非法幂等键在触达资金前失败。 */
+    @Test void missingReasonAndIdempotencyAreRejected() {
+        assertThatThrownBy(() -> controller.refund(user("PLATFORM", 0L), 9, 1, " ", request)).isInstanceOf(IllegalArgumentException.class);
+        assertThatThrownBy(() -> controller.refund(user("PLATFORM", 0L), 9, 1, "key",
+            new WalletRefundRequest(BigDecimal.ONE, " "))).isInstanceOf(IllegalArgumentException.class);
+        verifyNoInteractions(service);
+    }
+
+    private AuthenticatedUser user(String app, long tenant) {
+        return new AuthenticatedUser(7L, tenant, 0L, null, "finance", app, "WEB",
+            Set.of("platform:finance:customer-account:adjust"));
+    }
+}

finance/src/test/java/com/baiyue/finance/service/OverseasFeeWalletClosureTest.java

@@ -0,0 +1,183 @@
+package com.baiyue.finance.service;
+
+import com.baiyue.finance.client.FinanceFileClient;
+import com.baiyue.finance.dto.FinanceWalletDtos.*;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.datasource.DataSourceTransactionManager;
+import org.springframework.transaction.support.TransactionTemplate;
+
+import java.math.BigDecimal;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.LocalDate;
+import java.util.List;
+import java.util.UUID;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.regex.Pattern;
+
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.*;
+
+/** 真实资金服务、隔离数据库及事务验证海外费用释放、实扣与重复操作。 */
+class OverseasFeeWalletClosureTest {
+    private JdbcTemplate jdbc;
+    private FinanceWalletService wallet;
+    private TransactionTemplate transaction;
+
+    /** 复用正式资金表定义，所有造数只进入本测试独立内存库。 */
+    @BeforeEach void setup() throws Exception {
+        var dataSource = new JdbcDataSource();
+        dataSource.setURL("jdbc:h2:mem:" + UUID.randomUUID() + ";MODE=MySQL;DATABASE_TO_LOWER=TRUE;DB_CLOSE_DELAY=-1");
+        jdbc = new JdbcTemplate(dataSource);
+        transaction = new TransactionTemplate(new DataSourceTransactionManager(dataSource));
+        var sql = Files.readString(Path.of("src/main/resources/db/finance.sql"));
+        for (var table : List.of("fin_wallet_account", "fin_wallet_hold", "fin_wallet_ledger", "fin_idempotency_record", "fin_audit_log")) {
+            var matcher = Pattern.compile("(?s)CREATE TABLE IF NOT EXISTS " + table + " \\(.*?\\) ENGINE=[^;]+;").matcher(sql);
+            assertThat(matcher.find()).as(table).isTrue();
+            // H2 使用同一列及约束，但去除 MySQL 引擎与更新时间自动生成，避免多列生成键差异。
+            var ddl = matcher.group().replaceAll("(?s) ENGINE=.*", "")
+                .replaceAll("(?i) UNSIGNED", "")
+                .replaceAll("(?i) ON UPDATE CURRENT_TIMESTAMP\\(3\\)", "")
+                .replaceAll("(?i) DEFAULT CURRENT_TIMESTAMP\\(3\\)", "")
+                .replaceAll("(?i)((?:created_at|updated_at) DATETIME\\(3\\)) NOT NULL", "$1 NULL");
+            jdbc.execute(ddl);
+        }
+        var numbers = mock(FinanceDocumentNumberGenerator.class);
+        var sequence = new AtomicInteger();
+        when(numbers.next(anyString())).thenAnswer(call -> "AC-TEST-" + sequence.incrementAndGet());
+        wallet = new FinanceWalletService(jdbc, new ObjectMapper().findAndRegisterModules(),
+            mock(FinanceFileClient.class), numbers, "test", "", "test", "test");
+        jdbc.update("INSERT INTO fin_wallet_account(customer_id,currency_code,actual_balance,frozen_balance,available_balance,credit_limit,credit_used,credit_frozen,credit_expires_on,version,created_by,updated_by) VALUES(9,'CNY',60,0,160,100,0,0,?,0,0,0)", LocalDate.now().plusDays(7));
+    }
+
+    /** 驳回后释放原冻结，实际余额和授信均恢复可用且不发生消费。 */
+    @Test void rejectionReleasesCashAndCreditExactlyOnce() {
+        freeze();
+        assertThat(wallet.account(9).frozenBalance()).isEqualByComparingTo("80.00");
+        assertThat(wallet.account(9).creditFrozen()).isEqualByComparingTo("20.00");
+        var request = new WalletHoldActionRequest("金额录错，驳回费用");
+        transaction.execute(status -> wallet.release(9, "OVERSEAS_MANUAL_FEE", "701-1", "release", request));
+        transaction.execute(status -> wallet.release(9, "OVERSEAS_MANUAL_FEE", "701-1", "release", request));
+        var account = wallet.account(9);
+        assertThat(account.actualBalance()).isEqualByComparingTo("60.00");
+        assertThat(account.frozenBalance()).isZero(); assertThat(account.creditFrozen()).isZero();
+        assertThat(account.availableBalance()).isEqualByComparingTo("160.00");
+        assertThat(count("CONSUMPTION")).isZero(); assertThat(count("UNFREEZE")).isEqualTo(1);
+    }
+
+    /** 扣款事务失败后可重试原请求，多次点击或不同请求键均不重复消费。 */
+    @Test void failedSettlementRollsBackAndRetryConsumesOnlyOnce() {
+        freeze();
+        var request = new WalletHoldActionRequest("审核通过扣款");
+        assertThatThrownBy(() -> transaction.execute(status -> {
+            wallet.settle(9, "OVERSEAS_MANUAL_FEE", "701-1", "settle", request);
+            throw new IllegalStateException("模拟扣款事务提交前异常");
+        })).hasMessageContaining("模拟扣款");
+        assertThat(wallet.account(9).actualBalance()).isEqualByComparingTo("60.00");
+        assertThat(count("CONSUMPTION")).isZero();
+        for (int repeat = 0; repeat < 3; repeat++)
+            transaction.execute(status -> wallet.settle(9, "OVERSEAS_MANUAL_FEE", "701-1", "settle", request));
+        assertThatThrownBy(() -> transaction.execute(status -> wallet.settle(9, "OVERSEAS_MANUAL_FEE", "701-1", "another-key", request)))
+            .hasMessageContaining("已处理");
+        assertThat(wallet.account(9).actualBalance()).isZero();
+        assertThat(wallet.account(9).creditUsed()).isEqualByComparingTo("20.00");
+        assertThat(wallet.account(9).frozenBalance()).isZero(); assertThat(count("CONSUMPTION")).isEqualTo(1);
+    }
+
+    /** 第一版错扣退回复用手工充值；原因、关联单号和操作人进入资金流水。 */
+    @Test void manualCreditRetainsCorrectionReasonAndReplaysWithoutDoubleCredit() {
+        var request = new AccountAdjustmentRequest("RECHARGE", new BigDecimal("12.00"), LocalDate.now(),
+            "OTHER", "TR-001 / 费用701", "退回多收操作费", 0);
+        var first = transaction.execute(status -> wallet.adjust(9, 7, "财务员", "correction-credit", request));
+        var second = transaction.execute(status -> wallet.adjust(9, 7, "财务员", "correction-credit", request));
+        assertThat(second.ledgerId()).isEqualTo(first.ledgerId());
+        assertThat(first.remark()).isEqualTo("退回多收操作费");
+        assertThat(first.referenceNo()).isEqualTo("TR-001 / 费用701");
+        assertThat(first.operatorName()).isEqualTo("财务员");
+        assertThat(wallet.account(9).actualBalance()).isEqualByComparingTo("72.00");
+        assertThat(count("RECHARGE")).isEqualTo(1);
+    }
+
+    /** 部分退款优先还授信，累计退款不能超过原消费，原消费事实保持不变。 */
+    @Test void linkedRefundRestoresCreditThenCashAndCannotExceedOriginalConsumption() {
+        freeze();
+        var hold = transaction.execute(status -> wallet.settle(9, "OVERSEAS_MANUAL_FEE", "701-1", "settle", new WalletHoldActionRequest("审核扣款")));
+        long original = hold.actionLedgerId();
+        var first = transaction.execute(status -> wallet.refundConsumption(9, original, "refund-1", "refund-key-1", new BigDecimal("25"), 7, "财务", "多收退款"));
+        var replay = transaction.execute(status -> wallet.refundConsumption(9, original, "refund-1", "refund-key-1", new BigDecimal("25"), 7, "财务", "多收退款"));
+        assertThat(replay.ledgerId()).isEqualTo(first.ledgerId());
+        assertThat(first.changeType()).isEqualTo("REFUND");
+        assertThat(first.sourceType()).isEqualTo("BUSINESS_REFUND");
+        assertThat(first.referenceNo()).isEqualTo(jdbc.queryForObject("SELECT business_no FROM fin_wallet_ledger WHERE id=?", String.class, original));
+        assertThat(wallet.account(9).creditUsed()).isZero();
+        assertThat(wallet.account(9).actualBalance()).isEqualByComparingTo("5.00");
+        assertThatThrownBy(() -> transaction.execute(status -> wallet.refundConsumption(9, original, "refund-1", "refund-key-1", BigDecimal.ONE, 7, "财务", "变更金额"))).hasMessageContaining("幂等");
+        assertThatThrownBy(() -> transaction.execute(status -> wallet.refundConsumption(9, original, "refund-too-much", "refund-too-much", new BigDecimal("56"), 7, "财务", "退款"))).hasMessageContaining("超过");
+        transaction.execute(status -> wallet.refundConsumption(9, original, "refund-2", "refund-key-2", new BigDecimal("55"), 7, "财务", "余款退款"));
+        assertThat(wallet.account(9).actualBalance()).isEqualByComparingTo("60.00");
+        assertThat(count("REFUND")).isEqualTo(2);
+        assertThat(count("CONSUMPTION")).isEqualTo(1);
+        assertThat(jdbc.queryForObject("SELECT amount FROM fin_wallet_ledger WHERE id=?", BigDecimal.class, original)).isEqualByComparingTo("-80.00");
+    }
+
+    /** 非消费流水、跨客户原流水及非正金额均不能改变余额。 */
+    @Test void linkedRefundRejectsWrongCustomerNonConsumptionAndInvalidAmount() {
+        freeze();
+        long frozenLedger = jdbc.queryForObject("SELECT id FROM fin_wallet_ledger WHERE change_type='FREEZE'", Long.class);
+        assertThatThrownBy(() -> transaction.execute(status -> wallet.refundConsumption(9, frozenLedger, "bad", "bad", BigDecimal.ONE, 7, "财务", "退款"))).hasMessageContaining("成功业务扣款");
+        var hold = transaction.execute(status -> wallet.settle(9, "OVERSEAS_MANUAL_FEE", "701-1", "settle", new WalletHoldActionRequest("扣款")));
+        jdbc.update("INSERT INTO fin_wallet_account(customer_id,currency_code,actual_balance,frozen_balance,available_balance,credit_limit,credit_used,credit_frozen,version,created_by,updated_by) VALUES(10,'CNY',0,0,0,0,0,0,0,0,0)");
+        assertThatThrownBy(() -> transaction.execute(status -> wallet.refundConsumption(10, hold.actionLedgerId(), "wrong-customer", "wrong-customer", BigDecimal.ONE, 7, "财务", "退款"))).hasMessageContaining("不存在");
+        assertThatThrownBy(() -> transaction.execute(status -> wallet.refundConsumption(9, hold.actionLedgerId(), "zero", "zero", BigDecimal.ZERO, 7, "财务", "退款"))).isInstanceOf(RuntimeException.class);
+        assertThatThrownBy(() -> transaction.execute(status -> wallet.refundConsumption(9, hold.actionLedgerId(), "blank", "blank", BigDecimal.ONE, 7, "财务", " "))).hasMessageContaining("原因");
+        assertThat(count("REFUND")).isZero();
+        assertThat(wallet.account(9).creditUsed()).isEqualByComparingTo("20.00");
+        assertThat(wallet.account(10).actualBalance()).isZero();
+    }
+
+    /** 不同请求键的并发退款同样受原消费可退余额约束。 */
+    @Test void concurrentRefundsSerializeOnAccountAndNeverOverRefund() throws Exception {
+        freeze();
+        var hold = transaction.execute(status -> wallet.settle(9, "OVERSEAS_MANUAL_FEE", "701-1", "settle", new WalletHoldActionRequest("扣款")));
+        var start = new java.util.concurrent.CountDownLatch(1);
+        var executor = java.util.concurrent.Executors.newFixedThreadPool(2);
+        try {
+            var results = new java.util.ArrayList<java.util.concurrent.Future<Boolean>>();
+            for (int i = 0; i < 2; i++) {
+                final String reference = "concurrent-" + i;
+                results.add(executor.submit(() -> {
+                    start.await();
+                    try {
+                        transaction.execute(status -> wallet.refundConsumption(9, hold.actionLedgerId(), reference, reference, new BigDecimal("50"), 7, "财务", "并发退款"));
+                        return true;
+                    } catch (FinanceEventException ex) {
+                        assertThat(ex.code()).isEqualTo("FIN-WALLET-REFUND-EXCEEDED");
+                        return false;
+                    }
+                }));
+            }
+            start.countDown();
+            int succeeded = 0;
+            for (var result : results) if (result.get(10, java.util.concurrent.TimeUnit.SECONDS)) succeeded++;
+            assertThat(succeeded).isEqualTo(1);
+            assertThat(count("REFUND")).isEqualTo(1);
+            assertThat(wallet.account(9).actualBalance()).isEqualByComparingTo("30.00");
+        } finally { executor.shutdownNow(); }
+    }
+
+    /** 冻结始终沿用同一海外费用业务身份。 */
+    private void freeze() {
+        transaction.execute(status -> wallet.freeze(9, "freeze", new WalletFreezeRequest(
+            new BigDecimal("80.00"), "OVERSEAS_MANUAL_FEE", "701-1", "海外费用")));
+    }
+
+    /** 按真实流水类型统计资金影响，避免只检查服务返回状态。 */
+    private int count(String type) {
+        return jdbc.queryForObject("SELECT COUNT(*) FROM fin_wallet_ledger WHERE customer_id=9 AND change_type=?", Integer.class, type);
+    }
+}

firstleg/docs/business-index.md

@@ -42,7 +42,7 @@
 | 财务费用来源快照 | `controller/InternalFinanceFeeSourceController.java`；入库费用与柜次费用分别按来源 ID、版本向 Finance 提供不可变快照 |
 | 柜次费用明细与跨客户分摊组 | `controller/PlatformContainerFeeDetailController.java`、`service/ContainerFeeDetailService.java`、`dto/ContainerFeeDetailDtos.java`；跨客户公共柜费使用 `allocation-groups` 按柜内真实客户和订单原子分摊，入仓 ID/入仓码同时填写或同时留空；各行金额合计必须等于原始柜费，审核、驳回、调整、作废均整组处理，单行入口拒绝分摊组；契约 `src/main/resources/openapi/container-fees-v1.yaml`；Admin 消费端见 `../../apps/admin-web/src/modules/loading-lists/api/containerFees.ts` |
 | 财务整柜成本分摊快照 | `loading/controller/InternalFinanceCostSnapshotController.java`、`loading/service/FinanceCostSnapshotService.java` |
-| 分柜、预装、真实柜号后补与正式装柜清单生命周期 | `split/controller/PlatformSplitPreloadController.java`、`controller/PlatformLoadingListController.java`、`service/LoadingListService.java`；契约 `src/main/resources/openapi/loading-lists-v1.yaml`，详情阶段先查 `/loading-plans/{planId}/lifecycle`。创建柜次时原子生成唯一预装计划，加入入仓码明细时同步创建入库预装聚合与关联，不设推送步骤；同一 `planId` 在 `EDITING/LOADING` 返回 `PRELOAD`，`COMPLETED` 返回 `LOADING_LIST`。订单协作备注以 Order 为权威，`OrderRemarksSyncService` 负责订单列表与全部未冻结预装明细双向同步，完成装柜后保留冻结快照。订舱关联、预装确认和 PDA task 创建不依赖真实集装箱号；可在 `EDITING/LOADING` 首次补录，最终 PDA 完成前必须存在；已有值纠正仅限 `EDITING` 且任务未领取、无物理作业事实 |
+| 分柜、预装、真实柜号后补与正式装柜清单生命周期 | `split/controller/PlatformSplitPreloadController.java`、`controller/PlatformLoadingListController.java`、`service/LoadingListService.java`；契约 `src/main/resources/openapi/loading-lists-v1.yaml`，详情阶段先查 `/loading-plans/{planId}/lifecycle`。创建柜次时原子生成唯一预装计划，加入入仓码明细时同步创建入库预装聚合与关联，不设推送步骤；同一 `planId` 在 `EDITING/LOADING` 返回 `PRELOAD`，`COMPLETED` 返回 `LOADING_LIST`。订单协作备注以 Order 为权威，`OrderRemarksSyncService` 负责订单列表与全部未冻结预装明细双向同步，完成装柜后保留冻结快照。订舱关联允许真实集装箱号暂缺；确认预装和创建 PDA task 前必须补齐非空柜号，不按 ISO 格式阻断；可在 `EDITING/LOADING` 首次补录，PDA 完成前再次校验；已有值纠正仅限 `EDITING` 且任务未领取、无物理作业事实 |
 | 同柜不可拆组 | `loading/coload/controller/PlatformColoadGroupController.java`、`service/ColoadGroupService.java`、`persistence/ColoadGroupMapper.java`；契约 `src/main/resources/openapi/coload-groups-v1.yaml`。请求按订单 ID 建组，服务端允许待审核、待测量/测量中、待分柜及装柜中订单，冻结每票全部有效入仓片段与满箱数；成员全部未进柜时创建未锁定组，成员已满箱进入同一装柜计划时直接创建锁定组，部分占用或跨柜时拒绝；仅要求同国内仓、同渠道，允许跨客户及不同目的仓港；分配、移除、取消均保持整组原子 |
 | 货柜与全局智能排柜 | `controller/PlatformContainerController.java`、`PlatformSmartLoadingController.java`、`service/SmartLoadingService.java`、`repository/SmartLoadingRepository.java`、`client/PendingReviewOrderClient.java`、`loading/`；全局候选合并本服务履约投影与 Order `/internal/order/v1/pending-review-orders` 权威待审核页，工作台柜次从 `/inbound-candidates`、`/containers` 进入；普通箱数、待审核占位、同柜组和全部未拣移除分别走 `/inbound-assignments`、`/pending-review-assignments`、`/group-assignments`、`/unpicked-items`，明细规格拆分留在服务端 |
 | 货柜资料、PDA 证据与业务总览 | `controller/PlatformContainerController.java` 的 `/{id}/overview`、`/{id}/documents/{documentType}`，聚合 `mapper/ContainerOverviewMapper.java`；契约 `src/main/resources/openapi/phase3-container-overview-v1.yaml`，四类资料固定为目的港清关、国内出口报关、DO、PU 的当前唯一版本 |
@@ -58,7 +58,7 @@
 | 目的港码头拖车与还空预警 | `terminaldrayage/controller/PlatformTerminalDrayageController.java`、`service/TerminalDrayageService.java`、`mapper/TerminalDrayageMapper.java`；货柜实际到港后引用 Warehouse `ACTIVE/TRUCKING/OVERSEAS` 海外车队供应商，依次选择车队、预约提柜、确认实际提柜，海外仓卸柜或全部直送目的仓实际卸货完成后确认还柜；服务端按卸柜完成时间加 72 小时返回报空预警，实际提柜和还柜通过现有 `CarrierScheduleQueryService` 推进 `PICKED_UP/EMPTY_RETURNED`，不复制船节点或车队主档。契约 `src/main/resources/openapi/terminal-drayage-v1.yaml`，基线 `src/main/resources/db/phase3-terminal-drayage-schema.sql` 邮件由 `terminaldrayage/service/TerminalDrayageMailService.java` 入队，`TerminalDrayageMailDispatcher.java` 顺序投递，模板与 SMTP 配置见 `docs/terminal-drayage-mail.md`；首次选队不发信，换队事务内生成取消与请求两封邮件。 |
 | 船节点交接事件 | `portschedule/service/CarrierScheduleNodeOutboxService.java`；实际节点落库后按 `containerBookingId` 柜级发布 `FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED` V1，信封固定使用 `tenantId=0` 平台技术范围且 Payload 不携带客户，复用 `LoadingCompletedOutboxRepository`/Relay 直投 Lastleg `/internal/lastleg/events`；消费见 `../lastleg-service/src/main/java/com/baiyue/lastleg/shipping/service/ContainerShippingNodeConsumer.java`，ACK/重试按 `../../docs/统一认证与服务通信契约.md` |
 | Firstleg 业务单据编号 | `service/FirstlegDocumentNumberGenerator.java`；前缀与生成规则见 `../../../docs/业务单据编号契约.md`，柜次及实物标签规则保持不变 |
-| 订舱级拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java` 的 `/candidates`、`service/TruckAppointmentService.java`、`repository/TruckAppointmentRepository.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；拖车契约 `src/main/resources/openapi/truck-appointments-v1.yaml`。预约只绑定 `RELEASED` 订舱，候选排除缺提单/有效订舱文件或已有非终态预约的订舱；API 不含客户、柜次、装柜计划或真实柜号，每订舱最多一张有效预约，已有完成单不得重建收费；PDA 完成不推进拖车状态，全部要求货柜确认国内离仓后由 `TruckAppointmentCompletionService` 自动完成并经 `TruckAppointmentFeeService` 发布应付 |
+| 订舱级拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java` 的 `/candidates`、`service/TruckAppointmentService.java`、`repository/TruckAppointmentRepository.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；拖车契约 `src/main/resources/openapi/truck-appointments-v1.yaml`。预约只绑定 `RELEASED` 订舱，候选排除缺提单号或已有非终态预约的订舱；创建及派车不要求订舱文件；API 不含客户、柜次、装柜计划或真实柜号，每订舱最多一张有效预约，已有完成单不得重建收费；PDA 完成不推进拖车状态，全部要求货柜确认国内离仓后由 `TruckAppointmentCompletionService` 自动完成并经 `TruckAppointmentFeeService` 发布应付 |
 | 整柜出口报关 | `customs/container/controller/PlatformContainerCustomsController.java`、`customs/container/controller/MerchantContainerCustomsController.java`、`customs/container/service/ContainerCustomsService.java`、`customs/container/mapper/ContainerCustomsMapper.java`；装柜完成后按柜收集退税资料，多对多覆盖入仓码，开始报关冻结，完成文件逐资料一对一回传，全买单柜由平台确认并通过导出中心取明细；正式申报批次与海关结果在同一模块独立记录，不改报关四态、PDA 或船期事实；契约 `src/main/resources/openapi/customs-v1.yaml`，基线 `src/main/resources/db/phase3-container-customs-schema.sql`；消费者为 Admin `../../apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue` 和 Client `../../apps/client-web/src/modules/first-leg/components/CustomsDocumentsDialog.vue` |
 | 买单订单明细导出 Provider | `customs/container/controller/LoadingListBuyDeclarationExportController.java`、`service/LoadingListBuyDeclarationExportService.java`；只为 File 导出中心提供 `LOADING_LIST_BUY_DECLARATION_ITEMS` 的已完成装柜实际买单行，不在 Firstleg 生成文件 |
 | 跨模型桥接 | `loading/bridge/controller/PlatformLoadingModelBridgeController.java` |
@@ -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`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后运输、预报货量、三方和柜型需求只读；仅三项实际货量允许通过 `OceanBookingService.updateActualCargo` 按编辑权限、版本、幂等键和原因补录并保存前后审计快照。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
-- 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。
+- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合但不要求订舱附件，放舱后除预计到港外的运输、预报货量、三方和柜型需求只读；预计到港允许通过 `/estimated-arrival` 按编辑权限、版本与幂等键单独维护，保留前后审计快照且不得清空或早于预计开船，不改实际到港或计划到仓；三项实际货量允许通过 `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`，提单文件继续归订舱。
@@ -94,7 +94,7 @@
 
 ## 国内货柜履约装柜与 PDA 资源结算
 
-- 新增模拟柜只保存智能装柜的 9 类计划渠道 channel_group_code；未关联已放舱订舱时 channel_code/channel_name 为空，关联后才冻结订舱的实际渠道。智能装柜全局工作台和订舱关联候选均按计划渠道组匹配；服务端把业务渠道分组映射为实际渠道，并分别分页查询候选与 `WAIT_LOADING/EDITING/LOADING` 柜次；候选支持按创建日期和预计到货日期闭区间筛选，状态筛选使用最多四项的 `orderStatuses`，未传表示 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 全部未完成状态。状态只用于搜索和展示，能否加入以响应 `canAssign` 为准，由有效柜次占用、剩余箱数、容量、组锁和版本等事实决定；人工加入允许订单国内仓及渠道与柜次不同，智能推荐允许跨国内仓但仍只选择柜次渠道。容积和重量均允许达到柜型额定值的 150%，超过即拒绝。待审核事实必须经 `PendingReviewOrderClient` 重新核验 Order 权威 `SUBMITTED` 订单，待审核或待测量可先占位，但确认预装和启动 PDA 前仍必须进入 `WAIT_SPLIT`。计划明细通过 `totalPackageCount/remainingPackageCount` 返回可调总量和余量：测量前取 Order 原始申报箱数，进入 `WAIT_SPLIT/LOADING` 后取最新已审核测量箱数；只读补充失败时保守回退当前已分配数，调整写入仍重新查询并校验权威数量。同柜不可拆组只有全部成员命中状态集合时才返回，且必须成员完整、满箱并作为单个分页与分配单元，不能跨页或拆分。一次性移除未拣明细时，普通未拣项直接移除；同柜组仅全组未拣时整组移除，任一成员已拣则整组保留，单事务只递增一次计划版本。推荐顺序按入库时间先进先出。真实集装箱号允许在关联已放舱订舱时暂缺，但确认预装及创建 PDA 任务前必须补齐；历史已建但缺号的 PDA 任务可在预装详情首次补录，补录后按柜次当前真实集装箱号恢复作业。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
+- 新增模拟柜只保存智能装柜的 9 类计划渠道 channel_group_code；未关联已放舱订舱时 channel_code/channel_name 为空，关联后才冻结订舱的实际渠道。智能装柜全局工作台和订舱关联候选均按计划渠道组匹配；服务端把业务渠道分组映射为实际渠道，并分别分页查询候选与 `WAIT_LOADING/EDITING/LOADING` 柜次；候选支持按创建日期和预计到货日期闭区间筛选，状态筛选使用最多四项的 `orderStatuses`，未传表示 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 全部未完成状态。状态只用于搜索和展示，能否加入以响应 `canAssign` 为准，由有效柜次占用、剩余箱数、容量、组锁和版本等事实决定；人工加入允许订单国内仓及渠道与柜次不同，智能推荐允许跨国内仓但仍只选择柜次渠道。容积和重量均允许达到柜型额定值的 150%，超过即拒绝。待审核事实必须经 `PendingReviewOrderClient` 重新核验 Order 权威 `SUBMITTED` 订单，待审核或待测量可先占位，但确认预装和启动 PDA 前仍必须进入 `WAIT_SPLIT`。计划明细通过 `totalPackageCount/remainingPackageCount` 返回可调总量和余量：测量前取 Order 原始申报箱数，进入 `WAIT_SPLIT/LOADING` 后取最新已审核测量箱数；只读补充失败时保守回退当前已分配数，调整写入仍重新查询并校验权威数量。同柜不可拆组只有全部成员命中状态集合时才返回，且必须成员完整、满箱并作为单个分页与分配单元，不能跨页或拆分。一次性移除未拣明细时，普通未拣项直接移除；同柜组仅全组未拣时整组移除，任一成员已拣则整组保留，单事务只递增一次计划版本。推荐顺序按入库时间先进先出。真实集装箱号允许在关联已放舱订舱时暂缺；关联、运输修改和提柜补录统一只规范化空白和大小写，不以 ISO 长度、结构、设备类别或校验位阻断，数据库不设置 ISO 格式 CHECK，仍遵守同订舱唯一及已有柜号一致性。确认预装、创建 PDA 任务和 PDA 完成只要求真实柜号非空，不再校验 ISO 格式；跨服务装柜、船节点和卸柜事件统一接受非 ISO 柜号，冻结事实仍要求柜号已规范化且与来源柜一致。运输纠错继续遵守原因、版本及 PDA 领取和物理作业冻结限制。确认预装及创建 PDA 任务前必须补齐；历史已建但缺号的 PDA 任务可在预装详情首次补录，补录后按柜次当前真实集装箱号恢复作业。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
 - 预装进入 `CONFIRMING/CONFIRMED` 只固化确认快照，不得锁死尚未完成柜次的智能装柜分配；装柜计划仍处于 `EDITING/LOADING` 时可继续新增，未产生实物拣货的明细可调整或移除，已拣明细保持锁定。一件代发智能装柜候选以每个未被有效柜次占用的已封托托盘为独立分页、展示和分配单位；同一入仓单有多托时必须逐托返回，其中一托已分配不得隐藏或禁用其余未分配托盘。智能推荐必须逐个调用整托分配，容量不足时跳过整托，不得回退按箱分配；全局工作台传入当前 `customerId/inboundCode` 筛选范围时，服务端只能推荐同时命中的候选，同一次推荐按受影响客户统一重算费用，不得逐托重复重算。单行删除必须按该行 `palletId` 整托移除。装柜完成事件必须按计划项 `palletId` 精确冻结每托箱唛与 SKU 清单，不得仅按入仓单或货物明细关联而造成多托交叉重复。
 - 客户入库费用只在登录客户范围、测量审核通过、`feeStatus=SENT` 且存在已发布明细时可见；确认必须具备 `merchant:order:edit`，携带当前 `expectedFeeVersion` 与幂等键。成功后记录确认成员和时间；客户未确认或该票尚未装柜完成时，平台仍可修改箱规规则、生成新费用版本并重新发送，新版本必须清空旧版客户确认快照。仅当“客户已确认且该票已装柜完成”同时成立时最终冻结；装柜完成不得代替客户自动确认。旧版本、未发送或重复异参确认均返回冲突，不做兼容覆盖。
 - PDA 普通散箱拣货以 `fl_inbound_carton_label.box_code` 对应的稳定箱唛箱码为扫描身份；审核建单、重复打印、手工测量和墨家测量复用同一映射，版本字段只用于并发控制，不进入扫码文本。一个有效且未重复的箱码扫描表示拣出一箱，不得以 SKU、商品件数、入库单号或页面展示字段替代箱码。一件代发已封托的 `SEALED_PALLET` 是不可拆整托单元，PDA 可扫描计划快照中的 `palletNo`、用该托任一成员 `boxCode` 反查所属整托，也可在明细卡片手工确认整托；三种入口最终都必须携带权威 `palletNo` 以 `PICK_PALLET` 一次性提交，不能按成员箱逐箱累计、部分拣货或跳拣。PDA 首页从 Warehouse 主档选择启用国内仓，一件代发与装柜待办列表必须按所选 `warehouseId` 服务端过滤；装柜任务内部仍允许跨国内仓，仓库与渠道限制统一由上游装柜编排负责，PDA 只按已生成任务读取各入仓单自身的 `CONFIRMED` 库位资源，不得再用柜次仓库过滤任务明细、库存快照或拣货写入。任务下发与提交契约见 `src/main/resources/openapi/phase3-pda-convergence-v1.yaml`。

firstleg/src/main/java/com/baiyue/firstleg/controller/InternalFeeCatalogController.java

@@ -0,0 +1,58 @@
+package com.baiyue.firstleg.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.firstleg.service.SharedFeeCatalogService;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.List;
+
+/** 公共费用目录内部只读入口，禁止借用平台员工令牌跨服务查询。 */
+@RestController
+@RequestMapping("/internal/firstleg/v1/fee-items")
+public class InternalFeeCatalogController {
+    private final SharedFeeCatalogService service;
+    private final byte[] expectedToken;
+
+    /** 绑定费用目录服务与内部身份凭证，空凭证始终拒绝访问。 */
+    public InternalFeeCatalogController(SharedFeeCatalogService service,
+        @Value("${baiyue.security.internal-service-token:}") String token) {
+        this.service = service;
+        this.expectedToken = token.getBytes(StandardCharsets.UTF_8);
+    }
+
+    /** 返回适用海外仓收付方向的启用项目。 */
+    @GetMapping
+    public ApiResponse<List<SharedFeeCatalogService.Item>> list(
+        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
+        @RequestParam(defaultValue = "RECEIVABLE") String direction) {
+        requireToken(token);
+        return ApiResponse.success(service.list(direction));
+    }
+
+    /** 在费用创建时验证实时项目资格。 */
+    @GetMapping("/{code}")
+    public ApiResponse<SharedFeeCatalogService.Item> detail(
+        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
+        @PathVariable String code, @RequestParam String direction) {
+        requireToken(token);
+        return ApiResponse.success(service.requireActive(code, direction));
+    }
+
+    /** 使用常量时间比较内部凭证，未配置凭证时关闭入口。 */
+    private void requireToken(String token) {
+        if (expectedToken.length == 0 || token == null
+            || !MessageDigest.isEqual(expectedToken, token.getBytes(StandardCharsets.UTF_8))) {
+            throw new BizException(ResultCode.FORBIDDEN, "内部服务凭证无效");
+        }
+    }
+}

firstleg/src/main/java/com/baiyue/firstleg/customs/container/service/ContainerCustomsService.java

@@ -211,6 +211,7 @@ public class ContainerCustomsService {
         return platformView(planId);
     }
 
+    /** 全部预录单经客户确认后发送报关行执行，保留版本与发送状态校验。 */
     @Transactional
     public ContainerView submitToBroker(long planId, long operatorId, String operatorName, String key, ActionRequest request) {
         String action = "SUBMIT_CUSTOMS_TO_BROKER_" + planId;
@@ -221,8 +222,8 @@ public class ContainerCustomsService {
         ContainerRow container = mapper.lockContainer(planId);
         if (container == null || !DECLARING.equals(container.status())) throw conflict("当前柜不在报关中");
         if (!Objects.equals(container.version(), request.expectedVersion())) throw concurrent();
-        if (mapper.taxRefundCount(container.loadingPlanId()) == 0) throw conflict("全买单柜无需发送客户回执给报关行");
-        if (mapper.unconfirmedReceiptCount(container.id()) != 0) throw conflict("仍有报关行回执未完成客户确认");
+        if (mapper.taxRefundCount(container.loadingPlanId()) == 0) throw conflict("全买单柜无需发送预录单确认结果给报关行");
+        if (mapper.unconfirmedReceiptCount(container.id()) != 0) throw conflict("仍有预录单未完成客户确认");
         if (mapper.brokerSubmission(container.id()) == null) throw conflict("当前柜尚未完成首次发送报关行资料");
         if (mapper.brokerSubmittedAt(container.id()) != null) throw conflict("当前柜已发送给报关行执行");
         if (mapper.submitToBroker(container.id(), container.version(), operatorId, operatorName) != 1) throw concurrent();
@@ -231,6 +232,7 @@ public class ContainerCustomsService {
         return platformView(planId);
     }
 
+    /** 上传预录单并保存文件版本，已发送报关行执行后仍禁止替换。 */
     @Transactional
     public DocumentView uploadCompletion(long documentId, long operatorId, String operatorName, String key,
                                          int expectedVersion, MultipartFile file) {
@@ -246,7 +248,7 @@ public class ContainerCustomsService {
             throw conflict("当前客户资料不在报关中冻结版本");
         }
         if (mapper.brokerSubmittedAt(container.id()) != null) {
-            throw conflict("客户确认回执已发送给报关行，不可再修改回执");
+            throw conflict("客户确认的预录单已发送给报关行，不可再修改预录单");
         }
         if (mapper.brokerSubmission(container.id()) == null) {
             throw conflict("当前柜尚未完成首次发送报关行资料");
@@ -300,6 +302,7 @@ public class ContainerCustomsService {
         return merchantViewForDocument(tenantId, source);
     }
 
+    /** 预录单确认并发送报关行执行后，接收真实报关完税文件。 */
     @Transactional
     public DocumentView uploadFinalDocument(long documentId, long operatorId, String operatorName, String key,
                                             int expectedVersion, MultipartFile file) {
@@ -316,7 +319,7 @@ public class ContainerCustomsService {
         }
         if (mapper.brokerSubmittedAt(container.id()) == null) throw conflict("客户确认结果尚未发送给报关行");
         CompletionRow receipt = mapper.lockCompletion(documentId);
-        if (receipt == null || !"CONFIRMED".equals(receipt.customerConfirmStatus())) throw conflict("该客户回执尚未确认");
+        if (receipt == null || !"CONFIRMED".equals(receipt.customerConfirmStatus())) throw conflict("该客户的预录单尚未确认");
         FinalRow existing = mapper.lockFinalDocument(documentId);
         CustomsFileClient.Metadata metadata = upload(source.tenantId(), RESULT_FILE_TYPE, Long.toString(container.loadingPlanId()), operatorId, file);
         long finalId;
@@ -371,7 +374,7 @@ public class ContainerCustomsService {
         if (container == null || !(DECLARING.equals(container.status()) || COMPLETED.equals(container.status()))) throw conflict("当前柜尚未进入报关行执行阶段，不能创建正式申报批次");
         if (mapper.taxRefundCount(planId) == 0) throw conflict("全买单柜不创建退税正式申报批次");
         if (mapper.unconfirmedReceiptCount(container.id()) != 0 || mapper.brokerSubmittedAt(container.id()) == null) {
-            throw conflict("当前柜尚未完成退税资料、回执确认和报关行执行");
+            throw conflict("当前柜尚未完成退税资料、预录单确认和报关行执行");
         }
         if (!Objects.equals(container.version(), request.expectedVersion())) throw concurrent();
         long batchId = IdWorker.getId();
@@ -536,14 +539,15 @@ public class ContainerCustomsService {
                 row.operatorName(), row.createdAt())).toList();
     }
 
+    /** 按既有客户范围与可见状态下载预录单，沿用文件真实名称。 */
     public Download downloadCompletion(long tenantId, long documentId, boolean platform) {
         DocumentRow source = requiredDocument(documentId);
         ContainerRow container = mapper.containerById(source.customsContainerId());
         if (!platform && (source.tenantId() != tenantId || container == null || !Set.of(DECLARING, COMPLETED).contains(container.status()))) {
-            throw notFound("报关行回执不存在");
+            throw notFound("预录单不存在");
         }
         CompletionRow completion = mapper.completion(documentId);
-        if (completion == null) throw notFound("报关行回执不存在");
+        if (completion == null) throw notFound("预录单不存在");
         return download(source.tenantId(), RECEIPT_FILE_TYPE, Long.toString(container.loadingPlanId()), completion.fileId(), completion.fileName());
     }
 

firstleg/src/main/java/com/baiyue/firstleg/domain/Iso6346ContainerNumber.java

@@ -1,49 +0,0 @@
-package com.baiyue.firstleg.domain;
-
-import com.baiyue.common.core.api.ResultCode;
-import com.baiyue.common.core.exception.BizException;
-
-import java.util.Locale;
-
-/** ISO 6346 真实集装箱号的唯一规范化与校验入口。 */
-public final class Iso6346ContainerNumber {
-    private static final int[] LETTER_VALUES = {
-        10, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 23, 24,
-        25, 26, 27, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38
-    };
-
-    private Iso6346ContainerNumber() {
-    }
-
-    public static String require(String raw) {
-        String value = normalizeWhitespace(raw);
-        if (value == null || !value.matches("[A-Z]{3}[UJZ][0-9]{7}")) {
-            throw invalid();
-        }
-        int sum = 0;
-        for (int index = 0; index < 10; index++) {
-            char current = value.charAt(index);
-            int number = Character.isDigit(current)
-                ? current - '0' : LETTER_VALUES[current - 'A'];
-            sum += number * (1 << index);
-        }
-        int expected = sum % 11 % 10;
-        if (value.charAt(10) - '0' != expected) throw invalid();
-        return value;
-    }
-
-    private static String normalizeWhitespace(String raw) {
-        if (raw == null) return null;
-        StringBuilder value = new StringBuilder(raw.length());
-        raw.codePoints().filter(codePoint -> !Character.isWhitespace(codePoint)
-                && !Character.isSpaceChar(codePoint))
-            .forEach(value::appendCodePoint);
-        String normalized = value.toString().toUpperCase(Locale.ROOT);
-        return normalized.isEmpty() ? null : normalized;
-    }
-
-    private static BizException invalid() {
-        return new BizException(ResultCode.BAD_REQUEST,
-            "真实集装箱号必须符合ISO 6346结构、设备类别和校验位");
-    }
-}

firstleg/src/main/java/com/baiyue/firstleg/domain/RealContainerNumber.java

@@ -0,0 +1,19 @@
+package com.baiyue.firstleg.domain;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.common.event.ContainerNumbers;
+
+/** 真实集装箱号录入与作业门禁，与跨服务事件使用同一规范化规则。 */
+public final class RealContainerNumber {
+    private RealContainerNumber() { }
+
+    /** 保留柜号必填要求，不再检查 ISO 长度、设备类别和校验位。 */
+    public static String require(String raw) {
+        try {
+            return ContainerNumbers.normalizeRequired(raw);
+        } catch (IllegalArgumentException exception) {
+            throw new BizException(ResultCode.BAD_REQUEST, "真实集装箱号不能为空");
+        }
+    }
+}

firstleg/src/main/java/com/baiyue/firstleg/dto/TruckAppointmentDtos.java

@@ -3,7 +3,8 @@ import jakarta.validation.constraints.*; import java.math.BigDecimal; import jav
 public final class TruckAppointmentDtos { private TruckAppointmentDtos(){}
  public record Query(@Size(max=64) String keyword, com.baiyue.firstleg.domain.TruckAppointmentStatus status, @Positive Long oceanBookingId, @Min(1) long page, @Min(1) @Max(200) long size){ public Query{if(page==0)page=1;if(size==0)size=20;} }
  public record CandidateQuery(@Size(max=64) String keyword,@Min(1) long page,@Min(1) @Max(200) long size){public CandidateQuery{if(page==0)page=1;if(size==0)size=20;}}
- public record Candidate(Long oceanBookingId,String oceanBookingNo,String billOfLadingNo,Long warehouseId,String warehouseName,String channelCode,String channelName,Boolean bookingDocumentReady){}
+ /** 已放舱订舱候选，预约不依赖订舱附件。 */
+ public record Candidate(Long oceanBookingId,String oceanBookingNo,String billOfLadingNo,Long warehouseId,String warehouseName,String channelCode,String channelName){}
  public record SaveRequest(@Positive Long outboundOrderId,@NotNull @Positive Long oceanBookingId,@Positive Long warehouseId,@NotNull @Positive Long carrierId,@Size(max=128) String carrierName,@Size(max=128) String billOfLadingNo,@Size(max=64) String fleetContact,@Size(max=32) String fleetPhone,@Size(max=64) String driverName,@Size(max=32) String driverPhone,@Size(max=32) String driverIdCard,@Size(max=32) String vehicleNo,@Size(max=128) String storeName,@Size(max=64) String storeContact,@Size(max=32) String storePhone,@Size(max=255) String storeAddress,@Size(max=64) String storeCity,@Size(max=16) String storeZipcode,@PositiveOrZero Integer packageCount,@DecimalMin("0") BigDecimal grossWeightKg,@DecimalMin("0") BigDecimal volumeCbm,@PositiveOrZero Integer palletCount,@Size(max=255) String poNo,@NotNull LocalDateTime plannedLoadingAt,@PositiveOrZero Integer transitMinutes,@DecimalMin("0") @Digits(integer=16,fraction=2) BigDecimal payableAmount,@Pattern(regexp="RMB") String currency,@Size(max=1000) String remark,@NotNull @PositiveOrZero Integer expectedVersion){}
  public record ActionRequest(@NotNull @PositiveOrZero Integer expectedVersion,@Size(max=500) String reason){}
  public record AttachmentRequest(@NotNull @Positive Long fileId,@NotBlank @Pattern(regexp="DISPATCH_ORDER|DRIVER_DOCUMENT|VEHICLE_DOCUMENT|OTHER") String attachmentType,@Size(max=255) String fileName,@Size(max=128) String fileHash){ }

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

@@ -1,15 +1,14 @@
 package com.baiyue.firstleg.mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baiyue.firstleg.dto.TruckAppointmentDtos.*; import com.baiyue.firstleg.entity.TruckAppointmentEntity; import org.apache.ibatis.annotations.*;
 @Mapper public interface TruckAppointmentMapper extends BaseMapper<TruckAppointmentEntity>{
+ /** 查询已放舱且有提单号的可预约订舱，不依赖附件。 */
  @Select("""
   <script>
   SELECT o.id oceanBookingId,o.booking_no oceanBookingNo,o.bill_of_lading_no billOfLadingNo,
          o.warehouse_id warehouseId,o.warehouse_name warehouseName,o.channel_code channelCode,
-         o.channel_name channelName,TRUE bookingDocumentReady
+         o.channel_name channelName
     FROM fl_ocean_booking o
-   WHERE EXISTS (SELECT 1 FROM fl_ocean_booking_document d WHERE d.ocean_booking_id=o.id
-                  AND d.valid=1 AND d.document_type IN ('BOOKING_CONFIRMATION','BILL_OF_LADING'))
-     AND o.status='RELEASED' AND o.bill_of_lading_no IS NOT NULL AND o.bill_of_lading_no&lt;&gt;''
+   WHERE o.status='RELEASED' AND o.bill_of_lading_no IS NOT NULL AND o.bill_of_lading_no&lt;&gt;''
      AND NOT EXISTS (SELECT 1 FROM fl_truck_appointment t WHERE t.ocean_booking_id=o.id
                       AND t.status NOT IN ('CANCELLED','EXCEPTION'))
      AND (#{q.keyword} IS NULL OR o.booking_no LIKE CONCAT('%',#{q.keyword},'%')

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}/estimated-arrival")
+    @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:edit')")
+    @BusinessAudit(event="OCEAN_BOOKING_UPDATE_ESTIMATED_ARRIVAL", resourceType="OCEAN_BOOKING", resourceId="#oceanBookingId", description="维护订舱预计到港")
+    public ApiResponse<Detail> updateEstimatedArrival(@AuthenticationPrincipal AuthenticatedUser user,
+        @PathVariable @Positive long oceanBookingId, @RequestHeader("Idempotency-Key") String key,
+        @Valid @RequestBody EstimatedArrivalRequest request) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(service.updateEstimatedArrival(oceanBookingId, user.userId(), user.username(), key, request));
+    }
+
     /** 客服在放舱后补录实货量，沿用订舱编辑权限并记录审计。 */
     @PutMapping("/{oceanBookingId}/actual-cargo")
     @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:edit')")

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

@@ -95,6 +95,10 @@ public final class OceanBookingDtos {
                             @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
                             @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualVolumeCbm) {}
 
+    /** 放舱后仅维护预计到港，不接收其他运输资料。 */
+    public record EstimatedArrivalRequest(@NotNull @Min(0) Integer expectedVersion,
+                                         @NotNull LocalDateTime estimatedArrivalAt) {}
+
     /** 放舱后的受控实货量补录，不接收运输资料。 */
     public record ActualCargoRequest(@NotNull @Min(0) Integer expectedVersion,
                                     @Min(1) @Max(999999999) Integer actualPackageCount,

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

@@ -27,6 +27,11 @@ public interface OceanBookingMapper extends BaseMapper<OceanBookingEntity> {
                    @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},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 estimated_arrival_at=#{estimatedArrivalAt},updated_by=#{operatorId},updated_by_name=#{operatorName},updated_at=CURRENT_TIMESTAMP(3),version=version+1 WHERE id=#{id} AND status='RELEASED' AND version=#{version}")
+    int updateEstimatedArrival(@Param("id") long id, @Param("estimatedArrivalAt") java.time.LocalDateTime estimatedArrivalAt,
+        @Param("version") int version, @Param("operatorId") long operatorId, @Param("operatorName") String operatorName);
+
     /** 已放舱补实只更新白名单字段，保留乐观锁及状态门禁。 */
     @Update("""
         UPDATE fl_ocean_booking SET actual_package_count=#{value.actualPackageCount},

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

@@ -54,6 +54,11 @@ public class OceanBookingRepository {
     public int touchDraft(long id, int version, long operatorId, String operatorName) {
         return bookings.touchDraft(id, version, operatorId, operatorName);
     }
+    /** 按订舱版本仅更新已放舱预计到港，不重写其他运输或货量资料。 */
+    public int updateEstimatedArrival(long id, java.time.LocalDateTime estimatedArrivalAt, int version, long operatorId, String operatorName) {
+        return bookings.updateEstimatedArrival(id, estimatedArrivalAt, version, operatorId, operatorName);
+    }
+
     /** 只更新已放舱订舱的实际货量，运输快照保持冻结。 */
     public int updateActualCargo(OceanBookingEntity value, int version, long operatorId, String operatorName) {
         return bookings.updateActualCargo(value, version, operatorId, operatorName);

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

@@ -51,7 +51,6 @@ public class OceanBookingService {
     @Resource private WarehouseMasterDataClient warehouses;
     @Resource private WarehousePartnerClient partners;
     @Resource private FirstlegDocumentNumberGenerator documentNumbers;
-    @Resource private OceanBookingDocumentService documents;
     @Resource private com.baiyue.firstleg.service.IamCustomerSnapshotService customers;
     @Value("${baiyue.security.internal-service-token:}") private String internalToken;
     @Value("${baiyue.warehouse.public-tenant-id:0}") private long publicWarehouseTenantId;
@@ -145,6 +144,24 @@ 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 updateEstimatedArrival(long id, long operatorId, String name, String key, EstimatedArrivalRequest request) {
+        String action = "UPDATE_ESTIMATED_ARRIVAL";
+        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 (request.estimatedArrivalAt() == null) throw badRequest("预计到港时间不能为空");
+        if (before.getEstimatedSailingAt() != null && request.estimatedArrivalAt().isBefore(before.getEstimatedSailingAt())) {
+            throw badRequest("预计到港时间不能早于预计开船时间");
+        }
+        if (repository.updateEstimatedArrival(id, request.estimatedArrivalAt(), request.expectedVersion(), operatorId, name) != 1) throw concurrent();
+        OceanBookingEntity saved = required(id);
+        addHistory(id, before.getStatus(), saved.getStatus(), action, "维护预计到港", before, saved, operatorId, name);
+        return complete(id, operatorId, action, key, detail(saved));
+    }
+
     /** 放舱后仅补录实货量，版本、幂等结果和修改前后快照在同一事务保存。 */
     @Transactional
     public Detail updateActualCargo(long id, long operatorId, String name, String key, ActualCargoRequest request) {
@@ -176,6 +193,7 @@ public class OceanBookingService {
         complete(null, operatorId, action, key, new Detail(before, List.of(), List.of(), List.of(), List.of()));
     }
 
+    /** 校验完整订舱资料后放舱，不以附件上传作为前置条件。 */
     @Transactional public Detail release(long id, long operatorId, String name, String key, ReleaseRequest request) {
         String action = "RELEASE";
         Detail replay = claimOrReplay(id, operatorId, action, key, hash(action, id, request));
@@ -184,7 +202,6 @@ public class OceanBookingService {
         requireStatus(before, OceanBookingStatus.DRAFT);
         validateRelease(before, repository.parties(id), repository.requirements(id));
         validateMasterData(before);
-        documents.requireActiveValidDocument(before);
         if (repository.transition(id, OceanBookingStatus.DRAFT.name(), OceanBookingStatus.RELEASED.name(),
             request.expectedVersion(), operatorId, name) != 1) throw concurrent();
         OceanBookingEntity after = required(id);
@@ -262,6 +279,7 @@ 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

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

@@ -383,11 +383,12 @@ public class FbaPricingRepository {
             .set(InboundFeeEntity::getConfirmedAt, now));
     }
 
+    /** 确认费用时保留物流主状态，一件代发待组托也允许确认。 */
     public int markInboundConfirmed(long tenantId, long inboundId) {
         return inbounds.update(null, new LambdaUpdateWrapper<InboundPricingEntity>()
             .eq(InboundPricingEntity::getTenantId, tenantId).eq(InboundPricingEntity::getId, inboundId)
             .in(InboundPricingEntity::getProcessStatus,
-                List.of("FEE_CONFIRMING", "WAIT_PALLET", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"))
+                List.of("FEE_CONFIRMING", "WAIT_PALLET", "WAIT_PALLETIZE", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"))
             .eq(InboundPricingEntity::getFeeStatus, "CALCULATED")
             .set(InboundPricingEntity::getFeeStatus, "CONFIRMED"));
     }

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

@@ -54,6 +54,18 @@ public class FeeItemRepository {
             .eq(FeeItemEntity::getFeeCode, feeCode));
     }
 
+    /** 海外录费仅提供平台启用的国际仓库收付费项目，不复制费用目录。 */
+    public List<FeeItemEntity> listActiveInternationalWarehouseItems(String direction) {
+        return feeItems.selectList(new LambdaQueryWrapper<FeeItemEntity>()
+            .eq(FeeItemEntity::getTenantId, PLATFORM_TENANT_ID)
+            .eq(FeeItemEntity::getStatus, "ACTIVE")
+            .eq(FeeItemEntity::getTradeScope, "INTERNATIONAL")
+            .eq("RECEIVABLE".equals(direction), FeeItemEntity::getWarehouseReceivable, true)
+            .eq("PAYABLE".equals(direction), FeeItemEntity::getWarehousePayable, true)
+            .orderByAsc(FeeItemEntity::getCategory)
+            .orderByAsc(FeeItemEntity::getFeeTypeName));
+    }
+
     public boolean itemNameExists(String tradeScope, String feeTypeName, Long excludedId) {
         return feeItems.selectCount(new LambdaQueryWrapper<FeeItemEntity>()
             .eq(FeeItemEntity::getTenantId, PLATFORM_TENANT_ID)

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

@@ -12,7 +12,7 @@ import com.baiyue.firstleg.dto.ContainerDtos.FullUpdateRequest;
 import com.baiyue.firstleg.dto.ContainerDtos.SaveRequest;
 import com.baiyue.firstleg.dto.ContainerDtos.SimulationCreateRequest;
 import com.baiyue.firstleg.dto.ContainerDtos.OceanBookingLinkRequest;
-import com.baiyue.firstleg.domain.Iso6346ContainerNumber;
+import com.baiyue.firstleg.domain.RealContainerNumber;
 import com.baiyue.firstleg.entity.ContainerBookingEntity;
 import com.baiyue.firstleg.repository.ContainerRepository;
 import com.baiyue.firstleg.pricebookquery.application.model.PriceBookQueryRows.ChannelRow;
@@ -82,15 +82,19 @@ public class ContainerService {
         return value;
     }
 
+    /** 首次关联已放舱订舱，仅规范化柜号并保留关联资格与并发校验。 */
     @Transactional
     public ContainerBookingEntity linkOceanBooking(long id, long operatorId, String operatorName, OceanBookingLinkRequest request) {
         ContainerBookingEntity container = required(id); requireVersion(container, request.expectedVersion()); requireFirstLinkMutable(container);
         if (container.getOceanBookingId() != null) throw conflict("模拟柜已关联真实订舱柜");
         String existingContainerNo = trim(container.getContainerNo());
         String requestedContainerNo = trim(request.containerNo());
-        String containerNo = requestedContainerNo == null
-            ? existingContainerNo
-            : Iso6346ContainerNumber.require(requestedContainerNo);
+        // 本关联入口不按 ISO 长度、结构或校验位阻断，仍统一空白与大小写以核对唯一性。
+        if (requestedContainerNo != null) {
+            requestedContainerNo = trim(requestedContainerNo.replaceAll("[\\p{javaWhitespace}\\p{Z}]", "")
+                .toUpperCase(java.util.Locale.ROOT));
+        }
+        String containerNo = requestedContainerNo == null ? existingContainerNo : requestedContainerNo;
         if (existingContainerNo != null && !existingContainerNo.equals(containerNo)) {
             throw conflict("输入的真实集装箱号与当前柜次已录入柜号不一致，请先在预装运输信息中纠正");
         }
@@ -120,6 +124,7 @@ public class ContainerService {
         return required(id);
     }
 
+    /** 提柜后补录规范化真实柜号，保留同订舱唯一及作业冻结门禁。 */
     @Transactional
     public ContainerBookingEntity assignRealContainerNo(long id, String requestedContainerNo, int expectedVersion,
                                                          long operatorId, String operatorName) {
@@ -134,7 +139,7 @@ public class ContainerService {
             || repository.hasPickTask(id) || repository.hasEvidence(id) || repository.hasDocuments(id)) {
             throw conflict("已进入PDA、证据、单证或不可逆装柜阶段，不能补录真实柜号");
         }
-        String containerNo = Iso6346ContainerNumber.require(requestedContainerNo);
+        String containerNo = RealContainerNumber.require(requestedContainerNo);
         if (repository.containerNoExists(container.getOceanBookingId(), containerNo, id)) {
             throw conflict("当前提单下集装箱号已存在");
         }

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

@@ -26,7 +26,7 @@ import com.baiyue.firstleg.loading.bridge.dto.LoadingModelBridgeDtos.Link;
 import com.baiyue.firstleg.repository.LoadingListRepository;
 import com.baiyue.firstleg.repository.LoadingPickRepository;
 import com.baiyue.firstleg.repository.ContainerRepository;
-import com.baiyue.firstleg.domain.Iso6346ContainerNumber;
+import com.baiyue.firstleg.domain.RealContainerNumber;
 import com.baiyue.firstleg.domain.PriceBookChannelCatalog;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.JsonNode;
@@ -493,10 +493,10 @@ public class LoadingListService {
         return repository.preloadDetail(requirePlan(planId));
     }
 
+    /** 未提交柜号时保留原值，首次录入或纠错统一规范化并禁止清空。 */
     private static String targetContainerNo(AggregateRow before, String requested) {
-        if (requested != null) return Iso6346ContainerNumber.require(requested);
-        return StringUtils.hasText(before.getContainerNo())
-            ? Iso6346ContainerNumber.require(before.getContainerNo()) : null;
+        if (requested == null) return StringUtils.hasText(before.getContainerNo()) ? before.getContainerNo() : null;
+        return RealContainerNumber.require(requested);
     }
 
     private static String transportHash(long planId, int version, String containerNo,

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

@@ -23,7 +23,7 @@ import com.baiyue.firstleg.dto.LoadingPickDtos.InboundInventory;
 import com.baiyue.firstleg.dto.LoadingPickDtos.InventorySnapshot;
 import com.baiyue.firstleg.dto.LoadingPickDtos.InventoryUnit;
 import com.baiyue.firstleg.dto.LoadingPickDtos.PendingTask;
-import com.baiyue.firstleg.domain.Iso6346ContainerNumber;
+import com.baiyue.firstleg.domain.RealContainerNumber;
 import com.baiyue.firstleg.client.DomesticPdaOperatorClient;
 import com.baiyue.firstleg.entity.LoadingPickAssignmentEntity;
 import com.baiyue.firstleg.entity.LoadingPickHistoryEntity;
@@ -140,6 +140,7 @@ public class LoadingPickService {
             smartLoadingRepository.items(plan.getId()));
     }
 
+    /** 确认预装前验证作业资格和真实柜号必填。 */
     public List<Link> requirePreloadConfirmationReady(long loadingPlanId) {
         inboundHoldGuard.requirePlanNotHeld(loadingPlanId);
         List<Link> links = loadingModelBridge.requireAllocatedLinksForConfirmation(loadingPlanId);
@@ -151,6 +152,7 @@ public class LoadingPickService {
             if (booking == null || !StringUtils.hasText(booking.getContainerNo())) {
                 throw conflict("确认预装前必须录入真实集装箱号");
             }
+            requireContainerNumberBeforeStarting(booking.getContainerNo());
             var allocation = oceanBookingRepository.allocationByContainer(link.containerBookingId());
             if (allocation == null) throw conflict("确认预装前必须关联真实订舱柜");
             var oceanBooking = oceanBookingRepository.find(allocation.getOceanBookingId());
@@ -164,12 +166,14 @@ public class LoadingPickService {
         return links;
     }
 
+    /** 仅在柜号已满足完成事件要求时创建 PDA 任务，已有任务的重复同步保持原语义。 */
     @Transactional
     public void begin(long planId, String containerNo, long operatorId, String operatorName,
                       List<LoadingPlanItemEntity> planItems) {
         inboundHoldGuard.requirePlanNotHeld(planId);
         LoadingPickTaskEntity task = repository.taskByPlan(planId);
         if (task == null) {
+            requireContainerNumberBeforeStarting(containerNo);
             task = new LoadingPickTaskEntity();
             task.setLoadingPlanId(planId);
             var booking = smartLoadingRepository.booking(smartLoadingRepository.plan(planId).getContainerBookingId());
@@ -610,15 +614,25 @@ public class LoadingPickService {
     /** 本进程事务提交后的唤醒信号，权威命令和恢复事实仍保存在数据库。 */
     public record CompletionAccepted(long commandId, long acceptedAtNanos) {}
 
+    /** 确认预装和创建 PDA 任务前要求柜号非空，不以 ISO 格式阻断作业。 */
+    private static void requireContainerNumberBeforeStarting(String containerNo) {
+        try {
+            RealContainerNumber.require(containerNo);
+        } catch (BizException exception) {
+            throw conflict("请先在预装运输信息中录入真实集装箱号后再确认预装或启动PDA");
+        }
+    }
+
+    /** 完成前复核真实柜号，以生成一致的跨服务装柜完成事件。 */
     private void requireCompletionContainerNumber(long taskId) {
         ContainerBookingEntity booking = repository.activeBookingByTask(taskId);
         if (booking == null || !StringUtils.hasText(booking.getContainerNo())) {
             throw conflict("PDA确认装柜完成前必须录入真实集装箱号");
         }
         try {
-            Iso6346ContainerNumber.require(booking.getContainerNo());
+            RealContainerNumber.require(booking.getContainerNo());
         } catch (BizException exception) {
-            throw conflict("PDA确认装柜完成前必须录入符合ISO 6346的真实集装箱号");
+            throw conflict("PDA确认装柜完成前必须录入真实集装箱号");
         }
     }
 

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

@@ -0,0 +1,53 @@
+package com.baiyue.firstleg.service;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.firstleg.entity.FeeItemEntity;
+import com.baiyue.firstleg.repository.FeeItemRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.math.BigDecimal;
+import java.util.List;
+
+/** 向海外业务提供公共费用目录的只读切片，项目维护仍归头程主数据。 */
+@Service
+@RequiredArgsConstructor
+public class SharedFeeCatalogService {
+    private final FeeItemRepository repository;
+
+    /** 按收付方向返回当前可使用的费用项目。 */
+    public List<Item> list(String direction) {
+        requireDirection(direction);
+        return repository.listActiveInternationalWarehouseItems(direction).stream()
+            .map(SharedFeeCatalogService::snapshot).toList();
+    }
+
+    /** 写入业务费用前重新验证项目资格，停用或方向变化不得沿用旧选项。 */
+    public Item requireActive(String code, String direction) {
+        requireDirection(direction);
+        FeeItemEntity item = repository.findItemByCode(code);
+        if (item == null || !"ACTIVE".equals(item.getStatus())
+            || !"INTERNATIONAL".equals(item.getTradeScope())
+            || !("RECEIVABLE".equals(direction)
+                ? Boolean.TRUE.equals(item.getWarehouseReceivable())
+                : Boolean.TRUE.equals(item.getWarehousePayable()))) {
+            throw new BizException(ResultCode.CONFLICT, "费用项目未启用或不适用于本次收费");
+        }
+        return snapshot(item);
+    }
+
+    /** 校验显式收付方向，防止空方向绕过目录过滤。 */
+    private static void requireDirection(String direction) {
+        if (!"RECEIVABLE".equals(direction) && !"PAYABLE".equals(direction)) {
+            throw new BizException(ResultCode.BAD_REQUEST, "请选择费用收付方向");
+        }
+    }
+
+    /** 返回有限字段，不向其他服务暴露目录实体或审计属性。 */
+    private static Item snapshot(FeeItemEntity item) {
+        return new Item(item.getFeeCode(), item.getFeeTypeName(), item.getDefaultPrice());
+    }
+
+    public record Item(String code, String name, BigDecimal defaultPrice) { }
+}

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

@@ -9,7 +9,6 @@ import com.baiyue.firstleg.dto.TruckAppointmentDtos.*;
 import com.baiyue.firstleg.entity.*;
 import com.baiyue.firstleg.oceanbooking.entity.OceanBookingEntity;
 import com.baiyue.firstleg.oceanbooking.repository.OceanBookingRepository;
-import com.baiyue.firstleg.oceanbooking.service.OceanBookingDocumentService;
 import com.baiyue.firstleg.repository.TruckAppointmentRepository;
 import com.baiyue.firstleg.client.TruckAppointmentFileClient;
 import jakarta.annotation.Resource;
@@ -36,7 +35,6 @@ public class TruckAppointmentService {
  @Resource TruckAppointmentRepository repo;
  @Resource TruckAppointmentCompletionService completion;
  @Resource OceanBookingRepository oceanBookings;
- @Resource OceanBookingDocumentService oceanBookingDocuments;
  @Resource TruckAppointmentFileClient files;
  @Resource WarehouseSupplierSnapshotService suppliers;
  @Resource FirstlegDocumentNumberGenerator documentNumbers;
@@ -64,13 +62,13 @@ public class TruckAppointmentService {
   return completeOperation(id,action,idem,enrich(required(id)));
  }
  @Transactional public TruckAppointmentEntity reschedule(long id,LocalDateTime at,ActionRequest r,String idem,String clientHash,long uid,String name){String action="RESCHEDULE";String requestHash=hash(action,id,new ReschedulePayload(at,r));verifyClientHash(clientHash,requestHash);TruckAppointmentEntity replay=claimOrReplay(id,action,idem,requestHash);if(replay!=null)return replay;TruckAppointmentEntity e=required(id);completion.lockBooking(e.getOceanBookingId());checkVersion(e,r.expectedVersion()); if(e.getStatus()==TruckAppointmentStatus.COMPLETED||e.getStatus()==TruckAppointmentStatus.CANCELLED)throw conflict("当前状态不可改约"); TruckAppointmentEntity active=repo.firstActiveForUpdate(e.getOceanBookingId());if(active!=null&&!Objects.equals(active.getId(),e.getId()))throw existingAppointmentConflict(active);String from=e.getStatus().name(); if(repo.reschedule(id,at,r.reason(),e.getVersion())!=1)throw conflict("状态或版本已变化，请刷新后重试");TruckAppointmentEntity after=enrich(required(id));record(after,from,"RESCHEDULED",action,r.reason(),uid,name);completion.completeForBooking(e.getOceanBookingId());return completeOperation(id,action,idem,enrich(required(id)));}
+ /** 从已放舱订舱校验仓库和提单号，附件不作为预约条件。 */
  private AssociationContext validateAssociations(SaveRequest r){
   OceanBookingEntity booking=oceanBookings.find(r.oceanBookingId());
   if(booking==null)throw new BizException(ResultCode.NOT_FOUND,"关联订舱不存在");
   if(!"RELEASED".equals(booking.getStatus()))throw conflict("拖车预约只能选择已放舱订舱");
   Long warehouseId=mergeWarehouse(r.warehouseId(),booking.getWarehouseId(),"订舱");
   String billOfLadingNo=releasedBookingBill(booking,trim(r.billOfLadingNo()));
-  oceanBookingDocuments.requireActiveValidDocument(booking);
   return new AssociationContext(booking,warehouseId,billOfLadingNo);
  }
  private static void validateRequired(SaveRequest r){if(r.oceanBookingId()==null||r.oceanBookingId()<=0)throw bad("oceanBookingId不能为空");if(r.carrierId()==null||r.carrierId()<=0)throw bad("carrierId不能为空");if(r.plannedLoadingAt()==null)throw bad("plannedLoadingAt不能为空");if(r.expectedVersion()==null||r.expectedVersion()<0)throw bad("expectedVersion不合法");if(r.payableAmount()!=null&&(r.payableAmount().signum()<0||r.payableAmount().scale()>2))throw bad("拖车费必须为非负数且最多两位小数");}
@@ -85,13 +83,13 @@ public class TruckAppointmentService {
  private static void verifyClientHash(String clientHash,String serverHash){if(StringUtils.hasText(clientHash)&&!serverHash.equalsIgnoreCase(clientHash.trim()))throw bad("X-Request-Hash与请求内容不一致");}
  private static void validateKey(String key){if(!StringUtils.hasText(key)||key.trim().length()>128)throw bad("Idempotency-Key不能为空且不能超过128个字符");}
  private record ReschedulePayload(LocalDateTime plannedLoadingAt,ActionRequest request){}
+ /** 派车时复核订舱放舱状态及提单号，不要求订舱附件。 */
  private String requireDispatchReady(TruckAppointmentEntity appointment){
   if(appointment.getOceanBookingId()==null)throw conflict("拖车预约缺少订舱关联");
   OceanBookingEntity booking=oceanBookings.find(appointment.getOceanBookingId());
   if(booking==null)throw new BizException(ResultCode.NOT_FOUND,"关联订舱不存在");
   if(!"RELEASED".equals(booking.getStatus()))throw conflict("关联订舱尚未放舱");
   String bill=releasedBookingBill(booking,trim(appointment.getBillOfLadingNo()));
-  oceanBookingDocuments.requireActiveValidDocument(booking);
   return bill;
  }
  private static String releasedBookingBill(OceanBookingEntity booking,String requested){String authoritative=trim(booking.getBillOfLadingNo());if(!StringUtils.hasText(authoritative))throw conflict("关联已放舱订舱缺少提单号");if(StringUtils.hasText(requested)&&!authoritative.equals(requested))throw bad("billOfLadingNo与关联订舱不一致");return authoritative;}

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

@@ -9,11 +9,12 @@ 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.vessel_name vesselName,c.voyage_no voyageNo,
+          COALESCE(NULLIF(TRIM(c.destination_port_name),''),NULLIF(TRIM(c.destination_port_code),'')) 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
@@ -28,10 +29,11 @@ public interface ContainerCalendarSourceMapper {
         """)
     List<ContainerCalendarSource> byIds(@Param("ids") List<Long> ids);
 
-    /** 同时选出到港、缺日期和可能还柜的有效出仓柜，最终日期由业务服务复核。 */
+    /** 选出到港、缺日期和可能还柜的有效出仓柜；目的港名称为空时展示代码，最终日期由服务复核。 */
     @Select("""
         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.vessel_name vesselName,c.voyage_no voyageNo,
+          COALESCE(NULLIF(TRIM(c.destination_port_name),''),NULLIF(TRIM(c.destination_port_code),'')) 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

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

@@ -232,7 +232,7 @@ 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' AND NOT (
     (NEW.id <=> OLD.id)
     AND (NEW.booking_no <=> OLD.booking_no)
@@ -257,7 +257,6 @@ BEGIN
     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)
@@ -272,7 +271,7 @@ BEGIN
     AND (NEW.created_at <=> OLD.created_at)
     AND NEW.version = OLD.version + 1
   ) THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱运输资料不可修改，仅允许补录实货量';
+    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/db/phase3-smart-loading-schema.sql

@@ -35,7 +35,7 @@ CREATE TABLE IF NOT EXISTS fl_document_sequence (
 
 CREATE TABLE IF NOT EXISTS fl_container_booking (
   id BIGINT UNSIGNED NOT NULL COMMENT '货柜预订ID（雪花ID）',
-  container_no VARCHAR(64) NULL COMMENT '国内柜次真实集装箱号权威快照；ISO 6346标准格式；同一订舱内唯一，不同提单允许复用；订舱关联可选写入、提柜后可原子补录、预装纠错命令可修改',
+  container_no VARCHAR(64) NULL COMMENT '国内柜次真实集装箱号权威快照；订舱关联不限制ISO格式；同一订舱内唯一，不同提单允许复用；订舱关联可选写入、提柜后可原子补录、预装纠错命令可修改',
   cabinet_no VARCHAR(64) NOT NULL COMMENT '平台唯一内部柜号',
   source_type VARCHAR(24) NOT NULL DEFAULT 'SIMULATION' COMMENT '记录来源：SIMULATION内部模拟柜、OCEAN_BOOKING订舱真实柜',
   record_status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE' COMMENT '记录状态：ACTIVE可操作、MERGED已合并历史',
@@ -100,9 +100,7 @@ CREATE TABLE IF NOT EXISTS fl_container_booking (
   CONSTRAINT chk_container_booking_record_status CHECK (record_status IN ('ACTIVE','MERGED')),
   CONSTRAINT chk_container_booking_capacity CHECK (capacity_cbm IS NULL OR capacity_cbm > 0),
   CONSTRAINT chk_container_booking_weight CHECK (max_weight_kg IS NULL OR max_weight_kg > 0),
-  CONSTRAINT chk_container_booking_pickup_code CHECK (pickup_code IS NULL OR pickup_code REGEXP '^[0-9]{1,64}$'),
-  CONSTRAINT chk_container_booking_iso6346 CHECK
-    (container_no IS NULL OR container_no REGEXP '^[A-Z]{3}[UJZ][0-9]{7}$')
+  CONSTRAINT chk_container_booking_pickup_code CHECK (pickup_code IS NULL OR pickup_code REGEXP '^[0-9]{1,64}$')
 ) ENGINE=InnoDB COMMENT='平台货柜预订资料；预装状态唯一来源为装柜计划';
 
 CREATE TABLE IF NOT EXISTS fl_container_event_inbox (
@@ -228,11 +226,6 @@ BEGIN
     ALTER TABLE fl_container_booking ADD CONSTRAINT chk_container_booking_record_status
       CHECK (record_status IN ('ACTIVE','MERGED'));
   END IF;
-  IF NOT EXISTS (SELECT 1 FROM information_schema.table_constraints WHERE constraint_schema=DATABASE()
-      AND table_name='fl_container_booking' AND constraint_name='chk_container_booking_iso6346') THEN
-    ALTER TABLE fl_container_booking ADD CONSTRAINT chk_container_booking_iso6346
-      CHECK (container_no IS NULL OR container_no REGEXP '^[A-Z]{3}[UJZ][0-9]{7}$');
-  END IF;
   IF NOT EXISTS (SELECT 1 FROM information_schema.table_constraints WHERE constraint_schema=DATABASE()
       AND table_name='fl_container_booking' AND constraint_name='chk_container_booking_pickup_code') THEN
     ALTER TABLE fl_container_booking ADD CONSTRAINT chk_container_booking_pickup_code

firstleg/src/main/resources/openapi/appointment-calendar-sources-v1.yaml

@@ -40,7 +40,7 @@ paths:
                             containerNo: {type: string, nullable: true}
                             vesselName: {type: string, nullable: true}
                             voyageNo: {type: string, nullable: true}
-                            destinationPortName: {type: string, nullable: true}
+                            destinationPortName: {type: string, nullable: true, description: 目的港展示值，优先名称，名称为空时使用已保存的港口代码，两者均为空时返回null}
                             destinationWarehouseCode: {type: string, nullable: true}
                             arrivalAt: {type: string, format: date-time, nullable: true}
                             arrivalType: {type: string, enum: [ACTUAL, ESTIMATED]}

firstleg/src/main/resources/openapi/customs-v1.yaml

@@ -118,9 +118,9 @@ paths:
       x-permission: platform:firstleg:customs:list
       parameters: [{$ref: '#/components/parameters/DocumentId'}]
       responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
-  /api/platform/v1/customs/loading-plans/documents/{documentId}/receipt/download:
+  /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/download:
     get:
-      summary: 平台下载报关行回执
+      summary: 平台下载预录单
       x-permission: platform:firstleg:customs:list
       parameters: [{$ref: '#/components/parameters/DocumentId'}]
       responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}

firstleg/src/main/resources/openapi/fee-catalog-internal-v1.yaml

@@ -0,0 +1,24 @@
+openapi: 3.0.3
+info: { title: 公共费用目录内部查询, version: 1.0.0 }
+security: [{ internalToken: [] }]
+paths:
+  /internal/firstleg/v1/fee-items:
+    get:
+      summary: 查询当前启用的国际海外仓费用项目
+      parameters:
+        - { in: query, name: direction, schema: { type: string, enum: [RECEIVABLE, PAYABLE], default: RECEIVABLE } }
+      responses:
+        '200': { description: '统一响应data为费用项目数组，项目含code、name、defaultPrice；defaultPrice币种固定CNY，可为空。' }
+        '403': { description: 内部凭证缺失、错误或服务未配置凭证 }
+  /internal/firstleg/v1/fee-items/{code}:
+    get:
+      summary: 校验录费使用的当前费用项目资格
+      parameters:
+        - { in: path, name: code, required: true, schema: { type: string } }
+        - { in: query, name: direction, required: true, schema: { type: string, enum: [RECEIVABLE, PAYABLE] } }
+      responses:
+        '200': { description: 统一响应data为项目code、name、defaultPrice }
+        '409': { description: 项目不存在、停用或不适用于所选方向 }
+components:
+  securitySchemes:
+    internalToken: { type: apiKey, in: header, name: X-Internal-Service-Token }

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

@@ -607,7 +607,7 @@ paths:
   /api/platform/v1/containers/{id}/ocean-booking-link:
     post:
       summary: 将内部模拟柜关联到已发布订舱需求
-      description: 需要 platform:firstleg:container:edit；请求指定 RELEASED oceanBookingId 和未满配 requirementId，containerNo 可空。首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 模拟柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items，原子写入订舱、运输和范围快照并创建 allocation；提柜后由拖车链调用柜次服务原子补录真实柜号。若关联请求已提供 containerNo，服务端仍规范化并校验 ISO 6346 结构、设备类别和校验位，并保证同一订舱内唯一；不同提单允许复用同一集装箱号。存在跨仓、跨渠道、柜型规格不一致、超量、同提单重复柜号、PDA、有效装柜证据、业务单证或 LOADING/COMPLETED 等事实时拒绝。
+      description: 需要 platform:firstleg:container:edit；请求指定 RELEASED oceanBookingId 和未满配 requirementId，containerNo 可空。首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 模拟柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items，原子写入订舱、运输和范围快照并创建 allocation；提柜后由拖车链调用柜次服务原子补录真实柜号。若关联请求已提供 containerNo，服务端仅移除空白并转大写，不校验 ISO 6346 长度、结构或校验位，并保证同一订舱内唯一；不同提单允许复用同一集装箱号。运输信息、提柜补录、确认预装、创建PDA任务、装柜完成及跨服务事件统一不校验ISO格式；确认预装及创建PDA任务前仍必须补齐真实柜号。存在跨仓、跨渠道、柜型规格不一致、超量、同提单重复柜号、PDA、有效装柜证据、业务单证或 LOADING/COMPLETED 等事实时拒绝。
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ContainerOceanBookingLinkRequest'}}}}
       responses: {'200': {description: 关联后的同一模拟柜 containerBookingId/cabinetNo；列表仍只有这一条 ACTIVE 操作身份}}
@@ -2947,7 +2947,7 @@ components:
       properties:
         oceanBookingId: {type: integer, format: int64, minimum: 1, description: RELEASED订舱ID}
         requirementId: {type: integer, format: int64, minimum: 1, description: 未满配的订舱柜型需求ID}
-        containerNo: {type: string, nullable: true, maxLength: 64, description: 可选；港口提柜后可由拖车链另行原子补录。非空时服务端移除格式空白、转大写并校验ISO 6346结构、设备类别、校验位和同一订舱内唯一性}
+        containerNo: {type: string, nullable: true, maxLength: 64, description: 可选；港口提柜后可由拖车链另行原子补录。关联时移除格式空白并转大写，不校验ISO长度、结构或校验位，仍保证同一订舱内唯一；确认预装及创建PDA任务前必须补齐真实柜号，不校验ISO格式}
         expectedVersion: {type: integer, minimum: 0}
     ContainerFeeAdjustRequest:
       type: object

firstleg/src/main/resources/openapi/loading-lists-v1.yaml

@@ -50,7 +50,7 @@ paths:
       summary: 修改预装运输信息
       description: >-
         可在 EDITING 或 LOADING 阶段首次补录真实集装箱号；已有柜号的纠正仅限仍为 EDITING、PDA任务尚未领取且无任何物理作业事实时，并必须提供原因和当前版本；
-        containerNo 为 null 表示保持当前值，非空时服务端移除格式空白、转大写并校验ISO 6346结构、设备类别和校验位，空白字符串非法且禁止清空。
+        containerNo 为 null 时保留当前柜号；首次录入或纠正时服务端移除格式空白并转大写，不校验 ISO 6346 长度、结构、设备类别或校验位，空白字符串非法且禁止清空；同一订舱内柜号必须唯一。
       x-permission: platform:firstleg:preload:edit
       parameters:
         - {$ref: '#/components/parameters/PlanId'}

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

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: Ocean Booking API
   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.
+  description: Booking-owned files use File businessType OCEAN_BOOKING_DOCUMENT and businessId=oceanBookingId. 放舱不要求上传订舱确认文件或提单文件。 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}/estimated-arrival:
+    put:
+      summary: 放舱后维护预计到港
+      description: 仅允许RELEASED订舱按当前版本与幂等键维护estimatedArrivalAt，不得清空或早于预计开船时间；其他运输、预报、关系方、柜型与附件仍冻结，保存前后快照及操作人。不修改实际到港或计划到仓。
+      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/EstimatedArrivalRequest'}}}}
+      responses: {'200': {description: 已保存的RELEASED订舱详情，包含当前版本和预计到港}}
   /api/platform/v1/ocean-bookings/{oceanBookingId}/actual-cargo:
     put:
       summary: Supplement manual actual cargo on a RELEASED booking
@@ -40,7 +48,7 @@ paths:
   /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
     post:
       summary: Validate and permanently release a DRAFT
-      description: Release validates the persisted aggregate plus at least one active booking-owned BOOKING_CONFIRMATION or BILL_OF_LADING file. The customer is optional; a supplied customer must remain ACTIVE. Null denotes no single customer snapshot, never public access. It never requires or creates a real container number.
+      description: 放舱校验已保存的订舱业务资料，不以订舱确认文件或提单文件作为前置条件。 The customer is optional; a supplied customer must remain ACTIVE. Null denotes no single customer snapshot, never public access. It never requires or creates a real container number.
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReleaseRequest'}}}}
       responses: {'200': {description: RELEASED detail}}
@@ -200,7 +208,7 @@ 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}
@@ -217,6 +225,13 @@ components:
         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}, 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: 统一货重上限}}}
+    EstimatedArrivalRequest:
+      type: object
+      additionalProperties: false
+      required: [expectedVersion, estimatedArrivalAt]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        estimatedArrivalAt: {type: string, format: date-time}
     ActualCargoRequest:
       type: object
       additionalProperties: false

firstleg/src/main/resources/openapi/truck-appointments-v1.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: Truck Appointment API
   version: 2.0.0
-  description: A truck appointment belongs to one RELEASED ocean booking, independently of when or how that booking's internal containers are linked. Each booking may have at most one non-terminal appointment. The bill-of-lading number and warehouse are frozen from the booking, which must own at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file. Container identities and real container numbers remain in the container/loading modules and are not part of this API. PDA loading completion alone does not complete the appointment. All required containers must be allocated and confirmed departed from the domestic warehouse. Completion atomically creates approved ON_ACCOUNT container payable fees allocated by loaded volume and publishes their immutable snapshots through the existing Finance Outbox. Create, edit, submit and reschedule also recheck departure facts, covering late appointments. Zero amounts create no fee. Cancelled and exception appointments are excluded. RMB is the only appointment currency and maps to CNY in Finance.
+  description: A truck appointment belongs to one RELEASED ocean booking, independently of when or how that booking's internal containers are linked. Each booking may have at most one non-terminal appointment. The bill-of-lading number and warehouse are frozen from the booking. 预约创建及派车不要求订舱附件。 Container identities and real container numbers remain in the container/loading modules and are not part of this API. PDA loading completion alone does not complete the appointment. All required containers must be allocated and confirmed departed from the domestic warehouse. Completion atomically creates approved ON_ACCOUNT container payable fees allocated by loaded volume and publishes their immutable snapshots through the existing Finance Outbox. Create, edit, submit and reschedule also recheck departure facts, covering late appointments. Zero amounts create no fee. Cancelled and exception appointments are excluded. RMB is the only appointment currency and maps to CNY in Finance.
 paths:
   /api/platform/v1/truck-appointments:
     get:
@@ -33,7 +33,7 @@ paths:
   /api/platform/v1/truck-appointments/candidates:
     get:
       summary: Query authoritative create-time ocean-booking candidates
-      description: Requires platform:firstleg:truck-appointment:list. Returns one row per RELEASED booking with a bill of lading and an active booking-owned confirmation or bill file, excluding bookings that already have an active or completed truck appointment. Container allocation and loading status do not affect eligibility. Edit pages display their current booking from appointment detail rather than injecting it into this create-only result.
+      description: Requires platform:firstleg:truck-appointment:list. Returns one row per RELEASED booking with a bill of lading number, excluding bookings that already have an active or completed truck appointment. Container allocation and loading status do not affect eligibility. Edit pages display their current booking from appointment detail rather than injecting it into this create-only result.
       parameters:
         - {name: keyword, in: query, required: false, schema: {type: string, maxLength: 64}, description: Matches booking number or bill of lading}
         - {name: page, in: query, required: false, schema: {type: integer, format: int64, minimum: 1, default: 1}}
@@ -168,7 +168,7 @@ components:
         timestamp: {type: string, format: date-time}
     Candidate:
       type: object
-      required: [oceanBookingId, oceanBookingNo, warehouseId, bookingDocumentReady]
+      required: [oceanBookingId, oceanBookingNo, warehouseId]
       properties:
         oceanBookingId: {type: integer, format: int64}
         oceanBookingNo: {type: string}
@@ -177,7 +177,7 @@ components:
         warehouseName: {type: string, nullable: true}
         channelCode: {type: string, nullable: true}
         channelName: {type: string, nullable: true}
-        bookingDocumentReady: {type: boolean, enum: [true]}
+
     DetailEnvelope:
       type: object
       required: [code, message, data, timestamp]
@@ -221,7 +221,7 @@ components:
       required: [oceanBookingId, carrierId, plannedLoadingAt, expectedVersion]
       properties:
         outboundOrderId: {type: integer, format: int64, minimum: 1, nullable: true}
-        oceanBookingId: {type: integer, format: int64, minimum: 1, description: Required RELEASED booking; must have a bill of lading and own an active BOOKING_CONFIRMATION or BILL_OF_LADING file.}
+        oceanBookingId: {type: integer, format: int64, minimum: 1, description: Required RELEASED booking; must have a bill of lading number. 订舱附件不作为前置条件。}
         warehouseId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional consistency hint. The persisted warehouse is frozen from the selected booking.}
         carrierId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE Warehouse supplier ID validated as TRUCKING with truckingScope DOMESTIC (国内拖车).}
         carrierName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; the persisted snapshot comes from Warehouse supplier master data.}

firstleg/src/test/java/com/baiyue/firstleg/controller/ContainerControllerContractTest.java

@@ -88,7 +88,7 @@ class ContainerControllerContractTest {
     }
 
     @Test
-    @DisplayName("OpenAPI声明平台级货柜路径和冻结规则")
+    @DisplayName("OpenAPI声明平台级货柜路径、关联柜号格式放行及冻结规则")
     void documentsContainerContract() throws Exception {
         String openapi = new ClassPathResource("openapi/firstleg-v1.yaml")
             .getContentAsString(StandardCharsets.UTF_8);
@@ -106,7 +106,8 @@ class ContainerControllerContractTest {
             .contains("未满配 requirementId")
             .contains("containerNo 可空")
             .contains("提柜后由拖车链调用柜次服务原子补录真实柜号")
-            .contains("校验 ISO 6346 结构、设备类别和校验位，并保证同一订舱内唯一")
+            .contains("不校验 ISO 6346 长度、结构或校验位，并保证同一订舱内唯一")
+            .contains("运输信息、提柜补录、确认预装、创建PDA任务、装柜完成及跨服务事件统一不校验ISO格式")
             .doesNotContain("/api/platform/v1/containers/{id}/transport:")
             .doesNotContain("ContainerOceanBookingUnlinkRequest")
             .doesNotContain("ContainerTransportUpdateRequest")

firstleg/src/test/java/com/baiyue/firstleg/controller/LoadingListControllerContractTest.java

@@ -73,7 +73,7 @@ class LoadingListControllerContractTest {
             .contains("containerNo")
             .contains("voyageNo")
             .contains("首次补录真实集装箱号")
-            .contains("校验ISO 6346结构、设备类别和校验位")
+            .contains("不校验 ISO 6346 长度、结构、设备类别或校验位")
             .contains("PDA任务尚未领取且无任何物理作业事实")
             .contains("/loading-plans/{planId}/confirm")
             .contains("/loading-plans/{planId}/lifecycle")

firstleg/src/test/java/com/baiyue/firstleg/controller/TruckAppointmentControllerContractTest.java

@@ -30,7 +30,7 @@ class TruckAppointmentControllerContractTest {
  }
  @Test void openApiDocumentsLifecycleIdempotencyAndActualTimes() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/{id}/{action}:","/api/platform/v1/truck-appointments/{id}/reschedule:","name: Idempotency-Key","required: true","actual event timestamps");}
  @Test void openApiDocumentsActionableDuplicateCreateConflict() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("A0409","existing appointment number","continue editing","database booking-level unique key");}
- @Test void openApiPublishesBookingLevelCandidateContract() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/candidates:","Paged booking candidates","bookingDocumentReady","Container allocation and loading status do not affect eligibility").doesNotContain("requirementId:","containerBookingId:","loadingPlanId:");}
+ @Test void openApiPublishesBookingLevelCandidateContract() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/candidates:","Paged booking candidates","Container allocation and loading status do not affect eligibility").doesNotContain("requirementId:","containerBookingId:","loadingPlanId:");}
  @Test void openApiRequiresReleasedBookingWithoutContainerWriteProtocol() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("required: [oceanBookingId, carrierId, plannedLoadingAt, expectedVersion]","RELEASED ocean booking","PICKUP does not accept or write a container number","schema: {$ref: '#/components/schemas/DetailEnvelope'}").doesNotContain("containerBookingId:","loadingPlanId:","containerNo:","customerId", "customerName");}
  @Test void openApiKeepsOnlyNonBookingTruckAttachments() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("AttachmentRequest:","required: [fileId, attachmentType]","required: [attachmentType, file]","TRUCK_APPOINTMENT_ATTACHMENT","Deletes the appointment reference only","DetailStableReferences:","oceanBookingNo:","shippingCompanyName:","bookingAgentName:","billOfLadingNo:").doesNotContain("enum: [BILL_OF_LADING, DISPATCH_ORDER");}
  @Test void openApiExposesOnlyPayableWithFixedCurrencies() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("payableAmount:","enum: [RMB]","default: RMB").doesNotContain("receivableAmount");}

firstleg/src/test/java/com/baiyue/firstleg/customs/container/ContainerCustomsControllerContractTest.java

@@ -4,6 +4,7 @@ import com.baiyue.firstleg.customs.container.controller.*;
 import org.junit.jupiter.api.Test;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.core.io.ClassPathResource;
 import org.yaml.snakeyaml.Yaml;
 
@@ -12,6 +13,22 @@ import java.lang.reflect.Method;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class ContainerCustomsControllerContractTest {
+    /** 下载契约必须跟随实际 Controller，避免前端和文档共同固化不存在的地址。 */
+    @Test void platformPreEntryDownloadMatchesActualControllerAndOpenApi() throws Exception {
+        Method download = java.util.Arrays.stream(PlatformContainerCustomsController.class.getDeclaredMethods())
+            .filter(method -> method.getName().equals("downloadCompletion")).findFirst().orElseThrow();
+        String root = PlatformContainerCustomsController.class.getAnnotation(RequestMapping.class).value()[0];
+        String path = root + download.getAnnotation(GetMapping.class).value()[0];
+        String source = new ClassPathResource("openapi/customs-v1.yaml").getContentAsString(java.nio.charset.StandardCharsets.UTF_8);
+        java.util.Map<?, ?> specification = new Yaml().load(source);
+        java.util.Map<?, ?> paths = (java.util.Map<?, ?>) specification.get("paths");
+
+        assertThat(path).isEqualTo("/api/platform/v1/customs/loading-plans/documents/{documentId}/completion/download");
+        assertThat(paths.containsKey(path)).isTrue();
+        assertThat(paths.containsKey(root + "/documents/{documentId}/receipt/download")).isFalse();
+        assertThat(download.getAnnotation(PreAuthorize.class).value()).contains("platform:firstleg:customs:list");
+    }
+
     @Test void platformUsesListForReadsAndManageForWrites() {
         assertThat(PlatformContainerCustomsController.class.getAnnotation(RequestMapping.class).value())
             .containsExactly("/api/platform/v1/customs/loading-plans");

firstleg/src/test/java/com/baiyue/firstleg/customs/container/ContainerCustomsServiceTest.java

@@ -442,6 +442,7 @@ class ContainerCustomsServiceTest {
         verifyNoInteractions(files);
     }
 
+    /** 上传被拒绝时使用预录单名称，并保留报关行执行后的替换门禁。 */
     @Test void receiptCannotBeReplacedAfterBrokerSubmission(){
         var source=document(1L);when(mapper.document(1L)).thenReturn(source);
         when(mapper.claimCommand(anyLong(),eq(5L),eq("UPLOAD_COMPLETION_1"),eq("broker-sent-key"),anyString())).thenReturn(1);
@@ -450,7 +451,10 @@ class ContainerCustomsServiceTest {
         when(mapper.brokerSubmittedAt(2L)).thenReturn(java.time.LocalDateTime.now());
         var file=new MockMultipartFile("file","result.bin","application/octet-stream",new byte[]{1});
         assertThatThrownBy(()->service.uploadCompletion(1L,5L,"admin","broker-sent-key",0,file))
-            .isInstanceOf(BizException.class).hasMessageContaining("不可再修改回执");
+            .isInstanceOfSatisfying(BizException.class, error -> {
+                assertThat(error.getResultCode()).isEqualTo(ResultCode.CONFLICT);
+                assertThat(error).hasMessage("客户确认的预录单已发送给报关行，不可再修改预录单");
+            });
         verifyNoInteractions(files);
     }
 
@@ -512,11 +516,43 @@ class ContainerCustomsServiceTest {
         verify(mapper,never()).complete(anyLong(),anyInt(),anyLong(),anyString());
     }
 
+    /** 下载不可见或缺失的预录单时使用正式名称，不改变客户范围校验。 */
     @Test void merchantCannotDownloadCompletionBeforeWholeContainerCompletes(){
         var source=document(1L);when(mapper.document(1L)).thenReturn(source);
         when(mapper.containerById(2L)).thenReturn(container(ContainerCustomsService.DECLARING,3));
         assertThatThrownBy(()->service.downloadCompletion(7L,1L,false)).isInstanceOf(BizException.class)
-            .hasMessageContaining("报关行回执不存在");
+            .hasMessageContaining("预录单不存在");
+        verifyNoInteractions(files);
+    }
+
+    /** 平台下载的当前预录单不存在时仍返回原业务错误码和正式名称。 */
+    @Test void platformMissingPreEntryDocumentUsesCurrentName() {
+        when(mapper.document(1L)).thenReturn(document(1L));
+        when(mapper.completion(1L)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.downloadCompletion(0L, 1L, true))
+            .isInstanceOfSatisfying(BizException.class, error -> {
+                assertThat(error.getResultCode()).isEqualTo(ResultCode.NOT_FOUND);
+                assertThat(error).hasMessage("预录单不存在");
+            });
+        verifyNoInteractions(files);
+    }
+
+    /** 发送前置校验仅调整用户可见名称，不改变全买单或客户确认门禁。 */
+    @ParameterizedTest
+    @CsvSource({"0,0,全买单柜无需发送预录单确认结果给报关行", "1,1,仍有预录单未完成客户确认"})
+    void brokerSubmissionErrorsUsePreEntryDocumentName(int taxRefundCount, int unconfirmedCount, String message) {
+        when(mapper.claimCommand(anyLong(), eq(5L), eq("SUBMIT_CUSTOMS_TO_BROKER_9"), eq("pre-entry-name"), anyString())).thenReturn(1);
+        when(mapper.lockContainer(9L)).thenReturn(container(ContainerCustomsService.DECLARING, 3));
+        when(mapper.taxRefundCount(9L)).thenReturn(taxRefundCount);
+        when(mapper.unconfirmedReceiptCount(2L)).thenReturn(unconfirmedCount);
+
+        assertThatThrownBy(() -> service.submitToBroker(9L, 5L, "admin", "pre-entry-name", new ActionRequest(3, true, null)))
+            .isInstanceOfSatisfying(BizException.class, error -> {
+                assertThat(error.getResultCode()).isEqualTo(ResultCode.CONFLICT);
+                assertThat(error).hasMessage(message);
+            });
+        verify(mapper, never()).submitToBroker(anyLong(), anyInt(), anyLong(), anyString());
         verifyNoInteractions(files);
     }
 

firstleg/src/test/java/com/baiyue/firstleg/domain/Iso6346ContainerNumberTest.java

@@ -1,23 +0,0 @@
-package com.baiyue.firstleg.domain;
-
-import com.baiyue.common.core.exception.BizException;
-import org.junit.jupiter.api.Test;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
-class Iso6346ContainerNumberTest {
-    @Test
-    void normalizesAllowedWhitespaceAndLowercase() {
-        assertThat(Iso6346ContainerNumber.require(" ms cu 663987 0 "))
-            .isEqualTo("MSCU6639870");
-    }
-
-    @Test
-    void rejectsWrongEquipmentCategoryAndCheckDigit() {
-        assertThatThrownBy(() -> Iso6346ContainerNumber.require("MSCA6639870"))
-            .isInstanceOf(BizException.class).hasMessageContaining("设备类别");
-        assertThatThrownBy(() -> Iso6346ContainerNumber.require("MSCU6639871"))
-            .isInstanceOf(BizException.class).hasMessageContaining("校验位");
-    }
-}

firstleg/src/test/java/com/baiyue/firstleg/domain/RealContainerNumberTest.java

@@ -0,0 +1,28 @@
+package com.baiyue.firstleg.domain;
+
+import com.baiyue.common.core.exception.BizException;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class RealContainerNumberTest {
+    /** 录入只去空白转大写，ISO 长度、设备类别与校验位不构成门禁。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCA6639870", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void normalizesWithoutIsoValidation(String containerNo) {
+        assertThat(RealContainerNumber.require(" \u00a0" + containerNo.toLowerCase(java.util.Locale.ROOT) + " "))
+            .isEqualTo(containerNo);
+    }
+
+    /** 空柜号不能进入实际作业，包含规范化后为空的 Unicode 空白。 */
+    @ParameterizedTest
+    @NullAndEmptySource
+    @ValueSource(strings = {"   ", "\u00a0\u3000"})
+    void rejectsMissingNumber(String containerNo) {
+        assertThatThrownBy(() -> RealContainerNumber.require(containerNo))
+            .isInstanceOf(BizException.class).hasMessageContaining("不能为空");
+    }
+}

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

@@ -14,6 +14,37 @@ import java.nio.file.Path;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class PlatformOceanBookingControllerContractTest {
+    /** 预计到港命令仅接收版本与时间，沿用编辑权限及独立审计。 */
+    @Test void estimatedArrivalCommandHasNarrowDtoAndEditPermission() throws Exception {
+        var endpoint = method("updateEstimatedArrival");
+        assertThat(endpoint.getAnnotation(org.springframework.web.bind.annotation.PutMapping.class).value()).containsExactly("/{oceanBookingId}/estimated-arrival");
+        assertThat(endpoint.getAnnotation(PreAuthorize.class).value()).isEqualTo("hasAuthority('platform:firstleg:ocean-booking:edit')");
+        assertThat(endpoint.getAnnotation(BusinessAudit.class)).isNotNull();
+        assertThat(Arrays.stream(com.baiyue.firstleg.oceanbooking.dto.OceanBookingDtos.EstimatedArrivalRequest.class.getRecordComponents())
+            .map(java.lang.reflect.RecordComponent::getName)).containsExactly("expectedVersion", "estimatedArrivalAt");
+        assertThat(Files.readString(Path.of("src/main/resources/openapi/ocean-bookings-v1.yaml")))
+            .contains("/api/platform/v1/ocean-bookings/{oceanBookingId}/estimated-arrival:", "#/components/schemas/EstimatedArrivalRequest");
+    }
+
+    /** 真实方法权限拦截器拒绝只有读取权限的账号，命令不会进入服务层。 */
+    @Test void estimatedArrivalRejectsReadOnlyAccountBeforeServiceCall() {
+        var service = org.mockito.Mockito.mock(com.baiyue.firstleg.oceanbooking.service.OceanBookingService.class);
+        var target = new PlatformOceanBookingController();
+        org.springframework.test.util.ReflectionTestUtils.setField(target, "service", service);
+        var factory = new org.springframework.aop.framework.ProxyFactory(target);
+        factory.setProxyTargetClass(true);
+        factory.addAdvisor(org.springframework.security.authorization.method.AuthorizationManagerBeforeMethodInterceptor.preAuthorize());
+        var secured = (PlatformOceanBookingController) factory.getProxy();
+        var context = org.springframework.security.core.context.SecurityContextHolder.getContext();
+        context.setAuthentication(new org.springframework.security.authentication.UsernamePasswordAuthenticationToken("reader", "",
+            java.util.List.of(new org.springframework.security.core.authority.SimpleGrantedAuthority("platform:firstleg:ocean-booking:list"))));
+        try {
+            org.assertj.core.api.Assertions.assertThatThrownBy(() -> secured.updateEstimatedArrival(null, 1L, "eta-denied",
+                new com.baiyue.firstleg.oceanbooking.dto.OceanBookingDtos.EstimatedArrivalRequest(3, java.time.LocalDateTime.now())))
+                .isInstanceOf(org.springframework.security.access.AccessDeniedException.class);
+            org.mockito.Mockito.verifyNoInteractions(service);
+        } finally { org.springframework.security.core.context.SecurityContextHolder.clearContext(); }
+    }
     @Test
     void usesDedicatedResourceAndPermissions() {
         assertThat(PlatformOceanBookingController.class.getAnnotation(RequestMapping.class).value())

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

@@ -14,6 +14,13 @@ import java.util.Arrays;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class OceanBookingMapperContractTest {
+    /** 放舱后预计到港只更新该字段及版本审计，不允许带出其他冻结资料。 */
+    @Test void estimatedArrivalUpdateIsNarrowAndVersioned() throws Exception {
+        String sql = String.join("\n", OceanBookingMapper.class.getDeclaredMethod("updateEstimatedArrival", long.class,
+            java.time.LocalDateTime.class, int.class, long.class, String.class).getAnnotation(Update.class).value());
+        assertThat(sql).contains("estimated_arrival_at=#{estimatedArrivalAt}", "status='RELEASED'", "version=#{version}", "version=version+1")
+            .doesNotContain("vessel_name=", "voyage_no=", "estimated_sailing_at=", "actual_", "declared_", "warehouse_id=");
+    }
     @Test
     void listUsesPlatformAggregateFilters() throws Exception {
         String sql = String.join("\n", OceanBookingMapper.class.getDeclaredMethod("selectPage",

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

@@ -10,6 +10,14 @@ import java.nio.file.Path;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class OceanBookingSqlContractTest {
+    /** 两份触发器基线只放开预计到港，继续冻结船名、开船、预报和其他运输资料。 */
+    @Test void releasedFreezeAllowsEstimatedArrivalOnly() throws Exception {
+        for (String source : new String[] {sql(), Files.readString(Path.of("../deploy/sql/头程数据库统一增量-MySQL8.sql"))}) {
+            assertThat(source).doesNotContain("NEW.estimated_arrival_at <=> OLD.estimated_arrival_at")
+                .contains("NEW.vessel_name <=> OLD.vessel_name", "NEW.estimated_sailing_at <=> OLD.estimated_sailing_at",
+                    "NEW.declared_package_count <=> OLD.declared_package_count", "NEW.version = OLD.version + 1");
+        }
+    }
     @Test
     void definesDedicatedAggregateWithoutChangingContainerSemantics() throws Exception {
         String sql = sql();

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

@@ -118,7 +118,7 @@ class OceanBookingServiceTest {
         assertThat(result.oceanBooking().getStatus()).isEqualTo("RELEASED");
         assertThat(result.oceanBooking().getCustomerId()).isNull();
         assertThat(result.oceanBooking().getCustomerName()).isNull();
-        verify(documents).requireActiveValidDocument(stored.get());
+        verifyNoInteractions(documents);
         verify(customers, times(initialCustomer ? 1 : 0)).active(anyLong(), any());
     }
 
@@ -188,21 +188,22 @@ class OceanBookingServiceTest {
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
     }
 
+    /** 无订舱附件时仍可按完整业务资料放舱。 */
     @Test
-    void rejectsReleaseWithoutActiveBookingOwnedFileWithoutStateDrift() {
+    void releasesWithoutBookingFiles() {
         stubMasterData();
         OceanBookingEntity draft = completeBooking("DRAFT", 3);
-        when(repository.find(1L)).thenReturn(draft);
+        when(repository.find(1L)).thenReturn(draft, completeBooking("RELEASED", 4));
         when(repository.parties(1L)).thenReturn(parties());
         when(repository.requirements(1L)).thenReturn(List.of(requirement()));
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
-            "订舱缺少有效订舱确认或提单文件"))
-            .when(documents).requireActiveValidDocument(draft);
+        when(repository.documents(1L)).thenReturn(List.of());
+        when(repository.transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin")).thenReturn(1);
 
-        assertThatThrownBy(() -> service.release(1L, 9L, "admin", "release-no-file",
-            new ReleaseRequest(3, "确认")))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
-        verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
+        Detail result = service.release(1L, 9L, "admin", "release-no-file", new ReleaseRequest(3, "确认"));
+        assertThat(result.oceanBooking().getStatus()).isEqualTo("RELEASED");
+        assertThat(result.documents()).isEmpty();
+        verifyNoInteractions(documents);
+        verify(repository).transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin");
     }
 
     @Test
@@ -231,6 +232,19 @@ class OceanBookingServiceTest {
         verify(repository, times(1)).transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin");
     }
 
+    /** 缺预计到港不能放舱，避免关联柜次后丢失日历及默认到仓日期来源。 */
+    @Test
+    void rejectsReleaseWithoutEstimatedArrival() {
+        OceanBookingEntity draft = completeBooking("DRAFT", 3);
+        draft.setEstimatedArrivalAt(null);
+        when(repository.find(1L)).thenReturn(draft);
+        when(repository.parties(1L)).thenReturn(parties());
+        when(repository.requirements(1L)).thenReturn(List.of(requirement()));
+        assertThatThrownBy(() -> service.release(1L, 9L, "admin", "release-no-arrival", new ReleaseRequest(3, "确认放舱")))
+            .isInstanceOf(BizException.class).hasMessageContaining("尚未填写完整");
+        verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
+    }
+
     @Test
     void rejectsCarrierSnapshotMismatchAndUnassociatedBookingAgent() {
         stubMasterData();
@@ -386,6 +400,57 @@ class OceanBookingServiceTest {
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
     }
 
+    /** 预计到港独立更新、回显并保留修改前后审计，不能触及其他冻结字段。 */
+    @Test void maintainsReleasedEstimatedArrivalWithVersionAndAudit() {
+        var before = completeBooking("RELEASED", 3);
+        var after = objectMapper.convertValue(before, OceanBookingEntity.class);
+        var arrival = before.getEstimatedSailingAt().plusDays(20);
+        after.setEstimatedArrivalAt(arrival); after.setVersion(4);
+        when(repository.find(1L)).thenReturn(before, after);
+        when(repository.updateEstimatedArrival(1L, arrival, 3, 9L, "admin")).thenReturn(1);
+
+        var result = service.updateEstimatedArrival(1L, 9L, "admin", "eta-save", new EstimatedArrivalRequest(3, arrival));
+
+        assertThat(result.oceanBooking().getEstimatedArrivalAt()).isEqualTo(arrival);
+        assertThat(result.oceanBooking().getVersion()).isEqualTo(4);
+        assertThat(result.oceanBooking().getVesselName()).isEqualTo(before.getVesselName());
+        var history = ArgumentCaptor.forClass(com.baiyue.firstleg.oceanbooking.entity.OceanBookingStatusHistoryEntity.class);
+        verify(repository).insert(history.capture());
+        assertThat(history.getValue().getAction()).isEqualTo("UPDATE_ESTIMATED_ARRIVAL");
+        assertThat(history.getValue().getBeforeSnapshot()).contains("estimatedArrivalAt");
+        assertThat(history.getValue().getAfterSnapshot()).contains("estimatedArrivalAt");
+        verify(repository, never()).updateDraft(any(), anyInt(), anyLong(), any());
+        verify(repository, never()).replaceRequirements(anyLong(), any());
+    }
+
+    /** 草稿、旧版本、空值及逆序时间均不能走放舱后的预计到港命令。 */
+    @Test void rejectsInvalidEstimatedArrivalCommands() {
+        var value = completeBooking("DRAFT", 3);
+        when(repository.find(1L)).thenReturn(value);
+        var arrival = value.getEstimatedSailingAt().plusDays(20);
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-draft", new EstimatedArrivalRequest(3, arrival))).isInstanceOf(BizException.class);
+        value.setStatus("RELEASED");
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-stale", new EstimatedArrivalRequest(2, arrival))).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-empty", new EstimatedArrivalRequest(3, null))).hasMessageContaining("不能为空");
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-early", new EstimatedArrivalRequest(3, value.getEstimatedSailingAt().minusSeconds(1)))).hasMessageContaining("不能早于");
+        when(repository.updateEstimatedArrival(anyLong(), any(), anyInt(), anyLong(), any())).thenReturn(0);
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-conflict", new EstimatedArrivalRequest(3, arrival))).isInstanceOf(BizException.class);
+    }
+
+    /** 同一预计到港命令重放复用原结果，不重复保存或追加审计。 */
+    @Test void estimatedArrivalReplayDoesNotWriteAgain() throws Exception {
+        var request = new EstimatedArrivalRequest(3, LocalDateTime.of(2026, 10, 25, 10, 0));
+        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_ESTIMATED_ARRIVAL", 1L, request));
+        operation.setStatus("SUCCESS"); operation.setResultJson(objectMapper.writeValueAsString(replay));
+        when(repository.claimOperation(1L, 9L, "UPDATE_ESTIMATED_ARRIVAL", "eta-replay", operation.getRequestHash())).thenReturn(false);
+        when(repository.operation(9L, "UPDATE_ESTIMATED_ARRIVAL", "eta-replay")).thenReturn(operation);
+        assertThat(service.updateEstimatedArrival(1L, 9L, "admin", "eta-replay", request).oceanBooking().getVersion()).isEqualTo(4);
+        verify(repository, never()).updateEstimatedArrival(anyLong(), any(), anyInt(), anyLong(), any());
+        verify(repository, never()).insert(any(com.baiyue.firstleg.oceanbooking.entity.OceanBookingStatusHistoryEntity.class));
+    }
+
     @Test
     void supplementsReleasedActualCargoWithVersionAndBeforeAfterAudit() {
         OceanBookingEntity before = completeBooking("RELEASED", 3);

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

@@ -8,12 +8,23 @@ import org.apache.ibatis.annotations.Param;
 import org.apache.ibatis.annotations.Update;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean;
+import com.baiyue.firstleg.oceanbooking.entity.OceanBookingEntity;
+import org.h2.jdbcx.JdbcDataSource;
+import org.mybatis.spring.SqlSessionTemplate;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.test.util.ReflectionTestUtils;
 
 import java.util.Arrays;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 @DisplayName("货柜数据库映射契约")
 class ContainerBookingMapperContractTest {
@@ -106,7 +117,7 @@ class ContainerBookingMapperContractTest {
     }
 
     @Test
-    @DisplayName("初始化与统一增量锁定真实柜号权威、订舱内唯一和ISO结构约束")
+    @DisplayName("初始化与统一增量保留柜号权威及订舱内唯一，不限制关联柜号ISO格式")
     void databaseContractsFreezeAuthoritativeContainerNumber() throws Exception {
         String module = Files.readString(Path.of("src/main/resources/db/phase3-smart-loading-schema.sql"));
         String unified = Files.readString(Path.of("../deploy/sql/头程数据库统一增量-MySQL8.sql"));
@@ -118,8 +129,41 @@ class ContainerBookingMapperContractTest {
             assertThat(source.toLowerCase())
                 .contains("unique key uk_container_booking_ocean_container (ocean_booking_id,container_no)")
                 .contains("key idx_container_booking_container_no (container_no,updated_at,id)")
-                .contains("constraint chk_container_booking_iso6346")
-                .contains("^[a-z]{3}[ujz][0-9]{7}$");
+                .doesNotContain("chk_container_booking_iso6346", "^[a-z]{3}[ujz][0-9]{7}$");
         }
     }
+
+    /** 从当前建表基线创建隔离数据库，真实执行关联 Mapper 并验证唯一键和版本。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void linksNonIsoContainerNumbersThroughActualSchemaAndMapper(String containerNo) throws Exception {
+        var dataSource = new JdbcDataSource();
+        dataSource.setURL("jdbc:h2:mem:container-link-" + java.util.UUID.randomUUID() + ";MODE=MySQL;DB_CLOSE_DELAY=-1");
+        var jdbc = new JdbcTemplate(dataSource);
+        String source = Files.readString(Path.of("src/main/resources/db/phase3-smart-loading-schema.sql"));
+        int start = source.indexOf("CREATE TABLE IF NOT EXISTS fl_container_booking (");
+        jdbc.execute(source.substring(start, source.indexOf(';', source.indexOf(") ENGINE=InnoDB", start)) + 1));
+        for (long id = 1; id <= 3; id++) {
+            jdbc.update("INSERT INTO fl_container_booking(id,cabinet_no,warehouse_id,warehouse_name,container_type,created_by,updated_by) VALUES(?,?,8,'测试仓','40HQ',9,9)",
+                id, "D" + id);
+        }
+        var configuration = new MybatisConfiguration();
+        configuration.setMapUnderscoreToCamelCase(true);
+        configuration.addMapper(ContainerBookingMapper.class);
+        var factory = new MybatisSqlSessionFactoryBean();
+        factory.setDataSource(dataSource);
+        factory.setConfiguration(configuration);
+        var session = new SqlSessionTemplate(factory.getObject());
+        var repository = new ContainerRepository();
+        ReflectionTestUtils.setField(repository, "mapper", session.getMapper(ContainerBookingMapper.class));
+        var booking = new OceanBookingEntity();
+
+        assertThat(repository.linkReleasedBooking(1L, 21L, 31L, containerNo, booking, 0, 9L, "操作员")).isEqualTo(1);
+        assertThat(jdbc.queryForObject("SELECT container_no FROM fl_container_booking WHERE id=1", String.class)).isEqualTo(containerNo);
+        assertThat(jdbc.queryForObject("SELECT version FROM fl_container_booking WHERE id=1", Integer.class)).isEqualTo(1);
+        assertThat(repository.linkReleasedBooking(1L, 21L, 31L, containerNo, booking, 0, 9L, "操作员")).isZero();
+        assertThatThrownBy(() -> repository.linkReleasedBooking(2L, 21L, 31L, containerNo, booking, 0, 9L, "操作员"))
+            .isInstanceOf(DuplicateKeyException.class);
+        assertThat(repository.linkReleasedBooking(3L, 22L, 32L, containerNo, booking, 0, 9L, "操作员")).isEqualTo(1);
+    }
 }

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

@@ -0,0 +1,107 @@
+package com.baiyue.firstleg.repository;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.MybatisSqlSessionFactoryBuilder;
+import com.baiyue.firstleg.mapper.InboundPricingMapper;
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.session.SqlSession;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** 通过真实 Mapper 执行费用状态更新，防止业务层放行但持久化条件遗漏作业状态。 */
+class FbaPricingFeeTransitionTest {
+    private SqlSession session;
+    private JdbcTemplate sql;
+    private FbaPricingRepository repository;
+
+    /** 每项测试使用独立内存表，保留真实的客户和逻辑删除条件。 */
+    @BeforeEach
+    void setUp() throws Exception {
+        var ds = new JdbcDataSource();
+        ds.setURL("jdbc:h2:mem:fee-transition-" + UUID.randomUUID() + ";MODE=MySQL");
+        var config = new MybatisConfiguration();
+        config.setEnvironment(new Environment("test", new JdbcTransactionFactory(), ds));
+        config.addMapper(InboundPricingMapper.class);
+        session = new MybatisSqlSessionFactoryBuilder().build(config).openSession(true);
+        session.getConnection();
+        sql = new JdbcTemplate(ds);
+        sql.execute("CREATE TABLE fl_inbound_order(id BIGINT PRIMARY KEY,tenant_id BIGINT," +
+            "process_status VARCHAR(32),fee_status VARCHAR(32),deleted BOOLEAN DEFAULT FALSE)");
+        repository = new FbaPricingRepository();
+        ReflectionTestUtils.setField(repository, "inbounds", session.getMapper(InboundPricingMapper.class));
+    }
+
+    /** 关闭最后一个连接后销毁本项测试的内存数据库。 */
+    @AfterEach
+    void tearDown() {
+        if (session != null) session.close();
+    }
+
+    /** 费用确认和发送不得提前完成一件代发组托或回退已有履约进度。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"FEE_CONFIRMING", "WAIT_PALLET", "WAIT_PALLETIZE", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"})
+    void confirmsAndSendsWithoutAdvancingPalletization(String processStatus) {
+        insertInbound(processStatus, "CALCULATED");
+
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isEqualTo(1);
+        assertState(processStatus, "CONFIRMED");
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isZero();
+        assertThat(repository.markInboundFeeSent(10001L, 88L, processStatus)).isEqualTo(1);
+        assertState("FEE_CONFIRMING".equals(processStatus) ? "WAIT_PALLET" : processStatus, "SENT");
+        assertThat(repository.markInboundFeeSent(10001L, 88L, processStatus)).isZero();
+    }
+
+    /** 待组托只补费用确认资格，不能绕过费用快照的前置状态。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"UNPRICED", "CONFIRMED", "SENT", "VOIDED"})
+    void rejectsConfirmationUnlessFeeIsCalculated(String feeStatus) {
+        insertInbound("WAIT_PALLETIZE", feeStatus);
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isZero();
+        assertState("WAIT_PALLETIZE", feeStatus);
+    }
+
+    /** 非确认阶段、其他客户和已删除入库单仍不可确认。 */
+    @Test
+    void preservesProcessCustomerAndDeletionGuards() {
+        insertInbound("WAIT_MEASURE", "CALCULATED");
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isZero();
+        sql.update("UPDATE fl_inbound_order SET process_status='WAIT_PALLETIZE' WHERE id=88");
+        assertThat(repository.markInboundConfirmed(20002L, 88L)).isZero();
+        sql.update("UPDATE fl_inbound_order SET deleted=TRUE WHERE id=88");
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isZero();
+        assertState("WAIT_PALLETIZE", "CALCULATED");
+    }
+
+    /** 模拟发送前作业状态发生变化，旧状态条件须拒绝写入。 */
+    @Test
+    void rejectsSendWithStaleProcessStatus() {
+        insertInbound("WAIT_SPLIT", "CONFIRMED");
+        assertThat(repository.markInboundFeeSent(10001L, 88L, "WAIT_PALLETIZE")).isZero();
+        assertState("WAIT_SPLIT", "CONFIRMED");
+    }
+
+    /** 准备单个客户的入库单，不调用共享环境。 */
+    private void insertInbound(String processStatus, String feeStatus) {
+        sql.update("INSERT INTO fl_inbound_order(id,tenant_id,process_status,fee_status) VALUES(88,10001,?,?)",
+            processStatus, feeStatus);
+    }
+
+    /** 同时核对物理作业状态与费用状态，防止用改主流程掩盖发送问题。 */
+    private void assertState(String processStatus, String feeStatus) {
+        assertThat(sql.queryForObject("SELECT process_status FROM fl_inbound_order WHERE id=88", String.class))
+            .isEqualTo(processStatus);
+        assertThat(sql.queryForObject("SELECT fee_status FROM fl_inbound_order WHERE id=88", String.class))
+            .isEqualTo(feeStatus);
+    }
+}

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

@@ -194,8 +194,9 @@ class FbaPricingRepositoryRuleListTest {
             .contains(10001L, 88L, "FEE_CONFIRMING", "CONFIRMED", "SENT", "WAIT_PALLET");
     }
 
+    /** 费用确认状态集覆盖待组托及后续履约阶段。 */
     @Test
-    void feeConfirmationAllowsPostLoadingInboundStatuses() {
+    void feeConfirmationAllowsPalletizationAndPostLoadingInboundStatuses() {
         String source;
         try {
             source = Files.readString(Path.of(
@@ -205,7 +206,7 @@ class FbaPricingRepositoryRuleListTest {
             throw new AssertionError(exception);
         }
         assertThat(source)
-            .contains("List.of(\"FEE_CONFIRMING\", \"WAIT_PALLET\", \"WAIT_SPLIT\", \"LOADING\", \"LOADED\", \"DELIVERED\")");
+            .contains("List.of(\"FEE_CONFIRMING\", \"WAIT_PALLET\", \"WAIT_PALLETIZE\", \"WAIT_SPLIT\", \"LOADING\", \"LOADED\", \"DELIVERED\")");
     }
 
     @Test

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

@@ -10,6 +10,7 @@ import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class TruckAppointmentMapperContractTest {
+    /** 候选不依赖附件，仍保留提单号、状态、唯一预约和乐观锁条件。 */
     @Test void mapsToPhase3TableAndUsesOptimisticGuards() throws Exception {
         assertThat(TruckAppointmentEntity.class.getAnnotation(TableName.class).value()).isEqualTo("fl_truck_appointment");
         String page = TruckAppointmentMapper.class.getMethod("page", com.baomidou.mybatisplus.extension.plugins.pagination.Page.class, com.baiyue.firstleg.dto.TruckAppointmentDtos.Query.class).getAnnotation(Select.class).value()[0];
@@ -18,9 +19,10 @@ class TruckAppointmentMapperContractTest {
             .doesNotContain("fl_container_booking", "cabinet_no", "container_no");
         assertThat(page).doesNotContain("customer_id", "customerId", "customer_name");
         String candidates = TruckAppointmentMapper.class.getMethod("candidates", com.baomidou.mybatisplus.extension.plugins.pagination.Page.class, com.baiyue.firstleg.dto.TruckAppointmentDtos.CandidateQuery.class).getAnnotation(Select.class).value()[0];
-        assertThat(candidates).contains("FROM fl_ocean_booking o", "o.status='RELEASED'", "d.valid=1",
-            "'BOOKING_CONFIRMATION','BILL_OF_LADING'", "t.ocean_booking_id=o.id",
-            "t.status NOT IN ('CANCELLED','EXCEPTION')", "bookingDocumentReady");
+        assertThat(candidates).contains("FROM fl_ocean_booking o", "o.status='RELEASED'",
+            "o.bill_of_lading_no IS NOT NULL", "o.bill_of_lading_no<>''", "t.ocean_booking_id=o.id",
+            "t.status NOT IN ('CANCELLED','EXCEPTION')");
+        assertThat(candidates).doesNotContain("fl_ocean_booking_document", "bookingDocumentReady");
         assertThat(candidates).doesNotContain("fl_ocean_booking_container_allocation", "fl_container_booking",
             "loadingPlanId", "containerBookingId", "cabinetNo", "containerNo");
         String transition = TruckAppointmentMapper.class.getMethod("transition", long.class, String.class, String.class, int.class).getAnnotation(Update.class).value()[0];

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

@@ -297,21 +297,23 @@ class ContainerServiceTest {
         verifyNoInteractions(oceanBookings);
     }
 
-    @Test
+    /** 提柜补录使用相同的非 ISO 规则，并按版本原子保存。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "LOCAL-2026-001"})
     @DisplayName("提柜后按柜次版本原子补录真实柜号")
-    void assignsRealContainerNumberAfterPickup() {
+    void assignsRealContainerNumberAfterPickup(String containerNo) {
         ContainerBookingEntity linked = booking("EDITING", 3);
         linked.setContainerNo(null); linked.setOceanBookingId(21L); linked.setOceanBookingRequirementId(31L);
         ContainerBookingEntity assigned = booking("EDITING", 4);
-        assigned.setContainerNo("MSCU6639870"); assigned.setOceanBookingId(21L); assigned.setOceanBookingRequirementId(31L);
+        assigned.setContainerNo(containerNo); assigned.setOceanBookingId(21L); assigned.setOceanBookingRequirementId(31L);
         when(repository.find(11L)).thenReturn(linked, assigned);
-        when(repository.assignRealContainerNo(11L, "MSCU6639870", 3, 9L, "admin")).thenReturn(1);
+        when(repository.assignRealContainerNo(11L, containerNo, 3, 9L, "admin")).thenReturn(1);
 
         ContainerBookingEntity result = service.assignRealContainerNo(
-            11L, " ms cu 663987 0 ", 3, 9L, "admin");
+            11L, " " + containerNo.toLowerCase(java.util.Locale.ROOT) + " ", 3, 9L, "admin");
 
-        assertThat(result.getContainerNo()).isEqualTo("MSCU6639870");
-        verify(repository).assignRealContainerNo(11L, "MSCU6639870", 3, 9L, "admin");
+        assertThat(result.getContainerNo()).isEqualTo(containerNo);
+        verify(repository).assignRealContainerNo(11L, containerNo, 3, 9L, "admin");
     }
 
     @Test
@@ -329,17 +331,21 @@ class ContainerServiceTest {
         verify(repository, never()).assignRealContainerNo(anyLong(), anyString(), anyInt(), anyLong(), anyString());
     }
 
-    @Test
-    @DisplayName("首次关联拒绝错误ISO 6346校验位")
-    void rejectsInvalidContainerNumberCheckDigit() {
+    /** 关联入口允许非 ISO 柜号，继续按原版本和关联范围保存。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    @DisplayName("首次关联不因柜号长度结构或校验位阻断")
+    void linksWithoutIsoContainerNumberValidation(String containerNo) {
         stubLinkContext();
+        when(repository.linkReleasedBooking(eq(11L), eq(21L), eq(31L), eq(containerNo),
+            any(OceanBookingEntity.class), eq(2), eq(9L), eq("admin"))).thenReturn(1);
 
-        assertThatThrownBy(() -> service.linkOceanBooking(11L, 9L, "admin",
-            new OceanBookingLinkRequest(21L, 31L, "MSCU6639871", 2)))
-            .isInstanceOf(BizException.class).hasMessageContaining("校验位");
+        service.linkOceanBooking(11L, 9L, "admin", new OceanBookingLinkRequest(21L, 31L, containerNo, 2));
 
-        verify(repository, never()).linkReleasedBooking(anyLong(), anyLong(), anyLong(), anyString(),
-            any(), anyInt(), anyLong(), anyString());
+        verify(repository).containerNoExists(21L, containerNo, 11L);
+        verify(repository).linkReleasedBooking(eq(11L), eq(21L), eq(31L), eq(containerNo),
+            any(OceanBookingEntity.class), eq(2), eq(9L), eq("admin"));
+        verify(oceanBookings).insert(any(OceanBookingContainerAllocationEntity.class));
     }
 
     @Test

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

@@ -22,6 +22,9 @@ import com.baiyue.firstleg.pricebookquery.application.model.PriceBookQueryRows.R
 import jakarta.annotation.Resource;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+import org.junit.jupiter.params.provider.ValueSource;
 import org.mockito.ArgumentCaptor;
 import org.apache.ibatis.annotations.Select;
 import org.springframework.boot.test.mock.mockito.MockBean;
@@ -223,11 +226,13 @@ class FbaPricingServiceTest {
         verify(financeOutbox, never()).publishInbound(any(), anyLong(), anyLong(), anyLong(), anyInt(), any());
     }
 
-    @Test
-    @DisplayName("待分柜边界确认费用后仍保持主流程状态")
-    void confirmsAtWaitSplitWithoutRollingBackProcessStatus() {
+    /** 待组托、待分柜确认费用均不推进物流主流程。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"WAIT_PALLETIZE", "WAIT_SPLIT"})
+    @DisplayName("待组托或待分柜确认费用后仍保持主流程状态")
+    void confirmsWithoutRollingBackProcessStatus(String processStatus) {
         InboundPricingEntity inbound = inbound("10.000", "1.0000");
-        inbound.setProcessStatus("WAIT_SPLIT");
+        inbound.setProcessStatus(processStatus);
         inbound.setFeeStatus("CALCULATED");
         InboundFeeEntity fee = savedFee("CALCULATED");
         when(repository.findLatestFee(TENANT, INBOUND)).thenReturn(fee);
@@ -244,7 +249,7 @@ class FbaPricingServiceTest {
         FeeSnapshotResponse response = service.confirm(
             TENANT, OPERATOR, INBOUND, "confirm-wait-split");
 
-        assertThat(response.nextProcessStatus()).isEqualTo("WAIT_SPLIT");
+        assertThat(response.nextProcessStatus()).isEqualTo(processStatus);
         verify(repository).markInboundConfirmed(TENANT, INBOUND);
     }
 
@@ -436,11 +441,13 @@ class FbaPricingServiceTest {
         verify(repository, never()).insertFee(any());
     }
 
-    @Test
+    /** 待组托发送费用保留主状态，重复请求不重复生成费用事件。 */
+    @ParameterizedTest
+    @CsvSource({"FEE_CONFIRMING,WAIT_PALLET", "WAIT_PALLETIZE,WAIT_PALLETIZE"})
     @DisplayName("重复发送只返回首次结果且不会重复写Outbox")
-    void sendIsIdempotentAndDoesNotDuplicateOutbox() {
+    void sendIsIdempotentAndDoesNotDuplicateOutbox(String processStatus, String expectedStatus) {
         InboundPricingEntity inbound = inbound("10", "1");
-        inbound.setProcessStatus("FEE_CONFIRMING");
+        inbound.setProcessStatus(processStatus);
         inbound.setFeeStatus("CONFIRMED");
         InboundFeeEntity confirmed = savedFee("CONFIRMED");
         when(repository.findInbound(TENANT, INBOUND)).thenReturn(inbound);
@@ -448,7 +455,7 @@ class FbaPricingServiceTest {
         when(repository.findIdempotency(TENANT, OPERATOR, "FEE_SEND", "send-once"))
             .thenReturn(null, completed("FEE_SEND", 501L));
         when(repository.sendFee(TENANT, 501L, OPERATOR, NOW)).thenReturn(1);
-        when(repository.markInboundFeeSent(TENANT, INBOUND, "FEE_CONFIRMING")).thenReturn(1);
+        when(repository.markInboundFeeSent(TENANT, INBOUND, processStatus)).thenReturn(1);
         when(repository.completeIdempotency(any(), eq(501L), eq(NOW))).thenReturn(1);
         when(repository.findFee(TENANT, 501L)).thenReturn(confirmed);
         InboundFeeItemEntity item = new InboundFeeItemEntity(); item.setUnitPrice(new BigDecimal("2.00"));
@@ -459,8 +466,8 @@ class FbaPricingServiceTest {
         FeeSnapshotResponse first = service.send(TENANT, OPERATOR, INBOUND, "send-once");
         FeeSnapshotResponse repeated = service.send(TENANT, OPERATOR, INBOUND, "send-once");
 
-        assertThat(first.nextProcessStatus()).isEqualTo("WAIT_PALLET");
-        assertThat(repeated.nextProcessStatus()).isEqualTo("WAIT_PALLET");
+        assertThat(first.nextProcessStatus()).isEqualTo(expectedStatus);
+        assertThat(repeated.nextProcessStatus()).isEqualTo(expectedStatus);
         verify(financeOutbox, times(1)).publishInbound(
             eq(FinanceFeeSourceOutboxService.PUBLISHED), eq(TENANT), eq(INBOUND),
             eq(501L), eq(1), eq(NOW));

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

@@ -101,6 +101,23 @@ class LoadingCompletedOutboxServiceTest {
         assertThat(first.eventVersion()).isEqualTo(3);
     }
 
+    /** 非 ISO 柜号能生成当前 V3 事件，并保持冻结柜号原值。 */
+    @org.junit.jupiter.params.ParameterizedTest
+    @org.junit.jupiter.params.provider.ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "LOCAL-2026-001"})
+    void publishesNonIsoContainerNumber(String containerNo) throws Exception {
+        Row value = row(11, 100, 101);
+        value.setContainerNo(containerNo);
+        when(snapshots.rows(90L)).thenReturn(List.of(value));
+
+        service.publish(90L);
+
+        ArgumentCaptor<InboundOutboxEntity> captured = ArgumentCaptor.forClass(InboundOutboxEntity.class);
+        verify(outbox).insert(captured.capture());
+        EventEnvelope event = mapper.readValue(captured.getValue().getPayloadJson(), EventEnvelope.class);
+        assertThat(event.eventVersion()).isEqualTo(3);
+        assertThat(event.payload().path("containerNo").asText()).isEqualTo(containerNo);
+    }
+
     @Test void requiresFrozenPhysicalContainerNumberBeforePublishing() {
         Row value = row(11, 100, 101); value.setContainerNo(" ");
         when(snapshots.rows(90L)).thenReturn(List.of(value));

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

@@ -26,6 +26,9 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.annotation.Resource;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullSource;
+import org.junit.jupiter.params.provider.ValueSource;
 import org.mockito.ArgumentCaptor;
 import org.springframework.boot.test.context.TestConfiguration;
 import org.springframework.boot.test.mock.mockito.MockBean;
@@ -147,10 +150,45 @@ class LoadingListServiceTest {
         verifyNoInteractions(loadingPickService);
     }
 
+    /** 只更新航次时，关联已接受的非 ISO 柜号不应被重新校验或改写。 */
+    @ParameterizedTest
+    @NullSource
+    @ValueSource(strings = {"LOCAL-1", " local-1 "})
+    void preservesLinkedNonIsoNumberWhenOnlyVoyageChanges(String requested) {
+        AggregateRow before = row("EDITING", 3);
+        before.setContainerNo("LOCAL-1");
+        before.setVoyageNo("001E");
+        when(repository.aggregate(10L)).thenReturn(before);
+        when(repository.updateTransport(10L, 3, "LOCAL-1", "023E", 9L, "operator")).thenReturn(1);
+
+        service.updateTransport(10L, 100L, 9L, "operator", "preserve-linked-number",
+            new TransportUpdateRequest(requested, "023E", 3, null));
+
+        verify(repository).updateTransport(10L, 3, "LOCAL-1", "023E", 9L, "operator");
+        verify(loadingPickService).beginIfReady(30L, 9L, "operator");
+    }
+
+    /** 运输纠错与关联入口一致，只规范化柜号并保留纠错原因。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void acceptsNonIsoNumberInTransportCorrection(String containerNo) {
+        AggregateRow before = row("EDITING", 3);
+        before.setContainerNo("LOCAL-1");
+        when(repository.aggregate(10L)).thenReturn(before);
+        when(repository.updateTransport(10L, 3, containerNo, null, 9L, "operator")).thenReturn(1);
+
+        service.updateTransport(10L, 100L, 9L, "operator", "non-iso-correction",
+            new TransportUpdateRequest(" " + containerNo.toLowerCase(java.util.Locale.ROOT) + " ", null, 3, "纠错"));
+
+        verify(repository).updateTransport(10L, 3, containerNo, null, 9L, "operator");
+        verify(loadingPickService).beginIfReady(30L, 9L, "operator");
+    }
+
+    /** 关联入口接受的非 ISO 柜号，在 PDA 领取前仍可按版本和原因纠正为真实柜号。 */
     @Test
     void pushedEditingPreloadCanCorrectExistingContainerNumberBeforePdaClaim() {
         AggregateRow before = row("EDITING", 3);
-        before.setContainerNo("MSCU6639870");
+        before.setContainerNo("LOCAL-1");
         AggregateRow after = row("EDITING", 4);
         after.setContainerNo("CSQU3054383");
         when(repository.aggregate(10L)).thenReturn(before, after);
@@ -200,7 +238,7 @@ class LoadingListServiceTest {
 
         assertThatThrownBy(() -> service.updateTransport(10L, 100L, 9L, "operator", "key-1",
             new TransportUpdateRequest("   ", "023E", 3, "清空测试")))
-            .isInstanceOf(BizException.class).hasMessageContaining("ISO 6346");
+            .isInstanceOf(BizException.class).hasMessageContaining("不能为空");
         verify(repository, never()).updateTransport(eq(10L), eq(3),
             org.mockito.ArgumentMatchers.nullable(String.class),
             org.mockito.ArgumentMatchers.nullable(String.class), eq(9L),

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

@@ -227,7 +227,7 @@ class LoadingPickServiceTest {
         Link link = new Link(1L, 1L, 50L, 2L, "PENDING", 1,
             10L, 40L, "MSCU-001", "EDITING", 3, 2, null);
         var booking = new com.baiyue.firstleg.entity.ContainerBookingEntity();
-        booking.setId(40L); booking.setContainerNo("MSCU-001");
+        booking.setId(40L); booking.setContainerNo("MSCU6639870");
         var allocation = new OceanBookingContainerAllocationEntity();
         allocation.setOceanBookingId(90L);
         var ocean = new OceanBookingEntity();
@@ -962,6 +962,82 @@ class LoadingPickServiceTest {
         verify(repository, never()).acceptCompletion(anyLong(), anyInt());
     }
 
+    /** 关联接受的非 ISO 柜号可直接确认预装，保留订舱放舱门禁。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void acceptsNonIsoNumberBeforeConfirmation(String containerNo) {
+        Link link = new Link(1L, 1L, 50L, 2L, "PENDING", 1,
+            10L, 40L, containerNo, "EDITING", 3, 2, null);
+        var booking = new ContainerBookingEntity();
+        booking.setId(40L);
+        booking.setContainerNo(containerNo);
+        when(loadingModelBridge.requireAllocatedLinksForConfirmation(10L)).thenReturn(List.of(link));
+        when(smartLoadingRepository.booking(40L)).thenReturn(booking);
+
+        var allocation = new OceanBookingContainerAllocationEntity();
+        allocation.setOceanBookingId(90L);
+        var ocean = new OceanBookingEntity();
+        ocean.setId(90L);
+        ocean.setStatus("RELEASED");
+        when(oceanBookingRepository.allocationByContainer(40L)).thenReturn(allocation);
+        when(oceanBookingRepository.find(90L)).thenReturn(ocean);
+        assertThat(service.requirePreloadConfirmationReady(10L)).containsExactly(link);
+    }
+
+    /** 非 ISO 柜号可以创建 PDA 任务，任务仍按柜次关联权威柜号。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void createsPdaTaskWithNonIsoNumber(String containerNo) {
+        var plan = new com.baiyue.firstleg.entity.LoadingPlanEntity();
+        plan.setId(10L); plan.setContainerBookingId(40L);
+        var booking = new ContainerBookingEntity();
+        booking.setId(40L); booking.setContainerNo(containerNo); booking.setCabinetNo("D2092");
+        when(smartLoadingRepository.plan(10L)).thenReturn(plan);
+        when(smartLoadingRepository.booking(40L)).thenReturn(booking);
+        doAnswer(invocation -> {
+            LoadingPickTaskEntity created = invocation.getArgument(0);
+            created.setId(20L);
+            return 1;
+        }).when(repository).insert(any(LoadingPickTaskEntity.class));
+
+        service.begin(10L, containerNo, 9L, "operator", List.of());
+
+        ArgumentCaptor<LoadingPickTaskEntity> captured = ArgumentCaptor.forClass(LoadingPickTaskEntity.class);
+        verify(repository).insert(captured.capture());
+        assertThat(captured.getValue().getContainerBookingId()).isEqualTo(40L);
+        assertThat(captured.getValue().getTaskStatus()).isEqualTo("LOADING");
+    }
+
+    /** 去除 ISO 校验不应放开缺号任务。 */
+    @ParameterizedTest
+    @org.junit.jupiter.params.provider.NullAndEmptySource
+    @ValueSource(strings = {"   ", "\u00a0\u3000"})
+    void rejectsMissingNumberBeforeCreatingPdaTask(String containerNo) {
+        assertThatThrownBy(() -> service.begin(10L, containerNo, 9L, "operator", List.of()))
+            .isInstanceOf(BizException.class).hasMessageContaining("录入真实集装箱号");
+        verify(repository, never()).insert(any(LoadingPickTaskEntity.class));
+    }
+
+    /** 非 ISO 柜号不会在完成阶段再次受阻，仍通过持久化命令结算。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void completionAcceptsNonIsoNumberForCrossServiceFacts(String containerNo) {
+        repository.activeBookingByTask(20L).setContainerNo(containerNo);
+        when(repository.taskForUpdate(20L)).thenReturn(task());
+        LoadingPickTaskEntity completing = task();
+        completing.setTaskStatus("COMPLETING");
+        completing.setVersion(1);
+        when(repository.task(20L)).thenReturn(completing);
+        when(repository.allTaskItemsResolved(20L)).thenReturn(true);
+
+        Task result = service.complete(20L,
+            new CompleteLoadingRequest(0, "complete-non-iso", "checked"), 9L, "operator");
+
+        assertThat(result.taskStatus()).isEqualTo("COMPLETING");
+        verify(completionCommands).insert(any());
+        verify(repository).acceptCompletion(20L, 0);
+    }
+
     @Test
     void differentOperationIdIsRejectedImmediatelyWithConflict() {
         // different operationId is a canonical A0409 CONFLICT while the durable command is active.

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

@@ -36,8 +36,9 @@ class MerchantInboundBillingServiceTest {
     @MockBean private InboundFeeDetailService feeDetails;
     @Resource private MerchantInboundBillingService service;
 
+    /** 测量审核通过并发送费用后，待组托与后续履约阶段均可查看客户费用。 */
     @ParameterizedTest
-    @ValueSource(strings = {"WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"})
+    @ValueSource(strings = {"WAIT_PALLETIZE", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"})
     void shouldKeepPublishedBillingVisibleAfterFulfillmentProgresses(String processStatus) {
         InboundOrderEntity inbound = inbound(processStatus, "APPROVED", "SENT");
         InboundOrderDetail detail = new InboundOrderDetail(mock(com.baiyue.firstleg.dto.InboundOrderSummary.class),
@@ -84,9 +85,11 @@ class MerchantInboundBillingServiceTest {
         verify(orders).findByOrderId(10001L, 77L);
     }
 
-    @Test
-    void shouldHandleCase02() {
-        InboundOrderEntity inbound = inbound("WAIT_SPLIT", "PENDING", "SENT");
+    /** 待组托不绕过客户费用可见性的测量审核条件。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"WAIT_PALLETIZE", "WAIT_SPLIT"})
+    void shouldHandleCase02(String processStatus) {
+        InboundOrderEntity inbound = inbound(processStatus, "PENDING", "SENT");
         when(orders.findByOrderId(10001L, 77L)).thenReturn(inbound);
 
         assertThatThrownBy(() -> service.find(10001L, 77L))
@@ -105,6 +108,19 @@ class MerchantInboundBillingServiceTest {
         verify(pricing, never()).latest(20002L, 88L);
     }
 
+    /** 客户可在组托前确认已审核并发送的费用，继续使用当前费用版本和幂等键。 */
+    @Test
+    void confirmsPublishedFeeWhileWaitingForPalletization() {
+        when(orders.findByOrderId(10001L, 77L)).thenReturn(inbound("WAIT_PALLETIZE", "APPROVED", "SENT"));
+        FeeSnapshotResponse fee = mock(FeeSnapshotResponse.class);
+        when(pricing.confirmByCustomer(10001L, 7L, "客户成员", 88L, 3, "confirm-palletize"))
+            .thenReturn(fee);
+
+        assertThat(service.confirmFee(10001L, 7L, "客户成员", 77L, 3, "confirm-palletize"))
+            .isSameAs(fee);
+        verify(pricing).confirmByCustomer(10001L, 7L, "客户成员", 88L, 3, "confirm-palletize");
+    }
+
     @Test
     void shouldHandleCase04() {
         InboundOrderEntity inbound = inbound("WAIT_SPLIT", "APPROVED", "SENT");

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

@@ -0,0 +1,45 @@
+package com.baiyue.firstleg.service;
+
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.firstleg.controller.InternalFeeCatalogController;
+import com.baiyue.firstleg.entity.FeeItemEntity;
+import com.baiyue.firstleg.repository.FeeItemRepository;
+import org.junit.jupiter.api.Test;
+import java.math.BigDecimal;
+import java.util.List;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+class SharedFeeCatalogServiceTest {
+    /** 已停用、方向变更或非海外项目不能沿用页面旧选项。 */
+    @Test void currentEligibilityIsCheckedBeforeUse() {
+        FeeItemRepository repository = mock(FeeItemRepository.class);
+        SharedFeeCatalogService service = new SharedFeeCatalogService(repository);
+        FeeItemEntity item = new FeeItemEntity();
+        item.setFeeCode("FEE-1"); item.setFeeTypeName("操作费");
+        item.setStatus("ACTIVE"); item.setTradeScope("INTERNATIONAL");
+        item.setWarehouseReceivable(true); item.setDefaultPrice(new BigDecimal("2.50"));
+        when(repository.findItemByCode("FEE-1")).thenReturn(item);
+        when(repository.listActiveInternationalWarehouseItems("RECEIVABLE")).thenReturn(List.of(item));
+        assertEquals(new BigDecimal("2.50"), service.list("RECEIVABLE").get(0).defaultPrice());
+        assertEquals("操作费", service.requireActive("FEE-1", "RECEIVABLE").name());
+        assertThrows(BizException.class, () -> service.requireActive("FEE-1", "PAYABLE"));
+        item.setStatus("INACTIVE");
+        assertThrows(BizException.class, () -> service.requireActive("FEE-1", "RECEIVABLE"));
+        item.setStatus("ACTIVE"); item.setTradeScope("DOMESTIC");
+        assertThrows(BizException.class, () -> service.requireActive("FEE-1", "RECEIVABLE"));
+        assertThrows(BizException.class, () -> service.list(null));
+    }
+
+    /** 内部入口未配置、缺少或错误凭证均不得读取目录。 */
+    @Test void internalCatalogRequiresExplicitServiceIdentity() {
+        SharedFeeCatalogService service = mock(SharedFeeCatalogService.class);
+        InternalFeeCatalogController controller = new InternalFeeCatalogController(service, "configured-token");
+        assertThrows(BizException.class, () -> controller.list(null, "RECEIVABLE"));
+        assertThrows(BizException.class, () -> controller.detail("wrong", "FEE-1", "RECEIVABLE"));
+        assertThrows(BizException.class, () -> new InternalFeeCatalogController(service, "").list("", "RECEIVABLE"));
+        verifyNoInteractions(service);
+        when(service.list("RECEIVABLE")).thenReturn(List.of());
+        assertTrue(controller.list("configured-token", "RECEIVABLE").successful());
+    }
+}

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

@@ -84,7 +84,7 @@ class TruckAppointmentServiceTest {
     }
 
     @Test void createCandidatesDelegateOneBoundedAuthoritativeQuery() {
-        Candidate candidate = new Candidate(99L, "OB-1", "BL-1", 18L, "义乌仓", "SEA-US", "美西", true);
+        Candidate candidate = new Candidate(99L, "OB-1", "BL-1", 18L, "义乌仓", "SEA-US", "美西");
         when(repository.candidates(any())).thenReturn(new PageResult<>(List.of(candidate), 1, 20, 1, 1));
 
         PageResult<Candidate> result = service.candidates(new CandidateQuery(" OB-1 ", 1, 20));
@@ -170,7 +170,8 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).insert(any());
     }
 
-    @Test void createFreezesBookingBillAndRequiresBookingOwnedDocument() {
+    /** 无附件订舱可创建预约，提单号仍取订舱冻结值。 */
+    @Test void createFreezesBookingBillWithoutRequiringBookingDocument() {
         SaveRequest request = validRequest();
 
         service.create(7L, "admin", request);
@@ -178,7 +179,7 @@ class TruckAppointmentServiceTest {
         ArgumentCaptor<TruckAppointmentEntity> entity = ArgumentCaptor.forClass(TruckAppointmentEntity.class);
         verify(repository).insert(entity.capture());
         assertThat(entity.getValue().getBillOfLadingNo()).isEqualTo("BL-BOOKING-1");
-        verify(oceanBookingDocuments).requireActiveValidDocument(any(OceanBookingEntity.class));
+        verifyNoInteractions(oceanBookingDocuments);
         verifyNoInteractions(files);
     }
 
@@ -307,14 +308,14 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).insert(any());
     }
 
-    @Test void createStillRequiresBookingDocumentWithoutAnyContainerAssociation() {
+    /** 没有附件或货柜关联时，完整已放舱订舱仍可预约。 */
+    @Test void createAllowsBookingWithoutDocumentsOrContainerAssociation() {
         SaveRequest request = validRequest();
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
-            "订舱缺少有效订舱确认或提单文件"))
-            .when(oceanBookingDocuments).requireActiveValidDocument(any());
-        assertThatThrownBy(() -> service.create(7L, "admin", request))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
-        verify(repository, never()).insert(any());
+        TruckAppointmentEntity result = service.create(7L, "admin", request);
+        assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.DRAFT);
+        assertThat(result.getContainerBookingId()).isNull();
+        verify(repository).insert(any());
+        verifyNoInteractions(oceanBookingDocuments);
     }
 
     @Test void editCanSwitchToAnotherUnoccupiedReleasedBooking() {
@@ -407,7 +408,8 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).history(any());
     }
 
-    @Test void dispatchRequiresBookingBillAndActiveBookingOwnedDocument() {
+    /** 取消附件要求后，派车仍必须具备提单号。 */
+    @Test void dispatchRequiresBookingBill() {
         TruckAppointmentEntity missingBill = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
         missingBill.setOceanBookingId(99L); missingBill.setContainerBookingId(88L);
         OceanBookingEntity bookingWithoutBill = releasedBooking(); bookingWithoutBill.setBillOfLadingNo(null);
@@ -419,21 +421,11 @@ class TruckAppointmentServiceTest {
             "dispatch-no-bill", null, 7L, "admin"))
             .isInstanceOf(BizException.class).hasMessageContaining("提单号");
 
-        TruckAppointmentEntity missingAttachment = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
-        missingAttachment.setOceanBookingId(99L); missingAttachment.setContainerBookingId(88L); missingAttachment.setBillOfLadingNo("BL-BOOKING-1");
-        when(oceanBookings.find(99L)).thenReturn(releasedBooking());
-        when(repository.claimOperation(anyLong(), eq(1L), eq("DISPATCH"), eq("dispatch-no-file"), anyString())).thenReturn(true);
-        when(repository.find(1L)).thenReturn(missingAttachment);
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,"订舱缺少有效订舱确认或提单文件"))
-            .when(oceanBookingDocuments).requireActiveValidDocument(any());
-
-        assertThatThrownBy(() -> service.action(1L, "DISPATCH", new ActionRequest(1, null),
-            "dispatch-no-file", null, 7L, "admin"))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
         verify(repository, never()).dispatch(anyLong(), anyString(), anyString(), anyInt());
     }
 
-    @Test void dispatchFreezesReleasedBookingBillWithoutRequiringRealContainerNumber() {
+    /** 无附件、无真实柜号时可派车，但仍冻结已放舱订舱的提单号并记历史。 */
+    @Test void dispatchFreezesReleasedBookingBillWithoutRequiringDocumentsOrRealContainerNumber() {
         TruckAppointmentEntity before = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
         before.setOceanBookingId(99L); before.setContainerBookingId(88L); before.setBillOfLadingNo(null);
         TruckAppointmentEntity after = entity(TruckAppointmentStatus.DISPATCHED, 2);
@@ -452,6 +444,7 @@ class TruckAppointmentServiceTest {
         assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.DISPATCHED);
         assertThat(result.getBillOfLadingNo()).isEqualTo("BL-BOOKING-1");
         verify(repository).dispatch(1L, "PENDING_DISPATCH", "BL-BOOKING-1", 1);
+        verifyNoInteractions(oceanBookingDocuments);
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt());
         verify(repository).history(any(TruckAppointmentHistoryEntity.class));
     }

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

@@ -11,6 +11,41 @@ import java.time.LocalDateTime;
 import static org.junit.jupiter.api.Assertions.*;
 
 class ContainerCalendarSourceMapperTest {
+    /** 两个日历来源入口均优先展示港口名称，仅填代码时仍可回显，缺失时保持空值。 */
+    @Test
+    void displaysDestinationNameOrSavedCodeAcrossBothEntrypoints() throws Exception {
+        var ds = new JdbcDataSource();
+        ds.setURL("jdbc:h2:mem:calendar-port-display;MODE=MySQL;DB_CLOSE_DELAY=-1");
+        try (var connection = ds.getConnection(); var sql = connection.createStatement()) {
+            sql.execute("CREATE TABLE fl_container_booking(id BIGINT,cabinet_no VARCHAR,container_no VARCHAR," +
+                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_port_code VARCHAR,destination_warehouse_code VARCHAR," +
+                "actual_port_arrival_at TIMESTAMP,estimated_port_arrival_at TIMESTAMP,unloading_completed_at TIMESTAMP,record_status VARCHAR)");
+            sql.execute("CREATE TABLE fl_terminal_drayage(container_booking_id BIGINT,actual_empty_return_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_carrier_schedule_node_fact(id BIGINT,container_booking_id BIGINT,standard_node VARCHAR,actual_at TIMESTAMP,observed_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_direct_delivery_unloading(container_booking_id BIGINT,actual_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_outbound_dispatch(container_booking_id BIGINT,confirmed_at TIMESTAMP,reversed_at TIMESTAMP,status VARCHAR)");
+            sql.execute("INSERT INTO fl_container_booking(id,destination_port_name,destination_port_code,record_status) VALUES " +
+                "(1,'洛杉矶','USLAX','ACTIVE'),(2,NULL,'USLAX','ACTIVE'),(3,'   ','USLAX','ACTIVE')," +
+                "(4,'洛杉矶',NULL,'ACTIVE'),(5,'','   ','ACTIVE')");
+            sql.execute("INSERT INTO fl_outbound_dispatch SELECT id,'2026-10-01 00:00:00',NULL,'WAITING_FOR_LOADING' FROM fl_container_booking");
+        }
+        var config = new MybatisConfiguration();
+        config.setEnvironment(new Environment("test", new JdbcTransactionFactory(), ds));
+        config.addMapper(ContainerCalendarSourceMapper.class);
+        try (var session = new MybatisSqlSessionFactoryBuilder().build(config).openSession()) {
+            var mapper = session.getMapper(ContainerCalendarSourceMapper.class);
+            var from = LocalDateTime.parse("2026-10-01T00:00:00");
+            var calendar = mapper.sources(from, from.minusDays(2), from.minusDays(4), from.plusMonths(1));
+            var explicit = mapper.byIds(java.util.List.of(1L, 2L, 3L, 4L, 5L));
+            var expected = java.util.Arrays.asList("洛杉矶", "USLAX", "USLAX", "洛杉矶", null);
+            assertEquals(expected, calendar.stream().map(row -> row.destinationPortName()).toList());
+            for (var row : explicit) {
+                assertEquals(expected.get(row.containerBookingId().intValue() - 1), row.destinationPortName());
+            }
+            assertEquals(5, explicit.size());
+        }
+    }
+
     /** 后续观测可将实际到港修正为更早日期，两入口须取同一条最新实际记录。 */
     @Test
     void usesLatestObservedArrivalIncludingSameObservationIdTieBreakAcrossBothEntrypoints() throws Exception {
@@ -18,7 +53,7 @@ class ContainerCalendarSourceMapperTest {
         ds.setURL("jdbc:h2:mem:arrival-source-correction;MODE=MySQL;DB_CLOSE_DELAY=-1");
         try (var connection = ds.getConnection(); var sql = connection.createStatement()) {
             sql.execute("CREATE TABLE fl_container_booking(id BIGINT PRIMARY KEY,cabinet_no VARCHAR,container_no VARCHAR," +
-                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_warehouse_code VARCHAR," +
+                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_port_code VARCHAR,destination_warehouse_code VARCHAR," +
                 "actual_port_arrival_at TIMESTAMP,estimated_port_arrival_at TIMESTAMP,unloading_completed_at TIMESTAMP,record_status VARCHAR)");
             sql.execute("CREATE TABLE fl_terminal_drayage(container_booking_id BIGINT,actual_empty_return_at TIMESTAMP)");
             sql.execute("CREATE TABLE fl_carrier_schedule_query(id BIGINT,version INT,status VARCHAR)");
@@ -65,7 +100,7 @@ class ContainerCalendarSourceMapperTest {
         ds.setURL("jdbc:h2:mem:four-type-calendar;MODE=MySQL;DB_CLOSE_DELAY=-1");
         try (var connection = ds.getConnection(); var sql = connection.createStatement()) {
             sql.execute("CREATE TABLE fl_container_booking(id BIGINT,cabinet_no VARCHAR,container_no VARCHAR," +
-                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_warehouse_code VARCHAR," +
+                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_port_code VARCHAR,destination_warehouse_code VARCHAR," +
                 "actual_port_arrival_at TIMESTAMP,estimated_port_arrival_at TIMESTAMP,unloading_completed_at TIMESTAMP,record_status VARCHAR)");
             sql.execute("CREATE TABLE fl_terminal_drayage(container_booking_id BIGINT,actual_empty_return_at TIMESTAMP)");
             sql.execute("CREATE TABLE fl_carrier_schedule_node_fact(id BIGINT,container_booking_id BIGINT,standard_node VARCHAR,actual_at TIMESTAMP,observed_at TIMESTAMP)");

iam/src/main/resources/db/overseas-fee-permissions.sql

@@ -0,0 +1,50 @@
+-- 海外费用查询菜单；编辑与审核沿用独立财务按钮权限，只读授权不包含写操作。
+USE baiyue_iam;
+SET NAMES utf8mb4;
+DROP PROCEDURE IF EXISTS check_overseas_fee_permission_identity;
+DELIMITER $$
+CREATE PROCEDURE check_overseas_fee_permission_identity()
+BEGIN
+  -- 先恢复既有财务写按钮和管理员授权，再部署菜单；列表权限不代表可创建或审核。
+  -- 缺失时先执行 deploy/sql/overseas-fee-canonical-write-permissions-repair.sql。
+  IF (SELECT COUNT(*) FROM iam_role WHERE id=4000001 AND tenant_id=0 AND app_code='PLATFORM'
+      AND role_code='PLATFORM_ADMIN' AND role_type='SYSTEM' AND status='ACTIVE' AND deleted=0)<>1
+      OR EXISTS(SELECT 1 FROM iam_role WHERE role_code='PLATFORM_ADMIN' AND id<>4000001)
+      OR (SELECT COUNT(*) FROM iam_permission p JOIN iam_role_permission rp ON rp.permission_id=p.id
+          WHERE rp.role_id=4000001 AND rp.tenant_id=0 AND p.tenant_id=0 AND p.app_code='PLATFORM'
+          AND p.permission_type='BUTTON' AND p.status='ACTIVE' AND p.deleted=0
+          AND ((p.id=5105024 AND p.permission_code='platform:finance:fee-source:review')
+            OR (p.id=5105025 AND p.permission_code='platform:finance:fee-source:edit')))<>2 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Run overseas-fee-canonical-write-permissions-repair.sql first; fee write grants missing';
+  END IF;
+  IF EXISTS(SELECT 1 FROM iam_permission WHERE
+      (id=5117200 AND (permission_code<>'platform:overseas-fee:list' OR tenant_id<>0 OR app_code<>'PLATFORM' OR permission_type<>'MENU'))
+      OR (permission_code='platform:overseas-fee:list' AND (id<>5117200 OR tenant_id<>0 OR app_code<>'PLATFORM'))) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Overseas fee permission identity conflict';
+  END IF;
+END$$
+DELIMITER ;
+CALL check_overseas_fee_permission_identity();
+DROP PROCEDURE check_overseas_fee_permission_identity;
+
+START TRANSACTION;
+INSERT INTO iam_permission
+  (id,tenant_id,app_code,permission_type,parent_id,permission_code,permission_name,route_path,http_method,sort_no,status,built_in,deleted)
+VALUES (5117200,0,'PLATFORM','MENU',0,'platform:overseas-fee:list','海外费用管理','/overseas-business/fees','GET',890,'ACTIVE',1,0)
+ON DUPLICATE KEY UPDATE permission_name=VALUES(permission_name),route_path=VALUES(route_path),parent_id=0,status='ACTIVE',deleted=0;
+
+INSERT IGNORE INTO iam_role_permission(tenant_id,role_id,permission_id,created_at)
+SELECT 0,r.id,5117200,CURRENT_TIMESTAMP(3) FROM iam_role r
+WHERE r.tenant_id=0 AND r.app_code='PLATFORM' AND r.role_code='PLATFORM_ADMIN' AND r.status='ACTIVE' AND r.deleted=0;
+
+-- 默认管理员获得菜单后，同事务推进授权版本，已有会话及时读取新权限。
+INSERT INTO iam_security_subject_version(auth_user_id,permission_version)
+SELECT DISTINCT u.auth_user_id,1 FROM iam_user u
+JOIN iam_membership m ON m.user_id=u.id
+JOIN iam_membership_role mr ON mr.membership_id=m.id AND mr.tenant_id=m.tenant_id
+JOIN iam_role r ON r.id=mr.role_id
+WHERE u.auth_user_id IS NOT NULL AND u.status='ACTIVE' AND u.deleted=0
+  AND m.status='ACTIVE' AND m.deleted=0 AND r.tenant_id=0 AND r.app_code='PLATFORM'
+  AND r.role_code='PLATFORM_ADMIN' AND r.status='ACTIVE' AND r.deleted=0
+ON DUPLICATE KEY UPDATE permission_version=permission_version+1;
+COMMIT;

lastleg-service/AGENTS.md

@@ -56,7 +56,7 @@
 | 贴标申请、箱唛/SKU/组合换标与 PDA 完工 | `relabel/` |
 | PDA 仓内通用扫码与操作历史 | `pda/warehouse/controller/PdaWarehouseController.java` |
 | 船节点接收与海外 PDA 可收货门禁 | `shipping/service/ContainerShippingNodeConsumer.java` |
-| 内部散板需求只读来源 | `dispatch/service/DispatchCapacityDemandService.java`、`DispatchQueryController.java`的`/dispatches/capacity-demands`；默认发布字段随原排车创建/编辑保存，当前业务口径见拼车主契约，不恢复旧车次人工发布入口 |
+| 内部散板需求只读来源 | `dispatch/service/DispatchCapacityDemandService.java`、`DispatchQueryController.java`的`/dispatches/capacity-demands`；发布字段仅随智能排车创建保存且缺省不发布，编辑命令不接收该字段；重发须按原门禁取消排车再重新创建，当前业务口径见拼车主契约，不恢复旧车次人工发布入口 |
 | 平台排车查询、整车四块详情、审核与实载 | `dispatch/controller/DispatchQueryController.java`、`DispatchAggregateController.java`；公开契约`dispatch/port/`，业务规则见`../../docs/海外仓业务/排车列表统一作业改造契约.md` |
 | 草稿、双端装车发运 | `dispatch/controller/SmartDispatchController.java`、`dispatch/pda/controller/DispatchPdaController.java`；平台维护`DispatchController.java`；自动发运编排`dispatch/service/DispatchLoadingDepartureService.java` |
 | 仓储资源调用 | `inboundplan/pda/gateway/WarehouseResourceGateway.java` |

lastleg-service/docs/business-index.md

@@ -7,8 +7,8 @@
 退货预报、签收、库存、合箱与退货出库：
 
 - 客户预报 `returnreceipt/controller/MerchantReturnOrderController.java` → `returnreceipt/service/ReturnReceiptService.java`，路径 `/api/merchant/v1/last-leg/return-orders`；客户范围取认证身份，预报按 SKU 保存期望数量。状态 `PENDING_RECEIPT → PARTIALLY_RECEIVED → COMPLETED` 表示签收进度，不等于换标或出库完成。
-- PDA 后端签收 `returnreceipt/controller/PdaReturnReceiptController.java`，前缀 `/api/pda/v1/last-leg/return-receipts`，依次 `start/sku-candidates/confirm`；按冻结仓和退货单校验实收，不允许未预报 SKU 或超量，幂等重放不得重复入账。确认同时生成签收箱与 SKU 库存；设备页面是否接通另查 PDA 工作台，不能以 Controller 存在代替前端接入。
-- 库存/箱号 `returnreceipt/controller/PlatformReturnInventoryController.java`、`MerchantReturnInventoryController.java` → `returnreceipt/service/ReturnInventoryService.java`，前缀分别为 `/api/platform/v1/last-leg/return-inventory`、`/api/merchant/v1/last-leg/return-inventory`；PDA 合箱入口 `PdaReturnInventoryController.java` 的 `/packing/orders`、`/cartons/merge`、`/cartons/{cartonMark}/label`。同仓同客户选取退货单及可用 SKU，合箱扣减来源箱数量并生成目标箱，空来源箱标为 `MERGED`，不得跨客户或超出可用量。
+- PDA 后端签收 `returnreceipt/controller/PdaReturnReceiptController.java`，前缀 `/api/pda/v1/last-leg/return-receipts`，依次 `start/sku-candidates/confirm`；按冻结仓和退货单校验实收，不允许未预报 SKU 或超量。确认必须传提交前全单累计实收量 `expectedReceivedQuantity`，在订单锁内校验；响应丢失后换新键重复提交旧快照返回冲突，刷新后重新操作，同键幂等请求不得重复入账。确认同时生成签收箱与 SKU 库存；设备页面是否接通另查 PDA 工作台，不能以 Controller 存在代替前端接入。
+- 库存/箱号 `returnreceipt/controller/PlatformReturnInventoryController.java`、`MerchantReturnInventoryController.java` → `returnreceipt/service/ReturnInventoryService.java`，前缀分别为 `/api/platform/v1/last-leg/return-inventory`、`/api/merchant/v1/last-leg/return-inventory`；PDA 合箱入口 `PdaReturnInventoryController.java` 的 `/packing/orders`、`/cartons/merge`、`/cartons/{cartonMark}/label`。同仓同客户选取退货单及可用 SKU，合箱扣减来源箱数量并生成目标箱，空来源箱标为 `MERGED`，不得跨客户或超出可用量。实物合箱 `/cartons/merge-boxes` 必须提交扫码时全部来源箱 SKU 数量 `expectedSourceQuantities`，来源行锁内核对完整快照；旧快照换新键也拒绝扣减，重新扫描后才能提交当前实物。内部退货换标调用从已锁定任务及来源库存生成快照。
 - 退货出库继续进入 `delivery/service/DeliveryTransferService.java` 的 `RETURN_OUTBOUND`，按退货库存可用箱唛创建与拣货；不能与 `exceptionorder/` 的派送退回恢复库存混用。契约见 `src/main/resources/openapi/overseas-business-v1.yaml`，表入口 `src/main/resources/db/lastleg.sql` 的 `ll_return_*`。
 - 客户箱号管理使用 `GET /api/merchant/v1/last-leg/return-inventory/cartons` 按实物箱分页，库存箱内 SKU 明细仍使用根查询；两者均按登录客户精确隔离。合箱 `sourceBatchNo/sourceReturnNo` 保存实际消耗来源的去重业务编号（多个以逗号分隔），不得写状态或包含未取货订单。`ReturnCartonBarcode` 按箱号生成 Code 128 SVG，打印内容不得使用内部客户/仓库 ID。
 
@@ -36,6 +36,7 @@
 | 托盘分配算法 | `inboundplan/service/PalletAllocator.java` |
 | FBA 预约创建、详情与编辑 | `InboundPlanController.java` 的 `/fba-appointments/**`、`inboundplan/service/InboundFbaAppointmentService.java`、`BatchFbaAppointmentRequest.java`、`UpdateFbaAppointmentRequest.java` |
 | PDA 入仓、实收、上架与完成 | `inboundplan/pda/controller/ReceivingContainerController.java`、`inboundplan/pda/service/ReceivingContainerService.java`、内部编排 `InboundPdaWorkflowService.java`；公网入口固定为 `/api/pda/v1/last-leg/receiving-containers/**`，`/warehouse-profile` 只按 Token 绑定仓解析共享仓库中文名称与编码，旧 planNo/allocationId Controller 已移除。多计划同柜返回计划级 `assigned/mergeAllowed/urgent/mergeHint`；普通 FBA/OVERSEAS 分别使用 bulk/carton 收货，一件代发只允许 `/current/receipts/pallet` 按国内冻结来源托盘整托收货。合托只作现场可选提示；全部计划完整绑定真实 pallet/location/lock 前不得查看、准备或签收该柜，首扫只确认已预留绑定，不得重新分配计划资源 |
+| FBA收货短少确认 | `inboundplan/controller/InboundPlanController.java` 的 `/{planNo}/confirm-shortage` → `InboundPdaWorkflowService.confirmShortage`；仅平台入库编辑权限指定客户操作，要求待差异核对、原版本及应收/实收快照、原因和幂等键。仅同柜次同目的仓收货组单票且冻结申报单SKU可按总数确认，多SKU及跨票自动分摊拒绝；逐SKU实收不得超原申报，确认后保留应收与现场结束时间，按实收生成库存和原计租批次，计划/PDA任务进入 `PARTIAL_INBOUND`，尾程订单完成入库；同事务交接原预排，明确零实收的托盘同步移除预排明细、释放本车占用及预约分配并重算整车货量；缺少零实收证据或已有拣货拒绝。不重复发布卸柜事件。无实收、超收或逐SKU事实不一致拒绝；空预留托盘不能再次作为计划货源排车。 |
 | PDA 卸柜照片上传、归属校验与预览 | `ReceivingContainerController.java` 的 `/current/unload-photos/files`、`/current/unload-photos/files/{fileId}/download`，网关 `inboundplan/pda/gateway/UnloadPhotoFileGateway.java`、`HttpUnloadPhotoFileGateway.java`；File 类型固定 `OVERSEAS_UNLOAD_PHOTO`，下载只允许当前会话已签收的 fileId 并返回 `no-store` |
 | PDA 国内装柜照片对照 | `ReceivingContainerController.java` 的 `/current/domestic-loading-photos/{evidenceType}/content`、`ContainerLoadingEvidenceMapper.java`、`DomesticLoadingEvidenceGateway.java`；元数据按物理柜投影，不保存客户，下载必须经当前 PDA 会话鉴权并复用 `FILE_SERVICE_URL` 只读访问 File 服务，单图不可用不改变拆柜状态 |
 | 卸柜照片与海外卸柜完成 Outbox | `ReceivingContainerController.java`、`ReceivingContainerService.java`、`inboundplan/pda/service/InboundUnloadCompletedOutboxService.java`、`entity/LastlegEventOutbox.java`、`mapper/LastlegEventOutboxMapper.java`；多计划同柜只能在全柜完成后调用 `publishContainerCompleted`，按来源柜预订 ID 幂等发布一次，完成时刻与拍照时刻分离；事件模型见 `../common-event-contract/AGENTS.md` |
@@ -57,8 +58,9 @@
 | 派送三类资料、摘要与历史证据 | `delivery/controller/DeliveryDocumentController.java`、`delivery/service/DeliveryDocumentService.java`、`delivery/gateway/DeliveryDocumentFileGateway.java`、`src/main/resources/openapi/delivery-documents-v1.yaml`；固定装车照片 `LOADING_PHOTO`、BOL文件（含签名）`BOL`、签收文件（POD签收/快递签收）`RECEIPT`，按已保存类别计数 `x/3`。每类0至20文件，文件精确绑定客户、按目的FBA仓拆分的派送单和类别；全量保存共用派送版本并记录不可变历史，替换删除仅解绑，未保存上传不计数、不授权下载。`RECEIPT` 成功保存进权威快照时事务内自动完成当前派送单，单纯上传不触发完成 |
 | 异常订单与派送退回入仓 | `exceptionorder/controller/ExceptionOrderController.java`、`exceptionorder/service/ExceptionOrderService.java`、`exceptionorder/gateway/ExceptionEvidenceFileGateway.java`、`inventory/command/service/InventoryCommandService.java`；证据固定按客户、异常单 ID 和 `OVERSEAS_EXCEPTION_EVIDENCE` 校验。退回候选按原出库拣货事实冻结，不接受自由 SKU 或数量；异常按 `PENDING→PROCESSING→COMPLETED`（待处理可取消）、版本与幂等键流转。退回海外仓须把实收按原出库来源恢复到服务端校验的真实托盘/库位并写 `RETURN_STOCK_IN` 流水，库存恢复、异常完成与派送 `RETURNED` 在同一事务完成 |
 | 海外采购、客户下单、采购审核、客户/采购仓候选与操作流水 | `procurement/controller/`、`procurement/service/OverseasProcurementService.java`；客户入口按 `merchant:cross-border:procurement:list/create` 拆分且只取 Token 客户范围；OpenAPI `src/main/resources/openapi/overseas-business-v1.yaml` |
-| 海外业务资金指令与结果 | `wallet/WalletCommandOutboxService.java`、`WalletCommandCompletedConsumer.java`、`WalletResultHandler.java`；采购和换标通过 `WALLET_COMMAND_REQUESTED` 请求国内 Finance 冻结、结算或释放，并以 `WALLET_COMMAND_COMPLETED` 幂等回写业务资金状态；不得跨区同步调用 Finance 钱包或在 Lastleg 自建余额账本 |
-| 海外业务费用来源 | `financefee/controller/PlatformOverseasFeeSourceController.java`、`financefee/service/OverseasFeeSourceService.java`、`OverseasFeeBusinessGuard.java`、`OverseasFeeOutboxService.java`、`OverseasFeeOutboxRelay.java`；海外入仓、采购、美国卡车、本土散板和海外仓服务费必须匹配当前客户的真实业务，入仓记录和入仓码按事实选填；当前 V1 审核通过、调整或作废后以版本化完整快照经 Outbox/Event Bridge 进入独立 Finance，OpenAPI `src/main/resources/openapi/overseas-finance-fees-v1.yaml`。阶段 0A—0E 开发目标另读 `../../docs/财务管理/海外仓费用统一接入阶段0技术契约.md`，收费身份、候选版本、Finance 结果事件与资金计划 V2 尚须以实际代码落地验证，不能因文档存在宣称已实现 |
+| 海外业务资金指令与结果 | `wallet/WalletCommandOutboxService.java`、`WalletCommandCompletedConsumer.java`、`WalletResultHandler.java`；采购、换标、人工海外费用和仓租通过 `WALLET_COMMAND_REQUESTED` 请求 Finance 冻结、结算或释放，并以 `WALLET_COMMAND_COMPLETED` 幂等回写业务资金状态；不得同步调用 Finance 钱包或在 Lastleg 自建余额账本 |
+| 海外业务费用来源 | `financefee/controller/PlatformOverseasFeeSourceController.java`、`financefee/service/OverseasManualFeeService.java`、`OverseasFeeSourceService.java`、`OverseasFeeBusinessGuard.java`、`OverseasFeeOutboxService.java`；费用必须匹配当前客户的真实服务单，公共费用目录通过 Firstleg 内部接口读取。头程附加费审核后进入账单；海外人工应收创建先冻结、审核后扣款，驳回或取消释放，扣款成功后仅登记本地已收来源，不再推送财务账单；采购、换标原业务收费仍按其独立资金身份处理。头程账单费用及供应商应付经直接 Outbox 投递 Finance，余额应收仅通过资金指令取得扣款回执，OpenAPI `src/main/resources/openapi/overseas-finance-fees-v1.yaml`。新菜单列表权限与财务编辑、审核按钮权限分离；本地检查不能代替真实资金、账单联调 |
+| 自动仓租及出库资金门禁 | `storagerent/`；实际 PDA 收货建立原计租批次，头程自有海外仓目的地与仓储转运用中转阶梯，退货用原托阶梯；每24小时进一天，部分出库只承担原批次份额，余货不重置库龄。实际出库命令前单独提交资金预校验，冻结成功后才允许扣库存，按真实出库部分生成待审核仓租，订单费用与海外费用管理展示实际入库、出库、原计算额及实扣额；审核前可调价且说明必填，批准后沿原冻结按实额结算，驳回释放冻结；全部仓租使用余额及授信。客户仓租配置优先，无配置按报价表默认，内部查询失败不得回退。预占保存配置版本、完整阶梯、USD/CNY 原币及结算汇率快照，实际扣款不读最新价格。发布及真实验收清单见 `docs/overseas-fees-storage-rent-release.md` |
 | 美国/本土卡车订单 | `trucking/controller/PlatformUsTruckOrderController.java`、`MerchantUsTruckOrderController.java` 及同子域 Service/DTO；客户入口按 `merchant:cross-border:domestic-trucking:list/create/edit` 拆分 |
 | 本土散板订单 | `looseboard/controller/PlatformLocalLooseboardController.java`、`MerchantLocalLooseboardController.java` 及同子域 Service/DTO/Entity/Mapper；客户入口按 `merchant:cross-border:pallet-shipping:list/create/edit` 拆分；OpenAPI `src/main/resources/openapi/overseas-business-v1.yaml` |
 | 海外仓报价、月度汇率、车辆主数据 | 报价 `masterdata/quote/`、汇率 `masterdata/exchange/`；车辆入口 `masterdata/vehicle/adapter/in/web/PlatformVehicleController.java`，应用服务 `application/VehicleApplicationService.java`，持久化端口与适配器 `application/port/out/VehicleRepository.java`、`adapter/out/persistence/`；OpenAPI `src/main/resources/openapi/overseas-master-data-v1.yaml`，车辆档案不含派送履约历史 |
@@ -86,7 +88,7 @@
 - 车次成本：`fleet/trip/FleetTripCostService.java`、`fleet-trip-costs-v1.yaml`；按DEPART实测及外接实收分摊，不产生客户账单/付款。
 - 报价/统计：`fleet/quote/`、`fleet/reporting/`，合同`fleet-quotes-v1.yaml`、`fleet-operations-v1.yaml`；实测凭证按车次归属，仅当前/历史版本引用可下载。
 - 自有业务运营：`fleet/ownedbusiness/`、`fleet-owned-business-v1.yaml`，共同规则见`../../../docs/海外仓业务/自有业务首版开发契约.md`；原排车装车后三阶段按无实际拼车货物展示，车辆归属独立，仅补金额、逐目的地到达、里程、油耗与照片。原详情只经`dispatch.port.DispatchDetailReader`读取，原装车事务经`OwnedBusinessOwnershipCapture`捕获归属，不另建履约流程。
-- 外配业务运营：`fleet/outsourcedbusiness/`、`fleet-outsourced-business-v1.yaml`，共同规则见`../../../docs/海外仓业务/外配业务首版开发契约.md`；原排车装车后三阶段按实际接入需求池拼车货物展示，车辆归属独立，包含MASTER/EXTERNAL两种资源模式。只登记整车承运金额、逐目的仓到达和五装车照片，无里程/油耗或成本拆分。内部可信作用域复用四表，入口权限与自有严格分开，不引入第二履约模型。
+- 外配业务运营：`fleet/outsourcedbusiness/`、`fleet-outsourced-business-v1.yaml`，共同规则见`../../../docs/海外仓业务/外配业务首版开发契约.md`；原排车装车后三阶段按实际接入需求池拼车货物展示，车辆归属独立，包含MASTER/EXTERNAL两种资源模式。只登记整车承运金额、逐目的仓到达和五类装车照片（每类最多5张），无里程/油耗或成本拆分。内部可信作用域复用四表，入口权限与自有严格分开，不引入第二履约模型。
 - 外接选价合同：`fleet-quote-candidates-v1.yaml`、`fleet-trips-v1.yaml`；来源快照与成交价分开，确认承运复验。
 - 在途交接：`fleet/exception/`、`fleet-handovers-v1.yaml`；后台确认交接，旧资源分别结束任务，DEPART不重写。
 
@@ -161,3 +163,11 @@
 - 事件契约变化同时检查 `common-event-contract`、直接生产者/消费者、Outbox/Inbox 和 DeliveryAck 的 eventId/payloadHash；按 `../../docs/统一认证与服务通信契约.md` 的逐事件表验证，不引入旧 Payload 兼容。
 - 定向验证：从后端根执行 `mvn -pl lastleg-service -am test`。
 - 事件链路变更至少覆盖重复事件、相同来源入仓单、事务回滚、并发单号、内部令牌和租户越权测试。
+
+- 2026-10-26 装车资料：五类依次为司机驾驶证、车牌照片、装车完成、封车照片、BOL司机签字；既有技术槽位与文件归属保持。每类1至5张，未传 `replaceFileId` 追加，指定当前同类文件ID则精确替换；油耗仍单张替换。五类至少各一张且装车确认后才自动派送，同类多张不能充当其他类别，附加行版本/幂等/历史及当前文件下载授权共同保留。无需新增数据库字段，PDA、Admin、Lastleg需配套发布。
+
+### 海外人工收费首版切换
+
+- 除仓租外，换标报价、外接约定运费、拆柜打托成本仅保留业务依据，不再自动生成客户应收。旧派送应收参数须改由海外费用登记审核，供应商应付不变。订单详情新增费用统一委托人工费用服务。
+- 新换标资金状态固定 NOT_REQUIRED，完成不会发布旧自动应收；旧已冻结申请保留原资金收尾，仅在确认实扣后发布已收来源。已有旧来源只补扣款引用，不重复生成来源；旧财务账单需上线前核对撤销或核销。采购保留独立收费流程，禁止进入人工通用收费。
+- 同一服务业务的旧自动项目已锁款或已有有效应收时，拦截相同项目的人工重复登记；人工链允许按实际服务合法分次登记。

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

@@ -264,3 +264,7 @@ node lastleg-service/scripts/analyze-lastleg-dependencies.mjs --source-set all -
 - 两条边均属于同一 `lastleg-service` 部署单元内的海外仓出库与派送正式链路；本次只冻结已存在的生产依赖，不扩大海外主数据或安全投影的允许方向。
 
 2026-10-03 外接来货使用`FleetBookingIncomingGateway`，仅`transfer.fleet.FleetIncomingAdapter`实现该端口并复用`FleetDispatchGateway`的目的键算法；这两个精确类引用进入reviewedClassDependencies，不放开整个转运切片读取fleet实现。fleet不导入转运DTO/Service/Mapper，转运仍维护实收与库存；车次只保存实收证据和确认的承运载荷。包无环及禁止其他消费者扩大依赖的反向测试继续生效。
+
+### 档案照片只读复用边界（2026-10-26）
+
+`DispatchMasterPhotoService`仅通过`fleet.photo.port.FleetResourcePhotoPort`及其照片DTO读取档案照片，再经排车文件网关生成当趟副本。`TransportTaskService`仅新增照片类别DTO引用，不读取照片Mapper或Repository。`fleet.photo`复用车辆`VehicleRepository`应用端口与司机应用服务校验身份，不反向依赖排车；精确边界纳入依赖合同。

lastleg-service/docs/overseas-fees-storage-rent-release.md

@@ -0,0 +1,167 @@
+# 海外费用与仓租首版发布验收
+
+本文件记录本次实现范围及验收口径。源码、本地测试、模拟页面预览、环境部署与实际资金验收分别记录；本地结构补充与重启见文末记录，不能据此认定上线验收通过。
+
+## 首版规则
+
+费用入口为 Admin「海外业务 → 海外费用管理」，仅保留「费用明细」与「仓租库存」两个页签。仓租库存查看相关单据、入库批次、库龄、剩余数量及出库数量记录，不展示金额和审核、调价入口。仓租金额及入库/出库时间、出库批次、计算金额、应扣及实扣金额在费用明细详情查询，多入库批次分别展示实际入库时间。审核与调价统一在对应尾程单据详情的「费用明细」办理，审核前调价必须填写说明。复用 Firstleg 公共费用项目，仓租项目为 `FEE_TYPE_077 / 仓储费`；不建立第二套海外费用目录。人工费用选择真实客户、当前服务业务单、项目、金额与币种后创建，详情保留必要的审核和资金状态。
+
+头程附加费审核后推送 Finance 账单。其余海外人工应收创建时冻结余额及可用授信，审核通过后扣款，Finance 成功扣款回执后登记本地已收费用，直接显示已完成，不再推送财务账单；驳回、取消释放冻结。在途回执、失败重试与同键重放不能重复扣款。车辆或同车运输不能代替每笔费用对应的客户和业务订单。
+
+现有尾程订单没有权威的“原报价已含派送费”字段。首版新增头程派送费仍由审核人员核对原报价，已包含则驳回该费用；系统尚不支持自动判断报价包含关系，审核提示不能替代人工核对。
+
+头程货最终目的地为自有海外仓、仓储转运（含外来货）以及退货建立计租批次。仓租全部使用余额及可用授信。实际 PDA 入库开始、实际 PDA 出库停止本次出库份额计租，每24小时计一天，不足24小时按一天。余货保持原入库时刻，不重置免费期；移库、换标和拆合托不新增免费期。
+
+头程同单同仓多次实际入库合并为一个计租批次，统一从首次实际入库起算；补入库只追加箱数和计费体积，不重置库龄、免费期或已出库记录。单位体积沿用首次入库比例，后续修改订单体积不改写既有计租比例。其他业务保留各批实际入库时间分别计龄。头程未逐箱清点时，部分出库按来源单据箱数比例估算体积，审核前可调整金额并填写原因。本次不合并历史已存在的计租批次。
+
+| 规则 | 计费阶梯（USD） | 数量口径 |
+|---|---|---|
+| 中转仓租 | 第1–7天免费；8–30天0.8；31–60天1；61–90天1.5；91天起2 | CBM/天，按阶梯累加 |
+| 退货仓租 | 第1–30天1.5；31–60天2；61–90天3；91天起4 | 原始托数向上取整，按本次出库占原托比例分摊 |
+
+自动计租优先读取现有客户仓租配置；无客户配置时使用上述两张报价表。USD 配置缺少整组中转或退货阶梯时，缺失组补用对应默认报价；非 USD 配置不得直接补用美元价格。已配置阶梯须从第1天连续覆盖至无限期，有限尾阶梯、缺段、负价或不支持的币种均阻断计价，不将配置错误或服务异常当作默认报价。
+
+每次出库资金预校验保存客户、配置编号及版本、币种、完整阶梯和计算结果快照。有效预占和实际扣款使用原快照；修改配置不重算已冻结或已生成的费用。后续新预占按最新客户配置计算本次出库份额的全部库龄，仍保留最初入库时间；本版不把一次出库按历次调价日期再拆段计费。过期或货物、计租天数等依据变化时须重新预校验。
+
+原币金额与人民币结算额分别保留，冻结时固定汇率快照。无有效汇率时不得将美元直接作为人民币扣款。免费期零仓租保留出库记录，不要求汇率、不冻结资金。仓租自动计算，出库仅登记待审核费用并保留冻结；批准后沿原资金身份按实额扣款，驳回释放原冻结。订单费用和海外费用管理均展示原批次实际入库、实际出库、原计算金额、应扣金额及实扣金额。审核前允许原币金额调整且说明必填，保存版本；调低释放多余占用，调高由Finance结算时原子检查差额，余额不足保留原冻结，不登记实扣。原零元改非零先补冻结，成功后才能审核。其余客户收费人工录入并审核。历史已扣费用保留结果，不补审、不重复扣款。
+
+新计租批次在实际入库事务中记录 UTC 时刻，接口携带时区，页面按浏览器时区显示；不猜测历史无时区时间并回填。退货 SKU 换标保存原批次份额迁移快照，撤销时按该快照恢复。批次全部出库后，库龄固定在最后实际出库时刻。
+
+## 计租验收样例
+
+1. 中转批次10箱共2CBM，第10天出4箱：3个收费日 × 0.8CBM × 0.8 = **1.92 USD**；余6箱第31天出库：(23×0.8+1×1) × 1.2CBM = **23.28 USD**。余货仍从最初入库计龄。
+2. 退货原批次不足一托，100件按1托，第10天出40件：10×1.5×40%=**6 USD**；第40天出余60件：(30×1.5+10×2)×60%=**39 USD**。第二次出库不再次将剩余货物进位到1托。
+3. 入库后恰好24小时为1天，24小时加1毫秒为2天；恰好7天仍免费，7天加1毫秒进入第8天。对金额先按份额精算，完整收费命令汇总后按结算精度取整。
+
+## 发布配套
+
+- 后端：Firstleg 公共目录内部接口、Warehouse 客户仓租内部报价接口、Lastleg 费用/仓租及真实收发货挂钩。Finance 继续作为余额、授信、冻结和实扣的唯一权威；不得绕过 Outbox/Inbox 链路。
+- 前端：Admin 海外费用管理与海外 PDA 出库预校验同时发布，不能只更新一端。
+- 数据库文件：本次五份版本脚本及两份专项汇总 SQL 已收敛到 [国内统一空库基线](../../deploy/sql/头程数据库统一增量-MySQL8.sql) 和 [海外统一空库基线](../../deploy/sql/海外区域统一增量-MySQL8.sql)。海外基线完整包含资金与仓租四表、拆柜成本可空费用引用、退货 SKU 换标仓租份额快照、审核人名称及采购退款请求幂等字段和唯一索引，国内基线包含菜单和默认管理员授权。内容清单见 [数据库变更汇总](../../deploy/sql/20261022-海外费用仓租数据库变更汇总.md)。
+- 已有库：不能重放统一空库初始化；须按实际结构和明确授权审阅增量。[免费仓租定向结构修复](../../deploy/sql/overseas-storage-rent-zero-fee-repair.sql) 仅解决自动仓租双零金额和空汇率入费用源表，保留人工正额与正常费用有效汇率约束，不更新业务数据。独立的 [既有费用写权限修复](../../deploy/sql/overseas-fee-canonical-write-permissions-repair.sql) 仍只处理已有管理员两项 canonical 写权限，不能代替结构升级或菜单初始化。
+- 新空库：Lastleg 源基线与海外统一初始化脚本同步新表和字段；国内统一基线同步菜单。菜单查询权限 `platform:overseas-fee:list`，编辑与审核分别沿用 `platform:finance:fee-source:edit/review`，仅有查询权限不能写费用。
+- 配置：核对 Firstleg、Warehouse 内部服务地址及内部令牌、客户仓租阶梯、有效 USD/CNY 月度汇率、Finance 资金与费用事件直投及回执配置。当前结算支持 USD、CNY，CNY 按1:1结算，其他币种必须先调整为受支持币种。不得在材料中记录密钥。
+- 发布顺序：先发布 Warehouse 客户计租接口与 Finance，再发布 Lastleg，配套更新 Admin 与海外 PDA。成功扣款引用新增可选的 `walletBusinessType/walletBusinessNo`，分别指向人工费用冻结编号或仓租出库预占编号；外层业务编号仍是实际服务单。Finance 校验客户、金额、成功命令、冻结与流水一致且不可重复关联，接收后标记已结清。旧版 Finance 不识别这两个字段，不得先发生产者。
+
+## 实际环境验收
+
+以下必须在匹配版本、指定测试客户和仓库上实际操作并保留单号、资金事件、流水和页面证据；本地测试不替代这些步骤。
+
+| 场景 | 通过标准 |
+|---|---|
+| 权限与查询 | 菜单、客户、业务单、项目、审核及资金状态筛选有效；无权限按钮不展示，直接调用同样被拒绝 |
+| 人工海外收费 | 创建只冻结；审核后恰好扣一次；驳回/取消释放；不足余额但授信足够可成功，二者合计不足明确失败 |
+| 头程附加费 | 审核前不入账单，批准后回到正确头程来源且不扣钱包；人工核对原报价，已含派送费的新增收费须驳回 |
+| 仓租原生入库 | 头程自有仓、外来转运和退货实际扫码均生成正确原批次；非计租范围不误收 |
+| 部分及分批出库 | 原托比例、阶梯、库龄和余量符合上例；整托/多箱/混SKU全部来源核对后才能扣库存 |
+| 客户价格与默认报价 | 客户专价优先；无配置按两张默认报价；接口超时或无效阶梯不允许默认为免费或默认报价 |
+| 调价与币种 | 有效预占及已生成费用不受调价影响，新预占使用新版本；USD、CNY 原币及分币种汇总准确，不将混合币种直接相加 |
+| 资金门禁 | 未冻结成功、资金不足、过期、未知网络结果均不放行库存写；成功后仅本次实际出库份额扣款 |
+| 幂等与并发 | 同键重放、回执重复/错序、双设备争抢不重复扣款或超出原批次数量；内容改变不得复用原键 |
+| 移库换标及异常 | 移库、拆合托、换标保持原库龄；未知历史计租来源不可凭空补零放行 |
+| 弃置及取消 | 废弃实际扣库存同样校验仓租；放弃未完成的预占能释放，释放失败保留可处理记录 |
+| 资金核对 | 原币、汇率、人民币冻结与实扣金额一致，已收费用关联到正确Finance流水；余额应收不推送账单结算池，重试和回执重放不再次扣款 |
+| 页面及设备 | 实际浏览器核对表格、筛选、详情、审核弹窗及错误提示；PDA真实扫码和断网恢复通过 |
+
+## 验证记录
+
+本地验证结果在本次交付说明中列出；真实环境 SQL、部署、HTTP 联调与 PDA 设备验收尚未执行。上线前逐项填写环境、版本、执行时间与证据，未通过项不得标成通过。
+
+2026-10-22 本地验证记录（使用最终受影响文件；复用已通过且输入未变的结果）：
+
+| 范围 | 结果与边界 |
+|---|---|
+| Finance 与事件契约 | Finance 294项：293通过、1项因外部产品契约仓库缺失跳过；公共事件契约37项通过，包含资金业务引用序列化与旧哈希形状验证 |
+| Firstleg 费用目录 | 公共费用项目查询2项通过 |
+| Lastleg 受影响链路 | 37个测试类汇总578项：576通过、2项MySQL专用场景因未配置数据库跳过，0失败/错误；覆盖计租、资金回执、真实库存门禁、部分出库、移库换标、退货、转运及原收费入口。订单列表测试与重复注解修正后，受影响两类87项复跑通过 |
+| 海外 PDA | 仓租预校验、出库生命周期、履约与排车共88项通过；未运行真实设备 |
+| Admin | 新页面与接口定向测试、类型检查及构建通过；最终“头程入仓”文案修正后，展示规则3项定向复跑通过，差异格式检查通过。截图使用模拟数据与真实页面组件，不是环境验收证据 |
+| 数据库静态检查 | 初始化及统一SQL合同29项通过；迁移登记检查通过；没有连接数据库或执行SQL |
+| 架构与入口 | Mapper扫描424项、Lastleg依赖合同15项、Gateway路由合同5项通过；三个仓库差异格式检查通过 |
+
+已知环境检查缺口：`agents-index-contract.ps1` 因现有外部文档 `D:/project/docs/业务快速索引.md` 缺失未通过；Admin全量密度检查存在既有 `UnifiedOrdersView` 工具栏32px问题。本次新页面密度定向检查通过，不能据此宣称全仓检查全部通过。
+
+页面预览保存在 `D:/project/html/artifacts/overseas-fees-acceptance/`，包含费用列表、费用详情、人工费用审核、头程费用审核、仓租列表及仓租详情。
+
+2026-10-22 客户仓租配置接入补充验证（不与上一轮测试数量累加）：
+
+| 范围 | 结果与边界 |
+|---|---|
+| Warehouse 客户计租接口 | 4个定向测试类共24项全部通过；覆盖客户专价、默认报价、缺失组、无效阶梯、内部鉴权及一致读取 |
+| Lastleg 客户计价与出库 | 10个定向测试类共153项全部通过，无失败、错误或跳过；覆盖配置校验、动态阶梯、原批次份额、原价格快照消费、重建预占读取新价、CNY结算、混币展示和整托汇总，以及普通出库、退货出库和废弃库存门禁；生产与测试源码编译通过 |
+| Admin 币种展示 | 3个定向测试文件共9项通过，类型检查通过；列表按原币分别显示，详情按收费实际币种显示，不默认所有仓租为USD |
+| 静态契约 | Warehouse及仓租OpenAPI可解析；Gateway路由5项、Lastleg依赖15项通过；差异格式检查通过 |
+
+本次接入没有增加数据库字段；首版数据库定义以“发布配套”列出的国内、海外统一空库基线为准，已有库升级须单独核对。补充验证没有执行数据库脚本、部署、真实HTTP或PDA设备验收。
+
+旧收费切换：新换标报价不再冻结，外接运费只保留约定记录，拆柜打托只保留成本分摊。旧派送请求含客户应收将明确提示转到海外费用登记。历史换标若已发布过应收又已有冻结，结清回执只为原来源补扣款引用，绝不生成第二笔；此前进入 Finance 的旧账单不能仅靠本次发布自动回写，须在上线前核对并撤销未结应收或做既有账单核销，避免再次催收。新增旧冻结结清只在实际扣款成功后携带 command/hold/ledger 引用发布。采购独立流程及自动仓租保留。
+
+2026-10-22 费用入口与回显修复：尾程详情录费改用公共费用目录，按应收/应付方向查询，禁止自由输入和手工添加自动仓租。目录失败可重试，未加载成功不允许保存；供应商只在应付时加载。订单费用返回并显示统一结算方式及锁款/实扣状态；统一业务类型 LASTLEG_ORDER 展示为“尾程订单”，不把转运、退货尾程单一律标成头程入仓。历史已发布账单保留原结算记录，不自动重扣。
+
+客户名称为空时按真实客户 ID 经 IAM 内部接口补齐查询展示，保留原有名称快照，不回写历史费用；费用筛选和业务候选同步补齐名称。新录费用仍按实际 FIRST_LEG 与海外业务类型分流，前者审核入账单、后者锁款后审核扣费。
+
+本轮验证：Lastleg 定向4类64项通过，客户查名6项通过；Admin费用详情、接口与管理列表定向测试通过，类型检查通过；Gateway路由5项、Lastleg依赖15项、差异格式检查通过。本机 Lastleg、Warehouse、Finance 已重启加载新编译版本，正式 Gateway 已核验客户名称回显、费用目录方向及仓租查询。完整业务造单、PDA出库、资金实扣的逐单结果另记本轮场景报告，以上结果不能代替全链路验收。
+
+2026-10-23 库龄批次与操作入口调整：
+
+- 头程同单同仓补入库复用首次计租批次，并登记收货幂等记录；其他业务继续按实际入库批次分别计龄，不自动合并历史批次。
+- 页面只保留费用明细、仓租库存；库存查看库龄与余量，费用明细查询计费依据，审核和必填说明的调价放在对应尾程单据详情的费用明细。
+- 自动检查：Admin 费用管理、仓租库存和单据费用组件共35项测试及类型检查通过；Lastleg费用持久化与服务50项、Gateway路由5项通过；此前入库批次相关54项和Mapper扫描425项通过，相关输入未变的结果复用。
+- 本地数据库仅定向补建并核验 `ll_storage_rent_inbound` 表，没有重放空库初始化，没有修改费用或钱包记录。Lastleg与Admin服务已重启，最新检查为后端健康UP、前端HTTP200；最新前端调整由开发服务热更新加载。
+- 本轮未重新执行完整PDA出库及真实资金扣款流程；最终页面布局待人工操作真实页面并截图确认。
+
+2026-10-23 来源单展示补充：仓租库存的原业务单号明确标为「来源单号」，出库记录保留「出库业务单号」。单据费用详情及仓租审核弹框按每条原计租批次展示来源类型、来源单号和入库批次；头程货对应原尾程订单，退货货物对应原退货单，换标不覆盖原来源。查询按费用快照引用的批次编号批量读取原批次，并校验客户、仓库一致；缺失来源显示空值，不推断单号，不修改历史费用或计费金额。本次无需数据库结构变更。
+
+来源展示自动检查：Admin费用管理、仓租库存、单据费用35项测试与类型检查通过；后端来源隔离及仓租服务37项测试通过，生产和测试源码编译通过。后端已重启加载新增查询字段；页面布局仍待真实页面人工截图确认。
+
+2026-10-23 本机开发环境真实 HTTP 费用闭环补充（不含头程，不代表生产发布）：
+
+- 退货换标单 TH202610230002 已完成实物签收、清点、换标和 PDA 出库；出库仓租来源为退货单，原计算 USD 1.50 / CNY 10.01。调价 USD 1.00 必填原因后，旧版本审核被拒，正确版本审核及重放只生成一条 CNY 6.67 消费；释放原冻结 CNY 10.01，归还差额 CNY 3.34。另以原消费流水做 CNY 1.00 部分退款，原消费金额保持不变，退款仅增加一次余额并以 referenceNo 关联原消费。
+- 仓储转运单 ZY202610230002 的自动换标单 TB202610230002 已完成真实箱数清点、入库计龄、换标和 PDA 出库。仓租详情确认来源是 WAREHOUSE_TRANSFER / ZY202610230002，批次 ZY202610230002，数量 1、库龄 1 天；免费 USD 仓租保留 NULL 汇率。原零元改 USD 1.00 并采用实际月汇率 6.67，先冻结 CNY 6.67，审核前不实扣；旧版本审核拒绝，正确审核和重放后仅消费一次 CNY 6.67。原批次余量 0，在库仓租页总数为 0。
+- 自动仓租、本机实际资金流水及数据库金额/Fx边界的 30 项在线断言通过：原零元调价原因/版本门禁、差额冻结/释放、余额实扣、驳回与释放、重复请求、超余额冻结失败、原消费部分退款、来源/库存过滤均有报告。人工费用额外 6 项通过：退货单人工应收 1.23 先冻结后审核只扣一次，转运单 1.11 驳回后解冻，超余额费用不得审核且没有新增冻结或扣款。
+- 本机开发库已按用户单独授权执行 overseas-storage-rent-zero-fee-repair.sql；仅修正指定零元自动仓租金额/汇率约束，保留汇率 DEFAULT 1 但 MyBatis 显式写 NULL，未改业务行。Lastleg 重启加载最终代码。自动化持久化测试 3 项及仓租状态机 42 项通过。
+- Admin 自动化覆盖账户失败重试、500 字退款说明边界及换标资金状态中文映射；聚焦测试和类型检查通过。实际浏览器曾核对退货仓租详情及换标单费用区的审核/调价入口、出入库来源明细；自动仓租审核前“费用状态 —”符合现有契约（仅完成/失败显示状态），旁列显示待审核。
+- 美国卡车 `TR202610230001` 的统一目录应收已在线验证：1.23 元先冻结、审核同键重放只实扣一次，按卡车来源类型/单号查询正确回显；随后原消费关联退款 1.23 元且仅一条退款流水，再按正式取消接口将验收订单收口。卡车链路 7 项在线断言通过。
+- 散板在线验收被本机数据库结构漂移阻断，没有创建散板单。Lastleg 错误为 `ll_local_looseboard_order.transport_mode` 无默认值；开发库结构快照还显示 `pallet_required`、`transport_type` 等旧列与当前实体/基线不一致。当前发布基线和 `LocalLooseboardSchemaContractTest` 均明确排除 `transport_mode`。按授权边界没有为此执行 SQL 或修改业务代码，需先核对并获准将本机 Lastleg 表收敛到当前正式基线，再重试散板链路。
+- UI自动化继续检查时浏览器控制通道超时；此前已读到真实换标单详情 DOM，但本轮缺少最终页面截图，视觉验收状态保留为未完整确认。
+- 在线报告位于 D:/project/.codex-temp/overseas-release-live-report.json、overseas-money-live-report.json、overseas-refund-live-report.json、overseas-manual-money-live-report.json、overseas-zero-adjust-live-report.json；账户凭据和会话不在报告中。
+
+2026-10-23 接续验收：
+
+- 修正 `OverseasManualFeePersistenceTest` 的隔离 H2 费用表夹具，补齐 `exchange_rate` 并将无列名插入改为显式列名；`LocalLooseboardSchemaContractTest`、`LocalLooseboardPersistenceTest`、`OverseasManualFeePersistenceTest` 共14项定向测试通过。
+- 采购与费用跨区离线合同22项通过；Lastleg采购结构、OpenAPI、库存边界、请求边界、费用持久化共38项通过；Finance采购结算、海外钱包收口、派送费用覆盖共26项通过。以上均为本机自动化检查，不等于真实HTTP或页面验收。
+- 浏览器重试仍在读取当前登录页时超时，页面视觉验收继续保留未完成状态。
+- 散板本机结构只读对比已确认：`ll_local_looseboard_order` 仍含旧的 `transport_mode`、`container_type`、`contact_name`、`contact_info`、`requested_date` 及旧日期索引；当前正式基线要求移除这些字段并使用 `product_name`、`estimated_pallet_count`、双联系人、`pickup_at`/`delivery_at` 及新日期索引。未执行数据库变更，待单独授权后再按可审阅增量收敛并重试散板费用链路。
+
+当前不能标为海外费用全量上线验收通过：采购专用付款/部分退款及最终交寄门禁、散板单据费用创建和回显、派送费用入口迁移及旧入口不重复计费、应付账期/直付不改变客户钱包、真实角色权限与跨客户伪造归属拒绝，仍需分别针对实际业务单和部署授权做验收；卡车仅完成通用费用闭环，不代表车队履约生命周期已验。自动化测试覆盖了其中部分服务逻辑，但没有替代这些真实 HTTP 场景。本机 Gateway/数据库验证不代表生产部署；双设备竞争、MySQL 锁/回滚、未知网络结果与真实事件错序回执也仍未通过真实环境验收。
+
+2026-10-24 接续：
+
+- 已按单独授权执行本机散板结构收敛：正式表 `ll_local_looseboard_order` 备份为 `backup_ll_local_looseboard_order_20261023`，移除旧字段并补齐当前实体所需可空/默认值及日期索引；正式表与备份表均保留4条原记录。
+- Lastleg 已用完整本地环境变量恢复，`http://127.0.0.1:9303/actuator/health` 返回 UP；散板结构、持久化和人工费用14项定向测试全部通过。
+- 真实消费者造单夹具尚未完成：其测试上下文仍被 Spring Boot/Nacos config import 解析阻断，未据此伪造散板 HTTP 通过结论，也未重复写入已存在的换标、退货或卡车验收数据。
+## 2026-10-24 费用风险回归补充
+
+- Lastleg 定向回归 96 项实际执行通过：派送费用入口、人工费用、采购专用资金、费用取消/补偿、Outbox 重试、散板结构和费用归属均无失败。
+- Finance 定向回归 49 项实际执行通过：冻结/实扣/释放事务回滚、重复及冲突回执、Outbox 租约、原消费退款、客户账户隔离均无失败。
+- 新增 `PlatformOverseasFeeSourceControllerSecurityTest`，验证非 `PLATFORM + tenant=0` 主体在读取费用前直接返回 403；1 项通过。
+- `CargoDiscardMysqlAcceptanceTest` 本轮仍因本机未开启 MySQL 验收开关而跳过，不能视为废弃费用真实数据库验收通过。
+
+当前仍不能标记为“海外费用全部上线通过”的门槛：采购真实 HTTP 付款/部分退款/交寄门禁、DELIVERY_ORDER 真实费用迁移且旧入口不重复计费、卡车/散板真实单据费用目录闭环、账期/直付应付不触碰客户钱包、真实角色与跨客户 HTTP 隔离、双设备并发/超量出库、MySQL 锁回滚及未知网络回执。这些已有隔离测试或服务层证据，但尚缺真实服务/数据库证据。
+
+## 2026-10-26 缺口修复与散板真实接口复验
+
+- 本机 Lastleg 按完整 Nacos/JWT/Redis 环境重启，`/actuator/health` 返回 `UP`，并完成 Nacos 注册；此前网关 503 的直接原因是 9303 未启动/未注册，不是散板业务异常。
+- 使用新幂等键 `OVERSEAS-TEST-20261026-loose` 调用真实 Lastleg 接口创建散板订单，返回 `200`，订单号 `LB202610260002`，状态 `PENDING_ACCEPTANCE`。
+- 使用同一幂等键重复创建，返回同一订单 ID 和订单号；真实详情查询返回同一订单及状态，验证散板创建幂等和客户隔离查询。
+- 费用业务候选接口真实返回该散板订单，业务类型 `LOCAL_LOOSEBOARD`、业务单号 `LB202610260002`、客户 ID 一致。
+- Finance 服务当前未在本机注册，网关账户接口仍返回 `503`；因此散板费用冻结、审核、实扣和退款不能冒充真实 HTTP 已通过。Finance 定向自动化 49 项仍全部通过。
+
+## 2026-10-26 缺口修复接续
+
+- Finance 已使用完整本机 Nacos/JWT/Redis 环境恢复，`9203` 启动并注册；散板费用真实闭环已补验：`LB202610260002` 的登记冻结、审核实扣、详情回显、重复审核只扣一次均通过。
+- 散板原消费已做真实全额退款验收：重复退款复用同一流水、余额只恢复一次、超额退款及同键改金额均拒绝。
+- 真实权限/归属风险已验收：客户令牌访问平台费用和退款均拒绝；伪造客户 ID 或业务单号创建费用均拒绝。
+- 采购真实 HTTP 验收已创建测试采购单并验证下单幂等，但凭证上传因当前本机管理员会话缺少正式 `platform:overseas-business:purchase:buy` 权限被拒绝，不能将采购付款、部分退款、交寄门禁标记为通过。现有权限定义和服务层定向测试仍有效，需补齐本机角色授权后继续。
+- 回归期间发现 `LastlegOrderServiceTest` 使用旧版查询构造参数，已补齐测试调用；Lastleg 采购资金相关四个定向测试（`ProcurementFinancePersistenceTest`、`ProcurementPurchasePersistenceTest`、`ProcurementControlPersistenceTest`、`ProcurementChargePersistenceTest`）及生产/测试编译通过。
+- 当前仍未完成：采购真实付款/部分退款/交寄门禁、派送 `DELIVERY_ORDER` 真实迁移与旧入口去重、应付账期/直付不触碰客户钱包、真实角色矩阵验收、双设备并发/超量出库、MySQL 锁回滚和未知网络回执；页面视觉验收也仍需人工截图确认。

lastleg-service/docs/procurement-direction.md

@@ -0,0 +1,12 @@
+# 采购双方向履约
+
+2026-10-26 按用户要求增加国内采购发往海外，保留海外采购回国内。
+
+- `procurementDirection` 为 `OVERSEAS_TO_DOMESTIC` 或 `DOMESTIC_TO_OVERSEAS`，不传时保持历史进口方向。客户建单可选；平台审核仅展示客户下单方向，不允许审核改向；采购仓按该方向筛选。审核底部直接取消、拒绝或通过，拒绝必须填写具体原因。
+- 起运收货仓按方向读取 Warehouse 权威公共启用仓目录，国内方向只接受 DOMESTIC，进口方向保持海外 RECEIVING 能力约束。实际收货、计划仓更改、实际仓更正及面单寄件地址均校验同一方向。
+- 出口流程：审核 → 国内购买 → 国内分次实收并确认 → 装箱 → 国际面单、预估运费冻结、贴单 → 国内国际交寄 → 海外分次实收并确认 → 海外核定实际费用 → 寄海外客户。正常终态仍为 SHIPPED_TO_CUSTOMER，取消、拒绝、异常关闭规则保留。
+- 此次沿用单商品、一次购买、两段各整批交寄及 Admin 台账，不新增 WMS 库存、PDA 入账、分批购买或分批交寄。目的地接收地址沿用国际面单地址快照，最终客户地址由下单提供，最终面单变更仍需客户凭证。
+- 为保护历史数据关联，技术编码 OVERSEAS/DOMESTIC、overseas_received_at/domestic_received_at 及既有状态编码分别表示起运段/目的地段；业务展示按方向转换国内、海外。权限编码、费用用途 DOMESTIC_FREIGHT 和资金引用保持兼容；费用名称按实际目的地区域保存。
+- 版本与幂等覆盖方向；未传新字段的旧请求序列化忽略空方向，保留旧哈希。上线先执行 V34，再发布 Lastleg、Admin、Client；不能仅发布前端。
+
+自动验证覆盖方向持久化与幂等、国内仓主档校验、两段出口地址与交寄终态，以及页面切换方向后的仓库候选和旧请求重试。真实服务与人工截图验收另行记录。

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

@@ -64,6 +64,8 @@ test('fleet stays a business slice and its policies have no infrastructure depen
     && edge.target.startsWith('com.baiyue.lastleg.fleet.'));
   assert.ok(dispatchEdges.length > 0);
   assert.ok(dispatchEdges.every(edge => /\.(FleetDispatchGateway|FleetDispatchBindingGuard|FleetTripExecutionService|FleetExecutionModels|FleetCompletionModels)$/.test(edge.target)
+    || edge.source === 'com.baiyue.lastleg.dispatch.service.DispatchMasterPhotoService'
+      && ['com.baiyue.lastleg.fleet.photo.port.FleetResourcePhotoPort', 'com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels'].includes(edge.target)
     || edge.source === 'com.baiyue.lastleg.dispatch.fleet.FleetDispatchPlanningAdapter'
       && /\.(FleetBookingIncomingGateway|FleetDispatchPlanningGateway)$/.test(edge.target)
     || edge.source === 'com.baiyue.lastleg.dispatch.fleet.FleetDispatchPlanningMapper'
@@ -82,6 +84,7 @@ test('fleet stays a business slice and its policies have no infrastructure depen
       'TransportTaskProjection->trip.FleetTripEntity', 'TransportTaskProjection->trip.TransportTripChanged',
       'TransportTaskService->business.FleetPoolOrderQueries', 'TransportTaskService->driver.DriverService',
       'TransportTaskService->reporting.TripOperationsEvidenceGateway',
+      'TransportTaskService->photo.FleetResourcePhotoModels',
       // 取货照片沿既有运输边界读取车次身份/时间，并复用司机资格与证照授权；不开放 Mapper。
       'TransportReviewPhotos->driver.DriverService', 'TransportReviewPhotos->trip.FleetTripEntity',
     ].some(reference => `${edge.source}->${edge.target}` === `com.baiyue.lastleg.dispatch.transport.${reference.replace('->', '->com.baiyue.lastleg.fleet.')}`)),

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkDispatchPort.java

@@ -16,6 +16,12 @@ public interface AppointmentWorkDispatchPort {
     record CandidateBatches(List<BatchReference> appointmentBatches,List<String> blockReasons,boolean occupied) { }
     /** 整页真实客户/计划托盘一次批读；occupied含有效草稿与正式实托占用，由调用方核对本草稿身份。 */
     Map<CandidatePhysical,CandidateBatches> candidateBatches(List<CandidatePhysical> candidates);
+    /** 只读取本车已选实物的逐票预约选项；本车原占用不扣减本车可重新分配量。 */
+    Map<CandidatePhysical,List<AllocationSource>> allocationOptions(long dispatchId,List<CandidatePhysical> items);
+    record AllocationOption(String batchKey,String batchNo,Long recordVersion,int availablePackages,
+                            String confirmationNo,String appointmentAt,String appointmentEndAt,String timezone) { }
+    record AllocationSource(String sourceKey,String orderNo,String inboundCode,String destinationKey,Integer packageCount,
+                            List<AllocationOption> options,List<String> blockReasons) { }
     /** Current original allocations, grouped for authorized dispatches; historical copies are read-only evidence. */
     java.util.Map<Long,List<BatchReference>> references(List<Long> dispatchIds);
     /** 在来源锁前按批次键一次性预锁并核对权威版本，版本零合法。 */
@@ -27,7 +33,7 @@ public interface AppointmentWorkDispatchPort {
     String departureBlockReason(String dispatchNo);
     record ReceivingWindow(String batchKey,String batchNo,String customerId,String destinationKey,String confirmationNo,
                            java.time.Instant startAt,java.time.Instant endAt,String agreementKey,int version) { }
-    /** 预排不受限；提交审核、审核通过和开始拣货须有真实收货确认及可执行时间。 */
+    /** FBA选入前须已有正式时间确认；提交审核、审核通过和开始拣货继续复核运输安排。 */
     String reviewBlockReason(String dispatchNo,java.time.Instant plannedDepartureAt,java.time.Instant estimatedArrivalAt);
     List<ReceivingWindow> reviewEvidence(String dispatchNo);
     void removeItem(long dispatchId,long itemId);

lastleg-service/src/main/java/com/baiyue/lastleg/client/DomesticWarehouseDirectoryClient.java

@@ -19,6 +19,11 @@ public interface DomesticWarehouseDirectoryClient {
     ApiResponse<ReceivingWarehouse> receivingWarehouse(@PathVariable("warehouseId") long warehouseId,
         @RequestHeader("X-Internal-Service-Token") String internalToken);
 
+    /** 启用的国内公共仓库，供国内采购收货选择。 */
+    @GetMapping("/internal/warehouses/domestic")
+    ApiResponse<List<DomesticWarehouse>> domesticWarehouses(@RequestHeader("X-Internal-Service-Token") String internalToken);
+    record DomesticWarehouse(Long id, String warehouseCode, String warehouseName) { }
+
     record ReceivingWarehouse(Long warehouseId, String warehouseCode, String warehouseName, String countryCode, String status) { }
 
     @GetMapping("/internal/warehouses/0/{warehouseId}/active")

lastleg-service/src/main/java/com/baiyue/lastleg/client/FirstlegFeeCatalogClient.java

@@ -0,0 +1,27 @@
+package com.baiyue.lastleg.client;
+
+import com.baiyue.common.core.api.ApiResponse;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import java.math.BigDecimal;
+import java.util.List;
+
+/** 费用目录只读契约，不共享头程领域实体。 */
+@FeignClient(name = "firstleg-service", contextId = "firstlegFeeCatalogClient", url = "${FIRSTLEG_SERVICE_URL:${baiyue.clients.firstleg.url:}}")
+public interface FirstlegFeeCatalogClient {
+    /** 获取海外仓可选项目。 */
+    @GetMapping("/internal/firstleg/v1/fee-items")
+    ApiResponse<List<Item>> list(@RequestHeader("X-Internal-Service-Token") String token,
+                                @RequestParam("direction") String direction);
+
+    /** 验证实际录费使用的项目。 */
+    @GetMapping("/internal/firstleg/v1/fee-items/{code}")
+    ApiResponse<Item> detail(@RequestHeader("X-Internal-Service-Token") String token,
+                            @PathVariable("code") String code, @RequestParam("direction") String direction);
+
+    record Item(String code, String name, BigDecimal defaultPrice) { }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/delivery/model/DeliveryCargoGroups.java

@@ -59,16 +59,26 @@ public class DeliveryCargoGroups {
             var rows=entry.getValue().stream().sorted(Comparator.comparing(CargoLine::dispatchItemId)
                 .thenComparing(CargoLine::attributionId)).toList();
             var first=rows.get(0);
-            if (rows.stream().anyMatch(row->!Objects.equals(row.destination(),first.destination())))
+            // FBA以真实仓码分组；外接来货可缺内部仓ID，只沿同组已知ID核对，不能覆盖冲突值。
+            var destination=rows.stream().map(CargoLine::destination)
+                .filter(value->!blank(value.warehouseId())).findFirst().orElse(first.destination());
+            if (rows.stream().anyMatch(row->!Objects.equals(withKnownFbaWarehouseId(row.destination(),destination.warehouseId()),destination)))
                 throw conflict("同组货物的目的地信息不一致，请核对后安排");
             long packages=rows.stream().mapToLong(CargoLine::packages).reduce(0,Math::addExact);
             long pallets=rows.stream().map(CargoLine::warehousePalletId).filter(Objects::nonNull).distinct().count();
-            result.add(new Group(entry.getKey(),first.customerId(),first.customerName(),first.destination(),
+            result.add(new Group(entry.getKey(),first.customerId(),first.customerName(),destination,
                 hash(rows),rows,packages,pallets));
         }
         return List.copyOf(result);
     }
 
+    /** 仅补同一分组FBA缺失的内部引用，其他目的地事实必须保持完全一致。 */
+    private Destination withKnownFbaWarehouseId(Destination value,String warehouseId) {
+        if (!"FBA".equals(value.type()) || !blank(value.warehouseId()) || blank(warehouseId)) return value;
+        return new Destination(value.key(),value.type(),warehouseId,value.warehouseCode(),value.warehouseName(),
+            value.address(),value.postalCode(),value.contactName(),value.contactPhone());
+    }
+
     /** 客户是组身份的一部分，同目的仓的其他客户永不合单。 */
     public String groupKey(String customerId,Destination destination) {
         return hash(List.of(customerId,destination.key()));

lastleg-service/src/main/java/com/baiyue/lastleg/delivery/service/DeliveryTransferService.java

@@ -78,7 +78,6 @@ import org.springframework.web.server.ResponseStatusException;
 
 import java.time.LocalDateTime;
 import java.time.LocalDate;
-import java.time.format.DateTimeFormatter;
 import com.baiyue.lastleg.service.LastlegOrderNoGenerator;
 import java.math.BigDecimal;
 import java.math.RoundingMode;
@@ -92,6 +91,8 @@ import java.util.stream.Collectors;
 
 @Service
 public class DeliveryTransferService {
+    @jakarta.annotation.Resource private com.baiyue.lastleg.storagerent.service.StorageRentService storageRent;
+
     @Resource private DispatchAggregateRepository dispatches;
     @Resource private DispatchItemMapper dispatchItems;
     @Resource private OutboundOrderMapper outboundOrders;
@@ -192,7 +193,7 @@ public class DeliveryTransferService {
         outbound.setVolumeCbm(sum(createdMetricItems, OutboundPalletItem::getVolumeCbm));
         outbound.setOverseasWarehouseId(selectedWarehouseId); outboundOrders.updateById(outbound);
         OutboundPdaTask task = new OutboundPdaTask(); task.setId(IdWorker.getId()); task.setCustomerId(customerId); task.setOutboundOrderId(outbound.getId());
-        task.setTaskNo("PDA" + now.format(DateTimeFormatter.BASIC_ISO_DATE) + task.getId()); task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
+        task.setTaskNo(orderNoGenerator.next("OUTBOUND_TASK")); task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
         return taskResult(outbound, task);
     }
 
@@ -307,7 +308,7 @@ public class DeliveryTransferService {
         delivery.setVersion(0L); delivery.setCreatedBy(operatorId); delivery.setCreatedAt(now); delivery.setUpdatedAt(now);
         deliveryOrders.insert(delivery);
         OutboundPdaTask task = new OutboundPdaTask(); task.setId(IdWorker.getId()); task.setCustomerId(customerId); task.setOutboundOrderId(outbound.getId());
-        task.setTaskNo("PDA" + now.format(DateTimeFormatter.BASIC_ISO_DATE) + task.getId()); task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
+        task.setTaskNo(orderNoGenerator.next("OUTBOUND_TASK")); task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
         return taskResult(outbound, task);
     }
 
@@ -459,7 +460,7 @@ public class DeliveryTransferService {
         recordOperation(customerId, delivery.getId(), operatorId, "CREATE_DELIVERY", "仓储转运出库自动生成派送单", now);
 
         OutboundPdaTask task = new OutboundPdaTask(); task.setId(IdWorker.getId()); task.setCustomerId(customerId);
-        task.setOutboundOrderId(outbound.getId()); task.setTaskNo("PDA" + now.format(DateTimeFormatter.BASIC_ISO_DATE) + task.getId());
+        task.setOutboundOrderId(outbound.getId()); task.setTaskNo(orderNoGenerator.next("OUTBOUND_TASK"));
         task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
         transfer.setStatus("WAIT_OUTBOUND");
         if ("FBA".equals(destinationType)) transfer.setFbaWarehouseCode(request.destinationWarehouseCode().trim());
@@ -527,6 +528,7 @@ public class DeliveryTransferService {
         return pickResolved(warehouseId, operatorId, taskNo, request, false);
     }
 
+    /** PDA 真实出库在扣库存前校验同一扫码的仓租冻结，原幂等结果优先恢复。 */
     private DeliveryResponses.PdaTask pickResolved(String warehouseId, String operatorId, String taskNo,
                                                     DeliveryRequests.PdaPick request, boolean palletScan) {
         OutboundPdaTask task = pdaTasks.lockByNoAndWarehouse(required(taskNo, "PDA task number is required"),
@@ -561,6 +563,9 @@ public class DeliveryTransferService {
         if (item == null || !customerId.equals(item.getCustomerId())
             || !task.getOutboundOrderId().equals(item.getOutboundOrderId())) throw notFound("Outbound pallet item not found");
         if (request.packages() > item.getPackageCount() - value(item.getPickedPackageCount())) throw conflict("Picked quantity exceeds outbound pallet quantity");
+        storageRent.consume(warehouseId, new com.baiyue.lastleg.storagerent.dto.StorageRentDtos.PrepareRequest(
+            "OUTBOUND", taskNo, request.outboundPalletItemId(), request.inventoryPositionId(), request.packages(), null, null,
+            request.idempotencyKey(), request.cartonMarks(), request.skuCode(), request.productQuantity()));
         if ("RETURN_OUTBOUND".equals(outbound.getOutboundType())
             || ("RELABEL_OUTBOUND".equals(outbound.getOutboundType()) && item.getWarehousePalletId() == null)) {
             if ("RETURN_OUTBOUND".equals(outbound.getOutboundType()) && StringUtils.hasText(item.getPalletNo()) && !palletScan)
@@ -730,9 +735,22 @@ public class DeliveryTransferService {
         return taskResult(outbound, task);
     }
 
-    /** 扫描整托前核平全部指定来源，任一不足时不执行部分拣货。 */
+    /** 整托扫描使用与资金预校验完全一致的实际子来源，任一失败则整托回滚。 */
     @Transactional
     public DeliveryResponses.PdaTask pdaPickPallet(String warehouseId, String operatorId, String taskNo,
+                                                  String palletNo, DeliveryRequests.PdaPalletPick request) {
+        var children = storageRentPalletRequests(warehouseId, operatorId, taskNo, palletNo, request);
+        DeliveryResponses.PdaTask result = null;
+        for (var child : children) result = pickResolved(warehouseId, operatorId, taskNo, child, true);
+        if (result != null) return result;
+        var task = pdaTasks.lockByNoAndWarehouse(taskNo, warehouseId);
+        if (task == null) throw notFound("当前仓没有该出库工单");
+        return taskResult(requireOutbound(task), task);
+    }
+
+    /** 资金预校验和实际整托扫码共享同一来源展开及子扫描幂等键算法。 */
+    @Transactional
+    public java.util.List<DeliveryRequests.PdaPick> storageRentPalletRequests(String warehouseId, String operatorId, String taskNo,
                                                     String palletNo, DeliveryRequests.PdaPalletPick request) {
         String boundWarehouseId = required(warehouseId, "PDA warehouse binding is required");
         String code = required(taskNo, "PDA task number is required");
@@ -753,7 +771,7 @@ public class DeliveryTransferService {
             .stream().filter(item -> palletCode.equals(item.getPalletNo())).toList();
         if (palletItems.isEmpty()) throw notFound("当前出库任务没有该托盘");
         if (palletItems.stream().allMatch(item -> value(item.getPickedPackageCount()) >= value(item.getPackageCount()))) {
-            return taskResult(outbound, task);
+            return java.util.List.of();
         }
 
         if ("RETURN_OUTBOUND".equals(outbound.getOutboundType())) {
@@ -764,14 +782,9 @@ public class DeliveryTransferService {
                 !task.getCustomerId().equals(carton.getCustomerId()) || !expectedMarks.contains(carton.getCartonMark())
                     || !"OUTBOUND_PENDING".equals(carton.getStatus())))
                 throw conflict("托盘内容或出库预留已变化，请刷新核对");
-            DeliveryResponses.PdaTask result = taskResult(outbound, task);
-            for (OutboundPalletItem item : palletItems.stream().sorted(Comparator.comparing(OutboundPalletItem::getId)).toList()) {
-                if (value(item.getPickedPackageCount()) >= value(item.getPackageCount())) continue;
-                result = pickResolved(boundWarehouseId, operatorId, code,
-                    new DeliveryRequests.PdaPick(item.getId(), null, 1L,
-                        childKey(request.idempotencyKey(), "RETURN:" + item.getId()), List.of(item.getCartonMarks())), true);
-            }
-            return result;
+            return palletItems.stream().filter(item -> value(item.getPickedPackageCount()) < value(item.getPackageCount()))
+                .sorted(Comparator.comparing(OutboundPalletItem::getId)).map(item -> new DeliveryRequests.PdaPick(item.getId(), null, 1L,
+                    childKey(request.idempotencyKey(), "RETURN:" + item.getId()), List.of(item.getCartonMarks()))) .toList();
         }
 
         List<PalletPickPlan> plans = new ArrayList<>();
@@ -798,13 +811,8 @@ public class DeliveryTransferService {
             if (remaining > 0) throw conflict("托盘可用库存不足，整托拣货未执行：" + palletCode);
         }
 
-        DeliveryResponses.PdaTask result = taskResult(outbound, task);
-        for (PalletPickPlan plan : plans) {
-            String operationId = palletPickOperationId(request.idempotencyKey(), code, palletCode, plan);
-            result = pdaPick(boundWarehouseId, operatorId, code, new DeliveryRequests.PdaPick(
-                plan.itemId(), plan.positionId(), plan.packages(), operationId, plan.cartonMarks()));
-        }
-        return result;
+        return plans.stream().map(plan -> new DeliveryRequests.PdaPick(plan.itemId(), plan.positionId(), plan.packages(),
+            palletPickOperationId(request.idempotencyKey(), code, palletCode, plan), plan.cartonMarks())).toList();
     }
 
     @Transactional
@@ -1012,7 +1020,7 @@ public class DeliveryTransferService {
             delivery.setUpdatedAt(now); cancellations.save(delivery);
         }
         OutboundPdaTask task = cancellations.task(outbound);
-        if (task != null) { task.setStatus("CANCELLED"); task.setUpdatedAt(now); cancellations.save(task); }
+        if (task != null) { storageRent.cancelExecution("OUTBOUND",task.getTaskNo()); task.setStatus("CANCELLED"); task.setUpdatedAt(now); cancellations.save(task); }
         outbound.setStatus("CANCELLED"); outbound.setUpdatedAt(now); cancellations.save(outbound);
         for (OutboundPalletItem item : outboundItems) { item.setStatus("CANCELLED"); cancellations.save(item); }
         if ("WAREHOUSE_TRANSFER_OUTBOUND".equals(outbound.getOutboundType())) {

lastleg-service/src/main/java/com/baiyue/lastleg/delivery/service/DispatchDeliveryFees.java

@@ -116,17 +116,13 @@ public class DispatchDeliveryFees {
             if (fee==null || blank(fee.feeType()) || !SERVICES.contains(fee.feeType()) || blank(fee.direction()) || !Set.of("RECEIVABLE","PAYABLE").contains(fee.direction())
                 || blank(fee.currency()) || !Set.of("CNY","USD").contains(fee.currency()) || blank(fee.feeName()) || fee.amount()==null || fee.amount().signum()<=0)
                 throw conflict("派送费用类型、方向、币种或金额不合法");
+            if ("RECEIVABLE".equals(fee.direction())) throw conflict("请到海外费用登记并审核应收费用");
             if (!seen.add(fee.direction()+":"+fee.feeType())) throw conflict("同组同方向同费用不得重复登记");
             if ("RECEIVABLE".equals(fee.direction()) && group.cargo().stream().allMatch(c->covered(c,fee.feeType(),evidence,freight)))
                 throw conflict("本组该服务已全部覆盖，不得重复登记应收");
         }
-        var required=new HashSet<String>(); required.add("DELIVERY_FEE");
-        if (Set.of("FLOOR","MIXED").contains(input.loadingType())) required.add("LOADING_FEE");
-        if ("BUY_APPOINTMENT".equals(input.appointmentAccount())) {
-            if (blank(input.sellerName())) throw conflict("买约须填写卖家名称");required.add("APPOINTMENT_FEE");
-        }
-        for (var code:required) if (group.cargo().stream().anyMatch(c->!covered(c,code,evidence,freight)) && !seen.contains("RECEIVABLE:"+code))
-            throw conflict("本组尚有未覆盖的服务费用，请核对" );
+        if ("BUY_APPOINTMENT".equals(input.appointmentAccount()) && blank(input.sellerName()))
+            throw conflict("买约须填写卖家名称");
     }
 
     /** 子单及来源锁已经收齐后才核对原费用撤销状态，不能重复收费。 */
@@ -134,7 +130,7 @@ public class DispatchDeliveryFees {
         fees.requireNoActiveDeliveryReceivables(customerId,freight.priorInboundCodes());
     }
 
-    /** 费用与子单同事务保存，只向真实客户目的地发布一次正数来源。 */
+    /** 外接报价保留记录；只发布供应商应付，客户应收走人工审核。 */
     public void publish(Context context,Group group,ArrangeGroup input,DeliveryOrder delivery,
         DeliveryFeeCoverageModels.Evidence evidence,FleetBookingFreight.Preview freight,String operatorId,String arrangementKey) {
         var now=LocalDateTime.now();
@@ -144,12 +140,10 @@ public class DispatchDeliveryFees {
             operation.setOperatorId(operatorId);operation.setOperationNode("CONFIRM_EXTERNAL_FREIGHT");
             operation.setResult("外接预订 "+quote.bookingNo()+"；实收确认版本 "+quote.recordVersion()+"；约定运费 "+quote.currency()+" "+quote.amount().toPlainString());
             operation.setCreatedAt(now);repository.operation(operation);
-            if (quote.amount().signum()==0) continue;
-            fees.publishApproved(operatorId,groups.hash(List.of(arrangementKey,group.key(),quote.bookingNo(),"FREIGHT")),
-                save(group,delivery,null,"DELIVERY_FEE","外接约定运费", "RECEIVABLE",quote.currency(),quote.amount(),
-                    quote.quantity(),quote.quantityUnit(),quote.unitPrice(),null,quote.inboundCode()));
+            // 约定运费只保留商业记录，应收由海外费用人工登记审核。
         }
         for (var fee:input.fees()==null?List.<FeeItem>of():input.fees()) {
+            if (!"PAYABLE".equals(fee.direction())) throw conflict("请到海外费用登记并审核应收费用");
             var charged=group.cargo().stream().filter(c->!"RECEIVABLE".equals(fee.direction())||!covered(c,fee.feeType(),evidence,freight)).toList();
             var orders=charged.stream().map(CargoLine::orderId).filter(Objects::nonNull).distinct().toList();
             var inbound=charged.stream().map(CargoLine::inboundCode).filter(Objects::nonNull).distinct().toList();
@@ -164,7 +158,7 @@ public class DispatchDeliveryFees {
         String direction,String currency,BigDecimal amount,BigDecimal quantity,String unit,BigDecimal unitPrice,FeeItem input,String inboundCode) {
         return new OverseasFeeSourceDtos.SaveRequest(group.customerId(),group.customerName(),"OVERSEAS_DELIVERY_FEE","DELIVERY_ORDER",
             delivery.getId(),delivery.getDeliveryNo(),orderId,null,inboundCode,null,null,null,Long.valueOf(delivery.getOverseasWarehouseId()),
-            code,name,direction,input==null?null:input.supplierId(),input==null?null:input.supplierName(),input==null?null:input.supplierCategory(),
+            code,name, null,direction,input==null?null:input.supplierId(),input==null?null:input.supplierName(),input==null?null:input.supplierCategory(),
             input==null?null:input.settlementMode(),input==null||input.paidAt()==null?null:LocalDateTime.ofInstant(input.paidAt(),ZoneId.systemDefault()),
             input==null?null:input.paymentMethod(),input==null?null:input.paymentReferenceNo(),input==null?null:input.paymentVoucherFileIds(),
             LocalDate.now(),currency,amount,quantity,unit,unitPrice,input==null?null:input.periodStart(),input==null?null:input.periodEnd());

lastleg-service/src/main/java/com/baiyue/lastleg/discard/pda/dto/PdaCargoDiscardDtos.java

@@ -16,8 +16,12 @@ public final class PdaCargoDiscardDtos {
     public record ActualLine(@NotNull Long itemId, @PositiveOrZero int actualPackages) { }
     public record Confirm(@NotEmpty List<@Valid ActualLine> lines,
                           @NotEmpty @Size(max = 20) List<@NotNull @jakarta.validation.constraints.Positive Long> photoFileIds,
-                          List<@NotBlank String> scannedCartonMarks, Boolean confirmAllCartons) {
-        public Confirm(List<ActualLine> lines, List<Long> photoFileIds) { this(lines, photoFileIds, null, false); }
+                          List<@NotBlank String> scannedCartonMarks, Boolean confirmAllCartons,
+                          @NotBlank @Size(max=255) String idempotencyKey) {
+        /** 兼容已有调用，正式 PDA 必须提交扫码幂等键。 */
+        public Confirm(List<ActualLine> lines,List<Long> photos,List<String> marks,Boolean all){this(lines,photos,marks,all,null);}
+        /** 兼容已有内部照片确认调用。 */
+        public Confirm(List<ActualLine> lines, List<Long> photoFileIds) { this(lines, photoFileIds, null, false,null); }
     }
     /** 明细数量按来源标识单位：退货库存为件，其余箱级库存为箱。 */
     public record Sku(Long itemId, String skuCode, String productName, int plannedPackages,

lastleg-service/src/main/java/com/baiyue/lastleg/discard/pda/service/PdaCargoDiscardService.java

@@ -23,6 +23,7 @@ public class PdaCargoDiscardService {
     @Resource private CargoDiscardInventoryAdjustmentService adjustments;
     @Resource private CargoDiscardService discardService;
     @Resource private com.baiyue.lastleg.discard.service.CargoDiscardStockService stockService;
+    @Resource private com.baiyue.lastleg.storagerent.service.StorageRentService storageRent;
 
     /** 只读取绑定仓已审核申请的实际托盘任务。 */
     public List<PdaCargoDiscardDtos.PalletTask> tasks(PdaWarehouseIdentity identity) {
@@ -95,6 +96,9 @@ public class PdaCargoDiscardService {
         // 已完成托盘保持原始实点结果，终态重放不得再次扣减或释放库存。
         if (palletItems.stream().allMatch(item -> "COMPLETED".equals(item.getPdaStatus()))) return task;
         if (terminal) throw conflict("废弃终态不能执行未完成托盘");
+        storageRent.consume(String.valueOf(identity.overseasWarehouseId()),new com.baiyue.lastleg.storagerent.dto.StorageRentDtos.PrepareRequest(
+            "DISCARD",discardNo,null,null,null,null,palletNo,request.idempotencyKey(),null,null,null,
+            request.lines(),request.photoFileIds(),request.scannedCartonMarks(),request.confirmAllCartons()));
         LocalDateTime now = LocalDateTime.now();
         for (CargoDiscardItem item : palletItems) {
             if ("COMPLETED".equals(item.getPdaStatus())) {

lastleg-service/src/main/java/com/baiyue/lastleg/discard/service/CargoDiscardService.java

@@ -50,6 +50,7 @@ import java.util.Set;
 
 @Service
 public class CargoDiscardService {
+    @jakarta.annotation.Resource private com.baiyue.lastleg.storagerent.service.StorageRentService storageRent;
     @Resource private CargoDiscardStatisticsService statisticsService;
     @Resource private com.baiyue.lastleg.discard.repository.CargoDiscardQuantityRepository quantities;
     @Resource private com.baiyue.lastleg.service.LastlegOrderNoGenerator orderNoGenerator;
@@ -389,6 +390,7 @@ public class CargoDiscardService {
         release(customerId, application, links, items.listApplication(customerId, application.getId()));
         LocalDateTime at = now();
         String from = application.getStatus();
+        storageRent.cancelExecution("DISCARD",discardNo);
         application.setStatus(CANCELLED); application.setReviewedBy(platform ? operatorId : application.getReviewedBy());
         application.setReviewRemark(platform ? "平台取消" : application.getReviewRemark());
         application.setUpdatedAt(at); applications.updateById(application);

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

@@ -53,6 +53,18 @@ public class DispatchAggregateController {
     public ApiResponse<com.baiyue.lastleg.dispatch.port.DispatchWorkModels.Items> items(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo) {
         return ApiResponse.success(service.items(DispatchActorFactory.platform(user),dispatchNo));
     }
+    /** 本车货物逐票读取正式预约选项及当前分配。 */
+    @GetMapping("/{dispatchNo}/appointment-allocations")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")
+    public ApiResponse<com.baiyue.lastleg.dispatch.port.DispatchWorkModels.AppointmentAllocations> appointmentAllocations(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo) {
+        return ApiResponse.success(service.appointmentAllocations(DispatchActorFactory.platform(user),dispatchNo));
+    }
+    /** 原车版本化关联正式预约，不新建排车或修改库存。 */
+    @PutMapping("/{dispatchNo}/appointment-allocations")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<CommandResult> appointmentAllocations(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@RequestBody com.baiyue.lastleg.dispatch.port.DispatchWorkModels.AppointmentAllocationCommand request) {
+        return ApiResponse.success(service.saveAppointmentAllocations(DispatchActorFactory.platform(user),dispatchNo,request));
+    }
     /** 读取实际起点和卸货顺序。 */
     @GetMapping("/{dispatchNo}/route")
     @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")

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

@@ -10,7 +10,7 @@ public class DispatchAggregate {
     private String dispatchNo;
     private String taskType;
     /** 是否向内部散板需求池发布本车余位。 */
-    private Boolean publishLooseboardDemand = true;
+    private Boolean publishLooseboardDemand = false;
     private Long tripId;
     private String overseasWarehouseId;
     private String overseasWarehouseCode;

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

@@ -19,7 +19,20 @@ public interface DispatchAggregateMapper {
           OR EXISTS(SELECT 1 FROM ll_dispatch_truck_task t WHERE t.dispatch_no=d.dispatch_no AND t.customer_id=#{q.customerId})
           OR EXISTS(SELECT 1 FROM ll_fleet_pickup_task p JOIN ll_fleet_trip f ON f.trip_no=p.trip_no WHERE f.id=d.trip_id AND p.customer_id=#{q.customerId})
         )</if>
-        <if test='q.fbaAppointmentNo != null'> AND EXISTS(SELECT 1 FROM ll_dispatch_appointment_allocation a JOIN ll_inbound_fba_appointment ap ON a.batch_key=CONCAT('FBA_APPOINTMENT:',ap.id) WHERE a.dispatch_id=d.id AND ap.confirmation_no=#{q.fbaAppointmentNo})</if>
+        <if test='q.fbaAppointmentNo != null'> AND (
+          EXISTS(SELECT 1 FROM ll_dispatch_item i WHERE i.dispatch_order_id=d.id AND i.destination_type='FBA'
+            AND JSON_CONTAINS(COALESCE(JSON_EXTRACT(d.resources_json,'$.maintenance.destinationAppointments'),'[]'),
+              JSON_OBJECT('destinationKey',CONCAT('FBA:',UPPER(TRIM(COALESCE(NULLIF(i.destination_warehouse_code,''),i.fba_warehouse_code)))),'appointmentNo',#{q.fbaAppointmentNo}))=1)
+          OR EXISTS(SELECT 1 FROM ll_dispatch_appointment_allocation a
+            WHERE a.dispatch_id=d.id AND a.batch_key LIKE 'FBA_APPOINTMENT:%' AND
+        """ + DispatchReceivingSql.CONFIRMATION_NO + """
+            =#{q.fbaAppointmentNo}
+            AND NOT EXISTS(SELECT 1 FROM JSON_TABLE(
+              COALESCE(JSON_EXTRACT(d.resources_json,'$.maintenance.destinationAppointments'),'[]'),
+              '$[*]' COLUMNS(destination_key VARCHAR(256) PATH '$.destinationKey',
+                appointment_no VARCHAR(128) PATH '$.appointmentNo' NULL ON EMPTY)) saved
+              WHERE saved.destination_key=a.destination_key AND NULLIF(TRIM(saved.appointment_no),'') IS NOT NULL))
+        )</if>
         """;
     String REVIEW_DISPATCH = "CASE d.review_state WHEN 'DRAFT' THEN 'NOT_SUBMITTED' WHEN 'DISPATCH_PENDING' THEN 'PENDING' WHEN 'DISPATCH_REJECTED' THEN 'REJECTED' ELSE 'APPROVED' END";
     String REVIEW_LOADING = "CASE d.review_state WHEN 'LOADING_PENDING' THEN 'PENDING' WHEN 'LOADING_REJECTED' THEN 'REJECTED' WHEN 'APPROVED' THEN 'APPROVED' ELSE 'NOT_SUBMITTED' END";
@@ -109,7 +122,7 @@ public interface DispatchAggregateMapper {
           estimated_arrival_at=#{r.estimatedArrivalAt},remark=#{r.remark},loading_completed_at=#{r.loadingCompletedAt},
           loading_completion_hash=#{r.loadingCompletionHash},loading_confirmation_json=#{r.loadingConfirmationJson},arrangement_key=#{r.arrangementKey},
           arrangement_business_hash=#{r.arrangementBusinessHash},departed_at=#{r.departedAt},
-          delivery_completed_at=#{r.deliveryCompletedAt},package_count=#{r.packageCount},pallet_count=#{r.palletCount},picked_package_count=#{r.pickedPackageCount},
+          delivery_completed_at=#{r.deliveryCompletedAt},item_count=#{r.itemCount},route=#{r.route},package_count=#{r.packageCount},pallet_count=#{r.palletCount},picked_package_count=#{r.pickedPackageCount},
           shipped_package_count=#{r.shippedPackageCount},updated_at=#{r.updatedAt}
         WHERE id=#{r.id} AND record_version=#{version}
         """)