小遥配配 - API接口设计文档

文档信息

项目	内容
项目名称	小遥配配 - AI对话式电脑导购助手
文档版本	v2.0
创建日期	2025-12-22
最后更新	2026-02-25
协议	HTTPS
数据格式	JSON
认证方式	JWT Token（B端接口）

API环境配置

环境	API基础URL
开发环境	`http://localhost:8001`
测试环境	`https://test-api.xiaoyaos.com/peipei`
生产环境	`https://api.xiaoyaos.com/peipei`

1. 通用说明

1.1 请求规范

请求头（Request Headers）

字段	类型	必填	说明
Content-Type	String	是	`application/json`
Authorization	String	否	B端接口需要，格式：`Bearer {token}`
X-Request-ID	String	否	请求追踪ID（UUID格式）

请求示例

POST /api/user/chat/message HTTP/1.1
Host: api.xiaoyaos.com
Content-Type: application/json
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

{
  "session_id": "session_abc123",
  "shop_id": "1234567890123456789",
  "message": "我想要一台6000左右的游戏笔记本"
}

1.2 响应规范

统一响应格式

{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1703232000000,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

响应字段说明

字段	类型	说明
code	Integer	状态码（200成功，其他失败）
message	String	响应消息
data	Object/Array	响应数据
timestamp	Long	服务器时间戳（毫秒）
request_id	String	请求追踪ID

1.3 分页规范

分页请求参数

参数	类型	必填	默认值	说明
page	Integer	否	1	页码（从1开始）
limit	Integer	否	10	每页数量（最大100）

分页响应格式

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "total": 100,
    "page": 1,
    "limit": 10,
    "pages": 10
  }
}

1.4 认证说明

B端接口认证

使用 JWT Token 认证
Token 有效期：7天
Token 刷新：登录后重新获取

请求示例

GET /api/mer/skus HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2. C端接口（用户端）

2.1 对话模块

2.1.1 发送消息（AI意图识别）

接口地址： POST /api/user/chat/message

接口说明： 用户发送消息，AI识别意图并提取信息

请求参数：

参数	类型	必填	说明
session_id	String	否	会话ID（首次传空，后续使用返回的session_id）
shop_id	String	是	店铺ID（雪花算法生成的20位整数）
message	String	是	用户消息内容（1-500字符）

请求示例：

{
  "session_id": "session_abc123",
  "shop_id": "1234567890123456789",
  "message": "我想要一台6000左右的游戏笔记本能玩原神"
}

响应参数：

参数	类型	说明
session_id	String	会话ID（首次会话时返回，后续使用此ID）
ai_response	String	AI回复内容
extracted_info	Object	AI提取的用户需求信息
is_complete	Boolean	信息是否收集完整
next_action	String	下一步动作（ask/recommend）
quick_replies	Array	快捷回复选项

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "session_id": "session_abc123",
    "ai_response": "明白了！6000左右的游戏笔记本，玩原神完全够用～\n您需要经常携带吗？还是主要在家用？",
    "extracted_info": {
      "budget": "6000左右",
      "device_type": "笔记本",
      "usage": "游戏",
      "requirements": "玩原神",
      "brand": null,
      "portable": null
    },
    "is_complete": false,
    "next_action": "ask",
    "quick_replies": ["经常携带", "主要在家用", "不确定"]
  },
  "timestamp": 1703232000000
}

2.1.2 获取推荐方案

接口地址： POST /api/user/chat/recommend

接口说明： 根据用户需求获取AI推荐的电脑配置方案

请求参数：

参数	类型	必填	说明
session_id	String	是	会话ID
shop_id	String	是	店铺ID（雪花算法生成的20位整数）
needs	Object	是	用户需求信息

needs对象结构：

参数	类型	必填	说明
budget	String	是	预算范围
device_type	String	是	设备类型（desktop/laptop/aio）
usage	String	是	用途（办公/游戏/设计等）
requirements	String	否	具体需求描述
brand	String	否	品牌偏好
portable	String	否	便携性需求

请求示例：

{
  "session_id": "session_abc123",
  "shop_id": "1234567890123456789",
  "needs": {
    "budget": "6000左右",
    "device_type": "笔记本",
    "usage": "游戏",
    "requirements": "玩原神",
    "portable": "主要在家用"
  }
}

响应参数：

参数	类型	说明
recommendations	Array	推荐方案列表（最多3个）

recommendations数组元素结构：

参数	类型	说明
sku_id	String	配置ID（雪花算法生成的20位整数）
name	String	配置名称
device_type	String	设备类型
brand	String	品牌
price	Decimal	价格
specs	Object	配置参数
images	Array	图片URL数组
ai_reason	String	AI推荐理由
match_score	Integer	匹配分数（0-100）

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "recommendations": [
      {
        "sku_id": "1234567890123456790",
        "name": "联想拯救者Y7000P",
        "device_type": "笔记本",
        "brand": "联想",
        "price": 7499.00,
        "specs": {
          "cpu": "i7-12700H",
          "gpu": "RTX 4060 8G",
          "ram": "16GB DDR5",
          "storage": "512GB SSD",
          "screen": "15.6英寸 2.5K 165Hz",
          "weight": "2.4kg",
          "battery": "5-6小时"
        },
        "images": [
          "https://oss.aliyun.com/images/sku1_1.jpg",
          "https://oss.aliyun.com/images/sku1_2.jpg"
        ],
        "ai_reason": "这款笔记本搭载RTX 4060显卡，原神可以稳定60帧高画质运行，屏幕是2.5K 165Hz游戏体验非常流畅！性价比很高，强烈推荐！",
        "match_score": 95
      },
      {
        "sku_id": "1234567890123456791",
        "name": "华硕天选4",
        "device_type": "笔记本",
        "brand": "华硕",
        "price": 6999.00,
        "specs": {
          "cpu": "R7-7735HS",
          "gpu": "RTX 4060 8G",
          "ram": "16GB DDR5",
          "storage": "512GB SSD",
          "screen": "15.6英寸 2.5K 165Hz",
          "weight": "2.3kg",
          "battery": "4-5小时"
        },
        "images": [
          "https://oss.aliyun.com/images/sku2_1.jpg"
        ],
        "ai_reason": "AMD处理器性能强劲，同样是RTX 4060显卡，价格更实惠，性价比非常高！",
        "match_score": 92
      }
    ]
  },
  "timestamp": 1703232000000
}

