一件代发拣货

# Conflicts:
#	deploy/sql/头程数据库统一增量-MySQL8.sql
#	scripts/admin-test-env-modules/phase3-container-loading.mjs
#	scripts/admin-test-env-modules/phase3-loading.mjs

.gitlab-ci.yml

@@ -41,6 +41,27 @@ OpenAPI有效性:
       - "**/target/spotbugs*.xml"
       - "**/target/site/spotbugs.html"
 
+质量摘要:
+  stage: verify
+  image: node:22-alpine
+  cache: []
+  allow_failure: true
+  needs:
+    - job: OpenAPI有效性
+      artifacts: false
+    - job: 校验与测试
+      artifacts: true
+    - job: 静态分析报告
+      artifacts: true
+  script:
+    - node --test scripts/java-quality-summary.test.mjs
+    - node scripts/java-quality-summary.mjs --output target/java-quality-summary.json --require-jacoco --require-spotbugs
+  artifacts:
+    when: always
+    expire_in: 7 days
+    paths:
+      - target/java-quality-summary.json
+
 校验与测试:
   stage: verify
   script:
@@ -76,7 +97,6 @@ OpenAPI有效性:
       - finance/target/*.jar
       - warehouse/target/*.jar
       - warehouse-overseas-service/target/*.jar
-      - overseas-security-service/target/*.jar
       - lastleg-service/target/*.jar
       - file/target/*.jar
       - print/target/*.jar

AGENTS.md

@@ -11,7 +11,7 @@
 
 - 当前产品只有“平台—客户”两级。`tenant_id=0` 是平台技术作用域；`tenant_id>0` 是客户隔离键，不得新增租户切换、租户选择或租户级 RBAC。
 - 公共仓库、往来单位、快递、托盘、库位统一归属 `tenant_id=0`；订单、文件、费用等客户数据按客户 `tenant_id>0` 隔离。不得跨库 Join 或信任客户端客户 ID。
-- 国内订单交易状态归 `order`，头程履约/入库状态归 `firstleg`，财务账期、账单、收款、成本与核销归 `finance`，国内仓储资源归 `warehouse`；海外尾程订单、入仓计划、库存业务与海外本土业务归 `lastleg-service`，海外仓库/库位/托盘资源归 `warehouse-overseas-service`，海外公网入口归 `gateway-overseas`。文件对象归 `file`，第三方适配归 `integration-service`；跨服务通过内部客户端、DTO、事件和服务令牌协作。
+- 国内订单交易状态归 `order`，头程履约/入库状态归 `firstleg`，财务账期、账单、收款、成本与核销归 `finance`；全部仓库 ID、类型、状态、地址和能力主档归国内 `warehouse`，海外 `warehouse-overseas-service` 只维护引用同一国内 warehouseId 的库位、托盘和资源锁。海外尾程订单、入仓计划、库存业务与海外本土业务归 `lastleg-service`，海外公网入口归 `gateway-overseas`。文件对象归 `file`，第三方适配归 `integration-service`；跨服务通过内部客户端、DTO、事件和服务令牌协作。
 - 普通业务成功/失败使用 HTTP 200 + body `code`（成功为字符串 `"200"`）；认证、基础设施和网关拒绝可使用真实 401/403/503。
 
 ## 服务路由（按关键词定位）
@@ -20,9 +20,11 @@
 |---|---|---|
 | 登录、Token、密码、注册 | `auth/` | `auth/AGENTS.md` |
 | 客户档案、成员、审核、RBAC、授权快照 | `iam/` | `iam/AGENTS.md` |
+| 客户建档默认尺寸初始化与补偿 | `iam/`、`firstleg/` | IAM `CustomerDimensionRuleInitializationService` 持久化意图、`CustomerDimensionInitializationRelay` 后台投递；Firstleg 内部入口 `/internal/firstleg/v1/customer-dimension-configs/defaults`，未 `READY` 不得审核通过 |
 | 消息中心、站内通知、消息模板、收件箱 | `iam/` | `iam/AGENTS.md`，再按 `src/main/java/com/baiyue/iam/notification/` 定位；业务事件生产者回到所属服务 |
 | 订单、货物、快照、状态、幂等、Outbox | `order/` | `order/AGENTS.md` |
 | 履约分配、入库、测量、审核、FBA 计费 | `firstleg/` | `firstleg/AGENTS.md` |
+| Firstleg 内部模块化与依赖基线 | `firstleg/` | `firstleg/docs/firstleg-internal-modularization-baseline.md`、`firstleg/scripts/analyze-firstleg-dependencies.mjs`；价格簿查询和客户统计按端口/适配器切片，不改变服务与数据库边界 |
 | 分柜、柜次、智能排柜、预装/装柜清单、PDA | `firstleg/` | `firstleg/AGENTS.md`，再按 `split/`、`loading/`、`outbound/` 定位 |
 | 智能装柜入仓码候选与箱数分配 | `firstleg/` | `controller/PlatformSmartLoadingController.java` 的 `/inbound-candidates`、`/plans/{planId}/inbound-assignments`，业务编排 `service/SmartLoadingService.java` |
 | 订舱、船期、拖车、报关 | `firstleg/` | `oceanbooking/`、`portschedule/`、`outbound/dispatch/`、`customs/` |
@@ -36,14 +38,15 @@
 | 路由、CORS、JWT 入口、访问域 | `gateway/` | `gateway/AGENTS.md` |
 | 百度/Amazon/OCR/第三方适配 | `integration-service/` | `integration-service/AGENTS.md` |
 | 海外 API 路由、海外 Token、Audience/JWKS | `gateway-overseas/` | `gateway-overseas/AGENTS.md` |
-| 海外 IAM 状态与权限版本投影 | `overseas-security-service/` | `overseas-security-service/AGENTS.md`；消费三类 IAM 安全事件并为海外 Gateway 提供内部 fail-closed 校验 |
+| 海外 IAM 状态与权限版本投影 | `lastleg-service/security/` | `lastleg-service/AGENTS.md`；内部入口 `/internal/lastleg/security/v1/events`、`/validate`；消费三类 IAM 安全事件并为海外 Gateway 提供 fail-closed 校验，投影表归 `baiyue_lastleg` |
 | 尾程订单、海外入仓计划、换标、库存、采购、本土卡车 | `lastleg-service/` | `lastleg-service/AGENTS.md`，再按 `inboundplan/`、`relabel/`、`inventory/`、`procurement/`、`trucking/` 定位 |
 | 海外入仓分页、FBA 预约、PDA 柜号签收与入仓 | `lastleg-service/` | 平台入口 `inboundplan/controller/InboundPlanController.java`、`InboundPlanQueryMapper.java`、`InboundFbaAppointmentService.java`；PDA 公网入口 `inboundplan/pda/controller/ReceivingContainerController.java`、`ReceivingContainerService.java`，旧 planNo/allocationId Controller 已移除 |
 | 海外仓排车查询、候选与智能预排 | `lastleg-service/` | `dispatch/controller/DispatchQueryController.java`、`SmartDispatchController.java`；草稿柜、托盘锁和预排归 `dispatch/`，只读排车和预排创建独立开关，不自动开放编辑、取消、发车、PDA 出库或派送 |
 | 客户海外仓贴标、转运、废弃与退货换标 | `lastleg-service/` | `relabel/`、`transfer/`、`discard/` 的 Merchant Controller/Service；Client 消费端 `../apps/client-web/src/modules/overseas-warehouse/`，统一经 `gateway-overseas/` |
-| 海外仓 PDA 盘点、移库、托盘、换标与查询 | `lastleg-service/`、`warehouse-overseas-service/` | Lastleg `pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`；契约 `lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml`；物理库位/托盘调用 `warehouse-overseas-service/`，设备端入口是否开放以 `../apps/pda-overseas-uniapp/AGENTS.md` 为准 |
+| 海外仓 PDA 盘点、移库、托盘、换标与查询 | `lastleg-service/`、`warehouse-overseas-service/` | Lastleg `pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`；契约 `lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml`；物理托盘流转与补偿进入 Warehouse `InternalPdaPalletTransitionController`，设备端入口是否开放以 `../apps/pda-overseas-uniapp/AGENTS.md` 为准 |
 | 国内船节点向海外接柜门禁事件 | `firstleg/`、`common-event-contract/`、`lastleg-service/` | Firstleg `portschedule/service/CarrierScheduleNodeOutboxService.java` 发布 `FirstLegContainerShippingNodeRecordedV1`；Lastleg `shipping/service/ContainerShippingNodeConsumer.java` 单调消费，只有实际 `PICKUP_READY` 及以后节点允许海外 PDA 候选进入可收货 |
-| 海外仓库、海外库位、海外托盘、资源锁 | `warehouse-overseas-service/` | `warehouse-overseas-service/AGENTS.md` |
+| 海外仓库目录、海外库位、海外托盘、资源锁 | 国内仓库目录归 `warehouse/`，海外资源归 `warehouse-overseas-service/` | `warehouse/AGENTS.md`、`warehouse-overseas-service/AGENTS.md`；海外库只保存国内 warehouseId 引用 |
+| Lastleg 内部模块化与依赖基线 | `lastleg-service/` | `lastleg-service/docs/lastleg-internal-modularization-baseline.md`、`lastleg-service/scripts/analyze-lastleg-dependencies.mjs`；只用于约束服务内部依赖，不改变服务和数据库边界 |
 | PDF 标签、审计、跨区双向事件 | `print/`、`audit-service/`、`event-bridge-service/` | 事件模型先读 `common-event-contract/AGENTS.md`；国内真实生产验收 `firstleg/.../TaillegRealProducerAcceptanceTest.java`、海外真实消费验收 `lastleg-service/.../TaillegRealConsumerAcceptanceTest.java`；可靠投递与 CN/OVERSEAS 目标路由读 `event-bridge-service/AGENTS.md` |
 
 ## 公共模块快速索引
@@ -52,7 +55,7 @@
 |---|---|
 | 公共依赖版本 | `platform-bom/pom.xml`；统一管理公共组件版本，不放业务实现 |
 | 通用响应、分页、异常、基础实体与导出契约 | `common-core/`；从 `ApiResponse.java`、`PageResult.java`、`BizException.java`、`ExportContracts.java` 定位 |
-| Web 异常、请求关联 ID、Long ID 序列化 | `common-web/`；从 `GlobalExceptionHandler.java`、`CorrelationIdFilter.java`、`LongIdJacksonConfiguration.java` 定位 |
+| Web 异常、请求关联/Trace、同步出站传播、Long ID 序列化 | `common-web/`；从 `GlobalExceptionHandler.java`、`CorrelationIdFilter.java`、`TraceParent.java`、`FeignTraceRequestInterceptor.java`、`RestClientTraceInterceptor.java`、`LongIdJacksonConfiguration.java` 定位 |
 | JWT、JWKS、会话校验与认证用户 | `common-security/`；从 `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java`、`AccessTokenSessionValidator.java` 定位 |
 | Springdoc/OpenAPI 自动配置 | `common-openapi/`；从 `BaiyueOpenApiAutoConfiguration.java`、`OpenApiProperties.java` 定位 |
 | 业务审计注解、脱敏、Outbox 与投递 | `common-audit/`；从 `BusinessAudit.java`、`BusinessAuditAspect.java`、`SensitiveDataSanitizer.java`、`AuditOutboxPublisher.java` 定位 |
@@ -78,9 +81,10 @@
 - 供应商查询接口固定只使用 `platform:supplier:list`；IAM 中 `platform:supplier:list` 是正式菜单资源，`platform:supplier:view` 必须停用/移除，不得重新提升或兼容。
 - 权限语义变更必须同步 Controller `@PreAuthorize`、OpenAPI、模块权限 SQL、IAM 菜单资源、统一增量脚本和契约测试。并行模块任务不得覆盖菜单与权限总控已写入共享 SQL 或权限契约的改动。
 - 数据库只访问所属服务库。模块表结构位于 `<module>/src/main/resources/db/`；当前开发阶段直接更新最新模块基线和 `deploy/sql/头程数据库统一增量-MySQL8.sql`，不为历史开发数据新增兼容迁移。已有名称含 `migration` 的脚本仅作现有结构来源和开发追溯，部署说明见 `deploy/sql/README.md`。
+- 后端同样遵守根指引中的“开发数据和上传文件可丢弃”边界：不得为现有开发库孤儿文件、旧文件归属或历史部分失败新增删除补偿接口、兼容复用、回填或清理链路；只修复当前正式上传与持久化路径，既有开发文件由人工重新上传。
 - 通用配置在 `config/nacos/{local,cn}/`；服务日志、上传文件、`target/`、`reports/` 不属于源码。
 - Java 签名变更的最低编译门禁是 `mvn -pl <module> -am test-compile`，它必须在部署前完成并覆盖测试源码；有行为变化时继续运行 `mvn -pl <module> -am test`。`-DskipTests` 可跳过测试执行但仍须保留测试编译，`-Dmaven.test.skip=true` 会跳过测试编译，不得作为签名变更的交付验证。全量验证仍使用 `mvn -DskipTests validate`、`mvn test`；不要在本地启动 Java/Nacos/数据库，除非用户明确要求。
-- `AGENTS.md` 索引维护完成后运行 `./scripts/agents-index-contract.ps1`；脚本只读源码目录和指定指引，验证根快速表唯一性、部署单元、Client active 路由、海外 Gateway 覆盖、模块覆盖、关键入口与排除目录，不访问 HTTP、数据库或部署环境。
+- `AGENTS.md` 索引维护完成后运行 `./scripts/agents-index-contract.ps1`；脚本只读源码目录和指定指引，验证根快速表唯一性、部署单元、Client active 路由、四期范围漂移、仓库主档唯一权威、订舱关联候选与柜量语义、整柜出仓与船节点单调性、海外 Gateway 覆盖、PDA 运行配置/独立更新/语言预留、人工分段验收链、Lastleg 海外安全投影、同步 Trace、模块覆盖、关键入口与排除目录，不访问 HTTP、数据库或部署环境。
 - 单服务镜像构建/部署从 `Jenkinsfile.service`、`deploy/docker/Dockerfile`、`deploy/scripts/deploy-built-service.sh` 进入；新镜像启动失败或健康检查失败时只允许回滚到同服务先前镜像，并保持任务失败，离线合同见 `scripts/deploy-built-service-rollback.test.mjs`。实际部署仍须当前对话明确授权。
 
 ## 全量 HTTP 验收脚本路由
@@ -89,6 +93,7 @@
 - Admin 总入口默认按模块列表覆盖平台全链路；需要定位单个业务时使用 `--modules <name>`，模块名称和静态合同先查 `scripts/admin-test-env-modules/README.md`。
 - 这些脚本会创建、更新或最终停用测试数据，必须在当前对话明确授权测试环境验收后执行，并保存 JSON 报告；未授权不得请求 Gateway。
 - 后端 Maven、前端 `pnpm test/typecheck`、PDA `node --test` 和数据库 Dry-run 都是本地质量检查，不属于全量 HTTP 验收。
+- Java 模块、OpenAPI 覆盖、JaCoCo 与 SpotBugs 聚合摘要使用 `node scripts/java-quality-summary.mjs`；默认仅报告存量缺口，是否阻断由显式 `--require-*` 参数决定，输出位于 `target/` 时不得作为业务事实或提交物。
 - HTTP 全量通过后，才进入 Admin/Client 真实页面调用、浏览器样式和 PDA 页面/设备验收；自动化 HTTP 通过不代表视觉验收完成。
 
 ## 阶段文档入口

Jenkinsfile

@@ -1,6 +1,6 @@
 def serviceModules = [
     'gateway', 'gateway-overseas', 'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
-    'integration-service', 'lastleg-service', 'warehouse-overseas-service', 'overseas-security-service', 'event-bridge-service', 'audit-service'
+    'integration-service', 'lastleg-service', 'warehouse-overseas-service', 'event-bridge-service', 'audit-service'
 ]
 
 def serviceCheckboxes = [
@@ -17,21 +17,81 @@ def serviceCheckboxes = [
     'integration-service': 'SERVICE_INTEGRATION',
     'lastleg-service': 'SERVICE_LASTLEG',
     'warehouse-overseas-service': 'SERVICE_WAREHOUSE_OVERSEAS',
-    'overseas-security-service': 'SERVICE_OVERSEAS_SECURITY',
     'event-bridge-service': 'SERVICE_EVENT_BRIDGE',
     'audit-service': 'SERVICE_AUDIT'
 ]
 
-def commonPaths = [
-    'pom.xml', 'platform-bom/', 'common-core/', 'common-web/', 'common-security/',
-    'common-openapi/', 'common-audit/', 'common-event-contract/', 'Jenkinsfile',
-    'Jenkinsfile.service', 'deploy/'
+def fullRebuildPaths = [
+    'pom.xml', 'platform-bom/', 'common-core/', 'deploy/docker/',
+    'deploy/docker-compose.yml', 'deploy/service-map.yml'
+]
+
+def commonPathServices = [
+    'common-web/': [
+        'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
+        'integration-service', 'lastleg-service', 'warehouse-overseas-service',
+        'event-bridge-service', 'audit-service'
+    ],
+    'common-security/': [
+        'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file',
+        'lastleg-service', 'warehouse-overseas-service', 'audit-service'
+    ],
+    'common-openapi/': [
+        'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
+        'integration-service', 'lastleg-service', 'warehouse-overseas-service',
+        'event-bridge-service', 'audit-service'
+    ],
+    'common-audit/': [
+        'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file',
+        'warehouse-overseas-service', 'audit-service'
+    ],
+    'common-event-contract/': [
+        'firstleg', 'iam', 'lastleg-service', 'event-bridge-service'
+    ],
+    'deploy/docker-compose.overseas.yml': [
+        'gateway-overseas', 'lastleg-service', 'warehouse-overseas-service', 'event-bridge-service'
+    ],
+    'deploy/docker-compose.audit.yml': ['audit-service'],
+    'deploy/docker-compose.rocketmq.yml': ['event-bridge-service']
 ]
 
 def databaseMigrationPaths = ['deploy/sql/']
 
 def downstreamResults = [:]
 
+def parseAutoBuildState(String description, List<String> allowedServices) {
+    String marker = ' | RESULTS'
+    if (!description?.startsWith('AUTO ') || !description.contains(marker)) return null
+    int markerIndex = description.indexOf(marker)
+    String commit = description.substring('AUTO '.length(), markerIndex).trim()
+    if (!(commit ==~ /[0-9a-fA-F]{7,40}/)) return null
+    String summary = description.substring(markerIndex + marker.length()).trim()
+    List<String> failedServices = []
+    if (summary) {
+        summary.split(',').collect { it.trim() }.findAll { it }.each { item ->
+            int separator = item.indexOf('=')
+            if (separator > 0) {
+                String service = item.substring(0, separator).trim()
+                String result = item.substring(separator + 1).trim()
+                if (allowedServices.contains(service) && result != 'SUCCESS') failedServices << service
+            }
+        }
+    }
+    return [commit: commit, failedServices: failedServices.unique()]
+}
+
+def previousAutoBuildState(def previousBuild, List<String> allowedServices) {
+    def candidate = previousBuild
+    int inspected = 0
+    while (candidate != null && inspected < 30) {
+        def state = parseAutoBuildState(candidate.description, allowedServices)
+        if (state != null && ['SUCCESS', 'UNSTABLE'].contains(candidate.result)) return state
+        candidate = candidate.previousBuild
+        inspected++
+    }
+    return null
+}
+
 def environmentChoicesForJob(String jobBaseName) {
     return jobBaseName == 'backend-java-dev'
         ? ['development', 'test', 'staging', 'production']
@@ -69,7 +129,6 @@ pipeline {
         booleanParam(name: 'SERVICE_INTEGRATION', defaultValue: false, description: '第三方集成服务（integration-service）')
         booleanParam(name: 'SERVICE_LASTLEG', defaultValue: false, description: '海外尾程与入仓服务（lastleg-service）')
         booleanParam(name: 'SERVICE_WAREHOUSE_OVERSEAS', defaultValue: false, description: '海外仓资源服务（warehouse-overseas-service）')
-        booleanParam(name: 'SERVICE_OVERSEAS_SECURITY', defaultValue: false, description: '海外IAM安全投影服务（overseas-security-service）')
         booleanParam(name: 'SERVICE_EVENT_BRIDGE', defaultValue: false, description: '跨区域事件桥（event-bridge-service；默认同时部署国内和海外实例）')
         choice(name: 'EVENT_BRIDGE_REGION', choices: ['BOTH', 'CN', 'OVERSEAS'], description: 'BOTH 同时部署国内和海外实例；CN/OVERSEAS 用于单区故障重跑')
         booleanParam(name: 'SERVICE_AUDIT', defaultValue: false, description: '审计服务（audit-service）')
@@ -114,6 +173,8 @@ pipeline {
                         error('生产环境禁止跳过测试')
                     }
 
+                    env.SOURCE_COMMIT = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
+                    env.IMAGE_TAG = sh(script: 'git rev-parse --short=12 HEAD', returnStdout: true).trim()
                     List selected = []
                     if (params.BUILD_MODE == 'ALL') {
                         selected = serviceModules
@@ -125,9 +186,17 @@ pipeline {
                             error('SELECT 模式至少需要勾选一个服务')
                         }
                     } else {
-                        String base = env.GIT_PREVIOUS_SUCCESSFUL_COMMIT?.trim()
+                        def autoState = previousAutoBuildState(currentBuild.previousBuild, serviceModules)
+                        String base = autoState?.commit?.trim()
+                        List retryServices = autoState?.failedServices ?: []
+                        if (!base) {
+                            // 首次启用新算法时兼容旧构建记录；后续只读取标记为 AUTO 的完成记录，
+                            // SELECT/ALL 不会推进 AUTO 基线。
+                            base = env.GIT_PREVIOUS_SUCCESSFUL_COMMIT?.trim()
+                        }
                         if (!base || sh(script: "git cat-file -e ${base}^{commit} 2>/dev/null", returnStatus: true) != 0) {
                             selected = serviceModules
+                            echo 'AUTO 未找到可用基线，安全回退为全量构建'
                         } else {
                             List changed = sh(script: "git diff --name-only ${base} HEAD", returnStdout: true)
                                 .trim().split('\\n').collect { it.trim() }.findAll { it }
@@ -135,13 +204,27 @@ pipeline {
                                 databaseMigrationPaths.any { prefix -> path.startsWith(prefix) }
                             }
                             env.DATABASE_CHANGE_DETECTED = databaseChanged ? 'true' : 'false'
-                            boolean commonChanged = changed.any { path ->
-                                boolean databaseMigration = databaseMigrationPaths.any { prefix -> path.startsWith(prefix) }
-                                !databaseMigration && commonPaths.any { prefix -> path == prefix || path.startsWith(prefix) }
+                            List serviceRelevantChanges = changed.findAll { path ->
+                                !databaseMigrationPaths.any { prefix -> path.startsWith(prefix) }
                             }
-                            selected = commonChanged ? serviceModules : serviceModules.findAll { module ->
-                                changed.any { it == module || it.startsWith("${module}/") }
+                            boolean fullRebuild = serviceRelevantChanges.any { path ->
+                                fullRebuildPaths.any { prefix -> path == prefix || path.startsWith(prefix) }
                             }
+                            if (fullRebuild) {
+                                selected = serviceModules
+                            } else {
+                                selected = serviceModules.findAll { module ->
+                                    serviceRelevantChanges.any { it == module || it.startsWith("${module}/") }
+                                }
+                                commonPathServices.each { prefix, impactedServices ->
+                                    if (serviceRelevantChanges.any { path -> path == prefix || path.startsWith(prefix) }) {
+                                        selected.addAll(impactedServices)
+                                    }
+                                }
+                            }
+                            selected.addAll(retryServices)
+                            echo "AUTO 基线: ${base}；变更选中: ${selected.unique().join(',') ?: '无'}；" +
+                                "补跑失败服务: ${retryServices.join(',') ?: '无'}"
                         }
                     }
 
@@ -167,14 +250,16 @@ pipeline {
                     env.SELECTED_SERVICES = selected.join(',')
                     env.NO_SERVICE_CHANGE = selected ? 'false' : 'true'
                     if (!selected) {
-                        currentBuild.description = env.DATABASE_CHANGE_DETECTED == 'true'
-                            ? '仅数据库迁移变更 | 需单独审核执行'
-                            : '没有需要构建的业务服务'
+                        currentBuild.description = params.BUILD_MODE == 'AUTO'
+                            ? "AUTO ${env.IMAGE_TAG} | RESULTS"
+                            : (env.DATABASE_CHANGE_DETECTED == 'true'
+                                ? '仅数据库迁移变更 | 需单独审核执行'
+                                : '没有需要构建的业务服务')
                     } else {
-                        env.SOURCE_COMMIT = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
-                        env.IMAGE_TAG = sh(script: 'git rev-parse --short=12 HEAD', returnStdout: true).trim()
                         String databaseSuffix = env.DATABASE_CHANGE_DETECTED == 'true' ? ' | DB migration pending' : ''
-                        currentBuild.description = "${env.SELECTED_SERVICES} | ${env.IMAGE_TAG}${databaseSuffix}"
+                        currentBuild.description = params.BUILD_MODE == 'AUTO'
+                            ? "AUTO ${env.IMAGE_TAG} | PENDING ${env.SELECTED_SERVICES}${databaseSuffix}"
+                            : "${env.SELECTED_SERVICES} | ${env.IMAGE_TAG}${databaseSuffix}"
                         echo "本次独立调度服务: ${env.SELECTED_SERVICES}"
                     }
                     if (env.DATABASE_CHANGE_DETECTED == 'true') {
@@ -275,7 +360,9 @@ pipeline {
                         .collect { service, result -> "${service}=${result}" }
                     String summary = downstreamResults.collect { service, result -> "${service}=${result}" }.join(', ')
                     echo "单服务执行汇总: ${summary}"
-                    currentBuild.description = "${env.IMAGE_TAG} | ${summary}"
+                    currentBuild.description = params.BUILD_MODE == 'AUTO'
+                        ? "AUTO ${env.IMAGE_TAG} | RESULTS ${summary}"
+                        : "${env.IMAGE_TAG} | ${summary}"
                     if (failed) {
                         unstable("部分服务执行失败，但其他服务已独立完成：${failed.join(', ')}")
                     }

Jenkinsfile.service

@@ -1,6 +1,6 @@
 def serviceModules = [
     'gateway', 'gateway-overseas', 'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
-    'integration-service', 'lastleg-service', 'warehouse-overseas-service', 'overseas-security-service', 'event-bridge-service', 'audit-service'
+    'integration-service', 'lastleg-service', 'warehouse-overseas-service', 'event-bridge-service', 'audit-service'
 ]
 
 def serviceJars = [
@@ -17,7 +17,6 @@ def serviceJars = [
     'integration-service': 'integration-service/target/integration-service-1.0.0-SNAPSHOT.jar',
     'lastleg-service': 'lastleg-service/target/lastleg-service-1.0.0-SNAPSHOT.jar',
     'warehouse-overseas-service': 'warehouse-overseas-service/target/warehouse-overseas-service-1.0.0-SNAPSHOT.jar',
-    'overseas-security-service': 'overseas-security-service/target/overseas-security-service-1.0.0-SNAPSHOT.jar',
     'event-bridge-service': 'event-bridge-service/target/event-bridge-service-1.0.0-SNAPSHOT.jar',
     'audit-service': 'audit-service/target/audit-service-1.0.0-SNAPSHOT.jar'
 ]

README.md

@@ -12,7 +12,7 @@
 - `firstleg`：头程揽收、入仓、装载、发运和交接。
 - `warehouse`：国内仓储能力。
 - `file`、`print`、`audit-service`、`integration-service`：国内公共业务能力；Print 调用方接入见 `print/README.md`。
-- `gateway-overseas`、`lastleg-service`、`warehouse-overseas-service`、`overseas-security-service`：海外公网入口、海外尾程与入仓业务、海外仓储资源及 IAM 安全投影。
+- `gateway-overseas`、`lastleg-service`、`warehouse-overseas-service`：海外公网入口、海外尾程/入仓与 IAM 安全投影、海外仓储资源。
 - `event-bridge-service`：按国内、海外双实例部署的跨区域事件桥。
 - `common-*`、`common-event-contract`：由本仓维护并以 `com.baiyue.shared` 发布的公共制品。
 - `platform-bom`：统一管理仓库内公共依赖版本。

auth/src/main/java/com/baiyue/auth/client/IamOnboardingClient.java

@@ -25,5 +25,6 @@ public interface IamOnboardingClient {
                              String legalPerson, String legalPhone, String contactEmail,
                              String countryCode, String address) { }
 
-    record OnboardingResponse(Long tenantId, Long membershipId, String tenantStatus) { }
+    record OnboardingResponse(Long tenantId, Long membershipId, String tenantStatus,
+                              String dimensionInitializationStatus) { }
 }

auth/src/main/java/com/baiyue/auth/dto/MerchantRegisterResponse.java

@@ -5,5 +5,6 @@ public record MerchantRegisterResponse(
         Long tenantId,
         Long membershipId,
         String tenantStatus,
+        String dimensionInitializationStatus,
         String nextStep
 ) { }

auth/src/main/java/com/baiyue/auth/service/AuthService.java

@@ -117,6 +117,7 @@ public class AuthService {
             .subject(account.getId().toString())
             .claim("user_id", account.getId())
             .claim("username", account.getUsername())
+            .claim("display_name", account.getDisplayName() == null ? "" : account.getDisplayName())
             .claim("tenant_id", account.getDefaultTenantId())
             .claim("operator_tenant_id", account.getOperatorTenantId())
             .claim("membership_id", account.getDefaultMembershipId())
@@ -187,7 +188,7 @@ public class AuthService {
         JwtClaimsSet claims = JwtClaimsSet.builder().issuer(properties.issuer())
                 .audience(List.of(properties.audience())).id(jwtId)
                 .issuedAt(issuedAt).expiresAt(expiresAt).subject(account.getId().toString())
-                .claim("user_id", account.getId()).claim("username", account.getUsername())
+                .claim("user_id", account.getId()).claim("username", account.getUsername()).claim("display_name", account.getDisplayName() == null ? "" : account.getDisplayName())
                 .claim("tenant_id", account.getDefaultTenantId()).claim("operator_tenant_id", account.getOperatorTenantId())
                 .claim("membership_id", account.getDefaultMembershipId()).claim("app_code", "MERCHANT")
                 .claim("client_type", authorization.getClientType()).claim("token_version", account.getTokenVersion())

auth/src/main/java/com/baiyue/auth/service/MerchantRegistrationService.java

@@ -103,7 +103,8 @@ public class MerchantRegistrationService {
             throw exception;
         }
         return new MerchantRegisterResponse(accountId, onboarding.tenantId(), onboarding.membershipId(),
-                onboarding.tenantStatus(), "LOGIN_AND_COMPLETE_QUALIFICATIONS");
+                onboarding.tenantStatus(), onboarding.dimensionInitializationStatus(),
+                "LOGIN_AND_COMPLETE_QUALIFICATIONS");
     }
 
     private void registerRollbackCompensation(long accountId, AtomicBoolean compensationCompleted) {

auth/src/main/resources/db/phase1-admin-accounts.sql

@@ -1,4 +1,4 @@
--- Phase-one local administrator accounts.
+-- Phase-one local platform administrator account. Merchant accounts are created through onboarding.
 -- Development-only initial password: ChangeMe123!
 -- The BCrypt hash is intentionally stored instead of plaintext.
 USE baiyue_auth;
@@ -10,9 +10,7 @@ INSERT INTO auth_account (
   operator_tenant_id, default_membership_id, default_app_code, deleted
 ) VALUES
   (1000001, 'platform_admin', '$2a$12$AMZJjd88leYPLI9uKvjZiew2CTQXI32BXoHFX.FrCi28/IeZ7mZ96',
-   '平台系统管理员', 'ACTIVE', 0, 1, 0, 0, 0, 3000001, 'PLATFORM', 0),
-  (1000002, 'merchant_admin', '$2a$12$AMZJjd88leYPLI9uKvjZiew2CTQXI32BXoHFX.FrCi28/IeZ7mZ96',
-   'IT 测试客户管理员', 'ACTIVE', 0, 1, 0, 10001, 10001, 3000002, 'MERCHANT', 0)
+   '平台系统管理员', 'ACTIVE', 0, 1, 0, 0, 0, 3000001, 'PLATFORM', 0)
 ON DUPLICATE KEY UPDATE
   password_hash = VALUES(password_hash),
   display_name = VALUES(display_name),

auth/src/test/java/com/baiyue/auth/repository/InitialAccountSeedSqlContractTest.java

@@ -11,7 +11,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 
 class InitialAccountSeedSqlContractTest {
     @Test
-    void initializesOnlyThePlatformAndItTestAdministratorAccounts() throws Exception {
+    void initializesOnlyThePlatformAdministratorAccount() throws Exception {
         assertAccountSeed(new ClassPathResource("db/phase1-admin-accounts.sql")
             .getContentAsString(StandardCharsets.UTF_8));
         assertAccountSeed(Files.readString(unifiedSql(), StandardCharsets.UTF_8));
@@ -21,9 +21,10 @@ class InitialAccountSeedSqlContractTest {
         assertThat(sql)
             .contains("(1000001, 'platform_admin'")
             .contains("'平台系统管理员', 'ACTIVE'")
-            .contains("(1000002, 'merchant_admin'")
-            .contains("'IT 测试客户管理员', 'ACTIVE'")
             .contains("password_change_required")
+            .doesNotContain("merchant_admin")
+            .doesNotContain("IT_TEST")
+            .doesNotContain("(1000002, 'merchant_admin'")
             .doesNotContain("一期演示企业管理员");
     }
 

auth/src/test/java/com/baiyue/auth/service/MerchantRegistrationServiceTest.java

@@ -35,7 +35,7 @@ class MerchantRegistrationServiceTest {
     void registeredAuthAccountUsesTheOwnerIdentityReturnedByIamOnboarding() {
         when(encoder.encode("Password123")).thenReturn("encoded-password");
         when(onboarding.register(eq("internal-token"), any())).thenReturn(ApiResponse.success(
-                new IamOnboardingClient.OnboardingResponse(10001L, 30001L, "PROFILE_REQUIRED")));
+                new IamOnboardingClient.OnboardingResponse(10001L, 30001L, "PROFILE_REQUIRED", "PENDING")));
 
         var result = service.register(new MerchantRegisterRequest(
                 "registered_owner", "Password123", "注册人", "测试企业", "张三",
@@ -56,13 +56,14 @@ class MerchantRegistrationServiceTest {
         assertEquals("ACTIVE", storedAccount.getValue().getAccountStatus());
         assertEquals("encoded-password", storedAccount.getValue().getPasswordHash());
         assertEquals("LOGIN_AND_COMPLETE_QUALIFICATIONS", result.nextStep());
+        assertEquals("PENDING", result.dimensionInitializationStatus());
     }
 
     @Test
     void failedAuthInsertCompensatesTheIamRegistration() {
         when(encoder.encode("Password123")).thenReturn("encoded-password");
         when(onboarding.register(eq("internal-token"), any())).thenReturn(ApiResponse.success(
-                new IamOnboardingClient.OnboardingResponse(10001L, 30001L, "PROFILE_REQUIRED")));
+                new IamOnboardingClient.OnboardingResponse(10001L, 30001L, "PROFILE_REQUIRED", "PENDING")));
         when(onboarding.compensate(eq("internal-token"), any())).thenReturn(ApiResponse.success(null));
         doThrow(new IllegalStateException("auth database unavailable")).when(accounts).insert(any());
 
@@ -82,7 +83,7 @@ class MerchantRegistrationServiceTest {
     void rolledBackAuthTransactionCompensatesAfterTheLocalTransactionCompletes() {
         when(encoder.encode("Password123")).thenReturn("encoded-password");
         when(onboarding.register(eq("internal-token"), any())).thenReturn(ApiResponse.success(
-                new IamOnboardingClient.OnboardingResponse(10001L, 30001L, "PROFILE_REQUIRED")));
+                new IamOnboardingClient.OnboardingResponse(10001L, 30001L, "PROFILE_REQUIRED", "PENDING")));
         when(onboarding.compensate(eq("internal-token"), any())).thenReturn(ApiResponse.success(null));
 
         TransactionSynchronizationManager.initSynchronization();

common-event-contract/AGENTS.md

@@ -17,6 +17,7 @@
 | 头程装柜完成 V2（当前生产） | `FirstLegLoadingPlanCompletedV2.java`；订单级冻结 `destinationType=FBA|OVERSEAS`，FBA 可按箱数接收，OVERSEAS 逐明细冻结与实装箱数一致的 SKU/箱号；同时冻结来源/根订单与入仓标识、客户、业务类型、目的仓/备注/托盘及一键代发托盘 SKU 快照；国内生产者见 `../firstleg/src/main/java/com/baiyue/firstleg/service/LoadingCompletedOutboxService.java`，海外消费者见 `../lastleg-service/src/main/java/com/baiyue/lastleg/service/LoadingCompletedConsumer.java` |
 | 头程装柜完成 V1 解析模型 | `FirstLegLoadingPlanCompletedV1.java`；用于消费端冻结字段映射，新增生产不得回退为 V1 |
 | 海外卸柜完成 V1 | `OverseasContainerUnloadedV1.java`；按来源柜预订 ID 做柜级聚合/幂等，同一柜只发布一次；`unloadingCompletedAt` 必须是全柜 complete 时刻，不得用签收拍照时刻代替；海外生产者见 `../lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/service/InboundUnloadCompletedOutboxService.java`，国内消费者见 `../firstleg/src/main/java/com/baiyue/firstleg/service/OverseasContainerEventConsumer.java` |
+| 海外入仓单暂扣变更 V1 | `OverseasInboundOrderDetainedChangedV1.java`；聚合键固定为来源头程入仓单 ID，暂扣与解除暂扣均由尾程 Outbox 回传，国内按入仓单绑定、客户归属及聚合版本单调消费 |
 | 国内船节点记录 V1 | `FirstLegContainerShippingNodeRecordedV1.java`；只接受十节点中带实际时间和完整供应商审计字段的事实，国内生产者 `../firstleg/src/main/java/com/baiyue/firstleg/portschedule/service/CarrierScheduleNodeOutboxService.java`，海外消费者 `../lastleg-service/src/main/java/com/baiyue/lastleg/shipping/service/ContainerShippingNodeConsumer.java` |
 | IAM 安全事件 V1 | `IamSecurityEventsV1.java`；账号、授权快照等安全事件的冻结模型 |
 | 契约说明 | `package-info.java` |

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

@@ -13,6 +13,7 @@ public final class EventTypes {
     public static final String FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED =
         "FirstLegContainerShippingNodeRecorded";
     public static final String OVERSEAS_CONTAINER_UNLOADED = "OverseasContainerUnloaded";
+    public static final String OVERSEAS_INBOUND_ORDER_DETAINED_CHANGED = "OverseasInboundOrderDetainedChanged";
     public static final String IAM_USER_STATUS_CHANGED = "IamUserStatusChanged";
     public static final String IAM_TENANT_STATUS_CHANGED = "IamTenantStatusChanged";
     public static final String IAM_PERMISSION_VERSION_CHANGED = "IamPermissionVersionChanged";

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

@@ -0,0 +1,17 @@
+package com.baiyue.common.event;
+
+import java.time.Instant;
+
+/** 海外尾程按来源入仓单回传的暂扣状态事实。 */
+public record OverseasInboundOrderDetainedChangedV1(
+    String sourceInboundId,
+    String inboundCode,
+    String lastlegOrderId,
+    String lastlegOrderNo,
+    boolean detained,
+    String reason,
+    String operatorId,
+    String operatorName,
+    Instant changedAt
+) {
+}

