# MySQL 到 Elasticsearch 字段映射说明（业务版）

## 1. 概述

本文档说明 Elasticsearch 中的商品文档（Document）的各个字段是如何从 MySQL 数据库中的相关表获取和转换的。

### 1.1 数据源表

- **SPU 表** (`shoplazza_product_spu`): 商品基本信息
- **SKU 表** (`shoplazza_product_sku`): 商品变体信息（多款式）
- **Option 表** (`shoplazza_product_option`): 选项名称定义（如：颜色、尺寸）
- **类目表** (`product_category`): 类目信息（通过 SPU 表的 category_id 关联）

---

## 2. 基础字段映射

### 2.1 标识字段

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `tenant_id` | SPU 表 | `tenant_id` | 直接使用，转为字符串 |
| `spu_id` | SPU 表 | `id` | 直接使用，转为字符串 |

### 2.2 文本字段（多语言）

文本字段支持中英文双语，根据租户配置自动翻译。

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `title.zh` | SPU 表 | `title` | 如果主语言是中文，直接使用；否则翻译为中文 |
| `title.en` | SPU 表 | `title` | 如果主语言是英文，直接使用；否则翻译为英文 |
| `brief.zh` | SPU 表 | `brief` | 同上 |
| `brief.en` | SPU 表 | `brief` | 同上 |
| `description.zh` | SPU 表 | `description` | 同上 |
| `description.en` | SPU 表 | `description` | 同上 |
| `vendor.zh` | SPU 表 | `vendor` | 同上 |
| `vendor.en` | SPU 表 | `vendor` | 同上 |

**翻译规则：**
- 根据租户配置的 `primary_language` 确定主语言
- 如果配置了 `translate_to_en=true`，且主语言不是英文，则翻译为英文
- 如果配置了 `translate_to_zh=true`，且主语言不是中文，则翻译为中文

### 2.3 标签字段

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `tags` | SPU 表 | `tags` | 逗号分隔的字符串 → 数组<br/>示例：`"标签1,标签2"` → `["标签1", "标签2"]` |

### 2.4 图片字段

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `image_url` | SPU 表 | `image_src` |  |

### 2.5 销量字段

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `sales` | SPU 表 | `fake_sales` | 转为整数，如果为空则为 0 |

### 2.6 时间字段

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `create_time` | SPU 表 | `create_time` | 转为 ISO 格式字符串（如：`2024-01-01T00:00:00`） |
| `update_time` | SPU 表 | `update_time` | 转为 ISO 格式字符串 |

---

## 3. 类别（Category）字段映射

### 3.1 类别数据来源

类别信息主要来自 SPU 表的以下字段：
- `category_path`: 类目路径，逗号分隔的类目ID列表（如：`"1,2,3"`）
- `category`: 类目名称（备用字段）
- `category_id`: 当前类目ID
- `category_level`: 类目层级

### 3.2 类别映射流程

**步骤 1：解析 category_path**

从 SPU 表的 `category_path` 字段解析出类目ID列表：

```
category_path = "1,2,3"
→ category_ids = ["1", "2", "3"]
```

**步骤 2：ID 转名称**

通过预加载的类目映射表（从 SPU 表查询 `category_id` 和 `category` 字段构建），将ID转换为名称：

```
映射表：{"1": "电子产品", "2": "手机", "3": "iPhone"}
category_ids = ["1", "2", "3"]
→ category_names = ["电子产品", "手机", "iPhone"]
```

**步骤 3：构建 ES 字段**

| ES 字段 | 数据来源 | 转换说明 |
|---------|----------|----------|
| `category_path.zh` | 类目名称列表 | 用 `/` 连接：`"电子产品/手机/iPhone"` |
| `category1_name` | 类目名称列表[0] | 一级类目：`"电子产品"` |
| `category2_name` | 类目名称列表[1] | 二级类目：`"手机"` |
| `category3_name` | 类目名称列表[2] | 三级类目：`"iPhone"` |
| `category_id` | SPU 表 | `category_id` 转为字符串 |
| `category_level` | SPU 表 | `category_level` 转为整数 |

**备用处理：**

如果 `category_path` 为空，使用 `category` 字段作为备选：
- 如果 `category` 包含 `/`，按 `/` 分割为多级类目
- 否则，直接作为 `category1_name`

**数据质量检查：**

如果 `category_path` 中的类目ID在映射表中不存在，则不写入任何类目字段（视为没有类目）。

---

## 4. 多款式（SKU/Options）字段映射

### 4.1 SKU 嵌套结构

