Merge pull request #315 from mt21625457/main

perf(前端): 优化页面加载性能和用户体验 和 修复静态 import 导致入口文件膨胀问题

deploy/Caddyfile

@@ -33,6 +33,22 @@
 
 # 修改为你的域名
 example.com {
+	# =========================================================================
+	# 静态资源长期缓存（高优先级，放在最前面）
+	# 带 hash 的文件可以永久缓存，浏览器和 CDN 都会缓存
+	# =========================================================================
+	@static {
+		path /assets/*
+		path /logo.png
+		path /favicon.ico
+	}
+	header @static {
+		Cache-Control "public, max-age=31536000, immutable"
+		# 移除可能干扰缓存的头
+		-Pragma
+		-Expires
+	}
+
 	# =========================================================================
 	# TLS 安全配置
 	# =========================================================================

frontend/package.json

@@ -9,7 +9,10 @@
     "preview": "vite preview",
     "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix",
     "lint:check": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts",
-    "typecheck": "vue-tsc --noEmit"
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@lobehub/icons": "^4.0.2",
@@ -29,17 +32,21 @@
     "@types/file-saver": "^2.0.7",
     "@types/mdx": "^2.0.13",
     "@types/node": "^20.10.5",
-    "@vitejs/plugin-vue": "^5.2.3",
-    "autoprefixer": "^10.4.16",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
+    "@vitejs/plugin-vue": "^5.2.3",
+    "@vitest/coverage-v8": "^2.1.9",
+    "@vue/test-utils": "^2.4.6",
+    "autoprefixer": "^10.4.16",
     "eslint": "^8.57.0",
     "eslint-plugin-vue": "^9.25.0",
+    "jsdom": "^24.1.3",
     "postcss": "^8.4.32",
     "tailwindcss": "^3.4.0",
     "typescript": "~5.6.0",
     "vite": "^5.0.10",
     "vite-plugin-checker": "^0.9.1",
+    "vitest": "^2.1.9",
     "vue-tsc": "^2.2.0"
   }
 }

frontend/src/App.vue

@@ -2,6 +2,7 @@
 import { RouterView, useRouter, useRoute } from 'vue-router'
 import { onMounted, watch } from 'vue'
 import Toast from '@/components/common/Toast.vue'
+import NavigationProgress from '@/components/common/NavigationProgress.vue'
 import { useAppStore, useAuthStore, useSubscriptionStore } from '@/stores'
 import { getSetupStatus } from '@/api/setup'
 
@@ -84,6 +85,7 @@ onMounted(async () => {
 </script>
 
 <template>
+  <NavigationProgress />
   <RouterView />
   <Toast />
 </template>

frontend/src/__tests__/integration/navigation.spec.ts

@@ -0,0 +1,478 @@
+/**
+ * 导航集成测试
+ * 测试完整的页面导航流程、预加载和错误恢复机制
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { createRouter, createWebHistory, type Router } from 'vue-router'
+import { createPinia, setActivePinia } from 'pinia'
+import { mount, flushPromises } from '@vue/test-utils'
+import { defineComponent, h, nextTick } from 'vue'
+import { useNavigationLoadingState, _resetNavigationLoadingInstance } from '@/composables/useNavigationLoading'
+import { useRoutePrefetch } from '@/composables/useRoutePrefetch'
+
+// Mock 视图组件
+const MockDashboard = defineComponent({
+  name: 'MockDashboard',
+  render() {
+    return h('div', { class: 'dashboard' }, 'Dashboard')
+  }
+})
+
+const MockKeys = defineComponent({
+  name: 'MockKeys',
+  render() {
+    return h('div', { class: 'keys' }, 'Keys')
+  }
+})
+
+const MockUsage = defineComponent({
+  name: 'MockUsage',
+  render() {
+    return h('div', { class: 'usage' }, 'Usage')
+  }
+})
+
+// Mock stores
+vi.mock('@/stores/auth', () => ({
+  useAuthStore: () => ({
+    isAuthenticated: true,
+    isAdmin: false,
+    isSimpleMode: false,
+    checkAuth: vi.fn()
+  })
+}))
+
+vi.mock('@/stores/app', () => ({
+  useAppStore: () => ({
+    siteName: 'Test Site'
+  })
+}))
+
+// 创建测试路由
+function createTestRouter(): Router {
+  return createRouter({
+    history: createWebHistory(),
+    routes: [
+      {
+        path: '/',
+        redirect: '/dashboard'
+      },
+      {
+        path: '/dashboard',
+        name: 'Dashboard',
+        component: MockDashboard,
+        meta: { requiresAuth: true, title: 'Dashboard' }
+      },
+      {
+        path: '/keys',
+        name: 'Keys',
+        component: MockKeys,
+        meta: { requiresAuth: true, title: 'Keys' }
+      },
+      {
+        path: '/usage',
+        name: 'Usage',
+        component: MockUsage,
+        meta: { requiresAuth: true, title: 'Usage' }
+      }
+    ]
+  })
+}
+
+// 测试用 App 组件
+const TestApp = defineComponent({
+  name: 'TestApp',
+  setup() {
+    return () => h('div', { id: 'app' }, [h('router-view')])
+  }
+})
+
+describe('Navigation Integration Tests', () => {
+  let router: Router
+  let originalRequestIdleCallback: typeof window.requestIdleCallback
+  let originalCancelIdleCallback: typeof window.cancelIdleCallback
+
+  beforeEach(() => {
+    // 设置 Pinia
+    setActivePinia(createPinia())
+
+    // 重置导航加载状态
+    _resetNavigationLoadingInstance()
+
+    // 创建新的路由实例
+    router = createTestRouter()
+
+    // Mock requestIdleCallback
+    originalRequestIdleCallback = window.requestIdleCallback
+    originalCancelIdleCallback = window.cancelIdleCallback
+
+    vi.stubGlobal('requestIdleCallback', (cb: IdleRequestCallback) => {
+      const id = setTimeout(() => cb({ didTimeout: false, timeRemaining: () => 50 }), 0)
+      return id
+    })
+    vi.stubGlobal('cancelIdleCallback', (id: number) => clearTimeout(id))
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    window.requestIdleCallback = originalRequestIdleCallback
+    window.cancelIdleCallback = originalCancelIdleCallback
+  })
+
+  describe('完整页面导航流程', () => {
+    it('导航时应该触发加载状态变化', async () => {
+      const navigationLoading = useNavigationLoadingState()
+
+      // 初始状态
+      expect(navigationLoading.isLoading.value).toBe(false)
+
+      // 挂载应用
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [router]
+        }
+      })
+
+      // 等待路由初始化
+      await router.isReady()
+      await flushPromises()
+
+      // 导航到 /dashboard
+      await router.push('/dashboard')
+      await flushPromises()
+      await nextTick()
+
+      // 导航结束后状态应该重置
+      expect(navigationLoading.isLoading.value).toBe(false)
+
+      wrapper.unmount()
+    })
+
+    it('导航到新页面应该正确渲染组件', async () => {
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [router]
+        }
+      })
+
+      await router.isReady()
+      await router.push('/dashboard')
+      await flushPromises()
+      await nextTick()
+
+      // 检查当前路由
+      expect(router.currentRoute.value.path).toBe('/dashboard')
+
+      wrapper.unmount()
+    })
+
+    it('连续快速导航应该正确处理路由状态', async () => {
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [router]
+        }
+      })
+
+      await router.isReady()
+      await router.push('/dashboard')
+
+      // 快速连续导航
+      router.push('/keys')
+      router.push('/usage')
+      router.push('/dashboard')
+
+      await flushPromises()
+      await nextTick()
+
+      // 应该最终停在 /dashboard
+      expect(router.currentRoute.value.path).toBe('/dashboard')
+
+      wrapper.unmount()
+    })
+  })
+
+  describe('路由预加载', () => {
+    it('导航后应该触发相关路由预加载', async () => {
+      const routePrefetch = useRoutePrefetch()
+      const triggerSpy = vi.spyOn(routePrefetch, 'triggerPrefetch')
+
+      // 设置 afterEach 守卫
+      router.afterEach((to) => {
+        routePrefetch.triggerPrefetch(to)
+      })
+
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [router]
+        }
+      })
+
+      await router.isReady()
+      await router.push('/dashboard')
+      await flushPromises()
+
+      // 应该触发预加载
+      expect(triggerSpy).toHaveBeenCalled()
+
+      wrapper.unmount()
+    })
+
+    it('已预加载的路由不应重复预加载', async () => {
+      const routePrefetch = useRoutePrefetch()
+
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [router]
+        }
+      })
+
+      await router.isReady()
+      await router.push('/dashboard')
+      await flushPromises()
+
+      // 手动触发预加载
+      routePrefetch.triggerPrefetch(router.currentRoute.value)
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      const prefetchedCount = routePrefetch.prefetchedRoutes.value.size
+
+      // 再次触发相同路由预加载
+      routePrefetch.triggerPrefetch(router.currentRoute.value)
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      // 预加载数量不应增加
+      expect(routePrefetch.prefetchedRoutes.value.size).toBe(prefetchedCount)
+
+      wrapper.unmount()
+    })
+
+    it('路由变化时应取消之前的预加载任务', async () => {
+      const routePrefetch = useRoutePrefetch()
+
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [router]
+        }
+      })
+
+      await router.isReady()
+
+      // 触发预加载
+      routePrefetch.triggerPrefetch(router.currentRoute.value)
+
+      // 立即导航到新路由（这会在内部调用 cancelPendingPrefetch）
+      routePrefetch.triggerPrefetch({ path: '/keys' } as any)
+
+      // 由于 triggerPrefetch 内部调用 cancelPendingPrefetch，检查是否有预加载被正确管理
+      expect(routePrefetch.prefetchedRoutes.value.size).toBeLessThanOrEqual(2)
+
+      wrapper.unmount()
+    })
+  })
+
+  describe('Chunk 加载错误恢复', () => {
+    it('chunk 加载失败应该被正确捕获', async () => {
+      const errorHandler = vi.fn()
+
+      // 创建带错误处理的路由
+      const errorRouter = createRouter({
+        history: createWebHistory(),
+        routes: [
+          {
+            path: '/dashboard',
+            name: 'Dashboard',
+            component: MockDashboard
+          },
+          {
+            path: '/error-page',
+            name: 'ErrorPage',
+            // 模拟加载失败的组件
+            component: () => Promise.reject(new Error('Failed to fetch dynamically imported module'))
+          }
+        ]
+      })
+
+      errorRouter.onError(errorHandler)
+
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [errorRouter]
+        }
+      })
+
+      await errorRouter.isReady()
+      await errorRouter.push('/dashboard')
+      await flushPromises()
+
+      // 尝试导航到会失败的页面
+      try {
+        await errorRouter.push('/error-page')
+      } catch {
+        // 预期会失败
+      }
+
+      await flushPromises()
+
+      // 错误处理器应该被调用
+      expect(errorHandler).toHaveBeenCalled()
+
+      wrapper.unmount()
+    })
+
+    it('chunk 加载错误应该包含正确的错误信息', async () => {
+      let capturedError: Error | null = null
+
+      const errorRouter = createRouter({
+        history: createWebHistory(),
+        routes: [
+          {
+            path: '/dashboard',
+            name: 'Dashboard',
+            component: MockDashboard
+          },
+          {
+            path: '/chunk-error',
+            name: 'ChunkError',
+            component: () => {
+              const error = new Error('Loading chunk failed')
+              error.name = 'ChunkLoadError'
+              return Promise.reject(error)
+            }
+          }
+        ]
+      })
+
+      errorRouter.onError((error) => {
+        capturedError = error
+      })
+
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [errorRouter]
+        }
+      })
+
+      await errorRouter.isReady()
+
+      try {
+        await errorRouter.push('/chunk-error')
+      } catch {
+        // 预期会失败
+      }
+
+      await flushPromises()
+
+      expect(capturedError).not.toBeNull()
+      expect(capturedError!.name).toBe('ChunkLoadError')
+
+      wrapper.unmount()
+    })
+  })
+
+  describe('导航状态管理', () => {
+    it('导航开始时 isLoading 应该变为 true', async () => {
+      const navigationLoading = useNavigationLoadingState()
+
+      // 创建一个延迟加载的组件来模拟真实场景
+      const DelayedComponent = defineComponent({
+        name: 'DelayedComponent',
+        async setup() {
+          await new Promise((resolve) => setTimeout(resolve, 50))
+          return () => h('div', 'Delayed')
+        }
+      })
+
+      const delayRouter = createRouter({
+        history: createWebHistory(),
+        routes: [
+          {
+            path: '/dashboard',
+            name: 'Dashboard',
+            component: MockDashboard
+          },
+          {
+            path: '/delayed',
+            name: 'Delayed',
+            component: DelayedComponent
+          }
+        ]
+      })
+
+      // 设置导航守卫
+      delayRouter.beforeEach(() => {
+        navigationLoading.startNavigation()
+      })
+
+      delayRouter.afterEach(() => {
+        navigationLoading.endNavigation()
+      })
+
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [delayRouter]
+        }
+      })
+
+      await delayRouter.isReady()
+      await delayRouter.push('/dashboard')
+      await flushPromises()
+
+      // 导航结束后 isLoading 应该为 false
+      expect(navigationLoading.isLoading.value).toBe(false)
+
+      wrapper.unmount()
+    })
+
+    it('导航取消时应该正确重置状态', async () => {
+      const navigationLoading = useNavigationLoadingState()
+
+      const testRouter = createRouter({
+        history: createWebHistory(),
+        routes: [
+          {
+            path: '/dashboard',
+            name: 'Dashboard',
+            component: MockDashboard
+          },
+          {
+            path: '/keys',
+            name: 'Keys',
+            component: MockKeys,
+            beforeEnter: (_to, _from, next) => {
+              // 模拟导航取消
+              next(false)
+            }
+          }
+        ]
+      })
+
+      testRouter.beforeEach(() => {
+        navigationLoading.startNavigation()
+      })
+
+      testRouter.afterEach(() => {
+        navigationLoading.endNavigation()
+      })
+
+      const wrapper = mount(TestApp, {
+        global: {
+          plugins: [testRouter]
+        }
+      })
+
+      await testRouter.isReady()
+      await testRouter.push('/dashboard')
+      await flushPromises()
+
+      // 尝试导航到被取消的路由
+      await testRouter.push('/keys').catch(() => {})
+      await flushPromises()
+
+      // 导航被取消后，状态应该被重置
+      // 注意：由于 afterEach 仍然会被调用，isLoading 应该为 false
+      expect(navigationLoading.isLoading.value).toBe(false)
+
+      wrapper.unmount()
+    })
+  })
+})

frontend/src/__tests__/setup.ts

@@ -0,0 +1,45 @@
+/**
+ * Vitest 测试环境设置
+ * 提供全局 mock 和测试工具
+ */
+import { config } from '@vue/test-utils'
+import { vi } from 'vitest'
+
+// Mock requestIdleCallback (Safari < 15 不支持)
+if (typeof globalThis.requestIdleCallback === 'undefined') {
+  globalThis.requestIdleCallback = ((callback: IdleRequestCallback) => {
+    return window.setTimeout(() => callback({ didTimeout: false, timeRemaining: () => 50 }), 1)
+  }) as unknown as typeof requestIdleCallback
+}
+
+if (typeof globalThis.cancelIdleCallback === 'undefined') {
+  globalThis.cancelIdleCallback = ((id: number) => {
+    window.clearTimeout(id)
+  }) as unknown as typeof cancelIdleCallback
+}
+
+// Mock IntersectionObserver
+class MockIntersectionObserver {
+  observe = vi.fn()
+  disconnect = vi.fn()
+  unobserve = vi.fn()
+}
+
+globalThis.IntersectionObserver = MockIntersectionObserver as unknown as typeof IntersectionObserver
+
+// Mock ResizeObserver
+class MockResizeObserver {
+  observe = vi.fn()
+  disconnect = vi.fn()
+  unobserve = vi.fn()
+}
+
+globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver
+
+// Vue Test Utils 全局配置
+config.global.stubs = {
+  // 可以在这里添加全局 stub
+}
+
+// 设置全局测试超时
+vi.setConfig({ testTimeout: 10000 })

frontend/src/components/common/NavigationProgress.vue

@@ -0,0 +1,109 @@
+<script setup lang="ts">
+/**
+ * 导航进度条组件
+ * 在页面顶部显示加载进度，提供导航反馈
+ */
+import { computed } from 'vue'
+import { useNavigationLoadingState } from '@/composables/useNavigationLoading'
+
+const { isLoading } = useNavigationLoadingState()
+
+// 进度条可见性
+const isVisible = computed(() => isLoading.value)
+</script>
+
+<template>
+  <Transition name="progress-fade">
+    <div
+      v-show="isVisible"
+      class="navigation-progress"
+      role="progressbar"
+      aria-label="Loading"
+      aria-valuenow="0"
+      aria-valuemin="0"
+      aria-valuemax="100"
+    >
+      <div class="navigation-progress-bar" />
+    </div>
+  </Transition>
+</template>
+
+<style scoped>
+.navigation-progress {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 3px;
+  z-index: 9999;
+  overflow: hidden;
+  background: transparent;
+}
+
+.navigation-progress-bar {
+  height: 100%;
+  width: 100%;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    theme('colors.primary.400') 20%,
+    theme('colors.primary.500') 50%,
+    theme('colors.primary.400') 80%,
+    transparent 100%
+  );
+  animation: progress-slide 1.5s ease-in-out infinite;
+}
+
+/* 暗色模式下的进度条颜色 */
+:root.dark .navigation-progress-bar {
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    theme('colors.primary.500') 20%,
+    theme('colors.primary.400') 50%,
+    theme('colors.primary.500') 80%,
+    transparent 100%
+  );
+}
+
+/* 进度条滑动动画 */
+@keyframes progress-slide {
+  0% {
+    transform: translateX(-100%);
+  }
+  100% {
+    transform: translateX(100%);
+  }
+}
+
+/* 淡入淡出过渡 */
+.progress-fade-enter-active {
+  transition: opacity 0.15s ease-out;
+}
+
+.progress-fade-leave-active {
+  transition: opacity 0.3s ease-out;
+}
+
+.progress-fade-enter-from,
+.progress-fade-leave-to {
+  opacity: 0;
+}
+
+/* 减少动画模式 */
+@media (prefers-reduced-motion: reduce) {
+  .navigation-progress-bar {
+    animation: progress-pulse 2s ease-in-out infinite;
+  }
+
+  @keyframes progress-pulse {
+    0%,
+    100% {
+      opacity: 0.4;
+    }
+    50% {
+      opacity: 1;
+    }
+  }
+}
+</style>

