feat: 实现 Multi-Select Faceting 和 Selected 状态标记

核心功能： - 添加 multi_select 字段到 FacetConfig（默认为 true） - 实现 post_filter 支持 disjunctive faceting - 后端自动标记 facet 值的 selected 状态 - 支持 specifications 和普通字段的 multi-select 技术改进： - ESQueryBuilder: 分离 conjunctive/disjunctive filters - ResultFormatter: 根据 current_filters 标记 selected - Searcher: 传递 facet_configs 给 query builder 文档更新： - 添加 multi_select_faceting.md 详细文档 - 更新 API 对接指南，说明新功能 - 添加测试脚本 test_multi_select_facet.py 业界标准： - 遵循 Elasticsearch/Algolia/Amazon 的最佳实践 - 提供探索式搜索体验 - 前后端职责清晰分离

feat: 实现 Multi-Select Faceting 和 Selected 状态标记
核心功能： - 添加 multi_select 字段到 FacetConfig（默认为 true） - 实现 post_filter 支持 disjunctive faceting - 后端自动标记 facet 值的 selected 状态 - 支持 specifications 和普通字段的 multi-select 技术改进： - ESQueryBuilder: 分离 conjunctive/disjunctive filters - ResultFormatter: 根据 current_filters 标记 selected - Searcher: 传递 facet_configs 给 query builder 文档更新： - 添加 multi_select_faceting.md 详细文档 - 更新 API 对接指南，说明新功能 - 添加测试脚本 test_multi_select_facet.py 业界标准： - 遵循 Elasticsearch/Algolia/Amazon 的最佳实践 - 提供探索式搜索体验 - 前后端职责清晰分离
tangwang
1 parent b8317ce4
Showing 7 changed files with 884 additions and 24 deletions Show diff stats
api/models.py
api/result_formatter.py
docs/multi_select_faceting.md
docs/搜索API对接指南.md
search/es_query_builder.py
search/searcher.py
test_multi_select_facet.py
@@ -34,6 +34,10 @@ class FacetConfig(BaseModel):
     field: str = Field(..., description="分面字段名")
     size: int = Field(10, ge=1, le=100, description="返回的分面值数量")
     type: Literal["terms", "range"] = Field("terms", description="分面类型")