一个 SPU 可以有多个 SKU，每个 SKU 代表一个商品变体（如：红色-L码、蓝色-M码）。

**ES 中的 `skus` 字段结构：**

```json
{
  "skus": [
    {
      "sku_id": "123",
      "price": 99.99,
      "compare_at_price": 129.99,
      "sku_code": "SKU001",
      "stock": 100,
      "weight": 0.5,
      "weight_unit": "kg",
      "option1_value": "红色",
      "option2_value": "L",
      "option3_value": "棉",
      "image_src": "https://..."
    }
  ]
}
```

### 4.2 SKU 字段映射

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `skus[].sku_id` | SKU 表 | `id` | 转为字符串 |
| `skus[].price` | SKU 表 | `price` | 转为浮点数 |
| `skus[].compare_at_price` | SKU 表 | `compare_at_price` | 转为浮点数 |
| `skus[].sku_code` | SKU 表 | `sku` | 转为字符串 |
| `skus[].stock` | SKU 表 | `inventory_quantity` | 转为整数 |
| `skus[].weight` | SKU 表 | `weight` | 转为浮点数 |
| `skus[].weight_unit` | SKU 表 | `weight_unit` | 转为字符串 |
| `skus[].image_src` | SKU 表 | `image_src` | 转为字符串 |
| `skus[].option1_value` | SKU 表 | `option1` | 转为字符串 |
| `skus[].option2_value` | SKU 表 | `option2` | 转为字符串 |
| `skus[].option3_value` | SKU 表 | `option3` | 转为字符串 |

### 4.3 选项名称字段

选项名称来自 Option 表，按 `position` 字段排序（1、2、3 对应 option1、option2、option3）。

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `option1_name` | Option 表 | `name` (where position=1) | 第一个选项的名称（如："颜色"） |
| `option2_name` | Option 表 | `name` (where position=2) | 第二个选项的名称（如："尺寸"） |
| `option3_name` | Option 表 | `name` (where position=3) | 第三个选项的名称（如："材质"） |

**查询逻辑：**

```sql
SELECT position, name
FROM shoplazza_product_option
WHERE spu_id = ? AND deleted = 0
ORDER BY position
```

### 4.4 选项值字段

选项值来自所有 SKU 的 `option1`、`option2`、`option3` 字段，去重后形成列表。

| ES 字段 | 数据来源表 | 表中字段 | 转换说明 |
|---------|-----------|----------|----------|
| `option1_values` | SKU 表 | `option1` | 收集所有 SKU 的 option1 值，去重<br/>示例：`["红色", "蓝色", "绿色"]` |
| `option2_values` | SKU 表 | `option2` | 收集所有 SKU 的 option2 值，去重<br/>示例：`["S", "M", "L"]` |
| `option3_values` | SKU 表 | `option3` | 收集所有 SKU 的 option3 值，去重<br/>示例：`["棉", "涤纶"]` |

**转换逻辑：**

```
遍历所有 SKU：
  - 收集 option1 值 → option1_values 列表
  - 收集 option2 值 → option2_values 列表
  - 收集 option3 值 → option3_values 列表
去重后写入 ES
```

**注意：** 只有配置在 `searchable_option_dimensions` 中的选项才会被索引。

### 4.5 规格（Specifications）字段

规格字段用于支持按规格过滤和分面搜索，将 SKU 的选项值结构化存储。

**ES 中的 `specifications` 字段结构：**

```json
{
  "specifications": [
    {"sku_id": "123", "name": "颜色", "value": "红色"},
    {"sku_id": "123", "name": "尺寸", "value": "L"},
    {"sku_id": "124", "name": "颜色", "value": "蓝色"},
    {"sku_id": "124", "name": "尺寸", "value": "M"}
  ]
}
```

**构建逻辑：**

1. 从 Option 表获取选项名称映射：
   ```
   position=1 → name="颜色"
   position=2 → name="尺寸"
   position=3 → name="材质"
   ```

2. 遍历所有 SKU，为每个 SKU 的每个选项值构建规格记录：
   ```
   SKU.id=123, option1="红色", option2="L"
   → {"sku_id": "123", "name": "颜色", "value": "红色"}
   → {"sku_id": "123", "name": "尺寸", "value": "L"}
   ```

| ES 字段 | 数据来源 | 转换说明 |
|---------|----------|----------|
| `specifications[].sku_id` | SKU 表 | `id` 转为字符串 |
| `specifications[].name` | Option 表 | `name`（根据 position 匹配） |
| `specifications[].value` | SKU 表 | `option1/2/3` 转为字符串 |

### 4.6 价格聚合字段

