# table-spider-plugin

**Repository Path**: xfc03/table-spider-plugin

## Basic Information

- **Project Name**: table-spider-plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 表格采集扩展 - 功能说明

Chrome 扩展：A页面点击按钮，自动打开新标签跳转到B页面，在B页面采集表格数据后将采集结果返回A页面。支持分页、支持传入日期参数、支持两种采集方式（DOM 解析 / 请求响应）。

---

## 一、功能概述

- **注入范围**：仅在 **iframe** 内执行采集（`window.top !== window`）；顶层页不跑采集逻辑。
- **两种采集模式**（由 `spider.js` 内 `mode` 决定）：
  - **DOM 模式**（`mode !== "request"`）：页面 load 后延迟 800ms，解析当前页所有 `<table>`，点击「下一页」后等待 1–3 秒再采下一页，直到无下一页或达到页数上限。逻辑在 `getTableDataByDom.js`（`runCollectByDom`）。
  - **请求模式**（`mode === "request"`）：A 页传入 `date` 时，B 页在 load 前注入 `fetch-patch.js` 并派发 `spider-set-date` 劫持 listProductInfo 请求；load 后监听接口响应事件，用响应数据累加每页，再点击「下一页」并改写 pageNum 继续，直到无下一页或达到页数上限。逻辑在 `getTableDataByRequest.js`（`runCollectByRequest`）。
- **回传**：**请求模式**下，B 页采集结束时先经 `dataRefactoring` 转成统一结构，再通过 background 把数据发给 A 页；**DOM 模式**下当前实现不会触发回传（`runCollectByDom` 未调用传入的 `onDone`，仅控制台输出）。

---

## 二、脚本与流程

### 2.1 脚本职责

| 脚本 | 职责 |
|------|------|
| `messenger.js` | 监听 A 页 postMessage（`COLLECT_PARAMS`），转发给 background（openTab）；接收 background 转发的 `COLLECT_RESULT` 再 postMessage 给 A 页。 |
| `background.js` | 接收 openTab：把 params 写入 storage、可选在 URL 加 spider-date、新建标签打开 B 页；接收 collectDone：把 data 转发给 A 页 tab。 |
| `spider.js` | 仅在 iframe 内：有 `date` 时在 load 前注入 fetch-patch 并派发 spider-set-date；load 时读 storage 的 collectParams（maxPages、date），按 **mode** 调用 `runCollectByDom` 或 `runCollectByRequest`，请求模式结束时 `notifyCollectDone`（先 dataRefactoring 再发送）。 |
| `getTableDataByDom.js` | 提供 `getTableDataByDom()` 与 `runCollectByDom(options)`：按 DOM 解析表格并翻页采集。 |
| `getTableDataByRequest.js` | 提供 `getTableDataByRequest(apiResponse)` 与 `runCollectByRequest(options)`：监听 listProductInfo 响应事件分页采集，翻页前派发 spider-set-pagenum（若 fetch-patch 支持）。 |
| `fetch-patch.js` | 注入到**页面上下文**：监听 spider-set-date 设 `__SPIDER_PAY_DATE__`；劫持 XHR，对 listProductInfo 的请求改写 body 的 payTimeBegin/payTimeEnd；响应完成后派发 spider-listProductInfo-data 把响应数据传给 content script。 |
| `dataRefactoring.js` | 将 accumulated（pages/tables）转为统一输出：platform、version、content.params.date、content.data.{ total, items }，并做行级字段映射（如 express_company 根据 express_no 推断）。 |
| `collect-overlay.js` | 采集中遮罩与交互抑制（见 **2.4**）；由采货侠 / 拍机堂等 content_scripts 最先注入，提供 `showCollectOverlay` / `hideCollectOverlay`。 |

### 2.2 参数传递（A → B）

- A 页：`window.postMessage({ type: "COLLECT_PARAMS", targetUrl, params }, "*")`。
- **params**：`maxPages`（数字，0 表示不设上限）、`date`（可选，YYYY-MM-DD；请求模式需传 date 以便注入 fetch-patch 并改写请求）。
- messenger 收到后发 `openTab` 给 background；background 写 storage（collectParams、collectPendingTabId），然后 `chrome.tabs.create({ url: targetUrl })`。
- B 页（iframe）：load 时 `chrome.storage.local.get("collectParams")`，用后 `remove("collectParams")`，读取 `maxPages`、`date`，按 mode 执行 runCollectByDom 或 runCollectByRequest。

