# 云仓视频溯源 · 单号注入扩展
Chrome / Edge 扩展(**Manifest V3 + 原生 JS,零构建**)。
它注入到**第三方 WMS / 后台页面**里,按规则找到「运单号」这类字段,在它**旁边**渲染一个
「▶ 查看打包视频」按钮(宿主元素一个字都不改);点击按钮打开溯源页面,把编号作为关键词带过去。
> 首个取样站点:`https://wms.wms.gztbyc.com/order/orderManagement`
> 运单号长这样:
> ```html
> title="点击复制并查看快递单号二维码">321408064481776
> ```
> 扩展会在它后面插一个按钮(插在 `+1` 展开按钮之前):
> ```html
> 321408064481776
>
> ```
> 点按钮 → 小窗打开 `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-.crx`(文件名带版本号,长缓存)——
这条链路现在只用于**内网/离线分发**,客户端不再写企业策略;
- 正式分发:
- **Edge**:加载项商店(已上架),
桌面端「工具 → 安装浏览器插件(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);隐私政策页已上线:
> (源码 `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 各自
用 `