aijianhua/backend/API接口文档.md

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

概述

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

基础信息

• 基础URL: http://localhost:3000/api/v1
• 认证方式: Bearer Token (JWT)
• 数据格式: JSON
• 字符编码: UTF-8

认证接口

用户注册

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	是	花卉图片文件

响应示例:

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

错误码说明

错误码	说明
200	成功
201	创建成功
400	参数错误
401	未授权
403	禁止访问
404	资源不存在
409	资源冲突
500	服务器内部错误

安全要求

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

版本历史

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