6.8 KiB

Raw Blame History

Merchant AI HTTP API 调用说明

本文档用于喂给外部“解读 AI”或其他服务平台，让 AI 在对话中正确调用本项目的 HTTP JSON API 进行订单统计、线下订单分析和商户排行分析。

1. 服务定位

本项目是一个中间层 HTTP JSON API 服务。AI 不直接请求后台订单系统，也不直接拼接后台订单接口参数。

本项目负责：

接收 AI 的结构化分析请求
解析时间意图
调用后台订单接口
复用本项目内部统计逻辑
返回适合 AI 解读的 JSON 结果

2. 启动方式

本地开发启动：

php -S 127.0.0.1:8080 -t public public/index.php

健康检查：

GET http://127.0.0.1:8080/health

正常返回：

{
  "success": true,
  "data": {
    "status": "ok",
    "service": "merchant-ai-api"
  }
}

3. 接口列表

3.1 订单汇总

POST /api/order-summary

对应工具：get_order_summary

用途：订单总数、活跃商户数、成功订单数、订单金额合计、实付金额合计。

3.2 线下订单分析

POST /api/offline-stats

对应工具：get_offline_stats

用途：订单状态分布、支付方式分布、订单类型分布、平均订单金额、平均实付金额、最大订单金额。

3.3 商户排行榜

POST /api/merchant-ranking

对应工具：get_merchant_ranking

用途：按订单数、成功订单数、订单金额或实付金额生成商户排行。

4. 请求格式

所有统计接口都使用：

Content-Type: application/json

统一请求示例：

{
  "timePreset": "today",
  "status": -1,
  "keyword": "",
  "fieldKey": "all",
  "payType": "",
  "type": "",
  "btcId": null
}

5. 时间参数规则

AI 应优先传 timePreset，不要直接传自然语言时间。

值	含义
`today`	今天
`yesterday`	昨天
`last_7_days`	最近 7 天，包含今天
`last_30_days`	最近 30 天，包含今天
`this_week`	本周，周一到今天
`last_week`	上周，周一到周日
`this_month`	本月，1 号到今天
`last_month`	上月，1 号到月末
`custom`	自定义时间范围

6. AI 对话到接口参数映射

用户说“今天订单怎么样？”时调用：

{
  "timePreset": "today"
}

推荐接口：POST /api/order-summary

用户说“分析一下昨天线下订单”时调用：

{
  "timePreset": "yesterday"
}

推荐接口：POST /api/offline-stats

用户说“看本月商户排行”时调用：

{
  "timePreset": "this_month",
  "sortBy": "totalRealPay",
  "limit": 10
}

推荐接口：POST /api/merchant-ranking

用户说“查 6 月 1 日到 6 月 23 日订单统计”时调用：

{
  "timePreset": "custom",
  "startDate": "2026-06-01",
  "endDate": "2026-06-23"
}

推荐接口：POST /api/order-summary

7. 常用筛选参数

参数	类型	说明
`status`	integer	订单状态，默认 `-1` 表示全部
`keyword`	string	搜索关键词，当前会传给后台接口的 `real_name`
`fieldKey`	string	搜索字段，默认 `all`
`payType`	string	支付方式，对应后台 `pay_type`
`type`	string	订单类型，对应后台 `type`
`btcId`	integer	商户分类 ID，对应后台 `btc_id`

8. 商户排行参数

/api/merchant-ranking 额外支持：

参数	类型	说明
`sortBy`	string	排序字段
`limit`	integer	返回商户数量，默认 `10`，最大 `100`

sortBy 可选值：

值	含义
`orderCount`	按订单数排序
`successOrderCount`	按成功订单数排序
`totalOrderAmount`	按订单金额排序
`totalRealPay`	按实付金额排序，默认值

9. 响应格式

成功响应：

{
  "success": true,
  "data": {}
}

失败响应：

{
  "success": false,
  "error": {
    "code": "server_error",
    "message": "错误信息"
  }
}

常见错误：

code	含义	处理方式
`not_found`	路由不存在	检查 URL
`method_not_allowed`	请求方法错误	统计接口必须使用 POST
`server_error`	服务端或后台接口异常	根据 message 排查

10. AI 调用约束

AI 必须遵守以下规则：

统计接口必须使用 POST。
不要用浏览器 GET 方式访问统计接口。
时间优先使用 timePreset。
只有用户明确给出起止日期时，才使用 timePreset=custom。
自定义日期必须使用 YYYY-MM-DD。
不要传 今天、昨天、本月 这类中文自然语言给接口。
不要伪造不存在的筛选字段。
不要把后台系统 token 暴露给用户。
不要直接调用后台订单接口，只调用本项目 HTTP API。
如果用户问题不包含时间，默认使用 timePreset=today。

11. PowerShell 调用示例

订单汇总：

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8080/api/order-summary" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"timePreset":"today"}'

线下订单分析：

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8080/api/offline-stats" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"timePreset":"yesterday"}'

商户排行：

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8080/api/merchant-ranking" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"timePreset":"this_month","sortBy":"totalRealPay","limit":10}'

12. 推荐给 AI 的简短系统提示词

你需要通过 Merchant AI HTTP API 分析订单数据。统计接口只能使用 POST。不要直接请求后台订单接口，不要暴露 token。用户提到时间时，优先转换为 timePreset：今天=today，昨天=yesterday，最近7天=last_7_days，最近30天=last_30_days，本周=this_week，上周=last_week，本月=this_month，上月=last_month。只有明确起止日期时使用 custom，并传 startDate/endDate，格式 YYYY-MM-DD。不要把“今天”“昨天”“本月”等自然语言直接作为参数传给接口。如果用户没说时间，默认 timePreset=today。

6.8 KiB Raw Blame History Unescape Escape