从所有 SKU 的价格中计算聚合值。

| ES 字段 | 数据来源 | 转换说明 |
|---------|----------|----------|
| `min_price` | SKU 表 | 所有 SKU 的 `price` 最小值 |
| `max_price` | SKU 表 | 所有 SKU 的 `price` 最大值 |
| `compare_at_price` | SKU 表 | 所有 SKU 的 `compare_at_price` 最大值 |
| `sku_prices` | SKU 表 | 所有 SKU 的 `price` 数组<br/>示例：`[99.99, 99.99, 129.99]` |

**计算逻辑：**

```
遍历所有 SKU：
  - 收集 price → prices 列表
  - 收集 compare_at_price → compare_prices 列表

min_price = min(prices)
max_price = max(prices)
compare_at_price = max(compare_prices)
sku_prices = prices 列表
```

### 4.7 库存和重量聚合字段

| ES 字段 | 数据来源 | 转换说明 |
|---------|----------|----------|
| `total_inventory` | SKU 表 | 所有 SKU 的 `inventory_quantity` 求和 |
| `sku_weights` | SKU 表 | 所有 SKU 的 `weight` 数组<br/>示例：`[500, 500, 600]` |
| `sku_weight_units` | SKU 表 | 所有 SKU 的 `weight_unit` 去重后的列表<br/>示例：`["kg"]` |

**计算逻辑：**

```
遍历所有 SKU：
  - 累加 inventory_quantity → total_inventory
  - 收集 weight → sku_weights 列表
  - 收集 weight_unit → sku_weight_units 列表

total_inventory = 所有 SKU 库存之和
sku_weights = 所有 SKU 重量数组
sku_weight_units = 去重后的重量单位列表
```

---

## 5. 向量字段映射

### 5.1 标题向量（title_embedding）

| ES 字段 | 数据来源 | 转换说明 |
|---------|----------|----------|
| `title_embedding` | SPU 表 `title` | 使用文本编码器（BGE）将标题转换为 1024 维向量<br/>优先使用 `title.en`，如果没有则使用 `title.zh` |

**生成逻辑：**

```
如果启用向量搜索：
  文本 = title.en 或 title.zh
  向量 = 文本编码器.encode(文本)
  title_embedding = 向量（1024 维浮点数组）
```

---

## 6. 完整字段映射表

### 6.1 字段来源汇总

| ES 字段 | 数据来源表 | 表中字段 | 说明 |
|---------|-----------|----------|------|
| **基础字段** |
| `tenant_id` | SPU | `tenant_id` | 租户ID |
| `spu_id` | SPU | `id` | 商品ID |
| `title.zh/en` | SPU | `title` | 标题（多语言） |
| `brief.zh/en` | SPU | `brief` | 简介（多语言） |
| `description.zh/en` | SPU | `description` | 描述（多语言） |
| `vendor.zh/en` | SPU | `vendor` | 品牌（多语言） |
| `tags` | SPU | `tags` | 标签数组 |
| `image_url` | SPU | `image_src` | 主图URL |
| `sales` | SPU | `fake_sales` | 销量 |
| `create_time` | SPU | `create_time` | 创建时间 |
| `update_time` | SPU | `update_time` | 更新时间 |
| **类别字段** |
| `category_path.zh` | SPU + 类目映射 | `category_path` → 类目名称 | 类目路径 |
| `category1_name` | SPU + 类目映射 | `category_path` → 类目名称[0] | 一级类目 |
| `category2_name` | SPU + 类目映射 | `category_path` → 类目名称[1] | 二级类目 |
| `category3_name` | SPU + 类目映射 | `category_path` → 类目名称[2] | 三级类目 |
| `category_id` | SPU | `category_id` | 类目ID |
| `category_level` | SPU | `category_level` | 类目层级 |
| **SKU 嵌套字段** |
| `skus[]` | SKU | 多个字段 | SKU 数组（见 4.2 节） |
| **选项字段** |
| `option1_name` | Option | `name` (position=1) | 选项1名称 |
| `option2_name` | Option | `name` (position=2) | 选项2名称 |
| `option3_name` | Option | `name` (position=3) | 选项3名称 |
| `option1_values` | SKU | `option1` | 选项1值列表 |
| `option2_values` | SKU | `option2` | 选项2值列表 |
| `option3_values` | SKU | `option3` | 选项3值列表 |
| **规格字段** |
| `specifications[]` | SKU + Option | `option1/2/3` + `name` | 规格数组 |
| **聚合字段** |
| `min_price` | SKU | `price` | 最低价格 |
| `max_price` | SKU | `price` | 最高价格 |
| `compare_at_price` | SKU | `compare_at_price` | 最高原价 |
| `sku_prices` | SKU | `price` | 所有价格数组 |
| `total_inventory` | SKU | `inventory_quantity` | 总库存 |
| `sku_weights` | SKU | `weight` | 所有重量数组 |
| `sku_weight_units` | SKU | `weight_unit` | 重量单位列表 |
| **向量字段** |
| `title_embedding` | SPU | `title` | 标题向量（1024维） |

