# 用户管理

## 1. 功能概述

用户管理模块用于管理系统用户账号和角色权限，实现用户的增删改查、角色分配、密码管理以及权限配置功能。

**核心功能：**

- 用户账号管理：创建、编辑、删除用户账号
- 用户状态控制：启用/禁用用户账号
- 角色管理：创建、编辑、删除角色（用户组）
- 权限分配：为角色分配菜单和API权限
- 密码管理：修改密码、重置密码
- 用户数据导入导出：支持批量导入和导出用户数据

## 2. 术语说明

#### 2.1.1 用户管理术语

| 术语 | 定义 | 说明 |
|------|------|------|
| 用户组/角色 | 用户所属的权限分组 | 同一角色的用户拥有相同权限 |
| 出入证编号 | 用户的证件编号 | 用于门禁等场景 |
| 超级管理员 | 系统最高权限角色 | 默认拥有所有菜单权限 |
| is_all_menu | 是否拥有全部菜单权限 | 1表示拥有全部权限 |

## 3. 角色管理

### 3.1 角色列表查询

**查询条件：**

| 查询条件 | 说明 |
|---------|------|
| 状态 | 筛选启用或禁用状态的角色 |

**操作步骤：**

1. 进入【系统设置】→【用户管理】→【角色】
2. 在顶部查询区域选择状态条件
3. 点击【查询】按钮获取角色列表

### 3.2 新增角色

**操作步骤：**

1. 点击【新增角色】按钮
2. 填写角色名称和描述
3. 设置角色状态
4. 点击【确定】完成新增

**字段说明：**

| 字段 | 说明 | 必填 |
|------|------|------|
| 名称 | 角色名称，如"管理员"、"普通用户" | 是 |
| 描述 | 角色的详细说明 | 否 |
| 状态 | 启用或禁用 | 是 |

**【提示】** 角色名称不能重复。

### 3.3 编辑角色

**操作步骤：**

1. 在角色列表中点击需要编辑的角色
2. 修改角色信息
3. 点击【确定】保存更改

### 3.4 删除角色

**操作步骤：**

1. 在角色列表中找到需要删除的角色
2. 点击【删除】按钮
3. 在确认对话框中点击【确定】

**【重要】** 如果角色下存在用户，无法删除该角色。

### 3.5 权限分配

**操作步骤：**

1. 在角色列表中点击【权限配置】按钮
2. 在权限配置页面选择需要分配的菜单和API
3. 点击【确定】保存权限配置

**【提示】** 权限配置会覆盖角色原有的所有权限。

## 4. 用户管理

### 4.1 用户列表查询

**查询条件：**

| 查询条件 | 说明 |
|---------|------|
| 账号 | 按用户名模糊查询 |
| 姓名 | 按昵称模糊查询 |
| 用户组 | 按角色筛选 |
| 状态 | 筛选启用或禁用状态的用户 |

### 4.2 新增用户

**操作步骤：**

1. 点击【新增用户】按钮
2. 填写用户信息
3. 设置用户组和状态
4. 点击【确定】完成新增

**字段说明：**

| 字段 | 说明 | 必填 |
|------|------|------|
| 账号 | 用户登录账号 | 是 |
| 姓名 | 用户昵称或真实姓名 | 是 |
| 出入证编号 | 用户的证件编号 | 否 |
| 密码 | 用户登录密码 | 是 |
| 确认密码 | 再次输入密码确认 | 是 |
| 用户组 | 选择用户所属角色 | 是 |
| 状态 | 启用或禁用 | 是 |

**【注意】** 两次输入的密码必须一致，已删除或禁用的用户组无法选择。

### 4.3 编辑用户

**操作步骤：**

1. 在用户列表中点击需要编辑的用户
2. 修改用户信息
3. 点击【确定】保存更改

**【注意】** 不能禁用自己的账号。

### 4.4 删除用户

**操作步骤：**

1. 在用户列表中找到需要删除的用户
2. 点击【删除】按钮
3. 在确认对话框中点击【确定】

**【重要】** 不能删除自己的账号。

### 4.5 批量操作

**支持的批量操作：**

- 批量删除：选择多个用户后点击【批量删除】
- 批量启用/禁用：选择多个用户后点击【批量启用】或【批量禁用】

### 4.6 密码管理

#### 修改密码

**操作步骤：**

1. 在用户列表中点击【修改密码】按钮
2. 输入旧密码和新密码
3. 点击【确定】完成修改

#### 重置密码

**操作步骤：**

1. 在用户列表中点击【重置密码】按钮
2. 在确认对话框中点击【确定】
3. 密码将被重置为默认密码"123456"

### 4.7 用户数据导入导出

#### 导入用户数据

**操作步骤：**

1. 点击【下载导入模板】获取导入模板文件
2. 按照模板格式填写用户数据
3. 上传填写好的Excel文件
4. 点击【导入】完成批量导入

**导入模板字段：**

| 字段 | 说明 | 必填 |
|------|------|------|
| 账号 | 用户登录账号 | 是 |
| 姓名 | 用户昵称 | 是 |
| 出入证编号 | 用户证件编号 | 否 |
| 密码 | 用户密码 | 是 |
| 状态 | 启用或禁用 | 是 |
| 用户组 | 用户所属角色名称 | 是 |

#### 导出用户数据

**操作步骤：**

