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` 契约编写；未实现的服务端接口以明确报错提示（不阻断页面其它功能），后再开发服务端	先把交互/流水线定型，服务端按前端契约补齐，避免返工
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`
套图规划/一键生成/单张 AI 生图前端	studio 前端（Phase A，本次）	`image-suite.md`
suite 系列服务端接口（plan/generate/suites/image-edit/export）	server（Phase B）	`api.md`
采集对齐 image-suite-studio + 自动打开试算页	extension-v2（Phase C）	`collect.md`
批量 CSV 服务端导出（可选优化）	server（Phase D）	`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`	采集方案：以 image-suite-studio 为主要参考的引擎架构、三平台路径、采集后双动作、插件改造点	做插件（Phase C）时读
`trial-page.md`	商品试算页：页面结构、计价公式与校验、文案、采购地址、入库数据结构、CSV/组合码导出	做试算页前后端时读
`image-suite.md`	图片生成：套图规划→一键生成、模型路由、单张 AI 生图、水印、生成图回写与导出	做图片功能时读
`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/ 验证过的效率水平；后续可再评估半自动（表格粘贴）方案

10 KiB Raw Permalink Blame History Unescape Escape