# 1688/淘宝采集插件实施计划

> 优先级调整：Ozon 后置，先做 1688/淘宝
> 理由：1688 选择器有生产验证基础，可先跑通引擎；淘宝同属阿里系，复用度高
> 上游：[总体架构](../architecture.md) · [插件原方案](./plan.md) · [方案修正](./plan-revision.md)

---

## 1. 为什么先做 1688/淘宝

| 维度 | 1688/淘宝 | Ozon |
|---|---|---|
| 选择器来源 | v1.1.8 生产 bundle 反编译，已验证 | 需实测，哈希类名随时失效 |
| 技术难度 | 中（同源复用多） | 高（React SSR + 选择器未知） |
| 调试价值 | 可作引擎基准——跑通后 Ozon 采不到就一定是选择器问题 | 选择器和引擎同时调，歧义大 |
| 业务价值 | 补素材（1688 图多） | 跟卖（第一优先级但技术难） |

**策略**：先用 1688 跑通引擎和 File System Access 写盘，再用它诊断 Ozon 的选择器问题。

---

## 2. 淘宝 Profile 设计

### 2.1 与 1688 的共同点

| 项 | 共享原因 |
|---|---|
| CDN 规则 | 都是 `xxx.jpg_400x400.jpg` 后缀，`getOriginalImageUrl` 通用 |
| 懒加载 | `data-lazyload-src` / `data-src` 优先级相同 |
| SKU 背景图 | 都用 `backgroundImage` 取 SKU 缩略图 |
| 参数表结构 | `<dl>` 嵌套 `<dt>` `<dd>`，解析逻辑相同 |

可以抽一个 `profiles/alibaba-common.ts` 存共享工具。

### 2.2 淘宝特有选择器

**URL 匹配**：
```ts
urlPatterns: [
  /^https:\/\/item\.taobao\.com\/item\.htm\?id=\d+/,
  /^https:\/\/detail\.tmall\.com\/item\.htm\?id=\d+/  // 天猫
]

extractItemId: (url) => {
  const m = url.match(/[?&]id=(\d+)/);
  return m?.[1] ?? null;
}
```

**就绪选择器**（淘宝用 React 16，水合较快）：
```ts
readySelectors: [
  '[class*="ItemHeader"]',     // 标题区
  '[class*="MainPic"]',        // 主图画廊
  '[class*="SkuSelector"]'     // SKU 选择器
]
```

**文本规则**：
```ts
textRules: [
  {
    kind: 'title',
    selectors: [
      '[class*="ItemHeader--title"]',
      '.tb-detail-hd h1',
      'h1[data-spm="1000983"]'   // 旧版
    ],
    extract: 'first',
    required: true
  },
  {
    kind: 'price',
    selectors: [
      '[class*="Price--priceText"]',
      '.tb-rmb-num',
      '[class*="priceInt"]'
    ],
    extract: 'first'
  },
  {
    kind: 'params',
    selectors: [
      '[class*="Attributes"] dl',
      '#attributes .tm-clear',
      '.attributes-list dl'
    ],
    extract: 'table',
    tableKeySelector: 'dt',
    tableValueSelector: 'dd'
  }
]
```

**图片规则**：
```ts
imageGroups: [
  {
    key: 'main',
    name: '主图',
    type: 'img',
    selectors: [
      '[class*="MainPic"] img',        // React 版
      '#J_ImgBooth img',               // 旧版画廊
      '.tb-booth img'
    ],
    minWidth: 200,
    minHeight: 200
  },
  {
    key: 'sku',
    name: 'SKU图片',
    type: 'img',
    selectors: [
      '[class*="SkuSelector"] li',     // React 版
      '.tb-img li',                    // 旧版
      '[class*="skuItem"]'
    ],
    srcProps: ['backgroundImage'],     // 与 1688 同
    nameSelectors: ['span', '.value'], // 规格名
    minWidth: 20,
    minHeight: 20
  },
  {
    key: 'detail',
    name: '详情图',
    type: 'img',
    selectors: [
      '#description img',
      '[class*="Description"] img',
      '.detail-content img'
    ],
    minWidth: 300,
    minHeight: 100
  }
]
```

### 2.3 淘宝特殊处理

**动态详情图**：淘宝详情常用懒加载模块，需滚动触发。侧边栏提示同 Ozon：
```
⚠️ 详情图为 0，请滚动到页面底部后重新采集
```