### 2.3 回传 A 页（B → background → messenger → A）

- B 页：请求模式下采集结束调用 `notifyCollectDone()`，对 `accumulated` 做 `dataRefactoring(accumulated, { date: collectedDate })` 后 `chrome.runtime.sendMessage({ action: "collectDone", data: payload })`。
- background：收到 collectDone，从 storage 取 collectPendingTabId，`chrome.tabs.sendMessage(tabId, { type: "COLLECT_RESULT", data })` 给 A 页的 content script（messenger），再清除 collectPendingTabId。
- A 页：监听 `message`，当 `event.data.type === "COLLECT_RESULT"` 时，`event.data.data` 即为结果（请求模式下为 dataRefactoring 后的结构）。

### 2.4 采集中遮罩层（`scripts/collect-overlay.js`）

扩展在 **采货侠**、**拍机堂** 等业务页的 `content_scripts` 中**先于各平台 spider** 注入 `collect-overlay.js`，采集流程在适当时机调用全局方法：

- **`showCollectOverlay(opts?)`**：开始采集时调用。`opts.label` 可自定义顶部提示文案，默认类似「数据采集中，无法操作页面，请等待」。
- **`hideCollectOverlay()`**：采集结束或异常回传前调用，撤掉遮罩与相关副作用。

**行为概要：**

1. **视觉**：全屏透明层（`pointer-events: none`）仅作结构挂载，顶部居中一条提示条；不在遮罩根节点上写 `cursor`（透明层不接收指针时浏览器不绘制该层光标）。
2. **等待光标**：向 `document.documentElement` 增加类名（如 `lp-collect-cursor-wait`），并注入一次 `<style>`，对 `html/body/*` 使用 `cursor: wait !important`，使整页显示等待光标；隐藏时移除类名。
3. **防误关日期面板**：在 **`window` 捕获阶段**监听 `mousedown`、`pointerdown`、`touchstart`、`click`、`dblclick`。仅在存在遮罩节点、且事件为**用户真实操作**（`isTrusted === true`）、且**不在** Ant Design / rc-picker 日期相关节点内（如 `.ant-picker-dropdown`、`.rc-picker-dropdown` 等）时，执行 `preventDefault` + `stopPropagation`，避免事件到达 `document` 后被误判为「点外部」而关闭日期选择弹层。脚本通过 `element.click()` 等产生的事件多为 `isTrusted === false`，一般仍会落到目标节点，不拦截。
4. **接入点**：各平台在「开始自动化采集」处调用 `showCollectOverlay`，在 `collectDone` 或等价结束路径调用 `hideCollectOverlay`（具体见各目录 README 或 spider 脚本）。

---

## 三、表格解析与输出格式

### 3.1 DOM 模式表头与单元格（getTableDataByDom）

- **表头**：优先 thead 内第一行 th；无 thead 时取首行含 th 的 tr 的 th；无则用 col1、col2…
- **单元格**：Ant Design 多行（`<p><span class="title">标签:</span> 值</p>`）解析为对象；纯文本多行按行拆成数组；无 td 的行跳过。

### 3.2 请求模式列表解析（getTableDataByRequest）

- 从接口 JSON 按路径取列表：data.list、data.rows、data.records、data.pageList、data.items 等；取不到则用 findFirstObjectArray 递归兜底。
- 表头由首行对象的 Object.keys 得到，一行一条记录。

### 3.3 回传给 A 页的统一结构（dataRefactoring，仅请求模式）

```json
{
  "platform": "xxx",// 平台名称
  "version": "1.0.0",
  "content": {
    "params": { "date": "2024-06-01" }, // 查询日期
    "data": {
      "total": 21,
      "items": [
        {
          "imei": "...", // 串号
          "item_code": "...", // 订单编号
          "merchant": "",
          "category": "...", // 分类
          "brand": "...", // 品牌
          "model": "...", // 型号
          "cost_price": "...", // 单价
          "express_no": "...", // 物流单号
          "express_company": "...", // 物流公司
          "version":"...", // 版本（购买渠道）
          "network":"...", // 网络格式
          "color":"...", // 颜色
          "size":"...", // 尺寸
        }
      ]
    }
  }
}
```

- `items` 由每页 tables 的 data 合并后经 `rowToItem` 映射；`express_company` 根据 `express_no` 前缀推断国内快递。

---

## 四、分页与采集控制

