test: 完善自动化测试体系（7个模块，73个任务）

系统性地修复、补充和强化项目的自动化测试能力：

1. 测试基础设施修复
   - 修复 stubConcurrencyCache 缺失方法和构造函数参数不匹配
   - 创建 testutil 共享包（stubs.go, fixtures.go, httptest.go）
   - 为所有 Stub 添加编译期接口断言

2. 中间件测试补充
   - 新增 JWT 认证中间件测试（有效/过期/篡改/缺失 Token）
   - 补充 rate_limiter 和 recovery 中间件测试场景

3. 网关核心路径测试
   - 新增账户选择、等待队列、流式响应、并发控制、计费、Claude Code 检测测试
   - 覆盖负载均衡、粘性会话、SSE 转发、槽位管理等关键逻辑

4. 前端测试体系（11个新测试文件，163个测试用例）
   - Pinia stores: auth, app, subscriptions
   - API client: 请求拦截器、响应拦截器、401 刷新
   - Router guards: 认证重定向、管理员权限、简易模式限制
   - Composables: useForm, useTableLoader, useClipboard
   - Components: LoginForm, ApiKeyCreate, Dashboard

5. CI/CD 流水线重构
   - 重构 backend-ci.yml 为统一的 ci.yml
   - 前后端 4 个并行 Job + Postgres/Redis services
   - Race 检测、覆盖率收集与门禁、Docker 构建验证

6. E2E 自动化测试
   - e2e-test.sh 自动化脚本（Docker 启动→健康检查→测试→清理）
   - 用户注册→登录→API Key→网关调用完整链路测试
   - Mock 模式和 API Key 脱敏支持

7. 修复预存问题
   - tlsfingerprint dialer_test.go 缺失 build tag 导致集成测试编译冲突
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/internal/service/gateway_streaming_test.go

+//go:build unit
+
+package service
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+// --- parseSSEUsage 测试 ---
+
+func newMinimalGatewayService() *GatewayService {
+	return &GatewayService{
+		cfg: &config.Config{
+			Gateway: config.GatewayConfig{
+				StreamDataIntervalTimeout: 0,
+				MaxLineSize:               defaultMaxLineSize,
+			},
+		},
+		rateLimitService: &RateLimitService{},
+	}
+}
+
+func TestParseSSEUsage_MessageStart(t *testing.T) {
+	svc := newMinimalGatewayService()
+	usage := &ClaudeUsage{}
+
+	data := `{"type":"message_start","message":{"usage":{"input_tokens":100,"cache_creation_input_tokens":50,"cache_read_input_tokens":200}}}`
+	svc.parseSSEUsage(data, usage)
+
+	require.Equal(t, 100, usage.InputTokens)
+	require.Equal(t, 50, usage.CacheCreationInputTokens)
+	require.Equal(t, 200, usage.CacheReadInputTokens)
+	require.Equal(t, 0, usage.OutputTokens, "message_start 不应设置 output_tokens")
+}
+
+func TestParseSSEUsage_MessageDelta(t *testing.T) {
+	svc := newMinimalGatewayService()
+	usage := &ClaudeUsage{}
+
+	data := `{"type":"message_delta","usage":{"output_tokens":42}}`
+	svc.parseSSEUsage(data, usage)
+
+	require.Equal(t, 42, usage.OutputTokens)
+	require.Equal(t, 0, usage.InputTokens, "message_delta 的 output_tokens 不应影响已有的 input_tokens")
+}
+
+func TestParseSSEUsage_DeltaDoesNotOverwriteStartValues(t *testing.T) {
+	svc := newMinimalGatewayService()
+	usage := &ClaudeUsage{}
+
+	// 先处理 message_start
+	svc.parseSSEUsage(`{"type":"message_start","message":{"usage":{"input_tokens":100}}}`, usage)
+	require.Equal(t, 100, usage.InputTokens)
+
+	// 再处理 message_delta（output_tokens > 0, input_tokens = 0）
+	svc.parseSSEUsage(`{"type":"message_delta","usage":{"output_tokens":50}}`, usage)
+	require.Equal(t, 100, usage.InputTokens, "delta 中 input_tokens=0 不应覆盖 start 中的值")
+	require.Equal(t, 50, usage.OutputTokens)
+}
+
+func TestParseSSEUsage_DeltaOverwritesWithNonZero(t *testing.T) {
+	svc := newMinimalGatewayService()
+	usage := &ClaudeUsage{}
+
+	// GLM 等 API 会在 delta 中包含所有 usage 信息
+	svc.parseSSEUsage(`{"type":"message_delta","usage":{"input_tokens":200,"output_tokens":100,"cache_creation_input_tokens":30,"cache_read_input_tokens":60}}`, usage)
+	require.Equal(t, 200, usage.InputTokens)
+	require.Equal(t, 100, usage.OutputTokens)
+	require.Equal(t, 30, usage.CacheCreationInputTokens)
+	require.Equal(t, 60, usage.CacheReadInputTokens)
+}
+
+func TestParseSSEUsage_InvalidJSON(t *testing.T) {
+	svc := newMinimalGatewayService()
+	usage := &ClaudeUsage{}
+
+	// 无效 JSON 不应 panic
+	svc.parseSSEUsage("not json", usage)
+	require.Equal(t, 0, usage.InputTokens)
+	require.Equal(t, 0, usage.OutputTokens)
+}
+
+func TestParseSSEUsage_UnknownType(t *testing.T) {
+	svc := newMinimalGatewayService()
+	usage := &ClaudeUsage{}
+
+	// 不是 message_start 或 message_delta 的类型
+	svc.parseSSEUsage(`{"type":"content_block_delta","delta":{"text":"hello"}}`, usage)
+	require.Equal(t, 0, usage.InputTokens)
+	require.Equal(t, 0, usage.OutputTokens)
+}
+
+func TestParseSSEUsage_EmptyString(t *testing.T) {
+	svc := newMinimalGatewayService()
+	usage := &ClaudeUsage{}
+
+	svc.parseSSEUsage("", usage)
+	require.Equal(t, 0, usage.InputTokens)
+}
+
+func TestParseSSEUsage_DoneEvent(t *testing.T) {
+	svc := newMinimalGatewayService()
+	usage := &ClaudeUsage{}
+
+	// [DONE] 事件不应影响 usage
+	svc.parseSSEUsage("[DONE]", usage)
+	require.Equal(t, 0, usage.InputTokens)
+}
+
+// --- 流式响应端到端测试 ---
+
+func TestHandleStreamingResponse_CacheTokens(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := newMinimalGatewayService()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/messages", nil)
+
+	pr, pw := io.Pipe()
+	resp := &http.Response{StatusCode: http.StatusOK, Header: http.Header{}, Body: pr}
+
+	go func() {
+		defer func() { _ = pw.Close() }()
+		_, _ = pw.Write([]byte("data: {\"type\":\"message_start\",\"message\":{\"usage\":{\"input_tokens\":10,\"cache_creation_input_tokens\":20,\"cache_read_input_tokens\":30}}}\n\n"))
+		_, _ = pw.Write([]byte("data: {\"type\":\"message_delta\",\"usage\":{\"output_tokens\":15}}\n\n"))
+		_, _ = pw.Write([]byte("data: [DONE]\n\n"))
+	}()
+
+	result, err := svc.handleStreamingResponse(context.Background(), resp, c, &Account{ID: 1}, time.Now(), "model", "model", false)
+	_ = pr.Close()
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	require.NotNil(t, result.usage)
+	require.Equal(t, 10, result.usage.InputTokens)
+	require.Equal(t, 15, result.usage.OutputTokens)
+	require.Equal(t, 20, result.usage.CacheCreationInputTokens)
+	require.Equal(t, 30, result.usage.CacheReadInputTokens)
+}
+
+func TestHandleStreamingResponse_EmptyStream(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := newMinimalGatewayService()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/messages", nil)
+
+	pr, pw := io.Pipe()
+	resp := &http.Response{StatusCode: http.StatusOK, Header: http.Header{}, Body: pr}
+
+	go func() {
+		// 直接关闭，不发送任何事件
+		_ = pw.Close()
+	}()
+
+	result, err := svc.handleStreamingResponse(context.Background(), resp, c, &Account{ID: 1}, time.Now(), "model", "model", false)
+	_ = pr.Close()
+	require.NoError(t, err)
+	require.NotNil(t, result)
+}
+
+func TestHandleStreamingResponse_SpecialCharactersInJSON(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := newMinimalGatewayService()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/messages", nil)
+
+	pr, pw := io.Pipe()
+	resp := &http.Response{StatusCode: http.StatusOK, Header: http.Header{}, Body: pr}
+
+	go func() {
+		defer func() { _ = pw.Close() }()
+		// 包含特殊字符的 content_block_delta（引号、换行、Unicode）
+		_, _ = pw.Write([]byte("data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Hello \\\"world\\\"\\n你好\"}}\n\n"))
+		_, _ = pw.Write([]byte("data: {\"type\":\"message_start\",\"message\":{\"usage\":{\"input_tokens\":5}}}\n\n"))
+		_, _ = pw.Write([]byte("data: {\"type\":\"message_delta\",\"usage\":{\"output_tokens\":3}}\n\n"))
+		_, _ = pw.Write([]byte("data: [DONE]\n\n"))
+	}()
+
+	result, err := svc.handleStreamingResponse(context.Background(), resp, c, &Account{ID: 1}, time.Now(), "model", "model", false)
+	_ = pr.Close()
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	require.NotNil(t, result.usage)
+	require.Equal(t, 5, result.usage.InputTokens)
+	require.Equal(t, 3, result.usage.OutputTokens)
+
+	// 验证响应中包含转发的数据
+	body := rec.Body.String()
+	require.Contains(t, body, "content_block_delta", "响应应包含转发的 SSE 事件")
+}

backend/internal/service/gateway_waiting_queue_test.go

