# 员工管理模块 API 文档

> **文档版本**: v1.0
> **创建日期**: 2026-06-20
> **作者**: AI Assistant
> **状态**: 正式发布

---

## 目录

1. [概述](#概述)
2. [基础路径](#基础路径)
3. [员工管理接口](#员工管理接口)
   - [分页获取员工列表（含角色信息）](#分页获取员工列表含角色信息)
4. [用户管理接口（复用）](#用户管理接口复用)
   - [创建员工账号](#创建员工账号)
   - [获取员工详情](#获取员工详情)
   - [更新员工信息](#更新员工信息)
   - [逻辑删除员工](#逻辑删除员工)
   - [修改密码](#修改密码)
   - [为用户分配角色](#为用户分配角色)
   - [获取用户的角色](#获取用户的角色)
5. [角色管理接口（复用）](#角色管理接口复用)
   - [获取所有角色](#获取所有角色)
6. [数据模型](#数据模型)
   - [UserRegisterRequest](#userregisterrequest)
   - [EmployeePageResponse](#employeepageresponse)
   - [RoleInfo](#roleinfo)

---

## 概述

员工管理模块为店长（超级管理员 admin）提供新员工账号创建和权限分配功能。该模块复用已有的用户管理、角色管理接口，并新增了带角色信息的员工分页查询接口。

## 基础路径

所有接口的基础路径为: `http://{host}:{port}/api`

---

## 员工管理接口

### 分页获取员工列表（含角色信息）

> **新增接口**：该接口在已有 `/api/users/page` 基础上，额外返回每个员工的角色详细信息。

| 属性 | 值 |
|------|-----|
| **HTTP方法** | GET |
| **接口路径** | `/api/employees/page` |
| **所属文件** | `SysUserHandler.java` |

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| page | int | 否 | 0 | 页码（从0开始） |
| size | int | 否 | 10 | 每页数量 |
| sort | string | 否 | id | 排序字段 |
| order | string | 否 | asc | 排序方向（asc/desc） |
| keyword | string | 否 | - | 搜索关键字（匹配用户名/昵称） |

**成功响应** (200 OK):

```json
{
  "content": [
    {
      "id": 1,
      "username": "admin",
      "nickname": "超级管理员",
      "email": "admin@novalon.com",
      "phone": "13800138000",
      "avatar": null,
      "status": 1,
      "roles": [
        {
          "id": 1,
          "roleName": "超级管理员",
          "roleKey": "admin",
          "roleSort": 1
        }
      ],
      "createdAt": "2026-03-13T10:00:00",
      "updatedAt": "2026-03-13T10:00:00"
    }
  ],
  "totalPages": 1,
  "totalElements": 1,
  "currentPage": 0,
  "pageSize": 10,
  "first": true,
  "last": true
}
```

---

## 用户管理接口（复用）

以下接口为 `SysUserHandler` 中已有的用户管理接口，可直接用于员工管理。

### 创建员工账号

| 属性 | 值 |
|------|-----|
| **HTTP方法** | POST |
| **接口路径** | `/api/users` |
| **所属文件** | `SysUserHandler.java` |

**请求体**:

```json
{
  "username": "newstaff",
  "password": "Staff@123",
  "nickname": "新员工",
  "email": "staff@novalon.com",
  "phone": "13900139001",
  "roles": [2, 3]
}
```

**成功响应** (201 Created):

```json
{
  "id": 11,
  "username": "newstaff",
  "nickname": "新员工",
  "email": "staff@novalon.com",
  "phone": "13900139001",
  "status": 1,
  "createdAt": "2026-06-20T10:00:00",
  "updatedAt": "2026-06-20T10:00:00"
}
```

**校验规则**:
- `username`: 3-50位，只能包含字母、数字、下划线和横线
- `password`: 8-20位，必须包含大小写字母和数字
- `email`: 合法邮箱格式
- `phone`: 中国大陆手机号格式（1[3-9]开头的11位数字）

### 获取员工详情

| 属性 | 值 |
|------|-----|
| **HTTP方法** | GET |
| **接口路径** | `/api/users/{id}` |
| **所属文件** | `SysUserHandler.java` |

**成功响应** (200 OK):

```json
{
  "id": 1,
  "username": "admin",
  "nickname": "超级管理员",
  "email": "admin@novalon.com",
  "phone": "13800138000",
  "avatar": null,
  "status": 1,
  "roles": [1],
  "createdAt": "2026-03-13T10:00:00",
  "updatedAt": "2026-03-13T10:00:00"
}
```

### 更新员工信息

| 属性 | 值 |
|------|-----|
| **HTTP方法** | PUT |
| **接口路径** | `/api/users/{id}` |
| **所属文件** | `SysUserHandler.java` |

**请求体**:

```json
{
  "email": "newemail@novalon.com",
  "roleId": 2,
  "status": 1
}
```

### 逻辑删除员工

| 属性 | 值 |
|------|-----|
| **HTTP方法** | POST |
| **接口路径** | `/api/users/{id}/action/logical-delete` |
| **所属文件** | `SysUserHandler.java` |

### 修改密码

| 属性 | 值 |
|------|-----|
| **HTTP方法** | POST |
| **接口路径** | `/api/users/{id}/action/change-password` |
| **所属文件** | `SysUserHandler.java` |

**请求体**:

```json
{
  "oldPassword": "Old@123",
  "newPassword": "New@456"
}
```

### 为用户分配角色

| 属性 | 值 |
|------|-----|
| **HTTP方法** | POST |
| **接口路径** | `/api/users/{id}/roles` |
| **所属文件** | `SysUserHandler.java` |

**请求体**:

```json
{
  "roleIds": ["2", "3"]
}
```

### 获取用户的角色

| 属性 | 值 |
|------|-----|
| **HTTP方法** | GET |
| **接口路径** | `/api/users/{id}/roles` |
| **所属文件** | `SysUserHandler.java` |

---

## 角色管理接口（复用）

### 获取所有角色

| 属性 | 值 |
|------|-----|
| **HTTP方法** | GET |
| **接口路径** | `/api/roles` |
| **所属文件** | `SysRoleHandler.java` |

**成功响应** (200 OK):

```json
[
  {
    "id": 1,
    "roleName": "超级管理员",
    "roleKey": "admin",
    "roleSort": 1,
    "status": 1,
    "createdAt": "2026-03-13T10:00:00",
    "updatedAt": "2026-03-13T10:00:00"
  },
  {
    "id": 2,
    "roleName": "测试管理员",
    "roleKey": "test_admin",
    "roleSort": 2,
    "status": 1,
    "createdAt": "2026-03-13T10:00:00",
    "updatedAt": "2026-03-13T10:00:00"
  },
  {
    "id": 3,
    "roleName": "普通用户",
    "roleKey": "normal_user",
    "roleSort": 3,
    "status": 1,
    "createdAt": "2026-03-13T10:00:00",
    "updatedAt": "2026-03-13T10:00:00"
  },
  {
    "id": 4,
    "roleName": "访客",
    "roleKey": "guest",
    "roleSort": 4,
    "status": 1,
    "createdAt": "2026-03-13T10:00:00",
    "updatedAt": "2026-03-13T10:00:00"
  }
]
```

---

## 数据模型

### UserRegisterRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | String | 是 | 用户名（3-50位字母数字下划线横线） |
| password | String | 是 | 密码（8-20位含大小写字母和数字） |
| nickname | String | 否 | 昵称 |
| email | String | 是 | 邮箱 |
| phone | String | 是 | 手机号（中国大陆11位） |
| roles | List\<Long\> | 否 | 角色ID列表 |

### EmployeePageResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| content | List\<EmployeeInfo\> | 员工列表 |
| totalPages | int | 总页数 |
| totalElements | long | 总记录数 |
| currentPage | int | 当前页码 |
| pageSize | int | 每页数量 |
| first | boolean | 是否第一页 |
| last | boolean | 是否最后一页 |

### EmployeeInfo

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 用户ID |
| username | String | 用户名 |
| nickname | String | 昵称 |
| email | String | 邮箱 |
| phone | String | 手机号 |
| avatar | String | 头像URL |
| status | Integer | 状态：0-禁用, 1-正常 |
| roles | List\<RoleInfo\> | 角色列表 |
| createdAt | String | 创建时间 |
| updatedAt | String | 更新时间 |

### RoleInfo

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 角色ID |
| roleName | String | 角色名称 |
| roleKey | String | 角色标识 |
| roleSort | Integer | 排序号 |