feat(file): validate platform dispatch vehicle and driver evidence

# Conflicts:
#	deploy/sql/README.md
#	deploy/sql/海外区域统一增量-MySQL8.sql

.gitignore

@@ -1,4 +1,5 @@
 target/
+node_modules/
 .docker-context/
 *.log
 .idea/
@@ -13,6 +14,7 @@ logs/
 data/
 .env
 .env.*
+.env.development
 !.env.example
 !.env.*.example
 application-local.yml
@@ -23,4 +25,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
@@ -40,10 +93,11 @@ cache:
       - 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

@@ -1,73 +1,164 @@
-# 柏悦头程后端项目指引
+# 头程与海外仓后端项目指引
 
-## 适用范围
+> 当前为单 TEST、统一 Gateway/Auth 会话/Nacos 与业务 Outbox 直接投递。架构规则及部署/验收状态唯一见 `../docs/测试环境单机部署与配置契约.md`、`../docs/统一认证与服务通信契约.md`。模块旧双区域说明不能覆盖这两份契约；构建、部署与整体验收分别核对。
 
-- 本文件适用于 `baiyue-firstleg/` 整个 Maven 多模块仓库；进入子模块后同时遵守该模块的 `AGENTS.md`。
-- 开始修改前先读根目录 `README.md`、`pom.xml` 和 `docs/头程项目目录结构与服务说明.md`；业务边界以本文件及该说明的“项目定位、主要调用关系、开发和拆分约束”为准。
-- 本仓只承载国内头程业务。尾程源码、数据库、Redis、Nacos 和内部接口不得并入本仓。
+根 POM 当前聚合 20 个模块（7 个公共/依赖模块、13 个服务），部署映射见 `deploy/service-map.yml`。`gateway-overseas/` 与 `event-bridge-service/` 为退役待清理源码，不是当前构建或部署单元。
 
-## 模块快速索引
+## 适用范围与定位
 
-| 模块 | 职责 | 首选入口 |
-|---|---|---|
-| `platform-bom/` | 公共制品版本清单 | `pom.xml` 的 `dependencyManagement` |
-| `common-core/` | 返回模型、错误码、基础实体、MyBatis 配置 | `ApiResponse.java`、`ResultCode.java`、`exception/`、`model/`、`mybatis/`；成功码为字符串 `"200"` |
-| `common-web/` | HTTP 200 业务响应、全局异常、请求链路标识、长整型 JSON 字符串序列化 | `CommonWebAutoConfiguration.java`、`GlobalExceptionHandler.java`、`CorrelationIdFilter.java`、`LongIdJacksonConfiguration.java` |
-| `common-security/` | JWT、Redis 会话校验、认证上下文、401/403 | `JwtAuthenticationFilter.java`、`RedisAccessTokenSessionValidator.java` |
-| `common-openapi/` | SpringDoc 自动配置与长整型字符串契约 | `BaiyueOpenApiAutoConfiguration.java`、`OpenApiProperties.java` |
-| `common-audit/` | 审计注解、切面、脱敏与日志/HTTP 发送 | `BusinessAuditAspect.java`、`SensitiveDataSanitizer.java`、`HttpAuditSink.java` |
-| `common-event-contract/` | 跨区域事件信封、类型、标识、哈希与校验 | `EventEnvelope.java`、`EventTypes.java`、`EventEnvelopeValidator.java` |
-| `gateway/` | 路由、CORS、入口安全、请求标识、访问域隔离 | `config/`、`filter/CorrelationIdWebFilter.java`、`src/main/resources/application*.yml` |
-| `auth/` | 登录、令牌、注册、账号、密码与账号归属范围 | `InternalAccountController.java`、`AccountManagementService.java`、`AccountManagementDtos.java`、`src/main/resources/db/` |
-| `iam/` | 租户、商户成员、平台统一用户管理、企业资料/资质、RBAC 与授权快照 | `PlatformUserManagementController.java`、`PlatformTenantController.java`、`ProfileResourceController.java`、`RbacController.java` |
-| `order/` | 订单主数据、租户运单数、持久化幂等、状态编排、快照与 Outbox | `PlatformFirstLegOrderController.java`、`OrderApplicationService.java`、`TenantOrderCountResponse.java`、`README-ORDER.md` |
-| `firstleg/` | 履约任务分页/详情、操作分配与分配历史 | `PlatformFulfillmentAssignmentController.java`、`FulfillmentTaskService.java`、`src/main/resources/db/phase1-firstleg-task-list-index.sql` |
-| `warehouse/` | 仓库、地址、服务能力、往来单位多类型、快递公司与 XLSX 导入 | `controller/`、`PlatformPartnerQueryService.java`、`PartnerImportService.java`、`ExpressCompanyImportService.java` |
-| `file/` | 企业资质文件上传、替换、预览与鉴权 | `QualificationFileController.java`、`PlatformQualificationFileController.java`、`LocalQualificationStorage.java`；元数据仍归 IAM，File 自身表结构尚未接入 |
-| `print/` | 打印中心边界 | 当前为应用、健康检查和 `print/src/main/resources/db/print.sql` 骨架 |
-| `audit-service/` | 审计事件接收与持久化 | `AuditIngestController.java`、`AuditIngestService.java`；当前接收接口未实现内部令牌保护 |
-| `integration-service/` | 重量 OCR、百度 OCR、Amazon 等第三方适配 | `controller/WeightOcrController.java`、`service/ocr/`、`provider/ocr/`、`IntegrationProperties.java` |
-| `event-bridge-service/` | 跨区域事件接收、校验与 Inbox 幂等 | `EventBridgeController.java`、`EventInboxService.java` |
+- 本文件适用于 `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`。文件对象归 `file`，第三方适配归 `integration-service`；跨服务通过内部客户端、DTO、事件和服务令牌协作。
+- 普通业务成功/失败使用 HTTP 200 + body `code`（成功为字符串 `"200"`）；认证、基础设施和网关拒绝可使用真实 401/403/503。
+
+## 服务路由（按关键词定位）
+
+本表只保留定位入口；命中业务后用 `rg -n -F '关键词' docs/backend-business-index.md` 读取对应行/段的详细约束，再沿代码引用追踪；不默认全文加载详细索引。已知目标文件时直接定位，并定向核对该业务约束。
+
+### 后端任务最小读取集
+
+- 单服务 Controller/Service/Mapper 任务：本文件、目标服务 `AGENTS.md`、目标类及其直接调用点。
+- 跨服务 API/事件任务：在上述基础上增加直接调用方、被调用方及受影响的 OpenAPI/事件契约；公开路径、访问域或入口鉴权变化才增加 Gateway，内部调用和事件不经公网 Gateway。不因业务关键词自动加载整个业务专题。
+- 只有状态、权限、数据库或验收边界无法从上述入口确定时，才读取 `docs/业务快速索引.md`、专题 README 或完整契约。
+- 读取预算遵循工作区根指引：超过约 250 行或 8000 字符时先读职责、硬边界和验证章节，再检索任务命中段；不得仅因行数少而全文加载长业务表。聚合构建或架构任务才读取相关 `README.md`、`pom.xml` 和目录结构文档，已知单模块任务不增加概览文档。
+
+| 任务关键词 | 首选服务 |
 |---|---|
-| 后台用户管理、平台/企业账号、跨租户调动 | `iam/.../controller/PlatformUserManagementController.java` → `service/PlatformUserManagementService.java` → `auth/.../controller/InternalAccountController.java` 的 scope 接口 |
-| 企业客户档案、审核、必填资质 | `iam/.../controller/PlatformTenantController.java`、`service/TenantService.java`、`service/ProfileResourceService.java` |
-| 客户列表真实运单数 | `order/.../controller/PlatformFirstLegOrderController.java` 的 `/tenant-counts`；不要在 IAM 查订单表 |
-| 平台代客户上传或替换资质 | `file/.../controller/PlatformQualificationFileController.java` → `client/IamQualificationClient.java` → `iam/.../controller/InternalTenantController.java` 的 `/platform-qualifications` |
-| 往来单位多类型 | `warehouse/.../service/PlatformPartnerQueryService.java`、`entity/PartnerTypeEntity.java`、`src/main/resources/db/warehouse-partner.sql`，消费者看 `order/.../client/PartnerClient.java` |
-| 往来单位/快递公司批量导入 | `warehouse/.../service/PartnerImportService.java`、`ExpressCompanyImportService.java`、两个平台 Controller 的 `/import-template` 与 `/import` |
-| HTTP 200、body code、成功码 `"200"` | `docs/统一响应约定改造方案-HTTP200.md`、`common-core/ResultCode.java`、`common-web/GlobalExceptionHandler.java` |
-| 单服务 Jenkins 构建或部署 | 总控 `Jenkinsfile`、子 Job `Jenkinsfile.service`、模块/JAR 映射 `deploy/service-map.yml` |
+| 登录、Token、密码、注册与顶层授权快照 | `auth/` |
+| 客户档案、成员、审核、RBAC、授权快照 | `iam/` |
+| 客户建档默认箱规与权重系数初始化及补偿 | `iam/`、`firstleg/` |
+| 消息中心、站内通知、消息模板、收件箱 | `iam/` |
+| 订单、货物、快照、状态、幂等、Outbox | `order/` |
+| 客户头程订单中文批量导入 | `order/` |
+| 平台修改客户原始申报、履约渠道变更与跨服务同步 | `order/`、`firstleg/` |
+| 平台订单批量审核预览 | `order/` |
+| 履约分配、入库、测量、箱规算法、审核、FBA 计费 | `firstleg/` |
+| 入库单扣货、解除、凭证与履约门禁 | `firstleg/`、`file/` |
+| 称重确认、整票库位块与 PDA 资源结算 | `firstleg/`、`warehouse/` |
+| 客户专属价格簿、柜级阶梯运费与受控调价 | `firstleg/` |
+| Firstleg 内部模块化与依赖基线 | `firstleg/` |
+| Mapper 新增、移动、Bean 缺失与扫描遗漏 | 目标持久化服务 |
+| 脚本管理、全量验证、测试造数与诊断 | 仓库根 `scripts/`；服务专属脚本留在 `<service>/scripts/` |
+| 分柜、柜次、智能排柜、预装/装柜清单、真实柜号后补、PDA | `firstleg/` |
+| 合柜报关 / 同柜不可拆组、跨客户合柜、整组分配/移除 | `firstleg/` |
+| 全局智能装柜候选、柜次、占位与移除 | `firstleg/`、`order/` |
+| 客户入库结果与头程费用确认 | `firstleg/` |
+| 订舱资料/打印、船期、订舱级拖车、报关 | `firstleg/` |
+| 目的港码头拖车与还空预警 | `firstleg/` |
+| 客户账期、费用池、账单、入仓码联查、收款、成本、核销 | `finance/` |
+| 客户资金账户、充值、授信、冻结、结算与跨区资金指令 | `finance/`、`lastleg-service/`、`common-event-contract/` |
+| 柜级公共费用跨客户分摊 | `firstleg/`、`finance/` |
+| 海外业务费用来源跨区入池 | `lastleg-service/`、`common-event-contract/`、`finance/` |
+| 入库/柜次应付、直接已付、付款流水与凭证 | `firstleg/`、`finance/`、`file/` |
+| 仓库、往来单位、快递、托盘、库位 | `warehouse/` |
+| 供应商、国内整柜库存与出入库 | `warehouse/` |
+| 客户运营统计、在途柜量 | `firstleg/` |
+| 平台操作日志与审计查询 | `audit-service/` |
+| 资质、导出、导出退避重试、测量图片、文件下载 | `file/` |
+| 路由、CORS、JWT 入口、访问域 | `gateway/` |
+| 百度/Amazon/OCR/第三方适配 | `integration-service/` |
+| 统一 API 路由、Token、Audience/JWKS | `gateway/`、`auth/`、`common-security/` |
+| 统一会话与账号/客户权限撤销 | `auth/`、`iam/`、`common-security/` |
+| 尾程订单、海外入仓计划、换标、库存、采购、本土卡车 | `lastleg-service/` |
+| 尾程订单控制、柜级预览与入仓计划转换 | `lastleg-service/`、`warehouse-overseas-service/` |
+| 海外入仓分页、FBA 预约、PDA 柜号签收与入仓 | `lastleg-service/` |
+| 海外仓排车查询、候选与智能预排 | `lastleg-service/` |
+| 海外排车执行、PDA 出库、派送与一件代发 | `lastleg-service/` |
+| 海外异常退回、库存恢复与客户回访 | `lastleg-service/`、`file/` |
+| 一件代发 SKU/箱唛与暂扣跨区协同 | `order/`、`firstleg/`、`common-event-contract/`、`lastleg-service/` |
+| 客户海外仓贴标、转运、废弃与退货换标 | `lastleg-service/` |
+| 海外仓 PDA 盘点、移库、托盘、换标与查询 | `lastleg-service/`、`warehouse-overseas-service/` |
+| 国内船节点向海外接柜门禁事件 | `firstleg/`、`common-event-contract/`、`lastleg-service/` |
+| 海外仓库目录、海外库位、海外托盘、资源锁 | 国内仓库目录归 `warehouse/`，海外资源归 `warehouse-overseas-service/` |
+| Lastleg 内部模块化与依赖基线 | `lastleg-service/` |
+| 自营领星采集、经营统计、SKU 日销量 | `lastleg-service/selfoperated/` 查询与采集编排；领星签名/分页/外部接口查 `integration-service/`，不因采集页面任务同时读取两服务 |
+| 跨客户同仓预约、预约跟进、到港日历 | `lastleg-service/inboundplan/`、`appointmentplanning/`；到港事实查 `firstleg/portschedule/` |
+| 车辆、司机证照、车次、外接预订、车队报价、出车记录 | `lastleg-service/fleet/`；先读 `lastleg-service/AGENTS.md` 对应入口，客户排车关联再沿 `dispatch/fleet/` 实际调用 |
+| PDF 标签、审计、业务事件直投 | `print/`、`audit-service/`、`common-event-contract/` |
 
-## 配置、数据库与验证入口
+## 公共模块快速索引
 
-- 服务本地配置在各模块 `src/main/resources/application.yml`；Nacos 环境配置集中在 `config/nacos/local/` 和 `config/nacos/cn/`。
-- 每个服务的文件日志和滚动策略也在自身 `application.yml`，统一通过 `LOG_PATH` 或 `LOGGING_*` 环境变量覆盖；容器宿主机挂载见 `deploy/docker-compose.yml`。
-- 子模块索引中 `controller/`、`service/`、`client/` 等包内简写均从该模块的 `src/main/java/com/baiyue/<domain>/` 起算；资源路径从模块根目录起算。
-- 表结构和增量脚本优先在目标模块 `src/main/resources/db/` 查找；每个服务只能访问自己的数据库，禁止跨库 Join。
-- `CREATE TABLE IF NOT EXISTS` 不会升级既有表；新增字段或索引时必须同时提供可重复执行的增量迁移，并在部署清单中写明执行顺序。
-- 服务间调用先找调用方 `client/`；跨区域数据只使用 `common-event-contract/` 和事件桥，不共享领域 Entity。
-- 本地环境切换看 `docs/数据库环境切换说明.md`、`scripts/local-env.ps1` 与 `config/nacos/local/`；接口契约优先读目标模块 `src/main/resources/openapi/` 和 Controller，回归入口在 `scripts/`，历史资质文件迁移使用 `scripts/migrate-local-qualification-file.ps1`。
-- 平台管理与头程履约补齐的本地数据库只读核验、SQL 清单和回归结果见 `docs/2026-07-31平台管理与头程履约补齐回归报告.md`。
-- IAM 授角、订单主数据、File、Gateway CORS 与文件日志的本轮结果见 `docs/2026-07-31-P0-P2问题修复回归报告.md`。
-- 本轮测试环境数据库增量统一从 `deploy/sql/2026-07-31一期回归测试环境增量迁移.sql` 执行，执行边界与核验方式见 `deploy/sql/README.md`。
-- CI 总控入口是 `Jenkinsfile`，负责按变更或勾选项并行调度 11 个独立服务 Job；单服务构建、镜像与部署逻辑在 `Jenkinsfile.service`。Job 名必须以模块名结尾，公共模块或 `deploy/` 变化会触发全部服务。
-- 从本目录运行全量校验：`mvn -DskipTests validate`、`mvn test`。单模块修改优先运行 `mvn -pl <module> -am test`。
-- `reports/`、`target/`、日志、上传文件和本地环境文件不属于源码，检索与提交时排除。
+| 关键词 | 模块与入口 |
+|---|---|
+| 公共依赖版本 | `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` |
 
