文档完善

tangwang
1 parent 670c701f
Showing 17 changed files with 248 additions and 2229 deletions Show diff stats
API_DOCUMENTATION.md
BEST_PRACTICES_REFACTORING.md
CHANGES.md
README.md
docs/RequestContext_README.md
API_EXAMPLES.md -> docs/Search-API-Examples.md
USAGE_GUIDE.md -> docs/Usage-Guide.md
商品数据源入ES配置规范.md -> docs/reference/商品数据源入ES配置规范.md
阿里opensearch电商行业.md -> docs/reference/阿里opensearch电商行业.md
docs/BASE_CONFIG_GUIDE.md -> docs/基础配置指南.md
API_INTEGRATION_GUIDE.md -> docs/搜索API对接指南.md
API_QUICK_REFERENCE.md -> docs/搜索API速查表.md
docs/TestingPipeline_README.md -> docs/测试Pipeline说明.md
TEST_DATA_GUIDE.md -> docs/测试数据指南.md
环境相关.md -> docs/环境配置说明.md
设计文档.md -> docs/系统设计文档.md
INDEX_FIELDS_DOCUMENTATION.md -> docs/索引字段说明.md
@@ -1,938 +0,0 @@
-# 搜索引擎 API 接口文档
-
-## 概述
-
-本文档描述了电商搜索 SaaS 系统的 RESTful API 接口。系统提供强大的搜索功能，包括：
-
-- **多语言搜索**：支持中文、英文、俄文等多语言查询和自动翻译
-- **语义搜索**：基于 BGE-M3 文本向量和 CN-CLIP 图片向量的语义检索
-- **布尔表达式**：支持 AND、OR、RANK、ANDNOT 操作符
-- **灵活过滤**：精确匹配过滤器和数值范围过滤器
-- **分面搜索**：动态生成过滤选项，提供分组统计
-- **自定义排序**：支持按任意字段排序
-- **个性化排序**：可配置的相关性排序表达式
-
-## 基础信息
-
-- **Base URL**: `http://your-domain:6002`  (http://120.76.41.98:6002)
-- **协议**: HTTP/HTTPS
-- **数据格式**: JSON
-- **字符编码**: UTF-8
-
-## 搜索接口
-
-### 1. 文本搜索
-
-**端点**: `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 | Y | - | 搜索查询字符串，支持布尔表达式（AND, OR, RANK, ANDNOT） |
-| `size` | integer | N | 10 | 返回结果数量（1-100） |
-| `from` | integer | N | 0 | 分页偏移量 |
-| `filters` | object | N | null | 精确匹配过滤器（见下文） |
-| `range_filters` | object | N | null | 数值范围过滤器（见下文） |
-| `facets` | array | N | null | 分面配置（见下文） |
-| `sort_by` | string | N | null | 排序字段名 |
-| `sort_order` | string | N | "desc" | 排序方向：`asc` 或 `desc` |
-| `min_score` | float | N | null | 最小相关性分数阈值 |
-| `debug` | boolean | N | false | 是否返回调试信息 |
-| `user_id` | string | N | null | 用户ID（用于个性化，预留） |
-| `session_id` | string | N | null | 会话ID（用于分析，预留） |
-
-#### 过滤器详解
-
-##### 精确匹配过滤器 (filters)
-
-用于精确匹配或多值匹配（OR 逻辑）。
-
-**格式**:
-```json
-{
-  "filters": {
-    "categoryName_keyword": "玩具",           // 单值：精确匹配
-    "brandName_keyword": ["乐高", "孩之宝"],  // 数组：匹配任意值（OR）
-    "in_stock": true                          // 布尔值
-  }
-}
-```
-
-**支持的值类型**:
-- 字符串：精确匹配
-- 整数：精确匹配
-- 布尔值：精确匹配
-- 数组：匹配任意值（OR 逻辑）
-
-##### 范围过滤器 (range_filters)
-
-用于数值字段的范围过滤。
-
-**格式**:
-```json
-{
-  "range_filters": {
-    "price": {
-      "gte": 50,    // 大于等于
-      "lte": 200    // 小于等于
-    },
-    "days_since_last_update": {
-      "lte": 30     // 最近30天更新
-    }
-  }
-}
-```
-
-**支持的操作符**:
-- `gte`: 大于等于 (>=)
-- `gt`: 大于 (>)
-- `lte`: 小于等于 (<=)
-- `lt`: 小于 (<)
-
-**注意**: 至少需要指定一个操作符。
-
-##### 分面配置 (facets)
-
-用于生成分面统计（分组聚合）。
-
-**简单模式**（字符串数组）:
-```json
-{
-  "facets": ["categoryName_keyword", "brandName_keyword"]
-}
-```
-
-**高级模式**（配置对象数组）:
-```json
-{
-  "facets": [
-    {
-      "field": "categoryName_keyword",
-      "size": 15,
-      "type": "terms"
-    },
-    {
-      "field": "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' 时需要）
-
-#### 响应格式
-
-```json
-{
-  "hits": [
-    {
-      "_id": "12345",
-      "_score": 8.5,
-      "_custom_score": 12.3,
-      "_source": {
-        "name": "芭比时尚娃娃",
-        "price": 89.99,
-        "categoryName": "玩具",
-        "brandName": "美泰",
-        "imageUrl": "https://example.com/image.jpg"
-      }
-    }
-  ],
-  "total": 118,
-  "max_score": 8.5,
-  "took_ms": 45,
-  "facets": [
-    {
-      "field": "categoryName_keyword",
-      "label": "商品类目",
-      "type": "terms",
-      "values": [
-        {
-          "value": "玩具",
-          "label": "玩具",
-          "count": 85,
-          "selected": false
-        },
-        {
-          "value": "益智玩具",
-          "label": "益智玩具",
-          "count": 33,
-          "selected": false
-        }
-      ]
-    }
-  ],
-  "query_info": {
-    "original_query": "芭比娃娃",
-    "detected_language": "zh",
-    "translations": {
-      "en": "barbie doll"
-    }
-  },
-  "related_queries": null,
-  "performance_info": {
-    "total_duration": 45.2,
-    "stage_durations": {
-      "query_parsing": 5.3,
-      "elasticsearch_search": 35.1,
-      "result_processing": 4.8
-    }
-  },
-  "debug_info": null
-}
-```
-
-#### 响应字段说明
-
-| 字段 | 类型 | 描述 |
-|------|------|------|
-| `hits` | array | 搜索结果列表 |
-| `hits[]._id` | string | 文档ID |
-| `hits[]._score` | float | 相关性分数 |
-| `hits[]._custom_score` | float | 自定义排序分数（如启用） |
-| `hits[]._source` | object | 文档内容 |
-| `total` | integer | 匹配的总文档数 |
-| `max_score` | float | 最高相关性分数 |
-| `took_ms` | integer | 搜索耗时（毫秒） |
-| `facets` | array | 分面统计结果（标准化格式） |
-| `facets[].field` | string | 字段名 |
-| `facets[].label` | string | 显示标签 |
-| `facets[].type` | string | 分面类型：`terms` 或 `range` |
-| `facets[].values` | array | 分面值列表 |
-| `facets[].values[].value` | any | 分面值 |
-| `facets[].values[].label` | string | 显示标签 |
-| `facets[].values[].count` | integer | 文档数量 |
-| `facets[].values[].selected` | boolean | 是否已选中 |
-| `query_info` | object | 查询处理信息 |
-| `related_queries` | array | 相关搜索（预留） |
-| `performance_info` | object | 性能信息 |
-| `debug_info` | object | 调试信息（仅当 debug=true） |
-
-#### 请求示例
-
-**示例 1: 简单搜索**
-
-```bash
-curl -X POST "http://localhost:6002/search/" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "芭比娃娃",
-    "size": 20
-  }'
-```
-
-**示例 2: 带过滤器的搜索**
-
-```bash
-curl -X POST "http://localhost:6002/search/" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具",
-    "size": 20,
-    "filters": {
-      "categoryName_keyword": ["玩具", "益智玩具"],
-      "in_stock": true
-    },
-    "range_filters": {
-      "price": {
-        "gte": 50,
-        "lte": 200
-      }
-    }
-  }'
-```
-
-**示例 3: 带分面搜索（简单模式）**
-
-```bash
-curl -X POST "http://localhost:6002/search/" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具",
-    "size": 20,
-    "facets": ["categoryName_keyword", "brandName_keyword"]
-  }'
-```
-
-**示例 4: 带分面搜索（高级模式）**
-
-```bash
-curl -X POST "http://localhost:6002/search/" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具",
-    "size": 20,
-    "facets": [
-      {
-        "field": "categoryName_keyword",
-        "size": 15,
-        "type": "terms"
-      },
-      {
-        "field": "brandName_keyword",
-        "size": 15,
-        "type": "terms"
-      },
-      {
-        "field": "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}
-        ]
-      }
-    ]
-  }'
-```
-
-**示例 5: 复杂搜索（布尔表达式+过滤+排序）**
-
-```bash
-curl -X POST "http://localhost:6002/search/" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具 AND (乐高 OR 芭比)",
-    "size": 20,
-    "filters": {
-      "categoryName_keyword": "玩具"
-    },
-    "range_filters": {
-      "price": {
-        "gte": 50,
-        "lte": 200
-      },
-      "days_since_last_update": {
-        "lte": 30
-      }
-    },
-    "facets": [
-      {"field": "brandName_keyword", "size": 15},
-      {"field": "supplierName_keyword", "size": 10}
-    ],
-    "sort_by": "min_price",
-    "sort_order": "asc",
-    "debug": false
-  }'
-```
-
----
-
-### 2. 图片搜索
-
-**端点**: `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 | 数值范围过滤器 |
-
-#### 响应格式
-
-与文本搜索相同，但 `query_info` 包含图片信息：
-
-```json
-{
-  "hits": [...],
-  "total": 50,
-  "max_score": 0.95,
-  "took_ms": 120,
-  "query_info": {
-    "image_url": "https://example.com/image.jpg",
-    "search_type": "image_similarity"
-  }
-}
-```
-
-#### 请求示例
-
-```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": {
-      "categoryName_keyword": "玩具"
-    },
-    "range_filters": {
-      "price": {
-        "lte": 100
-      }
-    }
-  }'
-```
-
----
-
-### 3. 搜索建议（框架）
-
-**端点**: `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"
-```
-
----
-
-### 4. 即时搜索（框架）
-
-**端点**: `GET /search/instant`
-
-**描述**: 即时搜索，边输入边搜索。
-
-**注意**: 此功能暂未实现，调用标准搜索接口。
-
-#### 查询参数
-
-| 参数 | 类型 | 必填 | 默认值 | 描述 |
-|------|------|------|--------|------|
-| `q` | string | ✅ | - | 搜索查询（最少2个字符） |
-| `size` | integer | ❌ | 5 | 结果数量（1-20） |
-
-#### 请求示例
-
-```bash
-curl "http://localhost:6002/search/instant?q=玩具&size=5"
-```
-
----
-
-### 5. 获取单个文档
-
-**端点**: `GET /search/{doc_id}`
-
-**描述**: 根据文档ID获取单个文档详情。
-
-#### 路径参数
-
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| `doc_id` | string | 文档ID |
-
-#### 响应格式
-
-```json
-{
-  "id": "12345",
-  "source": {
-    "name": "芭比时尚娃娃",
-    "price": 89.99,
-    "categoryName": "玩具"
-  }
-}
-```
-
-#### 请求示例
-
-```bash
-curl "http://localhost:6002/search/12345"
-```
-
----
-
-## 管理接口
-
-### 1. 健康检查
-
-**端点**: `GET /admin/health`
-
-**描述**: 检查服务健康状态。
-
-#### 响应格式
-
-```json
-{
-  "status": "healthy",
-  "elasticsearch": "connected",
-  "tenant_id": "tenant1"
-}
-```
-
----
-
-### 2. 获取配置
-
-**端点**: `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
-}
-```
-
----
-
-### 3. 索引统计
-
-**端点**: `GET /admin/stats`
-
-**描述**: 获取索引统计信息。
-
-#### 响应格式
-
-```json
-{
-  "index_name": "search_tenant1",
-  "document_count": 10000,
-  "size_mb": 523.45
-}
-```
-
----
-
-### 4. 查询改写规则
-
-**端点**: `GET /admin/rewrite-rules`
-
-**描述**: 获取当前的查询改写规则。
-
-#### 响应格式
-
-```json
-{
-  "rules": {
-    "乐高": "brand:乐高 OR name:乐高",
-    "玩具": "category:玩具"
-  },
-  "count": 2
-}
-```
-
-**端点**: `POST /admin/rewrite-rules`
-
-**描述**: 更新查询改写规则。
-
-#### 请求格式
-
-```json
-{
-  "乐高": "brand:乐高 OR name:乐高",
-  "芭比": "brand:芭比 OR name:芭比"
-}
-```
-
----
-
-## 使用示例
-
-### Python 示例
-
-```python
-import requests
-
-API_URL = "http://localhost:6002/search/"
-
-# 简单搜索
-response = requests.post(API_URL, json={
-    "query": "芭比娃娃",
-    "size": 20
-})
-data = response.json()
-print(f"找到 {data['total']} 个结果")
-
-# 带过滤器和分面的搜索
-response = requests.post(API_URL, json={
-    "query": "玩具",
-    "size": 20,
-    "filters": {
-        "categoryName_keyword": ["玩具", "益智玩具"]
-    },
-    "range_filters": {
-        "price": {"gte": 50, "lte": 200}
-    },
-    "facets": [
-        {"field": "brandName_keyword", "size": 15},
-        {"field": "categoryName_keyword", "size": 15}
-    ],
-    "sort_by": "min_price",
-    "sort_order": "asc"
-})
-result = response.json()
-
-# 处理分面结果
-for facet in result.get('facets', []):
-    print(f"\n{facet['label']}:")
-    for value in facet['values']:
-        print(f"  - {value['label']}: {value['count']}")
-```
-
-### JavaScript 示例
-
-```javascript
-// 搜索函数
-async function searchProducts(query, filters, rangeFilters, facets) {
-    const response = await fetch('http://localhost:6002/search/', {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
-            query: query,
-            size: 20,
-            filters: filters,
-            range_filters: rangeFilters,
-            facets: facets
-        })
-    });
-    
-    const data = await response.json();
-    return data;
-}
-
-// 使用示例
-const result = await searchProducts(
-    "玩具",
-    { categoryName_keyword: ["玩具"] },
-    { price: { gte: 50, lte: 200 } },
-    [
-        { field: "brandName_keyword", size: 15 },
-        { field: "categoryName_keyword", size: 15 }
-    ]
-);
-
-// 显示分面结果
-result.facets.forEach(facet => {
-    console.log(`${facet.label}:`);
-    facet.values.forEach(value => {
-        console.log(`  - ${value.label}: ${value.count}`);
-    });
-});
-
-// 显示搜索结果
-result.hits.forEach(hit => {
-    const product = hit._source;
-    console.log(`${product.name} - ¥${product.price}`);
-});
-```
-
-### cURL 示例
-
-```bash
-# 简单搜索
-curl -X POST "http://localhost:6002/search/" \
-  -H "Content-Type: application/json" \
-  -d '{"query": "芭比娃娃", "size": 20}'
-
-# 带过滤和排序
-curl -X POST "http://localhost:6002/search/" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具",
-    "size": 20,
-    "filters": {"categoryName_keyword": "玩具"},
-    "range_filters": {"price": {"gte": 50, "lte": 200}},
-    "sort_by": "min_price",
-    "sort_order": "asc"
-  }'
-
-# 带分面搜索
-curl -X POST "http://localhost:6002/search/" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具",
-    "size": 20,
-    "facets": [
-      {"field": "categoryName_keyword", "size": 15},
-      {"field": "brandName_keyword", "size": 15}
-    ]
-  }'
-```
-
----
-
-## 布尔表达式语法
-
-### 支持的操作符
-
-| 操作符 | 描述 | 示例 |
-|--------|------|------|
-| `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 芭比) ANDNOT 电动"
-
-# 域查询
-"brand:乐高"
-"category:玩具"
-"title:芭比娃娃"
-```
-
----
-
-## 数据模型
-
-### 商品字段
-
-常见的商品字段包括：
-
-| 字段名 | 类型 | 描述 |
-|--------|------|------|
-| `skuId` | long | SKU ID（主键） |
-| `name` | text | 商品名称（中文） |
-| `enSpuName` | text | 商品名称（英文） |
-| `ruSkuName` | text | 商品名称（俄文） |
-| `categoryName` | text | 类目名称 |
-| `categoryName_keyword` | keyword | 类目名称（精确匹配） |
-| `brandName` | text | 品牌名称 |
-| `brandName_keyword` | keyword | 品牌名称（精确匹配） |
-| `supplierName` | text | 供应商名称 |
-| `supplierName_keyword` | keyword | 供应商名称（精确匹配） |
-| `price` | double | 价格 |
-| `imageUrl` | keyword | 商品图片URL |
-| `create_time` | date | 创建时间 |
-| `days_since_last_update` | int | 距上次更新天数 |
-
-**注意**: 不同客户可能有不同的字段配置。
-
----
-
-
-## 常见问题
-
-### Q1: 如何判断一个字段应该用哪种过滤器？
-
-**A**: 
-- **精确匹配过滤器** (`filters`): 用于 KEYWORD 类型字段（如类目、品牌、标签等）
-- **范围过滤器** (`range_filters`): 用于数值类型字段（如价格、库存、时间等）
-
-### Q2: 可以同时使用多个过滤器吗？
-
-**A**: 可以。多个过滤器之间是 AND 关系（必须同时满足）。
-
-```json
-{
-  "filters": {
-    "categoryName_keyword": "玩具",
-    "brandName_keyword": "乐高"
-  },
-  "range_filters": {
-    "price": {"gte": 50, "lte": 200}
-  }
-}
-```
-结果：类目是"玩具" **并且** 品牌是"乐高" **并且** 价格在50-200之间。
-
-### Q3: 如何实现"价格小于50或大于200"的过滤？
-
-**A**: 当前版本不支持单字段多个不连续范围。建议分两次查询或使用布尔查询。
-
-### Q4: 分面搜索返回的 selected 字段是什么意思？
-
-**A**: `selected` 表示该分面值是否在当前的过滤器中。前端可以用它来高亮已选中的过滤项。
-
-### Q5: 如何使用自定义排序？
-
-**A**: 使用 `sort_by` 和 `sort_order` 参数：
-
-```json
-{
-  "query": "玩具",
-  "sort_by": "price",
-  "sort_order": "asc"  // 价格从低到高
-}
-```
-
-常用排序字段：
-- `price`: 价格
-- `create_time`: 创建时间
-- `days_since_last_update`: 更新时间
-
-### Q6: 如何启用调试模式？
-
-**A**: 设置 `debug: true`，响应中会包含 `debug_info` 字段，包含：
-- 查询分析过程
-- ES 查询 DSL
-- ES 响应详情
-- 各阶段耗时
-
----
-
-## 版本历史
-
-### v3.0 (2024-11-12)
-
-**重大更新**：
-- ✅ 移除硬编码的 `price_ranges` 逻辑
-- ✅ 新增 `range_filters` 参数，支持任意数值字段的范围过滤
-- ✅ 新增 `facets` 参数，替代 `aggregations`，提供简化接口
-- ✅ 标准化分面搜索响应格式
-- ✅ 新增 `/search/suggestions` 端点（框架）
-- ✅ 新增 `/search/instant` 端点（框架）
-- ❌ **移除** `aggregations` 参数（不向后兼容）
-
-**迁移指南**：
-
-旧接口：
-```json
-{
-  "filters": {
-    "price_ranges": ["0-50", "50-100"]
-  },
-  "aggregations": {
-    "category_stats": {"terms": {"field": "categoryName_keyword", "size": 15}}
-  }
-}
-```
-
-新接口：
-```json
-{
-  "range_filters": {
-    "price": {"gte": 50, "lte": 100}
-  },
-  "facets": [
-    {"field": "categoryName_keyword", "size": 15}
-  ]
-}
-```
-
----
-
-## 附录
-
-### A. 支持的分析器
-
-| 分析器 | 语言 | 描述 |
-|--------|------|------|
-| `chinese_ecommerce` | 中文 | Ansj 中文分词器（电商优化） |
-| `english` | 英文 | 标准英文分析器 |
-| `russian` | 俄文 | 俄文分析器 |
-| `arabic` | 阿拉伯文 | 阿拉伯文分析器 |
-| `spanish` | 西班牙文 | 西班牙文分析器 |
-| `japanese` | 日文 | 日文分析器 |
-
-### B. 字段类型
-
-| 类型 | ES 映射 | 用途 |
-|------|---------|------|
-| `TEXT` | text | 全文检索 |
-| `KEYWORD` | keyword | 精确匹配、聚合、排序 |
-| `LONG` | long | 整数 |
-| `DOUBLE` | double | 浮点数 |
-| `DATE` | date | 日期时间 |
-| `BOOLEAN` | boolean | 布尔值 |
-| `TEXT_EMBEDDING` | dense_vector | 文本向量（1024维） |
-| `IMAGE_EMBEDDING` | dense_vector | 图片向量（1024维） |
-
@@ -1,274 +0,0 @@
-# 最佳实践重构总结
-
-**重构日期**: 2025-11-12  
-**重构人员**: AI Assistant  
-**重构原则**: 代码简洁、类型安全、单一职责
-
----
-
-## 重构目标
-
-1. **移除兼容代码**：不再支持多种数据格式，统一使用最佳实践
-2. **修复前端422错误**：支持日期时间字符串的 range filter
-3. **保持代码简洁**：单一数据流，清晰的类型定义
-
----
-
-## 修改文件
-
-### 1. `/home/tw/SearchEngine/api/models.py`
-
-#### 修改：RangeFilter 模型
-
-**之前**：只支持数值 (float)
-```python
-gte: Optional[float] = Field(None, description="大于等于 (>=)")
-```
-
-**之后**：支持数值和日期时间字符串
-```python
-gte: Optional[Union[float, str]] = Field(None, description="大于等于 (>=)。数值或ISO日期时间字符串")
-```
-
-**理由**：
-- 价格字段需要数值过滤：`{"gte": 50, "lte": 200}`
-- 时间字段需要字符串过滤：`{"gte": "2023-01-01T00:00:00Z"}`
-- 使用 `Union[float, str]` 同时支持两种类型
-
----
-
-### 2. `/home/tw/SearchEngine/search/es_query_builder.py`
-
-#### 修改：build_facets 方法
-
-**之前**：兼容字典和 Pydantic 模型
-```python
-else:
-    if isinstance(config, dict):
-        field = config['field']
-        facet_type = config.get('type', 'terms')
-        ...
-    else:
-        # Pydantic模型
-        field = config.field
-        facet_type = config.type
-        ...
-```
-
-**之后**：只支持标准格式（str 或 FacetConfig）
-```python
-# 简单模式：只有字段名（字符串）
-if isinstance(config, str):
-    field = config
-    ...
-
-# 高级模式：FacetConfig 对象
-else:
-    field = config.field
-    facet_type = config.type
-    ...
-```
-
-**理由**：
-- API 层已经定义标准格式：`List[Union[str, FacetConfig]]`
-- 移除字典支持，保持单一数据流
-- 代码更简洁，意图更清晰
-
----
-
-### 3. `/home/tw/SearchEngine/search/searcher.py`
-
-#### 修改：_standardize_facets 方法
-
-**之前**：兼容字典和 Pydantic 模型
-```python
-else:
-    field = config.get('field') if isinstance(config, dict) else config.field
-    facet_type = config.get('type', 'terms') if isinstance(config, dict) else getattr(config, 'type', 'terms')
-```
-
-**之后**：只支持标准格式
-```python
-else:
-    # FacetConfig 对象
-    field = config.field
-    facet_type = config.type
-```
-
-**理由**：
-- 与 build_facets 保持一致
-- 移除冗余的类型检查
-- 代码更清晰易读
-
----
-
-## 数据流设计
-
-### 标准数据流（最佳实践）
-
-```
-API Request
-    ↓
-Pydantic 验证 (SearchRequest)
-    ↓ facets: List[Union[str, FacetConfig]]
-Searcher.search()
-    ↓
-QueryBuilder.build_facets()
-    ↓ 只接受 str 或 FacetConfig
-ES Query (aggs)
-    ↓
-ES Response (aggregations)
-    ↓
-Searcher._standardize_facets()
-    ↓ 只处理 str 或 FacetConfig
-List[FacetResult] (Pydantic 模型)
-    ↓
-SearchResponse
-    ↓
-API Response (JSON)
-```
-
-### 类型定义
-
-```python
-# API 层
-facets: Optional[List[Union[str, FacetConfig]]] = None
-
-# Query Builder 层
-def build_facets(facet_configs: Optional[List[Union[str, 'FacetConfig']]])
-
-# Searcher 层
-def _standardize_facets(...) -> Optional[List[FacetResult]]
-
-# Response 层
-facets: Optional[List[FacetResult]] = None
-```
-
----
-
-## 测试结果
-
-### ✅ 所有测试通过
-
-| 测试场景 | 状态 | 说明 |
-|---------|------|------|
-| 字符串 facets | ✓ | `["categoryName_keyword"]` |
-| FacetConfig 对象 | ✓ | `{"field": "price", "type": "range", ...}` |
-| 数值 range filter | ✓ | `{"gte": 50, "lte": 200}` |
-| 日期时间 range filter | ✓ | `{"gte": "2023-01-01T00:00:00Z"}` |
-| 混合使用 | ✓ | filters + range_filters + facets |
-
-### ✅ 前端 422 错误已修复
-
-**问题**：前端筛选 listing time 时返回 422 Unprocessable Entity
-
-**原因**：`RangeFilter` 只接受 `float`，不接受日期时间字符串
-
-**解决**：修改 `RangeFilter` 支持 `Union[float, str]`
-
-**验证**：
-```bash
-curl -X POST /search/ \
-  -d '{"query": "玩具", "range_filters": {"create_time": {"gte": "2023-01-01T00:00:00Z"}}}'
-# ✓ 200 OK
-```
-
----
-
-## 代码质量
-
-### ✅ 无 Linter 错误
-```bash
-No linter errors found.
-```
-
-### ✅ 类型安全
-- 所有类型明确定义
-- Pydantic 自动验证
-- IDE 类型提示完整
-
-### ✅ 代码简洁
-- 移除所有兼容代码
-- 单一数据格式
-- 清晰的控制流
-
----
-
-## 最佳实践原则
-
-### 1. **单一职责**
-每个方法只处理一种标准格式，不兼容多种输入
-
-### 2. **类型明确**
-使用 Pydantic 模型而不是字典，类型在编译时就确定
-
-### 3. **数据流清晰**
-API → Pydantic → 业务逻辑 → Pydantic → Response
-
-### 4. **早期验证**
-在 API 层就验证数据，不在内部做多重兼容检查
-
-### 5. **代码可维护**
-- 删除冗余代码
-- 保持一致性
-- 易于理解和修改
-
----
-
-## 对比总结
-
-| 方面 | 重构前 | 重构后 |
-|------|-------|--------|
-| **数据格式** | 字典 + Pydantic（兼容） | 只有 Pydantic |
-| **类型检查** | 运行时多重检查 | 编译时类型明确 |
-| **代码行数** | 更多（兼容代码） | 更少（单一逻辑） |
-| **可维护性** | 复杂（多种路径） | 简单（单一路径） |
-| **错误处理** | 隐式容错 | 明确验证 |
-| **RangeFilter** | 只支持数值 | 支持数值+字符串 |
-| **前端兼容** | 422 错误 | 完全兼容 |
-
----
-
-## 后续建议
-
-### 1. 代码审查
-- [x] 移除所有字典兼容代码
-- [x] 统一使用 Pydantic 模型
-- [x] 修复前端 422 错误
-
-### 2. 测试覆盖
-- [x] 字符串 facets
-- [x] FacetConfig 对象
-- [x] 数值 range filter
-- [x] 日期时间 range filter
-- [x] 混合场景
-
-### 3. 文档更新
-- [x] 最佳实践文档
-- [x] 数据流设计
-- [ ] API 文档更新
-
-### 4. 性能优化
-- [ ] 添加请求缓存
-- [ ] 优化 Pydantic 验证
-- [ ] 监控性能指标
-
----
-
-## 结论
-
-本次重构成功实现了以下目标：
-
-✅ **代码简洁**：移除所有兼容代码，保持单一数据流  
-✅ **类型安全**：统一使用 Pydantic 模型，编译时类型检查  
-✅ **功能完整**：修复前端 422 错误，支持所有筛选场景  
-✅ **可维护性**：代码清晰，易于理解和修改  
-
-**核心原则**：*不做兼容多种方式的代码，定义一种最佳实践，所有模块都适配这种新方式*
-
----
-
-**版本**: v3.1  
-**状态**: ✅ 完成并通过测试  
-**下次更新**: 根据业务需求扩展
-
@@ -1,611 +0,0 @@
-# 变更日志 (CHANGELOG)
-
----
-
-## v3.0 - API 接口重构 (2024-11-12)
-
-### 重大更新
-
-本版本对搜索 API 进行了全面重构，移除硬编码逻辑，实现了灵活通用的 SaaS 接口设计。
-
-#### ❌ 破坏性变更（不向后兼容）
-
-1. **移除硬编码的 price_ranges 参数**
-   - 旧方式：`filters: {"price_ranges": ["0-50", "50-100"]}`
-   - 新方式：`range_filters: {"price": {"gte": 50, "lte": 100}}`
-
-2. **移除 aggregations 参数**
-   - 旧方式：`aggregations: {"category_stats": {"terms": {...}}}`（ES DSL）
-   - 新方式：`facets: [{"field": "categoryName_keyword", "size": 15}]`（简化配置）
-
-3. **响应格式变更**
-   - 旧方式：`response.aggregations`（ES 原始格式）
-   - 新方式：`response.facets`（标准化格式）
-
-#### ✅ 新增功能
-
-1. **结构化过滤参数**
-   - 新增 `range_filters` 参数：支持任意数值字段的范围过滤
-   - 支持 `gte`, `gt`, `lte`, `lt` 操作符
-   - 示例：
-     ```json
-     {
-       "range_filters": {
-         "price": {"gte": 50, "lte": 200},
-         "days_since_last_update": {"lte": 30}
-       }
-     }
-     ```
-
-2. **简化的分面配置**
-   - 新增 `facets` 参数：替代复杂的 ES DSL
-   - 支持简单模式（字符串数组）和高级模式（配置对象）
-   - 示例：
-     ```json
-     {
-       "facets": [
-         "categoryName_keyword",  // 简单模式
-         {"field": "brandName_keyword", "size": 15}  // 高级模式
-       ]
-     }
-     ```
-
-3. **标准化分面响应**
-   - 统一的分面结果格式
-   - 包含 `field`, `label`, `type`, `values`
-   - `values` 包含 `value`, `label`, `count`, `selected`
-   - 示例：
-     ```json
-     {
-       "facets": [
-         {
-           "field": "categoryName_keyword",
-           "label": "商品类目",
-           "type": "terms",
-           "values": [
-             {"value": "玩具", "label": "玩具", "count": 85, "selected": false}
-           ]
-         }
-       ]
-     }
-     ```
-
-4. **新增搜索建议端点**（框架）
-   - `GET /search/suggestions`: 自动补全
-   - `GET /search/instant`: 即时搜索
-   - 注：暂未实现，仅返回框架响应
-
-#### 🔧 代码改进
-
-1. **后端模型层** (`api/models.py`)
-   - 新增 `RangeFilter` 模型
-   - 新增 `FacetConfig` 模型
-   - 新增 `FacetValue` 和 `FacetResult` 模型
-   - 更新 `SearchRequest` 和 `SearchResponse`
-
-2. **查询构建器** (`search/es_query_builder.py`)
-   - **完全移除** 硬编码的 `price_ranges` 逻辑（第 205-233 行）
-   - 重构 `_build_filters` 方法，支持 `range_filters`
-   - **删除** `add_dynamic_aggregations` 方法
-   - 新增 `build_facets` 方法
-
-3. **搜索执行层** (`search/searcher.py`)
-   - 更新 `search()` 方法签名
-   - 新增 `_standardize_facets()` 方法
-   - 新增 `_get_field_label()` 方法
-   - 更新 `SearchResult` 类
-
-4. **API 路由层** (`api/routes/search.py`)
-   - 更新所有搜索端点
-   - 新增 `/search/suggestions` 端点
-   - 新增 `/search/instant` 端点
-
-5. **前端代码** (`frontend/static/js/app.js`)
-   - 更新状态管理，添加 `rangeFilters`
-   - 完全重写 `displayAggregations` 为 `displayFacets`
-   - 更新过滤器处理逻辑
-   - 删除所有硬编码的 `price_ranges`
-
-#### 📚 文档更新
-
-- 新增 `API_DOCUMENTATION.md`：完整的 API 接口文档
-- 更新 `README.md`：添加 v3.0 新功能说明
-- 更新 `USER_GUIDE.md`：更新 API 使用示例
-
-#### 🎯 改进要点
-
-**从特定实现到通用 SaaS**：
-- ❌ 移除：硬编码的价格范围值
-- ❌ 移除：暴露 ES DSL 的聚合接口
-- ❌ 移除：不统一的响应格式
-- ✅ 新增：通用的范围过滤器
-- ✅ 新增：简化的分面配置
-- ✅ 新增：标准化的响应格式
-
-#### 📋 迁移指南
-
-**旧接口** → **新接口**
-
-1. **过滤器迁移**：
-   ```json
-   // 旧
-   {"filters": {"price_ranges": ["50-100"]}}
-   
-   // 新
-   {"range_filters": {"price": {"gte": 50, "lte": 100}}}
-   ```
-
-2. **聚合迁移**：
-   ```json
-   // 旧
-   {
-     "aggregations": {
-       "category_stats": {
-         "terms": {"field": "categoryName_keyword", "size": 15}
-       }
-     }
-   }
-   
-   // 新
-   {
-     "facets": [
-       {"field": "categoryName_keyword", "size": 15}
-     ]
-   }
-   ```
-
-3. **响应解析迁移**：
-   ```javascript
-   // 旧
-   data.aggregations.category_stats.buckets.forEach(bucket => {
-       console.log(bucket.key, bucket.doc_count);
-   });
-   
-   // 新
-   data.facets.forEach(facet => {
-       facet.values.forEach(value => {
-           console.log(value.value, value.count);
-       });
-   });
-   ```
-
----
-
-## v2.x - 前端优化更新 (2025-11-11)
-
-## 概述
-基于提供的电商搜索引擎参考图片，对前端界面进行了全面重新设计和优化，采用更现代、简洁的布局风格。
-
----
-
-## 修改的文件
-
-### 1. `/home/tw/SearchEngine/frontend/index.html` ✅ 完全重写
-**更改内容：**
-- 去除旧的搜索示例和复杂布局
-- 添加简洁的顶部标题栏（Product + 商品数量 + Fold按钮）
-- 重新设计搜索栏（更简洁）
-- 添加水平筛选标签区域（Categories, Brand, Supplier）
-- 添加排序工具栏（带上下箭头的排序按钮）
-- 改用网格布局展示商品
-- 添加分页组件
-- 将查询信息改为可折叠的Debug区域
-
-**关键改进：**
-```html
-<!-- 新增顶部标题栏 -->
-<header class="top-header">
-    <div class="header-left">
-        <span class="logo">Product</span>
-        <span class="product-count">0 products found</span>
-    </div>
-    <div class="header-right">
-        <button class="fold-btn">Fold</button>
-    </div>
-</header>
-
-<!-- 新增水平筛选标签 -->
-<div class="filter-section">
-    <div class="filter-row">
-        <div class="filter-label">Categories:</div>
-        <div class="filter-tags" id="categoryTags"></div>
-    </div>
-    <!-- 品牌、供应商等 -->
-</div>
-
-<!-- 新增排序栏（带箭头） -->
-<div class="sort-section">
-    <button class="sort-btn">
-        By Price
-        <span class="sort-arrows">
-            <span class="arrow-up">▲</span>
-            <span class="arrow-down">▼</span>
-        </span>
-    </button>
-</div>
-
-<!-- 商品网格 -->
-<div class="product-grid"></div>
-
-<!-- 分页 -->
-<div class="pagination"></div>
-```
-
----
-
-### 2. `/home/tw/SearchEngine/frontend/static/css/style.css` ✅ 完全重写
-**更改内容：**
-- 去除紫色渐变背景，改为白色简洁背景
-- 重新设计所有组件样式
-- 添加顶部标题栏样式
-- 添加水平筛选标签样式（带hover和active状态）
-- 添加排序按钮样式（带箭头）
-- 重新设计商品卡片样式（网格布局）
-- 添加分页样式
-- 优化响应式设计
-
-**关键样式：**
-```css
-/* 白色背景 */
-body {
-    background: #f5f5f5;
-}
-
-/* 筛选标签 */
-.filter-tag {
-    padding: 6px 15px;
-    background: #f8f8f8;
-    border: 1px solid #ddd;
-    cursor: pointer;
-}
-
-.filter-tag.active {
-    background: #e74c3c;
-    color: white;
-}
-
-/* 排序箭头 */
-.sort-arrows {
-    display: inline-flex;
-    flex-direction: column;
-    font-size: 10px;
-}
-
-/* 商品网格 */
-.product-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
-    gap: 20px;
-}
-
-/* 商品卡片 */
-.product-card {
-    background: white;
-    border: 1px solid #e0e0e0;
-    border-radius: 8px;
-    transition: all 0.3s;
-}
-
-.product-card:hover {
-    box-shadow: 0 4px 12px rgba(0,0,0,0.1);
-    transform: translateY(-2px);
-}
-```
-
-**代码量对比：**
-- 旧版：433行
-- 新版：450行
-- 变化：+17行（增加了更多功能和响应式样式）
-
----
-
-### 3. `/home/tw/SearchEngine/frontend/static/js/app.js` ✅ 完全重构
-**更改内容：**
-- 添加状态管理对象（统一管理所有状态）
-- 重写搜索函数（支持分页）
-- 重写结果展示函数（商品网格布局）
-- 重写筛选聚合函数（水平标签展示）
-- 添加排序函数（支持字段+方向）
-- 添加分页函数（完整分页导航）
-- 优化代码结构（更模块化）
-
-**关键功能：**
-```javascript
-// 状态管理
-let state = {
-    query: '',
-    currentPage: 1,
-    pageSize: 20,
-    totalResults: 0,
-    filters: {},
-    sortBy: '',
-    sortOrder: 'desc',
-    aggregations: null
-};
-
-// 排序函数（支持上下箭头）
-function sortByField(field, order) {
-    state.sortBy = field;
-    state.sortOrder = order;
-    performSearch(state.currentPage);
-}
-
-// 分页函数
-function goToPage(page) {
-    performSearch(page);
-    window.scrollTo({ top: 0, behavior: 'smooth' });
-}
-
-// 商品网格展示
-function displayResults(data) {
-    // 生成商品卡片HTML
-    data.hits.forEach((hit) => {
-        html += `
-            <div class="product-card">
-                <div class="product-image-wrapper">...</div>
-                <div class="product-price">...</div>
-                <div class="product-moq">...</div>
-                <div class="product-title">...</div>
-            </div>
-        `;
-    });
-}
-
-// 水平筛选标签
-function displayAggregations(aggregations) {
-    // 显示为可点击的标签
-    html += `
-        <span class="filter-tag ${isActive ? 'active' : ''}" 
-              onclick="toggleFilter(...)">
-            ${key} (${count})
-        </span>
-    `;
-}
-```
-
-**代码量对比：**
-- 旧版：516行
-- 新版：465行
-- 变化：-51行（代码更简洁，功能更强）
-
----
-
-### 4. `/home/tw/SearchEngine/api/app.py` ✅ 添加静态文件服务
-**更改内容：**
-- 导入 `FileResponse` 和 `StaticFiles`
-- 添加前端HTML服务路由
-- 挂载静态文件目录（CSS, JS）
-- 将原有的 `/` 路由改为 `/api`
-
-**关键代码：**
-```python
-from fastapi.responses import FileResponse
-from fastapi.staticfiles import StaticFiles
-
-# 在文件末尾添加
-frontend_path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "frontend")
-if os.path.exists(frontend_path):
-    # 服务前端HTML
-    @app.get("/")
-    async def serve_frontend():
-        index_path = os.path.join(frontend_path, "index.html")
-        if os.path.exists(index_path):
-            return FileResponse(index_path)
-    
-    # 挂载静态文件
-    app.mount("/static", StaticFiles(directory=os.path.join(frontend_path, "static")), name="static")
-```
-
----
-
-## 新增的文件
-
-### 5. `/home/tw/SearchEngine/frontend/README.md` ✅ 新建
-前端详细文档，包含：
-- 优化说明
-- 功能介绍
-- 使用方法
-- 技术特点
-- 浏览器兼容性
-- 未来改进计划
-
-### 6. `/home/tw/SearchEngine/FRONTEND_GUIDE.md` ✅ 新建
-快速上手指南，包含：
-- 优化总结
-- 启动方法
-- 测试步骤
-- 常见问题
-- API接口说明
-- 性能指标
-
-### 7. `/home/tw/SearchEngine/scripts/test_frontend.sh` ✅ 新建
-自动化测试脚本，测试：
-- 健康检查
-- 前端HTML
-- CSS文件
-- JavaScript文件
-- 搜索API
-
-### 8. `/home/tw/SearchEngine/CHANGES.md` ✅ 新建
-本文件，记录所有更改。
-
----
-
-## 功能对比表
-
-| 功能 | 旧版前端 | 新版前端 | 状态 |
-|------|---------|---------|------|
-| 背景颜色 | 紫色渐变 | 白色简洁 | ✅ 优化 |
-| 顶部标题栏 | 大标题+副标题 | Product + 商品数 | ✅ 优化 |
-| 搜索框 | 带多个选项 | 简洁搜索框 | ✅ 优化 |
-| 筛选方式 | 左侧垂直面板 | 顶部水平标签 | ✅ 优化 |
-| 筛选交互 | 复选框 | 可点击标签 | ✅ 优化 |
-| 排序方式 | 下拉选择 | 按钮+箭头 | ✅ 优化 |
-| 商品展示 | 列表布局 | 网格布局 | ✅ 优化 |
-| 商品卡片 | 横向卡片 | 垂直卡片 | ✅ 优化 |
-| 分页功能 | ❌ 无 | ✅ 完整分页 | ✅ 新增 |
-| 响应式设计 | 基础支持 | 完整响应式 | ✅ 优化 |
-| 代码结构 | 混乱 | 模块化 | ✅ 优化 |
-| 状态管理 | 分散 | 统一管理 | ✅ 优化 |
-
----
-
-## 技术改进
-
-### 前端架构
-- ✅ **状态管理**：统一的state对象
-- ✅ **模块化**：功能清晰分离
-- ✅ **代码简化**：去除冗余代码
-- ✅ **性能优化**：减少DOM操作
-
-### UI/UX设计
-- ✅ **视觉一致性**：统一的设计语言
-- ✅ **交互直观**：标签式筛选，箭头排序
-- ✅ **响应迅速**：即时反馈
-- ✅ **移动友好**：完整的响应式支持
-
-### 代码质量
-- ✅ **可维护性**：清晰的结构
-- ✅ **可扩展性**：易于添加新功能
-- ✅ **可读性**：注释完整
-- ✅ **无linter错误**：代码规范
-
----
-
-## 测试步骤
-
-### 1. 启动服务
-```bash
-cd /home/tw/SearchEngine
-bash scripts/start_backend.sh
-```
-
-### 2. 运行测试
-```bash
-bash scripts/test_frontend.sh
-```
-
-### 3. 手动测试
-访问：`http://120.76.41.98:6002/`
-
-测试项目：
-- [ ] 页面正常加载
-- [ ] 搜索功能正常
-- [ ] 筛选标签可点击
-- [ ] 排序箭头可用
-- [ ] 商品网格展示正常
-- [ ] 分页功能正常
-- [ ] 响应式布局正常
-
----
-
-## 兼容性
-
-### 浏览器
-- ✅ Chrome 90+
-- ✅ Firefox 88+
-- ✅ Safari 14+
-- ✅ Edge 90+
-- ✅ 移动浏览器
-
-### 屏幕尺寸
-- ✅ 桌面（1920x1080）
-- ✅ 笔记本（1366x768）
-- ✅ 平板（768x1024）
-- ✅ 手机（375x667）
-
----
-
-## 性能指标
-
-| 指标 | 旧版 | 新版 | 改进 |
-|------|------|------|------|
-| 首屏加载 | ~1.5s | ~0.8s | ⬇️ 47% |
-| JavaScript大小 | 15KB | 13KB | ⬇️ 13% |
-| CSS大小 | 12KB | 11KB | ⬇️ 8% |
-| DOM节点数 | ~350 | ~200 | ⬇️ 43% |
-| 重绘次数 | 高 | 低 | ⬆️ 优化 |
-
----
-
-## 最佳实践应用
-
-### HTML
-- ✅ 语义化标签
-- ✅ 无障碍支持（ARIA）
-- ✅ SEO友好
-
-### CSS
-- ✅ CSS Grid布局
-- ✅ Flexbox布局
-- ✅ CSS变量
-- ✅ 媒体查询（响应式）
-
-### JavaScript
-- ✅ ES6+语法
-- ✅ 事件委托
-- ✅ 防抖/节流（如需要）
-- ✅ 错误处理
-
----
-
-## 下一步优化建议
-
-### 短期（1-2周）
-- [ ] 添加加载骨架屏
-- [ ] 优化图片懒加载
-- [ ] 添加搜索建议（自动完成）
-
-### 中期（1个月）
-- [ ] 添加用户偏好设置
-- [ ] 支持多主题切换
-- [ ] 添加商品收藏功能
-
-### 长期（3个月）
-- [ ] PWA支持（离线访问）
-- [ ] 国际化（多语言）
-- [ ] 性能监控
-
----
-
-## 回滚方案
-
-如需回滚到旧版：
-
-```bash
-cd /home/tw/SearchEngine
-git checkout HEAD~1 frontend/
-# 或从备份恢复
-```
-
----
-
-## 总结
-
-### 完成情况
-- ✅ HTML重构：100%
-- ✅ CSS重写：100%
-- ✅ JavaScript重构：100%
-- ✅ 后端适配：100%
-- ✅ 文档编写：100%
-- ✅ 测试脚本：100%
-
-### 核心成果
-1. **更好的用户体验**：简洁、直观的界面
-2. **更强的功能**：完整的筛选、排序、分页
-3. **更好的代码**：模块化、可维护
-4. **更好的性能**：更快的加载和响应
-
-### 达成目标
-✅ 完全符合参考图片的布局风格
-✅ 实现了所有要求的功能
-✅ 遵循了最佳实践
-✅ 代码质量高，易于维护
-✅ 响应式设计，支持多端
-
----
-
-**优化完成时间**：2025-11-11
-**总耗时**：约2小时
-**状态**：✅ 生产就绪
-
@@ -15,12 +15,12 @@
  
 | 步骤 | 去哪里看 | 摘要 |
 |------|---------|------|
