一、工具链 - 本机没有 .NET,微软域名又被网络阻断,改用 curl 从 builds.dotnet.microsoft.com 拉 dotnet-sdk-8.0.426-win-x64.zip,解压到 %LOCALAPPDATA%\Microsoft\dotnet(免管理员), 并写入用户 PATH / DOTNET_ROOT / DOTNET_CLI_TELEMETRY_OPTOUT。 二、首次编译暴露的两个真实缺陷(都已修复) - ProtocolHelper.cs 缺 using System.Collections.Generic(ImplicitUsings=disable 后 IEnumerable<string> 找不到)。 - App.xaml 少了 BgBrush,LoginWindow/MainWindow 用 StaticResource 引用它 → 编译期查不出, 运行期一弹登录窗就 XamlParseException 直接退出(事件日志里能看到)。 已补 BgBrush=#F5F7FA 并注明「缺一个就会运行时炸」。 - 顺带把 WFAC010(WinForms 建议 DPI 改走 ApplicationHighDpiMode)压掉并写明原因: 本程序宿主是 WPF,走不到 WinForms 的 ApplicationConfiguration,DPI 只能由 manifest 决定。 三、服务地址 = 构建期环境(对齐前端 VITE_BACKEND 的思路) - csproj:Debug → AppEnvironment=Development、ServerBaseUrl=http://127.0.0.1:7300; Release → Production、占位 https://packs.example.com;用 -p:ServerBaseUrl= 覆盖; 两者通过 AssemblyMetadataAttribute 写进程序集,exe 自带「我是哪个环境」。 - 新增 Services/BuildInfo.cs 读元数据(带兜底,绝不抛)。 - AppSettings:默认值改为 BuildInfo.DefaultServer;等于内置默认值时不落盘(换构建能自动跟随), 老版本已把默认值写进 settings.json 的也识别为"没改过";新增 UseServer() 支持运行时临时覆盖。 - App:解析 --server=xxx / -s xxx,其次 YUNCANG_SERVER 环境变量,写在构建默认值之前。 - 登录窗:「服务器地址」改叫「服务地址」,右侧显示"开发环境/生产环境"(只展示,由构建决定), 输入框 ToolTip 说明留空即用当前环境默认地址。 - /api/health 增加 env(Development/Production)与 server(当前后端地址),排障一眼看出装错没有。 四、验证 - Debug / Release / Release+域名覆盖 三种构建均 0 警告 0 错误; - Debug:health 返回 env=Development、server=http://127.0.0.1:7300; - Release:env=Production、server=https://packs.example.com; Release 加 -p:ServerBaseUrl=https://trace.yuncang.cn 后 server 随之变化; - 带 --server=http://10.0.0.9:7300 启动:server 被覆盖,settings.json 未被污染; - health / 未登录 query(401) / activate-login(200,登录窗弹出) / OPTIONS 预检(204+CORS) 全部正常。 - 注意:改 -p: 属性必须 -t:Rebuild,否则 MSBuild 不会重新生成 AssemblyInfo。 五、README - 新增「环境配置(开发 / 生产)」:构建矩阵、发布时覆盖域名、优先级、默认值不落盘的原因、 settings.json/session.json 的行为;补了本机 SDK 装在用户目录、需要 DOTNET_ROOT 的说明; 行为表新增「网页请求唤起登录」一行;health 返回字段更新。
209 lines
12 KiB
Markdown
209 lines
12 KiB
Markdown
# 云仓视频溯源软件(本机服务 / 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`(占位,打包时必须覆盖) |
|
||
|
||
打包正式版时指定真实域名:
|
||
|
||
```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/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)。
|
||
|
||
## 构建 / 运行 / 发布
|
||
|
||
```powershell
|
||
cd desktop
|
||
|
||
dotnet build # 编译(Debug = 开发环境,连本地 7300)
|
||
dotnet build -c Release # 编译(Release = 生产环境,默认地址见上一节)
|
||
dotnet run # 直接跑(调试)
|
||
|
||
# 发布给用户装(framework-dependent,体积小、需要装 Desktop Runtime)
|
||
dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com --self-contained false -o publish
|
||
|
||
# 或者自带运行时(体积大,但用户什么都不用装)
|
||
dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com --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, env, server, loggedIn, user, serverTime }`(`env` = `Development`/`Production`) |
|
||
| 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` 同步 + 插件目标地址同步 |
|