coder-thin-template-backend/api/user/用户管理API.md

# 用户管理API

## 概述

用户管理模块提供系统用户的增删改查功能，包括用户信息管理、状态控制、密码管理、角色分配等核心功能。

## 权限说明

用户管理接口需要相应的权限才能访问：

| 操作 | 权限码 | 说明 |
|------|--------|------|
| 查询用户列表 | `system:user:list` | 查看用户列表权限 |
| 新增用户 | `system:user:add` | 新增用户权限 |
| 修改用户 | `system:user:edit` | 修改用户信息权限 |
| 删除用户 | `system:user:remove` | 删除用户权限 |
| 重置密码 | `system:user:resetPwd` | 重置用户密码权限 |
| 修改状态 | `system:user:status` | 修改用户状态权限 |
| 分配角色 | `system:user:role` | 分配用户角色权限 |
| 导入用户 | `system:user:import` | 导入用户数据权限 |
| 导出用户 | `system:user:export` | 导出用户数据权限 |

## 接口列表

### 1. 分页查询用户列表

**接口地址**: `GET /coder/sysLoginUser/listPage`

**接口描述**: 分页查询系统用户列表

**是否需要认证**: 是

**权限要求**: `system:user:list`

**请求头**:
```
Authorization: your-token-value
```

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| pageNo | Integer | 否 | 页码 | 1 |
| pageSize | Integer | 否 | 每页大小 | 10 |
| loginName | String | 否 | 登录账号 | admin |
| userName | String | 否 | 用户姓名 | 管理员 |
| userType | String | 否 | 用户类型 | 1 |
| phone | String | 否 | 手机号码 | 13800138000 |
| sex | String | 否 | 用户性别 | 1 |
| userStatus | String | 否 | 用户状态 | 0 |
| beginTime | String | 否 | 开始时间 | 2024-01-01 |
| endTime | String | 否 | 结束时间 | 2024-12-31 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "records": [
      {
        "userId": 1,
        "loginName": "admin",
        "userName": "管理员",
        "userType": "1",
        "email": "admin@example.com",
        "phone": "13800138000",
        "sex": "1",
        "avatar": "/upload/avatar/admin.jpg",
        "userStatus": "0",
        "loginIp": "127.0.0.1",
        "loginTime": "2024-01-01 10:00:00",
        "pwdUpdateTime": "2024-01-01 10:00:00",
        "remark": "系统管理员",
        "createBy": "admin",
        "createTime": "2024-01-01 10:00:00",
        "updateBy": "admin",
        "updateTime": "2024-01-01 10:00:00",
        "roleIds": [1, 2]
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X GET \
  "http://localhost:18099/coder/sysLoginUser/listPage?pageNo=1&pageSize=10&loginName=admin" \
  -H "Authorization: your-token-value"
```

---

### 2. 查询所有用户

**接口地址**: `GET /coder/sysLoginUser/list`

**接口描述**: 查询所有系统用户（不分页）

**是否需要认证**: 是

**权限要求**: `system:user:list`

**请求参数**: 同分页查询（除pageNo、pageSize外）

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "userId": 1,
      "loginName": "admin",
      "userName": "管理员",
      // 其他字段...
    }
  ],
  "traceId": "trace-123456"
}
```

---

### 3. 根据ID查询用户

**接口地址**: `GET /coder/sysLoginUser/getById/{id}`

**接口描述**: 根据用户ID查询用户详细信息

**是否需要认证**: 是

**权限要求**: `system:user:list`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 用户ID |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "userId": 1,
    "loginName": "admin",
    "userName": "管理员",
    "userType": "1",
    "email": "admin@example.com",
    "phone": "13800138000",
    "sex": "1",
    "avatar": "/upload/avatar/admin.jpg",
    "userStatus": "0",
    "loginIp": "127.0.0.1",
    "loginTime": "2024-01-01 10:00:00",
    "pwdUpdateTime": "2024-01-01 10:00:00",
    "remark": "系统管理员",
    "createBy": "admin",
    "createTime": "2024-01-01 10:00:00",
    "updateBy": "admin",
    "updateTime": "2024-01-01 10:00:00",
    "roleIds": [1, 2]
  },
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X GET \
  http://localhost:18099/coder/sysLoginUser/getById/1 \
  -H "Authorization: your-token-value"
```

---

### 4. 新增用户

**接口地址**: `POST /coder/sysLoginUser/add`

**接口描述**: 新增系统用户

**是否需要认证**: 是

**权限要求**: `system:user:add`

**请求参数**:

```json
{
  "loginName": "newuser",
  "userName": "新用户",
  "password": "123456",
  "userType": "1",
  "email": "newuser@example.com",
  "phone": "13800138001",
  "sex": "1",
  "userStatus": "0",
  "remark": "新用户备注",
  "roleIds": [2]
}
```

**请求参数说明**:

| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| loginName | String | 是 | 登录账号 | 3-16位字母数字 |
| userName | String | 是 | 用户姓名 | 不能为空 |
| password | String | 是 | 登录密码 | 不能为空 |
| userType | String | 是 | 用户类型 | 1-系统用户 2-注册用户 |
| email | String | 否 | 邮箱地址 | 邮箱格式验证 |
| phone | String | 否 | 手机号码 | 手机号格式验证 |
| sex | String | 否 | 用户性别 | 1-男 2-女 3-未知 |
| userStatus | String | 是 | 用户状态 | 0-启用 1-停用 |
| remark | String | 否 | 备注信息 | 最长200字符 |
| roleIds | Long[] | 否 | 角色ID数组 | 有效的角色ID |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "新增成功",
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/add \
  -H "Content-Type: application/json" \
  -H "Authorization: your-token-value" \
  -d '{
    "loginName": "newuser",
    "userName": "新用户",
    "password": "123456",
    "userType": "1",
    "email": "newuser@example.com",
    "phone": "13800138001",
    "sex": "1",
    "userStatus": "0",
    "remark": "新用户备注",
    "roleIds": [2]
  }'
```

---

### 5. 修改用户信息

**接口地址**: `POST /coder/sysLoginUser/update`

**接口描述**: 修改系统用户信息

**是否需要认证**: 是

**权限要求**: `system:user:edit`

**请求参数**:

```json
{
  "userId": 1,
  "loginName": "admin",
  "userName": "管理员",
  "userType": "1",
  "email": "admin@example.com",
  "phone": "13800138000",
  "sex": "1",
  "userStatus": "0",
  "remark": "系统管理员",
  "roleIds": [1, 2]
}
```

**请求参数说明**:

| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| userId | Long | 是 | 用户ID | 必须是有效的用户ID |
| loginName | String | 是 | 登录账号 | 3-16位字母数字 |
| userName | String | 是 | 用户姓名 | 不能为空 |
| userType | String | 是 | 用户类型 | 1-系统用户 2-注册用户 |
| email | String | 否 | 邮箱地址 | 邮箱格式验证 |
| phone | String | 否 | 手机号码 | 手机号格式验证 |
| sex | String | 否 | 用户性别 | 1-男 2-女 3-未知 |
| userStatus | String | 是 | 用户状态 | 0-启用 1-停用 |
| remark | String | 否 | 备注信息 | 最长200字符 |
| roleIds | Long[] | 否 | 角色ID数组 | 有效的角色ID |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "修改成功",
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/update \
  -H "Content-Type: application/json" \
  -H "Authorization: your-token-value" \
  -d '{
    "userId": 1,
    "loginName": "admin",
    "userName": "管理员",
    "userType": "1",
    "email": "admin@example.com",
    "phone": "13800138000",
    "sex": "1",
    "userStatus": "0",
    "remark": "系统管理员",
    "roleIds": [1, 2]
  }'