2.1.3 获取对话历史

接口地址： GET /api/user/chat/history

接口说明： 获取指定会话的对话历史记录

请求参数：

参数	类型	必填	说明
session_id	String	是	会话ID

请求示例：

GET /api/user/chat/history?session_id=session_abc123 HTTP/1.1
Host: api.xiaoyaos.com

响应参数：

参数	类型	说明
messages	Array	消息列表

messages数组元素结构：

参数	类型	说明
role	String	角色（user/assistant）
content	String	消息内容
created_at	String	创建时间

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "messages": [
      {
        "role": "assistant",
        "content": "您好！我是小遥，我来帮您选一台合适的电脑～请问您的预算大概是多少呢？",
        "created_at": "2025-12-22T14:30:15Z"
      },
      {
        "role": "user",
        "content": "我想要一台6000左右的游戏笔记本能玩原神",
        "created_at": "2025-12-22T14:30:42Z"
      },
      {
        "role": "assistant",
        "content": "明白了！6000左右的游戏笔记本，玩原神完全够用～您需要经常携带吗？",
        "created_at": "2025-12-22T14:30:45Z"
      }
    ]
  },
  "timestamp": 1703232000000
}

2.2 线索模块

2.2.1 提交客户线索

接口地址： POST /api/user/lead/submit

接口说明： 用户选择方案后提交联系方式

请求参数：

参数	类型	必填	说明
session_id	String	是	会话ID
shop_id	String	是	店铺ID（雪花算法生成的20位整数）
sku_id	String	是	选中的配置ID（雪花算法生成的20位整数）
phone	String	是	手机号（11位数字）
wechat	String	否	微信号
remark	String	否	备注信息（最多200字符）

请求示例：

{
  "session_id": "session_abc123",
  "shop_id": "1234567890123456789",
  "sku_id": "1234567890123456790",
  "phone": "13812345678",
  "wechat": "user_wechat",
  "remark": "希望尽快联系，周末有空"
}

响应参数：

参数	类型	说明
lead_id	String	线索ID（雪花算法生成的20位整数）
shop_info	Object	店铺信息

shop_info对象结构：

参数	类型	说明
shop_name	String	店铺名称
phone	String	店铺电话
address	String	店铺地址
business_hours	String	营业时间

响应示例：

{
  "code": 200,
  "message": "提交成功",
  "data": {
    "lead_id": "1234567890123456792",
    "shop_info": {
      "shop_name": "XX电脑城",
      "phone": "13812345678",
      "address": "北京市朝阳区XX路XX号",
      "business_hours": "9:00 - 21:00"
    }
  },
  "timestamp": 1703232000000
}

2.2.2 获取店铺信息

接口地址： GET /api/user/shop/{shop_id}

接口说明： 获取店铺基本信息（用于分享页面展示）

路径参数：

参数	类型	必填	说明
shop_id	String	是	店铺ID（雪花算法生成的20位整数）

请求示例：

GET /api/user/shop/1234567890123456789 HTTP/1.1
Host: api.xiaoyaos.com

响应参数：

参数	类型	说明
id	String	店铺ID
shop_name	String	店铺名称
phone	String	联系电话
address	String	店铺地址
business_hours	String	营业时间
qrcode_url	String	二维码URL

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1234567890123456789",
    "shop_name": "XX电脑城",
    "phone": "13812345678",
    "address": "北京市朝阳区XX路XX号",
    "business_hours": "9:00 - 21:00",
    "qrcode_url": "https://oss.aliyun.com/qrcode/xxx.png"
  },
  "timestamp": 1703232000000
}

2.2.3 获取店铺预算区间

接口地址： GET /api/user/shop/{shop_id}/price-ranges

接口说明： 获取店铺建议的预算区间（根据SKU价格分布动态生成）

路径参数：

参数	类型	必填	说明
shop_id	String	是	店铺ID（对应merchant表的shop_id字段）

请求示例：

GET /api/user/shop/shop_12345678901234567890/price-ranges HTTP/1.1
Host: api.xiaoyaos.com

响应参数：

参数	类型	说明
price_ranges	Array	预算区间列表（4个区间）

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "price_ranges": [
      "1500-2500元",
      "2500-3500元",
      "3500-4500元",
      "4500元以上"
    ]
  },
  "timestamp": 1703232000000
}

区间生成规则：

SKU价格分布	生成的区间
无SKU	3000-5000元、5000-8000元、8000-12000元、12000元以上
所有SKU价格相同（如2500元）	1500-2500元、2500-3500元、3500-4500元、4500元以上
价格区间 < 500元	以平均价格为中心，1000元步长浮动
价格区间 500-2000元	4等分窄区间
价格区间 2000-5000元	4等分中等区间
价格区间 5000-15000元	固定宽区间（3000/4000/5000）
价格区间 ≥ 15000元	大区间（5000/10000/15000）

3. B端接口（商家端）

3.1 认证模块

3.1.1 商家注册

接口地址： POST /api/mer/auth/register

接口说明： 注册商家账号

请求参数：

参数	类型	必填	说明
username	String	是	用户名（3-20字符，字母数字下划线）
password	String	是	密码（8-20字符，含大小写字母+数字）
shop_name	String	是	店铺名称（2-50字符）
phone	String	是	联系电话（11位手机号）
address	String	否	店铺地址
business_hours	String	否	营业时间（默认：9:00-21:00）

请求示例：

{
  "username": "shop_admin",
  "password": "Password123!",
  "shop_name": "XX电脑城",
  "phone": "13812345678",
  "address": "北京市朝阳区XX路XX号",
  "business_hours": "9:00-21:00"
}

响应参数：

参数	类型	说明
token	String	JWT Token
user	Object	用户信息

