# Ozon Seller Kit V2 方案总览

> 状态：方案设计（待确认）
> 最后更新：2026-08-14
> 定位：本文是 V2 全部设计文档的入口与决策总表。先读本文，再按需读分册。

---

## 1. 一句话定位

V2 把 Ozon Seller Kit 从「**本地文件夹 + 单机工具**」升级为「**云端数据库 + 多店铺工作台**」：

```
V1（现状）                          V2（目标）
插件 ──写本地文件夹──> studio 读    插件 ──上传──> 服务端落库（采集箱）
                                    用户 ──> studio 工作台：看采集箱 → 编辑 → 发布
                                    服务端 ──> Ozon Seller API（多店铺）
                                    发布结果落库 → 支持 CSV 导出
```

核心变化只有一条：**契约真源从「磁盘上的商品文件夹」换成「数据库 + 七牛对象存储」**。本地文件夹不再承载主流程，降级为可选的导入/导出格式。

这是原架构文档（`docs/architecture.md` §7）里早已规划的 **S4 阶段**：商品库落库，本地文件夹降级。

---

## 2. 现状盘点（V1 资产）

| 部分 | 现状 | V2 处置 |
|---|---|---|
| `web/` 工具台 v1 | ✅ 在用（计价/登记/水印/俄文文案），冻结 | **只读**。计价公式、水印算法、文案交互被抄进 studio，不改原文件 |
| `extension-v1` | 1688/淘宝采集（SSR/DOM） | 保留为素材补充来源（二期） |
| `extension-v2` | Ozon 采集，**写本地文件夹**（File System Access） | 改造成**上传服务端落库**，删除本地写盘主路径 |
| `studio/` | React + antd，**仅「AI 图生图」一页**（wanx2.1-imageedit） | 扩为**多页工作台**：采集箱 / 商品编辑 / 发布 / 店铺 / 导出 |
| `server/` | FastAPI，无 DB，无 Ozon 对接；有 `/api/ai/*`、`/api/image/edit` | 加 DB + 七牛 + Ozon 对接 + 鉴权 + 异步任务 |

现状能力与可复用清单详见 [`capability-inventory.md`](./capability-inventory.md)（V2 设计输入稿）。

---

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

| 编号 | 决策 | 内容 | 理由 |
|---|---|---|---|
| **D1** | 契约云端化 | 商品数据落 **PostgreSQL**，图片落 **七牛**；本地文件夹降级为导入/导出格式 | 多设备、多店铺、可发布、可导出，单机文件夹做不到 |
| **D2** | 插件上传 | 插件采集结果走 `POST /api/materials` 上传落库，不再写本地 | 复用 `docs/extension/plan.md` §14 已定好的契约 |
| **D3** | 数据库选型 | PostgreSQL 16（腾讯云 CDB）+ SQLAlchemy 2.0 + Alembic | 单库覆盖结构化字段 + JSONB（attributes/raw），运维成熟 |
| **D4** | 图片存储 | 七牛云：源图由服务端代下转存，生成图也转存；Ozon 发布用七牛公网 URL | Ozon `images` 只收公网 URL（见 `architecture.md` §4） |
| **D5** | 图片方案 | **方案 B（高低搭配）✅ 已拍板**：集成 ecommerce-image-suite「电商套图」+ 保留 wanx2.1-imageedit（改名「智能修图」） | 二者是不同能力、共用 DASHSCOPE Key，互补不互斥；详见 [`image-strategy.md`](./image-strategy.md) |
| **D6** | 工作台化 | studio 从单页扩为：采集箱 → 商品编辑（计价+文案+图片+类目/属性）→ 发布 → 店铺 → 导出 | 对齐「采集 → 编辑 → 发布」主链路 |
| **D7** | 鉴权 | MVP 用长期 Bearer Token（单用户自用）；预留 `users` 表升级多用户 | 自用阶段不做 OAuth，与插件 options 页一致 |
| **D8** | 部署 | 腾讯云：FastAPI + nginx + PostgreSQL + 七牛；studio 静态托管；插件/前端指向公网后端 | 用户明确要部署腾讯云 |

