.gitattributes

@@ -5,6 +5,8 @@
 *.yaml text eol=lf
 *.md text eol=lf
 *.sql text eol=lf
+*.sh text eol=lf
+Jenkinsfile text eol=lf
 *.ps1 text eol=crlf
 *.cmd text eol=crlf
 *.bat text eol=crlf
@@ -13,4 +15,3 @@
 *.jpg binary
 *.jpeg binary
 *.pdf binary
-

.gitignore

@@ -1,4 +1,6 @@
 target/
+node_modules/
+.docker-context/
 *.log
 .idea/
 *.iml
@@ -13,6 +15,7 @@ data/
 .env
 .env.*
 !.env.example
+!.env.*.example
 application-local.yml
 bootstrap-local.yml
 *.hprof
@@ -21,4 +24,10 @@ dependency-reduced-pom.xml
 reports/runtime*/
 reports/uploads/
 reports/db-backup*/
+reports/
 uploads/
+.codex-temp*
+.codex-tmp*
+.runtime-*/
+.codex-*.out
+.codex-*.err

.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
-

AGENTS.md

@@ -0,0 +1,138 @@
+# 头程与海外仓后端项目指引
+
+## 适用范围与定位
+
+- 本文件适用于 `baiyue-firstleg/` Maven 多模块仓库，包含国内头程与海外区域服务；进入具体服务后继续读取该服务的 `AGENTS.md`。
+- 本层只负责：服务边界、跨服务契约、数据库部署总入口、阶段路由和通用验证。Controller、Service、DTO、SQL 细节以模块级指引为准。
+- 普通任务先读本文件和目标模块指引；聚合构建/架构问题再读 `README.md`、`pom.xml`、`docs/头程项目目录结构与服务说明.md`。
+- 平台/客户层级与权限公共语义见 `../docs/平台客户层级与权限契约.md`；国内/海外 Token、双区域 API 和跨区事件公共契约见 `../docs/跨区域认证与服务通信契约.md`。本文件只保留后端执行所需摘要。
+
+## 不可突破的产品与数据边界
+
+- 当前产品只有“平台—客户”两级。`tenant_id=0` 是平台技术作用域；`tenant_id>0` 是客户隔离键，不得新增租户切换、租户选择或租户级 RBAC。
+- 公共仓库、往来单位、快递、托盘、库位统一归属 `tenant_id=0`；订单、文件、费用等客户数据按客户 `tenant_id>0` 隔离。不得跨库 Join 或信任客户端客户 ID。
+- 国内订单交易状态归 `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。
+
+## 服务路由（按关键词定位）
+
+| 任务关键词 | 首选服务 | 先看入口 |
+|---|---|---|
+| 登录、Token、密码、注册与顶层授权快照 | `auth/` | `auth/AGENTS.md`；海外 Token 只携带稳定身份与版本，角色、权限和冻结海外仓从登录/刷新响应顶层快照读取，海外 Gateway 再按 IAM 安全投影失败关闭校验 |
+| 客户档案、成员、审核、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`；统一列表由 `UnifiedOrderQueryService` 组合交易与履约投影，仍固定显示 `PENDING_REVIEW` 并提供审核动作：Order 为 `SUBMITTED` 时必须优先返回 `PENDING_REVIEW/APPROVE_ORDER`，不得被 Firstleg 准备中状态覆盖 |
+| 客户头程订单中文批量导入 | `order/` | `MerchantBatchImportService.java`、`MerchantWarehouseCatalogClient.java`、`MerchantPricingCatalogClient.java`、`order-v1.yaml`；模板和导入都按当前客户读取动态地址、全部有效仓库与渠道，最多 50 行，只创建草稿，支持 `PARTIAL/ATOMIC` |
+| 平台修改客户原始申报、履约渠道变更与跨服务同步 | `order/`、`firstleg/` | Order `OrderDeclarationUpdateService.java`、`OrderInboundOutboxPublisher.java`、`order-v1.yaml`；Firstleg `OrderDeclarationSyncService.java`、`OrderDeclarationSyncMapper.java`、`firstleg-v1.yaml`。只更新申报快照；渠道变化先失败关闭校验履约可逆性与重新计价，成功后由版本化 `ORDER_DECLARATION_UPDATED_V1` 幂等同步，不覆盖实测、箱码或已确认费用 |
+| 平台订单批量审核预览 | `order/` | `PlatformFirstLegOrderController.java` 的 `/batch-review-preview`、`BatchOrderReviewPreviewService.java`、`BatchOrderReviewPreviewResponse.java`、`order-v1.yaml`；一次请求固定用订单与货物两次批量查询返回同序快照，不允许前端逐票请求详情，逐项资格以 `canApprove/blockReason` 为准 |
+| 履约分配、入库、测量、箱规算法、审核、FBA 计费 | `firstleg/` | `firstleg/AGENTS.md`；客户四档箱规与 `ADD/MULTIPLY` 默认算法从 `CustomerDimensionConfigService` 进入，单箱测量和最终计价分别由 `CustomerDimensionWeightingService`、`FbaPricingService` 保存并消费服务端快照 |
+| 入库单扣货、解除、凭证与履约门禁 | `firstleg/`、`file/` | Firstleg `InboundHoldService`、`InboundHoldGuard`、`InboundHoldEvidenceService`；平台接口 `/api/platform/inbounds/{inboundId}/hold`、`/release`、`/evidence`。扣货不改变 Order 主状态，命令使用入库聚合版本和幂等键；凭证只按客户、入库单及 `INBOUND_HOLD_EVIDENCE` 精确归属，所有装柜、PDA 拣货和国内出仓写入口统一复用门禁并失败关闭 |
+| 称重确认、整票库位块与 PDA 资源结算 | `firstleg/`、`warehouse/` | Firstleg `MeasurementLocationOccupationService.java`、`InboundMeasurementService.java`、`MeasurementSubmissionService.java`、`WarehousePalletLocationClient.java`；Warehouse `LocationBlockService.java` 与 `location-block-v1.yaml`。称重确认尽力建块、提交时再次补齐，库位指引失败不阻断测量主流程；部分拣货整段转移给余量子单，整票拣完才整块释放，A0 共享资源按 `reservationId` 区分 |
+| 客户专属价格簿、柜级阶梯运费与受控调价 | `firstleg/` | `PlatformPriceBookService.java`、`ActivePriceBookEstimator.java`、`FbaPricingService.java`、`pricing/ContainerTierAmountAllocator.java`、`InboundFeeDetailService.java`、`fba-pricing-v1.yaml`。`customerId=0` 为公共报价，正数为客户专属版本；计价优先专属 ACTIVE、缺失才回退公共 ACTIVE。同柜区域重量阶梯按实际成员计费量聚合命中并守恒分摊，装柜变化只重算未锁定客户费用；人工计费量调整限基准上下 10%，私人仓尾程派送费只绑定 `PRIVATE` 入库单；一件代发 `WAIT_PALLETIZE` 允许在预装确认前试算，写费用时必须保留托盘化状态 |
+| Firstleg 内部模块化与依赖基线 | `firstleg/` | `firstleg/docs/firstleg-internal-modularization-baseline.md`、`firstleg/scripts/analyze-firstleg-dependencies.mjs`；价格簿查询和客户统计按端口/适配器切片，不改变服务与数据库边界 |
+| Mapper 新增、移动、Bean 缺失与扫描遗漏 | 目标持久化服务 | 所有 Mapper 显式 `@Mapper`，启动类按服务根包注解过滤扫描；先运行 `node scripts/mapper-scan-contract.mjs`，再按目标模块执行 `test-compile/test`，不得等部署启动发现 |
+| 脚本管理、全量验证、测试造数与诊断 | 仓库根 `scripts/`；服务专属脚本留在 `<service>/scripts/` | 先读 `scripts/AGENTS.md` 和 `scripts/README.md`；Admin HTTP 内部模块继续读 `scripts/admin-test-env-modules/README.md`。新增入口必须登记用途、目标环境、数据副作用和报告位置，并通过 `scripts/script-documentation-contract.test.mjs` |
+| 分柜、柜次、智能排柜、预装/装柜清单、真实柜号后补、PDA | `firstleg/` | `firstleg/AGENTS.md`，再按 `split/`、`loading/`、`outbound/` 定位；创建柜次时原子生成唯一预装计划，加入入仓码时同步建立关联，不设推送步骤；预装/正式详情由 `/loading-plans/{planId}/lifecycle` 解析。真实集装箱号不阻塞订舱关联、计划确认或 PDA task 创建，可在 `EDITING/LOADING` 首次补录，但必须在 PDA 最终完成前存在。上传以幂等键绑定包含文件内容的请求哈希，完全重放不得再次调用 File |
+| 合柜报关 / 同柜不可拆组、跨客户合柜、整组分配/移除 | `firstleg/` | `loading/coload/controller/PlatformColoadGroupController.java`、`service/ColoadGroupService.java`、`persistence/ColoadGroupMapper.java`、`src/main/resources/openapi/coload-groups-v1.yaml`；按订单建组并冻结全部可用入仓片段，仅要求同国内仓、同渠道 |
+| 全局智能装柜候选、柜次、占位与移除 | `firstleg/`、`order/` | Firstleg `controller/PlatformSmartLoadingController.java` 的 `/inbound-candidates`、`/containers`、`/plans/{planId}/inbound-assignments`、`/pending-review-assignments`、`/group-assignments`、`/unpicked-items`，业务编排 `service/SmartLoadingService.java`；待审核事实由 `client/PendingReviewOrderClient.java` 经内部令牌查询 Order `/internal/order/v1/pending-review-orders` 与 `PendingReviewOrderQueryService.java` 的权威 `SUBMITTED/PENDING_REVIEW` 行。候选四态只用于筛选展示，资格以 `canAssign` 为准；待审核或待测量可先占位，确认预装和启动 PDA 前仍须进入 `WAIT_SPLIT`；计划明细总量/余量由 Order 原始申报或最新已审核测量补齐，调整时重验权威数量；人工加入允许跨渠道，智能推荐仍按柜次渠道；同柜组整组分页、分配和移除 |
+| 客户入库结果与头程费用确认 | `firstleg/` | `controller/MerchantInboundBillingController.java`、`service/MerchantInboundBillingService.java`、`FbaPricingService.java`，接口 `/api/merchant/v1/first-leg/orders/{orderId}/inbound-billing` 与 `/confirm`；客户按登录态范围读取并以费用版本和幂等键确认当前 `SENT` 费用，确认后锁定 |
+| 订舱资料/打印、船期、订舱级拖车、报关 | `firstleg/` | `oceanbooking/`、`portschedule/`、`TruckAppointmentService.java`、`outbound/dispatch/`、`customs/`；拖车只绑定 `RELEASED` 订舱，不携带客户、柜次、装柜计划或真实柜号，每订舱最多一张非终态预约，订舱文件联查 `file/AGENTS.md` |
+| 目的港码头拖车与还空预警 | `firstleg/` | `terminaldrayage/controller/PlatformTerminalDrayageController.java`、`service/TerminalDrayageService.java`、`src/main/resources/openapi/terminal-drayage-v1.yaml`；按 `containerBookingId` 聚合并与订舱级拖车分离，引用 Warehouse `ACTIVE + TRUCKING` 供应商，提柜/还柜复用船节点，服务端按海外卸柜完成时间加 72 小时计算还空预警 |
+| 客户账期、费用池、账单、入仓码联查、收款、成本、核销 | `finance/` | `finance/AGENTS.md`；客户账单行 `inboundCode` 由 `FinanceQueryService` 从费用来源快照提供，Client 复用头程入仓关系详情；费用来源和柜次成本快照再联查 `firstleg/AGENTS.md`，凭证再联查 `file/AGENTS.md` |
+| 客户资金账户、充值、授信、冻结、结算与跨区资金指令 | `finance/`、`lastleg-service/`、`common-event-contract/`、`event-bridge-service/` | 国内 `FinanceWalletService.java` 持有唯一 CNY 主账和不可变流水；平台、客户、内部入口见 `PlatformFinanceWalletController.java`、`ClientFinanceWalletController.java`、`InternalFinanceWalletController.java` 与 `finance-wallet-v1.yaml`。海外采购和换标由 Lastleg `wallet/` 发布 `WALLET_COMMAND_REQUESTED`，Finance 冻结、结算或释放后发布 `WALLET_COMMAND_COMPLETED` 回传，不跨区域同步调用钱包 |
+| 柜级公共费用跨客户分摊 | `firstleg/`、`finance/` | Firstleg `PlatformContainerFeeDetailController.java`、`ContainerFeeDetailService.java`、`container-fees-v1.yaml` 按柜内真实客户与订单原子创建 `allocation-groups`；金额合计必须等于总额，分组审核、驳回、调整、作废均整组处理，Finance 只消费各客户不可变来源快照 |
+| 海外业务费用来源跨区入池 | `lastleg-service/`、`common-event-contract/`、`event-bridge-service/`、`finance/` | Lastleg `financefee/` 审核五类海外费用并发布 `BUSINESS_FEE_SOURCE_CHANGED` 完整快照；Event Bridge 对 `targetRegion=CN` 定向投递 Finance `/internal/finance/v1/business-fee-source-events`；Finance 按事件 ID、Payload 哈希、来源系统/费用 ID/版本幂等入池，`PAYABLE + DIRECT_PAID` 单独形成已确认成本且不进入 AP 待结算 |
+| 入库/柜次应付、直接已付、付款流水与凭证 | `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` |
+| 平台操作日志与审计查询 | `audit-service/` | `audit-service/AGENTS.md`；平台查询接口 `/api/platform/v1/audit/logs` |
+| 资质、导出、导出退避重试、测量图片、文件下载 | `file/` | `file/AGENTS.md`；法人身份证选填，可在已有营业执照后单独补传或替换；`PENDING` 且已有失败尝试的退避任务可人工立即到期并复用当前投递，不创建并发任务 |
+| 路由、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`，尾程订单控制从 `LastlegOrderController.java`、`LastlegOrderCommandService.java` 进入，再按 `inboundplan/`、`relabel/`、`inventory/`、`procurement/`、`trucking/` 定位 |
+| 尾程订单控制、柜级预览与入仓计划转换 | `lastleg-service/`、`warehouse-overseas-service/` | `orders/container-summaries` 按 `sourceContainerBookingId` 跨客户聚合并分页返回全部稳定来源柜，已完成计划转换的柜仍用于接柜仓查询与修改，生成资格由 `allPlansReady/pendingPlanCount` 表达，详情返回全柜数据。`inbound-plans/container-preview` 由 `InboundPlanService.java` 返回服务端分组、托数、阻断项及快照版本/哈希；`ContainerInboundPlanConversionCoordinator.java` 校验同一快照并以唯一 Saga 先向 `WarehousePalletBatchService.java` 批量预留真实托盘，再本地原子生成剩余独立计划并确认资源，失败只补偿未确认资源，同柜重放不得新建第二批。暂扣/解除和固定八行人工节点进入 `LastlegOrderCommandService.java`；命令按订单版本、客户范围和幂等键执行，暂扣中的订单不得进入排车或出库 |
+| 海外入仓分页、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 出库或派送 |
+| 海外排车执行、PDA 出库、派送与一件代发 | `lastleg-service/` | `dispatch/controller/DispatchController.java`、`dispatch/pda/controller/DispatchPdaController.java`、`delivery/controller/DeliveryTransferController.java`、`OutboundPdaController.java`、`MerchantDeliveryController.java`，一件代发库存归 `dropship/`；统一经 `gateway-overseas/`，设备端正式入口继续查 `../apps/pda-overseas-uniapp/AGENTS.md` |
+| 海外异常退回、库存恢复与客户回访 | `lastleg-service/`、`file/` | `exceptionorder/`、`inventory/command/`、`customervisit/`；异常按版本和幂等键执行 `PENDING → PROCESSING → COMPLETED`，完成证据固定归 `OVERSEAS_EXCEPTION_EVIDENCE`。派送退回明细只能来自原出库拣货事实，退回海外仓时校验真实目标托盘/库位并以 `RETURN_STOCK_IN` 恢复库存后，原子完成异常单与派送 `RETURNED`；回访仍以 Lastleg 客户范围和派送状态为准 |
+| 一件代发 SKU/箱唛与暂扣跨区协同 | `order/`、`firstleg/`、`common-event-contract/`、`lastleg-service/` | Order `InternalOrderCargoController` 提供强制 SKU 与每箱数量；Firstleg `InboundCartonLabelService` 冻结箱唛 SKU，`DropshipPalletizationService` 完成清点、组托和封托，智能排柜只按 `SEALED` 整托分配，并消费 `OverseasInboundOrderDetainedChangedV1`；Lastleg `dropship/` 建立库存并发布暂扣变更 |
+| 客户海外仓贴标、转运、废弃与退货换标 | `lastleg-service/` | `relabel/`、`relabel/pda/`、`transfer/`、`discard/` 的 Merchant/PDA Controller 和 Service；换标下单按历史入仓库存选择，每个我方箱唛只形成一条箱任务，支持箱唛、SKU 和组合换标，SKU 子项不重复冻结。涉及箱唛换标时冻结派送方式，PDA 逐箱作业并上传完工照片，仓库复核后必须由客户查看证据确认，之后卡车进入预排车，自提/快递进入换标出库待创建；不伪造已入库单。Client 消费端 `../html/client-web/src/modules/overseas-warehouse/`，统一经 `gateway-overseas/` |
+| 海外仓 PDA 盘点、移库、托盘、换标与查询 | `lastleg-service/`、`warehouse-overseas-service/` | Lastleg `pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`；托盘作业保留托盘-入仓单组成明细，合托通过入仓计划托盘分配和合托记录留痕；`pallet-operations/relabel-disassemble` 按换标单箱唛快照解析原库存仓位，在一个幂等事务内移动对应冻结箱数并绑定已扫码目标托盘，同时更新换标明细和未开始拣货的出库托盘/箱唛快照；出库可扫描托盘但后台按托盘下各入仓单箱数核平；契约 `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` |
+
+散货托盘码与跨区传递：`firstleg/` 的 `LoadingPalletLabelService.java` 生成冻结标签并调用 Print 输出 PDF，`LoadingCompletedOutboxService.java` 传递装柜快照；`lastleg-service/` 通过 `LastlegSourcePalletMapper.java` 保存来源托盘，`InboundPlanService.java` 和 `ContainerInboundPlanConversionCoordinator.java` 消费。标签与资源预留的细节继续读对应服务指引。
+
+## 公共模块快速索引
+
+| 关键词 | 模块与入口 |
+|---|---|
+| 公共依赖版本 | `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` |
+
+## 全量验收路由
+
+- 当前订单与客户、入库测量与计费、国内货柜履约、海外仓业务及财务统一进入全量验收；按本次链路读取对应业务域/专题文档，不以历史规划终点阻断跨服务联调或回归。
+- `auth`、`iam`、`warehouse`、`order`、`firstleg`、`file`、`finance`、`integration-service` 及出仓相关能力按各自模块契约协作；状态、权限、数据库和 OpenAPI 以当前实现及已确认契约为准。
+
+## 国内头程与海外仓协同
+
+- 国内头程 Auth 是唯一用户账号和 Token 签发方；Admin/Client 共用一套前端和用户体系，海外仓不得另建登录或权限模型。
+- 统一使用 RS256/JWKS。国内登录/刷新时由 Auth 同时签发国内 Token 和短时海外 Token；前端统一认证层按国内/海外 API Base 自动选择。国内服务叠加 Redis 会话校验；海外 Token 只携带稳定身份、客户/仓库范围和版本声明，不携带角色或权限集。海外 Gateway 本地验签后必须通过 Lastleg 安全投影取得当前角色/权限并失败关闭，再清除外部伪造头、写入受内部服务令牌保护的可信身份上下文；海外服务不得访问国内 Redis，海外业务请求不得经国内 Gateway 中转。
+- 头程装柜完成向海外建尾程单、海外 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` 不读取尾程订单库。
+
+## 契约、数据库与验证入口
+
+- 对外 Controller/API 新增、改名或删除时，同时核对调用端、区域 Gateway、OpenAPI 和权限；提交前运行 `node --test scripts/gateway-route-contract.test.mjs`，自动发现生产 Controller 并校验网关目标服务与内部路径隔离。失败不得提交或标记完成；网关配置变化必须列入部署清单，不以业务服务单测代替入口检查。
+
+- 跨服务修改先检查调用方 `client/`、被调用方 Controller/DTO、`src/main/resources/openapi/` 和双方契约测试；禁止共享领域 Entity。
+- 修改 Java 方法、构造器、Controller、Client、DTO 或 Mapper 参数签名时，先用 `rg` 定向查找符号及旧参数形态，并同步更新 `src/main/`、`src/test/`、Mock、Fixture、契约测试和脚本中的全部调用点。新增可选参数也必须补齐旧测试调用，不能因生产调用已更新就视为完成。
+- 所有生产 MyBatis Mapper 接口必须显式标记 `@Mapper`；每个持久化服务只允许在启动类使用一次服务根包 `@MapperScan(..., annotationClass = Mapper.class)`，不得新增子域包白名单或分散的 `*MapperConfiguration`。新增或移动 Mapper 后先运行 `node scripts/mapper-scan-contract.mjs`，全量后端回归也会在 Maven 前执行该门禁。
+- 平台后台存在正式列表页时，`*:list` 同时授权列表、详情及只读辅助接口；`create`、`edit`、`delete`、`status`、`approve`、`review`、`export`、`upload`、`complete` 等操作保持独立。当前未上线，不兼容旧独立 `*:view`，Controller 不得使用 `hasAnyAuthority(list, view)`，OpenAPI 和角色初始化只保留 `*:list`。
+- 供应商查询接口固定只使用 `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、数据库或部署环境。
+- Mapper 注册静态合同为 `scripts/mapper-scan-contract.mjs`、`mapper-scan-contract.test.mjs`：自动发现聚合模块、生产 `*Mapper` 接口、服务启动类和分散扫描配置，不启动 Spring、不连接数据库；遗漏注解、扫描根漂移或重新引入子域扫描时直接失败并输出类与文件路径。
+- 单服务镜像构建/部署从 `Jenkinsfile.service`、`deploy/docker/Dockerfile`、`deploy/scripts/deploy-built-service.sh` 进入；新镜像启动失败或健康检查失败时只允许回滚到同服务先前镜像，并保持任务失败，离线合同见 `scripts/deploy-built-service-rollback.test.mjs`。实际部署仍须当前对话明确授权。
+
+## 全量 HTTP 验收脚本路由
+
+- 脚本管理的唯一总索引是 `scripts/README.md`，最近执行规则是 `scripts/AGENTS.md`。仓库级脚本、Admin 内部模块、服务局部合同和部署脚本的目录归属以这两个文件为准，不再通过无范围搜索猜测入口。
+- 全量验收唯一指向测试环境 HTTP：平台端执行 `scripts/admin-test-env-acceptance.mjs`，客户端执行 `scripts/client-test-env-acceptance.mjs`；入库测量与计费专项场景才单独执行 `scripts/client-phase2-test-env-acceptance.mjs`，不替代客户端全量入口。
+- Client 快速下单定向验收使用 `scripts/client-quick-order-test-env-acceptance.mjs`，只验证批量草稿接口、逐行隔离和幂等行为，不提交、不审核，也不替代 Client 全量入口。
+- 固定客户待审核订单使用 `scripts/create-pending-review-orders.mjs`；固定“IT测试”与“义乌仓”、随机真实线路并推进至 `WAIT_SPLIT` 使用 `scripts/it-test-wait-split-bulk.mjs`。二者都是造数入口，不属于全量验证；会写目标环境且不自动清理成功数据。
+- Admin 总入口默认按模块列表覆盖平台全链路；需要定位单个业务时使用 `--modules <name>`，模块名称和静态合同先查 `scripts/admin-test-env-modules/README.md`。
+- 订舱与拖车跨服务完整状态链由 Admin 注册模块 `service-center-flow` 验证，必须复用本轮已放舱订舱并由总入口展开依赖，不得直接执行模块文件或借历史数据。
+- 尾程公网控制由 `phase4-tail-order-controls` 在海外 PDA 前验证整柜接柜仓变更与恢复、单/批目的仓变更、单/批合托标记、CSV 导出、订单费用、暂扣/解除、八个人工节点和逐票人工计划；目的港码头拖车由 `phase5-terminal-drayage` 在卸柜后验证选车队、预约提柜、实际提柜和实际还柜，`phase4-carrier-nodes` 只读核验最终船节点终态。
+- 这些脚本会创建、更新或最终停用测试数据，必须在当前对话明确授权测试环境验收后执行，并保存 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 通过不代表视觉验收完成。
+- 修改脚本目录、入口或说明后，至少运行 `node --test scripts/script-documentation-contract.test.mjs`；修改 `AGENTS.md` 后继续运行 `./scripts/agents-index-contract.ps1`。两者均为离线只读合同，不能代替真实 HTTP 验收。
+
+## 业务域文档入口
+
+- 订单与客户：`../docs/订单与客户/README.md`、`../docs/订单与客户/订单与客户头程订单闭环设计.md`
+- 入库测量与计费：`../docs/入库测量与计费/README.md`、`../docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`、需求确认清单及联调报告
+- 国内货柜履约：`../docs/国内货柜履约/README.md`、`../docs/国内货柜履约/国内货柜履约开工门禁.md`、`../docs/国内货柜履约/国内货柜履约开发规划.md`、`../docs/国内货柜履约/国内货柜履约需求确认表.md`、页面与原型清单
+- 海外仓业务：`../docs/海外仓业务/README.md`；海外入口 `gateway-overseas/`，尾程与入仓库存 `lastleg-service/`，海外仓储资源 `warehouse-overseas-service/`
+- 海外仓全流程：以正式 Controller、前端路由、权限、SQL 与跨区事件契约为范围依据；海外接柜、入仓、库存、库内服务、排车、出库、派送、一件代发、异常退回和客户回访进入 `lastleg-service/`，国内 SKU/箱唛及暂扣协同进入 `order/`、`firstleg/`、`common-event-contract/`
+- 财务：`../docs/财务管理/README.md` 中已确认的范围、对象、状态和接口约束
+
+全量验收任务再读取对应阶段进度表、验收报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。

Jenkinsfile

@@ -1,29 +1,147 @@
 def serviceModules = [
-    'gateway', 'auth', 'iam', 'firstleg', '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',
-    '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',
-    'order': 'order/target/order-service-1.0.0-SNAPSHOT.jar',
-    'warehouse': 'warehouse/target/warehouse-service-1.0.0-SNAPSHOT.jar',
-    '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',
-    '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'
+def serviceCheckboxes = [
+    'gateway': 'SERVICE_GATEWAY',
+    'gateway-overseas': 'SERVICE_GATEWAY_OVERSEAS',
+    'auth': 'SERVICE_AUTH',
+    'iam': 'SERVICE_IAM',
+    'firstleg': 'SERVICE_FIRSTLEG',
+    'finance': 'SERVICE_FINANCE',
+    'order': 'SERVICE_ORDER',
+    'warehouse': 'SERVICE_WAREHOUSE',
+    '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', '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) {
+    if (!description?.startsWith('AUTO ')) return null
+    int markerIndex = description.indexOf(' | ')
+    if (markerIndex < 0) return null
+    String commit = description.substring('AUTO '.length(), markerIndex).trim()
+    if (!(commit ==~ /[0-9a-fA-F]{7,40}/)) return null
+    String state = description.substring(markerIndex + ' | '.length()).trim()
+    List<String> failedServices = []
+    if (state.startsWith('RESULTS')) {
+        String summary = state.substring('RESULTS'.length()).trim()
+        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
+            }
+        }
+    } else if (state.startsWith('PENDING')) {
+        // 上一轮若在统一测试、排队或并行部署期间失败/取消，description 仍是 PENDING。
+        // 将该轮已选服务作为精确补跑范围，同时让 Git 基线前进到该轮提交，
+        // 避免回退到很早的成功构建后把历史公共文件再次解释成全量变更。
+        String selected = state.substring('PENDING'.length()).trim()
+        int suffixIndex = selected.indexOf(' | ')
+        if (suffixIndex >= 0) selected = selected.substring(0, suffixIndex).trim()
+        failedServices.addAll(selected.split(',').collect { it.trim() }
+            .findAll { allowedServices.contains(it) })
+    } else {
+        return null
+    }
+    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)
+        // 完成的 RESULTS 和中断留下的 PENDING 都能推进 AUTO 基线；PENDING 中的服务会被精确补跑。
+        if (state != null) return state
+        candidate = candidate.previousBuild
+        inspected++
+    }
+    return null
+}
+
+def environmentChoicesForJob(String jobBaseName) {
+    return [fixedEnvironmentForJob(jobBaseName) ?: 'test']
+}
+
+def fixedEnvironmentForJob(String jobBaseName) {
+    switch (jobBaseName) {
+        case 'backend-java-dev':
+            return 'development'
+        case 'backend-java':
+            return 'test'
+        case 'backend-java-prod':
+            return 'production'
+        default:
+            return null
+    }
+}
+
+def fixedDownstreamJobPrefixForJob(String jobBaseName) {
+    switch (jobBaseName) {
+        case 'backend-java-dev':
+            return 'baiyue-firstleg-dev-'
+        case 'backend-java':
+            return 'baiyue-firstleg-'
+        case 'backend-java-prod':
+            return 'baiyue-firstleg-prod-'
+        default:
+            return null
+    }
+}
+
+def downstreamJobPrefixChoicesForJob(String jobBaseName) {
+    return [fixedDownstreamJobPrefixForJob(jobBaseName) ?: 'baiyue-firstleg-']
+}
+
 pipeline {
-    agent { label 'docker-java17' }
+    // 总控流水线只识别变更并调度独立的服务 Job；实际 Maven、镜像和部署在 Jenkinsfile.service 中完成。
+    agent none
 
     options {
         disableConcurrentBuilds()
@@ -32,38 +150,128 @@ pipeline {
     }
 
     parameters {
-        choice(name: 'BUILD_MODE', choices: ['AUTO', 'SELECT', 'ALL'], description: 'AUTO 按 Git 变更识别；SELECT 手工指定；ALL 构建全部服务')
-        string(name: 'SERVICE', defaultValue: 'gateway', description: 'SELECT 模式填写服务名，多个服务用英文逗号分隔')
-        choice(name: 'ENVIRONMENT', choices: ['test', 'staging', 'production'], description: '部署环境')
-        booleanParam(name: 'DEPLOY', defaultValue: false, description: '构建成功后是否部署')
+        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）')
+        booleanParam(name: 'SERVICE_FINANCE', defaultValue: false, description: '财务服务（finance）')
+        booleanParam(name: 'SERVICE_ORDER', defaultValue: false, description: '订单服务（order）')
+        booleanParam(name: 'SERVICE_WAREHOUSE', defaultValue: false, description: '仓库与往来单位服务（warehouse）')
+        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_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: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试；生产构建不建议勾选')
-        string(name: 'IMAGE_REPOSITORY', defaultValue: 'registry.example.com/your-group/baiyue-firstleg', description: 'GitLab Container Registry 项目地址')
-    }
-
-    environment {
-        REGISTRY_CREDENTIALS = 'gitlab-registry-credentials'
+        string(name: 'IMAGE_REPOSITORY', defaultValue: 'git.buggoglobal.com/java-project/baiyue-firstleg', description: '共享镜像仓库地址')
+        string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'git.buggoglobal.com/java-project/eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
+        choice(name: 'DOWNSTREAM_JOB_PREFIX', choices: downstreamJobPrefixChoicesForJob(env.JOB_BASE_NAME), description: '由当前总控 Job 固定的单服务 Job 前缀')
     }
 
     stages {
         stage('确定构建范围') {
+            agent { label 'java-builder' }
             steps {
                 script {
+                    String resolvedEnvironment = fixedEnvironmentForJob(env.JOB_BASE_NAME)
+                    String resolvedJobPrefix = fixedDownstreamJobPrefixForJob(env.JOB_BASE_NAME)
+                    if (!resolvedEnvironment || !resolvedJobPrefix) {
+                        error("未配置总控 Job ${env.JOB_BASE_NAME} 的固定部署环境，拒绝继续")
+                    }
+                    if (params.ENVIRONMENT != resolvedEnvironment ||
+                        params.DOWNSTREAM_JOB_PREFIX?.trim() != resolvedJobPrefix) {
+                        echo "忽略外部传入的环境或 Job 前缀；${env.JOB_BASE_NAME} 固定使用 ${resolvedEnvironment} / ${resolvedJobPrefix}"
+                    }
+                    env.RESOLVED_ENVIRONMENT = resolvedEnvironment
+                    echo "Job ${env.JOB_BASE_NAME} 使用部署环境: ${env.RESOLVED_ENVIRONMENT}"
+
+                    if (env.RESOLVED_ENVIRONMENT == 'production') {
+                        sh '''
+                            set -eu
+                            git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+                            test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" || {
+                              echo "生产构建只允许 origin/main 当前提交；请先通过 Pull Request 合并到 main 后再部署" >&2
+                              exit 1
+                            }
+                        '''
+                    }
+
+                    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
+
+                    env.RESOLVED_JOB_PREFIX = resolvedJobPrefix
+                    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
                     } else if (params.BUILD_MODE == 'SELECT') {
-                        selected = params.SERVICE.split(',').collect { it.trim() }.findAll { it }
+                        selected = serviceModules.findAll { service ->
+                            params[serviceCheckboxes[service]] == true
+                        }
+                        if (!selected) {
+                            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) {
+                            // 首次启用或旧构建记录已淘汰时，只比较当前提交的直接父提交。
+                            // 需要初始化全部服务时应显式使用 ALL，不能因历史成功基线过旧而意外全量部署。
+                            base = sh(script: 'git rev-parse HEAD^ 2>/dev/null || true', returnStdout: true).trim()
+                            if (base) echo "AUTO 未找到历史记录，本次使用直接父提交作为基线: ${base}"
+                        }
                         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 }
-                            boolean commonChanged = changed.any { path -> commonPaths.any { prefix -> path == prefix || path.startsWith(prefix) } }
-                            selected = commonChanged ? serviceModules : serviceModules.findAll { module ->
-                                changed.any { it == module || it.startsWith("${module}/") }
+                            boolean databaseChanged = changed.any { path ->
+                                databaseMigrationPaths.any { prefix -> path.startsWith(prefix) }
                             }
+                            env.DATABASE_CHANGE_DETECTED = databaseChanged ? 'true' : 'false'
+                            List serviceRelevantChanges = changed.findAll { path ->
+                                !databaseMigrationPaths.any { prefix -> path.startsWith(prefix) }
+                            }
+                            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(',') ?: '无'}"
                         }
                     }
 
@@ -71,28 +279,83 @@ pipeline {
                     if (invalid) {
                         error("未知服务: ${invalid.join(', ')}；允许值: ${serviceModules.join(', ')}")
                     }
+
                     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.NO_SERVICE_CHANGE = 'true'
-                        env.SELECTED_SERVICES = ''
+                        currentBuild.description = params.BUILD_MODE == 'AUTO'
+                            ? "AUTO ${env.IMAGE_TAG} | RESULTS"
+                            : (env.DATABASE_CHANGE_DETECTED == 'true'
+                                ? '仅数据库迁移变更 | 需单独审核执行'
+                                : '没有需要构建的业务服务')
                     } else {
-                        env.NO_SERVICE_CHANGE = 'false'
-                        env.SELECTED_SERVICES = selected.join(',')
-                        env.IMAGE_TAG = sh(script: 'git rev-parse --short=12 HEAD', returnStdout: true).trim()
-                        currentBuild.description = "${env.SELECTED_SERVICES} | ${env.IMAGE_TAG}"
-                        echo "本次构建服务: ${env.SELECTED_SERVICES}"
+                        String databaseSuffix = env.DATABASE_CHANGE_DETECTED == 'true' ? ' | DB migration pending' : ''
+                        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') {
+                        echo '检测到 deploy/sql/ 变更：AUTO 不据此扩大服务范围；统一 SQL 须独立审核并执行。'
                     }
                 }
             }
         }
 
-        stage('Maven 测试与打包') {
-            when { expression { env.NO_SERVICE_CHANGE != 'true' } }
+        stage('生产环境部署确认（仅 production 执行）') {
+            when {
+                allOf {
+                    expression { params.DEPLOY && env.RESOLVED_ENVIRONMENT == 'production' && env.NO_SERVICE_CHANGE != 'true' }
+                }
+            }
+            steps {
+                input message: "确认将 ${env.SELECTED_SERVICES} 的镜像 ${env.IMAGE_TAG} 分别部署到生产环境？", ok: '确认部署'
+            }
+        }
+
+        stage('Gateway 路由静态门禁') {
+            when {
+                expression { env.NO_SERVICE_CHANGE != 'true' }
+            }
+            agent { label 'java-builder' }
+            steps {
+                sh 'node --test scripts/gateway-route-contract.test.mjs'
+            }
+        }
+
+        stage('统一 Maven 测试门禁') {
+            when {
+                expression { env.NO_SERVICE_CHANGE != 'true' && !params.SKIP_TESTS }
+            }
+            agent { label 'java-builder' }
+            tools { maven 'maven-3.8.8' }
             steps {
                 script {
-                    String testOption = params.SKIP_TESTS ? '-DskipTests' : ''
-                    sh "mvn --batch-mode --errors --fail-at-end -pl ${env.SELECTED_SERVICES} -am clean package ${testOption}"
+                    String selectedModules = env.SELECTED_SERVICES.split(',')
+                        .collect { it.trim() }
+                        .findAll { it }
+                        .join(',')
+                    echo "统一测试本次选中的服务及其公共依赖: ${selectedModules}"
+                    sh """
+                        test \"\$(git rev-parse HEAD)\" = \"${env.SOURCE_COMMIT}\"
+                        find . -type f -path '*/target/surefire-reports/TEST-*.xml' -delete
+                        mvn --settings deploy/maven/settings-ci.xml --batch-mode --errors -pl ${selectedModules} -am test
+                    """
+                    echo "统一测试门禁通过: ${env.SOURCE_COMMIT}；下游单服务任务不再重复执行测试"
                 }
             }
             post {
@@ -102,53 +365,68 @@ pipeline {
             }
         }
 
-        stage('构建并推送镜像') {
+        stage('并行调度独立服务 Job') {
             when { expression { env.NO_SERVICE_CHANGE != 'true' } }
             steps {
                 script {
-                    String registryHost = params.IMAGE_REPOSITORY.tokenize('/')[0]
-                    withCredentials([usernamePassword(credentialsId: env.REGISTRY_CREDENTIALS, usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD')]) {
-                        sh 'printf %s "$REGISTRY_PASSWORD" | docker login -u "$REGISTRY_USER" --password-stdin "' + registryHost + '"'
-                        env.SELECTED_SERVICES.split(',').each { service ->
-                            String image = "${params.IMAGE_REPOSITORY}/${service}:${env.IMAGE_TAG}"
-                            sh "docker build -f deploy/docker/Dockerfile --build-arg JAR_FILE=${serviceJars[service]} -t ${image} ."
-                            sh "docker push ${image}"
+                    Map branches = [:]
+                    env.SELECTED_SERVICES.split(',').each { selectedService ->
+                        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,
+                                wait: true,
+                                propagate: false,
+                                parameters: [
+                                    string(name: 'SOURCE_COMMIT', value: env.SOURCE_COMMIT),
+                                    string(name: 'IMAGE_TAG', value: downstreamImageTag),
+                                    string(name: 'ENVIRONMENT', value: env.RESOLVED_ENVIRONMENT),
+                                    booleanParam(name: 'DEPLOY', value: params.DEPLOY),
+                                    // 总控已完成统一测试，或用户已明确选择跳过；下游仅负责编译、打包和部署。
+                                    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),
+                                    // Choice 参数始终传递所有新旧 Job 都接受的单区值；
+                                    // 双区意图通过现有 IMAGE_TAG 参数携带，由下游还原真实镜像标签。
+                                    string(name: 'EVENT_BRIDGE_REGION', value: downstreamBridgeRegion)
+                                ]
+                            )
+                            downstreamResults[service] = downstreamBuild.result ?: 'UNKNOWN'
+                            echo "${service} 执行结果: ${downstreamResults[service]} (${downstreamBuild.absoluteUrl})"
                         }
-                        sh "docker logout ${registryHost} || true"
                     }
+                    parallel branches
                 }
             }
         }
 
-        stage('生产部署确认') {
-            when {
-                allOf {
-                    expression { params.DEPLOY && params.ENVIRONMENT == 'production' && env.NO_SERVICE_CHANGE != 'true' }
-                }
-            }
-            steps {
-                input message: "确认将 ${env.SELECTED_SERVICES} 的镜像 ${env.IMAGE_TAG} 部署到生产环境？", ok: '确认部署'
-            }
-        }
-
-        stage('部署') {
-            when {
-                allOf {
-                    expression { params.DEPLOY && env.NO_SERVICE_CHANGE != 'true' }
-                }
-            }
+        stage('汇总服务结果') {
+            when { expression { env.NO_SERVICE_CHANGE != 'true' } }
             steps {
                 script {
-                    String credentialId = "firstleg-${params.ENVIRONMENT}-env"
-                    withCredentials([file(credentialsId: credentialId, variable: 'DEPLOY_ENV_FILE')]) {
-                        sh "sh deploy/scripts/deploy-services.sh '${params.ENVIRONMENT}' '${params.IMAGE_REPOSITORY}' '${env.IMAGE_TAG}' '${env.SELECTED_SERVICES}' \"\$DEPLOY_ENV_FILE\""
+                    List failed = downstreamResults.findAll { service, result -> result != 'SUCCESS' }
+                        .collect { service, result -> "${service}=${result}" }
+                    String summary = downstreamResults.collect { service, result -> "${service}=${result}" }.join(', ')
+                    echo "单服务执行汇总: ${summary}"
+                    currentBuild.description = params.BUILD_MODE == 'AUTO'
+                        ? "AUTO ${env.IMAGE_TAG} | RESULTS ${summary}"
+                        : "${env.IMAGE_TAG} | ${summary}"
+                    if (failed) {
+                        unstable("部分服务执行失败，但其他服务已独立完成：${failed.join(', ')}")
                     }
                 }
             }
         }
     }
 
-    post {
-        always { cleanWs(deleteDirs: true, notFailBuild: true) }
-    }
 }

Jenkinsfile.service

@@ -0,0 +1,320 @@
+def serviceModules = [
+    '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',
+    'finance': 'finance/target/finance-service-1.0.0-SNAPSHOT.jar',
+    'order': 'order/target/order-service-1.0.0-SNAPSHOT.jar',
+    'warehouse': 'warehouse/target/warehouse-service-1.0.0-SNAPSHOT.jar',
+    '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'
+]
+
+def fixedEnvironmentForServiceJob(String jobBaseName) {
+    if (jobBaseName?.startsWith('baiyue-firstleg-dev-')) {
+        return 'development'
+    }
+    if (jobBaseName?.startsWith('baiyue-firstleg-prod-')) {
+        return 'production'
+    }
+    if (jobBaseName?.startsWith('baiyue-firstleg-')) {
+        return 'test'
+    }
+    return null
+}
+
+def environmentChoicesForServiceJob(String jobBaseName) {
+    return [fixedEnvironmentForServiceJob(jobBaseName) ?: 'test']
+}
+
+pipeline {
+    // 构建在任意 java-builder 节点执行，部署再回到目标环境节点。
+    agent none
+
+    options {
+        skipDefaultCheckout(true)
+        disableConcurrentBuilds()
+        timestamps()
+        buildDiscarder(logRotator(numToKeepStr: '30'))
+    }
+
+    parameters {
+        string(name: 'SOURCE_COMMIT', defaultValue: '', description: '必须构建的 Git commit；通常由总控 Job 传入')
+        string(name: 'IMAGE_TAG', defaultValue: '', description: '不可变镜像标签；通常使用 Git commit 前 12 位')
+        choice(name: 'ENVIRONMENT', choices: environmentChoicesForServiceJob(env.JOB_BASE_NAME), description: '由当前单服务 Job 固定的部署环境')
+        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: 'git.buggoglobal.com/java-project/baiyue-firstleg', description: '共享镜像仓库基础路径，不包含服务名和标签')
+        string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'git.buggoglobal.com/java-project/eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
+    }
+
+    environment {
+        REGISTRY_CREDENTIALS = 'gitea-registry-token'
+        MAVEN_SETTINGS = 'deploy/maven/settings-ci.xml'
+        MAVEN_OPTS = '-Dfile.encoding=UTF-8 -Dmaven.wagon.http.retryHandler.count=3'
+    }
+
+    stages {
+        stage('构建并发布单服务') {
+            agent { label 'java-builder' }
+            tools { maven 'maven-3.8.8' }
+            stages {
+                stage('校验参数并检出指定提交') {
+                    steps {
+                        checkout scm
+
+                        script {
+                            String service = serviceModules.find { candidate ->
+                                env.JOB_BASE_NAME?.endsWith("-${candidate}")
+                            }
+                            String sourceCommit = params.SOURCE_COMMIT?.trim()
+                            String imageTag = params.IMAGE_TAG?.trim()
+                            String imageRepository = params.IMAGE_REPOSITORY?.trim()
+                            String resolvedEnvironment = fixedEnvironmentForServiceJob(env.JOB_BASE_NAME)
+
+                            if (!sourceCommit) {
+                                sourceCommit = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
+                            }
+                            if (!imageTag) {
+                                imageTag = sh(script: 'git rev-parse --short=12 HEAD', returnStdout: true).trim()
+                            }
+
+                            if (!serviceModules.contains(service)) {
+                                error("无法从 Job 名称 ${env.JOB_BASE_NAME} 识别服务；名称必须以以下服务之一结尾: ${serviceModules.join(', ')}")
+                            }
+                            if (!resolvedEnvironment) {
+                                error("未配置单服务 Job ${env.JOB_BASE_NAME} 的固定部署环境，拒绝继续")
+                            }
+                            if (params.ENVIRONMENT != resolvedEnvironment) {
+                                echo "忽略外部传入的环境 ${params.ENVIRONMENT}；${env.JOB_BASE_NAME} 固定使用 ${resolvedEnvironment}"
+                            }
+                            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')
+                            }
+                            if (!imageTag || !(imageTag ==~ /[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}/)) {
+                                error('IMAGE_TAG 不是合法的 Docker 镜像标签')
+                            }
+                            if (!imageRepository || imageRepository.contains('://')) {
+                                error('IMAGE_REPOSITORY 不能为空且不能包含协议前缀')
+                            }
+                            if (!imageRepository.contains('/')) {
+                                error('IMAGE_REPOSITORY 必须使用 host[:port]/owner/image 格式')
+                            }
+
+                            env.RESOLVED_SERVICE = service
+                            env.RESOLVED_ENVIRONMENT = resolvedEnvironment
+                            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(env.RESOLVED_ENVIRONMENT)) {
+                                    error('事件桥 BOTH 仅支持开发或测试环境；预发布和生产必须明确选择 CN 或 OVERSEAS')
+                                }
+                            }
+                        }
+
+                        sh '''
+                            if ! git cat-file -e "${RESOLVED_SOURCE_COMMIT}^{commit}" 2>/dev/null; then
+                              git fetch --no-tags origin
+                            fi
+                            git cat-file -e "${RESOLVED_SOURCE_COMMIT}^{commit}"
+                            git checkout --detach "${RESOLVED_SOURCE_COMMIT}"
+                            test "$(git rev-parse HEAD)" = "$(git rev-parse "${RESOLVED_SOURCE_COMMIT}^{commit}")"
+                        '''
+
+                        sh '''
+                            if [ "${RESOLVED_ENVIRONMENT}" = "production" ]; then
+                              git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+                              git merge-base --is-ancestor "${RESOLVED_SOURCE_COMMIT}" origin/main || {
+                                echo "生产构建只允许已经合并到 main 的提交" >&2
+                                exit 1
+                              }
+                            fi
+                        '''
+
+                        script {
+                            currentBuild.description = "${env.RESOLVED_SERVICE} | ${env.RESOLVED_IMAGE_TAG} | ${env.RESOLVED_ENVIRONMENT} | ${env.NODE_NAME}"
+                            echo "独立构建服务: ${env.RESOLVED_SERVICE}，提交: ${env.RESOLVED_SOURCE_COMMIT}，节点: ${env.NODE_NAME}"
+                        }
+                    }
+                }
+
+                stage('Maven 测试与打包') {
+                    steps {
+                        script {
+                            boolean coordinatorPinnedCommit = params.SOURCE_COMMIT?.trim() as boolean
+                            if (env.RESOLVED_ENVIRONMENT == 'production' && params.SKIP_TESTS && !coordinatorPinnedCommit) {
+                                error('生产环境手工构建禁止跳过测试；总控流水线可在统一测试通过后执行快速打包')
+                            }
+                            boolean skipTestExecution = env.RESOLVED_ENVIRONMENT == 'test' || params.SKIP_TESTS
+                            String testOption = skipTestExecution ? '-DskipTests' : ''
+                            if (params.SKIP_TESTS && coordinatorPinnedCommit) {
+                                echo "总控已处理提交 ${env.RESOLVED_SOURCE_COMMIT} 的测试门禁，本单服务仅编译测试源码并打包"
+                            } else if (env.RESOLVED_ENVIRONMENT == 'test') {
+                                echo '测试环境快速部署：编译主代码和测试代码，但不重复执行单元测试；完整测试由提交门禁和预发布执行'
+                            }
+                            sh "mvn --settings ${env.MAVEN_SETTINGS} --batch-mode --errors -pl ${env.RESOLVED_SERVICE} -am clean package ${testOption}"
+                        }
+                    }
+                    post {
+                        always {
+                            junit allowEmptyResults: true, testResults: '**/target/surefire-reports/TEST-*.xml'
+                        }
+                    }
+                }
+
+                stage('构建并发布单服务镜像') {
+                    steps {
+                        script {
+                            String image = "${env.RESOLVED_IMAGE_REPOSITORY}/${env.RESOLVED_SERVICE}:${env.RESOLVED_IMAGE_TAG}"
+                            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'"
+
+                            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 {
+                beforeAgent true
+                expression { params.DEPLOY && ['development', 'test'].contains(env.RESOLVED_ENVIRONMENT) }
+            }
+            agent none
+            steps {
+                script {
+                    String deploySlotLabel = "firstleg-${env.RESOLVED_ENVIRONMENT}-deploy-slot"
+                    String serviceDeployResource = "firstleg-${env.RESOLVED_ENVIRONMENT}-${env.RESOLVED_SERVICE}-deploy"
+                    String credentialId = "firstleg-${env.RESOLVED_ENVIRONMENT}-env"
+                    String targetLabel = env.RESOLVED_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} 本机部署到 ${env.RESOLVED_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 '${env.RESOLVED_ENVIRONMENT}' '${env.RESOLVED_IMAGE_REPOSITORY}' '${env.RESOLVED_IMAGE_TAG}' '${env.RESOLVED_SERVICE}' \"\$DEPLOY_ENV_FILE\""
+                                            }
+                                        }
+                                    }
+                                } finally {
+                                    cleanWs(deleteDirs: true, notFailBuild: true)
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        stage('部署生产环境单个服务') {
+            when {
+                beforeAgent true
+                expression { params.DEPLOY && env.RESOLVED_ENVIRONMENT == 'production' }
+            }
+            agent { label 'java-builder' }
+            steps {
+                deleteDir()
+                unstash 'deployment-files'
+                script {
+                    String credentialId = "firstleg-${env.RESOLVED_ENVIRONMENT}-env"
+                    String serviceDeployResource = "firstleg-production-${env.RESOLVED_SERVICE}-deploy"
+                    lock(resource: serviceDeployResource, inversePrecedence: true) {
+                        withCredentials([
+                            file(credentialsId: credentialId, variable: 'DEPLOY_ENV_FILE'),
+                            usernamePassword(credentialsId: 'gitea-production-pull-token', usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD'),
+                            sshUserPrivateKey(credentialsId: 'firstleg-production-ssh', keyFileVariable: 'TARGET_SSH_KEY', usernameVariable: 'TARGET_SSH_USER'),
+                            string(credentialsId: 'firstleg-production-host', variable: 'TARGET_SSH_HOST'),
+                            file(credentialsId: 'firstleg-production-known-hosts', variable: 'TARGET_SSH_KNOWN_HOSTS')
+                        ]) {
+                            withEnv([
+                                'TARGET_DEPLOY_DIR=/data/firstleg/deploy/services',
+                                'TARGET_SSH_TARGET=' + env.TARGET_SSH_USER + '@' + env.TARGET_SSH_HOST,
+                                "EVENT_BRIDGE_REGION_OVERRIDE=${params.EVENT_BRIDGE_REGION}"
+                            ]) {
+                                sh "sh deploy/scripts/deploy-built-service.sh '${env.RESOLVED_ENVIRONMENT}' '${env.RESOLVED_IMAGE_REPOSITORY}' '${env.RESOLVED_IMAGE_TAG}' '${env.RESOLVED_SERVICE}' \"\$DEPLOY_ENV_FILE\""
+                            }
+                        }
+                    }
+                }
+            }
+            post {
+                always {
+                    cleanWs(deleteDirs: true, notFailBuild: true)
+                }
+            }
+        }
+    }
+
+    post {
+        success {
+            echo "${env.RESOLVED_SERVICE} 已独立完成构建${params.DEPLOY ? '和部署' : ''}"
+        }
+    }
+}

README.md

@@ -1,32 +1,54 @@
-# 百悦头程平台
+# 柏悦头程平台
 
-本仓库承载国内头程业务，负责统一登录、租户、用户、角色、菜单、按钮权限、订单、国内仓储、头程履约以及国内公共能力。尾程业务不进入本仓库，通过版本化跨区域事件与尾程仓库协作。
+本仓库承载国内头程与海外仓后端，包含统一认证、国内订单与履约、国内外仓储资源、海外尾程与入仓业务，以及跨区域事件桥和公共能力。国内、海外仍保持独立数据库、Nacos 命名空间与部署边界，通过版本化跨区域事件协作。
+
+> 当前主体模型：业务单租户，产品只包含“平台—客户”两级。现有 `tenant_id > 0`、`tenantId` 和 `Tenant*` 是历史兼容命名，当前承载客户归属与隔离；`tenant_id = 0` 是平台账号、平台 RBAC 和平台公共主数据的技术作用域，不是可管理租户。平台公共仓库、往来单位、快递公司、托盘、库位等归属 `0`，客户订单、文件和费用归属客户 ID。未经过独立迁移设计，不得新增真实租户层或把现有客户隔离字段改义为上级租户。
 
 ## 模块
 
 - `auth`：统一登录、令牌签发与刷新。
-- `iam`：租户、用户、角色、菜单、按钮权限和数据范围。
+- `iam`：客户主档、用户、企业成员、角色、菜单、按钮权限和数据范围；部分路径、表和类保留 `tenant` 历史命名。
 - `order`：订单主数据及订单状态编排。
 - `firstleg`：头程揽收、入仓、装载、发运和交接。
 - `warehouse`：国内仓储能力。
-- `file`、`print`、`audit-service`、`integration-service`：国内公共业务能力。
-- `event-bridge-service`：跨区域事件接收幂等和投递记录基础骨架；真实跨区发送、重试调度和死信补投仍需完成。
+- `file`、`print`、`audit-service`、`integration-service`：国内公共业务能力；Print 调用方接入见 `print/README.md`。
+- `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
 ```
 
-2026-07-30 一期前端联调缺口已完成真实回归：19 个 Reactor 项目构建成功，75 项单元及组件测试、68 项认证与 IAM 真实 API、37 项订单与仓库真实 API 全部通过。详细证据见 `docs/phase1-business-maturity-regression-report.md`。
+GitLab 在独立 Node 镜像中自动执行拓扑合同，随后才允许服务制品打包。Maven `verify` 会为执行过测试且产生覆盖率数据的模块生成 `target/site/jacoco/index.html` 与 `jacoco.xml`；当前只生成报告，不设置覆盖率阈值，也不改变测试选择。Jenkins 的 `java-builder` 尚未在仓库中声明 Node 运行时，因此暂不重复执行该 Node 合同，以 GitLab 门禁和上述本地命令为准。
 
-本地一期完整联调启动顺序为：IAM、Auth、Firstleg、Order、Warehouse、File、Print，最后启动 Gateway。往来单位不是独立服务，由 `warehouse-service` 承载并保存到 `baiyue_warehouse.wh_partner`。
+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`。海外服务通过独立 Compose 与 Nacos 配置启动，不与国内服务共享数据库或配置命名空间。
 
 国内 Nacos 配置位于 `config/nacos/cn`。数据库、Redis、Nacos 和 RocketMQ 的生产密码必须通过环境变量或配置中心密文注入，禁止提交明文密码。
 