user对象结构：

参数	类型	说明
id	String	商家ID（雪花算法生成的20位整数）
username	String	用户名
shop_name	String	店铺名称
shop_id	String	店铺ID（如 shop_12345678901234567890）
share_link	String	完整分享链接
membership_expiry	String	会员到期时间（ISO 8601格式，null表示未开通会员）

响应示例：

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "1234567890123456789",
      "username": "shop_admin",
      "shop_name": "XX电脑城",
      "shop_id": "shop_12345678901234567890",
      "share_link": "https://peipei.xiaoyaos.com/?shop=shop_12345678901234567890",
      "membership_expiry": null
    }
  },
  "timestamp": 1703232000000
}

3.1.2 商家登录

接口地址： POST /api/mer/auth/login

接口说明： 商家登录

请求参数：

参数	类型	必填	说明
username	String	是	用户名
password	String	是	密码

请求示例：

{
  "username": "shop_admin",
  "password": "Password123!"
}

响应参数：

参数	类型	说明
token	String	JWT Token
user	Object	用户信息

user对象结构：

参数	类型	说明
id	String	商家ID
username	String	用户名
shop_name	String	店铺名称
phone	String	联系电话
shop_id	String	店铺ID
share_link	String	完整分享链接
membership_expiry	String	会员到期时间（null表示未开通会员）
is_membership_expired	Boolean	会员是否已过期
show_expiry_warning	Boolean	是否显示到期提醒（7天内到期）

响应示例：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "1234567890123456789",
      "username": "shop_admin",
      "shop_name": "XX电脑城",
      "phone": "13812345678",
      "shop_id": "shop_12345678901234567890",
      "share_link": "https://peipei.xiaoyaos.com/?shop=shop_12345678901234567890",
      "membership_expiry": null,
      "is_membership_expired": false,
      "show_expiry_warning": false
    }
  },
  "timestamp": 1703232000000
}

3.1.3 获取当前用户信息

接口地址： GET /api/mer/auth/me

接口说明： 获取当前登录用户信息

请求头：

Authorization: Bearer {token}

响应参数：

参数	类型	说明
id	String	商家ID
username	String	用户名
shop_name	String	店铺名称
phone	String	联系电话
address	String	店铺地址
business_hours	String	营业时间
qrcode_url	String	二维码URL
shop_id	String	店铺ID
share_link	String	完整分享链接
membership_expiry	String	会员到期时间（null表示未开通会员）
is_membership_expired	Boolean	会员是否已过期
show_expiry_warning	Boolean	是否显示到期提醒（7天内到期）
status	String	账号状态（active/inactive）
created_at	String	创建时间
updated_at	String	更新时间

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1234567890123456789",
    "username": "shop_admin",
    "shop_name": "XX电脑城",
    "phone": "13812345678",
    "address": "北京市朝阳区XX路XX号",
    "business_hours": "9:00-21:00",
    "qrcode_url": "https://oss.aliyun.com/qrcode/xxx.png",
    "shop_id": "shop_12345678901234567890",
    "share_link": "https://peipei.xiaoyaos.com/?shop=shop_12345678901234567890",
    "membership_expiry": null,
    "is_membership_expired": false,
    "show_expiry_warning": false,
    "status": "active",
    "created_at": "2025-12-22T10:00:00Z",
    "updated_at": "2025-12-22T10:00:00Z"
  },
  "timestamp": 1703232000000
}

3.1.4 修改密码

接口地址： PUT /api/mer/auth/password

接口说明： 修改登录密码

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
old_password	String	是	旧密码
new_password	String	是	新密码（8-20字符，含大小写字母+数字）

请求示例：

{
  "old_password": "Password123!",
  "new_password": "NewPassword456!"
}

响应示例：

{
  "code": 200,
  "message": "密码修改成功",
  "timestamp": 1703232000000
}

3.1.5 更新商家信息

接口地址： PUT /api/mer/auth/me

接口说明： 更新商家基本信息

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
shop_name	String	否	店铺名称（2-50字符）
phone	String	否	联系电话（11位手机号）
address	String	否	店铺地址
business_hours	String	否	营业时间

请求示例：

{
  "shop_name": "XX电脑城",
  "phone": "13812345678",
  "address": "北京市朝阳区XX路XX号",
  "business_hours": "9:00-21:00"
}

响应示例：

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": "1234567890123456789",
    "username": "shop_admin",
    "shop_name": "XX电脑城",
    "phone": "13812345678",
    "address": "北京市朝阳区XX路XX号",
    "business_hours": "9:00-21:00",
    "shop_id": "shop_12345678901234567890",
    "share_link": "https://peipei.xiaoyaos.com/?shop=shop_12345678901234567890",
    "updated_at": "2025-12-22T10:00:00Z"
  },
  "timestamp": 1703232000000
}

3.1.6 商家登出

接口地址： POST /api/mer/auth/logout

接口说明： 商家登出（客户端清除Token）

请求头：

Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "登出成功",
  "timestamp": 1703232000000
}

3.1.7 会员续期

接口地址： POST /api/mer/auth/membership/renew

接口说明： 续期会员账号（即使会员过期也可调用此接口）

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
days	Integer	是	续期天数（1-365）

请求示例：

{
  "days": 30
}

响应参数：

参数	类型	说明
membership_expiry	String	续期后的会员到期时间

响应示例：

{
  "code": 200,
  "message": "续期成功",
  "data": {
    "membership_expiry": "2026-02-22T10:00:00Z"
  },
  "timestamp": 1703232000000
}

3.2 首页看板模块

3.2.1 获取首页看板数据

接口地址： GET /api/mer/dashboard

接口说明： 获取首页看板完整数据（今日统计、趋势、分布等）

