一件代发拣货

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

.gitignore

@@ -1,4 +1,5 @@
 target/
+node_modules/
 .docker-context/
 *.log
 .idea/

.gitlab-ci.yml

@@ -13,6 +13,55 @@ cache:
   paths:
     - .m2/repository/
 
+Java拓扑合同:
+  stage: verify
+  image: node:22-alpine
+  cache: []
+  script:
+    - node --test scripts/java-topology-contract.test.mjs
+
+OpenAPI有效性:
+  stage: verify
+  image: node:22-alpine
+  cache: []
+  script:
+    - npm ci --ignore-scripts --prefix scripts/openapi-validation
+    - npm test --prefix scripts/openapi-validation
+    - npm run validate --prefix scripts/openapi-validation
+
+静态分析报告:
+  stage: verify
+  allow_failure: true
+  script:
+    - mvn $MAVEN_CLI_OPTS -Pstatic-analysis-report -DskipTests verify
+  artifacts:
+    when: always
+    expire_in: 7 days
+    paths:
+      - "**/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:
@@ -25,10 +74,14 @@ cache:
         - "**/target/surefire-reports/TEST-*.xml"
     paths:
       - "**/target/surefire-reports/"
+      - "**/target/site/jacoco/"
+      - "**/target/jacoco.exec"
 
 打包服务:
   stage: package
   needs:
+    - Java拓扑合同
+    - OpenAPI有效性
     - 校验与测试
   script:
     - mvn $MAVEN_CLI_OPTS -DskipTests package
@@ -36,14 +89,17 @@ cache:
     expire_in: 7 days
     paths:
       - gateway/target/*.jar
+      - gateway-overseas/target/*.jar
       - auth/target/*.jar
       - iam/target/*.jar
       - order/target/*.jar
       - firstleg/target/*.jar
+      - finance/target/*.jar
       - warehouse/target/*.jar
+      - warehouse-overseas-service/target/*.jar
+      - lastleg-service/target/*.jar
       - file/target/*.jar
       - print/target/*.jar
       - audit-service/target/*.jar
       - integration-service/target/*.jar
       - event-bridge-service/target/*.jar
-

.runtime-tailleg/DbQuery.java

@@ -0,0 +1,39 @@
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
+import java.sql.Statement;
+
+public final class DbQuery {
+    public static void main(String[] args) throws Exception {
+        if (args.length < 2) {
+            throw new IllegalArgumentException("usage: DbQuery <database> <sql>");
+        }
+        String url = "jdbc:mysql://127.0.0.1:3306/" + args[0]
+            + "?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai"
+            + "&useSSL=false&allowPublicKeyRetrieval=true";
+        try (Connection connection = DriverManager.getConnection(url, "root", "123456");
+             Statement statement = connection.createStatement()) {
+            boolean hasResult = statement.execute(args[1]);
+            if (!hasResult) {
+                System.out.println("updateCount=" + statement.getUpdateCount());
+                return;
+            }
+            try (ResultSet result = statement.getResultSet()) {
+                ResultSetMetaData meta = result.getMetaData();
+                for (int column = 1; column <= meta.getColumnCount(); column++) {
+                    if (column > 1) System.out.print("\t");
+                    System.out.print(meta.getColumnLabel(column));
+                }
+                System.out.println();
+                while (result.next()) {
+                    for (int column = 1; column <= meta.getColumnCount(); column++) {
+                        if (column > 1) System.out.print("\t");
+                        System.out.print(String.valueOf(result.getObject(column)));
+                    }
+                    System.out.println();
+                }
+            }
+        }
+    }
+}

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,12 +20,16 @@
 |---|---|---|
 | 登录、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/` |
 | 客户账期、费用池、账单、收款、成本、核销 | `finance/` | `finance/AGENTS.md`；费用来源和柜次成本快照再联查 `firstleg/AGENTS.md`，凭证再联查 `file/AGENTS.md` |
+| 入库/柜次应付、直接已付、付款流水与凭证 | `firstleg/`、`finance/`、`file/` | 业务费用与付款快照见 `firstleg/AGENTS.md` 的 `FeePaymentSnapshotValidator`；`/api/platform/finance/v1/vouchers` 上传凭证，File 按 `FINANCE_VOUCHER` 和客户范围校验 |
 | 仓库、往来单位、快递、托盘、库位 | `warehouse/` | `warehouse/AGENTS.md` |
 | 供应商、国内整柜库存与出入库 | `warehouse/` | `warehouse/AGENTS.md`；OpenAPI `warehouse/src/main/resources/openapi/supplier-v1.yaml`、`domestic-container-v1.yaml` |
 | 客户运营统计、在途柜量 | `firstleg/` | `firstleg/AGENTS.md`；OpenAPI `firstleg/src/main/resources/openapi/customer-statistics-v1.yaml` |
@@ -34,9 +38,28 @@
 | 路由、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 状态与权限版本投影 | `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/` 定位 |
-| 海外仓库、海外库位、海外托盘、资源锁 | `warehouse-overseas-service/` | `warehouse-overseas-service/AGENTS.md` |
-| PDF 标签、审计、事件 | `print/`、`audit-service/`、`event-bridge-service/` | 各服务指引 |
+| 海外入仓分页、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 `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/`，海外资源归 `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` |
+
+## 公共模块快速索引
+
+| 关键词 | 模块与入口 |
+|---|---|
+| 公共依赖版本 | `platform-bom/pom.xml`；统一管理公共组件版本，不放业务实现 |
+| 通用响应、分页、异常、基础实体与导出契约 | `common-core/`；从 `ApiResponse.java`、`PageResult.java`、`BizException.java`、`ExportContracts.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` 定位 |
+| 跨区域事件信封、Payload 与哈希 | `common-event-contract/`；继续读该目录 `AGENTS.md` |
 
 ## 全量验收路由
 
@@ -47,7 +70,7 @@
 
 - 国内头程 Auth 是唯一用户账号和 Token 签发方；Admin/Client 共用一套前端和用户体系，海外仓不得另建登录或权限模型。
 - 统一使用 RS256/JWKS。国内登录/刷新时由 Auth 同时签发国内 Token 和短时海外 Token；前端统一认证层按国内/海外 API Base 自动选择。国内服务叠加 Redis 会话校验，海外服务不得访问国内 Redis，只按限定 Audience 的海外 Token Claims 完成本地认证和授权；海外业务请求不得经国内 Gateway 中转。
-- 头程与海外仓的入库单、装柜结果、费用来源和财务回传走 MQ Outbox/Inbox 事件链；事件不携带用户 JWT，服务身份由 MQ TLS/ACL 或内部服务令牌负责。跨区事件契约、幂等和死信分别查 `common-event-contract/`、`event-bridge-service/` 与目标消费者。
+- 头程装柜完成向海外建尾程单、海外 PDA 卸柜完成向国内回写货柜报空事实，以及后续费用来源和财务回传，统一走 MQ Outbox/Inbox 事件链；事件不携带用户 JWT，服务身份由 MQ TLS/ACL 或内部服务令牌负责。跨区事件契约、幂等和死信分别查 `common-event-contract/`、`event-bridge-service/` 与目标消费者。
 - 海外浏览器请求只进入 `gateway-overseas/`，由其路由到 `lastleg-service/`、`warehouse-overseas-service/` 及海外部署的公共服务；不得经国内 `gateway/` 中转。`lastleg-service` 不读取头程数据库，`warehouse-overseas-service` 不读取尾程订单库。
 
 ## 契约、数据库与验证入口
@@ -58,8 +81,11 @@
 - 供应商查询接口固定只使用 `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 覆盖、PDA 运行配置/独立更新/语言预留、人工分段验收链、Lastleg 海外安全投影、同步 Trace、模块覆盖、关键入口与排除目录，不访问 HTTP、数据库或部署环境。
+- 单服务镜像构建/部署从 `Jenkinsfile.service`、`deploy/docker/Dockerfile`、`deploy/scripts/deploy-built-service.sh` 进入；新镜像启动失败或健康检查失败时只允许回滚到同服务先前镜像，并保持任务失败，离线合同见 `scripts/deploy-built-service-rollback.test.mjs`。实际部署仍须当前对话明确授权。
 
 ## 全量 HTTP 验收脚本路由
 
@@ -67,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,10 +1,11 @@
 def serviceModules = [
-    'gateway', 'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
-    'integration-service', 'event-bridge-service', 'audit-service'
+    'gateway', 'gateway-overseas', 'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
+    'integration-service', 'lastleg-service', 'warehouse-overseas-service', 'event-bridge-service', 'audit-service'
 ]
 
 def serviceCheckboxes = [
     'gateway': 'SERVICE_GATEWAY',
+    'gateway-overseas': 'SERVICE_GATEWAY_OVERSEAS',
     'auth': 'SERVICE_AUTH',
     'iam': 'SERVICE_IAM',
     'firstleg': 'SERVICE_FIRSTLEG',
@@ -14,29 +15,98 @@ def serviceCheckboxes = [
     'file': 'SERVICE_FILE',
     'print': 'SERVICE_PRINT',
     'integration-service': 'SERVICE_INTEGRATION',
+    'lastleg-service': 'SERVICE_LASTLEG',
+    'warehouse-overseas-service': 'SERVICE_WAREHOUSE_OVERSEAS',
     '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']
         : ['test', 'development', 'staging', 'production']
 }
 
+def downstreamJobPrefixForJob(String jobBaseName) {
+    return jobBaseName == 'backend-java-dev'
+        ? 'baiyue-firstleg-dev-'
+        : 'baiyue-firstleg-'
+}
+
 pipeline {
     // 总控流水线只识别变更并调度独立的服务 Job；实际 Maven、镜像和部署在 Jenkinsfile.service 中完成。
-    agent any
+    agent none
 
     options {
         disableConcurrentBuilds()
@@ -47,6 +117,7 @@ pipeline {
     parameters {
         choice(name: 'BUILD_MODE', choices: ['AUTO', 'SELECT', 'ALL'], description: 'AUTO 按 Git 变更识别；SELECT 勾选服务；ALL 构建全部服务')
         booleanParam(name: 'SERVICE_GATEWAY', defaultValue: false, description: 'Gateway 网关服务（gateway）')
+        booleanParam(name: 'SERVICE_GATEWAY_OVERSEAS', defaultValue: false, description: '海外 Gateway 网关服务（gateway-overseas）')
         booleanParam(name: 'SERVICE_AUTH', defaultValue: false, description: '统一认证服务（auth）')
         booleanParam(name: 'SERVICE_IAM', defaultValue: false, description: '租户与权限服务（iam）')
         booleanParam(name: 'SERVICE_FIRSTLEG', defaultValue: false, description: '头程履约服务（firstleg）')
@@ -56,19 +127,22 @@ pipeline {
         booleanParam(name: 'SERVICE_FILE', defaultValue: false, description: '文件中心（file）')
         booleanParam(name: 'SERVICE_PRINT', defaultValue: false, description: '打印服务（print）')
         booleanParam(name: 'SERVICE_INTEGRATION', defaultValue: false, description: '第三方集成服务（integration-service）')
-        booleanParam(name: 'SERVICE_EVENT_BRIDGE', defaultValue: false, description: '跨区域事件桥（event-bridge-service）')
+        booleanParam(name: 'SERVICE_LASTLEG', defaultValue: false, description: '海外尾程与入仓服务（lastleg-service）')
+        booleanParam(name: 'SERVICE_WAREHOUSE_OVERSEAS', defaultValue: false, description: '海外仓资源服务（warehouse-overseas-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）')
         choice(name: 'ENVIRONMENT', choices: environmentChoicesForJob(env.JOB_BASE_NAME), description: '部署环境')
         booleanParam(name: 'DEPLOY', defaultValue: false, description: '各服务构建成功后是否独立部署')
-        booleanParam(name: 'INITIALIZE_TEST_DATABASE', defaultValue: false, description: '仅 test：调度服务前幂等初始化测试数据库')
         booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试；生产构建不建议勾选')
         string(name: 'IMAGE_REPOSITORY', defaultValue: '172.31.198.7:10082/java-project/baiyue-firstleg', description: '内网共享镜像仓库地址')
-        string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'docker.m.daocloud.io/library/eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
-        string(name: 'DOWNSTREAM_JOB_PREFIX', defaultValue: 'baiyue-firstleg-', description: '单服务 Jenkins Job 名称前缀，例如 baiyue-firstleg-auth')
+        string(name: 'DOCKER_BASE_IMAGE', defaultValue: '172.31.198.7:10082/java-project/eclipse-temurin:17-jre-alpine', description: '内网 Java 17 基础镜像')
+        string(name: 'DOWNSTREAM_JOB_PREFIX', defaultValue: downstreamJobPrefixForJob(env.JOB_BASE_NAME), description: '单服务 Jenkins Job 名称前缀；开发总控自动使用 dev 专属 Job')
     }
 
     stages {
         stage('确定构建范围') {
+            agent { label 'java-builder' }
             steps {
                 script {
                     // 开发环境总控 Job 固定部署到 development，避免首次构建沿用 ENVIRONMENT 的默认 test 值。
@@ -79,19 +153,14 @@ pipeline {
                     env.RESOLVED_ENVIRONMENT = resolvedEnvironment
                     echo "Job ${env.JOB_BASE_NAME} 使用部署环境: ${env.RESOLVED_ENVIRONMENT}"
 
-                    String requestedRepository
-                    if (['development', 'test'].contains(env.RESOLVED_ENVIRONMENT)) {
-                        requestedRepository = "baiyue-firstleg-${env.RESOLVED_ENVIRONMENT}"
-                        echo "${env.RESOLVED_ENVIRONMENT} 环境使用本地镜像，由构建节点直接传输到部署目标"
-                    } else {
-                        requestedRepository = params.IMAGE_REPOSITORY?.trim()
-                        if (!requestedRepository || requestedRepository == 'registry.example.com/your-group/baiyue-firstleg') {
-                            error('预发布/生产环境必须填写真实镜像仓库地址')
-                        }
-                        if (requestedRepository.contains('://') || !requestedRepository.contains('/')) {
-                            error('IMAGE_REPOSITORY 格式错误：请填写 host[:port]/owner/image，不要包含 http:// 或 https://')
-                        }
+                    String requestedRepository = params.IMAGE_REPOSITORY?.trim()
+                    if (!requestedRepository || requestedRepository == 'registry.example.com/your-group/baiyue-firstleg') {
+                        error('必须填写真实镜像仓库地址')
                     }
+                    if (requestedRepository.contains('://') || !requestedRepository.contains('/')) {
+                        error('IMAGE_REPOSITORY 格式错误：请填写 host[:port]/owner/image，不要包含 http:// 或 https://')
+                    }
+                    echo "${env.RESOLVED_ENVIRONMENT} 环境使用共享镜像仓库: ${requestedRepository}"
                     env.RESOLVED_IMAGE_REPOSITORY = requestedRepository
 
                     String jobPrefix = params.DOWNSTREAM_JOB_PREFIX?.trim()
@@ -100,7 +169,12 @@ pipeline {
                     }
                     env.RESOLVED_JOB_PREFIX = jobPrefix
                     env.DATABASE_CHANGE_DETECTED = 'false'
+                    if (env.RESOLVED_ENVIRONMENT == 'production' && params.SKIP_TESTS) {
+                        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
@@ -112,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 }
@@ -122,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(',') ?: '无'}"
                         }
                     }
 
@@ -138,17 +234,32 @@ pipeline {
                     }
 
                     selected = selected.unique()
+                    if (params.DEPLOY && selected.contains('event-bridge-service')) {
+                        String bridgeRegion = params.EVENT_BRIDGE_REGION?.trim()
+                        if (!['BOTH', 'SELECT', 'CN', 'OVERSEAS'].contains(bridgeRegion)) {
+                            error('EVENT_BRIDGE_REGION 只能为 BOTH、CN 或 OVERSEAS')
+                        }
+                        if (['BOTH', 'SELECT'].contains(bridgeRegion) &&
+                            !['development', 'test'].contains(env.RESOLVED_ENVIRONMENT)) {
+                            error('事件桥 BOTH 仅支持开发或测试环境；预发布和生产必须明确选择 CN 或 OVERSEAS')
+                        }
+                        if (bridgeRegion == 'SELECT') {
+                            echo '兼容旧 Jenkins 参数 SELECT：本次按 BOTH 同时部署国内和海外事件桥'
+                        }
+                    }
                     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') {
@@ -169,14 +280,30 @@ pipeline {
             }
         }
 
-        stage('测试数据库初始化（可选）') {
+        stage('统一 Maven 测试门禁') {
             when {
-                allOf {
-                    expression { env.RESOLVED_ENVIRONMENT == 'test' && params.INITIALIZE_TEST_DATABASE }
+                expression { env.NO_SERVICE_CHANGE != 'true' && !params.SKIP_TESTS }
+            }
+            agent { label 'java-builder' }
+            tools { maven 'maven-3.8.8' }
+            steps {
+                script {
+                    String selectedModules = env.SELECTED_SERVICES.split(',')
+                        .collect { it.trim() }
+                        .findAll { it }
+                        .join(',')
+                    echo "统一测试本次选中的服务及其公共依赖: ${selectedModules}"
+                    sh """
+                        test \"\$(git rev-parse HEAD)\" = \"${env.SOURCE_COMMIT}\"
+                        mvn --settings deploy/maven/settings-ci.xml --batch-mode --errors -pl ${selectedModules} -am test
+                    """
+                    echo "统一测试门禁通过: ${env.SOURCE_COMMIT}；下游单服务任务不再重复执行测试"
                 }
             }
-            steps {
-                sh 'sh deploy/scripts/initialize-test-databases.sh'
+            post {
+                always {
+                    junit allowEmptyResults: true, testResults: '**/target/surefire-reports/TEST-*.xml'
+                }
             }
         }
 
@@ -189,6 +316,14 @@ pipeline {
                         String service = selectedService
                         branches[service] = {
                             String jobName = "${env.RESOLVED_JOB_PREFIX}${service}"
+                            boolean deployBothBridges = service == 'event-bridge-service' &&
+                                ['BOTH', 'SELECT'].contains(params.EVENT_BRIDGE_REGION)
+                            String downstreamImageTag = deployBothBridges
+                                ? "${env.IMAGE_TAG}-both"
+                                : env.IMAGE_TAG
+                            String downstreamBridgeRegion = deployBothBridges
+                                ? 'CN'
+                                : (service == 'event-bridge-service' ? params.EVENT_BRIDGE_REGION : 'CN')
                             echo "触发单服务 Job: ${jobName}"
                             def downstreamBuild = build(
                                 job: jobName,
@@ -196,12 +331,16 @@ pipeline {
                                 propagate: false,
                                 parameters: [
                                     string(name: 'SOURCE_COMMIT', value: env.SOURCE_COMMIT),
-                                    string(name: 'IMAGE_TAG', value: env.IMAGE_TAG),
+                                    string(name: 'IMAGE_TAG', value: downstreamImageTag),
                                     string(name: 'ENVIRONMENT', value: env.RESOLVED_ENVIRONMENT),
                                     booleanParam(name: 'DEPLOY', value: params.DEPLOY),
-                                    booleanParam(name: 'SKIP_TESTS', value: params.SKIP_TESTS),
+                                    // 总控已完成统一测试，或用户已明确选择跳过；下游仅负责编译、打包和部署。
+                                    booleanParam(name: 'SKIP_TESTS', value: true),
                                     string(name: 'IMAGE_REPOSITORY', value: env.RESOLVED_IMAGE_REPOSITORY),
-                                    string(name: 'DOCKER_BASE_IMAGE', value: params.DOCKER_BASE_IMAGE)
+                                    string(name: 'DOCKER_BASE_IMAGE', value: params.DOCKER_BASE_IMAGE),
+                                    // Choice 参数始终传递所有新旧 Job 都接受的单区值；
+                                    // 双区意图通过现有 IMAGE_TAG 参数携带，由下游还原真实镜像标签。
+                                    string(name: 'EVENT_BRIDGE_REGION', value: downstreamBridgeRegion)
                                 ]
                             )
                             downstreamResults[service] = downstreamBuild.result ?: 'UNKNOWN'
@@ -221,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(', ')}")
                     }
@@ -230,7 +371,4 @@ pipeline {
         }
     }
 
-    post {
-        always { cleanWs(deleteDirs: true, notFailBuild: true) }
-    }
 }

Jenkinsfile.service

