liufumingren 51abccbaaf desktop:加登录页、托盘图标、防多开(单实例 + 参数转发)
- LoginWindow:服务器地址 / 账号 / 密码 / 记住账号 → POST /api/web/auth/login 拿 user JWT;
  本地已有令牌时先用 GET /api/web/me 验证,有效就跳过登录(窗口一闪而过),无效清掉令牌留下重登。
- TrayIconService(WinForms NotifyIcon,csproj 开 UseWindowsForms):
  关窗口 = 隐藏到托盘(本机服务继续跑),双击托盘恢复,右键菜单「打开主界面 / 服务地址 / 版本 / 退出」;
  第一次缩到托盘冒一次气泡提示。退出只走托盘「退出」(App 改 ShutdownMode=OnExplicitShutdown)。
- 防多开:SingleInstance(Local\ 命名互斥体 + 命名管道)。第二个实例不抢 17311 端口,
  把 yuncang://open?code=… 转给已运行实例(在托盘里也会被弹出来并按 code 查询)后自己退出;
  还在登录界面时先把 URL 存起来,登录完成后再查。
- 生命周期调整:本机 HTTP 服务与托盘在 App 里创建(登录前就可用),主窗口只管展示与操作;
  日志改成全局 AppLog(窗口没开时的日志也会在窗口打开后补上)。
- 新增 AppSettings / SessionStore:%LOCALAPPDATA%\YuncangTrace\settings.json、session.json
  (服务器地址默认 http://127.0.0.1:7300;换服务器不会复用旧令牌)。
- 新增 ApiClient(登录 / 校验令牌)、MainWindow「退出登录」(清令牌回登录页)。
- 程序/托盘图标:Assets/app.ico + tools/make-icon.ps1(品牌蓝 + 白色播放三角)。
- csproj 关闭 ImplicitUsings:WPF 与 WinForms 同时开启时隐式命名空间会让
  MessageBox / Application / Clipboard 等产生歧义。

⚠️ 本机没有 .NET SDK,无法编译验证;已做 XAML/XML 良构与括号平衡检查。
2026-10-17 10:23:50 +08:00
..

云仓视频溯源软件(本机服务 / WPF)

Windows 桌面端,用前端 /local 公共页和 Chrome 插件做对接:

  • 登录页:账号密码登录后端(POST /api/web/auth/login)拿 user JWT,令牌存本机; 下次启动先用 /api/web/me 验证,还有效就直接进主界面;
  • 在 127.0.0.1:17311 起一个本机 HTTP 服务,浏览器里的页面直接查询本机数据;
  • 注册 yuncang:// 启动协议,网页可以「叫醒」本软件(前提是已安装);
  • 托盘图标:关窗口只是缩到托盘(本机服务不能因关窗断掉),双击托盘恢复窗口, 右键菜单有「打开主界面 / 服务地址 / 退出」;
  • 防多开:全局互斥体 + 命名管道 —— 第二个实例不会抢 17311 端口,而是把 yuncang://open?code=xxx 转给已运行的实例(在托盘里也会被叫出来并直接查询),然后自己退出。
desktop/
├── YuncangTrace.LocalService.csproj   # net8.0-windows + UseWPF + UseWindowsForms(托盘)
├── app.manifest                       # 高 DPI / 兼容性声明
├── Assets/app.ico                     # 程序/托盘图标(tools/make-icon.ps1 生成)
├── App.xaml / App.xaml.cs             # 防多开 + 托盘 + 登录流程 + 本机服务生命周期
├── LoginWindow.xaml / .xaml.cs        # 服务器地址 / 账号 / 密码 / 记住账号 / 自动恢复登录
├── MainWindow.xaml / .xaml.cs         # 服务状态、地址、协议注册、测试查询、日志、退出登录
└── Services/
    ├── LocalHttpServer.cs             # HttpListener + CORS + PNA
    ├── OrderQueryService.cs           # ★ 按运单号查数据(接真实数据源的地方)
    ├── ApiClient.cs                   # 登录 / 校验令牌(用到的全部后端接口)
    ├── SessionStore.cs                # 登录态(%LOCALAPPDATA%\YuncangTrace\session.json)
    ├── AppSettings.cs                 # 服务器地址 / 记住账号(%LOCALAPPDATA%\YuncangTrace\settings.json)
    ├── ProtocolHelper.cs              # yuncang:// 注册/反注册、解析 code
    ├── SingleInstance.cs              # 互斥体 + 命名管道转发参数(防多开)
    ├── TrayIconService.cs             # 托盘图标与菜单
    ├── AppLog.cs                      # 全局日志缓冲(窗口没开时的日志也不丢)
    └── JsonUtil.cs                    # JSON 序列化(中文不转义)

登录 / 托盘 / 防多开的行为

场景 行为
首次启动 先起本机服务(17311)与托盘,再弹登录页 → 登录成功才出主窗口
已有令牌 登录窗一闪而过:/api/web/me 通过就直接进主窗口;失效则清掉令牌留在登录页
关窗口(X) 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示)
再次双击 exe / 点网页「启动本机软件」 不会开第二个:把 yuncang://open?code=… 通过命名管道转给已运行实例
托盘双击 / 右键「打开主界面」 恢复窗口
「退出登录」 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序)
托盘右键「退出」 真正退出(dispose 托盘与本机服务)

