# dianshan 插件爬取任务开发文档（逻辑/通信/状态）

> 目的：把“点击爬取后发生了什么、会触发哪些方法、给谁通信、改变哪些状态”说清楚，方便后续二开与排查。
>
> 范围：`dianshan/` 目录内的扩展（popup + background + content/overlay + 外部网页桥接）。
>
> 注意：当前项目代码里没有 `startDianshanCrawl()` / `getDianshanCrawlState()` 这类方法名；
> 正确入口分别是 `startCrawl()`（`dianshan/src/background/task/crawlTask.ts:14`）与 `getCrawlTaskState()`（`dianshan/src/background/task/taskState.ts:10`），以及对应的消息 action（`START_CRAWL` / `GET_CRAWL_STATE`）。

---

## 1. 关键文件索引（按职责）

### 1.1 Popup（扩展弹窗 UI）
- `dianshan/src/popup/App.vue`
    - UI 展示：平台选择、开始/取消/继续按钮、步骤列表、底部语言切换/版本号
- `dianshan/src/popup/hook/use-scan.ts`
    - 与 background 通信（开始/取消/继续/读取状态）
    - 监听 `chrome.storage.onChanged` 同步任务状态
    - 计时器：根据 `startedAt` 计算已用时
- `dianshan/src/popup/hook/use-i18n.ts`
    - Popup 文案 i18n（中文/英文），持久化到 `chrome.storage.local`

### 1.2 Background（后台调度 + 任务状态机）
- `dianshan/src/background/index.ts`
    - 统一接收 popup/content/external 的 message（`chrome.runtime.onMessage`）
    - 监听窗口/Tab 关闭（自动暂停任务）
    - 监听 storage 变化并对外广播（external bridge）
- `dianshan/src/background/task/crawlTask.ts`
    - 任务生命周期：start/cancel/pause/resume/dismiss
    - 步骤执行器：按 steps 顺序打开页面、等待、抓取、处理中断/重试
    - 完成后收尾：发送结果 -> 清空记录 -> 关闭窗口
- `dianshan/src/background/task/taskState.ts`
    - 读写 `chrome.storage.local` 的 `crawlTaskState`
    - 写入时同时 `sendTabMessage(tabId,'CRAWL_STATE_UPDATE',state)` 推送给爬取窗口（overlay 用）
- `dianshan/src/background/task/helper.ts`
    - `openSingleTabWindow()` 创建 popup 类型新窗口并返回 `{windowId, tabId}`
    - `waitForTabLoaded()` 等待 tab load complete
    - `scrapeStepInContent()` 与 content script 通信执行抓取（`tabs.sendMessage`）
- `dianshan/src/background/service/externalBridge.ts`
    - 与外部网页（官网/业务系统）进行 external message / long-connect 通信
    - 监听 storage 变化，广播 `DIANSHAN_CRAWL_STATE / DONE / ...` 等事件

### 1.3 Content Script（爬取窗口页内逻辑）
- `dianshan/src/content/pageRunner.ts`
    - 接收 background 指令：
        - `CHECK_INTERRUPT`：判断登录/验证码/404/未就绪等“需要人工处理”的中断
        - `SCRAPE_STEP`：等待关键 selector 稳定后执行 DOM 抓取
- `dianshan/src/content/crawlOverlay.ts`
    - 爬取窗口左下角悬浮 UI（圆形计时菜单）
    - 点击圆形菜单展开后展示“与 popup 类似”的步骤进度/暂停提示/继续/取消
    - 接收 background 推送的 `CRAWL_STATE_UPDATE` 状态
    - 初始化时会拉取一次 `GET_CRAWL_STATE_FOR_TAB` 快照（只在爬取 tab 返回状态）

### 1.4 Shared（跨模块协议）
- `dianshan/src/shared/message.ts`
    - popup/content -> background 的消息 action 类型（例如 `START_CRAWL`）
- `dianshan/src/shared/tab.ts`
    - background -> content（爬取窗口 tab）消息 action 类型（例如 `CRAWL_STATE_UPDATE`）
- `dianshan/src/types/crawl.ts`
    - `CrawlTaskState` / `CrawlProgressStep` / `CrawlPauseInfo` 等任务数据结构

