分面接口修改：

{ "facets": [ { "field": "category1_name", "size": 15, "type": "terms" }, "specifications.color", "specifications.size" ] } { "facets": [ {"field": "category1_name", "size": 15, "type": "terms"}, {"field": "specifications.color", "size": 10, "type": "terms"}, {"field": "specifications.size", "size": 10, "type": "terms"} ] } 之前是上面的接口形式，主要是考虑属性的分面，因为款式都是有限的不需要设定 "size": 10, "type": "terms" 这些参数。但是从接口设计层面，最好按下面这样，这样的话 specifications.color 和 category1_name 的组装格式完全一样。前端不需要感知属性分面和类别等其他字段分面的差异。

分面接口修改：
{ "facets": [ { "field": "category1_name", "size": 15, "type": "terms" }, "specifications.color", "specifications.size" ] } { "facets": [ {"field": "category1_name", "size": 15, "type": "terms"}, {"field": "specifications.color", "size": 10, "type": "terms"}, {"field": "specifications.size", "size": 10, "type": "terms"} ] } 之前是上面的接口形式，主要是考虑属性的分面，因为款式都是有限的不需要设定 "size": 10, "type": "terms" 这些参数。但是从接口设计层面，最好按下面这样，这样的话 specifications.color 和 category1_name 的组装格式完全一样。前端不需要感知属性分面和类别等其他字段分面的差异。
tangwang
1 parent e7ad2b4a
Showing 10 changed files with 273 additions and 175 deletions Show diff stats
activate.sh
api/models.py
docs/搜索API对接指南.md
docs/系统设计文档.md
docs/索引字段说明v2.md
frontend/index.html
frontend/static/js/app.js
indexer/spu_transformer.py
search/es_query_builder.py
search/searcher.py
@@ -0,0 +1,12 @@
+#!/bin/bash
+source /home/tw/miniconda3/etc/profile.d/conda.sh
+conda activate searchengine
+
+# 如果需要加载 .env 中的环境变量
+if [ -f .env ]; then
+    set -a  # 自动导出所有变量
+    source <(grep -v '^#' .env | grep -v '^$' | sed 's/#.*$//' | sed 's/\r$//')
+    set +a  # 关闭自动导出
+fi
+
+echo "Environment activated: searchengine"
@@ -110,31 +110,34 @@ class SearchRequest(BaseModel):
     )
     # 排序
-    sort_by: Optional[str] = Field(None, description="排序字段名（如 'min_price', 'max_price', 'title'）")
-    sort_order: Optional[str] = Field("desc", description="排序方向: 'asc'（升序）或 'desc'（降序）")
+    sort_by: Optional[str] = Field(None, description="排序字段名。支持：'price'（价格，自动根据sort_order选择min_price或max_price）、'sales'（销量）、'create_time'（创建时间）、'update_time'（更新时间）")
+    sort_order: Optional[str] = Field("desc", description="排序方向: 'asc'（升序）或 'desc'（降序）。注意：price+asc=价格从低到高，price+desc=价格从高到低")
-    # 分面搜索 - 简化接口
-    facets: Optional[List[Union[str, FacetConfig]]] = Field(
+    # 分面搜索
+    facets: Optional[List[FacetConfig]] = Field(
         None,
-        description="分面配置。可以是字段名列表（使用默认配置）或详细的分面配置对象。支持 specifications 分面：\"specifications\"（所有name）或 \"specifications.color\"（指定name）",
+        description="分面配置对象列表。支持 specifications 分面：field=\"specifications\"（所有规格名称）或 field=\"specifications.color\"（指定规格名称）",
         json_schema_extra={
             "examples": [
-                # 简单模式：只指定字段名，使用默认配置
-                ["category1_name", "category2_name", "specifications"],
-                # 指定specifications的某个name
-                ["specifications.颜色", "specifications.尺寸"],
-                # 高级模式：详细配置
                 [
-                    {"field": "category1_name", "size": 15},
+                    {"field": "category1_name", "size": 15, "type": "terms"},
+                    {"field": "category2_name", "size": 10, "type": "terms"},
+                    {"field": "specifications.color", "size": 20, "type": "terms"},
+                    {"field": "specifications.size", "size": 15, "type": "terms"}
+                ],
+                [
+                    {"field": "category1_name", "size": 15, "type": "terms"},
                     {
                         "field": "min_price",
                         "type": "range",
                         "ranges": [
                             {"key": "0-50", "to": 50},
-                            {"key": "50-100", "from": 50, "to": 100}
+                            {"key": "50-100", "from": 50, "to": 100},
+                            {"key": "100-200", "from": 100, "to": 200},
+                            {"key": "200+", "from": 200}
                         ]
                     },
-                    "specifications"  # 所有specifications name的分面
+                    {"field": "specifications", "size": 10, "type": "terms"}
                 ]
             ]
         }
@@ -50,7 +50,7 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
       "gte": "2020-01-01T00:00:00Z" 
     }
   },
