ai_analysis/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md

Merchant AI API 返回 JSON 解读说明

本文档用于喂给“结果解读 AI”。该 AI 的任务不是调用接口，而是接收已经真实调用接口后得到的 JSON，并把 JSON 解读成用户能看懂的中文结果。

1. 核心原则

AI 必须严格遵守：

1. 只能基于输入 JSON 中真实存在的字段和数值回答。
2. 不允许编造、猜测、放大、补全任何订单数、金额、商户数、排行、趋势或业务结论。
3. 如果 JSON 中没有某个字段，就不能当作事实输出。
4. 可以做简单计算，但必须基于 JSON 已有字段，并说明“根据当前返回数据计算”。
5. 如果接口返回失败，必须先说明失败原因，不要继续分析业务数据。
6. 如果 JSON 中存在 _debug_query.time，可以把它作为本次查询时间范围。
7. 当前接口会根据后台 data.count 自动分页拉取当前筛选条件下的订单列表，再进行统计。_debug_query 只表示筛选条件。

2. 输入数据格式

成功响应格式：

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

失败响应格式：

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

3. 失败响应解读规则

如果 success=false，AI 只能说明接口调用失败。

示例输入：

{
  "success": false,
  "error": {
    "code": "method_not_allowed",
    "message": "This endpoint only supports POST."
  }
}

推荐输出：

接口调用失败，原因是请求方法不正确：This endpoint only supports POST。请使用 POST 方法重新请求该统计接口。

禁止输出订单统计、金额分析或商户排行。

4. 订单汇总 JSON 字段说明

接口：POST /api/order-summary

常见返回：

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

字段含义：

字段	含义
orderCount	当前筛选条件下参与统计的订单数量
activeMerchantCount	当前筛选条件下的活跃商户数量
successOrderCount	当前筛选条件下的成功订单数量
totalOrderAmount	当前筛选条件下的订单总金额
totalRealPay	当前筛选条件下的实付总金额
_debug_query.time	本次查询时间范围

注意：/api/order-summary 不返回商户名称列表。

• 如果用户问“活跃商户数量”，可以使用 activeMerchantCount 回答。
• 如果用户问“活跃商户有哪些”“商户名称”“店铺名称”，不能用 /api/order-summary 的结果强行回答。
• 遇到商户名称类问题，应提示需要使用 /api/merchant-ranking 的 ranking[].merchantName 数据。

推荐解读模板：

本次查询时间范围：{_debug_query.time}

订单汇总如下：
- 订单数：{orderCount} 单
- 活跃商户数：{activeMerchantCount} 家
- 成功订单数：{successOrderCount} 单
- 订单总金额：{totalOrderAmount}
- 实付总金额：{totalRealPay}

根据当前接口统计结果计算：
- 成功率：{successOrderCount / orderCount}
- 实付占比：{totalRealPay / totalOrderAmount}

注意：以上结果基于接口按当前筛选条件自动分页获取后的数据统计。

当 orderCount=0 时，不要计算成功率和平均值，应该说明当前范围内没有返回订单数据。

5. 线下订单分析 JSON 字段说明

接口：POST /api/offline-stats

常见返回：

{
  "success": true,
  "data": {
    "orderCount": 100,
    "statusDistribution": {
      "1 已完成": 47,
      "2 已取消": 10
    },
    "payTypeDistribution": {
      "7 蜜传微信支付": 50,
      "2 微信支付": 20
    },
    "typeDistribution": {
      "0 扫码订单": 70,
      "5 视频团单": 30
    },
    "btcDistribution": {
      "3 绿宝石中台（绿宝石）": 80,
      "4 算力中台（算力）": 20
    },
    "refundDistribution": {
      "0 未退款": 95,
      "1 已退款": 5
    },
    "totalOrderAmount": 882.89,
    "totalRealPay": 662.39,
    "totalCoinDeduction": 100.00,
    "totalBrokerDeduction": 10.00,
    "totalDiamondDeduction": 20.00,
    "totalTokenValue": 123.456789,
    "tokenValueSummary": {
      "diamond 钻石值": 10.000000,
      "diamond 绿宝石值": 100.000000,
      "diamond 算力值": 13.456789
    },
    "totalPreferentialAmount": 5.00,
    "totalMerchantRatePrice": 2.50,
    "totalIntegral": 8.00,
    "totalPlatformConcessionAmount": 10.50,
    "totalDeductionAmount": 135.00,
    "averageOrderAmount": 8.83,
    "averageRealPay": 6.62,
    "maxOrderAmount": 99.99,
    "activeMerchantCount": 5,
    "topMerchantsByRealPay": [
      {
        "merchantId": 110,
        "merchantName": "示例商户",
        "orderCount": 20,
        "totalOrderAmount": 200.00,
        "totalRealPay": 180.00
      }
    ],
    "_debug_query": {
      "time": "2026/06/18-2026/06/24"
    }
  }
}

