packServer/extension/README.md
liufumingren 6f52613e5e feat(desktop): 下线 Edge 企业策略安装(扩展已上架商店)
- 工具菜单去掉「安装浏览器插件(企业策略:Chrome / Edge)」「卸载浏览器插件(企业策略)」,
  删除 Services/ExtensionInstaller.cs(.reg 生成 + 提权导入 + 注册表校验)
- 只保留「安装浏览器插件(Edge 应用商店)」与「复制插件路径(Chrome / 开发者模式)」;
  商店弹窗去掉「审核中会 404」的说法,Chrome 用户直接引导到开发者模式
- 文档同步(桌面 README / 后端 README / extension README / STORE-SUBMISSION / keys README):
  写清老机器上残留的 HKLM 策略怎么手工清理,避免和商店版同时注入
- extension:publish(.crx + updates.xml)保留,仅给内网/离线分发用

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-01 16:32:55 +08:00

305 lines
20 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 自带的「点击复制二维码」行为。
---
## 0. 配置从哪来(1.1.0 起)
**插件只拉取并执行,不提供本地配置**:
- 后台(`平台管理 → 插件配置`)维护**单号前缀**(`YT` / `SF` / `32`…)、**生效站点**、跳转模板、安装包地址;
单号正则由服务端拼好(`\b(?:YT|SF|…)\d{10,16}\b`)一起下发,插件端**不展示、不可改**;
- 插件每 **5 分钟**自动拉一次 `GET https://pack.wms.gztbyc.com/api/web/extension/config`
(`chrome.alarms`;浏览器启动/扩展安装时也会立刻拉一次),选项页/弹窗里还有「立即同步」;
- **版本没变就不写存储**(避免整页重扫);**拉取失败保留旧配置**(断网照常工作),错误显示在选项页;
- 插件里不再有:规则编辑、正则输入、试跑、导入导出、使用说明 —— 这些都在后台维护。
---
## 0.1 打包与分发
浏览器**不认「加载已解压」之外的本地目录**,所以正式分发必须打包成签名好的 `.crx`:
```powershell
cd backend
npm run extension:bundle # 只压缩源码 → extension/dist(esbuild minify,去注释压空白,约 1/3 体积)
npm run extension:build # 压缩 + 打包(extension/out/ 下产出 .crx / updates.xml / extension-id.txt)
npm run extension:publish # 压缩 + 打包 + 上传到服务器 /download/extension/ + 刷新 nginx
npm run extension:zip # 压缩 + 出商店上传包(extension/out/*.zip,条目名是标准 `/`)
```
**分发用的都是 `extension/dist`(压缩产物),开发调试仍用源码目录**:
- `extension/` = 源码(带完整注释),`chrome://extensions`「加载已解压」时选这个目录;
- `extension/dist/` = 压缩产物(`dist/` 已 gitignore,随时可重新生成),桌面端安装包和 `.crx` 都只用它;
- 只做 minify、**不做混淆**:MV3 的 CSP 禁止 `eval`/`new Function`(`debugProtection` 之类直接报错),
而且 Chrome/Edge 商店要求提交的代码可读;压缩后已经去掉全部注释、缩短了标识符,
真正需要保密的东西也不在插件里(前缀/正则/站点全部由服务端下发,私钥从不进包)。
- 私钥 `extension/keys/key.pem`(首次运行自动生成,**务必单独备份**):它决定**扩展 ID**;
- 服务器上:`/download/extension/updates.xml`(**不缓存**)、
`/download/extension/YuncangTraceExtension-<version>.crx`(文件名带版本号,长缓存)——
这条链路现在只用于**内网/离线分发**,客户端不再写企业策略;
- 正式分发:
- **Edge**:加载项商店(已上架)<https://microsoftedge.microsoft.com/addons/detail/mgdonmkicojkabgalgekobaoohaohfcj>,
桌面端「工具 → 安装浏览器插件(Edge 应用商店)」直接打开,点「获取」即可;
- **Chrome**:桌面端「工具 → 复制插件路径(Chrome / 开发者模式)」,到 `chrome://extensions`
开开发者模式、加载已解压的扩展程序。
> ⚠️ 早期版本用 `ExtensionInstallForcelist` 写 HKLM 策略装自建 CRX(ID `lkei…`),**该功能已下线**。
> 用过旧版本的机器策略仍在,会和商店版同时注入 —— 手动删掉 `...\Policies\Google\Chrome\ExtensionInstallForcelist`
> 与 `...\Policies\Microsoft\Edge\ExtensionInstallForcelist` 里值带 `/download/extension/` 的项
> 及同级 `ExtensionInstallSources`,重启浏览器即可。
没有管理员权限的机器仍可用「工具 → 复制插件路径(Chrome / 开发者模式)」手动加载(拿到的是安装目录里的压缩版)。
> 国内环境下 **Chrome 应用商店连不上**(实测 `chromewebstore.google.com`、`clients2.google.com` 均超时),
> 官方分发走 **Edge 加载项商店**(可达、免费)。上架文案、权限说明、截图清单、审核应对
> 见 [STORE-SUBMISSION.md](./STORE-SUBMISSION.md);隐私政策页已上线:
> <https://pack.wms.gztbyc.com/extension-privacy.html>(源码 `frontend/public/extension-privacy.html`)。
## 1. 安装
### 客户机:从桌面端安装包直接加载(推荐)
桌面端安装包(MSI / EXE)已经把插件的**压缩产物**装到固定路径
`%LOCALAPPDATA%\Programs\YuncangTrace\extension`(源码、私钥都不进包):
1. 桌面端软件菜单「**工具 → 复制插件路径(开发者模式)**」(复制的是 Windows 路径,可直接粘进选择框)。
2. 打开 `chrome://extensions`(Edge 是 `edge://extensions`)→ 右上角打开 **开发者模式**。
3. 点 **加载已解压的扩展程序**,把刚复制的路径粘进去。
4. 刷新一下已经打开的 WMS 页面(扩展只对**安装之后**加载的页面生效)。
### 开发:直接加载仓库目录
1. 打开 `chrome://extensions`(Edge 是 `edge://extensions`)。
2. 右上角打开 **开发者模式**。
3. 点 **加载已解压的扩展程序**,选择本目录 `extension/`。
4. 刷新一下已经打开的 WMS 页面(扩展只对**安装之后**加载的页面生效)。
图标缺失时重新生成:`powershell -ExecutionPolicy Bypass -File tools\make-icons.ps1`
## 2. 目录结构
```
extension/
├── manifest.json # MV3 声明;permissions = storage + alarms,host_permissions 含后端域名
├── 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:打开目标地址 + **每 5 分钟拉取服务器配置**
│ ├── popup.html/.css/.js # 工具栏弹窗:配置版本、本页命中清单、重新扫描、立即同步
│ └── options.html/.js # ★ 只读状态页:同步状态 / 生效站点 / 前缀(不可编辑)
├── dist/ # 压缩产物(npm run extension:bundle 生成,不进仓库)
├── 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` 才需要重装)。
**分发才有打包步骤**:`npm run extension:bundle` 用 esbuild 逐文件压缩(**不合并文件**,
所以 `importScripts('lib/rules.js')` 和各处路径原样有效)输出到 `extension/dist`;
桌面端安装包与 `.crx` 都只打 `dist`。改了 `src/` 之后记得重跑一次(`build.ps1` 会自动跑)。
## 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 已移除)。当前版本只下发**一条**文本规则(前缀 + 位数),
所以下表这种「按选择器/属性抽编号」的写法暂时用不上 —— 它属于 `rules.js` 引擎仍然支持、但插件端不再暴露的能力。
因为是 `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">`(无任何视觉、不带可点类名、不拦点击);它是原文照抄的,
所以被匹配到的那段文字没变。
- 按钮文案是固定的默认值「查看打包视频」(`DEFAULT_BUTTON_TEXT`);`actionMode` 由 `defaultConfig()` 决定,插件端不提供入口。
- 提醒:按钮是真实 DOM,所以**容器元素的 `textContent` 会多出按钮文案** —— 这是插入 UI 的必然结果,
被匹配的那段文字本身没有被改动。
### 识别规则(服务器下发,唯一一条)
**只有一条文本规则**,内容由服务器按后台维护的**前缀**拼出来:
| id | 说明 | 生效站点 | 默认 |
| --- | --- | --- | --- |
| `remote` | `\b(?:YT\|SF\|JD\|ZTO\|YTO\|STO\|EMS\|DBL\|32\|77)\d{10,16}\b`(flags `g`) | 后台配的生效站点 | 由后台开关控制 |
- **只维护前缀**:后台「平台管理 → 插件配置」里加/删前缀(`YT`、`SF`、`32`…),
正则由后端 `buildPattern()` 拼好一起下发;插件端 `applyRemote()` 只把它当成一条 `text` 规则,**不解析、不展示**。
- 前缀后面必须跟 **10~16 位数字**(后台也可调,默认 10~16):所以 `321408064481776`(`32` 开头)会被命中,
而同一行的波次号 `E2026101600069`、发货单号 `JY2026101619599`、平台交易单号、17 开头的毫秒时间戳都不会;
- ⚠️ **数字前缀(`32` / `77`)最容易被内部 ID、订单号一起点亮** —— 发现误标就在后台把那个前缀删掉。
- 规则是**区分大小写**的(flags 只有 `g`):前缀统一存成大写,`yt1234…` 不会被点亮。
- `src/lib/rules.js` 里仍保留一条内置的 `express` 规则,**只作兜底**:首次安装还没同步成功时用它,
同步成功后会被服务器那条 `remote` 整个替换掉。
## 4. 目标地址模板
在后台「插件配置」里改(网页模板 / 唤起协议),占位符:
| 占位符 | 含义 |
| --- | --- |
| `{code}` | 提取到的编号,**URL 编码**后填入 |
| `{rawcode}` | 同上但不编码 |
| `{host}` | 当前站点 host |
```
默认:https://www.baidu.com/?keyword={code}
将来:https://video.example.com/trace?keyword={code}&from=wms
```
点击后按本地偏好呈现:**独立小窗**或**新标签页**(`openMode`,不再由服务器下发,避免每台机器行为不一致)。
## 5. 配置同步与排障
| 触发 | 频率 |
| --- | --- |
| 定时(`chrome.alarms`) | 每 5 分钟 |
| 扩展安装 / 浏览器启动 | 立刻一次 |
| 选项页 / 弹窗「立即同步」 | 手动 |
- 拉的是 `GET https://pack.wms.gztbyc.com/api/web/extension/config`(可用
`chrome.storage.local.pstConfigUrl` 覆盖,联调环境用);
- **安装包地址不用后台配**:每次同步还会读一次 `GET https://pack.wms.gztbyc.com/download/version.json`,
取里面的 `downloadUrl` 写进配置(和网页顶栏「下载桌面端」同一份,永远是最新发布版本);
只有 version.json 拉不到时才退回后台配置里那个值、再退回上一次的值;
- 返回 `{ ok, data: { version, enabled, hosts, prefixes, pattern, flags, urlTemplate, appUrlTemplate, downloadUrl } }`;
- **版本相同不写存储**:`pstConfig.remote.version` 与服务器一致就跳过,页面不会被无谓重扫;
- **失败保留旧配置**(断网/后端挂了照常工作),错误写进 `chrome.storage.local.pstSyncState`,选项页显示;
- 写配置后会触发 `chrome.storage.onChanged`,content script 自己 `unmark()` + 重扫,**不用刷新页面**。
排障入口:选项页(同步状态/上次错误/生效站点/前缀)→ 弹窗(本页命中清单)→ `chrome://extensions` 的
「Service Worker → 检查」里看 `syncConfig()` 的报错。
## 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`) |
| `alarms` | 每 5 分钟定时拉配置(MV3 的 service worker 会被回收,不能用 `setInterval`) |
| `host_permissions: https://pack.wms.gztbyc.com/*` | 拉 `GET /api/web/extension/config` |
| `host_permissions: http(s)://localhost:17300/*` | 探测本机软件是否在跑(协议唤起兜底) |
| content script `matches: http(s)://*/*` | 需要注入任意第三方系统,无法预先枚举域名 |
- 不请求 `tabs` / `scripting` / `cookies`,**不读页面 cookie**;唯一的出站请求就是上面那个配置接口
(以及本机 17300 的探测)。点击只是把算好的 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` 那个展开按钮)目前只取折叠时显示的第一个编号。