---

## 7. 数据查询示例

### 7.1 查询 SPU 数据

```sql
SELECT 
    id, tenant_id, title, brief, description, vendor,
    category, category_id, category_path, category_level,
    tags, image_src, fake_sales, create_time, update_time
FROM shoplazza_product_spu
WHERE tenant_id = ? AND id = ? AND deleted = 0
```

### 7.2 查询 SKU 数据

```sql
SELECT 
    id, spu_id, price, compare_at_price, sku,
    inventory_quantity, weight, weight_unit,
    option1, option2, option3, image_src
FROM shoplazza_product_sku
WHERE tenant_id = ? AND spu_id = ? AND deleted = 0
```

### 7.3 查询 Option 数据

```sql
SELECT 
    position, name
FROM shoplazza_product_option
WHERE tenant_id = ? AND spu_id = ? AND deleted = 0
ORDER BY position
```

### 7.4 查询类目映射

```sql
SELECT DISTINCT
    category_id, category
FROM shoplazza_product_spu
WHERE deleted = 0 AND category_id IS NOT NULL
```

---

## 8. ES 文档示例

```json
GET /search_products/_search
{
    "size": 1,
    "_source": "*",
    "query": {
      "bool": {
        "filter": [
          { "term": {"_id" : 74174} },
          { "term": { "tenant_id": "162" } }
        ]
      }
    }
  }
```

结果

```json
{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0,
    "hits": [
      {
        "_index": "search_products",
        "_id": "74174",
        "_score": 0,
        "_source": {
          "tenant_id": "162",
          "spu_id": "74174",
          "title.zh": "实色二阶碳纤维魔方 方形 2阶 塑料【英文包装】",
          "title.en": "Solid Color 2nd Order Carbon Fiber Rubik's Cube Square 2 Steps Plastic [English Packaging",
          "brief.zh": "实色二阶碳纤维魔方 方形 2阶 塑料【英文包装】",
          "brief.en": "Solid Color 2nd Order Carbon Fiber Rubik's Cube Square 2 Steps Plastic [English Packaging",
          "description.zh": "<p>实色二阶碳纤维魔方 方形 2阶 塑料【英文包装】</p>",
          "description.en": "<p>Solid Color 2nd Order Carbon Fiber Rubik's Cube Square 2 Steps Plastic [English Packaging]</p",
          "vendor.zh": "顺达",
          "vendor.en": "Shunda",
          "title_embedding": [
            -0.005125104915350676,
...
            0.018752742558717728
          ],
          "tags": [
            "魔方",
            "ShunDa"
          ],
          "category_path.zh": "玩具/汽车",
          "category_path.en": null,
          "category1_name": "玩具",
          "category2_name": "汽车",
          "category_name_text.zh": "汽车",
          "category_name_text.en": null,
          "category_name": "汽车",
          "category_id": "593389466647880832",
          "category_level": 2,
          "option1_name": "color",
          "option2_name": "size",
          "option3_name": "material",
          "image_url": "////img.staticdj.com/6eb4a98e2cb23af523da5456e424fc24.jpeg",
          "sales": 0,
          "skus": [
            {
              "sku_id": "3577878",
              "price": 346.13,
              "compare_at_price": 464.3,
              "sku_code": "2210777-Orange-30-塑料英文包装",
              "stock": 87,
              "weight": 1.99,
              "weight_unit": "kg",
              "option1_value": "Orange",
              "option2_value": "30",
              "option3_value": "塑料英文包装"
            },
            {
              "sku_id": "3577879",
              "price": 316.62,
              "compare_at_price": 466.27,
              "sku_code": "2210777-Orange-8-塑料英文包装",
              "stock": 41,
              "weight": 1.95,
              "weight_unit": "kg",
              "option1_value": "Orange",
              "option2_value": "8",
              "option3_value": "塑料英文包装"
            },
...
            {
              "sku_id": "3577941",
              "price": 380.03,
              "compare_at_price": 553.67,
              "sku_code": "2210777-Olive-2-塑料英文包装",
              "stock": 56,
              "weight": 2.78,
              "weight_unit": "kg",
              "option1_value": "Olive",
              "option2_value": "2",
              "option3_value": "塑料英文包装"
            }
          ],
          "specifications": [
            {
              "sku_id": "3577878",
              "name": "color",
              "value": "Orange"
            },
...
            {
              "sku_id": "3577941",
              "name": "material",
              "value": "塑料英文包装"
            }
          ],
          "option1_values": [
            "White",
            "Gold",
            "Violet",
            "Olive",
            "Turquoise",
            "Khaki",
            "Teal",
            "Orange"
          ],
          "option2_values": [
            "2",
            "30",
            "8",
            "1",
            "18",
            "27",
            "25",
            "29"
          ],
          "option3_values": [
            "塑料英文包装"
          ],
          "min_price": 262.92,
          "max_price": 389.18,
          "compare_at_price": 567.6,
          "sku_prices": [
            346.13,
...
            309.64,
            380.03
          ],
          "sku_weights": [
            1,
            1,
...
            2,
            2
          ],
          "sku_weight_units": [
            "kg"
          ],
          "total_inventory": 3269,
          "create_time": "2025-11-29T00:02:00",
          "update_time": "2025-12-20T00:01:41"
        }
      }
    ]
  }
}
```

