packServer/desktop/README.md
liufumingren 228723e0c3 设备端扫码上报 + 桌面端/Android 正式包发布脚手架
AndroidStation(原中控改造为纯设备端)
- 只做三件事:UDP 48899 被桌面端发现、TCP 8087 推送 USB 扫码结果、离线语音播报
- 扫码不再经过 UI:去掉逐键重绘,50ms 自动提交,同一码重复扫码也一律上报
- 离线语音种子(数字/字母/“开始打包”/欢迎语)随包安装,MediaPlayer 播放,启动把音量拉满
- 启动播报「欢迎使用溯源系统,初始化已经完成,扫码即可开始打包」
- 移除 Device Owner / 设备管理员 / lock task / 网络与 IP 设置等非普通应用能力(仅保留开机自启)
- 正式签名 keystore + release 签名配置,versionName/versionCode 可由打包脚本覆盖

发布脚手架
- backend/android_client:Android 正式包构建(build.ps1 + package.config.json)
- backend/scripts/deploy/publish-android.cjs + npm run android:build / android:publish
- 桌面端安装包改为 download/desktop,Android 为 download/android_client;
  version.json 仍走 /download/version.json(老客户端写死),新增 /download/android_client/version.json
- 谷歌插件随桌面端 MSI 安装到 <安装目录>\extension,工具菜单新增「复制谷歌插件地址」
- git-safety-check 增加仓库级禁区(keystore.properties / *.jks / local.properties)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-21 05:53:27 +08:00

