# Option值参与搜索功能文档

## 功能概述

实现了让子SKU的option值（option1_value, option2_value, option3_value）参与搜索的功能。

**新架构说明**：基于简洁版配置架构，索引结构由 `mappings/search_products.json` 定义，搜索行为由 `config/config.yaml` 配置。

## 改动清单

### 1. 索引Mapping (`mappings/search_products.json`)

添加3个新字段用于存储去重后的option值：

```json
{
  "mappings": {
    "properties": {
      "option1_values": {
        "type": "keyword"
      },
      "option2_values": {
        "type": "keyword"
      },
      "option3_values": {
        "type": "keyword"
      }
    }
  }
}
```

### 2. 配置文件 (`config/config.yaml`)

#### 新增字段权重配置

```yaml
# 字段权重配置
field_boosts:
  # ... 其他字段 ...
  option1_values: 0.5
  option2_values: 0.5
  option3_values: 0.5
```

#### 将新字段加入搜索域

```yaml
indexes:
  - name: "default"
    label: "默认搜索"
    fields:
      - "title_zh"
      - "brief_zh"
      # ... 其他字段 ...
      - "option1_values"
      - "option2_values"
      - "option3_values"
    boost: 1.0
```

#### 新增SPU配置项

```yaml
spu_config:
  enabled: true
  spu_field: "spu_id"
  inner_hits_size: 10
  # 配置哪些option维度参与检索（进索引、以及在线搜索）
  # 格式为list，选择option1/option2/option3中的一个或多个
  searchable_option_dimensions: ['option1', 'option2', 'option3']
```

### 3. 配置加载器 (`config/config_loader.py`)

#### SPUConfig类扩展

```python
@dataclass
class SPUConfig:
    enabled: bool = False
    spu_field: Optional[str] = None
    inner_hits_size: int = 3
    searchable_option_dimensions: List[str] = field(
        default_factory=lambda: ['option1', 'option2', 'option3']
    )
```

#### 配置解析逻辑

```python
spu_config = SPUConfig(
    enabled=spu_data.get("enabled", False),
    spu_field=spu_data.get("spu_field"),
    inner_hits_size=spu_data.get("inner_hits_size", 3),
    searchable_option_dimensions=spu_data.get(
        "searchable_option_dimensions", 
        ['option1', 'option2', 'option3']
    )
)
```

### 4. 数据灌入模块 (`indexer/spu_transformer.py`)

#### 加载配置

```python
def __init__(self, db_engine: Any, tenant_id: str):
    self.db_engine = db_engine
    self.tenant_id = tenant_id
    
    # 加载配置获取searchable_option_dimensions
    try:
        config_loader = ConfigLoader()
        config = config_loader.load_config()
        self.searchable_option_dimensions = config.spu_config.searchable_option_dimensions
    except Exception as e:
        print(f"Warning: Failed to load config, using default: {e}")
        self.searchable_option_dimensions = ['option1', 'option2', 'option3']
```

#### 提取option值逻辑

```python
# 从子SKU提取option值
option1_values = []
option2_values = []
option3_values = []

for _, sku_row in skus.iterrows():
    if pd.notna(sku_row.get('option1')):
        option1_values.append(str(sku_row['option1']))
    if pd.notna(sku_row.get('option2')):
        option2_values.append(str(sku_row['option2']))
    if pd.notna(sku_row.get('option3')):
        option3_values.append(str(sku_row['option3']))

# 去重并根据配置决定是否写入索引
if 'option1' in self.searchable_option_dimensions:
    doc['option1_values'] = list(set(option1_values)) if option1_values else []
else:
    doc['option1_values'] = []

# option2和option3类似...
```

### 5. 在线搜索

**无需修改代码**！

现有的 `get_match_fields_for_index` 机制会自动：
- 从 `field_boosts` 读取字段权重
- 将配置中的字段加入multi_match的fields
- 应用配置的权重（0.5）

