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（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`
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`	V2 总体架构：组件、技术栈、目录、鉴权、部署拓扑	先读这个，建立全局
`database.md`	PostgreSQL 表结构（按 Ozon 字段 + 采集/编辑/发布/店铺维度）	做数据层时读
`api.md`	后端 REST 接口契约（采集入库 / 商品 / 类目 / 店铺 / 发布 / 导出 / 图片 / 汇率）	前后端联调时读
`image-strategy.md`	图片处理：方案 A/B 对比、推荐、七牛存储、套图集成方式	图片这块没想明白时读
`ozon-publish.md`	Ozon Seller API 集成：鉴权、店铺绑定、类目/属性、发布、任务状态、CSV 导出字段	做发布链路时读
`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` §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

README.md Unescape Escape

Ozon Seller Kit V2 方案总览

1. 一句话定位

2. 现状盘点（V1 资产）

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

4. 数据流（端到端）

5. 分册索引

6. 与 V1 文档的关系

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

README.md