+//go:build unit
+
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestDecrementWaitCount_NilCache 确保 nil cache 不会 panic
+func TestDecrementWaitCount_NilCache(t *testing.T) {
+	svc := &ConcurrencyService{cache: nil}
+	// 不应 panic
+	svc.DecrementWaitCount(context.Background(), 1)
+}
+
+// TestDecrementWaitCount_CacheError 确保 cache 错误不会传播
+func TestDecrementWaitCount_CacheError(t *testing.T) {
+	cache := &stubConcurrencyCacheForTest{}
+	svc := NewConcurrencyService(cache)
+	// DecrementWaitCount 使用 background context，错误只记录日志不传播
+	svc.DecrementWaitCount(context.Background(), 1)
+}
+
+// TestDecrementAccountWaitCount_NilCache 确保 nil cache 不会 panic
+func TestDecrementAccountWaitCount_NilCache(t *testing.T) {
+	svc := &ConcurrencyService{cache: nil}
+	svc.DecrementAccountWaitCount(context.Background(), 1)
+}
+
+// TestDecrementAccountWaitCount_CacheError 确保 cache 错误不会传播
+func TestDecrementAccountWaitCount_CacheError(t *testing.T) {
+	cache := &stubConcurrencyCacheForTest{}
+	svc := NewConcurrencyService(cache)
+	svc.DecrementAccountWaitCount(context.Background(), 1)
+}
+
+// TestWaitingQueueFlow_IncrementThenDecrement 测试完整的等待队列增减流程
+func TestWaitingQueueFlow_IncrementThenDecrement(t *testing.T) {
+	cache := &stubConcurrencyCacheForTest{waitAllowed: true}
+	svc := NewConcurrencyService(cache)
+
+	// 进入等待队列
+	allowed, err := svc.IncrementWaitCount(context.Background(), 1, 25)
+	require.NoError(t, err)
+	require.True(t, allowed)
+
+	// 离开等待队列（不应 panic）
+	svc.DecrementWaitCount(context.Background(), 1)
+}
+
+// TestWaitingQueueFlow_AccountLevel 测试账号级等待队列流程
+func TestWaitingQueueFlow_AccountLevel(t *testing.T) {
+	cache := &stubConcurrencyCacheForTest{waitAllowed: true}
+	svc := NewConcurrencyService(cache)
+
+	// 进入账号等待队列
+	allowed, err := svc.IncrementAccountWaitCount(context.Background(), 42, 10)
+	require.NoError(t, err)
+	require.True(t, allowed)
+
+	// 离开账号等待队列
+	svc.DecrementAccountWaitCount(context.Background(), 42)
+}
+
+// TestWaitingQueueFull_Returns429Signal 测试等待队列满时返回 false
+func TestWaitingQueueFull_Returns429Signal(t *testing.T) {
+	// waitAllowed=false 模拟队列已满
+	cache := &stubConcurrencyCacheForTest{waitAllowed: false}
+	svc := NewConcurrencyService(cache)
+
+	// 用户级等待队列满
+	allowed, err := svc.IncrementWaitCount(context.Background(), 1, 25)
+	require.NoError(t, err)
+	require.False(t, allowed, "等待队列满时应返回 false（调用方根据此返回 429）")
+
+	// 账号级等待队列满
+	allowed, err = svc.IncrementAccountWaitCount(context.Background(), 1, 10)
+	require.NoError(t, err)
+	require.False(t, allowed, "账号等待队列满时应返回 false")
+}
+
+// TestWaitingQueue_FailOpen_OnCacheError 测试 Redis 故障时 fail-open
+func TestWaitingQueue_FailOpen_OnCacheError(t *testing.T) {
+	cache := &stubConcurrencyCacheForTest{waitErr: errors.New("redis connection refused")}
+	svc := NewConcurrencyService(cache)
+
+	// 用户级：Redis 错误时允许通过
+	allowed, err := svc.IncrementWaitCount(context.Background(), 1, 25)
+	require.NoError(t, err, "Redis 错误不应向调用方传播")
+	require.True(t, allowed, "Redis 故障时应 fail-open 放行")
+
+	// 账号级：同样 fail-open
+	allowed, err = svc.IncrementAccountWaitCount(context.Background(), 1, 10)
+	require.NoError(t, err, "Redis 错误不应向调用方传播")
+	require.True(t, allowed, "Redis 故障时应 fail-open 放行")
+}
+
+// TestCalculateMaxWait_Scenarios 测试最大等待队列大小计算
+func TestCalculateMaxWait_Scenarios(t *testing.T) {
+	tests := []struct {
+		concurrency int
+		expected    int
+	}{
+		{5, 25},   // 5 + 20
+		{10, 30},  // 10 + 20
+		{1, 21},   // 1 + 20
+		{0, 21},   // min(1) + 20
+		{-1, 21},  // min(1) + 20
+		{-10, 21}, // min(1) + 20
+		{100, 120}, // 100 + 20
+	}
+	for _, tt := range tests {
+		result := CalculateMaxWait(tt.concurrency)
+		require.Equal(t, tt.expected, result, "CalculateMaxWait(%d)", tt.concurrency)
+	}
+}

backend/internal/service/openai_gateway_service_test.go