frontend/src/components/common/__tests__/NavigationProgress.spec.ts

@@ -0,0 +1,83 @@
+/**
+ * NavigationProgress 组件单元测试
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount } from '@vue/test-utils'
+import { ref } from 'vue'
+import NavigationProgress from '../../common/NavigationProgress.vue'
+
+// Mock useNavigationLoadingState
+const mockIsLoading = ref(false)
+
+vi.mock('@/composables/useNavigationLoading', () => ({
+  useNavigationLoadingState: () => ({
+    isLoading: mockIsLoading
+  })
+}))
+
+describe('NavigationProgress', () => {
+  beforeEach(() => {
+    mockIsLoading.value = false
+  })
+
+  it('isLoading=false 时进度条应该隐藏', () => {
+    mockIsLoading.value = false
+    const wrapper = mount(NavigationProgress)
+
+    const progressBar = wrapper.find('.navigation-progress')
+    // v-show 会设置 display: none
+    expect(progressBar.isVisible()).toBe(false)
+  })
+
+  it('isLoading=true 时进度条应该可见', async () => {
+    mockIsLoading.value = true
+    const wrapper = mount(NavigationProgress)
+
+    await wrapper.vm.$nextTick()
+
+    const progressBar = wrapper.find('.navigation-progress')
+    expect(progressBar.exists()).toBe(true)
+    expect(progressBar.isVisible()).toBe(true)
+  })
+
+  it('应该有正确的 ARIA 属性', () => {
+    mockIsLoading.value = true
+    const wrapper = mount(NavigationProgress)
+
+    const progressBar = wrapper.find('.navigation-progress')
+    expect(progressBar.attributes('role')).toBe('progressbar')
+    expect(progressBar.attributes('aria-label')).toBe('Loading')
+    expect(progressBar.attributes('aria-valuemin')).toBe('0')
+    expect(progressBar.attributes('aria-valuemax')).toBe('100')
+  })
+
+  it('进度条应该有动画 class', () => {
+    mockIsLoading.value = true
+    const wrapper = mount(NavigationProgress)
+
+    const bar = wrapper.find('.navigation-progress-bar')
+    expect(bar.exists()).toBe(true)
+  })
+
+  it('应该正确响应 isLoading 状态变化', async () => {
+    // 测试初始状态为 false
+    mockIsLoading.value = false
+    const wrapper = mount(NavigationProgress)
+    await wrapper.vm.$nextTick()
+
+    // 初始状态隐藏
+    expect(wrapper.find('.navigation-progress').isVisible()).toBe(false)
+
+    // 卸载后重新挂载以测试 true 状态
+    wrapper.unmount()
+
+    // 改变为 true 后重新挂载
+    mockIsLoading.value = true
+    const wrapper2 = mount(NavigationProgress)
+    await wrapper2.vm.$nextTick()
+    expect(wrapper2.find('.navigation-progress').isVisible()).toBe(true)
+
+    // 清理
+    wrapper2.unmount()
+  })
+})

frontend/src/composables/__tests__/useNavigationLoading.spec.ts

@@ -0,0 +1,176 @@
+/**
+ * useNavigationLoading 组合式函数单元测试
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  useNavigationLoading,
+  _resetNavigationLoadingInstance
+} from '../useNavigationLoading'
+
+describe('useNavigationLoading', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    _resetNavigationLoadingInstance()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('startNavigation', () => {
+    it('导航开始时 isNavigating 应变为 true', () => {
+      const { isNavigating, startNavigation } = useNavigationLoading()
+
+      expect(isNavigating.value).toBe(false)
+
+      startNavigation()
+
+      expect(isNavigating.value).toBe(true)
+    })
+
+    it('导航开始后延迟显示加载指示器（防闪烁）', () => {
+      const { isLoading, startNavigation, ANTI_FLICKER_DELAY } = useNavigationLoading()
+
+      startNavigation()
+
+      // 立即检查，不应该显示
+      expect(isLoading.value).toBe(false)
+
+      // 经过防闪烁延迟后应该显示
+      vi.advanceTimersByTime(ANTI_FLICKER_DELAY)
+      expect(isLoading.value).toBe(true)
+    })
+  })
+
+  describe('endNavigation', () => {
+    it('导航结束时 isLoading 应变为 false', () => {
+      const { isLoading, startNavigation, endNavigation, ANTI_FLICKER_DELAY } = useNavigationLoading()
+
+      startNavigation()
+      vi.advanceTimersByTime(ANTI_FLICKER_DELAY)
+      expect(isLoading.value).toBe(true)
+
+      endNavigation()
+      expect(isLoading.value).toBe(false)
+    })
+
+    it('导航结束时 isNavigating 应变为 false', () => {
+      const { isNavigating, startNavigation, endNavigation } = useNavigationLoading()
+
+      startNavigation()
+      expect(isNavigating.value).toBe(true)
+
+      endNavigation()
+      expect(isNavigating.value).toBe(false)
+    })
+  })
+
+  describe('快速导航（< 100ms）防闪烁', () => {
+    it('快速导航不应触发显示加载指示器', () => {
+      const { isLoading, startNavigation, endNavigation, ANTI_FLICKER_DELAY } = useNavigationLoading()
+
+      startNavigation()
+
+      // 在防闪烁延迟之前结束导航
+      vi.advanceTimersByTime(ANTI_FLICKER_DELAY - 50)
+      endNavigation()
+
+      // 不应该显示加载指示器
+      expect(isLoading.value).toBe(false)
+
+      // 即使继续等待也不应该显示
+      vi.advanceTimersByTime(100)
+      expect(isLoading.value).toBe(false)
+    })
+  })
+
+  describe('cancelNavigation', () => {
+    it('导航取消时应正确重置状态', () => {
+      const { isLoading, startNavigation, cancelNavigation, ANTI_FLICKER_DELAY } = useNavigationLoading()
+
+      startNavigation()
+      vi.advanceTimersByTime(ANTI_FLICKER_DELAY / 2)
+
+      cancelNavigation()
+
+      // 取消后不应该触发显示
+      vi.advanceTimersByTime(ANTI_FLICKER_DELAY)
+      expect(isLoading.value).toBe(false)
+    })
+  })
+
+  describe('getNavigationDuration', () => {
+    it('应该返回正确的导航持续时间', () => {
+      const { startNavigation, getNavigationDuration } = useNavigationLoading()
+
+      expect(getNavigationDuration()).toBeNull()
+
+      startNavigation()
+      vi.advanceTimersByTime(500)
+
+      const duration = getNavigationDuration()
+      expect(duration).toBe(500)
+    })
+
+    it('导航结束后应返回 null', () => {
+      const { startNavigation, endNavigation, getNavigationDuration } = useNavigationLoading()
+
+      startNavigation()
+      vi.advanceTimersByTime(500)
+      endNavigation()
+
+      expect(getNavigationDuration()).toBeNull()
+    })
+  })
+
+  describe('resetState', () => {
+    it('应该重置所有状态', () => {
+      const { isLoading, isNavigating, startNavigation, resetState, ANTI_FLICKER_DELAY } = useNavigationLoading()
+
+      startNavigation()
+      vi.advanceTimersByTime(ANTI_FLICKER_DELAY)
+
+      expect(isLoading.value).toBe(true)
+      expect(isNavigating.value).toBe(true)
+
+      resetState()
+
+      expect(isLoading.value).toBe(false)
+      expect(isNavigating.value).toBe(false)
+    })
+  })
+
+  describe('连续导航场景', () => {
+    it('连续快速导航应正确处理状态', () => {
+      const { isLoading, startNavigation, cancelNavigation, endNavigation, ANTI_FLICKER_DELAY } = useNavigationLoading()
+
+      // 第一次导航
+      startNavigation()
+      vi.advanceTimersByTime(30)
+
+      // 第二次导航（取消第一次）
+      cancelNavigation()
+      startNavigation()
+      vi.advanceTimersByTime(30)
+
+      // 第三次导航（取消第二次）
+      cancelNavigation()
+      startNavigation()
+
+      // 这次等待足够长时间
+      vi.advanceTimersByTime(ANTI_FLICKER_DELAY)
+      expect(isLoading.value).toBe(true)
+
+      // 结束导航
+      endNavigation()
+      expect(isLoading.value).toBe(false)
+    })
+  })
+
+  describe('ANTI_FLICKER_DELAY 常量', () => {
+    it('应该为 100ms', () => {
+      const { ANTI_FLICKER_DELAY } = useNavigationLoading()
+      expect(ANTI_FLICKER_DELAY).toBe(100)
+    })
+  })
+})

frontend/src/composables/__tests__/useRoutePrefetch.spec.ts

@@ -0,0 +1,244 @@
+/**
+ * useRoutePrefetch 组合式函数单元测试
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import type { RouteLocationNormalized, Router, RouteRecordNormalized } from 'vue-router'
+
+import { useRoutePrefetch, _adminPrefetchMap, _userPrefetchMap } from '../useRoutePrefetch'
+
+// Mock 路由对象
+const createMockRoute = (path: string): RouteLocationNormalized => ({
+  path,
+  name: undefined,
+  params: {},
+  query: {},
+  hash: '',
+  fullPath: path,
+  matched: [],
+  meta: {},
+  redirectedFrom: undefined
+})
+
+// Mock Router
+const createMockRouter = (): Router => {
+  const mockImportFn = vi.fn().mockResolvedValue({ default: {} })
+
+  const routes: Partial<RouteRecordNormalized>[] = [
+    { path: '/admin/dashboard', components: { default: mockImportFn } },
+    { path: '/admin/accounts', components: { default: mockImportFn } },
+    { path: '/admin/users', components: { default: mockImportFn } },
+    { path: '/admin/groups', components: { default: mockImportFn } },
+    { path: '/admin/subscriptions', components: { default: mockImportFn } },
+    { path: '/admin/redeem', components: { default: mockImportFn } },
+    { path: '/dashboard', components: { default: mockImportFn } },
+    { path: '/keys', components: { default: mockImportFn } },
+    { path: '/usage', components: { default: mockImportFn } },
+    { path: '/redeem', components: { default: mockImportFn } },
+    { path: '/profile', components: { default: mockImportFn } }
+  ]
+
+  return {
+    getRoutes: () => routes as RouteRecordNormalized[]
+  } as Router
+}
+
+describe('useRoutePrefetch', () => {
+  let originalRequestIdleCallback: typeof window.requestIdleCallback
+  let originalCancelIdleCallback: typeof window.cancelIdleCallback
+  let mockRouter: Router
+
+  beforeEach(() => {
+    mockRouter = createMockRouter()
+
+    // 保存原始函数
+    originalRequestIdleCallback = window.requestIdleCallback
+    originalCancelIdleCallback = window.cancelIdleCallback
+
+    // Mock requestIdleCallback 立即执行
+    vi.stubGlobal('requestIdleCallback', (cb: IdleRequestCallback) => {
+      const id = setTimeout(() => cb({ didTimeout: false, timeRemaining: () => 50 }), 0)
+      return id
+    })
+    vi.stubGlobal('cancelIdleCallback', (id: number) => clearTimeout(id))
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    // 恢复原始函数
+    window.requestIdleCallback = originalRequestIdleCallback
+    window.cancelIdleCallback = originalCancelIdleCallback
+  })
+
+  describe('_isAdminRoute', () => {
+    it('应该正确识别管理员路由', () => {
+      const { _isAdminRoute } = useRoutePrefetch(mockRouter)
+      expect(_isAdminRoute('/admin/dashboard')).toBe(true)
+      expect(_isAdminRoute('/admin/users')).toBe(true)
+      expect(_isAdminRoute('/admin/accounts')).toBe(true)
+    })
+
+    it('应该正确识别非管理员路由', () => {
+      const { _isAdminRoute } = useRoutePrefetch(mockRouter)
+      expect(_isAdminRoute('/dashboard')).toBe(false)
+      expect(_isAdminRoute('/keys')).toBe(false)
+      expect(_isAdminRoute('/usage')).toBe(false)
+    })
+  })
+
+  describe('_getPrefetchConfig', () => {
+    it('管理员 dashboard 应该返回正确的预加载配置', () => {
+      const { _getPrefetchConfig } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/admin/dashboard')
+      const config = _getPrefetchConfig(route)
+
+      expect(config).toHaveLength(2)
+    })
+
+    it('普通用户 dashboard 应该返回正确的预加载配置', () => {
+      const { _getPrefetchConfig } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/dashboard')
+      const config = _getPrefetchConfig(route)
+
+      expect(config).toHaveLength(2)
+    })
+
+    it('未定义的路由应该返回空数组', () => {
+      const { _getPrefetchConfig } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/unknown-route')
+      const config = _getPrefetchConfig(route)
+
+      expect(config).toHaveLength(0)
+    })
+  })
+
+  describe('triggerPrefetch', () => {
+    it('应该在浏览器空闲时触发预加载', async () => {
+      const { triggerPrefetch, prefetchedRoutes } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/admin/dashboard')
+
+      triggerPrefetch(route)
+
+      // 等待 requestIdleCallback 执行
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      expect(prefetchedRoutes.value.has('/admin/dashboard')).toBe(true)
+    })
+
+    it('应该避免重复预加载同一路由', async () => {
+      const { triggerPrefetch, prefetchedRoutes } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/admin/dashboard')
+
+      triggerPrefetch(route)
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      // 第二次触发
+      triggerPrefetch(route)
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      // 只应该预加载一次
+      expect(prefetchedRoutes.value.size).toBe(1)
+    })
+  })
+
+  describe('cancelPendingPrefetch', () => {
+    it('应该取消挂起的预加载任务', () => {
+      const { triggerPrefetch, cancelPendingPrefetch, prefetchedRoutes } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/admin/dashboard')
+
+      triggerPrefetch(route)
+      cancelPendingPrefetch()
+
+      // 不应该有预加载完成
+      expect(prefetchedRoutes.value.size).toBe(0)
+    })
+  })
+
+  describe('路由变化时取消之前的预加载', () => {
+    it('应该在路由变化时取消之前的预加载任务', async () => {
+      const { triggerPrefetch, prefetchedRoutes } = useRoutePrefetch(mockRouter)
+
+      // 触发第一个路由的预加载
+      triggerPrefetch(createMockRoute('/admin/dashboard'))
+
+      // 立即切换到另一个路由
+      triggerPrefetch(createMockRoute('/admin/users'))
+
+      // 等待执行
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      // 只有最后一个路由应该被预加载
+      expect(prefetchedRoutes.value.has('/admin/users')).toBe(true)
+    })
+  })
+
+  describe('resetPrefetchState', () => {
+    it('应该重置所有预加载状态', async () => {
+      const { triggerPrefetch, resetPrefetchState, prefetchedRoutes } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/admin/dashboard')
+
+      triggerPrefetch(route)
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      expect(prefetchedRoutes.value.size).toBeGreaterThan(0)
+
+      resetPrefetchState()
+
+      expect(prefetchedRoutes.value.size).toBe(0)
+    })
+  })
+
+  describe('预加载映射表', () => {
+    it('管理员预加载映射表应该包含正确的路由', () => {
+      expect(_adminPrefetchMap).toHaveProperty('/admin/dashboard')
+      expect(_adminPrefetchMap['/admin/dashboard']).toHaveLength(2)
+    })
+
+    it('用户预加载映射表应该包含正确的路由', () => {
+      expect(_userPrefetchMap).toHaveProperty('/dashboard')
+      expect(_userPrefetchMap['/dashboard']).toHaveLength(2)
+    })
+  })
+
+  describe('requestIdleCallback 超时处理', () => {
+    it('超时后仍能正常执行预加载', async () => {
+      // 模拟超时情况
+      vi.stubGlobal('requestIdleCallback', (cb: IdleRequestCallback, options?: IdleRequestOptions) => {
+        const timeout = options?.timeout || 2000
+        return setTimeout(() => cb({ didTimeout: true, timeRemaining: () => 0 }), timeout)
+      })
+
+      const { triggerPrefetch, prefetchedRoutes } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/dashboard')
+
+      triggerPrefetch(route)
+
+      // 等待超时执行
+      await new Promise((resolve) => setTimeout(resolve, 2100))
+
+      expect(prefetchedRoutes.value.has('/dashboard')).toBe(true)
+    })
+  })
+
+  describe('预加载失败处理', () => {
+    it('预加载失败时应该静默处理不影响页面功能', async () => {
+      const { triggerPrefetch } = useRoutePrefetch(mockRouter)
+      const route = createMockRoute('/admin/dashboard')
+
+      // 不应该抛出异常
+      expect(() => triggerPrefetch(route)).not.toThrow()
+    })
+  })
+
+  describe('无 router 时的行为', () => {
+    it('没有传入 router 时应该正常工作但不执行预加载', async () => {
+      const { triggerPrefetch, prefetchedRoutes } = useRoutePrefetch()
+      const route = createMockRoute('/admin/dashboard')
+
+      triggerPrefetch(route)
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      // 没有 router，无法获取组件，所以不会预加载
+      expect(prefetchedRoutes.value.size).toBe(0)
+    })
+  })
+})

frontend/src/composables/useNavigationLoading.ts

@@ -0,0 +1,132 @@
+/**
+ * 导航加载状态组合式函数
+ * 管理路由切换时的加载状态，支持防闪烁逻辑
+ */
+import { ref, readonly, computed } from 'vue'
+
+/**
+ * 导航加载状态管理
+ *
+ * 功能：
+ * 1. 在路由切换时显示加载状态
+ * 2. 快速导航（< 100ms）不显示加载指示器（防闪烁）
+ * 3. 导航取消时正确重置状态
+ */
+export function useNavigationLoading() {
+  // 内部加载状态
+  const _isLoading = ref(false)
+
+  // 导航开始时间（用于防闪烁计算）
+  let navigationStartTime: number | null = null
+
+  // 防闪烁延迟计时器
+  let showLoadingTimer: ReturnType<typeof setTimeout> | null = null
+
+  // 是否应该显示加载指示器（考虑防闪烁逻辑）
+  const shouldShowLoading = ref(false)
+
+  // 防闪烁延迟时间（毫秒）
+  const ANTI_FLICKER_DELAY = 100
+
+  /**
+   * 清理计时器
+   */
+  const clearTimer = (): void => {
+    if (showLoadingTimer !== null) {
+      clearTimeout(showLoadingTimer)
+      showLoadingTimer = null
+    }
+  }
+
+  /**
+   * 导航开始时调用
+   */
+  const startNavigation = (): void => {
+    navigationStartTime = Date.now()
+    _isLoading.value = true
+
+    // 延迟显示加载指示器，实现防闪烁
+    clearTimer()
+    showLoadingTimer = setTimeout(() => {
+      if (_isLoading.value) {
+        shouldShowLoading.value = true
+      }
+    }, ANTI_FLICKER_DELAY)
+  }
+
+  /**
+   * 导航结束时调用
+   */
+  const endNavigation = (): void => {
+    clearTimer()
+    _isLoading.value = false
+    shouldShowLoading.value = false
+    navigationStartTime = null
+  }
+
+  /**
+   * 导航取消时调用（比如快速连续点击不同链接）
+   */
+  const cancelNavigation = (): void => {
+    clearTimer()
+    // 保持加载状态，因为新的导航会立即开始
+    // 但重置导航开始时间
+    navigationStartTime = null
+  }
+
+  /**
+   * 重置所有状态（用于测试）
+   */
+  const resetState = (): void => {
+    clearTimer()
+    _isLoading.value = false
+    shouldShowLoading.value = false
+    navigationStartTime = null
+  }
+
+  /**
+   * 获取导航持续时间（毫秒）
+   */
+  const getNavigationDuration = (): number | null => {
+    if (navigationStartTime === null) {
+      return null
+    }
+    return Date.now() - navigationStartTime
+  }
+
+  // 公开的加载状态（只读）
+  const isLoading = computed(() => shouldShowLoading.value)
+
+  // 内部加载状态（用于测试，不考虑防闪烁）
+  const isNavigating = readonly(_isLoading)
+
+  return {
+    isLoading,
+    isNavigating,
+    startNavigation,
+    endNavigation,
+    cancelNavigation,
+    resetState,
+    getNavigationDuration,
+    // 导出常量用于测试
+    ANTI_FLICKER_DELAY
+  }
+}
+
+// 创建单例实例，供全局使用
+let navigationLoadingInstance: ReturnType<typeof useNavigationLoading> | null = null
+
+export function useNavigationLoadingState() {
+  if (!navigationLoadingInstance) {
+    navigationLoadingInstance = useNavigationLoading()
+  }
+  return navigationLoadingInstance
+}
+
+// 导出重置函数（用于测试）
+export function _resetNavigationLoadingInstance(): void {
+  if (navigationLoadingInstance) {
+    navigationLoadingInstance.resetState()
+  }
+  navigationLoadingInstance = null
+}