1. 设置查询条件筛选需要导出的用户
2. 点击【导出】按钮
3. 系统后台生成导出任务
4. 在下载管理中获取导出文件

## 5. 后台API接口

### 5.1 用户管理接口

| API路径 | 方法 | 功能描述 | 所属文件 |
|---------|------|---------|---------|
| `/api/background/v1/system_settings/user_management/user/all` | GET | 获取启用状态的用户列表 | UserService.php:44 |
| `/api/background/v1/system_settings/user_management/user/list` | GET | 获取用户列表(分页) | UserService.php:77 |
| `/api/background/v1/system_settings/user_management/user/create` | POST | 创建用户 | UserService.php:144 |
| `/api/background/v1/system_settings/user_management/user/edit` | POST | 编辑用户 | UserService.php:192 |
| `/api/background/v1/system_settings/user_management/user/delete` | POST | 删除用户 | UserService.php:239 |
| `/api/background/v1/system_settings/user_management/user/batch_delete` | POST | 批量删除用户 | UserService.php:269 |
| `/api/background/v1/system_settings/user_management/user/enable` | POST | 启用用户 | UserService.php:302 |
| `/api/background/v1/system_settings/user_management/user/disable` | POST | 禁用用户 | UserService.php:321 |
| `/api/background/v1/system_settings/user_management/user/update_pwd` | POST | 修改密码 | UserService.php:346 |
| `/api/background/v1/system_settings/user_management/user/reset_pwd` | POST | 重置密码 | UserService.php:372 |
| `/api/background/v1/system_settings/user_management/user/get_import_template` | GET | 获取导入模板 | UserService.php:392 |
| `/api/background/v1/system_settings/user_management/user/user_data_import` | POST | 导入用户数据 | UserService.php:458 |
| `/api/background/v1/system_settings/user_management/user/user_data_export_task` | POST | 创建导出任务 | UserService.php:515 |

### 5.2 角色管理接口

| API路径 | 方法 | 功能描述 | 所属文件 |
|---------|------|---------|---------|
| `/api/background/v1/system_settings/user_management/role/all` | GET | 获取启用状态的角色列表 | RoleService.php:55 |
| `/api/background/v1/system_settings/user_management/role/list` | GET | 获取角色列表(分页) | RoleService.php:81 |
| `/api/background/v1/system_settings/user_management/role/create` | POST | 创建角色 | RoleService.php:154 |
| `/api/background/v1/system_settings/user_management/role/edit` | POST | 编辑角色 | RoleService.php:185 |
| `/api/background/v1/system_settings/user_management/role/delete` | POST | 删除角色 | RoleService.php:218 |
| `/api/background/v1/system_settings/user_management/role/update_status` | POST | 更新角色状态 | RoleService.php:243 |
| `/api/background/v1/system_settings/user_management/role/get_role_menu` | GET | 获取角色权限 | RoleService.php:257 |
| `/api/background/v1/system_settings/user_management/role/give_role_menu` | POST | 分配角色权限 | RoleService.php:300 |

## 6. 数据模型

### 6.1 用户表

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | int | 用户唯一标识 |
| username | varchar | 登录账号 |
| password | varchar | 加密后的密码 |
| nickname | varchar | 用户昵称 |
| role_id | int | 所属角色ID |
| head_pic | varchar | 头像URL |
| pass_number | varchar | 出入证编号 |
| last_login | datetime | 最后登录时间 |
| last_ip | varchar | 最后登录IP |
| is_all_menu | tinyint | 是否拥有全部菜单权限 |
| status | tinyint | 状态(0禁用/1启用) |
| sort | int | 排序序号 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |

### 6.2 角色表

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | int | 角色唯一标识 |
| name | varchar | 角色名称 |
| description | varchar | 角色描述 |
| system | tinyint | 是否系统内置角色 |
| status | tinyint | 状态(0禁用/1启用) |
| sort | int | 排序序号 |

### 6.3 角色菜单关联表

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | int | 关联ID |
| role_id | int | 角色ID |
| menu_id | int | 菜单ID |
| module | varchar | 模块(admin/pda/api) |

## 7. 数据流程图

```mermaid
flowchart TD
    A[用户管理] --> B[新增用户]
    A --> C[编辑用户]
    A --> D[删除用户]
    A --> E[修改密码]
    
    B --> F{验证用户名唯一性}
    F -->|已存在| G[提示错误]
    F -->|不存在| H{验证密码一致性}
    H -->|不一致| I[提示错误]
    H -->|一致| J{验证角色有效性}
    J -->|无效| K[提示错误]
    J -->|有效| L[保存用户数据]
    
    C --> M{验证用户名唯一性}
    M -->|重复| N[提示错误]
    M -->|唯一| O{是否禁用自己}
    O -->|是| P[提示错误]
    O -->|否| Q[更新用户数据]
    
    D --> R{是否删除自己}
    R -->|是| S[提示错误]
    R -->|否| T[删除用户并重新排序]
    
    E --> U{验证密码一致性}
    U -->|不一致| V[提示错误]
    U -->|一致| W{新旧密码是否相同}
    W -->|相同| X[提示错误]
    W -->|不同| Y[更新密码]
```

## 8. 注意事项

**【重要】** 用户在进行删除或禁用操作时，不能操作自己的账号。

**【注意】** 删除或禁用角色前，请确保该角色下没有关联的用户。

**【提示】** 导入用户数据时，如果用户名已存在，该行数据将被跳过。