**天猫 vs 淘宝 C 店**：URL 模式不同但 DOM 结构相似，用同一份 profile 即可。主要差异在类名前缀（`tm-` vs `tb-`），多写几套选择器兜底。

---

## 3. 更新后的里程碑

| # | 内容 | 工作量 | 产出 |
|---|---|---|---|
| **M1** | WXT 项目初始化 | 0.5h | extension/ 目录就位，能 dev |
| **M2** | 核心类型与工具 | 1h | profiles/types + collector/url + product.json TS 类型 |
| **M3** | 1688 profile + 采集引擎 | 3h | 能在 1688 页面 console 里跑 `scanCurrentPage()` |
| **M4** | 淘宝 profile | 1h | 同上，淘宝页面可用 |
| **M5** | Side Panel UI（基础） | 2h | 分组展示采集结果，勾选图片 |
| **M6** | File System Access 写盘 | 2h | 生成完整商品文件夹到本地 |
| **M7** | sources.json 去重 | 1h | 二次采集追加不重复 |
| **M8** | 淘宝实测与修正 | 1h | 在真实页面上跑，修选择器 |

**总计 11.5 小时**。M3 结束时引擎已可用，M6 结束时完整流程跑通。

---

## 4. 目录结构（实际代码）

```
extension/
├── wxt.config.ts
├── package.json
├── entrypoints/
│   ├── background.ts            # 图片代理 fetch（绕 CORS）
│   ├── sidepanel/
│   │   ├── index.html
│   │   └── App.tsx              # 采集控制 UI
│   └── content/
│       └── index.ts             # 注入页面，触发采集
│
├── src/
│   ├── profiles/
│   │   ├── types.ts             # SiteProfile / TextRule / ImageGroupRule
│   │   ├── alibaba-common.ts    # 阿里系共享工具（URL / CDN）
│   │   ├── 1688.ts              # ← 从 plan.md §6.2 移植
│   │   ├── taobao.ts            # ← 上面 §2.2 设计
│   │   └── index.ts             # matchProfile(url) 路由
│   │
│   ├── collector/
│   │   ├── scan.ts              # scanCurrentPage() 入口
│   │   ├── text.ts              # 文本提取
│   │   ├── image.ts             # 图片提取 + 分组
│   │   ├── url.ts               # ← 从 plan.md §6.3 移植
│   │   ├── dom.ts               # waitForAny / onUrlChange
│   │   └── dedupe.ts            # dedupeKey()
│   │
│   ├── export/
│   │   ├── filesystem.ts        # File System Access API 封装
│   │   ├── builder.ts           # 构建 product.json / sources.json
│   │   └── images.ts            # 图片写盘（调 background 代理）
│   │
│   ├── storage/
│   │   ├── keys.ts              # SH_ROOT_DIR / SH_CURRENT_FOLDER
│   │   └── settings.ts          # 配置读写
│   │
│   └── schema/
│       └── product.ts           # ProductJson / SourcesJson TS 类型
│
└── components/                  # Side Panel UI 组件
    ├── ScanResult.tsx           # 采集结果展示
    ├── ImagePicker.tsx          # 分组图片勾选
    └── FolderSelector.tsx       # 文件夹选择/新建
```

---

## 5. 关键技术点

### 5.1 File System Access API 核心代码

