scaffold-system 系统管理模块

模块概述

scaffold-system 是平台的核心系统管理模块，提供用户、角色、菜单、字典、系统配置、登录日志和操作日志的管理能力。基于 RBAC（基于角色的访问控制）模型实现权限管理，支持菜单权限的细粒度控制。所有写操作均使用 POST 方法，操作日志通过 @OperLog 注解自动记录。

功能列表

• 用户管理：用户的增删改查、密码修改/重置、角色分配、状态启停、批量删除
• 角色管理：角色的增删改查、菜单权限分配、状态启停、批量删除
• 菜单管理：菜单的增删改查、菜单树构建、按用户/角色查询菜单
• 字典管理：字典类型和字典数据的增删改查、按编码查询字典数据列表
• 系统配置：配置项的增删改查、按 key 查询配置值、配置缓存刷新、批量删除
• 登录日志：登录日志分页查询、批量删除、清空
• 操作日志：操作日志分页查询、批量删除、清空

核心组件

层	类名	职责
Controller	UserController	用户管理接口，路径 /v1/system/user
Controller	RoleController	角色管理接口，路径 /v1/system/role
Controller	MenuController	菜单管理接口，路径 /v1/system/menu
Controller	DictController	字典管理接口，路径 /v1/system/dict
Controller	DictDataController	字典数据管理接口，路径 /v1/system/dictData
Controller	SysConfigController	系统配置接口，路径 /v1/system/config
Controller	LoginLogController	登录日志接口，路径 /v1/system/loginLog
Controller	OperLogController	操作日志接口，路径 /v1/system/operLog
Service	UserService	用户业务逻辑
Service	RoleService	角色业务逻辑
Service	MenuService	菜单业务逻辑，含菜单树构建
Service	SysDictService / SysDictDataService	字典及字典数据业务逻辑
Service	SysConfigService	系统配置业务逻辑，支持缓存
Service	SysLoginLogService / SysOperLogService	日志查询与清理
Service	SysUserDetailsService	Spring Security 用户加载
Entity	User	用户实体
Entity	Role / RoleMenu / UserRole	角色及关联关系实体
Entity	Menu	菜单实体
Entity	SysDict / SysDictData	字典及字典数据实体
Entity	SysConfig	系统配置实体
Entity	SysLoginLog / SysOperLog	日志实体
Config	SystemAutoConfiguration	自动配置类，扫描 mapper 和组件

枚举值说明

状态枚举（布尔语义）

系统模块中的 status、visible 字段遵循布尔语义规范：

枚举	值	说明
UserStatusEnum.NORMAL	1	正常状态
UserStatusEnum.DISABLED	0	禁用状态
RoleStatusEnum.NORMAL	1	正常状态
RoleStatusEnum.DISABLED	0	禁用状态
MenuStatusEnum.NORMAL	1	正常状态
MenuStatusEnum.DISABLED	0	禁用状态
Menu.VISIBLE_YES	1	显示
Menu.VISIBLE_NO	0	隐藏

核心规范：1 = 正向值（正常/启用/显示），0 = 负向值（停用/禁用/隐藏）

数据权限范围

枚举	值	说明
DataScopeEnum.ALL	1	全部数据
DataScopeEnum.DEPT	2	本部门数据
DataScopeEnum.DEPT_AND_CHILD	3	本部门及以下数据
DataScopeEnum.SELF	4	仅本人数据
DataScopeEnum.CUSTOM	5	自定义数据

注意：DataScopeEnum 为多态状态机，不遵循布尔语义规范。

API 接口列表

用户管理 /v1/system/user

方法	路径	说明
POST	/create	创建用户
POST	/update	更新用户
POST	/delete/{userId}	删除用户
POST	/batchDelete	批量删除用户
GET	/get/{userId}	根据ID查询用户
GET	/page	分页查询用户（支持 username/nickname/mobile/status 筛选）
POST	/updatePassword	修改用户密码
POST	/resetPassword/{userId}	重置用户密码
POST	/assignRoles	分配用户角色
POST	/updateStatus/{userId}/{status}	修改用户状态

