# Hyperf API 接口约定文档

## 概述

本文档定义了 AI 助手与 Hyperf PHP 后端之间的 API 接口约定。

## 基本规范

### Base URL
```
http://hyperf-api:9501/api/v1
```

### 认证方式
```
Authorization: Bearer {token}
Content-Type: application/json
```

### 响应格式
```json
{
  "code": 0,           // 0=成功，非0=错误码
  "message": "success",
  "data": {...},       // 业务数据
  "meta": {
    "timestamp": 1705234567,
    "request_id": "uuid"
  }
}
```

### 错误码规范
| 范围 | 说明 |
|------|------|
| 1xxx | 认证相关错误 |
| 2xxx | 参数验证错误 |
| 3xxx | 业务逻辑错误 |
| 4xxx | 资源不存在 |
| 5xxx | 系统错误 |

---

## 订单模块 (Orders)

### 1. 查询订单

**POST** `/orders/query`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| user_id | string | 是 | 用户ID |
| account_id | string | 是 | 企业账号ID |
| order_id | string | 否 | 订单号（精确查询） |
| status | string | 否 | 订单状态筛选 |
| date_range.start | string | 否 | 开始日期 YYYY-MM-DD |
| date_range.end | string | 否 | 结束日期 YYYY-MM-DD |
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "orders": [
      {
        "order_id": "ORD20260114001",
        "status": "shipped",
        "items": [
          {
            "product_id": "prod_001",
            "name": "商品A",
            "quantity": 100,
            "unit_price": 50.00
          }
        ],
        "total_amount": 5000.00,
        "shipping_address": {...},
        "tracking_number": "SF1234567890",
        "created_at": "2026-01-10 10:00:00"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "page_size": 20
    }
  }
}
```

### 2. 物流跟踪

**GET** `/orders/{order_id}/logistics`

**查询参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| tracking_number | string | 否 | 物流单号（可选） |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "tracking_number": "SF1234567890",
    "courier": "顺丰速运",
    "status": "in_transit",
    "estimated_delivery": "2026-01-15",
    "timeline": [
      {
        "time": "2026-01-12 10:00:00",
        "location": "深圳转运中心",
        "status": "已发出",
        "description": "快件已从深圳发出"
      }
    ]
  }
}
```

### 3. 修改订单

**PUT** `/orders/{order_id}/modify`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| user_id | string | 是 | 用户ID（权限校验） |
| modifications | object | 是 | 修改内容 |
| modifications.shipping_address | object | 否 | 新收货地址 |
| modifications.items | array | 否 | 商品数量修改 |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "order": {...},
    "price_diff": 2500.00,
    "message": "订单修改成功"
  }
}
```

### 4. 取消订单

**POST** `/orders/{order_id}/cancel`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| user_id | string | 是 | 用户ID |
| reason | string | 是 | 取消原因 |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "order_id": "ORD20260114001",
    "status": "cancelled",
    "refund_info": {
      "amount": 5000.00,
      "method": "original_payment",
      "estimated_arrival": "3-5个工作日"
    }
  }
}
```

---

## 商品模块 (Products)

### 1. 商品搜索

**POST** `/products/search`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 搜索关键词 |
| filters.category | string | 否 | 分类筛选 |
| filters.brand | string | 否 | 品牌筛选 |
| filters.price_range.min | float | 否 | 最低价格 |
| filters.price_range.max | float | 否 | 最高价格 |
| sort | string | 否 | 排序：relevance/price_asc/price_desc/sales/latest |
| page | int | 否 | 页码 |
| page_size | int | 否 | 每页数量 |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "products": [
      {
        "product_id": "prod_001",
        "name": "办公笔记本A4",
        "brand": "得力",
        "price": 25.00,
        "image": "https://...",
        "stock": 5000,
        "min_order_quantity": 50
      }
    ],
    "total": 150,
    "pagination": {...}
  }
}
```

### 2. 商品详情

**GET** `/products/{product_id}`

**响应示例**
```json
{
  "code": 0,
  "data": {
    "product_id": "prod_001",
    "name": "办公笔记本A4",
    "description": "...",
    "specifications": {
      "size": "A4",
      "pages": 100
    },
    "price": 25.00,
    "price_tiers": [
      {"min_qty": 50, "price": 25.00},
      {"min_qty": 500, "price": 23.00},
      {"min_qty": 1000, "price": 20.00}
    ],
    "images": [...],
    "stock": 5000,
    "min_order_quantity": 50
  }
}
```

### 3. 智能推荐

**POST** `/products/recommend`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| user_id | string | 是 | 用户ID |
| account_id | string | 是 | 企业账号ID |
| context | object | 否 | 推荐上下文 |
| strategy | string | 否 | 推荐策略：collaborative/content_based/hybrid |
| limit | int | 否 | 推荐数量 |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "recommendations": [
      {
        "product": {...},
        "score": 0.95,
        "reason": "基于您的采购历史推荐"
      }
    ]
  }
}
```

