# 角色管理功能需求文档

## 1. 功能概述

角色管理功能是系统权限管理的核心模块，用于管理系统中的角色信息、角色权限分配以及角色与用户的关联关系。该功能提供了完整的CRUD操作，支持角色的新增、修改、删除、查询，以及权限管理和人员管理功能。

## 2. 功能需求

### 2.1 角色列表查询

#### 2.1.1 查询条件
- **角色名称**：支持模糊查询
- **查询按钮**：点击查询按钮执行查询操作
- **重置按钮**：清空查询条件并重新加载数据

#### 2.1.2 列表显示
列表显示以下字段：
- **选择框**：支持多选，用于批量删除操作
- **序号**：连续序号，支持跨页连续显示
- **角色名称**：显示角色名称，支持排序
- **备注**：显示角色描述信息，支持排序
- **是否系统角色**：显示是否为系统角色（是/否），支持排序
- **创建时间**：显示角色创建时间，格式为yyyy-MM-dd，支持排序
- **操作**：提供人员管理、修改、删除按钮

#### 2.1.3 列表功能
- **排序**：支持按角色名称、备注、是否系统角色、创建时间进行排序（数据库级排序）
- **分页**：支持分页显示，每页显示10/20/50/100条记录
- **Loading状态**：查询时显示loading状态，防止重复点击

### 2.2 新增角色

#### 2.2.1 新增按钮
- 位置：操作按钮区
- 功能：打开新增角色对话框

#### 2.2.2 新增对话框
- **标题**：新增角色
- **表单字段**：
  - 角色名称：必填，文本输入框
  - 备注：选填，文本输入框
  - 权限管理：树状控件，显示Sys_FunctionCode表的FunctionName

#### 2.2.3 权限树状控件
- **数据源**：从Sys_FunctionCode表获取数据
- **显示字段**：FunctionName
- **选择逻辑**：
  - 勾选父节点时，自动勾选所有子节点
  - 勾选子节点时，自动勾选父节点
  - 清除子节点时，不清除父节点的勾选
- **数据保存**：选中的FunctionCode保存到Sys_Role_Sys_FunctionCode表中

#### 2.2.4 保存逻辑
- 校验角色名称是否重复
- 保存角色信息到Sys_Role表
- 保存角色权限关系到Sys_Role_Sys_FunctionCode表
- 设置公共字段：
  - RecordStatus：1（启用）
  - CreateUserID：当前登录用户ID
  - CreateTime：当前时间
  - ModifyUserID：当前登录用户ID
  - ModifyTime：当前时间

### 2.3 修改角色

#### 2.3.1 修改按钮
- 位置：操作列
- 形式：图标按钮（Edit图标）
- 功能：打开修改角色对话框

#### 2.3.2 修改对话框
- **标题**：修改角色
- **表单字段**：与新增对话框相同
- **默认值**：回显当前角色的数据
- **权限树**：根据Sys_Role_Sys_FunctionCode表的数据默认勾选

#### 2.3.3 保存逻辑
- 校验角色名称是否与其他角色重复
- 更新角色信息到Sys_Role表
- 更新角色权限关系到Sys_Role_Sys_FunctionCode表（先删除旧的，再插入新的）
- 更新公共字段：
  - ModifyUserID：当前登录用户ID
  - ModifyTime：当前时间

### 2.4 删除角色

#### 2.4.1 单个删除
- **删除按钮**：操作列中的删除按钮（Delete图标）
- **确认对话框**：显示删除确认提示
- **删除逻辑**：
  - 先删除Sys_User_Sys_Role表中的用户角色关联数据
  - 再删除Sys_Role_Sys_FunctionCode表中的角色权限关联数据
  - 最后删除Sys_Role表中的角色数据

#### 2.4.2 批量删除
- **批量删除按钮**：操作按钮区
- **启用条件**：选中至少一条记录时启用
- **确认对话框**：显示删除确认提示
- **删除逻辑**：循环删除选中的角色，删除顺序与单个删除相同

### 2.5 人员管理

#### 2.5.1 人员管理按钮
- **位置**：操作列
- **形式**：图标按钮（User图标）
- **功能**：打开人员管理对话框

#### 2.5.2 人员管理对话框
- **标题**：角色名称
- **查询条件**：
  - 文本框：支持按姓名或登录名模糊查询
  - 查询按钮：执行查询操作
- **查询结果列表**：
  - 显示所有拥有该角色的用户
  - 字段：姓名、登录账号
  - 操作：删除按钮（移除该用户的角色）

