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

+/**
+ * 导航集成测试
+ * 测试完整的页面导航流程、预加载和错误恢复机制
+ */
+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

+/**
+ * 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

+<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

+/**
+ * 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

+/**
+ * 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

+/**
+ * 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)
+    })
+  })
+})