V2 落地计划与改动清单

状态：方案设计（待确认）上游：V2 总览 · 其余各分册

1. 分阶段里程碑（建议顺序）

每个里程碑都可独立验收，且不破坏 V1 正在用的部分。

#	里程碑	内容	产出/验收	估时
M0	数据层与骨架	建 DB + SQLAlchemy 模型 + Alembic 首迁移；`/api/health` 接 DB；`.env` 加 `DATABASE_URL`/`APP_TOKEN`/`SECRET_KEY`/`QINIU_*`	服务能连库、能 `alembic upgrade`	1d
M1	插件上传落库	extension-v2 加消息层 + api client + options；`POST /api/materials` + 素材下载转存七牛（后台协程）	插件点「上传」，采集箱能看到商品与图	2d
M2	采集箱列表 + 商品编辑骨架	studio 加「采集箱」页 + 「商品编辑」页（表单 + autosave 落库）；计价面板（抄 v1 公式）；文案面板（接 `/api/ai/copy`）	能看采集箱、编辑保存、算价、生成文案	3d
M3	图片：智能修图 + 七牛	`/api/image/edit` 加七牛转存；编辑页图片面板（水印沿用 canvas + 智能修图入口）	图片能转存七牛、能白底/去水印	1d
M4	店铺 + 类目 + 属性	`shops` CRUD + 连通校验；`/api/categories/*` 代理 + 缓存；属性映射 UI	能绑店铺、选类目、映射属性	3d
M5	发布链路	`POST /products/:id/publish` + 组装 items[0] + 轮询回填 + 发布结果页	商品成功进 Ozon 后台，product_id 回填	2d
M6	CSV 导出 + 打磨	`/api/export/products.csv` + 导出页；错误处理/限流/日志	能导出 CSV	1d
M7	部署腾讯云	nginx + systemd + PostgreSQL + 七牛配置；插件/studio 指向公网	公网可访问，闭环	1d
M8	（二期）电商套图	集成 ecommerce-image-suite（`/api/image/suite`）；俄文 Prompt	按方案 B 决策而定	2~3d

M2/M4 是最大的两块（编辑页 + 属性映射），也是最值得先用静态样例打磨 UI 的部分。

2. 各端改动清单

2.1 extension-v2（采集插件）

加 src/messaging/（MessageMap + client）与 src/api/client.ts（Bearer 鉴权，仅 background）。
background.ts 从「单个 fetchImage 分支」改为 handler 表路由；新增 collect/product-*/health 等消息。
options 页：后端地址 + Token + 「测试连接」。
sidepanel「导出到本地」旁边加「上传到服务端」：复用 buildProduct() 产物 → POST /api/materials。
删除/降级 File System Access 写盘主路径（保留为可选本地备份）。
SH_PENDING_QUEUE 重试队列 + GET /products/:id/fingerprints 跨页去重接线（v2 已写 builder 但未读回比对）。
manifest 加后端域名 host_permissions。

详细契约沿用 docs/extension/plan.md §9/§13/§14，已在 api.md §2 落地。

2.2 server（服务端）

依赖加：sqlalchemy[asyncio]、asyncpg、alembic、qiniu、python-jose(或 pyjwt)、cryptography。
新增 models/、migrations/、jobs/（下载转存协程、发布轮询协程）。
新增 api 文件：collection/products/categories/shops/publish/export/fx/auth。
复用不改：ai.py/image.py/deepseek.py/image_edit.py/models_catalog.py（image_edit.py 加七牛转存一步）。
新增 services/ozon_client.py（Ozon 通用调用）、services/qiniu.py（上传/下载转存）、services/pricing.py（把 v1 公式实现为服务端校验/计算，供「ready 校验」与 CSV）。
鉴权中间件：JWT 校验 + APP_TOKEN 换发。

2.3 studio（工作台）

