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:
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