From 227069e3712808251ab1c32006e5d19bea31e0ba Mon Sep 17 00:00:00 2001 From: "1173117610@qq.com" Date: Thu, 2 Jul 2026 17:12:21 +0800 Subject: [PATCH] =?UTF-8?q?=20=E6=B7=BB=E5=8A=A0=E5=85=B6=E4=BB=96?= =?UTF-8?q?=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/AI_INTEGRATION_GUIDE.md | 27 ++++++++++++++++++++---- docs/AI_RESPONSE_INTERPRETATION_GUIDE.md | 16 +++++++++----- src/Tools/AnalyzeOfflineOrdersTool.php | 7 ++++++ 3 files changed, 41 insertions(+), 9 deletions(-) diff --git a/docs/AI_INTEGRATION_GUIDE.md b/docs/AI_INTEGRATION_GUIDE.md index ba8e8f1..6eb0c96 100644 --- a/docs/AI_INTEGRATION_GUIDE.md +++ b/docs/AI_INTEGRATION_GUIDE.md @@ -60,7 +60,7 @@ POST /api/offline-stats 对应工具：`get_offline_stats` -用途：订单状态分布、支付方式分布、订单类型分布、营销中台分布、退款状态分布、抵扣金额、手续费、`diamond` 字段代币值汇总、平均订单金额、平均实付金额、最大订单金额、活跃商户数、实付金额 Top 商户。 +用途：订单状态分布、支付方式分布、订单类型分布、营销中台分布、退款状态分布、抵扣金额、抵扣红包/抵扣券、平台让利、`diamond` 字段代币值汇总、平均订单金额、平均实付金额、最大订单金额、活跃商户数、实付金额 Top 商户。 ### 3.3 商户排行榜 @@ -162,7 +162,7 @@ AI 默认不要使用 `date`，除非调用平台只能传固定后台日期格 ### 6.1 工具选择规则 - 用户问“订单汇总”“多少单”“订单金额合计”“实付金额合计”“活跃商户数量”时，选择 `order_summary`。 -- 用户问“状态分布”“支付类型分布”“订单类型分布”“抵扣金额”“手续费”“diamond/钻石/绿宝石/算力统计”时，选择 `offline_stats`。 +- 用户问“状态分布”“支付类型分布”“订单类型分布”“抵扣金额”“抵扣红包”“抵扣券”“平台让利”“手续费”“diamond/钻石/绿宝石/算力统计”时，选择 `offline_stats`。 - 用户问“排行”“排名”“Top 商家”“商户排行”时，选择 `merchant_ranking`。 - 用户问“活跃商户有哪些”“活跃商户名称”“商户列表”“有哪些商家”“店铺名称”时，必须选择 `merchant_ranking`，不要选择 `order_summary`。 - `order_summary` 只返回活跃商户数量 `activeMerchantCount`，不返回商户名称。 @@ -265,7 +265,26 @@ AI 默认不要使用 `date`，除非调用平台只能传固定后台日期格 - `diamond_ded` 表示消费券/钻石抵扣金额。 - 两者不是同一个字段，不要混淆。 -### 7.2 订单状态 `status` 取值 +### 7.2 财务统计字段映射 + +`/api/offline-stats` 中几个容易混淆的财务字段定义如下： + +| 返回字段 | 计算/来源 | 含义 | +| --- | --- | --- | +| `totalPreferentialAmount` | `pr_amount` 合计 | 抵扣红包/抵扣券金额 | +| `totalMerchantRatePrice` | `merchant_rate_price` 合计 | 商户让利金额 | +| `totalIntegral` | `integral` 合计 | 积分/平台让利积分值 | +| `totalPlatformConcessionAmount` | `merchant_rate_price + integral` 合计 | 平台让利合计 | +| `totalDeductionAmount` | `coin_ded + broker_ded + diamond_ded + pr_amount` 合计 | 抵扣类金额合计，不包含平台让利 | + +AI 解读规则： + +- 用户问“平台让利多少”时，读取 `totalPlatformConcessionAmount`。 +- 用户问“抵扣红包”“抵扣券金额”时，读取 `totalPreferentialAmount`。 +- 不要把 `pr_amount` 当作平台让利。 +- 不要把 `merchant_rate_price` 单独等同于完整平台让利，完整平台让利是 `merchant_rate_price + integral`。 + +### 7.3 订单状态 `status` 取值 | status | 含义 | 用户常见说法 | | --- | --- | --- | @@ -478,5 +497,5 @@ Invoke-RestMethod ` ## 13. 推荐给 AI 的简短系统提示词 ```text -你需要通过 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。工具选择：问订单汇总、多少单、金额合计、活跃商户数量，选择 order_summary；问状态分布、支付类型、订单类型、抵扣、手续费、diamond/钻石/绿宝石/算力统计，选择 offline_stats；问排行、排名、Top 商家、商户名称、活跃商户有哪些、商户列表、店铺名称，选择 merchant_ranking。注意 order_summary 只返回 activeMerchantCount，不返回商户名称；需要商户名称时必须用 merchant_ranking。解读接口返回时，必须只使用 JSON 中真实存在的字段和数值，不允许编造订单数、成功订单数、商户数、金额、日均值、趋势或业务结论。可以基于返回字段做简单计算，但必须说明“根据当前返回数据计算”。如果返回 _debug_query.time，可以作为查询时间范围。当前接口会自动分页拉取当前筛选条件下的订单数据后再统计，_debug_query 只表示筛选条件。 +你需要通过 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。工具选择：问订单汇总、多少单、金额合计、活跃商户数量，选择 order_summary；问状态分布、支付类型、订单类型、抵扣、抵扣红包、抵扣券、平台让利、diamond/钻石/绿宝石/算力统计，选择 offline_stats；问排行、排名、Top 商家、商户名称、活跃商户有哪些、商户列表、店铺名称，选择 merchant_ranking。平台让利读取 totalPlatformConcessionAmount，它等于 merchant_rate_price + integral；抵扣红包/抵扣券读取 totalPreferentialAmount，它来自 pr_amount；不要把 pr_amount 当作平台让利。注意 order_summary 只返回 activeMerchantCount，不返回商户名称；需要商户名称时必须用 merchant_ranking。解读接口返回时，必须只使用 JSON 中真实存在的字段和数值，不允许编造订单数、成功订单数、商户数、金额、日均值、趋势或业务结论。可以基于返回字段做简单计算，但必须说明“根据当前返回数据计算”。如果返回 _debug_query.time，可以作为查询时间范围。当前接口会自动分页拉取当前筛选条件下的订单数据后再统计，_debug_query 只表示筛选条件。 ``` diff --git a/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md b/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md index 56fd735..628e9e5 100644 --- a/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md +++ b/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md @@ -169,6 +169,8 @@ AI 必须严格遵守： }, "totalPreferentialAmount": 5.00, "totalMerchantRatePrice": 2.50, + "totalIntegral": 8.00, + "totalPlatformConcessionAmount": 10.50, "totalDeductionAmount": 135.00, "averageOrderAmount": 8.83, "averageRealPay": 6.62, @@ -207,9 +209,11 @@ AI 必须严格遵守： | `totalDiamondDeduction` | 消费券/钻石抵扣金额合计，对应 `diamond_ded` | | `totalTokenValue` | `diamond` 字段本身的总值，不是抵扣金额 | | `tokenValueSummary` | 按 `btc_id` 解释后的 `diamond` 字段汇总 | -| `totalPreferentialAmount` | 平台让利抵扣券金额合计，对应 `pr_amount` | -| `totalMerchantRatePrice` | 商户承担通道手续费合计，对应 `merchant_rate_price` | -| `totalDeductionAmount` | 抵扣类金额合计，包含抵用券、佣金、消费券、平台让利抵扣券 | +| `totalPreferentialAmount` | 抵扣红包/抵扣券金额合计，对应 `pr_amount` | +| `totalMerchantRatePrice` | 商户让利金额合计，对应 `merchant_rate_price` | +| `totalIntegral` | 积分/平台让利积分值合计，对应 `integral` | +| `totalPlatformConcessionAmount` | 平台让利合计，计算方式为 `merchant_rate_price + integral` | +| `totalDeductionAmount` | 抵扣类金额合计，包含抵用券、佣金、消费券、抵扣红包/抵扣券 | | `averageOrderAmount` | 平均订单金额 | | `averageRealPay` | 平均实付金额 | | `maxOrderAmount` | 最大订单金额 | @@ -243,8 +247,10 @@ AI 必须严格遵守： - 消费券/钻石抵扣：{totalDiamondDeduction} - diamond 字段总值：{totalTokenValue} - diamond 字段分中台汇总：{tokenValueSummary 中逐项列出} -- 平台让利抵扣券：{totalPreferentialAmount} -- 通道手续费：{totalMerchantRatePrice} +- 抵扣红包/抵扣券：{totalPreferentialAmount} +- 商户让利金额：{totalMerchantRatePrice} +- 积分/平台让利积分值：{totalIntegral} +- 平台让利合计：{totalPlatformConcessionAmount} - 抵扣合计：{totalDeductionAmount} - 平均订单金额：{averageOrderAmount} - 平均实付金额：{averageRealPay} diff --git a/src/Tools/AnalyzeOfflineOrdersTool.php b/src/Tools/AnalyzeOfflineOrdersTool.php index 79c2d0f..0d144af 100644 --- a/src/Tools/AnalyzeOfflineOrdersTool.php +++ b/src/Tools/AnalyzeOfflineOrdersTool.php @@ -44,6 +44,8 @@ final readonly class AnalyzeOfflineOrdersTool $tokenValueSummary = []; $totalPreferentialAmount = 0.0; $totalMerchantRatePrice = 0.0; + $totalIntegral = 0.0; + $totalPlatformConcessionAmount = 0.0; $maxOrderAmount = 0.0; foreach ($orders as $order) { @@ -60,6 +62,7 @@ final readonly class AnalyzeOfflineOrdersTool $tokenValue = (float) ($order['diamond'] ?? 0); $preferentialAmount = (float) ($order['pr_amount'] ?? 0); $merchantRatePrice = (float) ($order['merchant_rate_price'] ?? 0); + $integral = (float) ($order['integral'] ?? 0); $merchantId = (int) ($order['merchant_id'] ?? 0); $tokenValueKey = $this->tokenValueLabel($order['btc_id'] ?? null); @@ -77,6 +80,8 @@ final readonly class AnalyzeOfflineOrdersTool $tokenValueSummary[$tokenValueKey] = round(($tokenValueSummary[$tokenValueKey] ?? 0) + $tokenValue, 6); $totalPreferentialAmount += $preferentialAmount; $totalMerchantRatePrice += $merchantRatePrice; + $totalIntegral += $integral; + $totalPlatformConcessionAmount += $merchantRatePrice + $integral; $maxOrderAmount = max($maxOrderAmount, $orderAmount); if ($merchantId > 0) { @@ -123,6 +128,8 @@ final readonly class AnalyzeOfflineOrdersTool 'tokenValueSummary' => $tokenValueSummary, 'totalPreferentialAmount' => round($totalPreferentialAmount, 2), 'totalMerchantRatePrice' => round($totalMerchantRatePrice, 2), + 'totalIntegral' => round($totalIntegral, 2), + 'totalPlatformConcessionAmount' => round($totalPlatformConcessionAmount, 2), 'totalDeductionAmount' => round($totalCoinDeduction + $totalBrokerDeduction + $totalDiamondDeduction + $totalPreferentialAmount, 2), 'averageOrderAmount' => $orderCount > 0 ? round($totalOrderAmount / $orderCount, 2) : 0, 'averageRealPay' => $orderCount > 0 ? round($totalRealPay / $orderCount, 2) : 0,