aiotagro/aijianhua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
40460f78d21b73152f3e1dd700832d1482595a29
aijianhua/docs/API接口文档.md

9.1 KiB
Raw Blame History

爱鉴花小程序后端API接口文档

概述

本文档详细描述了爱鉴花小程序后端RESTful API接口规范，基于OpenAPI 3.0标准。

基础信息

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

认证接口

用户注册

POST /auth/register

请求参数:

参数名 类型 必填 说明
username string 是 用户名
password string 是 密码（最少6位）
phone string 是 手机号
email string 否 邮箱
user_type string 否 用户类型（farmer/buyer/admin）

响应示例:

{
  "code": 201,
  "message": "注册成功",
  "data": {
    "user_id": 1,
    "username": "testuser",
    "phone": "13800138000",
    "email": "user@example.com",
    "user_type": "farmer",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

用户登录

POST /auth/login

请求参数:

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

响应示例:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": 1,
    "username": "testuser",
    "phone": "13800138000",
    "email": "user@example.com",
    "user_type": "farmer",
    "avatar_url": "/uploads/avatars/avatar.jpg",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

用户接口

获取用户信息

GET /users/me

请求头:

Authorization: Bearer <token>

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "phone": "13800138000",
    "email": "user@example.com",
    "user_type": "farmer",
    "avatar_url": "/uploads/avatars/avatar.jpg",
    "created_at": "2023-01-01T00:00:00Z",
    "last_login": "2023-01-01T00:00:00Z"
  }
}

更新用户信息

PUT /users/{id}

请求参数:

参数名 类型 必填 说明
email string 否 邮箱
real_name string 否 真实姓名
avatar_url string 否 头像URL

商品接口

获取商品列表

GET /products

查询参数:

参数名 类型 说明
page integer 页码（默认1）
limit integer 每页数量（默认12）
category_id integer 分类ID
keyword string 搜索关键词
min_price number 最低价格
max_price number 最高价格
sort_by string 排序字段（name/price/created_at/stock）
sort_order string 排序方向（asc/desc）

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "products": [
      {
        "id": 1,
        "name": "玫瑰花",
        "category_id": 1,
        "price": 29.9,
        "stock": 100,
        "image": "/uploads/products/rose.jpg",
        "description": "新鲜玫瑰花，香气浓郁",
        "category_name": "鲜花"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 12,
      "total": 50,
      "pages": 5
    }
  }
}

获取商品详情

GET /products/{id}

订单接口

创建订单

POST /orders

请求参数:

参数名 类型 必填 说明
items array 是 商品列表
shipping_address string 是 收货地址

items数组结构:

[
  {
    "product_id": 1,
    "quantity": 2
  }
]

花卉识别接口

花卉识别

POST /identifications/identify

请求格式: multipart/form-data

请求参数:

参数名 类型 必填 说明
image file 是 植物图片文件
user_id integer 否 用户ID（记录识别历史）

响应示例:

{
  "code": 200,
  "message": "识别成功",
  "data": {
    "identification_id": 1,
    "plant_name": "玫瑰花",
    "scientific_name": "Rosa rugosa",
    "family": "蔷薇科",
    "confidence": 0.92,
    "care_tips": "喜阳光，需要充足水分",
    "related_products": [
      {
        "id": 1,
        "name": "玫瑰花束",
        "price": 29.9,
        "image": "/uploads/products/rose.jpg"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z"
  }
}

获取识别历史

GET /identifications/history

查询参数:

参数名 类型 说明
user_id integer 用户ID
page integer 页码（默认1）
limit integer 每页数量（默认10）

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "identifications": [
      {
        "id": 1,
        "plant_name": "玫瑰花",
        "image_url": "/uploads/identifications/rose_123.jpg",
        "confidence": 0.92,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 15,
      "pages": 2
    }
  }
}

推广奖励接口

生成推广链接

POST /promotions/generate-link

请求头:

Authorization: Bearer <token>

响应示例:

{
  "code": 200,
  "message": "生成成功",
  "data": {
    "promotion_link": "https://aijianhua.com/register?ref=ABC123",
    "qr_code_url": "/uploads/qrcodes/ABC123.png",
    "expires_at": "2024-02-15T10:30:00Z"
  }
}

获取推广数据

GET /promotions/stats

查询参数:

参数名 类型 说明
start_date string 开始日期（YYYY-MM-DD）
end_date string 结束日期（YYYY-MM-DD）

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total_referrals": 50,
    "successful_orders": 25,
    "pending_rewards": 250.00,
    "withdrawn_rewards": 500.00,
    "available_balance": 250.00,
    "daily_stats": [
      {
        "date": "2024-01-15",
        "referrals": 5,
        "orders": 3,
        "rewards": 30.00
      }
    ]
  }
}

申请提现

POST /promotions/withdraw

请求参数:

参数名 类型 必填 说明
amount number 是 提现金额（≥50元）
bank_account string 是 银行账号
bank_name string 是 银行名称

响应示例:

{
  "code": 200,
  "message": "提现申请已提交",
  "data": {
    "withdrawal_id": 1,
    "amount": 100.00,
    "status": "pending",
    "estimated_arrival": "2024-01-16T10:30:00Z"
  }
}

获取提现记录

GET /promotions/withdrawals

查询参数:

参数名 类型 说明
page integer 页码（默认1）
limit integer 每页数量（默认10）
status string 状态（pending/completed/rejected）

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "withdrawals": [
      {
        "id": 1,
        "amount": 100.00,
        "status": "completed",
        "bank_account": "****1234",
        "bank_name": "中国银行",
        "created_at": "2024-01-15T10:30:00Z",
        "completed_at": "2024-01-16T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 5,
      "pages": 1
    }
  }
}

错误码规范

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

响应示例:

{
  "code": 200,
  "message": "识别成功",
  "data": {
    "identification_id": 1,
    "image_url": "/uploads/identifications/identify-123.jpg",
    "results": [
      {
        "name": "玫瑰",
        "confidence": 0.95,
        "scientificName": "Rosa rugosa",
        "description": "玫瑰是蔷薇科蔷薇属的植物，具有浓郁的芳香和美丽的花朵。"
      }
    ],
    "best_result": {
      "name": "玫瑰",
      "confidence": 0.95,
      "scientificName": "Rosa rugosa",
      "description": "玫瑰是蔷薇科蔷薇属的植物，具有浓郁的芳香和美丽的花朵。"
    }
  }
}

获取识别历史

GET /identifications

安全要求

  1. 所有敏感接口必须使用HTTPS
  2. JWT token有效期7天
  3. 密码使用bcrypt加密存储
  4. 文件上传限制10MB
  5. 支持CORS跨域访问

版本历史

  • v1.0.0 (2024-03-15): 初始版本发布
  • 包含用户认证、商品管理、订单管理、花卉识别等核心功能