添加其他字段

docs/AI_INTEGRATION_GUIDE.md

@@ -324,6 +324,17 @@ AI 选择规则：
 | `sortBy` | string | 排序字段 |
 | `limit` | integer | 返回商户数量，默认 `10`，最大 `100` |
 
+`/api/merchant-ranking` 返回中会包含：
+
+| 字段 | 含义 |
+| --- | --- |
+| `merchantCount` | 当前筛选条件下聚合出的商户总数 |
+| `returnedCount` | 本次实际返回的排行条数 |
+| `limit` | 本次排行返回上限 |
+| `ranking` | 排行列表 |
+
+AI 解读时不要把 `returnedCount` 当成总商户数。应使用 `merchantCount` 表示“共有多少家活跃商户”，使用 `returnedCount` 表示“本次展示多少家”。
+
 `sortBy` 可选值：
 
 | 值 | 含义 |

docs/AI_RESPONSE_INTERPRETATION_GUIDE.md

@@ -296,6 +296,9 @@ AI 必须严格遵守：
   "success": true,
   "data": {
     "sortBy": "totalRealPay",
+    "merchantCount": 28,
+    "returnedCount": 10,
+    "limit": 10,
     "ranking": [
       {
         "merchantId": 1,
@@ -318,6 +321,9 @@ AI 必须严格遵守：
 | 字段 | 含义 |
 | --- | --- |
 | `sortBy` | 当前排行榜排序字段 |
+| `merchantCount` | 当前筛选条件下聚合出的商户总数 |
+| `returnedCount` | 本次实际返回的排行条数 |
+| `limit` | 本次排行返回上限 |
 | `ranking` | 商户排行列表 |
 | `merchantId` | 商户 ID |
 | `merchantName` | 商户名称，可能为空 |
@@ -331,7 +337,9 @@ AI 必须严格遵守：
 ```text
 本次查询时间范围：{_debug_query.time}
 
-商户排行榜如下，排序字段：{sortBy}
+当前筛选条件下共有 {merchantCount} 家活跃商户，本次返回 {returnedCount} 家，排序字段：{sortBy}。
+
+商户排行榜如下：
 
 1. {merchantName 或 merchantId}
    - 订单数：{orderCount}
@@ -355,6 +363,8 @@ AI 必须严格遵守：
 ```text
 本次查询时间范围：{_debug_query.time}
 
+当前筛选条件下共有 {merchantCount} 家活跃商户，本次返回 {returnedCount} 家。
+
 活跃商户如下：
 1. {merchantName 或 merchantId}
 2. {merchantName 或 merchantId}

src/Tools/MerchantRankingTool.php

@@ -67,6 +67,7 @@ final readonly class MerchantRankingTool
         });
 
         $maxItems = $limit !== null && $limit > 0 ? min($limit, 100) : 10;
+        $merchantCount = count($items);
         $items = array_slice($items, 0, $maxItems);
 
         foreach ($items as $index => $item) {
@@ -76,6 +77,9 @@ final readonly class MerchantRankingTool
 
         return [
             'sortBy' => $sortField,
+            'merchantCount' => $merchantCount,
+            'returnedCount' => count($items),
+            'limit' => $maxItems,
             'ranking' => $items,
             '_debug_query' => $query,
         ];