4.2 KiB
当前用户上下文设计
目标
为后端业务代码提供统一的当前用户读取能力，并将 GET /api/v1/auth/me 扩展为返回主平台 Token 中经验证的完整用户资料。
范围
- SSO 成功后，从已验证的主平台 Token payload 提取并本地持久化用户资料。
- 提供可注入的当前用户读取服务，供任意已认证业务接口使用。
- 扩展
/api/v1/auth/me返回的 DTO。 - 不改变本系统 JWT 的主体语义、角色授权方式或本地账号密码登录流程。
用户资料契约
当前用户对象和 /api/v1/auth/me 的 data 使用下列 camelCase 字段。roleid 与 studentid 保持主平台字段拼写，以避免调用方转换。
| 字段 | 来源 | 说明 |
|---|---|---|
schoolId / schoolName |
Token schoolId / schoolName |
学校标识与名称 |
collegeId / collegeName |
Token collegeId / collegeName |
院系标识与名称 |
majorId / majorName |
Token majorId / majorName |
专业标识与名称 |
roleid |
Token roleid |
主平台原始角色 ID；不替换为本系统角色 ID |
userId |
Token userId |
主平台用户 ID，也是本地用户 ID 与 JWT subject |
username |
Token username |
用户登录账号 |
name |
Token name |
用户姓名 |
classId / className |
Token classId / className |
班级标识与名称 |
studentid |
Token studentid |
学号/学生标识 |
标识类字段以字符串持久化和返回，以兼容主平台可能出现的非纯数字编码；userId 是唯一的数值主键，解析为 long。
架构与数据流
主平台 Token
-> PlatformTokenVerifier（验签、校验必填资料）
-> PlatformActor（完整的已验证身份）
-> PlatformIdentityProjectionService（事务内更新 sys_user、快照、授权角色）
-> platform_user_snapshot
本系统 JWT subject(userId)
-> CurrentUserService
-> platform_user_snapshot
-> 业务代码 / GET /api/v1/auth/me
PlatformTokenVerifier 只能在签名、登录时间和现有身份声明均通过后，才构造含完整资料的 PlatformActor。它校验 userId、username、name、roleid 必填，并将 roleid 映射为既有 TEACHER 或 STUDENT 以保留 Spring Security 授权行为。学校、院系、专业、班级和 studentid 允许为空，以兼容教师等不具备学生组织信息的身份。
PlatformIdentityProjectionService 在现有事务中更新扩展后的 platform_user_snapshot。快照是当前用户资料的唯一读取源；业务请求不会重新解析主平台 Token，也不会查询主平台数据库。
CurrentUserService 位于 security.application，从 Spring Security 的 Jwt 读取 subject，查询快照并返回不可变当前用户对象。未认证、subject 不是正整数或快照不存在时抛出既有 UNAUTHORIZED 业务异常。Controller 只调用该服务并将结果转换/直接作为响应 DTO 返回，不直接访问 Mapper。
持久化
扩展 platform_user_snapshot，增加学校、院系、专业、班级、主平台原始角色 ID 和学生标识字段。schema.sql 需同时覆盖新环境建表和已有数据库的幂等升级；不引入 Flyway。快照中保留 role_key 作为本系统授权映射，新增的 roleid 独立保存主平台原始值。
API 与错误处理
GET /api/v1/auth/me 仍要求本系统 Bearer JWT，并返回既有 ApiResponse 包装。成功响应只包含上述用户资料字段，不包含密码、主平台 Token、刷新令牌或快照同步时间。未认证或快照缺失时维持现有未授权错误语义。
测试
- Token 验证测试：完整资料被解析进已验证身份；缺少必填字段的 Token 被拒绝。
- 身份投影测试：扩展资料写入并在重复 SSO 时更新，不产生重复角色关联。
- 当前用户服务/接口测试：持有本系统 JWT 时能读取全部字段；无效 subject 与不存在快照返回未授权。
- 运行项目规定的 Maven 测试与打包命令。
非目标
- 不向业务 Controller 暴露用户、角色或快照 CRUD。
- 不在每次业务请求时调用主平台或解析主平台 Token。
- 不在本系统 JWT 中复制完整用户资料。