-| 1. 准备环境 | `环境相关.md` / `USAGE_GUIDE.md` | Conda/依赖、Elasticsearch、MySQL、必需的变量 |
-| 2. 构造测试数据 | `TEST_DATA_GUIDE.md` | Tenant1 Mock、Tenant2 CSV、`mock_data.sh` / `ingest.sh` |
-| 3. 启动与验证 | `USAGE_GUIDE.md` | `run.sh` 一键启动、分步脚本、日志与健康检查 |
-| 4. 理解架构 | `设计文档.md` | 数据流、配置系统、查询/搜索/索引模块 |
-| 5. 接入搜索 API | `API_DOCUMENTATION.md` / `API_INTEGRATION_GUIDE.md` | REST 端点、参数、响应、最佳实践 |
-| 6. 查字段定义 | `INDEX_FIELDS_DOCUMENTATION.md` | `search_products` 映射、字段来源、类型与用途 |
+| 1. 准备环境 | `环境配置说明.md` / `Usage-Guide.md` | Conda/依赖、Elasticsearch、MySQL、必需变量 |
+| 2. 构造测试数据 | `测试数据指南.md` | Tenant1 Mock、Tenant2 CSV、`mock_data.sh` / `ingest.sh` |
+| 3. 启动与验证 | `Usage-Guide.md` | `run.sh` 一键启动、分步脚本、日志与健康检查 |
+| 4. 理解架构 | `系统设计文档.md` | 数据流、配置系统、查询/搜索/索引模块 |
+| 5. 接入搜索 API | `搜索API对接指南.md` / `搜索API速查表.md` | REST 端点、参数、响应、最佳实践 |
+| 6. 查字段定义 | `索引字段说明.md` | `search_products` 映射、字段来源、类型与用途 |
  
 > README 仅保留最常用命令的“索引”。细节以主题文档为准。
  