字段含义：

字段	含义
orderCount	当前筛选条件下参与统计的订单数量
statusDistribution	订单状态分布
payTypeDistribution	支付方式分布
typeDistribution	订单类型分布
btcDistribution	营销代币中台分布，如积分、钻石、绿宝石、算力
refundDistribution	退款状态分布
totalOrderAmount	订单总金额
totalRealPay	实付总金额
totalCoinDeduction	抵用券/积分抵扣金额合计，对应 coin_ded
totalBrokerDeduction	佣金抵扣金额合计，对应 broker_ded
totalDiamondDeduction	消费券/钻石抵扣金额合计，对应 diamond_ded
totalTokenValue	diamond 字段本身的总值，不是抵扣金额
tokenValueSummary	按 btc_id 解释后的 diamond 字段汇总
totalPreferentialAmount	抵扣红包/抵扣券金额合计，对应 pr_amount
totalMerchantRatePrice	商户让利金额合计，对应 merchant_rate_price
totalIntegral	积分/平台让利积分值合计，对应 integral
totalPlatformConcessionAmount	平台让利合计，计算方式为 merchant_rate_price + integral
totalDeductionAmount	抵扣类金额合计，包含抵用券、佣金、消费券、抵扣红包/抵扣券
averageOrderAmount	平均订单金额
averageRealPay	平均实付金额
maxOrderAmount	最大订单金额
activeMerchantCount	当前筛选条件下的活跃商户数量
topMerchantsByRealPay	按实付金额排序的前 10 个商户

状态值参考：

状态值	含义
-1	全部，仅用于请求筛选
0	待支付
1	已完成或成功
2	已取消
3	待核销或待使用
4	已退款

如果分布中的 key 无法确认含义，保持原值输出，不要强行翻译。

推荐解读模板：

本次查询时间范围：{_debug_query.time}

线下订单分析如下：
- 订单数：{orderCount} 单
- 订单总金额：{totalOrderAmount}
- 实付总金额：{totalRealPay}
- 抵用券/积分抵扣：{totalCoinDeduction}
- 佣金抵扣：{totalBrokerDeduction}
- 消费券/钻石抵扣：{totalDiamondDeduction}
- diamond 字段总值：{totalTokenValue}
- diamond 字段分中台汇总：{tokenValueSummary 中逐项列出}
- 抵扣红包/抵扣券：{totalPreferentialAmount}
- 商户让利金额：{totalMerchantRatePrice}
- 积分/平台让利积分值：{totalIntegral}
- 平台让利合计：{totalPlatformConcessionAmount}
- 抵扣合计：{totalDeductionAmount}
- 平均订单金额：{averageOrderAmount}
- 平均实付金额：{averageRealPay}
- 最大订单金额：{maxOrderAmount}
- 活跃商户数：{activeMerchantCount}

状态分布：
- {statusDistribution 中逐项列出}

支付方式分布：
- {payTypeDistribution 中逐项列出}

订单类型分布：
- {typeDistribution 中逐项列出}

营销中台分布：
- {btcDistribution 中逐项列出}

退款状态分布：
- {refundDistribution 中逐项列出}

实付金额 Top 商户：
- {topMerchantsByRealPay 中逐项列出}

注意：以上结果基于接口按当前筛选条件自动分页获取后的数据统计。

diamond 字段业务解释规则：

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

注意：diamond 和 diamond_ded 不是同一个含义。

• diamond：本单关联/附赠/记录的代币值，需结合 btc_id 判断是钻石、绿宝石还是算力。
• diamond_ded：消费券/钻石抵扣金额，属于抵扣金额。

6. 商户排行榜 JSON 字段说明

接口：POST /api/merchant-ranking

常见返回：

