ozon-seller-kit/docs/v2.1/README.md

# Ozon Seller Kit V2.1 方案总览（转向：放弃 API 直传，聚焦试算工作流）

> 状态：方案定稿 + 分阶段实施（Phase A 前端先行，进行中）
> 最后更新：2026-08-26
> 定位：本文是 V2.1 全部设计文档的入口与决策总表。先读本文，再按需读分册。
> 前置：`docs/v2/`（V2 方案）。V2.1 是对 V2 主链路的一次「降本转向」，不推翻 V2 的基础设施决策（数据库/存储/鉴权/工作台化）。

---

## 1. 背景与转向

V2 原定主链路是「采集 → 编辑 → **Ozon Seller API 直传发布**」。实施到发布环节发现：
ImportProductsV3 直传要求类目字典对齐、属性 id 映射（含 `is_aspect` 变体属性）、description_category_id/type_id 解析、
多变体合并规则、错误码逐条排查等大量细节字段对齐工作。对个人开发者而言实现成本过高、性价比不高。

V2.1 退而求其次，把主链路改为：

```
V2（原计划）                                  V2.1（现在）
采集 → 采集箱 → 编辑 → API 直传发布           采集 → 采集箱 → 商品试算页 → CSV 导出
                     ↑                              ↑
              大量 Ozon 字段对齐工作          人工在 Ozon 后台上品（粘贴/上传）
```

核心变化只有一条：**「上品」这一步从 API 自动化退回人工，把省下来的精力放在试算页的效率工具上**
（价格试算、俄文文案、AI 图片生成、采购地址维护、数据入库、CSV 导出）。
采集、采集箱、商品数据落库等 V2 已实现的基础全部保留。

---

## 2. 端到端数据流

```
① 浏览 Ozon / 1688 / 淘宝商详页
      │  插件页内悬浮面板 → 快速采集（采集方案以 image-suite-studio 为主要参考）
      ▼
② 插件 POST /api/materials 上传（texts + images，已实现）
      │  服务端落库为采集箱商品（stage=collected），异步下载转存图片
      ▼
③ 双动作（插件内完成）：
      ├─ a. 同步到采集箱（已在 ② 落库）
      └─ b. 自动打开商品试算页  {studio}/trial/{product_id}（新标签页）
      ▼
④ 商品试算页（studio 新页面，操作流水线对齐 web/ 工具台 v1）：
      ├─ 01 商品信息核对/补录（标题、重量、尺寸、描述、采买地址、货号）
      ├─ 02 价格试算（进货价/净利率/贴单费/物流等级/预留折扣/汇率 → 销售价 ¥/₽、利润、成本）
      ├─ 03 俄文文案生成（AI 标题/简介/标签，一键回填）
      ├─ 04 图片与 AI 生图（采集图勾选 → 套图规划 → 一键生成；单张 AI 图生图；导出）
      └─ 05 入库与导出（每步自动落库 product.pricing/copy；CSV / 组合码导出）
      ▼
⑤ 上品：人工在 Ozon 卖家后台录入，用 CSV / 组合码批量回填价格与货号
```

---

## 3. V2.1 决策总表（D 系列）

