aijianhua/admin-system/API接口文档.md

爱鉴花后台管理系统 API 接口文档

概述

本文档描述了爱鉴花后台管理系统的 RESTful API 接口规范，基于 OpenAPI 3.0 标准。

基础信息

• Base URL: http://localhost:3200/api/v1
• 认证方式: Bearer Token (JWT)
• 响应格式: JSON

通用响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

错误码说明

错误码	说明
200	成功
400	请求参数错误
401	未授权访问
403	权限不足
404	资源不存在
409	资源冲突
500	服务器内部错误

用户管理接口

1. 获取用户列表

接口摘要: 获取用户列表（需要管理员权限）

请求方法: GET 请求路径: /users

请求参数:

参数名	类型	必填	说明
page	integer	否	页码，默认1
limit	integer	否	每页数量，默认10
keyword	string	否	搜索关键词（用户名/手机号/邮箱）
user_type	string	否	用户类型（farmer/buyer/admin）

请求示例:

GET /api/v1/users?page=1&limit=10&keyword=test&user_type=farmer
Authorization: Bearer <token>

响应示例 (200):

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "phone": "13800138000",
        "email": "test@example.com",
        "user_type": "farmer",
        "avatar_url": null,
        "created_at": "2023-12-01 10:00:00",
        "last_login": "2023-12-15 15:30:00"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "pages": 10
    }
  }
}

2. 创建用户

接口摘要: 创建新用户（需要管理员权限）

请求方法: POST 请求路径: /users

请求体:

参数名	类型	必填	说明
username	string	是	用户名
phone	string	是	手机号
email	string	是	邮箱地址
user_type	string	是	用户类型（farmer/buyer/admin）
password	string	是	密码（最少6位）
real_name	string	否	真实姓名
avatar_url	string	否	头像URL

请求示例:

POST /api/v1/users
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": "newuser",
  "phone": "13900139000",
  "email": "newuser@example.com",
  "user_type": "buyer",
  "password": "123456",
  "real_name": "张三",
  "avatar_url": null
}

响应示例 (201):

{
  "code": 201,
  "message": "用户创建成功",
  "data": {
    "id": 2,
    "username": "newuser",
    "phone": "13900139000",
    "email": "newuser@example.com",
    "user_type": "buyer",
    "avatar_url": null,
    "real_name": "张三"
  }
}

错误响应示例 (409):

{
  "code": 409,
  "message": "用户名已存在",
  "data": null
}

3. 获取用户详情

接口摘要: 获取指定用户的详细信息

请求方法: GET 请求路径: /users/{id}

路径参数:

参数名	类型	必填	说明
id	integer	是	用户ID

请求示例:

GET /api/v1/users/1
Authorization: Bearer <token>

响应示例 (200):

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "phone": "13800138000",
    "email": "test@example.com",
    "user_type": "farmer",
    "avatar_url": null,
    "real_name": "测试用户",
    "created_at": "2023-12-01 10:00:00",
    "last_login": "2023-12-15 15:30:00"
  }
}

4. 更新用户信息

接口摘要: 更新用户信息

请求方法: PUT 请求路径: /users/{id}

路径参数:

参数名	类型	必填	说明
id	integer	是	用户ID

请求体:

参数名	类型	必填	说明
username	string	否	用户名
phone	string	否	手机号
email	string	否	邮箱地址
user_type	string	否	用户类型
real_name	string	否	真实姓名
avatar_url	string	否	头像URL

请求示例:

PUT /api/v1/users/1
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": "updateduser",
  "phone": "13800138001",
  "email": "updated@example.com",
  "user_type": "admin",
  "real_name": "更新用户"
}

响应示例 (200):

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "username": "updateduser",
    "phone": "13800138001",
    "email": "updated@example.com",
    "user_type": "admin",
    "avatar_url": null,
    "real_name": "更新用户"
  }
}

5. 删除用户

接口摘要: 删除用户（软删除，需要管理员权限）

请求方法: DELETE 请求路径: /users/{id}

路径参数:

参数名	类型	必填	说明
id	integer	是	用户ID

请求示例:

DELETE /api/v1/users/1
Authorization: Bearer <token>

响应示例 (200):

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

6. 修改密码

接口摘要: 修改用户密码

请求方法: PUT 请求路径: /users/{id}/password

路径参数:

参数名	类型	必填	说明
id	integer	是	用户ID

请求体:

参数名	类型	必填	说明
old_password	string	是	原密码
new_password	string	是	新密码（最少6位）

请求示例:

PUT /api/v1/users/1/password
Authorization: Bearer <token>
Content-Type: application/json

{
  "old_password": "oldpassword123",
  "new_password": "newpassword456"
}

响应示例 (200):

{
  "code": 200,
  "message": "密码修改成功",
  "data": null
}

认证接口

1. 用户登录

接口摘要: 用户登录获取访问令牌

请求方法: POST 请求路径: /auth/login

请求体:

参数名	类型	必填	说明
username	string	是	用户名
password	string	是	密码

请求示例:

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

响应示例 (200):

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "user_type": "admin"
    }
  }
}

2. 获取当前用户信息

接口摘要: 获取当前登录用户信息

请求方法: GET 请求路径: /users/me

请求示例:

GET /api/v1/users/me
Authorization: Bearer <token>

响应示例 (200):

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "phone": "13800138000",
    "email": "admin@example.com",
    "user_type": "admin",
    "avatar_url": null,
    "real_name": "管理员",
    "created_at": "2023-12-01 10:00:00",
    "last_login": "2023-12-15 15:30:00"
  }
}