@@ -17,6 +17,10 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// 编译期接口断言
+var _ AccountRepository = (*stubOpenAIAccountRepo)(nil)
+var _ GatewayCache = (*stubGatewayCache)(nil)
+
 type stubOpenAIAccountRepo struct {
 	AccountRepository
 	accounts []Account

backend/internal/service/ops_alert_evaluator_service_test.go

@@ -10,6 +10,8 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+var _ OpsRepository = (*stubOpsRepo)(nil)
+
 type stubOpsRepo struct {
 	OpsRepository
 	overview *OpsDashboardOverview

backend/internal/service/sora_gateway_service_test.go

@@ -10,6 +10,8 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+var _ SoraClient = (*stubSoraClientForPoll)(nil)
+
 type stubSoraClientForPoll struct {
 	imageStatus *SoraImageTaskStatus
 	videoStatus *SoraVideoTaskStatus

backend/internal/testutil/fixtures.go

+//go:build unit
+
+package testutil
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+// NewTestUser 创建一个可用的测试用户，可通过 opts 覆盖默认值。
+func NewTestUser(opts ...func(*service.User)) *service.User {
+	u := &service.User{
+		ID:          1,
+		Email:       "test@example.com",
+		Username:    "testuser",
+		Role:        "user",
+		Balance:     100.0,
+		Concurrency: 5,
+		Status:      service.StatusActive,
+		CreatedAt:   time.Now(),
+		UpdatedAt:   time.Now(),
+	}
+	for _, opt := range opts {
+		opt(u)
+	}
+	return u
+}
+
+// NewTestAccount 创建一个可用的测试账户，可通过 opts 覆盖默认值。
+func NewTestAccount(opts ...func(*service.Account)) *service.Account {
+	a := &service.Account{
+		ID:          1,
+		Name:        "test-account",
+		Platform:    service.PlatformAnthropic,
+		Status:      service.StatusActive,
+		Schedulable: true,
+		Concurrency: 5,
+		Priority:    1,
+	}
+	for _, opt := range opts {
+		opt(a)
+	}
+	return a
+}
+
+// NewTestAPIKey 创建一个可用的测试 API Key，可通过 opts 覆盖默认值。
+func NewTestAPIKey(opts ...func(*service.APIKey)) *service.APIKey {
+	groupID := int64(1)
+	k := &service.APIKey{
+		ID:        1,
+		UserID:    1,
+		Key:       "sk-test-key-12345678",
+		Name:      "test-key",
+		GroupID:   &groupID,
+		Status:    service.StatusActive,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+	for _, opt := range opts {
+		opt(k)
+	}
+	return k
+}
+
+// NewTestGroup 创建一个可用的测试分组，可通过 opts 覆盖默认值。
+func NewTestGroup(opts ...func(*service.Group)) *service.Group {
+	g := &service.Group{
+		ID:       1,
+		Platform: service.PlatformAnthropic,
+		Status:   service.StatusActive,
+		Hydrated: true,
+	}
+	for _, opt := range opts {
+		opt(g)
+	}
+	return g
+}

backend/internal/testutil/httptest.go

+//go:build unit
+
+package testutil
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+func init() {
+	gin.SetMode(gin.TestMode)
+}
+
+// NewGinTestContext 创建一个 Gin 测试上下文和 ResponseRecorder。
+// body 为空字符串时创建无 body 的请求。
+func NewGinTestContext(method, path, body string) (*gin.Context, *httptest.ResponseRecorder) {
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+
+	var bodyReader io.Reader
+	if body != "" {
+		bodyReader = strings.NewReader(body)
+	}
+
+	c.Request = httptest.NewRequest(method, path, bodyReader)
+	if method == http.MethodPost || method == http.MethodPut || method == http.MethodPatch {
+		c.Request.Header.Set("Content-Type", "application/json")
+	}
+
+	return c, rec
+}

backend/internal/testutil/stubs.go

+//go:build unit
+
+// Package testutil 提供单元测试共享的 Stub、Fixture 和辅助函数。
+// 所有文件使用 //go:build unit 标签，确保不会被生产构建包含。
+package testutil
+
+import (
+	"context"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+// ============================================================
+// StubConcurrencyCache — service.ConcurrencyCache 的空实现
+// ============================================================
+
+// 编译期接口断言
+var _ service.ConcurrencyCache = StubConcurrencyCache{}
+
+// StubConcurrencyCache 是 ConcurrencyCache 的默认空实现，所有方法返回零值。
+type StubConcurrencyCache struct{}
+
+func (c StubConcurrencyCache) AcquireAccountSlot(_ context.Context, _ int64, _ int, _ string) (bool, error) {
+	return true, nil
+}
+func (c StubConcurrencyCache) ReleaseAccountSlot(_ context.Context, _ int64, _ string) error {
+	return nil
+}
+func (c StubConcurrencyCache) GetAccountConcurrency(_ context.Context, _ int64) (int, error) {
+	return 0, nil
+}
+func (c StubConcurrencyCache) IncrementAccountWaitCount(_ context.Context, _ int64, _ int) (bool, error) {
+	return true, nil
+}
+func (c StubConcurrencyCache) DecrementAccountWaitCount(_ context.Context, _ int64) error {
+	return nil
+}
+func (c StubConcurrencyCache) GetAccountWaitingCount(_ context.Context, _ int64) (int, error) {
+	return 0, nil
+}
+func (c StubConcurrencyCache) AcquireUserSlot(_ context.Context, _ int64, _ int, _ string) (bool, error) {
+	return true, nil
+}
+func (c StubConcurrencyCache) ReleaseUserSlot(_ context.Context, _ int64, _ string) error {
+	return nil
+}
+func (c StubConcurrencyCache) GetUserConcurrency(_ context.Context, _ int64) (int, error) {
+	return 0, nil
+}
+func (c StubConcurrencyCache) IncrementWaitCount(_ context.Context, _ int64, _ int) (bool, error) {
+	return true, nil
+}
+func (c StubConcurrencyCache) DecrementWaitCount(_ context.Context, _ int64) error { return nil }
+func (c StubConcurrencyCache) GetAccountsLoadBatch(_ context.Context, accounts []service.AccountWithConcurrency) (map[int64]*service.AccountLoadInfo, error) {
+	result := make(map[int64]*service.AccountLoadInfo, len(accounts))
+	for _, acc := range accounts {
+		result[acc.ID] = &service.AccountLoadInfo{AccountID: acc.ID, LoadRate: 0}
+	}
+	return result, nil
+}
+func (c StubConcurrencyCache) GetUsersLoadBatch(_ context.Context, users []service.UserWithConcurrency) (map[int64]*service.UserLoadInfo, error) {
+	result := make(map[int64]*service.UserLoadInfo, len(users))
+	for _, u := range users {
+		result[u.ID] = &service.UserLoadInfo{UserID: u.ID, LoadRate: 0}
+	}
+	return result, nil
+}
+func (c StubConcurrencyCache) CleanupExpiredAccountSlots(_ context.Context, _ int64) error {
+	return nil
+}
+
+// ============================================================
+// StubGatewayCache — service.GatewayCache 的空实现
+// ============================================================
+
+var _ service.GatewayCache = StubGatewayCache{}
+
+type StubGatewayCache struct{}
+
+func (c StubGatewayCache) GetSessionAccountID(_ context.Context, _ int64, _ string) (int64, error) {
+	return 0, nil
+}
+func (c StubGatewayCache) SetSessionAccountID(_ context.Context, _ int64, _ string, _ int64, _ time.Duration) error {
+	return nil
+}
+func (c StubGatewayCache) RefreshSessionTTL(_ context.Context, _ int64, _ string, _ time.Duration) error {
+	return nil
+}
+func (c StubGatewayCache) DeleteSessionAccountID(_ context.Context, _ int64, _ string) error {
+	return nil
+}
+func (c StubGatewayCache) IncrModelCallCount(_ context.Context, _ int64, _ string) (int64, error) {
+	return 0, nil
+}
+func (c StubGatewayCache) GetModelLoadBatch(_ context.Context, _ []int64, _ string) (map[int64]*service.ModelLoadInfo, error) {
+	return nil, nil
+}
+func (c StubGatewayCache) FindGeminiSession(_ context.Context, _ int64, _, _ string) (string, int64, bool) {
+	return "", 0, false
+}
+func (c StubGatewayCache) SaveGeminiSession(_ context.Context, _ int64, _, _, _ string, _ int64) error {
+	return nil
+}
+
+// ============================================================
+// StubSessionLimitCache — service.SessionLimitCache 的空实现
+// ============================================================
+
+var _ service.SessionLimitCache = StubSessionLimitCache{}
+
+type StubSessionLimitCache struct{}
+
+func (c StubSessionLimitCache) RegisterSession(_ context.Context, _ int64, _ string, _ int, _ time.Duration) (bool, error) {
+	return true, nil
+}
+func (c StubSessionLimitCache) RefreshSession(_ context.Context, _ int64, _ string, _ time.Duration) error {
+	return nil
+}
+func (c StubSessionLimitCache) GetActiveSessionCount(_ context.Context, _ int64) (int, error) {
+	return 0, nil
+}
+func (c StubSessionLimitCache) GetActiveSessionCountBatch(_ context.Context, _ []int64, _ map[int64]time.Duration) (map[int64]int, error) {
+	return nil, nil
+}
+func (c StubSessionLimitCache) IsSessionActive(_ context.Context, _ int64, _ string) (bool, error) {
+	return false, nil
+}
+func (c StubSessionLimitCache) GetWindowCost(_ context.Context, _ int64) (float64, bool, error) {
+	return 0, false, nil
+}
+func (c StubSessionLimitCache) SetWindowCost(_ context.Context, _ int64, _ float64) error {
+	return nil
+}
+func (c StubSessionLimitCache) GetWindowCostBatch(_ context.Context, _ []int64) (map[int64]float64, error) {
+	return nil, nil
+}

frontend/src/api/__tests__/client.spec.ts

+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import axios from 'axios'
+import type { AxiosInstance, InternalAxiosRequestConfig, AxiosResponse, AxiosHeaders } from 'axios'
+
+// 需要在导入 client 之前设置 mock
+vi.mock('@/i18n', () => ({
+  getLocale: () => 'zh-CN',
+}))
+
+describe('API Client', () => {
+  let apiClient: AxiosInstance
+
+  beforeEach(async () => {
+    localStorage.clear()
+    // 每次测试重新导入以获取干净的模块状态
+    vi.resetModules()
+    const mod = await import('@/api/client')
+    apiClient = mod.apiClient
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  // --- 请求拦截器 ---
+
+  describe('请求拦截器', () => {
+    it('自动附加 Authorization 头', async () => {
+      localStorage.setItem('auth_token', 'my-jwt-token')
+
+      // 拦截实际请求
+      const adapter = vi.fn().mockResolvedValue({
+        status: 200,
+        data: { code: 0, data: {} },
+        headers: {},
+        config: {},
+        statusText: 'OK',
+      })
+      apiClient.defaults.adapter = adapter
+
+      await apiClient.get('/test')
+
+      const config = adapter.mock.calls[0][0]
+      expect(config.headers.get('Authorization')).toBe('Bearer my-jwt-token')
+    })
+
+    it('无 token 时不附加 Authorization 头', async () => {
+      const adapter = vi.fn().mockResolvedValue({
+        status: 200,
+        data: { code: 0, data: {} },
+        headers: {},
+        config: {},
+        statusText: 'OK',
+      })
+      apiClient.defaults.adapter = adapter
+
+      await apiClient.get('/test')
+
+      const config = adapter.mock.calls[0][0]
+      expect(config.headers.get('Authorization')).toBeFalsy()
+    })
+
+    it('GET 请求自动附加 timezone 参数', async () => {
+      const adapter = vi.fn().mockResolvedValue({
+        status: 200,
+        data: { code: 0, data: {} },
+        headers: {},
+        config: {},
+        statusText: 'OK',
+      })
+      apiClient.defaults.adapter = adapter
+
+      await apiClient.get('/test')
+
+      const config = adapter.mock.calls[0][0]
+      expect(config.params).toHaveProperty('timezone')
+    })
+
+    it('POST 请求不附加 timezone 参数', async () => {
+      const adapter = vi.fn().mockResolvedValue({
+        status: 200,
+        data: { code: 0, data: {} },
+        headers: {},
+        config: {},
+        statusText: 'OK',
+      })
+      apiClient.defaults.adapter = adapter
+
+      await apiClient.post('/test', { foo: 'bar' })
+
+      const config = adapter.mock.calls[0][0]
+      expect(config.params?.timezone).toBeUndefined()
+    })
+  })
+
+  // --- 响应拦截器 ---
+
+  describe('响应拦截器', () => {
+    it('code=0 时解包 data 字段', async () => {
+      const adapter = vi.fn().mockResolvedValue({
+        status: 200,
+        data: { code: 0, data: { name: 'test' }, message: 'ok' },
+        headers: {},
+        config: {},
+        statusText: 'OK',
+      })
+      apiClient.defaults.adapter = adapter
+
+      const response = await apiClient.get('/test')
+      expect(response.data).toEqual({ name: 'test' })
+    })
+
+    it('code!=0 时拒绝并返回结构化错误', async () => {
+      const adapter = vi.fn().mockResolvedValue({
+        status: 200,
+        data: { code: 1001, message: '参数错误', data: null },
+        headers: {},
+        config: {},
+        statusText: 'OK',
+      })
+      apiClient.defaults.adapter = adapter
+
+      await expect(apiClient.get('/test')).rejects.toEqual(
+        expect.objectContaining({
+          code: 1001,
+          message: '参数错误',
+        })
+      )
+    })
+  })
+
+  // --- 401 Token 刷新 ---
+
+  describe('401 Token 刷新', () => {
+    it('无 refresh_token 时 401 清除 localStorage', async () => {
+      localStorage.setItem('auth_token', 'expired-token')
+      // 不设置 refresh_token
+
+      // Mock window.location
+      const originalLocation = window.location
+      Object.defineProperty(window, 'location', {
+        value: { ...originalLocation, pathname: '/dashboard', href: '/dashboard' },
+        writable: true,
+      })
+
+      const adapter = vi.fn().mockRejectedValue({
+        response: {
+          status: 401,
+          data: { code: 'TOKEN_EXPIRED', message: 'Token expired' },
+        },
+        config: {
+          url: '/test',
+          headers: { Authorization: 'Bearer expired-token' },
+        },
+        code: 'ERR_BAD_REQUEST',
+      })
+      apiClient.defaults.adapter = adapter
+
+      await expect(apiClient.get('/test')).rejects.toBeDefined()
+
+      expect(localStorage.getItem('auth_token')).toBeNull()
+
+      // 恢复 location
+      Object.defineProperty(window, 'location', {
+        value: originalLocation,
+        writable: true,
+      })
+    })
+  })
+
+  // --- 网络错误 ---
+
+  describe('网络错误', () => {
+    it('网络错误返回 status 0 的错误', async () => {
+      const adapter = vi.fn().mockRejectedValue({
+        code: 'ERR_NETWORK',
+        message: 'Network Error',
+        config: { url: '/test' },
+        // 没有 response
+      })
+      apiClient.defaults.adapter = adapter
+
+      await expect(apiClient.get('/test')).rejects.toEqual(
+        expect.objectContaining({
+          status: 0,
+          message: 'Network error. Please check your connection.',
+        })
+      )
+    })
+  })
+
+  // --- 请求取消 ---
+
+  describe('请求取消', () => {
+    it('取消的请求保持原始取消错误', async () => {
+      const source = axios.CancelToken.source()
+
+      const adapter = vi.fn().mockRejectedValue(
+        new axios.Cancel('Operation canceled')
+      )
+      apiClient.defaults.adapter = adapter
+
+      await expect(
+        apiClient.get('/test', { cancelToken: source.token })
+      ).rejects.toBeDefined()
+    })
+  })
+})

frontend/src/components/__tests__/ApiKeyCreate.spec.ts

+/**
+ * API Key 创建逻辑测试
+ * 通过封装组件测试 API Key 创建的核心流程
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { setActivePinia, createPinia } from 'pinia'
+import { defineComponent, ref, reactive } from 'vue'
+
+// Mock keysAPI
+const mockCreate = vi.fn()
+const mockList = vi.fn()
+
+vi.mock('@/api', () => ({
+  keysAPI: {
+    create: (...args: any[]) => mockCreate(...args),
+    list: (...args: any[]) => mockList(...args),
+  },
+  authAPI: {
+    getCurrentUser: vi.fn().mockResolvedValue({ data: {} }),
+    logout: vi.fn(),
+    refreshToken: vi.fn(),
+  },
+  isTotp2FARequired: () => false,
+}))
+
+vi.mock('@/api/admin/system', () => ({
+  checkUpdates: vi.fn(),
+}))
+
+vi.mock('@/api/auth', () => ({
+  getPublicSettings: vi.fn().mockResolvedValue({}),
+}))
+
+// Mock app store - 使用固定引用确保组件和测试共享同一对象
+const mockShowSuccess = vi.fn()
+const mockShowError = vi.fn()
+
+vi.mock('@/stores/app', () => ({
+  useAppStore: () => ({
+    showSuccess: mockShowSuccess,
+    showError: mockShowError,
+  }),
+}))
+
+import { useAppStore } from '@/stores/app'
+
+/**
+ * 简化的 API Key 创建测试组件
+ */
+const ApiKeyCreateTestComponent = defineComponent({
+  setup() {
+    const appStore = useAppStore()
+    const loading = ref(false)
+    const createdKey = ref('')
+    const formData = reactive({
+      name: '',
+      group_id: null as number | null,
+    })
+
+    const handleCreate = async () => {
+      if (!formData.name) return
+
+      loading.value = true
+      try {
+        const result = await mockCreate({
+          name: formData.name,
+          group_id: formData.group_id,
+        })
+        createdKey.value = result.key
+        appStore.showSuccess('API Key 创建成功')
+      } catch (error: any) {
+        appStore.showError(error.message || '创建失败')
+      } finally {
+        loading.value = false
+      }
+    }
+
+    return { formData, loading, createdKey, handleCreate }
+  },
+  template: `
+    <div>
+      <form @submit.prevent="handleCreate">
+        <input id="name" v-model="formData.name" placeholder="Key 名称" />
+        <select id="group" v-model="formData.group_id">
+          <option :value="null">默认</option>
+          <option :value="1">Group 1</option>
+        </select>
+        <button type="submit" :disabled="loading">创建</button>
+      </form>
+      <div v-if="createdKey" class="created-key">{{ createdKey }}</div>
+    </div>
+  `,
+})
+
+describe('ApiKey 创建流程', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+  })
+
+  it('创建 API Key 调用 API 并显示结果', async () => {
+    mockCreate.mockResolvedValue({
+      id: 1,
+      key: 'sk-test-key-12345',
+      name: 'My Test Key',
+    })
+
+    const wrapper = mount(ApiKeyCreateTestComponent)
+
+    await wrapper.find('#name').setValue('My Test Key')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(mockCreate).toHaveBeenCalledWith({
+      name: 'My Test Key',
+      group_id: null,
+    })
+
+    expect(wrapper.find('.created-key').text()).toBe('sk-test-key-12345')
+  })
+
+  it('选择分组后正确传参', async () => {
+    mockCreate.mockResolvedValue({
+      id: 2,
+      key: 'sk-group-key',
+      name: 'Group Key',
+    })
+
+    const wrapper = mount(ApiKeyCreateTestComponent)
+
+    await wrapper.find('#name').setValue('Group Key')
+    // 选择 group_id = 1
+    await wrapper.find('#group').setValue('1')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(mockCreate).toHaveBeenCalledWith({
+      name: 'Group Key',
+      group_id: 1,
+    })
+  })
+
+  it('创建失败时显示错误', async () => {
+    mockCreate.mockRejectedValue(new Error('配额不足'))
+
+    const wrapper = mount(ApiKeyCreateTestComponent)
+
+    await wrapper.find('#name').setValue('Fail Key')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(mockShowError).toHaveBeenCalledWith('配额不足')
+    expect(wrapper.find('.created-key').exists()).toBe(false)
+  })
+
+  it('名称为空时不提交', async () => {
+    const wrapper = mount(ApiKeyCreateTestComponent)
+
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(mockCreate).not.toHaveBeenCalled()
+  })
+
+  it('创建过程中按钮被禁用', async () => {
+    let resolveCreate: (v: any) => void
+    mockCreate.mockImplementation(
+      () => new Promise((resolve) => { resolveCreate = resolve })
+    )
+
+    const wrapper = mount(ApiKeyCreateTestComponent)
+
+    await wrapper.find('#name').setValue('Test Key')
+    await wrapper.find('form').trigger('submit')
+
+    expect(wrapper.find('button').attributes('disabled')).toBeDefined()
+
+    resolveCreate!({ id: 1, key: 'sk-test', name: 'Test Key' })
+    await flushPromises()
+
+    expect(wrapper.find('button').attributes('disabled')).toBeUndefined()
+  })
+})

frontend/src/components/__tests__/Dashboard.spec.ts

+/**
+ * Dashboard 数据加载逻辑测试
+ * 通过封装组件测试仪表板核心数据加载流程
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { setActivePinia, createPinia } from 'pinia'
+import { defineComponent, ref, onMounted, nextTick } from 'vue'
+
+// Mock API
+const mockGetDashboardStats = vi.fn()
+const mockRefreshUser = vi.fn()
+
+vi.mock('@/api', () => ({
+  authAPI: {
+    getCurrentUser: vi.fn().mockResolvedValue({
+      data: { id: 1, username: 'test', email: 'test@example.com', role: 'user', balance: 100, concurrency: 5, status: 'active', allowed_groups: null, created_at: '', updated_at: '' },
+    }),
+    logout: vi.fn(),
+    refreshToken: vi.fn(),
+  },
+  isTotp2FARequired: () => false,
+}))
+
+vi.mock('@/api/usage', () => ({
+  usageAPI: {
+    getDashboardStats: (...args: any[]) => mockGetDashboardStats(...args),
+  },
+}))
+
+vi.mock('@/api/admin/system', () => ({
+  checkUpdates: vi.fn(),
+}))
+
+vi.mock('@/api/auth', () => ({
+  getPublicSettings: vi.fn().mockResolvedValue({}),
+}))
+
+interface DashboardStats {
+  balance: number
+  api_key_count: number
+  active_api_key_count: number
+  today_requests: number
+  today_cost: number
+  today_tokens: number
+  total_tokens: number
+}
+
+/**
+ * 简化的 Dashboard 测试组件
+ */
+const DashboardTestComponent = defineComponent({
+  setup() {
+    const stats = ref<DashboardStats | null>(null)
+    const loading = ref(false)
+    const error = ref('')
+
+    const loadStats = async () => {
+      loading.value = true
+      error.value = ''
+      try {
+        stats.value = await mockGetDashboardStats()
+      } catch (e: any) {
+        error.value = e.message || '加载失败'
+      } finally {
+        loading.value = false
+      }
+    }
+
+    onMounted(loadStats)
+
+    return { stats, loading, error, loadStats }
+  },
+  template: `
+    <div>
+      <div v-if="loading" class="loading">加载中...</div>
+      <div v-if="error" class="error">{{ error }}</div>
+      <div v-if="stats" class="stats">
+        <span class="balance">{{ stats.balance }}</span>
+        <span class="api-keys">{{ stats.api_key_count }}</span>
+        <span class="today-requests">{{ stats.today_requests }}</span>
+        <span class="today-cost">{{ stats.today_cost }}</span>
+      </div>
+      <button class="refresh" @click="loadStats">刷新</button>
+    </div>
+  `,
+})
+
+describe('Dashboard 数据加载', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+  })
+
+  const fakeStats: DashboardStats = {
+    balance: 100.5,
+    api_key_count: 3,
+    active_api_key_count: 2,
+    today_requests: 150,
+    today_cost: 2.5,
+    today_tokens: 50000,
+    total_tokens: 1000000,
+  }
+
+  it('挂载后自动加载数据', async () => {
+    mockGetDashboardStats.mockResolvedValue(fakeStats)
+
+    const wrapper = mount(DashboardTestComponent)
+    await flushPromises()
+
+    expect(mockGetDashboardStats).toHaveBeenCalledTimes(1)
+    expect(wrapper.find('.balance').text()).toBe('100.5')
+    expect(wrapper.find('.api-keys').text()).toBe('3')
+    expect(wrapper.find('.today-requests').text()).toBe('150')
+    expect(wrapper.find('.today-cost').text()).toBe('2.5')
+  })
+
+  it('加载中显示 loading 状态', async () => {
+    let resolveStats: (v: any) => void
+    mockGetDashboardStats.mockImplementation(
+      () => new Promise((resolve) => { resolveStats = resolve })
+    )
+
+    const wrapper = mount(DashboardTestComponent)
+    await nextTick()
+
+    expect(wrapper.find('.loading').exists()).toBe(true)
+
+    resolveStats!(fakeStats)
+    await flushPromises()
+
+    expect(wrapper.find('.loading').exists()).toBe(false)
+    expect(wrapper.find('.stats').exists()).toBe(true)
+  })
+
+  it('加载失败时显示错误信息', async () => {
+    mockGetDashboardStats.mockRejectedValue(new Error('Network error'))
+
+    const wrapper = mount(DashboardTestComponent)
+    await flushPromises()
+
+    expect(wrapper.find('.error').text()).toBe('Network error')
+    expect(wrapper.find('.stats').exists()).toBe(false)
+  })
+
+  it('点击刷新按钮重新加载数据', async () => {
+    mockGetDashboardStats.mockResolvedValue(fakeStats)
+
+    const wrapper = mount(DashboardTestComponent)
+    await flushPromises()
+
+    expect(mockGetDashboardStats).toHaveBeenCalledTimes(1)
+
+    // 更新数据
+    const updatedStats = { ...fakeStats, today_requests: 200 }
+    mockGetDashboardStats.mockResolvedValue(updatedStats)
+
+    await wrapper.find('.refresh').trigger('click')
+    await flushPromises()
+
+    expect(mockGetDashboardStats).toHaveBeenCalledTimes(2)
+    expect(wrapper.find('.today-requests').text()).toBe('200')
+  })
+
+  it('数据为空时不显示统计信息', async () => {
+    mockGetDashboardStats.mockResolvedValue(null)
+
+    const wrapper = mount(DashboardTestComponent)
+    await flushPromises()
+
+    expect(wrapper.find('.stats').exists()).toBe(false)
+  })
+})

frontend/src/components/__tests__/LoginForm.spec.ts

+/**
+ * LoginView 组件核心逻辑测试
+ * 测试登录表单提交、验证、2FA 等场景
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { setActivePinia, createPinia } from 'pinia'
+import { defineComponent, reactive, ref } from 'vue'
+import { useAuthStore } from '@/stores/auth'
+
+// Mock 所有外部依赖
+const mockLogin = vi.fn()
+const mockLogin2FA = vi.fn()
+const mockPush = vi.fn()
+
+vi.mock('@/api', () => ({
+  authAPI: {
+    login: (...args: any[]) => mockLogin(...args),
+    login2FA: (...args: any[]) => mockLogin2FA(...args),
+    logout: vi.fn(),
+    getCurrentUser: vi.fn().mockResolvedValue({ data: {} }),
+    register: vi.fn(),
+    refreshToken: vi.fn(),
+  },
+  isTotp2FARequired: (response: any) => response?.requires_2fa === true,
+}))
+
+vi.mock('@/api/admin/system', () => ({
+  checkUpdates: vi.fn(),
+}))
+
+vi.mock('@/api/auth', () => ({
+  getPublicSettings: vi.fn().mockResolvedValue({}),
+}))
+
+/**
+ * 创建一个简化的测试组件来封装登录逻辑
+ * 避免引入 LoginView.vue 的全部依赖（AuthLayout、i18n、Icon 等）
+ */
+const LoginFormTestComponent = defineComponent({
+  setup() {
+    const authStore = useAuthStore()
+    const formData = reactive({ email: '', password: '' })
+    const isLoading = ref(false)
+    const errorMessage = ref('')
+
+    const handleLogin = async () => {
+      if (!formData.email || !formData.password) {
+        errorMessage.value = '请输入邮箱和密码'
+        return
+      }
+
+      isLoading.value = true
+      errorMessage.value = ''
+
+      try {
+        const response = await authStore.login({
+          email: formData.email,
+          password: formData.password,
+        })
+
+        // 2FA 流程由调用方处理
+        if ((response as any)?.requires_2fa) {
+          errorMessage.value = '需要 2FA 验证'
+          return
+        }
+
+        mockPush('/dashboard')
+      } catch (error: any) {
+        errorMessage.value = error.message || '登录失败'
+      } finally {
+        isLoading.value = false
+      }
+    }
+
+    return { formData, isLoading, errorMessage, handleLogin }
+  },
+  template: `
+    <form @submit.prevent="handleLogin">
+      <input id="email" v-model="formData.email" type="email" />
+      <input id="password" v-model="formData.password" type="password" />
+      <p v-if="errorMessage" class="error">{{ errorMessage }}</p>
+      <button type="submit" :disabled="isLoading">登录</button>
+    </form>
+  `,
+})
+
+describe('LoginForm 核心逻辑', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+  })
+
+  it('成功登录后跳转到 dashboard', async () => {
+    mockLogin.mockResolvedValue({
+      access_token: 'token',
+      token_type: 'Bearer',
+      user: { id: 1, username: 'test', email: 'test@example.com', role: 'user', balance: 0, concurrency: 5, status: 'active', allowed_groups: null, created_at: '', updated_at: '' },
+    })
+
+    const wrapper = mount(LoginFormTestComponent)
+
+    await wrapper.find('#email').setValue('test@example.com')
+    await wrapper.find('#password').setValue('password123')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(mockLogin).toHaveBeenCalledWith({
+      email: 'test@example.com',
+      password: 'password123',
+    })
+    expect(mockPush).toHaveBeenCalledWith('/dashboard')
+  })
+
+  it('登录失败时显示错误信息', async () => {
+    mockLogin.mockRejectedValue(new Error('Invalid credentials'))
+
+    const wrapper = mount(LoginFormTestComponent)
+
+    await wrapper.find('#email').setValue('test@example.com')
+    await wrapper.find('#password').setValue('wrong')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(wrapper.find('.error').text()).toBe('Invalid credentials')
+  })
+
+  it('空表单提交显示验证错误', async () => {
+    const wrapper = mount(LoginFormTestComponent)
+
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(wrapper.find('.error').text()).toBe('请输入邮箱和密码')
+    expect(mockLogin).not.toHaveBeenCalled()
+  })
+
+  it('需要 2FA 时不跳转', async () => {
+    mockLogin.mockResolvedValue({
+      requires_2fa: true,
+      temp_token: 'temp-123',
+    })
+
+    const wrapper = mount(LoginFormTestComponent)
+
+    await wrapper.find('#email').setValue('test@example.com')
+    await wrapper.find('#password').setValue('password123')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(mockPush).not.toHaveBeenCalled()
+    expect(wrapper.find('.error').text()).toBe('需要 2FA 验证')
+  })
+
+  it('提交过程中按钮被禁用', async () => {
+    let resolveLogin: (v: any) => void
+    mockLogin.mockImplementation(
+      () => new Promise((resolve) => { resolveLogin = resolve })
+    )
+
+    const wrapper = mount(LoginFormTestComponent)
+
+    await wrapper.find('#email').setValue('test@example.com')
+    await wrapper.find('#password').setValue('password123')
+    await wrapper.find('form').trigger('submit')
+
+    expect(wrapper.find('button').attributes('disabled')).toBeDefined()
+
+    resolveLogin!({
+      access_token: 'token',
+      token_type: 'Bearer',
+      user: { id: 1, username: 'test', email: 'test@example.com', role: 'user', balance: 0, concurrency: 5, status: 'active', allowed_groups: null, created_at: '', updated_at: '' },
+    })
+    await flushPromises()
+
+    expect(wrapper.find('button').attributes('disabled')).toBeUndefined()
+  })
+})

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

