From 917740ca07bed7908b7f6b59531a6a31b3e37c96 Mon Sep 17 00:00:00 2001
From: digua <i@digua.me>
Date: Thu, 30 Jul 2026 16:01:18 +0800
Subject: [PATCH] fix(home): prioritize agreement before changelog

Run the automatic changelog check only after the current agreement is already accepted or the user accepts it during startup. This prevents upgraded users from seeing overlapping modals and marking release notes as read too early.
---
 src/components/home/AgreementModal.vue     |  5 +++++
 src/components/home/ChangelogModal.vue     | 14 ++------------
 src/components/home/onboardingFlow.test.ts | 16 +++++++++++++++-
 src/components/home/onboardingFlow.ts      | 16 ++++++++++++++++
 src/pages/home/index.vue                   | 17 ++++++++++++++---
 5 files changed, 52 insertions(+), 16 deletions(-)

diff --git a/src/components/home/AgreementModal.vue b/src/components/home/AgreementModal.vue
index d75f2347..e0c0cd2d 100644
--- a/src/components/home/AgreementModal.vue
+++ b/src/components/home/AgreementModal.vue
@@ -13,6 +13,10 @@ const { t } = useI18n()
 const settingsStore = useSettingsStore()
 const { locale } = storeToRefs(settingsStore)
 
+const emit = defineEmits<{
+  accepted: []
+}>()
+
 const AGREEMENT_VERSION = '3.0'
 const AGREEMENT_KEY = 'chatlab_agreement_version'
 
