K12Study/docs/plan/modules/auth.md

问题陈述

将 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 角色，老师与机构角色不开放小程序登录。