# V2 多 SKU（多变体）配置方案调研

> 状态：调研结论（待实现）
> 来源：Ozon Seller API 官方文档 + `reference/maozi-plugin-3.2.3`（毛子ERP 逆向）+ `reference/AI编辑 - 毛子ERP.html`

---

## 1. 结论一句话

Ozon 的多变体商品**不是"一个商品带多个 SKU 子结构"**，而是 **N 个独立商品（各自 `offer_id` / `product_id`），通过同一个「型号名称」属性（attribute id = `9048`）自动合并成一张卡**。变体之间的差异只能体现在「aspect 属性」（颜色/尺码等）上。

---

## 2. Ozon 官方机制

### 2.1 合并规则（官方文档原文）

`/v3/product/import` 文档明确写：

> To merge two product description pages, pass `9048` in the `attributes` array for each product. **All attributes except size or color must match** in these description pages.

即：

- 每个变体 = `items[]` 里的一个独立 item（独立 `offer_id`）。
- 每个 item 的 `attributes` 里都带上 `id=9048`（型号名称 / Название модели），且**值相同**。
- 除「尺寸/颜色」这类 aspect 属性外，其它属性必须完全一致。
- Ozon 会把同型号、仅 aspect 不同的商品**自动合并成一张带变体选择器的卡片**。

### 2.2 aspect 属性（`is_aspect`）

`/v1/description-category/attribute` 返回的属性里，`is_aspect=true` 表示该属性是「区分同型号商品的变体维度」（官方定义：颜色、尺码这类）。这就是多变体的"轴"：

- 变体轴 = 类目下 `is_aspect=true` 的属性（通常 `颜色`、`尺码`/`尺寸`）。
- 其它属性（品牌、材料、型号名称…）在各变体间必须一致。

### 2.3 每个变体的图片

- 主图 `images`：每个变体传自己的主图（通常是该 SKU 的图）。
- 采集端已支持"SKU 图带规格名"（`sku-001-синий.jpg`），正好一一对应。

---

## 3. 采集侧（毛子ERP 的 SKU 组合逻辑）

毛子ERP（1688 采集，`content-scripts/content.js` 里的 `生成SKU组合` 函数）的做法：

```
规格选项（颜色×尺寸…） × SKU详情 → 笛卡尔积 → 变体列表
  红色, 蓝色            M, L           红色-M, 红色-L, 蓝色-M, 蓝色-L
```

关键点：
1. 从 `webAspects` 拿到规格维度（aspect）+ 每个维度的可选值（含 SKU 图）。
2. 若有独立 SKU 详情（价格/图），做笛卡尔积；否则用默认价格 + 规格图。
3. 每个变体：`{ name: "红色-M", price, primary_image, sku }`。

对我们的映射：`webAspects` 采集回来的 `skuVariants`（已有 `variantName` + `image`）就是变体轴的数据源。

---

## 4. 发布侧（Ozon 多 SKU 实现方案）

### 4.1 数据模型

在现有 `products` 表基础上，多 SKU 用**一张卡对应多个 product 记录**来表示：

- 每个变体是一条 `products` 记录，`offer_id` 唯一。
- 变体间共享 `型号名称`（存 `raw.model_name`，映射到 attribute `9048`）。
- 变体差异在 `attributes`（aspect 属性填不同字典值）。

### 4.2 发布流程

```
① 主商品：确定类目 → 拉属性 → 找 is_aspect=true 的属性（如 颜色/尺码）
② 变体配置 UI：
     颜色 ▾ [红/蓝/绿]（字典值）
     尺码 ▾ [M/L/XL]（字典值）
     → 笛卡尔积生成变体列表（可编辑每个变体的 offer_id / 价格 / 主图）
③ 对每个变体，组装 items[i]：
     offer_id        = 变体自己的货号（如 SKU-001-RED-M）
     attributes      = 同型号名称(9048) + 变体自己的颜色/尺码字典值 + 其它共同属性
     images          = 变体自己的主图
④ 一次 /v3/product/import 提交所有变体（≤100 个 item）
⑤ 轮询回填每个变体的 product_id，Ozon 自动合并成一张卡
```

### 4.3 关键字段映射

| 概念 | 来源 | 落点 |
|---|---|---|
| 型号名称 | 编辑页「型号名称」输入 | `attributes[{id:9048, values:[{value}]}]` |
| 变体轴 | 类目 `is_aspect=true` 属性 | `attributes`（不同变体填不同 `dictionary_value_id`） |
| 变体货号 | 用户/自动 | 每个变体 `offer_id` |
| 变体图 | 采集 `skuVariants[].image` | 每个变体 `images[0]` |
| 共同属性 | 属性映射结果 | 每个变体相同 |

---

## 5. 待实现的 UI（studio 新增「SKU 配置」面板）

```
[型号名称] 儿童保温杯 316
[变体维度] 颜色（字典下拉，多选） [红][蓝][绿]
          尺码（字典下拉，多选） [M][L][XL]
[生成变体] ← 笛卡尔积
┌──────────────────────────────────────────────┐
│ 颜色  尺码  货号          价格   主图          │
│ 红    M    SKU-001-RED-M  [  ]  [图]         │
│ 红    L    SKU-001-RED-L  [  ]  [图]         │
│ 蓝    M    SKU-001-BLU-M  [  ]  [图]         │
│ …                                           │
└──────────────────────────────────────────────┘
[保存变体] → 生成 N 条 products 记录（或发布时展开）
```

实现上两种选择：
- **A. 落库展开**：保存时直接生成 N 条 `products`（每个变体一条），发布时各自提交。
- **B. 发布时展开**：主商品存一份变体配置 JSON，发布时动态展开成 N 个 item 提交。

建议 **A**（落库展开）——与现有"采集箱 → 单商品编辑 → 发布"链路一致，每个变体可独立查看/编辑/重发。

---

## 6. 注意点

1. **变体必须同型号**：`9048` 值必须完全一致，否则 Ozon 不合并，会生成 N 张独立卡片。
2. **非 aspect 属性必须一致**：品牌/材料/描述等若不同，Ozon 拒绝合并。
3. **变体图数量**：每个变体各自 ≤15 张主图；`skuVariants` 采集的规格图作为变体主图候选。
4. **`complex_attributes` 不是用来做 SKU 的**：它用于视频/尺码表等富内容，别混用。
5. **单次 ≤100 item**：变体数超过 100 需分批提交。

---

## 7. 结论

- 多 SKU = **同型号名称(9048) + aspect 属性区分 + 多 product 记录**，靠 Ozon 自动合并，无需额外的"组合商品" API。
- 采集端已具备变体轴数据（`webAspects` 的 `skuVariants`），发布端只需一个「变体配置 + 展开提交」的 UI 即可落地。
- 推荐实现路径：studio 增加「SKU 配置」面板 → 落库展开为多条 product → 复用现有发布链路。