-    "sort_by": "min_price",
+    "sort_by": "price",
     "sort_order": "asc"
   }'
 ```
@@ -63,7 +63,11 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   -H "X-Tenant-ID: 162" \
   -d '{
     "query": "芭比娃娃",
-    "facets": ["category1_name", "specifications.color", "specifications.size", "specifications.material"],
+    "facets": [
+      {"field": "category1_name", "size": 10, "type": "terms"},
+      {"field": "specifications.color", "size": 10, "type": "terms"},
+      {"field": "specifications.size", "size": 10, "type": "terms"}
+    ],
     "min_score": 0.2
   }'
 ```
@@ -124,8 +128,8 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 | `filters` | object | N | null | 精确匹配过滤器（见下文） |
 | `range_filters` | object | N | null | 数值范围过滤器（见下文） |
 | `facets` | array | N | null | 分面配置（见下文） |
-| `sort_by` | string | N | null | 排序字段名（如 `min_price`, `max_price`） |
-| `sort_order` | string | N | "desc" | 排序方向：`asc`（升序）或 `desc`（降序） |
+| `sort_by` | string | N | null | 排序字段名。支持：`price`（价格）、`sales`（销量）、`create_time`（创建时间）、`update_time`（更新时间）。默认按相关性排序 |
+| `sort_order` | string | N | "desc" | 排序方向：`asc`（升序）或 `desc`（降序）。注意：`price`+`asc`=价格从低到高，`price`+`desc`=价格从高到低（后端自动映射为min_price或max_price） |
 | `min_score` | float | N | null | 最小相关性分数阈值 |
 | `sku_filter_dimension` | array[string] | N | null | 子SKU筛选维度列表（店铺配置）。指定后，每个SPU下的SKU将按这些维度的组合进行分组，每个组合只返回第一个SKU。支持的值：`option1`、`option2`、`option3` 或选项名称（如 `color`、`size`）。详见下文说明 |
 | `debug` | boolean | N | false | 是否返回调试信息 |
@@ -263,14 +267,8 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 用于生成分面统计（分组聚合），常用于构建筛选器UI。
-**简单模式**（字符串数组）:
-```json
-{
-  "facets": ["category1_name", "category2_name", "category3_name", "specifications"]
-}
-```
+**配置格式**（对象数组）:
-**高级模式**（配置对象数组）:
 ```json
 {
   "facets": [
@@ -280,6 +278,16 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
       "type": "terms"
     },
     {
+      "field": "category2_name",
+      "size": 10,
+      "type": "terms"
+    },
+    {
+      "field": "specifications.color",
+      "size": 20,
+      "type": "terms"
+    },
+    {
       "field": "min_price",
       "type": "range",
       "ranges": [
@@ -288,8 +296,7 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
         {"key": "100-200", "from": 100, "to": 200},
         {"key": "200+", "from": 200}
       ]
-    },
-    "specifications"  // 规格分面（特殊处理：嵌套聚合，按name分组，然后按value聚合）
+    }
   ]
 }
 ```