---

## 9. 关键映射关系总结

### 9.1 类别映射

```
SPU.category_path ("1,2,3")
  ↓ [解析ID列表]
category_ids ["1", "2", "3"]
  ↓ [通过映射表转换]
category_names ["电子产品", "手机", "iPhone"]
  ↓ [构建字段]
category_path.zh: "电子产品/手机/iPhone"
category1_name: "电子产品"
category2_name: "手机"
category3_name: "iPhone"
```

### 9.2 SKU 和选项映射

```
Option 表 (position=1, name="颜色")
  ↓
option1_name: "颜色"

SKU 表 (option1="红色", option1="蓝色")
  ↓ [收集所有值，去重]
option1_values: ["红色", "蓝色"]

SKU 表 + Option 表
  ↓ [组合构建]
specifications: [
  {name: "颜色", value: "红色", sku_id: "123"},
  {name: "颜色", value: "蓝色", sku_id: "124"}
]
```

### 9.3 价格聚合

```
SKU 表 (price: 99.99, 109.99, 129.99)
  ↓ [聚合计算]
min_price: 99.99
max_price: 129.99
sku_prices: [99.99, 109.99, 129.99]
```

---

## 附录：数据表字段对照

### SPU 表主要字段

| 表字段 | ES 字段 | 说明 |
|--------|---------|------|
| `id` | `spu_id` | 商品ID |
| `tenant_id` | `tenant_id` | 租户ID |
| `title` | `title.zh/en` | 标题 |
| `brief` | `brief.zh/en` | 简介 |
| `description` | `description.zh/en` | 描述 |
| `vendor` | `vendor.zh/en` | 品牌 |
| `tags` | `tags` | 标签 |
| `category_path` | `category_path.zh` | 类目路径 |
| `category_id` | `category_id` | 类目ID |
| `category_level` | `category_level` | 类目层级 |
| `image_src` | `image_url` | 主图 |
| `fake_sales` | `sales` | 销量 |
| `create_time` | `create_time` | 创建时间 |
| `update_time` | `update_time` | 更新时间 |

### SKU 表主要字段

| 表字段 | ES 字段 | 说明 |
|--------|---------|------|
| `id` | `skus[].sku_id` | SKU ID |
| `price` | `skus[].price`, `min_price`, `max_price`, `sku_prices` | 价格 |
| `compare_at_price` | `skus[].compare_at_price`, `compare_at_price` | 原价 |
| `sku` | `skus[].sku_code` | SKU编码 |
| `inventory_quantity` | `skus[].stock`, `total_inventory` | 库存 |
| `weight` | `skus[].weight`, `sku_weights` | 重量 |
| `weight_unit` | `skus[].weight_unit`, `sku_weight_units` | 重量单位 |
| `option1` | `skus[].option1_value`, `option1_values`, `specifications[].value` | 选项1值 |
| `option2` | `skus[].option2_value`, `option2_values`, `specifications[].value` | 选项2值 |
| `option3` | `skus[].option3_value`, `option3_values`, `specifications[].value` | 选项3值 |
| `image_src` | `skus[].image_src` | SKU图片 |

### Option 表主要字段

| 表字段 | ES 字段 | 说明 |
|--------|---------|------|
| `position` | - | 位置（1/2/3） |
| `name` | `option1_name`, `option2_name`, `option3_name`, `specifications[].name` | 选项名称 |