请求头：

Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "today_stats": {
      "consult_count": 23,
      "lead_count": 15,
      "conversion_rate": 0.652,
      "consult_trend": 15.5,
      "lead_trend": -10.2,
      "conversion_trend": 8.3
    },
    "trend_data": {
      "dates": ["12-16", "12-17", "12-18", "12-19", "12-20", "12-21", "12-22"],
      "scan_counts": [32, 45, 38, 52, 48, 55, 45],
      "consult_counts": [18, 23, 20, 28, 25, 30, 23],
      "lead_counts": [10, 15, 12, 18, 14, 16, 15]
    },
    "device_type_distribution": {
      "laptop": 14,
      "desktop": 7,
      "aio": 2
    },
    "budget_distribution": {
      "3000-5000": 5,
      "5000-8001": 10,
      "8001-12000": 6,
      "12000+": 2
    },
    "top_skus": [
      {
        "id": "1234567890123456790",
        "name": "联想拯救者Y7000P",
        "view_count": 45,
        "select_count": 12,
        "conversion_rate": 0.267
      }
    ]
  },
  "timestamp": 1703232000000
}

响应字段说明：

字段	类型	说明
consult_count	Integer	今日咨询数
lead_count	Integer	今日线索数
conversion_rate	Float	今日转化率（线索数/咨询数）
consult_trend	Float	咨询数趋势（较昨日，百分比）
lead_trend	Float	线索数趋势（较昨日，百分比）
conversion_trend	Float	转化率趋势（较昨日，百分比）

趋势值说明：

正数：较昨日增长
负数：较昨日下降
0：与昨日持平

3.2.2 获取趋势数据

接口地址： GET /api/mer/dashboard/trends

接口说明： 获取指定天数的趋势数据

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	默认值	说明
days	Integer	否	7	统计天数（最大30）

请求示例：

GET /api/mer/dashboard/trends?days=7 HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "dates": ["12-16", "12-17", "12-18", "12-19", "12-20", "12-21", "12-22"],
    "scan_counts": [32, 45, 38, 52, 48, 55, 45],
    "consult_counts": [18, 23, 20, 28, 25, 30, 23],
    "lead_counts": [10, 15, 12, 18, 14, 16, 15]
  },
  "timestamp": 1703232000000
}

3.2.3 获取转化率统计

接口地址： GET /api/mer/dashboard/conversion

接口说明： 获取扫码→咨询→线索的转化率统计

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	默认值	说明
period	String	否	today	统计周期（today/week/month）

请求示例：

GET /api/mer/dashboard/conversion?period=today HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "scan_to_consult": 0.511,
    "consult_to_lead": 0.652,
    "scan_to_lead": 0.333,
    "period": "today"
  },
  "timestamp": 1703232000000
}

3.2.4 获取热门配置排行

接口地址： GET /api/mer/dashboard/top-skus

接口说明： 获取热门配置排行

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	默认值	说明
limit	Integer	否	10	返回数量（最大50）

请求示例：

GET /api/mer/dashboard/top-skus?limit=10 HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "top_skus": [
      {
        "id": "1234567890123456790",
        "name": "联想拯救者Y7000P",
        "device_type": "笔记本",
        "brand": "联想",
        "price": 7499.00,
        "view_count": 45,
        "select_count": 12,
        "conversion_rate": 0.267
      },
      {
        "id": "1234567890123456791",
        "name": "华硕天选4",
        "device_type": "笔记本",
        "brand": "华硕",
        "price": 6999.00,
        "view_count": 38,
        "select_count": 10,
        "conversion_rate": 0.263
      }
    ]
  },
  "timestamp": 1703232000000
}

3.2.5 获取单个SKU统计

接口地址： GET /api/mer/dashboard/sku-stats

接口说明： 获取指定配置的查看/选择/转化数据

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
sku_id	String	是	配置ID（雪花算法生成的20位整数）

请求示例：

GET /api/mer/dashboard/sku-stats?sku_id=1234567890123456790 HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "sku_id": "1234567890123456790",
    "name": "联想拯救者Y7000P",
    "view_count": 45,
    "select_count": 12,
    "conversion_rate": 0.267,
    "trend_data": {
      "dates": ["12-16", "12-17", "12-18", "12-19", "12-20", "12-21", "12-22"],
      "view_counts": [5, 8, 6, 9, 7, 10, 45],
      "select_counts": [1, 2, 2, 3, 2, 2, 12]
    }
  },
  "timestamp": 1703232000000
}

3.2.6 获取业绩统计

接口地址： GET /api/mer/dashboard/performance

接口说明： 获取商家整体业绩数据

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	默认值	说明
period	String	否	today	统计周期（today/week/month）

请求示例：

GET /api/mer/dashboard/performance?period=week HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "period": "week",
    "total_scans": 312,
    "total_consults": 156,
    "total_leads": 89,
    "conversion_rate": 0.571,
    "comparison_with_last_period": 0.125,
    "device_type_stats": {
      "laptop": 56,
      "desktop": 24,
      "aio": 9
    }
  },
  "timestamp": 1703232000000
}

3.3 SKU管理模块

3.2.1 获取配置列表

接口地址： GET /api/mer/skus

接口说明： 获取商家的配置列表（分页）

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	默认值	说明
device_type	String	否	-	设备类型（desktop/laptop/aio）
status	String	否	-	状态（active/inactive）
search	String	否	-	搜索关键词（名称/品牌/型号）
page	Integer	否	1	页码
limit	Integer	否	10	每页数量

请求示例：

GET /api/mer/skus?device_type=laptop&status=active&page=1&limit=10&search=拯救者 HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "1234567890123456790",
        "name": "联想拯救者Y7000P",
        "device_type": "laptop",
        "brand": "联想",
        "price": 7499.00,
        "stock": 5,
        "status": "active",
        "tags": ["gaming", "brand"],
        "images": ["https://oss.aliyun.com/images/sku1_1.jpg"],
        "view_count": 45,
        "select_count": 12,
        "created_at": "2025-12-22T10:00:00Z"
      }
    ],
    "total": 23,
    "page": 1,
    "limit": 10,
    "pages": 3
  },
  "timestamp": 1703232000000
}

3.2.2 获取配置详情

接口地址： GET /api/mer/skus/{id}

接口说明： 获取指定配置的详细信息