#### 2.5.3 新增拥有该角色的用户
- **新增按钮**：人员管理对话框中
- **功能**：打开用户选择对话框

#### 2.5.4 用户选择对话框（通用组件）
- **查询条件**：
  - 登录账号：模糊查询
  - 姓名：模糊查询
- **查询结果列表**：
  - 勾选框
  - 登录账号
  - 姓名
- **查询功能**：
  - 支持数据库级分页
  - 可多次查询，选中结果累加到选中区
- **选中区**：
  - 显示已选中的用户
  - 支持取消选中
- **确定按钮**：
  - 将选中的用户添加到角色中
  - 维护Sys_User_Sys_Role表数据

## 3. 技术实现

### 3.1 后端实现

#### 3.1.1 实体类
- **Role**：角色实体类，对应Sys_Role表
- **SysRoleFunctionCode**：角色权限关联实体类，对应Sys_Role_Sys_FunctionCode表
- **SysUserRole**：用户角色关联实体类，对应Sys_User_Sys_Role表

#### 3.1.2 Repository
- **RoleRepository**：角色数据访问接口
- **SysRoleFunctionCodeRepository**：角色权限关联数据访问接口
- **SysUserRoleRepository**：用户角色关联数据访问接口

#### 3.1.3 Service
- **RoleService**：角色业务逻辑服务
  - queryRoles：分页查询角色列表
  - createRole：创建角色
  - updateRole：更新角色
  - deleteRoles：删除角色
  - getFunctionCodeTree：获取权限树数据
  - getRoleUsers：获取角色用户列表
  - addUsersToRole：添加用户到角色
  - removeUserFromRole：从角色中移除用户

#### 3.1.4 Controller
- **RoleController**：角色控制器
  - GET /role/list：查询角色列表
  - POST /role/create：创建角色
  - PUT /role/update：更新角色
  - DELETE /role/delete/{id}：删除角色
  - DELETE /role/batchDelete：批量删除角色
  - GET /role/functionCodeTree：获取权限树
  - GET /role/{roleId}/users：获取角色用户列表
  - POST /role/{roleId}/addUsers：添加用户到角色
  - DELETE /role/{roleId}/removeUser/{userId}：从角色中移除用户

### 3.2 前端实现

#### 3.2.1 组件结构
- **RoleManagement.vue**：角色管理主组件
- **UserSelectDialog.vue**：用户选择对话框通用组件

#### 3.2.2 主要功能方法
- **getRoles**：获取角色列表
- **handleSearch**：查询操作
- **resetSearchForm**：重置查询条件
- **handleSortChange**：排序处理
- **handleAdd**：打开新增对话框
- **handleEdit**：打开修改对话框
- **handleDelete**：删除角色
- **handleBatchDelete**：批量删除角色
- **handleSubmit**：提交新增/修改
- **handleUserManagement**：打开人员管理对话框
- **getRoleUsers**：获取角色用户列表
- **openUserSelectDialog**：打开用户选择对话框
- **handleUserSelectConfirm**：确认添加用户到角色
- **removeUserFromRole**：从角色中移除用户

#### 3.2.3 状态管理
- **queryForm**：查询条件表单
- **roleList**：角色列表数据
- **selectedRows**：选中的角色
- **currentPage**：当前页码
- **pageSize**：每页显示数量
- **total**：总记录数
- **loading**：查询loading状态
- **deleteLoading**：删除loading状态
- **sortMap**：排序参数

### 3.3 数据库设计

#### 3.3.1 Sys_Role表
- **RoleID**：角色ID（主键）
- **RoleName**：角色名称
- **Description**：角色描述
- **IsSystemRole**：是否系统角色
- **RecordStatus**：记录状态
- **CreateUserID**：创建人ID
- **CreateTime**：创建时间
- **ModifyUserID**：修改人ID
- **ModifyTime**：修改时间

#### 3.3.2 Sys_Role_Sys_FunctionCode表
- **ID**：主键
- **RoleID**：角色ID（外键）
- **FunctionCode**：功能代码（外键）

#### 3.3.3 Sys_User_Sys_Role表
- **ID**：主键
- **UserID**：用户ID（外键）
- **RoleID**：角色ID（外键）

## 4. 界面设计

### 4.1 布局结构
- **页面标题**：角色管理
- **查询条件区**：包含角色名称查询条件和查询/重置按钮
- **操作按钮区**：包含新增和删除按钮
- **表格区**：显示角色列表
- **分页区**：分页控件

