# Overseas Gateway 模块指引

> 本目录为退役源码，已退出根 POM 和部署映射。下文仅记录旧实现，不是现行规则。当前入口读 `../gateway/AGENTS.md`，认证读 `../auth/AGENTS.md` 与 `../../docs/统一认证与服务通信契约.md`；退役清理按 `../../docs/测试环境单机部署与配置契约.md` 核对实际引用与运行证据。不得恢复双 Token、专用安全投影或重新加入构建。

## 职责边界

- 负责海外 API 统一入口、路由、RS256/JWKS 验签、Audience 和必要 Claims 校验。
- 不保存签名私钥，不依赖国内 Redis 会话，不在网关实现尾程业务逻辑。
- 历史路由与身份实现只用于追溯；现行认证按 `../../docs/统一认证与服务通信契约.md`。

## 快速索引

| 功能 | 入口 |
|---|---|
| 安全链配置 | `src/main/java/com/baiyue/gateway/config/GatewaySecurityConfig.java` |
| Audience 校验 | `config/AudienceJwtValidator.java` |
| 必要 Claims 校验 | `config/RequiredClaimsJwtValidator.java` |
| PDA 换仓即时失效 | `filter/PdaSessionValidationFilter.java`、`HttpPdaSessionValidationClient.java`、`config/PdaSessionValidationProperties.java`；仅 `/api/pda/**` 本地验签后同步核对 Auth，任何异常 fail-closed |
| 海外安全事件即时失效 | `filter/OverseasSecurityProjectionFilter.java`、`HttpOverseasSecurityValidationClient.java`；全部 `/api/**` 本地验签后核对海外安全投影，用户/客户停用与权限版本不一致立即拒绝，并取回当前角色/权限快照 |
| 安全配置项 | `config/GatewaySecurityProperties.java` |
| 可信身份与授权头传递 | `filter/TrustedIdentityHeaderFilter.java`、`filter/OverseasSecurityProjectionFilter.java`；先清除外部伪造头，再以内部服务令牌保护投影快照 |
| 环境配置 | `src/main/resources/application.yml`、`../config/nacos/` |
| 浏览器业务路由 | `src/main/resources/application-overseas.yml`；Lastleg 显式覆盖 `/api/merchant/v1/last-leg/**`、`/api/platform/v1/last-leg/**`，Warehouse 仅显式覆盖平台仓库资源路径 |
| 海外 PDA 路由 | 设备端 `../../apps/pda-overseas-uniapp/`，服务端入口 `/api/pda/v1/last-leg/**`；必须在 Gateway 路由中显式声明并保持海外 Token/权限校验，不得让设备直连 Lastleg |
| 测试 | `src/test/java/com/baiyue/gateway/config/` |

## 安全规则

- 生产令牌 `aud` 必须包含 `lastleg-api`，并包含配置要求的身份声明。
- 网关必须清除外请求伪造的可信身份与授权头，仅传递验签并核对安全投影后生成的上下文；业务服务必须验证内部服务令牌。
- JWKS 地址、Issuer 和 Audience 必须外部配置；不得在源码写死生产密钥。
- merchant、platform 与 PDA 路径分别显式维护路由和授权边界；新增 PDA Controller 不会自动成为公网路由，Gateway 未声明前不得把设备链路标记为已联通。

## 修改与验证

- 本模块已退出聚合，不能从根使用 `mvn -pl gateway-overseas`；当前路由变更验证 `gateway` 及调用端，执行根 `scripts/gateway-route-contract.test.mjs`。
- 安全变更覆盖合法令牌、错误 Audience、缺失 Claims、过期/错误签名和身份头伪造测试。