```

---

### 6. 删除用户

**接口地址**: `POST /coder/sysLoginUser/deleteById/{id}`

**接口描述**: 根据ID删除用户

**是否需要认证**: 是

**权限要求**: `system:user:remove`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 用户ID |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "删除成功",
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/deleteById/1 \
  -H "Authorization: your-token-value"
```

---

### 7. 批量删除用户

**接口地址**: `POST /coder/sysLoginUser/batchDelete`

**接口描述**: 批量删除用户

**是否需要认证**: 是

**权限要求**: `system:user:remove`

**请求参数**:

```json
{
  "ids": [1, 2, 3]
}
```

**请求参数说明**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | Long[] | 是 | 用户ID数组 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "删除成功",
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/batchDelete \
  -H "Content-Type: application/json" \
  -H "Authorization: your-token-value" \
  -d '{
    "ids": [1, 2, 3]
  }'
```

---

### 8. 修改用户状态

**接口地址**: `POST /coder/sysLoginUser/updateStatus/{userId}/{userStatus}`

**接口描述**: 修改用户状态（启用/停用）

**是否需要认证**: 是

**权限要求**: `system:user:status`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| userId | Long | 是 | 用户ID |
| userStatus | String | 是 | 用户状态（0-启用 1-停用） |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "修改成功",
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/updateStatus/1/0 \
  -H "Authorization: your-token-value"
```

