# 索引字段说明文档

本文档详细说明了 Elasticsearch 索引中所有字段的类型、索引方式、数据来源等信息。

## 索引基本信息

- **索引名称**: `search_products`
- **索引级别**: SPU级别（商品级别）
- **数据结构**: SPU文档包含嵌套的skus（SKU）数组

## 字段说明表

### 基础字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
| tenant_id | keyword | 是 | 精确匹配 | SPU表 | tenant_id | BIGINT | 租户ID，用于多租户隔离 |
| spu_id | keyword | 是 | 精确匹配 | SPU表 | id | BIGINT | 商品ID（SPU ID） |
| handle | keyword | 是 | 精确匹配 | SPU表 | handle | VARCHAR(255) | 商品URL handle |

### 文本搜索字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | Boost权重 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|-----------|------|
| title | TEXT | 是 | english | SPU表 | title | VARCHAR(512) | 3.0 | 商品标题，权重最高 |
| brief | TEXT | 是 | english | SPU表 | brief | VARCHAR(512) | 1.5 | 商品简介 |
| description | TEXT | 是 | english | SPU表 | description | TEXT | 1.0 | 商品详细描述 |

### SEO字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | Boost权重 | 是否返回 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|-----------|---------|------|
| seo_title | TEXT | 是 | english | SPU表 | seo_title | VARCHAR(512) | 2.0 | 否 | SEO标题，用于提升相关性 |
| seo_description | TEXT | 是 | english | SPU表 | seo_description | TEXT | 1.5 | 否 | SEO描述 |
| seo_keywords | TEXT | 是 | english | SPU表 | seo_keywords | VARCHAR(1024) | 2.0 | 否 | SEO关键词 |

### 分类和标签字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | Boost权重 | 是否返回 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|-----------|---------|------|
| vendor | TEXT | 是 | english | SPU表 | vendor | VARCHAR(255) | 1.5 | 是 | 供应商/品牌（文本搜索） |
| vendor.keyword | keyword | 是 | 精确匹配 | SPU表 | vendor | VARCHAR(255) | - | 否 | 供应商/品牌（精确匹配，用于过滤） |
| product_type | TEXT | 是 | english | SPU表 | category | VARCHAR(255) | 1.5 | 是 | 商品类型（文本搜索） |
| product_type_keyword | keyword | 是 | 精确匹配 | SPU表 | category | VARCHAR(255) | - | 否 | 商品类型（精确匹配，用于过滤） |
| tags | TEXT | 是 | english | SPU表 | tags | VARCHAR(1024) | 1.0 | 是 | 标签（文本搜索） |
| tags.keyword | keyword | 是 | 精确匹配 | SPU表 | tags | VARCHAR(1024) | - | 否 | 标签（精确匹配，用于过滤） |
| category | TEXT | 是 | english | SPU表 | category | VARCHAR(255) | 1.5 | 是 | 类目（文本搜索） |
| category.keyword | keyword | 是 | 精确匹配 | SPU表 | category | VARCHAR(255) | - | 否 | 类目（精确匹配，用于过滤） |

### 价格字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
| min_price | FLOAT | 是 | float | SKU表（聚合计算） | price | DECIMAL(10,2) | 最低价格（从所有SKU中取最小值） |
| max_price | FLOAT | 是 | float | SKU表（聚合计算） | price | DECIMAL(10,2) | 最高价格（从所有SKU中取最大值） |
| compare_at_price | FLOAT | 是 | float | SKU表（聚合计算） | compare_at_price | DECIMAL(10,2) | 原价（从所有SKU中取最大值） |

**价格计算逻辑**：
- `min_price`: 取该SPU下所有SKU的price字段的最小值
- `max_price`: 取该SPU下所有SKU的price字段的最大值
- `compare_at_price`: 取该SPU下所有SKU的compare_at_price字段的最大值（如果存在）

### 图片字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
| image_url | keyword | 否 | 不索引 | SPU表 | image_src | VARCHAR(500) | 商品主图URL，仅用于展示 |

### 文本嵌入字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
| title_embedding | TEXT_EMBEDDING | 是 | 向量相似度（dot_product） | 计算生成 | title | VARCHAR(512) | 标题的文本向量（1024维），用于语义搜索 |

**说明**：
- 向量维度：1024
- 相似度算法：dot_product（点积）
- 数据来源：基于title字段通过BGE-M3模型生成

### 时间字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 是否返回 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|---------|------|
| create_time | DATE | 是 | 日期范围 | SPU表 | create_time | DATETIME | 是 | 创建时间 |
| update_time | DATE | 是 | 日期范围 | SPU表 | update_time | DATETIME | 是 | 更新时间 |
| shoplazza_created_at | DATE | 是 | 日期范围 | SPU表 | shoplazza_created_at | DATETIME | 否 | 店匠系统创建时间 |
| shoplazza_updated_at | DATE | 是 | 日期范围 | SPU表 | shoplazza_updated_at | DATETIME | 否 | 店匠系统更新时间 |

### 嵌套Skus字段（SKU级别）

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
| skus | JSON (nested) | 是 | 嵌套对象 | SKU表 | - | - | 商品变体数组（嵌套结构） |

#### Skus子字段

