# 商城服务API设计文档

## 1. 概述

本文档详细描述了商城服务(mall-service)提供的API接口，包括商品管理、购物车、订单、优惠券等核心功能。

## 2. 基础信息

- 基础路径: `/api/v1/mall`
- 版本: v1
- 通信协议: HTTP/HTTPS
- 数据格式: JSON
- 状态码: 遵循HTTP状态码规范

## 3. 全局Headers

| Header名称 | 是否必填 | 描述 |
|------------|----------|------|
| Authorization | 是 | Bearer Token认证信息 |
| Content-Type | 是 | application/json |

## 4. 全局响应格式

### 4.1 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

### 4.2 错误响应
```json
{
  "code": 40001,
  "message": "错误描述",
  "data": null
}
```

## 5. 商品管理接口

### 5.1 获取商品分类列表

**接口地址**: `GET /categories`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| parent_id | integer | 否 | 父分类ID，0表示获取顶级分类 |
| status | string | 否 | 状态(ACTIVE/INACTIVE) |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| items | array | 分类列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "农资",
        "parent_id": 0,
        "level": 1,
        "sort_order": 1,
        "icon": "https://example.com/icon1.png",
        "description": "农资产品分类",
        "status": "ACTIVE",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}
```

### 5.2 获取商品列表

**接口地址**: `GET /products`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| category_id | integer | 否 | 分类ID |
| keyword | string | 否 | 搜索关键词 |
| is_featured | boolean | 否 | 是否推荐 |
| is_new | boolean | 否 | 是否新品 |
| status | string | 否 | 商品状态(ACTIVE等) |
| sort_by | string | 否 | 排序字段(price_asc/price_desc/sales_count) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 商品列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1,
        "category_id": 1,
        "seller_id": 12345,
        "name": "优质小麦种子",
        "subtitle": "高产抗病小麦品种",
        "cover_image": "https://example.com/image1.jpg",
        "price": 25.00,
        "original_price": 30.00,
        "stock_quantity": 1000,
        "sales_count": 50,
        "status": "ACTIVE",
        "is_featured": true,
        "is_new": true,
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}
```

### 5.3 获取商品详情

**接口地址**: `GET /products/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 商品ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 商品ID |
| category | object | 分类信息 |
| seller | object | 卖家信息 |
| name | string | 商品名称 |
| subtitle | string | 商品副标题 |
| description | string | 商品描述 |
| cover_image | string | 封面图片URL |
| images | array | 商品图片URL列表 |
| price | number | 商品价格 |
| original_price | number | 原价 |
| cost_price | number | 成本价 |
| stock_quantity | integer | 库存数量 |
| sales_count | integer | 销售数量 |
| status | string | 商品状态 |
| is_featured | boolean | 是否推荐 |
| is_new | boolean | 是否新品 |
| tags | array | 商品标签 |
| attributes | object | 商品属性 |
| specifications | object | 商品规格 |
| reviews | array | 商品评价列表 |
| created_at | string | 创建时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "category": {
      "id": 1,
      "name": "农资"
    },
    "seller": {
      "id": 12345,
      "name": "张三种子店"
    },
    "name": "优质小麦种子",
    "subtitle": "高产抗病小麦品种",
    "description": "详细商品描述...",
    "cover_image": "https://example.com/image1.jpg",
    "images": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "price": 25.00,
    "original_price": 30.00,
    "cost_price": 20.00,
    "stock_quantity": 1000,
    "sales_count": 50,
    "status": "ACTIVE",
    "is_featured": true,
    "is_new": true,
    "tags": ["高产", "抗病"],
    "attributes": {
      "品种": "鲁麦2号",
      "净含量": "1公斤"
    },
    "specifications": {
      "包装规格": "1公斤/袋"
    },
    "reviews": [
      {
        "id": 1,
        "user": {
          "id": 54321,
          "name": "李四"
        },
        "rating": 5,
        "content": "种子质量很好，发芽率高",
        "images": [],
        "created_at": "2024-01-10T00:00:00Z"
      }
    ],
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

## 6. 购物车接口

### 6.1 添加商品到购物车

**接口地址**: `POST /cart/items`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 商品ID |
| quantity | integer | 是 | 商品数量 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 购物车项ID |
| user_id | integer | 用户ID |
| product | object | 商品信息 |
| quantity | integer | 商品数量 |
| selected | boolean | 是否选中 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "product_id": 1,
  "quantity": 2
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "product": {
      "id": 1,
      "name": "优质小麦种子",
      "price": 25.00,
      "cover_image": "https://example.com/image1.jpg"
    },
    "quantity": 2,
    "selected": true,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.2 获取购物车列表

**接口地址**: `GET /cart/items`

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| items | array | 购物车项列表 |
| total_amount | number | 总金额 |
| selected_amount | number | 选中商品总金额 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1001,
        "product": {
          "id": 1,
          "name": "优质小麦种子",
          "price": 25.00,
          "cover_image": "https://example.com/image1.jpg"
        },
        "quantity": 2,
        "selected": true,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "total_amount": 50.00,
    "selected_amount": 50.00
  }
}
```