+## 容器日志
+
+所有服务只向标准输出和标准错误写日志，不在容器内生成应用日志文件，也不把应用日志目录挂载到宿主机。国内、海外及基础设施 Compose 默认使用宝塔可见的 Docker `json-file` 日志驱动，并设置强制轮转；仍可通过 `docker logs` 排查。文件服务的 `/data/files` 是业务文件目录，不属于日志目录，必须继续持久化。
+
+单容器默认保留 `50m × 3`，可在各环境部署变量中覆盖：
+
+| 环境 | `DOCKER_LOG_DRIVER` | `DOCKER_LOG_MAX_SIZE` | `DOCKER_LOG_MAX_FILE` | 长期留存 |
+|---|---|---:|---:|---|
+| 开发 | `json-file` | `20m` | `2` | 不要求 |
+| 测试 | `json-file` | `50m` | `3` | 不要求 |
+| 生产前期 | `json-file` | `100m` | `5` | 宝塔与 `docker logs` 提供短期排障能力 |
+
+当前优先保证宝塔可观测性，因此不启用 `json-file` 压缩或非阻塞投递，避免面板无法读取轮转文件或在日志压力下静默丢弃。接入集中日志系统后，可通过 `DOCKER_LOG_DRIVER` 切换驱动，并由集中系统承担长期检索与留存。
+
+调整日志策略后必须重新创建容器；只重启既有容器不会改变其日志驱动。历史 `/data/logs/baiyue-firstleg` 文件和旧容器日志不自动删除，确认无需保留后再单独清理。
+
 ## 网关跨域配置
 
 本地默认允许商户端和后台端从 `localhost/127.0.0.1` 的 `5173/5174` 端口访问网关。部署到测试或生产环境时，必须通过 `CORS_ALLOWED_ORIGINS` 配置两个前端的明确地址，多个地址用英文逗号分隔，例如：
@@ -39,4 +61,4 @@ CORS_ALLOWED_ORIGINS=https://merchant.example.com,https://admin.example.com
 
 ## 仓库边界
 
-详细规则见 `docs/repository-boundary.md`。本仓不得引入尾程源码，不允许跨区域共享数据库、Redis 或 Nacos，也不允许通过公网直接调用对方内部服务。
+仓库边界、服务调用和拆分规则见 `docs/头程项目目录结构与服务说明.md` 的“项目定位”“主要调用关系”和“开发和拆分约束”。国内与海外服务不允许跨区域共享数据库、Redis 或 Nacos，也不允许通过公网直接调用对方内部服务。

audit-service/AGENTS.md

