wl
3ad6eee0d9
- 配置 Docker Compose 多服务编排 - 实现 Chatwoot + Agent 集成 - 配置 Strapi MCP 知识库 - 支持 7 种语言的 FAQ 系统 - 实现 LangGraph AI 工作流 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
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 条
|