K12Study/docs/plan/modules/gateway.md

问题陈述

将 gateway 从“仅转发 auth/upms 的静态网关”升级为全域统一接入层，负责鉴权透传、租户隔离防线、端侧能力边界控制（尤其小程序学生端）。

当前状态（已确认）

• 架构定义中网关应承接 auth/upms/course/question/achievement/recommendation 多域入口。参考 docs/architecture/logical-view.md (24-41)。
• 现有网关路由仅配置 auth 与 upms 两条，且目标地址硬编码 localhost。参考 backend/gateway/src/main/resources/application.yml (1-30)。
• JwtRelayFilter 仅做 token 校验并透传 X-User-Id/X-Username/X-Display-Name/X-Tenant-Id/X-Dept-Id。参考 backend/gateway/src/main/java/com/k12study/gateway/filter/JwtRelayFilter.java (1-79)、backend/common/common-core/src/main/java/com/k12study/common/core/constants/SecurityConstants.java (1-13)。
• API 设计要求对外统一 /api/*，且后续需扩展到 course/question/ai。参考 docs/architecture/api-design.md (1-82)。

模块拆分与设计细节

1) 子模块边界

• gw-routing：静态路由基线 + 服务发现路由（后续可接 nacos）。
• gw-authn：JWT 解析、白名单、令牌有效性检查。
• gw-authz：基于角色/权限码的接口级访问控制。
• gw-tenant-guard：租户上下文一致性校验与越权拦截。
• gw-client-policy：按 clientType + roleCodes 执行端侧能力约束（Web 与 Mini 分流，且角色可见能力分层）。

2) 路由与协议策略

• 扩展路由：/api/course/**、/api/question/**、/api/ai/**（以及后续 achievement）。
• 统一注入：traceId、用户上下文、端侧上下文，确保下游服务具备完整鉴权条件。
• 统一错误响应结构：code/message/data/traceId，避免当前 401 响应与标准不一致。

3) 租户隔离与端侧约束

• 对路径参数、query、body 中 tenant_id/class_id/course_id 做一致性校验（与 token tenant 比对）。
• 对小程序令牌执行角色准入：仅 clientType=MINI 且含 STUDENT 角色可访问；TEACHER/ORG_ADMIN 角色直接拒绝 mini 端访问。
• 对小程序学生令牌在网关层执行“只允许课堂练习/课后作业相关 API”，屏蔽课件/资料类接口。
• 为图检索与向量检索入口统一加租户隔离过滤（至少 tenant_id，必要时 tenant_path + class scope）。

问题点与风险

• 当前仅透传 tenant_id，缺 tenant_path/adcode/clientType，难以实现层级隔离与端侧细分授权。
• 路由静态且服务少，course/question/ai 接入后若不先做网关收口，跨域鉴权规则会分散在业务服务。
• 401 响应未附 traceId，排障链路不完整。
• 白名单仅按路径匹配，缺 method 维度与来源限制，存在误开放风险。

需确认的设计决策

• 首期是否在网关做“端侧能力强约束”还是只做鉴权透传（推荐首期即强约束）。
• 路由配置是否直接切到配置中心统一管理，还是先保持本地静态配置再迁移。
• 租户校验失败返回码与错误语义（401/403/422）统一口径。