# 索引字段说明 v2

本文档详细说明 `search_products` 索引的字段结构、类型、数据来源和用途。

## 索引概述

- **索引名称**: `search_products`
- **索引维度**: SPU（Standard Product Unit）级别
- **多租户隔离**: 通过 `tenant_id` 字段实现
- **Mapping 文件**: `mappings/search_products.json`

## 字段分类

### 1. 基础标识字段

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `tenant_id` | keyword | 租户ID，用于多租户隔离 | MySQL: `shoplazza_product_spu.tenant_id` |
| `spu_id` | keyword | SPU唯一标识 | MySQL: `shoplazza_product_spu.id` |
| `create_time` | date | 创建时间 | MySQL: `shoplazza_product_spu.created_at` |
| `update_time` | date | 更新时间 | MySQL: `shoplazza_product_spu.updated_at` |

### 2. 多语言文本字段

所有文本字段都支持中英文双语，后端根据请求的 `language` 参数自动选择对应语言字段返回。

#### 2.1 标题字段

| 字段名 | ES类型 | 分析器 | 说明 | 数据来源 |
|--------|--------|--------|------|----------|
| `title_zh` | text | hanlp_index / hanlp_standard | 中文标题 | MySQL: `shoplazza_product_spu.title` |
| `title_en` | text | english | 英文标题 | 暂为空（待翻译服务填充） |

#### 2.2 描述字段

| 字段名 | ES类型 | 分析器 | 说明 | 数据来源 |
|--------|--------|--------|------|----------|
| `brief_zh` | text | hanlp_index / hanlp_standard | 中文短描述 | MySQL: `shoplazza_product_spu.brief` |
| `brief_en` | text | english | 英文短描述 | 暂为空 |
| `description_zh` | text | hanlp_index / hanlp_standard | 中文详细描述 | MySQL: `shoplazza_product_spu.description` |
| `description_en` | text | english | 英文详细描述 | 暂为空 |

#### 2.3 供应商/品牌字段

| 字段名 | ES类型 | 分析器 | 子字段 | 说明 | 数据来源 |
|--------|--------|--------|--------|------|----------|
| `vendor_zh` | text | hanlp_index / hanlp_standard | `vendor_zh.keyword` (keyword, normalizer: lowercase) | 中文供应商/品牌 | MySQL: `shoplazza_product_spu.vendor` |
| `vendor_en` | text | english | `vendor_en.keyword` (keyword, normalizer: lowercase) | 英文供应商/品牌 | 暂为空 |

**用途**:
- `text` 类型：用于全文搜索（支持模糊匹配）
- `keyword` 子字段：用于精确匹配过滤和分面聚合

### 3. 标签字段

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `tags` | keyword | 标签列表（数组） | MySQL: `shoplazza_product_spu.tags`（逗号分隔字符串，转换为数组） |

**数据格式**: `["新品", "热卖", "爆款"]`

### 4. 类目字段

#### 4.1 类目路径（用于搜索）

| 字段名 | ES类型 | 分析器 | 说明 | 数据来源 |
|--------|--------|--------|------|----------|
| `category_path_zh` | text | hanlp_index / hanlp_standard | 中文类目路径（如"服装/男装/衬衫"） | MySQL: `shoplazza_product_spu.category_path` |
| `category_path_en` | text | english | 英文类目路径 | 暂为空 |

#### 4.2 类目名称（用于搜索）

| 字段名 | ES类型 | 分析器 | 说明 | 数据来源 |
|--------|--------|--------|------|----------|
| `category_name_zh` | text | hanlp_index / hanlp_standard | 中文类目名称 | MySQL: `shoplazza_product_spu.category` |
| `category_name_en` | text | english | 英文类目名称 | 暂为空 |

#### 4.3 类目标识（用于过滤和分面）

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `category_id` | keyword | 类目ID | MySQL: `shoplazza_product_spu.category_id` |
| `category_name` | keyword | 类目名称（用于过滤） | MySQL: `shoplazza_product_spu.category` |
| `category_level` | integer | 类目层级（1/2/3） | MySQL: `shoplazza_product_spu.category_level` |
| `category1_name` | keyword | 一级类目名称 | 从 `category_path` 解析 |
| `category2_name` | keyword | 二级类目名称 | 从 `category_path` 解析 |
| `category3_name` | keyword | 三级类目名称 | 从 `category_path` 解析 |

**用途**:
- `category_path_zh/en`, `category_name_zh/en`: 用于全文搜索，支持模糊匹配
- `category_id`, `category_name`, `category_level`, `category1/2/3_name`: 用于精确过滤和分面聚合

### 5. 规格字段（Specifications）

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `specifications` | nested | 规格列表（嵌套对象数组） | MySQL: `shoplazza_product_option` + `shoplazza_product_sku.option1/2/3` |

**嵌套结构**:
```json
{
  "specifications": [
    {
      "sku_id": "sku_123",
      "name": "color",
      "value": "white"
    },
    {
      "sku_id": "sku_123",
      "name": "size",
      "value": "256GB"
    }
  ]
}
```