请求头：

Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	String	是	配置ID（雪花算法生成的20位整数）

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1234567890123456790",
    "merchant_id": "1234567890123456789",
    "device_type": "laptop",
    "name": "联想拯救者Y7000P",
    "brand": "联想",
    "model": "Y7000P 2023款",
    "cpu": "i7-12700H",
    "gpu": "RTX 4060 8G",
    "ram": "16GB DDR5",
    "storage": "512GB SSD",
    "screen": "15.6英寸 2.5K 165Hz",
    "weight": "2.4kg",
    "battery": "5-6小时",
    "price": 7499.00,
    "stock": 5,
    "status": "active",
    "tags": ["gaming", "brand", "high-performance"],
    "images": [
      "https://oss.aliyun.com/images/sku1_1.jpg",
      "https://oss.aliyun.com/images/sku1_2.jpg"
    ],
    "view_count": 45,
    "select_count": 12,
    "created_at": "2025-12-22T10:00:00Z",
    "updated_at": "2025-12-22T10:00:00Z"
  },
  "timestamp": 1703232000000
}

3.2.3 添加配置

接口地址： POST /api/mer/skus

接口说明： 添加新的电脑配置

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
device_type	String	是	设备类型（desktop/laptop/aio）
name	String	是	配置名称（2-100字符）
brand	String	是	品牌（2-50字符）
model	String	否	型号
cpu	String	是	处理器
gpu	String	否	显卡
ram	String	是	内存
storage	String	是	存储
motherboard	String	否	主板（台式机）
power_supply	String	否	电源（台式机）
case	String	否	机箱（台式机）
screen	String	否	屏幕（笔记本/一体机）
weight	String	否	重量（笔记本）
battery	String	否	续航（笔记本）
price	Decimal	是	价格（大于0）
stock	Integer	是	库存（大于等于0）
tags	Array	否	标签数组
images	Array	否	图片URL数组

请求示例：

{
  "device_type": "laptop",
  "name": "联想拯救者Y7000P",
  "brand": "联想",
  "model": "Y7000P 2023款",
  "cpu": "i7-12700H",
  "gpu": "RTX 4060 8G",
  "ram": "16GB DDR5",
  "storage": "512GB SSD",
  "screen": "15.6英寸 2.5K 165Hz",
  "weight": "2.4kg",
  "battery": "5-6小时",
  "price": 7499.00,
  "stock": 5,
  "tags": ["gaming", "brand"],
  "images": [
    "https://oss.aliyun.com/images/sku1_1.jpg",
    "https://oss.aliyun.com/images/sku1_2.jpg"
  ]
}

响应示例：

{
  "code": 200,
  "message": "添加成功",
  "data": {
    "id": "1234567890123456790",
    "name": "联想拯救者Y7000P"
  },
  "timestamp": 1703232000000
}

3.2.4 编辑配置

接口地址： PUT /api/mer/skus/{id}

接口说明： 编辑指定配置

请求头：

Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	String	是	配置ID（雪花算法生成的20位整数）

请求参数：（所有字段可选，只传需要修改的字段）

参数	类型	必填	说明
name	String	否	配置名称
price	Decimal	否	价格
stock	Integer	否	库存
status	String	否	状态（active/inactive）
...	...	否	其他字段同添加接口

请求示例：

{
  "price": 7299.00,
  "stock": 3
}

响应示例：

{
  "code": 200,
  "message": "修改成功",
  "timestamp": 1703232000000
}

3.2.5 删除配置

接口地址： DELETE /api/mer/skus/{id}

接口说明： 删除指定配置

请求头：

Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	String	是	配置ID（雪花算法生成的20位整数）

响应示例：

{
  "code": 200,
  "message": "删除成功",
  "timestamp": 1703232000000
}

3.2.6 批量删除配置

接口地址： DELETE /api/mer/skus

接口说明： 批量删除配置

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
ids	Array	是	配置ID数组（整数数组）

请求示例：

{
  "ids": [1234567890123456790, 1234567890123456791]
}

响应示例：

{
  "code": 200,
  "message": "批量删除成功，成功2个，失败0个",
  "data": {
    "success_count": 2,
    "failed_count": 0
  },
  "timestamp": 1703232000000
}

3.3.7 获取SKU统计信息

接口地址： GET /api/mer/skus/stats/summary

接口说明： 获取SKU数量统计（总数、按设备类型、按状态）

请求头：

Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 23,
    "active_count": 18,
    "inactive_count": 5,
    "device_type_stats": {
      "desktop": 8,
      "laptop": 12,
      "aio": 3
    }
  },
  "timestamp": 1703232000000
}

3.4 线索管理模块

3.3.1 获取线索列表

接口地址： GET /api/mer/leads

接口说明： 获取客户线索列表（分页）

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	默认值	说明
status	String	否	-	状态（pending/contacted/closed/abandoned）
device_type	String	否	-	设备类型（desktop/laptop/aio）
start_date	String	否	-	开始日期（YYYY-MM-DD）
end_date	String	否	-	结束日期（YYYY-MM-DD）
search	String	否	-	搜索关键词（手机号/微信号）
page	Integer	否	1	页码
limit	Integer	否	10	每页数量

请求示例：

GET /api/mer/leads?status=pending&device_type=laptop&page=1&limit=10 HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应参数：

参数	类型	说明
id	String	线索ID
phone	String	脱敏手机号（如：138****5678）
phone_full	String	完整明文手机号（用于复制功能）
wechat	String	微信号
budget	String	预算
device_type	String	设备类型
usage	String	用途
requirements	String	具体需求
selected_sku	Object	选中的配置
status	String	线索状态
created_at	String	创建时间

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "1234567890123456792",
        "phone": "138****5678",
        "phone_full": "13812345678",
        "wechat": "user_wechat",
        "budget": "6000左右",
        "device_type": "laptop",
        "usage": "游戏",
        "requirements": "玩原神",
        "selected_sku": {
          "id": "1234567890123456790",
          "name": "联想拯救者Y7000P",
          "price": 7499.00
        },
        "status": "pending",
        "created_at": "2025-12-22T14:30:00Z"
      }
    ],
    "total": 15,
    "page": 1,
    "limit": 10,
    "pages": 2
  },
  "timestamp": 1703232000000
}

