移除探活接口:状态合进 /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:
liufumingren 2026-10-17 11:10:34 +08:00
parent 30ad162c69
commit c12ea3b197
5 changed files with 280 additions and 216 deletions

View File

@ -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}`:网页里有真实的查询结果,连不上就是真的没起来。
## ★ 接真实数据

View File

@ -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>
""";

View File

@ -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 };
}

View File

@ -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/',

View File

@ -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>