# Ozon Seller Kit - Ozon 采集插件（extension-v2）

采集 Ozon 商品页信息（标题 / 价格 / 参数 / 卖点 / 描述 / 图片 / 视频）到本地商品文件夹。

参考实现：`reference/maozi-plugin-3.2.3`（毛子ERP，Ozon 跟卖插件）。本项目按其采集思路，
落成本仓库 `docs/` 已经定下的「纯采集器 + 本地商品文件夹」架构（见 `docs/contracts/product-json.md`）。

## 与毛子ERP 的对应关系

| 毛子ERP 做法 | 本插件实现 |
|---|---|
| 请求 Ozon 内部页 JSON 接口 `entrypoint-api.bx/page/json/v2` | ✅ `src/collector/ozon-api.ts`（只收画廊 widget 的图）|
| 解析 `application/ld+json` 结构化数据 | ✅ `src/collector/jsonld.ts` |
| DOM `data-widget` 区块选择器 | ✅ `src/profiles/ozon.ts`（兜底 + 详情图补充）|
| —（Ozon SSR 页面自带 widget data-state） | ✅ `src/collector/ozon-state.ts`（★ 主路径，白名单）|
| 上传到毛子云后端 | ❌ 改为写本地商品文件夹（架构决策 D3/R1）|
| 登录 / AI / 跟卖工作流 | ❌ 不实现，插件只做采集 |

## 快速开始

```bash
cd extension-v2
pnpm install
pnpm dev          # 或 pnpm build 出 .output/chrome-mv3
```

然后：
1. 打开 `chrome://extensions/`
2. 开启「开发者模式」
3. 「加载已解压的扩展程序」→ 选择 `extension-v2/.output/chrome-mv3`

## 使用

1. 打开任意 Ozon 商品详情页（`ozon.ru` / `ozon.kz` / `ozon.by`）
2. 滚动到页面底部，让详情图完成懒加载
3. 点扩展图标 → 侧边栏打开
4. 「选择保存目录」（仅首次，之后自动记住）
5. 「开始采集当前页」→ 核对结果、勾选图片
6. 「导出到本地」→ 生成商品文件夹

## 采集路径（四路径降级）

```
① SSR widget state（DOM data-state 属性）── 主路径，同步、白名单、无需网络
   webGallery / webPrice / webProductHeading / webShortCharacteristics / webAspects …
        │ 缺失
        ▼
② JSON-LD（schema.org/Product）── 标准化，稳定（标题/品牌/价格/评分）
        │ 缺失
        ▼
③ Ozon 页 JSON API（entrypoint-api.bx）── 补充完整参数表与富文本描述
        │ 缺失
        ▼
④ DOM 选择器（data-widget 区块）── 兜底 + 详情图补充
```

★ **「为您推荐 / 一起购买」等其它商品 carousel 的图片不会被采集**：
- ① 只读白名单 widget（webGallery / webAspects 等）的 data-state，绝不遍历全页；
- ③ 只从画廊类 widget 收图片，不递归整个 widgetStates（旧版 bug 所在）；
- ④ DOM 选择器按 data-widget 区块作用域限定。

## 目录结构

```
extension-v2/
├── entrypoints/
│   ├── background.ts            # 图片代理 fetch（绕 CORS / 防盗链）
│   ├── sidepanel/               # 采集控制 UI
│   └── content/index.ts         # 注入商品页，暴露采集入口
├── src/
│   ├── profiles/                # ozon.ts（DOM 选择器 + URL/CDN 规则）
│   ├── collector/               # 采集引擎
│   │   ├── ozon-state.ts        # ★ SSR data-state 提取（主路径，白名单）
│   │   ├── jsonld.ts            # JSON-LD 提取
│   │   ├── ozon-api.ts          # Ozon 页 JSON API（只收画廊 widget 的图）
│   │   ├── scan.ts              # scanCurrentPage() 入口（四路径编排）
│   │   ├── image.ts / text.ts / dom.ts / url.ts
│   ├── export/                  # builder / filesystem / idb
│   └── schema/product.ts        # product.json 契约（TS 侧）
├── scripts/verify-pages.ts      # 用 reference/ozon*.html 验证采集逻辑
├── wxt.config.ts
└── package.json
```

## Console 调试

在 Ozon 商品详情页的 Console 里执行：

```js
const r = await window.__SellerHelperOzon.scan();
console.table(r.texts);
console.table(r.images);
console.log('stats:', r.stats, 'warnings:', r.warnings, 'source:', r.source);
```

## 验证

`scripts/verify-pages.ts` 用真实保存的页面（`reference/ozon1.html`、`ozon2.html`）
跑采集逻辑，覆盖：标题 / 价格 / 评分 / 画廊原图 / SKU 变体（图+名）/ 参数表 /
URL 还原（/wc\d+/、/c\d+/ 尺寸标记 → 原图）/ 缩略图生成。

```bash
# 从 extension-v2 目录
node_modules/.pnpm/esbuild@0.25.12/node_modules/esbuild/bin/esbuild \
  scripts/verify-pages.ts --bundle --platform=node --format=esm --outfile=/tmp/verify.mjs
node /tmp/verify.mjs
```

## 当前状态与已知限制

- ✅ 四路径采集引擎（SSR state / JSON-LD / API / DOM），选择器已在真实页面核实
- ✅ 「为您推荐 / 一起购买」等其它商品图片已排除（白名单 + 画廊 widget 限定）
- ✅ Side Panel UI（分组预览、勾选、文件夹名、写盘进度）
- ✅ File System Access 写本地商品文件夹（product.json + sources.json + images/）
- ✅ 图片 CDN 域名（ir.ozone.ru / io.ozone.ru / v-1.ozone.ru / cdn1.ozonusercontent.com）已加入 host_permissions
- ⚠️ 详情图（webDescription 区）在静态快照里没有，需滚动到底部后由 DOM 补充
- ⚠️ 完整参数表（>5 项）走 API 补充，若 API 被风控则只有前 5 项（webShortCharacteristics）

## 相关文档

- [总体架构](../../docs/architecture.md)
- [商品文件夹契约](../../docs/contracts/product-json.md)
- [插件方案（含毛子ERP 逆向分析）](../../docs/extension/plan.md)
- [插件方案修正（Ozon 优先）](../../docs/extension/plan-revision.md)