liufumingren c12ea3b197 移除探活接口:状态合进 /api/query;插件支持直接协议唤起 + 失败兜底
一、本机服务(桌面端)
- 删除 GET /api/health(说明页同步)。
- GET /api/query/{code} 合并状态,一次请求就能决定「展示结果」还是「提示唤起」:
  200 { ok, state:"ok", code, loggedIn, user, env, server, data }
  401 { ok:false, state:"need-login", ... } / 400 "bad-request" / 404 "not-found" / 500 "error"
  不论成败都带 loggedIn/user/env/server;只有网络层失败才代表「软件没启动」。
  原因:探活通过 ≠ 查询时软件还在(用户可能中途退出),两次请求之间状态会错位。

二、前端 /local
- api/local.ts:删 localHealth / checkLocalHealth / waitForHealth / waitForLoggedIn;
  新增 queryLocal()(非 2xx 但带 state 的 JSON 也正常返回)与 waitForQuery()(轮询同一接口)。
  request() 改为先读 body,这样 401 能拿到 state 而不只是状态码。
- LocalServiceView.vue:状态机改为单接口驱动
  连不上 → offline(下载/启动提示);need-login → 自动 activate-login + 轮询 query 等登录;
  ok → 展示;其它 → 展示错误。
  「重新查询」也走同一逻辑:用户中途退掉软件时点重查会**直接落到「服务暂不可用 + 可唤起」提示**,
  不再是一个莫名其妙的失败。
- 空 code 也发一次请求(服务端回 400 bad-request + 登录状态),所以没有 code 时同样能驱动页面状态。

三、Chrome 插件(extension/,工作区改动,暂未提交 —— 与另一会话的 WIP 混在同几个文件里)
- 默认目标模板改为 yuncang://open?code={code}:点击「查看打包视频」**直接唤起本机软件并带参**,
  不再先开网页;旧的 http 默认模板在配置升级(v2→v3)时自动换成协议模板,用户自定义的不动。
- content.js:按协议分流(http(s) → background 开标签页;其它 → 本页用户手势内用隐藏 iframe 触发)。
- 唤不起的兜底(浏览器不会告诉网页协议是否成功,必须超时猜):
  4 秒内页面没失焦 → 右下角卡片「没打开本机软件?」+「在网页中查看」(fallbackUrl)+「下载安装」
  (downloadUrl)+ 关闭。
- 新增配置:fallbackUrl(默认 http://localhost:7301/local?code={code})、downloadUrl(留空不显示下载按钮);
  options 页与使用说明同步。

四、验证
- /api/health → 404;/api/query/ABC123 → 200 state:ok + data;
  /api/query/ → 400 state:bad-request + loggedIn/user/env/server。
- 浏览器 /local?code=ABC123:正常展示;**杀掉软件后点「重新查询」→ 立即显示
  「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮 + 已安装启动按钮**。
- 插件脚本 node --check 全通过;PSTRules.buildUrl 输出 yuncang://open?code=YT1234567890,
  v2 旧配置升级后模板自动变为协议、fallbackUrl/downloadUrl 就位。
- 前端 vue-tsc + vite build 通过;桌面端 0 警告 0 错误。

五、文档
- desktop/README.md:接口表改为两个接口 + 状态码/state 对照表 + 响应示例;
  「和前端/插件怎么配合」改为插件直接唤起;新增「插件直接唤起与唤不起时的提示」一节。
2026-10-17 11:10:34 +08:00
..

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

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

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

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

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

环境配置(开发 / 生产)

和前端 VITE_BACKEND 一个思路:由构建决定,不靠用户手填。

构建 env 默认后端
dotnet build(Debug) Development http://127.0.0.1:7300(= 前端 dev 代理的后端)
dotnet build -c Release Production https://packs.example.com(占位,打包时必须覆盖)

打包正式版时指定真实域名:

dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com -o publish

优先级(从高到低):

  1. 启动参数 --server=http://192.168.1.10:7300(临时,不落盘);
  2. 环境变量 YUNCANG_SERVER;
  3. -p:ServerBaseUrl= 注入的构建默认值;
  4. 用户在登录页手改并保存的地址(settings.json)。

几个细节:

  • 地址等于内置默认值时,settings.json 里存空串 —— 所以换 Debug/Release 构建能自动跟随, 不会被上一次构建的默认值钉死;只有用户手改过的地址才会持久化。
  • 换地址后不会复用旧令牌(session.json 里的 ServerBaseUrl 对不上就要求重新登录)。
  • GET /api/health 会回 env 和 server,排查环境是否装错时先看这两个字段。

环境要求

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

本机 SDK 装在用户目录(免管理员):%LOCALAPPDATA%\Microsoft\dotnet, 已加入用户 PATH 和 DOTNET_ROOT。新开的终端才能直接用 dotnet; 老终端里临时用:$env:DOTNET_ROOT="$env:LOCALAPPDATA\Microsoft\dotnet"; $env:Path="$env:DOTNET_ROOT;$env:Path"。 直接双击 bin\...\*.exe 也需要 DOTNET_ROOT 已生效(否则报 “You must install .NET”)。 官方安装包:winget install --id Microsoft.DotNet.SDK.8 -e(要 UAC)。

构建 / 运行 / 发布

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 到标准位置, 或者每次用发布产物验证唤起。

本机接口(前端 /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(当前后端地址):

// 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": "本机软件未登录,请先在软件里登录" }

示例:

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」或干脆没反应)。 界面上仍可手动「取消启动协议」;
  • 手工注册/排查:
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=<运单号> 唤起本机软件并定位到该单号 (浏览器会先问一次「要打开吗」);也可以把插件的目标模板配成 http://<站点>/local?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. 4 秒内页面没失焦(软件窗口没抢焦点)→ 认为没起来,右下角弹出兜底卡片:
    • 在网页中查看 → 打开插件设置里的「唤不起时的兜底页」(默认 http://localhost:7301/local?code={code}, 该页面里有完整的下载安装引导);
    • 下载安装 → 打开插件设置里的「软件下载地址」(留空则不显示这个按钮)。
  3. 插件设置页有三个相关配置:目标地址模板(默认 yuncang://open?code={code})、 唤不起时的兜底页、软件下载地址。老配置里如果是旧的 http 默认模板,升级时会自动换成协议模板。

兜底只能靠「失焦」猜,不是 100% 准确(软件在后台启动、没抢焦点时会误报一次)。 想更稳就把目标模板配成 /local?code={code}:网页里有真实的查询结果,连不上就是真的没起来。

★ 接真实数据

只改一处: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: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 同步 + 插件目标地址同步