一、UI
- 主界面删除「已注册 yuncang://(网页可叫醒本软件)」整行(`ProtocolText`),
行定义 4→3(标题 / 查询 / 日志);删除 `UpdateProtocolState()` 及其调用。
协议对用户是内部实现,不展示;注册由 MSI 完成、卸载自动删除、启动自动校正。
二、修复(本次测试暴露的真实缺陷)
1. **更新检查提前到登录之前**(`App.OnStartup`):
原来放在 `ShowMainWindow()` 之后,一旦本地令牌失效/未登录,软件停在登录窗,
**永远不会检查更新**(实测 1.0.7 → 1.0.8 卡在登录窗 180s 未更新)。
2. **`ApiClient.MeAsync` 不再把网络错误当成"令牌失效"**:
原来 catch(ApiException) → return null,调用方据此 `SessionStore.Clear()`,
后端启动中/一时连不上就会**误删 session.json**(本次就丢了登录态)。
现在只有 401/403 返回 null;超时/连不上/5xx 抛异常 → 登录窗保留令牌并提示,
下次启动仍可自动登录。
三、验证(标准流程:打包 → 启动旧版 → 自动更新)
- 打包 1.0.9(含修复)并安装(旧版 1.0.7 因缺陷无法自更新,只能手工升级一次);
- 打包 1.0.10 → `test-update.ps1`:
当前安装 1.0.9(**处于登录窗,未登录**)→ 后端目标 1.0.10
[4s] 1.0.9 → [10s] 1.0.10
✔ 自动更新完成:1.0.9 → 1.0.10(耗时 10.1s)
✔ 本机服务 17300 有响应(HTTP 401)
✔ 软件进程已恢复
证明「未登录也能检测并完成更新」。
四、待用户操作:本次测试中 session.json 被旧逻辑误删,需要**重新登录一次**;
之后的版本不会因为网络抖动再丢登录态。
430 lines
24 KiB
Markdown
430 lines
24 KiB
Markdown
# 云仓视频溯源软件(本机服务 / WPF)
|
||
|
||
Windows 桌面端,用**前端 `/local` 公共页**和 **Chrome 插件**做对接:
|
||
|
||
- **登录页**:账号密码登录后端(`POST /api/web/auth/login`)拿 user JWT,令牌存本机;
|
||
下次启动先用 `/api/web/me` 验证,还有效就直接进主界面;
|
||
- 在 `127.0.0.1:17300` 起一个本机 HTTP 服务,浏览器里的页面直接查询本机数据;
|
||
- 注册 `yuncang://` 启动协议,网页可以「叫醒」本软件(前提是已安装);
|
||
- **托盘图标**:关窗口只是缩到托盘(本机服务不能因关窗断掉),双击托盘恢复窗口,
|
||
右键菜单有「打开主界面 / 重启软件 / 服务地址(只读)/ 退出」;
|
||
- **主界面不展示服务地址**:端口/地址属于内部实现细节,用户只需知道「能用」;
|
||
状态点 + 「运行中 · http://localhost:17300」已经够判断死活。
|
||
- **防多开**:全局互斥体 + 命名管道 —— 第二个实例不会抢 17300 端口,而是把
|
||
`yuncang://open?code=xxx` 转给已运行的实例(在托盘里也会被叫出来并直接查询),然后自己退出。
|
||
|
||
```
|
||
desktop/
|
||
├── YuncangTrace.LocalService.csproj # net8.0-windows + UseWPF + UseWindowsForms(托盘)
|
||
├── app.manifest # 高 DPI / 兼容性声明
|
||
├── Assets/app.ico # 程序/托盘图标(tools/make-icon.ps1 生成)
|
||
├── App.xaml / App.xaml.cs # 防多开 + 托盘 + 登录流程 + 本机服务生命周期
|
||
├── LoginWindow.xaml / .xaml.cs # 服务器地址 / 账号 / 密码 / 记住账号 / 自动恢复登录
|
||
├── MainWindow.xaml / .xaml.cs # 服务状态、地址、协议注册、测试查询、日志、退出登录
|
||
└── Services/
|
||
├── LocalHttpServer.cs # HttpListener + CORS + PNA
|
||
├── OrderQueryService.cs # ★ 按运单号查数据(接真实数据源的地方)
|
||
├── ApiClient.cs # 登录 / 校验令牌(用到的全部后端接口)
|
||
├── SessionStore.cs # 登录态(%LOCALAPPDATA%\YuncangTrace\session.json)
|
||
├── AppSettings.cs # 服务器地址 / 记住账号(%LOCALAPPDATA%\YuncangTrace\settings.json)
|
||
├── ProtocolHelper.cs # yuncang:// 注册/反注册、解析 code
|
||
├── SingleInstance.cs # 互斥体 + 命名管道转发参数(防多开)
|
||
├── TrayIconService.cs # 托盘图标与菜单
|
||
├── AppLog.cs # 全局日志缓冲(窗口没开时的日志也不丢)
|
||
└── JsonUtil.cs # JSON 序列化(中文不转义)
|
||
```
|
||
|
||
## 登录 / 托盘 / 防多开的行为
|
||
|
||
| 场景 | 行为 |
|
||
| --- | --- |
|
||
| 首次启动 | 先起本机服务(17300)与托盘,再弹登录页 → 登录成功才出主窗口 |
|
||
| 已有令牌 | 登录窗一闪而过:`/api/web/me` 通过就直接进主窗口;失效则清掉令牌留在登录页 |
|
||
| 关窗口(X) | 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示) |
|
||
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 `yuncang://open?code=…` 通过命名管道转给已运行实例 |
|
||
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
|
||
| 托盘右键「重启软件」 | 等 2 秒后拉起新进程(先退出才能释放单实例互斥体与 17300) |
|
||
| 「退出登录」 | 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序) |
|
||
| 网页请求唤起登录(`POST /api/activate-login`) | 未登录:登录窗弹到最前;已登录:主界面弹到最前(不影响本机服务) |
|
||
| 托盘右键「退出」 | 真正退出(dispose 托盘与本机服务) |
|
||
|
||
> 主界面**没有「停止服务 / 启动服务」**:本机服务跟随程序生命周期(启动即开、退出即停)。
|
||
> 留个停止按钮只会让用户误点后网页再也叫不醒软件(显示内容与「未安装」一模一样)。
|
||
> 也**没有「复制唤醒地址」**:唤醒地址由插件生成,不需要在界面上手测。
|
||
|
||
## 环境配置(开发 / 生产)
|
||
|
||
和前端 `VITE_BACKEND` 一个思路:**由构建决定,不靠用户手填**。
|
||
|
||
| 构建 | `env` | 默认后端 |
|
||
| --- | --- | --- |
|
||
| `dotnet build`(Debug) | `Development` | `http://127.0.0.1:7300`(= 前端 dev 代理的后端) |
|
||
| `dotnet build -c Release` | `Production` | `https://packs.example.com`(占位,打包时必须覆盖) |
|
||
|
||
打包正式版时指定真实域名:
|
||
|
||
```powershell
|
||
dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com -o publish
|
||
```
|
||
|
||
优先级(从高到低):
|
||
|
||
1. 启动参数 `--server=http://192.168.1.10:7300`(临时,不落盘);
|
||
2. 环境变量 `YUNCANG_SERVER`;
|
||
3. `-p:ServerBaseUrl=` 注入的构建默认值;
|
||
4. 用户在登录页手改并保存的地址(`settings.json`)。
|
||
|
||
几个细节:
|
||
|
||
- 地址等于**内置默认值**时,`settings.json` 里存空串 —— 所以换 Debug/Release 构建能自动跟随,
|
||
不会被上一次构建的默认值钉死;只有用户手改过的地址才会持久化。
|
||
- 换地址后**不会复用旧令牌**(`session.json` 里的 `ServerBaseUrl` 对不上就要求重新登录)。
|
||
- `GET /api/health` 会回 `env` 和 `server`,排查环境是否装错时先看这两个字段。
|
||
|
||
## 环境要求
|
||
|
||
- 编译:**.NET 8 SDK**(`dotnet --list-sdks` 能看到 `8.x`)
|
||
- 只运行已发布的 exe:**.NET 8 Desktop Runtime**(不需要 SDK)
|
||
|
||
> 本机 SDK 装在用户目录(免管理员):`%LOCALAPPDATA%\Microsoft\dotnet`,
|
||
> 已加入用户 `PATH` 和 `DOTNET_ROOT`。**新开的终端**才能直接用 `dotnet`;
|
||
> 老终端里临时用:`$env:DOTNET_ROOT="$env:LOCALAPPDATA\Microsoft\dotnet"; $env:Path="$env:DOTNET_ROOT;$env:Path"`。
|
||
> 直接双击 `bin\...\*.exe` 也需要 `DOTNET_ROOT` 已生效(否则报 “You must install .NET”)。
|
||
> 官方安装包:`winget install --id Microsoft.DotNet.SDK.8 -e`(要 UAC)。
|
||
|
||
## 构建 / 运行 / 发布
|
||
|
||
```powershell
|
||
cd desktop
|
||
|
||
dotnet build # 编译(Debug = 开发环境,连本地 7300)
|
||
dotnet build -c Release # 编译(Release = 生产环境,默认地址见上一节)
|
||
dotnet run # 直接跑(调试)
|
||
|
||
# ★ 发给用户、以及要用「网页叫醒」的话,必须用自包含发布
|
||
dotnet publish -c Release -r win-x64 --self-contained true `
|
||
-p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true `
|
||
-p:ServerBaseUrl=https://正式域名 -o publish
|
||
```
|
||
|
||
**为什么要自包含**:`dotnet build` 出来的 exe 是 *framework-dependent* 的,
|
||
它自己会去找 `C:\Program Files\dotnet` 或 `DOTNET_ROOT`。从**浏览器/资源管理器/协议**拉起的进程
|
||
拿不到我们临时设的环境变量,于是弹「You must install .NET Desktop Runtime」——
|
||
网页上表现就是「唤起没反应 / 弹安装提示」。
|
||
|
||
自包含单文件(约 154 MB)把运行时打进去了,双击和协议唤起都能直接跑,用户什么都不用装。
|
||
|
||
> `desktop/nuget.config` 指向华为云 NuGet 镜像(本机访问不了 api.nuget.org)——
|
||
> 自包含发布要下载 `Microsoft.*.App.Runtime.win-x64` 运行时包,没有镜像会 restore 失败。
|
||
|
||
开发阶段想让 `bin\Debug` 的 exe 也能直接双击,两个办法:装官方 SDK/Desktop Runtime 到标准位置,
|
||
或者每次用发布产物验证唤起。
|
||
|
||
## 打安装包(MSI)+ 自动更新
|
||
|
||
`desktop/installer/` 下是安装包定义(**WiX 5**,免费;WiX v6+ 需要 OSMF 付费协议,别装最新版)。
|
||
|
||
```powershell
|
||
# 工具只需装一次
|
||
dotnet tool install --global wix --version 5.0.2
|
||
|
||
cd desktop\installer
|
||
|
||
.\build.ps1 # 开发环境(默认),版本取 csproj(1.0.0)
|
||
.\build.ps1 -Version 1.0.1 # 指定版本
|
||
.\build.ps1 -Environment Production -Version 1.0.1 -ReleaseNotes "修复若干问题"
|
||
```
|
||
|
||
### 环境与域名(`package.config.json`)
|
||
|
||
| 环境 | 默认后端 | 用途 |
|
||
| --- | --- | --- |
|
||
| `Development` | `http://127.0.0.1:7300` | 本机联调;打完会自动把包+版本信息复制到后端,本机就能测更新 |
|
||
| `Production` | `https://packs.example.com`(**占位,发布前必须改成正式域名**) | 正式安装包 |
|
||
|
||
`build.ps1 -Environment Production` 自动用生产域名打 exe(`ServerBaseUrl`)和下载地址;
|
||
也可以用 `-ServerBaseUrl` 临时覆盖。
|
||
|
||
### 脚本做了什么
|
||
|
||
1. `dotnet publish`(自包含单文件,不依赖 .NET 运行时;版本号一起注入程序集);
|
||
2. `wix build` 生成 MSI;
|
||
3. 算 MD5 → 写 `version.json`;
|
||
4. 复制到后端:MSI → `backend/app/public/download/`,`version.json` → `backend/app/public/version/`;
|
||
5. 本地 `out/` 与后端目录**各只保留最近 5 个**安装包(`keepVersions` 可配)。
|
||
|
||
### 自动更新怎么工作
|
||
|
||
```
|
||
软件启动(登录后)→ GET {后端}/download/version.json?t=时间戳
|
||
→ version.json 的 version 比当前程序集版本新
|
||
→ 软件内弹窗:新版本号 / 更新说明 / 安装包大小
|
||
→ 点「立即更新」→ **软件内下载(进度条)**→ MD5 校验
|
||
→ 自动静默安装(msiexec /passive)→ 软件退出 → 装完自动重新打开
|
||
```
|
||
|
||
- **不跳浏览器**:下载、进度、校验、安装都在软件里完成。
|
||
- 下载落在 `%TEMP%\YuncangTraceUpdate\`,文件名取 downloadUrl 里的真实文件名。
|
||
- 安装前会等 3 秒(让本进程先退出,否则 exe 被占用换不掉);perUser 安装不需要管理员。
|
||
- **版本一致性防护**:若 `downloadUrl` 里的包版本(`YuncangTraceSetup-x.y.z.msi`)不比当前版本新,
|
||
直接忽略 —— 防止 version.json 配错/漏传包导致「装完还是旧版 → 无限弹窗」。
|
||
- 回归测试可用环境变量 `YUNCANG_AUTO_UPDATE=1` 让弹窗出现后自动开始下载(无需手点)。
|
||
|
||
`version.json` 长这样(脚本生成,**不用手写**):
|
||
|
||
```json
|
||
{
|
||
"version": "1.0.1",
|
||
"downloadUrl": "https://正式域名/download/YuncangTraceSetup-1.0.1.msi",
|
||
"md5": "7a93b4…",
|
||
"size": 56786944,
|
||
"publishedAt": "2026-10-17T12:00:58+08:00",
|
||
"buildId": "20261017120058",
|
||
"environment": "Production",
|
||
"releaseNotes": "修复若干问题"
|
||
}
|
||
```
|
||
|
||
### ⚠️ 缓存(这里最容易踩坑)
|
||
|
||
Egg 的 `static` 在生产默认**强缓存一年**。如果 `version.json` 也被缓存,软件永远检测不到更新。
|
||
|
||
处理方式(都已实现):
|
||
|
||
| 层 | 做法 |
|
||
| --- | --- |
|
||
| 文件位置 | `version.json` 放在 `app/public/version/`,**不在静态目录里** |
|
||
| 后端路由 | `GET /download/version.json` 由 `controller/download.js` 返回,显式 `Cache-Control: no-store`、去掉 `ETag`/`Last-Modified`(连 304 都不走) |
|
||
| 前端中间件 | `middleware/frontend.js` 放行 `/download/*`,否则会被 SPA 入口接管 |
|
||
| 客户端 | 请求带 `?t=毫秒时间戳` + `Cache-Control: no-cache` |
|
||
| 安装包本体 | 文件名带版本号 → `Cache-Control: public, max-age=31536000, immutable` |
|
||
|
||
> 生产前面如果还有 **nginx / CDN**,也要对 `/download/version.json` 关缓存,否则只在应用层关没用:
|
||
> ```nginx
|
||
> location = /download/version.json {
|
||
> add_header Cache-Control "no-store, no-cache, must-revalidate" always;
|
||
> proxy_no_cache 1;
|
||
> proxy_cache_bypass 1;
|
||
> proxy_pass http://127.0.0.1:7300;
|
||
> }
|
||
> ```
|
||
|
||
安装包行为:
|
||
|
||
| 项 | 说明 |
|
||
| --- | --- |
|
||
| 安装范围 | **perUser**(免管理员、无 UAC),装到 `%LOCALAPPDATA%\Programs\YuncangTrace` |
|
||
| 启动协议 | **安装即注册** `yuncang://`(HKCU),不需要先启动软件 |
|
||
| 卸载 | MSI 自动删除 exe、协议注册、开始菜单 —— 即「取消注册」 |
|
||
| 升级 | `MajorUpgrade`:装新版会替换旧版;降级被拦 |
|
||
| 用户数据 | `%LOCALAPPDATA%\YuncangTrace\{settings,session}.json` 卸载**不删**(重装后仍保持设置/登录) |
|
||
|
||
```powershell
|
||
msiexec /i out\YuncangTraceSetup-1.0.1.msi # 安装
|
||
msiexec /x out\YuncangTraceSetup-1.0.1.msi # 卸载
|
||
```
|
||
|
||
> 需要「本机所有用户都能用」时:`Product.wxs` 里 `Scope` 改 `perMachine`、注册表根改 `HKLM`,
|
||
> 安装时会要管理员权限(UAC)。默认的 perUser 更省事,也够用(软件数据本来就是按用户存的)。
|
||
|
||
> ⚠️ `build.ps1` 必须保存为 **UTF-8 with BOM**:PowerShell 5.1 读无 BOM 的脚本会按 GBK 解析,
|
||
> 中文注释直接把语法搞崩。
|
||
|
||
### 验证自动更新(不卸载重装)
|
||
|
||
```powershell
|
||
cd desktop\installer
|
||
|
||
.\build.ps1 -Environment Development -Version 1.0.7 # 先发布一个更高版本(包+version.json 落到后端)
|
||
.\test-update.ps1 # 启动旧版本 → 等它自己升级上去
|
||
```
|
||
|
||
`test-update.ps1` 做的事:
|
||
|
||
1. 读后端 `/download/version.json` 的目标版本,和当前安装版本比较(已是最新就直接退出);
|
||
2. 关掉正在运行的软件(单文件自解压出来的真实进程);
|
||
3. 带 `YUNCANG_AUTO_UPDATE=1` 启动**旧版本**(更新窗口出现后自动下载,不用手点);
|
||
4. 轮询 `%LOCALAPPDATA%\Programs\YuncangTrace\*.exe` 的 `ProductVersion`,直到变成目标版本;
|
||
5. 检查本机服务 17300 是否有响应、进程是否已恢复。
|
||
|
||
输出形如:
|
||
|
||
```
|
||
当前安装版本:1.0.6
|
||
后端目标版本:1.0.7
|
||
启动旧版本 1.0.6(自动更新已开启)…
|
||
[3s] 安装版本 = 1.0.6+af3f8ab…
|
||
[6.1s] 安装版本 =
|
||
[10.4s] 安装版本 = 1.0.7+d32656a…
|
||
✔ 自动更新完成:1.0.6 → 1.0.7(耗时 10.4s)
|
||
✔ 本机服务 17300 有响应(HTTP 401)
|
||
✔ 软件进程已恢复(PID 12024)
|
||
```
|
||
|
||
> 每次测更新都要打一个**比当前安装版本高**的包(脚本会拒绝在"已是最新"时白跑)。
|
||
|
||
## 本机接口(前端 `/local` 页用的就是这两个)
|
||
|
||
服务固定监听 `http://localhost:17300`(端口写在前端页面与插件里)。
|
||
代码里**同时注册了 `http://127.0.0.1:17300/`** 前缀 —— `HttpListener` 只接受「注册过的 host」,
|
||
不注册的话用 127.0.0.1 访问会直接被回 400(前端改 `VITE_LOCAL_SERVICE` 时就会碰到)。
|
||
|
||
浏览器直接打开 <http://localhost:17300/> 会看到一个说明页(列了接口,方便排查)。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/query/{code}` | 查信息,**同时把服务/登录状态一起返回**(见下)。没登录 → 401 `state:need-login` |
|
||
| POST | `/api/activate-login` | 把本机软件的**登录窗叫到前台**(已登录时把主界面叫到前台)。网页收到 `need-login` 时自动调它 |
|
||
|
||
### 为什么没有单独的「探活 / health」接口
|
||
|
||
探活通过 ≠ 真正查询时软件还在(用户可能中途退出了),两次请求之间状态会变。
|
||
把状态合进查询接口后,页面**只发一次请求**就能决定「展示结果」还是「提示可以唤起」:
|
||
|
||
| HTTP | `state` | 含义 |
|
||
| --- | --- | --- |
|
||
| 200 | `ok` | 查到了,`data` 是数据 |
|
||
| 401 | `need-login` | 软件在跑但**未登录**,页面去调 `activate-login` 并轮询本接口等登录 |
|
||
| 400 | `bad-request` | 参数不对(例:码为空) |
|
||
| 404 | `not-found` | 没这条记录 |
|
||
| 500 | `error` | 内部错误 |
|
||
|
||
**只有网络层失败(连不上 / 超时 / 被 CORS 拦)才代表「软件没启动」**,
|
||
这时页面提示「服务暂不可用 + 下载安装 / 启动本机软件」。
|
||
|
||
无论成败都带这些字段:`loggedIn`、`user`、`env`(`Development`/`Production`)、`server`(当前后端地址):
|
||
|
||
```jsonc
|
||
// 200
|
||
{ "ok": true, "state": "ok", "code": "ABC123", "loggedIn": true, "user": "管理员",
|
||
"env": "Development", "server": "http://127.0.0.1:7300",
|
||
"data": { "code": "ABC123", "orderNo": "SO-20261017-001", "videoPath": "D:\\video\\demo.mp4" } }
|
||
|
||
// 401
|
||
{ "ok": false, "state": "need-login", "code": "ABC123", "loggedIn": false, "user": null,
|
||
"env": "Development", "server": "http://127.0.0.1:7300", "message": "本机软件未登录,请先在软件里登录" }
|
||
```
|
||
|
||
示例:
|
||
|
||
```powershell
|
||
curl http://localhost:17300/api/query/321408064481776
|
||
curl http://localhost:17300/api/query/ # 400 bad-request,但带着登录状态
|
||
curl -X POST http://localhost:17300/api/activate-login
|
||
```
|
||
|
||
为什么唤起登录用 **POST**:GET 会被浏览器/聊天工具的链接预取误触发,POST 不会。
|
||
|
||
浏览器跨域(页面在站点域名上,请求的是 localhost)必须回这些响应头,代码里已经处理:
|
||
|
||
- `Access-Control-Allow-Origin`(回显 Origin)、`Allow-Methods`(`GET, POST, OPTIONS`)、`Allow-Headers`、`Max-Age`
|
||
- `Access-Control-Allow-Private-Network: true` —— 公网 https 页面访问 localhost 时 Chrome 会发
|
||
私有网络预检(PNA),不回这个头预检就失败
|
||
|
||
> ⚠️ 千万别只回 `200` 不带 CORS 头:浏览器会直接拦掉,前端看起来和「软件没启动」一模一样。
|
||
|
||
## 启动协议(网页叫醒本软件)
|
||
|
||
`yuncang://open?code=xxx`。注册写在 **HKCU**(免管理员):
|
||
|
||
```
|
||
HKEY_CURRENT_USER\Software\Classes\yuncang
|
||
(默认) = "URL:云仓视频溯源软件"
|
||
"URL Protocol" = ""
|
||
\shell\open\command
|
||
(默认) = "C:\...\YuncangTrace.LocalService.exe" "%1"
|
||
```
|
||
|
||
- **每次启动都会自动把注册项校正到「当前这个 exe」**(幂等)。这一点很关键:
|
||
换目录安装、从 `bin\Debug` 换成发布版、重新装一遍之后,注册表里残留的旧路径会让网页
|
||
唤起一个不存在 / 缺运行时的 exe(典型现象就是弹「You must install .NET」或干脆没反应)。
|
||
- **界面上完全不展示协议**:注册由安装包完成、卸载时 MSI 自动删除,启动时自动校正到当前 exe;
|
||
用户不需要知道 `yuncang://` 这回事(排障看日志或注册表即可)。
|
||
- 手工注册/排查:
|
||
|
||
```powershell
|
||
reg add "HKCU\Software\Classes\yuncang" /ve /d "URL:云仓视频溯源软件" /f
|
||
reg add "HKCU\Software\Classes\yuncang" /v "URL Protocol" /d "" /f
|
||
reg add "HKCU\Software\Classes\yuncang\shell\open\command" /ve /d '"C:\Path\YuncangTrace.LocalService.exe" "%1"' /f
|
||
reg query "HKCU\Software\Classes\yuncang\shell\open\command"
|
||
```
|
||
|
||
- 打包工具里对应:Inno Setup 的 `[Registry]` 段、NSIS 的 `WriteRegStr HKCU ...`、Electron 的
|
||
`app.setAsDefaultProtocolClient('yuncang')`;
|
||
- 协议名改了要同步前端 `VITE_APP_PROTOCOL`(默认 `yuncang`)。
|
||
|
||
## 和前端 / 插件怎么配合
|
||
|
||
1. WMS 页面上点运单号旁的按钮 → 插件按「打开方式」处理:默认**直接用 `yuncang://open?code=<运单号>` 唤起本机软件**并定位到该单号
|
||
(浏览器会先问一次「要打开吗」);把打开方式改成「独立小窗 / 新标签页」则改为打开网页;
|
||
2. `/local` 页只发一个请求 `GET /api/query/{code}`:
|
||
- **连不上** → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
|
||
点「已安装,启动本机软件」会走 `yuncang://open?code=...`,然后每秒重试同一个查询接口;
|
||
- **`need-login`**(软件没登录)→ 页面自动 `POST /api/activate-login`
|
||
把本机登录窗叫到前台,然后每秒重试**同一个查询接口**等登录完成(最长 30s),登录好**自动拿到结果**;
|
||
- **`ok`** → 直接展示(页面顶部会显示「本机软件已登录:xxx」)。
|
||
3. 本软件被协议拉起时,会拿到 `yuncang://open?code=xxx` 参数:已经开着就转给原窗口(单实例),
|
||
没开就启动 → 先登录 → 登录完自动查询这个码(登录前收到的 code 会先存着)。
|
||
单实例的命名管道监听**在登录之前就起来了**,所以用户卡在登录窗时被网页唤起也不会丢参数。
|
||
|
||
### 插件「直接唤起」与唤不起时的提示(重要)
|
||
|
||
浏览器**不会告诉网页**协议到底有没有打开成功 —— 没安装、协议没注册、用户在 Chrome 的
|
||
「要打开吗」上点了取消,这三种情况在页面侧**完全一样**。所以必须做超时兜底:
|
||
|
||
1. 点击 → 隐藏 iframe 触发 `yuncang://open?code=xxx`(不能导航当前页,否则协议没注册会变成错误页);
|
||
2. **判断到底成没成,不看页面焦点,看本机服务在不在**:协议触发后每 0.7s 探测一次
|
||
`http://localhost:17300/api/query/`(任何 HTTP 响应都算成功,扩展带 host 权限,不受页面 CSP 影响);
|
||
- 探测到 → 什么也不做(软件本来就在跑时也能正确判定,不会误报);
|
||
- 8 秒都探测不到 → 认为没起来,右下角弹出兜底卡片:
|
||
- **在网页中查看** → 打开插件设置里的「唤不起时的兜底页」(默认 `http://localhost:7301/local?code={code}`,
|
||
该页面里有完整的下载安装引导);
|
||
- **下载安装** → 打开插件设置里的「软件下载地址」(留空则不显示这个按钮)。
|
||
3. 插件设置页的相关配置:
|
||
- **打开方式**:`直接唤起本机软件(协议)`(默认)/ `独立小窗(网页)` / `新标签页(网页)`;
|
||
- **协议模板**(仅「直接唤起」时生效):默认 `yuncang://open?code={code}`;
|
||
- **网页地址模板**(仅小窗/标签页时生效):默认 `http://localhost:7301/local?code={code}`;
|
||
- **唤不起时的兜底页**、**软件下载地址**(留空则不显示「下载安装」按钮)。
|
||
老配置升级时会自动迁移(v3 把协议写在网页模板里的,会改成「打开方式 = 直接唤起 + 网页模板还原」),行为不变。
|
||
|
||
> 判定依据是「本机服务在不在」,所以**软件已经在跑时不会误报**(这是最常见的场景:
|
||
> 协议只是把参数转给已有实例,窗口不一定抢焦点)。真正的误报只剩一种:软件还没完全启动就超时 ——
|
||
> 那种情况提示一下也算合理。页面失焦只作为「快速判定成功」的辅助信号。
|
||
|
||
## ★ 接真实数据
|
||
|
||
只改一处:`Services/OrderQueryService.cs` 的 `Query(string? code)`。
|
||
|
||
```csharp
|
||
public QueryResult Query(string? code)
|
||
{
|
||
var value = (code ?? "").Trim();
|
||
if (value.Length == 0) return QueryResult.BadRequest("缺少运单号");
|
||
|
||
// 例:查本地 SQLite / 扫本地打包视频目录 / 调内部接口
|
||
var row = _db.FindByCode(value);
|
||
if (row is null) return QueryResult.NotFound($"没有找到 {value} 的记录");
|
||
|
||
return QueryResult.Success(new Dictionary<string, object?>
|
||
{
|
||
["code"] = row.Code,
|
||
["orderNo"] = row.OrderNo,
|
||
["printStatus"] = row.PrintStatus,
|
||
["videoPath"] = row.VideoPath,
|
||
});
|
||
}
|
||
```
|
||
|
||
返回对象**平铺**即可,前端页面会把顶层字段渲染成「项目 / 值」两列(字段随便加)。
|
||
|
||
## 常见问题
|
||
|
||
| 现象 | 处理 |
|
||
| --- | --- |
|
||
| 启动报「没有绑定端口的权限」/ `Access is denied (5)` | 管理员执行 `netsh http add urlacl url=http://localhost:17300/ user=%USERNAME%`,或改成以当前用户身份运行 |
|
||
| 报端口被占用(错误 32) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
|
||
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 `http://localhost:17300/api/health`:打不开→防火墙/端口;打得开→多半是 CORS 头没回 |
|
||
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
|
||
| 唤起时弹「You must install .NET Desktop Runtime」 | 唤起的是 `bin\Debug` 这类 framework-dependent 的 exe(拿不到 `DOTNET_ROOT`)。用自包含发布产物,并让它启动一次以校正注册表 |
|
||
| 改了协议名 | 注册表重注册 + 前端 `VITE_APP_PROTOCOL` 同步 + 插件目标地址同步 |
|