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

18 KiB
Raw Blame History

爱鉴花小程序API接口文档

概述

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

基础信息

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

通用响应格式

成功响应

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

错误响应

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

错误码说明

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

认证接口

1. 用户注册

POST /auth/register

请求参数:

参数名 类型 必填 说明 示例
username string 是 用户名（3-20字符） "testuser"
password string 是 密码（最少6位） "123456"
phone string 是 手机号 "13800138000"
email string 否 邮箱 "user@example.com"
user_type string 否 用户类型 "farmer"

响应示例:

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

2. 用户登录

POST /auth/login

请求参数:

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

响应示例:

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

3. 获取当前用户信息

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

植物识别接口

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,
    "description": "玫瑰花，蔷薇科蔷薇属植物，具有浓郁的香气...",
    "care_tips": "喜阳光，需要充足的水分和肥料...",
    "related_products": [
      {
        "id": 1,
        "name": "玫瑰花束",
        "price": 29.9,
        "image": "/uploads/products/rose_bouquet.jpg"
      }
    ]
  }
}

2. 获取识别历史

GET /identifications/history

请求头:

Authorization: Bearer <token>

查询参数:

参数名 类型 说明
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": "2023-01-01T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 15,
      "pages": 2
    }
  }
}

商品接口

1. 获取商品列表

GET /products

查询参数:

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

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "products": [
      {
        "id": 1,
        "name": "玫瑰花束",
        "category_id": 1,
        "price": 29.9,
        "original_price": 39.9,
        "stock": 100,
        "image": "/uploads/products/rose_bouquet.jpg",
        "description": "新鲜玫瑰花束，香气浓郁，适合送礼",
        "category_name": "鲜花",
        "sales_count": 150,
        "rating": 4.8,
        "review_count": 45
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 12,
      "total": 50,
      "pages": 5
    }
  }
}

2. 获取商品详情

GET /products/{id}

路径参数:

参数名 类型 说明 示例
id integer 商品ID 1

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "玫瑰花束",
    "category_id": 1,
    "price": 29.9,
    "original_price": 39.9,
    "stock": 100,
    "images": [
      "/uploads/products/rose_bouquet_1.jpg",
      "/uploads/products/rose_bouquet_2.jpg"
    ],
    "description": "新鲜玫瑰花束，包含12朵红玫瑰...",
    "details": "花材：红玫瑰12朵\n包装：精美礼盒包装\n配送：同城2小时配送",
    "care_instructions": "放置在阴凉处，定期换水...",
    "category_name": "鲜花",
    "sales_count": 150,
    "rating": 4.8,
    "review_count": 45,
    "reviews": [
      {
        "user_name": "张*",
        "rating": 5,
        "content": "花很新鲜，包装精美",
        "created_at": "2023-01-01T10:00:00Z"
      }
    ]
  }
}

3. 获取商品分类

GET /categories

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "鲜花",
      "icon": "/icons/flowers.png",
      "product_count": 25
    },
    {
      "id": 2,
      "name": "盆栽",
      "icon": "/icons/potted_plants.png",
      "product_count": 18
    }
  ]
}

购物车接口

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. 创建订单

POST /orders

请求头:

Authorization: Bearer <token>

请求参数:

参数名 类型 必填 说明 示例
items array 是 商品列表 -
address_id integer 是 收货地址ID 1
coupon_code string 否 优惠券代码 "WELCOME10"
remark string 否 订单备注 "请下午配送"

items数组结构:

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

响应示例:

{
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "order_id": 1,
    "order_no": "ORDER202301010001",
    "total_amount": 59.8,
    "payment_amount": 59.8,
    "pay_url": "/pay/order/ORDER202301010001"
  }
}

2. 获取订单列表

GET /orders

请求头:

Authorization: Bearer <token>

查询参数:

参数名 类型 说明 示例
page integer 页码（默认1） 1
limit integer 每页数量（默认10） 10
status string 订单状态 "pending"

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "orders": [
      {
        "id": 1,
        "order_no": "ORDER202301010001",
        "total_amount": 59.8,
        "status": "pending",
        "status_text": "待支付",
        "created_at": "2023-01-01T10:00:00Z",
        "items": [
          {
            "product_name": "玫瑰花束",
            "product_image": "/uploads/products/rose_bouquet.jpg",
            "quantity": 2,
            "price": 29.9
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 5,
      "pages": 1
    }
  }
}

3. 获取订单详情

GET /orders/{id}

请求头:

Authorization: Bearer <token>

路径参数:

参数名 类型 说明 示例
id integer 订单ID 1

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "order_no": "ORDER202301010001",
    "total_amount": 59.8,
    "payment_amount": 59.8,
    "status": "paid",
    "status_text": "已支付",
    "shipping_address": {
      "recipient": "张三",
      "phone": "13800138000",
      "address": "北京市海淀区中关村大街1号"
    },
    "items": [
      {
        "product_id": 1,
        "product_name": "玫瑰花束",
        "product_image": "/uploads/products/rose_bouquet.jpg",
        "quantity": 2,
        "price": 29.9,
        "subtotal": 59.8
      }
    ],
    "payment_info": {
      "payment_method": "wechat",
      "payment_time": "2023-01-01T10:05:00Z",
      "transaction_id": "4200001234567890"
    },
    "shipping_info": {
      "shipping_method": "express",
      "tracking_number": "SF1234567890",
      "estimated_delivery": "2023-01-01T14:00:00Z"
    },
    "created_at": "2023-01-01T10:00:00Z",
    "paid_at": "2023-01-01T10:05:00Z"
  }
}

收货地址接口

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. 获取推广信息

GET /promotion/info

请求头:

Authorization: Bearer <token>

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "promotion_code": "PROMO123456",
    "qr_code_url": "/uploads/qrcodes/promo_123456.png",
    "promotion_url": "https://aijianhua.com/promo/PROMO123456",
    "total_invites": 15,
    "successful_orders": 8,
    "total_earnings": 120.5,
    "available_balance": 85.3,
    "withdrawn_amount": 35.2
  }
}

2. 获取推广记录

GET /promotion/records

请求头:

Authorization: Bearer <token>

查询参数:

参数名 类型 说明 示例
page integer 页码（默认1） 1
limit integer 每页数量（默认10） 10
type string 记录类型 "invite"

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "records": [
      {
        "id": 1,
        "type": "invite",
        "user_name": "李*",
        "phone": "138****0000",
        "amount": 10.0,
        "status": "completed",
        "created_at": "2023-01-01T10:00:00Z"
      },
      {
        "id": 2,
        "type": "order_commission",
        "user_name": "王*",
        "order_amount": 299.0,
        "amount": 29.9,
        "status": "pending",
        "created_at": "2023-01-02T14:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "pages": 3
    }
  }
}

3. 申请提现

POST /promotion/withdraw

请求头:

Authorization: Bearer <token>

请求参数:

参数名 类型 必填 说明 示例
amount number 是 提现金额 50.0
payment_method string 是 支付方式 "wechat"
account_info string 是 账户信息 "wx_1234567890"

响应示例:

{
  "code": 200,
  "message": "提现申请已提交",
  "data": {
    "withdraw_id": 1,
    "amount": 50.0,
    "status": "processing",
    "estimated_arrival": "2023-01-03T10:00:00Z"
  }
}

4. 获取提现记录

GET /promotion/withdrawals

请求头:

Authorization: Bearer <token>

查询参数:

参数名 类型 说明 示例
page integer 页码（默认1） 1
limit integer 每页数量（默认10） 10

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "withdrawals": [
      {
        "id": 1,
        "amount": 50.0,
        "payment_method": "wechat",
        "status": "completed",
        "completed_at": "2023-01-03T10:00:00Z",
        "created_at": "2023-01-01T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 5,
      "pages": 1
    }
  }
}

支付接口

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

本文档最后更新: 2024-01-15 API版本: v1.0