@@ -1,10 +1,11 @@
 def serviceModules = [
-    'gateway', 'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
-    'integration-service', 'event-bridge-service', 'audit-service'
+    'gateway', 'gateway-overseas', 'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
+    'integration-service', 'lastleg-service', 'warehouse-overseas-service', 'event-bridge-service', 'audit-service'
 ]
 
 def serviceJars = [
     'gateway': 'gateway/target/gateway-1.0.0-SNAPSHOT.jar',
+    'gateway-overseas': 'gateway-overseas/target/gateway-overseas-1.0.0-SNAPSHOT.jar',
     'auth': 'auth/target/auth-service-1.0.0-SNAPSHOT.jar',
     'iam': 'iam/target/iam-service-1.0.0-SNAPSHOT.jar',
     'firstleg': 'firstleg/target/firstleg-service-1.0.0-SNAPSHOT.jar',
@@ -14,6 +15,8 @@ def serviceJars = [
     'file': 'file/target/file-service-1.0.0-SNAPSHOT.jar',
     'print': 'print/target/print-service-1.0.0-SNAPSHOT.jar',
     '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',
     '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'
 ]
@@ -35,17 +38,15 @@ pipeline {
         choice(name: 'ENVIRONMENT', choices: ['test', 'development', 'staging', 'production'], description: '部署环境')
         booleanParam(name: 'DEPLOY', defaultValue: false, description: '构建成功后是否部署本服务')
         booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试')
+        choice(name: 'EVENT_BRIDGE_REGION', choices: ['BOTH', 'CN', 'OVERSEAS', 'SELECT'], description: '仅 event-bridge-service 使用；BOTH 在开发/测试环境同时部署国内和海外实例；SELECT 为总控兼容值')
         string(name: 'IMAGE_REPOSITORY', defaultValue: '172.31.198.7:10082/java-project/baiyue-firstleg', description: '内网共享镜像仓库基础路径，不包含服务名和标签')
-        string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'docker.m.daocloud.io/library/eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
+        string(name: 'DOCKER_BASE_IMAGE', defaultValue: '172.31.198.7:10082/java-project/eclipse-temurin:17-jre-alpine', description: '内网 Java 17 基础镜像')
     }
 
     environment {
-        REGISTRY_CREDENTIALS = 'gitea-test-token'
+        REGISTRY_CREDENTIALS = 'gitea-registry-token'
         MAVEN_SETTINGS = 'deploy/maven/settings-ci.xml'
         MAVEN_OPTS = '-Dfile.encoding=UTF-8 -Dmaven.wagon.http.retryHandler.count=3'
-        DEVELOPMENT_SSH_TARGET = 'deploy@172.31.198.8'
-        DEVELOPMENT_SSH_KEY = '/var/jenkins_home/.ssh/dev_deploy'
-        DEVELOPMENT_DEPLOY_DIR = '/opt/firstleg/application'
     }
 
     stages {
@@ -63,9 +64,7 @@ pipeline {
                             }
                             String sourceCommit = params.SOURCE_COMMIT?.trim()
                             String imageTag = params.IMAGE_TAG?.trim()
-                            String imageRepository = ['development', 'test'].contains(params.ENVIRONMENT)
-                                ? "baiyue-firstleg-${params.ENVIRONMENT}"
-                                : params.IMAGE_REPOSITORY?.trim()
+                            String imageRepository = params.IMAGE_REPOSITORY?.trim()
 
                             if (!sourceCommit) {
                                 sourceCommit = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
@@ -77,6 +76,11 @@ pipeline {
                             if (!serviceModules.contains(service)) {
                                 error("无法从 Job 名称 ${env.JOB_BASE_NAME} 识别服务；名称必须以以下服务之一结尾: ${serviceModules.join(', ')}")
                             }
+                            boolean deployBothBridges = service == 'event-bridge-service' &&
+                                imageTag?.endsWith('-both')
+                            if (deployBothBridges) {
+                                imageTag = imageTag.substring(0, imageTag.length() - '-both'.length())
+                            }
                             if (!sourceCommit || !(sourceCommit ==~ /(?i)[0-9a-f]{7,40}/)) {
                                 error('SOURCE_COMMIT 必须是 7 到 40 位十六进制 Git commit')
                             }
@@ -86,14 +90,26 @@ pipeline {
                             if (!imageRepository || imageRepository.contains('://')) {
                                 error('IMAGE_REPOSITORY 不能为空且不能包含协议前缀')
                             }
-                            if (!['development', 'test'].contains(params.ENVIRONMENT) && !imageRepository.contains('/')) {
-                                error('预发布/生产环境 IMAGE_REPOSITORY 必须使用 host[:port]/owner/image 格式')
+                            if (!imageRepository.contains('/')) {
+                                error('IMAGE_REPOSITORY 必须使用 host[:port]/owner/image 格式')
                             }
 
                             env.RESOLVED_SERVICE = service
                             env.RESOLVED_SOURCE_COMMIT = sourceCommit
                             env.RESOLVED_IMAGE_TAG = imageTag
                             env.RESOLVED_IMAGE_REPOSITORY = imageRepository
+                            env.DEPLOY_BOTH_EVENT_BRIDGES = deployBothBridges ? 'true' : 'false'
+
+                            if (service == 'event-bridge-service' && params.DEPLOY) {
+                                String bridgeRegion = params.EVENT_BRIDGE_REGION?.trim()
+                                if (!['BOTH', 'SELECT', 'CN', 'OVERSEAS'].contains(bridgeRegion)) {
+                                    error('EVENT_BRIDGE_REGION 只能为 BOTH、CN 或 OVERSEAS')
+                                }
+                                if ((deployBothBridges || ['BOTH', 'SELECT'].contains(bridgeRegion)) &&
+                                    !['development', 'test'].contains(params.ENVIRONMENT)) {
+                                    error('事件桥 BOTH 仅支持开发或测试环境；预发布和生产必须明确选择 CN 或 OVERSEAS')
+                                }
+                            }
                         }
 
                         sh '''
@@ -115,12 +131,15 @@ pipeline {
                 stage('Maven 测试与打包') {
                     steps {
                         script {
-                            if (params.ENVIRONMENT == 'production' && params.SKIP_TESTS) {
-                                error('生产环境禁止跳过测试')
+                            boolean coordinatorPinnedCommit = params.SOURCE_COMMIT?.trim() as boolean
+                            if (params.ENVIRONMENT == 'production' && params.SKIP_TESTS && !coordinatorPinnedCommit) {
+                                error('生产环境手工构建禁止跳过测试；总控流水线可在统一测试通过后执行快速打包')
                             }
                             boolean skipTestExecution = params.ENVIRONMENT == 'test' || params.SKIP_TESTS
                             String testOption = skipTestExecution ? '-DskipTests' : ''
-                            if (params.ENVIRONMENT == 'test') {
+                            if (params.SKIP_TESTS && coordinatorPinnedCommit) {
+                                echo "总控已处理提交 ${env.RESOLVED_SOURCE_COMMIT} 的测试门禁，本单服务仅编译测试源码并打包"
+                            } else if (params.ENVIRONMENT == 'test') {
                                 echo '测试环境快速部署：编译主代码和测试代码，但不重复执行单元测试；完整测试由提交门禁和预发布执行'
                             }
                             sh "mvn --settings ${env.MAVEN_SETTINGS} --batch-mode --errors -pl ${env.RESOLVED_SERVICE} -am clean package ${testOption}"
@@ -140,69 +159,81 @@ pipeline {
                             String contextDir = ".docker-context/${env.RESOLVED_SERVICE}"
                             String jar = serviceJars[env.RESOLVED_SERVICE]
                             String registryHost = env.RESOLVED_IMAGE_REPOSITORY.tokenize('/')[0]
+                            String dockerConfigDir = "${pwd(tmp: true)}/docker-auth"
                             sh "mkdir -p '${contextDir}' && cp -f '${jar}' '${contextDir}/app.jar'"
-                            sh "docker build -f deploy/docker/Dockerfile --build-arg BASE_IMAGE=${params.DOCKER_BASE_IMAGE} --build-arg JAR_FILE=app.jar -t ${image} '${contextDir}'"
 
-                            if (['development', 'test'].contains(params.ENVIRONMENT)) {
-                                echo "${params.ENVIRONMENT} 镜像已保存在构建节点 ${env.NODE_NAME}: ${image}"
-                            } else {
-                                echo "推送共享镜像: ${image}"
+                            echo "推送共享镜像: ${image}"
+                            withEnv(["DOCKER_CONFIG=${dockerConfigDir}"]) {
+                                sh 'mkdir -p "$DOCKER_CONFIG"'
                                 withCredentials([usernamePassword(credentialsId: env.REGISTRY_CREDENTIALS, usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD')]) {
                                     try {
                                         sh 'printf %s "$REGISTRY_PASSWORD" | docker login -u "$REGISTRY_USER" --password-stdin "' + registryHost + '"'
+                                        sh "docker build -f deploy/docker/Dockerfile --build-arg BASE_IMAGE=${params.DOCKER_BASE_IMAGE} --build-arg JAR_FILE=app.jar -t ${image} '${contextDir}'"
                                         sh "docker push ${image}"
                                     } finally {
                                         sh "docker logout ${registryHost} || true"
+                                        sh 'rm -rf "$DOCKER_CONFIG"'
                                     }
                                 }
-                                if (params.DEPLOY) {
-                                    stash name: 'deployment-files', includes: 'deploy/**', useDefaultExcludes: true
-                                }
                             }
-                        }
-                    }
-                }
-
-                stage('直接部署开发或测试环境') {
-                    when {
-                        expression { params.DEPLOY && ['development', 'test'].contains(params.ENVIRONMENT) }
-                    }
-                    steps {
-                        script {
-                            boolean development = params.ENVIRONMENT == 'development'
-                            boolean targetIsLocal = development
-                                ? env.NODE_LABELS?.tokenize()?.contains('java-dev')
-                                : env.NODE_NAME == 'master'
-                            String credentialId = "firstleg-${params.ENVIRONMENT}-env"
-                            String remoteTarget = development ? 'deploy@172.31.198.8' : 'deploy@172.31.198.7'
-                            String remoteKey = development
-                                ? '/var/jenkins_home/.ssh/dev_deploy'
-                                : '/home/deploy/.ssh/test_deploy'
-                            String remoteKnownHosts = development
-                                ? '/var/jenkins_home/.ssh/known_hosts'
-                                : '/home/deploy/.ssh/known_hosts'
-                            String remoteDir = development
-                                ? '/opt/firstleg/application'
-                                : '/opt/firstleg/test-application'
-
-                            withEnv([
-                                "TARGET_IS_LOCAL=${targetIsLocal}",
-                                "TARGET_SSH_TARGET=${remoteTarget}",
-                                "TARGET_SSH_KEY=${remoteKey}",
-                                "TARGET_SSH_KNOWN_HOSTS=${remoteKnownHosts}",
-                                "TARGET_DEPLOY_DIR=${remoteDir}"
-                            ]) {
-                                withCredentials([file(credentialsId: credentialId, variable: 'DEPLOY_ENV_FILE')]) {
-                                    sh "sh deploy/scripts/deploy-built-service.sh '${params.ENVIRONMENT}' '${env.RESOLVED_IMAGE_REPOSITORY}' '${env.RESOLVED_IMAGE_TAG}' '${env.RESOLVED_SERVICE}' \"\$DEPLOY_ENV_FILE\""
-                                }
+                            if (params.DEPLOY) {
+                                stash name: 'deployment-files', includes: 'deploy/**', useDefaultExcludes: true
                             }
                         }
                     }
                 }
             }
-            post {
-                always {
-                    cleanWs(deleteDirs: true, notFailBuild: true)
+        }
+
+        stage('部署开发或测试环境') {
+            when {
+                beforeAgent true
+                expression { params.DEPLOY && ['development', 'test'].contains(params.ENVIRONMENT) }
+            }
+            agent none
+            steps {
+                script {
+                    String deploySlotLabel = "firstleg-${params.ENVIRONMENT}-deploy-slot"
+                    String serviceDeployResource = "firstleg-${params.ENVIRONMENT}-${env.RESOLVED_SERVICE}-deploy"
+                    String credentialId = "firstleg-${params.ENVIRONMENT}-env"
+                    String targetLabel = params.ENVIRONMENT == 'development' ? 'java-dev' : 'java-test'
+                    // 不同服务可以并行，但同一环境的同一服务只能有一个任务更新容器。
+                    // resource 未预配置时 Lockable Resources 会创建仅在构建期间存在的临时资源。
+                    lock(resource: serviceDeployResource, inversePrecedence: true) {
+                        lock(label: deploySlotLabel, quantity: 1, inversePrecedence: true) {
+                            node(targetLabel) {
+                                deleteDir()
+                                try {
+                                    unstash 'deployment-files'
+                                    echo "在目标节点 ${env.NODE_NAME} 本机部署到 ${params.ENVIRONMENT}"
+                                    List bridgeRegions = (env.RESOLVED_SERVICE == 'event-bridge-service' &&
+                                        (env.DEPLOY_BOTH_EVENT_BRIDGES == 'true' ||
+                                            ['BOTH', 'SELECT'].contains(params.EVENT_BRIDGE_REGION)))
+                                        ? ['CN', 'OVERSEAS']
+                                        : [params.EVENT_BRIDGE_REGION]
+                                    withCredentials([
+                                        file(credentialsId: credentialId, variable: 'DEPLOY_ENV_FILE'),
+                                        usernamePassword(credentialsId: env.REGISTRY_CREDENTIALS,
+                                            usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD')
+                                    ]) {
+                                        bridgeRegions.each { bridgeRegion ->
+                                            if (env.RESOLVED_SERVICE == 'event-bridge-service') {
+                                                echo "部署事件桥实例: ${bridgeRegion}"
+                                            }
+                                            withEnv([
+                                                'TARGET_IS_LOCAL=true',
+                                                "EVENT_BRIDGE_REGION_OVERRIDE=${bridgeRegion}"
+                                            ]) {
+                                                sh "sh deploy/scripts/deploy-built-service.sh '${params.ENVIRONMENT}' '${env.RESOLVED_IMAGE_REPOSITORY}' '${env.RESOLVED_IMAGE_TAG}' '${env.RESOLVED_SERVICE}' \"\$DEPLOY_ENV_FILE\""
+                                            }
+                                        }
+                                    }
+                                } finally {
+                                    cleanWs(deleteDirs: true, notFailBuild: true)
+                                }
+                            }
+                        }
+                    }
                 }
             }
         }
@@ -227,7 +258,10 @@ pipeline {
                     withCredentials([usernamePassword(credentialsId: env.REGISTRY_CREDENTIALS, usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD')]) {
                         try {
                             sh 'printf %s "$REGISTRY_PASSWORD" | docker login -u "$REGISTRY_USER" --password-stdin "' + registryHost + '"'
-                            withEnv(["DEVELOPMENT_DEPLOY_LOCAL=${localDevelopmentDeploy}"]) {
+                            withEnv([
+                                "DEVELOPMENT_DEPLOY_LOCAL=${localDevelopmentDeploy}",
+                                "EVENT_BRIDGE_REGION_OVERRIDE=${params.EVENT_BRIDGE_REGION}"
+                            ]) {
                                 withCredentials([file(credentialsId: credentialId, variable: 'DEPLOY_ENV_FILE')]) {
                                     sh "sh deploy/scripts/deploy-services.sh '${params.ENVIRONMENT}' '${env.RESOLVED_IMAGE_REPOSITORY}' '${env.RESOLVED_IMAGE_TAG}' '${env.RESOLVED_SERVICE}' \"\$DEPLOY_ENV_FILE\""
                                 }

README.md

@@ -1,6 +1,6 @@
 # 柏悦头程平台
 
-本仓库承载国内头程业务，负责统一登录、客户与企业成员、角色、菜单、按钮权限、订单、国内仓储、头程履约以及国内公共能力。尾程业务不进入本仓库，通过版本化跨区域事件与尾程仓库协作。
+本仓库承载国内头程与海外仓后端，包含统一认证、国内订单与履约、国内外仓储资源、海外尾程与入仓业务，以及跨区域事件桥和公共能力。国内、海外仍保持独立数据库、Nacos 命名空间与部署边界，通过版本化跨区域事件协作。
 
 > 当前主体模型：业务单租户，产品只包含“平台—客户”两级。现有 `tenant_id > 0`、`tenantId` 和 `Tenant*` 是历史兼容命名，当前承载客户归属与隔离；`tenant_id = 0` 是平台账号、平台 RBAC 和平台公共主数据的技术作用域，不是可管理租户。平台公共仓库、往来单位、快递公司、托盘、库位等归属 `0`，客户订单、文件和费用归属客户 ID。未经过独立迁移设计，不得新增真实租户层或把现有客户隔离字段改义为上级租户。
 
@@ -12,20 +12,24 @@
 - `firstleg`：头程揽收、入仓、装载、发运和交接。
 - `warehouse`：国内仓储能力。
 - `file`、`print`、`audit-service`、`integration-service`：国内公共业务能力；Print 调用方接入见 `print/README.md`。
-- `event-bridge-service`：跨区域事件接收幂等和投递记录基础骨架；真实跨区发送、重试调度和死信补投仍需完成。
+- `gateway-overseas`、`lastleg-service`、`warehouse-overseas-service`：海外公网入口、海外尾程/入仓与 IAM 安全投影、海外仓储资源。
+- `event-bridge-service`：按国内、海外双实例部署的跨区域事件桥。
 - `common-*`、`common-event-contract`：由本仓维护并以 `com.baiyue.shared` 发布的公共制品。
-- `platform-bom`：发布 `com.baiyue.shared:baiyue-platform-bom:1.0.0-SNAPSHOT`，尾程仓只通过固定版本引用。
+- `platform-bom`：统一管理仓库内公共依赖版本。
 
 ## 本地构建
 
 ```powershell
 mvn -DskipTests validate
+node --test scripts/java-topology-contract.test.mjs
 mvn test
 ```
 
+GitLab 在独立 Node 镜像中自动执行拓扑合同，随后才允许服务制品打包。Maven `verify` 会为执行过测试且产生覆盖率数据的模块生成 `target/site/jacoco/index.html` 与 `jacoco.xml`；当前只生成报告，不设置覆盖率阈值，也不改变测试选择。Jenkins 的 `java-builder` 尚未在仓库中声明 Node 运行时，因此暂不重复执行该 Node 合同，以 GitLab 门禁和上述本地命令为准。
+
 2026-07-30 一期前端联调缺口已完成真实回归：19 个 Reactor 项目构建成功，75 项单元及组件测试、68 项认证与 IAM 真实 API、37 项订单与仓库真实 API 全部通过。详细证据见 `docs/phase1-business-maturity-regression-report.md`。
 
-本地一期完整联调启动顺序为：IAM、Auth、Firstleg、Order、Warehouse、File、Print，最后启动 Gateway。往来单位不是独立服务，由 `warehouse-service` 承载并保存到 `baiyue_warehouse.wh_partner`。
+国内本地联调启动顺序为：IAM、Auth、Firstleg、Order、Warehouse、File、Print，最后启动 Gateway。往来单位不是独立服务，由 `warehouse-service` 承载并保存到 `baiyue_warehouse.wh_partner`。海外服务通过独立 Compose 与 Nacos 配置启动，不与国内服务共享数据库或配置命名空间。
 
 国内 Nacos 配置位于 `config/nacos/cn`。数据库、Redis、Nacos 和 RocketMQ 的生产密码必须通过环境变量或配置中心密文注入，禁止提交明文密码。
 
@@ -41,4 +45,4 @@ CORS_ALLOWED_ORIGINS=https://merchant.example.com,https://admin.example.com
 
 ## 仓库边界
 
-仓库边界、服务调用和拆分规则见 `docs/头程项目目录结构与服务说明.md` 的“项目定位”“主要调用关系”和“开发和拆分约束”。本仓不得引入尾程源码，不允许跨区域共享数据库、Redis 或 Nacos，也不允许通过公网直接调用对方内部服务。
+仓库边界、服务调用和拆分规则见 `docs/头程项目目录结构与服务说明.md` 的“项目定位”“主要调用关系”和“开发和拆分约束”。国内与海外服务不允许跨区域共享数据库、Redis 或 Nacos，也不允许通过公网直接调用对方内部服务。

auth/AGENTS.md

@@ -15,7 +15,8 @@
 | 内部账号管理与 scope | `controller/InternalAccountController.java`、`service/AccountManagementService.java` |
 | 统一 JWT 签发与 JWKS | `config/AuthSecurityConfig.java`、`config/AuthSecurityProperties.java`、`service/AuthService.java`；Auth 是国内与海外仓共用的唯一用户 Token 签发方，JWKS 公钥发布按认证接口契约实现 |
 | 国内小 JWT 与会话 | `service/AuthService.java`、`service/TokenSessionStore.java`；浏览器登录 Token 只承载稳定身份、应用域和版本声明，国内服务结合 Redis 会话校验 |
-| 海外访问 Token 签发 | 登录/刷新编排使用同一用户身份同时签发短时 RS256 海外 Token，限定海外 Audience 并携带海外 API 所需权限快照；前端统一认证层负责按区域 API 自动选择 |
+| 海外访问 Token 签发 | `service/OverseasTokenService.java`；登录/刷新编排使用同一用户身份同时签发短时 RS256 海外 Token，限定海外 Audience，只保留平台海外仓/海外业务/海外主数据及 `lastleg:*` 权限前缀；前端统一认证层负责按区域 API 自动选择 |
+| 海外 PDA 实时会话校验 | `controller/InternalAccountController.java`、`service/OverseasSessionValidationService.java`；只接受海外 Gateway 已验签后提取的 userId/tokenVersion/overseasWarehouseId，以内部服务令牌保护并实时联查 IAM 当前仓绑定 |
 | Token 会话与权限快照 | `service/TokenSessionStore.java`、`client/AuthorizationLoader.java`、`client/IamAuthorizationClient.java`；消费端映射见 `../common-security/src/main/java/com/baiyue/common/security/RedisAccessTokenSessionValidator.java`、`JwtClaimsMapper.java` |
 | 注册协作 | `service/MerchantRegistrationService.java` |
 | IAM 授权客户端 | `client/IamAuthorizationClient.java`、`client/IamOnboardingClient.java` |

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

@@ -21,4 +21,12 @@ public class AuthorizationSnapshot {
     private Set<String> roles;
     private Set<String> permissions;
     private Long permissionVersion;
+    private Long overseasWarehouseId;
+
+    public AuthorizationSnapshot(Long userId, Long tenantId, Long membershipId, String appCode,
+                                 String clientType, Set<String> roles, Set<String> permissions,
+                                 Long permissionVersion) {
+        this(userId, tenantId, membershipId, appCode, clientType, roles, permissions,
+            permissionVersion, null);
+    }
 }

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/controller/InternalAccountController.java

@@ -3,12 +3,16 @@ package com.baiyue.auth.controller;
 import com.baiyue.auth.dto.AccountManagementDtos.*;
 import com.baiyue.auth.service.AccountManagementService;
 import com.baiyue.auth.service.AuthService;
+import com.baiyue.auth.service.OverseasSessionValidationService;
+import com.baiyue.auth.dto.OverseasSessionValidationDtos;
 import com.baiyue.common.core.api.ApiResponse;
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import jakarta.annotation.PostConstruct;
 import jakarta.annotation.Resource;
 import jakarta.validation.Valid;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.web.bind.annotation.*;
 
@@ -18,11 +22,14 @@ import java.security.MessageDigest;
 /** 仅供可信内部服务调用的账号管理接口。 */
 @RestController
 @RequestMapping("/internal/auth/accounts")
+@Tag(name = "Internal Auth / 内部认证", description = "Service-token protected internal account and overseas PDA session APIs")
 public class InternalAccountController {
     @Resource
     private AccountManagementService service;
     @Resource
     private AuthService authService;
+    @Resource
+    private OverseasSessionValidationService overseasSessionValidationService;
 
     @Value("${baiyue.security.internal-service-token}")
     private String configuredToken;
@@ -64,6 +71,15 @@ public class InternalAccountController {
             @Valid @RequestBody RevokeAccountSessionsRequest request) {
         verify(token); service.revokeSessions(request.accountIds()); return ApiResponse.success(null);
     }
+    @PostMapping("/overseas-session/validate")
+    @Operation(summary = "Validate verified overseas PDA claims / 校验已验签的海外PDA声明",
+            description = "Accepts only claims extracted after Gateway JWT verification; raw tokens and user credentials are forbidden.")
+    public ApiResponse<OverseasSessionValidationDtos.Response> validateOverseasSession(
+            @RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+            @Valid @RequestBody OverseasSessionValidationDtos.Request request) {
+        verify(token);
+        return ApiResponse.success(overseasSessionValidationService.validate(request));
+    }
     @PutMapping("/{id}/profile")
     public ApiResponse<Void> profile(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,
                                      @PathVariable Long id, @Valid @RequestBody UpdateAccountProfileRequest request) {

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/dto/OverseasSessionValidationDtos.java

@@ -0,0 +1,29 @@
+package com.baiyue.auth.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
+
+/** 海外 PDA 已验签身份的实时会话校验契约；绝不接收 raw JWT 或用户凭据。 */
+public final class OverseasSessionValidationDtos {
+    private OverseasSessionValidationDtos() { }
+
+    @Schema(name = "OverseasSessionValidationRequest",
+            description = "Claims extracted only after overseas Gateway verifies the JWT signature")
+    public record Request(
+            @NotNull Long userId,
+            @NotNull Integer tokenVersion,
+            Long overseasWarehouseId) { }
+
+    @Schema(name = "OverseasSessionValidationResponse")
+    public record Response(boolean valid, FailureReason failureReason) {
+        public static Response accepted() { return new Response(true, null); }
+        public static Response rejected(FailureReason reason) { return new Response(false, reason); }
+    }
+
+    public enum FailureReason {
+        ACCOUNT_INVALID,
+        TOKEN_VERSION_MISMATCH,
+        WAREHOUSE_UNBOUND,
+        WAREHOUSE_MISMATCH
+    }
+}

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

@@ -111,12 +111,13 @@ public class AuthService {
         Instant issuedAt = Instant.now();
         String jwtId = UUID.randomUUID().toString();
         Instant expiresAt = issuedAt.plus(properties.accessTokenTtl());
-        JwtClaimsSet claims = JwtClaimsSet.builder()
+        JwtClaimsSet.Builder claimsBuilder = 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("display_name", account.getDisplayName() == null ? "" : account.getDisplayName())
             .claim("tenant_id", account.getDefaultTenantId())
             .claim("operator_tenant_id", account.getOperatorTenantId())
             .claim("membership_id", account.getDefaultMembershipId())
@@ -127,8 +128,11 @@ public class AuthService {
             .claim("userId", account.getId())
             .claim("tenantId", account.getDefaultTenantId())
             .claim("appCode", account.getDefaultAppCode())
-            .claim("permissionVersion", account.getTokenVersion())
-            .build();
+            .claim("permissionVersion", account.getTokenVersion());
+        if (authorization.getOverseasWarehouseId() != null) {
+            claimsBuilder.claim("overseas_warehouse_id", authorization.getOverseasWarehouseId());
+        }
+        JwtClaimsSet claims = claimsBuilder.build();
         String accessToken = jwtEncoder.encode(JwtEncoderParameters.from(
             signingHeader(), claims)).getTokenValue();
 
@@ -184,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/java/com/baiyue/auth/service/OverseasSessionValidationService.java

@@ -0,0 +1,38 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.AuthorizationLoader;
+import com.baiyue.auth.dto.OverseasSessionValidationDtos.FailureReason;
+import com.baiyue.auth.dto.OverseasSessionValidationDtos.Request;
+import com.baiyue.auth.dto.OverseasSessionValidationDtos.Response;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import jakarta.annotation.Resource;
+import org.springframework.stereotype.Service;
+
+import java.util.Objects;
+
+/** 实时核对海外 PDA token 的账号版本与当前 IAM 仓绑定。 */
+@Service
+public class OverseasSessionValidationService {
+    @Resource private AuthAccountRepository accounts;
+    @Resource private AuthorizationLoader authorizationLoader;
+
+    public Response validate(Request request) {
+        AuthAccount account = accounts.findById(request.userId());
+        if (account == null || !"ACTIVE".equals(account.getAccountStatus())) {
+            return Response.rejected(FailureReason.ACCOUNT_INVALID);
+        }
+        int currentVersion = account.getTokenVersion() == null ? 0 : account.getTokenVersion();
+        if (currentVersion != request.tokenVersion()) {
+            return Response.rejected(FailureReason.TOKEN_VERSION_MISMATCH);
+        }
+        Long currentWarehouseId = authorizationLoader.load(account).getOverseasWarehouseId();
+        if (currentWarehouseId == null || request.overseasWarehouseId() == null) {
+            return Response.rejected(FailureReason.WAREHOUSE_UNBOUND);
+        }
+        if (!Objects.equals(currentWarehouseId, request.overseasWarehouseId())) {
+            return Response.rejected(FailureReason.WAREHOUSE_MISMATCH);
+        }
+        return Response.accepted();
+    }
+}

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

@@ -19,12 +19,21 @@ import org.springframework.stereotype.Service;
 
 import java.time.Instant;
 import java.util.List;
+import java.util.Set;
 import java.util.UUID;
+import java.util.stream.Collectors;
 
 /** 将已经通过国内 HMAC 与 Redis 校验的会话兑换为海外 RS256 短时令牌。 */
 @Service
 @ConditionalOnProperty(name = "baiyue.security.overseas-jwt.enabled", havingValue = "true")
 public class OverseasTokenService {
+    private static final List<String> OVERSEAS_AUTHORITY_PREFIXES = List.of(
+        "platform:overseas-warehouse:",
+        "platform:overseas-business:",
+        "platform:overseas-master-data:",
+        "lastleg:"
+    );
+
     @Resource private AuthAccountRepository accounts;
     @Resource private AuthorizationLoader authorizationLoader;
     @Resource private OverseasJwtProperties properties;
@@ -42,21 +51,32 @@ public class OverseasTokenService {
     public OverseasTokenResponse issue(AuthAccount account, AuthorizationSnapshot authorization) {
         Instant issuedAt = Instant.now();
         Instant expiresAt = issuedAt.plus(properties.accessTokenTtl());
-        JwtClaimsSet claims = JwtClaimsSet.builder()
+        JwtClaimsSet.Builder claimsBuilder = JwtClaimsSet.builder()
             .issuer(properties.issuer()).audience(List.of(properties.audience()))
             .subject(account.getId().toString()).id(UUID.randomUUID().toString())
             .issuedAt(issuedAt).expiresAt(expiresAt)
-            .claim("user_id", account.getId()).claim("tenant_id", account.getDefaultTenantId())
+            .claim("user_id", account.getId()).claim("tenant_id", authorization.getTenantId())
             .claim("membership_id", authorization.getMembershipId())
-            .claim("app_code", account.getDefaultAppCode()).claim("client_type", authorization.getClientType())
+            .claim("app_code", authorization.getAppCode()).claim("client_type", authorization.getClientType())
             .claim("roles", authorization.getRoles())
-            .claim("authorities", authorization.getPermissions())
-            .claim("permission_version", authorization.getPermissionVersion() == null ? 0L : authorization.getPermissionVersion())
-            .build();
+            .claim("authorities", overseasAuthorities(authorization.getPermissions()))
+            .claim("token_version", account.getTokenVersion() == null ? 0 : account.getTokenVersion())
+            .claim("permission_version", authorization.getPermissionVersion() == null ? 0L : authorization.getPermissionVersion());
+        if (authorization.getOverseasWarehouseId() != null) {
+            claimsBuilder.claim("overseas_warehouse_id", authorization.getOverseasWarehouseId());
+        }
+        JwtClaimsSet claims = claimsBuilder.build();
         String token = encoder.encode(JwtEncoderParameters.from(
             JwsHeader.with(SignatureAlgorithm.RS256).keyId(properties.currentKid()).build(), claims)).getTokenValue();
         return new OverseasTokenResponse("Bearer", token, properties.accessTokenTtl().toSeconds());
     }
 
+    private Set<String> overseasAuthorities(Set<String> permissions) {
+        if (permissions == null || permissions.isEmpty()) return Set.of();
+        return permissions.stream()
+            .filter(permission -> permission != null && OVERSEAS_AUTHORITY_PREFIXES.stream().anyMatch(permission::startsWith))
+            .collect(Collectors.toUnmodifiableSet());
+    }
+
     public record OverseasTokenResponse(String tokenType, String accessToken, long expiresIn) { }
 }

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/controller/OverseasSessionValidationControllerContractTest.java

@@ -0,0 +1,28 @@
+package com.baiyue.auth.controller;
+
+import com.baiyue.auth.dto.OverseasSessionValidationDtos;
+import io.swagger.v3.oas.annotations.Operation;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.bind.annotation.PostMapping;
+
+import java.util.Arrays;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class OverseasSessionValidationControllerContractTest {
+    @Test
+    void internalEndpointAcceptsOnlyVerifiedClaimValuesAndIsDocumented() {
+        var method = Arrays.stream(InternalAccountController.class.getDeclaredMethods())
+                .filter(candidate -> candidate.getName().equals("validateOverseasSession"))
+                .findFirst().orElseThrow();
+
+        assertThat(method.getAnnotation(PostMapping.class).value())
+                .containsExactly("/overseas-session/validate");
+        assertThat(method.getAnnotation(Operation.class).description())
+                .contains("Gateway JWT verification", "raw tokens and user credentials are forbidden");
+        assertThat(OverseasSessionValidationDtos.Request.class.getRecordComponents())
+                .extracting(java.lang.reflect.RecordComponent::getName)
+                .containsExactly("userId", "tokenVersion", "overseasWarehouseId")
+                .doesNotContain("token", "accessToken", "authorization", "password");
+    }
+}

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/AuthServiceSmallJwtTest.java

@@ -23,7 +23,10 @@ import java.time.Duration;
 import java.util.Set;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
@@ -60,7 +63,7 @@ class AuthServiceSmallJwtTest {
         account.setDefaultAppCode("PLATFORM");
         account.setTokenVersion(1);
         AuthorizationSnapshot snapshot = new AuthorizationSnapshot(42L, 0L, 84L, "PLATFORM",
-                "WEB", Set.of("PLATFORM_ADMIN"), Set.of("platform:order:list"), 1L);
+                "WEB", Set.of("WAREHOUSE_PICKER"), Set.of("platform:order:list"), 1L, 900L);
         Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
 
         when(repository.findByUsername("operator")).thenReturn(account);
@@ -82,12 +85,13 @@ class AuthServiceSmallJwtTest {
                 .containsEntry("appCode", "PLATFORM")
                 .containsEntry("permissionVersion", 1)
                 .containsEntry("membership_id", 84L)
+                .containsEntry("overseas_warehouse_id", 900L)
                 .doesNotContainKeys("roles", "authorities", "permissions", "scope");
         assertThat(jwt.getValue().getClaims().getAudience()).containsExactly("lastleg-api");
         assertThat(jwt.getValue().getJwsHeader().getAlgorithm()).isEqualTo(MacAlgorithm.HS256);
         assertThat(jwt.getValue().getJwsHeader().getKeyId()).isNull();
         verify(tokenSessionStore).store(any(), org.mockito.ArgumentMatchers.eq(42L),
-                org.mockito.ArgumentMatchers.eq(Set.of("PLATFORM_ADMIN")),
+                org.mockito.ArgumentMatchers.eq(Set.of("WAREHOUSE_PICKER")),
                 org.mockito.ArgumentMatchers.eq(Set.of("platform:order:list")), any(),
                 org.mockito.ArgumentMatchers.eq(Duration.ofMinutes(30)),
                 org.mockito.ArgumentMatchers.eq(Duration.ofDays(7)));
@@ -123,12 +127,36 @@ class AuthServiceSmallJwtTest {
         var response = service.refresh("refresh-old");
 
         assertThat(response.accessToken()).isEqualTo("domestic-refreshed");
+        assertThat(response.tokenType()).isEqualTo("Bearer");
+        assertThat(response.expiresIn()).isEqualTo(1800);
+        assertThat(response.refreshToken()).isNotBlank().isNotEqualTo("refresh-old");
+        assertThat(response.refreshExpiresIn()).isEqualTo(604800);
         assertThat(response.overseasAccessToken()).isEqualTo("overseas-refreshed");
         assertThat(response.overseasExpiresIn()).isEqualTo(900);
+        verify(tokenSessionStore).consume("refresh-old");
+        verify(tokenSessionStore).store(anyString(), org.mockito.ArgumentMatchers.eq(52L),
+                org.mockito.ArgumentMatchers.eq(Set.of("MERCHANT_ADMIN")),
+                org.mockito.ArgumentMatchers.eq(Set.of("merchant:order:list")),
+                org.mockito.ArgumentMatchers.eq(response.refreshToken()),
+                org.mockito.ArgumentMatchers.eq(Duration.ofMinutes(30)),
+                org.mockito.ArgumentMatchers.eq(Duration.ofDays(7)));
         verify(authorizationLoader).load(account);
         verify(overseasTokenService).issue(account, snapshot);
     }
 
+    @Test
+    void consumedRefreshTokenCannotMintAnotherDomesticOrOverseasPair() {
+        when(tokenSessionStore.consume("refresh-consumed")).thenReturn(null);
+
+        assertThatThrownBy(() -> service.refresh("refresh-consumed"))
+                .isInstanceOf(com.baiyue.common.core.exception.BizException.class)
+                .hasMessageContaining("刷新令牌无效或已过期");
+
+        verify(repository, never()).findById(any());
+        verify(jwtEncoder, never()).encode(any());
+        verify(overseasTokenService, never()).issue(any(), any());
+    }
+
     @Test
     void impersonationTokenAlsoKeepsRolesAndPermissionsOutOfJwt() {
         AuthAccount account = new AuthAccount();

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();

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

@@ -0,0 +1,77 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.AuthorizationLoader;
+import com.baiyue.auth.client.AuthorizationSnapshot;
+import com.baiyue.auth.dto.OverseasSessionValidationDtos.FailureReason;
+import com.baiyue.auth.dto.OverseasSessionValidationDtos.Request;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+class OverseasSessionValidationServiceTest {
+    private final AuthAccountRepository accounts = mock(AuthAccountRepository.class);
+    private final AuthorizationLoader authorizationLoader = mock(AuthorizationLoader.class);
+    private final OverseasSessionValidationService service = new OverseasSessionValidationService();
+    private AuthAccount account;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        inject("accounts", accounts);
+        inject("authorizationLoader", authorizationLoader);
+        account = new AuthAccount();
+        account.setId(42L);
+        account.setAccountStatus("ACTIVE");
+        account.setTokenVersion(8);
+        when(accounts.findById(42L)).thenReturn(account);
+    }
+
+    @Test
+    void oldTokenIsRejectedAfterWarehouseChangeBumpsAccountVersion() {
+        assertThat(service.validate(new Request(42L, 7, 900L)))
+                .extracting("valid", "failureReason")
+                .containsExactly(false, FailureReason.TOKEN_VERSION_MISMATCH);
+    }
+
+    @Test
+    void newlyIssuedTokenWithCurrentWarehousePasses() {
+        when(authorizationLoader.load(account)).thenReturn(snapshot(8L, 901L));
+
+        assertThat(service.validate(new Request(42L, 8, 901L)).valid()).isTrue();
+    }
+
+    @Test
+    void missingOrChangedWarehouseBindingFailsClosed() {
+        when(authorizationLoader.load(account)).thenReturn(snapshot(8L, null));
+        assertThat(service.validate(new Request(42L, 8, null)).failureReason())
+                .isEqualTo(FailureReason.WAREHOUSE_UNBOUND);
+
+        when(authorizationLoader.load(account)).thenReturn(snapshot(8L, 901L));
+        assertThat(service.validate(new Request(42L, 8, 900L)).failureReason())
+                .isEqualTo(FailureReason.WAREHOUSE_MISMATCH);
+    }
+
+    @Test
+    void disabledAccountFailsClosedBeforeIamLookup() {
+        account.setAccountStatus("DISABLED");
+        assertThat(service.validate(new Request(42L, 8, 901L)).failureReason())
+                .isEqualTo(FailureReason.ACCOUNT_INVALID);
+    }
+
+    private static AuthorizationSnapshot snapshot(Long version, Long warehouseId) {
+        return new AuthorizationSnapshot(42L, 0L, 84L, "PLATFORM", "PDA",
+                Set.of("WAREHOUSE_PICKER"), Set.of("lastleg:pda:operate"), version, warehouseId);
+    }
+
+    private void inject(String fieldName, Object value) throws Exception {
+        var field = OverseasSessionValidationService.class.getDeclaredField(fieldName);
+        field.setAccessible(true);
+        field.set(service, value);
+    }
+}

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

@@ -24,6 +24,7 @@ import java.util.Set;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.when;
 
 @SpringJUnitConfig(classes = {OverseasTokenService.class, OverseasTokenServiceTest.Config.class})
@@ -45,10 +46,13 @@ class OverseasTokenServiceTest {
     @Test
     void signsShortRs256TokenWithCrossRegionClaims() {
         AuthAccount account = new AuthAccount();
-        account.setId(42L); account.setAccountStatus("ACTIVE"); account.setDefaultTenantId(100L);
+        account.setId(42L); account.setAccountStatus("ACTIVE"); account.setDefaultTenantId(999L);
         account.setDefaultMembershipId(84L); account.setDefaultAppCode("MERCHANT");
-        AuthorizationSnapshot snapshot = new AuthorizationSnapshot(42L, 100L, 84L, "MERCHANT", "WEB",
-            Set.of("MERCHANT_ADMIN"), Set.of("merchant:order:list"), 7L);
+        String authority = "platform:overseas-master-data:quote:list";
+        String lastlegAuthority = "lastleg:pda:operate";
+        String domesticAuthority = "platform:firstleg:order:list";
+        AuthorizationSnapshot snapshot = new AuthorizationSnapshot(42L, 0L, 84L, "PLATFORM", "WEB",
+            Set.of("WAREHOUSE_PICKER"), Set.of(authority, lastlegAuthority, domesticAuthority), 7L, 900L);
         Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
         when(accounts.findById(42L)).thenReturn(account);
         when(authorizationLoader.load(account)).thenReturn(snapshot);
@@ -64,13 +68,65 @@ class OverseasTokenServiceTest {
         assertThat(parameters.getJwsHeader().getKeyId()).isEqualTo("current-kid");
         assertThat(parameters.getClaims().getAudience()).containsExactly("lastleg-api");
         assertThat(parameters.getClaims().getClaims())
-            .containsEntry("user_id", 42L).containsEntry("tenant_id", 100L)
+            .containsEntry("user_id", 42L).containsEntry("tenant_id", 0L)
             .containsEntry("membership_id", 84L)
-            .containsEntry("app_code", "MERCHANT").containsEntry("client_type", "WEB")
+            .containsEntry("app_code", "PLATFORM").containsEntry("client_type", "WEB")
             .containsEntry("permission_version", 7L)
-            .containsEntry("roles", Set.of("MERCHANT_ADMIN"))
-            .containsEntry("authorities", Set.of("merchant:order:list"))
+            .containsEntry("token_version", 0)
+            .containsEntry("overseas_warehouse_id", 900L)
+            .containsEntry("roles", Set.of("WAREHOUSE_PICKER"))
+            .containsEntry("authorities", Set.of(authority, lastlegAuthority))
             .doesNotContainKeys("userId", "tenantId", "appCode", "permissionVersion");
         assertThat(response.expiresIn()).isEqualTo(900);
     }
+
+    @Test
+    void refreshedAuthorizationSnapshotReplacesWarehouseBindingAndTokenIdentity() {
+        AuthAccount account = new AuthAccount();
+        account.setId(43L); account.setAccountStatus("ACTIVE"); account.setDefaultTenantId(0L);
+        account.setDefaultMembershipId(85L); account.setDefaultAppCode("PLATFORM");
+        account.setTokenVersion(8);
+        AuthorizationSnapshot oldBinding = new AuthorizationSnapshot(43L, 0L, 85L, "PLATFORM", "PDA",
+            Set.of("WAREHOUSE_PICKER"), Set.of("lastleg:pda:operate"), 8L, 900L);
+        AuthorizationSnapshot newBinding = new AuthorizationSnapshot(43L, 0L, 85L, "PLATFORM", "PDA",
+            Set.of("WAREHOUSE_PICKER"), Set.of("lastleg:pda:operate"), 9L, 901L);
+        Jwt first = org.mockito.Mockito.mock(Jwt.class);
+        Jwt second = org.mockito.Mockito.mock(Jwt.class);
+        when(encoder.encode(any())).thenReturn(first, second);
+        when(first.getTokenValue()).thenReturn("overseas-old-binding");
+        when(second.getTokenValue()).thenReturn("overseas-new-binding");
+
+        var oldToken = service.issue(account, oldBinding);
+        var newToken = service.issue(account, newBinding);
+
+        ArgumentCaptor<JwtEncoderParameters> captor = ArgumentCaptor.forClass(JwtEncoderParameters.class);
+        verify(encoder, times(2)).encode(captor.capture());
+        var oldClaims = captor.getAllValues().get(0).getClaims();
+        var newClaims = captor.getAllValues().get(1).getClaims();
+        assertThat(oldClaims.getId()).isNotEqualTo(newClaims.getId());
+        assertThat(oldClaims.getClaims()).containsEntry("overseas_warehouse_id", 900L)
+            .containsEntry("permission_version", 8L);
+        assertThat(newClaims.getClaims()).containsEntry("overseas_warehouse_id", 901L)
+            .containsEntry("permission_version", 9L);
+        assertThat(newClaims.getClaims()).containsEntry("token_version", 8);
+        assertThat(oldToken.accessToken()).isNotEqualTo(newToken.accessToken());
+    }
+
+    @Test
+    void unboundWarehouseIsOmittedSoPdaIdentityMustFailClosed() {
+        AuthAccount account = new AuthAccount();
+        account.setId(44L); account.setAccountStatus("ACTIVE");
+        AuthorizationSnapshot unbound = new AuthorizationSnapshot(44L, 0L, 86L, "PLATFORM", "PDA",
+            Set.of("WAREHOUSE_PICKER"), Set.of("lastleg:pda:operate"), 10L, null);
+        Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
+        when(encoder.encode(any())).thenReturn(encoded);
+        when(encoded.getTokenValue()).thenReturn("overseas-unbound");
+
+        service.issue(account, unbound);
+
+        ArgumentCaptor<JwtEncoderParameters> captor = ArgumentCaptor.forClass(JwtEncoderParameters.class);
+        verify(encoder).encode(captor.capture());
+        assertThat(captor.getValue().getClaims().getClaims())
+            .doesNotContainKey("overseas_warehouse_id");
+    }
 }

common-event-contract/AGENTS.md

@@ -14,13 +14,20 @@
 | 事件 ID 与业务键 | `EventIdentifiers.java` |
 | Payload 规范化与哈希 | `EventPayloadCanonicalizer.java`、`EventPayloadHash.java` |
 | 事件类型与区域 | `EventTypes.java`、`RegionCode.java` |
-| 头程装柜完成 V1 | `FirstLegLoadingPlanCompletedV1.java`；国内生产者见 `../firstleg/service/LoadingCompletedOutboxService.java` |
+| 头程装柜完成 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` |
-| 契约测试 | `src/test/java/com/baiyue/common/event/EventEnvelopeTest.java`、`FirstLegLoadingPlanCompletedV1Test.java` |
+| 契约测试 | `src/test/java/com/baiyue/common/event/EventEnvelopeTest.java`、`FirstLegLoadingPlanCompletedV1Test.java`、`FirstLegLoadingPlanCompletedV2Test.java`、`OverseasContainerUnloadedV1Test.java`、`FirstLegContainerShippingNodeRecordedV1Test.java` |
+| 真实生产/消费验收 | `../firstleg/src/test/java/com/baiyue/firstleg/service/TaillegRealProducerAcceptanceTest.java`、`../lastleg-service/src/test/java/com/baiyue/lastleg/service/TaillegRealConsumerAcceptanceTest.java` |
 
 ## 修改与验证
 
 - 所有字段与事件类型都视为跨仓公共契约；当前开发阶段不保留旧事件字段、旧版本或兼容解析，目标契约变化时直接修改当前模型，并同步更新 `event-bridge-service/`、国内生产者、尾程消费者和全部契约测试。
 - 哈希算法或规范化规则变化必须同步更新全部生产者和消费者，并保留跨语言确定性测试。
 - MQ 事件不携带用户 Access Token；生产者和消费者使用 MQ TLS/ACL 或内部服务身份，事件信封负责事件 ID、业务键、来源/目标区域、版本和 Payload 哈希。
+- `OVERSEAS_CONTAINER_UNLOADED` 固定从 `OVERSEAS` 发往 `CN`，用于回传海外 PDA 卸柜完成及卸柜照片上传时间；预计报空时间由国内头程按照片上传时间加两天计算，实际报空时间允许后续补充。
 - 从父目录运行 `mvn -pl common-event-contract -am test`。

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

@@ -10,6 +10,10 @@ public final class EventTypes {
     public static final String ORDER_CANCELLED = "OrderCancelled";
     public static final String FIRST_LEG_SHIPMENT_DEPARTED = "FirstLegShipmentDeparted";
     public static final String FIRST_LEG_LOADING_PLAN_COMPLETED = "FirstLegLoadingPlanCompleted";
+    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/FirstLegContainerShippingNodeRecordedV1.java

@@ -0,0 +1,47 @@
+package com.baiyue.common.event;
+
+import java.time.Instant;
+import java.util.Map;
+
+/** Actual carrier milestone recorded by Firstleg for overseas receiving readiness. */
+public record FirstLegContainerShippingNodeRecordedV1(
+        String queryId,
+        String customerId,
+        String oceanBookingId,
+        String containerBookingId,
+        String containerNo,
+        String standardNode,
+        int nodeSequence,
+        Instant observedAt,
+        Instant actualAt,
+        String locationCode,
+        String locationName,
+        String providerCode,
+        String providerEventId,
+        String providerNodeCode,
+        String sourceReference,
+        String rawPayloadHash) {
+    private static final Map<String, Integer> STANDARD_NODES = Map.of(
+        "DEPARTED_WAREHOUSE", 10, "AT_ORIGIN_PORT", 20, "LOADED_ON_VESSEL", 30,
+        "DEPARTED_ORIGIN_PORT", 40, "IN_TRANSIT", 50, "ARRIVED_DESTINATION_PORT", 60,
+        "DISCHARGED_FROM_VESSEL", 70, "PICKUP_READY", 80, "PICKED_UP", 90,
+        "EMPTY_RETURNED", 100);
+
+    public FirstLegContainerShippingNodeRecordedV1 {
+        if (queryId == null || queryId.isBlank() || customerId == null || customerId.isBlank()
+            || oceanBookingId == null || oceanBookingId.isBlank()
+            || containerBookingId == null || containerBookingId.isBlank()
+            || containerNo == null || containerNo.isBlank()) {
+            throw new IllegalArgumentException("船节点交接业务标识不能为空");
+        }
+        if (standardNode == null || !Integer.valueOf(nodeSequence).equals(STANDARD_NODES.get(standardNode))
+            || observedAt == null || actualAt == null) {
+            throw new IllegalArgumentException("船节点交接只接受带实际时间的标准节点事实");
+        }
+        if (providerCode == null || providerCode.isBlank() || providerEventId == null
+            || providerEventId.isBlank() || providerNodeCode == null || providerNodeCode.isBlank()
+            || rawPayloadHash == null || !rawPayloadHash.matches("(?i)^[0-9a-f]{64}$")) {
+            throw new IllegalArgumentException("船节点交接供应商审计字段不完整");
+        }
+    }
+}

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

@@ -16,12 +16,25 @@ public record FirstLegLoadingPlanCompletedV1(
             String destinationWarehouseCode, String destinationWarehouseName,
             int packageCount, Integer productQuantity, Integer palletCount,
             BigDecimal grossWeightKg, BigDecimal netWeightKg, BigDecimal volumeCbm,
-            List<Item> items, String customerId, String orderType, List<PalletSnapshot> pallets) {
+            List<Item> items, String customerId, String orderType, List<PalletSnapshot> pallets,
+            String destinationType) {
         public Order {
             items = items == null ? List.of() : items;
             orderType = orderType == null || orderType.isBlank() ? "FIRST_LEG" : orderType;
             pallets = pallets == null ? List.of() : pallets;
         }
+        public Order(String sourceInboundId, String rootInboundId,
+                     String sourceOrderId, String sourceOrderNo, String rootOrderId,
+                     String inboundCode, String destinationWarehouseId,
+                     String destinationWarehouseCode, String destinationWarehouseName,
+                     int packageCount, Integer productQuantity, Integer palletCount,
+                     BigDecimal grossWeightKg, BigDecimal netWeightKg, BigDecimal volumeCbm,
+                     List<Item> items, String customerId, String orderType, List<PalletSnapshot> pallets) {
+            this(sourceInboundId, rootInboundId, sourceOrderId, sourceOrderNo, rootOrderId,
+                inboundCode, destinationWarehouseId, destinationWarehouseCode,
+                destinationWarehouseName, packageCount, productQuantity, palletCount,
+                grossWeightKg, netWeightKg, volumeCbm, items, customerId, orderType, pallets, null);
+        }
         public Order(String sourceInboundId, String rootInboundId,
                      String sourceOrderId, String sourceOrderNo, String rootOrderId,
                      String inboundCode, String destinationWarehouseId,
@@ -32,7 +45,7 @@ public record FirstLegLoadingPlanCompletedV1(
             this(sourceInboundId, rootInboundId, sourceOrderId, sourceOrderNo, rootOrderId,
                 inboundCode, destinationWarehouseId, destinationWarehouseCode,
                 destinationWarehouseName, packageCount, productQuantity, palletCount,
-                grossWeightKg, netWeightKg, volumeCbm, items, null, "FIRST_LEG", List.of());
+                grossWeightKg, netWeightKg, volumeCbm, items, null, "FIRST_LEG", List.of(), null);
         }
     }
 

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

@@ -3,7 +3,7 @@ package com.baiyue.common.event;
 import java.math.BigDecimal;
 import java.util.List;
 
-/** 装柜完成交接快照，包含三类逐货物备注及一键代发托盘快照。 */
+/** 装柜完成交接快照，包含三类逐货物备注、推荐托数和可复用的头程托盘编号快照。 */
 public record FirstLegLoadingPlanCompletedV2(
         String loadingPlanId, String planNo, String containerBookingId,
         String containerNo, String cabinetNo, String warehouseId, String warehouseName,
@@ -15,13 +15,28 @@ public record FirstLegLoadingPlanCompletedV2(
             String destinationWarehouseCode, String destinationWarehouseName,
             int packageCount, Integer productQuantity, Integer palletCount,
             BigDecimal grossWeightKg, BigDecimal netWeightKg, BigDecimal volumeCbm,
-            List<Item> items, String customerId, String orderType, List<PalletSnapshot> pallets) {
+            List<Item> items, String customerId, String orderType, List<PalletSnapshot> pallets,
+            /** 目的类型：FBA 可按箱数收货，OVERSEAS 必须逐箱扫码。 */
+            String destinationType) {
         public Order {
             items = items == null ? List.of() : items;
             orderType = orderType == null || orderType.isBlank() ? "FIRST_LEG" : orderType;
             pallets = pallets == null ? List.of() : pallets;
         }
 
+        public Order(String sourceInboundId, String rootInboundId,
+                     String sourceOrderId, String sourceOrderNo, String rootOrderId,
+                     String inboundCode, String destinationWarehouseId,
+                     String destinationWarehouseCode, String destinationWarehouseName,
+                     int packageCount, Integer productQuantity, Integer palletCount,
+                     BigDecimal grossWeightKg, BigDecimal netWeightKg, BigDecimal volumeCbm,
+                     List<Item> items, String customerId, String orderType, List<PalletSnapshot> pallets) {
+            this(sourceInboundId, rootInboundId, sourceOrderId, sourceOrderNo, rootOrderId,
+                inboundCode, destinationWarehouseId, destinationWarehouseCode,
+                destinationWarehouseName, packageCount, productQuantity, palletCount,
+                grossWeightKg, netWeightKg, volumeCbm, items, customerId, orderType, pallets, null);
+        }
+
         public Order(String sourceInboundId, String rootInboundId,
                      String sourceOrderId, String sourceOrderNo, String rootOrderId,
                      String inboundCode, String destinationWarehouseId,
@@ -32,7 +47,7 @@ public record FirstLegLoadingPlanCompletedV2(
             this(sourceInboundId, rootInboundId, sourceOrderId, sourceOrderNo, rootOrderId,
                 inboundCode, destinationWarehouseId, destinationWarehouseCode,
                 destinationWarehouseName, packageCount, productQuantity, palletCount,
-                grossWeightKg, netWeightKg, volumeCbm, items, null, "FIRST_LEG", List.of());
+                grossWeightKg, netWeightKg, volumeCbm, items, null, "FIRST_LEG", List.of(), null);
         }
     }
 
@@ -46,7 +61,9 @@ public record FirstLegLoadingPlanCompletedV2(
             String destinationWarehouseName, String fbaTrackingNo,
             String shipmentNo, String shippingMark,
             String customerRemark, String internalRemark, String warehouseRemark,
-            String palletNo, List<String> cartonMarks) {
+            String palletNo,
+            /** 按实装箱数稳定随机冻结的头程箱号；数量与 packageCount 相等且均对应本明细 SKU。 */
+            List<String> cartonMarks) {
         public Item {
             cartonMarks = cartonMarks == null ? List.of() : cartonMarks;
         }
@@ -69,10 +86,10 @@ public record FirstLegLoadingPlanCompletedV2(
         }
     }
 
-    /** 一键代发入仓单的托盘冻结快照。 */
+    /** 头程托盘冻结快照；普通入仓用于复用打印编号，一键代发还冻结 SKU/箱唛库存。 */
     public record PalletSnapshot(String palletNo, List<SkuPackageSnapshot> skuPackages) {}
 
-    /** 托盘下 SKU、箱数、数量及箱唛冻结快照。 */
+    /** 托盘下 SKU、箱数、数量及箱号冻结快照；cartonMarks 中每个箱号都对应 skuCode。 */
     public record SkuPackageSnapshot(String skuCode, String productName,
                                      int packageCount, int productQuantity,
                                      List<String> cartonMarks) {}

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

@@ -0,0 +1,16 @@
+package com.baiyue.common.event;
+
+import java.time.Instant;
+
+/**
+ * 海外仓柜级卸柜完成事实；国内订舱 ID 是稳定聚合与幂等标识，containerNo 用于核对物理柜号。
+ * unloadingCompletedAt 是全柜 complete 时刻，不得使用签收拍照上传时刻代替。
+ */
+public record OverseasContainerUnloadedV1(
+        String sourceContainerBookingId,
+        String containerNo,
+        Instant unloadingCompletedAt,
+        Instant unloadingPhotoUploadedAt,
+        Instant actualEmptyReportedAt
+) {
+}

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-event-contract/src/test/java/com/baiyue/common/event/FirstLegContainerShippingNodeRecordedV1Test.java

@@ -0,0 +1,49 @@
+package com.baiyue.common.event;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class FirstLegContainerShippingNodeRecordedV1Test {
+    @Test
+    void roundTripsLongBusinessIdsAndActualPickupReadyFact() throws Exception {
+        var payload = payload();
+        var mapper = new ObjectMapper().findAndRegisterModules();
+
+        var restored = mapper.readValue(mapper.writeValueAsString(payload),
+            FirstLegContainerShippingNodeRecordedV1.class);
+
+        assertThat(restored).isEqualTo(payload);
+        assertThat(restored.containerBookingId()).isEqualTo("2088000000000000003");
+        assertThat(restored.standardNode()).isEqualTo("PICKUP_READY");
+        assertThat(restored.nodeSequence()).isEqualTo(80);
+    }
+
+    @Test
+    void rejectsEstimatedOnlyOrIncompleteProviderFacts() {
+        assertThatThrownBy(() -> new FirstLegContainerShippingNodeRecordedV1(
+            "1", "2", "3", "4", "ZCSU7881970", "PICKUP_READY", 80,
+            Instant.parse("2026-08-25T01:00:00Z"), null, null, null,
+            "ZIM", "evt-1", "Carrier Release", "ZIM:evt-1", "a".repeat(64)))
+            .isInstanceOf(IllegalArgumentException.class).hasMessageContaining("实际时间");
+
+        assertThatThrownBy(() -> new FirstLegContainerShippingNodeRecordedV1(
+            "1", "2", "3", "4", "ZCSU7881970", "ARRIVED", 60,
+            Instant.parse("2026-08-25T01:00:00Z"), Instant.parse("2026-08-25T01:00:00Z"),
+            null, null, "ZIM", "evt-2", "ARRIVED", "ZIM:evt-2", "b".repeat(64)))
+            .isInstanceOf(IllegalArgumentException.class);
+    }
+
+    private static FirstLegContainerShippingNodeRecordedV1 payload() {
+        return new FirstLegContainerShippingNodeRecordedV1(
+            "2088000000000000001", "2088000000000000002", "2088000000000000004",
+            "2088000000000000003", "ZCSU7881970", "PICKUP_READY", 80,
+            Instant.parse("2026-08-25T01:02:00Z"), Instant.parse("2026-08-25T01:00:00Z"),
+            "USLAX", "Los Angeles", "ZIM", "evt-1", "AVAILABLE",
+            "ZIM:evt-1", "a".repeat(64));
+    }
+}

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

@@ -47,4 +47,17 @@ class FirstLegLoadingPlanCompletedV1Test {
         assertThat(restored).isEqualTo(payload);
         assertThat(json).contains("ONE_CLICK_DROPSHIP", "PLT-01", "BOX-003", "customerId");
     }
+
+    @Test
+    void legacyParserRetainsDestinationTypeWhenV2OrderCarriesIt() throws Exception {
+        String json = """
+            {"loadingPlanId":"1","planNo":"LP-1","containerBookingId":"2","containerNo":"CONT-1",
+             "warehouseId":"3","warehouseName":"海外仓","orders":[{"sourceInboundId":"100",
+             "destinationWarehouseId":"3","packageCount":1,"items":[],"destinationType":"OVERSEAS"}]}
+            """;
+
+        FirstLegLoadingPlanCompletedV1 restored = mapper.readValue(json, FirstLegLoadingPlanCompletedV1.class);
+
+        assertThat(restored.orders().get(0).destinationType()).isEqualTo("OVERSEAS");
+    }
 }

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

@@ -39,4 +39,31 @@ class FirstLegLoadingPlanCompletedV2Test {
         assertThat(json.at("/orders/0/orderType").asText()).isEqualTo("ONE_CLICK_DROPSHIP");
         assertThat(json.at("/orders/0/pallets/0/skuPackages/0/cartonMarks")).hasSize(2);
     }
+
+    @Test
+    void carriesFrozenDestinationType() {
+        var order = new FirstLegLoadingPlanCompletedV2.Order(
+            "2", "2", "3", "ORD", "3", "RK", null, "ONT8", "FBA ONT8",
+            2, 20, 0, null, null, null, List.of(), "11", "FIRST_LEG", List.of(), "FBA");
+
+        var json = new ObjectMapper().valueToTree(new FirstLegLoadingPlanCompletedV2(
+            "4", "P", "5", "CONT", "CAB", "6", "WH", List.of(order)));
+
+        assertThat(json.at("/orders/0/destinationType").asText()).isEqualTo("FBA");
+    }
+
+    @Test
+    void mapsEachOrdinaryCartonNumberToItsSku() {
+        var item = new FirstLegLoadingPlanCompletedV2.Item("1", "SKU-PSC2", "产品", "Product", 2,
+            20, null, null, null, null, null, null, null, null, null, null, null,
+            null, null, null, null, List.of("HDHK260711126-01", "HDHK260711126-02"));
+        var order = new FirstLegLoadingPlanCompletedV2.Order("2", "2", "3", "ORD", "3", "RK",
+            null, null, null, 2, 20, null, null, null, null, List.of(item));
+
+        var json = new ObjectMapper().valueToTree(new FirstLegLoadingPlanCompletedV2(
+            "4", "P", "5", "CONT", "CAB", "6", "WH", List.of(order)));
+
+        assertThat(json.at("/orders/0/items/0/skuCode").asText()).isEqualTo("SKU-PSC2");
+        assertThat(json.at("/orders/0/items/0/cartonMarks")).hasSize(2);
+    }
 }

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

@@ -0,0 +1,26 @@
+package com.baiyue.common.event;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class OverseasContainerUnloadedV1Test {
+    private final ObjectMapper mapper = new ObjectMapper().registerModule(new JavaTimeModule());
+
+    @Test
+    void payloadRoundTripsWithStableContainerIdAndUtcFacts() throws Exception {
+        var payload = new OverseasContainerUnloadedV1("1001", "MSCU1234567",
+            Instant.parse("2026-08-20T03:00:00Z"), Instant.parse("2026-08-20T02:30:00Z"), null);
+
+        String json = mapper.writeValueAsString(payload);
+
+        assertThat(mapper.readValue(json, OverseasContainerUnloadedV1.class)).isEqualTo(payload);
+        assertThat(json).contains("sourceContainerBookingId", "1001", "MSCU1234567", "unloadingPhotoUploadedAt");
+        assertThat(payload.unloadingCompletedAt()).isAfter(payload.unloadingPhotoUploadedAt());
+        assertThat(payload.unloadingCompletedAt()).isNotEqualTo(payload.unloadingPhotoUploadedAt());
+    }
+}

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-openapi/src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java

@@ -75,6 +75,14 @@ public class BaiyueOpenApiAutoConfiguration {
             .addOperationCustomizer(correlationHeaderCustomizer).build();
     }
 
+    @Bean
+    GroupedOpenApi pdaApi(OperationCustomizer correlationHeaderCustomizer) {
+        return GroupedOpenApi.builder().group("pda")
+            .displayName("PDA APIs / PDA 作业接口")
+            .pathsToMatch("/api/pda/**")
+            .addOperationCustomizer(correlationHeaderCustomizer).build();
+    }
+
     private Parameter header(String name, String description, boolean required) {
         return new HeaderParameter().name(name).description(description).required(required)
             .schema(new io.swagger.v3.oas.models.media.StringSchema());

common-openapi/src/test/java/com/baiyue/common/openapi/PdaOpenApiGroupContractTest.java

@@ -0,0 +1,17 @@
+package com.baiyue.common.openapi;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class PdaOpenApiGroupContractTest {
+    @Test
+    void pdaGroupOnlyMatchesDeviceApis() {
+        BaiyueOpenApiAutoConfiguration configuration = new BaiyueOpenApiAutoConfiguration();
+        var group = configuration.pdaApi(configuration.correlationHeaderCustomizer());
+
+        assertThat(group.getGroup()).isEqualTo("pda");
+        assertThat(group.getPathsToMatch()).containsExactly("/api/pda/**");
+        assertThat(group.getPathsToMatch()).noneMatch(path -> path.contains("internal"));
+    }
+}

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,13 +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) implements Principal {
+                                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,
-                permissions, false, null, null, false);
+        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, 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,13 +37,15 @@ 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,
                 Boolean.TRUE.equals(jwt.getClaim("impersonated")),
                 longClaim(jwt, "actor_user_id"),
                 longClaim(jwt, "actor_membership_id"),
-                Boolean.TRUE.equals(jwt.getClaim("password_change_required")));
+                Boolean.TRUE.equals(jwt.getClaim("password_change_required")),
+                longClaim(jwt, "overseas_warehouse_id"));
         List<SimpleGrantedAuthority> authorities = permissions.stream()
                 .map(SimpleGrantedAuthority::new).toList();
         return new BaiyueJwtAuthenticationToken(user, jwt.getTokenValue(), authorities);
@@ -86,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-security/src/test/java/com/baiyue/common/security/JwtClaimsMapperTest.java

@@ -81,6 +81,7 @@ class JwtClaimsMapperTest {
                 .claim("actor_user_id", 42L)
                 .claim("actor_membership_id", 43L)
                 .claim("password_change_required", true)
+                .claim("overseas_warehouse_id", 900L)
                 .build();
 
         AuthenticatedUser user = new JwtClaimsMapper().map(jwt).getPrincipal();
@@ -88,5 +89,6 @@ class JwtClaimsMapperTest {
         assertThat(user.actorUserId()).isEqualTo(42L);
         assertThat(user.actorMembershipId()).isEqualTo(43L);
         assertThat(user.passwordChangeRequired()).isTrue();
+        assertThat(user.overseasWarehouseId()).isEqualTo(900L);
     }
 }

common-web/AGENTS.md

@@ -11,6 +11,9 @@
 |---|---|
 | 链路上下文 | `src/main/java/com/baiyue/common/web/CorrelationContext.java` |
 | 请求 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` |
@@ -23,5 +26,8 @@
 - 网关/Servlet Security 的真实 401/403、协议或基础设施错误、Warehouse readiness 503、Audit 202 与 Event Bridge 内部鉴权仍保留真实 HTTP 状态；完整边界见 `../docs/统一响应约定改造方案-HTTP200.md`。
 - 修改自动配置时必须验证 `audit-service`、`event-bridge-service` 等只扫描自身包的应用仍能加载 `GlobalExceptionHandler` 和 `CorrelationIdFilter`。
 - 修改 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/pom.xml

@@ -39,6 +39,11 @@
             <groupId>io.micrometer</groupId>
             <artifactId>micrometer-registry-prometheus</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.github.openfeign</groupId>
+            <artifactId>feign-core</artifactId>
+            <optional>true</optional>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-test</artifactId>

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

@@ -9,8 +9,11 @@ import org.slf4j.MDC;
 public final class CorrelationContext {
     public static final String REQUEST_ID = "requestId";
     public static final String TRACE_ID = "traceId";
+    public static final String SPAN_ID = "spanId";
+    public static final String TRACE_PARENT = "traceparent";
     public static final String REQUEST_ID_HEADER = "X-Request-Id";
     public static final String TRACE_ID_HEADER = "X-Trace-Id";
+    public static final String TRACE_PARENT_HEADER = TraceParent.HEADER;
 
     private CorrelationContext() {}
 
@@ -22,6 +25,14 @@ public final class CorrelationContext {
         return value(request, TRACE_ID);
     }
 
+    public static String spanId(HttpServletRequest request) {
+        return value(request, SPAN_ID);
+    }
+
+    public static String traceParent(HttpServletRequest request) {
+        return value(request, TRACE_PARENT);
+    }
+
     private static String value(HttpServletRequest request, String key) {
         Object attribute = request.getAttribute(key);
         return attribute == null ? MDC.get(key) : attribute.toString();

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

@@ -11,6 +11,7 @@ import org.springframework.stereotype.Component;
 import org.springframework.web.filter.OncePerRequestFilter;
 
 import java.io.IOException;
+import java.util.Enumeration;
 import java.util.UUID;
 import java.util.regex.Pattern;
 
@@ -25,24 +26,60 @@ public class CorrelationIdFilter extends OncePerRequestFilter {
     @Override
     protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                     FilterChain filterChain) throws ServletException, IOException {
-        String requestId = acceptedOrGenerated(request.getHeader(CorrelationContext.REQUEST_ID_HEADER), false);
-        String traceId = acceptedOrGenerated(request.getHeader(CorrelationContext.TRACE_ID_HEADER), true);
+        String requestId = requestId(request);
+        TraceParent traceParent = traceParent(request);
+        String traceId = traceParent.traceId();
         request.setAttribute(CorrelationContext.REQUEST_ID, requestId);
         request.setAttribute(CorrelationContext.TRACE_ID, traceId);
+        request.setAttribute(CorrelationContext.SPAN_ID, traceParent.parentId());
+        request.setAttribute(CorrelationContext.TRACE_PARENT, traceParent.value());
         response.setHeader(CorrelationContext.REQUEST_ID_HEADER, requestId);
         response.setHeader(CorrelationContext.TRACE_ID_HEADER, traceId);
+        response.setHeader(CorrelationContext.TRACE_PARENT_HEADER, traceParent.value());
 
         try (MDC.MDCCloseable ignoredRequest = MDC.putCloseable(CorrelationContext.REQUEST_ID, requestId);
-             MDC.MDCCloseable ignoredTrace = MDC.putCloseable(CorrelationContext.TRACE_ID, traceId)) {
+             MDC.MDCCloseable ignoredTrace = MDC.putCloseable(CorrelationContext.TRACE_ID, traceId);
+             MDC.MDCCloseable ignoredSpan = MDC.putCloseable(CorrelationContext.SPAN_ID, traceParent.parentId())) {
             filterChain.doFilter(request, response);
         }
     }
 
-    private String acceptedOrGenerated(String candidate, boolean compact) {
-        if (candidate != null && SAFE_ID.matcher(candidate).matches()) {
-            return candidate;
+    private String requestId(HttpServletRequest request) {
+        HeaderValue header = singleHeader(request, CorrelationContext.REQUEST_ID_HEADER, 128);
+        if (header.valid() && SAFE_ID.matcher(header.value()).matches()) {
+            return header.value();
+        }
+        return UUID.randomUUID().toString();
+    }
+
+    private TraceParent traceParent(HttpServletRequest request) {
+        HeaderValue standard = singleHeader(request, CorrelationContext.TRACE_PARENT_HEADER,
+                TraceParent.HEADER_LENGTH);
+        if (standard.present()) {
+            if (standard.valid()) {
+                return TraceParent.parse(standard.value()).map(TraceParent::childOf)
+                        .orElseGet(() -> TraceParent.newRoot(null));
+            }
+            return TraceParent.newRoot(null);
+        }
+
+        HeaderValue legacy = singleHeader(request, CorrelationContext.TRACE_ID_HEADER, 32);
+        return TraceParent.newRoot(legacy.valid() ? legacy.value() : null);
+    }
+
+    private HeaderValue singleHeader(HttpServletRequest request, String name, int maxLength) {
+        Enumeration<String> values = request.getHeaders(name);
+        if (values == null || !values.hasMoreElements()) {
+            return HeaderValue.missing();
+        }
+        String value = values.nextElement();
+        boolean duplicate = values.hasMoreElements();
+        return new HeaderValue(true, !duplicate && value != null && value.length() <= maxLength, value);
+    }
+
+    private record HeaderValue(boolean present, boolean valid, String value) {
+        private static HeaderValue missing() {
+            return new HeaderValue(false, false, null);
         }
-        String id = UUID.randomUUID().toString();
-        return compact ? id.replace("-", "") : id;
     }
 }

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

@@ -0,0 +1,18 @@
+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.context.annotation.Bean;
+
+/** Enables synchronous Feign trace propagation without making Feign a required dependency. */
+@AutoConfiguration(afterName = "org.springframework.cloud.openfeign.FeignAutoConfiguration")
+@ConditionalOnClass(name = "feign.RequestInterceptor")
+public class FeignTracePropagationAutoConfiguration {
+
+    @Bean
+    @ConditionalOnMissingBean(FeignTraceRequestInterceptor.class)
+    FeignTraceRequestInterceptor feignTraceRequestInterceptor() {
+        return new FeignTraceRequestInterceptor();
+    }
+}

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

@@ -0,0 +1,41 @@
+package com.baiyue.common.web;
+
+import feign.RequestInterceptor;
+import feign.RequestTemplate;
+import org.slf4j.MDC;
+import org.springframework.core.Ordered;
+
+import java.util.regex.Pattern;
+
+/** Propagates the trusted synchronous request trace context to every Feign invocation. */
+public final class FeignTraceRequestInterceptor implements RequestInterceptor, Ordered {
+    private static final Pattern SAFE_REQUEST_ID = Pattern.compile("[A-Za-z0-9._:-]{1,128}");
+
+    @Override
+    public void apply(RequestTemplate template) {
+        removeManagedHeaders(template);
+
+        String requestId = MDC.get(CorrelationContext.REQUEST_ID);
+        if (requestId != null && SAFE_REQUEST_ID.matcher(requestId).matches()) {
+            template.header(CorrelationContext.REQUEST_ID_HEADER, requestId);
+        }
+
+        String traceId = MDC.get(CorrelationContext.TRACE_ID);
+        if (TraceParent.validLegacyTraceId(traceId)) {
+            TraceParent outbound = TraceParent.outboundChild(traceId);
+            template.header(CorrelationContext.TRACE_ID_HEADER, outbound.traceId());
+            template.header(CorrelationContext.TRACE_PARENT_HEADER, outbound.value());
+        }
+    }
+
+    @Override
+    public int getOrder() {
+        return Ordered.LOWEST_PRECEDENCE;
+    }
+
+    private void removeManagedHeaders(RequestTemplate template) {
+        template.removeHeader(CorrelationContext.REQUEST_ID_HEADER);
+        template.removeHeader(CorrelationContext.TRACE_ID_HEADER);
+        template.removeHeader(CorrelationContext.TRACE_PARENT_HEADER);
+    }
+}

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

@@ -21,6 +21,8 @@ import org.springframework.web.bind.MissingServletRequestParameterException;
 import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.servlet.resource.NoResourceFoundException;
+import org.springframework.web.server.ResponseStatusException;
 
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -79,6 +81,21 @@ public class GlobalExceptionHandler {
         return failure(ResultCode.FORBIDDEN, ResultCode.FORBIDDEN.message(), request);
     }
 
+    @ExceptionHandler(ResponseStatusException.class)
+    public ResponseEntity<ApiResponse<Void>> handleResponseStatus(
+            ResponseStatusException exception, HttpServletRequest request) {
+        ResultCode code = resultCode(exception.getStatusCode().value());
+        String message = exception.getReason() == null || exception.getReason().isBlank()
+                ? code.message() : exception.getReason();
+        return failure(code, message, request);
+    }
+
+    @ExceptionHandler(NoResourceFoundException.class)
+    public ResponseEntity<ApiResponse<Void>> handleNoResourceFound(
+            NoResourceFoundException exception, HttpServletRequest request) {
+        return failure(ResultCode.NOT_FOUND, ResultCode.NOT_FOUND.message(), request);
+    }
+
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ApiResponse<Void>> handleUnexpected(Exception exception, HttpServletRequest request) {
         log.error("Unhandled request failure requestId={} traceId={}",
@@ -123,4 +140,18 @@ public class GlobalExceptionHandler {
             meterRegistry.counter("baiyue.api.business.failures", "code", code.code()).increment();
         }
     }
+
+    private ResultCode resultCode(int status) {
+        return switch (status) {
+            case 400 -> ResultCode.BAD_REQUEST;
+            case 401 -> ResultCode.UNAUTHORIZED;
+            case 403 -> ResultCode.FORBIDDEN;
+            case 404 -> ResultCode.NOT_FOUND;
+            case 409 -> ResultCode.CONFLICT;
+            case 422 -> ResultCode.VALIDATION_FAILED;
+            case 429 -> ResultCode.TOO_MANY_REQUESTS;
+            case 503 -> ResultCode.SERVICE_UNAVAILABLE;
+            default -> ResultCode.INTERNAL_ERROR;
+        };
+    }
 }

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

@@ -0,0 +1,111 @@
+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;
+
+/**
+ * Strict W3C {@code traceparent} version 00 value.
+ *
+ * <p>This type deliberately accepts only the currently frozen version-00 shape. Unsupported,
+ * ambiguous or malformed input must start a new trace instead of being partially trusted.</p>
+ */
+public record TraceParent(String traceId, String parentId, String traceFlags) {
+    public static final String HEADER = "traceparent";
+    public static final int HEADER_LENGTH = 55;
+
+    private static final Pattern VERSION_00 = Pattern.compile(
+            "00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})");
+    private static final Pattern LEGACY_TRACE_ID = Pattern.compile("[0-9A-Fa-f]{32}");
+    private static final String ZERO_TRACE_ID = "0".repeat(32);
+    private static final String ZERO_PARENT_ID = "0".repeat(16);
+    private static final SecureRandom RANDOM = new SecureRandom();
+    private static final HexFormat HEX = HexFormat.of();
+
+    public TraceParent {
+        if (!validTraceId(traceId) || !validParentId(parentId)
+                || traceFlags == null || !traceFlags.matches("[0-9a-f]{2}")) {
+            throw new IllegalArgumentException("Invalid W3C traceparent components");
+        }
+    }
+
+    /** Parses one exact, lowercase W3C version-00 header value. */
+    public static Optional<TraceParent> parse(String value) {
+        if (value == null || value.length() != HEADER_LENGTH) {
+            return Optional.empty();
+        }
+        Matcher matcher = VERSION_00.matcher(value);
+        if (!matcher.matches() || !validTraceId(matcher.group(1)) || !validParentId(matcher.group(2))) {
+            return Optional.empty();
+        }
+        return Optional.of(new TraceParent(matcher.group(1), matcher.group(2), matcher.group(3)));
+    }
+
+    /** Creates the local inbound context for a valid remote parent. */
+    public static TraceParent childOf(TraceParent remoteParent) {
+        return new TraceParent(remoteParent.traceId(), randomNonZero(8), remoteParent.traceFlags());
+    }
+
+    /** Creates a new root context, optionally reusing a valid legacy trace ID. */
+    public static TraceParent newRoot(String legacyTraceId) {
+        String traceId = validLegacyTraceId(legacyTraceId)
+                ? legacyTraceId.toLowerCase(java.util.Locale.ROOT) : randomNonZero(16);
+        return new TraceParent(traceId, randomNonZero(8), "00");
+    }
+
+    /** Creates a sampled outbound child for a trusted current trace ID. */
+    public static TraceParent outboundChild(String currentTraceId) {
+        if (!validLegacyTraceId(currentTraceId)) {
+            throw new IllegalArgumentException("Current trace ID is invalid");
+        }
+        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);
+    }
+
+    public String value() {
+        return "00-" + traceId + '-' + parentId + '-' + traceFlags;
+    }
+
+    private static boolean validTraceId(String value) {
+        return value != null && value.matches("[0-9a-f]{32}") && !ZERO_TRACE_ID.equals(value);
+    }
+
+    private static boolean validParentId(String value) {
+        return value != null && value.matches("[0-9a-f]{16}") && !ZERO_PARENT_ID.equals(value);
+    }
+
+    private static String randomNonZero(int byteCount) {
+        byte[] bytes = new byte[byteCount];
+        String value;
+        do {
+            RANDOM.nextBytes(bytes);
+            value = HEX.formatHex(bytes);
+        } while (value.chars().allMatch(character -> character == '0'));
+        return value;
+    }
+}

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

@@ -1,2 +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/CommonWebAutoConfigurationTest.java

@@ -1,6 +1,8 @@
 package com.baiyue.common.web;
 
 import org.junit.jupiter.api.Test;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
 import org.springframework.boot.autoconfigure.AutoConfigurations;
 import org.springframework.boot.test.context.runner.ApplicationContextRunner;
 
@@ -16,6 +18,8 @@ class CommonWebAutoConfigurationTest {
         contextRunner.run(context -> {
             assertThat(context).hasSingleBean(GlobalExceptionHandler.class);
             assertThat(context).hasSingleBean(CorrelationIdFilter.class);
+            assertThat(CorrelationIdFilter.class.getAnnotation(Order.class).value())
+                    .isEqualTo(Ordered.HIGHEST_PRECEDENCE);
         });
     }
 

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

@@ -6,6 +6,8 @@ import org.springframework.mock.web.MockFilterChain;
 import org.springframework.mock.web.MockHttpServletRequest;
 import org.springframework.mock.web.MockHttpServletResponse;
 
+import java.io.IOException;
+
 import static org.assertj.core.api.Assertions.assertThat;
 
 @DisplayName("请求链路标识过滤功能")
@@ -13,27 +15,87 @@ class CorrelationIdFilterTest {
     private final CorrelationIdFilter filter = new CorrelationIdFilter();
 
     @Test
-    void preservesSafeIncomingIds() throws Exception {
+    void validTraceParentWinsAndMapsToLegacyTraceIdAndMdc() throws Exception {
         MockHttpServletRequest request = new MockHttpServletRequest();
         request.addHeader(CorrelationContext.REQUEST_ID_HEADER, "req-123");
-        request.addHeader(CorrelationContext.TRACE_ID_HEADER, "trace-123");
+        request.addHeader(CorrelationContext.TRACE_ID_HEADER, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+        request.addHeader(CorrelationContext.TRACE_PARENT_HEADER,
+                "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
         MockHttpServletResponse response = new MockHttpServletResponse();
 
-        filter.doFilter(request, response, new MockFilterChain());
+        CapturingFilterChain chain = new CapturingFilterChain();
+        filter.doFilter(request, response, chain);
 
         assertThat(response.getHeader(CorrelationContext.REQUEST_ID_HEADER)).isEqualTo("req-123");
-        assertThat(request.getAttribute(CorrelationContext.TRACE_ID)).isEqualTo("trace-123");
+        assertThat(response.getHeader(CorrelationContext.TRACE_ID_HEADER))
+                .isEqualTo("4bf92f3577b34da6a3ce929d0e0e4736");
+        assertThat(response.getHeader(CorrelationContext.TRACE_PARENT_HEADER))
+                .matches("00-4bf92f3577b34da6a3ce929d0e0e4736-[0-9a-f]{16}-01");
+        assertThat(chain.traceId).isEqualTo("4bf92f3577b34da6a3ce929d0e0e4736");
+        assertThat(chain.spanId).matches("[0-9a-f]{16}").isNotEqualTo("0000000000000000");
+        assertThat(org.slf4j.MDC.get(CorrelationContext.TRACE_ID)).isNull();
+        assertThat(org.slf4j.MDC.get(CorrelationContext.SPAN_ID)).isNull();
     }
 
     @Test
-    void replacesUnsafeIncomingIds() throws Exception {
+    void fallsBackToValidLegacyTraceIdOnlyWhenTraceParentIsMissing() throws Exception {
         MockHttpServletRequest request = new MockHttpServletRequest();
-        request.addHeader(CorrelationContext.REQUEST_ID_HEADER, "invalid value\n");
+        request.addHeader(CorrelationContext.TRACE_ID_HEADER, "ABCDEF0123456789ABCDEF0123456789");
         MockHttpServletResponse response = new MockHttpServletResponse();
+
         filter.doFilter(request, response, new MockFilterChain());
+
+        assertThat(response.getHeader(CorrelationContext.TRACE_ID_HEADER))
+                .isEqualTo("abcdef0123456789abcdef0123456789");
+        assertThat(response.getHeader(CorrelationContext.TRACE_PARENT_HEADER))
+                .matches("00-abcdef0123456789abcdef0123456789-[0-9a-f]{16}-00");
+    }
+
+    @Test
+    void invalidTraceParentStartsNewTraceWithoutTrustingLegacyTraceId() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        request.addHeader(CorrelationContext.TRACE_PARENT_HEADER,
+                "00-00000000000000000000000000000000-00f067aa0ba902b7-01");
+        request.addHeader(CorrelationContext.TRACE_ID_HEADER, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        filter.doFilter(request, response, new MockFilterChain());
+
+        assertThat(response.getHeader(CorrelationContext.TRACE_ID_HEADER))
+                .matches("[0-9a-f]{32}")
+                .isNotEqualTo("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
+                .isNotEqualTo("00000000000000000000000000000000");
+    }
+
+    @Test
+    void rejectsDuplicateAndOversizedHeaders() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        request.addHeader(CorrelationContext.REQUEST_ID_HEADER, "a".repeat(129));
+        request.addHeader(CorrelationContext.TRACE_PARENT_HEADER,
+                "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
+        request.addHeader(CorrelationContext.TRACE_PARENT_HEADER,
+                "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-00");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        filter.doFilter(request, response, new MockFilterChain());
+
         assertThat(response.getHeader(CorrelationContext.REQUEST_ID_HEADER))
                 .matches("[0-9a-f-]{36}");
         assertThat(response.getHeader(CorrelationContext.TRACE_ID_HEADER))
-                .matches("[0-9a-f]{32}");
+                .matches("[0-9a-f]{32}")
+                .isNotEqualTo("4bf92f3577b34da6a3ce929d0e0e4736")
+                .isNotEqualTo("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+    }
+
+    private static final class CapturingFilterChain extends MockFilterChain {
+        private String traceId;
+        private String spanId;
+
+        @Override
+        public void doFilter(jakarta.servlet.ServletRequest request,
+                             jakarta.servlet.ServletResponse response) throws IOException {
+            traceId = org.slf4j.MDC.get(CorrelationContext.TRACE_ID);
+            spanId = org.slf4j.MDC.get(CorrelationContext.SPAN_ID);
+        }
     }
 }

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

@@ -0,0 +1,37 @@
+package com.baiyue.common.web;
+
+import feign.RequestInterceptor;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.test.context.FilteredClassLoader;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class FeignTracePropagationAutoConfigurationTest {
+    private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
+            .withConfiguration(AutoConfigurations.of(FeignTracePropagationAutoConfiguration.class));
+
+    @Test
+    void registersTraceInterceptorWhenFeignIsPresent() {
+        contextRunner.run(context -> {
+            assertThat(context).hasSingleBean(FeignTraceRequestInterceptor.class);
+            assertThat(context.getBeansOfType(RequestInterceptor.class)).hasSize(1);
+        });
+    }
+
+    @Test
+    void doesNotLoadFeignConfigurationWhenFeignIsAbsent() {
+        contextRunner.withClassLoader(new FilteredClassLoader(RequestInterceptor.class))
+                .run(context -> {
+                    assertThat(context).hasNotFailed();
+                    assertThat(context).doesNotHaveBean("feignTraceRequestInterceptor");
+                });
+    }
+
+    @Test
+    void backsOffOnlyForAnApplicationProvidedTraceInterceptor() {
+        contextRunner.withBean(FeignTraceRequestInterceptor.class, FeignTraceRequestInterceptor::new)
+                .run(context -> assertThat(context).hasSingleBean(FeignTraceRequestInterceptor.class));
+    }
+}

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

@@ -0,0 +1,80 @@
+package com.baiyue.common.web;
+
+import feign.RequestTemplate;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.slf4j.MDC;
+import org.springframework.core.Ordered;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class FeignTraceRequestInterceptorTest {
+    private final FeignTraceRequestInterceptor interceptor = new FeignTraceRequestInterceptor();
+
+    @AfterEach
+    void clearMdc() {
+        MDC.clear();
+    }
+
+    @Test
+    void runsLastSoTrustedContextHasFinalHeaderAuthority() {
+        assertThat(interceptor.getOrder()).isEqualTo(Ordered.LOWEST_PRECEDENCE);
+    }
+
+    @Test
+    void overwritesCallerHeadersFromTrustedMdcAndCreatesNewSampledSpan() {
+        MDC.put(CorrelationContext.REQUEST_ID, "req-trusted-123");
+        MDC.put(CorrelationContext.TRACE_ID, "4bf92f3577b34da6a3ce929d0e0e4736");
+        RequestTemplate template = templateWithSpoofedHeaders();
+
+        interceptor.apply(template);
+
+        assertThat(template.headers().get(CorrelationContext.REQUEST_ID_HEADER))
+                .containsExactly("req-trusted-123");
+        assertThat(template.headers().get(CorrelationContext.TRACE_ID_HEADER))
+                .containsExactly("4bf92f3577b34da6a3ce929d0e0e4736");
+        assertThat(template.headers().get(CorrelationContext.TRACE_PARENT_HEADER))
+                .singleElement().asString()
+                .matches("00-4bf92f3577b34da6a3ce929d0e0e4736-[0-9a-f]{16}-01");
+    }
+
+    @Test
+    void createsDifferentNonZeroSpanForEachSynchronousInvocation() {
+        MDC.put(CorrelationContext.TRACE_ID, "4bf92f3577b34da6a3ce929d0e0e4736");
+        RequestTemplate first = new RequestTemplate();
+        RequestTemplate second = new RequestTemplate();
+
+        interceptor.apply(first);
+        interceptor.apply(second);
+
+        assertThat(singleHeader(first, CorrelationContext.TRACE_PARENT_HEADER))
+                .isNotEqualTo(singleHeader(second, CorrelationContext.TRACE_PARENT_HEADER));
+    }
+
+    @Test
+    void stripsManagedCallerHeadersWhenTrustedContextIsMissingOrInvalid() {
+        MDC.put(CorrelationContext.REQUEST_ID, "invalid request id");
+        MDC.put(CorrelationContext.TRACE_ID, "not-a-w3c-trace-id");
+        RequestTemplate template = templateWithSpoofedHeaders();
+
+        interceptor.apply(template);
+
+        assertThat(template.headers()).doesNotContainKeys(
+                CorrelationContext.REQUEST_ID_HEADER,
+                CorrelationContext.TRACE_ID_HEADER,
+                CorrelationContext.TRACE_PARENT_HEADER);
+    }
+
+    private RequestTemplate templateWithSpoofedHeaders() {
+        RequestTemplate template = new RequestTemplate();
+        template.header(CorrelationContext.REQUEST_ID_HEADER, "req-business-parameter");
+        template.header(CorrelationContext.TRACE_ID_HEADER, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+        template.header(CorrelationContext.TRACE_PARENT_HEADER,
+                "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-00");
+        return template;
+    }
+
+    private String singleHeader(RequestTemplate template, String name) {
+        return template.headers().get(name).iterator().next();
+    }
+}

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

@@ -12,7 +12,10 @@ import org.springframework.validation.BindException;
 import org.springframework.validation.FieldError;
 import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
 import org.springframework.web.bind.MissingRequestHeaderException;
+import org.springframework.web.servlet.resource.NoResourceFoundException;
 import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
 
 import java.lang.reflect.Method;
 
@@ -87,6 +90,32 @@ class GlobalExceptionHandlerTest {
                 .tag("code", ResultCode.CONFLICT.code()).counter().count()).isEqualTo(1.0);
     }
 
+    @Test
+    void responseStatusConflictMapsToCanonicalConflictInsteadOfInternalError() {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        request.setAttribute(CorrelationContext.REQUEST_ID, "stale-version");
+
+        var response = handler.handleResponseStatus(
+                new ResponseStatusException(HttpStatus.CONFLICT, "Order was changed; refresh and retry"), request);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(200);
+        assertThat(response.getBody().code()).isEqualTo(ResultCode.CONFLICT.code());
+        assertThat(response.getBody().message()).isEqualTo("Order was changed; refresh and retry");
+        assertThat(response.getBody().requestId()).isEqualTo("stale-version");
+    }
+
+    @Test
+    void missingControllerPathMapsToNotFoundInsteadOfInternalError() {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+
+        var response = handler.handleNoResourceFound(
+                new NoResourceFoundException(org.springframework.http.HttpMethod.GET,
+                        "api/platform/v1/last-leg/dispatches"), request);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(200);
+        assertThat(response.getBody().code()).isEqualTo(ResultCode.NOT_FOUND.code());
+    }
+
     private void paging(long page) {
     }
 }

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

@@ -0,0 +1,62 @@
+package com.baiyue.common.web;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class TraceParentTest {
+
+    @Test
+    void parsesCanonicalVersion00AndCreatesLocalChild() {
+        TraceParent remote = TraceParent.parse(
+                "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01").orElseThrow();
+
+        TraceParent local = TraceParent.childOf(remote);
+
+        assertThat(local.traceId()).isEqualTo(remote.traceId());
+        assertThat(local.parentId()).matches("[0-9a-f]{16}")
+                .isNotEqualTo(remote.parentId())
+                .isNotEqualTo("0000000000000000");
+        assertThat(local.traceFlags()).isEqualTo("01");
+        assertThat(local.value()).hasSize(TraceParent.HEADER_LENGTH);
+    }
+
+    @Test
+    void rejectsNonCanonicalUnsupportedAndZeroIdentifiers() {
+        assertThat(TraceParent.parse(
+                "00-4BF92F3577B34DA6A3CE929D0E0E4736-00f067aa0ba902b7-01")).isEmpty();
+        assertThat(TraceParent.parse(
+                "01-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")).isEmpty();
+        assertThat(TraceParent.parse(
+                "00-00000000000000000000000000000000-00f067aa0ba902b7-01")).isEmpty();
+        assertThat(TraceParent.parse(
+                "00-4bf92f3577b34da6a3ce929d0e0e4736-0000000000000000-01")).isEmpty();
+        assertThat(TraceParent.parse("x".repeat(10_000))).isEmpty();
+    }
+
+    @Test
+    void createsCanonicalNonZeroRootAndNormalizesLegacyHex() {
+        TraceParent root = TraceParent.newRoot("ABCDEF0123456789ABCDEF0123456789");
+
+        assertThat(root.traceId()).isEqualTo("abcdef0123456789abcdef0123456789");
+        assertThat(root.parentId()).matches("[0-9a-f]{16}").isNotEqualTo("0000000000000000");
+        assertThat(root.value()).matches(
+                "00-abcdef0123456789abcdef0123456789-[0-9a-f]{16}-00");
+    }
+
+    @Test
+    void createsSampledOutboundChildForTrustedCurrentTrace() {
+        TraceParent child = TraceParent.outboundChild("4BF92F3577B34DA6A3CE929D0E0E4736");
+
+        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/event-bridge-service.yml

@@ -8,3 +8,6 @@ baiyue:
   region: ${REGION_CODE:CN}
   deployment-cell: ${DEPLOYMENT_CELL:prod-cn}
   data-residency: ${DATA_RESIDENCY:CN}
+  event-dispatcher:
+    consumer-url: ${EVENT_CONSUMER_URL:http://firstleg:9202/internal/firstleg/v1/container-events}
+    firstleg-consumer-url: ${FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL:http://firstleg:9202/internal/firstleg/v1/container-events}

config/nacos/cn/firstleg-service.yml

@@ -7,6 +7,28 @@ spring:
 baiyue.clients.warehouse.url: ${WAREHOUSE_SERVICE_URL:}
 baiyue.clients.order.url: ${ORDER_SERVICE_URL:}
 baiyue.clients.file.url: ${FILE_SERVICE_URL:}
+baiyue:
+  carrier-schedule:
+    providers:
+      matson-automated: ${MATSON_TRACKING_ENABLED:false}
+      sml-automated: ${SML_TRACKING_ENABLED:false}
+      zim-official-api-enabled: ${ZIM_TRACKING_ENABLED:false}
+      cosco-official-api-enabled: ${COSCO_OPEN_API_ENABLED:false}
+      emc-automated: ${EMC_TRACKING_ENABLED:false}
+      hede-automated: ${HEDE_TRACKING_ENABLED:false}
+    scheduler:
+      zone: ${CARRIER_SCHEDULE_ZONE:Asia/Shanghai}
+      scan-fixed-delay: ${CARRIER_SCHEDULE_SCAN_FIXED_DELAY:PT1M}
+      scan-initial-delay: ${CARRIER_SCHEDULE_SCAN_INITIAL_DELAY:PT10S}
+      batch-size: ${CARRIER_SCHEDULE_BATCH_SIZE:20}
+      max-tasks-per-trigger: ${CARRIER_SCHEDULE_MAX_TASKS_PER_TRIGGER:2000}
+      lease-duration: ${CARRIER_SCHEDULE_LEASE_DURATION:PT5M}
+  lastleg:
+    event-bridge-url: ${LASTLEG_EVENT_BRIDGE_URL}
+    outbox-relay:
+      fixed-delay-ms: ${LASTLEG_OUTBOX_RELAY_FIXED_DELAY_MS:5000}
+      lease-seconds: ${LASTLEG_OUTBOX_RELAY_LEASE_SECONDS:60}
+      retry-seconds: ${LASTLEG_OUTBOX_RELAY_RETRY_SECONDS:30}
 firstleg:
   inbound:
     allow-rejected-measurement: false

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/cn/integration-service.yml

@@ -21,3 +21,39 @@ baiyue:
       max-qps-retries: ${BAIDU_OCR_MAX_QPS_RETRIES:3}
     amazon-sp-api:
       enabled: ${AMAZON_SP_API_ENABLED:false}
+    carrier-schedule:
+      matson:
+        enabled: ${MATSON_TRACKING_ENABLED:false}
+        page-url: ${MATSON_TRACKING_PAGE_URL:https://www.matson.com/shipment-tracking.html}
+        query-url: ${MATSON_TRACKING_QUERY_URL:https://www.matson.com/wp-content/plugins/matson-plugin/Api_calls/tracking_booking_proxy.php}
+        connect-timeout: ${MATSON_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${MATSON_TRACKING_REQUEST_TIMEOUT:30s}
+        min-request-interval: ${MATSON_TRACKING_MIN_REQUEST_INTERVAL:5s}
+      hede:
+        enabled: ${HEDE_TRACKING_ENABLED:false}
+        query-url: ${HEDE_TRACKING_QUERY_URL:http://elines.hedehk.com/getVBilldynamic}
+        connect-timeout: ${HEDE_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${HEDE_TRACKING_REQUEST_TIMEOUT:30s}
+        min-request-interval: ${HEDE_TRACKING_MIN_REQUEST_INTERVAL:5s}
+      sml:
+        enabled: ${SML_TRACKING_ENABLED:false}
+        query-url: ${SML_TRACKING_QUERY_URL:https://esvc.smlines.com/smline/CUP_HOM_3301GS.do}
+        connect-timeout: ${SML_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${SML_TRACKING_REQUEST_TIMEOUT:30s}
+        min-request-interval: ${SML_TRACKING_MIN_REQUEST_INTERVAL:5s}
+      zim:
+        enabled: ${ZIM_TRACKING_ENABLED:false}
+        authorization-url: ${ZIM_AUTHORIZATION_URL:https://apigw.zim.com/authorize/v1}
+        tracing-base-url: ${ZIM_TRACING_BASE_URL:https://apigw.zim.com/tracing/v2}
+        client-id: ${ZIM_CLIENT_ID:}
+        client-secret: ${ZIM_CLIENT_SECRET:}
+        subscription-key: ${ZIM_TRACKING_SUBSCRIPTION_KEY:}
+        connect-timeout: ${ZIM_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${ZIM_TRACKING_REQUEST_TIMEOUT:30s}
+        max-concurrency: ${ZIM_TRACKING_MAX_CONCURRENCY:10}
+      evergreen:
+        enabled: ${EMC_TRACKING_ENABLED:false}
+        query-url: ${EMC_TRACKING_QUERY_URL:https://www.evergreen-shipping.cn/servlet/TDB1_CargoTracking.do}
+        connect-timeout: ${EMC_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${EMC_TRACKING_REQUEST_TIMEOUT:30s}
+        min-request-interval: ${EMC_TRACKING_MIN_REQUEST_INTERVAL:5s}

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/firstleg-service.yml

@@ -6,6 +6,18 @@ spring.datasource:
 baiyue.clients.warehouse.url: ${WAREHOUSE_SERVICE_URL:}
 baiyue.clients.order.url: ${ORDER_SERVICE_URL:}
 baiyue.clients.file.url: ${FILE_SERVICE_URL:}
+baiyue.carrier-schedule.providers.matson-automated: ${MATSON_TRACKING_ENABLED:false}
+baiyue.carrier-schedule.providers.sml-automated: ${SML_TRACKING_ENABLED:false}
+baiyue.carrier-schedule.providers.zim-official-api-enabled: ${ZIM_TRACKING_ENABLED:false}
+baiyue.carrier-schedule.providers.cosco-official-api-enabled: ${COSCO_OPEN_API_ENABLED:false}
+baiyue.carrier-schedule.providers.emc-automated: ${EMC_TRACKING_ENABLED:false}
+baiyue.carrier-schedule.providers.hede-automated: ${HEDE_TRACKING_ENABLED:false}
+baiyue.carrier-schedule.scheduler.zone: ${CARRIER_SCHEDULE_ZONE:Asia/Shanghai}
+baiyue.carrier-schedule.scheduler.scan-fixed-delay: ${CARRIER_SCHEDULE_SCAN_FIXED_DELAY:PT1M}
+baiyue.carrier-schedule.scheduler.scan-initial-delay: ${CARRIER_SCHEDULE_SCAN_INITIAL_DELAY:PT10S}
+baiyue.carrier-schedule.scheduler.batch-size: ${CARRIER_SCHEDULE_BATCH_SIZE:20}
+baiyue.carrier-schedule.scheduler.max-tasks-per-trigger: ${CARRIER_SCHEDULE_MAX_TASKS_PER_TRIGGER:2000}
+baiyue.carrier-schedule.scheduler.lease-duration: ${CARRIER_SCHEDULE_LEASE_DURATION:PT5M}
 firstleg:
   inbound:
     allow-rejected-measurement: false

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/integration-service.yml

@@ -15,3 +15,39 @@ baiyue:
       max-batch-size: ${WEIGHT_OCR_MAX_BATCH_SIZE:50}
     amazon-sp-api:
       enabled: ${AMAZON_SP_API_ENABLED:false}
+    carrier-schedule:
+      matson:
+        enabled: ${MATSON_TRACKING_ENABLED:false}
+        page-url: ${MATSON_TRACKING_PAGE_URL:https://www.matson.com/shipment-tracking.html}
+        query-url: ${MATSON_TRACKING_QUERY_URL:https://www.matson.com/wp-content/plugins/matson-plugin/Api_calls/tracking_booking_proxy.php}
+        connect-timeout: ${MATSON_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${MATSON_TRACKING_REQUEST_TIMEOUT:30s}
+        min-request-interval: ${MATSON_TRACKING_MIN_REQUEST_INTERVAL:5s}
+      hede:
+        enabled: ${HEDE_TRACKING_ENABLED:false}
+        query-url: ${HEDE_TRACKING_QUERY_URL:http://elines.hedehk.com/getVBilldynamic}
+        connect-timeout: ${HEDE_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${HEDE_TRACKING_REQUEST_TIMEOUT:30s}
+        min-request-interval: ${HEDE_TRACKING_MIN_REQUEST_INTERVAL:5s}
+      sml:
+        enabled: ${SML_TRACKING_ENABLED:false}
+        query-url: ${SML_TRACKING_QUERY_URL:https://esvc.smlines.com/smline/CUP_HOM_3301GS.do}
+        connect-timeout: ${SML_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${SML_TRACKING_REQUEST_TIMEOUT:30s}
+        min-request-interval: ${SML_TRACKING_MIN_REQUEST_INTERVAL:5s}
+      zim:
+        enabled: ${ZIM_TRACKING_ENABLED:false}
+        authorization-url: ${ZIM_AUTHORIZATION_URL:https://apigw.zim.com/authorize/v1}
+        tracing-base-url: ${ZIM_TRACING_BASE_URL:https://apigw.zim.com/tracing/v2}
+        client-id: ${ZIM_CLIENT_ID:}
+        client-secret: ${ZIM_CLIENT_SECRET:}
+        subscription-key: ${ZIM_TRACKING_SUBSCRIPTION_KEY:}
+        connect-timeout: ${ZIM_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${ZIM_TRACKING_REQUEST_TIMEOUT:30s}
+        max-concurrency: ${ZIM_TRACKING_MAX_CONCURRENCY:10}
+      evergreen:
+        enabled: ${EMC_TRACKING_ENABLED:false}
+        query-url: ${EMC_TRACKING_QUERY_URL:https://www.evergreen-shipping.cn/servlet/TDB1_CargoTracking.do}
+        connect-timeout: ${EMC_TRACKING_CONNECT_TIMEOUT:10s}
+        request-timeout: ${EMC_TRACKING_REQUEST_TIMEOUT:30s}
+        min-request-interval: ${EMC_TRACKING_MIN_REQUEST_INTERVAL:5s}

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/baiyue-common.yml

@@ -4,10 +4,14 @@ baiyue:
     cell: ${DEPLOYMENT_CELL:prod-overseas}
     data-residency: ${DATA_RESIDENCY:OVERSEAS}
   security:
-    issuer: ${JWT_ISSUER:https://auth.example.com}
+    issuer: ${JWT_ISSUER:auth-service}
     audience: ${JWT_AUDIENCE:lastleg-api}
-    jwk-set-uri: ${JWT_JWK_SET_URI:https://auth.example.com/.well-known/jwks.json}
+    jwk-set-uri: ${JWT_JWK_SET_URI:http://127.0.0.1:9100/api/auth/.well-known/jwks.json}
     internal-service-token: ${INTERNAL_SERVICE_TOKEN}
+    pda-session-validation:
+      auth-url: ${AUTH_SESSION_VALIDATION_URL}
+      internal-service-token: ${INTERNAL_SERVICE_TOKEN}
+      timeout: ${PDA_SESSION_VALIDATION_TIMEOUT:2s}
     permission-snapshot-key-prefix: ${PERMISSION_SNAPSHOT_KEY_PREFIX:baiyue:permission-snapshot}
   openapi.enabled: ${SWAGGER_ENABLED:false}
   audit.enabled: true

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

@@ -9,7 +9,8 @@ baiyue:
   deployment-cell: ${DEPLOYMENT_CELL:prod-overseas}
   data-residency: ${DATA_RESIDENCY:OVERSEAS}
   event-dispatcher:
-    consumer-url: ${LASTLEG_CONSUMER_URL:http://lastleg-service:9303/internal/lastleg/events}
+    consumer-url: ${EVENT_CONSUMER_URL:http://lastleg-service:9303/internal/lastleg/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

@@ -1,3 +1,9 @@
 springdoc:
   api-docs.enabled: ${SWAGGER_ENABLED:false}
   swagger-ui.enabled: ${SWAGGER_ENABLED:false}
+baiyue:
+  security:
+    overseas-projection:
+      service-url: ${LASTLEG_SECURITY_SERVICE_URL:http://lastleg-service:9303}
+      internal-service-token: ${INTERNAL_SERVICE_TOKEN}
+      timeout: ${LASTLEG_SECURITY_VALIDATION_TIMEOUT:2s}

config/nacos/overseas/lastleg-service.yml

@@ -4,3 +4,39 @@ spring:
     username: ${LASTLEG_DB_USERNAME}
     password: ${LASTLEG_DB_PASSWORD}
     driver-class-name: com.mysql.cj.jdbc.Driver
+lastleg:
+  dispatch-query-api:
+    enabled: true
+  smart-dispatch-api:
+    enabled: true
+baiyue:
+  http:
+    clients:
+      unload-photo-file:
+        connect-timeout: ${LASTLEG_UNLOAD_PHOTO_FILE_CONNECT_TIMEOUT:3s}
+        read-timeout: ${LASTLEG_UNLOAD_PHOTO_FILE_READ_TIMEOUT:30s}
+      relabel-photo-file:
+        connect-timeout: ${LASTLEG_RELABEL_PHOTO_FILE_CONNECT_TIMEOUT:3s}
+        read-timeout: ${LASTLEG_RELABEL_PHOTO_FILE_READ_TIMEOUT:30s}
+      warehouse-resource:
+        connect-timeout: ${LASTLEG_WAREHOUSE_RESOURCE_CONNECT_TIMEOUT:3s}
+        read-timeout: ${LASTLEG_WAREHOUSE_RESOURCE_READ_TIMEOUT:5s}
+      pallet-physical:
+        connect-timeout: ${LASTLEG_PALLET_PHYSICAL_CONNECT_TIMEOUT:3s}
+        read-timeout: ${LASTLEG_PALLET_PHYSICAL_READ_TIMEOUT:5s}
+  clients:
+    domestic-warehouse:
+      url: ${DOMESTIC_WAREHOUSE_URL}
+      cache-ttl: ${DOMESTIC_WAREHOUSE_CACHE_TTL:30m}
+    file:
+      url: ${FILE_SERVICE_URL}
+    event-bridge:
+      url: ${CN_EVENT_BRIDGE_URL:${FIRSTLEG_EVENT_BRIDGE_URL}}
+  warehouse:
+    base-url: ${WAREHOUSE_OVERSEAS_SERVICE_URL:http://warehouse-overseas-service:9305}
+  firstleg:
+    event-bridge-url: ${CN_EVENT_BRIDGE_URL:${FIRSTLEG_EVENT_BRIDGE_URL}}
+    outbox-relay:
+      fixed-delay-ms: ${FIRSTLEG_OUTBOX_RELAY_FIXED_DELAY_MS:5000}
+      lease-seconds: ${FIRSTLEG_OUTBOX_RELAY_LEASE_SECONDS:60}
+      retry-seconds: ${FIRSTLEG_OUTBOX_RELAY_RETRY_SECONDS:30}

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/.env.overseas-auth.example

@@ -0,0 +1,12 @@
+# Auth signs short-lived overseas RS256 tokens with a private JWK Set.
+OVERSEAS_JWT_ENABLED=true
+OVERSEAS_JWT_ISSUER=auth-service
+OVERSEAS_JWT_AUDIENCE=lastleg-api
+OVERSEAS_JWT_CURRENT_KID=replace-with-current-signing-kid
+OVERSEAS_ACCESS_TOKEN_TTL=15m
+OVERSEAS_JWT_RSA_JWK_SET={"keys":[{"kty":"RSA","kid":"replace-with-current-signing-kid","use":"sig","alg":"RS256","n":"replace-with-modulus","e":"AQAB","d":"replace-with-private-exponent","p":"replace","q":"replace","dp":"replace","dq":"replace","qi":"replace"}]}
+
+# Overseas services validate tokens against Auth's public JWKS endpoint.
+JWT_JWK_SET_URI=https://replace-with-auth-host/api/auth/.well-known/jwks.json
+JWT_ISSUER=auth-service
+JWT_AUDIENCE=lastleg-api

deploy/docker-compose.overseas.yml

@@ -0,0 +1,109 @@
+name: firstleg-${DEPLOY_ENV:-test}-overseas
+
+x-overseas-common: &overseas-common
+  restart: unless-stopped
+  networks: [firstleg-overseas-network, infra-network]
+  extra_hosts:
+    - "host.docker.internal:host-gateway"
+  environment: &overseas-environment
+    SPRING_PROFILES_ACTIVE: overseas
+    NACOS_SERVER_ADDR: ${NACOS_SERVER_ADDR}
+    NACOS_USERNAME: ${NACOS_USERNAME}
+    NACOS_PASSWORD: ${NACOS_PASSWORD}
+    NACOS_GROUP: ${NACOS_GROUP:-BAIYUE}
+    NACOS_NAMESPACE: ${OVERSEAS_NACOS_NAMESPACE:-prod-overseas}
+    REDIS_HOST: ${OVERSEAS_REDIS_HOST:-host.docker.internal}
+    REDIS_PORT: ${OVERSEAS_REDIS_PORT:-6379}
+    REDIS_PASSWORD: ${OVERSEAS_REDIS_PASSWORD:-}
+    REDIS_DATABASE: ${OVERSEAS_REDIS_DATABASE:-0}
+    INTERNAL_SERVICE_TOKEN: ${INTERNAL_SERVICE_TOKEN}
+    JWT_ISSUER: ${JWT_ISSUER}
+    JWT_AUDIENCE: ${OVERSEAS_JWT_AUDIENCE:-lastleg-api}
+    JWT_JWK_SET_URI: ${JWT_JWK_SET_URI}
+    REGION_CODE: OVERSEAS
+    DEPLOYMENT_CELL: ${OVERSEAS_DEPLOYMENT_CELL:-test-overseas}
+    DATA_RESIDENCY: OVERSEAS
+    SPRING_SQL_INIT_MODE: never
+    LOG_PATH: /app/logs
+    TZ: Asia/Shanghai
+  logging:
+    driver: json-file
+    options:
+      max-size: 100m
+      max-file: "5"
+
+services:
+  gateway-overseas:
+    <<: *overseas-common
+    image: ${IMAGE_REPOSITORY}/gateway-overseas:${IMAGE_TAG}
+    container_name: firstleg-${DEPLOY_ENV:-test}-gateway-overseas
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${GATEWAY_OVERSEAS_PORT:-9300}:9300"]
+    volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/gateway-overseas:/app/logs"]
+    environment:
+      <<: *overseas-environment
+      SERVER_PORT: 9300
+      SWAGGER_ENABLED: ${SWAGGER_ENABLED:-false}
+      CORS_ALLOWED_ORIGINS: ${OVERSEAS_CORS_ALLOWED_ORIGINS:-}
+      CORS_ALLOW_CREDENTIALS: ${CORS_ALLOW_CREDENTIALS:-false}
+      AUTH_SESSION_VALIDATION_URL: ${AUTH_SESSION_VALIDATION_URL}
+      PDA_SESSION_VALIDATION_TIMEOUT: ${PDA_SESSION_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
+    image: ${IMAGE_REPOSITORY}/lastleg-service:${IMAGE_TAG}
+    container_name: firstleg-${DEPLOY_ENV:-test}-lastleg
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${LASTLEG_PORT:-9303}:9303"]
+    volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/lastleg-service:/app/logs"]
+    environment:
+      <<: *overseas-environment
+      SERVER_PORT: 9303
+      LASTLEG_DB_URL: ${LASTLEG_DB_URL}
+      LASTLEG_DB_USERNAME: ${LASTLEG_DB_USERNAME}
+      LASTLEG_DB_PASSWORD: ${LASTLEG_DB_PASSWORD}
+      CN_EVENT_BRIDGE_URL: ${CN_EVENT_BRIDGE_TARGET_URL:-http://event-bridge-cn:9312}
+      FIRSTLEG_EVENT_BRIDGE_URL: ${CN_EVENT_BRIDGE_TARGET_URL:-http://event-bridge-cn:9312}
+      DOMESTIC_WAREHOUSE_URL: ${DOMESTIC_WAREHOUSE_URL}
+      FILE_SERVICE_URL: ${FILE_SERVICE_URL}
+      WAREHOUSE_OVERSEAS_SERVICE_URL: ${WAREHOUSE_OVERSEAS_SERVICE_URL:-http://warehouse-overseas-service:9305}
+
+  warehouse-overseas-service:
+    <<: *overseas-common
+    image: ${IMAGE_REPOSITORY}/warehouse-overseas-service:${IMAGE_TAG}
+    container_name: firstleg-${DEPLOY_ENV:-test}-warehouse-overseas
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${WAREHOUSE_OVERSEAS_PORT:-9305}:9305"]
+    volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/warehouse-overseas-service:/app/logs"]
+    environment:
+      <<: *overseas-environment
+      SERVER_PORT: 9305
+      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
+    image: ${IMAGE_REPOSITORY}/event-bridge-service:${IMAGE_TAG}
+    container_name: firstleg-${DEPLOY_ENV:-test}-event-bridge-overseas
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${EVENT_BRIDGE_OVERSEAS_PORT:-9313}:9312"]
+    volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/event-bridge-service-overseas:/app/logs"]
+    environment:
+      <<: *overseas-environment
+      SERVER_PORT: 9312
+      EVENT_BRIDGE_DB_URL: ${EVENT_BRIDGE_OVERSEAS_DB_URL}
+      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}
+      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]
+
+networks:
+  firstleg-overseas-network:
+    name: firstleg-${DEPLOY_ENV:-test}-overseas-network
+  infra-network:
+    external: true
+    name: ${INFRA_NETWORK:-firstleg-test-infra-network}

deploy/docker-compose.yml

@@ -39,7 +39,7 @@ services:
     <<: *common
     image: ${IMAGE_REPOSITORY}/gateway:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-gateway
-    ports: ["${GATEWAY_PORT:-9000}:9000"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${GATEWAY_PORT:-9000}:9000"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/gateway:/app/logs"]
     environment:
       <<: *common-environment
@@ -52,7 +52,7 @@ services:
     <<: *common
     image: ${IMAGE_REPOSITORY}/auth:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-auth
-    ports: ["${AUTH_PORT:-9100}:9100"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${AUTH_PORT:-9100}:9100"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/auth:/app/logs"]
     environment:
       <<: *common-environment
@@ -60,12 +60,18 @@ services:
       AUTH_DB_URL: ${AUTH_DB_URL}
       AUTH_DB_USERNAME: ${AUTH_DB_USERNAME}
       AUTH_DB_PASSWORD: ${AUTH_DB_PASSWORD}
+      OVERSEAS_JWT_ENABLED: ${OVERSEAS_JWT_ENABLED:-false}
+      OVERSEAS_JWT_ISSUER: ${OVERSEAS_JWT_ISSUER:-auth-service}
+      OVERSEAS_JWT_AUDIENCE: ${OVERSEAS_JWT_AUDIENCE:-lastleg-api}
+      OVERSEAS_JWT_RSA_JWK_SET: ${OVERSEAS_JWT_RSA_JWK_SET:-}
+      OVERSEAS_JWT_CURRENT_KID: ${OVERSEAS_JWT_CURRENT_KID:-}
+      OVERSEAS_ACCESS_TOKEN_TTL: ${OVERSEAS_ACCESS_TOKEN_TTL:-15m}
 
   iam:
     <<: *common
     image: ${IMAGE_REPOSITORY}/iam:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-iam
-    ports: ["${IAM_PORT:-9201}:9201"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${IAM_PORT:-9201}:9201"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/iam:/app/logs"]
     environment:
       <<: *common-environment
@@ -73,12 +79,13 @@ 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
     image: ${IMAGE_REPOSITORY}/firstleg:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-business
-    ports: ["${FIRSTLEG_PORT:-9202}:9202"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${FIRSTLEG_PORT:-9202}:9202"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/firstleg:/app/logs"]
     environment:
       <<: *common-environment
@@ -86,12 +93,25 @@ services:
       FIRSTLEG_DB_URL: ${FIRSTLEG_DB_URL}
       FIRSTLEG_DB_USERNAME: ${FIRSTLEG_DB_USERNAME}
       FIRSTLEG_DB_PASSWORD: ${FIRSTLEG_DB_PASSWORD}
+      LASTLEG_EVENT_BRIDGE_URL: ${LASTLEG_EVENT_BRIDGE_URL}
+      MATSON_TRACKING_ENABLED: ${MATSON_TRACKING_ENABLED:-false}
+      SML_TRACKING_ENABLED: ${SML_TRACKING_ENABLED:-false}
+      ZIM_TRACKING_ENABLED: ${ZIM_TRACKING_ENABLED:-false}
+      COSCO_OPEN_API_ENABLED: ${COSCO_OPEN_API_ENABLED:-false}
+      EMC_TRACKING_ENABLED: ${EMC_TRACKING_ENABLED:-false}
+      HEDE_TRACKING_ENABLED: ${HEDE_TRACKING_ENABLED:-false}
+      CARRIER_SCHEDULE_ZONE: ${CARRIER_SCHEDULE_ZONE:-Asia/Shanghai}
+      CARRIER_SCHEDULE_SCAN_FIXED_DELAY: ${CARRIER_SCHEDULE_SCAN_FIXED_DELAY:-PT1M}
+      CARRIER_SCHEDULE_SCAN_INITIAL_DELAY: ${CARRIER_SCHEDULE_SCAN_INITIAL_DELAY:-PT10S}
+      CARRIER_SCHEDULE_BATCH_SIZE: ${CARRIER_SCHEDULE_BATCH_SIZE:-20}
+      CARRIER_SCHEDULE_MAX_TASKS_PER_TRIGGER: ${CARRIER_SCHEDULE_MAX_TASKS_PER_TRIGGER:-2000}
+      CARRIER_SCHEDULE_LEASE_DURATION: ${CARRIER_SCHEDULE_LEASE_DURATION:-PT5M}
 
   finance:
     <<: *common
     image: ${IMAGE_REPOSITORY}/finance:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-finance
-    ports: ["${FINANCE_PORT:-9203}:9203"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${FINANCE_PORT:-9203}:9203"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/finance:/app/logs"]
     environment:
       <<: *common-environment
@@ -104,7 +124,7 @@ services:
     <<: *common
     image: ${IMAGE_REPOSITORY}/order:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-order
-    ports: ["${ORDER_PORT:-9204}:9204"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${ORDER_PORT:-9204}:9204"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/order:/app/logs"]
     environment:
       <<: *common-environment
@@ -117,7 +137,7 @@ services:
     <<: *common
     image: ${IMAGE_REPOSITORY}/warehouse:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-warehouse
-    ports: ["${WAREHOUSE_PORT:-9205}:9205"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${WAREHOUSE_PORT:-9205}:9205"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/warehouse:/app/logs"]
     environment:
       <<: *common-environment
@@ -130,7 +150,7 @@ services:
     <<: *common
     image: ${IMAGE_REPOSITORY}/file:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-file
-    ports: ["${FILE_PORT:-9206}:9206"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${FILE_PORT:-9206}:9206"]
     volumes:
       - "${FILE_UPLOADS_HOST_DIR:-/data/firstleg/uploads}:/data/files"
       - "${LOG_ROOT:-/data/logs/baiyue-firstleg}/file:/app/logs"
@@ -154,7 +174,7 @@ services:
     <<: *common
     image: ${IMAGE_REPOSITORY}/print:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-print
-    ports: ["${PRINT_PORT:-9207}:9207"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${PRINT_PORT:-9207}:9207"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/print:/app/logs"]
     environment:
       <<: *common-environment
@@ -165,7 +185,7 @@ services:
     <<: *common
     image: ${IMAGE_REPOSITORY}/integration-service:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-integration
-    ports: ["${INTEGRATION_PORT:-9210}:9210"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${INTEGRATION_PORT:-9210}:9210"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/integration-service:/app/logs"]
     environment:
       <<: *common-environment
@@ -180,19 +200,56 @@ services:
       AMAZON_SP_API_AWS_ACCESS_KEY: ${AMAZON_SP_API_AWS_ACCESS_KEY:-}
       AMAZON_SP_API_AWS_SECRET_KEY: ${AMAZON_SP_API_AWS_SECRET_KEY:-}
       AMAZON_SP_API_REGION: ${AMAZON_SP_API_REGION:-}
+      MATSON_TRACKING_ENABLED: ${MATSON_TRACKING_ENABLED:-false}
+      MATSON_TRACKING_PAGE_URL: ${MATSON_TRACKING_PAGE_URL:-https://www.matson.com/shipment-tracking.html}
+      MATSON_TRACKING_QUERY_URL: ${MATSON_TRACKING_QUERY_URL:-https://www.matson.com/wp-content/plugins/matson-plugin/Api_calls/tracking_booking_proxy.php}
+      MATSON_TRACKING_CONNECT_TIMEOUT: ${MATSON_TRACKING_CONNECT_TIMEOUT:-10s}
+      MATSON_TRACKING_REQUEST_TIMEOUT: ${MATSON_TRACKING_REQUEST_TIMEOUT:-30s}
+      MATSON_TRACKING_MIN_REQUEST_INTERVAL: ${MATSON_TRACKING_MIN_REQUEST_INTERVAL:-5s}
+      SML_TRACKING_ENABLED: ${SML_TRACKING_ENABLED:-false}
+      SML_TRACKING_QUERY_URL: ${SML_TRACKING_QUERY_URL:-https://esvc.smlines.com/smline/CUP_HOM_3301GS.do}
+      SML_TRACKING_CONNECT_TIMEOUT: ${SML_TRACKING_CONNECT_TIMEOUT:-10s}
+      SML_TRACKING_REQUEST_TIMEOUT: ${SML_TRACKING_REQUEST_TIMEOUT:-30s}
+      SML_TRACKING_MIN_REQUEST_INTERVAL: ${SML_TRACKING_MIN_REQUEST_INTERVAL:-5s}
+      ZIM_TRACKING_ENABLED: ${ZIM_TRACKING_ENABLED:-false}
+      ZIM_AUTHORIZATION_URL: ${ZIM_AUTHORIZATION_URL:-https://apigw.zim.com/authorize/v1}
+      ZIM_TRACING_BASE_URL: ${ZIM_TRACING_BASE_URL:-https://apigw.zim.com/tracing/v2}
+      ZIM_CLIENT_ID: ${ZIM_CLIENT_ID:-}
+      ZIM_CLIENT_SECRET: ${ZIM_CLIENT_SECRET:-}
+      ZIM_TRACKING_SUBSCRIPTION_KEY: ${ZIM_TRACKING_SUBSCRIPTION_KEY:-}
+      ZIM_TRACKING_CONNECT_TIMEOUT: ${ZIM_TRACKING_CONNECT_TIMEOUT:-10s}
+      ZIM_TRACKING_REQUEST_TIMEOUT: ${ZIM_TRACKING_REQUEST_TIMEOUT:-30s}
+      ZIM_TRACKING_MAX_CONCURRENCY: ${ZIM_TRACKING_MAX_CONCURRENCY:-10}
+      EMC_TRACKING_ENABLED: ${EMC_TRACKING_ENABLED:-false}
+      EMC_TRACKING_QUERY_URL: ${EMC_TRACKING_QUERY_URL:-https://www.evergreen-shipping.cn/servlet/TDB1_CargoTracking.do}
+      EMC_TRACKING_CONNECT_TIMEOUT: ${EMC_TRACKING_CONNECT_TIMEOUT:-10s}
+      EMC_TRACKING_REQUEST_TIMEOUT: ${EMC_TRACKING_REQUEST_TIMEOUT:-30s}
+      EMC_TRACKING_MIN_REQUEST_INTERVAL: ${EMC_TRACKING_MIN_REQUEST_INTERVAL:-5s}
+      HEDE_TRACKING_ENABLED: ${HEDE_TRACKING_ENABLED:-false}
+      HEDE_TRACKING_QUERY_URL: ${HEDE_TRACKING_QUERY_URL:-http://elines.hedehk.com/getVBilldynamic}
+      HEDE_TRACKING_CONNECT_TIMEOUT: ${HEDE_TRACKING_CONNECT_TIMEOUT:-10s}
+      HEDE_TRACKING_REQUEST_TIMEOUT: ${HEDE_TRACKING_REQUEST_TIMEOUT:-30s}
+      HEDE_TRACKING_MIN_REQUEST_INTERVAL: ${HEDE_TRACKING_MIN_REQUEST_INTERVAL:-5s}
 
   event-bridge-service:
     <<: *common
     image: ${IMAGE_REPOSITORY}/event-bridge-service:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-event-bridge
-    ports: ["${EVENT_BRIDGE_PORT:-9300}:9300"]
+    ports: ["${PUBLISHED_BIND_ADDRESS:-0.0.0.0}:${EVENT_BRIDGE_PORT:-9312}:9312"]
     volumes: ["${LOG_ROOT:-/data/logs/baiyue-firstleg}/event-bridge-service:/app/logs"]
     environment:
       <<: *common-environment
-      SERVER_PORT: 9300
+      SERVER_PORT: 9312
       EVENT_BRIDGE_DB_URL: ${EVENT_BRIDGE_DB_URL}
       EVENT_BRIDGE_DB_USERNAME: ${EVENT_BRIDGE_DB_USERNAME}
       EVENT_BRIDGE_DB_PASSWORD: ${EVENT_BRIDGE_DB_PASSWORD}
+      EVENT_CONSUMER_URL: ${FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL:-http://firstleg:9202/internal/firstleg/v1/container-events}
+      FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL: ${FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL:-http://firstleg:9202/internal/firstleg/v1/container-events}
+      SPRING_SQL_INIT_MODE: never
+    networks:
+      firstleg-network:
+      infra-network:
+        aliases: [event-bridge-cn]
 
   audit-service:
     <<: *common

deploy/docker/Dockerfile

@@ -1,4 +1,12 @@
-ARG BASE_IMAGE=docker.m.daocloud.io/library/eclipse-temurin:17-jre-alpine
+ARG BASE_IMAGE=172.31.198.7:10082/java-project/eclipse-temurin:17-jre-alpine
+FROM ${BASE_IMAGE} AS extractor
+
+WORKDIR /workspace
+
+ARG JAR_FILE
+COPY ${JAR_FILE} app.jar
+RUN java -Djarmode=layertools -jar app.jar extract
+
 FROM ${BASE_IMAGE}
 
 RUN addgroup -S app \
@@ -9,8 +17,11 @@ WORKDIR /app
 # 预建镜像内运行时数据和日志目录并归属 app 用户；宿主机 bind mount 的属主需在部署前单独设置为 UID 10001。
 RUN mkdir -p /data/files /app/logs && chown -R app:app /data /app/logs
 
-ARG JAR_FILE
-COPY --chown=app:app ${JAR_FILE} /app/app.jar
+# 依赖层稳定、业务代码层高频变化；Registry 只需传输实际变化的 Layer。
+COPY --from=extractor --chown=app:app /workspace/dependencies/ ./
+COPY --from=extractor --chown=app:app /workspace/spring-boot-loader/ ./
+COPY --from=extractor --chown=app:app /workspace/snapshot-dependencies/ ./
+COPY --from=extractor --chown=app:app /workspace/application/ ./
 
 USER app
 
@@ -22,4 +33,4 @@ EXPOSE 8080
 HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
     CMD busybox wget -q -O /dev/null "http://127.0.0.1:${SERVER_PORT}/actuator/health" || exit 1
 
-ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]
+ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS org.springframework.boot.loader.launch.JarLauncher"]

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

@@ -13,7 +13,20 @@ SERVICE="$4"
 ENV_FILE="$5"
 COMPOSE_FILE="deploy/docker-compose.yml"
 IMAGE="$IMAGE_REPOSITORY/$SERVICE:$IMAGE_TAG"
+REGISTRY_HOST="${IMAGE_REPOSITORY%%/*}"
 PROJECT_NAME="firstleg-$DEPLOY_ENV"
+HEALTH_TIMEOUT_SECONDS="${DEPLOY_HEALTH_TIMEOUT_SECONDS:-240}"
+HEALTH_POLL_SECONDS="${DEPLOY_HEALTH_POLL_SECONDS:-5}"
+
+for value_name in HEALTH_TIMEOUT_SECONDS HEALTH_POLL_SECONDS; do
+  eval "value=\${$value_name}"
+  case "$value" in
+    ''|*[!0-9]*|0)
+      echo "$value_name 必须为正整数，当前: $value" >&2
+      exit 2
+      ;;
+  esac
+done
 
 case "$DEPLOY_ENV" in
   development|test) ;;
@@ -23,6 +36,13 @@ case "$DEPLOY_ENV" in
     ;;
 esac
 
+if [ "$DEPLOY_ENV" = "development" ]; then
+  PUBLISHED_BIND_ADDRESS=127.0.0.1
+else
+  PUBLISHED_BIND_ADDRESS="${PUBLISHED_BIND_ADDRESS:-0.0.0.0}"
+fi
+export PUBLISHED_BIND_ADDRESS
+
 case "$SERVICE" in
   *[!A-Za-z0-9_-]*|'')
     echo "非法服务名: $SERVICE" >&2
@@ -30,12 +50,10 @@ case "$SERVICE" in
     ;;
 esac
 
-for file in "$ENV_FILE" "$COMPOSE_FILE"; do
-  if [ ! -f "$file" ]; then
-    echo "必需文件不存在: $file" >&2
-    exit 2
-  fi
-done
+if [ ! -f "$ENV_FILE" ]; then
+  echo "必需文件不存在: $ENV_FILE" >&2
+  exit 2
+fi
 
 env_file_has_key() {
   grep -q "^$1=" "$ENV_FILE"
@@ -45,6 +63,48 @@ env_file_value() {
   sed -n "s/^$1=//p" "$ENV_FILE" | tail -n 1 | tr -d '\r'
 }
 
+case "$SERVICE" in
+  gateway-overseas|lastleg-service|warehouse-overseas-service)
+    COMPOSE_FILE="deploy/docker-compose.overseas.yml"
+    PROJECT_NAME="firstleg-$DEPLOY_ENV-overseas"
+    ;;
+  event-bridge-service)
+    BRIDGE_REGION="${EVENT_BRIDGE_REGION_OVERRIDE:-}"
+    if [ -z "$BRIDGE_REGION" ] && env_file_has_key REGION_CODE; then
+      BRIDGE_REGION="$(env_file_value REGION_CODE)"
+    fi
+    if [ -z "$BRIDGE_REGION" ]; then
+      echo "部署 event-bridge-service 时，环境文件必须显式包含 REGION_CODE=CN 或 REGION_CODE=OVERSEAS" >&2
+      exit 2
+    fi
+    case "$BRIDGE_REGION" in
+      CN) ;;
+      OVERSEAS)
+        COMPOSE_FILE="deploy/docker-compose.overseas.yml"
+        PROJECT_NAME="firstleg-$DEPLOY_ENV-overseas"
+        ;;
+      *)
+        echo "部署 event-bridge-service 时，REGION_CODE 只能为 CN 或 OVERSEAS" >&2
+        exit 2
+        ;;
+    esac
+    ;;
+esac
+
+if [ "$SERVICE" = "gateway-overseas" ]; then
+  if ! env_file_has_key AUTH_SESSION_VALIDATION_URL || [ -z "$(env_file_value AUTH_SESSION_VALIDATION_URL)" ]; then
+    echo "部署 gateway-overseas 时，环境文件必须包含非空 AUTH_SESSION_VALIDATION_URL" >&2
+    exit 2
+  fi
+fi
+
+for file in "$ENV_FILE" "$COMPOSE_FILE"; do
+  if [ ! -f "$file" ]; then
+    echo "必需文件不存在: $file" >&2
+    exit 2
+  fi
+done
+
 if [ "$SERVICE" = "finance" ]; then
   for key in FINANCE_DB_URL FINANCE_DB_USERNAME FINANCE_DB_PASSWORD; do
     if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
@@ -54,6 +114,56 @@ if [ "$SERVICE" = "finance" ]; then
   done
 fi
 
+case "$SERVICE" in
+  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
+        exit 2
+      fi
+    done
+    ;;
+esac
+
+if [ "$SERVICE" = "firstleg" ]; then
+  if ! env_file_has_key LASTLEG_EVENT_BRIDGE_URL || [ -z "$(env_file_value LASTLEG_EVENT_BRIDGE_URL)" ]; then
+    echo "部署 firstleg 时，环境文件必须包含非空 LASTLEG_EVENT_BRIDGE_URL" >&2
+    exit 2
+  fi
+fi
+
+if [ "$SERVICE" = "lastleg-service" ]; then
+  for key in LASTLEG_DB_URL LASTLEG_DB_USERNAME LASTLEG_DB_PASSWORD FIRSTLEG_EVENT_BRIDGE_URL DOMESTIC_WAREHOUSE_URL; do
+    if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
+      echo "部署 lastleg-service 时，环境文件必须包含非空 $key" >&2
+      exit 2
+    fi
+  done
+fi
+
+if [ "$SERVICE" = "warehouse-overseas-service" ]; then
+  for key in WAREHOUSE_OVERSEAS_DB_URL WAREHOUSE_OVERSEAS_DB_USERNAME WAREHOUSE_OVERSEAS_DB_PASSWORD; do
+    if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
+      echo "部署 warehouse-overseas-service 时，环境文件必须包含非空 $key" >&2
+      exit 2
+    fi
+  done
+fi
+
+if [ "$SERVICE" = "event-bridge-service" ]; then
+  if [ "$PROJECT_NAME" = "firstleg-$DEPLOY_ENV-overseas" ]; then
+    EVENT_BRIDGE_KEYS="EVENT_BRIDGE_OVERSEAS_DB_URL EVENT_BRIDGE_OVERSEAS_DB_USERNAME EVENT_BRIDGE_OVERSEAS_DB_PASSWORD EVENT_CONSUMER_URL"
+  else
+    EVENT_BRIDGE_KEYS="EVENT_BRIDGE_DB_URL EVENT_BRIDGE_DB_USERNAME EVENT_BRIDGE_DB_PASSWORD FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL"
+  fi
+  for key in $EVENT_BRIDGE_KEYS; do
+    if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
+      echo "部署 event-bridge-service 时，环境文件必须包含非空 $key" >&2
+      exit 2
+    fi
+  done
+fi
+
 if [ "$SERVICE" = "file" ]; then
   if ! env_file_has_key ROCKETMQ_NAME_SERVER || [ -z "$(env_file_value ROCKETMQ_NAME_SERVER)" ]; then
     echo "部署 file 服务时，环境文件必须包含非空 ROCKETMQ_NAME_SERVER" >&2
@@ -74,20 +184,156 @@ if [ "$SERVICE" = "file" ]; then
   fi
 fi
 
-docker image inspect "$IMAGE" >/dev/null
+: "${REGISTRY_USER:?REGISTRY_USER 未设置}"
+: "${REGISTRY_PASSWORD:?REGISTRY_PASSWORD 未设置}"
+
+local_registry_logout() {
+  docker logout "$REGISTRY_HOST" >/dev/null 2>&1 || true
+}
+
+local_compose() {
+  docker compose \
+    --project-name "$PROJECT_NAME" \
+    --env-file "$ENV_FILE" \
+    -f "$COMPOSE_FILE" \
+    "$@"
+}
+
+local_container_id() {
+  local_compose ps --all --quiet "$SERVICE" | head -n 1
+}
+
+local_container_image() {
+  container_id="$(local_container_id)"
+  if [ -n "$container_id" ]; then
+    docker inspect --format '{{.Config.Image}}' "$container_id"
+  fi
+}
+
+local_health_state() {
+  container_id="$(local_container_id)"
+  if [ -z "$container_id" ]; then
+    echo missing
+    return
+  fi
+  docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}no-health:{{.State.Status}}{{end}}' "$container_id" 2>/dev/null || echo missing
+}
+
+local_runtime_state() {
+  container_id="$(local_container_id)"
+  if [ -z "$container_id" ]; then
+    echo missing
+    return
+  fi
+  docker inspect --format '{{.State.Status}}' "$container_id" 2>/dev/null || echo missing
+}
+
+wait_for_local_health() {
+  elapsed=0
+  while [ "$elapsed" -lt "$HEALTH_TIMEOUT_SECONDS" ]; do
+    runtime_state="$(local_runtime_state)"
+    health_state="$(local_health_state)"
+    echo "容器运行状态: $runtime_state，健康状态: $health_state（已等待 ${elapsed}s）"
+    case "$runtime_state" in
+      restarting|exited|dead)
+        echo "容器未保持运行，立即停止等待: $runtime_state" >&2
+        return 1
+        ;;
+    esac
+    case "$health_state" in
+      healthy)
+        return 0
+        ;;
+      no-health:running)
+        echo "容器未配置 HEALTHCHECK，以运行状态作为成功依据" >&2
+        return 0
+        ;;
+      unhealthy|no-health:exited|no-health:dead)
+        return 1
+        ;;
+    esac
+    sleep "$HEALTH_POLL_SECONDS"
+    elapsed=$((elapsed + HEALTH_POLL_SECONDS))
+  done
+  echo "等待容器健康超时: ${HEALTH_TIMEOUT_SECONDS}s" >&2
+  return 1
+}
 
 deploy_local() {
+  printf '%s' "$REGISTRY_PASSWORD" | docker login -u "$REGISTRY_USER" --password-stdin "$REGISTRY_HOST"
+  trap local_registry_logout EXIT HUP INT TERM
+  previous_image="$(local_container_image || true)"
+  if [ -n "$previous_image" ]; then
+    echo "部署前运行镜像: $previous_image"
+  else
+    echo "首次部署，未发现可回滚的旧镜像"
+  fi
+  docker pull "$IMAGE"
   export DEPLOY_ENV IMAGE_REPOSITORY IMAGE_TAG
-  docker compose \
-    --project-name "$PROJECT_NAME" \
-    --env-file "$ENV_FILE" \
-    -f "$COMPOSE_FILE" \
-    up -d --remove-orphans --pull never "$SERVICE"
-  docker compose \
-    --project-name "$PROJECT_NAME" \
-    --env-file "$ENV_FILE" \
-    -f "$COMPOSE_FILE" \
-    ps "$SERVICE"
+  new_started=true
+  if ! local_compose up -d --no-deps --pull never "$SERVICE"; then
+    echo "新镜像启动命令失败: $IMAGE" >&2
+    new_started=false
+  fi
+  if [ "$new_started" = "true" ] && wait_for_local_health; then
+    running_image="$(local_container_image || true)"
+    if [ "$running_image" != "$IMAGE" ]; then
+      echo "运行容器镜像与请求镜像不一致: expected=$IMAGE actual=${running_image:-missing}" >&2
+      return 1
+    fi
+    echo "新镜像健康检查通过: $IMAGE"
+    local_compose ps "$SERVICE"
+    local_registry_logout
+    trap - EXIT HUP INT TERM
+    return 0
+  fi
+
+  echo "新镜像健康检查失败: $IMAGE" >&2
+  failed_container_id="$(local_container_id || true)"
+  if [ -n "$failed_container_id" ]; then
+    echo "新镜像容器最近日志（最多 200 行）:" >&2
+    docker logs --tail 200 "$failed_container_id" 2>&1 || true
+  else
+    echo "新镜像容器不存在，无法读取启动日志" >&2
+  fi
+  expected_prefix="$IMAGE_REPOSITORY/$SERVICE:"
+  case "$previous_image" in
+    "$expected_prefix"*)
+      previous_tag="${previous_image#"$expected_prefix"}"
+      ;;
+    '')
+      echo "首次部署没有可回滚镜像，部署失败" >&2
+      local_compose stop "$SERVICE" >/dev/null 2>&1 || true
+      return 1
+      ;;
+    *)
+      echo "旧镜像不属于当前服务，拒绝自动回滚: $previous_image" >&2
+      return 1
+      ;;
+  esac
+  if [ "$previous_image" = "$IMAGE" ]; then
+    echo "旧镜像与新镜像相同，无法自动回滚: $IMAGE" >&2
+    return 1
+  fi
+
+  echo "开始自动回滚到: $previous_image" >&2
+  if ! docker pull "$previous_image"; then
+    echo "自动回滚失败，无法拉取旧镜像: $previous_image" >&2
+    return 1
+  fi
+  IMAGE_TAG="$previous_tag"
+  export IMAGE_TAG
+  if ! local_compose up -d --no-deps --pull never "$SERVICE"; then
+    echo "自动回滚失败，旧镜像启动命令失败: $previous_image" >&2
+    return 1
+  fi
+  if wait_for_local_health; then
+    echo "自动回滚成功: $previous_image" >&2
+    local_compose ps "$SERVICE" || true
+  else
+    echo "自动回滚失败，旧镜像未恢复健康: $previous_image" >&2
+  fi
+  return 1
 }
 
 if [ "${TARGET_IS_LOCAL:-false}" = "true" ]; then
@@ -131,43 +377,172 @@ run_scp() {
 run_ssh install -d -m 750 "$REMOTE_DIR"
 
 SUFFIX="${IMAGE_TAG}.$$.${SERVICE}"
-REMOTE_ENV_TMP="$REMOTE_DIR/.env.$SUFFIX.tmp"
-REMOTE_COMPOSE_TMP="$REMOTE_DIR/docker-compose.yml.$SUFFIX.tmp"
+REMOTE_ENV_NAME=".env.$PROJECT_NAME"
+REMOTE_COMPOSE_NAME="docker-compose.$PROJECT_NAME.yml"
+REMOTE_ENV_TMP="$REMOTE_DIR/$REMOTE_ENV_NAME.$SUFFIX.tmp"
+REMOTE_COMPOSE_TMP="$REMOTE_DIR/$REMOTE_COMPOSE_NAME.$SUFFIX.tmp"
 run_scp "$ENV_FILE" "$SSH_TARGET:$REMOTE_ENV_TMP"
 run_scp "$COMPOSE_FILE" "$SSH_TARGET:$REMOTE_COMPOSE_TMP"
-run_ssh sh -s -- "$REMOTE_DIR" "$REMOTE_ENV_TMP" "$REMOTE_COMPOSE_TMP" <<'REMOTE_PREPARE'
+run_ssh sh -s -- "$REMOTE_ENV_TMP" "$REMOTE_COMPOSE_TMP" "$REMOTE_DIR/$REMOTE_ENV_NAME" "$REMOTE_DIR/$REMOTE_COMPOSE_NAME" <<'REMOTE_PREPARE'
 set -eu
-remote_dir="$1"
-env_tmp="$2"
-compose_tmp="$3"
+env_tmp="$1"
+compose_tmp="$2"
+env_target="$3"
+compose_target="$4"
 chmod 600 "$env_tmp"
 chmod 644 "$compose_tmp"
-mv -f "$env_tmp" "$remote_dir/.env"
-mv -f "$compose_tmp" "$remote_dir/docker-compose.yml"
+mv -f "$env_tmp" "$env_target"
+mv -f "$compose_tmp" "$compose_target"
 REMOTE_PREPARE
 
-echo "传输镜像到 $SSH_TARGET: $IMAGE"
-docker save "$IMAGE" | gzip -1 | run_ssh 'gzip -dc | docker load'
+remote_registry_logout() {
+  run_ssh docker logout "$REGISTRY_HOST" >/dev/null 2>&1 || true
+}
 
-run_ssh sh -s -- "$REMOTE_DIR" "$DEPLOY_ENV" "$IMAGE_REPOSITORY" "$IMAGE_TAG" "$SERVICE" <<'REMOTE_DEPLOY'
+echo "目标服务器从共享仓库拉取增量镜像: $IMAGE"
+printf '%s' "$REGISTRY_PASSWORD" | run_ssh docker login -u "$REGISTRY_USER" --password-stdin "$REGISTRY_HOST"
+trap remote_registry_logout EXIT HUP INT TERM
+run_ssh docker pull "$IMAGE"
+
+run_ssh sh -s -- "$REMOTE_DIR" "$DEPLOY_ENV" "$IMAGE_REPOSITORY" "$IMAGE_TAG" "$SERVICE" "$PROJECT_NAME" "$REMOTE_ENV_NAME" "$REMOTE_COMPOSE_NAME" "$HEALTH_TIMEOUT_SECONDS" "$HEALTH_POLL_SECONDS" <<'REMOTE_DEPLOY'
 set -eu
 remote_dir="$1"
 deploy_env="$2"
 image_repository="$3"
 image_tag="$4"
 service="$5"
+project_name="$6"
+env_file="$7"
+compose_file="$8"
+health_timeout_seconds="$9"
+health_poll_seconds="${10}"
 cd "$remote_dir"
 export DEPLOY_ENV="$deploy_env"
 export IMAGE_REPOSITORY="$image_repository"
 export IMAGE_TAG="$image_tag"
-docker compose \
-  --project-name "firstleg-$deploy_env" \
-  --env-file .env \
-  -f docker-compose.yml \
-  up -d --remove-orphans --pull never "$service"
-docker compose \
-  --project-name "firstleg-$deploy_env" \
-  --env-file .env \
-  -f docker-compose.yml \
-  ps "$service"
+if [ "$deploy_env" = "development" ]; then
+  export PUBLISHED_BIND_ADDRESS=127.0.0.1
+else
+  export PUBLISHED_BIND_ADDRESS="${PUBLISHED_BIND_ADDRESS:-0.0.0.0}"
+fi
+
+compose() {
+  docker compose \
+    --project-name "$project_name" \
+    --env-file "$env_file" \
+    -f "$compose_file" \
+    "$@"
+}
+
+container_id() {
+  compose ps --all --quiet "$service" | head -n 1
+}
+
+container_image() {
+  id="$(container_id)"
+  if [ -n "$id" ]; then
+    docker inspect --format '{{.Config.Image}}' "$id"
+  fi
+}
+
+health_state() {
+  id="$(container_id)"
+  if [ -z "$id" ]; then
+    echo missing
+    return
+  fi
+  docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}no-health:{{.State.Status}}{{end}}' "$id" 2>/dev/null || echo missing
+}
+
+wait_for_health() {
+  elapsed=0
+  while [ "$elapsed" -lt "$health_timeout_seconds" ]; do
+    state="$(health_state)"
+    echo "容器健康状态: $state（已等待 ${elapsed}s）"
+    case "$state" in
+      healthy) return 0 ;;
+      no-health:running)
+        echo "容器未配置 HEALTHCHECK，以运行状态作为成功依据" >&2
+        return 0
+        ;;
+      unhealthy|no-health:exited|no-health:dead) return 1 ;;
+    esac
+    sleep "$health_poll_seconds"
+    elapsed=$((elapsed + health_poll_seconds))
+  done
+  echo "等待容器健康超时: ${health_timeout_seconds}s" >&2
+  return 1
+}
+
+new_image="$image_repository/$service:$image_tag"
+previous_image="$(container_image || true)"
+if [ -n "$previous_image" ]; then
+  echo "部署前运行镜像: $previous_image"
+else
+  echo "首次部署，未发现可回滚的旧镜像"
+fi
+
+new_started=true
+if ! compose up -d --no-deps --pull never "$service"; then
+  echo "新镜像启动命令失败: $new_image" >&2
+  new_started=false
+fi
+if [ "$new_started" = "true" ] && wait_for_health; then
+  running_image="$(container_image || true)"
+  if [ "$running_image" != "$new_image" ]; then
+    echo "运行容器镜像与请求镜像不一致: expected=$new_image actual=${running_image:-missing}" >&2
+    exit 1
+  fi
+  echo "新镜像健康检查通过: $new_image"
+  compose ps "$service"
+  exit 0
+fi
+
+echo "新镜像健康检查失败: $new_image" >&2
+failed_container_id="$(remote_container_id || true)"
+if [ -n "$failed_container_id" ]; then
+  echo "新镜像容器最近日志（最多 200 行）:" >&2
+  docker logs --tail 200 "$failed_container_id" 2>&1 || true
+else
+  echo "新镜像容器不存在，无法读取启动日志" >&2
+fi
+expected_prefix="$image_repository/$service:"
+case "$previous_image" in
+  "$expected_prefix"*) previous_tag="${previous_image#"$expected_prefix"}" ;;
+  '')
+    echo "首次部署没有可回滚镜像，部署失败" >&2
+    compose stop "$service" >/dev/null 2>&1 || true
+    exit 1
+    ;;
+  *)
+    echo "旧镜像不属于当前服务，拒绝自动回滚: $previous_image" >&2
+    exit 1
+    ;;
+esac
+if [ "$previous_image" = "$new_image" ]; then
+  echo "旧镜像与新镜像相同，无法自动回滚: $new_image" >&2
+  exit 1
+fi
+
+echo "开始自动回滚到: $previous_image" >&2
+if ! docker pull "$previous_image"; then
+  echo "自动回滚失败，无法拉取旧镜像: $previous_image" >&2
+  exit 1
+fi
+IMAGE_TAG="$previous_tag"
+export IMAGE_TAG
+if ! compose up -d --no-deps --pull never "$service"; then
+  echo "自动回滚失败，旧镜像启动命令失败: $previous_image" >&2
+  exit 1
+fi
+if wait_for_health; then
+  echo "自动回滚成功: $previous_image" >&2
+  compose ps "$service" || true
+else
+  echo "自动回滚失败，旧镜像未恢复健康: $previous_image" >&2
+fi
+exit 1
 REMOTE_DEPLOY
+
+remote_registry_logout
+trap - EXIT HUP INT TERM

deploy/scripts/deploy-development-service.sh

@@ -15,7 +15,8 @@ SSH_TARGET="${DEVELOPMENT_SSH_TARGET:-deploy@172.31.198.8}"
 SSH_KEY="${DEVELOPMENT_SSH_KEY:-/var/jenkins_home/.ssh/dev_deploy}"
 SSH_KNOWN_HOSTS="${DEVELOPMENT_SSH_KNOWN_HOSTS:-/var/jenkins_home/.ssh/known_hosts}"
 REMOTE_DIR="${DEVELOPMENT_DEPLOY_DIR:-/opt/firstleg/application}"
-COMPOSE_FILE="deploy/docker-compose.yml"
+COMPOSE_FILE="${DEPLOY_COMPOSE_FILE:-deploy/docker-compose.yml}"
+PROJECT_NAME="${DEPLOY_PROJECT_NAME:-firstleg-development}"
 
 if [ ! -f "$SSH_KEY" ]; then
   echo "开发环境 SSH 私钥不存在: $SSH_KEY" >&2
@@ -63,21 +64,22 @@ if [ "${DEVELOPMENT_DEPLOY_LOCAL:-false}" = "true" ]; then
   cd "$REMOTE_DIR"
   export DEPLOY_ENV=development
   export IMAGE_REPOSITORY IMAGE_TAG
+  export PUBLISHED_BIND_ADDRESS=127.0.0.1
 
   docker compose \
-    --project-name firstleg-development \
+    --project-name "$PROJECT_NAME" \
     --env-file .env \
     -f docker-compose.yml \
     pull $SERVICES
 
   docker compose \
-    --project-name firstleg-development \
+    --project-name "$PROJECT_NAME" \
     --env-file .env \
     -f docker-compose.yml \
     up -d --remove-orphans --pull never $SERVICES
 
   docker compose \
-    --project-name firstleg-development \
+    --project-name "$PROJECT_NAME" \
     --env-file .env \
     -f docker-compose.yml \
     ps $SERVICES
@@ -129,27 +131,29 @@ for service in $SERVICES; do
   docker save "$image" | gzip -1 | run_ssh 'gzip -dc | docker load'
 done
 
-run_ssh sh -s -- "$REMOTE_DIR" "$IMAGE_REPOSITORY" "$IMAGE_TAG" "$SERVICE_CSV" <<'REMOTE_DEPLOY'
+run_ssh sh -s -- "$REMOTE_DIR" "$IMAGE_REPOSITORY" "$IMAGE_TAG" "$SERVICE_CSV" "$PROJECT_NAME" <<'REMOTE_DEPLOY'
 set -eu
 remote_dir="$1"
 image_repository="$2"
 image_tag="$3"
 service_csv="$4"
+project_name="$5"
 services=$(printf '%s' "$service_csv" | tr ',' ' ')
 
 cd "$remote_dir"
 export DEPLOY_ENV=development
 export IMAGE_REPOSITORY="$image_repository"
 export IMAGE_TAG="$image_tag"
+export PUBLISHED_BIND_ADDRESS=127.0.0.1
 
 docker compose \
-  --project-name firstleg-development \
+  --project-name "$project_name" \
   --env-file .env \
   -f docker-compose.yml \
   up -d --remove-orphans --pull never $services
 
 docker compose \
-  --project-name firstleg-development \
+  --project-name "$project_name" \
   --env-file .env \
   -f docker-compose.yml \
   ps $services

deploy/scripts/deploy-services.sh

@@ -19,6 +19,15 @@ fi
 
 SERVICES=$(printf '%s' "$SERVICE_CSV" | tr ',' ' ')
 
+for service in $SERVICES; do
+  case "$service" in
+    *[!A-Za-z0-9_-]*|'')
+      echo "非法服务名: $service" >&2
+      exit 2
+      ;;
+  esac
+done
+
 env_file_has_key() {
   grep -q "^$1=" "$ENV_FILE"
 }
@@ -27,6 +36,59 @@ env_file_value() {
   sed -n "s/^$1=//p" "$ENV_FILE" | tail -n 1 | tr -d '\r'
 }
 
+DEPLOY_REGION=CN
+for service in $SERVICES; do
+  case "$service" in
+    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
+        BRIDGE_REGION="$(env_file_value REGION_CODE)"
+      fi
+      if [ -z "$BRIDGE_REGION" ]; then
+        echo "部署 event-bridge-service 时，环境文件必须显式包含 REGION_CODE=CN 或 REGION_CODE=OVERSEAS" >&2
+        exit 2
+      fi
+      case "$BRIDGE_REGION" in
+        CN) ;;
+        OVERSEAS) DEPLOY_REGION=OVERSEAS ;;
+        *) echo "部署 event-bridge-service 时，REGION_CODE 只能为 CN 或 OVERSEAS" >&2; exit 2 ;;
+      esac
+      ;;
+  esac
+done
+if [ "$DEPLOY_REGION" = "OVERSEAS" ]; then
+  for service in $SERVICES; do
+    case "$service" in
+      gateway-overseas|lastleg-service|warehouse-overseas-service|event-bridge-service) ;;
+      *) echo "一次部署不得混合国内与海外服务: $SERVICE_CSV" >&2; exit 2 ;;
+    esac
+  done
+  COMPOSE_FILE="deploy/docker-compose.overseas.yml"
+  PROJECT_NAME="firstleg-${DEPLOY_ENV}-overseas"
+else
+  COMPOSE_FILE="deploy/docker-compose.yml"
+  PROJECT_NAME="firstleg-${DEPLOY_ENV}"
+fi
+
+if [ "$DEPLOY_REGION" = "OVERSEAS" ]; then
+  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
+      exit 2
+    fi
+  done
+fi
+
+case " $SERVICES " in
+  *" gateway-overseas "*)
+    if ! env_file_has_key AUTH_SESSION_VALIDATION_URL || [ -z "$(env_file_value AUTH_SESSION_VALIDATION_URL)" ]; then
+      echo "部署 gateway-overseas 时，环境文件必须包含非空 AUTH_SESSION_VALIDATION_URL" >&2
+      exit 2
+    fi
+    ;;
+esac
+
 case " $SERVICES " in
   *" finance "*)
     for key in FINANCE_DB_URL FINANCE_DB_USERNAME FINANCE_DB_PASSWORD; do
@@ -38,6 +100,53 @@ case " $SERVICES " in
     ;;
 esac
 
+case " $SERVICES " in
+  *" firstleg "*)
+    if ! env_file_has_key LASTLEG_EVENT_BRIDGE_URL || [ -z "$(env_file_value LASTLEG_EVENT_BRIDGE_URL)" ]; then
+      echo "部署 firstleg 时，环境文件必须包含非空 LASTLEG_EVENT_BRIDGE_URL" >&2
+      exit 2
+    fi
+    ;;
+esac
+
+case " $SERVICES " in
+  *" lastleg-service "*)
+    for key in LASTLEG_DB_URL LASTLEG_DB_USERNAME LASTLEG_DB_PASSWORD FIRSTLEG_EVENT_BRIDGE_URL DOMESTIC_WAREHOUSE_URL; do
+      if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
+        echo "部署 lastleg-service 时，环境文件必须包含非空 $key" >&2
+        exit 2
+      fi
+    done
+    ;;
+esac
+
+case " $SERVICES " in
+  *" warehouse-overseas-service "*)
+    for key in WAREHOUSE_OVERSEAS_DB_URL WAREHOUSE_OVERSEAS_DB_USERNAME WAREHOUSE_OVERSEAS_DB_PASSWORD; do
+      if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
+        echo "部署 warehouse-overseas-service 时，环境文件必须包含非空 $key" >&2
+        exit 2
+      fi
+    done
+    ;;
+esac
+
+case " $SERVICES " in
+  *" event-bridge-service "*)
+    if [ "$DEPLOY_REGION" = "OVERSEAS" ]; then
+      EVENT_BRIDGE_KEYS="EVENT_BRIDGE_OVERSEAS_DB_URL EVENT_BRIDGE_OVERSEAS_DB_USERNAME EVENT_BRIDGE_OVERSEAS_DB_PASSWORD EVENT_CONSUMER_URL"
+    else
+      EVENT_BRIDGE_KEYS="EVENT_BRIDGE_DB_URL EVENT_BRIDGE_DB_USERNAME EVENT_BRIDGE_DB_PASSWORD FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL"
+    fi
+    for key in $EVENT_BRIDGE_KEYS; do
+      if ! env_file_has_key "$key" || [ -z "$(env_file_value "$key")" ]; then
+        echo "部署 event-bridge-service 时，环境文件必须包含非空 $key" >&2
+        exit 2
+      fi
+    done
+    ;;
+esac
+
 case " $SERVICES " in
   *" file "*)
     if ! env_file_has_key ROCKETMQ_NAME_SERVER || [ -z "$(env_file_value ROCKETMQ_NAME_SERVER)" ]; then
@@ -75,24 +184,24 @@ esac
 export DEPLOY_ENV IMAGE_REPOSITORY IMAGE_TAG
 
 if [ "$DEPLOY_ENV" = "development" ]; then
-  exec sh deploy/scripts/deploy-development-service.sh \
+  DEPLOY_COMPOSE_FILE="$COMPOSE_FILE" DEPLOY_PROJECT_NAME="$PROJECT_NAME" exec sh deploy/scripts/deploy-development-service.sh \
     "$IMAGE_REPOSITORY" "$IMAGE_TAG" "$SERVICE_CSV" "$ENV_FILE"
 fi
 
 docker compose \
-  --project-name "firstleg-${DEPLOY_ENV}" \
+  --project-name "$PROJECT_NAME" \
   --env-file "$ENV_FILE" \
-  -f deploy/docker-compose.yml \
+  -f "$COMPOSE_FILE" \
   pull $SERVICES
 
 docker compose \
-  --project-name "firstleg-${DEPLOY_ENV}" \
+  --project-name "$PROJECT_NAME" \
   --env-file "$ENV_FILE" \
-  -f deploy/docker-compose.yml \
+  -f "$COMPOSE_FILE" \
   up -d --remove-orphans --pull never $SERVICES
 
 docker compose \
-  --project-name "firstleg-${DEPLOY_ENV}" \
+  --project-name "$PROJECT_NAME" \
   --env-file "$ENV_FILE" \
-  -f deploy/docker-compose.yml \
+  -f "$COMPOSE_FILE" \
   ps $SERVICES

deploy/service-map.yml

@@ -3,6 +3,11 @@ services:
     artifactId: gateway
     jar: gateway/target/gateway-1.0.0-SNAPSHOT.jar
     port: 9000
+  gateway-overseas:
+    artifactId: gateway-overseas
+    jar: gateway-overseas/target/gateway-overseas-1.0.0-SNAPSHOT.jar
+    port: 9300
+    regions: [OVERSEAS]
   auth:
     artifactId: auth-service
     jar: auth/target/auth-service-1.0.0-SNAPSHOT.jar
@@ -35,10 +40,21 @@ services:
     artifactId: integration-service
     jar: integration-service/target/integration-service-1.0.0-SNAPSHOT.jar
     port: 9210
+  lastleg-service:
+    artifactId: lastleg-service
+    jar: lastleg-service/target/lastleg-service-1.0.0-SNAPSHOT.jar
+    port: 9303
+    regions: [OVERSEAS]
+  warehouse-overseas-service:
+    artifactId: warehouse-overseas-service
+    jar: warehouse-overseas-service/target/warehouse-overseas-service-1.0.0-SNAPSHOT.jar
+    port: 9305
+    regions: [OVERSEAS]
   event-bridge-service:
     artifactId: event-bridge-service
     jar: event-bridge-service/target/event-bridge-service-1.0.0-SNAPSHOT.jar
-    port: 9300
+    port: 9312
+    regions: [CN, OVERSEAS]
   audit-service:
     artifactId: audit-service
     jar: audit-service/target/audit-service-1.0.0-SNAPSHOT.jar

deploy/sql/README.md

@@ -2,12 +2,15 @@
 
 ## 唯一数据库初始化与发布入口
 
-- 固定入口：`头程数据库统一增量-MySQL8.sql`。文件名保留历史兼容，内容维护为当前完整数据库基线和存量环境兼容升级，不再按日期拆分发布脚本。
+- 国内区域固定入口：`头程数据库统一增量-MySQL8.sql`。文件名保留历史兼容，内容维护为当前完整数据库基线和存量环境兼容升级，不再按日期拆分发布脚本。
+- 海外区域固定增量入口：`海外区域统一增量-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`。
@@ -56,6 +59,8 @@
 
 在 Navicat、DataGrip 或 MySQL 命令行中以“运行脚本”方式完整执行，确保客户端支持 `DELIMITER`。不要只选中局部语句执行。
 
+执行前先重新连接目标数据库，开启客户端 keepalive，并关闭“遇错继续执行”；出现连接断开、语法错误或 `SQLSTATE 45000` 后不得从失败位置续跑。由于 DDL 会隐式提交，存量环境可能已经部分更新；修复失败原因后应使用同一固定入口从第一行完整重跑，依靠脚本的元数据判断和幂等写入收敛结构。若出现 MySQL `4031`，先处理客户端连接保活或由数据库管理员调整 `wait_timeout` / `interactive_timeout`，再重新连接执行。
+
 执行结束后必须看到 `migration_status = PASS`。如果中途出现 `SQLSTATE 45000`，必须按错误中给出的缺失表、字段或权限处理后重新完整执行。
 
 ## 三期分柜、预装、拣货与装柜当前基线
@@ -215,3 +220,9 @@ SELECT
 - Warehouse 新增 `wh_overseas_storage_fee_rule` 和 `wh_overseas_storage_fee_tier`，包含客户唯一索引、分页索引、阶梯起始天唯一索引和规则明细查询索引。
 - IAM 新增 `platform:overseas-storage-fee:list/create/edit/delete` 四项权限，默认授予平台系统管理员。
 - Warehouse Service 启动前必须先执行固定入口；末尾只有两张表、五个索引和四项权限均存在才返回 `PASS`。
+
+## 四期海外权限目录
+
+- 固定入口已同步 `iam/src/main/resources/db/lastleg-permissions.sql` 的 `platform:overseas-*` 权限，并默认授予平台系统管理员。
+- 旧 `platform:lastleg:*` 权限会撤销角色关联并停用；不保留旧码兼容映射。
+- 本批不创建箱号、产品库、海外出库、退货出库或海外派送权限。

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

@@ -0,0 +1,149 @@
+# 同步调用依赖与失败传播治理基线
+
+## 目的与口径
+
+本基线覆盖当前官方 22 个 Maven 模块、15 个可执行服务之间的 OpenFeign、`RestClient`、`WebClient` 与 JDK `HttpClient` 调用。海外安全 Inbox/投影属于 Lastleg 内部子域，不再作为独立服务节点。基线用于识别同步依赖方向、在线请求深度、后台中继、超时、重试、熔断、幂等、错误映射和失败传播，不改变 Finance 或四期业务状态机。
+
+“存在双向服务边”不等于“一次在线请求会递归调用”。每条边必须继续区分：
+
+- `REQUEST`：用户或设备请求线程内，失败直接影响当前业务结果；
+- `BACKGROUND`：Outbox、Inbox、定时器或导出 Worker 中的同步传输，业务事务已与传输解耦；
+- `INFRASTRUCTURE`：审计、网关会话校验等基础设施调用；
+- `EXTERNAL`：Integration 对第三方供应商的调用。
+
+逐客户端可执行清单位于 `scripts/synchronous-dependency-baseline.mjs`，离线合同为 `scripts/synchronous-dependency-contract.test.mjs`。清单逐项冻结 44 个 Feign 与 16 个原始 HTTP 客户端的执行上下文、`READ/WRITE/READ_WRITE`、幂等类型和说明，并从同一事实源输出 REQUEST、BACKGROUND、INFRASTRUCTURE、EXTERNAL 与全图。新增客户端、目标服务、在线边、强连通分量或超时配置时，必须先更新基线并完成调用方与被调用方评审，不能仅修改测试期望以放行。
+
+## 当前服务边
+
+### OpenFeign
+
+| 调用方 | 被调用方 | 客户端数 | 主要上下文 |
+|---|---|---:|---|
+| Auth | IAM | 2 | 登录授权、注册，`REQUEST` |
+| IAM | Auth | 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/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` |
+| Finance | Firstleg | 2 | 费用来源/成本快照，事件消费与平台操作混合 |
+| Finance | File / IAM / Warehouse | 各 1 | 凭证、客户、供应商校验，`REQUEST` |
+| File | IAM | 2 | 资质登记为 `REQUEST`；导出 Provider 为 `BACKGROUND` |
+| File | Order / Firstleg / Finance / Warehouse | 各 1 | 导出 Provider，`BACKGROUND` |
+| File | Integration | 1 | OCR 在上传处理请求线程执行，`REQUEST` |
+| Lastleg | Event Bridge | 1 | 跨区事件 Outbox 中继，`BACKGROUND` |
+| Lastleg | 国内 Warehouse | 1 | 合作仓报价快照，`REQUEST` |
+
+合计 44 个 Feign 客户端。公共默认连接/读取超时为 3 秒/5 秒；File 的五个导出 Provider 客户端读取超时单独为 15 秒。
+
+### 原始 HTTP
+
+| 调用方 | 被调用方 | 实现 | 上下文与当前策略 |
+|---|---|---|---|
+| Gateway Overseas | Auth | `HttpPdaSessionValidationClient` | `INFRASTRUCTURE`；总超时 2 秒，异常由网关失败关闭 |
+| 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（业务事件与安全投影两个入口） | 三个 JDK `HttpClient` | `BACKGROUND`；连接 3 秒、请求 10 秒，持久化租约和退避由 Event Bridge 专项治理；Lastleg Security 投影不进入在线业务图 |
+| 启用 Common Audit 的服务 | Audit | `HttpAuditSink` | `INFRASTRUCTURE`；当前捕获异常后仅告警，可能让调用方误以为审计已成功，是高优先级失败传播缺口 |
+| Integration | 外部 OCR/船司 | 六个 JDK `HttpClient` | `EXTERNAL`；OCR 默认 10/60 秒，船司默认 10/30 秒，业务重试必须服从供应商和调度契约 |
+
+#### Lastleg 四个有界 RestClient
+
+四个客户端统一从 `LastlegRestClientFactory` 构建 JDK HTTP 传输，由 `LastlegRestClientProperties` 绑定独立超时。读取超时是单次请求的硬边界；客户端没有 Retry、fallback 或默认成功配置。
+
+| 客户端 | 构建与调用路径 | 写操作幂等性 | 默认超时 |
+|---|---|---|---|
+| `HttpUnloadPhotoFileGateway` | `ReceivingContainerController → ReceivingContainerService → UnloadPhotoFileGateway → /internal/file/v1/business-files/**` | `validate` GET 可重复；`upload` 每次写文件和元数据，没有幂等键，禁止自动重试 | 连接 3 秒、读取 30 秒 |
+| `HttpRelabelPhotoFileGateway` | `RelabelPdaController/Service → RelabelPhotoFileGateway → /internal/file/v1/business-files/**` | `validate` GET 可重复；`upload` 没有幂等键，禁止自动重试 | 连接 3 秒、读取 30 秒 |
+| `HttpWarehouseResourceGateway` | `InboundPdaWorkflowService`、PDA 仓内查询/盘点及 Dropship → Warehouse Resource/Pallet 内部接口 | 查询可重复；`reserve` 使用 `reservationKey`，`ensureDropship` 使用业务绑定，release/scrap 由服务端状态收敛；尽管服务端具备业务幂等，客户端仍不自动重试 | 连接 3 秒、读取 5 秒 |
+| `HttpPalletPhysicalGateway` | `PdaPalletOperationService`、`PdaInventoryMoveService` → `/internal/v1/pda-pallet-transitions/**` | 查询可重复；apply/compensate 使用稳定 `operationKey` 与请求哈希，服务端幂等；客户端仍不自动重试 | 连接 3 秒、读取 5 秒 |
+
+## 分上下文依赖图
+
+### 在线 REQUEST 图
+
+在线图只包含用户或设备请求线程中实际执行的服务边。Event Bridge、Outbox、船节点定时任务、导出 Provider 和 Gateway→Lastleg Security 基础设施校验均不计入在线深度。
+
+当前在线强连通分量为：
+
+`Auth ↔ IAM`；`Firstleg ↔ Order`
+
+`IAM → Firstleg` 默认尺寸初始化已退出请求线程，合同现冻结 21 条在线服务边；新增在线边或新增强连通分量直接失败。File 不再属于在线强连通分量；Finance、Lastleg 只指向上述分量或叶子服务，不属于在线环；Gateway Overseas→Lastleg Security 是 `INFRASTRUCTURE`，不是 REQUEST 边。
+
+### 后台 BACKGROUND 图
+
+后台图包含 Outbox/Inbox、导出 Worker 和定时任务，当前强连通分量为：
+
+`Event Bridge ↔ Firstleg ↔ Finance ↔ Lastleg ↔ Order`
+
+File 的五个导出 Provider、Order→Firstleg 入库 Outbox、该入库消费者为生成箱号而回读 Order 货物的后台回调、IAM 默认尺寸可靠任务、IAM 安全 Outbox、Firstleg/Lastleg 跨区 Outbox、Firstleg→Finance 费用 Outbox及 Event Bridge 三个消费者均只在后台图中计算。Event Bridge→Lastleg Security 与 Event Bridge→Lastleg 业务事件在服务图上收敛为同一条后台服务边，不形成新的在线业务边或独立安全节点。
+
+### 全图
+
+全上下文合并后，非平凡强连通分量仍为 8 个服务：
+
+`Auth ↔ IAM ↔ Order ↔ Firstleg ↔ Finance ↔ File ↔ Event Bridge ↔ Lastleg`
+
+全图只用于部署影响和故障域观察，不能再用于推导在线调用“无限深度”。
+
+### 用户入口在线最长简单路径
+
+默认在线预算为最多 2 个下游服务跳数。合同对每个已知用户入口枚举全部最长简单路径；下表列出的具体路径均超过预算：
+
+| 用户入口 | 最长跳数 | 全部长路径 |
+|---|---:|---|
+| 订单 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 → 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 边退出
+
+`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`，合同明确阻止仅改变分类却未退出生产调用的伪解环。
+
+## 退出顺序
+
+1. **冻结与分层。** 先用清单合同阻止未评审新边；为每个客户端补齐 `REQUEST/BACKGROUND/INFRASTRUCTURE/EXTERNAL`、读写语义、幂等键和失败映射。这个阶段不改变业务状态。
+2. **统一失败传播与时间预算。** 为 Feign 和原始 HTTP 明确连接/读取/总超时；默认禁用自动重试，只有具备幂等键且由业务明确拥有退避状态的后台操作可以重试；禁止空数据、默认成功或仅日志告警替代远端失败。
+3. **先退出伪在线环。** File 导出 Provider、Firstleg/Lastleg Event Bridge、Firstleg→Finance 费用投递继续作为后台链路，但必须从在线深度图剥离，并禁止 Worker 消费时无界同步回调。
+4. **退出 `Order ↔ Firstleg` 在线双向命令。** 保留一个方向的权威查询，将反向状态推进改为带版本、幂等和审计的 Outbox/Inbox；不复制 Order 交易状态或 Firstleg 履约状态。
+5. **退出 `Auth ↔ IAM` 在线双向写。** Auth 保持账号与 Token 唯一所有者，IAM 保持客户/RBAC 所有者；注册和账号开通使用可恢复编排，登录授权快照失败关闭，不引入第二套账号事实。
+6. **收敛 `IAM ↔ Firstleg`。** 客户维度规则和客户快照确定单一事实方向；允许短期只读查询，禁止两个服务互相修正对方数据。
+7. **在财务总控确认后退出 `Firstleg ↔ Finance` 回调。** 优先让版本化事件携带 Finance 校验所需的不可变快照或使用单向快照读取，保持 Finance 状态机和 Firstleg 费用事实边界不变。
+8. **收敛 File 相关环。** File 只拥有文件对象与导出任务；业务服务拥有导出数据和业务归属。凭证/照片校验失败关闭，导出 Worker 使用受限批次、超时和显式失败状态。
+
+## 错误、重试与熔断基线
+
+- 远端 HTTP 非 2xx、响应体 `code != "200"`、空响应和 DTO 不完整是四类不同失败，均不得变成成功或空列表。
+- 在线查询/命令默认不自动重试。若启用重试，必须同时证明方法幂等、请求具有稳定幂等键、最大尝试次数和总时间预算可控。
+- Outbox/Inbox 重试由持久化状态拥有，Feign/JDK 客户端不得再叠加隐式重试造成次数乘法。
+- 熔断打开时返回统一“依赖不可用”错误并保留 request/trace 关联信息，不配置业务成功型 fallback。
+- 404 只有在契约明确“资源不存在”时可映射为领域未找到；连接失败、超时、5xx、空响应必须映射为依赖不可用。
+- Common Audit 当前“只记录告警后返回”列为已知例外，不能据此推广静默降级；其可靠性与业务阻断口径需和审计/总控共同冻结。
+
+## 直接受影响验证
+
+| 变更范围 | 最低验证 |
+|---|---|
+| 图、客户端或超时配置 | `node --test scripts/synchronous-dependency-contract.test.mjs` |
+| 单个 Feign/HTTP 签名或错误映射 | `mvn -pl <调用方>,<被调用方> -am test-compile`，并运行双方直接相关测试 |
+| Auth/IAM | `mvn -pl auth,iam -am test` |
+| Order/Firstleg | `mvn -pl order,firstleg -am test` |
+| IAM/Firstleg | `mvn -pl iam,firstleg -am test` |
+| Firstleg/Finance | `mvn -pl firstleg,finance -am test`；业务口径先由财务总控确认 |
+| Firstleg/File 或 File/Finance | `mvn -pl firstleg,file,finance -am test`，按实际消费者缩小模块集 |
+| Lastleg 原始 HTTP | `mvn -pl lastleg-service,warehouse-overseas-service,file -am test`；不改变四期状态机 |
+| 全部治理阶段收口 | `mvn -DskipTests validate` 后执行 `mvn test` |
+
+以上均为本地离线验证；未经明确授权不启动 Java/Nacos/数据库，不执行 SQL、部署或测试环境 HTTP 验收。

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

@@ -10,7 +10,7 @@
 
 ## 1. 项目定位
 
-`baiyue-firstleg` 是国内头程业务后端仓库，采用 Maven 多模块单仓结构。仓库内包含 7 个公共模块和 11 个可独立启动、构建、制作镜像的微服务。
+`baiyue-firstleg` 是国内头程与海外仓后端仓库，采用 Maven 多模块单仓结构。根 POM 聚合 22 个 Maven 模块，其中 7 个是公共/依赖模块，15 个是可独立启动、构建、制作镜像的微服务。
 
 当前技术基线：
 
@@ -24,7 +24,7 @@
 - SpringDoc OpenAPI / Swagger
 - GitLab、Jenkins、Docker Compose
 
-本仓库只保存头程代码。尾程业务位于独立 Git 仓库，不允许把尾程源码、数据库或配置重新放回本仓库。
+国内与海外服务共享源码仓库和公共制品，但保持独立数据库、Nacos 命名空间与部署边界；跨区域业务协作使用版本化 Outbox/Inbox 事件，不共享业务数据源。
 
 ## 2. 根目录结构
 
@@ -39,11 +39,15 @@ baiyue-firstleg/
 ├─ common-event-contract/        # 国内外跨区域事件统一契约
 │
 ├─ gateway/                      # 统一 API 网关
+├─ gateway-overseas/             # 海外区域 API 网关
 ├─ auth/                         # 统一登录与账号凭据
 ├─ iam/                          # 租户、成员、角色、权限、企业审核
 ├─ order/                        # 头程订单中心
 ├─ firstleg/                     # 履约任务、二期入库、测量与计费
 ├─ warehouse/                    # 仓库主数据、托盘与库位资源
+├─ finance/                      # 财务账期、账单、收付款与核销
+├─ lastleg-service/              # 海外尾程、入仓、库存与本土业务
+├─ warehouse-overseas-service/   # 海外仓库、库位、托盘与资源锁
 ├─ file/                         # 资质、导出与测量图片文件中心
 ├─ print/                        # 打印中心
 ├─ audit-service/                # 审计日志中心
@@ -86,6 +90,7 @@ baiyue-firstleg/
 | 文件夹 | 注册服务名 | 端口 | 数据库 | 当前职责与实现情况 |
 | --- | --- | ---: | --- | --- |
 | `gateway` | `gateway` | 9000 | 无 | 统一路由、CORS、JWT/Redis 会话校验、商户端与平台端访问域隔离、Swagger 聚合 |
+| `gateway-overseas` | `gateway-overseas` | 9300 | 无 | 海外区域 API 入口、海外 Audience/JWKS 校验及海外服务路由 |
 | `auth` | `auth-service` | 9100 | `baiyue_auth` | 登录、刷新 Token、退出、商户注册、账号密码和账号内部管理 |
 | `iam` | `iam-service` | 9201 | `baiyue_iam` | 租户、企业资料、企业审核、成员、角色、权限、按钮权限、个人资料和授权快照 |
 | `firstleg` | `firstleg-service` | 9202 | `baiyue_firstleg` | 履约任务与分配；二期入库单、测量审核、FBA 计费、费用发布和完成入库编排；不是订单主数据服务 |
@@ -94,10 +99,12 @@ baiyue-firstleg/
 | `file` | `file-service` | 9206 | `baiyue_file` | 企业资质文件、公共异步导出下载、入库测量图片及重量 OCR 调用协作 |
 | `print` | `print-service` | 9207 | 无 | 无状态 PDF 渲染服务；调用方传入完整标签数据，服务在内存中生成一次性多页 PDF |
 | `integration-service` | `integration-service` | 9210 | 无 | 百度 OCR、Amazon SP-API 等第三方适配器和启停状态；默认关闭外部调用 |
-| `event-bridge-service` | `event-bridge-service` | 9300 | `baiyue_event_bridge` | 国内外事件接收、签名/内部令牌保护、幂等 Inbox 和接收结果 |
+| `lastleg-service` | `lastleg-service` | 9303 | `baiyue_lastleg` | 海外尾程订单、接柜入仓、库存、海外本土业务及 IAM 安全事件投影/实时校验；不含海外出库和派送 |
+| `warehouse-overseas-service` | `warehouse-overseas-service` | 9305 | 海外仓资源库 | 海外仓库、库位、托盘和资源锁 |
+| `event-bridge-service` | `event-bridge-service` | 9312 | `baiyue_event_bridge` | 按 CN/OVERSEAS 双实例部署的跨区事件 Inbox、重试和目标服务投递 |
 | `audit-service` | `audit-service` | 9700 | `baiyue_audit` | 接收公共审计事件并持久化；平台端可按权限查询已脱敏日志，业务审计发送默认开启 |
 
-MySQL、Redis、Nacos 是外部基础设施，不属于上述 11 个业务服务，也不应打包进业务镜像。
+MySQL、Redis、Nacos 是外部基础设施，不属于上述业务服务，也不应打包进业务镜像。
 
 ## 5. 各服务文件夹说明
 
@@ -155,6 +162,8 @@ Integration 负责百度 OCR、重量识别和 Amazon Logistics/SP-API 等第三
 
 Event Bridge 负责接收国内外服务器之间的必要业务事件，并通过 Inbox 实现幂等。事件载荷遵循 `common-event-contract`，包含事件 ID、来源和目标区域、业务键、版本、时间及 Payload 哈希；头程与尾程不共享 MySQL、Redis、Nacos 或内部接口。
 
+头程装柜完成事件以实际集装箱为顶层批次，`orders[]` 中每项是一张实际发运的来源入仓单；一个柜可包含多张入仓单。每个货物明细携带来源明细 ID、实际装运箱数和完整的国内箱唛池。国内不要求在装柜时逐箱扫描冻结，完整箱唛池可以大于本柜实际装运箱数；海外按实际首次扫描的箱唛确认归属和实收，未扫描箱唛保留给后续子订单。海外将同柜各来源入仓单分别生成入库计划，但以同一集装箱号关联，并且只允许同一目的仓的箱子合托。
+
 ## 6. 配置、部署和辅助目录
 
 ### `config/`
@@ -165,7 +174,7 @@ config/nacos/
 └─ cn/       # 国内服务器配置模板
 ```
 
-每套目录包含公共配置 `baiyue-common.yml` 和 11 个服务配置。配置模板可以提交，真实密码和第三方密钥不能提交。
+`local/`、`cn/`、`overseas/` 按部署区域保存公共配置和该区域需要的服务配置。配置模板可以提交，真实密码和第三方密钥不能提交。
 
 ### `deploy/`
 
@@ -174,7 +183,8 @@ deploy/
 ├─ docker/Dockerfile          # 通用 Java 17 镜像
 ├─ env/.env.test.example      # 环境变量示例
 ├─ scripts/deploy-services.sh # Jenkins 增量部署脚本
-├─ docker-compose.yml         # 11 个业务服务编排
+├─ docker-compose.yml         # 国内区域服务编排
+├─ docker-compose.overseas.yml # 海外区域服务编排
 ├─ docker-compose.rocketmq.yml # 公共导出 RocketMQ 基础设施
 ├─ sql/                       # 测试/存量环境统一迁移入口与说明
 └─ service-map.yml            # 模块、JAR、端口映射
@@ -271,6 +281,6 @@ HTTP 401 / `A0401`，不得再按 HTTP 200 + 空权限处理；只有使用新
 - 平台端和商户端权限分别管理，接口与按钮权限都必须由后端校验。
 - Controller 负责协议转换，Service 负责业务编排，Repository/Mapper 负责持久化。
 - 服务之间只传 DTO 或事件契约，不能依赖其他服务的 Entity、Mapper。
-- 公共模块变化会影响多个服务，Jenkins 会自动重建全部 11 个服务。
+- 公共模块变化会影响多个服务，Jenkins 会按 `service-map.yml` 覆盖的全部 15 个服务执行受影响构建。
 - 单一 Git 仓库不等于单一部署单元；每个服务仍生成独立 JAR、镜像和容器。
-- 头程与尾程保持两个 Git 仓库、两套数据库和两套运行环境。
+- 国内头程与海外仓共享 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 对同名属性的最终取值不直观，容易连错环境。