K12Study/docs/plan/modules-todo/upms-auth-frontend-backend-implementation.md

问题陈述

基于现有 auth 与 upms 模块完成前后端可联调实现（含 Web 管理端与小程序最小可用链路），从“占位/硬编码”升级为“数据库驱动 + 令牌会话治理 + 端侧鉴权一致”。

当前状态（已确认）

• auth 已有登录/刷新/当前用户接口，但服务实现为硬编码用户，未校验真实凭据，refresh 逻辑未做轮换与持久化（backend/auth/src/main/java/com/k12study/auth/controller/AuthController.java (18-47), backend/auth/src/main/java/com/k12study/auth/service/AuthService.java (18-74)）。
• upms 已有 routes/currentUser/areas/tenants/departments 接口，但全部为静态返回；且模块配置排除了数据源与 MyBatis 自动装配（backend/upms/src/main/java/com/k12study/upms/service/impl/UpmsQueryServiceImpl.java (17-132), backend/upms/src/main/resources/application.yml (1-18)）。
• 数据库脚本已提供认证与权限组织核心表（含 auth.tb_auth_refresh_token、auth.tb_auth_login_audit、upms.tb_sys_*、班级/文件/站内信相关表），但代码未接入（init/pg/auth/10_create_auth_tables.sql (1-64), init/pg/upms/10_create_upms_tables.sql (1-437)）。
• Web 端当前仅保存 accessToken，未使用 refreshToken，且路由初始化失败时会回退默认路由，缺少严格登录守卫（frontend/src/pages/LoginPage.tsx (17-21), frontend/src/utils/storage.ts (1-12), frontend/src/router/AppRouter.tsx (56-83)）。
• 小程序端仅有 API/request 封装，无登录页、无 token 持久化与鉴权头注入（app/src/api/auth.js (1-13), app/src/utils/request.js (1-53)）。
• 目标能力与约束已在模块计划中明确（docs/plan/modules/auth.md (1-40), docs/plan/modules/upms.md (1-40)）。

实施方案

1) 契约与模块边界收口

统一 auth/upms 前后端契约与字段口径：

1. auth 令牌 claims 扩展为 userId/tenantId/tenantPath/deptId/deptPath/adcode/roleCodes/clientType/sessionId，并在 API DTO 中显式化。
2. upms 保留现有 5 个查询接口，同时补齐模块计划中已冻结的班级、文件、站内信接口。
3. 将 Web 与 Mini 的端侧约束（clientType + roleCodes）纳入统一鉴权输入，避免服务内散落判断。

2) 后端 Auth 实现

1. 接入持久层（PostgreSQL + MyBatis Plus），补齐 auth 模块数据源配置与仓储层。
2. 实现真实登录链路：账号/手机号凭据校验、用户状态校验、角色准入校验（Mini 仅 STUDENT）。
3. 实现 refresh token 持久化与“一次一换”轮换：写入 tb_auth_refresh_token、刷新时撤销旧 token 并发放新 token。
4. 实现登录与刷新审计：写入 tb_auth_login_audit，记录成功/失败与关键上下文。
5. 加入学生端会话上限策略（上限 3，超限淘汰最久未活跃会话）。

3) 后端 UPMS 实现

1. 以数据库查询替换 UpmsQueryServiceImpl 静态数据，按租户上下文返回 routes/currentUser/areas/tenants/departments。
2. 建立角色-菜单-权限聚合链路（必要时补齐 user-role 关系表与增量 SQL）。
3. 增加班级、文件、站内信接口实现，统一租户隔离与对象存在性校验。
4. 统一 upms 返回结构与前端类型，避免前端做业务字段兜底。

4) 前端实现（Web + Mini）

1. Web：重构会话层（access + refresh + 当前用户），增加登录守卫与 401 自动刷新/失效登出。
2. Web：动态路由加载改为“鉴权成功后加载”，移除未登录默认路由回退。
3. Web：补齐 upms 数据消费页（至少 currentUser/组织树/消息入口）的真实接口接入。
4. Mini：补齐登录与 token 持久化，request 层注入 Authorization，处理 token 续期与失效。
5. Mini：按 clientType=MINI + role=STUDENT 约束仅开放学生端能力。

5) 联调与验收

1. 在 boot-dev（本地聚合）与 gateway + auth + upms（分布式）两种模式分别完成联调验证。
2. 验证项覆盖：登录/刷新/当前用户、动态路由、组织树、Mini 登录、站内信已读链路。
3. 运行后端编译与前端构建，补充最小接口/服务测试，确认关键鉴权与租户隔离场景通过。

交付顺序

建议按“Auth 后端 -> UPMS 后端 -> Web 前端 -> Mini 前端 -> 双模式联调”执行，避免前端先行导致接口反复改动。