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>
2026-01-14 19:25:22 +08:00
commit 3ad6eee0d9
59 changed files with 8078 additions and 0 deletions
--- a/hyperf_api/api_contract.md
+++ b/hyperf_api/api_contract.md
@@ -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 条