login_task_web/docs/接口文档.md

# 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状态码提供友好的错误提示
- **降级处理**: 当无法获取具体错误时，显示默认错误消息