# 云仓视频溯源软件(本机服务 / WPF)
Windows 桌面端,用**前端 `/local` 公共页**和 **Chrome 插件**做对接:
- **登录页**:账号密码登录后端(`POST /api/web/auth/login`)拿 user JWT,令牌存本机;
下次启动先用 `/api/web/me` 验证,还有效就直接进主界面;
- 在 `127.0.0.1:17300` 起一个本机 HTTP 服务,浏览器里的页面直接查询本机数据;
- 注册 `yuncang://` 启动协议,网页可以「叫醒」本软件(前提是已安装);
- **托盘图标**:关窗口只是缩到托盘(本机服务不能因关窗断掉),双击托盘恢复窗口,
右键菜单有「打开主界面 / 重启软件 / 退出」;
- **界面不展示服务地址**:登录页和主界面都不显示后端地址 / 本机端口,它们属于内部实现细节;
后端地址由构建注入(`package.config.json` 的 `serverBaseUrl`),需要临时指向别处时用启动参数
`--server=http://x.x.x.x:7300`(只对本次运行生效,不写进界面)。
- **防多开**:全局互斥体 + 命名管道 —— 第二个实例不会抢 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 # 本机 HTTP(17300):查询 / 唤起登录 / 下载录像
├── LoopbackHttpServer.cs # 回环 HTTP/1.1 服务端(TcpListener 自实现,不依赖 HTTP.sys)
├── LocalWsServer.cs # WebSocket(17301):拉通道 / 预览推帧 / 云台 / 满帧率窗口
├── 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 HTTP + 17301 WS)与托盘,再弹登录页 → 登录成功才出主窗口 |
| 启动时检查更新 | 进登录页的同时就开始查 `GET /download/version.json`(老版本用户卡在登录页也能收到提示)。**查到的版本不会塞进登录窗的模态循环**:登录窗还开着就先记下,等主窗口显示完再弹(`_pendingUpdate`)。以前直接盖在登录页上,会撞上「登录窗要关闭、但它挂着模态子窗」→ 父子窗一起被隐藏、两个模态循环互等,**主界面永远出不来**(日志停在 `已恢复登录` 之后,进程还在但没有任何窗口) |
| 已有令牌 | 登录窗一闪而过:`/api/web/me` 通过就直接进主窗口;失效则清掉令牌留在登录页 |
| 关窗口(X) | 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示) |
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 `yuncang://open?code=…` 通过命名管道转给已运行实例;**没带参数(双击快捷方式)也会转发一条 `--show`**,让已运行实例把主界面叫到前面 —— 以前这种情况什么都不发、第二个实例直接退出,表现就是「点图标没反应」 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 托盘右键「重启软件」 | 等 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/query/{code}` 会回 `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. **顺带把该录像机下的摄像头逐个校时**(`GET /api/web/nvrs/:id/channels` 拿通道号 →
`NET_DVR_SET_TIMECFG` 带通道号,录像机转发给 IPC),逐个通道报成功/失败;
4. 回读 NTP 配置与设备时间,在窗口里逐台返回结果(✔/✘ + 偏差 + 摄像头 n/m)。
- **为什么必须单独校摄像头**:画面里烧的 OSD 时间是**摄像头自己**的时钟,录像机录像用的是
录像机时钟 —— 两者互不相干。只校录像机时,有的 IPC 会自己跟随,有的不会(现场实测
通道 34 的 OSD 比录像机快 13 小时、通道 45 差约 2 年),回放再对齐也改不了这两行字。
个别第三方 IPC 会拒绝校时,窗口里会列出具体通道和错误(不影响其它通道)。
- 启动时校一次 + 运行期间默认每 **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`),
即使本机时间临时不准也不会截掉面单。
- **「同步 NVR 时间」直接写时间**:`NET_DVR_SET_TIMECFG` 写的是**设备本地时间**,我们写本机本地时间
(NTP 校准后的值)。前提是**录像机时区必须是东八区**——现场曾把录像机时区设成伦敦(GMT+0),
设备把本地时间当 UTC 推给摄像头,导致录像 OSD 整体跑偏 8~14 小时,而且**烧进视频后改不回来**。
软件走 8000 协议读不到时区,所以这一项由现场保证(时区改好后再同步)。
- **通道名走 8000 私有协议**:`NET_DVR_GET_IPPARACFG_V40`(IP 接入配置)里没有名字,
所以拉通道时对每个 `enabled` 通道再读一次 `NET_DVR_GET_PICCFG_V30`,结构体头部的
`sChanName`(偏移 4,32 字节,**GBK** 编码)就是通道名 —— 实测 32 路约 250ms,中文正常。
**不需要设备的 Web/ISAPI 端口**(很多现场只开 8000)。
- ISAPI 只是兜底:只有当 PICCFG 一个名字都没拿到(极老固件)才去读
`/ISAPI/ContentMgmt/InputProxy/channels`(先 500ms TCP 探测,依次试 80 / 443 / 8443,
设备自签证书不校验,按 IP 匹配、IP 对不上再按 ISAPI 的 `id` 推);
仍然失败就把名字留空,前端拼「NVR名-通道号」,不影响其他字段。
云台探测 / 时区读写**仍然完全不依赖 ISAPI**(`/api/hik/channels` 的 `webPort` 参数已删除,旧前端传了会被忽略)。
## 构建 / 运行 / 发布
## 构建 / 运行 / 发布
```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 / EXE)+ 自动更新
`desktop/installer/` 下有两套安装包定义,产物一样(perUser、装到同一个目录、注册同一个 `yuncang://` 协议):
- **MSI**(`Product.wxs`,**WiX 5**,免费;WiX v6+ 需要 OSMF 付费协议,别装最新版);
- **EXE**(`YuncangTrace.iss`,**Inno Setup 6**)——**完全不依赖 Windows Installer**。
> 为什么要 EXE:现场有电脑装不了 MSI(Windows Installer 服务被禁用 / 安全软件拦 MSI / 组策略禁止)。
> 这类机器用 EXE 版;装过旧 MSI 的机器再装 EXE 时,EXE 会先静默卸载旧 MSI,不会在「应用和功能」里留两个条目
> (旧 MSI 的卸载会把文件删掉,必须清掉)。MSI 卸载失败(正是 MSI 坏掉的现场)时,EXE 会尽量移除它的卸载项
> (HKLM 下的条目要管理员权限,删不掉只记日志)—— 避免以后误点「卸载」把新装的文件删了。
```powershell
# 工具只需装一次
dotnet tool install --global wix --version 5.0.2 # MSI
winget install --id JRSoftware.InnoSetup # EXE(提供 ISCC.exe)
cd desktop\installer
.\build.ps1 # 开发环境(默认),版本取 csproj,MSI + EXE 都打
.\build.ps1 -Target Exe # 只打 EXE
.\build.ps1 -Target Msi # 只打 MSI(老流程)
.\build.ps1 -Version 1.0.1 # 指定版本
.\build.ps1 -Environment Production -Version 1.0.1 -ReleaseNotes "修复若干问题"
.\build.ps1 -Target Exe -SkipDeploy # 只在 out\ 出包,不复制到后端(调打包用)
```
### 环境与域名(`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\**`、`..\extension\**` 作为独立文件输出**(不走单文件自解压);
缺 `publish\native\ffmpeg\ffmpeg.exe` 会直接报错中止;
2. `wix build` 生成 MSI(`Product.wxs` 用 ``、``
递归收集,保持目录结构;`extension\test` / `extension\tools` 这类调试文件不打进包);
`ISCC` 生成 EXE(`YuncangTrace.iss` 把 `publish\` 下的 exe / `native\**` / `extension\**` 打进单个安装包);
3. 算 MD5 → 写 `version.json`(MSI 一份、EXE 一份);
4. 复制到后端:安装包 → `backend/app/public/download/desktop/`,`version.json` → `backend/app/public/version/desktop/`;
5. 本地 `out/` 与后端目录**各只保留最近 5 个**安装包(`.msi` / `.exe` 分别算,`keepVersions` 可配)。
> 安装包与版本信息都归到后端 `desktop` 子目录:下载地址 `<域名>/download/desktop/YuncangTraceSetup-x.y.z.exe`(新客户端)
> 和 `.msi`(老客户端),版本信息仍是 `<域名>/download/version.json`(老客户端写死了这个地址,不能改)。
### 谷歌浏览器插件
仓库根目录的 `extension/` 会一起打进 MSI / EXE,安装后固定在 **`<安装目录>\extension`**
(perUser 安装即 `%LOCALAPPDATA%\Programs\YuncangTrace\extension`)。
**推荐:企业策略安装(零开发者模式)** —— `Services/ExtensionInstaller.cs`:
- 菜单「工具 → **安装谷歌插件(Chrome / Edge)**」:先拉后端 `/download/extension/updates.xml`
读出扩展 ID,再生成 `.reg` 文件、**runas 执行 `reg import`** 写 HKLM 策略(Chrome + Edge),
最后**读注册表**确认结果(不依赖子进程回传,早期用「提权起自己 + 临时文件回传」现场踩过
「退出码 0 但结果文件没写」的坑):
- `ExtensionInstallForcelist = ;https://<域名>/download/extension/updates.xml`
- `ExtensionInstallSources = https://<域名>/download/extension/*`
- 重启浏览器后自动装好,之后由 `updates.xml` 自己升级;`chrome://extensions` 里显示「由你的组织管理」;
- 菜单「工具 → **卸载谷歌插件**」:只删值里带 `/download/extension/` 的那几条,不影响别人写的策略;
- 前提:发布端已执行过 `cd backend && npm run extension:publish`(产出 `.crx` + `updates.xml`);
扩展 ID 由 `extension/keys/key.pem` 决定,**换私钥 = 换 ID = 已下发策略失效**,私钥务必备份;
- 提权失败(没有管理员权限)时提示用户走下面的开发者模式。
**兜底:开发者模式** ——
- 菜单「工具 → 复制插件路径(开发者模式)」直接把该目录的 **Windows 路径**(如 `C:\Users\xxx\AppData\Local\Programs\YuncangTrace\extension`)复制到剪贴板;
写剪贴板会重试(WPF → WinForms,各 3 次 ×150ms),被输入法/剪贴板工具/远程桌面占用时不会直接报 `CLIPBRD_E_CANT_OPEN`;
仍然失败会提示原因,并可以选「打开记事本」把路径显示出来手动抄写;
- 用户打开 `chrome://extensions` → 打开「开发者模式」→「加载已解压的扩展程序」→ 粘贴路径即可;
- 卸载时该目录随安装包一起删除;
### 自动更新怎么工作
```
软件启动(登录后)→ GET {后端}/download/version.json?t=时间戳
→ version.json 的 version 比当前程序集版本新
→ 软件内弹窗:新版本号 / 更新说明 / 安装包大小
→ 点「立即更新」→ **软件内下载(进度条)**→ MD5 校验
→ 自动静默安装(EXE 走 /VERYSILENT /SUPPRESSMSGBOXES /NORESTART;MSI 走 msiexec /passive)
→ 软件退出 → 装完自动重新打开
```
- **不跳浏览器**:下载、进度、校验、安装都在软件里完成。
- 下载落在 `%TEMP%\YuncangTraceUpdate\`,文件名取下载地址里的真实文件名。
- 安装前会等 3 秒(让本进程先退出,否则 exe 被占用换不掉);perUser 安装不需要管理员。
- **优先 EXE 包**:`version.json` 有 `downloadUrlExe` 就下 EXE(不依赖 Windows Installer,现场装不了 MSI 的机器也能升);
- **校验值必须成对取**:下 EXE 用 `md5Exe` / `sizeExe`,下 MSI 用 `md5` / `size`。
(`≤1.0.151` 的旧客户端两个都取 `md5`,于是下 EXE 拿 MSI 的哈希去比 → 必然「MD5 不一致」;
给这些机器的第一个修复版要只发 MSI,见 backend/README 的 `--target=Msi`);
没有该字段才退回 `downloadUrl`(MSI)。老客户端只认 `downloadUrl`,所以打包脚本**默认两个包都出**。
- **版本一致性防护**:若下载地址里的包版本(`YuncangTraceSetup-x.y.z.msi` / `.exe`)不比当前版本新,
直接忽略 —— 防止 version.json 配错/漏传包导致「装完还是旧版 → 无限弹窗」。
- 回归测试可用环境变量 `YUNCANG_AUTO_UPDATE=1` 让弹窗出现后自动开始下载(无需手点)。
`version.json` 长这样(脚本生成,**不用手写**):
```json
{
"version": "1.0.1",
"downloadUrl": "https://正式域名/download/desktop/YuncangTraceSetup-1.0.1.msi",
"md5": "7a93b4…",
"size": 141578240,
"downloadUrlExe": "https://正式域名/download/desktop/YuncangTraceSetup-1.0.1.exe",
"md5Exe": "d5c75e…",
"sizeExe": 118886550,
"publishedAt": "2026-10-17T12:00:58+08:00",
"buildId": "20261017120058",
"environment": "Production",
"releaseNotes": "修复若干问题"
}
```
> `downloadUrl`(MSI)是给老客户端的,**不能删**;`downloadUrlExe` 是新增字段,新客户端优先用它。
### ⚠️ 缓存(这里最容易踩坑)
Egg 的 `static` 在生产默认**强缓存一年**。如果 `version.json` 也被缓存,软件永远检测不到更新。
处理方式(都已实现):
| 层 | 做法 |
| --- | --- |
| 文件位置 | `version.json` 放在 `app/public/version/desktop/`,**不在静态目录里** |
| 后端路由 | `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 由 Windows Installer 删除;EXE 由安装目录下的 `unins000.exe` 删除。两者都会清掉 exe、协议注册、开始菜单 —— 即「取消注册」 |
| 升级 | MSI:`MajorUpgrade`(装新版替换旧版、拦降级);EXE:同一个 `AppId` 覆盖安装;**EXE ↔ MSI 可互相顶替**(装 EXE 时会先静默卸载旧 MSI) |
| 用户数据 | `%LOCALAPPDATA%\YuncangTrace\{settings,session}.json` 卸载**不删**(重装后仍保持设置/登录) |
```powershell
msiexec /i out\YuncangTraceSetup-1.0.1.msi # MSI 安装
msiexec /x out\YuncangTraceSetup-1.0.1.msi # MSI 卸载
.\out\YuncangTraceSetup-1.0.1.exe # EXE 安装(双击即可,免管理员)
.\out\YuncangTraceSetup-1.0.1.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /SP- # EXE 静默安装
```
> 需要「本机所有用户都能用」时:`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)
```
> 每次测更新都要打一个**比当前安装版本高**的包(脚本会拒绝在"已是最新"时白跑)。
## 本机接口
本机软件开**两个**端口,职责分开:
| 端口 | 协议 | 用途 |
| --- | --- | --- |
| **17300** | HTTP | 运单查询 / 唤起登录 / 按运单下载录像(低频、无状态) |
| **17301** | WebSocket | 拉通道 / 实时预览(推 JPEG 帧)/ 云台 / 满帧率窗口(预览相关全在这里) |
### HTTP 17300(前端 `/local` 页用的就是这两个)
服务固定监听 `http://localhost:17300`(端口写在前端页面与插件里)。
`LoopbackHttpServer` 直接监听 **127.0.0.1 和 ::1**,所以 `localhost` / `127.0.0.1` 两种写法都能连
(前端改 `VITE_LOCAL_SERVICE` 时不会碰到「回 400」)。请求的 `Host` 不是回环地址会被直接断开。
> ⚠️ **别改回 `HttpListener`**:它依赖 HTTP.sys。现场机器上 HTTP 服务被安全软件/系统优化禁用,
> 或者卡在 STOP_PENDING 时,`HttpListener.Start()` 会抛 `句柄无效(6)`,HTTP 与 WS 会**同时**起不来
> (2026-10-23 升级 1.0.113 后的现场故障就是它)。自建 TcpListener 不需要 HTTP.sys / urlacl / 管理员权限。
浏览器直接打开 会看到一个说明页(列了接口,方便排查)。
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/query/{code}` | 查信息,**同时把服务/登录状态一起返回**(见下)。没登录 → 401 `state:need-login` |
| POST | `/api/activate-login` | 把本机软件的**登录窗叫到前台**(已登录时把主界面叫到前台)。网页收到 `need-login` 时自动调它 |
| POST | `/api/playback/download` | 按运单下载录像(存到本机设置目录) |
> ⚠️ 以前的海康接口(`/api/hik/channels`、`/api/hik/preview*`、`/api/hik/ptz*`)**已全部迁移到 WS 17301**,
> HTTP 侧不再提供(访问会得到 404「接口不存在」)。前端 `api/localWs.ts` 是唯一调用入口。
### WebSocket 17301(预览 / 云台 / 拉通道)
一条连接可同时推多路画面(一条工作台合成画面 4 路没问题)。文本请求 `{id, action, ...}`,
回复 `{id, ok, data | message}`;二进制帧 = `[1 字节 sid 长度][sid ASCII][JPEG]`。
| action | 参数 | 说明 |
| --- | --- | --- |
| `hello` | — | 服务名/版本/端口/登录状态 |
| `ping` | — | 探活 |
| `get_channels` | `host, port, user, password` | 走 8000 私有协议登录 NVR,返回通道列表(与原来 HTTP 返回同构) |
| `start_preview` | + `channel, fps?, streamType?, mode?, logicalChannel?, name?` | 建预览会话,之后持续推该 `sid` 的 JPEG 帧 |
| `stop_preview` | `sid` | 停一路、释放设备码流 |
| `open_window` | 同 `start_preview` | 在本机软件里开**满帧率原生窗口**(PlayM4 直渲染,25fps) |
| `close_window` | `wid` | 关原生窗口(网页断开时也会自动关) |
| `ptz` | + `command, stop?, speed?` | 云台连续动作(`stop=true` 停) |
| `ptz_preset` | + `presetAction`(set/goto/clear), `preset` | 预置点 |
> `start_preview` / `get_channels` / `open_window` / `ptz*` 在服务端**并发执行**,不会把
> 「停止预览 / 云台停转」堵在消息循环后面;云台命令之间按连接串行化,保证「开始转 → 停」不乱序。
>
> 端口可用 `YUNCANG_LOCAL_WS_PORT` 覆盖;前端用 `VITE_LOCAL_WS` 覆盖默认 `ws://127.0.0.1:17301/`。
#### 预览延迟(子码流 / 主码流是两条完全不同的链路)
| 码流 | 链路 | 典型延迟 |
| --- | --- | --- |
| 子码流(`mode=stream`) | 8000 私有协议 → PlayM4 解码 → 取 JPEG | 低,稳定 |
| 主码流(`mode=ffmpeg`) | RTSP → ffmpeg 解码/缩放 → 编码 JPEG | 取决于传输方式 |
主码流**不能走 TCP**:RTP over TCP 一旦有排队(设备发送缓冲、交换队列),延迟只会越堆越高、
而且永远不会自己追回来(TCP 不丢帧)。所以实时预览的 ffmpeg 参数固定为:
- 传输 `-rtsp_transport udp`(丢包宁可丢帧,不排队;4 秒还收不到帧会**自动回退 TCP**,
因为部分网络禁 UDP,不能让用户看不了画面);
- `-analyzeduration 0 -max_delay 0 -reorder_queue_size 0 -avioflags direct -fflags nobuffer -flags low_delay -fps_mode passthrough`
(不分析流、不攒包、输出侧不补帧);
- 回放(`OpenUrl` 的 `lowLatency=false`)**保持 TCP**:回放靠时间戳对齐,丢包会算错延迟。
排查用日志(`logs\log_日期.txt`):
- `ffmpeg 已启动:... UDP` / `TCP` —— 实际用的传输方式;
- `[ffmpeg] 首帧到达:... 用时 320ms(UDP)` —— 首帧耗时;
- `[ffmpeg] UDP 收不到帧,回退 TCP` —— 该网络不通 UDP。
### 为什么没有单独的「探活 / 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」或干脆没反应)。
- **界面上完全不展示协议**:注册由安装包完成、卸载时自动删除,启动时自动校正到当前 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 秒,面板里显示进度),**任意一路拉到录像就停止校验**并显示「预览回放 / 下载录像」按钮 ——
> 不需要把每一路都验完,也不需要用户手动点「校验」。
> 预览和下载仍按**全部**流处理:没录像的那几路在下载时自己跳过,保证多路合并不会退化成单路。
>
> **跨网(查询机和录像机不在同一张网里)**:局域网找不到「设备管理服务」时改问云端,由**能访问
> 录像机的仓库扫码服务**校验;这种查询只给「下载录像」,而且下载**走云端中转**(云端建任务 →
> 仓库设备拉流合并并上传 → 本机把成片取回),不再让本机直连录像机 —— 查询机到仓库 NVR 的
> 8000/554 本来就不通,直连只会让 ffmpeg 报 `退出码 -138`(RTSP 连接超时,`AVERROR(ETIMEDOUT)`)。
>
> **回放时间按录像机时钟对齐**:扫码时间来自本机时钟,回放是按录像机本地时间定位的。
> 每次校验/预览/下载前会读一次录像机时间(8000 私有协议),把请求窗口整体平移,
> 日志里能看到 `[playback] 录像机 … 与本机时钟相差 X 秒`。本机时间不准(比如 Windows
> 时间服务没开、慢了几秒)时,短回放窗口会把面单截到窗口外 —— 这一步就是防这个。
### 多路对齐(预览 / 合并下载)
几路回放是**各自独立连录像机**的,天然会有两处时间差,都要单独处理:
1. **开播时间差(预览)**:各路 RTSP 建链快慢不同,先出帧的那路会一直“跑在前面”。
`PlaybackPreviewWindow` 的做法是**先一起等、再按帧一起放**:
- ffmpeg **每出一帧回调一次**(`HikFfmpegService.Subscribe`)按顺序进各自队列。
⚠️ 不能定时去取“最新一帧”:ffmpeg 定位到关键帧后会把「关键帧→请求时间」整段一次吐出来,
只留最新帧会把这串前面全丢掉,那一路的“第一帧”其实是 1~2 秒后的画面(现象:小窗一出现就超前);
- 每一路都出过第一帧(最多等 12 秒,超时当这路没录像)后才开始播,每 40ms 从**每路队列各取一帧**,
先上线的那路放的就是等同步时攒下的积压 → 几路自然停在同一内容位置;
- 队列超过 220 帧(≈9 秒)就丢到 50 帧(≈2 秒),设备推得比实时快也不会越播越晚。
日志里出现 `[playback] 多路回放开始同步播放(各路基线帧数:…)` 就说明生效了。
**收尾以最长的那一路为准**:各路是从自己的关键帧起推的,同样 8 秒的请求,20fps 那路只有 8.0 秒、
25fps 那路有 9.0 秒;所以不看请求窗口,而是看「队列空了 + 1.5 秒没再收到新帧」判定这一路播完,
**先播完的那路定格在最后一帧**,等最长的那路播完再统一释放设备会话(另有
`Window + 15 秒` 的硬上限,防止设备一直推)。标题变成「回放结束(Xs)」,X 就是最长那路的时长。
2. **录制起点差(下载 / 合并 / 预览)**:回放是从“请求时间所在**关键帧**”开始推的,
各通道 GOP 位置不同 → 同一时间点开始拉的两段录像,第一帧能差好几秒;
不处理就会两格画面错开。
**用 `NET_DVR_GetPlayBackOsdTime` 读第一帧的真实内容时间**(8000 协议,实测可用):
- 下载:`PullPlaybackToFile` 在第一包数据到达时读一次,`偏移 = 首帧 OSD − 请求时间`,
合并时提前的路用 `trim` 切头、晚开始的路用 `setpts` 后移
(日志 `[playback] 通道N 首帧 OSD=hh:mm:ss,比请求时间早/晚 X 秒`);
- 合并:**总时长取最长的那一段**(合并前读各段的真实时长),短的那格在 `overlay` 里定格最后一帧,
按请求窗口截会把从关键帧提前起推的那段尾巴切掉(日志 `[playback] 合并时长按最长的一段算:…`);
- 预览:RTSP 侧拿不到内容时间,所以开窗前先用 `ProbePlaybackOsdStart` 每路探一次,
按 OSD 差值推迟出图(日志 `[playback] 预览按 OSD 起点对齐:…`)。
- 拿不到 OSD(固件不支持/无数据)才退回「时长反推」(`提前量 = 文件时长 − 请求窗口`);
偏差超过 60 秒视为通道时钟异常,不做对齐,绝不把画面推歪。
⚠️ 曾经只用「时长反推」,实测同一个窗口拉两次会得到 36.1s / 42.1s 两种结果
(关键帧起止 + 流在哪断都不固定),头和尾分不开 → 会随机差 2~4 秒,已弃用为首选。
3. **摄像头自身的时钟**:画面里烧的 OSD 时间是**摄像头自己**打的,和录像机的录像时间轴无关。
两个摄像头时钟不一致时,即便回放已经对齐,两格 OSD 也会差几小时甚至几年 ——
这不是回放错位,要在录像机里开「摄像机校时(IPC 校时)」或给 IPC 配 NTP 才能一致。
查询日志只记结论(`[pack-query] 运单号 → found=… records=… streams=…`),不再写完整 JSON;
要排查原始数据看后端日志或页面。
要换成别的数据源,只改 `OrderQueryService.QueryAsync` 一个方法就行(返回 `QueryResult`,
`Data` 是扁平字典即可,前端 `/local` 页也吃这份数据)。
### 扫码 → 查询(不跳页)
- 手动输入 / 回车 / 点查询 / 协议唤起:`RunQueryAsync()`,**切到「打包查询」页**展示;
- 通道扫码:`OnChannelBarcode` 后台算一次结果,**绝不切页签**
(用户还在「扫码通道 / 扫码记录」页时,只在「打包查询」页签上加 `●`,
切过去时才把结果显示出来);
- 扫码数据本身仍由 `ScanService` 落记录 + 上报,跟查询是两条独立的路。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 启动报「句柄无效」/ `句柄无效 (6)` | 老版本用 `HttpListener`(HTTP.sys)才会这样:系统的 HTTP 服务被禁用或卡在 STOP_PENDING。本次修复起本机服务改成自建 TcpListener,不再依赖 HTTP.sys;老版本临时处理可 `net start http` 或重启电脑 |
| 启动报「没有绑定端口的权限」/ `Access is denied (5)` | 端口被安全软件拦了;换端口(`YUNCANG_LOCAL_PORT`)或加白名单 |
| 报端口被占用(`AddressAlreadyInUse`) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
| 双击图标没反应 / 主界面打不开,托盘图标还在 | 1.0.134 起:再次启动会把已运行实例的主界面叫到前面(托盘双击也行)。更老的版本点了没反应是正常的(第二个实例直接退出),从托盘打开即可 |
| 升级后主界面仍然出不来 | 看日志最后几行:停在 `准备显示更新窗口…` 之后就是老版本的「更新窗盖在登录窗上」死锁,装新版本即可;有 `[app] 主窗口没建:server=… session=… api=…` 说明登录态没建立 |
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 `http://localhost:17300/api/query/`(会回 400 但带登录状态):打不开→防火墙/端口;打得开→多半是 CORS 头没回。预览类问题则看 `ws://127.0.0.1:17301/` 能不能打开(直接浏览器访问应该返回一小段 JSON) |
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
| 唤起时弹「You must install .NET Desktop Runtime」 | 唤起的是 `bin\Debug` 这类 framework-dependent 的 exe(拿不到 `DOTNET_ROOT`)。用自包含发布产物,并让它启动一次以校正注册表 |
| 改了协议名 | 注册表重注册 + 前端 `VITE_APP_PROTOCOL` 同步 + 插件目标地址同步 |
## 主体切换 / 微信扫码登录 / 设备服务(2026-10-18)
### 登录窗
- **微信扫码登录**(2026-10-28 起走微信登录网关):点「微信扫码登录」→
`POST /api/web/auth/wechat-gateway/qrcode` 申请二维码 → 显示二维码
(`GET /api/wechat-gateway/qrcode.gif?state=`,WPF 不能渲染 SVG 所以后端额外给了 GIF 版)→ 长轮询
`GET /api/web/auth/wechat-gateway/login?state=&wait=25`,手机微信确认后直接拿令牌进主界面;
二维码过期(`expired`)会自动重新申请一张,绑定状态不对(`failed`)直接把服务端给的原因显示在二维码下面。
⚠️ 只有**已经绑定过微信**的账号才能扫码登录(绑定入口在网页版「个人中心 → 微信绑定」)。
- 账号密码登录与微信登录**都会带回主体列表**(`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 侧实测“字节发出去了但枪没执行”时无法判断 |
| 改名 | `ScanService.RenameChannelAsync`(通道页「重命名」) | 已添加的通道**直接改名**,不用删了再添加(删除会让服务器软删该通道并解绑工作台、通道号还可能变)。名字落本机 `channels.json` + 普通推送同步服务器(`POST /api/scan/channels` 按 `channelId` 更新 `channelName`),可选同时写设备 `SYS.HostName`(写失败不回滚本机改名)。服务模式下本机只落文件,后台服务发现文件变了会自己重载 |
| 串口指令调试 | `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`(增删带 `replace: true`,全量对账;改名只是更新名称)→ `GET /api/scan/channels` 回查确认 → 缺了就退避重试(1s→30s)直到服务器真的有;**删除通道会让服务器软删该通道并解绑工作台**(`removed` / `unbound`),删到 0 个也会推空列表 |
| 扫码记录 | `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`(有积压时上报循环每秒醒一次,空闲 30 秒),失败不标记、指数退避重发(服务端按 设备+通道+条码+秒 精确去重;**同一运单 24 小时内只保留一条,后上报的新时间会覆盖旧记录的时间与工作台快照**)。**主体过期/停用或令牌失效 → 暂停推送**(保留本地积压、不做无意义重试),暂停期间每 60 秒只发一次心跳;心跳返回 `subject.expired=false`(续费)后自动恢复并补传 |
### 添加通道(设备名 + 通道号)
`扫描设备 → 选中 → 添加为通道` 会弹窗让用户定**通道号**与**设备名**(与 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`。
### 重命名通道
`扫码通道 → 选中一行 → 重命名`:只改**名字**,通道号不动(通道号是现场认工位的号)。
- 名字先落本机 `channels.json`,再用**普通推送**同步服务器(`channelId` 不变,服务器按 id 更新
`channel_name`);不走 `replace` 全量对账,所以不会误删别的通道、也不会解绑工作台;
- 「同时把名称写入设备(`SYS.HostName`)」默认勾选(与添加通道一致),设备 IP 未知时该选项不可用;
写失败**只提示**,本机改名照样生效(设备名只影响设备面板/其他上位机看到的叫法,不影响收码);
- 名字没变就只按需补写设备名,不白刷一次服务器;
- 服务模式:桌面端只写通道文件,后台服务发现文件时间变了会重新加载并重连
(日志 `[agent] channels.json 已变更,重新加载通道`)。
### 面单摄像头(独立页签:配置 + 拉流识别)
「面单摄像头」是**单独的页签**(与「扫码通道/扫码记录」一起显示),每路一行:
`工作台 | 摄像头 | 上报通道 | 状态(识别中/启动中/异常/已停止) | 最近识别到的条码 | 首次识别时间 | 最近命中 | 码流 | 解码耗时 | 次数 | 备注`。
- **首次识别时间**:这条记录真正拿去上报/落库的时间,面单一直摆在拍摄区**不会刷新**(重复命中不改时间);
- **最近命中**:摄像头最近一次解码成功的时刻,每秒都在跳,只用来判断「摄像头有没有在看/对着条码」;
- **码流**:当前实际用的是主码流还是子码流、分辨率多少;
- **解码耗时**:最近一帧「OpenCV 检测 + 透视矫正 + ZXing 解码」花了多少毫秒,用来判断机器吃不吃得消;
- 行是按 `工作台|摄像头|通道` 原地更新的(不整体重画),只有值真变了才会重绘。
顶部状态行显示 `已拉取 N 路 · 时间`,底部的黄字是服务端提示(例如「摄像头找不到录像机」「录像机没有保存密码」)。
数据来源:服务模式下由**后台服务**拉配置 + 识别,界面读 `agent-status.json` 的 `LabelScan`
(后台服务每 **400ms** 写一轮、界面每 **300ms** 轮询一次,识别到就是几百毫秒内能看到);
普通模式下直接读本进程 `ScanService.LabelScan`。
#### 配置拉取(`LabelScanMonitor`)
- 服务启动拉一次 + **每 1 分钟**兜底(推送可能丢:设备正好离线、edge 任务 TTL 过期、推送失败);
以前是 5 分钟,现场在网页上改完面单摄像头要等好几分钟才生效,看起来就是「取消的那路还在跑、新增的不启动」;
- 收到 `labelScan.refresh`(**服务端**在 Web 端改了面单摄像头/工作台/上报通道后主动推的 edge 任务)立即重拉;
- 记住 `revision`:内容变了才写一条「配置变更」日志;
- 拉完就**对账**:新增的启动识别、配置变了的重建、消失的停掉;没变的不打断(轮询很密,不能断流);
- 对账单路失败(构造/启动异常)只记日志并清掉半成品,**不影响其它路**,下一轮会重试。
#### 识别(`LabelScanWorker`)
```
ffmpeg(RTSP, tcp) → 灰度 rawvideo 帧 → 读帧线程只留最新一帧(按 DecodeFps 限速)
→ OpenCV BarcodeDetector 整图检测(cv::barcode,输出条码四角点,带旋转/透视)
→ 无候选 = 画面里没面单,直接丢掉
→ 有候选:逐个透视矫正成轴对齐小图 → ZXing 解 CODE_128 → CleanBarcode 校验
→ 命中入队(扫描线程不等) → 上报线程:写记录 + 立即上报 + 通知安卓播报
```
- **为什么用 OpenCV 检测而不是自己找 ROI**:现场面单是**竖放或斜着**摆的(实测四角点
`(433,602)(450,514)(1371,685)(1354,774)`,倾斜约 5°)。1D 码要求扫描线完整穿过整条,
按「行梯度能量」找横带再轴对齐裁剪,会把条码截断 → **必然解不出**(实测 0 命中)。
OpenCV 给的是四角点,透视矫正后条码完整,实测 1920×1080 整图 **检测约 10~15ms + 解码约 1ms**,
3/3 帧命中、无面单画面 3/3 帧 0 候选(无假阳性)。
- **退避(隔帧检测)**:① 同一个码连续命中 3 次(面单没动)② 连续 3 帧没结果(画面里没面单)→ 之后隔帧检测;
一旦**画面变化**(面单拿走/换新/有人手伸进来,靠 32×18 缩略图平均灰度差 > 6 判定)立刻恢复全帧率。
实测面单摆着不动时 CPU 直接减半,新面单放上去不额外延迟。
- **选流**:先试子码流,**宽度够 1080 才用**(拉流解码开销只有主码流的 1/7,更省 CPU);
太小就退回主码流并在日志里说明。实测这台录像机子码流 800×448,条码只有 1.8px/模块,
同样设置**读不出来**;把子码流调到 1280×720 即可自动启用;
- **延迟**:`ffmpeg -threads 2`。HEVC 默认帧级多线程会把输出往后压好几帧 ——
用画面里的时间水印实测「OSD 时间 → 本机收到帧」:默认线程 **2.6s**、`-threads 1/2` **0.5s**、
加 `-fflags nobuffer -flags low_delay` 反而更慢(2.9s)。输入 20fps、我们只取 8fps,2 线程完全够;
- **不积压**:读帧线程始终把管道读空、只保留最新一帧,旧帧直接丢(`FrameLag` 恒为 0~个位数);
上报走独立线程 + 8 条缓冲队列,写记录/上报/通知安卓再慢也不会拖住识别;
- **RTSP 通道序号**:库里存的是设备通道号(数字通道从 33 起),RTSP 要 1 起序号,
所以按 `channelNo-32 → channelNo` 依次探测,成功后**记住**(日志 `码流就绪:主码流 2304x1296(序号 3201)`);
- 条码过滤:4~64 位、只含常见条码字符、**至少 6 位数字**(压掉摄像头误识别噪声);
- 同一张面单连续命中节流到 500ms 一次:足够维持「在场」状态,又不会刷上报;
- 断流自动重连(3 秒),连续失败按 3/10 次节流打日志;不影响扫码枪链路。
排障字段(`agent-status.json` 的 `LabelScan.Items[]`):
| 字段 | 含义 |
|---|---|
| `LastPath` | `OpenCV解码` / `无候选` / `候选未解出` / `稳态退避` / `失败退避` |
| `LastCvMs` | OpenCV 整图检测耗时 |
| `LastDecodeMs` | 透视矫正 + ZXing 解码耗时 |
| `RoiText` | 矫正后的条码尺寸(如 `条码 937x90`),或 `无候选` |
| `RoiRatio` | 矫正+解码耗时(毫秒) |
| `FrameLag` / `FrameDropped` | 取帧时的积压帧数 / 累计丢弃旧帧数(正常应接近 0) |
| `FramesRead` / `FrameThrottled` / `FramesDecoded` | 管道读到 / 限速丢弃 / 实际处理 的帧数 |
| `LastWaitMs` / `LastLoopMs` | 等新帧耗时 / 两次取帧的完整周期(看瓶颈在「帧不够」还是「处理慢」) |
| `RoiFailStreak` / `SteadyHits` | 连续无结果次数 / 连续命中次数(≥3 触发隔帧退避) |
日志样例:
```
[label-scan] 已拉取面单识别配置(启动):1 路,revision=sha1:df244c17781de5ba
[label-scan] 散单1号 → 测试散单面单(241 通道 64,主码流)→ 上报通道 2「测试安卓」
[label-scan] 散单1号 → 测试散单面单… 子码流只有 800x448(条码像素不够,读不出来),改用主码流
[label-scan] 散单1号 → 测试散单面单… 码流就绪:主码流 2304x1296(序号 3201)
[label-scan] 识别到条码:SF1164748936737(通道 2,首次 10-24 16:19:26,倾角 -12°,解码 38ms,新记录=True,播报=True)
```
页签里的「码流」「解码耗时」两列就是上面这些信息,现场调机位时能直接看出问题在哪一层。
⚠️ 配置快照里含录像机密码:只放内存,不落盘、不写日志、界面文案也不显示。
### 摄像头识别结果 → 记录 + 安卓播报通知
在「工作台 → 绑定管理」里把某路摄像头设为**面单摄像头**(每个工作台只保留一路,散单/团购都能设)后,识别到的条码
统一走 `ScanService.ReportCameraScanAsync(channelId, channelName, code, wsType)`。
**与扫码枪的差别(现场场景:面单放进拍摄区 → 开始打包 → 打包完才取走)**:
| | 扫码枪(团购) | 面单摄像头(散单) |
|---|---|---|
| 时间 | **最后一次**扫描(包裹离开扫码器) | **第一次**识别(面单进入拍摄区);面单没离开画面就**永不前移** |
| 上报时机 | 静默 5 秒后 | **写入即上报**(`ScanRecordItem.Immediate`) |
| 视野内重复命中 | 刷新时间 | **什么都不做**(不改时间、不重复上报、不重复播报) |
| 中途被手挡/移位/反光(面单还在画面里) | 刷新成新时间 | **仍算同一轮,时间不前移** |
| 面单真的被拿走(画面里连续 45 秒没有任何条码)后再放回 | 刷新成新时间 | 当作**新一轮打包**,用**这次**的时间(装错了重新打包、20 分钟后重新称重再包一遍都属于这种) |
**工作台类型决定规则**(后端下发的 `wsType`,见 `LabelScanMonitor.ModeOf`):
| | 散单(wsType=1) | 团购(wsType=2) |
|---|---|---|
| 面单摄像头识别 | 取**第一次** + 立即上报 | 和扫码枪一样:静默 5 秒、取**最后一次** |
| 扫码枪 | 同样取**第一次** + 立即上报(`DeviceService.ReportFirstSeen`,5 秒内重复算一次) | 静默 5 秒、取**最后一次**(不变) |
**工作台没接扫码枪也能用**(摄像头完全替代扫码枪):服务端会给这种工作台一条**虚拟通道**
`CAM-<工作台id>`(名字 `面单摄像头·<摄像头名>`),下发的 `items[].virtualChannel = true`。
设备端照常上报即可,差别只有:
- 通道名从配置里取(`LabelScanMonitor.ChannelNameOf`),因为 `CAM-` 不在本机 `channels.json` 里;
- `channels[]` 里也会带这条虚拟通道,所以记录规则照旧按 `wsType` 走;
- 虚拟通道没有对应的扫码工位,`NotifyScanSuccessAsync` 找不到安卓通道 → **不播报**(正常现象);
- 这类工作台在 Web 端「绑定管理」里看不到「没绑扫码通道」的警告,虚拟通道带「虚拟」标记、不给解绑。
- **「离开」只有一个判据**:画面里**连续 45 秒没有任何条码**(`LabelScanWorker.RepackAbsence`)。
识别线程和上报层共用这个值(`ScanService.CameraPresenceGap` = 它),避免出现
「算重新进去了、但时间没更新」的漏洞。在场状态是**按「通道|条码」**记的,
所以换一张新面单永远是新建记录、不受这个值影响。
- **为什么用「画面里有没有条码」而不是「有没有解出码」**:接入 OpenCV 后 `无候选` 是可信的
(面单在视野里就一定有候选);而「解不出」还会发生在面单明明在场的时候(反光、遮住一角)。
- **时间绝不因为识别空档前移**(这是修过的现场问题):面单一直摆着、中途被手挡一会儿,
以前会被当成「离开又回来」,加上这中间通道上又扫过别的包裹,打包时间直接被改成
「开始打包 30 秒之后」,录像定位整体偏移。**「中间扫过别的包裹」不是重新打包的信号**
—— 两张面单轮流进入视野就会命中,但那两张都没离开过。
- **真正的新一轮打包会被识别**:面单被拿走(画面里连续 45 秒没有条码)后再放回,
记录时间更新成这一次(`ScanService.ResolveCameraScanTime` 的 `afterAbsence`)。
例如 20 分钟后发现称重不对、开箱重装再包一遍 —— 只要换货期间面单离开了画面就成立。
- **时间只认记录**:上报/界面显示的时间都取本地记录里那条的 `ScannedAt`,
在场判定只决定「要不要重新上报一次 + 时间要不要更新」,服务重启、丢帧都不会把时间推后;
- **记录永远写**:与通道类型、安卓是否在线、设备服务是否开启无关。断网/离线只是留在本地队列等重试;
- **通知要回执**:只对 `AndroidStation` 通道发 `0x1E{"cmd":"scan","id":…,"code":…}\n`,
等设备回 `0x1E{"cmd":"ack","id":…}\n`(1.2 秒超时,最多重发 2 次)。
`CameraScanResult.Notified=false` 只代表「没确认到播报」,**不代表没记上**;
网口扫码枪没有语音能力,不发(避免被透传到枪的串口)。
**设备端要求 AndroidStation ≥ 1.0.3**:1.0.1 还不认识 0x1E 控制帧(表现为「安卓端没回执」),
1.0.2 起会把 ack 里的 id 过滤掉非字母数字字符导致桌面端永远比对不上,1.0.3 已改成原样回显。
### 界面
- 主窗口改成页签:**打包查询** / **扫码通道**(后者仅在「设备服务」开启后出现)。
查到条码(协议唤起或通道扫码)时**默认切回「打包查询」页签**并自动查询。
- 扫码通道页:**每个区块的状态与按钮都在各自标题行上**。
- 「扫码通道」标题行:状态(`扫码服务运行中 · 通道 N 个(在线 M)` + 通道同步状态 + 待上传条数)+ `重连全部` / `静音`(选中行切换,已静音时叫「恢复蜂鸣」)/ `读取设备配置` / `重命名` / `删除通道`(后三个都要先选中一行);
通道列表有「类型」「状态」「静音」三列(类型 = `安卓扫描通道` / `扫码枪`,来自 UDP 发现应答的设备型号,
`AndroidStation` 才标成安卓扫描通道。**只有安卓扫描通道需要「扫码成功」通知**:摄像头识别到条码时
通知它播报语音;扫码枪通道没有语音能力,不发。**记录一直在写,与通道类型/在线状态无关**);
**没有「同步通道」按钮** —— 通道增删/启停都会自动上传并回查确认;
- 「发现到的设备」标题行:`开始扫描`(**开关**,打开后常驻发现:每 3s 探测、socket 一直收,直到手工停止)+ `添加为通道` + 状态(`正在扫描… 未添加 N 台` / `发现 N 台未添加的设备(另有 M 台已添加)`);
发现列表和「添加通道」弹窗都会标注 **安卓扫描通道**(型号 `AndroidStation`),添加时把型号一起落进 `channels.json`。
- **已经添加为通道的设备不会再出现在发现列表里**:显示集合与「发现到的全集」分开存(`_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/模拟扫码枪`。