# V2.1 采集方案（扩展并入主仓 + 上报开关）

> 状态：已实施（Phase C 完成）
> 参考项目：`/Users/joey-xd/sites/seller-store/image-suite-studio`（下称 ISS）
> 架构（方案三，D2 决策修订）：**ISS 扩展整体并入主仓 `extensions/collector/`**，成为唯一采集工具
> （extension-v2 原地冻结、不再维护）；扩展新增「上报商品」功能，采集后一键入库主仓后台并自动打开商品试算页。
> 「ISS 独立产品化」远期通过构建/配置裁剪实现（扩展天然独立分发；server 的 suite API 模块不依赖 products），
> 不在代码层分叉——这是「单仓维护」与「独立产品可能」的折中。

---

## 1. 目录与形态

```
ozon-seller-kit/
├── extensions/               # Chrome 插件集合（复数，容纳未来多个插件）
│   └── collector/            ← ISS 扩展并入版（三平台采集 + 套图生图面板 + 商品上报）
├── extension-v1/             # 冻结（旧 1688/淘宝）
├── extension-v2/             # 冻结（旧 Ozon 采集，被 collector 取代）
├── server/                   # 唯一后端（8800）
└── studio/                   # 前端（试算页等）
```

- 构建：`pnpm -C extensions/collector build` → `.output/chrome-mv3`（Chrome 开发者模式加载 unpacked）
- 扩展包名：`ozon-collector-extension`；manifest 名保留「电商套图工作台」
- host_permissions 已加 `127.0.0.1:8800`（上报）与 `8900`（试算页）

## 2. 采集引擎（与 ISS 完全一致，见下表）

| 平台 | 主路径 | 兜底/补充 |
|---|---|---|
| **Ozon** | ① SSR `data-state` widget 白名单 | ② JSON-LD ③ 站内 `entrypoint-api.bx`（两 URL 合并）④ DOM + 模拟滚动 |
| **淘宝/天猫** | ① MAIN world 桥读 `__ICE_APP_CONTEXT__`（不调 mtop 防风控） | ② DOM（前缀匹配类名、详情图排除评价区；desc 故意不采） |
| **1688** | ① MAIN world 桥读 `window.context`（deepFind；skuProps 全维展开 + skuMapOriginal + 尺寸重量参数） | ② DOM（`#productAttributes` cells、`#detail`） |

采集数据结构 ScanResult：`{ platform, itemId, url, texts[], images[], breadcrumbs?, stats, warnings, source }`（texts: kind/content/pairs；images: groupKey/groupName/variantName/url/index/type）。

## 3. 商品上报（v2.1 新增）

```
快速采集（页内悬浮面板 / Side Panel）
   │  scanCurrentPage() → ScanResult（面板内可编辑标题/尺寸/重量/描述）
   ▼
「上报商品」按钮（01 商品信息区块下方；设置里可开关）
   │  POST {reportBaseUrl}/api/materials
   │  payload = { source: {platform, itemId, url, collectedAt},
   │              texts: editedTexts(),                       // 编辑后文本
   │              images: 全量采集图（groupKey/groupName/variantName/url/index/type）,
   │              refererOrigin: 源页 origin }                // 服务端下载源图带 Referer
   ▼
响应 { product_id } → chrome.tabs.create 打开 {studioBaseUrl}/trial/{product_id}
```

要点：
- **契约**：主仓 `MaterialsRequest`（camelCase：`source.itemId`、`groupKey`、`variantName`）与 ISS ImageMaterial 字段同名，直接映射；响应 `product_id` 用于打开试算页
- **重复上报**：服务端按 `platform + itemId` 复用商品（返回同一 product_id）→ 打开同一试算页
- **鉴权**：本地阶段主仓为宽松模式（未带 token 放行匿名），扩展直接裸调；远期收紧时在扩展 settings 加 token 即可
- **设置项**（面板「服务端设置」弹窗内新增）：启用商品上报开关 / OSK 后台地址（默认 `http://127.0.0.1:8800`）/ 试算页地址（默认 `http://localhost:8900`）
- 手动上传图（ISS 的 upload 组合）本期不上报；试算页内可用「上传图片」补（`/api/materials/bytes`）

## 4. 面板能力（保持 ISS 原样）

快速采集、商品信息编辑、图片勾选/上传/下载、AI 智能规划、风格/生图要求/模型选择、一键生图、生成结果导出——全部保留，仍连 ISS 生图 server（`baseUrl`，默认 3300）。
后续 Phase B 把生图服务端平移进主仓后，`baseUrl` 与 `reportBaseUrl` 可统一指向主仓。

## 5. 与 ISS 的差异总表

| 维度 | ISS（独立项目） | 本仓 extensions/collector |
|---|---|---|
| 采集引擎 | 三平台完整版 | 相同（整体并入） |
| 生图面板 | 连 ISS server（3300） | 同左（Phase B 后可切主仓） |
| 商品入库 | 无 | 「上报商品」→ 主仓 /api/materials + 自动打开试算页 |
| 鉴权 | 无 | 本地宽松模式（远期收紧） |
| 独立产品化 | 本体 | 远期：构建/配置裁剪出 collector + suite API 即可独立 |