### 6.3 更新购物车项

**接口地址**: `PUT /cart/items/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 购物车项ID |
| quantity | integer | 否 | 商品数量 |
| selected | boolean | 否 | 是否选中 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 购物车项ID |
| product | object | 商品信息 |
| quantity | integer | 商品数量 |
| selected | boolean | 是否选中 |
| updated_at | string | 更新时间 |

**示例请求**:
```json
{
  "quantity": 3,
  "selected": true
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "product": {
      "id": 1,
      "name": "优质小麦种子",
      "price": 25.00,
      "cover_image": "https://example.com/image1.jpg"
    },
    "quantity": 3,
    "selected": true,
    "updated_at": "2024-01-15T11:00:00Z"
  }
}
```

### 6.4 删除购物车项

**接口地址**: `DELETE /cart/items/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 购物车项ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| message | string | 删除结果信息 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "购物车项删除成功"
  }
}
```

## 7. 订单接口

### 7.1 创建订单

**接口地址**: `POST /orders`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| shipping_address_id | integer | 是 | 收货地址ID |
| coupon_id | integer | 否 | 优惠券ID |
| remark | string | 否 | 订单备注 |
| items | array | 是 | 订单项列表 |

**items元素结构**:

| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 商品ID |
| quantity | integer | 是 | 商品数量 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 订单ID |
| order_number | string | 订单编号 |
| total_amount | number | 订单总金额 |
| discount_amount | number | 优惠金额 |
| shipping_amount | number | 运费 |
| actual_amount | number | 实际支付金额 |
| status | string | 订单状态 |
| shipping_address | object | 收货地址 |
| items | array | 订单项列表 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "shipping_address_id": 1,
  "remark": "请尽快发货",
  "items": [
    {
      "product_id": 1,
      "quantity": 2
    }
  ]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "order_number": "ORD202401150001",
    "total_amount": 50.00,
    "discount_amount": 0.00,
    "shipping_amount": 0.00,
    "actual_amount": 50.00,
    "status": "PENDING_PAYMENT",
    "shipping_address": {
      "id": 1,
      "name": "张三",
      "phone": "13800138000",
      "province": "北京市",
      "city": "北京市",
      "district": "朝阳区",
      "detail_address": "某街道某号"
    },
    "items": [
      {
        "id": 3001,
        "product_id": 1,
        "product_name": "优质小麦种子",
        "product_image": "https://example.com/image1.jpg",
        "quantity": 2,
        "price": 25.00,
        "total_amount": 50.00
      }
    ],
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 7.2 获取订单列表

**接口地址**: `GET /orders`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 订单状态 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 订单列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 5,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 2001,
        "order_number": "ORD202401150001",
        "total_amount": 50.00,
        "actual_amount": 50.00,
        "status": "PAID",
        "shipping_address": {
          "name": "张三",
          "phone": "13800138000",
          "detail_address": "北京市朝阳区某街道某号"
        },
        "items": [
          {
            "product_name": "优质小麦种子",
            "product_image": "https://example.com/image1.jpg",
            "quantity": 2,
            "price": 25.00
          }
        ],
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 7.3 获取订单详情

**接口地址**: `GET /orders/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 订单ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 订单ID |
| order_number | string | 订单编号 |
| user | object | 买家信息 |
| seller | object | 卖家信息 |
| total_amount | number | 订单总金额 |
| discount_amount | number | 优惠金额 |
| shipping_amount | number | 运费 |
| actual_amount | number | 实际支付金额 |
| status | string | 订单状态 |
| payment_method | string | 支付方式 |
| payment_time | string | 支付时间 |
| shipping_address | object | 收货地址 |
| shipping_company | string | 物流公司 |
| shipping_number | string | 物流单号 |
| remark | string | 订单备注 |
| items | array | 订单项列表 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "order_number": "ORD202401150001",
    "user": {
      "id": 12345,
      "name": "张三"
    },
    "seller": {
      "id": 54321,
      "name": "张三种子店"
    },
    "total_amount": 50.00,
    "discount_amount": 0.00,
    "shipping_amount": 0.00,
    "actual_amount": 50.00,
    "status": "SHIPPED",
    "payment_method": "微信支付",
    "payment_time": "2024-01-15T11:00:00Z",
    "shipping_address": {
      "id": 1,
      "name": "张三",
      "phone": "13800138000",
      "province": "北京市",
      "city": "北京市",
      "district": "朝阳区",
      "detail_address": "某街道某号"
    },
    "shipping_company": "顺丰快递",
    "shipping_number": "SF1234567890",
    "remark": "请尽快发货",
    "items": [
      {
        "id": 3001,
        "product_id": 1,
        "product_name": "优质小麦种子",
        "product_image": "https://example.com/image1.jpg",
        "quantity": 2,
        "price": 25.00,
        "total_amount": 50.00
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:00:00Z"
  }
}
```

### 7.4 取消订单

**接口地址**: `PUT /orders/{id}/cancel`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 订单ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 订单ID |
| status | string | 更新后的订单状态 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "status": "CANCELLED",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}
```

