wangliang/assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
965b11316e1571885ded9e5235da2130a2474cf4
assistant/hyperf_api/api_contract.md
wl 3ad6eee0d9 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

9.7 KiB
Raw Blame History

Hyperf API 接口约定文档

概述

本文档定义了 AI 助手与 Hyperf PHP 后端之间的 API 接口约定。

基本规范

Base URL

http://hyperf-api:9501/api/v1

认证方式

Authorization: Bearer {token}
Content-Type: application/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

响应示例

{
  "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 否 物流单号（可选）

响应示例

{
  "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 否 商品数量修改

响应示例

{
  "code": 0,
  "data": {
    "order": {...},
    "price_diff": 2500.00,
    "message": "订单修改成功"
  }
}

4. 取消订单

POST /orders/{order_id}/cancel

请求参数

字段 类型 必填 说明
user_id string 是 用户ID
reason string 是 取消原因

响应示例

{
  "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 否 每页数量

响应示例

{
  "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}

响应示例

{
  "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 否 推荐数量

响应示例

{
  "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 否 收货地址（用于计算运费）

响应示例

{
  "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 否 指定仓库

响应示例

{
  "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列表

响应示例

{
  "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

响应示例

{
  "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 否 售后单号（不填查询全部）

响应示例

{
  "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 条
Reference in New Issue View Git Blame Copy Permalink