3.3.2 获取线索详情

接口地址： GET /api/mer/leads/{id}

接口说明： 获取指定线索的详细信息（包含解密后的手机号、微信号）

请求头：

Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	String	是	线索ID（雪花算法生成的20位整数）

响应参数：

参数	类型	说明
id	String	线索ID
phone	String	明文手机号
wechat	String	明文微信号
remark	String	客户备注
budget	String	预算
device_type	String	设备类型
usage	String	用途
requirements	String	具体需求
selected_sku	Object	选中的配置信息
conversation	Object	对话基本信息
notes	Array	跟进记录列表
status	String	线索状态
created_at	String	创建时间
updated_at	String	更新时间

selected_sku 对象结构：

参数	类型	说明
id	String	配置ID
name	String	配置名称
price	Decimal	价格

conversation 对象结构：

参数	类型	说明
id	String	对话ID
session_id	String	会话ID
status	String	对话状态
created_at	String	创建时间

notes 数组元素结构：

参数	类型	说明
id	String	备注ID
content	String	备注内容
created_by	String	创建商家ID
created_at	String	创建时间

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1234567890123456792",
    "phone": "13812345678",
    "wechat": "user_wechat",
    "remark": "希望尽快联系",
    "budget": "6000左右",
    "device_type": "laptop",
    "usage": "游戏",
    "requirements": "玩原神",
    "selected_sku": {
      "id": "1234567890123456790",
      "name": "联想拯救者Y7000P",
      "price": 7499.00
    },
    "conversation": {
      "id": "1234567890123456791",
      "session_id": "session_abc123",
      "status": "completed",
      "created_at": "2025-12-22T14:30:00Z"
    },
    "notes": [
      {
        "id": "1234567890123456793",
        "content": "已电话沟通，客户表示很满意，明天来店看实物",
        "created_by": "1234567890123456789",
        "created_at": "2025-12-22T14:35:00Z"
      }
    ],
    "status": "pending",
    "created_at": "2025-12-22T14:30:00Z",
    "updated_at": "2025-12-22T14:35:00Z"
  },
  "timestamp": 1703232000000
}

3.3.3 获取线索对话消息

接口地址： GET /api/mer/leads/{id}/messages

接口说明： 获取线索关联的完整对话消息记录

请求头：

Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	String	是	线索ID（雪花算法生成的20位整数）

响应参数：

参数	类型	说明
conversation_id	String	对话ID
items	Array	消息列表
total	Integer	消息总数

items 数组元素结构：

参数	类型	说明
id	String	消息ID
role	String	角色（assistant=小遥，user=客户）
content	String	消息内容
created_at	String	创建时间

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "conversation_id": "1234567890123456791",
    "items": [
      {
        "id": "1234567890123456801",
        "role": "assistant",
        "content": "您好！我是小遥，我来帮您选一台合适的电脑～请问您的预算大概是多少呢？",
        "created_at": "2025-12-22T14:30:15Z"
      },
      {
        "id": "1234567890123456802",
        "role": "user",
        "content": "我想要一台6000左右的游戏笔记本能玩原神",
        "created_at": "2025-12-22T14:30:42Z"
      },
      {
        "id": "1234567890123456803",
        "role": "assistant",
        "content": "明白了！6000左右的游戏笔记本，玩原神完全够用～您需要经常携带吗？",
        "created_at": "2025-12-22T14:30:45Z"
      }
    ],
    "total": 3
  },
  "timestamp": 1703232000000
}

3.3.4 修改线索状态

接口地址： PUT /api/mer/leads/{id}/status

接口说明： 修改线索状态

请求头：

Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	String	是	线索ID（雪花算法生成的20位整数）

请求参数：

参数	类型	必填	说明
status	String	是	状态（pending/contacted/closed/abandoned）

请求示例：

{
  "status": "contacted"
}

响应示例：

{
  "code": 200,
  "message": "状态修改成功",
  "timestamp": 1703232000000
}

3.3.5 添加跟进备注

接口地址： POST /api/mer/leads/{id}/notes

接口说明： 为线索添加跟进备注

请求头：

Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	String	是	线索ID（雪花算法生成的20位整数）

请求参数：

参数	类型	必填	说明
content	String	是	备注内容（1-500字符）

请求示例：

{
  "content": "已电话沟通，客户表示很满意，明天来店看实物"
}

响应示例：

{
  "code": 200,
  "message": "备注添加成功",
  "timestamp": 1703232000000
}

3.3.6 获取跟进记录

接口地址： GET /api/mer/leads/{id}/notes

接口说明： 获取指定线索的所有跟进记录

请求头：

Authorization: Bearer {token}

路径参数：

参数	类型	必填	说明
id	String	是	线索ID（雪花算法生成的20位整数）

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "notes": [
      {
        "id": "1234567890123456793",
        "content": "已电话沟通，客户表示很满意，明天来店看实物",
        "created_at": "2025-12-22T14:35:00Z"
      },
      {
        "id": "1234567890123456794",
        "content": "客户已到店，实际体验了机器，最终下单了",
        "created_at": "2025-12-23T10:15:00Z"
      }
    ]
  },
  "timestamp": 1703232000000
}

3.3.7 获取线索统计信息

接口地址： GET /api/mer/leads/stats/summary

接口说明： 获取线索数量统计（总数、按状态、按设备类型）

请求头：

Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "total_count": 89,
    "pending_count": 35,
    "contacted_count": 28,
    "closed_count": 18,
    "abandoned_count": 8,
    "device_type_stats": {
      "desktop": 32,
      "laptop": 48,
      "aio": 9
    },
    "today_count": 15,
    "week_count": 89,
    "month_count": 245
  },
  "timestamp": 1703232000000
}

3.5 分享管理模块

3.4.1 获取专属二维码

接口地址： GET /api/mer/share/qrcode

接口说明： 获取商家专属二维码和分享链接

请求头：

Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "qrcode_url": "https://oss.aliyun.com/qrcode/xxx.png",
    "shop_id": "shop_12345678901234567890",
    "share_link": "https://peipei.xiaoyaos.com/?shop=shop_12345678901234567890"
  },
  "timestamp": 1703232000000
}

3.4.2 生成分享海报

接口地址： POST /api/mer/share/poster

接口说明： 生成分享海报

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
template_id	String	是	模板ID（template_1/template_2/template_3）

请求示例：

{
  "template_id": "template_1"
}

响应示例：

{
  "code": 200,
  "message": "海报生成成功",
  "data": {
    "poster_url": "https://oss.aliyun.com/poster/xxx.png"
  },
  "timestamp": 1703232000000
}

3.4.3 获取分享统计

接口地址： GET /api/mer/share/stats

接口说明： 获取分享数据统计

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	默认值	说明
period	String	否	today	统计周期（today/week/month）

请求示例：

GET /api/mer/share/stats?period=today HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "scan_count": 45,
    "consult_count": 23,
    "lead_count": 15,
    "conversion_rate": 0.511,
    "device_type_stats": {
      "laptop": 14,
      "desktop": 7,
      "aio": 2
    },
    "budget_stats": {
      "3000-5000": 5,
      "5000-8001": 10,
      "8001-12000": 6,
      "12000+": 2
    }
  },
  "timestamp": 1703232000000
}

3.5.4 刷新二维码

接口地址： POST /api/mer/share/qrcode/refresh

接口说明： 刷新商家专属二维码（生成新的二维码）

请求头：

Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "二维码刷新成功",
  "data": {
    "qrcode_url": "https://oss.aliyun.com/qrcode/xxx_new.png",
    "shop_id": "shop_12345678901234567890",
    "share_link": "https://peipei.xiaoyaos.com/?shop=shop_12345678901234567890"
  },
  "timestamp": 1703232000000
}

3.5.5 获取分享统计趋势

接口地址： GET /api/mer/share/stats/trend

接口说明： 获取分享数据趋势统计

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	默认值	说明
days	Integer	否	7	统计天数（最大30）

请求示例：

GET /api/mer/share/stats/trend?days=7 HTTP/1.1
Host: api.xiaoyaos.com
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "dates": ["12-16", "12-17", "12-18", "12-19", "12-20", "12-21", "12-22"],
    "scan_counts": [32, 45, 38, 52, 48, 55, 45],
    "consult_counts": [18, 23, 20, 28, 25, 30, 23],
    "lead_counts": [10, 15, 12, 18, 14, 16, 15],
    "conversion_rates": [0.313, 0.333, 0.316, 0.346, 0.292, 0.291, 0.333]
  },
  "timestamp": 1703232000000
}

3.5.6 记录扫码行为

接口地址： POST /api/mer/share/stats/scan

接口说明： 记录用户扫码行为（C端调用）

请求参数：

参数	类型	必填	说明
shop_id	String	是	店铺ID（雪花算法生成的20位整数）

请求示例：

{
  "shop_id": "1234567890123456789"
}

响应示例：

{
  "code": 200,
  "message": "扫码记录成功",
  "timestamp": 1703232000000
}

3.6 文件上传模块

说明：本模块使用 OSS 直传方式，前端通过 STS 临时凭证直接上传文件到阿里云 OSS。

3.6.1 获取OSS直传凭证 ⭐

接口地址： GET /api/mer/upload/oss/token

接口说明： 获取OSS直传所需的 STS 临时凭证，前端使用 ali-oss SDK 直接上传文件到OSS

安全说明：

使用 STS 临时凭证，有效期1小时
必须配置 OSS_STS_ROLE_ARN
不支持永久 AccessKey 降级

请求头：

Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "region": "cn-shanghai",
    "bucket": "xiaoyaos-file",
    "accessKeyId": "STS.NTKxxxxxxxxxxxx",
    "accessKeySecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "stsToken": "CAISjwJ1q6Ft EXAMPLE_TOKEN_VALUE",
    "endpoint": "",
    "host": "https://file.xiaoyaosai.com",
    "dir": "peipei/merchant/1234567890123456789/images/2026/01",
    "expire": 1737651200
  },
  "timestamp": 1703232000000
}

响应字段说明：

字段	类型	说明
region	String	OSS区域（如 cn-shanghai）
bucket	String	OSS Bucket名称
accessKeyId	String	STS临时AccessKey ID
accessKeySecret	String	STS临时AccessKey Secret（用于签名）
stsToken	String	STS Token（临时凭证令牌）
endpoint	String	OSS endpoint（空字符串，使用region）
host	String	自定义域名（文件访问URL前缀）
dir	String	上传目录前缀
expire	Integer	过期时间（Unix时间戳，秒）

前端使用示例：

// 1. 获取STS临时凭证
const res = await getOSSUploadToken()
const { region, bucket, accessKeyId, accessKeySecret, stsToken, host, dir } = res.data.data

// 2. 使用 ali-oss SDK 直传
import OSS from 'ali-oss'
const client = new OSS({
  endpoint: `https://oss-${region}.aliyuncs.com`,
  accessKeyId,
  accessKeySecret,
  stsToken,  // STS临时凭证
  bucket,
  secure: true,
})

// 3. 上传文件
const timestamp = Date.now()
const random = Math.random().toString(36).substring(2, 8)
const ext = file.name.split('.').pop()
const filename = `${dir}/${timestamp}_${random}.${ext}`
const result = await client.put(filename, file)

// 4. 构建文件URL（使用自定义域名）
const fileUrl = `${host}/${filename}`

3.6.2 OSS上传回调

接口地址： POST /api/mer/upload/oss/callback

接口说明： OSS直传成功后的回调接口（可选），用于记录上传成功的文件信息

请求头：

Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
key	String	是	OSS文件路径
size	Integer	是	文件大小（字节）
name	String	是	原始文件名
etag	String	否	文件ETag

请求示例：

{
  "key": "peipei/merchant/1234567890123456789/images/2026/01/1234567890_abc123.jpg",
  "size": 102400,
  "name": "image.jpg",
  "etag": "D9A8E7F6C5B4A3D2"
}

响应示例：

{
  "code": 200,
  "message": "回调成功",
  "data": {
    "url": "https://file.xiaoyaosai.com/peipei/merchant/1234567890123456789/images/2026/01/1234567890_abc123.jpg",
    "key": "peipei/merchant/1234567890123456789/images/2026/01/1234567890_abc123.jpg",
    "size": 102400,
    "name": "image.jpg"
  },
  "timestamp": 1703232000000
}

4. 错误码说明

4.1 HTTP状态码

状态码	说明
200	请求成功
400	请求参数错误
401	未授权（Token无效或过期）
403	禁止访问（权限不足）
404	资源不存在
429	请求过于频繁
500	服务器内部错误

4.2 业务错误码

错误码	说明
1001	参数校验失败
1002	用户名已存在
1003	用户名或密码错误
1004	Token无效或过期
1005	权限不足
2001	商家不存在
2002	配置不存在
2003	线索不存在
2004	对话不存在
2005	会员已过期
3001	AI服务调用失败
3002	文件上传失败
3003	文件格式不支持
3004	文件大小超限
4001	数据库操作失败
4002	缓存操作失败
5001	系统繁忙，请稍后重试

4.3 错误响应示例

示例1：参数校验失败

{
  "code": 1001,
  "message": "参数校验失败：手机号格式不正确",
  "data": null,
  "timestamp": 1703232000000,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

示例2：会员已过期

{
  "code": 2005,
  "message": "会员已过期，请联系客服续期",
  "data": {
    "contact_wechat": "dtsola",
    "contact_name": "小遥配配客服",
    "message": "请添加微信客服咨询续费事宜"
  },
  "timestamp": 1703232000000,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

5. 附录

5.1 枚举值说明

设备类型（device_type）

值	说明
desktop	台式机
laptop	笔记本
aio	一体机

状态（status）

值	说明
active	激活/启用
inactive	停用/禁用

对话状态（conversation_status）

值	说明
active	进行中
completed	已完成（已提交线索）
abandoned	已放弃（超时未操作）

线索状态（lead_status）

值	说明
pending	待处理
contacted	已联系
closed	已成交
abandoned	已放弃

来源（source）

值	说明
qrcode	二维码扫码
link	分享链接

5.2 限流规则

接口类型	限流规则
C端接口	每IP每分钟10次
B端接口（查询）	每用户每分钟60次
B端接口（写入）	每用户每分钟30次
文件上传	每用户每分钟5次

5.3 数据格式规范

日期时间格式

ISO 8601格式：2025-12-22T14:30:00Z
时区：UTC+8（Asia/Shanghai）

金额格式

类型：Decimal
精度：保留2位小数
示例：7499.00

手机号格式

格式：11位数字
示例：13812345678

ID格式

类型：String（雪花算法生成的20位整数）
示例："1234567890123456789"

5.4 项目地址规划

项目	地址
开发环境API	`http://localhost:8001`
开发环境C端	`http://localhost:3000`
开发环境B端	`http://localhost:3001`
测试环境API	`https://test-api.xiaoyaos.com/peipei`
测试环境C端	`https://test-peipei.xiaoyaos.com`
测试环境B端	`https://test-peipei-mer.xiaoyaos.com`
生产环境API	`https://api.xiaoyaos.com/peipei`
生产环境C端	`https://peipei.xiaoyaos.com`
生产环境B端	`https://peipei-mer.xiaoyaos.com`

测试账号

用户名：test
密码：123456

文档维护： 技术团队 联系方式： tech@xiaoyaos.com 最后更新： 2026-02-25 (v2.0 - 新增 B端接口 3.3.3 获取线索对话消息，用于在线索详情页展示完整对话记录)

FilesExpand file tree

接口文档.md

Latest commit

History

接口文档.md

File metadata and controls

小遥配配 - API接口设计文档

文档信息

API环境配置

目录

B端接口目录

认证模块接口目录

1. 通用说明

1.1 请求规范

请求头（Request Headers）

请求示例

1.2 响应规范

统一响应格式

响应字段说明

1.3 分页规范

分页请求参数

分页响应格式

1.4 认证说明

B端接口认证

请求示例

2. C端接口（用户端）

2.1 对话模块

2.1.1 发送消息（AI意图识别）

2.1.2 获取推荐方案

2.1.3 获取对话历史

2.2 线索模块

2.2.1 提交客户线索

2.2.2 获取店铺信息

2.2.3 获取店铺预算区间

3. B端接口（商家端）

3.1 认证模块

3.1.1 商家注册

3.1.2 商家登录

3.1.3 获取当前用户信息

3.1.4 修改密码

3.1.5 更新商家信息

3.1.6 商家登出

3.1.7 会员续期

3.2 首页看板模块

3.2.1 获取首页看板数据

3.2.2 获取趋势数据

3.2.3 获取转化率统计

3.2.4 获取热门配置排行

3.2.5 获取单个SKU统计

3.2.6 获取业绩统计

3.3 SKU管理模块

3.2.1 获取配置列表

3.2.2 获取配置详情

3.2.3 添加配置

3.2.4 编辑配置

3.2.5 删除配置

3.2.6 批量删除配置

3.3.7 获取SKU统计信息

3.4 线索管理模块

3.3.1 获取线索列表

3.3.2 获取线索详情

3.3.3 获取线索对话消息

3.3.4 修改线索状态

3.3.5 添加跟进备注

3.3.6 获取跟进记录

3.3.7 获取线索统计信息

3.5 分享管理模块

3.4.1 获取专属二维码

3.4.2 生成分享海报

3.4.3 获取分享统计

3.5.4 刷新二维码

3.5.5 获取分享统计趋势

3.5.6 记录扫码行为

3.6 文件上传模块

3.6.1 获取OSS直传凭证 ⭐

3.6.2 OSS上传回调

4. 错误码说明

4.1 HTTP状态码

4.2 业务错误码

4.3 错误响应示例