# 用户管理功能需求文档

## 功能概述

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

## 功能模块

### 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 | 是 | 每页行数 |

**响应示例**：

```json
{
  "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`

**响应示例**：

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

### 3. 获取状态列表

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

**响应示例**：

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

### 4. 新增用户

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

**请求参数**：

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

**响应示例**：

```json
{
  "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`

**请求参数**：

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

**响应示例**：

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

### 6. 重置密码

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

**请求参数**：

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

**响应示例**：

```json
{
  "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. **数据统计**：提供用户数据统计报表