Joey
140 lines
8.3 KiB
Markdown
140 lines
8.3 KiB
Markdown
# V2 落地计划与改动清单
|
||
|
||
> 状态：方案设计（待确认）
|
||
> 上游：[V2 总览](./README.md) · 其余各分册
|
||
|
||
---
|
||
|
||
## 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（采集插件）
|
||
|
||
1. 加 `src/messaging/`（`MessageMap` + client）与 `src/api/client.ts`（Bearer 鉴权，仅 background）。
|
||
2. `background.ts` 从「单个 fetchImage 分支」改为 handler 表路由；新增 `collect`/`product-*`/`health` 等消息。
|
||
3. options 页：后端地址 + Token + 「测试连接」。
|
||
4. sidepanel「导出到本地」旁边加「上传到服务端」：复用 `buildProduct()` 产物 → `POST /api/materials`。
|
||
5. 删除/降级 File System Access 写盘主路径（保留为可选本地备份）。
|
||
6. `SH_PENDING_QUEUE` 重试队列 + `GET /products/:id/fingerprints` 跨页去重接线（v2 已写 builder 但未读回比对）。
|
||
7. manifest 加后端域名 `host_permissions`。
|
||
|
||
> 详细契约沿用 `docs/extension/plan.md` §9/§13/§14，已在 `api.md` §2 落地。
|
||
|
||
### 2.2 server（服务端）
|
||
|
||
1. 依赖加：`sqlalchemy[asyncio]`、`asyncpg`、`alembic`、`qiniu`、`python-jose`(或 pyjwt)、`cryptography`。
|
||
2. 新增 `models/`、`migrations/`、`jobs/`（下载转存协程、发布轮询协程）。
|
||
3. 新增 api 文件：`collection/products/categories/shops/publish/export/fx/auth`。
|
||
4. 复用不改：`ai.py`/`image.py`/`deepseek.py`/`image_edit.py`/`models_catalog.py`（`image_edit.py` 加七牛转存一步）。
|
||
5. 新增 `services/ozon_client.py`（Ozon 通用调用）、`services/qiniu.py`（上传/下载转存）、`services/pricing.py`（把 v1 公式实现为服务端校验/计算，供「ready 校验」与 CSV）。
|
||
6. 鉴权中间件：JWT 校验 + `APP_TOKEN` 换发。
|
||
|
||
### 2.3 studio（工作台）
|
||
|
||
1. 菜单从单页扩为多页：`采集箱 / 商品编辑 / 发布 / 店铺 / 导出 / 智能修图（原 AI 图生图）`。
|
||
2. 新建 `pages/product/` 及子组件（PricingPanel/CopyPanel/ImagePanel/CategoryPicker/AttributeMapper/PublishPanel）。
|
||
3. 计价纯函数从 `web/js/app.js` **抄**进 `src/pricing/`（不改原文件），补单测锁定 v1 数值。
|
||
4. 文案面板复用 `/api/ai/copy`（参考 `web/js/ai-copy.js` 交互）。
|
||
5. 状态管理引入 zustand（编辑页跨面板共享）；axios 客户端对齐 `/api/*`。
|
||
6. 复用不动：`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` 新增项）
|
||
|
||
```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. 部署（腾讯云）
|
||
|
||
1. **资源**：轻量应用服务器 / CVM + CDB PostgreSQL + 七牛（域名需备案，Ozon 拉取的是公网 URL，务必用已备案域名）。
|
||
2. **应用**：`uvicorn main:app --app-dir server --host 127.0.0.1 --port 8800 --workers 2`，systemd 守护；nginx 反代 `/api`，托管 studio 构建产物。
|
||
3. **数据**：`alembic upgrade head`；`.env` 放服务器（不入 git）；`SECRET_KEY` 换环境时注意密文一致性（见 database.md §5）。
|
||
4. **七牛**：配置 bucket + 绑定 CDN 域名 + 证书；Ozon 服务器需能公网访问该域名。
|
||
5. **健康检查**：`/api/health`（含 DB ping）给运维探活。
|
||
|
||
---
|
||
|
||
## 6. 风险与对策
|
||
|
||
| 风险 | 级别 | 对策 |
|
||
|---|---|---|
|
||
| 属性映射工作量大、体验差 | 🔴 高 | 自动匹配 + 人工确认；先做基础版，迭代智能匹配 |
|
||
| Ozon 改版/限额/风控 | 🟡 中 | 采集端已有四路径 + 埋点热更；发布端错误透传 + 退避 |
|
||
| ecommerce-image-suite 集成是脚本非服务 | 🟡 中 | 抽 prompt 引擎为服务模块（image-strategy §5 L2） |
|
||
| 店铺密钥泄露 | 🔴 高 | AES-GCM 加密落库 + 前端打码 + 永不回显明文 + 日志脱敏 |
|
||
| 任务异步（下载/发布）状态不可见 | 🟡 中 | 素材/发布都有状态表 + 前端轮询回显 |
|
||
| 本地 → 云上环境不一致 | 🟡 中 | 十二要素：配置全走 `.env`，Alembic 管 schema |
|
||
|
||
---
|
||
|
||
## 7. 待确认项（开工前拍板）
|
||
|
||
1. ~~图片方案 A / B~~ ✅ **已定 B（高低搭配）**（2026-08-15，见 [`image-strategy.md`](./image-strategy.md) §8）。
|
||
2. **电商套图是否进一期**：建议一期先只交付「智能修图」跑通闭环，套图二期。
|
||
3. **单用户还是预留多用户**：schema 已按多用户预留，MVP 用 `APP_TOKEN` 即可。
|
||
4. **库存是否自动设置**：一期发布到「已创建/审核」，库存去后台补（或二期接 `/v2/products/stocks`）。
|
||
5. **数据库选型**：已定 PostgreSQL；若想更省事可换 SQLite（本地）→ 但 JSONB/并发/腾讯云部署建议直接用 PostgreSQL。
|