# 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) - 业界最佳实践示例