# 电商套图工作台（image-suite-studio）

Chrome 插件 + Python 后端：采集 Ozon / 1688 / 淘宝 / 天猫 商品页的图片与信息（标题、描述、规格、尺寸），
基于采集素材**一键生成电商套图**（可设 5 种风格、7 种图类型、中英文案），生成后导出 ZIP。

参考并复用了 [ozon-seller-kit](../ozon-seller-kit) 的采集引擎（extension-v1/v2）与
[ecommerce-image-suite](../ecommerce-image-suite) 的生图 Prompt 架构。

## 架构

```
Chrome 插件（WXT + React + antd）          Python 后端（FastAPI，无数据库）
┌────────────────────────────┐            ┌──────────────────────────────┐
│ 页内悬浮面板                 │            │ POST /api/plan               │
│  ① 扫描商品页（四站点）      │ ─规划──▶ │   → DeepSeek 出图方案          │
│  ② 勾选/编辑素材            │ ◀─方案── │ POST /api/generate（无状态）   │
│  ③ 出图方案（默认/AI规划）    │ ──提交──▶ │   → 方案展开 → 逐张生图        │
│  ④ 轮询进度 → 导出 ZIP      │ ◀─轮询── │ GET  /api/suites/{id}[/zip]  │
└────────────────────────────┘            │ GET  /api/proxy-image        │
                                          └──────────────────────────────┘
```

### 任务与存储（无数据库设计）

- 生成任务存**进程内内存注册表**（`services/tasks.py`）：轮询/导出只服务当前会话正在跟踪的任务，
  重启即新会话（进行中任务中断，前端会提示"任务已中断，请重新生成"）—— 前端没有历史记录功能，
  任务状态无需跨进程持久化
- **串行生成队列**：所有用户共享同一批 API key，同一时间只跑一个任务，其余排队（pending），
  避免触发中转限流；多用户并发提交互不干扰（任务按 id 隔离，单实例部署）
- 图片本体全部落文件系统 `data/media/`（`/media` 静态托管），ZIP 导出直接读文件
- 接口暂无鉴权：公网暴露前需内网/反代白名单限制，登录鉴权后续版本补充；
  将来若需任务恢复/历史记录/多实例部署，再引入数据库（任务表结构简单，迁移成本低）

### 采集引擎（extension/src）

- 声明式 `SiteProfile`（选择器 + srcProps + 去重/排除规则），加站点只需加一个 profile：
  - `profiles/ozon.ts` — data-widget 选择器（DOM 兜底）
  - `profiles/1688.ts` — 多套画廊选择器变体 + CSS 背景图 SKU
  - `profiles/taobao.ts` — CSS Modules 前缀匹配，淘宝/天猫一份 profile
- 多路径采集（`collector/scan.ts` 统一编排）：
  - **Ozon**：SSR data-state（白名单）→ JSON-LD → 页面 JSON API → DOM，多源合并
  - **淘宝/天猫**：`window.__ICE_APP_CONTEXT__` SSR 主路径 + DOM 补充详情图
  - **1688**：纯 DOM（懒加载属性降级 + 占位图过滤 + 组内去重）
- 图片 URL 自动还原原图（阿里 `_400x400` 后缀 / Ozon `/wc\d+/` 路径段）

### 套图生成（server/services）

- `services/prompts/`：提示词按模型家族独立封装，`__init__.py` 按 (provider, model) 路由分发
  - `common.py`：商品上下文提炼、5 套风格模板、图内文案规范 TEXT_RENDER（家族共用）
  - `alibaba.py`：通义 wan*/qwen*（主体参考语义）；`doubao.py`：豆包（同语义，复用阿里装配）
  - `gpt.py`：gpt-image-2/-vip（`/v1/images/edits` 编辑语义，保真优先：商品只由 Image 1 定义，文字锚定仅作识别）
  - `google.py`：nano-banana 系列（原生主体保持语义）
  - 图类型：白底主图 / 核心卖点图 / 卖点图 / 材质图 / 场景展示图 / 多场景拼图 / 电商详情图 / 尺寸标注图 / SKU合集 / 创意图
  - 风格：北欧极简 / 清新明亮 / 高级感深色 / 暖调生活 / 纯净棚拍
  - 卖点从采集的参数表/卖点文本自动提炼
