feat: 初始化 B2B AI Shopping Assistant 项目
- 配置 Docker Compose 多服务编排 - 实现 Chatwoot + Agent 集成 - 配置 Strapi MCP 知识库 - 支持 7 种语言的 FAQ 系统 - 实现 LangGraph AI 工作流 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
470
hyperf_api/api_contract.md
Normal file
470
hyperf_api/api_contract.md
Normal file
@@ -0,0 +1,470 @@
|
||||
# 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 条
|
||||
901
hyperf_api/openapi.yaml
Normal file
901
hyperf_api/openapi.yaml
Normal file
@@ -0,0 +1,901 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: B2B Shopping AI Assistant - Hyperf API Contract
|
||||
description: |
|
||||
API contract for the Hyperf PHP backend to support the AI Assistant.
|
||||
This document defines the expected endpoints and data structures.
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: AI Assistant Team
|
||||
|
||||
servers:
|
||||
- url: http://hyperf-api:9501/api/v1
|
||||
description: Internal Docker network
|
||||
- url: http://localhost:9501/api/v1
|
||||
description: Local development
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
|
||||
schemas:
|
||||
# Common response wrapper
|
||||
ApiResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
description: "0 for success, non-zero for errors"
|
||||
example: 0
|
||||
message:
|
||||
type: string
|
||||
example: "success"
|
||||
data:
|
||||
type: object
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
timestamp:
|
||||
type: integer
|
||||
request_id:
|
||||
type: string
|
||||
|
||||
# Pagination
|
||||
Pagination:
|
||||
type: object
|
||||
properties:
|
||||
total:
|
||||
type: integer
|
||||
page:
|
||||
type: integer
|
||||
page_size:
|
||||
type: integer
|
||||
total_pages:
|
||||
type: integer
|
||||
|
||||
# Order schemas
|
||||
Order:
|
||||
type: object
|
||||
properties:
|
||||
order_id:
|
||||
type: string
|
||||
example: "ORD20260114001"
|
||||
status:
|
||||
type: string
|
||||
enum: [pending, paid, processing, shipped, delivered, cancelled]
|
||||
items:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/OrderItem'
|
||||
total_amount:
|
||||
type: number
|
||||
format: float
|
||||
shipping_address:
|
||||
$ref: '#/components/schemas/Address'
|
||||
tracking_number:
|
||||
type: string
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
OrderItem:
|
||||
type: object
|
||||
properties:
|
||||
item_id:
|
||||
type: string
|
||||
product_id:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
quantity:
|
||||
type: integer
|
||||
unit_price:
|
||||
type: number
|
||||
format: float
|
||||
subtotal:
|
||||
type: number
|
||||
format: float
|
||||
|
||||
Address:
|
||||
type: object
|
||||
properties:
|
||||
province:
|
||||
type: string
|
||||
city:
|
||||
type: string
|
||||
district:
|
||||
type: string
|
||||
detail:
|
||||
type: string
|
||||
contact:
|
||||
type: string
|
||||
phone:
|
||||
type: string
|
||||
|
||||
LogisticsTimeline:
|
||||
type: object
|
||||
properties:
|
||||
time:
|
||||
type: string
|
||||
format: date-time
|
||||
location:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
|
||||
# Product schemas
|
||||
Product:
|
||||
type: object
|
||||
properties:
|
||||
product_id:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
brand:
|
||||
type: string
|
||||
category:
|
||||
type: string
|
||||
price:
|
||||
type: number
|
||||
format: float
|
||||
price_tiers:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
min_qty:
|
||||
type: integer
|
||||
price:
|
||||
type: number
|
||||
image:
|
||||
type: string
|
||||
images:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
stock:
|
||||
type: integer
|
||||
min_order_quantity:
|
||||
type: integer
|
||||
specifications:
|
||||
type: object
|
||||
|
||||
Quote:
|
||||
type: object
|
||||
properties:
|
||||
quote_id:
|
||||
type: string
|
||||
product_id:
|
||||
type: string
|
||||
quantity:
|
||||
type: integer
|
||||
unit_price:
|
||||
type: number
|
||||
subtotal:
|
||||
type: number
|
||||
discount:
|
||||
type: number
|
||||
discount_reason:
|
||||
type: string
|
||||
tax:
|
||||
type: number
|
||||
shipping_fee:
|
||||
type: number
|
||||
total_price:
|
||||
type: number
|
||||
validity:
|
||||
type: string
|
||||
payment_terms:
|
||||
type: string
|
||||
estimated_delivery:
|
||||
type: string
|
||||
|
||||
# Aftersale schemas
|
||||
AftersaleRecord:
|
||||
type: object
|
||||
properties:
|
||||
aftersale_id:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum: [return, exchange, complaint, ticket]
|
||||
status:
|
||||
type: string
|
||||
order_id:
|
||||
type: string
|
||||
items:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
description:
|
||||
type: string
|
||||
progress:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
step:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
time:
|
||||
type: string
|
||||
note:
|
||||
type: string
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
paths:
|
||||
# ============ Order APIs ============
|
||||
/orders/query:
|
||||
post:
|
||||
summary: Query orders
|
||||
operationId: queryOrders
|
||||
tags: [Orders]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [user_id, account_id]
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
account_id:
|
||||
type: string
|
||||
order_id:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
date_range:
|
||||
type: object
|
||||
properties:
|
||||
start:
|
||||
type: string
|
||||
format: date
|
||||
end:
|
||||
type: string
|
||||
format: date
|
||||
page:
|
||||
type: integer
|
||||
default: 1
|
||||
page_size:
|
||||
type: integer
|
||||
default: 20
|
||||
responses:
|
||||
'200':
|
||||
description: Orders list
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
orders:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Order'
|
||||
pagination:
|
||||
$ref: '#/components/schemas/Pagination'
|
||||
|
||||
/orders/{order_id}/logistics:
|
||||
get:
|
||||
summary: Get logistics tracking
|
||||
operationId: getLogistics
|
||||
tags: [Orders]
|
||||
parameters:
|
||||
- name: order_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: tracking_number
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Logistics information
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
tracking_number:
|
||||
type: string
|
||||
courier:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
estimated_delivery:
|
||||
type: string
|
||||
timeline:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/LogisticsTimeline'
|
||||
|
||||
/orders/{order_id}/modify:
|
||||
put:
|
||||
summary: Modify order
|
||||
operationId: modifyOrder
|
||||
tags: [Orders]
|
||||
parameters:
|
||||
- name: order_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [user_id, modifications]
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
modifications:
|
||||
type: object
|
||||
properties:
|
||||
shipping_address:
|
||||
$ref: '#/components/schemas/Address'
|
||||
items:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
product_id:
|
||||
type: string
|
||||
quantity:
|
||||
type: integer
|
||||
responses:
|
||||
'200':
|
||||
description: Modified order
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
order:
|
||||
$ref: '#/components/schemas/Order'
|
||||
price_diff:
|
||||
type: number
|
||||
|
||||
/orders/{order_id}/cancel:
|
||||
post:
|
||||
summary: Cancel order
|
||||
operationId: cancelOrder
|
||||
tags: [Orders]
|
||||
parameters:
|
||||
- name: order_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [user_id, reason]
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
reason:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Cancellation result
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
order_id:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
refund_info:
|
||||
type: object
|
||||
properties:
|
||||
amount:
|
||||
type: number
|
||||
method:
|
||||
type: string
|
||||
estimated_arrival:
|
||||
type: string
|
||||
|
||||
/orders/{order_id}/invoice:
|
||||
get:
|
||||
summary: Get invoice
|
||||
operationId: getInvoice
|
||||
tags: [Orders]
|
||||
parameters:
|
||||
- name: order_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: type
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
enum: [normal, vat]
|
||||
default: normal
|
||||
responses:
|
||||
'200':
|
||||
description: Invoice information
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
invoice_number:
|
||||
type: string
|
||||
invoice_url:
|
||||
type: string
|
||||
amount:
|
||||
type: number
|
||||
tax:
|
||||
type: number
|
||||
issued_at:
|
||||
type: string
|
||||
|
||||
# ============ Product APIs ============
|
||||
/products/search:
|
||||
post:
|
||||
summary: Search products
|
||||
operationId: searchProducts
|
||||
tags: [Products]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [query]
|
||||
properties:
|
||||
query:
|
||||
type: string
|
||||
filters:
|
||||
type: object
|
||||
properties:
|
||||
category:
|
||||
type: string
|
||||
brand:
|
||||
type: string
|
||||
price_range:
|
||||
type: object
|
||||
properties:
|
||||
min:
|
||||
type: number
|
||||
max:
|
||||
type: number
|
||||
sort:
|
||||
type: string
|
||||
enum: [relevance, price_asc, price_desc, sales, latest]
|
||||
page:
|
||||
type: integer
|
||||
page_size:
|
||||
type: integer
|
||||
responses:
|
||||
'200':
|
||||
description: Search results
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
products:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Product'
|
||||
total:
|
||||
type: integer
|
||||
pagination:
|
||||
$ref: '#/components/schemas/Pagination'
|
||||
|
||||
/products/{product_id}:
|
||||
get:
|
||||
summary: Get product details
|
||||
operationId: getProduct
|
||||
tags: [Products]
|
||||
parameters:
|
||||
- name: product_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Product details
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: '#/components/schemas/Product'
|
||||
|
||||
/products/recommend:
|
||||
post:
|
||||
summary: Get product recommendations
|
||||
operationId: recommendProducts
|
||||
tags: [Products]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [user_id, account_id]
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
account_id:
|
||||
type: string
|
||||
context:
|
||||
type: object
|
||||
properties:
|
||||
current_query:
|
||||
type: string
|
||||
recent_views:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
strategy:
|
||||
type: string
|
||||
enum: [collaborative, content_based, hybrid]
|
||||
limit:
|
||||
type: integer
|
||||
responses:
|
||||
'200':
|
||||
description: Recommendations
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
recommendations:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
product:
|
||||
$ref: '#/components/schemas/Product'
|
||||
score:
|
||||
type: number
|
||||
reason:
|
||||
type: string
|
||||
|
||||
/products/quote:
|
||||
post:
|
||||
summary: Get B2B price quote
|
||||
operationId: getQuote
|
||||
tags: [Products]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [product_id, quantity, account_id]
|
||||
properties:
|
||||
product_id:
|
||||
type: string
|
||||
quantity:
|
||||
type: integer
|
||||
account_id:
|
||||
type: string
|
||||
delivery_address:
|
||||
type: object
|
||||
properties:
|
||||
province:
|
||||
type: string
|
||||
city:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Price quote
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: '#/components/schemas/Quote'
|
||||
|
||||
/products/inventory/check:
|
||||
post:
|
||||
summary: Check inventory
|
||||
operationId: checkInventory
|
||||
tags: [Products]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [product_ids]
|
||||
properties:
|
||||
product_ids:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
warehouse:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Inventory status
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
inventory:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
product_id:
|
||||
type: string
|
||||
available_stock:
|
||||
type: integer
|
||||
reserved_stock:
|
||||
type: integer
|
||||
warehouse:
|
||||
type: string
|
||||
|
||||
# ============ Aftersale APIs ============
|
||||
/aftersales/return:
|
||||
post:
|
||||
summary: Apply for return
|
||||
operationId: applyReturn
|
||||
tags: [Aftersales]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [order_id, user_id, items, description]
|
||||
properties:
|
||||
order_id:
|
||||
type: string
|
||||
user_id:
|
||||
type: string
|
||||
items:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
item_id:
|
||||
type: string
|
||||
quantity:
|
||||
type: integer
|
||||
reason:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
images:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Return application result
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
aftersale_id:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
estimated_refund:
|
||||
type: number
|
||||
process_steps:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
|
||||
/aftersales/exchange:
|
||||
post:
|
||||
summary: Apply for exchange
|
||||
operationId: applyExchange
|
||||
tags: [Aftersales]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [order_id, user_id, items, description]
|
||||
properties:
|
||||
order_id:
|
||||
type: string
|
||||
user_id:
|
||||
type: string
|
||||
items:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
item_id:
|
||||
type: string
|
||||
reason:
|
||||
type: string
|
||||
new_specs:
|
||||
type: object
|
||||
description:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Exchange application result
|
||||
|
||||
/aftersales/complaint:
|
||||
post:
|
||||
summary: Create complaint
|
||||
operationId: createComplaint
|
||||
tags: [Aftersales]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [user_id, type, title, description]
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum: [product_quality, service, logistics, pricing, other]
|
||||
title:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
related_order_id:
|
||||
type: string
|
||||
attachments:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Complaint creation result
|
||||
|
||||
/aftersales/ticket:
|
||||
post:
|
||||
summary: Create support ticket
|
||||
operationId: createTicket
|
||||
tags: [Aftersales]
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [user_id, category, priority, title, description]
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
category:
|
||||
type: string
|
||||
priority:
|
||||
type: string
|
||||
enum: [low, medium, high, urgent]
|
||||
title:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Ticket creation result
|
||||
|
||||
/aftersales/query:
|
||||
get:
|
||||
summary: Query aftersale records
|
||||
operationId: queryAftersales
|
||||
tags: [Aftersales]
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: aftersale_id
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Aftersale records
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/ApiResponse'
|
||||
- type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
records:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/AftersaleRecord'
|
||||
|
||||
tags:
|
||||
- name: Orders
|
||||
description: Order management APIs
|
||||
- name: Products
|
||||
description: Product catalog and pricing APIs
|
||||
- name: Aftersales
|
||||
description: Returns, exchanges, and complaints APIs
|
||||
Reference in New Issue
Block a user