feat(quota): load quota page from cached snapshots

Hydrate quota cards from backend cache snapshots, route manual refresh actions through quota-cache APIs, and surface cache metadata in the management UI.

Author: NGLSL

src/components/quota/QuotaCard.tsx

@@ -1,21 +1,21 @@
 /**
- * Generic quota card component.
+ * 通用 quota 卡片组件。
  */
 
 import { useTranslation } from 'react-i18next';
 import type { ReactElement, ReactNode } from 'react';
 import type { TFunction } from 'i18next';
-import type { AuthFileItem, ResolvedTheme, ThemeColors } from '@/types';
-import { TYPE_COLORS } from '@/utils/quota';
+import type {
+  AuthFileItem,
+  QuotaCacheStatus,
+  QuotaStateBase,
+  ResolvedTheme,
+  ThemeColors
+} from '@/types';
+import { formatQuotaResetTime, TYPE_COLORS } from '@/utils/quota';
 import styles from '@/pages/QuotaPage.module.scss';
 
-type QuotaStatus = 'idle' | 'loading' | 'success' | 'error';
-
-export interface QuotaStatusState {
-  status: QuotaStatus;
-  error?: string;
-  errorStatus?: number;
-}
+export type QuotaStatusState = QuotaStateBase;
 
 export interface QuotaProgressBarProps {
   percent: number | null;
@@ -69,6 +69,28 @@ interface QuotaCardProps<TState extends QuotaStatusState> {
   renderQuotaItems: (quota: TState, t: TFunction, helpers: QuotaRenderHelpers) => ReactNode;
 }
 
+/**
+ * 根据后端缓存状态选择对应的徽标样式，方便在卡片底部统一展示缓存健康度。
+ */
+const resolveCacheStatusClassName = (status: QuotaCacheStatus): string => {
+  switch (status) {
+    case 'fresh':
+      return styles.quotaCacheBadgeFresh;
+    case 'refreshing':
+      return styles.quotaCacheBadgeRefreshing;
+    case 'rate_limited':
+      return styles.quotaCacheBadgeRateLimited;
+    case 'unauthorized':
+      return styles.quotaCacheBadgeUnauthorized;
+    case 'error':
+      return styles.quotaCacheBadgeError;
+    case 'pending':
+      return styles.quotaCacheBadgePending;
+    default:
+      return '';
+  }
+};
+
 export function QuotaCard<TState extends QuotaStatusState>({
   item,
   quota,
@@ -95,6 +117,11 @@ export function QuotaCard<TState extends QuotaStatusState>({
     quota?.error || t('common.unknown_error')
   );
   const idleMessageKey = onRefresh ? `${i18nPrefix}.idle` : (cardIdleMessageKey ?? `${i18nPrefix}.idle`);
+  const cacheStatus = quota?.cacheStatus;
+  const cacheStatusLabel = cacheStatus ? t(`quota_management.cache_status_${cacheStatus}`) : null;
+  const lastRefreshLabel = quota?.lastRefreshAt ? formatQuotaResetTime(quota.lastRefreshAt) : null;
+  const quotaRecoverLabel = quota?.quotaRecoverAt ? formatQuotaResetTime(quota.quotaRecoverAt) : null;
+  const showCacheMeta = Boolean(cacheStatusLabel || lastRefreshLabel || quotaRecoverLabel);
 
   const getTypeLabel = (type: string): string => {
     const key = `auth_files.filter_${type}`;
@@ -148,6 +175,33 @@ export function QuotaCard<TState extends QuotaStatusState>({
           <div className={styles.quotaMessage}>{t(idleMessageKey)}</div>
         )}
       </div>
+
+      {showCacheMeta && (
+        <div className={styles.quotaCacheMeta}>
+          {cacheStatusLabel && cacheStatus && (
+            <div className={styles.quotaCacheItem}>
+              <span className={styles.quotaCacheLabel}>{t('quota_management.cache_status_label')}</span>
+              <span
+                className={`${styles.quotaCacheBadge} ${resolveCacheStatusClassName(cacheStatus)}`}
+              >
+                {cacheStatusLabel}
+              </span>
+            </div>
+          )}
+          {lastRefreshLabel && (
+            <div className={styles.quotaCacheItem}>
+              <span className={styles.quotaCacheLabel}>{t('quota_management.last_refresh')}</span>
+              <span className={styles.quotaCacheValue}>{lastRefreshLabel}</span>
+            </div>
+          )}
+          {quotaRecoverLabel && (
+            <div className={styles.quotaCacheItem}>
+              <span className={styles.quotaCacheLabel}>{t('quota_management.quota_recover_at')}</span>
+              <span className={styles.quotaCacheValue}>{quotaRecoverLabel}</span>
+            </div>
+          )}
+        </div>
+      )}
     </div>
   );
 }

src/components/quota/QuotaSection.tsx

@@ -1,16 +1,14 @@
 /**
- * Generic quota section component.
+ * 通用 quota 分区组件。
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { Card } from '@/components/ui/Card';
 import { Button } from '@/components/ui/Button';
 import { EmptyState } from '@/components/ui/EmptyState';
-import { triggerHeaderRefresh } from '@/hooks/useHeaderRefresh';
 import { useNotificationStore, useQuotaStore, useThemeStore } from '@/stores';
 import type { AuthFileItem, ResolvedTheme } from '@/types';
-import { getStatusFromError } from '@/utils/quota';
 import { QuotaCard } from './QuotaCard';
 import type { QuotaStatusState } from './QuotaCard';
 import { useQuotaLoader } from './useQuotaLoader';
@@ -111,8 +109,7 @@ export function QuotaSection<TState extends QuotaStatusState, TData>({
     Record<string, TState>
   >;
 
-  /* Removed useRef */
-  const [columns, gridRef] = useGridColumns(380); // Min card width 380px matches SCSS
+  const [columns, gridRef] = useGridColumns(380);
   const [viewMode, setViewMode] = useState<ViewMode>('paged');
   const [showTooManyWarning, setShowTooManyWarning] = useState(false);
 
@@ -151,40 +148,25 @@ export function QuotaSection<TState extends QuotaStatusState, TData>({
     };
   }, [showAllAllowed, viewMode]);
 
-  // Update page size based on view mode and columns
   useEffect(() => {
     if (effectiveViewMode === 'all') {
       setPageSize(Math.max(1, filteredFiles.length));
     } else {
-      // Paged mode: 3 rows * columns, capped to avoid oversized pages.
       setPageSize(Math.min(columns * 3, MAX_ITEMS_PER_PAGE));
     }
   }, [effectiveViewMode, columns, filteredFiles.length, setPageSize]);
 
   const { quota, loadQuota } = useQuotaLoader(config);
 
-  const pendingQuotaRefreshRef = useRef(false);
-  const prevFilesLoadingRef = useRef(loading);
-
-  const handleRefresh = useCallback(() => {
-    pendingQuotaRefreshRef.current = true;
-    void triggerHeaderRefresh();
-  }, []);
-
-  useEffect(() => {
-    const wasLoading = prevFilesLoadingRef.current;
-    prevFilesLoadingRef.current = loading;
-
-    if (!pendingQuotaRefreshRef.current) return;
-    if (loading) return;
-    if (!wasLoading) return;
-
-    pendingQuotaRefreshRef.current = false;
-    const scope = effectiveViewMode === 'all' ? 'all' : 'page';
-    const targets = effectiveViewMode === 'all' ? filteredFiles : pageItems;
-    if (targets.length === 0) return;
-    loadQuota(targets, scope, setLoading);
-  }, [loading, effectiveViewMode, filteredFiles, pageItems, loadQuota, setLoading]);
+  const refreshScope = effectiveViewMode === 'all' ? 'all' : 'page';
+  const refreshTargets = useMemo(
+    () => (refreshScope === 'all' ? filteredFiles : pageItems),
+    [filteredFiles, pageItems, refreshScope]
+  );
+  const refreshButtonLabel =
+    refreshScope === 'all'
+      ? t('quota_management.refresh_all_credentials')
+      : t('quota_management.refresh_current_page_credentials');
 
   useEffect(() => {
     if (loading) return;
@@ -204,37 +186,46 @@ export function QuotaSection<TState extends QuotaStatusState, TData>({
     });
   }, [filteredFiles, loading, setQuota]);
 
+  const handleRefresh = useCallback(async () => {
+    if (disabled || refreshTargets.length === 0) return;
+
+    try {
+      await loadQuota(refreshTargets, refreshScope, setLoading);
+      showNotification(
+        t('quota_management.refresh_selection_success', { count: refreshTargets.length }),
+        'success'
+      );
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : t('common.unknown_error');
+      showNotification(t('quota_management.refresh_selection_failed', { message }), 'error');
+    }
+  }, [
+    disabled,
+    loadQuota,
+    refreshScope,
+    refreshTargets,
+    setLoading,
+    showNotification,
+    t
+  ]);
+
   const refreshQuotaForFile = useCallback(
     async (file: AuthFileItem) => {
       if (disabled || file.disabled) return;
       if (quota[file.name]?.status === 'loading') return;
 
-      setQuota((prev) => ({
-        ...prev,
-        [file.name]: config.buildLoadingState()
-      }));
-
       try {
-        const data = await config.fetchQuota(file, t);
-        setQuota((prev) => ({
-          ...prev,
-          [file.name]: config.buildSuccessState(data)
-        }));
+        await loadQuota([file], 'page', setLoading);
         showNotification(t('auth_files.quota_refresh_success', { name: file.name }), 'success');
       } catch (err: unknown) {
         const message = err instanceof Error ? err.message : t('common.unknown_error');
-        const status = getStatusFromError(err);
-        setQuota((prev) => ({
-          ...prev,
-          [file.name]: config.buildErrorState(message, status)
-        }));
         showNotification(
           t('auth_files.quota_refresh_failed', { name: file.name, message }),
           'error'
         );
       }
     },
-    [config, disabled, quota, setQuota, showNotification, t]
+    [disabled, loadQuota, quota, setLoading, showNotification, t]
   );
 
   const titleNode = (
@@ -287,14 +278,14 @@ export function QuotaSection<TState extends QuotaStatusState, TData>({
             variant="secondary"
             size="sm"
             className={styles.refreshAllButton}
-            onClick={handleRefresh}
-            disabled={disabled || isRefreshing}
+            onClick={() => void handleRefresh()}
+            disabled={disabled || isRefreshing || refreshTargets.length === 0}
             loading={isRefreshing}
-            title={t('quota_management.refresh_all_credentials')}
-            aria-label={t('quota_management.refresh_all_credentials')}
+            title={refreshButtonLabel}
+            aria-label={refreshButtonLabel}
           >
             {!isRefreshing && <IconRefreshCw size={16} />}
-            {t('quota_management.refresh_all_credentials')}
+            {refreshButtonLabel}
           </Button>
         </div>
       }

src/components/quota/index.ts

@@ -5,5 +5,13 @@
 export { QuotaSection } from './QuotaSection';
 export { QuotaCard } from './QuotaCard';
 export { useQuotaLoader } from './useQuotaLoader';
-export { ANTIGRAVITY_CONFIG, CLAUDE_CONFIG, CODEX_CONFIG, GEMINI_CLI_CONFIG, KIMI_CONFIG } from './quotaConfigs';
+export {
+  ANTIGRAVITY_CONFIG,
+  CLAUDE_CONFIG,
+  CODEX_CONFIG,
+  GEMINI_CLI_CONFIG,
+  KIMI_CONFIG,
+  buildQuotaStateMapFromEntries,
+  buildQuotaStoresFromSnapshot,
+} from './quotaConfigs';
 export type { QuotaConfig } from './quotaConfigs';