添加 vue-router 依赖并配置路由，重构登录组件，完善 HTTP 请求拦截器以支持 token 刷新机制
This commit is contained in:
zyh
468
docs/接口文档.md
Normal file
468
docs/接口文档.md
Normal file
@@ -0,0 +1,468 @@
|
||||
# API 文档
|
||||
|
||||
## 用户管理接口
|
||||
|
||||
### 创建用户账户
|
||||
|
||||
#### 管理员创建用户账户
|
||||
|
||||
**接口地址：** `POST /api/admin/accounts`
|
||||
|
||||
**请求头：**
|
||||
```
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"userType": "ADMIN", // 必填，用户类型：ADMIN 或 AGENT
|
||||
"username": "newuser", // 必填，用户名，3-64字符，只能包含字母、数字、下划线
|
||||
"password": "123456", // 必填，密码，6-128字符
|
||||
"status": "ENABLED", // 可选，状态：ENABLED 或 DISABLED，默认ENABLED
|
||||
"pointsBalance": 0 // 可选，积分余额（仅AGENT类型），默认0
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应（200）：**
|
||||
```json
|
||||
{
|
||||
"id": 2,
|
||||
"userType": "ADMIN",
|
||||
"username": "newuser",
|
||||
"status": "ENABLED",
|
||||
"pointsBalance": 0,
|
||||
"createdAt": "2025-08-24T18:30:00.000",
|
||||
"updatedAt": "2025-08-24T18:30:00.000"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应：**
|
||||
|
||||
**400 Bad Request - 参数验证失败：**
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-24T18:30:00.000",
|
||||
"status": 400,
|
||||
"error": "Bad Request",
|
||||
"message": "Validation failed",
|
||||
"details": [
|
||||
{
|
||||
"field": "username",
|
||||
"message": "用户名长度必须在3-64字符之间"
|
||||
},
|
||||
{
|
||||
"field": "password",
|
||||
"message": "密码长度必须在6-128字符之间"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**409 Conflict - 用户名已存在：**
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-24T18:30:00.000",
|
||||
"status": 409,
|
||||
"error": "Conflict",
|
||||
"message": "用户名已存在"
|
||||
}
|
||||
```
|
||||
|
||||
**401 Unauthorized - 未授权：**
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-24T18:30:00.000",
|
||||
"status": 401,
|
||||
"error": "Unauthorized",
|
||||
"message": "访问被拒绝"
|
||||
}
|
||||
```
|
||||
|
||||
**403 Forbidden - 权限不足：**
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-24T18:30:00.000",
|
||||
"status": 403,
|
||||
"error": "Forbidden",
|
||||
"message": "权限不足，无法创建用户"
|
||||
}
|
||||
```
|
||||
|
||||
#### 用户自注册接口
|
||||
|
||||
**接口地址：** `POST /api/users`
|
||||
|
||||
**请求头：**
|
||||
```
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"userType": "AGENT", // 必填，用户类型：只能为 AGENT
|
||||
"username": "newagent", // 必填，用户名，3-64字符
|
||||
"password": "123456", // 必填，密码，6-128字符
|
||||
"pointsBalance": 0 // 可选，积分余额，默认0
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应（201）：**
|
||||
```json
|
||||
{
|
||||
"id": 3,
|
||||
"userType": "AGENT",
|
||||
"username": "newagent",
|
||||
"status": "ENABLED",
|
||||
"pointsBalance": 0,
|
||||
"createdAt": "2025-08-24T18:30:00.000",
|
||||
"updatedAt": "2025-08-24T18:30:00.000"
|
||||
}
|
||||
```
|
||||
|
||||
### 接口说明
|
||||
|
||||
#### 权限要求
|
||||
- **管理员接口** (`/api/admin/accounts`)：需要管理员权限，可以创建ADMIN和AGENT类型用户
|
||||
- **用户接口** (`/api/users`)：公开接口，只能创建AGENT类型用户
|
||||
|
||||
#### 参数说明
|
||||
|
||||
**userType（用户类型）：**
|
||||
- `ADMIN`：管理员用户
|
||||
- `AGENT`：代理用户
|
||||
|
||||
**username（用户名）：**
|
||||
- 长度：3-64字符
|
||||
- 格式：只能包含字母、数字、下划线
|
||||
- 唯一性：系统内必须唯一
|
||||
|
||||
**password（密码）：**
|
||||
- 长度：6-128字符
|
||||
- 存储：使用BCrypt加密存储
|
||||
- 安全：建议包含大小写字母、数字和特殊字符
|
||||
|
||||
**status（状态）：**
|
||||
- 可选值：`ENABLED`（启用）、`DISABLED`（禁用）
|
||||
- 默认值：`ENABLED`
|
||||
|
||||
**pointsBalance（积分余额）：**
|
||||
- 仅AGENT类型用户可以设置
|
||||
- 类型：整数，不能为负数
|
||||
- 默认值：0
|
||||
|
||||
#### 业务规则
|
||||
1. 用户名在系统内必须唯一
|
||||
2. 密码使用BCrypt加密存储，无法解密
|
||||
3. 创建成功后账户默认状态为ENABLED
|
||||
4. 只有管理员可以创建ADMIN类型用户
|
||||
5. 简化的用户模型，去除了角色和显示名称等复杂字段
|
||||
|
||||
#### 使用示例
|
||||
|
||||
**创建管理员用户：**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/admin/accounts \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer your-token" \
|
||||
-d '{
|
||||
"userType": "ADMIN",
|
||||
"username": "admin001",
|
||||
"password": "Admin123!"
|
||||
}'
|
||||
```
|
||||
|
||||
**创建代理用户：**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/admin/accounts \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer your-token" \
|
||||
-d '{
|
||||
"userType": "AGENT",
|
||||
"username": "agent001",
|
||||
"password": "Agent123!",
|
||||
"pointsBalance": 1000
|
||||
}'
|
||||
```
|
||||
|
||||
**用户自注册：**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/users \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"userType": "AGENT",
|
||||
"username": "newuser",
|
||||
"password": "User123!"
|
||||
}'
|
||||
```
|
||||
|
||||
### 重置密码接口
|
||||
|
||||
**接口地址：** `POST /api/admin/accounts/{id}/reset-password`
|
||||
|
||||
**请求头：**
|
||||
```
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**路径参数：**
|
||||
- `id`: 账户ID
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"newPassword": "NewPassword123!", // 必填，新密码，6-128字符
|
||||
"forceLogout": true // 可选，是否强制登出，默认true
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应（204）：** 无响应体
|
||||
|
||||
**错误响应：**
|
||||
|
||||
**400 Bad Request - 密码格式错误：**
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-24T18:30:00.000",
|
||||
"status": 400,
|
||||
"error": "Bad Request",
|
||||
"message": "新密码长度必须在6-128字符之间"
|
||||
}
|
||||
```
|
||||
|
||||
**404 Not Found - 用户不存在：**
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-24T18:30:00.000",
|
||||
"status": 404,
|
||||
"error": "Not Found",
|
||||
"message": "用户不存在"
|
||||
}
|
||||
```
|
||||
|
||||
### 启用/禁用用户接口
|
||||
|
||||
**启用用户：** `POST /api/admin/accounts/{id}/enable`
|
||||
**禁用用户：** `POST /api/admin/accounts/{id}/disable`
|
||||
|
||||
**请求头：**
|
||||
```
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**成功响应（204）：** 无响应体
|
||||
|
||||
## 前端接口调用说明
|
||||
|
||||
### 用户管理接口 (src/api/users.js)
|
||||
|
||||
#### 获取用户列表
|
||||
```javascript
|
||||
import { fetchUsers } from '@/api/users'
|
||||
|
||||
// 获取用户列表
|
||||
const params = {
|
||||
page: 1,
|
||||
size: 20, // 每页大小，默认20，最大200
|
||||
keyword: '搜索关键词', // 可选，搜索关键词
|
||||
userType: 'AGENT', // 可选，用户类型：ADMIN 或 AGENT
|
||||
status: 'ENABLED' // 可选，账户状态：ENABLED 或 DISABLED
|
||||
}
|
||||
const response = await fetchUsers(params)
|
||||
```
|
||||
|
||||
#### 创建用户
|
||||
```javascript
|
||||
import { createUser } from '@/api/users'
|
||||
|
||||
// 创建管理员用户
|
||||
const adminPayload = {
|
||||
userType: 'ADMIN',
|
||||
username: 'admin001',
|
||||
password: 'Admin123!',
|
||||
status: 'ENABLED'
|
||||
}
|
||||
|
||||
// 创建代理用户
|
||||
const agentPayload = {
|
||||
userType: 'AGENT',
|
||||
username: 'agent001',
|
||||
password: 'Agent123!',
|
||||
pointsBalance: 1000,
|
||||
status: 'ENABLED'
|
||||
}
|
||||
|
||||
const response = await createUser(adminPayload)
|
||||
```
|
||||
|
||||
#### 用户自注册（仅限AGENT）
|
||||
```javascript
|
||||
import { registerUser } from '@/api/users'
|
||||
|
||||
// 用户自注册（公开接口，无需权限）
|
||||
const agentPayload = {
|
||||
userType: 'AGENT', // 必填，只能为 AGENT
|
||||
username: 'newagent', // 必填，用户名，3-64字符
|
||||
password: 'Agent123!', // 必填，密码，6-128字符
|
||||
pointsBalance: 0 // 可选，积分余额，默认0
|
||||
}
|
||||
|
||||
const response = await registerUser(agentPayload)
|
||||
```
|
||||
|
||||
#### 更新用户
|
||||
```javascript
|
||||
import { updateUser } from '@/api/users'
|
||||
|
||||
const payload = {
|
||||
userType: 'AGENT',
|
||||
username: 'agent001',
|
||||
pointsBalance: 2000,
|
||||
status: 'ENABLED'
|
||||
}
|
||||
|
||||
const response = await updateUser(userId, payload)
|
||||
```
|
||||
|
||||
#### 删除用户
|
||||
```javascript
|
||||
import { deleteUser } from '@/api/users'
|
||||
|
||||
const response = await deleteUser(userId)
|
||||
```
|
||||
|
||||
#### 设置用户状态
|
||||
```javascript
|
||||
import { setUserStatus } from '@/api/users'
|
||||
|
||||
// 启用用户
|
||||
await setUserStatus(userId, true)
|
||||
|
||||
// 禁用用户
|
||||
await setUserStatus(userId, false)
|
||||
```
|
||||
|
||||
#### 重置用户密码
|
||||
```javascript
|
||||
import { resetUserPassword } from '@/api/users'
|
||||
|
||||
// 重置密码，需要指定新密码
|
||||
const newPassword = 'NewPassword123!'
|
||||
const forceLogout = true // 是否强制登出，默认为true
|
||||
const response = await resetUserPassword(userId, newPassword, forceLogout)
|
||||
```
|
||||
|
||||
### 认证接口 (src/api/auth.js)
|
||||
|
||||
#### 用户登录
|
||||
```javascript
|
||||
import { login } from '@/api/auth'
|
||||
|
||||
const payload = {
|
||||
username: 'admin',
|
||||
password: 'admin123'
|
||||
}
|
||||
|
||||
const response = await login(payload)
|
||||
// 返回包含 accessToken 和 refreshToken 的数据
|
||||
```
|
||||
|
||||
#### 刷新令牌
|
||||
```javascript
|
||||
import { refresh } from '@/api/auth'
|
||||
|
||||
const payload = {
|
||||
refreshToken: 'your-refresh-token'
|
||||
}
|
||||
|
||||
const response = await refresh(payload)
|
||||
```
|
||||
|
||||
#### 用户登出
|
||||
```javascript
|
||||
import { logout } from '@/api/auth'
|
||||
|
||||
const response = await logout()
|
||||
```
|
||||
|
||||
### 前端表单字段映射
|
||||
|
||||
#### 用户列表查询参数
|
||||
- `page`: 页码，默认1
|
||||
- `size`: 每页大小，默认20，最大200（前端使用pageSize，传参时转换为size）
|
||||
- `keyword`: 搜索关键词（用户名）
|
||||
- `userType`: 用户类型筛选 (ADMIN/AGENT)
|
||||
- `status`: 状态筛选 (ENABLED/DISABLED)
|
||||
|
||||
#### 用户创建/编辑表单字段
|
||||
- `userType`: 用户类型 (ADMIN/AGENT)
|
||||
- `username`: 用户名
|
||||
- `password`: 密码 (仅创建时)
|
||||
- `enabled`: 状态 (true/false，转换为ENABLED/DISABLED)
|
||||
- `pointsBalance`: 积分余额 (仅AGENT类型)
|
||||
|
||||
#### 后端返回数据字段
|
||||
- `status`: 用户状态 (ENABLED/DISABLED)
|
||||
- `enabled`: 兼容字段，部分接口可能返回 (true/false)
|
||||
|
||||
#### 表单验证规则
|
||||
- `userType`: 必填
|
||||
- `username`: 必填，3-64字符
|
||||
- `password`: 创建时必填，最少6位
|
||||
- `pointsBalance`: 仅AGENT类型必填，非负整数
|
||||
|
||||
### 注意事项
|
||||
|
||||
1. **接口路径**: 所有用户管理接口都使用 `/api/admin/accounts` 前缀
|
||||
2. **权限控制**:
|
||||
- 需要有效的 Bearer Token
|
||||
- 只有 ADMIN 类型用户可以访问用户管理功能
|
||||
- AGENT 类型用户无法访问用户管理页面和接口
|
||||
3. **状态字段**:
|
||||
- 前端表单使用 `enabled` (boolean)，提交时转换为 `status` (ENABLED/DISABLED)
|
||||
- 后端返回使用 `status` (ENABLED/DISABLED)，前端显示时需要转换
|
||||
4. **积分余额**: 仅AGENT类型用户可以设置积分余额
|
||||
5. **简化模型**: 去除了角色和显示名称字段，简化了用户管理
|
||||
6. **错误处理**: 统一使用HTTP状态码和错误消息处理
|
||||
7. **错误显示**: 前端自动显示后端返回的错误消息，支持字段级错误提示
|
||||
|
||||
### 错误处理机制
|
||||
|
||||
#### 后端错误响应格式
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-24T18:30:00.000",
|
||||
"status": 400,
|
||||
"error": "Bad Request",
|
||||
"message": "用户名已存在"
|
||||
}
|
||||
```
|
||||
|
||||
#### 字段验证错误格式
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-24T18:30:00.000",
|
||||
"status": 400,
|
||||
"error": "Bad Request",
|
||||
"message": "Validation failed",
|
||||
"details": [
|
||||
{
|
||||
"field": "username",
|
||||
"message": "用户名长度必须在3-64字符之间"
|
||||
},
|
||||
{
|
||||
"field": "password",
|
||||
"message": "密码长度必须在6-128字符之间"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 前端错误处理
|
||||
- **全局拦截**: HTTP拦截器自动显示错误消息
|
||||
- **字段级错误**: 支持显示具体的字段验证错误
|
||||
- **状态码映射**: 根据HTTP状态码提供友好的错误提示
|
||||
- **降级处理**: 当无法获取具体错误时，显示默认错误消息
|
||||
Reference in New Issue
Block a user