@@ -52,19 +52,21 @@ curl -X POST http://localhost:6002/search/ \
  
 | 文档 | 内容提要 | 适用场景 |
 |------|----------|----------|
-| `环境相关.md` | 系统要求、Conda/依赖、外部服务账号、常用端口 | 首次部署、环境核对 |
-| `USAGE_GUIDE.md` | 环境准备、服务启动、配置、日志、验证手册 | 日常运维、调试 |
-| `TEST_DATA_GUIDE.md` | 两个租户的模拟/CSV数据构造 & MySQL→ES流程 | 数据准备、联调 |
-| `设计文档.md` | 架构、配置系统、索引/查询/排序模块细节 | 研发/扩展功能 |
-| `INDEX_FIELDS_DOCUMENTATION.md` | `search_products` 字段、类型、来源、嵌套结构 | 新增字段、数据对齐 |
-| `API_DOCUMENTATION.md` | REST API（搜索/图片/管理）详解、示例、响应格式 | API 使用、测试 |
-| `API_INTEGRATION_GUIDE.md` | 客户对接指引、最佳实践、错误处理、语言说明 | 第三方集成、SDK 开发 |
-| `API_QUICK_REFERENCE.md` | 常用请求体速查表 | 支持团队快速查阅 |
-| `环境相关.md` + `.env` 模板 | 运行依赖账号、端口、密钥对照表 | 交付 & 运维 |
+| `环境配置说明.md` | 系统要求、Conda/依赖、外部服务账号、常用端口 | 首次部署、环境核对 |
+| `Usage-Guide.md` | 环境准备、服务启动、配置、日志、验证手册 | 日常运维、调试 |
+| `基础配置指南.md` | 租户字段、索引域、排序表达式配置流程 | 新租户开通、配置变更 |
+| `测试数据指南.md` | 两个租户的模拟/CSV 数据构造 & MySQL→ES 流程 | 数据准备、联调 |
+| `测试Pipeline说明.md` | 测试流水线、CI 脚本、上下文说明 | 自动化测试、追踪流水线 |
+| `系统设计文档.md` | 架构、配置系统、索引/查询/排序模块细节 | 研发/扩展功能 |
+| `索引字段说明.md` | `search_products` 字段、类型、来源、嵌套结构 | 新增字段、数据对齐 |
+| `搜索API对接指南.md` | REST API（文本/图片/管理）详解、示例、响应格式 | API 使用、测试 |
+| `搜索API速查表.md` | 常用请求体、过滤器、分面速查表 | 支持团队快速查阅 |
+| `Search-API-Examples.md` | Python/JS/cURL 端到端示例 | 客户工程、SDK 参考 |
+| `环境配置说明.md` + `.env` 模板 | 运行依赖账号、端口、密钥对照表 | 交付 & 运维 |
  
 更多补充材料：
  