---

### 9. 获取登录用户信息

**接口地址**: `GET /coder/sysLoginUser/getLoginUserInformation`

**接口描述**: 获取当前登录用户的详细信息

**是否需要认证**: 是

**权限要求**: 无（已登录用户可访问）

**请求参数**: 无

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "userId": 1,
    "loginName": "admin",
    "userName": "管理员",
    "userType": "1",
    "email": "admin@example.com",
    "phone": "13800138000",
    "sex": "1",
    "avatar": "/upload/avatar/admin.jpg",
    "userStatus": "0",
    "loginIp": "127.0.0.1",
    "loginTime": "2024-01-01 10:00:00",
    "pwdUpdateTime": "2024-01-01 10:00:00",
    "remark": "系统管理员",
    "createBy": "admin",
    "createTime": "2024-01-01 10:00:00",
    "updateBy": "admin",
    "updateTime": "2024-01-01 10:00:00",
    "roleIds": [1, 2],
    "roles": [
      {
        "roleId": 1,
        "roleName": "超级管理员",
        "roleCode": "admin"
      }
    ],
    "permissions": [
      "*:*:*"
    ]
  },
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X GET \
  http://localhost:18099/coder/sysLoginUser/getLoginUserInformation \
  -H "Authorization: your-token-value"
```

---

### 10. 获取个人资料

**接口地址**: `GET /coder/sysLoginUser/getPersonalData`

**接口描述**: 获取当前用户的个人资料

**是否需要认证**: 是

**权限要求**: 无（已登录用户可访问）

**请求参数**: 无

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "userId": 1,
    "loginName": "admin",
    "userName": "管理员",
    "email": "admin@example.com",
    "phone": "13800138000",
    "sex": "1",
    "avatar": "/upload/avatar/admin.jpg",
    "remark": "系统管理员"
  },
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X GET \
  http://localhost:18099/coder/sysLoginUser/getPersonalData \
  -H "Authorization: your-token-value"
```

---

### 11. 修改个人资料

**接口地址**: `POST /coder/sysLoginUser/updateBasicData`

**接口描述**: 修改当前用户的个人资料

**是否需要认证**: 是

**权限要求**: 无（已登录用户可访问）

**请求参数**:

```json
{
  "userName": "管理员",
  "email": "admin@example.com",
  "phone": "13800138000",
  "sex": "1",
  "avatar": "/upload/avatar/admin.jpg",
  "remark": "系统管理员"
}
```

**请求参数说明**:

| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| userName | String | 是 | 用户姓名 | 不能为空 |
| email | String | 否 | 邮箱地址 | 邮箱格式验证 |
| phone | String | 否 | 手机号码 | 手机号格式验证 |
| sex | String | 否 | 用户性别 | 1-男 2-女 3-未知 |
| avatar | String | 否 | 头像地址 | 有效的文件路径 |
| remark | String | 否 | 备注信息 | 最长200字符 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "修改成功",
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/updateBasicData \
  -H "Content-Type: application/json" \
  -H "Authorization: your-token-value" \
  -d '{
    "userName": "管理员",
    "email": "admin@example.com",
    "phone": "13800138000",
    "sex": "1",
    "avatar": "/upload/avatar/admin.jpg",
    "remark": "系统管理员"
  }'
```

---

### 12. 修改登录密码

**接口地址**: `POST /coder/sysLoginUser/updateUserPwd`

**接口描述**: 修改当前用户的登录密码

**是否需要认证**: 是

**权限要求**: 无（已登录用户可访问）

**请求参数**:

```json
{
  "oldPassword": "123456",
  "newPassword": "654321",
  "confirmPassword": "654321"
}
```

**请求参数说明**:

| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| oldPassword | String | 是 | 原密码 | 不能为空 |
| newPassword | String | 是 | 新密码 | 不能为空 |
| confirmPassword | String | 是 | 确认密码 | 必须与新密码一致 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "修改成功",
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/updateUserPwd \
  -H "Content-Type: application/json" \
  -H "Authorization: your-token-value" \
  -d '{
    "oldPassword": "123456",
    "newPassword": "654321",
    "confirmPassword": "654321"
  }'
```

---

### 13. 重置用户密码

