# 跨区域认证与服务通信契约

## 适用范围

- 本契约适用于 Admin、Client、国内头程服务、海外网关、尾程服务、海外仓资源服务及跨区域事件桥接。
- 业务范围仍按对应阶段和模块文档确定；本文件只冻结跨区域账号、请求路由、服务鉴权和事件通信边界。
- 开发/测试同机共置及生产国内/海外双控制面的实际部署拓扑、Nacos、数据库和 Event Bridge 规划见[双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)。

## 统一账号与 Token

- Admin、Client 只维护一套前端和一套用户账号体系；用户登录和 Token 签发统一归国内头程 Auth，不得为海外仓再创建独立登录、账号或权限体系。
- 统一使用 RS256/JWKS 信任链，但区分 Token 用途：国内登录/刷新时由同一 Auth 同时签发国内 Token 和短时海外 Token；海外 Token 限定海外 Audience，只携带稳定身份、客户范围与版本声明，不携带角色或权限集。
- 平台 `WAREHOUSE_PICKER` 必须在 IAM 成员关系中绑定一个启用的实际海外收货仓；Auth 将该绑定以可空 `overseas_warehouse_id` Claim 同步写入国内与海外 Token，海外 Token 同时携带账号 `token_version`。该 Claim 只用于已绑定的平台仓管员，页面和 PDA 请求不得传入或覆盖仓库身份；修改或清空仓绑定时 IAM 必须调用 Auth 撤销该账号全部会话并递增 `token_version`，随后重新签发 Token。
- 用户只登录一次，由前端统一认证模块按目标 API 自动选择 Token，不在页面或业务模块中分叉登录逻辑。
- JWKS 只暴露公钥验证能力，不暴露私钥；国内服务验证登录 Token 并结合 Redis 会话实现即时退出和权限变更，海外业务服务不访问国内 Redis。`gateway-overseas` 对普通 Admin/Client 海外接口验证海外 Token 的签名、Issuer、Audience、有效期、应用域和客户范围，再按 `userId/tenantId/permissionVersion` 从 Lastleg 安全投影取得当前海外授权快照；仅 `/api/pda/**` 在本地验签后，以内部服务身份向 Auth 发送 `userId/tokenVersion/overseasWarehouseId` 做无缓存实时核对。该调用不得传递 raw Token 或用户凭据，Auth 超时、不可用、账号停用、版本或仓绑定不一致均 fail-closed。
- 本期普通 Admin/Client 海外 Token 的即时失效范围固定为 IAM 投影的账号停用、客户停用和权限版本推进；Gateway 向 Lastleg 安全投影仅发送 `userId/tenantId/permissionVersion`，旧 Token 被拒绝后客户端必须退出并重新登录。`token_version` 仍是海外 JWT 必填 Claim，但其权威实时比对只用于上述 PDA→Auth 链；普通 Admin/Client 的退出、密码重置或普通会话撤销依赖短时 Token 自然过期，不得宣称已由 Lastleg 即时撤销。

## 区域 API 路由

- 一套前端使用国内、海外两个区域 API Base：国内业务直连 `gateway/`，海外仓业务直连 `gateway-overseas/`，再由海外网关路由到 `lastleg-service/`、`warehouse-overseas-service/` 和海外部署的公共服务。
- 日常海外请求不得经国内 Gateway 中转。区域地址、Token 选择和刷新由环境配置与统一 API/认证层处理，业务页面不得感知部署区域差异。
- 海外浏览器请求的具体 Audience、Claim 和路由以前端项目、`auth/`、`gateway-overseas/` 最近的 `AGENTS.md` 与实际配置为准；修改其中任一项时必须联查全部生产者和消费者。

## 跨区域事件与服务身份

- 头程与海外仓的数据流转使用 MQ 的 Outbox → Inbox、事件幂等、重试和死信机制。
- 事件使用版本化信封、事件 ID、业务键、来源/目标区域和 Payload 哈希，不携带用户 Access Token。
- 费用由海外仓发布事件，头程 Finance 消费并按来源快照入账；财务状态机和结算口径仍由财务契约冻结，海外服务不得自行定义。
- MQ 使用独立的服务身份、TLS 和 ACL；服务间事件鉴权与用户 JWT 鉴权分开。只有明确的同步 HTTP 内部接口才使用内部服务令牌。
- 修改事件时联查 `common-event-contract/`、`event-bridge-service/`、生产服务、消费服务、幂等记录、重试/死信和契约测试。

### 国内仓库目录同步读取