+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { setActivePinia, createPinia } from 'pinia'
+
+// Mock i18n
+vi.mock('@/i18n', () => ({
+  i18n: {
+    global: {
+      t: (key: string) => key,
+    },
+  },
+}))
+
+// Mock app store
+const mockShowSuccess = vi.fn()
+const mockShowError = vi.fn()
+
+vi.mock('@/stores/app', () => ({
+  useAppStore: () => ({
+    showSuccess: mockShowSuccess,
+    showError: mockShowError,
+  }),
+}))
+
+import { useClipboard } from '@/composables/useClipboard'
+
+describe('useClipboard', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.useFakeTimers()
+    vi.clearAllMocks()
+
+    // 默认模拟安全上下文 + Clipboard API
+    Object.defineProperty(window, 'isSecureContext', { value: true, writable: true })
+    Object.defineProperty(navigator, 'clipboard', {
+      value: {
+        writeText: vi.fn().mockResolvedValue(undefined),
+      },
+      writable: true,
+      configurable: true,
+    })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    // 恢复 execCommand
+    if ('execCommand' in document) {
+      delete (document as any).execCommand
+    }
+  })
+
+  it('复制成功后 copied 变为 true', async () => {
+    const { copied, copyToClipboard } = useClipboard()
+
+    expect(copied.value).toBe(false)
+
+    await copyToClipboard('hello')
+
+    expect(copied.value).toBe(true)
+  })
+
+  it('copied 在 2 秒后自动恢复为 false', async () => {
+    const { copied, copyToClipboard } = useClipboard()
+
+    await copyToClipboard('hello')
+    expect(copied.value).toBe(true)
+
+    vi.advanceTimersByTime(2000)
+
+    expect(copied.value).toBe(false)
+  })
+
+  it('复制成功时调用 showSuccess', async () => {
+    const { copyToClipboard } = useClipboard()
+
+    await copyToClipboard('hello', '已复制')
+
+    expect(mockShowSuccess).toHaveBeenCalledWith('已复制')
+  })
+
+  it('无自定义消息时使用 i18n 默认消息', async () => {
+    const { copyToClipboard } = useClipboard()
+
+    await copyToClipboard('hello')
+
+    expect(mockShowSuccess).toHaveBeenCalledWith('common.copiedToClipboard')
+  })
+
+  it('空文本返回 false 且不复制', async () => {
+    const { copyToClipboard, copied } = useClipboard()
+
+    const result = await copyToClipboard('')
+
+    expect(result).toBe(false)
+    expect(copied.value).toBe(false)
+    expect(navigator.clipboard.writeText).not.toHaveBeenCalled()
+  })
+
+  it('Clipboard API 失败时降级到 fallback', async () => {
+    ;(navigator.clipboard.writeText as any).mockRejectedValue(new Error('API failed'))
+
+    // jsdom 没有 execCommand，手动定义
+    ;(document as any).execCommand = vi.fn().mockReturnValue(true)
+
+    const { copyToClipboard, copied } = useClipboard()
+    const result = await copyToClipboard('fallback text')
+
+    expect(result).toBe(true)
+    expect(copied.value).toBe(true)
+    expect(document.execCommand).toHaveBeenCalledWith('copy')
+  })
+
+  it('非安全上下文使用 fallback', async () => {
+    Object.defineProperty(window, 'isSecureContext', { value: false, writable: true })
+
+    ;(document as any).execCommand = vi.fn().mockReturnValue(true)
+
+    const { copyToClipboard, copied } = useClipboard()
+    const result = await copyToClipboard('insecure context text')
+
+    expect(result).toBe(true)
+    expect(copied.value).toBe(true)
+    expect(navigator.clipboard.writeText).not.toHaveBeenCalled()
+    expect(document.execCommand).toHaveBeenCalledWith('copy')
+  })
+
+  it('所有复制方式均失败时调用 showError', async () => {
+    ;(navigator.clipboard.writeText as any).mockRejectedValue(new Error('fail'))
+    ;(document as any).execCommand = vi.fn().mockReturnValue(false)
+
+    const { copyToClipboard, copied } = useClipboard()
+    const result = await copyToClipboard('text')
+
+    expect(result).toBe(false)
+    expect(copied.value).toBe(false)
+    expect(mockShowError).toHaveBeenCalled()
+  })
+})

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