- **页数上限**：由 A 页 `params.maxPages` 传入，spider 中为 `effectiveMaxPages`；0 表示采到最后一页。
- **分页按钮**：Ant Design `.ant-pagination-next`，且 `aria-disabled !== "true"` 才点击。
- **DOM 模式**：无表格时每 1s 重试，最多 10 次（首页）/ 5 次（翻页后）；点击下一页后随机 1–3 秒再采下一页。
- **请求模式**：每页监听 spider-listProductInfo-data，先注册下一页监听再延迟约 400ms 后查按钮、派发 spider-set-pagenum、点击下一页；8 秒未收到本页响应则无数据时重头开始，有数据则结束。

---

## 五、配置与运行

- **manifest**：content_scripts 含 messenger（`<all_urls>`）与各业务域脚本（如采货侠、拍机堂等，`all_frames: true`）；**collect-overlay.js** 在各业务入口中先于对应 spider 注入，完整列表以 `manifest.json` 为准。web_accessible_resources 含 fetch-patch.js 等。
- **权限**：storage、tabs。
- **运行时机**：`run_at: "document_start"`；DOM 模式在 load 后延迟 800ms 开始采集。
- **采集模式**：spider.js 内 `mode` 为 `"request"` 时使用请求模式，否则使用 DOM 模式；请求模式需 A 页传 date 且在 iframe 内成功注入 fetch-patch。

---

## 六、A 页调用示例

### 6.1 发起采集（传参并打开 B 页）

```javascript
window.postMessage(
  {
    type: "COLLECT_PARAMS",
    targetUrl: "https://youpinoffice.zhuanzhuan.com/xxx",
    params: {
      maxPages: 5,
      date: "2024-06-01",
    },
  },
  "*"
);
```

### 6.2 接收结果（请求模式会收到；DOM 模式当前不会触发）

```javascript
window.addEventListener("message", function (event) {
  if (event.data?.type === "COLLECT_RESULT") {
    const result = event.data.data;
    console.log("收到采集结果：", result);
    // 请求模式下 result 为 dataRefactoring 后的结构：platform, version, content.params.date, content.data.items
  }
});
```

---

## 七、可调参数（脚本内）

| 位置 | 说明 |
|------|------|
| spider.js `effectiveMaxPages` | 默认 0；可由 A 页 params.maxPages 覆盖，0 表示采到最后一页。 |
| spider.js `mode` | `"request"` 使用请求响应采集，否则使用 DOM 解析采集。 |
| spider.js 首次采集延迟 | DOM 模式：setTimeout(..., 800)。 |
| getTableDataByDom 翻页等待 | 1–3 秒随机。 |
| getTableDataByRequest 等待下一页按钮 | 400ms 后开始查按钮，每 400ms 重试，最多 5 次。 |
| getTableDataByRequest 单页超时 | 8 秒未收到本页响应则按超时逻辑处理。 |

修改后需在 `chrome://extensions` 重新加载扩展并刷新目标页后生效。

---

## 八、按平台分包构建（Vite）

更完整的编排、虚拟拼接与 `emptyOutDir` 说明见 **`README-打包实现思路.md`**。

开发与调试可继续直接加载仓库根目录（使用根目录 `manifest.json`）。**发布某单一平台**时，在仓库根目录执行：

| 命令 | 产出目录 |
|------|----------|
| `npm install` | 安装 `vite`、`typescript` 等 |
| `npm run build` | `dist/chx`、`dist/pjt`、`dist/ksb`、`dist/xc` 四套 |
| `npm run build:chx` 等 | 仅对应平台目录 |

每个 `dist/<平台>/` 内含独立 **`manifest.json`**、`background.js`、`messenger.js`、`content.js`、`logo.png`；采货侠（`chx`）另含 **`scripts/CHX/CHX-fetch-patch.js`** 与 **`CHX-rejection-sniffer.js`**（供 `chrome.runtime.getURL` 注入页面）。在 Chrome 中选择「加载已解压的扩展程序」并指向 **`dist/chx`**（或其它平台文件夹）即可。

**content.js** 在构建时按 `vite.config.mjs` 中 **`CONTENT_SCRIPT_FILES`** 顺序**读源码拼接成单文件**再打包（与根目录 manifest 注入顺序一致），使 `fillDateAndQuery`、`runCollectByRequest` 等与各站 `*-spider.js` 处于同一作用域；若仅 `import` 多文件而不拼接，Rollup 会分模块并重命名，导致 spider 里按「全局」调用的符号报 `ReferenceError`。**background / messenger** 仍为单文件入口。编排脚本：**`scripts/run-extension-build.cjs`**。