**数据来源**:
- `name`: 从 `shoplazza_product_option` 表获取（选项名称，如"color"、"size"）
- `value`: 从 `shoplazza_product_sku` 表的 `option1`, `option2`, `option3` 字段获取（选项值，如"white"、"256GB"）
- `sku_id`: SKU ID，用于关联

**API 过滤示例**:
```json
{
  "query": "手机",
  "filters": {
  "specifications": {
      "name": "color",
      "value": "white"
    }
  }
}
```

**多个规格过滤（按维度分组）**:
```json
{
  "query": "手机",
  "filters": {
    "specifications": [
      {"name": "color", "value": "white"},
      {"name": "size", "value": "256GB"}
    ]
    }
}
```
说明：不同维度（不同name）是AND关系，相同维度（相同name）的多个值是OR关系。

**示例：相同维度的多个值（OR）**:
```json
{
  "query": "手机",
  "filters": {
    "specifications": [
      {"name": "size", "value": "3"},
      {"name": "size", "value": "4"},
      {"name": "size", "value": "5"},
      {"name": "color", "value": "green"}
    ]
  }
}
```
生成查询：(size=3 OR size=4 OR size=5) AND color=green

**ES 查询结构**（后端自动生成）:
```json
{
  "filter": [
    {
      "nested": {
        "path": "specifications",
        "query": {
          "bool": {
            "should": [
              {"bool": {"must": [{"term": {"specifications.name": "size"}}, {"term": {"specifications.value": "3"}}]}},
              {"bool": {"must": [{"term": {"specifications.name": "size"}}, {"term": {"specifications.value": "4"}}]}},
              {"bool": {"must": [{"term": {"specifications.name": "size"}}, {"term": {"specifications.value": "5"}}]}}
            ],
            "minimum_should_match": 1
          }
        }
      }
    },
    {
      "nested": {
        "path": "specifications",
        "query": {
          "bool": {
            "must": [
              {"term": {"specifications.name": "color"}},
              {"term": {"specifications.value": "green"}}
            ]
          }
        }
      }
    }
  ]
}
```

**API 分面示例**:

所有规格名称的分面：
```json
{
  "query": "手机",
  "facets": ["specifications"]
}
```

指定规格名称的分面：
```json
{
  "query": "手机",
  "facets": ["specifications.color", "specifications.size"]
}
```

**ES 聚合结构**（后端自动生成）:

所有规格名称：
```json
{
  "aggs": {
    "specifications_facet": {
      "nested": { "path": "specifications" },
      "aggs": {
        "by_name": {
          "terms": { "field": "specifications.name", "size": 20 },
          "aggs": {
            "value_counts": {
              "terms": { "field": "specifications.value", "size": 10 }
            }
          }
        }
      }
    }
  }
}
```
  
指定规格名称：
```json
{
  "aggs": {
    "specifications_color_facet": {
      "nested": { "path": "specifications" },
      "aggs": {
        "filter_by_name": {
          "filter": { "term": { "specifications.name": "color" } },
          "aggs": {
            "value_counts": {
              "terms": { "field": "specifications.value", "size": 10 }
            }
          }
        }
      }
    }
  }
}
```

### 6. 选项名称字段

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `option1_name` | keyword | 选项1名称（如"color"） | MySQL: `shoplazza_product_option` |
| `option2_name` | keyword | 选项2名称（如"size"） | MySQL: `shoplazza_product_option` |
| `option3_name` | keyword | 选项3名称 | MySQL: `shoplazza_product_option` |

### 7. 价格字段

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `min_price` | float | 最低价格 | 从所有 SKU 价格计算 |
| `max_price` | float | 最高价格 | 从所有 SKU 价格计算 |
| `compare_at_price` | float | 原价/对比价 | MySQL: `shoplazza_product_spu.compare_at_price` |
| `sku_prices` | float | 所有 SKU 价格列表（数组） | 从所有 SKU 价格汇总 |

### 8. 重量字段

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `sku_weights` | long | 所有 SKU 重量列表（数组） | 从所有 SKU 重量汇总 |
| `sku_weight_units` | keyword | 所有 SKU 重量单位列表（数组） | 从所有 SKU 重量单位汇总 |

### 9. 库存字段

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `total_inventory` | long | 总库存（所有 SKU 库存之和） | 从所有 SKU 库存汇总 |

### 10. SKU 嵌套字段

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `skus` | nested | SKU 详细信息列表（嵌套对象数组） | MySQL: `shoplazza_product_sku` |

**嵌套结构**:
```json
{
  "skus": [
    {
      "sku_id": "sku_123",
      "price": 99.99,
      "compare_at_price": 149.99,
      "sku_code": "SKU001",
      "stock": 100,
      "weight": 0.5,
      "weight_unit": "kg",
      "option1_value": "white",
      "option2_value": "256GB",
      "option3_value": null,
      "image_src": "https://example.com/image.jpg"
    }
  ]
}
```