@@ -298,18 +305,35 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 `specifications` 是嵌套字段，支持两种分面模式：
-**模式1：所有规格名称的分面** (`"specifications"`):
+**模式1：所有规格名称的分面**:
 ```json
 {
-  "facets": ["specifications"]
+  "facets": [
+    {
+      "field": "specifications",
+      "size": 10,
+      "type": "terms"
+    }
+  ]
 }
 ```
 返回所有规格名称（name）及其对应的值（value）列表。每个 name 会生成一个独立的分面结果。
-**模式2：指定规格名称的分面** (`"specifications.color"`):
+**模式2：指定规格名称的分面**:
 ```json
 {
-  "facets": ["specifications.color", "specifications.size", "specifications.material"]
+  "facets": [
+    {
+      "field": "specifications.color",
+      "size": 20,
+      "type": "terms"
+    },
+    {
+      "field": "specifications.size",
+      "size": 15,
+      "type": "terms"
+    }
+  ]
 }
 ```
 只返回指定规格名称的值列表。格式：`specifications.{name}`，其中 `{name}` 是规格名称（如"color"、"size"、"material"）。
@@ -564,6 +588,7 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 | `sku_weights` | array[integer] | 所有SKU重量列表 |
 | `sku_weight_units` | array[string] | 所有SKU重量单位列表 |
 | `total_inventory` | integer | 总库存 |
+| `sales` | integer | 销量（展示销量） |
 | `option1_name` | string | 选项1名称（如"color"） |
 | `option2_name` | string | 选项2名称（如"size"） |
 | `option3_name` | string | 选项3名称 |
@@ -605,11 +630,45 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   "query": "玩具",
   "size": 20,
   "from": 0,
-  "sort_by": "min_price",
+  "sort_by": "price",
   "sort_order": "asc"
 }
 ```
+**需求**: 搜索"玩具"，按价格从高到低排序
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0,
+  "sort_by": "price",
+  "sort_order": "desc"
+}
+```
+
+**需求**: 搜索"玩具"，按销量从高到低排序
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0,
+  "sort_by": "sales",
+  "sort_order": "desc"
+}
+```
+
+**需求**: 搜索"玩具"，按默认（相关性）排序
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0
+}
+```
+
 ### 场景2：SKU筛选（按维度过滤）
 **需求**: 搜索"芭比娃娃"，每个SPU下按颜色筛选，每种颜色只显示一个SKU
@@ -650,7 +709,7 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 ### 场景4：带分面的商品搜索
-**需求**: 搜索"玩具"，获取类目和品牌的分面统计，用于构建筛选器
+**需求**: 搜索"玩具"，获取类目和规格的分面统计，用于构建筛选器
 ```json
 {
@@ -658,9 +717,9 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   "size": 20,
   "language": "zh",
   "facets": [
-    "category1_name",
-    "category2_name",
-    "specifications"
+    {"field": "category1_name", "size": 15, "type": "terms"},
+    {"field": "category2_name", "size": 10, "type": "terms"},
+    {"field": "specifications", "size": 10, "type": "terms"}
   ]
 }
 ```
@@ -686,7 +745,8 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   "facets": [
     {
       "field": "category1_name",
-      "size": 15
+      "size": 15,
+      "type": "terms"
     },
     {
       "field": "min_price",
@@ -698,7 +758,11 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
         {"key": "200+", "from": 200}
       ]
     },
-    "specifications"
+    {
+      "field": "specifications",
+      "size": 10,
+      "type": "terms"
+    }
   ],
   "sort_by": "min_price",
   "sort_order": "asc"
@@ -768,18 +832,23 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   "query": "手机",
   "size": 20,
   "language": "zh",