| 编号 | 决策 | 内容 | 理由 |
|---|---|---|---|
| **D1** | 放弃 Ozon API 直传 | `server/api/publish.py`、`services/publish.py`、店铺/类目代理等发布链路代码**保留但冻结**，不作为主链路；上品方式 = CSV 导出 + 人工后台录入 | ImportProductsV3 字段对齐工作量对个人不可承受；人工上品每品只花几分钟 |
| **D2** | 采集以 image-suite-studio 为主要参考 | 采集引擎（collector/profiles/平台文件）、页内悬浮面板 UI、三平台覆盖（Ozon/1688/淘宝天猫）全部以 `../image-suite-studio/extension` 的实现为准 | 该项目已跑通三平台商详页采集（Ozon 四路径降级 + 阿里系 MAIN-world 桥），且与本仓 extension-v2 同源，合并成本低 |
| **D3** | 采集完成双动作 | 上传 `/api/materials` 入库（已实现）+ 插件自动打开 `{studio}/trial/{product_id}` | 采集即进入试算流水线，减少手工跳转 |
| **D4** | 商品试算页 studio 化 | 新增 `/trial/:id` 页面，功能与操作流水线对齐 `web/ozonSeller.html`（计价/俄文文案/图片水印/采购地址/登记/CSV/组合码），数据从 localStorage 升级为 products 表落库 | web/ v1 已验证好用，冻结只读；studio 是其 React+antd 版本 |
| **D5** | 图片生成对齐 image-suite-studio | 套图规划（DeepSeek）→ 一键生成（多 provider 模型路由：豆包/通义/RightAPI）→ 服务端水印 → 导出 ZIP；生成图回写 `product_assets(generated)` | 套图能力已在 image-suite-studio 验证；服务端代码整体平移复用 |
| **D6** | 单张 AI 图生图 | 采集图与生成图的每个图片单元格都有「AI 生图」按钮：弹窗输入要求 + 选模型 → 单张生成 | 套图批量生成之外补充精修单图的能力 |
| **D7** | 前端先行 | 先开发试算页前端：服务层按本文 [`api.md`](./api.md) 契约编写；未实现的服务端接口以明确报错提示（不阻断页面其它功能），后再开发服务端 | 先把交互/流水线定型，服务端按前端契约补齐，避免返工 |
| **D8** | 存储沿用 V2 基础设施 | 商品/素材落 PostgreSQL（本地开发 SQLite），图片走 `services/storage.py` 抽象（本地 `data/media/` 兜底，七牛可选） | 不为转向重做存储；D1 冻结后七牛不再是硬依赖 |

---

## 4. 现状盘点（2026-08-26）

### 4.1 已实现、V2.1 直接复用

| 能力 | 位置 | 说明 |
|---|---|---|
| Ozon 采集上传落库 | `extension-v2/` + `server/api/collection.py` | `POST /api/materials`、`/api/materials/bytes`、去重、异步转存 |
| 采集箱 | `studio/src/pages/collection/CollectionPage.tsx` | 列表/筛选/删除/复制 |
| 商品 CRUD | `server/api/products.py` + `studio/src/services/product.ts` | 详情/PATCH 自动保存（raw/pricing/copy JSON 均可存） |
| 计价纯函数 | `studio/src/pricing/pricing.ts` | 从 web/app.js 抄录的核心公式（V2.1 需补尺寸校验等，见 trial-page.md） |
| 俄文文案 | `server/api/ai.py` + `studio/src/pages/product/CopyPanel.tsx` | `/api/ai/models`、`/api/ai/copy`，生成+回填交互完整 |
| 智能修图（万相） | `server/api/image.py` + `studio/src/pages/ai-image/` | `/api/image/edit` 保留，独立页面不动 |
| 汇率 | `server/api/fx.py` + `studio/src/services/fx.ts` | `GET /api/fx` |
| 素材上传（字节） | `server/api/collection.py:204` | `POST /api/materials/bytes`，试算页「上传图片」直接用 |
| 登录鉴权 | `server/api/auth.py` + studio RequireAuth | APP_TOKEN 换 JWT |

### 4.2 V2.1 待开发

| 能力 | 端 | 分册 |
|---|---|---|
| 商品试算页（5 区块） | studio 前端（**Phase A，本次**） | [`trial-page.md`](./trial-page.md) |
| 套图规划/一键生成/单张 AI 生图 前端 | studio 前端（**Phase A，本次**） | [`image-suite.md`](./image-suite.md) |
| suite 系列服务端接口（plan/generate/suites/image-edit/export） | server（Phase B） | [`api.md`](./api.md) |
| 采集对齐 image-suite-studio + 自动打开试算页 | extension-v2（Phase C） | [`collect.md`](./collect.md) |
| 批量 CSV 服务端导出（可选优化） | server（Phase D） | [`api.md`](./api.md) §7 |

