packServer/extension/STORE-SUBMISSION.md
liufumingren 9b37101a7b docs(extension): Edge 商店上架材料 + 扩展隐私政策页
国内实测 Chrome 商店不可达(chromewebstore.google.com / clients2.google.com 均超时),
Edge 加载项商店 200/0.43s 可达,所以官方分发走 Edge 商店。

- extension/STORE-SUBMISSION.md(新):上架检查清单、中英文 listing 文案、逐条权限用途说明、
  数据使用声明、截图清单、审核退回应对、上架后 ID 变化与升级流程、现场操作对照;
- frontend/public/extension-privacy.html(新):隐私政策页,随前端构建发布到
  https://pack.wms.gztbyc.com/extension-privacy.html(npm run deploy 会自动带上);
- extension/README.md:分发章节补上「国内走 Edge 商店」与上面两份文档的入口。

扩展 1.1.2(压缩产物 + 跳转默认值修复)已发布到线上:
updates.xml -> YuncangTraceExtension-1.1.2.crx(27766 字节,200)。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-01 04:03:58 +08:00

157 lines
9.5 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.

# Edge 加载项商店 · 上架材料包
> 结论:**国内只走 Edge 加载项商店**。Chrome 应用商店在这条网络里连不上
> (实测 `chromewebstore.google.com` 与 `clients2.google.com` 均超时),上架也装不了;
> 而 `microsoftedge.microsoft.com/addons` 实测 200 / 0.43s,Edge 又是 Win10/11 自带。
>
> 本文所有文案可直接复制到 Microsoft Partner Center。
## 0. 为什么是 Edge(三条分发路线对比)
| 路线 | 覆盖谁 | 国内可用 | 现状 |
|---|---|---|---|
| **Edge 加载项商店** | 所有 Edge 用户,**非受管/非开发者模式也能一键装** | ✅ | 待上架(免费) |
| 企业策略 + 自建 CRX | 仅**受管设备**(加域 / Intune / 组策略) | ✅ | 已实现:菜单「安装谷歌插件」 |
| 开发者模式手动加载 | 任何 Chromium 内核浏览器 | ✅ | 已实现:菜单「复制插件路径(开发者模式)」 |
非受管电脑上 `ExtensionInstallForcelist` 会被 Chrome/Edge 拒绝(`[BLOCKED]`,提示"此设备并非由你的组织管理"),
所以**普通员工电脑只有商店这条路**。
## 1. 上架前检查清单
- [x] `manifest.json` 里**没有** `update_url`、**没有** `key`(商店会拒)
- [x] `name` 13 字符、`description` 69 字符(限制:name ≤ 45 / description ≤ 132)
- [x] `minimum_chrome_version: 96`(Edge 同内核,兼容)
- [x] 权限最小化:`storage` + `alarms`,host 只有本机服务与本项目后端
- [x] 隐私政策页面已上线:<https://pack.wms.gztbyc.com/extension-privacy.html>
(源码 `frontend/public/extension-privacy.html`,随前端一起发布)
- [x] 商店上传包:`extension/out/YuncangTraceExtension-<version>.zip`
(`cd backend && npm run extension:zip`,条目名是标准 `/`,`manifest.json` 在根目录)
- [ ] Microsoft Partner Center 账号(免费):<https://partner.microsoft.com/dashboard/microsoftedge/>
- [ ] 截图 3~5 张(见第 4 节)
- [ ] 确认隐私政策里的联系邮箱(当前写的 `support@gztbyc.com`,需要你确认或替换)
## 2. 商店字段(直接复制)
**扩展名称(Name)**
```
云仓视频溯源 · 单号注入
```
**简短描述(Short description,≤132 字符)**
```
在自家 WMS/后台页面识别运单号,一键打开打包视频溯源;识别规则与生效站点由管理员集中维护。
```
**详细描述(Detailed description)**
```
【它是做什么的】
在贵司自己的仓储管理系统、打单后台等网页上,自动识别运单号(如 YT1234567890123),
在单号旁加一个入口:点一下就能打开这段录像的打包视频溯源页面;装了桌面客户端的话,
会直接唤起客户端播放,无需手工复制粘贴单号再查询。
【为什么需要"访问所有网站"】
不同客户用的 WMS 来自不同供应商,域名、内网 IP 各不相同,无法在安装时预先枚举。
因此扩展在安装时申请了全站访问,但**只有当站点在管理员配置的白名单里时才会工作**;
其它网站上脚本立即退出,不读取、也不修改页面内容。
【安全与隐私(重点)】
· 页面内容只在你的浏览器本地匹配,**不上传**任何页面内容、截图或浏览记录;
· 识别到的单号只交给**同一台电脑上**安装的桌面客户端(localhost),不经过互联网;
· 扩展只从服务器拉取只读配置(生效站点、单号前缀、跳转模板),**不下发任何代码**;
· 不收集账号密码、不投放广告、不向第三方出售数据。
完整说明:https://pack.wms.gztbyc.com/extension-privacy.html
【怎么用】
1) 管理员在后台「平台管理 → 插件配置」维护单号前缀与生效站点;
2) 员工在 WMS 页面正常操作,单号会自动带上下划线/入口;
3) 点单号 → 打开溯源页面或唤起桌面客户端。配置每 5 分钟自动同步一次,改完无需重新安装。
```
**English(可选,建议一起填)**
```
Name: Yuncang Trace · Tracking No. Link
Short: Detect tracking numbers on your own WMS pages and open the packaging-video trace page in one click.
Detail:
This extension detects tracking numbers (e.g. YT1234567890123) on your company's WMS / shipping
admin pages and turns them into clickable links that open the corresponding packaging-video trace,
or launch the desktop client installed on the same PC.
Why "read and change all your data on all websites": every customer uses a different WMS vendor with
different domains or intranet IPs, so they cannot be pre-listed at install time. The content script
only runs its matching logic when the current site is on an allow-list maintained by the administrator;
on every other site it exits immediately and neither reads nor modifies the page.
Privacy: page text is matched locally and never uploaded; a detected tracking number is handed to the
desktop client on the same computer (localhost) only; the extension downloads read-only configuration
(no remote code); no accounts, no ads, no data sold to third parties.
Policy: https://pack.wms.gztbyc.com/extension-privacy.html
```
**其它字段**
| 字段 | 填什么 |
|---|---|
| 类别(Category) | Productivity(效率) |
| 语言 | 中文(简体)+ English |
| 隐私政策 URL | `https://pack.wms.gztbyc.com/extension-privacy.html` |
| 支持/主页 URL | `https://pack.wms.gztbyc.com/` |
| 联系邮箱 | `support@gztbyc.com`(**待确认**) |
| 定价 | 免费 |
## 3. 权限用途说明(审核问到时逐条贴)
| 权限 | 给审核的说明(中) | Justification (EN) |
|---|---|---|
| `storage` | 在本机保存管理员下发的配置与同步状态,不上传。 | Stores the administrator-provided configuration and last-sync state locally. |
| `alarms` | 每 5 分钟拉取一次配置,保证管理员改完尽快生效。 | Periodic (5 min) refresh of the read-only configuration. |
| `content_scripts` 全站(`http://*/*`, `https://*/*`) | 客户的 WMS 域名/内网地址无法预知,需在页面上识别运单号;实际只在白名单站点工作,其它站点立即退出且不读取 DOM。 | Customers' WMS hosts cannot be enumerated in advance. Matching only runs on an allow-listed site; otherwise the script exits without reading the DOM. |
| `host_permissions: https://pack.wms.gztbyc.com/*` | 只用于拉取只读配置与最新客户端版本信息。 | Fetches read-only configuration and the latest client version info. |
| `host_permissions: http://localhost:17300/*`、`http://127.0.0.1:17300/*` | 与本机安装的桌面客户端通信(判断是否安装、传递运单号)。 | Talks to the desktop client installed on the same machine (availability probe and tracking-number hand-off). |
**数据使用声明(Data usage 表单)**:全部选「不收集」——
只做本地匹配;不收集浏览历史、页面内容、个人身份信息、位置、财务信息;
不用于广告或画像;不出售给第三方。
(如果表单强制要求勾选"处理网站内容",就选「仅在本地处理,不上传」。)
## 4. 需要的截图(1280×800 或 640×400,PNG/JPG)
1. **注入效果**:`extension/test/wms-mock.html` 里单号带下划线/按钮的样子(最能说明用途);
2. **点击后的溯源页面**:桌面客户端或网页端播放界面;
3. **扩展选项页**:同步状态(版本号、生效站点、前缀)——说明配置集中管理;
4. 可选:桌面端「工具」菜单(安装/卸载/复制路径)。
> 截图里**不要出现**真实客户名、真实运单号、真实手机号;用测试数据。
## 5. 审核常见退回原因与应对
| 退回理由 | 应对 |
|---|---|
| "访问所有网站"权限过宽 | 贴第 3 节的说明 + 第 2 节的"为什么需要全站"段落;强调**运行时白名单**约束 |
| 描述太笼统,看不出单一用途 | 用第 2 节的详细描述(单一用途:在 WMS 页面识别单号并跳转溯源) |
| 缺少隐私政策 | 已经有:`https://pack.wms.gztbyc.com/extension-privacy.html`(上架前确认能打开) |
| 疑似远程代码 | 说明只下发**配置数据**(JSON),用 `new RegExp(字符串)` 编译,无 eval / 无远程 JS |
| 功能需要登录才可用 | 审核说明里写:功能依赖客户自有 WMS 与管理员配置;附带 `test/wms-mock.html` 的演示说明与截图 |
## 6. 上架之后要注意
1. **扩展 ID 会变**:商店用微软的密钥签名,ID 不再是 `lkeibbccgdddjamahnkibopcpidhgggk`(那是 `extension/keys/key.pem` 算出来的自建 ID)。
- 商店版:用户在 Edge 加载项页面点「获取」即可,**不需要**写策略;
- 自建 CRX(受管设备):继续用现有 ID 与 `updates.xml`,两条线互不影响。
2. **升级流程**:改代码 → 改 `manifest.json` 的 `version` → `cd backend && npm run extension:zip` →
在 Partner Center 上传新 zip → 审核通过后用户自动升级(Edge 端的自建 CRX 仍走 `npm run extension:publish`)。
3. 商店版和自建 CRX 版**不能同时装**在同一浏览器(同一扩展名会冲突)——现场二选一。
## 7. 现场操作对照
| 场景 | 操作 |
|---|---|
| 员工电脑(非受管)、用 Edge | 打开加载项商店页面 → 「获取」 |
| 员工电脑(加域 / 受管) | 桌面端「工具 → 安装谷歌插件」(写 HKLM 策略 + 自建 CRX) |
| 临时/无管理员权限 | 桌面端「工具 → 复制插件路径(开发者模式)」→ `edge://extensions` 加载已解压 |
| 国产 Chromium 浏览器(360/QQ/搜狗) | 多数支持"加载已解压的扩展程序",用同一条路径 |