Merge pull request #1637 from touwaeriol/feat/websearch-notify-pricing

feat: web search emulation, balance/quota notify, account stats pricing, per-provider refund control, Stripe fix / Web 搜索模拟、余额配额通知、渠道统计计费、按服务商退款控制、Stripe 修复

backend/internal/service/websearch_config.go

+package service
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"sync/atomic"
+	"time"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/websearch"
+	"golang.org/x/sync/singleflight"
+)
+
+// WebSearchEmulationConfig holds the global web search emulation configuration.
+type WebSearchEmulationConfig struct {
+	Enabled   bool                      `json:"enabled"`
+	Providers []WebSearchProviderConfig `json:"providers"`
+}
+
+// WebSearchProviderConfig describes a single search provider (Brave or Tavily).
+type WebSearchProviderConfig struct {
+	Type             string `json:"type"`                    // websearch.ProviderTypeBrave | Tavily
+	APIKey           string `json:"api_key,omitempty"`       // secret — omitted in API responses
+	APIKeyConfigured bool   `json:"api_key_configured"`      // read-only mask
+	QuotaLimit       *int64 `json:"quota_limit"`             // nil = unlimited, >0 = limited
+	SubscribedAt     *int64 `json:"subscribed_at,omitempty"` // subscription start (unix seconds); quota resets monthly
+	QuotaUsed        int64  `json:"quota_used,omitempty"`    // read-only: current usage from Redis
+	ProxyID          *int64 `json:"proxy_id"`                // optional proxy association
+	ExpiresAt        *int64 `json:"expires_at,omitempty"`    // optional expiration timestamp
+}
+
+// --- Validation ---
+
+const maxWebSearchProviders = 10
+
+var validProviderTypes = map[string]bool{
+	websearch.ProviderTypeBrave:  true,
+	websearch.ProviderTypeTavily: true,
+}
+
+func validateWebSearchConfig(cfg *WebSearchEmulationConfig) error {
+	if cfg == nil {
+		return nil
+	}
+	if len(cfg.Providers) > maxWebSearchProviders {
+		return fmt.Errorf("too many providers (max %d)", maxWebSearchProviders)
+	}
+	seen := make(map[string]bool, len(cfg.Providers))
+	for i, p := range cfg.Providers {
+		if !validProviderTypes[p.Type] {
+			return fmt.Errorf("provider[%d]: invalid type %q", i, p.Type)
+		}
+		if p.QuotaLimit != nil && *p.QuotaLimit < 0 {
+			return fmt.Errorf("provider[%d]: quota_limit must be > 0 or null", i)
+		}
+		if seen[p.Type] {
+			return fmt.Errorf("provider[%d]: duplicate type %q", i, p.Type)
+		}
+		seen[p.Type] = true
+	}
+	return nil
+}
+
+// --- In-process cache (same pattern as gateway forwarding settings) ---
+
+const sfKeyWebSearchConfig = "web_search_emulation_config"
+
+type cachedWebSearchEmulationConfig struct {
+	config    *WebSearchEmulationConfig
+	expiresAt int64 // unix nano
+}
+
+var webSearchEmulationCache atomic.Value // *cachedWebSearchEmulationConfig
+var webSearchEmulationSF singleflight.Group
+
+const (
+	webSearchEmulationCacheTTL  = 60 * time.Second
+	webSearchEmulationErrorTTL  = 5 * time.Second
+	webSearchEmulationDBTimeout = 5 * time.Second
+)
+
+// GetWebSearchEmulationConfig returns the configuration with in-process cache + singleflight.
+func (s *SettingService) GetWebSearchEmulationConfig(ctx context.Context) (*WebSearchEmulationConfig, error) {
+	if cached := webSearchEmulationCache.Load(); cached != nil {
+		if c, ok := cached.(*cachedWebSearchEmulationConfig); ok && time.Now().UnixNano() < c.expiresAt {
+			return c.config, nil
+		}
+	}
+	result, err, _ := webSearchEmulationSF.Do(sfKeyWebSearchConfig, func() (any, error) {
+		return s.loadWebSearchConfigFromDB()
+	})
+	if err != nil {
+		return &WebSearchEmulationConfig{}, err
+	}
+	if cfg, ok := result.(*WebSearchEmulationConfig); ok {
+		return cfg, nil
+	}
+	return &WebSearchEmulationConfig{}, nil
+}
+
+func (s *SettingService) loadWebSearchConfigFromDB() (*WebSearchEmulationConfig, error) {
+	dbCtx, cancel := context.WithTimeout(context.Background(), webSearchEmulationDBTimeout)
+	defer cancel()
+
+	raw, err := s.settingRepo.GetValue(dbCtx, SettingKeyWebSearchEmulationConfig)
+	if err != nil {
+		webSearchEmulationCache.Store(&cachedWebSearchEmulationConfig{
+			config:    &WebSearchEmulationConfig{},
+			expiresAt: time.Now().Add(webSearchEmulationErrorTTL).UnixNano(),
+		})
+		return &WebSearchEmulationConfig{}, err
+	}
+	cfg := parseWebSearchConfigJSON(raw)
+	webSearchEmulationCache.Store(&cachedWebSearchEmulationConfig{
+		config:    cfg,
+		expiresAt: time.Now().Add(webSearchEmulationCacheTTL).UnixNano(),
+	})
+	return cfg, nil
+}
+
+func parseWebSearchConfigJSON(raw string) *WebSearchEmulationConfig {
+	cfg := &WebSearchEmulationConfig{}
+	if raw == "" {
+		return cfg
+	}
+	if err := json.Unmarshal([]byte(raw), cfg); err != nil {
+		slog.Warn("websearch: failed to parse config JSON", "error", err)
+		return &WebSearchEmulationConfig{}
+	}
+	return cfg
+}
+
+// SaveWebSearchEmulationConfig validates and persists the configuration.
+// Empty API keys in the input are preserved from the existing config.
+func (s *SettingService) SaveWebSearchEmulationConfig(ctx context.Context, cfg *WebSearchEmulationConfig) error {
+	if err := validateWebSearchConfig(cfg); err != nil {
+		return infraerrors.BadRequest("INVALID_WEB_SEARCH_CONFIG", err.Error())
+	}
+	s.mergeExistingAPIKeys(ctx, cfg)
+
+	// After merge, validate all enabled providers have API keys
+	if cfg.Enabled {
+		for _, p := range cfg.Providers {
+			if p.APIKey == "" {
+				return infraerrors.BadRequest("MISSING_API_KEY",
+					fmt.Sprintf("provider %s has no API key configured", p.Type))
+			}
+		}
+	}
+
+	data, err := json.Marshal(cfg)
+	if err != nil {
+		return fmt.Errorf("websearch: marshal config: %w", err)
+	}
+	if err := s.settingRepo.Set(ctx, SettingKeyWebSearchEmulationConfig, string(data)); err != nil {
+		return fmt.Errorf("websearch: save config: %w", err)
+	}
+	// Invalidate: forget singleflight first, then store new value
+	webSearchEmulationSF.Forget(sfKeyWebSearchConfig)
+	webSearchEmulationCache.Store(&cachedWebSearchEmulationConfig{
+		config:    cfg,
+		expiresAt: time.Now().Add(webSearchEmulationCacheTTL).UnixNano(),
+	})
+
+	// Hot-reload: rebuild the global Manager with new config
+	s.rebuildWebSearchManager(ctx)
+	return nil
+}
+
+// mergeExistingAPIKeys preserves API keys from the current config when incoming value is empty.
+func (s *SettingService) mergeExistingAPIKeys(ctx context.Context, cfg *WebSearchEmulationConfig) {
+	existing, _ := s.getWebSearchEmulationConfigRaw(ctx)
+	if existing == nil || cfg == nil {
+		return
+	}
+	existingByType := make(map[string]string, len(existing.Providers))
+	for _, p := range existing.Providers {
+		if p.APIKey != "" {
+			existingByType[p.Type] = p.APIKey
+		}
+	}
+	for i := range cfg.Providers {
+		if cfg.Providers[i].APIKey == "" {
+			if key, ok := existingByType[cfg.Providers[i].Type]; ok {
+				cfg.Providers[i].APIKey = key
+			}
+		}
+	}
+}
+
+func (s *SettingService) getWebSearchEmulationConfigRaw(ctx context.Context) (*WebSearchEmulationConfig, error) {
+	raw, err := s.settingRepo.GetValue(ctx, SettingKeyWebSearchEmulationConfig)
+	if err != nil {
+		return nil, err
+	}
+	return parseWebSearchConfigJSON(raw), nil
+}
+
+// IsWebSearchEmulationEnabled is a quick check for whether the global switch is on.
+func (s *SettingService) IsWebSearchEmulationEnabled(ctx context.Context) bool {
+	cfg, err := s.GetWebSearchEmulationConfig(ctx)
+	if err != nil {
+		return false
+	}
+	return cfg.Enabled && len(cfg.Providers) > 0
+}
+
+// SetWebSearchManagerBuilder injects a callback that creates and wires a websearch.Manager.
+// The infra layer (main/wire) provides this builder, keeping redis out of the service layer.
+// Triggers initial build.
+func (s *SettingService) SetWebSearchManagerBuilder(ctx context.Context, builder WebSearchManagerBuilder) {
+	s.webSearchManagerBuilder = builder
+	s.rebuildWebSearchManager(ctx)
+}
+
+// rebuildWebSearchManager reads the current config, resolves proxy URLs, and invokes the builder.
+func (s *SettingService) rebuildWebSearchManager(ctx context.Context) {
+	if s.webSearchManagerBuilder == nil {
+		return
+	}
+	cfg, err := s.GetWebSearchEmulationConfig(ctx)
+	if err != nil {
+		SetWebSearchManager(nil)
+		return
+	}
+	proxyURLs := s.resolveProviderProxyURLs(ctx, cfg)
+	s.webSearchManagerBuilder(cfg, proxyURLs)
+}
+
+// resolveProviderProxyURLs collects proxy IDs from providers and resolves them to URLs.
+func (s *SettingService) resolveProviderProxyURLs(ctx context.Context, cfg *WebSearchEmulationConfig) map[int64]string {
+	if cfg == nil || s.proxyRepo == nil {
+		return nil
+	}
+	var ids []int64
+	for _, p := range cfg.Providers {
+		if p.ProxyID != nil && *p.ProxyID > 0 {
+			ids = append(ids, *p.ProxyID)
+		}
+	}
+	if len(ids) == 0 {
+		return nil
+	}
+	proxies, err := s.proxyRepo.ListByIDs(ctx, ids)
+	if err != nil {
+		slog.Warn("websearch: failed to resolve proxy URLs", "error", err)
+		return nil
+	}
+	result := make(map[int64]string, len(proxies))
+	for _, px := range proxies {
+		result[px.ID] = px.URL()
+	}
+	return result
+}
+
+// WebSearchTestResult holds the result of a search test.
+type WebSearchTestResult struct {
+	Provider string                   `json:"provider"`
+	Results  []websearch.SearchResult `json:"results"`
+	Query    string                   `json:"query"`
+}
+
+// TestWebSearch executes a test search using the currently configured Manager.
+// Uses Manager.TestSearch which bypasses quota tracking.
+const testSearchTimeout = 15 * time.Second
+
+func TestWebSearch(ctx context.Context, query string) (*WebSearchTestResult, error) {
+	mgr := getWebSearchManager()
+	if mgr == nil {
+		return nil, fmt.Errorf("web search: manager not initialized, save config first")
+	}
+	testCtx, cancel := context.WithTimeout(ctx, testSearchTimeout)
+	defer cancel()
+	resp, providerName, err := mgr.TestSearch(testCtx, websearch.SearchRequest{
+		Query:      query,
+		MaxResults: webSearchDefaultMaxResults,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &WebSearchTestResult{
+		Provider: providerName,
+		Results:  resp.Results,
+		Query:    resp.Query,
+	}, nil
+}
+
+// PopulateWebSearchUsage returns a copy with quota usage populated from Redis (api_key kept as-is).
+func PopulateWebSearchUsage(ctx context.Context, cfg *WebSearchEmulationConfig) *WebSearchEmulationConfig {
+	if cfg == nil {
+		return nil
+	}
+	out := *cfg
+	out.Providers = make([]WebSearchProviderConfig, len(cfg.Providers))
+
+	mgr := getWebSearchManager()
+
+	for i, p := range cfg.Providers {
+		out.Providers[i] = p
+		out.Providers[i].APIKeyConfigured = p.APIKey != ""
+
+		if mgr != nil {
+			used, _ := mgr.GetUsage(ctx, p.Type)
+			out.Providers[i].QuotaUsed = used
+		}
+	}
+	return &out
+}
+
+// ResetWebSearchUsage deletes the Redis quota key for the given provider type.
+func ResetWebSearchUsage(ctx context.Context, providerType string) error {
+	mgr := getWebSearchManager()
+	if mgr == nil {
+		return fmt.Errorf("web search manager not initialized")
+	}
+	return mgr.ResetUsage(ctx, providerType)
+}
+
+// SanitizeWebSearchConfig returns a copy with api_key fields masked and quota usage populated.
+func SanitizeWebSearchConfig(ctx context.Context, cfg *WebSearchEmulationConfig) *WebSearchEmulationConfig {
+	if cfg == nil {
+		return nil
+	}
+	out := *cfg
+	out.Providers = make([]WebSearchProviderConfig, len(cfg.Providers))
+
+	// Load usage from the global Manager (reads from Redis)
+	mgr := getWebSearchManager()
+
+	for i, p := range cfg.Providers {
+		out.Providers[i] = p
+		out.Providers[i].APIKeyConfigured = p.APIKey != ""
+		out.Providers[i].APIKey = "" // never return the secret
+
+		// Populate quota usage from Redis
+		if mgr != nil {
+			used, _ := mgr.GetUsage(ctx, p.Type)
+			out.Providers[i].QuotaUsed = used
+		}
+	}
+	return &out
+}

backend/internal/service/websearch_config_test.go

+//go:build unit
+
+package service
+
+import (
+	"context"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/websearch"
+	"github.com/stretchr/testify/require"
+)
+
+// --- validateWebSearchConfig ---
+
+func TestValidateWebSearchConfig_Nil(t *testing.T) {
+	require.NoError(t, validateWebSearchConfig(nil))
+}
+
+func TestValidateWebSearchConfig_Valid(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Enabled: true,
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", QuotaLimit: int64Ptr(1000)},
+			{Type: "tavily", QuotaLimit: int64Ptr(500)},
+		},
+	}
+	require.NoError(t, validateWebSearchConfig(cfg))
+}
+
+func TestValidateWebSearchConfig_TooManyProviders(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{Providers: make([]WebSearchProviderConfig, 11)}
+	for i := range cfg.Providers {
+		cfg.Providers[i] = WebSearchProviderConfig{Type: "brave"}
+	}
+	err := validateWebSearchConfig(cfg)
+	require.ErrorContains(t, err, "too many providers")
+}
+
+func TestValidateWebSearchConfig_InvalidType(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{{Type: "bing"}},
+	}
+	require.ErrorContains(t, validateWebSearchConfig(cfg), "invalid type")
+}
+
+func TestValidateWebSearchConfig_NegativeQuotaLimit(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{{Type: "brave", QuotaLimit: int64Ptr(-1)}},
+	}
+	require.ErrorContains(t, validateWebSearchConfig(cfg), "quota_limit must be > 0 or null")
+}
+
+func TestValidateWebSearchConfig_DuplicateType(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave"},
+			{Type: "brave"},
+		},
+	}
+	require.ErrorContains(t, validateWebSearchConfig(cfg), "duplicate type")
+}
+
+func TestValidateWebSearchConfig_NilQuotaLimit(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{{Type: "brave", QuotaLimit: nil}},
+	}
+	require.NoError(t, validateWebSearchConfig(cfg))
+}
+
+// --- parseWebSearchConfigJSON ---
+
+func TestParseWebSearchConfigJSON_ValidJSON(t *testing.T) {
+	raw := `{"enabled":true,"providers":[{"type":"brave","api_key":"sk-xxx"}]}`
+	cfg := parseWebSearchConfigJSON(raw)
+	require.True(t, cfg.Enabled)
+	require.Len(t, cfg.Providers, 1)
+	require.Equal(t, "brave", cfg.Providers[0].Type)
+}
+
+func TestParseWebSearchConfigJSON_EmptyString(t *testing.T) {
+	cfg := parseWebSearchConfigJSON("")
+	require.False(t, cfg.Enabled)
+	require.Empty(t, cfg.Providers)
+}
+
+func TestParseWebSearchConfigJSON_InvalidJSON(t *testing.T) {
+	cfg := parseWebSearchConfigJSON("not{json")
+	require.False(t, cfg.Enabled)
+	require.Empty(t, cfg.Providers)
+}
+
+func TestParseWebSearchConfigJSON_BackwardCompatibility(t *testing.T) {
+	// Old config with priority and quota_refresh_interval should parse without error
+	raw := `{"enabled":true,"providers":[{"type":"brave","priority":1,"quota_refresh_interval":"monthly","quota_limit":1000}]}`
+	cfg := parseWebSearchConfigJSON(raw)
+	require.True(t, cfg.Enabled)
+	require.Len(t, cfg.Providers, 1)
+	require.Equal(t, int64(1000), *cfg.Providers[0].QuotaLimit)
+}
+
+// --- SanitizeWebSearchConfig ---
+
+func TestSanitizeWebSearchConfig_MaskAPIKey(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Enabled: true,
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: "sk-secret-xxx"},
+		},
+	}
+	out := SanitizeWebSearchConfig(context.Background(), cfg)
+	require.Equal(t, "", out.Providers[0].APIKey)
+	require.True(t, out.Providers[0].APIKeyConfigured)
+}
+
+func TestSanitizeWebSearchConfig_NoAPIKey(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{{Type: "brave", APIKey: ""}},
+	}
+	out := SanitizeWebSearchConfig(context.Background(), cfg)
+	require.Equal(t, "", out.Providers[0].APIKey)
+	require.False(t, out.Providers[0].APIKeyConfigured)
+}
+
+func TestSanitizeWebSearchConfig_Nil(t *testing.T) {
+	require.Nil(t, SanitizeWebSearchConfig(context.Background(), nil))
+}
+
+func TestSanitizeWebSearchConfig_PreservesOtherFields(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Enabled: true,
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: "secret", QuotaLimit: int64Ptr(1000)},
+		},
+	}
+	out := SanitizeWebSearchConfig(context.Background(), cfg)
+	require.True(t, out.Enabled)
+	require.Equal(t, int64(1000), *out.Providers[0].QuotaLimit)
+}
+
+func TestSanitizeWebSearchConfig_DoesNotMutateOriginal(t *testing.T) {
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{{Type: "brave", APIKey: "secret"}},
+	}
+	_ = SanitizeWebSearchConfig(context.Background(), cfg)
+	require.Equal(t, "secret", cfg.Providers[0].APIKey)
+}
+
+// --- PopulateWebSearchUsage ---
+
+func TestPopulateWebSearchUsage_NilInput(t *testing.T) {
+	require.Nil(t, PopulateWebSearchUsage(context.Background(), nil))
+}
+
+func TestPopulateWebSearchUsage_NoManager_QuotaUsedZero(t *testing.T) {
+	// Ensure no global manager is set
+	SetWebSearchManager(nil)
+	defer SetWebSearchManager(nil)
+
+	cfg := &WebSearchEmulationConfig{
+		Enabled: true,
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: "sk-key", QuotaLimit: int64Ptr(1000)},
+		},
+	}
+	out := PopulateWebSearchUsage(context.Background(), cfg)
+	require.NotNil(t, out)
+	require.Len(t, out.Providers, 1)
+	require.Equal(t, int64(0), out.Providers[0].QuotaUsed)
+}
+
+func TestPopulateWebSearchUsage_APIKeyConfigured_True(t *testing.T) {
+	SetWebSearchManager(nil)
+	defer SetWebSearchManager(nil)
+
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: "sk-key"},
+		},
+	}
+	out := PopulateWebSearchUsage(context.Background(), cfg)
+	require.True(t, out.Providers[0].APIKeyConfigured)
+}
+
+func TestPopulateWebSearchUsage_APIKeyConfigured_False(t *testing.T) {
+	SetWebSearchManager(nil)
+	defer SetWebSearchManager(nil)
+
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: ""},
+		},
+	}
+	out := PopulateWebSearchUsage(context.Background(), cfg)
+	require.False(t, out.Providers[0].APIKeyConfigured)
+}
+
+func TestPopulateWebSearchUsage_NilQuotaLimit(t *testing.T) {
+	SetWebSearchManager(nil)
+	defer SetWebSearchManager(nil)
+
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: "sk-key", QuotaLimit: nil},
+		},
+	}
+	out := PopulateWebSearchUsage(context.Background(), cfg)
+	require.Nil(t, out.Providers[0].QuotaLimit)
+}
+
+func TestPopulateWebSearchUsage_NonNilQuotaLimit(t *testing.T) {
+	SetWebSearchManager(nil)
+	defer SetWebSearchManager(nil)
+
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: "sk-key", QuotaLimit: int64Ptr(500)},
+		},
+	}
+	out := PopulateWebSearchUsage(context.Background(), cfg)
+	require.NotNil(t, out.Providers[0].QuotaLimit)
+	require.Equal(t, int64(500), *out.Providers[0].QuotaLimit)
+}
+
+func TestPopulateWebSearchUsage_WithManager_NilRedis(t *testing.T) {
+	// Manager with nil Redis returns 0 usage without error
+	mgr := websearch.NewManager([]websearch.ProviderConfig{
+		{Type: "brave", APIKey: "k"},
+	}, nil)
+	SetWebSearchManager(mgr)
+	defer SetWebSearchManager(nil)
+
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: "sk-key", QuotaLimit: int64Ptr(1000)},
+		},
+	}
+	out := PopulateWebSearchUsage(context.Background(), cfg)
+	require.Equal(t, int64(0), out.Providers[0].QuotaUsed)
+	require.True(t, out.Providers[0].APIKeyConfigured)
+}
+
+func TestPopulateWebSearchUsage_DoesNotMutateOriginal(t *testing.T) {
+	SetWebSearchManager(nil)
+	defer SetWebSearchManager(nil)
+
+	cfg := &WebSearchEmulationConfig{
+		Providers: []WebSearchProviderConfig{
+			{Type: "brave", APIKey: "secret", QuotaLimit: int64Ptr(100)},
+		},
+	}
+	_ = PopulateWebSearchUsage(context.Background(), cfg)
+	// Original should be unchanged
+	require.Equal(t, "secret", cfg.Providers[0].APIKey)
+	require.Equal(t, int64(0), cfg.Providers[0].QuotaUsed)
+}
+
+// --- ResetWebSearchUsage ---
+
+func TestResetWebSearchUsage_NilManager(t *testing.T) {
+	SetWebSearchManager(nil)
+	defer SetWebSearchManager(nil)
+
+	err := ResetWebSearchUsage(context.Background(), "brave")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "not initialized")
+}