common-openapi/AGENTS.md

@@ -13,10 +13,12 @@
 | `baiyue.openapi` 配置项 | `src/main/java/com/baiyue/common/openapi/OpenApiProperties.java` |
 | 自动配置注册 | `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
 | 长整型 OpenAPI 字符串契约 | `src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java` |
+| PDA OpenAPI 分组 | `src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java` 的 `pda` GroupedOpenApi；固定匹配 `/api/pda/**`，合同测试 `src/test/java/com/baiyue/common/openapi/PdaOpenApiGroupContractTest.java` |
 
 ## 修改与验证
 
 - 调整分组、标题或安全方案时检查所有 MVC 服务的 Swagger 输出；Gateway 的 WebFlux 聚合配置在 `gateway/`。
+- PDA Controller 必须进入独立 `pda` 分组；新增或改名 `/api/pda/**` 路径时同步检查分组合同和目标服务 OpenAPI，不得混入平台或商户分组。
 - 普通业务成功和失败在 OpenAPI 中统一描述为 HTTP 200，并提示调用方检查 body `code`；只为 Security、协议、基础设施、Warehouse 503、Audit 202 和 Event Bridge 内部鉴权等真实状态边界声明非 200 响应。
 - 配置项变化直接同步代码、全部消费者和 Nacos 模板，当前开发阶段不保留旧配置键兼容。
 - 从父目录运行 `mvn -pl common-openapi -am test`。

common-security/AGENTS.md

@@ -12,7 +12,7 @@
 | 安全链自动配置 | `src/main/java/com/baiyue/common/security/BaiyueSecurityAutoConfiguration.java` |
 | JWT 解码模式 | `JwksJwtDecoderAutoConfiguration.java`（国内与海外统一 RS256/JWKS）；`HmacJwtDecoderAutoConfiguration.java` 仅作当前开发阶段清理前的旧实现定位，不得作为跨区域共享密钥方案 |
 | JWT 过滤与声明映射 | `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java` |
-| 当前用户与认证对象 | `AuthenticatedUser.java`、`BaiyueJwtAuthenticationToken.java` |
+| 当前用户与认证对象 | `AuthenticatedUser.java`、`BaiyueJwtAuthenticationToken.java`；海外 PDA 仓范围由 `JwtClaimsMapper.java` 将 `overseas_warehouse_id` 映射为 `overseasWarehouseId` |
 | 会话与授权来源 | `AccessTokenSessionValidator.java`、`RedisAccessTokenSessionValidator.java`（国内登录 Token 即时失效）、`ClaimsAccessTokenSessionValidator.java`（海外访问 Token 本地短时 Claims）、`RedisTokenKeys.java` |
 | 401/403 响应 | `JsonAuthenticationEntryPoint.java`、`JsonAccessDeniedHandler.java` |
 | 自动配置注册 | `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
@@ -22,6 +22,7 @@
 
 - 所有资源服务统一使用 `jwt-mode=jwks`、RS256、Issuer 和 JWKS；国内服务验证国内 Audience 并使用 `session-mode=redis`，海外服务只接受登录/刷新时签发的海外 Audience Token 并使用 `session-mode=claims`，不得访问国内 Redis。海外服务应缓存 JWKS 并在密钥轮换时刷新，不得每个请求访问国内 Auth；不得重新引入跨区域共享 HS256 密钥，也不得让海外服务接受国内 Token。
 - Token Claim、Redis Key、Issuer、Audience、JWKS、会话模式或认证对象变化必须同步检查 `auth/`、`gateway/`、Nacos/部署配置和所有实际业务服务。
+- `overseas_warehouse_id` 只承载 IAM 已确认的海外仓绑定；缺失、格式非法或与实时安全投影不一致时不得放宽 PDA 仓范围，Gateway 与业务服务必须 fail-closed。
 - `JsonAuthenticationEntryPoint` 与 `JsonAccessDeniedHandler` 属于统一 HTTP 200 业务契约的例外：认证入口仍返回真实 401/403，供前端刷新 Token 和区分授权失败。
 - 不降低服务端租户、会话或权限校验；密钥只从配置中心或环境变量读取。
 - 从父目录运行 `mvn -pl common-security -am test`。

common-security/src/main/java/com/baiyue/common/security/AuthenticatedUser.java

@@ -7,21 +7,36 @@ import java.util.Set;
  * 统一认证用户主体，携带用户、租户、成员身份、应用端、客户端类型及权限信息。
  */
 public record AuthenticatedUser(Long userId, Long tenantId, Long operatorTenantId, Long membershipId,
-                                String username, String appCode, String clientType,
+                                String username, String displayName, String appCode, String clientType,
                                 Set<String> permissions, boolean impersonated, Long actorUserId,
                                 Long actorMembershipId, boolean passwordChangeRequired,
                                 Long overseasWarehouseId) implements Principal {
     public AuthenticatedUser(Long userId, Long tenantId, Long operatorTenantId, Long membershipId,
                              String username, String appCode, String clientType, Set<String> permissions) {
-        this(userId, tenantId, operatorTenantId, membershipId, username, appCode, clientType,
+        this(userId, tenantId, operatorTenantId, membershipId, username, null, appCode, clientType,
                 permissions, false, null, null, false, null);
     }
     public AuthenticatedUser(Long userId, Long tenantId, Long operatorTenantId, Long membershipId,
                              String username, String appCode, String clientType, Set<String> permissions,
                              boolean impersonated, Long actorUserId, Long actorMembershipId,
                              boolean passwordChangeRequired) {
-        this(userId, tenantId, operatorTenantId, membershipId, username, appCode, clientType,
-            permissions, impersonated, actorUserId, actorMembershipId, passwordChangeRequired, null);
+        this(userId, tenantId, operatorTenantId, membershipId, username, null, appCode, clientType,
+                permissions, impersonated, actorUserId, actorMembershipId, passwordChangeRequired, null);
+    }
+    public AuthenticatedUser(Long userId, Long tenantId, Long operatorTenantId, Long membershipId,
+                             String username, String displayName, String appCode, String clientType,
+                             Set<String> permissions, boolean impersonated, Long actorUserId,
+                             Long actorMembershipId, boolean passwordChangeRequired) {
+        this(userId, tenantId, operatorTenantId, membershipId, username, displayName, appCode, clientType,
+                permissions, impersonated, actorUserId, actorMembershipId, passwordChangeRequired, null);
+    }
+    public AuthenticatedUser(Long userId, Long tenantId, Long operatorTenantId, Long membershipId,
+                             String username, String appCode, String clientType, Set<String> permissions,
+                             boolean impersonated, Long actorUserId, Long actorMembershipId,
+                             boolean passwordChangeRequired, Long overseasWarehouseId) {
+        this(userId, tenantId, operatorTenantId, membershipId, username, null, appCode, clientType,
+                permissions, impersonated, actorUserId, actorMembershipId, passwordChangeRequired,
+                overseasWarehouseId);
     }
     public AuthenticatedUser {
         permissions = permissions == null ? Set.of() : Set.copyOf(permissions);

common-security/src/main/java/com/baiyue/common/security/JwtClaimsMapper.java

@@ -37,6 +37,7 @@ public class JwtClaimsMapper {
                 longClaim(jwt, "operator_tenant_id"),
                 longClaim(jwt, "membership_id"),
                 username,
+                firstNonBlankNullable(jwt.getClaimAsString("displayName"), jwt.getClaimAsString("display_name")),
                 appCode,
                 jwt.getClaimAsString("client_type"),
                 permissions,
@@ -87,4 +88,9 @@ public class JwtClaimsMapper {
         for (String value : values) if (value != null && !value.isBlank()) return value;
         return "unknown";
     }
+
+    private String firstNonBlankNullable(String... values) {
+        for (String value : values) if (value != null && !value.isBlank()) return value.trim();
+        return null;
+    }
 }

common-web/AGENTS.md

@@ -13,6 +13,7 @@
 | 请求 ID 过滤器 | `src/main/java/com/baiyue/common/web/CorrelationIdFilter.java` |
 | W3C Trace Context | `src/main/java/com/baiyue/common/web/TraceParent.java`；严格接收 version 00，响应 `traceparent`、`X-Trace-Id` 与 MDC `traceId` 使用同一 trace ID |
 | Feign Trace 传播 | `FeignTraceRequestInterceptor.java`、`FeignTracePropagationAutoConfiguration.java`；仅 Feign 存在时装配，optional 依赖不向无 Feign 服务传递 |
+| RestClient Trace 传播 | `RestClientTraceInterceptor.java`、`RestClientTracePropagationAutoConfiguration.java`；Spring 管理的 Builder 自动装配，原始 Builder 可显式复用拦截器 |
 | 自动配置入口 | `src/main/java/com/baiyue/common/web/CommonWebAutoConfiguration.java`；为只扫描自身包的服务注册异常处理器和 Correlation 过滤器 |
 | 全局异常映射与业务失败指标 | `src/main/java/com/baiyue/common/web/GlobalExceptionHandler.java`；指标 `baiyue.api.business.failures` 按有限 `code` 标记 |
 | 过滤器测试 | `src/test/java/com/baiyue/common/web/CorrelationIdFilterTest.java` |
@@ -27,5 +28,6 @@
 - 修改 Correlation ID 时同步检查当前请求头契约、线程上下文清理和日志链路。
 - 入站 Trace 优先级固定为：合法单值 `traceparent` > 完全缺失 `traceparent` 时的 32 位非零十六进制 `X-Trace-Id` > 新 trace。只要 `traceparent` 已出现但重复、超长、格式非法或含全零 ID，就必须生成新 trace，不得回退信任 `X-Trace-Id`；请求 ID 独立按 `X-Request-Id` 校验或生成。
 - 同步 Feign 出站固定先移除调用模板中的 `X-Request-Id`、`X-Trace-Id`、`traceparent`，再仅从当前 MDC 的合法请求 ID 和 trace ID 重建；`traceparent` 沿用当前 trace ID、每次调用生成新非零 span ID、flags 固定 `01`。不得从业务参数、远端返回头或无效 MDC 建立上下文；本能力不处理 Reactor、异步线程、重试、超时或 fallback。
+- 同步 RestClient 出站统一覆盖 `X-Request-Id`、`X-Trace-Id`、`traceparent`，从当前 MDC 生成 child span；MDC 缺失或非法时安全新建 trace。不得从业务参数或远端响应头建立上下文，生产代码应使用 Spring 管理的 `RestClient.Builder`，原始 Builder 必须显式安装同一拦截器。
 - 从父目录运行 `mvn -pl common-web -am test`。
 - 所有对外 `Long/long` 值统一序列化为 JSON 字符串，避免 19 位雪花 ID 在浏览器中丢失精度；禁止业务模块重复添加局部转换器。

common-web/src/main/java/com/baiyue/common/web/OutboundTraceHeaders.java

@@ -0,0 +1,40 @@
+package com.baiyue.common.web;
+
+import org.slf4j.MDC;
+
+import java.util.UUID;
+import java.util.regex.Pattern;
+
+/** Immutable standard headers for one synchronous outbound child span. */
+public record OutboundTraceHeaders(String requestId, String traceId, String traceParent) {
+    private static final Pattern SAFE_REQUEST_ID = Pattern.compile("[A-Za-z0-9._:-]{1,128}");
+
+    /** Builds a child span from the current MDC, safely starting a new trace when absent/invalid. */
+    public static OutboundTraceHeaders fromCurrentOrNew() {
+        String requestId = safeRequestId(MDC.get(CorrelationContext.REQUEST_ID));
+        String traceId = TraceParent.normalizeTrustedTraceId(MDC.get(CorrelationContext.TRACE_ID))
+                .orElseGet(() -> TraceParent.newRoot(null).traceId());
+        return child(requestId, traceId);
+    }
+
+    /** Builds a local child from a trusted persisted trace value, or safely starts a new trace. */
+    public static OutboundTraceHeaders fromTrustedTraceOrNew(String trustedTraceId) {
+        String traceId = TraceParent.normalizeTrustedTraceId(trustedTraceId)
+                .orElseGet(() -> TraceParent.newRoot(null).traceId());
+        return child(UUID.randomUUID().toString(), traceId);
+    }
+
+    public String spanId() {
+        return TraceParent.parse(traceParent).orElseThrow().parentId();
+    }
+
+    private static OutboundTraceHeaders child(String requestId, String traceId) {
+        TraceParent child = TraceParent.outboundChild(traceId);
+        return new OutboundTraceHeaders(requestId, child.traceId(), child.value());
+    }
+
+    private static String safeRequestId(String value) {
+        return value != null && SAFE_REQUEST_ID.matcher(value).matches()
+                ? value : UUID.randomUUID().toString();
+    }
+}

common-web/src/main/java/com/baiyue/common/web/RestClientTraceCustomizer.java

@@ -0,0 +1,24 @@
+package com.baiyue.common.web;
+
+import org.springframework.boot.web.client.RestClientCustomizer;
+import org.springframework.core.Ordered;
+import org.springframework.web.client.RestClient;
+
+/** Installs the trace interceptor after ordinary RestClient customizers. */
+public final class RestClientTraceCustomizer implements RestClientCustomizer, Ordered {
+    private final RestClientTraceInterceptor interceptor;
+
+    public RestClientTraceCustomizer(RestClientTraceInterceptor interceptor) {
+        this.interceptor = interceptor;
+    }
+
+    @Override
+    public void customize(RestClient.Builder builder) {
+        builder.requestInterceptor(interceptor);
+    }
+
+    @Override
+    public int getOrder() {
+        return Ordered.LOWEST_PRECEDENCE;
+    }
+}

common-web/src/main/java/com/baiyue/common/web/RestClientTraceInterceptor.java

@@ -0,0 +1,21 @@
+package com.baiyue.common.web;
+
+import org.springframework.http.HttpRequest;
+import org.springframework.http.client.ClientHttpRequestExecution;
+import org.springframework.http.client.ClientHttpRequestInterceptor;
+import org.springframework.http.client.ClientHttpResponse;
+
+import java.io.IOException;
+
+/** Applies the trusted synchronous trace context to Spring RestClient requests. */
+public final class RestClientTraceInterceptor implements ClientHttpRequestInterceptor {
+    @Override
+    public ClientHttpResponse intercept(HttpRequest request, byte[] body,
+                                        ClientHttpRequestExecution execution) throws IOException {
+        OutboundTraceHeaders outbound = OutboundTraceHeaders.fromCurrentOrNew();
+        request.getHeaders().set(CorrelationContext.REQUEST_ID_HEADER, outbound.requestId());
+        request.getHeaders().set(CorrelationContext.TRACE_ID_HEADER, outbound.traceId());
+        request.getHeaders().set(CorrelationContext.TRACE_PARENT_HEADER, outbound.traceParent());
+        return execution.execute(request, body);
+    }
+}

common-web/src/main/java/com/baiyue/common/web/RestClientTracePropagationAutoConfiguration.java

@@ -0,0 +1,25 @@
+package com.baiyue.common.web;
+
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.web.client.RestClientCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.web.client.RestClient;
+
+/** Adds trace propagation to Spring-managed RestClient builders. */
+@AutoConfiguration(afterName = "org.springframework.boot.autoconfigure.web.client.RestClientAutoConfiguration")
+@ConditionalOnClass({RestClient.class, RestClientCustomizer.class})
+public class RestClientTracePropagationAutoConfiguration {
+
+    @Bean
+    @ConditionalOnMissingBean(RestClientTraceInterceptor.class)
+    RestClientTraceInterceptor restClientTraceInterceptor() {
+        return new RestClientTraceInterceptor();
+    }
+
+    @Bean
+    RestClientTraceCustomizer baiyueTraceRestClientCustomizer(RestClientTraceInterceptor interceptor) {
+        return new RestClientTraceCustomizer(interceptor);
+    }
+}

common-web/src/main/java/com/baiyue/common/web/TraceParent.java

@@ -3,6 +3,7 @@ package com.baiyue.common.web;
 import java.security.SecureRandom;
 import java.util.HexFormat;
 import java.util.Optional;
+import java.util.Locale;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -63,6 +64,24 @@ public record TraceParent(String traceId, String parentId, String traceFlags) {
         return new TraceParent(currentTraceId.toLowerCase(java.util.Locale.ROOT), randomNonZero(8), "01");
     }
 
+    /**
+     * Normalizes a trace ID from a trusted persisted/internal context.
+     *
+     * <p>Unlike an untrusted HTTP header, a canonical UUID is accepted and compacted because
+     * existing event envelopes historically persisted UUID trace IDs.</p>
+     */
+    public static Optional<String> normalizeTrustedTraceId(String value) {
+        if (validLegacyTraceId(value)) {
+            return Optional.of(value.toLowerCase(Locale.ROOT));
+        }
+        if (value != null && value.matches(
+                "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}")) {
+            String compact = value.replace("-", "").toLowerCase(Locale.ROOT);
+            return validLegacyTraceId(compact) ? Optional.of(compact) : Optional.empty();
+        }
+        return Optional.empty();
+    }
+
     public static boolean validLegacyTraceId(String value) {
         return value != null && LEGACY_TRACE_ID.matcher(value).matches()
                 && !ZERO_TRACE_ID.equalsIgnoreCase(value);

common-web/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -1,3 +1,4 @@
 com.baiyue.common.web.LongIdJacksonConfiguration
 com.baiyue.common.web.CommonWebAutoConfiguration
 com.baiyue.common.web.FeignTracePropagationAutoConfiguration
+com.baiyue.common.web.RestClientTracePropagationAutoConfiguration

common-web/src/test/java/com/baiyue/common/web/OutboundTraceHeadersTest.java

@@ -0,0 +1,41 @@
+package com.baiyue.common.web;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.slf4j.MDC;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class OutboundTraceHeadersTest {
+
+    @AfterEach
+    void clearMdc() {
+        MDC.clear();
+    }
+
+    @Test
+    void currentContextCreatesAValidChildWithoutUsingBusinessValues() {
+        MDC.put(CorrelationContext.REQUEST_ID, "req-trusted");
+        MDC.put(CorrelationContext.TRACE_ID, "4bf92f3577b34da6a3ce929d0e0e4736");
+
+        OutboundTraceHeaders headers = OutboundTraceHeaders.fromCurrentOrNew();
+
+        assertThat(headers.requestId()).isEqualTo("req-trusted");
+        assertThat(headers.traceId()).isEqualTo("4bf92f3577b34da6a3ce929d0e0e4736");
+        assertThat(headers.traceParent())
+                .matches("00-4bf92f3577b34da6a3ce929d0e0e4736-[0-9a-f]{16}-01");
+    }
+
+    @Test
+    void canonicalPersistedUuidIsCompactedAndInvalidValueStartsNewTrace() {
+        OutboundTraceHeaders uuid = OutboundTraceHeaders.fromTrustedTraceOrNew(
+                "550e8400-e29b-41d4-a716-446655440000");
+        OutboundTraceHeaders invalid = OutboundTraceHeaders.fromTrustedTraceOrNew(
+                "ORDER:customer-99:booking-123");
+
+        assertThat(uuid.traceId()).isEqualTo("550e8400e29b41d4a716446655440000");
+        assertThat(invalid.traceId()).matches("[0-9a-f]{32}")
+                .isNotEqualTo("ORDER:customer-99:booking-123");
+        assertThat(invalid.requestId()).matches("[0-9a-f-]{36}");
+    }
+}

common-web/src/test/java/com/baiyue/common/web/RestClientTraceInterceptorTest.java

@@ -0,0 +1,60 @@
+package com.baiyue.common.web;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.slf4j.MDC;
+import org.springframework.mock.http.client.MockClientHttpRequest;
+import org.springframework.mock.http.client.MockClientHttpResponse;
+
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class RestClientTraceInterceptorTest {
+    private final RestClientTraceInterceptor interceptor = new RestClientTraceInterceptor();
+
+    @AfterEach
+    void clearMdc() {
+        MDC.clear();
+    }
+
+    @Test
+    void trustedContextOverwritesAllCallerProvidedTraceHeaders() throws Exception {
+        MDC.put(CorrelationContext.REQUEST_ID, "req-rest-client");
+        MDC.put(CorrelationContext.TRACE_ID, "4bf92f3577b34da6a3ce929d0e0e4736");
+        MockClientHttpRequest request = new MockClientHttpRequest();
+        request.getHeaders().add(CorrelationContext.REQUEST_ID_HEADER, "business-request-id");
+        request.getHeaders().add(CorrelationContext.TRACE_ID_HEADER, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+        request.getHeaders().add(CorrelationContext.TRACE_PARENT_HEADER,
+                "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-00");
+        AtomicReference<org.springframework.http.HttpHeaders> captured = new AtomicReference<>();
+
+        interceptor.intercept(request, new byte[0], (outbound, body) -> {
+            captured.set(outbound.getHeaders());
+            return new MockClientHttpResponse(new byte[0], org.springframework.http.HttpStatus.OK);
+        });
+
+        assertThat(captured.get().getValuesAsList(CorrelationContext.REQUEST_ID_HEADER))
+                .containsExactly("req-rest-client");
+        assertThat(captured.get().getValuesAsList(CorrelationContext.TRACE_ID_HEADER))
+                .containsExactly("4bf92f3577b34da6a3ce929d0e0e4736");
+        assertThat(captured.get().getFirst(CorrelationContext.TRACE_PARENT_HEADER))
+                .matches("00-4bf92f3577b34da6a3ce929d0e0e4736-[0-9a-f]{16}-01");
+    }
+
+    @Test
+    void missingOrInvalidMdcSafelyCreatesNewStandardHeaders() throws Exception {
+        MDC.put(CorrelationContext.TRACE_ID, "business-order-123");
+        MockClientHttpRequest request = new MockClientHttpRequest();
+
+        interceptor.intercept(request, new byte[0], (outbound, body) ->
+                new MockClientHttpResponse(new byte[0], org.springframework.http.HttpStatus.OK));
+
+        assertThat(request.getHeaders().getFirst(CorrelationContext.REQUEST_ID_HEADER))
+                .matches("[0-9a-f-]{36}");
+        assertThat(request.getHeaders().getFirst(CorrelationContext.TRACE_ID_HEADER))
+                .matches("[0-9a-f]{32}").isNotEqualTo("business-order-123");
+        assertThat(request.getHeaders().getFirst(CorrelationContext.TRACE_PARENT_HEADER))
+                .matches("00-[0-9a-f]{32}-[0-9a-f]{16}-01");
+    }
+}

common-web/src/test/java/com/baiyue/common/web/RestClientTracePropagationAutoConfigurationTest.java

@@ -0,0 +1,37 @@
+package com.baiyue.common.web;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+import org.springframework.boot.web.client.RestClientCustomizer;
+import org.springframework.core.Ordered;
+import org.springframework.web.client.RestClient;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+
+class RestClientTracePropagationAutoConfigurationTest {
+    private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
+            .withConfiguration(AutoConfigurations.of(RestClientTracePropagationAutoConfiguration.class));
+
+    @Test
+    void registersInterceptorAndIndependentCustomizer() {
+        contextRunner.run(context -> {
+            assertThat(context).hasSingleBean(RestClientTraceInterceptor.class);
+            assertThat(context).hasBean("baiyueTraceRestClientCustomizer");
+            assertThat(context.getBeansOfType(RestClientCustomizer.class)).hasSize(1);
+            RestClientTraceCustomizer customizer = context.getBean(RestClientTraceCustomizer.class);
+            assertThat(customizer.getOrder()).isEqualTo(Ordered.LOWEST_PRECEDENCE);
+            RestClient.Builder builder = mock(RestClient.Builder.class);
+            customizer.customize(builder);
+            verify(builder).requestInterceptor(context.getBean(RestClientTraceInterceptor.class));
+        });
+    }
+
+    @Test
+    void reusesApplicationProvidedTraceInterceptor() {
+        contextRunner.withBean(RestClientTraceInterceptor.class, RestClientTraceInterceptor::new)
+                .run(context -> assertThat(context).hasSingleBean(RestClientTraceInterceptor.class));
+    }
+}

common-web/src/test/java/com/baiyue/common/web/TraceParentTest.java

@@ -51,4 +51,12 @@ class TraceParentTest {
         assertThat(child.value()).matches(
                 "00-4bf92f3577b34da6a3ce929d0e0e4736-[0-9a-f]{16}-01");
     }
+
+    @Test
+    void trustedPersistedUuidNormalizationDoesNotBroadenHttpParsing() {
+        assertThat(TraceParent.normalizeTrustedTraceId("550E8400-E29B-41D4-A716-446655440000"))
+                .contains("550e8400e29b41d4a716446655440000");
+        assertThat(TraceParent.parse(
+                "00-550E8400E29B41D4A716446655440000-00f067aa0ba902b7-01")).isEmpty();
+    }
 }

config/nacos/cn/iam-service.yml

@@ -5,6 +5,11 @@ spring:
     password: ${IAM_DB_PASSWORD}
     driver-class-name: com.mysql.cj.jdbc.Driver
 baiyue:
+  security-event:
+    event-bridge-url: ${SECURITY_EVENT_BRIDGE_URL:http://event-bridge-overseas:9312}
+  customer-dimension-initialization:
+    fixed-delay-ms: ${CUSTOMER_DIMENSION_INITIALIZATION_FIXED_DELAY_MS:5000}
+    max-attempts: ${CUSTOMER_DIMENSION_INITIALIZATION_MAX_ATTEMPTS:12}
   notification:
     scheduler-enabled: ${NOTIFICATION_SCHEDULER_ENABLED:false}
     dispatch-timeout-seconds: ${NOTIFICATION_DISPATCH_TIMEOUT_SECONDS:300}

config/nacos/local/README.md

@@ -10,8 +10,19 @@
 powershell -ExecutionPolicy Bypass -File D:\baiyue-firstleg\scripts\publish-local-nacos-config.ps1
 ```
 
+也可以使用统一入口；`local` 会被强制限制在 `public` namespace：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File D:\baiyue-firstleg\scripts\publish-nacos-config.ps1 -Environment local
+```
+
 配置发布成功后，各服务仍由自身的 Nacos Discovery 配置在启动时自动注册，不需要手工创建服务实例。
 
+本地海外链路也发布在同一 `public / BAIYUE` 作用域，包括
+`gateway-overseas.yml`、`lastleg-service.yml` 和
+`warehouse-overseas-service.yml`。这些配置默认通过 `127.0.0.1` 连接本机
+Auth、国内仓库、文件和海外服务；需要跨主机运行时使用对应环境变量覆盖。
+
 ## MyBatis SQL 日志
 
 本地公共配置使用 MyBatis `Slf4jImpl`，数据库服务的 Mapper 日志级别默认为 `DEBUG`。执行数据库操作时，控制台会打印 SQL 模板、参数和影响行数。

config/nacos/local/event-bridge-service.yml

@@ -5,5 +5,7 @@ spring.datasource:
   password: ${EVENT_BRIDGE_DB_PASSWORD:123456}
 baiyue:
   region: ${REGION_CODE:CN}
+  event-bridge:
+    accept-any-region: ${EVENT_BRIDGE_ACCEPT_ANY_REGION:true}
   deployment-cell: ${DEPLOYMENT_CELL:local-cn}
   data-residency: ${DATA_RESIDENCY:CN}

config/nacos/local/gateway-overseas.yml

@@ -0,0 +1,16 @@
+springdoc:
+  api-docs.enabled: ${SWAGGER_ENABLED:true}
+  swagger-ui.enabled: ${SWAGGER_ENABLED:true}
+baiyue:
+  security:
+    issuer: ${JWT_ISSUER:auth-service}
+    audience: ${JWT_AUDIENCE:lastleg-api}
+    jwk-set-uri: ${JWT_JWK_SET_URI:http://127.0.0.1:9100/api/auth/.well-known/jwks.json}
+    pda-session-validation:
+      auth-url: ${AUTH_SESSION_VALIDATION_URL:http://127.0.0.1:9100}
+      internal-service-token: ${INTERNAL_SERVICE_TOKEN:phase1-local-internal-token-at-least-32-bytes}
+      timeout: ${PDA_SESSION_VALIDATION_TIMEOUT:2s}
+    overseas-projection:
+      service-url: ${LASTLEG_SECURITY_SERVICE_URL:http://127.0.0.1:9303}
+      internal-service-token: ${INTERNAL_SERVICE_TOKEN:phase1-local-internal-token-at-least-32-bytes}
+      timeout: ${LASTLEG_SECURITY_VALIDATION_TIMEOUT:2s}

config/nacos/local/iam-service.yml

@@ -4,6 +4,9 @@ spring.datasource:
   username: ${IAM_DB_USERNAME:root}
   password: ${IAM_DB_PASSWORD:123456}
 baiyue:
+  customer-dimension-initialization:
+    fixed-delay-ms: ${CUSTOMER_DIMENSION_INITIALIZATION_FIXED_DELAY_MS:5000}
+    max-attempts: ${CUSTOMER_DIMENSION_INITIALIZATION_MAX_ATTEMPTS:12}
   notification:
     scheduler-enabled: ${NOTIFICATION_SCHEDULER_ENABLED:false}
     dispatch-timeout-seconds: ${NOTIFICATION_DISPATCH_TIMEOUT_SECONDS:300}

config/nacos/local/lastleg-service.yml

@@ -0,0 +1,29 @@
+spring:
+  datasource:
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    url: ${LASTLEG_DB_URL:jdbc:mysql://127.0.0.1:3306/baiyue_lastleg?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&rewriteBatchedStatements=true}
+    username: ${LASTLEG_DB_USERNAME:root}
+    password: ${LASTLEG_DB_PASSWORD:123456}
+lastleg:
+  dispatch-query-api.enabled: ${LASTLEG_DISPATCH_QUERY_API_ENABLED:true}
+  smart-dispatch-api.enabled: ${LASTLEG_SMART_DISPATCH_API_ENABLED:true}
+baiyue:
+  clients:
+    domestic-warehouse:
+      url: ${DOMESTIC_WAREHOUSE_URL:http://127.0.0.1:9205}
+      cache-ttl: ${DOMESTIC_WAREHOUSE_CACHE_TTL:30m}
+    file:
+      url: ${FILE_SERVICE_URL:http://127.0.0.1:9206}
+    event-bridge:
+      url: ${CN_EVENT_BRIDGE_URL:${FIRSTLEG_EVENT_BRIDGE_URL:http://127.0.0.1:9312}}
+  warehouse:
+    base-url: ${WAREHOUSE_OVERSEAS_SERVICE_URL:http://127.0.0.1:9305}
+  firstleg:
+    event-bridge-url: ${CN_EVENT_BRIDGE_URL:${FIRSTLEG_EVENT_BRIDGE_URL:http://127.0.0.1:9312}}
+  security:
+    internal-service-token: ${INTERNAL_SERVICE_TOKEN:phase1-local-internal-token-at-least-32-bytes}
+    jwt-mode: jwks
+    session-mode: claims
+    issuer: ${JWT_ISSUER:auth-service}
+    audience: ${JWT_AUDIENCE:lastleg-api}
+    jwk-set-uri: ${JWT_JWK_SET_URI:http://127.0.0.1:9100/api/auth/.well-known/jwks.json}

config/nacos/local/warehouse-overseas-service.yml

@@ -0,0 +1,19 @@
+spring:
+  datasource:
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    url: ${WAREHOUSE_DB_URL:jdbc:mysql://127.0.0.1:3306/baiyue_lastlag_warehouse?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&rewriteBatchedStatements=true}
+    username: ${WAREHOUSE_DB_USERNAME:root}
+    password: ${WAREHOUSE_DB_PASSWORD:123456}
+baiyue:
+  clients:
+    domestic-warehouse:
+      url: ${DOMESTIC_WAREHOUSE_URL:http://127.0.0.1:9205}
+      cache-ttl: ${DOMESTIC_WAREHOUSE_CACHE_TTL:30m}
+  internal-service:
+    token: ${INTERNAL_SERVICE_TOKEN:phase1-local-internal-token-at-least-32-bytes}
+  security:
+    jwt-mode: jwks
+    session-mode: claims
+    issuer: ${JWT_ISSUER:auth-service}
+    audience: ${JWT_AUDIENCE:lastleg-api}
+    jwk-set-uri: ${JWT_JWK_SET_URI:http://127.0.0.1:9100/api/auth/.well-known/jwks.json}

config/nacos/overseas/README.md

@@ -1,5 +1,19 @@
 # 海外 Nacos 配置
 
-将本目录文件按原文件名作为 Data ID 发布到 `prod-overseas` 命名空间和 `BAIYUE` 分组。配置只引用环境变量，不保存密码或访问密钥。Gateway 必须同时启用 `overseas` Profile。
+本目录是海外远程部署模板，由 dev/development、test 和 production 共用。配置只引用环境变量，不保存密码或访问密钥；三个环境必须发布到各自独立的 Nacos namespace，Gateway 必须同时启用 `overseas` Profile。
 
 海外入口与仓储 Data ID 分别为 `gateway-overseas.yml`、`warehouse-overseas-service.yml`。`print-service.yml` 对应头程仓库保留的共用打印服务，不包含尾程旧 Print 模块。
+
+发布示例：
+
+```powershell
+# 开发环境
+powershell -ExecutionPolicy Bypass -File D:\baiyue-firstleg\scripts\publish-nacos-config.ps1 `
+  -Environment development -Region overseas -ServerAddr <dev-nacos> -Namespace <dev-overseas-namespace>
+
+# 测试环境
+powershell -ExecutionPolicy Bypass -File D:\baiyue-firstleg\scripts\publish-nacos-config.ps1 `
+  -Environment test -Region overseas -ServerAddr <test-nacos> -Namespace <test-overseas-namespace>
+```
+
+远程环境禁止使用 `public` namespace。数据库、Redis、JWKS、内部服务令牌和跨区服务地址继续由对应 Jenkins Secret file 提供；不要把真实值写入本目录。

config/nacos/overseas/event-bridge-service.yml

@@ -10,7 +10,7 @@ baiyue:
   data-residency: ${DATA_RESIDENCY:OVERSEAS}
   event-dispatcher:
     consumer-url: ${EVENT_CONSUMER_URL:http://lastleg-service:9303/internal/lastleg/events}
-    security-consumer-url: ${OVERSEAS_SECURITY_EVENT_CONSUMER_URL:http://overseas-security-service:9307/internal/overseas-security/v1/events}
+    security-consumer-url: ${LASTLEG_SECURITY_EVENT_CONSUMER_URL:http://lastleg-service:9303/internal/lastleg/security/v1/events}
     fixed-delay: ${EVENT_DISPATCH_FIXED_DELAY:3000}
     batch-size: ${EVENT_DISPATCH_BATCH_SIZE:50}
     max-attempts: ${EVENT_DISPATCH_MAX_ATTEMPTS:10}

config/nacos/overseas/gateway-overseas.yml

@@ -4,6 +4,6 @@ springdoc:
 baiyue:
   security:
     overseas-projection:
-      service-url: ${OVERSEAS_SECURITY_SERVICE_URL:http://overseas-security-service:9307}
+      service-url: ${LASTLEG_SECURITY_SERVICE_URL:http://lastleg-service:9303}
       internal-service-token: ${INTERNAL_SERVICE_TOKEN}
-      timeout: ${OVERSEAS_SECURITY_VALIDATION_TIMEOUT:2s}
+      timeout: ${LASTLEG_SECURITY_VALIDATION_TIMEOUT:2s}

config/nacos/overseas/overseas-security-service.yml

@@ -1,7 +0,0 @@
-springdoc:
-  api-docs.enabled: ${SWAGGER_ENABLED:false}
-  swagger-ui.enabled: ${SWAGGER_ENABLED:false}
-baiyue:
-  security:
-    internal-service-token: ${INTERNAL_SERVICE_TOKEN}
-    permission-snapshot-key-prefix: ${PERMISSION_SNAPSHOT_KEY_PREFIX:baiyue:permission-snapshot}

config/nacos/overseas/warehouse-overseas-service.yml

@@ -4,3 +4,8 @@ spring:
     username: ${WAREHOUSE_DB_USERNAME}
     password: ${WAREHOUSE_DB_PASSWORD}
     driver-class-name: com.mysql.cj.jdbc.Driver
+baiyue:
+  clients:
+    domestic-warehouse:
+      url: ${DOMESTIC_WAREHOUSE_URL}
+      cache-ttl: ${DOMESTIC_WAREHOUSE_CACHE_TTL:30m}

deploy/docker-compose.overseas.yml

@@ -47,8 +47,8 @@ services:
       CORS_ALLOW_CREDENTIALS: ${CORS_ALLOW_CREDENTIALS:-false}
       AUTH_SESSION_VALIDATION_URL: ${AUTH_SESSION_VALIDATION_URL}
       PDA_SESSION_VALIDATION_TIMEOUT: ${PDA_SESSION_VALIDATION_TIMEOUT:-2s}
-      OVERSEAS_SECURITY_SERVICE_URL: ${OVERSEAS_SECURITY_SERVICE_URL:-http://overseas-security-service:9307}
-      OVERSEAS_SECURITY_VALIDATION_TIMEOUT: ${OVERSEAS_SECURITY_VALIDATION_TIMEOUT:-2s}
+      LASTLEG_SECURITY_SERVICE_URL: ${LASTLEG_SECURITY_SERVICE_URL:-http://lastleg-service:9303}
+      LASTLEG_SECURITY_VALIDATION_TIMEOUT: ${LASTLEG_SECURITY_VALIDATION_TIMEOUT:-2s}
 
   lastleg-service:
     <<: *overseas-common
@@ -80,6 +80,7 @@ services:
       WAREHOUSE_DB_URL: ${WAREHOUSE_OVERSEAS_DB_URL}
       WAREHOUSE_DB_USERNAME: ${WAREHOUSE_OVERSEAS_DB_USERNAME}
       WAREHOUSE_DB_PASSWORD: ${WAREHOUSE_OVERSEAS_DB_PASSWORD}
+      DOMESTIC_WAREHOUSE_URL: ${DOMESTIC_WAREHOUSE_URL}
 
   event-bridge-service:
     <<: *overseas-common
@@ -94,25 +95,12 @@ services:
       EVENT_BRIDGE_DB_USERNAME: ${EVENT_BRIDGE_OVERSEAS_DB_USERNAME}
       EVENT_BRIDGE_DB_PASSWORD: ${EVENT_BRIDGE_OVERSEAS_DB_PASSWORD}
       EVENT_CONSUMER_URL: ${EVENT_CONSUMER_URL:-http://lastleg-service:9303/internal/lastleg/events}
-      OVERSEAS_SECURITY_EVENT_CONSUMER_URL: ${OVERSEAS_SECURITY_EVENT_CONSUMER_URL:-http://overseas-security-service:9307/internal/overseas-security/v1/events}
+      LASTLEG_SECURITY_EVENT_CONSUMER_URL: ${LASTLEG_SECURITY_EVENT_CONSUMER_URL:-http://lastleg-service:9303/internal/lastleg/security/v1/events}
     networks:
       firstleg-overseas-network:
       infra-network:
         aliases: [event-bridge-overseas]
 
-  overseas-security-service:
-    <<: *overseas-common
-    image: ${IMAGE_REPOSITORY}/overseas-security-service:${IMAGE_TAG}
-    container_name: firstleg-${DEPLOY_ENV:-test}-overseas-security
-    ports: ["${PUBLISHED_BIND_ADDRESS:-127.0.0.1}:${OVERSEAS_SECURITY_PORT:-9307}:9307"]
-    volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/overseas-security-service:/app/logs"]
-    environment:
-      <<: *overseas-environment
-      SERVER_PORT: 9307
-      OVERSEAS_SECURITY_DB_URL: ${OVERSEAS_SECURITY_DB_URL}
-      OVERSEAS_SECURITY_DB_USERNAME: ${OVERSEAS_SECURITY_DB_USERNAME}
-      OVERSEAS_SECURITY_DB_PASSWORD: ${OVERSEAS_SECURITY_DB_PASSWORD}
-
 networks:
   firstleg-overseas-network:
     name: firstleg-${DEPLOY_ENV:-test}-overseas-network

deploy/docker-compose.yml

@@ -79,6 +79,7 @@ services:
       IAM_DB_URL: ${IAM_DB_URL}
       IAM_DB_USERNAME: ${IAM_DB_USERNAME}
       IAM_DB_PASSWORD: ${IAM_DB_PASSWORD}
+      SECURITY_EVENT_BRIDGE_URL: ${SECURITY_EVENT_BRIDGE_URL:-http://event-bridge-overseas:9312}
 
   firstleg:
     <<: *common

deploy/maven/settings-cn.xml

@@ -4,54 +4,36 @@
           xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
     <mirrors>
         <mirror>
-            <id>baiyue-nexus-public</id>
-            <name>柏悦 Nexus Maven 聚合仓库</name>
-            <url>http://8.163.30.128:18081/repository/maven-public/</url>
-            <mirrorOf>external:*</mirrorOf>
+            <id>aliyun-public</id>
+            <name>阿里云 Maven 公共镜像</name>
+            <url>https://maven.aliyun.com/repository/public</url>
+            <mirrorOf>central</mirrorOf>
         </mirror>
     </mirrors>
 
-    <servers>
-        <server>
-            <id>baiyue-nexus-public</id>
-            <username>${env.NEXUS_USERNAME}</username>
-            <password>${env.NEXUS_PASSWORD}</password>
-        </server>
-        <server>
-            <id>baiyue-nexus-releases</id>
-            <username>${env.NEXUS_USERNAME}</username>
-            <password>${env.NEXUS_PASSWORD}</password>
-        </server>
-        <server>
-            <id>baiyue-nexus-snapshots</id>
-            <username>${env.NEXUS_USERNAME}</username>
-            <password>${env.NEXUS_PASSWORD}</password>
-        </server>
-    </servers>
-
     <profiles>
         <profile>
-            <id>柏悦 Nexus</id>
+            <id>国内公共镜像</id>
             <repositories>
                 <repository>
-                    <id>baiyue-nexus-public</id>
-                    <url>http://8.163.30.128:18081/repository/maven-public/</url>
+                    <id>central</id>
+                    <url>https://repo.maven.apache.org/maven2</url>
                     <releases><enabled>true</enabled></releases>
-                    <snapshots><enabled>true</enabled></snapshots>
+                    <snapshots><enabled>false</enabled></snapshots>
                 </repository>
             </repositories>
             <pluginRepositories>
                 <pluginRepository>
-                    <id>baiyue-nexus-public</id>
-                    <url>http://8.163.30.128:18081/repository/maven-public/</url>
+                    <id>central</id>
+                    <url>https://repo.maven.apache.org/maven2</url>
                     <releases><enabled>true</enabled></releases>
-                    <snapshots><enabled>true</enabled></snapshots>
+                    <snapshots><enabled>false</enabled></snapshots>
                 </pluginRepository>
             </pluginRepositories>
         </profile>
     </profiles>
 
     <activeProfiles>
-        <activeProfile>柏悦 Nexus</activeProfile>
+        <activeProfile>国内公共镜像</activeProfile>
     </activeProfiles>
 </settings>

deploy/scripts/deploy-built-service.sh

@@ -37,10 +37,7 @@ case "$DEPLOY_ENV" in
 esac
 
 if [ "$DEPLOY_ENV" = "development" ]; then
-  case "$SERVICE" in
-    gateway|gateway-overseas) PUBLISHED_BIND_ADDRESS=0.0.0.0 ;;
-    *) PUBLISHED_BIND_ADDRESS=127.0.0.1 ;;
-  esac
+  PUBLISHED_BIND_ADDRESS=127.0.0.1
 else
   PUBLISHED_BIND_ADDRESS="${PUBLISHED_BIND_ADDRESS:-0.0.0.0}"
 fi
@@ -67,7 +64,7 @@ env_file_value() {
 }
 
 case "$SERVICE" in
-  gateway-overseas|lastleg-service|warehouse-overseas-service|overseas-security-service)
+  gateway-overseas|lastleg-service|warehouse-overseas-service)
     COMPOSE_FILE="deploy/docker-compose.overseas.yml"
     PROJECT_NAME="firstleg-$DEPLOY_ENV-overseas"
     ;;
@@ -101,15 +98,6 @@ if [ "$SERVICE" = "gateway-overseas" ]; then
   fi
 fi
 
-if [ "$SERVICE" = "overseas-security-service" ]; then
-  for key in OVERSEAS_SECURITY_DB_URL OVERSEAS_SECURITY_DB_USERNAME OVERSEAS_SECURITY_DB_PASSWORD; do
-    if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
-      echo "部署 overseas-security-service 时，环境文件必须包含非空 $key" >&2
-      exit 2
-    fi
-  done
-fi
-
 for file in "$ENV_FILE" "$COMPOSE_FILE"; do
   if [ ! -f "$file" ]; then
     echo "必需文件不存在: $file" >&2
@@ -127,7 +115,7 @@ if [ "$SERVICE" = "finance" ]; then
 fi
 
 case "$SERVICE" in
-  gateway-overseas|lastleg-service|warehouse-overseas-service|overseas-security-service)
+  gateway-overseas|lastleg-service|warehouse-overseas-service)
     for key in NACOS_SERVER_ADDR OVERSEAS_NACOS_NAMESPACE INTERNAL_SERVICE_TOKEN JWT_ISSUER OVERSEAS_JWT_AUDIENCE JWT_JWK_SET_URI; do
       if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
         echo "部署海外服务时，环境文件必须包含非空 $key" >&2
@@ -433,10 +421,7 @@ export DEPLOY_ENV="$deploy_env"
 export IMAGE_REPOSITORY="$image_repository"
 export IMAGE_TAG="$image_tag"
 if [ "$deploy_env" = "development" ]; then
-  case "$service" in
-    gateway|gateway-overseas) export PUBLISHED_BIND_ADDRESS=0.0.0.0 ;;
-    *) export PUBLISHED_BIND_ADDRESS=127.0.0.1 ;;
-  esac
+  export PUBLISHED_BIND_ADDRESS=127.0.0.1
 else
   export PUBLISHED_BIND_ADDRESS="${PUBLISHED_BIND_ADDRESS:-0.0.0.0}"
 fi

deploy/scripts/deploy-services.sh

@@ -39,7 +39,7 @@ env_file_value() {
 DEPLOY_REGION=CN
 for service in $SERVICES; do
   case "$service" in
-    gateway-overseas|lastleg-service|warehouse-overseas-service|overseas-security-service) DEPLOY_REGION=OVERSEAS ;;
+    gateway-overseas|lastleg-service|warehouse-overseas-service) DEPLOY_REGION=OVERSEAS ;;
     event-bridge-service)
       BRIDGE_REGION="${EVENT_BRIDGE_REGION_OVERRIDE:-}"
       if [ -z "$BRIDGE_REGION" ] && env_file_has_key REGION_CODE; then
@@ -60,7 +60,7 @@ done
 if [ "$DEPLOY_REGION" = "OVERSEAS" ]; then
   for service in $SERVICES; do
     case "$service" in
-      gateway-overseas|lastleg-service|warehouse-overseas-service|overseas-security-service|event-bridge-service) ;;
+      gateway-overseas|lastleg-service|warehouse-overseas-service|event-bridge-service) ;;
       *) echo "一次部署不得混合国内与海外服务: $SERVICE_CSV" >&2; exit 2 ;;
     esac
   done
@@ -80,17 +80,6 @@ if [ "$DEPLOY_REGION" = "OVERSEAS" ]; then
   done
 fi
 
-case " $SERVICES " in
-  *" overseas-security-service "*)
-    for key in OVERSEAS_SECURITY_DB_URL OVERSEAS_SECURITY_DB_USERNAME OVERSEAS_SECURITY_DB_PASSWORD; do
-      if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
-        echo "部署 overseas-security-service 时，环境文件必须包含非空 $key" >&2
-        exit 2
-      fi
-    done
-    ;;
-esac
-
 case " $SERVICES " in
   *" gateway-overseas "*)
     if ! env_file_has_key AUTH_SESSION_VALIDATION_URL || [ -z "$(env_file_value AUTH_SESSION_VALIDATION_URL)" ]; then

deploy/service-map.yml

@@ -8,11 +8,6 @@ services:
     jar: gateway-overseas/target/gateway-overseas-1.0.0-SNAPSHOT.jar
     port: 9300
     regions: [OVERSEAS]
-  overseas-security-service:
-    artifactId: overseas-security-service
-    jar: overseas-security-service/target/overseas-security-service-1.0.0-SNAPSHOT.jar
-    port: 9307
-    regions: [OVERSEAS]
   auth:
     artifactId: auth-service
     jar: auth/target/auth-service-1.0.0-SNAPSHOT.jar

deploy/sql/README.md

@@ -3,13 +3,14 @@
 ## 唯一数据库初始化与发布入口
 
 - 国内区域固定入口：`头程数据库统一增量-MySQL8.sql`。文件名保留历史兼容，内容维护为当前完整数据库基线和存量环境兼容升级，不再按日期拆分发布脚本。
-- 海外区域固定增量入口：`海外区域统一增量-MySQL8.sql`；空库先分别执行 `lastleg-service/src/main/resources/db/lastleg.sql`、`warehouse-overseas-service/src/main/resources/db/warehouse.sql` 与 `overseas-security-service/src/main/resources/db/overseas-security.sql` 基线，再执行该入口。固定入口升级 `baiyue_lastleg`、`baiyue_lastlag_warehouse` 与 `baiyue_overseas_security`，后者保存 IAM 安全事件消费者 Inbox 和可恢复投影；Redis 只作可重建镜像。
+- 海外区域固定增量入口：`海外区域统一增量-MySQL8.sql`；空库先分别执行 `lastleg-service/src/main/resources/db/lastleg.sql`与 `warehouse-overseas-service/src/main/resources/db/warehouse.sql` 基线，再执行该入口。固定入口会创建并校验独立的 `baiyue_event_bridge_overseas`，再升级 `baiyue_lastleg`与 `baiyue_lastlag_warehouse`；IAM 安全事件 Inbox 和可恢复投影已并入 `baiyue_lastleg.ll_security_*`，Redis 只作可重建镜像。
+- Lastleg 基线和海外固定增量仅确定性初始化国内固定 `platform_admin`（`authUserId=1000001`、`tenantId=0`）的 USER/AUTHORIZATION version=0 安全投影；其他既有开发账号不建立兼容表或长期补投入口。
 - 国内、海外 Compose 部署默认设置 `SPRING_SQL_INIT_MODE=never`，执行任一 SQL 均需用户单独授权。
 - 该脚本汇总一期、二期及已实现三期出仓能力的数据库基线、存量升级、IAM 权限资源和最终结构校验，适用于 MySQL 8.0。
 - 正式上线前的数据库变更直接维护该文件中的当前基线、存量兼容处理和最终校验，不再创建按日期拆分的发布 SQL；正式上线后的迁移策略在生产发布规范中另行冻结。
 - 当前测试环境尚未上线，船期价格表相关表、字段和索引只维护在现有初始化建表定义及本固定入口中，不向 `phase1-order-extension.sql`、`phase2-fba-pricing-migration.sql` 或新的增量脚本追加同一结构。
 - 模块 `src/main/resources/db/` 下的 SQL 用于开发溯源；`deploy/sql/` 下已有日期文件全部冻结为历史记录，不再单独部署，也不得与固定入口重复执行。
-- 固定入口不包含 `auth/phase1-admin-accounts.sql` 和 `warehouse/warehouse-seed.sql`；仅在开发/测试基线账号缺失时创建最小登录账号，重复执行不覆盖现有密码。脚本不写入演示订单；正式平台公共仓库主数据已内联到固定入口。
+- 固定入口不包含 `auth/phase1-admin-accounts.sql` 和 `warehouse/warehouse-seed.sql`；仅在开发/测试基线账号缺失时创建平台管理员，重复执行不覆盖现有密码。脚本不创建固定客户、客户账号或演示订单；客户必须通过正式建档/注册流程创建。正式平台公共仓库主数据已内联到固定入口；义乌、东莞、洛杉矶、纽约四个固定作业仓均初始化 `RECEIVING`，其中洛杉矶和纽约使用海外接柜入仓收货语义，FBA 目的地址不创建作业能力。
 - `warehouse/phase2-pallet-location-schema-migration.sql` 的有效结构已被当前 `phase2-pallet-location-schema.sql` 和后续共享溢出位迁移完整覆盖，因此不重复内联，避免每次部署无条件删除并重建同名唯一索引。
 - 脚本会创建 9 个独立数据库：`baiyue_auth`、`baiyue_iam`、`baiyue_order`、`baiyue_warehouse`、`baiyue_firstleg`、`baiyue_file`、`baiyue_audit`、`baiyue_event_bridge`、`baiyue_finance`。Gateway、Print、Integration Service 无数据库。
 - IAM 消息中心基线已内联到固定入口，包括 5 张 `iam_notification_*` 表、任务/事件幂等约束、平台消息管理权限、企业成员收件箱权限及默认角色授权；模块溯源脚本为 `iam/src/main/resources/db/notification-center.sql`。

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

@@ -278,7 +278,7 @@ PREPARE auth_password_change_required_stmt FROM @auth_password_change_required_s
 EXECUTE auth_password_change_required_stmt;
 DEALLOCATE PREPARE auth_password_change_required_stmt;
 
--- 开发/测试环境最小登录基线：一个平台系统管理员和一个 IT 测试客户管理员。
+-- 开发/测试环境最小登录基线只保留平台系统管理员；客户必须走正式建档/注册流程创建。
 -- 缺失账号首次创建时写入开发基线 BCrypt 哈希；重复执行统一增量绝不覆盖现有密码。
 INSERT INTO auth_account (
   id, username, password_hash, display_name, account_status,
@@ -286,9 +286,7 @@ INSERT INTO auth_account (
   operator_tenant_id, default_membership_id, default_app_code, deleted
 ) VALUES
   (1000001, 'platform_admin', '$2a$12$AMZJjd88leYPLI9uKvjZiew2CTQXI32BXoHFX.FrCi28/IeZ7mZ96',
-   '平台系统管理员', 'ACTIVE', 0, 1, 0, 0, 0, 3000001, 'PLATFORM', 0),
-  (1000002, 'merchant_admin', '$2a$12$AMZJjd88leYPLI9uKvjZiew2CTQXI32BXoHFX.FrCi28/IeZ7mZ96',
-   'IT 测试客户管理员', 'ACTIVE', 0, 1, 0, 10001, 10001, 3000002, 'MERCHANT', 0)
+   '平台系统管理员', 'ACTIVE', 0, 1, 0, 0, 0, 3000001, 'PLATFORM', 0)
 ON DUPLICATE KEY UPDATE
   display_name = VALUES(display_name),
   account_status = 'ACTIVE',
@@ -892,6 +890,7 @@ CREATE TABLE IF NOT EXISTS wh_partner (
  data_scope_id BIGINT UNSIGNED NOT NULL COMMENT '所属业务数据范围',
  partner_code VARCHAR(50) NOT NULL COMMENT '平台内唯一往来单位编码', partner_name VARCHAR(128) NOT NULL COMMENT '往来单位名称',
  partner_type VARCHAR(20) NOT NULL COMMENT '往来单位类型：CARRIER、SHIPPER或CONSIGNEE',
+ carrier_code VARCHAR(16) NULL COMMENT '船司标准编码：MATSON、SML、ZIM、COSCO、EMC、HEDE或OTHER；仅CARRIER必填',
  contact_name VARCHAR(64) NOT NULL COMMENT '联系人姓名', contact_phone VARCHAR(32) NOT NULL COMMENT '联系电话',
  contact_email VARCHAR(128) NULL COMMENT '联系邮箱', country_code CHAR(2) NOT NULL COMMENT '国家二字码',
  province VARCHAR(64) NULL COMMENT '省或州', city VARCHAR(64) NOT NULL COMMENT '城市', district VARCHAR(64) NULL COMMENT '区县',
@@ -903,7 +902,8 @@ CREATE TABLE IF NOT EXISTS wh_partner (
  deleted TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除标记：0未删除、1已删除', version INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
  PRIMARY KEY(id), UNIQUE KEY uk_wh_partner_tenant_code(tenant_id,partner_code,deleted),
  KEY idx_wh_partner_tenant_status(tenant_id,status,deleted),
- CONSTRAINT chk_wh_partner_type CHECK (partner_type IN ('CARRIER','SHIPPER','CONSIGNEE'))
+ CONSTRAINT chk_wh_partner_type CHECK (partner_type IN ('CARRIER','SHIPPER','CONSIGNEE')),
+ CONSTRAINT chk_wh_partner_carrier_code CHECK (carrier_code IS NULL OR carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER'))
 ) ENGINE=InnoDB COMMENT='平台统一维护、供全部客户共享的往来单位主数据';
 CREATE TABLE IF NOT EXISTS wh_partner_type (
  partner_id BIGINT UNSIGNED NOT NULL COMMENT '往来单位ID', tenant_id BIGINT UNSIGNED NOT NULL COMMENT '平台公共往来单位固定使用 tenant_id=0',
@@ -1194,10 +1194,7 @@ INSERT INTO iam_tenant (
   approved_at, approved_by, created_by, deleted, version
 ) VALUES
   (0, 'PLATFORM', '虫虫出海平台', 'PLATFORM', 'ACTIVE', '虫虫出海平台',
-   NULL, '平台系统管理员', NULL, NULL, NOW(3), 1000001, 1000001, 0, 0),
-  (10001, 'IT_TEST', 'IT 测试客户', 'MERCHANT', 'ACTIVE', 'IT 测试客户',
-   '91310000ITTEST0001', 'IT 测试客户管理员', '13800000000', 'it-test@example.com',
-   NOW(3), 1000001, 1000001, 0, 0)
+   NULL, '平台系统管理员', NULL, NULL, NOW(3), 1000001, 1000001, 0, 0)
 ON DUPLICATE KEY UPDATE
   tenant_code = VALUES(tenant_code), tenant_name = VALUES(tenant_name), tenant_type = VALUES(tenant_type),
   status = 'ACTIVE', legal_name = VALUES(legal_name),
@@ -1206,28 +1203,10 @@ ON DUPLICATE KEY UPDATE
   contact_email = VALUES(contact_email), approved_at = COALESCE(approved_at, NOW(3)),
   approved_by = VALUES(approved_by), deleted = 0;
 
--- The built-in IT customer must be immediately usable for order acceptance tests.
--- These approved metadata rows intentionally have no document URL: initialization must not
--- point at qualification files that do not exist in File service storage.
-INSERT INTO iam_tenant_qualification (
-  id, tenant_id, qualification_type, certificate_no, document_url,
-  valid_from, valid_to, status, review_comment, deleted
-) VALUES
-  (2100001, 10001, 'BUSINESS_LICENSE', '91310000ITTEST0001', NULL,
-   NULL, NULL, 'APPROVED', '开发测试初始化资质，无文件附件', 0),
-  (2100002, 10001, 'LEGAL_PERSON_ID', NULL, NULL,
-   NULL, NULL, 'APPROVED', '开发测试初始化资质，无文件附件', 0)
-ON DUPLICATE KEY UPDATE
-  tenant_id = VALUES(tenant_id), qualification_type = VALUES(qualification_type),
-  certificate_no = VALUES(certificate_no), status = 'APPROVED',
-  review_comment = VALUES(review_comment), deleted = 0;
-
 INSERT INTO iam_user (
   id, auth_user_id, user_type, display_name, phone, email, status, deleted, version
 ) VALUES
-  (2000001, 1000001, 'INTERNAL', '平台系统管理员', NULL, NULL, 'ACTIVE', 0, 0),
-  (2000002, 1000002, 'ENTERPRISE', 'IT 测试客户管理员', '13800000000',
-   'it-test@example.com', 'ACTIVE', 0, 0)
+  (2000001, 1000001, 'INTERNAL', '平台系统管理员', NULL, NULL, 'ACTIVE', 0, 0)
 ON DUPLICATE KEY UPDATE
   display_name = VALUES(display_name), phone = VALUES(phone), email = VALUES(email),
   status = 'ACTIVE', deleted = 0;
@@ -1235,8 +1214,7 @@ ON DUPLICATE KEY UPDATE
 INSERT INTO iam_membership (
   id, tenant_id, user_id, member_type, member_no, status, joined_at, deleted, version
 ) VALUES
-  (3000001, 0, 2000001, 'EMPLOYEE', 'PLATFORM-ADMIN-001', 'ACTIVE', NOW(3), 0, 0),
-  (3000002, 10001, 2000002, 'OWNER', 'MERCHANT-OWNER-001', 'ACTIVE', NOW(3), 0, 0)
+  (3000001, 0, 2000001, 'EMPLOYEE', 'PLATFORM-ADMIN-001', 'ACTIVE', NOW(3), 0, 0)
 ON DUPLICATE KEY UPDATE
   member_type = VALUES(member_type), member_no = VALUES(member_no),
   status = 'ACTIVE', joined_at = COALESCE(joined_at, NOW(3)), left_at = NULL, deleted = 0;
@@ -1246,9 +1224,7 @@ INSERT INTO iam_role (
 ) VALUES
   (4000001, 0, 'PLATFORM', 'PLATFORM_ADMIN', '平台超级管理员', 'SYSTEM', 'ACTIVE', '一期平台全部菜单和按钮', 0, 0),
   (4000002, 0, 'PLATFORM', 'CUSTOMER_REVIEWER', '企业审核员', 'SYSTEM', 'ACTIVE', '企业资料与入驻审核', 0, 0),
-  (4000003, 0, 'PLATFORM', 'ORDER_OPERATOR', '平台订单运营', 'SYSTEM', 'ACTIVE', '头程订单审核与履约处理', 0, 0),
-  (4000101, 10001, 'MERCHANT', 'MERCHANT_OWNER', '企业管理员', 'SYSTEM', 'ACTIVE', '本企业一期全部菜单和按钮', 0, 0),
-  (4000102, 10001, 'MERCHANT', 'MERCHANT_ORDER_MANAGER', '企业订单管理员', 'SYSTEM', 'ACTIVE', '本企业头程订单操作', 0, 0)
+  (4000003, 0, 'PLATFORM', 'ORDER_OPERATOR', '平台订单运营', 'SYSTEM', 'ACTIVE', '头程订单审核与履约处理', 0, 0)
 ON DUPLICATE KEY UPDATE
   role_name = VALUES(role_name), role_type = VALUES(role_type), status = 'ACTIVE',
   description = VALUES(description), deleted = 0;
@@ -1335,39 +1311,8 @@ SELECT 4000003, id, 0 FROM iam_permission
 WHERE id IN (5102019, 5102024, 5102025)
 ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
 
--- Merchant: level-one menus, level-two menus and buttons.
-INSERT INTO iam_permission
-  (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, deleted)
-VALUES
-  (5200000, 10001, 'MERCHANT', 'MENU', 0, 'merchant:enterprise', '企业管理', '/enterprise', NULL, 10, 'ACTIVE', 0),
-  (5201000, 10001, 'MERCHANT', 'MENU', 0, 'merchant:order', '头程订单', '/first-leg-orders', NULL, 20, 'ACTIVE', 0),
-  (5202000, 10001, 'MERCHANT', 'MENU', 0, 'merchant:master-data', '基础资料', '/master-data', NULL, 30, 'ACTIVE', 0),
-  (5200010, 10001, 'MERCHANT', 'MENU', 5200000, 'merchant:profile:view', '企业资料', '/enterprise/profile', NULL, 10, 'ACTIVE', 0),
-  (5200020, 10001, 'MERCHANT', 'MENU', 5200000, 'merchant:member:list', '企业成员', '/enterprise/members', NULL, 20, 'ACTIVE', 0),
-  (5200030, 10001, 'MERCHANT', 'MENU', 5200000, 'merchant:role:list', '角色管理', '/enterprise/roles', NULL, 30, 'ACTIVE', 0),
-  (5201010, 10001, 'MERCHANT', 'MENU', 5201000, 'merchant:order:list', '我的订单', '/first-leg-orders/list', NULL, 10, 'ACTIVE', 0),
-  (5201020, 10001, 'MERCHANT', 'MENU', 5201000, 'merchant:order:create-page', '新建订单', '/first-leg-orders/create', NULL, 20, 'ACTIVE', 0),
-  (5202010, 10001, 'MERCHANT', 'MENU', 5202000, 'merchant:warehouse:list', '收货仓选择', '/master-data/warehouses', NULL, 10, 'ACTIVE', 0),
-  (5202020, 10001, 'MERCHANT', 'MENU', 5202000, 'merchant:counterparty:list', '往来单位', '/master-data/counterparties', NULL, 20, 'ACTIVE', 0),
-  (5200011, 10001, 'MERCHANT', 'BUTTON', 5200010, 'merchant:profile:edit', '编辑企业资料', NULL, NULL, 10, 'ACTIVE', 0),
-  (5200012, 10001, 'MERCHANT', 'BUTTON', 5200010, 'merchant:qualification:upload', '上传企业资质', NULL, NULL, 20, 'ACTIVE', 0),
-  (5200021, 10001, 'MERCHANT', 'BUTTON', 5200020, 'merchant:member:create', '新增成员', NULL, NULL, 10, 'ACTIVE', 0),
-  (5200022, 10001, 'MERCHANT', 'BUTTON', 5200020, 'merchant:member:grant-role', '分配角色', NULL, NULL, 20, 'ACTIVE', 0),
-  (5200031, 10001, 'MERCHANT', 'BUTTON', 5200030, 'merchant:role:create', '新增角色', NULL, NULL, 10, 'ACTIVE', 0),
-  (5200032, 10001, 'MERCHANT', 'BUTTON', 5200030, 'merchant:role:grant', '角色授权', NULL, NULL, 20, 'ACTIVE', 0),
-  (5201011, 10001, 'MERCHANT', 'BUTTON', 5201010, 'merchant:order:view', '查看订单', NULL, NULL, 10, 'ACTIVE', 0),
-  (5201012, 10001, 'MERCHANT', 'BUTTON', 5201010, 'merchant:order:cancel', '取消订单', NULL, NULL, 20, 'ACTIVE', 0),
-  (5201021, 10001, 'MERCHANT', 'BUTTON', 5201020, 'merchant:order:create', '创建草稿', NULL, NULL, 10, 'ACTIVE', 0),
-  (5201022, 10001, 'MERCHANT', 'BUTTON', 5201020, 'merchant:order:edit', '编辑草稿', NULL, NULL, 20, 'ACTIVE', 0),
-  (5201023, 10001, 'MERCHANT', 'BUTTON', 5201020, 'merchant:order:submit', '提交订单', NULL, NULL, 30, 'ACTIVE', 0)
-ON DUPLICATE KEY UPDATE
-  permission_type = VALUES(permission_type), parent_id = VALUES(parent_id),
-  permission_name = VALUES(permission_name), route_path = VALUES(route_path),
-  http_method = NULL, sort_no = VALUES(sort_no), status = 'ACTIVE', deleted = 0;
-
 INSERT INTO iam_membership_role (membership_id, role_id, tenant_id) VALUES
-  (3000001, 4000001, 0),
-  (3000002, 4000101, 10001)
+  (3000001, 4000001, 0)
 ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
 
 -- Full administrator roles receive all phase-one permissions in their application scope.
@@ -1376,11 +1321,6 @@ SELECT 4000001, id, 0 FROM iam_permission
 WHERE app_code = 'PLATFORM' AND tenant_id = 0 AND permission_type IN ('MENU', 'BUTTON')
 ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
 
-INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
-SELECT 4000101, id, 10001 FROM iam_permission
-WHERE app_code = 'MERCHANT' AND tenant_id = 10001 AND permission_type IN ('MENU', 'BUTTON')
-ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
-
 -- Limited platform and merchant operational roles.
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
 SELECT 4000002, id, 0 FROM iam_permission
@@ -1396,17 +1336,10 @@ SELECT 4000003, id, 0 FROM iam_permission
 WHERE permission_code LIKE 'platform:order%' OR permission_code LIKE 'platform:firstleg%'
 ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
 
-INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
-SELECT 4000102, id, 10001 FROM iam_permission
-WHERE permission_code LIKE 'merchant:order%' OR permission_code IN ('merchant:master-data', 'merchant:warehouse:list')
-ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
-
 INSERT INTO iam_data_scope (id, role_id, tenant_id, scope_type, scope_expression) VALUES
   (6000001, 4000001, 0, 'TENANT', NULL),
   (6000002, 4000002, 0, 'TENANT', NULL),
-  (6000003, 4000003, 0, 'TENANT', NULL),
-  (6000101, 4000101, 10001, 'TENANT', NULL),
-  (6000102, 4000102, 10001, 'TENANT', NULL)
+  (6000003, 4000003, 0, 'TENANT', NULL)
 ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id), scope_type = VALUES(scope_type), scope_expression = NULL;
 
 -- ============================================================================
@@ -1455,17 +1388,34 @@ INSERT INTO iam_role (
 )
 ON DUPLICATE KEY UPDATE status='ACTIVE', deleted=0;
 
--- Clone the一期 merchant menu/button template into the global scope.
+-- Global merchant permission template used by every formally onboarded customer.
 INSERT INTO iam_permission (
   id, tenant_id, app_code, permission_type, parent_id, permission_code,
   permission_name, route_path, http_method, sort_no, status, deleted
 )
-SELECT id + 100000, 0, app_code, permission_type,
-       CASE WHEN parent_id = 0 THEN 0 ELSE parent_id + 100000 END,
-       permission_code, permission_name, route_path, NULL, sort_no, 'ACTIVE', 0
-FROM iam_permission
-WHERE tenant_id = 10001 AND app_code = 'MERCHANT'
-  AND permission_type IN ('MENU', 'BUTTON')
+VALUES
+  (5300000, 0, 'MERCHANT', 'MENU', 0, 'merchant:enterprise', '企业管理', '/enterprise', NULL, 10, 'ACTIVE', 0),
+  (5301000, 0, 'MERCHANT', 'MENU', 0, 'merchant:order', '头程订单', '/first-leg-orders', NULL, 20, 'ACTIVE', 0),
+  (5302000, 0, 'MERCHANT', 'MENU', 0, 'merchant:master-data', '基础资料', '/master-data', NULL, 30, 'ACTIVE', 0),
+  (5300010, 0, 'MERCHANT', 'MENU', 5300000, 'merchant:profile:view', '企业资料', '/enterprise/profile', NULL, 10, 'ACTIVE', 0),
+  (5300020, 0, 'MERCHANT', 'MENU', 5300000, 'merchant:member:list', '企业成员', '/enterprise/members', NULL, 20, 'ACTIVE', 0),
+  (5300030, 0, 'MERCHANT', 'MENU', 5300000, 'merchant:role:list', '角色管理', '/enterprise/roles', NULL, 30, 'ACTIVE', 0),
+  (5301010, 0, 'MERCHANT', 'MENU', 5301000, 'merchant:order:list', '我的订单', '/first-leg-orders/list', NULL, 10, 'ACTIVE', 0),
+  (5301020, 0, 'MERCHANT', 'MENU', 5301000, 'merchant:order:create-page', '新建订单', '/first-leg-orders/create', NULL, 20, 'ACTIVE', 0),
+  (5302010, 0, 'MERCHANT', 'MENU', 5302000, 'merchant:warehouse:list', '收货仓选择', '/master-data/warehouses', NULL, 10, 'ACTIVE', 0),
+  (5302020, 0, 'MERCHANT', 'MENU', 5302000, 'merchant:counterparty:list', '往来单位', '/master-data/counterparties', NULL, 20, 'ACTIVE', 0),
+  (5300011, 0, 'MERCHANT', 'BUTTON', 5300010, 'merchant:profile:edit', '编辑企业资料', NULL, NULL, 10, 'ACTIVE', 0),
+  (5300012, 0, 'MERCHANT', 'BUTTON', 5300010, 'merchant:qualification:upload', '上传企业资质', NULL, NULL, 20, 'ACTIVE', 0),
+  (5300021, 0, 'MERCHANT', 'BUTTON', 5300020, 'merchant:member:create', '新增成员', NULL, NULL, 10, 'ACTIVE', 0),
+  (5300022, 0, 'MERCHANT', 'BUTTON', 5300020, 'merchant:member:grant-role', '分配成员角色', NULL, NULL, 20, 'ACTIVE', 0),
+  (5300031, 0, 'MERCHANT', 'BUTTON', 5300030, 'merchant:role:create', '新增角色', NULL, NULL, 10, 'ACTIVE', 0),
+  (5300032, 0, 'MERCHANT', 'BUTTON', 5300030, 'merchant:role:grant', '角色授权', NULL, NULL, 20, 'ACTIVE', 0),
+  (5301011, 0, 'MERCHANT', 'BUTTON', 5301010, 'merchant:order:view', '查看订单', NULL, NULL, 10, 'ACTIVE', 0),
+  (5301012, 0, 'MERCHANT', 'BUTTON', 5301010, 'merchant:order:cancel', '取消订单', NULL, NULL, 20, 'ACTIVE', 0),
+  (5301021, 0, 'MERCHANT', 'BUTTON', 5301020, 'merchant:order:create', '创建草稿', NULL, NULL, 10, 'ACTIVE', 0),
+  (5301022, 0, 'MERCHANT', 'BUTTON', 5301020, 'merchant:order:edit', '编辑草稿', NULL, NULL, 20, 'ACTIVE', 0),
+  (5301023, 0, 'MERCHANT', 'BUTTON', 5301020, 'merchant:order:submit', '提交订单', NULL, NULL, 30, 'ACTIVE', 0),
+  (5301024, 0, 'MERCHANT', 'BUTTON', 5301020, 'merchant:order:quick-create', '快速下单', NULL, NULL, 40, 'ACTIVE', 0)
 ON DUPLICATE KEY UPDATE
   permission_name=VALUES(permission_name), route_path=VALUES(route_path),
   parent_id=VALUES(parent_id), sort_no=VALUES(sort_no), status='ACTIVE', deleted=0;
@@ -1507,20 +1457,11 @@ DEALLOCATE PREPARE member_no_index_stmt;
 INSERT INTO iam_permission
   (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, sort_no, status, deleted)
 VALUES
-  (5200023, 10001, 'MERCHANT', 'BUTTON', 5200020, 'merchant:member:edit', '编辑成员', 30, 'ACTIVE', 0),
-  (5200024, 10001, 'MERCHANT', 'BUTTON', 5200020, 'merchant:member:status', '启停成员', 40, 'ACTIVE', 0),
-  (5200025, 10001, 'MERCHANT', 'BUTTON', 5200020, 'merchant:member:reset-password', '重置成员密码', 50, 'ACTIVE', 0),
   (5300023, 0, 'MERCHANT', 'BUTTON', 5300020, 'merchant:member:edit', '编辑成员', 30, 'ACTIVE', 0),
   (5300024, 0, 'MERCHANT', 'BUTTON', 5300020, 'merchant:member:status', '启停成员', 40, 'ACTIVE', 0),
   (5300025, 0, 'MERCHANT', 'BUTTON', 5300020, 'merchant:member:reset-password', '重置成员密码', 50, 'ACTIVE', 0)
 ON DUPLICATE KEY UPDATE permission_name = VALUES(permission_name), status = VALUES(status), deleted = 0;
 
-INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
-SELECT 4000101, id, 10001 FROM iam_permission
-WHERE tenant_id = 10001 AND permission_code IN
-  ('merchant:member:edit', 'merchant:member:status', 'merchant:member:reset-password')
-ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
-
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
 SELECT 4000100, id, 0 FROM iam_permission
 WHERE tenant_id = 0 AND permission_code IN
@@ -1548,9 +1489,6 @@ VALUES
   (5101013, 0, 'PLATFORM', 'BUTTON', 5101010, 'platform:user:status', '启停用户', 30, 'ACTIVE', 0),
   (5101014, 0, 'PLATFORM', 'BUTTON', 5101010, 'platform:user:reset-password', '重置密码', 40, 'ACTIVE', 0),
   (5101015, 0, 'PLATFORM', 'BUTTON', 5101010, 'platform:user:grant-role', '分配内部用户角色', 50, 'ACTIVE', 0),
-  (5200033, 10001, 'MERCHANT', 'BUTTON', 5200030, 'merchant:role:edit', '编辑角色', 30, 'ACTIVE', 0),
-  (5200034, 10001, 'MERCHANT', 'BUTTON', 5200030, 'merchant:role:status', '启停角色', 40, 'ACTIVE', 0),
-  (5200035, 10001, 'MERCHANT', 'BUTTON', 5200030, 'merchant:role:delete', '删除角色', 50, 'ACTIVE', 0),
   (5300033, 0, 'MERCHANT', 'BUTTON', 5300030, 'merchant:role:edit', '编辑角色', 30, 'ACTIVE', 0),
   (5300034, 0, 'MERCHANT', 'BUTTON', 5300030, 'merchant:role:status', '启停角色', 40, 'ACTIVE', 0),
   (5300035, 0, 'MERCHANT', 'BUTTON', 5300030, 'merchant:role:delete', '删除角色', 50, 'ACTIVE', 0)
@@ -1569,12 +1507,6 @@ WHERE tenant_id = 0 AND app_code = 'PLATFORM'
                           'platform:user:grant-role')
 ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
 
-INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
-SELECT 4000101, id, 10001 FROM iam_permission
-WHERE tenant_id = 10001 AND app_code = 'MERCHANT'
-  AND permission_code IN ('merchant:role:edit', 'merchant:role:status', 'merchant:role:delete')
-ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
-
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
 SELECT 4000100, id, 0 FROM iam_permission
 WHERE tenant_id = 0 AND app_code = 'MERCHANT'
@@ -1942,7 +1874,8 @@ CALL add_column_if_missing('wh_partner', 'tenant_id', 'BIGINT UNSIGNED NOT NULL
 CALL add_column_if_missing('wh_partner', 'partner_code', 'VARCHAR(50) NOT NULL DEFAULT '''' AFTER tenant_id');
 CALL add_column_if_missing('wh_partner', 'partner_name', 'VARCHAR(128) NOT NULL DEFAULT '''' AFTER partner_code');
 CALL add_column_if_missing('wh_partner', 'partner_type', 'VARCHAR(20) NOT NULL DEFAULT ''CUSTOMER'' AFTER partner_name');
-CALL add_column_if_missing('wh_partner', 'contact_name', 'VARCHAR(64) NOT NULL DEFAULT '''' AFTER partner_type');
+CALL add_column_if_missing('wh_partner', 'carrier_code', 'VARCHAR(16) NULL COMMENT ''船司标准编码：MATSON、SML、ZIM、COSCO、EMC、HEDE或OTHER；仅CARRIER必填'' AFTER partner_type');
+CALL add_column_if_missing('wh_partner', 'contact_name', 'VARCHAR(64) NOT NULL DEFAULT '''' AFTER carrier_code');
 CALL add_column_if_missing('wh_partner', 'contact_phone', 'VARCHAR(32) NOT NULL DEFAULT '''' AFTER contact_name');
 CALL add_column_if_missing('wh_partner', 'contact_email', 'VARCHAR(128) NULL');
 CALL add_column_if_missing('wh_partner', 'country_code', 'CHAR(2) NOT NULL DEFAULT ''CN'' AFTER contact_email');
@@ -1958,6 +1891,8 @@ CALL add_column_if_missing('wh_partner', 'updated_by', 'BIGINT UNSIGNED NULL');
 CALL add_column_if_missing('wh_partner', 'updated_at', 'DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)');
 CALL add_column_if_missing('wh_partner', 'deleted', 'TINYINT(1) NOT NULL DEFAULT 0');
 CALL add_column_if_missing('wh_partner', 'version', 'INT NOT NULL DEFAULT 0');
+UPDATE wh_partner SET carrier_code = 'OTHER'
+ WHERE id = 191000000000000001 AND partner_type = 'CARRIER' AND carrier_code IS NULL;
 
 -- 该表在旧库中不存在时先由 warehouse-express-company.sql 建表；此段补齐早期部署缺列。
 CALL add_column_if_missing('wh_express_company', 'tenant_id', 'BIGINT UNSIGNED NOT NULL DEFAULT 0 AFTER id');
@@ -2567,6 +2502,7 @@ CREATE TABLE IF NOT EXISTS fl_inbound_order (
   destination_name VARCHAR(128) NULL COMMENT '目的仓名称快照',
   hold_flag TINYINT(1) NOT NULL DEFAULT 0 COMMENT '当前是否扣货',
   current_hold_reason VARCHAR(500) NULL COMMENT '当前扣货理由快照',
+  last_overseas_hold_version BIGINT UNSIGNED NULL COMMENT '海外暂扣事件最新聚合版本，用于阻止乱序覆盖',
   total_package_count INT UNSIGNED NULL COMMENT '确认后的总箱数',
   actual_gross_weight_kg DECIMAL(18,3) NULL COMMENT '确认后的实际总毛重kg',
   chargeable_weight_kg DECIMAL(18,3) NULL COMMENT '当前费用快照的计费重量kg',
@@ -2856,6 +2792,7 @@ CREATE TABLE IF NOT EXISTS fl_inbound_carton_label (
   inbound_detail_id BIGINT UNSIGNED NOT NULL COMMENT '订单货物明细ID，不建立跨库外键',
   cargo_item_no INT UNSIGNED NOT NULL COMMENT '订单货物明细序号快照',
   cargo_name VARCHAR(255) NULL COMMENT '货物名称快照',
+  sku_code VARCHAR(128) NULL COMMENT '箱唛绑定的SKU快照；二维码内容不变',
   detail_package_count INT UNSIGNED NOT NULL COMMENT '该订单货物明细箱数快照',
   inbound_code VARCHAR(40) NOT NULL COMMENT '入仓码快照',
   box_code VARCHAR(80) NOT NULL COMMENT '固定二维码内容：入仓码#总箱数-箱下标',
@@ -2893,6 +2830,7 @@ BEGIN
 END$$
 DELIMITER ;
 CALL unified_carton_label_add_column('label_version', 'INT UNSIGNED NOT NULL DEFAULT 1 COMMENT ''内部兼容批次字段，固定为1且不进入箱码'' AFTER carton_index');
+CALL unified_carton_label_add_column('sku_code', 'VARCHAR(128) NULL COMMENT ''箱唛绑定的SKU快照；二维码内容不变'' AFTER cargo_name');
 CALL unified_carton_label_add_column('batch_status', 'VARCHAR(16) NOT NULL DEFAULT ''ACTIVE'' COMMENT ''批次状态：ACTIVE有效、VOID已作废'' AFTER label_version');
 CALL unified_carton_label_add_column('cargo_fingerprint', 'CHAR(64) NULL COMMENT ''影响标签字段的SHA-256指纹'' AFTER batch_status');
 CALL unified_carton_label_add_column('voided_at', 'DATETIME(3) NULL COMMENT ''批次作废时间'' AFTER cargo_fingerprint');
@@ -4286,23 +4224,9 @@ SET @unified_ddl = IF(
 PREPARE unified_stmt FROM @unified_ddl; EXECUTE unified_stmt; DEALLOCATE PREPARE unified_stmt;
 
 -- ============================================================================
--- 重新同步一期商户管理员全局模板，包含一期后续追加的菜单和按钮
+-- 重新授权一期商户管理员全局模板，包含一期后续追加的菜单和按钮
 -- ============================================================================
 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, deleted
-)
-SELECT id + 100000, 0, app_code, permission_type,
-       CASE WHEN parent_id = 0 THEN 0 ELSE parent_id + 100000 END,
-       permission_code, permission_name, route_path, NULL, sort_no, 'ACTIVE', 0
-FROM iam_permission
-WHERE tenant_id = 10001 AND app_code = 'MERCHANT'
-  AND permission_type IN ('MENU', 'BUTTON')
-ON DUPLICATE KEY UPDATE
-  permission_name = VALUES(permission_name), route_path = VALUES(route_path),
-  parent_id = VALUES(parent_id), sort_no = VALUES(sort_no), status = 'ACTIVE', deleted = 0;
-
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
 SELECT owner_role.id, permission.id, 0
 FROM iam_role owner_role
@@ -5034,11 +4958,14 @@ BEGIN
     ALTER TABLE fl_container_booking ADD COLUMN customer_name VARCHAR(128) NULL
       COMMENT '已关联真实订舱客户名称快照' AFTER customer_id;
   END IF;
-  UPDATE fl_container_booking container_booking
-  JOIN fl_ocean_booking ocean_booking ON ocean_booking.id=container_booking.ocean_booking_id
-     SET container_booking.customer_id=COALESCE(container_booking.customer_id,ocean_booking.customer_id),
-         container_booking.customer_name=COALESCE(container_booking.customer_name,ocean_booking.customer_name)
-   WHERE container_booking.customer_id IS NULL OR container_booking.customer_name IS NULL;
+  IF EXISTS (SELECT 1 FROM information_schema.tables WHERE table_schema=DATABASE()
+      AND table_name='fl_ocean_booking') THEN
+    UPDATE fl_container_booking container_booking
+    JOIN fl_ocean_booking ocean_booking ON ocean_booking.id=container_booking.ocean_booking_id
+       SET container_booking.customer_id=COALESCE(container_booking.customer_id,ocean_booking.customer_id),
+           container_booking.customer_name=COALESCE(container_booking.customer_name,ocean_booking.customer_name)
+     WHERE container_booking.customer_id IS NULL OR container_booking.customer_name IS NULL;
+  END IF;
   IF NOT EXISTS (SELECT 1 FROM information_schema.statistics WHERE table_schema=DATABASE()
       AND table_name='fl_container_booking' AND index_name='uk_container_booking_container_no') THEN
     ALTER TABLE fl_container_booking ADD UNIQUE KEY uk_container_booking_container_no (container_no);
@@ -5498,6 +5425,66 @@ CREATE TABLE IF NOT EXISTS fl_loading_pick_history (
   CONSTRAINT fk_loading_pick_history_item FOREIGN KEY (pick_item_id) REFERENCES fl_loading_pick_item (id)
 ) ENGINE=InnoDB COMMENT='PDA拣货幂等和操作审计历史';
 
+CREATE TABLE IF NOT EXISTS fl_loading_work_pallet (
+  id BIGINT UNSIGNED NOT NULL COMMENT '一件代发现场作业托盘ID',
+  pick_task_id BIGINT UNSIGNED NOT NULL COMMENT 'PDA装柜拣货任务ID',
+  loading_plan_id BIGINT UNSIGNED NOT NULL COMMENT '装柜计划ID快照',
+  warehouse_id BIGINT UNSIGNED NOT NULL COMMENT '作业仓库ID',
+  warehouse_pallet_id BIGINT UNSIGNED NULL COMMENT '仓库实物托盘ID；未绑定仓库资源时为空',
+  pallet_code VARCHAR(64) NOT NULL COMMENT '现场托盘号',
+  open_operation_id VARCHAR(128) NOT NULL COMMENT '开托幂等操作号',
+  seal_operation_id VARCHAR(128) NULL COMMENT '封托幂等操作号',
+  pallet_status VARCHAR(16) NOT NULL DEFAULT 'OPEN' COMMENT '托盘状态：OPEN打托中、SEALED已封托、CANCELLED已取消',
+  created_by BIGINT UNSIGNED NOT NULL COMMENT '创建操作人ID',
+  created_by_name VARCHAR(64) NULL COMMENT '创建操作人名称快照',
+  sealed_by BIGINT UNSIGNED NULL COMMENT '封托操作人ID',
+  sealed_by_name VARCHAR(64) NULL COMMENT '封托操作人名称快照',
+  sealed_at DATETIME(3) NULL COMMENT '封托时间',
+  version INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_loading_work_pallet_code (pick_task_id, pallet_code),
+  UNIQUE KEY uk_loading_work_pallet_open_operation (open_operation_id),
+  UNIQUE KEY uk_loading_work_pallet_seal_operation (seal_operation_id),
+  KEY idx_loading_work_pallet_plan (loading_plan_id, pallet_status, id),
+  CONSTRAINT fk_loading_work_pallet_task FOREIGN KEY (pick_task_id) REFERENCES fl_loading_pick_task (id),
+  CONSTRAINT fk_loading_work_pallet_plan FOREIGN KEY (loading_plan_id) REFERENCES fl_loading_plan (id),
+  CONSTRAINT chk_loading_work_pallet_status CHECK (pallet_status IN ('OPEN','SEALED','CANCELLED'))
+) ENGINE=InnoDB COMMENT='一件代发PDA现场实际托盘；允许同托盘承载多个客户订单';
+
+CREATE TABLE IF NOT EXISTS fl_loading_work_pallet_carton (
+  id BIGINT UNSIGNED NOT NULL COMMENT '一件代发现场托盘箱唛绑定ID',
+  pick_task_id BIGINT UNSIGNED NOT NULL COMMENT 'PDA装柜拣货任务ID',
+  work_pallet_id BIGINT UNSIGNED NOT NULL COMMENT '现场作业托盘ID',
+  loading_plan_item_id BIGINT UNSIGNED NOT NULL COMMENT '装柜计划货物明细ID',
+  pick_item_id BIGINT UNSIGNED NOT NULL COMMENT 'PDA拣货明细ID',
+  tenant_id BIGINT UNSIGNED NOT NULL COMMENT '箱唛所属客户ID',
+  inbound_id BIGINT UNSIGNED NOT NULL COMMENT '来源入仓单ID',
+  inbound_detail_id BIGINT UNSIGNED NOT NULL COMMENT '来源入仓货物明细ID',
+  carton_label_id BIGINT UNSIGNED NOT NULL COMMENT '稳定箱唛记录ID',
+  box_code VARCHAR(80) NOT NULL COMMENT '稳定箱唛箱码快照',
+  sku_code VARCHAR(128) NOT NULL COMMENT 'SKU编码快照',
+  units_per_carton INT UNSIGNED NULL COMMENT '每箱产品数量快照',
+  bound_by BIGINT UNSIGNED NOT NULL COMMENT '最后绑定操作人ID',
+  bound_by_name VARCHAR(64) NULL COMMENT '最后绑定操作人名称快照',
+  operation_id VARCHAR(128) NOT NULL COMMENT '最近一次绑定或移托幂等操作号',
+  version INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '首次上托时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '最后移托时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_loading_work_carton_task_label (pick_task_id, carton_label_id),
+  UNIQUE KEY uk_loading_work_carton_operation (operation_id),
+  KEY idx_loading_work_carton_pallet (work_pallet_id, sku_code, id),
+  KEY idx_loading_work_carton_plan_item (loading_plan_item_id, id),
+  CONSTRAINT fk_loading_work_carton_task FOREIGN KEY (pick_task_id) REFERENCES fl_loading_pick_task (id),
+  CONSTRAINT fk_loading_work_carton_pallet FOREIGN KEY (work_pallet_id) REFERENCES fl_loading_work_pallet (id),
+  CONSTRAINT fk_loading_work_carton_plan_item FOREIGN KEY (loading_plan_item_id) REFERENCES fl_loading_plan_item (id),
+  CONSTRAINT fk_loading_work_carton_pick_item FOREIGN KEY (pick_item_id) REFERENCES fl_loading_pick_item (id),
+  CONSTRAINT fk_loading_work_carton_label FOREIGN KEY (carton_label_id) REFERENCES fl_inbound_carton_label (id),
+  CONSTRAINT chk_loading_work_carton_units CHECK (units_per_carton IS NULL OR units_per_carton > 0)
+) ENGINE=InnoDB COMMENT='一件代发PDA逐箱上托事实；客户订单不合并但实际托盘可混托';
+
 DROP PROCEDURE IF EXISTS repair_phase3_loading_pick_task_foreign_keys;
 DELIMITER $$
 CREATE PROCEDURE repair_phase3_loading_pick_task_foreign_keys()
@@ -5983,7 +5970,7 @@ BEGIN
   SELECT MAX(plan_status) INTO current_plan_status FROM fl_loading_plan
    WHERE container_booking_id = NEW.container_booking_id;
   IF current_plan_status = 'COMPLETED'
-     AND NEW.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION') THEN
+     AND NEW.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION', 'DELIVERY_ORDER', 'PICKUP_ORDER') THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜完成后货柜文件不可新增';
   END IF;
 END$$
@@ -5999,7 +5986,7 @@ BEGIN
   SELECT MAX(plan_status) INTO current_plan_status FROM fl_loading_plan
    WHERE container_booking_id = OLD.container_booking_id;
   IF current_plan_status = 'COMPLETED'
-     AND OLD.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION') THEN
+     AND OLD.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION', 'DELIVERY_ORDER', 'PICKUP_ORDER') THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜完成后货柜文件不可修改';
   END IF;
 END$$
@@ -6440,7 +6427,7 @@ JOIN wh_warehouse warehouse
 ON DUPLICATE KEY UPDATE
   tenant_id = VALUES(tenant_id);
 
--- 国内固定作业仓必须启用收货能力，FBA 目的地址仍不得创建作业能力。
+-- 四个固定平台作业仓必须启用收货能力，FBA 目的地址仍不得创建作业能力。
 INSERT INTO wh_service_capability (
   id, tenant_id, warehouse_id, capability_code, capability_name, enabled, cutoff_time,
   description, created_by, created_at, updated_by, updated_at, deleted, version
@@ -6449,7 +6436,11 @@ VALUES
   (193000000000400001,0,193000000000200001,'RECEIVING','头程收货',1,'16:00:00',
    '义乌仓头程订单收货能力',NULL,CURRENT_TIMESTAMP(3),NULL,CURRENT_TIMESTAMP(3),0,0),
   (193000000000400002,0,193000000000200002,'RECEIVING','头程收货',1,'16:00:00',
-   '东莞仓头程订单收货能力',NULL,CURRENT_TIMESTAMP(3),NULL,CURRENT_TIMESTAMP(3),0,0)
+   '东莞仓头程订单收货能力',NULL,CURRENT_TIMESTAMP(3),NULL,CURRENT_TIMESTAMP(3),0,0),
+  (193000000000400003,0,193000000000200003,'RECEIVING','海外收货',1,'16:00:00',
+   '洛杉矶仓海外接柜入仓收货能力',NULL,CURRENT_TIMESTAMP(3),NULL,CURRENT_TIMESTAMP(3),0,0),
+  (193000000000400004,0,193000000000200004,'RECEIVING','海外收货',1,'16:00:00',
+   '纽约仓海外接柜入仓收货能力',NULL,CURRENT_TIMESTAMP(3),NULL,CURRENT_TIMESTAMP(3),0,0)
 ON DUPLICATE KEY UPDATE
   capability_name = VALUES(capability_name),
   enabled = VALUES(enabled),
@@ -7096,11 +7087,11 @@ BEGIN
   IF (SELECT COUNT(*)
         FROM wh_service_capability capability
        WHERE capability.tenant_id = 0
-         AND capability.warehouse_id IN (193000000000200001,193000000000200002)
+         AND capability.warehouse_id IN (193000000000200001,193000000000200002,193000000000200003,193000000000200004)
          AND capability.capability_code = 'RECEIVING'
          AND capability.enabled = 1
-         AND capability.deleted = 0) <> 2 THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '国内固定作业仓收货能力写入校验失败';
+         AND capability.deleted = 0) <> 4 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '固定平台作业仓收货能力写入校验失败';
   END IF;
 END//
 DELIMITER ;
@@ -9109,6 +9100,7 @@ CREATE TABLE IF NOT EXISTS fl_ocean_booking (
   bill_of_lading_no VARCHAR(128) NULL COMMENT '提单号',
   shipping_company_id BIGINT UNSIGNED NULL COMMENT '船公司逻辑ID快照',
   shipping_company_name VARCHAR(128) NULL COMMENT '船公司名称快照',
+  carrier_code VARCHAR(16) NULL COMMENT '船司标准编码：MATSON/SML/ZIM/COSCO/EMC/HEDE/OTHER；发布前必填',
   booking_agent_id BIGINT UNSIGNED NULL COMMENT '订舱代理逻辑ID快照',
   booking_agent_name VARCHAR(128) NULL COMMENT '订舱代理名称快照',
   vessel_name VARCHAR(128) NULL COMMENT '当前确认船名快照',
@@ -9137,10 +9129,38 @@ CREATE TABLE IF NOT EXISTS fl_ocean_booking (
   CONSTRAINT chk_ocean_booking_customer CHECK (customer_id > 0),
   CONSTRAINT chk_ocean_booking_status CHECK (status IN
     ('DRAFT','RELEASED')),
+  CONSTRAINT chk_ocean_booking_carrier_code CHECK
+    (carrier_code IS NULL OR carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER')),
   CONSTRAINT chk_ocean_booking_schedule CHECK
     (estimated_sailing_at IS NULL OR estimated_arrival_at IS NULL OR estimated_arrival_at >= estimated_sailing_at)
 ) ENGINE=InnoDB COMMENT='独立海运订舱聚合；柜次仍由fl_container_booking承载';
 
+SET @ocean_add_carrier_code = (
+  SELECT IF(COUNT(*) = 0,
+    'ALTER TABLE fl_ocean_booking ADD COLUMN carrier_code VARCHAR(16) NULL COMMENT ''船司标准编码：MATSON/SML/ZIM/COSCO/EMC/HEDE/OTHER；发布前必填'' AFTER shipping_company_name',
+    'SELECT 1')
+    FROM information_schema.columns
+   WHERE table_schema=DATABASE() AND table_name='fl_ocean_booking' AND column_name='carrier_code'
+);
+PREPARE ocean_add_carrier_code_stmt FROM @ocean_add_carrier_code;
+EXECUTE ocean_add_carrier_code_stmt;
+DEALLOCATE PREPARE ocean_add_carrier_code_stmt;
+
+SET @ocean_drop_carrier_code_check = (
+  SELECT IF(COUNT(*) > 0,
+    'ALTER TABLE fl_ocean_booking DROP CHECK chk_ocean_booking_carrier_code',
+    'SELECT 1')
+    FROM information_schema.table_constraints
+   WHERE constraint_schema=DATABASE() AND table_name='fl_ocean_booking'
+     AND constraint_name='chk_ocean_booking_carrier_code' AND constraint_type='CHECK'
+);
+PREPARE ocean_drop_carrier_code_check_stmt FROM @ocean_drop_carrier_code_check;
+EXECUTE ocean_drop_carrier_code_check_stmt;
+DEALLOCATE PREPARE ocean_drop_carrier_code_check_stmt;
+ALTER TABLE fl_ocean_booking
+  ADD CONSTRAINT chk_ocean_booking_carrier_code CHECK
+    (carrier_code IS NULL OR carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER'));
+
 -- CREATE TABLE IF NOT EXISTS does not reconcile a database initialized before customer became optional.
 ALTER TABLE fl_ocean_booking
   MODIFY COLUMN customer_id BIGINT UNSIGNED NULL COMMENT '可选客户ID快照',
@@ -10377,11 +10397,11 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query (
   ocean_booking_id BIGINT UNSIGNED NOT NULL COMMENT '关联海运订舱ID',
   container_booking_id BIGINT UNSIGNED NULL COMMENT '指定查询的柜次ID；整票订舱查询时为空',
   container_scope_id BIGINT UNSIGNED GENERATED ALWAYS AS (COALESCE(container_booking_id,0)) STORED COMMENT '柜次唯一作用域计算值；整票订舱查询固定为0',
-  carrier_code VARCHAR(16) NOT NULL COMMENT '船公司编码：MATSON美森、SML森罗、ZIM以星、COSCO中远海运、EMC长荣、HEDE合德',
+  carrier_code VARCHAR(16) NOT NULL COMMENT '船公司标准编码；OTHER表示人工跟踪',
   tracking_type VARCHAR(32) NOT NULL COMMENT '官网跟踪类型：BOOKING_NO订舱号、BILL_OF_LADING提单号、CONTAINER_NO箱号',
   tracking_no VARCHAR(128) NOT NULL COMMENT '提交至船公司官网的跟踪号码',
   official_url VARCHAR(500) NOT NULL COMMENT '船公司官网查询入口地址快照',
-  access_mode VARCHAR(32) NOT NULL COMMENT '船司访问方式：PUBLIC_FORM、PUBLIC_WEB_PROXY、PUBLIC_HTML、HCAPTCHA、OFFICIAL_API',
+  access_mode VARCHAR(32) NOT NULL COMMENT '船司访问方式；MANUAL表示仅人工补录节点',
   status VARCHAR(24) NOT NULL COMMENT '任务操作状态：READY、MANUAL_REQUIRED、STOPPED',
   trigger_source VARCHAR(32) NOT NULL DEFAULT 'MANUAL' COMMENT '任务触发来源：OUTBOUND_CONFIRM或MANUAL',
   latest_standard_node VARCHAR(32) NULL COMMENT '最近实际标准船节点；预计事实不推进',
@@ -10423,11 +10443,11 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query (
   CONSTRAINT fk_carrier_schedule_query_result FOREIGN KEY (result_port_schedule_id) REFERENCES fl_port_schedule(id),
   CONSTRAINT chk_carrier_schedule_query_customer CHECK (customer_id > 0),
   CONSTRAINT chk_carrier_schedule_query_carrier CHECK
-    (carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE')),
+    (carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER')),
   CONSTRAINT chk_carrier_schedule_query_tracking CHECK
     (tracking_type IN ('BOOKING_NO','BILL_OF_LADING','CONTAINER_NO')),
   CONSTRAINT chk_carrier_schedule_query_access CHECK
-    (access_mode IN ('PUBLIC_FORM','PUBLIC_WEB_PROXY','PUBLIC_HTML','HCAPTCHA','OFFICIAL_API')),
+    (access_mode IN ('PUBLIC_FORM','PUBLIC_WEB_PROXY','PUBLIC_HTML','HCAPTCHA','OFFICIAL_API','MANUAL')),
   CONSTRAINT chk_carrier_schedule_query_status CHECK
     (status IN ('READY','MANUAL_REQUIRED','STOPPED')),
   CONSTRAINT chk_carrier_schedule_query_node CHECK
@@ -10786,6 +10806,7 @@ DROP PROCEDURE IF EXISTS migrate_carrier_schedule_retry_columns;
 -- CREATE TABLE IF NOT EXISTS 不会替换历史 CHECK 与唯一索引。统一收敛到当前
 -- READY/MANUAL_REQUIRED/STOPPED、五种访问方式、十个实际节点和每业务范围唯一任务。
 ALTER TABLE fl_carrier_schedule_query
+  DROP CHECK chk_carrier_schedule_query_carrier,
   DROP CHECK chk_carrier_schedule_query_access,
   DROP CHECK chk_carrier_schedule_query_status;
 DROP PROCEDURE IF EXISTS drop_legacy_carrier_schedule_node_check;
@@ -10802,8 +10823,10 @@ DELIMITER ;
 CALL drop_legacy_carrier_schedule_node_check();
 DROP PROCEDURE IF EXISTS drop_legacy_carrier_schedule_node_check;
 ALTER TABLE fl_carrier_schedule_query
+  ADD CONSTRAINT chk_carrier_schedule_query_carrier CHECK
+    (carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER')),
   ADD CONSTRAINT chk_carrier_schedule_query_access CHECK
-    (access_mode IN ('PUBLIC_FORM','PUBLIC_WEB_PROXY','PUBLIC_HTML','HCAPTCHA','OFFICIAL_API')),
+    (access_mode IN ('PUBLIC_FORM','PUBLIC_WEB_PROXY','PUBLIC_HTML','HCAPTCHA','OFFICIAL_API','MANUAL')),
   ADD CONSTRAINT chk_carrier_schedule_query_status CHECK
     (status IN ('READY','MANUAL_REQUIRED','STOPPED')),
   ADD CONSTRAINT chk_carrier_schedule_query_node CHECK
@@ -13484,6 +13507,7 @@ CALL queue_column_comment('baiyue_firstleg', 'fl_inbound_order', 'created_at', '
 CALL queue_column_comment('baiyue_firstleg', 'fl_inbound_order', 'created_by', '创建人ID');
 CALL queue_column_comment('baiyue_firstleg', 'fl_inbound_order', 'created_by_name', '创建人名称快照');
 CALL queue_column_comment('baiyue_firstleg', 'fl_inbound_order', 'current_hold_reason', '当前扣货理由快照');
+CALL queue_column_comment('baiyue_firstleg', 'fl_inbound_order', 'last_overseas_hold_version', '海外暂扣事件最新聚合版本，用于阻止乱序覆盖');
 CALL queue_column_comment('baiyue_firstleg', 'fl_inbound_order', 'customer_id', '客户逻辑ID');
 CALL queue_column_comment('baiyue_firstleg', 'fl_inbound_order', 'customer_name', '客户名称快照');
 CALL queue_column_comment('baiyue_firstleg', 'fl_inbound_order', 'customs_inspection', '是否商检');
@@ -13928,6 +13952,7 @@ CALL queue_column_comment('baiyue_firstleg', 'fl_mojia_measurement_receipt', 'up
 CALL queue_column_comment('baiyue_firstleg', 'fl_mojia_measurement_receipt', 'weight_kg', '设备实测重量kg');
 CALL queue_column_comment('baiyue_firstleg', 'fl_mojia_measurement_receipt', 'width_cm', '设备实测宽度cm');
 CALL queue_column_comment('baiyue_firstleg', 'fl_ocean_booking', 'bill_of_lading_no', '提单号');
+CALL queue_column_comment('baiyue_firstleg', 'fl_ocean_booking', 'carrier_code', '船司标准编码：MATSON/SML/ZIM/COSCO/EMC/HEDE/OTHER；发布前必填');
 CALL queue_column_comment('baiyue_firstleg', 'fl_ocean_booking', 'booking_agent_id', '订舱代理逻辑ID快照');
 CALL queue_column_comment('baiyue_firstleg', 'fl_ocean_booking', 'booking_agent_name', '订舱代理名称快照');
 CALL queue_column_comment('baiyue_firstleg', 'fl_ocean_booking', 'booking_no', '平台海运订舱编号');
@@ -14795,6 +14820,7 @@ CALL queue_column_comment('baiyue_warehouse', 'wh_pallet_location_transfer_opera
 CALL queue_column_comment('baiyue_warehouse', 'wh_pallet_location_transfer_operation', 'target_business_id', '目标子入仓单ID');
 CALL queue_column_comment('baiyue_warehouse', 'wh_pallet_location_transfer_operation', 'tenant_id', '仓储公共资源域，固定为0');
 CALL queue_column_comment('baiyue_warehouse', 'wh_partner', 'address_line', '详细地址');
+CALL queue_column_comment('baiyue_warehouse', 'wh_partner', 'carrier_code', '船司标准编码：MATSON、SML、ZIM、COSCO、EMC、HEDE或OTHER；仅CARRIER必填');
 CALL queue_column_comment('baiyue_warehouse', 'wh_partner', 'city', '城市');
 CALL queue_column_comment('baiyue_warehouse', 'wh_partner', 'contact_email', '联系邮箱');
 CALL queue_column_comment('baiyue_warehouse', 'wh_partner', 'contact_name', '联系人姓名');
@@ -14892,6 +14918,21 @@ BEGIN
          'baiyue_firstleg','baiyue_file','baiyue_audit','baiyue_event_bridge','baiyue_finance'))<>9 THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '统一迁移失败：九个业务数据库未完整创建';
   END IF;
+  IF (SELECT COUNT(*) FROM information_schema.columns
+       WHERE table_schema='baiyue_iam' AND table_name='iam_tenant'
+         AND column_name='dimension_initialization_status') <> 1
+     OR (SELECT COUNT(*) FROM information_schema.tables
+          WHERE table_schema='baiyue_iam'
+            AND table_name='iam_customer_dimension_initialization_task') <> 1
+     OR (SELECT COUNT(*) FROM information_schema.columns
+          WHERE table_schema='baiyue_iam'
+            AND table_name='iam_customer_dimension_initialization_task'
+            AND column_name IN ('tenant_id','initialization_key','action','status','attempt_count',
+              'next_retry_at','lease_owner','lease_until','last_error_code','last_error_message',
+              'task_version')) <> 11 THEN
+    SIGNAL SQLSTATE '45000'
+      SET MESSAGE_TEXT = '统一迁移失败：IAM客户默认尺寸后台初始化状态或可靠任务结构不完整';
+  END IF;
   IF (SELECT COUNT(*) FROM information_schema.columns
        WHERE table_schema='baiyue_firstleg' AND table_name='fl_carrier_schedule_query'
          AND column_name IN ('trigger_source','latest_standard_node','latest_node_observed_at',
@@ -15335,10 +15376,9 @@ VALUES
   (5105019, 0, 'PLATFORM', 'BUTTON', 5105000, 'platform:finance:cost:create', '登记成本', NULL, 'POST', 100, 'ACTIVE', 0),
   (5105020, 0, 'PLATFORM', 'BUTTON', 5105000, 'platform:finance:customer-terms:view', '查看客户账期', NULL, 'GET', 110, 'ACTIVE', 0),
   (5105021, 0, 'PLATFORM', 'BUTTON', 5105000, 'platform:finance:customer-terms:update', '修改客户账期', NULL, 'PUT', 120, 'ACTIVE', 0),
-  (5205000, 10001, 'MERCHANT', 'MENU', 5200000, 'merchant:finance:statement', '财务账单', '/finance/statements', NULL, 40, 'ACTIVE', 0),
-  (5205010, 10001, 'MERCHANT', 'BUTTON', 5205000, 'merchant:finance:statement:list', '查看账单', NULL, 'GET', 10, 'ACTIVE', 0),
-  (5205011, 10001, 'MERCHANT', 'BUTTON', 5205000, 'merchant:finance:statement:view', '查看账单详情及收款', NULL, 'GET', 20, 'ACTIVE', 0),
-  (5205012, 10001, 'MERCHANT', 'BUTTON', 5205000, 'merchant:finance:statement:confirm', '确认客户对账单', NULL, 'POST', 30, 'ACTIVE', 0),
+  (5305000, 0, 'MERCHANT', 'MENU', 5300000, 'merchant:finance:statement', '财务账单', '/finance/statements', NULL, 40, 'ACTIVE', 0),
+  (5305010, 0, 'MERCHANT', 'BUTTON', 5305000, 'merchant:finance:statement:list', '查看账单', NULL, 'GET', 10, 'ACTIVE', 0),
+  (5305011, 0, 'MERCHANT', 'BUTTON', 5305000, 'merchant:finance:statement:view', '查看账单详情及收款', NULL, 'GET', 20, 'ACTIVE', 0),
   (5305012, 0, 'MERCHANT', 'BUTTON', 5305000, 'merchant:finance:statement:confirm', '确认客户对账单', NULL, 'POST', 30, 'ACTIVE', 0)
 ON DUPLICATE KEY UPDATE permission_name=VALUES(permission_name), parent_id=VALUES(parent_id), route_path=VALUES(route_path), http_method=VALUES(http_method), status='ACTIVE', deleted=0;
 
@@ -15471,11 +15511,6 @@ WHERE tenant_id=0 AND app_code='PLATFORM' AND permission_code IN (
   'platform:finance:settlement-ap:create', 'platform:finance:payment:create',
   'platform:finance:settlement:void')
 ON DUPLICATE KEY UPDATE tenant_id=VALUES(tenant_id);
-INSERT INTO baiyue_iam.iam_role_permission (role_id, permission_id, tenant_id)
-SELECT 4000101, id, 10001 FROM baiyue_iam.iam_permission
- WHERE tenant_id=10001 AND app_code='MERCHANT' AND (permission_code='merchant:finance:statement' OR permission_code LIKE 'merchant:finance:%')
-ON DUPLICATE KEY UPDATE tenant_id=VALUES(tenant_id);
-
 -- 开发期 list-only 收口：先移除角色关联并停用旧只读资源，再执行最终 Finance 断言。
 DELETE rp FROM baiyue_iam.iam_role_permission rp
 JOIN baiyue_iam.iam_permission p ON p.id=rp.permission_id AND p.tenant_id=rp.tenant_id
@@ -15851,7 +15886,7 @@ CREATE TRIGGER trg_container_document_before_insert BEFORE INSERT ON fl_containe
 BEGIN
   DECLARE current_plan_status VARCHAR(24);
   SELECT MAX(plan_status) INTO current_plan_status FROM fl_loading_plan WHERE container_booking_id=NEW.container_booking_id;
-  IF current_plan_status='COMPLETED' AND NEW.document_type NOT IN ('DESTINATION_CLEARANCE','CUSTOMS_DECLARATION') THEN
+  IF current_plan_status='COMPLETED' AND NEW.document_type NOT IN ('DESTINATION_CLEARANCE','CUSTOMS_DECLARATION','DELIVERY_ORDER','PICKUP_ORDER') THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='装柜完成后货柜物流文件不可新增';
   END IF;
 END$$
@@ -15862,7 +15897,7 @@ CREATE TRIGGER trg_container_document_before_update BEFORE UPDATE ON fl_containe
 BEGIN
   DECLARE current_plan_status VARCHAR(24);
   SELECT MAX(plan_status) INTO current_plan_status FROM fl_loading_plan WHERE container_booking_id=OLD.container_booking_id;
-  IF current_plan_status='COMPLETED' AND OLD.document_type NOT IN ('DESTINATION_CLEARANCE','CUSTOMS_DECLARATION') THEN
+  IF current_plan_status='COMPLETED' AND OLD.document_type NOT IN ('DESTINATION_CLEARANCE','CUSTOMS_DECLARATION','DELIVERY_ORDER','PICKUP_ORDER') THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='装柜完成后货柜物流文件不可修改';
   END IF;
 END$$
@@ -15941,22 +15976,18 @@ SELECT 0, r.id, p.id, CURRENT_TIMESTAMP(3) FROM iam_role r JOIN iam_permission p
 WHERE r.tenant_id=0 AND r.app_code='PLATFORM' AND r.role_code='PLATFORM_ADMIN' AND p.permission_code IN ('platform:finance:customer-account:list','platform:finance:customer-arap:list','platform:finance:receivable-statistics:list','platform:finance:customer-statement:list','platform:finance:settlement-ar:list','platform:finance:settlement-ap:list','platform:finance:customer-account:export','platform:finance:customer-arap:export','platform:finance:receivable-statistics:export','platform:finance:customer-statement:export','platform:finance:settlement-ar:export','platform:finance:settlement-ap:export','platform:download:list');
 UPDATE iam_permission p JOIN (SELECT 'platform:finance:fee-source:review' code,5105041 parent_id UNION ALL SELECT 'platform:finance:fee-source:edit',5105041 UNION ALL SELECT 'platform:finance:reconciliation:create',5105042 UNION ALL SELECT 'platform:finance:reconciliation:review',5105042 UNION ALL SELECT 'platform:finance:reconciliation:issue',5105042 UNION ALL SELECT 'platform:finance:reconciliation:adjust',5105042 UNION ALL SELECT 'platform:finance:reconciliation:void',5105042 UNION ALL SELECT 'platform:finance:settlement-ar:create',5105043 UNION ALL SELECT 'platform:finance:settlement-ap:create',5105044 UNION ALL SELECT 'platform:finance:payment:create',5105044) mapping ON mapping.code=p.permission_code SET p.parent_id=mapping.parent_id WHERE p.tenant_id=0 AND p.app_code='PLATFORM' AND p.permission_type='BUTTON';
 
-INSERT IGNORE INTO iam_role_permission (tenant_id, role_id, permission_id, created_at)
-SELECT 10001, r.id, p.id, CURRENT_TIMESTAMP(3) FROM iam_role r JOIN iam_permission p ON p.tenant_id=10001 AND p.app_code='MERCHANT'
-WHERE r.tenant_id=10001 AND r.app_code='MERCHANT' AND r.role_code IN ('MERCHANT_OWNER','MERCHANT_ADMIN')
-  AND p.permission_code='merchant:finance:statement:confirm';
-
 INSERT IGNORE INTO iam_role_permission (tenant_id, role_id, permission_id, created_at)
 SELECT 0, r.id, p.id, CURRENT_TIMESTAMP(3) FROM iam_role r JOIN iam_permission p ON p.tenant_id=0 AND p.app_code='MERCHANT'
 WHERE r.tenant_id=0 AND r.app_code='MERCHANT' AND r.role_code='MERCHANT_OWNER'
   AND r.status='ACTIVE' AND r.deleted=0
-  AND p.permission_code='merchant:finance:statement:confirm'
+  AND p.permission_code IN ('merchant:finance:statement','merchant:finance:statement:list',
+                            'merchant:finance:statement:view','merchant:finance:statement:confirm')
   AND p.status='ACTIVE' AND p.deleted=0;
 
 INSERT INTO baiyue_iam.iam_permission
   (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, deleted)
 VALUES
-  (5201024, 10001, 'MERCHANT', 'BUTTON', 5201020, 'merchant:order:quick-create', '快速下单', NULL, NULL, 40, 'ACTIVE', 0)
+  (5301024, 0, 'MERCHANT', 'BUTTON', 5301020, 'merchant:order:quick-create', '快速下单', NULL, NULL, 40, 'ACTIVE', 0)
 ON DUPLICATE KEY UPDATE
   permission_type = VALUES(permission_type), parent_id = VALUES(parent_id), permission_name = VALUES(permission_name),
   route_path = VALUES(route_path), sort_no = VALUES(sort_no), status = 'ACTIVE', deleted = 0;
@@ -16172,11 +16203,8 @@ BEGIN
   IF (SELECT COUNT(*) FROM baiyue_iam.iam_permission WHERE tenant_id=0 AND app_code='PLATFORM' AND permission_code LIKE 'platform:finance:%' AND status='ACTIVE' AND deleted=0) <> 32 THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：平台 Finance 权限不完整';
   END IF;
-  IF (SELECT COUNT(*) FROM baiyue_iam.iam_permission WHERE tenant_id=10001 AND app_code='MERCHANT' AND permission_code IN ('merchant:finance:statement:list','merchant:finance:statement:view','merchant:finance:statement:confirm') AND status='ACTIVE' AND deleted=0) <> 3 THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：客户 Finance 查询与确认权限不完整';
-  END IF;
-  IF (SELECT COUNT(*) FROM baiyue_iam.iam_permission WHERE tenant_id=0 AND app_code='MERCHANT' AND permission_code='merchant:finance:statement:confirm' AND status='ACTIVE' AND deleted=0) <> 1 THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：客户全局对账单确认权限不完整';
+  IF (SELECT COUNT(*) FROM baiyue_iam.iam_permission WHERE tenant_id=0 AND app_code='MERCHANT' AND permission_code IN ('merchant:finance:statement','merchant:finance:statement:list','merchant:finance:statement:view','merchant:finance:statement:confirm') AND status='ACTIVE' AND deleted=0) <> 4 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：客户全局 Finance 权限模板不完整';
   END IF;
   IF (SELECT COUNT(*) FROM baiyue_iam.iam_role_permission rp JOIN baiyue_iam.iam_permission p ON p.id=rp.permission_id AND p.tenant_id=rp.tenant_id WHERE rp.role_id=4000001 AND rp.tenant_id=0 AND (p.permission_code='platform:finance' OR p.permission_code LIKE 'platform:finance:%')) <> 33 THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：平台管理员 Finance 授权不完整';
@@ -16184,11 +16212,8 @@ BEGIN
   IF (SELECT COUNT(*) FROM baiyue_iam.iam_role_permission rp JOIN baiyue_iam.iam_permission p ON p.id=rp.permission_id AND p.tenant_id=rp.tenant_id WHERE rp.role_id=4000001 AND rp.tenant_id=0 AND p.status='ACTIVE' AND p.deleted=0 AND p.permission_code IN ('platform:download:list','platform:finance:customer-account:export','platform:finance:customer-arap:export','platform:finance:receivable-statistics:export','platform:finance:customer-statement:export','platform:finance:settlement-ar:export','platform:finance:settlement-ap:export')) <> 7 THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：平台管理员 Finance 导出和下载中心授权不完整';
   END IF;
-  IF (SELECT COUNT(*) FROM baiyue_iam.iam_role_permission rp JOIN baiyue_iam.iam_permission p ON p.id=rp.permission_id AND p.tenant_id=rp.tenant_id WHERE rp.role_id=4000101 AND rp.tenant_id=10001 AND (p.permission_code='merchant:finance:statement' OR p.permission_code LIKE 'merchant:finance:%')) <> 4 THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：客户管理员 Finance 查询与确认授权不完整';
-  END IF;
-  IF (SELECT COUNT(*) FROM baiyue_iam.iam_role_permission rp JOIN baiyue_iam.iam_role r ON r.id=rp.role_id AND r.tenant_id=rp.tenant_id JOIN baiyue_iam.iam_permission p ON p.id=rp.permission_id AND p.tenant_id=rp.tenant_id WHERE r.tenant_id=0 AND r.app_code='MERCHANT' AND r.role_code='MERCHANT_OWNER' AND r.status='ACTIVE' AND r.deleted=0 AND p.permission_code='merchant:finance:statement:confirm' AND p.status='ACTIVE' AND p.deleted=0) <> 1 THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：客户全局管理员缺少对账单确认权限';
+  IF (SELECT COUNT(*) FROM baiyue_iam.iam_role_permission rp JOIN baiyue_iam.iam_role r ON r.id=rp.role_id AND r.tenant_id=rp.tenant_id JOIN baiyue_iam.iam_permission p ON p.id=rp.permission_id AND p.tenant_id=rp.tenant_id WHERE r.id=4000100 AND r.tenant_id=0 AND r.app_code='MERCHANT' AND r.role_code='MERCHANT_OWNER' AND r.status='ACTIVE' AND r.deleted=0 AND p.permission_code IN ('merchant:finance:statement','merchant:finance:statement:list','merchant:finance:statement:view','merchant:finance:statement:confirm') AND p.status='ACTIVE' AND p.deleted=0) <> 4 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='统一迁移失败：客户全局管理员 Finance 模板授权不完整';
   END IF;
 END$$
 DELIMITER ;
@@ -16277,12 +16302,35 @@ DROP PROCEDURE IF EXISTS add_container_empty_report_fields;
 
 CREATE TABLE IF NOT EXISTS fl_container_event_inbox (
   event_id VARCHAR(64) NOT NULL COMMENT '跨区事件全局唯一ID', event_type VARCHAR(64) NOT NULL COMMENT '事件类型',
-  event_version INT UNSIGNED NOT NULL COMMENT '事件契约版本', aggregate_id VARCHAR(64) NOT NULL COMMENT '货柜聚合ID',
-  aggregate_version BIGINT UNSIGNED NOT NULL COMMENT '货柜聚合版本', payload_hash VARCHAR(80) NOT NULL COMMENT '规范化负载SHA-256摘要',
+  event_version INT UNSIGNED NOT NULL COMMENT '事件契约版本', aggregate_id VARCHAR(64) NOT NULL COMMENT '跨区业务聚合ID',
+  aggregate_version BIGINT UNSIGNED NOT NULL COMMENT '跨区业务聚合版本', payload_hash VARCHAR(80) NOT NULL COMMENT '规范化负载SHA-256摘要',
   payload_json JSON NOT NULL COMMENT '原始事件负载', status VARCHAR(16) NOT NULL COMMENT 'RECEIVED或PROCESSED',
   received_at DATETIME(3) NOT NULL COMMENT '接收时间（UTC）', processed_at DATETIME(3) NULL COMMENT '处理完成时间（UTC）',
   PRIMARY KEY (event_id), KEY idx_container_event_aggregate (aggregate_id,aggregate_version)
-) ENGINE=InnoDB COMMENT='海外货柜事件消费Inbox';
+) ENGINE=InnoDB COMMENT='海外到国内业务事件消费Inbox';
+
+DROP PROCEDURE IF EXISTS add_inbound_overseas_hold_version;
+DELIMITER $$
+CREATE PROCEDURE add_inbound_overseas_hold_version()
+BEGIN
+  IF NOT EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema=DATABASE() AND table_name='fl_inbound_order'
+         AND column_name='last_overseas_hold_version'
+  ) THEN
+    ALTER TABLE fl_inbound_order
+      ADD COLUMN last_overseas_hold_version BIGINT UNSIGNED NULL
+      COMMENT '海外暂扣事件最新聚合版本，用于阻止乱序覆盖'
+      AFTER current_hold_reason;
+  END IF;
+  ALTER TABLE fl_container_event_inbox
+    MODIFY COLUMN aggregate_id VARCHAR(64) NOT NULL COMMENT '跨区业务聚合ID',
+    MODIFY COLUMN aggregate_version BIGINT UNSIGNED NOT NULL COMMENT '跨区业务聚合版本',
+    COMMENT='海外到国内业务事件消费Inbox';
+END$$
+DELIMITER ;
+CALL add_inbound_overseas_hold_version();
+DROP PROCEDURE IF EXISTS add_inbound_overseas_hold_version;
 
 -- 标准跨区事件摘要包含 sha256: 前缀，共 71 字符；兼容既有 Finance 64 位摘要。
 ALTER TABLE fl_inbound_outbox
@@ -16329,6 +16377,9 @@ VALUES
   (5107061,0,'PLATFORM','BUTTON',5107060,'platform:overseas-warehouse:location:create','创建海外库位',NULL,'POST',761,'ACTIVE',1,0),
   (5107062,0,'PLATFORM','BUTTON',5107060,'platform:overseas-warehouse:location:edit','编辑海外库位',NULL,'PUT',762,'ACTIVE',1,0),
   (5107063,0,'PLATFORM','BUTTON',5107060,'platform:overseas-warehouse:location:delete','删除海外库位',NULL,'DELETE',763,'ACTIVE',1,0),
+  (5107090,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:outbound:list','海外出库单','/overseas-warehouse/outbounds','GET',765,'ACTIVE',1,0),
+  (5107091,0,'PLATFORM','BUTTON',5107090,'platform:overseas-warehouse:outbound:create','创建海外出库单',NULL,'POST',766,'ACTIVE',1,0),
+  (5107092,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:delivery:list','海外派送单','/overseas-warehouse/delivery-orders','GET',767,'ACTIVE',1,0),
   (5107100,0,'PLATFORM','MENU',0,'platform:overseas-business:purchase:list','海外采购订单','/overseas-business/purchases','GET',800,'ACTIVE',1,0),
   (5107101,0,'PLATFORM','BUTTON',5107100,'platform:overseas-business:purchase:edit','编辑海外采购订单',NULL,'PATCH',801,'ACTIVE',1,0),
   (5107102,0,'PLATFORM','BUTTON',5107100,'platform:overseas-business:purchase:review','审核海外采购订单',NULL,'POST',802,'ACTIVE',1,0),
@@ -16503,10 +16554,27 @@ WHERE role.tenant_id=0 AND role.app_code='PLATFORM'
   AND UPPER(role.role_code) IN ('PLATFORM_ADMIN','PLATFORM_CUSTOM_ADMIN')
   AND role.status='ACTIVE' AND role.deleted=0 AND permission.status='ACTIVE' AND permission.deleted=0;
 
+-- PLATFORM_CUSTOM_ADMIN needs access to the overseas outbound and delivery lists shown in the admin navigation.
+INSERT IGNORE INTO baiyue_iam.iam_role_permission (tenant_id, role_id, permission_id, created_at)
+SELECT 0, role.id, permission.id, NOW(3)
+FROM baiyue_iam.iam_role role
+JOIN baiyue_iam.iam_permission permission ON permission.tenant_id=0 AND permission.app_code='PLATFORM'
+  AND permission.permission_code IN (
+    'platform:overseas-warehouse:outbound:list',
+    'platform:overseas-warehouse:delivery:list'
+  )
+WHERE role.tenant_id=0 AND role.app_code='PLATFORM'
+  AND UPPER(role.role_code)='PLATFORM_CUSTOM_ADMIN'
+  AND role.status='ACTIVE' AND role.deleted=0 AND permission.status='ACTIVE' AND permission.deleted=0;
+
 -- 海外智能排车草稿锁：拖入即锁定，移除或关闭草稿即释放。
 CREATE DATABASE IF NOT EXISTS baiyue_lastleg
   DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
 USE baiyue_lastleg;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='source_warehouse_id'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN source_warehouse_id VARCHAR(128) NULL COMMENT ''来源国内装柜仓 ID 快照'' AFTER customer_name'));
+PREPARE lastleg_order_source_warehouse_stmt FROM @ddl; EXECUTE lastleg_order_source_warehouse_stmt; DEALLOCATE PREPARE lastleg_order_source_warehouse_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='source_warehouse_name'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN source_warehouse_name VARCHAR(255) NULL COMMENT ''来源国内装柜仓名称快照'' AFTER source_warehouse_id'));
+PREPARE lastleg_order_source_warehouse_stmt FROM @ddl; EXECUTE lastleg_order_source_warehouse_stmt; DEALLOCATE PREPARE lastleg_order_source_warehouse_stmt;
 CREATE TABLE IF NOT EXISTS ll_dispatch_pallet_lock (
   id BIGINT NOT NULL COMMENT '主键ID',
   customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID',
@@ -16632,6 +16700,48 @@ SELECT 0,role.id,permission.id,NOW(3) FROM baiyue_iam.iam_role role
 JOIN baiyue_iam.iam_permission permission ON permission.id BETWEEN 5107070 AND 5107082 AND permission.tenant_id=0
 WHERE role.tenant_id=0 AND role.app_code='PLATFORM' AND role.role_code='PLATFORM_ADMIN' AND role.status='ACTIVE' AND role.deleted=0;
 
+-- IAM 客户提交即成功，默认尺寸通过持久化任务后台初始化；已有客户按历史事实标记 READY。
+USE baiyue_iam;
+SET @customer_dimension_status_ddl = (SELECT IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE()
+    AND table_name='iam_tenant' AND column_name='dimension_initialization_status'),
+  'SELECT 1',
+  'ALTER TABLE iam_tenant ADD COLUMN dimension_initialization_status VARCHAR(16) NOT NULL DEFAULT ''READY'' COMMENT ''默认尺寸初始化状态：PENDING待处理、READY已就绪、FAILED失败'' AFTER status'));
+PREPARE customer_dimension_status_stmt FROM @customer_dimension_status_ddl;
+EXECUTE customer_dimension_status_stmt;
+DEALLOCATE PREPARE customer_dimension_status_stmt;
+CREATE TABLE IF NOT EXISTS iam_customer_dimension_initialization_task (
+  tenant_id BIGINT NOT NULL COMMENT '客户ID及任务聚合ID',
+  operator_id BIGINT NOT NULL COMMENT '触发初始化的操作人ID；系统补偿为0',
+  initialization_key VARCHAR(128) NOT NULL COMMENT '稳定初始化幂等键：iam-customer-create:{tenantId}',
+  action VARCHAR(16) NOT NULL DEFAULT 'INITIALIZE' COMMENT '目标动作：INITIALIZE初始化、COMPENSATE补偿',
+  status VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT '投递状态：PENDING、SENDING、READY、FAILED、CANCELLED',
+  attempt_count INT NOT NULL DEFAULT 0 COMMENT '当前动作已失败尝试次数',
+  next_retry_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '下次允许投递时间',
+  lease_owner VARCHAR(128) NULL COMMENT '当前任务租约持有者',
+  lease_until DATETIME(3) NULL COMMENT '当前任务租约截止时间',
+  last_error_code VARCHAR(32) NULL COMMENT '最后下游错误码',
+  last_error_message VARCHAR(1000) NULL COMMENT '最后诊断错误，不保存敏感凭证',
+  remote_config_id BIGINT NULL COMMENT 'Firstleg返回的首条默认尺寸配置ID',
+  task_version INT NOT NULL DEFAULT 0 COMMENT '任务乐观版本；切换动作或认领时递增',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '任务创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '任务更新时间',
+  completed_at DATETIME(3) NULL COMMENT 'READY或CANCELLED完成时间',
+  PRIMARY KEY (tenant_id),
+  KEY idx_customer_dimension_task_dispatch (status,next_retry_at,lease_until),
+  KEY idx_customer_dimension_task_diagnosis (status,updated_at)
+) ENGINE=InnoDB COMMENT='IAM客户默认尺寸可靠后台初始化任务及诊断状态';
+
+-- 兼容已存在的旧表：CREATE TABLE IF NOT EXISTS 不会为旧表补充新字段。
+SET @customer_dimension_lease_ddl = (SELECT IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE()
+    AND table_name='iam_customer_dimension_initialization_task' AND column_name='lease_until'),
+  'SELECT 1',
+  'ALTER TABLE iam_customer_dimension_initialization_task ADD COLUMN lease_until DATETIME(3) NULL COMMENT ''当前任务租约截止时间'' AFTER lease_owner'));
+PREPARE customer_dimension_lease_stmt FROM @customer_dimension_lease_ddl;
+EXECUTE customer_dimension_lease_stmt;
+DEALLOCATE PREPARE customer_dimension_lease_stmt;
+
 CALL baiyue_firstleg.assert_unified_final_schema();
 DROP PROCEDURE IF EXISTS baiyue_firstleg.assert_unified_final_schema;
 SELECT 'PASS' AS migration_status,

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

@@ -1,6 +1,113 @@
 -- 海外区域固定增量入口。空库先执行 lastleg-service/src/main/resources/db/lastleg.sql 基线；
+-- 本入口同时初始化海外 Event Bridge 独立库，避免国内/海外实例误共用 Inbox。
 -- 本文件只由人工审核执行，服务部署默认不自动执行 SQL。
 SET NAMES utf8mb4;
+
+CREATE DATABASE IF NOT EXISTS baiyue_event_bridge_overseas
+  DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+USE baiyue_event_bridge_overseas;
+
+CREATE TABLE IF NOT EXISTS bridge_outbox (
+  event_id VARCHAR(128) NOT NULL COMMENT '事件全局标识',
+  idempotency_key VARCHAR(191) NOT NULL COMMENT '发送幂等键',
+  event_type VARCHAR(64) NOT NULL COMMENT '事件类型',
+  event_version INT NOT NULL COMMENT '事件契约版本',
+  source_region VARCHAR(32) NOT NULL COMMENT '来源区域',
+  target_region VARCHAR(32) NOT NULL COMMENT '目标区域',
+  customer_id VARCHAR(128) NOT NULL COMMENT '客户标识',
+  aggregate_type VARCHAR(64) NOT NULL COMMENT '聚合类型',
+  aggregate_id VARCHAR(128) NOT NULL COMMENT '聚合标识',
+  aggregate_version BIGINT NOT NULL COMMENT '聚合版本',
+  handover_version BIGINT NULL COMMENT '跨区交接版本',
+  trace_id VARCHAR(128) NOT NULL COMMENT '链路标识',
+  correlation_id VARCHAR(128) NOT NULL COMMENT '业务关联标识',
+  causation_id VARCHAR(128) NULL COMMENT '上游事件标识',
+  occurred_at DATETIME(3) NOT NULL COMMENT '业务事实发生时间',
+  payload_hash VARCHAR(71) NOT NULL COMMENT '规范化负载摘要',
+  payload_json JSON NOT NULL COMMENT '事件负载',
+  status VARCHAR(32) NOT NULL DEFAULT 'PENDING' COMMENT '投递状态',
+  retry_count INT NOT NULL DEFAULT 0 COMMENT '已重试次数',
+  next_retry_at DATETIME(3) NULL COMMENT '下次重试时间',
+  lease_owner VARCHAR(128) NULL COMMENT '租约持有者',
+  lease_until DATETIME(3) NULL COMMENT '租约截止时间',
+  last_error VARCHAR(1000) NULL COMMENT '最后错误',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  delivered_at DATETIME(3) NULL COMMENT '投递成功时间',
+  PRIMARY KEY (event_id),
+  UNIQUE KEY uk_bridge_outbox_idempotency (idempotency_key),
+  KEY idx_bridge_outbox_schedule (target_region,status,next_retry_at,lease_until)
+) ENGINE=InnoDB COMMENT='海外跨区域事件待投递箱';
+
+CREATE TABLE IF NOT EXISTS bridge_inbox (
+  event_id VARCHAR(128) NOT NULL COMMENT '事件全局标识',
+  idempotency_key VARCHAR(191) NOT NULL COMMENT '接收幂等键',
+  event_type VARCHAR(64) NOT NULL COMMENT '事件类型',
+  event_version INT NOT NULL COMMENT '事件契约版本',
+  source_region VARCHAR(32) NOT NULL COMMENT '来源区域',
+  target_region VARCHAR(32) NOT NULL COMMENT '目标区域',
+  customer_id VARCHAR(128) NOT NULL COMMENT '客户标识',
+  aggregate_type VARCHAR(64) NOT NULL COMMENT '聚合类型',
+  aggregate_id VARCHAR(128) NOT NULL COMMENT '聚合标识',
+  aggregate_version BIGINT NOT NULL COMMENT '聚合版本',
+  handover_version BIGINT NULL COMMENT '跨区交接版本',
+  trace_id VARCHAR(128) NOT NULL COMMENT '链路标识',
+  correlation_id VARCHAR(128) NOT NULL COMMENT '业务关联标识',
+  causation_id VARCHAR(128) NULL COMMENT '上游事件标识',
+  occurred_at DATETIME(3) NOT NULL COMMENT '业务事实发生时间',
+  payload_hash VARCHAR(71) NOT NULL COMMENT '规范化负载摘要',
+  payload_json JSON NOT NULL COMMENT '事件负载',
+  status VARCHAR(32) NOT NULL DEFAULT 'RECEIVED' COMMENT '消费状态',
+  lease_owner VARCHAR(128) NULL COMMENT '消费租约持有者',
+  lease_until DATETIME(3) NULL COMMENT '消费租约截止时间',
+  retry_count INT NOT NULL DEFAULT 0 COMMENT '消费重试次数',
+  next_retry_at DATETIME(3) NULL COMMENT '下次消费时间',
+  last_error VARCHAR(1000) NULL COMMENT '最后错误',
+  received_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '接收时间',
+  processed_at DATETIME(3) NULL COMMENT '消费完成时间',
+  PRIMARY KEY (event_id),
+  UNIQUE KEY uk_bridge_inbox_idempotency (idempotency_key),
+  KEY idx_bridge_inbox_consume (status,next_retry_at,lease_until)
+) ENGINE=InnoDB COMMENT='海外跨区域事件已接收箱';
+
+CREATE TABLE IF NOT EXISTS bridge_delivery_attempt (
+  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+  event_id VARCHAR(128) NOT NULL COMMENT '事件全局标识',
+  source_region VARCHAR(32) NOT NULL COMMENT '来源区域',
+  target_region VARCHAR(32) NOT NULL COMMENT '目标区域',
+  attempt_no INT NOT NULL COMMENT '投递序号',
+  status VARCHAR(32) NOT NULL COMMENT '投递结果',
+  response_code VARCHAR(64) NULL COMMENT '对端响应码',
+  error_message VARCHAR(1000) NULL COMMENT '错误信息',
+  started_at DATETIME(3) NOT NULL COMMENT '开始时间',
+  finished_at DATETIME(3) NULL COMMENT '完成时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_bridge_attempt (event_id,attempt_no),
+  KEY idx_bridge_attempt_event (event_id,started_at)
+) ENGINE=InnoDB COMMENT='海外跨区域事件投递尝试记录';
+
+DROP PROCEDURE IF EXISTS assert_overseas_event_bridge_schema;
+DELIMITER $$
+CREATE PROCEDURE assert_overseas_event_bridge_schema()
+BEGIN
+  IF (SELECT COUNT(*) FROM information_schema.tables
+       WHERE table_schema='baiyue_event_bridge_overseas'
+         AND table_name IN ('bridge_outbox','bridge_inbox','bridge_delivery_attempt')) <> 3 THEN
+    SIGNAL SQLSTATE '45000'
+      SET MESSAGE_TEXT='海外区域初始化失败：Event Bridge 三张表未完整创建';
+  END IF;
+  IF (SELECT COUNT(DISTINCT CONCAT(table_name, ':', index_name)) FROM information_schema.statistics
+       WHERE table_schema='baiyue_event_bridge_overseas'
+         AND ((table_name='bridge_outbox' AND index_name IN ('PRIMARY','uk_bridge_outbox_idempotency','idx_bridge_outbox_schedule'))
+           OR (table_name='bridge_inbox' AND index_name IN ('PRIMARY','uk_bridge_inbox_idempotency','idx_bridge_inbox_consume'))
+           OR (table_name='bridge_delivery_attempt' AND index_name IN ('PRIMARY','uk_bridge_attempt','idx_bridge_attempt_event')))) <> 9 THEN
+    SIGNAL SQLSTATE '45000'
+      SET MESSAGE_TEXT='海外区域初始化失败：Event Bridge 索引未完整创建';
+  END IF;
+END$$
+DELIMITER ;
+CALL assert_overseas_event_bridge_schema();
+DROP PROCEDURE IF EXISTS assert_overseas_event_bridge_schema;
+
 CREATE DATABASE IF NOT EXISTS baiyue_lastleg
   DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 USE baiyue_lastleg;
@@ -88,7 +195,7 @@ CREATE TABLE IF NOT EXISTS ll_overseas_procurement_order (
   purchase_quantity BIGINT NOT NULL COMMENT '采购数量', budget_unit_price DECIMAL(18,2) NULL COMMENT '预算单价',
   currency CHAR(3) NOT NULL DEFAULT 'USD' COMMENT '币种', receiving_address VARCHAR(1000) NULL COMMENT '收货地址',
   contact_name VARCHAR(128) NOT NULL COMMENT '联系人姓名', contact_phone VARCHAR(64) NOT NULL COMMENT '联系人电话',
-  purchase_warehouse_id VARCHAR(128) NULL COMMENT '采购入仓仓库ID', purchase_warehouse_name VARCHAR(255) NULL COMMENT '采购入仓仓库名称',
+  purchase_warehouse_id VARCHAR(128) NULL COMMENT '采购入仓仓库ID', purchase_warehouse_name VARCHAR(255) NULL COMMENT '采购入仓仓库名称', outbound_details JSON NULL COMMENT '出库明细',
   inbound_quantity BIGINT NOT NULL DEFAULT 0 COMMENT '采购单据累计入库数量', domestic_carrier VARCHAR(128) NULL COMMENT '境内承运商',
   domestic_tracking_no VARCHAR(128) NULL COMMENT '境内物流单号', overseas_carrier VARCHAR(128) NULL COMMENT '海外承运商',
   overseas_tracking_no VARCHAR(128) NULL COMMENT '海外物流单号', estimated_arrival_at DATETIME(3) NULL COMMENT '预计到达时间',
@@ -104,6 +211,8 @@ CREATE TABLE IF NOT EXISTS ll_overseas_procurement_order (
   KEY idx_ll_overseas_procurement_list(customer_id,status,created_at),
   KEY idx_ll_overseas_procurement_warehouse(customer_id,purchase_warehouse_id,created_at)
 ) ENGINE=InnoDB COMMENT='海外采购订单';
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_overseas_procurement_order' AND column_name='outbound_details'), 'SELECT 1', 'ALTER TABLE ll_overseas_procurement_order ADD COLUMN outbound_details JSON NULL COMMENT ''出库明细'' AFTER inbound_quantity'));
+PREPARE procurement_outbound_stmt FROM @ddl; EXECUTE procurement_outbound_stmt; DEALLOCATE PREPARE procurement_outbound_stmt;
 
 SET @ddl = (SELECT IF(EXISTS (
   SELECT 1 FROM information_schema.columns
@@ -862,6 +971,12 @@ PREPARE phase4_discard_review_stmt FROM @ddl; EXECUTE phase4_discard_review_stmt
 -- Warehouse Overseas 与 Lastleg 使用同一海外区域发布入口但保持独立数据库。
 -- 公共托盘详情实体读取 fba_warehouse_code；旧库缺列时创建可成功但详情会 S0500。
 USE baiyue_lastlag_warehouse;
+-- 仓库主档唯一权威已收口至国内 baiyue_warehouse；海外库只保留 warehouse_id 引用。
+-- 当前开发阶段不兼容旧海外主档数据，按依赖顺序移除重复表。
+DROP TABLE IF EXISTS wh_service_capability;
+DROP TABLE IF EXISTS wh_warehouse_address;
+DROP TABLE IF EXISTS wh_warehouse;
+
 CREATE TABLE IF NOT EXISTS wh_pallet_operation (
   id BIGINT NOT NULL COMMENT '托盘状态操作ID', operation_key VARCHAR(128) NOT NULL COMMENT '跨服务幂等操作键',
   request_hash VARCHAR(128) NOT NULL COMMENT '状态变更请求摘要', warehouse_id BIGINT NOT NULL COMMENT '实际海外仓ID',
@@ -939,33 +1054,63 @@ CREATE TABLE IF NOT EXISTS ll_order_operation_log (
   PRIMARY KEY(id), KEY idx_ll_order_operation_customer_order(customer_id,order_id,created_at)
 ) ENGINE=InnoDB COMMENT='尾程订单操作记录';
 
-CREATE DATABASE IF NOT EXISTS baiyue_overseas_security DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
-USE baiyue_overseas_security;
-CREATE TABLE IF NOT EXISTS overseas_security_event_inbox (
-  event_id VARCHAR(64) NOT NULL, event_type VARCHAR(96) NOT NULL, payload_hash CHAR(64) NOT NULL,
-  payload_json JSON NOT NULL, status VARCHAR(16) NOT NULL, result VARCHAR(32) NULL,
-  received_at DATETIME(3) NOT NULL, processed_at DATETIME(3) NULL,
+USE baiyue_lastleg;
+SET @ddl = (SELECT IF(EXISTS (
+  SELECT 1 FROM information_schema.columns
+   WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='version'
+), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN version INT NOT NULL DEFAULT 0 COMMENT ''入库计划乐观锁版本'' AFTER updated_at'));
+PREPARE ll_inbound_plan_version_ddl FROM @ddl;
+EXECUTE ll_inbound_plan_version_ddl;
+DEALLOCATE PREPARE ll_inbound_plan_version_ddl;
+
+SET @ddl = (SELECT IF(EXISTS (
+  SELECT 1 FROM information_schema.columns
+   WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='pallet_merge_batch_id'
+), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN pallet_merge_batch_id VARCHAR(64) NULL COMMENT ''平台预标记合托分组号'' AFTER pallet_merge_flag'));
+PREPARE ll_order_merge_batch_ddl FROM @ddl;
+EXECUTE ll_order_merge_batch_ddl;
+DEALLOCATE PREPARE ll_order_merge_batch_ddl;
+
+CREATE TABLE IF NOT EXISTS ll_security_event_inbox (
+  event_id VARCHAR(64) NOT NULL COMMENT '跨区安全事件ID', event_type VARCHAR(96) NOT NULL COMMENT 'IAM安全事件类型',
+  payload_hash CHAR(64) NOT NULL COMMENT '规范化载荷SHA-256哈希', payload_json JSON NOT NULL COMMENT '冻结事件载荷JSON',
+  status VARCHAR(16) NOT NULL COMMENT '消费状态：RECEIVED或PROCESSED',
+  result VARCHAR(32) NULL COMMENT '处理结果：APPLIED、STALE、DUPLICATE或DUPLICATE_VERSION',
+  received_at DATETIME(3) NOT NULL COMMENT '接收时间', processed_at DATETIME(3) NULL COMMENT '处理完成时间',
   PRIMARY KEY (event_id), KEY idx_security_inbox_type_time (event_type,received_at)
-) ENGINE=InnoDB COMMENT='海外IAM安全事件消费者Inbox';
-CREATE TABLE IF NOT EXISTS overseas_security_projection (
-  aggregate_type VARCHAR(32) NOT NULL, aggregate_id VARCHAR(64) NOT NULL, tenant_id BIGINT NOT NULL,
-  security_status VARCHAR(24) NULL, permission_version BIGINT NULL, aggregate_version BIGINT NOT NULL,
-  payload_hash CHAR(64) NOT NULL, last_event_id VARCHAR(64) NOT NULL,
-  changed_at DATETIME(3) NOT NULL, updated_at DATETIME(3) NOT NULL,
+) ENGINE=InnoDB COMMENT='海外IAM安全事件消费者收件箱';
+CREATE TABLE IF NOT EXISTS ll_security_projection (
+  aggregate_type VARCHAR(32) NOT NULL COMMENT '聚合类型：USER、TENANT或AUTHORIZATION',
+  aggregate_id VARCHAR(64) NOT NULL COMMENT '用户或客户聚合ID', tenant_id BIGINT NOT NULL COMMENT '平台0或客户ID',
+  security_status VARCHAR(24) NULL COMMENT '当前安全状态：ACTIVE或DISABLED',
+  permission_version BIGINT NULL COMMENT '当前单调权限版本',
+  aggregate_version BIGINT NOT NULL COMMENT '事件聚合单调版本', payload_hash CHAR(64) NOT NULL COMMENT '当前版本载荷哈希',
+  last_event_id VARCHAR(64) NOT NULL COMMENT '最后应用的事件ID',
+  changed_at DATETIME(3) NOT NULL COMMENT '国内IAM事实发生时间', updated_at DATETIME(3) NOT NULL COMMENT '投影更新时间',
   PRIMARY KEY (aggregate_type,aggregate_id), KEY idx_security_projection_tenant (tenant_id),
   KEY idx_security_projection_permission (aggregate_id,permission_version)
 ) ENGINE=InnoDB COMMENT='海外IAM安全状态与权限版本投影';
 
-DROP PROCEDURE IF EXISTS assert_overseas_security_projection_ready;
+-- 与国内固定 auth_account.id=1000001、tenant_id=0 的 platform_admin 一致；真实事件从版本1覆盖。
+INSERT IGNORE INTO ll_security_projection (
+  aggregate_type,aggregate_id,tenant_id,security_status,permission_version,aggregate_version,
+  payload_hash,last_event_id,changed_at,updated_at
+) VALUES
+  ('USER','1000001',0,'ACTIVE',0,0,SHA2('lastleg-baseline:platform_admin:USER:0',256),
+   'baseline-platform-admin-user-v0','1970-01-01 00:00:00.000','1970-01-01 00:00:00.000'),
+  ('AUTHORIZATION','1000001',0,NULL,0,0,SHA2('lastleg-baseline:platform_admin:AUTHORIZATION:0',256),
+   'baseline-platform-admin-authorization-v0','1970-01-01 00:00:00.000','1970-01-01 00:00:00.000');
+
+DROP PROCEDURE IF EXISTS assert_lastleg_security_projection_ready;
 DELIMITER $$
-CREATE PROCEDURE assert_overseas_security_projection_ready()
+CREATE PROCEDURE assert_lastleg_security_projection_ready()
 BEGIN
-  IF (SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='baiyue_overseas_security'
-      AND table_name IN ('overseas_security_event_inbox','overseas_security_projection')) <> 2 THEN
+  IF (SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='baiyue_lastleg'
+      AND table_name IN ('ll_security_event_inbox','ll_security_projection')) <> 2 THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='海外IAM安全Inbox或投影表未完整部署';
   END IF;
 END$$
 DELIMITER ;
-CALL assert_overseas_security_projection_ready();
-DROP PROCEDURE assert_overseas_security_projection_ready;
+CALL assert_lastleg_security_projection_ready();
+DROP PROCEDURE assert_lastleg_security_projection_ready;
 SELECT 'PASS' AS migration_status, '海外仓业务、海外仓资源与IAM安全投影结构已就绪' AS message;

docs/Order-Firstleg在线依赖解环设计.md

@@ -0,0 +1,60 @@
+# Order↔Firstleg 在线依赖解环设计
+
+## 结论
+
+当前不能在不改变已确认产品成功时点的前提下直接实施解环，业务代码保持不变。在线图仍包含
+`Order→Firstleg` 与 `Firstleg→Order`，所以非平凡强连通分量仍是 `Firstleg↔Order`。
+
+建议的最小退出方向是 **退出全部 `Firstleg→Order` REQUEST 边**。该方向只有
+`OrderCargoClient` 和 `OrderFulfillmentSplitClient` 两个客户端；Order 继续拥有订单、货物、父子订单和
+拆分台账，Firstleg 继续拥有入库、测量、分柜装柜、PDA 拣货和库位结算。完成后只保留
+`Order→Firstleg` 在线查询/门禁边以及双方后台边，在线 SCC 才会实际消失。
+
+## 当前可执行调用
+
+| 方向/客户端 | Controller→Service→Client→被调用入口 | 时点与调用者期望 | 失败传播 | 幂等性 |
+|---|---|---|---|---|
+| Order→Firstleg `FirstlegPricingClient` | `MerchantFirstLegOrderController`、`PlatformFirstLegOrderController` 的创建/编辑/提交 → `OrderApplicationService` → `OrderPricingChannelGuard` → `/internal/firstleg/v1/pricing/channels/validate` | 保存或提交前实时确认渠道有效；提交还必须取得入仓码前缀 | 业务错误原码上传；连接、空响应或不完整数据映射依赖不可用/冲突，订单不提交 | 纯读取 `SAFE_READ` |
+| Order→Firstleg `FirstlegUnifiedOrderClient` | `PlatformUnifiedOrderController`、`MerchantUnifiedOrderController` 列表/详情 → `UnifiedOrderQueryService` → Firstleg unified query/summaries/detail | 一个响应内组合 Order 主数据与 Firstleg 实时履约、测量、装柜和时间线 | 远端异常、失败码、空数据均失败关闭，不返回伪造履约摘要 | 纯读取 `SAFE_READ` |
+| Order→Firstleg `FirstlegInboundClient` | `MerchantFirstLegOrderController.page` → `MerchantInboundOrderListService` → references/prepareBatch；已提交订单编辑提交后 → `OrderApplicationService.prepareDraftInbound` → prepare；审核 Outbox → `OrderInboundOutboxPublisher` → create | 列表需要入库引用；草稿/待审编辑尝试同步预入库；审核成功已与 Firstleg 建单解耦 | references 失败关闭；prepare/prepareBatch 当前捕获异常并允许列表缺少入库引用，是现有失败传播缺口；审核 Outbox 持久化重试 | `tenantId+orderId` 业务键；Firstleg 对订单唯一且入仓码一致时幂等 |
+| Firstleg→Order `OrderCargoClient` | 箱号 Controller/Order 审核后台建单 → `InboundCartonLabelService`；测量 Controller/OpenAPI → `InboundMeasurementService`/`InboundMeasurementOpenApiService`；智能装柜 Controller → `SmartLoadingService` → Order cargo/snapshot endpoints | 首次箱号、测量明细、申报回填和装柜清单均要求当前订单货物事实 | 服务不可用、空数据、归属不一致均阻断当前操作；没有默认货物或空列表成功 | 纯读取 `SAFE_READ`；同时存在 REQUEST 和审核 Outbox 回调产生的 BACKGROUND 上下文 |
+| Firstleg→Order `OrderFulfillmentSplitClient` | `PlatformLoadingPdaController.complete` → `LoadingPickService.complete @Transactional` → `PdaPickSettlementService.settle` → `/internal/order/v1/fulfillment-splits` → `OrderFulfillmentSplitService.split @Transactional` | PDA 完成请求必须先取得 Order 真实余量子单 ID/单号，再在同一 Firstleg 事务写分片、测量、库位、审计并推进装柜完成 | Order 不可用或响应数量/柜次/父子关系不一致时整个 Firstleg 完成事务回滚；不得返回完成成功 | Firstleg 使用 `idempotencyKey=pda-task-{taskId}`、`operationId=PDA-SPLIT-{taskId}-{inboundId}`；Order 保存请求哈希并以唯一键重放 |
+
+## 事实所有权
+
+- Order：订单交易状态、订单货物及允许编辑的字段、父子订单 ID/单号、履约拆分台账和订单版本。
+- Firstleg：入库单、测量事实、分柜/装柜计划、PDA 拣货数量、库位结算、装柜证据和 `LOADING→LOADED` 门禁。
+- 允许复制的仅是带来源版本和哈希的 Order 快照；Firstleg 不得成为订单货物或父子订单的第二写入方。
+- 统一订单查询是组合读模型，不把 Firstleg 履约状态写回 Order 交易状态。
+
+## 推荐退出方案
+
+### 1. 先退出货物在线读取
+
+复用 Order 已有 Outbox 和 Firstleg 已有订单入库接收入口，将完整货物快照、订单版本和规范化哈希随草稿准备、待审编辑和审核事件可靠投递；Firstleg 以
+`tenantId+orderId+orderVersion` 单调 Inbox/快照落库。箱号、测量和智能装柜只读本地快照，缺失、版本冲突或哈希冲突均失败关闭。
+
+不能只在审核时复制一次：当前契约允许 `LOADED` 前按权限和状态修改业务资料。必须先冻结货物在哪个节点停止修改，或要求每次允许的 Order 编辑都可靠发布版本事件，并明确 Firstleg 在投影落后期间阻断哪些操作。
+
+### 2. 再将履约拆分改为可靠后台命令
+
+Firstleg 在本地持久化稳定 operation/idempotency key、数量行、柜次和请求哈希；后台 Relay 调用现有 Order 幂等拆分接口并保存完整响应。Order 现有拆分台账和唯一键可承担 Inbox/业务幂等，不需要新服务或 MQ。
+
+Firstleg 只有在后台结果为 `READY` 且父子关系、数量和柜次全部校验通过后，才能消费余量子订单 ID并执行本地结算。失败进入可诊断重试/DEAD，禁止默认成功。远端成功、本地未完成时只允许向前恢复，不得自动删除 Order 子订单。
+
+这一方案会引入技术态 `PENDING/READY/FAILED`，但不能擅自增加产品主状态。若在 PDA 首次点击完成时只创建任务并返回待处理，成功时点发生变化；若提前创建 Order 子单，则子单可能在装柜硬门禁完成前可见，同样改变现有语义。
+
+## 必须由产品冻结的决策
+
+1. **货物冻结点**：Order 货物在审核通过、首次生成箱号、确认测量还是确认预装后不可再改；若仍允许修改，哪些 Firstleg 操作必须等待最新 `orderVersion` 投影。
+2. **PDA 完成成功时点**：必须继续在一次请求中同时完成 Order 子单与 Firstleg 结算，还是允许首次请求返回“处理中”，后台完成后才成为 `LOADED`。同时确认后台已创建 Order 子单但 Firstleg 最终失败时采用持续向前修复，不提供在线冲正。
+
+上述任一决策未冻结前，不实施业务解环。
+
+## 最小实施与验证边界（决策冻结后）
+
+- Order：扩充版本化货物快照 Outbox；保留 `OrderFulfillmentSplitService` 事实所有权和现有幂等唯一键。
+- Firstleg：货物快照 Inbox/表、拆分命令 Outbox/Relay/诊断查询；替换两个在线 Client 的业务调用点。
+- SQL：仅更新当前模块基线与统一增量，不引入 Flyway/Liquibase，不执行 SQL。
+- 合同：证明生产请求路径不再引用两个客户端、`Firstleg→Order` 只剩 BACKGROUND，REQUEST SCC 中不再出现两者同一分量。
+- 测试：Order/Firstleg 全量直接测试、重复/异哈希事件、租约恢复、远端成功本地失败重放、DEAD 人工重试、PDA 未 READY 失败关闭，以及同步依赖合同。

docs/同步调用依赖与失败传播治理基线.md

@@ -2,7 +2,7 @@
 
 ## 目的与口径
 
-本基线覆盖后端服务之间的 OpenFeign、`RestClient`、`WebClient` 与 JDK `HttpClient` 调用。它用于识别同步依赖方向、在线请求深度、后台中继、超时、重试、熔断、幂等、错误映射和失败传播，不改变 Finance 或四期业务状态机。
+本基线覆盖当前官方 22 个 Maven 模块、15 个可执行服务之间的 OpenFeign、`RestClient`、`WebClient` 与 JDK `HttpClient` 调用。海外安全 Inbox/投影属于 Lastleg 内部子域，不再作为独立服务节点。基线用于识别同步依赖方向、在线请求深度、后台中继、超时、重试、熔断、幂等、错误映射和失败传播，不改变 Finance 或四期业务状态机。
 
 “存在双向服务边”不等于“一次在线请求会递归调用”。每条边必须继续区分：
 
@@ -21,12 +21,12 @@
 |---|---|---:|---|
 | Auth | IAM | 2 | 登录授权、注册，`REQUEST` |
 | IAM | Auth | 1 | 账号开通/管理，`REQUEST` |
-| IAM | Firstleg | 1 | 客户尺寸规则，`REQUEST` |
+| IAM | Firstleg | 1 | 客户尺寸默认规则可靠任务投递，`BACKGROUND` |
 | IAM | Warehouse | 1 | 海外仓储费协作，`REQUEST` |
 | IAM | Event Bridge | 1 | 安全事件中继，`BACKGROUND` |
 | Order | Firstleg | 3 | 计价/统一订单查询为 `REQUEST`，入库协作为 Outbox `BACKGROUND` |
 | Order | IAM / File / Warehouse | 各 1 | 资格、图片、仓库守卫，`REQUEST` |
-| Firstleg | Order | 2 | 货物查询与分拆回写，`REQUEST` |
+| Firstleg | Order | 2 | 货物查询同时存在 `REQUEST/BACKGROUND`；PDA 履约分拆为 `REQUEST` |
 | Firstleg | IAM / Finance / Integration / Event Bridge / Print | 各 1 | IAM、Integration、Print 为 `REQUEST`；Finance 与 Event Bridge 为 `BACKGROUND` 中继 |
 | Firstleg | File | 7 | 测量、装柜、凭证、报关、拖车等，`REQUEST` |
 | Firstleg | Warehouse | 4 | 主数据、供应商、库位/托盘，`REQUEST` |
@@ -45,10 +45,10 @@
 | 调用方 | 被调用方 | 实现 | 上下文与当前策略 |
 |---|---|---|---|
 | Gateway Overseas | Auth | `HttpPdaSessionValidationClient` | `INFRASTRUCTURE`；总超时 2 秒，异常由网关失败关闭 |
-| Gateway Overseas | Overseas Security | `HttpOverseasSecurityValidationClient` | `INFRASTRUCTURE`；安全投影实时校验，异常失败关闭，不进入在线业务图 |
+| Gateway Overseas | Lastleg Security 子域 | `HttpOverseasSecurityValidationClient` | `INFRASTRUCTURE`；Lastleg 内部安全投影实时校验，异常失败关闭，不进入在线业务图 |
 | Lastleg | Warehouse Overseas | 两个 `RestClient` Gateway | `REQUEST`；分别使用 3 秒连接、5 秒读取超时，配置可覆盖，不自动重试 |
 | Lastleg | File | 两个照片 `RestClient` Gateway | `REQUEST`；分别使用 3 秒连接、30 秒读取超时，配置可覆盖；校验响应 code 且失败关闭，不自动重试 |
-| Event Bridge | Firstleg / Lastleg / Overseas Security | 三个 JDK `HttpClient` | `BACKGROUND`；连接 3 秒、请求 10 秒，持久化租约和退避由 Event Bridge 专项治理；Security 投影不进入在线业务图 |
+| Event Bridge | Firstleg / Lastleg（业务事件与安全投影两个入口） | 三个 JDK `HttpClient` | `BACKGROUND`；连接 3 秒、请求 10 秒，持久化租约和退避由 Event Bridge 专项治理；Lastleg Security 投影不进入在线业务图 |
 | 启用 Common Audit 的服务 | Audit | `HttpAuditSink` | `INFRASTRUCTURE`；当前捕获异常后仅告警，可能让调用方误以为审计已成功，是高优先级失败传播缺口 |
 | Integration | 外部 OCR/船司 | 六个 JDK `HttpClient` | `EXTERNAL`；OCR 默认 10/60 秒，船司默认 10/30 秒，业务重试必须服从供应商和调度契约 |
 
@@ -67,21 +67,21 @@
 
 ### 在线 REQUEST 图
 
-在线图只包含用户或设备请求线程中实际执行的服务边。Event Bridge、Outbox、船节点定时任务、导出 Provider 和海外 Security 校验均不计入在线深度。
+在线图只包含用户或设备请求线程中实际执行的服务边。Event Bridge、Outbox、船节点定时任务、导出 Provider 和 Gateway→Lastleg Security 基础设施校验均不计入在线深度。
 
 当前在线强连通分量为：
 
-`Auth ↔ IAM ↔ Firstleg ↔ Order ↔ File`
+`Auth ↔ IAM`；`Firstleg ↔ Order`
 
-合同冻结 22 条在线服务边；新增在线边或新增强连通分量直接失败。Finance、Lastleg 只指向该分量或叶子服务，不属于在线环；Gateway Overseas→Security 是 `INFRASTRUCTURE`，不是 REQUEST 边。
+`IAM → Firstleg` 默认尺寸初始化已退出请求线程，合同现冻结 21 条在线服务边；新增在线边或新增强连通分量直接失败。File 不再属于在线强连通分量；Finance、Lastleg 只指向上述分量或叶子服务，不属于在线环；Gateway Overseas→Lastleg Security 是 `INFRASTRUCTURE`，不是 REQUEST 边。
 
 ### 后台 BACKGROUND 图
 
 后台图包含 Outbox/Inbox、导出 Worker 和定时任务，当前强连通分量为：
 
-`Event Bridge ↔ Firstleg ↔ Finance ↔ Lastleg`
+`Event Bridge ↔ Firstleg ↔ Finance ↔ Lastleg ↔ Order`
 
-File 的五个导出 Provider、Order→Firstleg 入库 Outbox、IAM 安全 Outbox、Firstleg/Lastleg 跨区 Outbox、Firstleg→Finance 费用 Outbox及 Event Bridge 三个消费者均只在后台图中计算。Event Bridge→Overseas Security 是单向后台叶子边，不形成在线业务环。
+File 的五个导出 Provider、Order→Firstleg 入库 Outbox、该入库消费者为生成箱号而回读 Order 货物的后台回调、IAM 默认尺寸可靠任务、IAM 安全 Outbox、Firstleg/Lastleg 跨区 Outbox、Firstleg→Finance 费用 Outbox及 Event Bridge 三个消费者均只在后台图中计算。Event Bridge→Lastleg Security 与 Event Bridge→Lastleg 业务事件在服务图上收敛为同一条后台服务边，不形成新的在线业务边或独立安全节点。
 
 ### 全图
 
@@ -97,21 +97,20 @@ File 的五个导出 Provider、Order→Firstleg 入库 Outbox、IAM 安全 Outb
 
 | 用户入口 | 最长跳数 | 全部长路径 |
 |---|---:|---|
-| 认证 API | 5 | `Auth → IAM → Firstleg → Order → File → Integration` |
-| IAM API | 4 | `IAM → Firstleg → Order → File → Integration` |
-| 订单 API | 4 | `Order → File → IAM → Firstleg → Print`；`Order → File → IAM → Firstleg → Warehouse`；`Order → Firstleg → File → IAM → Auth`；`Order → Firstleg → File → IAM → Warehouse`；`Order → IAM → Firstleg → File → Integration` |
+| 订单 API | 4 | `Order → Firstleg → File → IAM → Auth`；`Order → Firstleg → File → IAM → Warehouse` |
 | 头程 API/PDA | 4 | `Firstleg → Order → File → IAM → Auth`；`Firstleg → Order → File → IAM → Warehouse` |
-| 财务 API | 5 | `Finance → File → IAM → Firstleg → Order → Warehouse`；`Finance → Firstleg → Order → File → IAM → Auth`；`Finance → Firstleg → Order → File → IAM → Warehouse`；`Finance → IAM → Firstleg → Order → File → Integration` |
-| 文件 API | 4 | `File → IAM → Firstleg → Order → Warehouse` |
-| 海外尾程 API/PDA | 5 | `Lastleg → File → IAM → Firstleg → Order → Warehouse` |
-| 国内仓储 API | 0 | 无下游同步调用 |
-| 海外仓储 API | 0 | 无下游同步调用 |
+| 财务 API | 5 | `Finance → Firstleg → Order → File → IAM → Auth`；`Finance → Firstleg → Order → File → IAM → Warehouse` |
+| 海外尾程 API/PDA | 3 | `Lastleg → File → IAM → Auth`；`Lastleg → File → IAM → Warehouse` |
 
 这些是静态服务边可形成的最长简单路径，不表示每个具体 Controller 都会走完整链；后续入口级调用点治理必须继续以实际 Service 调用证据缩小路径，不能用静态可能性宣称线上已经发生。
 
-### 第一个建议退出的 REQUEST 边
+### 已完成的第一个 REQUEST 边退出
 
-建议优先将 `IAM → Firstleg` 的 `CustomerDimensionRuleClient` 默认尺寸初始化从 REQUEST WRITE 改为可靠后台编排。该命令已经携带稳定 `initializationKey` 并提供补偿接口，适合使用持久化 Outbox、显式 `PENDING/FAILED` 结果和人工可诊断重试；不得在失败时返回默认成功。退出此边可把当前五服务在线强连通分量拆为更小的 Auth↔IAM 与 Order↔Firstleg 子环，同时不触碰财务、Event Bridge 传输或四期业务状态机。实施前仍需 IAM/Firstleg 业务负责人确认“客户创建成功”与“默认尺寸已就绪”的产品时点。
+`IAM → Firstleg` 的 `CustomerDimensionRuleClient` 默认尺寸初始化已经从 REQUEST WRITE 改为可靠后台编排。IAM 与客户主档同事务持久化稳定 `initializationKey` 的任务，显式维护 `PENDING/READY/FAILED`，由租约调度重试并提供诊断查询和人工重试；审批通过与下单资格在未 READY 时失败关闭。此边现在仅属于 BACKGROUND，在线五服务强连通分量实际拆为 Auth↔IAM 与 Order↔Firstleg 两个子环，未触碰财务、Event Bridge 或四期业务状态机。
+
+### Order↔Firstleg 第二阶段结论
+
+具体入口、所有权与可执行退出方案见 `docs/Order-Firstleg在线依赖解环设计.md`。当前 `COMPLETE_LOADING` 在 Firstleg 本地事务中同步取得 Order 余量子单后才完成结算，且 Order 货物在 `LOADED` 前仍允许修改；成功时点和货物冻结点尚未冻结，因此本阶段不改业务代码。REQUEST SCC 仍为 `Firstleg↔Order`，合同明确阻止仅改变分类却未退出生产调用的伪解环。
 
 ## 退出顺序
 

docs/头程项目目录结构与服务说明.md

@@ -10,7 +10,7 @@
 
 ## 1. 项目定位
 
-`baiyue-firstleg` 是国内头程与海外仓后端仓库，采用 Maven 多模块单仓结构。根 POM 聚合 23 个 Maven 模块，其中 7 个是公共/依赖模块，16 个是可独立启动、构建、制作镜像的微服务。
+`baiyue-firstleg` 是国内头程与海外仓后端仓库，采用 Maven 多模块单仓结构。根 POM 聚合 22 个 Maven 模块，其中 7 个是公共/依赖模块，15 个是可独立启动、构建、制作镜像的微服务。
 
 当前技术基线：
 
@@ -48,7 +48,6 @@ baiyue-firstleg/
 ├─ finance/                      # 财务账期、账单、收付款与核销
 ├─ lastleg-service/              # 海外尾程、入仓、库存与本土业务
 ├─ warehouse-overseas-service/   # 海外仓库、库位、托盘与资源锁
-├─ overseas-security-service/    # 海外IAM安全事件Inbox、投影与实时校验
 ├─ file/                         # 资质、导出与测量图片文件中心
 ├─ print/                        # 打印中心
 ├─ audit-service/                # 审计日志中心
@@ -100,9 +99,8 @@ baiyue-firstleg/
 | `file` | `file-service` | 9206 | `baiyue_file` | 企业资质文件、公共异步导出下载、入库测量图片及重量 OCR 调用协作 |
 | `print` | `print-service` | 9207 | 无 | 无状态 PDF 渲染服务；调用方传入完整标签数据，服务在内存中生成一次性多页 PDF |
 | `integration-service` | `integration-service` | 9210 | 无 | 百度 OCR、Amazon SP-API 等第三方适配器和启停状态；默认关闭外部调用 |
-| `lastleg-service` | `lastleg-service` | 9303 | `baiyue_lastleg` | 海外尾程订单、接柜入仓、库存与海外本土业务；不含海外出库和派送 |
+| `lastleg-service` | `lastleg-service` | 9303 | `baiyue_lastleg` | 海外尾程订单、接柜入仓、库存、海外本土业务及 IAM 安全事件投影/实时校验；不含海外出库和派送 |
 | `warehouse-overseas-service` | `warehouse-overseas-service` | 9305 | 海外仓资源库 | 海外仓库、库位、托盘和资源锁 |
-| `overseas-security-service` | `overseas-security-service` | 9307 | `baiyue_overseas_security` | IAM安全事件可靠Inbox、单调投影及海外Token即时失效校验 |
 | `event-bridge-service` | `event-bridge-service` | 9312 | `baiyue_event_bridge` | 按 CN/OVERSEAS 双实例部署的跨区事件 Inbox、重试和目标服务投递 |
 | `audit-service` | `audit-service` | 9700 | `baiyue_audit` | 接收公共审计事件并持久化；平台端可按权限查询已脱敏日志，业务审计发送默认开启 |
 
@@ -283,6 +281,6 @@ HTTP 401 / `A0401`，不得再按 HTTP 200 + 空权限处理；只有使用新
 - 平台端和商户端权限分别管理，接口与按钮权限都必须由后端校验。
 - Controller 负责协议转换，Service 负责业务编排，Repository/Mapper 负责持久化。
 - 服务之间只传 DTO 或事件契约，不能依赖其他服务的 Entity、Mapper。
-- 公共模块变化会影响多个服务，Jenkins 会按 `service-map.yml` 覆盖的全部 16 个服务执行受影响构建。
+- 公共模块变化会影响多个服务，Jenkins 会按 `service-map.yml` 覆盖的全部 15 个服务执行受影响构建。
 - 单一 Git 仓库不等于单一部署单元；每个服务仍生成独立 JAR、镜像和容器。
 - 国内头程与海外仓共享 Git 仓库，但保持两套数据库、Nacos 命名空间和部署环境。

docs/数据库环境切换说明.md

@@ -1,66 +1,62 @@
-# 数据库环境切换说明
+# Nacos 环境切换说明
 
-## 环境定义
+数据库、Redis 和服务地址均由所选环境的 Nacos 配置决定。本地启动时只切换
+Nacos 地址与 namespace，不再通过 `application-test.yml` 单独切换数据库。
 
-- `dev`：本地开发环境，连接 `127.0.0.1:3306`，默认账号为 `root/123456`。
-- `test`：联调测试环境，连接 `8.163.30.128:3306`，各微服务仍使用独立数据库。
+## 环境映射
 
-所有服务默认使用 `dev`：
+| Maven Profile | Nacos 地址 | Namespace |
+| --- | --- | --- |
+| `local` | `127.0.0.1:8848` | `public` |
+| `dev` | `dev-nacos.buggoglobal.com:8848` | `DEV_NACOS_NAMESPACE` |
+| `test` | `8.163.30.128:8848` | `d99d7998-5bb0-4ffe-a2a0-1a564ce14463` |
 
-```yaml
-spring:
-  profiles:
-    active: ${SPRING_PROFILES_ACTIVE:dev}
+本地 Nacos 使用 `nacos/nacos`。开发和测试密码不写入 Git，需在启动 IDEA
+之前设置一次用户环境变量：
+
+```powershell
+[Environment]::SetEnvironmentVariable('DEV_NACOS_PASSWORD', '<开发 Nacos 密码>', 'User')
+[Environment]::SetEnvironmentVariable('TEST_NACOS_PASSWORD', '<测试 Nacos 密码>', 'User')
+[Environment]::SetEnvironmentVariable('DEV_NACOS_NAMESPACE', '<开发海外 namespace>', 'User')
 ```
 
-建议不要直接修改配置文件。通过 IDEA 的启动配置设置 `Active profiles` 即可切换：
+设置后完全退出并重新打开 IDEA，使 Maven 能读取新环境变量。
 
-- 本地数据库：`dev`
-- 测试数据库：`test`
+## IDEA 中切换
 
-也可以使用启动参数：
+1. 在 Maven 面板的 `Profiles` 中，`local`、`dev`、`test` 只勾选一个。
+2. 重新加载 Maven 项目。
+3. 在目标服务的 Maven `Plugins > spring-boot > spring-boot:run` 启动。
 
-```text
---spring.profiles.active=test
+例如海外查询链路需要分别启动 `gateway-overseas`、`lastleg-service` 和
+`warehouse-overseas-service`。已经运行的进程不会自动切换环境，切换 Profile
+后必须停止并重新启动。
+
+IDEA 普通绿色 Run 按钮不执行 Maven，因此不会读取 Maven Profile。需要继续使用
+绿色 Run 时，请在 Run Configuration 的 Environment variables 中设置
+`NACOS_SERVER_ADDR`、`NACOS_NAMESPACE`、`NACOS_USERNAME` 和 `NACOS_PASSWORD`。
+`gateway-overseas` 已默认启用 `overseas` Spring Profile。
+
+## PowerShell 中切换
+
+也可以在当前终端加载同一套变量，然后从同一终端启动服务：
+
+```powershell
+. .\scripts\use-nacos-environment.ps1 -Environment local -Region overseas
+. .\scripts\use-nacos-environment.ps1 -Environment dev -Region overseas
+. .\scripts\use-nacos-environment.ps1 -Environment test -Region overseas
 ```
 
-## 测试数据库密码
+脚本读取 `DEV_NACOS_PASSWORD`、`TEST_NACOS_PASSWORD`，namespace 优先读取
+`*_OVERSEAS_NACOS_NAMESPACE`，未设置时读取 `*_NACOS_NAMESPACE`。命令前面的点和
+空格不能省略，否则变量只存在于脚本子进程中。
 
-测试数据库密码不写入 Git。启动 `test` 环境前，在 IDEA 启动配置的环境变量中设置：
+## 当前限制
 
-```text
-TEST_DB_PASSWORD=测试数据库密码
-```
-
-公共测试连接参数支持覆盖：
-
-```text
-TEST_DB_HOST=8.163.30.128
-TEST_DB_PORT=3306
-TEST_DB_USERNAME=root
-TEST_DB_PASSWORD=测试数据库密码
-```
-
-每个服务还支持使用自己的 `*_TEST_DB_URL`、`*_TEST_DB_USERNAME` 和 `*_TEST_DB_PASSWORD` 覆盖公共参数。
-
-## 分库映射
-
-| 服务 | 测试数据库 |
-| --- | --- |
-| 认证服务 | `baiyue_auth` |
-| 权限服务 | `baiyue_iam` |
-| 订单服务 | `baiyue_order` |
-| 仓库服务 | `baiyue_warehouse` |
-| 头程履约服务 | `baiyue_firstleg` |
-| 文件服务 | `baiyue_file` |
-| 审计服务 | `baiyue_audit` |
-| 事件桥接服务 | `baiyue_event_bridge` |
-
-网关、打印和集成服务没有业务数据库，但同样支持 `dev/test` Profile。网关在两种环境下都会自动加载 `cn` 路由配置。
-
-## 注意事项
-
-- `test` 只切换数据库，Nacos 和 Redis 默认仍连接本机。
-- 环境变量优先级高于配置文件，可用于临时覆盖单个服务。
-- 修改 IDEA 环境变量后需要重启对应服务。
-- 不要把测试数据库密码提交到配置文件、启动脚本或 Git。
+- 测试 Nacos 的 `8848` 客户端端口已确认可连接。
+- 开发 Nacos 网页控制台可访问，但 `dev-nacos.buggoglobal.com:8848` 当前从本机
+  无法连接。需要开放 Nacos 客户端端口以及 Nacos 2.x/3.x 所需的 gRPC 端口，
+  或提供一个客户端可访问的内部地址。
+- 国内和海外存在同名 Data ID，远程环境必须使用各自独立 namespace。开发海外
+  namespace 尚未确认，因此通过 `DEV_NACOS_NAMESPACE` 在本机配置。
+- 不要同时勾选多个环境 Profile；Maven 对同名属性的最终取值不直观，容易连错环境。

event-bridge-service/AGENTS.md

@@ -12,12 +12,13 @@
 |---|---|
 | 接收、状态、人工补投 API | `src/main/java/com/baiyue/eventbridge/controller/EventBridgeController.java` |
 | Inbox 接收与幂等 | `service/EventInboxService.java` |
-| 按目标区域调度与重试 | `service/OverseasEventDispatcher.java`；`targetRegion=CN` 回投 Firstleg；海外业务事件投 Lastleg，三类 IAM 安全事件按 eventType 投 `overseas-security-service`，传输层不解析 payload |
+| 按目标区域调度与重试 | `service/OverseasEventDispatcher.java`；`targetRegion=CN` 回投 Firstleg；海外业务事件投 Lastleg 通用入口，三类 IAM 安全事件按 eventType 投 Lastleg `/internal/lastleg/security/v1/events`，传输层不解析 payload |
 | 尾程 HTTP 客户端 | `service/LastlegEventClient.java`、`HttpLastlegEventClient.java` |
 | 国内头程 HTTP 客户端 | `service/FirstlegEventClient.java`、`HttpFirstlegEventClient.java`；默认内部入口 `/internal/firstleg/v1/container-events` |
 | 人工补投 | `service/EventReplayService.java`；只允许 `DEAD` 转回 `RETRY`，记录操作人与原因，并保留原 `eventId`、payload 与 `payloadHash` |
 | Inbox 与投递记录 | `domain/BridgeInbox.java`、`BridgeDeliveryAttempt.java` 及对应 Mapper |
 | 传输指标与 Inbox 采样 | `metrics/EventBridgeMetrics.java`、`EventBridgeInboxMetricsSampler.java`；SLO 与告警合同 `docs/development-observability-slo.md` |
+| 事件 Trace 与原始 HTTP 传播 | `trace/EventBridgeTraceScope.java`、`EventBridgeHttpTracePropagation.java`；契约与已知缺口 `docs/event-trace-propagation.md` |
 | 内部服务令牌 | `security/InternalServiceTokenGuard.java` |
 | 数据库 | `src/main/resources/db/event-bridge.sql` |
 | 测试 | `src/test/java/com/baiyue/eventbridge/` |
@@ -29,6 +30,7 @@
 - 领取任务必须有数据库租约/并发保护，避免多实例重复发送；尾程幂等仍是最终保障。
 - 内部接口使用 `X-Internal-Service-Token`，生产还应置于受信网络或 mTLS 后。
 - 指标标签只允许有限 `target_region`、`event_type`、`result`，未知区域/类型折叠为 `OTHER`，禁止 eventId、customerId、错误消息等高基数标签。Inbox 聚合按现有状态索引定时采样，Prometheus scrape 不得查询数据库；开发阶段 SLO/告警只代表代码合同，不代表监控平台已部署。
+- 投递线程只从 Inbox 已冻结 `trace_id` 建立 MDC；合法 32 位 trace ID 或规范 UUID 可贯通，非法历史值安全重建。每次 JDK HttpClient 投递生成 child span，并覆盖三类标准 Trace 头；不得把 correlationId、eventId、customerId、聚合 ID、JWT 或内部令牌写入 Trace 字段。
 
 ## 修改与验证
 

event-bridge-service/docs/event-trace-propagation.md

@@ -0,0 +1,16 @@
+# Event Bridge Trace 传播基线
+
+- Event Bridge 领取 Inbox 后，仅从事件信封已冻结的 `traceId` 建立投递线程 MDC。
+- 32 位非零十六进制 trace ID 直接沿用；历史规范 UUID 去除连字符后沿用。
+- 其他旧值不满足 W3C Trace ID 约束，投递时安全重建新 trace，但不覆盖或迁移原事件信封。
+- 每次 HTTP 投递生成新的 `X-Request-Id` 和 child span，并统一覆盖 `X-Trace-Id`、`traceparent`。
+- `correlationId`、`eventId`、customer ID、聚合 ID、JWT 和内部服务令牌不得写入 Trace 标准字段。
+- 投递日志在 MDC 和显式 `traceId` 字段中记录本次标准 trace；投递 attempt 仍通过 `event_id`
+  关联 `bridge_inbox.trace_id`，本轮不增加数据库字段。
+
+## 共享契约缺口
+
+当前 `EventEnvelope.traceId` 仍是通用字符串契约，没有强制 32 位 W3C Trace ID；因此历史任意字符串不能
+无损映射为 W3C trace。若后续要求所有事件跨重试、跨语言绝对保持同一标准 trace，必须由
+`common-event-contract` 生产者、消费者和 Event Bridge 共同冻结字段校验后再收敛。本轮没有修改共享
+Payload、信封字段、哈希规则或可靠性状态机。

event-bridge-service/src/main/java/com/baiyue/eventbridge/metrics/EventBridgeMetrics.java

@@ -6,6 +6,7 @@ import com.baiyue.eventbridge.domain.BridgeInbox;
 import io.micrometer.core.instrument.MeterRegistry;
 import io.micrometer.core.instrument.Timer;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Component;
 
 import java.time.Clock;
@@ -29,6 +30,7 @@ public class EventBridgeMetrics {
             EventTypes.FIRST_LEG_LOADING_PLAN_COMPLETED,
             EventTypes.FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED,
             EventTypes.OVERSEAS_CONTAINER_UNLOADED,
+            EventTypes.OVERSEAS_INBOUND_ORDER_DETAINED_CHANGED,
             EventTypes.IAM_USER_STATUS_CHANGED,
             EventTypes.IAM_TENANT_STATUS_CHANGED,
             EventTypes.IAM_PERMISSION_VERSION_CHANGED,
@@ -41,6 +43,7 @@ public class EventBridgeMetrics {
     private final MeterRegistry registry;
     private final Clock clock;
 
+    @Autowired
     public EventBridgeMetrics(MeterRegistry registry) {
         this(registry, Clock.systemDefaultZone());
     }

event-bridge-service/src/main/java/com/baiyue/eventbridge/service/EventInboxService.java

@@ -14,7 +14,9 @@ import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 import jakarta.annotation.Resource;
 
+import java.time.Instant;
 import java.time.LocalDateTime;
+import java.time.temporal.ChronoUnit;
 import java.util.Objects;
 
 /**
@@ -29,10 +31,14 @@ public class EventInboxService {
     @Value("${baiyue.region:CN}")
     private String localRegion;
 
+    /** Local single-bridge mode may carry both regional envelopes; production keeps strict routing. */
+    @Value("${baiyue.event-bridge.accept-any-region:false}")
+    private boolean acceptAnyRegion;
+
     @Transactional
     public EventReceiveResult receive(EventEnvelope envelope) {
         envelope.requireValid();
-        if (!envelope.targetRegion().name().equalsIgnoreCase(localRegion)) {
+        if (!acceptAnyRegion && !envelope.targetRegion().name().equalsIgnoreCase(localRegion)) {
             throw new IllegalArgumentException("事件目标区域与当前事件桥区域不一致");
         }
         if (!EventPayloadHash.matches(
@@ -78,7 +84,7 @@ public class EventInboxService {
             && Objects.equals(existing.getAggregateId(), envelope.aggregateId())
             && Objects.equals(existing.getAggregateVersion(), envelope.aggregateVersion())
             && Objects.equals(existing.getHandoverVersion(), envelope.handoverVersion())
-            && Objects.equals(existing.getOccurredAt(), envelope.occurredAt())
+            && Objects.equals(normalizeOccurredAt(existing.getOccurredAt()), normalizeOccurredAt(envelope.occurredAt()))
             && Objects.equals(existing.getTraceId(), envelope.traceId())
             && Objects.equals(existing.getCorrelationId(), envelope.correlationId())
             && Objects.equals(existing.getCausationId(), envelope.causationId());
@@ -100,7 +106,7 @@ public class EventInboxService {
         inbox.setTraceId(envelope.traceId());
         inbox.setCorrelationId(envelope.correlationId());
         inbox.setCausationId(envelope.causationId());
-        inbox.setOccurredAt(envelope.occurredAt());
+        inbox.setOccurredAt(normalizeOccurredAt(envelope.occurredAt()));
         inbox.setPayloadHash(envelope.payloadHash().toLowerCase(java.util.Locale.ROOT));
         try {
             inbox.setPayloadJson(objectMapper.writeValueAsString(envelope.payload()));
@@ -111,4 +117,8 @@ public class EventInboxService {
         inbox.setReceivedAt(LocalDateTime.now());
         return inbox;
     }
+
+    private static Instant normalizeOccurredAt(Instant value) {
+        return value == null ? null : value.truncatedTo(ChronoUnit.MILLIS);
+    }
 }

event-bridge-service/src/main/java/com/baiyue/eventbridge/service/HttpFirstlegEventClient.java

@@ -4,6 +4,7 @@ import com.baiyue.common.event.EventEnvelope;
 import com.baiyue.common.event.RegionCode;
 import com.baiyue.eventbridge.config.EventDispatcherProperties;
 import com.baiyue.eventbridge.domain.BridgeInbox;
+import com.baiyue.eventbridge.trace.EventBridgeHttpTracePropagation;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.annotation.PostConstruct;
@@ -20,6 +21,7 @@ import java.net.http.HttpResponse;
 public class HttpFirstlegEventClient implements FirstlegEventClient {
     @Resource private ObjectMapper objectMapper;
     @Resource private EventDispatcherProperties properties;
+    @Resource private EventBridgeHttpTracePropagation tracePropagation;
     @Value("${baiyue.event-dispatcher.firstleg-consumer-url:http://127.0.0.1:9203/internal/firstleg/v1/container-events}")
     private URI consumerUrl;
     @Value("${baiyue.security.internal-service-token:}") private String serviceToken;
@@ -37,9 +39,10 @@ public class HttpFirstlegEventClient implements FirstlegEventClient {
             row.getCustomerId(), row.getAggregateType(), row.getAggregateId(), row.getAggregateVersion(),
             row.getHandoverVersion(), row.getTraceId(), row.getCorrelationId(), row.getCausationId(),
             objectMapper.readTree(row.getPayloadJson()), row.getPayloadHash());
-        HttpRequest request = HttpRequest.newBuilder(consumerUrl).timeout(properties.requestTimeout())
+        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder(consumerUrl).timeout(properties.requestTimeout())
             .header("Content-Type", "application/json")
-            .header("X-Internal-Service-Token", serviceToken)
+            .header("X-Internal-Service-Token", serviceToken);
+        HttpRequest request = tracePropagation.apply(requestBuilder)
             .POST(HttpRequest.BodyPublishers.ofString(objectMapper.writeValueAsString(envelope))).build();
         HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
         JsonNode responseBody;

event-bridge-service/src/main/java/com/baiyue/eventbridge/service/HttpLastlegEventClient.java

@@ -4,6 +4,7 @@ import com.baiyue.common.event.EventEnvelope;
 import com.baiyue.common.event.RegionCode;
 import com.baiyue.eventbridge.config.EventDispatcherProperties;
 import com.baiyue.eventbridge.domain.BridgeInbox;
+import com.baiyue.eventbridge.trace.EventBridgeHttpTracePropagation;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.springframework.beans.factory.annotation.Value;
@@ -19,6 +20,7 @@ import java.net.http.HttpResponse;
 public class HttpLastlegEventClient implements LastlegEventClient {
     @Resource private ObjectMapper objectMapper;
     @Resource private EventDispatcherProperties properties;
+    @Resource private EventBridgeHttpTracePropagation tracePropagation;
 
     @Value("${baiyue.security.internal-service-token:}")
     private String serviceToken;
@@ -38,10 +40,11 @@ public class HttpLastlegEventClient implements LastlegEventClient {
                 row.getHandoverVersion(), row.getTraceId(), row.getCorrelationId(), row.getCausationId(),
                 objectMapper.readTree(row.getPayloadJson()), row.getPayloadHash());
         String body = objectMapper.writeValueAsString(envelope);
-        HttpRequest request = HttpRequest.newBuilder(properties.consumerUrl())
+        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder(properties.consumerUrl())
                 .timeout(properties.requestTimeout())
                 .header("Content-Type", "application/json")
-                .header("X-Internal-Service-Token", serviceToken)
+                .header("X-Internal-Service-Token", serviceToken);
+        HttpRequest request = tracePropagation.apply(requestBuilder)
                 .POST(HttpRequest.BodyPublishers.ofString(body))
                 .build();
         HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

event-bridge-service/src/main/java/com/baiyue/eventbridge/service/HttpSecurityProjectionEventClient.java

@@ -4,9 +4,11 @@ import com.baiyue.common.event.EventEnvelope;
 import com.baiyue.common.event.RegionCode;
 import com.baiyue.eventbridge.config.EventDispatcherProperties;
 import com.baiyue.eventbridge.domain.BridgeInbox;
+import com.baiyue.eventbridge.trace.EventBridgeHttpTracePropagation;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.annotation.PostConstruct;
+import jakarta.annotation.Resource;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
 
@@ -19,6 +21,7 @@ import java.net.http.HttpResponse;
 public class HttpSecurityProjectionEventClient implements SecurityProjectionEventClient {
     private final ObjectMapper objectMapper;
     private final EventDispatcherProperties properties;
+    @Resource private EventBridgeHttpTracePropagation tracePropagation;
     @Value("${baiyue.event-dispatcher.security-consumer-url}") private URI consumerUrl;
     @Value("${baiyue.security.internal-service-token:}") private String serviceToken;
     private HttpClient httpClient;
@@ -39,18 +42,23 @@ public class HttpSecurityProjectionEventClient implements SecurityProjectionEven
                 row.getCustomerId(), row.getAggregateType(), row.getAggregateId(), row.getAggregateVersion(),
                 row.getHandoverVersion(), row.getTraceId(), row.getCorrelationId(), row.getCausationId(),
                 objectMapper.readTree(row.getPayloadJson()), row.getPayloadHash());
-        HttpRequest request = HttpRequest.newBuilder(consumerUrl).timeout(properties.requestTimeout())
+        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder(consumerUrl).timeout(properties.requestTimeout())
                 .header("Content-Type", "application/json")
-                .header("X-Internal-Service-Token", serviceToken)
+                .header("X-Internal-Service-Token", serviceToken);
+        HttpRequest request = tracePropagation.apply(requestBuilder)
                 .POST(HttpRequest.BodyPublishers.ofString(objectMapper.writeValueAsString(envelope))).build();
         HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
         JsonNode body;
         try { body = objectMapper.readTree(response.body()); }
         catch (Exception exception) { body = null; }
-        if (response.statusCode() / 100 != 2 || body == null || !"200".equals(body.path("code").asText())
-                || !row.getEventId().equals(body.path("data").path("eventId").asText())) {
-            throw new IllegalStateException("海外安全投影消费失败: HTTP " + response.statusCode());
-        }
+        requireAcknowledgement(response.statusCode(), body, row.getEventId());
         return String.valueOf(response.statusCode());
     }
+
+    static void requireAcknowledgement(int statusCode, JsonNode body, String eventId) {
+        if (statusCode / 100 != 2 || body == null || !"200".equals(body.path("code").asText())
+                || !eventId.equals(body.path("data").path("eventId").asText())) {
+            throw new IllegalStateException("Lastleg 安全投影消费失败: HTTP " + statusCode);
+        }
+    }
 }

event-bridge-service/src/main/java/com/baiyue/eventbridge/service/OverseasEventDispatcher.java

@@ -7,10 +7,13 @@ import com.baiyue.eventbridge.domain.BridgeInbox;
 import com.baiyue.eventbridge.mapper.BridgeDeliveryAttemptMapper;
 import com.baiyue.eventbridge.mapper.BridgeInboxMapper;
 import com.baiyue.eventbridge.metrics.EventBridgeMetrics;
+import com.baiyue.eventbridge.trace.EventBridgeTraceScope;
+import com.baiyue.common.web.CorrelationContext;
 import jakarta.annotation.Resource;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.scheduling.annotation.Scheduled;
 import org.springframework.stereotype.Component;
+import org.slf4j.MDC;
 
 import java.lang.management.ManagementFactory;
 import java.time.LocalDateTime;
@@ -42,6 +45,12 @@ public class OverseasEventDispatcher {
         }
 
         BridgeInbox event = inboxMapper.selectById(eventId);
+        try (EventBridgeTraceScope ignored = EventBridgeTraceScope.open(event)) {
+            dispatchClaimed(eventId, event);
+        }
+    }
+
+    private void dispatchClaimed(String eventId, BridgeInbox event) {
         int retryAttempt = event.getRetryCount() == null ? 1 : event.getRetryCount() + 1;
         int deliveryAttemptNo = inboxMapper.nextAttemptNo(eventId);
         BridgeDeliveryAttempt attempt = startAttempt(event, deliveryAttemptNo);
@@ -57,8 +66,8 @@ public class OverseasEventDispatcher {
                     : "FAILED_LEASE_LOST";
             finishAttempt(attempt, attemptStatus, null, error);
             metrics.recordTransport(event, EventBridgeMetrics.TransportResult.valueOf(attemptStatus));
-            log.warn("跨区事件投递失败 eventId={}, retryAttempt={}, deliveryAttempt={}, reason={}",
-                    eventId, retryAttempt, deliveryAttemptNo, error);
+            log.warn("跨区事件投递失败 eventId={}, retryAttempt={}, deliveryAttempt={}, traceId={}, reason={}",
+                    eventId, retryAttempt, deliveryAttemptNo, MDC.get(CorrelationContext.TRACE_ID), error);
             return;
         }
 
@@ -66,7 +75,8 @@ public class OverseasEventDispatcher {
             String error = "下游已确认成功，但事件租约已失效；保留当前 Inbox 状态并由新租约持有者幂等续投";
             finishAttempt(attempt, "ACKNOWLEDGED_LEASE_LOST", responseCode, error);
             metrics.recordTransport(event, EventBridgeMetrics.TransportResult.ACKNOWLEDGED_LEASE_LOST);
-            log.warn("跨区事件成功确认时租约已失效 eventId={}, deliveryAttempt={}", eventId, deliveryAttemptNo);
+            log.warn("跨区事件成功确认时租约已失效 eventId={}, deliveryAttempt={}, traceId={}",
+                    eventId, deliveryAttemptNo, MDC.get(CorrelationContext.TRACE_ID));
             return;
         }
         finishAttempt(attempt, "DELIVERED", responseCode, null);

event-bridge-service/src/main/java/com/baiyue/eventbridge/trace/EventBridgeHttpTracePropagation.java

@@ -0,0 +1,19 @@
+package com.baiyue.eventbridge.trace;
+
+import com.baiyue.common.web.CorrelationContext;
+import com.baiyue.common.web.OutboundTraceHeaders;
+import org.springframework.stereotype.Component;
+
+import java.net.http.HttpRequest;
+
+/** Applies a fresh child span to one raw JDK HttpClient request. */
+@Component
+public class EventBridgeHttpTracePropagation {
+    public HttpRequest.Builder apply(HttpRequest.Builder builder) {
+        OutboundTraceHeaders outbound = OutboundTraceHeaders.fromCurrentOrNew();
+        return builder
+                .setHeader(CorrelationContext.REQUEST_ID_HEADER, outbound.requestId())
+                .setHeader(CorrelationContext.TRACE_ID_HEADER, outbound.traceId())
+                .setHeader(CorrelationContext.TRACE_PARENT_HEADER, outbound.traceParent());
+    }
+}

event-bridge-service/src/main/java/com/baiyue/eventbridge/trace/EventBridgeTraceScope.java

@@ -0,0 +1,35 @@
+package com.baiyue.eventbridge.trace;
+
+import com.baiyue.common.web.CorrelationContext;
+import com.baiyue.common.web.OutboundTraceHeaders;
+import com.baiyue.eventbridge.domain.BridgeInbox;
+import org.slf4j.MDC;
+
+import java.util.Map;
+
+/** Establishes one trusted MDC context for an Event Bridge delivery attempt. */
+public final class EventBridgeTraceScope implements AutoCloseable {
+    private final Map<String, String> previous;
+
+    private EventBridgeTraceScope(Map<String, String> previous) {
+        this.previous = previous;
+    }
+
+    public static EventBridgeTraceScope open(BridgeInbox event) {
+        Map<String, String> previous = MDC.getCopyOfContextMap();
+        OutboundTraceHeaders local = OutboundTraceHeaders.fromTrustedTraceOrNew(event.getTraceId());
+        MDC.put(CorrelationContext.REQUEST_ID, local.requestId());
+        MDC.put(CorrelationContext.TRACE_ID, local.traceId());
+        MDC.put(CorrelationContext.SPAN_ID, local.spanId());
+        return new EventBridgeTraceScope(previous);
+    }
+
+    @Override
+    public void close() {
+        if (previous == null) {
+            MDC.clear();
+        } else {
+            MDC.setContextMap(previous);
+        }
+    }
+}

event-bridge-service/src/main/resources/application.yml

@@ -29,11 +29,11 @@ spring:
         namespace: ${NACOS_NAMESPACE:}
 
 baiyue:
-  region: ${REGION_CODE:OVERSEAS}
+  region: ${REGION_CODE:CN}
   event-dispatcher:
     consumer-url: ${EVENT_CONSUMER_URL:${LASTLEG_CONSUMER_URL:http://127.0.0.1:9303/internal/lastleg/events}}
     firstleg-consumer-url: ${FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL:http://127.0.0.1:9202/internal/firstleg/v1/container-events}
-    security-consumer-url: ${OVERSEAS_SECURITY_EVENT_CONSUMER_URL:http://127.0.0.1:9307/internal/overseas-security/v1/events}
+    security-consumer-url: ${LASTLEG_SECURITY_EVENT_CONSUMER_URL:http://127.0.0.1:9303/internal/lastleg/security/v1/events}
     fixed-delay: ${EVENT_DISPATCH_FIXED_DELAY:3000}
     batch-size: ${EVENT_DISPATCH_BATCH_SIZE:50}
     max-attempts: ${EVENT_DISPATCH_MAX_ATTEMPTS:10}

event-bridge-service/src/test/java/com/baiyue/eventbridge/metrics/EventBridgeMetricsTest.java

@@ -8,12 +8,32 @@ import org.junit.jupiter.api.Test;
 import java.lang.reflect.Modifier;
 import java.util.Arrays;
 
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.AnnotationConfigApplicationContext;
+
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.mockito.Mockito.mock;
 
 class EventBridgeMetricsTest {
 
+    @Test
+    void productionConstructorIsExplicitForSpringWhenTestClockConstructorAlsoExists() throws Exception {
+        assertThat(EventBridgeMetrics.class.getConstructor(MeterRegistry.class)
+                .isAnnotationPresent(Autowired.class)).isTrue();
+    }
+
+    @Test
+    void springContextCreatesMetricsBeanWithTheAnnotatedProductionConstructor() {
+        try (AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext()) {
+            context.registerBean(MeterRegistry.class, SimpleMeterRegistry::new);
+            context.register(EventBridgeMetrics.class);
+            context.refresh();
+
+            assertThat(context.getBean(EventBridgeMetrics.class)).isNotNull();
+        }
+    }
+
     @Test
     void collapsesUnboundedRegionAndEventTypeLabelsToOther() {
         SimpleMeterRegistry registry = new SimpleMeterRegistry();

event-bridge-service/src/test/java/com/baiyue/eventbridge/service/EventInboxServiceTest.java

@@ -65,6 +65,22 @@ class EventInboxServiceTest {
         assertThat(receiveCount("DUPLICATE")).isEqualTo(1.0);
     }
 
+    @Test
+    void 数据库毫秒精度截断后相同事件仍判定为重复() {
+        EventEnvelope source = envelope("sha256:placeholder");
+        EventEnvelope precise = new EventEnvelope(source.eventId(), source.eventType(), source.eventVersion(),
+                Instant.parse("2026-07-29T08:30:00.123456789Z"), source.sourceRegion(), source.targetRegion(),
+                source.tenantId(), source.aggregateType(), source.aggregateId(), source.aggregateVersion(),
+                source.handoverVersion(), source.traceId(), source.correlationId(), source.causationId(),
+                source.payload(), source.payloadHash());
+        EventEnvelope envelope = withHash(precise);
+        BridgeInbox existing = existing(envelope, envelope.payloadHash());
+        existing.setOccurredAt(Instant.parse("2026-07-29T08:30:00.123Z"));
+        when(store.findByEventId(envelope.eventId())).thenReturn(existing);
+
+        assertThat(service.receive(envelope).result()).isEqualTo("重复");
+    }
+
     @Test
     void 相同事件但摘要不同时拒绝覆盖() {
         EventEnvelope envelope = withHash(envelope("sha256:placeholder"));
@@ -109,6 +125,15 @@ class EventInboxServiceTest {
                 .hasMessageContaining("目标区域");
     }
 
+    @Test
+    void 本地单实例模式允许接收不同目标区域事件() {
+        EventInboxService localService = service("CN", true);
+        EventEnvelope envelope = withHash(envelope("sha256:placeholder"));
+
+        assertThat(localService.receive(envelope).result()).isEqualTo("已接收");
+        verify(store).insert(any(BridgeInbox.class));
+    }
+
     private EventEnvelope envelope(String hash) {
         return new EventEnvelope("550e8400-e29b-41d4-a716-446655440000", "OrderApproved", 1,
                 Instant.parse("2026-07-29T08:30:00Z"), RegionCode.CN, RegionCode.OVERSEAS,
@@ -117,11 +142,16 @@ class EventInboxServiceTest {
     }
 
     private EventInboxService service(String region) {
+        return service(region, false);
+    }
+
+    private EventInboxService service(String region, boolean acceptAnyRegion) {
         EventInboxService service = new EventInboxService();
         ReflectionTestUtils.setField(service, "inboxStore", store);
         ReflectionTestUtils.setField(service, "objectMapper", objectMapper);
         ReflectionTestUtils.setField(service, "metrics", metrics);
         ReflectionTestUtils.setField(service, "localRegion", region);
+        ReflectionTestUtils.setField(service, "acceptAnyRegion", acceptAnyRegion);
         return service;
     }
 

event-bridge-service/src/test/java/com/baiyue/eventbridge/service/HttpSecurityProjectionEventClientTest.java

@@ -0,0 +1,44 @@
+package com.baiyue.eventbridge.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+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.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class HttpSecurityProjectionEventClientTest {
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Test
+    void onlyMatchingLastlegAcknowledgementCompletesBridgeDelivery() throws Exception {
+        var acknowledged = objectMapper.readTree("""
+            {"code":"200","data":{"eventId":"event-1","result":"APPLIED"}}
+            """);
+        var businessFailure = objectMapper.readTree("""
+            {"code":"A0409","message":"payloadHash 冲突","data":{"eventId":"event-1"}}
+            """);
+        var wrongEvent = objectMapper.readTree("""
+            {"code":"200","data":{"eventId":"event-2","result":"DUPLICATE"}}
+            """);
+
+        assertThatCode(() -> HttpSecurityProjectionEventClient.requireAcknowledgement(
+            200, acknowledged, "event-1")).doesNotThrowAnyException();
+        assertThatThrownBy(() -> HttpSecurityProjectionEventClient.requireAcknowledgement(
+            200, businessFailure, "event-1")).isInstanceOf(IllegalStateException.class);
+        assertThatThrownBy(() -> HttpSecurityProjectionEventClient.requireAcknowledgement(
+            200, wrongEvent, "event-1")).isInstanceOf(IllegalStateException.class);
+    }
+
+    @Test
+    void defaultConsumerUrlTargetsLastlegSecurityEndpoint() throws Exception {
+        String application = Files.readString(Path.of("src/main/resources/application.yml"));
+
+        assertThat(application).contains(
+            "LASTLEG_SECURITY_EVENT_CONSUMER_URL:http://127.0.0.1:9303/internal/lastleg/security/v1/events")
+            .doesNotContain("/internal/overseas-security/v1/events");
+    }
+}

event-bridge-service/src/test/java/com/baiyue/eventbridge/service/OverseasEventDispatcherTest.java

@@ -7,11 +7,13 @@ import com.baiyue.eventbridge.domain.BridgeInbox;
 import com.baiyue.eventbridge.mapper.BridgeDeliveryAttemptMapper;
 import com.baiyue.eventbridge.mapper.BridgeInboxMapper;
 import com.baiyue.eventbridge.metrics.EventBridgeMetrics;
+import com.baiyue.common.web.CorrelationContext;
 import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.mockito.ArgumentCaptor;
 import org.springframework.test.util.ReflectionTestUtils;
+import org.slf4j.MDC;
 
 import java.net.URI;
 import java.time.Duration;
@@ -63,7 +65,12 @@ class OverseasEventDispatcherTest {
 
     @Test
     void successfulDeliveryIsConfirmedAndAudited() throws Exception {
-        when(eventClient.deliver(event)).thenReturn("200");
+        event.setTraceId("550e8400-e29b-41d4-a716-446655440000");
+        when(eventClient.deliver(event)).thenAnswer(invocation -> {
+            assertThat(MDC.get(CorrelationContext.TRACE_ID))
+                    .isEqualTo("550e8400e29b41d4a716446655440000");
+            return "200";
+        });
         when(inboxMapper.markProcessed(eq("event-1"), anyString())).thenReturn(1);
 
         dispatcher.dispatchOne("event-1");
@@ -74,6 +81,7 @@ class OverseasEventDispatcherTest {
         assertThat(updatedAttempt().getStatus()).isEqualTo("DELIVERED");
         assertThat(transportCount("DELIVERED")).isEqualTo(1.0);
         assertThat(registry.get(EventBridgeMetrics.DELIVERY_LATENCY_METRIC).timer().count()).isEqualTo(1);
+        assertThat(MDC.get(CorrelationContext.TRACE_ID)).isNull();
     }
 
     @Test

event-bridge-service/src/test/java/com/baiyue/eventbridge/trace/EventBridgeTracePropagationTest.java

@@ -0,0 +1,65 @@
+package com.baiyue.eventbridge.trace;
+
+import com.baiyue.common.web.CorrelationContext;
+import com.baiyue.eventbridge.domain.BridgeInbox;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.slf4j.MDC;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class EventBridgeTracePropagationTest {
+
+    @AfterEach
+    void clearMdc() {
+        MDC.clear();
+    }
+
+    @Test
+    void envelopeUuidFlowsThroughMdcAndRawHttpAsAChildSpan() {
+        BridgeInbox event = new BridgeInbox();
+        event.setTraceId("550e8400-e29b-41d4-a716-446655440000");
+        event.setCorrelationId("ORDER:customer-99:booking-123");
+        event.setEventId("event-business-id");
+
+        try (EventBridgeTraceScope ignored = EventBridgeTraceScope.open(event)) {
+            String localSpan = MDC.get(CorrelationContext.SPAN_ID);
+            HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create("http://127.0.0.1/internal"))
+                    .header(CorrelationContext.REQUEST_ID_HEADER, event.getEventId())
+                    .header(CorrelationContext.TRACE_ID_HEADER, event.getCorrelationId())
+                    .header(CorrelationContext.TRACE_PARENT_HEADER,
+                            "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-00");
+            HttpRequest request = new EventBridgeHttpTracePropagation().apply(builder).GET().build();
+
+            assertThat(MDC.get(CorrelationContext.TRACE_ID))
+                    .isEqualTo("550e8400e29b41d4a716446655440000");
+            assertThat(request.headers().firstValue(CorrelationContext.TRACE_ID_HEADER))
+                    .contains("550e8400e29b41d4a716446655440000");
+            assertThat(request.headers().firstValue(CorrelationContext.REQUEST_ID_HEADER).orElseThrow())
+                    .matches("[0-9a-f-]{36}").isNotEqualTo(event.getEventId());
+            assertThat(request.headers().firstValue(CorrelationContext.TRACE_PARENT_HEADER).orElseThrow())
+                    .matches("00-550e8400e29b41d4a716446655440000-[0-9a-f]{16}-01")
+                    .doesNotContain(localSpan);
+        }
+
+        assertThat(MDC.get(CorrelationContext.TRACE_ID)).isNull();
+    }
+
+    @Test
+    void invalidLegacyEnvelopeTraceIsSafelyRebuiltAndPreviousMdcIsRestored() {
+        MDC.put("existing", "preserved");
+        BridgeInbox event = new BridgeInbox();
+        event.setTraceId("JWT-or-business-id-value");
+
+        try (EventBridgeTraceScope ignored = EventBridgeTraceScope.open(event)) {
+            assertThat(MDC.get(CorrelationContext.TRACE_ID)).matches("[0-9a-f]{32}")
+                    .isNotEqualTo(event.getTraceId());
+        }
+
+        assertThat(MDC.get("existing")).isEqualTo("preserved");
+        assertThat(MDC.get(CorrelationContext.TRACE_ID)).isNull();
+    }
+}

file/AGENTS.md

@@ -12,6 +12,7 @@
 | 商户/平台资质 | `controller/QualificationFileController.java`、`PlatformQualificationFileController.java` |
 | 导出中心 | `controller/PlatformExportTaskController.java`、`service/ExportTaskService.java`、`service/ExportStateService.java`、`service/GenericXlsxExportRunner.java`、`config/ExportDefinitionRegistry.java`、`client/ExportProviderClient.java`、`mq/` |
 | 测量图片/证据 | `controller/PlatformMeasurementImageController.java`、`InternalMeasurementImageController.java`、`service/MeasurementImageService.java` |
+| 平台订单商品图片读取 | `controller/PlatformProductImageController.java` 的 `/api/platform/v1/files/product-images/{tenantId}/{fileId}`、`service/ProductImageService.java`；仅平台 `platform:order:list` 可按明确客户与文件 ID 内联读取，响应 `no-store` |
 | 装柜与业务文件证据 | `controller/PlatformLoadingEvidenceController.java`、`InternalLoadingEvidenceController.java`、`InternalBusinessFileController.java`、`service/InternalBusinessFileService.java` |
 | 财务付款凭证、海外卸柜照片 | 通用业务文件入口 `InternalBusinessFileController.java`、`InternalBusinessFileService.java`；业务类型分别为 `FINANCE_VOUCHER`、`OVERSEAS_UNLOAD_PHOTO`，必须按客户与业务 ID 精确校验 |
 | 存储与实体 | `service/LocalQualificationStorage.java`、`MeasurementImageStorage.java`、`entity/FileObjectEntity.java` |
@@ -23,6 +24,7 @@
 
 - 上传先写真实文件再登记 IAM 元数据；异常结果未知时保留文件供重试，禁止伪造 URL。
 - 所有文件按客户、入库单、文件类型校验归属；重量图片可 OCR，第三方尺寸证据不得触发重量 OCR。
+- 商品图片平台读取必须同时校验平台身份、`platform:order:list`、客户范围、文件业务类型与正整数 ID；不得提供匿名 URL、跨客户读取或把内部存储路径返回页面。
 - 公共导出只接受 `ExportDefinitionRegistry` 明确登记的 `exportType`，由 File 调用所属业务服务的内部 Provider 分批取数并生成文件；业务页面不得直连 Provider。新增或修改导出类型时同步检查业务服务 Provider、File Feign 客户端/响应上限、权限、Admin 下载中心标签与重试映射及契约测试。
 - 生产环境显式配置 `FILE_STORAGE_ROOT`；磁盘故障返回 `S0503`，不得包装成业务错误。
 

file/src/main/java/com/baiyue/file/controller/PlatformProductImageController.java

@@ -0,0 +1,55 @@
+package com.baiyue.file.controller;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.file.service.ProductImageService;
+import jakarta.annotation.Resource;
+import org.springframework.http.CacheControl;
+import org.springframework.http.ContentDisposition;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+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.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.nio.charset.StandardCharsets;
+
+/** 鐢ㄤ簬骞冲彴绔鍗曡鎯呮煡鐪嬪晢鎴峰晢鍝佸浘鐗囥€? */
+@RestController
+@RequestMapping("/api/platform/v1/files/product-images")
+public class PlatformProductImageController {
+    @Resource private ProductImageService images;
+
+    @GetMapping("/{tenantId}/{fileId}")
+    @PreAuthorize("hasAuthority('platform:order:list')")
+    public ResponseEntity<byte[]> download(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @PathVariable long tenantId,
+        @PathVariable long fileId) {
+        requirePlatform(user);
+        if (tenantId <= 0 || fileId <= 0) {
+            throw new BizException(ResultCode.BAD_REQUEST, "瀹㈡埛鍜屾枃浠禝D蹇呴』澶т簬0");
+        }
+        var image = images.download(tenantId, fileId);
+        return ResponseEntity.ok()
+            .cacheControl(CacheControl.noStore())
+            .contentType(MediaType.parseMediaType(image.contentType()))
+            .contentLength(image.content().length)
+            .header(HttpHeaders.CONTENT_DISPOSITION, ContentDisposition.inline()
+                .filename(image.fileName(), StandardCharsets.UTF_8).build().toString())
+            .body(image.content());
+    }
+
+    private static void requirePlatform(AuthenticatedUser user) {
+        if (user == null || !"PLATFORM".equalsIgnoreCase(user.appCode())
+            || user.tenantId() == null || user.tenantId() != 0L
+            || user.userId() == null || user.userId() <= 0) {
+            throw new BizException(ResultCode.FORBIDDEN, "闇€瑕佸钩鍙扮韬唤");
+        }
+    }
+}

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

@@ -20,7 +20,7 @@ public class InternalBusinessFileService {
         "CUSTOMS_RECEIPT",
         "FINANCE_VOUCHER",
         "CONTAINER_CLEARANCE_DOCUMENT",
-        "LOADING_CUSTOMS_DOCUMENT",
+        "LOADING_CUSTOMS_DECLARATION",
         "CONTAINER_DELIVERY_ORDER",
         "CONTAINER_PICKUP_ORDER",
         "OVERSEAS_UNLOAD_PHOTO",

file/src/test/java/com/baiyue/file/client/ExportProviderFeignConfigurationTest.java

@@ -9,9 +9,14 @@ import org.springframework.boot.autoconfigure.http.HttpMessageConverters;
 import java.nio.charset.StandardCharsets;
 import java.util.Map;
 
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 class ExportProviderFeignConfigurationTest {
+    @Test void keepsOpenFeignFormEncoderOnTheRuntimeClasspath() {
+        assertDoesNotThrow(() -> Class.forName("feign.form.spring.SpringFormEncoder"));
+    }
+
     @Test void rejectsAnOversizedProviderResponseBeforeJsonDeserialization() {
         ExportProviderFeignConfiguration configuration=new ExportProviderFeignConfiguration();
         Decoder decoder=configuration.exportProviderDecoder(HttpMessageConverters::new);

file/src/test/java/com/baiyue/file/controller/InternalBusinessFileControllerTest.java

@@ -35,14 +35,14 @@ class InternalBusinessFileControllerTest {
     }
 
     @Test void zeroTenantDownloadReturnsOwnedContentWithoutCaching() {
-        when(service.download(0L, "LOADING_CUSTOMS_DOCUMENT", "51", 91L))
+        when(service.download(0L, "LOADING_CUSTOMS_DECLARATION", "51", 91L))
             .thenReturn(new InternalBusinessFileService.Download("declaration.pdf", "application/pdf", new byte[]{1, 2}));
 
-        var response = controller.download("internal-token", 0L, "LOADING_CUSTOMS_DOCUMENT", "51", 91L);
+        var response = controller.download("internal-token", 0L, "LOADING_CUSTOMS_DECLARATION", "51", 91L);
 
         assertThat(response.getBody()).containsExactly(1, 2);
         assertThat(response.getHeaders().getCacheControl()).contains("no-store");
-        verify(service).download(0L, "LOADING_CUSTOMS_DOCUMENT", "51", 91L);
+        verify(service).download(0L, "LOADING_CUSTOMS_DECLARATION", "51", 91L);
     }
 
     @Test void rejectsInvalidTokenAndNegativeTenantBeforeServiceAccess() {

file/src/test/java/com/baiyue/file/controller/ProductImageControllerContractTest.java

@@ -77,6 +77,26 @@ class ProductImageControllerContractTest {
         assertThatThrownBy(() -> controller.upload(platform, file)).isInstanceOf(BizException.class);
     }
 
+    @Test
+    void platformDownloadUsesTenantScopeAndOrderListPermission() throws Exception {
+        RequestMapping mapping = PlatformProductImageController.class.getAnnotation(RequestMapping.class);
+        assertThat(mapping.value()).contains("/api/platform/v1/files/product-images");
+        var download = PlatformProductImageController.class.getDeclaredMethod(
+            "download", AuthenticatedUser.class, long.class, long.class);
+        assertThat(download.getAnnotation(PreAuthorize.class).value())
+            .isEqualTo("hasAuthority('platform:order:list')");
+
+        ProductImageService service = mock(ProductImageService.class);
+        PlatformProductImageController controller = new PlatformProductImageController();
+        ReflectionTestUtils.setField(controller, "images", service);
+        when(service.download(10001L, 31L)).thenReturn(
+            new ProductImageService.Download("product.png", "image/png", new byte[] {1}));
+
+        var platform = new AuthenticatedUser(1L, 0L, 0L, 1L, "admin", "PLATFORM", "WEB", Set.of());
+        assertThat(controller.download(platform, 10001L, 31L).getBody()).containsExactly(1);
+        verify(service).download(10001L, 31L);
+    }
+
     private static AuthenticatedUser merchant(long tenantId) {
         return new AuthenticatedUser(2L, tenantId, tenantId, 2L, "merchant", "MERCHANT", "WEB", Set.of());
     }

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

@@ -47,7 +47,7 @@ class InternalBusinessFileServiceTest {
         });
 
         var clearance = service.upload(0L, "CONTAINER_CLEARANCE_DOCUMENT", "41", 7L, file);
-        var customs = service.upload(0L, "LOADING_CUSTOMS_DOCUMENT", "51", 7L, file);
+        var customs = service.upload(0L, "LOADING_CUSTOMS_DECLARATION", "51", 7L, file);
         var deliveryOrder = service.upload(0L, "CONTAINER_DELIVERY_ORDER", "41", 7L, file);
         var pickupOrder = service.upload(0L, "CONTAINER_PICKUP_ORDER", "41", 7L, file);
         var unloadPhoto = service.upload(11L, "OVERSEAS_UNLOAD_PHOTO", "51", 7L, file);
@@ -57,7 +57,7 @@ class InternalBusinessFileServiceTest {
             InternalBusinessFileService.Metadata::businessId).containsExactly(0L, "CONTAINER_CLEARANCE_DOCUMENT", "41");
         assertThat(customs).extracting(InternalBusinessFileService.Metadata::tenantId,
             InternalBusinessFileService.Metadata::businessType,
-            InternalBusinessFileService.Metadata::businessId).containsExactly(0L, "LOADING_CUSTOMS_DOCUMENT", "51");
+            InternalBusinessFileService.Metadata::businessId).containsExactly(0L, "LOADING_CUSTOMS_DECLARATION", "51");
         assertThat(deliveryOrder.businessType()).isEqualTo("CONTAINER_DELIVERY_ORDER");
         assertThat(pickupOrder.businessType()).isEqualTo("CONTAINER_PICKUP_ORDER");
         assertThat(unloadPhoto).extracting(InternalBusinessFileService.Metadata::tenantId,
@@ -119,22 +119,23 @@ class InternalBusinessFileServiceTest {
 
     @Test void platformMetadataAndDownloadRequireExactCompositeOwnership() {
         FileObjectEntity value = new FileObjectEntity(); value.setId(91L); value.setTenantId(0L);
-        value.setBusinessType("LOADING_CUSTOMS_DOCUMENT"); value.setBusinessId("51");
+        value.setBusinessType("LOADING_CUSTOMS_DECLARATION"); value.setBusinessId("51");
         value.setOriginalName("declaration.pdf"); value.setObjectKey("business-files/0/51/declaration.pdf");
         value.setContentType("application/pdf"); value.setSha256("c".repeat(64)); value.setSizeBytes(8L);
         when(files.selectOne(any())).thenReturn(value, value, null, null, null);
         when(storage.read(value.getObjectKey())).thenReturn("document".getBytes());
 
-        assertThat(service.metadata(0L, "LOADING_CUSTOMS_DOCUMENT", "51", 91L).fileName())
+        assertThat(service.metadata(0L, "LOADING_CUSTOMS_DECLARATION", "51", 91L).fileName())
             .isEqualTo("declaration.pdf");
-        assertThat(service.download(0L, "LOADING_CUSTOMS_DOCUMENT", "51", 91L).content())
+        assertThat(service.download(0L, "LOADING_CUSTOMS_DECLARATION", "51", 91L).content())
             .isEqualTo("document".getBytes());
         assertThatThrownBy(() -> service.metadata(0L, "CONTAINER_CLEARANCE_DOCUMENT", "51", 91L))
             .isInstanceOf(BizException.class).hasMessageContaining("归属不匹配");
-        assertThatThrownBy(() -> service.metadata(0L, "LOADING_CUSTOMS_DOCUMENT", "52", 91L))
+        assertThatThrownBy(() -> service.metadata(0L, "LOADING_CUSTOMS_DECLARATION", "52", 91L))
             .isInstanceOf(BizException.class).hasMessageContaining("归属不匹配");
-        assertThatThrownBy(() -> service.metadata(0L, "LOADING_CUSTOMS_DOCUMENT", "51", 92L))
+        assertThatThrownBy(() -> service.metadata(0L, "LOADING_CUSTOMS_DECLARATION", "51", 92L))
             .isInstanceOf(BizException.class).hasMessageContaining("归属不匹配");
         verify(storage).read(value.getObjectKey());
     }
+
 }

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

@@ -13,8 +13,8 @@ final class FinanceOperatorSnapshot {
         Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
         if (authentication != null && authentication.getPrincipal() instanceof AuthenticatedUser user
                 && user.userId() != null && user.userId() == operatorId
-                && StringUtils.hasText(user.username())) {
-            return user.username().trim();
+                && (StringUtils.hasText(user.displayName()) || StringUtils.hasText(user.username()))) {
+            return StringUtils.hasText(user.displayName()) ? user.displayName().trim() : user.username().trim();
         }
         return null;
     }

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

@@ -41,23 +41,26 @@ public class ReceivableStatisticsService {
         LocalDate from = month.atDay(1);
         LocalDate to = month.plusMonths(1).atDay(1);
         StringBuilder sql = new StringBuilder("""
-            SELECT tenant_id, customer_name_snapshot,
-                   SUM(total_amount) total_receivable,
-                   SUM(paid_amount) total_received,
-                   SUM(outstanding_amount) total_outstanding
-              FROM fin_settlement
-             WHERE direction='RECEIVABLE'
-               AND status<>'VOIDED'
-               AND currency_code='CNY'
-               AND generated_date>=?
-               AND generated_date<?
+            SELECT s.tenant_id,
+                   COALESCE(p.customer_name_snapshot, MAX(s.customer_name_snapshot)) customer_name_snapshot,
+                   SUM(s.total_amount) total_receivable,
+                   SUM(s.paid_amount) total_received,
+                   SUM(s.outstanding_amount) total_outstanding
+              FROM fin_settlement s
+              LEFT JOIN fin_customer_settlement_profile p
+                ON p.tenant_id=s.tenant_id AND p.status='ACTIVE'
+             WHERE s.direction='RECEIVABLE'
+               AND s.status<>'VOIDED'
+               AND s.currency_code='CNY'
+               AND s.generated_date>=?
+               AND s.generated_date<?
             """);
         List<Object> args = new ArrayList<>(List.of(from, to));
         if (customerId != null) {
-            sql.append(" AND tenant_id=?");
+            sql.append(" AND s.tenant_id=?");
             args.add(customerId);
         }
-        sql.append(" GROUP BY tenant_id,customer_name_snapshot ORDER BY customer_name_snapshot,tenant_id");
+        sql.append(" GROUP BY s.tenant_id,p.customer_name_snapshot ORDER BY customer_name_snapshot,s.tenant_id");
         return jdbc.query(sql.toString(), (rs, rowNum) -> checked(new ReceivableStatisticsRow(
             rs.getLong("tenant_id"), rs.getString("customer_name_snapshot"), CURRENCY,
             rs.getBigDecimal("total_receivable"), rs.getBigDecimal("total_received"),

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

@@ -68,7 +68,9 @@ public class ReconciliationStatementService {
         CustomerProfile customer = customer(request.customerId());
         long subjectId = activeSubject();
         List<Source> sources = eligibleSources(request);
-        if (sources.isEmpty()) throw error("FIN_409", "没有符合结算条件的CNY应收费用来源");
+        if (sources.isEmpty()) {
+            throw error("FIN_409", "当前客户在所选账期内没有可生成的CNY应收费用，请调整账期或选择其他客户后重试");
+        }
         BigDecimal total = sources.stream().map(Source::amount).reduce(BigDecimal.ZERO, BigDecimal::add);
         LocalDate dueDate = request.periodEnd().plusDays(customer.creditDays());
         String statementNo = documentNumbers.next("REC");

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

@@ -40,8 +40,8 @@ class ReceivableStatisticsServiceTest {
         assertThat(result.records()).containsExactly(rows.get(0));
         var sql = org.mockito.ArgumentCaptor.forClass(String.class);
         verify(jdbc).query(sql.capture(), any(RowMapper.class), any(Object[].class));
-        assertThat(sql.getValue()).contains("direction='RECEIVABLE'", "status<>'VOIDED'", "currency_code='CNY'",
-            "generated_date>=?", "generated_date<?", "GROUP BY tenant_id,customer_name_snapshot");
+        assertThat(sql.getValue()).contains("s.direction='RECEIVABLE'", "s.status<>'VOIDED'", "s.currency_code='CNY'",
+            "s.generated_date>=?", "s.generated_date<?", "fin_customer_settlement_profile", "GROUP BY s.tenant_id,p.customer_name_snapshot");
     }
 
     @Test

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

@@ -28,6 +28,16 @@ class FinanceOperatorSnapshotTest {
         assertThat(FinanceOperatorSnapshot.currentName(72L)).isNull();
     }
 
+    @Test
+    void prefersAuthenticatedDisplayNameOverLoginUsername() {
+        AuthenticatedUser user = new AuthenticatedUser(71L, null, null, null,
+            "12555214478", "廖万昌", "MERCHANT", "WEB", Set.of(), false, null, null, false);
+        SecurityContextHolder.getContext().setAuthentication(
+            new UsernamePasswordAuthenticationToken(user, null));
+
+        assertThat(FinanceOperatorSnapshot.currentName(71L)).isEqualTo("廖万昌");
+    }
+
     @Test
     void labelsSystemGeneratedEntriesWithoutInventingAnOperator() {
         assertThat(FinanceOperatorSnapshot.currentName(0L)).isEqualTo("系统");

firstleg/AGENTS.md

@@ -10,10 +10,11 @@
 
 | 目标 | 入口 |
 |---|---|
+| 内部模块化基线与依赖分析 | `docs/firstleg-internal-modularization-baseline.md`、`scripts/analyze-firstleg-dependencies.mjs`、`scripts/analyze-firstleg-dependencies.test.mjs`、`src/test/resources/architecture/firstleg-slice-dependencies.json`；只约束本服务内部包依赖，不改变部署单元或数据库边界 |
 | 履约任务/分配 | `controller/PlatformFulfillmentAssignmentController.java`、`service/FulfillmentTaskService.java` |
 | 入库单查询/聚合 | `controller/PlatformInboundOrderController.java`、`service/InboundOrderQueryService.java` |
 | 平台测量/OCR | `controller/PlatformInboundMeasurementController.java`、`service/InboundMeasurementService.java`、`service/CartonMeasurementService.java`；手工单箱测量也从该 Controller 与 `CartonMeasurementService` 进入 |
-| 箱唛箱码生成、打印与测量绑定 | 审核建单生成钩子 `controller/InternalInboundOrderController.java`；生成/解析 `service/InboundCartonLabelService.java`、`repository/InboundCartonLabelRepository.java`；平台与客户打印 `controller/PlatformInboundOrderController.java`、`MerchantInboundCartonLabelController.java`、`service/InboundCartonLabelPrintService.java`；基线/升级 SQL 为 `src/main/resources/db/phase2-inbound-carton-label.sql`、`phase2-carton-label-versioning-migration.sql` |
+| 箱唛箱码生成、打印与测量绑定 | 审核建单生成钩子 `controller/InternalInboundOrderController.java`；生成/解析 `service/InboundCartonLabelService.java`、`repository/InboundCartonLabelRepository.java`；平台与客户打印 `controller/PlatformInboundOrderController.java`、`MerchantInboundCartonLabelController.java`、`service/InboundCartonLabelPrintService.java`。`fl_inbound_carton_label.sku_code` 是箱唛的 SKU 冻结快照，生成时经 `client/OrderCargoClient.java` 获取；既有记录按 `inbound_detail_id` 回填。`ONE_CLICK_DROPSHIP` 缺 SKU 时禁止生成箱唛。`box_code`、二维码内容和现有打印版式不携带 SKU，不能因该绑定改变。基线/升级 SQL 为 `src/main/resources/db/phase2-inbound-carton-label.sql`、`phase2-carton-label-versioning-migration.sql`、`../deploy/sql/头程数据库统一增量-MySQL8.sql` |
 | 墨家设备测量上传 | `controller/OpenApiInboundMeasurementController.java`、`dto/MojiaMeasurementDtos.java`、`service/MojiaMeasurementOpenApiService.java`、`security/MeasurementRequestAuthenticator.java`；接口契约见 `src/main/resources/openapi/firstleg-v1.yaml` 与 `../../docs/墨家设备测量上传接口说明-V3.md` |
 | 审核与初始计价 | `controller/PlatformInboundMeasurementReviewController.java`、`service/MeasurementReviewService.java`、`service/InitialInboundPricingService.java`、`dto/MeasurementApprovalResponse.java` |
 | FBA 主数据/计费 | `controller/PlatformFbaMasterDataController.java`、`PlatformFbaPricingController.java`、`service/FbaPricingService.java` |
@@ -22,19 +23,22 @@
 | 客户费用查询 | `controller/MerchantInboundBillingController.java`、`service/MerchantInboundBillingService.java` |
 | 客户运营统计/在途柜量 | `customerstatistics/controller/PlatformCustomerTransitStatisticsController.java`、`customerstatistics/service/CustomerTransitStatisticsService.java`；契约见 `src/main/resources/openapi/customer-statistics-v1.yaml` |
 | 费用项目与价格簿 | `controller/PlatformFeeItemController.java`、`PlatformPriceBookController.java`、`MerchantPriceBookController.java` |
+| 价格簿查询内部切片 | `pricebookquery/application/port/in/PriceBookQueryUseCase.java`、`application/PriceBookQueryService.java`、`application/port/out/PriceBookQueryReader.java`、`adapter/out/persistence/PriceBookQueryMapper.java`；查询行模型位于 `application/model/PriceBookQueryRows.java` |
 | 财务费用来源快照 | `controller/InternalFinanceFeeSourceController.java`；入库费用与柜次费用分别按来源 ID、版本向 Finance 提供不可变快照 |
 | 柜次费用明细 | `controller/PlatformContainerFeeDetailController.java`、`service/ContainerFeeDetailService.java`、`dto/ContainerFeeDetailDtos.java`；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` |
 | 货柜与智能排柜 | `controller/PlatformContainerController.java`、`PlatformSmartLoadingController.java`、`service/SmartLoadingService.java`、`repository/SmartLoadingRepository.java`、`loading/`；按入仓码候选与箱数分配分别从 `/inbound-candidates`、`/plans/{planId}/inbound-assignments` 进入，明细规格拆分留在服务端 |
+| 货柜资料、PDA 证据与业务总览 | `controller/PlatformContainerController.java` 的 `/{id}/overview`、`/{id}/documents/{documentType}`，聚合 `mapper/ContainerOverviewMapper.java`；契约 `src/main/resources/openapi/phase3-container-overview-v1.yaml`，四类资料固定为目的港清关、国内出口报关、DO、PU 的当前唯一版本 |
 | PDA 拣货与装柜 | `controller/PlatformLoadingPdaController.java`、`loading/controller/PlatformLoadingDeliveryController.java` |
 | 装柜完成跨区事件 | `service/LoadingCompletedOutboxService.java`、`LoadingCompletedOutboxRelay.java`、`repository/LoadingCompletedOutboxRepository.java`、`mapper/LoadingCartonManifestMapper.java`、`client/EventBridgeClient.java`；从 `fl_inbound_order.destination_type` 冻结 V2 `orders[].destinationType=FBA|OVERSEAS`，OVERSEAS 按最终实装与稳定箱码冻结，FBA 可仅冻结箱数；真实生产验收 `src/test/java/com/baiyue/firstleg/service/TaillegRealProducerAcceptanceTest.java`；事件模型见 `../common-event-contract/AGENTS.md` |
 | 海外卸柜完成事件回写 | 内部入口 `controller/InternalOverseasContainerEventController.java`、消费者 `service/OverseasContainerEventConsumer.java`、Inbox `entity/ContainerEventInboxEntity.java` 与 `mapper/ContainerEventInboxMapper.java`；事件模型见 `../common-event-contract/AGENTS.md` |
-| 三期海运订舱与出仓前船期资料 | `oceanbooking/controller/PlatformOceanBookingController.java`、`oceanbooking/service/OceanBookingService.java`、`portschedule/controller/PlatformPortScheduleController.java`；订舱契约见 `src/main/resources/openapi/ocean-bookings-v1.yaml`，表结构见 `src/main/resources/db/phase3-ocean-booking-schema.sql` |
+| 海外暂扣状态回写 | 同一内部事件入口、消费者 `service/OverseasInboundOrderDetainedConsumer.java`；按来源入仓单 ID 更新 `fl_inbound_order.hold_flag/current_hold_reason`，复用跨区 Inbox 并写 `fl_inbound_hold_record` |
+| 三期海运订舱、关联候选与出仓前船期资料 | `oceanbooking/controller/PlatformOceanBookingController.java`、`oceanbooking/service/OceanBookingService.java`、`oceanbooking/mapper/OceanBookingMapper.java`、`portschedule/controller/PlatformPortScheduleController.java`；关联候选入口 `/api/platform/v1/ocean-bookings/link-candidates`，订舱契约见 `src/main/resources/openapi/ocean-bookings-v1.yaml`，表结构见 `src/main/resources/db/phase3-ocean-booking-schema.sql` |
 | 四期国内出仓后船节点定时查询 | `outbound/dispatch/service/OutboundDispatchService.java` 在确认出仓事务内幂等创建现有 `CarrierScheduleQuery`；编排与租约 `portschedule/service/CarrierScheduleQueryScheduler.java`，任务/十节点事实/异常事实/不可变 attempt `CarrierScheduleQueryService.java`，平台查询与人工补录入口 `PlatformCarrierScheduleQueryController.java` 的 `/{queryId}/manual-nodes`；停止只由实际 `EMPTY_RETURNED` 节点触发，不提供无节点停止入口；外部船司/轨迹调用经 `integration-service/`；标准见 `../../docs/四期/船节点标准化契约.md` |
 | 船节点跨区交接事件 | `portschedule/service/CarrierScheduleNodeOutboxService.java`；实际节点落库后发布 `FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED` V1，复用 `LoadingCompletedOutboxRepository`/Relay 投 Event Bridge；海外消费见 `../lastleg-service/src/main/java/com/baiyue/lastleg/shipping/service/ContainerShippingNodeConsumer.java` |
 | Firstleg 业务单据编号 | `service/FirstlegDocumentNumberGenerator.java`；当前支持 `OB`、`TA`、`CB`、`CAB`、`LP` 前缀，按北京时间每日独立编号；具体业务归属以各调用服务为准 |
-| 拖车与出仓调度 | `controller/PlatformTruckAppointmentController.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java` |
+| 拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；按真实 `containerBookingId` 查询聚合和 `gate`、确认离仓，契约 `src/main/resources/openapi/phase3-outbound-dispatch-v1.yaml` |
 | 报关协同 | `customs/controller/PlatformCustomsController.java`、`MerchantCustomsController.java` |
 | 跨模型桥接 | `loading/bridge/controller/PlatformLoadingModelBridgeController.java` |
 | 跨服务客户端 | `client/OrderCargoClient.java`、`WarehousePalletLocationClient.java`、`MeasurementImageClient.java`、`LoadingEvidenceFileClient.java`、`EventBridgeClient.java` |
@@ -44,15 +48,21 @@
 
 ## 修改约束
 
+- 移动包、拆分端口/适配器或引入新的跨切片依赖时，先核对内部模块化基线并运行 `node --test scripts/analyze-firstleg-dependencies.test.mjs`；确需更新依赖基线时必须说明稳定边界变化，不能把临时循环依赖登记为长期豁免。
 - 平台接口必须校验目标客户、权限、乐观锁、幂等键、历史和审计；商户查询只能使用登录态客户。
+- 价格簿查询消费者依赖 `PriceBookQueryUseCase` 或稳定查询端口，不得反向依赖持久化 Mapper；移动旧查询类时同步更新生产调用、测试、Mock 与 import，避免同一职责在根 `repository/mapper` 和 `pricebookquery/` 双写。
 - 第三方回传必须签名、时间窗、防重放、请求哈希，并绑定订单货物和 File 证据；不得信任外部客户字段。
 - 稳定箱码映射以入库快照和 Order 货物明细为事实；订单审核创建入库单时必须幂等生成，打印接口只复用或补齐同一映射，用户是否下载箱唛不得决定箱码有效性。手工测量、墨家设备和 PDA 扫码统一通过 `InboundCartonLabelService` 校验客户、入库单、货物明细、总箱数/下标和有效批次，不得在测量时临时伪造箱码或接受跨客户、跨入库箱码。
+- 一件代发以 `fl_inbound_carton_label.sku_code` 作为不可变 SKU 快照；PDA 仍只扫描稳定 `box_code`，不得将 SKU 塞入二维码或以 SKU 替代箱码。实际打托后的查询必须能按“现场托盘 -> 客户 -> SKU -> 箱数”聚合；历史箱唛仅能在同客户、同入库单范围内按 `inbound_detail_id` 回填，禁止按货名、箱规或箱号猜测 SKU。修改本链路时同步检查 `OrderCargoClient`、Order 内部货物接口及 PDA 打托实现。
 - 测量审核通过后直接进入 `WAIT_SPLIT`，费用仅作为独立初算和人工维护结果，不得阻塞或回退订单主流程；计费量、单价和附加费调整必须版本化并由服务端重算金额。状态或 DTO 变更时逐个检查 Order/Warehouse/File/Integration 消费者。
 - 报关、订舱和拖车引用的供应商必须通过 `WarehouseSupplierSnapshotService` 按 ID 向 Warehouse 校验：报关使用 `CUSTOMS`，订舱使用 `BOOKING`（不区分国内/国外 scope），拖车使用 `TRUCKING`；供应商必须为 `ACTIVE`。请求中的名称只能作为一致性提示，持久化名称必须来自 Warehouse 快照，禁止用自由文本绕过 ID、类别或启用状态校验。修改任一供应商引用 DTO、OpenAPI 或内部客户端时，必须同步检查三条业务链、Warehouse `supplier-v1.yaml`、数据库快照字段和对应契约测试。
 - 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后永久只读。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
 - 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。
 - 订舱号统一使用 `OB-yyMMdd-####`，按北京时间创建日每日独立递增且单日最多 9999；不得以实体 ID 拼接生成。放舱不要求真实柜号，也不得为满足放舱校验伪造柜号。
+- 订舱列表 `containerCount` 固定为该订舱全部柜型需求 `quantity` 之和，与真实柜关联/解除无关；关联候选只返回 `RELEASED`、剩余数量大于 0 且 `warehouseId + channelCode + containerType` 精确匹配的需求，由服务端集合查询 ACTIVE 分配量。前端不得扇出详情计算或用已关联柜数覆盖该字段，最终关联命令仍须重验目标货柜可修改性。
 - 四期船节点任务从确认柜子离开国内仓库后启用，必须绑定真实订舱和柜次；十个标准节点、预计/实际时间、异常事实、供应商缺失节点和还柜停止规则统一以 `../../docs/四期/船节点标准化契约.md` 为准。`CarrierScheduleQuery` 的正常业务查询槽位固定为 `Asia/Shanghai` 每日 09:00、12:30、16:00；每分钟任务只扫描已到期 `next_allowed_at`，不是每分钟请求船司。成功、无变化、需人工或永久失败进入下一固定槽位；仅技术性 `RETRYABLE_FAILURE` 在当前槽内按15/30分钟退避，含首次最多3次且不得跨下一槽，实际 `EMPTY_RETURNED` 后停止。错过的正常槽位直接顺延，不在服务恢复时补跑；单轮按受控批次持续领取并受最大任务数保护。租约、调度尝试和内部停止入口不得暴露为平台页面 API，外部失败不得推进业务节点，不得在三期另建查询任务。
+- 国内出仓确认以真实 `containerBookingId` 聚合全部入仓绑定并锁定校验；装柜证据按物理货柜只计算一次，国内出口报关资料必须存在且已完成，拖车状态和独立船期只作参考。全部门禁在同一事务通过后推进所有技术行、记录一条可见历史并幂等创建 `CarrierScheduleQuery/DEPARTED_WAREHOUSE`，不允许单入仓局部成功。
+- 手工船节点的预计时间只追加事实，不推进 `latestStandardNode`；携带 `actualAt` 时标准节点序号必须严格大于最新实际节点，重复、相同或回退节点返回冲突。已审核实际时间修正只能更新同一事实的时间/证据，不得制造第二条同节点实际事实或绕过单调推进。
 - 海外卸柜完成事件只接受 `OVERSEAS -> CN` 的 `OVERSEAS_CONTAINER_UNLOADED` V1，并通过内部服务令牌进入。消费者必须校验信封、Payload 哈希、来源货柜和时间顺序，以 event ID + Payload 哈希幂等，使用事件聚合版本阻止乱序覆盖；预计报空时间固定按卸柜照片上传时间加两天计算，实际报空时间可为空。
 - Firstleg 只拥有业务费用及履约事实；Finance 拥有费用入池、账期、账单、收款、成本分摊结果和财务状态。修改费用来源版本、发布条件、柜次归属或体积快照时同步检查 `../finance/src/main/java/com/baiyue/finance/client/FirstlegFeeSourceClient.java`、同目录 `FirstlegCostSnapshotClient.java` 及双方契约测试，不在 Firstleg 复制财务状态机。
 - `DIRECT_PAID` 仅适用于 `PAYABLE`，必须同时保存 `paidAt`、合法 `paymentMethod`，并至少提供 `paymentReferenceNo` 或一个当前客户范围内的 `FINANCE_VOUCHER`；`RECEIVABLE` 与 `ON_ACCOUNT` 不得残留付款字段。创建、调整和审核前均通过 `FeePaymentSnapshotValidator` 失败关闭复核。

firstleg/docs/firstleg-internal-modularization-baseline.md

@@ -1,4 +1,4 @@
-# Firstleg 内部模块化基线与首切片方案
+# Firstleg 内部模块化基线与切片实施记录
 
 ## 1. 范围与生成方式
 
@@ -198,3 +198,53 @@ mvn -pl firstleg -am -Dtest=CustomerTransitStatisticsServiceTest,CustomerTransit
 - 根 Mapper 扫描只把旧精确包替换为新精确包，没有扩大扫描范围或增加兼容 Bean。
 - 验证结果：Node 合同 3/3；`test-compile` 成功；客户统计加根扫描定向测试 7/7；`mvn -pl firstleg -am test` 共 854 个测试，0 失败、0 错误、3 跳过，构建成功。
 - 首次并发执行 `test-compile` 时，其他专项同时写入共享 `target/classes` 导致若干无关 class 文件瞬时缺失；源符号核对正常，独立重跑 `test-compile` 与完整测试均成功。
+
+## 12. 第二切片：价格簿只读查询
+
+### 12.1 选择证据
+
+第二切片选择 `pricebook-query`，而没有选择报关、拖车、出仓或船节点：
+
+- 原实现只有 `PriceBookQueryRows`、`PriceBookQueryRepository`、`PriceBookQueryMapper` 三个核心文件，全部为只读查询，不承载 Controller、权限或状态机。
+- `PriceBookQueryMapper -> repository.PriceBookQueryRows` 是主源码唯一 `mapper -> repository` 反向依赖，也是物理包 SCC `mapper <-> repository` 的唯一成因。
+- 报关和拖车均涉及 MultipartFile、Feign、装柜或出仓门禁；出仓和船节点属于当前业务热点，风险高于只读价格簿查询。
+- 本切片不触碰 `LoadingPickService`、客户尺寸初始化、IAM 解环、POM、CI、AGENTS、SQL 或部署配置。
+
+### 12.2 目标结构与依赖方向
+
+```text
+pricebookquery/
+  application/
+    PriceBookQueryService.java
+    model/PriceBookQueryRows.java
+    port/in/PriceBookQueryUseCase.java
+    port/out/PriceBookQueryReader.java
+  adapter/out/persistence/
+    PriceBookQueryMapper.java
+```
+
+依赖由“多个业务 Service -> 全局 Repository -> 全局 Mapper -> Repository Rows”改为：
+
+```text
+业务消费者 -> PriceBookQueryUseCase
+PriceBookQueryService -> PriceBookQueryReader
+PriceBookQueryMapper -> PriceBookQueryReader + PriceBookQueryRows
+```
+
+消费者只能访问 In Port 和只读模型；application 不依赖 Spring MVC、MyBatis、MyBatis-Plus 或其他 Firstleg 切片。Mapper 的七段 `@Select` SQL 文本和方法参数保持不变。
+
+### 12.3 依赖图变化
+
+- 主源码由 430 类/949 条内部依赖/67 包变为 432 类/953 条内部依赖/72 包；新增项为 In Port、Out Port 和 Application Service，原 Repository 被删除。
+- 物理包多节点 SCC 从 1 个降为 0 个。
+- `pricebook-query` 是零出向边的叶子，不进入逻辑 SCC；显式入向仅为订舱、测量计价、分柜装柜三个消费者切片。
+- 原 `split-loading -> measurement-pricing` 两条价格簿引用被替换为显式 `split-loading -> pricebook-query`；Node 合同没有简单放宽旧边。
+- 既有 88 条跨切片 Entity/DTO 泄漏和 31 条 Mapper 泄漏均未增加。
+
+### 12.4 棘轮与回滚边界
+
+- Node 合同锁定五个目标类位置、application 依赖禁令、零出向/三类入向和消费者只能访问 In Port/模型，并断言物理包 SCC 为空。
+- `PriceBookQueryArchitectureTest` 用 ArchUnit 执行同等边界，持久化 Mapper 必须实现 Out Port。
+- 回滚仅恢复原三文件及消费者类型引用；不涉及 URI、权限、JSON、SQL、表结构、业务状态或环境配置。
+- 只读模型仍保留原 Lombok 可变 Bean 形态以维持 MyBatis 映射行为；本轮不顺带改造成不可变领域对象。
+- 验证结果：七段 `@Select` SQL 文本逐块完全一致；Node 合同 5/5；`test-compile` 成功；价格簿、ArchUnit、根扫描及三个消费者切片定向测试 78/78；Firstleg 聚合全量 878 个测试，0 失败、0 错误、3 跳过，构建成功。

firstleg/scripts/analyze-firstleg-dependencies.mjs

@@ -13,6 +13,7 @@ const internalPrefix = 'com.baiyue.firstleg.';
 
 const sliceRules = [
   ['customer-statistics', /(?:^|\.)(?:customerstatistics)(?:\.|$)/],
+  ['pricebook-query', /(?:^|\.)(?:pricebookquery)(?:\.|$)/],
   ['finance-integration', /(?:InternalFinance|FinanceFeeSource|FinanceCostSnapshot|FeePaymentVoucher|FeePaymentSnapshot|ContainerFeeSourceSnapshot)/],
   ['shipping-nodes', /(?:CarrierScheduleQuery|CarrierScheduleNode|CarrierScheduleAdapter|CarrierScheduleAttempt|CarrierScheduleException)/],
   ['booking-customs-trucking', /(?:^|\.)(?:oceanbooking|customs)(?:\.|$)|(?:TruckAppointment|WarehouseSupplier|PortSchedule|DispatchGate)/],
@@ -273,8 +274,9 @@ function checkContract(report, contractPath) {
     if (!actualClass) violations.push(`required class missing: ${fqcn}`);
     else if (actualClass.file !== expectedFile) violations.push(`class location changed: ${fqcn} (${actualClass.file})`);
   }
-  const applicationRule = contract.applicationDependencyRule;
-  if (applicationRule) {
+  const applicationRules = contract.applicationDependencyRules
+    ?? (contract.applicationDependencyRule ? [contract.applicationDependencyRule] : []);
+  for (const applicationRule of applicationRules) {
     const applicationClasses = report.classes.filter(entry => entry.packageName.startsWith(applicationRule.packagePrefix));
     for (const entry of applicationClasses) {
       for (const imported of entry.imports) {
@@ -291,6 +293,15 @@ function checkContract(report, contractPath) {
       }
     }
   }
+  for (const exposureRule of contract.sliceExposureRules ?? []) {
+    for (const edge of report.classDependencies) {
+      if (!edge.source.startsWith(exposureRule.slicePrefix)
+          && edge.target.startsWith(exposureRule.slicePrefix)
+          && !(exposureRule.allowedTargetPrefixes ?? []).some(prefix => edge.target.startsWith(prefix))) {
+        violations.push(`forbidden slice implementation dependency: ${edge.source} -> ${edge.target}`);
+      }
+    }
+  }
   for (const [slice, rule] of Object.entries(contract.sliceSpecificRules ?? {})) {
     const outgoing = report.sliceEdges.filter(edge => edge.source === slice).map(edge => edge.target).sort();
     const incoming = report.sliceEdges.filter(edge => edge.target === slice).map(edge => edge.source).sort();

firstleg/scripts/analyze-firstleg-dependencies.test.mjs

@@ -52,3 +52,43 @@ test('customer statistics application layer only depends inward', () => {
     && edge.target.startsWith('com.baiyue.firstleg.') && !edge.target.startsWith(prefix));
   assert.deepEqual(outwardDependencies, []);
 });
+
+test('price book query is a leaf slice and removes the package cycle', () => {
+  const report = analyze();
+  const classes = report.classes.filter(entry => entry.slice === 'pricebook-query');
+  assert.deepEqual(classes.map(entry => entry.fqcn).sort(), [
+    'com.baiyue.firstleg.pricebookquery.adapter.out.persistence.PriceBookQueryMapper',
+    'com.baiyue.firstleg.pricebookquery.application.PriceBookQueryService',
+    'com.baiyue.firstleg.pricebookquery.application.model.PriceBookQueryRows',
+    'com.baiyue.firstleg.pricebookquery.application.port.in.PriceBookQueryUseCase',
+    'com.baiyue.firstleg.pricebookquery.application.port.out.PriceBookQueryReader',
+  ]);
+  assert.deepEqual(report.sliceEdges.filter(edge => edge.source === 'pricebook-query'), []);
+  assert.deepEqual(report.sliceEdges.filter(edge => edge.target === 'pricebook-query')
+    .map(edge => edge.source).sort(), ['booking-customs-trucking', 'measurement-pricing', 'split-loading']);
+  assert.equal(report.sliceSccs.some(component => component.includes('pricebook-query')), false);
+  assert.deepEqual(report.packageSccs, []);
+});
+
+test('price book query application and consumers respect ports', () => {
+  const report = analyze();
+  const prefix = 'com.baiyue.firstleg.pricebookquery.application';
+  const applicationClasses = report.classes.filter(entry => entry.packageName.startsWith(prefix));
+  assert.equal(applicationClasses.length, 4);
+  for (const entry of applicationClasses) {
+    assert.equal(entry.imports.some(imported => imported.startsWith('org.springframework.web')), false);
+    assert.equal(entry.imports.some(imported => imported.startsWith('org.apache.ibatis')), false);
+    assert.equal(entry.imports.some(imported => imported.startsWith('com.baomidou.mybatisplus')), false);
+  }
+  const outwardDependencies = report.classDependencies.filter(edge => edge.source.startsWith(prefix)
+    && edge.target.startsWith('com.baiyue.firstleg.') && !edge.target.startsWith(prefix));
+  assert.deepEqual(outwardDependencies, []);
+  const allowedTargets = [
+    'com.baiyue.firstleg.pricebookquery.application.model.',
+    'com.baiyue.firstleg.pricebookquery.application.port.in.',
+  ];
+  const implementationLeaks = report.classDependencies.filter(edge => !edge.source.startsWith('com.baiyue.firstleg.pricebookquery.')
+    && edge.target.startsWith('com.baiyue.firstleg.pricebookquery.')
+    && !allowedTargets.some(prefixValue => edge.target.startsWith(prefixValue)));
+  assert.deepEqual(implementationLeaks, []);
+});

firstleg/src/main/java/com/baiyue/firstleg/BaiyueFirstlegApplication.java

@@ -18,7 +18,8 @@ import org.springframework.scheduling.annotation.EnableScheduling;
         "com.baiyue.firstleg.outbound.dispatch.mapper",
         "com.baiyue.firstleg.portschedule.mapper",
         "com.baiyue.firstleg.customs.mapper",
-        "com.baiyue.firstleg.customerstatistics.adapter.out.persistence"
+        "com.baiyue.firstleg.customerstatistics.adapter.out.persistence",
+        "com.baiyue.firstleg.pricebookquery.adapter.out.persistence"
 })
 @EnableFeignClients(basePackages = "com.baiyue.firstleg")
 @EnableScheduling

firstleg/src/main/java/com/baiyue/firstleg/client/OrderCargoClient.java

@@ -63,7 +63,12 @@ public interface OrderCargoClient {
     }
 
     record CargoLabelBinding(Long cargoId, Long orderId, Integer itemNo, String cargoName,
-                             Integer packageCount, BigDecimal lengthCm, BigDecimal widthCm,
+                             String skuNo, Integer packageCount, BigDecimal lengthCm, BigDecimal widthCm,
                              BigDecimal heightCm) {
+        public CargoLabelBinding(Long cargoId, Long orderId, Integer itemNo, String cargoName,
+                                 Integer packageCount, BigDecimal lengthCm, BigDecimal widthCm,
+                                 BigDecimal heightCm) {
+            this(cargoId, orderId, itemNo, cargoName, null, packageCount, lengthCm, widthCm, heightCm);
+        }
     }
 }

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

@@ -4,8 +4,9 @@ import com.baiyue.common.core.api.ApiResponse;
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import com.baiyue.common.event.EventEnvelope;
-import com.baiyue.firstleg.entity.ContainerBookingEntity;
+import com.baiyue.common.event.EventTypes;
 import com.baiyue.firstleg.service.OverseasContainerEventConsumer;
+import com.baiyue.firstleg.service.OverseasInboundOrderDetainedConsumer;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -20,14 +21,17 @@ import java.security.MessageDigest;
 @RequiredArgsConstructor
 public class InternalOverseasContainerEventController {
     private final OverseasContainerEventConsumer consumer;
+    private final OverseasInboundOrderDetainedConsumer detainedConsumer;
     @Value("${baiyue.security.internal-service-token}") private String expectedToken;
 
     @PostMapping("/internal/firstleg/v1/container-events")
-    public ApiResponse<ContainerBookingEntity> receive(
+    public ApiResponse<Object> receive(
         @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
         @RequestBody EventEnvelope event) {
         authenticate(token);
-        return ApiResponse.success(consumer.consume(event));
+        Object result = EventTypes.OVERSEAS_INBOUND_ORDER_DETAINED_CHANGED.equals(event.eventType())
+            ? detainedConsumer.consume(event) : consumer.consume(event);
+        return ApiResponse.success(result);
     }
 
     private void authenticate(String token) {

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

@@ -128,6 +128,21 @@ public class PlatformContainerController {
         return ApiResponse.success(loadingLists.containerClearance(id));
     }
 
+    @GetMapping("/{id}/clearance/document/{fileId}/download")
+    @PreAuthorize("hasAuthority('platform:firstleg:customs:manage')")
+    @Operation(summary = "下载货柜目的港清关附件", description = "校验当前清关附件和 File 业务归属，完成态仍可下载。")
+    public ResponseEntity<byte[]> downloadClearance(
+        @AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long id,
+        @PathVariable @Positive long fileId) {
+        FirstlegScopeGuard.platform(user);
+        var download = loadingLists.downloadContainerClearance(id, fileId);
+        return ResponseEntity.ok().cacheControl(CacheControl.noStore())
+            .header(HttpHeaders.CONTENT_DISPOSITION, org.springframework.http.ContentDisposition.attachment()
+                .filename(download.fileName(), StandardCharsets.UTF_8).build().toString())
+            .contentType(download.contentType()).contentLength(download.content().length)
+            .body(download.content());
+    }
+
     @PostMapping("/{id}/clearance/document")
     @PreAuthorize("hasAuthority('platform:firstleg:customs:manage')")
     @Operation(summary = "上传或替换货柜目的港清关资料")

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

@@ -25,6 +25,10 @@ import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.Positive;
 import jakarta.validation.constraints.Size;
 import org.springframework.http.MediaType;
+import org.springframework.http.CacheControl;
+import org.springframework.http.ContentDisposition;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.validation.annotation.Validated;
@@ -40,6 +44,8 @@ import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.bind.annotation.RequestPart;
 import org.springframework.web.multipart.MultipartFile;
 
+import java.nio.charset.StandardCharsets;
+
 /** 基于同一装柜计划聚合提供平台预装清单和已确认装柜清单。 */
 @Tag(name = "平台预装与装柜清单", description = "预装单向推进和已确认装柜清单只读查询")
 @Validated
@@ -124,6 +130,21 @@ public class PlatformLoadingListController {
         return ApiResponse.success(service.loadingDeclaration(planId, warehouseId));
     }
 
+    @Operation(summary = "下载装柜清单出口报关附件", description = "完成态仍可下载；服务端校验装柜计划、仓库、当前附件及 File 业务归属。")
+    @GetMapping("/loading-lists/{planId}/customs/document/{fileId}/download")
+    @PreAuthorize("hasAuthority('platform:firstleg:loading-list:list')")
+    public ResponseEntity<byte[]> downloadDeclaration(
+        @AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long planId,
+        @PathVariable @Positive long fileId, @RequestParam @Positive long warehouseId) {
+        FirstlegScopeGuard.platform(user);
+        var download = service.downloadLoadingDeclaration(planId, warehouseId, fileId);
+        return ResponseEntity.ok().cacheControl(CacheControl.noStore())
+            .header(HttpHeaders.CONTENT_DISPOSITION, ContentDisposition.attachment()
+                .filename(download.fileName(), StandardCharsets.UTF_8).build().toString())
+            .contentType(download.contentType()).contentLength(download.content().length)
+            .body(download.content());
+    }
+
     @Operation(summary = "上传或替换装柜清单出口报关文档")
     @PostMapping("/loading-lists/{planId}/customs/document")
     @PreAuthorize("hasAuthority('platform:firstleg:customs:manage')")

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

@@ -17,6 +17,11 @@ import java.util.List;
 import com.baiyue.firstleg.dto.LoadingPickDtos.Task;
 import com.baiyue.firstleg.service.FirstlegScopeGuard;
 import com.baiyue.firstleg.service.LoadingPickService;
+import com.baiyue.firstleg.service.LoadingWorkPalletService;
+import com.baiyue.firstleg.dto.LoadingPalletDtos.OpenRequest;
+import com.baiyue.firstleg.dto.LoadingPalletDtos.ScanRequest;
+import com.baiyue.firstleg.dto.LoadingPalletDtos.SealRequest;
+import com.baiyue.firstleg.dto.LoadingPalletDtos.Pallet;
 import jakarta.annotation.Resource;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotBlank;
@@ -41,6 +46,8 @@ import org.springframework.web.bind.annotation.RestController;
 public class PlatformLoadingPdaController {
     @Resource
     private LoadingPickService service;
+    @Resource
+    private LoadingWorkPalletService palletService;
 
     @GetMapping("/tasks")
     @PreAuthorize("hasAuthority('platform:firstleg:pda:view')")
@@ -164,4 +171,45 @@ public class PlatformLoadingPdaController {
         FirstlegScopeGuard.platform(user);
         return ApiResponse.success(service.operations(taskId));
     }
+
+    @GetMapping("/tasks/{taskId}/pallets")
+    @PreAuthorize("hasAuthority('platform:firstleg:pda:view')")
+    public ApiResponse<List<Pallet>> pallets(@AuthenticationPrincipal AuthenticatedUser user,
+                                             @PathVariable @Positive long taskId,
+                                             @RequestParam @Positive long warehouseId) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(palletService.list(taskId, warehouseId));
+    }
+
+    @PostMapping("/tasks/{taskId}/pallets/open")
+    @PreAuthorize("hasAuthority('platform:firstleg:pda:work')")
+    public ApiResponse<Pallet> openPallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @PathVariable @Positive long taskId,
+                                          @Valid @RequestBody OpenRequest request) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(palletService.open(taskId, request, user.userId(), user.username()));
+    }
+
+    /** 扫到其他未封托托盘上的箱唛时，同时完成按箱移托。 */
+    @PostMapping("/tasks/{taskId}/pallets/{palletId}/cartons/scan")
+    @PreAuthorize("hasAuthority('platform:firstleg:pda:work')")
+    public ApiResponse<Pallet> scanCarton(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @PathVariable @Positive long taskId,
+                                          @PathVariable @Positive long palletId,
+                                          @Valid @RequestBody ScanRequest request) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(palletService.scan(taskId, palletId, request,
+            user.userId(), user.username()));
+    }
+
+    @PostMapping("/tasks/{taskId}/pallets/{palletId}/seal")
+    @PreAuthorize("hasAuthority('platform:firstleg:pda:work')")
+    public ApiResponse<Pallet> sealPallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @PathVariable @Positive long taskId,
+                                          @PathVariable @Positive long palletId,
+                                          @Valid @RequestBody SealRequest request) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(palletService.seal(taskId, palletId, request,
+            user.userId(), user.username()));
+    }
 }

firstleg/src/main/java/com/baiyue/firstleg/customs/mapper/CustomsCaseMapper.java

@@ -2,4 +2,10 @@ package com.baiyue.firstleg.customs.mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.customs.entity.CustomsCaseEntity;
 import org.apache.ibatis.annotations.Mapper;
-@Mapper public interface CustomsCaseMapper extends BaseMapper<CustomsCaseEntity> {}
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+@Mapper public interface CustomsCaseMapper extends BaseMapper<CustomsCaseEntity> {
+    @Select("SELECT COUNT(*) FROM fl_container_document WHERE container_booking_id=#{containerBookingId} "
+        + "AND document_type='CUSTOMS_DECLARATION' AND completed_at IS NOT NULL")
+    int completedLoadingDeclaration(@Param("containerBookingId") long containerBookingId);
+}

firstleg/src/main/java/com/baiyue/firstleg/customs/repository/CustomsRepository.java

@@ -81,6 +81,9 @@ public class CustomsRepository {
             .eq(CustomsCaseEntity::getContainerBookingId, containerBookingId)
             .orderByDesc(CustomsCaseEntity::getUpdatedAt).last("LIMIT 1"));
     }
+    public boolean loadingDeclarationCompleted(long containerBookingId) {
+        return cases.completedLoadingDeclaration(containerBookingId) == 1;
+    }
     public boolean containerCarriesOrder(long containerId, long tenantId, long orderId) {
         LoadingPlanEntity plan = loadingPlans.selectOne(new LambdaQueryWrapper<LoadingPlanEntity>()
             .eq(LoadingPlanEntity::getContainerBookingId, containerId));

firstleg/src/main/java/com/baiyue/firstleg/customs/service/CustomsDispatchGateContributor.java

@@ -1,6 +1,5 @@
 package com.baiyue.firstleg.customs.service;
 
-import com.baiyue.firstleg.customs.entity.CustomsCaseEntity;
 import com.baiyue.firstleg.customs.repository.CustomsRepository;
 import com.baiyue.firstleg.outbound.dispatch.dto.OutboundDispatchDtos.GateItem;
 import com.baiyue.firstleg.outbound.dispatch.gate.OutboundDispatchGateContributor;
@@ -18,13 +17,11 @@ public class CustomsDispatchGateContributor implements OutboundDispatchGateContr
         if (context.tenantId() <= 0 || context.customerId() <= 0) {
             return gate(false, "INVALID_CUSTOMER_SCOPE");
         }
-        CustomsCaseEntity value = repository.gateCase(context.tenantId(), context.orderId(),
-            context.inboundId(), context.containerBookingId());
-        if (value == null) return gate(false, "MISSING");
-        return gate("CLEARANCE_COMPLETED".equals(value.getStatus()), value.getStatus());
+        boolean completed = repository.loadingDeclarationCompleted(context.containerBookingId());
+        return gate(completed, completed ? "COMPLETED" : "MISSING");
     }
 
     private static GateItem gate(boolean passed, String actual) {
-        return new GateItem("CUSTOMS_CLEARANCE", "报关完成", passed, actual, "CLEARANCE_COMPLETED");
+        return new GateItem("CUSTOMS_CLEARANCE", "报关完成", passed, actual, "COMPLETED");
     }
 }

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

@@ -41,9 +41,15 @@ public final class InboundMeasurementRequests {
         @NotBlank @Size(max = 32) String itemNo,
         @NotBlank @Size(max = 64) String boxSpecification,
         @NotNull @Positive @Max(1000000) Integer packageCount,
-        @NotNull @DecimalMin("0.001") @Digits(integer = 9, fraction = 3) BigDecimal lengthCm,
-        @NotNull @DecimalMin("0.001") @Digits(integer = 9, fraction = 3) BigDecimal widthCm,
-        @NotNull @DecimalMin("0.001") @Digits(integer = 9, fraction = 3) BigDecimal heightCm,
+        @NotNull @DecimalMin(value = "0.001", message = "箱规长度必须大于等于 0.001 cm")
+        @DecimalMax(value = "999999999.999", message = "箱规长度不能超过 999,999,999.999 cm")
+        @Digits(integer = 9, fraction = 3, message = "箱规长度最多 9 位整数、3 位小数") BigDecimal lengthCm,
+        @NotNull @DecimalMin(value = "0.001", message = "箱规宽度必须大于等于 0.001 cm")
+        @DecimalMax(value = "999999999.999", message = "箱规宽度不能超过 999,999,999.999 cm")
+        @Digits(integer = 9, fraction = 3, message = "箱规宽度最多 9 位整数、3 位小数") BigDecimal widthCm,
+        @NotNull @DecimalMin(value = "0.001", message = "箱规高度必须大于等于 0.001 cm")
+        @DecimalMax(value = "999999999.999", message = "箱规高度不能超过 999,999,999.999 cm")
+        @Digits(integer = 9, fraction = 3, message = "箱规高度最多 9 位整数、3 位小数") BigDecimal heightCm,
         @Positive Long intelligentImageFileId,
         @Size(max = 500) String overLimitWarning,
         @DecimalMin("0.000") @Digits(integer = 9, fraction = 3) BigDecimal outerLengthCm,

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

@@ -0,0 +1,41 @@
+package com.baiyue.firstleg.dto;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+
+import java.util.List;
+
+/** 一件代发PDA现场打托接口模型。 */
+public final class LoadingPalletDtos {
+    private LoadingPalletDtos() {}
+
+    public record OpenRequest(
+        @NotNull @Min(1) Long warehouseId,
+        @Min(1) Long warehousePalletId,
+        @NotBlank @Size(max = 64) String palletCode,
+        @NotBlank @Size(max = 128) String operationId
+    ) {}
+
+    public record ScanRequest(
+        @NotNull @Min(1) Long warehouseId,
+        @NotBlank @Size(max = 80) String boxCode,
+        @NotBlank @Size(max = 128) String operationId
+    ) {}
+
+    public record SealRequest(
+        @NotNull @Min(1) Long warehouseId,
+        @NotNull @Min(0) Integer expectedVersion,
+        @NotBlank @Size(max = 128) String operationId
+    ) {}
+
+    public record Carton(Long id, String boxCode, String skuCode, Long tenantId,
+                         Long inboundId, Long inboundDetailId, Integer unitsPerCarton) {}
+
+    public record SkuSummary(String skuCode, Integer cartonCount, Long productQuantity) {}
+
+    public record Pallet(Long id, String palletCode, Long warehousePalletId, String status,
+                         Integer version, Integer cartonCount, Integer skuCount,
+                         Integer customerCount, List<SkuSummary> skus, List<Carton> cartons) {}
+}

firstleg/src/main/java/com/baiyue/firstleg/entity/InboundCartonLabelEntity.java

@@ -22,6 +22,7 @@ public class InboundCartonLabelEntity {
     private Long inboundDetailId;
     private Integer cargoItemNo;
     private String cargoName;
+    private String skuCode;
     private Integer detailPackageCount;
     private String inboundCode;
     private String boxCode;