# 交易系统 API 文档 (v1.1.0)

## 1. 接口概述

### 1.1 功能范围
- 商品发布/下架
- 订单创建/支付
- 物流跟踪
- 订单状态查询

### 1.2 基础路径
`/api/v1/[系统名称]`

### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据管理
- 系统接口（高级权限）：配置管理

### 1.4 全局错误码
| 状态码 | 说明               |
|--------|--------------------|
| 400    | 请求参数无效       |
| 401    | 未授权             |
| 403    | 权限不足           |
| 404    | 资源不存在         |
| 500    | 服务器内部错误     |
`/api/v1/trades`

## 2. 接口明细

### 2.1 商品发布
```
POST /products
```

**请求参数**:
| 字段         | 类型   | 必填 | 说明               |
|--------------|--------|------|--------------------|
| name         | string | 是   | 商品名称          |
| price        | number | 是   | 价格(元)          |
| stock        | number | 是   | 库存数量          |
| category     | string | 是   | 商品分类          |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "product_id": "prod_001",
    "name": "优质牛肉",
    "price": 98.5,
    "stock": 100,
    "category": "生鲜",
    "seller_id": "seller_001",
    "created_at": "2024-01-20T10:00:00Z",
    "status": "上架中"
  }
}
```

### 2.2 创建订单
```
POST /orders
```

**请求参数**:
| 字段         | 类型   | 必填 | 说明               |
|--------------|--------|------|--------------------|
| product_id   | number | 是   | 商品ID            |
| quantity     | number | 是   | 购买数量          |
| address_id   | number | 是   | 收货地址ID        |
| payment_method | string | 是   | 支付方式(微信/支付宝)|
| coupon_code  | string | 否   | 优惠券码          |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "order_id": "order_001",
    "product_id": "prod_001",
    "quantity": 2,
    "total_amount": 197.0,
    "discount_amount": 0.0,
    "final_amount": 197.0,
    "payment_method": "微信支付",
    "order_status": "待支付",
    "created_at": "2024-01-20T10:00:00Z",
    "payment_expiry": "2024-01-20T10:30:00Z"
  }
}
```

### 2.3 物流跟踪
```
GET /logistics/:order_id
```

**请求参数**:
| 参数        | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| order_id    | string | 是   | 订单ID             |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "order_id": "order_001",
    "logistics": [
      {
        "tracking_number": "SF1234567890",
        "status": "已发货",
        "current_location": "北京市朝阳区",
        "estimated_delivery": "2024-01-22T10:00:00Z",
        "history": [
          {
            "time": "2024-01-20T10:00:00Z",
            "status": "商家已接单",
            "location": "北京市朝阳区"
          },
          {
            "time": "2024-01-20T12:00:00Z", 
            "status": "已发货",
            "location": "北京市朝阳区"
          }
        ]
      }
    ]
  }
}
```

## 3. 状态流转
```mermaid
stateDiagram
    [*] --> 待支付
    待支付 --> 已支付: 支付成功
    已支付 --> 配送中: 商家发货
    配送中 --> 已完成: 确认收货
```

## 4. 安全要求
- 支付接口需HTTPS加密
- 敏感数据需RSA加密传输

## 5. 权限控制
- 商品发布：商户
- 订单创建：用户
- 物流跟踪：用户/商户
## 3. 版本历史

### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义