11 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

用途：订单状态分布、支付方式分布、订单类型分布、营销中台分布、退款状态分布、抵扣金额、手续费、diamond 字段代币值汇总、平均订单金额、平均实付金额、最大订单金额、活跃商户数、实付金额 Top 商户。

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`

7.1 `diamond` 字段与 `btc_id` 的关系

后台订单里存在 diamond 字段。该字段不是固定只表示“钻石”，需要结合 btc_id 判断业务含义：

btc_id	`diamond` 字段含义
`1`	钻石值
`3`	绿宝石值
`4`	算力值

/api/offline-stats 会返回：

字段	含义
`totalTokenValue`	所有订单 `diamond` 字段本身的合计
`tokenValueSummary`	按 `btc_id` 解释后的 `diamond` 字段汇总，例如钻石值、绿宝石值、算力值

注意：

diamond 表示本单关联/附赠/记录的代币值。
diamond_ded 表示消费券/钻石抵扣金额。
两者不是同一个字段，不要混淆。

7.2 订单状态 `status` 取值

status	含义	用户常见说法
`-1`	全部订单	全部、所有订单、不限状态
`0`	待支付	待支付、未付款、未支付订单
`1`	已完成/成功	已完成、成功订单、已支付完成
`2`	已取消	已取消、取消订单
`3`	待核销/待使用	待核销、待使用、未使用
`4`	已退款	已退款、退款订单

AI 选择规则：

用户没有提到订单状态时，必须传 status=-1。
用户问“成功订单”“已完成订单”时，传 status=1。
用户问“待支付订单”“未付款订单”时，传 status=0。
用户问“取消订单”时，传 status=2。
用户问“待核销”“待使用”时，传 status=3。
用户问“退款订单”时，传 status=4。
如果用户说“订单汇总”“今日数据”“最近7天数据”但没有限定状态，传 status=-1。

示例：

用户说“今天成功订单有多少？”时调用：

{
  "timePreset": "today",
  "status": 1
}

用户说“最近7天退款订单金额是多少？”时调用：

{
  "timePreset": "last_7_days",
  "status": 4
}

用户说“本月所有订单汇总”时调用：

{
  "timePreset": "this_month",
  "status": -1
}

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 必须严格按照接口返回的 JSON 数据解读，不允许编造、放大、补全或推测不存在的数据。

例如接口返回：

{
  "success": true,
  "data": {
    "orderCount": 100,
    "activeMerchantCount": 5,
    "successOrderCount": 47,
    "totalOrderAmount": 882.89,
    "totalRealPay": 662.39,
    "_debug_query": {
      "time": "2026/06/18-2026/06/24"
    }
  }
}

AI 只能解读为：

查询时间范围：2026/06/18-2026/06/24
当前接口返回订单数：100
活跃商户数：5
成功订单数：47
订单总金额：882.89
实付总金额：662.39

AI 可以基于已返回字段做简单计算，但必须说明是“根据当前返回数据计算”：

成功率：47 / 100 = 47%
实付占比：662.39 / 882.89 ≈ 75.03%
平均订单金额：882.89 / 100 ≈ 8.83
平均实付金额：662.39 / 100 ≈ 6.62

AI 禁止输出以下内容，除非接口明确返回：

禁止把 100 改写成 3850
禁止编造 3427 个成功订单
禁止编造 186 家商户
禁止编造 日均订单 550 单
禁止编造 日均流水 38.5 万元
禁止编造“整体交易状况良好”等过度结论
禁止把未返回的后台总数当作事实

注意：当前接口内部请求后台订单列表时使用 page=1、limit=100。因此 orderCount=100 表示当前接口本次返回并参与统计的订单数量，不应擅自推断为后台完整总订单量，除非接口后续明确返回总数。

11. AI 调用约束

AI 必须遵守以下规则：

统计接口必须使用 POST。
不要用浏览器 GET 方式访问统计接口。
时间优先使用 timePreset。
只有用户明确给出起止日期时，才使用 timePreset=custom。
自定义日期必须使用 YYYY-MM-DD。
不要传 今天、昨天、本月 这类中文自然语言给接口。
不要伪造不存在的筛选字段。
不要把后台系统 token 暴露给用户。
不要直接调用后台订单接口，只调用本项目 HTTP API。
如果用户问题不包含时间，默认使用 timePreset=today。
解读结果时只能使用接口返回的字段，不允许编造不存在的订单数、金额、商户数、日均值或趋势结论。
如果要计算成功率、平均值、占比，必须基于接口返回字段计算，并说明“根据当前返回数据计算”。
如果接口返回 _debug_query.time，可以把它作为本次查询时间范围。

12. 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}'

13. 推荐给 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。订单状态 status：全部=-1，待支付=0，已完成/成功=1，已取消=2，待核销/待使用=3，已退款=4；如果用户没有限定状态，默认 status=-1。解读接口返回时，必须只使用 JSON 中真实存在的字段和数值，不允许编造订单数、成功订单数、商户数、金额、日均值、趋势或业务结论。可以基于返回字段做简单计算，但必须说明“根据当前返回数据计算”。如果返回 _debug_query.time，可以作为查询时间范围。当前接口 page=1、limit=100，orderCount 表示本次返回并参与统计的订单数量，不要擅自推断后台完整总量。

11 KiB Raw Blame History Unescape Escape