TugboatAIRebuild/用户管理功能需求文档.md

用户管理功能需求文档

功能概述

用户管理功能用于管理系统中的用户信息，包括用户的查询、新增、删除和密码重置等操作。

功能模块

1. 用户查询

1.1 查询条件

用户管理页面提供以下查询条件：

• 用户名：模糊匹配用户的Name字段
• 用户角色：从Sys_Role表中列出所有角色，只要用户能关联到该角色就匹配
• 状态：从Sys_DictionaryItem表中DictionaryCode='RecordStatus'的记录中选择

1.2 查询操作

• 查询按钮：根据输入的查询条件筛选用户列表
• 重置按钮：清空所有查询条件并重新加载用户列表

1.3 用户列表显示

用户列表以表格形式展示，包含以下字段：

字段名称	说明	数据来源
勾选列	复选框，用于批量选择用户	-
序号	记录的顺序号，支持跨页顺序	前端计算
用户名	用户的名称	User.Name字段
账号	用户的登录账号	User.LoginID字段
用户角色	用户关联的角色，多个角色用逗号分隔	通过Sys_UserRole关联Sys_Role
企业微信账号	用户的企业微信账号	User.WeChatUserId字段
状态	用户的状态	User.RecordStatus关联Sys_DictionaryItem
操作	操作按钮列	-

1.4 分页功能

• 支持分页显示用户列表
• 可选择每页显示10、20、50、100条记录
• 支持跳转到指定页码
• 显示总记录数

2. 用户新增

2.1 新增按钮

在按钮区提供"新增"按钮，点击后弹出新增用户对话框。

2.2 新增用户对话框

新增用户对话框包含以下字段：

字段名称	是否必填	说明	验证规则
账号	是	用户的登录账号	不能为空
用户名	是	用户的名称	不能为空
密码	是	用户登录密码	不能为空，长度不少于6位
确认密码	是	再次输入密码	不能为空，必须与密码一致
用户角色	否	用户关联的角色	从Sys_Role表中选择
企业微信账号	否	用户的企业微信账号	可选输入
状态	是	用户的状态	从Sys_DictionaryItem表中选择

2.3 新增操作流程

1. 点击"新增"按钮打开对话框
2. 填写用户信息
3. 点击"提交"按钮
4. 前端进行表单验证
5. 验证通过后调用后端API创建用户
6. 创建成功后关闭对话框并刷新用户列表
7. 创建失败时显示错误信息

3. 用户删除

3.1 批量删除

在按钮区提供"删除"按钮，用于批量删除选中的用户。

3.2 单个删除

在操作列提供"删除"链接，用于删除当前行的用户。

3.3 删除操作流程

1. 选中要删除的用户（批量）或点击操作列的"删除"链接（单个）
2. 调用后端API删除用户
3. 删除成功后刷新用户列表
4. 删除失败时显示错误信息

3.4 删除逻辑

• 删除用户时，同时删除该用户在Sys_UserRole表中的角色关联记录
• 从Sys_User表中删除用户记录

4. 密码重置

4.1 重置密码链接

在操作列提供"重置密码"链接，点击后弹出重置密码对话框。

4.2 重置密码对话框

重置密码对话框包含以下字段：

字段名称	说明
用户名	显示用户的名称（只读）
账号	显示用户的登录账号（只读）
新密码	输入新的密码
确认密码	再次输入新密码

4.3 重置密码操作流程

1. 点击操作列的"重置密码"链接
2. 弹出对话框，显示用户名和账号
3. 输入新密码和确认密码
4. 点击"提交"按钮
5. 前端验证两次输入的密码是否一致
6. 验证通过后调用后端API重置密码
7. 重置成功后关闭对话框并显示成功提示
8. 重置失败时显示错误信息

4.4 密码加密

• 新密码使用MD5加密后存储到User.Password字段

数据库设计

相关表结构

Sys_User表

字段名	类型	说明
UserID	varchar(36)	用户ID（主键）
LoginID	varchar(50)	登录账号
Name	varchar(100)	用户名
Password	varchar(100)	密码（MD5加密）
WeChatUserId	varchar(100)	企业微信账号
RecordStatus	int	状态
CreateTime	datetime	创建时间
ModifyTime	datetime	修改时间

Sys_Role表

字段名	类型	说明
RoleID	varchar(36)	角色ID（主键）
RoleName	varchar(100)	角色名称
Description	varchar(500)	角色描述
IsSystemRole	bit	是否系统角色
RecordStatus	int	状态

Sys_UserRole表

字段名	类型	说明
UserID	varchar(36)	用户ID（主键）
RoleID	varchar(36)	角色ID（主键）

Sys_DictionaryItem表

字段名	类型	说明
DictionaryItemID	varchar(36)	字典项ID（主键）
DictionaryCode	varchar(50)	字典代码
Value	int	字典值
Name	varchar(100)	字典名称

接口设计

1. 查询用户列表

接口地址：GET /api/user/list

请求参数：

参数名	类型	必填	说明
loginId	String	否	用户名（模糊查询）
roleName	String	否	用户角色（模糊查询）
recordStatus	Integer	否	状态
page	Integer	是	页码
pageSize	Integer	是	每页行数

响应示例：