+    multi_select: bool = Field(
+        True,
+        description="是否支持多选（disjunctive faceting）。启用后，选中该分面的过滤器时，仍会显示其他可选项"
+    )
     ranges: Optional[List[Dict[str, Any]]] = Field(
         None,
         description="范围分面的范围定义（仅当 type='range' 时需要）"
@@ -220,24 +220,40 @@ class ResultFormatter:
     @staticmethod
     def format_facets(
         es_aggregations: Dict[str, Any],
-        facet_configs: Optional[List[Any]] = None
+        facet_configs: Optional[List[Any]] = None,
+        current_filters: Optional[Dict[str, Any]] = None
     ) -> List[FacetResult]:
         """
-        Format ES aggregations to FacetResult list.
+        Format ES aggregations to FacetResult list with selected state.
  
         支持：
         1. 普通terms聚合
         2. range聚合
         3. specifications嵌套聚合（按name分组，然后按value聚合）
+        4. 标记selected状态（基于current_filters）
  
         Args:
             es_aggregations: ES aggregations response
             facet_configs: Facet configurations (optional)
+            current_filters: Current applied filters (used to mark selected values)
  
         Returns:
-            List of FacetResult objects
+            List of FacetResult objects with selected states
         """
         facets = []
+        
+        # Build a set of selected values for specifications
+        selected_specs = set()
+        if current_filters and 'specifications' in current_filters:
+            specs = current_filters['specifications']
+            if isinstance(specs, list):
+                # [{"name": "颜色", "value": "白色"}, ...]
+                for spec in specs:
+                    if isinstance(spec, dict):
+                        selected_specs.add((spec.get('name'), spec.get('value')))
+            elif isinstance(specs, dict):
+                # {"name": "颜色", "value": "白色"}
+                selected_specs.add((specs.get('name'), specs.get('value')))
  
         for field_name, agg_data in es_aggregations.items():
             display_field = field_name[:-6] if field_name.endswith("_facet") else field_name
@@ -254,11 +270,13 @@ class ResultFormatter:
                         values = []
                         if 'buckets' in value_counts:
                             for value_bucket in value_counts['buckets']:
+                                # Check if this spec value is selected
+                                is_selected = (name, value_bucket['key']) in selected_specs
                                 value = FacetValue(
                                     value=value_bucket['key'],
                                     label=str(value_bucket['key']),
                                     count=value_bucket['doc_count'],
-                                    selected=False
+                                    selected=is_selected
                                 )
                                 values.append(value)
  
@@ -288,11 +306,13 @@ class ResultFormatter:
                     values = []
                     if 'buckets' in value_counts and value_counts['buckets']:
                         for value_bucket in value_counts['buckets']:
+                            # Check if this spec value is selected
+                            is_selected = (name, value_bucket['key']) in selected_specs
                             value = FacetValue(
                                 value=value_bucket['key'],
                                 label=str(value_bucket['key']),
                                 count=value_bucket['doc_count'],
-                                selected=False
+                                selected=is_selected
                             )
                             values.append(value)
  
@@ -311,11 +331,20 @@ class ResultFormatter:
             if 'buckets' in agg_data:
                 values = []
                 for bucket in agg_data['buckets']:
+                    # Check if this value is selected in current filters
+                    is_selected = False
+                    if current_filters and display_field in current_filters:
+                        filter_value = current_filters[display_field]
+                        if isinstance(filter_value, list):
+                            is_selected = bucket['key'] in filter_value
+                        else:
+                            is_selected = bucket['key'] == filter_value
+                    
                     value = FacetValue(
                         value=bucket['key'],
                         label=bucket.get('key_as_string', str(bucket['key'])),
                         count=bucket['doc_count'],
-                        selected=False
+                        selected=is_selected
                     )
                     values.append(value)
  
@@ -333,11 +362,20 @@ class ResultFormatter:
                 values = []
                 for bucket in agg_data['buckets']:
                     range_key = bucket.get('key', '')
+                    # Check if this range is selected
+                    is_selected = False
+                    if current_filters and display_field in current_filters:
+                        filter_value = current_filters[display_field]
+                        if isinstance(filter_value, list):
+                            is_selected = range_key in filter_value
+                        else:
+                            is_selected = range_key == filter_value
+                    
                     value = FacetValue(
                         value=range_key,
                         label=range_key,
                         count=bucket['doc_count'],
-                        selected=False
+                        selected=is_selected
                     )
                     values.append(value)
  
@@ -0,0 +1,399 @@
+# Multi-Select Faceting 功能说明
+
+## 概述
+
+Multi-Select Faceting（多选分面）是业界标准的 Faceted Search 功能，允许用户在选中某个分面筛选项后，仍然能看到该分面的其他可选项，提供更好的探索式搜索体验。
+
+## 功能特性
+
+### 1. 两种 Faceting 模式
+
+#### 标准模式（Conjunctive Faceting）
+- **设置**: `multi_select: false`（默认）
+- **行为**: 选中某个分面值后，该分面只显示选中的值
+- **适用场景**: 层级下钻、逐步精炼
+- **ES 实现**: 过滤器应用在 `query.bool.filter`
+
+#### Multi-Select 模式（Disjunctive Faceting）
+- **设置**: `multi_select: true`
+- **行为**: 选中某个分面值后，该分面仍显示所有可选项
+- **适用场景**: 颜色、品牌、尺码等可切换属性
+- **ES 实现**: 过滤器应用在 `post_filter`
+
+### 2. Selected 状态标记
+
+所有 facet 值都包含 `selected` 字段，标记当前是否被选中：
+- `selected: true` - 当前筛选项已被选中
+- `selected: false` - 当前筛选项未被选中
+
+## 使用示例
+
+### 示例 1: 标准 Category Faceting
+
+```json
+{
+  "query": "T恤",
+  "filters": {
+    "category1_name": "服装"
+  },
+  "facets": [
+    {
+      "field": "category1_name",
+      "size": 10,
+      "type": "terms",
+      "multi_select": false
+    }
+  ]
+}
+```
+
+**响应**:
+```json
+{
+  "results": [...],
+  "facets": [
+    {
+      "field": "category1_name",
+      "values": [
+        {"value": "服装", "count": 150, "selected": true}
+      ]
+    }
+  ]
+}
+```
+
+### 示例 2: Multi-Select Brand Faceting
+
+```json
+{
+  "query": "手机",
+  "filters": {
+    "brand_name": "苹果"
+  },
+  "facets": [
+    {
+      "field": "brand_name",
+      "size": 10,
+      "type": "terms",
+      "multi_select": true
+    }
+  ]
+}
+```
+
+**响应**:
+```json
+{
+  "results": [...只包含苹果手机...],
+  "facets": [
+    {
+      "field": "brand_name",
+      "values": [
+        {"value": "苹果", "count": 150, "selected": true},
+        {"value": "华为", "count": 120, "selected": false},
+        {"value": "小米", "count": 98, "selected": false}
+      ]
+    }
+  ]
+}
+```
+
+### 示例 3: Specifications Multi-Select
+
+```json
+{
+  "query": "衬衫",
+  "filters": {
+    "specifications": {
+      "name": "颜色",
+      "value": "白色"
+    }
+  },
+  "facets": [
+    {
+      "field": "specifications.颜色",
+      "size": 10,
+      "type": "terms",
+      "multi_select": true
+    },
+    {
+      "field": "specifications.尺码",
+      "size": 10,
+      "type": "terms",
+      "multi_select": false
+    }
+  ]
+}
+```
+
+**响应**:
+```json
+{
+  "results": [...只包含白色衬衫...],
+  "facets": [
+    {
+      "field": "specifications.颜色",
+      "label": "颜色",
+      "values": [
+        {"value": "白色", "count": 50, "selected": true},
+        {"value": "蓝色", "count": 35, "selected": false},
+        {"value": "黑色", "count": 28, "selected": false}
+      ]
+    },
+    {
+      "field": "specifications.尺码",
+      "label": "尺码",
+      "values": [
+        {"value": "M", "count": 20, "selected": false},
+        {"value": "L", "count": 18, "selected": false},
+        {"value": "XL", "count": 12, "selected": false}
+      ]
+    }
+  ]
+}
+```
+
+注意：尺码分面（`multi_select: false`）的统计是基于白色衬衫的。
+
+### 示例 4: 混合多个 Multi-Select Facets
+
+```json
+{
+  "query": "*",
+  "filters": {
+    "category1_name": "玩具",
+    "specifications": [
+      {"name": "颜色", "value": "红色"},
+      {"name": "材质", "value": "塑料"}
+    ]
+  },
+  "facets": [
+    {
+      "field": "category1_name",
+      "size": 10,
+      "multi_select": true
+    },
+    {
+      "field": "specifications.颜色",
+      "size": 10,
+      "multi_select": true
+    },
+    {
+      "field": "specifications.材质",
+      "size": 10,
+      "multi_select": true
+    },
+    {
+      "field": "specifications.年龄段",
+      "size": 10,
+      "multi_select": false
+    }
+  ]
+}
+```
+
+**行为说明**:
+- `category1_name`: 显示所有类目选项（玩具被标记为 selected）
+- `specifications.颜色`: 显示所有颜色选项（红色被标记为 selected）
+- `specifications.材质`: 显示所有材质选项（塑料被标记为 selected）
+- `specifications.年龄段`: 只显示符合当前过滤条件的年龄段选项
+
+## 前端集成建议
+
+### React 示例
+
+```jsx
+function FacetComponent({ facet }) {
+  return (
+    <div className="facet">
+      <h3>{facet.label}</h3>
+      {facet.values.map(value => (
+        <label key={value.value} className={value.selected ? 'active' : ''}>
+          <input 
+            type="checkbox"
+            checked={value.selected}
+            onChange={() => toggleFilter(facet.field, value.value)}
+          />
+          {value.value} ({value.count})
+        </label>
+      ))}
+    </div>
+  );
+}
+```
+
+### Vue 示例
+
+```vue
+<template>
+  <div class="facet">
+    <h3>{{ facet.label }}</h3>
+    <label 
+      v-for="value in facet.values" 
+      :key="value.value"
+      :class="{ active: value.selected }"
+    >
+      <input 
+        type="checkbox"
+        :checked="value.selected"
+        @change="toggleFilter(facet.field, value.value)"
+      />
+      {{ value.value }} ({{ value.count }})
+    </label>
+  </div>
+</template>
+```
+
+## 技术实现细节
+
+### Elasticsearch Query 结构
+
+**Multi-Select Faceting** 使用 `post_filter` 实现：
+
+```json
+{
+  "query": {
+    "bool": {
+      "must": [...],
+      "filter": [
+        // 只包含 multi_select=false 的过滤器
+        {"term": {"category2_name": "短袖T恤"}}
+      ]
+    }
+  },
+  "post_filter": {
+    "bool": {
+      "filter": [
+        // 包含 multi_select=true 的过滤器
+        {"term": {"brand_name": "苹果"}},
+        {
+          "nested": {
+            "path": "specifications",
+            "query": {
+              "bool": {
+                "must": [
+                  {"term": {"specifications.name": "颜色"}},
+                  {"term": {"specifications.value": "白色"}}
+                ]
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "aggs": {
+    // 所有聚合都基于 query 的结果（不受 post_filter 影响）
+    "brand_name_facet": {...},
+    "specifications_颜色_facet": {...}
+  }
+}
+```
+
+**关键点**:
+- `query.bool.filter`: 影响结果和聚合
+- `post_filter`: 只影响结果，不影响聚合
+- 聚合统计基于 `query` 的结果，因此 multi-select facet 可以显示多个选项
+
+## 最佳实践
+
+### 1. 何时使用 Multi-Select
+
+| Facet 类型 | 推荐模式 | 原因 |
+|-----------|---------|------|
+| 颜色 | `multi_select: true` | 用户需要切换颜色 |
+| 品牌 | `multi_select: true` | 用户需要比较不同品牌 |
+| 尺码 | `multi_select: true` | 用户需要查看其他尺码 |
+| 类目 | `multi_select: false` | 层级下钻 |
+| 价格区间 | `multi_select: false` | 互斥选择 |
+| 是否有货 | `multi_select: false` | 布尔值筛选 |
+
+### 2. 性能考虑
+
+- **过多 Multi-Select**: 会增加 ES 查询复杂度
+- **建议**: 最多 3-5 个 multi-select facets
+- **优化**: 对于不常用的属性使用标准模式
+
+### 3. UI 设计建议
+
+- **Multi-Select Facets**: 使用复选框（Checkbox）
+- **Standard Facets**: 使用单选框（Radio）或链接
+- **Selected 状态**: 使用不同颜色或图标标识
+
+## API 变更说明
+
+### 新增字段
+
+**FacetConfig**:
+```json
+{
+  "field": "brand_name",
+  "size": 10,
+  "type": "terms",
+  "multi_select": true  // 新增字段
+}
+```
+
+**FacetValue**:
+```json
+{
+  "value": "苹果",
+  "count": 150,
+  "selected": true  // 现在由后端返回真实状态
+}
+```
+
+### 兼容性
+
+- `multi_select` 默认为 `false`，保持向后兼容
+- 旧版 API 调用仍然有效（使用标准模式）
+
+## 测试验证
+
+运行测试脚本：
+```bash
+python test_multi_select_facet.py
+```
+
+测试覆盖：
+1. ✓ 标准 Faceting (multi_select=false)
+2. ✓ Multi-Select Faceting (multi_select=true)
+3. ✓ Specifications Multi-Select
+4. ✓ ES Query 结构验证
+
+## 故障排查
+
+### 问题 1: Multi-Select 不生效
+
+**症状**: 设置了 `multi_select: true`，但仍然只返回一个值
+
+**检查**:
+1. 确认 `multi_select` 字段在请求中正确设置
+2. 检查 ES query 是否包含 `post_filter`（开启 `debug: true`）
+3. 验证 Elasticsearch 版本支持 `post_filter`
+
+### 问题 2: Selected 标记不正确
+
+**症状**: `selected` 字段没有正确标记
+
+**检查**:
+1. 确认 `filters` 中的字段名与 facet 字段名一致
+2. 对于 specifications，检查 `name` 和 `value` 是否匹配
+3. 检查 `filters` 的值类型（字符串、数组等）
+
+### 问题 3: 性能问题
+
+**症状**: 启用 Multi-Select 后查询变慢
+
+**优化**:
+1. 减少 multi-select facets 数量
+2. 降低 facet `size` 参数
+3. 考虑使用缓存
+4. 为常用字段建立索引
+
+## 参考资料
+
+- [Elasticsearch Post Filter](https://www.elastic.co/guide/en/elasticsearch/reference/current/filter-search-results.html#post-filter)
+- [Algolia Disjunctive Faceting](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#conjunctive-and-disjunctive-facets)
+- [Amazon Product Search](https://www.amazon.com) - 业界最佳实践示例
+
@@ -275,17 +275,20 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
     {
       "field": "category1_name",
       "size": 15,
-      "type": "terms"
+      "type": "terms",
+      "multi_select": false
     },
     {
-      "field": "category2_name",
+      "field": "brand_name",
       "size": 10,
-      "type": "terms"
+      "type": "terms",
+      "multi_select": true
     },
     {
       "field": "specifications.color",
       "size": 20,
-      "type": "terms"
+      "type": "terms",
+      "multi_select": true
     },
     {
       "field": "min_price",
@@ -301,6 +304,62 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 }
 ```
  
+**Facet 字段说明**:
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `field` | string | 是 | - | 分面字段名 |
+| `size` | int | 否 | 10 | 返回的分面值数量（1-100） |
+| `type` | string | 否 | "terms" | 分面类型：`terms`（词条聚合）或 `range`（范围聚合） |
+| `multi_select` | bool | 否 | false | **是否支持多选模式**（见下文详细说明） |
+| `ranges` | array | 否 | null | 范围配置（仅 `type="range"` 时需要） |
+
+#### 🆕 Multi-Select Faceting（多选分面）
+
+**重要特性**: `multi_select` 字段控制分面的行为模式。
+
+##### 标准模式 (multi_select: false)
+- **行为**: 选中某个分面值后，该分面只显示选中的值
+- **适用场景**: 层级类目、互斥选择
+- **示例**: 类目下钻（玩具 > 娃娃 > 芭比）
+
+```json
+{
+  "filters": {"category1_name": "玩具"},
+  "facets": [
+    {"field": "category1_name", "size": 10, "multi_select": false}
+  ]
+}
+```
+**响应**: 只返回 "玩具" 一个选项
+
+##### Multi-Select 模式 (multi_select: true) ⭐
+- **行为**: 选中某个分面值后，该分面仍显示所有可选项
+- **适用场景**: 颜色、品牌、尺码等可切换属性
+- **示例**: 选择了"红色"后，仍能看到"蓝色"、"绿色"等选项
+
+```json
+{
+  "filters": {
+    "specifications": {"name": "颜色", "value": "红色"}
+  },
+  "facets": [
+    {"field": "specifications.颜色", "size": 10, "multi_select": true}
+  ]
+}
+```
+**响应**: 返回所有颜色选项，"红色" 被标记为 `selected: true`
+
+##### 推荐配置
+
+| 分面类型 | multi_select | 原因 |
+|---------|-------------|------|
+| 颜色 | `true` | 用户需要切换颜色 |
+| 品牌 | `true` | 用户需要比较品牌 |
+| 尺码 | `true` | 用户需要查看其他尺码 |
+| 类目 | `false` | 层级下钻 |
+| 价格区间 | `false` | 互斥选择 |
+
 **规格分面说明**:
  
 `specifications` 是嵌套字段，支持两种分面模式：
@@ -326,12 +385,14 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
     {
       "field": "specifications.color",
       "size": 20,
-      "type": "terms"
+      "type": "terms",
+      "multi_select": true
     },
     {
       "field": "specifications.size",
       "size": 15,
-      "type": "terms"
+      "type": "terms",
+      "multi_select": true
     }
   ]
 }
@@ -347,8 +408,9 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
       "label": "color",
       "type": "terms",
       "values": [
-        {"value": "white", "count": 50, "selected": false},
-        {"value": "black", "count": 30, "selected": false}
+        {"value": "white", "count": 50, "selected": true},  // ✓ selected 字段由后端标记
+        {"value": "black", "count": 30, "selected": false},
+        {"value": "red", "count": 20, "selected": false}
       ]
     },
     {
@@ -44,6 +44,54 @@ class ESQueryBuilder:
         self.source_fields = source_fields
         self.function_score_config = function_score_config
  
+    def _split_filters_for_faceting(
+        self,
+        filters: Optional[Dict[str, Any]],
+        facet_configs: Optional[List[Any]]
+    ) -> tuple:
+        """
+        Split filters into conjunctive (query) and disjunctive (post_filter) based on facet configs.
+        
+        Disjunctive filters (multi-select facets):
+        - Applied via post_filter (affects results but not aggregations)
+        - Allows showing other options in the same facet even when filtered
+        
+        Conjunctive filters (standard facets):
+        - Applied in query.bool.filter (affects both results and aggregations)
+        - Standard drill-down behavior
+        
+        Args:
+            filters: All filters from request
+            facet_configs: Facet configurations with multi_select flags
+            
+        Returns:
+            (conjunctive_filters, disjunctive_filters)
+        """
+        if not filters or not facet_configs:
+            return filters or {}, {}
+        
+        # Get fields that support multi-select
+        multi_select_fields = set()
+        for fc in facet_configs:
+            if getattr(fc, 'multi_select', False):
+                # Handle specifications.xxx format
+                if fc.field.startswith('specifications.'):
+                    multi_select_fields.add('specifications')
+                else:
+                    multi_select_fields.add(fc.field)
+        
+        # Split filters
+        conjunctive = {}
+        disjunctive = {}
+        
+        for field, value in filters.items():
+            if field in multi_select_fields:
+                disjunctive[field] = value
+            else:
+                conjunctive[field] = value
+        
+        return conjunctive, disjunctive
+
     def build_query(
         self,
         query_text: str,
@@ -51,6 +99,7 @@ class ESQueryBuilder:
         query_node: Optional[QueryNode] = None,
         filters: Optional[Dict[str, Any]] = None,
         range_filters: Optional[Dict[str, Any]] = None,
+        facet_configs: Optional[List[Any]] = None,
         size: int = 10,
         from_: int = 0,
         enable_knn: bool = True,
@@ -59,10 +108,11 @@ class ESQueryBuilder:
         min_score: Optional[float] = None
     ) -> Dict[str, Any]:
         """
-        Build complete ES query (简化版).
+        Build complete ES query with post_filter support for multi-select faceting.
  
-        结构：filters and (text_recall or embedding_recall)
-        - filters: 前端传递的过滤条件永远起作用
+        结构：filters and (text_recall or embedding_recall) + post_filter
+        - conjunctive_filters: 应用在 query.bool.filter（影响结果和聚合）
+        - disjunctive_filters: 应用在 post_filter（只影响结果，不影响聚合）
         - text_recall: 文本相关性召回（中英文字段都用）
         - embedding_recall: 向量召回（KNN）
         - function_score: 包装召回部分，支持提权字段
@@ -71,8 +121,9 @@ class ESQueryBuilder:
             query_text: Query text for BM25 matching
             query_vector: Query embedding for KNN search
             query_node: Parsed boolean expression tree
-            filters: Exact match filters (always applied)
-            range_filters: Range filters for numeric fields (always applied)
+            filters: Exact match filters
+            range_filters: Range filters for numeric fields (always applied in query)
+            facet_configs: Facet configurations (used to identify multi-select facets)
             size: Number of results
             from_: Offset for pagination
             enable_knn: Whether to use KNN search
@@ -110,8 +161,13 @@ class ESQueryBuilder:
         # Embedding recall (KNN - separate from query, handled below)
         has_embedding = enable_knn and query_vector is not None and self.text_embedding_field
  
-        # 2. Build filter clauses (always applied)
-        filter_clauses = self._build_filters(filters, range_filters)
+        # 2. Split filters for multi-select faceting
+        conjunctive_filters, disjunctive_filters = self._split_filters_for_faceting(
+            filters, facet_configs
+        )
+        
+        # Build filter clauses for query (conjunctive filters + range filters)
+        filter_clauses = self._build_filters(conjunctive_filters, range_filters)
  
         # 3. Build main query structure: filters and recall
         if recall_clauses:
@@ -162,7 +218,18 @@ class ESQueryBuilder:
             }
             es_query["knn"] = knn_clause
  
-        # 5. Add minimum score filter
+        # 5. Add post_filter for disjunctive (multi-select) filters
+        if disjunctive_filters:
+            post_filter_clauses = self._build_filters(disjunctive_filters, None)
+            if post_filter_clauses:
+                if len(post_filter_clauses) == 1:
+                    es_query["post_filter"] = post_filter_clauses[0]
+                else:
+                    es_query["post_filter"] = {
+                        "bool": {"filter": post_filter_clauses}
+                    }
+
+        # 6. Add minimum score filter
         if min_score is not None:
             es_query["min_score"] = min_score
  
@@ -275,6 +275,7 @@ class Searcher:
                 query_node=query_node,
                 filters=filters,
                 range_filters=range_filters,
+                facet_configs=facets,
                 size=size,
                 from_=from_,
                 enable_knn=enable_embedding and parsed_query.query_vector is not None,
@@ -381,7 +382,8 @@ class Searcher:
             if facets:
                 standardized_facets = ResultFormatter.format_facets(
                     es_response.get('aggregations', {}),
-                    facets
+                    facets,
+                    filters
                 )
  
             # Generate suggestions and related searches
@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""
+测试 Multi-Select Faceting 和 Selected 标记功能
+
+验证：
+1. multi_select=False 时，选中某个 facet 值后，该 facet 只返回一个值（标准模式）
+2. multi_select=True 时，选中某个 facet 值后，该 facet 仍返回多个值（disjunctive 模式）
+3. selected 字段正确标记
+"""
+
+import requests
+import json
+
+API_URL = "http://localhost:8000/api/search"
+TENANT_ID = "test_tenant"
+
+def test_standard_faceting():
+    """测试标准 faceting（multi_select=False）"""
+    print("\n" + "="*80)
+    print("测试 1: 标准 Faceting (multi_select=False)")
+    print("="*80)
+    
+    # 选择 category1_name = "玩具"
+    payload = {
+        "query": "*",
+        "size": 5,
+        "filters": {
+            "category1_name": "玩具"
+        },
+        "facets": [
+            {
+                "field": "category1_name",
+                "size": 10,
+                "type": "terms",
+                "multi_select": False  # 标准模式
+            }
+        ]
+    }
+    
+    headers = {"X-Tenant-ID": TENANT_ID}
+    
+    try:
+        response = requests.post(API_URL, json=payload, headers=headers)
+        response.raise_for_status()
+        result = response.json()
+        
+        print(f"\n✓ 请求成功 (HTTP {response.status_code})")
+        print(f"  总结果数: {result.get('total', 0)}")
+        
+        if result.get('facets'):
+            for facet in result['facets']:
+                if facet['field'] == 'category1_name':
+                    print(f"\n  Facet: {facet['field']}")
+                    print(f"  Values 数量: {len(facet['values'])}")
+                    for val in facet['values']:
+                        selected_mark = "✓" if val.get('selected') else " "
+                        print(f"    [{selected_mark}] {val['value']}: {val['count']}")
+                    
+                    # 验证
+                    if len(facet['values']) == 1:
+                        print("\n  ✓ 验证通过: multi_select=False 时，只返回选中的值")
+                    else:
+                        print("\n  ⚠ 警告: multi_select=False 时应只返回一个值")
+                    
+                    selected_values = [v['value'] for v in facet['values'] if v.get('selected')]
+                    if selected_values == ['玩具']:
+                        print("  ✓ 验证通过: selected 字段正确标记")
+                    else:
+                        print(f"  ✗ 错误: selected 标记不正确，期望 ['玩具']，实际 {selected_values}")
+        else:
+            print("\n  ⚠ 警告: 没有返回 facets")
+            
+    except requests.exceptions.RequestException as e:
+        print(f"\n✗ 请求失败: {e}")
+    except Exception as e:
+        print(f"\n✗ 错误: {e}")
+
+
+def test_multi_select_faceting():
+    """测试 Multi-Select Faceting (multi_select=True)"""
+    print("\n" + "="*80)
+    print("测试 2: Multi-Select Faceting (multi_select=True)")
+    print("="*80)
+    
+    # 选择 category1_name = "玩具"
+    payload = {
+        "query": "*",
+        "size": 5,
+        "filters": {
+            "category1_name": "玩具"
+        },
+        "facets": [
+            {
+                "field": "category1_name",
+                "size": 10,
+                "type": "terms",
+                "multi_select": True  # Multi-select 模式
+            }
+        ]
+    }
+    
+    headers = {"X-Tenant-ID": TENANT_ID}
+    
+    try:
+        response = requests.post(API_URL, json=payload, headers=headers)
+        response.raise_for_status()
+        result = response.json()
+        
+        print(f"\n✓ 请求成功 (HTTP {response.status_code})")
+        print(f"  总结果数: {result.get('total', 0)}")
+        
+        if result.get('facets'):
+            for facet in result['facets']:
+                if facet['field'] == 'category1_name':
+                    print(f"\n  Facet: {facet['field']}")
+                    print(f"  Values 数量: {len(facet['values'])}")
+                    for val in facet['values'][:5]:  # 只显示前5个
+                        selected_mark = "✓" if val.get('selected') else " "
+                        print(f"    [{selected_mark}] {val['value']}: {val['count']}")
+                    
+                    # 验证
+                    if len(facet['values']) > 1:
+                        print(f"\n  ✓ 验证通过: multi_select=True 时，返回多个值 ({len(facet['values'])} 个)")
+                    else:
+                        print("\n  ✗ 错误: multi_select=True 时应返回多个值")
+                    
+                    selected_values = [v['value'] for v in facet['values'] if v.get('selected')]
+                    if selected_values == ['玩具']:
+                        print("  ✓ 验证通过: selected 字段正确标记")
+                    else:
+                        print(f"  ⚠ 警告: selected 标记可能不正确，期望 ['玩具']，实际 {selected_values}")
+        else:
+            print("\n  ⚠ 警告: 没有返回 facets")
+            
+    except requests.exceptions.RequestException as e:
+        print(f"\n✗ 请求失败: {e}")
+    except Exception as e:
+        print(f"\n✗ 错误: {e}")
+
+
+def test_specifications_multi_select():
+    """测试 Specifications 的 Multi-Select Faceting"""
+    print("\n" + "="*80)
+    print("测试 3: Specifications Multi-Select Faceting")
+    print("="*80)
+    
+    # 选择 specifications.颜色 = "白色"
+    payload = {
+        "query": "*",
+        "size": 5,
+        "filters": {
+            "specifications": {
+                "name": "颜色",
+                "value": "白色"
+            }
+        },
+        "facets": [
+            {
+                "field": "specifications.颜色",
+                "size": 10,
+                "type": "terms",
+                "multi_select": True
+            },
+            {
+                "field": "specifications.尺寸",
+                "size": 10,
+                "type": "terms",
+                "multi_select": False
+            }
+        ]
+    }
+    
+    headers = {"X-Tenant-ID": TENANT_ID}
+    
+    try:
+        response = requests.post(API_URL, json=payload, headers=headers)
+        response.raise_for_status()
+        result = response.json()
+        
+        print(f"\n✓ 请求成功 (HTTP {response.status_code})")
+        print(f"  总结果数: {result.get('total', 0)}")
+        
+        if result.get('facets'):
+            for facet in result['facets']:
+                print(f"\n  Facet: {facet['field']} (multi_select={facet.get('multi_select', 'N/A')})")
+                print(f"  Values 数量: {len(facet['values'])}")
+                for val in facet['values'][:5]:
+                    selected_mark = "✓" if val.get('selected') else " "
+                    print(f"    [{selected_mark}] {val['value']}: {val['count']}")
+                
+                # 验证 specifications.颜色
+                if facet['field'] == 'specifications.颜色':
+                    if len(facet['values']) > 1:
+                        print(f"  ✓ 验证通过: multi_select=True，返回多个颜色选项")
+                    selected_values = [v['value'] for v in facet['values'] if v.get('selected')]
+                    if '白色' in selected_values:
+                        print("  ✓ 验证通过: '白色' 被正确标记为 selected")
+                
+                # 验证 specifications.尺寸（基于白色商品的尺寸分布）
+                if facet['field'] == 'specifications.尺寸':
+                    print(f"  ℹ 尺寸分布基于已选的颜色过滤器")
+        else:
+            print("\n  ⚠ 警告: 没有返回 facets")
+            
+    except requests.exceptions.RequestException as e:
+        print(f"\n✗ 请求失败: {e}")
+    except Exception as e:
+        print(f"\n✗ 错误: {e}")
+
+
+def test_es_query_structure():
+    """测试 ES Query 结构（需要 debug=True）"""
+    print("\n" + "="*80)
+    print("测试 4: ES Query 结构验证 (debug=True)")
+    print("="*80)
+    
+    payload = {
+        "query": "手机",
+        "size": 1,
+        "filters": {
+            "category1_name": "电子产品",
+            "specifications": {"name": "颜色", "value": "白色"}
+        },
+        "facets": [
+            {
+                "field": "category1_name",
+                "size": 5,
+                "multi_select": True
+            },
+            {
+                "field": "specifications.颜色",
+                "size": 5,
+                "multi_select": True
+            }
+        ],
+        "debug": True
+    }
+    
+    headers = {"X-Tenant-ID": TENANT_ID}
+    
+    try:
+        response = requests.post(API_URL, json=payload, headers=headers)
+        response.raise_for_status()
+        result = response.json()
+        
+        print(f"\n✓ 请求成功")
+        
+        if result.get('debug_info') and result['debug_info'].get('es_query'):
+            es_query = result['debug_info']['es_query']
+            
+            # 检查 post_filter
+            if 'post_filter' in es_query:
+                print("\n  ✓ ES Query 包含 post_filter:")
+                print(f"    {json.dumps(es_query['post_filter'], indent=4, ensure_ascii=False)[:200]}...")
+            else:
+                print("\n  ℹ ES Query 不包含 post_filter（可能没有 multi-select 过滤器）")
+            
+            # 检查 query.bool.filter
+            if 'query' in es_query and 'bool' in es_query['query']:
+                filters = es_query['query']['bool'].get('filter', [])
+                print(f"\n  ✓ Query filters 数量: {len(filters)}")
+                
+        else:
+            print("\n  ⚠ 警告: debug_info 中没有 es_query")
+            
+    except requests.exceptions.RequestException as e:
+        print(f"\n✗ 请求失败: {e}")
+    except Exception as e:
+        print(f"\n✗ 错误: {e}")
+
+
+if __name__ == "__main__":
+    print("\n" + "="*80)
+    print("Multi-Select Faceting 功能测试")
+    print("="*80)
+    print(f"\nAPI URL: {API_URL}")
+    print(f"Tenant ID: {TENANT_ID}")
+    
+    # 运行测试
+    test_standard_faceting()
+    test_multi_select_faceting()
+    test_specifications_multi_select()
+    test_es_query_structure()
+    
+    print("\n" + "="*80)
+    print("测试完成")
+    print("="*80)
+