@@ -0,0 +1,30 @@
+# Audit Service 模块指引
+
+## 职责边界
+
+- Mapper 只由 `BaiyueAuditApplication.java` 对 `com.baiyue.audit` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。
+- 负责接收 `common-audit` 产生的审计事件并持久化到 `baiyue_audit`。
+- 审计注解、切面、脱敏和发送策略在 `common-audit/`；本服务不复制业务服务的审计采集逻辑。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 应用入口 | `src/main/java/com/baiyue/audit/BaiyueAuditApplication.java` |
+| 内部接收 API | `controller/AuditIngestController.java`（`/internal/audit/events`） |
+| 平台日志查询 API | `controller/PlatformAuditLogController.java`（`/api/platform/v1/audit/logs`）、`service/AuditLogQueryService.java`；列表与详情统一使用 `platform:audit:list` |
+| 接收 DTO | `dto/AuditIngestRequest.java` |
+| 入库编排 | `service/AuditIngestService.java` |
+| 持久化 | `entity/AuditLogEntity.java`、`mapper/AuditLogMapper.java`、`repository/AuditEventRepository.java` |
+| 表结构 | `src/main/resources/db/audit.sql` |
+| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/audit-service.yml` |
+
+## 修改与验证
+
+- 当前接收接口尚未实现内部令牌保护，仅适合受控本地/内网联调；部署到共享或生产环境前必须补齐可信服务身份校验，且不对前端开放。
+- `POST /internal/audit/events` 成功接收保留真实 HTTP 202；请求进入 `common-web` 异常处理后的业务/校验失败遵循 HTTP 200 + body code。不要把 202 改成普通 200，也不要把业务失败重新改成 HTTP 4xx/5xx。
+- `common-web/CommonWebAutoConfiguration` 负责在本服务仅扫描 `com.baiyue.audit` 时注册统一异常处理和 Correlation 过滤器；相关改动需连同本模块做启动/上下文验证。
+- 入库前确保密码、Token、证件等敏感信息已脱敏；新增字段时同步检查 `../common-audit/src/main/java/com/baiyue/common/audit/AuditEvent.java` 与发送实现。
+- 平台日志列表不得返回变更前后快照，详情才返回已脱敏 JSON；客户账号不得访问平台查询接口。
+- 审计链路故障不得阻塞核心交易；保留幂等、超时、容量和留存策略的演进空间。
+- 自动化测试位于 `src/test/java/com/baiyue/audit/`，覆盖平台日志查询、Controller 权限、MQ 接收/死信和持久化；从父目录运行 `mvn -pl audit-service -am test`，并按改动验证接收和持久化结果。

audit-service/pom.xml

@@ -27,6 +27,11 @@
             <artifactId>baiyue-common-openapi</artifactId>
             <version>${project.version}</version>
         </dependency>
+        <dependency>
+            <groupId>com.baiyue.shared</groupId>
+            <artifactId>baiyue-common-security</artifactId>
+            <version>${project.version}</version>
+        </dependency>
         <dependency>
             <groupId>com.baomidou</groupId>
             <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
@@ -36,6 +41,10 @@
             <artifactId>mysql-connector-j</artifactId>
             <scope>runtime</scope>
         </dependency>
+        <dependency>
+            <groupId>org.apache.rocketmq</groupId>
+            <artifactId>rocketmq-spring-boot-starter</artifactId>
+        </dependency>
         <dependency>
             <groupId>com.alibaba.cloud</groupId>
             <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>

audit-service/src/main/java/com/baiyue/audit/BaiyueAuditApplication.java

@@ -1,15 +1,22 @@
 package com.baiyue.audit;
 
+import com.baiyue.common.core.mybatis.MybatisPlusConfiguration;
+import org.apache.ibatis.annotations.Mapper;
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Import;
+import org.springframework.scheduling.annotation.EnableScheduling;
 
 /**
  * 审计微服务启动入口，初始化 Spring Boot 应用并扫描审计日志 Mapper。
  */
-@MapperScan("com.baiyue.audit.mapper")
+@MapperScan(basePackages = "com.baiyue.audit", annotationClass = Mapper.class)
+@EnableScheduling
+@Import(MybatisPlusConfiguration.class)
 @SpringBootApplication
 public class BaiyueAuditApplication {
+
     public static void main(String[] args) {
         SpringApplication.run(BaiyueAuditApplication.class, args);
     }

audit-service/src/main/java/com/baiyue/audit/controller/AuditIngestController.java

@@ -8,11 +8,15 @@ import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import jakarta.validation.Valid;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.bind.annotation.RequestHeader;
 import org.springframework.web.bind.annotation.RestController;
 
 /**
@@ -25,21 +29,40 @@ import org.springframework.web.bind.annotation.RestController;
 @RestController
 @RequestMapping("/internal/audit/events")
 public class AuditIngestController {
+    private static final String INTERNAL_SERVICE_TOKEN_HEADER = "X-Internal-Service-Token";
+
     @Resource
     private AuditIngestService service;
+
+    @Value("${baiyue.security.internal-service-token:}")
+    private String internalServiceToken;
     @Operation(
         summary = "Ingest business audit event / 写入业务审计事件",
         description = "Validates and stores one sanitized event in baiyue_audit.sys_audit_log. / 校验并将一条脱敏事件写入 baiyue_audit.sys_audit_log。"
     )
     @ApiResponses({
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "202", description = "Event accepted and stored / 事件已接收并存储"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid event payload / 事件载荷无效"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "500", description = "Audit storage failed / 审计存储失败")
     })
     @PostMapping
-    @ResponseStatus(HttpStatus.ACCEPTED)
-    public ApiResponse<Void> ingest(@Valid @RequestBody AuditIngestRequest event) {
+    public ResponseEntity<ApiResponse<Void>> ingest(
+            @RequestHeader(value = INTERNAL_SERVICE_TOKEN_HEADER, required = false) String providedToken,
+            @Valid @RequestBody AuditIngestRequest event) {
+        if (!tokenMatches(providedToken)) {
+            return ResponseEntity.status(HttpStatus.FORBIDDEN)
+                    .body(ApiResponse.failure(com.baiyue.common.core.api.ResultCode.FORBIDDEN,
+                            "Internal service token is invalid", null, null));
+        }
         service.ingest(event);
-        return ApiResponse.success(null);
+        return ResponseEntity.status(HttpStatus.ACCEPTED).body(ApiResponse.success(null));
+    }
+
+    private boolean tokenMatches(String providedToken) {
+        if (providedToken == null || providedToken.isBlank()
+                || internalServiceToken == null || internalServiceToken.isBlank()) {
+            return false;
+        }
+        return MessageDigest.isEqual(
+                internalServiceToken.getBytes(StandardCharsets.UTF_8),
+                providedToken.getBytes(StandardCharsets.UTF_8));
     }
 }

audit-service/src/main/java/com/baiyue/audit/controller/PlatformAuditLogController.java

@@ -0,0 +1,65 @@
+package com.baiyue.audit.controller;
+
+import com.baiyue.audit.dto.AuditLogQuery;
+import com.baiyue.audit.dto.AuditLogResponses;
+import com.baiyue.audit.service.AuditLogQueryService;
+import com.baiyue.audit.service.AuditPlatformScopeGuard;
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.security.AuthenticatedUser;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.annotation.Resource;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.Instant;
+
+/** 平台端统一操作日志查询入口。 */
+@RestController
+@Validated
+@RequestMapping("/api/platform/v1/audit/logs")
+@Tag(name = "Platform audit logs / 平台操作日志")
+public class PlatformAuditLogController {
+    @Resource
+    private AuditLogQueryService service;
+
+    @GetMapping
+    @PreAuthorize("hasAuthority('platform:audit:list')")
+    @Operation(summary = "分页查询操作日志", description = "仅平台端可查询，列表不返回变更前后快照。默认按发生时间、日志 ID 倒序。")
+    public ApiResponse<PageResult<AuditLogResponses.ListItem>> page(
+            @AuthenticationPrincipal AuthenticatedUser user,
+            @RequestParam(defaultValue = "1") @Min(1) long page,
+            @RequestParam(defaultValue = "20") @Min(1) @Max(100) long size,
+            @RequestParam(required = false) Long accountId,
+            @RequestParam(required = false) Long operatorUserId,
+            @RequestParam(required = false) String eventType,
+            @RequestParam(required = false) String resourceType,
+            @RequestParam(required = false) String resourceId,
+            @RequestParam(required = false) Boolean success,
+            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) Instant occurredFrom,
+            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) Instant occurredTo,
+            @RequestParam(required = false) String keyword) {
+        AuditPlatformScopeGuard.requirePlatform(user);
+        return ApiResponse.success(service.page(new AuditLogQuery(accountId, operatorUserId, eventType,
+                resourceType, resourceId, success, occurredFrom, occurredTo, keyword), page, size));
+    }
+
+    @GetMapping("/{id}")
+    @PreAuthorize("hasAuthority('platform:audit:list')")
+    @Operation(summary = "查看操作日志详情", description = "仅平台端可查询，详情返回已脱敏的变更前后快照。")
+    public ApiResponse<AuditLogResponses.Detail> detail(@AuthenticationPrincipal AuthenticatedUser user,
+                                                          @PathVariable @Min(1) Long id) {
+        AuditPlatformScopeGuard.requirePlatform(user);
+        return ApiResponse.success(service.detail(id));
+    }
+}

audit-service/src/main/java/com/baiyue/audit/dto/AuditIngestRequest.java

@@ -13,6 +13,8 @@ import java.time.Instant;
  */
 @Schema(name = "AuditIngestRequest", description = "Internal business audit event / 内部业务审计事件")
 public record AuditIngestRequest(
+    @Schema(description = "Global idempotency event ID / 全局幂等事件ID", example = "b150c69d-8813-46b7-9a7c-81bfa5b91021")
+    @Size(max = 64) String eventId,
     @Schema(description = "Event code / 事件编码", example = "WAREHOUSE_UPDATE", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank @Size(max = 64) String eventType,
     @Schema(description = "Resource type / 资源类型", example = "WAREHOUSE", requiredMode = Schema.RequiredMode.REQUIRED)

audit-service/src/main/java/com/baiyue/audit/dto/AuditLogQuery.java

@@ -0,0 +1,19 @@
+package com.baiyue.audit.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.Instant;
+
+/** 平台操作日志筛选条件。accountId 对应审计库中的 tenant_id。 */
+@Schema(name = "AuditLogQuery", description = "平台操作日志分页筛选条件")
+public record AuditLogQuery(
+        Long accountId,
+        Long operatorUserId,
+        String eventType,
+        String resourceType,
+        String resourceId,
+        Boolean success,
+        Instant occurredFrom,
+        Instant occurredTo,
+        String keyword) {
+}

audit-service/src/main/java/com/baiyue/audit/dto/AuditLogResponses.java

@@ -0,0 +1,67 @@
+package com.baiyue.audit.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.Instant;
+import java.time.LocalDateTime;
+
+/** 平台审计日志查询响应。列表刻意不包含前后快照，详情才返回完整证据。 */
+public final class AuditLogResponses {
+    private AuditLogResponses() {
+    }
+
+    @Schema(name = "AuditLogListItem", description = "操作日志列表项，不包含变更前后快照")
+    public record ListItem(
+            Long id,
+            String eventId,
+            String eventType,
+            String resourceType,
+            String resourceId,
+            String description,
+            Long accountId,
+            Long operatorTenantId,
+            Long userId,
+            String username,
+            String appCode,
+            String clientType,
+            String clientIp,
+            String requestId,
+            String traceId,
+            String serviceName,
+            Boolean success,
+            String errorCode,
+            String errorMessage,
+            Instant occurredAt,
+            LocalDateTime createdAt) {
+    }
+
+    @Schema(name = "AuditLogDetail", description = "操作日志详情，包含已脱敏的变更前后快照")
+    public record Detail(
+            Long id,
+            String eventId,
+            String eventType,
+            String resourceType,
+            String resourceId,
+            String description,
+            String requestId,
+            String traceId,
+            Long accountId,
+            Long operatorTenantId,
+            Long userId,
+            String username,
+            String appCode,
+            String clientType,
+            String httpMethod,
+            String requestUri,
+            String clientIp,
+            Long durationMs,
+            Boolean success,
+            String errorCode,
+            String errorMessage,
+            String beforeData,
+            String afterData,
+            String serviceName,
+            Instant occurredAt,
+            LocalDateTime createdAt) {
+    }
+}

audit-service/src/main/java/com/baiyue/audit/entity/AuditLogEntity.java

@@ -23,6 +23,7 @@ public class AuditLogEntity {
     @Schema(description = "Audit log ID / 审计日志 ID", example = "190000000000000201")
     @TableId(type = IdType.AUTO)
     private Long id;
+    private String eventId;
     private String eventType;
     private String resourceType;
     private String resourceId;

audit-service/src/main/java/com/baiyue/audit/mapper/AuditLogMapper.java

@@ -1,10 +1,13 @@
 package com.baiyue.audit.mapper;
 
+import org.apache.ibatis.annotations.Mapper;
+
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.audit.entity.AuditLogEntity;
 
 /**
  * 审计日志 MyBatis-Plus Mapper，提供 {@code sys_audit_log} 表的单表写入和查询能力。
  */
+@Mapper
 public interface AuditLogMapper extends BaseMapper<AuditLogEntity> {
 }

audit-service/src/main/java/com/baiyue/audit/mq/AuditDeadLetterConsumer.java

@@ -0,0 +1,40 @@
+package com.baiyue.audit.mq;
+
+import com.baiyue.audit.repository.AuditDeadLetterRepository;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.Resource;
+import org.apache.rocketmq.spring.annotation.RocketMQMessageListener;
+import org.apache.rocketmq.spring.core.RocketMQListener;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.stereotype.Component;
+
+import java.nio.charset.StandardCharsets;
+import java.util.UUID;
+
+/** 将 RocketMQ 最终死信转存数据库，供补偿任务恢复。 */
+@Component
+@ConditionalOnProperty(prefix = "baiyue.audit.rocketmq", name = "dead-letter-consumer-enabled", havingValue = "true")
+@RocketMQMessageListener(
+    topic = "${baiyue.audit.rocketmq.dead-letter-topic}",
+    consumerGroup = "${baiyue.audit.rocketmq.dead-letter-group}")
+public class AuditDeadLetterConsumer implements RocketMQListener<String> {
+    @Resource
+    private ObjectMapper json;
+    @Resource
+    private AuditDeadLetterRepository repository;
+
+    @Override
+    public void onMessage(String payload) {
+        repository.save(eventId(payload), payload);
+    }
+
+    private String eventId(String payload) {
+        try {
+            String value = json.readTree(payload).path("eventId").asText();
+            if (!value.isBlank()) return value;
+        } catch (Exception ignored) {
+            // 无法解析的毒消息也必须使用确定性 ID 收入死信表。
+        }
+        return "invalid-" + UUID.nameUUIDFromBytes(payload.getBytes(StandardCharsets.UTF_8));
+    }
+}

audit-service/src/main/java/com/baiyue/audit/mq/AuditRocketMqConsumer.java

@@ -0,0 +1,34 @@
+package com.baiyue.audit.mq;
+
+import com.baiyue.audit.dto.AuditIngestRequest;
+import com.baiyue.audit.service.AuditIngestService;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.Resource;
+import org.apache.rocketmq.spring.annotation.RocketMQMessageListener;
+import org.apache.rocketmq.spring.core.RocketMQListener;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.stereotype.Component;
+
+/** RocketMQ 审计事件消费者；数据库 event_id 唯一键保证重复消息安全。 */
+@Component
+@ConditionalOnProperty(prefix = "baiyue.audit.rocketmq", name = "consumer-enabled", havingValue = "true")
+@RocketMQMessageListener(
+    topic = "${baiyue.audit.rocketmq.topic}",
+    selectorExpression = "AUDIT",
+    consumerGroup = "${baiyue.audit.rocketmq.consumer-group}")
+public class AuditRocketMqConsumer implements RocketMQListener<String> {
+    @Resource
+    private ObjectMapper json;
+    @Resource
+    private AuditIngestService service;
+
+    @Override
+    public void onMessage(String payload) {
+        try {
+            service.ingest(json.readValue(payload, AuditIngestRequest.class));
+        } catch (JsonProcessingException exception) {
+            throw new IllegalArgumentException("审计消息格式无效", exception);
+        }
+    }
+}

audit-service/src/main/java/com/baiyue/audit/repository/AuditDeadLetterRepository.java

@@ -0,0 +1,73 @@
+package com.baiyue.audit.repository;
+
+import jakarta.annotation.Resource;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Repository;
+
+import java.util.List;
+
+/** 审计 RocketMQ 死信及补偿状态仓储。 */
+@Repository
+public class AuditDeadLetterRepository {
+    @Resource
+    private JdbcTemplate jdbc;
+
+    public void save(String eventId, String payload) {
+        jdbc.update("""
+            INSERT INTO sys_audit_dead_letter(event_id,payload_text,status,retry_count,next_retry_at,created_at)
+            VALUES (?,?,'PENDING',0,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3))
+            ON DUPLICATE KEY UPDATE payload_text=VALUES(payload_text)
+            """, eventId, payload);
+    }
+
+    public List<Long> pendingIds(int limit) {
+        return jdbc.queryForList("""
+            SELECT id FROM sys_audit_dead_letter
+            WHERE status='PENDING' AND next_retry_at<=CURRENT_TIMESTAMP(3)
+            ORDER BY next_retry_at,id LIMIT ?
+            """, Long.class, limit);
+    }
+
+    public boolean claim(long id, String owner, int leaseSeconds) {
+        return jdbc.update("""
+            UPDATE sys_audit_dead_letter SET status='PROCESSING',lease_owner=?,
+              lease_until=DATE_ADD(CURRENT_TIMESTAMP(3),INTERVAL ? SECOND),retry_count=retry_count+1
+            WHERE id=? AND status='PENDING' AND next_retry_at<=CURRENT_TIMESTAMP(3)
+            """, owner, leaseSeconds, id) == 1;
+    }
+
+    public DeadRow find(long id) {
+        List<DeadRow> rows = jdbc.query(
+            "SELECT id,event_id,payload_text,retry_count FROM sys_audit_dead_letter WHERE id=?",
+            (rs, rowNum) -> new DeadRow(rs.getLong(1), rs.getString(2), rs.getString(3), rs.getInt(4)), id);
+        return rows.isEmpty() ? null : rows.get(0);
+    }
+
+    public void processed(long id, String owner) {
+        jdbc.update("""
+            UPDATE sys_audit_dead_letter SET status='PROCESSED',processed_at=CURRENT_TIMESTAMP(3),
+              lease_owner=NULL,lease_until=NULL,last_error=NULL
+            WHERE id=? AND status='PROCESSING' AND lease_owner=?
+            """, id, owner);
+    }
+
+    public void failed(long id, String owner, int maxAttempts, String error) {
+        jdbc.update("""
+            UPDATE sys_audit_dead_letter
+            SET status=IF(retry_count>=?,'DEAD','PENDING'),
+              next_retry_at=DATE_ADD(CURRENT_TIMESTAMP(3),INTERVAL 60 SECOND),
+              lease_owner=NULL,lease_until=NULL,last_error=?
+            WHERE id=? AND status='PROCESSING' AND lease_owner=?
+            """, maxAttempts, error, id, owner);
+    }
+
+    public int releaseExpired() {
+        return jdbc.update("""
+            UPDATE sys_audit_dead_letter SET status='PENDING',next_retry_at=CURRENT_TIMESTAMP(3),
+              lease_owner=NULL,lease_until=NULL
+            WHERE status='PROCESSING' AND lease_until<=CURRENT_TIMESTAMP(3) LIMIT 100
+            """);
+    }
+
+    public record DeadRow(long id, String eventId, String payload, int retryCount) { }
+}

audit-service/src/main/java/com/baiyue/audit/repository/AuditEventRepository.java

@@ -1,23 +1,29 @@
 package com.baiyue.audit.repository;
 
+import jakarta.annotation.Resource;
+
 import com.baiyue.audit.dto.AuditIngestRequest;
 import com.baiyue.audit.entity.AuditLogEntity;
 import com.baiyue.audit.mapper.AuditLogMapper;
+import com.baiyue.audit.dto.AuditLogQuery;
+import com.baiyue.common.core.api.PageResult;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import org.springframework.stereotype.Repository;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.util.StringUtils;
 
 /**
  * 审计事件持久化仓储，负责将内部审计请求映射并追加写入审计日志表。
  */
 @Repository
 public class AuditEventRepository {
-    private final AuditLogMapper mapper;
+    @Resource
+    private AuditLogMapper mapper;
 
-    public AuditEventRepository(AuditLogMapper mapper) {
-        this.mapper = mapper;
-    }
-
-    public void save(AuditIngestRequest event) {
+    public boolean save(AuditIngestRequest event, String eventId) {
         AuditLogEntity entity = new AuditLogEntity();
+        entity.setEventId(eventId);
         entity.setEventType(event.eventType());
         entity.setResourceType(event.resourceType());
         entity.setResourceId(event.resourceId());
@@ -41,7 +47,40 @@ public class AuditEventRepository {
         entity.setAfterData(jsonOrNull(event.afterData()));
         entity.setOccurredAt(event.occurredAt());
         entity.setServiceName(event.serviceName());
-        mapper.insert(entity);
+        try {
+            mapper.insert(entity);
+            return true;
+        } catch (DuplicateKeyException ignored) {
+            return false;
+        }
+    }
+
+    public PageResult<AuditLogEntity> page(AuditLogQuery query, long page, long size) {
+        LambdaQueryWrapper<AuditLogEntity> wrapper = new LambdaQueryWrapper<AuditLogEntity>()
+                .eq(query.accountId() != null, AuditLogEntity::getTenantId, query.accountId())
+                .eq(query.operatorUserId() != null, AuditLogEntity::getUserId, query.operatorUserId())
+                .eq(StringUtils.hasText(query.eventType()), AuditLogEntity::getEventType, query.eventType())
+                .eq(StringUtils.hasText(query.resourceType()), AuditLogEntity::getResourceType, query.resourceType())
+                .eq(StringUtils.hasText(query.resourceId()), AuditLogEntity::getResourceId, query.resourceId())
+                .eq(query.success() != null, AuditLogEntity::getSuccess, query.success())
+                .ge(query.occurredFrom() != null, AuditLogEntity::getOccurredAt, query.occurredFrom())
+                .le(query.occurredTo() != null, AuditLogEntity::getOccurredAt, query.occurredTo())
+                .orderByDesc(AuditLogEntity::getOccurredAt)
+                .orderByDesc(AuditLogEntity::getId);
+        if (StringUtils.hasText(query.keyword())) {
+            String keyword = query.keyword().trim();
+            wrapper.and(condition -> condition
+                    .like(AuditLogEntity::getDescription, keyword)
+                    .or().like(AuditLogEntity::getUsername, keyword)
+                    .or().like(AuditLogEntity::getResourceId, keyword)
+                    .or().like(AuditLogEntity::getRequestId, keyword)
+                    .or().like(AuditLogEntity::getTraceId, keyword));
+        }
+        return PageResult.from(mapper.selectPage(new Page<>(page, size), wrapper));
+    }
+
+    public AuditLogEntity findById(Long id) {
+        return mapper.selectById(id);
     }
 
     private static String jsonOrNull(String value) {

audit-service/src/main/java/com/baiyue/audit/service/AuditDeadLetterCompensator.java

@@ -0,0 +1,47 @@
+package com.baiyue.audit.service;
+
+import com.baiyue.audit.dto.AuditIngestRequest;
+import com.baiyue.audit.repository.AuditDeadLetterRepository;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.Resource;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+/** 定时重放已持久化的审计死信，达到上限后保留为 DEAD 供人工处理。 */
+@Component
+@ConditionalOnProperty(prefix = "baiyue.audit.rocketmq", name = "dead-letter-compensation-enabled", havingValue = "true")
+public class AuditDeadLetterCompensator {
+    @Resource
+    private AuditDeadLetterRepository repository;
+    @Resource
+    private AuditIngestService service;
+    @Resource
+    private ObjectMapper json;
+    @Value("${spring.application.name:audit-service}-${random.uuid}")
+    private String owner;
+    @Value("${baiyue.audit.rocketmq.dead-letter-max-attempts:5}")
+    private int maxAttempts;
+
+    @Scheduled(fixedDelayString = "${baiyue.audit.rocketmq.dead-letter-poll-ms:10000}")
+    public void compensate() {
+        repository.releaseExpired();
+        for (Long id : repository.pendingIds(50)) {
+            if (!repository.claim(id, owner, 60)) continue;
+            AuditDeadLetterRepository.DeadRow row = repository.find(id);
+            if (row == null) continue;
+            try {
+                service.ingest(json.readValue(row.payload(), AuditIngestRequest.class));
+                repository.processed(id, owner);
+            } catch (Exception exception) {
+                repository.failed(id, owner, maxAttempts, safe(exception.getMessage()));
+            }
+        }
+    }
+
+    private static String safe(String value) {
+        String message = value == null ? "死信补偿失败" : value;
+        return message.length() <= 1000 ? message : message.substring(0, 1000);
+    }
+}

audit-service/src/main/java/com/baiyue/audit/service/AuditIngestService.java

@@ -5,6 +5,9 @@ import com.baiyue.audit.dto.AuditIngestRequest;
 import com.baiyue.audit.repository.AuditEventRepository;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
+
+import java.util.UUID;
 
 /**
  * 审计事件写入应用服务，在事务内接收并持久化不可变业务审计记录。
@@ -16,7 +19,8 @@ public class AuditIngestService {
 
 
     @Transactional
-    public void ingest(AuditIngestRequest event) {
-        repository.save(event);
+    public boolean ingest(AuditIngestRequest event) {
+        String eventId = StringUtils.hasText(event.eventId()) ? event.eventId() : UUID.randomUUID().toString();
+        return repository.save(event, eventId);
     }
 }

audit-service/src/main/java/com/baiyue/audit/service/AuditLogQueryService.java

@@ -0,0 +1,48 @@
+package com.baiyue.audit.service;
+
+import com.baiyue.audit.dto.AuditLogQuery;
+import com.baiyue.audit.dto.AuditLogResponses;
+import com.baiyue.audit.entity.AuditLogEntity;
+import com.baiyue.audit.repository.AuditEventRepository;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import jakarta.annotation.Resource;
+import org.springframework.stereotype.Service;
+
+/** 平台统一操作日志查询服务。 */
+@Service
+public class AuditLogQueryService {
+    @Resource
+    private AuditEventRepository repository;
+
+    public PageResult<AuditLogResponses.ListItem> page(AuditLogQuery query, long page, long size) {
+        PageResult<AuditLogEntity> source = repository.page(query, page, size);
+        return new PageResult<>(source.records().stream().map(this::toListItem).toList(),
+                source.page(), source.size(), source.total(), source.pages());
+    }
+
+    public AuditLogResponses.Detail detail(Long id) {
+        AuditLogEntity entity = repository.findById(id);
+        if (entity == null) {
+            throw new BizException(ResultCode.NOT_FOUND, "操作日志不存在");
+        }
+        return new AuditLogResponses.Detail(
+                entity.getId(), entity.getEventId(), entity.getEventType(), entity.getResourceType(), entity.getResourceId(),
+                entity.getDescription(), entity.getRequestId(), entity.getTraceId(), entity.getTenantId(),
+                entity.getOperatorTenantId(), entity.getUserId(), entity.getUsername(), entity.getAppCode(),
+                entity.getClientType(), entity.getHttpMethod(), entity.getRequestUri(), entity.getClientIp(),
+                entity.getDurationMs(), entity.getSuccess(), entity.getErrorCode(), entity.getErrorMessage(),
+                entity.getBeforeData(), entity.getAfterData(), entity.getServiceName(), entity.getOccurredAt(),
+                entity.getCreatedAt());
+    }
+
+    private AuditLogResponses.ListItem toListItem(AuditLogEntity entity) {
+        return new AuditLogResponses.ListItem(
+                entity.getId(), entity.getEventId(), entity.getEventType(), entity.getResourceType(), entity.getResourceId(),
+                entity.getDescription(), entity.getTenantId(), entity.getOperatorTenantId(), entity.getUserId(),
+                entity.getUsername(), entity.getAppCode(), entity.getClientType(), entity.getClientIp(), entity.getRequestId(),
+                entity.getTraceId(), entity.getServiceName(), entity.getSuccess(), entity.getErrorCode(),
+                entity.getErrorMessage(), entity.getOccurredAt(), entity.getCreatedAt());
+    }
+}

audit-service/src/main/java/com/baiyue/audit/service/AuditPlatformScopeGuard.java

@@ -0,0 +1,20 @@
+package com.baiyue.audit.service;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.common.security.AuthenticatedUser;
+
+/** 审计日志只允许平台端账号读取，避免商户端通过通用日志接口获取跨账号记录。 */
+public final class AuditPlatformScopeGuard {
+    private AuditPlatformScopeGuard() {
+    }
+
+    public static void requirePlatform(AuthenticatedUser user) {
+        if (user == null || user.userId() == null) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "请先登录");
+        }
+        if (!"PLATFORM".equals(user.appCode()) || !Long.valueOf(0L).equals(user.tenantId())) {
+            throw new BizException(ResultCode.FORBIDDEN, "仅平台端可查看操作日志");
+        }
+    }
+}

audit-service/src/main/resources/application-dev.yml

@@ -0,0 +1,6 @@
+spring:
+  datasource:
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    url: ${AUDIT_DB_URL:jdbc:mysql://127.0.0.1:3306/baiyue_audit?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&rewriteBatchedStatements=true}
+    username: ${AUDIT_DB_USERNAME:root}
+    password: ${AUDIT_DB_PASSWORD:123456}

audit-service/src/main/resources/application-test.yml

@@ -0,0 +1,6 @@
+spring:
+  datasource:
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    url: ${AUDIT_TEST_DB_URL:jdbc:mysql://${TEST_DB_HOST:8.163.30.128}:${TEST_DB_PORT:3306}/baiyue_audit?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true&rewriteBatchedStatements=true}
+    username: ${AUDIT_TEST_DB_USERNAME:${TEST_DB_USERNAME:root}}
+    password: ${AUDIT_TEST_DB_PASSWORD:${TEST_DB_PASSWORD}}

audit-service/src/main/resources/application.yml

@@ -2,6 +2,8 @@ server:
   port: ${AUDIT_PORT:9700}
 
 spring:
+  profiles:
+    active: ${SPRING_PROFILES_ACTIVE:dev}
   application:
     name: audit-service
   config:
@@ -14,18 +16,27 @@ spring:
       username: ${NACOS_USERNAME:nacos}
       password: ${NACOS_PASSWORD:nacos}
       discovery:
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         enabled: ${NACOS_DISCOVERY_ENABLED:true}
         register-enabled: ${NACOS_REGISTER_ENABLED:true}
         group: ${NACOS_GROUP:BAIYUE}
         namespace: ${NACOS_NAMESPACE:public}
-      config.namespace: ${NACOS_NAMESPACE:public}
-
-  # 本地 IDEA 启动默认连接本机 MySQL；生产环境请通过 AUDIT_DB_* 环境变量覆盖。
-  datasource:
-    driver-class-name: com.mysql.cj.jdbc.Driver
-    url: ${AUDIT_DB_URL:jdbc:mysql://127.0.0.1:3306/baiyue_audit?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&rewriteBatchedStatements=true}
-    username: ${AUDIT_DB_USERNAME:root}
-    password: ${AUDIT_DB_PASSWORD:123456}
+      config:
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
+        namespace: ${NACOS_NAMESPACE:public}
 
 baiyue.audit.enabled: false
+baiyue:
+  audit:
+    rocketmq:
+      consumer-enabled: ${AUDIT_MQ_CONSUMER_ENABLED:false}
+      topic: ${MQ_TOPIC_PREFIX:test-}baiyue-audit-event-v1
+      consumer-group: ${MQ_TOPIC_PREFIX:test-}baiyue-audit-consumer-v1
+      dead-letter-consumer-enabled: ${AUDIT_DLQ_CONSUMER_ENABLED:false}
+      dead-letter-topic: "%DLQ%${MQ_TOPIC_PREFIX:test-}baiyue-audit-consumer-v1"
+      dead-letter-group: ${MQ_TOPIC_PREFIX:test-}baiyue-audit-dlq-handler-v1
+      dead-letter-compensation-enabled: ${AUDIT_DLQ_COMPENSATION_ENABLED:false}
+      dead-letter-max-attempts: ${AUDIT_DLQ_MAX_ATTEMPTS:5}
+rocketmq:
+  name-server: ${ROCKETMQ_NAME_SERVER:127.0.0.1:9876}
 management.endpoints.web.exposure.include: health,info,prometheus

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

@@ -4,14 +4,15 @@ USE baiyue_audit;
 
 CREATE TABLE IF NOT EXISTS sys_audit_log (
   id BIGINT NOT NULL AUTO_INCREMENT COMMENT '审计日志自增ID',
+  event_id VARCHAR(64) DEFAULT NULL COMMENT '审计事件全局唯一ID',
   event_type VARCHAR(64) NOT NULL COMMENT '审计事件编码',
   resource_type VARCHAR(64) NOT NULL COMMENT '被操作资源类型',
   resource_id VARCHAR(128) DEFAULT NULL COMMENT '被操作资源ID',
   description VARCHAR(255) DEFAULT NULL COMMENT '操作说明',
   request_id VARCHAR(128) DEFAULT NULL COMMENT '请求ID，用于单次请求追踪',
   trace_id VARCHAR(128) DEFAULT NULL COMMENT '分布式链路追踪ID',
-  tenant_id BIGINT DEFAULT NULL COMMENT '业务数据所属租户ID',
-  operator_tenant_id BIGINT DEFAULT NULL COMMENT '操作主体所属租户ID',
+  tenant_id BIGINT DEFAULT NULL COMMENT '客户ID和数据隔离键；平台级审计可为空或为0',
+  operator_tenant_id BIGINT DEFAULT NULL COMMENT '操作主体所属客户ID；平台操作可为空或为0',
   user_id BIGINT DEFAULT NULL COMMENT '操作用户ID',
   username VARCHAR(128) DEFAULT NULL COMMENT '操作用户名快照',
   app_code VARCHAR(64) DEFAULT NULL COMMENT '操作来源应用端',
@@ -29,8 +30,26 @@ CREATE TABLE IF NOT EXISTS sys_audit_log (
   occurred_at DATETIME(3) NOT NULL COMMENT '业务操作发生时间',
   created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '审计服务落库时间',
   PRIMARY KEY (id),
+  UNIQUE KEY uk_audit_event_id (event_id),
   KEY idx_audit_tenant_time (tenant_id, occurred_at),
   KEY idx_audit_event_time (event_type, occurred_at),
   KEY idx_audit_user_time (user_id, occurred_at),
   KEY idx_audit_request (request_id)
 ) ENGINE=InnoDB COMMENT='统一业务审计日志表：追加记录敏感操作的主体、租户、资源、结果及前后快照；不同于消息Outbox和消费幂等表';
+
+CREATE TABLE IF NOT EXISTS sys_audit_dead_letter (
+  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '死信记录自增ID',
+  event_id VARCHAR(64) NOT NULL COMMENT '审计事件全局唯一ID',
+  payload_text LONGTEXT NOT NULL COMMENT 'RocketMQ死信原始载荷',
+  status VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT '状态：PENDING待补偿、PROCESSING处理中、PROCESSED已处理、DEAD永久失败',
+  retry_count INT NOT NULL DEFAULT 0 COMMENT '死信重试次数',
+  next_retry_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '下次允许补偿时间',
+  lease_owner VARCHAR(128) NULL COMMENT '当前补偿租约持有实例',
+  lease_until DATETIME(3) NULL COMMENT '当前补偿租约截止时间',
+  last_error VARCHAR(1000) NULL COMMENT '最近一次补偿错误',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '死信记录创建时间',
+  processed_at DATETIME(3) NULL COMMENT '补偿处理完成时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_audit_dead_event (event_id),
+  KEY idx_audit_dead_retry (status, next_retry_at, lease_until)
+) ENGINE=InnoDB COMMENT='审计消息死信补偿表';

audit-service/src/main/resources/db/reliable-audit-migration.sql

@@ -0,0 +1,39 @@
+USE baiyue_audit;
+
+DROP PROCEDURE IF EXISTS add_audit_event_id;
+DELIMITER $$
+CREATE PROCEDURE add_audit_event_id()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.COLUMNS
+    WHERE TABLE_SCHEMA='baiyue_audit' AND TABLE_NAME='sys_audit_log' AND COLUMN_NAME='event_id'
+  ) THEN
+    ALTER TABLE sys_audit_log ADD COLUMN event_id VARCHAR(64) NULL COMMENT '审计事件全局唯一ID' AFTER id;
+  END IF;
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.STATISTICS
+    WHERE TABLE_SCHEMA='baiyue_audit' AND TABLE_NAME='sys_audit_log' AND INDEX_NAME='uk_audit_event_id'
+  ) THEN
+    ALTER TABLE sys_audit_log ADD UNIQUE KEY uk_audit_event_id (event_id);
+  END IF;
+END$$
+DELIMITER ;
+CALL add_audit_event_id();
+DROP PROCEDURE IF EXISTS add_audit_event_id;
+
+CREATE TABLE IF NOT EXISTS sys_audit_dead_letter (
+  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '死信记录自增ID',
+  event_id VARCHAR(64) NOT NULL COMMENT '审计事件全局唯一ID',
+  payload_text LONGTEXT NOT NULL COMMENT 'RocketMQ死信原始载荷',
+  status VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT '状态：PENDING待补偿、PROCESSING处理中、PROCESSED已处理、DEAD永久失败',
+  retry_count INT NOT NULL DEFAULT 0 COMMENT '死信重试次数',
+  next_retry_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '下次允许补偿时间',
+  lease_owner VARCHAR(128) NULL COMMENT '当前补偿租约持有实例',
+  lease_until DATETIME(3) NULL COMMENT '当前补偿租约截止时间',
+  last_error VARCHAR(1000) NULL COMMENT '最近一次补偿错误',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '死信记录创建时间',
+  processed_at DATETIME(3) NULL COMMENT '补偿处理完成时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_audit_dead_event (event_id),
+  KEY idx_audit_dead_retry (status, next_retry_at, lease_until)
+) ENGINE=InnoDB COMMENT='审计消息死信补偿表';

audit-service/src/test/java/com/baiyue/audit/BaiyueAuditApplicationContractTest.java

@@ -0,0 +1,17 @@
+package com.baiyue.audit;
+
+import com.baiyue.common.core.mybatis.MybatisPlusConfiguration;
+import org.junit.jupiter.api.Test;
+import org.springframework.context.annotation.Import;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class BaiyueAuditApplicationContractTest {
+    @Test
+    void importsSharedMybatisPaginationConfiguration() {
+        Import imported = BaiyueAuditApplication.class.getAnnotation(Import.class);
+
+        assertThat(imported).isNotNull();
+        assertThat(imported.value()).contains(MybatisPlusConfiguration.class);
+    }
+}

audit-service/src/test/java/com/baiyue/audit/controller/AuditIngestControllerTest.java

@@ -0,0 +1,74 @@
+package com.baiyue.audit.controller;
+
+import com.baiyue.audit.service.AuditIngestService;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.http.MediaType;
+import org.springframework.test.context.TestPropertySource;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@SpringJUnitConfig(AuditIngestController.class)
+@TestPropertySource(properties = "baiyue.security.internal-service-token=0123456789abcdef0123456789abcdef")
+class AuditIngestControllerTest {
+    private static final String TOKEN = "0123456789abcdef0123456789abcdef";
+
+    @MockBean
+    private AuditIngestService service;
+
+    @Resource
+    private AuditIngestController controller;
+
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        mockMvc = MockMvcBuilders.standaloneSetup(controller).build();
+    }
+
+    @Test
+    void rejectsInvalidInternalToken() throws Exception {
+        mockMvc.perform(post("/internal/audit/events")
+                        .header("X-Internal-Service-Token", "wrong-token")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(validRequest()))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.code").value("A0403"));
+
+        verify(service, never()).ingest(any());
+    }
+
+    @Test
+    void acceptsEventWithInternalToken() throws Exception {
+        mockMvc.perform(post("/internal/audit/events")
+                        .header("X-Internal-Service-Token", TOKEN)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(validRequest()))
+                .andExpect(status().isAccepted())
+                .andExpect(jsonPath("$.code").value("200"));
+
+        verify(service).ingest(any());
+    }
+
+    private String validRequest() {
+        return """
+                {
+                  "eventType":"ROLE_UPDATE",
+                  "resourceType":"ROLE",
+                  "durationMs":0,
+                  "success":true,
+                  "occurredAt":"2026-08-05T00:00:00Z"
+                }
+                """;
+    }
+}

audit-service/src/test/java/com/baiyue/audit/controller/PlatformAuditLogControllerContractTest.java

@@ -0,0 +1,92 @@
+package com.baiyue.audit.controller;
+
+import com.baiyue.audit.dto.AuditLogQuery;
+import com.baiyue.audit.dto.AuditLogResponses;
+import com.baiyue.audit.service.AuditLogQueryService;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.common.security.AuthenticatedUser;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.security.access.prepost.PreAuthorize;
+
+import java.util.List;
+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.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+@SpringJUnitConfig(PlatformAuditLogController.class)
+class PlatformAuditLogControllerContractTest {
+    @MockBean
+    private AuditLogQueryService service;
+
+    @Resource
+    private PlatformAuditLogController controller;
+
+    @Test
+    void platformCanQueryLogList() {
+        when(service.page(any(AuditLogQuery.class), org.mockito.ArgumentMatchers.eq(1L),
+                org.mockito.ArgumentMatchers.eq(20L)))
+                .thenReturn(new PageResult<>(List.of(), 1, 20, 0, 0));
+
+        var response = controller.page(user("PLATFORM"), 1, 20, 10001L, 7L, "ROLE_UPDATE", "ROLE", "9",
+                true, null, null, "管理员");
+
+        assertThat(response.successful()).isTrue();
+        verify(service).page(new AuditLogQuery(10001L, 7L, "ROLE_UPDATE", "ROLE", "9", true,
+                null, null, "管理员"), 1, 20);
+    }
+
+    @Test
+    void merchantCannotReadPlatformLogs() {
+        assertThatThrownBy(() -> controller.page(user("MERCHANT"), 1, 20, null, null, null, null,
+                null, null, null, null, null)).isInstanceOf(BizException.class)
+                .hasMessage("仅平台端可查看操作日志");
+        verifyNoInteractions(service);
+    }
+
+    @Test
+    void platformApplicationWithCustomerTenantCannotReadLogs() {
+        AuthenticatedUser malformed = new AuthenticatedUser(7L, 10001L, 10001L, 1L,
+                "异常平台账号", "PLATFORM", "WEB", Set.of("platform:audit:list"));
+
+        assertThatThrownBy(() -> controller.page(malformed, 1, 20, null, null, null, null,
+                null, null, null, null, null)).isInstanceOf(BizException.class)
+                .hasMessage("仅平台端可查看操作日志");
+        verifyNoInteractions(service);
+    }
+
+    @Test
+    void platformCanReadLogDetail() {
+        AuditLogResponses.Detail detail = new AuditLogResponses.Detail(8L, "audit-1", "ROLE_UPDATE", "ROLE", "9", null,
+                null, null, null, null, 7L, "管理员", "PLATFORM", "WEB", null, null, null, 1L,
+                true, null, null, "{}", "{}", "iam-service", null, null);
+        when(service.detail(8L)).thenReturn(detail);
+
+        assertThat(controller.detail(user("PLATFORM"), 8L).data()).isEqualTo(detail);
+        verify(service).detail(8L);
+    }
+
+    @Test
+    void listAndDetailUseTheSamePlatformAuditPermission() throws NoSuchMethodException {
+        String expected = "hasAuthority('platform:audit:list')";
+
+        assertThat(PlatformAuditLogController.class.getMethod("page", AuthenticatedUser.class,
+                long.class, long.class, Long.class, Long.class, String.class, String.class, String.class,
+                Boolean.class, java.time.Instant.class, java.time.Instant.class, String.class)
+                .getAnnotation(PreAuthorize.class).value()).isEqualTo(expected);
+        assertThat(PlatformAuditLogController.class.getMethod("detail", AuthenticatedUser.class, Long.class)
+                .getAnnotation(PreAuthorize.class).value()).isEqualTo(expected);
+    }
+
+    private static AuthenticatedUser user(String appCode) {
+        return new AuthenticatedUser(7L, 0L, 0L, 1L, "管理员", appCode, "WEB", Set.of("platform:audit:list"));
+    }
+}

audit-service/src/test/java/com/baiyue/audit/mq/AuditMqReliabilityTest.java

@@ -0,0 +1,107 @@
+package com.baiyue.audit.mq;
+
+import com.baiyue.audit.repository.AuditDeadLetterRepository;
+import com.baiyue.audit.service.AuditDeadLetterCompensator;
+import com.baiyue.audit.service.AuditIngestService;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.test.context.TestPropertySource;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@SpringJUnitConfig(classes = {
+        AuditMqReliabilityTest.Config.class,
+        AuditRocketMqConsumer.class,
+        AuditDeadLetterConsumer.class,
+        AuditDeadLetterCompensator.class
+})
+@TestPropertySource(properties = {
+        "baiyue.audit.rocketmq.consumer-enabled=true",
+        "baiyue.audit.rocketmq.dead-letter-consumer-enabled=true",
+        "baiyue.audit.rocketmq.dead-letter-compensation-enabled=true",
+        "baiyue.audit.rocketmq.topic=test-audit",
+        "baiyue.audit.rocketmq.consumer-group=test-audit-consumer",
+        "baiyue.audit.rocketmq.dead-letter-topic=%DLQ%test-audit-consumer",
+        "baiyue.audit.rocketmq.dead-letter-group=test-audit-dlq",
+        "spring.application.name=audit-service-test"
+})
+class AuditMqReliabilityTest {
+    private static final String PAYLOAD = """
+            {"eventId":"event-1","eventType":"ROLE_UPDATE","resourceType":"ROLE",
+             "durationMs":10,"success":true,"occurredAt":"2026-08-05T00:00:00Z"}
+            """;
+
+    @MockBean
+    private AuditIngestService service;
+    @MockBean
+    private AuditDeadLetterRepository repository;
+    @Resource
+    private AuditRocketMqConsumer consumer;
+    @Resource
+    private AuditDeadLetterConsumer deadLetterConsumer;
+    @Resource
+    private AuditDeadLetterCompensator compensator;
+
+    @Test
+    void consumesAuditEvent() {
+        consumer.onMessage(PAYLOAD);
+
+        verify(service).ingest(any());
+    }
+
+    @Test
+    void rejectsInvalidPayload() {
+        assertThatThrownBy(() -> consumer.onMessage("not-json"))
+                .isInstanceOf(IllegalArgumentException.class);
+    }
+
+    @Test
+    void storesDeadLetter() {
+        deadLetterConsumer.onMessage(PAYLOAD);
+
+        verify(repository).save("event-1", PAYLOAD);
+    }
+
+    @Test
+    void compensatesDeadLetter() {
+        when(repository.pendingIds(50)).thenReturn(java.util.List.of(7L));
+        when(repository.claim(eq(7L), anyString(), eq(60))).thenReturn(true);
+        when(repository.find(7L)).thenReturn(
+                new AuditDeadLetterRepository.DeadRow(7L, "event-1", PAYLOAD, 1));
+
+        compensator.compensate();
+
+        verify(service).ingest(any());
+        verify(repository).processed(eq(7L), anyString());
+    }
+
+    @Test
+    void retriesFailedCompensation() {
+        when(repository.pendingIds(50)).thenReturn(java.util.List.of(8L));
+        when(repository.claim(eq(8L), anyString(), eq(60))).thenReturn(true);
+        when(repository.find(8L)).thenReturn(
+                new AuditDeadLetterRepository.DeadRow(8L, "event-2", "not-json", 1));
+
+        compensator.compensate();
+
+        verify(repository).failed(eq(8L), anyString(), eq(5), anyString());
+    }
+
+    @Configuration
+    static class Config {
+        @Bean
+        ObjectMapper objectMapper() {
+            return new ObjectMapper().findAndRegisterModules();
+        }
+    }
+}

audit-service/src/test/java/com/baiyue/audit/service/AuditIngestIdempotencyTest.java

@@ -0,0 +1,39 @@
+package com.baiyue.audit.service;
+
+import com.baiyue.audit.dto.AuditIngestRequest;
+import com.baiyue.audit.repository.AuditEventRepository;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+import java.time.Instant;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@SpringJUnitConfig(AuditIngestService.class)
+class AuditIngestIdempotencyTest {
+    @MockBean
+    private AuditEventRepository repository;
+    @Resource
+    private AuditIngestService service;
+
+    @Test
+    void keepsStableEventIdForMqRedelivery() {
+        AuditIngestRequest request = request("audit-1");
+        when(repository.save(request, "audit-1")).thenReturn(false);
+
+        assertThat(service.ingest(request)).isFalse();
+
+        verify(repository).save(request, "audit-1");
+    }
+
+    private static AuditIngestRequest request(String eventId) {
+        return new AuditIngestRequest(eventId, "ROLE_UPDATE", "ROLE", "1", "修改角色",
+            "request-1", "trace-1", 1L, 1L, 1L, "admin", "PLATFORM", "WEB", "PUT",
+            "/roles/1", "127.0.0.1", 10, true, null, null, null, null,
+            Instant.parse("2026-08-05T00:00:00Z"), "iam-service");
+    }
+}

audit-service/src/test/java/com/baiyue/audit/service/AuditLogQueryServiceTest.java

@@ -0,0 +1,103 @@
+package com.baiyue.audit.service;
+
+import com.baiyue.audit.dto.AuditLogQuery;
+import com.baiyue.audit.dto.AuditLogResponses;
+import com.baiyue.audit.entity.AuditLogEntity;
+import com.baiyue.audit.repository.AuditEventRepository;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.core.exception.BizException;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.Mockito.when;
+
+@SpringJUnitConfig(AuditLogQueryService.class)
+class AuditLogQueryServiceTest {
+    @MockBean
+    private AuditEventRepository repository;
+
+    @Resource
+    private AuditLogQueryService service;
+
+    @Test
+    void pageDoesNotExposeSnapshots() {
+        AuditLogQuery query = new AuditLogQuery(10001L, 7L, "ROLE_UPDATE", "ROLE", "9", true,
+                null, null, "管理员");
+        when(repository.page(query, 1, 20)).thenReturn(new PageResult<>(List.of(log(8L)), 1, 20, 1, 1));
+
+        PageResult<AuditLogResponses.ListItem> result = service.page(query, 1, 20);
+
+        assertThat(result.records()).singleElement().satisfies(item -> {
+            assertThat(item.id()).isEqualTo(8L);
+            assertThat(item.accountId()).isEqualTo(10001L);
+            assertThat(item.eventType()).isEqualTo("ROLE_UPDATE");
+        });
+        assertThat(AuditLogResponses.ListItem.class.getRecordComponents())
+                .extracting(component -> component.getName())
+                .doesNotContain("beforeData", "afterData");
+    }
+
+    @Test
+    void pagePreservesTotalAndPagesForCustomerLogPagination() {
+        AuditLogQuery query = new AuditLogQuery(10001L, null, null, "TENANT", null, null,
+                null, null, null);
+        when(repository.page(query, 1, 20)).thenReturn(new PageResult<>(List.of(log(8L)), 1, 20, 13, 1));
+
+        PageResult<AuditLogResponses.ListItem> result = service.page(query, 1, 20);
+
+        assertThat(result.records()).hasSize(1);
+        assertThat(result.total()).isEqualTo(13);
+        assertThat(result.pages()).isEqualTo(1);
+    }
+
+    @Test
+    void detailReturnsSanitizedSnapshots() {
+        when(repository.findById(8L)).thenReturn(log(8L));
+
+        AuditLogResponses.Detail detail = service.detail(8L);
+
+        assertThat(detail.beforeData()).isEqualTo("{\"name\":\"旧角色\"}");
+        assertThat(detail.afterData()).isEqualTo("{\"name\":\"新角色\"}");
+    }
+
+    @Test
+    void missingLogIsReportedAsNotFound() {
+        when(repository.findById(8L)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.detail(8L)).isInstanceOf(BizException.class)
+                .hasMessage("操作日志不存在");
+    }
+
+    private static AuditLogEntity log(Long id) {
+        AuditLogEntity entity = new AuditLogEntity();
+        entity.setId(id);
+        entity.setEventId("audit-8");
+        entity.setEventType("ROLE_UPDATE");
+        entity.setResourceType("ROLE");
+        entity.setResourceId("9");
+        entity.setDescription("管理员修改角色权限");
+        entity.setTenantId(10001L);
+        entity.setOperatorTenantId(0L);
+        entity.setUserId(7L);
+        entity.setUsername("管理员");
+        entity.setAppCode("PLATFORM");
+        entity.setClientType("WEB");
+        entity.setRequestId("request-8");
+        entity.setTraceId("trace-8");
+        entity.setSuccess(true);
+        entity.setBeforeData("{\"name\":\"旧角色\"}");
+        entity.setAfterData("{\"name\":\"新角色\"}");
+        entity.setServiceName("iam-service");
+        entity.setOccurredAt(Instant.parse("2026-08-05T10:00:00Z"));
+        entity.setCreatedAt(LocalDateTime.of(2026, 8, 5, 18, 0));
+        return entity;
+    }
+}

auth/AGENTS.md

@@ -0,0 +1,38 @@
+# Auth Service 模块指引
+
+## 职责与边界
+
+- Mapper 只由 `BaiyueAuthApplication.java` 对 `com.baiyue.auth` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。
+- 负责登录、注册、账号凭据、Access/Refresh Token、退出、密码和账号归属范围。
+- 客户主档、成员、角色权限归 `iam/`；Auth 通过 IAM 客户端获取授权快照，不跨库写 IAM。
+- 修改国内/海外 Token、Audience、JWKS 或跨区域身份边界前，先读 `../../docs/跨区域认证与服务通信契约.md`。
+- `tenant_id=0` 为平台作用域，`tenant_id>0` 为客户 ID；不得引入租户管理或切换。
+
+## 模块入口
+
+| 目标 | 入口 |
+|---|---|
+| 登录/刷新/退出/改密 | `src/main/java/com/baiyue/auth/controller/AuthController.java` |
+| 内部账号管理与 scope | `controller/InternalAccountController.java`、`service/AccountManagementService.java` |
+| 登录标识与企业联系人解耦 | `service/AccountManagementService.java`、`dto/AccountManagementDtos.java`、`service/MerchantRegistrationService.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 签发 | `service/OverseasTokenService.java`；登录/刷新编排使用同一用户身份同时签发短时 RS256 海外 Token，限定海外 Audience，只携带稳定身份、客户范围和版本声明，不携带角色或权限集；前端统一认证层负责按区域 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` |
+| DTO/持久化 | `dto/AccountManagementDtos.java`、`entity/`、`mapper/`、`repository/` |
+| SQL/OpenAPI | `src/main/resources/db/`、`src/main/resources/openapi/` |
+| 测试/验证 | `src/test/java/com/baiyue/auth/`；`mvn -pl auth -am test` |
+
+## 修改约束
+
+- 密码、Token、敏感 Claim 不得写日志；统一 JWT 使用 RS256，私钥只留在 Auth，JWKS 只发布公钥。国内登录 Token 的实时权限来自 Redis 会话快照；短时海外 Token 不携带角色或权限集，海外授权由 IAM 事件投影到 Lastleg，再由海外 Gateway 验证并以可信内网上下文传递，海外服务不访问国内 Redis。修改登录响应、Claim、Audience、JWKS、权限快照或过期策略时联查 Admin/Client 统一认证层、`common-security/`、`gateway/`、`iam/` 和海外服务消费者。
+- 注册跨 Auth/IAM 必须保持幂等和失败补偿；内部接口仅接受服务令牌。
+- 登录账号的 username、phone、email 唯一性只约束 Auth 账号；IAM 公司联系电话/联系邮箱是企业资料，不得反向覆盖账号登录标识，也不得因其他企业使用相同联系电话而拒绝。成员登录手机号变更只能由 IAM 账号协作入口同步并撤销该账号全部会话。
+- 业务错误保持 HTTP 200 + body code；Security 认证失败保留真实 401/403。
+
+## 全量验收导航
+
+订单与客户、入库测量与计费、国内货柜履约、海外仓业务及财务全量验收均复用本模块认证能力；按本次链路读取对应业务域/专题文档，重点核对 Token、应用域、客户隔离、失效和跨 Auth/IAM 补偿，不因历史规划边界排除其他消费者。

auth/JWT-JWKS-CONTRACT.md

@@ -0,0 +1,76 @@
+# 国内与海外 JWT/JWKS 冻结契约
+
+## 双轨边界
+
+### 国内现有链路
+
+- 登录、刷新、退出和代登录接口保持原契约，不修改 `TokenResponse`。
+- 签名算法保持 `HS256`，继续使用 `JWT_SECRET`。
+- Access Token 默认有效期保持 24 分钟，Refresh Token 默认有效期保持 7 天。
+- 业务服务继续使用国内 HMAC 验签与 Redis 会话校验，账号停用、退出和 Token 版本失效规则不变。
+- 国内 Token 保持现有 snake_case 声明，不增加海外 `aud`，也不要求配置 RSA/JWK。
+
+### 海外尾程链路
+
+- 海外能力默认关闭：`OVERSEAS_JWT_ENABLED=false`。
+- 已通过国内 HS256 与 Redis 校验的登录用户调用 `POST /api/auth/overseas/token`，兑换独立的海外短时 Token。
+- 海外 Token 使用 `RS256`，默认有效期 15 分钟，不签发 Refresh Token。
+- 尾程必须配置 `baiyue.security.jwt-mode=jwks` 和 `baiyue.security.session-mode=claims`，只做 JWKS 验签和本地安全投影校验，不创建或访问国内 Redis 会话校验器。
+- 海外功能未启用时，兑换接口返回“海外认证未启用”；JWKS Controller、海外签发服务和 `overseasJwtEncoder` 均不创建，Auth 仍可正常启动并签发国内 HS256 Token。
+
+## 海外签发契约
+
+- `issuer`：`auth-service`
+- `audience`：`lastleg-api`
+- 算法白名单：仅 `RS256`
+- Access Token 默认有效期：15 分钟
+- 兑换接口：`POST /api/auth/overseas/token`
+- JWKS 路径：`/api/auth/.well-known/jwks.json`
+- Auth 直连地址：`http://{auth-host}:9100/api/auth/.well-known/jwks.json`
+- JWKS HTTP 缓存：5 分钟，响应 `Cache-Control: public, max-age=300`
+
+海外 Token 的 JSON 声明名称和类型固定如下：
+
+| 声明 | JSON 类型 | 说明 |
+|---|---|---|
+| `sub` | string | 用户 ID 的字符串形式 |
+| `jti` | string | Token 唯一标识 |
+| `iat` | number | 签发时间 |
+| `exp` | number | 过期时间 |
+| `aud` | string array | 固定包含 `lastleg-api` |
+| `userId` | number | 认证用户 ID |
+| `tenantId` | number | 当前客户 ID；平台账号为平台作用域值 |
+| `appCode` | string | `PLATFORM` 或 `MERCHANT` |
+| `roles` | string array | 当前角色编码快照 |
+| `authorities` | string array | 当前权限编码快照 |
+| `permissionVersion` | number | IAM 单调权限版本 |
+
+海外 Token 从 V1 起只使用上述 camelCase 自定义声明，不读取国内 snake_case 声明。
+
+## 海外配置
+
+```yaml
+baiyue:
+  security:
+    overseas-jwt:
+      enabled: ${OVERSEAS_JWT_ENABLED:false}
+      issuer: ${OVERSEAS_JWT_ISSUER:auth-service}
+      audience: ${OVERSEAS_JWT_AUDIENCE:lastleg-api}
+      rsa-jwk-set: ${OVERSEAS_JWT_RSA_JWK_SET:}
+      current-kid: ${OVERSEAS_JWT_CURRENT_KID:}
+      access-token-ttl: ${OVERSEAS_ACCESS_TOKEN_TTL:15m}
+```
+
+只有显式启用海外能力时才校验 `OVERSEAS_JWT_RSA_JWK_SET` 和 `OVERSEAS_JWT_CURRENT_KID`。启用后配置不合法必须启动失败，避免错误密钥签发。
+
+## 密钥轮换
+
+- JWK Set 只允许 RSA 密钥。
+- `OVERSEAS_JWT_CURRENT_KID` 必须指向唯一的当前签名私钥，JWT Header 写入该 `kid`。
+- 非当前密钥只能保留公钥；JWKS 只发布公钥，不得输出私钥参数。
+- 轮换时同时发布当前公钥和上一公钥，上一公钥至少保留 20 分钟，即 15 分钟最大 Token 生命周期加 5 分钟 JWKS 缓存。
+- 重叠期结束后移除上一公钥，禁止复用历史 `kid`。
+
+## IAM 安全事件
+
+安全事件的 `eventType`、版本、状态枚举和 payload 以 `iam/SECURITY-EVENT-AUDIT.md` 为唯一契约。尾程维护用户状态、客户状态和权限版本的本地投影，请求期间不反向同步访问国内 IAM。

