471 lines
9.7 KiB
Markdown
471 lines
9.7 KiB
Markdown
|
# 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 条
|