aijianhua/docs/API接口文档.md

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

## 概述

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

## 基础信息

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

## 通用响应格式

### 成功响应
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

### 错误响应
```json
{
  "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） |

**响应示例**:

```json
{
  "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 | 是 | 密码 |

**响应示例**:

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

**响应示例**:

```json
{
  "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） |

**响应示例**:

```json
{
  "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数组结构**:
```json
[
  {
    "product_id": 1,
    "quantity": 2
  }
]
```

## 购物车接口

### 1. 获取购物车

**GET** `/cart`

**请求头**:
```
Authorization: Bearer <token>
```

**响应示例**:
```json
{
  "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 |

**响应示例**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": {
    "cart_item_id": 1
  }
}
```

### 3. 更新购物车商品数量

**PUT** `/cart/items/{id}`

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:

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

**请求参数**:

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

**响应示例**:
```json
{
  "code": 200,
  "message": "更新成功"
}
```

### 4. 删除购物车商品

**DELETE** `/cart/items/{id}`

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:

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

**响应示例**:
```json
{
  "code": 200,
  "message": "删除成功"
}
```

## 收货地址接口

### 1. 获取收货地址列表

**GET** `/addresses`

**请求头**:
```
Authorization: Bearer <token>
```

**响应示例**:
```json
{
  "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 |

**响应示例**:
```json
{
  "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 |

**响应示例**:
```json
{
  "code": 200,
  "message": "更新成功"
}
```

### 4. 删除收货地址

**DELETE** `/addresses/{id}`

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:

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

**响应示例**:
```json
{
  "code": 200,
  "message": "删除成功"
}
```

## 支付接口

### 1. 发起支付

**POST** `/pay/orders/{order_no}`

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:

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

**响应示例**:
```json
{
  "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" |

**响应示例**:
```json
{
  "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" |

**响应示例**:
```json
{
  "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（记录识别历史） |

**响应示例**:
```json
{
  "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） |

**响应示例**:
```json
{
  "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>
```

**响应示例**:
```json
{
  "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） |

**响应示例**:
```json
{
  "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 | 是 | 银行名称 |

**响应示例**:
```json
{
  "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） |

**响应示例**:
```json
{
  "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 | 是 | 花卉图片文件 |

**响应示例**:

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