packServer/desktop/README.md

640 lines
45 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.

# 云仓视频溯源软件(本机服务 / 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 # 日志落文件:软件目录\logs\log_yyyy-MM-dd.txt(按天一个)
└── JsonUtil.cs # JSON 序列化(中文不转义)
```
## 登录 / 托盘 / 防多开的行为
| 场景 | 行为 |
| --- | --- |
| 首次启动 | 先起本机服务(17300)与托盘,再弹登录页 → 登录成功才出主窗口 |
| 已有令牌 | 登录窗一闪而过:`/api/web/me` 通过就直接进主窗口;失效则清掉令牌留在登录页 |
| 关窗口(X) | 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示) |
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 `yuncang://open?code=…` 通过命名管道转给已运行实例 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 托盘右键「重启软件」 | 等 2 秒后拉起新进程(先退出才能释放单实例互斥体与 17300) |
| 「退出登录」 | 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序) |
| 网页请求唤起登录(`POST /api/activate-login`) | 未登录:登录窗弹到最前;已登录:主界面弹到最前(不影响本机服务) |
| 托盘右键「退出」 | 真正退出(dispose 托盘与本机服务) |
> 主界面**没有「停止服务 / 启动服务」**:本机服务跟随程序生命周期(启动即开、退出即停)。
> 留个停止按钮只会让用户误点后网页再也叫不醒软件(显示内容与「未安装」一模一样)。
> 也**没有「复制唤醒地址」**:唤醒地址由插件生成,不需要在界面上手测。
>
> 主界面顶部菜单:
> - **工具**:测试查询(聚焦输入框)、打开日志目录、清理日志、清理更新缓存(`%TEMP%\YuncangTraceUpdate`)
> - **服务**:服务状态(只读)、重启软件
> - **帮助**:检查更新、关于(版本 / 环境 / 运行状态)
>
> **日志不在界面上显示**,只写文件(按天一个,方便直接发给别人排查):
> `<软件目录>\logs\log_2026-09-22.txt`,行格式 `[2026-09-22 14:03:11] 内容`。
> 软件目录不可写时(如装到 Program Files)自动退回 `%LOCALAPPDATA%\YuncangTrace\logs`。
> 「工具 → 打开日志目录」用资源管理器打开它,「清理日志」删掉全部 `log_*.txt`(当天文件也能删,之后会重建)。
## 环境配置(开发 / 生产)
和前端 `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)
- 打安装包:`desktop\native\ffmpeg\ffmpeg.exe` 必须存在(见 [native/ffmpeg/README.md](native/ffmpeg/README.md))
- **默认普通权限运行**:`app.manifest` 是 `asInvoker`(不是 `requireAdministrator`)。
双击、开始菜单、网页 `yuncang://` 协议唤起都**不弹 UAC**。
- **只有改系统时间才提权**:NTP 窗口点「立即校时 / 同步 NVR 时间」时,才会用 `runas` 拉起
一个只做校时的临时进程(弹一次 UAC,见 `Services/ElevatedNtp.cs`)。
非管理员启动时,启动/定时自动校时会跳过(日志有 `[ntp] 当前不是管理员权限`)。
> **ffmpeg 已打进安装包**(`native\ffmpeg\ffmpeg.exe`)。客户机(尤其是非设备服务器的查件电脑)
> 不需要自己装 ffmpeg 就能做回放校验、多路合并。bin 里的 exe **不再**去 PATH 里找 ffmpeg 时才可用 ——
> 开发时仍可用环境变量 `YUNCANG_FFMPEG` 覆盖版本。
> 本机 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)。
## NTP 校时(2026-10-19)
扫码时间取**本机时钟**,回放按**录像机本地时间**定位;本机时间不准会让录像整体错位
(现场实测 Windows 时间服务没启动,本机慢了近 10 秒,30 秒的回放窗口直接把面单截到窗口外)。
- **入口在「服务 → NTP 校时…」**,只有**设备服务开启**(服务模式)时才显示;关闭设备服务后菜单隐藏。
- **服务模式强制项**:NTP 校时必须启用、启动时必须校时、定时校时不能停(间隔至少 5 分钟),
窗口里的两个开关会置灰,保存时后端(桌面端)也会再强制一次。
- 设置项:NTP 服务器、自动校时间隔(分钟,0 = 仅启动时)、「立即校时」。
- **「同步 NVR 时间」**:拉取当前主体全部录像机(`GET /api/web/nvrs`,后端已有,无需新增接口),
逐台静默执行:
1. 用 8000 私有协议写 NTP(`NET_DVR_SET_NTPCFG`,与桌面端**同一个 NTP 地址**);
2. 立即生效:`NET_DVR_SET_TIMECFG` 把设备时间直接校准到 NTP 时间;
3. 回读 NTP 配置与设备时间,在窗口里逐台返回结果(✔/✘ + 偏差)。
- 启动时校一次 + 运行期间默认每 **30 分钟**校一次;偏差小于 **0.2 秒**不调整。
- 实现:`Services/NtpClient.cs`(UDP 123 SNTP)+ `Services/ClockSyncService.cs`
(打开 `SeSystemtimePrivilege` 后调用 `SetSystemTime`);NVR 侧在 `HikDeviceService.GetNtpConfig/SetNtpConfig/SetDeviceTime`。
- 改系统时间需要管理员,但**不再要求整个软件以管理员启动**:
非管理员时点「立即校时 / 同步 NVR 时间」会通过 `runas` 起一个只做校时的临时进程
(`--ntp-sync-elevated`,见 `Services/ElevatedNtp.cs`),结果写到临时 JSON 供主进程读回;
用户点「否」只提示「已取消」,不会报错。
- 日志:`[ntp] 启动校时完成:ntp.aliyun.com 偏差 +9.60 秒,往返 30 ms`;
`[ntp] 同步 NVR 完成:1/1 台(…)`;失败只记日志,不影响登录/查询。
- 回放侧仍会按录像机时钟做二次对齐(`HikPlaybackService.ClockOffset`),
即使本机时间临时不准也不会截掉面单。
## 构建 / 运行 / 发布
## 构建 / 运行 / 发布
```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 运行时;版本号一起注入程序集);
**同时把 `native\HCNetSDK\**`、`native\ffmpeg\**` 作为独立文件输出**(不走单文件自解压);
缺 `publish\native\ffmpeg\ffmpeg.exe` 会直接报错中止;
2. `wix build` 生成 MSI(`Product.wxs` 用 `<Files Include="..\publish\native\**" />` 递归收集,保持目录结构);
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` 的 `QueryAsync(code)` 调
`GET /api/web/pack-query?code=`(用户令牌 + `X-Subject-Id`),**范围限定当前主体**。
后端用**扫码当时的工作台快照**(`scan_records.workstation_snapshot`)算好回放计划,
本机只负责把返回拍成「项目 / 值」两列:
| 字段 | 含义 |
| --- | --- |
| `扫码记录数` | 同一运单被扫了几次(不同中控/通道/重复扫) |
| `记录 N · 扫码时间` | 已转成本机本地时间 |
| `记录 N · 中控 / 通道` | 哪台中控的哪个通道 |
| `记录 N · 工作台` | 当时的工作台 + 类型(团购 / 散单) |
| `记录 N · 回放区间` | `开始 ~ 结束(秒)`,散单被最大录制时长截断时会标注 |
| `记录 N · 录像机` | 涉及的录像机(名称 + `IP:端口`) |
| `记录 N · 摄像头` | 通道号 + 名称 + 在画布上的位置/尺寸(多路合并要按这个摆) |
> **自动校验回放**:查询命中(后端返回了 `streams`)后,桌面端会**立刻**逐路去录像机试拉
> (每路 2 秒,面板里显示进度),**任意一路拉到录像就停止校验**并显示「预览回放 / 下载录像」按钮 ——
> 不需要把每一路都验完,也不需要用户手动点「校验」。
> 预览和下载仍按**全部**流处理:没录像的那几路在下载时自己跳过,保证多路合并不会退化成单路。
>
> **回放时间按录像机时钟对齐**:扫码时间来自本机时钟,回放是按录像机本地时间定位的。
> 每次校验/预览/下载前会读一次录像机时间(8000 私有协议),把请求窗口整体平移,
> 日志里能看到 `[playback] 录像机 … 与本机时钟相差 X 秒`。本机时间不准(比如 Windows
> 时间服务没开、慢了几秒)时,短回放窗口会把面单截到窗口外 —— 这一步就是防这个。
查询日志只记结论(`[pack-query] 运单号 → found=… records=… streams=…`),不再写完整 JSON;
要排查原始数据看后端日志或页面。
要换成别的数据源,只改 `OrderQueryService.QueryAsync` 一个方法就行(返回 `QueryResult`,
`Data` 是扁平字典即可,前端 `/local` 页也吃这份数据)。
### 扫码 → 查询(不跳页)
- 手动输入 / 回车 / 点查询 / 协议唤起:`RunQueryAsync()`,**切到「打包查询」页**展示;
- 通道扫码:`OnChannelBarcode` 后台算一次结果,**绝不切页签**
(用户还在「扫码通道 / 扫码记录」页时,只在「打包查询」页签上加 `●`,
切过去时才把结果显示出来);
- 扫码数据本身仍由 `ScanService` 落记录 + 上报,跟查询是两条独立的路。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 启动报「没有绑定端口的权限」/ `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` 同步 + 插件目标地址同步 |
## 主体切换 / 微信扫码登录 / 设备服务(2026-10-18)
### 登录窗
- **微信扫码登录**:点「微信扫码登录」→ `GET /api/wechat/login` 发码 → 显示二维码
(`GET /api/wechat/qrcode.gif?code=`,WPF 不能渲染 SVG 所以后端额外给了 GIF 版)→ 长轮询
`GET /api/wechat/login?code=&wait=25`,手机确认后直接拿令牌进主界面;码过期会自动换新。
- 账号密码登录与微信登录**都会带回主体列表**(`subjects`),主界面右上角显示当前主体。
### 主界面
- 左上状态行:`主体:xxx · 设备服务:未开启 / 已开启(SN)`。
- 菜单 **服务**:
- `当前主体:xxx` → 弹窗切换主体(`GET /api/web/subjects`;切换后设备服务若开着会提示在新主体下重新开启)
- `开启设备服务`(**只有主体管理员可见**;默认关闭)
- `关闭设备服务`(开启后才出现)
- `服务状态:运行中/未启动`
- **开启流程**:先 `GET /api/web/devices/active` 看该主体是否已有设备 → 有就弹确认
「一个主体只允许一台设备在线,开启后它会被踢下线」→ `POST /api/web/devices/activate`
(服务端踢人 + 发长期设备 JWT)→ 上报本机通道 `DESKTOP / 本机中控`。
- **上报**:开启后,本机每处理一个运单号(协议唤起 / 测试查询)都会 `POST /api/scan/records`
(通道 `DESKTOP`,服务端按 设备+通道+条码+秒 去重)。关闭/退出登录时会 `POST /api/web/devices/:id/logout` 让令牌立即失效。
- 状态都落在 `%LOCALAPPDATA%\YuncangTrace\settings.json`(`SubjectId/SubjectName/SubjectRole`、
`DeviceServiceEnabled/DeviceId/DeviceSn/DeviceToken`),其中 `DeviceServiceEnabled` **默认 false**。
### 相关文件
`Services/ApiClient.cs`(登录/微信/主体/设备/上报)、`Services/DeviceService.cs`(开启/关闭/上报)、
`Services/AppSettings.cs`(新增主体与设备字段)、`LoginWindow.*`(微信面板)、`MainWindow.*`(服务菜单 + 状态行)、
`SubjectPickerWindow.*`(切换主体弹窗)。
### 后台扫码服务(Windows 服务,2026-10-19)
「开启设备服务」不再依赖桌面端常驻:会安装系统服务 **`YuncangTraceAgent`**(LocalSystem、自动启动),
**退出软件 / 注销用户 / 重启电脑后继续收码上报**。
| 项 | 位置 / 说明 |
|---|---|
| 服务程序 | `%ProgramData%\YuncangTrace\agent\YuncangTraceAgent.exe`(从安装目录复制;**MSI 升级不会撞「文件被占用」**) |
| 服务配置 | `%ProgramData%\YuncangTrace\agent.json`:服务器地址 + **长期设备令牌**(默认 365 天)+ NTP 设置 |
| 服务令牌 | `%ProgramData%\YuncangTrace\agent-token.json`:访问令牌 + **刷新令牌**(服务自动续期后更新;单独一份避免和 agent.json 互相覆盖) |
| 共享数据 | `channels.json` / `scan-records.json` 在 `%ProgramData%\YuncangTrace\`(普通模式仍在 `%LOCALAPPDATA%`) |
| 运行状态 | `agent-status.json`:是否运行 / 通道在线 / 待上传条数 / NTP 结果,桌面端只读展示 |
| 命令 | `agent-command.json`:立即上传 / 清空记录 / 重新加载通道 / 立即校时 / 立即续期令牌(服务每秒轮询) |
| 发现列表 | `agent-discovered.json`(桌面端「扫码通道」页展示用) |
| NTP | 服务以 LocalSystem 定时校时,**不再需要 UAC**;NTP 窗口的「立即校时」只写命令文件 |
| 安装 / 卸载 | 开启 / 关闭设备服务时用 `runas` 提权(**各弹一次 UAC**),之后日常使用无 UAC |
| 升级 | 新版本启动后检测服务副本版本,提示更新(一次 UAC) |
| 日志 | `%ProgramData%\YuncangTrace\agent\logs\log_*.txt` |
| 日志策略 | 按天一个文件,**自动保留 14 天**;状态文件改为「内容变化才写 + 30 秒保活」(不再每 2 秒重写);面单压着扫码器时同一个码每 5 分钟才记一行 |
| 手动排障 | `sc query YuncangTraceAgent` / `sc start|stop YuncangTraceAgent` |
| 调试 | `YuncangTrace.LocalService.exe --agent-run`(不经 SCM,直接跑后台循环) |
> **退出登录不会关闭设备服务**:服务模式下只清登录态,设备令牌和 `agent.json` 保留,扫码继续上报。
> 要停止必须走「服务 → 关闭设备服务」。
>
> **换账号登录(不属于后台服务主体)**:后台服务是独立进程,继续按原主体扫码/上报;
> 桌面端会把**界面主体**自动切到当前账号可用的主体(查询用),并在状态行标注「服务主体 id=xxx」。
> 此时:
> - **管理员**:扫码通道 / 扫码记录页照常显示,但页顶有醒目提示「后台服务运行在主体 id=xxx,与当前主体不一致」,
> 要换到当前主体必须先「服务 → 关闭设备服务」,再「开启设备服务」重新绑定;
> - **普通成员**:扫码通道 / 扫码记录页**直接隐藏**(本地文件是那台服务的数据,与当前账号的主体无关),只保留打包查询;
> - 查询接口用的是当前账号的主体;「关闭设备服务」仍可执行:先停/卸载本地服务,再尝试通知服务器注销(不是该主体成员时服务端注销会失败,日志有记录);
> - 账号下**一个主体都没有**:弹窗提醒后**直接退回登录页**(后台服务保持运行,换有主体的账号登录即可)。
>
> 只有当前界面主体就是服务主体时,切换主体才必须先关闭设备服务(避免扫码写到旧主体)。
>
> **令牌自动续期**:激活时后端同时下发访问令牌(365 天)和刷新令牌(默认 730 天)。
> 后台服务在访问令牌剩余不足 7 天时自动调 `POST /api/device/refresh` 换新(两者都轮换),
> 结果写到 `agent-token.json`;只要服务在跑就不需要人工重新激活。
> 关闭设备服务 / 被同主体其它设备踢下线时,刷新令牌一并作废。
> 需要验证续期流程时:菜单 **服务 → 立即续期设备令牌**(写 `RefreshTokenAt` 命令),服务会立即换一次并记日志。
>
> **设备心跳**:后台服务每 **60 秒**调 `POST /api/scanner/heartbeat` 刷新后端 `last_seen_at`,
> 所以即使长时间没扫码,网页设备列表也能看出服务在线;心跳 401 会触发令牌续期。
>
> 服务模式下桌面端只做界面/配置:不启动本进程的 `ScanService`(避免和后台服务抢设备连接),
> 通道在线状态、扫码记录都从服务写的文件里读。
## 扫码服务(从 AndroidScanCenter 移植,2026-10-18)
扫码中控不再由 Android 盒子承担,**TCP/UDP 通讯全部搬到桌面端**:
| 能力 | 实现 | 说明 |
|---|---|---|
| 设备发现 | `Services/Scan/DiscoveryMonitor.cs` | **常驻 UDP**:一个 socket 一直开着,每 3s 向 `255.255.255.255` + 各网段定向广播发一次探测,期间**持续收**、按 MAC 合并,12s 没见到就摘掉。⚠️ 设备**不会主动广播**(实测绑 48899 静听 40s 只能收到自己的探测包),回复只发回**发送方源端口**,所以不能在 48899 上被动监听 |
| 设备配置 / 重启 | 同上(JCMD) | `CID 10003` 读 SYS、`10005` 写 SYS(增量)、`20003` 重启;**不要发 `DO_RELOAD`**(会抹掉改动) |
| 写设备名 / 确保 TCP 服务 | `Services/Scan/DeviceConfig.cs` | 条目 **`packcenter` / TCP-SERVER / 8087**(**不用 Android 的 `scancenter:8086`**),缺失/不对则整条写入 → `10017` **落 flash** → 回读校验;**设备最多放 3 条 SOCK**,满了就复用一条非保留条目(`scancenter`、`netp` 是别人的,绝不动),实际用的名字记在通道的 `SockName` 上;写前备份全部条目原始字段,写完发现别人的条目丢了会**原样写回** |
| 自愈 | `ScanService.HealAsync` | 通道连续 3 次连不上 → 回查设备 SOCK 条目,被删/被改就重建(每台设备 60s 最多一次) |
| 收条码 | `Services/Scan/ChannelConnection.cs` | 每条通道一条 **TCP 出向连接**到设备 `:8087`(设备当服务端),按 CR/LF 切行,断线 5s 重连;设备每 ~0.7s 推的 6 字节二进制帧(`04 D0 00 00 FF 2C`)会被忽略,不污染条码行 || 扫码枪设置 | `Services/Scan/ScannerCommands.cs` | 连上后一次写 28 字节:**连续扫描 + 识别间隔 0s + 静音状态**(9+9+10,静音那两条是 10 字节,校验位照抄)。写失败不影响收码。扫码枪自己重启会丢设置,靠“每次重连都下发”自动兜住 |
| 静音 | `ScanService.SetMuted` | **只存本地 + 让连接重走一遍**(关 socket → 立即重连 → 整条设置重下发)。不在现有 socket 上补写指令:Android 侧实测“字节发出去了但枪没执行”时无法判断 |
| 串口指令调试 | `Views/ScannerCommandWindow`(通道页「串口指令…」) | 发任意 **HEX 字节**透传给扫码枪,预填四条常用指令(静音/恢复蜂鸣/连续扫描/间隔 0s)。换批枪后指令集不同时现场自己试,不用发版 |
| 假死看门狗 | `ScanService.WatchdogLoopAsync` | 每 30s:连接看着在线但 **60s 没字节** → 回查设备侧 `SOCK.ClientIP`(CID 10001 才有)→ 本机 IP 不在里面就强制重连(设备断电重启时 TCP 不发 FIN,`ReadAsync` 会永久挂住) |
| IP 变化 | `ScanService.ApplyDiscoveredIps` | 每次发现结果回来就刷新各通道 `LastIp`,变了立即用新地址重连(DHCP 续租后不会卡在旧 IP) || 通道配置 | `Services/Scan/ChannelStore.cs` | `%LOCALAPPDATA%\YuncangTrace\channels.json`(服务模式:`%ProgramData%\YuncangTrace\channels.json`),通道号取最小空号、删除后不复用;**不再有团购/散单字段**(团散在「工作台」区分) |
| 编排 | `Services/Scan/ScanService.cs` | 启动→连接所有启用通道;**通道一旦变动(增/删/停用)自动同步到服务器**:`POST /api/scan/channels` → `GET /api/scan/channels` 回查确认 → 缺了就退避重试(1s→30s)直到服务器真的有 |
| 扫码记录 | `Services/Scan/ScanRecordStore.cs` | `%LOCALAPPDATA%\YuncangTrace\scan-records.json`(服务模式:`%ProgramData%\YuncangTrace\scan-records.json`),每个通道最多 5000 条;**先落本地、服务器确认后才标「已上传」**,没确认的一直重试,断网不丢;连续扫描只刷新「最近一次扫到的时间」;**扫到后 5 分钟没再扫到同一个码才上报**,上报的就是最后一次扫描时间;同一运单 24 小时内再次扫到会**重新激活同一条本地记录**(不新增行),下一轮上报覆盖服务器记录 |
| 上报队列 | `Services/DeviceService.cs` | 条码静默满 5 分钟后后台攒批(50 条/批)推 `POST /api/scan/records`,失败不标记、指数退避重发(服务端按 设备+通道+条码+秒 精确去重;**同一运单 24 小时内只保留一条,后上报的新时间会覆盖旧记录的时间与工作台快照**) |
### 添加通道(设备名 + 通道号)
`扫描设备 → 选中 → 添加为通道` 会弹窗让用户定**通道号**与**设备名**(与 AndroidScanCenter 一致):
- **通道号**:`1..50` 的下拉框,已占用的号照样列出来并标注「已被 xx 占用」,选中就提示、不关框;
默认勾在最小空号上。没有「通道号」设备字段 —— 它是**本地概念**(现场认工位),上报时就是 `channelId`。
- **设备名**:默认填设备自报的 `HostName`,会**写进设备**(`SYS.HostName`,UTF-8 支持中文)并落 flash;
留空则用设备自报名。写失败**不阻断**添加(只影响设备面板/其他上位机看到的叫法)。
添加顺序是「**先配设备、后落本地**」(回滚本地行不通:设备名可能已经写上去了):
1. 确保设备有给中控用的 TCP 服务(`SOCK` 段 `packcenter / TCP-SERVER / 8087`):
已就绪则不写;缺失/不对则整条写入 → **回读确认**(设备 `RC=0` 只代表报文收到了,端口冲突它不报错);
这一步失败就**整个添加失败**,本地什么都不写(否则会得到一条永远连不上的死通道)。
2. 设备名与自报的不同 → `10005` 写 `SYS.HostName` → `10017` 落 flash(不落盘一次重载就丢)。
3. 才把通道写进本地配置、开始连 TCP,并同步通道列表到服务器。
真机验证(`192.168.9.204`,E10C 1.41.1):`写设备配置 SYS:0` → `保存到 flash:0` →
广播里的 `HostName` 立即变成新名字 → `通道 1(工位 9)已连接 192.168.9.204:8087`。
### 界面
- 主窗口改成页签:**打包查询** / **扫码通道**(后者仅在「设备服务」开启后出现)。
查到条码(协议唤起或通道扫码)时**默认切回「打包查询」页签**并自动查询。
- 扫码通道页:**每个区块的状态与按钮都在各自标题行上**。
- 「扫码通道」标题行:状态(`扫码服务运行中 · 通道 N 个(在线 M)` + 通道同步状态 + 待上传条数)+ `重连全部` / `停用` / `静音`(选中行切换,已静音时叫「恢复蜂鸣」)/ `读取设备配置` / `删除通道`;
通道列表有「状态」「静音」两列;
**没有「同步通道」按钮** —— 通道增删/启停都会自动上传并回查确认;
- 「发现到的设备」标题行:`开始扫描`(**开关**,打开后常驻发现:每 3s 探测、socket 一直收,直到手工停止)+ `添加为通道` + 状态(`正在扫描… 未添加 N 台` / `发现 N 台未添加的设备(另有 M 台已添加)`)。
- **已经添加为通道的设备不会再出现在发现列表里**:显示集合与「发现到的全集」分开存(`_allDevices` / `_devices`),
按通道 MAC 过滤;删掉通道后那台设备会自己回到列表里,不用重新扫。每轮结果按 MAC 合并,不整表覆盖(UDP 丢包时设备不会闪没)。
- 扫码记录页(对应 AndroidScanCenter 的「通道回放」,`Views/ScanRecordsView`):
通道筛选 / `立即上传` / `清空`,列表显示 时间 / 通道 / 号 / 条码 / **已上传或待上传** / 确认时间,
状态行是 `全部通道:显示 N 条 · 本地共 M 条 · 待上传 K 条`。
数据源是本地记录库,所以**服务器挂了也能看到刚才扫了什么、还有多少没传出去**。
- 菜单 **工具 → 打开配置页(后台)**:用系统浏览器打开 `{服务器}/?token=<用户JWT>`,
前端启动时读 `?token=` 存进 localStorage 并把参数从地址栏去掉(免登录,见 `frontend/src/router/index.ts`)。
### 联调验证(本机)
用 `node` 起一个假设备(`127.0.0.1:8087` 推两行条码)→ 开启设备服务 → 日志:
```
[scan] 扫码服务已启动,通道 1 个
[scan] 通道已同步到服务器并确认:1 个
[scan] 通道 1(模拟扫码枪)已连接 127.0.0.1:8087
[scan] 通道 1 扫码:TESTCH-BARCODE-9001(5 分钟未再扫到后上报)
(5 分钟后)
[scan] 已上报扫码 1 条
```
数据库 `scan_records` 里 `channel_id=1`、`device_sn=MINGREN`;工作台可绑定通道 `1/模拟扫码枪`。