- 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 密码,绝不入库)。
163 lines
9.7 KiB
Markdown
163 lines
9.7 KiB
Markdown
# 云仓视频溯源 · 单号注入扩展
|
||
|
||
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` 那个展开按钮)目前只取折叠时显示的第一个编号。
|