```ts
// src/export/filesystem.ts

let rootDirHandle: FileSystemDirectoryHandle | null = null;

export async function selectRootDir(): Promise<void> {
  rootDirHandle = await window.showDirectoryPicker({ mode: 'readwrite' });
  // 持久化到 IndexedDB（WXT 有 storage.defineItem 封装）
  await storage.setItem('local:SH_ROOT_DIR', rootDirHandle);
}

export async function ensureRootDir(): Promise<FileSystemDirectoryHandle> {
  if (!rootDirHandle) {
    rootDirHandle = await storage.getItem('local:SH_ROOT_DIR');
  }
  if (!rootDirHandle) {
    throw new Error('请先选择保存目录');
  }
  // 验证权限
  if (await rootDirHandle.queryPermission({ mode: 'readwrite' }) !== 'granted') {
    await rootDirHandle.requestPermission({ mode: 'readwrite' });
  }
  return rootDirHandle;
}

export async function writeProductFolder(
  folderName: string,
  data: {
    product: ProductJson;
    sources: SourcesJson;
    images: Array<{ file: string; blob: Blob }>;
  }
): Promise<void> {
  const root = await ensureRootDir();
  const productDir = await root.getDirectoryHandle(folderName, { create: true });

  // 写 product.json
  const productFile = await productDir.getFileHandle('product.json', { create: true });
  const w1 = await productFile.createWritable();
  await w1.write(JSON.stringify(data.product, null, 2));
  await w1.close();

  // 写 sources.json
  const sourcesFile = await productDir.getFileHandle('sources.json', { create: true });
  const w2 = await sourcesFile.createWritable();
  await w2.write(JSON.stringify(data.sources, null, 2));
  await w2.close();

  // 写图片（分组到子目录）
  const imagesDir = await productDir.getDirectoryHandle('images', { create: true });
  for (const img of data.images) {
    const [group] = img.file.split('/');  // "main/main-001.jpg" → "main"
    const groupDir = await imagesDir.getDirectoryHandle(group, { create: true });
    const filename = img.file.split('/')[1];
    const fh = await groupDir.getFileHandle(filename, { create: true });
    const w = await fh.createWritable();
    await w.write(img.blob);
    await w.close();
  }
}
```

### 5.2 跨页去重（读 sources.json）

```ts
export async function readExistingSources(
  folderName: string
): Promise<Set<string>> {
  try {
    const root = await ensureRootDir();
    const productDir = await root.getDirectoryHandle(folderName);
    const sourcesFile = await productDir.getFileHandle('sources.json');
    const file = await sourcesFile.getFile();
    const text = await file.text();
    const sources: SourcesJson = JSON.parse(text);
    return new Set(sources.dedupeKeys || []);
  } catch {
    return new Set();  // 文件夹不存在或首次采集
  }
}
```

---

## 6. Side Panel UI 交互（简化版）

```
┌─ 1688/淘宝 采集助手 ────────────┐
│                               │
│ 保存到: ~/Ozon商品库/         │
│        [选择目录]              │
│                               │
│ 当前文件夹: 儿童保温杯_316    │
│            [新建]              │
│                               │
├─────────────────────────────── │
│ 本页识别到:                    │
│                               │
│ 标题: 儿童316不锈钢保温杯…    │
│                               │
│ ☑ 主图 (6)          [全选]    │
│   [缩略图缩略图...]            │
│                               │
│ ☑ SKU图 (4)         [全选]    │
│   蓝色 粉色 绿色 白色          │
│                               │
│ ☐ 详情图 (9)        [全选]    │
│   ⚠️ 0张，请滚到底部后重新采集  │
│                               │
│ ☑ 视频 (1)                    │
│                               │
├─────────────────────────────── │
│ 已选 11 项                     │
│                               │
│ [开始采集]  [追加到文件夹]     │
└───────────────────────────────┘
```

**交互要点**：
- 首次使用提示选择根目录（只需一次）
- 文件夹名默认取商品标题（可改）
- 详情图为 0 时明确提示原因
- "追加到文件夹"按钮读 sources.json，标灰重复项

---

## 7. 开工前检查清单

### 环境
- [ ] Node.js 18+ / pnpm 已安装
- [ ] Chrome 114+（File System Access 与 Side Panel 最低版本）

### 技术决策确认
- [ ] Side Panel UI 用 React（已定）还是原生 JS？ → **React**
- [ ] 要不要一期就做淘宝，还是先只做 1688？ → **都做，复用度高**
- [ ] product.json 的 TS 类型现在就手写，还是等 Pydantic 先写？ → **手写，用契约文档**

### 文件准备
- [ ] `docs/extension/drafts/*.ts` 要不要直接搬到 `extension/src/`？ → **等项目初始化后再搬**
- [ ] `reference/1688-extension/` 的 bundle 要不要进 git？ → **已在 .gitignore，不进**

---

## 8. 下一步

我可以：

**A. 立刻初始化项目**（会生成约 20 个文件）
```bash
cd /Users/joey-xd/sites/seller-store/ozon-seller-kit
mkdir extension && cd extension
pnpm create wxt@latest .
# 选 React + TypeScript
```

**B. 先写 M2 的核心类型和工具**，验证设计
- `src/schema/product.ts`（按契约文档）
- `src/collector/url.ts`（从 plan.md 移植）
- `src/profiles/types.ts`（从 plan.md 移植）

**C. 分步实现，每个里程碑验收后再进下一个**

你倾向哪个？还是有其他想法？