auth/pom.xml

@@ -6,6 +6,7 @@
     <artifactId>auth-service</artifactId>
     <dependencies>
         <dependency><groupId>com.baiyue.shared</groupId><artifactId>baiyue-common-audit</artifactId><version>${project.version}</version></dependency>
+        <dependency><groupId>org.apache.rocketmq</groupId><artifactId>rocketmq-spring-boot-starter</artifactId></dependency>
 <dependency><groupId>com.baiyue.shared</groupId><artifactId>baiyue-common-openapi</artifactId><version>${project.version}</version></dependency>
 <dependency><groupId>com.baiyue.shared</groupId><artifactId>baiyue-common-web</artifactId><version>${project.version}</version></dependency>
         <dependency><groupId>com.baiyue.shared</groupId><artifactId>baiyue-common-security</artifactId><version>${project.version}</version></dependency>

auth/src/main/java/com/baiyue/auth/BaiyueAuthApplication.java

@@ -1,5 +1,6 @@
 package com.baiyue.auth;
 
+import org.apache.ibatis.annotations.Mapper;
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
@@ -8,7 +9,7 @@ import org.springframework.cloud.openfeign.EnableFeignClients;
 /**
  * 认证服务启动入口，负责装配统一登录、令牌签发与会话管理相关组件。
  */