### 4.3 冻结（不删代码，不再投入）

- Ozon 发布链路：`server/api/publish.py`、`server/services/publish.py`、`server/api/categories.py`、`server/services/ozon_client.py`
- studio 商品编辑页的「属性映射」「发布」区块（页面保留，作为长期能力储备）
- `docs/v2/ozon-publish.md`、`docs/v2/multi-sku.md` 的直传方案（远期若重启再参考）
- `web/` v1 工具台（继续冻结只读，直到试算页功能对齐后废弃）

---

## 5. 分册索引

| 文档 | 内容 | 什么时候读 |
|---|---|---|
| [`collect.md`](./collect.md) | 采集方案：以 image-suite-studio 为主要参考的引擎架构、三平台路径、采集后双动作、插件改造点 | 做插件（Phase C）时读 |
| [`trial-page.md`](./trial-page.md) | 商品试算页：页面结构、计价公式与校验、文案、采购地址、入库数据结构、CSV/组合码导出 | 做试算页前后端时读 |
| [`image-suite.md`](./image-suite.md) | 图片生成：套图规划→一键生成、模型路由、单张 AI 生图、水印、生成图回写与导出 | 做图片功能时读 |
| [`api.md`](./api.md) | 新增/复用的服务端 REST 契约（前端服务层已按此开发） | 前后端联调时读 |

---

## 6. 实施阶段

| 阶段 | 内容 | 状态 |
|---|---|---|
| **Phase A（本次）** | docs/v2.1 方案文档 + 试算页前端（路由/入口/5 区块/服务层契约） | ✅ 本次交付 |
| **Phase B** | 服务端：`/api/suite/*`、`/api/suites/*`、`/api/export/images`、`/api/proxy-image`（从 image-suite-studio/server 平移 generator/planner/prompts/watermark/tasks/storage） | 待开工 |
| **Phase C** | 插件：extension-v2 的 collector/profiles/面板对齐 image-suite-studio（补 1688/淘宝、页内悬浮面板），采集成功后自动打开 `/trial/{id}` | 待开工 |
| **Phase D** | 打磨：批量 CSV 服务端化、生成图自动回写素材、水印增强（拖动定位/白底处理评估移植 web v1 能力）、组合码批量导出优化 | 待开工 |

每个阶段结束都可独立运行：Phase A 结束时，试算页的计价/文案/素材上传/入库立即可用（对接已有接口），套图相关按钮点击会提示「服务端接口未实现」。

---

## 7. 与 V2 文档的关系

- V2 的基础设施决策（D1 契约云端化、D3 PostgreSQL、D6 工作台化、D7 鉴权）**全部沿用**。
- V2 的 D 图片方案 B（套图 + 智能修图）**升级落地**：套图引擎不再自研，直接平移 image-suite-studio 的服务端实现。
- V2 的发布链路（`ozon-publish.md`）**冻结**；`api.md` 中的 `/api/publish`、`/api/categories` 不再是主链路。
- 若存在分歧，以 `docs/v2.1/` 为准。

---

## 8. 关键风险

| 风险 | 级别 | 对策 |
|---|---|---|
| image-suite-studio 服务端是无状态内存任务表，重启丢任务 | 🟡 低 | 接受（与该项目建设一致）：图片落盘 storage 不丢，任务状态丢了重新生成即可；文档明示 |
| 采集图防盗链（Ozon/阿里 CDN）在 studio 页面直接展示可能失败 | 🟡 中 | 素材展示优先 `stored_url`（服务端已转存）；Phase B 补 `/api/proxy-image` 兜底 |
| 前端先行的契约与服务端实现不一致导致返工 | 🟡 中 | api.md 即契约真源，服务端按文档实现；字段命名对齐 image-suite-studio 已验证的结构 |
| CSV 人工上品仍是手工活 | 🟢 低 | 组合码 + CSV 已是 web/ 验证过的效率水平；后续可再评估半自动（表格粘贴）方案 |