# 网站接入店闪扩展说明

这个扩展已经提供网站侧调用接口。网站点击“开始”时，可以让扩展执行和 popup 手动点击“立即爬取”一样的流程：打开新浏览器窗口、进入平台后台、抓取数据。抓取完成后，扩展会通过长连接把结果推回网站。

## 1. 先配置允许连接的网站域名

扩展的 `manifest.config.ts` 里有：

```ts
externally_connectable: {
    matches: [
        "http://localhost:3000/*",
    ]
}
```

把你的网站域名加进去，例如：

```ts
externally_connectable: {
    matches: [
        "http://localhost:3000/*",
        "https://your-site.com/*",
    ]
}
```

改完扩展后需要重新 `pnpm run build`，并在 Chrome 扩展管理页重新加载扩展。

## 2. 网站侧需要知道扩展 ID

Chrome 扩展管理页打开“开发者模式”，复制这个扩展的 ID：

```ts
const EXTENSION_ID = "这里换成你的扩展ID";
```

开发环境如果每次扩展 ID 变化，建议给扩展配置固定 key，或者每次复制新的 ID 到网站项目配置里。

## 3. 推荐的网站侧接入代码

网站页面加载后先建立长连接，用来接收扩展推送的进度和最终结果。

```ts
const EXTENSION_ID = "这里换成你的扩展ID";

type DianshanMessage = {
  ok: boolean;
  type?: string;
  data?: {
    state: any | null;
    result: Record<string, unknown> | null;
  };
  error?: string;
};

let port: chrome.runtime.Port | null = null;

export function connectDianshanExtension() {
  port = chrome.runtime.connect(EXTENSION_ID, { name: "DIANSHAN_CRAWL" });

  port.onMessage.addListener((message: DianshanMessage) => {
    console.log("[dianshan]", message);

    if (message.type === "DIANSHAN_CRAWL_STATE") {
      // 可选：更新网站上的进度 UI
      return;
    }

    if (message.type === "DIANSHAN_CRAWL_DONE") {
      // 抓取完成，最终数据在 message.data.result
      console.log("抓取结果", message.data?.result);
      return;
    }

    if (message.type === "DIANSHAN_CRAWL_FAILED") {
      // 抓取失败，可展示 message.data.state.steps 里的失败原因
      console.error("抓取失败", message.data?.state);
      return;
    }

    if (message.type === "DIANSHAN_CRAWL_CANCELED" || message.type === "DIANSHAN_CRAWL_CLEARED") {
      // 用户取消或任务被清空
      console.log("抓取已取消");
    }
  });

  port.onDisconnect.addListener(() => {
    port = null;
  });
}
```

## 4. 网站点击“开始抓取”

按钮点击时调用：

```ts
export async function startDianshanCrawl(platformId = "Shopee") {
  const response = await chrome.runtime.sendMessage(EXTENSION_ID, {
    type: "DIANSHAN_START_CRAWL",
    payload: { platformId },
  });

  if (!response?.ok) {
    throw new Error(response?.error ?? "启动抓取失败");
  }

  return response.data;
}
```

效果等同于用户打开 popup 后手动点击“立即爬取”。如果当前已经有 running/paused 的任务，扩展会直接返回当前任务，不会重复打开多个抓取窗口。

## 5. 查询当前状态

```ts
export async function getDianshanCrawlState() {
  return chrome.runtime.sendMessage(EXTENSION_ID, {
    type: "DIANSHAN_GET_CRAWL_STATE",
  });
}
```

## 6. 网站侧取消抓取

```ts
export async function cancelDianshanCrawl() {
  return chrome.runtime.sendMessage(EXTENSION_ID, {
    type: "DIANSHAN_CANCEL_CRAWL",
  });
}
```

取消后扩展会清空 `crawlTaskState`，并关闭扩展自动打开的浏览器窗口。

## 7. 返回数据结构

长连接收到 `DIANSHAN_CRAWL_DONE` 时，数据大致是：

```ts
{
  ok: true,
  type: "DIANSHAN_CRAWL_DONE",
  data: {
    state: {
      id: "Shopee-...",
      platformId: "Shopee",
      platformName: "Shopee 后台",
      status: "completed",
      steps: [
        {
          name: "数据看板",
          uniqueKey: "databoard",
          status: "success",
          result: {}
        }
      ]
    },
    result: {
      databoard: {
        name: "数据看板",
        status: "success",
        result: {}
      },
      adscenter: {
        name: "广告中心",
        status: "success",
        result: {}
      }
    }
  }
}
```

网站项目里一般用 `message.data.result` 入库或展示即可；如果要展示进度，用 `message.data.state.steps`。

## 8. 最小使用流程

```ts
connectDianshanExtension();

document.querySelector("#start")?.addEventListener("click", async () => {
  await startDianshanCrawl("Shopee");
});
```

注意：网站必须运行在 `externally_connectable.matches` 配置过的域名下，否则 Chrome 会拒绝调用扩展。