服务器地址默认 http://127.0.0.1:7300(后端 dev 默认端口),登录页上可以改,改完会存进 settings.json。 换服务器后不会复用旧令牌(会要求重新登录)。

环境要求

  • 编译:.NET 8 SDK(dotnet --list-sdks 能看到 8.x)
  • 只运行已发布的 exe:.NET 8 Desktop Runtime(不需要 SDK)

本仓库当前环境没有装 .NET,所以这份代码没在 CI 里编译过;第一次请自己跑一遍 dotnet build,有报错直接贴出来。

构建 / 运行 / 发布

cd desktop

dotnet build -c Release                 # 编译
dotnet run                              # 直接跑(调试)

# 发布给用户装(framework-dependent,体积小、需要装 Desktop Runtime)
dotnet publish -c Release -r win-x64 --self-contained false -o publish

# 或者自带运行时(体积大,但用户什么都不用装)
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o publish

本机接口(前端 /local 页用的就是这两个)

服务固定监听 http://localhost:17311(端口写在前端页面与插件里)。 代码里同时注册了 http://127.0.0.1:17311/ 前缀 —— HttpListener 只接受「注册过的 host」, 不注册的话用 127.0.0.1 访问会直接被回 400(前端改 VITE_LOCAL_SERVICE 时就会碰到)。

浏览器直接打开 http://localhost:17311/ 会看到一个说明页(列了下面两个接口,方便排查)。

方法 路径 说明
GET /api/health 探活:只要能返回 2xx 就认为软件已启动。返回 { ok, name, version, port, serverTime }
GET /api/query/{code} 按运单号查信息。成功时把字段平铺在顶层({ code, orderNo, ... }),失败返回 { ok:false, message } + 4xx

示例:

curl http://localhost:17311/api/health
curl http://localhost:17311/api/query/321408064481776

浏览器跨域(页面在站点域名上,请求的是 localhost)必须回这些响应头,代码里已经处理:

  • Access-Control-Allow-Origin(回显 Origin)、Allow-Methods、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);卸载时点「取消启动协议」或调用 ProtocolHelper.Unregister();
  • 手工注册/排查:
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 页面上点运单号旁的按钮 → 插件打开 http://<站点>/local?code=<运单号>;
  2. /local 页先探活 http://localhost:17311/api/health:
    • 通 → 直接调 /api/query/{code} 展示;
    • 不通 → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮; 点「已安装,启动本机软件」会走 yuncang://open?code=...,然后每 1s 轮询探活,起来后自动查询。
  3. 本软件被协议拉起时,会拿到 yuncang://open?code=xxx 参数:已经开着就转给原窗口(单实例), 没开就启动并直接查询这个码。

★ 接真实数据

只改一处:Services/OrderQueryService.cs 的 Query(string? code)。

public QueryResult Query(string? code)
{
    var value = (code ?? "").Trim();
    if (value.Length == 0) return QueryResult.BadRequest("缺少运单号");

    // 例:查本地 SQLite / 扫本地打包视频目录 / 调内部接口
    var row = _db.FindByCode(value);
    if (row is null) return QueryResult.NotFound($"没有找到 {value} 的记录");

    return QueryResult.Success(new Dictionary<string, object?>
    {
        ["code"] = row.Code,
        ["orderNo"] = row.OrderNo,
        ["printStatus"] = row.PrintStatus,
        ["videoPath"] = row.VideoPath,
    });
}

返回对象平铺即可,前端页面会把顶层字段渲染成「项目 / 值」两列(字段随便加)。

常见问题

现象 处理
启动报「没有绑定端口的权限」/ Access is denied (5) 管理员执行 netsh http add urlacl url=http://localhost:17311/ user=%USERNAME%,或改成以当前用户身份运行
报端口被占用(错误 32) 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程
网页提示服务不可用,但软件在跑 先用浏览器直接打开 http://localhost:17311/api/health:打不开→防火墙/端口;打得开→多半是 CORS 头没回
点网页「启动本机软件」没反应 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击)
改了协议名 注册表重注册 + 前端 VITE_APP_PROTOCOL 同步 + 插件目标地址同步