feat: 开发采集、采集箱和商品编辑功能

2026-08-15 22:17:26 +08:00
parent c61d1a3154
commit 36357843d0
130 changed files with 18005 additions and 12 deletions
@@ -0,0 +1,124 @@
+# 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)