-  "facets": ["specifications"]
+  "facets": [
+    {"field": "specifications", "size": 10, "type": "terms"}
+  ]
 }
 ```
-**需求**: 只获取"color"规格的分面统计
+**需求**: 只获取"color"和"size"规格的分面统计
 ```json
 {
   "query": "手机",
   "size": 20,
   "language": "zh",
-  "facets": ["specifications.color", "specifications.size"]
+  "facets": [
+    {"field": "specifications.color", "size": 20, "type": "terms"},
+    {"field": "specifications.size", "size": 15, "type": "terms"}
+  ]
 }
 ```
@@ -800,10 +869,10 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
     }
   },
   "facets": [
-    "category1_name",
-    "category2_name",
-    "specifications.color",
-    "specifications.size"
+    {"field": "category1_name", "size": 15, "type": "terms"},
+    {"field": "category2_name", "size": 10, "type": "terms"},
+    {"field": "specifications.color", "size": 20, "type": "terms"},
+    {"field": "specifications.size", "size": 15, "type": "terms"}
   ]
 }
 ```
@@ -1006,6 +1075,7 @@ curl &quot;http://localhost:6002/search/12345&quot;
 | `sku_weights` | long | SKU重量列表（数组） |
 | `sku_weight_units` | keyword | SKU重量单位列表（数组） |
 | `total_inventory` | long | 总库存 |
+| `sales` | long | 销量（展示销量） |
 | `skus` | nested | SKU详细信息（嵌套对象数组） |
 | `create_time`, `update_time` | date | 创建/更新时间 |
 | `title_embedding` | dense_vector | 标题向量（1024维，仅用于搜索） |
@@ -1038,11 +1108,15 @@ curl &quot;http://localhost:6002/search/12345&quot;
 #### 排序字段
-- `min_price`: 最低价格
-- `max_price`: 最高价格
+- `price`: 价格（后端自动根据sort_order映射：asc→min_price，desc→max_price）
+- `sales`: 销量
 - `create_time`: 创建时间
 - `update_time`: 更新时间
-- `relevance_score`: 相关性分数（默认）
+- `relevance_score`: 相关性分数（默认，不指定sort_by时使用）
+
+**注意**: 前端只需传 `price`，后端会自动处理：
+- `sort_by: "price"` + `sort_order: "asc"` → 按 `min_price` 升序（价格从低到高）
+- `sort_by: "price"` + `sort_order: "desc"` → 按 `max_price` 降序（价格从高到低）
 ### 支持的分析器
@@ -699,45 +699,44 @@ Elasticsearch
 #### 8.3.2 Facets 配置数据流
-**输入格式**：`List[Union[str, FacetConfig]]`
+**输入格式**：`List[FacetConfig]`
-- **简单模式**：字符串列表（字段名），使用默认配置
-  ```json
-  ["category1_name", "category2_name", "specifications"]
-  ```
-
-- **Specifications分面**：
-  - 所有规格名称：`"specifications"` - 返回所有name及其value列表
-  - 指定规格名称：`"specifications.color"` - 只返回指定name的value列表
+**配置对象列表**：所有分面配置必须使用 FacetConfig 对象
+```json
+[
+  {
+    "field": "category1_name",
+    "size": 15,
+    "type": "terms"
+  },
+  {
+    "field": "specifications.color",
+    "size": 20,
+    "type": "terms"
+  },
+  {
+    "field": "min_price",
+    "type": "range",
+    "ranges": [
+      {"key": "0-50", "to": 50},
+      {"key": "50-100", "from": 50, "to": 100}
+    ]
+  }
+]
+```
-- **高级模式**：FacetConfig 对象列表，支持自定义配置
-  ```json
-  [
-    {
-      "field": "category1_name",
-      "size": 15,
-      "type": "terms"
-    },
-    {
-      "field": "min_price",
-      "type": "range",
-      "ranges": [
-        {"key": "0-50", "to": 50},
-        {"key": "50-100", "from": 50, "to": 100}
-      ]
-    },
-    "specifications.color"  // 指定规格名称的分面
-  ]
-  ```
+**Specifications 分面支持**：
+- 所有规格名称：`field: "specifications"` - 返回所有 name 及其 value 列表
+- 指定规格名称：`field: "specifications.color"` - 只返回指定 name 的 value 列表
 **数据流**：