## 8. 收货地址接口

### 8.1 添加收货地址

**接口地址**: `POST /addresses`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 收货人姓名 |
| phone | string | 是 | 联系电话 |
| province | string | 是 | 省份 |
| city | string | 是 | 城市 |
| district | string | 是 | 区县 |
| detail_address | string | 是 | 详细地址 |
| is_default | boolean | 否 | 是否默认地址 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 地址ID |
| user_id | integer | 用户ID |
| name | string | 收货人姓名 |
| phone | string | 联系电话 |
| province | string | 省份 |
| city | string | 城市 |
| district | string | 区县 |
| detail_address | string | 详细地址 |
| is_default | boolean | 是否默认地址 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "name": "张三",
  "phone": "13800138000",
  "province": "北京市",
  "city": "北京市",
  "district": "朝阳区",
  "detail_address": "某街道某号",
  "is_default": true
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "user_id": 12345,
    "name": "张三",
    "phone": "13800138000",
    "province": "北京市",
    "city": "北京市",
    "district": "朝阳区",
    "detail_address": "某街道某号",
    "is_default": true,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 8.2 获取收货地址列表

**接口地址**: `GET /addresses`

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| items | array | 地址列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "张三",
        "phone": "13800138000",
        "province": "北京市",
        "city": "北京市",
        "district": "朝阳区",
        "detail_address": "某街道某号",
        "is_default": true,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 8.3 更新收货地址

**接口地址**: `PUT /addresses/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 地址ID |
| name | string | 否 | 收货人姓名 |
| phone | string | 否 | 联系电话 |
| province | string | 否 | 省份 |
| city | string | 否 | 城市 |
| district | string | 否 | 区县 |
| detail_address | string | 否 | 详细地址 |
| is_default | boolean | 否 | 是否默认地址 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 地址ID |
| name | string | 收货人姓名 |
| phone | string | 联系电话 |
| province | string | 省份 |
| city | string | 城市 |
| district | string | 区县 |
| detail_address | string | 详细地址 |
| is_default | boolean | 是否默认地址 |
| updated_at | string | 更新时间 |

**示例请求**:
```json
{
  "name": "张三",
  "phone": "13800138000",
  "province": "北京市",
  "city": "北京市",
  "district": "朝阳区",
  "detail_address": "某街道某号",
  "is_default": true
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三",
    "phone": "13800138000",
    "province": "北京市",
    "city": "北京市",
    "district": "朝阳区",
    "detail_address": "某街道某号",
    "is_default": true,
    "updated_at": "2024-01-15T11:00:00Z"
  }
}
```

### 8.4 删除收货地址

**接口地址**: `DELETE /addresses/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 地址ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| message | string | 删除结果信息 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "收货地址删除成功"
  }
}
```

## 9. 优惠券接口

### 9.1 获取可用优惠券列表

**接口地址**: `GET /coupons/available`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| amount | number | 否 | 订单金额，用于筛选满足条件的优惠券 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| items | array | 优惠券列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "满100减10元",
        "type": "FIXED_AMOUNT",
        "value": 10.00,
        "min_amount": 100.00,
        "max_discount_amount": null,
        "start_time": "2024-01-01T00:00:00Z",
        "end_time": "2024-12-31T23:59:59Z",
        "status": "ACTIVE"
      }
    ]
  }
}
```

