aijianhua/backend/API接口文档.md

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

## 概述

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

## 基础信息

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

## 认证接口

### 用户注册

```http
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..."
  }
}
```

### 用户登录

```http
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..."
  }
}
```

## 用户接口

### 获取用户信息

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

### 更新用户信息

```http
PUT /users/{id}
```

**请求参数**:

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

## 商品接口

### 获取商品列表

```http
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
    }
  }
}
```

### 获取商品详情

```http
GET /products/{id}
```

## 订单接口

### 创建订单

```http
POST /orders
```

**请求参数**:

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

**items数组结构**:
```json
[
  {
    "product_id": 1,
    "quantity": 2
  }
]
```

## 花卉识别接口

### 花卉识别

```http
POST /identifications/identify
```

**请求格式**: `multipart/form-data`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| 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": "玫瑰是蔷薇科蔷薇属的植物，具有浓郁的芳香和美丽的花朵。"
    }
  }
}
```

### 获取识别历史

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