-@MapperScan("com.baiyue.auth.mapper")
+@MapperScan(basePackages = "com.baiyue.auth", annotationClass = Mapper.class)
 @EnableFeignClients(basePackages = "com.baiyue.auth.client")
 @SpringBootApplication(scanBasePackages = "com.baiyue")
 public class BaiyueAuthApplication {

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

@@ -1,5 +1,8 @@
 package com.baiyue.auth.client;
 
+import jakarta.annotation.Resource;
+import jakarta.annotation.PostConstruct;
+
 import com.baiyue.auth.entity.AuthAccount;
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
@@ -7,21 +10,23 @@ import feign.FeignException;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
 
+import java.util.Objects;
+
 /**
- * 授权快照加载器，调用 IAM 服务并校验返回身份上下文，为认证令牌组装权限声明。
+ * 授权快照加载器，调用 IAM 服务并校验返回身份上下文，为 Redis 会话组装授权快照。
  */
 @Component
 public class AuthorizationLoader {
-    private final IamAuthorizationClient client;
-    private final String internalToken;
+    @Resource
+    private IamAuthorizationClient client;
+    @Value("${baiyue.security.internal-service-token}")
+    private String internalToken;
 
-    public AuthorizationLoader(IamAuthorizationClient client,
-                               @Value("${baiyue.security.internal-service-token}") String internalToken) {
+    @PostConstruct
+    void validateConfiguration() {
         if (internalToken == null || internalToken.getBytes(java.nio.charset.StandardCharsets.UTF_8).length < 32) {
             throw new IllegalStateException("INTERNAL_SERVICE_TOKEN 至少需要 32 字节");
         }
-        this.client = client;
-        this.internalToken = internalToken;
     }
 
     public AuthorizationSnapshot load(AuthAccount account) {
@@ -29,14 +34,32 @@ public class AuthorizationLoader {
             var response = client.load(internalToken, new AuthorizationSnapshotRequest(
                     account.getId(), account.getDefaultTenantId(), account.getDefaultMembershipId(),
                     account.getDefaultAppCode()));
-            if (response == null || !response.successful() || response.data() == null) {
+            if (response == null) {
+                throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM 权限服务暂时不可用");
+            }
+            if (!response.successful()) {
+                ResultCode code = ResultCode.of(response.code());
+                if (code == ResultCode.BAD_REQUEST || code == ResultCode.FORBIDDEN || code == ResultCode.NOT_FOUND) {
+                    throw new BizException(ResultCode.FORBIDDEN, "账号没有有效的 IAM 身份或权限");
+                }
+                throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM 权限服务暂时不可用");
+            }
+            AuthorizationSnapshot snapshot = response.data();
+            if (snapshot == null) {
                 throw new BizException(ResultCode.FORBIDDEN, "账号没有有效的 IAM 身份或权限");
             }
-            return response.data();
+            if (!Objects.equals(account.getId(), snapshot.getUserId())
+                    || !Objects.equals(account.getDefaultTenantId(), snapshot.getTenantId())
+                    || !Objects.equals(account.getDefaultMembershipId(), snapshot.getMembershipId())
+                    || !Objects.equals(account.getDefaultAppCode(), snapshot.getAppCode())) {
+                throw new BizException(ResultCode.FORBIDDEN, "IAM 授权快照身份与账号归属不一致");
+            }
+            return snapshot;
         } catch (FeignException exception) {
-            if (exception.status() == 400 || exception.status() == 403 || exception.status() == 404) {
-                throw new BizException(ResultCode.FORBIDDEN, "账号没有有效的 IAM 身份或权限");
-            }
+            throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM 权限服务暂时不可用");
+        } catch (BizException exception) {
+            throw exception;
+        } catch (RuntimeException exception) {
             throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM 权限服务暂时不可用");
         }
     }

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

@@ -20,4 +20,13 @@ public class AuthorizationSnapshot {
     private String clientType;
     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

@@ -1,8 +1,11 @@
 package com.baiyue.auth.client;
 
 import com.baiyue.common.core.api.ApiResponse;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.cloud.openfeign.FeignClient;
 import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestHeader;
 
@@ -14,9 +17,20 @@ public interface IamOnboardingClient {
             @RequestHeader("X-Internal-Service-Token") String internalToken,
             @RequestBody OnboardingRequest request);
 
+    @GetMapping("/merchant-registrations/{authUserId}")
+    ApiResponse<OnboardingResponse> registration(
+            @RequestHeader("X-Internal-Service-Token") String internalToken,
+            @PathVariable("authUserId") Long authUserId);
+
+    @DeleteMapping("/merchant-registrations/{authUserId}/compensation")
+    ApiResponse<Void> compensate(
+            @RequestHeader("X-Internal-Service-Token") String internalToken,
+            @PathVariable("authUserId") Long authUserId);
+
     record OnboardingRequest(Long authUserId, String displayName, String companyName,
-                             String legalPerson, String legalPhone, String contactEmail,
+                             String legalPerson, String administratorPhone, 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/config/AuthSecurityConfig.java

@@ -1,6 +1,5 @@
 package com.baiyue.auth.config;
 
-import com.nimbusds.jose.jwk.source.ImmutableSecret;
 import com.baiyue.common.security.JwtAuthenticationFilter;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
@@ -10,14 +9,11 @@ import org.springframework.security.config.http.SessionCreationPolicy;
 import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
 import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
-import org.springframework.security.oauth2.jwt.JwtEncoder;
-import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
 import org.springframework.security.web.SecurityFilterChain;
 import org.springframework.security.web.AuthenticationEntryPoint;
 import org.springframework.security.web.access.AccessDeniedHandler;
 import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
 
-import java.nio.charset.StandardCharsets;
 
 /**
  * 认证服务安全配置，集中声明密码编码器、JWT 编码器以及认证接口的安全过滤链。
@@ -25,15 +21,21 @@ import java.nio.charset.StandardCharsets;
 @Configuration
 @EnableConfigurationProperties(AuthSecurityProperties.class)
 public class AuthSecurityConfig {
-    @Bean
-    PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(12); }
+    static final String[] PUBLIC_AUTH_ENDPOINTS = {
+        "/api/auth/register",
+        "/api/auth/login",
+        "/api/auth/refresh",
+        "/api/auth/logout",
+        "/api/auth/impersonations/exchange",
+        "/api/auth/.well-known/jwks.json",
+        "/actuator/health",
+        "/v3/api-docs/**",
+        "/swagger-ui/**",
+        "/swagger-ui.html"
+    };
 
     @Bean
-    JwtEncoder jwtEncoder(AuthSecurityProperties properties) {
-        byte[] secret = properties.jwtSecret().getBytes(StandardCharsets.UTF_8);
-        if (secret.length < 32) throw new IllegalStateException("JWT_SECRET 至少需要 32 字节");
-        return new NimbusJwtEncoder(new ImmutableSecret<>(secret));
-    }
+    PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(12); }
 
     @Bean
     SecurityFilterChain authSecurityFilterChain(HttpSecurity http,
@@ -47,8 +49,7 @@ public class AuthSecurityConfig {
             .exceptionHandling(errors -> errors
                 .authenticationEntryPoint(entryPoint).accessDeniedHandler(deniedHandler))
             .authorizeHttpRequests(auth -> auth
-                .requestMatchers("/api/auth/register", "/api/auth/login", "/api/auth/refresh", "/api/auth/logout",
-                    "/actuator/health", "/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
+                .requestMatchers(PUBLIC_AUTH_ENDPOINTS).permitAll()
                 .requestMatchers("/internal/auth/**").permitAll()
                 .anyRequest().authenticated())
             .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)

auth/src/main/java/com/baiyue/auth/config/AuthSecurityProperties.java

@@ -8,7 +8,7 @@ import java.time.Duration;
  * 认证安全配置属性，承载 JWT 密钥、签发方及访问令牌、刷新令牌有效期。
  */
 @ConfigurationProperties(prefix = "baiyue.security")
-public record AuthSecurityProperties(String jwtSecret, String issuer,
+public record AuthSecurityProperties(String jwtSecret, String issuer, String audience,
                                      Duration accessTokenTtl, Duration refreshTokenTtl,
                                      int maxLoginFailures, Duration lockDuration) {
 }

auth/src/main/java/com/baiyue/auth/config/DomesticJwtConfiguration.java

@@ -0,0 +1,22 @@
+package com.baiyue.auth.config;
+
+import com.nimbusds.jose.jwk.source.ImmutableSecret;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
+
+import java.nio.charset.StandardCharsets;
+
+/** 国内现有 HS256 编码器，始终为认证服务主编码器。 */
+@Configuration(proxyBeanMethods = false)
+public class DomesticJwtConfiguration {
+    @Bean("jwtEncoder")
+    @Primary
+    JwtEncoder jwtEncoder(AuthSecurityProperties properties) {
+        byte[] secret = properties.jwtSecret().getBytes(StandardCharsets.UTF_8);
+        if (secret.length < 32) throw new IllegalStateException("JWT_SECRET 至少需要 32 字节");
+        return new NimbusJwtEncoder(new ImmutableSecret<>(secret));
+    }
+}

auth/src/main/java/com/baiyue/auth/config/OverseasJwtConfiguration.java

@@ -0,0 +1,37 @@
+package com.baiyue.auth.config;
+
+import com.nimbusds.jose.jwk.JWKSet;
+import com.nimbusds.jose.jwk.RSAKey;
+import com.nimbusds.jose.jwk.source.ImmutableJWKSet;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
+
+@Configuration(proxyBeanMethods = false)
+@EnableConfigurationProperties(OverseasJwtProperties.class)
+@ConditionalOnProperty(name = "baiyue.security.overseas-jwt.enabled", havingValue = "true")
+public class OverseasJwtConfiguration {
+    @Bean("overseasJwtEncoder")
+    JwtEncoder overseasJwtEncoder(OverseasJwtProperties properties) {
+        try {
+            JWKSet set = JWKSet.parse(properties.rsaJwkSet());
+            RSAKey current = set.getKeyByKeyId(properties.currentKid()) instanceof RSAKey rsa ? rsa : null;
+            if (current == null || !current.isPrivate()) {
+                throw new IllegalStateException("海外 current-kid 必须指向包含私钥的 RSA 密钥");
+            }
+            if (set.getKeys().stream().anyMatch(jwk -> !(jwk instanceof RSAKey))) {
+                throw new IllegalStateException("海外 JWK Set 只能包含 RSA 密钥");
+            }
+            if (set.getKeys().stream().anyMatch(jwk -> !properties.currentKid().equals(jwk.getKeyID())
+                    && jwk instanceof RSAKey rsa && rsa.isPrivate())) {
+                throw new IllegalStateException("海外非当前密钥只能配置公钥");
+            }
+            return new NimbusJwtEncoder(new ImmutableJWKSet<>(set));
+        } catch (java.text.ParseException exception) {
+            throw new IllegalStateException("海外 RSA JWK Set 配置无效", exception);
+        }
+    }
+}

auth/src/main/java/com/baiyue/auth/config/OverseasJwtProperties.java

@@ -0,0 +1,10 @@
+package com.baiyue.auth.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+import java.time.Duration;
+
+/** 海外尾程 RS256 短时令牌配置，默认关闭。 */
+@ConfigurationProperties(prefix = "baiyue.security.overseas-jwt")
+public record OverseasJwtProperties(boolean enabled, String issuer, String audience,
+                                    String rsaJwkSet, String currentKid, Duration accessTokenTtl) { }

auth/src/main/java/com/baiyue/auth/controller/AuthController.java

@@ -8,6 +8,8 @@ import com.baiyue.auth.dto.MerchantRegisterRequest;
 import com.baiyue.auth.dto.MerchantRegisterResponse;
 import com.baiyue.auth.service.MerchantRegistrationService;
 import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.security.SecurityRequirements;
@@ -18,7 +20,11 @@ import org.springframework.web.bind.annotation.*;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import com.baiyue.common.security.AuthenticatedUser;
 import com.baiyue.auth.dto.AccountManagementDtos.ChangePasswordRequest;
+import com.baiyue.auth.dto.AccountManagementDtos.ForcedPasswordChangeRequest;
+import com.baiyue.auth.dto.AccountManagementDtos;
 import com.baiyue.auth.service.AccountManagementService;
+import com.baiyue.auth.service.OverseasTokenService;
+import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.security.access.prepost.PreAuthorize;
 
 /**
@@ -34,20 +40,44 @@ public class AuthController {
     private MerchantRegistrationService registrationService;
     @Resource
     private AccountManagementService accountManagementService;
+    @Resource
+    private ObjectProvider<OverseasTokenService> overseasTokens;
+
+    @PostMapping("/overseas/token")
+    @PreAuthorize("isAuthenticated()")
+    @Operation(summary = "兑换海外尾程访问令牌", description = "使用已通过国内会话校验的身份兑换 15 分钟 RS256 海外令牌。")
+    public ApiResponse<OverseasTokenService.OverseasTokenResponse> exchangeOverseasToken(
+            @AuthenticationPrincipal AuthenticatedUser user) {
+        OverseasTokenService service = overseasTokens.getIfAvailable();
+        if (service == null) throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "海外认证未启用");
+        return ApiResponse.success(service.exchange(user.userId()));
+    }
 
     @PutMapping("/password")
     @PreAuthorize("isAuthenticated()")
     @Operation(summary = "修改当前用户密码")
     public ApiResponse<Void> changePassword(@AuthenticationPrincipal AuthenticatedUser user,
                                             @Valid @RequestBody ChangePasswordRequest request) {
+        if (user.impersonated()) throw new BizException(ResultCode.FORBIDDEN, "代登录会话不能修改密码");
         accountManagementService.changePassword(user.userId(), request);
         return ApiResponse.success(null);
     }
 
+    @PutMapping("/password/forced")
+    @PreAuthorize("isAuthenticated()")
+    @Operation(summary = "完成强制改密")
+    public ApiResponse<Void> forcedChangePassword(@AuthenticationPrincipal AuthenticatedUser user,
+                                                   @Valid @RequestBody ForcedPasswordChangeRequest request) {
+        if (user.impersonated()) throw new BizException(ResultCode.FORBIDDEN, "代登录会话不能修改密码");
+        if (!user.passwordChangeRequired()) throw new BizException(ResultCode.CONFLICT, "当前账号不需要强制改密");
+        accountManagementService.forcedChangePassword(user.userId(), request);
+        return ApiResponse.success(null);
+    }
+
     @SecurityRequirements
     @PostMapping("/register")
     @Operation(summary = "Merchant registration / 客户注册",
-            description = "Create a login account and an enterprise profile awaiting one business-license upload.")
+            description = "Create a login account and enterprise profile. The supplied phone initializes both the first administrator login phone and company contact phone; they are maintained independently after creation. Only the business license and unified social credit code are required for review; legal-person ID is optional.")
     public ApiResponse<MerchantRegisterResponse> register(@Valid @RequestBody MerchantRegisterRequest request) {
         return ApiResponse.success(registrationService.register(request));
     }
@@ -55,10 +85,7 @@ public class AuthController {
     @SecurityRequirements
     @Operation(summary = "Login / 登录", description = "Validate credentials and issue access and refresh tokens. / 校验账号密码并签发访问令牌和刷新令牌。")
     @ApiResponses({
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Login succeeded / 登录成功"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid request / 请求参数错误"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "401", description = "Invalid username or password / 用户名或密码错误"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "429", description = "Account temporarily locked / 账号暂时锁定")
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Success or authentication business failure; inspect body code / 成功或认证业务失败，按响应体 code 判断"),
     })
     @PostMapping("/login")
     public ApiResponse<TokenResponse> login(@Valid @RequestBody LoginRequest request) {
@@ -68,8 +95,7 @@ public class AuthController {
     @SecurityRequirements
     @Operation(summary = "Refresh token / 刷新令牌", description = "Rotate a valid refresh token and issue a new token pair. / 轮换有效刷新令牌并签发新的令牌对。")
     @ApiResponses({
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Token refreshed / 刷新成功"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "401", description = "Refresh token invalid or expired / 刷新令牌无效或已过期")
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Success or refresh-token business failure; inspect body code / 成功或刷新令牌业务失败，按响应体 code 判断")
     })
     @PostMapping("/refresh")
     public ApiResponse<TokenResponse> refresh(@Valid @RequestBody RefreshRequest request) {
@@ -86,4 +112,11 @@ public class AuthController {
         authService.logout(request.refreshToken());
         return ApiResponse.success(null);
     }
+
+    @SecurityRequirements
+    @PostMapping("/impersonations/exchange")
+    public ApiResponse<AuthService.ImpersonationTokenResponse> exchangeImpersonation(
+            @Valid @RequestBody AccountManagementDtos.ImpersonationExchangeRequest request) {
+        return ApiResponse.success(authService.exchangeImpersonationTicket(request.code()));
+    }
 }

auth/src/main/java/com/baiyue/auth/controller/InternalAccountController.java

@@ -2,11 +2,17 @@ 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.*;
 
@@ -16,24 +22,39 @@ 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 {
-    private final AccountManagementService service;
-    private final String configuredToken;
+    @Resource
+    private AccountManagementService service;
+    @Resource
+    private AuthService authService;
+    @Resource
+    private OverseasSessionValidationService overseasSessionValidationService;
+
+    @Value("${baiyue.security.internal-service-token}")
+    private String configuredToken;
     private byte[] tokenBytes;
 
-    public InternalAccountController(AccountManagementService service,
-            @Value("${baiyue.security.internal-service-token}") String configuredToken) {
-        this.service = service;
-        this.configuredToken = configuredToken;
+    @PostConstruct
+    void init() {
+        byte[] configured = configuredToken == null
+                ? new byte[0] : configuredToken.getBytes(StandardCharsets.UTF_8);
+        if (configured.length < 32) {
+            throw new IllegalStateException("INTERNAL_SERVICE_TOKEN 至少需要 32 字节");
+        }
+        tokenBytes = configured;
     }
 
-    @PostConstruct void init() { tokenBytes = configuredToken.getBytes(StandardCharsets.UTF_8); }
-
     @PostMapping
     public ApiResponse<AccountSummary> create(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,
                                                @Valid @RequestBody CreateAccountRequest request) {
         verify(token); return ApiResponse.success(service.create(request));
     }
+    @GetMapping("/availability")
+    public ApiResponse<Boolean> availability(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+                                             @RequestParam String username) {
+        verify(token); return ApiResponse.success(service.usernameAvailable(username));
+    }
     @GetMapping("/{id}")
     public ApiResponse<AccountSummary> summary(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,
                                                 @PathVariable Long id) {
@@ -44,10 +65,62 @@ public class InternalAccountController {
                                     @PathVariable Long id, @Valid @RequestBody UpdateAccountStatusRequest request) {
         verify(token); service.updateStatus(id, request); return ApiResponse.success(null);
     }
+    @PostMapping("/sessions/revoke")
+    public ApiResponse<Void> revokeSessions(
+            @RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+            @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) {
+        verify(token); service.updateProfile(id, request); return ApiResponse.success(null);
+    }
+    @PutMapping("/{id}/login-identifiers")
+    public ApiResponse<AccountSummary> loginIdentifiers(
+            @RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+            @PathVariable Long id, @Valid @RequestBody ChangeLoginIdentifiersRequest request) {
+        verify(token);
+        return ApiResponse.success(service.changeLoginIdentifiers(id, request));
+    }
+    @PutMapping("/{id}/phone")
+    public ApiResponse<Void> phone(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+                                   @PathVariable Long id, @Valid @RequestBody UpdateAccountPhoneRequest request) {
+        verify(token);
+        service.updatePhone(id, request);
+        return ApiResponse.success(null);
+    }
     @PutMapping("/{id}/password")
     public ApiResponse<Void> reset(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,
                                    @PathVariable Long id, @Valid @RequestBody ResetPasswordRequest request) {
-        verify(token); service.resetPassword(id, request); return ApiResponse.success(null);
+        verify(token); service.resetPassword(id, request, request.forceChange()); return ApiResponse.success(null);
+    }
+
+    @PostMapping("/impersonation-tickets")
+    public ApiResponse<ImpersonationTicketResponse> impersonationTicket(
+            @RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+            @Valid @RequestBody ImpersonationTicketRequest request) {
+        verify(token); return ApiResponse.success(authService.createImpersonationTicket(request));
+    }
+
+    @PutMapping("/tenant/{tenantId}/archive")
+    public ApiResponse<Void> archiveTenant(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+                                           @PathVariable Long tenantId) {
+        verify(token); service.archiveTenant(tenantId); return ApiResponse.success(null);
+    }
+    @PutMapping("/{id}/scope")
+    public ApiResponse<Void> scope(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+                                   @PathVariable Long id, @Valid @RequestBody UpdateAccountScopeRequest request) {
+        verify(token); service.updateScope(id, request); return ApiResponse.success(null);
     }
     @DeleteMapping("/{id}/compensation")
     public ApiResponse<Void> compensate(@RequestHeader(value="X-Internal-Service-Token", required=false) String token,

auth/src/main/java/com/baiyue/auth/controller/JwksController.java

@@ -0,0 +1,31 @@
+package com.baiyue.auth.controller;
+
+import com.baiyue.auth.config.OverseasJwtProperties;
+import com.nimbusds.jose.jwk.JWKSet;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.security.SecurityRequirements;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.CacheControl;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+/** 仅在海外 JWT 显式启用后发布 RSA 公钥。 */
+@RestController
+@ConditionalOnProperty(name = "baiyue.security.overseas-jwt.enabled", havingValue = "true")
+public class JwksController {
+    private final OverseasJwtProperties properties;
+
+    public JwksController(OverseasJwtProperties properties) { this.properties = properties; }
+
+    @GetMapping("/api/auth/.well-known/jwks.json")
+    @SecurityRequirements
+    @Operation(summary = "获取海外 JWT 公钥集", description = "仅发布当前和轮换期上一把 RSA 公钥，不包含私钥。")
+    public ResponseEntity<Map<String, Object>> jwks() throws Exception {
+        return ResponseEntity.ok().cacheControl(CacheControl.maxAge(5, TimeUnit.MINUTES).cachePublic())
+            .body(JWKSet.parse(properties.rsaJwkSet()).toPublicJWKSet().toJSONObject());
+    }
+}

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

@@ -2,9 +2,13 @@ package com.baiyue.auth.dto;
 
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.Size;
 import jakarta.validation.constraints.Pattern;
 
+import java.time.LocalDateTime;
+import java.util.Set;
+
 /** 账号安全及内部账号管理契约。 */
 public final class AccountManagementDtos {
     private AccountManagementDtos() { }
@@ -12,14 +16,61 @@ public final class AccountManagementDtos {
     public record ChangePasswordRequest(@NotBlank String oldPassword,
                                         @NotBlank @Size(min = 8, max = 64)
                                         @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d).+$", message = "密码必须同时包含字母和数字") String newPassword) { }
+    public record ForcedPasswordChangeRequest(
+            @NotBlank @Size(min = 8, max = 64)
+            @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d).+$", message = "密码必须同时包含字母和数字")
+            String newPassword) { }
     public record CreateAccountRequest(@NotNull Long accountId,
-                                       @NotBlank @Pattern(regexp = "^[A-Za-z0-9_.@-]{4,64}$") String username,
+                                       @NotBlank @Pattern(regexp = "^[A-Za-z][A-Za-z0-9_.@-]{3,63}$") String username,
+                                       @Pattern(regexp = "^1[3-9]\\d{9}$") String phone,
                                        @NotBlank @Size(min = 8, max = 64)
                                        @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d).+$", message = "密码必须同时包含字母和数字") String password,
                                        @NotBlank String displayName, @NotNull Long tenantId,
-                                       @NotNull Long membershipId) { }
+                                       @NotNull Long membershipId,
+                                       @Pattern(regexp = "MERCHANT|PLATFORM", message = "应用端只能是 MERCHANT 或 PLATFORM")
+                                       String appCode,
+                                       @Pattern(regexp = "ACTIVE|DISABLED", message = "账号状态只能是 ACTIVE 或 DISABLED")
+                                       String accountStatus) {
+        public CreateAccountRequest(Long accountId, String username, String password, String displayName,
+                                    Long tenantId, Long membershipId, String appCode) {
+            this(accountId, username, null, password, displayName, tenantId, membershipId, appCode, "ACTIVE");
+        }
+        public CreateAccountRequest(Long accountId, String username, String password, String displayName,
+                                    Long tenantId, Long membershipId, String appCode, String accountStatus) {
+            this(accountId, username, null, password, displayName, tenantId, membershipId, appCode, accountStatus);
+        }
+    }
+    public record ChangeLoginIdentifiersRequest(
+            @NotBlank @Pattern(regexp = "^[A-Za-z][A-Za-z0-9_.@-]{3,63}$") String username,
+            @NotBlank @Pattern(regexp = "^1[3-9]\\d{9}$") String phone,
+            @NotBlank String currentPassword) { }
+    public record UpdateAccountPhoneRequest(
+            @Pattern(regexp = "^1[3-9]\\d{9}$") String phone) { }
+    public record UpdateAccountProfileRequest(@NotBlank @Size(max = 64) String displayName) { }
     public record UpdateAccountStatusRequest(@NotBlank String status) { }
+    public record RevokeAccountSessionsRequest(
+            @NotEmpty @Size(max = 500) Set<@NotNull Long> accountIds) {
+        public RevokeAccountSessionsRequest {
+            accountIds = Set.copyOf(accountIds);
+        }
+    }
     public record ResetPasswordRequest(@NotBlank @Size(min = 8, max = 64)
-                                       @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d).+$", message = "密码必须同时包含字母和数字") String newPassword) { }
-    public record AccountSummary(Long accountId, String username, String displayName, String status) { }
+                                       @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d).+$", message = "密码必须同时包含字母和数字") String newPassword,
+                                       Boolean forceChangePassword) {
+        public boolean forceChange() { return Boolean.TRUE.equals(forceChangePassword); }
+    }
+    public record ResetPasswordOptions(boolean forceChangePassword) { }
+    public record ImpersonationTicketRequest(@NotNull Long targetAuthUserId, @NotNull Long tenantId,
+                                             @NotNull Long membershipId, @NotNull Long actorUserId,
+                                             @NotNull Long actorMembershipId, @NotBlank String reason) { }
+    public record ImpersonationTicketResponse(String code, String ticketId, long expiresIn) { }
+    public record ImpersonationExchangeRequest(@NotBlank String code) { }
+    public record UpdateAccountScopeRequest(@NotNull Long tenantId, @NotNull Long membershipId,
+                                            @NotBlank @Pattern(regexp = "MERCHANT|PLATFORM") String appCode) { }
+    public record AccountSummary(Long accountId, String username, String phone, String displayName, String status,
+                                 LocalDateTime lastLoginAt, Long tenantId, Long membershipId, String appCode) {
+        public AccountSummary(Long accountId, String username, String displayName, String status) {
+            this(accountId, username, null, displayName, status, null, null, null, null);
+        }
+    }
 }

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

@@ -2,13 +2,15 @@ package com.baiyue.auth.dto;
 
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
 
 /**
  * 登录请求契约，接收账号、密码和目标应用域等统一登录参数。
  */
 @Schema(name = "LoginRequest", description = "Unified login credentials / 统一登录凭据")
 public record LoginRequest(
-    @Schema(description = "Login username / 登录用户名", example = "merchant_admin") @NotBlank String username,
+    @Schema(description = "Username or mainland China mobile number / 用户名或中国大陆手机号", example = "merchant_admin")
+    @NotBlank @Size(max = 64) String loginId,
     @Schema(description = "Login password / 登录密码", example = "ChangeMe123!", format = "password") @NotBlank String password
 ) {
-}
+}

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

@@ -8,12 +8,13 @@ import jakarta.validation.constraints.Size;
 
 @Schema(name = "MerchantRegisterRequest", description = "Phase-one merchant account registration")
 public record MerchantRegisterRequest(
-        @NotBlank @Pattern(regexp = "[A-Za-z0-9_]{4,64}") String username,
+        @NotBlank @Pattern(regexp = "^[A-Za-z][A-Za-z0-9_.@-]{3,63}$") String username,
         @NotBlank @Size(min = 8, max = 72) String password,
         @NotBlank @Size(max = 64) String displayName,
         @NotBlank @Size(max = 128) String companyName,
-        @NotBlank @Size(max = 64) String legalPerson,
-        @NotBlank @Size(max = 32) String legalPhone,
+        @Size(max = 64) String legalPerson,
+        @Schema(description = "首个企业管理员的登录手机号；注册时同时初始化企业联系电话，创建后两者独立维护")
+        @NotBlank @Pattern(regexp = "^1[3-9]\\d{9}$") String phone,
         @Email @Size(max = 128) String contactEmail,
         @Size(min = 2, max = 2) String countryCode,
         @Size(max = 255) String address

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

@@ -2,6 +2,8 @@ package com.baiyue.auth.dto;
 
 import io.swagger.v3.oas.annotations.media.Schema;
 
+import java.util.Set;
+
 /**
  * 认证令牌响应契约，返回访问令牌、刷新令牌及其有效期等会话信息。
  */
@@ -11,6 +13,16 @@ public record TokenResponse(
     @Schema(description = "JWT access token / JWT 访问令牌", format = "password") String accessToken,
     @Schema(description = "Access token lifetime in seconds / 访问令牌有效秒数", example = "1800") long expiresIn,
     @Schema(description = "Refresh token / 刷新令牌", format = "password") String refreshToken,
-    @Schema(description = "Refresh token lifetime in seconds / 刷新令牌有效秒数", example = "604800") long refreshExpiresIn
+    @Schema(description = "Refresh token lifetime in seconds / 刷新令牌有效秒数", example = "604800") long refreshExpiresIn,
+    @Schema(description = "Short-lived overseas API access token; null only when overseas JWT is disabled / 海外 API 短时访问令牌；仅海外 JWT 未启用时为空",
+        format = "password", nullable = true) String overseasAccessToken,
+    @Schema(description = "Overseas access token lifetime in seconds; zero only when overseas JWT is disabled / 海外访问令牌有效秒数；仅海外 JWT 未启用时为 0",
+        example = "900", minimum = "0") long overseasExpiresIn,
+    @Schema(description = "Current role snapshot returned outside JWT / JWT 外返回的当前角色快照") Set<String> roles,
+    @Schema(description = "Current authority snapshot returned outside JWT / JWT 外返回的当前权限快照") Set<String> authorities
 ) {
-}
+    public TokenResponse {
+        roles = roles == null ? Set.of() : Set.copyOf(roles);
+        authorities = authorities == null ? Set.of() : Set.copyOf(authorities);
+    }
+}

auth/src/main/java/com/baiyue/auth/entity/AuthAccount.java

@@ -18,12 +18,14 @@ import java.time.LocalDateTime;
 public class AuthAccount {
     @TableId private Long id;
     private String username;
+    private String phone;
     private String passwordHash;
     private String displayName;
     private String accountStatus;
     private Integer failedLoginCount;
     private LocalDateTime lockedUntil;
     private Integer tokenVersion;
+    private Boolean passwordChangeRequired;
     private Long defaultTenantId;
     private Long operatorTenantId;
     private Long defaultMembershipId;

auth/src/main/java/com/baiyue/auth/mapper/AuthAccountMapper.java

@@ -1,9 +1,12 @@
 package com.baiyue.auth.mapper;
 
+import org.apache.ibatis.annotations.Mapper;
+
 import com.baiyue.auth.entity.AuthAccount;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 
 /**
  * 认证账号 MyBatis-Plus 数据访问接口，负责 {@code auth_account} 表的基础持久化操作。
  */
+@Mapper
 public interface AuthAccountMapper extends BaseMapper<AuthAccount> { }

auth/src/main/java/com/baiyue/auth/mapper/AuthRefreshTokenMapper.java

@@ -1,9 +1,12 @@
 package com.baiyue.auth.mapper;
 
+import org.apache.ibatis.annotations.Mapper;
+
 import com.baiyue.auth.entity.AuthRefreshToken;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 
 /**
  * 刷新令牌 MyBatis-Plus 数据访问接口，负责 {@code auth_refresh_token} 表的基础持久化操作。
  */
+@Mapper
 public interface AuthRefreshTokenMapper extends BaseMapper<AuthRefreshToken> { }

auth/src/main/java/com/baiyue/auth/repository/AuthAccountRepository.java

@@ -1,20 +1,20 @@
 package com.baiyue.auth.repository;
 
+import jakarta.annotation.Resource;
+
 import com.baiyue.auth.entity.AuthAccount;
 import com.baiyue.auth.mapper.AuthAccountMapper;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import org.springframework.stereotype.Repository;
+import java.util.List;
 
 /**
  * 认证账号仓储，封装按用户名或主键查询以及账号保存操作，隔离服务层与 MyBatis-Plus 查询细节。
  */
 @Repository
 public class AuthAccountRepository {
-    private final AuthAccountMapper mapper;
-
-    public AuthAccountRepository(AuthAccountMapper mapper) {
-        this.mapper = mapper;
-    }
+    @Resource
+    private AuthAccountMapper mapper;
 
     public AuthAccount findByUsername(String username) {
         return mapper.selectOne(new LambdaQueryWrapper<AuthAccount>()
@@ -22,17 +22,46 @@ public class AuthAccountRepository {
             .last("LIMIT 1"));
     }
 
+    public AuthAccount findByPhone(String phone) {
+        return mapper.selectOne(new LambdaQueryWrapper<AuthAccount>()
+            .eq(AuthAccount::getPhone, phone)
+            .last("LIMIT 1"));
+    }
+
     public boolean existsByUsername(String username) {
         return mapper.selectCount(new LambdaQueryWrapper<AuthAccount>()
                 .eq(AuthAccount::getUsername, username)) > 0;
     }
 
+    public boolean existsByPhone(String phone) {
+        return mapper.selectCount(new LambdaQueryWrapper<AuthAccount>()
+                .eq(AuthAccount::getPhone, phone)) > 0;
+    }
+
+    public boolean existsByUsernameForOtherAccount(String username, Long accountId) {
+        return mapper.selectCount(new LambdaQueryWrapper<AuthAccount>()
+                .eq(AuthAccount::getUsername, username)
+                .ne(AuthAccount::getId, accountId)) > 0;
+    }
+
+    public boolean existsByPhoneForOtherAccount(String phone, Long accountId) {
+        return mapper.selectCount(new LambdaQueryWrapper<AuthAccount>()
+                .eq(AuthAccount::getPhone, phone)
+                .ne(AuthAccount::getId, accountId)) > 0;
+    }
+
     public void insert(AuthAccount account) { mapper.insert(account); }
 
     public AuthAccount findById(Long id) {
         return mapper.selectById(id);
     }
 
+    public List<AuthAccount> findMerchantByTenant(Long tenantId) {
+        return mapper.selectList(new LambdaQueryWrapper<AuthAccount>()
+                .eq(AuthAccount::getDefaultTenantId, tenantId)
+                .eq(AuthAccount::getDefaultAppCode, "MERCHANT"));
+    }
+
     public void save(AuthAccount account) {
         mapper.updateById(account);
     }

auth/src/main/java/com/baiyue/auth/repository/AuthRefreshTokenRepository.java

@@ -1,5 +1,7 @@
 package com.baiyue.auth.repository;
 
+import jakarta.annotation.Resource;
+
 import com.baiyue.auth.entity.AuthRefreshToken;
 import com.baiyue.auth.mapper.AuthRefreshTokenMapper;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
@@ -10,11 +12,8 @@ import org.springframework.stereotype.Repository;
  */
 @Repository
 public class AuthRefreshTokenRepository {
-    private final AuthRefreshTokenMapper mapper;
-
-    public AuthRefreshTokenRepository(AuthRefreshTokenMapper mapper) {
-        this.mapper = mapper;
-    }
+    @Resource
+    private AuthRefreshTokenMapper mapper;
 
     public AuthRefreshToken findByHash(String tokenHash, boolean forUpdate) {
         String limit = forUpdate ? "LIMIT 1 FOR UPDATE" : "LIMIT 1";

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

@@ -11,6 +11,10 @@ import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 import com.baiyue.common.audit.BusinessAudit;
 
+import java.util.Locale;
+import java.util.Objects;
+import java.util.Set;
+
 /** 账号生命周期管理，所有密码只以 BCrypt 摘要写入数据库。 */
 @Service
 public class AccountManagementService {
@@ -18,38 +22,71 @@ public class AccountManagementService {
     @Resource private PasswordEncoder passwordEncoder;
     @Resource private TokenSessionStore tokenSessionStore;
 
+    public boolean usernameAvailable(String username) {
+        return username != null && !username.isBlank() && !repository.existsByUsername(username.trim());
+    }
+
     @Transactional
     @BusinessAudit(event = "PASSWORD_CHANGE", resourceType = "ACCOUNT", resourceId = "#accountId", description = "修改本人密码", captureAfter = false)
     public void changePassword(Long accountId, ChangePasswordRequest request) {
         AuthAccount account = required(accountId);
+        if (Boolean.TRUE.equals(account.getPasswordChangeRequired())) {
+            throw new BizException(ResultCode.CONFLICT, "请先使用强制改密接口设置新密码");
+        }
         if (!passwordEncoder.matches(request.oldPassword(), account.getPasswordHash())) {
             throw new BizException(ResultCode.BAD_REQUEST, "原密码错误");
         }
         if (passwordEncoder.matches(request.newPassword(), account.getPasswordHash())) {
             throw new BizException(ResultCode.BAD_REQUEST, "新密码不能与原密码相同");
         }
-        setPasswordAndRevoke(account, request.newPassword());
+        setPasswordAndRevoke(account, request.newPassword(), false);
+    }
+
+    @Transactional
+    @BusinessAudit(event = "PASSWORD_FORCED_CHANGE", resourceType = "ACCOUNT", resourceId = "#accountId",
+            description = "完成管理员重置后的强制改密", captureAfter = false)
+    public void forcedChangePassword(Long accountId, ForcedPasswordChangeRequest request) {
+        AuthAccount account = required(accountId);
+        if (!Boolean.TRUE.equals(account.getPasswordChangeRequired())) {
+            throw new BizException(ResultCode.CONFLICT, "当前账号不需要强制改密");
+        }
+        if (passwordEncoder.matches(request.newPassword(), account.getPasswordHash())) {
+            throw new BizException(ResultCode.BAD_REQUEST, "新密码不能与当前密码相同");
+        }
+        setPasswordAndRevoke(account, request.newPassword(), false);
     }
 
     @Transactional
     @BusinessAudit(event = "ACCOUNT_CREATE", resourceType = "ACCOUNT",
         resourceId = "#request.accountId", description = "创建认证账号")
     public AccountSummary create(CreateAccountRequest request) {
-        if (repository.existsByUsername(request.username()) || repository.findById(request.accountId()) != null) {
+        String appCode = request.appCode() == null ? "MERCHANT"
+                : request.appCode().trim().toUpperCase(Locale.ROOT);
+        validateScope(appCode, request.tenantId());
+        AuthAccount existing = repository.findById(request.accountId());
+        if (existing != null) {
+            if (sameIdentity(existing, request, appCode)) return summary(existing);
+            throw new BizException(ResultCode.CONFLICT, "认证账号标识已被其他成员使用");
+        }
+        if (repository.existsByUsername(request.username())) {
             throw new BizException(ResultCode.CONFLICT, "登录账号已存在");
         }
+        if (request.phone() != null && repository.existsByPhone(request.phone())) {
+            throw new BizException(ResultCode.CONFLICT, "手机号已存在");
+        }
         AuthAccount account = new AuthAccount();
         account.setId(request.accountId());
         account.setUsername(request.username());
+        account.setPhone(request.phone());
         account.setPasswordHash(passwordEncoder.encode(request.password()));
         account.setDisplayName(request.displayName());
-        account.setAccountStatus("ACTIVE");
+        account.setAccountStatus(request.accountStatus() == null ? "ACTIVE" : request.accountStatus());
         account.setFailedLoginCount(0);
         account.setTokenVersion(1);
         account.setDefaultTenantId(request.tenantId());
         account.setOperatorTenantId(request.tenantId());
         account.setDefaultMembershipId(request.membershipId());
-        account.setDefaultAppCode("MERCHANT");
+        account.setDefaultAppCode(appCode);
         account.setDeleted(0);
         repository.insert(account);
         return summary(account);
@@ -66,10 +103,94 @@ public class AccountManagementService {
         bumpVersion(account);
     }
 
+    @Transactional
+    @BusinessAudit(event = "ACCOUNT_SESSIONS_REVOKE", resourceType = "ACCOUNT_BATCH",
+            resourceId = "'RBAC_CHANGE'", description = "RBAC 变更批量撤销账号会话",
+            captureBefore = false, captureAfter = false)
+    public void revokeSessions(Set<Long> accountIds) {
+        accountIds.forEach(accountId -> bumpVersion(required(accountId)));
+    }
+
+    @Transactional
+    @BusinessAudit(event = "ACCOUNT_PROFILE_CHANGE", resourceType = "ACCOUNT", resourceId = "#accountId",
+            description = "同步账号显示名称", captureAfter = false)
+    public void updateProfile(Long accountId, UpdateAccountProfileRequest request) {
+        AuthAccount account = required(accountId);
+        if (Objects.equals(account.getDisplayName(), request.displayName())) return;
+        account.setDisplayName(request.displayName());
+        bumpVersion(account);
+    }
+
+    @Transactional
+    @BusinessAudit(event = "ACCOUNT_LOGIN_IDENTIFIERS_CHANGE", resourceType = "ACCOUNT", resourceId = "#accountId",
+            description = "修改本人用户名和手机号", captureAfter = false)
+    public AccountSummary changeLoginIdentifiers(Long accountId, ChangeLoginIdentifiersRequest request) {
+        AuthAccount account = required(accountId);
+        if (!passwordEncoder.matches(request.currentPassword(), account.getPasswordHash())) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "当前密码错误");
+        }
+        String username = request.username().trim();
+        String phone = request.phone().trim();
+        if (repository.existsByUsernameForOtherAccount(username, accountId)) {
+            throw new BizException(ResultCode.CONFLICT, "用户名已存在");
+        }
+        if (repository.existsByPhoneForOtherAccount(phone, accountId)) {
+            throw new BizException(ResultCode.CONFLICT, "手机号已存在");
+        }
+        if (Objects.equals(account.getUsername(), username) && Objects.equals(account.getPhone(), phone)) {
+            return summary(account);
+        }
+        account.setUsername(username);
+        account.setPhone(phone);
+        bumpVersion(account);
+        return summary(account);
+    }
+
+    @Transactional
+    @BusinessAudit(event = "ACCOUNT_PHONE_SYNC", resourceType = "ACCOUNT", resourceId = "#accountId",
+            description = "同步受管账号手机号", captureAfter = false)
+    public void updatePhone(Long accountId, UpdateAccountPhoneRequest request) {
+        AuthAccount account = required(accountId);
+        String phone = request.phone() == null ? null : request.phone().trim();
+        if (Objects.equals(account.getPhone(), phone)) return;
+        if (phone != null && repository.existsByPhoneForOtherAccount(phone, accountId)) {
+            throw new BizException(ResultCode.CONFLICT, "手机号已存在");
+        }
+        account.setPhone(phone);
+        bumpVersion(account);
+    }
+
     @Transactional
     @BusinessAudit(event = "PASSWORD_RESET", resourceType = "ACCOUNT", resourceId = "#accountId", description = "管理员重置密码", captureAfter = false)
-    public void resetPassword(Long accountId, ResetPasswordRequest request) {
-        setPasswordAndRevoke(required(accountId), request.newPassword());
+    public void resetPassword(Long accountId, ResetPasswordRequest request, boolean forceChangePassword) {
+        setPasswordAndRevoke(required(accountId), request.newPassword(), forceChangePassword);
+    }
+
+    @Transactional
+    @BusinessAudit(event = "CUSTOMER_ACCOUNT_ARCHIVE", resourceType = "TENANT", resourceId = "#tenantId",
+            description = "归档客户并撤销客户账号", captureBefore = false, captureAfter = false)
+    public void archiveTenant(Long tenantId) {
+        for (AuthAccount account : repository.findMerchantByTenant(tenantId)) {
+            account.setAccountStatus("DISABLED");
+            account.setPasswordChangeRequired(false);
+            account.setTokenVersion((account.getTokenVersion() == null ? 0 : account.getTokenVersion()) + 1);
+            repository.save(account);
+            tokenSessionStore.revokeAll(account.getId());
+        }
+    }
+
+    @Transactional
+    @BusinessAudit(event = "ACCOUNT_SCOPE_CHANGE", resourceType = "ACCOUNT", resourceId = "#accountId",
+            description = "修改账号所属租户", captureAfter = false)
+    public void updateScope(Long accountId, UpdateAccountScopeRequest request) {
+        String appCode = request.appCode().trim().toUpperCase(Locale.ROOT);
+        validateScope(appCode, request.tenantId());
+        AuthAccount account = required(accountId);
+        account.setDefaultTenantId(request.tenantId());
+        account.setOperatorTenantId(request.tenantId());
+        account.setDefaultMembershipId(request.membershipId());
+        account.setDefaultAppCode(appCode);
+        bumpVersion(account);
     }
 
     @Transactional
@@ -86,10 +207,11 @@ public class AccountManagementService {
 
     public AccountSummary summary(Long accountId) { return summary(required(accountId)); }
 
-    private void setPasswordAndRevoke(AuthAccount account, String password) {
+    private void setPasswordAndRevoke(AuthAccount account, String password, boolean forceChangePassword) {
         account.setPasswordHash(passwordEncoder.encode(password));
         account.setFailedLoginCount(0);
         account.setLockedUntil(null);
+        account.setPasswordChangeRequired(forceChangePassword);
         bumpVersion(account);
     }
 
@@ -106,6 +228,27 @@ public class AccountManagementService {
     }
 
     private AccountSummary summary(AuthAccount a) {
-        return new AccountSummary(a.getId(), a.getUsername(), a.getDisplayName(), a.getAccountStatus());
+        return new AccountSummary(a.getId(), a.getUsername(), a.getPhone(), a.getDisplayName(), a.getAccountStatus(),
+                a.getLastLoginAt(), a.getDefaultTenantId(), a.getDefaultMembershipId(), a.getDefaultAppCode());
+    }
+
+    private void validateScope(String appCode, Long tenantId) {
+        if (!"MERCHANT".equals(appCode) && !"PLATFORM".equals(appCode)) {
+            throw new BizException(ResultCode.BAD_REQUEST, "应用端只能是 MERCHANT 或 PLATFORM");
+        }
+        if (("PLATFORM".equals(appCode) && tenantId != 0L)
+                || ("MERCHANT".equals(appCode) && tenantId <= 0L)) {
+            throw new BizException(ResultCode.BAD_REQUEST, "账号应用端与租户范围不匹配");
+        }
+    }
+
+    private boolean sameIdentity(AuthAccount account, CreateAccountRequest request, String appCode) {
+        return Objects.equals(account.getUsername(), request.username())
+                && Objects.equals(account.getPhone(), request.phone())
+                && Objects.equals(account.getDefaultTenantId(), request.tenantId())
+                && Objects.equals(account.getOperatorTenantId(), request.tenantId())
+                && Objects.equals(account.getDefaultMembershipId(), request.membershipId())
+                && Objects.equals(account.getDefaultAppCode(), appCode)
+                && !Integer.valueOf(1).equals(account.getDeleted());
     }
 }

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

@@ -7,6 +7,8 @@ import com.baiyue.auth.entity.AuthAccount;
 import com.baiyue.auth.repository.AuthAccountRepository;
 import com.baiyue.auth.dto.LoginRequest;
 import com.baiyue.auth.dto.TokenResponse;
+import com.baiyue.auth.dto.AccountManagementDtos.ImpersonationTicketRequest;
+import com.baiyue.auth.dto.AccountManagementDtos.ImpersonationTicketResponse;
 import com.baiyue.common.audit.BusinessAudit;
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
@@ -21,15 +23,18 @@ import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
 import org.springframework.security.oauth2.jwt.JwsHeader;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
+import org.springframework.beans.factory.ObjectProvider;
 
 import java.security.SecureRandom;
 import java.time.Instant;
 import java.time.LocalDateTime;
 import java.util.Base64;
 import java.util.UUID;
+import java.time.Duration;
+import java.util.List;
 
 /**
- * 统一认证应用服务，编排密码校验、IAM 权限快照加载、JWT 签发、刷新令牌轮换与注销事务。
+ * 统一认证应用服务，编排密码校验、IAM 权限快照加载、小 JWT 签发、刷新令牌轮换与注销事务。
  */
 @Service
 public class AuthService {
@@ -45,15 +50,20 @@ public class AuthService {
     private AuthorizationLoader authorizationLoader;
     @Resource
     private TokenSessionStore tokenSessionStore;
+    @Resource
+    private ObjectProvider<OverseasTokenService> overseasTokens;
 
     private final SecureRandom secureRandom = new SecureRandom();
 
 
     @Transactional
-    @BusinessAudit(event = "AUTH_LOGIN", resourceType = "ACCOUNT", resourceId = "#request.username",
+    @BusinessAudit(event = "AUTH_LOGIN", resourceType = "ACCOUNT", resourceId = "#request.loginId",
         description = "User login / 用户登录", captureAfter = false)
     public TokenResponse login(LoginRequest request) {
-        AuthAccount account = accountRepository.findByUsername(request.username());
+        String loginId = request.loginId().trim();
+        AuthAccount account = loginId.matches("^1[3-9]\\d{9}$")
+                ? accountRepository.findByPhone(loginId)
+                : accountRepository.findByUsername(loginId);
         if (account == null) throw invalidCredentials();
         LocalDateTime now = LocalDateTime.now();
         if (!"ACTIVE".equals(account.getAccountStatus()))
@@ -104,34 +114,122 @@ public class AuthService {
         Instant issuedAt = Instant.now();
         String jwtId = UUID.randomUUID().toString();
         Instant expiresAt = issuedAt.plus(properties.accessTokenTtl());
-        JwtClaimsSet claims = JwtClaimsSet.builder()
-            .issuer(properties.issuer()).id(jwtId).issuedAt(issuedAt).expiresAt(expiresAt)
+        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())
             .claim("app_code", account.getDefaultAppCode())
             .claim("client_type", authorization.getClientType())
-            .claim("roles", authorization.getRoles())
-            .claim("permissions", authorization.getPermissions())
             .claim("token_version", account.getTokenVersion())
-            .build();
+            .claim("password_change_required", Boolean.TRUE.equals(account.getPasswordChangeRequired()))
+            .claim("userId", account.getId())
+            .claim("tenantId", account.getDefaultTenantId())
+            .claim("appCode", account.getDefaultAppCode())
+            .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(
-            JwsHeader.with(MacAlgorithm.HS256).build(), claims)).getTokenValue();
+            signingHeader(), claims)).getTokenValue();
 
         byte[] random = new byte[48];
         secureRandom.nextBytes(random);
         String rawRefresh = Base64.getUrlEncoder().withoutPadding().encodeToString(random);
-        tokenSessionStore.store(jwtId, account.getId(), rawRefresh,
+        tokenSessionStore.store(jwtId, account.getId(), authorization.getRoles(), authorization.getPermissions(), rawRefresh,
                 properties.accessTokenTtl(), properties.refreshTokenTtl());
+        OverseasTokenService service = overseasTokens.getIfAvailable();
+        OverseasTokenService.OverseasTokenResponse overseas = service == null
+                ? null : service.issue(account, authorization);
         return new TokenResponse("Bearer", accessToken, properties.accessTokenTtl().toSeconds(),
-            rawRefresh, properties.refreshTokenTtl().toSeconds());
+            rawRefresh, properties.refreshTokenTtl().toSeconds(),
+            overseas == null ? null : overseas.accessToken(),
+            overseas == null ? 0L : overseas.expiresIn(),
+            authorization.getRoles(), authorization.getPermissions());
+    }
+
+    @Transactional
+    @BusinessAudit(event = "CUSTOMER_IMPERSONATION_TICKET_CREATE", resourceType = "IMPERSONATION",
+        resourceId = "#request.tenantId", description = "创建客户代登录授权码", captureBefore = false, captureAfter = false)
+    public ImpersonationTicketResponse createImpersonationTicket(ImpersonationTicketRequest request) {
+        AuthAccount account = accountRepository.findById(request.targetAuthUserId());
+        if (account == null || !"ACTIVE".equals(account.getAccountStatus())
+                || !"MERCHANT".equals(account.getDefaultAppCode())
+                || !request.tenantId().equals(account.getDefaultTenantId())
+                || !request.membershipId().equals(account.getDefaultMembershipId())) {
+            throw new BizException(ResultCode.CONFLICT, "目标客户管理员账号不可代登录");
+        }
+        byte[] bytes = new byte[48];
+        secureRandom.nextBytes(bytes);
+        String code = Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
+        String ticketId = UUID.randomUUID().toString();
+        tokenSessionStore.storeImpersonationTicket(code,
+                new TokenSessionStore.ImpersonationTicket(ticketId, account.getId(), request.tenantId(),
+                        request.membershipId(), request.actorUserId(), request.actorMembershipId(), request.reason()),
+                Duration.ofSeconds(60));
+        return new ImpersonationTicketResponse(code, ticketId, 60);
+    }
+
+    @Transactional
+    @BusinessAudit(event = "CUSTOMER_IMPERSONATION_EXCHANGE", resourceType = "IMPERSONATION",
+        resourceId = "'IMPERSONATION_EXCHANGE'", description = "兑换客户代登录授权码", captureBefore = false, captureAfter = false)
+    public ImpersonationTokenResponse exchangeImpersonationTicket(String code) {
+        TokenSessionStore.ImpersonationTicket ticket = tokenSessionStore.consumeImpersonationTicket(code);
+        if (ticket == null) throw new BizException(ResultCode.UNAUTHORIZED, "代登录授权码无效或已过期");
+        AuthAccount account = accountRepository.findById(ticket.targetAuthUserId());
+        if (account == null || !"ACTIVE".equals(account.getAccountStatus()))
+            throw new BizException(ResultCode.UNAUTHORIZED, "目标客户账号不可用");
+        AuthorizationSnapshot authorization = authorizationLoader.load(account);
+        Instant issuedAt = Instant.now();
+        Instant expiresAt = issuedAt.plus(Duration.ofMinutes(15));
+        String jwtId = UUID.randomUUID().toString();
+        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("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())
+                .claim("userId", account.getId()).claim("tenantId", account.getDefaultTenantId())
+                .claim("appCode", "MERCHANT")
+                .claim("permissionVersion", account.getTokenVersion())
+                .claim("impersonated", true).claim("impersonation_id", ticket.ticketId())
+                .claim("actor_user_id", ticket.actorUserId()).claim("actor_membership_id", ticket.actorMembershipId())
+                .claim("password_change_required", Boolean.TRUE.equals(account.getPasswordChangeRequired())).build();
+        String accessToken = jwtEncoder.encode(JwtEncoderParameters.from(signingHeader(), claims)).getTokenValue();
+        tokenSessionStore.storeAccessOnly(jwtId, account.getId(), authorization.getRoles(),
+                authorization.getPermissions(), Duration.ofMinutes(15));
+        OverseasTokenService service = overseasTokens.getIfAvailable();
+        OverseasTokenService.OverseasTokenResponse overseas = service == null
+                ? null : service.issue(account, authorization);
+        return new ImpersonationTokenResponse("Bearer", accessToken, 900,
+                overseas == null ? null : overseas.accessToken(),
+                overseas == null ? 0L : overseas.expiresIn(),
+                authorization.getRoles(), authorization.getPermissions());
+    }
+
+    public record ImpersonationTokenResponse(String tokenType, String accessToken, long expiresIn,
+                                              String overseasAccessToken, long overseasExpiresIn,
+                                              java.util.Set<String> roles,
+                                              java.util.Set<String> authorities) {
+        public ImpersonationTokenResponse {
+            roles = roles == null ? java.util.Set.of() : java.util.Set.copyOf(roles);
+            authorities = authorities == null ? java.util.Set.of() : java.util.Set.copyOf(authorities);
+        }
+    }
+
+    private JwsHeader signingHeader() {
+        return JwsHeader.with(MacAlgorithm.HS256).build();
     }
 
     private static BizException invalidCredentials() {
-        return new BizException(ResultCode.UNAUTHORIZED, "用户名或密码错误");
+        return new BizException(ResultCode.UNAUTHORIZED, "登录标识或密码错误");
     }
 
 }

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

@@ -11,13 +11,21 @@ import com.baiyue.common.audit.BusinessAudit;
 import com.baomidou.mybatisplus.core.toolkit.IdWorker;
 import feign.FeignException;
 import jakarta.annotation.Resource;
+import org.springframework.dao.DuplicateKeyException;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.support.TransactionSynchronization;
+import org.springframework.transaction.support.TransactionSynchronizationManager;
 import org.springframework.transaction.annotation.Transactional;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.concurrent.atomic.AtomicBoolean;
 
 @Service
 public class MerchantRegistrationService {
+    private static final Logger LOGGER = LoggerFactory.getLogger(MerchantRegistrationService.class);
     @Resource private AuthAccountRepository accountRepository;
     @Resource private PasswordEncoder passwordEncoder;
     @Resource private IamOnboardingClient onboardingClient;
@@ -27,29 +35,66 @@ public class MerchantRegistrationService {
     @BusinessAudit(event = "MERCHANT_REGISTER", resourceType = "ACCOUNT",
         resourceId = "#request.username", description = "商户注册", captureAfter = false)
     public MerchantRegisterResponse register(MerchantRegisterRequest request) {
-        if (accountRepository.existsByUsername(request.username())) {
-            throw new BizException(ResultCode.CONFLICT, "Username already exists");
+        AuthAccount usernameAccount = accountRepository.findByUsername(request.username());
+        AuthAccount phoneAccount = accountRepository.findByPhone(request.phone());
+        if (usernameAccount != null && phoneAccount != null
+                && usernameAccount.getId().equals(phoneAccount.getId())
+                && "MERCHANT".equals(usernameAccount.getDefaultAppCode())
+                && "ACTIVE".equals(usernameAccount.getAccountStatus())
+                && passwordEncoder.matches(request.password(), usernameAccount.getPasswordHash())) {
+            return existingRegistration(usernameAccount);
+        }
+        if (usernameAccount != null) {
+            throw new BizException(ResultCode.CONFLICT, "用户名已存在");
+        }
+        if (phoneAccount != null) {
+            throw new BizException(ResultCode.CONFLICT, "该手机号已注册，请直接登录后继续完善企业资质");
         }
         long accountId = IdWorker.getId();
+        String passwordHash = passwordEncoder.encode(request.password());
+        AtomicBoolean compensationCompleted = new AtomicBoolean(false);
+        registerRollbackCompensation(accountId, compensationCompleted);
         IamOnboardingClient.OnboardingResponse onboarding;
         try {
             var response = onboardingClient.register(internalToken,
                     new IamOnboardingClient.OnboardingRequest(accountId, request.displayName(),
-                            request.companyName(), request.legalPerson(), request.legalPhone(),
+                            request.companyName(), request.legalPerson(), request.phone(),
                             request.contactEmail(), request.countryCode(), request.address()));
-            if (response == null || !response.successful() || response.data() == null) {
+            if (response == null) {
+                throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM registration failed");
+            }
+            if (!response.successful()) {
+                ResultCode code = ResultCode.of(response.code());
+                String message = response.message() == null || response.message().isBlank()
+                        ? code.message() : response.message();
+                throw new BizException(code, message);
+            }
+            if (response.data() == null) {
                 throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM registration failed");
             }
             onboarding = response.data();
         } catch (FeignException exception) {
-            if (exception.status() == 409) throw new BizException(ResultCode.CONFLICT, "Enterprise already exists");
-            throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM registration service is unavailable");
+            BizException failure = new BizException(ResultCode.SERVICE_UNAVAILABLE,
+                    "IAM registration service is unavailable");
+            failure.addSuppressed(exception);
+            compensateOnboarding(accountId, failure, compensationCompleted);
+            throw failure;
+        } catch (BizException exception) {
+            compensateOnboarding(accountId, exception, compensationCompleted);
+            throw exception;
+        } catch (RuntimeException exception) {
+            BizException failure = new BizException(ResultCode.SERVICE_UNAVAILABLE,
+                    "IAM registration service is unavailable");
+            failure.addSuppressed(exception);
+            compensateOnboarding(accountId, failure, compensationCompleted);
+            throw failure;
         }
 
         AuthAccount account = new AuthAccount();
         account.setId(accountId);
         account.setUsername(request.username());
-        account.setPasswordHash(passwordEncoder.encode(request.password()));
+        account.setPhone(request.phone());
+        account.setPasswordHash(passwordHash);
         account.setDisplayName(request.displayName());
         account.setAccountStatus("ACTIVE");
         account.setFailedLoginCount(0);
@@ -59,8 +104,80 @@ public class MerchantRegistrationService {
         account.setDefaultMembershipId(onboarding.membershipId());
         account.setDefaultAppCode("MERCHANT");
         account.setDeleted(0);
-        accountRepository.insert(account);
+        try {
+            accountRepository.insert(account);
+        } catch (DuplicateKeyException exception) {
+            BizException failure = new BizException(ResultCode.CONFLICT, "用户名或手机号已存在");
+            failure.addSuppressed(exception);
+            compensateOnboarding(accountId, failure, compensationCompleted);
+            throw failure;
+        } catch (RuntimeException exception) {
+            compensateOnboarding(accountId, exception, compensationCompleted);
+            throw exception;
+        }
         return new MerchantRegisterResponse(accountId, onboarding.tenantId(), onboarding.membershipId(),
-                onboarding.tenantStatus(), "LOGIN_AND_UPLOAD_BUSINESS_LICENSE");
+                onboarding.tenantStatus(), onboarding.dimensionInitializationStatus(),
+                "LOGIN_AND_COMPLETE_QUALIFICATIONS");
+    }
+
+    private MerchantRegisterResponse existingRegistration(AuthAccount account) {
+        try {
+            var response = onboardingClient.registration(internalToken, account.getId());
+            if (response == null || !response.successful() || response.data() == null) {
+                throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "注册状态暂时无法确认，请直接登录后继续完善企业资质");
+            }
+            var onboarding = response.data();
+            if (!java.util.Set.of("PROFILE_REQUIRED", "REJECTED").contains(onboarding.tenantStatus())) {
+                throw new BizException(ResultCode.CONFLICT, "该账号已注册，请直接登录");
+            }
+            return new MerchantRegisterResponse(account.getId(), onboarding.tenantId(), onboarding.membershipId(),
+                    onboarding.tenantStatus(), onboarding.dimensionInitializationStatus(),
+                    "LOGIN_AND_COMPLETE_QUALIFICATIONS");
+        } catch (FeignException exception) {
+            throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "注册状态暂时无法确认，请直接登录后继续完善企业资质");
+        }
+    }
+
+    private void registerRollbackCompensation(long accountId, AtomicBoolean compensationCompleted) {
+        if (!TransactionSynchronizationManager.isSynchronizationActive()) {
+            return;
+        }
+        TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
+            @Override
+            public void afterCompletion(int status) {
+                if (status == STATUS_COMMITTED || compensationCompleted.get()) {
+                    return;
+                }
+                IllegalStateException rollbackFailure = new IllegalStateException(
+                        "Auth transaction rolled back after IAM onboarding");
+                if (!compensateOnboarding(accountId, rollbackFailure, compensationCompleted)) {
+                    LOGGER.error("IAM registration compensation failed after Auth rollback, authUserId={}",
+                            accountId, rollbackFailure);
+                }
+            }
+        });
+    }
+
+    private boolean compensateOnboarding(long accountId, RuntimeException registrationFailure,
+                                         AtomicBoolean compensationCompleted) {
+        if (compensationCompleted.get()) {
+            return true;
+        }
+        try {
+            var response = onboardingClient.compensate(internalToken, accountId);
+            if (response != null && response.successful()) {
+                compensationCompleted.set(true);
+                return true;
+            }
+            {
+                String code = response == null ? "empty-response" : response.code();
+                String message = response == null ? "IAM compensation returned no response" : response.message();
+                registrationFailure.addSuppressed(new IllegalStateException(
+                        "IAM registration compensation failed: code=" + code + ", message=" + message));
+            }
+        } catch (RuntimeException compensationFailure) {
+            registrationFailure.addSuppressed(compensationFailure);
+        }
+        return false;
     }
 }

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

@@ -0,0 +1,71 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.AuthorizationLoader;
+import com.baiyue.auth.client.AuthorizationSnapshot;
+import com.baiyue.auth.config.OverseasJwtProperties;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import jakarta.annotation.Resource;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
+import org.springframework.security.oauth2.jwt.JwtClaimsSet;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
+import org.springframework.security.oauth2.jwt.JwsHeader;
+import org.springframework.stereotype.Service;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+/** 将已经通过国内 HMAC 与 Redis 校验的会话兑换为海外 RS256 短时令牌。 */
+@Service
+@ConditionalOnProperty(name = "baiyue.security.overseas-jwt.enabled", havingValue = "true")
+public class OverseasTokenService {
+    @Resource private AuthAccountRepository accounts;
+    @Resource private AuthorizationLoader authorizationLoader;
+    @Resource private OverseasJwtProperties properties;
+    @Resource @Qualifier("overseasJwtEncoder") private JwtEncoder encoder;
+
+    public OverseasTokenResponse exchange(long authenticatedUserId) {
+        AuthAccount account = accounts.findById(authenticatedUserId);
+        if (account == null || !"ACTIVE".equals(account.getAccountStatus())) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "账号不可用");
+        }
+        AuthorizationSnapshot authorization = authorizationLoader.load(account);
+        return issue(account, authorization);
+    }
+
+    public OverseasTokenResponse issue(AuthAccount account, AuthorizationSnapshot authorization) {
+        Instant issuedAt = Instant.now();
+        Instant expiresAt = issuedAt.plus(properties.accessTokenTtl());
+        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", authorization.getTenantId())
+            .claim("membership_id", authorization.getMembershipId())
+            .claim("app_code", authorization.getAppCode()).claim("client_type", authorization.getClientType())
+            .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(),
+            authorization.getRoles(), authorization.getPermissions());
+    }
+
+    public record OverseasTokenResponse(String tokenType, String accessToken, long expiresIn,
+                                        java.util.Set<String> roles, java.util.Set<String> authorities) {
+        public OverseasTokenResponse {
+            roles = roles == null ? java.util.Set.of() : java.util.Set.copyOf(roles);
+            authorities = authorities == null ? java.util.Set.of() : java.util.Set.copyOf(authorities);
+        }
+    }
+}

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

@@ -1,10 +1,14 @@
 package com.baiyue.auth.service;
 
+import jakarta.annotation.Resource;
+import jakarta.annotation.PostConstruct;
+
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import com.baiyue.common.security.RedisTokenKeys;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.dao.DataAccessException;
 import org.springframework.data.redis.core.StringRedisTemplate;
 import org.springframework.data.redis.core.SetOperations;
@@ -25,24 +29,27 @@ import java.util.List;
  */
 @Component
 public class TokenSessionStore {
-    private final StringRedisTemplate redisTemplate;
-    private final ObjectMapper objectMapper;
-    private final String keyPrefix;
+    @Autowired
+    private StringRedisTemplate redisTemplate;
+    @Resource
+    private ObjectMapper objectMapper;
+    @Value("${baiyue.security.token-key-prefix:baiyue:auth}")
+    private String keyPrefix;
 
-    public TokenSessionStore(StringRedisTemplate redisTemplate, ObjectMapper objectMapper,
-                             @Value("${baiyue.security.token-key-prefix:baiyue:auth}") String keyPrefix) {
-        this.redisTemplate = redisTemplate;
-        this.objectMapper = objectMapper;
-        this.keyPrefix = RedisTokenKeys.normalize(keyPrefix);
+    @PostConstruct
+    void normalizeKeyPrefix() {
+        keyPrefix = RedisTokenKeys.normalize(keyPrefix);
     }
 
-    public void store(String jwtId, Long userId, String rawRefreshToken,
-                      Duration accessTtl, Duration refreshTtl) {
+    public void store(String jwtId, Long userId, Set<String> roles, Set<String> permissions,
+                      String rawRefreshToken, Duration accessTtl, Duration refreshTtl) {
         String accessKey = RedisTokenKeys.access(keyPrefix, jwtId);
         String refreshKey = RedisTokenKeys.refresh(keyPrefix, sha256(rawRefreshToken));
         String userKey = userSessionsKey(userId);
         try {
-            redisTemplate.opsForValue().set(accessKey, userId.toString(), accessTtl);
+            String accessValue = objectMapper.writeValueAsString(
+                    new AccessSession(1, userId, normalized(roles), normalized(permissions)));
+            redisTemplate.opsForValue().set(accessKey, accessValue, accessTtl);
             String refreshValue = objectMapper.writeValueAsString(new RefreshSession(userId, jwtId));
             redisTemplate.opsForValue().set(refreshKey, refreshValue, refreshTtl);
             SetOperations<String, String> sets = redisTemplate.opsForSet();
@@ -54,6 +61,41 @@ public class TokenSessionStore {
         }
     }
 
+    public void storeAccessOnly(String jwtId, Long userId, Set<String> roles,
+                                Set<String> permissions, Duration ttl) {
+        try {
+            String accessKey = RedisTokenKeys.access(keyPrefix, jwtId);
+            String accessValue = objectMapper.writeValueAsString(
+                    new AccessSession(1, userId, normalized(roles), normalized(permissions)));
+            redisTemplate.opsForValue().set(accessKey, accessValue, ttl);
+            redisTemplate.opsForSet().add(userSessionsKey(userId), accessKey);
+            redisTemplate.expire(userSessionsKey(userId), ttl);
+        } catch (Exception exception) {
+            throw unavailable(exception);
+        }
+    }
+
+    public void storeImpersonationTicket(String rawCode, ImpersonationTicket ticket, Duration ttl) {
+        try {
+            redisTemplate.opsForValue().set(keyPrefix + ":impersonation:" + sha256(rawCode),
+                    objectMapper.writeValueAsString(ticket), ttl);
+        } catch (Exception exception) {
+            throw unavailable(exception);
+        }
+    }
+
+    public ImpersonationTicket consumeImpersonationTicket(String rawCode) {
+        try {
+            String value = redisTemplate.opsForValue().getAndDelete(keyPrefix + ":impersonation:" + sha256(rawCode));
+            if (value == null || value.isBlank()) return null;
+            return objectMapper.readValue(value, ImpersonationTicket.class);
+        } catch (DataAccessException exception) {
+            throw unavailable(exception);
+        } catch (Exception exception) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "代登录授权码无效或已过期");
+        }
+    }
+
     public RefreshSession consume(String rawRefreshToken) {
         try {
             String value = redisTemplate.opsForValue().getAndDelete(
@@ -97,7 +139,7 @@ public class TokenSessionStore {
             while (cursor.hasNext()) {
                 String key = cursor.next();
                 String value = redisTemplate.opsForValue().get(key);
-                if ((!refresh && userId.toString().equals(value)) || (refresh && belongsTo(value, userId))) {
+                if ((!refresh && accessBelongsTo(value, userId)) || (refresh && belongsTo(value, userId))) {
                     result.add(key);
                 }
             }
@@ -112,6 +154,16 @@ public class TokenSessionStore {
         catch (Exception ignored) { return false; }
     }
 
+    private boolean accessBelongsTo(String value, Long userId) {
+        if (value == null || value.isBlank()) return false;
+        try { return userId.equals(objectMapper.readValue(value, AccessSession.class).userId()); }
+        catch (Exception ignored) { return false; }
+    }
+
+    private static Set<String> normalized(Set<String> values) {
+        return values == null ? Set.of() : Set.copyOf(values);
+    }
+
     private String userSessionsKey(Long userId) {
         return keyPrefix + ":user-sessions:" + userId;
     }
@@ -131,4 +183,13 @@ public class TokenSessionStore {
     }
 
     public record RefreshSession(Long userId, String accessJwtId) { }
+    public record AccessSession(int version, Long userId, Set<String> roles, Set<String> permissions) {
+        public AccessSession {
+            roles = normalized(roles);
+            permissions = normalized(permissions);
+        }
+    }
+    public record ImpersonationTicket(String ticketId, Long targetAuthUserId, Long tenantId,
+                                      Long membershipId, Long actorUserId, Long actorMembershipId,
+                                      String reason) { }
 }

auth/src/main/resources/application-dev.yml

@@ -0,0 +1,6 @@
+spring:
+  datasource:
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    url: ${AUTH_DB_URL:jdbc:mysql://127.0.0.1:3306/baiyue_auth?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&rewriteBatchedStatements=true}
+    username: ${AUTH_DB_USERNAME:root}
+    password: ${AUTH_DB_PASSWORD:123456}

auth/src/main/resources/application-test.yml

@@ -0,0 +1,15 @@
+spring:
+  cloud:
+    nacos:
+      config:
+        namespace: ${NACOS_NAMESPACE:test}
+        group: ${NACOS_GROUP:BAIYUE}
+        encode: UTF-8
+      discovery:
+        namespace: ${NACOS_NAMESPACE:test}
+        group: ${NACOS_GROUP:BAIYUE}
+  datasource:
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    url: ${AUTH_TEST_DB_URL:jdbc:mysql://${TEST_DB_HOST:8.163.30.128}:${TEST_DB_PORT:3306}/baiyue_auth?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true&rewriteBatchedStatements=true}
+    username: ${AUTH_TEST_DB_USERNAME:${TEST_DB_USERNAME:root}}
+    password: ${AUTH_TEST_DB_PASSWORD:${TEST_DB_PASSWORD}}

auth/src/main/resources/application.yml

@@ -1,6 +1,8 @@
 server:
   port: ${AUTH_PORT:9100}
 spring:
+  profiles:
+    active: ${SPRING_PROFILES_ACTIVE:dev}
   application:
     name: auth-service
   config:
@@ -24,22 +26,26 @@ spring:
         register-enabled: ${NACOS_REGISTER_ENABLED:true}
         group: ${NACOS_GROUP:BAIYUE}
         namespace: ${NACOS_NAMESPACE:public}
-      config.namespace: ${NACOS_NAMESPACE:public}
-  datasource:
-    driver-class-name: com.mysql.cj.jdbc.Driver
-    url: ${AUTH_DB_URL:jdbc:mysql://127.0.0.1:3306/baiyue_auth?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&rewriteBatchedStatements=true}
-    username: ${AUTH_DB_USERNAME:root}
-    password: ${AUTH_DB_PASSWORD:123456}
-
+      config:
+        namespace: ${NACOS_NAMESPACE:public}
+        encode: UTF-8
 baiyue.security:
   jwt-secret: ${JWT_SECRET:change-me-to-at-least-32-bytes-long-before-start}
   internal-service-token: ${INTERNAL_SERVICE_TOKEN:change-me-to-an-internal-token-at-least-32-bytes-long}
   token-key-prefix: ${REDIS_TOKEN_KEY_PREFIX:baiyue:auth}
   issuer: ${JWT_ISSUER:auth-service}
-  access-token-ttl: ${ACCESS_TOKEN_TTL:30m}
+  audience: ${JWT_AUDIENCE:lastleg-api}
+  access-token-ttl: ${ACCESS_TOKEN_TTL:24m}
   refresh-token-ttl: ${REFRESH_TOKEN_TTL:7d}
   max-login-failures: ${MAX_LOGIN_FAILURES:5}
   lock-duration: ${LOGIN_LOCK_DURATION:15m}
+  overseas-jwt:
+    enabled: ${OVERSEAS_JWT_ENABLED:false}
+    issuer: ${OVERSEAS_JWT_ISSUER:auth-service}
+    audience: ${OVERSEAS_JWT_AUDIENCE:lastleg-api}
+    rsa-jwk-set: ${OVERSEAS_JWT_RSA_JWK_SET:}
+    current-kid: ${OVERSEAS_JWT_CURRENT_KID:}
+    access-token-ttl: ${OVERSEAS_ACCESS_TOKEN_TTL:15m}
 
 baiyue.clients:
   iam:

auth/src/main/resources/db/audit-outbox.sql

@@ -0,0 +1,25 @@
+USE baiyue_auth;
+
+-- 可靠审计本地 Outbox；与认证业务表位于同一数据库。
+CREATE TABLE IF NOT EXISTS sys_audit_outbox (
+  event_id VARCHAR(64) NOT NULL COMMENT '审计事件全局唯一ID',
+  event_type VARCHAR(64) NOT NULL COMMENT '审计事件类型',
+  resource_type VARCHAR(64) NOT NULL COMMENT '资源类型',
+  resource_id VARCHAR(128) NULL COMMENT '资源ID',
+  service_name VARCHAR(64) NULL COMMENT '来源服务',
+  payload_json JSON NOT NULL COMMENT '脱敏后的审计事件',
+  status VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT '发送状态：PENDING待发送、SENDING发送中、SENT已发送、DEAD进入死信',
+  attempt_count INT NOT NULL DEFAULT 0 COMMENT '当前周期发送次数',
+  compensation_count INT NOT NULL DEFAULT 0 COMMENT '自动补偿次数',
+  next_retry_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '下一次重试时间',
+  lease_owner VARCHAR(128) NULL COMMENT '当前租约持有者',
+  lease_until DATETIME(3) NULL COMMENT '发送租约截止时间',
+  last_error VARCHAR(1000) NULL COMMENT '最近一次发送错误信息',
+  dead_at DATETIME(3) NULL COMMENT '进入死信时间',
+  sent_at DATETIME(3) NULL COMMENT '成功发送时间',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '记录创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '记录更新时间',
+  PRIMARY KEY (event_id),
+  KEY idx_audit_outbox_publish (status, next_retry_at, lease_until, created_at),
+  KEY idx_audit_outbox_retention (status, sent_at)
+) ENGINE=InnoDB COMMENT='可靠审计事件本地发送箱';

auth/src/main/resources/db/auth-login-identifiers.sql

@@ -0,0 +1,46 @@
+-- Auth 单一登录标识增量：用户名或中国大陆手机号。
+-- 可重复执行；手机号仅从 IAM 当前用户档案回填，无法确认的账号保持 NULL。
+USE baiyue_auth;
+
+DROP PROCEDURE IF EXISTS auth_add_login_phone;
+DELIMITER $$
+CREATE PROCEDURE auth_add_login_phone()
+BEGIN
+  IF NOT EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = 'baiyue_auth' AND table_name = 'auth_account' AND column_name = 'phone') THEN
+    ALTER TABLE auth_account ADD COLUMN phone VARCHAR(32) NULL COMMENT '全局唯一中国大陆登录手机号' AFTER username;
+  END IF;
+END$$
+DELIMITER ;
+CALL auth_add_login_phone();
+DROP PROCEDURE auth_add_login_phone;
+
+DROP PROCEDURE IF EXISTS auth_backfill_login_phone;
+DELIMITER $$
+CREATE PROCEDURE auth_backfill_login_phone()
+BEGIN
+  UPDATE auth_account
+     SET phone = NULL
+   WHERE phone IS NOT NULL AND phone NOT REGEXP '^1[3-9][0-9]{9}$';
+  UPDATE auth_account account
+  JOIN baiyue_iam.iam_user user ON user.auth_user_id = account.id AND user.deleted = 0
+  JOIN (
+    SELECT phone
+      FROM baiyue_iam.iam_user
+     WHERE deleted = 0 AND phone REGEXP '^1[3-9][0-9]{9}$'
+     GROUP BY phone
+    HAVING COUNT(DISTINCT auth_user_id) = 1
+  ) unique_phone ON unique_phone.phone = user.phone
+     SET account.phone = user.phone
+   WHERE account.phone IS NULL AND user.phone REGEXP '^1[3-9][0-9]{9}$';
+  IF NOT EXISTS (
+      SELECT 1 FROM information_schema.statistics
+       WHERE table_schema = 'baiyue_auth' AND table_name = 'auth_account'
+         AND index_name = 'uk_auth_account_phone') THEN
+    ALTER TABLE auth_account ADD UNIQUE KEY uk_auth_account_phone (phone);
+  END IF;
+END$$
+DELIMITER ;
+CALL auth_backfill_login_phone();
+DROP PROCEDURE auth_backfill_login_phone;

auth/src/main/resources/db/auth.sql

@@ -6,22 +6,25 @@ USE baiyue_auth;
 CREATE TABLE IF NOT EXISTS auth_account (
   id BIGINT NOT NULL COMMENT '统一登录账号ID（雪花ID）',
   username VARCHAR(64) NOT NULL COMMENT '全局唯一登录名',
+  phone VARCHAR(32) DEFAULT NULL COMMENT '全局唯一中国大陆登录手机号',
   password_hash VARCHAR(255) NOT NULL COMMENT 'BCrypt密码哈希，禁止保存明文密码',
   display_name VARCHAR(64) NOT NULL COMMENT '登录后展示名称',
-  account_status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE' COMMENT '账号状态：ACTIVE、DISABLED、LOCKED',
+  account_status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE' COMMENT '账号状态：ACTIVE正常、DISABLED停用、LOCKED锁定',
   failed_login_count INT NOT NULL DEFAULT 0 COMMENT '连续登录失败次数',
   locked_until DATETIME(3) DEFAULT NULL COMMENT '临时锁定截止时间',
   token_version INT NOT NULL DEFAULT 1 COMMENT '令牌版本，递增后可使历史令牌失效',
-  default_tenant_id BIGINT NOT NULL COMMENT '默认业务租户ID',
-  operator_tenant_id BIGINT NOT NULL COMMENT '操作主体租户ID，平台端与商户端身份隔离',
-  default_membership_id BIGINT DEFAULT NULL COMMENT '默认租户成员关系ID',
-  default_app_code VARCHAR(20) NOT NULL COMMENT '默认应用端：MERCHANT或PLATFORM',
+  password_change_required TINYINT NOT NULL DEFAULT 0 COMMENT '管理员重置后是否强制下次登录改密',
+  default_tenant_id BIGINT NOT NULL COMMENT '默认业务作用域ID：0为平台，正数为客户ID',
+  operator_tenant_id BIGINT NOT NULL COMMENT '操作主体作用域ID：0为平台，正数为客户ID，用于平台端与客户端身份隔离',
+  default_membership_id BIGINT DEFAULT NULL COMMENT '默认客户成员关系ID；平台账号可为空',
+  default_app_code VARCHAR(20) NOT NULL COMMENT '默认应用端：MERCHANT企业客户端、PLATFORM平台后台',
   deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除标记',
   last_login_at DATETIME(3) DEFAULT NULL COMMENT '最近一次成功登录时间',
   created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
   updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
   PRIMARY KEY (id),
   UNIQUE KEY uk_auth_account_username (username),
+  UNIQUE KEY uk_auth_account_phone (phone),
   KEY idx_auth_account_status (account_status, locked_until)
 ) ENGINE=InnoDB COMMENT='统一登录账号表：保存平台端和商户端共用的认证凭据及账号安全状态';
 
@@ -29,9 +32,9 @@ CREATE TABLE IF NOT EXISTS auth_refresh_token (
   id BIGINT NOT NULL COMMENT '刷新令牌记录ID（雪花ID）',
   token_hash CHAR(64) NOT NULL COMMENT '刷新令牌SHA-256摘要，不保存令牌明文',
   user_id BIGINT NOT NULL COMMENT '认证账号ID',
-  tenant_id BIGINT NOT NULL COMMENT '令牌当前业务租户ID',
-  operator_tenant_id BIGINT NOT NULL COMMENT '令牌操作主体租户ID',
-  app_code VARCHAR(20) NOT NULL COMMENT '令牌所属应用端',
+  tenant_id BIGINT NOT NULL COMMENT '令牌当前业务作用域ID：0为平台，正数为客户ID',
+  operator_tenant_id BIGINT NOT NULL COMMENT '令牌操作主体作用域ID：0为平台，正数为客户ID',
+  app_code VARCHAR(20) NOT NULL COMMENT '令牌所属应用端：MERCHANT企业客户端、PLATFORM平台后台',
   expires_at DATETIME(3) NOT NULL COMMENT '到期时间',
   revoked_at DATETIME(3) DEFAULT NULL COMMENT '吊销时间，非空表示不可继续使用',
   created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '签发时间',
@@ -39,6 +42,6 @@ CREATE TABLE IF NOT EXISTS auth_refresh_token (
   UNIQUE KEY uk_auth_refresh_hash (token_hash),
   KEY idx_auth_refresh_user (user_id, revoked_at, expires_at),
   KEY idx_auth_refresh_expire (expires_at, revoked_at)
-) ENGINE=InnoDB COMMENT='刷新令牌表：保存令牌摘要、租户上下文、有效期和轮换/吊销状态';
+) ENGINE=InnoDB COMMENT='刷新令牌表：保存令牌摘要、平台或客户作用域、有效期和轮换/吊销状态';
 
 -- 初始管理员密码必须由部署脚本生成 BCrypt 哈希后显式写入，仓库内禁止提供默认密码。

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;
@@ -6,19 +6,18 @@ SET NAMES utf8mb4;
 
 INSERT INTO auth_account (
   id, username, password_hash, display_name, account_status,
-  failed_login_count, token_version, default_tenant_id,
+  failed_login_count, token_version, password_change_required, default_tenant_id,
   operator_tenant_id, default_membership_id, default_app_code, deleted
 ) VALUES
   (1000001, 'platform_admin', '$2a$12$AMZJjd88leYPLI9uKvjZiew2CTQXI32BXoHFX.FrCi28/IeZ7mZ96',
-   '平台管理员', 'ACTIVE', 0, 1, 0, 0, 3000001, 'PLATFORM', 0),
-  (1000002, 'merchant_admin', '$2a$12$AMZJjd88leYPLI9uKvjZiew2CTQXI32BXoHFX.FrCi28/IeZ7mZ96',
-   '一期演示企业管理员', 'ACTIVE', 0, 1, 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),
   account_status = 'ACTIVE',
   failed_login_count = 0,
   locked_until = NULL,
+  password_change_required = VALUES(password_change_required),
   default_tenant_id = VALUES(default_tenant_id),
   operator_tenant_id = VALUES(operator_tenant_id),
   default_membership_id = VALUES(default_membership_id),

auth/src/main/resources/db/phase1-customer-account-operations.sql

@@ -0,0 +1,11 @@
+USE baiyue_auth;
+
+SET @add_password_change_required = IF(
+  EXISTS(SELECT 1 FROM information_schema.columns
+         WHERE table_schema = DATABASE() AND table_name = 'auth_account'
+           AND column_name = 'password_change_required'),
+  'SELECT 1',
+  'ALTER TABLE auth_account ADD COLUMN password_change_required TINYINT NOT NULL DEFAULT 0 COMMENT ''管理员重置后是否强制下次登录改密'' AFTER token_version');
+PREPARE phase1_customer_account_sql FROM @add_password_change_required;
+EXECUTE phase1_customer_account_sql;
+DEALLOCATE PREPARE phase1_customer_account_sql;

auth/src/test/java/com/baiyue/auth/client/AuthorizationLoaderTest.java

@@ -0,0 +1,77 @@
+package com.baiyue.auth.client;
+
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class AuthorizationLoaderTest {
+    private static final String INTERNAL_TOKEN = "test-internal-service-token-at-least-32-bytes";
+
+    @Mock private IamAuthorizationClient client;
+    @InjectMocks private AuthorizationLoader loader;
+
+    @BeforeEach
+    void setUp() {
+        ReflectionTestUtils.setField(loader, "internalToken", INTERNAL_TOKEN);
+        loader.validateConfiguration();
+    }
+
+    @Test
+    void returnsSnapshotWhenEchoedIdentityMatchesAccount() {
+        AuthAccount account = account();
+        AuthorizationSnapshot snapshot = snapshot(42L, 10001L, 9L, "MERCHANT");
+        when(client.load(eq(INTERNAL_TOKEN), any())).thenReturn(ApiResponse.success(snapshot));
+
+        assertSame(snapshot, loader.load(account));
+    }
+
+    @Test
+    void rejectsEveryMismatchedEchoedIdentityField() {
+        AuthAccount account = account();
+
+        assertIdentityMismatch(account, snapshot(43L, 10001L, 9L, "MERCHANT"));
+        assertIdentityMismatch(account, snapshot(42L, 10002L, 9L, "MERCHANT"));
+        assertIdentityMismatch(account, snapshot(42L, 10001L, 10L, "MERCHANT"));
+        assertIdentityMismatch(account, snapshot(42L, 10001L, 9L, "PLATFORM"));
+    }
+
+    private void assertIdentityMismatch(AuthAccount account, AuthorizationSnapshot snapshot) {
+        when(client.load(eq(INTERNAL_TOKEN), any())).thenReturn(ApiResponse.success(snapshot));
+
+        BizException exception = assertThrows(BizException.class, () -> loader.load(account));
+
+        assertEquals(ResultCode.FORBIDDEN, exception.getResultCode());
+    }
+
+    private AuthAccount account() {
+        AuthAccount account = new AuthAccount();
+        account.setId(42L);
+        account.setDefaultTenantId(10001L);
+        account.setDefaultMembershipId(9L);
+        account.setDefaultAppCode("MERCHANT");
+        return account;
+    }
+
+    private AuthorizationSnapshot snapshot(Long userId, Long tenantId, Long membershipId, String appCode) {
+        return new AuthorizationSnapshot(userId, tenantId, membershipId, appCode, appCode,
+                Set.of("MERCHANT_ADMIN"), Set.of("merchant:profile:view"), 1L);
+    }
+}

auth/src/test/java/com/baiyue/auth/config/AuthSecurityConfigTest.java

@@ -0,0 +1,15 @@
+package com.baiyue.auth.config;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class AuthSecurityConfigTest {
+    @Test
+    void permitsAnonymousImpersonationCodeExchange() {
+        assertTrue(Arrays.asList(AuthSecurityConfig.PUBLIC_AUTH_ENDPOINTS)
+            .contains("/api/auth/impersonations/exchange"));
+    }
+}

auth/src/test/java/com/baiyue/auth/config/AuthTokenTtlConfigurationContractTest.java

@@ -0,0 +1,23 @@
+package com.baiyue.auth.config;
+
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class AuthTokenTtlConfigurationContractTest {
+    @Test
+    void cnNacosConfigurationKeepsShortAccessAndSevenDayRefreshTokens() throws Exception {
+        String configuration = Files.readString(
+            Path.of("..", "config", "nacos", "cn", "auth-service.yml"), StandardCharsets.UTF_8);
+
+        assertThat(configuration)
+            .contains("access-token-ttl: ${ACCESS_TOKEN_TTL:24m}")
+            .contains("refresh-token-ttl: ${REFRESH_TOKEN_TTL:7d}")
+            .contains("access-token-ttl: ${OVERSEAS_ACCESS_TOKEN_TTL:15m}")
+            .doesNotContain("access-token-ttl: ${ACCESS_TOKEN_TTL:7d}");
+    }
+}

auth/src/test/java/com/baiyue/auth/config/DualTrackJwtConfigurationTest.java

@@ -0,0 +1,29 @@
+package com.baiyue.auth.config;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class DualTrackJwtConfigurationTest {
+    private final ApplicationContextRunner runner = new ApplicationContextRunner()
+        .withConfiguration(AutoConfigurations.of(DomesticJwtConfiguration.class, OverseasJwtConfiguration.class))
+        .withBean(AuthSecurityProperties.class, () -> new AuthSecurityProperties(
+            "domestic-secret-at-least-32-bytes-long", "auth-service", "lastleg-api",
+            java.time.Duration.ofMinutes(24), java.time.Duration.ofDays(7), 5,
+            java.time.Duration.ofMinutes(15)))
+        .withPropertyValues(
+            "baiyue.security.overseas-jwt.enabled=false");
+
+    @Test
+    void startsDomesticEncoderWithoutRsaConfiguration() {
+        runner.run(context -> {
+            assertThat(context).hasNotFailed();
+            assertThat(context).hasBean("jwtEncoder");
+            assertThat(context).doesNotHaveBean("overseasJwtEncoder");
+            assertThat(context).hasSingleBean(JwtEncoder.class);
+        });
+    }
+}

auth/src/test/java/com/baiyue/auth/controller/InternalAccountControllerConfigurationTest.java

@@ -0,0 +1,21 @@
+package com.baiyue.auth.controller;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class InternalAccountControllerConfigurationTest {
+    @Test
+    void rejectsEmptyAndShortInternalServiceTokens() {
+        assertTokenRejected(null);
+        assertTokenRejected("");
+        assertTokenRejected("short-token");
+    }
+
+    private void assertTokenRejected(String token) {
+        InternalAccountController controller = new InternalAccountController();
+        ReflectionTestUtils.setField(controller, "configuredToken", token);
+        assertThrows(IllegalStateException.class, controller::init);
+    }
+}

auth/src/test/java/com/baiyue/auth/controller/JwksControllerTest.java

@@ -0,0 +1,40 @@
+package com.baiyue.auth.controller;
+
+import com.baiyue.auth.config.OverseasJwtProperties;
+import com.nimbusds.jose.JWSAlgorithm;
+import com.nimbusds.jose.jwk.JWKSet;
+import com.nimbusds.jose.jwk.KeyUse;
+import com.nimbusds.jose.jwk.RSAKey;
+import com.nimbusds.jose.util.Base64URL;
+import org.junit.jupiter.api.Test;
+
+import java.math.BigInteger;
+import java.time.Duration;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class JwksControllerTest {
+    @Test
+    void publishesOnlyPublicKeyMaterialForCurrentAndPreviousKeys() throws Exception {
+        RSAKey current = key("current", true);
+        RSAKey previous = key("previous", false);
+        String json = new JWKSet(List.of(current, previous)).toString(false);
+        var properties = new OverseasJwtProperties(true, "auth-service", "lastleg-api", json,
+            "current", Duration.ofMinutes(15));
+
+        var body = new JwksController(properties).jwks().getBody();
+        String published = new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsString(body);
+
+        assertThat(published).contains("current", "previous", "\"n\"", "\"e\"")
+            .doesNotContain("\"d\"", "\"p\"", "\"q\"", "\"dp\"", "\"dq\"", "\"qi\"");
+    }
+
+    private RSAKey key(String kid, boolean privatePart) {
+        RSAKey.Builder builder = new RSAKey.Builder(
+            Base64URL.encode(BigInteger.valueOf(3233)), Base64URL.encode(BigInteger.valueOf(17)))
+            .keyID(kid).keyUse(KeyUse.SIGNATURE).algorithm(JWSAlgorithm.RS256);
+        if (privatePart) builder.privateExponent(Base64URL.encode(BigInteger.valueOf(2753)));
+        return builder.build();
+    }
+}

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

@@ -0,0 +1,32 @@
+package com.baiyue.auth.repository;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.core.io.ClassPathResource;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class AuthLoginIdentifiersSqlContractTest {
+    @Test
+    void backfillsOnlyUniquelyOwnedPhonesAndKeepsDuplicateLegacyPhonesUnbound() throws Exception {
+        assertSafeBackfill(new ClassPathResource("db/auth-login-identifiers.sql")
+            .getContentAsString(StandardCharsets.UTF_8));
+        assertSafeBackfill(Files.readString(unifiedSql(), StandardCharsets.UTF_8));
+    }
+
+    private static void assertSafeBackfill(String sql) {
+        assertThat(sql)
+            .contains("phone NOT REGEXP '^1[3-9][0-9]{9}$'")
+            .contains("HAVING COUNT(DISTINCT auth_user_id) = 1")
+            .contains("ADD UNIQUE KEY uk_auth_account_phone (phone)")
+            .doesNotContain("IAM 存在重复手机号，禁止建立 Auth 唯一登录索引");
+    }
+
+    private static Path unifiedSql() {
+        Path path = Path.of("deploy", "sql", "头程数据库统一增量-MySQL8.sql");
+        return Files.exists(path) ? path : Path.of("..", "deploy", "sql", "头程数据库统一增量-MySQL8.sql");
+    }
+}

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

@@ -0,0 +1,35 @@
+package com.baiyue.auth.repository;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.core.io.ClassPathResource;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class InitialAccountSeedSqlContractTest {
+    @Test
+    void initializesOnlyThePlatformAdministratorAccount() throws Exception {
+        assertAccountSeed(new ClassPathResource("db/phase1-admin-accounts.sql")
+            .getContentAsString(StandardCharsets.UTF_8));
+        assertAccountSeed(Files.readString(unifiedSql(), StandardCharsets.UTF_8));
+    }
+
+    private static void assertAccountSeed(String sql) {
+        assertThat(sql)
+            .contains("(1000001, 'platform_admin'")
+            .contains("'平台系统管理员', 'ACTIVE'")
+            .contains("password_change_required")
+            .doesNotContain("merchant_admin")
+            .doesNotContain("IT_TEST")
+            .doesNotContain("(1000002, 'merchant_admin'")
+            .doesNotContain("一期演示企业管理员");
+    }
+
+    private static Path unifiedSql() {
+        Path path = Path.of("deploy", "sql", "头程数据库统一增量-MySQL8.sql");
+        return Files.exists(path) ? path : Path.of("..", "deploy", "sql", "头程数据库统一增量-MySQL8.sql");
+    }
+}

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

@@ -0,0 +1,48 @@
+package com.baiyue.auth.repository;
+
+import com.baiyue.auth.dto.AccountManagementDtos.ChangeLoginIdentifiersRequest;
+import com.baiyue.auth.dto.MerchantRegisterRequest;
+import jakarta.validation.Validation;
+import org.junit.jupiter.api.Test;
+import org.springframework.core.io.ClassPathResource;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class LoginIdentifierContractTest {
+
+    @Test
+    void registrationExposesAnAccountPhoneInsteadOfALegalPersonPhoneAlias() {
+        var componentNames = Arrays.stream(MerchantRegisterRequest.class.getRecordComponents())
+                .map(component -> component.getName())
+                .toList();
+
+        assertThat(componentNames).contains("phone").doesNotContain("legalPhone");
+    }
+
+    @Test
+    void mainlandMobileRuleRejectsPlaceholderNumbersAcrossJavaAndSql() throws Exception {
+        try (var factory = Validation.buildDefaultValidatorFactory()) {
+            var validator = factory.getValidator();
+            var invalidRegistration = new MerchantRegisterRequest(
+                    "merchant.user", "Password1", "测试用户", "测试企业", "张三",
+                    "11111111111", null, "CN", null);
+            var validChange = new ChangeLoginIdentifiersRequest(
+                    "merchant.user", "13800138000", "Password1");
+            var invalidChange = new ChangeLoginIdentifiersRequest(
+                    "merchant.user", "11111111111", "Password1");
+
+            assertThat(validator.validate(invalidRegistration)).isNotEmpty();
+            assertThat(validator.validate(validChange)).isEmpty();
+            assertThat(validator.validate(invalidChange)).isNotEmpty();
+        }
+
+        String sql = new ClassPathResource("db/auth-login-identifiers.sql")
+                .getContentAsString(StandardCharsets.UTF_8);
+        assertThat(sql)
+                .contains("REGEXP '^1[3-9][0-9]{9}$'")
+                .doesNotContain("REGEXP '^1[0-9]{10}$'");
+    }
+}

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

@@ -1,35 +1,50 @@
 package com.baiyue.auth.service;
 
 import com.baiyue.auth.dto.AccountManagementDtos.ChangePasswordRequest;
+import com.baiyue.auth.dto.AccountManagementDtos.ForcedPasswordChangeRequest;
+import com.baiyue.auth.dto.AccountManagementDtos.CreateAccountRequest;
+import com.baiyue.auth.dto.AccountManagementDtos.UpdateAccountProfileRequest;
+import com.baiyue.auth.dto.AccountManagementDtos.UpdateAccountPhoneRequest;
 import com.baiyue.auth.dto.AccountManagementDtos.UpdateAccountStatusRequest;
+import com.baiyue.auth.dto.AccountManagementDtos.UpdateAccountScopeRequest;
+import com.baiyue.auth.dto.AccountManagementDtos.ChangeLoginIdentifiersRequest;
 import com.baiyue.auth.entity.AuthAccount;
 import com.baiyue.auth.repository.AuthAccountRepository;
 import com.baiyue.common.core.exception.BizException;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
-import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+import jakarta.annotation.Resource;
 
 import static org.junit.jupiter.api.Assertions.*;
 import static org.mockito.Mockito.*;
+import java.time.LocalDateTime;
+import java.util.Set;
+import java.util.List;
 
+@DisplayName("账号管理服务")
+@SpringJUnitConfig(classes = {AccountManagementService.class, AccountManagementServiceTest.TestConfig.class})
 class AccountManagementServiceTest {
-    private final AuthAccountRepository repository = mock(AuthAccountRepository.class);
-    private final TokenSessionStore sessions = mock(TokenSessionStore.class);
-    private final BCryptPasswordEncoder encoder = new BCryptPasswordEncoder(4);
-    private final AccountManagementService service = new AccountManagementService();
+    @MockBean private AuthAccountRepository repository;
+    @MockBean private TokenSessionStore sessions;
+    @Resource private PasswordEncoder encoder;
+    @Resource private AccountManagementService service;
     private AuthAccount account;
 
     @BeforeEach void setUp() {
-        ReflectionTestUtils.setField(service, "repository", repository);
-        ReflectionTestUtils.setField(service, "passwordEncoder", encoder);
-        ReflectionTestUtils.setField(service, "tokenSessionStore", sessions);
         account = new AuthAccount(); account.setId(10L); account.setPasswordHash(encoder.encode("OldPass1"));
         account.setTokenVersion(2); account.setAccountStatus("ACTIVE");
         when(repository.findById(10L)).thenReturn(account);
     }
 
-    @Test void 修改密码校验旧密码并撤销全部会话() {
+    @Test void changePasswordValidatesCurrentPasswordAndRevokesAllSessions() {
         service.changePassword(10L, new ChangePasswordRequest("OldPass1", "NewPass2"));
         assertTrue(encoder.matches("NewPass2", account.getPasswordHash()));
         assertEquals(3, account.getTokenVersion());
@@ -37,16 +52,206 @@ class AccountManagementServiceTest {
         verify(sessions).revokeAll(10L);
     }
 
-    @Test void 原密码错误不得写入() {
+    @Test void changePasswordDoesNotPersistWhenCurrentPasswordIsInvalid() {
         assertThrows(BizException.class,
                 () -> service.changePassword(10L, new ChangePasswordRequest("WrongPass1", "NewPass2")));
         verify(repository, never()).save(any());
         verify(sessions, never()).revokeAll(any());
     }
 
-    @Test void 停用账号撤销全部会话() {
+    @Test void forcedPasswordChangeRequiresResetFlagAndClearsIt() {
+        account.setPasswordChangeRequired(true);
+
+        service.forcedChangePassword(10L, new ForcedPasswordChangeRequest("NewPass2"));
+
+        assertTrue(encoder.matches("NewPass2", account.getPasswordHash()));
+        assertFalse(account.getPasswordChangeRequired());
+        verify(repository).save(account);
+        verify(sessions).revokeAll(10L);
+    }
+
+    @Test void normalPasswordChangeIsRejectedUntilForcedChangeIsCompleted() {
+        account.setPasswordChangeRequired(true);
+
+        assertThrows(BizException.class,
+                () -> service.changePassword(10L, new ChangePasswordRequest("OldPass1", "NewPass2")));
+        verify(repository, never()).save(any());
+    }
+
+    @Test void disableAccountRevokesAllSessions() {
         service.updateStatus(10L, new UpdateAccountStatusRequest("DISABLED"));
         assertEquals("DISABLED", account.getAccountStatus());
         verify(sessions).revokeAll(10L);
     }
+
+    @Test void createPlatformAccountPersistsPlatformAppCodeAndPasswordHashOnly() {
+        when(repository.findById(20L)).thenReturn(null);
+        when(repository.existsByUsername("platform.user")).thenReturn(false);
+
+        var result = service.create(new CreateAccountRequest(20L, "platform.user", "Password1",
+                "平台用户", 0L, 30L, "PLATFORM"));
+
+        assertEquals("platform.user", result.username());
+        var captor = org.mockito.ArgumentCaptor.forClass(AuthAccount.class);
+        verify(repository).insert(captor.capture());
+        assertEquals("PLATFORM", captor.getValue().getDefaultAppCode());
+        assertTrue(encoder.matches("Password1", captor.getValue().getPasswordHash()));
+        assertNotEquals("Password1", captor.getValue().getPasswordHash());
+    }
+
+    @Test void usernameAvailabilityUsesTheAuthAccountRepositoryAsTheFactSource() {
+        when(repository.existsByUsername("13800138000")).thenReturn(true);
+
+        assertFalse(service.usernameAvailable("13800138000"));
+        assertTrue(service.usernameAvailable("13900139000"));
+    }
+
+    @Test void createDisabledAccountAndSummaryExposeLastLoginAndScope() {
+        when(repository.findById(20L)).thenReturn(null);
+        when(repository.existsByUsername("merchant.user")).thenReturn(false);
+
+        var created = service.create(new CreateAccountRequest(20L, "merchant.user", "Password1",
+                "企业用户", 10001L, 30L, "MERCHANT", "DISABLED"));
+        var captor = org.mockito.ArgumentCaptor.forClass(AuthAccount.class);
+        verify(repository).insert(captor.capture());
+        AuthAccount stored = captor.getValue();
+        stored.setLastLoginAt(LocalDateTime.of(2026, 6, 1, 10, 30));
+        when(repository.findById(20L)).thenReturn(stored);
+
+        var summary = service.summary(20L);
+        assertEquals("DISABLED", created.status());
+        assertEquals(10001L, summary.tenantId());
+        assertEquals(30L, summary.membershipId());
+        assertEquals(LocalDateTime.of(2026, 6, 1, 10, 30), summary.lastLoginAt());
+    }
+
+    @Test void updateScopeChangesTenantAndRevokesExistingSessions() {
+        account.setDefaultTenantId(10001L); account.setOperatorTenantId(10001L);
+        account.setDefaultMembershipId(30L); account.setDefaultAppCode("MERCHANT");
+
+        service.updateScope(10L, new UpdateAccountScopeRequest(10002L, 30L, "MERCHANT"));
+
+        assertEquals(10002L, account.getDefaultTenantId());
+        assertEquals(10002L, account.getOperatorTenantId());
+        verify(repository).save(account);
+        verify(sessions).revokeAll(10L);
+    }
+
+    @Test void createAccountRetriesIdempotentlyForSameAccountAndOwner() {
+        account.setUsername("platform.user"); account.setDisplayName("平台用户");
+        account.setDefaultTenantId(0L); account.setOperatorTenantId(0L);
+        account.setDefaultMembershipId(30L); account.setDefaultAppCode("PLATFORM"); account.setDeleted(0);
+
+        var result = service.create(new CreateAccountRequest(10L, "platform.user", "Password1",
+                "平台用户", 0L, 30L, "PLATFORM"));
+
+        assertEquals(10L, result.accountId());
+        verify(repository, never()).insert(any());
+    }
+
+    @Test void synchronizeDisplayNameRevokesExistingSessions() {
+        account.setDisplayName("旧名称");
+
+        service.updateProfile(10L, new UpdateAccountProfileRequest("新名称"));
+
+        assertEquals("新名称", account.getDisplayName());
+        verify(repository).save(account);
+        verify(sessions).revokeAll(10L);
+    }
+
+    @Test void changeLoginIdentifiersRequiresCurrentPasswordAndRevokesSessions() {
+        account.setUsername("old.user");
+        account.setPhone("13800138000");
+        when(repository.existsByUsernameForOtherAccount("new.user", 10L)).thenReturn(false);
+        when(repository.existsByPhoneForOtherAccount("13900139000", 10L)).thenReturn(false);
+
+        var result = service.changeLoginIdentifiers(10L,
+                new ChangeLoginIdentifiersRequest("new.user", "13900139000", "OldPass1"));
+
+        assertEquals("new.user", result.username());
+        assertEquals("13900139000", result.phone());
+        assertEquals(3, account.getTokenVersion());
+        verify(sessions).revokeAll(10L);
+    }
+
+    @Test void managedPhoneChangeOrRemovalRevokesOnlyThatAccountsSessions() {
+        account.setPhone("13800138000");
+
+        service.updatePhone(10L, new UpdateAccountPhoneRequest(null));
+
+        assertEquals(null, account.getPhone());
+        assertEquals(3, account.getTokenVersion());
+        verify(repository).save(account);
+        verify(sessions).revokeAll(10L);
+    }
+
+    @Test void duplicatePhoneDoesNotChangeLoginIdentifiers() {
+        account.setUsername("old.user");
+        account.setPhone("13800138000");
+        when(repository.existsByUsernameForOtherAccount("new.user", 10L)).thenReturn(false);
+        when(repository.existsByPhoneForOtherAccount("13900139000", 10L)).thenReturn(true);
+
+        assertThrows(BizException.class, () -> service.changeLoginIdentifiers(10L,
+                new ChangeLoginIdentifiersRequest("new.user", "13900139000", "OldPass1")));
+        verify(repository, never()).save(any());
+        verify(sessions, never()).revokeAll(any());
+    }
+
+    @Test void rbacChangeRevokesAccessAndRefreshSessionsAndBumpsTokenVersions() {
+        AuthAccount second = new AuthAccount();
+        second.setId(11L); second.setTokenVersion(7); second.setAccountStatus("ACTIVE");
+        when(repository.findById(11L)).thenReturn(second);
+
+        service.revokeSessions(Set.of(10L, 11L));
+
+        assertEquals(3, account.getTokenVersion());
+        assertEquals(8, second.getTokenVersion());
+        verify(repository).save(account);
+        verify(repository).save(second);
+        verify(sessions).revokeAll(10L);
+        verify(sessions).revokeAll(11L);
+    }
+
+    @Test void archiveTenantDisablesEveryMerchantAccountAndRevokesSessions() {
+        AuthAccount owner = merchantAccount(20L, 10001L, "ACTIVE", 3);
+        AuthAccount member = merchantAccount(21L, 10001L, "DISABLED", null);
+        when(repository.findMerchantByTenant(10001L)).thenReturn(List.of(owner, member));
+
+        service.archiveTenant(10001L);
+
+        assertEquals("DISABLED", owner.getAccountStatus());
+        assertEquals(4, owner.getTokenVersion());
+        assertEquals("DISABLED", member.getAccountStatus());
+        assertEquals(1, member.getTokenVersion());
+        verify(repository).save(owner);
+        verify(repository).save(member);
+        verify(sessions).revokeAll(20L);
+        verify(sessions).revokeAll(21L);
+    }
+
+    @Test void archiveTenantIsSuccessfulWhenCustomerHasNoAccounts() {
+        when(repository.findMerchantByTenant(10001L)).thenReturn(List.of());
+
+        service.archiveTenant(10001L);
+
+        verify(repository, never()).save(any());
+        verify(sessions, never()).revokeAll(any());
+    }
+
+    private AuthAccount merchantAccount(long id, long tenantId, String status, Integer tokenVersion) {
+        AuthAccount value = new AuthAccount();
+        value.setId(id);
+        value.setDefaultTenantId(tenantId);
+        value.setDefaultAppCode("MERCHANT");
+        value.setAccountStatus(status);
+        value.setTokenVersion(tokenVersion);
+        return value;
+    }
+    @Configuration
+    static class TestConfig {
+        @Bean
+        PasswordEncoder passwordEncoder() {
+            return new BCryptPasswordEncoder(4);
+        }
+    }
 }

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

@@ -0,0 +1,252 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.AuthorizationLoader;
+import com.baiyue.auth.client.AuthorizationSnapshot;
+import com.baiyue.auth.config.AuthSecurityProperties;
+import com.baiyue.auth.dto.LoginRequest;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
+import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+import jakarta.annotation.Resource;
+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;
+
+@SpringJUnitConfig(classes = {AuthService.class, AuthServiceSmallJwtTest.TestConfig.class})
+class AuthServiceSmallJwtTest {
+    @MockBean private AuthAccountRepository repository;
+    @MockBean private PasswordEncoder passwordEncoder;
+    @MockBean private JwtEncoder jwtEncoder;
+    @MockBean private AuthorizationLoader authorizationLoader;
+    @MockBean private TokenSessionStore tokenSessionStore;
+    @MockBean private OverseasTokenService overseasTokenService;
+    @Resource private AuthService service;
+
+    @Configuration(proxyBeanMethods = false)
+    static class TestConfig {
+        @Bean
+        AuthSecurityProperties properties() {
+            return new AuthSecurityProperties("unused", "auth-service", "lastleg-api",
+                    Duration.ofMinutes(30),
+                    Duration.ofDays(7), 5, Duration.ofMinutes(10));
+        }
+    }
+
+    @Test
+    void signsCrossRegionClaimsAndStoresSession() {
+        AuthAccount account = new AuthAccount();
+        account.setId(42L);
+        account.setUsername("operator");
+        account.setPasswordHash("hash");
+        account.setAccountStatus("ACTIVE");
+        account.setDefaultTenantId(0L);
+        account.setOperatorTenantId(0L);
+        account.setDefaultMembershipId(84L);
+        account.setDefaultAppCode("PLATFORM");
+        account.setTokenVersion(1);
+        AuthorizationSnapshot snapshot = new AuthorizationSnapshot(42L, 0L, 84L, "PLATFORM",
+                "WEB", Set.of("OVERSEAS_WAREHOUSE_PDA_OPERATOR"), Set.of("platform:order:list"), 1L, 900L);
+        Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
+
+        when(repository.findByUsername("operator")).thenReturn(account);
+        when(passwordEncoder.matches("secret", "hash")).thenReturn(true);
+        when(authorizationLoader.load(account)).thenReturn(snapshot);
+        when(jwtEncoder.encode(any())).thenReturn(encoded);
+        when(encoded.getTokenValue()).thenReturn("small-token");
+        when(overseasTokenService.issue(account, snapshot)).thenReturn(
+                new OverseasTokenService.OverseasTokenResponse("Bearer", "overseas-token", 900,
+                    snapshot.getRoles(), snapshot.getPermissions()));
+
+        var response = service.login(new LoginRequest("operator", "secret"));
+
+        ArgumentCaptor<JwtEncoderParameters> jwt = ArgumentCaptor.forClass(JwtEncoderParameters.class);
+        verify(jwtEncoder).encode(jwt.capture());
+        assertThat(jwt.getValue().getClaims().getClaims())
+                .containsEntry("user_id", 42L)
+                .containsEntry("userId", 42L)
+                .containsEntry("tenantId", 0L)
+                .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("OVERSEAS_WAREHOUSE_PDA_OPERATOR")),
+                org.mockito.ArgumentMatchers.eq(Set.of("platform:order:list")), any(),
+                org.mockito.ArgumentMatchers.eq(Duration.ofMinutes(30)),
+                org.mockito.ArgumentMatchers.eq(Duration.ofDays(7)));
+        verify(overseasTokenService).issue(account, snapshot);
+        assertThat(response.overseasAccessToken()).isEqualTo("overseas-token");
+        assertThat(response.overseasExpiresIn()).isEqualTo(900);
+        assertThat(response.roles()).containsExactly("OVERSEAS_WAREHOUSE_PDA_OPERATOR");
+        assertThat(response.authorities()).containsExactly("platform:order:list");
+    }
+
+    @Test
+    void mainlandPhoneIsResolvedAsTheSinglePhoneLoginIdentifier() {
+        AuthAccount account = new AuthAccount();
+        account.setId(42L);
+        account.setUsername("operator");
+        account.setPhone("13800138000");
+        account.setPasswordHash("hash");
+        account.setAccountStatus("ACTIVE");
+        account.setDefaultTenantId(0L);
+        account.setOperatorTenantId(0L);
+        account.setDefaultMembershipId(84L);
+        account.setDefaultAppCode("PLATFORM");
+        account.setTokenVersion(1);
+        AuthorizationSnapshot snapshot = new AuthorizationSnapshot(42L, 0L, 84L, "PLATFORM",
+                "WEB", Set.of(), Set.of(), 1L);
+        Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
+        when(repository.findByPhone("13800138000")).thenReturn(account);
+        when(passwordEncoder.matches("secret", "hash")).thenReturn(true);
+        when(authorizationLoader.load(account)).thenReturn(snapshot);
+        when(jwtEncoder.encode(any())).thenReturn(encoded);
+        when(encoded.getTokenValue()).thenReturn("small-token");
+
+        service.login(new LoginRequest("13800138000", "secret"));
+
+        verify(repository).findByPhone("13800138000");
+        verify(repository, never()).findByUsername("13800138000");
+    }
+
+    @Test
+    void placeholderNumberIsNeverResolvedAsAMobileLoginIdentifier() {
+        when(repository.findByUsername("11111111111")).thenReturn(null);
+
+        assertThatThrownBy(() -> service.login(new LoginRequest("11111111111", "secret")))
+                .isInstanceOf(com.baiyue.common.core.exception.BizException.class)
+                .hasMessageContaining("登录标识或密码错误");
+
+        verify(repository).findByUsername("11111111111");
+        verify(repository, never()).findByPhone("11111111111");
+    }
+
+    @Test
+    void refreshRotatesDomesticAndOverseasTokensFromOneAuthorizationSnapshot() {
+        AuthAccount account = new AuthAccount();
+        account.setId(52L);
+        account.setUsername("merchant");
+        account.setAccountStatus("ACTIVE");
+        account.setDefaultTenantId(10001L);
+        account.setOperatorTenantId(10001L);
+        account.setDefaultMembershipId(94L);
+        account.setDefaultAppCode("MERCHANT");
+        account.setTokenVersion(3);
+        AuthorizationSnapshot snapshot = new AuthorizationSnapshot(52L, 10001L, 94L, "MERCHANT",
+                "WEB", Set.of("MERCHANT_ADMIN"), Set.of("merchant:order:list"), 3L);
+        Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
+
+        when(tokenSessionStore.consume("refresh-old")).thenReturn(
+                new TokenSessionStore.RefreshSession(52L, "refresh-session"));
+        when(repository.findById(52L)).thenReturn(account);
+        when(authorizationLoader.load(account)).thenReturn(snapshot);
+        when(jwtEncoder.encode(any())).thenReturn(encoded);
+        when(encoded.getTokenValue()).thenReturn("domestic-refreshed");
+        when(overseasTokenService.issue(account, snapshot)).thenReturn(
+                new OverseasTokenService.OverseasTokenResponse("Bearer", "overseas-refreshed", 900,
+                    snapshot.getRoles(), snapshot.getPermissions()));
+
+        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);
+        assertThat(response.roles()).containsExactly("MERCHANT_ADMIN");
+        assertThat(response.authorities()).containsExactly("merchant:order:list");
+        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();
+        account.setId(43L);
+        account.setUsername("merchant-owner");
+        account.setAccountStatus("ACTIVE");
+        account.setDefaultTenantId(10001L);
+        account.setOperatorTenantId(0L);
+        account.setDefaultMembershipId(85L);
+        account.setDefaultAppCode("MERCHANT");
+        account.setTokenVersion(2);
+        AuthorizationSnapshot snapshot = new AuthorizationSnapshot(43L, 10001L, 85L, "MERCHANT",
+                "WEB", Set.of("MERCHANT_OWNER"), Set.of("merchant:order:list"), 2L);
+        Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
+        TokenSessionStore.ImpersonationTicket ticket = new TokenSessionStore.ImpersonationTicket(
+                "ticket-1", 43L, 10001L, 85L, 42L, 84L, "support");
+
+        when(tokenSessionStore.consumeImpersonationTicket("one-time-code")).thenReturn(ticket);
+        when(repository.findById(43L)).thenReturn(account);
+        when(authorizationLoader.load(account)).thenReturn(snapshot);
+        when(jwtEncoder.encode(any())).thenReturn(encoded);
+        when(encoded.getTokenValue()).thenReturn("small-impersonation-token");
+        when(overseasTokenService.issue(account, snapshot)).thenReturn(
+                new OverseasTokenService.OverseasTokenResponse("Bearer", "overseas-impersonation-token", 900,
+                        Set.of("MERCHANT_OWNER"), Set.of("merchant:order:list")));
+
+        AuthService.ImpersonationTokenResponse response = service.exchangeImpersonationTicket("one-time-code");
+
+        assertThat(response.overseasAccessToken()).isEqualTo("overseas-impersonation-token");
+        assertThat(response.overseasExpiresIn()).isEqualTo(900);
+        assertThat(response.roles()).containsExactly("MERCHANT_OWNER");
+        assertThat(response.authorities()).containsExactly("merchant:order:list");
+
+        ArgumentCaptor<JwtEncoderParameters> jwt = ArgumentCaptor.forClass(JwtEncoderParameters.class);
+        verify(jwtEncoder).encode(jwt.capture());
+        assertThat(jwt.getValue().getClaims().getClaims())
+                .containsEntry("appCode", "MERCHANT")
+                .containsEntry("impersonated", true)
+                .containsEntry("membership_id", 85L)
+                .doesNotContainKeys("roles", "authorities", "permissions", "scope");
+        verify(tokenSessionStore).storeAccessOnly(any(), org.mockito.ArgumentMatchers.eq(43L),
+                org.mockito.ArgumentMatchers.eq(Set.of("MERCHANT_OWNER")),
+                org.mockito.ArgumentMatchers.eq(Set.of("merchant:order:list")),
+                org.mockito.ArgumentMatchers.eq(Duration.ofMinutes(15)));
+        verify(overseasTokenService).issue(account, snapshot);
+    }
+}

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

@@ -0,0 +1,148 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.IamOnboardingClient;
+import com.baiyue.auth.dto.MerchantRegisterRequest;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import com.baiyue.common.core.api.ApiResponse;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.test.context.TestPropertySource;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.transaction.support.TransactionSynchronization;
+import org.springframework.transaction.support.TransactionSynchronizationManager;
+
+import jakarta.annotation.Resource;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.never;
+
+@SpringJUnitConfig(MerchantRegistrationService.class)
+@TestPropertySource(properties = "baiyue.security.internal-service-token=internal-token")
+class MerchantRegistrationServiceTest {
+    @MockBean private AuthAccountRepository accounts;
+    @MockBean private PasswordEncoder encoder;
+    @MockBean private IamOnboardingClient onboarding;
+    @Resource private MerchantRegistrationService service;
+    @Test
+    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", "PENDING")));
+
+        var result = service.register(new MerchantRegisterRequest(
+                "registered_owner", "Password123", "注册人", "测试企业", "张三",
+                "13800138000", "owner@example.com", "CN", "深圳市宝安区"));
+
+        ArgumentCaptor<IamOnboardingClient.OnboardingRequest> onboardingRequest =
+                ArgumentCaptor.forClass(IamOnboardingClient.OnboardingRequest.class);
+        ArgumentCaptor<AuthAccount> storedAccount = ArgumentCaptor.forClass(AuthAccount.class);
+        verify(onboarding).register(eq("internal-token"), onboardingRequest.capture());
+        verify(accounts).insert(storedAccount.capture());
+
+        assertEquals(onboardingRequest.getValue().authUserId(), storedAccount.getValue().getId());
+        assertEquals(result.accountId(), storedAccount.getValue().getId());
+        assertEquals(10001L, storedAccount.getValue().getDefaultTenantId());
+        assertEquals(10001L, storedAccount.getValue().getOperatorTenantId());
+        assertEquals(30001L, storedAccount.getValue().getDefaultMembershipId());
+        assertEquals("MERCHANT", storedAccount.getValue().getDefaultAppCode());
+        assertEquals("ACTIVE", storedAccount.getValue().getAccountStatus());
+        assertEquals("13800138000", storedAccount.getValue().getPhone());
+        assertEquals("13800138000", onboardingRequest.getValue().administratorPhone());
+        assertEquals("encoded-password", storedAccount.getValue().getPasswordHash());
+        assertEquals("LOGIN_AND_COMPLETE_QUALIFICATIONS", result.nextStep());
+        assertEquals("PENDING", result.dimensionInitializationStatus());
+    }
+
+    @Test
+    void exactIncompleteRegistrationRetryReturnsTheExistingRegistration() {
+        AuthAccount account = new AuthAccount();
+        account.setId(9001L);
+        account.setUsername("registered_owner");
+        account.setPhone("13800138000");
+        account.setPasswordHash("encoded-password");
+        account.setAccountStatus("ACTIVE");
+        account.setDefaultAppCode("MERCHANT");
+        when(accounts.findByUsername("registered_owner")).thenReturn(account);
+        when(accounts.findByPhone("13800138000")).thenReturn(account);
+        when(encoder.matches("Password123", "encoded-password")).thenReturn(true);
+        when(onboarding.registration("internal-token", 9001L)).thenReturn(ApiResponse.success(
+                new IamOnboardingClient.OnboardingResponse(10001L, 30001L, "PROFILE_REQUIRED", "READY")));
+
+        var result = service.register(new MerchantRegisterRequest(
+                "registered_owner", "Password123", "注册人", "测试企业", null,
+                "13800138000", "owner@example.com", "CN", "深圳市宝安区"));
+
+        assertEquals(9001L, result.accountId());
+        assertEquals(10001L, result.tenantId());
+        assertEquals("READY", result.dimensionInitializationStatus());
+        verify(onboarding, never()).register(eq("internal-token"), any());
+        verify(accounts, never()).insert(any());
+    }
+
+    @Test
+    void phoneOwnedByAnotherUsernameDirectsTheUserBackToLogin() {
+        AuthAccount account = new AuthAccount();
+        account.setId(9001L);
+        account.setUsername("registered_owner");
+        account.setPhone("13800138000");
+        when(accounts.findByPhone("13800138000")).thenReturn(account);
+
+        var failure = assertThrows(com.baiyue.common.core.exception.BizException.class,
+                () -> service.register(new MerchantRegisterRequest(
+                        "another_owner", "Password123", "注册人", "测试企业", null,
+                        "13800138000", "owner@example.com", "CN", "深圳市宝安区")));
+
+        assertEquals("该手机号已注册，请直接登录后继续完善企业资质", failure.getMessage());
+        verify(onboarding, never()).register(eq("internal-token"), any());
+    }
+
+    @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", "PENDING")));
+        when(onboarding.compensate(eq("internal-token"), any())).thenReturn(ApiResponse.success(null));
+        doThrow(new IllegalStateException("auth database unavailable")).when(accounts).insert(any());
+
+        assertThrows(IllegalStateException.class, () -> service.register(new MerchantRegisterRequest(
+                "failed_owner", "Password123", "注册人", "测试企业", "张三",
+                "13800138000", "owner@example.com", "CN", "深圳市宝安区")));
+
+        ArgumentCaptor<IamOnboardingClient.OnboardingRequest> onboardingRequest =
+                ArgumentCaptor.forClass(IamOnboardingClient.OnboardingRequest.class);
+        ArgumentCaptor<Long> compensationUserId = ArgumentCaptor.forClass(Long.class);
+        verify(onboarding).register(eq("internal-token"), onboardingRequest.capture());
+        verify(onboarding).compensate(eq("internal-token"), compensationUserId.capture());
+        assertEquals(onboardingRequest.getValue().authUserId(), compensationUserId.getValue());
+    }
+
+    @Test
+    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", "PENDING")));
+        when(onboarding.compensate(eq("internal-token"), any())).thenReturn(ApiResponse.success(null));
+
+        TransactionSynchronizationManager.initSynchronization();
+        try {
+            service.register(new MerchantRegisterRequest(
+                    "rollback_owner", "Password123", "注册人", "测试企业", "张三",
+                    "13800138000", "owner@example.com", "CN", "深圳市宝安区"));
+            var synchronizations = TransactionSynchronizationManager.getSynchronizations();
+            assertEquals(1, synchronizations.size());
+            synchronizations.get(0).afterCompletion(TransactionSynchronization.STATUS_ROLLED_BACK);
+            verify(onboarding).compensate(eq("internal-token"), any());
+        } finally {
+            TransactionSynchronizationManager.clearSynchronization();
+        }
+    }
+}

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("OVERSEAS_WAREHOUSE_PDA_OPERATOR"), 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

@@ -0,0 +1,139 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.AuthorizationLoader;
+import com.baiyue.auth.client.AuthorizationSnapshot;
+import com.baiyue.auth.config.OverseasJwtProperties;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
+import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.test.context.TestPropertySource;
+
+import java.time.Duration;
+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})
+@TestPropertySource(properties = "baiyue.security.overseas-jwt.enabled=true")
+class OverseasTokenServiceTest {
+    @MockBean private AuthAccountRepository accounts;
+    @MockBean private AuthorizationLoader authorizationLoader;
+    @MockBean(name = "overseasJwtEncoder") private JwtEncoder encoder;
+    @Resource private OverseasTokenService service;
+
+    @Configuration(proxyBeanMethods = false)
+    static class Config {
+        @Bean OverseasJwtProperties properties() {
+            return new OverseasJwtProperties(true, "auth-service", "lastleg-api", "{}", "current-kid",
+                Duration.ofMinutes(15));
+        }
+    }
+
+    @Test
+    void signsShortRs256TokenWithCrossRegionClaims() {
+        AuthAccount account = new AuthAccount();
+        account.setId(42L); account.setAccountStatus("ACTIVE"); account.setDefaultTenantId(999L);
+        account.setDefaultMembershipId(84L); account.setDefaultAppCode("MERCHANT");
+        String authority = "platform:overseas-master-data:quote:list";
+        String merchantAuthority = "merchant:warehouse:delivery:list";
+        String merchantCrossBorderAuthority = "merchant:cross-border:procurement";
+        String lastlegAuthority = "lastleg:pda:operate";
+        String financeAuthority = "platform:finance:fee-source:edit";
+        String domesticAuthority = "platform:firstleg:order:list";
+        AuthorizationSnapshot snapshot = new AuthorizationSnapshot(42L, 0L, 84L, "PLATFORM", "WEB",
+            Set.of("OVERSEAS_WAREHOUSE_PDA_OPERATOR"),
+            Set.of(authority, merchantAuthority, merchantCrossBorderAuthority, lastlegAuthority,
+                financeAuthority, domesticAuthority), 7L, 900L);
+        Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
+        when(accounts.findById(42L)).thenReturn(account);
+        when(authorizationLoader.load(account)).thenReturn(snapshot);
+        when(encoder.encode(any())).thenReturn(encoded);
+        when(encoded.getTokenValue()).thenReturn("overseas-token");
+
+        var response = service.exchange(42L);
+
+        ArgumentCaptor<JwtEncoderParameters> captor = ArgumentCaptor.forClass(JwtEncoderParameters.class);
+        verify(encoder).encode(captor.capture());
+        var parameters = captor.getValue();
+        assertThat(parameters.getJwsHeader().getAlgorithm()).isEqualTo(SignatureAlgorithm.RS256);
+        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", 0L)
+            .containsEntry("membership_id", 84L)
+            .containsEntry("app_code", "PLATFORM").containsEntry("client_type", "WEB")
+            .containsEntry("permission_version", 7L)
+            .containsEntry("token_version", 0)
+            .containsEntry("overseas_warehouse_id", 900L)
+            .doesNotContainKeys("roles", "authorities", "permissions", "userId", "tenantId", "appCode",
+                "permissionVersion");
+        assertThat(response.expiresIn()).isEqualTo(900);
+        assertThat(response.roles()).containsExactly("OVERSEAS_WAREHOUSE_PDA_OPERATOR");
+        assertThat(response.authorities()).containsExactlyInAnyOrder(authority, merchantAuthority,
+            merchantCrossBorderAuthority, lastlegAuthority, financeAuthority, domesticAuthority);
+    }
+
+    @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("OVERSEAS_WAREHOUSE_PDA_OPERATOR"), Set.of("lastleg:pda:operate"), 8L, 900L);
+        AuthorizationSnapshot newBinding = new AuthorizationSnapshot(43L, 0L, 85L, "PLATFORM", "PDA",
+            Set.of("OVERSEAS_WAREHOUSE_PDA_OPERATOR"), 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("OVERSEAS_WAREHOUSE_PDA_OPERATOR"), 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");
+    }
+}

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

@@ -1,10 +1,17 @@
 package com.baiyue.auth.service;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import jakarta.annotation.Resource;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
 import org.springframework.data.redis.core.StringRedisTemplate;
 import org.springframework.data.redis.core.ValueOperations;
 import org.springframework.data.redis.core.SetOperations;
+import org.springframework.test.context.TestPropertySource;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
 
 import java.time.Duration;
 import java.util.Set;
@@ -16,32 +23,49 @@ import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 import static org.mockito.Mockito.eq;
 
+@DisplayName("令牌会话存储")
+@SpringJUnitConfig(classes = {TokenSessionStore.class, TokenSessionStoreTest.TestConfig.class})
+@TestPropertySource(properties = "baiyue.security.token-key-prefix=baiyue:auth")
 class TokenSessionStoreTest {
+    @MockBean
+    private StringRedisTemplate redis;
+
+    @Resource
+    private TokenSessionStore store;
+
+    @Configuration(proxyBeanMethods = false)
+    static class TestConfig {
+        @Bean
+        ObjectMapper objectMapper() {
+            return new ObjectMapper();
+        }
+    }
     @Test
     void storesAccessAndHashedRefreshWithIndependentTtls() {
-        StringRedisTemplate redis = mock(StringRedisTemplate.class);
         @SuppressWarnings("unchecked")
         ValueOperations<String, String> values = mock(ValueOperations.class);
         when(redis.opsForValue()).thenReturn(values);
-        TokenSessionStore store = new TokenSessionStore(redis, new ObjectMapper(), "baiyue:auth:");
 
-        store.store("jti-1", 42L, "raw-refresh", Duration.ofMinutes(30), Duration.ofDays(7));
+        store.store("jti-1", 42L, Set.of("ADMIN"), Set.of("order:read"),
+                "raw-refresh", Duration.ofMinutes(30), Duration.ofDays(7));
 
-        verify(values).set("baiyue:auth:access:jti-1", "42", Duration.ofMinutes(30));
+        verify(values).set(eq("baiyue:auth:access:jti-1"),
+                org.mockito.ArgumentMatchers.argThat(value -> value.contains("\"version\":1")
+                        && value.contains("\"userId\":42")
+                        && value.contains("ADMIN") && value.contains("order:read")),
+                eq(Duration.ofMinutes(30)));
         verify(values).set(org.mockito.ArgumentMatchers.startsWith("baiyue:auth:refresh:"),
                 org.mockito.ArgumentMatchers.contains("\"userId\":42"), org.mockito.ArgumentMatchers.eq(Duration.ofDays(7)));
     }
 
     @Test
     void atomicallyConsumesRefreshAndRevokesItsAccessSession() throws Exception {
-        StringRedisTemplate redis = mock(StringRedisTemplate.class);
         @SuppressWarnings("unchecked")
         ValueOperations<String, String> values = mock(ValueOperations.class);
         when(redis.opsForValue()).thenReturn(values);
         String json = new ObjectMapper().writeValueAsString(
                 new TokenSessionStore.RefreshSession(42L, "jti-1"));
         when(values.getAndDelete(anyString())).thenReturn(json);
-        TokenSessionStore store = new TokenSessionStore(redis, new ObjectMapper(), "baiyue:auth");
 
         TokenSessionStore.RefreshSession session = store.consume("raw-refresh");
 
@@ -53,26 +77,23 @@ class TokenSessionStoreTest {
 
     @Test
     void treatsAlreadyConsumedRefreshAsInvalid() {
-        StringRedisTemplate redis = mock(StringRedisTemplate.class);
         @SuppressWarnings("unchecked")
         ValueOperations<String, String> values = mock(ValueOperations.class);
         when(redis.opsForValue()).thenReturn(values);
         when(values.getAndDelete(anyString())).thenReturn(null);
 
-        assertThat(new TokenSessionStore(redis, new ObjectMapper(), "baiyue:auth")
-                .consume("raw-refresh")).isNull();
+        assertThat(store.consume("raw-refresh")).isNull();
     }
 
     @Test
     void revokesAllIndexedSessionsForUser() {
-        StringRedisTemplate redis = mock(StringRedisTemplate.class);
         @SuppressWarnings("unchecked")
         SetOperations<String, String> sets = mock(SetOperations.class);
         when(redis.opsForSet()).thenReturn(sets);
         when(sets.members("baiyue:auth:user-sessions:42"))
                 .thenReturn(Set.of("baiyue:auth:access:a", "baiyue:auth:refresh:b"));
 
-        new TokenSessionStore(redis, new ObjectMapper(), "baiyue:auth").revokeAll(42L);
+        store.revokeAll(42L);
 
         verify(redis).delete(eq(Set.of("baiyue:auth:access:a", "baiyue:auth:refresh:b")));
         verify(redis).delete("baiyue:auth:user-sessions:42");

common-audit/AGENTS.md

@@ -0,0 +1,23 @@
+# Common Audit 模块指引
+
+## 职责边界
+
+- 负责业务审计事件采集、注解切面、敏感字段脱敏以及日志/HTTP 输出。
+- 审计记录持久化属于 `audit-service/`；本模块不依赖具体业务 Entity 或数据库。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 审计注解与切面 | `src/main/java/com/baiyue/common/audit/BusinessAudit.java`、`BusinessAuditAspect.java` |
+| 事件模型 | `AuditEvent.java` |
+| 输出抽象与实现 | `AuditSink.java`、`LoggingAuditSink.java`、`HttpAuditSink.java` |
+| 敏感数据脱敏 | `SensitiveDataSanitizer.java` |
+| `baiyue.audit` 配置 | `AuditProperties.java` |
+| 自动配置 | `BaiyueAuditAutoConfiguration.java` 与 `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
+
+## 修改与验证
+
+- 新增审计字段时先确认不会泄露密码、令牌、证件或客户敏感数据，并检查 `audit-service` 接收 DTO。
+- 审计失败不应破坏核心业务；调整输出策略时保留超时、关闭开关和安全降级。
+- 从父目录运行 `mvn -pl common-audit -am test`，并按影响追加验证 `audit-service`。

common-audit/pom.xml

@@ -11,5 +11,16 @@
         <dependency><groupId>com.baiyue.shared</groupId><artifactId>baiyue-common-security</artifactId><version>${project.version}</version></dependency>
         <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-aop</artifactId></dependency>
         <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
+        <dependency><groupId>org.springframework</groupId><artifactId>spring-jdbc</artifactId></dependency>
+        <dependency>
+            <groupId>org.apache.rocketmq</groupId>
+            <artifactId>rocketmq-spring-boot-starter</artifactId>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 </project>

common-audit/src/main/java/com/baiyue/common/audit/AuditEvent.java

@@ -6,7 +6,7 @@ import java.time.Instant;
  * 跨服务业务审计事件契约，记录操作对象、操作者、租户、请求上下文、执行结果和变更快照。
  */
 public record AuditEvent(
-    String eventType, String resourceType, String resourceId, String description,
+    String eventId, String eventType, String resourceType, String resourceId, String description,
     String requestId, String traceId, Long tenantId, Long operatorTenantId,
     Long userId, String username, String appCode, String clientType,
     String httpMethod, String requestUri, String clientIp, long durationMs,

common-audit/src/main/java/com/baiyue/common/audit/AuditOutboxPublisher.java

@@ -0,0 +1,62 @@
+package com.baiyue.common.audit;
+
+import org.apache.rocketmq.spring.core.RocketMQTemplate;
+import org.apache.rocketmq.spring.support.RocketMQHeaders;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.messaging.support.MessageBuilder;
+import org.springframework.scheduling.annotation.Scheduled;
+
+/** 带租约、退避、死信和自动补偿的审计 Outbox 发布器。 */
+public class AuditOutboxPublisher {
+    private static final Logger log = LoggerFactory.getLogger(AuditOutboxPublisher.class);
+    private static final int[] BACKOFF_SECONDS = {5, 15, 60, 300, 900};
+    private final AuditOutboxRepository repository;
+    private final RocketMQTemplate rocketMQ;
+    private final AuditProperties properties;
+    private final String owner;
+
+    public AuditOutboxPublisher(AuditOutboxRepository repository, RocketMQTemplate rocketMQ,
+                                AuditProperties properties, String owner) {
+        this.repository = repository;
+        this.rocketMQ = rocketMQ;
+        this.properties = properties;
+        this.owner = owner;
+    }
+
+    @Scheduled(fixedDelayString = "${baiyue.audit.outbox.poll-interval-ms:5000}")
+    public void publish() {
+        AuditProperties.Outbox config = properties.getOutbox();
+        repository.releaseExpiredClaims();
+        repository.compensateDead(config.getCompensationDelayMinutes(), config.getMaxCompensations());
+        repository.deleteSent(config.getRetentionDays());
+        for (String eventId : repository.publishableIds(config.getBatchSize())) {
+            if (!repository.claim(eventId, owner, config.getLeaseSeconds())) {
+                continue;
+            }
+            AuditOutboxRepository.OutboxRow row = repository.find(eventId);
+            if (row == null) {
+                continue;
+            }
+            try {
+                var message = MessageBuilder.withPayload(row.payloadJson())
+                    .setHeader(RocketMQHeaders.KEYS, eventId)
+                    .setHeader("eventId", eventId)
+                    .build();
+                rocketMQ.syncSend(properties.getRocketmq().getTopic() + ":AUDIT", message,
+                    properties.getRocketmq().getSendTimeoutMs());
+                repository.sent(eventId, owner);
+            } catch (RuntimeException exception) {
+                int index = Math.min(Math.max(row.attemptCount(), 1) - 1, BACKOFF_SECONDS.length - 1);
+                repository.failed(eventId, owner, config.getMaxAttempts(), BACKOFF_SECONDS[index],
+                    safe(exception.getMessage()));
+                log.warn("审计事件投递失败 eventId={} attempt={}", eventId, row.attemptCount(), exception);
+            }
+        }
+    }
+
+    private static String safe(String value) {
+        String message = value == null ? "RocketMQ 发送失败" : value;
+        return message.length() <= 1000 ? message : message.substring(0, 1000);
+    }
+}

common-audit/src/main/java/com/baiyue/common/audit/AuditOutboxRepository.java

@@ -0,0 +1,94 @@
+package com.baiyue.common.audit;
+
+import jakarta.annotation.Resource;
+import org.springframework.jdbc.core.JdbcTemplate;
+
+import java.util.List;
+
+/** 业务库本地审计 Outbox 仓储。 */
+public class AuditOutboxRepository {
+    @Resource
+    private JdbcTemplate jdbc;
+
+    public void append(AuditEvent event, String payload) {
+        jdbc.update("""
+            INSERT INTO sys_audit_outbox
+              (event_id,event_type,resource_type,resource_id,service_name,payload_json,status,
+               attempt_count,compensation_count,next_retry_at,created_at,updated_at)
+            VALUES (?,?,?,?,?,CAST(? AS JSON),'PENDING',0,0,CURRENT_TIMESTAMP(3),
+                    CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3))
+            """, event.eventId(), event.eventType(), event.resourceType(), event.resourceId(),
+            event.serviceName(), payload);
+    }
+
+    public List<String> publishableIds(int limit) {
+        return jdbc.queryForList("""
+            SELECT event_id FROM sys_audit_outbox
+            WHERE status='PENDING' AND next_retry_at<=CURRENT_TIMESTAMP(3)
+            ORDER BY next_retry_at,created_at LIMIT ?
+            """, String.class, limit);
+    }
+
+    public boolean claim(String eventId, String owner, int leaseSeconds) {
+        return jdbc.update("""
+            UPDATE sys_audit_outbox SET status='SENDING',lease_owner=?,
+              lease_until=DATE_ADD(CURRENT_TIMESTAMP(3),INTERVAL ? SECOND),
+              attempt_count=attempt_count+1,updated_at=CURRENT_TIMESTAMP(3)
+            WHERE event_id=? AND status='PENDING' AND next_retry_at<=CURRENT_TIMESTAMP(3)
+            """, owner, leaseSeconds, eventId) == 1;
+    }
+
+    public OutboxRow find(String eventId) {
+        List<OutboxRow> rows = jdbc.query(
+            "SELECT event_id,payload_json,attempt_count FROM sys_audit_outbox WHERE event_id=?",
+            (rs, rowNum) -> new OutboxRow(rs.getString(1), rs.getString(2), rs.getInt(3)), eventId);
+        return rows.isEmpty() ? null : rows.get(0);
+    }
+
+    public boolean sent(String eventId, String owner) {
+        return jdbc.update("""
+            UPDATE sys_audit_outbox SET status='SENT',sent_at=CURRENT_TIMESTAMP(3),
+              lease_owner=NULL,lease_until=NULL,last_error=NULL,updated_at=CURRENT_TIMESTAMP(3)
+            WHERE event_id=? AND status='SENDING' AND lease_owner=?
+            """, eventId, owner) == 1;
+    }
+
+    public boolean failed(String eventId, String owner, int maxAttempts, int backoffSeconds, String error) {
+        return jdbc.update("""
+            UPDATE sys_audit_outbox
+            SET status=IF(attempt_count>=?,'DEAD','PENDING'),
+              next_retry_at=IF(attempt_count>=?,next_retry_at,
+                DATE_ADD(CURRENT_TIMESTAMP(3),INTERVAL ? SECOND)),
+              dead_at=IF(attempt_count>=?,CURRENT_TIMESTAMP(3),dead_at),
+              lease_owner=NULL,lease_until=NULL,last_error=?,updated_at=CURRENT_TIMESTAMP(3)
+            WHERE event_id=? AND status='SENDING' AND lease_owner=?
+            """, maxAttempts, maxAttempts, backoffSeconds, maxAttempts, error, eventId, owner) == 1;
+    }
+
+    public int releaseExpiredClaims() {
+        return jdbc.update("""
+            UPDATE sys_audit_outbox SET status='PENDING',next_retry_at=CURRENT_TIMESTAMP(3),
+              lease_owner=NULL,lease_until=NULL,updated_at=CURRENT_TIMESTAMP(3)
+            WHERE status='SENDING' AND lease_until<=CURRENT_TIMESTAMP(3) LIMIT 100
+            """);
+    }
+
+    public int compensateDead(int delayMinutes, int maxCompensations) {
+        return jdbc.update("""
+            UPDATE sys_audit_outbox SET status='PENDING',attempt_count=0,
+              compensation_count=compensation_count+1,next_retry_at=CURRENT_TIMESTAMP(3),
+              dead_at=NULL,last_error=NULL,updated_at=CURRENT_TIMESTAMP(3)
+            WHERE status='DEAD' AND compensation_count<?
+              AND dead_at<=DATE_SUB(CURRENT_TIMESTAMP(3),INTERVAL ? MINUTE) LIMIT 50
+            """, maxCompensations, delayMinutes);
+    }
+
+    public int deleteSent(int retentionDays) {
+        return jdbc.update("""
+            DELETE FROM sys_audit_outbox WHERE status='SENT'
+              AND sent_at<DATE_SUB(CURRENT_TIMESTAMP(3),INTERVAL ? DAY) LIMIT 500
+            """, retentionDays);
+    }
+
+    public record OutboxRow(String eventId, String payloadJson, int attemptCount) { }
+}

common-audit/src/main/java/com/baiyue/common/audit/AuditOutboxRocketMqAutoConfiguration.java

@@ -0,0 +1,33 @@
+package com.baiyue.common.audit;
+
+import org.apache.rocketmq.spring.core.RocketMQTemplate;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.scheduling.annotation.EnableScheduling;
+
+/**
+ * 审计 Outbox 的 RocketMQ 发布配置。
+ * 该配置与基础审计配置隔离：未引入 RocketMQ 的服务仍可使用 HTTP 审计投递。
+ */
+@AutoConfiguration(after = BaiyueAuditAutoConfiguration.class)
+@EnableScheduling
+@ConditionalOnClass(name = "org.apache.rocketmq.spring.core.RocketMQTemplate")
+@ConditionalOnBean(type = {
+        "com.baiyue.common.audit.AuditOutboxRepository",
+        "org.apache.rocketmq.spring.core.RocketMQTemplate"
+})
+@ConditionalOnProperty(prefix = "baiyue.audit.outbox", name = "publisher-enabled", havingValue = "true")
+public class AuditOutboxRocketMqAutoConfiguration {
+
+    @Bean
+    AuditOutboxPublisher auditOutboxPublisher(AuditOutboxRepository repository,
+                                              RocketMQTemplate rocketMQ,
+                                              AuditProperties properties,
+                                              @Value("${spring.application.name:unknown}-${random.uuid}") String owner) {
+        return new AuditOutboxPublisher(repository, rocketMQ, properties, owner);
+    }
+}

common-audit/src/main/java/com/baiyue/common/audit/AuditProperties.java

@@ -11,6 +11,8 @@ public class AuditProperties {
     private String endpoint;
     private int maxPayloadLength = 16000;
     private String serviceName = "unknown-service";
+    private final Outbox outbox = new Outbox();
+    private final Rocketmq rocketmq = new Rocketmq();
 
     public boolean isEnabled() { return enabled; }
     public void setEnabled(boolean enabled) { this.enabled = enabled; }
@@ -20,4 +22,44 @@ public class AuditProperties {
     public void setMaxPayloadLength(int maxPayloadLength) { this.maxPayloadLength = maxPayloadLength; }
     public String getServiceName() { return serviceName; }
     public void setServiceName(String serviceName) { this.serviceName = serviceName; }
+    public Outbox getOutbox() { return outbox; }
+    public Rocketmq getRocketmq() { return rocketmq; }
+
+    public static class Outbox {
+        private boolean enabled;
+        private boolean publisherEnabled;
+        private int batchSize = 50;
+        private int leaseSeconds = 60;
+        private int maxAttempts = 5;
+        private int maxCompensations = 2;
+        private int compensationDelayMinutes = 30;
+        private int retentionDays = 30;
+
+        public boolean isEnabled() { return enabled; }
+        public void setEnabled(boolean enabled) { this.enabled = enabled; }
+        public boolean isPublisherEnabled() { return publisherEnabled; }
+        public void setPublisherEnabled(boolean publisherEnabled) { this.publisherEnabled = publisherEnabled; }
+        public int getBatchSize() { return batchSize; }
+        public void setBatchSize(int batchSize) { this.batchSize = batchSize; }
+        public int getLeaseSeconds() { return leaseSeconds; }
+        public void setLeaseSeconds(int leaseSeconds) { this.leaseSeconds = leaseSeconds; }
+        public int getMaxAttempts() { return maxAttempts; }
+        public void setMaxAttempts(int maxAttempts) { this.maxAttempts = maxAttempts; }
+        public int getMaxCompensations() { return maxCompensations; }
+        public void setMaxCompensations(int maxCompensations) { this.maxCompensations = maxCompensations; }
+        public int getCompensationDelayMinutes() { return compensationDelayMinutes; }
+        public void setCompensationDelayMinutes(int compensationDelayMinutes) { this.compensationDelayMinutes = compensationDelayMinutes; }
+        public int getRetentionDays() { return retentionDays; }
+        public void setRetentionDays(int retentionDays) { this.retentionDays = retentionDays; }
+    }
+
+    public static class Rocketmq {
+        private String topic = "test-baiyue-audit-event-v1";
+        private int sendTimeoutMs = 3000;
+
+        public String getTopic() { return topic; }
+        public void setTopic(String topic) { this.topic = topic; }
+        public int getSendTimeoutMs() { return sendTimeoutMs; }
+        public void setSendTimeoutMs(int sendTimeoutMs) { this.sendTimeoutMs = sendTimeoutMs; }
+    }
 }

common-audit/src/main/java/com/baiyue/common/audit/BaiyueAuditAutoConfiguration.java

@@ -3,10 +3,17 @@ package com.baiyue.common.audit;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
+import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.web.client.RestClient;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.TransactionDefinition;
+import org.springframework.transaction.support.TransactionTemplate;
 
 /**
  * 业务审计自动配置，按配置创建脱敏器、审计输出端和审计切面。
@@ -15,9 +22,29 @@ import org.springframework.web.client.RestClient;
 @EnableConfigurationProperties(AuditProperties.class)
 @ConditionalOnProperty(prefix = "baiyue.audit", name = "enabled", havingValue = "true", matchIfMissing = true)
 public class BaiyueAuditAutoConfiguration {
-    @Bean @ConditionalOnMissingBean AuditSink auditSink(RestClient.Builder builder, AuditProperties p) {
-        return p.getEndpoint() == null || p.getEndpoint().isBlank() ? new LoggingAuditSink() : new HttpAuditSink(builder, p.getEndpoint());
+    @Bean
+    @ConditionalOnMissingBean
+    AuditSink auditSink(RestClient.Builder builder, AuditProperties p, ObjectMapper mapper,
+                        ObjectProvider<AuditOutboxRepository> outbox,
+                        ObjectProvider<PlatformTransactionManager> transactionManagers,
+                        @Value("${baiyue.security.internal-service-token:}") String internalServiceToken) {
+        AuditOutboxRepository repository = outbox.getIfAvailable();
+        PlatformTransactionManager transactionManager = transactionManagers.getIfAvailable();
+        if (p.getOutbox().isEnabled() && p.getOutbox().isPublisherEnabled()
+                && repository != null && transactionManager != null) {
+            TransactionTemplate transactions = new TransactionTemplate(transactionManager);
+            transactions.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRES_NEW);
+            return new OutboxAuditSink(repository, mapper, transactions);
+        }
+        return p.getEndpoint() == null || p.getEndpoint().isBlank()
+                ? new LoggingAuditSink()
+                : new HttpAuditSink(builder, p.getEndpoint(), internalServiceToken);
     }
+    @Bean
+    @ConditionalOnBean(JdbcTemplate.class)
+    @ConditionalOnProperty(prefix = "baiyue.audit.outbox", name = "enabled", havingValue = "true")
+    AuditOutboxRepository auditOutboxRepository() { return new AuditOutboxRepository(); }
+
     @Bean SensitiveDataSanitizer sensitiveDataSanitizer(ObjectMapper mapper, AuditProperties p) { return new SensitiveDataSanitizer(mapper, p.getMaxPayloadLength()); }
-    @Bean BusinessAuditAspect businessAuditAspect(AuditSink sink, SensitiveDataSanitizer sanitizer, AuditProperties p) { return new BusinessAuditAspect(sink, sanitizer, p.getServiceName()); }
+    @Bean BusinessAuditAspect businessAuditAspect() { return new BusinessAuditAspect(); }
 }