提交 299ccb35 authored 作者: caifuming's avatar caifuming

cfm_7/17完善后端配置(先写的静态进行功能展示)

上级 58c1d2b9
# 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
...@@ -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,38 +246,147 @@ public class DataInitializer implements CommandLineRunner { ...@@ -117,38 +246,147 @@ 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("""
...@@ -166,19 +404,106 @@ public class DataInitializer implements CommandLineRunner { ...@@ -166,19 +404,106 @@ public class DataInitializer implements CommandLineRunner {
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) {
log.warn("[migrate] {}.{} 单列唯一索引修正失败: {}", 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) { } catch (Exception e) {
log.warn("[migrate] {}.{} 单列唯一索引修正失败(可能已修正或表不存在): {}", log.warn("[migrate] 检查表 {} 是否存在失败: {}", tableName, e.getMessage());
tableName, columnName, e.getMessage()); return false;
} }
} }
} }
...@@ -55,7 +55,7 @@ public class DepartmentController { ...@@ -55,7 +55,7 @@ public class DepartmentController {
} }
@PostMapping @PostMapping
@PreAuthorize("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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)
......
...@@ -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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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);
......
...@@ -106,7 +106,7 @@ public class RoleController { ...@@ -106,7 +106,7 @@ public class RoleController {
// ========== 3.4.3 创建角色 ========== // ========== 3.4.3 创建角色 ==========
@PostMapping @PostMapping
@PreAuthorize("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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) {
......
...@@ -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("hasRole('ADMIN') or #id == authentication.principal.id") @PreAuthorize("hasAuthority('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("hasRole('ADMIN') or #id == authentication.principal.id") @PreAuthorize("hasAuthority('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("hasRole('ADMIN') or #id == authentication.principal.id") @PreAuthorize("hasAuthority('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,7 +128,7 @@ public class UserController { ...@@ -121,7 +128,7 @@ public class UserController {
// ========== 3.3.4 修改密码 ========== // ========== 3.3.4 修改密码 ==========
@PutMapping("/{id}/password") @PutMapping("/{id}/password")
@PreAuthorize("hasRole('ADMIN') or #id == authentication.principal.id") @PreAuthorize("hasAuthority('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) {
...@@ -133,7 +140,7 @@ public class UserController { ...@@ -133,7 +140,7 @@ public class UserController {
// ========== 3.3.5 用户列表(带数据权限) ========== // ========== 3.3.5 用户列表(带数据权限) ==========
@GetMapping @GetMapping
@PreAuthorize("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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("hasRole('ADMIN')") @PreAuthorize("hasAuthority('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());
......
...@@ -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);
} }
...@@ -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
...@@ -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);
......
...@@ -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")
......
...@@ -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 resolveRoleAuthority(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());
......
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);
}
}
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);
}
}
...@@ -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) {
......
...@@ -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;
} }
......
-- ============================================================
-- 用户模块数据库表设计
-- 根据 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;
...@@ -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": 200,
"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": 200,
"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": 200,
"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": 200,
"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": 200,
"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": 200,
"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": 200,
"data": { "data": {
"id": 1, "id": 1,
"roleName": "管理员", "roleName": "管理员",
...@@ -580,6 +1117,15 @@ GET /api/v1/roles/{id} ...@@ -580,6 +1117,15 @@ GET /api/v1/roles/{id}
} }
``` ```
**返回状态码**:
| HTTP | 场景 | 业务码 | message |
|------|------|--------|---------|
| 200 | 查询成功 | 0 | 操作成功 |
| 401 | 未登录 / Token 失效 | 1002 | 认证失败,请重新登录 |
| 404 | 角色不存在 | 1004 | 角色不存在 |
| 500 | 系统异常 | 9999 | 系统繁忙,请稍后再试 |
--- ---
#### 3.4.3 创建角色(ADMIN) #### 3.4.3 创建角色(ADMIN)
...@@ -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": 200,
"data": [ "data": [
{ {
"id": 1, "id": 1,
...@@ -668,60 +1248,326 @@ GET /api/v1/menus ...@@ -668,60 +1248,326 @@ 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 | 目录(一级菜单,不可点击) |
| 2 | 菜单(页面) |
| 3 | 按钮(页面内按钮权限) |
| 序号 | 功能点 | 描述 | 优先级 | **验收标准**:
- [ ] 返回完整菜单树形结构
- [ ] 按 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 | | 1 | 发送验证码 | 生成 6 位数字验证码 | P0 |
| 2 | 防刷限制 | 同一手机 60s 内只能发一次 | P0 | | 2 | 防刷限制 | 同一手机 60s 内只能发一次 | P0 |
...@@ -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 = 30; private static final int LOCK_DURATION_MINUTES = 10;
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 拼接 | 高 | 参数化绑定,禁止字符串拼接用户输入 |
| 菜单循环引用 | 中 | 父子关系校验 + 树形深度限制 |
--- ---
......
# 用户模块 · 需求与验收标准文档
项目:实习生培训平台
阶段:阶段一 · 基座搭建(需求整理)
模块:用户模块(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) 设计文档 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 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论