# 搜索API接口对接指南
  
  本文档为搜索服务的使用方提供完整的API对接指南，包括接口说明、请求参数、响应格式和使用示例。
  
  ## 目录
  
  1. [快速开始](#快速开始)
  2. [接口概览](#接口概览)
  3. [文本搜索接口](#文本搜索接口)
  4. [图片搜索接口](#图片搜索接口)
  5. [响应格式说明](#响应格式说明)
  6. [常见场景示例](#常见场景示例)
  7. [错误处理](#错误处理)
  8. [最佳实践](#最佳实践)
  
  ---
  
  ## 快速开始
  
  ### 基础信息
  
  - **Base URL**: `http://your-domain:6002` 或 `http://120.76.41.98:6002`
  - **协议**: HTTP/HTTPS
  - **数据格式**: JSON
  - **字符编码**: UTF-8
  - **请求方法**: POST（搜索接口）
  
  ### 最简单的搜索请求
  
  ```bash
  curl -X POST "http://localhost:6002/search/" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "芭比娃娃"
    }'
  ```
  
  ### Python示例
  
  ```python
  import requests
  
  url = "http://localhost:6002/search/"
  response = requests.post(url, json={"query": "芭比娃娃"})
  data = response.json()
  print(f"找到 {data['total']} 个结果")
  ```
  
  ### JavaScript示例
  
  ```javascript
  const response = await fetch('http://localhost:6002/search/', {
      method: 'POST',
      headers: {
          'Content-Type': 'application/json'
      },
      body: JSON.stringify({
          query: '芭比娃娃'
      })
  });
  const data = await response.json();
  console.log(`找到 ${data.total} 个结果`);
  ```
  
  ---
  
  ## 接口概览
  
  | 接口 | 方法 | 路径 | 说明 |
  |------|------|------|------|
  | 文本搜索 | POST | `/search/` | 执行文本搜索查询 |
  | 图片搜索 | POST | `/search/image` | 基于图片相似度搜索 |
  | 搜索建议 | GET | `/search/suggestions` | 获取搜索建议（框架，暂未实现） |
  | 获取文档 | GET | `/search/{doc_id}` | 根据ID获取单个文档 |
  | 健康检查 | GET | `/admin/health` | 检查服务状态 |
  
  ---
  
  ## 文本搜索接口
  
  ### 接口信息
  
  - **端点**: `POST /search/`
  - **描述**: 执行文本搜索查询，支持多语言、布尔表达式、过滤器和分面搜索
  
  ### 请求参数
  
  #### 完整请求体结构
  
  ```json
  {
    "query": "string (required)",
    "size": 10,
    "from": 0,
    "filters": {},
    "range_filters": {},
    "facets": [],
    "sort_by": "string",
    "sort_order": "desc",
    "min_score": 0.0,
    "debug": false,
    "user_id": "string",
    "session_id": "string"
  }
  ```
  
  #### 参数详细说明
  
  | 参数 | 类型 | 必填 | 默认值 | 说明 |
  |------|------|------|--------|------|
  | `query` | string | ✅ | - | 搜索查询字符串，支持布尔表达式（AND, OR, RANK, ANDNOT） |
  | `size` | integer | ❌ | 10 | 返回结果数量（1-100） |
  | `from` | integer | ❌ | 0 | 分页偏移量（用于分页） |
  | `filters` | object | ❌ | null | 精确匹配过滤器（见下文） |
  | `range_filters` | object | ❌ | null | 数值范围过滤器（见下文） |
  | `facets` | array | ❌ | null | 分面配置（见下文） |
  | `sort_by` | string | ❌ | null | 排序字段名（如 `min_price`, `max_price`, `title`） |
  | `sort_order` | string | ❌ | "desc" | 排序方向：`asc`（升序）或 `desc`（降序） |
  | `min_score` | float | ❌ | null | 最小相关性分数阈值 |
  | `debug` | boolean | ❌ | false | 是否返回调试信息 |
  | `user_id` | string | ❌ | null | 用户ID（用于个性化，预留） |
  | `session_id` | string | ❌ | null | 会话ID（用于分析，预留） |
  
  ### 过滤器详解
  
  #### 1. 精确匹配过滤器 (filters)
  
  用于精确匹配或多值匹配（OR 逻辑）。
  
  **格式**:
  ```json
  {
    "filters": {
      "category_keyword": "玩具",                    // 单值：精确匹配
      "vendor_keyword": ["乐高", "孩之宝"],          // 数组：匹配任意值（OR）
      "product_type_keyword": "益智玩具"              // 单值：精确匹配
    }
  }
  ```
  
  **支持的值类型**:
  - 字符串：精确匹配
  - 整数：精确匹配
  - 布尔值：精确匹配
  - 数组：匹配任意值（OR 逻辑）
  
  **常用过滤字段**:
  - `category_keyword`: 类目
  - `vendor_keyword`: 品牌/供应商
  - `product_type_keyword`: 商品类型
  - `tags_keyword`: 标签
  
  #### 2. 范围过滤器 (range_filters)
  
  用于数值字段的范围过滤。
  
  **格式**:
  ```json
  {
    "range_filters": {
      "min_price": {
        "gte": 50,    // 大于等于
        "lte": 200    // 小于等于
      },
      "max_price": {
        "gt": 100     // 大于
      },
      "create_time": {
        "gte": "2024-01-01T00:00:00Z"  // 日期时间字符串
      }
    }
  }
  ```
  
  **支持的操作符**:
  - `gte`: 大于等于 (>=)
  - `gt`: 大于 (>)
  - `lte`: 小于等于 (<=)
  - `lt`: 小于 (<)
  
  **注意**: 至少需要指定一个操作符。
  
  **常用范围字段**:
  - `min_price`: 最低价格
  - `max_price`: 最高价格
  - `compare_at_price`: 原价
  - `create_time`: 创建时间
  - `update_time`: 更新时间
  
  #### 3. 分面配置 (facets)
  
  用于生成分面统计（分组聚合），常用于构建筛选器UI。
  
  **简单模式**（字符串数组）:
  ```json
  {
    "facets": ["category_keyword", "vendor_keyword"]
  }
  ```
  
  **高级模式**（配置对象数组）:
  ```json
  {
    "facets": [
      {
        "field": "category_keyword",
        "size": 15,
        "type": "terms"
      },
      {
        "field": "min_price",
        "type": "range",
        "ranges": [
          {"key": "0-50", "to": 50},
          {"key": "50-100", "from": 50, "to": 100},
          {"key": "100-200", "from": 100, "to": 200},
          {"key": "200+", "from": 200}
        ]
      }
    ]
  }
  ```
  
  **分面配置参数**:
  - `field`: 字段名（必填）
  - `size`: 返回的分组数量（默认：10，范围：1-100）
  - `type`: 分面类型，`terms`（分组统计）或 `range`（范围统计）
  - `ranges`: 范围定义（仅当 type='range' 时需要）
  
  ### 布尔表达式语法
  
  搜索查询支持布尔表达式，提供更灵活的搜索能力。
  
  **支持的操作符**:
  
  | 操作符 | 描述 | 示例 |
  |--------|------|------|
  | `AND` | 所有词必须匹配 | `玩具 AND 乐高` |
  | `OR` | 任意词匹配 | `芭比 OR 娃娃` |
  | `ANDNOT` | 排除特定词 | `玩具 ANDNOT 电动` |
  | `RANK` | 排序加权（不强制匹配） | `玩具 RANK 乐高` |
  | `()` | 分组 | `玩具 AND (乐高 OR 芭比)` |
  
  **操作符优先级**（从高到低）:
  1. `()` - 括号
  2. `ANDNOT` - 排除
  3. `AND` - 与
  4. `OR` - 或
  5. `RANK` - 排序
  
  **示例**:
  ```
  "芭比娃娃"                    // 简单查询
  "玩具 AND 乐高"               // AND 查询
  "芭比 OR 娃娃"                // OR 查询
  "玩具 ANDNOT 电动"            // 排除查询
  "玩具 AND (乐高 OR 芭比)"      // 复杂查询
  ```
  
  ---
  
  ## 图片搜索接口
  
  ### 接口信息
  
  - **端点**: `POST /search/image`
  - **描述**: 基于图片相似度进行搜索，使用图片向量进行语义匹配
  
  ### 请求参数
  
  ```json
  {
    "image_url": "string (required)",
    "size": 10,
    "filters": {},
    "range_filters": {}
  }
  ```
  
  ### 参数说明
  
  | 参数 | 类型 | 必填 | 默认值 | 描述 |
  |------|------|------|--------|------|
  | `image_url` | string | ✅ | - | 查询图片的 URL |
  | `size` | integer | ❌ | 10 | 返回结果数量（1-100） |
  | `filters` | object | ❌ | null | 精确匹配过滤器 |
  | `range_filters` | object | ❌ | null | 数值范围过滤器 |
  
  ### 请求示例
  
  ```bash
  curl -X POST "http://localhost:6002/search/image" \
    -H "Content-Type: application/json" \
    -d '{
      "image_url": "https://example.com/barbie.jpg",
      "size": 20,
      "filters": {
        "category_keyword": "玩具"
      },
      "range_filters": {
        "min_price": {
          "lte": 100
        }
      }
    }'
  ```
  
  ---
  
  ## 响应格式说明
  
  ### 标准响应结构
  
  ```json
  {
    "results": [
      {
        "product_id": "12345",
        "title": "芭比时尚娃娃",
        "handle": "barbie-doll",
        "description": "高品质芭比娃娃",
        "vendor": "美泰",
        "product_type": "玩具",
        "tags": "娃娃, 玩具, 女孩",
        "price": 89.99,
        "compare_at_price": 129.99,
        "currency": "USD",
        "image_url": "https://example.com/image.jpg",
        "in_stock": true,
        "variants": [
          {
            "variant_id": "67890",
            "title": "粉色款",
            "price": 89.99,
            "compare_at_price": 129.99,
            "sku": "BARBIE-001",
            "stock": 100,
            "options": {
              "option1": "粉色",
              "option2": "标准款"
            }
          }
        ],
        "relevance_score": 8.5
      }
    ],
    "total": 118,
    "max_score": 8.5,
    "facets": [
      {
        "field": "category_keyword",
        "label": "category_keyword",
        "type": "terms",
        "values": [
          {
            "value": "玩具",
            "label": "玩具",
            "count": 85,
            "selected": false
          }
        ]
      }
    ],
    "query_info": {
      "original_query": "芭比娃娃",
      "detected_language": "zh",
      "translations": {
        "en": "barbie doll"
      }
    },
    "suggestions": [],
    "related_searches": [],
    "took_ms": 45,
    "performance_info": null,
    "debug_info": null
  }
  ```
  
  ### 响应字段说明
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `results` | array | 搜索结果列表（ProductResult对象数组） |
  | `results[].product_id` | string | 商品ID |
  | `results[].title` | string | 商品标题 |
  | `results[].price` | float | 价格（min_price） |
  | `results[].variants` | array | 变体列表（SKU列表） |
  | `results[].relevance_score` | float | 相关性分数 |
  | `total` | integer | 匹配的总文档数 |
  | `max_score` | float | 最高相关性分数 |
  | `facets` | array | 分面统计结果 |
  | `query_info` | object | 查询处理信息 |
  | `took_ms` | integer | 搜索耗时（毫秒） |
  
  ### ProductResult字段说明
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `product_id` | string | 商品ID（SPU ID） |
  | `title` | string | 商品标题 |
  | `handle` | string | 商品URL handle |
  | `description` | string | 商品描述 |
  | `vendor` | string | 供应商/品牌 |
  | `product_type` | string | 商品类型 |
  | `tags` | string | 标签 |
  | `price` | float | 价格（min_price） |
  | `compare_at_price` | float | 原价 |
  | `currency` | string | 货币单位（默认USD） |
  | `image_url` | string | 主图URL |
  | `in_stock` | boolean | 是否有库存（任意变体有库存即为true） |
  | `variants` | array | 变体列表 |
  | `relevance_score` | float | 相关性分数 |
  
  ### VariantResult字段说明
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `variant_id` | string | 变体ID（SKU ID） |
  | `title` | string | 变体标题 |
  | `price` | float | 价格 |
  | `compare_at_price` | float | 原价 |
  | `sku` | string | SKU编码 |
  | `stock` | integer | 库存数量 |
  | `options` | object | 选项（颜色、尺寸等） |
  
  ---
  
  ## 常见场景示例
  
  ### 场景1：商品列表页搜索
  
  **需求**: 搜索"玩具"，按价格从低到高排序，显示前20个结果
  
  ```json
  {
    "query": "玩具",
    "size": 20,
    "from": 0,
    "sort_by": "min_price",
    "sort_order": "asc"
  }
  ```
  
  ### 场景2：带筛选的商品搜索
  
  **需求**: 搜索"玩具"，筛选类目为"益智玩具"，价格在50-200之间
  
  ```json
  {
    "query": "玩具",
    "size": 20,
    "filters": {
      "category_keyword": "益智玩具"
    },
    "range_filters": {
      "min_price": {
        "gte": 50,
        "lte": 200
      }
    }
  }
  ```
  
  ### 场景3：带分面的商品搜索
  
  **需求**: 搜索"玩具"，获取类目和品牌的分面统计，用于构建筛选器
  
  ```json
  {
    "query": "玩具",
    "size": 20,
    "facets": [
      "category_keyword",
      "vendor_keyword"
    ]
  }
  ```
  
  ### 场景4：多条件组合搜索
  
  **需求**: 搜索"玩具"，筛选多个品牌，价格范围，并获取分面统计
  
  ```json
  {
    "query": "玩具",
    "size": 20,
    "filters": {
      "vendor_keyword": ["乐高", "孩之宝", "美泰"]
    },
    "range_filters": {
      "min_price": {
        "gte": 50,
        "lte": 200
      }
    },
    "facets": [
      {
        "field": "category_keyword",
        "size": 15
      },
      {
        "field": "min_price",
        "type": "range",
        "ranges": [
          {"key": "0-50", "to": 50},
          {"key": "50-100", "from": 50, "to": 100},
          {"key": "100-200", "from": 100, "to": 200},
          {"key": "200+", "from": 200}
        ]
      }
    ],
    "sort_by": "min_price",
    "sort_order": "asc"
  }
  ```
  
  ### 场景5：布尔表达式搜索
  
  **需求**: 搜索包含"玩具"和"乐高"的商品，排除"电动"
  
  ```json
  {
    "query": "玩具 AND 乐高 ANDNOT 电动",
    "size": 20
  }
  ```
  
  ### 场景6：分页查询
  
  **需求**: 获取第2页结果（每页20条）
  
  ```json
  {
    "query": "玩具",
    "size": 20,
    "from": 20
  }
  ```
  
  ---
  
  ## 错误处理
  
  ### 错误响应格式
  
  ```json
  {
    "error": "错误信息",
    "detail": "详细错误信息（可选）"
  }
  ```
  
  ### 常见错误码
  
  | HTTP状态码 | 说明 | 处理建议 |
  |-----------|------|---------|
  | 200 | 成功 | - |
  | 400 | 请求参数错误 | 检查请求参数格式和必填字段 |
  | 404 | 接口不存在 | 检查接口路径 |
  | 500 | 服务器内部错误 | 联系技术支持 |
  
  ### 错误处理示例
  
  **Python**:
  ```python
  import requests
  
  try:
      response = requests.post(url, json=payload, timeout=10)
      response.raise_for_status()
      data = response.json()
  except requests.exceptions.HTTPError as e:
      print(f"HTTP错误: {e}")
      if response.status_code == 400:
          error_data = response.json()
          print(f"错误详情: {error_data.get('detail')}")
  except requests.exceptions.RequestException as e:
      print(f"请求异常: {e}")
  ```
  
  **JavaScript**:
  ```javascript
  try {
      const response = await fetch(url, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(payload)
      });
      
      if (!response.ok) {
          const error = await response.json();
          throw new Error(error.error || `HTTP ${response.status}`);
      }
      
      const data = await response.json();
  } catch (error) {
      console.error('搜索失败:', error.message);
  }
  ```
  
  ---
  
  ### 5. 代码示例
  
  **完整的搜索函数（Python）**:
  
  ```python
  import requests
  from typing import Dict, Any, Optional, List
  
  class SearchClient:
      def __init__(self, base_url: str = "http://localhost:6002"):
          self.base_url = base_url
          self.timeout = 10
      
      def search(
          self,
          query: str,
          size: int = 20,
          from_: int = 0,
          filters: Optional[Dict] = None,
          range_filters: Optional[Dict] = None,
          facets: Optional[List] = None,
          sort_by: Optional[str] = None,
          sort_order: str = "desc"
      ) -> Dict[str, Any]:
          """
          执行搜索查询
          
          Args:
              query: 搜索查询字符串
              size: 返回结果数量
              from_: 分页偏移量
              filters: 精确匹配过滤器
              range_filters: 范围过滤器
              facets: 分面配置
              sort_by: 排序字段
              sort_order: 排序方向
          
          Returns:
              搜索结果字典
          """
          url = f"{self.base_url}/search/"
          payload = {
              "query": query,
              "size": size,
              "from": from_,
          }
          
          if filters:
              payload["filters"] = filters
          if range_filters:
              payload["range_filters"] = range_filters
          if facets:
              payload["facets"] = facets
          if sort_by:
              payload["sort_by"] = sort_by
              payload["sort_order"] = sort_order
          
          try:
              response = requests.post(
                  url,
                  json=payload,
                  timeout=self.timeout
              )
              response.raise_for_status()
              return response.json()
          except requests.exceptions.RequestException as e:
              raise Exception(f"搜索请求失败: {e}")
  
  # 使用示例
  client = SearchClient()
  result = client.search(
      query="玩具",
      size=20,
      filters={"category_keyword": "益智玩具"},
      range_filters={"min_price": {"gte": 50, "lte": 200}},
      facets=["category_keyword", "vendor_keyword"],
      sort_by="min_price",
      sort_order="asc"
  )
  
  print(f"找到 {result['total']} 个结果")
  for product in result['results']:
      print(f"{product['title']} - ¥{product['price']}")
  ```
  
  **完整的搜索函数（JavaScript）**:
  
  ```javascript
  class SearchClient {
      constructor(baseUrl = 'http://localhost:6002') {
          this.baseUrl = baseUrl;
          this.timeout = 10000;
      }
      
      async search({
          query,
          size = 20,
          from = 0,
          filters = null,
          rangeFilters = null,
          facets = null,
          sortBy = null,
          sortOrder = 'desc'
      }) {
          const url = `${this.baseUrl}/search/`;
          const payload = {
              query,
              size,
              from,
          };
          
          if (filters) payload.filters = filters;
          if (rangeFilters) payload.range_filters = rangeFilters;
          if (facets) payload.facets = facets;
          if (sortBy) {
              payload.sort_by = sortBy;
              payload.sort_order = sortOrder;
          }
          
          try {
              const response = await fetch(url, {
                  method: 'POST',
                  headers: {
                      'Content-Type': 'application/json'
                  },
                  body: JSON.stringify(payload),
                  signal: AbortSignal.timeout(this.timeout)
              });
              
              if (!response.ok) {
                  const error = await response.json();
                  throw new Error(error.error || `HTTP ${response.status}`);
              }
              
              return await response.json();
          } catch (error) {
              throw new Error(`搜索请求失败: ${error.message}`);
          }
      }
  }
  
  // 使用示例
  const client = new SearchClient();
  const result = await client.search({
      query: '玩具',
      size: 20,
      filters: { category_keyword: '益智玩具' },
      rangeFilters: { min_price: { gte: 50, lte: 200 } },
      facets: ['category_keyword', 'vendor_keyword'],
      sortBy: 'min_price',
      sortOrder: 'asc'
  });
  
  console.log(`找到 ${result.total} 个结果`);
  result.results.forEach(product => {
      console.log(`${product.title} - ¥${product.price}`);
  });
  ```
  
  ---
  

  ## 其他接口
  
  ### 搜索建议（框架）
  
  - **端点**: `GET /search/suggestions`
  - **描述**: 返回搜索建议（自动补全/热词）。当前为框架实现，接口和响应格式已经固定，可平滑扩展。
  
  #### 查询参数
  
  | 参数 | 类型 | 必填 | 默认值 | 描述 |
  |------|------|------|--------|------|
  | `q` | string | ✅ | - | 查询字符串（至少 1 个字符） |
  | `size` | integer | ❌ | 5 | 返回建议数量（1-20） |
  | `types` | string | ❌ | `query` | 建议类型（逗号分隔）：`query`, `product`, `category`, `brand` |
  
  #### 响应示例
  
  ```json
  {
    "query": "芭",
    "suggestions": [
      {
        "text": "芭比娃娃",
        "type": "query",
        "highlight": "<em>芭</em>比娃娃",
        "popularity": 850
      }
    ],
    "took_ms": 5
  }
  ```
  
  #### 请求示例
  
  ```bash
  curl "http://localhost:6002/search/suggestions?q=芭&size=5&types=query,product"
  ```
  
  ---
  
  ### 即时搜索（框架）
  
  - **端点**: `GET /search/instant`
  - **描述**: 边输入边搜索，采用轻量参数响应当前输入。底层复用标准搜索能力。
  
  #### 查询参数
  
  | 参数 | 类型 | 必填 | 默认值 | 描述 |
  |------|------|------|--------|------|
  | `q` | string | ✅ | - | 搜索查询（至少 2 个字符） |
  | `size` | integer | ❌ | 5 | 返回结果数量（1-20） |
  
  #### 请求示例
  
  ```bash
  curl "http://localhost:6002/search/instant?q=玩具&size=5"
  ```
  
  ---
  
  ### 获取单个文档
  
  - **端点**: `GET /search/{doc_id}`
  - **描述**: 根据文档 ID 获取单个商品详情，用于点击结果后的详情页或排查问题。
  
  #### 路径参数
  
  | 参数 | 类型 | 描述 |
  |------|------|------|
  | `doc_id` | string | 商品或文档 ID |
  
  #### 响应示例
  
  ```json
  {
    "id": "12345",
    "source": {
      "title": "芭比时尚娃娃",
      "min_price": 89.99,
      "category_keyword": "玩具"
    }
  }
  ```
  
  #### 请求示例
  
  ```bash
  curl "http://localhost:6002/search/12345"
  ```
  
  ---
  
  ## 管理接口
  
  ### 健康检查
  
  - **端点**: `GET /admin/health`
  - **描述**: 检查服务与依赖（如 Elasticsearch）状态。
  
  ```json
  {
    "status": "healthy",
    "elasticsearch": "connected",
    "tenant_id": "tenant1"
  }
  ```
  
  ---
  
  ### 获取配置
  
  - **端点**: `GET /admin/config`
  - **描述**: 返回当前租户的脱敏配置，便于核对索引及排序表达式。
  
  ```json
  {
    "tenant_id": "tenant1",
    "tenant_name": "Tenant1 Test Instance",
    "es_index_name": "search_tenant1",
    "num_fields": 20,
    "num_indexes": 4,
    "supported_languages": ["zh", "en", "ru"],
    "ranking_expression": "bm25() + 0.2*text_embedding_relevance()",
    "spu_enabled": false
  }
  ```
  
  ---
  
  ### 索引统计
  
  - **端点**: `GET /admin/stats`
  - **描述**: 获取索引文档数量与磁盘大小，方便监控。
  
  ```json
  {
    "index_name": "search_tenant1",
    "document_count": 10000,
    "size_mb": 523.45
  }
  ```
  
  ---
  
  ## 数据模型
  
  ### 商品字段
  
  | 字段名 | 类型 | 描述 |
  |--------|------|------|
  | `product_id` | keyword | 商品 ID（SPU） |
  | `sku_id` | keyword/long | SKU ID（主键） |
  | `title` | text | 商品名称（中文） |
  | `en_title` | text | 商品名称（英文） |
  | `ru_title` | text | 商品名称（俄文） |
  | `category_keyword` | keyword | 类目（精确匹配） |
  | `vendor_keyword` | keyword | 品牌/供应商（精确匹配） |
  | `product_type_keyword` | keyword | 商品类型 |
  | `tags_keyword` | keyword | 标签 |
  | `min_price` | double | 最低价格 |
  | `max_price` | double | 最高价格 |
  | `compare_at_price` | double | 原价 |
  | `create_time` | date | 创建时间 |
  | `update_time` | date | 更新时间 |
  | `in_stock` | boolean | 是否有库存 |
  | `text_embedding` | dense_vector | 文本向量（1024 维） |
  | `image_embedding` | dense_vector | 图片向量（1024 维） |
  
  > 不同租户可自定义字段名称，但最佳实践是对可过滤字段建立 `*_keyword` 版本，对可排序字段显式建 keyword/数值映射。
  
  ---
  
  ## 常见问题（FAQ）
  
  **Q1: 如何判断一个字段应该用哪种过滤器？**  
  `filters` 针对 keyword/布尔/整数字段做精确匹配；`range_filters` 针对数值或日期字段做区间查询。
  
  **Q2: 可以同时使用多个过滤器吗？**  
  可以，所有过滤条件为 AND 关系。例如：
  
  ```json
  {
    "filters": {
      "category_keyword": "玩具",
      "vendor_keyword": "乐高"
    },
    "range_filters": {
      "min_price": {"gte": 50, "lte": 200}
    }
  }
  ```
  
  **Q4: 分面结果里的 `selected` 字段含义是什么？**  
  指示该分面值是否已在当前过滤条件中，前端可据此高亮。
  
  **Q5: 如何自定义排序？**  
  设置 `sort_by` 和 `sort_order`，常用字段包括 `min_price`, `max_price`, `title`, `create_time`, `update_time`, `relevance_score`。
  
  **Q6: 如何启用调试模式？**  
  添加 `debug: true`，即可在响应中看到 `debug_info`（ES DSL、阶段耗时、打分细节）。
  
  ---
  

  ## 附录
  
  ### 常用字段列表
  
  #### 过滤字段（使用 `*_keyword` 后缀）
  
  - `category_keyword`: 类目
  - `vendor_keyword`: 品牌/供应商
  - `product_type_keyword`: 商品类型
  - `tags_keyword`: 标签
  
  #### 范围字段
  
  - `min_price`: 最低价格
  - `max_price`: 最高价格
  - `compare_at_price`: 原价
  - `create_time`: 创建时间
  - `update_time`: 更新时间
  
  #### 排序字段
  
  - `min_price`: 最低价格
  - `max_price`: 最高价格
  - `title`: 标题（字母序）
  - `create_time`: 创建时间
  - `update_time`: 更新时间
  - `relevance_score`: 相关性分数（默认）
  

  ### 支持的分析器
  
  | 分析器 | 语言 | 描述 |
  |--------|------|------|
  | `chinese_ecommerce` | 中文 | 基于 Ansj 的电商优化中文分析器 |
  | `english` | 英文 | 标准英文分析器 |
  | `russian` | 俄文 | 俄文分析器 |
  | `arabic` | 阿拉伯文 | 阿拉伯文分析器 |
  | `spanish` | 西班牙文 | 西班牙文分析器 |
  | `japanese` | 日文 | 日文分析器 |
  
  ### 字段类型速查
  
  | 类型 | ES Mapping | 用途 |
  |------|------------|------|
  | `TEXT` | `text` | 全文检索 |
  | `KEYWORD` | `keyword` | 精确匹配、聚合、排序 |
  | `LONG` | `long` | 整数 |
  | `DOUBLE` | `double` | 浮点数 |
  | `DATE` | `date` | 日期时间 |
  | `BOOLEAN` | `boolean` | 布尔值 |
  | `TEXT_EMBEDDING` | `dense_vector` | 文本语义向量 |
  | `IMAGE_EMBEDDING` | `dense_vector` | 图片语义向量 |