前端:新增不需要登录的「本机软件」公共页 /local?code=

给 Chrome 插件用:点运单号旁的按钮直接打开这一页(插件里的默认目标地址模板已改成
http://localhost:7301/local?code={code},线上换域名即可)。

- 打开即探活 GET http://localhost:17311/api/health:
  - 连不上/超时/被 CORS 拦 → 「服务暂不可用」+「本地打印服务未启动,请下载安装后再试」
    + 居中的「下载 云仓视频溯源软件」按钮 + 「重新检测」(页面上也打出探测地址,方便排查);
  - 可用 → 用 ?code= 调 GET http://localhost:17311/api/query/{code},把返回按
    「项目 / 值」两列展示,另附可展开的原始 JSON(本机软件返回结构未知,做通用渲染)。
- 没带 code 时给一个输入框手动查;提交后把 code 同步进地址栏(命名路由 local-service)。
- 路由 meta.public,并且**已登录时也不被踢回首页**(和扫码确认页一样始终显示,
  因为插件/手机是直接打开它的)。
- 本机服务地址可用 VITE_LOCAL_SERVICE 覆盖(换端口或改用 127.0.0.1 时)。

⚠️ 本机软件需要放行 CORS(Access-Control-Allow-Origin),否则浏览器会拦掉跨域请求,
表现和「软件没启动」一样(页面只能提示服务暂不可用)。

实测:7301 前端 + 一个模拟的 17311 本机服务 —— 无服务时提示文案与居中正确;
起服务后 /local?code=321408064481797 自动查出 6 行信息;不带 code 时手动输入可查。
This commit is contained in:
liufumingren 2026-10-17 10:02:48 +08:00
parent 407551f86e
commit 7198dd1eb4
3 changed files with 323 additions and 1 deletions

79
frontend/src/api/local.ts Normal file
View File

@ -0,0 +1,79 @@
/**
* 本机软件(打印服务)客户端 —— 由 Chrome 插件打开的公共页用它查运单信息
*
* 本机服务默认监听 `http://localhost:17311`:
* - `GET /api/health` 探活:能连通就是「软件已启动」
* - `GET /api/query/{code}` 按运单号查信息
*
* ⚠️ 这是**跨域**请求(页面同源是我们的站点,目标是 localhost:17311):
* 本机软件必须允许 CORS(`Access-Control-Allow-Origin` 放行站点来源),否则浏览器会拦掉,
* 表现和「软件没启动」一样 —— 页面统一提示「服务暂不可用」。
*
* 地址可用 `VITE_LOCAL_SERVICE` 覆盖(换端口 / 换 127.0.0.1 时用)。
*/
/** 本机服务地址(去掉末尾斜杠) */
export const LOCAL_BASE = ((import.meta.env.VITE_LOCAL_SERVICE as string | undefined) || 'http://localhost:17311')
.replace(/\/+$/, '');
/** 本机服务返回非 2xx / 超时 / 跨域失败时抛它 */
export class LocalServiceError extends Error {
/** HTTP 状态码(网络层失败时为 0) */
status: number;
constructor(message: string, status = 0) {
super(message);
this.name = 'LocalServiceError';
this.status = status;
}
}
/** 带超时的 GET;返回解析后的 JSON(不是 JSON 就给纯文本) */
async function get<T>(path: string, timeoutMs: number): Promise<T> {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetch(`${LOCAL_BASE}${path}`, {
method: 'GET',
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;
}
} finally {
clearTimeout(timer);
}
}
/**
* 探活:本机软件是否在跑
*
* 只要 `GET /api/health` 能拿到 2xx 就算可用;返回体里显式写了 `ok:false` 也算不可用。
* 连不上 / 超时 / 被 CORS 拦掉 → false(页面统一提示「服务暂不可用」)。
*/
export async function checkLocalHealth(): Promise<boolean> {
try {
const data = await get<unknown>('/api/health', 2500);
if (data && typeof data === 'object' && 'ok' in data) {
return Boolean((data as { ok?: unknown }).ok);
}
return true;
} catch {
return false;
}
}
/**
* 按运单号 / 码查信息(本机软件返回什么就原样给什么,展示层做通用渲染)
* @param code 运单号(来自插件跳转的 `?code=`)
*/
export function queryLocalInfo(code: string): Promise<unknown> {
return get<unknown>(`/api/query/${encodeURIComponent(code)}`, 8000);
}

View File

@ -12,6 +12,9 @@ const routes: RouteRecordRaw[] = [
{ path: '/reset', name: 'reset', component: () => import('@/views/ResetView.vue'), meta: { public: true, bare: true } },
// 手机扫码后打开:确认登录(公开)
{ path: '/wechat', name: 'wechat-confirm', component: () => import('@/views/WechatConfirmView.vue'), meta: { public: true, bare: true } },
// 本机软件(打印服务)公共页:**不需要登录**,Chrome 插件打开 `/local?code=<运单号>`
// 页面自己探活 http://localhost:17311/api/health,再查 /api/query/{code}
{ path: '/local', name: 'local-service', component: () => import('@/views/LocalServiceView.vue'), meta: { public: true, bare: true } },
{ path: '/', name: 'home', component: () => import('@/views/HomeView.vue') },
{ path: '/devices', name: 'devices', component: () => import('@/views/DevicesView.vue') },
@ -32,7 +35,10 @@ router.beforeEach((to) => {
if (!to.meta.public && !logged) {
return { name: 'login', query: { redirect: to.fullPath } };
}
if (to.meta.public && logged && to.name !== 'wechat-confirm') {
// 已登录时这些公开页也照常显示(扫码确认页 / 本机软件页:由插件或手机直接打开,
// 不该被踢回首页)
const alwaysShow = to.name === 'wechat-confirm' || to.name === 'local-service';
if (to.meta.public && logged && !alwaysShow) {
return { name: 'home' };
}
return true;

View File

@ -0,0 +1,237 @@
<script setup lang="ts">
/**
* 本机软件(打印服务)公共页 —— **不需要登录**,给 Chrome 插件直接打开用
*
* 流程:
* 1. 打开就探活 `GET http://localhost:17311/api/health`;
* 2. 探不到 → 「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮(居中);
* 3. 探到了 → 用插件带过来的 `?code=`(运单号)调 `GET /api/query/{code}`,把返回信息展示出来。
*
* 前端路由:`/local?code=xxx`(`meta.public`,未登录也能看);插件里把目标地址模板写成
* `http://<站点>/local?code={code}` 即可。
*/
import { computed, onMounted, ref } from 'vue';
import { useRoute, useRouter } from 'vue-router';
import { checkLocalHealth, queryLocalInfo, LOCAL_BASE, LocalServiceError } from '@/api/local';
/**
* 安装包下载地址:换成真实地址,或用环境变量 `VITE_SOFTWARE_DOWNLOAD_URL` 覆盖
* (没配时按钮点不动,只作为提示)
*/
const DOWNLOAD_URL = (import.meta.env.VITE_SOFTWARE_DOWNLOAD_URL as string | undefined) || '#';
const route = useRoute();
const router = useRouter();
type Status = 'checking' | 'offline' | 'ready';
const status = ref<Status>('checking');
const code = ref(String(route.query.code || '').trim());
const info = ref<unknown>(null);
const querying = ref(false);
const error = ref('');
/** 探活:连不上就是「软件没启动」 */
async function detect() {
status.value = 'checking';
error.value = '';
const alive = await checkLocalHealth();
status.value = alive ? 'ready' : 'offline';
if (alive) await runQuery();
}
/** 按码查信息(没填码就只停在输入框) */
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) {
error.value = err instanceof LocalServiceError
? `查询失败:${err.message}`
: '查询失败,请确认本机软件已启动后重试';
} finally {
querying.value = false;
}
}
/** 输入框里改了码,同步到地址栏(方便刷新 / 复制链接) */
function submitCode() {
const target = code.value.trim();
router.replace({ name: 'local-service', query: target ? { code: target } : {} });
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) }];
return Object.entries(data as Record<string, unknown>).map(([ key, value ]) => {
let text: string;
if (value === null || value === undefined) text = '—';
else if (typeof value === 'object') text = JSON.stringify(value);
else text = String(value);
return { key, value: text };
});
});
const raw = computed(() => (info.value === null || info.value === undefined ? '' : JSON.stringify(info.value, null, 2)));
onMounted(detect);
</script>
<template>
<div class="bare-page">
<div class="card bare-card local-card">
<div class="brand-line">云仓视频溯源系统</div>
<!-- ① 正在检测 -->
<template v-if="status === 'checking'">
<p class="center hint">正在检测本机打印服务…</p>
</template>
<!-- ② 本机软件没启动 / 连不上 -->
<template v-else-if="status === 'offline'">
<div class="alert alert-error center-block">
<b>服务暂不可用</b>
</div>
<p class="center hint">本地打印服务未启动,请下载安装后再试</p>
<p class="center">
<a class="btn download" :href="DOWNLOAD_URL" target="_blank" rel="noopener">下载 云仓视频溯源软件</a>
</p>
<p class="center hint tiny">
已安装?请先启动软件,再点
<a href="#" @click.prevent="detect">重新检测</a>
<br>
(当前探测地址:{{ LOCAL_BASE }})
</p>
</template>
<!-- ③ 本机软件在跑 -->
<template v-else>
<div v-if="!code" class="field-plain">
<span class="tip">必填 · 运单号 / 条码</span>
<div class="input-row">
<input v-model="code" placeholder="运单号" @keyup.enter="submitCode" />
<button class="btn" type="button" :disabled="querying" @click="submitCode">查询</button>
</div>
</div>
<template v-else>
<p class="center hint">
运单号 <code>{{ code }}</code>
<button class="btn btn-ghost btn-inline" type="button" :disabled="querying" @click="runQuery">重新查询</button>
</p>
</template>
<div v-if="error" class="alert alert-error">{{ error }}</div>
<p v-else-if="querying" class="center hint">查询中…</p>
<template v-else-if="info !== null">
<table v-if="entries.length" class="table result-table">
<tbody>
<tr v-for="row in entries" :key="row.key">
<th>{{ row.key }}</th>
<td>{{ row.value }}</td>
</tr>
</tbody>
</table>
<p v-else class="center hint">本机软件没有返回内容。</p>
<details v-if="raw" class="raw">
<summary>原始返回(JSON)</summary>
<pre class="json-box">{{ raw }}</pre>
</details>
</template>
</template>
</div>
</div>
</template>
<style scoped>
.local-card {
width: 460px;
}
.brand-line {
margin: 0 0 16px;
font-size: 18px;
font-weight: 600;
text-align: center;
}
.center {
text-align: center;
}
.center-block {
text-align: center;
}
.download {
display: inline-block;
padding: 10px 22px;
border-radius: 8px;
background: var(--brand);
color: #fff;
font-size: 15px;
}
.download:hover {
background: var(--brand-dark);
}
.tiny {
font-size: 12px;
}
.btn-inline {
margin-left: 8px;
padding: 2px 10px;
font-size: 12px;
}
.result-table {
border: 1px solid var(--border);
border-radius: 8px;
overflow: hidden;
}
.result-table th {
width: 38%;
white-space: nowrap;
}
.result-table td {
word-break: break-all;
}
.raw {
margin-top: 12px;
font-size: 13px;
}
.raw summary {
cursor: pointer;
color: var(--text-muted);
}
.json-box {
margin: 8px 0 0;
max-height: 260px;
overflow: auto;
padding: 10px 12px;
border-radius: 8px;
background: #f9fafb;
border: 1px solid var(--border);
font: 12px/1.6 ui-monospace, SFMono-Regular, Consolas, monospace;
white-space: pre-wrap;
word-break: break-all;
}
</style>