移除探活接口:状态合进 /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 对照表 + 响应示例;
「和前端/插件怎么配合」改为插件直接唤起;新增「插件直接唤起与唤不起时的提示」一节。
This commit is contained in:
parent
30ad162c69
commit
c12ea3b197
@ -113,7 +113,7 @@ dotnet publish -c Release -r win-x64 --self-contained true `
|
||||
开发阶段想让 `bin\Debug` 的 exe 也能直接双击,两个办法:装官方 SDK/Desktop Runtime 到标准位置,
|
||||
或者每次用发布产物验证唤起。
|
||||
|
||||
## 本机接口(前端 `/local` 页用的就是这三个)
|
||||
## 本机接口(前端 `/local` 页用的就是这两个)
|
||||
|
||||
服务固定监听 `http://localhost:17300`(端口写在前端页面与插件里)。
|
||||
代码里**同时注册了 `http://127.0.0.1:17300/`** 前缀 —— `HttpListener` 只接受「注册过的 host」,
|
||||
@ -123,15 +123,43 @@ dotnet publish -c Release -r win-x64 --self-contained true `
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 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` 时自动调它 |
|
||||
| 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`(当前后端地址):
|
||||
|
||||
```jsonc
|
||||
// 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": "本机软件未登录,请先在软件里登录" }
|
||||
```
|
||||
|
||||
示例:
|
||||
|
||||
```powershell
|
||||
curl http://localhost:17300/api/health
|
||||
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
|
||||
```
|
||||
|
||||
@ -176,17 +204,33 @@ reg query "HKCU\Software\Classes\yuncang\shell\open\command"
|
||||
|
||||
## 和前端 / 插件怎么配合
|
||||
|
||||
1. WMS 页面上点运单号旁的按钮 → 插件打开 `http://<站点>/local?code=<运单号>`(`/local/` 也认);
|
||||
2. `/local` 页先探活 `http://localhost:17300/api/health`:
|
||||
1. WMS 页面上点运单号旁的按钮 → 插件**直接用 `yuncang://open?code=<运单号>` 唤起本机软件**并定位到该单号
|
||||
(浏览器会先问一次「要打开吗」);也可以把插件的目标模板配成 `http://<站点>/local?code=<运单号>` 先开网页;
|
||||
2. `/local` 页只发一个请求 `GET /api/query/{code}`:
|
||||
- **连不上** → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
|
||||
点「已安装,启动本机软件」会走 `yuncang://open?code=...`,然后每 1s 轮询探活;
|
||||
- **连上了但 `loggedIn:false`**(软件没登录)→ 页面自动 `POST /api/activate-login`
|
||||
把本机登录窗叫到前台,然后每秒探活等登录完成(最长 30s),登录好**自动继续查询**;
|
||||
- **已登录** → 直接调 `/api/query/{code}` 展示(页面顶部会显示「本机软件已登录:xxx」)。
|
||||
点「已安装,启动本机软件」会走 `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}`:网页里有真实的查询结果,连不上就是真的没起来。
|
||||
|
||||
## ★ 接真实数据
|
||||
|
||||
|
||||
@ -10,8 +10,9 @@ namespace YuncangTrace.LocalService.Services;
|
||||
/// 本机 HTTP 服务(只监听 127.0.0.1)
|
||||
///
|
||||
/// 给浏览器里的页面调用(我们的 `/local` 公共页、以及任何想取数据的前端):
|
||||
/// - <c>GET /api/health</c> 探活:返回 2xx 即认为「软件已启动」
|
||||
/// - <c>GET /api/query/{code}</c> 按运单号查信息,成功时**平铺**返回字段
|
||||
/// - <c>GET /api/query/{code}</c> 查信息;**同时把服务/登录状态一起返回**(没登录回 401 `state:need-login`),
|
||||
/// 页面一次请求就能决定「展示结果」还是「提示唤起」,不再需要单独的探活接口;
|
||||
/// - <c>POST /api/activate-login</c> 把登录窗/主界面叫到前台。
|
||||
///
|
||||
/// ⚠️ 两个坑(都在这里处理好了):
|
||||
/// 1. **CORS**:页面同源是站点域名,请求本机属于跨域,必须回
|
||||
@ -40,13 +41,13 @@ public sealed class LocalHttpServer : IDisposable
|
||||
/// <summary>网页请求唤起登录(`POST /api/activate-login`);服务线程触发,订阅方自己切 UI 线程</summary>
|
||||
public event Action? LoginRequested;
|
||||
|
||||
/// <summary>当前是否已登录(由 App 提供,供 `/api/health` 用)</summary>
|
||||
/// <summary>当前是否已登录(由 App 提供,随 `/api/query` 一起返回)</summary>
|
||||
public Func<bool>? IsLoggedInProvider { get; set; }
|
||||
|
||||
/// <summary>当前登录用户显示名(由 App 提供,供 `/api/health` 用)</summary>
|
||||
/// <summary>当前登录用户显示名(由 App 提供,随 `/api/query` 一起返回)</summary>
|
||||
public Func<string?>? UserNameProvider { get; set; }
|
||||
|
||||
/// <summary>当前后端地址(由 App 提供,供 `/api/health` 排障用)</summary>
|
||||
/// <summary>当前后端地址(由 App 提供,随 `/api/query` 一起返回,排障用)</summary>
|
||||
public Func<string?>? ServerBaseUrlProvider { get; set; }
|
||||
|
||||
public LocalHttpServer(OrderQueryService queryService)
|
||||
@ -166,46 +167,69 @@ public sealed class LocalHttpServer : IDisposable
|
||||
return;
|
||||
}
|
||||
|
||||
if (path.Equals("/api/health", StringComparison.OrdinalIgnoreCase)
|
||||
|| path.Equals("/api/health/", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
// ok = 服务在跑(前端只认这个);loggedIn = 本机软件是否已登录(没登录就唤起登录)
|
||||
await WriteJsonAsync(response, 200, new
|
||||
{
|
||||
ok = true,
|
||||
name = "云仓视频溯源打印服务",
|
||||
version = typeof(LocalHttpServer).Assembly.GetName().Version?.ToString() ?? "1.0.0",
|
||||
port = Port,
|
||||
env = BuildInfo.Environment,
|
||||
server = ServerBaseUrlProvider?.Invoke(),
|
||||
loggedIn = IsLoggedIn,
|
||||
user = UserNameProvider?.Invoke(),
|
||||
serverTime = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"),
|
||||
}).ConfigureAwait(false);
|
||||
return;
|
||||
}
|
||||
|
||||
const string queryPrefix = "/api/query/";
|
||||
if (path.StartsWith(queryPrefix, StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
// 未登录不查(网页会先把登录窗叫出来)
|
||||
if (!IsLoggedIn)
|
||||
// 一个接口把「软件在跑吗 / 登录了吗 / 查到什么」全返回 ——
|
||||
// 网页只发一次请求就能决定展示结果还是提示“唤起”,不会出现“探活通过、真正查询时软件已退出”的错位。
|
||||
var code = Uri.UnescapeDataString(path[queryPrefix.Length..]).Trim();
|
||||
var loggedIn = IsLoggedIn;
|
||||
var user = UserNameProvider?.Invoke();
|
||||
var env = BuildInfo.Environment;
|
||||
var server = ServerBaseUrlProvider?.Invoke();
|
||||
|
||||
if (!loggedIn)
|
||||
{
|
||||
await WriteJsonAsync(response, 401, new { ok = false, message = "本机软件未登录,请先在软件里登录", loggedIn = false }).ConfigureAwait(false);
|
||||
await WriteJsonAsync(response, 401, new
|
||||
{
|
||||
ok = false,
|
||||
state = "need-login",
|
||||
code,
|
||||
loggedIn = false,
|
||||
user,
|
||||
env,
|
||||
server,
|
||||
message = "本机软件未登录,请先在软件里登录",
|
||||
}).ConfigureAwait(false);
|
||||
return;
|
||||
}
|
||||
|
||||
var code = Uri.UnescapeDataString(path[queryPrefix.Length..]).Trim();
|
||||
var result = _queryService.Query(code);
|
||||
|
||||
if (result.Ok)
|
||||
{
|
||||
await WriteJsonAsync(response, 200, result.Data).ConfigureAwait(false);
|
||||
await WriteJsonAsync(response, 200, new
|
||||
{
|
||||
ok = true,
|
||||
state = "ok",
|
||||
code,
|
||||
loggedIn,
|
||||
user,
|
||||
env,
|
||||
server,
|
||||
data = result.Data,
|
||||
}).ConfigureAwait(false);
|
||||
return;
|
||||
}
|
||||
else
|
||||
|
||||
var state = result.StatusCode switch
|
||||
{
|
||||
await WriteJsonAsync(response, result.StatusCode, new { ok = false, message = result.Message }).ConfigureAwait(false);
|
||||
}
|
||||
400 => "bad-request",
|
||||
404 => "not-found",
|
||||
_ => "error",
|
||||
};
|
||||
|
||||
await WriteJsonAsync(response, result.StatusCode, new
|
||||
{
|
||||
ok = false,
|
||||
state,
|
||||
code,
|
||||
loggedIn,
|
||||
user,
|
||||
env,
|
||||
server,
|
||||
message = result.Message,
|
||||
}).ConfigureAwait(false);
|
||||
return;
|
||||
}
|
||||
|
||||
@ -220,8 +244,7 @@ public sealed class LocalHttpServer : IDisposable
|
||||
<h2>云仓视频溯源软件(本机服务)</h2>
|
||||
<p>服务运行中,只监听本机(127.0.0.1:17300)。</p>
|
||||
<ul>
|
||||
<li><a href="/api/health">/api/health</a> 探活(含登录状态)</li>
|
||||
<li><code>/api/query/{运单号}</code> 按运单号查信息(需已登录)</li>
|
||||
<li><code>/api/query/{运单号}</code> 查询(同时返回服务/登录状态;没登录回 401)</li>
|
||||
<li><code>POST /api/activate-login</code> 把登录窗叫到前台</li>
|
||||
</ul>
|
||||
""";
|
||||
|
||||
@ -1,12 +1,16 @@
|
||||
/**
|
||||
* 本机软件(打印服务)客户端 —— 由 Chrome 插件打开的公共页用它查运单信息
|
||||
*
|
||||
* 本机服务默认监听 `http://localhost:17300`:
|
||||
* - `GET /api/health` 探活 + 登录状态(`{ ok, loggedIn, user }`)
|
||||
* - `GET /api/query/{code}` 按运单号查信息(需已登录)
|
||||
* - `POST /api/activate-login` 把本机软件的登录窗叫到前台
|
||||
* 本机服务默认监听 `http://localhost:17300`,只有两个接口:
|
||||
* - `GET /api/query/{code}` 查信息,**同时返回服务/登录状态**(没登录回 401 `state:need-login`)
|
||||
* - `POST /api/activate-login` 把本机软件的登录窗/主界面叫到前台
|
||||
*
|
||||
* ⚠️ 这是**跨域**请求(页面同源是我们的站点,目标是 localhost:17300): * 本机软件必须允许 CORS(`Access-Control-Allow-Origin` 放行站点来源),否则浏览器会拦掉,
|
||||
* 为什么不再单独做探活接口:探活通过 ≠ 真正查询时软件还在(用户可能中途退了),
|
||||
* 两次请求之间的状态可能已经变了。合并成一个接口后,页面只发一次请求就能决定
|
||||
* 「展示结果」还是「提示可以唤起」。
|
||||
*
|
||||
* ⚠️ 这是**跨域**请求(页面同源是我们的站点,目标是 localhost:17300):
|
||||
* 本机软件必须允许 CORS(`Access-Control-Allow-Origin` 放行站点来源),否则浏览器会拦掉,
|
||||
* 表现和「软件没启动」一样 —— 页面统一提示「服务暂不可用」。
|
||||
*
|
||||
* 地址可用 `VITE_LOCAL_SERVICE` 覆盖(换端口 / 换 127.0.0.1 时用)。
|
||||
@ -28,7 +32,7 @@ export class LocalServiceError extends Error {
|
||||
}
|
||||
}
|
||||
|
||||
/** 带超时的请求;返回解析后的 JSON(不是 JSON 就给纯文本) */
|
||||
/** 带超时的请求;**非 2xx 且返回了 JSON(带 state)时也原样返回**,交给调用方判状态 */
|
||||
async function request<T>(path: string, timeoutMs: number, method: 'GET' | 'POST' = 'GET'): Promise<T> {
|
||||
const controller = new AbortController();
|
||||
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
||||
@ -38,59 +42,66 @@ async function request<T>(path: string, timeoutMs: number, method: 'GET' | 'POST
|
||||
headers: { Accept: 'application/json' },
|
||||
signal: controller.signal,
|
||||
});
|
||||
if (!res.ok) throw new LocalServiceError(`本地服务返回 ${res.status}`, res.status);
|
||||
|
||||
const text = await res.text();
|
||||
if (!text) return null as T;
|
||||
try {
|
||||
return JSON.parse(text) as T;
|
||||
} catch {
|
||||
return text as unknown as T;
|
||||
let body: unknown = null;
|
||||
if (text) {
|
||||
try {
|
||||
body = JSON.parse(text);
|
||||
} catch {
|
||||
body = text;
|
||||
}
|
||||
}
|
||||
|
||||
if (!res.ok) {
|
||||
// 本机软件的错误响应也是统一的 JSON(带 state/loggedIn),原样交给调用方
|
||||
if (body && typeof body === 'object' && 'state' in (body as Record<string, unknown>)) {
|
||||
return body as T;
|
||||
}
|
||||
throw new LocalServiceError(`本地服务返回 ${res.status}`, res.status);
|
||||
}
|
||||
|
||||
return (body ?? null) as T;
|
||||
} finally {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
|
||||
function get<T>(path: string, timeoutMs: number): Promise<T> {
|
||||
return request<T>(path, timeoutMs, 'GET');
|
||||
}
|
||||
/** 查询接口返回的业务状态 */
|
||||
export type LocalQueryState = 'ok' | 'need-login' | 'bad-request' | 'not-found' | 'error';
|
||||
|
||||
/** 本机软件状态(`GET /api/health`) */
|
||||
export interface LocalHealth {
|
||||
/** 软件在跑(只要 2xx 就算) */
|
||||
online: boolean;
|
||||
/** 软件已登录(没登录就唤起登录窗) */
|
||||
/**
|
||||
* `GET /api/query/{code}` 的统一响应
|
||||
*
|
||||
* 不论成败都带 `loggedIn` / `user` / `env` / `server`,所以:
|
||||
* - 收到任何响应(200/400/401/404)= 软件在跑;
|
||||
* - 只有**网络失败**(连不上/超时/被 CORS 拦)= 软件没启动。
|
||||
*/
|
||||
export interface LocalQueryResult {
|
||||
ok: boolean;
|
||||
state: LocalQueryState;
|
||||
/** 本次查询的运单号(原样回来,方便排查) */
|
||||
code?: string;
|
||||
loggedIn: boolean;
|
||||
/** 当前登录用户显示名 */
|
||||
user: string | null;
|
||||
/** 构建环境:Development / Production */
|
||||
env?: string;
|
||||
/** 当前后端地址(排障用) */
|
||||
server?: string;
|
||||
/** 失败原因 */
|
||||
message?: string;
|
||||
/** 成功时的数据(键值对,直接渲染) */
|
||||
data?: Record<string, unknown> | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 探活 + 拿登录状态
|
||||
* 查信息 —— **同时拿到服务/登录状态**
|
||||
*
|
||||
* 连不上 / 超时 / 被 CORS 拦掉 → `online: false`(页面统一提示「服务暂不可用」)。
|
||||
* 老版本软件没有 `loggedIn` 字段 → 当作已登录(不让新页面把老客户端卡死)。
|
||||
* 连不上 / 超时 / 被 CORS 拦 → 抛 {@link LocalServiceError}(页面提示「服务暂不可用」);
|
||||
* 其余情况都正常返回,看 `state`
|
||||
*/
|
||||
export async function localHealth(): Promise<LocalHealth> {
|
||||
try {
|
||||
const data = await get<unknown>('/api/health', 2500);
|
||||
if (!data || typeof data !== 'object') return { online: true, loggedIn: true, user: null };
|
||||
|
||||
const record = data as Record<string, unknown>;
|
||||
const online = record.ok !== false;
|
||||
const loggedIn = 'loggedIn' in record ? Boolean(record.loggedIn) : true;
|
||||
const user = typeof record.user === 'string' ? record.user : null;
|
||||
|
||||
return { online, loggedIn, user };
|
||||
} catch {
|
||||
return { online: false, loggedIn: false, user: null };
|
||||
}
|
||||
}
|
||||
|
||||
/** 向后兼容:只关心「在不在跑」的地方用这个 */
|
||||
export async function checkLocalHealth(): Promise<boolean> {
|
||||
return (await localHealth()).online;
|
||||
export async function queryLocal(code: string): Promise<LocalQueryResult> {
|
||||
return request<LocalQueryResult>(`/api/query/${encodeURIComponent(code)}`, 8000);
|
||||
}
|
||||
|
||||
/**
|
||||
@ -102,20 +113,15 @@ export function requestLocalLogin(): Promise<{ ok?: boolean; loggedIn?: boolean;
|
||||
return request('/api/activate-login', 4000, 'POST');
|
||||
}
|
||||
|
||||
/**
|
||||
* 按运单号 / 码查信息(本机软件返回什么就原样给什么,展示层做通用渲染)
|
||||
* @param code 运单号(来自插件跳转的 `?code=`)
|
||||
*/
|
||||
export function queryLocalInfo(code: string): Promise<unknown> {
|
||||
return get<unknown>(`/api/query/${encodeURIComponent(code)}`, 8000);
|
||||
}
|
||||
|
||||
/**
|
||||
* 叫醒已安装的本机软件:**自定义 URL Scheme**(安装包写进注册表的那种,像 `thunder://`、
|
||||
* `baiduyunguanjia://` 一样)
|
||||
*
|
||||
* 网页**无法直接执行 exe**:只能让浏览器去打开 `xxx://…`,由系统按注册表找到 exe 并拉起(
|
||||
* Chrome/Edge 会先弹「要打开 xxx 吗?」)。所以:先试这个,再轮询 health 确认真的起来了。
|
||||
* Chrome/Edge 会先弹「要打开 xxx 吗?」)。
|
||||
*
|
||||
* ⚠️ 浏览器**不会告诉我们成功与否**:能唤起、没安装、用户点「取消」在网页侧看起来一模一样。
|
||||
* 所以调用方必须配合超时兑底(轮询 `queryLocal` 等软件起来,超时就展示下载安装提示)。
|
||||
*
|
||||
* 协议名用 `VITE_APP_PROTOCOL` 配(默认 `yuncang`),必须与安装包里注册的一致。
|
||||
*/
|
||||
@ -130,6 +136,8 @@ export function appLaunchUrl(code?: string): string {
|
||||
/**
|
||||
* 触发唤醒。用隐藏 iframe 而不是 `location.href`:
|
||||
* 协议没注册时 Chrome 会直接在当前标签报错页,用 iframe 就只是静默失败。
|
||||
*
|
||||
* 只能在**用户手势**里调(点击 / 回车),否则 Chrome 会拦掉外部协议。
|
||||
*/
|
||||
export function launchApp(code?: string): void {
|
||||
const iframe = document.createElement('iframe');
|
||||
@ -140,35 +148,32 @@ export function launchApp(code?: string): void {
|
||||
}
|
||||
|
||||
/**
|
||||
* 轮询探活:本机软件从被叫醒到 HTTP 服务可用需要几秒
|
||||
* @return 最后一次探到的状态
|
||||
* 轮询查询:直到不再是「未登录」为止
|
||||
*
|
||||
* 用途:
|
||||
* - 软件没登录 → 唤起登录窗后,等用户登录完(登录成功后同一个接口就直接返回数据);
|
||||
* - 刚被协议唤起 → 等软件把 HTTP 服务拉起来。
|
||||
*
|
||||
* @returns `offline: true` = 申请不到(软件中途退了/没起来);`result` = 最后一次拿到的响应
|
||||
*/
|
||||
export async function waitForHealth(timeoutMs = 12000, intervalMs = 1000): Promise<LocalHealth> {
|
||||
export async function waitForQuery(
|
||||
code: string,
|
||||
timeoutMs = 30000,
|
||||
intervalMs = 1000,
|
||||
): Promise<{ result?: LocalQueryResult; offline: boolean }> {
|
||||
const deadline = Date.now() + timeoutMs;
|
||||
let last: LocalHealth = { online: false, loggedIn: false, user: null };
|
||||
let last: LocalQueryResult | undefined;
|
||||
|
||||
while (Date.now() < deadline) {
|
||||
last = await localHealth();
|
||||
if (last.online) return last;
|
||||
try {
|
||||
last = await queryLocal(code);
|
||||
} catch {
|
||||
return { result: last, offline: true };
|
||||
}
|
||||
|
||||
if (last.state !== 'need-login') return { result: last, offline: false };
|
||||
await new Promise(resolve => setTimeout(resolve, intervalMs));
|
||||
}
|
||||
|
||||
return last;
|
||||
}
|
||||
|
||||
/**
|
||||
* 等用户在本机软件里登录完成(每 1s 问一次 health,最多 timeoutMs)
|
||||
* @return 最后一次探到的状态
|
||||
*/
|
||||
export async function waitForLoggedIn(timeoutMs = 30000, intervalMs = 1000): Promise<LocalHealth> {
|
||||
const deadline = Date.now() + timeoutMs;
|
||||
let last: LocalHealth = { online: false, loggedIn: false, user: null };
|
||||
|
||||
while (Date.now() < deadline) {
|
||||
last = await localHealth();
|
||||
if (!last.online || last.loggedIn) return last;
|
||||
await new Promise(resolve => setTimeout(resolve, intervalMs));
|
||||
}
|
||||
|
||||
return last;
|
||||
return { result: last, offline: false };
|
||||
}
|
||||
|
||||
@ -13,7 +13,8 @@ const routes: RouteRecordRaw[] = [
|
||||
// 手机扫码后打开:确认登录(公开)
|
||||
{ path: '/wechat', name: 'wechat-confirm', component: () => import('@/views/WechatConfirmView.vue'), meta: { public: true, bare: true } },
|
||||
// 本机软件(打印服务)公共页:**不需要登录**,Chrome 插件打开 `/local?code=<运单号>`
|
||||
// 页面自己探活 http://localhost:17300/api/health,没登录就唤起软件登录,再查 /api/query/{code}
|
||||
// 页面自己查 http://localhost:17300/api/query/{code}(状态和结果一起回来),
|
||||
// 没启动就提示下载/唤起,没登录就唤起软件登录
|
||||
{
|
||||
path: '/local',
|
||||
alias: '/local/',
|
||||
|
||||
@ -2,12 +2,15 @@
|
||||
/**
|
||||
* 本机软件(打印服务)公共页 —— **不需要登录网站**,给 Chrome 插件直接打开用
|
||||
*
|
||||
* 流程:
|
||||
* 1. 打开就探活 `GET http://localhost:17300/api/health`;
|
||||
* 流程(**只用一个接口** `GET /api/query/{code}`,状态和结果一起回来):
|
||||
* 1. 打开就查一次(没带 code 也查,服务端会回「缺少运单号」+ 当前登录状态);
|
||||
* 2. 连不上 → 「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮 + 「启动本机软件」;
|
||||
* 3. 连上了但**本机软件没登录** → 自动请求 `POST /api/activate-login` 把登录窗叫到前台,
|
||||
* 然后每秒探活等登录完成(最长 30s),登录好自动继续;
|
||||
* 4. 已登录 → 用插件带过来的 `?code=`(运单号)调 `GET /api/query/{code}`,把返回信息展示出来。
|
||||
* 3. 返回 `need-login` → 自动 `POST /api/activate-login` 唤起登录窗,然后轮询**同一个查询接口**
|
||||
* 等登录完成(最长 30s),登录好自动拿到结果;
|
||||
* 4. `ok` → 展示数据;`not-found` 等 → 展示错误。
|
||||
*
|
||||
* 这样「中途退出软件」时,点「重新查询」会直接落到第 2 步的提示(而不是一个莫名其妙的失败),
|
||||
* 用户马上能看到「启动/下载」入口。
|
||||
*
|
||||
* 前端路由:`/local?code=xxx`(`meta.public`,未登录也能看);插件里把目标地址模板写成
|
||||
* `http://<站点>/local?code={code}` 即可。
|
||||
@ -17,14 +20,11 @@ import { useRoute, useRouter } from 'vue-router';
|
||||
import {
|
||||
APP_PROTOCOL,
|
||||
launchApp,
|
||||
localHealth,
|
||||
requestLocalLogin,
|
||||
queryLocalInfo,
|
||||
waitForHealth,
|
||||
waitForLoggedIn,
|
||||
queryLocal,
|
||||
waitForQuery,
|
||||
LOCAL_BASE,
|
||||
LocalServiceError,
|
||||
type LocalHealth,
|
||||
type LocalQueryResult,
|
||||
} from '@/api/local';
|
||||
|
||||
/**
|
||||
@ -40,54 +40,67 @@ type Status = 'checking' | 'offline' | 'launching' | 'need-login' | 'ready';
|
||||
|
||||
const status = ref<Status>('checking');
|
||||
const code = ref(String(route.query.code || '').trim());
|
||||
const info = ref<unknown>(null);
|
||||
const info = ref<Record<string, unknown> | null>(null);
|
||||
const querying = ref(false);
|
||||
const error = ref('');
|
||||
const launchFailed = ref(false);
|
||||
|
||||
/** 本机软件当前登录用户(health 里带回来的) */
|
||||
/** 本机软件当前登录用户(查询接口一起带回来的) */
|
||||
const loggedUser = ref<string | null>(null);
|
||||
/** 正在等用户在软件里完成登录 */
|
||||
const waitingLogin = ref(false);
|
||||
/** 当前连的后端(排障用,随查询接口返回) */
|
||||
const backend = ref('');
|
||||
|
||||
const emptyHealth: LocalHealth = { online: false, loggedIn: false, user: null };
|
||||
/** 记录接口返回的公共字段(登录用户、后端地址) */
|
||||
function applyMeta(res: LocalQueryResult) {
|
||||
loggedUser.value = res.user ?? null;
|
||||
backend.value = res.server || '';
|
||||
}
|
||||
|
||||
/** 探活 + 按状态往下走 */
|
||||
async function detect() {
|
||||
/** 根据一次查询结果驱动页面状态 */
|
||||
async function apply(res: LocalQueryResult) {
|
||||
applyMeta(res);
|
||||
|
||||
if (res.state === 'need-login') {
|
||||
status.value = 'need-login';
|
||||
await askLogin();
|
||||
return;
|
||||
}
|
||||
|
||||
status.value = 'ready';
|
||||
if (res.ok) {
|
||||
info.value = res.data ?? null;
|
||||
error.value = '';
|
||||
} else {
|
||||
info.value = null;
|
||||
error.value = res.message || '查询失败';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 打开页面 / 点「重新查询」:**只发一次查询请求**
|
||||
*
|
||||
* 连不上 → 直接给「服务暂不可用 + 下载/启动本机软件」;
|
||||
* 未登录 → 自动唤起登录并轮询同一个接口等登录完成;
|
||||
* 其余 → 展示数据或错误。
|
||||
*/
|
||||
async function load() {
|
||||
status.value = 'checking';
|
||||
error.value = '';
|
||||
info.value = null;
|
||||
launchFailed.value = false;
|
||||
|
||||
const health = await localHealth();
|
||||
|
||||
if (!health.online) {
|
||||
try {
|
||||
const res = await queryLocal(code.value.trim());
|
||||
await apply(res);
|
||||
} catch {
|
||||
// 连不上 = 软件没启动(或刚被用户退掉)→ 直接给下载 / 唤起入口
|
||||
status.value = 'offline';
|
||||
return;
|
||||
}
|
||||
|
||||
if (!health.loggedIn) {
|
||||
await requireLogin(health);
|
||||
return;
|
||||
}
|
||||
|
||||
await enterReady(health);
|
||||
}
|
||||
|
||||
/** 已登录:展示 + 查询 */
|
||||
async function enterReady(health: LocalHealth) {
|
||||
loggedUser.value = health.user;
|
||||
status.value = 'ready';
|
||||
await runQuery();
|
||||
}
|
||||
|
||||
/** 本机软件没登录:唤起登录窗并等登录完成 */
|
||||
async function requireLogin(health: LocalHealth = emptyHealth) {
|
||||
status.value = 'need-login';
|
||||
loggedUser.value = health.user;
|
||||
await askLogin();
|
||||
}
|
||||
|
||||
/** 请求唤起登录窗,并轮询等登录完成(30s) */
|
||||
/** 本机软件没登录:唤起登录窗,并轮询同一个查询接口等登录完成 */
|
||||
async function askLogin() {
|
||||
waitingLogin.value = true;
|
||||
|
||||
@ -97,67 +110,45 @@ async function askLogin() {
|
||||
// 唤起失败也继续轮询:用户可能自己从托盘打开软件登录
|
||||
}
|
||||
|
||||
const health = await waitForLoggedIn(30000);
|
||||
|
||||
if (!health.online) {
|
||||
status.value = 'offline';
|
||||
waitingLogin.value = false;
|
||||
return;
|
||||
}
|
||||
|
||||
if (health.loggedIn) {
|
||||
waitingLogin.value = false;
|
||||
await enterReady(health);
|
||||
return;
|
||||
}
|
||||
|
||||
// 30s 还没登录:留在提示页,用户可再点一次
|
||||
const outcome = await waitForQuery(code.value.trim(), 30000);
|
||||
waitingLogin.value = false;
|
||||
|
||||
if (outcome.offline) {
|
||||
status.value = 'offline';
|
||||
return;
|
||||
}
|
||||
if (outcome.result) await apply(outcome.result);
|
||||
}
|
||||
|
||||
/** 「启动本机软件」:自定义协议叫醒 → 轮询探活 → 需要登录就唤起登录 */
|
||||
/** 「启动本机软件」:协议叫醒(带 code)→ 轮询查询接口等它起来 */
|
||||
async function launch() {
|
||||
launchFailed.value = false;
|
||||
status.value = 'launching';
|
||||
|
||||
launchApp(code.value.trim() || undefined);
|
||||
|
||||
const health = await waitForHealth();
|
||||
const outcome = await waitForQuery(code.value.trim(), 15000);
|
||||
|
||||
if (!health.online) {
|
||||
if (outcome.offline) {
|
||||
launchFailed.value = true;
|
||||
status.value = 'offline';
|
||||
return;
|
||||
}
|
||||
|
||||
if (!health.loggedIn) {
|
||||
await requireLogin(health);
|
||||
return;
|
||||
}
|
||||
|
||||
await enterReady(health);
|
||||
if (outcome.result) await apply(outcome.result);
|
||||
}
|
||||
|
||||
/** 按码查信息(没填码就只停在输入框) */
|
||||
/** 按码查信息(码为空也发一次:服务端会回「缺少运单号」+ 当前登录状态,照样能驱动页面) */
|
||||
async function runQuery() {
|
||||
const target = code.value.trim();
|
||||
if (!target) return;
|
||||
|
||||
querying.value = true;
|
||||
error.value = '';
|
||||
info.value = null;
|
||||
try {
|
||||
info.value = await queryLocalInfo(target);
|
||||
} catch (err) {
|
||||
if (err instanceof LocalServiceError && err.status === 401) {
|
||||
// 刚好在这期间退出了登录:再走一次唤起登录
|
||||
await requireLogin();
|
||||
return;
|
||||
}
|
||||
|
||||
error.value = err instanceof LocalServiceError
|
||||
? `查询失败:${err.message}`
|
||||
: '查询失败,请确认本机软件已启动后重试';
|
||||
try {
|
||||
const res = await queryLocal(code.value.trim());
|
||||
await apply(res);
|
||||
} catch {
|
||||
// 中途退出了软件 / 服务停了:直接切到「可以唤起」的提示,不用用户再踩坑
|
||||
status.value = 'offline';
|
||||
info.value = null;
|
||||
} finally {
|
||||
querying.value = false;
|
||||
}
|
||||
@ -170,13 +161,12 @@ function submitCode() {
|
||||
runQuery();
|
||||
}
|
||||
|
||||
/** 把任意返回结构拍平成「项目 - 值」两列,便于通用展示 */
|
||||
/** 把返回的数据拍平成「项目 - 值」两列,便于通用展示 */
|
||||
const entries = computed<Array<{ key: string; value: string }>>(() => {
|
||||
const data = info.value;
|
||||
if (data === null || data === undefined) return [];
|
||||
if (typeof data !== 'object') return [{ key: '结果', value: String(data) }];
|
||||
if (!data) return [];
|
||||
|
||||
return Object.entries(data as Record<string, unknown>).map(([ key, value ]) => {
|
||||
return Object.entries(data).map(([ key, value ]) => {
|
||||
let text: string;
|
||||
if (value === null || value === undefined) text = '—';
|
||||
else if (typeof value === 'object') text = JSON.stringify(value);
|
||||
@ -185,9 +175,9 @@ const entries = computed<Array<{ key: string; value: string }>>(() => {
|
||||
});
|
||||
});
|
||||
|
||||
const raw = computed(() => (info.value === null || info.value === undefined ? '' : JSON.stringify(info.value, null, 2)));
|
||||
const raw = computed(() => (info.value ? JSON.stringify(info.value, null, 2) : ''));
|
||||
|
||||
onMounted(detect);
|
||||
onMounted(load);
|
||||
</script>
|
||||
|
||||
<template>
|
||||
@ -195,9 +185,9 @@ onMounted(detect);
|
||||
<div class="card bare-card local-card">
|
||||
<div class="brand-line">云仓视频溯源系统</div>
|
||||
|
||||
<!-- ① 正在检测 / 正在启动 -->
|
||||
<!-- ① 正在连接 / 正在启动 -->
|
||||
<template v-if="status === 'checking'">
|
||||
<p class="center hint">正在检测本机打印服务…</p>
|
||||
<p class="center hint">正在连接本机打印服务…</p>
|
||||
</template>
|
||||
<template v-else-if="status === 'launching'">
|
||||
<p class="center hint">正在启动本机软件…(浏览器问“要打开吗”请点允许)</p>
|
||||
@ -220,7 +210,7 @@ onMounted(detect);
|
||||
没有反应?可能是没安装、或安装时没注册启动协议({{ APP_PROTOCOL }}://),先下载安装吧。
|
||||
</p>
|
||||
<p class="center hint tiny">
|
||||
再点 <a href="#" @click.prevent="detect">重新检测</a>
|
||||
再点 <a href="#" @click.prevent="load">重新连接</a>
|
||||
<br>
|
||||
(当前探测地址:{{ LOCAL_BASE }})
|
||||
</p>
|
||||
@ -242,6 +232,7 @@ onMounted(detect);
|
||||
看不到窗口?双击托盘里的「云仓视频溯源软件」图标
|
||||
<br>
|
||||
(探测地址:{{ LOCAL_BASE }})
|
||||
<span v-if="backend"><br>(本机后端:{{ backend }})</span>
|
||||
</p>
|
||||
</template>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user