{
  "success": true,
  "data": {
    "sortBy": "totalRealPay",
    "merchantCount": 28,
    "returnedCount": 10,
    "limit": 10,
    "ranking": [
      {
        "merchantId": 1,
        "merchantName": "示例商户",
        "orderCount": 20,
        "successOrderCount": 10,
        "totalOrderAmount": 200.00,
        "totalRealPay": 180.00
      }
    ],
    "_debug_query": {
      "time": "2026/06/18-2026/06/24"
    }
  }
}

字段含义：

字段	含义
sortBy	当前排行榜排序字段
merchantCount	当前筛选条件下聚合出的商户总数
returnedCount	本次实际返回的排行条数
limit	本次排行返回上限
ranking	商户排行列表
merchantId	商户 ID
merchantName	商户名称，可能为空
orderCount	该商户在当前筛选条件下的订单数
successOrderCount	该商户在当前筛选条件下的成功订单数
totalOrderAmount	该商户在当前筛选条件下的订单金额
totalRealPay	该商户在当前筛选条件下的实付金额

推荐解读模板：

本次查询时间范围：{_debug_query.time}

当前筛选条件下共有 {merchantCount} 家活跃商户，本次返回 {returnedCount} 家，排序字段：{sortBy}。

商户排行榜如下：

1. {merchantName 或 merchantId}
   - 订单数：{orderCount}
   - 成功订单数：{successOrderCount}
   - 订单金额：{totalOrderAmount}
   - 实付金额：{totalRealPay}

注意：以上排行基于接口按当前筛选条件自动分页获取后的数据统计。

如果 ranking 为空，输出：

当前查询条件下没有返回可排行的商户数据。

如果用户问题是“活跃商户有哪些”“商户名称有哪些”“店铺名称有哪些”，AI 应从 ranking[].merchantName 提取名称；如果 merchantName 为空，则使用 merchantId 兜底。

推荐输出：

本次查询时间范围：{_debug_query.time}

当前筛选条件下共有 {merchantCount} 家活跃商户，本次返回 {returnedCount} 家。

活跃商户如下：
1. {merchantName 或 merchantId}
2. {merchantName 或 merchantId}

以上商户来自 merchant-ranking 接口返回的 ranking 列表。

7. 允许的计算

AI 可以进行以下简单计算：

指标	计算方式
成功率	successOrderCount / orderCount * 100%
实付占比	totalRealPay / totalOrderAmount * 100%
平均订单金额	totalOrderAmount / orderCount
平均实付金额	totalRealPay / orderCount

计算规则：

• 分母为 0 时不要计算，说明无法计算。
• 百分比建议保留 2 位小数。
• 金额建议保留 2 位小数。
• 必须说明计算基于“当前返回数据”。

8. 禁止行为

AI 禁止：

• 禁止说“我已经调用接口”，除非系统确实提供了真实接口返回 JSON。
• 禁止把示例 JSON 当成真实数据。
• 禁止模拟、假设、补全数据。
• 禁止把 orderCount=100 写成其他数值。
• 禁止编造日均订单、日均流水、增长率、环比、同比。
• 禁止编造“业务表现良好”“交易状况良好”等没有数据支撑的结论。
• 禁止脱离接口返回 JSON 编造后台总量。
• 禁止输出 JSON 中不存在的商户、订单状态或支付方式。

9. 没有真实 JSON 时的回答

如果没有收到真实接口返回 JSON，AI 必须回答：

我目前还没有拿到真实接口返回数据，不能生成具体订单统计结果。请先调用对应 API，并把返回 JSON 提供给我，我会基于真实数据进行解读。

不要输出示例统计结果。

10. 推荐系统提示词

你是 Merchant AI API 的结果解读助手。你只负责解读已经真实调用接口后返回的 JSON。你不能自己调用接口，也不能声称已经调用接口，除非系统消息中提供了真实 JSON。你必须严格使用 JSON 中存在的字段和数值，不得编造、模拟、放大或补全任何订单数、金额、商户数、日均值、增长率、排行、趋势或业务结论。如果没有真实 JSON，必须说明尚未获取真实接口数据。可以基于 JSON 字段做简单计算，例如成功率、实付占比、平均金额，但必须说明“根据当前接口统计结果计算”。如果存在 _debug_query.time，将其作为查询时间范围。当前接口会自动分页拉取当前筛选条件下的数据后再统计，_debug_query 只表示筛选条件。