-- `TEST_DATA_GUIDE.md`：包含完整工作流脚本示例
+- `测试数据指南.md`：包含完整工作流脚本示例
 - `商品数据源入ES配置规范.md`：数据源映射约定
 - `MULTILANG_FEATURE.md`：多语言处理细节
  
@@ -73,12 +75,12 @@ curl -X POST http://localhost:6002/search/ \
 - **数据构建 → MySQL → Elasticsearch**  
   - `scripts/mock_data.sh`：Tenant1 Mock + Tenant2 CSV 一条龙  
   - `scripts/ingest.sh <tenant_id> [recreate]`：驱动 `indexer/` 模块写入 `search_products`
-  - 详解：`TEST_DATA_GUIDE.md`
+  - 详解：`测试数据指南.md`
  
 - **搜索服务 & API**  
   - `api/`（FastAPI）承载 REST API，`search/` + `query/` 负责查询解析与下发  
-  - API、分页、过滤、Facet、KNN 等：`API_DOCUMENTATION.md`
-  - 对接案例与错误码：`API_INTEGRATION_GUIDE.md`
+  - API、分页、过滤、Facet、KNN 等：`搜索API对接指南.md`
+  - 对接案例、示例与错误码：`搜索API对接指南.md`、`Search-API-Examples.md`
  
 - **配置驱动能力**  
   - `config/schema/{tenant_id}/config.yaml`：字段定义、索引域、排序表达式、SPU 聚合  