@@ -51,6 +55,7 @@ const renderedContent = computed(() => md.render(agreementText.value))
 function handleAgree() {
   localStorage.setItem(AGREEMENT_KEY, AGREEMENT_VERSION)
   isOpen.value = false
+  emit('accepted')
 }
 
 function handleDisagree() {
diff --git a/src/components/home/ChangelogModal.vue b/src/components/home/ChangelogModal.vue
index 37bac4fe..10404fbe 100644
--- a/src/components/home/ChangelogModal.vue
+++ b/src/components/home/ChangelogModal.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, watch, onMounted } from 'vue'
+import { ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { storeToRefs } from 'pinia'
 import { useSettingsStore } from '@/stores/settings'
@@ -36,7 +36,6 @@ const hoveredVersion = ref<string | null>(null)
 const currentAppVersion = ref<string | null>(null)
 
 const CHANGELOG_READ_KEY = 'chatlab_changelog_read_version'
-const AGREEMENT_KEY = 'chatlab_agreement_version'
 
 // summary 的白名单配置（可按需扩展）
 const SUMMARY_SANITIZE_OPTIONS = {
@@ -133,10 +132,6 @@ function markVersionAsRead(version: string) {
 // 检查是否需要显示新版本日志（冷启动时自动检查）
 async function checkNewVersion() {
   try {
-    if (!localStorage.getItem(AGREEMENT_KEY)) {
-      return
-    }
-
     // 1. 获取当前软件版本号
     const rawVersion = await usePlatformService().getVersion()
     const currentVersion = normalizeChangelogVersion(rawVersion)
@@ -224,12 +219,7 @@ function getLatestVersion() {
   return changelogs.value[0]?.version || null
 }
 
-// 组件挂载时检查新版本
-onMounted(() => {
-  checkNewVersion()
-})
-
-defineExpose({ open, openWithData, close, fetchChangelogs, getLatestVersion })
+defineExpose({ open, openWithData, close, fetchChangelogs, getLatestVersion, checkNewVersion })
 </script>
 
 <template>
diff --git a/src/components/home/onboardingFlow.test.ts b/src/components/home/onboardingFlow.test.ts
index eb00d307..2d4d1d57 100644
--- a/src/components/home/onboardingFlow.test.ts
+++ b/src/components/home/onboardingFlow.test.ts
@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
 
-import { resolveLanguageBootstrap } from './onboardingFlow'
+import { resolveLanguageBootstrap, resolvePostLanguageBootstrap } from './onboardingFlow'
 
 test('新用户没有保存语言时应先打开语言选择，不继续后续弹窗流程', () => {
   assert.deepEqual(resolveLanguageBootstrap(''), {
@@ -16,3 +16,17 @@ test('已有保存语言时应跳过语言选择并继续后续弹窗流程', ()
     shouldContinue: true,
   })
 })
+
+test('已接受旧版协议的用户应优先确认当前协议，不检查更新日志', () => {
+  assert.deepEqual(resolvePostLanguageBootstrap(true), {
+    shouldOpenAgreement: true,
+    shouldCheckChangelog: false,
+  })
+})
+
+test('已接受当前协议的用户才可以检查更新日志', () => {
+  assert.deepEqual(resolvePostLanguageBootstrap(false), {
+    shouldOpenAgreement: false,
+    shouldCheckChangelog: true,
+  })
+})
diff --git a/src/components/home/onboardingFlow.ts b/src/components/home/onboardingFlow.ts
index b20afe70..cb6823cb 100644
--- a/src/components/home/onboardingFlow.ts
+++ b/src/components/home/onboardingFlow.ts
@@ -3,6 +3,11 @@ export interface LanguageBootstrapResult {
   shouldContinue: boolean
 }
 
+export interface PostLanguageBootstrapResult {
+  shouldOpenAgreement: boolean
+  shouldCheckChangelog: boolean
+}
+
 /**
  * 根据后端保存的语言配置决定首次启动弹窗流程。
  * 空语言代表新用户，需要先完成语言选择，避免用户协议和语言弹窗同时打开。
@@ -14,3 +19,14 @@ export function resolveLanguageBootstrap(savedLocale: string | null | undefined)
     shouldContinue: hasSavedLocale,
   }
 }
+
+/**
+ * Keep the mandatory agreement ahead of optional startup content.
+ * Changelog checks may resume only after the current agreement is accepted.
+ */
+export function resolvePostLanguageBootstrap(needsAgreement: boolean): PostLanguageBootstrapResult {
+  return {
+    shouldOpenAgreement: needsAgreement,
+    shouldCheckChangelog: !needsAgreement,
+  }
+}
diff --git a/src/pages/home/index.vue b/src/pages/home/index.vue
index 9c13e7fd..2b75e15a 100644
--- a/src/pages/home/index.vue
+++ b/src/pages/home/index.vue
@@ -6,6 +6,7 @@ import { getChatlabSiteLocalePath } from '@/utils/chatlabSiteLocale'
 import logoSvg from '@/assets/images/logo.svg'
 import LanguageSelectModal from '@/components/home/LanguageSelectModal.vue'
 import AgreementModal from '@/components/home/AgreementModal.vue'
+import { resolvePostLanguageBootstrap } from '@/components/home/onboardingFlow'
 import MigrationModal from './components/MigrationModal.vue'
 import ImportArea from '@/components/import/ImportArea.vue'
 import ImportTabSelector from './components/import/ImportTabSelector.vue'
@@ -35,11 +36,21 @@ const agreementModalRef = ref<InstanceType<typeof AgreementModal> | null>(null)
 
 // 语言选择完成后，检查是否需要显示协议弹窗
 function onLanguageSelectDone() {
-  if (agreementModalRef.value?.needsAgreement()) {
-    agreementModalRef.value.open()
+  const agreementModal = agreementModalRef.value
+  if (!agreementModal) return
+
+  const bootstrap = resolvePostLanguageBootstrap(agreementModal.needsAgreement())
+  if (bootstrap.shouldOpenAgreement) {
+    agreementModal.open()
+  } else if (bootstrap.shouldCheckChangelog) {
+    changelogModalRef.value?.checkNewVersion()
   }
 }
 
+function onAgreementAccepted() {
+  changelogModalRef.value?.checkNewVersion()
+}
+
 // 打开版本日志弹窗（手动点击时调用）
 async function openChangelog() {
   changelogModalRef.value?.open()
@@ -120,7 +131,7 @@ const tutorialExportUrl = computed(() => {
     <LanguageSelectModal @done="onLanguageSelectDone" />
 
     <!-- 用户协议弹窗 -->
-    <AgreementModal ref="agreementModalRef" />
+    <AgreementModal ref="agreementModalRef" @accepted="onAgreementAccepted" />
 
     <!-- 数据库迁移弹窗 -->
     <MigrationModal />