packServer/desktop/README.md
liufumingren 700394b56f 本机服务端口改 17300,/api/health 带登录状态,网页可唤起软件登录
- 端口 17311 → **17300**(桌面端常量、localhost/127.0.0.1 双前缀、前端 LOCAL_BASE、
  插件默认目标与说明、两个 README 全部同步)。
- `/api/health` 返回值加上 `loggedIn` / `user`(由 App 提供:IsLoggedInProvider、UserNameProvider),
  前端只认 `ok`(探活),再用 `loggedIn` 决定要不要唤起登录。
- 新增 `POST /api/activate-login`:叫本机软件把登录窗(已登录则主界面)带到前台。
  用 POST 而不是 GET,避免被浏览器/聊天工具的链接预取误触发;CORS Allow-Methods 加了 POST。
- `/api/query/{code}` 未登录时返回 401(前端会转去唤起登录)。
- 桌面端:App 记住登录窗引用,收到 LoginRequested 时切回 UI 线程激活它(托盘里也能叫出来)。
- 前端 `/local?code=`:
  - 路由加 alias `/local/`;
  - 新增 need-login 状态:探活到「软件在跑但没登录」→ 自动 POST activate-login →
    每秒探活等登录(30s 上限)→ 登录完成后自动查询;期间有「再叫一次登录窗口」按钮与托盘提示;
  - api/local.ts 增加 localHealth()(online/loggedIn/user)、requestLocalLogin()、waitForLoggedIn();
    waitForHealth() 改为返回状态而非 bool;老版本软件没有 loggedIn 字段时按已登录处理(向后兼容)。
- 实测(7301 + 模拟的 17300):打开 /local/?code=… → 「本机软件未登录 / 正在等待登录…」→
  mock 翻成已登录后自动切到查询结果(5 行);杀掉 mock 后显示「服务暂不可用」且探测地址为 17300。
2026-10-17 10:28:01 +08:00

178 lines
9.9 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://` 启动协议,网页可以「叫醒」本软件(前提是已安装);
- **托盘图标**:关窗口只是缩到托盘(本机服务不能因关窗断掉),双击托盘恢复窗口,
右键菜单有「打开主界面 / 服务地址 / 退出」;
- **防多开**:全局互斥体 + 命名管道 —— 第二个实例不会抢 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=…` 通过命名管道转给已运行实例 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 「退出登录」 | 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序) |
| 托盘右键「退出」 | 真正退出(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:17300`(端口写在前端页面与插件里)。
代码里**同时注册了 `http://127.0.0.1:17300/`** 前缀 —— `HttpListener` 只接受「注册过的 host」,
不注册的话用 127.0.0.1 访问会直接被回 400(前端改 `VITE_LOCAL_SERVICE` 时就会碰到)。
浏览器直接打开 <http://localhost:17300/> 会看到一个说明页(列了接口,方便排查)。
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/health` | 验活 + 登录状态:**2xx 即认为软件已启动**。返回 `{ ok, name, version, port, loggedIn, user, serverTime }` |
| GET | `/api/query/{code}` | 按运单号查信息(**需已登录**,否则 401 `{ ok:false, loggedIn:false, message }`)。成功时字段**平铺**在顶层(`{ code, orderNo, ... }`) |
| POST | `/api/activate-login` | 把本机软件的**登录窗叫到前台**(已登录时把主界面叫到前台)。网页发现 `loggedIn:false` 时自动调它 |
示例:
```powershell
curl http://localhost:17300/api/health
curl http://localhost:17300/api/query/321408064481776
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);卸载时点「取消启动协议」或调用 `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=<运单号>`(`/local/` 也认);
2. `/local` 页先探活 `http://localhost:17300/api/health`:
- **连不上** → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
点「已安装,启动本机软件」会走 `yuncang://open?code=...`,然后每 1s 轮询探活;
- **连上了但 `loggedIn:false`**(软件没登录)→ 页面自动 `POST /api/activate-login`
把本机登录窗叫到前台,然后每秒探活等登录完成(最长 30s),登录好**自动继续查询**;
- **已登录** → 直接调 `/api/query/{code}` 展示(页面顶部会显示「本机软件已登录:xxx」)。
3. 本软件被协议拉起时,会拿到 `yuncang://open?code=xxx` 参数:已经开着就转给原窗口(单实例),
没开就启动 → 先登录 → 登录完自动查询这个码(登录前收到的 code 会先存着)。
## ★ 接真实数据
只改一处:`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:17300/ user=%USERNAME%`,或改成以当前用户身份运行 |
| 报端口被占用(错误 32) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 `http://localhost:17300/api/health`:打不开→防火墙/端口;打得开→多半是 CORS 头没回 |
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
| 改了协议名 | 注册表重注册 + 前端 `VITE_APP_PROTOCOL` 同步 + 插件目标地址同步 |