## 使用说明

### 配置方式

在 `config/config.yaml` 中修改 `searchable_option_dimensions`：

```yaml
# 所有option都参与检索
searchable_option_dimensions: ['option1', 'option2', 'option3']

# 只有option1参与检索
searchable_option_dimensions: ['option1']

# option1和option3参与检索
searchable_option_dimensions: ['option1', 'option3']
```

### 权重调整

在 `config/config.yaml` 的 `field_boosts` 中修改：

```yaml
field_boosts:
  option1_values: 0.8  # 调整为0.8
  option2_values: 0.5
  option3_values: 0.5
```

### 数据灌入流程

#### 方案1：完整重建索引

```bash
python scripts/recreate_and_import.py \
    --tenant-id 1 \
    --recreate \
    --db-host localhost \
    --db-database saas \
    --db-username root \
    --db-password xxx
```

#### 方案2：单独灌入数据

```bash
python scripts/ingest_shoplazza.py \
    --tenant-id 1 \
    --db-host localhost \
    --db-database saas \
    --db-username root \
    --db-password xxx
```

**注意**：如果修改了mapping（添加新字段），需要先重建索引。

### 测试验证

#### 1. 验证数据是否正确写入

使用ES查询检查文档：

```bash
curl -X GET "localhost:9200/search_products/_search?pretty" \
  -H 'Content-Type: application/json' -d'
{
  "query": {"match_all": {}},
  "size": 1,
  "_source": ["spu_id", "title_zh", "option1_values", "option2_values", "option3_values"]
}
'
```

**期望结果**：
```json
{
  "hits": {
    "hits": [
      {
        "_source": {
          "spu_id": "123",
          "title_zh": "测试商品",
          "option1_values": ["红色", "蓝色", "绿色"],
          "option2_values": ["S", "M", "L"],
          "option3_values": []
        }
      }
    ]
  }
}
```

#### 2. 验证option值参与搜索

假设某个商品有子SKU的option1值为 "红色"、"蓝色"：

```bash
# 搜索"红色"应该能匹配到该商品
curl -X POST "localhost:9200/search_products/_search?pretty" \
  -H 'Content-Type: application/json' -d'
{
  "query": {
    "multi_match": {
      "query": "红色",
      "fields": ["title_zh^3.0", "option1_values^0.5"]
    }
  }
}
'
```

#### 3. 通过API测试

```bash
curl -X POST "http://localhost:6002/api/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "红色",
    "tenant_id": "1",
    "size": 10
  }'
```

**期望**：搜索"红色"能匹配到option1_value包含"红色"的商品。

## 设计亮点

### 1. 配置驱动

通过配置文件灵活控制哪些option参与检索，无需修改代码：

```yaml
searchable_option_dimensions: ['option1']  # 配置即可
```

### 2. 权重集中管理

所有字段权重统一在 `field_boosts` 中配置，便于调整：

```yaml
field_boosts:
  title_zh: 3.0
  option1_values: 0.5
  # 集中管理，一目了然
```

### 3. 复用现有框架

充分利用现有的 `get_match_fields_for_index` 机制：
- 自动从 `field_boosts` 读取权重
- 自动将字段加入搜索
- 无需额外开发

### 4. 最小改动

只修改了必要的模块：
- ✅ 添加mapping字段
- ✅ 添加配置项
- ✅ 修改数据灌入逻辑
- ❌ 无需修改搜索逻辑（自动支持）

### 5. 向后兼容

默认配置包含所有option，不影响现有功能：

```yaml
searchable_option_dimensions: ['option1', 'option2', 'option3']  # 默认全部
```

## 架构优势

### 简洁版配置架构

本功能基于新的简洁版配置架构实现：

| 组件 | 职责 | 优势 |
|------|------|------|
| `mappings/search_products.json` | 定义索引结构 | 单一真相来源 |
| `config/config.yaml` | 定义搜索行为 | 简洁易读 |
| `field_boosts` | 字段权重字典 | 集中管理 |