+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { setActivePinia, createPinia } from 'pinia'
+import { useForm } from '@/composables/useForm'
+import { useAppStore } from '@/stores/app'
+
+// Mock API 依赖（app store 内部引用了这些）
+vi.mock('@/api/admin/system', () => ({
+  checkUpdates: vi.fn(),
+}))
+vi.mock('@/api/auth', () => ({
+  getPublicSettings: vi.fn(),
+}))
+
+describe('useForm', () => {
+  let appStore: ReturnType<typeof useAppStore>
+
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    appStore = useAppStore()
+    vi.clearAllMocks()
+  })
+
+  it('submit 期间 loading 为 true，完成后为 false', async () => {
+    let resolveSubmit: () => void
+    const submitFn = vi.fn(
+      () => new Promise<void>((resolve) => { resolveSubmit = resolve })
+    )
+
+    const { loading, submit } = useForm({
+      form: { name: 'test' },
+      submitFn,
+    })
+
+    expect(loading.value).toBe(false)
+
+    const submitPromise = submit()
+    // 提交中
+    expect(loading.value).toBe(true)
+
+    resolveSubmit!()
+    await submitPromise
+
+    expect(loading.value).toBe(false)
+  })
+
+  it('submit 成功时显示成功消息', async () => {
+    const submitFn = vi.fn().mockResolvedValue(undefined)
+    const showSuccessSpy = vi.spyOn(appStore, 'showSuccess')
+
+    const { submit } = useForm({
+      form: { name: 'test' },
+      submitFn,
+      successMsg: '保存成功',
+    })
+
+    await submit()
+
+    expect(showSuccessSpy).toHaveBeenCalledWith('保存成功')
+  })
+
+  it('submit 成功但无 successMsg 时不调用 showSuccess', async () => {
+    const submitFn = vi.fn().mockResolvedValue(undefined)
+    const showSuccessSpy = vi.spyOn(appStore, 'showSuccess')
+
+    const { submit } = useForm({
+      form: { name: 'test' },
+      submitFn,
+    })
+
+    await submit()
+
+    expect(showSuccessSpy).not.toHaveBeenCalled()
+  })
+
+  it('submit 失败时显示错误消息并抛出错误', async () => {
+    const error = Object.assign(new Error('提交失败'), {
+      response: { data: { message: '服务器错误' } },
+    })
+    const submitFn = vi.fn().mockRejectedValue(error)
+    const showErrorSpy = vi.spyOn(appStore, 'showError')
+
+    const { submit, loading } = useForm({
+      form: { name: 'test' },
+      submitFn,
+    })
+
+    await expect(submit()).rejects.toThrow('提交失败')
+
+    expect(showErrorSpy).toHaveBeenCalled()
+    expect(loading.value).toBe(false)
+  })
+
+  it('submit 失败时使用自定义 errorMsg', async () => {
+    const submitFn = vi.fn().mockRejectedValue(new Error('network'))
+    const showErrorSpy = vi.spyOn(appStore, 'showError')
+
+    const { submit } = useForm({
+      form: { name: 'test' },
+      submitFn,
+      errorMsg: '自定义错误提示',
+    })
+
+    await expect(submit()).rejects.toThrow()
+
+    expect(showErrorSpy).toHaveBeenCalledWith('自定义错误提示')
+  })
+
+  it('loading 中不会重复提交', async () => {
+    let resolveSubmit: () => void
+    const submitFn = vi.fn(
+      () => new Promise<void>((resolve) => { resolveSubmit = resolve })
+    )
+
+    const { submit } = useForm({
+      form: { name: 'test' },
+      submitFn,
+    })
+
+    // 第一次提交
+    const p1 = submit()
+    // 第二次提交（应被忽略，因为 loading=true）
+    submit()
+
+    expect(submitFn).toHaveBeenCalledTimes(1)
+
+    resolveSubmit!()
+    await p1
+  })
+
+  it('传递 form 数据到 submitFn', async () => {
+    const formData = { name: 'test', email: 'test@example.com' }
+    const submitFn = vi.fn().mockResolvedValue(undefined)
+
+    const { submit } = useForm({
+      form: formData,
+      submitFn,
+    })
+
+    await submit()
+
+    expect(submitFn).toHaveBeenCalledWith(formData)
+  })
+})

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

