gym-manage/gym-manage-api/docs/employee-api.md

员工管理模块 API 文档

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

---

目录

1. 概述
2. 基础路径
3. 员工管理接口
   • 分页获取员工列表（含角色信息）
4. 用户管理接口（复用）
   • 创建员工账号
   • 获取员工详情
   • 更新员工信息
   • 逻辑删除员工
   • 修改密码
   • 为用户分配角色
   • 获取用户的角色
5. 角色管理接口（复用）
   • 获取所有角色
6. 数据模型
   • UserRegisterRequest
   • EmployeePageResponse
   • 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):

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

请求体:

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

成功响应 (201 Created):

{
  "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):

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

请求体:

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

请求体:

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

为用户分配角色

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

请求体:

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

获取用户的角色

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

---

角色管理接口（复用）

获取所有角色

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

成功响应 (200 OK):

[
  {
    "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	排序号