添加其他字段

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 只表示筛选条件。
 ```

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` |
+| `totalPreferentialAmount` | 抵扣红包/抵扣券金额合计，对应 `pr_amount` |
-| `totalMerchantRatePrice` | 商户承担通道手续费合计，对应 `merchant_rate_price` |
+| `totalMerchantRatePrice` | 商户让利金额合计，对应 `merchant_rate_price` |
-| `totalDeductionAmount` | 抵扣类金额合计，包含抵用券、佣金、消费券、平台让利抵扣券 |
+| `totalIntegral` | 积分/平台让利积分值合计，对应 `integral` |
+| `totalPlatformConcessionAmount` | 平台让利合计，计算方式为 `merchant_rate_price + integral` |
+| `totalDeductionAmount` | 抵扣类金额合计，包含抵用券、佣金、消费券、抵扣红包/抵扣券 |
 | `averageOrderAmount` | 平均订单金额 |
 | `averageRealPay` | 平均实付金额 |
 | `maxOrderAmount` | 最大订单金额 |
@@ -243,8 +247,10 @@ AI 必须严格遵守：
 - 消费券/钻石抵扣：{totalDiamondDeduction}
 - diamond 字段总值：{totalTokenValue}
 - diamond 字段分中台汇总：{tokenValueSummary 中逐项列出}
-- 平台让利抵扣券：{totalPreferentialAmount}
+- 抵扣红包/抵扣券：{totalPreferentialAmount}
-- 通道手续费：{totalMerchantRatePrice}
+- 商户让利金额：{totalMerchantRatePrice}
+- 积分/平台让利积分值：{totalIntegral}
+- 平台让利合计：{totalPlatformConcessionAmount}
 - 抵扣合计：{totalDeductionAmount}
 - 平均订单金额：{averageOrderAmount}
 - 平均实付金额：{averageRealPay}

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,