-## 通用修改约束
+## 全量验收路由
 
-- Controller 只做协议转换，Service 负责编排，Repository/Mapper 负责持久化；不要跨层堆放业务逻辑。
-- 商户数据必须保留租户维度，并由服务端执行租户、访问域、数据范围和按钮权限校验。
-- 修改 SQL、DTO、事件或公共组件时同步检查所有生产者与消费者；优先保持兼容，不能兼容时写清迁移顺序。
-- 对外 HTTP JSON 中的 Java `Long/long` 统一输出字符串，请求同时接受字符串 ID；业务模块禁止重复添加局部 ID 转换器，OpenAPI 必须同步声明字符串契约。
-- 普通业务成功与失败统一使用 HTTP 200，并以响应体字符串 `code` 判断；`code == "200"` 才成功。网关/Servlet Security 的真实 401/403、协议与基础设施错误、Warehouse readiness 503、Audit 202 和 Event Bridge 内部鉴权边界除外；完整约定见 `docs/统一响应约定改造方案-HTTP200.md`。
-- 密码、令牌、第三方密钥和真实客户数据只能通过环境变量或配置中心密文注入。
+- 当前订单与客户、入库测量与计费、国内货柜履约、海外仓业务及财务统一进入全量验收；按本次链路读取对应业务域/专题文档，不以历史规划终点阻断跨服务联调或回归。
+- `auth`、`iam`、`warehouse`、`order`、`firstleg`、`file`、`finance`、`integration-service` 及出仓相关能力按各自模块契约协作；状态、权限、数据库和 OpenAPI 以当前实现及已确认契约为准。
 
-## 本地内部服务令牌
+## 国内头程与海外仓协同
 
