packServer/extension/README.md
liufumingren bd2363bf00 chore: 初始化仓库(backend / frontend / extension 三块)
- backend/:Egg 3 纯 JSON 接口服务(MySQL 8 + Redis),全部走 header 令牌鉴权;
  已彻底去掉服务端渲染(删除 page 控制器 / app/view / nunjucks / session / CSRF),
  开发时把页面请求反代到前端 dev server,生产托管 frontend/dist(SPA 回退)。
  单测 91 个通过(不需要本机数据库)。
- frontend/:Vite + Vue3 + TypeScript 的 SPA(登录 / 注册 / 找回密码 / 扫码登录与确认 /
  首页统计 / 设备管理 / 扫码记录 / 个人中心 / 测试页),vue-tsc 类型检查与构建通过。
- extension/:MV3 浏览器扩展(零构建),注入第三方 WMS 页面识别运单号并打开溯源页。
- 忽略规则统一放根 .gitignore:node_modules、dist、logs / logs-*、run、typings、
  .env*、config.local.js(含本机数据库与 Redis 密码,绝不入库)。
2026-10-17 08:50:32 +08:00

163 lines
9.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 云仓视频溯源 · 单号注入扩展
Chrome / Edge 扩展(**Manifest V3 + 原生 JS,零构建**)。
它注入到**第三方 WMS / 后台页面**里,按规则把「运单号」这类字段就地**二次加工**成可点击元素;
点击后打开溯源页面(当前先用 `https://www.baidu.com/?keyword={code}` 占位),把编号作为关键词带过去。
> 首个取样站点:`https://wms.wms.gztbyc.com/order/orderManagement`
> 运单号长这样:
> ```html
> <span class="click-copy-link" role="button" tabindex="0"
> title="点击复制并查看快递单号二维码">321408064481776</span>
> ```
> 点击它 → 小窗打开 `https://www.baidu.com/?keyword=321408064481776`
---
## 1. 安装
1. 打开 `chrome://extensions`(Edge 是 `edge://extensions`)。
2. 右上角打开 **开发者模式**。
3. 点 **加载已解压的扩展程序**,选择本目录 `extension/`。
4. 刷新一下已经打开的 WMS 页面(扩展只对**安装之后**加载的页面生效)。
图标缺失时重新生成:`powershell -ExecutionPolicy Bypass -File tools\make-icons.ps1`
## 2. 目录结构
```
extension/
├── manifest.json # MV3 声明;权限只有 "storage"
├── icons/ # 16/32/48/128,由 tools/make-icons.ps1 生成
├── src/
│ ├── lib/rules.js # ★ 规则引擎(配置归一化 / 正则编译 / DOM 加工 / 地址拼接)
│ ├── content.js # 注入脚本:扫描 + 加工 + 点击拦截 + MutationObserver 补标
│ ├── content.css # 注入样式(全部 .pst- 前缀 + !important)
│ ├── background.js # service worker:只负责把算好的地址打开(小窗 / 新标签页)
│ ├── popup.html/.css/.js # 工具栏弹窗:开关、本页命中清单、重新扫描
│ └── options.html/.css/.js # ★ 规则配置页:基本设置 / 规则编辑 / 试跑 / 导入导出
├── test/wms-mock.html # 自测页:按真实结构复刻的表格
└── tools/make-icons.ps1 # 生成图标(纯 ASCII,见文件头说明)
```
**没有构建步骤**:`rules.js` 挂在 `globalThis.PSTRules` 上,content script / popup / options 各自
用 `<script src>` 或 `manifest.content_scripts.js` 按顺序加载它。改完代码在 `chrome://extensions` 点一下
刷新即可(改 `manifest.json` 才需要重装)。
## 3. 两种匹配方式
| 方式 | 适用 | 关键字段 |
| --- | --- | --- |
| **文本正则** | 页面结构会变、但有稳定的编号格式(`YT1234…`) | `pattern` + `flags`(可带 `exclude` 排除) |
| **CSS 选择器** | 元素本身很好定位(Element-Plus 表格里的 `[title*="快递单号"]`) | `selector` + `attr`(空 = 取元素文本) |
- **文本正则**:遍历文本节点,把**命中的子串**包成 `<span class="pst-trace-mark" data-pst-code="…">`。
原文原样保留在 span 里,所以宿主页读 `textContent`、复制粘贴、表单校验拿到的内容**都不变**。
- **CSS 选择器**:直接给命中元素加类名和 `data-pst-*`,不包一层(适合本来就是个 `<span>` / `<tr>` 的情况)。
- `pattern` 的**第 1 个捕获组**会被当成编号(`{code}` 的值);没写捕获组就用整个匹配。
### 内置规则
| id | 说明 | 生效站点 | 默认 |
| --- | --- | --- | --- |
| `wms-waybill` | `[title*="快递单号"]`,取文本 —— **取样自 gztbyc WMS** | `wms.wms.gztbyc.com` / `*.gztbyc.com` | 开 |
| `express` | `\b(?:YT\|SF\|JD\|ZTO\|YTO\|STO\|EMS\|DBL)\d{10,16}\b` 通用文本规则 | 全部 | 开 |
| `numeric` | 纯数字 12~20 位 | 全部 | **关**(容易把时间戳、内部 ID 点亮,页面上到处下划线反而没人敢用) |
| `dom-attr` | `[data-order-no]` 取属性 | 全部 | 关(示例) |
> ⚠️ gztbyc WMS 一行里有 4 个长得很像的 `.click-copy-link`:
> 发货单号 `JY2026101619599`、运单号 `321408064481776`、波次号 `E2026101600069`、平台交易单号 `6930529169563286869`。
> **只有运单号那个的 `title` 含「快递单号」**,所以规则用 `[title*="快递单号"]` 而不是 `.click-copy-link`。
## 4. 目标地址模板
在**基本设置**里改一处即可切到真实打包视频页,占位符:
| 占位符 | 含义 |
| --- | --- |
| `{code}` | 提取到的编号,**URL 编码**后填入 |
| `{rawcode}` | 同上但不编码 |
| `{host}` | 当前站点 host |
```
默认:https://www.baidu.com/?keyword={code}
将来:https://video.example.com/trace?keyword={code}&from=wms
```
单条规则还可以设**专属地址**(留空则用全局模板)。点击后按「打开方式」呈现:
**独立小窗**(默认)或**新标签页**。
## 5. 调规则:别刷页面,用「试跑」
配置页里的 **规则试跑** 用的是**当前表单里还没保存**的规则,所以可以边调边看:
- 输入类型选 `HTML 片段`,粘一段真实 DOM,点「试跑」;
- 它会模拟一个站点(默认 `wms.wms.gztbyc.com`,用于校验规则的「生效站点」),
列出**命中的编号 + 最终目标地址**,并给出**二次加工后的 HTML**;
- 0 命中时会把每条启用规则的「生效站点 / 选择器 / 正则」列出来,方便判断是**站点被过滤了**还是**没匹配上**;
- 点「填入 WMS 取样」可以一键载入内置样例。
工具栏弹窗则用来确认**线上是否真的生效**:显示「本页命中 N」+ 编号清单(点一条可直接打开)。
## 6. 自测页
```powershell
# 任选一种方式打开 test/wms-mock.html
npx --yes http-server extension/test -p 7310 # → http://127.0.0.1:7310/wms-mock.html
```
(也可以直接双击打开 `file://`,但要在扩展详情里额外开启「允许访问文件网址」。)
预期:表格里 **3 个运单号**被标记(青色虚线下划线 + ▶ 角标),其余 9 个蓝色文本不受影响。
## 7. 行为约定
- **点击拦截**在捕获阶段完成,`preventDefault + stopImmediatePropagation`,不会触发宿主页的委托逻辑,
也不会让外层 `<a>` 跳走。
- **修饰键放行**:按住 <kbd>Ctrl</kbd> / <kbd>⌘</kbd> / <kbd>Alt</kbd> / <kbd>Shift</kbd> 点击 = 不拦,
交还给页面原本的行为。
(gztbyc WMS 上那个运单号 span 原本是「点击复制二维码」,想用原功能就按住 Ctrl 点。)
- **SPA 友好**:`MutationObserver`(默认 400ms 防抖)盯着新增节点和文本变化自动补标;
自己也写了 DOM 会触发观察器,用 `quietUntil` 时间窗把这类回声挡掉,避免无限重扫。
- **完整可撤销**:关掉总开关、改规则、或当前站点不在生效范围时会 `unmark()`——
wrap 模式把 `<span>` 换回纯文本,selector 模式把类名 / `data-pst-*` / 被覆盖的 `title` / 加过的 `tabindex` 全部还原。
- **上限保护**:单次扫描最多看 `maxNodes`(默认 5000)个文本节点、单页最多标 `maxMarks`(默认 400)处,
超了会截断并在弹窗里显示 `N+`。
## 8. 权限与安全
| 权限 | 用途 |
| --- | --- |
| `storage` | 存规则配置(优先 `storage.sync`,超 8KB 单项配额自动退到 `storage.local` 并提示) |
| content script `matches: http(s)://*/*` | 需要注入任意第三方系统,无法预先枚举域名 |
- 不请求 `tabs` / `scripting` / `cookies`,**不读页面 cookie,不发任何请求**:
点击只是把算好的 URL 交给 `chrome.tabs.create` / `chrome.windows.create`。
- 注入走隔离世界(ISOLATED),不注入页面上下文,不受宿主页 CSP 影响。
- 想收窄范围:改 `manifest.json` 里 `content_scripts[0].matches` 为具体域名(如 `https://wms.wms.gztbyc.com/*`),
重新加载扩展即可;规则层面的范围由「生效站点」控制。
- 页面上不想要的可加 `data-pst-skip` 属性(能改页面时),引擎会整棵子树跳过。
## 9. 踩过的坑(都已修,改代码时注意)
- **`border-color` 不能放进 `transition`**:`border-bottom-color` 未指定时计算值是 `currentColor`
(宿主页链接色,实测 `#409eff`),一旦参与过渡,标记出来的**第一帧**是不确定的宿主色
——每标一处都闪一下蓝。实测 `0ms = rgb(64,158,255)` → `150ms = rgb(14,165,164)`,去掉后立即正确。
- **`tools/make-icons.ps1` 必须保持纯 ASCII**:PowerShell 5.1 在中文机器上把**无 BOM** 的 `.ps1`
按 GBK 读,UTF-8 中文变乱码;乱码落进 `("{0}" -f $x)` 这类格式串里会直接报
`Input string was not in a correct format` 而中断脚本。
- **命中数不能只看 `applyMarks` 的返回值**:它只处理「还没标过的」节点,滚动/翻页是增量补标,
返回值只是本轮新增。所以 `status` 里的清单是**直接数 DOM 上的 `.pst-trace-mark`**(`collectItems`)。
- **`chrome.tabs.sendMessage` 要指定 `frameId: 0`**:页面里多个 iframe 都注入过脚本,
不定帧会拿到不确定的那个回复。
- **`unmark` 的账要记清**:`tabindex` / `title` 可能本来就是页面自己的,只有我们记过账
(`data-pst-tab` / `data-pst-title`)的才还原。
- nunjucks 无关但同类教训:**新加的类名前缀统一用 `pst-`**,避免和宿主页或本项目其它样式撞名。
## 10. 下一步(还没做)
- 把目标地址换成真实的打包视频页(后端需要提供 `GET /api/.../trace?keyword=<运单号>` 之类的接口)。
- 需要「先查有没有视频、再决定是否标记」时,把 `content.js` 的 `runScan()` 前接一次
`fetch`(要加对应域名的 `host_permissions`),或改成点击时才查。
- 一次报多张运单(`+1` 那个展开按钮)目前只取折叠时显示的第一个编号。