Joey
125 lines
5.5 KiB
Markdown
125 lines
5.5 KiB
Markdown
# 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)
|