### 1.5 关键方法定位（按真实代码）
> 下面列的都是当前项目里“确实存在”的方法/入口，后面章节会反复引用；每条都附带文件地址+行号，方便你 Ctrl+P 直达。

- popup 启动爬取：`handleScan()`：`dianshan/src/popup/hook/use-scan.ts:46`
- popup 取消爬取：`handleCancelCrawl()`：`dianshan/src/popup/hook/use-scan.ts:70`
- popup 继续爬取：`handleResumeCrawl()`：`dianshan/src/popup/hook/use-scan.ts:83`
- popup 同步状态：`handleStorageChanged()`：`dianshan/src/popup/hook/use-scan.ts:146`

- background 消息总入口：`chrome.runtime.onMessage.addListener(...)`：`dianshan/src/background/index.ts:22`
- background 路由：`case "START_CRAWL"` 等：`dianshan/src/background/index.ts:34`
- background 窗口/Tab 关闭监听：`windows.onRemoved`/`tabs.onRemoved`：`dianshan/src/background/index.ts:92`

- 任务启动：`startCrawl()`：`dianshan/src/background/task/crawlTask.ts:14`
- 任务执行器：`runCrawlSteps()`：`dianshan/src/background/task/crawlTask.ts:63`
- 完成收尾：`finalizeCompletedTask()`：`dianshan/src/background/task/crawlTask.ts:312`
- 取消任务：`cancelCrawl()`：`dianshan/src/background/task/crawlTask.ts:131`
- 窗口关闭自动暂停：`pauseCrawlOnWindowRemoved()`：`dianshan/src/background/task/crawlTask.ts:158`
- Tab 关闭自动暂停：`pauseCrawlOnTabRemoved()`：`dianshan/src/background/task/crawlTask.ts:188`
- 继续/恢复：`resumeCrawl()`：`dianshan/src/background/task/crawlTask.ts:219`

- 状态读写：`getCrawlTaskState()`/`setCrawlTaskState()`：`dianshan/src/background/task/taskState.ts:10` / `dianshan/src/background/task/taskState.ts:20`

- 新开爬取窗口：`openSingleTabWindow()`：`dianshan/src/background/task/helper.ts:8`
- 等待页面加载：`waitForTabLoaded()`：`dianshan/src/background/task/helper.ts:45`
- 让 content 抓取：`scrapeStepInContent()`：`dianshan/src/background/task/helper.ts:90`

- content 执行器入口：`setupPageRunner()`：`dianshan/src/content/pageRunner.ts:28`
- content 抓取处理：`handlePageRunnerMessage()`：`dianshan/src/content/pageRunner.ts:38`

- 爬取窗口悬浮 UI：`mountCrawlOverlay()`：`dianshan/src/content/crawlOverlay.ts:36`
- 悬浮 UI 初始化拉取快照：`GET_CRAWL_STATE_FOR_TAB`：`dianshan/src/content/crawlOverlay.ts:67`
- 悬浮 UI 实时状态推送：`CRAWL_STATE_UPDATE`：`dianshan/src/content/crawlOverlay.ts:54`

---

## 2. 核心数据结构：CrawlTaskState（状态机）

存储位置：`chrome.storage.local['crawlTaskState']`

关键字段（简化说明）：
- `id`：任务唯一 ID（`platformId-startedAt`）
- `platformId/platformName`：平台信息
- `windowId/tabId`：当前爬取窗口与承载爬取的 tab（overlay 只在这个 tab 渲染）
- `startedAt`：任务开始时间戳（用于 popup/overlay 计时）
- `status`：`running | paused | completed | failed | canceled`
- `pause`：当 `status='paused'` 时存在，包含
    - `reason`：`reauth | shield | not_found | page_not_ready | window_closed`
    - `message`：给用户看的暂停提示
- `currentStepIndex`：当前执行到的步骤索引
- `steps[]`：每个步骤的进度条记录
    - `uniqueKey/name`
    - `status`：`pending | running | success | failed`
    - `result/message`：抓取结果或失败原因

状态同步策略：
- background 每次 `setCrawlTaskState()` / `updateCrawlTaskState()` 都会写入 storage
- popup：监听 `chrome.storage.onChanged`，永远以 storage 为准渲染 UI
- overlay：通过 `sendTabMessage(tabId,'CRAWL_STATE_UPDATE',state)` 实时更新（并可在初始化时请求快照）
- 外部网页：`chrome.storage.onChanged` -> `externalBridge.broadcastCrawlStorageChange()` 广播结果/状态

---

## 3. “点击爬取”后的完整时序（从 UI 到抓取）

以下用“触发方法 / 通信对象 / 状态变化”描述每一步。

### 3.1 Popup 点击 “Scan now”
1) 触发方法
- popup：`use-scan.ts -> handleScan()`（`dianshan/src/popup/hook/use-scan.ts:46`）

2) 通信
- popup -> background：`sendBackgroundMessage({ action:'START_CRAWL', payload:{ platformId } })`

3) background 入口
- `background/index.ts` 的 `chrome.runtime.onMessage` 收到 `START_CRAWL`（`dianshan/src/background/index.ts:22` / `dianshan/src/background/index.ts:34`）
- 调用：`crawlTask.startCrawl(platformId)`（`dianshan/src/background/task/crawlTask.ts:14`）

4) 状态变化（startCrawl）
- `openSingleTabWindow(steps[0].url)`：创建爬取窗口（popup 类型）得到 `{windowId, tabId}`（`dianshan/src/background/task/helper.ts:8`）
- 构建初始 `CrawlTaskState`：
    - `status='running'`
    - `currentStepIndex=0`
    - `steps[0].status='running'`，其余 `pending`
- `setCrawlTaskState(nextState)` 写入 storage（`dianshan/src/background/task/taskState.ts:20`）
    - 这一步会触发：
        - popup 的 storage 监听更新 UI
        - background 同时 `sendTabMessage(tabId,'CRAWL_STATE_UPDATE',state)` 推送给 overlay（`dianshan/src/background/task/taskState.ts:20`）
        - externalBridge 通过 storage.onChanged 对外广播（如果网页有连 port）

5) 启动执行器
- background：创建 `AbortController`，并异步执行：
    - `runCrawlSteps(taskId, tabId, platform.steps, signal, startIndex=0)`（`dianshan/src/background/task/crawlTask.ts:63`）

---

## 4. “执行一个步骤”会发生什么（runCrawlSteps 的循环体）

每个 step 的处理流程如下（对每个 i 从 startIndex 到 steps.length-1）：

### 4.1 进入新 step：先更新状态机
1) 触发方法
- background：`updateCrawlTaskState(taskId, updater)`

2) 状态变化
- `currentStepIndex = i`
- `steps[i].status = 'running'`（其它步骤保持原样）

3) 通信影响
- 因为 `updateCrawlTaskState()` 内部会 `setCrawlTaskState()`：
    - storage 写入 -> popup UI 更新
    - 同时 `sendTabMessage(tabId,'CRAWL_STATE_UPDATE',state)` -> overlay 更新
    - storage.onChanged -> external bridge 广播（如果外部网页连着）

### 4.2 跳转页面并等待加载完成
1) 触发方法
- background：`chrome.tabs.update(tabId, { url: step.url, active: true })`
- background：`waitForTabLoaded(tabId, signal)`

2) 通信对象
- background -> Chrome tabs API（无 content 参与）

3) 状态变化
- 不改变任务状态，只是准备让 content script 进入目标页面上下文

### 4.3 让 content script 执行抓取（核心通信）
1) 触发方法
- background：`scrapeStepInContent(tabId, step, signal)`

2) 通信
- background -> content（爬取窗口 tab）：`chrome.tabs.sendMessage(tabId, { action:'SCRAPE_STEP', payload:{ fields, checkSelector } })`

3) content 入口
- `content/pageRunner.ts` 的 `chrome.runtime.onMessage` 收到 `SCRAPE_STEP`
    - `detectPageInterrupt()`：先判断是否需要人工处理（登录/验证码/404/未就绪）
    - `waitForStableSelector(checkSelector, timeout)`：等待关键 DOM 稳定出现
    - `processFields(fields, document.body)`：按配置抓取 DOM 数据

4) 返回值约定（PageRunnerResponse）
- `ok: true, data: DomScrapeResult`：本步骤抓取成功
- `interrupt: CrawlPauseInfo`：需要人工处理（会进入 paused）
- `ok: false, error`：未就绪/异常，background 会重试

### 4.4 抓取成功：写入结果并标记 step success
1) 触发方法
- background：`updateCrawlTaskState(taskId, updater)`

2) 状态变化
- `steps[i].status = 'success'`
- `steps[i].result = res.data`

3) 通信影响
- 同 4.1：storage + overlay 推送 + external bridge 广播

### 4.5 抓取中断：进入 paused（需要用户处理）
中断来源：
- content 检测到 `shield/reauth/not_found/page_not_ready`
- 或者：爬取窗口被用户关掉（见第 6 章）

1) 触发方法（以 content 中断为例）
- background：`updateCrawlTaskState(taskId, s => ({ ...s, status:'paused', pause: interrupt }))`（`dianshan/src/background/task/crawlTask.ts:93`）

2) 状态变化
- `status='paused'`
- `pause={reason,message}`

3) 执行器行为
- background 在 `runCrawlSteps` 内部“死等恢复”：
    - 循环检查 `getCrawlTaskState()?.status === 'paused'`
    - 直到用户点击“继续”把状态改回 `running` 才继续

4) UI 行为
- popup / overlay 都会显示暂停提示 + “Continue”

---

## 5. “点击继续”会发生什么（RESUME_CRAWL）

触发来源：
- popup 的 Continue
- overlay 的 Continue

### 5.1 popup/overlay 发消息
- popup：`use-scan.ts -> handleResumeCrawl() -> sendBackgroundMessage({action:'RESUME_CRAWL'})`（`dianshan/src/popup/hook/use-scan.ts:83`）
- overlay：`crawlOverlay.ts -> chrome.runtime.sendMessage({action:'RESUME_CRAWL'})`（`dianshan/src/content/crawlOverlay.ts:392`）

### 5.2 background 处理 resume
入口：
- `background/index.ts` switch case `RESUME_CRAWL`（`dianshan/src/background/index.ts:66`）
    - 调用 `crawlTask.resumeCrawl()`（`dianshan/src/background/task/crawlTask.ts:219`）

resumeCrawl 分两类：

#### A) 登录/验证码等中断（窗口仍存在）
条件：
- `state.status === 'paused'`
- `state.pause.reason !== 'window_closed'`
- `state.windowId && state.tabId` 还在

行为：
- 仅把状态改回 `running`（清掉 pause）
- 原来的 `runCrawlSteps()` 仍在“死等恢复”，会自动继续跑下一轮

#### B) 窗口被关闭导致中断（需要重开窗口）
条件：
- `state.pause.reason === 'window_closed'` 或 `windowId/tabId` 不存在

行为：
- 根据 `currentStepIndex` 找到“第一个未 success 的步骤”作为 `startIndex`
- `openSingleTabWindow(url)` 重新打开爬取窗口（`dianshan/src/background/task/helper.ts:8`）
- `setCrawlTaskState()` 写入新的 `windowId/tabId/status='running'/currentStepIndex=startIndex`（`dianshan/src/background/task/taskState.ts:20`）
- 新建 `AbortController`，重新启动执行器：
    - `runCrawlSteps(taskId, newTabId, platform.steps, signal, startIndex)`（`dianshan/src/background/task/crawlTask.ts:63`）

---

## 6. “爬取过程中窗口被关掉”会发生什么（自动暂停）

触发点：
- `background/index.ts` 监听：
    - `chrome.windows.onRemoved`（`dianshan/src/background/index.ts:92`）
    - `chrome.tabs.onRemoved`（兜底）（`dianshan/src/background/index.ts:97`）

处理逻辑：
- 调用 `crawlTask.pauseCrawlOnWindowRemoved(windowId)`（`dianshan/src/background/task/crawlTask.ts:158`）或 `pauseCrawlOnTabRemoved(tabId)`（`dianshan/src/background/task/crawlTask.ts:188`）

行为：
1) 中止执行器
- 找到当前任务对应的 `AbortController` 并 `abort()`
- 目的：避免后台继续对不存在的 tab 进行 `tabs.update/sendMessage` 导致刷屏错误

2) 状态改为 paused
- `status='paused'`
- `pause.reason='window_closed'`
- `pause.message` 提示用户点击继续可恢复
- 清空 `windowId/tabId`（避免 UI 侧再尝试 focus 老窗口）

用户点击继续后：
- 走第 5.2 的 B 分支：重开窗口 + 从未完成步骤继续

---

## 7. “全部步骤完成”会发生什么（发送结果 + 清理 + 关窗）

触发点：
- `runCrawlSteps()` 完成 for 循环后：
    1) `updateCrawlTaskState(...status='completed')`
    2) 调用 `finalizeCompletedTask(taskId)`

finalizeCompletedTask 做三件事（顺序很重要）：
1) 发送结果给页面
    - background -> content（爬取 tab）：`sendTabMessage(tabId,'CRAWL_COMPLETED',{ result: ... })`
    - 同时 storage 完成态会触发 `externalBridge` 对外广播 `DIANSHAN_CRAWL_DONE`
2) 清空本次任务记录
    - `clearCrawlTaskState()`：移除 `chrome.storage.local['crawlTaskState']`
    - popup 会收到 storage 改变并自动把 UI 恢复到“未开始”状态
3) 关闭爬取窗口
    - `chrome.windows.remove(windowId)`

---

## 8. Popup/Overlay 如何拿到状态（同步机制总结）

### 8.1 Popup：只看 storage（强一致）
- 初次加载：发 `GET_CRAWL_STATE`
- 后续更新：监听 `chrome.storage.onChanged`，只要 `crawlTaskState` 变化就刷新 UI

### 8.2 Overlay：推送为主，拉取为辅
- 推送：background 写入 state 时会 `sendTabMessage(tabId,'CRAWL_STATE_UPDATE',state)`
    - overlay 监听 `chrome.runtime.onMessage`，收到 `action==='CRAWL_STATE_UPDATE'` 立刻渲染
- 拉取：overlay 初始化时发 `GET_CRAWL_STATE_FOR_TAB`
    - background 只在 `sender.tab.id === state.tabId` 时返回 state，否则返回 null

---

## 9. 外部网页（官网/业务系统）如何接收结果（externalBridge）

两种方式：

### 9.1 onMessageExternal（短消息）
- 网页发 `DIANSHAN_START_CRAWL / DIANSHAN_GET_CRAWL_STATE / ...`
- background `externalBridge.handleExternalMessage()` 返回当前状态/平台列表等

### 9.2 onConnectExternal（长连接 Port）
- 网页建立 Port（name=`DIANSHAN_CRAWL`）
- background 把当前 state 发一次 `DIANSHAN_CRAWL_STATE`
- 后续只要 storage 变化，就广播：
    - `DIANSHAN_CRAWL_STATE`（进行中）
    - `DIANSHAN_CRAWL_DONE`（完成且带 result）
    - `DIANSHAN_CRAWL_CLEARED / FAILED / CANCELED`（清理/失败/取消）

结果结构：
- `externalBridge.buildCrawlWebPayload(state)` 会给出：
    - `state`：完整状态机
    - `result`：仅当 `state.status==='completed'` 时非空，为按 step.uniqueKey 聚合的结果对象

---

## 10. 常见问题排查（建议）

1) overlay 不显示 / 不更新
- 先确认该 tab 是否为 `crawlTaskState.tabId`
- overlay 初始化会请求 `GET_CRAWL_STATE_FOR_TAB`，只有爬取 tab 才返回 state
- 确认 background 写入 state 时是否调用了 `setCrawlTaskState()`（它会推送 `CRAWL_STATE_UPDATE`）

2) 点击取消 popup “闪一下”
- 通常是计时器回调解引用了空状态；popup 侧必须在 state 清空时 stop timer

3) 窗口被关后任务还在后台跑
- 应当由 `windows.onRemoved/tabs.onRemoved` 触发 `pauseCrawlOnWindowRemoved/TabRemoved`
- 检查 background/index.ts 是否注册了监听

---

## 11. 约定：消息 action 一览（当前）

popup/content -> background（`dianshan/src/shared/message.ts`）：
- `START_CRAWL`
- `GET_CRAWL_STATE`
- `GET_CRAWL_STATE_FOR_TAB`（仅爬取 tab 返回 state）
- `CANCEL_CRAWL`
- `RESUME_CRAWL`
- `DISMISS_CRAWL`
- `CANCEL_AUTOCLOSE`（兼容旧 overlay 按钮，不建议新逻辑依赖）

background -> content（`dianshan/src/shared/tab.ts`）：
- `CRAWL_STATE_UPDATE`（overlay/pagerunner 可用）
- `CRAWL_COMPLETED`（完成时额外发送结果）