# 云仓视频溯源 · 单号注入扩展
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:build # 只打包(extension/out/ 下产出 .crx / updates.xml / extension-id.txt)
npm run extension:publish # 打包 + 上传到服务器 /download/extension/ + 刷新 nginx
```
- 私钥 `extension/keys/key.pem`(首次运行自动生成,**务必单独备份**):它决定**扩展 ID**,
换了私钥 = 换了 ID = 已经下发到客户机的策略全部失效;
- 服务器上:`/download/extension/updates.xml`(**不缓存**,浏览器靠它自动升级)、
`/download/extension/YuncangTraceExtension-.crx`(文件名带版本号,长缓存);
- 客户机:桌面端「工具 → **安装谷歌插件**」→ 允许一次 UAC → 写 HKLM 策略:
```
Chrome/Edge ExtensionInstallForcelist = <扩展ID>;https://<域名>/download/extension/updates.xml
Chrome/Edge ExtensionInstallSources = https://<域名>/download/extension/*
```
重启浏览器即自动装好(`chrome://extensions` 里显示「由你的组织管理」)。
「工具 → 卸载谷歌插件」只会删掉值里带 `/download/extension/` 的那几条,不动别的策略。
没有管理员权限的机器仍可用「工具 → 复制插件路径(开发者模式)」手动加载。
## 1. 安装
### 客户机:从桌面端安装包直接加载(推荐)
桌面端安装包(MSI / EXE)已经把这个 `extension/` 目录一起装好,路径固定为
`%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 # ★ 只读状态页:同步状态 / 生效站点 / 前缀(不可编辑)
├── test/wms-mock.html # 自测页:按真实结构复刻的表格
└── tools/make-icons.ps1 # 生成图标(纯 ASCII,见文件头说明)
```
**没有构建步骤**:`rules.js` 挂在 `globalThis.PSTRules` 上,content script / popup / options 各自
用 `