33 lines
3.1 KiB
Markdown
33 lines
3.1 KiB
Markdown
# 问题陈述
|
||
将 `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）统一口径。
|