- `generator.py`：图像 provider（图生图，参考图 = 采集主图）
  - `doubao`：火山方舟 Seedream（默认，`ARK_API_KEY`）
  - `tongyi`：通义万相/千问（`DASHSCOPE_API_KEY`，wan* 异步轮询 / qwen* 同步）
  - `rightapi`：gpt-image-2 / gpt-image-2-vip / nano-banana / nano-banana-2 / nano-banana-2-lite / nano-banana-pro（OpenAI 兼容中转 `RIGHTAPI_API_KEY`，统一 `/v1/images/generations` 异步任务流，参考图走 JSON `image` data-URI 数组——见 `docs/rightapi-调用排查与修复方案.md`）
  - ⚠️ `gpt-image-2-vip` 为官逆通道：不透传保真参数、参考图被弱化，商品还原度不稳定（生成前有警示）；正式出图用 `gpt-image-2`
  - 插件只传模型名，服务端按模型名自动路由到对应 provider
- `watermark.py`：生成图水印（Pillow 后处理，AI 出图后、落盘前合成；插件「服务端设置」里开关，默认样式复刻 ozonSeller：图片圆形徽章 / 文字白字黑描边，右下角；预览与导出即所见）

## 快速开始

### 1. 后端

```bash
cd server
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 配置 API Key（二选一，豆包为默认）
cp ../.env.example ../.env
# 编辑 ../.env 填入 ARK_API_KEY 或 DASHSCOPE_API_KEY

python main.py   # http://127.0.0.1:3300
```

### 2. 插件

```bash
cd extension
pnpm install
pnpm build        # 产物在 .output/chrome-mv3
# Chrome → chrome://extensions → 开发者模式 → 加载已解压的扩展程序 → 选 .output/chrome-mv3
```

### 3. 使用

1. 打开 Ozon / 1688 / 淘宝 / 天猫 的**商品详情页**，滚动到底部（详情图懒加载），页面右下角出现「套」悬浮按钮
2. 点击悬浮按钮（或点击工具栏插件图标）→ 右侧滑出悬浮面板，悬浮在商品页上方、不挤压原页面
3. 面板内：扫描 → 检查/勾选素材（默认全选主图+SKU）→ 选择风格 / 图类型 / 文案语言 → 一键生成 → 完成后「导出 ZIP」
4. 收起面板：面板顶栏 ✕、Esc 或再点工具栏图标；同一页面内重新展开，状态保留

## API 一览

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/plan` | DeepSeek 出图方案规划（`{texts, sku_variants, image_stats, platform}`） |
| POST | `/api/generate` | 无状态一键生成（`{texts, images, plan, style_set, platform}`，不落商品库） |
| GET | `/api/suites/{id}` | 任务状态 + 已生成图 URL |
| GET | `/api/suites/{id}/zip` | 导出 ZIP（按方案标题命名） |
| POST | `/api/export-images` | 导出采集图片 ZIP（`{title, images}`，内部按分组名建文件夹） |
| GET | `/api/proxy-image?url=` | 图片代理（绕源站防盗链） |
| GET | `/api/health` | 健康检查 + provider 配置状态 |

## 说明与限制

- 单用户本地部署，未做鉴权（如需暴露公网请自行加 token 校验）
- 生图依赖付费 API（豆包 Seedream / 通义万相），任务逐张串行生成，一张约 10-60 秒
- 淘宝/天猫页面改版频繁，选择器失效时优先检查 `profiles/taobao.ts` 的 `[class*="xx--"]` 前缀
- 模特图（两阶段生成）与视频生成暂未实现，可参考 ecommerce-image-suite 后续扩展