+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { useTableLoader } from '@/composables/useTableLoader'
+import { nextTick } from 'vue'
+
+// Mock @vueuse/core 的 useDebounceFn
+vi.mock('@vueuse/core', () => ({
+  useDebounceFn: (fn: Function, ms: number) => {
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const debounced = (...args: any[]) => {
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => fn(...args), ms)
+    }
+    debounced.cancel = () => { if (timer) clearTimeout(timer) }
+    return debounced
+  },
+}))
+
+// Mock Vue 的 onUnmounted（composable 外使用时会报错）
+vi.mock('vue', async () => {
+  const actual = await vi.importActual('vue')
+  return {
+    ...actual,
+    onUnmounted: vi.fn(),
+  }
+})
+
+const createMockFetchFn = (items: any[] = [], total = 0, pages = 1) => {
+  return vi.fn().mockResolvedValue({ items, total, pages })
+}
+
+describe('useTableLoader', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  // --- 基础加载 ---
+
+  describe('基础加载', () => {
+    it('load 执行 fetchFn 并更新 items', async () => {
+      const mockItems = [{ id: 1, name: 'item1' }, { id: 2, name: 'item2' }]
+      const fetchFn = createMockFetchFn(mockItems, 2, 1)
+
+      const { items, loading, load, pagination } = useTableLoader({
+        fetchFn,
+      })
+
+      expect(items.value).toHaveLength(0)
+
+      await load()
+
+      expect(items.value).toEqual(mockItems)
+      expect(pagination.total).toBe(2)
+      expect(pagination.pages).toBe(1)
+      expect(loading.value).toBe(false)
+    })
+
+    it('load 期间 loading 为 true', async () => {
+      let resolveLoad: (v: any) => void
+      const fetchFn = vi.fn(
+        () => new Promise((resolve) => { resolveLoad = resolve })
+      )
+
+      const { loading, load } = useTableLoader({ fetchFn })
+
+      const p = load()
+      expect(loading.value).toBe(true)
+
+      resolveLoad!({ items: [], total: 0, pages: 0 })
+      await p
+
+      expect(loading.value).toBe(false)
+    })
+
+    it('使用默认 pageSize=20', async () => {
+      const fetchFn = createMockFetchFn()
+      const { load, pagination } = useTableLoader({ fetchFn })
+
+      await load()
+
+      expect(fetchFn).toHaveBeenCalledWith(
+        1,
+        20,
+        expect.anything(),
+        expect.objectContaining({ signal: expect.any(AbortSignal) })
+      )
+      expect(pagination.page_size).toBe(20)
+    })
+
+    it('可自定义 pageSize', async () => {
+      const fetchFn = createMockFetchFn()
+      const { load } = useTableLoader({ fetchFn, pageSize: 50 })
+
+      await load()
+
+      expect(fetchFn).toHaveBeenCalledWith(
+        1,
+        50,
+        expect.anything(),
+        expect.anything()
+      )
+    })
+  })
+
+  // --- 分页 ---
+
+  describe('分页', () => {
+    it('handlePageChange 更新页码并加载', async () => {
+      const fetchFn = createMockFetchFn([], 100, 5)
+      const { handlePageChange, pagination, load } = useTableLoader({ fetchFn })
+
+      await load() // 初始加载
+      fetchFn.mockClear()
+
+      handlePageChange(3)
+
+      expect(pagination.page).toBe(3)
+      // 等待 load 完成
+      await vi.runAllTimersAsync()
+      expect(fetchFn).toHaveBeenCalledWith(3, 20, expect.anything(), expect.anything())
+    })
+
+    it('handlePageSizeChange 重置到第1页并加载', async () => {
+      const fetchFn = createMockFetchFn([], 100, 5)
+      const { handlePageSizeChange, pagination, load } = useTableLoader({ fetchFn })
+
+      await load()
+      pagination.page = 3
+      fetchFn.mockClear()
+
+      handlePageSizeChange(50)
+
+      expect(pagination.page).toBe(1)
+      expect(pagination.page_size).toBe(50)
+    })
+
+    it('handlePageChange 限制页码范围', async () => {
+      const fetchFn = createMockFetchFn([], 100, 5)
+      const { handlePageChange, pagination, load } = useTableLoader({ fetchFn })
+
+      await load()
+
+      // 超出范围的页码被限制
+      handlePageChange(999)
+      expect(pagination.page).toBe(5) // 限制在 pages=5
+
+      handlePageChange(0)
+      expect(pagination.page).toBe(1) // 最小为 1
+    })
+  })
+
+  // --- 搜索防抖 ---
+
+  describe('搜索防抖', () => {
+    it('debouncedReload 在 300ms 内多次调用只执行一次', async () => {
+      const fetchFn = createMockFetchFn()
+      const { debouncedReload } = useTableLoader({ fetchFn })
+
+      // 快速连续调用
+      debouncedReload()
+      debouncedReload()
+      debouncedReload()
+
+      // 还没到 300ms，不应调用 fetchFn
+      expect(fetchFn).not.toHaveBeenCalled()
+
+      // 推进 300ms
+      vi.advanceTimersByTime(300)
+
+      // 等待异步完成
+      await vi.runAllTimersAsync()
+
+      expect(fetchFn).toHaveBeenCalledTimes(1)
+    })
+
+    it('reload 重置到第 1 页', async () => {
+      const fetchFn = createMockFetchFn([], 100, 5)
+      const { reload, pagination, load } = useTableLoader({ fetchFn })
+
+      await load()
+      pagination.page = 3
+
+      await reload()
+
+      expect(pagination.page).toBe(1)
+    })
+  })
+
+  // --- 请求取消 ---
+
+  describe('请求取消', () => {
+    it('新请求取消前一个未完成的请求', async () => {
+      let callCount = 0
+      const fetchFn = vi.fn((_page, _size, _params, options) => {
+        callCount++
+        const currentCall = callCount
+        return new Promise((resolve, reject) => {
+          // 模拟监听 abort
+          if (options?.signal) {
+            options.signal.addEventListener('abort', () => {
+              reject({ name: 'CanceledError', code: 'ERR_CANCELED' })
+            })
+          }
+          // 异步解决
+          setTimeout(() => {
+            resolve({ items: [{ id: currentCall }], total: 1, pages: 1 })
+          }, 1000)
+        })
+      })
+
+      const { load, items } = useTableLoader({ fetchFn })
+
+      // 第一次加载
+      const p1 = load()
+      // 第二次加载（应取消第一次）
+      const p2 = load()
+
+      // 推进时间让第二次完成
+      vi.advanceTimersByTime(1000)
+      await vi.runAllTimersAsync()
+
+      // 等待两个 Promise settle
+      await Promise.allSettled([p1, p2])
+
+      // 第二次请求的结果生效
+      expect(fetchFn).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  // --- 错误处理 ---
+
+  describe('错误处理', () => {
+    it('非取消错误会被抛出', async () => {
+      const fetchFn = vi.fn().mockRejectedValue(new Error('Server error'))
+      const { load } = useTableLoader({ fetchFn })
+
+      await expect(load()).rejects.toThrow('Server error')
+    })
+
+    it('取消错误被静默处理', async () => {
+      const fetchFn = vi.fn().mockRejectedValue({ name: 'CanceledError', code: 'ERR_CANCELED' })
+      const { load } = useTableLoader({ fetchFn })
+
+      // 不应抛出
+      await load()
+    })
+  })
+})

frontend/src/router/__tests__/guards.spec.ts

+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { createRouter, createMemoryHistory } from 'vue-router'
+import { setActivePinia, createPinia } from 'pinia'
+import { defineComponent, h } from 'vue'
+
+// Mock 导航加载状态
+vi.mock('@/composables/useNavigationLoading', () => {
+  const mockStart = vi.fn()
+  const mockEnd = vi.fn()
+  return {
+    useNavigationLoadingState: () => ({
+      startNavigation: mockStart,
+      endNavigation: mockEnd,
+      isLoading: { value: false },
+    }),
+    useNavigationLoading: () => ({
+      startNavigation: mockStart,
+      endNavigation: mockEnd,
+      isLoading: { value: false },
+    }),
+  }
+})
+
+// Mock 路由预加载
+vi.mock('@/composables/useRoutePrefetch', () => ({
+  useRoutePrefetch: () => ({
+    triggerPrefetch: vi.fn(),
+    cancelPendingPrefetch: vi.fn(),
+    resetPrefetchState: vi.fn(),
+  }),
+}))
+
+// Mock API 相关模块
+vi.mock('@/api', () => ({
+  authAPI: {
+    getCurrentUser: vi.fn().mockResolvedValue({ data: {} }),
+    logout: vi.fn(),
+  },
+  isTotp2FARequired: () => false,
+}))
+
+vi.mock('@/api/admin/system', () => ({
+  checkUpdates: vi.fn(),
+}))
+
+vi.mock('@/api/auth', () => ({
+  getPublicSettings: vi.fn(),
+}))
+
+const DummyComponent = defineComponent({
+  render() {
+    return h('div', 'dummy')
+  },
+})
+
+/**
+ * 创建带守卫逻辑的测试路由
+ * 模拟 router/index.ts 中的 beforeEach 守卫逻辑
+ */
+function createTestRouter() {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/login', component: DummyComponent, meta: { requiresAuth: false, title: 'Login' } },
+      {
+        path: '/register',
+        component: DummyComponent,
+        meta: { requiresAuth: false, title: 'Register' },
+      },
+      { path: '/home', component: DummyComponent, meta: { requiresAuth: false, title: 'Home' } },
+      { path: '/dashboard', component: DummyComponent, meta: { title: 'Dashboard' } },
+      { path: '/keys', component: DummyComponent, meta: { title: 'API Keys' } },
+      { path: '/subscriptions', component: DummyComponent, meta: { title: 'Subscriptions' } },
+      { path: '/redeem', component: DummyComponent, meta: { title: 'Redeem' } },
+      {
+        path: '/admin/dashboard',
+        component: DummyComponent,
+        meta: { requiresAdmin: true, title: 'Admin Dashboard' },
+      },
+      {
+        path: '/admin/users',
+        component: DummyComponent,
+        meta: { requiresAdmin: true, title: 'Admin Users' },
+      },
+      {
+        path: '/admin/groups',
+        component: DummyComponent,
+        meta: { requiresAdmin: true, title: 'Admin Groups' },
+      },
+      {
+        path: '/admin/subscriptions',
+        component: DummyComponent,
+        meta: { requiresAdmin: true, title: 'Admin Subscriptions' },
+      },
+      {
+        path: '/admin/redeem',
+        component: DummyComponent,
+        meta: { requiresAdmin: true, title: 'Admin Redeem' },
+      },
+    ],
+  })
+
+  return router
+}
+
+// 用于测试的 auth 状态
+interface MockAuthState {
+  isAuthenticated: boolean
+  isAdmin: boolean
+  isSimpleMode: boolean
+}
+
+/**
+ * 将 router/index.ts 中 beforeEach 守卫的核心逻辑提取为可测试的函数
+ */
+function simulateGuard(
+  toPath: string,
+  toMeta: Record<string, any>,
+  authState: MockAuthState
+): string | null {
+  const requiresAuth = toMeta.requiresAuth !== false
+  const requiresAdmin = toMeta.requiresAdmin === true
+
+  // 不需要认证的路由
+  if (!requiresAuth) {
+    if (
+      authState.isAuthenticated &&
+      (toPath === '/login' || toPath === '/register')
+    ) {
+      return authState.isAdmin ? '/admin/dashboard' : '/dashboard'
+    }
+    return null // 允许通过
+  }
+
+  // 需要认证但未登录
+  if (!authState.isAuthenticated) {
+    return '/login'
+  }
+
+  // 需要管理员但不是管理员
+  if (requiresAdmin && !authState.isAdmin) {
+    return '/dashboard'
+  }
+
+  // 简易模式限制
+  if (authState.isSimpleMode) {
+    const restrictedPaths = [
+      '/admin/groups',
+      '/admin/subscriptions',
+      '/admin/redeem',
+      '/subscriptions',
+      '/redeem',
+    ]
+    if (restrictedPaths.some((path) => toPath.startsWith(path))) {
+      return authState.isAdmin ? '/admin/dashboard' : '/dashboard'
+    }
+  }
+
+  return null // 允许通过
+}
+
+describe('路由守卫逻辑', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  // --- 未认证用户 ---
+
+  describe('未认证用户', () => {
+    const authState: MockAuthState = {
+      isAuthenticated: false,
+      isAdmin: false,
+      isSimpleMode: false,
+    }
+
+    it('访问需要认证的页面重定向到 /login', () => {
+      const redirect = simulateGuard('/dashboard', {}, authState)
+      expect(redirect).toBe('/login')
+    })
+
+    it('访问管理页面重定向到 /login', () => {
+      const redirect = simulateGuard('/admin/dashboard', { requiresAdmin: true }, authState)
+      expect(redirect).toBe('/login')
+    })
+
+    it('访问公开页面允许通过', () => {
+      const redirect = simulateGuard('/login', { requiresAuth: false }, authState)
+      expect(redirect).toBeNull()
+    })
+
+    it('访问 /home 公开页面允许通过', () => {
+      const redirect = simulateGuard('/home', { requiresAuth: false }, authState)
+      expect(redirect).toBeNull()
+    })
+  })
+
+  // --- 已认证普通用户 ---
+
+  describe('已认证普通用户', () => {
+    const authState: MockAuthState = {
+      isAuthenticated: true,
+      isAdmin: false,
+      isSimpleMode: false,
+    }
+
+    it('访问 /login 重定向到 /dashboard', () => {
+      const redirect = simulateGuard('/login', { requiresAuth: false }, authState)
+      expect(redirect).toBe('/dashboard')
+    })
+
+    it('访问 /register 重定向到 /dashboard', () => {
+      const redirect = simulateGuard('/register', { requiresAuth: false }, authState)
+      expect(redirect).toBe('/dashboard')
+    })
+
+    it('访问 /dashboard 允许通过', () => {
+      const redirect = simulateGuard('/dashboard', {}, authState)
+      expect(redirect).toBeNull()
+    })
+
+    it('访问管理页面被拒绝，重定向到 /dashboard', () => {
+      const redirect = simulateGuard('/admin/dashboard', { requiresAdmin: true }, authState)
+      expect(redirect).toBe('/dashboard')
+    })
+
+    it('访问 /admin/users 被拒绝', () => {
+      const redirect = simulateGuard('/admin/users', { requiresAdmin: true }, authState)
+      expect(redirect).toBe('/dashboard')
+    })
+  })
+
+  // --- 已认证管理员 ---
+
+  describe('已认证管理员', () => {
+    const authState: MockAuthState = {
+      isAuthenticated: true,
+      isAdmin: true,
+      isSimpleMode: false,
+    }
+
+    it('访问 /login 重定向到 /admin/dashboard', () => {
+      const redirect = simulateGuard('/login', { requiresAuth: false }, authState)
+      expect(redirect).toBe('/admin/dashboard')
+    })
+
+    it('访问管理页面允许通过', () => {
+      const redirect = simulateGuard('/admin/dashboard', { requiresAdmin: true }, authState)
+      expect(redirect).toBeNull()
+    })
+
+    it('访问用户页面允许通过', () => {
+      const redirect = simulateGuard('/dashboard', {}, authState)
+      expect(redirect).toBeNull()
+    })
+  })
+
+  // --- 简易模式 ---
+
+  describe('简易模式受限路由', () => {
+    it('普通用户简易模式访问 /subscriptions 重定向到 /dashboard', () => {
+      const authState: MockAuthState = {
+        isAuthenticated: true,
+        isAdmin: false,
+        isSimpleMode: true,
+      }
+      const redirect = simulateGuard('/subscriptions', {}, authState)
+      expect(redirect).toBe('/dashboard')
+    })
+
+    it('普通用户简易模式访问 /redeem 重定向到 /dashboard', () => {
+      const authState: MockAuthState = {
+        isAuthenticated: true,
+        isAdmin: false,
+        isSimpleMode: true,
+      }
+      const redirect = simulateGuard('/redeem', {}, authState)
+      expect(redirect).toBe('/dashboard')
+    })
+
+    it('管理员简易模式访问 /admin/groups 重定向到 /admin/dashboard', () => {
+      const authState: MockAuthState = {
+        isAuthenticated: true,
+        isAdmin: true,
+        isSimpleMode: true,
+      }
+      const redirect = simulateGuard('/admin/groups', { requiresAdmin: true }, authState)
+      expect(redirect).toBe('/admin/dashboard')
+    })
+
+    it('管理员简易模式访问 /admin/subscriptions 重定向', () => {
+      const authState: MockAuthState = {
+        isAuthenticated: true,
+        isAdmin: true,
+        isSimpleMode: true,
+      }
+      const redirect = simulateGuard(
+        '/admin/subscriptions',
+        { requiresAdmin: true },
+        authState
+      )
+      expect(redirect).toBe('/admin/dashboard')
+    })
+
+    it('简易模式下非受限页面正常访问', () => {
+      const authState: MockAuthState = {
+        isAuthenticated: true,
+        isAdmin: false,
+        isSimpleMode: true,
+      }
+      const redirect = simulateGuard('/dashboard', {}, authState)
+      expect(redirect).toBeNull()
+    })
+
+    it('简易模式下 /keys 正常访问', () => {
+      const authState: MockAuthState = {
+        isAuthenticated: true,
+        isAdmin: false,
+        isSimpleMode: true,
+      }
+      const redirect = simulateGuard('/keys', {}, authState)
+      expect(redirect).toBeNull()
+    })
+  })
+})