frontend/src/composables/useRoutePrefetch.ts

@@ -0,0 +1,202 @@
+/**
+ * 路由预加载组合式函数
+ * 在浏览器空闲时预加载可能访问的下一个页面，提升导航体验
+ *
+ * 优化说明：
+ * - 不使用静态 import() 映射表，避免增加入口文件大小
+ * - 通过路由配置动态获取组件的 import 函数
+ * - 只在实际需要预加载时才执行
+ */
+import { ref, readonly } from 'vue'
+import type { RouteLocationNormalized, Router } from 'vue-router'
+
+/**
+ * 组件导入函数类型
+ */
+type ComponentImportFn = () => Promise<unknown>
+
+/**
+ * 预加载邻接表：定义每个路由应该预加载哪些相邻路由
+ * 只存储路由路径，不存储 import 函数，避免打包问题
+ */
+const PREFETCH_ADJACENCY: Record<string, string[]> = {
+  // Admin routes - 预加载最常访问的相邻页面
+  '/admin/dashboard': ['/admin/accounts', '/admin/users'],
+  '/admin/accounts': ['/admin/dashboard', '/admin/users'],
+  '/admin/users': ['/admin/groups', '/admin/dashboard'],
+  '/admin/groups': ['/admin/subscriptions', '/admin/users'],
+  '/admin/subscriptions': ['/admin/groups', '/admin/redeem'],
+  // User routes
+  '/dashboard': ['/keys', '/usage'],
+  '/keys': ['/dashboard', '/usage'],
+  '/usage': ['/keys', '/redeem'],
+  '/redeem': ['/usage', '/profile'],
+  '/profile': ['/dashboard', '/keys']
+}
+
+/**
+ * requestIdleCallback 的返回类型
+ */
+type IdleCallbackHandle = number | ReturnType<typeof setTimeout>
+
+/**
+ * requestIdleCallback polyfill (Safari < 15)
+ */
+const scheduleIdleCallback = (
+  callback: IdleRequestCallback,
+  options?: IdleRequestOptions
+): IdleCallbackHandle => {
+  if (typeof window.requestIdleCallback === 'function') {
+    return window.requestIdleCallback(callback, options)
+  }
+  return setTimeout(() => {
+    callback({ didTimeout: false, timeRemaining: () => 50 })
+  }, 1000)
+}
+
+const cancelScheduledCallback = (handle: IdleCallbackHandle): void => {
+  if (typeof window.cancelIdleCallback === 'function' && typeof handle === 'number') {
+    window.cancelIdleCallback(handle)
+  } else {
+    clearTimeout(handle)
+  }
+}
+
+/**
+ * 路由预加载组合式函数
+ *
+ * @param router - Vue Router 实例，用于获取路由组件
+ */
+export function useRoutePrefetch(router?: Router) {
+  // 当前挂起的预加载任务句柄
+  const pendingPrefetchHandle = ref<IdleCallbackHandle | null>(null)
+
+  // 已预加载的路由集合
+  const prefetchedRoutes = ref<Set<string>>(new Set())
+
+  /**
+   * 从路由配置中获取组件的 import 函数
+   */
+  const getComponentImporter = (path: string): ComponentImportFn | null => {
+    if (!router) return null
+
+    const routes = router.getRoutes()
+    const route = routes.find((r) => r.path === path)
+
+    if (route && route.components?.default) {
+      const component = route.components.default
+      // 检查是否是懒加载组件（函数形式）
+      if (typeof component === 'function') {
+        return component as ComponentImportFn
+      }
+    }
+    return null
+  }
+
+  /**
+   * 获取当前路由应该预加载的路由路径列表
+   */
+  const getPrefetchPaths = (route: RouteLocationNormalized): string[] => {
+    return PREFETCH_ADJACENCY[route.path] || []
+  }
+
+  /**
+   * 执行单个组件的预加载
+   */
+  const prefetchComponent = async (importFn: ComponentImportFn): Promise<void> => {
+    try {
+      await importFn()
+    } catch (error) {
+      // 静默处理预加载错误
+      if (import.meta.env.DEV) {
+        console.debug('[Prefetch] Failed to prefetch component:', error)
+      }
+    }
+  }
+
+  /**
+   * 取消挂起的预加载任务
+   */
+  const cancelPendingPrefetch = (): void => {
+    if (pendingPrefetchHandle.value !== null) {
+      cancelScheduledCallback(pendingPrefetchHandle.value)
+      pendingPrefetchHandle.value = null
+    }
+  }
+
+  /**
+   * 触发路由预加载
+   */
+  const triggerPrefetch = (route: RouteLocationNormalized): void => {
+    cancelPendingPrefetch()
+
+    const prefetchPaths = getPrefetchPaths(route)
+    if (prefetchPaths.length === 0) return
+
+    pendingPrefetchHandle.value = scheduleIdleCallback(
+      () => {
+        pendingPrefetchHandle.value = null
+
+        const routePath = route.path
+        if (prefetchedRoutes.value.has(routePath)) return
+
+        // 获取需要预加载的组件 import 函数
+        const importFns: ComponentImportFn[] = []
+        for (const path of prefetchPaths) {
+          const importFn = getComponentImporter(path)
+          if (importFn) {
+            importFns.push(importFn)
+          }
+        }
+
+        if (importFns.length > 0) {
+          Promise.all(importFns.map(prefetchComponent)).then(() => {
+            prefetchedRoutes.value.add(routePath)
+          })
+        }
+      },
+      { timeout: 2000 }
+    )
+  }
+
+  /**
+   * 重置预加载状态
+   */
+  const resetPrefetchState = (): void => {
+    cancelPendingPrefetch()
+    prefetchedRoutes.value.clear()
+  }
+
+  /**
+   * 判断是否为管理员路由
+   */
+  const isAdminRoute = (path: string): boolean => {
+    return path.startsWith('/admin')
+  }
+
+  /**
+   * 获取预加载配置（兼容旧 API）
+   */
+  const getPrefetchConfig = (route: RouteLocationNormalized): ComponentImportFn[] => {
+    const paths = getPrefetchPaths(route)
+    const importFns: ComponentImportFn[] = []
+    for (const path of paths) {
+      const importFn = getComponentImporter(path)
+      if (importFn) importFns.push(importFn)
+    }
+    return importFns
+  }
+
+  return {
+    prefetchedRoutes: readonly(prefetchedRoutes),
+    triggerPrefetch,
+    cancelPendingPrefetch,
+    resetPrefetchState,
+    _getPrefetchConfig: getPrefetchConfig,
+    _isAdminRoute: isAdminRoute
+  }
+}
+
+// 兼容旧测试的导出
+export const _adminPrefetchMap = PREFETCH_ADJACENCY
+export const _userPrefetchMap = PREFETCH_ADJACENCY

