# 问题陈述
将 `auth` 从当前演示版 JWT 发放器升级为可用于 Web 教师/机构端与小程序学生端的统一认证中心，确保令牌生命周期、租户上下文与审计链路可落地。
## 当前状态（已确认）
* 架构与 API 对 `auth` 的约束是登录、刷新、当前用户三类基础接口。参考 `docs/architecture/api-design.md (12-16)`、`docs/architecture/logical-view.md (7-9)`。
* 现有 `AuthController` 仅暴露 `/auth/tokens`、`/auth/tokens/refresh`、`/auth/users/current`。参考 `backend/auth/src/main/java/com/k12study/auth/controller/AuthController.java (1-49)`。
* `AuthService` 当前为占位实现：默认 `admin`、不校验密码、refresh token 直接复用 access token 生成逻辑。参考 `backend/auth/src/main/java/com/k12study/auth/service/AuthService.java (18-74)`。
* `init` 已提供 `auth.tb_auth_refresh_token` 与 `auth.tb_auth_login_audit`，但代码尚未接入。参考 `init/pg/auth/10_create_auth_tables.sql (1-54)`。
* 当前需求已调整为“学生手机号绑定 + 手动登录”，不使用 openid/微信取号能力；现有代码尚未体现该约束。参考 `docs/AI智能学习系统功能清单.md (1-30)`。
## 模块拆分与设计细节
### 1) 子模块边界
* `auth-credential`：账号密码、手机号绑定、手动登录、验证码/密码校验。
* `auth-token`：access/refresh 双令牌、旋转、撤销、过期策略。
* `auth-context`：输出标准 claims（userId/tenantId/tenantPath/deptId/adcode/roleCodes/clientType）。
* `auth-audit`：登录审计、刷新审计、异常登录行为记录。
### 2) 认证通道设计
* Web（机构/教师）：账号密码 + 可选验证码。
* Mini（学生）：手机号 + 手动输入凭证登录；“手机号+密码”与“手机号+短信验证码”为并列可选登录主流程，不依赖微信 code/openid。
* 统一返回 token 结构，但按 `clientType` 写入不同策略（如 mini 更短 access TTL、更严格 refresh 轮换）。
* 学生身份主键统一使用平台 `user_id` + 绑定手机号，不引入 openid 作为账号主索引。
### 3) 令牌与隔离策略
* access token 仅短期有效；refresh token 必须入库（`tb_auth_refresh_token`）并采用“每次刷新强制轮换”策略（one-time refresh token）与撤销机制。
* claims 必须包含租户上下文与端侧上下文，供 gateway 与业务域执行“租户隔离 + 端能力限制”。
* `currentUser` 不再回退静态默认用户，统一由 token + 用户表读取。
### 4) 与小程序约束联动
* 身份区分以 `role` 为准：小程序仅允许 `STUDENT` 角色登录；`TEACHER/ORG_ADMIN` 角色不发放 mini 可用令牌。
* 为后续“课程仅展示课堂练习/课后作业”提供 `clientType=MINI` + `role=STUDENT` 的稳定判定依据。
* 学生允许在不同家长手机登录，同一学生并发会话上限固定为 `3`，超限时淘汰最久未活跃会话。
## 问题点与风险
* 现有 refresh 流程不安全（refresh token 与 access token同构），无法实现撤销与会话治理。
* 代码未接 `tb_auth_refresh_token`/`tb_auth_login_audit`，审计与风控链路缺失。
* 若角色体系未在 token 与网关策略中一致生效，会导致小程序端角色越权风险。
* JWT claims 字段不足（缺 tenant_path/adcode/clientType），会放大跨租户与跨端越权风险。
* 跨设备登录场景下，若缺少设备会话治理（会话上限/异地提醒/强制下线），共享手机会增加账号滥用风险。
## 已确定的实现决策
* 学生手动登录提供双可选主流程：`手机号+密码` 与 `手机号+短信验证码`。
* refresh token 采用“每次刷新强制轮换”策略。
* 学生跨多家长手机登录并发会话上限固定为 `3`，超限淘汰最近最久未活跃会话。
* 身份区分以 `role` 为准；小程序仅开放 `STUDENT` 角色，老师与机构角色不开放小程序登录。