frontend/src/stores/__tests__/app.spec.ts

+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { setActivePinia, createPinia } from 'pinia'
+import { useAppStore } from '@/stores/app'
+
+// Mock API 模块
+vi.mock('@/api/admin/system', () => ({
+  checkUpdates: vi.fn(),
+}))
+
+vi.mock('@/api/auth', () => ({
+  getPublicSettings: vi.fn(),
+}))
+
+describe('useAppStore', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.useFakeTimers()
+    // 清除 window.__APP_CONFIG__
+    delete (window as any).__APP_CONFIG__
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  // --- Toast 消息管理 ---
+
+  describe('Toast 消息管理', () => {
+    it('showSuccess 创建 success 类型 toast', () => {
+      const store = useAppStore()
+      const id = store.showSuccess('操作成功')
+
+      expect(id).toMatch(/^toast-/)
+      expect(store.toasts).toHaveLength(1)
+      expect(store.toasts[0].type).toBe('success')
+      expect(store.toasts[0].message).toBe('操作成功')
+    })
+
+    it('showError 创建 error 类型 toast', () => {
+      const store = useAppStore()
+      store.showError('出错了')
+
+      expect(store.toasts).toHaveLength(1)
+      expect(store.toasts[0].type).toBe('error')
+      expect(store.toasts[0].message).toBe('出错了')
+    })
+
+    it('showWarning 创建 warning 类型 toast', () => {
+      const store = useAppStore()
+      store.showWarning('警告信息')
+
+      expect(store.toasts).toHaveLength(1)
+      expect(store.toasts[0].type).toBe('warning')
+    })
+
+    it('showInfo 创建 info 类型 toast', () => {
+      const store = useAppStore()
+      store.showInfo('提示信息')
+
+      expect(store.toasts).toHaveLength(1)
+      expect(store.toasts[0].type).toBe('info')
+    })
+
+    it('toast 在指定 duration 后自动消失', () => {
+      const store = useAppStore()
+      store.showSuccess('临时消息', 3000)
+
+      expect(store.toasts).toHaveLength(1)
+
+      vi.advanceTimersByTime(3000)
+
+      expect(store.toasts).toHaveLength(0)
+    })
+
+    it('hideToast 移除指定 toast', () => {
+      const store = useAppStore()
+      const id = store.showSuccess('消息1')
+      store.showError('消息2')
+
+      expect(store.toasts).toHaveLength(2)
+
+      store.hideToast(id)
+
+      expect(store.toasts).toHaveLength(1)
+      expect(store.toasts[0].type).toBe('error')
+    })
+
+    it('clearAllToasts 清除所有 toast', () => {
+      const store = useAppStore()
+      store.showSuccess('消息1')
+      store.showError('消息2')
+      store.showWarning('消息3')
+
+      expect(store.toasts).toHaveLength(3)
+
+      store.clearAllToasts()
+
+      expect(store.toasts).toHaveLength(0)
+    })
+
+    it('hasActiveToasts 正确反映 toast 状态', () => {
+      const store = useAppStore()
+      expect(store.hasActiveToasts).toBe(false)
+
+      store.showSuccess('消息')
+      expect(store.hasActiveToasts).toBe(true)
+
+      store.clearAllToasts()
+      expect(store.hasActiveToasts).toBe(false)
+    })
+
+    it('多个 toast 的 ID 唯一', () => {
+      const store = useAppStore()
+      const id1 = store.showSuccess('消息1')
+      const id2 = store.showSuccess('消息2')
+      const id3 = store.showSuccess('消息3')
+
+      expect(id1).not.toBe(id2)
+      expect(id2).not.toBe(id3)
+    })
+  })
+
+  // --- 侧边栏 ---
+
+  describe('侧边栏管理', () => {
+    it('toggleSidebar 切换折叠状态', () => {
+      const store = useAppStore()
+      expect(store.sidebarCollapsed).toBe(false)
+
+      store.toggleSidebar()
+      expect(store.sidebarCollapsed).toBe(true)
+
+      store.toggleSidebar()
+      expect(store.sidebarCollapsed).toBe(false)
+    })
+
+    it('setSidebarCollapsed 直接设置状态', () => {
+      const store = useAppStore()
+
+      store.setSidebarCollapsed(true)
+      expect(store.sidebarCollapsed).toBe(true)
+
+      store.setSidebarCollapsed(false)
+      expect(store.sidebarCollapsed).toBe(false)
+    })
+
+    it('toggleMobileSidebar 切换移动端状态', () => {
+      const store = useAppStore()
+      expect(store.mobileOpen).toBe(false)
+
+      store.toggleMobileSidebar()
+      expect(store.mobileOpen).toBe(true)
+
+      store.toggleMobileSidebar()
+      expect(store.mobileOpen).toBe(false)
+    })
+  })
+
+  // --- Loading 状态 ---
+
+  describe('Loading 状态管理', () => {
+    it('setLoading 管理引用计数', () => {
+      const store = useAppStore()
+      expect(store.loading).toBe(false)
+
+      store.setLoading(true)
+      expect(store.loading).toBe(true)
+
+      store.setLoading(true) // 两次 true
+      expect(store.loading).toBe(true)
+
+      store.setLoading(false) // 第一次 false，计数还是 1
+      expect(store.loading).toBe(true)
+
+      store.setLoading(false) // 第二次 false，计数为 0
+      expect(store.loading).toBe(false)
+    })
+
+    it('setLoading(false) 不会使计数为负', () => {
+      const store = useAppStore()
+
+      store.setLoading(false)
+      store.setLoading(false)
+      expect(store.loading).toBe(false)
+
+      store.setLoading(true)
+      expect(store.loading).toBe(true)
+
+      store.setLoading(false)
+      expect(store.loading).toBe(false)
+    })
+
+    it('withLoading 自动管理 loading 状态', async () => {
+      const store = useAppStore()
+
+      const result = await store.withLoading(async () => {
+        expect(store.loading).toBe(true)
+        return 'done'
+      })
+
+      expect(result).toBe('done')
+      expect(store.loading).toBe(false)
+    })
+
+    it('withLoading 错误时也恢复 loading 状态', async () => {
+      const store = useAppStore()
+
+      await expect(
+        store.withLoading(async () => {
+          throw new Error('操作失败')
+        })
+      ).rejects.toThrow('操作失败')
+
+      expect(store.loading).toBe(false)
+    })
+
+    it('withLoadingAndError 错误时显示 toast 并返回 null', async () => {
+      const store = useAppStore()
+
+      const result = await store.withLoadingAndError(async () => {
+        throw new Error('网络错误')
+      })
+
+      expect(result).toBeNull()
+      expect(store.loading).toBe(false)
+      expect(store.toasts).toHaveLength(1)
+      expect(store.toasts[0].type).toBe('error')
+    })
+  })
+
+  // --- reset ---
+
+  describe('reset', () => {
+    it('重置所有 UI 状态', () => {
+      const store = useAppStore()
+
+      store.setSidebarCollapsed(true)
+      store.setLoading(true)
+      store.showSuccess('消息')
+
+      store.reset()
+
+      expect(store.sidebarCollapsed).toBe(false)
+      expect(store.loading).toBe(false)
+      expect(store.toasts).toHaveLength(0)
+    })
+  })
+
+  // --- 公开设置 ---
+
+  describe('公开设置加载', () => {
+    it('从 window.__APP_CONFIG__ 初始化', () => {
+      ;(window as any).__APP_CONFIG__ = {
+        site_name: 'TestSite',
+        site_logo: '/logo.png',
+        version: '1.0.0',
+        contact_info: 'test@test.com',
+        api_base_url: 'https://api.test.com',
+        doc_url: 'https://docs.test.com',
+      }
+
+      const store = useAppStore()
+      const result = store.initFromInjectedConfig()
+
+      expect(result).toBe(true)
+      expect(store.siteName).toBe('TestSite')
+      expect(store.siteLogo).toBe('/logo.png')
+      expect(store.siteVersion).toBe('1.0.0')
+      expect(store.publicSettingsLoaded).toBe(true)
+    })
+
+    it('无注入配置时返回 false', () => {
+      const store = useAppStore()
+      const result = store.initFromInjectedConfig()
+
+      expect(result).toBe(false)
+      expect(store.publicSettingsLoaded).toBe(false)
+    })
+
+    it('clearPublicSettingsCache 清除缓存', () => {
+      ;(window as any).__APP_CONFIG__ = { site_name: 'Test' }
+      const store = useAppStore()
+      store.initFromInjectedConfig()
+
+      expect(store.publicSettingsLoaded).toBe(true)
+
+      store.clearPublicSettingsCache()
+
+      expect(store.publicSettingsLoaded).toBe(false)
+      expect(store.cachedPublicSettings).toBeNull()
+    })
+  })
+})