**接口地址**: `POST /coder/sysLoginUser/resetPwd/{id}/{password}`

**接口描述**: 重置指定用户的密码

**是否需要认证**: 是

**权限要求**: `system:user:resetPwd`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 用户ID |
| password | String | 是 | 新密码 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": "重置成功",
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/resetPwd/1/123456 \
  -H "Authorization: your-token-value"
```

---

### 14. 下载用户导入模板

**接口地址**: `GET /coder/sysLoginUser/downloadExcelTemplate`

**接口描述**: 下载用户批量导入的Excel模板

**是否需要认证**: 是

**权限要求**: `system:user:import`

**请求参数**: 无

**响应**: Excel文件下载

**调用示例**:

```bash
curl -X GET \
  http://localhost:18099/coder/sysLoginUser/downloadExcelTemplate \
  -H "Authorization: your-token-value" \
  -o user_template.xlsx
```

---

### 15. 导出用户数据

**接口地址**: `GET /coder/sysLoginUser/exportExcelData`

**接口描述**: 导出用户数据到Excel

**是否需要认证**: 是

**权限要求**: `system:user:export`

**请求参数**: 同查询参数

**响应**: Excel文件下载

**调用示例**:

```bash
curl -X GET \
  "http://localhost:18099/coder/sysLoginUser/exportExcelData?userStatus=0" \
  -H "Authorization: your-token-value" \
  -o users.xlsx
```

---

### 16. 导入用户数据

**接口地址**: `POST /coder/sysLoginUser/importExcelData`

**接口描述**: 从Excel文件导入用户数据

**是否需要认证**: 是

**权限要求**: `system:user:import`

**请求参数**: 文件上传

**Content-Type**: `multipart/form-data`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | File | 是 | Excel文件 |
| updateSupport | Boolean | 否 | 是否更新已存在的用户 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "total": 100,
    "success": 95,
    "failed": 5,
    "message": "导入成功95条，失败5条"
  },
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X POST \
  http://localhost:18099/coder/sysLoginUser/importExcelData \
  -H "Authorization: your-token-value" \
  -F "file=@users.xlsx" \
  -F "updateSupport=true"
```

---

## 数据字典

### 用户类型 (userType)

| 值 | 说明 |
|----|------|
| 1 | 系统用户 |
| 2 | 注册用户 |
| 3 | 微信用户 |

### 用户性别 (sex)

| 值 | 说明 |
|----|------|
| 1 | 男 |
| 2 | 女 |
| 3 | 未知 |

### 用户状态 (userStatus)

| 值 | 说明 |
|----|------|
| 0 | 启用 |
| 1 | 停用 |

---

## 错误码说明

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 400 | 账号长度为 3-16 位 | 登录账号长度不符合要求 |
| 400 | 账号格式为数字以及字母 | 登录账号格式不正确 |
| 400 | 登录账号不能为空 | 登录账号为空 |
| 400 | 用户真实姓名不能为空 | 用户姓名为空 |
| 400 | 用户不存在 | 用户ID不存在 |
| 400 | 账号已存在 | 登录账号已被使用 |
| 400 | 手机号已存在 | 手机号已被使用 |
| 400 | 邮箱已存在 | 邮箱已被使用 |
| 400 | 不能删除当前用户 | 不能删除自己的账号 |
| 400 | 不能停用当前用户 | 不能停用自己的账号 |
| 400 | 原密码错误 | 修改密码时原密码不正确 |
| 400 | 新密码不能与原密码相同 | 新密码与原密码一致 |
| 400 | 两次输入的密码不一致 | 确认密码与新密码不一致 |
| 401 | 当前会话未登录 | 未登录或Token无效 |
| 403 | 权限不足 | 没有相应的操作权限 |
| 500 | 系统异常 | 服务器内部错误 |

---

## 注意事项

1. **权限验证**: 所有用户管理操作都需要相应的权限
2. **数据校验**: 新增和修改用户时会进行数据格式校验
3. **唯一性约束**: 登录账号、手机号、邮箱必须唯一
4. **密码安全**: 密码使用盐值加密存储
5. **操作日志**: 所有用户操作都会记录日志
6. **批量操作**: 批量删除时会跳过超级管理员账号
7. **Excel导入**: 支持Excel模板导入用户数据
8. **角色关联**: 用户删除时会自动删除角色关联关系
9. **会话管理**: 用户状态变更时会影响其登录会话
10. **数据完整性**: 删除用户前会检查关联数据