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