### 4.2 样式规范
- **页面背景**：白色
- **卡片样式**：白色背景，圆角4px，阴影效果
- **表格样式**：
  - 表头背景色：#f5f7fa
  - 表头字体颜色：#303133
  - 表头字体粗细：bold
  - 表格字体大小：12px
  - 单元格内边距：8px 0
- **按钮样式**：使用Element Plus默认样式
- **Loading状态**：查询和删除操作时显示loading状态

### 4.3 响应式设计
- 表格宽度：calc(100vw - 331px)
- 表格高度：calc(100vh - 395px)
- 固定列：选择框、序号、操作列固定
- 文本截断：长文本显示省略号

## 5. 业务规则

### 5.1 角色名称唯一性
- 角色名称在系统中必须唯一
- 新增时校验角色名称是否已存在
- 修改时校验角色名称是否与其他角色重复

### 5.2 系统角色保护
- 系统角色（IsSystemRole=true）不允许删除
- 系统角色的权限不允许修改

### 5.3 级联删除
- 删除角色时，必须先删除关联的用户角色关系
- 删除角色时，必须先删除关联的角色权限关系
- 删除角色时，必须最后删除角色本身

### 5.4 权限树选择逻辑
- 勾选父节点时，自动勾选所有子节点
- 勾选子节点时，自动勾选父节点
- 清除子节点时，不清除父节点的勾选

## 6. 性能优化

### 6.1 数据库级排序
- 排序在数据库层面执行，提高查询效率
- 避免在前端进行大数据量的排序操作

### 6.2 分页查询
- 使用数据库分页，避免一次性加载大量数据
- 支持自定义每页显示数量

### 6.3 Loading状态管理
- 查询、删除操作时显示loading状态
- 防止用户重复点击，避免重复提交

### 6.4 缓存优化
- 权限树数据可以缓存，减少数据库查询
- 字典数据可以缓存，减少数据库查询

## 7. 安全性

### 7.1 权限控制
- 只有拥有角色管理权限的用户才能访问该功能
- 删除操作需要二次确认，防止误操作

### 7.2 数据验证
- 前端进行表单验证
- 后端进行业务逻辑验证
- 防止SQL注入、XSS攻击等安全漏洞

### 7.3 操作日志
- 记录所有角色的增删改操作
- 记录操作人、操作时间、操作内容

## 8. 测试要点

### 8.1 功能测试
- 测试角色的增删改查功能
- 测试权限树的选择逻辑
- 测试人员管理功能
- 测试批量删除功能
- 测试排序和分页功能

### 8.2 界面测试
- 测试界面布局是否符合设计要求
- 测试响应式布局是否正常
- 测试Loading状态是否正常显示
- 测试固定列是否正常工作

### 8.3 性能测试
- 测试大数据量下的查询性能
- 测试并发操作的性能
- 测试内存使用情况

### 8.4 安全测试
- 测试权限控制是否生效
- 测试数据验证是否完善
- 测试SQL注入、XSS攻击等安全漏洞

## 9. 版本历史

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| 1.0 | 2026-03-05 | 初始版本，完成角色管理功能开发 | AI Assistant |

## 10. 附录

### 10.1 相关文档
- [后端开发最佳实践](../.trae/rules/backend-dev-best-practices.md)
- [Web前端开发最佳实践](../.trae/rules/web-dev-best-practices.md)
- [数据库结构文档](../database_structure.md)

### 10.2 代码文件
- 后端：
  - `JavaBackend/src/main/java/com/lianda/backend/model/Role.java`
  - `JavaBackend/src/main/java/com/lianda/backend/model/SysRoleFunctionCode.java`
  - `JavaBackend/src/main/java/com/lianda/backend/model/SysUserRole.java`
  - `JavaBackend/src/main/java/com/lianda/backend/repository/RoleRepository.java`
  - `JavaBackend/src/main/java/com/lianda/backend/repository/SysRoleFunctionCodeRepository.java`
  - `JavaBackend/src/main/java/com/lianda/backend/repository/SysUserRoleRepository.java`
  - `JavaBackend/src/main/java/com/lianda/backend/service/RoleService.java`
  - `JavaBackend/src/main/java/com/lianda/backend/controller/RoleController.java`
- 前端：
  - `vue-frontend/src/components/RoleManagement.vue`
  - `vue-frontend/src/components/UserSelectDialog.vue`