-1. API 层：接收 `List[Union[str, FacetConfig]]`
-2. Searcher 层：透传，不做转换
-3. ES Query Builder：只接受 `str` 或 `FacetConfig`，自动处理两种格式
+1. API 层：接收 `List[FacetConfig]`，Pydantic 验证参数
+2. Searcher 层：透传 FacetConfig 对象列表
+3. ES Query Builder：解析 FacetConfig 对象
    - 检测 `"specifications"` 或 `"specifications.{name}"` 格式
-   - 构建对应的嵌套聚合查询
-4. 输出：转换为 ES 聚合查询（包括specifications嵌套聚合）
-5. Result Formatter：格式化ES聚合结果，处理specifications嵌套结构
+   - 构建对应的嵌套聚合查询或普通聚合查询
+4. 输出：转换为 ES 聚合查询（包括 specifications 嵌套聚合）
+5. Result Formatter：格式化 ES 聚合结果，处理 specifications 嵌套结构
 #### 8.3.3 Range Filters 数据流
@@ -284,11 +284,12 @@
 | `sku_weights` | long | 所有 SKU 重量列表（数组） | 从所有 SKU 重量汇总 |
 | `sku_weight_units` | keyword | 所有 SKU 重量单位列表（数组） | 从所有 SKU 重量单位汇总 |
-### 9. 库存字段
+### 9. 库存与销量字段
 | 字段名 | ES类型 | 说明 | 数据来源 |
 |--------|--------|------|----------|
 | `total_inventory` | long | 总库存（所有 SKU 库存之和） | 从所有 SKU 库存汇总 |
+| `sales` | long | 销量（展示销量） | MySQL: `shoplazza_product_spu.fake_sales` |
 ### 10. SKU 嵌套字段
@@ -363,6 +364,16 @@
 - `vendor_zh.keyword`, `vendor_en.keyword`
 - `specifications` (嵌套查询)
 - `min_price`, `max_price` (范围过滤)
+- `sales` (范围过滤)
+- `total_inventory` (范围过滤)
+
+### 排序字段
+
+- `price`: 价格（前端传入，后端自动映射：asc→min_price，desc→max_price）
+- `sales`: 销量
+- `create_time`: 创建时间
+- `update_time`: 更新时间
+- `relevance_score`: 相关性分数（默认）
 ### 分面字段（聚合统计）
@@ -94,11 +94,18 @@
                     <span class="arrow-down" data-field="create_time" data-order="asc" onclick="sortByField('create_time', 'asc')">▼</span>
                 </span>
             </button>
-            <button class="sort-btn" data-sort="min_price">
+            <button class="sort-btn" data-sort="price">
                 By Price
                 <span class="sort-arrows">
-                    <span class="arrow-up" data-field="min_price" data-order="asc" onclick="sortByField('min_price', 'asc')">▲</span>
-                    <span class="arrow-down" data-field="min_price" data-order="desc" onclick="sortByField('min_price', 'desc')">▼</span>
+                    <span class="arrow-up" data-field="price" data-order="asc" onclick="sortByField('price', 'asc')">▲</span>
+                    <span class="arrow-down" data-field="price" data-order="desc" onclick="sortByField('price', 'desc')">▼</span>
+                </span>
+            </button>
+            <button class="sort-btn" data-sort="sales">
+                By Sales
+                <span class="sort-arrows">
+                    <span class="arrow-up" data-field="sales" data-order="desc" onclick="sortByField('sales', 'desc')">▲</span>
+                    <span class="arrow-down" data-field="sales" data-order="asc" onclick="sortByField('sales', 'asc')">▼</span>
                 </span>
             </button>
@@ -135,6 +142,6 @@
         <p>SearchEngine © 2025 | API: <span id="apiUrl">Loading...</span></p>
     </footer>
-    <script src="/static/js/app.js?v=3.4"></script>
+    <script src="/static/js/app.js?v=3.7"></script>
 </body>
 </html>