### 4. B2B 询价

**POST** `/products/quote`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| product_id | string | 是 | 商品ID |
| quantity | int | 是 | 采购数量 |
| account_id | string | 是 | 企业账号ID（用于获取专属价格） |
| delivery_address | object | 否 | 收货地址（用于计算运费） |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "quote_id": "QT20260114001",
    "product_id": "prod_001",
    "quantity": 1000,
    "unit_price": 20.00,
    "subtotal": 20000.00,
    "discount": 500.00,
    "discount_reason": "VIP客户折扣",
    "tax": 2535.00,
    "shipping_fee": 200.00,
    "total_price": 22235.00,
    "validity": "7天",
    "payment_terms": "月结30天",
    "estimated_delivery": "2026-01-25"
  }
}
```

### 5. 库存查询

**POST** `/products/inventory/check`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| product_ids | array | 是 | 商品ID列表 |
| warehouse | string | 否 | 指定仓库 |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "inventory": [
      {
        "product_id": "prod_001",
        "available_stock": 4500,
        "reserved_stock": 500,
        "warehouse": "华南仓"
      }
    ]
  }
}
```

---

## 售后模块 (Aftersales)

### 1. 退货申请

**POST** `/aftersales/return`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| order_id | string | 是 | 订单号 |
| user_id | string | 是 | 用户ID |
| items | array | 是 | 退货商品列表 |
| items[].item_id | string | 是 | 订单商品ID |
| items[].quantity | int | 是 | 退货数量 |
| items[].reason | string | 是 | 退货原因 |
| description | string | 是 | 问题描述 |
| images | array | 否 | 图片URL列表 |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "aftersale_id": "AS20260114001",
    "status": "pending_review",
    "estimated_refund": 2500.00,
    "process_steps": [
      "提交申请",
      "商家审核",
      "寄回商品",
      "确认收货",
      "退款到账"
    ]
  }
}
```

### 2. 换货申请

**POST** `/aftersales/exchange`

参数结构与退货类似，返回换货单信息。

### 3. 创建投诉

**POST** `/aftersales/complaint`

**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| user_id | string | 是 | 用户ID |
| type | string | 是 | 投诉类型：product_quality/service/logistics/other |
| title | string | 是 | 投诉标题 |
| description | string | 是 | 详细描述 |
| related_order_id | string | 否 | 关联订单号 |
| attachments | array | 否 | 附件URL |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "complaint_id": "CMP20260114001",
    "status": "processing",
    "assigned_to": "客服主管-张三",
    "expected_response_time": "24小时内"
  }
}
```

### 4. 查询售后状态

**GET** `/aftersales/query`

**查询参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| user_id | string | 是 | 用户ID |
| aftersale_id | string | 否 | 售后单号（不填查询全部） |

**响应示例**
```json
{
  "code": 0,
  "data": {
    "records": [
      {
        "aftersale_id": "AS20260114001",
        "type": "return",
        "status": "approved",
        "order_id": "ORD20260114001",
        "progress": [
          {
            "step": "商家审核",
            "status": "completed",
            "time": "2026-01-14 10:00:00",
            "note": "审核通过，请寄回商品"
          }
        ],
        "created_at": "2026-01-13"
      }
    ]
  }
}
```

---

## 实现优先级

1. **高优先级**（核心流程）
   - POST /orders/query
   - GET /orders/{id}/logistics
   - POST /products/search
   - GET /products/{id}

2. **中优先级**（完整体验）
   - POST /products/quote
   - POST /aftersales/return
   - GET /aftersales/query

3. **低优先级**（增强功能）
   - POST /products/recommend
   - PUT /orders/{id}/modify
   - POST /aftersales/complaint

---

## 注意事项

1. **权限校验**：所有涉及订单/售后操作的接口需要验证 user_id 是否有权限
2. **幂等性**：POST 请求应该支持幂等，避免重复提交
3. **错误处理**：返回清晰的错误信息，便于 AI 理解和向用户解释
4. **性能考虑**：列表接口支持分页，单次返回数据量不超过 100 条