菜单从单页扩为多页：采集箱 / 商品编辑 / 发布 / 店铺 / 导出 / 智能修图（原 AI 图生图）。
新建 pages/product/ 及子组件（PricingPanel/CopyPanel/ImagePanel/CategoryPicker/AttributeMapper/PublishPanel）。
计价纯函数从 web/js/app.js 抄进 src/pricing/（不改原文件），补单测锁定 v1 数值。
文案面板复用 /api/ai/copy（参考 web/js/ai-copy.js 交互）。
状态管理引入 zustand（编辑页跨面板共享）；axios 客户端对齐 /api/*。
复用不动：utils/watermark.ts、annotation.ts、image.ts、布局壳、AiImagePage（改名「智能修图」）。

2.4 web（v1 工具台）

冻结，零改动。只被读（抄公式、抄文案交互）。

3. 计价公式迁移（v1 → 服务端 + studio）

来源：web/js/app.js（calculateLogisticsFee / calculateAndDisplay / validateDimensions / validateLogisticsLevel / validatePriceRange / updateDerivedPrices）。

迁移方式：

studio 侧：抽成 TS 纯函数（输入字段 + 汇率 + 预留% → 输出全部结果字段），展示在编辑页计价面板。
server 侧：抽成 services/pricing.py（同样公式的 Python 版），用于「ready 校验」、products.price 最终写入、CSV 导出的一致性。

为什么两端各一份：计价是高频纯前端交互（实时算），不需要每次走后端；但发布前校验和导出需要服务端有权威结果。约定：以服务端 services/pricing.py 为真源，前端 TS 版照抄并对齐，用同一组 fixture 测两端一致性（沿用 V1 契约测试思路）。

关键常量（照抄不改）：

项	值
物流费	low/high/high2 三档 × 两重量段（公式见 app.js:959）
净到手比例 netRate	low=0.845；high/high2=0.785
完全抽成	15.5%（low）/ 21.5%（其他），含约 3.5% 其它费
汇率源	FloatRates → 俄央行 → er-api，5~25 区间过滤，兜底 11.5
预留折扣	默认 50%，0~95

4. 配置（`.env` 新增项）

# 现有
DEEPSEEK_API_KEY=…
DASHSCOPE_API_KEY=…
# V2 新增
APP_TOKEN=…                 # 单用户登录 token（MVP）
SECRET_KEY=…                # 店铺凭证 AES-GCM 加密密钥
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/ozon_seller
# 七牛
QINIU_ACCESS_KEY=…
QINIU_SECRET_KEY=…
QINIU_BUCKET=…
QINIU_DOMAIN=https://cdn.example.com   # 七牛绑定域名（Ozon 拉取用）
APP_BASE_URL=https://api.example.com   # 插件/studio 回写、生成图回调用

.env.example 同步补占位并注释。

5. 部署（腾讯云）

资源：轻量应用服务器 / CVM + CDB PostgreSQL + 七牛（域名需备案，Ozon 拉取的是公网 URL，务必用已备案域名）。
应用：uvicorn main:app --app-dir server --host 127.0.0.1 --port 8800 --workers 2，systemd 守护；nginx 反代 /api，托管 studio 构建产物。
数据：alembic upgrade head；.env 放服务器（不入 git）；SECRET_KEY 换环境时注意密文一致性（见 database.md §5）。
七牛：配置 bucket + 绑定 CDN 域名 + 证书；Ozon 服务器需能公网访问该域名。
健康检查：/api/health（含 DB ping）给运维探活。

6. 风险与对策

风险	级别	对策
属性映射工作量大、体验差	🔴 高	自动匹配 + 人工确认；先做基础版，迭代智能匹配
Ozon 改版/限额/风控	🟡 中	采集端已有四路径 + 埋点热更；发布端错误透传 + 退避
ecommerce-image-suite 集成是脚本非服务	🟡 中	抽 prompt 引擎为服务模块（image-strategy §5 L2）
店铺密钥泄露	🔴 高	AES-GCM 加密落库 + 前端打码 + 永不回显明文 + 日志脱敏
任务异步（下载/发布）状态不可见	🟡 中	素材/发布都有状态表 + 前端轮询回显
本地 → 云上环境不一致	🟡 中	十二要素：配置全走 `.env`，Alembic 管 schema

7. 待确认项（开工前拍板）

~~图片方案 A / B~~ ✅ 已定 B（高低搭配）（2026-08-15，见 image-strategy.md §8）。
电商套图是否进一期：建议一期先只交付「智能修图」跑通闭环，套图二期。
单用户还是预留多用户：schema 已按多用户预留，MVP 用 APP_TOKEN 即可。
库存是否自动设置：一期发布到「已创建/审核」，库存去后台补（或二期接 /v2/products/stocks）。
数据库选型：已定 PostgreSQL；若想更省事可换 SQLite（本地）→ 但 JSONB/并发/腾讯云部署建议直接用 PostgreSQL。

8.3 KiB Raw Permalink Blame History Unescape Escape