-- `scripts/local-env.ps1` 是本地运行时的统一环境入口，Order、Warehouse、IAM 等相互调用的服务必须从同一套 `INTERNAL_SERVICE_TOKEN` 启动。
-- `config/nacos/local/baiyue-common.yml` 的本地默认令牌必须与该脚本一致；变更后执行 `scripts/publish-local-nacos-config.ps1` 发布并重启相关服务。
+- Auth 是唯一用户账号与 Token 签发方；目标为各端共用 Gateway 和 Redis 会话，保留 RS256/JWKS、客户隔离、权限撤销、PDA 仓绑定及服务身份校验。当前源码已移除旧海外会话验证与 Lastleg 安全投影，改为 Auth 权威会话校验；本地验证不等于测试环境部署验收。
+- 装柜、船节点、卸柜、暂扣、派送、费用与资金按统一通信契约的逐事件表直接投递。保留本地 Outbox、消费幂等、重试与失败处置，不携带用户 JWT；旧 Bridge 源码已退出聚合和发布清单，退役待清理；实际停机仍须替代链验证与授权，不得据源码状态认定已部署。
+- `lastleg-service` 不读取头程数据库，`warehouse-overseas-service` 不读取尾程订单库。共用测试 MySQL 实例不改变服务数据归属。准确路由、ACK、撤销矩阵和切换门槛只维护在新的两份主契约中。
+
+## 数据库访问与中文代码注释（所有服务及公共模块强制）
+
+- 本节适用于全部后端服务和公共模块；新增、修改的方法必须执行，触及的存量代码同步整改。登记本约束不代表存量代码已全部完成迁移和注释补齐。
+- 生产代码的关系型数据库读写统一经 MyBatis/MyBatis-Plus Mapper 执行；Controller、Service、定时任务、消费者、编号生成器和公共基础组件不得直接使用 `JdbcTemplate`、`NamedParameterJdbcTemplate`、原生 JDBC/Connection/Statement 或其他通道执行 SQL。仅改成 Repository 包装 JDBC 不算整改，SQL 必须进入 Mapper；无数据库职责的模块不得为满足本条新增数据库访问。
+- 正常业务数据库访问路径统一为 `Controller → Service → Repository → Mapper`，四层职责明确，不得省略 Repository，也不得由 Controller 直接调用 Repository/Mapper，或由 Service 直接调用 Mapper。定时任务、消费者等非 HTTP 入口从 Service 进入，同样经 Repository → Mapper 完成持久化访问。
+- Controller 负责请求接收、参数校验、入口权限和响应转换；Service 负责业务规则、编排及业务事务；Repository 负责领域数据访问封装、查询组合与持久化模型转换，对 Service 提供有业务含义的数据操作；Mapper 负责 SQL 执行及数据库记录映射。Repository 不承载业务状态流转，不直接用 JDBC 执行 SQL；Service 不继承 MyBatis-Plus `ServiceImpl` 等方式绕过 Repository。
+- 复杂查询、批量处理、原子计数、锁定读取、Outbox 和数据库监控查询同样经 Repository → Mapper，不以 SQL 特殊或实现方便为由跳层。公共模块需要数据库能力时，按现有模块边界定义 Repository/持久化接口，由所属服务的 Repository → Mapper 实现，禁止借此跨服务读库。
+- 迁移数据库操作须保留客户隔离条件、事务传播、行锁、幂等和并发语义；`LAST_INSERT_ID()` 等连接级操作必须在同一事务连接完成，并明确关闭相关读取缓存，不能仅机械搬移 SQL。Mapper 注册及扫描仍遵守下文统一规范。
+- 测试代码可用 `JdbcTemplate` 创建隔离测试表、准备数据及核对结果；被测生产路径仍必须调用实际 Mapper，不得把测试造数做法带入生产。数据库基线和迁移脚本按现有部署契约管理。
+- 每个手写方法及构造器均须添加简短中文注释，通常 1—3 行说明业务用途；接口方法和 Mapper 方法优先使用中文 Javadoc。覆盖方法同样须有简短中文说明，实现中的关键规则仍须就地注释；自动生成的方法不手工逐个补注释。
+- 核心业务、复杂 SQL、状态流转、资金与库存变更、权限隔离、事务、锁、幂等、并发、重试和补偿逻辑，须在关键代码前增加适量中文注释，解释业务规则、处理原因、约束边界及失败影响；不逐行翻译代码，不添加无信息量或与实现不符的注释。
+- 新增和修改的代码说明注释统一使用中文；必要的技术标识、协议名、类名可保留原文，第三方许可证和生成标记保持原样。修改方法时同步更新相关存量英文或过期说明；审查时同时核对 Controller → Service → Repository → Mapper 分层及中文方法、核心逻辑注释。
+
+## 契约、数据库与验证入口
+
+- 对外 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/test/`；服务日志、上传文件、`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`；脚本只读源码目录和指定指引，不访问 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` 只读核验最终船节点终态。
+- 这些脚本会创建、更新或最终停用测试数据；指定测试环境和服务后，本轮非破坏性写入复用一次授权，删除、重置、SQL、部署或发布仍逐项授权，并保存 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/头程到尾程/README.md` 指向的当前阶段文档读取，需求确认和联调报告仅在历史追溯或验收证据任务中读取
+- 国内货柜履约：`../docs/国内货柜履约/README.md`，报关规则变化再查 `../docs/国内货柜履约/报关资料与船期价格接入梳理.md`。规划、确认与验收材料按归档位置及文档角色判断，当前入口指定的有效规则仍按需核对，历史材料只用于追溯或证据任务
+- 海外仓业务：`../docs/海外仓业务/README.md`；统一入口 `gateway/`，尾程与入仓库存 `lastleg-service/`，海外仓储资源 `warehouse-overseas-service/`
+- 海外仓全流程：以正式 Controller、前端路由、权限、SQL 与跨区事件契约为范围依据；海外接柜、入仓、库存、库内服务、排车、出库、派送、一件代发、异常退回和客户回访进入 `lastleg-service/`，国内 SKU/箱唛及暂扣协同进入 `order/`、`firstleg/`、`common-event-contract/`
+- 财务：`../docs/财务管理/README.md` 中已确认的范围、对象、状态和接口约束
+
+全量验收需要证据时再读取对应阶段报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。

Jenkinsfile

@@ -1,6 +1,6 @@
 def serviceModules = [
-    'gateway', 'auth', 'iam', 'firstleg', 'order', 'warehouse', 'file', 'print',
-    'integration-service', 'event-bridge-service', 'audit-service'
+    'gateway', 'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
+    'integration-service', 'lastleg-service', 'warehouse-overseas-service', 'audit-service'
 ]
 
 def serviceCheckboxes = [
@@ -8,26 +8,134 @@ def serviceCheckboxes = [
     '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',
-    'event-bridge-service': 'SERVICE_EVENT_BRIDGE',
+    'lastleg-service': 'SERVICE_LASTLEG',
+    'warehouse-overseas-service': 'SERVICE_WAREHOUSE_OVERSEAS',
     'audit-service': 'SERVICE_AUDIT'
 ]
 
-def commonPaths = [
-    'pom.xml', 'platform-bom/', 'common-core/', 'common-web/', 'common-security/',
-    'common-openapi/', 'common-audit/', 'common-event-contract/', 'Jenkinsfile',
-    'Jenkinsfile.service', 'deploy/'
+def fullRebuildPaths = [
+    'pom.xml', 'platform-bom/', 'common-core/', 'deploy/docker/',
+    'deploy/docker-compose.yml', 'deploy/service-map.yml', 'config/nacos/test/', 'deploy/scripts/', 'Jenkinsfile'
 ]
 
+def commonPathServices = [
+    'common-web/': [
+        'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
+        'integration-service', 'lastleg-service', 'warehouse-overseas-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',
+        'audit-service'
+    ],
+    'common-audit/': [
+        'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file',
+        'warehouse-overseas-service', 'audit-service'
+    ],
+    'common-event-contract/': [
+        'firstleg', 'finance', 'lastleg-service'
+    ],
+    'deploy/docker-compose.audit.yml': ['audit-service'],
+]
+
+def databaseMigrationPaths = ['deploy/sql/']
+// 暂停数据库结构只读门禁；保留实现，完成 Credentials 配置后改为 true。
+def databaseSchemaContractEnabled = false
+
 def downstreamResults = [:]
+def downstreamBuildUrls = [:]
+def downstreamBuildNumbers = [:]
+
+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':
+            return 'test'
+        case 'backend-java-prod':
+            return 'production'
+        default:
+            return null
+    }
+}
+
+def fixedDownstreamJobPrefixForJob(String jobBaseName) {
+    switch (jobBaseName) {
+        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 {
     // 总控流水线只识别变更并调度独立的服务 Job；实际 Maven、镜像和部署在 Jenkinsfile.service 中完成。
-    agent any
+    agent none
 
     options {
         disableConcurrentBuilds()
@@ -39,48 +147,64 @@ pipeline {
         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_AUTH', defaultValue: false, description: '统一认证服务（auth）')
-        booleanParam(name: 'SERVICE_IAM', defaultValue: false, description: '租户与权限服务（iam）')
+        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_EVENT_BRIDGE', defaultValue: false, description: '跨区域事件桥（event-bridge-service）')
+        booleanParam(name: 'SERVICE_LASTLEG', defaultValue: false, description: '海外尾程与入仓服务（lastleg-service）')
+        booleanParam(name: 'SERVICE_WAREHOUSE_OVERSEAS', defaultValue: false, description: '海外仓资源服务（warehouse-overseas-service）')
         booleanParam(name: 'SERVICE_AUDIT', defaultValue: false, description: '审计服务（audit-service）')
-        choice(name: 'ENVIRONMENT', choices: ['test', 'staging', 'production'], description: '部署环境')
+        choice(name: 'ENVIRONMENT', choices: environmentChoicesForJob(env.JOB_BASE_NAME), description: '部署环境')
         booleanParam(name: 'DEPLOY', defaultValue: false, description: '各服务构建成功后是否独立部署')
-        booleanParam(name: 'INITIALIZE_TEST_DATABASE', defaultValue: false, description: '仅 test：调度服务前幂等初始化测试数据库')
-        booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试；生产构建不建议勾选')
-        string(name: 'IMAGE_REPOSITORY', defaultValue: '8.163.30.128:10082/java-project/baiyue-firstleg', description: '预发布/生产镜像仓库地址；test 环境自动使用本机镜像')
-        string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'docker.m.daocloud.io/library/eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
-        string(name: 'DOWNSTREAM_JOB_PREFIX', defaultValue: 'baiyue-firstleg-', description: '单服务 Jenkins Job 名称前缀，例如 baiyue-firstleg-auth')
+        booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试执行（仍编译测试源码）')
+        string(name: 'IMAGE_REPOSITORY', defaultValue: '', description: '必须填写已核实的共享镜像仓库地址 host[:port]/owner/image')
+        string(name: 'DOCKER_BASE_IMAGE', defaultValue: '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 requestedRepository
-                    if (params.ENVIRONMENT == 'test') {
-                        requestedRepository = 'baiyue-firstleg-test'
-                        echo '测试环境使用 Jenkins 节点本机镜像，不登录、不推送远程 Registry'
-                    } else {
-                        requestedRepository = params.IMAGE_REPOSITORY?.trim()
-                        if (!requestedRepository || requestedRepository == 'registry.example.com/your-group/baiyue-firstleg') {
-                            error('预发布/生产环境必须填写真实镜像仓库地址')
-                        }
-                        if (requestedRepository.contains('://') || !requestedRepository.contains('/')) {
-                            error('IMAGE_REPOSITORY 格式错误：请填写 host[:port]/owner/image，不要包含 http:// 或 https://')
-                        }
+                    String 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) {
+                        error('部署环境和下游前缀必须与当前 Job 固定映射一致')
+                    }
+                    env.RESOLVED_ENVIRONMENT = resolvedEnvironment
+                    echo "Job ${env.JOB_BASE_NAME} 使用部署环境: ${env.RESOLVED_ENVIRONMENT}"
+
+                    // 先记录当前提交，使后续生产校验失败时通知仍能定位版本。
+                    env.SOURCE_COMMIT = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
+                    env.IMAGE_TAG = sh(script: 'git rev-parse --short=12 HEAD', returnStdout: true).trim()
+
+
+
+                    String requestedRepository = params.IMAGE_REPOSITORY?.trim()
+                    if (!requestedRepository) {
+                        error('必须填写真实镜像仓库地址')
+                    }
+                    if (requestedRepository.tokenize('/')[0] ==~ /(?i)(?:[a-z0-9-]+\.)*example\.(?:com|net|org)(?::[0-9]+)?/) {
+                        error('IMAGE_REPOSITORY 不能使用 example 示例域名，请填写已核实的镜像仓库地址')
+                    }
+                    if (requestedRepository.contains('://') || !requestedRepository.contains('/')) {
+                        error('IMAGE_REPOSITORY 格式错误：请填写 host[:port]/owner/image，不要包含 http:// 或 https://')
+                    }
+                    echo "${env.RESOLVED_ENVIRONMENT} 环境使用共享镜像仓库: ${requestedRepository}"
                     env.RESOLVED_IMAGE_REPOSITORY = requestedRepository
 
-                    String jobPrefix = params.DOWNSTREAM_JOB_PREFIX?.trim()
-                    if (!jobPrefix) {
-                        error('DOWNSTREAM_JOB_PREFIX 不能为空')
-                    }
-                    env.RESOLVED_JOB_PREFIX = jobPrefix
+                    env.RESOLVED_JOB_PREFIX = resolvedJobPrefix
+                    env.DATABASE_CHANGE_DETECTED = 'false'
+
 
                     List selected = []
                     if (params.BUILD_MODE == 'ALL') {
@@ -93,18 +217,46 @@ pipeline {
                             error('SELECT 模式至少需要勾选一个服务')
                         }
                     } else {
-                        String base = env.GIT_PREVIOUS_SUCCESSFUL_COMMIT?.trim()
+                        def autoState = previousAutoBuildState(currentBuild.previousBuild, serviceModules)
+                        String base = autoState?.commit?.trim()
+                        List retryServices = autoState?.failedServices ?: []
+                        if (!base) {
+                            // 首次启用或旧构建记录已淘汰时，只比较当前提交的直接父提交。
+                            // 需要初始化全部服务时应显式使用 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) }
+                            boolean databaseChanged = changed.any { path ->
+                                databaseMigrationPaths.any { prefix -> path.startsWith(prefix) }
                             }
-                            selected = commonChanged ? serviceModules : serviceModules.findAll { module ->
-                                changed.any { it == module || it.startsWith("${module}/") }
+                            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(',') ?: '无'}"
                         }
                     }
 
@@ -114,39 +266,90 @@ pipeline {
                     }
 
                     selected = selected.unique()
+
                     env.SELECTED_SERVICES = selected.join(',')
                     env.NO_SERVICE_CHANGE = selected ? 'false' : 'true'
                     if (!selected) {
-                        currentBuild.description = '没有需要构建的业务服务'
+                        currentBuild.description = params.BUILD_MODE == 'AUTO'
+                            ? "AUTO ${env.IMAGE_TAG} | RESULTS"
+                            : (env.DATABASE_CHANGE_DETECTED == 'true'
+                                ? '仅数据库迁移变更 | 需单独审核执行'
+                                : '没有需要构建的业务服务')
                     } else {
-                        env.SOURCE_COMMIT = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
-                        env.IMAGE_TAG = sh(script: 'git rev-parse --short=12 HEAD', returnStdout: true).trim()
-                        currentBuild.description = "${env.SELECTED_SERVICES} | ${env.IMAGE_TAG}"
+                        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('生产环境部署确认（仅 production 执行）') {
+        stage('Gateway 路由静态门禁') {
             when {
-                allOf {
-                    expression { params.DEPLOY && params.ENVIRONMENT == 'production' && env.NO_SERVICE_CHANGE != 'true' }
-                }
+                expression { env.NO_SERVICE_CHANGE != 'true' }
             }
+            agent { label 'java-builder' }
             steps {
-                input message: "确认将 ${env.SELECTED_SERVICES} 的镜像 ${env.IMAGE_TAG} 分别部署到生产环境？", ok: '确认部署'
+                sh 'node --test scripts/gateway-route-contract.test.mjs'
             }
         }
 
-        stage('测试数据库初始化（可选）') {
+        stage('数据库结构只读门禁') {
             when {
-                allOf {
-                    expression { params.ENVIRONMENT == 'test' && params.INITIALIZE_TEST_DATABASE }
+                expression { databaseSchemaContractEnabled }
+            }
+            agent { label 'java-builder' }
+            steps {
+                script {
+                    String credentialId = "firstleg-${env.RESOLVED_ENVIRONMENT}-schema-readonly"
+                    withCredentials([file(credentialsId: credentialId, variable: 'SCHEMA_CHECK_ENV_FILE')]) {
+                        sh '''
+                            set -eu
+                            set -a
+                            . "$SCHEMA_CHECK_ENV_FILE"
+                            set +a
+                            test "${SCHEMA_CHECK_READ_ONLY:-}" = "true"
+                            node scripts/database-schema-contract.mjs --region BOTH
+                        '''
+                    }
                 }
             }
+        }
+
+        stage('统一 Maven 测试门禁') {
+            when {
+                expression { env.NO_SERVICE_CHANGE != 'true' && !params.SKIP_TESTS }
+            }
+            agent { label 'java-builder' }
+            tools { maven 'maven-3.8.8' }
             steps {
-                sh 'sh deploy/scripts/initialize-test-databases.sh'
+                script {
+                    String selectedModules = env.SELECTED_SERVICES.split(',')
+                        .collect { it.trim() }
+                        .findAll { it }
+                        .join(',')
+                    echo "统一测试本次选中的服务及其公共依赖: ${selectedModules}"
+                    lock(resource: 'firstleg-test-maven') {
+                        timeout(time: 50, unit: 'MINUTES') {
+                            sh """
+                                test \"\$(git rev-parse HEAD)\" = \"${env.SOURCE_COMMIT}\"
+                                find . -type f -path '*/target/surefire-reports/TEST-*.xml' -delete
+                                sh deploy/scripts/run-ci-maven.sh --settings deploy/maven/settings-ci.xml --batch-mode --errors -pl ${selectedModules} -am test
+                            """
+                        }
+                    }
+                    echo "统一测试门禁通过: ${env.SOURCE_COMMIT}；下游单服务任务不再重复执行测试"
+                }
+            }
+            post {
+                always {
+                    junit allowEmptyResults: true, testResults: '**/target/surefire-reports/TEST-*.xml'
+                }
             }
         }
 
@@ -167,14 +370,17 @@ pipeline {
                                 parameters: [
                                     string(name: 'SOURCE_COMMIT', value: env.SOURCE_COMMIT),
                                     string(name: 'IMAGE_TAG', value: env.IMAGE_TAG),
-                                    string(name: 'ENVIRONMENT', value: params.ENVIRONMENT),
+                                    string(name: 'ENVIRONMENT', value: env.RESOLVED_ENVIRONMENT),
                                     booleanParam(name: 'DEPLOY', value: params.DEPLOY),
-                                    booleanParam(name: 'SKIP_TESTS', value: params.SKIP_TESTS),
+                                    // 总控已完成统一测试，或用户已明确选择跳过；下游仅负责编译、打包和部署。
+                                    booleanParam(name: 'SKIP_TESTS', value: true),
                                     string(name: 'IMAGE_REPOSITORY', value: env.RESOLVED_IMAGE_REPOSITORY),
                                     string(name: 'DOCKER_BASE_IMAGE', value: params.DOCKER_BASE_IMAGE)
                                 ]
                             )
                             downstreamResults[service] = downstreamBuild.result ?: 'UNKNOWN'
+                            downstreamBuildUrls[service] = downstreamBuild.absoluteUrl ?: ''
+                            downstreamBuildNumbers[service] = downstreamBuild.number?.toString() ?: ''
                             echo "${service} 执行结果: ${downstreamResults[service]} (${downstreamBuild.absoluteUrl})"
                         }
                     }
@@ -191,7 +397,9 @@ pipeline {
                         .collect { service, result -> "${service}=${result}" }
                     String summary = downstreamResults.collect { service, result -> "${service}=${result}" }.join(', ')
                     echo "单服务执行汇总: ${summary}"
-                    currentBuild.description = "${env.IMAGE_TAG} | ${summary}"
+                    currentBuild.description = params.BUILD_MODE == 'AUTO'
+                        ? "AUTO ${env.IMAGE_TAG} | RESULTS ${summary}"
+                        : "${env.IMAGE_TAG} | ${summary}"
                     if (failed) {
                         unstable("部分服务执行失败，但其他服务已独立完成：${failed.join(', ')}")
                     }
@@ -200,7 +408,4 @@ pipeline {
         }
     }
 
-    post {
-        always { cleanWs(deleteDirs: true, notFailBuild: true) }
-    }
 }

Jenkinsfile.service

@@ -1,6 +1,6 @@
 def serviceModules = [
-    'gateway', 'auth', 'iam', 'firstleg', 'order', 'warehouse', 'file', 'print',
-    'integration-service', 'event-bridge-service', 'audit-service'
+    'gateway', 'auth', 'iam', 'firstleg', 'finance', 'order', 'warehouse', 'file', 'print',
+    'integration-service', 'lastleg-service', 'warehouse-overseas-service', 'audit-service'
 ]
 
 def serviceJars = [
@@ -8,22 +8,32 @@ def serviceJars = [
     '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',
-    'event-bridge-service': 'event-bridge-service/target/event-bridge-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',
     'audit-service': 'audit-service/target/audit-service-1.0.0-SNAPSHOT.jar'
 ]
 
-pipeline {
-    // 每个 Jenkins 子 Job 使用自己的 workspace，因此不同服务可以并行执行 mvn clean。
-    agent any
-
-    tools {
-        maven 'maven-3.8.8'
+def fixedEnvironmentForServiceJob(String jobBaseName) {
+    if (jobBaseName?.startsWith('baiyue-firstleg-prod-')) return 'production'
+    if (jobBaseName?.startsWith('baiyue-firstleg-') && !jobBaseName.startsWith('baiyue-firstleg-dev-') && !jobBaseName.startsWith('baiyue-firstleg-prod-')) {
+        return 'test'
     }
+    return null
+}
+
+def environmentChoicesForServiceJob(String jobBaseName) {
+    return [fixedEnvironmentForServiceJob(jobBaseName) ?: 'test']
+}
+
+pipeline {
+    // 构建在任意 java-builder 节点执行，部署再回到目标环境节点。
+    agent none
 
     options {
         skipDefaultCheckout(true)
@@ -35,110 +45,152 @@ pipeline {
     parameters {
         string(name: 'SOURCE_COMMIT', defaultValue: '', description: '必须构建的 Git commit；通常由总控 Job 传入')
         string(name: 'IMAGE_TAG', defaultValue: '', description: '不可变镜像标签；通常使用 Git commit 前 12 位')
-        choice(name: 'ENVIRONMENT', choices: ['test', 'staging', 'production'], description: '部署环境')
+        choice(name: 'ENVIRONMENT', choices: environmentChoicesForServiceJob(env.JOB_BASE_NAME), description: '由当前单服务 Job 固定的部署环境')
+        booleanParam(name: 'ALLOW_SAME_CONTRACT_ROLLBACK', defaultValue: false, description: '仅确认相同协议与Schema时允许回滚；架构切换保持关闭')
         booleanParam(name: 'DEPLOY', defaultValue: false, description: '构建成功后是否部署本服务')
         booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试')
-        string(name: 'IMAGE_REPOSITORY', defaultValue: 'baiyue-firstleg-test', description: '镜像仓库基础路径，不包含服务名和标签')
-        string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'docker.m.daocloud.io/library/eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
+        string(name: 'IMAGE_REPOSITORY', defaultValue: '', description: '必须填写已核实的共享镜像仓库基础路径，不包含服务名和标签')
+        string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
     }
 
     environment {
-        REGISTRY_CREDENTIALS = 'gitea-test-token'
-        MAVEN_SETTINGS = 'deploy/maven/settings-cn.xml'
-        MAVEN_OPTS = '-Dfile.encoding=UTF-8 -Dmaven.wagon.http.retryHandler.count=3'
+        REGISTRY_CREDENTIALS = 'gitea-registry-token'
+        MAVEN_SETTINGS = 'deploy/maven/settings-ci.xml'
     }
 
     stages {
-        stage('校验参数并检出指定提交') {
-            steps {
-                checkout scm
+        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()
+                        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 (!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 (!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 不能为空且不能包含 http:// 或 https://')
-                    }
-                    if (params.ENVIRONMENT != 'test' && !imageRepository.contains('/')) {
-                        error('预发布/生产环境 IMAGE_REPOSITORY 必须使用 host[:port]/owner/image 格式')
-                    }
+                            if (!serviceModules.contains(service)) {
+                                error("无法从 Job 名称 ${env.JOB_BASE_NAME} 识别服务；名称必须以以下服务之一结尾: ${serviceModules.join(', ')}")
+                            }
+                            if (!resolvedEnvironment) {
+                                error("未配置单服务 Job ${env.JOB_BASE_NAME} 的固定部署环境，拒绝继续")
+                            }
+                            if (params.ENVIRONMENT != resolvedEnvironment) {
+                                error('部署环境必须与当前单服务 Job 固定映射一致')
+                            }
+                            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.tokenize('/')[0] ==~ /(?i)(?:[a-z0-9-]+\.)*example\.(?:com|net|org)(?::[0-9]+)?/) {
+                                error('IMAGE_REPOSITORY 不能使用 example 示例域名，请填写已核实的镜像仓库地址')
+                            }
+                            if (!imageRepository.contains('/')) {
+                                error('IMAGE_REPOSITORY 必须使用 host[:port]/owner/image 格式')
+                            }
 
-                    env.RESOLVED_SERVICE = service
-                    env.RESOLVED_SOURCE_COMMIT = sourceCommit
-                    env.RESOLVED_IMAGE_TAG = imageTag
-                    env.RESOLVED_IMAGE_REPOSITORY = imageRepository
+                            env.RESOLVED_SERVICE = service
+                            env.RESOLVED_ENVIRONMENT = resolvedEnvironment
+                            env.RESOLVED_SOURCE_COMMIT = sourceCommit
+                            env.RESOLVED_IMAGE_TAG = imageTag
+                            env.RESOLVED_IMAGE_REPOSITORY = imageRepository
+
+
+                        }
+
+                        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}")"
+                            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}"
+                        }
+                    }
                 }
 
-                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}")"
-                '''
+                stage('Maven 测试与打包') {
+                    steps {
+                        script {
+                            boolean coordinatorPinnedCommit = params.SOURCE_COMMIT?.trim() as boolean
 
-                script {
-                    currentBuild.description = "${env.RESOLVED_SERVICE} | ${env.RESOLVED_IMAGE_TAG} | ${params.ENVIRONMENT}"
-                    echo "独立构建服务: ${env.RESOLVED_SERVICE}，提交: ${env.RESOLVED_SOURCE_COMMIT}"
+                            boolean skipTestExecution = params.SKIP_TESTS
+                            String testOption = skipTestExecution ? '-DskipTests' : ''
+                            if (params.SKIP_TESTS && coordinatorPinnedCommit) {
+                                echo "总控已处理提交 ${env.RESOLVED_SOURCE_COMMIT} 的测试门禁，本单服务仅编译测试源码并打包"
+                            }
+                            lock(resource: 'firstleg-test-maven') {
+                                timeout(time: 50, unit: 'MINUTES') {
+                                    sh "sh deploy/scripts/run-ci-maven.sh --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('Maven 测试与打包') {
-            steps {
-                script {
-                    String testOption = params.SKIP_TESTS ? '-DskipTests' : ''
-                    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'"
 
-        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]
-                    sh "mkdir -p '${contextDir}' && cp -f '${jar}' '${contextDir}/app.jar'"
-                    sh "docker build -f deploy/docker/Dockerfile --build-arg BASE_IMAGE=${params.DOCKER_BASE_IMAGE} --build-arg JAR_FILE=app.jar -t ${image} '${contextDir}'"
-
-                    if (params.ENVIRONMENT == 'test') {
-                        echo "测试镜像已保存在当前 Docker 节点：${image}"
-                    } else {
-                        String registryHost = env.RESOLVED_IMAGE_REPOSITORY.tokenize('/')[0]
-                        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 push ${image}"
-                            } finally {
-                                sh "docker logout ${registryHost} || true"
+                            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
                             }
                         }
                     }
@@ -146,25 +198,61 @@ pipeline {
             }
         }
 
-        stage('部署单个服务') {
-            when { expression { params.DEPLOY } }
+        stage('部署 TEST') {
+            when { expression { params.DEPLOY && env.RESOLVED_ENVIRONMENT == 'test' } }
+            agent none
             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}' '${env.RESOLVED_IMAGE_REPOSITORY}' '${env.RESOLVED_IMAGE_TAG}' '${env.RESOLVED_SERVICE}' \"\$DEPLOY_ENV_FILE\""
+                    lock(resource: "firstleg-test-${env.RESOLVED_SERVICE}-deploy", inversePrecedence: true) {
+                      node('java-test') {
+                        deleteDir()
+                        unstash 'deployment-files'
+                        withCredentials([
+                            file(credentialsId: 'firstleg-test-env', variable: 'DEPLOY_ENV_FILE'),
+                            usernamePassword(credentialsId: env.REGISTRY_CREDENTIALS, usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD')
+                        ]) {
+                            withEnv(['TARGET_IS_LOCAL=true', "ALLOW_SAME_CONTRACT_ROLLBACK=${params.ALLOW_SAME_CONTRACT_ROLLBACK}"]) {
+                                sh 'sh deploy/scripts/deploy-built-service.sh test "$RESOLVED_IMAGE_REPOSITORY" "$RESOLVED_IMAGE_TAG" "$RESOLVED_SERVICE" "$DEPLOY_ENV_FILE"'
+                            }
+                        }
+                      }
                     }
                 }
             }
         }
+
+        stage('部署临时灰度') {
+            when { expression { params.DEPLOY && env.RESOLVED_ENVIRONMENT == 'production' } }
+            agent none
+            steps {
+                script {
+                    lock(resource: "firstleg-production-${env.RESOLVED_SERVICE}-deploy", inversePrecedence: true) {
+                        node('java-builder') {
+                            deleteDir()
+                            unstash 'deployment-files'
+                            withCredentials([
+                                file(credentialsId: 'firstleg-production-env', 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_IS_LOCAL=false', 'TARGET_SSH_TARGET=' + env.TARGET_SSH_USER + '@' + env.TARGET_SSH_HOST,
+                                    "ALLOW_SAME_CONTRACT_ROLLBACK=${params.ALLOW_SAME_CONTRACT_ROLLBACK}"]) {
+                                    sh 'sh deploy/scripts/deploy-built-service.sh production "$RESOLVED_IMAGE_REPOSITORY" "$RESOLVED_IMAGE_TAG" "$RESOLVED_SERVICE" "$DEPLOY_ENV_FILE"'
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
     }
 
     post {
         success {
             echo "${env.RESOLVED_SERVICE} 已独立完成构建${params.DEPLOY ? '和部署' : ''}"
         }
-        always {
-            cleanWs(deleteDirs: true, notFailBuild: true)
-        }
     }
 }

README.md

@@ -1,35 +1,56 @@
 # 柏悦头程平台
 
-本仓库承载国内头程业务，负责统一登录、租户、用户、角色、菜单、按钮权限、订单、国内仓储、头程履约以及国内公共能力。尾程业务不进入本仓库，通过版本化跨区域事件与尾程仓库协作。
+本仓库承载头程与海外仓后端。当前只有一个测试环境，目标为所有服务同机部署，统一 Gateway、Auth 会话及 Nacos 命名空间，业务服务继续按职责拥有独立 Schema。部署与切换见[测试环境单机部署与配置契约](../docs/测试环境单机部署与配置契约.md)，路由、认证和事件投递见[统一认证与服务通信契约](../docs/统一认证与服务通信契约.md)。
+
+根 POM 与发布清单已收敛为 20 个模块、13 个服务；本地配置变化尚未经过真实 TEST 部署验收。`gateway-overseas/` 与 `event-bridge-service/` 为退役待清理源码，已不参与当前聚合构建和发布。
+
+> 当前主体模型：业务单租户，产品只包含“平台—客户”两级。现有 `tenant_id > 0`、`tenantId` 和 `Tenant*` 是历史兼容命名，当前承载客户归属与隔离；`tenant_id = 0` 是平台账号、平台 RBAC 和平台公共主数据的技术作用域，不是可管理租户。平台公共仓库、往来单位、快递公司、托盘、库位等归属 `0`，客户订单、文件和费用归属客户 ID。未经过独立迁移设计，不得新增真实租户层或把现有客户隔离字段改义为上级租户。
 
 ## 模块
 
+- `gateway`：四端统一 API 入口。
+- `finance`：财务账单、费用、充值、授信与资金核销。
 - `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`。
+- `lastleg-service`、`warehouse-overseas-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`。
 
-国内 Nacos 配置位于 `config/nacos/cn`。数据库、Redis、Nacos 和 RocketMQ 的生产密码必须通过环境变量或配置中心密文注入，禁止提交明文密码。
+唯一发布配置为 `deploy/docker-compose.yml`、`deploy/env/.env.test.example` 和 `config/nacos/test/`；所有保留服务共用实际 Namespace ID、Auth/Redis 会话和单机内部网络，各服务 Schema 保留。往来单位由 `warehouse-service` 承载并保存到 `baiyue_warehouse.wh_partner`。发布、健康检查和失败恢复见 `deploy/TEST单机部署执行清单.md`。真实凭据不得提交；本地编译不代表另有开发环境。
+
+## 容器日志
+
+所有服务只向标准输出和标准错误写日志，不在容器内生成应用日志文件，也不把应用日志目录挂载到宿主机。统一业务及基础设施 Compose 默认使用宝塔可见的 Docker `json-file` 日志驱动，并设置强制轮转；仍可通过 `docker logs` 排查。文件服务的 `/data/files` 是业务文件目录，不属于日志目录，必须继续持久化。
+
+单容器默认保留 `50m × 3`，可在 TEST 部署变量中覆盖：
+
+| 环境 | `DOCKER_LOG_DRIVER` | `DOCKER_LOG_MAX_SIZE` | `DOCKER_LOG_MAX_FILE` | 长期留存 |
+|---|---|---:|---:|---|
+| 测试 | `json-file` | `50m` | `3` | 不要求 |
+
+当前优先保证宝塔可观测性，因此不启用 `json-file` 压缩或非阻塞投递，避免面板无法读取轮转文件或在日志压力下静默丢弃。接入集中日志系统后，可通过 `DOCKER_LOG_DRIVER` 切换驱动，并由集中系统承担长期检索与留存。
+
+调整日志策略后必须重新创建容器；只重启既有容器不会改变其日志驱动。历史 `/data/logs/baiyue-firstleg` 文件和旧容器日志不自动删除，确认无需保留后再单独清理。
 
 ## 网关跨域配置
 
-本地默认允许商户端和后台端从 `localhost/127.0.0.1` 的 `5173/5174` 端口访问网关。部署到测试或生产环境时，必须通过 `CORS_ALLOWED_ORIGINS` 配置两个前端的明确地址，多个地址用英文逗号分隔，例如：
+本地默认允许商户端和后台端从 `localhost/127.0.0.1` 的 `5173/5174` 端口访问网关。部署到 TEST 时，必须通过 `CORS_ALLOWED_ORIGINS` 配置两个前端的明确地址，多个地址用英文逗号分隔，例如：
 
 ```text
 CORS_ALLOWED_ORIGINS=https://merchant.example.com,https://admin.example.com
