Skip to content
项目
群组
代码片段
帮助
当前项目
正在载入...
登录 / 注册
切换导航面板
S
studyweb
项目
项目
详情
活动
周期分析
仓库
仓库
文件
提交
分支
标签
贡献者
图表
比较
统计图
议题
0
议题
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
CI / CD
CI / CD
流水线
作业
日程
统计图
Wiki
Wiki
代码片段
代码片段
成员
成员
折叠边栏
关闭边栏
活动
图像
聊天
创建新问题
作业
提交
问题看板
Open sidebar
project
studyweb
Commits
299ccb35
提交
299ccb35
authored
7月 17, 2026
作者:
caifuming
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
cfm_7/17完善后端配置(先写的静态进行功能展示)
上级
58c1d2b9
隐藏空白字符变更
内嵌
并排
正在显示
19 个修改的文件
包含
3654 行增加
和
236 行删除
+3654
-236
.env
.env
+21
-0
DataInitializer.java
...ain/java/com/platform/backend/config/DataInitializer.java
+420
-95
DepartmentController.java
...com/platform/backend/controller/DepartmentController.java
+3
-3
MenuController.java
.../java/com/platform/backend/controller/MenuController.java
+5
-5
RoleController.java
.../java/com/platform/backend/controller/RoleController.java
+5
-5
UserController.java
.../java/com/platform/backend/controller/UserController.java
+28
-17
RolePermissionRepository.java
...platform/backend/repository/RolePermissionRepository.java
+12
-1
RoleRepository.java
.../java/com/platform/backend/repository/RoleRepository.java
+5
-0
UserRepository.java
.../java/com/platform/backend/repository/UserRepository.java
+1
-0
UserRoleRepository.java
...a/com/platform/backend/repository/UserRoleRepository.java
+1
-0
CustomUserDetailsService.java
...m/platform/backend/security/CustomUserDetailsService.java
+22
-8
PermissionService.java
...java/com/platform/backend/security/PermissionService.java
+134
-0
SecurityExpression.java
...ava/com/platform/backend/security/SecurityExpression.java
+67
-0
MenuService.java
...c/main/java/com/platform/backend/service/MenuService.java
+6
-0
RoleService.java
...c/main/java/com/platform/backend/service/RoleService.java
+7
-1
user-module-schema.sql
sql/user-module-schema.sql
+288
-0
user-module-任务文档.md
平台文档/user-module-任务文档.md
+1613
-101
用户模块需求与验收标准文档.md
平台文档/用户模块需求与验收标准文档.md
+576
-0
角色与权限模型( RBAC)设计文档.md
平台文档/角色与权限模型( RBAC)设计文档.md
+440
-0
没有找到文件。
.env
0 → 100644
浏览文件 @
299ccb35
# MySQL (主机端口: 13306)
MYSQL_HOST=localhost
MYSQL_PORT=13306
MYSQL_ROOT_PASSWORD=root123
MYSQL_DATABASE=studyweb
MYSQL_USER=studyweb
MYSQL_PASSWORD=studyweb123
# Redis (主机端口: 16379)
REDIS_HOST=localhost
REDIS_PORT=16379
REDIS_PASSWORD=studyweb123
# MinIO (主机端口: 19000 API / 19001 Console)
MINIO_ENDPOINT=localhost:19000
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin123
# Loki (主机端口: 13100)
LOKI_HOST=localhost
LOKI_PORT=13100
backend/apps/backend-app/src/main/java/com/platform/backend/config/DataInitializer.java
浏览文件 @
299ccb35
...
@@ -2,8 +2,10 @@ package com.platform.backend.config;
...
@@ -2,8 +2,10 @@ package com.platform.backend.config;
import
com.platform.backend.entity.Permission
;
import
com.platform.backend.entity.Permission
;
import
com.platform.backend.entity.Role
;
import
com.platform.backend.entity.Role
;
import
com.platform.backend.entity.RolePermission
;
import
com.platform.backend.entity.User
;
import
com.platform.backend.entity.User
;
import
com.platform.backend.repository.PermissionRepository
;
import
com.platform.backend.repository.PermissionRepository
;
import
com.platform.backend.repository.RolePermissionRepository
;
import
com.platform.backend.repository.RoleRepository
;
import
com.platform.backend.repository.RoleRepository
;
import
com.platform.backend.repository.UserRepository
;
import
com.platform.backend.repository.UserRepository
;
import
lombok.RequiredArgsConstructor
;
import
lombok.RequiredArgsConstructor
;
...
@@ -14,8 +16,7 @@ import org.springframework.security.crypto.password.PasswordEncoder;
...
@@ -14,8 +16,7 @@ import org.springframework.security.crypto.password.PasswordEncoder;
import
org.springframework.stereotype.Component
;
import
org.springframework.stereotype.Component
;
import
org.springframework.transaction.annotation.Transactional
;
import
org.springframework.transaction.annotation.Transactional
;
import
java.util.Arrays
;
import
java.util.*
;
import
java.util.List
;
@Slf4j
@Slf4j
@Component
@Component
...
@@ -25,75 +26,203 @@ public class DataInitializer implements CommandLineRunner {
...
@@ -25,75 +26,203 @@ public class DataInitializer implements CommandLineRunner {
private
final
UserRepository
userRepository
;
private
final
UserRepository
userRepository
;
private
final
RoleRepository
roleRepository
;
private
final
RoleRepository
roleRepository
;
private
final
PermissionRepository
permissionRepository
;
private
final
PermissionRepository
permissionRepository
;
private
final
RolePermissionRepository
rolePermissionRepository
;
private
final
PasswordEncoder
passwordEncoder
;
private
final
PasswordEncoder
passwordEncoder
;
private
final
JdbcTemplate
jdbcTemplate
;
private
final
JdbcTemplate
jdbcTemplate
;
@Override
@Override
public
void
run
(
String
...
args
)
{
public
void
run
(
String
...
args
)
{
// 数据库列修正(防止旧表 device 为 VARCHAR(500) 导致插入失败;DDL 自动提交,无需事务)
migrateLoginLogColumns
();
migrateLoginLogColumns
();
migrateProjectSoftDeleteUniqueIndexes
();
migrateProjectSoftDeleteUniqueIndexes
();
migrateProjectModuleConstraints
();
// 以下操作在事务内执行
initRolesAndPermissions
();
initRolesAndPermissions
();
}
}
@Transactional
@Transactional
public
void
initRolesAndPermissions
()
{
public
void
initRolesAndPermissions
()
{
//
创建预设角色
//
========== 1. 创建角色 ==========
Role
adminRole
=
ensureRole
(
"管理员"
,
"ROLE_ADMIN"
,
"全系统配置、用户管理"
,
1
);
Role
adminRole
=
ensureRole
(
"管理员"
,
"ROLE_ADMIN"
,
"全系统配置、用户管理"
,
1
);
ensureRole
(
"主管"
,
"ROLE_SUPERVISOR"
,
"审核学员、内容终审"
,
1
);
Role
supervisorRole
=
ensureRole
(
"主管"
,
"ROLE_SUPERVISOR"
,
"审核学员、内容终审"
,
1
);
ensureRole
(
"导师"
,
"ROLE_MENTOR"
,
"答辩评审、学员指导"
,
1
);
Role
mentorRole
=
ensureRole
(
"导师"
,
"ROLE_MENTOR"
,
"答辩评审、学员指导"
,
1
);
ensureRole
(
"学员"
,
"ROLE_STUDENT"
,
"参与实训、提交产物"
,
1
);
Role
studentRole
=
ensureRole
(
"学员"
,
"ROLE_STUDENT"
,
"参与实训、提交产物"
,
1
);
// 创建基础权限
// ========== 2. 创建所有权限点 ==========
ensurePermission
(
"project:read"
,
"查看项目"
,
"project"
);
// 项目管理模块 (5)
ensurePermission
(
"project:view"
,
"查看项目列表/详情"
,
"project"
);
ensurePermission
(
"project:create"
,
"创建项目"
,
"project"
);
ensurePermission
(
"project:create"
,
"创建项目"
,
"project"
);
ensurePermission
(
"project:update"
,
"更新项目"
,
"project"
);
ensurePermission
(
"project:update"
,
"更新项目"
,
"project"
);
ensurePermission
(
"project:delete"
,
"删除项目"
,
"project"
);
ensurePermission
(
"project:delete"
,
"删除项目(软删除)"
,
"project"
);
ensurePermission
(
"training:read"
,
"查看实训"
,
"training"
);
ensurePermission
(
"project:simple_list"
,
"获取项目下拉列表"
,
"project"
);
ensurePermission
(
"training:submit"
,
"提交实训"
,
"training"
);
ensurePermission
(
"training:review"
,
"审核实训"
,
"training"
);
// 标签管理模块 (4)
ensurePermission
(
"defense:review"
,
"答辩评审"
,
"defense"
);
ensurePermission
(
"tag:view"
,
"查看标签列表"
,
"tag"
);
ensurePermission
(
"audit:review"
,
"主管审核"
,
"audit"
);
ensurePermission
(
"tag:create"
,
"创建标签"
,
"tag"
);
ensurePermission
(
"user:read"
,
"查看用户"
,
"user"
);
ensurePermission
(
"tag:update"
,
"更新标签"
,
"tag"
);
ensurePermission
(
"tag:delete"
,
"删除标签"
,
"tag"
);
// 难度配置模块 (4)
ensurePermission
(
"difficulty:view"
,
"查看难度评分卡"
,
"difficulty"
);
ensurePermission
(
"difficulty:config"
,
"配置评分卡维度/权重"
,
"difficulty"
);
ensurePermission
(
"difficulty:calibrate"
,
"AI 难度校准(一键校准)"
,
"difficulty"
);
ensurePermission
(
"difficulty:ai_score_view"
,
"查看 AI 评分结果"
,
"difficulty"
);
// 项目推荐模块 (4)
ensurePermission
(
"recommend:request"
,
"发起 AI 项目推荐"
,
"recommend"
);
ensurePermission
(
"recommend:view"
,
"查看推荐列表/历史"
,
"recommend"
);
ensurePermission
(
"recommend:choose"
,
"采纳推荐项目"
,
"recommend"
);
ensurePermission
(
"recommend:ignore"
,
"忽略推荐项目"
,
"recommend"
);
// 知识点模块 (5)
ensurePermission
(
"knowledge:view"
,
"查看知识点列表/详情"
,
"knowledge"
);
ensurePermission
(
"knowledge:create"
,
"手动添加知识点"
,
"knowledge"
);
ensurePermission
(
"knowledge:update"
,
"编辑知识点"
,
"knowledge"
);
ensurePermission
(
"knowledge:delete"
,
"删除知识点"
,
"knowledge"
);
ensurePermission
(
"knowledge:ai_extract"
,
"AI 触发知识点提取"
,
"knowledge"
);
// 文件管理模块 (2)
ensurePermission
(
"file:upload"
,
"上传项目资料"
,
"file"
);
ensurePermission
(
"file:download"
,
"获取签名下载 URL"
,
"file"
);
// 实训任务管理模块 (8)
ensurePermission
(
"training:create"
,
"创建实训任务"
,
"training"
);
ensurePermission
(
"training:view_own"
,
"查看本人的实训"
,
"training"
);
ensurePermission
(
"training:view_assigned"
,
"查看分配给我的"
,
"training"
);
ensurePermission
(
"training:view_all"
,
"查看全部实训"
,
"training"
);
ensurePermission
(
"training:update"
,
"更新实训任务"
,
"training"
);
ensurePermission
(
"training:delete"
,
"删除实训任务"
,
"training"
);
ensurePermission
(
"training:assign_mentor"
,
"分配/变更导师"
,
"training"
);
ensurePermission
(
"training:view_detail"
,
"查看实训任务详情"
,
"training"
);
// 预览管理模块 (4)
ensurePermission
(
"preview:view_knowledge"
,
"查看预览知识点"
,
"preview"
);
ensurePermission
(
"preview:submit"
,
"提交预览完成"
,
"preview"
);
ensurePermission
(
"preview:tak_quiz"
,
"参加预习小测"
,
"preview"
);
ensurePermission
(
"preview:view_progress"
,
"查看预览进度"
,
"preview"
);
// 实操管理模块 (3)
ensurePermission
(
"practice:submit_artifact"
,
"提交实操产物"
,
"practice"
);
ensurePermission
(
"practice:write_report"
,
"撰写实操报告"
,
"practice"
);
ensurePermission
(
"practice:submit_report"
,
"提交实操报告"
,
"practice"
);
// 答辩管理模块 (5)
ensurePermission
(
"defense:apply"
,
"申请答辩"
,
"defense"
);
ensurePermission
(
"defense:review"
,
"答辩评审(评分+结论)"
,
"defense"
);
ensurePermission
(
"defense:audit"
,
"答辩审核(主管级)"
,
"defense"
);
ensurePermission
(
"defense:view"
,
"查看答辩记录/详情"
,
"defense"
);
ensurePermission
(
"defense:pending_list"
,
"查看待办答辩列表"
,
"defense"
);
// 历史记录模块 (3)
ensurePermission
(
"history:view_own"
,
"查看本人历史实训记录"
,
"history"
);
ensurePermission
(
"history:view_department"
,
"查看本部门历史实训记录"
,
"history"
);
ensurePermission
(
"history:view_all"
,
"查看全部历史实训记录"
,
"history"
);
// 容器管理模块 (2)
ensurePermission
(
"container:use"
,
"使用容器沙箱"
,
"container"
);
ensurePermission
(
"container:manage"
,
"管理容器(创建/销毁/续期)"
,
"container"
);
// 缺陷记录模块 (2)
ensurePermission
(
"defect:view"
,
"查看缺陷记录列表"
,
"defect"
);
ensurePermission
(
"defect:add"
,
"手动添加缺陷记录"
,
"defect"
);
// 进阶匹配模块 (3)
ensurePermission
(
"advanced:accept"
,
"采纳进阶推荐"
,
"advanced"
);
ensurePermission
(
"advanced:reject"
,
"忽略进阶推荐"
,
"advanced"
);
ensurePermission
(
"advanced:view"
,
"查看进阶匹配记录"
,
"advanced"
);
// 能力画像模块 (1)
ensurePermission
(
"profile:view"
,
"查看学员能力画像"
,
"profile"
);
// 用户管理模块 (6)
ensurePermission
(
"user:view_list"
,
"查看用户列表"
,
"user"
);
ensurePermission
(
"user:create"
,
"创建用户"
,
"user"
);
ensurePermission
(
"user:create"
,
"创建用户"
,
"user"
);
ensurePermission
(
"user:update"
,
"更新用户"
,
"user"
);
ensurePermission
(
"user:update"
,
"更新用户信息"
,
"user"
);
ensurePermission
(
"user:delete"
,
"删除用户"
,
"user"
);
ensurePermission
(
"user:delete"
,
"删除用户(软删除)"
,
"user"
);
ensurePermission
(
"user:assign-role"
,
"分配角色"
,
"user"
);
ensurePermission
(
"user:view_detail"
,
"查看用户详情"
,
"user"
);
ensurePermission
(
"user:*"
,
"用户模块全部权限"
,
"user"
);
// 创建管理员账号
// 角色权限管理模块 (6)
if
(!
userRepository
.
existsByUsername
(
"admin"
))
{
ensurePermission
(
"role:view"
,
"查看角色列表/详情"
,
"role"
);
User
admin
=
new
User
();
ensurePermission
(
"role:create"
,
"创建角色"
,
"role"
);
admin
.
setUsername
(
"admin"
);
ensurePermission
(
"role:update"
,
"更新角色/权限分配"
,
"role"
);
admin
.
setPassword
(
passwordEncoder
.
encode
(
"admin123"
));
ensurePermission
(
"role:delete"
,
"删除角色"
,
"role"
);
admin
.
setRealName
(
"管理员"
);
ensurePermission
(
"role:assign_user"
,
"分配用户角色"
,
"role"
);
admin
.
setEmail
(
"admin@example.com"
);
ensurePermission
(
"permission:assign"
,
"分配角色权限"
,
"role"
);
admin
.
setRoleId
(
adminRole
.
getId
());
admin
.
setStatus
(
1
);
// 导师工作台模块 (1)
admin
.
setIsDeleted
(
0
);
ensurePermission
(
"mentor:dashboard"
,
"查看导师工作台统计"
,
"mentor_dashboard"
);
admin
.
setMustChangePassword
(
0
);
userRepository
.
save
(
admin
);
// 部门管理模块 (3)
log
.
info
(
"测试账号已创建: admin / admin123 (roleId={})"
,
adminRole
.
getId
());
ensurePermission
(
"dept:create"
,
"创建部门"
,
"dept"
);
}
else
{
ensurePermission
(
"dept:update"
,
"更新部门"
,
"dept"
);
// admin 已存在:确保密码正确(schema-init.sql 的 INSERT IGNORE 用的是旧哈希)
ensurePermission
(
"dept:delete"
,
"删除部门"
,
"dept"
);
User
admin
=
userRepository
.
findByUsername
(
"admin"
).
orElse
(
null
);
if
(
admin
!=
null
)
{
// 菜单管理模块 (4)
String
expectedHash
=
passwordEncoder
.
encode
(
"admin123"
);
ensurePermission
(
"menu:view"
,
"查看菜单树"
,
"menu"
);
// 如果密码哈希不匹配(schema-init 插入了错误哈希),强制更新
ensurePermission
(
"menu:create"
,
"创建菜单"
,
"menu"
);
if
(!
passwordEncoder
.
matches
(
"admin123"
,
admin
.
getPassword
()))
{
ensurePermission
(
"menu:update"
,
"更新菜单"
,
"menu"
);
admin
.
setPassword
(
expectedHash
);
ensurePermission
(
"menu:delete"
,
"删除菜单"
,
"menu"
);
admin
.
setRoleId
(
adminRole
.
getId
());
admin
.
setStatus
(
1
);
// ========== 3. 建立角色-权限关联 ==========
admin
.
setIsDeleted
(
0
);
// 管理员 - 全部权限
admin
.
setMustChangePassword
(
0
);
Map
<
String
,
Long
>
permMap
=
getPermissionMap
();
userRepository
.
save
(
admin
);
assignAllPermissions
(
adminRole
.
getId
(),
permMap
);
log
.
info
(
"admin 账号密码已修正为 admin123(schema-init 旧哈希已替换)"
);
}
else
{
// 主管 - 按矩阵分配
log
.
info
(
"admin 账号已存在且密码正确,跳过"
);
assignPermissions
(
supervisorRole
.
getId
(),
permMap
,
}
"project:view"
,
"project:simple_list"
,
}
"tag:view"
,
}
"difficulty:view"
,
"difficulty:calibrate"
,
"difficulty:ai_score_view"
,
"recommend:view"
,
"knowledge:view"
,
"training:view_all"
,
"training:view_detail"
,
"preview:view_progress"
,
"defense:audit"
,
"defense:view"
,
"defense:pending_list"
,
"history:view_all"
,
"container:manage"
,
"advanced:view"
,
"profile:view"
,
"user:view_list"
,
"user:view_detail"
,
"role:view"
,
"permission:assign"
,
"mentor:dashboard"
);
// 导师 - 按矩阵分配
assignPermissions
(
mentorRole
.
getId
(),
permMap
,
"project:view"
,
"project:simple_list"
,
"tag:view"
,
"difficulty:view"
,
"knowledge:view"
,
"training:view_assigned"
,
"training:view_detail"
,
"preview:view_progress"
,
"defense:review"
,
"defense:view"
,
"defense:pending_list"
,
"history:view_department"
,
"defect:view"
,
"defect:add"
,
"profile:view"
,
"user:view_detail"
,
"role:view"
,
"mentor:dashboard"
);
// 学员 - 按矩阵分配
assignPermissions
(
studentRole
.
getId
(),
permMap
,
"project:view"
,
"project:simple_list"
,
"recommend:request"
,
"recommend:view"
,
"recommend:choose"
,
"recommend:ignore"
,
"knowledge:view"
,
"training:create"
,
"training:view_own"
,
"training:update"
,
"training:delete"
,
"training:view_detail"
,
"preview:view_knowledge"
,
"preview:submit"
,
"preview:tak_quiz"
,
"practice:submit_artifact"
,
"practice:write_report"
,
"practice:submit_report"
,
"defense:apply"
,
"defense:view"
,
"history:view_own"
,
"container:use"
,
"defect:view"
,
"advanced:accept"
,
"advanced:reject"
,
"advanced:view"
,
"profile:view"
);
// ========== 4. 创建管理员账号 ==========
initAdminUser
(
adminRole
);
log
.
info
(
"RBAC 权限体系初始化完成:{} 个角色,{} 个权限点"
,
4
,
permMap
.
size
());
}
}
private
Role
ensureRole
(
String
name
,
String
code
,
String
desc
,
int
isPreset
)
{
private
Role
ensureRole
(
String
name
,
String
code
,
String
desc
,
int
isPreset
)
{
...
@@ -117,68 +246,264 @@ public class DataInitializer implements CommandLineRunner {
...
@@ -117,68 +246,264 @@ public class DataInitializer implements CommandLineRunner {
});
});
}
}
/**
private
Map
<
String
,
Long
>
getPermissionMap
()
{
* 修正 user_login_log 表的列类型,防止 device 列超长导致整条日志插入失败。
Map
<
String
,
Long
>
map
=
new
HashMap
<>();
* <ul>
permissionRepository
.
findAll
().
forEach
(
p
->
map
.
put
(
p
.
getPermissionCode
(),
p
.
getId
()));
* <li>device VARCHAR(500) → TEXT</li>
return
map
;
* <li>fail_reason VARCHAR(100) → VARCHAR(255)</li>
}
* </ul>
*/
private
void
assignPermissions
(
Long
roleId
,
Map
<
String
,
Long
>
permMap
,
String
...
codes
)
{
for
(
String
code
:
codes
)
{
Long
permId
=
permMap
.
get
(
code
);
if
(
permId
!=
null
)
{
assignRolePermission
(
roleId
,
permId
);
}
}
}
private
void
assignAllPermissions
(
Long
roleId
,
Map
<
String
,
Long
>
permMap
)
{
for
(
Long
permId
:
permMap
.
values
())
{
assignRolePermission
(
roleId
,
permId
);
}
}
private
void
assignRolePermission
(
Long
roleId
,
Long
permId
)
{
boolean
exists
=
rolePermissionRepository
.
findByRoleId
(
roleId
).
stream
()
.
anyMatch
(
rp
->
rp
.
getPermissionId
().
equals
(
permId
));
if
(!
exists
)
{
RolePermission
rp
=
new
RolePermission
();
rp
.
setRoleId
(
roleId
);
rp
.
setPermissionId
(
permId
);
rp
.
setCreatedAt
(
java
.
time
.
LocalDateTime
.
now
());
rolePermissionRepository
.
save
(
rp
);
}
}
private
void
initAdminUser
(
Role
adminRole
)
{
if
(!
userRepository
.
existsByUsername
(
"admin"
))
{
User
admin
=
new
User
();
admin
.
setUsername
(
"admin"
);
admin
.
setPassword
(
passwordEncoder
.
encode
(
"admin123"
));
admin
.
setRealName
(
"管理员"
);
admin
.
setEmail
(
"admin@example.com"
);
admin
.
setRoleId
(
adminRole
.
getId
());
admin
.
setStatus
(
1
);
admin
.
setIsDeleted
(
0
);
admin
.
setMustChangePassword
(
0
);
userRepository
.
save
(
admin
);
log
.
info
(
"测试账号已创建: admin / admin123 (roleId={})"
,
adminRole
.
getId
());
}
else
{
User
admin
=
userRepository
.
findByUsername
(
"admin"
).
orElse
(
null
);
if
(
admin
!=
null
&&
!
passwordEncoder
.
matches
(
"admin123"
,
admin
.
getPassword
()))
{
admin
.
setPassword
(
passwordEncoder
.
encode
(
"admin123"
));
admin
.
setRoleId
(
adminRole
.
getId
());
admin
.
setStatus
(
1
);
admin
.
setIsDeleted
(
0
);
admin
.
setMustChangePassword
(
0
);
userRepository
.
save
(
admin
);
log
.
info
(
"admin 账号密码已修正为 admin123"
);
}
}
}
private
void
migrateLoginLogColumns
()
{
private
void
migrateLoginLogColumns
()
{
try
{
try
{
// 修正 device 字段(User-Agent 通常远超 500 字符)
jdbcTemplate
.
execute
(
"ALTER TABLE user_login_log MODIFY COLUMN device TEXT"
);
jdbcTemplate
.
execute
(
"ALTER TABLE user_login_log MODIFY COLUMN device TEXT"
);
log
.
info
(
"[migrate] user_login_log.device → TEXT OK"
);
log
.
info
(
"[migrate] user_login_log.device → TEXT OK"
);
jdbcTemplate
.
execute
(
"ALTER TABLE user_login_log MODIFY COLUMN fail_reason VARCHAR(255)"
);
// 修正 fail_reason 字段(避免较长的失败原因被截断)
jdbcTemplate
.
execute
(
"ALTER TABLE user_login_log MODIFY COLUMN fail_reason VARCHAR(255)"
);
log
.
info
(
"[migrate] user_login_log.fail_reason → VARCHAR(255) OK"
);
log
.
info
(
"[migrate] user_login_log.fail_reason → VARCHAR(255) OK"
);
}
catch
(
Exception
e
)
{
}
catch
(
Exception
e
)
{
log
.
warn
(
"[migrate] user_login_log 列修正失败
(可能已是最优类型或表不存在)
: {}"
,
e
.
getMessage
());
log
.
warn
(
"[migrate] user_login_log 列修正失败: {}"
,
e
.
getMessage
());
}
}
}
}
/**
* 项目删除按文档要求是软删除。旧库里 name 单列唯一会让已软删项目继续占用名称,
* 因此删除单列唯一索引,保留服务层的“未删除项目名称不可重复”校验。
*/
private
void
migrateProjectSoftDeleteUniqueIndexes
()
{
private
void
migrateProjectSoftDeleteUniqueIndexes
()
{
dropSingleColumnUniqueIndexIfExists
(
"proj_internal_project"
,
"name"
);
dropSingleColumnUniqueIndexIfExists
(
"proj_internal_project"
,
"name"
);
dropSingleColumnUniqueIndexIfExists
(
"proj_annotation_project"
,
"name"
);
dropSingleColumnUniqueIndexIfExists
(
"proj_annotation_project"
,
"name"
);
}
}
/**
* 项目模块数据库补丁:
* 1. 补齐文档要求的组合索引。
* 2. 补齐关键外键约束。
* 3. 先清理会导致加外键失败的历史脏数据,避免影响现有接口启动。
*/
private
void
migrateProjectModuleConstraints
()
{
ensureCompositeIndex
(
"proj_internal_project"
,
"idx_department_difficulty"
,
"department_id, difficulty_level"
);
normalizeInvalidCalibrationUsers
();
ensureForeignKey
(
"proj_internal_project"
,
"fk_proj_internal_project_department"
,
"department_id"
,
"user_department"
,
"id"
,
"SET NULL"
);
ensureForeignKey
(
"proj_github_project"
,
"fk_proj_github_project_seed_project"
,
"seed_project_id"
,
"proj_internal_project"
,
"id"
,
"SET NULL"
);
ensureForeignKey
(
"proj_difficulty_calibration"
,
"fk_proj_difficulty_calibration_score"
,
"score_id"
,
"proj_difficulty_score"
,
"id"
,
"SET NULL"
);
ensureForeignKey
(
"proj_difficulty_calibration"
,
"fk_proj_difficulty_calibration_user"
,
"calibration_by"
,
"user_user"
,
"id"
,
"SET NULL"
);
ensureForeignKey
(
"kp_knowledge_dependency"
,
"fk_kp_knowledge_dependency_knowledge"
,
"knowledge_id"
,
"kp_knowledge_point"
,
"id"
,
"CASCADE"
);
ensureForeignKey
(
"kp_knowledge_dependency"
,
"fk_kp_knowledge_dependency_prerequisite"
,
"prerequisite_id"
,
"kp_knowledge_point"
,
"id"
,
"CASCADE"
);
}
private
void
dropSingleColumnUniqueIndexIfExists
(
String
tableName
,
String
columnName
)
{
private
void
dropSingleColumnUniqueIndexIfExists
(
String
tableName
,
String
columnName
)
{
try
{
try
{
List
<
String
>
indexNames
=
jdbcTemplate
.
queryForList
(
"""
List
<
String
>
indexNames
=
jdbcTemplate
.
queryForList
(
"""
SELECT s.INDEX_NAME
SELECT s.INDEX_NAME
FROM INFORMATION_SCHEMA.STATISTICS s
FROM INFORMATION_SCHEMA.STATISTICS s
JOIN (
JOIN (
SELECT INDEX_NAME, COUNT(*) AS column_count
SELECT INDEX_NAME, COUNT(*) AS column_count
FROM INFORMATION_SCHEMA.STATISTICS
FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?
GROUP BY INDEX_NAME
GROUP BY INDEX_NAME
) c ON c.INDEX_NAME = s.INDEX_NAME
) c ON c.INDEX_NAME = s.INDEX_NAME
WHERE s.TABLE_SCHEMA = DATABASE()
WHERE s.TABLE_SCHEMA = DATABASE()
AND s.TABLE_NAME = ?
AND s.TABLE_NAME = ?
AND s.COLUMN_NAME = ?
AND s.COLUMN_NAME = ?
AND s.NON_UNIQUE = 0
AND s.NON_UNIQUE = 0
AND s.INDEX_NAME <> 'PRIMARY'
AND s.INDEX_NAME <> 'PRIMARY'
AND c.column_count = 1
AND c.column_count = 1
"""
,
"""
,
String
.
class
,
tableName
,
tableName
,
columnName
);
String
.
class
,
tableName
,
tableName
,
columnName
);
for
(
String
indexName
:
indexNames
)
{
for
(
String
indexName
:
indexNames
)
{
jdbcTemplate
.
execute
(
"ALTER TABLE `"
+
tableName
+
"` DROP INDEX `"
+
indexName
+
"`"
);
jdbcTemplate
.
execute
(
"ALTER TABLE `"
+
tableName
+
"` DROP INDEX `"
+
indexName
+
"`"
);
log
.
info
(
"[migrate] {}.{} 单列唯一索引 {} 已删除,软删除项目名称可复用"
,
log
.
info
(
"[migrate] {}.{} 单列唯一索引 {} 已删除"
,
tableName
,
columnName
,
indexName
);
tableName
,
columnName
,
indexName
);
}
}
}
catch
(
Exception
e
)
{
}
catch
(
Exception
e
)
{
log
.
warn
(
"[migrate] {}.{} 单列唯一索引修正失败(可能已修正或表不存在): {}"
,
log
.
warn
(
"[migrate] {}.{} 单列唯一索引修正失败: {}"
,
tableName
,
columnName
,
e
.
getMessage
());
tableName
,
columnName
,
e
.
getMessage
());
}
}
private
void
normalizeInvalidCalibrationUsers
()
{
if
(!
tableExists
(
"proj_difficulty_calibration"
)
||
!
tableExists
(
"user_user"
))
{
return
;
}
try
{
int
updated
=
jdbcTemplate
.
update
(
"""
UPDATE proj_difficulty_calibration c
LEFT JOIN user_user u ON c.calibration_by = u.id
SET c.calibration_by = NULL
WHERE c.calibration_by IS NOT NULL
AND u.id IS NULL
"""
);
if
(
updated
>
0
)
{
log
.
info
(
"[migrate] proj_difficulty_calibration.calibration_by 已清理 {} 条无效引用"
,
updated
);
}
}
catch
(
Exception
e
)
{
log
.
warn
(
"[migrate] proj_difficulty_calibration.calibration_by 无效引用清理失败: {}"
,
e
.
getMessage
());
}
}
private
void
ensureCompositeIndex
(
String
tableName
,
String
indexName
,
String
columnList
)
{
if
(!
tableExists
(
tableName
))
{
return
;
}
try
{
Integer
count
=
jdbcTemplate
.
queryForObject
(
"""
SELECT COUNT(*)
FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = ?
AND INDEX_NAME = ?
"""
,
Integer
.
class
,
tableName
,
indexName
);
if
(
count
!=
null
&&
count
>
0
)
{
return
;
}
jdbcTemplate
.
execute
(
"ALTER TABLE `"
+
tableName
+
"` ADD INDEX `"
+
indexName
+
"` ("
+
columnList
+
")"
);
log
.
info
(
"[migrate] {} 索引 {} 已创建"
,
tableName
,
indexName
);
}
catch
(
Exception
e
)
{
log
.
warn
(
"[migrate] {} 索引 {} 创建失败: {}"
,
tableName
,
indexName
,
e
.
getMessage
());
}
}
private
void
ensureForeignKey
(
String
tableName
,
String
constraintName
,
String
columnName
,
String
referencedTable
,
String
referencedColumn
,
String
onDeleteAction
)
{
if
(!
tableExists
(
tableName
)
||
!
tableExists
(
referencedTable
))
{
return
;
}
try
{
Integer
count
=
jdbcTemplate
.
queryForObject
(
"""
SELECT COUNT(*)
FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = ?
AND CONSTRAINT_NAME = ?
AND CONSTRAINT_TYPE = 'FOREIGN KEY'
"""
,
Integer
.
class
,
tableName
,
constraintName
);
if
(
count
!=
null
&&
count
>
0
)
{
return
;
}
jdbcTemplate
.
execute
(
"ALTER TABLE `"
+
tableName
+
"` "
+
"ADD CONSTRAINT `"
+
constraintName
+
"` "
+
"FOREIGN KEY (`"
+
columnName
+
"`) "
+
"REFERENCES `"
+
referencedTable
+
"` (`"
+
referencedColumn
+
"`) "
+
"ON DELETE "
+
onDeleteAction
+
" ON UPDATE CASCADE"
);
log
.
info
(
"[migrate] {} 外键 {} 已创建"
,
tableName
,
constraintName
);
}
catch
(
Exception
e
)
{
log
.
warn
(
"[migrate] {} 外键 {} 创建失败: {}"
,
tableName
,
constraintName
,
e
.
getMessage
());
}
}
private
boolean
tableExists
(
String
tableName
)
{
try
{
Integer
count
=
jdbcTemplate
.
queryForObject
(
"""
SELECT COUNT(*)
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = ?
"""
,
Integer
.
class
,
tableName
);
return
count
!=
null
&&
count
>
0
;
}
catch
(
Exception
e
)
{
log
.
warn
(
"[migrate] 检查表 {} 是否存在失败: {}"
,
tableName
,
e
.
getMessage
());
return
false
;
}
}
}
}
}
}
backend/apps/backend-app/src/main/java/com/platform/backend/controller/DepartmentController.java
浏览文件 @
299ccb35
...
@@ -55,7 +55,7 @@ public class DepartmentController {
...
@@ -55,7 +55,7 @@ public class DepartmentController {
}
}
@PostMapping
@PostMapping
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('dept:create
')"
)
public
ResponseEntity
<
ApiResponse
<
Department
>>
create
(
@RequestBody
Department
dept
,
public
ResponseEntity
<
ApiResponse
<
Department
>>
create
(
@RequestBody
Department
dept
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] POST /api/v1/departments name={}"
,
dept
.
getName
());
log
.
info
(
"[API] POST /api/v1/departments name={}"
,
dept
.
getName
());
...
@@ -65,7 +65,7 @@ public class DepartmentController {
...
@@ -65,7 +65,7 @@ public class DepartmentController {
}
}
@PutMapping
(
"/{id}"
)
@PutMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('dept:update
')"
)
public
ResponseEntity
<
ApiResponse
<
Department
>>
update
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Department
>>
update
(
@PathVariable
Long
id
,
@RequestBody
Department
dept
,
@RequestBody
Department
dept
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -81,7 +81,7 @@ public class DepartmentController {
...
@@ -81,7 +81,7 @@ public class DepartmentController {
}
}
@DeleteMapping
(
"/{id}"
)
@DeleteMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('dept:delete
')"
)
public
ResponseEntity
<
Void
>
delete
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
public
ResponseEntity
<
Void
>
delete
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] DELETE /api/v1/departments/{}"
,
id
);
log
.
info
(
"[API] DELETE /api/v1/departments/{}"
,
id
);
departmentRepository
.
findById
(
id
)
departmentRepository
.
findById
(
id
)
...
...
backend/apps/backend-app/src/main/java/com/platform/backend/controller/MenuController.java
浏览文件 @
299ccb35
...
@@ -59,7 +59,7 @@ public class MenuController {
...
@@ -59,7 +59,7 @@ public class MenuController {
// ========== 3.5.2 完整菜单树 ==========
// ========== 3.5.2 完整菜单树 ==========
@GetMapping
(
"/tree"
)
@GetMapping
(
"/tree"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('menu:view
')"
)
public
ResponseEntity
<
ApiResponse
<
List
<
Map
<
String
,
Object
>>>>
getTree
(
public
ResponseEntity
<
ApiResponse
<
List
<
Map
<
String
,
Object
>>>>
getTree
(
@RequestParam
(
required
=
false
)
Integer
status
,
@RequestParam
(
required
=
false
)
Integer
status
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -69,7 +69,7 @@ public class MenuController {
...
@@ -69,7 +69,7 @@ public class MenuController {
// ========== 3.5.3 菜单详情 ==========
// ========== 3.5.3 菜单详情 ==========
@GetMapping
(
"/{id}"
)
@GetMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('menu:view
')"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
getMenuById
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
getMenuById
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] GET /api/v1/menus/{}"
,
id
);
log
.
info
(
"[API] GET /api/v1/menus/{}"
,
id
);
...
@@ -94,7 +94,7 @@ public class MenuController {
...
@@ -94,7 +94,7 @@ public class MenuController {
// ========== 3.5.4 创建菜单 ==========
// ========== 3.5.4 创建菜单 ==========
@PostMapping
@PostMapping
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('menu:create
')"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
createMenu
(
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
createMenu
(
@RequestBody
MenuRequest
request
,
HttpServletRequest
httpReq
)
{
@RequestBody
MenuRequest
request
,
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] POST /api/v1/menus name={}"
,
request
.
getName
());
log
.
info
(
"[API] POST /api/v1/menus name={}"
,
request
.
getName
());
...
@@ -108,7 +108,7 @@ public class MenuController {
...
@@ -108,7 +108,7 @@ public class MenuController {
// ========== 3.5.5 更新菜单 ==========
// ========== 3.5.5 更新菜单 ==========
@PutMapping
(
"/{id}"
)
@PutMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('menu:update
')"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
updateMenu
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Void
>>
updateMenu
(
@PathVariable
Long
id
,
@RequestBody
MenuUpdateRequest
request
,
@RequestBody
MenuUpdateRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -121,7 +121,7 @@ public class MenuController {
...
@@ -121,7 +121,7 @@ public class MenuController {
// ========== 3.5.6 删除菜单 ==========
// ========== 3.5.6 删除菜单 ==========
@DeleteMapping
(
"/{id}"
)
@DeleteMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('menu:delete
')"
)
public
ResponseEntity
<
Void
>
deleteMenu
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
public
ResponseEntity
<
Void
>
deleteMenu
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] DELETE /api/v1/menus/{}"
,
id
);
log
.
info
(
"[API] DELETE /api/v1/menus/{}"
,
id
);
menuService
.
delete
(
id
);
menuService
.
delete
(
id
);
...
...
backend/apps/backend-app/src/main/java/com/platform/backend/controller/RoleController.java
浏览文件 @
299ccb35
...
@@ -106,7 +106,7 @@ public class RoleController {
...
@@ -106,7 +106,7 @@ public class RoleController {
// ========== 3.4.3 创建角色 ==========
// ========== 3.4.3 创建角色 ==========
@PostMapping
@PostMapping
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('role:create
')"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
createRole
(
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
createRole
(
@RequestBody
CreateRoleRequest
request
,
HttpServletRequest
httpReq
)
{
@RequestBody
CreateRoleRequest
request
,
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] POST /api/v1/roles roleName={}"
,
request
.
getRoleName
());
log
.
info
(
"[API] POST /api/v1/roles roleName={}"
,
request
.
getRoleName
());
...
@@ -124,7 +124,7 @@ public class RoleController {
...
@@ -124,7 +124,7 @@ public class RoleController {
// ========== 3.4.4 更新角色 ==========
// ========== 3.4.4 更新角色 ==========
@PutMapping
(
"/{id}"
)
@PutMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('role:update
')"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
updateRole
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Void
>>
updateRole
(
@PathVariable
Long
id
,
@RequestBody
UpdateRoleRequest
request
,
@RequestBody
UpdateRoleRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -138,7 +138,7 @@ public class RoleController {
...
@@ -138,7 +138,7 @@ public class RoleController {
// ========== 3.4.5 删除角色 ==========
// ========== 3.4.5 删除角色 ==========
@DeleteMapping
(
"/{id}"
)
@DeleteMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('role:delete
')"
)
public
ResponseEntity
<
Void
>
deleteRole
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
public
ResponseEntity
<
Void
>
deleteRole
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] DELETE /api/v1/roles/{}"
,
id
);
log
.
info
(
"[API] DELETE /api/v1/roles/{}"
,
id
);
if
(!
isAdmin
())
throw
new
BizException
(
BizCode
.
FORBIDDEN
);
if
(!
isAdmin
())
throw
new
BizException
(
BizCode
.
FORBIDDEN
);
...
@@ -165,7 +165,7 @@ public class RoleController {
...
@@ -165,7 +165,7 @@ public class RoleController {
// ========== 3.5.7 角色分配菜单 ==========
// ========== 3.5.7 角色分配菜单 ==========
@PutMapping
(
"/{roleId}/menus"
)
@PutMapping
(
"/{roleId}/menus"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('role:update
')"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
assignMenus
(
@PathVariable
Long
roleId
,
public
ResponseEntity
<
ApiResponse
<
Void
>>
assignMenus
(
@PathVariable
Long
roleId
,
@RequestBody
AssignMenusRequest
request
,
@RequestBody
AssignMenusRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -177,7 +177,7 @@ public class RoleController {
...
@@ -177,7 +177,7 @@ public class RoleController {
// ========== 4.10 角色分配自定义数据权限部门 ==========
// ========== 4.10 角色分配自定义数据权限部门 ==========
@PutMapping
(
"/{roleId}/custom-depts"
)
@PutMapping
(
"/{roleId}/custom-depts"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('role:update
')"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
assignCustomDepts
(
@PathVariable
Long
roleId
,
public
ResponseEntity
<
ApiResponse
<
Void
>>
assignCustomDepts
(
@PathVariable
Long
roleId
,
@RequestBody
AssignCustomDeptsRequest
request
,
@RequestBody
AssignCustomDeptsRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
...
backend/apps/backend-app/src/main/java/com/platform/backend/controller/UserController.java
浏览文件 @
299ccb35
...
@@ -10,10 +10,12 @@ import com.platform.backend.common.DataScope;
...
@@ -10,10 +10,12 @@ import com.platform.backend.common.DataScope;
import
com.platform.backend.dto.ApiResponse
;
import
com.platform.backend.dto.ApiResponse
;
import
com.platform.backend.dto.UpdatePhoneRequest
;
import
com.platform.backend.dto.UpdatePhoneRequest
;
import
com.platform.backend.entity.User
;
import
com.platform.backend.entity.User
;
import
com.platform.backend.repository.RoleRepository
;
import
com.platform.backend.service.AsyncImportService
;
import
com.platform.backend.service.AsyncImportService
;
import
com.platform.backend.service.PasswordService
;
import
com.platform.backend.service.PasswordService
;
import
com.platform.backend.service.UnlockLogService
;
import
com.platform.backend.service.UnlockLogService
;
import
com.platform.backend.service.UserService
;
import
com.platform.backend.service.UserService
;
import
com.platform.backend.security.PermissionService
;
import
jakarta.servlet.http.HttpServletRequest
;
import
jakarta.servlet.http.HttpServletRequest
;
import
lombok.Data
;
import
lombok.Data
;
import
lombok.RequiredArgsConstructor
;
import
lombok.RequiredArgsConstructor
;
...
@@ -49,6 +51,8 @@ public class UserController {
...
@@ -49,6 +51,8 @@ public class UserController {
private
final
AsyncImportService
asyncImportService
;
private
final
AsyncImportService
asyncImportService
;
private
final
UnlockLogService
unlockLogService
;
private
final
UnlockLogService
unlockLogService
;
private
final
SmsCodeService
smsCodeService
;
private
final
SmsCodeService
smsCodeService
;
private
final
RoleRepository
roleRepository
;
private
final
PermissionService
permissionService
;
private
String
tid
(
HttpServletRequest
req
)
{
private
String
tid
(
HttpServletRequest
req
)
{
Object
t
=
req
.
getAttribute
(
AuthConstants
.
MDC_TRACE_ID
);
Object
t
=
req
.
getAttribute
(
AuthConstants
.
MDC_TRACE_ID
);
...
@@ -75,12 +79,15 @@ public class UserController {
...
@@ -75,12 +79,15 @@ public class UserController {
}
}
log
.
info
(
"[API] GET /api/v1/users/me username={}"
,
username
);
log
.
info
(
"[API] GET /api/v1/users/me username={}"
,
username
);
User
user
=
userService
.
getByUsername
(
username
);
User
user
=
userService
.
getByUsername
(
username
);
return
ApiResponseEnvelope
.
ok
(
buildUserDetail
(
user
),
tid
(
httpReq
));
Map
<
String
,
Object
>
detail
=
buildUserDetail
(
user
);
// 仅当前用户需要完整权限集合用于前端按钮控制,避免扩大用户列表接口的数据暴露范围。
detail
.
put
(
"permissions"
,
permissionService
.
getUserPermissionCodes
(
user
.
getId
()));
return
ApiResponseEnvelope
.
ok
(
detail
,
tid
(
httpReq
));
}
}
// ========== 3.3.2 用户详情 ==========
// ========== 3.3.2 用户详情 ==========
@GetMapping
(
"/{id}"
)
@GetMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN') or #id == authentication.principal.id
"
)
@PreAuthorize
(
"has
Authority('user:view_detail') or @ss.isCurrentUserOrAdmin(#id)
"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
getUserById
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
getUserById
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] GET /api/v1/users/{}"
,
id
);
log
.
info
(
"[API] GET /api/v1/users/{}"
,
id
);
...
@@ -93,7 +100,7 @@ public class UserController {
...
@@ -93,7 +100,7 @@ public class UserController {
// ========== 3.3.3 更新用户信息 ==========
// ========== 3.3.3 更新用户信息 ==========
@PutMapping
(
"/{id}"
)
@PutMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN') or #id == authentication.principal.id
"
)
@PreAuthorize
(
"has
Authority('user:update') or @ss.isCurrentUserOrAdmin(#id)
"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
updateUser
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
updateUser
(
@PathVariable
Long
id
,
@RequestBody
UpdateUserRequest
request
,
@RequestBody
UpdateUserRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -106,7 +113,7 @@ public class UserController {
...
@@ -106,7 +113,7 @@ public class UserController {
// ========== 更新手机号(需验证码) ==========
// ========== 更新手机号(需验证码) ==========
@PutMapping
(
"/{id}/phone"
)
@PutMapping
(
"/{id}/phone"
)
@PreAuthorize
(
"has
Role('ADMIN') or #id == authentication.principal.id
"
)
@PreAuthorize
(
"has
Authority('user:update') or @ss.isCurrentUserOrAdmin(#id)
"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
updatePhone
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Void
>>
updatePhone
(
@PathVariable
Long
id
,
@RequestBody
UpdatePhoneRequest
request
,
@RequestBody
UpdatePhoneRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -121,10 +128,10 @@ public class UserController {
...
@@ -121,10 +128,10 @@ public class UserController {
// ========== 3.3.4 修改密码 ==========
// ========== 3.3.4 修改密码 ==========
@PutMapping
(
"/{id}/password"
)
@PutMapping
(
"/{id}/password"
)
@PreAuthorize
(
"has
Role('ADMIN') or #id == authentication.principal.id
"
)
@PreAuthorize
(
"has
Authority('user:update') or @ss.isCurrentUserOrAdmin(#id)
"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
changePassword
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Void
>>
changePassword
(
@PathVariable
Long
id
,
@RequestBody
ChangePasswordRequest
request
,
@RequestBody
ChangePasswordRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] PUT /api/v1/users/{}/password"
,
id
);
log
.
info
(
"[API] PUT /api/v1/users/{}/password"
,
id
);
passwordService
.
changePassword
(
currentUsername
(),
id
,
isAdmin
(),
passwordService
.
changePassword
(
currentUsername
(),
id
,
isAdmin
(),
request
.
getOldPassword
(),
request
.
getNewPassword
());
request
.
getOldPassword
(),
request
.
getNewPassword
());
...
@@ -133,7 +140,7 @@ public class UserController {
...
@@ -133,7 +140,7 @@ public class UserController {
// ========== 3.3.5 用户列表(带数据权限) ==========
// ========== 3.3.5 用户列表(带数据权限) ==========
@GetMapping
@GetMapping
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('user:view_list
')"
)
@DataScope
(
tableAlias
=
"root"
,
deptIdColumn
=
"departmentId"
,
userIdColumn
=
"id"
)
@DataScope
(
tableAlias
=
"root"
,
deptIdColumn
=
"departmentId"
,
userIdColumn
=
"id"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
listUsers
(
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
listUsers
(
@RequestParam
(
defaultValue
=
"1"
)
int
page
,
@RequestParam
(
defaultValue
=
"1"
)
int
page
,
...
@@ -157,7 +164,7 @@ public class UserController {
...
@@ -157,7 +164,7 @@ public class UserController {
// ========== 3.3.6 创建用户 ==========
// ========== 3.3.6 创建用户 ==========
@PostMapping
@PostMapping
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('user:create
')"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
createUser
(
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
createUser
(
@RequestBody
CreateUserRequest
request
,
@RequestBody
CreateUserRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -171,7 +178,7 @@ public class UserController {
...
@@ -171,7 +178,7 @@ public class UserController {
// ========== 3.3.7 删除用户(软删除) ==========
// ========== 3.3.7 删除用户(软删除) ==========
@DeleteMapping
(
"/{id}"
)
@DeleteMapping
(
"/{id}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('user:delete
')"
)
public
ResponseEntity
<
Void
>
deleteUser
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
public
ResponseEntity
<
Void
>
deleteUser
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] DELETE /api/v1/users/{}"
,
id
);
log
.
info
(
"[API] DELETE /api/v1/users/{}"
,
id
);
userService
.
softDelete
(
id
,
currentUsername
());
userService
.
softDelete
(
id
,
currentUsername
());
...
@@ -180,7 +187,7 @@ public class UserController {
...
@@ -180,7 +187,7 @@ public class UserController {
// ========== 3.3.8 重置用户密码(管理员) ==========
// ========== 3.3.8 重置用户密码(管理员) ==========
@PutMapping
(
"/{id}/password/reset"
)
@PutMapping
(
"/{id}/password/reset"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('user:update
')"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
resetPassword
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Void
>>
resetPassword
(
@PathVariable
Long
id
,
@RequestBody
ResetPasswordRequest
request
,
@RequestBody
ResetPasswordRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -191,7 +198,7 @@ public class UserController {
...
@@ -191,7 +198,7 @@ public class UserController {
// ========== 4.11 用户角色分配 ==========
// ========== 4.11 用户角色分配 ==========
@PutMapping
(
"/{id}/roles"
)
@PutMapping
(
"/{id}/roles"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('role:assign_user
')"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
assignRoles
(
@PathVariable
Long
id
,
public
ResponseEntity
<
ApiResponse
<
Void
>>
assignRoles
(
@PathVariable
Long
id
,
@RequestBody
AssignRolesRequest
request
,
@RequestBody
AssignRolesRequest
request
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -202,7 +209,7 @@ public class UserController {
...
@@ -202,7 +209,7 @@ public class UserController {
// ========== 4.13 手动解锁 ==========
// ========== 4.13 手动解锁 ==========
@PutMapping
(
"/{id}/unlock"
)
@PutMapping
(
"/{id}/unlock"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('user:update
')"
)
public
ResponseEntity
<
ApiResponse
<
Void
>>
unlockAccount
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
public
ResponseEntity
<
ApiResponse
<
Void
>>
unlockAccount
(
@PathVariable
Long
id
,
HttpServletRequest
httpReq
)
{
String
operator
=
currentUsername
();
String
operator
=
currentUsername
();
log
.
info
(
"[API] PUT /api/v1/users/{}/unlock operator={}"
,
id
,
operator
);
log
.
info
(
"[API] PUT /api/v1/users/{}/unlock operator={}"
,
id
,
operator
);
...
@@ -214,7 +221,7 @@ public class UserController {
...
@@ -214,7 +221,7 @@ public class UserController {
// ========== 3.3.9 批量导入用户(异步) ==========
// ========== 3.3.9 批量导入用户(异步) ==========
@PostMapping
(
"/batch-import"
)
@PostMapping
(
"/batch-import"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('user:create
')"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
batchImport
(
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
batchImport
(
@RequestParam
(
"file"
)
org
.
springframework
.
web
.
multipart
.
MultipartFile
file
,
@RequestParam
(
"file"
)
org
.
springframework
.
web
.
multipart
.
MultipartFile
file
,
HttpServletRequest
httpReq
)
{
HttpServletRequest
httpReq
)
{
...
@@ -241,7 +248,7 @@ public class UserController {
...
@@ -241,7 +248,7 @@ public class UserController {
// ========== 3.3.10 查询导入进度 ==========
// ========== 3.3.10 查询导入进度 ==========
@GetMapping
(
"/batch-import/{taskId}"
)
@GetMapping
(
"/batch-import/{taskId}"
)
@PreAuthorize
(
"has
Role('ADMIN
')"
)
@PreAuthorize
(
"has
Authority('user:create
')"
)
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
getImportProgress
(
public
ResponseEntity
<
ApiResponse
<
Map
<
String
,
Object
>>>
getImportProgress
(
@PathVariable
String
taskId
,
HttpServletRequest
httpReq
)
{
@PathVariable
String
taskId
,
HttpServletRequest
httpReq
)
{
log
.
info
(
"[API] GET /api/v1/users/batch-import/{}"
,
taskId
);
log
.
info
(
"[API] GET /api/v1/users/batch-import/{}"
,
taskId
);
...
@@ -295,6 +302,11 @@ public class UserController {
...
@@ -295,6 +302,11 @@ public class UserController {
map
.
put
(
"phone"
,
maskPhone
(
user
.
getPhone
()));
map
.
put
(
"phone"
,
maskPhone
(
user
.
getPhone
()));
map
.
put
(
"avatar"
,
user
.
getAvatarUrl
());
map
.
put
(
"avatar"
,
user
.
getAvatarUrl
());
map
.
put
(
"roleId"
,
user
.
getRoleId
());
map
.
put
(
"roleId"
,
user
.
getRoleId
());
// 获取角色名称
if
(
user
.
getRoleId
()
!=
null
)
{
String
roleName
=
roleRepository
.
findRoleNameById
(
user
.
getRoleId
());
map
.
put
(
"roleName"
,
roleName
);
}
map
.
put
(
"departmentId"
,
user
.
getDepartmentId
());
map
.
put
(
"departmentId"
,
user
.
getDepartmentId
());
map
.
put
(
"status"
,
user
.
getStatus
());
map
.
put
(
"status"
,
user
.
getStatus
());
map
.
put
(
"createdAt"
,
user
.
getCreatedAt
());
map
.
put
(
"createdAt"
,
user
.
getCreatedAt
());
...
@@ -313,4 +325,4 @@ public class UserController {
...
@@ -313,4 +325,4 @@ public class UserController {
if
(
phone
==
null
||
phone
.
length
()
<
11
)
return
phone
;
if
(
phone
==
null
||
phone
.
length
()
<
11
)
return
phone
;
return
phone
.
substring
(
0
,
3
)
+
"****"
+
phone
.
substring
(
7
);
return
phone
.
substring
(
0
,
3
)
+
"****"
+
phone
.
substring
(
7
);
}
}
}
}
\ No newline at end of file
backend/apps/backend-app/src/main/java/com/platform/backend/repository/RolePermissionRepository.java
浏览文件 @
299ccb35
...
@@ -2,6 +2,9 @@ package com.platform.backend.repository;
...
@@ -2,6 +2,9 @@ package com.platform.backend.repository;
import
com.platform.backend.entity.RolePermission
;
import
com.platform.backend.entity.RolePermission
;
import
org.springframework.data.jpa.repository.JpaRepository
;
import
org.springframework.data.jpa.repository.JpaRepository
;
import
org.springframework.data.jpa.repository.Modifying
;
import
org.springframework.data.jpa.repository.Query
;
import
org.springframework.data.repository.query.Param
;
import
org.springframework.stereotype.Repository
;
import
org.springframework.stereotype.Repository
;
import
java.util.List
;
import
java.util.List
;
...
@@ -9,6 +12,14 @@ import java.util.List;
...
@@ -9,6 +12,14 @@ import java.util.List;
@Repository
@Repository
public
interface
RolePermissionRepository
extends
JpaRepository
<
RolePermission
,
Long
>
{
public
interface
RolePermissionRepository
extends
JpaRepository
<
RolePermission
,
Long
>
{
List
<
RolePermission
>
findByRoleId
(
Long
roleId
);
List
<
RolePermission
>
findByRoleId
(
Long
roleId
);
void
deleteByRoleId
(
Long
roleId
);
List
<
RolePermission
>
findByRoleIdIn
(
List
<
Long
>
roleIds
);
/**
* 权限替换前立即执行删除,避免同一角色重复插入时触发唯一索引冲突。
*/
@Modifying
(
flushAutomatically
=
true
)
@Query
(
"DELETE FROM RolePermission rp WHERE rp.roleId = :roleId"
)
void
deleteByRoleId
(
@Param
(
"roleId"
)
Long
roleId
);
long
countByRoleId
(
Long
roleId
);
long
countByRoleId
(
Long
roleId
);
}
}
backend/apps/backend-app/src/main/java/com/platform/backend/repository/RoleRepository.java
浏览文件 @
299ccb35
...
@@ -2,6 +2,7 @@ package com.platform.backend.repository;
...
@@ -2,6 +2,7 @@ package com.platform.backend.repository;
import
com.platform.backend.entity.Role
;
import
com.platform.backend.entity.Role
;
import
org.springframework.data.jpa.repository.JpaRepository
;
import
org.springframework.data.jpa.repository.JpaRepository
;
import
org.springframework.data.jpa.repository.Query
;
import
org.springframework.stereotype.Repository
;
import
org.springframework.stereotype.Repository
;
import
java.util.Optional
;
import
java.util.Optional
;
...
@@ -9,4 +10,7 @@ import java.util.Optional;
...
@@ -9,4 +10,7 @@ import java.util.Optional;
@Repository
@Repository
public
interface
RoleRepository
extends
JpaRepository
<
Role
,
Long
>
{
public
interface
RoleRepository
extends
JpaRepository
<
Role
,
Long
>
{
Optional
<
Role
>
findByRoleCode
(
String
roleCode
);
Optional
<
Role
>
findByRoleCode
(
String
roleCode
);
@Query
(
"SELECT r.roleName FROM Role r WHERE r.id = :id"
)
String
findRoleNameById
(
Long
id
);
}
}
\ No newline at end of file
backend/apps/backend-app/src/main/java/com/platform/backend/repository/UserRepository.java
浏览文件 @
299ccb35
...
@@ -16,6 +16,7 @@ public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificat
...
@@ -16,6 +16,7 @@ public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificat
boolean
existsByUsername
(
String
username
);
boolean
existsByUsername
(
String
username
);
boolean
existsByPhone
(
String
phone
);
boolean
existsByPhone
(
String
phone
);
long
countByIsDeletedAndRoleId
(
Integer
isDeleted
,
Long
roleId
);
long
countByIsDeletedAndRoleId
(
Integer
isDeleted
,
Long
roleId
);
List
<
User
>
findByRoleId
(
Long
roleId
);
// 分页查询
// 分页查询
List
<
User
>
findByIsDeleted
(
Integer
isDeleted
);
List
<
User
>
findByIsDeleted
(
Integer
isDeleted
);
...
...
backend/apps/backend-app/src/main/java/com/platform/backend/repository/UserRoleRepository.java
浏览文件 @
299ccb35
...
@@ -13,6 +13,7 @@ import java.util.List;
...
@@ -13,6 +13,7 @@ import java.util.List;
public
interface
UserRoleRepository
extends
JpaRepository
<
UserRole
,
Long
>
{
public
interface
UserRoleRepository
extends
JpaRepository
<
UserRole
,
Long
>
{
List
<
UserRole
>
findByUserId
(
Long
userId
);
List
<
UserRole
>
findByUserId
(
Long
userId
);
List
<
UserRole
>
findByRoleId
(
Long
roleId
);
List
<
UserRole
>
findByRoleId
(
Long
roleId
);
List
<
UserRole
>
findByUserIdAndRoleId
(
Long
userId
,
Long
roleId
);
@Modifying
@Modifying
@Query
(
"DELETE FROM UserRole ur WHERE ur.userId = :userId"
)
@Query
(
"DELETE FROM UserRole ur WHERE ur.userId = :userId"
)
...
...
backend/apps/backend-app/src/main/java/com/platform/backend/security/CustomUserDetailsService.java
浏览文件 @
299ccb35
...
@@ -12,8 +12,13 @@ import org.springframework.security.core.userdetails.UserDetailsService;
...
@@ -12,8 +12,13 @@ import org.springframework.security.core.userdetails.UserDetailsService;
import
org.springframework.security.core.userdetails.UsernameNotFoundException
;
import
org.springframework.security.core.userdetails.UsernameNotFoundException
;
import
org.springframework.stereotype.Service
;
import
org.springframework.stereotype.Service
;
import
java.util.Collections
;
import
java.util.ArrayList
;
import
java.util.List
;
import
java.util.stream.Collectors
;
/**
* 用户详情服务:加载用户信息和权限
*/
@Slf4j
@Slf4j
@Service
@Service
@RequiredArgsConstructor
@RequiredArgsConstructor
...
@@ -21,28 +26,38 @@ public class CustomUserDetailsService implements UserDetailsService {
...
@@ -21,28 +26,38 @@ public class CustomUserDetailsService implements UserDetailsService {
private
final
UserRepository
userRepository
;
private
final
UserRepository
userRepository
;
private
final
RoleRepository
roleRepository
;
private
final
RoleRepository
roleRepository
;
private
final
PermissionService
permissionService
;
@Override
@Override
public
UserDetails
loadUserByUsername
(
String
username
)
throws
UsernameNotFoundException
{
public
UserDetails
loadUserByUsername
(
String
username
)
throws
UsernameNotFoundException
{
User
user
=
userRepository
.
findByUsername
(
username
)
User
user
=
userRepository
.
findByUsername
(
username
)
.
orElseThrow
(()
->
new
UsernameNotFoundException
(
"用户不存在: "
+
username
));
.
orElseThrow
(()
->
new
UsernameNotFoundException
(
"用户不存在: "
+
username
));
String
authority
=
resolveAuthority
(
user
);
// 1. 获取角色信息
String
roleAuthority
=
resolveRoleAuthority
(
user
);
List
<
SimpleGrantedAuthority
>
authorities
=
new
ArrayList
<>();
authorities
.
add
(
new
SimpleGrantedAuthority
(
roleAuthority
));
// 2. 获取权限信息(从数据库加载,支持缓存)
List
<
String
>
permissions
=
permissionService
.
getUserPermissions
(
user
.
getId
());
for
(
String
perm
:
permissions
)
{
authorities
.
add
(
new
SimpleGrantedAuthority
(
perm
));
}
// 3. 构建 UserDetails
return
new
org
.
springframework
.
security
.
core
.
userdetails
.
User
(
return
new
org
.
springframework
.
security
.
core
.
userdetails
.
User
(
user
.
getUsername
(),
user
.
getUsername
(),
user
.
getPassword
(),
user
.
getPassword
(),
user
.
getEnabled
(),
user
.
getEnabled
(),
true
,
true
,
true
,
true
,
true
,
true
,
Collections
.
singletonList
(
new
SimpleGrantedAuthority
(
authority
))
authorities
);
);
}
}
/**
/**
* 通过 roleId 在 user_role 字典表里查 role_code,拼装成 Spring Security 的 authority。
* 获取用户的角色 authority(Spring Security 格式)
* 默认 fallback 为 ROLE_USER。
*/
*/
private
String
resolveAuthority
(
User
user
)
{
private
String
resolve
Role
Authority
(
User
user
)
{
Long
roleId
=
user
.
getRoleId
();
Long
roleId
=
user
.
getRoleId
();
if
(
roleId
==
null
)
{
if
(
roleId
==
null
)
{
log
.
warn
(
"用户 {} 未关联 roleId,使用默认 ROLE_USER"
,
user
.
getUsername
());
log
.
warn
(
"用户 {} 未关联 roleId,使用默认 ROLE_USER"
,
user
.
getUsername
());
...
@@ -56,4 +71,4 @@ public class CustomUserDetailsService implements UserDetailsService {
...
@@ -56,4 +71,4 @@ public class CustomUserDetailsService implements UserDetailsService {
return
"ROLE_USER"
;
return
"ROLE_USER"
;
});
});
}
}
}
}
\ No newline at end of file
backend/apps/backend-app/src/main/java/com/platform/backend/security/PermissionService.java
0 → 100644
浏览文件 @
299ccb35
package
com
.
platform
.
backend
.
security
;
import
com.fasterxml.jackson.core.JsonProcessingException
;
import
com.fasterxml.jackson.core.type.TypeReference
;
import
com.fasterxml.jackson.databind.ObjectMapper
;
import
com.platform.backend.entity.Permission
;
import
com.platform.backend.repository.PermissionRepository
;
import
com.platform.backend.repository.RolePermissionRepository
;
import
com.platform.backend.repository.UserRoleRepository
;
import
com.platform.backend.repository.UserRepository
;
import
lombok.RequiredArgsConstructor
;
import
lombok.extern.slf4j.Slf4j
;
import
org.springframework.data.redis.core.StringRedisTemplate
;
import
org.springframework.stereotype.Service
;
import
java.time.Duration
;
import
java.util.ArrayList
;
import
java.util.Collections
;
import
java.util.HashSet
;
import
java.util.List
;
import
java.util.Set
;
import
java.util.stream.Collectors
;
/**
* 权限服务:从数据库加载用户权限,支持 Redis 缓存
*/
@Slf4j
@Service
@RequiredArgsConstructor
public
class
PermissionService
{
private
final
PermissionRepository
permissionRepository
;
private
final
RolePermissionRepository
rolePermissionRepository
;
private
final
UserRoleRepository
userRoleRepository
;
private
final
UserRepository
userRepository
;
private
final
StringRedisTemplate
redisTemplate
;
private
final
ObjectMapper
objectMapper
;
private
static
final
String
CACHE_PREFIX
=
"user:perm:"
;
private
static
final
Duration
CACHE_TTL
=
Duration
.
ofHours
(
1
);
/**
* 获取用户的所有权限码列表
*/
public
List
<
String
>
getUserPermissions
(
Long
userId
)
{
String
cacheKey
=
CACHE_PREFIX
+
userId
;
String
cached
=
redisTemplate
.
opsForValue
().
get
(
cacheKey
);
if
(
cached
!=
null
)
{
try
{
return
objectMapper
.
readValue
(
cached
,
new
TypeReference
<
List
<
String
>>()
{});
}
catch
(
JsonProcessingException
e
)
{
log
.
warn
(
"解析权限缓存失败 userId={}"
,
userId
);
}
}
List
<
String
>
permissions
=
loadUserPermissions
(
userId
);
try
{
redisTemplate
.
opsForValue
().
set
(
cacheKey
,
objectMapper
.
writeValueAsString
(
permissions
),
CACHE_TTL
);
}
catch
(
JsonProcessingException
e
)
{
log
.
warn
(
"序列化权限缓存失败 userId={}"
,
userId
);
}
return
permissions
;
}
/**
* 从数据库加载用户权限
*/
private
List
<
String
>
loadUserPermissions
(
Long
userId
)
{
// 获取用户主角色
List
<
Long
>
roleIds
=
new
ArrayList
<>();
userRepository
.
findById
(
userId
).
ifPresent
(
user
->
{
if
(
user
.
getRoleId
()
!=
null
)
{
roleIds
.
add
(
user
.
getRoleId
());
}
});
// 获取用户关联的其他角色
userRoleRepository
.
findByUserId
(
userId
).
forEach
(
ur
->
{
if
(!
roleIds
.
contains
(
ur
.
getRoleId
()))
{
roleIds
.
add
(
ur
.
getRoleId
());
}
});
if
(
roleIds
.
isEmpty
())
{
log
.
warn
(
"用户 {} 没有关联任何角色"
,
userId
);
return
Collections
.
emptyList
();
}
// 获取所有角色关联的权限
List
<
Long
>
permissionIds
=
rolePermissionRepository
.
findByRoleIdIn
(
roleIds
).
stream
()
.
map
(
rp
->
rp
.
getPermissionId
())
.
collect
(
Collectors
.
toList
());
// 转换为权限码
return
permissionRepository
.
findAllById
(
permissionIds
).
stream
()
.
map
(
Permission:
:
getPermissionCode
)
.
collect
(
Collectors
.
toList
());
}
/**
* 刷新用户权限缓存
*/
public
void
refreshCache
(
Long
userId
)
{
String
cacheKey
=
CACHE_PREFIX
+
userId
;
redisTemplate
.
delete
(
cacheKey
);
log
.
info
(
"用户 {} 权限缓存已刷新"
,
userId
);
}
/**
* 刷新指定角色的所有用户权限缓存
*/
public
void
refreshCacheByRoleId
(
Long
roleId
)
{
Set
<
Long
>
userIds
=
new
HashSet
<>();
userRoleRepository
.
findByRoleId
(
roleId
).
forEach
(
userRole
->
userIds
.
add
(
userRole
.
getUserId
()));
// 兼容早期仅写 user.role_id、未写 user_role 关联表的用户数据。
userRepository
.
findByRoleId
(
roleId
).
forEach
(
user
->
userIds
.
add
(
user
.
getId
()));
userIds
.
forEach
(
this
::
refreshCache
);
}
/**
* 检查用户是否拥有指定权限
*/
public
boolean
hasPermission
(
Long
userId
,
String
permissionCode
)
{
return
getUserPermissions
(
userId
).
contains
(
permissionCode
);
}
/**
* 获取用户的权限码列表(用于前端按钮级权限控制)
*/
public
List
<
String
>
getUserPermissionCodes
(
Long
userId
)
{
return
getUserPermissions
(
userId
);
}
}
backend/apps/backend-app/src/main/java/com/platform/backend/security/SecurityExpression.java
0 → 100644
浏览文件 @
299ccb35
package
com
.
platform
.
backend
.
security
;
import
com.platform.backend.entity.User
;
import
com.platform.backend.repository.UserRepository
;
import
lombok.RequiredArgsConstructor
;
import
org.springframework.security.core.Authentication
;
import
org.springframework.security.core.context.SecurityContextHolder
;
import
org.springframework.stereotype.Component
;
import
java.util.Optional
;
/**
* 自定义权限表达式方法,用于 @PreAuthorize 注解
*/
@Component
(
"ss"
)
@RequiredArgsConstructor
public
class
SecurityExpression
{
private
final
UserRepository
userRepository
;
/**
* 检查当前用户是否是管理员
*/
public
boolean
isAdmin
()
{
Authentication
auth
=
SecurityContextHolder
.
getContext
().
getAuthentication
();
if
(
auth
==
null
)
return
false
;
return
auth
.
getAuthorities
().
stream
()
.
anyMatch
(
a
->
"ROLE_ADMIN"
.
equals
(
a
.
getAuthority
()));
}
/**
* 检查当前用户是否是本人(用于用户查看/修改自己的信息)
*/
public
boolean
isCurrentUserOrAdmin
(
Long
userId
)
{
if
(
isAdmin
())
return
true
;
Optional
<
User
>
currentUser
=
getCurrentUser
();
return
currentUser
.
isPresent
()
&&
currentUser
.
get
().
getId
().
equals
(
userId
);
}
/**
* 检查当前用户是否有指定权限
*/
public
boolean
hasPermission
(
String
permissionCode
)
{
Authentication
auth
=
SecurityContextHolder
.
getContext
().
getAuthentication
();
if
(
auth
==
null
)
return
false
;
return
auth
.
getAuthorities
().
stream
()
.
anyMatch
(
a
->
permissionCode
.
equals
(
a
.
getAuthority
()));
}
/**
* 获取当前登录用户
*/
public
Optional
<
User
>
getCurrentUser
()
{
Authentication
auth
=
SecurityContextHolder
.
getContext
().
getAuthentication
();
if
(
auth
==
null
||
auth
.
getName
()
==
null
||
"anonymousUser"
.
equals
(
auth
.
getName
()))
{
return
Optional
.
empty
();
}
return
userRepository
.
findByUsername
(
auth
.
getName
());
}
/**
* 获取当前用户ID
*/
public
Long
getCurrentUserId
()
{
return
getCurrentUser
().
map
(
User:
:
getId
).
orElse
(
null
);
}
}
backend/apps/backend-app/src/main/java/com/platform/backend/service/MenuService.java
浏览文件 @
299ccb35
...
@@ -12,6 +12,7 @@ import com.platform.backend.repository.MenuRepository;
...
@@ -12,6 +12,7 @@ import com.platform.backend.repository.MenuRepository;
import
com.platform.backend.repository.RoleMenuRepository
;
import
com.platform.backend.repository.RoleMenuRepository
;
import
com.platform.backend.repository.UserRepository
;
import
com.platform.backend.repository.UserRepository
;
import
com.platform.backend.repository.UserRoleRepository
;
import
com.platform.backend.repository.UserRoleRepository
;
import
com.platform.backend.security.PermissionService
;
import
lombok.RequiredArgsConstructor
;
import
lombok.RequiredArgsConstructor
;
import
lombok.extern.slf4j.Slf4j
;
import
lombok.extern.slf4j.Slf4j
;
import
org.springframework.data.redis.core.StringRedisTemplate
;
import
org.springframework.data.redis.core.StringRedisTemplate
;
...
@@ -38,6 +39,7 @@ public class MenuService {
...
@@ -38,6 +39,7 @@ public class MenuService {
private
final
UserRepository
userRepository
;
private
final
UserRepository
userRepository
;
private
final
StringRedisTemplate
redis
;
private
final
StringRedisTemplate
redis
;
private
final
ObjectMapper
objectMapper
;
private
final
ObjectMapper
objectMapper
;
private
final
PermissionService
permissionService
;
private
static
final
long
MENU_TTL_HOURS
=
1
;
private
static
final
long
MENU_TTL_HOURS
=
1
;
private
static
final
String
MENU_CACHE_KEY_PREFIX
=
"menu:"
;
private
static
final
String
MENU_CACHE_KEY_PREFIX
=
"menu:"
;
...
@@ -190,6 +192,10 @@ public class MenuService {
...
@@ -190,6 +192,10 @@ public class MenuService {
private
void
refreshAllMenuCache
()
{
private
void
refreshAllMenuCache
()
{
incrementMenuCacheVersion
();
incrementMenuCacheVersion
();
// 清除所有用户权限缓存
userRepository
.
findAll
().
forEach
(
user
->
{
permissionService
.
refreshCache
(
user
.
getId
());
});
}
}
private
List
<
Map
<
String
,
Object
>>
buildTree
(
List
<
Menu
>
all
,
Long
parentId
)
{
private
List
<
Map
<
String
,
Object
>>
buildTree
(
List
<
Menu
>
all
,
Long
parentId
)
{
...
...
backend/apps/backend-app/src/main/java/com/platform/backend/service/RoleService.java
浏览文件 @
299ccb35
...
@@ -12,6 +12,7 @@ import com.platform.backend.repository.RoleMenuRepository;
...
@@ -12,6 +12,7 @@ import com.platform.backend.repository.RoleMenuRepository;
import
com.platform.backend.repository.RolePermissionRepository
;
import
com.platform.backend.repository.RolePermissionRepository
;
import
com.platform.backend.repository.RoleRepository
;
import
com.platform.backend.repository.RoleRepository
;
import
com.platform.backend.repository.UserRoleRepository
;
import
com.platform.backend.repository.UserRoleRepository
;
import
com.platform.backend.security.PermissionService
;
import
lombok.RequiredArgsConstructor
;
import
lombok.RequiredArgsConstructor
;
import
lombok.extern.slf4j.Slf4j
;
import
lombok.extern.slf4j.Slf4j
;
import
org.springframework.data.redis.core.StringRedisTemplate
;
import
org.springframework.data.redis.core.StringRedisTemplate
;
...
@@ -36,6 +37,7 @@ public class RoleService {
...
@@ -36,6 +37,7 @@ public class RoleService {
private
final
UserRoleRepository
userRoleRepository
;
private
final
UserRoleRepository
userRoleRepository
;
private
final
RoleCustomDeptRepository
roleCustomDeptRepository
;
private
final
RoleCustomDeptRepository
roleCustomDeptRepository
;
private
final
StringRedisTemplate
redis
;
private
final
StringRedisTemplate
redis
;
private
final
PermissionService
permissionService
;
public
List
<
Role
>
list
()
{
public
List
<
Role
>
list
()
{
return
roleRepository
.
findAll
();
return
roleRepository
.
findAll
();
...
@@ -79,7 +81,9 @@ public class RoleService {
...
@@ -79,7 +81,9 @@ public class RoleService {
Integer
dataScope
,
Integer
sort
,
Integer
status
,
Integer
dataScope
,
Integer
sort
,
Integer
status
,
List
<
Long
>
permissionIds
)
{
List
<
Long
>
permissionIds
)
{
Role
role
=
getById
(
id
);
Role
role
=
getById
(
id
);
if
(
role
.
getIsPreset
()
!=
null
&&
role
.
getIsPreset
()
==
1
)
{
boolean
isPresetRole
=
role
.
getIsPreset
()
!=
null
&&
role
.
getIsPreset
()
==
1
;
// 预置角色的身份定义不可改,但管理员可以调整其权限集合。
if
(
isPresetRole
&&
(
roleName
!=
null
||
description
!=
null
||
dataScope
!=
null
||
sort
!=
null
||
status
!=
null
))
{
throw
new
BizException
(
BizCode
.
ROLE_PRESET
);
throw
new
BizException
(
BizCode
.
ROLE_PRESET
);
}
}
if
(
roleName
!=
null
)
role
.
setRoleName
(
roleName
);
if
(
roleName
!=
null
)
role
.
setRoleName
(
roleName
);
...
@@ -97,6 +101,8 @@ public class RoleService {
...
@@ -97,6 +101,8 @@ public class RoleService {
rp
.
setPermissionId
(
permId
);
rp
.
setPermissionId
(
permId
);
rolePermissionRepository
.
save
(
rp
);
rolePermissionRepository
.
save
(
rp
);
}
}
// 角色权限更新后,确保该角色所有用户的下一次请求立即重新从数据库取权限。
permissionService
.
refreshCacheByRoleId
(
id
);
}
}
return
role
;
return
role
;
}
}
...
...
sql/user-module-schema.sql
0 → 100644
浏览文件 @
299ccb35
-- ============================================================
-- 用户模块数据库表设计
-- 根据 user-module-任务文档.md 设计
-- 数据库: studyweb
-- 创建时间: 2026-07-15
-- ============================================================
SET
NAMES
utf8mb4
;
SET
FOREIGN_KEY_CHECKS
=
0
;
-- ----------------------------
-- 1. 部门表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_department
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
name
VARCHAR
(
100
)
NOT
NULL
COMMENT
'部门名称'
,
code
VARCHAR
(
50
)
UNIQUE
COMMENT
'部门编码:tech/annotation'
,
description
VARCHAR
(
500
)
COMMENT
'说明'
,
parent_id
BIGINT
COMMENT
'父部门ID'
,
status
TINYINT
DEFAULT
1
COMMENT
'状态:1=启用 0=禁用'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
updated_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
ON
UPDATE
CURRENT_TIMESTAMP
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'部门表'
;
-- ----------------------------
-- 2. 用户表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_user
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
username
VARCHAR
(
50
)
NOT
NULL
UNIQUE
COMMENT
'用户名'
,
password
VARCHAR
(
255
)
NOT
NULL
COMMENT
'bcrypt加密密码'
,
real_name
VARCHAR
(
50
)
NOT
NULL
COMMENT
'真实姓名'
,
email
VARCHAR
(
100
)
COMMENT
'邮箱'
,
phone
VARCHAR
(
20
)
COMMENT
'手机号'
,
role_id
BIGINT
COMMENT
'主角色ID(单角色快速查询字段)'
,
department_id
BIGINT
COMMENT
'所属部门'
,
avatar_url
VARCHAR
(
500
)
COMMENT
'头像'
,
status
TINYINT
DEFAULT
1
COMMENT
'0=禁用 1=启用'
,
is_deleted
TINYINT
DEFAULT
0
COMMENT
'软删除标记'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
updated_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
ON
UPDATE
CURRENT_TIMESTAMP
,
INDEX
idx_role_id
(
role_id
),
INDEX
idx_department_id
(
department_id
),
INDEX
idx_status
(
status
),
INDEX
idx_phone
(
phone
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'用户表'
;
-- ----------------------------
-- 3. 角色表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_role
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
role_name
VARCHAR
(
50
)
NOT
NULL
UNIQUE
COMMENT
'角色名称'
,
role_code
VARCHAR
(
50
)
UNIQUE
COMMENT
'角色编码,用于 Spring Security(如 ROLE_ADMIN)'
,
description
VARCHAR
(
200
)
COMMENT
'角色描述'
,
is_preset
TINYINT
DEFAULT
0
COMMENT
'是否预置角色:0=否 1=是'
,
data_scope
TINYINT
DEFAULT
4
COMMENT
'数据权限:1=全部 2=本部门 3=本部门及下级 4=仅本人 5=自定义'
,
sort
INT
DEFAULT
0
COMMENT
'排序号'
,
status
TINYINT
DEFAULT
1
COMMENT
'状态:1=启用 0=禁用'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
updated_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
ON
UPDATE
CURRENT_TIMESTAMP
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'角色表'
;
-- ----------------------------
-- 4. 权限点表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_permission
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
permission_code
VARCHAR
(
50
)
NOT
NULL
UNIQUE
COMMENT
'权限编码'
,
permission_name
VARCHAR
(
100
)
NOT
NULL
COMMENT
'权限名称'
,
module
VARCHAR
(
50
)
NOT
NULL
COMMENT
'所属模块:project/training/defense/audit/user'
,
description
VARCHAR
(
200
)
COMMENT
'权限说明'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
updated_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
ON
UPDATE
CURRENT_TIMESTAMP
,
INDEX
idx_module
(
module
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'权限点表'
;
-- ----------------------------
-- 5. 用户角色关联表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_user_role
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
user_id
BIGINT
NOT
NULL
COMMENT
'用户ID'
,
role_id
BIGINT
NOT
NULL
COMMENT
'角色ID'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
UNIQUE
KEY
uk_user_role
(
user_id
,
role_id
),
INDEX
idx_user_id
(
user_id
),
INDEX
idx_role_id
(
role_id
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'用户角色关联表'
;
-- ----------------------------
-- 6. 角色权限关联表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_role_permission
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
role_id
BIGINT
NOT
NULL
COMMENT
'角色ID'
,
permission_id
BIGINT
NOT
NULL
COMMENT
'权限ID'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
UNIQUE
KEY
uk_role_permission
(
role_id
,
permission_id
),
INDEX
idx_role_id
(
role_id
),
INDEX
idx_permission_id
(
permission_id
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'角色权限关联表'
;
-- ----------------------------
-- 7. 角色菜单关联表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_role_menu
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
role_id
BIGINT
NOT
NULL
COMMENT
'角色ID'
,
menu_id
BIGINT
NOT
NULL
COMMENT
'菜单ID'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
UNIQUE
KEY
uk_role_menu
(
role_id
,
menu_id
),
INDEX
idx_role_id
(
role_id
),
INDEX
idx_menu_id
(
menu_id
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'角色菜单关联表'
;
-- ----------------------------
-- 8. 菜单表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_menu
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
parent_id
BIGINT
DEFAULT
0
COMMENT
'父菜单ID:0=顶级'
,
name
VARCHAR
(
50
)
NOT
NULL
COMMENT
'菜单标识(英文,唯一)'
,
title
VARCHAR
(
50
)
NOT
NULL
COMMENT
'菜单标题(中文)'
,
icon
VARCHAR
(
100
)
COMMENT
'图标'
,
path
VARCHAR
(
255
)
COMMENT
'路由路径'
,
component
VARCHAR
(
255
)
COMMENT
'前端组件路径'
,
permission_code
VARCHAR
(
50
)
COMMENT
'权限标识(按钮级)'
,
type
TINYINT
DEFAULT
1
COMMENT
'类型:1=菜单 2=按钮'
,
sort
INT
DEFAULT
0
COMMENT
'排序号'
,
visible
TINYINT
DEFAULT
1
COMMENT
'是否显示:1=显示 0=隐藏'
,
status
TINYINT
DEFAULT
1
COMMENT
'状态:1=启用 0=禁用'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
updated_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
ON
UPDATE
CURRENT_TIMESTAMP
,
INDEX
idx_parent_id
(
parent_id
),
INDEX
idx_status
(
status
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'菜单表'
;
-- ----------------------------
-- 9. 登录日志表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_login_log
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
user_id
BIGINT
COMMENT
'用户ID'
,
username
VARCHAR
(
50
)
NOT
NULL
COMMENT
'登录账号'
,
ip
VARCHAR
(
50
)
COMMENT
'IP地址'
,
device
TEXT
COMMENT
'设备信息(User-Agent)'
,
location
VARCHAR
(
100
)
COMMENT
'登录地点'
,
status
TINYINT
NOT
NULL
COMMENT
'1=成功 2=失败'
,
fail_reason
VARCHAR
(
255
)
COMMENT
'失败原因'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
INDEX
idx_user_id
(
user_id
),
INDEX
idx_created_at
(
created_at
),
INDEX
idx_username
(
username
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'登录日志表'
;
-- ----------------------------
-- 10. 短信验证码表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_sms_code
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
phone
VARCHAR
(
20
)
NOT
NULL
COMMENT
'手机号'
,
code
VARCHAR
(
10
)
NOT
NULL
COMMENT
'验证码'
,
type
VARCHAR
(
20
)
NOT
NULL
COMMENT
'用途:login/register/reset'
,
ip
VARCHAR
(
50
)
NOT
NULL
COMMENT
'请求IP'
,
expire_time
DATETIME
NOT
NULL
COMMENT
'过期时间'
,
is_used
TINYINT
DEFAULT
0
COMMENT
'是否已使用'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
INDEX
idx_phone_type
(
phone
,
type
),
INDEX
idx_created_at
(
created_at
),
INDEX
idx_expire_time
(
expire_time
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'短信验证码表'
;
-- ----------------------------
-- 11. 密码历史表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_password_history
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
user_id
BIGINT
NOT
NULL
COMMENT
'用户ID'
,
password_hash
VARCHAR
(
255
)
NOT
NULL
COMMENT
'历史密码哈希'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
INDEX
idx_pwd_history_user
(
user_id
,
created_at
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'密码历史表'
;
-- ----------------------------
-- 12. 角色自定义数据权限表
-- ----------------------------
CREATE
TABLE
IF
NOT
EXISTS
user_role_custom_dept
(
id
BIGINT
AUTO_INCREMENT
PRIMARY
KEY
,
role_id
BIGINT
NOT
NULL
COMMENT
'角色ID'
,
department_id
BIGINT
NOT
NULL
COMMENT
'部门ID'
,
created_at
DATETIME
DEFAULT
CURRENT_TIMESTAMP
,
UNIQUE
KEY
uk_role_dept
(
role_id
,
department_id
),
INDEX
idx_department_id
(
department_id
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'角色自定义数据权限表'
;
-- ============================================================
-- ALTER TABLE:修正已有表的字段(兼容旧表,不影响数据)
-- ============================================================
-- 修正 user_login_log.device 类型(User-Agent 远超 100 字符)
ALTER
TABLE
user_login_log
MODIFY
COLUMN
device
TEXT
COMMENT
'设备信息(User-Agent)'
;
-- 修正 user_login_log.fail_reason 长度(支持更长的错误原因描述)
ALTER
TABLE
user_login_log
MODIFY
COLUMN
fail_reason
VARCHAR
(
255
)
COMMENT
'失败原因'
;
-- 已有 user_role 表补 data_scope/sort/status 字段(不影响已存在的列)
ALTER
TABLE
user_role
ADD
COLUMN
IF
NOT
EXISTS
data_scope
TINYINT
DEFAULT
4
COMMENT
'数据权限:1=全部 2=本部门 3=本部门及下级 4=仅本人 5=自定义'
AFTER
is_preset
;
ALTER
TABLE
user_role
ADD
COLUMN
IF
NOT
EXISTS
sort
INT
DEFAULT
0
COMMENT
'排序号'
AFTER
data_scope
;
ALTER
TABLE
user_role
ADD
COLUMN
IF
NOT
EXISTS
status
TINYINT
DEFAULT
1
COMMENT
'状态:1=启用 0=禁用'
AFTER
sort
;
-- 已有 user_user 表补 must_change_password 字段(首次登录必须改密)
ALTER
TABLE
user_user
ADD
COLUMN
IF
NOT
EXISTS
must_change_password
TINYINT
DEFAULT
1
COMMENT
'首次登录是否必须修改密码:0=否 1=是'
;
-- 已有 user_sms_code 表补 created_at 索引
ALTER
TABLE
user_sms_code
ADD
INDEX
IF
NOT
EXISTS
idx_created_at
(
created_at
);
-- ============================================================
-- 插入预置角色数据
-- ============================================================
INSERT
IGNORE
INTO
user_role
(
role_name
,
role_code
,
description
,
is_preset
,
data_scope
,
sort
,
status
)
VALUES
(
'ADMIN'
,
'ROLE_ADMIN'
,
'管理员:全系统配置、用户管理'
,
1
,
1
,
0
,
1
),
(
'SUPERVISOR'
,
'ROLE_SUPERVISOR'
,
'主管:审核学员、内容终审'
,
1
,
3
,
1
,
1
),
(
'MENTOR'
,
'ROLE_MENTOR'
,
'导师:答辩评审、学员指导'
,
1
,
4
,
2
,
1
),
(
'STUDENT'
,
'ROLE_STUDENT'
,
'学员:参与实训、提交产物'
,
1
,
4
,
3
,
1
);
-- ============================================================
-- 插入预置权限数据
-- ============================================================
INSERT
IGNORE
INTO
user_permission
(
permission_code
,
permission_name
,
module
,
description
)
VALUES
-- 项目权限
(
'project:read'
,
'查看项目'
,
'project'
,
'查看项目列表和详情'
),
(
'project:create'
,
'创建项目'
,
'project'
,
'创建新项目'
),
(
'project:update'
,
'更新项目'
,
'project'
,
'修改项目信息'
),
(
'project:delete'
,
'删除项目'
,
'project'
,
'删除项目'
),
-- 实训权限
(
'training:read'
,
'查看实训'
,
'training'
,
'查看实训内容'
),
(
'training:submit'
,
'提交实训'
,
'training'
,
'提交实训产物'
),
(
'training:review'
,
'审核实训'
,
'training'
,
'审核学员实训'
),
-- 答辩权限
(
'defense:review'
,
'答辩评审'
,
'defense'
,
'参与答辩评审'
),
-- 审核权限
(
'audit:review'
,
'主管审核'
,
'audit'
,
'主管审核权限'
),
-- 用户管理权限
(
'user:read'
,
'查看用户'
,
'user'
,
'查看用户列表和详情'
),
(
'user:create'
,
'创建用户'
,
'user'
,
'创建新用户'
),
(
'user:update'
,
'更新用户'
,
'user'
,
'修改用户信息'
),
(
'user:delete'
,
'删除用户'
,
'user'
,
'删除用户'
),
(
'user:assign-role'
,
'分配角色'
,
'user'
,
'分配用户角色'
);
-- ============================================================
-- 为预置角色分配权限
-- ============================================================
-- ADMIN: 所有权限
INSERT
IGNORE
INTO
user_role_permission
(
role_id
,
permission_id
)
SELECT
1
,
id
FROM
user_permission
;
-- SUPERVISOR: 审核相关权限
INSERT
IGNORE
INTO
user_role_permission
(
role_id
,
permission_id
)
SELECT
2
,
id
FROM
user_permission
WHERE
permission_code
IN
(
'project:read'
,
'training:read'
,
'training:review'
,
'defense:review'
,
'audit:review'
);
-- MENTOR: 导师相关权限
INSERT
IGNORE
INTO
user_role_permission
(
role_id
,
permission_id
)
SELECT
3
,
id
FROM
user_permission
WHERE
permission_code
IN
(
'project:read'
,
'project:update'
,
'training:read'
,
'defense:review'
);
-- STUDENT: 学员权限
INSERT
IGNORE
INTO
user_role_permission
(
role_id
,
permission_id
)
SELECT
4
,
id
FROM
user_permission
WHERE
permission_code
IN
(
'project:read'
,
'training:read'
,
'training:submit'
);
-- ============================================================
-- 插入默认管理员账户 (密码: Admin123)
-- bcrypt加密后的密码
-- ============================================================
-- 管理员默认密码已配置,首次登录不需要改密
INSERT
IGNORE
INTO
user_user
(
username
,
password
,
real_name
,
email
,
role_id
,
status
,
is_deleted
,
must_change_password
)
VALUES
(
'admin'
,
'$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG'
,
'系统管理员'
,
'admin@example.com'
,
1
,
1
,
0
,
0
);
-- 为管理员分配ADMIN角色
INSERT
IGNORE
INTO
user_user_role
(
user_id
,
role_id
)
VALUES
(
1
,
1
);
-- ============================================================
-- 插入默认部门数据
-- ============================================================
INSERT
IGNORE
INTO
user_department
(
name
,
code
,
description
)
VALUES
(
'技术部'
,
'tech'
,
'负责系统研发和技术支持'
),
(
'标注部'
,
'annotation'
,
'负责数据标注和质量管理'
);
SET
FOREIGN_KEY_CHECKS
=
1
;
平台文档/user-module-任务文档.md
浏览文件 @
299ccb35
...
@@ -67,6 +67,18 @@ user-module
...
@@ -67,6 +67,18 @@ user-module
┌──────────────┐ ┌─────────────────┐
┌──────────────┐ ┌─────────────────┐
│ user_user │──────<│ user_login_log │
│ user_user │──────<│ user_login_log │
└──────────────┘ └─────────────────┘
└──────────────┘ └─────────────────┘
┌──────────────┐ ┌─────────────────┐ ┌──────────────┐
│ user_menu │──────<│ user_role_menu │>──────│ user_role │
└──────────────┘ └─────────────────┘ └──────────────┘
┌──────────────┐ ┌────────────────────────┐
│ user_user │──────<│ user_password_history │
└──────────────┘ └────────────────────────┘
┌──────────────┐ ┌──────────────────────────┐
│ user_role │──────<│ user_role_custom_dept │
└──────────────┘ └──────────────────────────┘
```
```
### 2.2 表结构
### 2.2 表结构
...
@@ -85,11 +97,13 @@ user-module
...
@@ -85,11 +97,13 @@ user-module
| department_id | BIGINT | FK → user_department | 所属部门 |
| department_id | BIGINT | FK → user_department | 所属部门 |
| avatar_url | VARCHAR(500) | | 头像 |
| avatar_url | VARCHAR(500) | | 头像 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
| is_deleted | TINYINT | DEFAULT 0 | 软删除标记:0=正常 1=已删除 |
| created_at | DATETIME | | 创建时间 |
| created_at | DATETIME | | 创建时间 |
| updated_at | DATETIME | | 更新时间 |
> **说明**:role_id 字段保留用于单角色快速查询;多角色场景通过 user_user_role 关联表处理。
> **说明**:role_id 字段保留用于单角色快速查询;多角色场景通过 user_user_role 关联表处理。
**索引**
:(role_id),(department_id)
**索引**
:(role_id),(department_id)
,(status),(phone)
---
---
...
@@ -99,17 +113,25 @@ user-module
...
@@ -99,17 +113,25 @@ user-module
|------|------|------|------|
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| id | BIGINT | PK | 主键 |
| role_name | VARCHAR(50) | NOT NULL | 角色名称 |
| role_name | VARCHAR(50) | NOT NULL | 角色名称 |
| role_code | VARCHAR(50) | UNIQUE | 角色编码,用于 Spring Security(如 ROLE_ADMIN) |
| description | VARCHAR(200) | | 角色描述 |
| description | VARCHAR(200) | | 角色描述 |
| is_preset | TINYINT | DEFAULT 0 | 是否预置角色:0=否 1=是 |
| data_scope | TINYINT | DEFAULT 4 | 数据权限范围:1=全部 2=本部门 3=本部门及下级 4=仅本人 5=自定义 |
| sort | INT | DEFAULT 0 | 排序号 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
| created_at | DATETIME | | 创建时间 |
| created_at | DATETIME | | 创建时间 |
| updated_at | DATETIME | | 更新时间 |
> **说明**:data_scope 字段用于资源级权限控制,详见 4.10 节。
**预置角色**
:
**预置角色**
:
| role_name | 说明 |
| role_name |
role_code |
说明 |
|----------|------|
|----------
-|-----------
|------|
| ADMIN | 管理员:全系统配置、用户管理 |
| ADMIN |
ROLE_ADMIN |
管理员:全系统配置、用户管理 |
| SUPERVISOR | 主管:审核学员、内容终审 |
| SUPERVISOR |
ROLE_SUPERVISOR |
主管:审核学员、内容终审 |
| MENTOR | 导师:答辩评审、学员指导 |
| MENTOR |
ROLE_MENTOR |
导师:答辩评审、学员指导 |
| STUDENT | 学员:参与实训、提交产物 |
| STUDENT |
ROLE_STUDENT |
学员:参与实训、提交产物 |
---
---
...
@@ -134,8 +156,14 @@ user-module
...
@@ -134,8 +156,14 @@ user-module
| project:delete | 删除项目 |
| project:delete | 删除项目 |
| training:read | 查看实训 |
| training:read | 查看实训 |
| training:submit | 提交实训 |
| training:submit | 提交实训 |
| training:review | 审核实训 |
| defense:review | 答辩评审 |
| defense:review | 答辩评审 |
| audit:review | 主管审核 |
| audit:review | 主管审核 |
| user:read | 查看用户 |
| user:create | 创建用户 |
| user:update | 更新用户 |
| user:delete | 删除用户 |
| user:assign-role | 分配角色 |
---
---
...
@@ -211,6 +239,70 @@ user-module
...
@@ -211,6 +239,70 @@ user-module
---
---
#### 2.2.9 菜单表(user_menu)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| parent_id | BIGINT | DEFAULT 0 | 父菜单 ID,0=顶级菜单 |
| name | VARCHAR(50) | NOT NULL | 路由名称(前端路由 name,不可重复) |
| title | VARCHAR(50) | NOT NULL | 菜单标题(前端展示) |
| icon | VARCHAR(50) | | 图标标识 |
| path | VARCHAR(200) | | 路由路径 |
| component | VARCHAR(200) | | 前端组件路径 |
| permission_code | VARCHAR(50) | | 关联权限码(如 project:read) |
| type | TINYINT | NOT NULL | 类型:1=目录 2=菜单 3=按钮 |
| sort | INT | DEFAULT 0 | 排序号(升序) |
| visible | TINYINT | DEFAULT 1 | 是否可见:0=隐藏 1=显示 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
| created_at | DATETIME | | 创建时间 |
| updated_at | DATETIME | | 更新时间 |
**索引**
:(parent_id),(permission_code)
---
#### 2.2.10 角色菜单关联表(user_role_menu)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| role_id | BIGINT | FK → user_role | 角色 |
| menu_id | BIGINT | FK → user_menu | 菜单 |
| created_at | DATETIME | | 创建时间 |
**唯一索引**
:(role_id, menu_id)
---
#### 2.2.11 密码历史表(user_password_history)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 用户 ID |
| password_hash | VARCHAR(255) | NOT NULL | 历史密码哈希(bcrypt) |
| created_at | DATETIME | | 修改时间 |
**索引**
:(user_id, created_at DESC)
> **说明**:用于密码修改时校验「不可与最近 3 次密码相同」,仅保留最近 N 条(N 默认 3)。
---
#### 2.2.12 角色自定义数据权限表(user_role_custom_dept)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| role_id | BIGINT | FK → user_role | 角色 |
| department_id | BIGINT | FK → user_department | 自定义部门 |
| created_at | DATETIME | | 创建时间 |
**唯一索引**
:(role_id, department_id)
> **说明**:仅当 data_scope = 5(自定义)时生效,配置角色可访问的部门集合。
## 三、API 接口设计
## 三、API 接口设计
### 3.1 统一规范
### 3.1 统一规范
...
@@ -219,12 +311,24 @@ user-module
...
@@ -219,12 +311,24 @@ user-module
```
json
```
json
{
{
"code"
:
0
,
"code"
:
20
0
,
"message"
:
"操作成功"
,
"message"
:
"操作成功"
,
"data"
:
{}
"data"
:
{},
"traceId"
:
"a1b2c3d4e5f6"
,
"timestamp"
:
1720944000000
}
}
```
```
**字段说明**
:
| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 状态码:0=成功,其他见下表 |
| message | string | 提示信息 |
| data | object | 业务数据 |
| traceId | string | 链路追踪 ID(用于日志检索) |
| timestamp | long | 服务端时间戳(毫秒) |
**状态码定义**
:
**状态码定义**
:
| 区间 | 说明 |
| 区间 | 说明 |
...
@@ -237,7 +341,7 @@ user-module
...
@@ -237,7 +341,7 @@ user-module
```
json
```
json
{
{
"code"
:
0
,
"code"
:
20
0
,
"data"
:
{
"data"
:
{
"total"
:
100
,
"total"
:
100
,
"page"
:
1
,
"page"
:
1
,
...
@@ -249,6 +353,77 @@ user-module
...
@@ -249,6 +353,77 @@ user-module
---
---
#### 3.1.3 HTTP 状态码规范
> 接口的 HTTP 响应状态码按 RESTful 规范执行;响应体中的 `code` 字段为**业务码**(0=成功),二者职责分离。
**HTTP 状态码总表**
:
| HTTP 状态码 | 含义 | 适用场景 | 业务码示例 |
|------------|------|----------|-----------|
| 200 OK | 请求成功 | GET / PUT / POST(无返回体) | 0 |
| 201 Created | 资源创建成功 | POST 创建类 | 0 |
| 204 No Content | 无返回内容 | DELETE 删除成功 | - |
| 400 Bad Request | 请求参数错误 | 参数校验失败、字段缺失 | 1001 |
| 401 Unauthorized | 未登录 / Token 失效 | Token 过期、Token 非法、未登录 | 1002 |
| 403 Forbidden | 无权限访问 | @PreAuthorize 拒绝、角色不足 | 1003 |
| 404 Not Found | 资源不存在 | 用户不存在、菜单不存在 | 1004 |
| 409 Conflict | 资源冲突 | 用户名 / 手机号已存在 | 2002 |
| 423 Locked | 账号被锁定 | 登录失败超过上限 | 2010 |
| 429 Too Many Requests | 请求过于频繁 | IP 限流、短信频控 | 1005 |
| 500 Internal Server Error | 服务器内部错误 | 未知异常 | 9999 |
**接口 → 状态码对照表**
:
| 模块 | 接口 | Method | 成功 | 主要异常 |
|------|------|--------|------|----------|
| 认证 | /auth/login | POST | 200 | 400/401/423/429 |
| 认证 | /auth/refresh | POST | 200 | 401 |
| 认证 | /auth/register | POST | 201 | 400/409/429 |
| 认证 | /auth/logout | POST | 200 | 401 |
| 认证 | /auth/sms-code | POST | 200 | 400/429 |
| 认证 | /auth/reset-password | POST | 200 | 400/404/429 |
| 用户 | /users/me | GET | 200 | 401 |
| 用户 | /users/{id} | GET | 200 | 401/403/404 |
| 用户 | /users/{id} | PUT | 200 | 400/401/403/404/409 |
| 用户 | /users/{id}/password | PUT | 200 | 400/401 |
| 用户 | /users | GET | 200 | 401/403 |
| 用户 | /users | POST | 201 | 400/401/403/409 |
| 用户 | /users/{id} | DELETE | 204 | 401/403/404 |
| 用户 | /users/{id}/password/reset | PUT | 200 | 400/401/403/404 |
| 用户 | /users/batch-import | POST | 200 | 400/401/403 |
| 用户 | /users/batch-import/{taskId} | GET | 200 | 401/404 |
| 用户 | /users/{id}/roles | PUT | 200 | 400/401/403/404 |
| 用户 | /users/{id}/unlock | PUT | 200 | 401/403/404 |
| 角色 | /roles | GET | 200 | 401 |
| 角色 | /roles/{id} | GET | 200 | 401/404 |
| 角色 | /roles | POST | 201 | 400/401/403/409 |
| 角色 | /roles/{id} | PUT | 200 | 400/401/403/404 |
| 角色 | /roles/{id} | DELETE | 204 | 401/403/404/409 |
| 角色 | /roles/{roleId}/menus | PUT | 200 | 400/401/403/404 |
| 菜单 | /menus | GET | 200 | 401 |
| 菜单 | /menus/tree | GET | 200 | 401/403 |
| 菜单 | /menus/{id} | GET | 200 | 401/403/404 |
| 菜单 | /menus | POST | 201 | 400/401/403/409 |
| 菜单 | /menus/{id} | PUT | 200 | 400/401/403/404 |
| 菜单 | /menus/{id} | DELETE | 204 | 401/403/404/409 |
**典型异常响应示例**
:
| 场景 | HTTP | 业务码 | message |
|------|------|--------|---------|
| 账号密码错误 | 401 | 1002 | 账号或密码错误 |
| Token 过期 | 401 | 1002 | 认证失败,请重新登录 |
| 无权限访问 | 403 | 1003 | 无权限访问 |
| 用户不存在 | 404 | 1004 | 用户不存在 |
| 手机号已注册 | 409 | 2002 | 该手机号已注册 |
| 账号已锁定 | 423 | 2010 | 账号已被锁定,请 10 分钟后再试 |
| 短信发送频繁 | 429 | 1005 | 请求过于频繁,请稍后再试 |
| 参数校验失败 | 400 | 1001 | password: 密码长度 8-20 位 |
| 服务器内部错误 | 500 | 9999 | 系统繁忙,请稍后再试 |
---
### 3.2 认证接口(/api/v1/auth)
### 3.2 认证接口(/api/v1/auth)
#### 3.2.1 登录
#### 3.2.1 登录
...
@@ -270,7 +445,7 @@ POST /api/v1/auth/login
...
@@ -270,7 +445,7 @@ POST /api/v1/auth/login
```
json
```
json
{
{
"code"
:
0
,
"code"
:
20
0
,
"message"
:
"登录成功"
,
"message"
:
"登录成功"
,
"data"
:
{
"data"
:
{
"accessToken"
:
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
,
"accessToken"
:
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
,
...
@@ -294,7 +469,18 @@ POST /api/v1/auth/login
...
@@ -294,7 +469,18 @@ POST /api/v1/auth/login
-
[
]
密码错误返回"账号或密码错误"(不暴露具体原因)
-
[
]
密码错误返回"账号或密码错误"(不暴露具体原因)
-
[
]
登录成功清除错误计数
-
[
]
登录成功清除错误计数
-
[
]
记录登录日志(user_login_log)
-
[
]
记录登录日志(user_login_log)
-
[
]
登录失败超过 5 次锁定 30 分钟
-
[
]
登录失败超过 5 次锁定 10 分钟
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 登录成功 | 0 | 登录成功 |
| 400 | 请求参数缺失 / 格式错误 | 1001 | 参数错误 |
| 401 | 用户名或密码错误 | 1002 | 账号或密码错误 |
| 423 | 账号已被锁定 | 2010 | 账号已被锁定,请 10 分钟后再试 |
| 429 | 同一账号 1 分钟内请求 ≥ 10 次 | 1005 | 请求过于频繁,请稍后再试 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
...
@@ -316,7 +502,7 @@ POST /api/v1/auth/refresh
...
@@ -316,7 +502,7 @@ POST /api/v1/auth/refresh
```
json
```
json
{
{
"code"
:
0
,
"code"
:
20
0
,
"message"
:
"刷新成功"
,
"message"
:
"刷新成功"
,
"data"
:
{
"data"
:
{
"accessToken"
:
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
,
"accessToken"
:
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
,
...
@@ -329,6 +515,15 @@ POST /api/v1/auth/refresh
...
@@ -329,6 +515,15 @@ POST /api/v1/auth/refresh
-
[
]
refreshToken 有效时返回新的 accessToken
-
[
]
refreshToken 有效时返回新的 accessToken
-
[
]
refreshToken 过期或黑名单返回 401
-
[
]
refreshToken 过期或黑名单返回 401
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 刷新成功 | 0 | 刷新成功 |
| 400 | refreshToken 为空 / 格式错误 | 1001 | 参数错误 |
| 401 | refreshToken 过期 / 非法 / 黑名单 | 1002 | 认证失败,请重新登录 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.2.3 注册
#### 3.2.3 注册
...
@@ -340,12 +535,12 @@ POST /api/v1/auth/register
...
@@ -340,12 +535,12 @@ POST /api/v1/auth/register
**请求参数**
:
**请求参数**
:
```
json
```
json
{
{
"username"
:
"zhangsan"
,
"username"
:
"zhangsan"
,
"phone"
:
"13800138000"
,
"phone"
:
"13800138000"
,
"password"
:
"Aa123456"
,
"password"
:
"Aa123456"
,
"realName"
:
"张三"
"realName"
:
"张三"
}
}
```
```
**验收标准**
:
**验收标准**
:
...
@@ -356,6 +551,17 @@ POST /api/v1/auth/register
...
@@ -356,6 +551,17 @@ POST /api/v1/auth/register
-
[
]
新用户默认角色为"学员"(STUDENT)
-
[
]
新用户默认角色为"学员"(STUDENT)
-
[
]
密码数据库存储为 bcrypt 加密字符串
-
[
]
密码数据库存储为 bcrypt 加密字符串
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 201 | 注册成功 | 0 | 注册成功 |
| 400 | 参数校验失败(手机号格式 / 密码强度 / 验证码为空) | 1001 | 参数错误 |
| 400 | 验证码错误或已过期 | 2003 | 验证码错误或已过期 |
| 409 | 手机号已注册 | 2002 | 该手机号已注册 |
| 429 | 验证码请求过于频繁 | 1005 | 请求过于频繁,请稍后再试 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.2.4 登出
#### 3.2.4 登出
...
@@ -370,6 +576,14 @@ POST /api/v1/auth/logout
...
@@ -370,6 +576,14 @@ POST /api/v1/auth/logout
-
[
]
refreshToken 加入 Redis 黑名单
-
[
]
refreshToken 加入 Redis 黑名单
-
[
]
登出后 Token 无法使用
-
[
]
登出后 Token 无法使用
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 登出成功 | 0 | 登出成功 |
| 401 | 未登录 / Token 已失效 | 1002 | 认证失败,请重新登录 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.2.5 发送验证码
#### 3.2.5 发送验证码
...
@@ -395,6 +609,15 @@ POST /api/v1/auth/sms-code
...
@@ -395,6 +609,15 @@ POST /api/v1/auth/sms-code
-
[
]
单 IP 1 小时最多 10 次
-
[
]
单 IP 1 小时最多 10 次
-
[
]
记录发送日志(不含验证码内容)
-
[
]
记录发送日志(不含验证码内容)
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 发送成功 | 0 | 发送成功 |
| 400 | 手机号格式错误 / type 非法 | 1001 | 参数错误 |
| 429 | 60s 内重复请求 / 单 IP 超限 | 1005 | 请求过于频繁,请稍后再试 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.2.6 找回密码
#### 3.2.6 找回密码
...
@@ -418,6 +641,16 @@ POST /api/v1/auth/reset-password
...
@@ -418,6 +641,16 @@ POST /api/v1/auth/reset-password
-
[
]
验证码使用后立即失效
-
[
]
验证码使用后立即失效
-
[
]
新密码加密存储
-
[
]
新密码加密存储
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 重置成功 | 0 | 密码重置成功 |
| 400 | 参数错误 / 验证码错误 / 密码强度不足 | 1001 / 2003 | 参数错误 / 验证码错误或已过期 |
| 404 | 该手机号未注册 | 2001 | 用户不存在 |
| 429 | 请求过于频繁 | 1005 | 请求过于频繁,请稍后再试 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
### 3.3 用户管理接口(/api/v1/users)
### 3.3 用户管理接口(/api/v1/users)
...
@@ -432,7 +665,7 @@ GET /api/v1/users/me
...
@@ -432,7 +665,7 @@ GET /api/v1/users/me
```
json
```
json
{
{
"code"
:
0
,
"code"
:
20
0
,
"data"
:
{
"data"
:
{
"id"
:
1
,
"id"
:
1
,
"username"
:
"admin"
,
"username"
:
"admin"
,
...
@@ -454,6 +687,14 @@ GET /api/v1/users/me
...
@@ -454,6 +687,14 @@ GET /api/v1/users/me
-
[
]
敏感字段脱敏展示(手机号 138
****
8000)
-
[
]
敏感字段脱敏展示(手机号 138
****
8000)
-
[
]
包含角色和权限列表
-
[
]
包含角色和权限列表
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 过期 / Token 非法 | 1002 | 认证失败,请重新登录 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.3.2 获取用户详情
#### 3.3.2 获取用户详情
...
@@ -466,6 +707,16 @@ GET /api/v1/users/{id}
...
@@ -466,6 +707,16 @@ GET /api/v1/users/{id}
-
[
]
敏感字段脱敏
-
[
]
敏感字段脱敏
-
[
]
返回用户完整角色信息
-
[
]
返回用户完整角色信息
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 无权限访问(非本人且非 ADMIN) | 1003 | 无权限访问 |
| 404 | 用户不存在 | 1004 | 用户不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.3.3 更新用户信息
#### 3.3.3 更新用户信息
...
@@ -489,6 +740,18 @@ PUT /api/v1/users/{id}
...
@@ -489,6 +740,18 @@ PUT /api/v1/users/{id}
-
[
]
更新手机号需验证码
-
[
]
更新手机号需验证码
-
[
]
更新后同步刷新 Redis 缓存
-
[
]
更新后同步刷新 Redis 缓存
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 更新成功 | 0 | 操作成功 |
| 400 | 参数校验失败 | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非本人且非 ADMIN | 1003 | 无权限访问 |
| 404 | 用户不存在 | 1004 | 用户不存在 |
| 409 | 手机号已被其他用户占用 | 2002 | 该手机号已被使用 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.3.4 修改密码
#### 3.3.4 修改密码
...
@@ -512,6 +775,18 @@ PUT /api/v1/users/{id}/password
...
@@ -512,6 +775,18 @@ PUT /api/v1/users/{id}/password
-
[
]
不可与最近 3 次密码相同
-
[
]
不可与最近 3 次密码相同
-
[
]
修改后 Token 刷新
-
[
]
修改后 Token 刷新
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 修改成功 | 0 | 操作成功 |
| 400 | 参数校验失败 / 新密码强度不足 | 1001 | 参数错误 |
| 400 | 旧密码错误 | 2004 | 旧密码错误 |
| 400 | 与最近 3 次密码相同 | 2005 | 不可与最近 3 次密码相同 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非本人且非 ADMIN | 1003 | 无权限访问 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.3.5 用户列表(ADMIN)
#### 3.3.5 用户列表(ADMIN)
...
@@ -520,12 +795,266 @@ PUT /api/v1/users/{id}/password
...
@@ -520,12 +795,266 @@ PUT /api/v1/users/{id}/password
GET /api/v1/users
GET /api/v1/users
```
```
**请求参数**
:page / size / keyword / role_id / department_id / status
**请求参数**
:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| page | int | 否 | 1 | 页码,从 1 开始 |
| size | int | 否 | 10 | 每页条数,最大 100 |
| keyword | string | 否 | - | 关键词,对 username / real_name / phone 模糊匹配 |
| role_id | long | 否 | - | 角色 ID(精确匹配) |
| department_id | long | 否 | - | 部门 ID(精确匹配) |
| status | int | 否 | - | 状态:0=禁用 1=启用 |
| sort_field | string | 否 | created_at | 排序字段:created_at / updated_at |
| sort_order | string | 否 | desc | 排序方向:asc / desc |
**响应参数**
:
```
json
{
"code"
:
200
,
"data"
:
{
"total"
:
100
,
"page"
:
1
,
"size"
:
10
,
"pages"
:
10
,
"items"
:
[
{
"id"
:
1
,
"username"
:
"admin"
,
"realName"
:
"管理员"
,
"phone"
:
"138****8000"
,
"email"
:
"admin@example.com"
,
"roleName"
:
"管理员"
,
"departmentName"
:
"技术部"
,
"status"
:
1
,
"lastLoginTime"
:
"2026-07-14 10:00:00"
,
"createdAt"
:
"2026-01-01 00:00:00"
}
]
}
}
```
**验收标准**
:
**验收标准**
:
-
[
]
支持分页查询
-
[
]
支持分页查询
(page / size)
-
[
]
关键词搜索:
姓名/用户名/手机号模糊匹配
-
[
]
关键词搜索:
username / real_name / phone 三字段 OR 模糊匹配(LIKE %keyword%)
-
[
]
角色筛选 / 部门筛选 / 状态筛选
-
[
]
角色筛选 / 部门筛选 / 状态筛选
-
[
]
默认按 created_at DESC 排序
-
[
]
列表中手机号 / 邮箱脱敏展示
-
[
]
仅 ADMIN 可访问(@PreAuthorize("hasRole('ADMIN')"))
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 400 | 参数校验失败(page / size 非法) | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.3.6 创建用户(ADMIN)
```
POST /api/v1/users
```
**请求参数**
:
```
json
{
"username"
:
"zhangsan"
,
"realName"
:
"张三"
,
"phone"
:
"13800138000"
,
"email"
:
"zhangsan@example.com"
,
"password"
:
"Aa123456"
,
"roleIds"
:
[
4
],
"departmentId"
:
1
,
"status"
:
1
}
```
**验收标准**
:
-
[
]
用户名 / 手机号全局唯一
-
[
]
密码强度校验:至少 8 位,包含大小写字母 + 数字
-
[
]
密码 bcrypt 加密存储(cost = 12)
-
[
]
角色关联写入 user_user_role
-
[
]
默认 status = 1(启用)
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 201 | 创建成功 | 0 | 创建成功 |
| 400 | 参数校验失败 / 密码强度不足 | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 409 | 用户名 / 手机号已存在 | 2002 | 用户名已存在 / 该手机号已注册 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.3.7 删除用户(ADMIN)
```
DELETE /api/v1/users/{id}
```
**验收标准**
:
-
[
]
软删除(is_deleted = 1),不物理删除
-
[
]
被删除用户无法登录(登录校验 is_deleted = 0)
-
[
]
不能删除自己(防止误操作)
-
[
]
不能删除 ADMIN 角色用户(防止系统瘫痪)
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 204 | 删除成功(无响应体) | - | - |
| 400 | 试图删除自己 | 2006 | 不能删除自己 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 用户不存在 | 1004 | 用户不存在 |
| 409 | 存在未结业务(如进行中实训) | 2007 | 用户存在未结业务,无法删除 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.3.8 重置用户密码(ADMIN)
```
PUT /api/v1/users/{id}/password/reset
```
**请求参数**
:
```
json
{
"newPassword"
:
"Aa123456"
}
```
**验收标准**
:
-
[
]
无需校验旧密码(管理员重置场景)
-
[
]
新密码强度校验
-
[
]
加密存储(cost = 12)
-
[
]
清除该用户所有 Token(加入黑名单)
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 重置成功 | 0 | 操作成功 |
| 400 | 参数校验失败 / 密码强度不足 | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 用户不存在 | 1004 | 用户不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.3.9 批量导入用户(ADMIN)
```
POST /api/v1/users/batch-import
```
**请求类型**
:
`multipart/form-data`
**请求参数**
:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | Excel 文件(.xlsx),首行为表头 |
| defaultRoleId | long | 否 | 默认角色 ID(未指定角色行使用) |
| defaultDepartmentId | long | 否 | 默认部门 ID |
| defaultPassword | string | 否 | 默认密码(不传则使用手机号后 6 位) |
**Excel 模板列**
:
| 列 | 字段名 | 必填 | 说明 |
|----|--------|------|------|
| A | username | 是 | 用户名 |
| B | real_name | 是 | 真实姓名 |
| C | phone | 是 | 手机号 |
| D | email | 否 | 邮箱 |
| E | role_codes | 否 | 角色编码,多个用英文逗号分隔,如
`STUDENT,MENTOR`
|
| F | department_code | 否 | 部门编码 |
**响应参数**
:
```
json
{
"code"
:
200
,
"message"
:
"导入完成"
,
"data"
:
{
"total"
:
100
,
"successCount"
:
95
,
"failCount"
:
5
,
"failDetails"
:
[
{
"rowNum"
:
3
,
"username"
:
"lisi"
,
"reason"
:
"手机号已存在"
},
{
"rowNum"
:
12
,
"username"
:
"wangwu"
,
"reason"
:
"角色编码不存在"
}
]
}
}
```
**验收标准**
:
-
[
]
文件大小限制:≤ 5MB,行数限制:≤ 1000 行
-
[
]
逐行校验,单行失败不影响整体导入
-
[
]
用户名 / 手机号重复的行跳过并记录
-
[
]
角色编码 / 部门编码不存在时跳过该行
-
[
]
默认密码策略:未填写则使用手机号后 6 位
-
[
]
密码统一 bcrypt 加密存储(cost = 12)
-
[
]
导入完成返回成功 / 失败明细
-
[
]
异步处理:返回 taskId,前端轮询查询导入结果
**查询导入进度**
:
```
GET /api/v1/users/batch-import/{taskId}
```
**响应参数**
:
```
json
{
"code"
:
200
,
"data"
:
{
"taskId"
:
"uuid"
,
"status"
:
"PROCESSING"
,
"total"
:
100
,
"processed"
:
60
,
"successCount"
:
58
,
"failCount"
:
2
,
"progress"
:
60
}
}
```
**status 可选值**
:PENDING / PROCESSING / SUCCESS / FAILED
**返回状态码(3.3.9 批量导入)**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 提交成功,返回 taskId | 0 | 导入任务已提交 |
| 400 | 文件为空 / 文件格式错误 / 行数超限 | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
**返回状态码(3.3.10 进度查询)**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 404 | taskId 不存在 | 1004 | 任务不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
...
@@ -541,7 +1070,7 @@ GET /api/v1/roles
...
@@ -541,7 +1070,7 @@ GET /api/v1/roles
```
json
```
json
{
{
"code"
:
0
,
"code"
:
20
0
,
"data"
:
[
"data"
:
[
{
{
"id"
:
1
,
"id"
:
1
,
...
@@ -554,6 +1083,14 @@ GET /api/v1/roles
...
@@ -554,6 +1083,14 @@ GET /api/v1/roles
}
}
```
```
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.4.2 获取角色详情
#### 3.4.2 获取角色详情
...
@@ -566,7 +1103,7 @@ GET /api/v1/roles/{id}
...
@@ -566,7 +1103,7 @@ GET /api/v1/roles/{id}
```
json
```
json
{
{
"code"
:
0
,
"code"
:
20
0
,
"data"
:
{
"data"
:
{
"id"
:
1
,
"id"
:
1
,
"roleName"
:
"管理员"
,
"roleName"
:
"管理员"
,
...
@@ -580,12 +1117,21 @@ GET /api/v1/roles/{id}
...
@@ -580,12 +1117,21 @@ GET /api/v1/roles/{id}
}
}
```
```
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 404 | 角色不存在 | 1004 | 角色不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.4.3 创建角色(ADMIN)
#### 3.4.3 创建角色(ADMIN)
```
```
POST /api/v1/roles
POST /api/v1/roles
```
```
**请求参数**
:
**请求参数**
:
...
@@ -602,6 +1148,17 @@ POST /api/v1/roles
...
@@ -602,6 +1148,17 @@ POST /api/v1/roles
-
[
]
角色名称唯一
-
[
]
角色名称唯一
-
[
]
权限关联创建
-
[
]
权限关联创建
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 201 | 创建成功 | 0 | 创建成功 |
| 400 | 参数校验失败(角色名称为空 / 权限ID非法) | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 409 | 角色名称已存在 / roleCode 已存在 | 2008 | 角色名称已存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.4.4 更新角色(ADMIN)
#### 3.4.4 更新角色(ADMIN)
...
@@ -615,6 +1172,18 @@ PUT /api/v1/roles/{id}
...
@@ -615,6 +1172,18 @@ PUT /api/v1/roles/{id}
-
[
]
权限关联更新
-
[
]
权限关联更新
-
[
]
刷新用户权限缓存
-
[
]
刷新用户权限缓存
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 更新成功 | 0 | 操作成功 |
| 400 | 参数校验失败 | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN / 预置角色不可修改 | 1003 | 无权限访问 / 预置角色不可修改 |
| 404 | 角色不存在 | 1004 | 角色不存在 |
| 409 | 角色名称已存在 | 2008 | 角色名称已存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
#### 3.4.5 删除角色(ADMIN)
#### 3.4.5 删除角色(ADMIN)
...
@@ -627,6 +1196,17 @@ DELETE /api/v1/roles/{id}
...
@@ -627,6 +1196,17 @@ DELETE /api/v1/roles/{id}
-
[
]
预置角色不可删除
-
[
]
预置角色不可删除
-
[
]
有关联用户不可删除
-
[
]
有关联用户不可删除
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 204 | 删除成功(无响应体) | - | - |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN / 预置角色不可删除 | 1003 | 无权限访问 / 预置角色不可删除 |
| 404 | 角色不存在 | 1004 | 角色不存在 |
| 409 | 存在关联用户 | 2009 | 该角色下存在用户,无法删除 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
---
### 3.5 菜单权限接口(/api/v1/menus)
### 3.5 菜单权限接口(/api/v1/menus)
...
@@ -641,7 +1221,7 @@ GET /api/v1/menus
...
@@ -641,7 +1221,7 @@ GET /api/v1/menus
```
json
```
json
{
{
"code"
:
0
,
"code"
:
20
0
,
"data"
:
[
"data"
:
[
{
{
"id"
:
1
,
"id"
:
1
,
...
@@ -668,68 +1248,334 @@ GET /api/v1/menus
...
@@ -668,68 +1248,334 @@ GET /api/v1/menus
-
[
]
Redis 缓存(key =
`menu:{userId}`
,TTL = 1 小时)
-
[
]
Redis 缓存(key =
`menu:{userId}`
,TTL = 1 小时)
-
[
]
角色变更时刷新缓存
-
[
]
角色变更时刷新缓存
---
**返回状态码**
:
## 四、功能点拆解 & 验收标准
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
### 4.1 登录模块
---
| 序号 | 功能点 | 描述 | 优先级 |
#### 3.5.2 获取完整菜单树(ADMIN)
|------|--------|------|--------|
| 1 | 账号密码登录 | username + password | P0 |
| 2 | JWT 双 Token | accessToken(2h) + refreshToken(7d) | P0 |
| 3 | Token 校验 | 请求拦截校验 JWT | P0 |
| 4 | Token 刷新 | refreshToken 换 accessToken | P0 |
| 5 | 登录日志 | 记录登录行为 | P1 |
| 6 | 登录锁定 | 连续 5 次失败锁定 30 分钟 | P0 |
**验收标准**
:
```
```
[ ] 输入正确账号密码,返回 accessToken + refreshToken
GET /api/v1/menus/tree
[ ] accessToken 有效期 2 小时,refreshToken 有效期 7 天
[ ] Token 包含用户ID、角色、过期时间签名
[ ] 密码错误时返回"账号或密码错误"
[ ] refreshToken 存储至 Redis,支持主动失效
[ ] 登录成功清除错误计数
[ ] 记录登录日志(user_login_log)
[ ] 连续 5 次密码错误,账号锁定 30 分钟
```
```
---
**请求参数**
:
### 4.2 注册模块
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | int | 否 | 状态筛选:0=禁用 1=启用 |
| 序号 | 功能点 | 描述 | 优先级 |
**响应参数**
:
|------|--------|------|--------|
| 1 | 表单校验 | 手机号/邮箱/密码格式校验 | P0 |
| 2 | 验证码校验 | 短信验证码校验 | P0 |
| 3 | 密码加密 | bcrypt 加密存储(cost = 12) | P0 |
| 4 | 重复检测 | 手机号/用户名唯一性 | P0 |
| 5 | 默认角色 | 注册分配"学员"角色 | P0 |
**验收标准**
:
```
json
```
{
[ ] 手机号格式:11位数字,1 开头
"code"
:
200
,
[ ] 密码强度:至少8位,包含大小写字母+数字
"data"
:
[
[ ] 验证码错误返回"验证码错误或已过期"
{
[ ] 已注册手机号返回"该手机号已注册"
"id"
:
1
,
[ ] 新用户默认角色为"学员"
"parentId"
:
0
,
[ ] 密码数据库存储为加密字符串
"name"
:
"项目管理"
,
"title"
:
"项目管理"
,
"icon"
:
"project"
,
"path"
:
"/projects"
,
"component"
:
"project/Index"
,
"permissionCode"
:
"project:read"
,
"type"
:
1
,
"sort"
:
1
,
"visible"
:
1
,
"status"
:
1
,
"createdAt"
:
"2026-01-01 00:00:00"
,
"children"
:
[
{
"id"
:
2
,
"parentId"
:
1
,
"name"
:
"项目列表"
,
"title"
:
"项目列表"
,
"icon"
:
"list"
,
"path"
:
"/projects/list"
,
"component"
:
"project/List"
,
"permissionCode"
:
"project:list"
,
"type"
:
2
,
"sort"
:
1
,
"visible"
:
1
,
"status"
:
1
}
]
}
]
}
```
```
---
**菜单 type 取值**
:
### 4.3 验证码模块
| 序号 | 功能点 | 描述 | 优先级 |
| 值 | 含义 |
|------|--------|------|--------|
|----|------|
| 1 | 发送验证码 | 生成 6 位数字验证码 | P0 |
| 1 | 目录(一级菜单,不可点击) |
| 2 | 防刷限制 | 同一手机 60s 内只能发一次 | P0 |
| 2 | 菜单(页面) |
| 3 | 有效期 | 验证码 5 分钟有效 | P0 |
| 3 | 按钮(页面内按钮权限) |
| 4 | Redis 存储 | key = sms:{phone}:{type},TTL = 5min | P0 |
| 5 | IP 限流 | 单 IP 1 小时最多 10 次 | P1 |
**验收标准**
:
| 6 | 验证码校验 | 一次性使用 | P0 |
-
[
]
返回完整菜单树形结构
| 7 | 错误计数 | 错误 3 次验证码失效 | P1 |
-
[
]
按 sort ASC, id ASC 排序
-
[
]
默认仅返回 status = 1 的菜单
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.5.3 获取菜单详情(ADMIN)
```
GET /api/v1/menus/{id}
```
**响应参数**
:
```
json
{
"code"
:
200
,
"data"
:
{
"id"
:
1
,
"parentId"
:
0
,
"name"
:
"项目管理"
,
"title"
:
"项目管理"
,
"icon"
:
"project"
,
"path"
:
"/projects"
,
"component"
:
"project/Index"
,
"permissionCode"
:
"project:read"
,
"type"
:
1
,
"sort"
:
1
,
"visible"
:
1
,
"status"
:
1
,
"createdAt"
:
"2026-01-01 00:00:00"
,
"updatedAt"
:
"2026-01-01 00:00:00"
}
}
```
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 菜单不存在 | 1004 | 菜单不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.5.4 创建菜单(ADMIN)
```
POST /api/v1/menus
```
**请求参数**
:
```
json
{
"parentId"
:
0
,
"name"
:
"project"
,
"title"
:
"项目管理"
,
"icon"
:
"project"
,
"path"
:
"/projects"
,
"component"
:
"project/Index"
,
"permissionCode"
:
"project:read"
,
"type"
:
1
,
"sort"
:
1
,
"visible"
:
1
,
"status"
:
1
}
```
**验收标准**
:
-
[
]
parentId = 0 表示顶级菜单
-
[
]
parentId ≠ 0 时校验父菜单存在
-
[
]
permissionCode 关联到 user_permission 表(可为空,按钮类型必填)
-
[
]
name 同级菜单下唯一
-
[
]
创建后刷新全量用户菜单缓存(
`menu:*`
)
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 201 | 创建成功 | 0 | 创建成功 |
| 400 | 参数校验失败 / type=3 时 permissionCode 缺失 | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 父菜单不存在 | 1004 | 父菜单不存在 |
| 409 | 同级菜单下 name 重复 | 2011 | 菜单名称已存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.5.5 更新菜单(ADMIN)
```
PUT /api/v1/menus/{id}
```
**请求参数**
:
```
json
{
"title"
:
"项目管理新版"
,
"icon"
:
"project-new"
,
"path"
:
"/projects/v2"
,
"sort"
:
2
,
"visible"
:
1
,
"status"
:
1
}
```
**验收标准**
:
-
[
]
不允许修改 name(前端路由名)
-
[
]
不允许将 parentId 修改为自己的子菜单(防循环引用)
-
[
]
修改后刷新全量用户菜单缓存
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 更新成功 | 0 | 操作成功 |
| 400 | 参数校验失败 / parentId 形成循环引用 | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 菜单不存在 | 1004 | 菜单不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.5.6 删除菜单(ADMIN)
```
DELETE /api/v1/menus/{id}
```
**验收标准**
:
-
[
]
存在子菜单时不允许删除
-
[
]
删除后清理权限关联
-
[
]
删除后刷新全量用户菜单缓存
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 204 | 删除成功(无响应体) | - | - |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 菜单不存在 | 1004 | 菜单不存在 |
| 409 | 存在子菜单 | 2012 | 存在子菜单,无法删除 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
#### 3.5.7 角色分配菜单(ADMIN)
```
PUT /api/v1/roles/{roleId}/menus
```
**请求参数**
:
```
json
{
"menuIds"
:
[
1
,
2
,
3
,
4
]
}
```
**验收标准**
:
-
[
]
替换式更新(先删后插)
-
[
]
校验 menuIds 全部存在
-
[
]
修改后刷新该角色下所有用户的菜单缓存
-
[
]
修改后刷新该角色下所有用户的权限缓存(
`user:perm:{userId}`
)
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 分配成功 | 0 | 操作成功 |
| 400 | 参数校验失败(menuIds 为空) | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 角色不存在 / 菜单不存在 | 1004 | 角色不存在 / 菜单不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
## 四、功能点拆解 & 验收标准
### 4.1 登录模块
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 账号密码登录 | username + password | P0 |
| 2 | JWT 双 Token | accessToken(2h) + refreshToken(7d) | P0 |
| 3 | Token 校验 | 请求拦截校验 JWT | P0 |
| 4 | Token 刷新 | refreshToken 换 accessToken | P0 |
| 5 | 登录日志 | 记录登录行为 | P1 |
| 6 | 登录锁定 | 连续 5 次失败锁定 10 分钟 | P0 |
**验收标准**
:
```
[ ] 输入正确账号密码,返回 accessToken + refreshToken
[ ] accessToken 有效期 2 小时,refreshToken 有效期 7 天
[ ] Token 包含用户ID、角色、过期时间签名
[ ] 密码错误时返回"账号或密码错误"
[ ] refreshToken 存储至 Redis,支持主动失效
[ ] 登录成功清除错误计数
[ ] 记录登录日志(user_login_log)
[ ] 连续 5 次密码错误,账号锁定 10 分钟
```
---
### 4.2 注册模块
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 表单校验 | 手机号/邮箱/密码格式校验 | P0 |
| 2 | 验证码校验 | 短信验证码校验 | P0 |
| 3 | 密码加密 | bcrypt 加密存储(cost = 12) | P0 |
| 4 | 重复检测 | 手机号/用户名唯一性 | P0 |
| 5 | 默认角色 | 注册分配"学员"角色 | P0 |
**验收标准**
:
```
[ ] 手机号格式:11位数字,1 开头
[ ] 密码强度:至少8位,包含大小写字母+数字
[ ] 验证码错误返回"验证码错误或已过期"
[ ] 已注册手机号返回"该手机号已注册"
[ ] 新用户默认角色为"学员"
[ ] 密码数据库存储为加密字符串
```
---
### 4.3 验证码模块
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 发送验证码 | 生成 6 位数字验证码 | P0 |
| 2 | 防刷限制 | 同一手机 60s 内只能发一次 | P0 |
| 3 | 有效期 | 验证码 5 分钟有效 | P0 |
| 4 | Redis 存储 | key = sms:{phone}:{type},TTL = 5min | P0 |
| 5 | IP 限流 | 单 IP 1 小时最多 10 次 | P1 |
| 6 | 验证码校验 | 一次性使用 | P0 |
| 7 | 错误计数 | 错误 3 次验证码失效 | P1 |
**验收标准**
:
**验收标准**
:
```
```
...
@@ -859,6 +1705,373 @@ GET /api/v1/menus
...
@@ -859,6 +1705,373 @@ GET /api/v1/menus
---
---
### 4.10 资源级权限
资源级权限在「方法级权限」通过之后,进一步控制「能操作哪些数据」。
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 数据权限范围 | ALL / DEPARTMENT / DEPARTMENT_AND_SUB / SELF / CUSTOM | P1 |
| 2 | 部门权限 | 仅可访问本部门及下级部门数据 | P1 |
| 3 | 本人权限 | 仅可访问本人创建的数据 | P1 |
| 4 | 自定义数据权限 | 自定义部门范围 | P2 |
| 5 | 数据权限注解 | @DataScope 注解 + 拦截器 | P1 |
**数据权限范围(user_role.data_scope)**
:
| 取值 | 说明 | SQL 注入示例 |
|------|------|-------------|
| 1 | 全部数据(ALL) | 无附加条件 |
| 2 | 本部门(DEPARTMENT) |
`AND u.department_id = #{user.deptId}`
|
| 3 | 本部门及下级(DEPARTMENT_AND_SUB) |
`AND u.department_id IN (#{deptAndChildren})`
|
| 4 | 仅本人(SELF) |
`AND u.id = #{userId}`
|
| 5 | 自定义(CUSTOM) |
`AND u.department_id IN (#{customDeptIds})`
|
**@DataScope 注解使用示例**
:
```
java
@DataScope
(
tableAlias
=
"u"
)
@PreAuthorize
(
"hasAuthority('user:read')"
)
public
PageResult
<
UserVO
>
listUsers
(
UserQuery
query
)
{
// 拦截器自动注入 user.deptId、user.userId
return
userMapper
.
selectList
(
query
);
}
```
**拦截器实现要点**
:
```
java
@Component
public
class
DataScopeInterceptor
implements
HandlerMethodArgumentResolver
{
// 1. 从 SecurityContext 取当前用户
// 2. 读取 user_role.data_scope
// 3. 根据 data_scope 生成 SQL 片段
// 4. 通过 ThreadLocal 传递给 MyBatis 拦截器拼接 SQL
}
```
**MyBatis 拦截器 SQL 拼接**
:
```
java
@Intercepts
(
@Signature
(
type
=
Executor
.
class
,
method
=
"query"
,
...))
public
class
DataScopeSqlInterceptor
implements
Interceptor
{
@Override
public
Object
intercept
(
Invocation
invocation
)
{
// 取出 ThreadLocal 中的数据权限 SQL 片段
String
dataScopeSql
=
DataScopeContext
.
get
();
if
(
dataScopeSql
!=
null
)
{
// 重写 SQL,追加 WHERE 条件
String
newSql
=
originalSql
+
" AND "
+
dataScopeSql
;
// 替换 BoundSql
}
}
}
```
**验收标准**
:
```
[ ] ADMIN 默认 data_scope = 1(全部)
[ ] 部门负责人 data_scope = 3(本部门及下级)
[ ] 普通学员 data_scope = 4(仅本人)
[ ] 列表接口自动注入数据范围 SQL
[ ] 自定义部门范围通过角色关联表配置
```
---
### 4.11 用户角色分配
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 单用户分配 | 替换式分配角色 | P0 |
| 2 | 批量分配 | 批量用户赋权 | P1 |
| 3 | 权限即时生效 | 清除用户权限缓存 | P0 |
**接口定义**
:
```
PUT /api/v1/users/{id}/roles
```
**请求参数**
:
```
json
{
"roleIds"
:
[
1
,
2
]
}
```
**验收标准**
:
-
[
]
替换式分配(先删后插)
-
[
]
ADMIN 角色仅可由其他 ADMIN 分配
-
[
]
分配后清除该用户菜单缓存(
`menu:{userId}`
)和权限缓存(
`user:perm:{userId}`
)
-
[
]
分配后该用户 Token 立即失效(强制重新登录)
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 分配成功 | 0 | 操作成功 |
| 400 | 参数校验失败(roleIds 为空) | 1001 | 参数错误 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 用户不存在 / 角色不存在 | 1004 | 用户不存在 / 角色不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
### 4.12 密码安全
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 密码强度校验 | 大小写 + 数字 ≥ 8 位 | P0 |
| 2 | BCrypt 加密 | cost = 12 | P0 |
| 3 | 密码历史 | 不可与最近 3 次密码相同 | P1 |
| 4 | 默认密码 | 批量导入使用临时密码 | P1 |
| 5 | 首次登录改密 | 强制修改默认密码 | P2 |
**密码强度规则(正则)**
:
```
regex
^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[A-Za-z\d!@#$%^&*()_+\-=]{8,20}$
```
**密码强度校验实现**
:
```
java
public
class
PasswordValidator
{
private
static
final
Pattern
PATTERN
=
Pattern
.
compile
(
"^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)[A-Za-z\\d!@#$%^&*()_+\\-=]{8,20}$"
);
public
static
boolean
isValid
(
String
password
)
{
return
password
!=
null
&&
PATTERN
.
matcher
(
password
).
matches
();
}
}
```
**BCrypt 加密实现**
:
```
java
@Configuration
public
class
PasswordEncoderConfig
{
@Bean
public
PasswordEncoder
passwordEncoder
()
{
// strength = 12,对应 cost = 2^12 = 4096 轮迭代
return
new
BCryptPasswordEncoder
(
12
);
}
}
```
**密码历史校验实现**
:
```
java
@Service
public
class
PasswordHistoryService
{
private
static
final
int
HISTORY_LIMIT
=
3
;
public
boolean
isReusedPassword
(
Long
userId
,
String
newPassword
,
PasswordEncoder
encoder
)
{
List
<
String
>
recentHashes
=
userPasswordHistoryMapper
.
findRecentHashes
(
userId
,
HISTORY_LIMIT
);
return
recentHashes
.
stream
()
.
anyMatch
(
hash
->
encoder
.
matches
(
newPassword
,
hash
));
}
}
```
**user_password_history 表结构**
:
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 用户 ID |
| password_hash | VARCHAR(255) | NOT NULL | 历史密码哈希 |
| created_at | DATETIME | | 修改时间 |
**索引**
:(user_id, created_at DESC)
**验收标准**
:
-
[
]
密码长度 8-20 位
-
[
]
必须包含大小写字母 + 数字
-
[
]
不可与最近 3 次密码相同
-
[
]
修改密码成功后写入历史表
-
[
]
BCrypt cost = 12 不可在配置中修改为更小值
---
### 4.13 登录安全
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 登录失败计数 | Redis 计数失败次数 | P0 |
| 2 | 账号锁定 | 5 次失败锁定 10 分钟 | P0 |
| 3 | 锁定提示 | 返回剩余锁定时间 | P0 |
| 4 | 手动解锁 | ADMIN 可手动解锁 | P1 |
| 5 | 登录日志 | 记录成功 / 失败 | P0 |
| 6 | IP 限流 | 单 IP 1 小时 ≤ 10 次 | P1 |
**手动解锁接口(ADMIN)**
:
```
PUT /api/v1/users/{id}/unlock
```
**验收标准**
:
-
[
]
清除 Redis 中的
`login:fail:{phone}`
和
`login:locked:{phone}`
-
[
]
记录解锁日志(操作人、解锁时间、解锁原因)
**返回状态码**
:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 解锁成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 403 | 非 ADMIN | 1003 | 无权限访问 |
| 404 | 用户不存在 | 1004 | 用户不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
---
### 4.14 统一异常处理
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 全局异常拦截 | @RestControllerAdvice | P0 |
| 2 | 业务异常 | BizException + ErrorCode | P0 |
| 3 | 参数校验异常 | MethodArgumentNotValidException | P0 |
| 4 | 权限异常 | AccessDeniedException → 403 | P0 |
| 5 | 认证异常 | AuthenticationException → 401 | P0 |
| 6 | 未知异常 | 兜底 500 + traceId | P0 |
**异常码定义**
:
| 异常类 | HTTP 状态码 | 业务码 | 说明 |
|--------|------------|--------|------|
| BizException | 4xx / 5xx | 2xxx | 业务异常(按具体场景映射到 400/409/423/429 等) |
| ParamInvalidException | 400 | 1001 | 参数错误 |
| UnauthorizedException | 401 | 1002 | 未登录 |
| ForbiddenException | 403 | 1003 | 无权限 |
| ResourceNotFoundException | 404 | 1004 | 资源不存在 |
| AccessDeniedException | 403 | 1003 | 无权限(Spring Security 抛出) |
| AuthenticationException | 401 | 1002 | 认证失败(Spring Security 抛出) |
| AccountLockedException | 423 | 2010 | 账号已被锁定 |
| RateLimitException | 429 | 1005 | 请求过于频繁 |
| SystemException | 500 | 9999 | 系统异常 |
> **说明**:BizException 是所有业务异常的基类,HTTP 状态码由业务场景决定(如「手机号已注册」映射到 409,「账号已锁定」映射到 423)。
**统一异常响应格式**
:
```
json
{
"code"
:
2001
,
"message"
:
"用户不存在"
,
"data"
:
null
,
"traceId"
:
"a1b2c3d4"
,
"timestamp"
:
1720944000000
}
```
**全局异常处理器实现**
:
```
java
@RestControllerAdvice
public
class
GlobalExceptionHandler
{
/**
* 业务异常:按业务码映射 HTTP 状态码
*/
@ExceptionHandler
(
BizException
.
class
)
public
ResponseEntity
<
R
<
Void
>>
handleBiz
(
BizException
e
)
{
log
.
warn
(
"业务异常: code={}, msg={}"
,
e
.
getCode
(),
e
.
getMessage
());
HttpStatus
status
=
HttpStatusMapper
.
map
(
e
.
getCode
());
return
ResponseEntity
.
status
(
status
).
body
(
R
.
fail
(
e
.
getCode
(),
e
.
getMessage
()));
}
/**
* 参数校验异常 → 400
*/
@ExceptionHandler
(
MethodArgumentNotValidException
.
class
)
public
ResponseEntity
<
R
<
Void
>>
handleValid
(
MethodArgumentNotValidException
e
)
{
String
msg
=
e
.
getBindingResult
().
getFieldErrors
().
stream
()
.
map
(
f
->
f
.
getField
()
+
": "
+
f
.
getDefaultMessage
())
.
collect
(
Collectors
.
joining
(
"; "
));
return
ResponseEntity
.
status
(
HttpStatus
.
BAD_REQUEST
)
.
body
(
R
.
fail
(
1001
,
msg
));
}
/**
* Spring Security 权限异常 → 403
*/
@ExceptionHandler
(
AccessDeniedException
.
class
)
public
ResponseEntity
<
R
<
Void
>>
handleAccessDenied
(
AccessDeniedException
e
)
{
return
ResponseEntity
.
status
(
HttpStatus
.
FORBIDDEN
)
.
body
(
R
.
fail
(
1003
,
"无权限访问"
));
}
/**
* Spring Security 认证异常 → 401
*/
@ExceptionHandler
(
AuthenticationException
.
class
)
public
ResponseEntity
<
R
<
Void
>>
handleAuth
(
AuthenticationException
e
)
{
return
ResponseEntity
.
status
(
HttpStatus
.
UNAUTHORIZED
)
.
body
(
R
.
fail
(
1002
,
"认证失败,请重新登录"
));
}
/**
* 未知异常 → 500 + traceId
*/
@ExceptionHandler
(
Exception
.
class
)
public
ResponseEntity
<
R
<
Void
>>
handleUnknown
(
Exception
e
)
{
String
traceId
=
MDC
.
get
(
"traceId"
);
log
.
error
(
"系统异常: traceId={}"
,
traceId
,
e
);
return
ResponseEntity
.
status
(
HttpStatus
.
INTERNAL_SERVER_ERROR
)
.
body
(
R
.
fail
(
9999
,
"系统繁忙,请稍后再试"
));
}
}
```
**业务码 → HTTP 状态码映射**
:
```
java
public
class
HttpStatusMapper
{
private
static
final
Map
<
Integer
,
HttpStatus
>
MAP
=
Map
.
of
(
1001
,
HttpStatus
.
BAD_REQUEST
,
// 参数错误
1002
,
HttpStatus
.
UNAUTHORIZED
,
// 未登录
1003
,
HttpStatus
.
FORBIDDEN
,
// 无权限
1004
,
HttpStatus
.
NOT_FOUND
,
// 资源不存在
1005
,
HttpStatus
.
TOO_MANY_REQUESTS
,
// 请求过于频繁
2001
,
HttpStatus
.
NOT_FOUND
,
// 用户不存在
2002
,
HttpStatus
.
CONFLICT
,
// 手机号 / 用户名已存在
2003
,
HttpStatus
.
BAD_REQUEST
,
// 验证码错误
2008
,
HttpStatus
.
CONFLICT
,
// 角色名称已存在
2009
,
HttpStatus
.
CONFLICT
,
// 角色存在关联用户
2010
,
HttpStatus
.
LOCKED
,
// 账号已锁定
2011
,
HttpStatus
.
CONFLICT
,
// 菜单名称已存在
2012
,
HttpStatus
.
CONFLICT
// 存在子菜单
);
public
static
HttpStatus
map
(
int
bizCode
)
{
return
MAP
.
getOrDefault
(
bizCode
,
HttpStatus
.
BAD_REQUEST
);
}
}
```
**验收标准**
:
-
[
]
所有异常统一返回 R
<T>
结构
-
[
]
业务异常按业务码自动映射到正确的 HTTP 状态码
-
[
]
参数校验异常 → HTTP 400
-
[
]
权限异常 → HTTP 403,认证异常 → HTTP 401
-
[
]
校验异常聚合所有字段错误
-
[
]
未知异常不暴露堆栈,仅返回 traceId
-
[
]
异常日志记录 traceId,便于链路追踪
---
## 五、技术实现要点
## 五、技术实现要点
### 5.1 JWT Token 结构
### 5.1 JWT Token 结构
...
@@ -884,8 +2097,15 @@ GET /api/v1/menus
...
@@ -884,8 +2097,15 @@ GET /api/v1/menus
|
`token:refresh:{userId}`
| 刷新令牌 | 7d |
|
`token:refresh:{userId}`
| 刷新令牌 | 7d |
|
`token:blacklist:{refreshToken}`
| 登出黑名单 | 2h |
|
`token:blacklist:{refreshToken}`
| 登出黑名单 | 2h |
|
`sms:{phone}:{type}`
| 短信验证码 | 5min |
|
`sms:{phone}:{type}`
| 短信验证码 | 5min |
|
`login:fail:{phone}`
| 登录失败计数 | 30min |
|
`sms:limit:ip:{ip}`
| 短信发送 IP 限流计数 | 1h |
|
`sms:limit:phone:{phone}`
| 短信发送频控(60s) | 60s |
|
`login:fail:{phone}`
| 登录失败计数 | 10min |
|
`login:locked:{phone}`
| 账号锁定标记 | 10min |
|
`menu:{userId}`
| 用户菜单缓存 | 1h |
|
`menu:{userId}`
| 用户菜单缓存 | 1h |
|
`user:perm:{userId}`
| 用户权限码缓存 | 1h |
|
`pwd:reset:code:{phone}`
| 找回密码验证码 | 5min |
---
### 5.3 Security 配置
### 5.3 Security 配置
...
@@ -895,15 +2115,42 @@ GET /api/v1/menus
...
@@ -895,15 +2115,42 @@ GET /api/v1/menus
@EnableMethodSecurity
(
prePostEnabled
=
true
)
@EnableMethodSecurity
(
prePostEnabled
=
true
)
public
class
SecurityConfig
{
public
class
SecurityConfig
{
private
static
final
String
[]
WHITELIST
=
{
"/api/v1/auth/login"
,
"/api/v1/auth/register"
,
"/api/v1/auth/refresh"
,
"/api/v1/auth/sms-code"
,
"/api/v1/auth/reset-password"
,
"/api/health"
,
"/swagger-ui/**"
,
"/v3/api-docs/**"
};
@Bean
@Bean
public
SecurityFilterChain
filterChain
(
HttpSecurity
http
)
throws
Exception
{
public
SecurityFilterChain
filterChain
(
HttpSecurity
http
)
throws
Exception
{
http
http
.
csrf
(
AbstractHttpConfigurer:
:
disable
)
.
csrf
(
AbstractHttpConfigurer:
:
disable
)
.
sessionManagement
(
s
->
s
.
sessionCreationPolicy
(
SessionCreationPolicy
.
STATELESS
))
.
authorizeHttpRequests
(
auth
->
auth
.
authorizeHttpRequests
(
auth
->
auth
.
requestMatchers
(
"/api/v1/auth/**"
).
permitAll
()
.
requestMatchers
(
WHITELIST
).
permitAll
()
.
requestMatchers
(
"/api/health"
).
permitAll
()
.
anyRequest
().
authenticated
()
.
anyRequest
().
authenticated
()
)
)
// 未登录(401)
.
exceptionHandling
(
ex
->
ex
.
authenticationEntryPoint
((
req
,
resp
,
e
)
->
{
resp
.
setStatus
(
HttpServletResponse
.
SC_UNAUTHORIZED
);
resp
.
setContentType
(
MediaType
.
APPLICATION_JSON_VALUE
);
resp
.
getWriter
().
write
(
"{\"code\":1002,\"message\":\"认证失败,请重新登录\"}"
);
})
// 无权限(403)
.
accessDeniedHandler
((
req
,
resp
,
e
)
->
{
resp
.
setStatus
(
HttpServletResponse
.
SC_FORBIDDEN
);
resp
.
setContentType
(
MediaType
.
APPLICATION_JSON_VALUE
);
resp
.
getWriter
().
write
(
"{\"code\":1003,\"message\":\"无权限访问\"}"
);
})
)
.
addFilterBefore
(
jwtAuthFilter
,
UsernamePasswordAuthenticationFilter
.
class
);
.
addFilterBefore
(
jwtAuthFilter
,
UsernamePasswordAuthenticationFilter
.
class
);
return
http
.
build
();
return
http
.
build
();
...
@@ -918,7 +2165,7 @@ public class SecurityConfig {
...
@@ -918,7 +2165,7 @@ public class SecurityConfig {
public
class
LoginAttemptService
{
public
class
LoginAttemptService
{
private
static
final
int
MAX_ATTEMPTS
=
5
;
private
static
final
int
MAX_ATTEMPTS
=
5
;
private
static
final
int
LOCK_DURATION_MINUTES
=
3
0
;
private
static
final
int
LOCK_DURATION_MINUTES
=
1
0
;
public
void
loginSucceeded
(
String
phone
)
{
public
void
loginSucceeded
(
String
phone
)
{
redisTemplate
.
delete
(
"login:fail:"
+
phone
);
redisTemplate
.
delete
(
"login:fail:"
+
phone
);
...
@@ -940,6 +2187,248 @@ public class LoginAttemptService {
...
@@ -940,6 +2187,248 @@ public class LoginAttemptService {
---
---
### 5.5 JWT 工具类
```
java
@Component
public
class
JwtUtil
{
private
static
final
String
SECRET
=
"your-256-bit-secret-key-here-please-change"
;
private
static
final
long
ACCESS_EXPIRE_MS
=
2
*
60
*
60
*
1000L
;
// 2h
private
static
final
long
REFRESH_EXPIRE_MS
=
7
*
24
*
60
*
60
*
1000L
;
// 7d
private
final
JwtParser
parser
;
private
final
JwtBuilder
builder
;
public
JwtUtil
()
{
SecretKeySpec
key
=
new
SecretKeySpec
(
SECRET
.
getBytes
(),
"HmacSHA256"
);
this
.
parser
=
Jwts
.
parser
().
verifyWith
(
key
).
build
();
this
.
builder
=
Jwts
.
builder
().
signWith
(
key
,
Jwts
.
SIG
.
HS256
);
}
public
String
generateAccessToken
(
Long
userId
,
String
username
,
List
<
String
>
roles
)
{
return
builder
.
subject
(
String
.
valueOf
(
userId
))
.
claim
(
"username"
,
username
)
.
claim
(
"roles"
,
roles
)
.
claim
(
"type"
,
"access"
)
.
issuedAt
(
new
Date
())
.
expiration
(
new
Date
(
System
.
currentTimeMillis
()
+
ACCESS_EXPIRE_MS
))
.
compact
();
}
public
String
generateRefreshToken
(
Long
userId
)
{
return
builder
.
subject
(
String
.
valueOf
(
userId
))
.
claim
(
"type"
,
"refresh"
)
.
issuedAt
(
new
Date
())
.
expiration
(
new
Date
(
System
.
currentTimeMillis
()
+
REFRESH_EXPIRE_MS
))
.
compact
();
}
public
Claims
parse
(
String
token
)
{
return
parser
.
parseSignedClaims
(
token
).
getPayload
();
}
public
boolean
isExpired
(
String
token
)
{
return
parse
(
token
).
getExpiration
().
before
(
new
Date
());
}
}
```
---
### 5.6 JWT 认证过滤器
```
java
@Component
public
class
JwtAuthFilter
extends
OncePerRequestFilter
{
@Autowired
private
JwtUtil
jwtUtil
;
@Autowired
private
RedisTemplate
<
String
,
String
>
redisTemplate
;
@Override
protected
void
doFilterInternal
(
HttpServletRequest
request
,
HttpServletResponse
response
,
FilterChain
chain
)
{
String
token
=
resolveToken
(
request
);
if
(
token
!=
null
&&
!
jwtUtil
.
isExpired
(
token
))
{
// 检查黑名单
String
blacklistKey
=
"token:blacklist:"
+
token
;
if
(
Boolean
.
TRUE
.
equals
(
redisTemplate
.
hasKey
(
blacklistKey
)))
{
writeUnauthorized
(
response
,
"Token 已失效"
);
return
;
}
// 解析并构造 Authentication
Claims
claims
=
jwtUtil
.
parse
(
token
);
String
userId
=
claims
.
getSubject
();
@SuppressWarnings
(
"unchecked"
)
List
<
String
>
roles
=
(
List
<
String
>)
claims
.
get
(
"roles"
);
List
<
SimpleGrantedAuthority
>
authorities
=
roles
.
stream
()
.
map
(
r
->
new
SimpleGrantedAuthority
(
"ROLE_"
+
r
))
.
collect
(
Collectors
.
toList
());
UsernamePasswordAuthenticationToken
auth
=
new
UsernamePasswordAuthenticationToken
(
userId
,
null
,
authorities
);
SecurityContextHolder
.
getContext
().
setAuthentication
(
auth
);
}
chain
.
doFilter
(
request
,
response
);
}
private
String
resolveToken
(
HttpServletRequest
request
)
{
String
bearer
=
request
.
getHeader
(
"Authorization"
);
return
(
bearer
!=
null
&&
bearer
.
startsWith
(
"Bearer "
))
?
bearer
.
substring
(
7
)
:
null
;
}
}
```
---
### 5.7 短信验证码服务
```
java
@Service
public
class
SmsCodeService
{
@Autowired
private
RedisTemplate
<
String
,
String
>
redisTemplate
;
@Autowired
private
SmsSender
smsSender
;
private
static
final
int
CODE_TTL_SECONDS
=
5
*
60
;
// 5 分钟
private
static
final
int
RESEND_INTERVAL_SECONDS
=
60
;
// 60 秒
private
static
final
int
IP_LIMIT_PER_HOUR
=
10
;
// 单 IP 1h ≤ 10 次
private
static
final
int
MAX_VERIFY_ERRORS
=
3
;
// 错误 3 次失效
public
void
send
(
String
phone
,
String
type
,
String
ip
)
{
// 1. IP 限流
String
ipKey
=
"sms:limit:ip:"
+
ip
;
Long
ipCount
=
redisTemplate
.
opsForValue
().
increment
(
ipKey
);
if
(
ipCount
==
1
)
{
redisTemplate
.
expire
(
ipKey
,
1
,
TimeUnit
.
HOURS
);
}
if
(
ipCount
>
IP_LIMIT_PER_HOUR
)
{
throw
new
BizException
(
"1004"
,
"请求过于频繁,请稍后再试"
);
}
// 2. 频控
String
cooldownKey
=
"sms:limit:phone:"
+
phone
+
":"
+
type
;
if
(
Boolean
.
TRUE
.
equals
(
redisTemplate
.
hasKey
(
cooldownKey
)))
{
throw
new
BizException
(
"1005"
,
"请稍后再试"
);
}
// 3. 生成验证码
String
code
=
RandomUtil
.
randomNumbers
(
6
);
// 4. 存储
String
codeKey
=
"sms:"
+
phone
+
":"
+
type
;
redisTemplate
.
opsForValue
().
set
(
codeKey
,
code
,
CODE_TTL_SECONDS
,
TimeUnit
.
SECONDS
);
redisTemplate
.
opsForValue
().
set
(
cooldownKey
,
"1"
,
RESEND_INTERVAL_SECONDS
,
TimeUnit
.
SECONDS
);
// 5. 发送
smsSender
.
send
(
phone
,
code
,
type
);
}
public
boolean
verify
(
String
phone
,
String
code
,
String
type
)
{
String
key
=
"sms:"
+
phone
+
":"
+
type
;
String
cached
=
redisTemplate
.
opsForValue
().
get
(
key
);
if
(
cached
==
null
)
{
return
false
;
}
if
(!
cached
.
equals
(
code
))
{
// 错误次数 +1,达到上限失效
String
errKey
=
"sms:err:"
+
phone
+
":"
+
type
;
Long
errors
=
redisTemplate
.
opsForValue
().
increment
(
errKey
);
if
(
errors
!=
null
&&
errors
>=
MAX_VERIFY_ERRORS
)
{
redisTemplate
.
delete
(
key
);
redisTemplate
.
delete
(
errKey
);
}
else
if
(
errors
!=
null
)
{
redisTemplate
.
expire
(
errKey
,
CODE_TTL_SECONDS
,
TimeUnit
.
SECONDS
);
}
return
false
;
}
// 验证通过,删除(一次性)
redisTemplate
.
delete
(
key
);
redisTemplate
.
delete
(
"sms:err:"
+
phone
+
":"
+
type
);
return
true
;
}
}
```
---
### 5.8 登录日志记录
```
java
@Aspect
@Component
public
class
LoginLogAspect
{
@Autowired
private
UserLoginLogMapper
loginLogMapper
;
@AfterReturning
(
"execution(* com.platform.auth.controller.AuthController.login(..)) && args(req)"
)
public
void
logSuccess
(
JoinPoint
jp
,
LoginRequest
req
)
{
UserLoginLog
log
=
new
UserLoginLog
();
log
.
setUsername
(
req
.
getUsername
());
log
.
setStatus
((
byte
)
1
);
log
.
setIp
(
WebUtil
.
getClientIp
());
log
.
setDevice
(
WebUtil
.
getDevice
());
loginLogMapper
.
insert
(
log
);
}
@AfterThrowing
(
pointcut
=
"execution(* com.platform.auth.controller.AuthController.login(..))"
,
throwing
=
"ex"
)
public
void
logFailure
(
JoinPoint
jp
,
Throwable
ex
)
{
Object
[]
args
=
jp
.
getArgs
();
if
(
args
.
length
>
0
&&
args
[
0
]
instanceof
LoginRequest
req
)
{
UserLoginLog
log
=
new
UserLoginLog
();
log
.
setUsername
(
req
.
getUsername
());
log
.
setStatus
((
byte
)
2
);
log
.
setIp
(
WebUtil
.
getClientIp
());
log
.
setFailReason
(
ex
.
getMessage
());
loginLogMapper
.
insert
(
log
);
}
}
}
```
---
### 5.9 动态菜单组装
```
java
@Service
public
class
MenuService
{
@Autowired
private
UserRoleMapper
userRoleMapper
;
@Autowired
private
RoleMenuMapper
roleMenuMapper
;
@Autowired
private
UserMenuMapper
menuMapper
;
@Autowired
private
RedisTemplate
<
String
,
Object
>
redisTemplate
;
private
static
final
long
MENU_TTL_HOURS
=
1
;
public
List
<
MenuVO
>
getUserMenuTree
(
Long
userId
)
{
String
cacheKey
=
"menu:"
+
userId
;
List
<
MenuVO
>
cached
=
(
List
<
MenuVO
>)
redisTemplate
.
opsForValue
().
get
(
cacheKey
);
if
(
cached
!=
null
)
return
cached
;
// 查询用户角色 → 角色菜单 → 菜单详情
List
<
Long
>
roleIds
=
userRoleMapper
.
findRoleIdsByUserId
(
userId
);
List
<
Long
>
menuIds
=
roleMenuMapper
.
findMenuIdsByRoleIds
(
roleIds
);
List
<
UserMenu
>
allMenus
=
menuMapper
.
selectBatchIds
(
menuIds
);
// 组装树形结构
List
<
MenuVO
>
tree
=
buildTree
(
allMenus
,
0L
);
redisTemplate
.
opsForValue
().
set
(
cacheKey
,
tree
,
MENU_TTL_HOURS
,
TimeUnit
.
HOURS
);
return
tree
;
}
public
void
refreshCache
(
Long
userId
)
{
redisTemplate
.
delete
(
"menu:"
+
userId
);
redisTemplate
.
delete
(
"user:perm:"
+
userId
);
}
}
```
---
## 六、任务优先级
## 六、任务优先级
### P0(必须完成)
### P0(必须完成)
...
@@ -950,32 +2439,43 @@ public class LoginAttemptService {
...
@@ -950,32 +2439,43 @@ public class LoginAttemptService {
| 2 | Token 刷新接口 | 登录 |
| 2 | Token 刷新接口 | 登录 |
| 3 | 注册接口 + 短信验证码 | 注册 |
| 3 | 注册接口 + 短信验证码 | 注册 |
| 4 | 获取当前用户信息 | 用户 |
| 4 | 获取当前用户信息 | 用户 |
| 5 | 用户列表 + 分页 + 筛选 | 用户 |
| 5 | 用户列表 + 分页 +
关键词
筛选 | 用户 |
| 6 | 用户详情/更新/删除 | 用户 |
| 6 | 用户详情/
创建/
更新/删除 | 用户 |
| 7 | 角色列表/详情 | 角色 |
| 7 | 角色列表/详情 | 角色 |
| 8 | 角色创建/更新/删除 | 角色 |
| 8 | 角色创建/更新/删除 | 角色 |
| 9 | 权限码体系 + @PreAuthorize | 权限 |
| 9 | 权限码体系 + @PreAuthorize | 权限 |
| 10 | 登录锁定 | 安全 |
| 10 | 登录锁定(5 次/10 分钟) | 安全 |
| 11 | 统一响应格式 | 框架 |
| 11 | 统一响应格式 + 全局异常处理 | 框架 |
| 12 | BCrypt 密码加密(cost = 12) | 安全 |
| 13 | 密码强度校验 | 安全 |
| 14 | JWT 认证过滤器 + 白名单 | 框架 |
| 15 | 角色权限分配 | 权限 |
### P1(核心功能)
### P1(核心功能)
| 序号 | 任务 | 模块 |
| 序号 | 任务 | 模块 |
|------|------|------|
|------|------|------|
| 12 | 登出接口 + Token 黑名单 | 登出 |
| 16 | 登出接口 + Token 黑名单 | 登出 |
| 13 | 找回密码 | 密码 |
| 17 | 找回密码 | 密码 |
| 14 | 修改密码 | 密码 |
| 18 | 修改密码 | 密码 |
| 15 | 用户角色分配 | 权限 |
| 19 | 用户角色分配 | 权限 |
| 16 | 动态菜单接口 | 菜单 |
| 20 | 动态菜单接口(用户菜单) | 菜单 |
| 17 | 登录日志 | 日志 |
| 21 | 登录日志 | 日志 |
| 18 | IP 限流 | 安全 |
| 22 | IP 限流 | 安全 |
| 23 | 菜单树 CRUD(管理后台) | 菜单 |
| 24 | 批量导入用户 | 用户 |
| 25 | 资源级权限(数据权限范围) | 权限 |
| 26 | 手动解锁账号 | 安全 |
### P2(完善功能)
### P2(完善功能)
| 序号 | 任务 | 模块 |
| 序号 | 任务 | 模块 |
|------|------|------|
|------|------|------|
| 19 | 密码历史记录 | 安全 |
| 27 | 密码历史记录(不可与最近 3 次相同) | 安全 |
| 20 | 菜单缓存优化 | 菜单 |
| 28 | 菜单缓存优化 | 菜单 |
| 29 | 自定义数据权限(部门范围配置) | 权限 |
| 30 | 首次登录强制改密 | 安全 |
| 31 | 批量导入异步化 + 进度查询 | 用户 |
---
---
...
@@ -983,27 +2483,30 @@ public class LoginAttemptService {
...
@@ -983,27 +2483,30 @@ public class LoginAttemptService {
```
```
第一周:基础框架 + 登录
第一周:基础框架 + 登录
├── 1. 项目初始化 + 统一响应框架
├── 1. 项目初始化 + 统一响应框架
+ 全局异常处理
├── 2. JWT 工具类 + Redis 配置
├── 2. JWT 工具类 + Redis 配置
├── 3. 登录接口(username + password)
├── 3. 登录接口(username + password)
├── 4. Token 校验过滤器
├── 4. Token 校验过滤器
├── 5. Token 刷新接口
├── 5. Token 刷新接口
└── 6. 登录锁定
└── 6. 登录锁定
(5 次/10 分钟)
第二周:注册 + 用户管理 + 角色权限
第二周:注册 + 用户管理 + 角色权限
├── 1. 短信验证码接口(Redis)
├── 1. 短信验证码接口(Redis)
├── 2. 注册接口
├── 2. 注册接口
├── 3. 用户 CRUD 接口
├── 3. 用户 CRUD 接口
(含分页 + 关键词筛选)
├── 4. 角色 CRUD 接口
├── 4. 角色 CRUD 接口
├── 5. 权限码体系 + @PreAuthorize
├── 5. 权限码体系 + @PreAuthorize
└── 6. 找回/修改密码
├── 6. 找回/修改密码 + 密码强度校验 + bcrypt 加密
└── 7. 用户角色分配接口
第三周:完善 + 安全加固
第三周:完善 + 安全加固
├── 1. 登出 + Token 黑名单
├── 1. 登出 + Token 黑名单
├── 2. 动态菜单接口
├── 2. 动态菜单接口(用户菜单 + Redis 缓存)
├── 3. 登录日志
├── 3. 菜单树 CRUD 管理接口
├── 4. IP 限流
├── 4. 登录日志
└── 5. 单元测试 + 接口文档
├── 5. IP 限流 + 频控
├── 6. 资源级权限(@DataScope)
└── 7. 单元测试 + 接口文档
```
```
---
---
...
@@ -1029,6 +2532,12 @@ public class LoginAttemptService {
...
@@ -1029,6 +2532,12 @@ public class LoginAttemptService {
| GET /users/{id} | training-module | 获取导师/学员信息 |
| GET /users/{id} | training-module | 获取导师/学员信息 |
| GET /users/me | 所有模块 | 获取当前用户信息 |
| GET /users/me | 所有模块 | 获取当前用户信息 |
| GET /roles | 所有模块 | 获取角色列表用于权限判断 |
| GET /roles | 所有模块 | 获取角色列表用于权限判断 |
| POST /users/batch-import | admin-web | 批量导入用户(Excel) |
| GET /menus | 所有模块 | 获取当前用户菜单树 |
| GET /menus/tree | admin-web | 获取完整菜单树 |
| PUT /users/{id}/roles | admin-web | 分配用户角色 |
| PUT /users/{id}/password/reset | admin-web | 管理员重置密码 |
| PUT /users/{id}/unlock | admin-web | 手动解锁账号 |
### 9.2 调用其他模块接口
### 9.2 调用其他模块接口
...
@@ -1045,6 +2554,9 @@ public class LoginAttemptService {
...
@@ -1045,6 +2554,9 @@ public class LoginAttemptService {
| 权限绕过 | 高 | 全链路测试 + 代码审查 |
| 权限绕过 | 高 | 全链路测试 + 代码审查 |
| Redis 不可用 | 中 | 本地缓存降级 |
| Redis 不可用 | 中 | 本地缓存降级 |
| 短信轰炸 | 中 | IP 限流 + 手机号频控 |
| 短信轰炸 | 中 | IP 限流 + 手机号频控 |
| 批量导入 OOM | 中 | EasyExcel 流式读取 + 异步处理 |
| 资源级权限 SQL 拼接 | 高 | 参数化绑定,禁止字符串拼接用户输入 |
| 菜单循环引用 | 中 | 父子关系校验 + 树形深度限制 |
---
---
...
...
平台文档/用户模块需求与验收标准文档.md
0 → 100644
浏览文件 @
299ccb35
# 用户模块 · 需求与验收标准文档
项目:实习生培训平台
阶段:阶段一 · 基座搭建(需求整理)
模块:用户模块(user-module)
文档变更记录
版本:V1.0 | 日期:2026-07-15 | 初始版本,基于user-module-任务文档V1整理
版本:V2.0 | 日期:2026-07-16 | 补充业务状态码规范、完善边界测试用例、优化API清单
版本:v2.1 | 日期:2026-07-16 |全面对齐user-module-任务文档 V2:补充 4 张数据表、新增菜单管理/批量导入/数据权限等功能、修正锁定时间为 10 分钟、全面对齐 RESTful HTTP 状态码规范,完善全量测试用例。
**关联文档**
:
[
PRD文档
](
./PRD文档.docx
)
|
[
需求文档
](
./需求文档.docx
)
[
RBAC设计文档
](
./RBAC设计文档.md
)
|
[
数据库设计V1
](
./数据库设计V1.md
)
[
技术架构设计
](
./技术架构设计.md
)
[
user-module-任务文档
](
./user-module-任务文档0716.md
)
---
## 一、用户模块概述(来源依据)
### 1.1 模块定位
用户模块(user-module)是平台的基座模块,为所有业务模块(项目库、实训、答辩、审核、通知等)提供统一的认证与授权能力。
### 1.2 技术栈
来源:
[
user-module-任务文档
]
sec1.2
| 技术 | 版本 | 用途 |
| :-------------- | :------ | :------------------------ |
| Spring Boot | 3.x | 基础框架 |
| Spring Security | 6.x | 安全框架 |
| Spring Data JPA | 3.x | ORM |
| Redis | 7.x | 缓存、验证码、Token黑名单 |
| JWT (jjwt) | 0.12.x | Token 生成与校验 |
| BCrypt | cost=12 | 密码加密 |
| validation | 3.x | 参数校验 |
### 1.3 角色定义(4种预置角色)
来源:
[
数据库设计V1
]
sec3.1.2、
[
user-module-任务文档
]
sec2.2.2
| 角色 | 说明 |
| :--------- | :--------------------------- |
| ADMIN | 管理员:全系统配置、用户管理 |
| SUPERVISOR | 主管:审核学员、内容终审 |
| MENTOR | 导师:答辩评审、学员指导 |
| STUDENT | 学员:参与实训、提交产物 |
### 1.4 涉及的数据表(12张)
来源:
[
数据库设计V1
]
sec3.1、
[
user-module-任务文档
]
sec2.2
| 表名 | 说明 |
| :-------------------- | :----------------------------------------------------------- |
| user_user | 用户账号表(role_id FK, department_id FK, status, is_deleted) |
| user_role | 角色定义表(预置4条,含 data_scope 数据权限范围字段) |
| user_permission | 权限点表(permission_code / module / description) |
| user_role_permission | 角色-权限多对多关联表 |
| user_user_role | 用户-角色关联表,支持多角色 |
| user_department | 部门表(tech/annotation) |
| user_login_log | 登录日志表:记录登录IP/设备/地点/状态/失败原因 |
| user_sms_code | 短信验证码表:手机号/验证码/类型/IP/过期时间/是否已使用 |
| user_menu | 菜单表(新增:目录/菜单/按钮,路由配置) |
| user_role_menu | 角色-菜单关联表(新增) |
| user_password_history | 密码历史表(新增:用于校验不可与最近3次密码相同) |
| user_role_custom_dept | 角色自定义数据权限表(新增:data_scope=5时生效) |
### 1.5 用户模块权限矩阵
| 权限编码 | ADMIN | SUPERVISOR | MENTOR | STUDENT |
| :---------- | :---: | :--------: | :----: | :-----: |
| user:read | Y | - | - | - |
| user:create | Y | - | - | - |
| user:update | Y | - | - | - |
| user:delete | Y | - | - | - |
### 1.6 认证与安全约束
来源:
[
user-module-任务文档
]
sec4.1-4.4、
[
RBAC设计文档
]
sec8
| 约束 | 规范 |
| :----------- | :---------------------------------------------- |
| 密码加密 | bcrypt (cost = 12) |
| Token 时效 | access_token 2h + refresh_token 7d |
| Token 黑名单 | 登出后 refreshToken 加入 Redis 黑名单 |
| 登录锁定 | 连续5次失败锁定 10分钟 |
| 验证码 | 6位数字,5分钟有效,错误3次后失效 |
| 验证码防刷 | 60s内同一手机号限1次,单IP 1小时限10次 |
| 接口鉴权 | @PreAuthorize + JWT 过滤器 |
| 越权响应 | HTTP 403 + JSON 格式:code=1003, message=无权限 |
| 权限缓存 | Redis 缓存角色权限列表及用户菜单 |
| 审计留痕 | 登录日志记录到 user_login_log 表 |
### 1.7 RBAC 四级访问控制
来源:
[
user-module-任务文档
]
sec4.9、
[
RBAC设计文档
]
sec6
| 层级 | 实现位置 | 说明 |
| :----------- | :-------------------------------- | :--------------------------------------- |
| 第一级(菜单) | 前端路由守卫 + 动态菜单接口 | 按角色返回不同菜单树 |
| 第二级(按钮) | 前端按钮指令 | 按权限码控制按钮显示/隐藏 |
| 第三级(接口) | 后端 @PreAuthorize + hasAuthority | 从 JWT 解析角色,查权限,无权限返回403 |
| 第四级(数据) | 后端 @DataScope + MyBatis拦截器 | 资源级权限控制(本部门/仅本人/自定义等) |
---
## 二、功能清单
| 编号 | 子模块 | 功能名称 | 功能描述 | 权限 | 优先级 |
| :--- | :---------- | :------------------- | :------------------------------------------ | :------- | :----- |
| U-01 | 认证-登录 | 用户登录 | 账号密码登录,签发JWT双Token,记录登录日志 | 无需认证 | P0 |
| U-02 | 认证-登录 | 登录锁定 | 连续5次失败锁定10分钟 | 系统内置 | P0 |
| U-03 | 认证-登出 | 用户登出 | refreshToken加入Redis黑名单 | 已登录 | P1 |
| U-04 | 认证-Token | Token刷新 | refreshToken换取新accessToken | 已登录 | P0 |
| U-05 | 认证-验证码 | 发送短信验证码 | 6位数字验证码,Redis存5分钟,60s防刷+IP限流 | 无需认证 | P0 |
| U-06 | 认证-注册 | 用户注册 | 手机号+验证码+密码注册,默认STUDENT角色 | 无需认证 | P0 |
| U-07 | 认证-密码 | 找回密码 | 手机号+验证码验证后重置密码 | 无需认证 | P1 |
| U-08 | 用户管理 | 用户列表与搜索 | 分页列表,支持关键字/角色/部门/状态筛选 | ADMIN | P0 |
| U-09 | 用户管理 | 新增用户 | ADMIN创建用户 | ADMIN | P0 |
| U-10 | 用户管理 | 编辑用户 | ADMIN修改用户信息;改手机号需验证码 | ADMIN | P0 |
| U-11 | 用户管理 | 启用/禁用/删除 | ADMIN切换status或软删除(is_deleted) | ADMIN | P0 |
| U-12 | 用户管理 | 查看用户详情 | 查看用户详细信息,敏感字段脱敏 | ADMIN | P0 |
| U-13 | 用户管理 | 修改密码 | 用户自改(旧密码校验);不可与最近3次密码相同 | 本人 | P1 |
| U-14 | 用户管理 | 管理员重置密码 | ADMIN强制重置用户密码,清除Token | ADMIN | P1 |
| U-15 | 用户管理 | 批量导入用户 | Excel批量导入,异步处理,返回进度 | ADMIN | P1 |
| U-16 | 用户管理 | 手动解锁账号 | ADMIN手动解除账号登录锁定 | ADMIN | P1 |
| U-17 | 用户管理 | 获取当前用户信息 | 返回当前用户信息(含角色/权限),脱敏展示 | 已登录 | P0 |
| U-18 | 角色管理 | 角色列表与详情 | 查看角色列表(含用户数)和角色详情(含权限) | ADMIN | P0 |
| U-19 | 角色管理 | 创建角色 | 新增角色+绑定权限 | ADMIN | P0 |
| U-20 | 角色管理 | 编辑角色 | 修改角色信息/权限;预置角色不可修改 | ADMIN | P0 |
| U-21 | 角色管理 | 删除角色 | 删除角色;预置/有用户关联不可删 | ADMIN | P0 |
| U-22 | 用户-角色 | 用户多角色分配 | 通过user_user_role为用户分配/移除角色 | ADMIN | P1 |
| U-23 | 权限管理 | 权限列表/搜索 | 分页展示权限点,可按模块筛选 | ADMIN | P0 |
| U-24 | 权限管理 | 角色绑定权限 | 为角色勾选/取消权限,保存后即时生效 | ADMIN | P0 |
| U-25 | 部门管理 | 部门列表 | 展示部门列表 | ADMIN | P0 |
| U-26 | 部门管理 | 新增/编辑/删除 | 维护部门;编码唯一;删除需校验用户 | ADMIN | P0 |
| U-27 | RBAC基础 | 动态菜单接口 | 根据角色返回菜单树,Redis缓存1h | 已登录 | P1 |
| U-28 | RBAC基础 | 菜单管理(CRUD) | ADMIN维护菜单树(目录/菜单/按钮) | ADMIN | P1 |
| U-29 | RBAC基础 | 角色分配菜单 | 为角色勾选/取消菜单权限 | ADMIN | P1 |
| U-30 | RBAC基础 | 按钮级权限指令 | 根据权限码控制按钮可见性 | 已登录 | P1 |
| U-31 | RBAC基础 | 后端接口权限校验 | @PreAuthorize,白名单除外全部强制登录 | 已登录 | P0 |
| U-32 | RBAC基础 | 权限缓存(Redis) | Redis缓存,权限变更时清除缓存 | 系统内置 | P0 |
| U-33 | RBAC基础 | 种子数据初始化 | 初始化4种角色+权限矩阵+默认管理员 | 系统内置 | P0 |
| U-34 | RBAC基础 | 资源级权限(数据权限) | 基于@DataScope控制数据可见范围 | 系统内置 | P1 |
| U-35 | 安全 | IP限流 | 单IP 1小时接口调用次数限制 | 系统内置 | P1 |
| U-36 | 安全 | 登录日志查询 | 查询user_login_log表记录 | ADMIN | P1 |
| U-37 | 安全 | 数据脱敏 | 手机号138
****
8000,邮箱部分脱敏,密码不返回 | 系统内置 | P1 |
| U-38 | 框架 | 统一响应格式 | 所有接口返回 {code, message, data, traceId} | 系统内置 | P0 |
| U-39 | 框架 | 分页响应格式 | 分页接口返回 {total, page, size, items} | 系统内置 | P0 |
---
## 三、功能清单 + 验收标准
### U-01 用户登录
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-01 | |
| 前置条件 | 用户已存在且status=1, 未锁定 | |
| 验收标准 | 1. 正确账号密码返回 accessToken(2h)+refreshToken(7d)
<br>
2. 错误密码返回 HTTP 401 + JSON(code=1002)
<br>
3. 不存在的账号返回 HTTP 401(不暴露具体原因)
<br>
4. 禁用/已删除用户返回 HTTP 403 + JSON(code=2002)
<br>
5. 登录成功清除错误计数
<br>
6. 记录登录日志到user_login_log(含IP/设备/状态)
<br>
7. 被锁定账号无法登录,返回 HTTP 423 + JSON(code=2010) | task-doc sec3.2.1 |
### U-02 登录锁定
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :-------------- |
| 功能编号 | U-02 | |
| 前置条件 | Redis可用 | |
| 验收标准 | 1. 连续5次密码错误触发锁定
<br>
2.
**锁定持续10分钟**
<br>
3. 锁定期间即使用正确密码也登录失败,返回剩余锁定时间
<br>
4. 成功登录后清除失败计数
<br>
5. Redis key=login:fail:{phone}/login:locked:{phone} | task-doc sec5.4 |
### U-03 用户登出
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-03 |
| 前置条件 | 用户已登录 |
| 验收标准 | 1. refreshToken加入Redis黑名单
<br>
2. 黑名单TTL=accessToken剩余时间
<br>
3. 该refreshToken不可再刷新Token |
### U-04 Token刷新
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-04 |
| 前置条件 | refreshToken未过期(7天内)且不在黑名单 |
| 验收标准 | 1. 返回新accessToken(重置2h)
<br>
2. 过期(超7天)或黑名单中的refreshToken返回 HTTP 401
<br>
3. 前端需实现请求拦截器,当 access_token 过期返回 401 时,自动使用 refresh_token 静默换取新 Token 并重试原请求,不中断用户操作 |
### U-05 发送短信验证码
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-05 | |
| 前置条件 | 传入符合格式的手机号 | |
| 验收标准 | 1. 生成6位数字验证码
<br>
2. Redis存储 phone:type -> code, TTL=5min
<br>
3. 入参校验:若手机号格式错误(非11位/非1开头),返回 HTTP 400 + code=1001
<br>
4. 60s内同一手机号重复请求返回 HTTP 429 + code=1005
<br>
5. 单IP 1小时最多10次,超出返回 HTTP 429 + code=1005
<br>
6.
**验证码错误3次后自动失效**
<br>
7. type可选值: login/register/reset | task-doc sec3.2.5 |
### U-06 用户注册
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-06 | |
| 前置条件 | 手机号+验证码已验证 | |
| 验收标准 | 1. 手机号格式: 11位数字, 1开头
<br>
2. 密码强度: 至少8位, 大小写字母+数字
<br>
3. 验证码错误返回 HTTP 400 + code=2003;验证码过期返回 HTTP 400 + code=2003
<br>
4. 已注册手机号返回
**HTTP 409**
+ code=2002
<br>
5. 新用户默认角色为STUDENT,创建成功返回
**HTTP 201**
<br>
6. 密码bcrypt加密存储 | task-doc sec3.2.3 |
### U-07 找回密码
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-07 | |
| 前置条件 | 手机号已注册 | |
| 验收标准 | 1. 验证码正确且未过期
<br>
2. 验证码使用后立即失效(一次性),已使用返回 HTTP 400 + code=2003
<br>
3. 新密码强度校验,加密存储
<br>
4. 手机号未注册返回 HTTP 404 + code=2001 | task-doc sec3.2.6 |
### U-08 用户列表与搜索
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-08 |
| 前置条件 | 当前用户拥有 user:read |
| 验收标准 | 1. 支持分页(page/size),默认按 created_at DESC 排序
<br>
2. 关键字搜索: 姓名/用户名/手机号模糊匹配
<br>
3. 角色筛选 / 部门筛选 / 状态筛选
<br>
4. 列表中手机号/邮箱脱敏展示
<br>
5. 非ADMIN访问返回 HTTP 403 |
### U-09 新增用户
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-09 |
| 前置条件 | 当前用户拥有 user:create |
| 验收标准 | 1. 必填: 用户名/真实姓名/密码/角色
<br>
2. 用户名/手机号全局唯一,重复返回
**HTTP 409**
+ code=2002
<br>
3. 密码bcrypt加密,创建成功返回
**HTTP 201**
<br>
4. status默认1(启用) |
### U-10 编辑用户
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-10 |
| 前置条件 | 当前用户拥有 user:update |
| 验收标准 | 1. 可修改: 真实姓名/邮箱/手机号/角色/部门
<br>
2. 用户名不可修改
<br>
3. 修改手机号需短信验证码确认,且新手机号唯一性校验(冲突返回 409)
<br>
4. 更新后同步刷新 Redis 缓存 |
### U-11 启用/禁用/删除用户
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-11 |
| 前置条件 | 当前用户拥有 user:delete |
| 验收标准 | 1. 禁用(status=0)后用户无法登录
<br>
2. 删除为软删除(is_deleted=1),删除成功返回
**HTTP 204**
(无响应体)
<br>
3. 不能删除自己,不能删除ADMIN角色用户
<br>
4. 存在未结业务(如进行中实训)返回 HTTP 409 + code=2007 |
### U-12 查看用户详情
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-12 |
| 前置条件 | 当前用户拥有 user:read |
| 验收标准 | 1. 返回用户完整信息(含角色)
<br>
2. 手机号脱敏: 138
****
8000
<br>
3. 密码字段不返回
<br>
4. 用户不存在返回 HTTP 404 |
### U-13 修改密码 (用户自改)
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-13 | |
| 前置条件 | 用户已登录(本人) | |
| 验收标准 | 1. 用户自改需校验旧密码,错误返回 HTTP 400 + code=2004
<br>
2. 新密码强度校验
<br>
3. 不可与最近3次密码相同(查user_password_history),重复返回 HTTP 400 + code=2005
<br>
4. 修改后Token刷新(需重新登录) | task-doc sec3.3.4 |
### U-14 管理员重置密码 (新增)
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-14 | |
| 前置条件 | 当前用户为 ADMIN | |
| 验收标准 | 1. 无需校验旧密码
<br>
2. 新密码强度校验,加密存储
<br>
3. 重置成功后,
**清除该用户所有Token(加入黑名单)**
,强制其重新登录 | task-doc sec3.3.8 |
### U-15 批量导入用户 (新增)
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-15 | |
| 前置条件 | 当前用户为 ADMIN,上传 Excel 文件 | |
| 验收标准 | 1. 文件大小≤5MB,行数≤1000行
<br>
2. 逐行校验,单行失败不影响整体导入(跳过并记录原因)
<br>
3. 默认密码策略:未填写则使用手机号后6位
<br>
4.
**异步处理**
:提交后返回 taskId,前端通过
`GET /batch-import/{taskId}`
轮询进度 | task-doc sec3.3.9 |
### U-16 手动解锁账号 (新增)
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :--------------- |
| 功能编号 | U-16 | |
| 前置条件 | 当前用户为 ADMIN | |
| 验收标准 | 1. 清除 Redis 中的
`login:fail:{phone}`
和
`login:locked:{phone}`
<br>
2. 记录解锁日志(操作人、解锁时间) | task-doc sec4.13 |
### U-17 获取当前用户信息
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-17 | |
| 前置条件 | 用户已登录 | |
| 验收标准 | 1. 返回用户完整信息(含角色/权限列表)
<br>
2. 包含最后登录时间
<br>
3. 手机号脱敏展示,密码字段不返回 | task-doc sec3.3.1 |
### U-18/U-19/U-20/U-21 角色管理
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-18 ~ U-21 |
| 前置条件 | 当前用户拥有对应权限 |
| 验收标准 | 1. 角色列表含用户数统计和isPreset标记
<br>
2. 角色名称/编码唯一,冲突返回 HTTP 409 + code=2008
<br>
3. 创建/更新角色可同时绑定权限
<br>
4. 预置角色不可修改和删除(返回 403)
<br>
5. 删除角色需检查: 无用户关联才可删除(否则返回 409 + code=2009)
<br>
6. 删除成功返回 HTTP 204 |
### U-22 用户多角色分配
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :--------------- |
| 功能编号 | U-22 | |
| 前置条件 | 当前用户拥有 user:update | |
| 验收标准 | 1. 通过user_user_role表
**替换式分配**
(先删后插)
<br>
2. 分配后清除该用户菜单缓存和权限缓存
<br>
3. 分配后该用户Token立即失效(强制重新登录) | task-doc sec4.11 |
### U-23/U-24 权限管理
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-23 ~ U-24 |
| 前置条件 | 当前用户拥有对应权限 |
| 验收标准 | 1. 权限码格式: 模块:操作 (如 project:read)
<br>
2. 绑定权限后即时生效
<br>
3. 权限变更后清除Redis缓存 |
### U-25/U-26 部门管理
| 项目 | 内容 |
| :------- | :------------------------------------------------------- |
| 功能编号 | U-25 ~ U-26 |
| 前置条件 | 当前用户拥有对应权限 |
| 验收标准 | 1. 编码唯一(如 tech/annotation)
<br>
2. 删除前检查用户关联 |
### U-27 动态菜单接口
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-27 | |
| 前置条件 | 用户已登录 | |
| 验收标准 | 1. 不同角色返回不同菜单树
<br>
2. 返回结构: id/name/path/icon/children
<br>
3. Redis缓存 key=menu:{userId}, TTL=1h
<br>
4. 角色权限变更时缓存失效 | task-doc sec3.5.1 |
### U-28 菜单管理(CRUD) (新增)
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------------- |
| 功能编号 | U-28 | |
| 前置条件 | 当前用户为 ADMIN | |
| 验收标准 | 1. 支持创建目录(type=1)、菜单(type=2)、按钮(type=3)
<br>
2. 同级菜单 name 唯一,冲突返回 HTTP 409 + code=2011
<br>
3. 存在子菜单时不允许删除(返回 409 + code=2012)
<br>
4. 不允许修改 name(前端路由名),不允许形成循环引用
<br>
5. 修改/删除后刷新全量用户菜单缓存 | task-doc sec3.5.4-3.5.6 |
### U-29 角色分配菜单 (新增)
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :---------------- |
| 功能编号 | U-29 | |
| 前置条件 | 当前用户为 ADMIN | |
| 验收标准 | 1.
**替换式更新**
(先删后插 user_role_menu)
<br>
2. 校验 menuIds 全部存在
<br>
3. 修改后刷新该角色下所有用户的菜单缓存和权限缓存 | task-doc sec3.5.7 |
### U-30 按钮级权限指令
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-30 |
| 前置条件 | 用户已登录, 前端已获取权限列表 |
| 验收标准 | 1. 有权限的用户看到操作按钮
<br>
2. 无权限的用户按钮隐藏, 不报错 |
### U-31 后端接口权限校验
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :-------------- |
| 功能编号 | U-31 | |
| 前置条件 | 请求携带有效JWT | |
| 验收标准 | 1. 有权限返回200
<br>
2. 无权限返回 HTTP 403 + JSON(code=1003)
<br>
3. JWT伪造/过期返回 HTTP 401 + JSON(code=1002)
<br>
4. 白名单(/api/v1/auth/
**
)除外全部强制登录 | task-doc sec4.9 |
### U-32 权限缓存(Redis)
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-32 |
| 前置条件 | Redis服务可用 |
| 验收标准 | 1. 首次从DB加载写入Redis
<br>
2. 后续从Redis读取
<br>
3. 角色权限变更后清除Redis缓存
<br>
4. Redis不可用时降级为DB查询 |
### U-33 种子数据初始化
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-33 |
| 前置条件 | 数据库表结构创建完成 |
| 验收标准 | 1. user_role表预置4条: ADMIN/SUPERVISOR/MENTOR/STUDENT
<br>
2. user_permission表预置完整权限矩阵
<br>
3. 预置一个默认ADMIN账号
<br>
4. 幂等, 可重复执行 |
### U-34 资源级权限(数据权限) (新增)
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :--------------- |
| 功能编号 | U-34 | |
| 前置条件 | 系统内置,基于 @DataScope 注解 | |
| 验收标准 | 1. 根据 user_role.data_scope 自动注入 SQL 过滤条件
<br>
2. 范围:1=全部, 2=本部门, 3=本部门及下级, 4=仅本人, 5=自定义
<br>
3. ADMIN 默认 data_scope = 1
<br>
4. 拦截器实现 MyBatis SQL 拼接,禁止字符串拼接防注入 | task-doc sec4.10 |
### U-35 IP限流
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :-------------- |
| 功能编号 | U-35 | |
| 前置条件 | 系统内置 | |
| 验收标准 | 1. 单IP 1小时超过阈值(如10次)临时限制
<br>
2. 超出限制返回
**HTTP 429**
+ JSON(code=1005) | task-doc sec4.3 |
### U-36 登录日志查询
| 项目 | 内容 | 来源 |
| :------- | :------------------------------------------------------- | :---------------- |
| 功能编号 | U-36 | |
| 前置条件 | ADMIN登录 | |
| 验收标准 | 1. 查询user_login_log表
<br>
2. 支持按时间范围/用户/IP筛选 | task-doc sec2.2.7 |
### U-37 数据脱敏
| 项目 | 内容 | 来源 |
| :------- | :----------------------------------------------------------- | :-------------- |
| 功能编号 | U-37 | |
| 前置条件 | 系统内置 | |
| 验收标准 | 1. 手机号显示 138
****
8000 (中间4位隐藏)
<br>
2. 邮箱 @前3位字符后隐藏
<br>
3. 密码字段永不返回 | task-doc sec4.5 |
### U-38 统一响应格式与异常处理
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-38 |
| 前置条件 | 系统内置 |
| 验收标准 | 1. 所有接口返回统一 JSON:
`{"code": 业务码, "message": "提示", "data": {}, "traceId": "xxx", "timestamp": 123}`
<br>
2. 成功时
`code`
为
`0`
(或0000),HTTP 状态码遵循 RESTful 规范
<br>
3. 全局异常拦截:参数校验(400)、认证异常(401)、权限异常(403)、业务异常(按场景映射409/423/429)、未知异常(500+traceId) |
### U-39 分页响应格式
| 项目 | 内容 |
| :------- | :----------------------------------------------------------- |
| 功能编号 | U-39 |
| 前置条件 | 系统内置 |
| 验收标准 | 分页接口返回
`{"code": 0, "data": {"total": 100, "page": 1, "size": 10, "pages": 10, "items": []}}`
|
---
## 四、测试用例
### 4.1 认证模块(U-01 ~ U-07)
| 编号 | 所属功能 | 测试场景 | 前置条件 | 预期结果 | 类型 |
| :-------- | :----------- | :--------------------- | :---------------- | :------------------------------------- | :--- |
| TC-U01-01 | U-01登录 | 正常登录 | 用户已启用 | 返回 HTTP 200, 签发JWT | 正向 |
| TC-U01-02 | U-01登录 | 密码错误 | 用户已启用 | 返回 HTTP 401, code=1002 | 异常 |
| TC-U01-03 | U-01登录 | 账号不存在 | - | 返回 HTTP 401, 不暴露原因 | 异常 |
| TC-U01-04 | U-01登录 | 禁用用户登录 | status=0 | 返回 HTTP 403, code=2002 | 异常 |
| TC-U01-05 | U-01登录 | 登录日志记录 | 登录成功 | user_login_log写入记录 | 正向 |
| TC-U02-01 | U-02锁定 | 连续5次失败 | 用户已启用 | 触发锁定
**10分钟**
| 异常 |
| TC-U02-02 | U-02锁定 | 锁定后正确密码 | 已锁定 | 返回 HTTP 423, code=2010, 提示剩余时间 | 异常 |
| TC-U02-03 | U-02锁定 | 成功登录后解锁 | 已锁定+成功登录 | 错误计数清零 | 正向 |
| TC-U03-01 | U-03登出 | 正常登出 | 已登录 | 返回 HTTP 200, Token入黑名单 | 正向 |
| TC-U03-02 | U-03登出 | 登出后用原Token | 已登出 | 返回 HTTP 401 | 异常 |
| TC-U04-01 | U-04刷新 | 正常刷新 | refreshToken有效 | 新accessToken | 正向 |
| TC-U04-02 | U-04刷新 | refreshToken过期 | 超7天 | 返回 HTTP 401 | 异常 |
| TC-U04-03 | U-04刷新 | 黑名单中的refreshToken | 已登出 | 返回 HTTP 401 | 异常 |
| TC-U05-01 | U-05验证码 | 正常发送 | 手机号有效 | 返回 HTTP 200, Redis写入验证码 | 正向 |
| TC-U05-02 | U-05验证码 | 60s内重复请求 | 同一手机号 | 返回 HTTP 429, code=1005 | 异常 |
| TC-U05-03 | U-05验证码 | IP超限 | 单IP超过10次/小时 | 返回 HTTP 429, code=1005 | 异常 |
| TC-U05-04 | U-05验证码 | 验证码过期 | 超过5分钟 | 返回 HTTP 400, code=2003 | 异常 |
| TC-U05-05 | U-05验证码 | 验证码一次性 | 已使用 | 验证码失效 | 正向 |
| TC-U05-06 | U-05验证码 |
**验证码错误3次**
| 连续输入错误 | 第3次错误后验证码自动失效 | 异常 |
| TC-U05-07 | U-05验证码 | 手机号格式错误 | 输入非11位号码 | 返回 HTTP 400, code=1001 | 异常 |
| TC-U06-01 | U-06注册 | 正常注册 | 验证码正确 | 返回
**HTTP 201**
, 默认STUDENT | 正向 |
| TC-U06-02 | U-06注册 | 手机号已注册 | 手机号存在 | 返回
**HTTP 409**
, code=2002 | 异常 |
| TC-U06-03 | U-06注册 | 密码长度不足 | 输入7位密码 | 校验拦截,提示至少8位 | 边界 |
| TC-U06-04 | U-06注册 | 验证码错误 | 错误验证码 | 返回 HTTP 400, code=2003 | 异常 |
| TC-U06-05 | U-06注册 | 手机号格式错误 | 输入非11位号码 | 返回 HTTP 400, code=1001 | 异常 |
| TC-U06-06 | U-06注册 | 密码强度不足 | 仅含数字 | 校验拦截 | 异常 |
| TC-U07-01 | U-07找回密码 | 正常找回 | 验证码正确 | 密码重置成功 | 正向 |
| TC-U07-02 | U-07找回密码 | 验证码已使用 | 一次性使用 | 返回 HTTP 400, code=2003 | 异常 |
### 4.2 用户管理(U-08 ~ U-17)
| 编号 | 所属功能 | 测试场景 | 前置条件 | 预期结果 | 类型 |
| :-------- | :----------- | :-------------------- | :---------------- | :---------------------------- | :--- |
| TC-U08-01 | U-08列表 | 分页查看 | ADMIN登录 | 分页展示用户 | 正向 |
| TC-U08-02 | U-08列表 | 关键字搜索 | ADMIN登录 | 模糊匹配 | 正向 |
| TC-U08-03 | U-08列表 | 角色/部门/状态筛选 | ADMIN登录 | 筛选结果 | 正向 |
| TC-U08-04 | U-08列表 | 非ADMIN访问 | 非ADMIN | 返回 HTTP 403 | 异常 |
| TC-U08-05 | U-08列表 | 分页参数边界值 | ADMIN登录,page=0 | 后端兜底处理,不报错 | 边界 |
| TC-U09-01 | U-09新增 | 正常新增 | ADMIN登录 | 返回
**HTTP 201**
| 正向 |
| TC-U09-02 | U-09新增 | 用户名重复 | ADMIN登录 | 返回
**HTTP 409**
, code=2002 | 异常 |
| TC-U09-03 | U-09新增 | 密码bcrypt加密 | ADMIN登录 | 存储为密文 | 安全 |
| TC-U10-01 | U-10编辑 | 正常编辑 | ADMIN登录 | 更新成功 | 正向 |
| TC-U10-02 | U-10编辑 | 用户名不可修改 | ADMIN登录 | 只读 | 边界 |
| TC-U10-03 | U-10编辑 | 改手机号需验证码 | ADMIN登录 | 无验证码则失败 | 异常 |
| TC-U10-04 | U-10编辑 | 邮箱格式错误 | 输入非法邮箱 | 返回 HTTP 400, code=1001 | 异常 |
| TC-U11-01 | U-11禁用/删 | 禁用用户 | ADMIN登录 | status=0 | 正向 |
| TC-U11-02 | U-11禁用/删 | 正常软删除 | ADMIN登录 | 返回
**HTTP 204**
(无响应体) | 正向 |
| TC-U11-03 | U-11禁用/删 | 删除有未结业务用户 | ADMIN登录 | 返回
**HTTP 409**
, code=2007 | 异常 |
| TC-U11-04 | U-11禁用/删 | ADMIN删自身 | ADMIN登录 | 禁止操作 | 异常 |
| TC-U12-01 | U-12详情 | 查看用户详情 | ADMIN登录 | 返回完整信息 | 正向 |
| TC-U12-02 | U-12详情 | 手机号脱敏 | ADMIN登录 | 138
****
8000 | 正向 |
| TC-U13-01 | U-13改密 | 正常修改 | 本人登录 | 成功, Token刷新 | 正向 |
| TC-U13-02 | U-13改密 | 旧密码错误 | 本人登录 | 返回 HTTP 400, code=2004 | 异常 |
| TC-U13-03 | U-13改密 | 与最近3次密码相同 | 本人登录 | 返回 HTTP 400, code=2005 | 异常 |
| TC-U14-01 | U-14重置 | ADMIN重置密码 | ADMIN登录 | 成功,且原用户Token失效 | 正向 |
| TC-U15-01 | U-15导入 | 导入含重复手机号Excel | ADMIN登录 | 跳过重复行,返回成功/失败明细 | 正向 |
| TC-U15-02 | U-15导入 | 导入超大文件 | 文件>5MB | 返回 HTTP 400, code=1001 | 异常 |
| TC-U16-01 | U-16解锁 | 手动解锁锁定账号 | ADMIN登录 | 清除Redis锁定标记,用户可登录 | 正向 |
| TC-U17-01 | U-17当前用户 | 获取当前用户 | 已登录 | 返回含角色/权限 | 正向 |
| TC-U17-02 | U-17当前用户 | 数据脱敏 | 已登录 | 手机号138
****
8000 | 正向 |
### 4.3 角色、菜单与权限(U-18 ~ U-34)
| 编号 | 所属功能 | 测试场景 | 前置条件 | 预期结果 | 类型 |
| :-------- | :----------- | :----------------- | :--------------- | :--------------------------------- | :--- |
| TC-U18-01 | U-18角色列表 | 查看角色列表 | ADMIN登录 | 4条预置+用户数+isPreset | 正向 |
| TC-U18-02 | U-18角色列表 | 查看角色详情+权限 | ADMIN登录 | 含权限列表 | 正向 |
| TC-U19-01 | U-19创建角色 | 正常创建 | ADMIN登录 | 返回
**HTTP 201**
| 正向 |
| TC-U19-02 | U-19创建角色 | 名称重复 | ADMIN登录 | 返回
**HTTP 409**
, code=2008 | 异常 |
| TC-U20-01 | U-20编辑角色 | 正常编辑 | ADMIN登录 | 更新成功 | 正向 |
| TC-U20-02 | U-20编辑角色 | 预置角色不可编辑 | ADMIN登录 | 阻止操作 | 异常 |
| TC-U21-01 | U-21删除角色 | 删除无用户角色 | ADMIN登录 | 返回
**HTTP 204**
| 正向 |
| TC-U21-02 | U-21删除角色 | 删除有用户角色 | ADMIN登录 | 返回
**HTTP 409**
, code=2009 | 异常 |
| TC-U21-03 | U-21删除角色 | 删除预置角色 | ADMIN登录 | 提示系统角色不可删除 | 异常 |
| TC-U22-01 | U-22多角色 | 为用户分配多角色 | ADMIN登录 | user_user_role新增 | 正向 |
| TC-U22-02 | U-22多角色 | 权限取并集 | 用户拥有多角色 | 拥有所有角色权限 | 正向 |
| TC-U23-01 | U-23权限列表 | 查看权限列表 | ADMIN登录 | 展示所有权限点 | 正向 |
| TC-U23-02 | U-23权限列表 | 按模块筛选 | ADMIN登录 | 筛选结果 | 正向 |
| TC-U24-01 | U-24绑定权限 | 绑定权限 | ADMIN登录 | 绑定成功, 即时生效 | 正向 |
| TC-U24-02 | U-24绑定权限 | 权限变更实时生效 | 在线用户权限被改 | 即返回403 | 安全 |
| TC-U25-01 | U-25部门列表 | 查看部门列表 | ADMIN登录 | 展示列表 | 正向 |
| TC-U25-02 | U-25部门列表 | 编码唯一性 | 输入已存在编码 | 返回 HTTP 409 | 异常 |
| TC-U26-01 | U-26部门CRUD | 正常新增/编辑 | ADMIN登录 | 成功 | 正向 |
| TC-U26-02 | U-26部门CRUD | 删除有用户部门 | ADMIN登录 | 阻止删除 | 异常 |
| TC-U27-01 | U-27动态菜单 | ADMIN菜单 | ADMIN登录 | 全部菜单 | 正向 |
| TC-U27-02 | U-27动态菜单 | STUDENT菜单 | STUDENT登录 | 仅实训相关 | 正向 |
| TC-U27-03 | U-27动态菜单 | 菜单缓存 | 已登录 | Redis缓存, 权限变更清除 | 正向 |
| TC-U28-01 | U-28菜单管理 | 创建目录/菜单/按钮 | ADMIN登录 | 返回 HTTP 201 | 正向 |
| TC-U28-02 | U-28菜单管理 | 同级菜单name重复 | ADMIN登录 | 返回
**HTTP 409**
, code=2011 | 异常 |
| TC-U28-03 | U-28菜单管理 | 删除有子菜单的目录 | ADMIN登录 | 返回
**HTTP 409**
, code=2012 | 异常 |
| TC-U29-01 | U-29分配菜单 | 角色分配菜单 | ADMIN登录 | 替换式更新,刷新用户缓存 | 正向 |
| TC-U29-02 | U-29分配菜单 | 传入不存在的menuId | ADMIN登录 | 返回 HTTP 404 | 异常 |
| TC-U30-01 | U-30按钮权限 | 有权限可见 | 有权限登录 | 按钮显示 | 正向 |
| TC-U30-02 | U-30按钮权限 | 无权限隐藏 | 无权限登录 | 按钮隐藏 | 正向 |
| TC-U31-01 | U-31接口校验 | 有权限 | 有权限登录 | 200 | 正向 |
| TC-U31-02 | U-31接口校验 | 无权限 | 无权限登录 | 403 | 异常 |
| TC-U31-03 | U-31接口校验 | JWT伪造 | - | 401 | 安全 |
| TC-U31-04 | U-31接口校验 | JWT过期 | Token超2h | 401 | 异常 |
| TC-U32-01 | U-32缓存 | Redis命中 | 已缓存 | 不走DB | 正向 |
| TC-U32-02 | U-32缓存 | 权限变更后清除 | 权限变更 | 缓存清除 | 正向 |
| TC-U32-03 | U-32缓存 | Redis降级 | Redis不可用 | 降级DB查询 | 异常 |
| TC-U33-01 | U-33种子数据 | 首次初始化 | 首次部署 | 4角色+全部权限+管理员 | 正向 |
| TC-U33-02 | U-33种子数据 | 幂等 | 已有数据 | 不重复 | 正向 |
| TC-U34-01 | U-34数据权限 | 普通学员查列表 | data_scope=4 | SQL自动注入
`AND u.id = #{userId}`
| 安全 |
### 4.4 安全与框架(U-35 ~ U-39)
| 编号 | 所属功能 | 测试场景 | 前置条件 | 预期结果 | 类型 |
| :-------- | :----------- | :--------- | :----------- | :---------------------------- | :--- |
| TC-U35-01 | U-35 IP限流 | IP超限 | 单IP超过阈值 | 返回
**HTTP 429**
, code=1005 | 异常 |
| TC-U36-01 | U-36登录日志 | 查询日志 | ADMIN登录 | 展示登录记录 | 正向 |
| TC-U36-02 | U-36登录日志 | 按条件筛选 | ADMIN登录 | 时间/IP筛选 | 正向 |
| TC-U37-01 | U-37脱敏 | 手机号脱敏 | 已登录 | 138
****
8000格式 | 正向 |
| TC-U37-02 | U-37脱敏 | 密码不返回 | 已登录 | 无password字段 | 正向 |
| TC-U38-01 | U-38统一响应 | 正常请求 | - | 包含code/message/data/traceId | 正向 |
| TC-U38-02 | U-38统一响应 | 未知异常 | 触发500 | 不暴露堆栈,返回traceId | 安全 |
| TC-U39-01 | U-39分页响应 | 分页查询 | - | 包含total/page/size/items | 正向 |
**测试用例统计**
:正向 52 个、异常 40 个、边界 3 个、安全 5 个,合计 100 个。
---
## 五、附录:完整API清单与状态码规范
### 5.1 业务状态码(code)与 HTTP 状态码映射规范
为了便于排查问题和前端统一处理,严格遵循 RESTful 规范与任务文档要求:
| 业务状态码 (code) | HTTP 状态码 | 含义说明 | 对应场景 |
| :---------------- | :---------------------------- | :------------------ | :------------------------------- |
|
**0 / 0000**
|
**200 OK**
| 请求成功 | GET / PUT / POST(无返回体) |
|
**0 / 0000**
|
**201 Created**
| 资源创建成功 | POST 创建类 (注册/新增用户/菜单) |
|
**-**
|
**204 No Content**
| 无返回内容 | DELETE 删除成功 |
|
**1001**
|
**400 Bad Request**
| 参数校验失败 | 格式错误/必填项缺失 |
|
**1002**
|
**401 Unauthorized**
| 未登录 / Token 失效 | Token过期/非法/未登录 |
|
**1003**
|
**403 Forbidden**
| 无权限访问 | @PreAuthorize 拒绝/预置角色操作 |
|
**1004**
|
**404 Not Found**
| 资源不存在 | 用户/角色/菜单不存在 |
|
**1005**
|
**429 Too Many Requests**
| 请求过于频繁 | IP限流/短信频控 |
|
**2002**
|
**409 Conflict**
| 资源冲突 | 用户名/手机号/角色名已存在 |
|
**2007**
|
**409 Conflict**
| 存在未结业务 | 用户存在进行中实训无法删除 |
|
**2009**
|
**409 Conflict**
| 存在关联数据 | 角色下存在用户无法删除 |
|
**2010**
|
**423 Locked**
| 账号被锁定 | 登录失败超过上限 |
|
**2011**
|
**409 Conflict**
| 菜单名称已存在 | 同级菜单 name 重复 |
|
**2012**
|
**409 Conflict**
| 存在子菜单 | 菜单目录下有子节点无法删除 |
|
**9999**
|
**500 Internal Server Error**
| 服务器内部错误 | 未知异常 |
### 5.2 完整 API 清单
| 方法 | 路径 | 功能 | 权限 | 优先级 |
| :----- | :---------------------------------- | :------------- | :------------ | :----- |
| POST | /api/v1/auth/login | 登录 | 无需认证 | P0 |
| POST | /api/v1/auth/logout | 登出 | 已登录 | P1 |
| POST | /api/v1/auth/refresh | 刷新Token | refresh_token | P0 |
| POST | /api/v1/auth/register | 注册 | 无需认证 | P0 |
| POST | /api/v1/auth/sms-code | 发送验证码 | 无需认证 | P0 |
| POST | /api/v1/auth/reset-password | 找回密码 | 无需认证 | P1 |
| GET | /api/v1/users | 用户列表 | user:read | P0 |
| GET | /api/v1/users/me | 获取当前用户 | 已登录 | P0 |
| GET | /api/v1/users/{id} | 用户详情 | user:read | P0 |
| POST | /api/v1/users | 新增用户 | user:create | P0 |
| PUT | /api/v1/users/{id} | 编辑用户 | user:update | P0 |
| DELETE | /api/v1/users/{id} | 软删除用户 | user:delete | P0 |
| PATCH | /api/v1/users/{id}/status | 启用/禁用 | user:delete | P0 |
| PUT | /api/v1/users/{id}/password | 修改密码(自改) | 本人 | P1 |
| PUT | /api/v1/users/{id}/password/reset | 管理员重置密码 | ADMIN | P1 |
| POST | /api/v1/users/batch-import | 批量导入用户 | ADMIN | P1 |
| GET | /api/v1/users/batch-import/{taskId} | 查询导入进度 | ADMIN | P2 |
| PUT | /api/v1/users/{id}/roles | 用户多角色分配 | user:update | P1 |
| PUT | /api/v1/users/{id}/unlock | 手动解锁账号 | ADMIN | P1 |
| GET | /api/v1/roles | 角色列表 | user:read | P0 |
| GET | /api/v1/roles/{id} | 角色详情+权限 | user:read | P0 |
| POST | /api/v1/roles | 创建角色 | user:create | P0 |
| PUT | /api/v1/roles/{id} | 编辑角色 | user:update | P0 |
| DELETE | /api/v1/roles/{id} | 删除角色 | user:delete | P0 |
| PUT | /api/v1/roles/{roleId}/menus | 角色分配菜单 | ADMIN | P1 |
| GET | /api/v1/permissions | 权限列表 | user:read | P0 |
| PUT | /api/v1/roles/{id}/permissions | 角色绑定权限 | user:update | P0 |
| GET | /api/v1/menus | 动态菜单(用户) | 已登录 | P1 |
| GET | /api/v1/menus/tree | 获取完整菜单树 | ADMIN | P1 |
| GET | /api/v1/menus/{id} | 菜单详情 | ADMIN | P1 |
| POST | /api/v1/menus | 创建菜单 | ADMIN | P1 |
| PUT | /api/v1/menus/{id} | 更新菜单 | ADMIN | P1 |
| DELETE | /api/v1/menus/{id} | 删除菜单 | ADMIN | P1 |
| GET | /api/v1/departments | 部门列表 | user:read | P0 |
| POST | /api/v1/departments | 新增部门 | user:create | P0 |
| PUT | /api/v1/departments/{id} | 编辑部门 | user:update | P0 |
| DELETE | /api/v1/departments/{id} | 删除部门 | user:delete | P0 |
| GET | /api/v1/login-logs | 登录日志查询 | ADMIN | P1 |
\ No newline at end of file
平台文档/角色与权限模型( RBAC)设计文档.md
0 → 100644
浏览文件 @
299ccb35
# 角色与权限模型 (RBAC) 设计文档 V2.1
基于《user-module-任务文档》《project-module-任务文档》《training-module-任务文档》中的角色权限定义综合整理
版本:V2.1 | 日期:2026-07-16 | 状态:已对齐任务文档 V2
## 1. 设计依据
### 1.1 角色定义
系统定义 4 种角色,覆盖用户管理、项目管理、实训管理三大模块。
| 角色 | 编码 | 说明 |
| :----- | :--------- | :------------------------------------------- |
| 管理员 | ADMIN | 全系统配置、项目管理、用户管理、实训全量查看 |
| 主管 | SUPERVISOR | 审核学员、难度校准、答辩审核、历史全量查看 |
| 导师 | MENTOR | 学员指导、答辩评审、查看分配给我的实训 |
| 学员 | STUDENT | 参与实训、提交产物、发起推荐 |
### 1.2 操作级别定义
| 操作级别 | 含义 |
| :------- | :------------------------- |
| 查看 | 只读,可浏览不可操作 |
| 操作 | 执行功能的核心操作 |
| 增删改查 | 完整 CRUD |
| 校准 | 对 AI 评分进行人工校准 |
| 审核 | 复核并给结论 / 批准驳回 |
| 管理 | 最高权限,含配置和全量管理 |
## 2. 权限编码规范
格式:
`{module}:{operation}`
| 模块 | 前缀 | 说明 |
| :------- | :--------- | :--------------------------- |
| 用户管理 | user | 用户管理、角色管理、权限分配 |
| 项目管理 | project | 项目库 CRUD、标签管理 |
| 实训管理 | training | 实训任务、预览、实操、答辩 |
| 答辩 | defense | 答辩申请、评审、审核 |
| 容器 | container | Docker 沙箱容器管理 |
| 难度 | difficulty | 难度评分卡配置、AI 评分校准 |
| 标签 | tag | 项目标签 CRUD |
| 推荐 | recommend | AI 项目推荐发起、查看 |
| 知识点 | knowledge | 知识点提取、查看、编辑 |
| 文件 | file | 项目资料上传、下载 |
| 历史记录 | history | 历史实训记录查看 |
| 进阶匹配 | advanced | 进阶项目匹配管理 |
| 能力画像 | profile | 学员能力画像查看 |
## 3. 用户模块表结构设计
### 3.1 user_user -- 用户表
| 字段 | 类型 | 约束 | 说明 |
| :------------ | :----------- | :------------------- | :-------------------------------- |
| id | BIGINT | PK | 用户主键 |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
| password | VARCHAR(255) | NOT NULL | bcrypt 加密密码 |
| real_name | VARCHAR(50) | NOT NULL | 真实姓名 |
| email | VARCHAR(100) | | 邮箱 |
| phone | VARCHAR(20) | | 手机号 |
| role_id | BIGINT | FK → roles | 角色(多角色通过 user_user_role) |
| department_id | BIGINT | FK → user_department | 所属部门 |
| avatar_url | VARCHAR(500) | | 头像 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
| is_deleted | TINYINT | DEFAULT 0 | 软删除标记:0=正常 1=已删除 |
| created_at | DATETIME | | 创建时间 |
| updated_at | DATETIME | | 更新时间 |
说明:role_id 字段保留用于单角色快速查询;多角色场景通过 user_user_role 关联表处理。
索引:(role_id),(department_id),(status),(phone)
### 3.2 user_roles -- 角色表
| 字段 | 类型 | 约束 | 说明 |
| :---------- | :----------- | :-------- | :----------------------------------------------------------- |
| id | BIGINT | PK | 主键 |
| role_name | VARCHAR(50) | NOT NULL | 角色名称 |
| role_code | VARCHAR(50) | UNIQUE | 角色编码,用于 Spring Security(如 ROLE_ADMIN) |
| description | VARCHAR(200) | | 角色描述 |
| is_preset | TINYINT | DEFAULT 0 | 是否预置角色:0=否 1=是 |
| data_scope | TINYINT | DEFAULT 4 | 数据权限范围:1=全部 2=本部门 3=本部门及下级 4=仅本人 5=自定义 |
| sort | INT | DEFAULT 0 | 排序号 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
| created_at | DATETIME | | 创建时间 |
| updated_at | DATETIME | | 更新时间 |
说明:data_scope 字段用于资源级权限控制,详见第 6 节。
预置角色:
| role_name | role_code | 说明 |
| :--------- | :-------------- | :--------------------------- |
| ADMIN | ROLE_ADMIN | 管理员:全系统配置、用户管理 |
| SUPERVISOR | ROLE_SUPERVISOR | 主管:审核学员、内容终审 |
| MENTOR | ROLE_MENTOR | 导师:答辩评审、学员指导 |
| STUDENT | ROLE_STUDENT | 学员:参与实训、提交产物 |
### 3.3 user_permissions -- 权限点表
| 字段 | 类型 | 约束 | 说明 |
| :-------------- | :----------- | :--------------- | :---------------------------------- |
| id | BIGINT | PK | 主键 |
| permission_code | VARCHAR(50) | NOT NULL, UNIQUE | 权限编码,格式 {module}:{operation} |
| permission_name | VARCHAR(100) | NOT NULL | 权限名称 |
| module | VARCHAR(50) | NOT NULL | 所属模块 |
| description | VARCHAR(200) | | 权限说明 |
| created_at | DATETIME | | 创建时间 |
### 3.4 user_role_permissions -- 角色权限关联表
| 字段 | 类型 | 约束 | 说明 |
| :------------ | :------- | :-------------------- | :------- |
| id | BIGINT | PK | 主键 |
| role_id | BIGINT | FK -> roles(id) | 角色 |
| permission_id | BIGINT | FK -> permissions(id) | 权限 |
| created_at | DATETIME | | 创建时间 |
唯一索引: (role_id, permission_id)
### 3.5 user_user_role -- 用户角色关联表
| 字段 | 类型 | 约束 | 说明 |
| :--------- | :------- | :-------------- | :------- |
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 用户 |
| role_id | BIGINT | FK → user_roles | 角色 |
| created_at | DATETIME | | 创建时间 |
唯一索引:(user_id, role_id)
### 3.6 user_department -- 部门表
| 字段 | 类型 | 约束 | 说明 |
| :---------- | :----------- | :------- | :-------------- |
| id | BIGINT | PK | |
| name | VARCHAR(100) | NOT NULL | 部门名称 |
| code | VARCHAR(50) | UNIQUE | tech/annotation |
| description | VARCHAR(500) | | 说明 |
### 3.7 user_login_log -- 登录日志表
| 字段 | 类型 | 约束 | 说明 |
| :---------- | :----------- | :------------- | :------------ |
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 用户 ID |
| username | VARCHAR(50) | NOT NULL | 登录账号 |
| ip | VARCHAR(50) | | IP 地址 |
| device | VARCHAR(100) | | 设备信息 |
| location | VARCHAR(100) | | 登录地点 |
| status | TINYINT | NOT NULL | 1=成功 2=失败 |
| fail_reason | VARCHAR(100) | | 失败原因 |
| created_at | DATETIME | | 登录时间 |
索引:(user_id),(created_at)
### 3.8 user_menu -- 菜单表 (新增)
| 字段 | 类型 | 约束 | 说明 |
| :-------------- | :----------- | :-------- | :---------------------------------- |
| id | BIGINT | PK | 主键 |
| parent_id | BIGINT | DEFAULT 0 | 父菜单 ID,0=顶级菜单 |
| name | VARCHAR(50) | NOT NULL | 路由名称(前端路由 name,不可重复) |
| title | VARCHAR(50) | NOT NULL | 菜单标题(前端展示) |
| icon | VARCHAR(50) | | 图标标识 |
| path | VARCHAR(200) | | 路由路径 |
| component | VARCHAR(200) | | 前端组件路径 |
| permission_code | VARCHAR(50) | | 关联权限码(如 project:read) |
| type | TINYINT | NOT NULL | 类型:1=目录 2=菜单 3=按钮 |
| sort | INT | DEFAULT 0 | 排序号(升序) |
| visible | TINYINT | DEFAULT 1 | 是否可见:0=隐藏 1=显示 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
### 3.9 user_role_menu -- 角色菜单关联表 (新增)
| 字段 | 类型 | 约束 | 说明 |
| :------ | :----- | :-------------- | :--- |
| id | BIGINT | PK | 主键 |
| role_id | BIGINT | FK → user_roles | 角色 |
| menu_id | BIGINT | FK → user_menu | 菜单 |
唯一索引:(role_id, menu_id)
### 3.10 user_password_history -- 密码历史表 (新增)
| 字段 | 类型 | 约束 | 说明 |
| :------------ | :----------- | :------------- | :--------------------- |
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 用户 ID |
| password_hash | VARCHAR(255) | NOT NULL | 历史密码哈希(bcrypt) |
| created_at | DATETIME | | 修改时间 |
说明:用于密码修改时校验「不可与最近 3 次密码相同」,仅保留最近 N 条(N 默认 3)。
### 3.11 user_role_custom_dept -- 角色自定义数据权限表 (新增)
| 字段 | 类型 | 约束 | 说明 |
| :------------ | :----- | :------------------- | :--------- |
| id | BIGINT | PK | 主键 |
| role_id | BIGINT | FK → user_roles | 角色 |
| department_id | BIGINT | FK → user_department | 自定义部门 |
唯一索引:(role_id, department_id)
说明:仅当 data_scope = 5(自定义)时生效,配置角色可访问的部门集合。
### 3.12 ER图
```
text
┌──────────────────── user_roles【角色表】──────────────────┐
│ id(PK bigint) 角色ID(自增主键) │
│ role_name(varchar50) 角色名称 │
│ role_code(varchar50) 角色编码(ROLE_ADMIN) │
│ is_preset(tinyint) 是否预置角色 │
│ data_scope(tinyint) 数据权限范围 │
│ sort(int) 排序号 │
│ status(tinyint) 启用状态 │
└───────────┬──────────────────────────┬───────────────────┘
│1 │1
│拥有多个用户 │拥有多条权限
▼ ▼
┌──user_user_role【用户角色关联表】┐ ┌─user_role_permissions【角色权限关联表】─┐
│ id(PK bigint) 自增ID │ │ id(PK bigint) 自增ID │
│ user_id(FK) → user_user.id │ │ role_id(FK) → user_roles.id │
│ role_id(FK) → user_roles.id │ │ permission_id(FK) → user_permissions.id │
└───────┬─────────────────────────┘ └────────────────────┬───────────────────────┘
│N │N
▼ ▼
┌──────────────── user_user【用户表】────────────────────┐ ┌────user_permissions【权限表】────┐
│ id(PK bigint) 用户主键 │ │ id(PK bigint) 权限ID │
│ username(varchar50) UNIQUE NOT NULL 账号 │ │ permission_code(varchar50) UNIQUE│
│ password(varchar255) NOT NULL 密码 │ │ permission_name(varchar100) │
│ real_name(varchar50) NOT NULL 真实姓名 │ │ module(varchar50) NOT NULL │
│ email(varchar100) 邮箱 │ │ description(varchar200) │
│ phone(varchar20) 手机号 │ └────────────────────────────────┘
│ role_id(FK) → user_roles.id【冗余主角色】 │
│ department_id(FK) → user_department.id │
│ status(tinyint) 默认1 启用状态 │
│ is_deleted(tinyint) 软删除标记 │
└──┬────────────────────────────┬───────────────────────┘
│N │1
│属于一个部门 │产生多条登录日志
▼ ▼
┌──user_department【部门表】┐ ┌────user_login_log【登录日志表】────────────
│ id(PK bigint) 部门ID │ │ id(PK bigint) 日志ID │
│ name(varchar100) NOT NULL 部门名│ user_id(FK) → user_user.id │
│ code(varchar50) UNIQUE 部门编码│ username(varchar50) NOT NULL 登录账号 │
│ description(varchar500) 部门说明│ ip(varchar50) 登录IP │
└───────────────────────────┘ │ device(varchar100) 设备信息 │
│ location(varchar100) 登录地点 │
│ status(tinyint) NOT NULL 登录状态 │
│ fail_reason(varchar100) 失败原因 │
└────────────────────────────────────────────┘
┌──────────────────── user_menu【菜单表】──────────────────┐
│ id(PK bigint) 菜单ID │
│ parent_id(bigint) 父菜单ID │
│ name(varchar50) 路由名称 │
│ title(varchar50) 菜单标题 │
│ type(tinyint) 类型:1=目录 2=菜单 3=按钮 │
│ permission_code(varchar50)关联权限码 │
└─────────────────────────────────────────────────────────┘
│1
│拥有多条角色关联
▼
┌──user_role_menu【角色菜单关联表】──┐ ┌─user_role_custom_dept【自定义数据权限】─┐
│ id(PK bigint) 自增ID │ │ id(PK bigint) 自增ID │
│ role_id(FK) → user_roles.id │ │ role_id(FK) → user_roles.id │
│ menu_id(FK) → user_menu.id │ │ department_id(FK) → user_department.id │
└───────────────────────────────────┘ └─────────────────────────────────────────┘
```
## 4. 完整权限矩阵(按模块分组)
### 4.1 项目管理模块(project)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :------------------ | :----------------- | :------- | :--: | :--: | :--: | :----: |
| project:read | 查看项目列表/详情 | 查看 | Y | Y | Y | Y |
| project:create | 创建项目 | 操作 | - | - | - | Y |
| project:update | 更新项目 | 操作 | - | - | - | Y |
| project:delete | 删除项目(软删除) | 操作 | - | - | - | Y |
| project:simple_list | 获取项目下拉列表 | 查看 | Y | Y | Y | Y |
### 4.2 标签管理模块(tag)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :--------- | :----------- | :------- | :--: | :--: | :--: | :----: |
| tag:read | 查看标签列表 | 查看 | Y | Y | Y | Y |
| tag:create | 创建标签 | 操作 | - | - | - | Y |
| tag:update | 更新标签 | 操作 | - | - | - | Y |
| tag:delete | 删除标签 | 操作 | - | - | - | Y |
### 4.3 难度配置模块(difficulty)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :----------------------- | :---------------------- | :------- | :--: | :--: | :--: | :----: |
| difficulty:read | 查看难度评分卡 | 查看 | - | Y | Y | Y |
| difficulty:config | 配置评分卡维度/权重 | 操作 | - | - | - | Y |
| difficulty:calibrate | AI 难度校准(一键校准) | 操作 | - | - | Y | - |
| difficulty:ai_score_view | 查看 AI 评分结果 | 查看 | - | - | Y | Y |
### 4.4 项目推荐模块(recommend)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :---------------- | :---------------- | :------- | :--: | :--: | :--: | :----: |
| recommend:request | 发起 AI 项目推荐 | 操作 | Y | - | - | - |
| recommend:read | 查看推荐列表/历史 | 查看 | Y | - | - | Y |
| recommend:choose | 采纳推荐项目 | 操作 | Y | - | - | - |
| recommend:ignore | 忽略推荐项目 | 操作 | Y | - | - | - |
### 4.5 知识点模块(knowledge)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :------------------- | :------------------ | :------- | :--: | :--: | :--: | :----: |
| knowledge:read | 查看知识点列表/详情 | 查看 | Y | Y | Y | Y |
| knowledge:create | 手动添加知识点 | 操作 | - | - | - | Y |
| knowledge:update | 编辑知识点 | 操作 | - | - | - | Y |
| knowledge:delete | 删除知识点 | 操作 | - | - | - | Y |
| knowledge:ai_extract | AI 触发知识点提取 | 操作 | - | - | - | Y |
### 4.6 文件管理模块(file)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :------------ | :--------------- | :------- | :--: | :--: | :--: | :----: |
| file:upload | 上传项目资料 | 操作 | - | - | - | Y |
| file:download | 获取签名下载 URL | 操作 | - | - | - | Y |
### 4.7 实训任务管理模块(training)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :--------------------- | :--------------- | :------- | :--: | :--: | :--: | :----: |
| training:create | 创建实训任务 | 操作 | Y | - | - | Y |
| training:read_own | 查看本人的实训 | 查看 | Y | - | - | - |
| training:read_assigned | 查看分配给我的 | 查看 | - | Y | - | - |
| training:read_all | 查看全部实训 | 查看 | - | - | Y | Y |
| training:update | 更新实训任务 | 操作 | Y | - | - | Y |
| training:delete | 删除实训任务 | 操作 | Y | - | - | Y |
| training:assign_mentor | 分配/变更导师 | 操作 | - | - | - | Y |
| training:read_detail | 查看实训任务详情 | 查看 | Y | Y | Y | Y |
### 4.8 预览管理模块(preview)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :--------------------- | :------------- | :------- | :--: | :--: | :--: | :----: |
| preview:read_knowledge | 查看预览知识点 | 操作 | Y | - | - | - |
| preview:submit | 提交预览完成 | 操作 | Y | - | - | - |
| preview:tak_quiz | 参加预习小测 | 操作 | Y | - | - | - |
| preview:read_progress | 查看预览进度 | 查看 | - | Y | - | - |
### 4.9 实操管理模块(practice)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :----------------------- | :----------- | :------- | :--: | :--: | :--: | :----: |
| practice:submit_artifact | 提交实操产物 | 操作 | Y | - | - | - |
| practice:write_report | 撰写实操报告 | 操作 | Y | - | - | - |
| practice:submit_report | 提交实操报告 | 操作 | Y | - | - | - |
### 4.10 答辩管理模块(defense)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :------------------- | :-------------------- | :------- | :--: | :--: | :--: | :----: |
| defense:apply | 申请答辩 | 操作 | Y | - | - | - |
| defense:review | 答辩评审(评分+结论) | 操作 | - | Y | - | - |
| defense:audit | 答辩审核(主管级) | 操作 | - | - | Y | - |
| defense:read | 查看答辩记录/详情 | 查看 | Y | Y | Y | Y |
| defense:pending_list | 查看待办答辩列表 | 查看 | - | Y | Y | - |
### 4.11 历史记录模块(history)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :---------------------- | :--------------------- | :------- | :--: | :--: | :--: | :----: |
| history:read_own | 查看本人历史实训记录 | 查看 | Y | - | - | - |
| history:read_department | 查看本部门历史实训记录 | 查看 | - | Y | - | - |
| history:read_all | 查看全部历史实训记录 | 查看 | - | - | Y | Y |
### 4.12 容器管理模块(container)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :--------------- | :------------------------- | :------- | :--: | :--: | :--: | :----: |
| container:use | 使用容器沙箱 | 操作 | Y | - | - | - |
| container:manage | 管理容器(创建/销毁/续期) | 操作 | - | - | - | Y |
### 4.13 缺陷记录模块(defect)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :---------- | :--------------- | :------- | :--: | :--: | :--: | :----: |
| defect:read | 查看缺陷记录列表 | 查看 | Y | Y | - | Y |
| defect:add | 手动添加缺陷记录 | 操作 | - | Y | - | Y |
### 4.14 进阶匹配模块(advanced)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :-------------- | :--------------- | :------- | :--: | :--: | :--: | :----: |
| advanced:accept | 采纳进阶推荐 | 操作 | Y | - | - | - |
| advanced:reject | 忽略进阶推荐 | 操作 | Y | - | - | - |
| advanced:read | 查看进阶匹配记录 | 查看 | Y | - | - | Y |
### 4.15 能力画像模块(profile)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :----------- | :--------------- | :------- | :--: | :--: | :--: | :----: |
| profile:read | 查看学员能力画像 | 查看 | Y | Y | Y | Y |
### 4.16 用户管理模块(user)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :--------------- | :----------------- | :------- | :--: | :--: | :--: | :----: |
| user:read | 查看用户列表/详情 | 查看 | - | - | - | Y |
| user:create | 创建用户 | 操作 | - | - | - | Y |
| user:update | 更新用户信息 | 操作 | - | - | - | Y |
| user:delete | 删除用户(软删除) | 操作 | - | - | - | Y |
| user:assign-role | 分配用户角色 | 操作 | - | - | - | Y |
### 4.17 角色权限管理模块(role)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :---------------- | :---------------- | :------- | :--: | :--: | :--: | :----: |
| role:read | 查看角色列表/详情 | 查看 | - | - | - | Y |
| role:create | 创建角色 | 操作 | - | - | - | Y |
| role:update | 更新角色/权限分配 | 操作 | - | - | - | Y |
| role:delete | 删除角色 | 操作 | - | - | - | Y |
| role:assign-user | 分配用户角色 | 操作 | - | - | - | Y |
| permission:assign | 分配角色权限 | 操作 | - | - | - | Y |
### 4.18 导师工作台模块(mentor_dashboard)
| 权限编码 | 权限名称 | 操作级别 | 学员 | 导师 | 主管 | 管理员 |
| :--------------- | :----------------- | :------- | :--: | :--: | :--: | :----: |
| mentor:dashboard | 查看导师工作台统计 | 查看 | - | Y | - | Y |
## 5. 权限检查流程
1.
**前端路由守卫**
:按角色显示/隐藏菜单项。
2.
**按钮级指令**
:按权限编码控制按钮显隐(查看/操作/配置等)。
3.
**后端 API**
:
`@PreAuthorize`
校验,从 JWT 解析 role_id。
4.
**查询 role_permissions**
:是否有对应权限码。
5.
**响应结果**
:有权限 -> 200,无权限 -> 403。
示例:导师看到评审按钮,主管只能看到查看按钮;学员看到 “发起推荐” 按钮但看不到 “删除项目” 按钮。
## 6. 资源级权限控制(数据权限)(新增)
### 6.1 设计目标
在接口权限(@PreAuthorize)校验通过后,进一步控制用户
**能看到哪些数据**
(例如:学员只能看自己的,导师只能看本部门的)。
### 6.2 数据范围定义 (data_scope)
基于
`user_roles`
表的
`data_scope`
字段:
*
**1 (ALL)**
:全部数据(ADMIN 默认)。
*
**2 (DEPARTMENT)**
:本部门数据。
*
**3 (DEPARTMENT_AND_SUB)**
:本部门及下级部门数据。
*
**4 (SELF)**
:仅本人数据(STUDENT 默认)。
*
**5 (CUSTOM)**
:自定义部门范围(通过
`user_role_custom_dept`
表配置)。
### 6.3 技术实现方案
*
**注解**
:使用
`@DataScope(tableAlias = "u")`
标记在 Mapper 方法上。
*
**拦截器**
:MyBatis 拦截器读取当前用户的
`data_scope`
,自动在 SQL 后面拼接
`AND u.department_id = ...`
或
`AND u.id = ...`
。
*
**安全**
:严禁字符串拼接用户输入,必须使用参数化查询防 SQL 注入。
## 7. 安全要求
| 要求 | 实现 |
| :--------- | :---------------------------------- |
| 密码加密 | bcrypt (cost=12) |
| 传输加密 | HTTPS / TLS 1.3 |
| Token 时效 | access_token 2h + refresh_token 7d |
| 接口鉴权 | @PreAuthorize + 拦截器 |
| 越权响应 | HTTP 403 + JSON 错误码 |
| 权限缓存 | Redis 缓存角色权限列表,key=role_id |
| 密码历史 | 不可与最近 3 次密码相同 |
## 8. 与各模块的映射
| 来源模块 | 对应的权限分组 | 权限条目数 |
| :----------------------- | :----------------------------------------------------------- | :--------- |
| user-module-任务文档 | user / role | 12 |
| project-module-任务文档 | project / tag / difficulty / recommend / knowledge / file | 22 |
| training-module-任务文档 | training / preview / practice / defense / container / defect / advanced / profile / history / mentor_dashboard | 24 |
总计定义权限:约 58 个权限点,覆盖系统全部 4 种角色,按 18 个功能模块分组管理。
\ No newline at end of file
编写
预览
Markdown
格式
0%
重试
或
添加新文件
添加附件
取消
您添加了
0
人
到此讨论。请谨慎行事。
请先完成此评论的编辑!
取消
请
注册
或者
登录
后发表评论