baiyue-firstleg/gateway/AGENTS.md

Gateway 模块指引

职责边界

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

快速索引

功能	入口
应用入口	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/

修改与验证

• 新增服务路由时同步检查本地与 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 聚合。