| 索引字段名 | ES字段类型 | 是否索引 | 索引方式 | 数据来源表 | 表中字段名 | 表中字段类型 | 说明 |
|-----------|-----------|---------|---------|-----------|-----------|-------------|------|
| skus.sku_id | keyword | 是 | 精确匹配 | SKU表 | id | BIGINT | 变体ID（SKU ID） |
| skus.title | text | 是 | english | SKU表 | title | VARCHAR(500) | 变体标题 |
| skus.price | float | 是 | float | SKU表 | price | DECIMAL(10,2) | 变体价格 |
| skus.compare_at_price | float | 是 | float | SKU表 | compare_at_price | DECIMAL(10,2) | 变体原价 |
| skus.sku | keyword | 是 | 精确匹配 | SKU表 | sku | VARCHAR(100) | SKU编码 |
| skus.stock | long | 是 | float | SKU表 | inventory_quantity | INT(11) | 库存数量 |
| skus.options | object | 是 | 对象 | SKU表 | option1/option2/option3 | VARCHAR(255) | 选项（颜色、尺寸等） |

**Skus结构说明**：
- `skus` 是一个嵌套对象数组，每个元素代表一个SKU
- 使用ES的nested类型，支持对嵌套字段进行独立查询和过滤
- `options` 对象包含 `option1`、`option2`、`option3` 三个字段，分别对应SKU表中的选项值

## 字段类型说明

### ES字段类型映射

| ES字段类型 | Elasticsearch映射 | 用途 |
|-----------|------------------|------|
| keyword | keyword | 精确匹配、过滤、聚合、排序 |
| TEXT | text | 全文检索（支持分词） |
| FLOAT | float | 浮点数（价格、权重等） |
| LONG | long | 整数（库存、计数等） |
| DATE | date | 日期时间 |
| TEXT_EMBEDDING | dense_vector | 文本向量（1024维） |
| JSON | object/nested | 嵌套对象 |

### 分析器说明

| 分析器名称 | 语言 | 说明 |
|-----------|------|------|
| chinese_ecommerce | 中文 | Ansj中文分词器（电商优化），用于中文文本的分词和搜索 |

## 索引配置

### 索引设置

- **分片数**: 1
- **副本数**: 0
- **刷新间隔**: 30秒

### 查询域（Query Domains）

系统定义了多个查询域，用于在不同场景下搜索不同的字段组合：

1. **default（默认索引）**: 搜索所有文本字段
   - 包含字段：title, brief, description, seo_title, seo_description, seo_keywords, vendor, product_type, tags, category
   - Boost: 1.0

2. **title（标题索引）**: 仅搜索标题相关字段
   - 包含字段：title, seo_title
   - Boost: 2.0

3. **vendor（品牌索引）**: 仅搜索品牌字段
   - 包含字段：vendor
   - Boost: 1.5

4. **category（类目索引）**: 仅搜索类目字段
   - 包含字段：category
   - Boost: 1.5

5. **tags（标签索引）**: 搜索标签和SEO关键词
   - 包含字段：tags, seo_keywords
   - Boost: 1.0

## 数据转换规则

### 数据类型转换

1. **BIGINT → keyword**: 数字ID转换为字符串（如 `spu_id`, `sku_id`）
2. **DECIMAL → FLOAT**: 价格字段从DECIMAL转换为FLOAT
3. **INT → LONG**: 库存数量从INT转换为LONG
4. **DATETIME → DATE**: 时间字段转换为ISO格式字符串

### 特殊处理

1. **价格聚合**: 从多个SKU的价格中计算min_price、max_price、compare_at_price
2. **图片URL处理**: 如果image_src不是完整URL，会自动添加协议前缀
3. **选项合并**: 将SKU表的option1、option2、option3合并为options对象

## 注意事项

1. **多租户隔离**: 所有查询必须包含 `tenant_id` 过滤条件
2. **嵌套查询**: 查询skus字段时需要使用nested查询语法
3. **字段命名**: 用于过滤的字段应使用 `*_keyword` 后缀的字段
4. **向量搜索**: title_embedding字段用于语义搜索，需要配合文本查询使用
5. **Boost权重**: 不同字段的boost权重影响搜索结果的相关性排序

## 数据来源表结构

### SPU表（shoplazza_product_spu）

主要字段：
- `id`: BIGINT - 主键ID
- `tenant_id`: BIGINT - 租户ID
- `handle`: VARCHAR(255) - URL handle
- `title`: VARCHAR(512) - 商品标题
- `brief`: VARCHAR(512) - 商品简介
- `description`: TEXT - 商品描述
- `vendor`: VARCHAR(255) - 供应商/品牌
- `category`: VARCHAR(255) - 类目
- `tags`: VARCHAR(1024) - 标签
- `seo_title`: VARCHAR(512) - SEO标题
- `seo_description`: TEXT - SEO描述
- `seo_keywords`: VARCHAR(1024) - SEO关键词
- `image_src`: VARCHAR(500) - 图片URL
- `create_time`: DATETIME - 创建时间
- `update_time`: DATETIME - 更新时间
- `shoplazza_created_at`: DATETIME - 店匠创建时间
- `shoplazza_updated_at`: DATETIME - 店匠更新时间

### SKU表（shoplazza_product_sku）

主要字段：
- `id`: BIGINT - 主键ID（对应sku_id）
- `spu_id`: BIGINT - SPU ID（关联字段）
- `title`: VARCHAR(500) - 变体标题
- `price`: DECIMAL(10,2) - 价格
- `compare_at_price`: DECIMAL(10,2) - 原价
- `sku`: VARCHAR(100) - SKU编码
- `inventory_quantity`: INT(11) - 库存数量
- `option1`: VARCHAR(255) - 选项1
- `option2`: VARCHAR(255) - 选项2
- `option3`: VARCHAR(255) - 选项3