zyh/login_task_web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9ff0e7aa2df15502863b5ca6447dee51d73abe99
login_task_web/docs/接口文档.md

11 KiB
Raw Blame History

API 文档

用户管理接口

创建用户账户

管理员创建用户账户

接口地址： POST /api/admin/accounts

请求头：

Content-Type: application/json
Authorization: Bearer {token}

请求参数：

{
  "userType": "ADMIN",           // 必填，用户类型：ADMIN 或 AGENT
  "username": "newuser",         // 必填，用户名，3-64字符，只能包含字母、数字、下划线
  "password": "123456",          // 必填，密码，6-128字符
  "status": "ENABLED",           // 可选，状态：ENABLED 或 DISABLED，默认ENABLED
  "pointsBalance": 0             // 可选，积分余额（仅AGENT类型），默认0
}

成功响应（200）：

{
  "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 - 参数验证失败：

{
  "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 - 用户名已存在：

{
  "timestamp": "2025-08-24T18:30:00.000",
  "status": 409,
  "error": "Conflict",
  "message": "用户名已存在"
}

401 Unauthorized - 未授权：

{
  "timestamp": "2025-08-24T18:30:00.000",
  "status": 401,
  "error": "Unauthorized",
  "message": "访问被拒绝"
}

403 Forbidden - 权限不足：

{
  "timestamp": "2025-08-24T18:30:00.000",
  "status": 403,
  "error": "Forbidden",
  "message": "权限不足，无法创建用户"
}

用户自注册接口

接口地址： POST /api/users

请求头：

Content-Type: application/json

请求参数：

{
  "userType": "AGENT",           // 必填，用户类型：只能为 AGENT
  "username": "newagent",        // 必填，用户名，3-64字符
  "password": "123456",          // 必填，密码，6-128字符
  "pointsBalance": 0             // 可选，积分余额，默认0
}

成功响应（201）：

{
  "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. 简化的用户模型，去除了角色和显示名称等复杂字段

使用示例

创建管理员用户：

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!"
  }'

创建代理用户：

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
  }'

用户自注册：

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

请求参数：

{
  "newPassword": "NewPassword123!",  // 必填，新密码，6-128字符
  "forceLogout": true                // 可选，是否强制登出，默认true
}

成功响应（204）： 无响应体

错误响应：

400 Bad Request - 密码格式错误：

{
  "timestamp": "2025-08-24T18:30:00.000",
  "status": 400,
  "error": "Bad Request",
  "message": "新密码长度必须在6-128字符之间"
}

404 Not Found - 用户不存在：

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

获取用户列表

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)

创建用户

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）

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)

更新用户

import { updateUser } from '@/api/users'

const payload = {
  userType: 'AGENT',
  username: 'agent001',
  pointsBalance: 2000,
  status: 'ENABLED'
}

const response = await updateUser(userId, payload)

删除用户

import { deleteUser } from '@/api/users'

const response = await deleteUser(userId)

设置用户状态

import { setUserStatus } from '@/api/users'

// 启用用户
await setUserStatus(userId, true)

// 禁用用户
await setUserStatus(userId, false)

重置用户密码

import { resetUserPassword } from '@/api/users'

// 重置密码，需要指定新密码
const newPassword = 'NewPassword123!'
const forceLogout = true  // 是否强制登出，默认为true
const response = await resetUserPassword(userId, newPassword, forceLogout)

认证接口 (src/api/auth.js)

用户登录

import { login } from '@/api/auth'

const payload = {
  username: 'admin',
  password: 'admin123'
}

const response = await login(payload)
// 返回包含 accessToken 和 refreshToken 的数据

刷新令牌

import { refresh } from '@/api/auth'

const payload = {
  refreshToken: 'your-refresh-token'
}

const response = await refresh(payload)

用户登出

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. 错误显示: 前端自动显示后端返回的错误消息，支持字段级错误提示

错误处理机制

后端错误响应格式

{
  "timestamp": "2025-08-24T18:30:00.000",
  "status": 400,
  "error": "Bad Request",
  "message": "用户名已存在"
}

字段验证错误格式

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