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

16 KiB
Raw Permalink Blame History

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

概述

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

基础信息

  • Base URL:
    • Node.js后端: http://localhost:3000/api/v1
    • Java后端: http://localhost:3200
  • 认证方式: Bearer Token (JWT)
  • 响应格式: JSON
  • 字符编码: UTF-8

通用响应格式

成功响应

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

错误响应

{
  "code": 400,
  "message": "参数错误",
  "error": "详细错误信息"
}

错误码说明

错误码 说明
200 成功
201 创建成功
400 参数错误
401 未授权
403 禁止访问
404 资源不存在
409 资源冲突
500 服务器内部错误
1001 识别失败
1002 图片格式不支持
2001 推广奖励不足
2002 提现频率限制
3001 库存不足
3002 订单状态异常

认证接口

用户注册

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

购物车接口

1. 获取购物车

GET /cart

请求头:

Authorization: Bearer <token>

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "product_name": "玫瑰花束",
        "product_image": "/uploads/products/rose_bouquet.jpg",
        "price": 29.9,
        "quantity": 2,
        "subtotal": 59.8,
        "stock": 100
      }
    ],
    "total_amount": 59.8,
    "total_quantity": 2
  }
}

2. 添加商品到购物车

POST /cart/items

请求头:

Authorization: Bearer <token>

请求参数:

参数名 类型 必填 说明 示例
product_id integer 是 商品ID 1
quantity integer 是 数量 2

响应示例:

{
  "code": 200,
  "message": "添加成功",
  "data": {
    "cart_item_id": 1
  }
}

3. 更新购物车商品数量

PUT /cart/items/{id}

请求头:

Authorization: Bearer <token>

路径参数:

参数名 类型 说明 示例
id integer 购物车项ID 1

请求参数:

参数名 类型 必填 说明 示例
quantity integer 是 数量 3

响应示例:

{
  "code": 200,
  "message": "更新成功"
}

4. 删除购物车商品

DELETE /cart/items/{id}

请求头:

Authorization: Bearer <token>

路径参数:

参数名 类型 说明 示例
id integer 购物车项ID 1

响应示例:

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

收货地址接口

1. 获取收货地址列表

GET /addresses

请求头:

Authorization: Bearer <token>

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "recipient": "张三",
      "phone": "13800138000",
      "province": "北京市",
      "city": "北京市",
      "district": "海淀区",
      "detail": "中关村大街1号",
      "is_default": true,
      "created_at": "2023-01-01T00:00:00Z"
    }
  ]
}

2. 添加收货地址

POST /addresses

请求头:

Authorization: Bearer <token>

请求参数:

参数名 类型 必填 说明 示例
recipient string 是 收货人 "张三"
phone string 是 手机号 "13800138000"
province string 是 省份 "北京市"
city string 是 城市 "北京市"
district string 是 区县 "海淀区"
detail string 是 详细地址 "中关村大街1号"
is_default boolean 否 是否默认 true

响应示例:

{
  "code": 201,
  "message": "添加成功",
  "data": {
    "address_id": 1
  }
}

3. 更新收货地址

PUT /addresses/{id}

请求头:

Authorization: Bearer <token>

路径参数:

参数名 类型 说明 示例
id integer 地址ID 1

请求参数:

参数名 类型 必填 说明 示例
recipient string 否 收货人 "张三"
phone string 否 手机号 "13800138000"
province string 否 省份 "北京市"
city string 否 城市 "北京市"
district string 否 区县 "海淀区"
detail string 否 详细地址 "中关村大街1号"
is_default boolean 否 是否默认 true

响应示例:

{
  "code": 200,
  "message": "更新成功"
}

4. 删除收货地址

DELETE /addresses/{id}

请求头:

Authorization: Bearer <token>

路径参数:

参数名 类型 说明 示例
id integer 地址ID 1

响应示例:

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

支付接口

1. 发起支付

POST /pay/orders/{order_no}

请求头:

Authorization: Bearer <token>

路径参数:

参数名 类型 说明 示例
order_no string 订单编号 "ORDER202301010001"

响应示例:

{
  "code": 200,
  "message": "支付参数生成成功",
  "data": {
    "payment_params": {
      "timeStamp": "1672531200",
      "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
      "package": "prepay_id=wx201410272009395522fsd8f8f8f8f8f8",
      "signType": "MD5",
      "paySign": "C380BEC2BFD727A4B6845133519F3AD6"
    }
  }
}

2. 查询支付结果

GET /pay/orders/{order_no}/status

请求头:

Authorization: Bearer <token>

路径参数:

参数名 类型 说明 示例
order_no string 订单编号 "ORDER202301010001"

响应示例:

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "order_no": "ORDER202301010001",
    "payment_status": "paid",
    "paid_amount": 59.8,
    "paid_at": "2023-01-01T10:05:00Z"
  }
}

文件上传接口

1. 上传文件

POST /upload

请求格式: multipart/form-data

请求参数:

参数名 类型 必填 说明 示例
file file 是 上传文件 -
type string 否 文件类型 "avatar"

响应示例:

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "/uploads/avatars/avatar_123.jpg",
    "filename": "avatar_123.jpg",
    "size": 102400,
    "mime_type": "image/jpeg"
  }
}

花卉识别接口

1. 花卉识别

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

2. 获取识别历史

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): 初始版本发布
  • 包含用户认证、商品管理、订单管理、花卉识别等核心功能