backend/internal/service/wire.go

@@ -373,10 +373,11 @@ func ProvideBackupService(
 	return svc
 }
 
-// ProvideSettingService wires SettingService with group reader for default subscription validation.
-func ProvideSettingService(settingRepo SettingRepository, groupRepo GroupRepository, cfg *config.Config) *SettingService {
+// ProvideSettingService wires SettingService with group reader and proxy repo.
+func ProvideSettingService(settingRepo SettingRepository, groupRepo GroupRepository, proxyRepo ProxyRepository, cfg *config.Config) *SettingService {
 	svc := NewSettingService(settingRepo, cfg)
 	svc.SetDefaultSubscriptionGroupReader(groupRepo)
+	svc.SetProxyRepository(proxyRepo)
 	return svc
 }
 
@@ -465,6 +466,7 @@ var ProviderSet = wire.NewSet(
 	ProvidePaymentConfigService,
 	NewPaymentService,
 	ProvidePaymentOrderExpiryService,
+	ProvideBalanceNotifyService,
 )
 
 // ProvidePaymentConfigService wraps NewPaymentConfigService to accept the named
@@ -473,6 +475,11 @@ func ProvidePaymentConfigService(entClient *dbent.Client, settingRepo SettingRep
 	return NewPaymentConfigService(entClient, settingRepo, []byte(key))
 }
 
+// ProvideBalanceNotifyService creates BalanceNotifyService
+func ProvideBalanceNotifyService(emailService *EmailService, settingRepo SettingRepository, accountRepo AccountRepository) *BalanceNotifyService {
+	return NewBalanceNotifyService(emailService, settingRepo, accountRepo)
+}
+
 // ProvidePaymentOrderExpiryService creates and starts PaymentOrderExpiryService.
 func ProvidePaymentOrderExpiryService(paymentSvc *PaymentService) *PaymentOrderExpiryService {
 	svc := NewPaymentOrderExpiryService(paymentSvc, 60*time.Second)

backend/internal/web/embed_on.go

@@ -10,6 +10,8 @@ import (
 	"io"
 	"io/fs"
 	"net/http"
+	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -32,11 +34,12 @@ type PublicSettingsProvider interface {
 
 // FrontendServer serves the embedded frontend with settings injection
 type FrontendServer struct {
-	distFS     fs.FS
-	fileServer http.Handler
-	baseHTML   []byte
-	cache      *HTMLCache
-	settings   PublicSettingsProvider
+	distFS      fs.FS
+	fileServer  http.Handler
+	baseHTML    []byte
+	cache       *HTMLCache
+	settings    PublicSettingsProvider
+	overrideDir string // local file override directory
 }
 
 // NewFrontendServer creates a new frontend server with settings injection
@@ -62,11 +65,12 @@ func NewFrontendServer(settingsProvider PublicSettingsProvider) (*FrontendServer
 	cache.SetBaseHTML(baseHTML)
 
 	return &FrontendServer{
-		distFS:     distFS,
-		fileServer: http.FileServer(http.FS(distFS)),
-		baseHTML:   baseHTML,
-		cache:      cache,
-		settings:   settingsProvider,
+		distFS:      distFS,
+		fileServer:  http.FileServer(http.FS(distFS)),
+		baseHTML:    baseHTML,
+		cache:       cache,
+		settings:    settingsProvider,
+		overrideDir: filepath.Join("data", "public"),
 	}, nil
 }
 
@@ -99,6 +103,11 @@ func (s *FrontendServer) Middleware() gin.HandlerFunc {
 			return
 		}
 
+		// Try local override first
+		if s.tryServeOverride(c, cleanPath) {
+			return
+		}
+
 		// Serve static files normally
 		s.fileServer.ServeHTTP(c.Writer, c.Request)
 		c.Abort()
@@ -114,6 +123,22 @@ func (s *FrontendServer) fileExists(path string) bool {
 	return true
 }
 
+// tryServeOverride checks if a local override file exists and serves it.
+// Files in overrideDir take precedence over embedded files.
+func (s *FrontendServer) tryServeOverride(c *gin.Context, cleanPath string) bool {
+	if s.overrideDir == "" {
+		return false
+	}
+	filePath := filepath.Join(s.overrideDir, filepath.Clean("/"+cleanPath))
+	info, err := os.Stat(filePath)
+	if err != nil || info.IsDir() {
+		return false
+	}
+	c.File(filePath)
+	c.Abort()
+	return true
+}
+
 func (s *FrontendServer) serveIndexHTML(c *gin.Context) {
 	// Get nonce from context (generated by SecurityHeaders middleware)
 	nonce := middleware.GetNonceFromContext(c)
@@ -226,6 +251,7 @@ func ServeEmbeddedFrontend() gin.HandlerFunc {
 		panic("failed to get dist subdirectory: " + err.Error())
 	}
 	fileServer := http.FileServer(http.FS(distFS))
+	overrideDir := filepath.Join("data", "public")
 
 	return func(c *gin.Context) {
 		path := c.Request.URL.Path
@@ -242,6 +268,10 @@ func ServeEmbeddedFrontend() gin.HandlerFunc {
 
 		if file, err := distFS.Open(cleanPath); err == nil {
 			_ = file.Close()
+			// Try local override first
+			if tryServeOverrideFile(c, overrideDir, cleanPath) {
+				return
+			}
 			fileServer.ServeHTTP(c.Writer, c.Request)
 			c.Abort()
 			return
@@ -251,6 +281,21 @@ func ServeEmbeddedFrontend() gin.HandlerFunc {
 	}
 }
 
+// tryServeOverrideFile is a standalone version of tryServeOverride for legacy usage.
+func tryServeOverrideFile(c *gin.Context, overrideDir, cleanPath string) bool {
+	if overrideDir == "" {
+		return false
+	}
+	filePath := filepath.Join(overrideDir, filepath.Clean("/"+cleanPath))
+	info, err := os.Stat(filePath)
+	if err != nil || info.IsDir() {
+		return false
+	}
+	c.File(filePath)
+	c.Abort()
+	return true
+}
+
 func shouldBypassEmbeddedFrontend(path string) bool {
 	trimmed := strings.TrimSpace(path)
 	return strings.HasPrefix(trimmed, "/api/") ||

backend/migrations/095_channel_features.sql

+ALTER TABLE channels ADD COLUMN IF NOT EXISTS features TEXT NOT NULL DEFAULT '';
+COMMENT ON COLUMN channels.features IS '渠道特性描述，JSON 数组格式，用于支付页面展示';

backend/migrations/101_add_account_stats_pricing.sql

+-- Account statistics pricing: allow channels to configure custom pricing for account cost tracking.
+
+-- 1. Channel-level toggle
+ALTER TABLE channels ADD COLUMN IF NOT EXISTS apply_pricing_to_account_stats BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- 2. Account stats pricing rules (ordered list per channel)
+CREATE TABLE IF NOT EXISTS channel_account_stats_pricing_rules (
+    id BIGSERIAL PRIMARY KEY,
+    channel_id BIGINT NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+    name VARCHAR(100) NOT NULL DEFAULT '',
+    group_ids BIGINT[] NOT NULL DEFAULT '{}',
+    account_ids BIGINT[] NOT NULL DEFAULT '{}',
+    sort_order INT NOT NULL DEFAULT 0,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_cas_pricing_rules_channel_id ON channel_account_stats_pricing_rules(channel_id);
+
+-- 3. Model pricing for each rule (same structure as channel_model_pricing)
+CREATE TABLE IF NOT EXISTS channel_account_stats_model_pricing (
+    id BIGSERIAL PRIMARY KEY,
+    rule_id BIGINT NOT NULL REFERENCES channel_account_stats_pricing_rules(id) ON DELETE CASCADE,
+    platform VARCHAR(50) NOT NULL DEFAULT '',
+    models JSONB NOT NULL DEFAULT '[]',
+    billing_mode VARCHAR(20) NOT NULL DEFAULT 'token',
+    input_price NUMERIC(20,10),
+    output_price NUMERIC(20,10),
+    cache_write_price NUMERIC(20,10),
+    cache_read_price NUMERIC(20,10),
+    image_output_price NUMERIC(20,10),
+    per_request_price NUMERIC(20,10),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_cas_model_pricing_rule_id ON channel_account_stats_model_pricing(rule_id);
+
+-- 4. Usage logs: pre-computed account stats cost (NULL = use default formula)
+ALTER TABLE usage_logs ADD COLUMN IF NOT EXISTS account_stats_cost NUMERIC(20,10);

backend/migrations/101_add_balance_notify_fields.sql

+-- Balance notification user preferences
+ALTER TABLE users ADD COLUMN IF NOT EXISTS balance_notify_enabled BOOLEAN NOT NULL DEFAULT true;
+ALTER TABLE users ADD COLUMN IF NOT EXISTS balance_notify_threshold DECIMAL(20,8) DEFAULT NULL;
+ALTER TABLE users ADD COLUMN IF NOT EXISTS balance_notify_extra_emails TEXT NOT NULL DEFAULT '[]';

backend/migrations/101_add_channel_features_config.sql

+ALTER TABLE channels ADD COLUMN IF NOT EXISTS features_config JSONB NOT NULL DEFAULT '{}';
+COMMENT ON COLUMN channels.features_config IS '渠道特性配置（如 web_search_emulation），JSON 对象格式';

backend/migrations/102_add_balance_notify_threshold_type.sql

+-- Add threshold type support (fixed / percentage) to balance notification
+ALTER TABLE users ADD COLUMN IF NOT EXISTS balance_notify_threshold_type VARCHAR(10) NOT NULL DEFAULT 'fixed';
+-- Track cumulative recharge amount for percentage threshold calculation
+ALTER TABLE users ADD COLUMN IF NOT EXISTS total_recharged DECIMAL(20,8) NOT NULL DEFAULT 0;

backend/migrations/103_add_allow_user_refund.sql

+ALTER TABLE payment_provider_instances ADD COLUMN IF NOT EXISTS allow_user_refund BOOLEAN NOT NULL DEFAULT false;

backend/migrations/104_migrate_notify_emails_to_struct.sql

+-- Migrate notification email lists from old []string format to new []NotifyEmailEntry format
+-- Old: ["a@x.com", "b@x.com"]
+-- New: [{"email":"a@x.com","disabled":false,"verified":true}, ...]
+-- Existing emails are marked as verified=false (unverified), disabled=false (enabled)
+
+-- 1. User balance notification emails
+UPDATE users
+SET balance_notify_extra_emails = (
+  SELECT COALESCE(
+    jsonb_agg(jsonb_build_object('email', elem::text, 'disabled', false, 'verified', false)),
+    '[]'::jsonb
+  )::text
+  FROM jsonb_array_elements_text(balance_notify_extra_emails::jsonb) AS elem
+)
+WHERE balance_notify_extra_emails IS NOT NULL
+  AND balance_notify_extra_emails <> '[]'
+  AND balance_notify_extra_emails <> ''
+  AND (balance_notify_extra_emails::jsonb -> 0) IS NOT NULL
+  AND jsonb_typeof(balance_notify_extra_emails::jsonb -> 0) = 'string';
+
+-- 2. Admin account quota notification emails
+UPDATE settings
+SET value = (
+  SELECT COALESCE(
+    jsonb_agg(jsonb_build_object('email', elem::text, 'disabled', false, 'verified', false)),
+    '[]'::jsonb
+  )::text
+  FROM jsonb_array_elements_text(value::jsonb) AS elem
+)
+WHERE key = 'account_quota_notify_emails'
+  AND value IS NOT NULL
+  AND value <> '[]'
+  AND value <> ''
+  AND (value::jsonb -> 0) IS NOT NULL
+  AND jsonb_typeof(value::jsonb -> 0) = 'string';

backend/migrations/105_migrate_websearch_emulation_to_tristate.sql

+-- Convert old boolean web_search_emulation to tri-state string
+-- true → "enabled", false → remove key (becomes "default")
+UPDATE accounts
+SET extra = (extra - 'web_search_emulation') || jsonb_build_object('web_search_emulation', 'enabled')
+WHERE extra ? 'web_search_emulation'
+  AND extra->>'web_search_emulation' = 'true';
+
+UPDATE accounts
+SET extra = extra - 'web_search_emulation'
+WHERE extra ? 'web_search_emulation'
+  AND extra->>'web_search_emulation' = 'false';

backend/migrations/106_add_account_stats_pricing_intervals.sql

+-- Add intervals table for account stats pricing rules (mirrors channel_pricing_intervals).
+CREATE TABLE IF NOT EXISTS channel_account_stats_pricing_intervals (
+    id                BIGSERIAL      PRIMARY KEY,
+    pricing_id        BIGINT         NOT NULL REFERENCES channel_account_stats_model_pricing(id) ON DELETE CASCADE,
+    min_tokens        INT            NOT NULL DEFAULT 0,
+    max_tokens        INT,
+    tier_label        VARCHAR(50),
+    input_price       NUMERIC(20,12),
+    output_price      NUMERIC(20,12),
+    cache_write_price NUMERIC(20,12),
+    cache_read_price  NUMERIC(20,12),
+    per_request_price NUMERIC(20,12),
+    sort_order        INT            NOT NULL DEFAULT 0,
+    created_at        TIMESTAMPTZ    NOT NULL DEFAULT NOW(),
+    updated_at        TIMESTAMPTZ    NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_account_stats_pricing_intervals_pricing_id
+    ON channel_account_stats_pricing_intervals (pricing_id);

frontend/src/api/admin/channels.ts

@@ -34,6 +34,14 @@ export interface ChannelModelPricing {
   intervals: PricingInterval[]
 }
 
+export interface AccountStatsPricingRule {
+  id?: number
+  name: string
+  group_ids: number[]
+  account_ids: number[]
+  pricing: ChannelModelPricing[]
+}
+
 export interface Channel {
   id: number
   name: string
@@ -41,9 +49,12 @@ export interface Channel {
   status: string
   billing_model_source: string // "requested" | "upstream"
   restrict_models: boolean
+  features_config?: Record<string, unknown>
   group_ids: number[]
   model_pricing: ChannelModelPricing[]
   model_mapping: Record<string, Record<string, string>> // platform → {src→dst}
+  apply_pricing_to_account_stats: boolean
+  account_stats_pricing_rules: AccountStatsPricingRule[]
   created_at: string
   updated_at: string
 }
@@ -56,6 +67,9 @@ export interface CreateChannelRequest {
   model_mapping?: Record<string, Record<string, string>>
   billing_model_source?: string
   restrict_models?: boolean
+  features_config?: Record<string, unknown>
+  apply_pricing_to_account_stats?: boolean
+  account_stats_pricing_rules?: AccountStatsPricingRule[]
 }
 
 export interface UpdateChannelRequest {
@@ -67,6 +81,9 @@ export interface UpdateChannelRequest {
   model_mapping?: Record<string, Record<string, string>>
   billing_model_source?: string
   restrict_models?: boolean
+  features_config?: Record<string, unknown>
+  apply_pricing_to_account_stats?: boolean
+  account_stats_pricing_rules?: AccountStatsPricingRule[]
 }
 
 interface PaginatedResponse<T> {

frontend/src/api/admin/settings.ts

@@ -4,7 +4,7 @@
  */
 
 import { apiClient } from '../client'
-import type { CustomMenuItem, CustomEndpoint } from '@/types'
+import type { CustomMenuItem, CustomEndpoint, NotifyEmailEntry } from '@/types'
 
 export interface DefaultSubscriptionSetting {
   group_id: number
@@ -114,6 +114,7 @@ export interface SystemSettings {
   enable_fingerprint_unification: boolean
   enable_metadata_passthrough: boolean
   enable_cch_signing: boolean
+  web_search_emulation_enabled?: boolean
 
   // Payment configuration
   payment_enabled: boolean
@@ -134,6 +135,13 @@ export interface SystemSettings {
   payment_cancel_rate_limit_window: number
   payment_cancel_rate_limit_unit: string
   payment_cancel_rate_limit_window_mode: string
+
+  // Balance & quota notification
+  balance_low_notify_enabled: boolean
+  balance_low_notify_threshold: number
+  balance_low_notify_recharge_url: string
+  account_quota_notify_enabled: boolean
+  account_quota_notify_emails: NotifyEmailEntry[]
 }
 
 export interface UpdateSettingsRequest {
@@ -233,6 +241,12 @@ export interface UpdateSettingsRequest {
   payment_cancel_rate_limit_window?: number
   payment_cancel_rate_limit_unit?: string
   payment_cancel_rate_limit_window_mode?: string
+  // Balance & quota notification
+  balance_low_notify_enabled?: boolean
+  balance_low_notify_threshold?: number
+  balance_low_notify_recharge_url?: string
+  account_quota_notify_enabled?: boolean
+  account_quota_notify_emails?: NotifyEmailEntry[]
 }
 
 /**
@@ -482,6 +496,63 @@ export async function updateBetaPolicySettings(
   return data
 }
 
+// --- Web Search Emulation Config ---
+
+export interface WebSearchProviderConfig {
+  type: 'brave' | 'tavily'
+  api_key: string
+  api_key_configured: boolean
+  quota_limit: number | null
+  subscribed_at: number | null
+  quota_used?: number
+  proxy_id: number | null
+  expires_at: number | null
+}
+
+export interface WebSearchEmulationConfig {
+  enabled: boolean
+  providers: WebSearchProviderConfig[]
+}
+
+export interface WebSearchTestResult {
+  provider: string
+  results: { url: string; title: string; snippet: string; page_age?: string }[]
+  query: string
+}
+
+export async function getWebSearchEmulationConfig(): Promise<WebSearchEmulationConfig> {
+  const { data } = await apiClient.get<WebSearchEmulationConfig>(
+    '/admin/settings/web-search-emulation'
+  )
+  return data
+}
+
+export async function updateWebSearchEmulationConfig(
+  config: WebSearchEmulationConfig
+): Promise<WebSearchEmulationConfig> {
+  const { data } = await apiClient.put<WebSearchEmulationConfig>(
+    '/admin/settings/web-search-emulation',
+    config
+  )
+  return data
+}
+
+export async function testWebSearchEmulation(
+  query: string
+): Promise<WebSearchTestResult> {
+  const { data } = await apiClient.post<WebSearchTestResult>(
+    '/admin/settings/web-search-emulation/test',
+    { query }
+  )
+  return data
+}
+
+export async function resetWebSearchUsage(
+  payload: { provider_type: string }
+): Promise<void> {
+  await apiClient.post('/admin/settings/web-search-emulation/reset-usage', payload)
+}
+
 export const settingsAPI = {
   getSettings,
   updateSettings,
@@ -497,7 +568,11 @@ export const settingsAPI = {
   getRectifierSettings,
   updateRectifierSettings,
   getBetaPolicySettings,
-  updateBetaPolicySettings
+  updateBetaPolicySettings,
+  getWebSearchEmulationConfig,
+  updateWebSearchEmulationConfig,
+  testWebSearchEmulation,
+  resetWebSearchUsage
 }
 
 export default settingsAPI

frontend/src/api/client.ts

@@ -270,9 +270,9 @@ apiClient.interceptors.response.use(
       return Promise.reject({
         status,
         code: apiData.code,
+        reason: apiData.reason,
         error: apiData.error,
         message: apiData.message || apiData.detail || error.message,
-        reason: apiData.reason,
         metadata: apiData.metadata,
       })
     }

frontend/src/api/payment.ts

@@ -75,5 +75,10 @@ export const paymentAPI = {
   /** Request a refund for a completed order */
   requestRefund(id: number, data: { reason: string }) {
     return apiClient.post(`/payment/orders/${id}/refund-request`, data)
+  },
+
+  /** Get provider instance IDs that allow user refund */
+  getRefundEligibleProviders() {
+    return apiClient.get<{ provider_instance_ids: string[] }>('/payment/orders/refund-eligible-providers')
   }
 }

frontend/src/api/user.ts

@@ -4,7 +4,7 @@
  */
 
 import { apiClient } from './client'
-import type { User, ChangePasswordRequest } from '@/types'
+import type { User, ChangePasswordRequest, NotifyEmailEntry } from '@/types'
 
 /**
  * Get current user profile
@@ -22,6 +22,9 @@ export async function getProfile(): Promise<User> {
  */
 export async function updateProfile(profile: {
   username?: string
+  balance_notify_enabled?: boolean
+  balance_notify_threshold?: number | null
+  balance_notify_extra_emails?: NotifyEmailEntry[]
 }): Promise<User> {
   const { data } = await apiClient.put<User>('/user', profile)
   return data
@@ -45,10 +48,49 @@ export async function changePassword(
   return data
 }
 
+/**
+ * Send verification code for adding a notify email
+ * @param email - Email address to verify
+ */
+export async function sendNotifyEmailCode(email: string): Promise<void> {
+  await apiClient.post('/user/notify-email/send-code', { email })
+}
+
+/**
+ * Verify and add a notify email
+ * @param email - Email address to add
+ * @param code - Verification code
+ */
+export async function verifyNotifyEmail(email: string, code: string): Promise<void> {
+  await apiClient.post('/user/notify-email/verify', { email, code })
+}
+
+/**
+ * Remove a notify email
+ * @param email - Email address to remove
+ */
+export async function removeNotifyEmail(email: string): Promise<void> {
+  await apiClient.delete('/user/notify-email', { data: { email } })
+}
+
+/**
+ * Toggle a notify email's disabled state
+ * @param email - Email address (empty string for primary email placeholder)
+ * @param disabled - Whether to disable the email
+ */
+export async function toggleNotifyEmail(email: string, disabled: boolean): Promise<User> {
+  const { data } = await apiClient.put<User>('/user/notify-email/toggle', { email, disabled })
+  return data
+}
+
 export const userAPI = {
   getProfile,
   updateProfile,
-  changePassword
+  changePassword,
+  sendNotifyEmailCode,
+  verifyNotifyEmail,
+  removeNotifyEmail,
+  toggleNotifyEmail
 }
 
 export default userAPI

frontend/src/components/account/AccountCapacityCell.vue

 <template>
-  <div class="flex flex-col gap-1.5">
+  <div class="flex flex-col gap-0.5">
     <!-- 并发槽位 -->
-    <div class="flex items-center gap-1.5">
-      <span
-        :class="[
-          'inline-flex items-center gap-1 rounded-md px-2 py-0.5 text-xs font-medium',
-          concurrencyClass
-        ]"
-      >
-        <svg class="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
-          <path stroke-linecap="round" stroke-linejoin="round" d="M3.75 6A2.25 2.25 0 016 3.75h2.25A2.25 2.25 0 0110.5 6v2.25a2.25 2.25 0 01-2.25 2.25H6a2.25 2.25 0 01-2.25-2.25V6zM3.75 15.75A2.25 2.25 0 016 13.5h2.25a2.25 2.25 0 012.25 2.25V18a2.25 2.25 0 01-2.25 2.25H6A2.25 2.25 0 013.75 18v-2.25zM13.5 6a2.25 2.25 0 012.25-2.25H18A2.25 2.25 0 0120.25 6v2.25A2.25 2.25 0 0118 10.5h-2.25a2.25 2.25 0 01-2.25-2.25V6zM13.5 15.75a2.25 2.25 0 012.25-2.25H18a2.25 2.25 0 012.25 2.25V18A2.25 2.25 0 0118 20.25h-2.25A2.25 2.25 0 0113.5 18v-2.25z" />
-        </svg>
-        <span class="font-mono">{{ currentConcurrency }}</span>
-        <span class="text-gray-400 dark:text-gray-500">/</span>
-        <span class="font-mono">{{ account.concurrency }}</span>
-      </span>
-    </div>
-
-    <!-- 5h窗口费用限制（仅 Anthropic OAuth/SetupToken 且启用时显示） -->
-    <div v-if="showWindowCost" class="flex items-center gap-1">
-      <span
-        :class="[
-          'inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 text-[10px] font-medium',
-          windowCostClass
-        ]"
-        :title="windowCostTooltip"
-      >
-        <svg class="h-2.5 w-2.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
-          <path stroke-linecap="round" stroke-linejoin="round" d="M12 6v12m-3-2.818l.879.659c1.171.879 3.07.879 4.242 0 1.172-.879 1.172-2.303 0-3.182C13.536 12.219 12.768 12 12 12c-.725 0-1.45-.22-2.003-.659-1.106-.879-1.106-2.303 0-3.182s2.9-.879 4.006 0l.415.33M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-        </svg>
-        <span class="font-mono">${{ formatCost(currentWindowCost) }}</span>
-        <span class="text-gray-400 dark:text-gray-500">/</span>
-        <span class="font-mono">${{ formatCost(account.window_cost_limit) }}</span>
-      </span>
-    </div>
-
-    <!-- 会话数量限制（仅 Anthropic OAuth/SetupToken 且启用时显示） -->
-    <div v-if="showSessionLimit" class="flex items-center gap-1">
-      <span
-        :class="[
-          'inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 text-[10px] font-medium',
-          sessionLimitClass
-        ]"
-        :title="sessionLimitTooltip"
-      >
-        <svg class="h-2.5 w-2.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
-          <path stroke-linecap="round" stroke-linejoin="round" d="M15 19.128a9.38 9.38 0 002.625.372 9.337 9.337 0 004.121-.952 4.125 4.125 0 00-7.533-2.493M15 19.128v-.003c0-1.113-.285-2.16-.786-3.07M15 19.128v.106A12.318 12.318 0 018.624 21c-2.331 0-4.512-.645-6.374-1.766l-.001-.109a6.375 6.375 0 0111.964-3.07M12 6.375a3.375 3.375 0 11-6.75 0 3.375 3.375 0 016.75 0zm8.25 2.25a2.625 2.625 0 11-5.25 0 2.625 2.625 0 015.25 0z" />
-        </svg>
-        <span class="font-mono">{{ activeSessions }}</span>
-        <span class="text-gray-400 dark:text-gray-500">/</span>
-        <span class="font-mono">{{ account.max_sessions }}</span>
-      </span>
-    </div>
-
-    <!-- RPM 限制（仅 Anthropic OAuth/SetupToken 且启用时显示） -->
-    <div v-if="showRpmLimit" class="flex items-center gap-1">
-      <span
-        :class="[
-          'inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 text-[10px] font-medium',
-          rpmClass
-        ]"
-        :title="rpmTooltip"
-      >
-        <svg class="h-2.5 w-2.5" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
-          <path stroke-linecap="round" stroke-linejoin="round" d="M12 6v6h4.5m4.5 0a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
-        </svg>
-        <span class="font-mono">{{ currentRPM }}</span>
-        <span class="text-gray-400 dark:text-gray-500">/</span>
-        <span class="font-mono">{{ account.base_rpm }}</span>
-        <span class="text-[9px] opacity-60">{{ rpmStrategyTag }}</span>
-      </span>
-    </div>
+    <CapacityBadge :color-class="concurrencyClass" :current="currentConcurrency" :max="account.concurrency">
+      <svg class="h-2.5 w-2.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M3.75 6A2.25 2.25 0 016 3.75h2.25A2.25 2.25 0 0110.5 6v2.25a2.25 2.25 0 01-2.25 2.25H6a2.25 2.25 0 01-2.25-2.25V6zM3.75 15.75A2.25 2.25 0 016 13.5h2.25a2.25 2.25 0 012.25 2.25V18a2.25 2.25 0 01-2.25 2.25H6A2.25 2.25 0 013.75 18v-2.25zM13.5 6a2.25 2.25 0 012.25-2.25H18A2.25 2.25 0 0120.25 6v2.25A2.25 2.25 0 0118 10.5h-2.25a2.25 2.25 0 01-2.25-2.25V6zM13.5 15.75a2.25 2.25 0 012.25-2.25H18a2.25 2.25 0 012.25 2.25V18A2.25 2.25 0 0118 20.25h-2.25A2.25 2.25 0 0113.5 18v-2.25z" />
+      </svg>
+    </CapacityBadge>
+
+    <!-- 5h窗口费用限制 -->
+    <CapacityBadge v-if="showWindowCost" :color-class="windowCostClass" :tooltip="windowCostTooltip" :current="'$' + formatCost(currentWindowCost)" :max="'$' + formatCost(account.window_cost_limit)">
+      <svg class="h-2.5 w-2.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M12 6v12m-3-2.818l.879.659c1.171.879 3.07.879 4.242 0 1.172-.879 1.172-2.303 0-3.182C13.536 12.219 12.768 12 12 12c-.725 0-1.45-.22-2.003-.659-1.106-.879-1.106-2.303 0-3.182s2.9-.879 4.006 0l.415.33M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+      </svg>
+    </CapacityBadge>
+
+    <!-- 会话数量限制 -->
+    <CapacityBadge v-if="showSessionLimit" :color-class="sessionLimitClass" :tooltip="sessionLimitTooltip" :current="activeSessions" :max="account.max_sessions!">
+      <svg class="h-2.5 w-2.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M15 19.128a9.38 9.38 0 002.625.372 9.337 9.337 0 004.121-.952 4.125 4.125 0 00-7.533-2.493M15 19.128v-.003c0-1.113-.285-2.16-.786-3.07M15 19.128v.106A12.318 12.318 0 018.624 21c-2.331 0-4.512-.645-6.374-1.766l-.001-.109a6.375 6.375 0 0111.964-3.07M12 6.375a3.375 3.375 0 11-6.75 0 3.375 3.375 0 016.75 0zm8.25 2.25a2.625 2.625 0 11-5.25 0 2.625 2.625 0 015.25 0z" />
+      </svg>
+    </CapacityBadge>
+
+    <!-- RPM 限制 -->
+    <CapacityBadge v-if="showRpmLimit" :color-class="rpmClass" :tooltip="rpmTooltip" :current="currentRPM" :max="account.base_rpm!" :suffix="rpmStrategyTag">
+      <svg class="h-2.5 w-2.5" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M12 6v6h4.5m4.5 0a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
+      </svg>
+    </CapacityBadge>
 
     <!-- API Key 账号配额限制 -->
     <QuotaBadge v-if="showDailyQuota" :used="account.quota_daily_used ?? 0" :limit="account.quota_daily_limit!" label="D" />
@@ -83,7 +39,8 @@
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 import type { Account } from '@/types'
-import QuotaBadge from './QuotaBadge.vue'
+import CapacityBadge from '@/components/account/CapacityBadge.vue'
+import QuotaBadge from '@/components/account/QuotaBadge.vue'
 
 const props = defineProps<{
   account: Account
@@ -91,225 +48,143 @@ const props = defineProps<{
 
 const { t } = useI18n()
 
-// 当前并发数
+// ====== 并发 ======
 const currentConcurrency = computed(() => props.account.current_concurrency || 0)
 
-// 是否为 Anthropic OAuth/SetupToken 账号
-const isAnthropicOAuthOrSetupToken = computed(() => {
-  return (
-    props.account.platform === 'anthropic' &&
-    (props.account.type === 'oauth' || props.account.type === 'setup-token')
-  )
-})
-
-// 是否显示窗口费用限制
-const showWindowCost = computed(() => {
-  return (
-    isAnthropicOAuthOrSetupToken.value &&
-    props.account.window_cost_limit !== undefined &&
-    props.account.window_cost_limit !== null &&
-    props.account.window_cost_limit > 0
-  )
-})
-
-// 当前窗口费用
-const currentWindowCost = computed(() => props.account.current_window_cost ?? 0)
-
-// 是否显示会话限制
-const showSessionLimit = computed(() => {
-  return (
-    isAnthropicOAuthOrSetupToken.value &&
-    props.account.max_sessions !== undefined &&
-    props.account.max_sessions !== null &&
-    props.account.max_sessions > 0
-  )
-})
-
-// 当前活跃会话数
-const activeSessions = computed(() => props.account.active_sessions ?? 0)
-
-// 并发状态样式
 const concurrencyClass = computed(() => {
   const current = currentConcurrency.value
   const max = props.account.concurrency
-
-  if (current >= max) {
-    return 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
-  }
-  if (current > 0) {
-    return 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
-  }
+  if (current >= max) return 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
+  if (current > 0) return 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
   return 'bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-400'
 })
 
-// 窗口费用状态样式
+// ====== 窗口费用 ======
+const isAnthropicOAuthOrSetupToken = computed(() =>
+  props.account.platform === 'anthropic' &&
+  (props.account.type === 'oauth' || props.account.type === 'setup-token')
+)
+
+const showWindowCost = computed(() =>
+  isAnthropicOAuthOrSetupToken.value &&
+  props.account.window_cost_limit != null &&
+  props.account.window_cost_limit > 0
+)
+
+const currentWindowCost = computed(() => props.account.current_window_cost ?? 0)
+
 const windowCostClass = computed(() => {
   if (!showWindowCost.value) return ''
-
   const current = currentWindowCost.value
   const limit = props.account.window_cost_limit || 0
   const reserve = props.account.window_cost_sticky_reserve || 10
-
-  if (current >= limit + reserve) {
-    return 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
-  }
-  if (current >= limit) {
-    return 'bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400'
-  }
-  if (current >= limit * 0.8) {
-    return 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
-  }
+  if (current >= limit + reserve) return 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
+  if (current >= limit) return 'bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400'
+  if (current >= limit * 0.8) return 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
   return 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-400'
 })
 
-// 窗口费用提示文字
 const windowCostTooltip = computed(() => {
   if (!showWindowCost.value) return ''
-
   const current = currentWindowCost.value
   const limit = props.account.window_cost_limit || 0
   const reserve = props.account.window_cost_sticky_reserve || 10
-
-  if (current >= limit + reserve) {
-    return t('admin.accounts.capacity.windowCost.blocked')
-  }
-  if (current >= limit) {
-    return t('admin.accounts.capacity.windowCost.stickyOnly')
-  }
+  if (current >= limit + reserve) return t('admin.accounts.capacity.windowCost.blocked')
+  if (current >= limit) return t('admin.accounts.capacity.windowCost.stickyOnly')
   return t('admin.accounts.capacity.windowCost.normal')
 })
 
-// 会话限制状态样式
+// ====== 会话限制 ======
+const showSessionLimit = computed(() =>
+  isAnthropicOAuthOrSetupToken.value &&
+  props.account.max_sessions != null &&
+  props.account.max_sessions > 0
+)
+
+const activeSessions = computed(() => props.account.active_sessions ?? 0)
+
 const sessionLimitClass = computed(() => {
   if (!showSessionLimit.value) return ''
-
   const current = activeSessions.value
   const max = props.account.max_sessions || 0
-
-  if (current >= max) {
-    return 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
-  }
-  if (current >= max * 0.8) {
-    return 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
-  }
+  if (current >= max) return 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
+  if (current >= max * 0.8) return 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
   return 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-400'
 })
 
-// 会话限制提示文字
 const sessionLimitTooltip = computed(() => {
   if (!showSessionLimit.value) return ''
-
   const current = activeSessions.value
   const max = props.account.max_sessions || 0
   const idle = props.account.session_idle_timeout_minutes || 5
-
-  if (current >= max) {
-    return t('admin.accounts.capacity.sessions.full', { idle })
-  }
+  if (current >= max) return t('admin.accounts.capacity.sessions.full', { idle })
   return t('admin.accounts.capacity.sessions.normal', { idle })
 })
 
-// 是否显示 RPM 限制
-const showRpmLimit = computed(() => {
-  return (
-    isAnthropicOAuthOrSetupToken.value &&
-    props.account.base_rpm !== undefined &&
-    props.account.base_rpm !== null &&
-    props.account.base_rpm > 0
-  )
-})
+// ====== RPM ======
+const showRpmLimit = computed(() =>
+  isAnthropicOAuthOrSetupToken.value &&
+  props.account.base_rpm != null &&
+  props.account.base_rpm > 0
+)
 
-// 当前 RPM 计数
 const currentRPM = computed(() => props.account.current_rpm ?? 0)
-
-// RPM 策略
 const rpmStrategy = computed(() => props.account.rpm_strategy || 'tiered')
+const rpmStrategyTag = computed(() => rpmStrategy.value === 'sticky_exempt' ? '[S]' : '[T]')
 
-// RPM 策略标签
-const rpmStrategyTag = computed(() => {
-  return rpmStrategy.value === 'sticky_exempt' ? '[S]' : '[T]'
-})
-
-// RPM buffer 计算（与后端一致：base <= 0 时 buffer 为 0）
 const rpmBuffer = computed(() => {
   const base = props.account.base_rpm || 0
   return props.account.rpm_sticky_buffer ?? (base > 0 ? Math.max(1, Math.floor(base / 5)) : 0)
 })
 
-// RPM 状态样式
 const rpmClass = computed(() => {
   if (!showRpmLimit.value) return ''
-
   const current = currentRPM.value
   const base = props.account.base_rpm ?? 0
   const buffer = rpmBuffer.value
-
   if (rpmStrategy.value === 'tiered') {
-    if (current >= base + buffer) {
-      return 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
-    }
-    if (current >= base) {
-      return 'bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400'
-    }
+    if (current >= base + buffer) return 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
+    if (current >= base) return 'bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400'
   } else {
-    if (current >= base) {
-      return 'bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400'
-    }
-  }
-  if (current >= base * 0.8) {
-    return 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
+    if (current >= base) return 'bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400'
   }
+  if (current >= base * 0.8) return 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
   return 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-400'
 })
 
-// RPM 提示文字（增强版：显示策略、区域、缓冲区）
 const rpmTooltip = computed(() => {
   if (!showRpmLimit.value) return ''
-
   const current = currentRPM.value
   const base = props.account.base_rpm ?? 0
   const buffer = rpmBuffer.value
-
   if (rpmStrategy.value === 'tiered') {
-    if (current >= base + buffer) {
-      return t('admin.accounts.capacity.rpm.tieredBlocked', { buffer })
-    }
-    if (current >= base) {
-      return t('admin.accounts.capacity.rpm.tieredStickyOnly', { buffer })
-    }
-    if (current >= base * 0.8) {
-      return t('admin.accounts.capacity.rpm.tieredWarning')
-    }
+    if (current >= base + buffer) return t('admin.accounts.capacity.rpm.tieredBlocked', { buffer })
+    if (current >= base) return t('admin.accounts.capacity.rpm.tieredStickyOnly', { buffer })
+    if (current >= base * 0.8) return t('admin.accounts.capacity.rpm.tieredWarning')
     return t('admin.accounts.capacity.rpm.tieredNormal')
   } else {
-    if (current >= base) {
-      return t('admin.accounts.capacity.rpm.stickyExemptOver')
-    }
-    if (current >= base * 0.8) {
-      return t('admin.accounts.capacity.rpm.stickyExemptWarning')
-    }
+    if (current >= base) return t('admin.accounts.capacity.rpm.stickyExemptOver')
+    if (current >= base * 0.8) return t('admin.accounts.capacity.rpm.stickyExemptWarning')
     return t('admin.accounts.capacity.rpm.stickyExemptNormal')
   }
 })
 
-// 是否显示各维度配额（apikey / bedrock 类型）
-const isQuotaEligible = computed(() => props.account.type === 'apikey' || props.account.type === 'bedrock')
-
-const showDailyQuota = computed(() => {
-  return isQuotaEligible.value && (props.account.quota_daily_limit ?? 0) > 0
-})
-
-const showWeeklyQuota = computed(() => {
-  return isQuotaEligible.value && (props.account.quota_weekly_limit ?? 0) > 0
-})
-
-const showTotalQuota = computed(() => {
-  return isQuotaEligible.value && (props.account.quota_limit ?? 0) > 0
-})
-
 // 格式化费用显示
 const formatCost = (value: number | null | undefined) => {
   if (value === null || value === undefined) return '0'
   return value.toFixed(2)
 }
+
+// ====== 配额 ======
+const isQuotaEligible = computed(() => props.account.type === 'apikey' || props.account.type === 'bedrock')
+
+const showDailyQuota = computed(() =>
+  isQuotaEligible.value && props.account.quota_daily_limit != null && props.account.quota_daily_limit > 0
+)
+const showWeeklyQuota = computed(() =>
+  isQuotaEligible.value && props.account.quota_weekly_limit != null && props.account.quota_weekly_limit > 0
+)
+const showTotalQuota = computed(() =>
+  isQuotaEligible.value && props.account.quota_limit != null && props.account.quota_limit > 0
+)
 </script>

frontend/src/components/account/AccountUsageCell.vue

@@ -439,15 +439,20 @@
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted, onUnmounted, watch } from 'vue'
+import { ref, computed, onMounted, onBeforeUnmount, onUnmounted, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { adminAPI } from '@/api/admin'
 import type { Account, AccountUsageInfo, GeminiCredentials, WindowStats } from '@/types'
 import { buildOpenAIUsageRefreshKey } from '@/utils/accountUsageRefresh'
+import { enqueueUsageRequest } from '@/utils/usageLoadQueue'
 import { formatCompactNumber } from '@/utils/format'
 import UsageProgressBar from './UsageProgressBar.vue'
 import AccountQuotaInfo from './AccountQuotaInfo.vue'
 
+// Module-level cache shared across all AccountUsageCell instances
+const _usageCache = new Map<number, { data: AccountUsageInfo; ts: number }>()
+const USAGE_CACHE_TTL = 5 * 60 * 1000 // 5 minutes
+
 const props = withDefaults(
   defineProps<{
     account: Account
@@ -465,6 +470,9 @@ const props = withDefaults(
 const { t } = useI18n()
 const desktopViewportQuery = '(min-width: 768px)'
 
+const unmounted = ref(false)
+onBeforeUnmount(() => { unmounted.value = true })
+
 const loading = ref(false)
 const activeQueryLoading = ref(false)
 const error = ref<string | null>(null)
@@ -941,19 +949,36 @@ const isAnthropicOAuthOrSetupToken = computed(() => {
   return props.account.platform === 'anthropic' && (props.account.type === 'oauth' || props.account.type === 'setup-token')
 })
 
-const loadUsage = async (source?: 'passive' | 'active') => {
+const loadUsage = async (options?: { source?: 'passive' | 'active'; bypassCache?: boolean }) => {
   if (!shouldFetchUsage.value) return
 
+  // Check cache
+  if (!options?.bypassCache) {
+    const cached = _usageCache.get(props.account.id)
+    if (cached && Date.now() - cached.ts < USAGE_CACHE_TTL) {
+      usageInfo.value = cached.data
+      loading.value = false
+      return
+    }
+  }
+
   loading.value = true
   error.value = null
 
   try {
-    usageInfo.value = await adminAPI.accounts.getUsage(props.account.id, source)
+    const fetchFn = () => adminAPI.accounts.getUsage(props.account.id, options?.source)
+    const result = await enqueueUsageRequest(props.account, fetchFn)
+    if (!unmounted.value) {
+      usageInfo.value = result
+      _usageCache.set(props.account.id, { data: result, ts: Date.now() })
+    }
   } catch (e: any) {
-    error.value = t('common.error')
-    console.error('Failed to load usage:', e)
+    if (!unmounted.value) {
+      error.value = t('common.error')
+      console.error('Failed to load usage:', e)
+    }
   } finally {
-    loading.value = false
+    if (!unmounted.value) loading.value = false
   }
 }
 
@@ -962,7 +987,7 @@ const flushPendingAutoLoad = () => {
   const source = pendingAutoLoadSource.value
   pendingAutoLoad.value = false
   pendingAutoLoadSource.value = undefined
-  loadUsage(source).catch((e) => {
+  loadUsage({ source }).catch((e) => {
     console.error('Failed to load deferred usage:', e)
   })
 }
@@ -974,7 +999,7 @@ const requestAutoLoad = (source?: 'passive' | 'active') => {
     pendingAutoLoadSource.value = source
     return
   }
-  loadUsage(source).catch((e) => {
+  loadUsage({ source }).catch((e) => {
     console.error('Failed to auto load usage:', e)
   })
 }
@@ -1138,7 +1163,10 @@ watch(
     if (!shouldFetchUsage.value) return
 
     const source = isAnthropicOAuthOrSetupToken.value ? 'passive' : undefined
-    requestAutoLoad(source)
+    _usageCache.delete(props.account.id)
+    loadUsage({ source, bypassCache: true }).catch((e) => {
+      console.error('Failed to refresh usage after manual refresh:', e)
+    })
   }
 )