feat(用户端): 低于 4.0.52 的桌面装机进强制升级遮罩——存量装机只有线上 Web 这一条覆盖通道

后端那个版本地板闸门只会把请求挡成 code 4012,客户端业务代码里没有任何 4012 分支:只拦、不推;
而桌面窗口直载 app-web(APP_URL = config.WEB_HOME_URL),做在页面上才吃得到已经装出去的机器。

判定落在 shared/client-force-update.ts(纯函数,17 例含"换地板结论就翻面"的反例):判不出来一律不拦
(浏览器形态、读不到本机版本、版本串解析不出数字、没有可下的包、线上包并不比本机新)。
遮罩挂 App.vue 根=登录页与首页一起覆盖,自动开始下载,失败只给"重试(断点续传)",不再等第二次确认。
This commit is contained in:
2026-10-13 21:37:08 +08:00
parent 731aa35a47
commit fa11db59ee
5 changed files with 440 additions and 0 deletions
+2
View File
@@ -2,6 +2,7 @@
<el-config-provider :locale="zhCn">
<router-view />
<ExpiryNotice />
<ForceUpdateGate />
</el-config-provider>
</template>
@@ -14,6 +15,7 @@
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import { onBeforeUnmount } from 'vue'
import ExpiryNotice from '@/shared/components/ExpiryNotice.vue'
import ForceUpdateGate from '@/shared/components/ForceUpdateGate.vue'
import { disposeGlobalErrorGuard } from '@/shared/utils/app-error'
import { uninstallUserTokenSync } from '@/shared/auth/user-token-sync'
import { disposeDownloadProgressListener } from '@/shared/utils/download-progress'
@@ -0,0 +1,74 @@
/**
* 强制升级判定(纯函数,无 DOM、可 node --test 直跑)。
*
* 动机:桌面窗口的页面是线上 Web(app_client/main.py 的 APP_URL = config.WEB_HOME_URL),
* 所以"要不要升、不升能不能继续用"这件事只有发一次 app-web 才能覆盖存量装机;
* 服务端那个版本地板闸门(ClientVersionGuardFilter)只会把请求挡成 code 4012,
* 而客户端业务代码里没有任何 4012 分支——它只拦、不推。这里补的就是"推"那一半。
*
* 判定刻意保守:**任何"判不出来"的情况一律不拦**(浏览器形态、读不到本机版本、
* 版本串解析不出数字、没有可下载的更新包、最新包并不比本机新)。
* 挡在门外是拿用户当天的任务换他们的下一次启动,误判一次的代价比漏判大。
*/
import { compareVersions, normVersion } from './utils/version-compare.ts'
/** 强升地板:低于这个版本的桌面装机必须更新后才能继续用。 */
export const FORCE_UPDATE_TARGET = '4.0.52'
/** 不拦的理由。每个值都必须能在界面上被解释,不许拿空串当"没必要说"。 */
export type ForceSkipReason =
| 'not-desktop'
| 'no-local-version'
| 'unparsable-local-version'
| 'invalid-target'
| 'at-or-above-target'
| 'no-newer-package'
export type ForceDecision =
| { force: true; localVersion: string; targetVersion: string }
| { force: false; reason: ForceSkipReason; localVersion: string; targetVersion: string }
/**
* 点分数字版本:至少三段、每段都是非负整数。
*
* 需要它是因为 compareVersions 把解析不出的段当 0('4.0.52-beta' 会等于 '4.0.0'),
* 于是"带后缀的版本"会被判成更旧而误锁人。地板只认能算干净的形状。
*/
export function isDottedNumericVersion(value: string): boolean {
const parts = normVersion(value).split('.')
if (parts.length < 3) return false
return parts.every((part) => /^\d+$/.test(part))
}
export function decideForceUpdate(input: {
/** 有没有真实的桌面桥(能下载并自启更新程序);Web 降级桥不算。 */
desktopBridge: boolean
/** 本机 exe 版本(桥读不到就传空串)。 */
localVersion: string
/** 线上最新包版本(/api/version/latest 的 version)。 */
latestVersion: string
/** 最新包有没有可用下载地址。 */
hasPackage: boolean
targetVersion?: string
}): ForceDecision {
const target = normVersion(input.targetVersion ?? FORCE_UPDATE_TARGET)
const local = normVersion(input.localVersion)
const notForced = (reason: ForceSkipReason): ForceDecision => ({
force: false,
reason,
localVersion: local,
targetVersion: target,
})
if (!input.desktopBridge) return notForced('not-desktop')
if (!isDottedNumericVersion(target)) return notForced('invalid-target')
if (!local) return notForced('no-local-version')
if (!isDottedNumericVersion(local)) return notForced('unparsable-local-version')
if (compareVersions(local, target) >= 0) return notForced('at-or-above-target')
// 到了这一步才看包:没有地址、或线上包并不比本机新,那就拿不出"升上去更好"的东西,
// 不能把人锁在门外(灰度回滚期 latest 低于地板是真实存在的状态)。
if (!input.hasPackage) return notForced('no-newer-package')
const latest = normVersion(input.latestVersion)
if (!latest || compareVersions(latest, local) <= 0) return notForced('no-newer-package')
return { force: true, localVersion: local, targetVersion: target }
}
@@ -0,0 +1,190 @@
<script setup lang="ts">
/**
* 强制升级遮罩:低于地板版本的桌面装机,不更新就不能继续用。
*
* 为什么做在页面而不是 exe 或后端闸门:桌面窗口直载线上 Web,存量装机下次打开就吃到这一版;
* exe 里的代码改不动已经装出去的那些,后端地板闸门只会把请求挡成 code 4012(客户端不认这个码,
* 只拦不推)。判定本身在 shared/client-force-update.ts(纯函数、可实跑),这里只管挂载时机与界面。
*
* 不打扰的情形(由判定决定,不在这里二次猜):浏览器形态、老 exe 读不到本机版本、
* 没有可用更新包、本机已达标或线上包更旧。
*/
import { computed, onMounted, onUnmounted, ref } from 'vue'
import UpdateProgressBar from '@/shared/components/UpdateProgressBar.vue'
import { decideForceUpdate, type ForceDecision } from '@/shared/client-force-update'
import { getPywebviewApi, hasPywebview } from '@/shared/bridges/pywebview'
import { useVersionUpdate } from '@/shared/composables/useVersionUpdate'
const { currentVersion, latestVersion, fileUrl, progress, runCheck, startUpdate } = useVersionUpdate()
const decision = ref<ForceDecision | null>(null)
let evaluated = false
const blocked = computed(() => decision.value?.force === true)
const failed = computed(() => progress.value?.status === 'failed')
/** 下载/校验进行中不许再点(Python 侧有同一把锁,但界面不该让人白点一次)。 */
const inFlight = computed(() => {
const status = progress.value?.status
return status === 'downloading' || status === 'verifying'
})
const readyToExit = computed(() => progress.value?.status === 'ready')
const primaryText = computed(() => {
if (inFlight.value) return '正在下载更新包…'
if (readyToExit.value) return '更新包已就绪'
return '立即更新'
})
function start(): void {
if (!fileUrl.value || inFlight.value || readyToExit.value) return
void startUpdate(fileUrl.value)
}
async function evaluate(): Promise<void> {
if (evaluated) return
evaluated = true
await runCheck()
decision.value = decideForceUpdate({
// 只有"真桌面桥 + 会做更新"两个条件同时成立才拦人:降级桥点了也办不成事
desktopBridge: hasPywebview() && Boolean(getPywebviewApi()?.do_update_app),
localVersion: currentVersion.value,
latestVersion: latestVersion.value,
hasPackage: Boolean(fileUrl.value),
})
if (decision.value.force) start()
}
// 桥注入可能晚于本组件挂载:没就绪就等 pywebviewready,就绪了才判一次(浏览器永远不判成强升)
const readyHandler = () => {
void evaluate()
}
onMounted(() => {
if (hasPywebview()) {
void evaluate()
return
}
window.addEventListener('pywebviewready', readyHandler, { once: true })
})
onUnmounted(() => {
window.removeEventListener('pywebviewready', readyHandler)
})
</script>
<template>
<div v-if="blocked && decision" class="force-update-mask" role="dialog" aria-modal="true" aria-label="需要更新">
<section class="force-update-card">
<h2 class="force-update-title">需要更新后才能继续使用</h2>
<p class="force-update-versions">
当前版本 <b>v{{ decision.localVersion }}</b> 最低要求 <b>v{{ decision.targetVersion }}</b>
</p>
<p class="force-update-desc">
这个版本已不能正常使用。更新已开始自动下载,下载完成后程序会在本机任务跑完时自动退出并安装。
</p>
<UpdateProgressBar :progress="progress" />
<div class="force-update-actions">
<button
type="button"
class="force-update-primary"
:disabled="inFlight || readyToExit"
@click="start"
>
{{ primaryText }}
</button>
<button v-if="failed" type="button" class="force-update-ghost" @click="start">
重试(从断点继续)
</button>
</div>
<p v-if="failed" class="force-update-tip">
下载没成功可以再点重试,网络中断后会从断点继续。反复失败请联系技术支持协助更新。
</p>
<p v-else-if="readyToExit" class="force-update-tip">
更新包已就绪,等本机任务跑完就会自动退出并更新;也可以先保存手上的工作再重启。
</p>
</section>
</div>
</template>
<style scoped>
.force-update-mask {
position: fixed;
inset: 0;
z-index: 3200;
background: rgba(20, 20, 20, 0.78);
display: flex;
align-items: center;
justify-content: center;
padding: 24px;
}
.force-update-card {
width: 460px;
max-width: 100%;
background: #fff;
border-radius: 10px;
padding: 22px 24px 18px;
box-shadow: 0 12px 36px rgba(0, 0, 0, 0.32);
}
.force-update-title {
margin: 0 0 10px;
font-size: 18px;
color: #c0392b;
}
.force-update-versions {
margin: 0 0 8px;
font-size: 14px;
color: #333;
}
.force-update-desc {
margin: 0 0 12px;
font-size: 13px;
line-height: 1.7;
color: #555;
}
.force-update-actions {
margin-top: 14px;
display: flex;
gap: 10px;
flex-wrap: wrap;
}
.force-update-primary {
padding: 8px 20px;
border: none;
border-radius: 5px;
background: #28a745;
color: #fff;
font-size: 14px;
cursor: pointer;
}
.force-update-primary:disabled {
background: #9fc9ab;
cursor: default;
}
.force-update-ghost {
padding: 8px 14px;
border: 1px solid #d0d0d0;
border-radius: 5px;
background: #fff;
color: #333;
font-size: 14px;
cursor: pointer;
}
.force-update-tip {
margin: 12px 0 0;
font-size: 12px;
line-height: 1.7;
color: #8a6d3b;
}
</style>
@@ -342,6 +342,7 @@ export function useVersionUpdate() {
loadCurrentVersion,
loadVersions,
runCheck,
startUpdate,
doUpdate,
doUpdateVersion,
}
@@ -0,0 +1,173 @@
import { test } from 'node:test'
import assert from 'node:assert/strict'
import { readFileSync, readdirSync, statSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { join, resolve, dirname, relative } from 'node:path'
/**
* 强制升级门(10-13 决定对 4.0.52 以下的桌面装机开启)。
*
* 两半各自要证的:
* ① 判定本体(client-force-update.ts)—— 真单元测试,含"换地板结论就跟着变"的反例,
* 否则一条恒真的 force 判据会一直绿到把所有人锁在门外那天。
* ② 接线(.vue 组件在本套里挂不起来,按 readSource 约定钉形状)—— 要防的是
* "模块写了但没挂进 App"(改了没人跑)与"组件里塞 try/catch、用 window.confirm
* 走回手动那条路"(那等于把强升退化成又一次用户点一下)。
*/
import {
decideForceUpdate,
FORCE_UPDATE_TARGET,
isDottedNumericVersion,
} from '../src/shared/client-force-update.ts'
const here = dirname(fileURLToPath(import.meta.url))
const srcRoot = resolve(here, '../src')
const gate = readFileSync(resolve(srcRoot, 'shared/components/ForceUpdateGate.vue'), 'utf8')
const appVue = readFileSync(resolve(srcRoot, 'App.vue'), 'utf8')
function listSourceFiles(dir: string): string[] {
const out: string[] = []
for (const name of readdirSync(dir)) {
const full = join(dir, name)
if (statSync(full).isDirectory()) out.push(...listSourceFiles(full))
else if (/\.(ts|vue)$/.test(name)) out.push(full)
}
return out
}
test('test_floor_constant_is_pinned_dotted_version', () => {
assert.equal(FORCE_UPDATE_TARGET, '4.0.52', '地板改动必须显式改常量并留出处')
assert.ok(isDottedNumericVersion(FORCE_UPDATE_TARGET), '地板必须是三段点分数字')
})
test('test_below_floor_on_desktop_with_package_forces', () => {
const d = decideForceUpdate({
desktopBridge: true, localVersion: '4.0.51', latestVersion: '4.0.52', hasPackage: true,
})
assert.equal(d.force, true)
assert.equal(d.localVersion, '4.0.51')
assert.equal(d.targetVersion, '4.0.52')
})
test('test_very_old_client_also_forces', () => {
const d = decideForceUpdate({
desktopBridge: true, localVersion: '3.0.73', latestVersion: '4.0.52', hasPackage: true,
})
assert.equal(d.force, true, '远低于地板的老装机正是这次要覆盖的人')
})
test('test_at_floor_does_not_force', () => {
const d = decideForceUpdate({
desktopBridge: true, localVersion: '4.0.52', latestVersion: '4.0.52', hasPackage: true,
})
assert.equal(d.force, false)
assert.equal(d.reason, 'at-or-above-target')
})
test('test_newer_than_floor_does_not_force', () => {
// 灰度/回滚窗口里"本机比地板新"是真会发生的:不能反过来把人按住
const d = decideForceUpdate({
desktopBridge: true, localVersion: '4.0.99', latestVersion: '4.0.99', hasPackage: true,
})
assert.equal(d.force, false)
assert.equal(d.reason, 'at-or-above-target')
})
test('test_browser_runtime_never_forces', () => {
// 网页形态没有 exe 可升,拦下来就是把用户关在门外
const d = decideForceUpdate({
desktopBridge: false, localVersion: '4.0.20', latestVersion: '4.0.52', hasPackage: true,
})
assert.equal(d.force, false)
assert.equal(d.reason, 'not-desktop')
})
test('test_missing_local_version_does_not_force', () => {
// 老 exe 没有 get_app_version 桥:判不出来就不拦(宁漏不误锁)
const d = decideForceUpdate({
desktopBridge: true, localVersion: '', latestVersion: '4.0.52', hasPackage: true,
})
assert.equal(d.force, false)
assert.equal(d.reason, 'no-local-version')
})
test('test_unparsable_local_version_does_not_force', () => {
// compareVersions 把非数字段当 0,'4.0.52-beta' 会被算成 '4.0.52'、'x-beta' 会被算成 '0.0.0':
// 少了这道判据,带后缀的内部版本会被误锁
const d = decideForceUpdate({
desktopBridge: true, localVersion: 'beta', latestVersion: '4.0.52', hasPackage: true,
})
assert.equal(d.force, false)
assert.equal(d.reason, 'unparsable-local-version')
})
test('test_no_download_url_does_not_force', () => {
const d = decideForceUpdate({
desktopBridge: true, localVersion: '4.0.47', latestVersion: '4.0.52', hasPackage: false,
})
assert.equal(d.force, false)
assert.equal(d.reason, 'no-newer-package', '没有可下的包就别把人锁住')
})
test('test_latest_package_not_above_local_does_not_force', () => {
// 线上包已回滚到 4.0.40:升上去更差,不升
const d = decideForceUpdate({
desktopBridge: true, localVersion: '4.0.47', latestVersion: '4.0.40', hasPackage: true,
})
assert.equal(d.force, false)
assert.equal(d.reason, 'no-newer-package')
})
test('test_invalid_floor_does_not_force', () => {
const d = decideForceUpdate({
desktopBridge: true, localVersion: '4.0.47', latestVersion: '4.0.52', hasPackage: true,
targetVersion: 'v4',
})
assert.equal(d.force, false)
assert.equal(d.reason, 'invalid-target', '地板写坏了要认出来,不许拿 0.0.0 当阈值')
})
test('test_decision_follows_the_floor_not_the_caller', () => {
// 反例自证:同一次调用只换地板,结论必须翻面(否则上一条条"低于地板就 force"是恒真)
const input = {
desktopBridge: true, localVersion: '4.0.51', latestVersion: '4.0.52', hasPackage: true,
}
assert.equal(decideForceUpdate({ ...input, targetVersion: '4.0.52' }).force, true)
assert.equal(decideForceUpdate({ ...input, targetVersion: '4.0.51' }).force, false)
})
test('test_is_dotted_numeric_version_real_samples', () => {
assert.equal(isDottedNumericVersion('4.0.52'), true)
assert.equal(isDottedNumericVersion('v4.1.0'), true, '前缀 v 归一化后按点分数字认')
assert.equal(isDottedNumericVersion('4.0'), false, '不足三段不认:0 补齐会把地板算成 4.0.0')
assert.equal(isDottedNumericVersion('4.0.52-beta'), false)
assert.equal(isDottedNumericVersion(''), false)
})
test('test_gate_uses_the_shared_decision_and_real_bridge', () => {
assert.ok(gate.includes('decideForceUpdate'), '遮罩必须走同一个判定,不许在组件里另写一套比较')
assert.ok(gate.includes('hasPywebview()'), '桌面判定只认真桥,Web 降级桥不算')
assert.ok(gate.includes('do_update_app'), '没有更新能力的装机不许拦(拦了也办不成事)')
assert.ok(gate.includes('startUpdate('), '自动开始下载走既有下载链,不复制第二份下载实现')
})
test('test_gate_does_not_fall_back_to_manual_confirm', () => {
assert.equal(gate.includes('window.confirm'), false, '强升不该再等用户点一次"是否更新"')
assert.equal(/catch\s*[({]/.test(gate), false, '遮罩里新增 try/catch 会绕过静默棘轮的台账')
})
test('test_gate_pairs_its_pywebview_ready_listener', () => {
// 桥可能晚于挂载就绪:必须等 pywebviewready,且卸载时配对摘掉
assert.ok(gate.includes("addEventListener('pywebviewready'"), '就绪前不判定,就绪后判一次')
assert.ok(gate.includes("removeEventListener('pywebviewready'"), '监听没有只加不摘的')
})
test('test_gate_is_mounted_once_at_app_root', () => {
assert.ok(appVue.includes('<ForceUpdateGate />'), '挂在根组件=登录页与首页一起覆盖(存量装机下次打开就吃到)')
assert.ok(appVue.includes("import ForceUpdateGate from '@/shared/components/ForceUpdateGate.vue'"))
const consumers = listSourceFiles(srcRoot).filter((file) => {
if (relative(srcRoot, file).split('\\').join('/').startsWith('shared/components/ForceUpdateGate.vue')) return false
return readFileSync(file, 'utf8').includes('ForceUpdateGate')
})
assert.equal(consumers.length, 1, `ForceUpdateGate 的消费者必须只有 App.vue,实测 ${consumers.length} 处`)
})