738 lines
54 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://` 启动协议,网页可以「叫醒」本软件(前提是已安装);
- **托盘图标**:关窗口只是缩到托盘(本机服务不能因关窗断掉),双击托盘恢复窗口,
右键菜单有「打开主界面 / 重启软件 / 退出」;
- **界面不展示服务地址**:登录页和主界面都不显示后端地址 / 本机端口,它们属于内部实现细节;
后端地址由构建注入(`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 # HttpListener(17300):查询 / 唤起登录 / 下载录像
├── 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`,有新版本会把更新窗盖在登录页上(否则老版本用户永远卡在登录页收不到更新) |
| 已有令牌 | 登录窗一闪而过:`/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/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 协议读不到时区,所以这一项由现场保证(时区改好后再同步)。
- **不再依赖 ISAPI/Web 端口**:以前用 ISAPI 补通道名、探测云台、读写时区,
但这些接口在部分摄像头/NVR 上根本不存在(实测有设备 `/ISAPI/*` 全 404),已全部移除:
通道名留空(前端拼「NVR名-通道号」)、不再标记「是否支持云台」(预览界面统一显示方向盘)。
`/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)+ 自动更新
`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\**`、`..\extension\**` 作为独立文件输出**(不走单文件自解压);
缺 `publish\native\ffmpeg\ffmpeg.exe` 会直接报错中止;
2. `wix build` 生成 MSI(`Product.wxs` 用 `<Files Include="..\publish\native\**" />`、`<Files Include="..\publish\extension\**" />`
递归收集,保持目录结构;`extension\test` / `extension\tools` 这类调试文件不打进包);
3. 算 MD5 → 写 `version.json`;
4. 复制到后端:MSI → `backend/app/public/download/desktop/`,`version.json` → `backend/app/public/version/desktop/`;
5. 本地 `out/` 与后端目录**各只保留最近 5 个**安装包(`keepVersions` 可配)。
> 安装包与版本信息都归到后端 `desktop` 子目录:下载地址 `<域名>/download/desktop/YuncangTraceSetup-x.y.z.msi`,
> 版本信息仍是 `<域名>/download/version.json`(老客户端写死了这个地址,不能改)。
### 谷歌浏览器插件随包安装
仓库根目录的 `extension/` 会一起打进 MSI,安装后固定在 **`<安装目录>\extension`**
(perUser 安装即 `%LOCALAPPDATA%\Programs\YuncangTrace\extension`):
- 菜单「工具 → 复制谷歌插件地址」直接把该目录的 **Windows 路径**(如 `C:\Users\xxx\AppData\Local\Programs\YuncangTrace\extension`)复制到剪贴板;
- 用户打开 `chrome://extensions` → 打开「开发者模式」→「加载已解压的扩展程序」→ 粘贴路径即可;
- 卸载时该目录随 MSI 组件一起删除;
### 自动更新怎么工作
```
软件启动(登录后)→ 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/desktop/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/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 自动删除 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)
```
> 每次测更新都要打一个**比当前安装版本高**的包(脚本会拒绝在"已是最新"时白跑)。
## 本机接口
本机软件开**两个**端口,职责分开:
| 端口 | 协议 | 用途 |
| --- | --- | --- |
| **17300** | HTTP | 运单查询 / 唤起登录 / 按运单下载录像(低频、无状态) |
| **17301** | WebSocket | 拉通道 / 实时预览(推 JPEG 帧)/ 云台 / 满帧率窗口(预览相关全在这里) |
### HTTP 17300(前端 `/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` 时自动调它 |
| 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/`。
### 为什么没有单独的「探活 / 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
> 时间服务没开、慢了几秒)时,短回放窗口会把面单截到窗口外 —— 这一步就是防这个。
### 多路对齐(预览 / 合并下载)
几路回放是**各自独立连录像机**的,天然会有两处时间差,都要单独处理:
1. **开播时间差(预览)**:各路 RTSP 建链快慢不同,先出帧的那路会一直“跑在前面”。
`PlaybackPreviewWindow` 的做法是**先一起等、再按帧一起放**:
- ffmpeg **每出一帧回调一次**(`HikFfmpegService.Subscribe`)按顺序进各自队列。
⚠️ 不能定时去取“最新一帧”:ffmpeg 定位到关键帧后会把「关键帧→请求时间」整段一次吐出来,
只留最新帧会把这串前面全丢掉,那一路的“第一帧”其实是 1~2 秒后的画面(现象:小窗一出现就超前);
- 每一路都出过第一帧(最多等 12 秒,超时当这路没录像)后才开始播,每 40ms 从**每路队列各取一帧**,
先上线的那路放的就是等同步时攒下的积压 → 几路自然停在同一内容位置;
- 队列超过 220 帧(≈9 秒)就丢到 50 帧(≈2 秒),设备推得比实时快也不会越播越晚。
日志里出现 `[playback] 多路回放开始同步播放(各路基线帧数:…)` 就说明生效了。
**播到请求窗口就一起停**:录像机不会按 `endtime` 主动断流,各路停的时机还不一样
(实测一路到点停止、另一路还在往后推,看着就是一个窗先冻住),
所以到 `EndTime - StartTime` 时统一收尾、释放设备会话,标题变成「回放结束」。
2. **录制起点差(下载 / 合并 / 预览)**:回放是从“请求时间所在**关键帧**”开始推的,
各通道 GOP 位置不同 → 同一时间点开始拉的两段录像,第一帧能差好几秒;
不处理就会两格画面错开。
**用 `NET_DVR_GetPlayBackOsdTime` 读第一帧的真实内容时间**(8000 协议,实测可用):
- 下载:`PullPlaybackToFile` 在第一包数据到达时读一次,`偏移 = 首帧 OSD − 请求时间`,
合并时提前的路用 `trim` 切头、晚开始的路用 `setpts` 后移
(日志 `[playback] 通道N 首帧 OSD=hh:mm:ss,比请求时间早/晚 X 秒`);
- 预览: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` 落记录 + 上报,跟查询是两条独立的路。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 启动报「没有绑定端口的权限」/ `Access is denied (5)` | 管理员执行 `netsh http add urlacl url=http://localhost:17300/ user=%USERNAME%`,或改成以当前用户身份运行 |
| 报端口被占用(错误 32) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 `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)
### 登录窗
- **微信扫码登录**:点「微信扫码登录」→ `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`(带 `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`,失败不标记、指数退避重发(服务端按 设备+通道+条码+秒 精确去重;**同一运单 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`。
### 界面
- 主窗口改成页签:**打包查询** / **扫码通道**(后者仅在「设备服务」开启后出现)。
查到条码(协议唤起或通道扫码)时**默认切回「打包查询」页签**并自动查询。
- 扫码通道页:**每个区块的状态与按钮都在各自标题行上**。
- 「扫码通道」标题行:状态(`扫码服务运行中 · 通道 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/模拟扫码枪`。