@@ -39,4 +60,6 @@ CORS_ALLOWED_ORIGINS=https://merchant.example.com,https://admin.example.com
 
 ## 仓库边界
 
-详细规则见 `docs/repository-boundary.md`。本仓不得引入尾程源码，不允许跨区域共享数据库、Redis 或 Nacos，也不允许通过公网直接调用对方内部服务。
+仓库结构入口见 `docs/头程项目目录结构与服务说明.md`。服务保持数据归属、禁止跨库直接查询其他服务业务表；同机可共用 MySQL 实例、Redis 和 Nacos。内部调用不通过公网，部署及通信规则以新的两份主契约为准。
+
+前端 phase4 定向离线检查入口为 `apps/admin-web/scripts/phase4-test-frontend-acceptance.mjs`（工作区相对路径），由 Admin 的 `pnpm test:phase4:test` 使用 `vitest.phase4-test.config.ts` 执行；不替代真实HTTP、页面或PDA验收。

audit-service/AGENTS.md

@@ -1,7 +1,13 @@
 # Audit Service 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
+- Mapper 只由 `BaiyueAuditApplication.java` 对 `com.baiyue.audit` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。
 - 负责接收 `common-audit` 产生的审计事件并持久化到 `baiyue_audit`。
 - 审计注解、切面、脱敏和发送策略在 `common-audit/`；本服务不复制业务服务的审计采集逻辑。
 
@@ -11,11 +17,12 @@
 |---|---|
 | 应用入口 | `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` |
+| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/test/audit-service.yml` |
 
 ## 修改与验证
 
@@ -23,5 +30,6 @@
 - `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；客户账号不得访问平台查询接口。
 - 审计链路故障不得阻塞核心交易；保留幂等、超时、容量和留存策略的演进空间。
-- 当前没有专属自动化测试；从父目录运行 `mvn -pl audit-service -am test`，并按改动验证接收和持久化结果。
+- 自动化测试位于 `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>
@@ -44,6 +53,10 @@
             <groupId>com.alibaba.cloud</groupId>
             <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-test</artifactId>

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

@@ -1,13 +1,17 @@
 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;
 
 /**
  * 审计微服务启动入口，初始化 Spring Boot 应用并扫描审计日志 Mapper。
  */
-@MapperScan("com.baiyue.audit.mapper")
+@MapperScan(basePackages = "com.baiyue.audit", annotationClass = Mapper.class)
+@Import(MybatisPlusConfiguration.class)
 @SpringBootApplication
 public class BaiyueAuditApplication {
 

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,8 +29,13 @@ 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。"
@@ -35,9 +44,25 @@ public class AuditIngestController {
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "202", description = "Event accepted and stored / 事件已接收并存储"),
     })
     @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

@@ -1,6 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -3,38 +3,40 @@ server:
 
 spring:
   profiles:
-    active: ${SPRING_PROFILES_ACTIVE:dev}
+    active: ${SPRING_PROFILES_ACTIVE:test}
   application:
     name: audit-service
   config:
     import:
-      - optional:nacos:baiyue-common.yml?group=BAIYUE&refreshEnabled=true
-      - optional:nacos:${spring.application.name}.yml?group=BAIYUE&refreshEnabled=true
+      - nacos:baiyue-common.yml?group=${NACOS_GROUP:BAIYUE}&refreshEnabled=true
+      - nacos:${spring.application.name}.yml?group=${NACOS_GROUP:BAIYUE}&refreshEnabled=true
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
-      username: ${NACOS_USERNAME:nacos}
-      password: ${NACOS_PASSWORD:nacos}
+      server-addr: ${NACOS_SERVER_ADDR}
+      username: ${NACOS_USERNAME}
+      password: ${NACOS_PASSWORD}
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
+        server-addr: ${NACOS_SERVER_ADDR}
         enabled: ${NACOS_DISCOVERY_ENABLED:true}
         register-enabled: ${NACOS_REGISTER_ENABLED:true}
         group: ${NACOS_GROUP:BAIYUE}
-        namespace: ${NACOS_NAMESPACE:public}
+        namespace: ${NACOS_NAMESPACE}
       config:
-        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
-        namespace: ${NACOS_NAMESPACE:public}
+        server-addr: ${NACOS_SERVER_ADDR}
+        namespace: ${NACOS_NAMESPACE}
 
 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
-
-logging:
-  file:
-    name: "${LOGGING_FILE_NAME:${LOG_PATH:./logs}/${spring.application.name}.log}"
-  logback:
-    rollingpolicy:
-      file-name-pattern: "${LOGGING_ROLLING_FILE_NAME_PATTERN:${LOG_PATH:./logs}/${spring.application.name}.%d{yyyy-MM-dd}.%i.log.gz}"
-      max-file-size: "${LOGGING_ROLLING_MAX_FILE_SIZE:100MB}"
-      max-history: "${LOGGING_ROLLING_MAX_HISTORY:30}"
-      total-size-cap: "${LOGGING_ROLLING_TOTAL_SIZE_CAP:5GB}"
-      clean-history-on-start: "${LOGGING_ROLLING_CLEAN_HISTORY_ON_START:false}"

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

@@ -0,0 +1,51 @@
+package com.baiyue.audit;
+
+import com.baiyue.common.web.CommonWebAutoConfiguration;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.actuate.autoconfigure.endpoint.EndpointAutoConfiguration;
+import org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointAutoConfiguration;
+import org.springframework.boot.actuate.autoconfigure.web.server.ManagementContextAutoConfiguration;
+import org.springframework.boot.actuate.autoconfigure.health.HealthEndpointAutoConfiguration;
+import org.springframework.boot.actuate.health.Health;
+import org.springframework.boot.actuate.health.HealthIndicator;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.autoconfigure.http.HttpMessageConvertersAutoConfiguration;
+import org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration;
+import org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration;
+import org.springframework.boot.autoconfigure.web.servlet.DispatcherServletAutoConfiguration;
+import org.springframework.boot.test.context.runner.WebApplicationContextRunner;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+class AuditHealthEndpointTest {
+    private final WebApplicationContextRunner context = new WebApplicationContextRunner()
+        .withConfiguration(AutoConfigurations.of(
+            JacksonAutoConfiguration.class, HttpMessageConvertersAutoConfiguration.class,
+            WebMvcAutoConfiguration.class, DispatcherServletAutoConfiguration.class, EndpointAutoConfiguration.class,
+            HealthEndpointAutoConfiguration.class, WebEndpointAutoConfiguration.class,
+            ManagementContextAutoConfiguration.class, CommonWebAutoConfiguration.class))
+        .withPropertyValues("management.endpoints.web.exposure.include=health");
+
+    @Test
+    void actuatorHealthReturnsUpInsteadOfBusinessResourceNotFound() {
+        context.withBean("dependencyHealthIndicator", HealthIndicator.class, () -> () -> Health.up().build())
+            .run(application -> MockMvcBuilders.webAppContextSetup(application).build()
+                .perform(get("/actuator/health"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.status").value("UP"))
+                .andExpect(jsonPath("$.code").doesNotExist()));
+    }
+
+    @Test
+    void failedHealthContributorReturnsDownAndServiceUnavailable() {
+        context.withBean("dependencyHealthIndicator", HealthIndicator.class, () -> () -> Health.down().build())
+            .run(application -> MockMvcBuilders.webAppContextSetup(application).build()
+                .perform(get("/actuator/health"))
+                .andExpect(status().isServiceUnavailable())
+                .andExpect(jsonPath("$.status").value("DOWN"))
+                .andExpect(jsonPath("$.code").doesNotExist()));
+    }
+}

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

@@ -1,32 +1,45 @@
 # Auth Service 模块指引
 
-## 职责边界
+## 数据库访问与中文注释约束
 
-- 负责账号凭据、登录、Access/Refresh Token 生命周期、退出、密码变更及商户注册协作。
-- 租户、成员资料、角色和权限属于 `iam/`；Auth 只通过 IAM 客户端加载授权快照和创建注册结果。
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
 
-## 快速索引
+## 职责与边界
 
-| 功能 | 入口 |
+- Mapper 只由 `BaiyueAuthApplication.java` 对 `com.baiyue.auth` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。
+- 负责登录、注册、账号凭据、Access/Refresh Token、退出、密码和账号归属范围。
+- 客户主档、成员、角色权限归 `iam/`；Auth 通过 IAM 客户端获取授权快照，不跨库写 IAM。
+- 修改统一 Access/Refresh Token、Audience、JWKS、Redis 会话或权限撤销前，先读 `../../docs/统一认证与服务通信契约.md` 的认证章节；平台、客户及两类 PDA 保持各自访问域和仓绑定边界。
+- `tenant_id=0` 为平台作用域，`tenant_id>0` 为客户 ID；不得引入租户管理或切换。
+
+## 模块入口
+
+| 目标 | 入口 |
 |---|---|
-| 应用与安全配置 | `src/main/java/com/baiyue/auth/BaiyueAuthApplication.java`、`config/AuthSecurityConfig.java` |
-| 登录、注册、刷新、退出、改密 API | `controller/AuthController.java`（`/api/auth`） |
-| 内部账号管理 API | `controller/InternalAccountController.java`（`/internal/auth/accounts`）；含创建、资料/状态/密码、`PUT /{id}/scope` 账号归属迁移和补偿删除 |
-| 认证与令牌编排 | `service/AuthService.java`、`TokenSessionStore.java` |
-| 账号创建、显示名同步、状态、密码和归属范围 | `service/AccountManagementService.java`；平台账号使用 `default_app_code=PLATFORM`、`tenant_id=0`，范围变更会递增 token version 撤销旧会话 |
-| 商户注册协作 | `service/MerchantRegistrationService.java` |
-| IAM 调用与授权快照 | `client/IamAuthorizationClient.java`、`IamOnboardingClient.java`、`AuthorizationSnapshot.java` |
-| 账号与 Refresh Token 持久化 | `entity/`、`mapper/`、`repository/` |
-| 请求/响应模型 | `dto/AccountManagementDtos.java`；创建可指定初始状态，`AccountSummary` 返回最后登录时间、租户、成员与应用端 |
-| 表结构与一期账号 | `src/main/resources/db/auth.sql`、`phase1-admin-accounts.sql` |
-| 配置与测试 | `src/main/resources/application.yml`、`src/test/java/com/baiyue/auth/service/` |
+| 登录/刷新/退出/改密 | `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 会话校验 |
+| 统一 RS256 签发 | `config/UnifiedJwtConfiguration.java`、`config/UnifiedJwtProperties.java`；登录、刷新、代登录使用唯一 Access Token，`JWT_RSA_JWK_SET` 和 `JWT_CURRENT_KID` 仅配置在 Auth；不再提供海外 Token 兑换 |
+| 统一会话权威校验 | `controller/InternalAccountController.java`、`service/SessionStateService.java`；内部 `/internal/auth/accounts/sessions/validate` 接收 jwtId/userId，核对 Redis Access 与状态指纹，再查询当前 Auth/IAM；内部服务令牌保护，不接收或转发用户 JWT |
+| 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。
-- 修改 Token Claim、会话 Redis Key、过期或撤销逻辑时同步检查 `common-security/`、`gateway/` 和 IAM 授权快照。
-- 注册流程跨 Auth/IAM，失败补偿和幂等必须成对检查；不要跨库写 IAM 表。
-- 内部账号创建允许相同账号 ID 与相同归属幂等重试；不同身份占用同一 ID 必须冲突。内部接口只接收 IAM 的服务令牌，不直接暴露给前端。
-- 平台统一用户管理跨租户移动成员时由 IAM 调用 `PUT /internal/auth/accounts/{id}/scope` 同步 Auth 默认租户、成员和应用端；修改该契约必须同时检查 `iam/client/AuthAccountClient.java` 与 `PlatformUserManagementService.java`。
-- 登录、刷新等业务失败仍是 HTTP 200 + 非 `"200"` body code；Security 入口产生的真实 401 保留给客户端 Token 刷新流程。
-- 从父目录运行 `mvn -pl auth -am test`，认证接口变更再运行相关 `scripts/` 回归。
+- 密码、Token、敏感 Claim 不得写日志；统一 JWT 使用 RS256，私钥只留在 Auth，JWKS 只发布公钥。统一 Token 不携带角色或权限集，权限来自共享 Redis 会话；用户、客户、权限和仓绑定变更必须撤销受影响会话。本地源码已采用统一权威状态校验并移除安全投影，不能将本地改造视为测试环境已部署。修改登录响应、Claim、Audience、JWKS、权限快照或过期策略时联查 Admin/Client 统一认证层、`common-security/`、`gateway/`、`iam/` 和海外服务消费者。
+- 登录、刷新和账号安全修改通过账号行锁串行化；IAM 身份、权限、客户版本、仓绑定由单条 SQL 快照组成指纹，Access/Refresh 均绑定指纹。Gateway 与业务服务逐请求在线核对，无正结果缓存；提交后开始的请求不得接受旧指纹，提交前已经完成认证的在途业务请求不追溯中断。撤销失败使变更失败或回滚，丢失撤销响应也不得恢复旧会话。
+- 校验链为 Gateway/业务服务 → Auth → IAM，不转发 Bearer、无递归。统一 `baiyue.security.session-validation-uri` 默认 `http://auth:9100/internal/auth/accounts/sessions/validate`；外层请求总超时 4 秒，Auth→IAM 连接 1 秒/读取 2 秒且不自动重试。Auth/IAM/Redis 任一不可用均失败关闭；真实吞吐与耗时仍需测试环境验证。
+- 注册跨 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>
@@ -21,6 +22,7 @@
         <dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope></dependency>
         <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
         <dependency><groupId>org.springframework.security</groupId><artifactId>spring-security-test</artifactId><scope>test</scope></dependency>
