packServer/desktop/README.md
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

172 lines
9.1 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: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`,有报错直接贴出来。
## 构建 / 运行 / 发布
```powershell
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 |
示例:
```powershell
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()`;
- 手工注册/排查:
```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 页面上点运单号旁的按钮 → 插件打开 `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)`。
```csharp
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` 同步 + 插件目标地址同步 |