diff --git a/frontend-vue/src/App.vue b/frontend-vue/src/App.vue index 4d1ddcafb..6425587fd 100644 --- a/frontend-vue/src/App.vue +++ b/frontend-vue/src/App.vue @@ -2,6 +2,7 @@ + @@ -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' diff --git a/frontend-vue/src/shared/client-force-update.ts b/frontend-vue/src/shared/client-force-update.ts new file mode 100644 index 000000000..9fa71a8d5 --- /dev/null +++ b/frontend-vue/src/shared/client-force-update.ts @@ -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 } +} diff --git a/frontend-vue/src/shared/components/ForceUpdateGate.vue b/frontend-vue/src/shared/components/ForceUpdateGate.vue new file mode 100644 index 000000000..8bfde52ad --- /dev/null +++ b/frontend-vue/src/shared/components/ForceUpdateGate.vue @@ -0,0 +1,190 @@ + + + + + diff --git a/frontend-vue/src/shared/composables/useVersionUpdate.ts b/frontend-vue/src/shared/composables/useVersionUpdate.ts index 8bf8f03f9..7f60d3fb3 100644 --- a/frontend-vue/src/shared/composables/useVersionUpdate.ts +++ b/frontend-vue/src/shared/composables/useVersionUpdate.ts @@ -342,6 +342,7 @@ export function useVersionUpdate() { loadCurrentVersion, loadVersions, runCheck, + startUpdate, doUpdate, doUpdateVersion, } diff --git a/frontend-vue/tests/client-force-update.test.ts b/frontend-vue/tests/client-force-update.test.ts new file mode 100644 index 000000000..69fe3db4a --- /dev/null +++ b/frontend-vue/tests/client-force-update.test.ts @@ -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(''), '挂在根组件=登录页与首页一起覆盖(存量装机下次打开就吃到)') + 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} 处`) +})