+        <dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><scope>test</scope></dependency>
     </dependencies>
     <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
 </project>

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

@@ -0,0 +1,14 @@
+package com.baiyue.auth.client;
+
+import feign.Request;
+import feign.Retryer;
+import org.springframework.context.annotation.Bean;
+import java.util.concurrent.TimeUnit;
+
+/** Only the IAM authorization client uses this bounded, single-attempt chain. */
+public class AuthorizationFeignConfiguration {
+    @Bean public Request.Options authorizationRequestOptions() {
+        return new Request.Options(1, TimeUnit.SECONDS, 2, TimeUnit.SECONDS, false);
+    }
+    @Bean public Retryer authorizationRetryer() { return Retryer.NEVER_RETRY; }
+}

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) {
@@ -39,10 +44,17 @@ public class AuthorizationLoader {
                 }
                 throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM 权限服务暂时不可用");
             }
-            if (response.data() == null) {
+            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) {
             throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM 权限服务暂时不可用");
         } catch (BizException exception) {

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

@@ -20,4 +20,29 @@ public class AuthorizationSnapshot {
     private String clientType;
     private Set<String> roles;
     private Set<String> permissions;
+    private Long permissionVersion;
+    private Long overseasWarehouseId;
+    private Long domesticWarehouseId;
+    private Long tenantVersion;
+
+    public AuthorizationSnapshot(Long userId, Long tenantId, Long membershipId, String appCode,
+            String clientType, Set<String> roles, Set<String> permissions, Long permissionVersion,
+            Long overseasWarehouseId, Long domesticWarehouseId) {
+        this(userId, tenantId, membershipId, appCode, clientType, roles, permissions,
+            permissionVersion, overseasWarehouseId, domesticWarehouseId, 0L);
+    }
+
+    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, null);
+    }
+
+    public AuthorizationSnapshot(Long userId, Long tenantId, Long membershipId, String appCode,
+                                 String clientType, Set<String> roles, Set<String> permissions,
+                                 Long permissionVersion, Long overseasWarehouseId) {
+        this(userId, tenantId, membershipId, appCode, clientType, roles, permissions,
+            permissionVersion, overseasWarehouseId, null);
+    }
 }

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

@@ -9,7 +9,7 @@ import org.springframework.web.bind.annotation.RequestHeader;
 /**
  * 认证服务访问 IAM 内部授权接口的声明式客户端，用于加载用户在指定应用和租户下的权限快照。
  */
-@FeignClient(name = "iam-service", contextId = "iamAuthorizationClient",
+@FeignClient(name = "iam-service", contextId = "iamAuthorizationClient", configuration = AuthorizationFeignConfiguration.class,
         url = "${baiyue.clients.iam.url:}", path = "/internal/iam")
 public interface IamAuthorizationClient {
     @PostMapping("/authorization-snapshot")

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 issuer, String audience,
                                      Duration accessTokenTtl, Duration refreshTokenTtl,
                                      int maxLoginFailures, Duration lockDuration) {
 }

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

@@ -0,0 +1,35 @@
+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.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(UnifiedJwtProperties.class)
+public class UnifiedJwtConfiguration {
+    @Bean("jwtEncoder")
+    JwtEncoder jwtEncoder(UnifiedJwtProperties 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/UnifiedJwtProperties.java

@@ -0,0 +1,7 @@
+package com.baiyue.auth.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/** Unified RS256 signing key configuration. Private keys remain in Auth. */
+@ConfigurationProperties(prefix = "baiyue.security.jwt")
+public record UnifiedJwtProperties(String rsaJwkSet, String currentKid) { }

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,6 +20,8 @@ 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 org.springframework.security.access.prepost.PreAuthorize;
 
@@ -34,20 +38,31 @@ public class AuthController {
     private MerchantRegistrationService registrationService;
     @Resource
     private AccountManagementService accountManagementService;
-
     @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));
     }
@@ -82,4 +97,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,12 +2,14 @@ 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.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.tags.Tag;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.web.bind.annotation.*;
 
@@ -17,25 +19,38 @@ import java.security.MessageDigest;
 /** 仅供可信内部服务调用的账号管理接口。 */
 @RestController
 @RequestMapping("/internal/auth/accounts")
+@Tag(name = "Internal Auth / 内部认证", description = "Service-token protected internal account and unified session APIs")
 public class InternalAccountController {
     @Resource
     private AccountManagementService service;
+    @Resource
+    private AuthService authService;
+    @Resource private com.baiyue.auth.service.SessionStateService sessionStateService;
 
-    private final String configuredToken;
+    @Value("${baiyue.security.internal-service-token}")
+    private String configuredToken;
     private byte[] tokenBytes;
 
-    public InternalAccountController(
-            @Value("${baiyue.security.internal-service-token}") String configuredToken) {
-        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) {
@@ -46,15 +61,59 @@ 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);
+    }
+    public record SessionValidationRequest(@jakarta.validation.constraints.NotBlank String jwtId,
+        @jakarta.validation.constraints.NotNull Long userId) { }
+
+    @PostMapping("/sessions/validate")
+    public ApiResponse<Boolean> validateSession(
+            @RequestHeader(value="X-Internal-Service-Token", required=false) String token,
+            @Valid @RequestBody SessionValidationRequest request) {
+        verify(token);
+        return ApiResponse.success(sessionStateService.validate(request.jwtId(), request.userId()));
+    }
+
     @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,

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

@@ -0,0 +1,29 @@
+package com.baiyue.auth.controller;
+
+import com.baiyue.auth.config.UnifiedJwtProperties;
+import com.nimbusds.jose.jwk.JWKSet;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.security.SecurityRequirements;
+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
+public class JwksController {
+    private final UnifiedJwtProperties properties;
+
+    public JwksController(UnifiedJwtProperties 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,10 +2,12 @@ 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 {
@@ -14,8 +16,13 @@ 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,
@@ -26,19 +33,44 @@ public final class AccountManagementDtos {
                                        String accountStatus) {
         public CreateAccountRequest(Long accountId, String username, String password, String displayName,
                                     Long tenantId, Long membershipId, String appCode) {
-            this(accountId, username, password, displayName, tenantId, membershipId, appCode, "ACTIVE");
+            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) { }
+                                       @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 displayName, String status,
+    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, displayName, status, null, null, null, null);
+            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/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,12 @@ 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 = "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,25 +1,31 @@
 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>()
             .eq(AuthAccount::getUsername, username)
-            .last("LIMIT 1"));
+            .last("LIMIT 1 FOR UPDATE"));
+    }
+
+    public AuthAccount findByPhone(String phone) {
+        return mapper.selectOne(new LambdaQueryWrapper<AuthAccount>()
+            .eq(AuthAccount::getPhone, phone)
+            .last("LIMIT 1 FOR UPDATE"));
     }
 
     public boolean existsByUsername(String username) {
@@ -27,10 +33,35 @@ public class AuthAccountRepository {
                 .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);
+        return mapper.selectOne(new LambdaQueryWrapper<AuthAccount>().eq(AuthAccount::getId, id).last("FOR UPDATE"));
+    }
+
+    public AuthAccount findCurrentById(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").orderByAsc(AuthAccount::getId).last("FOR UPDATE"));
     }
 
     public void save(AuthAccount 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

@@ -9,10 +9,12 @@ import jakarta.annotation.Resource;
 import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
+import org.springframework.dao.DuplicateKeyException;
 import com.baiyue.common.audit.BusinessAudit;
 
 import java.util.Locale;
 import java.util.Objects;
+import java.util.Set;
 
 /** 账号生命周期管理，所有密码只以 BCrypt 摘要写入数据库。 */
 @Service
@@ -21,17 +23,38 @@ 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
@@ -41,7 +64,9 @@ public class AccountManagementService {
         String appCode = request.appCode() == null ? "MERCHANT"
                 : request.appCode().trim().toUpperCase(Locale.ROOT);
         validateScope(appCode, request.tenantId());
-        AuthAccount existing = repository.findById(request.accountId());
+        // Locking a missing key takes an InnoDB gap lock and can deadlock
+        // unrelated account inserts. The unique indexes arbitrate creation.
+        AuthAccount existing = repository.findCurrentById(request.accountId());
         if (existing != null) {
             if (sameIdentity(existing, request, appCode)) return summary(existing);
             throw new BizException(ResultCode.CONFLICT, "认证账号标识已被其他成员使用");
@@ -49,9 +74,13 @@ public class AccountManagementService {
         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(request.accountStatus() == null ? "ACTIVE" : request.accountStatus());
@@ -62,7 +91,13 @@ public class AccountManagementService {
         account.setDefaultMembershipId(request.membershipId());
         account.setDefaultAppCode(appCode);
         account.setDeleted(0);
-        repository.insert(account);
+        try {
+            repository.insert(account);
+        } catch (DuplicateKeyException duplicate) {
+            AuthAccount winner = repository.findById(request.accountId());
+            if (winner != null && sameIdentity(winner, request, appCode)) return summary(winner);
+            throw new BizException(ResultCode.CONFLICT, "认证账号标识或登录账号已被使用");
+        }
         return summary(account);
     }
 
@@ -77,6 +112,14 @@ 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.stream().sorted().forEach(accountId -> bumpVersion(required(accountId)));
+    }
+
     @Transactional
     @BusinessAudit(event = "ACCOUNT_PROFILE_CHANGE", resourceType = "ACCOUNT", resourceId = "#accountId",
             description = "同步账号显示名称", captureAfter = false)
@@ -87,10 +130,62 @@ public class AccountManagementService {
         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
@@ -121,10 +216,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);
     }
 
@@ -141,7 +237,7 @@ 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());
     }
 
@@ -157,6 +253,7 @@ public class AccountManagementService {
 
     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())

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;
@@ -14,22 +16,25 @@ import com.baiyue.common.core.exception.BizException;
 
 import jakarta.annotation.Resource;
 import org.springframework.security.crypto.password.PasswordEncoder;
-import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
+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 org.springframework.transaction.annotation.Transactional;
+import com.baiyue.auth.config.UnifiedJwtProperties;
 
 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 UnifiedJwtProperties signingProperties;
 
     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()))
@@ -82,7 +92,8 @@ public class AuthService {
         AuthAccount account = accountRepository.findById(session.userId());
         if (account == null || !"ACTIVE".equals(account.getAccountStatus()))
             throw new BizException(ResultCode.UNAUTHORIZED, "账号不可用");
-        return issue(account);
+        if (session.fingerprint() == null) throw new BizException(ResultCode.UNAUTHORIZED, "刷新会话缺少授权状态");
+        return issue(account, session.fingerprint());
     }
 
     @Transactional
@@ -99,39 +110,125 @@ public class AuthService {
         accountRepository.save(account);
     }
 
-    private TokenResponse issue(AuthAccount account) {
+    private TokenResponse issue(AuthAccount account) { return issue(account, null); }
+
+    private TokenResponse issue(AuthAccount account, String expectedState) {
         AuthorizationSnapshot authorization = authorizationLoader.load(account);
+        if (expectedState != null && !expectedState.equals(SessionStateService.fingerprint(account, authorization))) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "授权状态已变更，请重新登录");
+        }
         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());
+        }
+        if (authorization.getDomesticWarehouseId() != null) {
+            claimsBuilder.claim("domestic_warehouse_id", authorization.getDomesticWarehouseId());
+        }
+        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(),
+                SessionStateService.fingerprint(account, authorization), rawRefresh,
                 properties.accessTokenTtl(), properties.refreshTokenTtl());
         return new TokenResponse("Bearer", accessToken, properties.accessTokenTtl().toSeconds(),
-            rawRefresh, properties.refreshTokenTtl().toSeconds());
+            rawRefresh, properties.refreshTokenTtl().toSeconds(),
+            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(), SessionStateService.fingerprint(account, authorization), Duration.ofMinutes(15));
+        return new ImpersonationTokenResponse("Bearer", accessToken, 900,
+                authorization.getRoles(), authorization.getPermissions());
+    }
+
+    public record ImpersonationTokenResponse(String tokenType, String accessToken, long expiresIn,
+                                              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(SignatureAlgorithm.RS256).keyId(signingProperties.currentKid()).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,15 +35,30 @@ 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) {
                 throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "IAM registration failed");