---

## 4. 数据流（端到端）

```
① 浏览 Ozon 竞品页（或 1688/淘宝补素材）
      │  点插件 → 侧边栏 → 采集 → 勾选
      ▼
② 插件 POST /api/materials 上传（texts + images 的 URL + source）
      │  服务端立即落库为「采集箱商品」，异步排队下载源图 → 转存七牛
      ▼
③ studio「采集箱」列表：查看/筛选/删除商品
      │  进入商品编辑页
      ▼
④ 编辑：offer_id / 计价 / 俄文文案 / 图片（水印·智能修图·套图）/ 类目选择 / 属性映射
      │  每一步落库（Draft），可随时回来继续
      ▼
⑤ 发布：绑定店铺 → 服务端组装 ImportProductsV3 items[0] → POST /v3/product/import
      │  轮询 /v1/product/import/info 直到 imported / moderation / failed
      ▼
⑥ 落库：ozon_product_id / product_id / 状态 / 发布任务记录
      │
      ▼
⑦ CSV 导出：采集箱 + 已发布商品的字段导出（含 product_id 回填）
```

---

## 5. 分册索引

| 文档 | 内容 | 什么时候读 |
|---|---|---|
| [`architecture.md`](./architecture.md) | V2 总体架构：组件、技术栈、目录、鉴权、部署拓扑 | 先读这个，建立全局 |
| [`database.md`](./database.md) | PostgreSQL 表结构（按 Ozon 字段 + 采集/编辑/发布/店铺维度） | 做数据层时读 |
| [`api.md`](./api.md) | 后端 REST 接口契约（采集入库 / 商品 / 类目 / 店铺 / 发布 / 导出 / 图片 / 汇率） | 前后端联调时读 |
| [`image-strategy.md`](./image-strategy.md) | 图片处理：方案 A/B 对比、推荐、七牛存储、套图集成方式 | 图片这块没想明白时读 |
| [`ozon-publish.md`](./ozon-publish.md) | Ozon Seller API 集成：鉴权、店铺绑定、类目/属性、发布、任务状态、CSV 导出字段 | 做发布链路时读 |
| [`migration.md`](./migration.md) | 分阶段落地计划、改动点清单、风险 | 开工前读 |

---

## 6. 与 V1 文档的关系

- `docs/architecture.md`（V1 总架构）仍有效，V2 是其 **S4 阶段**的具体化；S1–S3 的结论（后端收进 `server/`、契约对齐 ImportProductsV3、`_` 前缀剥离、图床公网 URL 硬约束）全部沿用。
- `docs/contracts/product-json.md` 的**字段结构**在 V2 成为 `products` 表 + `product_assets` 表的设计蓝本；「文件夹」语义换成「商品记录」。
- `docs/extension/plan.md` §9/§13/§14 的**消息层、`/api/materials` 契约、鉴权、重试队列**在 V2 原样采纳，只把「写文件夹」换成「上传落库」。
- 若存在分歧，以 `docs/v2/` 为准。

---

## 7. 关键风险（先立 flag，细节见 migration.md）

| 风险 | 级别 | 对策 |
|---|---|---|
| Ozon 类目/属性字典大且需实时性 | 🟡 中 | 服务端缓存 + 按类目按需拉取，见 [`ozon-publish.md`](./ozon-publish.md) §3 |
| 采集属性 → Ozon 属性 id 的映射工作量大 | 🔴 高 | 自动匹配 + 人工确认 UI，见 `ozon-publish.md` §4 |
| ecommerce-image-suite 是「脚本+Skill」形态，非服务 | 🟡 中 | 把 generate.py 的 prompt 引擎抽成服务端能力，见 `image-strategy.md` §5 |
| 发布是异步（task_id 轮询），用户不能干等 | 🟡 中 | 任务表 + 轮询 + 状态回显，见 `ozon-publish.md` §5 |
| 密钥落库（店铺 Client-Id/Api-Key） | 🔴 高 | 服务端 AES 加密存储，前端永不回显明文，见 `database.md` §2.6 |