**字段说明**:
- `sku_id`: SKU 唯一标识
- `price`: SKU 价格
- `compare_at_price`: SKU 原价
- `sku_code`: SKU 编码
- `stock`: 库存数量
- `weight`: 重量
- `weight_unit`: 重量单位
- `option1_value`, `option2_value`, `option3_value`: 选项值（对应 `option1_name`, `option2_name`, `option3_name`）
- `image_src`: SKU 图片地址（`index: false`，仅用于返回）

### 11. 图片字段

| 字段名 | ES类型 | 说明 | 数据来源 |
|--------|--------|------|----------|
| `image_url` | keyword | 主图URL（`index: false`，仅用于返回） | MySQL: `shoplazza_product_spu.image_url` |

### 12. 向量字段（不返回给前端）

| 字段名 | ES类型 | 维度 | 说明 | 数据来源 |
|--------|--------|------|------|----------|
| `title_embedding` | dense_vector | 1024 | 标题向量（用于语义搜索） | 由 BGE-M3 模型生成 |
| `image_embedding` | nested | - | 图片向量（用于图片搜索） | 由 CN-CLIP 模型生成 |

**注意**: 这些字段仅用于搜索，不会返回给前端。

## 字段用途总结

### 搜索字段（参与相关性计算）

- `title_zh`, `title_en` (boost: 3.0)
- `brief_zh`, `brief_en` (boost: 1.5)
- `description_zh`, `description_en` (boost: 1.0)
- `vendor_zh`, `vendor_en` (boost: 1.5)
- `tags` (boost: 1.0)
- `category_path_zh`, `category_path_en` (boost: 1.5)
- `category_name_zh`, `category_name_en` (boost: 1.5)
- `title_embedding` (向量召回，boost: 0.2)

### 过滤字段（精确匹配）

- `tenant_id` (必需，多租户隔离)
- `category_id`, `category_name`, `category1_name`, `category2_name`, `category3_name`
- `vendor_zh.keyword`, `vendor_en.keyword`
- `specifications` (嵌套查询)
- `min_price`, `max_price` (范围过滤)

### 分面字段（聚合统计）

- `category1_name`, `category2_name`, `category3_name`
- `specifications` (所有规格名称的分面，嵌套聚合，按 name 分组，然后按 value 聚合)
- `specifications.{name}` (指定规格名称的分面，如 `specifications.color`，只返回该 name 的 value 列表)

### 返回字段（前端展示）

除 `title_embedding` 和 `image_embedding` 外，所有字段都会根据 `language` 参数自动选择对应的中英文字段返回。

## 数据映射规则

### 多语言字段映射

后端根据请求的 `language` 参数（`zh` 或 `en`）自动选择：

- `language="zh"`: 优先返回 `*_zh` 字段，如果为空则回退到 `*_en` 字段
- `language="en"`: 优先返回 `*_en` 字段，如果为空则回退到 `*_zh` 字段

映射到前端字段：
- `title_zh/en` → `title`
- `brief_zh/en` → `brief`
- `description_zh/en` → `description`
- `vendor_zh/en` → `vendor`
- `category_path_zh/en` → `category_path`
- `category_name_zh/en` → `category_name`

### 规格数据构建

1. 从 `shoplazza_product_option` 表获取选项名称（`option1_name`, `option2_name`, `option3_name`）
2. 从 `shoplazza_product_sku` 表获取选项值（`option1`, `option2`, `option3`）
3. 将每个 SKU 的选项组合构建为 `specifications` 数组：
   ```python
   for sku in skus:
       if sku.option1 and option1_name:
           specifications.append({
               "sku_id": sku.id,
               "name": option1_name,  # 如"color"
               "value": sku.option1   # 如"white"
           })
       # 同样处理 option2, option3
   ```

## 查询架构

### 查询结构

```
filters AND (text_recall OR embedding_recall)
```

- **filters**: 前端传递的过滤条件（永远起作用）
- **text_recall**: 文本相关性召回（同时搜索中英文字段）
- **embedding_recall**: 向量召回（KNN）
- **function_score**: 包装召回部分，支持提权字段（新鲜度、销量等）

### 文本召回字段

默认同时搜索以下字段（中英文都包含）：
- `title_zh^3.0`, `title_en^3.0`
- `brief_zh^1.5`, `brief_en^1.5`
- `description_zh^1.0`, `description_en^1.0`
- `vendor_zh^1.5`, `vendor_en^1.5`
- `category_path_zh^1.5`, `category_path_en^1.5`
- `category_name_zh^1.5`, `category_name_en^1.5`
- `tags^1.0`

## 注意事项

1. **索引维度**: 所有数据以 SPU 为单位索引，SKU 信息作为嵌套字段存储
2. **多租户隔离**: 所有查询必须包含 `tenant_id` 过滤条件
3. **多语言支持**: 文本字段支持中英文，后端根据 `language` 参数自动选择
4. **规格分面**: `specifications` 使用嵌套聚合，按 `name` 分组，然后按 `value` 聚合
5. **向量字段**: `title_embedding` 和 `image_embedding` 仅用于搜索，不返回给前端