@@ -51,17 +74,27 @@ public class MerchantRegistrationService {
             }
             onboarding = response.data();
         } catch (FeignException exception) {
-            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) {
-            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;
         }
 
         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);
@@ -71,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/SessionStateService.java

@@ -0,0 +1,63 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.AuthorizationLoader;
+import com.baiyue.auth.client.AuthorizationSnapshot;
+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 com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.Resource;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.security.MessageDigest;
+import java.util.HexFormat;
+import java.util.TreeSet;
+
+/** No cache: a validation started after a security commit must observe that commit. */
+@Service
+public class SessionStateService {
+    private static final ObjectMapper FINGERPRINT_JSON = new ObjectMapper();
+    @Resource private AuthAccountRepository accounts;
+    @Resource private AuthorizationLoader authorizationLoader;
+    @Resource private TokenSessionStore sessions;
+
+    public static String fingerprint(AuthAccount account, AuthorizationSnapshot snapshot) {
+        try {
+            if (account.getTokenVersion() == null || snapshot.getPermissionVersion() == null
+                    || snapshot.getTenantVersion() == null) throw new IllegalArgumentException("Missing persisted security version");
+            // Ordered JSON array avoids set ordering and delimiter ambiguities.
+            Object[] state = {account.getId(), account.getTokenVersion(), account.getDefaultTenantId(),
+                account.getDefaultMembershipId(), account.getDefaultAppCode(), account.getOperatorTenantId(),
+                snapshot.getPermissionVersion(), snapshot.getTenantVersion(), snapshot.getClientType(),
+                snapshot.getOverseasWarehouseId(), snapshot.getDomesticWarehouseId(),
+                new TreeSet<>(snapshot.getRoles()), new TreeSet<>(snapshot.getPermissions())};
+            return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256")
+                .digest(FINGERPRINT_JSON.writeValueAsBytes(state)));
+        } catch (Exception failure) {
+            throw new IllegalStateException("Cannot fingerprint authorization state", failure);
+        }
+    }
+
+    private void requireCurrent(Long userId, String expected) {
+        AuthAccount account = accounts.findCurrentById(userId);
+        if (account == null || !"ACTIVE".equals(account.getAccountStatus())
+                || Integer.valueOf(1).equals(account.getDeleted()) || expected == null
+                || !expected.equals(fingerprint(account, authorizationLoader.load(account)))) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "登录授权已变更，请重新登录");
+        }
+    }
+
+    @Transactional(readOnly = true, propagation = Propagation.REQUIRES_NEW,
+        isolation = org.springframework.transaction.annotation.Isolation.READ_COMMITTED)
+    public boolean validate(String jwtId, Long userId) {
+        TokenSessionStore.SessionState state = sessions.loadState(jwtId);
+        if (state == null || !state.userId().equals(userId)) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "登录会话已失效");
+        }
+        requireCurrent(userId, state.fingerprint());
+        return true;
+    }
+}

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

@@ -1,15 +1,17 @@
 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;
-import org.springframework.data.redis.core.Cursor;
-import org.springframework.data.redis.core.ScanOptions;
 import org.springframework.stereotype.Component;
 
 import java.nio.charset.StandardCharsets;
@@ -17,43 +19,81 @@ import java.security.MessageDigest;
 import java.time.Duration;
 import java.util.HexFormat;
 import java.util.Set;
-import java.util.ArrayList;
-import java.util.List;
 
 /**
  * 认证会话存储服务，使用 Redis 保存和一次性消费刷新会话，支持刷新令牌轮换及主动撤销。
  */
 @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 fingerprint, 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 refreshValue = objectMapper.writeValueAsString(new RefreshSession(userId, jwtId));
+            String accessValue = objectMapper.writeValueAsString(
+                    new AccessSession(1, userId, normalized(roles), normalized(permissions)));
+            redisTemplate.opsForValue().set(accessKey, accessValue, accessTtl);
+            storeState(jwtId, userId, fingerprint, accessTtl);
+            String refreshValue = objectMapper.writeValueAsString(new RefreshSession(userId, jwtId, fingerprint));
             redisTemplate.opsForValue().set(refreshKey, refreshValue, refreshTtl);
             SetOperations<String, String> sets = redisTemplate.opsForSet();
-            if (sets != null) sets.add(userKey, accessKey, refreshKey);
+            if (sets != null) sets.add(userKey, accessKey, refreshKey, stateKey(jwtId));
             redisTemplate.expire(userKey, refreshTtl);
         } catch (Exception exception) {
-            try { redisTemplate.delete(Set.of(accessKey, refreshKey, userKey)); } catch (DataAccessException ignored) { }
+            try { redisTemplate.delete(Set.of(accessKey, refreshKey, stateKey(jwtId))); } catch (DataAccessException ignored) { }
             throw unavailable(exception);
         }
     }
 