- 国内 `warehouse-service` 是 Warehouse ID、类型、状态、地址和能力的唯一权威。海外数据库不得复制仓库、地址或服务能力主表。
- `warehouse-overseas-service` 只保存库位、托盘、资源锁及其国内 `warehouseId` 引用；资源写入和 Lastleg PDA 仓绑定校验通过受内部服务令牌保护的国内只读目录完成。
- 只允许平台共享、`OVERSEAS`、`ACTIVE` 且启用 `RECEIVING` 的仓作为海外实际收货仓。低频正结果可缓存 30 分钟，空目录、不存在和停用结果不得长缓存。
- FBA 目的仓同样只以国内 `warehouse-service` 的平台公共主数据为权威，但语义与海外实际收货仓严格分离：Admin 候选使用 `warehouseType=FBA&status=ACTIVE` 的平台仓库分页；Lastleg 写入通过受内部服务令牌保护的 `/internal/warehouses/0/{warehouseId}/active` 读取当前事实，并继续校验 `warehouseType=FBA` 及 ID/编码/名称一致。`OVERSEAS`、`OVERSEAS_PARTNER` 或 `DOMESTIC` 均不得作为 FBA 目的仓。

### IAM 安全事件海外投影冻结

- `IamUserStatusChanged`、`IamTenantStatusChanged`、`IamPermissionVersionChanged` V1 固定由 Lastleg 独立安全入口 `/internal/lastleg/security/v1/events` 消费；不得投递到 Lastleg 的 LoadingCompletedConsumer。
- 安全状态只使用 `ACTIVE`/`DISABLED`：`IamTenantStatusChanged` 仅在 IAM 客户业务状态为 `ACTIVE` 时发布 `ACTIVE`，`PROFILE_REQUIRED`、`PENDING`、`REJECTED`、`DISABLED`、`ARCHIVED` 及其他不可用状态统一折叠为 `DISABLED`。Lastleg 只校验该两态安全快照，不解释国内建档/审核工作流。
- Event Bridge 只按冻结的 eventType→consumer URL 选择下游，不解析状态、权限版本或 payload 业务字段。海外业务事件仍投 Lastleg，国内回流事件仍投 Firstleg。
- Lastleg 以 MySQL `ll_security_event_inbox` 和 `ll_security_projection` 为可靠来源：eventId 相同 hash 相同幂等，异 hash 冲突；聚合版本只单调推进，旧版本标记 STALE，同版本异 hash 冲突。Redis 仅为提交后写入的可重建镜像，授权校验不依赖 Redis 默认放行。
- 海外 Gateway 对全部 `/api/**` 在本地 JWT 验签后，传递 `userId/tenantId/permissionVersion` 到 Lastleg 安全入口。Lastleg 校验通过时返回该版本的角色与海外权限快照，Gateway 清除外部伪造的授权头后，以内部服务令牌保护的可信头传给海外业务服务。业务服务必须同时验证 JWT 和内部服务令牌，不得从 JWT 回退读取完整权限集。用户停用返回 A0401；客户停用或 Token 权限版本不一致返回 A0403；安全投影、SQL 或调用链不可用均 fail-closed。PDA 在此基础上继续执行 Auth 仓绑定实时核验。
- Auth 的登录、刷新和海外 Token 兑换响应在响应体中返回当前 `roles/authorities` 授权快照；国内与海外 JWT 都只保留主体、客户、成员、应用、版本和海外仓绑定等最小身份 Claim，不携带角色或权限集合。客户端可用响应快照做入口展示或本地前置提示，但每次业务请求的最终授权仍由 Gateway/Lastleg 的实时投影决定；客户端不得再从 JWT 解析角色或权限，也不得把响应快照作为绕过服务端校验的依据。
- 新客户创建、审核激活以及新用户授权均由 IAM 在业务事务内写初始安全事件。开发阶段不提供历史账号长期 Bootstrap 或兼容入口；固定 `platform_admin` 由 Lastleg 数据库基线初始化 version=0 的 USER 投影，所有既有开发账号（包括 `platform_admin`）必须在部署后由总控按 IAM 当前事实一次性重建 AUTHORIZATION 授权快照，不纳入产品代码。任何缺失投影继续 fail-closed，不能在 Lastleg 运行时代填或默认放行。

## 修改与验收

- Token、Audience、Claim、JWKS、API Base 或刷新策略变化时，至少联查 Auth、IAM、Admin/Client 统一认证层、国内/海外 Gateway、`common-security/` 和目标海外服务。
- `overseas_warehouse_id` 变化时还需联查 IAM 平台用户维护、海外 PDA、Lastleg 收货会话及 Warehouse Overseas 共享仓校验；验收必须同时覆盖未绑定拒绝、非仓管角色禁止绑定和换仓后旧 Token 失效。
- 跨区域事件变化时同步检查事件版本、Payload 哈希、Outbox、Inbox、重复投递、失败重试、死信和全部实际消费者。
- 本文件是跨区域通信的公共事实来源；项目和模块 `AGENTS.md` 只保留执行所需摘要及本文件入口，不复制完整协议。