### 9.2 领取优惠券

**接口地址**: `POST /coupons/{id}/claim`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 优惠券ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 用户优惠券ID |
| user_id | integer | 用户ID |
| coupon | object | 优惠券信息 |
| status | string | 状态 |
| received_at | string | 领取时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "coupon": {
      "id": 1,
      "name": "满100减10元",
      "type": "FIXED_AMOUNT",
      "value": 10.00,
      "min_amount": 100.00
    },
    "status": "AVAILABLE",
    "received_at": "2024-01-15T10:30:00Z"
  }
}
```

### 9.3 获取我的优惠券列表

**接口地址**: `GET /coupons/mine`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 状态(AVAILABLE/USED/EXPIRED) |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| items | array | 用户优惠券列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1001,
        "coupon": {
          "id": 1,
          "name": "满100减10元",
          "type": "FIXED_AMOUNT",
          "value": 10.00,
          "min_amount": 100.00,
          "start_time": "2024-01-01T00:00:00Z",
          "end_time": "2024-12-31T23:59:59Z"
        },
        "status": "AVAILABLE",
        "received_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

## 10. 商品评价接口

### 10.1 添加商品评价

**接口地址**: `POST /reviews`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| order_id | integer | 是 | 订单ID |
| product_id | integer | 是 | 商品ID |
| rating | integer | 是 | 评分(1-5星) |
| content | string | 否 | 评价内容 |
| images | array | 否 | 评价图片URL列表 |
| is_anonymous | boolean | 否 | 是否匿名 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 评价ID |
| user | object | 用户信息 |
| product_id | integer | 商品ID |
| order_id | integer | 订单ID |
| rating | integer | 评分 |
| content | string | 评价内容 |
| images | array | 评价图片URL列表 |
| is_anonymous | boolean | 是否匿名 |
| status | string | 审核状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "order_id": 2001,
  "product_id": 1,
  "rating": 5,
  "content": "种子质量很好，发芽率高",
  "images": [],
  "is_anonymous": false
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "user": {
      "id": 12345,
      "name": "张三"
    },
    "product_id": 1,
    "order_id": 2001,
    "rating": 5,
    "content": "种子质量很好，发芽率高",
    "images": [],
    "is_anonymous": false,
    "status": "PENDING",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 10.2 获取商品评价列表

**接口地址**: `GET /reviews`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 商品ID |
| rating | integer | 否 | 评分筛选 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 评价列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 10,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1,
        "user": {
          "id": 12345,
          "name": "张三"
        },
        "rating": 5,
        "content": "种子质量很好，发芽率高",
        "images": [],
        "is_anonymous": false,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

## 11. 商品收藏接口

### 11.1 添加商品收藏

**接口地址**: `POST /favorites`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 商品ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 收藏ID |
| user_id | integer | 用户ID |
| product | object | 商品信息 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "product_id": 1
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "product": {
      "id": 1,
      "name": "优质小麦种子",
      "price": 25.00,
      "cover_image": "https://example.com/image1.jpg"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 11.2 获取商品收藏列表

**接口地址**: `GET /favorites`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 收藏列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 5,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1001,
        "product": {
          "id": 1,
          "name": "优质小麦种子",
          "price": 25.00,
          "cover_image": "https://example.com/image1.jpg"
        },
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 11.3 删除商品收藏

**接口地址**: `DELETE /favorites/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 收藏ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| message | string | 删除结果信息 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "商品收藏删除成功"
  }
}
```

## 12. 错误码定义

| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 商品不存在 | 指定的商品不存在 |
| 40003 | 商品已下架 | 商品已下架，无法购买 |
| 40004 | 库存不足 | 商品库存不足 |
| 40005 | 购物车项不存在 | 指定的购物车项不存在 |
| 40006 | 订单不存在 | 指定的订单不存在 |
| 40007 | 订单状态不允许此操作 | 当前订单状态不允许执行该操作 |
| 40008 | 收货地址不存在 | 指定的收货地址不存在 |
| 40009 | 优惠券不存在 | 指定的优惠券不存在 |
| 40010 | 优惠券不可用 | 优惠券不满足使用条件或已过期 |
| 40011 | 已领取过该优惠券 | 不能重复领取同一张优惠券 |
| 40012 | 商品评价已存在 | 该订单商品已评价 |
| 40013 | 商品收藏已存在 | 该商品已在收藏夹中 |
| 40014 | 商品收藏不存在 | 指定的商品收藏不存在 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |