新增后台管理系统（答辩用

2026-06-24 05:07:32 +08:00
parent 2251f31524
commit 1f209e6761
98 changed files with 25099 additions and 0 deletions
@@ -0,0 +1,189 @@
+# 认证管理模块 API 文档
+
+> **文档版本**: v1.0
+> **创建日期**: 2026-06-16
+> **作者**: 张翔
+> **状态**: 正式发布
+
+---
+
+## 目录
+
+1. [概述](#概述)
+2. [基础路径](#基础路径)
+3. [认证接口](#认证接口)
+   - [用户名+密码登录](#用户名密码登录)
+   - [获取用户信息](#获取用户信息)
+4. [数据模型](#数据模型)
+   - [LoginRequest](#loginrequest)
+   - [LoginResponse](#loginresponse)
+   - [UserInfo](#userinfo)
+5. [响应码说明](#响应码说明)
+
+---
+
+## 概述
+
+认证管理模块提供用户登录认证和用户信息查询功能。采用 Spring WebFlux 响应式编程，支持高并发场景。
+
+## 基础路径
+
+所有接口的基础路径为: `http://{host}:{port}/api/auth`
+
+---
+
+## 认证接口
+
+### 用户名+密码登录
+
+| 属性 | 值 |
+|------|-----|
+| **HTTP方法** | POST |
+| **接口路径** | `/api/auth/login` |
+| **所属文件** | `AuthHandler.java` |
+
+**请求参数**:
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| username | string | 是 | - | 用户名 |
+| password | string | 是 | - | 密码 |
+
+**成功响应** (200 OK):
+
+```json
+{
+  "code": 200,
+  "message": "登录成功",
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "tokenType": "Bearer",
+    "expiresIn": 7200,
+    "userInfo": {
+      "id": 1,
+      "username": "admin",
+      "email": "admin@example.com",
+      "phone": "13800138000",
+      "nickname": "超级管理员",
+      "status": 1,
+      "roleId": 1
+    }
+  }
+}
+```
+
+**失败响应** (400 Bad Request):
+
+```json
+{
+  "code": 400,
+  "message": "用户名或密码错误"
+}
+```
+
+---
+
+### 获取用户信息
+
+| 属性 | 值 |
+|------|-----|
+| **HTTP方法** | GET |
+| **接口路径** | `/api/auth/users/{id}` |
+| **所属文件** | `AuthHandler.java` |
+
+**路径参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | Long | 是 | 用户ID |
+
+**成功响应** (200 OK):
+
+```json
+{
+  "code": 200,
+  "message": "获取用户信息成功",
+  "data": {
+    "id": 1,
+    "username": "admin",
+    "email": "admin@example.com",
+    "phone": "13800138000",
+    "nickname": "超级管理员",
+    "status": 1,
+    "roleId": 1
+  }
+}
+```
+
+**失败响应** (400 Bad Request):
+
+```json
+{
+  "code": 400,
+  "message": "无效的用户ID"
+}
+```
+
+---
+
+## 数据模型
+
+### LoginRequest
+
+用户登录请求对象。
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| username | string | 是 | 用户名 | admin |
+| password | string | 是 | 密码 | Test@123 |
+
+### LoginResponse
+
+用户登录响应对象。
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| accessToken | string | 访问令牌 | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
+| refreshToken | string | 刷新令牌 | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
+| tokenType | string | 令牌类型 | Bearer |
+| expiresIn | Long | 过期时间（秒） | 7200 |
+| userInfo | UserInfo | 用户信息 | - |
+
+### UserInfo
+
+用户信息对象。
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| id | Long | 用户ID | 1 |
+| username | string | 用户名 | admin |
+| email | string | 邮箱 | admin@example.com |
+| phone | string | 手机号 | 13800138000 |
+| nickname | string | 昵称 | 超级管理员 |
+| status | Integer | 状态：0-禁用，1-正常 | 1 |
+| roleId | Long | 角色ID | 1 |
+
+---
+
+## 响应码说明
+
+| 响应码 | 说明 |
+|--------|------|
+| 200 | 成功 |
+| 400 | 请求参数错误（如用户名密码错误、无效的用户ID） |
+| 401 | 未授权（认证失败） |
+| 403 | 禁止访问 |
+| 404 | 资源未找到 |
+| 409 | 冲突（如重复数据） |
+| 500 | 服务器内部错误 |
+
+---
+
+## 业务规则
+
+1. 登录成功后返回的 `accessToken` 用于后续接口的身份认证
+2. `accessToken` 有效期为 2 小时（7200 秒）
+3. `refreshToken` 用于刷新 `accessToken`，有效期为 7 天
+4. 用户状态 `status` 为 0 时表示禁用，无法登录
+5. 所有需要认证的接口需要在请求头中携带 `Authorization: Bearer {accessToken}`
@@ -0,0 +1,343 @@
+# 员工管理模块 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 | 排序号 |
@@ -0,0 +1,51 @@
+# soybean-admin-mock
+
+## Docs
+- [🦊一分钟，了解 Apifox ！](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/doc-2825188.md): 
+
+## API Docs
+- Auth [用户名+密码登录](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-100526985.md): 
+- Auth [获取用户信息](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-120399825.md): 
+- Auth [刷新token](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-120415125.md): 
+- Auth [自定义后端错误](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-158477619.md): 
+- 前端路由 [获取用户路由数据](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-120415303.md): 
+- 前端路由 [路由是否存在](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-120415373.md): 当用户访问一个路由失败时，有可能是没有该路由的权限，或者没有该路由，所以需要判断路由是否存在
+- 前端路由 [获取固定的路由数据(不需要权限)](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-158516240.md): 
+- 前端路由 [获取react用户路由](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-273820808.md): 
+- 调试 [debug](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-125438392.md): 
+- 调试 [debug post](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-134021864.md): 
+- 系统管理 [系统管理 - 获取角色列表](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-145344387.md): 
+- 系统管理 [系统管理 - 获取用户列表](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-149754769.md): 
+- 系统管理 [系统管理 - 获取用户列表(废弃)](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-145387463.md): 
+- 系统管理 [获取所有角色](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-145409928.md): 
+- 系统管理 [获取菜单列表](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-145421249.md): 
+- 系统管理 [系统管理 - 获取菜单列表](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-157945109.md): 
+- 系统管理 [获取所有页面组件](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-157988353.md): 
+- 系统管理 [获取菜单树](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-158414289.md): 
+- 项目配置 [获取用户配置](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-229492806.md): 
+- 项目配置 [保存用户配置](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-229493074.md): 
+- 用户 [postApiUsersLogin](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003433.md): 用户登录
+- 用户 [postApiUsersRegister](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003434.md): 用户注册
+- 用户 [getApiUsersProfile](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003435.md): 获取用户个人信息
+- 用户 [putApiUsersPassword](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003436.md): 更新用户密码
+- 用户 [postApiUsersLogout](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003437.md): 用户登出
+- 角色 [getApiRoles](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003438.md): 获取所有角色
+- 角色 [postApiRoles](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003439.md): 创建角色
+- 角色 [getApiRolesById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003440.md): 获取角色详情
+- 角色 [putApiRolesById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003441.md): 更新角色
+- 角色 [deleteApiRolesById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003442.md): 删除角色
+- 权限 [getApiPermissions](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003443.md): 获取所有权限
+- 权限 [postApiPermissions](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003444.md): 创建权限
+- 权限 [getApiPermissionsById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003445.md): 获取权限详情
+- 权限 [putApiPermissionsById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003446.md): 更新权限
+- 权限 [deleteApiPermissionsById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003447.md): 删除权限
+- 菜单 [getApiMenusUser](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003448.md): 获取用户菜单
+- 菜单 [getApiMenus](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003449.md): 获取所有菜单
+- 菜单 [postApiMenus](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003450.md): 创建菜单
+- 菜单 [getApiMenusById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003451.md): 获取菜单详情
+- 菜单 [putApiMenusById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003452.md): 更新菜单
+- 菜单 [deleteApiMenusById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003453.md): 删除菜单
+- 文件 [postApiFilesUpload](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003454.md): 上传文件
+- 文件 [getApiFilesById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003455.md): 获取文件信息
+- 文件 [deleteApiFilesById](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003456.md): 删除文件
+- 文件 [getApiFilesUser](https://s.apifox.cn/35c8727a-d3ab-47e9-8863-ef8e37df6887/api-281003457.md): 获取用户文件列表