优化

2026-08-08 12:01:45 +08:00
parent 1a2f598c9a
commit a35cd868b9
56 changed files with 7178 additions and 735 deletions
@@ -1,36 +1,20 @@
 # Gateway 模块指引

-## 职责边界
+## 职责与边界

- 统一承接前端流量，负责服务路由、CORS、JWT/Redis 会话校验、商户端与平台端访问域隔离及 Swagger 聚合。
- 网关完成入口认证，但业务服务仍必须执行客户归属、数据范围和权限校验；业务编排不得写入网关。Claim 中的 `tenant_id > 0` 当前是客户隔离兼容字段，`tenant_id=0` 是平台技术作用域，不得据此新增租户切换或真实租户访问域。
+- 负责路由、CORS、JWT/Redis 会话校验、平台/客户访问域隔离、请求标识和 Swagger 聚合。
+- 只做入口认证，不做业务编排；下游服务仍必须校验客户归属、数据范围和权限。

-## 快速索引
+## 模块入口与验证

-| 功能 | 入口 |
-|---|---|
-| 应用入口 | `src/main/java/com/baiyue/gateway/BaiyueGatewayApplication.java` |
-| Security WebFilterChain | `config/GatewaySecurityConfig.java` |
-| 商户/平台访问域 | `config/AppScopeAuthorizationManager.java` |
-| JWT 与安全配置项 | `config/GatewaySecurityProperties.java` |
-| Redis 会话过滤 | `config/RedisTokenSessionWebFilter.java` |
-| CORS | `config/GatewayCorsConfiguration.java`、`GatewayCorsProperties.java` |
-| 请求标识 | `filter/CorrelationIdWebFilter.java`；包括预检和安全失败响应的 `X-Request-Id` |
-| 可信身份头清理/注入 | `filter/TrustedIdentityHeaderFilter.java` |
-| 本地路由 | `src/main/resources/application.yml` |
-| 国内环境与 Swagger 聚合 | `src/main/resources/application-cn.yml`、`../config/nacos/{local,cn}/gateway.yml` |
-| 访问域与 CORS 测试 | `src/test/java/com/baiyue/gateway/config/` |
+- 应用：`BaiyueGatewayApplication.java`
+- Security/访问域：`config/GatewaySecurityConfig.java`、`AppScopeAuthorizationManager.java`
+- 会话/CORS/请求头：`config/RedisTokenSessionWebFilter.java`、`GatewayCorsConfiguration.java`、`filter/TrustedIdentityHeaderFilter.java`、`CorrelationIdWebFilter.java`
+- 路由配置：`src/main/resources/application*.yml`、`../config/nacos/{local,cn}/gateway.yml`
+- 测试：`src/test/java/com/baiyue/gateway/`；`mvn -pl gateway -am test`

-## 修改与验证
+## 修改约束与分期

- 新增服务路由时同步检查本地与 Nacos 配置、访问域、公开路径和 Swagger 聚合；前端只访问网关。
- 禁止信任客户端自行传入的身份头；Token Claim、Redis Key 变化要与 `auth/`、`common-security/` 同步。
- 普通业务响应由下游服务返回 HTTP 200 + body code；Gateway 自身的认证/会话失败仍保留真实 401/403，不能为了统一响应改成 HTTP 200。
- CORS 生产来源必须为明确 HTTPS 域名，不能放宽为 `*`。
- 从父目录运行 `mvn -pl gateway -am test`。
-
-## 分期快速索引
-
- 一期：承载 Admin/Client 登录后的应用域、JWT 会话、客户隔离和 CORS；先读 `../../docs/一期/README.md` 与一期闭环设计，网关只做入口认证，不替代 `auth`、`iam`、`order` 的业务授权。
- 二期：新增到仓、测量、计费和第三方测量联调路由时，先读 `../../docs/二期/README.md`、主流程和联调报告；保持 `tenant_id>0` 客户隔离、`tenant_id=0` 平台公共资源及内部服务令牌边界，不把内部测量接口暴露到外部 Gateway。
- 三期：当前 NO-GO；不得提前开放分柜、订舱、PDA、装柜、报关或港务路由。待 `../../docs/三期/三期需求确认表.md` 的 P3 阻断项解除并锁定契约后，再同步公开路径、App Scope、权限码和 Swagger 聚合。
+- 新增路由同步检查本地/Nacos、App Scope、CORS、公开路径和 Swagger；不得暴露内部令牌接口。
+- 一期承载登录后 Admin/Client 入口；二期接入到仓/测量/计费公开路由但保持内部测量接口隔离；三期当前 NO-GO，不开放分柜、订舱、PDA、装柜、报关或港务路由。
+- 三期先读 `../../docs/三期/三期需求确认表.md`，解除阻断并冻结契约后再改网关。