39 lines
4.3 KiB
Markdown
39 lines
4.3 KiB
Markdown
# 问题陈述
|
||
基于现有 `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 前端 -> 双模式联调”执行，避免前端先行导致接口反复改动。
|