### 与旧架构对比

**旧架构**：需要在 `config.yaml` 中详细定义字段类型、analyzer等。

**新架构**：只需配置权重，字段结构由mapping定义。

```yaml
# 新架构 - 只配置权重
field_boosts:
  option1_values: 0.5
```

vs

```yaml
# 旧架构 - 需要详细定义（已废弃）
fields:
  - name: "option1_values"
    type: "KEYWORD"
    boost: 0.5
    index: true
    store: true
    # ... 更多配置
```

## 注意事项

### 1. 索引重建

修改mapping后需要重建索引：

```bash
python scripts/recreate_and_import.py --tenant-id 1 --recreate --db-xxx
```

### 2. 配置验证

修改配置后建议验证：

```python
from config import ConfigLoader
loader = ConfigLoader()
config = loader.load_config(validate=True)  # 自动验证
```

### 3. 权重调优

初始权重设为0.5，可根据实际效果调整：

```yaml
field_boosts:
  option1_values: 0.8  # 提高权重
  option2_values: 0.3  # 降低权重
```

### 4. 空值处理

未配置的option字段会写入空数组，不影响搜索：

```python
# 如果只配置 ['option1']
doc['option1_values'] = ["红色", "蓝色"]  # 有值
doc['option2_values'] = []  # 空数组
doc['option3_values'] = []  # 空数组
```

## 故障排查

### 1. option值没有进入索引

**检查项**：
- ✅ `searchable_option_dimensions` 配置是否正确
- ✅ 数据灌入日志是否有警告信息
- ✅ MySQL中的SKU数据option字段是否有值
- ✅ 是否已重建索引

**解决方案**：
```bash
# 查看灌入日志
python scripts/ingest_shoplazza.py --tenant-id 1 --db-xxx

# 检查配置
python -c "from config import ConfigLoader; print(ConfigLoader().load_config().spu_config.searchable_option_dimensions)"
```

### 2. 搜索option值没有效果

**检查项**：
- ✅ 字段是否在 `default` 索引域的 `fields` 列表中
- ✅ 权重是否设置正确（不为0）
- ✅ 使用ES的 `_analyze` API 检查分词

**解决方案**：
```yaml
# 确保字段在搜索域中
indexes:
  - name: "default"
    fields:
      - "option1_values"  # 必须包含

# 确保权重合理
field_boosts:
  option1_values: 0.5  # 不要设为0
```

### 3. 配置加载失败

**检查项**：
- ✅ `config/config.yaml` 语法是否正确
- ✅ 查看应用启动日志

**解决方案**：
```bash
# 验证YAML语法
python -c "import yaml; yaml.safe_load(open('config/config.yaml'))"

# 测试配置加载
python -c "from config import ConfigLoader; ConfigLoader().load_config()"
```

## 性能影响

### 索引大小

每个SPU增加3个keyword数组字段，预估增加：
- 小数据集（<10k SPU）：可忽略
- 中数据集（10k-100k SPU）：约5-10%
- 大数据集（>100k SPU）：需要监控

### 搜索性能

- option_values字段为keyword类型，精确匹配，性能良好
- 权重设为0.5，对相关性影响较小
- 建议监控查询延迟并根据实际情况调整

## 扩展建议

### 1. 动态权重

未来可支持根据用户行为动态调整权重：

```yaml
field_boosts:
  option1_values: ${dynamic.option1_weight}  # 动态权重
```

### 2. 多语言option

支持option值的多语言搜索：

```yaml
field_boosts:
  option1_values_zh: 0.5
  option1_values_en: 0.5
```

### 3. option分组

支持按option分组聚合：

```yaml
facets:
  - field: "option1_values"
    type: "terms"
```

---

**功能版本**: v1.0  
**文档日期**: 2024-12-02  
**架构版本**: v2.0 (简洁版配置架构)