+    public void storeAccessOnly(String jwtId, Long userId, Set<String> roles,
+                                Set<String> permissions, String fingerprint, 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);
+            storeState(jwtId, userId, fingerprint, ttl);
+            redisTemplate.opsForSet().add(userSessionsKey(userId), accessKey, stateKey(jwtId));
+            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(
@@ -61,6 +101,7 @@ public class TokenSessionStore {
             if (value == null || value.isBlank()) return null;
             RefreshSession session = objectMapper.readValue(value, RefreshSession.class);
             redisTemplate.delete(RedisTokenKeys.access(keyPrefix, session.accessJwtId()));
+            redisTemplate.delete(stateKey(session.accessJwtId()));
             return session;
         } catch (DataAccessException exception) {
             throw unavailable(exception);
@@ -79,37 +120,30 @@ public class TokenSessionStore {
         try {
             Set<String> keys = redisTemplate.opsForSet().members(userKey);
             if (keys != null && !keys.isEmpty()) redisTemplate.delete(keys);
-            // 兼容功能上线前尚未写入用户会话索引的存量令牌，SCAN 不阻塞 Redis 主线程。
-            List<String> legacyKeys = new ArrayList<>();
-            collectLegacyKeys(keyPrefix + ":access:*", userId, legacyKeys, false);
-            collectLegacyKeys(keyPrefix + ":refresh:*", userId, legacyKeys, true);
-            if (!legacyKeys.isEmpty()) redisTemplate.delete(legacyKeys);
             redisTemplate.delete(userKey);
         } catch (DataAccessException exception) {
             throw unavailable(exception);
         }
     }
 
-    private void collectLegacyKeys(String pattern, Long userId, List<String> result, boolean refresh) {
-        Cursor<String> cursor = redisTemplate.scan(ScanOptions.scanOptions().match(pattern).count(500).build());
-        if (cursor == null) return;
-        try (cursor) {
-            while (cursor.hasNext()) {
-                String key = cursor.next();
-                String value = redisTemplate.opsForValue().get(key);
-                if ((!refresh && userId.toString().equals(value)) || (refresh && belongsTo(value, userId))) {
-                    result.add(key);
-                }
-            }
-        } catch (Exception exception) {
-            throw unavailable(exception);
-        }
+    private String stateKey(String jwtId) { return keyPrefix + ":state:" + jwtId; }
+
+    private void storeState(String jwtId, Long userId, String fingerprint, Duration ttl) throws Exception {
+        if (fingerprint == null || fingerprint.isBlank()) throw new IllegalArgumentException("Missing security state");
+        redisTemplate.opsForValue().set(stateKey(jwtId),
+            objectMapper.writeValueAsString(new SessionState(userId, fingerprint)), ttl);
     }
 
-    private boolean belongsTo(String value, Long userId) {
-        if (value == null || value.isBlank()) return false;
-        try { return userId.equals(objectMapper.readValue(value, RefreshSession.class).userId()); }
-        catch (Exception ignored) { return false; }
+    public SessionState loadState(String jwtId) {
+        try {
+            if (!Boolean.TRUE.equals(redisTemplate.hasKey(RedisTokenKeys.access(keyPrefix, jwtId)))) return null;
+            String value = redisTemplate.opsForValue().get(stateKey(jwtId));
+            return value == null ? null : objectMapper.readValue(value, SessionState.class);
+        } catch (Exception failure) { throw unavailable(failure); }
+    }
+
+    private static Set<String> normalized(Set<String> values) {
+        return values == null ? Set.of() : Set.copyOf(values);
     }
 
     private String userSessionsKey(Long userId) {
@@ -130,5 +164,15 @@ public class TokenSessionStore {
         }
     }
 
-    public record RefreshSession(Long userId, String accessJwtId) { }
+    public record SessionState(Long userId, String fingerprint) { }
+    public record RefreshSession(Long userId, String accessJwtId, String fingerprint) { }
+    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

@@ -1,6 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -2,42 +2,48 @@ server:
   port: ${AUTH_PORT:9100}
 spring:
   profiles:
-    active: ${SPRING_PROFILES_ACTIVE:dev}
+    active: ${SPRING_PROFILES_ACTIVE:test}
   application:
     name: auth-service
   config:
     import:
-      - optional:nacos:baiyue-common.yml?group=BAIYUE&refreshEnabled=true
-      - optional:nacos:${spring.application.name}.yml?group=BAIYUE&refreshEnabled=true
+      - nacos:baiyue-common.yml?group=${NACOS_GROUP:BAIYUE}&refreshEnabled=true
+      - nacos:${spring.application.name}.yml?group=${NACOS_GROUP:BAIYUE}&refreshEnabled=true
   data:
     redis:
-      host: ${REDIS_HOST:127.0.0.1}
+      host: ${REDIS_HOST}
       port: ${REDIS_PORT:6379}
       password: ${REDIS_PASSWORD:}
       database: ${REDIS_DATABASE:0}
       timeout: ${REDIS_TIMEOUT:3s}
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
-      username: ${NACOS_USERNAME:nacos}
-      password: ${NACOS_PASSWORD:nacos}
+      server-addr: ${NACOS_SERVER_ADDR}
+      username: ${NACOS_USERNAME}
+      password: ${NACOS_PASSWORD}
       discovery:
         enabled: ${NACOS_DISCOVERY_ENABLED:true}
         register-enabled: ${NACOS_REGISTER_ENABLED:true}
         group: ${NACOS_GROUP:BAIYUE}
-        namespace: ${NACOS_NAMESPACE:public}
+        namespace: ${NACOS_NAMESPACE}
       config:
-        namespace: ${NACOS_NAMESPACE:public}
+        namespace: ${NACOS_NAMESPACE}
         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}
+  internal-service-token: ${INTERNAL_SERVICE_TOKEN}
   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}
+  jwt-mode: jwks
+  session-mode: redis
+  jwk-set-uri: ${JWT_JWKS_URI:http://auth:9100/api/auth/.well-known/jwks.json}
+  jwt:
+    rsa-jwk-set: ${JWT_RSA_JWK_SET:}
+    current-kid: ${JWT_CURRENT_KID:}
 
 baiyue.clients:
   iam:
@@ -45,13 +51,4 @@ baiyue.clients:
 
 management.endpoints.web.exposure.include: health,info,prometheus
 
-logging:
-  file:
-    name: "${LOGGING_FILE_NAME:${LOG_PATH:./logs}/${spring.application.name}.log}"
-  logback:
-    rollingpolicy:
-      file-name-pattern: "${LOGGING_ROLLING_FILE_NAME_PATTERN:${LOG_PATH:./logs}/${spring.application.name}.%d{yyyy-MM-dd}.%i.log.gz}"
-      max-file-size: "${LOGGING_ROLLING_MAX_FILE_SIZE:100MB}"
-      max-history: "${LOGGING_ROLLING_MAX_HISTORY:30}"
-      total-size-cap: "${LOGGING_ROLLING_TOTAL_SIZE_CAP:5GB}"
-      clean-history-on-start: "${LOGGING_ROLLING_CLEAN_HISTORY_ON_START:false}"
+baiyue.security.session-validation-uri: ${AUTH_SESSION_VALIDATION_URL:http://auth:9100/internal/auth/accounts/sessions/validate}

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/main/resources/openapi/auth-internal.yaml

@@ -0,0 +1,39 @@
+openapi: 3.0.3
+info:
+  title: Auth internal session validation
+  version: 1.0.0
+paths:
+  /internal/auth/accounts/sessions/validate:
+    post:
+      summary: Validate persisted account and IAM authorization state
+      description: Internal network only. No Gateway public route. Verifies the Redis Access session and state fingerprint against current Auth account and a consistent IAM snapshot. No positive cache; missing state, stale state and dependency failure deny access. Does not accept or forward a user Bearer token.
+      security:
+        - internalServiceToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [jwtId, userId]
+              properties:
+                jwtId: {type: string, minLength: 1}
+                userId: {type: integer, format: int64}
+      responses:
+        '200':
+          description: Only string code 200 and boolean data true constitute success. Business errors deny access.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [code]
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data: {type: boolean, nullable: true}
+components:
+  securitySchemes:
+    internalServiceToken:
+      type: apiKey
+      in: header
+      name: X-Internal-Service-Token

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

@@ -0,0 +1,96 @@
+package com.baiyue.auth.client;
+
+import feign.Client;
+import feign.FeignException;
+import feign.Request;
+import feign.Response;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.autoconfigure.http.HttpMessageConvertersAutoConfiguration;
+import org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration;
+import org.springframework.boot.env.YamlPropertySourceLoader;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+import org.springframework.cloud.openfeign.EnableFeignClients;
+import org.springframework.cloud.openfeign.FeignAutoConfiguration;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.cloud.openfeign.FeignClientProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.io.FileSystemResource;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.assertj.core.api.Assertions.*;
+
+class AuthorizationFeignConfigurationContractTest {
+    @Test
+    void actualNamedNacosConfigMatchesContextIdAndOverridesGlobalFeignBudget() {
+        new ApplicationContextRunner()
+            .withConfiguration(AutoConfigurations.of(FeignAutoConfiguration.class,
+                JacksonAutoConfiguration.class, HttpMessageConvertersAutoConfiguration.class))
+            .withUserConfiguration(OfflineFeignConfiguration.class)
+            .withPropertyValues("baiyue.clients.iam.url=http://127.0.0.1:1")
+            .withInitializer(context -> {
+                for (String file : new String[]{"baiyue-common.yml", "auth-service.yml"}) {
+                    Path path = Path.of("config", "nacos", "test", file);
+                    if (!Files.isRegularFile(path)) path = Path.of("..").resolve(path);
+                    try {
+                        // Load real configuration as properties only, without config-data imports.
+                        for (var source : new YamlPropertySourceLoader().load(file, new FileSystemResource(path))) {
+                            context.getEnvironment().getPropertySources().addLast(source);
+                        }
+                    } catch (java.io.IOException failure) {
+                        throw new IllegalStateException("Cannot read actual Auth Feign configuration", failure);
+                    }
+                }
+            })
+            .run(context -> {
+                assertThat(context).hasNotFailed();
+                String contextId = IamAuthorizationClient.class.getAnnotation(FeignClient.class).contextId();
+                var properties = context.getBean(FeignClientProperties.class);
+                var named = properties.getConfig().get(contextId);
+                assertThat(named).as("Nacos key must match actual @FeignClient contextId").isNotNull();
+                assertThat(named.getConnectTimeout()).isEqualTo(1000);
+                assertThat(named.getReadTimeout()).isEqualTo(2000);
+                assertThat(named.isFollowRedirects()).isFalse();
+                assertThat(properties.getConfig().get("default").getConnectTimeout()).isEqualTo(3000);
+                assertThat(properties.getConfig().get("default").getReadTimeout()).isEqualTo(5000);
+
+                var transport = context.getBean(CapturingClient.class);
+                var client = context.getBean(IamAuthorizationClient.class);
+                var request = new AuthorizationSnapshotRequest(1L, 7L, 9L, "MERCHANT");
+                client.load("offline-service-token", request);
+                assertThat(transport.options.get().connectTimeoutMillis()).isEqualTo(1000);
+                assertThat(transport.options.get().readTimeoutMillis()).isEqualTo(2000);
+                assertThat(transport.options.get().isFollowRedirects()).isFalse();
+
+                transport.status.set(503);
+                assertThatThrownBy(() -> client.load("offline-service-token", request)).isInstanceOf(FeignException.class);
+                assertThat(transport.calls.get()).as("One success plus one failure, without automatic retry").isEqualTo(2);
+            });
+    }
+
+    @Configuration(proxyBeanMethods = false)
+    @EnableFeignClients(clients = IamAuthorizationClient.class)
+    static class OfflineFeignConfiguration {
+        @Bean CapturingClient capturingClient() { return new CapturingClient(); }
+    }
+
+    /** The real Feign factory builds the client; only network I/O is replaced. */
+    static class CapturingClient implements Client {
+        final AtomicReference<Request.Options> options = new AtomicReference<>();
+        final AtomicInteger calls = new AtomicInteger();
+        final AtomicInteger status = new AtomicInteger(204);
+
+        @Override public Response execute(Request request, Request.Options effectiveOptions) {
+            options.set(effectiveOptions);
+            calls.incrementAndGet();
+            return Response.builder().request(request).status(status.get()).reason("offline")
+                .headers(Map.of()).build();
+        }
+    }
+}

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 testNacosConfigurationKeepsUnifiedShortAccessAndSevenDayRefreshTokens() throws Exception {
+        String configuration = Files.readString(
+            Path.of("..", "config", "nacos", "test", "auth-service.yml"), StandardCharsets.UTF_8);
+
+        assertThat(configuration)
+            .contains("access-token-ttl: ${ACCESS_TOKEN_TTL:24m}")
+            .contains("refresh-token-ttl: ${REFRESH_TOKEN_TTL:7d}")
+            .doesNotContain("OVERSEAS_ACCESS_TOKEN_TTL")
+            .doesNotContain("access-token-ttl: ${ACCESS_TOKEN_TTL:7d}");
+    }
+}

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

@@ -0,0 +1,43 @@
+package com.baiyue.auth.config;
+
+import com.nimbusds.jose.JWSAlgorithm;
+import com.nimbusds.jose.jwk.JWKSet;
+import com.nimbusds.jose.jwk.gen.RSAKeyGenerator;
+import org.junit.jupiter.api.Test;
+import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
+import org.springframework.security.oauth2.jwt.*;
+import java.time.Instant;
+import java.util.List;
+import static org.assertj.core.api.Assertions.*;
+
+class UnifiedJwtConfigurationTest {
+    @Test
+    void signsWithCurrentKeyAndRetainsPreviousPublicKeyForRotation() throws Exception {
+        var current = new RSAKeyGenerator(2048).keyID("current").algorithm(JWSAlgorithm.RS256).generate();
+        var previous = new RSAKeyGenerator(2048).keyID("previous").algorithm(JWSAlgorithm.RS256).generate();
+        var properties = new UnifiedJwtProperties(new JWKSet(List.of(current, previous.toPublicJWK())).toString(false), "current");
+        var encoder = new UnifiedJwtConfiguration().jwtEncoder(properties);
+        var now = Instant.now();
+        var token = encoder.encode(JwtEncoderParameters.from(
+                JwsHeader.with(SignatureAlgorithm.RS256).keyId("current").build(),
+                JwtClaimsSet.builder().subject("42").issuedAt(now).expiresAt(now.plusSeconds(60)).build()));
+        var decoded = NimbusJwtDecoder.withPublicKey(current.toRSAPublicKey()).build().decode(token.getTokenValue());
+        assertThat(decoded.getSubject()).isEqualTo("42");
+        assertThat(decoded.getHeaders()).containsEntry("kid", "current").containsEntry("alg", "RS256");
+        assertThatThrownBy(() -> NimbusJwtDecoder.withPublicKey(previous.toRSAPublicKey()).build().decode(token.getTokenValue()))
+                .isInstanceOf(JwtException.class);
+    }
+
+    @Test
+    void rejectsMissingPrivateKeyAndPreviousPrivateKey() throws Exception {
+        var current = new RSAKeyGenerator(2048).keyID("current").generate();
+        var previous = new RSAKeyGenerator(2048).keyID("previous").generate();
+        var config = new UnifiedJwtConfiguration();
+        assertThatThrownBy(() -> config.jwtEncoder(new UnifiedJwtProperties(new JWKSet(current.toPublicJWK()).toString(), "current")))
+                .isInstanceOf(IllegalStateException.class);
+        assertThatThrownBy(() -> config.jwtEncoder(new UnifiedJwtProperties(new JWKSet(List.of(current, previous)).toString(false), "current")))
+                .isInstanceOf(IllegalStateException.class);
+        assertThatThrownBy(() -> config.jwtEncoder(new UnifiedJwtProperties("", "current")))
+                .isInstanceOf(IllegalStateException.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,39 @@
+package com.baiyue.auth.controller;
+
+import com.baiyue.auth.config.UnifiedJwtProperties;
+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 UnifiedJwtProperties(json, "current");
+
+        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/repository/AuthLoginIdentifiersSqlContractTest.java

@@ -0,0 +1,43 @@
+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 legacyMigrationBackfillsOnlyUniquelyOwnedPhonesAndKeepsDuplicatesUnbound() throws Exception {
+        assertSafeBackfill(new ClassPathResource("db/auth-login-identifiers.sql")
+            .getContentAsString(StandardCharsets.UTF_8));
+    }
+
+    @Test
+    void emptyDatabaseInitializationDeclaresPhoneUniquenessWithoutLegacyBackfill() throws Exception {
+        String sql = Files.readString(unifiedSql(), StandardCharsets.UTF_8);
+
+        assertThat(sql)
+            .contains("phone varchar(32) DEFAULT NULL")
+            .contains("UNIQUE KEY uk_auth_account_phone (phone)")
+            .doesNotContain("phone NOT REGEXP '^1[3-9][0-9]{9}$'")
+            .doesNotContain("HAVING COUNT(DISTINCT auth_user_id) = 1")
+            .doesNotContain("ALTER TABLE auth_account");
+    }
+
+    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)
+            .containsPattern("\\(1000001\\s*,\\s*'platform_admin'")
+            .containsPattern("'平台系统管理员'\\s*,\\s*'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,45 @@
 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 org.springframework.dao.DuplicateKeyException;
+
+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);
@@ -50,6 +60,25 @@ class AccountManagementServiceTest {
         verify(sessions, never()).revokeAll(any());
     }
 
+    @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());
@@ -57,7 +86,7 @@ class AccountManagementServiceTest {
     }
 
     @Test void createPlatformAccountPersistsPlatformAppCodeAndPasswordHashOnly() {
-        when(repository.findById(20L)).thenReturn(null);
+        when(repository.findCurrentById(20L)).thenReturn(null);
         when(repository.existsByUsername("platform.user")).thenReturn(false);
 
         var result = service.create(new CreateAccountRequest(20L, "platform.user", "Password1",
@@ -69,10 +98,18 @@ class AccountManagementServiceTest {
         assertEquals("PLATFORM", captor.getValue().getDefaultAppCode());
         assertTrue(encoder.matches("Password1", captor.getValue().getPasswordHash()));
         assertNotEquals("Password1", captor.getValue().getPasswordHash());
+        verify(repository, never()).findById(20L);
+    }
+
+    @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.findCurrentById(20L)).thenReturn(null);
         when(repository.existsByUsername("merchant.user")).thenReturn(false);
 
         var created = service.create(new CreateAccountRequest(20L, "merchant.user", "Password1",
@@ -106,6 +143,7 @@ class AccountManagementServiceTest {
         account.setUsername("platform.user"); account.setDisplayName("平台用户");
         account.setDefaultTenantId(0L); account.setOperatorTenantId(0L);
         account.setDefaultMembershipId(30L); account.setDefaultAppCode("PLATFORM"); account.setDeleted(0);
+        when(repository.findCurrentById(10L)).thenReturn(account);
 
         var result = service.create(new CreateAccountRequest(10L, "platform.user", "Password1",
                 "平台用户", 0L, 30L, "PLATFORM"));
@@ -114,6 +152,44 @@ class AccountManagementServiceTest {
         verify(repository, never()).insert(any());
     }
 
+    @Test void concurrentInsertOfSameIdentityReturnsDurableWinner() {
+        account.setUsername("platform.user"); account.setDefaultTenantId(0L);
+        account.setOperatorTenantId(0L); account.setDefaultMembershipId(30L);
+        account.setDefaultAppCode("PLATFORM"); account.setDeleted(0);
+        when(repository.findCurrentById(10L)).thenReturn(null);
+        doThrow(new DuplicateKeyException("concurrent insert")).when(repository).insert(any());
+
+        var result = service.create(new CreateAccountRequest(10L, "platform.user", "Password1",
+                "平台用户", 0L, 30L, "PLATFORM"));
+
+        assertEquals(10L, result.accountId());
+        var order = inOrder(repository);
+        order.verify(repository).findCurrentById(10L);
+        order.verify(repository).existsByUsername("platform.user");
+        order.verify(repository).insert(any());
+        order.verify(repository).findById(10L);
+        verify(repository, never()).save(any());
+    }
+
+    @Test void concurrentInsertOfDifferentIdentityIsRejected() {
+        when(repository.findCurrentById(10L)).thenReturn(null);
+        doThrow(new DuplicateKeyException("concurrent insert")).when(repository).insert(any());
+
+        assertThrows(BizException.class, () -> service.create(new CreateAccountRequest(10L,
+                "platform.user", "Password1", "平台用户", 0L, 30L, "PLATFORM")));
+        verify(repository, never()).save(any());
+    }
+
+    @Test void concurrentUsernameConflictDoesNotCreateOrReturnAnotherAccount() {
+        when(repository.findCurrentById(20L)).thenReturn(null);
+        when(repository.findById(20L)).thenReturn(null);
+        doThrow(new DuplicateKeyException("username conflict")).when(repository).insert(any());
+
+        assertThrows(BizException.class, () -> service.create(new CreateAccountRequest(20L,
+                "platform.user", "Password1", "平台用户", 0L, 30L, "PLATFORM")));
+        verify(repository, never()).save(any());
+    }
+
     @Test void synchronizeDisplayNameRevokesExistingSessions() {
         account.setDisplayName("旧名称");
 
@@ -123,4 +199,100 @@ class AccountManagementServiceTest {
         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,236 @@
+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.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 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;
+    @Resource private AuthService service;
+
+    @Configuration(proxyBeanMethods = false)
+    static class TestConfig {
+        @Bean
+        com.baiyue.auth.config.UnifiedJwtProperties signingProperties() {
+            return new com.baiyue.auth.config.UnifiedJwtProperties("unused", "current");
+        }
+        @Bean
+        AuthSecurityProperties properties() {
+            return new AuthSecurityProperties("auth-service", "lastleg-api",
+                    Duration.ofMinutes(30),
+                    Duration.ofDays(7), 5, Duration.ofMinutes(10));
+        }
+    }
+
+    @Test
+    void signsUnifiedClaimsAndStoresSession() {
+        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");
+
+        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(SignatureAlgorithm.RS256);
+        assertThat(jwt.getValue().getJwsHeader().getKeyId()).isEqualTo("current");
+        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")), anyString(), any(),
+                org.mockito.ArgumentMatchers.eq(Duration.ofMinutes(30)),
+                org.mockito.ArgumentMatchers.eq(Duration.ofDays(7)));
+        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 refreshRotatesUnifiedTokenFromCurrentAuthorizationSnapshot() {
+        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", SessionStateService.fingerprint(account, snapshot)));
+        when(repository.findById(52L)).thenReturn(account);
+        when(authorizationLoader.load(account)).thenReturn(snapshot);
+        when(jwtEncoder.encode(any())).thenReturn(encoded);
+        when(encoded.getTokenValue()).thenReturn("domestic-refreshed");
+
+        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.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")),
+                anyString(), org.mockito.ArgumentMatchers.eq(response.refreshToken()),
+                org.mockito.ArgumentMatchers.eq(Duration.ofMinutes(30)),
+                org.mockito.ArgumentMatchers.eq(Duration.ofDays(7)));
+        verify(authorizationLoader).load(account);
+    }
+
+    @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());
+    }
+
+    @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");
+
+        AuthService.ImpersonationTokenResponse response = service.exchangeImpersonationTicket("one-time-code");
+
+        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")),
+                anyString(), org.mockito.ArgumentMatchers.eq(Duration.ofMinutes(15)));
+    }
+}

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

@@ -0,0 +1,281 @@
+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.config.UnifiedJwtProperties;
+import com.baiyue.auth.dto.AccountManagementDtos.ResetPasswordRequest;
+import com.baiyue.auth.dto.LoginRequest;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import com.baiyue.common.core.exception.BizException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.aop.framework.ProxyFactory;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.data.redis.core.ValueOperations;
+import org.springframework.data.redis.core.SetOperations;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.datasource.DataSourceTransactionManager;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.transaction.annotation.AnnotationTransactionAttributeSource;
+import org.springframework.transaction.interceptor.TransactionInterceptor;
+import org.springframework.transaction.support.TransactionTemplate;
+
+import java.time.Duration;
+import java.util.Set;
+import java.util.UUID;
+import java.util.concurrent.*;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+/** Real MyBatis repository, JDBC transactions/row locks and production login/refresh/revocation services.
+ * Redis is an atomic in-memory transport double; this is not a Redis/MySQL environment test. */
+class SessionStateConcurrencyTest {
+    JdbcTemplate authDb, iamDb;
+    DataSourceTransactionManager authTx, iamTx;
+    AuthService auth;
+    AccountManagementService accounts;
+    SessionStateService states;
+    TokenSessionStore sessions;
+    JwtEncoder encoder;
+    AtomicBoolean redisFailure;
+    final ConcurrentMap<String, String> values = new ConcurrentHashMap<>();
+    final ConcurrentMap<String, Set<String>> sets = new ConcurrentHashMap<>();
+
+    @BeforeEach void setup() throws Exception {
+        authDb = database(); iamDb = database();
+        authTx = new DataSourceTransactionManager(authDb.getDataSource());
+        iamTx = new DataSourceTransactionManager(iamDb.getDataSource());
+        authDb.execute("CREATE TABLE auth_account(id BIGINT PRIMARY KEY, username VARCHAR(50),phone VARCHAR(50),"
+            + "password_hash VARCHAR(100),display_name VARCHAR(50),account_status VARCHAR(20),failed_login_count INT,"
+            + "locked_until TIMESTAMP,token_version INT,password_change_required BOOLEAN,default_tenant_id BIGINT,"
+            + "operator_tenant_id BIGINT,default_membership_id BIGINT,default_app_code VARCHAR(20),deleted INT,"
+            + "last_login_at TIMESTAMP,created_at TIMESTAMP,updated_at TIMESTAMP)");
+        authDb.update("INSERT INTO auth_account(id,username,password_hash,account_status,token_version,default_tenant_id,"
+            + "operator_tenant_id,default_membership_id,default_app_code,deleted) VALUES(1,'operator','old-password','ACTIVE',1,7,7,9,'MERCHANT',0)");
+        iamDb.execute("CREATE TABLE authorization_state(id BIGINT PRIMARY KEY, version BIGINT, tenant_version BIGINT, permission VARCHAR(50), warehouse BIGINT, active BOOLEAN)");
+        iamDb.update("INSERT INTO authorization_state VALUES (1,1,1,'write',10,true)");
+
+        var factory = new com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean();
+        factory.setDataSource(authDb.getDataSource());
+        var config = new com.baomidou.mybatisplus.core.MybatisConfiguration();
+        config.setMapUnderscoreToCamelCase(true);
+        config.addMapper(com.baiyue.auth.mapper.AuthAccountMapper.class);
+        factory.setConfiguration(config);
+        var mapper = new org.mybatis.spring.SqlSessionTemplate(factory.getObject())
+            .getMapper(com.baiyue.auth.mapper.AuthAccountMapper.class);
+        var repository = new AuthAccountRepository();
+        ReflectionTestUtils.setField(repository, "mapper", mapper);
+        AuthorizationLoader loader = mock(AuthorizationLoader.class);
+        when(loader.load(any())).thenAnswer(call -> {
+            var tx = new TransactionTemplate(iamTx);
+            tx.setIsolationLevel(org.springframework.transaction.TransactionDefinition.ISOLATION_REPEATABLE_READ);
+            return tx.execute(status -> iamDb.queryForObject("SELECT * FROM authorization_state WHERE id=1", (rs, row) -> {
+                if (!rs.getBoolean("active")) throw new IllegalArgumentException("IAM identity disabled");
+                return new AuthorizationSnapshot(1L, 7L, 9L, "MERCHANT", "MERCHANT", Set.of("OPERATOR"),
+                    Set.of(rs.getString("permission")), rs.getLong("version"), rs.getLong("warehouse"), null,
+                    rs.getLong("tenant_version"));
+            }));
+        });
+        sessions = new TokenSessionStore();
+        ReflectionTestUtils.setField(sessions, "objectMapper", new ObjectMapper());
+        ReflectionTestUtils.setField(sessions, "keyPrefix", "test");
+        ReflectionTestUtils.setField(sessions, "redisTemplate", redis());
+        PasswordEncoder passwords = mock(PasswordEncoder.class);
+        when(passwords.matches(anyString(), anyString())).thenAnswer(c -> c.getArgument(0).equals(c.getArgument(1)));
+        when(passwords.encode(anyString())).thenAnswer(c -> c.getArgument(0));
+        encoder = mock(JwtEncoder.class);
+        when(encoder.encode(any())).thenAnswer(c -> {
+            var claims = ((org.springframework.security.oauth2.jwt.JwtEncoderParameters)c.getArgument(0)).getClaims();
+            return Jwt.withTokenValue(claims.getId()).header("alg", "RS256").claims(m -> m.putAll(claims.getClaims())).build();
+        });
+        var service = new AuthService();
+        ReflectionTestUtils.setField(service, "accountRepository", repository);
+        ReflectionTestUtils.setField(service, "authorizationLoader", loader);
+        ReflectionTestUtils.setField(service, "tokenSessionStore", sessions);
+        ReflectionTestUtils.setField(service, "passwordEncoder", passwords);
+        ReflectionTestUtils.setField(service, "jwtEncoder", encoder);
+        ReflectionTestUtils.setField(service, "properties", new AuthSecurityProperties("issuer", "aud", Duration.ofMinutes(5), Duration.ofHours(1), 5, Duration.ofMinutes(1)));
+        ReflectionTestUtils.setField(service, "signingProperties", new UnifiedJwtProperties("unused", "kid"));
+        auth = transactional(service);
+        var management = new AccountManagementService();
+        ReflectionTestUtils.setField(management, "repository", repository);
+        ReflectionTestUtils.setField(management, "tokenSessionStore", sessions);
+        ReflectionTestUtils.setField(management, "passwordEncoder", passwords);
+        accounts = transactional(management);
+        var state = new SessionStateService();
+        ReflectionTestUtils.setField(state, "accounts", repository);
+        ReflectionTestUtils.setField(state, "authorizationLoader", loader);
+        ReflectionTestUtils.setField(state, "sessions", sessions);
+        states = transactional(state);
+    }
+
+    @Test void lateLoginAfterRevokeBeforeIamCommitCannotUseOldPermissionsOrRefresh() throws Exception {
+        var revoked = new CountDownLatch(1);
+        var snapshotLoaded = new CountDownLatch(1);
+        var committed = new CountDownLatch(1);
+        doAnswer(c -> {
+            snapshotLoaded.countDown(); await(committed);
+            var claims = ((org.springframework.security.oauth2.jwt.JwtEncoderParameters)c.getArgument(0)).getClaims();
+            return Jwt.withTokenValue(claims.getId()).header("alg", "RS256").claims(m -> m.putAll(claims.getClaims())).build();
+        }).when(encoder).encode(any());
+        ExecutorService pool = Executors.newFixedThreadPool(2);
+        try {
+            Future<?> change = pool.submit(() -> {
+                new TransactionTemplate(iamTx).executeWithoutResult(tx -> {
+                    iamDb.update("UPDATE authorization_state SET version=version+1, permission='read' WHERE id=1");
+                    accounts.revokeSessions(Set.of(1L));
+                    revoked.countDown(); await(snapshotLoaded);
+                });
+                committed.countDown();
+            });
+            await(revoked);
+            var login = pool.submit(() -> auth.login(new LoginRequest("operator", "old-password")));
+            var stale = login.get(5, TimeUnit.SECONDS); change.get(5, TimeUnit.SECONDS);
+            // Access and state were written AFTER revoke, yet the first post-commit request is denied.
+            assertThat(values).containsKey("test:access:" + stale.accessToken());
+            assertThatThrownBy(() -> states.validate(stale.accessToken(), 1L)).isInstanceOf(BizException.class);
+            assertThatThrownBy(() -> auth.refresh(stale.refreshToken())).isInstanceOf(BizException.class);
+            var fresh = auth.login(new LoginRequest("operator", "old-password"));
+            assertThat(states.validate(fresh.accessToken(), 1L)).isTrue();
+            assertThat(fresh.authorities()).containsExactly("read");
+            assertThatThrownBy(() -> auth.refresh(stale.refreshToken())).isInstanceOf(BizException.class);
+        } finally { committed.countDown(); pool.shutdownNow(); }
+    }
+
+    @Test void passwordResetWaitsForConcurrentLoginThenInvalidatesAccessAndRefresh() throws Exception {
+        var loaded = new CountDownLatch(1); var release = new CountDownLatch(1);
+        doAnswer(c -> {
+            loaded.countDown(); await(release);
+            var claims = ((org.springframework.security.oauth2.jwt.JwtEncoderParameters)c.getArgument(0)).getClaims();
+            return Jwt.withTokenValue(claims.getId()).header("alg", "RS256").claims(m -> m.putAll(claims.getClaims())).build();
+        }).when(encoder).encode(any());
+        ExecutorService pool = Executors.newFixedThreadPool(2);
+        try {
+            var login = pool.submit(() -> auth.login(new LoginRequest("operator", "old-password")));
+            await(loaded);
+            var resetting = new CountDownLatch(1);
+            var reset = pool.submit(() -> { resetting.countDown(); accounts.resetPassword(1L, new ResetPasswordRequest("new-password", false), false); });
+            await(resetting);
+            assertThatThrownBy(() -> reset.get(100, TimeUnit.MILLISECONDS)).isInstanceOf(TimeoutException.class);
+            release.countDown();
+            var old = login.get(5, TimeUnit.SECONDS); reset.get(5, TimeUnit.SECONDS);
+            assertThat(authDb.queryForObject("SELECT token_version FROM auth_account WHERE id=1", Integer.class)).isEqualTo(2);
+            assertThatThrownBy(() -> states.validate(old.accessToken(), 1L)).isInstanceOf(BizException.class);
+            assertThatThrownBy(() -> auth.refresh(old.refreshToken())).isInstanceOf(BizException.class);
+        } finally { release.countDown(); pool.shutdownNow(); }
+    }
+
+    @Test void failedRevocationRollsBackAuthAndIamAndDoesNotReportSuccess() {
+        var old = auth.login(new LoginRequest("operator", "old-password"));
+        redisFailure.set(true);
+        assertThatThrownBy(() -> new TransactionTemplate(iamTx).executeWithoutResult(tx -> {
+            iamDb.update("UPDATE authorization_state SET version=version+1, active=false WHERE id=1");
+            accounts.revokeSessions(Set.of(1L));
+        })).isInstanceOf(BizException.class);
+        redisFailure.set(false);
+        assertThat(authDb.queryForObject("SELECT token_version FROM auth_account WHERE id=1", Integer.class)).isEqualTo(1);
+        assertThat(iamDb.queryForObject("SELECT version FROM authorization_state WHERE id=1", Long.class)).isEqualTo(1);
+        assertThat(states.validate(old.accessToken(), 1L)).isTrue();
+    }
+
+    @Test void committedIamVersionRejectsResidualSessionWhenNoRedisDeletionHappens() {
+        var old = auth.login(new LoginRequest("operator", "old-password"));
+        new TransactionTemplate(iamTx).executeWithoutResult(tx ->
+            iamDb.update("UPDATE authorization_state SET tenant_version=tenant_version+1 WHERE id=1"));
+        assertThatThrownBy(() -> states.validate(old.accessToken(), 1L)).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> auth.refresh(old.refreshToken())).isInstanceOf(BizException.class);
+        var current = auth.login(new LoginRequest("operator", "old-password"));
+        assertThat(states.validate(current.accessToken(), 1L)).isTrue();
+        iamDb.update("UPDATE authorization_state SET warehouse=20 WHERE id=1");
+        assertThatThrownBy(() -> states.validate(current.accessToken(), 1L)).isInstanceOf(BizException.class);
+    }
+
+    @Test void iamRollbackPreservesFingerprintAndOtherUserCannotUseSession() {
+        var old = auth.login(new LoginRequest("operator", "old-password"));
+        new TransactionTemplate(iamTx).executeWithoutResult(tx -> {
+            iamDb.update("UPDATE authorization_state SET version=version+1, permission='read' WHERE id=1");
+            tx.setRollbackOnly();
+        });
+        assertThat(states.validate(old.accessToken(), 1L)).isTrue();
+        assertThatThrownBy(() -> states.validate(old.accessToken(), 2L)).isInstanceOf(BizException.class);
+        var refreshed = auth.refresh(old.refreshToken());
+        assertThat(states.validate(refreshed.accessToken(), 1L)).isTrue();
+    }
+
+    @Test void lostRevokeAcknowledgementRollsBackIamButCannotRestoreOldAuthSession() {
+        var old = auth.login(new LoginRequest("operator", "old-password"));
+        assertThatThrownBy(() -> new TransactionTemplate(iamTx).executeWithoutResult(tx -> {
+            iamDb.update("UPDATE authorization_state SET version=version+1, permission='read' WHERE id=1");
+            accounts.revokeSessions(Set.of(1L));
+            throw new IllegalStateException("Auth response timed out after its commit");
+        })).isInstanceOf(IllegalStateException.class);
+        assertThat(iamDb.queryForObject("SELECT permission FROM authorization_state WHERE id=1", String.class)).isEqualTo("write");
+        assertThat(authDb.queryForObject("SELECT token_version FROM auth_account WHERE id=1", Integer.class)).isEqualTo(2);
+        assertThatThrownBy(() -> states.validate(old.accessToken(), 1L)).isInstanceOf(BizException.class);
+        var fresh = auth.login(new LoginRequest("operator", "old-password"));
+        assertThat(states.validate(fresh.accessToken(), 1L)).isTrue();
+        assertThat(fresh.authorities()).containsExactly("write");
+    }
+
+    @Test void disabledCustomerOrMemberAndUnavailableIamRejectAccessAndRefresh() {
+        var old = auth.login(new LoginRequest("operator", "old-password"));
+        // No Redis deletion: the authoritative identity gate alone closes the session.
+        iamDb.update("UPDATE authorization_state SET active=false, tenant_version=tenant_version+1 WHERE id=1");
+        assertThatThrownBy(() -> states.validate(old.accessToken(), 1L)).isInstanceOf(IllegalArgumentException.class);
+        assertThatThrownBy(() -> auth.refresh(old.refreshToken())).isInstanceOf(IllegalArgumentException.class);
+        iamDb.update("UPDATE authorization_state SET active=true WHERE id=1");
+        var fresh = auth.login(new LoginRequest("operator", "old-password"));
+        iamDb.execute("DROP TABLE authorization_state");
+        assertThatThrownBy(() -> states.validate(fresh.accessToken(), 1L)).isInstanceOf(org.springframework.dao.DataAccessException.class);
+        assertThatThrownBy(() -> auth.refresh(fresh.refreshToken())).isInstanceOf(org.springframework.dao.DataAccessException.class);
+    }
+
+    @SuppressWarnings("unchecked") private StringRedisTemplate redis() {
+        redisFailure = new AtomicBoolean();
+        var redis = mock(StringRedisTemplate.class);
+        ValueOperations<String,String> ops = mock(ValueOperations.class);
+        SetOperations<String,String> index = mock(SetOperations.class);
+        when(redis.opsForValue()).thenReturn(ops); when(redis.opsForSet()).thenReturn(index);
+        doAnswer(c -> { values.put(c.getArgument(0), c.getArgument(1)); return null; }).when(ops).set(anyString(), anyString(), any(Duration.class));
+        when(ops.get(anyString())).thenAnswer(c -> values.get(c.getArgument(0)));
+        when(ops.getAndDelete(anyString())).thenAnswer(c -> values.remove(c.getArgument(0)));
+        when(redis.hasKey(anyString())).thenAnswer(c -> values.containsKey(c.getArgument(0)));
+        when(redis.delete(anyString())).thenAnswer(c -> values.remove(c.getArgument(0)) != null);
+        when(redis.delete(anyCollection())).thenAnswer(c -> {
+            if (redisFailure.get()) throw new org.springframework.data.redis.RedisConnectionFailureException("offline");
+            long count = 0; for (Object key : (java.util.Collection<?>) c.getArgument(0)) if (values.remove(key) != null) count++;
+            return count;
+        });
+        when(index.members(anyString())).thenAnswer(c -> sets.getOrDefault(c.getArgument(0), Set.of()));
+        doAnswer(c -> {
+            Set<String> members = sets.computeIfAbsent(c.getArgument(0), key -> ConcurrentHashMap.newKeySet());
+            for (int i=1; i<c.getArguments().length; i++) members.add(c.getArgument(i));
+            return 1L;
+        }).when(index).add(anyString(), any(String[].class));
+        return redis;
+    }
+
+    static JdbcTemplate database() {
+        var ds = new JdbcDataSource(); ds.setURL("jdbc:h2:mem:" + UUID.randomUUID() + ";MODE=MySQL;DB_CLOSE_DELAY=-1;LOCK_TIMEOUT=3000");
+        return new JdbcTemplate(ds);
+    }
+    @SuppressWarnings("unchecked") <T> T transactional(T target) {
+        var factory = new ProxyFactory(target); factory.setProxyTargetClass(true);
+        factory.addAdvice(new TransactionInterceptor(authTx, new AnnotationTransactionAttributeSource()));
+        return (T) factory.getProxy();
+    }
+    static void await(CountDownLatch latch) {
+        try { if (!latch.await(5, TimeUnit.SECONDS)) throw new AssertionError("Barrier timed out"); }
+        catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new AssertionError(e); }
+    }
+}

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

@@ -3,9 +3,15 @@ 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;
@@ -18,32 +24,48 @@ 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"),
+                "state", "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"));
+                new TokenSessionStore.RefreshSession(42L, "jti-1", "state"));
         when(values.getAndDelete(anyString())).thenReturn(json);
-        TokenSessionStore store = new TokenSessionStore(redis, new ObjectMapper(), "baiyue:auth");
 
         TokenSessionStore.RefreshSession session = store.consume("raw-refresh");
 
@@ -55,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

@@ -1,5 +1,10 @@
 # Common Audit 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
 - 负责业务审计事件采集、注解切面、敏感字段脱敏以及日志/HTTP 输出。

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,31 @@
+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;
+
+/**
+ * 审计 Outbox 的 RocketMQ 发布配置。
+ * 该配置与基础审计配置隔离：未引入 RocketMQ 的服务仍可使用 HTTP 审计投递。
+ */
+@AutoConfiguration(after = BaiyueAuditAutoConfiguration.class)
+@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(); }
 }

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

@@ -14,6 +14,8 @@ public @interface BusinessAudit {
     String event();
     String resourceType();
     String resourceId() default ""; // SpEL, e.g. #request.orderId
+    /** 业务数据所属客户 ID 的可选 SpEL；平台代客操作未配置时自动识别名为 tenantId 的参数。 */
+    String tenantId() default "";
     String description() default "";
     boolean captureBefore() default true;
     boolean captureAfter() default true;