@@ -86,10 +86,10 @@ async function performSearch(page = 1) {
     // Define facets (一级分类 + 三个属性分面)
     const facets = [
-        "category1_name",  // 一级分类
-        "specifications.color",  // 颜色属性
-        "specifications.size",   // 尺寸属性
-        "specifications.material" // 材质属性
+        { field: "category1_name", size: 15, type: "terms" },  // 一级分类
+        { field: "specifications.color", size: 20, type: "terms" },  // 颜色属性
+        { field: "specifications.size", size: 15, type: "terms" },   // 尺寸属性
+        { field: "specifications.material", size: 10, type: "terms" } // 材质属性
     ];
     // Show loading
@@ -98,6 +98,7 @@ class SPUTransformer:
                 image_src, image_width, image_height, image_path, image_alt,
                 tags, note, category, category_id, category_google_id,
                 category_level, category_path,
+                fake_sales, display_fake_sales,
                 tenant_id, creator, create_time, updater, update_time, deleted
             FROM shoplazza_product_spu
             WHERE tenant_id = :tenant_id AND deleted = 0
@@ -447,6 +448,15 @@ class SPUTransformer:
                 image_src = f"//{image_src}" if image_src.startswith('//') else image_src
             doc['image_url'] = image_src
+        # Sales (fake_sales)
+        if pd.notna(spu_row.get('fake_sales')):
+            try:
+                doc['sales'] = int(spu_row['fake_sales'])
+            except (ValueError, TypeError):
+                doc['sales'] = 0
+        else:
+            doc['sales'] = 0
+
         # Process SKUs and build specifications
         skus_list = []
         prices = []
@@ -519,7 +519,7 @@ class ESQueryBuilder:
         Args:
             es_query: Existing ES query
-            sort_by: Field name for sorting
+            sort_by: Field name for sorting (支持 'price' 自动映射)
             sort_order: Sort order: 'asc' or 'desc'
         Returns:
@@ -531,6 +531,13 @@ class ESQueryBuilder:
         if not sort_order:
             sort_order = "desc"
+        # Auto-map 'price' to 'min_price' or 'max_price' based on sort_order
+        if sort_by == "price":
+            if sort_order.lower() == "asc":
+                sort_by = "min_price"  # 价格从低到高
+            else:
+                sort_by = "max_price"  # 价格从高到低
+
         if "sort" not in es_query:
             es_query["sort"] = []
@@ -546,20 +553,18 @@ class ESQueryBuilder:
     def build_facets(
         self,
-        facet_configs: Optional[List[Union[str, 'FacetConfig']]] = None
+        facet_configs: Optional[List['FacetConfig']] = None
     ) -> Dict[str, Any]:
         """
         构建分面聚合。
-        支持：
-        1. 分类分面：category1_name, category2_name, category3_name, category_name
-        2. specifications分面：嵌套聚合，按name聚合，然后按value聚合
-        
         Args:
-            facet_configs: 分面配置列表（标准格式）：
-                - str: 字段名，使用默认 terms 配置
-                - FacetConfig: 详细的分面配置对象
-                - 特殊值 "specifications": 构建specifications嵌套分面
+            facet_configs: 分面配置对象列表
+            
+            支持的字段类型：
+                - 普通字段: 如 "category1_name"（terms 或 range 类型）
+                - specifications: "specifications"（返回所有规格名称及其值）
+                - specifications.{name}: 如 "specifications.color"（返回指定规格名称的值）
         Returns:
             ES aggregations 字典
@@ -570,99 +575,76 @@ class ESQueryBuilder:
         aggs = {}
         for config in facet_configs:
-            # 特殊处理：specifications嵌套分面
-            if isinstance(config, str):
-                # 格式1: "specifications" - 返回所有name的分面
-                if config == "specifications":
-                    aggs["specifications_facet"] = {
-                        "nested": {
-                            "path": "specifications"
-                        },
-                        "aggs": {
-                            "by_name": {
-                                "terms": {
-                                    "field": "specifications.name",
-                                    "size": 20,
-                                    "order": {"_count": "desc"}
-                                },
-                                "aggs": {
-                                    "value_counts": {
-                                        "terms": {
-                                            "field": "specifications.value",
-                                            "size": 10,
-                                            "order": {"_count": "desc"}
-                                        }
+            field = config.field
+            size = config.size
+            facet_type = config.type
+            
+            # 处理 specifications（所有规格名称）
+            if field == "specifications":
+                aggs["specifications_facet"] = {
+                    "nested": {"path": "specifications"},
+                    "aggs": {
+                        "by_name": {
+                            "terms": {
+                                "field": "specifications.name",
+                                "size": 20,
+                                "order": {"_count": "desc"}
+                            },
+                            "aggs": {
+                                "value_counts": {
+                                    "terms": {
+                                        "field": "specifications.value",
+                                        "size": size,
+                                        "order": {"_count": "desc"}
                                     }
                                 }
                             }
                         }
                     }
-                    continue
-                
-                # 格式2: "specifications.color" 或 "specifications.颜色" - 只返回指定name的value列表
-                if config.startswith("specifications."):
-                    name = config[len("specifications."):]
-                    agg_name = f"specifications_{name}_facet"
-                    aggs[agg_name] = {
-                        "nested": {
-                            "path": "specifications"
-                        },
-                        "aggs": {
-                            "filter_by_name": {
-                                "filter": {
-                                    "term": {"specifications.name": name}
-                                },
-                                "aggs": {
-                                    "value_counts": {
-                                        "terms": {
-                                            "field": "specifications.value",
-                                            "size": 10,
-                                            "order": {"_count": "desc"}
-                                        }
+                }
+                continue
+            
+            # 处理 specifications.{name}（指定规格名称）
+            if field.startswith("specifications."):
+                name = field[len("specifications."):]
+                agg_name = f"specifications_{name}_facet"
+                aggs[agg_name] = {
+                    "nested": {"path": "specifications"},
+                    "aggs": {
+                        "filter_by_name": {
+                            "filter": {"term": {"specifications.name": name}},
+                            "aggs": {
+                                "value_counts": {
+                                    "terms": {
+                                        "field": "specifications.value",
+                                        "size": size,
+                                        "order": {"_count": "desc"}
                                     }
                                 }
                             }
                         }
                     }
-                    continue
+                }
+                continue
+            
+            # 处理普通字段
+            agg_name = f"{field}_facet"
-            # 简单模式：只有字段名（字符串，非specifications）
-            if isinstance(config, str):
-                field = config
-                agg_name = f"{field}_facet"
+            if facet_type == 'terms':
                 aggs[agg_name] = {
                     "terms": {
                         "field": field,
-                        "size": 10,
+                        "size": size,
                         "order": {"_count": "desc"}
                     }
                 }
-                continue
-            
-            # 高级模式：FacetConfig 对象
-            else:
-                # 此时 config 应该是 FacetConfig 对象
-                field = config.field
-                facet_type = config.type
-                size = config.size
-                agg_name = f"{field}_facet"
-                
-                if facet_type == 'terms':
+            elif facet_type == 'range':
+                if config.ranges:
                     aggs[agg_name] = {
-                        "terms": {
+                        "range": {
                             "field": field,
-                            "size": size,
-                            "order": {"_count": "desc"}
+                            "ranges": config.ranges
                         }
                     }
-                
-                elif facet_type == 'range':
-                    if config.ranges:
-                        aggs[agg_name] = {
-                            "range": {
-                                "field": field,
-                                "ranges": config.ranges
-                            }
-                        }
         return aggs
@@ -17,7 +17,7 @@ from .rerank_engine import RerankEngine
 from config import SearchConfig
 from config.utils import get_match_fields_for_index
 from context.request_context import RequestContext, RequestContextStage, create_request_context
-from api.models import FacetResult, FacetValue
+from api.models import FacetResult, FacetValue, FacetConfig
 from api.result_formatter import ResultFormatter
 logger = logging.getLogger(__name__)
@@ -123,7 +123,7 @@ class Searcher:
         from_: int = 0,
         filters: Optional[Dict[str, Any]] = None,
         range_filters: Optional[Dict[str, Any]] = None,
-        facets: Optional[List[Any]] = None,
+        facets: Optional[List[FacetConfig]] = None,
         min_score: Optional[float] = None,
         context: Optional[RequestContext] = None,
         sort_by: Optional[str] = None,