@@ -96,16 +98,3 @@ scripts/        数据/服务脚本（mock_data, ingest, run 等）
 frontend/       简易调试页面
 docs/           运营及中文资料
 ```
-
-## 常用参考
-
-- **运行/排障**：`USAGE_GUIDE.md`、`环境相关.md`
-- **功能设计**：`设计文档.md`
-- **字段/数据对齐**：`INDEX_FIELDS_DOCUMENTATION.md`
-- **API 对接**：`API_DOCUMENTATION.md`、`API_INTEGRATION_GUIDE.md`
-- **测试数据**：`TEST_DATA_GUIDE.md`
-
-## 许可证
-
-专有软件 - 保留所有权利
-
@@ -1,374 +0,0 @@
-# RequestContext 使用指南
-
-## 概述
-
-`RequestContext` 是一个请求粒度的上下文管理器，用于跟踪和管理搜索请求的整个生命周期。它提供了统一的数据存储、性能监控和日志记录功能。
-
-## 核心功能
-
-### 1. 查询分析结果存储
-- 原始查询、规范化查询、重写查询
-- 检测语言和翻译结果
-- 查询向量（embedding）
-- 布尔查询AST
-
-### 2. 各检索阶段中间结果
-- 解析后的查询对象
-- 布尔查询语法树
-- ES查询DSL
-- ES响应数据
-- 处理后的搜索结果
-
-### 3. 性能监控
-- 自动计时各阶段耗时
-- 计算各阶段耗时占比
-- 识别性能瓶颈
-- 详细的性能摘要日志
-
-### 4. 错误处理和警告
-- 统一的错误信息存储
-- 警告信息收集
-- 完整的上下文错误跟踪
-
-## 支持的搜索阶段
-
-```python
-class RequestContextStage(Enum):
-    TOTAL = "total_search"                    # 总搜索时间
-    QUERY_PARSING = "query_parsing"          # 查询解析
-    BOOLEAN_PARSING = "boolean_parsing"      # 布尔查询解析
-    QUERY_BUILDING = "query_building"        # ES查询构建
-    ELASTICSEARCH_SEARCH = "elasticsearch_search"  # ES搜索
-    RESULT_PROCESSING = "result_processing"  # 结果处理
-    RERANKING = "reranking"                  # 重排序
-```
-
-## 基本使用方法
-
-### 1. 创建RequestContext
-
-```python
-from context import create_request_context, RequestContext
-
-# 方式1: 使用工厂函数
-context = create_request_context(reqid="req-001", uid="user-123")
-
-# 方式2: 直接创建
-context = RequestContext(reqid="req-001", uid="user-123")
-
-# 方式3: 作为上下文管理器使用
-with create_request_context("req-002", "user-456") as context:
-    # 搜索逻辑
-    pass  # 自动记录性能摘要
-```
-
-### 2. 阶段计时
-
-```python
-from context import RequestContextStage
-
-# 开始计时
-context.start_stage(RequestContextStage.QUERY_PARSING)
-
-# 执行查询解析逻辑
-# parsed_query = query_parser.parse(query, context=context)
-
-# 结束计时
-duration = context.end_stage(RequestContextStage.QUERY_PARSING)
-print(f"查询解析耗时: {duration:.2f}ms")
-```
-
-### 3. 存储查询分析结果
-
-```python
-context.store_query_analysis(
-    original_query="红色连衣裙",
-    normalized_query="红色 连衣裙",
-    rewritten_query="红色 女 连衣裙",
-    detected_language="zh",
-    translations={"en": "red dress"},
-    query_vector=[0.1, 0.2, 0.3, ...],  # 如果有向量
-    is_simple_query=True
-)
-```
-
-### 4. 存储中间结果
-
-```python
-# 存储解析后的查询对象
-context.store_intermediate_result('parsed_query', parsed_query)
-
-# 存储ES查询DSL
-context.store_intermediate_result('es_query', es_query_dict)
-
-# 存储ES响应
-context.store_intermediate_result('es_response', es_response)
-
-# 存储处理后的结果
-context.store_intermediate_result('processed_hits', hits)
-```
-
-### 5. 错误处理和警告
-
-```python
-try:
-    # 可能出错的操作
-    risky_operation()
-except Exception as e:
-    context.set_error(e)
-
-# 添加警告信息
-context.add_warning("查询结果较少，建议放宽搜索条件")
-
-# 检查是否有错误
-if context.has_error():
-    print(f"搜索出错: {context.metadata['error_info']}")
-```
-
-## 在Searcher中使用
-
-### 1. 自动创建Context（向后兼容）
-
-```python
-searcher = Searcher(config, es_client)
-
-# Searcher会自动创建RequestContext
-result = searcher.search(
-    query="无线蓝牙耳机",
-    size=10,
-    enable_embedding=True
-)
-
-# 结果中包含context信息
-print(result.context.get_summary())
-```
-
-### 2. 手动创建和传递Context
-
-```python
-# 创建自己的context
-context = create_request_context("my-req-001", "user-789")
-
-# 传递给searcher
-result = searcher.search(
-    query="运动鞋",
-    context=context  # 传递自定义context
-)
-
-# 使用context进行详细分析
-summary = context.get_summary()
-print(f"总耗时: {summary['performance']['total_duration_ms']:.1f}ms")
-```
-
-## 性能分析
-
-### 1. 获取性能摘要
-
-```python
-summary = context.get_summary()
-
-# 基本信息
-print(f"请求ID: {summary['request_info']['reqid']}")
-print(f"总耗时: {summary['performance']['total_duration_ms']:.1f}ms")
-
-# 各阶段耗时
-for stage, duration in summary['performance']['stage_timings_ms'].items():
-    percentage = summary['performance']['stage_percentages'].get(stage, 0)
-    print(f"{stage}: {duration:.1f}ms ({percentage:.1f}%)")
-
-# 查询分析信息
-query_info = summary['query_analysis']
-print(f"原查询: {query_info['original_query']}")
-print(f"重写查询: {query_info['rewritten_query']}")
-print(f"检测语言: {query_info['detected_language']}")
-```
-
-### 2. 识别性能瓶颈
-
-```python
-summary = context.get_summary()
-
-# 找出耗时超过20%的阶段
-bottlenecks = []
-for stage, percentage in summary['performance']['stage_percentages'].items():
-    if percentage > 20:
-        bottlenecks.append((stage, percentage))
-
-if bottlenecks:
-    print("性能瓶颈:")
-    for stage, percentage in bottlenecks:
-        print(f"  - {stage}: {percentage:.1f}%")
-```
-
-### 3. 自动性能日志
-
-RequestContext会在以下时机自动记录详细的性能摘要日志：
-
-- 上下文管理器退出时 (`with context:`)
-- 手动调用 `context.log_performance_summary()`
-- Searcher.search() 完成时
-
-日志格式示例：
-```
-[2024-01-01 10:30:45] [INFO] [request_context] 搜索请求性能摘要 | reqid: req-001 | 总耗时: 272.6ms | 阶段耗时: |   - query_parsing: 35.3ms (13.0%) |   - elasticsearch_search: 146.0ms (53.6%) |   - result_processing: 18.6ms (6.8%) | 查询: '红色连衣裙' -> '红色 女 连衣裙' (zh) | 结果: 156 hits ES查询: 2456 chars
-```
-
-## 线程安全
-
-RequestContext是线程安全的，支持并发请求处理。每个请求使用独立的context实例，互不干扰。
-
-```python
-import threading
-from context import create_request_context
-
-def worker(request_id, query):
-    context = create_request_context(request_id)
-    # 搜索逻辑
-    # context自动跟踪此线程的请求
-    pass
-
-# 多线程并发处理
-threads = []
-for i in range(5):
-    t = threading.Thread(target=worker, args=(f"req-{i}", f"query-{i}"))
-    threads.append(t)
-    t.start()
-
-for t in threads:
-    t.join()
-```
-
-## 调试支持
-
-### 1. 检查中间结果
-
-```python
-# 获取查询解析结果
-parsed_query = context.get_intermediate_result('parsed_query')
-
-# 获取ES查询DSL
-es_query = context.get_intermediate_result('es_query')
-
-# 获取ES响应
-es_response = context.get_intermediate_result('es_response')
-
-# 获取原始搜索结果
-raw_hits = context.get_intermediate_result('raw_hits')
-
-# 获取最终处理后的结果
-processed_hits = context.get_intermediate_result('processed_hits')
-```
-
-### 2. 错误诊断
-
-```python
-if context.has_error():
-    error_info = context.metadata['error_info']
-    print(f"错误类型: {error_info['type']}")
-    print(f"错误消息: {error_info['message']}")
-
-    # 检查是否有警告
-    if context.metadata['warnings']:
-        print("警告信息:")
-        for warning in context.metadata['warnings']:
-            print(f"  - {warning}")
-```
-
-## 最佳实践
-
-### 1. 统一使用Context
-
-```python
-# 推荐：在整个搜索流程中传递同一个context
-result = searcher.search(query, context=context)
-
-# 不推荐：在各个环节创建不同的context
-```
-
-### 2. 合理设置阶段边界
-
-```python
-# 只在有意义的大阶段之间计时
-context.start_stage(RequestContextStage.QUERY_PARSING)
-# 整个查询解析逻辑
-context.end_stage(RequestContextStage.QUERY_PARSING)
-
-# 避免在细粒度操作间频繁计时
-```
-
-### 3. 及时存储关键数据
-
-```python
-# 在每个阶段完成后及时存储结果
-context.store_intermediate_result('parsed_query', parsed_query)
-context.store_intermediate_result('es_query', es_query)
-
-# 便于后续调试和分析
-```
-
-### 4. 适当使用警告
-
-```python
-# 使用警告记录非致命问题
-if total_hits < 10:
-    context.add_warning("搜索结果较少，建议放宽搜索条件")
-
-if query_time > 5.0:
-    context.add_warning(f"查询耗时较长: {query_time:.1f}秒")
-```
-
-## 集成示例
-
-### API接口集成
-
-```python
-from flask import Flask, request, jsonify
-from context import create_request_context
-
-app = Flask(__name__)
-
-@app.route('/search')
-def api_search():
-    # 从请求中获取参数
-    query = request.args.get('q', '')
-    uid = request.args.get('uid', 'anonymous')
-
-    # 创建context
-    context = create_request_context(uid=uid)
-
-    try:
-        # 执行搜索
-        result = searcher.search(query, context=context)
-
-        # 返回结果（包含性能信息）
-        response = {
-            'results': result.to_dict(),
-            'performance': context.get_summary()['performance']
-        }
-
-        return jsonify(response)
-
-    except Exception as e:
-        context.set_error(e)
-        context.log_performance_summary()
-
-        return jsonify({
-            'error': str(e),
-            'request_id': context.reqid
-        }), 500
-```
-
-## 总结
-
-RequestContext提供了一个强大而灵活的框架，用于管理搜索请求的整个生命周期。通过统一的上下文管理、自动性能监控和详细的日志记录，它显著提升了搜索系统的可观测性和调试能力。
-
-主要优势：
-
-1. **统一管理**: 所有请求相关数据集中存储
-2. **自动监控**: 无需手动计时，自动跟踪性能
-3. **详细日志**: 完整的请求生命周期记录
-4. **向后兼容**: 现有代码无需修改即可受益
-5. **线程安全**: 支持高并发场景
-6. **易于调试**: 丰富的中间结果和错误信息
-
-通过合理使用RequestContext，可以构建更加可靠、高性能和易维护的搜索系统。
 \ No newline at end of file
@@ -761,6 +761,209 @@ result.results.forEach(product =&gt; {
  
 ---
  
+## 其他接口
+
+### 搜索建议（框架）
+
+- **端点**: `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、阶段耗时、打分细节）。
+
+---
+
 ## 附录
  
 ### 常用字段列表
@@ -789,3 +992,27 @@ result.results.forEach(product =&gt; {
 - `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` | 图片语义向量 |
+