feat: 开发采集、采集箱和商品编辑功能

2026-08-15 22:17:26 +08:00
parent c61d1a3154
commit 36357843d0
130 changed files with 18005 additions and 12 deletions
@@ -0,0 +1,138 @@
+# 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 → 复用现有发布链路。