frontend/src/router/index.ts

@@ -6,6 +6,8 @@
 import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router'
 import { useAuthStore } from '@/stores/auth'
 import { useAppStore } from '@/stores/app'
+import { useNavigationLoadingState } from '@/composables/useNavigationLoading'
+import { useRoutePrefetch } from '@/composables/useRoutePrefetch'
 
 /**
  * Route definitions with lazy loading
@@ -326,7 +328,15 @@ const router = createRouter({
  */
 let authInitialized = false
 
+// 初始化导航加载状态和预加载
+const navigationLoading = useNavigationLoadingState()
+// 延迟初始化预加载，传入 router 实例
+let routePrefetch: ReturnType<typeof useRoutePrefetch> | null = null
+
 router.beforeEach((to, _from, next) => {
+  // 开始导航加载状态
+  navigationLoading.startNavigation()
+
   const authStore = useAuthStore()
 
   // Restore auth state from localStorage on first navigation (page refresh)
@@ -398,6 +408,21 @@ router.beforeEach((to, _from, next) => {
   next()
 })
 
+/**
+ * Navigation guard: End loading and trigger prefetch
+ */
+router.afterEach((to) => {
+  // 结束导航加载状态
+  navigationLoading.endNavigation()
+
+  // 懒初始化预加载（首次导航时创建，传入 router 实例）
+  if (!routePrefetch) {
+    routePrefetch = useRoutePrefetch(router)
+  }
+  // 触发路由预加载（在浏览器空闲时执行）
+  routePrefetch.triggerPrefetch(to)
+})
+
 /**
  * Navigation guard: Error handling
  * Handles dynamic import failures caused by deployment updates

frontend/src/style.css

@@ -1,5 +1,3 @@
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');
-
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
@@ -11,7 +9,6 @@
 
   html {
     @apply scroll-smooth antialiased;
-    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
   }
 
   body {

frontend/tailwind.config.js

@@ -50,16 +50,19 @@ export default {
       },
       fontFamily: {
         sans: [
-          'Inter',
+          'system-ui',
           '-apple-system',
           'BlinkMacSystemFont',
           'Segoe UI',
           'Roboto',
           'Helvetica Neue',
           'Arial',
+          'PingFang SC',
+          'Hiragino Sans GB',
+          'Microsoft YaHei',
           'sans-serif'
         ],
-        mono: ['JetBrains Mono', 'Fira Code', 'Monaco', 'Consolas', 'monospace']
+        mono: ['ui-monospace', 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'monospace']
       },
       boxShadow: {
         glass: '0 8px 32px rgba(0, 0, 0, 0.08)',

frontend/vite.config.ts

@@ -58,7 +58,49 @@ export default defineConfig({
   },
   build: {
     outDir: '../backend/internal/web/dist',
-    emptyOutDir: true
+    emptyOutDir: true,
+    rollupOptions: {
+      output: {
+        /**
+         * 手动分包配置
+         * 分离第三方库并按功能合并应用代码，避免循环依赖
+         */
+        manualChunks(id: string) {
+          if (id.includes('node_modules')) {
+            // Vue 核心库
+            if (
+              id.includes('/vue/') ||
+              id.includes('/vue-router/') ||
+              id.includes('/pinia/') ||
+              id.includes('/@vue/')
+            ) {
+              return 'vendor-vue'
+            }
+
+            // UI 工具库（较大，单独分离）
+            if (id.includes('/@vueuse/') || id.includes('/xlsx/')) {
+              return 'vendor-ui'
+            }
+
+            // 图表库
+            if (id.includes('/chart.js/') || id.includes('/vue-chartjs/')) {
+              return 'vendor-chart'
+            }
+
+            // 国际化
+            if (id.includes('/vue-i18n/') || id.includes('/@intlify/')) {
+              return 'vendor-i18n'
+            }
+
+            // 其他小型第三方库合并
+            return 'vendor-misc'
+          }
+
+          // 应用代码：按入口点自动分包，不手动干预
+          // 这样可以避免循环依赖，同时保持合理的 chunk 数量
+        }
+      }
+    }
   },
   server: {
     host: '0.0.0.0',

frontend/vitest.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import viteConfig from './vite.config'
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      globals: true,
+      environment: 'jsdom',
+      include: ['src/**/*.{test,spec}.{js,ts,jsx,tsx}'],
+      exclude: ['node_modules', 'dist'],
+      coverage: {
+        provider: 'v8',
+        reporter: ['text', 'json', 'html'],
+        include: ['src/**/*.{js,ts,vue}'],
+        exclude: [
+          'node_modules',
+          'src/**/*.d.ts',
+          'src/**/*.spec.ts',
+          'src/**/*.test.ts',
+          'src/main.ts'
+        ],
+        thresholds: {
+          global: {
+            statements: 80,
+            branches: 80,
+            functions: 80,
+            lines: 80
+          }
+        }
+      },
+      setupFiles: ['./src/__tests__/setup.ts']
+    }
+  })
+)