{
  "content": [
    {
      "id": "user-id-1",
      "loginId": "admin",
      "name": "管理员",
      "roleName": "系统管理员",
      "weChatUserId": "wx123456",
      "recordStatus": 1,
      "recordStatusName": "正常",
      "createTime": "2026-01-01 10:00:00",
      "modifyTime": "2026-01-01 10:00:00"
    }
  ],
  "totalElements": 100
}

2. 获取角色列表

接口地址：GET /api/user/roles

响应示例：

[
  {
    "roleId": "role-id-1",
    "roleName": "系统管理员",
    "description": "系统管理员角色",
    "isSystemRole": true,
    "recordStatus": 1
  }
]

3. 获取状态列表

接口地址：GET /api/user/record-status

响应示例：

[
  {
    "dictionaryItemId": "dict-id-1",
    "dictionaryCode": "RecordStatus",
    "value": 1,
    "name": "正常"
  }
]

4. 新增用户

接口地址：POST /api/user/create

请求参数：

{
  "loginId": "testuser",
  "name": "测试用户",
  "password": "123456",
  "roleId": "role-id-1",
  "weChatUserId": "wx789012",
  "recordStatus": 1
}

响应示例：

{
  "success": true,
  "message": "用户创建成功",
  "data": {
    "id": "new-user-id",
    "loginId": "testuser",
    "name": "测试用户",
    "roleName": "系统管理员",
    "weChatUserId": "wx789012",
    "recordStatus": 1,
    "recordStatusName": "正常",
    "createTime": "2026-03-02 10:00:00",
    "modifyTime": "2026-03-02 10:00:00"
  }
}

5. 删除用户

接口地址：DELETE /api/user/delete

请求参数：

["user-id-1", "user-id-2"]

响应示例：

{
  "success": true,
  "message": "删除成功",
  "deletedCount": 2
}

6. 重置密码

接口地址：POST /api/user/reset-password

请求参数：

{
  "userId": "user-id-1",
  "newPassword": "newpassword123"
}

响应示例：

{
  "success": true,
  "message": "密码重置成功"
}

权限控制

功能权限代码

功能	权限代码
查询用户列表	0101
获取角色列表	010101
获取状态列表	010102
删除用户	0102
重置密码	0103
新增用户	0104

权限验证

• 所有接口都需要进行权限验证
• 前端按钮根据用户权限代码显示或隐藏
• 后端接口使用@RequirePermission注解进行权限验证

界面设计

页面布局

1. 页面标题：显示"用户管理"
2. 查询条件区：包含用户名、用户角色、状态查询条件和查询、重置按钮
3. 操作按钮区：包含新增、删除按钮
4. 表格区：显示用户列表
5. 分页区：显示分页控件

响应式设计

• 表格高度自适应屏幕高度：calc(100vh - 551px)
• 表格宽度自适应屏幕宽度
• 支持横向滚动条（当表格内容超出屏幕宽度时）
• 支持纵向滚动条（当表格内容超出可视区域时）

技术实现

后端技术栈

• Spring Boot
• Spring Data JPA
• Spring Security
• SQL Server 2008 R2

前端技术栈

• Vue 3
• Element Plus
• Axios

关键技术点

1. 数据源路由：使用@DataSource注解指定数据源类型（COMMON/BRANCH）
2. 分页查询：使用Spring Data的Page和Pageable实现分页
3. 密码加密：使用MD5算法加密密码
4. 表单验证：前端使用Element Plus的表单验证规则
5. 权限控制：使用自定义注解@RequirePermission和Vue指令v-permission

注意事项

1. 数据源配置：用户管理功能使用COMMON数据源（tugboatcommon数据库）
2. 密码安全：密码必须使用MD5加密存储
3. 事务管理：删除用户和新增用户时需要使用@Transactional注解保证事务一致性
4. 级联删除：删除用户时需要同时删除用户角色关联记录
5. 输入验证：前端和后端都需要进行输入验证
6. 错误处理：所有操作都需要进行异常处理并返回友好的错误信息
7. 权限验证：所有接口都需要进行权限验证

开发规范

代码规范

• 所有方法都需要添加函数级注释
• 遵循Java和Vue的代码规范
• 使用Lombok简化代码
• 使用DTO进行数据传输

命名规范

• 实体类：使用驼峰命名法，如User、SysRole
• 数据库表：使用下划线命名法，如Sys_User、Sys_Role
• 接口路径：使用小写和连字符，如/user/list
• Vue组件：使用PascalCase命名法，如UserManagement

文件组织

• 后端代码按功能模块组织：controller、service、repository、dto、model
• 前端组件按功能模块组织：components目录下按功能分类

测试要点

1. 查询功能测试：测试各种查询条件组合
2. 新增功能测试：测试必填字段验证、密码一致性验证
3. 删除功能测试：测试单个删除和批量删除
4. 密码重置测试：测试密码一致性验证
5. 分页功能测试：测试分页切换和每页行数切换
6. 权限控制测试：测试不同权限用户的访问控制
7. 异常处理测试：测试各种异常情况的处理

后续优化建议

1. 批量导入：支持Excel批量导入用户
2. 批量导出：支持Excel批量导出用户
3. 用户详情：支持查看用户详细信息
4. 用户编辑：支持编辑用户信息
5. 密码策略：支持配置密码复杂度策略
6. 操作日志：记录用户管理操作日志
7. 数据统计：提供用户数据统计报表