# 交易服务API设计文档

## 1. 概述

本文档详细描述了交易服务(trade-service)提供的API接口，包括商品管理、订单处理、支付和物流等核心功能。

## 2. 基础信息

- 基础路径: `/api/v1/trade`
- 版本: 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": 10001,
  "message": "错误描述",
  "data": null
}
```

## 5. 商品管理接口

### 5.1 发布商品

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

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| title | string | 是 | 商品标题 |
| description | string | 否 | 商品描述 |
| category | string | 是 | 商品分类 |
| price | number | 是 | 商品价格 |
| quantity | integer | 是 | 商品数量 |
| images | array | 否 | 商品图片URL列表 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 商品ID |
| seller_id | integer | 卖家用户ID |
| title | string | 商品标题 |
| description | string | 商品描述 |
| category | string | 商品分类 |
| price | number | 商品价格 |
| quantity | integer | 商品数量 |
| status | string | 商品状态 |
| images | array | 商品图片URL列表 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "title": "优质黄牛",
  "description": "3岁健康黄牛，体重500公斤",
  "category": "livestock",
  "price": 15000.00,
  "quantity": 1,
  "images": [
    "http://example.com/image1.jpg",
    "http://example.com/image2.jpg"
  ]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "seller_id": 12345,
    "title": "优质黄牛",
    "description": "3岁健康黄牛，体重500公斤",
    "category": "livestock",
    "price": 15000.00,
    "quantity": 1,
    "status": "PENDING",
    "images": [
      "http://example.com/image1.jpg",
      "http://example.com/image2.jpg"
    ],
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 5.2 查询商品列表

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

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| category | string | 否 | 商品分类 |
| status | string | 否 | 商品状态 |
| 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": 1001,
        "seller_id": 12345,
        "title": "优质黄牛",
        "description": "3岁健康黄牛，体重500公斤",
        "category": "livestock",
        "price": 15000.00,
        "quantity": 1,
        "status": "APPROVED",
        "images": [
          "http://example.com/image1.jpg"
        ],
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 5.3 查询商品详情

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

**请求参数**:

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

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 商品ID |
| seller_id | integer | 卖家用户ID |
| title | string | 商品标题 |
| description | string | 商品描述 |
| category | string | 商品分类 |
| price | number | 商品价格 |
| quantity | integer | 商品数量 |
| status | string | 商品状态 |
| images | array | 商品图片URL列表 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "seller_id": 12345,
    "title": "优质黄牛",
    "description": "3岁健康黄牛，体重500公斤",
    "category": "livestock",
    "price": 15000.00,
    "quantity": 1,
    "status": "APPROVED",
    "images": [
      "http://example.com/image1.jpg",
      "http://example.com/image2.jpg"
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

## 6. 订单管理接口

### 6.1 创建订单

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

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 商品ID |
| quantity | integer | 是 | 购买数量 |
| shipping_address | string | 是 | 收货地址 |
| contact_phone | string | 是 | 联系电话 |
| remark | string | 否 | 买家备注 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 订单ID |
| order_no | string | 订单编号 |
| buyer_id | integer | 买家用户ID |
| seller_id | integer | 卖家用户ID |
| product_id | integer | 商品ID |
| quantity | integer | 购买数量 |
| unit_price | number | 单价 |
| total_amount | number | 总金额 |
| status | string | 订单状态 |
| shipping_address | string | 收货地址 |
| contact_phone | string | 联系电话 |
| remark | string | 买家备注 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "product_id": 1001,
  "quantity": 1,
  "shipping_address": "北京市朝阳区xxx街道",
  "contact_phone": "13800138000",
  "remark": "请尽快发货"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "order_no": "ORD20240115103000001",
    "buyer_id": 54321,
    "seller_id": 12345,
    "product_id": 1001,
    "quantity": 1,
    "unit_price": 15000.00,
    "total_amount": 15000.00,
    "status": "CREATED",
    "shipping_address": "北京市朝阳区xxx街道",
    "contact_phone": "13800138000",
    "remark": "请尽快发货",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.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": 50,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 2001,
        "order_no": "ORD20240115103000001",
        "buyer_id": 54321,
        "seller_id": 12345,
        "product_id": 1001,
        "quantity": 1,
        "unit_price": 15000.00,
        "total_amount": 15000.00,
        "status": "PAID",
        "shipping_address": "北京市朝阳区xxx街道",
        "contact_phone": "13800138000",
        "remark": "请尽快发货",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 6.3 查询订单详情

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

**请求参数**:

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

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 订单ID |
| order_no | string | 订单编号 |
| buyer_id | integer | 买家用户ID |
| seller_id | integer | 卖家用户ID |
| product | object | 商品信息 |
| quantity | integer | 购买数量 |
| unit_price | number | 单价 |
| total_amount | number | 总金额 |
| status | string | 订单状态 |
| shipping_address | string | 收货地址 |
| contact_phone | string | 联系电话 |
| remark | string | 买家备注 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "order_no": "ORD20240115103000001",
    "buyer_id": 54321,
    "seller_id": 12345,
    "product": {
      "id": 1001,
      "title": "优质黄牛",
      "price": 15000.00,
      "images": [
        "http://example.com/image1.jpg"
      ]
    },
    "quantity": 1,
    "unit_price": 15000.00,
    "total_amount": 15000.00,
    "status": "PAID",
    "shipping_address": "北京市朝阳区xxx街道",
    "contact_phone": "13800138000",
    "remark": "请尽快发货",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}
```

## 7. 支付接口

### 7.1 发起支付

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

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| order_id | integer | 是 | 订单ID |
| payment_method | string | 是 | 支付方式(WECHAT/ALIPAY/BANK) |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 支付ID |
| order_id | integer | 关联订单ID |
| payment_no | string | 支付流水号 |
| amount | number | 支付金额 |
| payment_method | string | 支付方式 |
| status | string | 支付状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "order_id": 2001,
  "payment_method": "WECHAT"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "order_id": 2001,
    "payment_no": "PAY20240115103000001",
    "amount": 15000.00,
    "payment_method": "WECHAT",
    "status": "PENDING",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 7.2 查询支付状态

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

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 支付ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 支付ID |
| order_id | integer | 关联订单ID |
| payment_no | string | 支付流水号 |
| amount | number | 支付金额 |
| payment_method | string | 支付方式 |
| status | string | 支付状态 |
| transaction_id | string | 第三方支付平台交易ID |
| paid_at | string | 实际支付时间 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "order_id": 2001,
    "payment_no": "PAY20240115103000001",
    "amount": 15000.00,
    "payment_method": "WECHAT",
    "status": "SUCCESS",
    "transaction_id": "wx1234567890",
    "paid_at": "2024-01-15T11:00:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}
```

## 8. 错误码定义

| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 10001 | 参数错误 | 请求参数不合法 |
| 10002 | 商品不存在 | 指定的商品不存在 |
| 10003 | 订单不存在 | 指定的订单不存在 |
| 10004 | 支付记录不存在 | 指定的支付记录不存在 |
| 10005 | 库存不足 | 商品库存不足 |
| 10006 | 订单状态错误 | 订单状态不正确，无法执行当前操作 |
| 10007 | 支付失败 | 支付处理失败 |
| 20001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 20002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |