Expand seller store functionality

2026-09-07 17:51:11 +08:00
parent 4c0f3a4a79
commit ceb644a3f9
35 changed files with 32883 additions and 364 deletions
@@ -0,0 +1,73 @@
+# 浏览器扩展的 Background Service Worker
+
+> 本文以 Atlas 采集插件为例，说明 Chrome Manifest V3 扩展的后台运行环境、消息调用链与调试方法。
+
+## 1. 它是什么
+
+`Background Service Worker` 是 Chrome Manifest V3 扩展的后台运行环境。它不属于任何网页，也没有固定 UI；Chrome 在收到消息、标签页事件等需要处理的事件时唤醒它，空闲后停止它以节省资源。
+
+因此，后台代码不能假设进程始终存活，也不能只用模块变量保存登录态或业务状态。需要跨唤醒保留的数据应写入 `chrome.storage`；本项目使用 `chrome.storage.local` 保存插件同步得到的短期登录令牌。
+
+## 2. Atlas 采集插件中的调用链
+
+```text
+商品网页（Content Script）
+  点击“编辑上架”
+        │ browser.runtime.sendMessage(...)
+        ▼
+扩展 Background Service Worker
+  读取 chrome.storage 中的登录令牌
+  fetch Atlas API，并附加 Authorization
+        │
+        ▼
+Atlas API
+        │
+        ▼
+Background 将结果回传给 Content Script
+  打开采集测试页 / 展示错误
+```
+
+项目中三个环境彼此隔离：
+
+| 环境 | 运行位置 | 负责内容 |
+|---|---|---|
+| 商品网页 | Ozon、1688、淘宝、天猫等页面 | 原网站 DOM 与原网站 Network 请求 |
+| Content Script | 注入商品网页的扩展脚本 | 悬浮窗、商品解析、向后台发送消息 |
+| Background Service Worker | `chrome-extension://…` 扩展上下文 | 登录令牌、跨站 API 请求、打开标签页 |
+
+采集请求由 Background 发出，所以它不会出现在商品网页 DevTools 的 Network 面板。商品页 DevTools 只能看到来源网站自身的网络请求。
+
+## 3. 为什么采用后台请求
+
+- 登录令牌保留在扩展存储中，不必暴露给来源商品页的 JavaScript。
+- Content Script 仅负责页面交互和净化后的商品载荷；API 鉴权、请求和跳转集中在后台处理。
+- 后台拥有扩展声明的 `host_permissions`，可访问 Atlas API 与受支持来源站点；页面本身的跨域限制不会决定插件后台请求的权限。
+
+后台权限仍应遵循最小化原则：本项目只允许访问 Atlas API、Atlas Web 与明确支持的来源站点，绝不读取来源站 Cookie 或 localStorage。
+
+## 4. 前端如何调试
+
+### 4.1 调试后台 API 请求
+
+1. 打开 `chrome://extensions`，开启“开发者模式”。
+2. 找到 Atlas 采集插件，点击卡片中的 **Service Worker** 或“检查视图”。
+3. 在打开的 DevTools 中查看：
+   - **Console**：后台异常、消息处理失败；
+   - **Network**：`/api/extension/session`、`/api/extension/materials` 等 Atlas API 请求、状态码与响应体；
+   - **Application → Storage → Extension storage**：插件保存的登录态数据。
+
+这里才是排查 `Authorization` 请求头、API 4xx/5xx，以及采集写入失败的正确位置。
+
+### 4.2 调试悬浮窗和商品解析
+
+在商品详情页按 F12，使用该页面的 DevTools：
+
+- **Console**：查看 Content Script 的页面解析、悬浮窗和 `sendMessage` 调用错误；
+- **Sources**：寻找 `chrome-extension://…/content-scripts/collector.js`，可对商品解析或点击处理函数下断点；
+- **Network**：只用于分析 Ozon、1688、淘宝、天猫页面自身的请求与页面数据来源，不应期待看到 Atlas API 请求。
+
+### 4.3 Service Worker 生命周期注意事项
+
+Service Worker 空闲后会被 Chrome 停止；再次刷新商品页、点击悬浮窗或收到扩展事件时才会重新唤醒。调试时建议在 Service Worker DevTools 勾选“保留日志”，避免后台停止后丢失 Console 输出。
+
+不要依赖 Service Worker 模块变量存储登录状态或待处理任务。需要持久化的数据应使用 `chrome.storage`、后端数据库或其他可恢复的存储；异步操作应能安全地在下一次后台唤醒后继续或重试。