aijianhua/docs/后台管理系统API文档.md

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

基于 OpenAPI 3.0 规范

基础信息

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

统一响应格式

所有接口都遵循以下响应格式：

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

认证接口

管理员登录

POST /auth/login

请求参数:

参数名	类型	必填	说明
login	string	是	用户名/手机号/邮箱
password	string	是	密码

响应示例:

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

用户管理接口

获取用户列表

GET /users

权限要求: 管理员

查询参数:

参数名	类型	必填	说明
page	number	否	页码，默认1
limit	number	否	每页数量，默认10
keyword	string	否	搜索关键词
user_type	string	否	用户类型过滤

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "phone": "13800138000",
        "email": "test@example.com",
        "user_type": "farmer",
        "created_at": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "pages": 10
    }
  }
}

获取用户详情

GET /users/{id}

路径参数:

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

删除用户

DELETE /users/{id}

权限要求: 管理员

商品管理接口

获取商品列表

GET /products

查询参数:

参数名	类型	必填	说明
page	number	否	页码，默认1
limit	number	否	每页数量，默认10
category_id	number	否	分类ID过滤
min_price	number	否	最低价格
max_price	number	否	最高价格
status	number	否	状态过滤

创建商品

POST /products

权限要求: 管理员

请求体:

{
  "name": "玫瑰花",
  "category_id": 1,
  "price": 29.9,
  "stock": 100,
  "image": "/uploads/roses.jpg",
  "description": "新鲜玫瑰花束"
}

订单管理接口

获取订单列表

GET /orders

权限要求: 管理员

查询参数:

参数名	类型	必填	说明
page	number	否	页码，默认1
limit	number	否	每页数量，默认10
status	number	否	订单状态过滤
start_date	string	否	开始日期
end_date	string	否	结束日期

更新订单状态

PUT /orders/{id}/status

权限要求: 管理员

请求体:

{
  "payment_status": 1,
  "shipping_status": 2
}

识别记录管理接口

获取识别记录列表

GET /identifications

权限要求: 管理员

查询参数:

参数名	类型	必填	说明
page	number	否	页码，默认1
limit	number	否	每页数量，默认10
start_date	string	否	开始日期
end_date	string	否	结束日期
min_confidence	number	否	最低置信度

数据统计接口

获取系统统计概览

GET /admin/statistics/overview

权限要求: 管理员

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total_users": 1000,
    "new_users_today": 10,
    "total_orders": 500,
    "total_revenue": 15000.50,
    "total_identifications": 2000,
    "active_users_today": 50
  }
}

获取趋势数据

GET /admin/statistics/trend

查询参数:

参数名	类型	必填	说明
days	number	否	天数，默认7
type	string	否	统计类型（users/orders/revenue/identifications）

系统配置接口

获取系统配置

GET /admin/config

权限要求: 管理员

更新系统配置

PUT /admin/config/{key}

权限要求: 管理员

请求体:

{
  "value": "new_value"
}

错误码说明

错误码	错误信息	说明
200	成功	请求成功
201	创建成功	资源创建成功
400	参数错误	请求参数验证失败
401	未授权	需要登录认证
403	禁止访问	权限不足
404	资源不存在	请求的资源不存在
409	资源冲突	资源已存在或状态冲突
500	服务器内部错误	服务器内部处理错误
1001	识别失败	植物识别处理失败
1002	图片格式不支持	上传的图片格式不支持
2001	推广奖励不足	可提现余额不足50元
2002	提现频率限制	24小时内只能提现一次
3001	库存不足	商品库存不足
3002	订单状态异常	订单状态不允许此操作

安全要求

1. 所有敏感操作需要管理员权限
2. API请求需要携带有效的JWT Token
3. 密码传输需要加密
4. 文件上传需要验证文件类型和大小

---

文档版本: 1.0.0
最后更新: 2024-03-15