packServer/extension/README.md

227 lines
14 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://wms.wms.gztbyc.com/order/orderManagement`
> 运单号长这样:
> ```html
> <span class="click-copy-link" role="button" tabindex="0"
> title="点击复制并查看快递单号二维码">321408064481776</span>
> ```
> 扩展会在它后面插一个按钮(插在 `+1` 展开按钮之前):
> ```html
> <span class="click-copy-link" …>321408064481776</span>
> <button class="pst-trace-mark pst-trace-btn" data-pst-code="321408064481776"
> data-pst-url="https://www.baidu.com/?keyword=321408064481776">查看打包视频</button>
> ```
> 点按钮 → 小窗打开 `https://www.baidu.com/?keyword=321408064481776`。
> 原来的运单号仍保留 WMS 自带的「点击复制二维码」行为。
---
## 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. 匹配方式 × 加工方式
**匹配(怎么找)**
| 方式 | 适用 | 关键字段 |
| --- | --- | --- |
| **CSS 选择器** | 元素本身好定位,**或编号在属性里** | `selector` + `attr`(空 = 取元素文本)+ 可选 `pattern` |
| **文本正则** | 页面结构会变、但有稳定的编号格式(`YT1234…`) | `pattern` + `flags`(必填,可用 `exclude` 排除) |
- `pattern` 的**第 1 个捕获组**会被当成编号(`{code}` 的值);没写捕获组就用整个匹配。
- 选择器模式下 `pattern` 是**可选**的:填了就从「`attr` 取到的值 / 元素文本」里**再抽一次**编号。
- ⚠️ **属性里的值只能用选择器模式**:文本正则只遍历文本节点,拿不到属性值。
### 例:编号藏在 `javascript:` 链接里
```html
<a href="javascript:MM_openTrace('../system/view-trace!viewTrace.jspb?postNum=202610101621&amp;wareHouseId=5400')">
202610101621
</a>
```
这条的编号既在链接文字里、也在 `href` 的 `postNum=` 参数里。两种写法都行:
| 写法 | selector | attr | pattern | 说明 |
| --- | --- | --- | --- | --- |
| **从属性抽(推荐)** | `a[href*="postNum="]` | `href` | `postNum=([0-9A-Za-z_-]+)` | 不依赖链接文字,文字被改成「查看轨迹」也照样能取到编号 |
| 取链接文字 | `a[href*="postNum="]` | *(空)* | *(空)* | 简单;引擎会对取到的文本 `trim()`,那一大串换行/制表符会被去掉 |
内置示例规则不再默认带着这种结构(2026-10-17 已移除);真要处理 旧版 JSP 轨迹链接,在配置页自己加一条规则(下表两种写法都行)。
因为是 `button` 加工方式,按钮插在 `<a>` **之后**,`<a>` 自己那个 `javascript:MM_openTrace(...)` 照旧能用。
**加工(找到之后干什么)**
| 方式 | 行为 | 适合 |
| --- | --- | --- |
| **`button`(默认)** | 命中元素**一个字都不改**,只在它旁边插一个「查看打包视频」兄弟按钮 | 元素本身有自己的点击行为(比如「点击复制二维码」),不能抢 |
| **`chip`** | 命中元素**自己**变成可点(加类名 / 改写 `title` / 接管点击);可配下划线 / 高亮 / 胶囊 + ▶ 角标 | 命中处本来只是普通文字 |
- `button` 方式是**零侵入**的:
- 不加类名、不改 `title`、不动 `role` / `tabindex`、**不接管它的点击** → 页面原有的行为完全不受影响;
- 只往宿主元素上写 `data-pst-code` / `data-pst-rule` 两个属性当「已处理」记号
(`data-*` 对事件和渲染没有任何影响),撤销时一并摘掉;
- 按钮插在命中元素之后;若命中元素在 `<a>` 里,则退到那个 `<a>` 之后
—— `<button>` 嵌进 `<a>` 是非法嵌套。
- `chip` 方式下点击会被脚本在捕获阶段拦掉(`preventDefault + stopImmediatePropagation`),
所以**原元素自己的点击不会再触发**;想用原功能就按住修饰键点(见「行为约定」)。
- `text` 正则 + `button`:因为要把按钮放到「命中位置的旁边」,必须包一层**纯定位**的
`<span class="pst-trace-anchor">`(无任何视觉、不带可点类名、不拦点击);它是原文照抄的,
所以被匹配到的那段文字没变。
- 按钮文案在**基本设置**里配(默认「查看打包视频」);全局和单条规则都能设 `actionMode`,规则留空则跟随全局。
- 提醒:按钮是真实 DOM,所以**容器元素的 `textContent` 会多出按钮文案** —— 这是插入 UI 的必然结果,
被匹配的那段文字本身没有被改动。
### 内置规则
**只内置一条**(实测这一条就能盖住真实页面的单号):
| id | 说明 | 生效站点 | 默认 |
| --- | --- | --- | --- |
| `express` | 文本规则 `\b(?:YT\|SF\|JD\|ZTO\|YTO\|STO\|EMS\|DBL\|32\|77)\d{10,16}\b`(`gi`) | 全部 | 开 |
- **前缀表就是唯一要维护的地方**:在 `src/lib/rules.js` 的 `EXPRESS_PREFIXES` 里往数组里追加新前缀即可
(以前没出现过、又确实出现在单号开头的就加进去)—— 正则会跟着拼出来,**不用改正则本身**:
```js
const EXPRESS_PREFIXES = [ 'YT', 'SF', 'JD', 'ZTO', 'YTO', 'STO', 'EMS', 'DBL', '32', '77' ];
const EXPRESS_PATTERN = '\\b(?:' + EXPRESS_PREFIXES.join('|') + ')\\d{10,16}\\b';
```
- 前缀后面必须跟 **10~16 位数字**(`\d{10,16}`):所以 `321408064481776`(WMS 运单号,`32` 开头)会被命中,
而同一行的波次号 `E2026101600069`、发货单号 `JY2026101619599`、平台交易单号、17 开头的毫秒时间戳都不会;
- ⚠️ **数字前缀(`32` / `77`)最容易被内部 ID、订单号一起点亮** —— 发现误标就把那个前缀拿掉,或者给规则加 `exclude`;
- 其它匹配方式(CSS 选择器 / 从 `href` 抽编号 / 按 `data-*` 取值)**不再内置示例**,需要时在配置页自己加一条即可,写法见上面的例子;
- **升级迁移(config version 1 → 2)**:扩展升级后第一次打开配置页/页面时,会
① 把已移除的示例规则(`wms-waybill` / `numeric` / `legacy-postnum` / `dom-attr`)从你的规则里剔掉,
② 内置的 `express` 如果还是老正则(说明你没改过它)就换成带新前缀表的正则 ——
**你自己加的规则、以及你改过的 `express` 都不动**(见 `upgradeRules()`)。
## 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 个运单号**旁边各多一个「▶ 查看打包视频」按钮(插在运单号和 `+1` 之间),
其余 9 个蓝色文本不受影响;页面底部那行 `SF1234567890123` 也会被文本正则命中并插按钮。
## 7. 行为约定
- **默认(button)模式下完全不碰宿主元素**:命中元素的点击、样式、`title` 全部原样,
只有我们自己新插的那个按钮会响应点击。
- **chip 模式下**点击拦截在捕获阶段完成(`preventDefault + stopImmediatePropagation`),
不会触发宿主页的委托逻辑,也不会让外层 `<a>` 跳走;此时可以用修饰键放行 ——
按住 <kbd>Ctrl</kbd> / <kbd>⌘</kbd> / <kbd>Alt</kbd> / <kbd>Shift</kbd> 点击就不拦,交还给页面原本的行为。
- **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` 而中断脚本。
- **`acceptTextNode` 的「已处理」判断必须看 `data-pst-code`,不能只看类名**:button 模式不给宿主元素加类名,
只看类名会让 text 正则规则把同一个编号再包一遍,插出第二个按钮。
- **button 模式要能跨重扫去重**:`applyMarks` 只处理「还没标过」的节点,而 button 模式的宿主元素**永远不带 markClass**,
每轮增量重扫都会重新命中它 → 靠 `data-pst-code` 记号 + `existingButton()`(看 `nextElementSibling`)两道保险,
实测连续 `applyMarks` 5 次仍然是 3 个按钮。
- **命中数不能只看 `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` 那个展开按钮)目前只取折叠时显示的第一个编号。