角色管理 /v1/system/role

方法	路径	说明
POST	/create	创建角色
POST	/update	更新角色
POST	/delete/{roleId}	删除角色
POST	/batchDelete	批量删除角色
GET	/get/{roleId}	根据ID查询角色
GET	/page	分页查询角色
POST	/assignMenus	分配角色菜单权限
POST	/updateStatus/{roleId}/{status}	修改角色状态

菜单管理 /v1/system/menu

方法	路径	说明
POST	/create	创建菜单
POST	/update	更新菜单
POST	/delete/{menuId}	删除菜单
GET	/get/{menuId}	根据ID查询菜单
GET	/list	查询菜单列表（平铺）
GET	/tree	构建菜单树（树形结构）

字典管理 /v1/system/dict

方法	路径	说明
POST	/create	创建字典类型
POST	/update	更新字典类型
POST	/delete/{id}	删除字典（同时删除关联的字典数据）
GET	/get/{id}	根据ID查询字典
GET	/page	分页查询字典

字典数据管理 /v1/system/dictData

方法	路径	说明
POST	/create	创建字典数据
POST	/update	更新字典数据
POST	/delete/{id}	删除字典数据
GET	/get/{id}	根据ID查询字典数据
GET	/page	分页查询字典数据
GET	/list?dictCode=xxx	根据字典编码查询数据列表

系统配置 /v1/system/config

方法	路径	说明
POST	/create	创建配置项
POST	/update	更新配置项
POST	/delete/{id}	删除配置项
POST	/batchDelete	批量删除配置项
GET	/get/{id}	根据ID查询配置
GET	/getValue/{configKey}	根据配置键查询配置值
GET	/page	分页查询配置
POST	/refreshCache	刷新配置缓存

登录日志 /v1/system/loginLog

方法	路径	说明
GET	/get/{id}	根据ID查询登录日志
GET	/page	分页查询登录日志
POST	/batchDelete	批量删除登录日志
POST	/clean	清空登录日志

操作日志 /v1/system/operLog

方法	路径	说明
GET	/get/{id}	根据ID查询操作日志
GET	/page	分页查询操作日志
POST	/batchDelete	批量删除操作日志
POST	/clean	清空操作日志

使用示例

创建用户并分配角色

// 1. 创建用户
UserCreateDTO createDTO = new UserCreateDTO();
createDTO.setUsername("zhangsan");
createDTO.setNickname("张三");
createDTO.setMobile("13800138000");
createDTO.setEmail("zhangsan@example.com");
Long userId = userService.createUser(createDTO);

// 2. 分配角色
UserRoleAssignDTO assignDTO = new UserRoleAssignDTO();
assignDTO.setUserId(userId);
assignDTO.setRoleIds(List.of(1L, 2L));
userService.assignRoles(assignDTO);

前端调用字典数据

// 根据字典编码获取字典数据列表，用于下拉框等场景
const { data } = await get('/v1/system/dictData/list', { params: { dictCode: 'gender' } })
// data = [{ label: '男', value: '1' }, { label: '女', value: '2' }]

获取菜单树构建前端路由

// 获取完整菜单树，用于构建前端侧边栏导航
const { data } = await get('/v1/system/menu/tree')
// data 为树形结构数组

注意事项

• 所有写操作（创建/更新/删除）均使用 POST 方法，不使用 PUT/DELETE。
• 用户密码在存储前经过加密处理，重置密码后会设置为系统默认密码。
• 角色删除前需确认未被用户引用；菜单删除会递归删除子菜单。
• 字典删除会级联删除其下的所有字典数据。
• 系统配置支持缓存，修改配置后需调用 /refreshCache 刷新缓存才能生效。
• 所有实体使用雪花 ID（Long 类型），前端需以字符串处理避免 JS 精度丢失。
• 模块自动配置类为 SystemAutoConfiguration，通过 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 注册。