chore: initial public snapshot for github upload

llm-gateway-competitors/sub2api-tar/backend/internal/config/wire.go

@@ -0,0 +1,13 @@
+package config
+
+import "github.com/google/wire"
+
+// ProviderSet 提供配置层的依赖
+var ProviderSet = wire.NewSet(
+	ProvideConfig,
+)
+
+// ProvideConfig 提供应用配置
+func ProvideConfig() (*Config, error) {
+	return LoadForBootstrap()
+}

llm-gateway-competitors/sub2api-tar/backend/internal/domain/announcement.go

@@ -0,0 +1,232 @@
+package domain
+
+import (
+	"strings"
+	"time"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+)
+
+const (
+	AnnouncementStatusDraft    = "draft"
+	AnnouncementStatusActive   = "active"
+	AnnouncementStatusArchived = "archived"
+)
+
+const (
+	AnnouncementNotifyModeSilent = "silent"
+	AnnouncementNotifyModePopup  = "popup"
+)
+
+const (
+	AnnouncementConditionTypeSubscription = "subscription"
+	AnnouncementConditionTypeBalance      = "balance"
+)
+
+const (
+	AnnouncementOperatorIn  = "in"
+	AnnouncementOperatorGT  = "gt"
+	AnnouncementOperatorGTE = "gte"
+	AnnouncementOperatorLT  = "lt"
+	AnnouncementOperatorLTE = "lte"
+	AnnouncementOperatorEQ  = "eq"
+)
+
+var (
+	ErrAnnouncementNotFound      = infraerrors.NotFound("ANNOUNCEMENT_NOT_FOUND", "announcement not found")
+	ErrAnnouncementInvalidTarget = infraerrors.BadRequest("ANNOUNCEMENT_INVALID_TARGET", "invalid announcement targeting rules")
+)
+
+type AnnouncementTargeting struct {
+	// AnyOf 表示 OR：任意一个条件组满足即可展示。
+	AnyOf []AnnouncementConditionGroup `json:"any_of,omitempty"`
+}
+
+type AnnouncementConditionGroup struct {
+	// AllOf 表示 AND：组内所有条件都满足才算命中该组。
+	AllOf []AnnouncementCondition `json:"all_of,omitempty"`
+}
+
+type AnnouncementCondition struct {
+	// Type: subscription | balance
+	Type string `json:"type"`
+
+	// Operator:
+	// - subscription: in
+	// - balance: gt/gte/lt/lte/eq
+	Operator string `json:"operator"`
+
+	// subscription 条件：匹配的订阅套餐（group_id）
+	GroupIDs []int64 `json:"group_ids,omitempty"`
+
+	// balance 条件：比较阈值
+	Value float64 `json:"value,omitempty"`
+}
+
+func (t AnnouncementTargeting) Matches(balance float64, activeSubscriptionGroupIDs map[int64]struct{}) bool {
+	// 空规则：展示给所有用户
+	if len(t.AnyOf) == 0 {
+		return true
+	}
+
+	for _, group := range t.AnyOf {
+		if len(group.AllOf) == 0 {
+			// 空条件组不命中（避免 OR 中出现无条件 “全命中”）
+			continue
+		}
+		allMatched := true
+		for _, cond := range group.AllOf {
+			if !cond.Matches(balance, activeSubscriptionGroupIDs) {
+				allMatched = false
+				break
+			}
+		}
+		if allMatched {
+			return true
+		}
+	}
+
+	return false
+}
+
+func (c AnnouncementCondition) Matches(balance float64, activeSubscriptionGroupIDs map[int64]struct{}) bool {
+	switch c.Type {
+	case AnnouncementConditionTypeSubscription:
+		if c.Operator != AnnouncementOperatorIn {
+			return false
+		}
+		if len(c.GroupIDs) == 0 {
+			return false
+		}
+		if len(activeSubscriptionGroupIDs) == 0 {
+			return false
+		}
+		for _, gid := range c.GroupIDs {
+			if _, ok := activeSubscriptionGroupIDs[gid]; ok {
+				return true
+			}
+		}
+		return false
+
+	case AnnouncementConditionTypeBalance:
+		switch c.Operator {
+		case AnnouncementOperatorGT:
+			return balance > c.Value
+		case AnnouncementOperatorGTE:
+			return balance >= c.Value
+		case AnnouncementOperatorLT:
+			return balance < c.Value
+		case AnnouncementOperatorLTE:
+			return balance <= c.Value
+		case AnnouncementOperatorEQ:
+			return balance == c.Value
+		default:
+			return false
+		}
+
+	default:
+		return false
+	}
+}
+
+func (t AnnouncementTargeting) NormalizeAndValidate() (AnnouncementTargeting, error) {
+	normalized := AnnouncementTargeting{AnyOf: make([]AnnouncementConditionGroup, 0, len(t.AnyOf))}
+
+	// 允许空 targeting（展示给所有用户）
+	if len(t.AnyOf) == 0 {
+		return normalized, nil
+	}
+
+	if len(t.AnyOf) > 50 {
+		return AnnouncementTargeting{}, ErrAnnouncementInvalidTarget
+	}
+
+	for _, g := range t.AnyOf {
+		if len(g.AllOf) == 0 {
+			return AnnouncementTargeting{}, ErrAnnouncementInvalidTarget
+		}
+		if len(g.AllOf) > 50 {
+			return AnnouncementTargeting{}, ErrAnnouncementInvalidTarget
+		}
+
+		group := AnnouncementConditionGroup{AllOf: make([]AnnouncementCondition, 0, len(g.AllOf))}
+		for _, c := range g.AllOf {
+			cond := AnnouncementCondition{
+				Type:     strings.TrimSpace(c.Type),
+				Operator: strings.TrimSpace(c.Operator),
+				Value:    c.Value,
+			}
+			for _, gid := range c.GroupIDs {
+				if gid <= 0 {
+					return AnnouncementTargeting{}, ErrAnnouncementInvalidTarget
+				}
+				cond.GroupIDs = append(cond.GroupIDs, gid)
+			}
+
+			if err := cond.validate(); err != nil {
+				return AnnouncementTargeting{}, err
+			}
+			group.AllOf = append(group.AllOf, cond)
+		}
+
+		normalized.AnyOf = append(normalized.AnyOf, group)
+	}
+
+	return normalized, nil
+}
+
+func (c AnnouncementCondition) validate() error {
+	switch c.Type {
+	case AnnouncementConditionTypeSubscription:
+		if c.Operator != AnnouncementOperatorIn {
+			return ErrAnnouncementInvalidTarget
+		}
+		if len(c.GroupIDs) == 0 {
+			return ErrAnnouncementInvalidTarget
+		}
+		return nil
+
+	case AnnouncementConditionTypeBalance:
+		switch c.Operator {
+		case AnnouncementOperatorGT, AnnouncementOperatorGTE, AnnouncementOperatorLT, AnnouncementOperatorLTE, AnnouncementOperatorEQ:
+			return nil
+		default:
+			return ErrAnnouncementInvalidTarget
+		}
+
+	default:
+		return ErrAnnouncementInvalidTarget
+	}
+}
+
+type Announcement struct {
+	ID         int64
+	Title      string
+	Content    string
+	Status     string
+	NotifyMode string
+	Targeting  AnnouncementTargeting
+	StartsAt   *time.Time
+	EndsAt     *time.Time
+	CreatedBy  *int64
+	UpdatedBy  *int64
+	CreatedAt  time.Time
+	UpdatedAt  time.Time
+}
+
+func (a *Announcement) IsActiveAt(now time.Time) bool {
+	if a == nil {
+		return false
+	}
+	if a.Status != AnnouncementStatusActive {
+		return false
+	}
+	if a.StartsAt != nil && now.Before(*a.StartsAt) {
+		return false
+	}
+	if a.EndsAt != nil && !now.Before(*a.EndsAt) {
+		// ends_at 语义：到点即下线
+		return false
+	}
+	return true
+}

llm-gateway-competitors/sub2api-tar/backend/internal/domain/constants.go

@@ -0,0 +1,140 @@
+package domain
+
+// Status constants
+const (
+	StatusActive   = "active"
+	StatusDisabled = "disabled"
+	StatusError    = "error"
+	StatusUnused   = "unused"
+	StatusUsed     = "used"
+	StatusExpired  = "expired"
+)
+
+// Role constants
+const (
+	RoleAdmin = "admin"
+	RoleUser  = "user"
+)
+
+// Platform constants
+const (
+	PlatformAnthropic   = "anthropic"
+	PlatformOpenAI      = "openai"
+	PlatformGemini      = "gemini"
+	PlatformAntigravity = "antigravity"
+	PlatformSora        = "sora"
+)
+
+// Account type constants
+const (
+	AccountTypeOAuth      = "oauth"       // OAuth类型账号（full scope: profile + inference）
+	AccountTypeSetupToken = "setup-token" // Setup Token类型账号（inference only scope）
+	AccountTypeAPIKey     = "apikey"      // API Key类型账号
+	AccountTypeUpstream   = "upstream"    // 上游透传类型账号（通过 Base URL + API Key 连接上游）
+	AccountTypeBedrock    = "bedrock"     // AWS Bedrock 类型账号（通过 SigV4 签名或 API Key 连接 Bedrock，由 credentials.auth_mode 区分）
+)
+
+// Redeem type constants
+const (
+	RedeemTypeBalance      = "balance"
+	RedeemTypeConcurrency  = "concurrency"
+	RedeemTypeSubscription = "subscription"
+	RedeemTypeInvitation   = "invitation"
+)
+
+// PromoCode status constants
+const (
+	PromoCodeStatusActive   = "active"
+	PromoCodeStatusDisabled = "disabled"
+)
+
+// Admin adjustment type constants
+const (
+	AdjustmentTypeAdminBalance     = "admin_balance"     // 管理员调整余额
+	AdjustmentTypeAdminConcurrency = "admin_concurrency" // 管理员调整并发数
+)
+
+// Group subscription type constants
+const (
+	SubscriptionTypeStandard     = "standard"     // 标准计费模式（按余额扣费）
+	SubscriptionTypeSubscription = "subscription" // 订阅模式（按限额控制）
+)
+
+// Subscription status constants
+const (
+	SubscriptionStatusActive    = "active"
+	SubscriptionStatusExpired   = "expired"
+	SubscriptionStatusSuspended = "suspended"
+)
+
+// DefaultAntigravityModelMapping 是 Antigravity 平台的默认模型映射
+// 当账号未配置 model_mapping 时使用此默认值
+// 与前端 useModelWhitelist.ts 中的 antigravityDefaultMappings 保持一致
+var DefaultAntigravityModelMapping = map[string]string{
+	// Claude 白名单
+	"claude-opus-4-6-thinking":   "claude-opus-4-6-thinking", // 官方模型
+	"claude-opus-4-6":            "claude-opus-4-6-thinking", // 简称映射
+	"claude-opus-4-5-thinking":   "claude-opus-4-6-thinking", // 迁移旧模型
+	"claude-sonnet-4-6":          "claude-sonnet-4-6",
+	"claude-sonnet-4-5":          "claude-sonnet-4-5",
+	"claude-sonnet-4-5-thinking": "claude-sonnet-4-5-thinking",
+	// Claude 详细版本 ID 映射
+	"claude-opus-4-5-20251101":   "claude-opus-4-6-thinking", // 迁移旧模型
+	"claude-sonnet-4-5-20250929": "claude-sonnet-4-5",
+	// Claude Haiku → Sonnet（无 Haiku 支持）
+	"claude-haiku-4-5":          "claude-sonnet-4-5",
+	"claude-haiku-4-5-20251001": "claude-sonnet-4-5",
+	// Gemini 2.5 白名单
+	"gemini-2.5-flash":               "gemini-2.5-flash",
+	"gemini-2.5-flash-image":         "gemini-2.5-flash-image",
+	"gemini-2.5-flash-image-preview": "gemini-2.5-flash-image",
+	"gemini-2.5-flash-lite":          "gemini-2.5-flash-lite",
+	"gemini-2.5-flash-thinking":      "gemini-2.5-flash-thinking",
+	"gemini-2.5-pro":                 "gemini-2.5-pro",
+	// Gemini 3 白名单
+	"gemini-3-flash":    "gemini-3-flash",
+	"gemini-3-pro-high": "gemini-3-pro-high",
+	"gemini-3-pro-low":  "gemini-3-pro-low",
+	// Gemini 3 preview 映射
+	"gemini-3-flash-preview": "gemini-3-flash",
+	"gemini-3-pro-preview":   "gemini-3-pro-high",
+	// Gemini 3.1 白名单
+	"gemini-3.1-pro-high": "gemini-3.1-pro-high",
+	"gemini-3.1-pro-low":  "gemini-3.1-pro-low",
+	// Gemini 3.1 preview 映射
+	"gemini-3.1-pro-preview": "gemini-3.1-pro-high",
+	// Gemini 3.1 image 白名单
+	"gemini-3.1-flash-image": "gemini-3.1-flash-image",
+	// Gemini 3.1 image preview 映射
+	"gemini-3.1-flash-image-preview": "gemini-3.1-flash-image",
+	// Gemini 3 image 兼容映射（向 3.1 image 迁移）
+	"gemini-3-pro-image":         "gemini-3.1-flash-image",
+	"gemini-3-pro-image-preview": "gemini-3.1-flash-image",
+	// 其他官方模型
+	"gpt-oss-120b-medium":    "gpt-oss-120b-medium",
+	"tab_flash_lite_preview": "tab_flash_lite_preview",
+}
+
+// DefaultBedrockModelMapping 是 AWS Bedrock 平台的默认模型映射
+// 将 Anthropic 标准模型名映射到 Bedrock 模型 ID
+// 注意：此处的 "us." 前缀仅为默认值，ResolveBedrockModelID 会根据账号配置的
+// aws_region 自动调整为匹配的区域前缀（如 eu.、apac.、jp. 等）
+var DefaultBedrockModelMapping = map[string]string{
+	// Claude Opus
+	"claude-opus-4-6-thinking": "us.anthropic.claude-opus-4-6-v1",
+	"claude-opus-4-6":          "us.anthropic.claude-opus-4-6-v1",
+	"claude-opus-4-5-thinking": "us.anthropic.claude-opus-4-5-20251101-v1:0",
+	"claude-opus-4-5-20251101": "us.anthropic.claude-opus-4-5-20251101-v1:0",
+	"claude-opus-4-1":          "us.anthropic.claude-opus-4-1-20250805-v1:0",
+	"claude-opus-4-20250514":   "us.anthropic.claude-opus-4-20250514-v1:0",
+	// Claude Sonnet
+	"claude-sonnet-4-6-thinking": "us.anthropic.claude-sonnet-4-6",
+	"claude-sonnet-4-6":          "us.anthropic.claude-sonnet-4-6",
+	"claude-sonnet-4-5":          "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+	"claude-sonnet-4-5-thinking": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+	"claude-sonnet-4-5-20250929": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+	"claude-sonnet-4-20250514":   "us.anthropic.claude-sonnet-4-20250514-v1:0",
+	// Claude Haiku
+	"claude-haiku-4-5":          "us.anthropic.claude-haiku-4-5-20251001-v1:0",
+	"claude-haiku-4-5-20251001": "us.anthropic.claude-haiku-4-5-20251001-v1:0",
+}

llm-gateway-competitors/sub2api-tar/backend/internal/domain/constants_test.go

@@ -0,0 +1,26 @@
+package domain
+
+import "testing"
+
+func TestDefaultAntigravityModelMapping_ImageCompatibilityAliases(t *testing.T) {
+	t.Parallel()
+
+	cases := map[string]string{
+		"gemini-2.5-flash-image":         "gemini-2.5-flash-image",
+		"gemini-2.5-flash-image-preview": "gemini-2.5-flash-image",
+		"gemini-3.1-flash-image":         "gemini-3.1-flash-image",
+		"gemini-3.1-flash-image-preview": "gemini-3.1-flash-image",
+		"gemini-3-pro-image":             "gemini-3.1-flash-image",
+		"gemini-3-pro-image-preview":     "gemini-3.1-flash-image",
+	}
+
+	for from, want := range cases {
+		got, ok := DefaultAntigravityModelMapping[from]
+		if !ok {
+			t.Fatalf("expected mapping for %q to exist", from)
+		}
+		if got != want {
+			t.Fatalf("unexpected mapping for %q: got %q want %q", from, got, want)
+		}
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/account_data.go

@@ -0,0 +1,606 @@
+package admin
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"log/slog"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	dataType       = "sub2api-data"
+	legacyDataType = "sub2api-bundle"
+	dataVersion    = 1
+	dataPageCap    = 1000
+)
+
+type DataPayload struct {
+	Type       string        `json:"type,omitempty"`
+	Version    int           `json:"version,omitempty"`
+	ExportedAt string        `json:"exported_at"`
+	Proxies    []DataProxy   `json:"proxies"`
+	Accounts   []DataAccount `json:"accounts"`
+}
+
+type DataProxy struct {
+	ProxyKey string `json:"proxy_key"`
+	Name     string `json:"name"`
+	Protocol string `json:"protocol"`
+	Host     string `json:"host"`
+	Port     int    `json:"port"`
+	Username string `json:"username,omitempty"`
+	Password string `json:"password,omitempty"`
+	Status   string `json:"status"`
+}
+
+type DataAccount struct {
+	Name               string         `json:"name"`
+	Notes              *string        `json:"notes,omitempty"`
+	Platform           string         `json:"platform"`
+	Type               string         `json:"type"`
+	Credentials        map[string]any `json:"credentials"`
+	Extra              map[string]any `json:"extra,omitempty"`
+	ProxyKey           *string        `json:"proxy_key,omitempty"`
+	Concurrency        int            `json:"concurrency"`
+	Priority           int            `json:"priority"`
+	RateMultiplier     *float64       `json:"rate_multiplier,omitempty"`
+	ExpiresAt          *int64         `json:"expires_at,omitempty"`
+	AutoPauseOnExpired *bool          `json:"auto_pause_on_expired,omitempty"`
+}
+
+type DataImportRequest struct {
+	Data                 DataPayload `json:"data"`
+	SkipDefaultGroupBind *bool       `json:"skip_default_group_bind"`
+}
+
+type DataImportResult struct {
+	ProxyCreated   int               `json:"proxy_created"`
+	ProxyReused    int               `json:"proxy_reused"`
+	ProxyFailed    int               `json:"proxy_failed"`
+	AccountCreated int               `json:"account_created"`
+	AccountFailed  int               `json:"account_failed"`
+	Errors         []DataImportError `json:"errors,omitempty"`
+}
+
+type DataImportError struct {
+	Kind     string `json:"kind"`
+	Name     string `json:"name,omitempty"`
+	ProxyKey string `json:"proxy_key,omitempty"`
+	Message  string `json:"message"`
+}
+
+func buildProxyKey(protocol, host string, port int, username, password string) string {
+	return fmt.Sprintf("%s|%s|%d|%s|%s", strings.TrimSpace(protocol), strings.TrimSpace(host), port, strings.TrimSpace(username), strings.TrimSpace(password))
+}
+
+func (h *AccountHandler) ExportData(c *gin.Context) {
+	ctx := c.Request.Context()
+
+	selectedIDs, err := parseAccountIDs(c)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	accounts, err := h.resolveExportAccounts(ctx, selectedIDs, c)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	includeProxies, err := parseIncludeProxies(c)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	var proxies []service.Proxy
+	if includeProxies {
+		proxies, err = h.resolveExportProxies(ctx, accounts)
+		if err != nil {
+			response.ErrorFrom(c, err)
+			return
+		}
+	} else {
+		proxies = []service.Proxy{}
+	}
+
+	proxyKeyByID := make(map[int64]string, len(proxies))
+	dataProxies := make([]DataProxy, 0, len(proxies))
+	for i := range proxies {
+		p := proxies[i]
+		key := buildProxyKey(p.Protocol, p.Host, p.Port, p.Username, p.Password)
+		proxyKeyByID[p.ID] = key
+		dataProxies = append(dataProxies, DataProxy{
+			ProxyKey: key,
+			Name:     p.Name,
+			Protocol: p.Protocol,
+			Host:     p.Host,
+			Port:     p.Port,
+			Username: p.Username,
+			Password: p.Password,
+			Status:   p.Status,
+		})
+	}
+
+	dataAccounts := make([]DataAccount, 0, len(accounts))
+	for i := range accounts {
+		acc := accounts[i]
+		var proxyKey *string
+		if acc.ProxyID != nil {
+			if key, ok := proxyKeyByID[*acc.ProxyID]; ok {
+				proxyKey = &key
+			}
+		}
+		var expiresAt *int64
+		if acc.ExpiresAt != nil {
+			v := acc.ExpiresAt.Unix()
+			expiresAt = &v
+		}
+		dataAccounts = append(dataAccounts, DataAccount{
+			Name:               acc.Name,
+			Notes:              acc.Notes,
+			Platform:           acc.Platform,
+			Type:               acc.Type,
+			Credentials:        acc.Credentials,
+			Extra:              acc.Extra,
+			ProxyKey:           proxyKey,
+			Concurrency:        acc.Concurrency,
+			Priority:           acc.Priority,
+			RateMultiplier:     acc.RateMultiplier,
+			ExpiresAt:          expiresAt,
+			AutoPauseOnExpired: &acc.AutoPauseOnExpired,
+		})
+	}
+
+	payload := DataPayload{
+		ExportedAt: time.Now().UTC().Format(time.RFC3339),
+		Proxies:    dataProxies,
+		Accounts:   dataAccounts,
+	}
+
+	response.Success(c, payload)
+}
+
+func (h *AccountHandler) ImportData(c *gin.Context) {
+	var req DataImportRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if err := validateDataHeader(req.Data); err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	executeAdminIdempotentJSON(c, "admin.accounts.import_data", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		return h.importData(ctx, req)
+	})
+}
+
+func (h *AccountHandler) importData(ctx context.Context, req DataImportRequest) (DataImportResult, error) {
+	skipDefaultGroupBind := true
+	if req.SkipDefaultGroupBind != nil {
+		skipDefaultGroupBind = *req.SkipDefaultGroupBind
+	}
+
+	dataPayload := req.Data
+	result := DataImportResult{}
+
+	existingProxies, err := h.listAllProxies(ctx)
+	if err != nil {
+		return result, err
+	}
+
+	proxyKeyToID := make(map[string]int64, len(existingProxies))
+	for i := range existingProxies {
+		p := existingProxies[i]
+		key := buildProxyKey(p.Protocol, p.Host, p.Port, p.Username, p.Password)
+		proxyKeyToID[key] = p.ID
+	}
+
+	for i := range dataPayload.Proxies {
+		item := dataPayload.Proxies[i]
+		key := item.ProxyKey
+		if key == "" {
+			key = buildProxyKey(item.Protocol, item.Host, item.Port, item.Username, item.Password)
+		}
+		if err := validateDataProxy(item); err != nil {
+			result.ProxyFailed++
+			result.Errors = append(result.Errors, DataImportError{
+				Kind:     "proxy",
+				Name:     item.Name,
+				ProxyKey: key,
+				Message:  err.Error(),
+			})
+			continue
+		}
+		normalizedStatus := normalizeProxyStatus(item.Status)
+		if existingID, ok := proxyKeyToID[key]; ok {
+			proxyKeyToID[key] = existingID
+			result.ProxyReused++
+			if normalizedStatus != "" {
+				if proxy, getErr := h.adminService.GetProxy(ctx, existingID); getErr == nil && proxy != nil && proxy.Status != normalizedStatus {
+					_, _ = h.adminService.UpdateProxy(ctx, existingID, &service.UpdateProxyInput{
+						Status: normalizedStatus,
+					})
+				}
+			}
+			continue
+		}
+
+		created, createErr := h.adminService.CreateProxy(ctx, &service.CreateProxyInput{
+			Name:     defaultProxyName(item.Name),
+			Protocol: item.Protocol,
+			Host:     item.Host,
+			Port:     item.Port,
+			Username: item.Username,
+			Password: item.Password,
+		})
+		if createErr != nil {
+			result.ProxyFailed++
+			result.Errors = append(result.Errors, DataImportError{
+				Kind:     "proxy",
+				Name:     item.Name,
+				ProxyKey: key,
+				Message:  createErr.Error(),
+			})
+			continue
+		}
+		proxyKeyToID[key] = created.ID
+		result.ProxyCreated++
+
+		if normalizedStatus != "" && normalizedStatus != created.Status {
+			_, _ = h.adminService.UpdateProxy(ctx, created.ID, &service.UpdateProxyInput{
+				Status: normalizedStatus,
+			})
+		}
+	}
+
+	for i := range dataPayload.Accounts {
+		item := dataPayload.Accounts[i]
+		if err := validateDataAccount(item); err != nil {
+			result.AccountFailed++
+			result.Errors = append(result.Errors, DataImportError{
+				Kind:    "account",
+				Name:    item.Name,
+				Message: err.Error(),
+			})
+			continue
+		}
+
+		var proxyID *int64
+		if item.ProxyKey != nil && *item.ProxyKey != "" {
+			if id, ok := proxyKeyToID[*item.ProxyKey]; ok {
+				proxyID = &id
+			} else {
+				result.AccountFailed++
+				result.Errors = append(result.Errors, DataImportError{
+					Kind:     "account",
+					Name:     item.Name,
+					ProxyKey: *item.ProxyKey,
+					Message:  "proxy_key not found",
+				})
+				continue
+			}
+		}
+
+		enrichCredentialsFromIDToken(&item)
+
+		accountInput := &service.CreateAccountInput{
+			Name:                 item.Name,
+			Notes:                item.Notes,
+			Platform:             item.Platform,
+			Type:                 item.Type,
+			Credentials:          item.Credentials,
+			Extra:                item.Extra,
+			ProxyID:              proxyID,
+			Concurrency:          item.Concurrency,
+			Priority:             item.Priority,
+			RateMultiplier:       item.RateMultiplier,
+			GroupIDs:             nil,
+			ExpiresAt:            item.ExpiresAt,
+			AutoPauseOnExpired:   item.AutoPauseOnExpired,
+			SkipDefaultGroupBind: skipDefaultGroupBind,
+		}
+
+		if _, err := h.adminService.CreateAccount(ctx, accountInput); err != nil {
+			result.AccountFailed++
+			result.Errors = append(result.Errors, DataImportError{
+				Kind:    "account",
+				Name:    item.Name,
+				Message: err.Error(),
+			})
+			continue
+		}
+		result.AccountCreated++
+	}
+
+	return result, nil
+}
+
+func (h *AccountHandler) listAllProxies(ctx context.Context) ([]service.Proxy, error) {
+	page := 1
+	pageSize := dataPageCap
+	var out []service.Proxy
+	for {
+		items, total, err := h.adminService.ListProxies(ctx, page, pageSize, "", "", "")
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, items...)
+		if len(out) >= int(total) || len(items) == 0 {
+			break
+		}
+		page++
+	}
+	return out, nil
+}
+
+func (h *AccountHandler) listAccountsFiltered(ctx context.Context, platform, accountType, status, search string) ([]service.Account, error) {
+	page := 1
+	pageSize := dataPageCap
+	var out []service.Account
+	for {
+		items, total, err := h.adminService.ListAccounts(ctx, page, pageSize, platform, accountType, status, search, 0)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, items...)
+		if len(out) >= int(total) || len(items) == 0 {
+			break
+		}
+		page++
+	}
+	return out, nil
+}
+
+func (h *AccountHandler) resolveExportAccounts(ctx context.Context, ids []int64, c *gin.Context) ([]service.Account, error) {
+	if len(ids) > 0 {
+		accounts, err := h.adminService.GetAccountsByIDs(ctx, ids)
+		if err != nil {
+			return nil, err
+		}
+		out := make([]service.Account, 0, len(accounts))
+		for _, acc := range accounts {
+			if acc == nil {
+				continue
+			}
+			out = append(out, *acc)
+		}
+		return out, nil
+	}
+
+	platform := c.Query("platform")
+	accountType := c.Query("type")
+	status := c.Query("status")
+	search := strings.TrimSpace(c.Query("search"))
+	if len(search) > 100 {
+		search = search[:100]
+	}
+	return h.listAccountsFiltered(ctx, platform, accountType, status, search)
+}
+
+func (h *AccountHandler) resolveExportProxies(ctx context.Context, accounts []service.Account) ([]service.Proxy, error) {
+	if len(accounts) == 0 {
+		return []service.Proxy{}, nil
+	}
+
+	seen := make(map[int64]struct{})
+	ids := make([]int64, 0)
+	for i := range accounts {
+		if accounts[i].ProxyID == nil {
+			continue
+		}
+		id := *accounts[i].ProxyID
+		if id <= 0 {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	if len(ids) == 0 {
+		return []service.Proxy{}, nil
+	}
+
+	return h.adminService.GetProxiesByIDs(ctx, ids)
+}
+
+func parseAccountIDs(c *gin.Context) ([]int64, error) {
+	values := c.QueryArray("ids")
+	if len(values) == 0 {
+		raw := strings.TrimSpace(c.Query("ids"))
+		if raw != "" {
+			values = []string{raw}
+		}
+	}
+	if len(values) == 0 {
+		return nil, nil
+	}
+
+	ids := make([]int64, 0, len(values))
+	for _, item := range values {
+		for _, part := range strings.Split(item, ",") {
+			part = strings.TrimSpace(part)
+			if part == "" {
+				continue
+			}
+			id, err := strconv.ParseInt(part, 10, 64)
+			if err != nil || id <= 0 {
+				return nil, fmt.Errorf("invalid account id: %s", part)
+			}
+			ids = append(ids, id)
+		}
+	}
+	return ids, nil
+}
+
+func parseIncludeProxies(c *gin.Context) (bool, error) {
+	raw := strings.TrimSpace(strings.ToLower(c.Query("include_proxies")))
+	if raw == "" {
+		return true, nil
+	}
+	switch raw {
+	case "1", "true", "yes", "on":
+		return true, nil
+	case "0", "false", "no", "off":
+		return false, nil
+	default:
+		return true, fmt.Errorf("invalid include_proxies value: %s", raw)
+	}
+}
+
+func validateDataHeader(payload DataPayload) error {
+	if payload.Type != "" && payload.Type != dataType && payload.Type != legacyDataType {
+		return fmt.Errorf("unsupported data type: %s", payload.Type)
+	}
+	if payload.Version != 0 && payload.Version != dataVersion {
+		return fmt.Errorf("unsupported data version: %d", payload.Version)
+	}
+	if payload.Proxies == nil {
+		return errors.New("proxies is required")
+	}
+	if payload.Accounts == nil {
+		return errors.New("accounts is required")
+	}
+	return nil
+}
+
+func validateDataProxy(item DataProxy) error {
+	if strings.TrimSpace(item.Protocol) == "" {
+		return errors.New("proxy protocol is required")
+	}
+	if strings.TrimSpace(item.Host) == "" {
+		return errors.New("proxy host is required")
+	}
+	if item.Port <= 0 || item.Port > 65535 {
+		return errors.New("proxy port is invalid")
+	}
+	switch item.Protocol {
+	case "http", "https", "socks5", "socks5h":
+	default:
+		return fmt.Errorf("proxy protocol is invalid: %s", item.Protocol)
+	}
+	if item.Status != "" {
+		normalizedStatus := normalizeProxyStatus(item.Status)
+		if normalizedStatus != service.StatusActive && normalizedStatus != "inactive" {
+			return fmt.Errorf("proxy status is invalid: %s", item.Status)
+		}
+	}
+	return nil
+}
+
+func validateDataAccount(item DataAccount) error {
+	if strings.TrimSpace(item.Name) == "" {
+		return errors.New("account name is required")
+	}
+	if strings.TrimSpace(item.Platform) == "" {
+		return errors.New("account platform is required")
+	}
+	if strings.TrimSpace(item.Type) == "" {
+		return errors.New("account type is required")
+	}
+	if len(item.Credentials) == 0 {
+		return errors.New("account credentials is required")
+	}
+	switch item.Type {
+	case service.AccountTypeOAuth, service.AccountTypeSetupToken, service.AccountTypeAPIKey, service.AccountTypeUpstream:
+	default:
+		return fmt.Errorf("account type is invalid: %s", item.Type)
+	}
+	if item.RateMultiplier != nil && *item.RateMultiplier < 0 {
+		return errors.New("rate_multiplier must be >= 0")
+	}
+	if item.Concurrency < 0 {
+		return errors.New("concurrency must be >= 0")
+	}
+	if item.Priority < 0 {
+		return errors.New("priority must be >= 0")
+	}
+	return nil
+}
+
+func defaultProxyName(name string) string {
+	if strings.TrimSpace(name) == "" {
+		return "imported-proxy"
+	}
+	return name
+}
+
+// enrichCredentialsFromIDToken performs best-effort extraction of user info fields
+// (email, plan_type, chatgpt_account_id, etc.) from id_token in credentials.
+// Only applies to OpenAI/Sora OAuth accounts. Skips expired token errors silently.
+// Existing credential values are never overwritten — only missing fields are filled.
+func enrichCredentialsFromIDToken(item *DataAccount) {
+	if item.Credentials == nil {
+		return
+	}
+	// Only enrich OpenAI/Sora OAuth accounts
+	platform := strings.ToLower(strings.TrimSpace(item.Platform))
+	if platform != service.PlatformOpenAI && platform != service.PlatformSora {
+		return
+	}
+	if strings.ToLower(strings.TrimSpace(item.Type)) != service.AccountTypeOAuth {
+		return
+	}
+
+	idToken, _ := item.Credentials["id_token"].(string)
+	if strings.TrimSpace(idToken) == "" {
+		return
+	}
+
+	// DecodeIDToken skips expiry validation — safe for imported data
+	claims, err := openai.DecodeIDToken(idToken)
+	if err != nil {
+		slog.Debug("import_enrich_id_token_decode_failed", "account", item.Name, "error", err)
+		return
+	}
+
+	userInfo := claims.GetUserInfo()
+	if userInfo == nil {
+		return
+	}
+
+	// Fill missing fields only (never overwrite existing values)
+	setIfMissing := func(key, value string) {
+		if value == "" {
+			return
+		}
+		if existing, _ := item.Credentials[key].(string); existing == "" {
+			item.Credentials[key] = value
+		}
+	}
+
+	setIfMissing("email", userInfo.Email)
+	setIfMissing("plan_type", userInfo.PlanType)
+	setIfMissing("chatgpt_account_id", userInfo.ChatGPTAccountID)
+	setIfMissing("chatgpt_user_id", userInfo.ChatGPTUserID)
+	setIfMissing("organization_id", userInfo.OrganizationID)
+}
+
+func normalizeProxyStatus(status string) string {
+	normalized := strings.TrimSpace(strings.ToLower(status))
+	switch normalized {
+	case "":
+		return ""
+	case service.StatusActive:
+		return service.StatusActive
+	case "inactive", service.StatusDisabled:
+		return "inactive"
+	default:
+		return normalized
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/account_data_handler_test.go

@@ -0,0 +1,232 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type dataResponse struct {
+	Code int         `json:"code"`
+	Data dataPayload `json:"data"`
+}
+
+type dataPayload struct {
+	Type     string        `json:"type"`
+	Version  int           `json:"version"`
+	Proxies  []dataProxy   `json:"proxies"`
+	Accounts []dataAccount `json:"accounts"`
+}
+
+type dataProxy struct {
+	ProxyKey string `json:"proxy_key"`
+	Name     string `json:"name"`
+	Protocol string `json:"protocol"`
+	Host     string `json:"host"`
+	Port     int    `json:"port"`
+	Username string `json:"username"`
+	Password string `json:"password"`
+	Status   string `json:"status"`
+}
+
+type dataAccount struct {
+	Name        string         `json:"name"`
+	Platform    string         `json:"platform"`
+	Type        string         `json:"type"`
+	Credentials map[string]any `json:"credentials"`
+	Extra       map[string]any `json:"extra"`
+	ProxyKey    *string        `json:"proxy_key"`
+	Concurrency int            `json:"concurrency"`
+	Priority    int            `json:"priority"`
+}
+
+func setupAccountDataRouter() (*gin.Engine, *stubAdminService) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	adminSvc := newStubAdminService()
+
+	h := NewAccountHandler(
+		adminSvc,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+	)
+
+	router.GET("/api/v1/admin/accounts/data", h.ExportData)
+	router.POST("/api/v1/admin/accounts/data", h.ImportData)
+	return router, adminSvc
+}
+
+func TestExportDataIncludesSecrets(t *testing.T) {
+	router, adminSvc := setupAccountDataRouter()
+
+	proxyID := int64(11)
+	adminSvc.proxies = []service.Proxy{
+		{
+			ID:       proxyID,
+			Name:     "proxy",
+			Protocol: "http",
+			Host:     "127.0.0.1",
+			Port:     8080,
+			Username: "user",
+			Password: "pass",
+			Status:   service.StatusActive,
+		},
+		{
+			ID:       12,
+			Name:     "orphan",
+			Protocol: "https",
+			Host:     "10.0.0.1",
+			Port:     443,
+			Username: "o",
+			Password: "p",
+			Status:   service.StatusActive,
+		},
+	}
+	adminSvc.accounts = []service.Account{
+		{
+			ID:          21,
+			Name:        "account",
+			Platform:    service.PlatformOpenAI,
+			Type:        service.AccountTypeOAuth,
+			Credentials: map[string]any{"token": "secret"},
+			Extra:       map[string]any{"note": "x"},
+			ProxyID:     &proxyID,
+			Concurrency: 3,
+			Priority:    50,
+			Status:      service.StatusDisabled,
+		},
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/accounts/data", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp dataResponse
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+	require.Empty(t, resp.Data.Type)
+	require.Equal(t, 0, resp.Data.Version)
+	require.Len(t, resp.Data.Proxies, 1)
+	require.Equal(t, "pass", resp.Data.Proxies[0].Password)
+	require.Len(t, resp.Data.Accounts, 1)
+	require.Equal(t, "secret", resp.Data.Accounts[0].Credentials["token"])
+}
+
+func TestExportDataWithoutProxies(t *testing.T) {
+	router, adminSvc := setupAccountDataRouter()
+
+	proxyID := int64(11)
+	adminSvc.proxies = []service.Proxy{
+		{
+			ID:       proxyID,
+			Name:     "proxy",
+			Protocol: "http",
+			Host:     "127.0.0.1",
+			Port:     8080,
+			Username: "user",
+			Password: "pass",
+			Status:   service.StatusActive,
+		},
+	}
+	adminSvc.accounts = []service.Account{
+		{
+			ID:          21,
+			Name:        "account",
+			Platform:    service.PlatformOpenAI,
+			Type:        service.AccountTypeOAuth,
+			Credentials: map[string]any{"token": "secret"},
+			ProxyID:     &proxyID,
+			Concurrency: 3,
+			Priority:    50,
+			Status:      service.StatusDisabled,
+		},
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/accounts/data?include_proxies=false", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp dataResponse
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+	require.Len(t, resp.Data.Proxies, 0)
+	require.Len(t, resp.Data.Accounts, 1)
+	require.Nil(t, resp.Data.Accounts[0].ProxyKey)
+}
+
+func TestImportDataReusesProxyAndSkipsDefaultGroup(t *testing.T) {
+	router, adminSvc := setupAccountDataRouter()
+
+	adminSvc.proxies = []service.Proxy{
+		{
+			ID:       1,
+			Name:     "proxy",
+			Protocol: "socks5",
+			Host:     "1.2.3.4",
+			Port:     1080,
+			Username: "u",
+			Password: "p",
+			Status:   service.StatusActive,
+		},
+	}
+
+	dataPayload := map[string]any{
+		"data": map[string]any{
+			"type":    dataType,
+			"version": dataVersion,
+			"proxies": []map[string]any{
+				{
+					"proxy_key": "socks5|1.2.3.4|1080|u|p",
+					"name":      "proxy",
+					"protocol":  "socks5",
+					"host":      "1.2.3.4",
+					"port":      1080,
+					"username":  "u",
+					"password":  "p",
+					"status":    "active",
+				},
+			},
+			"accounts": []map[string]any{
+				{
+					"name":        "acc",
+					"platform":    service.PlatformOpenAI,
+					"type":        service.AccountTypeOAuth,
+					"credentials": map[string]any{"token": "x"},
+					"proxy_key":   "socks5|1.2.3.4|1080|u|p",
+					"concurrency": 3,
+					"priority":    50,
+				},
+			},
+		},
+		"skip_default_group_bind": true,
+	}
+
+	body, _ := json.Marshal(dataPayload)
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/accounts/data", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	require.Len(t, adminSvc.createdProxies, 0)
+	require.Len(t, adminSvc.createdAccounts, 1)
+	require.True(t, adminSvc.createdAccounts[0].SkipDefaultGroupBind)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/account_handler_available_models_test.go

@@ -0,0 +1,105 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type availableModelsAdminService struct {
+	*stubAdminService
+	account service.Account
+}
+
+func (s *availableModelsAdminService) GetAccount(_ context.Context, id int64) (*service.Account, error) {
+	if s.account.ID == id {
+		acc := s.account
+		return &acc, nil
+	}
+	return s.stubAdminService.GetAccount(context.Background(), id)
+}
+
+func setupAvailableModelsRouter(adminSvc service.AdminService) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	handler := NewAccountHandler(adminSvc, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	router.GET("/api/v1/admin/accounts/:id/models", handler.GetAvailableModels)
+	return router
+}
+
+func TestAccountHandlerGetAvailableModels_OpenAIOAuthUsesExplicitModelMapping(t *testing.T) {
+	svc := &availableModelsAdminService{
+		stubAdminService: newStubAdminService(),
+		account: service.Account{
+			ID:       42,
+			Name:     "openai-oauth",
+			Platform: service.PlatformOpenAI,
+			Type:     service.AccountTypeOAuth,
+			Status:   service.StatusActive,
+			Credentials: map[string]any{
+				"model_mapping": map[string]any{
+					"gpt-5": "gpt-5.1",
+				},
+			},
+		},
+	}
+	router := setupAvailableModelsRouter(svc)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/accounts/42/models", nil)
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Len(t, resp.Data, 1)
+	require.Equal(t, "gpt-5", resp.Data[0].ID)
+}
+
+func TestAccountHandlerGetAvailableModels_OpenAIOAuthPassthroughFallsBackToDefaults(t *testing.T) {
+	svc := &availableModelsAdminService{
+		stubAdminService: newStubAdminService(),
+		account: service.Account{
+			ID:       43,
+			Name:     "openai-oauth-passthrough",
+			Platform: service.PlatformOpenAI,
+			Type:     service.AccountTypeOAuth,
+			Status:   service.StatusActive,
+			Credentials: map[string]any{
+				"model_mapping": map[string]any{
+					"gpt-5": "gpt-5.1",
+				},
+			},
+			Extra: map[string]any{
+				"openai_passthrough": true,
+			},
+		},
+	}
+	router := setupAvailableModelsRouter(svc)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/accounts/43/models", nil)
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.NotEmpty(t, resp.Data)
+	require.NotEqual(t, "gpt-5", resp.Data[0].ID)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/account_handler_mixed_channel_test.go

@@ -0,0 +1,198 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func setupAccountMixedChannelRouter(adminSvc *stubAdminService) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	accountHandler := NewAccountHandler(adminSvc, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	router.POST("/api/v1/admin/accounts/check-mixed-channel", accountHandler.CheckMixedChannel)
+	router.POST("/api/v1/admin/accounts", accountHandler.Create)
+	router.PUT("/api/v1/admin/accounts/:id", accountHandler.Update)
+	router.POST("/api/v1/admin/accounts/bulk-update", accountHandler.BulkUpdate)
+	return router
+}
+
+func TestAccountHandlerCheckMixedChannelNoRisk(t *testing.T) {
+	adminSvc := newStubAdminService()
+	router := setupAccountMixedChannelRouter(adminSvc)
+
+	body, _ := json.Marshal(map[string]any{
+		"platform":  "antigravity",
+		"group_ids": []int64{27},
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/accounts/check-mixed-channel", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, float64(0), resp["code"])
+	data, ok := resp["data"].(map[string]any)
+	require.True(t, ok)
+	require.Equal(t, false, data["has_risk"])
+	require.Equal(t, int64(0), adminSvc.lastMixedCheck.accountID)
+	require.Equal(t, "antigravity", adminSvc.lastMixedCheck.platform)
+	require.Equal(t, []int64{27}, adminSvc.lastMixedCheck.groupIDs)
+}
+
+func TestAccountHandlerCheckMixedChannelWithRisk(t *testing.T) {
+	adminSvc := newStubAdminService()
+	adminSvc.checkMixedErr = &service.MixedChannelError{
+		GroupID:         27,
+		GroupName:       "claude-max",
+		CurrentPlatform: "Antigravity",
+		OtherPlatform:   "Anthropic",
+	}
+	router := setupAccountMixedChannelRouter(adminSvc)
+
+	body, _ := json.Marshal(map[string]any{
+		"platform":   "antigravity",
+		"group_ids":  []int64{27},
+		"account_id": 99,
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/accounts/check-mixed-channel", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, float64(0), resp["code"])
+	data, ok := resp["data"].(map[string]any)
+	require.True(t, ok)
+	require.Equal(t, true, data["has_risk"])
+	require.Equal(t, "mixed_channel_warning", data["error"])
+	details, ok := data["details"].(map[string]any)
+	require.True(t, ok)
+	require.Equal(t, float64(27), details["group_id"])
+	require.Equal(t, "claude-max", details["group_name"])
+	require.Equal(t, "Antigravity", details["current_platform"])
+	require.Equal(t, "Anthropic", details["other_platform"])
+	require.Equal(t, int64(99), adminSvc.lastMixedCheck.accountID)
+}
+
+func TestAccountHandlerCreateMixedChannelConflictSimplifiedResponse(t *testing.T) {
+	adminSvc := newStubAdminService()
+	adminSvc.createAccountErr = &service.MixedChannelError{
+		GroupID:         27,
+		GroupName:       "claude-max",
+		CurrentPlatform: "Antigravity",
+		OtherPlatform:   "Anthropic",
+	}
+	router := setupAccountMixedChannelRouter(adminSvc)
+
+	body, _ := json.Marshal(map[string]any{
+		"name":        "ag-oauth-1",
+		"platform":    "antigravity",
+		"type":        "oauth",
+		"credentials": map[string]any{"refresh_token": "rt"},
+		"group_ids":   []int64{27},
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/accounts", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusConflict, rec.Code)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, "mixed_channel_warning", resp["error"])
+	require.Contains(t, resp["message"], "mixed_channel_warning")
+	_, hasDetails := resp["details"]
+	_, hasRequireConfirmation := resp["require_confirmation"]
+	require.False(t, hasDetails)
+	require.False(t, hasRequireConfirmation)
+}
+
+func TestAccountHandlerUpdateMixedChannelConflictSimplifiedResponse(t *testing.T) {
+	adminSvc := newStubAdminService()
+	adminSvc.updateAccountErr = &service.MixedChannelError{
+		GroupID:         27,
+		GroupName:       "claude-max",
+		CurrentPlatform: "Antigravity",
+		OtherPlatform:   "Anthropic",
+	}
+	router := setupAccountMixedChannelRouter(adminSvc)
+
+	body, _ := json.Marshal(map[string]any{
+		"group_ids": []int64{27},
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/accounts/3", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusConflict, rec.Code)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, "mixed_channel_warning", resp["error"])
+	require.Contains(t, resp["message"], "mixed_channel_warning")
+	_, hasDetails := resp["details"]
+	_, hasRequireConfirmation := resp["require_confirmation"]
+	require.False(t, hasDetails)
+	require.False(t, hasRequireConfirmation)
+}
+
+func TestAccountHandlerBulkUpdateMixedChannelConflict(t *testing.T) {
+	adminSvc := newStubAdminService()
+	adminSvc.bulkUpdateAccountErr = &service.MixedChannelError{
+		GroupID:         27,
+		GroupName:       "claude-max",
+		CurrentPlatform: "Antigravity",
+		OtherPlatform:   "Anthropic",
+	}
+	router := setupAccountMixedChannelRouter(adminSvc)
+
+	body, _ := json.Marshal(map[string]any{
+		"account_ids": []int64{1, 2, 3},
+		"group_ids":   []int64{27},
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/accounts/bulk-update", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusConflict, rec.Code)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, "mixed_channel_warning", resp["error"])
+	require.Contains(t, resp["message"], "claude-max")
+}
+
+func TestAccountHandlerBulkUpdateMixedChannelConfirmSkips(t *testing.T) {
+	adminSvc := newStubAdminService()
+	router := setupAccountMixedChannelRouter(adminSvc)
+
+	body, _ := json.Marshal(map[string]any{
+		"account_ids":                []int64{1, 2},
+		"group_ids":                  []int64{27},
+		"confirm_mixed_channel_risk": true,
+	})
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/accounts/bulk-update", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, float64(0), resp["code"])
+	data, ok := resp["data"].(map[string]any)
+	require.True(t, ok)
+	require.Equal(t, float64(2), data["success"])
+	require.Equal(t, float64(0), data["failed"])
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/account_handler_passthrough_test.go

@@ -0,0 +1,67 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAccountHandler_Create_AnthropicAPIKeyPassthroughExtraForwarded(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	adminSvc := newStubAdminService()
+	handler := NewAccountHandler(
+		adminSvc,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+	)
+
+	router := gin.New()
+	router.POST("/api/v1/admin/accounts", handler.Create)
+
+	body := map[string]any{
+		"name":     "anthropic-key-1",
+		"platform": "anthropic",
+		"type":     "apikey",
+		"credentials": map[string]any{
+			"api_key":  "sk-ant-xxx",
+			"base_url": "https://api.anthropic.com",
+		},
+		"extra": map[string]any{
+			"anthropic_passthrough": true,
+		},
+		"concurrency": 1,
+		"priority":    1,
+	}
+	raw, err := json.Marshal(body)
+	require.NoError(t, err)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/accounts", bytes.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.Len(t, adminSvc.createdAccounts, 1)
+
+	created := adminSvc.createdAccounts[0]
+	require.Equal(t, "anthropic", created.Platform)
+	require.Equal(t, "apikey", created.Type)
+	require.NotNil(t, created.Extra)
+	require.Equal(t, true, created.Extra["anthropic_passthrough"])
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/account_today_stats_cache.go

@@ -0,0 +1,25 @@
+package admin
+
+import (
+	"strconv"
+	"strings"
+	"time"
+)
+
+var accountTodayStatsBatchCache = newSnapshotCache(30 * time.Second)
+
+func buildAccountTodayStatsBatchCacheKey(accountIDs []int64) string {
+	if len(accountIDs) == 0 {
+		return "accounts_today_stats_empty"
+	}
+	var b strings.Builder
+	b.Grow(len(accountIDs) * 6)
+	_, _ = b.WriteString("accounts_today_stats:")
+	for i, id := range accountIDs {
+		if i > 0 {
+			_ = b.WriteByte(',')
+		}
+		_, _ = b.WriteString(strconv.FormatInt(id, 10))
+	}
+	return b.String()
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/admin_basic_handlers_test.go

@@ -0,0 +1,268 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func setupAdminRouter() (*gin.Engine, *stubAdminService) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	adminSvc := newStubAdminService()
+
+	userHandler := NewUserHandler(adminSvc, nil)
+	groupHandler := NewGroupHandler(adminSvc)
+	proxyHandler := NewProxyHandler(adminSvc)
+	redeemHandler := NewRedeemHandler(adminSvc, nil)
+
+	router.GET("/api/v1/admin/users", userHandler.List)
+	router.GET("/api/v1/admin/users/:id", userHandler.GetByID)
+	router.POST("/api/v1/admin/users", userHandler.Create)
+	router.PUT("/api/v1/admin/users/:id", userHandler.Update)
+	router.DELETE("/api/v1/admin/users/:id", userHandler.Delete)
+	router.POST("/api/v1/admin/users/:id/balance", userHandler.UpdateBalance)
+	router.GET("/api/v1/admin/users/:id/api-keys", userHandler.GetUserAPIKeys)
+	router.GET("/api/v1/admin/users/:id/usage", userHandler.GetUserUsage)
+
+	router.GET("/api/v1/admin/groups", groupHandler.List)
+	router.GET("/api/v1/admin/groups/all", groupHandler.GetAll)
+	router.GET("/api/v1/admin/groups/:id", groupHandler.GetByID)
+	router.POST("/api/v1/admin/groups", groupHandler.Create)
+	router.PUT("/api/v1/admin/groups/:id", groupHandler.Update)
+	router.DELETE("/api/v1/admin/groups/:id", groupHandler.Delete)
+	router.GET("/api/v1/admin/groups/:id/stats", groupHandler.GetStats)
+	router.GET("/api/v1/admin/groups/:id/api-keys", groupHandler.GetGroupAPIKeys)
+
+	router.GET("/api/v1/admin/proxies", proxyHandler.List)
+	router.GET("/api/v1/admin/proxies/all", proxyHandler.GetAll)
+	router.GET("/api/v1/admin/proxies/:id", proxyHandler.GetByID)
+	router.POST("/api/v1/admin/proxies", proxyHandler.Create)
+	router.PUT("/api/v1/admin/proxies/:id", proxyHandler.Update)
+	router.DELETE("/api/v1/admin/proxies/:id", proxyHandler.Delete)
+	router.POST("/api/v1/admin/proxies/batch-delete", proxyHandler.BatchDelete)
+	router.POST("/api/v1/admin/proxies/:id/test", proxyHandler.Test)
+	router.POST("/api/v1/admin/proxies/:id/quality-check", proxyHandler.CheckQuality)
+	router.GET("/api/v1/admin/proxies/:id/stats", proxyHandler.GetStats)
+	router.GET("/api/v1/admin/proxies/:id/accounts", proxyHandler.GetProxyAccounts)
+
+	router.GET("/api/v1/admin/redeem-codes", redeemHandler.List)
+	router.GET("/api/v1/admin/redeem-codes/:id", redeemHandler.GetByID)
+	router.POST("/api/v1/admin/redeem-codes", redeemHandler.Generate)
+	router.DELETE("/api/v1/admin/redeem-codes/:id", redeemHandler.Delete)
+	router.POST("/api/v1/admin/redeem-codes/batch-delete", redeemHandler.BatchDelete)
+	router.POST("/api/v1/admin/redeem-codes/:id/expire", redeemHandler.Expire)
+	router.GET("/api/v1/admin/redeem-codes/:id/stats", redeemHandler.GetStats)
+
+	return router, adminSvc
+}
+
+func TestUserHandlerEndpoints(t *testing.T) {
+	router, _ := setupAdminRouter()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/users?page=1&page_size=20", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/users/1", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	createBody := map[string]any{"email": "new@example.com", "password": "pass123", "balance": 1, "concurrency": 2}
+	body, _ := json.Marshal(createBody)
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/users", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	updateBody := map[string]any{"email": "updated@example.com"}
+	body, _ = json.Marshal(updateBody)
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPut, "/api/v1/admin/users/1", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodDelete, "/api/v1/admin/users/1", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/users/1/balance", bytes.NewBufferString(`{"balance":1,"operation":"add"}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/users/1/api-keys", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/users/1/usage?period=today", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+}
+
+func TestGroupHandlerEndpoints(t *testing.T) {
+	router, _ := setupAdminRouter()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/groups", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/groups/all", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/groups/2", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	body, _ := json.Marshal(map[string]any{"name": "new", "platform": "anthropic", "subscription_type": "standard"})
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/groups", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	body, _ = json.Marshal(map[string]any{"name": "update"})
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPut, "/api/v1/admin/groups/2", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodDelete, "/api/v1/admin/groups/2", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/groups/2/stats", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/groups/2/api-keys", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+}
+
+func TestProxyHandlerEndpoints(t *testing.T) {
+	router, _ := setupAdminRouter()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/proxies", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/proxies/all", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/proxies/4", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	body, _ := json.Marshal(map[string]any{"name": "proxy", "protocol": "http", "host": "localhost", "port": 8080})
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/proxies", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	body, _ = json.Marshal(map[string]any{"name": "proxy2"})
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPut, "/api/v1/admin/proxies/4", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodDelete, "/api/v1/admin/proxies/4", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/proxies/batch-delete", bytes.NewBufferString(`{"ids":[1,2]}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/proxies/4/test", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/proxies/4/quality-check", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/proxies/4/stats", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/proxies/4/accounts", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+}
+
+func TestRedeemHandlerEndpoints(t *testing.T) {
+	router, _ := setupAdminRouter()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/redeem-codes", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/redeem-codes/5", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	body, _ := json.Marshal(map[string]any{"count": 1, "type": "balance", "value": 10})
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/redeem-codes", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodDelete, "/api/v1/admin/redeem-codes/5", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/redeem-codes/batch-delete", bytes.NewBufferString(`{"ids":[1,2]}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/redeem-codes/5/expire", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/redeem-codes/5/stats", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/admin_helpers_test.go

@@ -0,0 +1,224 @@
+package admin
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseTimeRange(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	req := httptest.NewRequest(http.MethodGet, "/?start_date=2024-01-01&end_date=2024-01-02&timezone=UTC", nil)
+	c.Request = req
+
+	start, end := parseTimeRange(c)
+	require.Equal(t, time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC), start)
+	require.Equal(t, time.Date(2024, 1, 3, 0, 0, 0, 0, time.UTC), end)
+
+	req = httptest.NewRequest(http.MethodGet, "/?start_date=bad&timezone=UTC", nil)
+	c.Request = req
+	start, end = parseTimeRange(c)
+	require.False(t, start.IsZero())
+	require.False(t, end.IsZero())
+}
+
+func TestParseOpsViewParam(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/?view=excluded", nil)
+	require.Equal(t, opsListViewExcluded, parseOpsViewParam(c))
+
+	c2, _ := gin.CreateTestContext(w)
+	c2.Request = httptest.NewRequest(http.MethodGet, "/?view=all", nil)
+	require.Equal(t, opsListViewAll, parseOpsViewParam(c2))
+
+	c3, _ := gin.CreateTestContext(w)
+	c3.Request = httptest.NewRequest(http.MethodGet, "/?view=unknown", nil)
+	require.Equal(t, opsListViewErrors, parseOpsViewParam(c3))
+
+	require.Equal(t, "", parseOpsViewParam(nil))
+}
+
+func TestParseOpsDuration(t *testing.T) {
+	dur, ok := parseOpsDuration("1h")
+	require.True(t, ok)
+	require.Equal(t, time.Hour, dur)
+
+	_, ok = parseOpsDuration("invalid")
+	require.False(t, ok)
+}
+
+func TestParseOpsOpenAITokenStatsDuration(t *testing.T) {
+	tests := []struct {
+		input string
+		want  time.Duration
+		ok    bool
+	}{
+		{input: "30m", want: 30 * time.Minute, ok: true},
+		{input: "1h", want: time.Hour, ok: true},
+		{input: "1d", want: 24 * time.Hour, ok: true},
+		{input: "15d", want: 15 * 24 * time.Hour, ok: true},
+		{input: "30d", want: 30 * 24 * time.Hour, ok: true},
+		{input: "7d", want: 0, ok: false},
+	}
+
+	for _, tt := range tests {
+		got, ok := parseOpsOpenAITokenStatsDuration(tt.input)
+		require.Equal(t, tt.ok, ok, "input=%s", tt.input)
+		require.Equal(t, tt.want, got, "input=%s", tt.input)
+	}
+}
+
+func TestParseOpsOpenAITokenStatsFilter_Defaults(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+
+	before := time.Now().UTC()
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	after := time.Now().UTC()
+
+	require.NoError(t, err)
+	require.NotNil(t, filter)
+	require.Equal(t, "30d", filter.TimeRange)
+	require.Equal(t, 1, filter.Page)
+	require.Equal(t, 20, filter.PageSize)
+	require.Equal(t, 0, filter.TopN)
+	require.Nil(t, filter.GroupID)
+	require.Equal(t, "", filter.Platform)
+	require.True(t, filter.StartTime.Before(filter.EndTime))
+	require.WithinDuration(t, before.Add(-30*24*time.Hour), filter.StartTime, 2*time.Second)
+	require.WithinDuration(t, after, filter.EndTime, 2*time.Second)
+}
+
+func TestParseOpsOpenAITokenStatsFilter_WithTopN(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(
+		http.MethodGet,
+		"/?time_range=1h&platform=openai&group_id=12&top_n=50",
+		nil,
+	)
+
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	require.NoError(t, err)
+	require.Equal(t, "1h", filter.TimeRange)
+	require.Equal(t, "openai", filter.Platform)
+	require.NotNil(t, filter.GroupID)
+	require.Equal(t, int64(12), *filter.GroupID)
+	require.Equal(t, 50, filter.TopN)
+	require.Equal(t, 0, filter.Page)
+	require.Equal(t, 0, filter.PageSize)
+}
+
+func TestParseOpsOpenAITokenStatsFilter_InvalidParams(t *testing.T) {
+	tests := []string{
+		"/?time_range=7d",
+		"/?group_id=0",
+		"/?group_id=abc",
+		"/?top_n=0",
+		"/?top_n=101",
+		"/?top_n=10&page=1",
+		"/?top_n=10&page_size=20",
+		"/?page=0",
+		"/?page_size=0",
+		"/?page_size=101",
+	}
+
+	gin.SetMode(gin.TestMode)
+	for _, rawURL := range tests {
+		w := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest(http.MethodGet, rawURL, nil)
+
+		_, err := parseOpsOpenAITokenStatsFilter(c)
+		require.Error(t, err, "url=%s", rawURL)
+	}
+}
+
+func TestParseOpsTimeRange(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	now := time.Now().UTC()
+	startStr := now.Add(-time.Hour).Format(time.RFC3339)
+	endStr := now.Format(time.RFC3339)
+	c.Request = httptest.NewRequest(http.MethodGet, "/?start_time="+startStr+"&end_time="+endStr, nil)
+	start, end, err := parseOpsTimeRange(c, "1h")
+	require.NoError(t, err)
+	require.True(t, start.Before(end))
+
+	c2, _ := gin.CreateTestContext(w)
+	c2.Request = httptest.NewRequest(http.MethodGet, "/?start_time=bad", nil)
+	_, _, err = parseOpsTimeRange(c2, "1h")
+	require.Error(t, err)
+}
+
+func TestParseOpsRealtimeWindow(t *testing.T) {
+	dur, label, ok := parseOpsRealtimeWindow("5m")
+	require.True(t, ok)
+	require.Equal(t, 5*time.Minute, dur)
+	require.Equal(t, "5min", label)
+
+	_, _, ok = parseOpsRealtimeWindow("invalid")
+	require.False(t, ok)
+}
+
+func TestPickThroughputBucketSeconds(t *testing.T) {
+	require.Equal(t, 60, pickThroughputBucketSeconds(30*time.Minute))
+	require.Equal(t, 300, pickThroughputBucketSeconds(6*time.Hour))
+	require.Equal(t, 3600, pickThroughputBucketSeconds(48*time.Hour))
+}
+
+func TestParseOpsQueryMode(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/?mode=raw", nil)
+	require.Equal(t, service.ParseOpsQueryMode("raw"), parseOpsQueryMode(c))
+	require.Equal(t, service.OpsQueryMode(""), parseOpsQueryMode(nil))
+}
+
+func TestOpsAlertRuleValidation(t *testing.T) {
+	raw := map[string]json.RawMessage{
+		"name":        json.RawMessage(`"High error rate"`),
+		"metric_type": json.RawMessage(`"error_rate"`),
+		"operator":    json.RawMessage(`">"`),
+		"threshold":   json.RawMessage(`90`),
+	}
+
+	validated, err := validateOpsAlertRulePayload(raw)
+	require.NoError(t, err)
+	require.Equal(t, "High error rate", validated.Name)
+
+	_, err = validateOpsAlertRulePayload(map[string]json.RawMessage{})
+	require.Error(t, err)
+
+	require.True(t, isPercentOrRateMetric("error_rate"))
+	require.False(t, isPercentOrRateMetric("concurrency_queue_depth"))
+}
+
+func TestOpsWSHelpers(t *testing.T) {
+	prefixes, invalid := parseTrustedProxyList("10.0.0.0/8,invalid")
+	require.Len(t, prefixes, 1)
+	require.Len(t, invalid, 1)
+
+	host := hostWithoutPort("example.com:443")
+	require.Equal(t, "example.com", host)
+
+	addr := netip.MustParseAddr("10.0.0.1")
+	require.True(t, isAddrInTrustedProxies(addr, prefixes))
+	require.False(t, isAddrInTrustedProxies(netip.MustParseAddr("192.168.0.1"), prefixes))
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/admin_service_stub_test.go

@@ -0,0 +1,449 @@
+package admin
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+type stubAdminService struct {
+	users                []service.User
+	apiKeys              []service.APIKey
+	groups               []service.Group
+	accounts             []service.Account
+	proxies              []service.Proxy
+	proxyCounts          []service.ProxyWithAccountCount
+	redeems              []service.RedeemCode
+	createdAccounts      []*service.CreateAccountInput
+	createdProxies       []*service.CreateProxyInput
+	updatedProxyIDs      []int64
+	updatedProxies       []*service.UpdateProxyInput
+	testedProxyIDs       []int64
+	createAccountErr     error
+	updateAccountErr     error
+	bulkUpdateAccountErr error
+	checkMixedErr        error
+	lastMixedCheck       struct {
+		accountID int64
+		platform  string
+		groupIDs  []int64
+	}
+	mu sync.Mutex
+}
+
+func newStubAdminService() *stubAdminService {
+	now := time.Now().UTC()
+	user := service.User{
+		ID:        1,
+		Email:     "user@example.com",
+		Role:      service.RoleUser,
+		Status:    service.StatusActive,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	apiKey := service.APIKey{
+		ID:        10,
+		UserID:    user.ID,
+		Key:       "sk-test",
+		Name:      "test",
+		Status:    service.StatusActive,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	group := service.Group{
+		ID:        2,
+		Name:      "group",
+		Platform:  service.PlatformAnthropic,
+		Status:    service.StatusActive,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	account := service.Account{
+		ID:        3,
+		Name:      "account",
+		Platform:  service.PlatformAnthropic,
+		Type:      service.AccountTypeOAuth,
+		Status:    service.StatusActive,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	proxy := service.Proxy{
+		ID:        4,
+		Name:      "proxy",
+		Protocol:  "http",
+		Host:      "127.0.0.1",
+		Port:      8080,
+		Status:    service.StatusActive,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	redeem := service.RedeemCode{
+		ID:        5,
+		Code:      "R-TEST",
+		Type:      service.RedeemTypeBalance,
+		Value:     10,
+		Status:    service.StatusUnused,
+		CreatedAt: now,
+	}
+	return &stubAdminService{
+		users:       []service.User{user},
+		apiKeys:     []service.APIKey{apiKey},
+		groups:      []service.Group{group},
+		accounts:    []service.Account{account},
+		proxies:     []service.Proxy{proxy},
+		proxyCounts: []service.ProxyWithAccountCount{{Proxy: proxy, AccountCount: 1}},
+		redeems:     []service.RedeemCode{redeem},
+	}
+}
+
+func (s *stubAdminService) ListUsers(ctx context.Context, page, pageSize int, filters service.UserListFilters) ([]service.User, int64, error) {
+	return s.users, int64(len(s.users)), nil
+}
+
+func (s *stubAdminService) GetUser(ctx context.Context, id int64) (*service.User, error) {
+	for i := range s.users {
+		if s.users[i].ID == id {
+			return &s.users[i], nil
+		}
+	}
+	user := service.User{ID: id, Email: "user@example.com", Status: service.StatusActive}
+	return &user, nil
+}
+
+func (s *stubAdminService) CreateUser(ctx context.Context, input *service.CreateUserInput) (*service.User, error) {
+	user := service.User{ID: 100, Email: input.Email, Status: service.StatusActive}
+	return &user, nil
+}
+
+func (s *stubAdminService) UpdateUser(ctx context.Context, id int64, input *service.UpdateUserInput) (*service.User, error) {
+	user := service.User{ID: id, Email: "updated@example.com", Status: service.StatusActive}
+	return &user, nil
+}
+
+func (s *stubAdminService) DeleteUser(ctx context.Context, id int64) error {
+	return nil
+}
+
+func (s *stubAdminService) UpdateUserBalance(ctx context.Context, userID int64, balance float64, operation string, notes string) (*service.User, error) {
+	user := service.User{ID: userID, Balance: balance, Status: service.StatusActive}
+	return &user, nil
+}
+
+func (s *stubAdminService) GetUserAPIKeys(ctx context.Context, userID int64, page, pageSize int) ([]service.APIKey, int64, error) {
+	return s.apiKeys, int64(len(s.apiKeys)), nil
+}
+
+func (s *stubAdminService) GetUserUsageStats(ctx context.Context, userID int64, period string) (any, error) {
+	return map[string]any{"user_id": userID}, nil
+}
+
+func (s *stubAdminService) ListGroups(ctx context.Context, page, pageSize int, platform, status, search string, isExclusive *bool) ([]service.Group, int64, error) {
+	return s.groups, int64(len(s.groups)), nil
+}
+
+func (s *stubAdminService) GetAllGroups(ctx context.Context) ([]service.Group, error) {
+	return s.groups, nil
+}
+
+func (s *stubAdminService) GetAllGroupsByPlatform(ctx context.Context, platform string) ([]service.Group, error) {
+	return s.groups, nil
+}
+
+func (s *stubAdminService) GetGroup(ctx context.Context, id int64) (*service.Group, error) {
+	group := service.Group{ID: id, Name: "group", Status: service.StatusActive}
+	return &group, nil
+}
+
+func (s *stubAdminService) CreateGroup(ctx context.Context, input *service.CreateGroupInput) (*service.Group, error) {
+	group := service.Group{ID: 200, Name: input.Name, Status: service.StatusActive}
+	return &group, nil
+}
+
+func (s *stubAdminService) UpdateGroup(ctx context.Context, id int64, input *service.UpdateGroupInput) (*service.Group, error) {
+	group := service.Group{ID: id, Name: input.Name, Status: service.StatusActive}
+	return &group, nil
+}
+
+func (s *stubAdminService) DeleteGroup(ctx context.Context, id int64) error {
+	return nil
+}
+
+func (s *stubAdminService) GetGroupAPIKeys(ctx context.Context, groupID int64, page, pageSize int) ([]service.APIKey, int64, error) {
+	return s.apiKeys, int64(len(s.apiKeys)), nil
+}
+
+func (s *stubAdminService) GetGroupRateMultipliers(_ context.Context, _ int64) ([]service.UserGroupRateEntry, error) {
+	return nil, nil
+}
+
+func (s *stubAdminService) ClearGroupRateMultipliers(_ context.Context, _ int64) error {
+	return nil
+}
+
+func (s *stubAdminService) BatchSetGroupRateMultipliers(_ context.Context, _ int64, _ []service.GroupRateMultiplierInput) error {
+	return nil
+}
+
+func (s *stubAdminService) ListAccounts(ctx context.Context, page, pageSize int, platform, accountType, status, search string, groupID int64) ([]service.Account, int64, error) {
+	return s.accounts, int64(len(s.accounts)), nil
+}
+
+func (s *stubAdminService) GetAccount(ctx context.Context, id int64) (*service.Account, error) {
+	account := service.Account{ID: id, Name: "account", Status: service.StatusActive}
+	return &account, nil
+}
+
+func (s *stubAdminService) GetAccountsByIDs(ctx context.Context, ids []int64) ([]*service.Account, error) {
+	out := make([]*service.Account, 0, len(ids))
+	for _, id := range ids {
+		account := service.Account{ID: id, Name: "account", Status: service.StatusActive}
+		out = append(out, &account)
+	}
+	return out, nil
+}
+
+func (s *stubAdminService) CreateAccount(ctx context.Context, input *service.CreateAccountInput) (*service.Account, error) {
+	s.mu.Lock()
+	s.createdAccounts = append(s.createdAccounts, input)
+	s.mu.Unlock()
+	if s.createAccountErr != nil {
+		return nil, s.createAccountErr
+	}
+	account := service.Account{ID: 300, Name: input.Name, Status: service.StatusActive}
+	return &account, nil
+}
+
+func (s *stubAdminService) UpdateAccount(ctx context.Context, id int64, input *service.UpdateAccountInput) (*service.Account, error) {
+	if s.updateAccountErr != nil {
+		return nil, s.updateAccountErr
+	}
+	account := service.Account{ID: id, Name: input.Name, Status: service.StatusActive}
+	return &account, nil
+}
+
+func (s *stubAdminService) DeleteAccount(ctx context.Context, id int64) error {
+	return nil
+}
+
+func (s *stubAdminService) RefreshAccountCredentials(ctx context.Context, id int64) (*service.Account, error) {
+	account := service.Account{ID: id, Name: "account", Status: service.StatusActive}
+	return &account, nil
+}
+
+func (s *stubAdminService) ClearAccountError(ctx context.Context, id int64) (*service.Account, error) {
+	account := service.Account{ID: id, Name: "account", Status: service.StatusActive}
+	return &account, nil
+}
+
+func (s *stubAdminService) SetAccountError(ctx context.Context, id int64, errorMsg string) error {
+	return nil
+}
+
+func (s *stubAdminService) SetAccountSchedulable(ctx context.Context, id int64, schedulable bool) (*service.Account, error) {
+	account := service.Account{ID: id, Name: "account", Status: service.StatusActive, Schedulable: schedulable}
+	return &account, nil
+}
+
+func (s *stubAdminService) BulkUpdateAccounts(ctx context.Context, input *service.BulkUpdateAccountsInput) (*service.BulkUpdateAccountsResult, error) {
+	if s.bulkUpdateAccountErr != nil {
+		return nil, s.bulkUpdateAccountErr
+	}
+	return &service.BulkUpdateAccountsResult{Success: len(input.AccountIDs), Failed: 0, SuccessIDs: input.AccountIDs}, nil
+}
+
+func (s *stubAdminService) CheckMixedChannelRisk(ctx context.Context, currentAccountID int64, currentAccountPlatform string, groupIDs []int64) error {
+	s.lastMixedCheck.accountID = currentAccountID
+	s.lastMixedCheck.platform = currentAccountPlatform
+	s.lastMixedCheck.groupIDs = append([]int64(nil), groupIDs...)
+	return s.checkMixedErr
+}
+
+func (s *stubAdminService) ListProxies(ctx context.Context, page, pageSize int, protocol, status, search string) ([]service.Proxy, int64, error) {
+	search = strings.TrimSpace(strings.ToLower(search))
+	filtered := make([]service.Proxy, 0, len(s.proxies))
+	for _, proxy := range s.proxies {
+		if protocol != "" && proxy.Protocol != protocol {
+			continue
+		}
+		if status != "" && proxy.Status != status {
+			continue
+		}
+		if search != "" {
+			name := strings.ToLower(proxy.Name)
+			host := strings.ToLower(proxy.Host)
+			if !strings.Contains(name, search) && !strings.Contains(host, search) {
+				continue
+			}
+		}
+		filtered = append(filtered, proxy)
+	}
+	return filtered, int64(len(filtered)), nil
+}
+
+func (s *stubAdminService) ListProxiesWithAccountCount(ctx context.Context, page, pageSize int, protocol, status, search string) ([]service.ProxyWithAccountCount, int64, error) {
+	return s.proxyCounts, int64(len(s.proxyCounts)), nil
+}
+
+func (s *stubAdminService) GetAllProxies(ctx context.Context) ([]service.Proxy, error) {
+	return s.proxies, nil
+}
+
+func (s *stubAdminService) GetAllProxiesWithAccountCount(ctx context.Context) ([]service.ProxyWithAccountCount, error) {
+	return s.proxyCounts, nil
+}
+
+func (s *stubAdminService) GetProxy(ctx context.Context, id int64) (*service.Proxy, error) {
+	for i := range s.proxies {
+		proxy := s.proxies[i]
+		if proxy.ID == id {
+			return &proxy, nil
+		}
+	}
+	proxy := service.Proxy{ID: id, Name: "proxy", Status: service.StatusActive}
+	return &proxy, nil
+}
+
+func (s *stubAdminService) GetProxiesByIDs(ctx context.Context, ids []int64) ([]service.Proxy, error) {
+	if len(ids) == 0 {
+		return []service.Proxy{}, nil
+	}
+	out := make([]service.Proxy, 0, len(ids))
+	seen := make(map[int64]struct{}, len(ids))
+	for _, id := range ids {
+		seen[id] = struct{}{}
+	}
+	for i := range s.proxies {
+		proxy := s.proxies[i]
+		if _, ok := seen[proxy.ID]; ok {
+			out = append(out, proxy)
+		}
+	}
+	return out, nil
+}
+
+func (s *stubAdminService) CreateProxy(ctx context.Context, input *service.CreateProxyInput) (*service.Proxy, error) {
+	s.mu.Lock()
+	s.createdProxies = append(s.createdProxies, input)
+	s.mu.Unlock()
+	proxy := service.Proxy{ID: 400, Name: input.Name, Status: service.StatusActive}
+	return &proxy, nil
+}
+
+func (s *stubAdminService) UpdateProxy(ctx context.Context, id int64, input *service.UpdateProxyInput) (*service.Proxy, error) {
+	s.mu.Lock()
+	s.updatedProxyIDs = append(s.updatedProxyIDs, id)
+	s.updatedProxies = append(s.updatedProxies, input)
+	s.mu.Unlock()
+	proxy := service.Proxy{ID: id, Name: input.Name, Status: service.StatusActive}
+	return &proxy, nil
+}
+
+func (s *stubAdminService) DeleteProxy(ctx context.Context, id int64) error {
+	return nil
+}
+
+func (s *stubAdminService) BatchDeleteProxies(ctx context.Context, ids []int64) (*service.ProxyBatchDeleteResult, error) {
+	return &service.ProxyBatchDeleteResult{DeletedIDs: ids}, nil
+}
+
+func (s *stubAdminService) GetProxyAccounts(ctx context.Context, proxyID int64) ([]service.ProxyAccountSummary, error) {
+	return []service.ProxyAccountSummary{{ID: 1, Name: "account"}}, nil
+}
+
+func (s *stubAdminService) CheckProxyExists(ctx context.Context, host string, port int, username, password string) (bool, error) {
+	return false, nil
+}
+
+func (s *stubAdminService) TestProxy(ctx context.Context, id int64) (*service.ProxyTestResult, error) {
+	s.mu.Lock()
+	s.testedProxyIDs = append(s.testedProxyIDs, id)
+	s.mu.Unlock()
+	return &service.ProxyTestResult{Success: true, Message: "ok"}, nil
+}
+
+func (s *stubAdminService) CheckProxyQuality(ctx context.Context, id int64) (*service.ProxyQualityCheckResult, error) {
+	return &service.ProxyQualityCheckResult{
+		ProxyID:        id,
+		Score:          95,
+		Grade:          "A",
+		Summary:        "通过 5 项，告警 0 项，失败 0 项，挑战 0 项",
+		PassedCount:    5,
+		WarnCount:      0,
+		FailedCount:    0,
+		ChallengeCount: 0,
+		CheckedAt:      time.Now().Unix(),
+		Items: []service.ProxyQualityCheckItem{
+			{Target: "base_connectivity", Status: "pass", Message: "ok"},
+			{Target: "openai", Status: "pass", HTTPStatus: 401},
+			{Target: "anthropic", Status: "pass", HTTPStatus: 401},
+			{Target: "gemini", Status: "pass", HTTPStatus: 200},
+			{Target: "sora", Status: "pass", HTTPStatus: 401},
+		},
+	}, nil
+}
+
+func (s *stubAdminService) ListRedeemCodes(ctx context.Context, page, pageSize int, codeType, status, search string) ([]service.RedeemCode, int64, error) {
+	return s.redeems, int64(len(s.redeems)), nil
+}
+
+func (s *stubAdminService) GetRedeemCode(ctx context.Context, id int64) (*service.RedeemCode, error) {
+	code := service.RedeemCode{ID: id, Code: "R-TEST", Status: service.StatusUnused}
+	return &code, nil
+}
+
+func (s *stubAdminService) GenerateRedeemCodes(ctx context.Context, input *service.GenerateRedeemCodesInput) ([]service.RedeemCode, error) {
+	return s.redeems, nil
+}
+
+func (s *stubAdminService) DeleteRedeemCode(ctx context.Context, id int64) error {
+	return nil
+}
+
+func (s *stubAdminService) BatchDeleteRedeemCodes(ctx context.Context, ids []int64) (int64, error) {
+	return int64(len(ids)), nil
+}
+
+func (s *stubAdminService) ExpireRedeemCode(ctx context.Context, id int64) (*service.RedeemCode, error) {
+	code := service.RedeemCode{ID: id, Code: "R-TEST", Status: service.StatusUsed}
+	return &code, nil
+}
+
+func (s *stubAdminService) GetUserBalanceHistory(ctx context.Context, userID int64, page, pageSize int, codeType string) ([]service.RedeemCode, int64, float64, error) {
+	return s.redeems, int64(len(s.redeems)), 100.0, nil
+}
+
+func (s *stubAdminService) UpdateGroupSortOrders(ctx context.Context, updates []service.GroupSortOrderUpdate) error {
+	return nil
+}
+
+func (s *stubAdminService) AdminUpdateAPIKeyGroupID(ctx context.Context, keyID int64, groupID *int64) (*service.AdminUpdateAPIKeyGroupIDResult, error) {
+	for i := range s.apiKeys {
+		if s.apiKeys[i].ID == keyID {
+			k := s.apiKeys[i]
+			if groupID != nil {
+				if *groupID == 0 {
+					k.GroupID = nil
+				} else {
+					gid := *groupID
+					k.GroupID = &gid
+				}
+			}
+			return &service.AdminUpdateAPIKeyGroupIDResult{APIKey: &k}, nil
+		}
+	}
+	return nil, service.ErrAPIKeyNotFound
+}
+
+func (s *stubAdminService) ResetAccountQuota(ctx context.Context, id int64) error {
+	return nil
+}
+
+func (s *stubAdminService) EnsureOpenAIPrivacy(ctx context.Context, account *service.Account) string {
+	return ""
+}
+
+// Ensure stub implements interface.
+var _ service.AdminService = (*stubAdminService)(nil)

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/announcement_handler.go

@@ -0,0 +1,250 @@
+package admin
+
+import (
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// AnnouncementHandler handles admin announcement management
+type AnnouncementHandler struct {
+	announcementService *service.AnnouncementService
+}
+
+// NewAnnouncementHandler creates a new admin announcement handler
+func NewAnnouncementHandler(announcementService *service.AnnouncementService) *AnnouncementHandler {
+	return &AnnouncementHandler{
+		announcementService: announcementService,
+	}
+}
+
+type CreateAnnouncementRequest struct {
+	Title      string                        `json:"title" binding:"required"`
+	Content    string                        `json:"content" binding:"required"`
+	Status     string                        `json:"status" binding:"omitempty,oneof=draft active archived"`
+	NotifyMode string                        `json:"notify_mode" binding:"omitempty,oneof=silent popup"`
+	Targeting  service.AnnouncementTargeting `json:"targeting"`
+	StartsAt   *int64                        `json:"starts_at"` // Unix seconds, 0/empty = immediate
+	EndsAt     *int64                        `json:"ends_at"`   // Unix seconds, 0/empty = never
+}
+
+type UpdateAnnouncementRequest struct {
+	Title      *string                        `json:"title"`
+	Content    *string                        `json:"content"`
+	Status     *string                        `json:"status" binding:"omitempty,oneof=draft active archived"`
+	NotifyMode *string                        `json:"notify_mode" binding:"omitempty,oneof=silent popup"`
+	Targeting  *service.AnnouncementTargeting `json:"targeting"`
+	StartsAt   *int64                         `json:"starts_at"` // Unix seconds, 0 = clear
+	EndsAt     *int64                         `json:"ends_at"`   // Unix seconds, 0 = clear
+}
+
+// List handles listing announcements with filters
+// GET /api/v1/admin/announcements
+func (h *AnnouncementHandler) List(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+	status := strings.TrimSpace(c.Query("status"))
+	search := strings.TrimSpace(c.Query("search"))
+	if len(search) > 200 {
+		search = search[:200]
+	}
+
+	params := pagination.PaginationParams{
+		Page:     page,
+		PageSize: pageSize,
+	}
+
+	items, paginationResult, err := h.announcementService.List(
+		c.Request.Context(),
+		params,
+		service.AnnouncementListFilters{Status: status, Search: search},
+	)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.Announcement, 0, len(items))
+	for i := range items {
+		out = append(out, *dto.AnnouncementFromService(&items[i]))
+	}
+	response.Paginated(c, out, paginationResult.Total, page, pageSize)
+}
+
+// GetByID handles getting an announcement by ID
+// GET /api/v1/admin/announcements/:id
+func (h *AnnouncementHandler) GetByID(c *gin.Context) {
+	announcementID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || announcementID <= 0 {
+		response.BadRequest(c, "Invalid announcement ID")
+		return
+	}
+
+	item, err := h.announcementService.GetByID(c.Request.Context(), announcementID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.AnnouncementFromService(item))
+}
+
+// Create handles creating a new announcement
+// POST /api/v1/admin/announcements
+func (h *AnnouncementHandler) Create(c *gin.Context) {
+	var req CreateAnnouncementRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not found in context")
+		return
+	}
+
+	input := &service.CreateAnnouncementInput{
+		Title:      req.Title,
+		Content:    req.Content,
+		Status:     req.Status,
+		NotifyMode: req.NotifyMode,
+		Targeting:  req.Targeting,
+		ActorID:    &subject.UserID,
+	}
+
+	if req.StartsAt != nil && *req.StartsAt > 0 {
+		t := time.Unix(*req.StartsAt, 0)
+		input.StartsAt = &t
+	}
+	if req.EndsAt != nil && *req.EndsAt > 0 {
+		t := time.Unix(*req.EndsAt, 0)
+		input.EndsAt = &t
+	}
+
+	created, err := h.announcementService.Create(c.Request.Context(), input)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.AnnouncementFromService(created))
+}
+
+// Update handles updating an announcement
+// PUT /api/v1/admin/announcements/:id
+func (h *AnnouncementHandler) Update(c *gin.Context) {
+	announcementID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || announcementID <= 0 {
+		response.BadRequest(c, "Invalid announcement ID")
+		return
+	}
+
+	var req UpdateAnnouncementRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not found in context")
+		return
+	}
+
+	input := &service.UpdateAnnouncementInput{
+		Title:      req.Title,
+		Content:    req.Content,
+		Status:     req.Status,
+		NotifyMode: req.NotifyMode,
+		Targeting:  req.Targeting,
+		ActorID:    &subject.UserID,
+	}
+
+	if req.StartsAt != nil {
+		if *req.StartsAt == 0 {
+			var cleared *time.Time = nil
+			input.StartsAt = &cleared
+		} else {
+			t := time.Unix(*req.StartsAt, 0)
+			ptr := &t
+			input.StartsAt = &ptr
+		}
+	}
+
+	if req.EndsAt != nil {
+		if *req.EndsAt == 0 {
+			var cleared *time.Time = nil
+			input.EndsAt = &cleared
+		} else {
+			t := time.Unix(*req.EndsAt, 0)
+			ptr := &t
+			input.EndsAt = &ptr
+		}
+	}
+
+	updated, err := h.announcementService.Update(c.Request.Context(), announcementID, input)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.AnnouncementFromService(updated))
+}
+
+// Delete handles deleting an announcement
+// DELETE /api/v1/admin/announcements/:id
+func (h *AnnouncementHandler) Delete(c *gin.Context) {
+	announcementID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || announcementID <= 0 {
+		response.BadRequest(c, "Invalid announcement ID")
+		return
+	}
+
+	if err := h.announcementService.Delete(c.Request.Context(), announcementID); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Announcement deleted successfully"})
+}
+
+// ListReadStatus handles listing users read status for an announcement
+// GET /api/v1/admin/announcements/:id/read-status
+func (h *AnnouncementHandler) ListReadStatus(c *gin.Context) {
+	announcementID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || announcementID <= 0 {
+		response.BadRequest(c, "Invalid announcement ID")
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	params := pagination.PaginationParams{
+		Page:     page,
+		PageSize: pageSize,
+	}
+	search := strings.TrimSpace(c.Query("search"))
+	if len(search) > 200 {
+		search = search[:200]
+	}
+
+	items, paginationResult, err := h.announcementService.ListUserReadStatus(
+		c.Request.Context(),
+		announcementID,
+		params,
+		search,
+	)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Paginated(c, items, paginationResult.Total, page, pageSize)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/antigravity_oauth_handler.go

@@ -0,0 +1,91 @@
+package admin
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type AntigravityOAuthHandler struct {
+	antigravityOAuthService *service.AntigravityOAuthService
+}
+
+func NewAntigravityOAuthHandler(antigravityOAuthService *service.AntigravityOAuthService) *AntigravityOAuthHandler {
+	return &AntigravityOAuthHandler{antigravityOAuthService: antigravityOAuthService}
+}
+
+type AntigravityGenerateAuthURLRequest struct {
+	ProxyID *int64 `json:"proxy_id"`
+}
+
+// GenerateAuthURL generates Google OAuth authorization URL
+// POST /api/v1/admin/antigravity/oauth/auth-url
+func (h *AntigravityOAuthHandler) GenerateAuthURL(c *gin.Context) {
+	var req AntigravityGenerateAuthURLRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "请求无效: "+err.Error())
+		return
+	}
+
+	result, err := h.antigravityOAuthService.GenerateAuthURL(c.Request.Context(), req.ProxyID)
+	if err != nil {
+		response.InternalError(c, "生成授权链接失败: "+err.Error())
+		return
+	}
+
+	response.Success(c, result)
+}
+
+type AntigravityExchangeCodeRequest struct {
+	SessionID string `json:"session_id" binding:"required"`
+	State     string `json:"state" binding:"required"`
+	Code      string `json:"code" binding:"required"`
+	ProxyID   *int64 `json:"proxy_id"`
+}
+
+// ExchangeCode 用 authorization code 交换 token
+// POST /api/v1/admin/antigravity/oauth/exchange-code
+func (h *AntigravityOAuthHandler) ExchangeCode(c *gin.Context) {
+	var req AntigravityExchangeCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "请求无效: "+err.Error())
+		return
+	}
+
+	tokenInfo, err := h.antigravityOAuthService.ExchangeCode(c.Request.Context(), &service.AntigravityExchangeCodeInput{
+		SessionID: req.SessionID,
+		State:     req.State,
+		Code:      req.Code,
+		ProxyID:   req.ProxyID,
+	})
+	if err != nil {
+		response.BadRequest(c, "Token 交换失败: "+err.Error())
+		return
+	}
+
+	response.Success(c, tokenInfo)
+}
+
+// AntigravityRefreshTokenRequest represents the request for validating Antigravity refresh token
+type AntigravityRefreshTokenRequest struct {
+	RefreshToken string `json:"refresh_token" binding:"required"`
+	ProxyID      *int64 `json:"proxy_id"`
+}
+
+// RefreshToken validates an Antigravity refresh token and returns full token info
+// POST /api/v1/admin/antigravity/oauth/refresh-token
+func (h *AntigravityOAuthHandler) RefreshToken(c *gin.Context) {
+	var req AntigravityRefreshTokenRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "请求无效: "+err.Error())
+		return
+	}
+
+	tokenInfo, err := h.antigravityOAuthService.ValidateRefreshToken(c.Request.Context(), req.RefreshToken, req.ProxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, tokenInfo)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/apikey_handler.go

@@ -0,0 +1,63 @@
+package admin
+
+import (
+	"strconv"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// AdminAPIKeyHandler handles admin API key management
+type AdminAPIKeyHandler struct {
+	adminService service.AdminService
+}
+
+// NewAdminAPIKeyHandler creates a new admin API key handler
+func NewAdminAPIKeyHandler(adminService service.AdminService) *AdminAPIKeyHandler {
+	return &AdminAPIKeyHandler{
+		adminService: adminService,
+	}
+}
+
+// AdminUpdateAPIKeyGroupRequest represents the request to update an API key's group
+type AdminUpdateAPIKeyGroupRequest struct {
+	GroupID *int64 `json:"group_id"` // nil=不修改, 0=解绑, >0=绑定到目标分组
+}
+
+// UpdateGroup handles updating an API key's group binding
+// PUT /api/v1/admin/api-keys/:id
+func (h *AdminAPIKeyHandler) UpdateGroup(c *gin.Context) {
+	keyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid API key ID")
+		return
+	}
+
+	var req AdminUpdateAPIKeyGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	result, err := h.adminService.AdminUpdateAPIKeyGroupID(c.Request.Context(), keyID, req.GroupID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	resp := struct {
+		APIKey                 *dto.APIKey `json:"api_key"`
+		AutoGrantedGroupAccess bool        `json:"auto_granted_group_access"`
+		GrantedGroupID         *int64      `json:"granted_group_id,omitempty"`
+		GrantedGroupName       string      `json:"granted_group_name,omitempty"`
+	}{
+		APIKey:                 dto.APIKeyFromService(result.APIKey),
+		AutoGrantedGroupAccess: result.AutoGrantedGroupAccess,
+		GrantedGroupID:         result.GrantedGroupID,
+		GrantedGroupName:       result.GrantedGroupName,
+	}
+	response.Success(c, resp)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/apikey_handler_test.go

@@ -0,0 +1,202 @@
+package admin
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func setupAPIKeyHandler(adminSvc service.AdminService) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	h := NewAdminAPIKeyHandler(adminSvc)
+	router.PUT("/api/v1/admin/api-keys/:id", h.UpdateGroup)
+	return router
+}
+
+func TestAdminAPIKeyHandler_UpdateGroup_InvalidID(t *testing.T) {
+	router := setupAPIKeyHandler(newStubAdminService())
+	body := `{"group_id": 2}`
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/abc", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+	require.Contains(t, rec.Body.String(), "Invalid API key ID")
+}
+
+func TestAdminAPIKeyHandler_UpdateGroup_InvalidJSON(t *testing.T) {
+	router := setupAPIKeyHandler(newStubAdminService())
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/10", bytes.NewBufferString(`{bad json`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+	require.Contains(t, rec.Body.String(), "Invalid request")
+}
+
+func TestAdminAPIKeyHandler_UpdateGroup_KeyNotFound(t *testing.T) {
+	router := setupAPIKeyHandler(newStubAdminService())
+	body := `{"group_id": 2}`
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/999", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	// ErrAPIKeyNotFound maps to 404
+	require.Equal(t, http.StatusNotFound, rec.Code)
+}
+
+func TestAdminAPIKeyHandler_UpdateGroup_BindGroup(t *testing.T) {
+	router := setupAPIKeyHandler(newStubAdminService())
+	body := `{"group_id": 2}`
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/10", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp struct {
+		Code int             `json:"code"`
+		Data json.RawMessage `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+
+	var data struct {
+		APIKey struct {
+			ID      int64  `json:"id"`
+			GroupID *int64 `json:"group_id"`
+		} `json:"api_key"`
+		AutoGrantedGroupAccess bool `json:"auto_granted_group_access"`
+	}
+	require.NoError(t, json.Unmarshal(resp.Data, &data))
+	require.Equal(t, int64(10), data.APIKey.ID)
+	require.NotNil(t, data.APIKey.GroupID)
+	require.Equal(t, int64(2), *data.APIKey.GroupID)
+}
+
+func TestAdminAPIKeyHandler_UpdateGroup_Unbind(t *testing.T) {
+	svc := newStubAdminService()
+	gid := int64(2)
+	svc.apiKeys[0].GroupID = &gid
+	router := setupAPIKeyHandler(svc)
+	body := `{"group_id": 0}`
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/10", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp struct {
+		Data struct {
+			APIKey struct {
+				GroupID *int64 `json:"group_id"`
+			} `json:"api_key"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Nil(t, resp.Data.APIKey.GroupID)
+}
+
+func TestAdminAPIKeyHandler_UpdateGroup_ServiceError(t *testing.T) {
+	svc := &failingUpdateGroupService{
+		stubAdminService: newStubAdminService(),
+		err:              errors.New("internal failure"),
+	}
+	router := setupAPIKeyHandler(svc)
+	body := `{"group_id": 2}`
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/10", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusInternalServerError, rec.Code)
+}
+
+// H2: empty body → group_id is nil → no-op, returns original key
+func TestAdminAPIKeyHandler_UpdateGroup_EmptyBody_NoChange(t *testing.T) {
+	router := setupAPIKeyHandler(newStubAdminService())
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/10", bytes.NewBufferString(`{}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp struct {
+		Code int `json:"code"`
+		Data struct {
+			APIKey struct {
+				ID int64 `json:"id"`
+			} `json:"api_key"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+	require.Equal(t, int64(10), resp.Data.APIKey.ID)
+}
+
+// M2: service returns GROUP_NOT_ACTIVE → handler maps to 400
+func TestAdminAPIKeyHandler_UpdateGroup_GroupNotActive(t *testing.T) {
+	svc := &failingUpdateGroupService{
+		stubAdminService: newStubAdminService(),
+		err:              infraerrors.BadRequest("GROUP_NOT_ACTIVE", "target group is not active"),
+	}
+	router := setupAPIKeyHandler(svc)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/10", bytes.NewBufferString(`{"group_id": 5}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+	require.Contains(t, rec.Body.String(), "GROUP_NOT_ACTIVE")
+}
+
+// M2: service returns INVALID_GROUP_ID → handler maps to 400
+func TestAdminAPIKeyHandler_UpdateGroup_NegativeGroupID(t *testing.T) {
+	svc := &failingUpdateGroupService{
+		stubAdminService: newStubAdminService(),
+		err:              infraerrors.BadRequest("INVALID_GROUP_ID", "group_id must be non-negative"),
+	}
+	router := setupAPIKeyHandler(svc)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/api-keys/10", bytes.NewBufferString(`{"group_id": -5}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+	require.Contains(t, rec.Body.String(), "INVALID_GROUP_ID")
+}
+
+// failingUpdateGroupService overrides AdminUpdateAPIKeyGroupID to return an error.
+type failingUpdateGroupService struct {
+	*stubAdminService
+	err error
+}
+
+func (f *failingUpdateGroupService) AdminUpdateAPIKeyGroupID(_ context.Context, _ int64, _ *int64) (*service.AdminUpdateAPIKeyGroupIDResult, error) {
+	return nil, f.err
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/backup_handler.go

@@ -0,0 +1,204 @@
+package admin
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type BackupHandler struct {
+	backupService *service.BackupService
+	userService   *service.UserService
+}
+
+func NewBackupHandler(backupService *service.BackupService, userService *service.UserService) *BackupHandler {
+	return &BackupHandler{
+		backupService: backupService,
+		userService:   userService,
+	}
+}
+
+// ─── S3 配置 ───
+
+func (h *BackupHandler) GetS3Config(c *gin.Context) {
+	cfg, err := h.backupService.GetS3Config(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, cfg)
+}
+
+func (h *BackupHandler) UpdateS3Config(c *gin.Context) {
+	var req service.BackupS3Config
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	cfg, err := h.backupService.UpdateS3Config(c.Request.Context(), req)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, cfg)
+}
+
+func (h *BackupHandler) TestS3Connection(c *gin.Context) {
+	var req service.BackupS3Config
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	err := h.backupService.TestS3Connection(c.Request.Context(), req)
+	if err != nil {
+		response.Success(c, gin.H{"ok": false, "message": err.Error()})
+		return
+	}
+	response.Success(c, gin.H{"ok": true, "message": "connection successful"})
+}
+
+// ─── 定时备份 ───
+
+func (h *BackupHandler) GetSchedule(c *gin.Context) {
+	cfg, err := h.backupService.GetSchedule(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, cfg)
+}
+
+func (h *BackupHandler) UpdateSchedule(c *gin.Context) {
+	var req service.BackupScheduleConfig
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	cfg, err := h.backupService.UpdateSchedule(c.Request.Context(), req)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, cfg)
+}
+
+// ─── 备份操作 ───
+
+type CreateBackupRequest struct {
+	ExpireDays *int `json:"expire_days"` // nil=使用默认值14，0=永不过期
+}
+
+func (h *BackupHandler) CreateBackup(c *gin.Context) {
+	var req CreateBackupRequest
+	_ = c.ShouldBindJSON(&req) // 允许空 body
+
+	expireDays := 14 // 默认14天过期
+	if req.ExpireDays != nil {
+		expireDays = *req.ExpireDays
+	}
+
+	record, err := h.backupService.CreateBackup(c.Request.Context(), "manual", expireDays)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, record)
+}
+
+func (h *BackupHandler) ListBackups(c *gin.Context) {
+	records, err := h.backupService.ListBackups(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	if records == nil {
+		records = []service.BackupRecord{}
+	}
+	response.Success(c, gin.H{"items": records})
+}
+
+func (h *BackupHandler) GetBackup(c *gin.Context) {
+	backupID := c.Param("id")
+	if backupID == "" {
+		response.BadRequest(c, "backup ID is required")
+		return
+	}
+	record, err := h.backupService.GetBackupRecord(c.Request.Context(), backupID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, record)
+}
+
+func (h *BackupHandler) DeleteBackup(c *gin.Context) {
+	backupID := c.Param("id")
+	if backupID == "" {
+		response.BadRequest(c, "backup ID is required")
+		return
+	}
+	if err := h.backupService.DeleteBackup(c.Request.Context(), backupID); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"deleted": true})
+}
+
+func (h *BackupHandler) GetDownloadURL(c *gin.Context) {
+	backupID := c.Param("id")
+	if backupID == "" {
+		response.BadRequest(c, "backup ID is required")
+		return
+	}
+	url, err := h.backupService.GetBackupDownloadURL(c.Request.Context(), backupID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"url": url})
+}
+
+// ─── 恢复操作（需要重新输入管理员密码） ───
+
+type RestoreBackupRequest struct {
+	Password string `json:"password" binding:"required"`
+}
+
+func (h *BackupHandler) RestoreBackup(c *gin.Context) {
+	backupID := c.Param("id")
+	if backupID == "" {
+		response.BadRequest(c, "backup ID is required")
+		return
+	}
+
+	var req RestoreBackupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "password is required for restore operation")
+		return
+	}
+
+	// 从上下文获取当前管理员用户 ID
+	sub, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "unauthorized")
+		return
+	}
+
+	// 获取管理员用户并验证密码
+	user, err := h.userService.GetByID(c.Request.Context(), sub.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	if !user.CheckPassword(req.Password) {
+		response.BadRequest(c, "incorrect admin password")
+		return
+	}
+
+	if err := h.backupService.RestoreBackup(c.Request.Context(), backupID); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"restored": true})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/batch_update_credentials_test.go

@@ -0,0 +1,208 @@
+//go:build unit
+
+package admin
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+// failingAdminService 嵌入 stubAdminService，可配置 UpdateAccount 在指定 ID 时失败。
+type failingAdminService struct {
+	*stubAdminService
+	failOnAccountID int64
+	updateCallCount atomic.Int64
+}
+
+func (f *failingAdminService) UpdateAccount(ctx context.Context, id int64, input *service.UpdateAccountInput) (*service.Account, error) {
+	f.updateCallCount.Add(1)
+	if id == f.failOnAccountID {
+		return nil, errors.New("database error")
+	}
+	return f.stubAdminService.UpdateAccount(ctx, id, input)
+}
+
+func setupAccountHandlerWithService(adminSvc service.AdminService) (*gin.Engine, *AccountHandler) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	handler := NewAccountHandler(adminSvc, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	router.POST("/api/v1/admin/accounts/batch-update-credentials", handler.BatchUpdateCredentials)
+	return router, handler
+}
+
+func TestBatchUpdateCredentials_AllSuccess(t *testing.T) {
+	svc := &failingAdminService{stubAdminService: newStubAdminService()}
+	router, _ := setupAccountHandlerWithService(svc)
+
+	body, _ := json.Marshal(BatchUpdateCredentialsRequest{
+		AccountIDs: []int64{1, 2, 3},
+		Field:      "account_uuid",
+		Value:      "test-uuid",
+	})
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/v1/admin/accounts/batch-update-credentials", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code, "全部成功时应返回 200")
+	require.Equal(t, int64(3), svc.updateCallCount.Load(), "应调用 3 次 UpdateAccount")
+}
+
+func TestBatchUpdateCredentials_PartialFailure(t *testing.T) {
+	// 让第 2 个账号（ID=2）更新时失败
+	svc := &failingAdminService{
+		stubAdminService: newStubAdminService(),
+		failOnAccountID:  2,
+	}
+	router, _ := setupAccountHandlerWithService(svc)
+
+	body, _ := json.Marshal(BatchUpdateCredentialsRequest{
+		AccountIDs: []int64{1, 2, 3},
+		Field:      "org_uuid",
+		Value:      "test-org",
+	})
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/v1/admin/accounts/batch-update-credentials", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	// 实现采用"部分成功"模式：总是返回 200 + 成功/失败明细
+	require.Equal(t, http.StatusOK, w.Code, "批量更新返回 200 + 成功/失败明细")
+
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
+	data := resp["data"].(map[string]any)
+	require.Equal(t, float64(2), data["success"], "应有 2 个成功")
+	require.Equal(t, float64(1), data["failed"], "应有 1 个失败")
+
+	// 所有 3 个账号都会被尝试更新（非 fail-fast）
+	require.Equal(t, int64(3), svc.updateCallCount.Load(),
+		"应调用 3 次 UpdateAccount（逐个尝试，失败后继续）")
+}
+
+func TestBatchUpdateCredentials_FirstAccountNotFound(t *testing.T) {
+	// GetAccount 在 stubAdminService 中总是成功的，需要创建一个 GetAccount 会失败的 stub
+	svc := &getAccountFailingService{
+		stubAdminService: newStubAdminService(),
+		failOnAccountID:  1,
+	}
+	router, _ := setupAccountHandlerWithService(svc)
+
+	body, _ := json.Marshal(BatchUpdateCredentialsRequest{
+		AccountIDs: []int64{1, 2, 3},
+		Field:      "account_uuid",
+		Value:      "test",
+	})
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/v1/admin/accounts/batch-update-credentials", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusNotFound, w.Code, "第一阶段验证失败应返回 404")
+}
+
+// getAccountFailingService 模拟 GetAccount 在特定 ID 时返回 not found。
+type getAccountFailingService struct {
+	*stubAdminService
+	failOnAccountID int64
+}
+
+func (f *getAccountFailingService) GetAccount(ctx context.Context, id int64) (*service.Account, error) {
+	if id == f.failOnAccountID {
+		return nil, errors.New("not found")
+	}
+	return f.stubAdminService.GetAccount(ctx, id)
+}
+
+func TestBatchUpdateCredentials_InterceptWarmupRequests_NonBool(t *testing.T) {
+	svc := &failingAdminService{stubAdminService: newStubAdminService()}
+	router, _ := setupAccountHandlerWithService(svc)
+
+	// intercept_warmup_requests 传入非 bool 类型（string），应返回 400
+	body, _ := json.Marshal(map[string]any{
+		"account_ids": []int64{1},
+		"field":       "intercept_warmup_requests",
+		"value":       "not-a-bool",
+	})
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/v1/admin/accounts/batch-update-credentials", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusBadRequest, w.Code,
+		"intercept_warmup_requests 传入非 bool 值应返回 400")
+}
+
+func TestBatchUpdateCredentials_InterceptWarmupRequests_ValidBool(t *testing.T) {
+	svc := &failingAdminService{stubAdminService: newStubAdminService()}
+	router, _ := setupAccountHandlerWithService(svc)
+
+	body, _ := json.Marshal(map[string]any{
+		"account_ids": []int64{1},
+		"field":       "intercept_warmup_requests",
+		"value":       true,
+	})
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/v1/admin/accounts/batch-update-credentials", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code,
+		"intercept_warmup_requests 传入合法 bool 值应返回 200")
+}
+
+func TestBatchUpdateCredentials_AccountUUID_NonString(t *testing.T) {
+	svc := &failingAdminService{stubAdminService: newStubAdminService()}
+	router, _ := setupAccountHandlerWithService(svc)
+
+	// account_uuid 传入非 string 类型（number），应返回 400
+	body, _ := json.Marshal(map[string]any{
+		"account_ids": []int64{1},
+		"field":       "account_uuid",
+		"value":       12345,
+	})
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/v1/admin/accounts/batch-update-credentials", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusBadRequest, w.Code,
+		"account_uuid 传入非 string 值应返回 400")
+}
+
+func TestBatchUpdateCredentials_AccountUUID_NullValue(t *testing.T) {
+	svc := &failingAdminService{stubAdminService: newStubAdminService()}
+	router, _ := setupAccountHandlerWithService(svc)
+
+	// account_uuid 传入 null（设置为空），应正常通过
+	body, _ := json.Marshal(map[string]any{
+		"account_ids": []int64{1},
+		"field":       "account_uuid",
+		"value":       nil,
+	})
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/v1/admin/accounts/batch-update-credentials", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code,
+		"account_uuid 传入 null 应返回 200")
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/dashboard_handler.go

@@ -0,0 +1,606 @@
+package admin
+
+import (
+	"encoding/json"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// DashboardHandler handles admin dashboard statistics
+type DashboardHandler struct {
+	dashboardService   *service.DashboardService
+	aggregationService *service.DashboardAggregationService
+	startTime          time.Time // Server start time for uptime calculation
+}
+
+// NewDashboardHandler creates a new admin dashboard handler
+func NewDashboardHandler(dashboardService *service.DashboardService, aggregationService *service.DashboardAggregationService) *DashboardHandler {
+	return &DashboardHandler{
+		dashboardService:   dashboardService,
+		aggregationService: aggregationService,
+		startTime:          time.Now(),
+	}
+}
+
+// parseTimeRange parses start_date, end_date query parameters
+// Uses user's timezone if provided, otherwise falls back to server timezone
+func parseTimeRange(c *gin.Context) (time.Time, time.Time) {
+	userTZ := c.Query("timezone") // Get user's timezone from request
+	now := timezone.NowInUserLocation(userTZ)
+	startDate := c.Query("start_date")
+	endDate := c.Query("end_date")
+
+	var startTime, endTime time.Time
+
+	if startDate != "" {
+		if t, err := timezone.ParseInUserLocation("2006-01-02", startDate, userTZ); err == nil {
+			startTime = t
+		} else {
+			startTime = timezone.StartOfDayInUserLocation(now.AddDate(0, 0, -7), userTZ)
+		}
+	} else {
+		startTime = timezone.StartOfDayInUserLocation(now.AddDate(0, 0, -7), userTZ)
+	}
+
+	if endDate != "" {
+		if t, err := timezone.ParseInUserLocation("2006-01-02", endDate, userTZ); err == nil {
+			endTime = t.Add(24 * time.Hour) // Include the end date
+		} else {
+			endTime = timezone.StartOfDayInUserLocation(now.AddDate(0, 0, 1), userTZ)
+		}
+	} else {
+		endTime = timezone.StartOfDayInUserLocation(now.AddDate(0, 0, 1), userTZ)
+	}
+
+	return startTime, endTime
+}
+
+// GetStats handles getting dashboard statistics
+// GET /api/v1/admin/dashboard/stats
+func (h *DashboardHandler) GetStats(c *gin.Context) {
+	stats, err := h.dashboardService.GetDashboardStats(c.Request.Context())
+	if err != nil {
+		response.Error(c, 500, "Failed to get dashboard statistics")
+		return
+	}
+
+	// Calculate uptime in seconds
+	uptime := int64(time.Since(h.startTime).Seconds())
+
+	response.Success(c, gin.H{
+		// 用户统计
+		"total_users":     stats.TotalUsers,
+		"today_new_users": stats.TodayNewUsers,
+		"active_users":    stats.ActiveUsers,
+
+		// API Key 统计
+		"total_api_keys":  stats.TotalAPIKeys,
+		"active_api_keys": stats.ActiveAPIKeys,
+
+		// 账户统计
+		"total_accounts":     stats.TotalAccounts,
+		"normal_accounts":    stats.NormalAccounts,
+		"error_accounts":     stats.ErrorAccounts,
+		"ratelimit_accounts": stats.RateLimitAccounts,
+		"overload_accounts":  stats.OverloadAccounts,
+
+		// 累计 Token 使用统计
+		"total_requests":              stats.TotalRequests,
+		"total_input_tokens":          stats.TotalInputTokens,
+		"total_output_tokens":         stats.TotalOutputTokens,
+		"total_cache_creation_tokens": stats.TotalCacheCreationTokens,
+		"total_cache_read_tokens":     stats.TotalCacheReadTokens,
+		"total_tokens":                stats.TotalTokens,
+		"total_cost":                  stats.TotalCost,       // 标准计费
+		"total_actual_cost":           stats.TotalActualCost, // 实际扣除
+
+		// 今日 Token 使用统计
+		"today_requests":              stats.TodayRequests,
+		"today_input_tokens":          stats.TodayInputTokens,
+		"today_output_tokens":         stats.TodayOutputTokens,
+		"today_cache_creation_tokens": stats.TodayCacheCreationTokens,
+		"today_cache_read_tokens":     stats.TodayCacheReadTokens,
+		"today_tokens":                stats.TodayTokens,
+		"today_cost":                  stats.TodayCost,       // 今日标准计费
+		"today_actual_cost":           stats.TodayActualCost, // 今日实际扣除
+
+		// 系统运行统计
+		"average_duration_ms": stats.AverageDurationMs,
+		"uptime":              uptime,
+
+		// 性能指标
+		"rpm": stats.Rpm,
+		"tpm": stats.Tpm,
+
+		// 预聚合新鲜度
+		"hourly_active_users": stats.HourlyActiveUsers,
+		"stats_updated_at":    stats.StatsUpdatedAt,
+		"stats_stale":         stats.StatsStale,
+	})
+}
+
+type DashboardAggregationBackfillRequest struct {
+	Start string `json:"start"`
+	End   string `json:"end"`
+}
+
+// BackfillAggregation handles triggering aggregation backfill
+// POST /api/v1/admin/dashboard/aggregation/backfill
+func (h *DashboardHandler) BackfillAggregation(c *gin.Context) {
+	if h.aggregationService == nil {
+		response.InternalError(c, "Aggregation service not available")
+		return
+	}
+
+	var req DashboardAggregationBackfillRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+	start, err := time.Parse(time.RFC3339, req.Start)
+	if err != nil {
+		response.BadRequest(c, "Invalid start time")
+		return
+	}
+	end, err := time.Parse(time.RFC3339, req.End)
+	if err != nil {
+		response.BadRequest(c, "Invalid end time")
+		return
+	}
+
+	if err := h.aggregationService.TriggerBackfill(start, end); err != nil {
+		if errors.Is(err, service.ErrDashboardBackfillDisabled) {
+			response.Forbidden(c, "Backfill is disabled")
+			return
+		}
+		if errors.Is(err, service.ErrDashboardBackfillTooLarge) {
+			response.BadRequest(c, "Backfill range too large")
+			return
+		}
+		response.InternalError(c, "Failed to trigger backfill")
+		return
+	}
+
+	response.Success(c, gin.H{
+		"status": "accepted",
+	})
+}
+
+// GetRealtimeMetrics handles getting real-time system metrics
+// GET /api/v1/admin/dashboard/realtime
+func (h *DashboardHandler) GetRealtimeMetrics(c *gin.Context) {
+	// Return mock data for now
+	response.Success(c, gin.H{
+		"active_requests":       0,
+		"requests_per_minute":   0,
+		"average_response_time": 0,
+		"error_rate":            0.0,
+	})
+}
+
+// GetUsageTrend handles getting usage trend data
+// GET /api/v1/admin/dashboard/trend
+// Query params: start_date, end_date (YYYY-MM-DD), granularity (day/hour), user_id, api_key_id, model, account_id, group_id, request_type, stream, billing_type
+func (h *DashboardHandler) GetUsageTrend(c *gin.Context) {
+	startTime, endTime := parseTimeRange(c)
+	granularity := c.DefaultQuery("granularity", "day")
+
+	// Parse optional filter params
+	var userID, apiKeyID, accountID, groupID int64
+	var model string
+	var requestType *int16
+	var stream *bool
+	var billingType *int8
+
+	if userIDStr := c.Query("user_id"); userIDStr != "" {
+		if id, err := strconv.ParseInt(userIDStr, 10, 64); err == nil {
+			userID = id
+		}
+	}
+	if apiKeyIDStr := c.Query("api_key_id"); apiKeyIDStr != "" {
+		if id, err := strconv.ParseInt(apiKeyIDStr, 10, 64); err == nil {
+			apiKeyID = id
+		}
+	}
+	if accountIDStr := c.Query("account_id"); accountIDStr != "" {
+		if id, err := strconv.ParseInt(accountIDStr, 10, 64); err == nil {
+			accountID = id
+		}
+	}
+	if groupIDStr := c.Query("group_id"); groupIDStr != "" {
+		if id, err := strconv.ParseInt(groupIDStr, 10, 64); err == nil {
+			groupID = id
+		}
+	}
+	if modelStr := c.Query("model"); modelStr != "" {
+		model = modelStr
+	}
+	if requestTypeStr := strings.TrimSpace(c.Query("request_type")); requestTypeStr != "" {
+		parsed, err := service.ParseUsageRequestType(requestTypeStr)
+		if err != nil {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		value := int16(parsed)
+		requestType = &value
+	} else if streamStr := c.Query("stream"); streamStr != "" {
+		if streamVal, err := strconv.ParseBool(streamStr); err == nil {
+			stream = &streamVal
+		} else {
+			response.BadRequest(c, "Invalid stream value, use true or false")
+			return
+		}
+	}
+	if billingTypeStr := c.Query("billing_type"); billingTypeStr != "" {
+		if v, err := strconv.ParseInt(billingTypeStr, 10, 8); err == nil {
+			bt := int8(v)
+			billingType = &bt
+		} else {
+			response.BadRequest(c, "Invalid billing_type")
+			return
+		}
+	}
+
+	trend, hit, err := h.getUsageTrendCached(c.Request.Context(), startTime, endTime, granularity, userID, apiKeyID, accountID, groupID, model, requestType, stream, billingType)
+	if err != nil {
+		response.Error(c, 500, "Failed to get usage trend")
+		return
+	}
+	c.Header("X-Snapshot-Cache", cacheStatusValue(hit))
+
+	response.Success(c, gin.H{
+		"trend":       trend,
+		"start_date":  startTime.Format("2006-01-02"),
+		"end_date":    endTime.Add(-24 * time.Hour).Format("2006-01-02"),
+		"granularity": granularity,
+	})
+}
+
+// GetModelStats handles getting model usage statistics
+// GET /api/v1/admin/dashboard/models
+// Query params: start_date, end_date (YYYY-MM-DD), user_id, api_key_id, account_id, group_id, request_type, stream, billing_type
+func (h *DashboardHandler) GetModelStats(c *gin.Context) {
+	startTime, endTime := parseTimeRange(c)
+
+	// Parse optional filter params
+	var userID, apiKeyID, accountID, groupID int64
+	var requestType *int16
+	var stream *bool
+	var billingType *int8
+
+	if userIDStr := c.Query("user_id"); userIDStr != "" {
+		if id, err := strconv.ParseInt(userIDStr, 10, 64); err == nil {
+			userID = id
+		}
+	}
+	if apiKeyIDStr := c.Query("api_key_id"); apiKeyIDStr != "" {
+		if id, err := strconv.ParseInt(apiKeyIDStr, 10, 64); err == nil {
+			apiKeyID = id
+		}
+	}
+	if accountIDStr := c.Query("account_id"); accountIDStr != "" {
+		if id, err := strconv.ParseInt(accountIDStr, 10, 64); err == nil {
+			accountID = id
+		}
+	}
+	if groupIDStr := c.Query("group_id"); groupIDStr != "" {
+		if id, err := strconv.ParseInt(groupIDStr, 10, 64); err == nil {
+			groupID = id
+		}
+	}
+	if requestTypeStr := strings.TrimSpace(c.Query("request_type")); requestTypeStr != "" {
+		parsed, err := service.ParseUsageRequestType(requestTypeStr)
+		if err != nil {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		value := int16(parsed)
+		requestType = &value
+	} else if streamStr := c.Query("stream"); streamStr != "" {
+		if streamVal, err := strconv.ParseBool(streamStr); err == nil {
+			stream = &streamVal
+		} else {
+			response.BadRequest(c, "Invalid stream value, use true or false")
+			return
+		}
+	}
+	if billingTypeStr := c.Query("billing_type"); billingTypeStr != "" {
+		if v, err := strconv.ParseInt(billingTypeStr, 10, 8); err == nil {
+			bt := int8(v)
+			billingType = &bt
+		} else {
+			response.BadRequest(c, "Invalid billing_type")
+			return
+		}
+	}
+
+	stats, hit, err := h.getModelStatsCached(c.Request.Context(), startTime, endTime, userID, apiKeyID, accountID, groupID, requestType, stream, billingType)
+	if err != nil {
+		response.Error(c, 500, "Failed to get model statistics")
+		return
+	}
+	c.Header("X-Snapshot-Cache", cacheStatusValue(hit))
+
+	response.Success(c, gin.H{
+		"models":     stats,
+		"start_date": startTime.Format("2006-01-02"),
+		"end_date":   endTime.Add(-24 * time.Hour).Format("2006-01-02"),
+	})
+}
+
+// GetGroupStats handles getting group usage statistics
+// GET /api/v1/admin/dashboard/groups
+// Query params: start_date, end_date (YYYY-MM-DD), user_id, api_key_id, account_id, group_id, request_type, stream, billing_type
+func (h *DashboardHandler) GetGroupStats(c *gin.Context) {
+	startTime, endTime := parseTimeRange(c)
+
+	var userID, apiKeyID, accountID, groupID int64
+	var requestType *int16
+	var stream *bool
+	var billingType *int8
+
+	if userIDStr := c.Query("user_id"); userIDStr != "" {
+		if id, err := strconv.ParseInt(userIDStr, 10, 64); err == nil {
+			userID = id
+		}
+	}
+	if apiKeyIDStr := c.Query("api_key_id"); apiKeyIDStr != "" {
+		if id, err := strconv.ParseInt(apiKeyIDStr, 10, 64); err == nil {
+			apiKeyID = id
+		}
+	}
+	if accountIDStr := c.Query("account_id"); accountIDStr != "" {
+		if id, err := strconv.ParseInt(accountIDStr, 10, 64); err == nil {
+			accountID = id
+		}
+	}
+	if groupIDStr := c.Query("group_id"); groupIDStr != "" {
+		if id, err := strconv.ParseInt(groupIDStr, 10, 64); err == nil {
+			groupID = id
+		}
+	}
+	if requestTypeStr := strings.TrimSpace(c.Query("request_type")); requestTypeStr != "" {
+		parsed, err := service.ParseUsageRequestType(requestTypeStr)
+		if err != nil {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		value := int16(parsed)
+		requestType = &value
+	} else if streamStr := c.Query("stream"); streamStr != "" {
+		if streamVal, err := strconv.ParseBool(streamStr); err == nil {
+			stream = &streamVal
+		} else {
+			response.BadRequest(c, "Invalid stream value, use true or false")
+			return
+		}
+	}
+	if billingTypeStr := c.Query("billing_type"); billingTypeStr != "" {
+		if v, err := strconv.ParseInt(billingTypeStr, 10, 8); err == nil {
+			bt := int8(v)
+			billingType = &bt
+		} else {
+			response.BadRequest(c, "Invalid billing_type")
+			return
+		}
+	}
+
+	stats, hit, err := h.getGroupStatsCached(c.Request.Context(), startTime, endTime, userID, apiKeyID, accountID, groupID, requestType, stream, billingType)
+	if err != nil {
+		response.Error(c, 500, "Failed to get group statistics")
+		return
+	}
+	c.Header("X-Snapshot-Cache", cacheStatusValue(hit))
+
+	response.Success(c, gin.H{
+		"groups":     stats,
+		"start_date": startTime.Format("2006-01-02"),
+		"end_date":   endTime.Add(-24 * time.Hour).Format("2006-01-02"),
+	})
+}
+
+// GetAPIKeyUsageTrend handles getting API key usage trend data
+// GET /api/v1/admin/dashboard/api-keys-trend
+// Query params: start_date, end_date (YYYY-MM-DD), granularity (day/hour), limit (default 5)
+func (h *DashboardHandler) GetAPIKeyUsageTrend(c *gin.Context) {
+	startTime, endTime := parseTimeRange(c)
+	granularity := c.DefaultQuery("granularity", "day")
+	limitStr := c.DefaultQuery("limit", "5")
+	limit, err := strconv.Atoi(limitStr)
+	if err != nil || limit <= 0 {
+		limit = 5
+	}
+
+	trend, hit, err := h.getAPIKeyUsageTrendCached(c.Request.Context(), startTime, endTime, granularity, limit)
+	if err != nil {
+		response.Error(c, 500, "Failed to get API key usage trend")
+		return
+	}
+	c.Header("X-Snapshot-Cache", cacheStatusValue(hit))
+
+	response.Success(c, gin.H{
+		"trend":       trend,
+		"start_date":  startTime.Format("2006-01-02"),
+		"end_date":    endTime.Add(-24 * time.Hour).Format("2006-01-02"),
+		"granularity": granularity,
+	})
+}
+
+// GetUserUsageTrend handles getting user usage trend data
+// GET /api/v1/admin/dashboard/users-trend
+// Query params: start_date, end_date (YYYY-MM-DD), granularity (day/hour), limit (default 12)
+func (h *DashboardHandler) GetUserUsageTrend(c *gin.Context) {
+	startTime, endTime := parseTimeRange(c)
+	granularity := c.DefaultQuery("granularity", "day")
+	limitStr := c.DefaultQuery("limit", "12")
+	limit, err := strconv.Atoi(limitStr)
+	if err != nil || limit <= 0 {
+		limit = 12
+	}
+
+	trend, hit, err := h.getUserUsageTrendCached(c.Request.Context(), startTime, endTime, granularity, limit)
+	if err != nil {
+		response.Error(c, 500, "Failed to get user usage trend")
+		return
+	}
+	c.Header("X-Snapshot-Cache", cacheStatusValue(hit))
+
+	response.Success(c, gin.H{
+		"trend":       trend,
+		"start_date":  startTime.Format("2006-01-02"),
+		"end_date":    endTime.Add(-24 * time.Hour).Format("2006-01-02"),
+		"granularity": granularity,
+	})
+}
+
+// BatchUsersUsageRequest represents the request body for batch user usage stats
+type BatchUsersUsageRequest struct {
+	UserIDs []int64 `json:"user_ids" binding:"required"`
+}
+
+var dashboardUsersRankingCache = newSnapshotCache(5 * time.Minute)
+var dashboardBatchUsersUsageCache = newSnapshotCache(30 * time.Second)
+var dashboardBatchAPIKeysUsageCache = newSnapshotCache(30 * time.Second)
+
+func parseRankingLimit(raw string) int {
+	limit, err := strconv.Atoi(strings.TrimSpace(raw))
+	if err != nil || limit <= 0 {
+		return 12
+	}
+	if limit > 50 {
+		return 50
+	}
+	return limit
+}
+
+// GetUserSpendingRanking handles getting user spending ranking data.
+// GET /api/v1/admin/dashboard/users-ranking
+func (h *DashboardHandler) GetUserSpendingRanking(c *gin.Context) {
+	startTime, endTime := parseTimeRange(c)
+	limit := parseRankingLimit(c.DefaultQuery("limit", "12"))
+
+	keyRaw, _ := json.Marshal(struct {
+		Start string `json:"start"`
+		End   string `json:"end"`
+		Limit int    `json:"limit"`
+	}{
+		Start: startTime.UTC().Format(time.RFC3339),
+		End:   endTime.UTC().Format(time.RFC3339),
+		Limit: limit,
+	})
+	cacheKey := string(keyRaw)
+	if cached, ok := dashboardUsersRankingCache.Get(cacheKey); ok {
+		c.Header("X-Snapshot-Cache", "hit")
+		response.Success(c, cached.Payload)
+		return
+	}
+
+	ranking, err := h.dashboardService.GetUserSpendingRanking(c.Request.Context(), startTime, endTime, limit)
+	if err != nil {
+		response.Error(c, 500, "Failed to get user spending ranking")
+		return
+	}
+
+	payload := gin.H{
+		"ranking":           ranking.Ranking,
+		"total_actual_cost": ranking.TotalActualCost,
+		"total_requests":    ranking.TotalRequests,
+		"total_tokens":      ranking.TotalTokens,
+		"start_date":        startTime.Format("2006-01-02"),
+		"end_date":          endTime.Add(-24 * time.Hour).Format("2006-01-02"),
+	}
+	dashboardUsersRankingCache.Set(cacheKey, payload)
+	c.Header("X-Snapshot-Cache", "miss")
+	response.Success(c, payload)
+}
+
+// GetBatchUsersUsage handles getting usage stats for multiple users
+// POST /api/v1/admin/dashboard/users-usage
+func (h *DashboardHandler) GetBatchUsersUsage(c *gin.Context) {
+	var req BatchUsersUsageRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	userIDs := normalizeInt64IDList(req.UserIDs)
+	if len(userIDs) == 0 {
+		response.Success(c, gin.H{"stats": map[string]any{}})
+		return
+	}
+
+	keyRaw, _ := json.Marshal(struct {
+		UserIDs []int64 `json:"user_ids"`
+	}{
+		UserIDs: userIDs,
+	})
+	cacheKey := string(keyRaw)
+	if cached, ok := dashboardBatchUsersUsageCache.Get(cacheKey); ok {
+		c.Header("X-Snapshot-Cache", "hit")
+		response.Success(c, cached.Payload)
+		return
+	}
+
+	stats, err := h.dashboardService.GetBatchUserUsageStats(c.Request.Context(), userIDs, time.Time{}, time.Time{})
+	if err != nil {
+		response.Error(c, 500, "Failed to get user usage stats")
+		return
+	}
+
+	payload := gin.H{"stats": stats}
+	dashboardBatchUsersUsageCache.Set(cacheKey, payload)
+	c.Header("X-Snapshot-Cache", "miss")
+	response.Success(c, payload)
+}
+
+// BatchAPIKeysUsageRequest represents the request body for batch api key usage stats
+type BatchAPIKeysUsageRequest struct {
+	APIKeyIDs []int64 `json:"api_key_ids" binding:"required"`
+}
+
+// GetBatchAPIKeysUsage handles getting usage stats for multiple API keys
+// POST /api/v1/admin/dashboard/api-keys-usage
+func (h *DashboardHandler) GetBatchAPIKeysUsage(c *gin.Context) {
+	var req BatchAPIKeysUsageRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	apiKeyIDs := normalizeInt64IDList(req.APIKeyIDs)
+	if len(apiKeyIDs) == 0 {
+		response.Success(c, gin.H{"stats": map[string]any{}})
+		return
+	}
+
+	keyRaw, _ := json.Marshal(struct {
+		APIKeyIDs []int64 `json:"api_key_ids"`
+	}{
+		APIKeyIDs: apiKeyIDs,
+	})
+	cacheKey := string(keyRaw)
+	if cached, ok := dashboardBatchAPIKeysUsageCache.Get(cacheKey); ok {
+		c.Header("X-Snapshot-Cache", "hit")
+		response.Success(c, cached.Payload)
+		return
+	}
+
+	stats, err := h.dashboardService.GetBatchAPIKeyUsageStats(c.Request.Context(), apiKeyIDs, time.Time{}, time.Time{})
+	if err != nil {
+		response.Error(c, 500, "Failed to get API key usage stats")
+		return
+	}
+
+	payload := gin.H{"stats": stats}
+	dashboardBatchAPIKeysUsageCache.Set(cacheKey, payload)
+	c.Header("X-Snapshot-Cache", "miss")
+	response.Success(c, payload)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/dashboard_handler_cache_test.go

@@ -0,0 +1,118 @@
+package admin
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type dashboardUsageRepoCacheProbe struct {
+	service.UsageLogRepository
+	trendCalls      atomic.Int32
+	usersTrendCalls atomic.Int32
+}
+
+func (r *dashboardUsageRepoCacheProbe) GetUsageTrendWithFilters(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	granularity string,
+	userID, apiKeyID, accountID, groupID int64,
+	model string,
+	requestType *int16,
+	stream *bool,
+	billingType *int8,
+) ([]usagestats.TrendDataPoint, error) {
+	r.trendCalls.Add(1)
+	return []usagestats.TrendDataPoint{{
+		Date:        "2026-03-11",
+		Requests:    1,
+		TotalTokens: 2,
+		Cost:        3,
+		ActualCost:  4,
+	}}, nil
+}
+
+func (r *dashboardUsageRepoCacheProbe) GetUserUsageTrend(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	granularity string,
+	limit int,
+) ([]usagestats.UserUsageTrendPoint, error) {
+	r.usersTrendCalls.Add(1)
+	return []usagestats.UserUsageTrendPoint{{
+		Date:       "2026-03-11",
+		UserID:     1,
+		Email:      "cache@test.dev",
+		Requests:   2,
+		Tokens:     20,
+		Cost:       2,
+		ActualCost: 1,
+	}}, nil
+}
+
+func resetDashboardReadCachesForTest() {
+	dashboardTrendCache = newSnapshotCache(30 * time.Second)
+	dashboardUsersTrendCache = newSnapshotCache(30 * time.Second)
+	dashboardAPIKeysTrendCache = newSnapshotCache(30 * time.Second)
+	dashboardModelStatsCache = newSnapshotCache(30 * time.Second)
+	dashboardGroupStatsCache = newSnapshotCache(30 * time.Second)
+	dashboardSnapshotV2Cache = newSnapshotCache(30 * time.Second)
+}
+
+func TestDashboardHandler_GetUsageTrend_UsesCache(t *testing.T) {
+	t.Cleanup(resetDashboardReadCachesForTest)
+	resetDashboardReadCachesForTest()
+
+	gin.SetMode(gin.TestMode)
+	repo := &dashboardUsageRepoCacheProbe{}
+	dashboardSvc := service.NewDashboardService(repo, nil, nil, nil)
+	handler := NewDashboardHandler(dashboardSvc, nil)
+	router := gin.New()
+	router.GET("/admin/dashboard/trend", handler.GetUsageTrend)
+
+	req1 := httptest.NewRequest(http.MethodGet, "/admin/dashboard/trend?start_date=2026-03-01&end_date=2026-03-07&granularity=day", nil)
+	rec1 := httptest.NewRecorder()
+	router.ServeHTTP(rec1, req1)
+	require.Equal(t, http.StatusOK, rec1.Code)
+	require.Equal(t, "miss", rec1.Header().Get("X-Snapshot-Cache"))
+
+	req2 := httptest.NewRequest(http.MethodGet, "/admin/dashboard/trend?start_date=2026-03-01&end_date=2026-03-07&granularity=day", nil)
+	rec2 := httptest.NewRecorder()
+	router.ServeHTTP(rec2, req2)
+	require.Equal(t, http.StatusOK, rec2.Code)
+	require.Equal(t, "hit", rec2.Header().Get("X-Snapshot-Cache"))
+	require.Equal(t, int32(1), repo.trendCalls.Load())
+}
+
+func TestDashboardHandler_GetUserUsageTrend_UsesCache(t *testing.T) {
+	t.Cleanup(resetDashboardReadCachesForTest)
+	resetDashboardReadCachesForTest()
+
+	gin.SetMode(gin.TestMode)
+	repo := &dashboardUsageRepoCacheProbe{}
+	dashboardSvc := service.NewDashboardService(repo, nil, nil, nil)
+	handler := NewDashboardHandler(dashboardSvc, nil)
+	router := gin.New()
+	router.GET("/admin/dashboard/users-trend", handler.GetUserUsageTrend)
+
+	req1 := httptest.NewRequest(http.MethodGet, "/admin/dashboard/users-trend?start_date=2026-03-01&end_date=2026-03-07&granularity=day&limit=8", nil)
+	rec1 := httptest.NewRecorder()
+	router.ServeHTTP(rec1, req1)
+	require.Equal(t, http.StatusOK, rec1.Code)
+	require.Equal(t, "miss", rec1.Header().Get("X-Snapshot-Cache"))
+
+	req2 := httptest.NewRequest(http.MethodGet, "/admin/dashboard/users-trend?start_date=2026-03-01&end_date=2026-03-07&granularity=day&limit=8", nil)
+	rec2 := httptest.NewRecorder()
+	router.ServeHTTP(rec2, req2)
+	require.Equal(t, http.StatusOK, rec2.Code)
+	require.Equal(t, "hit", rec2.Header().Get("X-Snapshot-Cache"))
+	require.Equal(t, int32(1), repo.usersTrendCalls.Load())
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/dashboard_handler_request_type_test.go

@@ -0,0 +1,179 @@
+package admin
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type dashboardUsageRepoCapture struct {
+	service.UsageLogRepository
+	trendRequestType *int16
+	trendStream      *bool
+	modelRequestType *int16
+	modelStream      *bool
+	rankingLimit     int
+	ranking          []usagestats.UserSpendingRankingItem
+	rankingTotal     float64
+}
+
+func (s *dashboardUsageRepoCapture) GetUsageTrendWithFilters(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	granularity string,
+	userID, apiKeyID, accountID, groupID int64,
+	model string,
+	requestType *int16,
+	stream *bool,
+	billingType *int8,
+) ([]usagestats.TrendDataPoint, error) {
+	s.trendRequestType = requestType
+	s.trendStream = stream
+	return []usagestats.TrendDataPoint{}, nil
+}
+
+func (s *dashboardUsageRepoCapture) GetModelStatsWithFilters(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	userID, apiKeyID, accountID, groupID int64,
+	requestType *int16,
+	stream *bool,
+	billingType *int8,
+) ([]usagestats.ModelStat, error) {
+	s.modelRequestType = requestType
+	s.modelStream = stream
+	return []usagestats.ModelStat{}, nil
+}
+
+func (s *dashboardUsageRepoCapture) GetUserSpendingRanking(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	limit int,
+) (*usagestats.UserSpendingRankingResponse, error) {
+	s.rankingLimit = limit
+	return &usagestats.UserSpendingRankingResponse{
+		Ranking:         s.ranking,
+		TotalActualCost: s.rankingTotal,
+		TotalRequests:   44,
+		TotalTokens:     1234,
+	}, nil
+}
+
+func newDashboardRequestTypeTestRouter(repo *dashboardUsageRepoCapture) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	dashboardSvc := service.NewDashboardService(repo, nil, nil, nil)
+	handler := NewDashboardHandler(dashboardSvc, nil)
+	router := gin.New()
+	router.GET("/admin/dashboard/trend", handler.GetUsageTrend)
+	router.GET("/admin/dashboard/models", handler.GetModelStats)
+	router.GET("/admin/dashboard/users-ranking", handler.GetUserSpendingRanking)
+	return router
+}
+
+func TestDashboardTrendRequestTypePriority(t *testing.T) {
+	repo := &dashboardUsageRepoCapture{}
+	router := newDashboardRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/dashboard/trend?request_type=ws_v2&stream=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.NotNil(t, repo.trendRequestType)
+	require.Equal(t, int16(service.RequestTypeWSV2), *repo.trendRequestType)
+	require.Nil(t, repo.trendStream)
+}
+
+func TestDashboardTrendInvalidRequestType(t *testing.T) {
+	repo := &dashboardUsageRepoCapture{}
+	router := newDashboardRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/dashboard/trend?request_type=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestDashboardTrendInvalidStream(t *testing.T) {
+	repo := &dashboardUsageRepoCapture{}
+	router := newDashboardRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/dashboard/trend?stream=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestDashboardModelStatsRequestTypePriority(t *testing.T) {
+	repo := &dashboardUsageRepoCapture{}
+	router := newDashboardRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/dashboard/models?request_type=sync&stream=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.NotNil(t, repo.modelRequestType)
+	require.Equal(t, int16(service.RequestTypeSync), *repo.modelRequestType)
+	require.Nil(t, repo.modelStream)
+}
+
+func TestDashboardModelStatsInvalidRequestType(t *testing.T) {
+	repo := &dashboardUsageRepoCapture{}
+	router := newDashboardRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/dashboard/models?request_type=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestDashboardModelStatsInvalidStream(t *testing.T) {
+	repo := &dashboardUsageRepoCapture{}
+	router := newDashboardRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/dashboard/models?stream=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestDashboardUsersRankingLimitAndCache(t *testing.T) {
+	dashboardUsersRankingCache = newSnapshotCache(5 * time.Minute)
+	repo := &dashboardUsageRepoCapture{
+		ranking: []usagestats.UserSpendingRankingItem{
+			{UserID: 7, Email: "rank@example.com", ActualCost: 10.5, Requests: 3, Tokens: 300},
+		},
+		rankingTotal: 88.8,
+	}
+	router := newDashboardRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/dashboard/users-ranking?limit=100&start_date=2025-01-01&end_date=2025-01-02", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.Equal(t, 50, repo.rankingLimit)
+	require.Contains(t, rec.Body.String(), "\"total_actual_cost\":88.8")
+	require.Contains(t, rec.Body.String(), "\"total_requests\":44")
+	require.Contains(t, rec.Body.String(), "\"total_tokens\":1234")
+	require.Equal(t, "miss", rec.Header().Get("X-Snapshot-Cache"))
+
+	req2 := httptest.NewRequest(http.MethodGet, "/admin/dashboard/users-ranking?limit=100&start_date=2025-01-01&end_date=2025-01-02", nil)
+	rec2 := httptest.NewRecorder()
+	router.ServeHTTP(rec2, req2)
+
+	require.Equal(t, http.StatusOK, rec2.Code)
+	require.Equal(t, "hit", rec2.Header().Get("X-Snapshot-Cache"))
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/dashboard_query_cache.go

@@ -0,0 +1,200 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+)
+
+var (
+	dashboardTrendCache        = newSnapshotCache(30 * time.Second)
+	dashboardModelStatsCache   = newSnapshotCache(30 * time.Second)
+	dashboardGroupStatsCache   = newSnapshotCache(30 * time.Second)
+	dashboardUsersTrendCache   = newSnapshotCache(30 * time.Second)
+	dashboardAPIKeysTrendCache = newSnapshotCache(30 * time.Second)
+)
+
+type dashboardTrendCacheKey struct {
+	StartTime   string `json:"start_time"`
+	EndTime     string `json:"end_time"`
+	Granularity string `json:"granularity"`
+	UserID      int64  `json:"user_id"`
+	APIKeyID    int64  `json:"api_key_id"`
+	AccountID   int64  `json:"account_id"`
+	GroupID     int64  `json:"group_id"`
+	Model       string `json:"model"`
+	RequestType *int16 `json:"request_type"`
+	Stream      *bool  `json:"stream"`
+	BillingType *int8  `json:"billing_type"`
+}
+
+type dashboardModelGroupCacheKey struct {
+	StartTime   string `json:"start_time"`
+	EndTime     string `json:"end_time"`
+	UserID      int64  `json:"user_id"`
+	APIKeyID    int64  `json:"api_key_id"`
+	AccountID   int64  `json:"account_id"`
+	GroupID     int64  `json:"group_id"`
+	RequestType *int16 `json:"request_type"`
+	Stream      *bool  `json:"stream"`
+	BillingType *int8  `json:"billing_type"`
+}
+
+type dashboardEntityTrendCacheKey struct {
+	StartTime   string `json:"start_time"`
+	EndTime     string `json:"end_time"`
+	Granularity string `json:"granularity"`
+	Limit       int    `json:"limit"`
+}
+
+func cacheStatusValue(hit bool) string {
+	if hit {
+		return "hit"
+	}
+	return "miss"
+}
+
+func mustMarshalDashboardCacheKey(value any) string {
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return ""
+	}
+	return string(raw)
+}
+
+func snapshotPayloadAs[T any](payload any) (T, error) {
+	typed, ok := payload.(T)
+	if !ok {
+		var zero T
+		return zero, fmt.Errorf("unexpected cache payload type %T", payload)
+	}
+	return typed, nil
+}
+
+func (h *DashboardHandler) getUsageTrendCached(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	granularity string,
+	userID, apiKeyID, accountID, groupID int64,
+	model string,
+	requestType *int16,
+	stream *bool,
+	billingType *int8,
+) ([]usagestats.TrendDataPoint, bool, error) {
+	key := mustMarshalDashboardCacheKey(dashboardTrendCacheKey{
+		StartTime:   startTime.UTC().Format(time.RFC3339),
+		EndTime:     endTime.UTC().Format(time.RFC3339),
+		Granularity: granularity,
+		UserID:      userID,
+		APIKeyID:    apiKeyID,
+		AccountID:   accountID,
+		GroupID:     groupID,
+		Model:       model,
+		RequestType: requestType,
+		Stream:      stream,
+		BillingType: billingType,
+	})
+	entry, hit, err := dashboardTrendCache.GetOrLoad(key, func() (any, error) {
+		return h.dashboardService.GetUsageTrendWithFilters(ctx, startTime, endTime, granularity, userID, apiKeyID, accountID, groupID, model, requestType, stream, billingType)
+	})
+	if err != nil {
+		return nil, hit, err
+	}
+	trend, err := snapshotPayloadAs[[]usagestats.TrendDataPoint](entry.Payload)
+	return trend, hit, err
+}
+
+func (h *DashboardHandler) getModelStatsCached(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	userID, apiKeyID, accountID, groupID int64,
+	requestType *int16,
+	stream *bool,
+	billingType *int8,
+) ([]usagestats.ModelStat, bool, error) {
+	key := mustMarshalDashboardCacheKey(dashboardModelGroupCacheKey{
+		StartTime:   startTime.UTC().Format(time.RFC3339),
+		EndTime:     endTime.UTC().Format(time.RFC3339),
+		UserID:      userID,
+		APIKeyID:    apiKeyID,
+		AccountID:   accountID,
+		GroupID:     groupID,
+		RequestType: requestType,
+		Stream:      stream,
+		BillingType: billingType,
+	})
+	entry, hit, err := dashboardModelStatsCache.GetOrLoad(key, func() (any, error) {
+		return h.dashboardService.GetModelStatsWithFilters(ctx, startTime, endTime, userID, apiKeyID, accountID, groupID, requestType, stream, billingType)
+	})
+	if err != nil {
+		return nil, hit, err
+	}
+	stats, err := snapshotPayloadAs[[]usagestats.ModelStat](entry.Payload)
+	return stats, hit, err
+}
+
+func (h *DashboardHandler) getGroupStatsCached(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	userID, apiKeyID, accountID, groupID int64,
+	requestType *int16,
+	stream *bool,
+	billingType *int8,
+) ([]usagestats.GroupStat, bool, error) {
+	key := mustMarshalDashboardCacheKey(dashboardModelGroupCacheKey{
+		StartTime:   startTime.UTC().Format(time.RFC3339),
+		EndTime:     endTime.UTC().Format(time.RFC3339),
+		UserID:      userID,
+		APIKeyID:    apiKeyID,
+		AccountID:   accountID,
+		GroupID:     groupID,
+		RequestType: requestType,
+		Stream:      stream,
+		BillingType: billingType,
+	})
+	entry, hit, err := dashboardGroupStatsCache.GetOrLoad(key, func() (any, error) {
+		return h.dashboardService.GetGroupStatsWithFilters(ctx, startTime, endTime, userID, apiKeyID, accountID, groupID, requestType, stream, billingType)
+	})
+	if err != nil {
+		return nil, hit, err
+	}
+	stats, err := snapshotPayloadAs[[]usagestats.GroupStat](entry.Payload)
+	return stats, hit, err
+}
+
+func (h *DashboardHandler) getAPIKeyUsageTrendCached(ctx context.Context, startTime, endTime time.Time, granularity string, limit int) ([]usagestats.APIKeyUsageTrendPoint, bool, error) {
+	key := mustMarshalDashboardCacheKey(dashboardEntityTrendCacheKey{
+		StartTime:   startTime.UTC().Format(time.RFC3339),
+		EndTime:     endTime.UTC().Format(time.RFC3339),
+		Granularity: granularity,
+		Limit:       limit,
+	})
+	entry, hit, err := dashboardAPIKeysTrendCache.GetOrLoad(key, func() (any, error) {
+		return h.dashboardService.GetAPIKeyUsageTrend(ctx, startTime, endTime, granularity, limit)
+	})
+	if err != nil {
+		return nil, hit, err
+	}
+	trend, err := snapshotPayloadAs[[]usagestats.APIKeyUsageTrendPoint](entry.Payload)
+	return trend, hit, err
+}
+
+func (h *DashboardHandler) getUserUsageTrendCached(ctx context.Context, startTime, endTime time.Time, granularity string, limit int) ([]usagestats.UserUsageTrendPoint, bool, error) {
+	key := mustMarshalDashboardCacheKey(dashboardEntityTrendCacheKey{
+		StartTime:   startTime.UTC().Format(time.RFC3339),
+		EndTime:     endTime.UTC().Format(time.RFC3339),
+		Granularity: granularity,
+		Limit:       limit,
+	})
+	entry, hit, err := dashboardUsersTrendCache.GetOrLoad(key, func() (any, error) {
+		return h.dashboardService.GetUserUsageTrend(ctx, startTime, endTime, granularity, limit)
+	})
+	if err != nil {
+		return nil, hit, err
+	}
+	trend, err := snapshotPayloadAs[[]usagestats.UserUsageTrendPoint](entry.Payload)
+	return trend, hit, err
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/dashboard_snapshot_v2_handler.go

@@ -0,0 +1,302 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+var dashboardSnapshotV2Cache = newSnapshotCache(30 * time.Second)
+
+type dashboardSnapshotV2Stats struct {
+	usagestats.DashboardStats
+	Uptime int64 `json:"uptime"`
+}
+
+type dashboardSnapshotV2Response struct {
+	GeneratedAt string `json:"generated_at"`
+
+	StartDate   string `json:"start_date"`
+	EndDate     string `json:"end_date"`
+	Granularity string `json:"granularity"`
+
+	Stats      *dashboardSnapshotV2Stats        `json:"stats,omitempty"`
+	Trend      []usagestats.TrendDataPoint      `json:"trend,omitempty"`
+	Models     []usagestats.ModelStat           `json:"models,omitempty"`
+	Groups     []usagestats.GroupStat           `json:"groups,omitempty"`
+	UsersTrend []usagestats.UserUsageTrendPoint `json:"users_trend,omitempty"`
+}
+
+type dashboardSnapshotV2Filters struct {
+	UserID      int64
+	APIKeyID    int64
+	AccountID   int64
+	GroupID     int64
+	Model       string
+	RequestType *int16
+	Stream      *bool
+	BillingType *int8
+}
+
+type dashboardSnapshotV2CacheKey struct {
+	StartTime         string `json:"start_time"`
+	EndTime           string `json:"end_time"`
+	Granularity       string `json:"granularity"`
+	UserID            int64  `json:"user_id"`
+	APIKeyID          int64  `json:"api_key_id"`
+	AccountID         int64  `json:"account_id"`
+	GroupID           int64  `json:"group_id"`
+	Model             string `json:"model"`
+	RequestType       *int16 `json:"request_type"`
+	Stream            *bool  `json:"stream"`
+	BillingType       *int8  `json:"billing_type"`
+	IncludeStats      bool   `json:"include_stats"`
+	IncludeTrend      bool   `json:"include_trend"`
+	IncludeModels     bool   `json:"include_models"`
+	IncludeGroups     bool   `json:"include_groups"`
+	IncludeUsersTrend bool   `json:"include_users_trend"`
+	UsersTrendLimit   int    `json:"users_trend_limit"`
+}
+
+func (h *DashboardHandler) GetSnapshotV2(c *gin.Context) {
+	startTime, endTime := parseTimeRange(c)
+	granularity := strings.TrimSpace(c.DefaultQuery("granularity", "day"))
+	if granularity != "hour" {
+		granularity = "day"
+	}
+
+	includeStats := parseBoolQueryWithDefault(c.Query("include_stats"), true)
+	includeTrend := parseBoolQueryWithDefault(c.Query("include_trend"), true)
+	includeModels := parseBoolQueryWithDefault(c.Query("include_model_stats"), true)
+	includeGroups := parseBoolQueryWithDefault(c.Query("include_group_stats"), false)
+	includeUsersTrend := parseBoolQueryWithDefault(c.Query("include_users_trend"), false)
+	usersTrendLimit := 12
+	if raw := strings.TrimSpace(c.Query("users_trend_limit")); raw != "" {
+		if parsed, err := strconv.Atoi(raw); err == nil && parsed > 0 && parsed <= 50 {
+			usersTrendLimit = parsed
+		}
+	}
+
+	filters, err := parseDashboardSnapshotV2Filters(c)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	keyRaw, _ := json.Marshal(dashboardSnapshotV2CacheKey{
+		StartTime:         startTime.UTC().Format(time.RFC3339),
+		EndTime:           endTime.UTC().Format(time.RFC3339),
+		Granularity:       granularity,
+		UserID:            filters.UserID,
+		APIKeyID:          filters.APIKeyID,
+		AccountID:         filters.AccountID,
+		GroupID:           filters.GroupID,
+		Model:             filters.Model,
+		RequestType:       filters.RequestType,
+		Stream:            filters.Stream,
+		BillingType:       filters.BillingType,
+		IncludeStats:      includeStats,
+		IncludeTrend:      includeTrend,
+		IncludeModels:     includeModels,
+		IncludeGroups:     includeGroups,
+		IncludeUsersTrend: includeUsersTrend,
+		UsersTrendLimit:   usersTrendLimit,
+	})
+	cacheKey := string(keyRaw)
+
+	cached, hit, err := dashboardSnapshotV2Cache.GetOrLoad(cacheKey, func() (any, error) {
+		return h.buildSnapshotV2Response(
+			c.Request.Context(),
+			startTime,
+			endTime,
+			granularity,
+			filters,
+			includeStats,
+			includeTrend,
+			includeModels,
+			includeGroups,
+			includeUsersTrend,
+			usersTrendLimit,
+		)
+	})
+	if err != nil {
+		response.Error(c, 500, err.Error())
+		return
+	}
+	if cached.ETag != "" {
+		c.Header("ETag", cached.ETag)
+		c.Header("Vary", "If-None-Match")
+		if ifNoneMatchMatched(c.GetHeader("If-None-Match"), cached.ETag) {
+			c.Status(http.StatusNotModified)
+			return
+		}
+	}
+	c.Header("X-Snapshot-Cache", cacheStatusValue(hit))
+	response.Success(c, cached.Payload)
+}
+
+func (h *DashboardHandler) buildSnapshotV2Response(
+	ctx context.Context,
+	startTime, endTime time.Time,
+	granularity string,
+	filters *dashboardSnapshotV2Filters,
+	includeStats, includeTrend, includeModels, includeGroups, includeUsersTrend bool,
+	usersTrendLimit int,
+) (*dashboardSnapshotV2Response, error) {
+	resp := &dashboardSnapshotV2Response{
+		GeneratedAt: time.Now().UTC().Format(time.RFC3339),
+		StartDate:   startTime.Format("2006-01-02"),
+		EndDate:     endTime.Add(-24 * time.Hour).Format("2006-01-02"),
+		Granularity: granularity,
+	}
+
+	if includeStats {
+		stats, err := h.dashboardService.GetDashboardStats(ctx)
+		if err != nil {
+			return nil, errors.New("failed to get dashboard statistics")
+		}
+		resp.Stats = &dashboardSnapshotV2Stats{
+			DashboardStats: *stats,
+			Uptime:         int64(time.Since(h.startTime).Seconds()),
+		}
+	}
+
+	if includeTrend {
+		trend, _, err := h.getUsageTrendCached(
+			ctx,
+			startTime,
+			endTime,
+			granularity,
+			filters.UserID,
+			filters.APIKeyID,
+			filters.AccountID,
+			filters.GroupID,
+			filters.Model,
+			filters.RequestType,
+			filters.Stream,
+			filters.BillingType,
+		)
+		if err != nil {
+			return nil, errors.New("failed to get usage trend")
+		}
+		resp.Trend = trend
+	}
+
+	if includeModels {
+		models, _, err := h.getModelStatsCached(
+			ctx,
+			startTime,
+			endTime,
+			filters.UserID,
+			filters.APIKeyID,
+			filters.AccountID,
+			filters.GroupID,
+			filters.RequestType,
+			filters.Stream,
+			filters.BillingType,
+		)
+		if err != nil {
+			return nil, errors.New("failed to get model statistics")
+		}
+		resp.Models = models
+	}
+
+	if includeGroups {
+		groups, _, err := h.getGroupStatsCached(
+			ctx,
+			startTime,
+			endTime,
+			filters.UserID,
+			filters.APIKeyID,
+			filters.AccountID,
+			filters.GroupID,
+			filters.RequestType,
+			filters.Stream,
+			filters.BillingType,
+		)
+		if err != nil {
+			return nil, errors.New("failed to get group statistics")
+		}
+		resp.Groups = groups
+	}
+
+	if includeUsersTrend {
+		usersTrend, _, err := h.getUserUsageTrendCached(ctx, startTime, endTime, granularity, usersTrendLimit)
+		if err != nil {
+			return nil, errors.New("failed to get user usage trend")
+		}
+		resp.UsersTrend = usersTrend
+	}
+
+	return resp, nil
+}
+
+func parseDashboardSnapshotV2Filters(c *gin.Context) (*dashboardSnapshotV2Filters, error) {
+	filters := &dashboardSnapshotV2Filters{
+		Model: strings.TrimSpace(c.Query("model")),
+	}
+
+	if userIDStr := strings.TrimSpace(c.Query("user_id")); userIDStr != "" {
+		id, err := strconv.ParseInt(userIDStr, 10, 64)
+		if err != nil {
+			return nil, err
+		}
+		filters.UserID = id
+	}
+	if apiKeyIDStr := strings.TrimSpace(c.Query("api_key_id")); apiKeyIDStr != "" {
+		id, err := strconv.ParseInt(apiKeyIDStr, 10, 64)
+		if err != nil {
+			return nil, err
+		}
+		filters.APIKeyID = id
+	}
+	if accountIDStr := strings.TrimSpace(c.Query("account_id")); accountIDStr != "" {
+		id, err := strconv.ParseInt(accountIDStr, 10, 64)
+		if err != nil {
+			return nil, err
+		}
+		filters.AccountID = id
+	}
+	if groupIDStr := strings.TrimSpace(c.Query("group_id")); groupIDStr != "" {
+		id, err := strconv.ParseInt(groupIDStr, 10, 64)
+		if err != nil {
+			return nil, err
+		}
+		filters.GroupID = id
+	}
+
+	if requestTypeStr := strings.TrimSpace(c.Query("request_type")); requestTypeStr != "" {
+		parsed, err := service.ParseUsageRequestType(requestTypeStr)
+		if err != nil {
+			return nil, err
+		}
+		value := int16(parsed)
+		filters.RequestType = &value
+	} else if streamStr := strings.TrimSpace(c.Query("stream")); streamStr != "" {
+		streamVal, err := strconv.ParseBool(streamStr)
+		if err != nil {
+			return nil, err
+		}
+		filters.Stream = &streamVal
+	}
+
+	if billingTypeStr := strings.TrimSpace(c.Query("billing_type")); billingTypeStr != "" {
+		v, err := strconv.ParseInt(billingTypeStr, 10, 8)
+		if err != nil {
+			return nil, err
+		}
+		bt := int8(v)
+		filters.BillingType = &bt
+	}
+
+	return filters, nil
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/data_management_handler.go

@@ -0,0 +1,545 @@
+package admin
+
+import (
+	"context"
+	"strconv"
+	"strings"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+type DataManagementHandler struct {
+	dataManagementService dataManagementService
+}
+
+func NewDataManagementHandler(dataManagementService *service.DataManagementService) *DataManagementHandler {
+	return &DataManagementHandler{dataManagementService: dataManagementService}
+}
+
+type dataManagementService interface {
+	GetConfig(ctx context.Context) (service.DataManagementConfig, error)
+	UpdateConfig(ctx context.Context, cfg service.DataManagementConfig) (service.DataManagementConfig, error)
+	ValidateS3(ctx context.Context, cfg service.DataManagementS3Config) (service.DataManagementTestS3Result, error)
+	CreateBackupJob(ctx context.Context, input service.DataManagementCreateBackupJobInput) (service.DataManagementBackupJob, error)
+	ListSourceProfiles(ctx context.Context, sourceType string) ([]service.DataManagementSourceProfile, error)
+	CreateSourceProfile(ctx context.Context, input service.DataManagementCreateSourceProfileInput) (service.DataManagementSourceProfile, error)
+	UpdateSourceProfile(ctx context.Context, input service.DataManagementUpdateSourceProfileInput) (service.DataManagementSourceProfile, error)
+	DeleteSourceProfile(ctx context.Context, sourceType, profileID string) error
+	SetActiveSourceProfile(ctx context.Context, sourceType, profileID string) (service.DataManagementSourceProfile, error)
+	ListS3Profiles(ctx context.Context) ([]service.DataManagementS3Profile, error)
+	CreateS3Profile(ctx context.Context, input service.DataManagementCreateS3ProfileInput) (service.DataManagementS3Profile, error)
+	UpdateS3Profile(ctx context.Context, input service.DataManagementUpdateS3ProfileInput) (service.DataManagementS3Profile, error)
+	DeleteS3Profile(ctx context.Context, profileID string) error
+	SetActiveS3Profile(ctx context.Context, profileID string) (service.DataManagementS3Profile, error)
+	ListBackupJobs(ctx context.Context, input service.DataManagementListBackupJobsInput) (service.DataManagementListBackupJobsResult, error)
+	GetBackupJob(ctx context.Context, jobID string) (service.DataManagementBackupJob, error)
+	EnsureAgentEnabled(ctx context.Context) error
+	GetAgentHealth(ctx context.Context) service.DataManagementAgentHealth
+}
+
+type TestS3ConnectionRequest struct {
+	Endpoint        string `json:"endpoint"`
+	Region          string `json:"region" binding:"required"`
+	Bucket          string `json:"bucket" binding:"required"`
+	AccessKeyID     string `json:"access_key_id"`
+	SecretAccessKey string `json:"secret_access_key"`
+	Prefix          string `json:"prefix"`
+	ForcePathStyle  bool   `json:"force_path_style"`
+	UseSSL          bool   `json:"use_ssl"`
+}
+
+type CreateBackupJobRequest struct {
+	BackupType     string `json:"backup_type" binding:"required,oneof=postgres redis full"`
+	UploadToS3     bool   `json:"upload_to_s3"`
+	S3ProfileID    string `json:"s3_profile_id"`
+	PostgresID     string `json:"postgres_profile_id"`
+	RedisID        string `json:"redis_profile_id"`
+	IdempotencyKey string `json:"idempotency_key"`
+}
+
+type CreateSourceProfileRequest struct {
+	ProfileID string                             `json:"profile_id" binding:"required"`
+	Name      string                             `json:"name" binding:"required"`
+	Config    service.DataManagementSourceConfig `json:"config" binding:"required"`
+	SetActive bool                               `json:"set_active"`
+}
+
+type UpdateSourceProfileRequest struct {
+	Name   string                             `json:"name" binding:"required"`
+	Config service.DataManagementSourceConfig `json:"config" binding:"required"`
+}
+
+type CreateS3ProfileRequest struct {
+	ProfileID       string `json:"profile_id" binding:"required"`
+	Name            string `json:"name" binding:"required"`
+	Enabled         bool   `json:"enabled"`
+	Endpoint        string `json:"endpoint"`
+	Region          string `json:"region"`
+	Bucket          string `json:"bucket"`
+	AccessKeyID     string `json:"access_key_id"`
+	SecretAccessKey string `json:"secret_access_key"`
+	Prefix          string `json:"prefix"`
+	ForcePathStyle  bool   `json:"force_path_style"`
+	UseSSL          bool   `json:"use_ssl"`
+	SetActive       bool   `json:"set_active"`
+}
+
+type UpdateS3ProfileRequest struct {
+	Name            string `json:"name" binding:"required"`
+	Enabled         bool   `json:"enabled"`
+	Endpoint        string `json:"endpoint"`
+	Region          string `json:"region"`
+	Bucket          string `json:"bucket"`
+	AccessKeyID     string `json:"access_key_id"`
+	SecretAccessKey string `json:"secret_access_key"`
+	Prefix          string `json:"prefix"`
+	ForcePathStyle  bool   `json:"force_path_style"`
+	UseSSL          bool   `json:"use_ssl"`
+}
+
+func (h *DataManagementHandler) GetAgentHealth(c *gin.Context) {
+	health := h.getAgentHealth(c)
+	payload := gin.H{
+		"enabled":     health.Enabled,
+		"reason":      health.Reason,
+		"socket_path": health.SocketPath,
+	}
+	if health.Agent != nil {
+		payload["agent"] = gin.H{
+			"status":         health.Agent.Status,
+			"version":        health.Agent.Version,
+			"uptime_seconds": health.Agent.UptimeSeconds,
+		}
+	}
+	response.Success(c, payload)
+}
+
+func (h *DataManagementHandler) GetConfig(c *gin.Context) {
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	cfg, err := h.dataManagementService.GetConfig(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, cfg)
+}
+
+func (h *DataManagementHandler) UpdateConfig(c *gin.Context) {
+	var req service.DataManagementConfig
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	cfg, err := h.dataManagementService.UpdateConfig(c.Request.Context(), req)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, cfg)
+}
+
+func (h *DataManagementHandler) TestS3(c *gin.Context) {
+	var req TestS3ConnectionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	result, err := h.dataManagementService.ValidateS3(c.Request.Context(), service.DataManagementS3Config{
+		Enabled:         true,
+		Endpoint:        req.Endpoint,
+		Region:          req.Region,
+		Bucket:          req.Bucket,
+		AccessKeyID:     req.AccessKeyID,
+		SecretAccessKey: req.SecretAccessKey,
+		Prefix:          req.Prefix,
+		ForcePathStyle:  req.ForcePathStyle,
+		UseSSL:          req.UseSSL,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"ok": result.OK, "message": result.Message})
+}
+
+func (h *DataManagementHandler) CreateBackupJob(c *gin.Context) {
+	var req CreateBackupJobRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	req.IdempotencyKey = normalizeBackupIdempotencyKey(c.GetHeader("X-Idempotency-Key"), req.IdempotencyKey)
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+
+	triggeredBy := "admin:unknown"
+	if subject, ok := middleware2.GetAuthSubjectFromContext(c); ok {
+		triggeredBy = "admin:" + strconv.FormatInt(subject.UserID, 10)
+	}
+	job, err := h.dataManagementService.CreateBackupJob(c.Request.Context(), service.DataManagementCreateBackupJobInput{
+		BackupType:     req.BackupType,
+		UploadToS3:     req.UploadToS3,
+		S3ProfileID:    req.S3ProfileID,
+		PostgresID:     req.PostgresID,
+		RedisID:        req.RedisID,
+		TriggeredBy:    triggeredBy,
+		IdempotencyKey: req.IdempotencyKey,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"job_id": job.JobID, "status": job.Status})
+}
+
+func (h *DataManagementHandler) ListSourceProfiles(c *gin.Context) {
+	sourceType := strings.TrimSpace(c.Param("source_type"))
+	if sourceType == "" {
+		response.BadRequest(c, "Invalid source_type")
+		return
+	}
+	if sourceType != "postgres" && sourceType != "redis" {
+		response.BadRequest(c, "source_type must be postgres or redis")
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	items, err := h.dataManagementService.ListSourceProfiles(c.Request.Context(), sourceType)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"items": items})
+}
+
+func (h *DataManagementHandler) CreateSourceProfile(c *gin.Context) {
+	sourceType := strings.TrimSpace(c.Param("source_type"))
+	if sourceType != "postgres" && sourceType != "redis" {
+		response.BadRequest(c, "source_type must be postgres or redis")
+		return
+	}
+
+	var req CreateSourceProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	profile, err := h.dataManagementService.CreateSourceProfile(c.Request.Context(), service.DataManagementCreateSourceProfileInput{
+		SourceType: sourceType,
+		ProfileID:  req.ProfileID,
+		Name:       req.Name,
+		Config:     req.Config,
+		SetActive:  req.SetActive,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, profile)
+}
+
+func (h *DataManagementHandler) UpdateSourceProfile(c *gin.Context) {
+	sourceType := strings.TrimSpace(c.Param("source_type"))
+	if sourceType != "postgres" && sourceType != "redis" {
+		response.BadRequest(c, "source_type must be postgres or redis")
+		return
+	}
+	profileID := strings.TrimSpace(c.Param("profile_id"))
+	if profileID == "" {
+		response.BadRequest(c, "Invalid profile_id")
+		return
+	}
+
+	var req UpdateSourceProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	profile, err := h.dataManagementService.UpdateSourceProfile(c.Request.Context(), service.DataManagementUpdateSourceProfileInput{
+		SourceType: sourceType,
+		ProfileID:  profileID,
+		Name:       req.Name,
+		Config:     req.Config,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, profile)
+}
+
+func (h *DataManagementHandler) DeleteSourceProfile(c *gin.Context) {
+	sourceType := strings.TrimSpace(c.Param("source_type"))
+	if sourceType != "postgres" && sourceType != "redis" {
+		response.BadRequest(c, "source_type must be postgres or redis")
+		return
+	}
+	profileID := strings.TrimSpace(c.Param("profile_id"))
+	if profileID == "" {
+		response.BadRequest(c, "Invalid profile_id")
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	if err := h.dataManagementService.DeleteSourceProfile(c.Request.Context(), sourceType, profileID); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"deleted": true})
+}
+
+func (h *DataManagementHandler) SetActiveSourceProfile(c *gin.Context) {
+	sourceType := strings.TrimSpace(c.Param("source_type"))
+	if sourceType != "postgres" && sourceType != "redis" {
+		response.BadRequest(c, "source_type must be postgres or redis")
+		return
+	}
+	profileID := strings.TrimSpace(c.Param("profile_id"))
+	if profileID == "" {
+		response.BadRequest(c, "Invalid profile_id")
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	profile, err := h.dataManagementService.SetActiveSourceProfile(c.Request.Context(), sourceType, profileID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, profile)
+}
+
+func (h *DataManagementHandler) ListS3Profiles(c *gin.Context) {
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+
+	items, err := h.dataManagementService.ListS3Profiles(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"items": items})
+}
+
+func (h *DataManagementHandler) CreateS3Profile(c *gin.Context) {
+	var req CreateS3ProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+
+	profile, err := h.dataManagementService.CreateS3Profile(c.Request.Context(), service.DataManagementCreateS3ProfileInput{
+		ProfileID: req.ProfileID,
+		Name:      req.Name,
+		SetActive: req.SetActive,
+		S3: service.DataManagementS3Config{
+			Enabled:         req.Enabled,
+			Endpoint:        req.Endpoint,
+			Region:          req.Region,
+			Bucket:          req.Bucket,
+			AccessKeyID:     req.AccessKeyID,
+			SecretAccessKey: req.SecretAccessKey,
+			Prefix:          req.Prefix,
+			ForcePathStyle:  req.ForcePathStyle,
+			UseSSL:          req.UseSSL,
+		},
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, profile)
+}
+
+func (h *DataManagementHandler) UpdateS3Profile(c *gin.Context) {
+	var req UpdateS3ProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	profileID := strings.TrimSpace(c.Param("profile_id"))
+	if profileID == "" {
+		response.BadRequest(c, "Invalid profile_id")
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+
+	profile, err := h.dataManagementService.UpdateS3Profile(c.Request.Context(), service.DataManagementUpdateS3ProfileInput{
+		ProfileID: profileID,
+		Name:      req.Name,
+		S3: service.DataManagementS3Config{
+			Enabled:         req.Enabled,
+			Endpoint:        req.Endpoint,
+			Region:          req.Region,
+			Bucket:          req.Bucket,
+			AccessKeyID:     req.AccessKeyID,
+			SecretAccessKey: req.SecretAccessKey,
+			Prefix:          req.Prefix,
+			ForcePathStyle:  req.ForcePathStyle,
+			UseSSL:          req.UseSSL,
+		},
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, profile)
+}
+
+func (h *DataManagementHandler) DeleteS3Profile(c *gin.Context) {
+	profileID := strings.TrimSpace(c.Param("profile_id"))
+	if profileID == "" {
+		response.BadRequest(c, "Invalid profile_id")
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	if err := h.dataManagementService.DeleteS3Profile(c.Request.Context(), profileID); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"deleted": true})
+}
+
+func (h *DataManagementHandler) SetActiveS3Profile(c *gin.Context) {
+	profileID := strings.TrimSpace(c.Param("profile_id"))
+	if profileID == "" {
+		response.BadRequest(c, "Invalid profile_id")
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	profile, err := h.dataManagementService.SetActiveS3Profile(c.Request.Context(), profileID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, profile)
+}
+
+func (h *DataManagementHandler) ListBackupJobs(c *gin.Context) {
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+
+	pageSize := int32(20)
+	if raw := strings.TrimSpace(c.Query("page_size")); raw != "" {
+		v, err := strconv.Atoi(raw)
+		if err != nil || v <= 0 {
+			response.BadRequest(c, "Invalid page_size")
+			return
+		}
+		pageSize = int32(v)
+	}
+
+	result, err := h.dataManagementService.ListBackupJobs(c.Request.Context(), service.DataManagementListBackupJobsInput{
+		PageSize:   pageSize,
+		PageToken:  c.Query("page_token"),
+		Status:     c.Query("status"),
+		BackupType: c.Query("backup_type"),
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, result)
+}
+
+func (h *DataManagementHandler) GetBackupJob(c *gin.Context) {
+	jobID := strings.TrimSpace(c.Param("job_id"))
+	if jobID == "" {
+		response.BadRequest(c, "Invalid backup job ID")
+		return
+	}
+
+	if !h.requireAgentEnabled(c) {
+		return
+	}
+	job, err := h.dataManagementService.GetBackupJob(c.Request.Context(), jobID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, job)
+}
+
+func (h *DataManagementHandler) requireAgentEnabled(c *gin.Context) bool {
+	if h.dataManagementService == nil {
+		err := infraerrors.ServiceUnavailable(
+			service.DataManagementAgentUnavailableReason,
+			"data management agent service is not configured",
+		).WithMetadata(map[string]string{"socket_path": service.DefaultDataManagementAgentSocketPath})
+		response.ErrorFrom(c, err)
+		return false
+	}
+
+	if err := h.dataManagementService.EnsureAgentEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return false
+	}
+
+	return true
+}
+
+func (h *DataManagementHandler) getAgentHealth(c *gin.Context) service.DataManagementAgentHealth {
+	if h.dataManagementService == nil {
+		return service.DataManagementAgentHealth{
+			Enabled:    false,
+			Reason:     service.DataManagementAgentUnavailableReason,
+			SocketPath: service.DefaultDataManagementAgentSocketPath,
+		}
+	}
+	return h.dataManagementService.GetAgentHealth(c.Request.Context())
+}
+
+func normalizeBackupIdempotencyKey(headerValue, bodyValue string) string {
+	headerKey := strings.TrimSpace(headerValue)
+	if headerKey != "" {
+		return headerKey
+	}
+	return strings.TrimSpace(bodyValue)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/data_management_handler_test.go

@@ -0,0 +1,78 @@
+package admin
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type apiEnvelope struct {
+	Code    int             `json:"code"`
+	Message string          `json:"message"`
+	Reason  string          `json:"reason"`
+	Data    json.RawMessage `json:"data"`
+}
+
+func TestDataManagementHandler_AgentHealthAlways200(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	svc := service.NewDataManagementServiceWithOptions(filepath.Join(t.TempDir(), "missing.sock"), 50*time.Millisecond)
+	h := NewDataManagementHandler(svc)
+
+	r := gin.New()
+	r.GET("/api/v1/admin/data-management/agent/health", h.GetAgentHealth)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/data-management/agent/health", nil)
+	r.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var envelope apiEnvelope
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &envelope))
+	require.Equal(t, 0, envelope.Code)
+
+	var data struct {
+		Enabled    bool   `json:"enabled"`
+		Reason     string `json:"reason"`
+		SocketPath string `json:"socket_path"`
+	}
+	require.NoError(t, json.Unmarshal(envelope.Data, &data))
+	require.False(t, data.Enabled)
+	require.Equal(t, service.DataManagementDeprecatedReason, data.Reason)
+	require.Equal(t, svc.SocketPath(), data.SocketPath)
+}
+
+func TestDataManagementHandler_NonHealthRouteReturns503WhenDisabled(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	svc := service.NewDataManagementServiceWithOptions(filepath.Join(t.TempDir(), "missing.sock"), 50*time.Millisecond)
+	h := NewDataManagementHandler(svc)
+
+	r := gin.New()
+	r.GET("/api/v1/admin/data-management/config", h.GetConfig)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/data-management/config", nil)
+	r.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusServiceUnavailable, rec.Code)
+
+	var envelope apiEnvelope
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &envelope))
+	require.Equal(t, http.StatusServiceUnavailable, envelope.Code)
+	require.Equal(t, service.DataManagementDeprecatedReason, envelope.Reason)
+}
+
+func TestNormalizeBackupIdempotencyKey(t *testing.T) {
+	require.Equal(t, "from-header", normalizeBackupIdempotencyKey("from-header", "from-body"))
+	require.Equal(t, "from-body", normalizeBackupIdempotencyKey(" ", " from-body "))
+	require.Equal(t, "", normalizeBackupIdempotencyKey("", ""))
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/error_passthrough_handler.go

@@ -0,0 +1,282 @@
+package admin
+
+import (
+	"strconv"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+// ErrorPassthroughHandler 处理错误透传规则的 HTTP 请求
+type ErrorPassthroughHandler struct {
+	service *service.ErrorPassthroughService
+}
+
+// NewErrorPassthroughHandler 创建错误透传规则处理器
+func NewErrorPassthroughHandler(service *service.ErrorPassthroughService) *ErrorPassthroughHandler {
+	return &ErrorPassthroughHandler{service: service}
+}
+
+// CreateErrorPassthroughRuleRequest 创建规则请求
+type CreateErrorPassthroughRuleRequest struct {
+	Name            string   `json:"name" binding:"required"`
+	Enabled         *bool    `json:"enabled"`
+	Priority        int      `json:"priority"`
+	ErrorCodes      []int    `json:"error_codes"`
+	Keywords        []string `json:"keywords"`
+	MatchMode       string   `json:"match_mode"`
+	Platforms       []string `json:"platforms"`
+	PassthroughCode *bool    `json:"passthrough_code"`
+	ResponseCode    *int     `json:"response_code"`
+	PassthroughBody *bool    `json:"passthrough_body"`
+	CustomMessage   *string  `json:"custom_message"`
+	SkipMonitoring  *bool    `json:"skip_monitoring"`
+	Description     *string  `json:"description"`
+}
+
+// UpdateErrorPassthroughRuleRequest 更新规则请求（部分更新，所有字段可选）
+type UpdateErrorPassthroughRuleRequest struct {
+	Name            *string  `json:"name"`
+	Enabled         *bool    `json:"enabled"`
+	Priority        *int     `json:"priority"`
+	ErrorCodes      []int    `json:"error_codes"`
+	Keywords        []string `json:"keywords"`
+	MatchMode       *string  `json:"match_mode"`
+	Platforms       []string `json:"platforms"`
+	PassthroughCode *bool    `json:"passthrough_code"`
+	ResponseCode    *int     `json:"response_code"`
+	PassthroughBody *bool    `json:"passthrough_body"`
+	CustomMessage   *string  `json:"custom_message"`
+	SkipMonitoring  *bool    `json:"skip_monitoring"`
+	Description     *string  `json:"description"`
+}
+
+// List 获取所有规则
+// GET /api/v1/admin/error-passthrough-rules
+func (h *ErrorPassthroughHandler) List(c *gin.Context) {
+	rules, err := h.service.List(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, rules)
+}
+
+// GetByID 根据 ID 获取规则
+// GET /api/v1/admin/error-passthrough-rules/:id
+func (h *ErrorPassthroughHandler) GetByID(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid rule ID")
+		return
+	}
+
+	rule, err := h.service.GetByID(c.Request.Context(), id)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	if rule == nil {
+		response.NotFound(c, "Rule not found")
+		return
+	}
+
+	response.Success(c, rule)
+}
+
+// Create 创建规则
+// POST /api/v1/admin/error-passthrough-rules
+func (h *ErrorPassthroughHandler) Create(c *gin.Context) {
+	var req CreateErrorPassthroughRuleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	rule := &model.ErrorPassthroughRule{
+		Name:       req.Name,
+		Priority:   req.Priority,
+		ErrorCodes: req.ErrorCodes,
+		Keywords:   req.Keywords,
+		Platforms:  req.Platforms,
+	}
+
+	// 设置默认值
+	if req.Enabled != nil {
+		rule.Enabled = *req.Enabled
+	} else {
+		rule.Enabled = true
+	}
+	if req.MatchMode != "" {
+		rule.MatchMode = req.MatchMode
+	} else {
+		rule.MatchMode = model.MatchModeAny
+	}
+	if req.PassthroughCode != nil {
+		rule.PassthroughCode = *req.PassthroughCode
+	} else {
+		rule.PassthroughCode = true
+	}
+	if req.PassthroughBody != nil {
+		rule.PassthroughBody = *req.PassthroughBody
+	} else {
+		rule.PassthroughBody = true
+	}
+	if req.SkipMonitoring != nil {
+		rule.SkipMonitoring = *req.SkipMonitoring
+	}
+	rule.ResponseCode = req.ResponseCode
+	rule.CustomMessage = req.CustomMessage
+	rule.Description = req.Description
+
+	// 确保切片不为 nil
+	if rule.ErrorCodes == nil {
+		rule.ErrorCodes = []int{}
+	}
+	if rule.Keywords == nil {
+		rule.Keywords = []string{}
+	}
+	if rule.Platforms == nil {
+		rule.Platforms = []string{}
+	}
+
+	created, err := h.service.Create(c.Request.Context(), rule)
+	if err != nil {
+		if _, ok := err.(*model.ValidationError); ok {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, created)
+}
+
+// Update 更新规则（支持部分更新）
+// PUT /api/v1/admin/error-passthrough-rules/:id
+func (h *ErrorPassthroughHandler) Update(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid rule ID")
+		return
+	}
+
+	var req UpdateErrorPassthroughRuleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// 先获取现有规则
+	existing, err := h.service.GetByID(c.Request.Context(), id)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	if existing == nil {
+		response.NotFound(c, "Rule not found")
+		return
+	}
+
+	// 部分更新：只更新请求中提供的字段
+	rule := &model.ErrorPassthroughRule{
+		ID:              id,
+		Name:            existing.Name,
+		Enabled:         existing.Enabled,
+		Priority:        existing.Priority,
+		ErrorCodes:      existing.ErrorCodes,
+		Keywords:        existing.Keywords,
+		MatchMode:       existing.MatchMode,
+		Platforms:       existing.Platforms,
+		PassthroughCode: existing.PassthroughCode,
+		ResponseCode:    existing.ResponseCode,
+		PassthroughBody: existing.PassthroughBody,
+		CustomMessage:   existing.CustomMessage,
+		SkipMonitoring:  existing.SkipMonitoring,
+		Description:     existing.Description,
+	}
+
+	// 应用请求中提供的更新
+	if req.Name != nil {
+		rule.Name = *req.Name
+	}
+	if req.Enabled != nil {
+		rule.Enabled = *req.Enabled
+	}
+	if req.Priority != nil {
+		rule.Priority = *req.Priority
+	}
+	if req.ErrorCodes != nil {
+		rule.ErrorCodes = req.ErrorCodes
+	}
+	if req.Keywords != nil {
+		rule.Keywords = req.Keywords
+	}
+	if req.MatchMode != nil {
+		rule.MatchMode = *req.MatchMode
+	}
+	if req.Platforms != nil {
+		rule.Platforms = req.Platforms
+	}
+	if req.PassthroughCode != nil {
+		rule.PassthroughCode = *req.PassthroughCode
+	}
+	if req.ResponseCode != nil {
+		rule.ResponseCode = req.ResponseCode
+	}
+	if req.PassthroughBody != nil {
+		rule.PassthroughBody = *req.PassthroughBody
+	}
+	if req.CustomMessage != nil {
+		rule.CustomMessage = req.CustomMessage
+	}
+	if req.Description != nil {
+		rule.Description = req.Description
+	}
+	if req.SkipMonitoring != nil {
+		rule.SkipMonitoring = *req.SkipMonitoring
+	}
+
+	// 确保切片不为 nil
+	if rule.ErrorCodes == nil {
+		rule.ErrorCodes = []int{}
+	}
+	if rule.Keywords == nil {
+		rule.Keywords = []string{}
+	}
+	if rule.Platforms == nil {
+		rule.Platforms = []string{}
+	}
+
+	updated, err := h.service.Update(c.Request.Context(), rule)
+	if err != nil {
+		if _, ok := err.(*model.ValidationError); ok {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, updated)
+}
+
+// Delete 删除规则
+// DELETE /api/v1/admin/error-passthrough-rules/:id
+func (h *ErrorPassthroughHandler) Delete(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid rule ID")
+		return
+	}
+
+	if err := h.service.Delete(c.Request.Context(), id); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Rule deleted successfully"})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/gemini_oauth_handler.go

@@ -0,0 +1,146 @@
+package admin
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+type GeminiOAuthHandler struct {
+	geminiOAuthService *service.GeminiOAuthService
+}
+
+func NewGeminiOAuthHandler(geminiOAuthService *service.GeminiOAuthService) *GeminiOAuthHandler {
+	return &GeminiOAuthHandler{geminiOAuthService: geminiOAuthService}
+}
+
+// GetCapabilities returns the Gemini OAuth configuration capabilities.
+// GET /api/v1/admin/gemini/oauth/capabilities
+func (h *GeminiOAuthHandler) GetCapabilities(c *gin.Context) {
+	cfg := h.geminiOAuthService.GetOAuthConfig()
+	response.Success(c, cfg)
+}
+
+type GeminiGenerateAuthURLRequest struct {
+	ProxyID   *int64 `json:"proxy_id"`
+	ProjectID string `json:"project_id"`
+	// OAuth 类型: "code_assist" (需要 project_id) 或 "ai_studio" (不需要 project_id)
+	// 默认为 "code_assist" 以保持向后兼容
+	OAuthType string `json:"oauth_type"`
+	// TierID is a user-selected tier to be used when auto detection is unavailable or fails.
+	TierID string `json:"tier_id"`
+}
+
+// GenerateAuthURL generates Google OAuth authorization URL for Gemini.
+// POST /api/v1/admin/gemini/oauth/auth-url
+func (h *GeminiOAuthHandler) GenerateAuthURL(c *gin.Context) {
+	var req GeminiGenerateAuthURLRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// 默认使用 code_assist 以保持向后兼容
+	oauthType := strings.TrimSpace(req.OAuthType)
+	if oauthType == "" {
+		oauthType = "code_assist"
+	}
+	if oauthType != "code_assist" && oauthType != "google_one" && oauthType != "ai_studio" {
+		response.BadRequest(c, "Invalid oauth_type: must be 'code_assist', 'google_one', or 'ai_studio'")
+		return
+	}
+
+	// Always pass the "hosted" callback URI; the OAuth service may override it depending on
+	// oauth_type and whether the built-in Gemini CLI OAuth client is used.
+	redirectURI := deriveGeminiRedirectURI(c)
+	result, err := h.geminiOAuthService.GenerateAuthURL(c.Request.Context(), req.ProxyID, redirectURI, req.ProjectID, oauthType, req.TierID)
+	if err != nil {
+		msg := err.Error()
+		// Treat missing/invalid OAuth client configuration as a user/config error.
+		if strings.Contains(msg, "OAuth client not configured") ||
+			strings.Contains(msg, "requires your own OAuth Client") ||
+			strings.Contains(msg, "requires a custom OAuth Client") ||
+			strings.Contains(msg, "GEMINI_CLI_OAUTH_CLIENT_SECRET_MISSING") ||
+			strings.Contains(msg, "built-in Gemini CLI OAuth client_secret is not configured") {
+			response.BadRequest(c, "Failed to generate auth URL: "+msg)
+			return
+		}
+		response.InternalError(c, "Failed to generate auth URL: "+msg)
+		return
+	}
+
+	response.Success(c, result)
+}
+
+type GeminiExchangeCodeRequest struct {
+	SessionID string `json:"session_id" binding:"required"`
+	State     string `json:"state" binding:"required"`
+	Code      string `json:"code" binding:"required"`
+	ProxyID   *int64 `json:"proxy_id"`
+	// OAuth 类型: "code_assist" 或 "ai_studio"，需要与 GenerateAuthURL 时的类型一致
+	OAuthType string `json:"oauth_type"`
+	// TierID is a user-selected tier to be used when auto detection is unavailable or fails.
+	// This field is optional; when omitted, the server uses the tier stored in the OAuth session.
+	TierID string `json:"tier_id"`
+}
+
+// ExchangeCode exchanges authorization code for tokens.
+// POST /api/v1/admin/gemini/oauth/exchange-code
+func (h *GeminiOAuthHandler) ExchangeCode(c *gin.Context) {
+	var req GeminiExchangeCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// 默认使用 code_assist 以保持向后兼容
+	oauthType := strings.TrimSpace(req.OAuthType)
+	if oauthType == "" {
+		oauthType = "code_assist"
+	}
+	if oauthType != "code_assist" && oauthType != "google_one" && oauthType != "ai_studio" {
+		response.BadRequest(c, "Invalid oauth_type: must be 'code_assist', 'google_one', or 'ai_studio'")
+		return
+	}
+
+	tokenInfo, err := h.geminiOAuthService.ExchangeCode(c.Request.Context(), &service.GeminiExchangeCodeInput{
+		SessionID: req.SessionID,
+		State:     req.State,
+		Code:      req.Code,
+		ProxyID:   req.ProxyID,
+		OAuthType: oauthType,
+		TierID:    req.TierID,
+	})
+	if err != nil {
+		response.BadRequest(c, "Failed to exchange code: "+err.Error())
+		return
+	}
+
+	response.Success(c, tokenInfo)
+}
+
+func deriveGeminiRedirectURI(c *gin.Context) string {
+	origin := strings.TrimSpace(c.GetHeader("Origin"))
+	if origin != "" {
+		return strings.TrimRight(origin, "/") + "/auth/callback"
+	}
+
+	scheme := "http"
+	if c.Request.TLS != nil {
+		scheme = "https"
+	}
+	if xfProto := strings.TrimSpace(c.GetHeader("X-Forwarded-Proto")); xfProto != "" {
+		scheme = strings.TrimSpace(strings.Split(xfProto, ",")[0])
+	}
+
+	host := strings.TrimSpace(c.Request.Host)
+	if xfHost := strings.TrimSpace(c.GetHeader("X-Forwarded-Host")); xfHost != "" {
+		host = strings.TrimSpace(strings.Split(xfHost, ",")[0])
+	}
+
+	return fmt.Sprintf("%s://%s/auth/callback", scheme, host)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/group_handler.go

@@ -0,0 +1,487 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// GroupHandler handles admin group management
+type GroupHandler struct {
+	adminService service.AdminService
+}
+
+type optionalLimitField struct {
+	set   bool
+	value *float64
+}
+
+func (f *optionalLimitField) UnmarshalJSON(data []byte) error {
+	f.set = true
+
+	trimmed := bytes.TrimSpace(data)
+	if bytes.Equal(trimmed, []byte("null")) {
+		f.value = nil
+		return nil
+	}
+
+	var number float64
+	if err := json.Unmarshal(trimmed, &number); err == nil {
+		f.value = &number
+		return nil
+	}
+
+	var text string
+	if err := json.Unmarshal(trimmed, &text); err == nil {
+		text = strings.TrimSpace(text)
+		if text == "" {
+			f.value = nil
+			return nil
+		}
+		number, err = strconv.ParseFloat(text, 64)
+		if err != nil {
+			return fmt.Errorf("invalid numeric limit value %q: %w", text, err)
+		}
+		f.value = &number
+		return nil
+	}
+
+	return fmt.Errorf("invalid limit value: %s", string(trimmed))
+}
+
+func (f optionalLimitField) ToServiceInput() *float64 {
+	if !f.set {
+		return nil
+	}
+	if f.value != nil {
+		return f.value
+	}
+	zero := 0.0
+	return &zero
+}
+
+// NewGroupHandler creates a new admin group handler
+func NewGroupHandler(adminService service.AdminService) *GroupHandler {
+	return &GroupHandler{
+		adminService: adminService,
+	}
+}
+
+// CreateGroupRequest represents create group request
+type CreateGroupRequest struct {
+	Name             string             `json:"name" binding:"required"`
+	Description      string             `json:"description"`
+	Platform         string             `json:"platform" binding:"omitempty,oneof=anthropic openai gemini antigravity sora"`
+	RateMultiplier   float64            `json:"rate_multiplier"`
+	IsExclusive      bool               `json:"is_exclusive"`
+	SubscriptionType string             `json:"subscription_type" binding:"omitempty,oneof=standard subscription"`
+	DailyLimitUSD    optionalLimitField `json:"daily_limit_usd"`
+	WeeklyLimitUSD   optionalLimitField `json:"weekly_limit_usd"`
+	MonthlyLimitUSD  optionalLimitField `json:"monthly_limit_usd"`
+	// 图片生成计费配置（antigravity 和 gemini 平台使用，负数表示清除配置）
+	ImagePrice1K                    *float64 `json:"image_price_1k"`
+	ImagePrice2K                    *float64 `json:"image_price_2k"`
+	ImagePrice4K                    *float64 `json:"image_price_4k"`
+	SoraImagePrice360               *float64 `json:"sora_image_price_360"`
+	SoraImagePrice540               *float64 `json:"sora_image_price_540"`
+	SoraVideoPricePerRequest        *float64 `json:"sora_video_price_per_request"`
+	SoraVideoPricePerRequestHD      *float64 `json:"sora_video_price_per_request_hd"`
+	ClaudeCodeOnly                  bool     `json:"claude_code_only"`
+	FallbackGroupID                 *int64   `json:"fallback_group_id"`
+	FallbackGroupIDOnInvalidRequest *int64   `json:"fallback_group_id_on_invalid_request"`
+	// 模型路由配置（仅 anthropic 平台使用）
+	ModelRouting        map[string][]int64 `json:"model_routing"`
+	ModelRoutingEnabled bool               `json:"model_routing_enabled"`
+	MCPXMLInject        *bool              `json:"mcp_xml_inject"`
+	// 支持的模型系列（仅 antigravity 平台使用）
+	SupportedModelScopes []string `json:"supported_model_scopes"`
+	// Sora 存储配额
+	SoraStorageQuotaBytes int64 `json:"sora_storage_quota_bytes"`
+	// OpenAI Messages 调度配置（仅 openai 平台使用）
+	AllowMessagesDispatch bool   `json:"allow_messages_dispatch"`
+	DefaultMappedModel    string `json:"default_mapped_model"`
+	// 从指定分组复制账号（创建后自动绑定）
+	CopyAccountsFromGroupIDs []int64 `json:"copy_accounts_from_group_ids"`
+}
+
+// UpdateGroupRequest represents update group request
+type UpdateGroupRequest struct {
+	Name             string             `json:"name"`
+	Description      string             `json:"description"`
+	Platform         string             `json:"platform" binding:"omitempty,oneof=anthropic openai gemini antigravity sora"`
+	RateMultiplier   *float64           `json:"rate_multiplier"`
+	IsExclusive      *bool              `json:"is_exclusive"`
+	Status           string             `json:"status" binding:"omitempty,oneof=active inactive"`
+	SubscriptionType string             `json:"subscription_type" binding:"omitempty,oneof=standard subscription"`
+	DailyLimitUSD    optionalLimitField `json:"daily_limit_usd"`
+	WeeklyLimitUSD   optionalLimitField `json:"weekly_limit_usd"`
+	MonthlyLimitUSD  optionalLimitField `json:"monthly_limit_usd"`
+	// 图片生成计费配置（antigravity 和 gemini 平台使用，负数表示清除配置）
+	ImagePrice1K                    *float64 `json:"image_price_1k"`
+	ImagePrice2K                    *float64 `json:"image_price_2k"`
+	ImagePrice4K                    *float64 `json:"image_price_4k"`
+	SoraImagePrice360               *float64 `json:"sora_image_price_360"`
+	SoraImagePrice540               *float64 `json:"sora_image_price_540"`
+	SoraVideoPricePerRequest        *float64 `json:"sora_video_price_per_request"`
+	SoraVideoPricePerRequestHD      *float64 `json:"sora_video_price_per_request_hd"`
+	ClaudeCodeOnly                  *bool    `json:"claude_code_only"`
+	FallbackGroupID                 *int64   `json:"fallback_group_id"`
+	FallbackGroupIDOnInvalidRequest *int64   `json:"fallback_group_id_on_invalid_request"`
+	// 模型路由配置（仅 anthropic 平台使用）
+	ModelRouting        map[string][]int64 `json:"model_routing"`
+	ModelRoutingEnabled *bool              `json:"model_routing_enabled"`
+	MCPXMLInject        *bool              `json:"mcp_xml_inject"`
+	// 支持的模型系列（仅 antigravity 平台使用）
+	SupportedModelScopes *[]string `json:"supported_model_scopes"`
+	// Sora 存储配额
+	SoraStorageQuotaBytes *int64 `json:"sora_storage_quota_bytes"`
+	// OpenAI Messages 调度配置（仅 openai 平台使用）
+	AllowMessagesDispatch *bool   `json:"allow_messages_dispatch"`
+	DefaultMappedModel    *string `json:"default_mapped_model"`
+	// 从指定分组复制账号（同步操作：先清空当前分组的账号绑定，再绑定源分组的账号）
+	CopyAccountsFromGroupIDs []int64 `json:"copy_accounts_from_group_ids"`
+}
+
+// List handles listing all groups with pagination
+// GET /api/v1/admin/groups
+func (h *GroupHandler) List(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+	platform := c.Query("platform")
+	status := c.Query("status")
+	search := c.Query("search")
+	// 标准化和验证 search 参数
+	search = strings.TrimSpace(search)
+	if len(search) > 100 {
+		search = search[:100]
+	}
+	isExclusiveStr := c.Query("is_exclusive")
+
+	var isExclusive *bool
+	if isExclusiveStr != "" {
+		val := isExclusiveStr == "true"
+		isExclusive = &val
+	}
+
+	groups, total, err := h.adminService.ListGroups(c.Request.Context(), page, pageSize, platform, status, search, isExclusive)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	outGroups := make([]dto.AdminGroup, 0, len(groups))
+	for i := range groups {
+		outGroups = append(outGroups, *dto.GroupFromServiceAdmin(&groups[i]))
+	}
+	response.Paginated(c, outGroups, total, page, pageSize)
+}
+
+// GetAll handles getting all active groups without pagination
+// GET /api/v1/admin/groups/all
+func (h *GroupHandler) GetAll(c *gin.Context) {
+	platform := c.Query("platform")
+
+	var groups []service.Group
+	var err error
+
+	if platform != "" {
+		groups, err = h.adminService.GetAllGroupsByPlatform(c.Request.Context(), platform)
+	} else {
+		groups, err = h.adminService.GetAllGroups(c.Request.Context())
+	}
+
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	outGroups := make([]dto.AdminGroup, 0, len(groups))
+	for i := range groups {
+		outGroups = append(outGroups, *dto.GroupFromServiceAdmin(&groups[i]))
+	}
+	response.Success(c, outGroups)
+}
+
+// GetByID handles getting a group by ID
+// GET /api/v1/admin/groups/:id
+func (h *GroupHandler) GetByID(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	group, err := h.adminService.GetGroup(c.Request.Context(), groupID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.GroupFromServiceAdmin(group))
+}
+
+// Create handles creating a new group
+// POST /api/v1/admin/groups
+func (h *GroupHandler) Create(c *gin.Context) {
+	var req CreateGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	group, err := h.adminService.CreateGroup(c.Request.Context(), &service.CreateGroupInput{
+		Name:                            req.Name,
+		Description:                     req.Description,
+		Platform:                        req.Platform,
+		RateMultiplier:                  req.RateMultiplier,
+		IsExclusive:                     req.IsExclusive,
+		SubscriptionType:                req.SubscriptionType,
+		DailyLimitUSD:                   req.DailyLimitUSD.ToServiceInput(),
+		WeeklyLimitUSD:                  req.WeeklyLimitUSD.ToServiceInput(),
+		MonthlyLimitUSD:                 req.MonthlyLimitUSD.ToServiceInput(),
+		ImagePrice1K:                    req.ImagePrice1K,
+		ImagePrice2K:                    req.ImagePrice2K,
+		ImagePrice4K:                    req.ImagePrice4K,
+		SoraImagePrice360:               req.SoraImagePrice360,
+		SoraImagePrice540:               req.SoraImagePrice540,
+		SoraVideoPricePerRequest:        req.SoraVideoPricePerRequest,
+		SoraVideoPricePerRequestHD:      req.SoraVideoPricePerRequestHD,
+		ClaudeCodeOnly:                  req.ClaudeCodeOnly,
+		FallbackGroupID:                 req.FallbackGroupID,
+		FallbackGroupIDOnInvalidRequest: req.FallbackGroupIDOnInvalidRequest,
+		ModelRouting:                    req.ModelRouting,
+		ModelRoutingEnabled:             req.ModelRoutingEnabled,
+		MCPXMLInject:                    req.MCPXMLInject,
+		SupportedModelScopes:            req.SupportedModelScopes,
+		SoraStorageQuotaBytes:           req.SoraStorageQuotaBytes,
+		AllowMessagesDispatch:           req.AllowMessagesDispatch,
+		DefaultMappedModel:              req.DefaultMappedModel,
+		CopyAccountsFromGroupIDs:        req.CopyAccountsFromGroupIDs,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.GroupFromServiceAdmin(group))
+}
+
+// Update handles updating a group
+// PUT /api/v1/admin/groups/:id
+func (h *GroupHandler) Update(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	var req UpdateGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	group, err := h.adminService.UpdateGroup(c.Request.Context(), groupID, &service.UpdateGroupInput{
+		Name:                            req.Name,
+		Description:                     req.Description,
+		Platform:                        req.Platform,
+		RateMultiplier:                  req.RateMultiplier,
+		IsExclusive:                     req.IsExclusive,
+		Status:                          req.Status,
+		SubscriptionType:                req.SubscriptionType,
+		DailyLimitUSD:                   req.DailyLimitUSD.ToServiceInput(),
+		WeeklyLimitUSD:                  req.WeeklyLimitUSD.ToServiceInput(),
+		MonthlyLimitUSD:                 req.MonthlyLimitUSD.ToServiceInput(),
+		ImagePrice1K:                    req.ImagePrice1K,
+		ImagePrice2K:                    req.ImagePrice2K,
+		ImagePrice4K:                    req.ImagePrice4K,
+		SoraImagePrice360:               req.SoraImagePrice360,
+		SoraImagePrice540:               req.SoraImagePrice540,
+		SoraVideoPricePerRequest:        req.SoraVideoPricePerRequest,
+		SoraVideoPricePerRequestHD:      req.SoraVideoPricePerRequestHD,
+		ClaudeCodeOnly:                  req.ClaudeCodeOnly,
+		FallbackGroupID:                 req.FallbackGroupID,
+		FallbackGroupIDOnInvalidRequest: req.FallbackGroupIDOnInvalidRequest,
+		ModelRouting:                    req.ModelRouting,
+		ModelRoutingEnabled:             req.ModelRoutingEnabled,
+		MCPXMLInject:                    req.MCPXMLInject,
+		SupportedModelScopes:            req.SupportedModelScopes,
+		SoraStorageQuotaBytes:           req.SoraStorageQuotaBytes,
+		AllowMessagesDispatch:           req.AllowMessagesDispatch,
+		DefaultMappedModel:              req.DefaultMappedModel,
+		CopyAccountsFromGroupIDs:        req.CopyAccountsFromGroupIDs,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.GroupFromServiceAdmin(group))
+}
+
+// Delete handles deleting a group
+// DELETE /api/v1/admin/groups/:id
+func (h *GroupHandler) Delete(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	err = h.adminService.DeleteGroup(c.Request.Context(), groupID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Group deleted successfully"})
+}
+
+// GetStats handles getting group statistics
+// GET /api/v1/admin/groups/:id/stats
+func (h *GroupHandler) GetStats(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	// Return mock data for now
+	response.Success(c, gin.H{
+		"total_api_keys":  0,
+		"active_api_keys": 0,
+		"total_requests":  0,
+		"total_cost":      0.0,
+	})
+	_ = groupID // TODO: implement actual stats
+}
+
+// GetGroupAPIKeys handles getting API keys in a group
+// GET /api/v1/admin/groups/:id/api-keys
+func (h *GroupHandler) GetGroupAPIKeys(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+
+	keys, total, err := h.adminService.GetGroupAPIKeys(c.Request.Context(), groupID, page, pageSize)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	outKeys := make([]dto.APIKey, 0, len(keys))
+	for i := range keys {
+		outKeys = append(outKeys, *dto.APIKeyFromService(&keys[i]))
+	}
+	response.Paginated(c, outKeys, total, page, pageSize)
+}
+
+// GetGroupRateMultipliers handles getting rate multipliers for users in a group
+// GET /api/v1/admin/groups/:id/rate-multipliers
+func (h *GroupHandler) GetGroupRateMultipliers(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	entries, err := h.adminService.GetGroupRateMultipliers(c.Request.Context(), groupID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	if entries == nil {
+		entries = []service.UserGroupRateEntry{}
+	}
+	response.Success(c, entries)
+}
+
+// ClearGroupRateMultipliers handles clearing all rate multipliers for a group
+// DELETE /api/v1/admin/groups/:id/rate-multipliers
+func (h *GroupHandler) ClearGroupRateMultipliers(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	if err := h.adminService.ClearGroupRateMultipliers(c.Request.Context(), groupID); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Rate multipliers cleared successfully"})
+}
+
+// BatchSetGroupRateMultipliersRequest represents batch set rate multipliers request
+type BatchSetGroupRateMultipliersRequest struct {
+	Entries []service.GroupRateMultiplierInput `json:"entries" binding:"required"`
+}
+
+// BatchSetGroupRateMultipliers handles batch setting rate multipliers for a group
+// PUT /api/v1/admin/groups/:id/rate-multipliers
+func (h *GroupHandler) BatchSetGroupRateMultipliers(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	var req BatchSetGroupRateMultipliersRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if err := h.adminService.BatchSetGroupRateMultipliers(c.Request.Context(), groupID, req.Entries); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Rate multipliers updated successfully"})
+}
+
+// UpdateSortOrderRequest represents the request to update group sort orders
+type UpdateSortOrderRequest struct {
+	Updates []struct {
+		ID        int64 `json:"id" binding:"required"`
+		SortOrder int   `json:"sort_order"`
+	} `json:"updates" binding:"required,min=1"`
+}
+
+// UpdateSortOrder handles updating group sort orders
+// PUT /api/v1/admin/groups/sort-order
+func (h *GroupHandler) UpdateSortOrder(c *gin.Context) {
+	var req UpdateSortOrderRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	updates := make([]service.GroupSortOrderUpdate, 0, len(req.Updates))
+	for _, u := range req.Updates {
+		updates = append(updates, service.GroupSortOrderUpdate{
+			ID:        u.ID,
+			SortOrder: u.SortOrder,
+		})
+	}
+
+	if err := h.adminService.UpdateGroupSortOrders(c.Request.Context(), updates); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Sort order updated successfully"})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/id_list_utils.go

@@ -0,0 +1,25 @@
+package admin
+
+import "sort"
+
+func normalizeInt64IDList(ids []int64) []int64 {
+	if len(ids) == 0 {
+		return nil
+	}
+
+	out := make([]int64, 0, len(ids))
+	seen := make(map[int64]struct{}, len(ids))
+	for _, id := range ids {
+		if id <= 0 {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		out = append(out, id)
+	}
+
+	sort.Slice(out, func(i, j int) bool { return out[i] < out[j] })
+	return out
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/id_list_utils_test.go

@@ -0,0 +1,57 @@
+//go:build unit
+
+package admin
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNormalizeInt64IDList(t *testing.T) {
+	tests := []struct {
+		name string
+		in   []int64
+		want []int64
+	}{
+		{"nil input", nil, nil},
+		{"empty input", []int64{}, nil},
+		{"single element", []int64{5}, []int64{5}},
+		{"already sorted unique", []int64{1, 2, 3}, []int64{1, 2, 3}},
+		{"duplicates removed", []int64{3, 1, 3, 2, 1}, []int64{1, 2, 3}},
+		{"zero filtered", []int64{0, 1, 2}, []int64{1, 2}},
+		{"negative filtered", []int64{-5, -1, 3}, []int64{3}},
+		{"all invalid", []int64{0, -1, -2}, []int64{}},
+		{"sorted output", []int64{9, 3, 7, 1}, []int64{1, 3, 7, 9}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := normalizeInt64IDList(tc.in)
+			if tc.want == nil {
+				require.Nil(t, got)
+			} else {
+				require.Equal(t, tc.want, got)
+			}
+		})
+	}
+}
+
+func TestBuildAccountTodayStatsBatchCacheKey(t *testing.T) {
+	tests := []struct {
+		name string
+		ids  []int64
+		want string
+	}{
+		{"empty", nil, "accounts_today_stats_empty"},
+		{"single", []int64{42}, "accounts_today_stats:42"},
+		{"multiple", []int64{1, 2, 3}, "accounts_today_stats:1,2,3"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := buildAccountTodayStatsBatchCacheKey(tc.ids)
+			require.Equal(t, tc.want, got)
+		})
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/idempotency_helper.go

@@ -0,0 +1,115 @@
+package admin
+
+import (
+	"context"
+	"strconv"
+	"time"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+type idempotencyStoreUnavailableMode int
+
+const (
+	idempotencyStoreUnavailableFailClose idempotencyStoreUnavailableMode = iota
+	idempotencyStoreUnavailableFailOpen
+)
+
+func executeAdminIdempotent(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	execute func(context.Context) (any, error),
+) (*service.IdempotencyExecuteResult, error) {
+	coordinator := service.DefaultIdempotencyCoordinator()
+	if coordinator == nil {
+		data, err := execute(c.Request.Context())
+		if err != nil {
+			return nil, err
+		}
+		return &service.IdempotencyExecuteResult{Data: data}, nil
+	}
+
+	actorScope := "admin:0"
+	if subject, ok := middleware2.GetAuthSubjectFromContext(c); ok {
+		actorScope = "admin:" + strconv.FormatInt(subject.UserID, 10)
+	}
+
+	return coordinator.Execute(c.Request.Context(), service.IdempotencyExecuteOptions{
+		Scope:          scope,
+		ActorScope:     actorScope,
+		Method:         c.Request.Method,
+		Route:          c.FullPath(),
+		IdempotencyKey: c.GetHeader("Idempotency-Key"),
+		Payload:        payload,
+		RequireKey:     true,
+		TTL:            ttl,
+	}, execute)
+}
+
+func executeAdminIdempotentJSON(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	execute func(context.Context) (any, error),
+) {
+	executeAdminIdempotentJSONWithMode(c, scope, payload, ttl, idempotencyStoreUnavailableFailClose, execute)
+}
+
+func executeAdminIdempotentJSONFailOpenOnStoreUnavailable(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	execute func(context.Context) (any, error),
+) {
+	executeAdminIdempotentJSONWithMode(c, scope, payload, ttl, idempotencyStoreUnavailableFailOpen, execute)
+}
+
+func executeAdminIdempotentJSONWithMode(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	mode idempotencyStoreUnavailableMode,
+	execute func(context.Context) (any, error),
+) {
+	result, err := executeAdminIdempotent(c, scope, payload, ttl, execute)
+	if err != nil {
+		if infraerrors.Code(err) == infraerrors.Code(service.ErrIdempotencyStoreUnavail) {
+			strategy := "fail_close"
+			if mode == idempotencyStoreUnavailableFailOpen {
+				strategy = "fail_open"
+			}
+			service.RecordIdempotencyStoreUnavailable(c.FullPath(), scope, "handler_"+strategy)
+			logger.LegacyPrintf("handler.idempotency", "[Idempotency] store unavailable: method=%s route=%s scope=%s strategy=%s", c.Request.Method, c.FullPath(), scope, strategy)
+			if mode == idempotencyStoreUnavailableFailOpen {
+				data, fallbackErr := execute(c.Request.Context())
+				if fallbackErr != nil {
+					response.ErrorFrom(c, fallbackErr)
+					return
+				}
+				c.Header("X-Idempotency-Degraded", "store-unavailable")
+				response.Success(c, data)
+				return
+			}
+		}
+		if retryAfter := service.RetryAfterSecondsFromError(err); retryAfter > 0 {
+			c.Header("Retry-After", strconv.Itoa(retryAfter))
+		}
+		response.ErrorFrom(c, err)
+		return
+	}
+	if result != nil && result.Replayed {
+		c.Header("X-Idempotency-Replayed", "true")
+	}
+	response.Success(c, result.Data)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/idempotency_helper_test.go

@@ -0,0 +1,285 @@
+package admin
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type storeUnavailableRepoStub struct{}
+
+func (storeUnavailableRepoStub) CreateProcessing(context.Context, *service.IdempotencyRecord) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) GetByScopeAndKeyHash(context.Context, string, string) (*service.IdempotencyRecord, error) {
+	return nil, errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) TryReclaim(context.Context, int64, string, time.Time, time.Time, time.Time) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) ExtendProcessingLock(context.Context, int64, string, time.Time, time.Time) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) MarkSucceeded(context.Context, int64, int, string, time.Time) error {
+	return errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) MarkFailedRetryable(context.Context, int64, string, time.Time, time.Time) error {
+	return errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) DeleteExpired(context.Context, time.Time, int) (int64, error) {
+	return 0, errors.New("store unavailable")
+}
+
+func TestExecuteAdminIdempotentJSONFailCloseOnStoreUnavailable(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	service.SetDefaultIdempotencyCoordinator(service.NewIdempotencyCoordinator(storeUnavailableRepoStub{}, service.DefaultIdempotencyConfig()))
+	t.Cleanup(func() {
+		service.SetDefaultIdempotencyCoordinator(nil)
+	})
+
+	var executed int
+	router := gin.New()
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeAdminIdempotentJSON(c, "admin.test.high", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed++
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Idempotency-Key", "test-key-1")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusServiceUnavailable, rec.Code)
+	require.Equal(t, 0, executed, "fail-close should block business execution when idempotency store is unavailable")
+}
+
+func TestExecuteAdminIdempotentJSONFailOpenOnStoreUnavailable(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	service.SetDefaultIdempotencyCoordinator(service.NewIdempotencyCoordinator(storeUnavailableRepoStub{}, service.DefaultIdempotencyConfig()))
+	t.Cleanup(func() {
+		service.SetDefaultIdempotencyCoordinator(nil)
+	})
+
+	var executed int
+	router := gin.New()
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeAdminIdempotentJSONFailOpenOnStoreUnavailable(c, "admin.test.medium", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed++
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Idempotency-Key", "test-key-2")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.Equal(t, "store-unavailable", rec.Header().Get("X-Idempotency-Degraded"))
+	require.Equal(t, 1, executed, "fail-open strategy should allow semantic idempotent path to continue")
+}
+
+type memoryIdempotencyRepoStub struct {
+	mu     sync.Mutex
+	nextID int64
+	data   map[string]*service.IdempotencyRecord
+}
+
+func newMemoryIdempotencyRepoStub() *memoryIdempotencyRepoStub {
+	return &memoryIdempotencyRepoStub{
+		nextID: 1,
+		data:   make(map[string]*service.IdempotencyRecord),
+	}
+}
+
+func (r *memoryIdempotencyRepoStub) key(scope, keyHash string) string {
+	return scope + "|" + keyHash
+}
+
+func (r *memoryIdempotencyRepoStub) clone(in *service.IdempotencyRecord) *service.IdempotencyRecord {
+	if in == nil {
+		return nil
+	}
+	out := *in
+	if in.LockedUntil != nil {
+		v := *in.LockedUntil
+		out.LockedUntil = &v
+	}
+	if in.ResponseBody != nil {
+		v := *in.ResponseBody
+		out.ResponseBody = &v
+	}
+	if in.ResponseStatus != nil {
+		v := *in.ResponseStatus
+		out.ResponseStatus = &v
+	}
+	if in.ErrorReason != nil {
+		v := *in.ErrorReason
+		out.ErrorReason = &v
+	}
+	return &out
+}
+
+func (r *memoryIdempotencyRepoStub) CreateProcessing(_ context.Context, record *service.IdempotencyRecord) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	k := r.key(record.Scope, record.IdempotencyKeyHash)
+	if _, ok := r.data[k]; ok {
+		return false, nil
+	}
+	cp := r.clone(record)
+	cp.ID = r.nextID
+	r.nextID++
+	r.data[k] = cp
+	record.ID = cp.ID
+	return true, nil
+}
+
+func (r *memoryIdempotencyRepoStub) GetByScopeAndKeyHash(_ context.Context, scope, keyHash string) (*service.IdempotencyRecord, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.clone(r.data[r.key(scope, keyHash)]), nil
+}
+
+func (r *memoryIdempotencyRepoStub) TryReclaim(_ context.Context, id int64, fromStatus string, now, newLockedUntil, newExpiresAt time.Time) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		if rec.Status != fromStatus {
+			return false, nil
+		}
+		if rec.LockedUntil != nil && rec.LockedUntil.After(now) {
+			return false, nil
+		}
+		rec.Status = service.IdempotencyStatusProcessing
+		rec.LockedUntil = &newLockedUntil
+		rec.ExpiresAt = newExpiresAt
+		rec.ErrorReason = nil
+		return true, nil
+	}
+	return false, nil
+}
+
+func (r *memoryIdempotencyRepoStub) ExtendProcessingLock(_ context.Context, id int64, requestFingerprint string, newLockedUntil, newExpiresAt time.Time) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		if rec.Status != service.IdempotencyStatusProcessing || rec.RequestFingerprint != requestFingerprint {
+			return false, nil
+		}
+		rec.LockedUntil = &newLockedUntil
+		rec.ExpiresAt = newExpiresAt
+		return true, nil
+	}
+	return false, nil
+}
+
+func (r *memoryIdempotencyRepoStub) MarkSucceeded(_ context.Context, id int64, responseStatus int, responseBody string, expiresAt time.Time) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		rec.Status = service.IdempotencyStatusSucceeded
+		rec.LockedUntil = nil
+		rec.ExpiresAt = expiresAt
+		rec.ResponseStatus = &responseStatus
+		rec.ResponseBody = &responseBody
+		rec.ErrorReason = nil
+		return nil
+	}
+	return nil
+}
+
+func (r *memoryIdempotencyRepoStub) MarkFailedRetryable(_ context.Context, id int64, errorReason string, lockedUntil, expiresAt time.Time) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		rec.Status = service.IdempotencyStatusFailedRetryable
+		rec.LockedUntil = &lockedUntil
+		rec.ExpiresAt = expiresAt
+		rec.ErrorReason = &errorReason
+		return nil
+	}
+	return nil
+}
+
+func (r *memoryIdempotencyRepoStub) DeleteExpired(_ context.Context, _ time.Time, _ int) (int64, error) {
+	return 0, nil
+}
+
+func TestExecuteAdminIdempotentJSONConcurrentRetryOnlyOneSideEffect(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	repo := newMemoryIdempotencyRepoStub()
+	cfg := service.DefaultIdempotencyConfig()
+	cfg.ProcessingTimeout = 2 * time.Second
+	service.SetDefaultIdempotencyCoordinator(service.NewIdempotencyCoordinator(repo, cfg))
+	t.Cleanup(func() {
+		service.SetDefaultIdempotencyCoordinator(nil)
+	})
+
+	var executed atomic.Int32
+	router := gin.New()
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeAdminIdempotentJSON(c, "admin.test.concurrent", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed.Add(1)
+			time.Sleep(120 * time.Millisecond)
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	call := func() (int, http.Header) {
+		req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Idempotency-Key", "same-key")
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+		return rec.Code, rec.Header()
+	}
+
+	var status1, status2 int
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() {
+		defer wg.Done()
+		status1, _ = call()
+	}()
+	go func() {
+		defer wg.Done()
+		status2, _ = call()
+	}()
+	wg.Wait()
+
+	require.Contains(t, []int{http.StatusOK, http.StatusConflict}, status1)
+	require.Contains(t, []int{http.StatusOK, http.StatusConflict}, status2)
+	require.Equal(t, int32(1), executed.Load(), "same idempotency key should execute side-effect only once")
+
+	status3, headers3 := call()
+	require.Equal(t, http.StatusOK, status3)
+	require.Equal(t, "true", headers3.Get("X-Idempotency-Replayed"))
+	require.Equal(t, int32(1), executed.Load())
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/openai_oauth_handler.go

@@ -0,0 +1,304 @@
+package admin
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// OpenAIOAuthHandler handles OpenAI OAuth-related operations
+type OpenAIOAuthHandler struct {
+	openaiOAuthService *service.OpenAIOAuthService
+	adminService       service.AdminService
+}
+
+func oauthPlatformFromPath(c *gin.Context) string {
+	if strings.Contains(c.FullPath(), "/admin/sora/") {
+		return service.PlatformSora
+	}
+	return service.PlatformOpenAI
+}
+
+// NewOpenAIOAuthHandler creates a new OpenAI OAuth handler
+func NewOpenAIOAuthHandler(openaiOAuthService *service.OpenAIOAuthService, adminService service.AdminService) *OpenAIOAuthHandler {
+	return &OpenAIOAuthHandler{
+		openaiOAuthService: openaiOAuthService,
+		adminService:       adminService,
+	}
+}
+
+// OpenAIGenerateAuthURLRequest represents the request for generating OpenAI auth URL
+type OpenAIGenerateAuthURLRequest struct {
+	ProxyID     *int64 `json:"proxy_id"`
+	RedirectURI string `json:"redirect_uri"`
+}
+
+// GenerateAuthURL generates OpenAI OAuth authorization URL
+// POST /api/v1/admin/openai/generate-auth-url
+func (h *OpenAIOAuthHandler) GenerateAuthURL(c *gin.Context) {
+	var req OpenAIGenerateAuthURLRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		// Allow empty body
+		req = OpenAIGenerateAuthURLRequest{}
+	}
+
+	result, err := h.openaiOAuthService.GenerateAuthURL(
+		c.Request.Context(),
+		req.ProxyID,
+		req.RedirectURI,
+		oauthPlatformFromPath(c),
+	)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, result)
+}
+
+// OpenAIExchangeCodeRequest represents the request for exchanging OpenAI auth code
+type OpenAIExchangeCodeRequest struct {
+	SessionID   string `json:"session_id" binding:"required"`
+	Code        string `json:"code" binding:"required"`
+	State       string `json:"state" binding:"required"`
+	RedirectURI string `json:"redirect_uri"`
+	ProxyID     *int64 `json:"proxy_id"`
+}
+
+// ExchangeCode exchanges OpenAI authorization code for tokens
+// POST /api/v1/admin/openai/exchange-code
+func (h *OpenAIOAuthHandler) ExchangeCode(c *gin.Context) {
+	var req OpenAIExchangeCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	tokenInfo, err := h.openaiOAuthService.ExchangeCode(c.Request.Context(), &service.OpenAIExchangeCodeInput{
+		SessionID:   req.SessionID,
+		Code:        req.Code,
+		State:       req.State,
+		RedirectURI: req.RedirectURI,
+		ProxyID:     req.ProxyID,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, tokenInfo)
+}
+
+// OpenAIRefreshTokenRequest represents the request for refreshing OpenAI token
+type OpenAIRefreshTokenRequest struct {
+	RefreshToken string `json:"refresh_token"`
+	RT           string `json:"rt"`
+	ClientID     string `json:"client_id"`
+	ProxyID      *int64 `json:"proxy_id"`
+}
+
+// RefreshToken refreshes an OpenAI OAuth token
+// POST /api/v1/admin/openai/refresh-token
+// POST /api/v1/admin/sora/rt2at
+func (h *OpenAIOAuthHandler) RefreshToken(c *gin.Context) {
+	var req OpenAIRefreshTokenRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	refreshToken := strings.TrimSpace(req.RefreshToken)
+	if refreshToken == "" {
+		refreshToken = strings.TrimSpace(req.RT)
+	}
+	if refreshToken == "" {
+		response.BadRequest(c, "refresh_token is required")
+		return
+	}
+
+	var proxyURL string
+	if req.ProxyID != nil {
+		proxy, err := h.adminService.GetProxy(c.Request.Context(), *req.ProxyID)
+		if err == nil && proxy != nil {
+			proxyURL = proxy.URL()
+		}
+	}
+
+	// 未指定 client_id 时，根据请求路径平台自动设置默认值，避免 repository 层盲猜
+	clientID := strings.TrimSpace(req.ClientID)
+	if clientID == "" {
+		platform := oauthPlatformFromPath(c)
+		clientID, _ = openai.OAuthClientConfigByPlatform(platform)
+	}
+
+	tokenInfo, err := h.openaiOAuthService.RefreshTokenWithClientID(c.Request.Context(), refreshToken, proxyURL, clientID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, tokenInfo)
+}
+
+// ExchangeSoraSessionToken exchanges Sora session token to access token
+// POST /api/v1/admin/sora/st2at
+func (h *OpenAIOAuthHandler) ExchangeSoraSessionToken(c *gin.Context) {
+	var req struct {
+		SessionToken string `json:"session_token"`
+		ST           string `json:"st"`
+		ProxyID      *int64 `json:"proxy_id"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	sessionToken := strings.TrimSpace(req.SessionToken)
+	if sessionToken == "" {
+		sessionToken = strings.TrimSpace(req.ST)
+	}
+	if sessionToken == "" {
+		response.BadRequest(c, "session_token is required")
+		return
+	}
+
+	tokenInfo, err := h.openaiOAuthService.ExchangeSoraSessionToken(c.Request.Context(), sessionToken, req.ProxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, tokenInfo)
+}
+
+// RefreshAccountToken refreshes token for a specific OpenAI/Sora account
+// POST /api/v1/admin/openai/accounts/:id/refresh
+// POST /api/v1/admin/sora/accounts/:id/refresh
+func (h *OpenAIOAuthHandler) RefreshAccountToken(c *gin.Context) {
+	accountID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid account ID")
+		return
+	}
+
+	// Get account
+	account, err := h.adminService.GetAccount(c.Request.Context(), accountID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	platform := oauthPlatformFromPath(c)
+	if account.Platform != platform {
+		response.BadRequest(c, "Account platform does not match OAuth endpoint")
+		return
+	}
+
+	// Only refresh OAuth-based accounts
+	if !account.IsOAuth() {
+		response.BadRequest(c, "Cannot refresh non-OAuth account credentials")
+		return
+	}
+
+	// Use OpenAI OAuth service to refresh token
+	tokenInfo, err := h.openaiOAuthService.RefreshAccountToken(c.Request.Context(), account)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Build new credentials from token info
+	newCredentials := h.openaiOAuthService.BuildAccountCredentials(tokenInfo)
+
+	// Preserve non-token settings from existing credentials
+	for k, v := range account.Credentials {
+		if _, exists := newCredentials[k]; !exists {
+			newCredentials[k] = v
+		}
+	}
+
+	updatedAccount, err := h.adminService.UpdateAccount(c.Request.Context(), accountID, &service.UpdateAccountInput{
+		Credentials: newCredentials,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.AccountFromService(updatedAccount))
+}
+
+// CreateAccountFromOAuth creates a new OpenAI/Sora OAuth account from token info
+// POST /api/v1/admin/openai/create-from-oauth
+// POST /api/v1/admin/sora/create-from-oauth
+func (h *OpenAIOAuthHandler) CreateAccountFromOAuth(c *gin.Context) {
+	var req struct {
+		SessionID   string  `json:"session_id" binding:"required"`
+		Code        string  `json:"code" binding:"required"`
+		State       string  `json:"state" binding:"required"`
+		RedirectURI string  `json:"redirect_uri"`
+		ProxyID     *int64  `json:"proxy_id"`
+		Name        string  `json:"name"`
+		Concurrency int     `json:"concurrency"`
+		Priority    int     `json:"priority"`
+		GroupIDs    []int64 `json:"group_ids"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Exchange code for tokens
+	tokenInfo, err := h.openaiOAuthService.ExchangeCode(c.Request.Context(), &service.OpenAIExchangeCodeInput{
+		SessionID:   req.SessionID,
+		Code:        req.Code,
+		State:       req.State,
+		RedirectURI: req.RedirectURI,
+		ProxyID:     req.ProxyID,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Build credentials from token info
+	credentials := h.openaiOAuthService.BuildAccountCredentials(tokenInfo)
+
+	platform := oauthPlatformFromPath(c)
+
+	// Use email as default name if not provided
+	name := req.Name
+	if name == "" && tokenInfo.Email != "" {
+		name = tokenInfo.Email
+	}
+	if name == "" {
+		if platform == service.PlatformSora {
+			name = "Sora OAuth Account"
+		} else {
+			name = "OpenAI OAuth Account"
+		}
+	}
+
+	// Create account
+	account, err := h.adminService.CreateAccount(c.Request.Context(), &service.CreateAccountInput{
+		Name:        name,
+		Platform:    platform,
+		Type:        "oauth",
+		Credentials: credentials,
+		Extra:       nil,
+		ProxyID:     req.ProxyID,
+		Concurrency: req.Concurrency,
+		Priority:    req.Priority,
+		GroupIDs:    req.GroupIDs,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.AccountFromService(account))
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_alerts_handler.go

@@ -0,0 +1,612 @@
+package admin
+
+import (
+	"encoding/json"
+	"fmt"
+	"math"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/gin-gonic/gin/binding"
+)
+
+var validOpsAlertMetricTypes = []string{
+	"success_rate",
+	"error_rate",
+	"upstream_error_rate",
+	"cpu_usage_percent",
+	"memory_usage_percent",
+	"concurrency_queue_depth",
+	"group_available_accounts",
+	"group_available_ratio",
+	"group_rate_limit_ratio",
+	"account_rate_limited_count",
+	"account_error_count",
+	"account_error_ratio",
+	"overload_account_count",
+}
+
+var validOpsAlertMetricTypeSet = func() map[string]struct{} {
+	set := make(map[string]struct{}, len(validOpsAlertMetricTypes))
+	for _, v := range validOpsAlertMetricTypes {
+		set[v] = struct{}{}
+	}
+	return set
+}()
+
+var validOpsAlertOperators = []string{">", "<", ">=", "<=", "==", "!="}
+
+var validOpsAlertOperatorSet = func() map[string]struct{} {
+	set := make(map[string]struct{}, len(validOpsAlertOperators))
+	for _, v := range validOpsAlertOperators {
+		set[v] = struct{}{}
+	}
+	return set
+}()
+
+var validOpsAlertSeverities = []string{"P0", "P1", "P2", "P3"}
+
+var validOpsAlertSeveritySet = func() map[string]struct{} {
+	set := make(map[string]struct{}, len(validOpsAlertSeverities))
+	for _, v := range validOpsAlertSeverities {
+		set[v] = struct{}{}
+	}
+	return set
+}()
+
+type opsAlertRuleValidatedInput struct {
+	Name       string
+	MetricType string
+	Operator   string
+	Threshold  float64
+
+	Severity string
+
+	WindowMinutes    int
+	SustainedMinutes int
+	CooldownMinutes  int
+
+	Enabled     bool
+	NotifyEmail bool
+
+	WindowProvided    bool
+	SustainedProvided bool
+	CooldownProvided  bool
+	SeverityProvided  bool
+	EnabledProvided   bool
+	NotifyProvided    bool
+}
+
+func isPercentOrRateMetric(metricType string) bool {
+	switch metricType {
+	case "success_rate",
+		"error_rate",
+		"upstream_error_rate",
+		"cpu_usage_percent",
+		"memory_usage_percent",
+		"group_available_ratio",
+		"group_rate_limit_ratio",
+		"account_error_ratio":
+		return true
+	default:
+		return false
+	}
+}
+
+func validateOpsAlertRulePayload(raw map[string]json.RawMessage) (*opsAlertRuleValidatedInput, error) {
+	if raw == nil {
+		return nil, fmt.Errorf("invalid request body")
+	}
+
+	requiredFields := []string{"name", "metric_type", "operator", "threshold"}
+	for _, field := range requiredFields {
+		if _, ok := raw[field]; !ok {
+			return nil, fmt.Errorf("%s is required", field)
+		}
+	}
+
+	var name string
+	if err := json.Unmarshal(raw["name"], &name); err != nil || strings.TrimSpace(name) == "" {
+		return nil, fmt.Errorf("name is required")
+	}
+	name = strings.TrimSpace(name)
+
+	var metricType string
+	if err := json.Unmarshal(raw["metric_type"], &metricType); err != nil || strings.TrimSpace(metricType) == "" {
+		return nil, fmt.Errorf("metric_type is required")
+	}
+	metricType = strings.TrimSpace(metricType)
+	if _, ok := validOpsAlertMetricTypeSet[metricType]; !ok {
+		return nil, fmt.Errorf("metric_type must be one of: %s", strings.Join(validOpsAlertMetricTypes, ", "))
+	}
+
+	var operator string
+	if err := json.Unmarshal(raw["operator"], &operator); err != nil || strings.TrimSpace(operator) == "" {
+		return nil, fmt.Errorf("operator is required")
+	}
+	operator = strings.TrimSpace(operator)
+	if _, ok := validOpsAlertOperatorSet[operator]; !ok {
+		return nil, fmt.Errorf("operator must be one of: %s", strings.Join(validOpsAlertOperators, ", "))
+	}
+
+	var threshold float64
+	if err := json.Unmarshal(raw["threshold"], &threshold); err != nil {
+		return nil, fmt.Errorf("threshold must be a number")
+	}
+	if math.IsNaN(threshold) || math.IsInf(threshold, 0) {
+		return nil, fmt.Errorf("threshold must be a finite number")
+	}
+	if isPercentOrRateMetric(metricType) {
+		if threshold < 0 || threshold > 100 {
+			return nil, fmt.Errorf("threshold must be between 0 and 100 for metric_type %s", metricType)
+		}
+	} else if threshold < 0 {
+		return nil, fmt.Errorf("threshold must be >= 0")
+	}
+
+	validated := &opsAlertRuleValidatedInput{
+		Name:       name,
+		MetricType: metricType,
+		Operator:   operator,
+		Threshold:  threshold,
+	}
+
+	if v, ok := raw["severity"]; ok {
+		validated.SeverityProvided = true
+		var sev string
+		if err := json.Unmarshal(v, &sev); err != nil {
+			return nil, fmt.Errorf("severity must be a string")
+		}
+		sev = strings.ToUpper(strings.TrimSpace(sev))
+		if sev != "" {
+			if _, ok := validOpsAlertSeveritySet[sev]; !ok {
+				return nil, fmt.Errorf("severity must be one of: %s", strings.Join(validOpsAlertSeverities, ", "))
+			}
+			validated.Severity = sev
+		}
+	}
+	if validated.Severity == "" {
+		validated.Severity = "P2"
+	}
+
+	if v, ok := raw["enabled"]; ok {
+		validated.EnabledProvided = true
+		if err := json.Unmarshal(v, &validated.Enabled); err != nil {
+			return nil, fmt.Errorf("enabled must be a boolean")
+		}
+	} else {
+		validated.Enabled = true
+	}
+
+	if v, ok := raw["notify_email"]; ok {
+		validated.NotifyProvided = true
+		if err := json.Unmarshal(v, &validated.NotifyEmail); err != nil {
+			return nil, fmt.Errorf("notify_email must be a boolean")
+		}
+	} else {
+		validated.NotifyEmail = true
+	}
+
+	if v, ok := raw["window_minutes"]; ok {
+		validated.WindowProvided = true
+		if err := json.Unmarshal(v, &validated.WindowMinutes); err != nil {
+			return nil, fmt.Errorf("window_minutes must be an integer")
+		}
+		switch validated.WindowMinutes {
+		case 1, 5, 60:
+		default:
+			return nil, fmt.Errorf("window_minutes must be one of: 1, 5, 60")
+		}
+	} else {
+		validated.WindowMinutes = 1
+	}
+
+	if v, ok := raw["sustained_minutes"]; ok {
+		validated.SustainedProvided = true
+		if err := json.Unmarshal(v, &validated.SustainedMinutes); err != nil {
+			return nil, fmt.Errorf("sustained_minutes must be an integer")
+		}
+		if validated.SustainedMinutes < 1 || validated.SustainedMinutes > 1440 {
+			return nil, fmt.Errorf("sustained_minutes must be between 1 and 1440")
+		}
+	} else {
+		validated.SustainedMinutes = 1
+	}
+
+	if v, ok := raw["cooldown_minutes"]; ok {
+		validated.CooldownProvided = true
+		if err := json.Unmarshal(v, &validated.CooldownMinutes); err != nil {
+			return nil, fmt.Errorf("cooldown_minutes must be an integer")
+		}
+		if validated.CooldownMinutes < 0 || validated.CooldownMinutes > 1440 {
+			return nil, fmt.Errorf("cooldown_minutes must be between 0 and 1440")
+		}
+	} else {
+		validated.CooldownMinutes = 0
+	}
+
+	return validated, nil
+}
+
+// ListAlertRules returns all ops alert rules.
+// GET /api/v1/admin/ops/alert-rules
+func (h *OpsHandler) ListAlertRules(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	rules, err := h.opsService.ListAlertRules(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, rules)
+}
+
+// CreateAlertRule creates an ops alert rule.
+// POST /api/v1/admin/ops/alert-rules
+func (h *OpsHandler) CreateAlertRule(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var raw map[string]json.RawMessage
+	if err := c.ShouldBindBodyWith(&raw, binding.JSON); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+	validated, err := validateOpsAlertRulePayload(raw)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	var rule service.OpsAlertRule
+	if err := c.ShouldBindBodyWith(&rule, binding.JSON); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	rule.Name = validated.Name
+	rule.MetricType = validated.MetricType
+	rule.Operator = validated.Operator
+	rule.Threshold = validated.Threshold
+	rule.WindowMinutes = validated.WindowMinutes
+	rule.SustainedMinutes = validated.SustainedMinutes
+	rule.CooldownMinutes = validated.CooldownMinutes
+	rule.Severity = validated.Severity
+	rule.Enabled = validated.Enabled
+	rule.NotifyEmail = validated.NotifyEmail
+
+	created, err := h.opsService.CreateAlertRule(c.Request.Context(), &rule)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, created)
+}
+
+// UpdateAlertRule updates an existing ops alert rule.
+// PUT /api/v1/admin/ops/alert-rules/:id
+func (h *OpsHandler) UpdateAlertRule(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid rule ID")
+		return
+	}
+
+	var raw map[string]json.RawMessage
+	if err := c.ShouldBindBodyWith(&raw, binding.JSON); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+	validated, err := validateOpsAlertRulePayload(raw)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	var rule service.OpsAlertRule
+	if err := c.ShouldBindBodyWith(&rule, binding.JSON); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	rule.ID = id
+	rule.Name = validated.Name
+	rule.MetricType = validated.MetricType
+	rule.Operator = validated.Operator
+	rule.Threshold = validated.Threshold
+	rule.WindowMinutes = validated.WindowMinutes
+	rule.SustainedMinutes = validated.SustainedMinutes
+	rule.CooldownMinutes = validated.CooldownMinutes
+	rule.Severity = validated.Severity
+	rule.Enabled = validated.Enabled
+	rule.NotifyEmail = validated.NotifyEmail
+
+	updated, err := h.opsService.UpdateAlertRule(c.Request.Context(), &rule)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, updated)
+}
+
+// DeleteAlertRule deletes an ops alert rule.
+// DELETE /api/v1/admin/ops/alert-rules/:id
+func (h *OpsHandler) DeleteAlertRule(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid rule ID")
+		return
+	}
+
+	if err := h.opsService.DeleteAlertRule(c.Request.Context(), id); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"deleted": true})
+}
+
+// GetAlertEvent returns a single ops alert event.
+// GET /api/v1/admin/ops/alert-events/:id
+func (h *OpsHandler) GetAlertEvent(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid event ID")
+		return
+	}
+
+	ev, err := h.opsService.GetAlertEventByID(c.Request.Context(), id)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, ev)
+}
+
+// UpdateAlertEventStatus updates an ops alert event status.
+// PUT /api/v1/admin/ops/alert-events/:id/status
+func (h *OpsHandler) UpdateAlertEventStatus(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid event ID")
+		return
+	}
+
+	var payload struct {
+		Status string `json:"status"`
+	}
+	if err := c.ShouldBindJSON(&payload); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+	payload.Status = strings.TrimSpace(payload.Status)
+	if payload.Status == "" {
+		response.BadRequest(c, "Invalid status")
+		return
+	}
+	if payload.Status != service.OpsAlertStatusResolved && payload.Status != service.OpsAlertStatusManualResolved {
+		response.BadRequest(c, "Invalid status")
+		return
+	}
+
+	var resolvedAt *time.Time
+	if payload.Status == service.OpsAlertStatusResolved || payload.Status == service.OpsAlertStatusManualResolved {
+		now := time.Now().UTC()
+		resolvedAt = &now
+	}
+	if err := h.opsService.UpdateAlertEventStatus(c.Request.Context(), id, payload.Status, resolvedAt); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"updated": true})
+}
+
+// ListAlertEvents lists recent ops alert events.
+// GET /api/v1/admin/ops/alert-events
+// CreateAlertSilence creates a scoped silence for ops alerts.
+// POST /api/v1/admin/ops/alert-silences
+func (h *OpsHandler) CreateAlertSilence(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var payload struct {
+		RuleID   int64   `json:"rule_id"`
+		Platform string  `json:"platform"`
+		GroupID  *int64  `json:"group_id"`
+		Region   *string `json:"region"`
+		Until    string  `json:"until"`
+		Reason   string  `json:"reason"`
+	}
+	if err := c.ShouldBindJSON(&payload); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+	until, err := time.Parse(time.RFC3339, strings.TrimSpace(payload.Until))
+	if err != nil {
+		response.BadRequest(c, "Invalid until")
+		return
+	}
+
+	createdBy := (*int64)(nil)
+	if subject, ok := middleware.GetAuthSubjectFromContext(c); ok {
+		uid := subject.UserID
+		createdBy = &uid
+	}
+
+	silence := &service.OpsAlertSilence{
+		RuleID:    payload.RuleID,
+		Platform:  strings.TrimSpace(payload.Platform),
+		GroupID:   payload.GroupID,
+		Region:    payload.Region,
+		Until:     until,
+		Reason:    strings.TrimSpace(payload.Reason),
+		CreatedBy: createdBy,
+	}
+
+	created, err := h.opsService.CreateAlertSilence(c.Request.Context(), silence)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, created)
+}
+
+func (h *OpsHandler) ListAlertEvents(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	limit := 20
+	if raw := strings.TrimSpace(c.Query("limit")); raw != "" {
+		n, err := strconv.Atoi(raw)
+		if err != nil || n <= 0 {
+			response.BadRequest(c, "Invalid limit")
+			return
+		}
+		limit = n
+	}
+
+	filter := &service.OpsAlertEventFilter{
+		Limit:    limit,
+		Status:   strings.TrimSpace(c.Query("status")),
+		Severity: strings.TrimSpace(c.Query("severity")),
+	}
+
+	if v := strings.TrimSpace(c.Query("email_sent")); v != "" {
+		vv := strings.ToLower(v)
+		switch vv {
+		case "true", "1":
+			b := true
+			filter.EmailSent = &b
+		case "false", "0":
+			b := false
+			filter.EmailSent = &b
+		default:
+			response.BadRequest(c, "Invalid email_sent")
+			return
+		}
+	}
+
+	// Cursor pagination: both params must be provided together.
+	rawTS := strings.TrimSpace(c.Query("before_fired_at"))
+	rawID := strings.TrimSpace(c.Query("before_id"))
+	if (rawTS == "") != (rawID == "") {
+		response.BadRequest(c, "before_fired_at and before_id must be provided together")
+		return
+	}
+	if rawTS != "" {
+		ts, err := time.Parse(time.RFC3339Nano, rawTS)
+		if err != nil {
+			if t2, err2 := time.Parse(time.RFC3339, rawTS); err2 == nil {
+				ts = t2
+			} else {
+				response.BadRequest(c, "Invalid before_fired_at")
+				return
+			}
+		}
+		filter.BeforeFiredAt = &ts
+	}
+	if rawID != "" {
+		id, err := strconv.ParseInt(rawID, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid before_id")
+			return
+		}
+		filter.BeforeID = &id
+	}
+
+	// Optional global filter support (platform/group/time range).
+	if platform := strings.TrimSpace(c.Query("platform")); platform != "" {
+		filter.Platform = platform
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+	if startTime, endTime, err := parseOpsTimeRange(c, "24h"); err == nil {
+		// Only apply when explicitly provided to avoid surprising default narrowing.
+		if strings.TrimSpace(c.Query("start_time")) != "" || strings.TrimSpace(c.Query("end_time")) != "" || strings.TrimSpace(c.Query("time_range")) != "" {
+			filter.StartTime = &startTime
+			filter.EndTime = &endTime
+		}
+	} else {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	events, err := h.opsService.ListAlertEvents(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, events)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_dashboard_handler.go

@@ -0,0 +1,353 @@
+package admin
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+// GetDashboardOverview returns vNext ops dashboard overview (raw path).
+// GET /api/v1/admin/ops/dashboard/overview
+func (h *OpsHandler) GetDashboardOverview(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsDashboardFilter{
+		StartTime: startTime,
+		EndTime:   endTime,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+		QueryMode: parseOpsQueryMode(c),
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+
+	data, err := h.opsService.GetDashboardOverview(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+// GetDashboardThroughputTrend returns throughput time series (raw path).
+// GET /api/v1/admin/ops/dashboard/throughput-trend
+func (h *OpsHandler) GetDashboardThroughputTrend(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsDashboardFilter{
+		StartTime: startTime,
+		EndTime:   endTime,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+		QueryMode: parseOpsQueryMode(c),
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+
+	bucketSeconds := pickThroughputBucketSeconds(endTime.Sub(startTime))
+	data, err := h.opsService.GetThroughputTrend(c.Request.Context(), filter, bucketSeconds)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+// GetDashboardLatencyHistogram returns the latency distribution histogram (success requests).
+// GET /api/v1/admin/ops/dashboard/latency-histogram
+func (h *OpsHandler) GetDashboardLatencyHistogram(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsDashboardFilter{
+		StartTime: startTime,
+		EndTime:   endTime,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+		QueryMode: parseOpsQueryMode(c),
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+
+	data, err := h.opsService.GetLatencyHistogram(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+// GetDashboardErrorTrend returns error counts time series (raw path).
+// GET /api/v1/admin/ops/dashboard/error-trend
+func (h *OpsHandler) GetDashboardErrorTrend(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsDashboardFilter{
+		StartTime: startTime,
+		EndTime:   endTime,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+		QueryMode: parseOpsQueryMode(c),
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+
+	bucketSeconds := pickThroughputBucketSeconds(endTime.Sub(startTime))
+	data, err := h.opsService.GetErrorTrend(c.Request.Context(), filter, bucketSeconds)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+// GetDashboardErrorDistribution returns error distribution by status code (raw path).
+// GET /api/v1/admin/ops/dashboard/error-distribution
+func (h *OpsHandler) GetDashboardErrorDistribution(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsDashboardFilter{
+		StartTime: startTime,
+		EndTime:   endTime,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+		QueryMode: parseOpsQueryMode(c),
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+
+	data, err := h.opsService.GetErrorDistribution(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+// GetDashboardOpenAITokenStats returns OpenAI token efficiency stats grouped by model.
+// GET /api/v1/admin/ops/dashboard/openai-token-stats
+func (h *OpsHandler) GetDashboardOpenAITokenStats(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	data, err := h.opsService.GetOpenAITokenStats(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func parseOpsOpenAITokenStatsFilter(c *gin.Context) (*service.OpsOpenAITokenStatsFilter, error) {
+	if c == nil {
+		return nil, fmt.Errorf("invalid request")
+	}
+
+	timeRange := strings.TrimSpace(c.Query("time_range"))
+	if timeRange == "" {
+		timeRange = "30d"
+	}
+	dur, ok := parseOpsOpenAITokenStatsDuration(timeRange)
+	if !ok {
+		return nil, fmt.Errorf("invalid time_range")
+	}
+	end := time.Now().UTC()
+	start := end.Add(-dur)
+
+	filter := &service.OpsOpenAITokenStatsFilter{
+		TimeRange: timeRange,
+		StartTime: start,
+		EndTime:   end,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+	}
+
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			return nil, fmt.Errorf("invalid group_id")
+		}
+		filter.GroupID = &id
+	}
+
+	topNRaw := strings.TrimSpace(c.Query("top_n"))
+	pageRaw := strings.TrimSpace(c.Query("page"))
+	pageSizeRaw := strings.TrimSpace(c.Query("page_size"))
+	if topNRaw != "" && (pageRaw != "" || pageSizeRaw != "") {
+		return nil, fmt.Errorf("invalid query: top_n cannot be used with page/page_size")
+	}
+
+	if topNRaw != "" {
+		topN, err := strconv.Atoi(topNRaw)
+		if err != nil || topN < 1 || topN > 100 {
+			return nil, fmt.Errorf("invalid top_n")
+		}
+		filter.TopN = topN
+		return filter, nil
+	}
+
+	filter.Page = 1
+	filter.PageSize = 20
+	if pageRaw != "" {
+		page, err := strconv.Atoi(pageRaw)
+		if err != nil || page < 1 {
+			return nil, fmt.Errorf("invalid page")
+		}
+		filter.Page = page
+	}
+	if pageSizeRaw != "" {
+		pageSize, err := strconv.Atoi(pageSizeRaw)
+		if err != nil || pageSize < 1 || pageSize > 100 {
+			return nil, fmt.Errorf("invalid page_size")
+		}
+		filter.PageSize = pageSize
+	}
+	return filter, nil
+}
+
+func parseOpsOpenAITokenStatsDuration(v string) (time.Duration, bool) {
+	switch strings.TrimSpace(v) {
+	case "30m":
+		return 30 * time.Minute, true
+	case "1h":
+		return time.Hour, true
+	case "1d":
+		return 24 * time.Hour, true
+	case "15d":
+		return 15 * 24 * time.Hour, true
+	case "30d":
+		return 30 * 24 * time.Hour, true
+	default:
+		return 0, false
+	}
+}
+
+func pickThroughputBucketSeconds(window time.Duration) int {
+	// Keep buckets predictable and avoid huge responses.
+	switch {
+	case window <= 2*time.Hour:
+		return 60
+	case window <= 24*time.Hour:
+		return 300
+	default:
+		return 3600
+	}
+}
+
+func parseOpsQueryMode(c *gin.Context) service.OpsQueryMode {
+	if c == nil {
+		return ""
+	}
+	raw := strings.TrimSpace(c.Query("mode"))
+	if raw == "" {
+		// Empty means "use server default" (DB setting ops_query_mode_default).
+		return ""
+	}
+	return service.ParseOpsQueryMode(raw)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_handler.go

@@ -0,0 +1,925 @@
+package admin
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type OpsHandler struct {
+	opsService *service.OpsService
+}
+
+// GetErrorLogByID returns ops error log detail.
+// GET /api/v1/admin/ops/errors/:id
+func (h *OpsHandler) GetErrorLogByID(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	idStr := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid error id")
+		return
+	}
+
+	detail, err := h.opsService.GetErrorLogByID(c.Request.Context(), id)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, detail)
+}
+
+const (
+	opsListViewErrors   = "errors"
+	opsListViewExcluded = "excluded"
+	opsListViewAll      = "all"
+)
+
+func parseOpsViewParam(c *gin.Context) string {
+	if c == nil {
+		return ""
+	}
+	v := strings.ToLower(strings.TrimSpace(c.Query("view")))
+	switch v {
+	case "", opsListViewErrors:
+		return opsListViewErrors
+	case opsListViewExcluded:
+		return opsListViewExcluded
+	case opsListViewAll:
+		return opsListViewAll
+	default:
+		return opsListViewErrors
+	}
+}
+
+func NewOpsHandler(opsService *service.OpsService) *OpsHandler {
+	return &OpsHandler{opsService: opsService}
+}
+
+// GetErrorLogs lists ops error logs.
+// GET /api/v1/admin/ops/errors
+func (h *OpsHandler) GetErrorLogs(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	// Ops list can be larger than standard admin tables.
+	if pageSize > 500 {
+		pageSize = 500
+	}
+
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsErrorLogFilter{Page: page, PageSize: pageSize}
+
+	if !startTime.IsZero() {
+		filter.StartTime = &startTime
+	}
+	if !endTime.IsZero() {
+		filter.EndTime = &endTime
+	}
+	filter.View = parseOpsViewParam(c)
+	filter.Phase = strings.TrimSpace(c.Query("phase"))
+	filter.Owner = strings.TrimSpace(c.Query("error_owner"))
+	filter.Source = strings.TrimSpace(c.Query("error_source"))
+	filter.Query = strings.TrimSpace(c.Query("q"))
+	filter.UserQuery = strings.TrimSpace(c.Query("user_query"))
+
+	// Force request errors: client-visible status >= 400.
+	// buildOpsErrorLogsWhere already applies this for non-upstream phase.
+	if strings.EqualFold(strings.TrimSpace(filter.Phase), "upstream") {
+		filter.Phase = ""
+	}
+
+	if platform := strings.TrimSpace(c.Query("platform")); platform != "" {
+		filter.Platform = platform
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+	if v := strings.TrimSpace(c.Query("account_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		filter.AccountID = &id
+	}
+
+	if v := strings.TrimSpace(c.Query("resolved")); v != "" {
+		switch strings.ToLower(v) {
+		case "1", "true", "yes":
+			b := true
+			filter.Resolved = &b
+		case "0", "false", "no":
+			b := false
+			filter.Resolved = &b
+		default:
+			response.BadRequest(c, "Invalid resolved")
+			return
+		}
+	}
+	if statusCodesStr := strings.TrimSpace(c.Query("status_codes")); statusCodesStr != "" {
+		parts := strings.Split(statusCodesStr, ",")
+		out := make([]int, 0, len(parts))
+		for _, part := range parts {
+			p := strings.TrimSpace(part)
+			if p == "" {
+				continue
+			}
+			n, err := strconv.Atoi(p)
+			if err != nil || n < 0 {
+				response.BadRequest(c, "Invalid status_codes")
+				return
+			}
+			out = append(out, n)
+		}
+		filter.StatusCodes = out
+	}
+
+	result, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Paginated(c, result.Errors, int64(result.Total), result.Page, result.PageSize)
+}
+
+// ListRequestErrors lists client-visible request errors.
+// GET /api/v1/admin/ops/request-errors
+func (h *OpsHandler) ListRequestErrors(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	if pageSize > 500 {
+		pageSize = 500
+	}
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsErrorLogFilter{Page: page, PageSize: pageSize}
+	if !startTime.IsZero() {
+		filter.StartTime = &startTime
+	}
+	if !endTime.IsZero() {
+		filter.EndTime = &endTime
+	}
+	filter.View = parseOpsViewParam(c)
+	filter.Phase = strings.TrimSpace(c.Query("phase"))
+	filter.Owner = strings.TrimSpace(c.Query("error_owner"))
+	filter.Source = strings.TrimSpace(c.Query("error_source"))
+	filter.Query = strings.TrimSpace(c.Query("q"))
+	filter.UserQuery = strings.TrimSpace(c.Query("user_query"))
+
+	// Force request errors: client-visible status >= 400.
+	// buildOpsErrorLogsWhere already applies this for non-upstream phase.
+	if strings.EqualFold(strings.TrimSpace(filter.Phase), "upstream") {
+		filter.Phase = ""
+	}
+
+	if platform := strings.TrimSpace(c.Query("platform")); platform != "" {
+		filter.Platform = platform
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+	if v := strings.TrimSpace(c.Query("account_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		filter.AccountID = &id
+	}
+
+	if v := strings.TrimSpace(c.Query("resolved")); v != "" {
+		switch strings.ToLower(v) {
+		case "1", "true", "yes":
+			b := true
+			filter.Resolved = &b
+		case "0", "false", "no":
+			b := false
+			filter.Resolved = &b
+		default:
+			response.BadRequest(c, "Invalid resolved")
+			return
+		}
+	}
+	if statusCodesStr := strings.TrimSpace(c.Query("status_codes")); statusCodesStr != "" {
+		parts := strings.Split(statusCodesStr, ",")
+		out := make([]int, 0, len(parts))
+		for _, part := range parts {
+			p := strings.TrimSpace(part)
+			if p == "" {
+				continue
+			}
+			n, err := strconv.Atoi(p)
+			if err != nil || n < 0 {
+				response.BadRequest(c, "Invalid status_codes")
+				return
+			}
+			out = append(out, n)
+		}
+		filter.StatusCodes = out
+	}
+
+	result, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Paginated(c, result.Errors, int64(result.Total), result.Page, result.PageSize)
+}
+
+// GetRequestError returns request error detail.
+// GET /api/v1/admin/ops/request-errors/:id
+func (h *OpsHandler) GetRequestError(c *gin.Context) {
+	// same storage; just proxy to existing detail
+	h.GetErrorLogByID(c)
+}
+
+// ListRequestErrorUpstreamErrors lists upstream error logs correlated to a request error.
+// GET /api/v1/admin/ops/request-errors/:id/upstream-errors
+func (h *OpsHandler) ListRequestErrorUpstreamErrors(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	idStr := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid error id")
+		return
+	}
+
+	// Load request error to get correlation keys.
+	detail, err := h.opsService.GetErrorLogByID(c.Request.Context(), id)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Correlate by request_id/client_request_id.
+	requestID := strings.TrimSpace(detail.RequestID)
+	clientRequestID := strings.TrimSpace(detail.ClientRequestID)
+	if requestID == "" && clientRequestID == "" {
+		response.Paginated(c, []*service.OpsErrorLog{}, 0, 1, 10)
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	if pageSize > 500 {
+		pageSize = 500
+	}
+
+	// Keep correlation window wide enough so linked upstream errors
+	// are discoverable even when UI defaults to 1h elsewhere.
+	startTime, endTime, err := parseOpsTimeRange(c, "30d")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsErrorLogFilter{Page: page, PageSize: pageSize}
+	if !startTime.IsZero() {
+		filter.StartTime = &startTime
+	}
+	if !endTime.IsZero() {
+		filter.EndTime = &endTime
+	}
+	filter.View = "all"
+	filter.Phase = "upstream"
+	filter.Owner = "provider"
+	filter.Source = strings.TrimSpace(c.Query("error_source"))
+	filter.Query = strings.TrimSpace(c.Query("q"))
+
+	if platform := strings.TrimSpace(c.Query("platform")); platform != "" {
+		filter.Platform = platform
+	}
+
+	// Prefer exact match on request_id; if missing, fall back to client_request_id.
+	if requestID != "" {
+		filter.RequestID = requestID
+	} else {
+		filter.ClientRequestID = clientRequestID
+	}
+
+	result, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// If client asks for details, expand each upstream error log to include upstream response fields.
+	includeDetail := strings.TrimSpace(c.Query("include_detail"))
+	if includeDetail == "1" || strings.EqualFold(includeDetail, "true") || strings.EqualFold(includeDetail, "yes") {
+		details := make([]*service.OpsErrorLogDetail, 0, len(result.Errors))
+		for _, item := range result.Errors {
+			if item == nil {
+				continue
+			}
+			d, err := h.opsService.GetErrorLogByID(c.Request.Context(), item.ID)
+			if err != nil || d == nil {
+				continue
+			}
+			details = append(details, d)
+		}
+		response.Paginated(c, details, int64(result.Total), result.Page, result.PageSize)
+		return
+	}
+
+	response.Paginated(c, result.Errors, int64(result.Total), result.Page, result.PageSize)
+}
+
+// RetryRequestErrorClient retries the client request based on stored request body.
+// POST /api/v1/admin/ops/request-errors/:id/retry-client
+func (h *OpsHandler) RetryRequestErrorClient(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	idStr := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid error id")
+		return
+	}
+
+	result, err := h.opsService.RetryError(c.Request.Context(), subject.UserID, id, service.OpsRetryModeClient, nil)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, result)
+}
+
+// RetryRequestErrorUpstreamEvent retries a specific upstream attempt using captured upstream_request_body.
+// POST /api/v1/admin/ops/request-errors/:id/upstream-errors/:idx/retry
+func (h *OpsHandler) RetryRequestErrorUpstreamEvent(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	idStr := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid error id")
+		return
+	}
+
+	idxStr := strings.TrimSpace(c.Param("idx"))
+	idx, err := strconv.Atoi(idxStr)
+	if err != nil || idx < 0 {
+		response.BadRequest(c, "Invalid upstream idx")
+		return
+	}
+
+	result, err := h.opsService.RetryUpstreamEvent(c.Request.Context(), subject.UserID, id, idx)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, result)
+}
+
+// ResolveRequestError toggles resolved status.
+// PUT /api/v1/admin/ops/request-errors/:id/resolve
+func (h *OpsHandler) ResolveRequestError(c *gin.Context) {
+	h.UpdateErrorResolution(c)
+}
+
+// ListUpstreamErrors lists independent upstream errors.
+// GET /api/v1/admin/ops/upstream-errors
+func (h *OpsHandler) ListUpstreamErrors(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	if pageSize > 500 {
+		pageSize = 500
+	}
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsErrorLogFilter{Page: page, PageSize: pageSize}
+	if !startTime.IsZero() {
+		filter.StartTime = &startTime
+	}
+	if !endTime.IsZero() {
+		filter.EndTime = &endTime
+	}
+
+	filter.View = parseOpsViewParam(c)
+	filter.Phase = "upstream"
+	filter.Owner = "provider"
+	filter.Source = strings.TrimSpace(c.Query("error_source"))
+	filter.Query = strings.TrimSpace(c.Query("q"))
+
+	if platform := strings.TrimSpace(c.Query("platform")); platform != "" {
+		filter.Platform = platform
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+	if v := strings.TrimSpace(c.Query("account_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		filter.AccountID = &id
+	}
+
+	if v := strings.TrimSpace(c.Query("resolved")); v != "" {
+		switch strings.ToLower(v) {
+		case "1", "true", "yes":
+			b := true
+			filter.Resolved = &b
+		case "0", "false", "no":
+			b := false
+			filter.Resolved = &b
+		default:
+			response.BadRequest(c, "Invalid resolved")
+			return
+		}
+	}
+	if statusCodesStr := strings.TrimSpace(c.Query("status_codes")); statusCodesStr != "" {
+		parts := strings.Split(statusCodesStr, ",")
+		out := make([]int, 0, len(parts))
+		for _, part := range parts {
+			p := strings.TrimSpace(part)
+			if p == "" {
+				continue
+			}
+			n, err := strconv.Atoi(p)
+			if err != nil || n < 0 {
+				response.BadRequest(c, "Invalid status_codes")
+				return
+			}
+			out = append(out, n)
+		}
+		filter.StatusCodes = out
+	}
+
+	result, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Paginated(c, result.Errors, int64(result.Total), result.Page, result.PageSize)
+}
+
+// GetUpstreamError returns upstream error detail.
+// GET /api/v1/admin/ops/upstream-errors/:id
+func (h *OpsHandler) GetUpstreamError(c *gin.Context) {
+	h.GetErrorLogByID(c)
+}
+
+// RetryUpstreamError retries upstream error using the original account_id.
+// POST /api/v1/admin/ops/upstream-errors/:id/retry
+func (h *OpsHandler) RetryUpstreamError(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	idStr := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid error id")
+		return
+	}
+
+	result, err := h.opsService.RetryError(c.Request.Context(), subject.UserID, id, service.OpsRetryModeUpstream, nil)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, result)
+}
+
+// ResolveUpstreamError toggles resolved status.
+// PUT /api/v1/admin/ops/upstream-errors/:id/resolve
+func (h *OpsHandler) ResolveUpstreamError(c *gin.Context) {
+	h.UpdateErrorResolution(c)
+}
+
+// ==================== Existing endpoints ====================
+
+// ListRequestDetails returns a request-level list (success + error) for drill-down.
+// GET /api/v1/admin/ops/requests
+func (h *OpsHandler) ListRequestDetails(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	if pageSize > 100 {
+		pageSize = 100
+	}
+
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsRequestDetailFilter{
+		Page:      page,
+		PageSize:  pageSize,
+		StartTime: &startTime,
+		EndTime:   &endTime,
+	}
+
+	filter.Kind = strings.TrimSpace(c.Query("kind"))
+	filter.Platform = strings.TrimSpace(c.Query("platform"))
+	filter.Model = strings.TrimSpace(c.Query("model"))
+	filter.RequestID = strings.TrimSpace(c.Query("request_id"))
+	filter.Query = strings.TrimSpace(c.Query("q"))
+	filter.Sort = strings.TrimSpace(c.Query("sort"))
+
+	if v := strings.TrimSpace(c.Query("user_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid user_id")
+			return
+		}
+		filter.UserID = &id
+	}
+	if v := strings.TrimSpace(c.Query("api_key_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid api_key_id")
+			return
+		}
+		filter.APIKeyID = &id
+	}
+	if v := strings.TrimSpace(c.Query("account_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		filter.AccountID = &id
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+
+	if v := strings.TrimSpace(c.Query("min_duration_ms")); v != "" {
+		parsed, err := strconv.Atoi(v)
+		if err != nil || parsed < 0 {
+			response.BadRequest(c, "Invalid min_duration_ms")
+			return
+		}
+		filter.MinDurationMs = &parsed
+	}
+	if v := strings.TrimSpace(c.Query("max_duration_ms")); v != "" {
+		parsed, err := strconv.Atoi(v)
+		if err != nil || parsed < 0 {
+			response.BadRequest(c, "Invalid max_duration_ms")
+			return
+		}
+		filter.MaxDurationMs = &parsed
+	}
+
+	out, err := h.opsService.ListRequestDetails(c.Request.Context(), filter)
+	if err != nil {
+		// Invalid sort/kind/platform etc should be a bad request; keep it simple.
+		if strings.Contains(strings.ToLower(err.Error()), "invalid") {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		response.Error(c, http.StatusInternalServerError, "Failed to list request details")
+		return
+	}
+
+	response.Paginated(c, out.Items, out.Total, out.Page, out.PageSize)
+}
+
+type opsRetryRequest struct {
+	Mode            string `json:"mode"`
+	PinnedAccountID *int64 `json:"pinned_account_id"`
+	Force           bool   `json:"force"`
+}
+
+type opsResolveRequest struct {
+	Resolved bool `json:"resolved"`
+}
+
+// RetryErrorRequest retries a failed request using stored request_body.
+// POST /api/v1/admin/ops/errors/:id/retry
+func (h *OpsHandler) RetryErrorRequest(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	idStr := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid error id")
+		return
+	}
+
+	req := opsRetryRequest{Mode: service.OpsRetryModeClient}
+	if err := c.ShouldBindJSON(&req); err != nil && !errors.Is(err, io.EOF) {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	if strings.TrimSpace(req.Mode) == "" {
+		req.Mode = service.OpsRetryModeClient
+	}
+
+	// Force flag is currently a UI-level acknowledgement. Server may still enforce safety constraints.
+	_ = req.Force
+
+	// Legacy endpoint safety: only allow retrying the client request here.
+	// Upstream retries must go through the split endpoints.
+	if strings.EqualFold(strings.TrimSpace(req.Mode), service.OpsRetryModeUpstream) {
+		response.BadRequest(c, "upstream retry is not supported on this endpoint")
+		return
+	}
+
+	result, err := h.opsService.RetryError(c.Request.Context(), subject.UserID, id, req.Mode, req.PinnedAccountID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, result)
+}
+
+// ListRetryAttempts lists retry attempts for an error log.
+// GET /api/v1/admin/ops/errors/:id/retries
+func (h *OpsHandler) ListRetryAttempts(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	idStr := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid error id")
+		return
+	}
+
+	limit := 50
+	if v := strings.TrimSpace(c.Query("limit")); v != "" {
+		n, err := strconv.Atoi(v)
+		if err != nil || n <= 0 {
+			response.BadRequest(c, "Invalid limit")
+			return
+		}
+		limit = n
+	}
+
+	items, err := h.opsService.ListRetryAttemptsByErrorID(c.Request.Context(), id, limit)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, items)
+}
+
+// UpdateErrorResolution allows manual resolve/unresolve.
+// PUT /api/v1/admin/ops/errors/:id/resolve
+func (h *OpsHandler) UpdateErrorResolution(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	idStr := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || id <= 0 {
+		response.BadRequest(c, "Invalid error id")
+		return
+	}
+
+	var req opsResolveRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	uid := subject.UserID
+	if err := h.opsService.UpdateErrorResolution(c.Request.Context(), id, req.Resolved, &uid, nil); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"ok": true})
+}
+
+func parseOpsTimeRange(c *gin.Context, defaultRange string) (time.Time, time.Time, error) {
+	startStr := strings.TrimSpace(c.Query("start_time"))
+	endStr := strings.TrimSpace(c.Query("end_time"))
+
+	parseTS := func(s string) (time.Time, error) {
+		if s == "" {
+			return time.Time{}, nil
+		}
+		if t, err := time.Parse(time.RFC3339Nano, s); err == nil {
+			return t, nil
+		}
+		return time.Parse(time.RFC3339, s)
+	}
+
+	start, err := parseTS(startStr)
+	if err != nil {
+		return time.Time{}, time.Time{}, err
+	}
+	end, err := parseTS(endStr)
+	if err != nil {
+		return time.Time{}, time.Time{}, err
+	}
+
+	// start/end explicitly provided (even partially)
+	if startStr != "" || endStr != "" {
+		if end.IsZero() {
+			end = time.Now()
+		}
+		if start.IsZero() {
+			dur, _ := parseOpsDuration(defaultRange)
+			start = end.Add(-dur)
+		}
+		if start.After(end) {
+			return time.Time{}, time.Time{}, fmt.Errorf("invalid time range: start_time must be <= end_time")
+		}
+		if end.Sub(start) > 30*24*time.Hour {
+			return time.Time{}, time.Time{}, fmt.Errorf("invalid time range: max window is 30 days")
+		}
+		return start, end, nil
+	}
+
+	// time_range fallback
+	tr := strings.TrimSpace(c.Query("time_range"))
+	if tr == "" {
+		tr = defaultRange
+	}
+	dur, ok := parseOpsDuration(tr)
+	if !ok {
+		dur, _ = parseOpsDuration(defaultRange)
+	}
+
+	end = time.Now()
+	start = end.Add(-dur)
+	if end.Sub(start) > 30*24*time.Hour {
+		return time.Time{}, time.Time{}, fmt.Errorf("invalid time range: max window is 30 days")
+	}
+	return start, end, nil
+}
+
+func parseOpsDuration(v string) (time.Duration, bool) {
+	switch strings.TrimSpace(v) {
+	case "5m":
+		return 5 * time.Minute, true
+	case "30m":
+		return 30 * time.Minute, true
+	case "1h":
+		return time.Hour, true
+	case "6h":
+		return 6 * time.Hour, true
+	case "24h":
+		return 24 * time.Hour, true
+	case "7d":
+		return 7 * 24 * time.Hour, true
+	case "30d":
+		return 30 * 24 * time.Hour, true
+	default:
+		return 0, false
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_realtime_handler.go

@@ -0,0 +1,250 @@
+package admin
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+// GetConcurrencyStats returns real-time concurrency usage aggregated by platform/group/account.
+// GET /api/v1/admin/ops/concurrency
+func (h *OpsHandler) GetConcurrencyStats(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	if !h.opsService.IsRealtimeMonitoringEnabled(c.Request.Context()) {
+		response.Success(c, gin.H{
+			"enabled":   false,
+			"platform":  map[string]*service.PlatformConcurrencyInfo{},
+			"group":     map[int64]*service.GroupConcurrencyInfo{},
+			"account":   map[int64]*service.AccountConcurrencyInfo{},
+			"timestamp": time.Now().UTC(),
+		})
+		return
+	}
+
+	platformFilter := strings.TrimSpace(c.Query("platform"))
+	var groupID *int64
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		groupID = &id
+	}
+
+	platform, group, account, collectedAt, err := h.opsService.GetConcurrencyStats(c.Request.Context(), platformFilter, groupID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	payload := gin.H{
+		"enabled":  true,
+		"platform": platform,
+		"group":    group,
+		"account":  account,
+	}
+	if collectedAt != nil {
+		payload["timestamp"] = collectedAt.UTC()
+	}
+	response.Success(c, payload)
+}
+
+// GetUserConcurrencyStats returns real-time concurrency usage for all active users.
+// GET /api/v1/admin/ops/user-concurrency
+func (h *OpsHandler) GetUserConcurrencyStats(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	if !h.opsService.IsRealtimeMonitoringEnabled(c.Request.Context()) {
+		response.Success(c, gin.H{
+			"enabled":   false,
+			"user":      map[int64]*service.UserConcurrencyInfo{},
+			"timestamp": time.Now().UTC(),
+		})
+		return
+	}
+
+	users, collectedAt, err := h.opsService.GetUserConcurrencyStats(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	payload := gin.H{
+		"enabled": true,
+		"user":    users,
+	}
+	if collectedAt != nil {
+		payload["timestamp"] = collectedAt.UTC()
+	}
+	response.Success(c, payload)
+}
+
+// GetAccountAvailability returns account availability statistics.
+// GET /api/v1/admin/ops/account-availability
+//
+// Query params:
+// - platform: optional
+// - group_id: optional
+func (h *OpsHandler) GetAccountAvailability(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	if !h.opsService.IsRealtimeMonitoringEnabled(c.Request.Context()) {
+		response.Success(c, gin.H{
+			"enabled":   false,
+			"platform":  map[string]*service.PlatformAvailability{},
+			"group":     map[int64]*service.GroupAvailability{},
+			"account":   map[int64]*service.AccountAvailability{},
+			"timestamp": time.Now().UTC(),
+		})
+		return
+	}
+
+	platform := strings.TrimSpace(c.Query("platform"))
+	var groupID *int64
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		groupID = &id
+	}
+
+	platformStats, groupStats, accountStats, collectedAt, err := h.opsService.GetAccountAvailabilityStats(c.Request.Context(), platform, groupID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	payload := gin.H{
+		"enabled":  true,
+		"platform": platformStats,
+		"group":    groupStats,
+		"account":  accountStats,
+	}
+	if collectedAt != nil {
+		payload["timestamp"] = collectedAt.UTC()
+	}
+	response.Success(c, payload)
+}
+
+func parseOpsRealtimeWindow(v string) (time.Duration, string, bool) {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case "", "1min", "1m":
+		return 1 * time.Minute, "1min", true
+	case "5min", "5m":
+		return 5 * time.Minute, "5min", true
+	case "30min", "30m":
+		return 30 * time.Minute, "30min", true
+	case "1h", "60m", "60min":
+		return 1 * time.Hour, "1h", true
+	default:
+		return 0, "", false
+	}
+}
+
+// GetRealtimeTrafficSummary returns QPS/TPS current/peak/avg for the selected window.
+// GET /api/v1/admin/ops/realtime-traffic
+//
+// Query params:
+// - window: 1min|5min|30min|1h (default: 1min)
+// - platform: optional
+// - group_id: optional
+func (h *OpsHandler) GetRealtimeTrafficSummary(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	windowDur, windowLabel, ok := parseOpsRealtimeWindow(c.Query("window"))
+	if !ok {
+		response.BadRequest(c, "Invalid window")
+		return
+	}
+
+	platform := strings.TrimSpace(c.Query("platform"))
+	var groupID *int64
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		groupID = &id
+	}
+
+	endTime := time.Now().UTC()
+	startTime := endTime.Add(-windowDur)
+
+	if !h.opsService.IsRealtimeMonitoringEnabled(c.Request.Context()) {
+		disabledSummary := &service.OpsRealtimeTrafficSummary{
+			Window:    windowLabel,
+			StartTime: startTime,
+			EndTime:   endTime,
+			Platform:  platform,
+			GroupID:   groupID,
+			QPS:       service.OpsRateSummary{},
+			TPS:       service.OpsRateSummary{},
+		}
+		response.Success(c, gin.H{
+			"enabled":   false,
+			"summary":   disabledSummary,
+			"timestamp": endTime,
+		})
+		return
+	}
+
+	filter := &service.OpsDashboardFilter{
+		StartTime: startTime,
+		EndTime:   endTime,
+		Platform:  platform,
+		GroupID:   groupID,
+		QueryMode: service.OpsQueryModeRaw,
+	}
+
+	summary, err := h.opsService.GetRealtimeTrafficSummary(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	if summary != nil {
+		summary.Window = windowLabel
+	}
+	response.Success(c, gin.H{
+		"enabled":   true,
+		"summary":   summary,
+		"timestamp": endTime,
+	})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_runtime_logging_handler_test.go

@@ -0,0 +1,173 @@
+package admin
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type testSettingRepo struct {
+	values map[string]string
+}
+
+func newTestSettingRepo() *testSettingRepo {
+	return &testSettingRepo{values: map[string]string{}}
+}
+
+func (s *testSettingRepo) Get(ctx context.Context, key string) (*service.Setting, error) {
+	v, err := s.GetValue(ctx, key)
+	if err != nil {
+		return nil, err
+	}
+	return &service.Setting{Key: key, Value: v}, nil
+}
+func (s *testSettingRepo) GetValue(ctx context.Context, key string) (string, error) {
+	v, ok := s.values[key]
+	if !ok {
+		return "", service.ErrSettingNotFound
+	}
+	return v, nil
+}
+func (s *testSettingRepo) Set(ctx context.Context, key, value string) error {
+	s.values[key] = value
+	return nil
+}
+func (s *testSettingRepo) GetMultiple(ctx context.Context, keys []string) (map[string]string, error) {
+	out := make(map[string]string, len(keys))
+	for _, k := range keys {
+		if v, ok := s.values[k]; ok {
+			out[k] = v
+		}
+	}
+	return out, nil
+}
+func (s *testSettingRepo) SetMultiple(ctx context.Context, settings map[string]string) error {
+	for k, v := range settings {
+		s.values[k] = v
+	}
+	return nil
+}
+func (s *testSettingRepo) GetAll(ctx context.Context) (map[string]string, error) {
+	out := make(map[string]string, len(s.values))
+	for k, v := range s.values {
+		out[k] = v
+	}
+	return out, nil
+}
+func (s *testSettingRepo) Delete(ctx context.Context, key string) error {
+	delete(s.values, key)
+	return nil
+}
+
+func newOpsRuntimeRouter(handler *OpsHandler, withUser bool) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	if withUser {
+		r.Use(func(c *gin.Context) {
+			c.Set(string(middleware.ContextKeyUser), middleware.AuthSubject{UserID: 7})
+			c.Next()
+		})
+	}
+	r.GET("/runtime/logging", handler.GetRuntimeLogConfig)
+	r.PUT("/runtime/logging", handler.UpdateRuntimeLogConfig)
+	r.POST("/runtime/logging/reset", handler.ResetRuntimeLogConfig)
+	return r
+}
+
+func newRuntimeOpsService(t *testing.T) *service.OpsService {
+	t.Helper()
+	if err := logger.Init(logger.InitOptions{
+		Level:       "info",
+		Format:      "json",
+		ServiceName: "sub2api",
+		Environment: "test",
+		Output: logger.OutputOptions{
+			ToStdout: false,
+			ToFile:   false,
+		},
+	}); err != nil {
+		t.Fatalf("init logger: %v", err)
+	}
+
+	settingRepo := newTestSettingRepo()
+	cfg := &config.Config{
+		Ops: config.OpsConfig{Enabled: true},
+		Log: config.LogConfig{
+			Level:           "info",
+			Caller:          true,
+			StacktraceLevel: "error",
+			Sampling: config.LogSamplingConfig{
+				Enabled:    false,
+				Initial:    100,
+				Thereafter: 100,
+			},
+		},
+	}
+	return service.NewOpsService(nil, settingRepo, cfg, nil, nil, nil, nil, nil, nil, nil, nil)
+}
+
+func TestOpsRuntimeLoggingHandler_GetConfig(t *testing.T) {
+	h := NewOpsHandler(newRuntimeOpsService(t))
+	r := newOpsRuntimeRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/runtime/logging", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d, want 200", w.Code)
+	}
+}
+
+func TestOpsRuntimeLoggingHandler_UpdateUnauthorized(t *testing.T) {
+	h := NewOpsHandler(newRuntimeOpsService(t))
+	r := newOpsRuntimeRouter(h, false)
+
+	body := `{"level":"debug","enable_sampling":false,"sampling_initial":100,"sampling_thereafter":100,"caller":true,"stacktrace_level":"error","retention_days":30}`
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/runtime/logging", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", w.Code)
+	}
+}
+
+func TestOpsRuntimeLoggingHandler_UpdateAndResetSuccess(t *testing.T) {
+	h := NewOpsHandler(newRuntimeOpsService(t))
+	r := newOpsRuntimeRouter(h, true)
+
+	payload := map[string]any{
+		"level":               "debug",
+		"enable_sampling":     false,
+		"sampling_initial":    100,
+		"sampling_thereafter": 100,
+		"caller":              true,
+		"stacktrace_level":    "error",
+		"retention_days":      30,
+	}
+	raw, _ := json.Marshal(payload)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/runtime/logging", bytes.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("update status=%d, want 200, body=%s", w.Code, w.Body.String())
+	}
+
+	w = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/runtime/logging/reset", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("reset status=%d, want 200, body=%s", w.Code, w.Body.String())
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_settings_handler.go

@@ -0,0 +1,273 @@
+package admin
+
+import (
+	"net/http"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+// GetEmailNotificationConfig returns Ops email notification config (DB-backed).
+// GET /api/v1/admin/ops/email-notification/config
+func (h *OpsHandler) GetEmailNotificationConfig(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	cfg, err := h.opsService.GetEmailNotificationConfig(c.Request.Context())
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get email notification config")
+		return
+	}
+	response.Success(c, cfg)
+}
+
+// UpdateEmailNotificationConfig updates Ops email notification config (DB-backed).
+// PUT /api/v1/admin/ops/email-notification/config
+func (h *OpsHandler) UpdateEmailNotificationConfig(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var req service.OpsEmailNotificationConfigUpdateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	updated, err := h.opsService.UpdateEmailNotificationConfig(c.Request.Context(), &req)
+	if err != nil {
+		// Most failures here are validation errors from request payload; treat as 400.
+		response.Error(c, http.StatusBadRequest, err.Error())
+		return
+	}
+	response.Success(c, updated)
+}
+
+// GetAlertRuntimeSettings returns Ops alert evaluator runtime settings (DB-backed).
+// GET /api/v1/admin/ops/runtime/alert
+func (h *OpsHandler) GetAlertRuntimeSettings(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	cfg, err := h.opsService.GetOpsAlertRuntimeSettings(c.Request.Context())
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get alert runtime settings")
+		return
+	}
+	response.Success(c, cfg)
+}
+
+// UpdateAlertRuntimeSettings updates Ops alert evaluator runtime settings (DB-backed).
+// PUT /api/v1/admin/ops/runtime/alert
+func (h *OpsHandler) UpdateAlertRuntimeSettings(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var req service.OpsAlertRuntimeSettings
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	updated, err := h.opsService.UpdateOpsAlertRuntimeSettings(c.Request.Context(), &req)
+	if err != nil {
+		response.Error(c, http.StatusBadRequest, err.Error())
+		return
+	}
+	response.Success(c, updated)
+}
+
+// GetRuntimeLogConfig returns runtime log config (DB-backed).
+// GET /api/v1/admin/ops/runtime/logging
+func (h *OpsHandler) GetRuntimeLogConfig(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	cfg, err := h.opsService.GetRuntimeLogConfig(c.Request.Context())
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get runtime log config")
+		return
+	}
+	response.Success(c, cfg)
+}
+
+// UpdateRuntimeLogConfig updates runtime log config and applies changes immediately.
+// PUT /api/v1/admin/ops/runtime/logging
+func (h *OpsHandler) UpdateRuntimeLogConfig(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var req service.OpsRuntimeLogConfig
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	updated, err := h.opsService.UpdateRuntimeLogConfig(c.Request.Context(), &req, subject.UserID)
+	if err != nil {
+		response.Error(c, http.StatusBadRequest, err.Error())
+		return
+	}
+	response.Success(c, updated)
+}
+
+// ResetRuntimeLogConfig removes runtime override and falls back to env/yaml baseline.
+// POST /api/v1/admin/ops/runtime/logging/reset
+func (h *OpsHandler) ResetRuntimeLogConfig(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	updated, err := h.opsService.ResetRuntimeLogConfig(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.Error(c, http.StatusBadRequest, err.Error())
+		return
+	}
+	response.Success(c, updated)
+}
+
+// GetAdvancedSettings returns Ops advanced settings (DB-backed).
+// GET /api/v1/admin/ops/advanced-settings
+func (h *OpsHandler) GetAdvancedSettings(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	cfg, err := h.opsService.GetOpsAdvancedSettings(c.Request.Context())
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get advanced settings")
+		return
+	}
+	response.Success(c, cfg)
+}
+
+// UpdateAdvancedSettings updates Ops advanced settings (DB-backed).
+// PUT /api/v1/admin/ops/advanced-settings
+func (h *OpsHandler) UpdateAdvancedSettings(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var req service.OpsAdvancedSettings
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	updated, err := h.opsService.UpdateOpsAdvancedSettings(c.Request.Context(), &req)
+	if err != nil {
+		response.Error(c, http.StatusBadRequest, err.Error())
+		return
+	}
+	response.Success(c, updated)
+}
+
+// GetMetricThresholds returns Ops metric thresholds (DB-backed).
+// GET /api/v1/admin/ops/settings/metric-thresholds
+func (h *OpsHandler) GetMetricThresholds(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	cfg, err := h.opsService.GetMetricThresholds(c.Request.Context())
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get metric thresholds")
+		return
+	}
+	response.Success(c, cfg)
+}
+
+// UpdateMetricThresholds updates Ops metric thresholds (DB-backed).
+// PUT /api/v1/admin/ops/settings/metric-thresholds
+func (h *OpsHandler) UpdateMetricThresholds(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var req service.OpsMetricThresholds
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	updated, err := h.opsService.UpdateMetricThresholds(c.Request.Context(), &req)
+	if err != nil {
+		response.Error(c, http.StatusBadRequest, err.Error())
+		return
+	}
+	response.Success(c, updated)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_snapshot_v2_handler.go

@@ -0,0 +1,145 @@
+package admin
+
+import (
+	"encoding/json"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"golang.org/x/sync/errgroup"
+)
+
+var opsDashboardSnapshotV2Cache = newSnapshotCache(30 * time.Second)
+
+type opsDashboardSnapshotV2Response struct {
+	GeneratedAt string `json:"generated_at"`
+
+	Overview        *service.OpsDashboardOverview       `json:"overview"`
+	ThroughputTrend *service.OpsThroughputTrendResponse `json:"throughput_trend"`
+	ErrorTrend      *service.OpsErrorTrendResponse      `json:"error_trend"`
+}
+
+type opsDashboardSnapshotV2CacheKey struct {
+	StartTime    string               `json:"start_time"`
+	EndTime      string               `json:"end_time"`
+	Platform     string               `json:"platform"`
+	GroupID      *int64               `json:"group_id"`
+	QueryMode    service.OpsQueryMode `json:"mode"`
+	BucketSecond int                  `json:"bucket_second"`
+}
+
+// GetDashboardSnapshotV2 returns ops dashboard core snapshot in one request.
+// GET /api/v1/admin/ops/dashboard/snapshot-v2
+func (h *OpsHandler) GetDashboardSnapshotV2(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	startTime, endTime, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsDashboardFilter{
+		StartTime: startTime,
+		EndTime:   endTime,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+		QueryMode: parseOpsQueryMode(c),
+	}
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		filter.GroupID = &id
+	}
+	bucketSeconds := pickThroughputBucketSeconds(endTime.Sub(startTime))
+
+	keyRaw, _ := json.Marshal(opsDashboardSnapshotV2CacheKey{
+		StartTime:    startTime.UTC().Format(time.RFC3339),
+		EndTime:      endTime.UTC().Format(time.RFC3339),
+		Platform:     filter.Platform,
+		GroupID:      filter.GroupID,
+		QueryMode:    filter.QueryMode,
+		BucketSecond: bucketSeconds,
+	})
+	cacheKey := string(keyRaw)
+
+	if cached, ok := opsDashboardSnapshotV2Cache.Get(cacheKey); ok {
+		if cached.ETag != "" {
+			c.Header("ETag", cached.ETag)
+			c.Header("Vary", "If-None-Match")
+			if ifNoneMatchMatched(c.GetHeader("If-None-Match"), cached.ETag) {
+				c.Status(http.StatusNotModified)
+				return
+			}
+		}
+		c.Header("X-Snapshot-Cache", "hit")
+		response.Success(c, cached.Payload)
+		return
+	}
+
+	var (
+		overview *service.OpsDashboardOverview
+		trend    *service.OpsThroughputTrendResponse
+		errTrend *service.OpsErrorTrendResponse
+	)
+	g, gctx := errgroup.WithContext(c.Request.Context())
+	g.Go(func() error {
+		f := *filter
+		result, err := h.opsService.GetDashboardOverview(gctx, &f)
+		if err != nil {
+			return err
+		}
+		overview = result
+		return nil
+	})
+	g.Go(func() error {
+		f := *filter
+		result, err := h.opsService.GetThroughputTrend(gctx, &f, bucketSeconds)
+		if err != nil {
+			return err
+		}
+		trend = result
+		return nil
+	})
+	g.Go(func() error {
+		f := *filter
+		result, err := h.opsService.GetErrorTrend(gctx, &f, bucketSeconds)
+		if err != nil {
+			return err
+		}
+		errTrend = result
+		return nil
+	})
+	if err := g.Wait(); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	resp := &opsDashboardSnapshotV2Response{
+		GeneratedAt:     time.Now().UTC().Format(time.RFC3339),
+		Overview:        overview,
+		ThroughputTrend: trend,
+		ErrorTrend:      errTrend,
+	}
+
+	cached := opsDashboardSnapshotV2Cache.Set(cacheKey, resp)
+	if cached.ETag != "" {
+		c.Header("ETag", cached.ETag)
+		c.Header("Vary", "If-None-Match")
+	}
+	c.Header("X-Snapshot-Cache", "miss")
+	response.Success(c, resp)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_system_log_handler.go

@@ -0,0 +1,174 @@
+package admin
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type opsSystemLogCleanupRequest struct {
+	StartTime string `json:"start_time"`
+	EndTime   string `json:"end_time"`
+
+	Level           string `json:"level"`
+	Component       string `json:"component"`
+	RequestID       string `json:"request_id"`
+	ClientRequestID string `json:"client_request_id"`
+	UserID          *int64 `json:"user_id"`
+	AccountID       *int64 `json:"account_id"`
+	Platform        string `json:"platform"`
+	Model           string `json:"model"`
+	Query           string `json:"q"`
+}
+
+// ListSystemLogs returns indexed system logs.
+// GET /api/v1/admin/ops/system-logs
+func (h *OpsHandler) ListSystemLogs(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	if pageSize > 200 {
+		pageSize = 200
+	}
+
+	start, end, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsSystemLogFilter{
+		Page:            page,
+		PageSize:        pageSize,
+		StartTime:       &start,
+		EndTime:         &end,
+		Level:           strings.TrimSpace(c.Query("level")),
+		Component:       strings.TrimSpace(c.Query("component")),
+		RequestID:       strings.TrimSpace(c.Query("request_id")),
+		ClientRequestID: strings.TrimSpace(c.Query("client_request_id")),
+		Platform:        strings.TrimSpace(c.Query("platform")),
+		Model:           strings.TrimSpace(c.Query("model")),
+		Query:           strings.TrimSpace(c.Query("q")),
+	}
+	if v := strings.TrimSpace(c.Query("user_id")); v != "" {
+		id, parseErr := strconv.ParseInt(v, 10, 64)
+		if parseErr != nil || id <= 0 {
+			response.BadRequest(c, "Invalid user_id")
+			return
+		}
+		filter.UserID = &id
+	}
+	if v := strings.TrimSpace(c.Query("account_id")); v != "" {
+		id, parseErr := strconv.ParseInt(v, 10, 64)
+		if parseErr != nil || id <= 0 {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		filter.AccountID = &id
+	}
+
+	result, err := h.opsService.ListSystemLogs(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Paginated(c, result.Logs, int64(result.Total), result.Page, result.PageSize)
+}
+
+// CleanupSystemLogs deletes indexed system logs by filter.
+// POST /api/v1/admin/ops/system-logs/cleanup
+func (h *OpsHandler) CleanupSystemLogs(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	var req opsSystemLogCleanupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	parseTS := func(raw string) (*time.Time, error) {
+		raw = strings.TrimSpace(raw)
+		if raw == "" {
+			return nil, nil
+		}
+		if t, err := time.Parse(time.RFC3339Nano, raw); err == nil {
+			return &t, nil
+		}
+		t, err := time.Parse(time.RFC3339, raw)
+		if err != nil {
+			return nil, err
+		}
+		return &t, nil
+	}
+	start, err := parseTS(req.StartTime)
+	if err != nil {
+		response.BadRequest(c, "Invalid start_time")
+		return
+	}
+	end, err := parseTS(req.EndTime)
+	if err != nil {
+		response.BadRequest(c, "Invalid end_time")
+		return
+	}
+
+	filter := &service.OpsSystemLogCleanupFilter{
+		StartTime:       start,
+		EndTime:         end,
+		Level:           strings.TrimSpace(req.Level),
+		Component:       strings.TrimSpace(req.Component),
+		RequestID:       strings.TrimSpace(req.RequestID),
+		ClientRequestID: strings.TrimSpace(req.ClientRequestID),
+		UserID:          req.UserID,
+		AccountID:       req.AccountID,
+		Platform:        strings.TrimSpace(req.Platform),
+		Model:           strings.TrimSpace(req.Model),
+		Query:           strings.TrimSpace(req.Query),
+	}
+
+	deleted, err := h.opsService.CleanupSystemLogs(c.Request.Context(), filter, subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"deleted": deleted})
+}
+
+// GetSystemLogIngestionHealth returns sink health metrics.
+// GET /api/v1/admin/ops/system-logs/health
+func (h *OpsHandler) GetSystemLogIngestionHealth(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, h.opsService.GetSystemLogSinkHealth())
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_system_log_handler_test.go

@@ -0,0 +1,233 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type responseEnvelope struct {
+	Code    int             `json:"code"`
+	Message string          `json:"message"`
+	Data    json.RawMessage `json:"data"`
+}
+
+func newOpsSystemLogTestRouter(handler *OpsHandler, withUser bool) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	if withUser {
+		r.Use(func(c *gin.Context) {
+			c.Set(string(middleware.ContextKeyUser), middleware.AuthSubject{UserID: 99})
+			c.Next()
+		})
+	}
+	r.GET("/logs", handler.ListSystemLogs)
+	r.POST("/logs/cleanup", handler.CleanupSystemLogs)
+	r.GET("/logs/health", handler.GetSystemLogIngestionHealth)
+	return r
+}
+
+func TestOpsSystemLogHandler_ListUnavailable(t *testing.T) {
+	h := NewOpsHandler(nil)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status=%d, want 503", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_ListInvalidUserID(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs?user_id=abc", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_ListInvalidAccountID(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs?account_id=-1", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_ListMonitoringDisabled(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, &config.Config{
+		Ops: config.OpsConfig{Enabled: false},
+	}, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status=%d, want 404", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_ListSuccess(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs?time_range=30m&page=1&page_size=20", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d, want 200", w.Code)
+	}
+
+	var resp responseEnvelope
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+	if resp.Code != 0 {
+		t.Fatalf("unexpected response code: %+v", resp)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupUnauthorized(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupInvalidPayload(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{bad-json`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupInvalidTime(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"start_time":"bad","request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupInvalidEndTime(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"end_time":"bad","request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupServiceUnavailable(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status=%d, want 503", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupMonitoringDisabled(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, &config.Config{
+		Ops: config.OpsConfig{Enabled: false},
+	}, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status=%d, want 404", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_Health(t *testing.T) {
+	sink := service.NewOpsSystemLogSink(nil)
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, sink)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs/health", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d, want 200", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_HealthUnavailableAndMonitoringDisabled(t *testing.T) {
+	h := NewOpsHandler(nil)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs/health", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status=%d, want 503", w.Code)
+	}
+
+	svc := service.NewOpsService(nil, nil, &config.Config{
+		Ops: config.OpsConfig{Enabled: false},
+	}, nil, nil, nil, nil, nil, nil, nil, nil)
+	h = NewOpsHandler(svc)
+	r = newOpsSystemLogTestRouter(h, false)
+	w = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/logs/health", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status=%d, want 404", w.Code)
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/ops_ws_handler.go

@@ -0,0 +1,761 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"math"
+	"net"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/gorilla/websocket"
+)
+
+type OpsWSProxyConfig struct {
+	TrustProxy     bool
+	TrustedProxies []netip.Prefix
+	OriginPolicy   string
+}
+
+const (
+	envOpsWSTrustProxy     = "OPS_WS_TRUST_PROXY"
+	envOpsWSTrustedProxies = "OPS_WS_TRUSTED_PROXIES"
+	envOpsWSOriginPolicy   = "OPS_WS_ORIGIN_POLICY"
+	envOpsWSMaxConns       = "OPS_WS_MAX_CONNS"
+	envOpsWSMaxConnsPerIP  = "OPS_WS_MAX_CONNS_PER_IP"
+)
+
+const (
+	OriginPolicyStrict     = "strict"
+	OriginPolicyPermissive = "permissive"
+)
+
+var opsWSProxyConfig = loadOpsWSProxyConfigFromEnv()
+
+var upgrader = websocket.Upgrader{
+	CheckOrigin: func(r *http.Request) bool {
+		return isAllowedOpsWSOrigin(r)
+	},
+	// Subprotocol negotiation:
+	// - The frontend passes ["sub2api-admin", "jwt.<token>"].
+	// - We always select "sub2api-admin" so the token is never echoed back in the handshake response.
+	Subprotocols: []string{"sub2api-admin"},
+}
+
+const (
+	qpsWSPushInterval       = 2 * time.Second
+	qpsWSRefreshInterval    = 5 * time.Second
+	qpsWSRequestCountWindow = 1 * time.Minute
+
+	defaultMaxWSConns      = 100
+	defaultMaxWSConnsPerIP = 20
+)
+
+var wsConnCount atomic.Int32
+var wsConnCountByIPMu sync.Mutex
+var wsConnCountByIP = make(map[string]int32)
+
+const qpsWSIdleStopDelay = 30 * time.Second
+
+const (
+	opsWSCloseRealtimeDisabled = 4001
+)
+
+var qpsWSIdleStopMu sync.Mutex
+var qpsWSIdleStopTimer *time.Timer
+
+func cancelQPSWSIdleStop() {
+	qpsWSIdleStopMu.Lock()
+	if qpsWSIdleStopTimer != nil {
+		qpsWSIdleStopTimer.Stop()
+		qpsWSIdleStopTimer = nil
+	}
+	qpsWSIdleStopMu.Unlock()
+}
+
+func scheduleQPSWSIdleStop() {
+	qpsWSIdleStopMu.Lock()
+	if qpsWSIdleStopTimer != nil {
+		qpsWSIdleStopMu.Unlock()
+		return
+	}
+	qpsWSIdleStopTimer = time.AfterFunc(qpsWSIdleStopDelay, func() {
+		// Only stop if truly idle at fire time.
+		if wsConnCount.Load() == 0 {
+			qpsWSCache.Stop()
+		}
+		qpsWSIdleStopMu.Lock()
+		qpsWSIdleStopTimer = nil
+		qpsWSIdleStopMu.Unlock()
+	})
+	qpsWSIdleStopMu.Unlock()
+}
+
+type opsWSRuntimeLimits struct {
+	MaxConns      int32
+	MaxConnsPerIP int32
+}
+
+var opsWSLimits = loadOpsWSRuntimeLimitsFromEnv()
+
+const (
+	qpsWSWriteTimeout = 10 * time.Second
+	qpsWSPongWait     = 60 * time.Second
+	qpsWSPingInterval = 30 * time.Second
+
+	// We don't expect clients to send application messages; we only read to process control frames (Pong/Close).
+	qpsWSMaxReadBytes = 1024
+)
+
+type opsWSQPSCache struct {
+	refreshInterval    time.Duration
+	requestCountWindow time.Duration
+
+	lastUpdatedUnixNano atomic.Int64
+	payload             atomic.Value // []byte
+
+	opsService *service.OpsService
+	cancel     context.CancelFunc
+	done       chan struct{}
+
+	mu      sync.Mutex
+	running bool
+}
+
+var qpsWSCache = &opsWSQPSCache{
+	refreshInterval:    qpsWSRefreshInterval,
+	requestCountWindow: qpsWSRequestCountWindow,
+}
+
+func (c *opsWSQPSCache) start(opsService *service.OpsService) {
+	if c == nil || opsService == nil {
+		return
+	}
+
+	for {
+		c.mu.Lock()
+		if c.running {
+			c.mu.Unlock()
+			return
+		}
+
+		// If a previous refresh loop is currently stopping, wait for it to fully exit.
+		done := c.done
+		if done != nil {
+			c.mu.Unlock()
+			<-done
+
+			c.mu.Lock()
+			if c.done == done && !c.running {
+				c.done = nil
+			}
+			c.mu.Unlock()
+			continue
+		}
+
+		c.opsService = opsService
+		ctx, cancel := context.WithCancel(context.Background())
+		c.cancel = cancel
+		c.done = make(chan struct{})
+		done = c.done
+		c.running = true
+		c.mu.Unlock()
+
+		go func() {
+			defer close(done)
+			c.refreshLoop(ctx)
+		}()
+		return
+	}
+}
+
+// Stop stops the background refresh loop.
+// It is safe to call multiple times.
+func (c *opsWSQPSCache) Stop() {
+	if c == nil {
+		return
+	}
+
+	c.mu.Lock()
+	if !c.running {
+		done := c.done
+		c.mu.Unlock()
+		if done != nil {
+			<-done
+		}
+		return
+	}
+	cancel := c.cancel
+	c.cancel = nil
+	c.running = false
+	c.opsService = nil
+	done := c.done
+	c.mu.Unlock()
+
+	if cancel != nil {
+		cancel()
+	}
+	if done != nil {
+		<-done
+	}
+
+	c.mu.Lock()
+	if c.done == done && !c.running {
+		c.done = nil
+	}
+	c.mu.Unlock()
+}
+
+func (c *opsWSQPSCache) refreshLoop(ctx context.Context) {
+	ticker := time.NewTicker(c.refreshInterval)
+	defer ticker.Stop()
+
+	c.refresh(ctx)
+	for {
+		select {
+		case <-ticker.C:
+			c.refresh(ctx)
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+func (c *opsWSQPSCache) refresh(parentCtx context.Context) {
+	if c == nil {
+		return
+	}
+
+	c.mu.Lock()
+	opsService := c.opsService
+	c.mu.Unlock()
+	if opsService == nil {
+		return
+	}
+
+	if parentCtx == nil {
+		parentCtx = context.Background()
+	}
+	ctx, cancel := context.WithTimeout(parentCtx, 10*time.Second)
+	defer cancel()
+
+	now := time.Now().UTC()
+	stats, err := opsService.GetWindowStats(ctx, now.Add(-c.requestCountWindow), now)
+	if err != nil || stats == nil {
+		if err != nil {
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] refresh: get window stats failed: %v", err)
+		}
+		return
+	}
+
+	requestCount := stats.SuccessCount + stats.ErrorCountTotal
+	qps := 0.0
+	tps := 0.0
+	if c.requestCountWindow > 0 {
+		seconds := c.requestCountWindow.Seconds()
+		qps = roundTo1DP(float64(requestCount) / seconds)
+		tps = roundTo1DP(float64(stats.TokenConsumed) / seconds)
+	}
+
+	payload := gin.H{
+		"type":      "qps_update",
+		"timestamp": now.Format(time.RFC3339),
+		"data": gin.H{
+			"qps":           qps,
+			"tps":           tps,
+			"request_count": requestCount,
+		},
+	}
+
+	msg, err := json.Marshal(payload)
+	if err != nil {
+		logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] refresh: marshal payload failed: %v", err)
+		return
+	}
+
+	c.payload.Store(msg)
+	c.lastUpdatedUnixNano.Store(now.UnixNano())
+}
+
+func roundTo1DP(v float64) float64 {
+	return math.Round(v*10) / 10
+}
+
+func (c *opsWSQPSCache) getPayload() []byte {
+	if c == nil {
+		return nil
+	}
+	if cached, ok := c.payload.Load().([]byte); ok && cached != nil {
+		return cached
+	}
+	return nil
+}
+
+func closeWS(conn *websocket.Conn, code int, reason string) {
+	if conn == nil {
+		return
+	}
+	msg := websocket.FormatCloseMessage(code, reason)
+	_ = conn.WriteControl(websocket.CloseMessage, msg, time.Now().Add(qpsWSWriteTimeout))
+	_ = conn.Close()
+}
+
+// QPSWSHandler handles realtime QPS push via WebSocket.
+// GET /api/v1/admin/ops/ws/qps
+func (h *OpsHandler) QPSWSHandler(c *gin.Context) {
+	clientIP := requestClientIP(c.Request)
+
+	if h == nil || h.opsService == nil {
+		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "ops service not initialized"})
+		return
+	}
+
+	// If realtime monitoring is disabled, prefer a successful WS upgrade followed by a clean close
+	// with a deterministic close code. This prevents clients from spinning on 404/1006 reconnect loops.
+	if !h.opsService.IsRealtimeMonitoringEnabled(c.Request.Context()) {
+		conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
+		if err != nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "ops realtime monitoring is disabled"})
+			return
+		}
+		closeWS(conn, opsWSCloseRealtimeDisabled, "realtime_disabled")
+		return
+	}
+
+	cancelQPSWSIdleStop()
+	// Lazily start the background refresh loop so unit tests that never hit the
+	// websocket route don't spawn goroutines that depend on DB/Redis stubs.
+	qpsWSCache.start(h.opsService)
+
+	// Reserve a global slot before upgrading the connection to keep the limit strict.
+	if !tryAcquireOpsWSTotalSlot(opsWSLimits.MaxConns) {
+		logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] connection limit reached: %d/%d", wsConnCount.Load(), opsWSLimits.MaxConns)
+		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "too many connections"})
+		return
+	}
+	defer func() {
+		if wsConnCount.Add(-1) == 0 {
+			scheduleQPSWSIdleStop()
+		}
+	}()
+
+	if opsWSLimits.MaxConnsPerIP > 0 && clientIP != "" {
+		if !tryAcquireOpsWSIPSlot(clientIP, opsWSLimits.MaxConnsPerIP) {
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] per-ip connection limit reached: ip=%s limit=%d", clientIP, opsWSLimits.MaxConnsPerIP)
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "too many connections"})
+			return
+		}
+		defer releaseOpsWSIPSlot(clientIP)
+	}
+
+	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] upgrade failed: %v", err)
+		return
+	}
+
+	defer func() {
+		_ = conn.Close()
+	}()
+
+	handleQPSWebSocket(c.Request.Context(), conn)
+}
+
+func tryAcquireOpsWSTotalSlot(limit int32) bool {
+	if limit <= 0 {
+		return true
+	}
+	for {
+		current := wsConnCount.Load()
+		if current >= limit {
+			return false
+		}
+		if wsConnCount.CompareAndSwap(current, current+1) {
+			return true
+		}
+	}
+}
+
+func tryAcquireOpsWSIPSlot(clientIP string, limit int32) bool {
+	if strings.TrimSpace(clientIP) == "" || limit <= 0 {
+		return true
+	}
+	wsConnCountByIPMu.Lock()
+	defer wsConnCountByIPMu.Unlock()
+	current := wsConnCountByIP[clientIP]
+	if current >= limit {
+		return false
+	}
+	wsConnCountByIP[clientIP] = current + 1
+	return true
+}
+
+func releaseOpsWSIPSlot(clientIP string) {
+	if strings.TrimSpace(clientIP) == "" {
+		return
+	}
+	wsConnCountByIPMu.Lock()
+	defer wsConnCountByIPMu.Unlock()
+	current, ok := wsConnCountByIP[clientIP]
+	if !ok {
+		return
+	}
+	if current <= 1 {
+		delete(wsConnCountByIP, clientIP)
+		return
+	}
+	wsConnCountByIP[clientIP] = current - 1
+}
+
+func handleQPSWebSocket(parentCtx context.Context, conn *websocket.Conn) {
+	if conn == nil {
+		return
+	}
+
+	ctx, cancel := context.WithCancel(parentCtx)
+	defer cancel()
+
+	var closeOnce sync.Once
+	closeConn := func() {
+		closeOnce.Do(func() {
+			_ = conn.Close()
+		})
+	}
+
+	closeFrameCh := make(chan []byte, 1)
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		defer cancel()
+
+		conn.SetReadLimit(qpsWSMaxReadBytes)
+		if err := conn.SetReadDeadline(time.Now().Add(qpsWSPongWait)); err != nil {
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] set read deadline failed: %v", err)
+			return
+		}
+		conn.SetPongHandler(func(string) error {
+			return conn.SetReadDeadline(time.Now().Add(qpsWSPongWait))
+		})
+		conn.SetCloseHandler(func(code int, text string) error {
+			select {
+			case closeFrameCh <- websocket.FormatCloseMessage(code, text):
+			default:
+			}
+			cancel()
+			return nil
+		})
+
+		for {
+			_, _, err := conn.ReadMessage()
+			if err != nil {
+				if websocket.IsUnexpectedCloseError(err, websocket.CloseNormalClosure, websocket.CloseGoingAway, websocket.CloseNoStatusReceived) {
+					logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] read failed: %v", err)
+				}
+				return
+			}
+		}
+	}()
+
+	// Push QPS data every 2 seconds (values are globally cached and refreshed at most once per qpsWSRefreshInterval).
+	pushTicker := time.NewTicker(qpsWSPushInterval)
+	defer pushTicker.Stop()
+
+	// Heartbeat ping every 30 seconds.
+	pingTicker := time.NewTicker(qpsWSPingInterval)
+	defer pingTicker.Stop()
+
+	writeWithTimeout := func(messageType int, data []byte) error {
+		if err := conn.SetWriteDeadline(time.Now().Add(qpsWSWriteTimeout)); err != nil {
+			return err
+		}
+		return conn.WriteMessage(messageType, data)
+	}
+
+	sendClose := func(closeFrame []byte) {
+		if closeFrame == nil {
+			closeFrame = websocket.FormatCloseMessage(websocket.CloseNormalClosure, "")
+		}
+		_ = writeWithTimeout(websocket.CloseMessage, closeFrame)
+	}
+
+	for {
+		select {
+		case <-pushTicker.C:
+			msg := qpsWSCache.getPayload()
+			if msg == nil {
+				continue
+			}
+			if err := writeWithTimeout(websocket.TextMessage, msg); err != nil {
+				logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] write failed: %v", err)
+				cancel()
+				closeConn()
+				wg.Wait()
+				return
+			}
+
+		case <-pingTicker.C:
+			if err := writeWithTimeout(websocket.PingMessage, nil); err != nil {
+				logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] ping failed: %v", err)
+				cancel()
+				closeConn()
+				wg.Wait()
+				return
+			}
+
+		case closeFrame := <-closeFrameCh:
+			sendClose(closeFrame)
+			closeConn()
+			wg.Wait()
+			return
+
+		case <-ctx.Done():
+			var closeFrame []byte
+			select {
+			case closeFrame = <-closeFrameCh:
+			default:
+			}
+			sendClose(closeFrame)
+
+			closeConn()
+			wg.Wait()
+			return
+		}
+	}
+}
+
+func isAllowedOpsWSOrigin(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+	origin := strings.TrimSpace(r.Header.Get("Origin"))
+	if origin == "" {
+		switch strings.ToLower(strings.TrimSpace(opsWSProxyConfig.OriginPolicy)) {
+		case OriginPolicyStrict:
+			return false
+		case OriginPolicyPermissive, "":
+			return true
+		default:
+			return true
+		}
+	}
+	parsed, err := url.Parse(origin)
+	if err != nil || parsed.Hostname() == "" {
+		return false
+	}
+	originHost := strings.ToLower(parsed.Hostname())
+
+	trustProxyHeaders := shouldTrustOpsWSProxyHeaders(r)
+	reqHost := hostWithoutPort(r.Host)
+	if trustProxyHeaders {
+		xfHost := strings.TrimSpace(r.Header.Get("X-Forwarded-Host"))
+		if xfHost != "" {
+			xfHost = strings.TrimSpace(strings.Split(xfHost, ",")[0])
+			if xfHost != "" {
+				reqHost = hostWithoutPort(xfHost)
+			}
+		}
+	}
+	reqHost = strings.ToLower(reqHost)
+	if reqHost == "" {
+		return false
+	}
+	return originHost == reqHost
+}
+
+func shouldTrustOpsWSProxyHeaders(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+	if !opsWSProxyConfig.TrustProxy {
+		return false
+	}
+	peerIP, ok := requestPeerIP(r)
+	if !ok {
+		return false
+	}
+	return isAddrInTrustedProxies(peerIP, opsWSProxyConfig.TrustedProxies)
+}
+
+func requestPeerIP(r *http.Request) (netip.Addr, bool) {
+	if r == nil {
+		return netip.Addr{}, false
+	}
+	host, _, err := net.SplitHostPort(strings.TrimSpace(r.RemoteAddr))
+	if err != nil {
+		host = strings.TrimSpace(r.RemoteAddr)
+	}
+	host = strings.TrimPrefix(host, "[")
+	host = strings.TrimSuffix(host, "]")
+	if host == "" {
+		return netip.Addr{}, false
+	}
+	addr, err := netip.ParseAddr(host)
+	if err != nil {
+		return netip.Addr{}, false
+	}
+	return addr.Unmap(), true
+}
+
+func requestClientIP(r *http.Request) string {
+	if r == nil {
+		return ""
+	}
+
+	trustProxyHeaders := shouldTrustOpsWSProxyHeaders(r)
+	if trustProxyHeaders {
+		xff := strings.TrimSpace(r.Header.Get("X-Forwarded-For"))
+		if xff != "" {
+			// Use the left-most entry (original client). If multiple proxies add values, they are comma-separated.
+			xff = strings.TrimSpace(strings.Split(xff, ",")[0])
+			xff = strings.TrimPrefix(xff, "[")
+			xff = strings.TrimSuffix(xff, "]")
+			if addr, err := netip.ParseAddr(xff); err == nil && addr.IsValid() {
+				return addr.Unmap().String()
+			}
+		}
+	}
+
+	if peer, ok := requestPeerIP(r); ok && peer.IsValid() {
+		return peer.String()
+	}
+	return ""
+}
+
+func isAddrInTrustedProxies(addr netip.Addr, trusted []netip.Prefix) bool {
+	if !addr.IsValid() {
+		return false
+	}
+	for _, p := range trusted {
+		if p.Contains(addr) {
+			return true
+		}
+	}
+	return false
+}
+
+func loadOpsWSProxyConfigFromEnv() OpsWSProxyConfig {
+	cfg := OpsWSProxyConfig{
+		TrustProxy:     true,
+		TrustedProxies: defaultTrustedProxies(),
+		OriginPolicy:   OriginPolicyPermissive,
+	}
+
+	if v := strings.TrimSpace(os.Getenv(envOpsWSTrustProxy)); v != "" {
+		if parsed, err := strconv.ParseBool(v); err == nil {
+			cfg.TrustProxy = parsed
+		} else {
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s=%q (expected bool); using default=%v", envOpsWSTrustProxy, v, cfg.TrustProxy)
+		}
+	}
+
+	if raw := strings.TrimSpace(os.Getenv(envOpsWSTrustedProxies)); raw != "" {
+		prefixes, invalid := parseTrustedProxyList(raw)
+		if len(invalid) > 0 {
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s entries ignored: %s", envOpsWSTrustedProxies, strings.Join(invalid, ", "))
+		}
+		cfg.TrustedProxies = prefixes
+	}
+
+	if v := strings.TrimSpace(os.Getenv(envOpsWSOriginPolicy)); v != "" {
+		normalized := strings.ToLower(v)
+		switch normalized {
+		case OriginPolicyStrict, OriginPolicyPermissive:
+			cfg.OriginPolicy = normalized
+		default:
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s=%q (expected %q or %q); using default=%q", envOpsWSOriginPolicy, v, OriginPolicyStrict, OriginPolicyPermissive, cfg.OriginPolicy)
+		}
+	}
+
+	return cfg
+}
+
+func loadOpsWSRuntimeLimitsFromEnv() opsWSRuntimeLimits {
+	cfg := opsWSRuntimeLimits{
+		MaxConns:      defaultMaxWSConns,
+		MaxConnsPerIP: defaultMaxWSConnsPerIP,
+	}
+
+	if v := strings.TrimSpace(os.Getenv(envOpsWSMaxConns)); v != "" {
+		if parsed, err := strconv.Atoi(v); err == nil && parsed > 0 {
+			cfg.MaxConns = int32(parsed)
+		} else {
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s=%q (expected int>0); using default=%d", envOpsWSMaxConns, v, cfg.MaxConns)
+		}
+	}
+	if v := strings.TrimSpace(os.Getenv(envOpsWSMaxConnsPerIP)); v != "" {
+		if parsed, err := strconv.Atoi(v); err == nil && parsed >= 0 {
+			cfg.MaxConnsPerIP = int32(parsed)
+		} else {
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s=%q (expected int>=0); using default=%d", envOpsWSMaxConnsPerIP, v, cfg.MaxConnsPerIP)
+		}
+	}
+	return cfg
+}
+
+func defaultTrustedProxies() []netip.Prefix {
+	prefixes, _ := parseTrustedProxyList("127.0.0.0/8,::1/128")
+	return prefixes
+}
+
+func parseTrustedProxyList(raw string) (prefixes []netip.Prefix, invalid []string) {
+	for _, token := range strings.Split(raw, ",") {
+		item := strings.TrimSpace(token)
+		if item == "" {
+			continue
+		}
+
+		var (
+			p   netip.Prefix
+			err error
+		)
+		if strings.Contains(item, "/") {
+			p, err = netip.ParsePrefix(item)
+		} else {
+			var addr netip.Addr
+			addr, err = netip.ParseAddr(item)
+			if err == nil {
+				addr = addr.Unmap()
+				bits := 128
+				if addr.Is4() {
+					bits = 32
+				}
+				p = netip.PrefixFrom(addr, bits)
+			}
+		}
+
+		if err != nil || !p.IsValid() {
+			invalid = append(invalid, item)
+			continue
+		}
+
+		prefixes = append(prefixes, p.Masked())
+	}
+	return prefixes, invalid
+}
+
+func hostWithoutPort(hostport string) string {
+	hostport = strings.TrimSpace(hostport)
+	if hostport == "" {
+		return ""
+	}
+	if host, _, err := net.SplitHostPort(hostport); err == nil {
+		return host
+	}
+	if strings.HasPrefix(hostport, "[") && strings.HasSuffix(hostport, "]") {
+		return strings.Trim(hostport, "[]")
+	}
+	parts := strings.Split(hostport, ":")
+	return parts[0]
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/promo_handler.go

@@ -0,0 +1,209 @@
+package admin
+
+import (
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// PromoHandler handles admin promo code management
+type PromoHandler struct {
+	promoService *service.PromoService
+}
+
+// NewPromoHandler creates a new admin promo handler
+func NewPromoHandler(promoService *service.PromoService) *PromoHandler {
+	return &PromoHandler{
+		promoService: promoService,
+	}
+}
+
+// CreatePromoCodeRequest represents create promo code request
+type CreatePromoCodeRequest struct {
+	Code        string  `json:"code"`                                  // 可选，为空则自动生成
+	BonusAmount float64 `json:"bonus_amount" binding:"required,min=0"` // 赠送余额
+	MaxUses     int     `json:"max_uses" binding:"min=0"`              // 最大使用次数，0=无限
+	ExpiresAt   *int64  `json:"expires_at"`                            // 过期时间戳（秒）
+	Notes       string  `json:"notes"`                                 // 备注
+}
+
+// UpdatePromoCodeRequest represents update promo code request
+type UpdatePromoCodeRequest struct {
+	Code        *string  `json:"code"`
+	BonusAmount *float64 `json:"bonus_amount" binding:"omitempty,min=0"`
+	MaxUses     *int     `json:"max_uses" binding:"omitempty,min=0"`
+	Status      *string  `json:"status" binding:"omitempty,oneof=active disabled"`
+	ExpiresAt   *int64   `json:"expires_at"`
+	Notes       *string  `json:"notes"`
+}
+
+// List handles listing all promo codes with pagination
+// GET /api/v1/admin/promo-codes
+func (h *PromoHandler) List(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+	status := c.Query("status")
+	search := strings.TrimSpace(c.Query("search"))
+	if len(search) > 100 {
+		search = search[:100]
+	}
+
+	params := pagination.PaginationParams{
+		Page:     page,
+		PageSize: pageSize,
+	}
+
+	codes, paginationResult, err := h.promoService.List(c.Request.Context(), params, status, search)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.PromoCode, 0, len(codes))
+	for i := range codes {
+		out = append(out, *dto.PromoCodeFromService(&codes[i]))
+	}
+	response.Paginated(c, out, paginationResult.Total, page, pageSize)
+}
+
+// GetByID handles getting a promo code by ID
+// GET /api/v1/admin/promo-codes/:id
+func (h *PromoHandler) GetByID(c *gin.Context) {
+	codeID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid promo code ID")
+		return
+	}
+
+	code, err := h.promoService.GetByID(c.Request.Context(), codeID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.PromoCodeFromService(code))
+}
+
+// Create handles creating a new promo code
+// POST /api/v1/admin/promo-codes
+func (h *PromoHandler) Create(c *gin.Context) {
+	var req CreatePromoCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	input := &service.CreatePromoCodeInput{
+		Code:        req.Code,
+		BonusAmount: req.BonusAmount,
+		MaxUses:     req.MaxUses,
+		Notes:       req.Notes,
+	}
+
+	if req.ExpiresAt != nil {
+		t := time.Unix(*req.ExpiresAt, 0)
+		input.ExpiresAt = &t
+	}
+
+	code, err := h.promoService.Create(c.Request.Context(), input)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.PromoCodeFromService(code))
+}
+
+// Update handles updating a promo code
+// PUT /api/v1/admin/promo-codes/:id
+func (h *PromoHandler) Update(c *gin.Context) {
+	codeID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid promo code ID")
+		return
+	}
+
+	var req UpdatePromoCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	input := &service.UpdatePromoCodeInput{
+		Code:        req.Code,
+		BonusAmount: req.BonusAmount,
+		MaxUses:     req.MaxUses,
+		Status:      req.Status,
+		Notes:       req.Notes,
+	}
+
+	if req.ExpiresAt != nil {
+		if *req.ExpiresAt == 0 {
+			// 0 表示清除过期时间
+			input.ExpiresAt = nil
+		} else {
+			t := time.Unix(*req.ExpiresAt, 0)
+			input.ExpiresAt = &t
+		}
+	}
+
+	code, err := h.promoService.Update(c.Request.Context(), codeID, input)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.PromoCodeFromService(code))
+}
+
+// Delete handles deleting a promo code
+// DELETE /api/v1/admin/promo-codes/:id
+func (h *PromoHandler) Delete(c *gin.Context) {
+	codeID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid promo code ID")
+		return
+	}
+
+	err = h.promoService.Delete(c.Request.Context(), codeID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Promo code deleted successfully"})
+}
+
+// GetUsages handles getting usage records for a promo code
+// GET /api/v1/admin/promo-codes/:id/usages
+func (h *PromoHandler) GetUsages(c *gin.Context) {
+	codeID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid promo code ID")
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	params := pagination.PaginationParams{
+		Page:     page,
+		PageSize: pageSize,
+	}
+
+	usages, paginationResult, err := h.promoService.ListUsages(c.Request.Context(), codeID, params)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.PromoCodeUsage, 0, len(usages))
+	for i := range usages {
+		out = append(out, *dto.PromoCodeUsageFromService(&usages[i]))
+	}
+	response.Paginated(c, out, paginationResult.Total, page, pageSize)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/proxy_data.go

@@ -0,0 +1,239 @@
+package admin
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+// ExportData exports proxy-only data for migration.
+func (h *ProxyHandler) ExportData(c *gin.Context) {
+	ctx := c.Request.Context()
+
+	selectedIDs, err := parseProxyIDs(c)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	var proxies []service.Proxy
+	if len(selectedIDs) > 0 {
+		proxies, err = h.getProxiesByIDs(ctx, selectedIDs)
+		if err != nil {
+			response.ErrorFrom(c, err)
+			return
+		}
+	} else {
+		protocol := c.Query("protocol")
+		status := c.Query("status")
+		search := strings.TrimSpace(c.Query("search"))
+		if len(search) > 100 {
+			search = search[:100]
+		}
+
+		proxies, err = h.listProxiesFiltered(ctx, protocol, status, search)
+		if err != nil {
+			response.ErrorFrom(c, err)
+			return
+		}
+	}
+
+	dataProxies := make([]DataProxy, 0, len(proxies))
+	for i := range proxies {
+		p := proxies[i]
+		key := buildProxyKey(p.Protocol, p.Host, p.Port, p.Username, p.Password)
+		dataProxies = append(dataProxies, DataProxy{
+			ProxyKey: key,
+			Name:     p.Name,
+			Protocol: p.Protocol,
+			Host:     p.Host,
+			Port:     p.Port,
+			Username: p.Username,
+			Password: p.Password,
+			Status:   p.Status,
+		})
+	}
+
+	payload := DataPayload{
+		ExportedAt: time.Now().UTC().Format(time.RFC3339),
+		Proxies:    dataProxies,
+		Accounts:   []DataAccount{},
+	}
+
+	response.Success(c, payload)
+}
+
+// ImportData imports proxy-only data for migration.
+func (h *ProxyHandler) ImportData(c *gin.Context) {
+	type ProxyImportRequest struct {
+		Data DataPayload `json:"data"`
+	}
+
+	var req ProxyImportRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if err := validateDataHeader(req.Data); err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	ctx := c.Request.Context()
+	result := DataImportResult{}
+
+	existingProxies, err := h.listProxiesFiltered(ctx, "", "", "")
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	proxyByKey := make(map[string]service.Proxy, len(existingProxies))
+	for i := range existingProxies {
+		p := existingProxies[i]
+		key := buildProxyKey(p.Protocol, p.Host, p.Port, p.Username, p.Password)
+		proxyByKey[key] = p
+	}
+
+	latencyProbeIDs := make([]int64, 0, len(req.Data.Proxies))
+	for i := range req.Data.Proxies {
+		item := req.Data.Proxies[i]
+		key := item.ProxyKey
+		if key == "" {
+			key = buildProxyKey(item.Protocol, item.Host, item.Port, item.Username, item.Password)
+		}
+
+		if err := validateDataProxy(item); err != nil {
+			result.ProxyFailed++
+			result.Errors = append(result.Errors, DataImportError{
+				Kind:     "proxy",
+				Name:     item.Name,
+				ProxyKey: key,
+				Message:  err.Error(),
+			})
+			continue
+		}
+
+		normalizedStatus := normalizeProxyStatus(item.Status)
+		if existing, ok := proxyByKey[key]; ok {
+			result.ProxyReused++
+			if normalizedStatus != "" && normalizedStatus != existing.Status {
+				if _, err := h.adminService.UpdateProxy(ctx, existing.ID, &service.UpdateProxyInput{Status: normalizedStatus}); err != nil {
+					result.Errors = append(result.Errors, DataImportError{
+						Kind:     "proxy",
+						Name:     item.Name,
+						ProxyKey: key,
+						Message:  "update status failed: " + err.Error(),
+					})
+				}
+			}
+			latencyProbeIDs = append(latencyProbeIDs, existing.ID)
+			continue
+		}
+
+		created, err := h.adminService.CreateProxy(ctx, &service.CreateProxyInput{
+			Name:     defaultProxyName(item.Name),
+			Protocol: item.Protocol,
+			Host:     item.Host,
+			Port:     item.Port,
+			Username: item.Username,
+			Password: item.Password,
+		})
+		if err != nil {
+			result.ProxyFailed++
+			result.Errors = append(result.Errors, DataImportError{
+				Kind:     "proxy",
+				Name:     item.Name,
+				ProxyKey: key,
+				Message:  err.Error(),
+			})
+			continue
+		}
+		result.ProxyCreated++
+		proxyByKey[key] = *created
+
+		if normalizedStatus != "" && normalizedStatus != created.Status {
+			if _, err := h.adminService.UpdateProxy(ctx, created.ID, &service.UpdateProxyInput{Status: normalizedStatus}); err != nil {
+				result.Errors = append(result.Errors, DataImportError{
+					Kind:     "proxy",
+					Name:     item.Name,
+					ProxyKey: key,
+					Message:  "update status failed: " + err.Error(),
+				})
+			}
+		}
+		// CreateProxy already triggers a latency probe, avoid double probing here.
+	}
+
+	if len(latencyProbeIDs) > 0 {
+		ids := append([]int64(nil), latencyProbeIDs...)
+		go func() {
+			for _, id := range ids {
+				_, _ = h.adminService.TestProxy(context.Background(), id)
+			}
+		}()
+	}
+
+	response.Success(c, result)
+}
+
+func (h *ProxyHandler) getProxiesByIDs(ctx context.Context, ids []int64) ([]service.Proxy, error) {
+	if len(ids) == 0 {
+		return []service.Proxy{}, nil
+	}
+	return h.adminService.GetProxiesByIDs(ctx, ids)
+}
+
+func parseProxyIDs(c *gin.Context) ([]int64, error) {
+	values := c.QueryArray("ids")
+	if len(values) == 0 {
+		raw := strings.TrimSpace(c.Query("ids"))
+		if raw != "" {
+			values = []string{raw}
+		}
+	}
+	if len(values) == 0 {
+		return nil, nil
+	}
+
+	ids := make([]int64, 0, len(values))
+	for _, item := range values {
+		for _, part := range strings.Split(item, ",") {
+			part = strings.TrimSpace(part)
+			if part == "" {
+				continue
+			}
+			id, err := strconv.ParseInt(part, 10, 64)
+			if err != nil || id <= 0 {
+				return nil, fmt.Errorf("invalid proxy id: %s", part)
+			}
+			ids = append(ids, id)
+		}
+	}
+	return ids, nil
+}
+
+func (h *ProxyHandler) listProxiesFiltered(ctx context.Context, protocol, status, search string) ([]service.Proxy, error) {
+	page := 1
+	pageSize := dataPageCap
+	var out []service.Proxy
+	for {
+		items, total, err := h.adminService.ListProxies(ctx, page, pageSize, protocol, status, search)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, items...)
+		if len(out) >= int(total) || len(items) == 0 {
+			break
+		}
+		page++
+	}
+	return out, nil
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/proxy_data_handler_test.go

@@ -0,0 +1,188 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type proxyDataResponse struct {
+	Code int         `json:"code"`
+	Data DataPayload `json:"data"`
+}
+
+type proxyImportResponse struct {
+	Code int              `json:"code"`
+	Data DataImportResult `json:"data"`
+}
+
+func setupProxyDataRouter() (*gin.Engine, *stubAdminService) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	adminSvc := newStubAdminService()
+
+	h := NewProxyHandler(adminSvc)
+	router.GET("/api/v1/admin/proxies/data", h.ExportData)
+	router.POST("/api/v1/admin/proxies/data", h.ImportData)
+
+	return router, adminSvc
+}
+
+func TestProxyExportDataRespectsFilters(t *testing.T) {
+	router, adminSvc := setupProxyDataRouter()
+
+	adminSvc.proxies = []service.Proxy{
+		{
+			ID:       1,
+			Name:     "proxy-a",
+			Protocol: "http",
+			Host:     "127.0.0.1",
+			Port:     8080,
+			Username: "user",
+			Password: "pass",
+			Status:   service.StatusActive,
+		},
+		{
+			ID:       2,
+			Name:     "proxy-b",
+			Protocol: "https",
+			Host:     "10.0.0.2",
+			Port:     443,
+			Username: "u",
+			Password: "p",
+			Status:   service.StatusDisabled,
+		},
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/proxies/data?protocol=https", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp proxyDataResponse
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+	require.Empty(t, resp.Data.Type)
+	require.Equal(t, 0, resp.Data.Version)
+	require.Len(t, resp.Data.Proxies, 1)
+	require.Len(t, resp.Data.Accounts, 0)
+	require.Equal(t, "https", resp.Data.Proxies[0].Protocol)
+}
+
+func TestProxyExportDataWithSelectedIDs(t *testing.T) {
+	router, adminSvc := setupProxyDataRouter()
+
+	adminSvc.proxies = []service.Proxy{
+		{
+			ID:       1,
+			Name:     "proxy-a",
+			Protocol: "http",
+			Host:     "127.0.0.1",
+			Port:     8080,
+			Username: "user",
+			Password: "pass",
+			Status:   service.StatusActive,
+		},
+		{
+			ID:       2,
+			Name:     "proxy-b",
+			Protocol: "https",
+			Host:     "10.0.0.2",
+			Port:     443,
+			Username: "u",
+			Password: "p",
+			Status:   service.StatusDisabled,
+		},
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/proxies/data?ids=2", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp proxyDataResponse
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+	require.Len(t, resp.Data.Proxies, 1)
+	require.Equal(t, "https", resp.Data.Proxies[0].Protocol)
+	require.Equal(t, "10.0.0.2", resp.Data.Proxies[0].Host)
+}
+
+func TestProxyImportDataReusesAndTriggersLatencyProbe(t *testing.T) {
+	router, adminSvc := setupProxyDataRouter()
+
+	adminSvc.proxies = []service.Proxy{
+		{
+			ID:       1,
+			Name:     "proxy-a",
+			Protocol: "http",
+			Host:     "127.0.0.1",
+			Port:     8080,
+			Username: "user",
+			Password: "pass",
+			Status:   service.StatusActive,
+		},
+	}
+
+	payload := map[string]any{
+		"data": map[string]any{
+			"type":    dataType,
+			"version": dataVersion,
+			"proxies": []map[string]any{
+				{
+					"proxy_key": "http|127.0.0.1|8080|user|pass",
+					"name":      "proxy-a",
+					"protocol":  "http",
+					"host":      "127.0.0.1",
+					"port":      8080,
+					"username":  "user",
+					"password":  "pass",
+					"status":    "inactive",
+				},
+				{
+					"proxy_key": "https|10.0.0.2|443|u|p",
+					"name":      "proxy-b",
+					"protocol":  "https",
+					"host":      "10.0.0.2",
+					"port":      443,
+					"username":  "u",
+					"password":  "p",
+					"status":    "active",
+				},
+			},
+			"accounts": []map[string]any{},
+		},
+	}
+
+	body, _ := json.Marshal(payload)
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/proxies/data", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var resp proxyImportResponse
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+	require.Equal(t, 1, resp.Data.ProxyCreated)
+	require.Equal(t, 1, resp.Data.ProxyReused)
+	require.Equal(t, 0, resp.Data.ProxyFailed)
+
+	adminSvc.mu.Lock()
+	updatedIDs := append([]int64(nil), adminSvc.updatedProxyIDs...)
+	adminSvc.mu.Unlock()
+	require.Contains(t, updatedIDs, int64(1))
+
+	require.Eventually(t, func() bool {
+		adminSvc.mu.Lock()
+		defer adminSvc.mu.Unlock()
+		return len(adminSvc.testedProxyIDs) == 1
+	}, time.Second, 10*time.Millisecond)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/proxy_handler.go

@@ -0,0 +1,367 @@
+package admin
+
+import (
+	"context"
+	"strconv"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ProxyHandler handles admin proxy management
+type ProxyHandler struct {
+	adminService service.AdminService
+}
+
+// NewProxyHandler creates a new admin proxy handler
+func NewProxyHandler(adminService service.AdminService) *ProxyHandler {
+	return &ProxyHandler{
+		adminService: adminService,
+	}
+}
+
+// CreateProxyRequest represents create proxy request
+type CreateProxyRequest struct {
+	Name     string `json:"name" binding:"required"`
+	Protocol string `json:"protocol" binding:"required,oneof=http https socks5 socks5h"`
+	Host     string `json:"host" binding:"required"`
+	Port     int    `json:"port" binding:"required,min=1,max=65535"`
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+// UpdateProxyRequest represents update proxy request
+type UpdateProxyRequest struct {
+	Name     string `json:"name"`
+	Protocol string `json:"protocol" binding:"omitempty,oneof=http https socks5 socks5h"`
+	Host     string `json:"host"`
+	Port     int    `json:"port" binding:"omitempty,min=1,max=65535"`
+	Username string `json:"username"`
+	Password string `json:"password"`
+	Status   string `json:"status" binding:"omitempty,oneof=active inactive"`
+}
+
+// List handles listing all proxies with pagination
+// GET /api/v1/admin/proxies
+func (h *ProxyHandler) List(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+	protocol := c.Query("protocol")
+	status := c.Query("status")
+	search := c.Query("search")
+	// 标准化和验证 search 参数
+	search = strings.TrimSpace(search)
+	if len(search) > 100 {
+		search = search[:100]
+	}
+
+	proxies, total, err := h.adminService.ListProxiesWithAccountCount(c.Request.Context(), page, pageSize, protocol, status, search)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.AdminProxyWithAccountCount, 0, len(proxies))
+	for i := range proxies {
+		out = append(out, *dto.ProxyWithAccountCountFromServiceAdmin(&proxies[i]))
+	}
+	response.Paginated(c, out, total, page, pageSize)
+}
+
+// GetAll handles getting all active proxies without pagination
+// GET /api/v1/admin/proxies/all
+// Optional query param: with_count=true to include account count per proxy
+func (h *ProxyHandler) GetAll(c *gin.Context) {
+	withCount := c.Query("with_count") == "true"
+
+	if withCount {
+		proxies, err := h.adminService.GetAllProxiesWithAccountCount(c.Request.Context())
+		if err != nil {
+			response.ErrorFrom(c, err)
+			return
+		}
+		out := make([]dto.AdminProxyWithAccountCount, 0, len(proxies))
+		for i := range proxies {
+			out = append(out, *dto.ProxyWithAccountCountFromServiceAdmin(&proxies[i]))
+		}
+		response.Success(c, out)
+		return
+	}
+
+	proxies, err := h.adminService.GetAllProxies(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.AdminProxy, 0, len(proxies))
+	for i := range proxies {
+		out = append(out, *dto.ProxyFromServiceAdmin(&proxies[i]))
+	}
+	response.Success(c, out)
+}
+
+// GetByID handles getting a proxy by ID
+// GET /api/v1/admin/proxies/:id
+func (h *ProxyHandler) GetByID(c *gin.Context) {
+	proxyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid proxy ID")
+		return
+	}
+
+	proxy, err := h.adminService.GetProxy(c.Request.Context(), proxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.ProxyFromServiceAdmin(proxy))
+}
+
+// Create handles creating a new proxy
+// POST /api/v1/admin/proxies
+func (h *ProxyHandler) Create(c *gin.Context) {
+	var req CreateProxyRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	executeAdminIdempotentJSON(c, "admin.proxies.create", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		proxy, err := h.adminService.CreateProxy(ctx, &service.CreateProxyInput{
+			Name:     strings.TrimSpace(req.Name),
+			Protocol: strings.TrimSpace(req.Protocol),
+			Host:     strings.TrimSpace(req.Host),
+			Port:     req.Port,
+			Username: strings.TrimSpace(req.Username),
+			Password: strings.TrimSpace(req.Password),
+		})
+		if err != nil {
+			return nil, err
+		}
+		return dto.ProxyFromServiceAdmin(proxy), nil
+	})
+}
+
+// Update handles updating a proxy
+// PUT /api/v1/admin/proxies/:id
+func (h *ProxyHandler) Update(c *gin.Context) {
+	proxyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid proxy ID")
+		return
+	}
+
+	var req UpdateProxyRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	proxy, err := h.adminService.UpdateProxy(c.Request.Context(), proxyID, &service.UpdateProxyInput{
+		Name:     strings.TrimSpace(req.Name),
+		Protocol: strings.TrimSpace(req.Protocol),
+		Host:     strings.TrimSpace(req.Host),
+		Port:     req.Port,
+		Username: strings.TrimSpace(req.Username),
+		Password: strings.TrimSpace(req.Password),
+		Status:   strings.TrimSpace(req.Status),
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.ProxyFromServiceAdmin(proxy))
+}
+
+// Delete handles deleting a proxy
+// DELETE /api/v1/admin/proxies/:id
+func (h *ProxyHandler) Delete(c *gin.Context) {
+	proxyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid proxy ID")
+		return
+	}
+
+	err = h.adminService.DeleteProxy(c.Request.Context(), proxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Proxy deleted successfully"})
+}
+
+// BatchDelete handles batch deleting proxies
+// POST /api/v1/admin/proxies/batch-delete
+func (h *ProxyHandler) BatchDelete(c *gin.Context) {
+	type BatchDeleteRequest struct {
+		IDs []int64 `json:"ids" binding:"required,min=1"`
+	}
+
+	var req BatchDeleteRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	result, err := h.adminService.BatchDeleteProxies(c.Request.Context(), req.IDs)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, result)
+}
+
+// Test handles testing proxy connectivity
+// POST /api/v1/admin/proxies/:id/test
+func (h *ProxyHandler) Test(c *gin.Context) {
+	proxyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid proxy ID")
+		return
+	}
+
+	result, err := h.adminService.TestProxy(c.Request.Context(), proxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, result)
+}
+
+// CheckQuality handles checking proxy quality across common AI targets.
+// POST /api/v1/admin/proxies/:id/quality-check
+func (h *ProxyHandler) CheckQuality(c *gin.Context) {
+	proxyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid proxy ID")
+		return
+	}
+
+	result, err := h.adminService.CheckProxyQuality(c.Request.Context(), proxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, result)
+}
+
+// GetStats handles getting proxy statistics
+// GET /api/v1/admin/proxies/:id/stats
+func (h *ProxyHandler) GetStats(c *gin.Context) {
+	proxyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid proxy ID")
+		return
+	}
+
+	// Return mock data for now
+	_ = proxyID
+	response.Success(c, gin.H{
+		"total_accounts":  0,
+		"active_accounts": 0,
+		"total_requests":  0,
+		"success_rate":    100.0,
+		"average_latency": 0,
+	})
+}
+
+// GetProxyAccounts handles getting accounts using a proxy
+// GET /api/v1/admin/proxies/:id/accounts
+func (h *ProxyHandler) GetProxyAccounts(c *gin.Context) {
+	proxyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid proxy ID")
+		return
+	}
+
+	accounts, err := h.adminService.GetProxyAccounts(c.Request.Context(), proxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.ProxyAccountSummary, 0, len(accounts))
+	for i := range accounts {
+		out = append(out, *dto.ProxyAccountSummaryFromService(&accounts[i]))
+	}
+	response.Success(c, out)
+}
+
+// BatchCreateProxyItem represents a single proxy in batch create request
+type BatchCreateProxyItem struct {
+	Protocol string `json:"protocol" binding:"required,oneof=http https socks5 socks5h"`
+	Host     string `json:"host" binding:"required"`
+	Port     int    `json:"port" binding:"required,min=1,max=65535"`
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+// BatchCreateRequest represents batch create proxies request
+type BatchCreateRequest struct {
+	Proxies []BatchCreateProxyItem `json:"proxies" binding:"required,min=1"`
+}
+
+// BatchCreate handles batch creating proxies
+// POST /api/v1/admin/proxies/batch
+func (h *ProxyHandler) BatchCreate(c *gin.Context) {
+	var req BatchCreateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	created := 0
+	skipped := 0
+
+	for _, item := range req.Proxies {
+		// Trim all string fields
+		host := strings.TrimSpace(item.Host)
+		protocol := strings.TrimSpace(item.Protocol)
+		username := strings.TrimSpace(item.Username)
+		password := strings.TrimSpace(item.Password)
+
+		// Check for duplicates (same host, port, username, password)
+		exists, err := h.adminService.CheckProxyExists(c.Request.Context(), host, item.Port, username, password)
+		if err != nil {
+			response.ErrorFrom(c, err)
+			return
+		}
+
+		if exists {
+			skipped++
+			continue
+		}
+
+		// Create proxy with default name
+		_, err = h.adminService.CreateProxy(c.Request.Context(), &service.CreateProxyInput{
+			Name:     "default",
+			Protocol: protocol,
+			Host:     host,
+			Port:     item.Port,
+			Username: username,
+			Password: password,
+		})
+		if err != nil {
+			// If creation fails due to duplicate, count as skipped
+			skipped++
+			continue
+		}
+
+		created++
+	}
+
+	response.Success(c, gin.H{
+		"created": created,
+		"skipped": skipped,
+	})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/redeem_handler.go

@@ -0,0 +1,360 @@
+package admin
+
+import (
+	"bytes"
+	"context"
+	"encoding/csv"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RedeemHandler handles admin redeem code management
+type RedeemHandler struct {
+	adminService  service.AdminService
+	redeemService *service.RedeemService
+}
+
+// NewRedeemHandler creates a new admin redeem handler
+func NewRedeemHandler(adminService service.AdminService, redeemService *service.RedeemService) *RedeemHandler {
+	return &RedeemHandler{
+		adminService:  adminService,
+		redeemService: redeemService,
+	}
+}
+
+// GenerateRedeemCodesRequest represents generate redeem codes request
+type GenerateRedeemCodesRequest struct {
+	Count        int     `json:"count" binding:"required,min=1,max=100"`
+	Type         string  `json:"type" binding:"required,oneof=balance concurrency subscription invitation"`
+	Value        float64 `json:"value" binding:"min=0"`
+	GroupID      *int64  `json:"group_id"`                                    // 订阅类型必填
+	ValidityDays int     `json:"validity_days" binding:"omitempty,max=36500"` // 订阅类型使用，默认30天，最大100年
+}
+
+// CreateAndRedeemCodeRequest represents creating a fixed code and redeeming it for a target user.
+// Type 为 omitempty 而非 required 是为了向后兼容旧版调用方（不传 type 时默认 balance）。
+type CreateAndRedeemCodeRequest struct {
+	Code         string  `json:"code" binding:"required,min=3,max=128"`
+	Type         string  `json:"type" binding:"omitempty,oneof=balance concurrency subscription invitation"` // 不传时默认 balance（向后兼容）
+	Value        float64 `json:"value" binding:"required,gt=0"`
+	UserID       int64   `json:"user_id" binding:"required,gt=0"`
+	GroupID      *int64  `json:"group_id"`                                    // subscription 类型必填
+	ValidityDays int     `json:"validity_days" binding:"omitempty,max=36500"` // subscription 类型必填，>0
+	Notes        string  `json:"notes"`
+}
+
+// List handles listing all redeem codes with pagination
+// GET /api/v1/admin/redeem-codes
+func (h *RedeemHandler) List(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+	codeType := c.Query("type")
+	status := c.Query("status")
+	search := c.Query("search")
+	// 标准化和验证 search 参数
+	search = strings.TrimSpace(search)
+	if len(search) > 100 {
+		search = search[:100]
+	}
+
+	codes, total, err := h.adminService.ListRedeemCodes(c.Request.Context(), page, pageSize, codeType, status, search)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.AdminRedeemCode, 0, len(codes))
+	for i := range codes {
+		out = append(out, *dto.RedeemCodeFromServiceAdmin(&codes[i]))
+	}
+	response.Paginated(c, out, total, page, pageSize)
+}
+
+// GetByID handles getting a redeem code by ID
+// GET /api/v1/admin/redeem-codes/:id
+func (h *RedeemHandler) GetByID(c *gin.Context) {
+	codeID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid redeem code ID")
+		return
+	}
+
+	code, err := h.adminService.GetRedeemCode(c.Request.Context(), codeID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.RedeemCodeFromServiceAdmin(code))
+}
+
+// Generate handles generating new redeem codes
+// POST /api/v1/admin/redeem-codes/generate
+func (h *RedeemHandler) Generate(c *gin.Context) {
+	var req GenerateRedeemCodesRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	executeAdminIdempotentJSON(c, "admin.redeem_codes.generate", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		codes, execErr := h.adminService.GenerateRedeemCodes(ctx, &service.GenerateRedeemCodesInput{
+			Count:        req.Count,
+			Type:         req.Type,
+			Value:        req.Value,
+			GroupID:      req.GroupID,
+			ValidityDays: req.ValidityDays,
+		})
+		if execErr != nil {
+			return nil, execErr
+		}
+
+		out := make([]dto.AdminRedeemCode, 0, len(codes))
+		for i := range codes {
+			out = append(out, *dto.RedeemCodeFromServiceAdmin(&codes[i]))
+		}
+		return out, nil
+	})
+}
+
+// CreateAndRedeem creates a fixed redeem code and redeems it for a target user in one step.
+// POST /api/v1/admin/redeem-codes/create-and-redeem
+func (h *RedeemHandler) CreateAndRedeem(c *gin.Context) {
+	if h.redeemService == nil {
+		response.InternalError(c, "redeem service not configured")
+		return
+	}
+
+	var req CreateAndRedeemCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	req.Code = strings.TrimSpace(req.Code)
+	// 向后兼容：旧版调用方（如 Sub2ApiPay）不传 type 字段，默认当作 balance 充值处理。
+	// 请勿删除此默认值逻辑，否则会导致旧版调用方 400 报错。
+	if req.Type == "" {
+		req.Type = "balance"
+	}
+
+	if req.Type == "subscription" {
+		if req.GroupID == nil {
+			response.BadRequest(c, "group_id is required for subscription type")
+			return
+		}
+		if req.ValidityDays <= 0 {
+			response.BadRequest(c, "validity_days must be greater than 0 for subscription type")
+			return
+		}
+	}
+
+	executeAdminIdempotentJSON(c, "admin.redeem_codes.create_and_redeem", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		existing, err := h.redeemService.GetByCode(ctx, req.Code)
+		if err == nil {
+			return h.resolveCreateAndRedeemExisting(ctx, existing, req.UserID)
+		}
+		if !errors.Is(err, service.ErrRedeemCodeNotFound) {
+			return nil, err
+		}
+
+		createErr := h.redeemService.CreateCode(ctx, &service.RedeemCode{
+			Code:         req.Code,
+			Type:         req.Type,
+			Value:        req.Value,
+			Status:       service.StatusUnused,
+			Notes:        req.Notes,
+			GroupID:      req.GroupID,
+			ValidityDays: req.ValidityDays,
+		})
+		if createErr != nil {
+			// Unique code race: if code now exists, use idempotent semantics by used_by.
+			existingAfterCreateErr, getErr := h.redeemService.GetByCode(ctx, req.Code)
+			if getErr == nil {
+				return h.resolveCreateAndRedeemExisting(ctx, existingAfterCreateErr, req.UserID)
+			}
+			return nil, createErr
+		}
+
+		redeemed, redeemErr := h.redeemService.Redeem(ctx, req.UserID, req.Code)
+		if redeemErr != nil {
+			return nil, redeemErr
+		}
+		return gin.H{"redeem_code": dto.RedeemCodeFromServiceAdmin(redeemed)}, nil
+	})
+}
+
+func (h *RedeemHandler) resolveCreateAndRedeemExisting(ctx context.Context, existing *service.RedeemCode, userID int64) (any, error) {
+	if existing == nil {
+		return nil, infraerrors.Conflict("REDEEM_CODE_CONFLICT", "redeem code conflict")
+	}
+
+	// If previous run created the code but crashed before redeem, redeem it now.
+	if existing.CanUse() {
+		redeemed, err := h.redeemService.Redeem(ctx, userID, existing.Code)
+		if err == nil {
+			return gin.H{"redeem_code": dto.RedeemCodeFromServiceAdmin(redeemed)}, nil
+		}
+		if !errors.Is(err, service.ErrRedeemCodeUsed) {
+			return nil, err
+		}
+		latest, getErr := h.redeemService.GetByCode(ctx, existing.Code)
+		if getErr == nil {
+			existing = latest
+		}
+	}
+
+	if existing.UsedBy != nil && *existing.UsedBy == userID {
+		return gin.H{"redeem_code": dto.RedeemCodeFromServiceAdmin(existing)}, nil
+	}
+
+	return nil, infraerrors.Conflict("REDEEM_CODE_CONFLICT", "redeem code already used by another user")
+}
+
+// Delete handles deleting a redeem code
+// DELETE /api/v1/admin/redeem-codes/:id
+func (h *RedeemHandler) Delete(c *gin.Context) {
+	codeID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid redeem code ID")
+		return
+	}
+
+	err = h.adminService.DeleteRedeemCode(c.Request.Context(), codeID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Redeem code deleted successfully"})
+}
+
+// BatchDelete handles batch deleting redeem codes
+// POST /api/v1/admin/redeem-codes/batch-delete
+func (h *RedeemHandler) BatchDelete(c *gin.Context) {
+	var req struct {
+		IDs []int64 `json:"ids" binding:"required,min=1"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	deleted, err := h.adminService.BatchDeleteRedeemCodes(c.Request.Context(), req.IDs)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{
+		"deleted": deleted,
+		"message": "Redeem codes deleted successfully",
+	})
+}
+
+// Expire handles expiring a redeem code
+// POST /api/v1/admin/redeem-codes/:id/expire
+func (h *RedeemHandler) Expire(c *gin.Context) {
+	codeID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid redeem code ID")
+		return
+	}
+
+	code, err := h.adminService.ExpireRedeemCode(c.Request.Context(), codeID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.RedeemCodeFromServiceAdmin(code))
+}
+
+// GetStats handles getting redeem code statistics
+// GET /api/v1/admin/redeem-codes/stats
+func (h *RedeemHandler) GetStats(c *gin.Context) {
+	// Return mock data for now
+	response.Success(c, gin.H{
+		"total_codes":             0,
+		"active_codes":            0,
+		"used_codes":              0,
+		"expired_codes":           0,
+		"total_value_distributed": 0.0,
+		"by_type": gin.H{
+			"balance":     0,
+			"concurrency": 0,
+			"trial":       0,
+		},
+	})
+}
+
+// Export handles exporting redeem codes to CSV
+// GET /api/v1/admin/redeem-codes/export
+func (h *RedeemHandler) Export(c *gin.Context) {
+	codeType := c.Query("type")
+	status := c.Query("status")
+
+	// Get all codes without pagination (use large page size)
+	codes, _, err := h.adminService.ListRedeemCodes(c.Request.Context(), 1, 10000, codeType, status, "")
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Create CSV buffer
+	var buf bytes.Buffer
+	writer := csv.NewWriter(&buf)
+
+	// Write header
+	if err := writer.Write([]string{"id", "code", "type", "value", "status", "used_by", "used_by_email", "used_at", "created_at"}); err != nil {
+		response.InternalError(c, "Failed to export redeem codes: "+err.Error())
+		return
+	}
+
+	// Write data rows
+	for _, code := range codes {
+		usedBy := ""
+		if code.UsedBy != nil {
+			usedBy = fmt.Sprintf("%d", *code.UsedBy)
+		}
+		usedByEmail := ""
+		if code.User != nil {
+			usedByEmail = code.User.Email
+		}
+		usedAt := ""
+		if code.UsedAt != nil {
+			usedAt = code.UsedAt.Format("2006-01-02 15:04:05")
+		}
+		if err := writer.Write([]string{
+			fmt.Sprintf("%d", code.ID),
+			code.Code,
+			code.Type,
+			fmt.Sprintf("%.2f", code.Value),
+			code.Status,
+			usedBy,
+			usedByEmail,
+			usedAt,
+			code.CreatedAt.Format("2006-01-02 15:04:05"),
+		}); err != nil {
+			response.InternalError(c, "Failed to export redeem codes: "+err.Error())
+			return
+		}
+	}
+
+	writer.Flush()
+	if err := writer.Error(); err != nil {
+		response.InternalError(c, "Failed to export redeem codes: "+err.Error())
+		return
+	}
+
+	c.Header("Content-Type", "text/csv")
+	c.Header("Content-Disposition", "attachment; filename=redeem_codes.csv")
+	c.Data(200, "text/csv", buf.Bytes())
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/redeem_handler_test.go

@@ -0,0 +1,135 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// newCreateAndRedeemHandler creates a RedeemHandler with a non-nil (but minimal)
+// RedeemService so that CreateAndRedeem's nil guard passes and we can test the
+// parameter-validation layer that runs before any service call.
+func newCreateAndRedeemHandler() *RedeemHandler {
+	return &RedeemHandler{
+		adminService:  newStubAdminService(),
+		redeemService: &service.RedeemService{}, // non-nil to pass nil guard
+	}
+}
+
+// postCreateAndRedeemValidation calls CreateAndRedeem and returns the response
+// status code. For cases that pass validation and proceed into the service layer,
+// a panic may occur (because RedeemService internals are nil); this is expected
+// and treated as "validation passed" (returns 0 to indicate panic).
+func postCreateAndRedeemValidation(t *testing.T, handler *RedeemHandler, body any) (code int) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+
+	jsonBytes, err := json.Marshal(body)
+	require.NoError(t, err)
+	c.Request, _ = http.NewRequest(http.MethodPost, "/api/v1/admin/redeem-codes/create-and-redeem", bytes.NewReader(jsonBytes))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	defer func() {
+		if r := recover(); r != nil {
+			// Panic means we passed validation and entered service layer (expected for minimal stub).
+			code = 0
+		}
+	}()
+	handler.CreateAndRedeem(c)
+	return w.Code
+}
+
+func TestCreateAndRedeem_TypeDefaultsToBalance(t *testing.T) {
+	// 不传 type 字段时应默认 balance，不触发 subscription 校验。
+	// 验证通过后进入 service 层会 panic（返回 0），说明默认值生效。
+	h := newCreateAndRedeemHandler()
+	code := postCreateAndRedeemValidation(t, h, map[string]any{
+		"code":    "test-balance-default",
+		"value":   10.0,
+		"user_id": 1,
+	})
+
+	assert.NotEqual(t, http.StatusBadRequest, code,
+		"omitting type should default to balance and pass validation")
+}
+
+func TestCreateAndRedeem_SubscriptionRequiresGroupID(t *testing.T) {
+	h := newCreateAndRedeemHandler()
+	code := postCreateAndRedeemValidation(t, h, map[string]any{
+		"code":          "test-sub-no-group",
+		"type":          "subscription",
+		"value":         29.9,
+		"user_id":       1,
+		"validity_days": 30,
+		// group_id 缺失
+	})
+
+	assert.Equal(t, http.StatusBadRequest, code)
+}
+
+func TestCreateAndRedeem_SubscriptionRequiresPositiveValidityDays(t *testing.T) {
+	groupID := int64(5)
+	h := newCreateAndRedeemHandler()
+
+	cases := []struct {
+		name         string
+		validityDays int
+	}{
+		{"zero", 0},
+		{"negative", -1},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			code := postCreateAndRedeemValidation(t, h, map[string]any{
+				"code":          "test-sub-bad-days-" + tc.name,
+				"type":          "subscription",
+				"value":         29.9,
+				"user_id":       1,
+				"group_id":      groupID,
+				"validity_days": tc.validityDays,
+			})
+
+			assert.Equal(t, http.StatusBadRequest, code)
+		})
+	}
+}
+
+func TestCreateAndRedeem_SubscriptionValidParamsPassValidation(t *testing.T) {
+	groupID := int64(5)
+	h := newCreateAndRedeemHandler()
+	code := postCreateAndRedeemValidation(t, h, map[string]any{
+		"code":          "test-sub-valid",
+		"type":          "subscription",
+		"value":         29.9,
+		"user_id":       1,
+		"group_id":      groupID,
+		"validity_days": 31,
+	})
+
+	assert.NotEqual(t, http.StatusBadRequest, code,
+		"valid subscription params should pass validation")
+}
+
+func TestCreateAndRedeem_BalanceIgnoresSubscriptionFields(t *testing.T) {
+	h := newCreateAndRedeemHandler()
+	// balance 类型不传 group_id 和 validity_days，不应报 400
+	code := postCreateAndRedeemValidation(t, h, map[string]any{
+		"code":    "test-balance-no-extras",
+		"type":    "balance",
+		"value":   50.0,
+		"user_id": 1,
+	})
+
+	assert.NotEqual(t, http.StatusBadRequest, code,
+		"balance type should not require group_id or validity_days")
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/scheduled_test_handler.go

@@ -0,0 +1,163 @@
+package admin
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+// ScheduledTestHandler handles admin scheduled-test-plan management.
+type ScheduledTestHandler struct {
+	scheduledTestSvc *service.ScheduledTestService
+}
+
+// NewScheduledTestHandler creates a new ScheduledTestHandler.
+func NewScheduledTestHandler(scheduledTestSvc *service.ScheduledTestService) *ScheduledTestHandler {
+	return &ScheduledTestHandler{scheduledTestSvc: scheduledTestSvc}
+}
+
+type createScheduledTestPlanRequest struct {
+	AccountID      int64  `json:"account_id" binding:"required"`
+	ModelID        string `json:"model_id"`
+	CronExpression string `json:"cron_expression" binding:"required"`
+	Enabled        *bool  `json:"enabled"`
+	MaxResults     int    `json:"max_results"`
+	AutoRecover    *bool  `json:"auto_recover"`
+}
+
+type updateScheduledTestPlanRequest struct {
+	ModelID        string `json:"model_id"`
+	CronExpression string `json:"cron_expression"`
+	Enabled        *bool  `json:"enabled"`
+	MaxResults     int    `json:"max_results"`
+	AutoRecover    *bool  `json:"auto_recover"`
+}
+
+// ListByAccount GET /admin/accounts/:id/scheduled-test-plans
+func (h *ScheduledTestHandler) ListByAccount(c *gin.Context) {
+	accountID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "invalid account id")
+		return
+	}
+
+	plans, err := h.scheduledTestSvc.ListPlansByAccount(c.Request.Context(), accountID)
+	if err != nil {
+		response.InternalError(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, plans)
+}
+
+// Create POST /admin/scheduled-test-plans
+func (h *ScheduledTestHandler) Create(c *gin.Context) {
+	var req createScheduledTestPlanRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	plan := &service.ScheduledTestPlan{
+		AccountID:      req.AccountID,
+		ModelID:        req.ModelID,
+		CronExpression: req.CronExpression,
+		Enabled:        true,
+		MaxResults:     req.MaxResults,
+	}
+	if req.Enabled != nil {
+		plan.Enabled = *req.Enabled
+	}
+	if req.AutoRecover != nil {
+		plan.AutoRecover = *req.AutoRecover
+	}
+
+	created, err := h.scheduledTestSvc.CreatePlan(c.Request.Context(), plan)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, created)
+}
+
+// Update PUT /admin/scheduled-test-plans/:id
+func (h *ScheduledTestHandler) Update(c *gin.Context) {
+	planID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "invalid plan id")
+		return
+	}
+
+	existing, err := h.scheduledTestSvc.GetPlan(c.Request.Context(), planID)
+	if err != nil {
+		response.NotFound(c, "plan not found")
+		return
+	}
+
+	var req updateScheduledTestPlanRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	if req.ModelID != "" {
+		existing.ModelID = req.ModelID
+	}
+	if req.CronExpression != "" {
+		existing.CronExpression = req.CronExpression
+	}
+	if req.Enabled != nil {
+		existing.Enabled = *req.Enabled
+	}
+	if req.MaxResults > 0 {
+		existing.MaxResults = req.MaxResults
+	}
+	if req.AutoRecover != nil {
+		existing.AutoRecover = *req.AutoRecover
+	}
+
+	updated, err := h.scheduledTestSvc.UpdatePlan(c.Request.Context(), existing)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, updated)
+}
+
+// Delete DELETE /admin/scheduled-test-plans/:id
+func (h *ScheduledTestHandler) Delete(c *gin.Context) {
+	planID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "invalid plan id")
+		return
+	}
+
+	if err := h.scheduledTestSvc.DeletePlan(c.Request.Context(), planID); err != nil {
+		response.InternalError(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "deleted"})
+}
+
+// ListResults GET /admin/scheduled-test-plans/:id/results
+func (h *ScheduledTestHandler) ListResults(c *gin.Context) {
+	planID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "invalid plan id")
+		return
+	}
+
+	limit := 50
+	if l, err := strconv.Atoi(c.Query("limit")); err == nil && l > 0 {
+		limit = l
+	}
+
+	results, err := h.scheduledTestSvc.ListResults(c.Request.Context(), planID, limit)
+	if err != nil {
+		response.InternalError(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, results)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/search_truncate_test.go

@@ -0,0 +1,97 @@
+//go:build unit
+
+package admin
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// truncateSearchByRune 模拟 user_handler.go 中的 search 截断逻辑
+func truncateSearchByRune(search string, maxRunes int) string {
+	if runes := []rune(search); len(runes) > maxRunes {
+		return string(runes[:maxRunes])
+	}
+	return search
+}
+
+func TestTruncateSearchByRune(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		maxRunes int
+		wantLen  int // 期望的 rune 长度
+	}{
+		{
+			name:     "纯中文超长",
+			input:    string(make([]rune, 150)),
+			maxRunes: 100,
+			wantLen:  100,
+		},
+		{
+			name:     "纯 ASCII 超长",
+			input:    string(make([]byte, 150)),
+			maxRunes: 100,
+			wantLen:  100,
+		},
+		{
+			name:     "空字符串",
+			input:    "",
+			maxRunes: 100,
+			wantLen:  0,
+		},
+		{
+			name:     "恰好 100 个字符",
+			input:    string(make([]rune, 100)),
+			maxRunes: 100,
+			wantLen:  100,
+		},
+		{
+			name:     "不足 100 字符不截断",
+			input:    "hello世界",
+			maxRunes: 100,
+			wantLen:  7,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := truncateSearchByRune(tc.input, tc.maxRunes)
+			require.Equal(t, tc.wantLen, len([]rune(result)))
+		})
+	}
+}
+
+func TestTruncateSearchByRune_PreservesMultibyte(t *testing.T) {
+	// 101 个中文字符，截断到 100 个后应该仍然是有效 UTF-8
+	input := ""
+	for i := 0; i < 101; i++ {
+		input += "中"
+	}
+	result := truncateSearchByRune(input, 100)
+
+	require.Equal(t, 100, len([]rune(result)))
+	// 验证截断结果是有效的 UTF-8（每个中文字符 3 字节）
+	require.Equal(t, 300, len(result))
+}
+
+func TestTruncateSearchByRune_MixedASCIIAndMultibyte(t *testing.T) {
+	// 50 个 ASCII + 51 个中文 = 101 个 rune
+	input := ""
+	for i := 0; i < 50; i++ {
+		input += "a"
+	}
+	for i := 0; i < 51; i++ {
+		input += "中"
+	}
+	result := truncateSearchByRune(input, 100)
+
+	runes := []rune(result)
+	require.Equal(t, 100, len(runes))
+	// 前 50 个应该是 'a'，后 50 个应该是 '中'
+	require.Equal(t, 'a', runes[0])
+	require.Equal(t, 'a', runes[49])
+	require.Equal(t, '中', runes[50])
+	require.Equal(t, '中', runes[99])
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/snapshot_cache.go

@@ -0,0 +1,138 @@
+package admin
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"strings"
+	"sync"
+	"time"
+
+	"golang.org/x/sync/singleflight"
+)
+
+type snapshotCacheEntry struct {
+	ETag      string
+	Payload   any
+	ExpiresAt time.Time
+}
+
+type snapshotCache struct {
+	mu    sync.RWMutex
+	ttl   time.Duration
+	items map[string]snapshotCacheEntry
+	sf    singleflight.Group
+}
+
+type snapshotCacheLoadResult struct {
+	Entry snapshotCacheEntry
+	Hit   bool
+}
+
+func newSnapshotCache(ttl time.Duration) *snapshotCache {
+	if ttl <= 0 {
+		ttl = 30 * time.Second
+	}
+	return &snapshotCache{
+		ttl:   ttl,
+		items: make(map[string]snapshotCacheEntry),
+	}
+}
+
+func (c *snapshotCache) Get(key string) (snapshotCacheEntry, bool) {
+	if c == nil || key == "" {
+		return snapshotCacheEntry{}, false
+	}
+	now := time.Now()
+
+	c.mu.RLock()
+	entry, ok := c.items[key]
+	c.mu.RUnlock()
+	if !ok {
+		return snapshotCacheEntry{}, false
+	}
+	if now.After(entry.ExpiresAt) {
+		c.mu.Lock()
+		delete(c.items, key)
+		c.mu.Unlock()
+		return snapshotCacheEntry{}, false
+	}
+	return entry, true
+}
+
+func (c *snapshotCache) Set(key string, payload any) snapshotCacheEntry {
+	if c == nil {
+		return snapshotCacheEntry{}
+	}
+	entry := snapshotCacheEntry{
+		ETag:      buildETagFromAny(payload),
+		Payload:   payload,
+		ExpiresAt: time.Now().Add(c.ttl),
+	}
+	if key == "" {
+		return entry
+	}
+	c.mu.Lock()
+	c.items[key] = entry
+	c.mu.Unlock()
+	return entry
+}
+
+func (c *snapshotCache) GetOrLoad(key string, load func() (any, error)) (snapshotCacheEntry, bool, error) {
+	if load == nil {
+		return snapshotCacheEntry{}, false, nil
+	}
+	if entry, ok := c.Get(key); ok {
+		return entry, true, nil
+	}
+	if c == nil || key == "" {
+		payload, err := load()
+		if err != nil {
+			return snapshotCacheEntry{}, false, err
+		}
+		return c.Set(key, payload), false, nil
+	}
+
+	value, err, _ := c.sf.Do(key, func() (any, error) {
+		if entry, ok := c.Get(key); ok {
+			return snapshotCacheLoadResult{Entry: entry, Hit: true}, nil
+		}
+		payload, err := load()
+		if err != nil {
+			return nil, err
+		}
+		return snapshotCacheLoadResult{Entry: c.Set(key, payload), Hit: false}, nil
+	})
+	if err != nil {
+		return snapshotCacheEntry{}, false, err
+	}
+	result, ok := value.(snapshotCacheLoadResult)
+	if !ok {
+		return snapshotCacheEntry{}, false, nil
+	}
+	return result.Entry, result.Hit, nil
+}
+
+func buildETagFromAny(payload any) string {
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return ""
+	}
+	sum := sha256.Sum256(raw)
+	return "\"" + hex.EncodeToString(sum[:]) + "\""
+}
+
+func parseBoolQueryWithDefault(raw string, def bool) bool {
+	value := strings.TrimSpace(strings.ToLower(raw))
+	if value == "" {
+		return def
+	}
+	switch value {
+	case "1", "true", "yes", "on":
+		return true
+	case "0", "false", "no", "off":
+		return false
+	default:
+		return def
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/snapshot_cache_test.go

@@ -0,0 +1,185 @@
+//go:build unit
+
+package admin
+
+import (
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestSnapshotCache_SetAndGet(t *testing.T) {
+	c := newSnapshotCache(5 * time.Second)
+
+	entry := c.Set("key1", map[string]string{"hello": "world"})
+	require.NotEmpty(t, entry.ETag)
+	require.NotNil(t, entry.Payload)
+
+	got, ok := c.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, entry.ETag, got.ETag)
+}
+
+func TestSnapshotCache_Expiration(t *testing.T) {
+	c := newSnapshotCache(1 * time.Millisecond)
+
+	c.Set("key1", "value")
+	time.Sleep(5 * time.Millisecond)
+
+	_, ok := c.Get("key1")
+	require.False(t, ok, "expired entry should not be returned")
+}
+
+func TestSnapshotCache_GetEmptyKey(t *testing.T) {
+	c := newSnapshotCache(5 * time.Second)
+	_, ok := c.Get("")
+	require.False(t, ok)
+}
+
+func TestSnapshotCache_GetMiss(t *testing.T) {
+	c := newSnapshotCache(5 * time.Second)
+	_, ok := c.Get("nonexistent")
+	require.False(t, ok)
+}
+
+func TestSnapshotCache_NilReceiver(t *testing.T) {
+	var c *snapshotCache
+	_, ok := c.Get("key")
+	require.False(t, ok)
+
+	entry := c.Set("key", "value")
+	require.Empty(t, entry.ETag)
+}
+
+func TestSnapshotCache_SetEmptyKey(t *testing.T) {
+	c := newSnapshotCache(5 * time.Second)
+
+	// Set with empty key should return entry but not store it
+	entry := c.Set("", "value")
+	require.NotEmpty(t, entry.ETag)
+
+	_, ok := c.Get("")
+	require.False(t, ok)
+}
+
+func TestSnapshotCache_DefaultTTL(t *testing.T) {
+	c := newSnapshotCache(0)
+	require.Equal(t, 30*time.Second, c.ttl)
+
+	c2 := newSnapshotCache(-1 * time.Second)
+	require.Equal(t, 30*time.Second, c2.ttl)
+}
+
+func TestSnapshotCache_ETagDeterministic(t *testing.T) {
+	c := newSnapshotCache(5 * time.Second)
+	payload := map[string]int{"a": 1, "b": 2}
+
+	entry1 := c.Set("k1", payload)
+	entry2 := c.Set("k2", payload)
+	require.Equal(t, entry1.ETag, entry2.ETag, "same payload should produce same ETag")
+}
+
+func TestSnapshotCache_ETagFormat(t *testing.T) {
+	c := newSnapshotCache(5 * time.Second)
+	entry := c.Set("k", "test")
+	// ETag should be quoted hex string: "abcdef..."
+	require.True(t, len(entry.ETag) > 2)
+	require.Equal(t, byte('"'), entry.ETag[0])
+	require.Equal(t, byte('"'), entry.ETag[len(entry.ETag)-1])
+}
+
+func TestBuildETagFromAny_UnmarshalablePayload(t *testing.T) {
+	// channels are not JSON-serializable
+	etag := buildETagFromAny(make(chan int))
+	require.Empty(t, etag)
+}
+
+func TestSnapshotCache_GetOrLoad_MissThenHit(t *testing.T) {
+	c := newSnapshotCache(5 * time.Second)
+	var loads atomic.Int32
+
+	entry, hit, err := c.GetOrLoad("key1", func() (any, error) {
+		loads.Add(1)
+		return map[string]string{"hello": "world"}, nil
+	})
+	require.NoError(t, err)
+	require.False(t, hit)
+	require.NotEmpty(t, entry.ETag)
+	require.Equal(t, int32(1), loads.Load())
+
+	entry2, hit, err := c.GetOrLoad("key1", func() (any, error) {
+		loads.Add(1)
+		return map[string]string{"unexpected": "value"}, nil
+	})
+	require.NoError(t, err)
+	require.True(t, hit)
+	require.Equal(t, entry.ETag, entry2.ETag)
+	require.Equal(t, int32(1), loads.Load())
+}
+
+func TestSnapshotCache_GetOrLoad_ConcurrentSingleflight(t *testing.T) {
+	c := newSnapshotCache(5 * time.Second)
+	var loads atomic.Int32
+	start := make(chan struct{})
+	const callers = 8
+	errCh := make(chan error, callers)
+
+	var wg sync.WaitGroup
+	wg.Add(callers)
+	for range callers {
+		go func() {
+			defer wg.Done()
+			<-start
+			_, _, err := c.GetOrLoad("shared", func() (any, error) {
+				loads.Add(1)
+				time.Sleep(20 * time.Millisecond)
+				return "value", nil
+			})
+			errCh <- err
+		}()
+	}
+	close(start)
+	wg.Wait()
+	close(errCh)
+
+	for err := range errCh {
+		require.NoError(t, err)
+	}
+
+	require.Equal(t, int32(1), loads.Load())
+}
+
+func TestParseBoolQueryWithDefault(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  string
+		def  bool
+		want bool
+	}{
+		{"empty returns default true", "", true, true},
+		{"empty returns default false", "", false, false},
+		{"1", "1", false, true},
+		{"true", "true", false, true},
+		{"TRUE", "TRUE", false, true},
+		{"yes", "yes", false, true},
+		{"on", "on", false, true},
+		{"0", "0", true, false},
+		{"false", "false", true, false},
+		{"FALSE", "FALSE", true, false},
+		{"no", "no", true, false},
+		{"off", "off", true, false},
+		{"whitespace trimmed", "  true  ", false, true},
+		{"unknown returns default true", "maybe", true, true},
+		{"unknown returns default false", "maybe", false, false},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := parseBoolQueryWithDefault(tc.raw, tc.def)
+			require.Equal(t, tc.want, got)
+		})
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/subscription_handler.go

@@ -0,0 +1,322 @@
+package admin
+
+import (
+	"context"
+	"strconv"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// toResponsePagination converts pagination.PaginationResult to response.PaginationResult
+func toResponsePagination(p *pagination.PaginationResult) *response.PaginationResult {
+	if p == nil {
+		return nil
+	}
+	return &response.PaginationResult{
+		Total:    p.Total,
+		Page:     p.Page,
+		PageSize: p.PageSize,
+		Pages:    p.Pages,
+	}
+}
+
+// SubscriptionHandler handles admin subscription management
+type SubscriptionHandler struct {
+	subscriptionService *service.SubscriptionService
+}
+
+// NewSubscriptionHandler creates a new admin subscription handler
+func NewSubscriptionHandler(subscriptionService *service.SubscriptionService) *SubscriptionHandler {
+	return &SubscriptionHandler{
+		subscriptionService: subscriptionService,
+	}
+}
+
+// AssignSubscriptionRequest represents assign subscription request
+type AssignSubscriptionRequest struct {
+	UserID       int64  `json:"user_id" binding:"required"`
+	GroupID      int64  `json:"group_id" binding:"required"`
+	ValidityDays int    `json:"validity_days" binding:"omitempty,max=36500"` // max 100 years
+	Notes        string `json:"notes"`
+}
+
+// BulkAssignSubscriptionRequest represents bulk assign subscription request
+type BulkAssignSubscriptionRequest struct {
+	UserIDs      []int64 `json:"user_ids" binding:"required,min=1"`
+	GroupID      int64   `json:"group_id" binding:"required"`
+	ValidityDays int     `json:"validity_days" binding:"omitempty,max=36500"` // max 100 years
+	Notes        string  `json:"notes"`
+}
+
+// AdjustSubscriptionRequest represents adjust subscription request (extend or shorten)
+type AdjustSubscriptionRequest struct {
+	Days int `json:"days" binding:"required,min=-36500,max=36500"` // negative to shorten, positive to extend
+}
+
+// List handles listing all subscriptions with pagination and filters
+// GET /api/v1/admin/subscriptions
+func (h *SubscriptionHandler) List(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+
+	// Parse optional filters
+	var userID, groupID *int64
+	if userIDStr := c.Query("user_id"); userIDStr != "" {
+		if id, err := strconv.ParseInt(userIDStr, 10, 64); err == nil {
+			userID = &id
+		}
+	}
+	if groupIDStr := c.Query("group_id"); groupIDStr != "" {
+		if id, err := strconv.ParseInt(groupIDStr, 10, 64); err == nil {
+			groupID = &id
+		}
+	}
+	status := c.Query("status")
+
+	// Parse sorting parameters
+	sortBy := c.DefaultQuery("sort_by", "created_at")
+	sortOrder := c.DefaultQuery("sort_order", "desc")
+
+	subscriptions, pagination, err := h.subscriptionService.List(c.Request.Context(), page, pageSize, userID, groupID, status, sortBy, sortOrder)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.AdminUserSubscription, 0, len(subscriptions))
+	for i := range subscriptions {
+		out = append(out, *dto.UserSubscriptionFromServiceAdmin(&subscriptions[i]))
+	}
+	response.PaginatedWithResult(c, out, toResponsePagination(pagination))
+}
+
+// GetByID handles getting a subscription by ID
+// GET /api/v1/admin/subscriptions/:id
+func (h *SubscriptionHandler) GetByID(c *gin.Context) {
+	subscriptionID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid subscription ID")
+		return
+	}
+
+	subscription, err := h.subscriptionService.GetByID(c.Request.Context(), subscriptionID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserSubscriptionFromServiceAdmin(subscription))
+}
+
+// GetProgress handles getting subscription usage progress
+// GET /api/v1/admin/subscriptions/:id/progress
+func (h *SubscriptionHandler) GetProgress(c *gin.Context) {
+	subscriptionID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid subscription ID")
+		return
+	}
+
+	progress, err := h.subscriptionService.GetSubscriptionProgress(c.Request.Context(), subscriptionID)
+	if err != nil {
+		response.NotFound(c, "Subscription not found")
+		return
+	}
+
+	response.Success(c, progress)
+}
+
+// Assign handles assigning a subscription to a user
+// POST /api/v1/admin/subscriptions/assign
+func (h *SubscriptionHandler) Assign(c *gin.Context) {
+	var req AssignSubscriptionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Get admin user ID from context
+	adminID := getAdminIDFromContext(c)
+
+	subscription, err := h.subscriptionService.AssignSubscription(c.Request.Context(), &service.AssignSubscriptionInput{
+		UserID:       req.UserID,
+		GroupID:      req.GroupID,
+		ValidityDays: req.ValidityDays,
+		AssignedBy:   adminID,
+		Notes:        req.Notes,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserSubscriptionFromServiceAdmin(subscription))
+}
+
+// BulkAssign handles bulk assigning subscriptions to multiple users
+// POST /api/v1/admin/subscriptions/bulk-assign
+func (h *SubscriptionHandler) BulkAssign(c *gin.Context) {
+	var req BulkAssignSubscriptionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Get admin user ID from context
+	adminID := getAdminIDFromContext(c)
+
+	result, err := h.subscriptionService.BulkAssignSubscription(c.Request.Context(), &service.BulkAssignSubscriptionInput{
+		UserIDs:      req.UserIDs,
+		GroupID:      req.GroupID,
+		ValidityDays: req.ValidityDays,
+		AssignedBy:   adminID,
+		Notes:        req.Notes,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.BulkAssignResultFromService(result))
+}
+
+// Extend handles adjusting a subscription (extend or shorten)
+// POST /api/v1/admin/subscriptions/:id/extend
+func (h *SubscriptionHandler) Extend(c *gin.Context) {
+	subscriptionID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid subscription ID")
+		return
+	}
+
+	var req AdjustSubscriptionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	idempotencyPayload := struct {
+		SubscriptionID int64                     `json:"subscription_id"`
+		Body           AdjustSubscriptionRequest `json:"body"`
+	}{
+		SubscriptionID: subscriptionID,
+		Body:           req,
+	}
+	executeAdminIdempotentJSON(c, "admin.subscriptions.extend", idempotencyPayload, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		subscription, execErr := h.subscriptionService.ExtendSubscription(ctx, subscriptionID, req.Days)
+		if execErr != nil {
+			return nil, execErr
+		}
+		return dto.UserSubscriptionFromServiceAdmin(subscription), nil
+	})
+}
+
+// ResetSubscriptionQuotaRequest represents the reset quota request
+type ResetSubscriptionQuotaRequest struct {
+	Daily   bool `json:"daily"`
+	Weekly  bool `json:"weekly"`
+	Monthly bool `json:"monthly"`
+}
+
+// ResetQuota resets daily, weekly, and/or monthly usage for a subscription.
+// POST /api/v1/admin/subscriptions/:id/reset-quota
+func (h *SubscriptionHandler) ResetQuota(c *gin.Context) {
+	subscriptionID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid subscription ID")
+		return
+	}
+	var req ResetSubscriptionQuotaRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	if !req.Daily && !req.Weekly && !req.Monthly {
+		response.BadRequest(c, "At least one of 'daily', 'weekly', or 'monthly' must be true")
+		return
+	}
+	sub, err := h.subscriptionService.AdminResetQuota(c.Request.Context(), subscriptionID, req.Daily, req.Weekly, req.Monthly)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, dto.UserSubscriptionFromServiceAdmin(sub))
+}
+
+// Revoke handles revoking a subscription
+// DELETE /api/v1/admin/subscriptions/:id
+func (h *SubscriptionHandler) Revoke(c *gin.Context) {
+	subscriptionID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid subscription ID")
+		return
+	}
+
+	err = h.subscriptionService.RevokeSubscription(c.Request.Context(), subscriptionID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Subscription revoked successfully"})
+}
+
+// ListByGroup handles listing subscriptions for a specific group
+// GET /api/v1/admin/groups/:id/subscriptions
+func (h *SubscriptionHandler) ListByGroup(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid group ID")
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+
+	subscriptions, pagination, err := h.subscriptionService.ListGroupSubscriptions(c.Request.Context(), groupID, page, pageSize)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.AdminUserSubscription, 0, len(subscriptions))
+	for i := range subscriptions {
+		out = append(out, *dto.UserSubscriptionFromServiceAdmin(&subscriptions[i]))
+	}
+	response.PaginatedWithResult(c, out, toResponsePagination(pagination))
+}
+
+// ListByUser handles listing subscriptions for a specific user
+// GET /api/v1/admin/users/:id/subscriptions
+func (h *SubscriptionHandler) ListByUser(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	subscriptions, err := h.subscriptionService.ListUserSubscriptions(c.Request.Context(), userID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.AdminUserSubscription, 0, len(subscriptions))
+	for i := range subscriptions {
+		out = append(out, *dto.UserSubscriptionFromServiceAdmin(&subscriptions[i]))
+	}
+	response.Success(c, out)
+}
+
+// Helper function to get admin ID from context
+func getAdminIDFromContext(c *gin.Context) int64 {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		return 0
+	}
+	return subject.UserID
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/system_handler.go

@@ -0,0 +1,177 @@
+package admin
+
+import (
+	"context"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/sysutil"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// SystemHandler handles system-related operations
+type SystemHandler struct {
+	updateSvc *service.UpdateService
+	lockSvc   *service.SystemOperationLockService
+}
+
+// NewSystemHandler creates a new SystemHandler
+func NewSystemHandler(updateSvc *service.UpdateService, lockSvc *service.SystemOperationLockService) *SystemHandler {
+	return &SystemHandler{
+		updateSvc: updateSvc,
+		lockSvc:   lockSvc,
+	}
+}
+
+// GetVersion returns the current version
+// GET /api/v1/admin/system/version
+func (h *SystemHandler) GetVersion(c *gin.Context) {
+	info, _ := h.updateSvc.CheckUpdate(c.Request.Context(), false)
+	response.Success(c, gin.H{
+		"version": info.CurrentVersion,
+	})
+}
+
+// CheckUpdates checks for available updates
+// GET /api/v1/admin/system/check-updates
+func (h *SystemHandler) CheckUpdates(c *gin.Context) {
+	force := c.Query("force") == "true"
+	info, err := h.updateSvc.CheckUpdate(c.Request.Context(), force)
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, err.Error())
+		return
+	}
+	response.Success(c, info)
+}
+
+// PerformUpdate downloads and applies the update
+// POST /api/v1/admin/system/update
+func (h *SystemHandler) PerformUpdate(c *gin.Context) {
+	operationID := buildSystemOperationID(c, "update")
+	payload := gin.H{"operation_id": operationID}
+	executeAdminIdempotentJSON(c, "admin.system.update", payload, service.DefaultSystemOperationIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		lock, release, err := h.acquireSystemLock(ctx, operationID)
+		if err != nil {
+			return nil, err
+		}
+		var releaseReason string
+		succeeded := false
+		defer func() {
+			release(releaseReason, succeeded)
+		}()
+
+		if err := h.updateSvc.PerformUpdate(ctx); err != nil {
+			releaseReason = "SYSTEM_UPDATE_FAILED"
+			return nil, err
+		}
+		succeeded = true
+
+		return gin.H{
+			"message":      "Update completed. Please restart the service.",
+			"need_restart": true,
+			"operation_id": lock.OperationID(),
+		}, nil
+	})
+}
+
+// Rollback restores the previous version
+// POST /api/v1/admin/system/rollback
+func (h *SystemHandler) Rollback(c *gin.Context) {
+	operationID := buildSystemOperationID(c, "rollback")
+	payload := gin.H{"operation_id": operationID}
+	executeAdminIdempotentJSON(c, "admin.system.rollback", payload, service.DefaultSystemOperationIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		lock, release, err := h.acquireSystemLock(ctx, operationID)
+		if err != nil {
+			return nil, err
+		}
+		var releaseReason string
+		succeeded := false
+		defer func() {
+			release(releaseReason, succeeded)
+		}()
+
+		if err := h.updateSvc.Rollback(); err != nil {
+			releaseReason = "SYSTEM_ROLLBACK_FAILED"
+			return nil, err
+		}
+		succeeded = true
+
+		return gin.H{
+			"message":      "Rollback completed. Please restart the service.",
+			"need_restart": true,
+			"operation_id": lock.OperationID(),
+		}, nil
+	})
+}
+
+// RestartService restarts the systemd service
+// POST /api/v1/admin/system/restart
+func (h *SystemHandler) RestartService(c *gin.Context) {
+	operationID := buildSystemOperationID(c, "restart")
+	payload := gin.H{"operation_id": operationID}
+	executeAdminIdempotentJSON(c, "admin.system.restart", payload, service.DefaultSystemOperationIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		lock, release, err := h.acquireSystemLock(ctx, operationID)
+		if err != nil {
+			return nil, err
+		}
+		succeeded := false
+		defer func() {
+			release("", succeeded)
+		}()
+
+		// Schedule service restart in background after sending response
+		// This ensures the client receives the success response before the service restarts
+		go func() {
+			// Wait a moment to ensure the response is sent
+			time.Sleep(500 * time.Millisecond)
+			sysutil.RestartServiceAsync()
+		}()
+		succeeded = true
+		return gin.H{
+			"message":      "Service restart initiated",
+			"operation_id": lock.OperationID(),
+		}, nil
+	})
+}
+
+func (h *SystemHandler) acquireSystemLock(
+	ctx context.Context,
+	operationID string,
+) (*service.SystemOperationLock, func(string, bool), error) {
+	if h.lockSvc == nil {
+		return nil, nil, service.ErrIdempotencyStoreUnavail
+	}
+	lock, err := h.lockSvc.Acquire(ctx, operationID)
+	if err != nil {
+		return nil, nil, err
+	}
+	release := func(reason string, succeeded bool) {
+		releaseCtx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+		defer cancel()
+		_ = h.lockSvc.Release(releaseCtx, lock, succeeded, reason)
+	}
+	return lock, release, nil
+}
+
+func buildSystemOperationID(c *gin.Context, operation string) string {
+	key := strings.TrimSpace(c.GetHeader("Idempotency-Key"))
+	if key == "" {
+		return "sysop-" + operation + "-" + strconv.FormatInt(time.Now().UnixNano(), 36)
+	}
+	actorScope := "admin:0"
+	if subject, ok := middleware2.GetAuthSubjectFromContext(c); ok {
+		actorScope = "admin:" + strconv.FormatInt(subject.UserID, 10)
+	}
+	seed := operation + "|" + actorScope + "|" + c.FullPath() + "|" + key
+	hash := service.HashIdempotencyKey(seed)
+	if len(hash) > 24 {
+		hash = hash[:24]
+	}
+	return "sysop-" + hash
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/usage_cleanup_handler_test.go

@@ -0,0 +1,463 @@
+package admin
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type cleanupRepoStub struct {
+	mu         sync.Mutex
+	created    []*service.UsageCleanupTask
+	listTasks  []service.UsageCleanupTask
+	listResult *pagination.PaginationResult
+	listErr    error
+	statusByID map[int64]string
+}
+
+func (s *cleanupRepoStub) CreateTask(ctx context.Context, task *service.UsageCleanupTask) error {
+	if task == nil {
+		return nil
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if task.ID == 0 {
+		task.ID = int64(len(s.created) + 1)
+	}
+	if task.CreatedAt.IsZero() {
+		task.CreatedAt = time.Now().UTC()
+	}
+	task.UpdatedAt = task.CreatedAt
+	clone := *task
+	s.created = append(s.created, &clone)
+	return nil
+}
+
+func (s *cleanupRepoStub) ListTasks(ctx context.Context, params pagination.PaginationParams) ([]service.UsageCleanupTask, *pagination.PaginationResult, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.listTasks, s.listResult, s.listErr
+}
+
+func (s *cleanupRepoStub) ClaimNextPendingTask(ctx context.Context, staleRunningAfterSeconds int64) (*service.UsageCleanupTask, error) {
+	return nil, nil
+}
+
+func (s *cleanupRepoStub) GetTaskStatus(ctx context.Context, taskID int64) (string, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.statusByID == nil {
+		return "", sql.ErrNoRows
+	}
+	status, ok := s.statusByID[taskID]
+	if !ok {
+		return "", sql.ErrNoRows
+	}
+	return status, nil
+}
+
+func (s *cleanupRepoStub) UpdateTaskProgress(ctx context.Context, taskID int64, deletedRows int64) error {
+	return nil
+}
+
+func (s *cleanupRepoStub) CancelTask(ctx context.Context, taskID int64, canceledBy int64) (bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.statusByID == nil {
+		s.statusByID = map[int64]string{}
+	}
+	status := s.statusByID[taskID]
+	if status != service.UsageCleanupStatusPending && status != service.UsageCleanupStatusRunning {
+		return false, nil
+	}
+	s.statusByID[taskID] = service.UsageCleanupStatusCanceled
+	return true, nil
+}
+
+func (s *cleanupRepoStub) MarkTaskSucceeded(ctx context.Context, taskID int64, deletedRows int64) error {
+	return nil
+}
+
+func (s *cleanupRepoStub) MarkTaskFailed(ctx context.Context, taskID int64, deletedRows int64, errorMsg string) error {
+	return nil
+}
+
+func (s *cleanupRepoStub) DeleteUsageLogsBatch(ctx context.Context, filters service.UsageCleanupFilters, limit int) (int64, error) {
+	return 0, nil
+}
+
+var _ service.UsageCleanupRepository = (*cleanupRepoStub)(nil)
+
+func setupCleanupRouter(cleanupService *service.UsageCleanupService, userID int64) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	if userID > 0 {
+		router.Use(func(c *gin.Context) {
+			c.Set(string(middleware.ContextKeyUser), middleware.AuthSubject{UserID: userID})
+			c.Next()
+		})
+	}
+
+	handler := NewUsageHandler(nil, nil, nil, cleanupService)
+	router.POST("/api/v1/admin/usage/cleanup-tasks", handler.CreateCleanupTask)
+	router.GET("/api/v1/admin/usage/cleanup-tasks", handler.ListCleanupTasks)
+	router.POST("/api/v1/admin/usage/cleanup-tasks/:id/cancel", handler.CancelCleanupTask)
+	return router
+}
+
+func TestUsageHandlerCreateCleanupTaskUnauthorized(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 0)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewBufferString(`{}`))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusUnauthorized, recorder.Code)
+}
+
+func TestUsageHandlerCreateCleanupTaskUnavailable(t *testing.T) {
+	router := setupCleanupRouter(nil, 1)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewBufferString(`{}`))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusServiceUnavailable, recorder.Code)
+}
+
+func TestUsageHandlerCreateCleanupTaskBindError(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 88)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewBufferString("{bad-json"))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusBadRequest, recorder.Code)
+}
+
+func TestUsageHandlerCreateCleanupTaskMissingRange(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 88)
+
+	payload := map[string]any{
+		"start_date": "2024-01-01",
+		"timezone":   "UTC",
+	}
+	body, err := json.Marshal(payload)
+	require.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusBadRequest, recorder.Code)
+}
+
+func TestUsageHandlerCreateCleanupTaskInvalidDate(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 88)
+
+	payload := map[string]any{
+		"start_date": "2024-13-01",
+		"end_date":   "2024-01-02",
+		"timezone":   "UTC",
+	}
+	body, err := json.Marshal(payload)
+	require.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusBadRequest, recorder.Code)
+}
+
+func TestUsageHandlerCreateCleanupTaskInvalidEndDate(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 88)
+
+	payload := map[string]any{
+		"start_date": "2024-01-01",
+		"end_date":   "2024-02-40",
+		"timezone":   "UTC",
+	}
+	body, err := json.Marshal(payload)
+	require.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusBadRequest, recorder.Code)
+}
+
+func TestUsageHandlerCreateCleanupTaskInvalidRequestType(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 88)
+
+	payload := map[string]any{
+		"start_date":   "2024-01-01",
+		"end_date":     "2024-01-02",
+		"timezone":     "UTC",
+		"request_type": "invalid",
+	}
+	body, err := json.Marshal(payload)
+	require.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusBadRequest, recorder.Code)
+}
+
+func TestUsageHandlerCreateCleanupTaskRequestTypePriority(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 99)
+
+	payload := map[string]any{
+		"start_date":   "2024-01-01",
+		"end_date":     "2024-01-02",
+		"timezone":     "UTC",
+		"request_type": "ws_v2",
+		"stream":       false,
+	}
+	body, err := json.Marshal(payload)
+	require.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusOK, recorder.Code)
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	require.Len(t, repo.created, 1)
+	created := repo.created[0]
+	require.NotNil(t, created.Filters.RequestType)
+	require.Equal(t, int16(service.RequestTypeWSV2), *created.Filters.RequestType)
+	require.Nil(t, created.Filters.Stream)
+}
+
+func TestUsageHandlerCreateCleanupTaskWithLegacyStream(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 99)
+
+	payload := map[string]any{
+		"start_date": "2024-01-01",
+		"end_date":   "2024-01-02",
+		"timezone":   "UTC",
+		"stream":     true,
+	}
+	body, err := json.Marshal(payload)
+	require.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusOK, recorder.Code)
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	require.Len(t, repo.created, 1)
+	created := repo.created[0]
+	require.Nil(t, created.Filters.RequestType)
+	require.NotNil(t, created.Filters.Stream)
+	require.True(t, *created.Filters.Stream)
+}
+
+func TestUsageHandlerCreateCleanupTaskSuccess(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 99)
+
+	payload := map[string]any{
+		"start_date": " 2024-01-01 ",
+		"end_date":   "2024-01-02",
+		"timezone":   "UTC",
+		"model":      "gpt-4",
+	}
+	body, err := json.Marshal(payload)
+	require.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusOK, recorder.Code)
+
+	var resp response.Response
+	require.NoError(t, json.Unmarshal(recorder.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	require.Len(t, repo.created, 1)
+	created := repo.created[0]
+	require.Equal(t, int64(99), created.CreatedBy)
+	require.NotNil(t, created.Filters.Model)
+	require.Equal(t, "gpt-4", *created.Filters.Model)
+
+	start := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
+	end := time.Date(2024, 1, 2, 0, 0, 0, 0, time.UTC).Add(24*time.Hour - time.Nanosecond)
+	require.True(t, created.Filters.StartTime.Equal(start))
+	require.True(t, created.Filters.EndTime.Equal(end))
+}
+
+func TestUsageHandlerListCleanupTasksUnavailable(t *testing.T) {
+	router := setupCleanupRouter(nil, 0)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/usage/cleanup-tasks", nil)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusServiceUnavailable, recorder.Code)
+}
+
+func TestUsageHandlerListCleanupTasksSuccess(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	repo.listTasks = []service.UsageCleanupTask{
+		{
+			ID:        7,
+			Status:    service.UsageCleanupStatusSucceeded,
+			CreatedBy: 4,
+		},
+	}
+	repo.listResult = &pagination.PaginationResult{Total: 1, Page: 1, PageSize: 20, Pages: 1}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 1)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/usage/cleanup-tasks", nil)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusOK, recorder.Code)
+
+	var resp struct {
+		Code int `json:"code"`
+		Data struct {
+			Items []dto.UsageCleanupTask `json:"items"`
+			Total int64                  `json:"total"`
+			Page  int                    `json:"page"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(recorder.Body.Bytes(), &resp))
+	require.Equal(t, 0, resp.Code)
+	require.Len(t, resp.Data.Items, 1)
+	require.Equal(t, int64(7), resp.Data.Items[0].ID)
+	require.Equal(t, int64(1), resp.Data.Total)
+	require.Equal(t, 1, resp.Data.Page)
+}
+
+func TestUsageHandlerListCleanupTasksError(t *testing.T) {
+	repo := &cleanupRepoStub{listErr: errors.New("boom")}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true, MaxRangeDays: 31}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 1)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/usage/cleanup-tasks", nil)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusInternalServerError, recorder.Code)
+}
+
+func TestUsageHandlerCancelCleanupTaskUnauthorized(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 0)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks/1/cancel", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+}
+
+func TestUsageHandlerCancelCleanupTaskNotFound(t *testing.T) {
+	repo := &cleanupRepoStub{}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 1)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks/999/cancel", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusNotFound, rec.Code)
+}
+
+func TestUsageHandlerCancelCleanupTaskConflict(t *testing.T) {
+	repo := &cleanupRepoStub{statusByID: map[int64]string{2: service.UsageCleanupStatusSucceeded}}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 1)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks/2/cancel", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusConflict, rec.Code)
+}
+
+func TestUsageHandlerCancelCleanupTaskSuccess(t *testing.T) {
+	repo := &cleanupRepoStub{statusByID: map[int64]string{3: service.UsageCleanupStatusPending}}
+	cfg := &config.Config{UsageCleanup: config.UsageCleanupConfig{Enabled: true}}
+	cleanupService := service.NewUsageCleanupService(repo, nil, nil, cfg)
+	router := setupCleanupRouter(cleanupService, 1)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/usage/cleanup-tasks/3/cancel", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/usage_handler.go

@@ -0,0 +1,585 @@
+package admin
+
+import (
+	"context"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// UsageHandler handles admin usage-related requests
+type UsageHandler struct {
+	usageService   *service.UsageService
+	apiKeyService  *service.APIKeyService
+	adminService   service.AdminService
+	cleanupService *service.UsageCleanupService
+}
+
+// NewUsageHandler creates a new admin usage handler
+func NewUsageHandler(
+	usageService *service.UsageService,
+	apiKeyService *service.APIKeyService,
+	adminService service.AdminService,
+	cleanupService *service.UsageCleanupService,
+) *UsageHandler {
+	return &UsageHandler{
+		usageService:   usageService,
+		apiKeyService:  apiKeyService,
+		adminService:   adminService,
+		cleanupService: cleanupService,
+	}
+}
+
+// CreateUsageCleanupTaskRequest represents cleanup task creation request
+type CreateUsageCleanupTaskRequest struct {
+	StartDate   string  `json:"start_date"`
+	EndDate     string  `json:"end_date"`
+	UserID      *int64  `json:"user_id"`
+	APIKeyID    *int64  `json:"api_key_id"`
+	AccountID   *int64  `json:"account_id"`
+	GroupID     *int64  `json:"group_id"`
+	Model       *string `json:"model"`
+	RequestType *string `json:"request_type"`
+	Stream      *bool   `json:"stream"`
+	BillingType *int8   `json:"billing_type"`
+	Timezone    string  `json:"timezone"`
+}
+
+// List handles listing all usage records with filters
+// GET /api/v1/admin/usage
+func (h *UsageHandler) List(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+	exactTotal := false
+	if exactTotalRaw := strings.TrimSpace(c.Query("exact_total")); exactTotalRaw != "" {
+		parsed, err := strconv.ParseBool(exactTotalRaw)
+		if err != nil {
+			response.BadRequest(c, "Invalid exact_total value, use true or false")
+			return
+		}
+		exactTotal = parsed
+	}
+
+	// Parse filters
+	var userID, apiKeyID, accountID, groupID int64
+	if userIDStr := c.Query("user_id"); userIDStr != "" {
+		id, err := strconv.ParseInt(userIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid user_id")
+			return
+		}
+		userID = id
+	}
+
+	if apiKeyIDStr := c.Query("api_key_id"); apiKeyIDStr != "" {
+		id, err := strconv.ParseInt(apiKeyIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid api_key_id")
+			return
+		}
+		apiKeyID = id
+	}
+
+	if accountIDStr := c.Query("account_id"); accountIDStr != "" {
+		id, err := strconv.ParseInt(accountIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		accountID = id
+	}
+
+	if groupIDStr := c.Query("group_id"); groupIDStr != "" {
+		id, err := strconv.ParseInt(groupIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		groupID = id
+	}
+
+	model := c.Query("model")
+
+	var requestType *int16
+	var stream *bool
+	if requestTypeStr := strings.TrimSpace(c.Query("request_type")); requestTypeStr != "" {
+		parsed, err := service.ParseUsageRequestType(requestTypeStr)
+		if err != nil {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		value := int16(parsed)
+		requestType = &value
+	} else if streamStr := c.Query("stream"); streamStr != "" {
+		val, err := strconv.ParseBool(streamStr)
+		if err != nil {
+			response.BadRequest(c, "Invalid stream value, use true or false")
+			return
+		}
+		stream = &val
+	}
+
+	var billingType *int8
+	if billingTypeStr := c.Query("billing_type"); billingTypeStr != "" {
+		val, err := strconv.ParseInt(billingTypeStr, 10, 8)
+		if err != nil {
+			response.BadRequest(c, "Invalid billing_type")
+			return
+		}
+		bt := int8(val)
+		billingType = &bt
+	}
+
+	// Parse date range
+	var startTime, endTime *time.Time
+	userTZ := c.Query("timezone") // Get user's timezone from request
+	if startDateStr := c.Query("start_date"); startDateStr != "" {
+		t, err := timezone.ParseInUserLocation("2006-01-02", startDateStr, userTZ)
+		if err != nil {
+			response.BadRequest(c, "Invalid start_date format, use YYYY-MM-DD")
+			return
+		}
+		startTime = &t
+	}
+
+	if endDateStr := c.Query("end_date"); endDateStr != "" {
+		t, err := timezone.ParseInUserLocation("2006-01-02", endDateStr, userTZ)
+		if err != nil {
+			response.BadRequest(c, "Invalid end_date format, use YYYY-MM-DD")
+			return
+		}
+		// Use half-open range [start, end), move to next calendar day start (DST-safe).
+		t = t.AddDate(0, 0, 1)
+		endTime = &t
+	}
+
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
+	filters := usagestats.UsageLogFilters{
+		UserID:      userID,
+		APIKeyID:    apiKeyID,
+		AccountID:   accountID,
+		GroupID:     groupID,
+		Model:       model,
+		RequestType: requestType,
+		Stream:      stream,
+		BillingType: billingType,
+		StartTime:   startTime,
+		EndTime:     endTime,
+		ExactTotal:  exactTotal,
+	}
+
+	records, result, err := h.usageService.ListWithFilters(c.Request.Context(), params, filters)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.AdminUsageLog, 0, len(records))
+	for i := range records {
+		out = append(out, *dto.UsageLogFromServiceAdmin(&records[i]))
+	}
+	response.Paginated(c, out, result.Total, page, pageSize)
+}
+
+// Stats handles getting usage statistics with filters
+// GET /api/v1/admin/usage/stats
+func (h *UsageHandler) Stats(c *gin.Context) {
+	// Parse filters - same as List endpoint
+	var userID, apiKeyID, accountID, groupID int64
+	if userIDStr := c.Query("user_id"); userIDStr != "" {
+		id, err := strconv.ParseInt(userIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid user_id")
+			return
+		}
+		userID = id
+	}
+
+	if apiKeyIDStr := c.Query("api_key_id"); apiKeyIDStr != "" {
+		id, err := strconv.ParseInt(apiKeyIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid api_key_id")
+			return
+		}
+		apiKeyID = id
+	}
+
+	if accountIDStr := c.Query("account_id"); accountIDStr != "" {
+		id, err := strconv.ParseInt(accountIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		accountID = id
+	}
+
+	if groupIDStr := c.Query("group_id"); groupIDStr != "" {
+		id, err := strconv.ParseInt(groupIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid group_id")
+			return
+		}
+		groupID = id
+	}
+
+	model := c.Query("model")
+
+	var requestType *int16
+	var stream *bool
+	if requestTypeStr := strings.TrimSpace(c.Query("request_type")); requestTypeStr != "" {
+		parsed, err := service.ParseUsageRequestType(requestTypeStr)
+		if err != nil {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		value := int16(parsed)
+		requestType = &value
+	} else if streamStr := c.Query("stream"); streamStr != "" {
+		val, err := strconv.ParseBool(streamStr)
+		if err != nil {
+			response.BadRequest(c, "Invalid stream value, use true or false")
+			return
+		}
+		stream = &val
+	}
+
+	var billingType *int8
+	if billingTypeStr := c.Query("billing_type"); billingTypeStr != "" {
+		val, err := strconv.ParseInt(billingTypeStr, 10, 8)
+		if err != nil {
+			response.BadRequest(c, "Invalid billing_type")
+			return
+		}
+		bt := int8(val)
+		billingType = &bt
+	}
+
+	// Parse date range
+	userTZ := c.Query("timezone")
+	now := timezone.NowInUserLocation(userTZ)
+	var startTime, endTime time.Time
+
+	startDateStr := c.Query("start_date")
+	endDateStr := c.Query("end_date")
+
+	if startDateStr != "" && endDateStr != "" {
+		var err error
+		startTime, err = timezone.ParseInUserLocation("2006-01-02", startDateStr, userTZ)
+		if err != nil {
+			response.BadRequest(c, "Invalid start_date format, use YYYY-MM-DD")
+			return
+		}
+		endTime, err = timezone.ParseInUserLocation("2006-01-02", endDateStr, userTZ)
+		if err != nil {
+			response.BadRequest(c, "Invalid end_date format, use YYYY-MM-DD")
+			return
+		}
+		// 与 SQL 条件 created_at < end 对齐，使用次日 00:00 作为上边界（DST-safe）。
+		endTime = endTime.AddDate(0, 0, 1)
+	} else {
+		period := c.DefaultQuery("period", "today")
+		switch period {
+		case "today":
+			startTime = timezone.StartOfDayInUserLocation(now, userTZ)
+		case "week":
+			startTime = now.AddDate(0, 0, -7)
+		case "month":
+			startTime = now.AddDate(0, -1, 0)
+		default:
+			startTime = timezone.StartOfDayInUserLocation(now, userTZ)
+		}
+		endTime = now
+	}
+
+	// Build filters and call GetStatsWithFilters
+	filters := usagestats.UsageLogFilters{
+		UserID:      userID,
+		APIKeyID:    apiKeyID,
+		AccountID:   accountID,
+		GroupID:     groupID,
+		Model:       model,
+		RequestType: requestType,
+		Stream:      stream,
+		BillingType: billingType,
+		StartTime:   &startTime,
+		EndTime:     &endTime,
+	}
+
+	stats, err := h.usageService.GetStatsWithFilters(c.Request.Context(), filters)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, stats)
+}
+
+// SearchUsers handles searching users by email keyword
+// GET /api/v1/admin/usage/search-users
+func (h *UsageHandler) SearchUsers(c *gin.Context) {
+	keyword := c.Query("q")
+	if keyword == "" {
+		response.Success(c, []any{})
+		return
+	}
+
+	// Limit to 30 results
+	users, _, err := h.adminService.ListUsers(c.Request.Context(), 1, 30, service.UserListFilters{Search: keyword})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Return simplified user list (only id and email)
+	type SimpleUser struct {
+		ID    int64  `json:"id"`
+		Email string `json:"email"`
+	}
+
+	result := make([]SimpleUser, len(users))
+	for i, u := range users {
+		result[i] = SimpleUser{
+			ID:    u.ID,
+			Email: u.Email,
+		}
+	}
+
+	response.Success(c, result)
+}
+
+// SearchAPIKeys handles searching API keys by user
+// GET /api/v1/admin/usage/search-api-keys
+func (h *UsageHandler) SearchAPIKeys(c *gin.Context) {
+	userIDStr := c.Query("user_id")
+	keyword := c.Query("q")
+
+	var userID int64
+	if userIDStr != "" {
+		id, err := strconv.ParseInt(userIDStr, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "Invalid user_id")
+			return
+		}
+		userID = id
+	}
+
+	keys, err := h.apiKeyService.SearchAPIKeys(c.Request.Context(), userID, keyword, 30)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Return simplified API key list (only id and name)
+	type SimpleAPIKey struct {
+		ID     int64  `json:"id"`
+		Name   string `json:"name"`
+		UserID int64  `json:"user_id"`
+	}
+
+	result := make([]SimpleAPIKey, len(keys))
+	for i, k := range keys {
+		result[i] = SimpleAPIKey{
+			ID:     k.ID,
+			Name:   k.Name,
+			UserID: k.UserID,
+		}
+	}
+
+	response.Success(c, result)
+}
+
+// ListCleanupTasks handles listing usage cleanup tasks
+// GET /api/v1/admin/usage/cleanup-tasks
+func (h *UsageHandler) ListCleanupTasks(c *gin.Context) {
+	if h.cleanupService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Usage cleanup service unavailable")
+		return
+	}
+	operator := int64(0)
+	if subject, ok := middleware.GetAuthSubjectFromContext(c); ok {
+		operator = subject.UserID
+	}
+	page, pageSize := response.ParsePagination(c)
+	logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 请求清理任务列表: operator=%d page=%d page_size=%d", operator, page, pageSize)
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
+	tasks, result, err := h.cleanupService.ListTasks(c.Request.Context(), params)
+	if err != nil {
+		logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 查询清理任务列表失败: operator=%d page=%d page_size=%d err=%v", operator, page, pageSize, err)
+		response.ErrorFrom(c, err)
+		return
+	}
+	out := make([]dto.UsageCleanupTask, 0, len(tasks))
+	for i := range tasks {
+		out = append(out, *dto.UsageCleanupTaskFromService(&tasks[i]))
+	}
+	logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 返回清理任务列表: operator=%d total=%d items=%d page=%d page_size=%d", operator, result.Total, len(out), page, pageSize)
+	response.Paginated(c, out, result.Total, page, pageSize)
+}
+
+// CreateCleanupTask handles creating a usage cleanup task
+// POST /api/v1/admin/usage/cleanup-tasks
+func (h *UsageHandler) CreateCleanupTask(c *gin.Context) {
+	if h.cleanupService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Usage cleanup service unavailable")
+		return
+	}
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Unauthorized(c, "Unauthorized")
+		return
+	}
+
+	var req CreateUsageCleanupTaskRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+	req.StartDate = strings.TrimSpace(req.StartDate)
+	req.EndDate = strings.TrimSpace(req.EndDate)
+	if req.StartDate == "" || req.EndDate == "" {
+		response.BadRequest(c, "start_date and end_date are required")
+		return
+	}
+
+	startTime, err := timezone.ParseInUserLocation("2006-01-02", req.StartDate, req.Timezone)
+	if err != nil {
+		response.BadRequest(c, "Invalid start_date format, use YYYY-MM-DD")
+		return
+	}
+	endTime, err := timezone.ParseInUserLocation("2006-01-02", req.EndDate, req.Timezone)
+	if err != nil {
+		response.BadRequest(c, "Invalid end_date format, use YYYY-MM-DD")
+		return
+	}
+	endTime = endTime.Add(24*time.Hour - time.Nanosecond)
+
+	var requestType *int16
+	stream := req.Stream
+	if req.RequestType != nil {
+		parsed, err := service.ParseUsageRequestType(*req.RequestType)
+		if err != nil {
+			response.BadRequest(c, err.Error())
+			return
+		}
+		value := int16(parsed)
+		requestType = &value
+		stream = nil
+	}
+
+	filters := service.UsageCleanupFilters{
+		StartTime:   startTime,
+		EndTime:     endTime,
+		UserID:      req.UserID,
+		APIKeyID:    req.APIKeyID,
+		AccountID:   req.AccountID,
+		GroupID:     req.GroupID,
+		Model:       req.Model,
+		RequestType: requestType,
+		Stream:      stream,
+		BillingType: req.BillingType,
+	}
+
+	var userID any
+	if filters.UserID != nil {
+		userID = *filters.UserID
+	}
+	var apiKeyID any
+	if filters.APIKeyID != nil {
+		apiKeyID = *filters.APIKeyID
+	}
+	var accountID any
+	if filters.AccountID != nil {
+		accountID = *filters.AccountID
+	}
+	var groupID any
+	if filters.GroupID != nil {
+		groupID = *filters.GroupID
+	}
+	var model any
+	if filters.Model != nil {
+		model = *filters.Model
+	}
+	var streamValue any
+	if filters.Stream != nil {
+		streamValue = *filters.Stream
+	}
+	var requestTypeName any
+	if filters.RequestType != nil {
+		requestTypeName = service.RequestTypeFromInt16(*filters.RequestType).String()
+	}
+	var billingType any
+	if filters.BillingType != nil {
+		billingType = *filters.BillingType
+	}
+
+	idempotencyPayload := struct {
+		OperatorID int64                         `json:"operator_id"`
+		Body       CreateUsageCleanupTaskRequest `json:"body"`
+	}{
+		OperatorID: subject.UserID,
+		Body:       req,
+	}
+	executeAdminIdempotentJSON(c, "admin.usage.cleanup_tasks.create", idempotencyPayload, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 请求创建清理任务: operator=%d start=%s end=%s user_id=%v api_key_id=%v account_id=%v group_id=%v model=%v request_type=%v stream=%v billing_type=%v tz=%q",
+			subject.UserID,
+			filters.StartTime.Format(time.RFC3339),
+			filters.EndTime.Format(time.RFC3339),
+			userID,
+			apiKeyID,
+			accountID,
+			groupID,
+			model,
+			requestTypeName,
+			streamValue,
+			billingType,
+			req.Timezone,
+		)
+
+		task, err := h.cleanupService.CreateTask(ctx, filters, subject.UserID)
+		if err != nil {
+			logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 创建清理任务失败: operator=%d err=%v", subject.UserID, err)
+			return nil, err
+		}
+		logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 清理任务已创建: task=%d operator=%d status=%s", task.ID, subject.UserID, task.Status)
+		return dto.UsageCleanupTaskFromService(task), nil
+	})
+}
+
+// CancelCleanupTask handles canceling a usage cleanup task
+// POST /api/v1/admin/usage/cleanup-tasks/:id/cancel
+func (h *UsageHandler) CancelCleanupTask(c *gin.Context) {
+	if h.cleanupService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Usage cleanup service unavailable")
+		return
+	}
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Unauthorized(c, "Unauthorized")
+		return
+	}
+	idStr := strings.TrimSpace(c.Param("id"))
+	taskID, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil || taskID <= 0 {
+		response.BadRequest(c, "Invalid task id")
+		return
+	}
+	logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 请求取消清理任务: task=%d operator=%d", taskID, subject.UserID)
+	if err := h.cleanupService.CancelTask(c.Request.Context(), taskID, subject.UserID); err != nil {
+		logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 取消清理任务失败: task=%d operator=%d err=%v", taskID, subject.UserID, err)
+		response.ErrorFrom(c, err)
+		return
+	}
+	logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 清理任务已取消: task=%d operator=%d", taskID, subject.UserID)
+	response.Success(c, gin.H{"id": taskID, "status": service.UsageCleanupStatusCanceled})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/usage_handler_request_type_test.go

@@ -0,0 +1,140 @@
+package admin
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type adminUsageRepoCapture struct {
+	service.UsageLogRepository
+	listFilters  usagestats.UsageLogFilters
+	statsFilters usagestats.UsageLogFilters
+}
+
+func (s *adminUsageRepoCapture) ListWithFilters(ctx context.Context, params pagination.PaginationParams, filters usagestats.UsageLogFilters) ([]service.UsageLog, *pagination.PaginationResult, error) {
+	s.listFilters = filters
+	return []service.UsageLog{}, &pagination.PaginationResult{
+		Total:    0,
+		Page:     params.Page,
+		PageSize: params.PageSize,
+		Pages:    0,
+	}, nil
+}
+
+func (s *adminUsageRepoCapture) GetStatsWithFilters(ctx context.Context, filters usagestats.UsageLogFilters) (*usagestats.UsageStats, error) {
+	s.statsFilters = filters
+	return &usagestats.UsageStats{}, nil
+}
+
+func newAdminUsageRequestTypeTestRouter(repo *adminUsageRepoCapture) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	usageSvc := service.NewUsageService(repo, nil, nil, nil)
+	handler := NewUsageHandler(usageSvc, nil, nil, nil)
+	router := gin.New()
+	router.GET("/admin/usage", handler.List)
+	router.GET("/admin/usage/stats", handler.Stats)
+	return router
+}
+
+func TestAdminUsageListRequestTypePriority(t *testing.T) {
+	repo := &adminUsageRepoCapture{}
+	router := newAdminUsageRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage?request_type=ws_v2&stream=false", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.NotNil(t, repo.listFilters.RequestType)
+	require.Equal(t, int16(service.RequestTypeWSV2), *repo.listFilters.RequestType)
+	require.Nil(t, repo.listFilters.Stream)
+}
+
+func TestAdminUsageListInvalidRequestType(t *testing.T) {
+	repo := &adminUsageRepoCapture{}
+	router := newAdminUsageRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage?request_type=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestAdminUsageListInvalidStream(t *testing.T) {
+	repo := &adminUsageRepoCapture{}
+	router := newAdminUsageRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage?stream=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestAdminUsageListExactTotalTrue(t *testing.T) {
+	repo := &adminUsageRepoCapture{}
+	router := newAdminUsageRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage?exact_total=true", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.True(t, repo.listFilters.ExactTotal)
+}
+
+func TestAdminUsageListInvalidExactTotal(t *testing.T) {
+	repo := &adminUsageRepoCapture{}
+	router := newAdminUsageRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage?exact_total=oops", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestAdminUsageStatsRequestTypePriority(t *testing.T) {
+	repo := &adminUsageRepoCapture{}
+	router := newAdminUsageRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage/stats?request_type=stream&stream=bad", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.NotNil(t, repo.statsFilters.RequestType)
+	require.Equal(t, int16(service.RequestTypeStream), *repo.statsFilters.RequestType)
+	require.Nil(t, repo.statsFilters.Stream)
+}
+
+func TestAdminUsageStatsInvalidRequestType(t *testing.T) {
+	repo := &adminUsageRepoCapture{}
+	router := newAdminUsageRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage/stats?request_type=oops", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestAdminUsageStatsInvalidStream(t *testing.T) {
+	repo := &adminUsageRepoCapture{}
+	router := newAdminUsageRequestTypeTestRouter(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage/stats?stream=oops", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/user_attribute_handler.go

@@ -0,0 +1,362 @@
+package admin
+
+import (
+	"encoding/json"
+	"strconv"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// UserAttributeHandler handles user attribute management
+type UserAttributeHandler struct {
+	attrService *service.UserAttributeService
+}
+
+// NewUserAttributeHandler creates a new handler
+func NewUserAttributeHandler(attrService *service.UserAttributeService) *UserAttributeHandler {
+	return &UserAttributeHandler{attrService: attrService}
+}
+
+// --- Request/Response DTOs ---
+
+// CreateAttributeDefinitionRequest represents create attribute definition request
+type CreateAttributeDefinitionRequest struct {
+	Key         string                          `json:"key" binding:"required,min=1,max=100"`
+	Name        string                          `json:"name" binding:"required,min=1,max=255"`
+	Description string                          `json:"description"`
+	Type        string                          `json:"type" binding:"required"`
+	Options     []service.UserAttributeOption   `json:"options"`
+	Required    bool                            `json:"required"`
+	Validation  service.UserAttributeValidation `json:"validation"`
+	Placeholder string                          `json:"placeholder"`
+	Enabled     bool                            `json:"enabled"`
+}
+
+// UpdateAttributeDefinitionRequest represents update attribute definition request
+type UpdateAttributeDefinitionRequest struct {
+	Name        *string                          `json:"name"`
+	Description *string                          `json:"description"`
+	Type        *string                          `json:"type"`
+	Options     *[]service.UserAttributeOption   `json:"options"`
+	Required    *bool                            `json:"required"`
+	Validation  *service.UserAttributeValidation `json:"validation"`
+	Placeholder *string                          `json:"placeholder"`
+	Enabled     *bool                            `json:"enabled"`
+}
+
+// ReorderRequest represents reorder attribute definitions request
+type ReorderRequest struct {
+	IDs []int64 `json:"ids" binding:"required"`
+}
+
+// UpdateUserAttributesRequest represents update user attributes request
+type UpdateUserAttributesRequest struct {
+	Values map[int64]string `json:"values" binding:"required"`
+}
+
+// BatchGetUserAttributesRequest represents batch get user attributes request
+type BatchGetUserAttributesRequest struct {
+	UserIDs []int64 `json:"user_ids" binding:"required"`
+}
+
+// BatchUserAttributesResponse represents batch user attributes response
+type BatchUserAttributesResponse struct {
+	// Map of userID -> map of attributeID -> value
+	Attributes map[int64]map[int64]string `json:"attributes"`
+}
+
+var userAttributesBatchCache = newSnapshotCache(30 * time.Second)
+
+// AttributeDefinitionResponse represents attribute definition response
+type AttributeDefinitionResponse struct {
+	ID           int64                           `json:"id"`
+	Key          string                          `json:"key"`
+	Name         string                          `json:"name"`
+	Description  string                          `json:"description"`
+	Type         string                          `json:"type"`
+	Options      []service.UserAttributeOption   `json:"options"`
+	Required     bool                            `json:"required"`
+	Validation   service.UserAttributeValidation `json:"validation"`
+	Placeholder  string                          `json:"placeholder"`
+	DisplayOrder int                             `json:"display_order"`
+	Enabled      bool                            `json:"enabled"`
+	CreatedAt    string                          `json:"created_at"`
+	UpdatedAt    string                          `json:"updated_at"`
+}
+
+// AttributeValueResponse represents attribute value response
+type AttributeValueResponse struct {
+	ID          int64  `json:"id"`
+	UserID      int64  `json:"user_id"`
+	AttributeID int64  `json:"attribute_id"`
+	Value       string `json:"value"`
+	CreatedAt   string `json:"created_at"`
+	UpdatedAt   string `json:"updated_at"`
+}
+
+// --- Helpers ---
+
+func defToResponse(def *service.UserAttributeDefinition) *AttributeDefinitionResponse {
+	return &AttributeDefinitionResponse{
+		ID:           def.ID,
+		Key:          def.Key,
+		Name:         def.Name,
+		Description:  def.Description,
+		Type:         string(def.Type),
+		Options:      def.Options,
+		Required:     def.Required,
+		Validation:   def.Validation,
+		Placeholder:  def.Placeholder,
+		DisplayOrder: def.DisplayOrder,
+		Enabled:      def.Enabled,
+		CreatedAt:    def.CreatedAt.Format("2006-01-02T15:04:05Z07:00"),
+		UpdatedAt:    def.UpdatedAt.Format("2006-01-02T15:04:05Z07:00"),
+	}
+}
+
+func valueToResponse(val *service.UserAttributeValue) *AttributeValueResponse {
+	return &AttributeValueResponse{
+		ID:          val.ID,
+		UserID:      val.UserID,
+		AttributeID: val.AttributeID,
+		Value:       val.Value,
+		CreatedAt:   val.CreatedAt.Format("2006-01-02T15:04:05Z07:00"),
+		UpdatedAt:   val.UpdatedAt.Format("2006-01-02T15:04:05Z07:00"),
+	}
+}
+
+// --- Handlers ---
+
+// ListDefinitions lists all attribute definitions
+// GET /admin/user-attributes
+func (h *UserAttributeHandler) ListDefinitions(c *gin.Context) {
+	enabledOnly := c.Query("enabled") == "true"
+
+	defs, err := h.attrService.ListDefinitions(c.Request.Context(), enabledOnly)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]*AttributeDefinitionResponse, 0, len(defs))
+	for i := range defs {
+		out = append(out, defToResponse(&defs[i]))
+	}
+
+	response.Success(c, out)
+}
+
+// CreateDefinition creates a new attribute definition
+// POST /admin/user-attributes
+func (h *UserAttributeHandler) CreateDefinition(c *gin.Context) {
+	var req CreateAttributeDefinitionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	def, err := h.attrService.CreateDefinition(c.Request.Context(), service.CreateAttributeDefinitionInput{
+		Key:         req.Key,
+		Name:        req.Name,
+		Description: req.Description,
+		Type:        service.UserAttributeType(req.Type),
+		Options:     req.Options,
+		Required:    req.Required,
+		Validation:  req.Validation,
+		Placeholder: req.Placeholder,
+		Enabled:     req.Enabled,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, defToResponse(def))
+}
+
+// UpdateDefinition updates an attribute definition
+// PUT /admin/user-attributes/:id
+func (h *UserAttributeHandler) UpdateDefinition(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid attribute ID")
+		return
+	}
+
+	var req UpdateAttributeDefinitionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	input := service.UpdateAttributeDefinitionInput{
+		Name:        req.Name,
+		Description: req.Description,
+		Options:     req.Options,
+		Required:    req.Required,
+		Validation:  req.Validation,
+		Placeholder: req.Placeholder,
+		Enabled:     req.Enabled,
+	}
+	if req.Type != nil {
+		t := service.UserAttributeType(*req.Type)
+		input.Type = &t
+	}
+
+	def, err := h.attrService.UpdateDefinition(c.Request.Context(), id, input)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, defToResponse(def))
+}
+
+// DeleteDefinition deletes an attribute definition
+// DELETE /admin/user-attributes/:id
+func (h *UserAttributeHandler) DeleteDefinition(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid attribute ID")
+		return
+	}
+
+	if err := h.attrService.DeleteDefinition(c.Request.Context(), id); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Attribute definition deleted successfully"})
+}
+
+// ReorderDefinitions reorders attribute definitions
+// PUT /admin/user-attributes/reorder
+func (h *UserAttributeHandler) ReorderDefinitions(c *gin.Context) {
+	var req ReorderRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Convert IDs array to orders map (position in array = display_order)
+	orders := make(map[int64]int, len(req.IDs))
+	for i, id := range req.IDs {
+		orders[id] = i
+	}
+
+	if err := h.attrService.ReorderDefinitions(c.Request.Context(), orders); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Reorder successful"})
+}
+
+// GetUserAttributes gets a user's attribute values
+// GET /admin/users/:id/attributes
+func (h *UserAttributeHandler) GetUserAttributes(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	values, err := h.attrService.GetUserAttributes(c.Request.Context(), userID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]*AttributeValueResponse, 0, len(values))
+	for i := range values {
+		out = append(out, valueToResponse(&values[i]))
+	}
+
+	response.Success(c, out)
+}
+
+// UpdateUserAttributes updates a user's attribute values
+// PUT /admin/users/:id/attributes
+func (h *UserAttributeHandler) UpdateUserAttributes(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	var req UpdateUserAttributesRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	inputs := make([]service.UpdateUserAttributeInput, 0, len(req.Values))
+	for attrID, value := range req.Values {
+		inputs = append(inputs, service.UpdateUserAttributeInput{
+			AttributeID: attrID,
+			Value:       value,
+		})
+	}
+
+	if err := h.attrService.UpdateUserAttributes(c.Request.Context(), userID, inputs); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Return updated values
+	values, err := h.attrService.GetUserAttributes(c.Request.Context(), userID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]*AttributeValueResponse, 0, len(values))
+	for i := range values {
+		out = append(out, valueToResponse(&values[i]))
+	}
+
+	response.Success(c, out)
+}
+
+// GetBatchUserAttributes gets attribute values for multiple users
+// POST /admin/user-attributes/batch
+func (h *UserAttributeHandler) GetBatchUserAttributes(c *gin.Context) {
+	var req BatchGetUserAttributesRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	userIDs := normalizeInt64IDList(req.UserIDs)
+	if len(userIDs) == 0 {
+		response.Success(c, BatchUserAttributesResponse{Attributes: map[int64]map[int64]string{}})
+		return
+	}
+
+	keyRaw, _ := json.Marshal(struct {
+		UserIDs []int64 `json:"user_ids"`
+	}{
+		UserIDs: userIDs,
+	})
+	cacheKey := string(keyRaw)
+	if cached, ok := userAttributesBatchCache.Get(cacheKey); ok {
+		c.Header("X-Snapshot-Cache", "hit")
+		response.Success(c, cached.Payload)
+		return
+	}
+
+	attrs, err := h.attrService.GetBatchUserAttributes(c.Request.Context(), userIDs)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	payload := BatchUserAttributesResponse{Attributes: attrs}
+	userAttributesBatchCache.Set(cacheKey, payload)
+	c.Header("X-Snapshot-Cache", "miss")
+	response.Success(c, payload)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/admin/user_handler.go

@@ -0,0 +1,368 @@
+package admin
+
+import (
+	"context"
+	"strconv"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// UserWithConcurrency wraps AdminUser with current concurrency info
+type UserWithConcurrency struct {
+	dto.AdminUser
+	CurrentConcurrency int `json:"current_concurrency"`
+}
+
+// UserHandler handles admin user management
+type UserHandler struct {
+	adminService       service.AdminService
+	concurrencyService *service.ConcurrencyService
+}
+
+// NewUserHandler creates a new admin user handler
+func NewUserHandler(adminService service.AdminService, concurrencyService *service.ConcurrencyService) *UserHandler {
+	return &UserHandler{
+		adminService:       adminService,
+		concurrencyService: concurrencyService,
+	}
+}
+
+// CreateUserRequest represents admin create user request
+type CreateUserRequest struct {
+	Email                 string  `json:"email" binding:"required,email"`
+	Password              string  `json:"password" binding:"required,min=6"`
+	Username              string  `json:"username"`
+	Notes                 string  `json:"notes"`
+	Balance               float64 `json:"balance"`
+	Concurrency           int     `json:"concurrency"`
+	AllowedGroups         []int64 `json:"allowed_groups"`
+	SoraStorageQuotaBytes int64   `json:"sora_storage_quota_bytes"`
+}
+
+// UpdateUserRequest represents admin update user request
+// 使用指针类型来区分"未提供"和"设置为0"
+type UpdateUserRequest struct {
+	Email         string   `json:"email" binding:"omitempty,email"`
+	Password      string   `json:"password" binding:"omitempty,min=6"`
+	Username      *string  `json:"username"`
+	Notes         *string  `json:"notes"`
+	Balance       *float64 `json:"balance"`
+	Concurrency   *int     `json:"concurrency"`
+	Status        string   `json:"status" binding:"omitempty,oneof=active disabled"`
+	AllowedGroups *[]int64 `json:"allowed_groups"`
+	// GroupRates 用户专属分组倍率配置
+	// map[groupID]*rate，nil 表示删除该分组的专属倍率
+	GroupRates            map[int64]*float64 `json:"group_rates"`
+	SoraStorageQuotaBytes *int64             `json:"sora_storage_quota_bytes"`
+}
+
+// UpdateBalanceRequest represents balance update request
+type UpdateBalanceRequest struct {
+	Balance   float64 `json:"balance" binding:"required,gt=0"`
+	Operation string  `json:"operation" binding:"required,oneof=set add subtract"`
+	Notes     string  `json:"notes"`
+}
+
+// List handles listing all users with pagination
+// GET /api/v1/admin/users
+// Query params:
+//   - status: filter by user status
+//   - role: filter by user role
+//   - search: search in email, username
+//   - attr[{id}]: filter by custom attribute value, e.g. attr[1]=company
+func (h *UserHandler) List(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+
+	search := c.Query("search")
+	// 标准化和验证 search 参数
+	search = strings.TrimSpace(search)
+	if runes := []rune(search); len(runes) > 100 {
+		search = string(runes[:100])
+	}
+
+	filters := service.UserListFilters{
+		Status:     c.Query("status"),
+		Role:       c.Query("role"),
+		Search:     search,
+		Attributes: parseAttributeFilters(c),
+	}
+	if raw, ok := c.GetQuery("include_subscriptions"); ok {
+		includeSubscriptions := parseBoolQueryWithDefault(raw, true)
+		filters.IncludeSubscriptions = &includeSubscriptions
+	}
+
+	users, total, err := h.adminService.ListUsers(c.Request.Context(), page, pageSize, filters)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Batch get current concurrency (nil map if unavailable)
+	var loadInfo map[int64]*service.UserLoadInfo
+	if len(users) > 0 && h.concurrencyService != nil {
+		usersConcurrency := make([]service.UserWithConcurrency, len(users))
+		for i := range users {
+			usersConcurrency[i] = service.UserWithConcurrency{
+				ID:             users[i].ID,
+				MaxConcurrency: users[i].Concurrency,
+			}
+		}
+		loadInfo, _ = h.concurrencyService.GetUsersLoadBatch(c.Request.Context(), usersConcurrency)
+	}
+
+	// Build response with concurrency info
+	out := make([]UserWithConcurrency, len(users))
+	for i := range users {
+		out[i] = UserWithConcurrency{
+			AdminUser: *dto.UserFromServiceAdmin(&users[i]),
+		}
+		if info := loadInfo[users[i].ID]; info != nil {
+			out[i].CurrentConcurrency = info.CurrentConcurrency
+		}
+	}
+
+	response.Paginated(c, out, total, page, pageSize)
+}
+
+// parseAttributeFilters extracts attribute filters from query params
+// Format: attr[{attributeID}]=value, e.g. attr[1]=company&attr[2]=developer
+func parseAttributeFilters(c *gin.Context) map[int64]string {
+	result := make(map[int64]string)
+
+	// Get all query params and look for attr[*] pattern
+	for key, values := range c.Request.URL.Query() {
+		if len(values) == 0 || values[0] == "" {
+			continue
+		}
+		// Check if key matches pattern attr[{id}]
+		if len(key) > 5 && key[:5] == "attr[" && key[len(key)-1] == ']' {
+			idStr := key[5 : len(key)-1]
+			id, err := strconv.ParseInt(idStr, 10, 64)
+			if err == nil && id > 0 {
+				result[id] = values[0]
+			}
+		}
+	}
+
+	return result
+}
+
+// GetByID handles getting a user by ID
+// GET /api/v1/admin/users/:id
+func (h *UserHandler) GetByID(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	user, err := h.adminService.GetUser(c.Request.Context(), userID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserFromServiceAdmin(user))
+}
+
+// Create handles creating a new user
+// POST /api/v1/admin/users
+func (h *UserHandler) Create(c *gin.Context) {
+	var req CreateUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	user, err := h.adminService.CreateUser(c.Request.Context(), &service.CreateUserInput{
+		Email:                 req.Email,
+		Password:              req.Password,
+		Username:              req.Username,
+		Notes:                 req.Notes,
+		Balance:               req.Balance,
+		Concurrency:           req.Concurrency,
+		AllowedGroups:         req.AllowedGroups,
+		SoraStorageQuotaBytes: req.SoraStorageQuotaBytes,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserFromServiceAdmin(user))
+}
+
+// Update handles updating a user
+// PUT /api/v1/admin/users/:id
+func (h *UserHandler) Update(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	var req UpdateUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// 使用指针类型直接传递，nil 表示未提供该字段
+	user, err := h.adminService.UpdateUser(c.Request.Context(), userID, &service.UpdateUserInput{
+		Email:                 req.Email,
+		Password:              req.Password,
+		Username:              req.Username,
+		Notes:                 req.Notes,
+		Balance:               req.Balance,
+		Concurrency:           req.Concurrency,
+		Status:                req.Status,
+		AllowedGroups:         req.AllowedGroups,
+		GroupRates:            req.GroupRates,
+		SoraStorageQuotaBytes: req.SoraStorageQuotaBytes,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserFromServiceAdmin(user))
+}
+
+// Delete handles deleting a user
+// DELETE /api/v1/admin/users/:id
+func (h *UserHandler) Delete(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	err = h.adminService.DeleteUser(c.Request.Context(), userID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "User deleted successfully"})
+}
+
+// UpdateBalance handles updating user balance
+// POST /api/v1/admin/users/:id/balance
+func (h *UserHandler) UpdateBalance(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	var req UpdateBalanceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	idempotencyPayload := struct {
+		UserID int64                `json:"user_id"`
+		Body   UpdateBalanceRequest `json:"body"`
+	}{
+		UserID: userID,
+		Body:   req,
+	}
+	executeAdminIdempotentJSON(c, "admin.users.balance.update", idempotencyPayload, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		user, execErr := h.adminService.UpdateUserBalance(ctx, userID, req.Balance, req.Operation, req.Notes)
+		if execErr != nil {
+			return nil, execErr
+		}
+		return dto.UserFromServiceAdmin(user), nil
+	})
+}
+
+// GetUserAPIKeys handles getting user's API keys
+// GET /api/v1/admin/users/:id/api-keys
+func (h *UserHandler) GetUserAPIKeys(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+
+	keys, total, err := h.adminService.GetUserAPIKeys(c.Request.Context(), userID, page, pageSize)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.APIKey, 0, len(keys))
+	for i := range keys {
+		out = append(out, *dto.APIKeyFromService(&keys[i]))
+	}
+	response.Paginated(c, out, total, page, pageSize)
+}
+
+// GetUserUsage handles getting user's usage statistics
+// GET /api/v1/admin/users/:id/usage
+func (h *UserHandler) GetUserUsage(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	period := c.DefaultQuery("period", "month")
+
+	stats, err := h.adminService.GetUserUsageStats(c.Request.Context(), userID, period)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, stats)
+}
+
+// GetBalanceHistory handles getting user's balance/concurrency change history
+// GET /api/v1/admin/users/:id/balance-history
+// Query params:
+//   - type: filter by record type (balance, admin_balance, concurrency, admin_concurrency, subscription)
+func (h *UserHandler) GetBalanceHistory(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	codeType := c.Query("type")
+
+	codes, total, totalRecharged, err := h.adminService.GetUserBalanceHistory(c.Request.Context(), userID, page, pageSize, codeType)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Convert to admin DTO (includes notes field for admin visibility)
+	out := make([]dto.AdminRedeemCode, 0, len(codes))
+	for i := range codes {
+		out = append(out, *dto.RedeemCodeFromServiceAdmin(&codes[i]))
+	}
+
+	// Custom response with total_recharged alongside pagination
+	pages := int((total + int64(pageSize) - 1) / int64(pageSize))
+	if pages < 1 {
+		pages = 1
+	}
+	response.Success(c, gin.H{
+		"items":           out,
+		"total":           total,
+		"page":            page,
+		"page_size":       pageSize,
+		"pages":           pages,
+		"total_recharged": totalRecharged,
+	})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/announcement_handler.go

@@ -0,0 +1,81 @@
+package handler
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// AnnouncementHandler handles user announcement operations
+type AnnouncementHandler struct {
+	announcementService *service.AnnouncementService
+}
+
+// NewAnnouncementHandler creates a new user announcement handler
+func NewAnnouncementHandler(announcementService *service.AnnouncementService) *AnnouncementHandler {
+	return &AnnouncementHandler{
+		announcementService: announcementService,
+	}
+}
+
+// List handles listing announcements visible to current user
+// GET /api/v1/announcements
+func (h *AnnouncementHandler) List(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not found in context")
+		return
+	}
+
+	unreadOnly := parseBoolQuery(c.Query("unread_only"))
+
+	items, err := h.announcementService.ListForUser(c.Request.Context(), subject.UserID, unreadOnly)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.UserAnnouncement, 0, len(items))
+	for i := range items {
+		out = append(out, *dto.UserAnnouncementFromService(&items[i]))
+	}
+	response.Success(c, out)
+}
+
+// MarkRead marks an announcement as read for current user
+// POST /api/v1/announcements/:id/read
+func (h *AnnouncementHandler) MarkRead(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not found in context")
+		return
+	}
+
+	announcementID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil || announcementID <= 0 {
+		response.BadRequest(c, "Invalid announcement ID")
+		return
+	}
+
+	if err := h.announcementService.MarkRead(c.Request.Context(), subject.UserID, announcementID); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "ok"})
+}
+
+func parseBoolQuery(v string) bool {
+	switch strings.TrimSpace(strings.ToLower(v)) {
+	case "1", "true", "yes", "y", "on":
+		return true
+	default:
+		return false
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/api_key_handler.go

@@ -0,0 +1,306 @@
+// Package handler provides HTTP request handlers for the application.
+package handler
+
+import (
+	"context"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// APIKeyHandler handles API key-related requests
+type APIKeyHandler struct {
+	apiKeyService *service.APIKeyService
+}
+
+// NewAPIKeyHandler creates a new APIKeyHandler
+func NewAPIKeyHandler(apiKeyService *service.APIKeyService) *APIKeyHandler {
+	return &APIKeyHandler{
+		apiKeyService: apiKeyService,
+	}
+}
+
+// CreateAPIKeyRequest represents the create API key request payload
+type CreateAPIKeyRequest struct {
+	Name          string   `json:"name" binding:"required"`
+	GroupID       *int64   `json:"group_id"`        // nullable
+	CustomKey     *string  `json:"custom_key"`      // 可选的自定义key
+	IPWhitelist   []string `json:"ip_whitelist"`    // IP 白名单
+	IPBlacklist   []string `json:"ip_blacklist"`    // IP 黑名单
+	Quota         *float64 `json:"quota"`           // 配额限制 (USD)
+	ExpiresInDays *int     `json:"expires_in_days"` // 过期天数
+
+	// Rate limit fields (0 = unlimited)
+	RateLimit5h *float64 `json:"rate_limit_5h"`
+	RateLimit1d *float64 `json:"rate_limit_1d"`
+	RateLimit7d *float64 `json:"rate_limit_7d"`
+}
+
+// UpdateAPIKeyRequest represents the update API key request payload
+type UpdateAPIKeyRequest struct {
+	Name        string   `json:"name"`
+	GroupID     *int64   `json:"group_id"`
+	Status      string   `json:"status" binding:"omitempty,oneof=active inactive"`
+	IPWhitelist []string `json:"ip_whitelist"` // IP 白名单
+	IPBlacklist []string `json:"ip_blacklist"` // IP 黑名单
+	Quota       *float64 `json:"quota"`        // 配额限制 (USD), 0=无限制
+	ExpiresAt   *string  `json:"expires_at"`   // 过期时间 (ISO 8601)
+	ResetQuota  *bool    `json:"reset_quota"`  // 重置已用配额
+
+	// Rate limit fields (nil = no change, 0 = unlimited)
+	RateLimit5h         *float64 `json:"rate_limit_5h"`
+	RateLimit1d         *float64 `json:"rate_limit_1d"`
+	RateLimit7d         *float64 `json:"rate_limit_7d"`
+	ResetRateLimitUsage *bool    `json:"reset_rate_limit_usage"` // 重置限速用量
+}
+
+// List handles listing user's API keys with pagination
+// GET /api/v1/api-keys
+func (h *APIKeyHandler) List(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
+
+	// Parse filter parameters
+	var filters service.APIKeyListFilters
+	if search := strings.TrimSpace(c.Query("search")); search != "" {
+		if len(search) > 100 {
+			search = search[:100]
+		}
+		filters.Search = search
+	}
+	filters.Status = c.Query("status")
+	if groupIDStr := c.Query("group_id"); groupIDStr != "" {
+		gid, err := strconv.ParseInt(groupIDStr, 10, 64)
+		if err == nil {
+			filters.GroupID = &gid
+		}
+	}
+
+	keys, result, err := h.apiKeyService.List(c.Request.Context(), subject.UserID, params, filters)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.APIKey, 0, len(keys))
+	for i := range keys {
+		out = append(out, *dto.APIKeyFromService(&keys[i]))
+	}
+	response.Paginated(c, out, result.Total, page, pageSize)
+}
+
+// GetByID handles getting a single API key
+// GET /api/v1/api-keys/:id
+func (h *APIKeyHandler) GetByID(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	keyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid key ID")
+		return
+	}
+
+	key, err := h.apiKeyService.GetByID(c.Request.Context(), keyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// 验证所有权
+	if key.UserID != subject.UserID {
+		response.Forbidden(c, "Not authorized to access this key")
+		return
+	}
+
+	response.Success(c, dto.APIKeyFromService(key))
+}
+
+// Create handles creating a new API key
+// POST /api/v1/api-keys
+func (h *APIKeyHandler) Create(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var req CreateAPIKeyRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	svcReq := service.CreateAPIKeyRequest{
+		Name:          req.Name,
+		GroupID:       req.GroupID,
+		CustomKey:     req.CustomKey,
+		IPWhitelist:   req.IPWhitelist,
+		IPBlacklist:   req.IPBlacklist,
+		ExpiresInDays: req.ExpiresInDays,
+	}
+	if req.Quota != nil {
+		svcReq.Quota = *req.Quota
+	}
+	if req.RateLimit5h != nil {
+		svcReq.RateLimit5h = *req.RateLimit5h
+	}
+	if req.RateLimit1d != nil {
+		svcReq.RateLimit1d = *req.RateLimit1d
+	}
+	if req.RateLimit7d != nil {
+		svcReq.RateLimit7d = *req.RateLimit7d
+	}
+
+	executeUserIdempotentJSON(c, "user.api_keys.create", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		key, err := h.apiKeyService.Create(ctx, subject.UserID, svcReq)
+		if err != nil {
+			return nil, err
+		}
+		return dto.APIKeyFromService(key), nil
+	})
+}
+
+// Update handles updating an API key
+// PUT /api/v1/api-keys/:id
+func (h *APIKeyHandler) Update(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	keyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid key ID")
+		return
+	}
+
+	var req UpdateAPIKeyRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	svcReq := service.UpdateAPIKeyRequest{
+		IPWhitelist:         req.IPWhitelist,
+		IPBlacklist:         req.IPBlacklist,
+		Quota:               req.Quota,
+		ResetQuota:          req.ResetQuota,
+		RateLimit5h:         req.RateLimit5h,
+		RateLimit1d:         req.RateLimit1d,
+		RateLimit7d:         req.RateLimit7d,
+		ResetRateLimitUsage: req.ResetRateLimitUsage,
+	}
+	if req.Name != "" {
+		svcReq.Name = &req.Name
+	}
+	svcReq.GroupID = req.GroupID
+	if req.Status != "" {
+		svcReq.Status = &req.Status
+	}
+	// Parse expires_at if provided
+	if req.ExpiresAt != nil {
+		if *req.ExpiresAt == "" {
+			// Empty string means clear expiration
+			svcReq.ExpiresAt = nil
+			svcReq.ClearExpiration = true
+		} else {
+			t, err := time.Parse(time.RFC3339, *req.ExpiresAt)
+			if err != nil {
+				response.BadRequest(c, "Invalid expires_at format: "+err.Error())
+				return
+			}
+			svcReq.ExpiresAt = &t
+		}
+	}
+
+	key, err := h.apiKeyService.Update(c.Request.Context(), keyID, subject.UserID, svcReq)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.APIKeyFromService(key))
+}
+
+// Delete handles deleting an API key
+// DELETE /api/v1/api-keys/:id
+func (h *APIKeyHandler) Delete(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	keyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid key ID")
+		return
+	}
+
+	err = h.apiKeyService.Delete(c.Request.Context(), keyID, subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "API key deleted successfully"})
+}
+
+// GetAvailableGroups 获取用户可以绑定的分组列表
+// GET /api/v1/groups/available
+func (h *APIKeyHandler) GetAvailableGroups(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	groups, err := h.apiKeyService.GetAvailableGroups(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.Group, 0, len(groups))
+	for i := range groups {
+		out = append(out, *dto.GroupFromService(&groups[i]))
+	}
+	response.Success(c, out)
+}
+
+// GetUserGroupRates 获取当前用户的专属分组倍率配置
+// GET /api/v1/groups/rates
+func (h *APIKeyHandler) GetUserGroupRates(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	rates, err := h.apiKeyService.GetUserGroupRates(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, rates)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/auth_handler.go

@@ -0,0 +1,610 @@
+package handler
+
+import (
+	"log/slog"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// AuthHandler handles authentication-related requests
+type AuthHandler struct {
+	cfg           *config.Config
+	authService   *service.AuthService
+	userService   *service.UserService
+	settingSvc    *service.SettingService
+	promoService  *service.PromoService
+	redeemService *service.RedeemService
+	totpService   *service.TotpService
+}
+
+// NewAuthHandler creates a new AuthHandler
+func NewAuthHandler(cfg *config.Config, authService *service.AuthService, userService *service.UserService, settingService *service.SettingService, promoService *service.PromoService, redeemService *service.RedeemService, totpService *service.TotpService) *AuthHandler {
+	return &AuthHandler{
+		cfg:           cfg,
+		authService:   authService,
+		userService:   userService,
+		settingSvc:    settingService,
+		promoService:  promoService,
+		redeemService: redeemService,
+		totpService:   totpService,
+	}
+}
+
+// RegisterRequest represents the registration request payload
+type RegisterRequest struct {
+	Email          string `json:"email" binding:"required,email"`
+	Password       string `json:"password" binding:"required,min=6"`
+	VerifyCode     string `json:"verify_code"`
+	TurnstileToken string `json:"turnstile_token"`
+	PromoCode      string `json:"promo_code"`      // 注册优惠码
+	InvitationCode string `json:"invitation_code"` // 邀请码
+}
+
+// SendVerifyCodeRequest 发送验证码请求
+type SendVerifyCodeRequest struct {
+	Email          string `json:"email" binding:"required,email"`
+	TurnstileToken string `json:"turnstile_token"`
+}
+
+// SendVerifyCodeResponse 发送验证码响应
+type SendVerifyCodeResponse struct {
+	Message   string `json:"message"`
+	Countdown int    `json:"countdown"` // 倒计时秒数
+}
+
+// LoginRequest represents the login request payload
+type LoginRequest struct {
+	Email          string `json:"email" binding:"required,email"`
+	Password       string `json:"password" binding:"required"`
+	TurnstileToken string `json:"turnstile_token"`
+}
+
+// AuthResponse 认证响应格式（匹配前端期望）
+type AuthResponse struct {
+	AccessToken  string    `json:"access_token"`
+	RefreshToken string    `json:"refresh_token,omitempty"` // 新增：Refresh Token
+	ExpiresIn    int       `json:"expires_in,omitempty"`    // 新增：Access Token有效期（秒）
+	TokenType    string    `json:"token_type"`
+	User         *dto.User `json:"user"`
+}
+
+// respondWithTokenPair 生成 Token 对并返回认证响应
+// 如果 Token 对生成失败，回退到只返回 Access Token（向后兼容）
+func (h *AuthHandler) respondWithTokenPair(c *gin.Context, user *service.User) {
+	tokenPair, err := h.authService.GenerateTokenPair(c.Request.Context(), user, "")
+	if err != nil {
+		slog.Error("failed to generate token pair", "error", err, "user_id", user.ID)
+		// 回退到只返回Access Token
+		token, tokenErr := h.authService.GenerateToken(user)
+		if tokenErr != nil {
+			response.InternalError(c, "Failed to generate token")
+			return
+		}
+		response.Success(c, AuthResponse{
+			AccessToken: token,
+			TokenType:   "Bearer",
+			User:        dto.UserFromService(user),
+		})
+		return
+	}
+	response.Success(c, AuthResponse{
+		AccessToken:  tokenPair.AccessToken,
+		RefreshToken: tokenPair.RefreshToken,
+		ExpiresIn:    tokenPair.ExpiresIn,
+		TokenType:    "Bearer",
+		User:         dto.UserFromService(user),
+	})
+}
+
+// Register handles user registration
+// POST /api/v1/auth/register
+func (h *AuthHandler) Register(c *gin.Context) {
+	var req RegisterRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Turnstile 验证（邮箱验证码注册场景避免重复校验一次性 token）
+	if err := h.authService.VerifyTurnstileForRegister(c.Request.Context(), req.TurnstileToken, ip.GetClientIP(c), req.VerifyCode); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	_, user, err := h.authService.RegisterWithVerification(c.Request.Context(), req.Email, req.Password, req.VerifyCode, req.PromoCode, req.InvitationCode)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	h.respondWithTokenPair(c, user)
+}
+
+// SendVerifyCode 发送邮箱验证码
+// POST /api/v1/auth/send-verify-code
+func (h *AuthHandler) SendVerifyCode(c *gin.Context) {
+	var req SendVerifyCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Turnstile 验证
+	if err := h.authService.VerifyTurnstile(c.Request.Context(), req.TurnstileToken, ip.GetClientIP(c)); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	result, err := h.authService.SendVerifyCodeAsync(c.Request.Context(), req.Email)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, SendVerifyCodeResponse{
+		Message:   "Verification code sent successfully",
+		Countdown: result.Countdown,
+	})
+}
+
+// Login handles user login
+// POST /api/v1/auth/login
+func (h *AuthHandler) Login(c *gin.Context) {
+	var req LoginRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Turnstile 验证
+	if err := h.authService.VerifyTurnstile(c.Request.Context(), req.TurnstileToken, ip.GetClientIP(c)); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	token, user, err := h.authService.Login(c.Request.Context(), req.Email, req.Password)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	_ = token // token 由 authService.Login 返回但此处由 respondWithTokenPair 重新生成
+
+	// Check if TOTP 2FA is enabled for this user
+	if h.totpService != nil && h.settingSvc.IsTotpEnabled(c.Request.Context()) && user.TotpEnabled {
+		// Create a temporary login session for 2FA
+		tempToken, err := h.totpService.CreateLoginSession(c.Request.Context(), user.ID, user.Email)
+		if err != nil {
+			response.InternalError(c, "Failed to create 2FA session")
+			return
+		}
+
+		response.Success(c, TotpLoginResponse{
+			Requires2FA:     true,
+			TempToken:       tempToken,
+			UserEmailMasked: service.MaskEmail(user.Email),
+		})
+		return
+	}
+
+	// Backend mode: only admin can login
+	if h.settingSvc.IsBackendModeEnabled(c.Request.Context()) && !user.IsAdmin() {
+		response.Forbidden(c, "Backend mode is active. Only admin login is allowed.")
+		return
+	}
+
+	h.respondWithTokenPair(c, user)
+}
+
+// TotpLoginResponse represents the response when 2FA is required
+type TotpLoginResponse struct {
+	Requires2FA     bool   `json:"requires_2fa"`
+	TempToken       string `json:"temp_token,omitempty"`
+	UserEmailMasked string `json:"user_email_masked,omitempty"`
+}
+
+// Login2FARequest represents the 2FA login request
+type Login2FARequest struct {
+	TempToken string `json:"temp_token" binding:"required"`
+	TotpCode  string `json:"totp_code" binding:"required,len=6"`
+}
+
+// Login2FA completes the login with 2FA verification
+// POST /api/v1/auth/login/2fa
+func (h *AuthHandler) Login2FA(c *gin.Context) {
+	var req Login2FARequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	slog.Debug("login_2fa_request",
+		"temp_token_len", len(req.TempToken),
+		"totp_code_len", len(req.TotpCode))
+
+	// Get the login session
+	session, err := h.totpService.GetLoginSession(c.Request.Context(), req.TempToken)
+	if err != nil || session == nil {
+		tokenPrefix := ""
+		if len(req.TempToken) >= 8 {
+			tokenPrefix = req.TempToken[:8]
+		}
+		slog.Debug("login_2fa_session_invalid",
+			"temp_token_prefix", tokenPrefix,
+			"error", err)
+		response.BadRequest(c, "Invalid or expired 2FA session")
+		return
+	}
+
+	slog.Debug("login_2fa_session_found",
+		"user_id", session.UserID,
+		"email", session.Email)
+
+	// Verify the TOTP code
+	if err := h.totpService.VerifyCode(c.Request.Context(), session.UserID, req.TotpCode); err != nil {
+		slog.Debug("login_2fa_verify_failed",
+			"user_id", session.UserID,
+			"error", err)
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Get the user (before session deletion so we can check backend mode)
+	user, err := h.userService.GetByID(c.Request.Context(), session.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Backend mode: only admin can login (check BEFORE deleting session)
+	if h.settingSvc.IsBackendModeEnabled(c.Request.Context()) && !user.IsAdmin() {
+		response.Forbidden(c, "Backend mode is active. Only admin login is allowed.")
+		return
+	}
+
+	// Delete the login session (only after all checks pass)
+	_ = h.totpService.DeleteLoginSession(c.Request.Context(), req.TempToken)
+
+	h.respondWithTokenPair(c, user)
+}
+
+// GetCurrentUser handles getting current authenticated user
+// GET /api/v1/auth/me
+func (h *AuthHandler) GetCurrentUser(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	user, err := h.userService.GetByID(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	type UserResponse struct {
+		*dto.User
+		RunMode string `json:"run_mode"`
+	}
+
+	runMode := config.RunModeStandard
+	if h.cfg != nil {
+		runMode = h.cfg.RunMode
+	}
+
+	response.Success(c, UserResponse{User: dto.UserFromService(user), RunMode: runMode})
+}
+
+// ValidatePromoCodeRequest 验证优惠码请求
+type ValidatePromoCodeRequest struct {
+	Code string `json:"code" binding:"required"`
+}
+
+// ValidatePromoCodeResponse 验证优惠码响应
+type ValidatePromoCodeResponse struct {
+	Valid       bool    `json:"valid"`
+	BonusAmount float64 `json:"bonus_amount,omitempty"`
+	ErrorCode   string  `json:"error_code,omitempty"`
+	Message     string  `json:"message,omitempty"`
+}
+
+// ValidatePromoCode 验证优惠码（公开接口，注册前调用）
+// POST /api/v1/auth/validate-promo-code
+func (h *AuthHandler) ValidatePromoCode(c *gin.Context) {
+	// 检查优惠码功能是否启用
+	if h.settingSvc != nil && !h.settingSvc.IsPromoCodeEnabled(c.Request.Context()) {
+		response.Success(c, ValidatePromoCodeResponse{
+			Valid:     false,
+			ErrorCode: "PROMO_CODE_DISABLED",
+		})
+		return
+	}
+
+	var req ValidatePromoCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	promoCode, err := h.promoService.ValidatePromoCode(c.Request.Context(), req.Code)
+	if err != nil {
+		// 根据错误类型返回对应的错误码
+		errorCode := "PROMO_CODE_INVALID"
+		switch err {
+		case service.ErrPromoCodeNotFound:
+			errorCode = "PROMO_CODE_NOT_FOUND"
+		case service.ErrPromoCodeExpired:
+			errorCode = "PROMO_CODE_EXPIRED"
+		case service.ErrPromoCodeDisabled:
+			errorCode = "PROMO_CODE_DISABLED"
+		case service.ErrPromoCodeMaxUsed:
+			errorCode = "PROMO_CODE_MAX_USED"
+		case service.ErrPromoCodeAlreadyUsed:
+			errorCode = "PROMO_CODE_ALREADY_USED"
+		}
+
+		response.Success(c, ValidatePromoCodeResponse{
+			Valid:     false,
+			ErrorCode: errorCode,
+		})
+		return
+	}
+
+	if promoCode == nil {
+		response.Success(c, ValidatePromoCodeResponse{
+			Valid:     false,
+			ErrorCode: "PROMO_CODE_INVALID",
+		})
+		return
+	}
+
+	response.Success(c, ValidatePromoCodeResponse{
+		Valid:       true,
+		BonusAmount: promoCode.BonusAmount,
+	})
+}
+
+// ValidateInvitationCodeRequest 验证邀请码请求
+type ValidateInvitationCodeRequest struct {
+	Code string `json:"code" binding:"required"`
+}
+
+// ValidateInvitationCodeResponse 验证邀请码响应
+type ValidateInvitationCodeResponse struct {
+	Valid     bool   `json:"valid"`
+	ErrorCode string `json:"error_code,omitempty"`
+}
+
+// ValidateInvitationCode 验证邀请码（公开接口，注册前调用）
+// POST /api/v1/auth/validate-invitation-code
+func (h *AuthHandler) ValidateInvitationCode(c *gin.Context) {
+	// 检查邀请码功能是否启用
+	if h.settingSvc == nil || !h.settingSvc.IsInvitationCodeEnabled(c.Request.Context()) {
+		response.Success(c, ValidateInvitationCodeResponse{
+			Valid:     false,
+			ErrorCode: "INVITATION_CODE_DISABLED",
+		})
+		return
+	}
+
+	var req ValidateInvitationCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// 验证邀请码
+	redeemCode, err := h.redeemService.GetByCode(c.Request.Context(), req.Code)
+	if err != nil {
+		response.Success(c, ValidateInvitationCodeResponse{
+			Valid:     false,
+			ErrorCode: "INVITATION_CODE_NOT_FOUND",
+		})
+		return
+	}
+
+	// 检查类型和状态
+	if redeemCode.Type != service.RedeemTypeInvitation {
+		response.Success(c, ValidateInvitationCodeResponse{
+			Valid:     false,
+			ErrorCode: "INVITATION_CODE_INVALID",
+		})
+		return
+	}
+
+	if redeemCode.Status != service.StatusUnused {
+		response.Success(c, ValidateInvitationCodeResponse{
+			Valid:     false,
+			ErrorCode: "INVITATION_CODE_USED",
+		})
+		return
+	}
+
+	response.Success(c, ValidateInvitationCodeResponse{
+		Valid: true,
+	})
+}
+
+// ForgotPasswordRequest 忘记密码请求
+type ForgotPasswordRequest struct {
+	Email          string `json:"email" binding:"required,email"`
+	TurnstileToken string `json:"turnstile_token"`
+}
+
+// ForgotPasswordResponse 忘记密码响应
+type ForgotPasswordResponse struct {
+	Message string `json:"message"`
+}
+
+// ForgotPassword 请求密码重置
+// POST /api/v1/auth/forgot-password
+func (h *AuthHandler) ForgotPassword(c *gin.Context) {
+	var req ForgotPasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Turnstile 验证
+	if err := h.authService.VerifyTurnstile(c.Request.Context(), req.TurnstileToken, ip.GetClientIP(c)); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	frontendBaseURL := strings.TrimSpace(h.settingSvc.GetFrontendURL(c.Request.Context()))
+	if frontendBaseURL == "" {
+		slog.Error("frontend_url not configured in settings or config; cannot build password reset link")
+		response.InternalError(c, "Password reset is not configured")
+		return
+	}
+
+	// Request password reset (async)
+	// Note: This returns success even if email doesn't exist (to prevent enumeration)
+	if err := h.authService.RequestPasswordResetAsync(c.Request.Context(), req.Email, frontendBaseURL); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, ForgotPasswordResponse{
+		Message: "If your email is registered, you will receive a password reset link shortly.",
+	})
+}
+
+// ResetPasswordRequest 重置密码请求
+type ResetPasswordRequest struct {
+	Email       string `json:"email" binding:"required,email"`
+	Token       string `json:"token" binding:"required"`
+	NewPassword string `json:"new_password" binding:"required,min=6"`
+}
+
+// ResetPasswordResponse 重置密码响应
+type ResetPasswordResponse struct {
+	Message string `json:"message"`
+}
+
+// ResetPassword 重置密码
+// POST /api/v1/auth/reset-password
+func (h *AuthHandler) ResetPassword(c *gin.Context) {
+	var req ResetPasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Reset password
+	if err := h.authService.ResetPassword(c.Request.Context(), req.Email, req.Token, req.NewPassword); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, ResetPasswordResponse{
+		Message: "Your password has been reset successfully. You can now log in with your new password.",
+	})
+}
+
+// ==================== Token Refresh Endpoints ====================
+
+// RefreshTokenRequest 刷新Token请求
+type RefreshTokenRequest struct {
+	RefreshToken string `json:"refresh_token" binding:"required"`
+}
+
+// RefreshTokenResponse 刷新Token响应
+type RefreshTokenResponse struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+	ExpiresIn    int    `json:"expires_in"` // Access Token有效期（秒）
+	TokenType    string `json:"token_type"`
+}
+
+// RefreshToken 刷新Token
+// POST /api/v1/auth/refresh
+func (h *AuthHandler) RefreshToken(c *gin.Context) {
+	var req RefreshTokenRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	result, err := h.authService.RefreshTokenPair(c.Request.Context(), req.RefreshToken)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Backend mode: block non-admin token refresh
+	if h.settingSvc.IsBackendModeEnabled(c.Request.Context()) && result.UserRole != "admin" {
+		response.Forbidden(c, "Backend mode is active. Only admin login is allowed.")
+		return
+	}
+
+	response.Success(c, RefreshTokenResponse{
+		AccessToken:  result.AccessToken,
+		RefreshToken: result.RefreshToken,
+		ExpiresIn:    result.ExpiresIn,
+		TokenType:    "Bearer",
+	})
+}
+
+// LogoutRequest 登出请求
+type LogoutRequest struct {
+	RefreshToken string `json:"refresh_token,omitempty"` // 可选：撤销指定的Refresh Token
+}
+
+// LogoutResponse 登出响应
+type LogoutResponse struct {
+	Message string `json:"message"`
+}
+
+// Logout 用户登出
+// POST /api/v1/auth/logout
+func (h *AuthHandler) Logout(c *gin.Context) {
+	var req LogoutRequest
+	// 允许空请求体（向后兼容）
+	_ = c.ShouldBindJSON(&req)
+
+	// 如果提供了Refresh Token，撤销它
+	if req.RefreshToken != "" {
+		if err := h.authService.RevokeRefreshToken(c.Request.Context(), req.RefreshToken); err != nil {
+			slog.Debug("failed to revoke refresh token", "error", err)
+			// 不影响登出流程
+		}
+	}
+
+	response.Success(c, LogoutResponse{
+		Message: "Logged out successfully",
+	})
+}
+
+// RevokeAllSessionsResponse 撤销所有会话响应
+type RevokeAllSessionsResponse struct {
+	Message string `json:"message"`
+}
+
+// RevokeAllSessions 撤销当前用户的所有会话
+// POST /api/v1/auth/revoke-all-sessions
+func (h *AuthHandler) RevokeAllSessions(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	if err := h.authService.RevokeAllUserSessions(c.Request.Context(), subject.UserID); err != nil {
+		slog.Error("failed to revoke all sessions", "user_id", subject.UserID, "error", err)
+		response.InternalError(c, "Failed to revoke sessions")
+		return
+	}
+
+	response.Success(c, RevokeAllSessionsResponse{
+		Message: "All sessions have been revoked. Please log in again.",
+	})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/auth_linuxdo_oauth.go

@@ -0,0 +1,730 @@
+package handler
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/oauth"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+	"github.com/imroc/req/v3"
+	"github.com/tidwall/gjson"
+)
+
+const (
+	linuxDoOAuthCookiePath        = "/api/v1/auth/oauth/linuxdo"
+	linuxDoOAuthStateCookieName   = "linuxdo_oauth_state"
+	linuxDoOAuthVerifierCookie    = "linuxdo_oauth_verifier"
+	linuxDoOAuthRedirectCookie    = "linuxdo_oauth_redirect"
+	linuxDoOAuthCookieMaxAgeSec   = 10 * 60 // 10 minutes
+	linuxDoOAuthDefaultRedirectTo = "/dashboard"
+	linuxDoOAuthDefaultFrontendCB = "/auth/linuxdo/callback"
+
+	linuxDoOAuthMaxRedirectLen      = 2048
+	linuxDoOAuthMaxFragmentValueLen = 512
+	linuxDoOAuthMaxSubjectLen       = 64 - len("linuxdo-")
+)
+
+type linuxDoTokenResponse struct {
+	AccessToken  string `json:"access_token"`
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int64  `json:"expires_in"`
+	RefreshToken string `json:"refresh_token,omitempty"`
+	Scope        string `json:"scope,omitempty"`
+}
+
+type linuxDoTokenExchangeError struct {
+	StatusCode          int
+	ProviderError       string
+	ProviderDescription string
+	Body                string
+}
+
+func (e *linuxDoTokenExchangeError) Error() string {
+	if e == nil {
+		return ""
+	}
+	parts := []string{fmt.Sprintf("token exchange status=%d", e.StatusCode)}
+	if strings.TrimSpace(e.ProviderError) != "" {
+		parts = append(parts, "error="+strings.TrimSpace(e.ProviderError))
+	}
+	if strings.TrimSpace(e.ProviderDescription) != "" {
+		parts = append(parts, "error_description="+strings.TrimSpace(e.ProviderDescription))
+	}
+	return strings.Join(parts, " ")
+}
+
+// LinuxDoOAuthStart 启动 LinuxDo Connect OAuth 登录流程。
+// GET /api/v1/auth/oauth/linuxdo/start?redirect=/dashboard
+func (h *AuthHandler) LinuxDoOAuthStart(c *gin.Context) {
+	cfg, err := h.getLinuxDoOAuthConfig(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	state, err := oauth.GenerateState()
+	if err != nil {
+		response.ErrorFrom(c, infraerrors.InternalServer("OAUTH_STATE_GEN_FAILED", "failed to generate oauth state").WithCause(err))
+		return
+	}
+
+	redirectTo := sanitizeFrontendRedirectPath(c.Query("redirect"))
+	if redirectTo == "" {
+		redirectTo = linuxDoOAuthDefaultRedirectTo
+	}
+
+	secureCookie := isRequestHTTPS(c)
+	setCookie(c, linuxDoOAuthStateCookieName, encodeCookieValue(state), linuxDoOAuthCookieMaxAgeSec, secureCookie)
+	setCookie(c, linuxDoOAuthRedirectCookie, encodeCookieValue(redirectTo), linuxDoOAuthCookieMaxAgeSec, secureCookie)
+
+	codeChallenge := ""
+	if cfg.UsePKCE {
+		verifier, err := oauth.GenerateCodeVerifier()
+		if err != nil {
+			response.ErrorFrom(c, infraerrors.InternalServer("OAUTH_PKCE_GEN_FAILED", "failed to generate pkce verifier").WithCause(err))
+			return
+		}
+		codeChallenge = oauth.GenerateCodeChallenge(verifier)
+		setCookie(c, linuxDoOAuthVerifierCookie, encodeCookieValue(verifier), linuxDoOAuthCookieMaxAgeSec, secureCookie)
+	}
+
+	redirectURI := strings.TrimSpace(cfg.RedirectURL)
+	if redirectURI == "" {
+		response.ErrorFrom(c, infraerrors.InternalServer("OAUTH_CONFIG_INVALID", "oauth redirect url not configured"))
+		return
+	}
+
+	authURL, err := buildLinuxDoAuthorizeURL(cfg, state, codeChallenge, redirectURI)
+	if err != nil {
+		response.ErrorFrom(c, infraerrors.InternalServer("OAUTH_BUILD_URL_FAILED", "failed to build oauth authorization url").WithCause(err))
+		return
+	}
+
+	c.Redirect(http.StatusFound, authURL)
+}
+
+// LinuxDoOAuthCallback 处理 OAuth 回调：创建/登录用户，然后重定向到前端。
+// GET /api/v1/auth/oauth/linuxdo/callback?code=...&state=...
+func (h *AuthHandler) LinuxDoOAuthCallback(c *gin.Context) {
+	cfg, cfgErr := h.getLinuxDoOAuthConfig(c.Request.Context())
+	if cfgErr != nil {
+		response.ErrorFrom(c, cfgErr)
+		return
+	}
+
+	frontendCallback := strings.TrimSpace(cfg.FrontendRedirectURL)
+	if frontendCallback == "" {
+		frontendCallback = linuxDoOAuthDefaultFrontendCB
+	}
+
+	if providerErr := strings.TrimSpace(c.Query("error")); providerErr != "" {
+		redirectOAuthError(c, frontendCallback, "provider_error", providerErr, c.Query("error_description"))
+		return
+	}
+
+	code := strings.TrimSpace(c.Query("code"))
+	state := strings.TrimSpace(c.Query("state"))
+	if code == "" || state == "" {
+		redirectOAuthError(c, frontendCallback, "missing_params", "missing code/state", "")
+		return
+	}
+
+	secureCookie := isRequestHTTPS(c)
+	defer func() {
+		clearCookie(c, linuxDoOAuthStateCookieName, secureCookie)
+		clearCookie(c, linuxDoOAuthVerifierCookie, secureCookie)
+		clearCookie(c, linuxDoOAuthRedirectCookie, secureCookie)
+	}()
+
+	expectedState, err := readCookieDecoded(c, linuxDoOAuthStateCookieName)
+	if err != nil || expectedState == "" || state != expectedState {
+		redirectOAuthError(c, frontendCallback, "invalid_state", "invalid oauth state", "")
+		return
+	}
+
+	redirectTo, _ := readCookieDecoded(c, linuxDoOAuthRedirectCookie)
+	redirectTo = sanitizeFrontendRedirectPath(redirectTo)
+	if redirectTo == "" {
+		redirectTo = linuxDoOAuthDefaultRedirectTo
+	}
+
+	codeVerifier := ""
+	if cfg.UsePKCE {
+		codeVerifier, _ = readCookieDecoded(c, linuxDoOAuthVerifierCookie)
+		if codeVerifier == "" {
+			redirectOAuthError(c, frontendCallback, "missing_verifier", "missing pkce verifier", "")
+			return
+		}
+	}
+
+	redirectURI := strings.TrimSpace(cfg.RedirectURL)
+	if redirectURI == "" {
+		redirectOAuthError(c, frontendCallback, "config_error", "oauth redirect url not configured", "")
+		return
+	}
+
+	tokenResp, err := linuxDoExchangeCode(c.Request.Context(), cfg, code, redirectURI, codeVerifier)
+	if err != nil {
+		description := ""
+		var exchangeErr *linuxDoTokenExchangeError
+		if errors.As(err, &exchangeErr) && exchangeErr != nil {
+			log.Printf(
+				"[LinuxDo OAuth] token exchange failed: status=%d provider_error=%q provider_description=%q body=%s",
+				exchangeErr.StatusCode,
+				exchangeErr.ProviderError,
+				exchangeErr.ProviderDescription,
+				truncateLogValue(exchangeErr.Body, 2048),
+			)
+			description = exchangeErr.Error()
+		} else {
+			log.Printf("[LinuxDo OAuth] token exchange failed: %v", err)
+			description = err.Error()
+		}
+		redirectOAuthError(c, frontendCallback, "token_exchange_failed", "failed to exchange oauth code", singleLine(description))
+		return
+	}
+
+	email, username, subject, err := linuxDoFetchUserInfo(c.Request.Context(), cfg, tokenResp)
+	if err != nil {
+		log.Printf("[LinuxDo OAuth] userinfo fetch failed: %v", err)
+		redirectOAuthError(c, frontendCallback, "userinfo_failed", "failed to fetch user info", "")
+		return
+	}
+
+	// 安全考虑：不要把第三方返回的 email 直接映射到本地账号（可能与本地邮箱用户冲突导致账号被接管）。
+	// 统一使用基于 subject 的稳定合成邮箱来做账号绑定。
+	if subject != "" {
+		email = linuxDoSyntheticEmail(subject)
+	}
+
+	// 传入空邀请码；如果需要邀请码，服务层返回 ErrOAuthInvitationRequired
+	tokenPair, _, err := h.authService.LoginOrRegisterOAuthWithTokenPair(c.Request.Context(), email, username, "")
+	if err != nil {
+		if errors.Is(err, service.ErrOAuthInvitationRequired) {
+			pendingToken, tokenErr := h.authService.CreatePendingOAuthToken(email, username)
+			if tokenErr != nil {
+				redirectOAuthError(c, frontendCallback, "login_failed", "service_error", "")
+				return
+			}
+			fragment := url.Values{}
+			fragment.Set("error", "invitation_required")
+			fragment.Set("pending_oauth_token", pendingToken)
+			fragment.Set("redirect", redirectTo)
+			redirectWithFragment(c, frontendCallback, fragment)
+			return
+		}
+		// 避免把内部细节泄露给客户端；给前端保留结构化原因与提示信息即可。
+		redirectOAuthError(c, frontendCallback, "login_failed", infraerrors.Reason(err), infraerrors.Message(err))
+		return
+	}
+
+	fragment := url.Values{}
+	fragment.Set("access_token", tokenPair.AccessToken)
+	fragment.Set("refresh_token", tokenPair.RefreshToken)
+	fragment.Set("expires_in", fmt.Sprintf("%d", tokenPair.ExpiresIn))
+	fragment.Set("token_type", "Bearer")
+	fragment.Set("redirect", redirectTo)
+	redirectWithFragment(c, frontendCallback, fragment)
+}
+
+type completeLinuxDoOAuthRequest struct {
+	PendingOAuthToken string `json:"pending_oauth_token" binding:"required"`
+	InvitationCode    string `json:"invitation_code"     binding:"required"`
+}
+
+// CompleteLinuxDoOAuthRegistration completes a pending OAuth registration by validating
+// the invitation code and creating the user account.
+// POST /api/v1/auth/oauth/linuxdo/complete-registration
+func (h *AuthHandler) CompleteLinuxDoOAuthRegistration(c *gin.Context) {
+	var req completeLinuxDoOAuthRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "INVALID_REQUEST", "message": err.Error()})
+		return
+	}
+
+	email, username, err := h.authService.VerifyPendingOAuthToken(req.PendingOAuthToken)
+	if err != nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "INVALID_TOKEN", "message": "invalid or expired registration token"})
+		return
+	}
+
+	tokenPair, _, err := h.authService.LoginOrRegisterOAuthWithTokenPair(c.Request.Context(), email, username, req.InvitationCode)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"access_token":  tokenPair.AccessToken,
+		"refresh_token": tokenPair.RefreshToken,
+		"expires_in":    tokenPair.ExpiresIn,
+		"token_type":    "Bearer",
+	})
+}
+
+func (h *AuthHandler) getLinuxDoOAuthConfig(ctx context.Context) (config.LinuxDoConnectConfig, error) {
+	if h != nil && h.settingSvc != nil {
+		return h.settingSvc.GetLinuxDoConnectOAuthConfig(ctx)
+	}
+	if h == nil || h.cfg == nil {
+		return config.LinuxDoConnectConfig{}, infraerrors.ServiceUnavailable("CONFIG_NOT_READY", "config not loaded")
+	}
+	if !h.cfg.LinuxDo.Enabled {
+		return config.LinuxDoConnectConfig{}, infraerrors.NotFound("OAUTH_DISABLED", "oauth login is disabled")
+	}
+	return h.cfg.LinuxDo, nil
+}
+
+func linuxDoExchangeCode(
+	ctx context.Context,
+	cfg config.LinuxDoConnectConfig,
+	code string,
+	redirectURI string,
+	codeVerifier string,
+) (*linuxDoTokenResponse, error) {
+	client := req.C().SetTimeout(30 * time.Second)
+
+	form := url.Values{}
+	form.Set("grant_type", "authorization_code")
+	form.Set("client_id", cfg.ClientID)
+	form.Set("code", code)
+	form.Set("redirect_uri", redirectURI)
+	if cfg.UsePKCE {
+		form.Set("code_verifier", codeVerifier)
+	}
+
+	r := client.R().
+		SetContext(ctx).
+		SetHeader("Accept", "application/json")
+
+	switch strings.ToLower(strings.TrimSpace(cfg.TokenAuthMethod)) {
+	case "", "client_secret_post":
+		form.Set("client_secret", cfg.ClientSecret)
+	case "client_secret_basic":
+		r.SetBasicAuth(cfg.ClientID, cfg.ClientSecret)
+	case "none":
+	default:
+		return nil, fmt.Errorf("unsupported token_auth_method: %s", cfg.TokenAuthMethod)
+	}
+
+	resp, err := r.SetFormDataFromValues(form).Post(cfg.TokenURL)
+	if err != nil {
+		return nil, fmt.Errorf("request token: %w", err)
+	}
+	body := strings.TrimSpace(resp.String())
+	if !resp.IsSuccessState() {
+		providerErr, providerDesc := parseOAuthProviderError(body)
+		return nil, &linuxDoTokenExchangeError{
+			StatusCode:          resp.StatusCode,
+			ProviderError:       providerErr,
+			ProviderDescription: providerDesc,
+			Body:                body,
+		}
+	}
+
+	tokenResp, ok := parseLinuxDoTokenResponse(body)
+	if !ok || strings.TrimSpace(tokenResp.AccessToken) == "" {
+		return nil, &linuxDoTokenExchangeError{
+			StatusCode: resp.StatusCode,
+			Body:       body,
+		}
+	}
+	if strings.TrimSpace(tokenResp.TokenType) == "" {
+		tokenResp.TokenType = "Bearer"
+	}
+	return tokenResp, nil
+}
+
+func linuxDoFetchUserInfo(
+	ctx context.Context,
+	cfg config.LinuxDoConnectConfig,
+	token *linuxDoTokenResponse,
+) (email string, username string, subject string, err error) {
+	client := req.C().SetTimeout(30 * time.Second)
+	authorization, err := buildBearerAuthorization(token.TokenType, token.AccessToken)
+	if err != nil {
+		return "", "", "", fmt.Errorf("invalid token for userinfo request: %w", err)
+	}
+
+	resp, err := client.R().
+		SetContext(ctx).
+		SetHeader("Accept", "application/json").
+		SetHeader("Authorization", authorization).
+		Get(cfg.UserInfoURL)
+	if err != nil {
+		return "", "", "", fmt.Errorf("request userinfo: %w", err)
+	}
+	if !resp.IsSuccessState() {
+		return "", "", "", fmt.Errorf("userinfo status=%d", resp.StatusCode)
+	}
+
+	return linuxDoParseUserInfo(resp.String(), cfg)
+}
+
+func linuxDoParseUserInfo(body string, cfg config.LinuxDoConnectConfig) (email string, username string, subject string, err error) {
+	email = firstNonEmpty(
+		getGJSON(body, cfg.UserInfoEmailPath),
+		getGJSON(body, "email"),
+		getGJSON(body, "user.email"),
+		getGJSON(body, "data.email"),
+		getGJSON(body, "attributes.email"),
+	)
+	username = firstNonEmpty(
+		getGJSON(body, cfg.UserInfoUsernamePath),
+		getGJSON(body, "username"),
+		getGJSON(body, "preferred_username"),
+		getGJSON(body, "name"),
+		getGJSON(body, "user.username"),
+		getGJSON(body, "user.name"),
+	)
+	subject = firstNonEmpty(
+		getGJSON(body, cfg.UserInfoIDPath),
+		getGJSON(body, "sub"),
+		getGJSON(body, "id"),
+		getGJSON(body, "user_id"),
+		getGJSON(body, "uid"),
+		getGJSON(body, "user.id"),
+	)
+
+	subject = strings.TrimSpace(subject)
+	if subject == "" {
+		return "", "", "", errors.New("userinfo missing id field")
+	}
+	if !isSafeLinuxDoSubject(subject) {
+		return "", "", "", errors.New("userinfo returned invalid id field")
+	}
+
+	email = strings.TrimSpace(email)
+	if email == "" {
+		// LinuxDo Connect 的 userinfo 可能不提供 email。为兼容现有用户模型（email 必填且唯一），使用稳定的合成邮箱。
+		email = linuxDoSyntheticEmail(subject)
+	}
+
+	username = strings.TrimSpace(username)
+	if username == "" {
+		username = "linuxdo_" + subject
+	}
+
+	return email, username, subject, nil
+}
+
+func buildLinuxDoAuthorizeURL(cfg config.LinuxDoConnectConfig, state string, codeChallenge string, redirectURI string) (string, error) {
+	u, err := url.Parse(cfg.AuthorizeURL)
+	if err != nil {
+		return "", fmt.Errorf("parse authorize_url: %w", err)
+	}
+
+	q := u.Query()
+	q.Set("response_type", "code")
+	q.Set("client_id", cfg.ClientID)
+	q.Set("redirect_uri", redirectURI)
+	if strings.TrimSpace(cfg.Scopes) != "" {
+		q.Set("scope", cfg.Scopes)
+	}
+	q.Set("state", state)
+	if cfg.UsePKCE {
+		q.Set("code_challenge", codeChallenge)
+		q.Set("code_challenge_method", "S256")
+	}
+
+	u.RawQuery = q.Encode()
+	return u.String(), nil
+}
+
+func redirectOAuthError(c *gin.Context, frontendCallback string, code string, message string, description string) {
+	fragment := url.Values{}
+	fragment.Set("error", truncateFragmentValue(code))
+	if strings.TrimSpace(message) != "" {
+		fragment.Set("error_message", truncateFragmentValue(message))
+	}
+	if strings.TrimSpace(description) != "" {
+		fragment.Set("error_description", truncateFragmentValue(description))
+	}
+	redirectWithFragment(c, frontendCallback, fragment)
+}
+
+func redirectWithFragment(c *gin.Context, frontendCallback string, fragment url.Values) {
+	u, err := url.Parse(frontendCallback)
+	if err != nil {
+		// 兜底：尽力跳转到默认页面，避免卡死在回调页。
+		c.Redirect(http.StatusFound, linuxDoOAuthDefaultRedirectTo)
+		return
+	}
+	if u.Scheme != "" && !strings.EqualFold(u.Scheme, "http") && !strings.EqualFold(u.Scheme, "https") {
+		c.Redirect(http.StatusFound, linuxDoOAuthDefaultRedirectTo)
+		return
+	}
+	u.Fragment = fragment.Encode()
+	c.Header("Cache-Control", "no-store")
+	c.Header("Pragma", "no-cache")
+	c.Redirect(http.StatusFound, u.String())
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		v = strings.TrimSpace(v)
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func parseOAuthProviderError(body string) (providerErr string, providerDesc string) {
+	body = strings.TrimSpace(body)
+	if body == "" {
+		return "", ""
+	}
+
+	providerErr = firstNonEmpty(
+		getGJSON(body, "error"),
+		getGJSON(body, "code"),
+		getGJSON(body, "error.code"),
+	)
+	providerDesc = firstNonEmpty(
+		getGJSON(body, "error_description"),
+		getGJSON(body, "error.message"),
+		getGJSON(body, "message"),
+		getGJSON(body, "detail"),
+	)
+
+	if providerErr != "" || providerDesc != "" {
+		return providerErr, providerDesc
+	}
+
+	values, err := url.ParseQuery(body)
+	if err != nil {
+		return "", ""
+	}
+	providerErr = firstNonEmpty(values.Get("error"), values.Get("code"))
+	providerDesc = firstNonEmpty(values.Get("error_description"), values.Get("error_message"), values.Get("message"))
+	return providerErr, providerDesc
+}
+
+func parseLinuxDoTokenResponse(body string) (*linuxDoTokenResponse, bool) {
+	body = strings.TrimSpace(body)
+	if body == "" {
+		return nil, false
+	}
+
+	accessToken := strings.TrimSpace(getGJSON(body, "access_token"))
+	if accessToken != "" {
+		tokenType := strings.TrimSpace(getGJSON(body, "token_type"))
+		refreshToken := strings.TrimSpace(getGJSON(body, "refresh_token"))
+		scope := strings.TrimSpace(getGJSON(body, "scope"))
+		expiresIn := gjson.Get(body, "expires_in").Int()
+		return &linuxDoTokenResponse{
+			AccessToken:  accessToken,
+			TokenType:    tokenType,
+			ExpiresIn:    expiresIn,
+			RefreshToken: refreshToken,
+			Scope:        scope,
+		}, true
+	}
+
+	values, err := url.ParseQuery(body)
+	if err != nil {
+		return nil, false
+	}
+	accessToken = strings.TrimSpace(values.Get("access_token"))
+	if accessToken == "" {
+		return nil, false
+	}
+	expiresIn := int64(0)
+	if raw := strings.TrimSpace(values.Get("expires_in")); raw != "" {
+		if v, err := strconv.ParseInt(raw, 10, 64); err == nil {
+			expiresIn = v
+		}
+	}
+	return &linuxDoTokenResponse{
+		AccessToken:  accessToken,
+		TokenType:    strings.TrimSpace(values.Get("token_type")),
+		ExpiresIn:    expiresIn,
+		RefreshToken: strings.TrimSpace(values.Get("refresh_token")),
+		Scope:        strings.TrimSpace(values.Get("scope")),
+	}, true
+}
+
+func getGJSON(body string, path string) string {
+	path = strings.TrimSpace(path)
+	if path == "" {
+		return ""
+	}
+	res := gjson.Get(body, path)
+	if !res.Exists() {
+		return ""
+	}
+	return res.String()
+}
+
+func truncateLogValue(value string, maxLen int) string {
+	value = strings.TrimSpace(value)
+	if value == "" || maxLen <= 0 {
+		return ""
+	}
+	if len(value) <= maxLen {
+		return value
+	}
+	value = value[:maxLen]
+	for !utf8.ValidString(value) {
+		value = value[:len(value)-1]
+	}
+	return value
+}
+
+func singleLine(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return ""
+	}
+	return strings.Join(strings.Fields(value), " ")
+}
+
+func sanitizeFrontendRedirectPath(path string) string {
+	path = strings.TrimSpace(path)
+	if path == "" {
+		return ""
+	}
+	if len(path) > linuxDoOAuthMaxRedirectLen {
+		return ""
+	}
+	// 只允许同源相对路径（避免开放重定向）。
+	if !strings.HasPrefix(path, "/") {
+		return ""
+	}
+	if strings.HasPrefix(path, "//") {
+		return ""
+	}
+	if strings.Contains(path, "://") {
+		return ""
+	}
+	if strings.ContainsAny(path, "\r\n") {
+		return ""
+	}
+	return path
+}
+
+func isRequestHTTPS(c *gin.Context) bool {
+	if c.Request.TLS != nil {
+		return true
+	}
+	proto := strings.ToLower(strings.TrimSpace(c.GetHeader("X-Forwarded-Proto")))
+	return proto == "https"
+}
+
+func encodeCookieValue(value string) string {
+	return base64.RawURLEncoding.EncodeToString([]byte(value))
+}
+
+func decodeCookieValue(value string) (string, error) {
+	raw, err := base64.RawURLEncoding.DecodeString(value)
+	if err != nil {
+		return "", err
+	}
+	return string(raw), nil
+}
+
+func readCookieDecoded(c *gin.Context, name string) (string, error) {
+	ck, err := c.Request.Cookie(name)
+	if err != nil {
+		return "", err
+	}
+	return decodeCookieValue(ck.Value)
+}
+
+func setCookie(c *gin.Context, name string, value string, maxAgeSec int, secure bool) {
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name:     name,
+		Value:    value,
+		Path:     linuxDoOAuthCookiePath,
+		MaxAge:   maxAgeSec,
+		HttpOnly: true,
+		Secure:   secure,
+		SameSite: http.SameSiteLaxMode,
+	})
+}
+
+func clearCookie(c *gin.Context, name string, secure bool) {
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name:     name,
+		Value:    "",
+		Path:     linuxDoOAuthCookiePath,
+		MaxAge:   -1,
+		HttpOnly: true,
+		Secure:   secure,
+		SameSite: http.SameSiteLaxMode,
+	})
+}
+
+func truncateFragmentValue(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return ""
+	}
+	if len(value) > linuxDoOAuthMaxFragmentValueLen {
+		value = value[:linuxDoOAuthMaxFragmentValueLen]
+		for !utf8.ValidString(value) {
+			value = value[:len(value)-1]
+		}
+	}
+	return value
+}
+
+func buildBearerAuthorization(tokenType, accessToken string) (string, error) {
+	tokenType = strings.TrimSpace(tokenType)
+	if tokenType == "" {
+		tokenType = "Bearer"
+	}
+	if !strings.EqualFold(tokenType, "Bearer") {
+		return "", fmt.Errorf("unsupported token_type: %s", tokenType)
+	}
+
+	accessToken = strings.TrimSpace(accessToken)
+	if accessToken == "" {
+		return "", errors.New("missing access_token")
+	}
+	if strings.ContainsAny(accessToken, " \t\r\n") {
+		return "", errors.New("access_token contains whitespace")
+	}
+	return "Bearer " + accessToken, nil
+}
+
+func isSafeLinuxDoSubject(subject string) bool {
+	subject = strings.TrimSpace(subject)
+	if subject == "" || len(subject) > linuxDoOAuthMaxSubjectLen {
+		return false
+	}
+	for _, r := range subject {
+		switch {
+		case r >= '0' && r <= '9':
+		case r >= 'a' && r <= 'z':
+		case r >= 'A' && r <= 'Z':
+		case r == '_' || r == '-':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
+func linuxDoSyntheticEmail(subject string) string {
+	subject = strings.TrimSpace(subject)
+	if subject == "" {
+		return ""
+	}
+	return "linuxdo-" + subject + service.LinuxDoConnectSyntheticEmailDomain
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/auth_linuxdo_oauth_test.go

@@ -0,0 +1,108 @@
+package handler
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSanitizeFrontendRedirectPath(t *testing.T) {
+	require.Equal(t, "/dashboard", sanitizeFrontendRedirectPath("/dashboard"))
+	require.Equal(t, "/dashboard", sanitizeFrontendRedirectPath(" /dashboard "))
+	require.Equal(t, "", sanitizeFrontendRedirectPath("dashboard"))
+	require.Equal(t, "", sanitizeFrontendRedirectPath("//evil.com"))
+	require.Equal(t, "", sanitizeFrontendRedirectPath("https://evil.com"))
+	require.Equal(t, "", sanitizeFrontendRedirectPath("/\nfoo"))
+
+	long := "/" + strings.Repeat("a", linuxDoOAuthMaxRedirectLen)
+	require.Equal(t, "", sanitizeFrontendRedirectPath(long))
+}
+
+func TestBuildBearerAuthorization(t *testing.T) {
+	auth, err := buildBearerAuthorization("", "token123")
+	require.NoError(t, err)
+	require.Equal(t, "Bearer token123", auth)
+
+	auth, err = buildBearerAuthorization("bearer", "token123")
+	require.NoError(t, err)
+	require.Equal(t, "Bearer token123", auth)
+
+	_, err = buildBearerAuthorization("MAC", "token123")
+	require.Error(t, err)
+
+	_, err = buildBearerAuthorization("Bearer", "token 123")
+	require.Error(t, err)
+}
+
+func TestLinuxDoParseUserInfoParsesIDAndUsername(t *testing.T) {
+	cfg := config.LinuxDoConnectConfig{
+		UserInfoURL: "https://connect.linux.do/api/user",
+	}
+
+	email, username, subject, err := linuxDoParseUserInfo(`{"id":123,"username":"alice"}`, cfg)
+	require.NoError(t, err)
+	require.Equal(t, "123", subject)
+	require.Equal(t, "alice", username)
+	require.Equal(t, "linuxdo-123@linuxdo-connect.invalid", email)
+}
+
+func TestLinuxDoParseUserInfoDefaultsUsername(t *testing.T) {
+	cfg := config.LinuxDoConnectConfig{
+		UserInfoURL: "https://connect.linux.do/api/user",
+	}
+
+	email, username, subject, err := linuxDoParseUserInfo(`{"id":"123"}`, cfg)
+	require.NoError(t, err)
+	require.Equal(t, "123", subject)
+	require.Equal(t, "linuxdo_123", username)
+	require.Equal(t, "linuxdo-123@linuxdo-connect.invalid", email)
+}
+
+func TestLinuxDoParseUserInfoRejectsUnsafeSubject(t *testing.T) {
+	cfg := config.LinuxDoConnectConfig{
+		UserInfoURL: "https://connect.linux.do/api/user",
+	}
+
+	_, _, _, err := linuxDoParseUserInfo(`{"id":"123@456"}`, cfg)
+	require.Error(t, err)
+
+	tooLong := strings.Repeat("a", linuxDoOAuthMaxSubjectLen+1)
+	_, _, _, err = linuxDoParseUserInfo(`{"id":"`+tooLong+`"}`, cfg)
+	require.Error(t, err)
+}
+
+func TestParseOAuthProviderErrorJSON(t *testing.T) {
+	code, desc := parseOAuthProviderError(`{"error":"invalid_client","error_description":"bad secret"}`)
+	require.Equal(t, "invalid_client", code)
+	require.Equal(t, "bad secret", desc)
+}
+
+func TestParseOAuthProviderErrorForm(t *testing.T) {
+	code, desc := parseOAuthProviderError("error=invalid_request&error_description=Missing+code_verifier")
+	require.Equal(t, "invalid_request", code)
+	require.Equal(t, "Missing code_verifier", desc)
+}
+
+func TestParseLinuxDoTokenResponseJSON(t *testing.T) {
+	token, ok := parseLinuxDoTokenResponse(`{"access_token":"t1","token_type":"Bearer","expires_in":3600,"scope":"user"}`)
+	require.True(t, ok)
+	require.Equal(t, "t1", token.AccessToken)
+	require.Equal(t, "Bearer", token.TokenType)
+	require.Equal(t, int64(3600), token.ExpiresIn)
+	require.Equal(t, "user", token.Scope)
+}
+
+func TestParseLinuxDoTokenResponseForm(t *testing.T) {
+	token, ok := parseLinuxDoTokenResponse("access_token=t2&token_type=bearer&expires_in=60")
+	require.True(t, ok)
+	require.Equal(t, "t2", token.AccessToken)
+	require.Equal(t, "bearer", token.TokenType)
+	require.Equal(t, int64(60), token.ExpiresIn)
+}
+
+func TestSingleLineStripsWhitespace(t *testing.T) {
+	require.Equal(t, "hello world", singleLine("hello\r\nworld"))
+	require.Equal(t, "", singleLine("\n\t\r"))
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/dto/announcement.go

@@ -0,0 +1,78 @@
+package dto
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+type Announcement struct {
+	ID         int64  `json:"id"`
+	Title      string `json:"title"`
+	Content    string `json:"content"`
+	Status     string `json:"status"`
+	NotifyMode string `json:"notify_mode"`
+
+	Targeting service.AnnouncementTargeting `json:"targeting"`
+
+	StartsAt *time.Time `json:"starts_at,omitempty"`
+	EndsAt   *time.Time `json:"ends_at,omitempty"`
+
+	CreatedBy *int64 `json:"created_by,omitempty"`
+	UpdatedBy *int64 `json:"updated_by,omitempty"`
+
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+type UserAnnouncement struct {
+	ID         int64  `json:"id"`
+	Title      string `json:"title"`
+	Content    string `json:"content"`
+	NotifyMode string `json:"notify_mode"`
+
+	StartsAt *time.Time `json:"starts_at,omitempty"`
+	EndsAt   *time.Time `json:"ends_at,omitempty"`
+
+	ReadAt *time.Time `json:"read_at,omitempty"`
+
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+func AnnouncementFromService(a *service.Announcement) *Announcement {
+	if a == nil {
+		return nil
+	}
+	return &Announcement{
+		ID:         a.ID,
+		Title:      a.Title,
+		Content:    a.Content,
+		Status:     a.Status,
+		NotifyMode: a.NotifyMode,
+		Targeting:  a.Targeting,
+		StartsAt:   a.StartsAt,
+		EndsAt:     a.EndsAt,
+		CreatedBy:  a.CreatedBy,
+		UpdatedBy:  a.UpdatedBy,
+		CreatedAt:  a.CreatedAt,
+		UpdatedAt:  a.UpdatedAt,
+	}
+}
+
+func UserAnnouncementFromService(a *service.UserAnnouncement) *UserAnnouncement {
+	if a == nil {
+		return nil
+	}
+	return &UserAnnouncement{
+		ID:         a.Announcement.ID,
+		Title:      a.Announcement.Title,
+		Content:    a.Announcement.Content,
+		NotifyMode: a.Announcement.NotifyMode,
+		StartsAt:   a.Announcement.StartsAt,
+		EndsAt:     a.Announcement.EndsAt,
+		ReadAt:     a.ReadAt,
+		CreatedAt:  a.Announcement.CreatedAt,
+		UpdatedAt:  a.Announcement.UpdatedAt,
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/dto/api_key_mapper_last_used_test.go

@@ -0,0 +1,40 @@
+package dto
+
+import (
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAPIKeyFromService_MapsLastUsedAt(t *testing.T) {
+	lastUsed := time.Now().UTC().Truncate(time.Second)
+	src := &service.APIKey{
+		ID:         1,
+		UserID:     2,
+		Key:        "sk-map-last-used",
+		Name:       "Mapper",
+		Status:     service.StatusActive,
+		LastUsedAt: &lastUsed,
+	}
+
+	out := APIKeyFromService(src)
+	require.NotNil(t, out)
+	require.NotNil(t, out.LastUsedAt)
+	require.WithinDuration(t, lastUsed, *out.LastUsedAt, time.Second)
+}
+
+func TestAPIKeyFromService_MapsNilLastUsedAt(t *testing.T) {
+	src := &service.APIKey{
+		ID:     1,
+		UserID: 2,
+		Key:    "sk-map-last-used-nil",
+		Name:   "MapperNil",
+		Status: service.StatusActive,
+	}
+
+	out := APIKeyFromService(src)
+	require.NotNil(t, out)
+	require.Nil(t, out.LastUsedAt)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/dto/mappers.go

@@ -0,0 +1,734 @@
+// Package dto provides data transfer objects for HTTP handlers.
+package dto
+
+import (
+	"strconv"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+func UserFromServiceShallow(u *service.User) *User {
+	if u == nil {
+		return nil
+	}
+	return &User{
+		ID:            u.ID,
+		Email:         u.Email,
+		Username:      u.Username,
+		Role:          u.Role,
+		Balance:       u.Balance,
+		Concurrency:   u.Concurrency,
+		Status:        u.Status,
+		AllowedGroups: u.AllowedGroups,
+		CreatedAt:     u.CreatedAt,
+		UpdatedAt:     u.UpdatedAt,
+	}
+}
+
+func UserFromService(u *service.User) *User {
+	if u == nil {
+		return nil
+	}
+	out := UserFromServiceShallow(u)
+	if len(u.APIKeys) > 0 {
+		out.APIKeys = make([]APIKey, 0, len(u.APIKeys))
+		for i := range u.APIKeys {
+			k := u.APIKeys[i]
+			out.APIKeys = append(out.APIKeys, *APIKeyFromService(&k))
+		}
+	}
+	if len(u.Subscriptions) > 0 {
+		out.Subscriptions = make([]UserSubscription, 0, len(u.Subscriptions))
+		for i := range u.Subscriptions {
+			s := u.Subscriptions[i]
+			out.Subscriptions = append(out.Subscriptions, *UserSubscriptionFromService(&s))
+		}
+	}
+	return out
+}
+
+// UserFromServiceAdmin converts a service User to DTO for admin users.
+// It includes notes - user-facing endpoints must not use this.
+func UserFromServiceAdmin(u *service.User) *AdminUser {
+	if u == nil {
+		return nil
+	}
+	base := UserFromService(u)
+	if base == nil {
+		return nil
+	}
+	return &AdminUser{
+		User:                  *base,
+		Notes:                 u.Notes,
+		GroupRates:            u.GroupRates,
+		SoraStorageQuotaBytes: u.SoraStorageQuotaBytes,
+		SoraStorageUsedBytes:  u.SoraStorageUsedBytes,
+	}
+}
+
+func APIKeyFromService(k *service.APIKey) *APIKey {
+	if k == nil {
+		return nil
+	}
+	out := &APIKey{
+		ID:            k.ID,
+		UserID:        k.UserID,
+		Key:           k.Key,
+		Name:          k.Name,
+		GroupID:       k.GroupID,
+		Status:        k.Status,
+		IPWhitelist:   k.IPWhitelist,
+		IPBlacklist:   k.IPBlacklist,
+		LastUsedAt:    k.LastUsedAt,
+		Quota:         k.Quota,
+		QuotaUsed:     k.QuotaUsed,
+		ExpiresAt:     k.ExpiresAt,
+		CreatedAt:     k.CreatedAt,
+		UpdatedAt:     k.UpdatedAt,
+		RateLimit5h:   k.RateLimit5h,
+		RateLimit1d:   k.RateLimit1d,
+		RateLimit7d:   k.RateLimit7d,
+		Usage5h:       k.EffectiveUsage5h(),
+		Usage1d:       k.EffectiveUsage1d(),
+		Usage7d:       k.EffectiveUsage7d(),
+		Window5hStart: k.Window5hStart,
+		Window1dStart: k.Window1dStart,
+		Window7dStart: k.Window7dStart,
+		User:          UserFromServiceShallow(k.User),
+		Group:         GroupFromServiceShallow(k.Group),
+	}
+	if k.Window5hStart != nil && !service.IsWindowExpired(k.Window5hStart, service.RateLimitWindow5h) {
+		t := k.Window5hStart.Add(service.RateLimitWindow5h)
+		out.Reset5hAt = &t
+	}
+	if k.Window1dStart != nil && !service.IsWindowExpired(k.Window1dStart, service.RateLimitWindow1d) {
+		t := k.Window1dStart.Add(service.RateLimitWindow1d)
+		out.Reset1dAt = &t
+	}
+	if k.Window7dStart != nil && !service.IsWindowExpired(k.Window7dStart, service.RateLimitWindow7d) {
+		t := k.Window7dStart.Add(service.RateLimitWindow7d)
+		out.Reset7dAt = &t
+	}
+	return out
+}
+
+func GroupFromServiceShallow(g *service.Group) *Group {
+	if g == nil {
+		return nil
+	}
+	out := groupFromServiceBase(g)
+	return &out
+}
+
+func GroupFromService(g *service.Group) *Group {
+	if g == nil {
+		return nil
+	}
+	return GroupFromServiceShallow(g)
+}
+
+// GroupFromServiceAdmin converts a service Group to DTO for admin users.
+// It includes internal fields like model_routing and account_count.
+func GroupFromServiceAdmin(g *service.Group) *AdminGroup {
+	if g == nil {
+		return nil
+	}
+	out := &AdminGroup{
+		Group:                groupFromServiceBase(g),
+		ModelRouting:         g.ModelRouting,
+		ModelRoutingEnabled:  g.ModelRoutingEnabled,
+		MCPXMLInject:         g.MCPXMLInject,
+		DefaultMappedModel:   g.DefaultMappedModel,
+		SupportedModelScopes: g.SupportedModelScopes,
+		AccountCount:         g.AccountCount,
+		SortOrder:            g.SortOrder,
+	}
+	if len(g.AccountGroups) > 0 {
+		out.AccountGroups = make([]AccountGroup, 0, len(g.AccountGroups))
+		for i := range g.AccountGroups {
+			ag := g.AccountGroups[i]
+			out.AccountGroups = append(out.AccountGroups, *AccountGroupFromService(&ag))
+		}
+	}
+	return out
+}
+
+func groupFromServiceBase(g *service.Group) Group {
+	return Group{
+		ID:                              g.ID,
+		Name:                            g.Name,
+		Description:                     g.Description,
+		Platform:                        g.Platform,
+		RateMultiplier:                  g.RateMultiplier,
+		IsExclusive:                     g.IsExclusive,
+		Status:                          g.Status,
+		SubscriptionType:                g.SubscriptionType,
+		DailyLimitUSD:                   g.DailyLimitUSD,
+		WeeklyLimitUSD:                  g.WeeklyLimitUSD,
+		MonthlyLimitUSD:                 g.MonthlyLimitUSD,
+		ImagePrice1K:                    g.ImagePrice1K,
+		ImagePrice2K:                    g.ImagePrice2K,
+		ImagePrice4K:                    g.ImagePrice4K,
+		SoraImagePrice360:               g.SoraImagePrice360,
+		SoraImagePrice540:               g.SoraImagePrice540,
+		SoraVideoPricePerRequest:        g.SoraVideoPricePerRequest,
+		SoraVideoPricePerRequestHD:      g.SoraVideoPricePerRequestHD,
+		ClaudeCodeOnly:                  g.ClaudeCodeOnly,
+		FallbackGroupID:                 g.FallbackGroupID,
+		FallbackGroupIDOnInvalidRequest: g.FallbackGroupIDOnInvalidRequest,
+		SoraStorageQuotaBytes:           g.SoraStorageQuotaBytes,
+		AllowMessagesDispatch:           g.AllowMessagesDispatch,
+		CreatedAt:                       g.CreatedAt,
+		UpdatedAt:                       g.UpdatedAt,
+	}
+}
+
+func AccountFromServiceShallow(a *service.Account) *Account {
+	if a == nil {
+		return nil
+	}
+	out := &Account{
+		ID:                      a.ID,
+		Name:                    a.Name,
+		Notes:                   a.Notes,
+		Platform:                a.Platform,
+		Type:                    a.Type,
+		Credentials:             a.Credentials,
+		Extra:                   a.Extra,
+		ProxyID:                 a.ProxyID,
+		Concurrency:             a.Concurrency,
+		LoadFactor:              a.LoadFactor,
+		Priority:                a.Priority,
+		RateMultiplier:          a.BillingRateMultiplier(),
+		Status:                  a.Status,
+		ErrorMessage:            a.ErrorMessage,
+		LastUsedAt:              a.LastUsedAt,
+		ExpiresAt:               timeToUnixSeconds(a.ExpiresAt),
+		AutoPauseOnExpired:      a.AutoPauseOnExpired,
+		CreatedAt:               a.CreatedAt,
+		UpdatedAt:               a.UpdatedAt,
+		Schedulable:             a.Schedulable,
+		RateLimitedAt:           a.RateLimitedAt,
+		RateLimitResetAt:        a.RateLimitResetAt,
+		OverloadUntil:           a.OverloadUntil,
+		TempUnschedulableUntil:  a.TempUnschedulableUntil,
+		TempUnschedulableReason: a.TempUnschedulableReason,
+		SessionWindowStart:      a.SessionWindowStart,
+		SessionWindowEnd:        a.SessionWindowEnd,
+		SessionWindowStatus:     a.SessionWindowStatus,
+		GroupIDs:                a.GroupIDs,
+	}
+
+	// 提取 5h 窗口费用控制和会话数量控制配置（仅 Anthropic OAuth/SetupToken 账号有效）
+	if a.IsAnthropicOAuthOrSetupToken() {
+		if limit := a.GetWindowCostLimit(); limit > 0 {
+			out.WindowCostLimit = &limit
+		}
+		if reserve := a.GetWindowCostStickyReserve(); reserve > 0 {
+			out.WindowCostStickyReserve = &reserve
+		}
+		if maxSessions := a.GetMaxSessions(); maxSessions > 0 {
+			out.MaxSessions = &maxSessions
+		}
+		if idleTimeout := a.GetSessionIdleTimeoutMinutes(); idleTimeout > 0 {
+			out.SessionIdleTimeoutMin = &idleTimeout
+		}
+		if rpm := a.GetBaseRPM(); rpm > 0 {
+			out.BaseRPM = &rpm
+			strategy := a.GetRPMStrategy()
+			out.RPMStrategy = &strategy
+			buffer := a.GetRPMStickyBuffer()
+			out.RPMStickyBuffer = &buffer
+		}
+		// 用户消息队列模式
+		if mode := a.GetUserMsgQueueMode(); mode != "" {
+			out.UserMsgQueueMode = &mode
+		}
+		// TLS指纹伪装开关
+		if a.IsTLSFingerprintEnabled() {
+			enabled := true
+			out.EnableTLSFingerprint = &enabled
+		}
+		// 会话ID伪装开关
+		if a.IsSessionIDMaskingEnabled() {
+			enabled := true
+			out.EnableSessionIDMasking = &enabled
+		}
+		// 缓存 TTL 强制替换
+		if a.IsCacheTTLOverrideEnabled() {
+			enabled := true
+			out.CacheTTLOverrideEnabled = &enabled
+			target := a.GetCacheTTLOverrideTarget()
+			out.CacheTTLOverrideTarget = &target
+		}
+	}
+
+	// 提取账号配额限制（apikey / bedrock 类型有效）
+	if a.IsAPIKeyOrBedrock() {
+		if limit := a.GetQuotaLimit(); limit > 0 {
+			out.QuotaLimit = &limit
+			used := a.GetQuotaUsed()
+			out.QuotaUsed = &used
+		}
+		if limit := a.GetQuotaDailyLimit(); limit > 0 {
+			out.QuotaDailyLimit = &limit
+			used := a.GetQuotaDailyUsed()
+			out.QuotaDailyUsed = &used
+		}
+		if limit := a.GetQuotaWeeklyLimit(); limit > 0 {
+			out.QuotaWeeklyLimit = &limit
+			used := a.GetQuotaWeeklyUsed()
+			out.QuotaWeeklyUsed = &used
+		}
+		// 固定时间重置配置
+		if mode := a.GetQuotaDailyResetMode(); mode == "fixed" {
+			out.QuotaDailyResetMode = &mode
+			hour := a.GetQuotaDailyResetHour()
+			out.QuotaDailyResetHour = &hour
+		}
+		if mode := a.GetQuotaWeeklyResetMode(); mode == "fixed" {
+			out.QuotaWeeklyResetMode = &mode
+			day := a.GetQuotaWeeklyResetDay()
+			out.QuotaWeeklyResetDay = &day
+			hour := a.GetQuotaWeeklyResetHour()
+			out.QuotaWeeklyResetHour = &hour
+		}
+		if a.GetQuotaDailyResetMode() == "fixed" || a.GetQuotaWeeklyResetMode() == "fixed" {
+			tz := a.GetQuotaResetTimezone()
+			out.QuotaResetTimezone = &tz
+		}
+		if a.Extra != nil {
+			if v, ok := a.Extra["quota_daily_reset_at"].(string); ok && v != "" {
+				out.QuotaDailyResetAt = &v
+			}
+			if v, ok := a.Extra["quota_weekly_reset_at"].(string); ok && v != "" {
+				out.QuotaWeeklyResetAt = &v
+			}
+		}
+	}
+
+	return out
+}
+
+func AccountFromService(a *service.Account) *Account {
+	if a == nil {
+		return nil
+	}
+	out := AccountFromServiceShallow(a)
+	out.Proxy = ProxyFromService(a.Proxy)
+	if len(a.AccountGroups) > 0 {
+		out.AccountGroups = make([]AccountGroup, 0, len(a.AccountGroups))
+		for i := range a.AccountGroups {
+			ag := a.AccountGroups[i]
+			out.AccountGroups = append(out.AccountGroups, *AccountGroupFromService(&ag))
+		}
+	}
+	if len(a.Groups) > 0 {
+		out.Groups = make([]*Group, 0, len(a.Groups))
+		for _, g := range a.Groups {
+			out.Groups = append(out.Groups, GroupFromServiceShallow(g))
+		}
+	}
+	return out
+}
+
+func timeToUnixSeconds(value *time.Time) *int64 {
+	if value == nil {
+		return nil
+	}
+	ts := value.Unix()
+	return &ts
+}
+
+func AccountGroupFromService(ag *service.AccountGroup) *AccountGroup {
+	if ag == nil {
+		return nil
+	}
+	return &AccountGroup{
+		AccountID: ag.AccountID,
+		GroupID:   ag.GroupID,
+		Priority:  ag.Priority,
+		CreatedAt: ag.CreatedAt,
+		Account:   AccountFromServiceShallow(ag.Account),
+		Group:     GroupFromServiceShallow(ag.Group),
+	}
+}
+
+func ProxyFromService(p *service.Proxy) *Proxy {
+	if p == nil {
+		return nil
+	}
+	return &Proxy{
+		ID:        p.ID,
+		Name:      p.Name,
+		Protocol:  p.Protocol,
+		Host:      p.Host,
+		Port:      p.Port,
+		Username:  p.Username,
+		Status:    p.Status,
+		CreatedAt: p.CreatedAt,
+		UpdatedAt: p.UpdatedAt,
+	}
+}
+
+func ProxyWithAccountCountFromService(p *service.ProxyWithAccountCount) *ProxyWithAccountCount {
+	if p == nil {
+		return nil
+	}
+	return &ProxyWithAccountCount{
+		Proxy:          *ProxyFromService(&p.Proxy),
+		AccountCount:   p.AccountCount,
+		LatencyMs:      p.LatencyMs,
+		LatencyStatus:  p.LatencyStatus,
+		LatencyMessage: p.LatencyMessage,
+		IPAddress:      p.IPAddress,
+		Country:        p.Country,
+		CountryCode:    p.CountryCode,
+		Region:         p.Region,
+		City:           p.City,
+		QualityStatus:  p.QualityStatus,
+		QualityScore:   p.QualityScore,
+		QualityGrade:   p.QualityGrade,
+		QualitySummary: p.QualitySummary,
+		QualityChecked: p.QualityChecked,
+	}
+}
+
+// ProxyFromServiceAdmin converts a service Proxy to AdminProxy DTO for admin users.
+// It includes the password field - user-facing endpoints must not use this.
+func ProxyFromServiceAdmin(p *service.Proxy) *AdminProxy {
+	if p == nil {
+		return nil
+	}
+	base := ProxyFromService(p)
+	if base == nil {
+		return nil
+	}
+	return &AdminProxy{
+		Proxy:    *base,
+		Password: p.Password,
+	}
+}
+
+// ProxyWithAccountCountFromServiceAdmin converts a service ProxyWithAccountCount to AdminProxyWithAccountCount DTO.
+// It includes the password field - user-facing endpoints must not use this.
+func ProxyWithAccountCountFromServiceAdmin(p *service.ProxyWithAccountCount) *AdminProxyWithAccountCount {
+	if p == nil {
+		return nil
+	}
+	admin := ProxyFromServiceAdmin(&p.Proxy)
+	if admin == nil {
+		return nil
+	}
+	return &AdminProxyWithAccountCount{
+		AdminProxy:     *admin,
+		AccountCount:   p.AccountCount,
+		LatencyMs:      p.LatencyMs,
+		LatencyStatus:  p.LatencyStatus,
+		LatencyMessage: p.LatencyMessage,
+		IPAddress:      p.IPAddress,
+		Country:        p.Country,
+		CountryCode:    p.CountryCode,
+		Region:         p.Region,
+		City:           p.City,
+		QualityStatus:  p.QualityStatus,
+		QualityScore:   p.QualityScore,
+		QualityGrade:   p.QualityGrade,
+		QualitySummary: p.QualitySummary,
+		QualityChecked: p.QualityChecked,
+	}
+}
+
+func ProxyAccountSummaryFromService(a *service.ProxyAccountSummary) *ProxyAccountSummary {
+	if a == nil {
+		return nil
+	}
+	return &ProxyAccountSummary{
+		ID:       a.ID,
+		Name:     a.Name,
+		Platform: a.Platform,
+		Type:     a.Type,
+		Notes:    a.Notes,
+	}
+}
+
+func RedeemCodeFromService(rc *service.RedeemCode) *RedeemCode {
+	if rc == nil {
+		return nil
+	}
+	out := redeemCodeFromServiceBase(rc)
+	return &out
+}
+
+// RedeemCodeFromServiceAdmin converts a service RedeemCode to DTO for admin users.
+// It includes notes - user-facing endpoints must not use this.
+func RedeemCodeFromServiceAdmin(rc *service.RedeemCode) *AdminRedeemCode {
+	if rc == nil {
+		return nil
+	}
+	return &AdminRedeemCode{
+		RedeemCode: redeemCodeFromServiceBase(rc),
+		Notes:      rc.Notes,
+	}
+}
+
+func redeemCodeFromServiceBase(rc *service.RedeemCode) RedeemCode {
+	out := RedeemCode{
+		ID:           rc.ID,
+		Code:         rc.Code,
+		Type:         rc.Type,
+		Value:        rc.Value,
+		Status:       rc.Status,
+		UsedBy:       rc.UsedBy,
+		UsedAt:       rc.UsedAt,
+		CreatedAt:    rc.CreatedAt,
+		GroupID:      rc.GroupID,
+		ValidityDays: rc.ValidityDays,
+		User:         UserFromServiceShallow(rc.User),
+		Group:        GroupFromServiceShallow(rc.Group),
+	}
+
+	// For admin_balance/admin_concurrency types, include notes so users can see
+	// why they were charged or credited by admin
+	if (rc.Type == "admin_balance" || rc.Type == "admin_concurrency") && rc.Notes != "" {
+		out.Notes = &rc.Notes
+	}
+
+	return out
+}
+
+// AccountSummaryFromService returns a minimal AccountSummary for usage log display.
+// Only includes ID and Name - no sensitive fields like Credentials, Proxy, etc.
+func AccountSummaryFromService(a *service.Account) *AccountSummary {
+	if a == nil {
+		return nil
+	}
+	return &AccountSummary{
+		ID:   a.ID,
+		Name: a.Name,
+	}
+}
+
+func usageLogFromServiceUser(l *service.UsageLog) UsageLog {
+	// 普通用户 DTO：严禁包含管理员字段（例如 account_rate_multiplier、ip_address、account）。
+	requestType := l.EffectiveRequestType()
+	stream, openAIWSMode := service.ApplyLegacyRequestFields(requestType, l.Stream, l.OpenAIWSMode)
+	return UsageLog{
+		ID:                    l.ID,
+		UserID:                l.UserID,
+		APIKeyID:              l.APIKeyID,
+		AccountID:             l.AccountID,
+		RequestID:             l.RequestID,
+		Model:                 l.Model,
+		ServiceTier:           l.ServiceTier,
+		ReasoningEffort:       l.ReasoningEffort,
+		InboundEndpoint:       l.InboundEndpoint,
+		UpstreamEndpoint:      l.UpstreamEndpoint,
+		GroupID:               l.GroupID,
+		SubscriptionID:        l.SubscriptionID,
+		InputTokens:           l.InputTokens,
+		OutputTokens:          l.OutputTokens,
+		CacheCreationTokens:   l.CacheCreationTokens,
+		CacheReadTokens:       l.CacheReadTokens,
+		CacheCreation5mTokens: l.CacheCreation5mTokens,
+		CacheCreation1hTokens: l.CacheCreation1hTokens,
+		InputCost:             l.InputCost,
+		OutputCost:            l.OutputCost,
+		CacheCreationCost:     l.CacheCreationCost,
+		CacheReadCost:         l.CacheReadCost,
+		TotalCost:             l.TotalCost,
+		ActualCost:            l.ActualCost,
+		RateMultiplier:        l.RateMultiplier,
+		BillingType:           l.BillingType,
+		RequestType:           requestType.String(),
+		Stream:                stream,
+		OpenAIWSMode:          openAIWSMode,
+		DurationMs:            l.DurationMs,
+		FirstTokenMs:          l.FirstTokenMs,
+		ImageCount:            l.ImageCount,
+		ImageSize:             l.ImageSize,
+		MediaType:             l.MediaType,
+		UserAgent:             l.UserAgent,
+		CacheTTLOverridden:    l.CacheTTLOverridden,
+		CreatedAt:             l.CreatedAt,
+		User:                  UserFromServiceShallow(l.User),
+		APIKey:                APIKeyFromService(l.APIKey),
+		Group:                 GroupFromServiceShallow(l.Group),
+		Subscription:          UserSubscriptionFromService(l.Subscription),
+	}
+}
+
+// UsageLogFromService converts a service UsageLog to DTO for regular users.
+// It excludes Account details and IP address - users should not see these.
+func UsageLogFromService(l *service.UsageLog) *UsageLog {
+	if l == nil {
+		return nil
+	}
+	u := usageLogFromServiceUser(l)
+	return &u
+}
+
+// UsageLogFromServiceAdmin converts a service UsageLog to DTO for admin users.
+// It includes minimal Account info (ID, Name only) and IP address.
+func UsageLogFromServiceAdmin(l *service.UsageLog) *AdminUsageLog {
+	if l == nil {
+		return nil
+	}
+	return &AdminUsageLog{
+		UsageLog:              usageLogFromServiceUser(l),
+		AccountRateMultiplier: l.AccountRateMultiplier,
+		IPAddress:             l.IPAddress,
+		Account:               AccountSummaryFromService(l.Account),
+	}
+}
+
+func UsageCleanupTaskFromService(task *service.UsageCleanupTask) *UsageCleanupTask {
+	if task == nil {
+		return nil
+	}
+	return &UsageCleanupTask{
+		ID:     task.ID,
+		Status: task.Status,
+		Filters: UsageCleanupFilters{
+			StartTime:   task.Filters.StartTime,
+			EndTime:     task.Filters.EndTime,
+			UserID:      task.Filters.UserID,
+			APIKeyID:    task.Filters.APIKeyID,
+			AccountID:   task.Filters.AccountID,
+			GroupID:     task.Filters.GroupID,
+			Model:       task.Filters.Model,
+			RequestType: requestTypeStringPtr(task.Filters.RequestType),
+			Stream:      task.Filters.Stream,
+			BillingType: task.Filters.BillingType,
+		},
+		CreatedBy:    task.CreatedBy,
+		DeletedRows:  task.DeletedRows,
+		ErrorMessage: task.ErrorMsg,
+		CanceledBy:   task.CanceledBy,
+		CanceledAt:   task.CanceledAt,
+		StartedAt:    task.StartedAt,
+		FinishedAt:   task.FinishedAt,
+		CreatedAt:    task.CreatedAt,
+		UpdatedAt:    task.UpdatedAt,
+	}
+}
+
+func requestTypeStringPtr(requestType *int16) *string {
+	if requestType == nil {
+		return nil
+	}
+	value := service.RequestTypeFromInt16(*requestType).String()
+	return &value
+}
+
+func SettingFromService(s *service.Setting) *Setting {
+	if s == nil {
+		return nil
+	}
+	return &Setting{
+		ID:        s.ID,
+		Key:       s.Key,
+		Value:     s.Value,
+		UpdatedAt: s.UpdatedAt,
+	}
+}
+
+func UserSubscriptionFromService(sub *service.UserSubscription) *UserSubscription {
+	if sub == nil {
+		return nil
+	}
+	out := userSubscriptionFromServiceBase(sub)
+	return &out
+}
+
+// UserSubscriptionFromServiceAdmin converts a service UserSubscription to DTO for admin users.
+// It includes assignment metadata and notes.
+func UserSubscriptionFromServiceAdmin(sub *service.UserSubscription) *AdminUserSubscription {
+	if sub == nil {
+		return nil
+	}
+	return &AdminUserSubscription{
+		UserSubscription: userSubscriptionFromServiceBase(sub),
+		AssignedBy:       sub.AssignedBy,
+		AssignedAt:       sub.AssignedAt,
+		Notes:            sub.Notes,
+		AssignedByUser:   UserFromServiceShallow(sub.AssignedByUser),
+	}
+}
+
+func userSubscriptionFromServiceBase(sub *service.UserSubscription) UserSubscription {
+	return UserSubscription{
+		ID:                 sub.ID,
+		UserID:             sub.UserID,
+		GroupID:            sub.GroupID,
+		StartsAt:           sub.StartsAt,
+		ExpiresAt:          sub.ExpiresAt,
+		Status:             sub.Status,
+		DailyWindowStart:   sub.DailyWindowStart,
+		WeeklyWindowStart:  sub.WeeklyWindowStart,
+		MonthlyWindowStart: sub.MonthlyWindowStart,
+		DailyUsageUSD:      sub.DailyUsageUSD,
+		WeeklyUsageUSD:     sub.WeeklyUsageUSD,
+		MonthlyUsageUSD:    sub.MonthlyUsageUSD,
+		CreatedAt:          sub.CreatedAt,
+		UpdatedAt:          sub.UpdatedAt,
+		User:               UserFromServiceShallow(sub.User),
+		Group:              GroupFromServiceShallow(sub.Group),
+	}
+}
+
+func BulkAssignResultFromService(r *service.BulkAssignResult) *BulkAssignResult {
+	if r == nil {
+		return nil
+	}
+	subs := make([]AdminUserSubscription, 0, len(r.Subscriptions))
+	for i := range r.Subscriptions {
+		subs = append(subs, *UserSubscriptionFromServiceAdmin(&r.Subscriptions[i]))
+	}
+	statuses := make(map[string]string, len(r.Statuses))
+	for userID, status := range r.Statuses {
+		statuses[strconv.FormatInt(userID, 10)] = status
+	}
+	return &BulkAssignResult{
+		SuccessCount:  r.SuccessCount,
+		CreatedCount:  r.CreatedCount,
+		ReusedCount:   r.ReusedCount,
+		FailedCount:   r.FailedCount,
+		Subscriptions: subs,
+		Errors:        r.Errors,
+		Statuses:      statuses,
+	}
+}
+
+func PromoCodeFromService(pc *service.PromoCode) *PromoCode {
+	if pc == nil {
+		return nil
+	}
+	return &PromoCode{
+		ID:          pc.ID,
+		Code:        pc.Code,
+		BonusAmount: pc.BonusAmount,
+		MaxUses:     pc.MaxUses,
+		UsedCount:   pc.UsedCount,
+		Status:      pc.Status,
+		ExpiresAt:   pc.ExpiresAt,
+		Notes:       pc.Notes,
+		CreatedAt:   pc.CreatedAt,
+		UpdatedAt:   pc.UpdatedAt,
+	}
+}
+
+func PromoCodeUsageFromService(u *service.PromoCodeUsage) *PromoCodeUsage {
+	if u == nil {
+		return nil
+	}
+	return &PromoCodeUsage{
+		ID:          u.ID,
+		PromoCodeID: u.PromoCodeID,
+		UserID:      u.UserID,
+		BonusAmount: u.BonusAmount,
+		UsedAt:      u.UsedAt,
+		User:        UserFromServiceShallow(u.User),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/dto/mappers_usage_test.go

@@ -0,0 +1,111 @@
+package dto
+
+import (
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/require"
+)
+
+func TestUsageLogFromService_IncludesOpenAIWSMode(t *testing.T) {
+	t.Parallel()
+
+	wsLog := &service.UsageLog{
+		RequestID:    "req_1",
+		Model:        "gpt-5.3-codex",
+		OpenAIWSMode: true,
+	}
+	httpLog := &service.UsageLog{
+		RequestID:    "resp_1",
+		Model:        "gpt-5.3-codex",
+		OpenAIWSMode: false,
+	}
+
+	require.True(t, UsageLogFromService(wsLog).OpenAIWSMode)
+	require.False(t, UsageLogFromService(httpLog).OpenAIWSMode)
+	require.True(t, UsageLogFromServiceAdmin(wsLog).OpenAIWSMode)
+	require.False(t, UsageLogFromServiceAdmin(httpLog).OpenAIWSMode)
+}
+
+func TestUsageLogFromService_PrefersRequestTypeForLegacyFields(t *testing.T) {
+	t.Parallel()
+
+	log := &service.UsageLog{
+		RequestID:    "req_2",
+		Model:        "gpt-5.3-codex",
+		RequestType:  service.RequestTypeWSV2,
+		Stream:       false,
+		OpenAIWSMode: false,
+	}
+
+	userDTO := UsageLogFromService(log)
+	adminDTO := UsageLogFromServiceAdmin(log)
+
+	require.Equal(t, "ws_v2", userDTO.RequestType)
+	require.True(t, userDTO.Stream)
+	require.True(t, userDTO.OpenAIWSMode)
+	require.Equal(t, "ws_v2", adminDTO.RequestType)
+	require.True(t, adminDTO.Stream)
+	require.True(t, adminDTO.OpenAIWSMode)
+}
+
+func TestUsageCleanupTaskFromService_RequestTypeMapping(t *testing.T) {
+	t.Parallel()
+
+	requestType := int16(service.RequestTypeStream)
+	task := &service.UsageCleanupTask{
+		ID:     1,
+		Status: service.UsageCleanupStatusPending,
+		Filters: service.UsageCleanupFilters{
+			RequestType: &requestType,
+		},
+	}
+
+	dtoTask := UsageCleanupTaskFromService(task)
+	require.NotNil(t, dtoTask)
+	require.NotNil(t, dtoTask.Filters.RequestType)
+	require.Equal(t, "stream", *dtoTask.Filters.RequestType)
+}
+
+func TestRequestTypeStringPtrNil(t *testing.T) {
+	t.Parallel()
+	require.Nil(t, requestTypeStringPtr(nil))
+}
+
+func TestUsageLogFromService_IncludesServiceTierForUserAndAdmin(t *testing.T) {
+	t.Parallel()
+
+	serviceTier := "priority"
+	inboundEndpoint := "/v1/chat/completions"
+	upstreamEndpoint := "/v1/responses"
+	log := &service.UsageLog{
+		RequestID:             "req_3",
+		Model:                 "gpt-5.4",
+		ServiceTier:           &serviceTier,
+		InboundEndpoint:       &inboundEndpoint,
+		UpstreamEndpoint:      &upstreamEndpoint,
+		AccountRateMultiplier: f64Ptr(1.5),
+	}
+
+	userDTO := UsageLogFromService(log)
+	adminDTO := UsageLogFromServiceAdmin(log)
+
+	require.NotNil(t, userDTO.ServiceTier)
+	require.Equal(t, serviceTier, *userDTO.ServiceTier)
+	require.NotNil(t, userDTO.InboundEndpoint)
+	require.Equal(t, inboundEndpoint, *userDTO.InboundEndpoint)
+	require.NotNil(t, userDTO.UpstreamEndpoint)
+	require.Equal(t, upstreamEndpoint, *userDTO.UpstreamEndpoint)
+	require.NotNil(t, adminDTO.ServiceTier)
+	require.Equal(t, serviceTier, *adminDTO.ServiceTier)
+	require.NotNil(t, adminDTO.InboundEndpoint)
+	require.Equal(t, inboundEndpoint, *adminDTO.InboundEndpoint)
+	require.NotNil(t, adminDTO.UpstreamEndpoint)
+	require.Equal(t, upstreamEndpoint, *adminDTO.UpstreamEndpoint)
+	require.NotNil(t, adminDTO.AccountRateMultiplier)
+	require.InDelta(t, 1.5, *adminDTO.AccountRateMultiplier, 1e-12)
+}
+
+func f64Ptr(value float64) *float64 {
+	return &value
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/dto/settings.go

@@ -0,0 +1,213 @@
+package dto
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// CustomMenuItem represents a user-configured custom menu entry.
+type CustomMenuItem struct {
+	ID         string `json:"id"`
+	Label      string `json:"label"`
+	IconSVG    string `json:"icon_svg"`
+	URL        string `json:"url"`
+	Visibility string `json:"visibility"` // "user" or "admin"
+	SortOrder  int    `json:"sort_order"`
+}
+
+// SystemSettings represents the admin settings API response payload.
+type SystemSettings struct {
+	RegistrationEnabled              bool     `json:"registration_enabled"`
+	EmailVerifyEnabled               bool     `json:"email_verify_enabled"`
+	RegistrationEmailSuffixWhitelist []string `json:"registration_email_suffix_whitelist"`
+	PromoCodeEnabled                 bool     `json:"promo_code_enabled"`
+	PasswordResetEnabled             bool     `json:"password_reset_enabled"`
+	FrontendURL                      string   `json:"frontend_url"`
+	InvitationCodeEnabled            bool     `json:"invitation_code_enabled"`
+	TotpEnabled                      bool     `json:"totp_enabled"`                   // TOTP 双因素认证
+	TotpEncryptionKeyConfigured      bool     `json:"totp_encryption_key_configured"` // TOTP 加密密钥是否已配置
+
+	SMTPHost               string `json:"smtp_host"`
+	SMTPPort               int    `json:"smtp_port"`
+	SMTPUsername           string `json:"smtp_username"`
+	SMTPPasswordConfigured bool   `json:"smtp_password_configured"`
+	SMTPFrom               string `json:"smtp_from_email"`
+	SMTPFromName           string `json:"smtp_from_name"`
+	SMTPUseTLS             bool   `json:"smtp_use_tls"`
+
+	TurnstileEnabled             bool   `json:"turnstile_enabled"`
+	TurnstileSiteKey             string `json:"turnstile_site_key"`
+	TurnstileSecretKeyConfigured bool   `json:"turnstile_secret_key_configured"`
+
+	LinuxDoConnectEnabled                bool   `json:"linuxdo_connect_enabled"`
+	LinuxDoConnectClientID               string `json:"linuxdo_connect_client_id"`
+	LinuxDoConnectClientSecretConfigured bool   `json:"linuxdo_connect_client_secret_configured"`
+	LinuxDoConnectRedirectURL            string `json:"linuxdo_connect_redirect_url"`
+
+	SiteName                    string           `json:"site_name"`
+	SiteLogo                    string           `json:"site_logo"`
+	SiteSubtitle                string           `json:"site_subtitle"`
+	APIBaseURL                  string           `json:"api_base_url"`
+	ContactInfo                 string           `json:"contact_info"`
+	DocURL                      string           `json:"doc_url"`
+	HomeContent                 string           `json:"home_content"`
+	HideCcsImportButton         bool             `json:"hide_ccs_import_button"`
+	PurchaseSubscriptionEnabled bool             `json:"purchase_subscription_enabled"`
+	PurchaseSubscriptionURL     string           `json:"purchase_subscription_url"`
+	SoraClientEnabled           bool             `json:"sora_client_enabled"`
+	CustomMenuItems             []CustomMenuItem `json:"custom_menu_items"`
+
+	DefaultConcurrency   int                          `json:"default_concurrency"`
+	DefaultBalance       float64                      `json:"default_balance"`
+	DefaultSubscriptions []DefaultSubscriptionSetting `json:"default_subscriptions"`
+
+	// Model fallback configuration
+	EnableModelFallback      bool   `json:"enable_model_fallback"`
+	FallbackModelAnthropic   string `json:"fallback_model_anthropic"`
+	FallbackModelOpenAI      string `json:"fallback_model_openai"`
+	FallbackModelGemini      string `json:"fallback_model_gemini"`
+	FallbackModelAntigravity string `json:"fallback_model_antigravity"`
+
+	// Identity patch configuration (Claude -> Gemini)
+	EnableIdentityPatch bool   `json:"enable_identity_patch"`
+	IdentityPatchPrompt string `json:"identity_patch_prompt"`
+
+	// Ops monitoring (vNext)
+	OpsMonitoringEnabled         bool   `json:"ops_monitoring_enabled"`
+	OpsRealtimeMonitoringEnabled bool   `json:"ops_realtime_monitoring_enabled"`
+	OpsQueryModeDefault          string `json:"ops_query_mode_default"`
+	OpsMetricsIntervalSeconds    int    `json:"ops_metrics_interval_seconds"`
+
+	MinClaudeCodeVersion string `json:"min_claude_code_version"`
+
+	// 分组隔离
+	AllowUngroupedKeyScheduling bool `json:"allow_ungrouped_key_scheduling"`
+
+	// Backend Mode
+	BackendModeEnabled bool `json:"backend_mode_enabled"`
+}
+
+type DefaultSubscriptionSetting struct {
+	GroupID      int64 `json:"group_id"`
+	ValidityDays int   `json:"validity_days"`
+}
+
+type PublicSettings struct {
+	RegistrationEnabled              bool             `json:"registration_enabled"`
+	EmailVerifyEnabled               bool             `json:"email_verify_enabled"`
+	RegistrationEmailSuffixWhitelist []string         `json:"registration_email_suffix_whitelist"`
+	PromoCodeEnabled                 bool             `json:"promo_code_enabled"`
+	PasswordResetEnabled             bool             `json:"password_reset_enabled"`
+	InvitationCodeEnabled            bool             `json:"invitation_code_enabled"`
+	TotpEnabled                      bool             `json:"totp_enabled"` // TOTP 双因素认证
+	TurnstileEnabled                 bool             `json:"turnstile_enabled"`
+	TurnstileSiteKey                 string           `json:"turnstile_site_key"`
+	SiteName                         string           `json:"site_name"`
+	SiteLogo                         string           `json:"site_logo"`
+	SiteSubtitle                     string           `json:"site_subtitle"`
+	APIBaseURL                       string           `json:"api_base_url"`
+	ContactInfo                      string           `json:"contact_info"`
+	DocURL                           string           `json:"doc_url"`
+	HomeContent                      string           `json:"home_content"`
+	HideCcsImportButton              bool             `json:"hide_ccs_import_button"`
+	PurchaseSubscriptionEnabled      bool             `json:"purchase_subscription_enabled"`
+	PurchaseSubscriptionURL          string           `json:"purchase_subscription_url"`
+	CustomMenuItems                  []CustomMenuItem `json:"custom_menu_items"`
+	LinuxDoOAuthEnabled              bool             `json:"linuxdo_oauth_enabled"`
+	SoraClientEnabled                bool             `json:"sora_client_enabled"`
+	BackendModeEnabled               bool             `json:"backend_mode_enabled"`
+	Version                          string           `json:"version"`
+}
+
+// SoraS3Settings Sora S3 存储配置 DTO（响应用，不含敏感字段）
+type SoraS3Settings struct {
+	Enabled                   bool   `json:"enabled"`
+	Endpoint                  string `json:"endpoint"`
+	Region                    string `json:"region"`
+	Bucket                    string `json:"bucket"`
+	AccessKeyID               string `json:"access_key_id"`
+	SecretAccessKeyConfigured bool   `json:"secret_access_key_configured"`
+	Prefix                    string `json:"prefix"`
+	ForcePathStyle            bool   `json:"force_path_style"`
+	CDNURL                    string `json:"cdn_url"`
+	DefaultStorageQuotaBytes  int64  `json:"default_storage_quota_bytes"`
+}
+
+// SoraS3Profile Sora S3 存储配置项 DTO（响应用，不含敏感字段）
+type SoraS3Profile struct {
+	ProfileID                 string `json:"profile_id"`
+	Name                      string `json:"name"`
+	IsActive                  bool   `json:"is_active"`
+	Enabled                   bool   `json:"enabled"`
+	Endpoint                  string `json:"endpoint"`
+	Region                    string `json:"region"`
+	Bucket                    string `json:"bucket"`
+	AccessKeyID               string `json:"access_key_id"`
+	SecretAccessKeyConfigured bool   `json:"secret_access_key_configured"`
+	Prefix                    string `json:"prefix"`
+	ForcePathStyle            bool   `json:"force_path_style"`
+	CDNURL                    string `json:"cdn_url"`
+	DefaultStorageQuotaBytes  int64  `json:"default_storage_quota_bytes"`
+	UpdatedAt                 string `json:"updated_at"`
+}
+
+// ListSoraS3ProfilesResponse Sora S3 配置列表响应
+type ListSoraS3ProfilesResponse struct {
+	ActiveProfileID string          `json:"active_profile_id"`
+	Items           []SoraS3Profile `json:"items"`
+}
+
+// StreamTimeoutSettings 流超时处理配置 DTO
+type StreamTimeoutSettings struct {
+	Enabled                bool   `json:"enabled"`
+	Action                 string `json:"action"`
+	TempUnschedMinutes     int    `json:"temp_unsched_minutes"`
+	ThresholdCount         int    `json:"threshold_count"`
+	ThresholdWindowMinutes int    `json:"threshold_window_minutes"`
+}
+
+// RectifierSettings 请求整流器配置 DTO
+type RectifierSettings struct {
+	Enabled                  bool `json:"enabled"`
+	ThinkingSignatureEnabled bool `json:"thinking_signature_enabled"`
+	ThinkingBudgetEnabled    bool `json:"thinking_budget_enabled"`
+}
+
+// BetaPolicyRule Beta 策略规则 DTO
+type BetaPolicyRule struct {
+	BetaToken    string `json:"beta_token"`
+	Action       string `json:"action"`
+	Scope        string `json:"scope"`
+	ErrorMessage string `json:"error_message,omitempty"`
+}
+
+// BetaPolicySettings Beta 策略配置 DTO
+type BetaPolicySettings struct {
+	Rules []BetaPolicyRule `json:"rules"`
+}
+
+// ParseCustomMenuItems parses a JSON string into a slice of CustomMenuItem.
+// Returns empty slice on empty/invalid input.
+func ParseCustomMenuItems(raw string) []CustomMenuItem {
+	raw = strings.TrimSpace(raw)
+	if raw == "" || raw == "[]" {
+		return []CustomMenuItem{}
+	}
+	var items []CustomMenuItem
+	if err := json.Unmarshal([]byte(raw), &items); err != nil {
+		return []CustomMenuItem{}
+	}
+	return items
+}
+
+// ParseUserVisibleMenuItems parses custom menu items and filters out admin-only entries.
+func ParseUserVisibleMenuItems(raw string) []CustomMenuItem {
+	items := ParseCustomMenuItems(raw)
+	filtered := make([]CustomMenuItem, 0, len(items))
+	for _, item := range items {
+		if item.Visibility != "admin" {
+			filtered = append(filtered, item)
+		}
+	}
+	return filtered
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/dto/types.go

@@ -0,0 +1,515 @@
+package dto
+
+import "time"
+
+type User struct {
+	ID            int64     `json:"id"`
+	Email         string    `json:"email"`
+	Username      string    `json:"username"`
+	Role          string    `json:"role"`
+	Balance       float64   `json:"balance"`
+	Concurrency   int       `json:"concurrency"`
+	Status        string    `json:"status"`
+	AllowedGroups []int64   `json:"allowed_groups"`
+	CreatedAt     time.Time `json:"created_at"`
+	UpdatedAt     time.Time `json:"updated_at"`
+
+	APIKeys       []APIKey           `json:"api_keys,omitempty"`
+	Subscriptions []UserSubscription `json:"subscriptions,omitempty"`
+}
+
+// AdminUser 是管理员接口使用的 user DTO（包含敏感/内部字段）。
+// 注意：普通用户接口不得返回 notes 等管理员备注信息。
+type AdminUser struct {
+	User
+
+	Notes string `json:"notes"`
+	// GroupRates 用户专属分组倍率配置
+	// map[groupID]rateMultiplier
+	GroupRates            map[int64]float64 `json:"group_rates,omitempty"`
+	SoraStorageQuotaBytes int64             `json:"sora_storage_quota_bytes"`
+	SoraStorageUsedBytes  int64             `json:"sora_storage_used_bytes"`
+}
+
+type APIKey struct {
+	ID          int64      `json:"id"`
+	UserID      int64      `json:"user_id"`
+	Key         string     `json:"key"`
+	Name        string     `json:"name"`
+	GroupID     *int64     `json:"group_id"`
+	Status      string     `json:"status"`
+	IPWhitelist []string   `json:"ip_whitelist"`
+	IPBlacklist []string   `json:"ip_blacklist"`
+	LastUsedAt  *time.Time `json:"last_used_at"`
+	Quota       float64    `json:"quota"`      // Quota limit in USD (0 = unlimited)
+	QuotaUsed   float64    `json:"quota_used"` // Used quota amount in USD
+	ExpiresAt   *time.Time `json:"expires_at"` // Expiration time (nil = never expires)
+	CreatedAt   time.Time  `json:"created_at"`
+	UpdatedAt   time.Time  `json:"updated_at"`
+
+	// Rate limit fields
+	RateLimit5h   float64    `json:"rate_limit_5h"`
+	RateLimit1d   float64    `json:"rate_limit_1d"`
+	RateLimit7d   float64    `json:"rate_limit_7d"`
+	Usage5h       float64    `json:"usage_5h"`
+	Usage1d       float64    `json:"usage_1d"`
+	Usage7d       float64    `json:"usage_7d"`
+	Window5hStart *time.Time `json:"window_5h_start"`
+	Window1dStart *time.Time `json:"window_1d_start"`
+	Window7dStart *time.Time `json:"window_7d_start"`
+	Reset5hAt     *time.Time `json:"reset_5h_at,omitempty"`
+	Reset1dAt     *time.Time `json:"reset_1d_at,omitempty"`
+	Reset7dAt     *time.Time `json:"reset_7d_at,omitempty"`
+
+	User  *User  `json:"user,omitempty"`
+	Group *Group `json:"group,omitempty"`
+}
+
+type Group struct {
+	ID             int64   `json:"id"`
+	Name           string  `json:"name"`
+	Description    string  `json:"description"`
+	Platform       string  `json:"platform"`
+	RateMultiplier float64 `json:"rate_multiplier"`
+	IsExclusive    bool    `json:"is_exclusive"`
+	Status         string  `json:"status"`
+
+	SubscriptionType string   `json:"subscription_type"`
+	DailyLimitUSD    *float64 `json:"daily_limit_usd"`
+	WeeklyLimitUSD   *float64 `json:"weekly_limit_usd"`
+	MonthlyLimitUSD  *float64 `json:"monthly_limit_usd"`
+
+	// 图片生成计费配置（仅 antigravity 平台使用）
+	ImagePrice1K *float64 `json:"image_price_1k"`
+	ImagePrice2K *float64 `json:"image_price_2k"`
+	ImagePrice4K *float64 `json:"image_price_4k"`
+
+	// Sora 按次计费配置
+	SoraImagePrice360          *float64 `json:"sora_image_price_360"`
+	SoraImagePrice540          *float64 `json:"sora_image_price_540"`
+	SoraVideoPricePerRequest   *float64 `json:"sora_video_price_per_request"`
+	SoraVideoPricePerRequestHD *float64 `json:"sora_video_price_per_request_hd"`
+
+	// Claude Code 客户端限制
+	ClaudeCodeOnly  bool   `json:"claude_code_only"`
+	FallbackGroupID *int64 `json:"fallback_group_id"`
+	// 无效请求兜底分组
+	FallbackGroupIDOnInvalidRequest *int64 `json:"fallback_group_id_on_invalid_request"`
+
+	// Sora 存储配额
+	SoraStorageQuotaBytes int64 `json:"sora_storage_quota_bytes"`
+
+	// OpenAI Messages 调度开关（用户侧需要此字段判断是否展示 Claude Code 教程）
+	AllowMessagesDispatch bool `json:"allow_messages_dispatch"`
+
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+// AdminGroup 是管理员接口使用的 group DTO（包含敏感/内部字段）。
+// 注意：普通用户接口不得返回 model_routing/account_count/account_groups 等内部信息。
+type AdminGroup struct {
+	Group
+
+	// 模型路由配置（仅 anthropic 平台使用）
+	ModelRouting        map[string][]int64 `json:"model_routing"`
+	ModelRoutingEnabled bool               `json:"model_routing_enabled"`
+
+	// MCP XML 协议注入（仅 antigravity 平台使用）
+	MCPXMLInject bool `json:"mcp_xml_inject"`
+
+	// OpenAI Messages 调度配置（仅 openai 平台使用）
+	DefaultMappedModel string `json:"default_mapped_model"`
+
+	// 支持的模型系列（仅 antigravity 平台使用）
+	SupportedModelScopes []string       `json:"supported_model_scopes"`
+	AccountGroups        []AccountGroup `json:"account_groups,omitempty"`
+	AccountCount         int64          `json:"account_count,omitempty"`
+
+	// 分组排序
+	SortOrder int `json:"sort_order"`
+}
+
+type Account struct {
+	ID                 int64          `json:"id"`
+	Name               string         `json:"name"`
+	Notes              *string        `json:"notes"`
+	Platform           string         `json:"platform"`
+	Type               string         `json:"type"`
+	Credentials        map[string]any `json:"credentials"`
+	Extra              map[string]any `json:"extra"`
+	ProxyID            *int64         `json:"proxy_id"`
+	Concurrency        int            `json:"concurrency"`
+	LoadFactor         *int           `json:"load_factor,omitempty"`
+	Priority           int            `json:"priority"`
+	RateMultiplier     float64        `json:"rate_multiplier"`
+	Status             string         `json:"status"`
+	ErrorMessage       string         `json:"error_message"`
+	LastUsedAt         *time.Time     `json:"last_used_at"`
+	ExpiresAt          *int64         `json:"expires_at"`
+	AutoPauseOnExpired bool           `json:"auto_pause_on_expired"`
+	CreatedAt          time.Time      `json:"created_at"`
+	UpdatedAt          time.Time      `json:"updated_at"`
+
+	Schedulable bool `json:"schedulable"`
+
+	RateLimitedAt    *time.Time `json:"rate_limited_at"`
+	RateLimitResetAt *time.Time `json:"rate_limit_reset_at"`
+	OverloadUntil    *time.Time `json:"overload_until"`
+
+	TempUnschedulableUntil  *time.Time `json:"temp_unschedulable_until"`
+	TempUnschedulableReason string     `json:"temp_unschedulable_reason"`
+
+	SessionWindowStart  *time.Time `json:"session_window_start"`
+	SessionWindowEnd    *time.Time `json:"session_window_end"`
+	SessionWindowStatus string     `json:"session_window_status"`
+
+	// 5h窗口费用控制（仅 Anthropic OAuth/SetupToken 账号有效）
+	// 从 extra 字段提取，方便前端显示和编辑
+	WindowCostLimit         *float64 `json:"window_cost_limit,omitempty"`
+	WindowCostStickyReserve *float64 `json:"window_cost_sticky_reserve,omitempty"`
+
+	// 会话数量控制（仅 Anthropic OAuth/SetupToken 账号有效）
+	// 从 extra 字段提取，方便前端显示和编辑
+	MaxSessions           *int `json:"max_sessions,omitempty"`
+	SessionIdleTimeoutMin *int `json:"session_idle_timeout_minutes,omitempty"`
+
+	// RPM 限制（仅 Anthropic OAuth/SetupToken 账号有效）
+	// 从 extra 字段提取，方便前端显示和编辑
+	BaseRPM          *int    `json:"base_rpm,omitempty"`
+	RPMStrategy      *string `json:"rpm_strategy,omitempty"`
+	RPMStickyBuffer  *int    `json:"rpm_sticky_buffer,omitempty"`
+	UserMsgQueueMode *string `json:"user_msg_queue_mode,omitempty"`
+
+	// TLS指纹伪装（仅 Anthropic OAuth/SetupToken 账号有效）
+	// 从 extra 字段提取，方便前端显示和编辑
+	EnableTLSFingerprint *bool `json:"enable_tls_fingerprint,omitempty"`
+
+	// 会话ID伪装（仅 Anthropic OAuth/SetupToken 账号有效）
+	// 启用后将在15分钟内固定 metadata.user_id 中的 session ID
+	// 从 extra 字段提取，方便前端显示和编辑
+	EnableSessionIDMasking *bool `json:"session_id_masking_enabled,omitempty"`
+
+	// 缓存 TTL 强制替换（仅 Anthropic OAuth/SetupToken 账号有效）
+	// 启用后将所有 cache creation tokens 归入指定的 TTL 类型计费
+	CacheTTLOverrideEnabled *bool   `json:"cache_ttl_override_enabled,omitempty"`
+	CacheTTLOverrideTarget  *string `json:"cache_ttl_override_target,omitempty"`
+
+	// API Key 账号配额限制
+	QuotaLimit       *float64 `json:"quota_limit,omitempty"`
+	QuotaUsed        *float64 `json:"quota_used,omitempty"`
+	QuotaDailyLimit  *float64 `json:"quota_daily_limit,omitempty"`
+	QuotaDailyUsed   *float64 `json:"quota_daily_used,omitempty"`
+	QuotaWeeklyLimit *float64 `json:"quota_weekly_limit,omitempty"`
+	QuotaWeeklyUsed  *float64 `json:"quota_weekly_used,omitempty"`
+
+	// 配额固定时间重置配置
+	QuotaDailyResetMode  *string `json:"quota_daily_reset_mode,omitempty"`
+	QuotaDailyResetHour  *int    `json:"quota_daily_reset_hour,omitempty"`
+	QuotaWeeklyResetMode *string `json:"quota_weekly_reset_mode,omitempty"`
+	QuotaWeeklyResetDay  *int    `json:"quota_weekly_reset_day,omitempty"`
+	QuotaWeeklyResetHour *int    `json:"quota_weekly_reset_hour,omitempty"`
+	QuotaResetTimezone   *string `json:"quota_reset_timezone,omitempty"`
+	QuotaDailyResetAt    *string `json:"quota_daily_reset_at,omitempty"`
+	QuotaWeeklyResetAt   *string `json:"quota_weekly_reset_at,omitempty"`
+
+	Proxy         *Proxy         `json:"proxy,omitempty"`
+	AccountGroups []AccountGroup `json:"account_groups,omitempty"`
+
+	GroupIDs []int64  `json:"group_ids,omitempty"`
+	Groups   []*Group `json:"groups,omitempty"`
+}
+
+type AccountGroup struct {
+	AccountID int64     `json:"account_id"`
+	GroupID   int64     `json:"group_id"`
+	Priority  int       `json:"priority"`
+	CreatedAt time.Time `json:"created_at"`
+
+	Account *Account `json:"account,omitempty"`
+	Group   *Group   `json:"group,omitempty"`
+}
+
+type Proxy struct {
+	ID        int64     `json:"id"`
+	Name      string    `json:"name"`
+	Protocol  string    `json:"protocol"`
+	Host      string    `json:"host"`
+	Port      int       `json:"port"`
+	Username  string    `json:"username"`
+	Password  string    `json:"-"`
+	Status    string    `json:"status"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+type ProxyWithAccountCount struct {
+	Proxy
+	AccountCount   int64  `json:"account_count"`
+	LatencyMs      *int64 `json:"latency_ms,omitempty"`
+	LatencyStatus  string `json:"latency_status,omitempty"`
+	LatencyMessage string `json:"latency_message,omitempty"`
+	IPAddress      string `json:"ip_address,omitempty"`
+	Country        string `json:"country,omitempty"`
+	CountryCode    string `json:"country_code,omitempty"`
+	Region         string `json:"region,omitempty"`
+	City           string `json:"city,omitempty"`
+	QualityStatus  string `json:"quality_status,omitempty"`
+	QualityScore   *int   `json:"quality_score,omitempty"`
+	QualityGrade   string `json:"quality_grade,omitempty"`
+	QualitySummary string `json:"quality_summary,omitempty"`
+	QualityChecked *int64 `json:"quality_checked,omitempty"`
+}
+
+// AdminProxy 是管理员接口使用的 proxy DTO（包含密码等敏感字段）。
+// 注意：普通接口不得使用此 DTO。
+type AdminProxy struct {
+	Proxy
+	Password string `json:"password,omitempty"`
+}
+
+// AdminProxyWithAccountCount 是管理员接口使用的带账号统计的 proxy DTO。
+type AdminProxyWithAccountCount struct {
+	AdminProxy
+	AccountCount   int64  `json:"account_count"`
+	LatencyMs      *int64 `json:"latency_ms,omitempty"`
+	LatencyStatus  string `json:"latency_status,omitempty"`
+	LatencyMessage string `json:"latency_message,omitempty"`
+	IPAddress      string `json:"ip_address,omitempty"`
+	Country        string `json:"country,omitempty"`
+	CountryCode    string `json:"country_code,omitempty"`
+	Region         string `json:"region,omitempty"`
+	City           string `json:"city,omitempty"`
+	QualityStatus  string `json:"quality_status,omitempty"`
+	QualityScore   *int   `json:"quality_score,omitempty"`
+	QualityGrade   string `json:"quality_grade,omitempty"`
+	QualitySummary string `json:"quality_summary,omitempty"`
+	QualityChecked *int64 `json:"quality_checked,omitempty"`
+}
+
+type ProxyAccountSummary struct {
+	ID       int64   `json:"id"`
+	Name     string  `json:"name"`
+	Platform string  `json:"platform"`
+	Type     string  `json:"type"`
+	Notes    *string `json:"notes,omitempty"`
+}
+
+type RedeemCode struct {
+	ID        int64      `json:"id"`
+	Code      string     `json:"code"`
+	Type      string     `json:"type"`
+	Value     float64    `json:"value"`
+	Status    string     `json:"status"`
+	UsedBy    *int64     `json:"used_by"`
+	UsedAt    *time.Time `json:"used_at"`
+	CreatedAt time.Time  `json:"created_at"`
+
+	GroupID      *int64 `json:"group_id"`
+	ValidityDays int    `json:"validity_days"`
+
+	// Notes is only populated for admin_balance/admin_concurrency types
+	// so users can see why they were charged or credited
+	Notes *string `json:"notes,omitempty"`
+
+	User  *User  `json:"user,omitempty"`
+	Group *Group `json:"group,omitempty"`
+}
+
+// AdminRedeemCode 是管理员接口使用的 redeem code DTO（包含 notes 等字段）。
+// 注意：普通用户接口不得返回 notes 等内部信息。
+type AdminRedeemCode struct {
+	RedeemCode
+
+	Notes string `json:"notes"`
+}
+
+// UsageLog 是普通用户接口使用的 usage log DTO（不包含管理员字段）。
+type UsageLog struct {
+	ID        int64  `json:"id"`
+	UserID    int64  `json:"user_id"`
+	APIKeyID  int64  `json:"api_key_id"`
+	AccountID int64  `json:"account_id"`
+	RequestID string `json:"request_id"`
+	Model     string `json:"model"`
+	// ServiceTier records the OpenAI service tier used for billing, e.g. "priority" / "flex".
+	ServiceTier *string `json:"service_tier,omitempty"`
+	// ReasoningEffort is the request's reasoning effort level.
+	// OpenAI: "low"/"medium"/"high"/"xhigh"; Claude: "low"/"medium"/"high"/"max".
+	ReasoningEffort *string `json:"reasoning_effort,omitempty"`
+	// InboundEndpoint is the client-facing API endpoint path, e.g. /v1/chat/completions.
+	InboundEndpoint *string `json:"inbound_endpoint,omitempty"`
+	// UpstreamEndpoint is the normalized upstream endpoint path, e.g. /v1/responses.
+	UpstreamEndpoint *string `json:"upstream_endpoint,omitempty"`
+
+	GroupID        *int64 `json:"group_id"`
+	SubscriptionID *int64 `json:"subscription_id"`
+
+	InputTokens         int `json:"input_tokens"`
+	OutputTokens        int `json:"output_tokens"`
+	CacheCreationTokens int `json:"cache_creation_tokens"`
+	CacheReadTokens     int `json:"cache_read_tokens"`
+
+	CacheCreation5mTokens int `json:"cache_creation_5m_tokens"`
+	CacheCreation1hTokens int `json:"cache_creation_1h_tokens"`
+
+	InputCost         float64 `json:"input_cost"`
+	OutputCost        float64 `json:"output_cost"`
+	CacheCreationCost float64 `json:"cache_creation_cost"`
+	CacheReadCost     float64 `json:"cache_read_cost"`
+	TotalCost         float64 `json:"total_cost"`
+	ActualCost        float64 `json:"actual_cost"`
+	RateMultiplier    float64 `json:"rate_multiplier"`
+
+	BillingType  int8   `json:"billing_type"`
+	RequestType  string `json:"request_type"`
+	Stream       bool   `json:"stream"`
+	OpenAIWSMode bool   `json:"openai_ws_mode"`
+	DurationMs   *int   `json:"duration_ms"`
+	FirstTokenMs *int   `json:"first_token_ms"`
+
+	// 图片生成字段
+	ImageCount int     `json:"image_count"`
+	ImageSize  *string `json:"image_size"`
+	MediaType  *string `json:"media_type"`
+
+	// User-Agent
+	UserAgent *string `json:"user_agent"`
+
+	// Cache TTL Override 标记
+	CacheTTLOverridden bool `json:"cache_ttl_overridden"`
+
+	CreatedAt time.Time `json:"created_at"`
+
+	User         *User             `json:"user,omitempty"`
+	APIKey       *APIKey           `json:"api_key,omitempty"`
+	Group        *Group            `json:"group,omitempty"`
+	Subscription *UserSubscription `json:"subscription,omitempty"`
+}
+
+// AdminUsageLog 是管理员接口使用的 usage log DTO（包含管理员字段）。
+type AdminUsageLog struct {
+	UsageLog
+
+	// AccountRateMultiplier 账号计费倍率快照（nil 表示按 1.0 处理）
+	AccountRateMultiplier *float64 `json:"account_rate_multiplier"`
+
+	// IPAddress 用户请求 IP（仅管理员可见）
+	IPAddress *string `json:"ip_address,omitempty"`
+
+	// Account 最小账号信息（避免泄露敏感字段）
+	Account *AccountSummary `json:"account,omitempty"`
+}
+
+type UsageCleanupFilters struct {
+	StartTime   time.Time `json:"start_time"`
+	EndTime     time.Time `json:"end_time"`
+	UserID      *int64    `json:"user_id,omitempty"`
+	APIKeyID    *int64    `json:"api_key_id,omitempty"`
+	AccountID   *int64    `json:"account_id,omitempty"`
+	GroupID     *int64    `json:"group_id,omitempty"`
+	Model       *string   `json:"model,omitempty"`
+	RequestType *string   `json:"request_type,omitempty"`
+	Stream      *bool     `json:"stream,omitempty"`
+	BillingType *int8     `json:"billing_type,omitempty"`
+}
+
+type UsageCleanupTask struct {
+	ID           int64               `json:"id"`
+	Status       string              `json:"status"`
+	Filters      UsageCleanupFilters `json:"filters"`
+	CreatedBy    int64               `json:"created_by"`
+	DeletedRows  int64               `json:"deleted_rows"`
+	ErrorMessage *string             `json:"error_message,omitempty"`
+	CanceledBy   *int64              `json:"canceled_by,omitempty"`
+	CanceledAt   *time.Time          `json:"canceled_at,omitempty"`
+	StartedAt    *time.Time          `json:"started_at,omitempty"`
+	FinishedAt   *time.Time          `json:"finished_at,omitempty"`
+	CreatedAt    time.Time           `json:"created_at"`
+	UpdatedAt    time.Time           `json:"updated_at"`
+}
+
+// AccountSummary is a minimal account info for usage log display.
+// It intentionally excludes sensitive fields like Credentials, Proxy, etc.
+type AccountSummary struct {
+	ID   int64  `json:"id"`
+	Name string `json:"name"`
+}
+
+type Setting struct {
+	ID        int64     `json:"id"`
+	Key       string    `json:"key"`
+	Value     string    `json:"value"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+type UserSubscription struct {
+	ID      int64 `json:"id"`
+	UserID  int64 `json:"user_id"`
+	GroupID int64 `json:"group_id"`
+
+	StartsAt  time.Time `json:"starts_at"`
+	ExpiresAt time.Time `json:"expires_at"`
+	Status    string    `json:"status"`
+
+	DailyWindowStart   *time.Time `json:"daily_window_start"`
+	WeeklyWindowStart  *time.Time `json:"weekly_window_start"`
+	MonthlyWindowStart *time.Time `json:"monthly_window_start"`
+
+	DailyUsageUSD   float64 `json:"daily_usage_usd"`
+	WeeklyUsageUSD  float64 `json:"weekly_usage_usd"`
+	MonthlyUsageUSD float64 `json:"monthly_usage_usd"`
+
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+
+	User  *User  `json:"user,omitempty"`
+	Group *Group `json:"group,omitempty"`
+}
+
+// AdminUserSubscription 是管理员接口使用的订阅 DTO（包含分配信息/备注等字段）。
+// 注意：普通用户接口不得返回 assigned_by/assigned_at/notes/assigned_by_user 等管理员字段。
+type AdminUserSubscription struct {
+	UserSubscription
+
+	AssignedBy *int64    `json:"assigned_by"`
+	AssignedAt time.Time `json:"assigned_at"`
+	Notes      string    `json:"notes"`
+
+	AssignedByUser *User `json:"assigned_by_user,omitempty"`
+}
+
+type BulkAssignResult struct {
+	SuccessCount  int                     `json:"success_count"`
+	CreatedCount  int                     `json:"created_count"`
+	ReusedCount   int                     `json:"reused_count"`
+	FailedCount   int                     `json:"failed_count"`
+	Subscriptions []AdminUserSubscription `json:"subscriptions"`
+	Errors        []string                `json:"errors"`
+	Statuses      map[string]string       `json:"statuses,omitempty"`
+}
+
+// PromoCode 注册优惠码
+type PromoCode struct {
+	ID          int64      `json:"id"`
+	Code        string     `json:"code"`
+	BonusAmount float64    `json:"bonus_amount"`
+	MaxUses     int        `json:"max_uses"`
+	UsedCount   int        `json:"used_count"`
+	Status      string     `json:"status"`
+	ExpiresAt   *time.Time `json:"expires_at"`
+	Notes       string     `json:"notes"`
+	CreatedAt   time.Time  `json:"created_at"`
+	UpdatedAt   time.Time  `json:"updated_at"`
+}
+
+// PromoCodeUsage 优惠码使用记录
+type PromoCodeUsage struct {
+	ID          int64     `json:"id"`
+	PromoCodeID int64     `json:"promo_code_id"`
+	UserID      int64     `json:"user_id"`
+	BonusAmount float64   `json:"bonus_amount"`
+	UsedAt      time.Time `json:"used_at"`
+
+	User *User `json:"user,omitempty"`
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/endpoint.go

@@ -0,0 +1,174 @@
+package handler
+
+import (
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+// ──────────────────────────────────────────────────────────
+// Canonical inbound / upstream endpoint paths.
+// All normalization and derivation reference this single set
+// of constants — add new paths HERE when a new API surface
+// is introduced.
+// ──────────────────────────────────────────────────────────
+
+const (
+	EndpointMessages        = "/v1/messages"
+	EndpointChatCompletions = "/v1/chat/completions"
+	EndpointResponses       = "/v1/responses"
+	EndpointGeminiModels    = "/v1beta/models"
+)
+
+// gin.Context keys used by the middleware and helpers below.
+const (
+	ctxKeyInboundEndpoint = "_gateway_inbound_endpoint"
+)
+
+// ──────────────────────────────────────────────────────────
+// Normalization functions
+// ──────────────────────────────────────────────────────────
+
+// NormalizeInboundEndpoint maps a raw request path (which may carry
+// prefixes like /antigravity, /openai, /sora) to its canonical form.
+//
+//	"/antigravity/v1/messages"   → "/v1/messages"
+//	"/v1/chat/completions"       → "/v1/chat/completions"
+//	"/openai/v1/responses/foo"   → "/v1/responses"
+//	"/v1beta/models/gemini:gen"  → "/v1beta/models"
+func NormalizeInboundEndpoint(path string) string {
+	path = strings.TrimSpace(path)
+	switch {
+	case strings.Contains(path, EndpointChatCompletions):
+		return EndpointChatCompletions
+	case strings.Contains(path, EndpointMessages):
+		return EndpointMessages
+	case strings.Contains(path, EndpointResponses):
+		return EndpointResponses
+	case strings.Contains(path, EndpointGeminiModels):
+		return EndpointGeminiModels
+	default:
+		return path
+	}
+}
+
+// DeriveUpstreamEndpoint determines the upstream endpoint from the
+// account platform and the normalized inbound endpoint.
+//
+// Platform-specific rules:
+//   - OpenAI always forwards to /v1/responses (with optional subpath
+//     such as /v1/responses/compact preserved from the raw URL).
+//   - Anthropic  → /v1/messages
+//   - Gemini     → /v1beta/models
+//   - Sora       → /v1/chat/completions
+//   - Antigravity routes may target either Claude or Gemini, so the
+//     inbound endpoint is used to distinguish.
+func DeriveUpstreamEndpoint(inbound, rawRequestPath, platform string) string {
+	inbound = strings.TrimSpace(inbound)
+
+	switch platform {
+	case service.PlatformOpenAI:
+		// OpenAI forwards everything to the Responses API.
+		// Preserve subresource suffix (e.g. /v1/responses/compact).
+		if suffix := responsesSubpathSuffix(rawRequestPath); suffix != "" {
+			return EndpointResponses + suffix
+		}
+		return EndpointResponses
+
+	case service.PlatformAnthropic:
+		return EndpointMessages
+
+	case service.PlatformGemini:
+		return EndpointGeminiModels
+
+	case service.PlatformSora:
+		return EndpointChatCompletions
+
+	case service.PlatformAntigravity:
+		// Antigravity accounts serve both Claude and Gemini.
+		if inbound == EndpointGeminiModels {
+			return EndpointGeminiModels
+		}
+		return EndpointMessages
+	}
+
+	// Unknown platform — fall back to inbound.
+	return inbound
+}
+
+// responsesSubpathSuffix extracts the part after "/responses" in a raw
+// request path, e.g. "/openai/v1/responses/compact" → "/compact".
+// Returns "" when there is no meaningful suffix.
+func responsesSubpathSuffix(rawPath string) string {
+	trimmed := strings.TrimRight(strings.TrimSpace(rawPath), "/")
+	idx := strings.LastIndex(trimmed, "/responses")
+	if idx < 0 {
+		return ""
+	}
+	suffix := trimmed[idx+len("/responses"):]
+	if suffix == "" || suffix == "/" {
+		return ""
+	}
+	if !strings.HasPrefix(suffix, "/") {
+		return ""
+	}
+	return suffix
+}
+
+// ──────────────────────────────────────────────────────────
+// Middleware
+// ──────────────────────────────────────────────────────────
+
+// InboundEndpointMiddleware normalizes the request path and stores the
+// canonical inbound endpoint in gin.Context so that every handler in
+// the chain can read it via GetInboundEndpoint.
+//
+// Apply this middleware to all gateway route groups.
+func InboundEndpointMiddleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		path := c.FullPath()
+		if path == "" && c.Request != nil && c.Request.URL != nil {
+			path = c.Request.URL.Path
+		}
+		c.Set(ctxKeyInboundEndpoint, NormalizeInboundEndpoint(path))
+		c.Next()
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// Context helpers — used by handlers before building
+// RecordUsageInput / RecordUsageLongContextInput.
+// ──────────────────────────────────────────────────────────
+
+// GetInboundEndpoint returns the canonical inbound endpoint stored by
+// InboundEndpointMiddleware. If the middleware did not run (e.g. in
+// tests), it falls back to normalizing c.FullPath() on the fly.
+func GetInboundEndpoint(c *gin.Context) string {
+	if v, ok := c.Get(ctxKeyInboundEndpoint); ok {
+		if s, ok := v.(string); ok && s != "" {
+			return s
+		}
+	}
+	// Fallback: normalize on the fly.
+	path := ""
+	if c != nil {
+		path = c.FullPath()
+		if path == "" && c.Request != nil && c.Request.URL != nil {
+			path = c.Request.URL.Path
+		}
+	}
+	return NormalizeInboundEndpoint(path)
+}
+
+// GetUpstreamEndpoint derives the upstream endpoint from the context
+// and the account platform. Handlers call this after scheduling an
+// account, passing account.Platform.
+func GetUpstreamEndpoint(c *gin.Context, platform string) string {
+	inbound := GetInboundEndpoint(c)
+	rawPath := ""
+	if c != nil && c.Request != nil && c.Request.URL != nil {
+		rawPath = c.Request.URL.Path
+	}
+	return DeriveUpstreamEndpoint(inbound, rawPath, platform)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/endpoint_test.go

@@ -0,0 +1,159 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func init() { gin.SetMode(gin.TestMode) }
+
+// ──────────────────────────────────────────────────────────
+// NormalizeInboundEndpoint
+// ──────────────────────────────────────────────────────────
+
+func TestNormalizeInboundEndpoint(t *testing.T) {
+	tests := []struct {
+		path string
+		want string
+	}{
+		// Direct canonical paths.
+		{"/v1/messages", EndpointMessages},
+		{"/v1/chat/completions", EndpointChatCompletions},
+		{"/v1/responses", EndpointResponses},
+		{"/v1beta/models", EndpointGeminiModels},
+
+		// Prefixed paths (antigravity, openai, sora).
+		{"/antigravity/v1/messages", EndpointMessages},
+		{"/openai/v1/responses", EndpointResponses},
+		{"/openai/v1/responses/compact", EndpointResponses},
+		{"/sora/v1/chat/completions", EndpointChatCompletions},
+		{"/antigravity/v1beta/models/gemini:generateContent", EndpointGeminiModels},
+
+		// Gin route patterns with wildcards.
+		{"/v1beta/models/*modelAction", EndpointGeminiModels},
+		{"/v1/responses/*subpath", EndpointResponses},
+
+		// Unknown path is returned as-is.
+		{"/v1/embeddings", "/v1/embeddings"},
+		{"", ""},
+		{"  /v1/messages  ", EndpointMessages},
+	}
+	for _, tt := range tests {
+		t.Run(tt.path, func(t *testing.T) {
+			require.Equal(t, tt.want, NormalizeInboundEndpoint(tt.path))
+		})
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// DeriveUpstreamEndpoint
+// ──────────────────────────────────────────────────────────
+
+func TestDeriveUpstreamEndpoint(t *testing.T) {
+	tests := []struct {
+		name     string
+		inbound  string
+		rawPath  string
+		platform string
+		want     string
+	}{
+		// Anthropic.
+		{"anthropic messages", EndpointMessages, "/v1/messages", service.PlatformAnthropic, EndpointMessages},
+
+		// Gemini.
+		{"gemini models", EndpointGeminiModels, "/v1beta/models/gemini:gen", service.PlatformGemini, EndpointGeminiModels},
+
+		// Sora.
+		{"sora completions", EndpointChatCompletions, "/sora/v1/chat/completions", service.PlatformSora, EndpointChatCompletions},
+
+		// OpenAI — always /v1/responses.
+		{"openai responses root", EndpointResponses, "/v1/responses", service.PlatformOpenAI, EndpointResponses},
+		{"openai responses compact", EndpointResponses, "/openai/v1/responses/compact", service.PlatformOpenAI, "/v1/responses/compact"},
+		{"openai responses nested", EndpointResponses, "/openai/v1/responses/compact/detail", service.PlatformOpenAI, "/v1/responses/compact/detail"},
+		{"openai from messages", EndpointMessages, "/v1/messages", service.PlatformOpenAI, EndpointResponses},
+		{"openai from completions", EndpointChatCompletions, "/v1/chat/completions", service.PlatformOpenAI, EndpointResponses},
+
+		// Antigravity — uses inbound to pick Claude vs Gemini upstream.
+		{"antigravity claude", EndpointMessages, "/antigravity/v1/messages", service.PlatformAntigravity, EndpointMessages},
+		{"antigravity gemini", EndpointGeminiModels, "/antigravity/v1beta/models", service.PlatformAntigravity, EndpointGeminiModels},
+
+		// Unknown platform — passthrough.
+		{"unknown platform", "/v1/embeddings", "/v1/embeddings", "unknown", "/v1/embeddings"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			require.Equal(t, tt.want, DeriveUpstreamEndpoint(tt.inbound, tt.rawPath, tt.platform))
+		})
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// responsesSubpathSuffix
+// ──────────────────────────────────────────────────────────
+
+func TestResponsesSubpathSuffix(t *testing.T) {
+	tests := []struct {
+		raw  string
+		want string
+	}{
+		{"/v1/responses", ""},
+		{"/v1/responses/", ""},
+		{"/v1/responses/compact", "/compact"},
+		{"/openai/v1/responses/compact/detail", "/compact/detail"},
+		{"/v1/messages", ""},
+		{"", ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.raw, func(t *testing.T) {
+			require.Equal(t, tt.want, responsesSubpathSuffix(tt.raw))
+		})
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// InboundEndpointMiddleware + context helpers
+// ──────────────────────────────────────────────────────────
+
+func TestInboundEndpointMiddleware(t *testing.T) {
+	router := gin.New()
+	router.Use(InboundEndpointMiddleware())
+
+	var captured string
+	router.POST("/v1/messages", func(c *gin.Context) {
+		captured = GetInboundEndpoint(c)
+		c.Status(http.StatusOK)
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/messages", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, EndpointMessages, captured)
+}
+
+func TestGetInboundEndpoint_FallbackWithoutMiddleware(t *testing.T) {
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/antigravity/v1/messages", nil)
+
+	// Middleware did not run — fallback to normalizing c.Request.URL.Path.
+	got := GetInboundEndpoint(c)
+	require.Equal(t, EndpointMessages, got)
+}
+
+func TestGetUpstreamEndpoint_FullFlow(t *testing.T) {
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/openai/v1/responses/compact", nil)
+
+	// Simulate middleware.
+	c.Set(ctxKeyInboundEndpoint, NormalizeInboundEndpoint(c.Request.URL.Path))
+
+	got := GetUpstreamEndpoint(c, service.PlatformOpenAI)
+	require.Equal(t, "/v1/responses/compact", got)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/failover_loop.go

@@ -0,0 +1,174 @@
+package handler
+
+import (
+	"context"
+	"net/http"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"go.uber.org/zap"
+)
+
+// TempUnscheduler 用于 HandleFailoverError 中同账号重试耗尽后的临时封禁。
+// GatewayService 隐式实现此接口。
+type TempUnscheduler interface {
+	TempUnscheduleRetryableError(ctx context.Context, accountID int64, failoverErr *service.UpstreamFailoverError)
+}
+
+// FailoverAction 表示 failover 错误处理后的下一步动作
+type FailoverAction int
+
+const (
+	// FailoverContinue 继续循环（同账号重试或切换账号，调用方统一 continue）
+	FailoverContinue FailoverAction = iota
+	// FailoverExhausted 切换次数耗尽（调用方应返回错误响应）
+	FailoverExhausted
+	// FailoverCanceled context 已取消（调用方应直接 return）
+	FailoverCanceled
+)
+
+const (
+	// maxSameAccountRetries 同账号重试次数上限（针对 RetryableOnSameAccount 错误）
+	maxSameAccountRetries = 3
+	// sameAccountRetryDelay 同账号重试间隔
+	sameAccountRetryDelay = 500 * time.Millisecond
+	// singleAccountBackoffDelay 单账号分组 503 退避重试固定延时。
+	// Service 层在 SingleAccountRetry 模式下已做充分原地重试（最多 3 次、总等待 30s），
+	// Handler 层只需短暂间隔后重新进入 Service 层即可。
+	singleAccountBackoffDelay = 2 * time.Second
+)
+
+// FailoverState 跨循环迭代共享的 failover 状态
+type FailoverState struct {
+	SwitchCount           int
+	MaxSwitches           int
+	FailedAccountIDs      map[int64]struct{}
+	SameAccountRetryCount map[int64]int
+	LastFailoverErr       *service.UpstreamFailoverError
+	ForceCacheBilling     bool
+	hasBoundSession       bool
+}
+
+// NewFailoverState 创建 failover 状态
+func NewFailoverState(maxSwitches int, hasBoundSession bool) *FailoverState {
+	return &FailoverState{
+		MaxSwitches:           maxSwitches,
+		FailedAccountIDs:      make(map[int64]struct{}),
+		SameAccountRetryCount: make(map[int64]int),
+		hasBoundSession:       hasBoundSession,
+	}
+}
+
+// HandleFailoverError 处理 UpstreamFailoverError，返回下一步动作。
+// 包含：缓存计费判断、同账号重试、临时封禁、切换计数、Antigravity 延时。
+func (s *FailoverState) HandleFailoverError(
+	ctx context.Context,
+	gatewayService TempUnscheduler,
+	accountID int64,
+	platform string,
+	failoverErr *service.UpstreamFailoverError,
+) FailoverAction {
+	s.LastFailoverErr = failoverErr
+
+	// 缓存计费判断
+	if needForceCacheBilling(s.hasBoundSession, failoverErr) {
+		s.ForceCacheBilling = true
+	}
+
+	// 同账号重试：对 RetryableOnSameAccount 的临时性错误，先在同一账号上重试
+	if failoverErr.RetryableOnSameAccount && s.SameAccountRetryCount[accountID] < maxSameAccountRetries {
+		s.SameAccountRetryCount[accountID]++
+		logger.FromContext(ctx).Warn("gateway.failover_same_account_retry",
+			zap.Int64("account_id", accountID),
+			zap.Int("upstream_status", failoverErr.StatusCode),
+			zap.Int("same_account_retry_count", s.SameAccountRetryCount[accountID]),
+			zap.Int("same_account_retry_max", maxSameAccountRetries),
+		)
+		if !sleepWithContext(ctx, sameAccountRetryDelay) {
+			return FailoverCanceled
+		}
+		return FailoverContinue
+	}
+
+	// 同账号重试用尽，执行临时封禁
+	if failoverErr.RetryableOnSameAccount {
+		gatewayService.TempUnscheduleRetryableError(ctx, accountID, failoverErr)
+	}
+
+	// 加入失败列表
+	s.FailedAccountIDs[accountID] = struct{}{}
+
+	// 检查是否耗尽
+	if s.SwitchCount >= s.MaxSwitches {
+		return FailoverExhausted
+	}
+
+	// 递增切换计数
+	s.SwitchCount++
+	logger.FromContext(ctx).Warn("gateway.failover_switch_account",
+		zap.Int64("account_id", accountID),
+		zap.Int("upstream_status", failoverErr.StatusCode),
+		zap.Int("switch_count", s.SwitchCount),
+		zap.Int("max_switches", s.MaxSwitches),
+	)
+
+	// Antigravity 平台换号线性递增延时
+	if platform == service.PlatformAntigravity {
+		delay := time.Duration(s.SwitchCount-1) * time.Second
+		if !sleepWithContext(ctx, delay) {
+			return FailoverCanceled
+		}
+	}
+
+	return FailoverContinue
+}
+
+// HandleSelectionExhausted 处理选号失败（所有候选账号都在排除列表中）时的退避重试决策。
+// 针对 Antigravity 单账号分组的 503 (MODEL_CAPACITY_EXHAUSTED) 场景：
+// 清除排除列表、等待退避后重新选号。
+//
+// 返回 FailoverContinue 时，调用方应设置 SingleAccountRetry context 并 continue。
+// 返回 FailoverExhausted 时，调用方应返回错误响应。
+// 返回 FailoverCanceled 时，调用方应直接 return。
+func (s *FailoverState) HandleSelectionExhausted(ctx context.Context) FailoverAction {
+	if s.LastFailoverErr != nil &&
+		s.LastFailoverErr.StatusCode == http.StatusServiceUnavailable &&
+		s.SwitchCount <= s.MaxSwitches {
+
+		logger.FromContext(ctx).Warn("gateway.failover_single_account_backoff",
+			zap.Duration("backoff_delay", singleAccountBackoffDelay),
+			zap.Int("switch_count", s.SwitchCount),
+			zap.Int("max_switches", s.MaxSwitches),
+		)
+		if !sleepWithContext(ctx, singleAccountBackoffDelay) {
+			return FailoverCanceled
+		}
+		logger.FromContext(ctx).Warn("gateway.failover_single_account_retry",
+			zap.Int("switch_count", s.SwitchCount),
+			zap.Int("max_switches", s.MaxSwitches),
+		)
+		s.FailedAccountIDs = make(map[int64]struct{})
+		return FailoverContinue
+	}
+	return FailoverExhausted
+}
+
+// needForceCacheBilling 判断 failover 时是否需要强制缓存计费。
+// 粘性会话切换账号、或上游明确标记时，将 input_tokens 转为 cache_read 计费。
+func needForceCacheBilling(hasBoundSession bool, failoverErr *service.UpstreamFailoverError) bool {
+	return hasBoundSession || (failoverErr != nil && failoverErr.ForceCacheBilling)
+}
+
+// sleepWithContext 等待指定时长，返回 false 表示 context 已取消。
+func sleepWithContext(ctx context.Context, d time.Duration) bool {
+	if d <= 0 {
+		return true
+	}
+	select {
+	case <-ctx.Done():
+		return false
+	case <-time.After(d):
+		return true
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/failover_loop_test.go

@@ -0,0 +1,729 @@
+package handler
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/stretchr/testify/require"
+)
+
+// ---------------------------------------------------------------------------
+// Mock
+// ---------------------------------------------------------------------------
+
+// mockTempUnscheduler 记录 TempUnscheduleRetryableError 的调用信息。
+type mockTempUnscheduler struct {
+	calls []tempUnscheduleCall
+}
+
+type tempUnscheduleCall struct {
+	accountID   int64
+	failoverErr *service.UpstreamFailoverError
+}
+
+func (m *mockTempUnscheduler) TempUnscheduleRetryableError(_ context.Context, accountID int64, failoverErr *service.UpstreamFailoverError) {
+	m.calls = append(m.calls, tempUnscheduleCall{accountID: accountID, failoverErr: failoverErr})
+}
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+func newTestFailoverErr(statusCode int, retryable, forceBilling bool) *service.UpstreamFailoverError {
+	return &service.UpstreamFailoverError{
+		StatusCode:             statusCode,
+		RetryableOnSameAccount: retryable,
+		ForceCacheBilling:      forceBilling,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// NewFailoverState 测试
+// ---------------------------------------------------------------------------
+
+func TestNewFailoverState(t *testing.T) {
+	t.Run("初始化字段正确", func(t *testing.T) {
+		fs := NewFailoverState(5, true)
+		require.Equal(t, 5, fs.MaxSwitches)
+		require.Equal(t, 0, fs.SwitchCount)
+		require.NotNil(t, fs.FailedAccountIDs)
+		require.Empty(t, fs.FailedAccountIDs)
+		require.NotNil(t, fs.SameAccountRetryCount)
+		require.Empty(t, fs.SameAccountRetryCount)
+		require.Nil(t, fs.LastFailoverErr)
+		require.False(t, fs.ForceCacheBilling)
+		require.True(t, fs.hasBoundSession)
+	})
+
+	t.Run("无绑定会话", func(t *testing.T) {
+		fs := NewFailoverState(3, false)
+		require.Equal(t, 3, fs.MaxSwitches)
+		require.False(t, fs.hasBoundSession)
+	})
+
+	t.Run("零最大切换次数", func(t *testing.T) {
+		fs := NewFailoverState(0, false)
+		require.Equal(t, 0, fs.MaxSwitches)
+	})
+}
+
+// ---------------------------------------------------------------------------
+// sleepWithContext 测试
+// ---------------------------------------------------------------------------
+
+func TestSleepWithContext(t *testing.T) {
+	t.Run("零时长立即返回true", func(t *testing.T) {
+		start := time.Now()
+		ok := sleepWithContext(context.Background(), 0)
+		require.True(t, ok)
+		require.Less(t, time.Since(start), 50*time.Millisecond)
+	})
+
+	t.Run("负时长立即返回true", func(t *testing.T) {
+		start := time.Now()
+		ok := sleepWithContext(context.Background(), -1*time.Second)
+		require.True(t, ok)
+		require.Less(t, time.Since(start), 50*time.Millisecond)
+	})
+
+	t.Run("正常等待后返回true", func(t *testing.T) {
+		start := time.Now()
+		ok := sleepWithContext(context.Background(), 50*time.Millisecond)
+		elapsed := time.Since(start)
+		require.True(t, ok)
+		require.GreaterOrEqual(t, elapsed, 40*time.Millisecond)
+		require.Less(t, elapsed, 500*time.Millisecond)
+	})
+
+	t.Run("已取消context立即返回false", func(t *testing.T) {
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+
+		start := time.Now()
+		ok := sleepWithContext(ctx, 5*time.Second)
+		require.False(t, ok)
+		require.Less(t, time.Since(start), 50*time.Millisecond)
+	})
+
+	t.Run("等待期间context取消返回false", func(t *testing.T) {
+		ctx, cancel := context.WithCancel(context.Background())
+		go func() {
+			time.Sleep(30 * time.Millisecond)
+			cancel()
+		}()
+
+		start := time.Now()
+		ok := sleepWithContext(ctx, 5*time.Second)
+		elapsed := time.Since(start)
+		require.False(t, ok)
+		require.Less(t, elapsed, 500*time.Millisecond)
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — 基本切换流程
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_BasicSwitch(t *testing.T) {
+	t.Run("非重试错误_非Antigravity_直接切换", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(500, false, false)
+
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SwitchCount)
+		require.Contains(t, fs.FailedAccountIDs, int64(100))
+		require.Equal(t, err, fs.LastFailoverErr)
+		require.False(t, fs.ForceCacheBilling)
+		require.Empty(t, mock.calls, "不应调用 TempUnschedule")
+	})
+
+	t.Run("非重试错误_Antigravity_第一次切换无延迟", func(t *testing.T) {
+		// switchCount 从 0→1 时，sleepFailoverDelay(ctx, 1) 的延时 = (1-1)*1s = 0
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(500, false, false)
+
+		start := time.Now()
+		action := fs.HandleFailoverError(context.Background(), mock, 100, service.PlatformAntigravity, err)
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SwitchCount)
+		require.Less(t, elapsed, 200*time.Millisecond, "第一次切换延迟应为 0")
+	})
+
+	t.Run("非重试错误_Antigravity_第二次切换有1秒延迟", func(t *testing.T) {
+		// switchCount 从 1→2 时，sleepFailoverDelay(ctx, 2) 的延时 = (2-1)*1s = 1s
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		fs.SwitchCount = 1 // 模拟已切换一次
+
+		err := newTestFailoverErr(500, false, false)
+		start := time.Now()
+		action := fs.HandleFailoverError(context.Background(), mock, 200, service.PlatformAntigravity, err)
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 2, fs.SwitchCount)
+		require.GreaterOrEqual(t, elapsed, 800*time.Millisecond, "第二次切换延迟应约 1s")
+		require.Less(t, elapsed, 3*time.Second)
+	})
+
+	t.Run("连续切换直到耗尽", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(2, false)
+
+		// 第一次切换：0→1
+		err1 := newTestFailoverErr(500, false, false)
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err1)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SwitchCount)
+
+		// 第二次切换：1→2
+		err2 := newTestFailoverErr(502, false, false)
+		action = fs.HandleFailoverError(context.Background(), mock, 200, "openai", err2)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 2, fs.SwitchCount)
+
+		// 第三次已耗尽：SwitchCount(2) >= MaxSwitches(2)
+		err3 := newTestFailoverErr(503, false, false)
+		action = fs.HandleFailoverError(context.Background(), mock, 300, "openai", err3)
+		require.Equal(t, FailoverExhausted, action)
+		require.Equal(t, 2, fs.SwitchCount, "耗尽时不应继续递增")
+
+		// 验证失败账号列表
+		require.Len(t, fs.FailedAccountIDs, 3)
+		require.Contains(t, fs.FailedAccountIDs, int64(100))
+		require.Contains(t, fs.FailedAccountIDs, int64(200))
+		require.Contains(t, fs.FailedAccountIDs, int64(300))
+
+		// LastFailoverErr 应为最后一次的错误
+		require.Equal(t, err3, fs.LastFailoverErr)
+	})
+
+	t.Run("MaxSwitches为0时首次即耗尽", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(0, false)
+		err := newTestFailoverErr(500, false, false)
+
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.Equal(t, FailoverExhausted, action)
+		require.Equal(t, 0, fs.SwitchCount)
+		require.Contains(t, fs.FailedAccountIDs, int64(100))
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — 缓存计费 (ForceCacheBilling)
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_CacheBilling(t *testing.T) {
+	t.Run("hasBoundSession为true时设置ForceCacheBilling", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, true) // hasBoundSession=true
+		err := newTestFailoverErr(500, false, false)
+
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.True(t, fs.ForceCacheBilling)
+	})
+
+	t.Run("failoverErr.ForceCacheBilling为true时设置", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(500, false, true) // ForceCacheBilling=true
+
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.True(t, fs.ForceCacheBilling)
+	})
+
+	t.Run("两者均为false时不设置", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(500, false, false)
+
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.False(t, fs.ForceCacheBilling)
+	})
+
+	t.Run("一旦设置不会被后续错误重置", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+
+		// 第一次：ForceCacheBilling=true → 设置
+		err1 := newTestFailoverErr(500, false, true)
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", err1)
+		require.True(t, fs.ForceCacheBilling)
+
+		// 第二次：ForceCacheBilling=false → 仍然保持 true
+		err2 := newTestFailoverErr(502, false, false)
+		fs.HandleFailoverError(context.Background(), mock, 200, "openai", err2)
+		require.True(t, fs.ForceCacheBilling, "ForceCacheBilling 一旦设置不应被重置")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — 同账号重试 (RetryableOnSameAccount)
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_SameAccountRetry(t *testing.T) {
+	t.Run("第一次重试返回FailoverContinue", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(400, true, false)
+
+		start := time.Now()
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SameAccountRetryCount[100])
+		require.Equal(t, 0, fs.SwitchCount, "同账号重试不应增加切换计数")
+		require.NotContains(t, fs.FailedAccountIDs, int64(100), "同账号重试不应加入失败列表")
+		require.Empty(t, mock.calls, "同账号重试期间不应调用 TempUnschedule")
+		// 验证等待了 sameAccountRetryDelay (500ms)
+		require.GreaterOrEqual(t, elapsed, 400*time.Millisecond)
+		require.Less(t, elapsed, 2*time.Second)
+	})
+
+	t.Run("达到最大重试次数前均返回FailoverContinue", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(400, true, false)
+
+		for i := 1; i <= maxSameAccountRetries; i++ {
+			action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+			require.Equal(t, FailoverContinue, action)
+			require.Equal(t, i, fs.SameAccountRetryCount[100])
+		}
+
+		require.Empty(t, mock.calls, "达到最大重试次数前均不应调用 TempUnschedule")
+	})
+
+	t.Run("超过最大重试次数后触发TempUnschedule并切换", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(400, true, false)
+
+		for i := 0; i < maxSameAccountRetries; i++ {
+			fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		}
+		require.Equal(t, maxSameAccountRetries, fs.SameAccountRetryCount[100])
+
+		// 第 maxSameAccountRetries+1 次：重试耗尽，应切换账号
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SwitchCount)
+		require.Contains(t, fs.FailedAccountIDs, int64(100))
+
+		// 验证 TempUnschedule 被调用
+		require.Len(t, mock.calls, 1)
+		require.Equal(t, int64(100), mock.calls[0].accountID)
+		require.Equal(t, err, mock.calls[0].failoverErr)
+	})
+
+	t.Run("不同账号独立跟踪重试次数", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(5, false)
+		err := newTestFailoverErr(400, true, false)
+
+		// 账号 100 第一次重试
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SameAccountRetryCount[100])
+
+		// 账号 200 第一次重试（独立计数）
+		action = fs.HandleFailoverError(context.Background(), mock, 200, "openai", err)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SameAccountRetryCount[200])
+		require.Equal(t, 1, fs.SameAccountRetryCount[100], "账号 100 的计数不应受影响")
+	})
+
+	t.Run("重试耗尽后再次遇到同账号_直接切换", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(5, false)
+		err := newTestFailoverErr(400, true, false)
+
+		// 耗尽账号 100 的重试
+		for i := 0; i < maxSameAccountRetries; i++ {
+			fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		}
+		// 第 maxSameAccountRetries+1 次: 重试耗尽 → 切换
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.Equal(t, FailoverContinue, action)
+
+		// 再次遇到账号 100，计数仍为 maxSameAccountRetries，条件不满足 → 直接切换
+		action = fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.Equal(t, FailoverContinue, action)
+		require.Len(t, mock.calls, 2, "第二次耗尽也应调用 TempUnschedule")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — TempUnschedule 调用验证
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_TempUnschedule(t *testing.T) {
+	t.Run("非重试错误不调用TempUnschedule", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(500, false, false) // RetryableOnSameAccount=false
+
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.Empty(t, mock.calls)
+	})
+
+	t.Run("重试错误耗尽后调用TempUnschedule_传入正确参数", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(502, true, false)
+
+		for i := 0; i < maxSameAccountRetries; i++ {
+			fs.HandleFailoverError(context.Background(), mock, 42, "openai", err)
+		}
+		// 再次触发时才会执行 TempUnschedule + 切换
+		fs.HandleFailoverError(context.Background(), mock, 42, "openai", err)
+
+		require.Len(t, mock.calls, 1)
+		require.Equal(t, int64(42), mock.calls[0].accountID)
+		require.Equal(t, 502, mock.calls[0].failoverErr.StatusCode)
+		require.True(t, mock.calls[0].failoverErr.RetryableOnSameAccount)
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — Context 取消
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_ContextCanceled(t *testing.T) {
+	t.Run("同账号重试sleep期间context取消", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(400, true, false)
+
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel() // 立即取消
+
+		start := time.Now()
+		action := fs.HandleFailoverError(ctx, mock, 100, "openai", err)
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverCanceled, action)
+		require.Less(t, elapsed, 100*time.Millisecond, "应立即返回")
+		// 重试计数仍应递增
+		require.Equal(t, 1, fs.SameAccountRetryCount[100])
+	})
+
+	t.Run("Antigravity延迟期间context取消", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		fs.SwitchCount = 1 // 下一次 switchCount=2 → delay = 1s
+		err := newTestFailoverErr(500, false, false)
+
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel() // 立即取消
+
+		start := time.Now()
+		action := fs.HandleFailoverError(ctx, mock, 100, service.PlatformAntigravity, err)
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverCanceled, action)
+		require.Less(t, elapsed, 100*time.Millisecond, "应立即返回而非等待 1s")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — FailedAccountIDs 跟踪
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_FailedAccountIDs(t *testing.T) {
+	t.Run("切换时添加到失败列表", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", newTestFailoverErr(500, false, false))
+		require.Contains(t, fs.FailedAccountIDs, int64(100))
+
+		fs.HandleFailoverError(context.Background(), mock, 200, "openai", newTestFailoverErr(502, false, false))
+		require.Contains(t, fs.FailedAccountIDs, int64(200))
+		require.Len(t, fs.FailedAccountIDs, 2)
+	})
+
+	t.Run("耗尽时也添加到失败列表", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(0, false)
+
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", newTestFailoverErr(500, false, false))
+		require.Equal(t, FailoverExhausted, action)
+		require.Contains(t, fs.FailedAccountIDs, int64(100))
+	})
+
+	t.Run("同账号重试期间不添加到失败列表", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", newTestFailoverErr(400, true, false))
+		require.Equal(t, FailoverContinue, action)
+		require.NotContains(t, fs.FailedAccountIDs, int64(100))
+	})
+
+	t.Run("同一账号多次切换不重复添加", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(5, false)
+
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", newTestFailoverErr(500, false, false))
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", newTestFailoverErr(500, false, false))
+		require.Len(t, fs.FailedAccountIDs, 1, "map 天然去重")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — LastFailoverErr 更新
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_LastFailoverErr(t *testing.T) {
+	t.Run("每次调用都更新LastFailoverErr", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+
+		err1 := newTestFailoverErr(500, false, false)
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", err1)
+		require.Equal(t, err1, fs.LastFailoverErr)
+
+		err2 := newTestFailoverErr(502, false, false)
+		fs.HandleFailoverError(context.Background(), mock, 200, "openai", err2)
+		require.Equal(t, err2, fs.LastFailoverErr)
+	})
+
+	t.Run("同账号重试时也更新LastFailoverErr", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+
+		err := newTestFailoverErr(400, true, false)
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.Equal(t, err, fs.LastFailoverErr)
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — 综合集成场景
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_IntegrationScenario(t *testing.T) {
+	t.Run("模拟完整failover流程_多账号混合重试与切换", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, true) // hasBoundSession=true
+
+		// 1. 账号 100 遇到可重试错误，同账号重试 maxSameAccountRetries 次
+		retryErr := newTestFailoverErr(400, true, false)
+		for i := 0; i < maxSameAccountRetries; i++ {
+			action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", retryErr)
+			require.Equal(t, FailoverContinue, action)
+		}
+		require.True(t, fs.ForceCacheBilling, "hasBoundSession=true 应设置 ForceCacheBilling")
+
+		// 2. 账号 100 超过重试上限 → TempUnschedule + 切换
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", retryErr)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SwitchCount)
+		require.Len(t, mock.calls, 1)
+
+		// 3. 账号 200 遇到不可重试错误 → 直接切换
+		switchErr := newTestFailoverErr(500, false, false)
+		action = fs.HandleFailoverError(context.Background(), mock, 200, "openai", switchErr)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 2, fs.SwitchCount)
+
+		// 4. 账号 300 遇到不可重试错误 → 再切换
+		action = fs.HandleFailoverError(context.Background(), mock, 300, "openai", switchErr)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 3, fs.SwitchCount)
+
+		// 5. 账号 400 → 已耗尽 (SwitchCount=3 >= MaxSwitches=3)
+		action = fs.HandleFailoverError(context.Background(), mock, 400, "openai", switchErr)
+		require.Equal(t, FailoverExhausted, action)
+
+		// 最终状态验证
+		require.Equal(t, 3, fs.SwitchCount, "耗尽时不再递增")
+		require.Len(t, fs.FailedAccountIDs, 4, "4个不同账号都在失败列表中")
+		require.True(t, fs.ForceCacheBilling)
+		require.Len(t, mock.calls, 1, "只有账号 100 触发了 TempUnschedule")
+	})
+
+	t.Run("模拟Antigravity平台完整流程", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(2, false)
+
+		err := newTestFailoverErr(500, false, false)
+
+		// 第一次切换：delay = 0s
+		start := time.Now()
+		action := fs.HandleFailoverError(context.Background(), mock, 100, service.PlatformAntigravity, err)
+		elapsed := time.Since(start)
+		require.Equal(t, FailoverContinue, action)
+		require.Less(t, elapsed, 200*time.Millisecond, "第一次切换延迟为 0")
+
+		// 第二次切换：delay = 1s
+		start = time.Now()
+		action = fs.HandleFailoverError(context.Background(), mock, 200, service.PlatformAntigravity, err)
+		elapsed = time.Since(start)
+		require.Equal(t, FailoverContinue, action)
+		require.GreaterOrEqual(t, elapsed, 800*time.Millisecond, "第二次切换延迟约 1s")
+
+		// 第三次：耗尽（无延迟，因为在检查延迟之前就返回了）
+		start = time.Now()
+		action = fs.HandleFailoverError(context.Background(), mock, 300, service.PlatformAntigravity, err)
+		elapsed = time.Since(start)
+		require.Equal(t, FailoverExhausted, action)
+		require.Less(t, elapsed, 200*time.Millisecond, "耗尽时不应有延迟")
+	})
+
+	t.Run("ForceCacheBilling通过错误标志设置", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false) // hasBoundSession=false
+
+		// 第一次：ForceCacheBilling=false
+		err1 := newTestFailoverErr(500, false, false)
+		fs.HandleFailoverError(context.Background(), mock, 100, "openai", err1)
+		require.False(t, fs.ForceCacheBilling)
+
+		// 第二次：ForceCacheBilling=true（Antigravity 粘性会话切换）
+		err2 := newTestFailoverErr(500, false, true)
+		fs.HandleFailoverError(context.Background(), mock, 200, "openai", err2)
+		require.True(t, fs.ForceCacheBilling, "错误标志应触发 ForceCacheBilling")
+
+		// 第三次：ForceCacheBilling=false，但状态仍保持 true
+		err3 := newTestFailoverErr(500, false, false)
+		fs.HandleFailoverError(context.Background(), mock, 300, "openai", err3)
+		require.True(t, fs.ForceCacheBilling, "不应重置")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleFailoverError — 边界条件
+// ---------------------------------------------------------------------------
+
+func TestHandleFailoverError_EdgeCases(t *testing.T) {
+	t.Run("StatusCode为0的错误也能正常处理", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(0, false, false)
+
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "openai", err)
+		require.Equal(t, FailoverContinue, action)
+	})
+
+	t.Run("AccountID为0也能正常跟踪", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(500, true, false)
+
+		action := fs.HandleFailoverError(context.Background(), mock, 0, "openai", err)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SameAccountRetryCount[0])
+	})
+
+	t.Run("负AccountID也能正常跟踪", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		err := newTestFailoverErr(500, true, false)
+
+		action := fs.HandleFailoverError(context.Background(), mock, -1, "openai", err)
+		require.Equal(t, FailoverContinue, action)
+		require.Equal(t, 1, fs.SameAccountRetryCount[-1])
+	})
+
+	t.Run("空平台名称不触发Antigravity延迟", func(t *testing.T) {
+		mock := &mockTempUnscheduler{}
+		fs := NewFailoverState(3, false)
+		fs.SwitchCount = 1
+		err := newTestFailoverErr(500, false, false)
+
+		start := time.Now()
+		action := fs.HandleFailoverError(context.Background(), mock, 100, "", err)
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverContinue, action)
+		require.Less(t, elapsed, 200*time.Millisecond, "空平台不应触发 Antigravity 延迟")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// HandleSelectionExhausted 测试
+// ---------------------------------------------------------------------------
+
+func TestHandleSelectionExhausted(t *testing.T) {
+	t.Run("无LastFailoverErr时返回Exhausted", func(t *testing.T) {
+		fs := NewFailoverState(3, false)
+		// LastFailoverErr 为 nil
+
+		action := fs.HandleSelectionExhausted(context.Background())
+		require.Equal(t, FailoverExhausted, action)
+	})
+
+	t.Run("非503错误返回Exhausted", func(t *testing.T) {
+		fs := NewFailoverState(3, false)
+		fs.LastFailoverErr = newTestFailoverErr(500, false, false)
+
+		action := fs.HandleSelectionExhausted(context.Background())
+		require.Equal(t, FailoverExhausted, action)
+	})
+
+	t.Run("503且未耗尽_等待后返回Continue并清除失败列表", func(t *testing.T) {
+		fs := NewFailoverState(3, false)
+		fs.LastFailoverErr = newTestFailoverErr(503, false, false)
+		fs.FailedAccountIDs[100] = struct{}{}
+		fs.SwitchCount = 1
+
+		start := time.Now()
+		action := fs.HandleSelectionExhausted(context.Background())
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverContinue, action)
+		require.Empty(t, fs.FailedAccountIDs, "应清除失败账号列表")
+		require.GreaterOrEqual(t, elapsed, 1500*time.Millisecond, "应等待约 2s")
+		require.Less(t, elapsed, 5*time.Second)
+	})
+
+	t.Run("503但SwitchCount已超过MaxSwitches_返回Exhausted", func(t *testing.T) {
+		fs := NewFailoverState(2, false)
+		fs.LastFailoverErr = newTestFailoverErr(503, false, false)
+		fs.SwitchCount = 3 // > MaxSwitches(2)
+
+		start := time.Now()
+		action := fs.HandleSelectionExhausted(context.Background())
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverExhausted, action)
+		require.Less(t, elapsed, 100*time.Millisecond, "不应等待")
+	})
+
+	t.Run("503但context已取消_返回Canceled", func(t *testing.T) {
+		fs := NewFailoverState(3, false)
+		fs.LastFailoverErr = newTestFailoverErr(503, false, false)
+
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+
+		start := time.Now()
+		action := fs.HandleSelectionExhausted(ctx)
+		elapsed := time.Since(start)
+
+		require.Equal(t, FailoverCanceled, action)
+		require.Less(t, elapsed, 100*time.Millisecond, "应立即返回")
+	})
+
+	t.Run("503且SwitchCount等于MaxSwitches_仍可重试", func(t *testing.T) {
+		fs := NewFailoverState(2, false)
+		fs.LastFailoverErr = newTestFailoverErr(503, false, false)
+		fs.SwitchCount = 2 // == MaxSwitches，条件是 <=，仍可重试
+
+		action := fs.HandleSelectionExhausted(context.Background())
+		require.Equal(t, FailoverContinue, action)
+	})
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_handler_error_fallback_test.go

@@ -0,0 +1,49 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGatewayEnsureForwardErrorResponse_WritesFallbackWhenNotWritten(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+
+	h := &GatewayHandler{}
+	wrote := h.ensureForwardErrorResponse(c, false)
+
+	require.True(t, wrote)
+	require.Equal(t, http.StatusBadGateway, w.Code)
+
+	var parsed map[string]any
+	err := json.Unmarshal(w.Body.Bytes(), &parsed)
+	require.NoError(t, err)
+	assert.Equal(t, "error", parsed["type"])
+	errorObj, ok := parsed["error"].(map[string]any)
+	require.True(t, ok)
+	assert.Equal(t, "upstream_error", errorObj["type"])
+	assert.Equal(t, "Upstream request failed", errorObj["message"])
+}
+
+func TestGatewayEnsureForwardErrorResponse_DoesNotOverrideWrittenResponse(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+	c.String(http.StatusTeapot, "already written")
+
+	h := &GatewayHandler{}
+	wrote := h.ensureForwardErrorResponse(c, false)
+
+	require.False(t, wrote)
+	require.Equal(t, http.StatusTeapot, w.Code)
+	assert.Equal(t, "already written", w.Body.String())
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_handler_intercept_test.go

@@ -0,0 +1,65 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDetectInterceptType_MaxTokensOneHaikuRequiresClaudeCodeClient(t *testing.T) {
+	body := []byte(`{"messages":[{"role":"user","content":[{"type":"text","text":"hello"}]}]}`)
+
+	notClaudeCode := detectInterceptType(body, "claude-haiku-4-5", 1, false, false)
+	require.Equal(t, InterceptTypeNone, notClaudeCode)
+
+	isClaudeCode := detectInterceptType(body, "claude-haiku-4-5", 1, false, true)
+	require.Equal(t, InterceptTypeMaxTokensOneHaiku, isClaudeCode)
+}
+
+func TestDetectInterceptType_SuggestionModeUnaffected(t *testing.T) {
+	body := []byte(`{
+		"messages":[{
+			"role":"user",
+			"content":[{"type":"text","text":"[SUGGESTION MODE:foo]"}]
+		}],
+		"system":[]
+	}`)
+
+	got := detectInterceptType(body, "claude-sonnet-4-5", 256, false, false)
+	require.Equal(t, InterceptTypeSuggestionMode, got)
+}
+
+func TestSendMockInterceptResponse_MaxTokensOneHaiku(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	rec := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(rec)
+
+	sendMockInterceptResponse(ctx, "claude-haiku-4-5", InterceptTypeMaxTokensOneHaiku)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var response map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &response))
+	require.Equal(t, "max_tokens", response["stop_reason"])
+
+	id, ok := response["id"].(string)
+	require.True(t, ok)
+	require.True(t, strings.HasPrefix(id, "msg_bdrk_"))
+
+	content, ok := response["content"].([]any)
+	require.True(t, ok)
+	require.NotEmpty(t, content)
+
+	firstBlock, ok := content[0].(map[string]any)
+	require.True(t, ok)
+	require.Equal(t, "#", firstBlock["text"])
+
+	usage, ok := response["usage"].(map[string]any)
+	require.True(t, ok)
+	require.Equal(t, float64(1), usage["output_tokens"])
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_handler_stream_failover_test.go

@@ -0,0 +1,122 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// partialMessageStartSSE 模拟 handleStreamingResponse 已写入的首批 SSE 事件。
+const partialMessageStartSSE = "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_01\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"model\":\"claude-sonnet-4-5\",\"stop_reason\":null,\"stop_sequence\":null,\"usage\":{\"input_tokens\":10,\"output_tokens\":1}}}\n\n" +
+	"event: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n"
+
+// TestStreamWrittenGuard_MessagesPath_AbortFailoverOnSSEContentWritten 验证：
+// 当 Forward 在返回 UpstreamFailoverError 前已向客户端写入 SSE 内容时，
+// 故障转移保护逻辑必须终止循环并发送 SSE 错误事件，而不是进行下一次 Forward。
+// 具体验证：
+//  1. c.Writer.Size() 检测条件正确触发（字节数已增加）
+//  2. handleFailoverExhausted 以 streamStarted=true 调用后，响应体以 SSE 错误事件结尾
+//  3. 响应体中只出现一个 message_start，不存在第二个（防止流拼接腐化）
+func TestStreamWrittenGuard_MessagesPath_AbortFailoverOnSSEContentWritten(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/messages", nil)
+
+	// 步骤 1：记录 Forward 前的 writer size（模拟 writerSizeBeforeForward := c.Writer.Size()）
+	sizeBeforeForward := c.Writer.Size()
+	require.Equal(t, -1, sizeBeforeForward, "gin writer 初始 Size 应为 -1（未写入任何字节）")
+
+	// 步骤 2：模拟 Forward 已向客户端写入部分 SSE 内容（message_start + content_block_start）
+	_, err := c.Writer.Write([]byte(partialMessageStartSSE))
+	require.NoError(t, err)
+
+	// 步骤 3：验证守卫条件成立（c.Writer.Size() != sizeBeforeForward）
+	require.NotEqual(t, sizeBeforeForward, c.Writer.Size(),
+		"写入 SSE 内容后 writer size 必须增加，守卫条件应为 true")
+
+	// 步骤 4：模拟 UpstreamFailoverError（上游在流中途返回 403）
+	failoverErr := &service.UpstreamFailoverError{
+		StatusCode:   http.StatusForbidden,
+		ResponseBody: []byte(`{"error":{"type":"permission_error","message":"forbidden"}}`),
+	}
+
+	// 步骤 5：守卫触发 → 调用 handleFailoverExhausted，streamStarted=true
+	h := &GatewayHandler{}
+	h.handleFailoverExhausted(c, failoverErr, service.PlatformAnthropic, true)
+
+	body := w.Body.String()
+
+	// 断言 A：响应体中包含最初写入的 message_start SSE 事件行
+	require.Contains(t, body, "event: message_start", "响应体应包含已写入的 message_start SSE 事件")
+
+	// 断言 B：响应体以 SSE 错误事件结尾（data: {"type":"error",...}\n\n）
+	require.True(t, strings.HasSuffix(strings.TrimRight(body, "\n"), "}"),
+		"响应体应以 JSON 对象结尾（SSE error event 的 data 字段）")
+	require.Contains(t, body, `"type":"error"`, "响应体末尾必须包含 SSE 错误事件")
+
+	// 断言 C：SSE event 行 "event: message_start" 只出现一次（防止双 message_start 拼接腐化）
+	firstIdx := strings.Index(body, "event: message_start")
+	lastIdx := strings.LastIndex(body, "event: message_start")
+	assert.Equal(t, firstIdx, lastIdx,
+		"响应体中 'event: message_start' 必须只出现一次，不得因 failover 拼接导致两次")
+}
+
+// TestStreamWrittenGuard_GeminiPath_AbortFailoverOnSSEContentWritten 与上述测试相同，
+// 验证 Gemini 路径使用 service.PlatformGemini（而非 account.Platform）时行为一致。
+func TestStreamWrittenGuard_GeminiPath_AbortFailoverOnSSEContentWritten(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1beta/models/gemini-2.0-flash:streamGenerateContent", nil)
+
+	sizeBeforeForward := c.Writer.Size()
+
+	_, err := c.Writer.Write([]byte(partialMessageStartSSE))
+	require.NoError(t, err)
+
+	require.NotEqual(t, sizeBeforeForward, c.Writer.Size())
+
+	failoverErr := &service.UpstreamFailoverError{
+		StatusCode: http.StatusForbidden,
+	}
+
+	h := &GatewayHandler{}
+	h.handleFailoverExhausted(c, failoverErr, service.PlatformGemini, true)
+
+	body := w.Body.String()
+
+	require.Contains(t, body, "event: message_start")
+	require.Contains(t, body, `"type":"error"`)
+
+	firstIdx := strings.Index(body, "event: message_start")
+	lastIdx := strings.LastIndex(body, "event: message_start")
+	assert.Equal(t, firstIdx, lastIdx, "Gemini 路径不得出现双 message_start")
+}
+
+// TestStreamWrittenGuard_NoByteWritten_GuardNotTriggered 验证反向场景：
+// 当 Forward 返回 UpstreamFailoverError 时若未向客户端写入任何 SSE 内容，
+// 守卫条件（c.Writer.Size() != sizeBeforeForward）为 false，不应中止 failover。
+func TestStreamWrittenGuard_NoByteWritten_GuardNotTriggered(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/messages", nil)
+
+	// 模拟 writerSizeBeforeForward：初始为 -1
+	sizeBeforeForward := c.Writer.Size()
+
+	// Forward 未写入任何字节直接返回错误（例如 401 发生在连接建立前）
+	// c.Writer.Size() 仍为 -1
+
+	// 守卫条件：sizeBeforeForward == c.Writer.Size() → 不触发
+	guardTriggered := c.Writer.Size() != sizeBeforeForward
+	require.False(t, guardTriggered,
+		"未写入任何字节时，守卫条件必须为 false，应允许正常 failover 继续")
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_handler_warmup_intercept_unit_test.go

@@ -0,0 +1,351 @@
+//go:build unit
+
+package handler
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ctxkey"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	middleware "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+// 目标：严格验证“antigravity 账号通过 /v1/messages 提供 Claude 服务时”，
+// 当账号 credentials.intercept_warmup_requests=true 且请求为 Warmup 时，
+// 后端会在转发上游前直接拦截并返回 mock 响应（不依赖上游）。
+
+type fakeSchedulerCache struct {
+	accounts []*service.Account
+}
+
+func (f *fakeSchedulerCache) GetSnapshot(_ context.Context, _ service.SchedulerBucket) ([]*service.Account, bool, error) {
+	return f.accounts, true, nil
+}
+func (f *fakeSchedulerCache) SetSnapshot(_ context.Context, _ service.SchedulerBucket, _ []service.Account) error {
+	return nil
+}
+func (f *fakeSchedulerCache) GetAccount(_ context.Context, _ int64) (*service.Account, error) {
+	return nil, nil
+}
+func (f *fakeSchedulerCache) SetAccount(_ context.Context, _ *service.Account) error { return nil }
+func (f *fakeSchedulerCache) DeleteAccount(_ context.Context, _ int64) error         { return nil }
+func (f *fakeSchedulerCache) UpdateLastUsed(_ context.Context, _ map[int64]time.Time) error {
+	return nil
+}
+func (f *fakeSchedulerCache) TryLockBucket(_ context.Context, _ service.SchedulerBucket, _ time.Duration) (bool, error) {
+	return true, nil
+}
+func (f *fakeSchedulerCache) ListBuckets(_ context.Context) ([]service.SchedulerBucket, error) {
+	return nil, nil
+}
+func (f *fakeSchedulerCache) GetOutboxWatermark(_ context.Context) (int64, error) { return 0, nil }
+func (f *fakeSchedulerCache) SetOutboxWatermark(_ context.Context, _ int64) error { return nil }
+
+type fakeGroupRepo struct {
+	group *service.Group
+}
+
+func (f *fakeGroupRepo) Create(context.Context, *service.Group) error { return nil }
+func (f *fakeGroupRepo) GetByID(context.Context, int64) (*service.Group, error) {
+	return f.group, nil
+}
+func (f *fakeGroupRepo) GetByIDLite(context.Context, int64) (*service.Group, error) {
+	return f.group, nil
+}
+func (f *fakeGroupRepo) Update(context.Context, *service.Group) error          { return nil }
+func (f *fakeGroupRepo) Delete(context.Context, int64) error                   { return nil }
+func (f *fakeGroupRepo) DeleteCascade(context.Context, int64) ([]int64, error) { return nil, nil }
+func (f *fakeGroupRepo) List(context.Context, pagination.PaginationParams) ([]service.Group, *pagination.PaginationResult, error) {
+	return nil, nil, nil
+}
+func (f *fakeGroupRepo) ListWithFilters(context.Context, pagination.PaginationParams, string, string, string, *bool) ([]service.Group, *pagination.PaginationResult, error) {
+	return nil, nil, nil
+}
+func (f *fakeGroupRepo) ListActive(context.Context) ([]service.Group, error) { return nil, nil }
+func (f *fakeGroupRepo) ListActiveByPlatform(context.Context, string) ([]service.Group, error) {
+	return nil, nil
+}
+func (f *fakeGroupRepo) ExistsByName(context.Context, string) (bool, error)    { return false, nil }
+func (f *fakeGroupRepo) GetAccountCount(context.Context, int64) (int64, error) { return 0, nil }
+func (f *fakeGroupRepo) DeleteAccountGroupsByGroupID(context.Context, int64) (int64, error) {
+	return 0, nil
+}
+func (f *fakeGroupRepo) GetAccountIDsByGroupIDs(context.Context, []int64) ([]int64, error) {
+	return nil, nil
+}
+func (f *fakeGroupRepo) BindAccountsToGroup(context.Context, int64, []int64) error { return nil }
+func (f *fakeGroupRepo) UpdateSortOrders(context.Context, []service.GroupSortOrderUpdate) error {
+	return nil
+}
+
+type fakeConcurrencyCache struct{}
+
+func (f *fakeConcurrencyCache) AcquireAccountSlot(context.Context, int64, int, string) (bool, error) {
+	return true, nil
+}
+func (f *fakeConcurrencyCache) ReleaseAccountSlot(context.Context, int64, string) error { return nil }
+func (f *fakeConcurrencyCache) GetAccountConcurrency(context.Context, int64) (int, error) {
+	return 0, nil
+}
+func (f *fakeConcurrencyCache) IncrementAccountWaitCount(context.Context, int64, int) (bool, error) {
+	return true, nil
+}
+func (f *fakeConcurrencyCache) DecrementAccountWaitCount(context.Context, int64) error { return nil }
+func (f *fakeConcurrencyCache) GetAccountWaitingCount(context.Context, int64) (int, error) {
+	return 0, nil
+}
+func (f *fakeConcurrencyCache) AcquireUserSlot(context.Context, int64, int, string) (bool, error) {
+	return true, nil
+}
+func (f *fakeConcurrencyCache) ReleaseUserSlot(context.Context, int64, string) error   { return nil }
+func (f *fakeConcurrencyCache) GetUserConcurrency(context.Context, int64) (int, error) { return 0, nil }
+func (f *fakeConcurrencyCache) IncrementWaitCount(context.Context, int64, int) (bool, error) {
+	return true, nil
+}
+func (f *fakeConcurrencyCache) DecrementWaitCount(context.Context, int64) error { return nil }
+func (f *fakeConcurrencyCache) GetAccountsLoadBatch(context.Context, []service.AccountWithConcurrency) (map[int64]*service.AccountLoadInfo, error) {
+	return map[int64]*service.AccountLoadInfo{}, nil
+}
+func (f *fakeConcurrencyCache) GetUsersLoadBatch(context.Context, []service.UserWithConcurrency) (map[int64]*service.UserLoadInfo, error) {
+	return map[int64]*service.UserLoadInfo{}, nil
+}
+func (f *fakeConcurrencyCache) GetAccountConcurrencyBatch(_ context.Context, accountIDs []int64) (map[int64]int, error) {
+	result := make(map[int64]int, len(accountIDs))
+	for _, id := range accountIDs {
+		result[id] = 0
+	}
+	return result, nil
+}
+func (f *fakeConcurrencyCache) CleanupExpiredAccountSlots(context.Context, int64) error { return nil }
+func (f *fakeConcurrencyCache) CleanupStaleProcessSlots(context.Context, string) error  { return nil }
+
+func newTestGatewayHandler(t *testing.T, group *service.Group, accounts []*service.Account) (*GatewayHandler, func()) {
+	t.Helper()
+
+	schedulerCache := &fakeSchedulerCache{accounts: accounts}
+	schedulerSnapshot := service.NewSchedulerSnapshotService(schedulerCache, nil, nil, nil, nil)
+
+	gwSvc := service.NewGatewayService(
+		nil, // accountRepo (not used: scheduler snapshot hit)
+		&fakeGroupRepo{group: group},
+		nil, // usageLogRepo
+		nil, // usageBillingRepo
+		nil, // userRepo
+		nil, // userSubRepo
+		nil, // userGroupRateRepo
+		nil, // cache (disable sticky)
+		nil, // cfg
+		schedulerSnapshot,
+		nil, // concurrencyService (disable load-aware; tryAcquire always acquired)
+		nil, // billingService
+		nil, // rateLimitService
+		nil, // billingCacheService
+		nil, // identityService
+		nil, // httpUpstream
+		nil, // deferredService
+		nil, // claudeTokenProvider
+		nil, // sessionLimitCache
+		nil, // rpmCache
+		nil, // digestStore
+		nil, // settingService
+	)
+
+	// RunModeSimple：跳过计费检查，避免引入 repo/cache 依赖。
+	cfg := &config.Config{RunMode: config.RunModeSimple}
+	billingCacheSvc := service.NewBillingCacheService(nil, nil, nil, nil, cfg)
+
+	concurrencySvc := service.NewConcurrencyService(&fakeConcurrencyCache{})
+	concurrencyHelper := NewConcurrencyHelper(concurrencySvc, SSEPingFormatClaude, 0)
+
+	h := &GatewayHandler{
+		gatewayService:      gwSvc,
+		billingCacheService: billingCacheSvc,
+		concurrencyHelper:   concurrencyHelper,
+		// 这些字段对本测试不敏感，保持较小即可
+		maxAccountSwitches:       1,
+		maxAccountSwitchesGemini: 1,
+	}
+
+	cleanup := func() {
+		billingCacheSvc.Stop()
+	}
+	return h, cleanup
+}
+
+func TestGatewayHandlerMessages_InterceptWarmup_AntigravityAccount_MixedSchedulingV1(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	groupID := int64(2001)
+	accountID := int64(1001)
+
+	group := &service.Group{
+		ID:       groupID,
+		Hydrated: true,
+		Platform: service.PlatformAnthropic, // /v1/messages（Claude兼容）入口
+		Status:   service.StatusActive,
+	}
+
+	account := &service.Account{
+		ID:       accountID,
+		Name:     "ag-1",
+		Platform: service.PlatformAntigravity,
+		Type:     service.AccountTypeOAuth,
+		Credentials: map[string]any{
+			"access_token":              "tok_xxx",
+			"intercept_warmup_requests": true,
+		},
+		Extra: map[string]any{
+			"mixed_scheduling": true, // 关键：允许被 anthropic 分组混合调度选中
+		},
+		Concurrency:   1,
+		Priority:      1,
+		Status:        service.StatusActive,
+		Schedulable:   true,
+		AccountGroups: []service.AccountGroup{{AccountID: accountID, GroupID: groupID}},
+	}
+
+	h, cleanup := newTestGatewayHandler(t, group, []*service.Account{account})
+	defer cleanup()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+
+	body := []byte(`{
+		"model": "claude-sonnet-4-5",
+		"max_tokens": 256,
+		"messages": [{"role":"user","content":[{"type":"text","text":"Warmup"}]}]
+	}`)
+	req := httptest.NewRequest("POST", "/v1/messages", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req = req.WithContext(context.WithValue(req.Context(), ctxkey.Group, group))
+	c.Request = req
+
+	apiKey := &service.APIKey{
+		ID:      3001,
+		UserID:  4001,
+		GroupID: &groupID,
+		Status:  service.StatusActive,
+		User: &service.User{
+			ID:          4001,
+			Concurrency: 10,
+			Balance:     100,
+		},
+		Group: group,
+	}
+
+	c.Set(string(middleware.ContextKeyAPIKey), apiKey)
+	c.Set(string(middleware.ContextKeyUser), middleware.AuthSubject{UserID: apiKey.UserID, Concurrency: 10})
+
+	h.Messages(c)
+
+	require.Equal(t, 200, rec.Code)
+
+	// 断言：确实选中了 antigravity 账号（不是纯函数测试，而是从 Handler 里验证调度结果）
+	selected, ok := c.Get(opsAccountIDKey)
+	require.True(t, ok)
+	require.Equal(t, accountID, selected)
+
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, "msg_mock_warmup", resp["id"])
+	require.Equal(t, "claude-sonnet-4-5", resp["model"])
+
+	content, ok := resp["content"].([]any)
+	require.True(t, ok)
+	require.Len(t, content, 1)
+	first, ok := content[0].(map[string]any)
+	require.True(t, ok)
+	require.Equal(t, "New Conversation", first["text"])
+}
+
+func TestGatewayHandlerMessages_InterceptWarmup_AntigravityAccount_ForcePlatform(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	groupID := int64(2002)
+	accountID := int64(1002)
+
+	group := &service.Group{
+		ID:       groupID,
+		Hydrated: true,
+		Platform: service.PlatformAntigravity,
+		Status:   service.StatusActive,
+	}
+
+	account := &service.Account{
+		ID:       accountID,
+		Name:     "ag-2",
+		Platform: service.PlatformAntigravity,
+		Type:     service.AccountTypeOAuth,
+		Credentials: map[string]any{
+			"access_token":              "tok_xxx",
+			"intercept_warmup_requests": true,
+		},
+		Concurrency:   1,
+		Priority:      1,
+		Status:        service.StatusActive,
+		Schedulable:   true,
+		AccountGroups: []service.AccountGroup{{AccountID: accountID, GroupID: groupID}},
+	}
+
+	h, cleanup := newTestGatewayHandler(t, group, []*service.Account{account})
+	defer cleanup()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+
+	body := []byte(`{
+		"model": "claude-sonnet-4-5",
+		"max_tokens": 256,
+		"messages": [{"role":"user","content":[{"type":"text","text":"Warmup"}]}]
+	}`)
+	req := httptest.NewRequest("POST", "/antigravity/v1/messages", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	// 模拟 routes/gateway.go 里的 ForcePlatform 中间件效果：
+	// - 写入 request.Context（Service读取）
+	// - 写入 gin.Context（Handler快速读取）
+	ctx := context.WithValue(req.Context(), ctxkey.Group, group)
+	ctx = context.WithValue(ctx, ctxkey.ForcePlatform, service.PlatformAntigravity)
+	req = req.WithContext(ctx)
+	c.Request = req
+	c.Set(string(middleware.ContextKeyForcePlatform), service.PlatformAntigravity)
+
+	apiKey := &service.APIKey{
+		ID:      3002,
+		UserID:  4002,
+		GroupID: &groupID,
+		Status:  service.StatusActive,
+		User: &service.User{
+			ID:          4002,
+			Concurrency: 10,
+			Balance:     100,
+		},
+		Group: group,
+	}
+
+	c.Set(string(middleware.ContextKeyAPIKey), apiKey)
+	c.Set(string(middleware.ContextKeyUser), middleware.AuthSubject{UserID: apiKey.UserID, Concurrency: 10})
+
+	h.Messages(c)
+
+	require.Equal(t, 200, rec.Code)
+
+	selected, ok := c.Get(opsAccountIDKey)
+	require.True(t, ok)
+	require.Equal(t, accountID, selected)
+
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Equal(t, "msg_mock_warmup", resp["id"])
+	require.Equal(t, "claude-sonnet-4-5", resp["model"])
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_helper.go

@@ -0,0 +1,400 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"math/rand/v2"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// claudeCodeValidator is a singleton validator for Claude Code client detection
+var claudeCodeValidator = service.NewClaudeCodeValidator()
+
+const claudeCodeParsedRequestContextKey = "claude_code_parsed_request"
+
+// SetClaudeCodeClientContext 检查请求是否来自 Claude Code 客户端，并设置到 context 中
+// 返回更新后的 context
+func SetClaudeCodeClientContext(c *gin.Context, body []byte, parsedReq *service.ParsedRequest) {
+	if c == nil || c.Request == nil {
+		return
+	}
+	if parsedReq != nil {
+		c.Set(claudeCodeParsedRequestContextKey, parsedReq)
+	}
+
+	ua := c.GetHeader("User-Agent")
+	// Fast path：非 Claude CLI UA 直接判定 false，避免热路径二次 JSON 反序列化。
+	if !claudeCodeValidator.ValidateUserAgent(ua) {
+		ctx := service.SetClaudeCodeClient(c.Request.Context(), false)
+		c.Request = c.Request.WithContext(ctx)
+		return
+	}
+
+	isClaudeCode := false
+	if !strings.Contains(c.Request.URL.Path, "messages") {
+		// 与 Validate 行为一致：非 messages 路径 UA 命中即可视为 Claude Code 客户端。
+		isClaudeCode = true
+	} else {
+		// 仅在确认为 Claude CLI 且 messages 路径时再做 body 解析。
+		bodyMap := claudeCodeBodyMapFromParsedRequest(parsedReq)
+		if bodyMap == nil {
+			bodyMap = claudeCodeBodyMapFromContextCache(c)
+		}
+		if bodyMap == nil && len(body) > 0 {
+			_ = json.Unmarshal(body, &bodyMap)
+		}
+		isClaudeCode = claudeCodeValidator.Validate(c.Request, bodyMap)
+	}
+
+	// 更新 request context
+	ctx := service.SetClaudeCodeClient(c.Request.Context(), isClaudeCode)
+
+	// 仅在确认为 Claude Code 客户端时提取版本号写入 context
+	if isClaudeCode {
+		if version := claudeCodeValidator.ExtractVersion(ua); version != "" {
+			ctx = service.SetClaudeCodeVersion(ctx, version)
+		}
+	}
+
+	c.Request = c.Request.WithContext(ctx)
+}
+
+func claudeCodeBodyMapFromParsedRequest(parsedReq *service.ParsedRequest) map[string]any {
+	if parsedReq == nil {
+		return nil
+	}
+	bodyMap := map[string]any{
+		"model": parsedReq.Model,
+	}
+	if parsedReq.System != nil || parsedReq.HasSystem {
+		bodyMap["system"] = parsedReq.System
+	}
+	if parsedReq.MetadataUserID != "" {
+		bodyMap["metadata"] = map[string]any{"user_id": parsedReq.MetadataUserID}
+	}
+	return bodyMap
+}
+
+func claudeCodeBodyMapFromContextCache(c *gin.Context) map[string]any {
+	if c == nil {
+		return nil
+	}
+	if cached, ok := c.Get(service.OpenAIParsedRequestBodyKey); ok {
+		if bodyMap, ok := cached.(map[string]any); ok {
+			return bodyMap
+		}
+	}
+	if cached, ok := c.Get(claudeCodeParsedRequestContextKey); ok {
+		switch v := cached.(type) {
+		case *service.ParsedRequest:
+			return claudeCodeBodyMapFromParsedRequest(v)
+		case service.ParsedRequest:
+			return claudeCodeBodyMapFromParsedRequest(&v)
+		}
+	}
+	return nil
+}
+
+// 并发槽位等待相关常量
+//
+// 性能优化说明：
+// 原实现使用固定间隔（100ms）轮询并发槽位，存在以下问题：
+// 1. 高并发时频繁轮询增加 Redis 压力
+// 2. 固定间隔可能导致多个请求同时重试（惊群效应）
+//
+// 新实现使用指数退避 + 抖动算法：
+// 1. 初始退避 100ms，每次乘以 1.5，最大 2s
+// 2. 添加 ±20% 的随机抖动，分散重试时间点
+// 3. 减少 Redis 压力，避免惊群效应
+const (
+	// maxConcurrencyWait 等待并发槽位的最大时间
+	maxConcurrencyWait = 30 * time.Second
+	// defaultPingInterval 流式响应等待时发送 ping 的默认间隔
+	defaultPingInterval = 10 * time.Second
+	// initialBackoff 初始退避时间
+	initialBackoff = 100 * time.Millisecond
+	// backoffMultiplier 退避时间乘数（指数退避）
+	backoffMultiplier = 1.5
+	// maxBackoff 最大退避时间
+	maxBackoff = 2 * time.Second
+)
+
+// SSEPingFormat defines the format of SSE ping events for different platforms
+type SSEPingFormat string
+
+const (
+	// SSEPingFormatClaude is the Claude/Anthropic SSE ping format
+	SSEPingFormatClaude SSEPingFormat = "data: {\"type\": \"ping\"}\n\n"
+	// SSEPingFormatNone indicates no ping should be sent (e.g., OpenAI has no ping spec)
+	SSEPingFormatNone SSEPingFormat = ""
+	// SSEPingFormatComment is an SSE comment ping for OpenAI/Codex CLI clients
+	SSEPingFormatComment SSEPingFormat = ":\n\n"
+)
+
+// ConcurrencyError represents a concurrency limit error with context
+type ConcurrencyError struct {
+	SlotType  string
+	IsTimeout bool
+}
+
+func (e *ConcurrencyError) Error() string {
+	if e.IsTimeout {
+		return fmt.Sprintf("timeout waiting for %s concurrency slot", e.SlotType)
+	}
+	return fmt.Sprintf("%s concurrency limit reached", e.SlotType)
+}
+
+// ConcurrencyHelper provides common concurrency slot management for gateway handlers
+type ConcurrencyHelper struct {
+	concurrencyService *service.ConcurrencyService
+	pingFormat         SSEPingFormat
+	pingInterval       time.Duration
+}
+
+// NewConcurrencyHelper creates a new ConcurrencyHelper
+func NewConcurrencyHelper(concurrencyService *service.ConcurrencyService, pingFormat SSEPingFormat, pingInterval time.Duration) *ConcurrencyHelper {
+	if pingInterval <= 0 {
+		pingInterval = defaultPingInterval
+	}
+	return &ConcurrencyHelper{
+		concurrencyService: concurrencyService,
+		pingFormat:         pingFormat,
+		pingInterval:       pingInterval,
+	}
+}
+
+// wrapReleaseOnDone ensures release runs at most once and still triggers on context cancellation.
+// 用于避免客户端断开或上游超时导致的并发槽位泄漏。
+// 优化：基于 context.AfterFunc 注册回调，避免每请求额外守护 goroutine。
+func wrapReleaseOnDone(ctx context.Context, releaseFunc func()) func() {
+	if releaseFunc == nil {
+		return nil
+	}
+	var once sync.Once
+	var stop func() bool
+
+	release := func() {
+		once.Do(func() {
+			if stop != nil {
+				_ = stop()
+			}
+			releaseFunc()
+		})
+	}
+
+	stop = context.AfterFunc(ctx, release)
+
+	return release
+}
+
+// IncrementWaitCount increments the wait count for a user
+func (h *ConcurrencyHelper) IncrementWaitCount(ctx context.Context, userID int64, maxWait int) (bool, error) {
+	return h.concurrencyService.IncrementWaitCount(ctx, userID, maxWait)
+}
+
+// DecrementWaitCount decrements the wait count for a user
+func (h *ConcurrencyHelper) DecrementWaitCount(ctx context.Context, userID int64) {
+	h.concurrencyService.DecrementWaitCount(ctx, userID)
+}
+
+// IncrementAccountWaitCount increments the wait count for an account
+func (h *ConcurrencyHelper) IncrementAccountWaitCount(ctx context.Context, accountID int64, maxWait int) (bool, error) {
+	return h.concurrencyService.IncrementAccountWaitCount(ctx, accountID, maxWait)
+}
+
+// DecrementAccountWaitCount decrements the wait count for an account
+func (h *ConcurrencyHelper) DecrementAccountWaitCount(ctx context.Context, accountID int64) {
+	h.concurrencyService.DecrementAccountWaitCount(ctx, accountID)
+}
+
+// TryAcquireUserSlot 尝试立即获取用户并发槽位。
+// 返回值: (releaseFunc, acquired, error)
+func (h *ConcurrencyHelper) TryAcquireUserSlot(ctx context.Context, userID int64, maxConcurrency int) (func(), bool, error) {
+	result, err := h.concurrencyService.AcquireUserSlot(ctx, userID, maxConcurrency)
+	if err != nil {
+		return nil, false, err
+	}
+	if !result.Acquired {
+		return nil, false, nil
+	}
+	return result.ReleaseFunc, true, nil
+}
+
+// TryAcquireAccountSlot 尝试立即获取账号并发槽位。
+// 返回值: (releaseFunc, acquired, error)
+func (h *ConcurrencyHelper) TryAcquireAccountSlot(ctx context.Context, accountID int64, maxConcurrency int) (func(), bool, error) {
+	result, err := h.concurrencyService.AcquireAccountSlot(ctx, accountID, maxConcurrency)
+	if err != nil {
+		return nil, false, err
+	}
+	if !result.Acquired {
+		return nil, false, nil
+	}
+	return result.ReleaseFunc, true, nil
+}
+
+// AcquireUserSlotWithWait acquires a user concurrency slot, waiting if necessary.
+// For streaming requests, sends ping events during the wait.
+// streamStarted is updated if streaming response has begun.
+func (h *ConcurrencyHelper) AcquireUserSlotWithWait(c *gin.Context, userID int64, maxConcurrency int, isStream bool, streamStarted *bool) (func(), error) {
+	ctx := c.Request.Context()
+
+	// Try to acquire immediately
+	releaseFunc, acquired, err := h.TryAcquireUserSlot(ctx, userID, maxConcurrency)
+	if err != nil {
+		return nil, err
+	}
+
+	if acquired {
+		return releaseFunc, nil
+	}
+
+	// Need to wait - handle streaming ping if needed
+	return h.waitForSlotWithPing(c, "user", userID, maxConcurrency, isStream, streamStarted)
+}
+
+// AcquireAccountSlotWithWait acquires an account concurrency slot, waiting if necessary.
+// For streaming requests, sends ping events during the wait.
+// streamStarted is updated if streaming response has begun.
+func (h *ConcurrencyHelper) AcquireAccountSlotWithWait(c *gin.Context, accountID int64, maxConcurrency int, isStream bool, streamStarted *bool) (func(), error) {
+	ctx := c.Request.Context()
+
+	// Try to acquire immediately
+	releaseFunc, acquired, err := h.TryAcquireAccountSlot(ctx, accountID, maxConcurrency)
+	if err != nil {
+		return nil, err
+	}
+
+	if acquired {
+		return releaseFunc, nil
+	}
+
+	// Need to wait - handle streaming ping if needed
+	return h.waitForSlotWithPing(c, "account", accountID, maxConcurrency, isStream, streamStarted)
+}
+
+// waitForSlotWithPing waits for a concurrency slot, sending ping events for streaming requests.
+// streamStarted pointer is updated when streaming begins (for proper error handling by caller).
+func (h *ConcurrencyHelper) waitForSlotWithPing(c *gin.Context, slotType string, id int64, maxConcurrency int, isStream bool, streamStarted *bool) (func(), error) {
+	return h.waitForSlotWithPingTimeout(c, slotType, id, maxConcurrency, maxConcurrencyWait, isStream, streamStarted, false)
+}
+
+// waitForSlotWithPingTimeout waits for a concurrency slot with a custom timeout.
+func (h *ConcurrencyHelper) waitForSlotWithPingTimeout(c *gin.Context, slotType string, id int64, maxConcurrency int, timeout time.Duration, isStream bool, streamStarted *bool, tryImmediate bool) (func(), error) {
+	ctx, cancel := context.WithTimeout(c.Request.Context(), timeout)
+	defer cancel()
+
+	acquireSlot := func() (*service.AcquireResult, error) {
+		if slotType == "user" {
+			return h.concurrencyService.AcquireUserSlot(ctx, id, maxConcurrency)
+		}
+		return h.concurrencyService.AcquireAccountSlot(ctx, id, maxConcurrency)
+	}
+
+	if tryImmediate {
+		result, err := acquireSlot()
+		if err != nil {
+			return nil, err
+		}
+		if result.Acquired {
+			return result.ReleaseFunc, nil
+		}
+	}
+
+	// Determine if ping is needed (streaming + ping format defined)
+	needPing := isStream && h.pingFormat != ""
+
+	var flusher http.Flusher
+	if needPing {
+		var ok bool
+		flusher, ok = c.Writer.(http.Flusher)
+		if !ok {
+			return nil, fmt.Errorf("streaming not supported")
+		}
+	}
+
+	// Only create ping ticker if ping is needed
+	var pingCh <-chan time.Time
+	if needPing {
+		pingTicker := time.NewTicker(h.pingInterval)
+		defer pingTicker.Stop()
+		pingCh = pingTicker.C
+	}
+
+	backoff := initialBackoff
+	timer := time.NewTimer(backoff)
+	defer timer.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return nil, &ConcurrencyError{
+				SlotType:  slotType,
+				IsTimeout: true,
+			}
+
+		case <-pingCh:
+			// Send ping to keep connection alive
+			if !*streamStarted {
+				c.Header("Content-Type", "text/event-stream")
+				c.Header("Cache-Control", "no-cache")
+				c.Header("Connection", "keep-alive")
+				c.Header("X-Accel-Buffering", "no")
+				*streamStarted = true
+			}
+			if _, err := fmt.Fprint(c.Writer, string(h.pingFormat)); err != nil {
+				return nil, err
+			}
+			flusher.Flush()
+
+		case <-timer.C:
+			// Try to acquire slot
+			result, err := acquireSlot()
+			if err != nil {
+				return nil, err
+			}
+
+			if result.Acquired {
+				return result.ReleaseFunc, nil
+			}
+			backoff = nextBackoff(backoff)
+			timer.Reset(backoff)
+		}
+	}
+}
+
+// AcquireAccountSlotWithWaitTimeout acquires an account slot with a custom timeout (keeps SSE ping).
+func (h *ConcurrencyHelper) AcquireAccountSlotWithWaitTimeout(c *gin.Context, accountID int64, maxConcurrency int, timeout time.Duration, isStream bool, streamStarted *bool) (func(), error) {
+	return h.waitForSlotWithPingTimeout(c, "account", accountID, maxConcurrency, timeout, isStream, streamStarted, true)
+}
+
+// nextBackoff 计算下一次退避时间
+// 性能优化：使用指数退避 + 随机抖动，避免惊群效应
+// current: 当前退避时间
+// 返回值：下一次退避时间（100ms ~ 2s 之间）
+func nextBackoff(current time.Duration) time.Duration {
+	// 指数退避：当前时间 * 1.5
+	next := time.Duration(float64(current) * backoffMultiplier)
+	if next > maxBackoff {
+		next = maxBackoff
+	}
+	// 添加 ±20% 的随机抖动（jitter 范围 0.8 ~ 1.2）
+	// 抖动可以分散多个请求的重试时间点，避免同时冲击 Redis
+	jitter := 0.8 + rand.Float64()*0.4
+	jittered := time.Duration(float64(next) * jitter)
+	if jittered < initialBackoff {
+		return initialBackoff
+	}
+	if jittered > maxBackoff {
+		return maxBackoff
+	}
+	return jittered
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_helper_backoff_test.go

@@ -0,0 +1,106 @@
+package handler
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// --- Task 6.2 验证: math/rand/v2 迁移后 nextBackoff 行为正确 ---
+
+func TestNextBackoff_ExponentialGrowth(t *testing.T) {
+	// 验证退避时间指数增长（乘数 1.5）
+	// 由于有随机抖动（±20%），需要验证范围
+	current := initialBackoff // 100ms
+
+	for i := 0; i < 10; i++ {
+		next := nextBackoff(current)
+
+		// 退避结果应在 [initialBackoff, maxBackoff] 范围内
+		assert.GreaterOrEqual(t, int64(next), int64(initialBackoff),
+			"第 %d 次退避不应低于初始值 %v", i, initialBackoff)
+		assert.LessOrEqual(t, int64(next), int64(maxBackoff),
+			"第 %d 次退避不应超过最大值 %v", i, maxBackoff)
+
+		// 为下一轮提供当前退避值
+		current = next
+	}
+}
+
+func TestNextBackoff_BoundedByMaxBackoff(t *testing.T) {
+	// 即使输入非常大，输出也不超过 maxBackoff
+	for i := 0; i < 100; i++ {
+		result := nextBackoff(10 * time.Second)
+		assert.LessOrEqual(t, int64(result), int64(maxBackoff),
+			"退避值不应超过 maxBackoff")
+	}
+}
+
+func TestNextBackoff_BoundedByInitialBackoff(t *testing.T) {
+	// 即使输入非常小，输出也不低于 initialBackoff
+	for i := 0; i < 100; i++ {
+		result := nextBackoff(1 * time.Millisecond)
+		assert.GreaterOrEqual(t, int64(result), int64(initialBackoff),
+			"退避值不应低于 initialBackoff")
+	}
+}
+
+func TestNextBackoff_HasJitter(t *testing.T) {
+	// 验证多次调用会产生不同的值（随机抖动生效）
+	// 使用相同的输入调用 50 次，收集结果
+	results := make(map[time.Duration]bool)
+	current := 500 * time.Millisecond
+
+	for i := 0; i < 50; i++ {
+		result := nextBackoff(current)
+		results[result] = true
+	}
+
+	// 50 次调用应该至少有 2 个不同的值（抖动存在）
+	require.Greater(t, len(results), 1,
+		"nextBackoff 应产生随机抖动，但所有 50 次调用结果相同")
+}
+
+func TestNextBackoff_InitialValueGrows(t *testing.T) {
+	// 验证从初始值开始，退避趋势是增长的
+	current := initialBackoff
+	var sum time.Duration
+
+	runs := 100
+	for i := 0; i < runs; i++ {
+		next := nextBackoff(current)
+		sum += next
+		current = next
+	}
+
+	avg := sum / time.Duration(runs)
+	// 平均退避时间应大于初始值（因为指数增长 + 上限）
+	assert.Greater(t, int64(avg), int64(initialBackoff),
+		"平均退避时间应大于初始退避值")
+}
+
+func TestNextBackoff_ConvergesToMaxBackoff(t *testing.T) {
+	// 从初始值开始，经过多次退避后应收敛到 maxBackoff 附近
+	current := initialBackoff
+	for i := 0; i < 20; i++ {
+		current = nextBackoff(current)
+	}
+
+	// 经过 20 次迭代后，应该已经到达 maxBackoff 区间
+	// 由于抖动，允许 ±20% 的范围
+	lowerBound := time.Duration(float64(maxBackoff) * 0.8)
+	assert.GreaterOrEqual(t, int64(current), int64(lowerBound),
+		"经过多次退避后应收敛到 maxBackoff 附近")
+}
+
+func BenchmarkNextBackoff(b *testing.B) {
+	current := initialBackoff
+	for i := 0; i < b.N; i++ {
+		current = nextBackoff(current)
+		if current > maxBackoff {
+			current = initialBackoff
+		}
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_helper_fastpath_test.go

@@ -0,0 +1,126 @@
+package handler
+
+import (
+	"context"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/require"
+)
+
+type concurrencyCacheMock struct {
+	acquireUserSlotFn    func(ctx context.Context, userID int64, maxConcurrency int, requestID string) (bool, error)
+	acquireAccountSlotFn func(ctx context.Context, accountID int64, maxConcurrency int, requestID string) (bool, error)
+	releaseUserCalled    int32
+	releaseAccountCalled int32
+}
+
+func (m *concurrencyCacheMock) AcquireAccountSlot(ctx context.Context, accountID int64, maxConcurrency int, requestID string) (bool, error) {
+	if m.acquireAccountSlotFn != nil {
+		return m.acquireAccountSlotFn(ctx, accountID, maxConcurrency, requestID)
+	}
+	return false, nil
+}
+
+func (m *concurrencyCacheMock) ReleaseAccountSlot(ctx context.Context, accountID int64, requestID string) error {
+	atomic.AddInt32(&m.releaseAccountCalled, 1)
+	return nil
+}
+
+func (m *concurrencyCacheMock) GetAccountConcurrency(ctx context.Context, accountID int64) (int, error) {
+	return 0, nil
+}
+
+func (m *concurrencyCacheMock) GetAccountConcurrencyBatch(ctx context.Context, accountIDs []int64) (map[int64]int, error) {
+	result := make(map[int64]int, len(accountIDs))
+	for _, accountID := range accountIDs {
+		result[accountID] = 0
+	}
+	return result, nil
+}
+
+func (m *concurrencyCacheMock) IncrementAccountWaitCount(ctx context.Context, accountID int64, maxWait int) (bool, error) {
+	return true, nil
+}
+
+func (m *concurrencyCacheMock) DecrementAccountWaitCount(ctx context.Context, accountID int64) error {
+	return nil
+}
+
+func (m *concurrencyCacheMock) GetAccountWaitingCount(ctx context.Context, accountID int64) (int, error) {
+	return 0, nil
+}
+
+func (m *concurrencyCacheMock) AcquireUserSlot(ctx context.Context, userID int64, maxConcurrency int, requestID string) (bool, error) {
+	if m.acquireUserSlotFn != nil {
+		return m.acquireUserSlotFn(ctx, userID, maxConcurrency, requestID)
+	}
+	return false, nil
+}
+
+func (m *concurrencyCacheMock) ReleaseUserSlot(ctx context.Context, userID int64, requestID string) error {
+	atomic.AddInt32(&m.releaseUserCalled, 1)
+	return nil
+}
+
+func (m *concurrencyCacheMock) GetUserConcurrency(ctx context.Context, userID int64) (int, error) {
+	return 0, nil
+}
+
+func (m *concurrencyCacheMock) IncrementWaitCount(ctx context.Context, userID int64, maxWait int) (bool, error) {
+	return true, nil
+}
+
+func (m *concurrencyCacheMock) DecrementWaitCount(ctx context.Context, userID int64) error {
+	return nil
+}
+
+func (m *concurrencyCacheMock) GetAccountsLoadBatch(ctx context.Context, accounts []service.AccountWithConcurrency) (map[int64]*service.AccountLoadInfo, error) {
+	return map[int64]*service.AccountLoadInfo{}, nil
+}
+
+func (m *concurrencyCacheMock) GetUsersLoadBatch(ctx context.Context, users []service.UserWithConcurrency) (map[int64]*service.UserLoadInfo, error) {
+	return map[int64]*service.UserLoadInfo{}, nil
+}
+
+func (m *concurrencyCacheMock) CleanupExpiredAccountSlots(ctx context.Context, accountID int64) error {
+	return nil
+}
+
+func (m *concurrencyCacheMock) CleanupStaleProcessSlots(ctx context.Context, activeRequestPrefix string) error {
+	return nil
+}
+
+func TestConcurrencyHelper_TryAcquireUserSlot(t *testing.T) {
+	cache := &concurrencyCacheMock{
+		acquireUserSlotFn: func(ctx context.Context, userID int64, maxConcurrency int, requestID string) (bool, error) {
+			return true, nil
+		},
+	}
+	helper := NewConcurrencyHelper(service.NewConcurrencyService(cache), SSEPingFormatNone, time.Second)
+
+	release, acquired, err := helper.TryAcquireUserSlot(context.Background(), 101, 2)
+	require.NoError(t, err)
+	require.True(t, acquired)
+	require.NotNil(t, release)
+
+	release()
+	require.Equal(t, int32(1), atomic.LoadInt32(&cache.releaseUserCalled))
+}
+
+func TestConcurrencyHelper_TryAcquireAccountSlot_NotAcquired(t *testing.T) {
+	cache := &concurrencyCacheMock{
+		acquireAccountSlotFn: func(ctx context.Context, accountID int64, maxConcurrency int, requestID string) (bool, error) {
+			return false, nil
+		},
+	}
+	helper := NewConcurrencyHelper(service.NewConcurrencyService(cache), SSEPingFormatNone, time.Second)
+
+	release, acquired, err := helper.TryAcquireAccountSlot(context.Background(), 201, 1)
+	require.NoError(t, err)
+	require.False(t, acquired)
+	require.Nil(t, release)
+	require.Equal(t, int32(0), atomic.LoadInt32(&cache.releaseAccountCalled))
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_helper_hotpath_test.go

@@ -0,0 +1,321 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type helperConcurrencyCacheStub struct {
+	mu sync.Mutex
+
+	accountSeq []bool
+	userSeq    []bool
+
+	accountAcquireCalls int
+	userAcquireCalls    int
+	accountReleaseCalls int
+	userReleaseCalls    int
+}
+
+func (s *helperConcurrencyCacheStub) AcquireAccountSlot(ctx context.Context, accountID int64, maxConcurrency int, requestID string) (bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.accountAcquireCalls++
+	if len(s.accountSeq) == 0 {
+		return false, nil
+	}
+	v := s.accountSeq[0]
+	s.accountSeq = s.accountSeq[1:]
+	return v, nil
+}
+
+func (s *helperConcurrencyCacheStub) ReleaseAccountSlot(ctx context.Context, accountID int64, requestID string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.accountReleaseCalls++
+	return nil
+}
+
+func (s *helperConcurrencyCacheStub) GetAccountConcurrency(ctx context.Context, accountID int64) (int, error) {
+	return 0, nil
+}
+
+func (s *helperConcurrencyCacheStub) GetAccountConcurrencyBatch(ctx context.Context, accountIDs []int64) (map[int64]int, error) {
+	out := make(map[int64]int, len(accountIDs))
+	for _, accountID := range accountIDs {
+		out[accountID] = 0
+	}
+	return out, nil
+}
+
+func (s *helperConcurrencyCacheStub) IncrementAccountWaitCount(ctx context.Context, accountID int64, maxWait int) (bool, error) {
+	return true, nil
+}
+
+func (s *helperConcurrencyCacheStub) DecrementAccountWaitCount(ctx context.Context, accountID int64) error {
+	return nil
+}
+
+func (s *helperConcurrencyCacheStub) GetAccountWaitingCount(ctx context.Context, accountID int64) (int, error) {
+	return 0, nil
+}
+
+func (s *helperConcurrencyCacheStub) AcquireUserSlot(ctx context.Context, userID int64, maxConcurrency int, requestID string) (bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.userAcquireCalls++
+	if len(s.userSeq) == 0 {
+		return false, nil
+	}
+	v := s.userSeq[0]
+	s.userSeq = s.userSeq[1:]
+	return v, nil
+}
+
+func (s *helperConcurrencyCacheStub) ReleaseUserSlot(ctx context.Context, userID int64, requestID string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.userReleaseCalls++
+	return nil
+}
+
+func (s *helperConcurrencyCacheStub) GetUserConcurrency(ctx context.Context, userID int64) (int, error) {
+	return 0, nil
+}
+
+func (s *helperConcurrencyCacheStub) IncrementWaitCount(ctx context.Context, userID int64, maxWait int) (bool, error) {
+	return true, nil
+}
+
+func (s *helperConcurrencyCacheStub) DecrementWaitCount(ctx context.Context, userID int64) error {
+	return nil
+}
+
+func (s *helperConcurrencyCacheStub) GetAccountsLoadBatch(ctx context.Context, accounts []service.AccountWithConcurrency) (map[int64]*service.AccountLoadInfo, error) {
+	out := make(map[int64]*service.AccountLoadInfo, len(accounts))
+	for _, acc := range accounts {
+		out[acc.ID] = &service.AccountLoadInfo{AccountID: acc.ID}
+	}
+	return out, nil
+}
+
+func (s *helperConcurrencyCacheStub) GetUsersLoadBatch(ctx context.Context, users []service.UserWithConcurrency) (map[int64]*service.UserLoadInfo, error) {
+	out := make(map[int64]*service.UserLoadInfo, len(users))
+	for _, user := range users {
+		out[user.ID] = &service.UserLoadInfo{UserID: user.ID}
+	}
+	return out, nil
+}
+
+func (s *helperConcurrencyCacheStub) CleanupExpiredAccountSlots(ctx context.Context, accountID int64) error {
+	return nil
+}
+
+func (s *helperConcurrencyCacheStub) CleanupStaleProcessSlots(ctx context.Context, activeRequestPrefix string) error {
+	return nil
+}
+
+func newHelperTestContext(method, path string) (*gin.Context, *httptest.ResponseRecorder) {
+	gin.SetMode(gin.TestMode)
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(method, path, nil)
+	return c, rec
+}
+
+func validClaudeCodeBodyJSON() []byte {
+	return []byte(`{
+		"model":"claude-3-5-sonnet-20241022",
+		"system":[{"text":"You are Claude Code, Anthropic's official CLI for Claude."}],
+		"metadata":{"user_id":"user_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_account__session_abc-123"}
+	}`)
+}
+
+func TestSetClaudeCodeClientContext_FastPathAndStrictPath(t *testing.T) {
+	t.Run("non_cli_user_agent_sets_false", func(t *testing.T) {
+		c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+		c.Request.Header.Set("User-Agent", "curl/8.6.0")
+
+		SetClaudeCodeClientContext(c, validClaudeCodeBodyJSON(), nil)
+		require.False(t, service.IsClaudeCodeClient(c.Request.Context()))
+	})
+
+	t.Run("cli_non_messages_path_sets_true", func(t *testing.T) {
+		c, _ := newHelperTestContext(http.MethodGet, "/v1/models")
+		c.Request.Header.Set("User-Agent", "claude-cli/1.0.1")
+
+		SetClaudeCodeClientContext(c, nil, nil)
+		require.True(t, service.IsClaudeCodeClient(c.Request.Context()))
+	})
+
+	t.Run("cli_messages_path_valid_body_sets_true", func(t *testing.T) {
+		c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+		c.Request.Header.Set("User-Agent", "claude-cli/1.0.1")
+		c.Request.Header.Set("X-App", "claude-code")
+		c.Request.Header.Set("anthropic-beta", "message-batches-2024-09-24")
+		c.Request.Header.Set("anthropic-version", "2023-06-01")
+
+		SetClaudeCodeClientContext(c, validClaudeCodeBodyJSON(), nil)
+		require.True(t, service.IsClaudeCodeClient(c.Request.Context()))
+	})
+
+	t.Run("cli_messages_path_invalid_body_sets_false", func(t *testing.T) {
+		c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+		c.Request.Header.Set("User-Agent", "claude-cli/1.0.1")
+		// 缺少严格校验所需 header + body 字段
+		SetClaudeCodeClientContext(c, []byte(`{"model":"x"}`), nil)
+		require.False(t, service.IsClaudeCodeClient(c.Request.Context()))
+	})
+}
+
+func TestSetClaudeCodeClientContext_ReuseParsedRequestAndContextCache(t *testing.T) {
+	t.Run("reuse parsed request without body unmarshal", func(t *testing.T) {
+		c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+		c.Request.Header.Set("User-Agent", "claude-cli/1.0.1")
+		c.Request.Header.Set("X-App", "claude-code")
+		c.Request.Header.Set("anthropic-beta", "message-batches-2024-09-24")
+		c.Request.Header.Set("anthropic-version", "2023-06-01")
+
+		parsedReq := &service.ParsedRequest{
+			Model: "claude-3-5-sonnet-20241022",
+			System: []any{
+				map[string]any{"text": "You are Claude Code, Anthropic's official CLI for Claude."},
+			},
+			MetadataUserID: "user_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_account__session_abc-123",
+		}
+
+		// body 非法 JSON，如果函数复用 parsedReq 成功则仍应判定为 Claude Code。
+		SetClaudeCodeClientContext(c, []byte(`{invalid`), parsedReq)
+		require.True(t, service.IsClaudeCodeClient(c.Request.Context()))
+	})
+
+	t.Run("reuse context cache without body unmarshal", func(t *testing.T) {
+		c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+		c.Request.Header.Set("User-Agent", "claude-cli/1.0.1")
+		c.Request.Header.Set("X-App", "claude-code")
+		c.Request.Header.Set("anthropic-beta", "message-batches-2024-09-24")
+		c.Request.Header.Set("anthropic-version", "2023-06-01")
+		c.Set(service.OpenAIParsedRequestBodyKey, map[string]any{
+			"model": "claude-3-5-sonnet-20241022",
+			"system": []any{
+				map[string]any{"text": "You are Claude Code, Anthropic's official CLI for Claude."},
+			},
+			"metadata": map[string]any{"user_id": "user_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_account__session_abc-123"},
+		})
+
+		SetClaudeCodeClientContext(c, []byte(`{invalid`), nil)
+		require.True(t, service.IsClaudeCodeClient(c.Request.Context()))
+	})
+}
+
+func TestWaitForSlotWithPingTimeout_AccountAndUserAcquire(t *testing.T) {
+	cache := &helperConcurrencyCacheStub{
+		accountSeq: []bool{false, true},
+		userSeq:    []bool{false, true},
+	}
+	concurrency := service.NewConcurrencyService(cache)
+	helper := NewConcurrencyHelper(concurrency, SSEPingFormatNone, 5*time.Millisecond)
+
+	t.Run("account_slot_acquired_after_retry", func(t *testing.T) {
+		c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+		streamStarted := false
+		release, err := helper.waitForSlotWithPingTimeout(c, "account", 101, 2, time.Second, false, &streamStarted, true)
+		require.NoError(t, err)
+		require.NotNil(t, release)
+		require.False(t, streamStarted)
+		release()
+		require.GreaterOrEqual(t, cache.accountAcquireCalls, 2)
+		require.GreaterOrEqual(t, cache.accountReleaseCalls, 1)
+	})
+
+	t.Run("user_slot_acquired_after_retry", func(t *testing.T) {
+		c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+		streamStarted := false
+		release, err := helper.waitForSlotWithPingTimeout(c, "user", 202, 3, time.Second, false, &streamStarted, true)
+		require.NoError(t, err)
+		require.NotNil(t, release)
+		release()
+		require.GreaterOrEqual(t, cache.userAcquireCalls, 2)
+		require.GreaterOrEqual(t, cache.userReleaseCalls, 1)
+	})
+}
+
+func TestWaitForSlotWithPingTimeout_TimeoutAndStreamPing(t *testing.T) {
+	cache := &helperConcurrencyCacheStub{
+		accountSeq: []bool{false, false, false},
+	}
+	concurrency := service.NewConcurrencyService(cache)
+
+	t.Run("timeout_returns_concurrency_error", func(t *testing.T) {
+		helper := NewConcurrencyHelper(concurrency, SSEPingFormatNone, 5*time.Millisecond)
+		c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+		streamStarted := false
+		release, err := helper.waitForSlotWithPingTimeout(c, "account", 101, 2, 130*time.Millisecond, false, &streamStarted, true)
+		require.Nil(t, release)
+		var cErr *ConcurrencyError
+		require.ErrorAs(t, err, &cErr)
+		require.True(t, cErr.IsTimeout)
+	})
+
+	t.Run("stream_mode_sends_ping_before_timeout", func(t *testing.T) {
+		helper := NewConcurrencyHelper(concurrency, SSEPingFormatComment, 10*time.Millisecond)
+		c, rec := newHelperTestContext(http.MethodPost, "/v1/messages")
+		streamStarted := false
+		release, err := helper.waitForSlotWithPingTimeout(c, "account", 101, 2, 70*time.Millisecond, true, &streamStarted, true)
+		require.Nil(t, release)
+		var cErr *ConcurrencyError
+		require.ErrorAs(t, err, &cErr)
+		require.True(t, cErr.IsTimeout)
+		require.True(t, streamStarted)
+		require.Contains(t, rec.Body.String(), ":\n\n")
+	})
+}
+
+func TestWaitForSlotWithPingTimeout_AcquireError(t *testing.T) {
+	errCache := &helperConcurrencyCacheStubWithError{
+		err: errors.New("redis unavailable"),
+	}
+	concurrency := service.NewConcurrencyService(errCache)
+	helper := NewConcurrencyHelper(concurrency, SSEPingFormatNone, 5*time.Millisecond)
+	c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+	streamStarted := false
+	release, err := helper.waitForSlotWithPingTimeout(c, "account", 1, 1, 200*time.Millisecond, false, &streamStarted, true)
+	require.Nil(t, release)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "redis unavailable")
+}
+
+func TestAcquireAccountSlotWithWaitTimeout_ImmediateAttemptBeforeBackoff(t *testing.T) {
+	cache := &helperConcurrencyCacheStub{
+		accountSeq: []bool{false},
+	}
+	concurrency := service.NewConcurrencyService(cache)
+	helper := NewConcurrencyHelper(concurrency, SSEPingFormatNone, 5*time.Millisecond)
+	c, _ := newHelperTestContext(http.MethodPost, "/v1/messages")
+	streamStarted := false
+
+	release, err := helper.AcquireAccountSlotWithWaitTimeout(c, 301, 1, 30*time.Millisecond, false, &streamStarted)
+	require.Nil(t, release)
+	var cErr *ConcurrencyError
+	require.ErrorAs(t, err, &cErr)
+	require.True(t, cErr.IsTimeout)
+	require.GreaterOrEqual(t, cache.accountAcquireCalls, 1)
+}
+
+type helperConcurrencyCacheStubWithError struct {
+	helperConcurrencyCacheStub
+	err error
+}
+
+func (s *helperConcurrencyCacheStubWithError) AcquireAccountSlot(ctx context.Context, accountID int64, maxConcurrency int, requestID string) (bool, error) {
+	return false, s.err
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gateway_helper_test.go

@@ -0,0 +1,141 @@
+package handler
+
+import (
+	"context"
+	"runtime"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// TestWrapReleaseOnDone_NoGoroutineLeak 验证 wrapReleaseOnDone 修复后不会泄露 goroutine
+func TestWrapReleaseOnDone_NoGoroutineLeak(t *testing.T) {
+	// 记录测试开始时的 goroutine 数量
+	runtime.GC()
+	time.Sleep(100 * time.Millisecond)
+	initialGoroutines := runtime.NumGoroutine()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var releaseCount int32
+	release := wrapReleaseOnDone(ctx, func() {
+		atomic.AddInt32(&releaseCount, 1)
+	})
+
+	// 正常释放
+	release()
+
+	// 等待足够时间确保 goroutine 退出
+	time.Sleep(200 * time.Millisecond)
+
+	// 验证只释放一次
+	if count := atomic.LoadInt32(&releaseCount); count != 1 {
+		t.Errorf("expected release count to be 1, got %d", count)
+	}
+
+	// 强制 GC，清理已退出的 goroutine
+	runtime.GC()
+	time.Sleep(100 * time.Millisecond)
+
+	// 验证 goroutine 数量没有增加（允许±2的误差，考虑到测试框架本身可能创建的 goroutine）
+	finalGoroutines := runtime.NumGoroutine()
+	if finalGoroutines > initialGoroutines+2 {
+		t.Errorf("goroutine leak detected: initial=%d, final=%d, leaked=%d",
+			initialGoroutines, finalGoroutines, finalGoroutines-initialGoroutines)
+	}
+}
+
+// TestWrapReleaseOnDone_ContextCancellation 验证 context 取消时也能正确释放
+func TestWrapReleaseOnDone_ContextCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+
+	var releaseCount int32
+	_ = wrapReleaseOnDone(ctx, func() {
+		atomic.AddInt32(&releaseCount, 1)
+	})
+
+	// 取消 context，应该触发释放
+	cancel()
+
+	// 等待释放完成
+	time.Sleep(100 * time.Millisecond)
+
+	// 验证释放被调用
+	if count := atomic.LoadInt32(&releaseCount); count != 1 {
+		t.Errorf("expected release count to be 1, got %d", count)
+	}
+}
+
+// TestWrapReleaseOnDone_MultipleCallsOnlyReleaseOnce 验证多次调用 release 只释放一次
+func TestWrapReleaseOnDone_MultipleCallsOnlyReleaseOnce(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var releaseCount int32
+	release := wrapReleaseOnDone(ctx, func() {
+		atomic.AddInt32(&releaseCount, 1)
+	})
+
+	// 调用多次
+	release()
+	release()
+	release()
+
+	// 等待执行完成
+	time.Sleep(100 * time.Millisecond)
+
+	// 验证只释放一次
+	if count := atomic.LoadInt32(&releaseCount); count != 1 {
+		t.Errorf("expected release count to be 1, got %d", count)
+	}
+}
+
+// TestWrapReleaseOnDone_NilReleaseFunc 验证 nil releaseFunc 不会 panic
+func TestWrapReleaseOnDone_NilReleaseFunc(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	release := wrapReleaseOnDone(ctx, nil)
+
+	if release != nil {
+		t.Error("expected nil release function when releaseFunc is nil")
+	}
+}
+
+// TestWrapReleaseOnDone_ConcurrentCalls 验证并发调用的安全性
+func TestWrapReleaseOnDone_ConcurrentCalls(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var releaseCount int32
+	release := wrapReleaseOnDone(ctx, func() {
+		atomic.AddInt32(&releaseCount, 1)
+	})
+
+	// 并发调用 release
+	const numGoroutines = 10
+	for i := 0; i < numGoroutines; i++ {
+		go release()
+	}
+
+	// 等待所有 goroutine 完成
+	time.Sleep(200 * time.Millisecond)
+
+	// 验证只释放一次
+	if count := atomic.LoadInt32(&releaseCount); count != 1 {
+		t.Errorf("expected release count to be 1, got %d", count)
+	}
+}
+
+// BenchmarkWrapReleaseOnDone 性能基准测试
+func BenchmarkWrapReleaseOnDone(b *testing.B) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		release := wrapReleaseOnDone(ctx, func() {})
+		release()
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gemini_cli_session_test.go

@@ -0,0 +1,143 @@
+//go:build unit
+
+package handler
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestExtractGeminiCLISessionHash(t *testing.T) {
+	tests := []struct {
+		name             string
+		body             string
+		privilegedUserID string
+		wantEmpty        bool
+		wantHash         string
+	}{
+		{
+			name:             "with privileged-user-id and tmp dir",
+			body:             `{"contents":[{"parts":[{"text":"The project's temporary directory is: /Users/ianshaw/.gemini/tmp/f7851b009ed314d1baee62e83115f486160283f4a55a582d89fdac8b9fe3b740"}]}]}`,
+			privilegedUserID: "90785f52-8bbe-4b17-b111-a1ddea1636c3",
+			wantEmpty:        false,
+			wantHash: func() string {
+				combined := "90785f52-8bbe-4b17-b111-a1ddea1636c3:f7851b009ed314d1baee62e83115f486160283f4a55a582d89fdac8b9fe3b740"
+				hash := sha256.Sum256([]byte(combined))
+				return hex.EncodeToString(hash[:])
+			}(),
+		},
+		{
+			name:             "without privileged-user-id but with tmp dir",
+			body:             `{"contents":[{"parts":[{"text":"The project's temporary directory is: /Users/ianshaw/.gemini/tmp/f7851b009ed314d1baee62e83115f486160283f4a55a582d89fdac8b9fe3b740"}]}]}`,
+			privilegedUserID: "",
+			wantEmpty:        false,
+			wantHash:         "f7851b009ed314d1baee62e83115f486160283f4a55a582d89fdac8b9fe3b740",
+		},
+		{
+			name:             "without tmp dir",
+			body:             `{"contents":[{"parts":[{"text":"Hello world"}]}]}`,
+			privilegedUserID: "90785f52-8bbe-4b17-b111-a1ddea1636c3",
+			wantEmpty:        true,
+		},
+		{
+			name:             "empty body",
+			body:             "",
+			privilegedUserID: "90785f52-8bbe-4b17-b111-a1ddea1636c3",
+			wantEmpty:        true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// 创建测试上下文
+			w := httptest.NewRecorder()
+			c, _ := gin.CreateTestContext(w)
+			c.Request = httptest.NewRequest("POST", "/test", nil)
+			if tt.privilegedUserID != "" {
+				c.Request.Header.Set("x-gemini-api-privileged-user-id", tt.privilegedUserID)
+			}
+
+			// 调用函数
+			result := extractGeminiCLISessionHash(c, []byte(tt.body))
+
+			// 验证结果
+			if tt.wantEmpty {
+				require.Empty(t, result, "expected empty session hash")
+			} else {
+				require.NotEmpty(t, result, "expected non-empty session hash")
+				require.Equal(t, tt.wantHash, result, "session hash mismatch")
+			}
+		})
+	}
+}
+
+func TestGeminiCLITmpDirRegex(t *testing.T) {
+	tests := []struct {
+		name      string
+		input     string
+		wantMatch bool
+		wantHash  string
+	}{
+		{
+			name:      "valid tmp dir path",
+			input:     "/Users/ianshaw/.gemini/tmp/f7851b009ed314d1baee62e83115f486160283f4a55a582d89fdac8b9fe3b740",
+			wantMatch: true,
+			wantHash:  "f7851b009ed314d1baee62e83115f486160283f4a55a582d89fdac8b9fe3b740",
+		},
+		{
+			name:      "valid tmp dir path in text",
+			input:     "The project's temporary directory is: /Users/ianshaw/.gemini/tmp/f7851b009ed314d1baee62e83115f486160283f4a55a582d89fdac8b9fe3b740\nOther text",
+			wantMatch: true,
+			wantHash:  "f7851b009ed314d1baee62e83115f486160283f4a55a582d89fdac8b9fe3b740",
+		},
+		{
+			name:      "invalid hash length",
+			input:     "/Users/ianshaw/.gemini/tmp/abc123",
+			wantMatch: false,
+		},
+		{
+			name:      "no tmp dir",
+			input:     "Hello world",
+			wantMatch: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			match := geminiCLITmpDirRegex.FindStringSubmatch(tt.input)
+			if tt.wantMatch {
+				require.NotNil(t, match, "expected regex to match")
+				require.Len(t, match, 2, "expected 2 capture groups")
+				require.Equal(t, tt.wantHash, match[1], "hash mismatch")
+			} else {
+				require.Nil(t, match, "expected regex not to match")
+			}
+		})
+	}
+}
+
+func TestSafeShortPrefix(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		n     int
+		want  string
+	}{
+		{name: "空字符串", input: "", n: 8, want: ""},
+		{name: "长度小于截断值", input: "abc", n: 8, want: "abc"},
+		{name: "长度等于截断值", input: "12345678", n: 8, want: "12345678"},
+		{name: "长度大于截断值", input: "1234567890", n: 8, want: "12345678"},
+		{name: "截断值为0", input: "123456", n: 0, want: "123456"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			require.Equal(t, tt.want, safeShortPrefix(tt.input, tt.n))
+		})
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gemini_v1beta_handler.go

@@ -0,0 +1,730 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"regexp"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/antigravity"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/gemini"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/googleapi"
+	pkghttputil "github.com/Wei-Shaw/sub2api/internal/pkg/httputil"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/google/uuid"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// geminiCLITmpDirRegex 用于从 Gemini CLI 请求体中提取 tmp 目录的哈希值
+// 匹配格式: /Users/xxx/.gemini/tmp/[64位十六进制哈希]
+var geminiCLITmpDirRegex = regexp.MustCompile(`/\.gemini/tmp/([A-Fa-f0-9]{64})`)
+
+// GeminiV1BetaListModels proxies:
+// GET /v1beta/models
+func (h *GatewayHandler) GeminiV1BetaListModels(c *gin.Context) {
+	apiKey, ok := middleware.GetAPIKeyFromContext(c)
+	if !ok || apiKey == nil {
+		googleError(c, http.StatusUnauthorized, "Invalid API key")
+		return
+	}
+	// 检查平台：优先使用强制平台（/antigravity 路由），否则要求 gemini 分组
+	forcePlatform, hasForcePlatform := middleware.GetForcePlatformFromContext(c)
+	if !hasForcePlatform && (apiKey.Group == nil || apiKey.Group.Platform != service.PlatformGemini) {
+		googleError(c, http.StatusBadRequest, "API key group platform is not gemini")
+		return
+	}
+
+	// 强制 antigravity 模式：返回 antigravity 支持的模型列表
+	if forcePlatform == service.PlatformAntigravity {
+		c.JSON(http.StatusOK, antigravity.FallbackGeminiModelsList())
+		return
+	}
+
+	account, err := h.geminiCompatService.SelectAccountForAIStudioEndpoints(c.Request.Context(), apiKey.GroupID)
+	if err != nil {
+		// 没有 gemini 账户，检查是否有 antigravity 账户可用
+		hasAntigravity, _ := h.geminiCompatService.HasAntigravityAccounts(c.Request.Context(), apiKey.GroupID)
+		if hasAntigravity {
+			// antigravity 账户使用静态模型列表
+			c.JSON(http.StatusOK, gemini.FallbackModelsList())
+			return
+		}
+		googleError(c, http.StatusServiceUnavailable, "No available Gemini accounts: "+err.Error())
+		return
+	}
+
+	res, err := h.geminiCompatService.ForwardAIStudioGET(c.Request.Context(), account, "/v1beta/models")
+	if err != nil {
+		googleError(c, http.StatusBadGateway, err.Error())
+		return
+	}
+	if shouldFallbackGeminiModels(res) {
+		c.JSON(http.StatusOK, gemini.FallbackModelsList())
+		return
+	}
+	writeUpstreamResponse(c, res)
+}
+
+// GeminiV1BetaGetModel proxies:
+// GET /v1beta/models/{model}
+func (h *GatewayHandler) GeminiV1BetaGetModel(c *gin.Context) {
+	apiKey, ok := middleware.GetAPIKeyFromContext(c)
+	if !ok || apiKey == nil {
+		googleError(c, http.StatusUnauthorized, "Invalid API key")
+		return
+	}
+	// 检查平台：优先使用强制平台（/antigravity 路由），否则要求 gemini 分组
+	forcePlatform, hasForcePlatform := middleware.GetForcePlatformFromContext(c)
+	if !hasForcePlatform && (apiKey.Group == nil || apiKey.Group.Platform != service.PlatformGemini) {
+		googleError(c, http.StatusBadRequest, "API key group platform is not gemini")
+		return
+	}
+
+	modelName := strings.TrimSpace(c.Param("model"))
+	if modelName == "" {
+		googleError(c, http.StatusBadRequest, "Missing model in URL")
+		return
+	}
+
+	// 强制 antigravity 模式：返回 antigravity 模型信息
+	if forcePlatform == service.PlatformAntigravity {
+		c.JSON(http.StatusOK, antigravity.FallbackGeminiModel(modelName))
+		return
+	}
+
+	account, err := h.geminiCompatService.SelectAccountForAIStudioEndpoints(c.Request.Context(), apiKey.GroupID)
+	if err != nil {
+		// 没有 gemini 账户，检查是否有 antigravity 账户可用
+		hasAntigravity, _ := h.geminiCompatService.HasAntigravityAccounts(c.Request.Context(), apiKey.GroupID)
+		if hasAntigravity {
+			// antigravity 账户使用静态模型信息
+			c.JSON(http.StatusOK, gemini.FallbackModel(modelName))
+			return
+		}
+		googleError(c, http.StatusServiceUnavailable, "No available Gemini accounts: "+err.Error())
+		return
+	}
+
+	res, err := h.geminiCompatService.ForwardAIStudioGET(c.Request.Context(), account, "/v1beta/models/"+modelName)
+	if err != nil {
+		googleError(c, http.StatusBadGateway, err.Error())
+		return
+	}
+	if shouldFallbackGeminiModels(res) {
+		c.JSON(http.StatusOK, gemini.FallbackModel(modelName))
+		return
+	}
+	writeUpstreamResponse(c, res)
+}
+
+// GeminiV1BetaModels proxies Gemini native REST endpoints like:
+// POST /v1beta/models/{model}:generateContent
+// POST /v1beta/models/{model}:streamGenerateContent?alt=sse
+func (h *GatewayHandler) GeminiV1BetaModels(c *gin.Context) {
+	apiKey, ok := middleware.GetAPIKeyFromContext(c)
+	if !ok || apiKey == nil {
+		googleError(c, http.StatusUnauthorized, "Invalid API key")
+		return
+	}
+	authSubject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok {
+		googleError(c, http.StatusInternalServerError, "User context not found")
+		return
+	}
+	reqLog := requestLogger(
+		c,
+		"handler.gemini_v1beta.models",
+		zap.Int64("user_id", authSubject.UserID),
+		zap.Int64("api_key_id", apiKey.ID),
+		zap.Any("group_id", apiKey.GroupID),
+	)
+
+	// 检查平台：优先使用强制平台（/antigravity 路由，中间件已设置 request.Context），否则要求 gemini 分组
+	if !middleware.HasForcePlatform(c) {
+		if apiKey.Group == nil || apiKey.Group.Platform != service.PlatformGemini {
+			googleError(c, http.StatusBadRequest, "API key group platform is not gemini")
+			return
+		}
+	}
+
+	modelName, action, err := parseGeminiModelAction(strings.TrimPrefix(c.Param("modelAction"), "/"))
+	if err != nil {
+		googleError(c, http.StatusNotFound, err.Error())
+		return
+	}
+
+	stream := action == "streamGenerateContent"
+	reqLog = reqLog.With(zap.String("model", modelName), zap.String("action", action), zap.Bool("stream", stream))
+
+	body, err := pkghttputil.ReadRequestBodyWithPrealloc(c.Request)
+	if err != nil {
+		if maxErr, ok := extractMaxBytesError(err); ok {
+			googleError(c, http.StatusRequestEntityTooLarge, buildBodyTooLargeMessage(maxErr.Limit))
+			return
+		}
+		googleError(c, http.StatusBadRequest, "Failed to read request body")
+		return
+	}
+	if len(body) == 0 {
+		googleError(c, http.StatusBadRequest, "Request body is empty")
+		return
+	}
+
+	setOpsRequestContext(c, modelName, stream, body)
+
+	// Get subscription (may be nil)
+	subscription, _ := middleware.GetSubscriptionFromContext(c)
+
+	// For Gemini native API, do not send Claude-style ping frames.
+	geminiConcurrency := NewConcurrencyHelper(h.concurrencyHelper.concurrencyService, SSEPingFormatNone, 0)
+
+	// 0) wait queue check
+	maxWait := service.CalculateMaxWait(authSubject.Concurrency)
+	canWait, err := geminiConcurrency.IncrementWaitCount(c.Request.Context(), authSubject.UserID, maxWait)
+	waitCounted := false
+	if err != nil {
+		reqLog.Warn("gemini.user_wait_counter_increment_failed", zap.Error(err))
+	} else if !canWait {
+		reqLog.Info("gemini.user_wait_queue_full", zap.Int("max_wait", maxWait))
+		googleError(c, http.StatusTooManyRequests, "Too many pending requests, please retry later")
+		return
+	}
+	if err == nil && canWait {
+		waitCounted = true
+	}
+	defer func() {
+		if waitCounted {
+			geminiConcurrency.DecrementWaitCount(c.Request.Context(), authSubject.UserID)
+		}
+	}()
+
+	// 1) user concurrency slot
+	streamStarted := false
+	if h.errorPassthroughService != nil {
+		service.BindErrorPassthroughService(c, h.errorPassthroughService)
+	}
+	userReleaseFunc, err := geminiConcurrency.AcquireUserSlotWithWait(c, authSubject.UserID, authSubject.Concurrency, stream, &streamStarted)
+	if err != nil {
+		reqLog.Warn("gemini.user_slot_acquire_failed", zap.Error(err))
+		googleError(c, http.StatusTooManyRequests, err.Error())
+		return
+	}
+	if waitCounted {
+		geminiConcurrency.DecrementWaitCount(c.Request.Context(), authSubject.UserID)
+		waitCounted = false
+	}
+	// 确保请求取消时也会释放槽位，避免长连接被动中断造成泄漏
+	userReleaseFunc = wrapReleaseOnDone(c.Request.Context(), userReleaseFunc)
+	if userReleaseFunc != nil {
+		defer userReleaseFunc()
+	}
+
+	// 2) billing eligibility check (after wait)
+	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
+		reqLog.Info("gemini.billing_eligibility_check_failed", zap.Error(err))
+		status, _, message := billingErrorDetails(err)
+		googleError(c, status, message)
+		return
+	}
+
+	// 3) select account (sticky session based on request body)
+	// 优先使用 Gemini CLI 的会话标识（privileged-user-id + tmp 目录哈希）
+	sessionHash := extractGeminiCLISessionHash(c, body)
+	if sessionHash == "" {
+		// Fallback: 使用通用的会话哈希生成逻辑（适用于其他客户端）
+		parsedReq, _ := service.ParseGatewayRequest(body, domain.PlatformGemini)
+		if parsedReq != nil {
+			parsedReq.SessionContext = &service.SessionContext{
+				ClientIP:  ip.GetClientIP(c),
+				UserAgent: c.GetHeader("User-Agent"),
+				APIKeyID:  apiKey.ID,
+			}
+		}
+		sessionHash = h.gatewayService.GenerateSessionHash(parsedReq)
+	}
+	sessionKey := sessionHash
+	if sessionHash != "" {
+		sessionKey = "gemini:" + sessionHash
+	}
+
+	// 查询粘性会话绑定的账号 ID（用于检测账号切换）
+	var sessionBoundAccountID int64
+	if sessionKey != "" {
+		sessionBoundAccountID, _ = h.gatewayService.GetCachedSessionAccountID(c.Request.Context(), apiKey.GroupID, sessionKey)
+		if sessionBoundAccountID > 0 {
+			prefetchedGroupID := int64(0)
+			if apiKey.GroupID != nil {
+				prefetchedGroupID = *apiKey.GroupID
+			}
+			ctx := service.WithPrefetchedStickySession(c.Request.Context(), sessionBoundAccountID, prefetchedGroupID, h.metadataBridgeEnabled())
+			c.Request = c.Request.WithContext(ctx)
+		}
+	}
+
+	// === Gemini 内容摘要会话 Fallback 逻辑 ===
+	// 当原有会话标识无效时（sessionBoundAccountID == 0），尝试基于内容摘要链匹配
+	var geminiDigestChain string
+	var geminiPrefixHash string
+	var geminiSessionUUID string
+	var matchedDigestChain string
+	useDigestFallback := sessionBoundAccountID == 0
+
+	if useDigestFallback {
+		// 解析 Gemini 请求体
+		var geminiReq antigravity.GeminiRequest
+		if err := json.Unmarshal(body, &geminiReq); err == nil && len(geminiReq.Contents) > 0 {
+			// 生成摘要链
+			geminiDigestChain = service.BuildGeminiDigestChain(&geminiReq)
+			if geminiDigestChain != "" {
+				// 生成前缀 hash
+				userAgent := c.GetHeader("User-Agent")
+				clientIP := ip.GetClientIP(c)
+				platform := ""
+				if apiKey.Group != nil {
+					platform = apiKey.Group.Platform
+				}
+				geminiPrefixHash = service.GenerateGeminiPrefixHash(
+					authSubject.UserID,
+					apiKey.ID,
+					clientIP,
+					userAgent,
+					platform,
+					modelName,
+				)
+
+				// 查找会话
+				foundUUID, foundAccountID, foundMatchedChain, found := h.gatewayService.FindGeminiSession(
+					c.Request.Context(),
+					derefGroupID(apiKey.GroupID),
+					geminiPrefixHash,
+					geminiDigestChain,
+				)
+				if found {
+					matchedDigestChain = foundMatchedChain
+					sessionBoundAccountID = foundAccountID
+					geminiSessionUUID = foundUUID
+					reqLog.Info("gemini.digest_fallback_matched",
+						zap.String("session_uuid_prefix", safeShortPrefix(foundUUID, 8)),
+						zap.Int64("account_id", foundAccountID),
+						zap.String("digest_chain", truncateDigestChain(geminiDigestChain)),
+					)
+
+					// 关键：如果原 sessionKey 为空，使用 prefixHash + uuid 作为 sessionKey
+					// 这样 SelectAccountWithLoadAwareness 的粘性会话逻辑会优先使用匹配到的账号
+					if sessionKey == "" {
+						sessionKey = service.GenerateGeminiDigestSessionKey(geminiPrefixHash, foundUUID)
+					}
+					_ = h.gatewayService.BindStickySession(c.Request.Context(), apiKey.GroupID, sessionKey, foundAccountID)
+				} else {
+					// 生成新的会话 UUID
+					geminiSessionUUID = uuid.New().String()
+					// 为新会话也生成 sessionKey（用于后续请求的粘性会话）
+					if sessionKey == "" {
+						sessionKey = service.GenerateGeminiDigestSessionKey(geminiPrefixHash, geminiSessionUUID)
+					}
+				}
+			}
+		}
+	}
+
+	// 判断是否真的绑定了粘性会话：有 sessionKey 且已经绑定到某个账号
+	hasBoundSession := sessionKey != "" && sessionBoundAccountID > 0
+	cleanedForUnknownBinding := false
+
+	fs := NewFailoverState(h.maxAccountSwitchesGemini, hasBoundSession)
+
+	// 单账号分组提前设置 SingleAccountRetry 标记，让 Service 层首次 503 就不设模型限流标记。
+	// 避免单账号分组收到 503 (MODEL_CAPACITY_EXHAUSTED) 时设 29s 限流，导致后续请求连续快速失败。
+	if h.gatewayService.IsSingleAntigravityAccountGroup(c.Request.Context(), apiKey.GroupID) {
+		ctx := service.WithSingleAccountRetry(c.Request.Context(), true, h.metadataBridgeEnabled())
+		c.Request = c.Request.WithContext(ctx)
+	}
+
+	for {
+		selection, err := h.gatewayService.SelectAccountWithLoadAwareness(c.Request.Context(), apiKey.GroupID, sessionKey, modelName, fs.FailedAccountIDs, "") // Gemini 不使用会话限制
+		if err != nil {
+			if len(fs.FailedAccountIDs) == 0 {
+				googleError(c, http.StatusServiceUnavailable, "No available Gemini accounts: "+err.Error())
+				return
+			}
+			action := fs.HandleSelectionExhausted(c.Request.Context())
+			switch action {
+			case FailoverContinue:
+				ctx := service.WithSingleAccountRetry(c.Request.Context(), true, h.metadataBridgeEnabled())
+				c.Request = c.Request.WithContext(ctx)
+				continue
+			case FailoverCanceled:
+				return
+			default: // FailoverExhausted
+				h.handleGeminiFailoverExhausted(c, fs.LastFailoverErr)
+				return
+			}
+		}
+		account := selection.Account
+		setOpsSelectedAccount(c, account.ID, account.Platform)
+
+		// 检测账号切换：如果粘性会话绑定的账号与当前选择的账号不同，清除 thoughtSignature
+		// 注意：Gemini 原生 API 的 thoughtSignature 与具体上游账号强相关；跨账号透传会导致 400。
+		if sessionBoundAccountID > 0 && sessionBoundAccountID != account.ID {
+			reqLog.Info("gemini.sticky_session_account_switched",
+				zap.Int64("from_account_id", sessionBoundAccountID),
+				zap.Int64("to_account_id", account.ID),
+				zap.Bool("clean_thought_signature", true),
+			)
+			body = service.CleanGeminiNativeThoughtSignatures(body)
+			sessionBoundAccountID = account.ID
+		} else if sessionKey != "" && sessionBoundAccountID == 0 && !cleanedForUnknownBinding && bytes.Contains(body, []byte(`"thoughtSignature"`)) {
+			// 无缓存绑定但请求里已有 thoughtSignature：常见于缓存丢失/TTL 过期后，客户端继续携带旧签名。
+			// 为避免第一次转发就 400，这里做一次确定性清理，让新账号重新生成签名链路。
+			reqLog.Info("gemini.sticky_session_binding_missing",
+				zap.Bool("clean_thought_signature", true),
+			)
+			body = service.CleanGeminiNativeThoughtSignatures(body)
+			cleanedForUnknownBinding = true
+			sessionBoundAccountID = account.ID
+		} else if sessionBoundAccountID == 0 {
+			// 记录本次请求中首次选择到的账号，便于同一请求内 failover 时检测切换。
+			sessionBoundAccountID = account.ID
+		}
+
+		// 4) account concurrency slot
+		accountReleaseFunc := selection.ReleaseFunc
+		if !selection.Acquired {
+			if selection.WaitPlan == nil {
+				googleError(c, http.StatusServiceUnavailable, "No available Gemini accounts")
+				return
+			}
+			accountWaitCounted := false
+			canWait, err := geminiConcurrency.IncrementAccountWaitCount(c.Request.Context(), account.ID, selection.WaitPlan.MaxWaiting)
+			if err != nil {
+				reqLog.Warn("gemini.account_wait_counter_increment_failed", zap.Int64("account_id", account.ID), zap.Error(err))
+			} else if !canWait {
+				reqLog.Info("gemini.account_wait_queue_full",
+					zap.Int64("account_id", account.ID),
+					zap.Int("max_waiting", selection.WaitPlan.MaxWaiting),
+				)
+				googleError(c, http.StatusTooManyRequests, "Too many pending requests, please retry later")
+				return
+			}
+			if err == nil && canWait {
+				accountWaitCounted = true
+			}
+			defer func() {
+				if accountWaitCounted {
+					geminiConcurrency.DecrementAccountWaitCount(c.Request.Context(), account.ID)
+				}
+			}()
+
+			accountReleaseFunc, err = geminiConcurrency.AcquireAccountSlotWithWaitTimeout(
+				c,
+				account.ID,
+				selection.WaitPlan.MaxConcurrency,
+				selection.WaitPlan.Timeout,
+				stream,
+				&streamStarted,
+			)
+			if err != nil {
+				reqLog.Warn("gemini.account_slot_acquire_failed", zap.Int64("account_id", account.ID), zap.Error(err))
+				googleError(c, http.StatusTooManyRequests, err.Error())
+				return
+			}
+			if accountWaitCounted {
+				geminiConcurrency.DecrementAccountWaitCount(c.Request.Context(), account.ID)
+				accountWaitCounted = false
+			}
+			if err := h.gatewayService.BindStickySession(c.Request.Context(), apiKey.GroupID, sessionKey, account.ID); err != nil {
+				reqLog.Warn("gemini.bind_sticky_session_failed", zap.Int64("account_id", account.ID), zap.Error(err))
+			}
+		}
+		// 账号槽位/等待计数需要在超时或断开时安全回收
+		accountReleaseFunc = wrapReleaseOnDone(c.Request.Context(), accountReleaseFunc)
+
+		// 5) forward (根据平台分流)
+		var result *service.ForwardResult
+		requestCtx := c.Request.Context()
+		if fs.SwitchCount > 0 {
+			requestCtx = service.WithAccountSwitchCount(requestCtx, fs.SwitchCount, h.metadataBridgeEnabled())
+		}
+		if account.Platform == service.PlatformAntigravity && account.Type != service.AccountTypeAPIKey {
+			result, err = h.antigravityGatewayService.ForwardGemini(requestCtx, c, account, modelName, action, stream, body, hasBoundSession)
+		} else {
+			result, err = h.geminiCompatService.ForwardNative(requestCtx, c, account, modelName, action, stream, body)
+		}
+		if accountReleaseFunc != nil {
+			accountReleaseFunc()
+		}
+		if err != nil {
+			var failoverErr *service.UpstreamFailoverError
+			if errors.As(err, &failoverErr) {
+				failoverAction := fs.HandleFailoverError(c.Request.Context(), h.gatewayService, account.ID, account.Platform, failoverErr)
+				switch failoverAction {
+				case FailoverContinue:
+					continue
+				case FailoverExhausted:
+					h.handleGeminiFailoverExhausted(c, fs.LastFailoverErr)
+					return
+				case FailoverCanceled:
+					return
+				}
+			}
+			// ForwardNative already wrote the response
+			reqLog.Error("gemini.forward_failed", zap.Int64("account_id", account.ID), zap.Error(err))
+			return
+		}
+
+		// 捕获请求信息（用于异步记录，避免在 goroutine 中访问 gin.Context）
+		userAgent := c.GetHeader("User-Agent")
+		clientIP := ip.GetClientIP(c)
+
+		// 保存 Gemini 内容摘要会话（用于 Fallback 匹配）
+		if useDigestFallback && geminiDigestChain != "" && geminiPrefixHash != "" {
+			if err := h.gatewayService.SaveGeminiSession(
+				c.Request.Context(),
+				derefGroupID(apiKey.GroupID),
+				geminiPrefixHash,
+				geminiDigestChain,
+				geminiSessionUUID,
+				account.ID,
+				matchedDigestChain,
+			); err != nil {
+				reqLog.Warn("gemini.digest_session_save_failed", zap.Int64("account_id", account.ID), zap.Error(err))
+			}
+		}
+
+		// 使用量记录通过有界 worker 池提交，避免请求热路径创建无界 goroutine。
+		requestPayloadHash := service.HashUsageRequestPayload(body)
+		inboundEndpoint := GetInboundEndpoint(c)
+		upstreamEndpoint := GetUpstreamEndpoint(c, account.Platform)
+		h.submitUsageRecordTask(func(ctx context.Context) {
+			if err := h.gatewayService.RecordUsageWithLongContext(ctx, &service.RecordUsageLongContextInput{
+				Result:                result,
+				APIKey:                apiKey,
+				User:                  apiKey.User,
+				Account:               account,
+				Subscription:          subscription,
+				InboundEndpoint:       inboundEndpoint,
+				UpstreamEndpoint:      upstreamEndpoint,
+				UserAgent:             userAgent,
+				IPAddress:             clientIP,
+				RequestPayloadHash:    requestPayloadHash,
+				LongContextThreshold:  200000, // Gemini 200K 阈值
+				LongContextMultiplier: 2.0,    // 超出部分双倍计费
+				ForceCacheBilling:     fs.ForceCacheBilling,
+				APIKeyService:         h.apiKeyService,
+			}); err != nil {
+				logger.L().With(
+					zap.String("component", "handler.gemini_v1beta.models"),
+					zap.Int64("user_id", authSubject.UserID),
+					zap.Int64("api_key_id", apiKey.ID),
+					zap.Any("group_id", apiKey.GroupID),
+					zap.String("model", modelName),
+					zap.Int64("account_id", account.ID),
+				).Error("gemini.record_usage_failed", zap.Error(err))
+			}
+		})
+		reqLog.Debug("gemini.request_completed",
+			zap.Int64("account_id", account.ID),
+			zap.Int("switch_count", fs.SwitchCount),
+		)
+		return
+	}
+}
+
+func parseGeminiModelAction(rest string) (model string, action string, err error) {
+	rest = strings.TrimSpace(rest)
+	if rest == "" {
+		return "", "", &pathParseError{"missing path"}
+	}
+
+	// Standard: {model}:{action}
+	if i := strings.Index(rest, ":"); i > 0 && i < len(rest)-1 {
+		return rest[:i], rest[i+1:], nil
+	}
+
+	// Fallback: {model}/{action}
+	if i := strings.Index(rest, "/"); i > 0 && i < len(rest)-1 {
+		return rest[:i], rest[i+1:], nil
+	}
+
+	return "", "", &pathParseError{"invalid model action path"}
+}
+
+func (h *GatewayHandler) handleGeminiFailoverExhausted(c *gin.Context, failoverErr *service.UpstreamFailoverError) {
+	if failoverErr == nil {
+		googleError(c, http.StatusBadGateway, "Upstream request failed")
+		return
+	}
+
+	statusCode := failoverErr.StatusCode
+	responseBody := failoverErr.ResponseBody
+
+	// 先检查透传规则
+	if h.errorPassthroughService != nil && len(responseBody) > 0 {
+		if rule := h.errorPassthroughService.MatchRule(service.PlatformGemini, statusCode, responseBody); rule != nil {
+			// 确定响应状态码
+			respCode := statusCode
+			if !rule.PassthroughCode && rule.ResponseCode != nil {
+				respCode = *rule.ResponseCode
+			}
+
+			// 确定响应消息
+			msg := service.ExtractUpstreamErrorMessage(responseBody)
+			if !rule.PassthroughBody && rule.CustomMessage != nil {
+				msg = *rule.CustomMessage
+			}
+
+			if rule.SkipMonitoring {
+				c.Set(service.OpsSkipPassthroughKey, true)
+			}
+
+			googleError(c, respCode, msg)
+			return
+		}
+	}
+
+	// 使用默认的错误映射
+	status, message := mapGeminiUpstreamError(statusCode)
+	googleError(c, status, message)
+}
+
+func mapGeminiUpstreamError(statusCode int) (int, string) {
+	switch statusCode {
+	case 401:
+		return http.StatusBadGateway, "Upstream authentication failed, please contact administrator"
+	case 403:
+		return http.StatusBadGateway, "Upstream access forbidden, please contact administrator"
+	case 429:
+		return http.StatusTooManyRequests, "Upstream rate limit exceeded, please retry later"
+	case 529:
+		return http.StatusServiceUnavailable, "Upstream service overloaded, please retry later"
+	case 500, 502, 503, 504:
+		return http.StatusBadGateway, "Upstream service temporarily unavailable"
+	default:
+		return http.StatusBadGateway, "Upstream request failed"
+	}
+}
+
+type pathParseError struct{ msg string }
+
+func (e *pathParseError) Error() string { return e.msg }
+
+func googleError(c *gin.Context, status int, message string) {
+	c.JSON(status, gin.H{
+		"error": gin.H{
+			"code":    status,
+			"message": message,
+			"status":  googleapi.HTTPStatusToGoogleStatus(status),
+		},
+	})
+}
+
+func writeUpstreamResponse(c *gin.Context, res *service.UpstreamHTTPResult) {
+	if res == nil {
+		googleError(c, http.StatusBadGateway, "Empty upstream response")
+		return
+	}
+	for k, vv := range res.Headers {
+		// Avoid overriding content-length and hop-by-hop headers.
+		if strings.EqualFold(k, "Content-Length") || strings.EqualFold(k, "Transfer-Encoding") || strings.EqualFold(k, "Connection") {
+			continue
+		}
+		for _, v := range vv {
+			c.Writer.Header().Add(k, v)
+		}
+	}
+	contentType := res.Headers.Get("Content-Type")
+	if contentType == "" {
+		contentType = "application/json"
+	}
+	c.Data(res.StatusCode, contentType, res.Body)
+}
+
+func shouldFallbackGeminiModels(res *service.UpstreamHTTPResult) bool {
+	if res == nil {
+		return true
+	}
+	if res.StatusCode != http.StatusUnauthorized && res.StatusCode != http.StatusForbidden {
+		return false
+	}
+	if strings.Contains(strings.ToLower(res.Headers.Get("Www-Authenticate")), "insufficient_scope") {
+		return true
+	}
+	if strings.Contains(strings.ToLower(string(res.Body)), "insufficient authentication scopes") {
+		return true
+	}
+	if strings.Contains(strings.ToLower(string(res.Body)), "access_token_scope_insufficient") {
+		return true
+	}
+	return false
+}
+
+// extractGeminiCLISessionHash 从 Gemini CLI 请求中提取会话标识。
+// 组合 x-gemini-api-privileged-user-id header 和请求体中的 tmp 目录哈希。
+//
+// 会话标识生成策略：
+//  1. 从请求体中提取 tmp 目录哈希（64位十六进制）
+//  2. 从 header 中提取 privileged-user-id（UUID）
+//  3. 组合两者生成 SHA256 哈希作为最终的会话标识
+//
+// 如果找不到 tmp 目录哈希，返回空字符串（不使用粘性会话）。
+//
+// extractGeminiCLISessionHash extracts session identifier from Gemini CLI requests.
+// Combines x-gemini-api-privileged-user-id header with tmp directory hash from request body.
+func extractGeminiCLISessionHash(c *gin.Context, body []byte) string {
+	// 1. 从请求体中提取 tmp 目录哈希
+	match := geminiCLITmpDirRegex.FindSubmatch(body)
+	if len(match) < 2 {
+		return "" // 没有找到 tmp 目录，不使用粘性会话
+	}
+	tmpDirHash := string(match[1])
+
+	// 2. 提取 privileged-user-id
+	privilegedUserID := strings.TrimSpace(c.GetHeader("x-gemini-api-privileged-user-id"))
+
+	// 3. 组合生成最终的 session hash
+	if privilegedUserID != "" {
+		// 组合两个标识符：privileged-user-id + tmp 目录哈希
+		combined := privilegedUserID + ":" + tmpDirHash
+		hash := sha256.Sum256([]byte(combined))
+		return hex.EncodeToString(hash[:])
+	}
+
+	// 如果没有 privileged-user-id，直接使用 tmp 目录哈希
+	return tmpDirHash
+}
+
+// truncateDigestChain 截断摘要链用于日志显示
+func truncateDigestChain(chain string) string {
+	if len(chain) <= 50 {
+		return chain
+	}
+	return chain[:50] + "..."
+}
+
+// safeShortPrefix 返回字符串前 n 个字符；长度不足时返回原字符串。
+// 用于日志展示，避免切片越界。
+func safeShortPrefix(value string, n int) string {
+	if n <= 0 || len(value) <= n {
+		return value
+	}
+	return value[:n]
+}
+
+// derefGroupID 安全解引用 *int64，nil 返回 0
+func derefGroupID(groupID *int64) int64 {
+	if groupID == nil {
+		return 0
+	}
+	return *groupID
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/gemini_v1beta_handler_test.go

@@ -0,0 +1,143 @@
+//go:build unit
+
+package handler
+
+import (
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/require"
+)
+
+// TestGeminiV1BetaHandler_PlatformRoutingInvariant 文档化并验证 Handler 层的平台路由逻辑不变量
+// 该测试确保 gemini 和 antigravity 平台的路由逻辑符合预期
+func TestGeminiV1BetaHandler_PlatformRoutingInvariant(t *testing.T) {
+	tests := []struct {
+		name            string
+		platform        string
+		expectedService string
+		description     string
+	}{
+		{
+			name:            "Gemini平台使用ForwardNative",
+			platform:        service.PlatformGemini,
+			expectedService: "GeminiMessagesCompatService.ForwardNative",
+			description:     "Gemini OAuth 账户直接调用 Google API",
+		},
+		{
+			name:            "Antigravity平台使用ForwardGemini",
+			platform:        service.PlatformAntigravity,
+			expectedService: "AntigravityGatewayService.ForwardGemini",
+			description:     "Antigravity 账户通过 CRS 中转，支持 Gemini 协议",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// 模拟 GeminiV1BetaModels 中的路由决策 (lines 199-205 in gemini_v1beta_handler.go)
+			var routedService string
+			if tt.platform == service.PlatformAntigravity {
+				routedService = "AntigravityGatewayService.ForwardGemini"
+			} else {
+				routedService = "GeminiMessagesCompatService.ForwardNative"
+			}
+
+			require.Equal(t, tt.expectedService, routedService,
+				"平台 %s 应该路由到 %s: %s",
+				tt.platform, tt.expectedService, tt.description)
+		})
+	}
+}
+
+// TestGeminiV1BetaHandler_ListModelsAntigravityFallback 验证 ListModels 的 antigravity 降级逻辑
+// 当没有 gemini 账户但有 antigravity 账户时，应返回静态模型列表
+func TestGeminiV1BetaHandler_ListModelsAntigravityFallback(t *testing.T) {
+	tests := []struct {
+		name             string
+		hasGeminiAccount bool
+		hasAntigravity   bool
+		expectedBehavior string
+	}{
+		{
+			name:             "有Gemini账户-调用ForwardAIStudioGET",
+			hasGeminiAccount: true,
+			hasAntigravity:   false,
+			expectedBehavior: "forward_to_upstream",
+		},
+		{
+			name:             "无Gemini有Antigravity-返回静态列表",
+			hasGeminiAccount: false,
+			hasAntigravity:   true,
+			expectedBehavior: "static_fallback",
+		},
+		{
+			name:             "无任何账户-返回503",
+			hasGeminiAccount: false,
+			hasAntigravity:   false,
+			expectedBehavior: "service_unavailable",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// 模拟 GeminiV1BetaListModels 的逻辑 (lines 33-44 in gemini_v1beta_handler.go)
+			var behavior string
+
+			if tt.hasGeminiAccount {
+				behavior = "forward_to_upstream"
+			} else if tt.hasAntigravity {
+				behavior = "static_fallback"
+			} else {
+				behavior = "service_unavailable"
+			}
+
+			require.Equal(t, tt.expectedBehavior, behavior)
+		})
+	}
+}
+
+// TestGeminiV1BetaHandler_GetModelAntigravityFallback 验证 GetModel 的 antigravity 降级逻辑
+func TestGeminiV1BetaHandler_GetModelAntigravityFallback(t *testing.T) {
+	tests := []struct {
+		name             string
+		hasGeminiAccount bool
+		hasAntigravity   bool
+		expectedBehavior string
+	}{
+		{
+			name:             "有Gemini账户-调用ForwardAIStudioGET",
+			hasGeminiAccount: true,
+			hasAntigravity:   false,
+			expectedBehavior: "forward_to_upstream",
+		},
+		{
+			name:             "无Gemini有Antigravity-返回静态模型信息",
+			hasGeminiAccount: false,
+			hasAntigravity:   true,
+			expectedBehavior: "static_model_info",
+		},
+		{
+			name:             "无任何账户-返回503",
+			hasGeminiAccount: false,
+			hasAntigravity:   false,
+			expectedBehavior: "service_unavailable",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// 模拟 GeminiV1BetaGetModel 的逻辑 (lines 77-87 in gemini_v1beta_handler.go)
+			var behavior string
+
+			if tt.hasGeminiAccount {
+				behavior = "forward_to_upstream"
+			} else if tt.hasAntigravity {
+				behavior = "static_model_info"
+			} else {
+				behavior = "service_unavailable"
+			}
+
+			require.Equal(t, tt.expectedBehavior, behavior)
+		})
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/handler.go

@@ -0,0 +1,56 @@
+package handler
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/handler/admin"
+)
+
+// AdminHandlers contains all admin-related HTTP handlers
+type AdminHandlers struct {
+	Dashboard        *admin.DashboardHandler
+	User             *admin.UserHandler
+	Group            *admin.GroupHandler
+	Account          *admin.AccountHandler
+	Announcement     *admin.AnnouncementHandler
+	DataManagement   *admin.DataManagementHandler
+	Backup           *admin.BackupHandler
+	OAuth            *admin.OAuthHandler
+	OpenAIOAuth      *admin.OpenAIOAuthHandler
+	GeminiOAuth      *admin.GeminiOAuthHandler
+	AntigravityOAuth *admin.AntigravityOAuthHandler
+	Proxy            *admin.ProxyHandler
+	Redeem           *admin.RedeemHandler
+	Promo            *admin.PromoHandler
+	Setting          *admin.SettingHandler
+	Ops              *admin.OpsHandler
+	System           *admin.SystemHandler
+	Subscription     *admin.SubscriptionHandler
+	Usage            *admin.UsageHandler
+	UserAttribute    *admin.UserAttributeHandler
+	ErrorPassthrough *admin.ErrorPassthroughHandler
+	APIKey           *admin.AdminAPIKeyHandler
+	ScheduledTest    *admin.ScheduledTestHandler
+}
+
+// Handlers contains all HTTP handlers
+type Handlers struct {
+	Auth          *AuthHandler
+	User          *UserHandler
+	APIKey        *APIKeyHandler
+	Usage         *UsageHandler
+	Redeem        *RedeemHandler
+	Subscription  *SubscriptionHandler
+	Announcement  *AnnouncementHandler
+	Admin         *AdminHandlers
+	Gateway       *GatewayHandler
+	OpenAIGateway *OpenAIGatewayHandler
+	SoraGateway   *SoraGatewayHandler
+	SoraClient    *SoraClientHandler
+	Setting       *SettingHandler
+	Totp          *TotpHandler
+}
+
+// BuildInfo contains build-time information
+type BuildInfo struct {
+	Version   string
+	BuildType string // "source" for manual builds, "release" for CI builds
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/idempotency_helper.go

@@ -0,0 +1,65 @@
+package handler
+
+import (
+	"context"
+	"strconv"
+	"time"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+func executeUserIdempotentJSON(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	execute func(context.Context) (any, error),
+) {
+	coordinator := service.DefaultIdempotencyCoordinator()
+	if coordinator == nil {
+		data, err := execute(c.Request.Context())
+		if err != nil {
+			response.ErrorFrom(c, err)
+			return
+		}
+		response.Success(c, data)
+		return
+	}
+
+	actorScope := "user:0"
+	if subject, ok := middleware2.GetAuthSubjectFromContext(c); ok {
+		actorScope = "user:" + strconv.FormatInt(subject.UserID, 10)
+	}
+
+	result, err := coordinator.Execute(c.Request.Context(), service.IdempotencyExecuteOptions{
+		Scope:          scope,
+		ActorScope:     actorScope,
+		Method:         c.Request.Method,
+		Route:          c.FullPath(),
+		IdempotencyKey: c.GetHeader("Idempotency-Key"),
+		Payload:        payload,
+		RequireKey:     true,
+		TTL:            ttl,
+	}, execute)
+	if err != nil {
+		if infraerrors.Code(err) == infraerrors.Code(service.ErrIdempotencyStoreUnavail) {
+			service.RecordIdempotencyStoreUnavailable(c.FullPath(), scope, "handler_fail_close")
+			logger.LegacyPrintf("handler.idempotency", "[Idempotency] store unavailable: method=%s route=%s scope=%s strategy=fail_close", c.Request.Method, c.FullPath(), scope)
+		}
+		if retryAfter := service.RetryAfterSecondsFromError(err); retryAfter > 0 {
+			c.Header("Retry-After", strconv.Itoa(retryAfter))
+		}
+		response.ErrorFrom(c, err)
+		return
+	}
+	if result != nil && result.Replayed {
+		c.Header("X-Idempotency-Replayed", "true")
+	}
+	response.Success(c, result.Data)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/idempotency_helper_test.go

@@ -0,0 +1,285 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type userStoreUnavailableRepoStub struct{}
+
+func (userStoreUnavailableRepoStub) CreateProcessing(context.Context, *service.IdempotencyRecord) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (userStoreUnavailableRepoStub) GetByScopeAndKeyHash(context.Context, string, string) (*service.IdempotencyRecord, error) {
+	return nil, errors.New("store unavailable")
+}
+func (userStoreUnavailableRepoStub) TryReclaim(context.Context, int64, string, time.Time, time.Time, time.Time) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (userStoreUnavailableRepoStub) ExtendProcessingLock(context.Context, int64, string, time.Time, time.Time) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (userStoreUnavailableRepoStub) MarkSucceeded(context.Context, int64, int, string, time.Time) error {
+	return errors.New("store unavailable")
+}
+func (userStoreUnavailableRepoStub) MarkFailedRetryable(context.Context, int64, string, time.Time, time.Time) error {
+	return errors.New("store unavailable")
+}
+func (userStoreUnavailableRepoStub) DeleteExpired(context.Context, time.Time, int) (int64, error) {
+	return 0, errors.New("store unavailable")
+}
+
+type userMemoryIdempotencyRepoStub struct {
+	mu     sync.Mutex
+	nextID int64
+	data   map[string]*service.IdempotencyRecord
+}
+
+func newUserMemoryIdempotencyRepoStub() *userMemoryIdempotencyRepoStub {
+	return &userMemoryIdempotencyRepoStub{
+		nextID: 1,
+		data:   make(map[string]*service.IdempotencyRecord),
+	}
+}
+
+func (r *userMemoryIdempotencyRepoStub) key(scope, keyHash string) string {
+	return scope + "|" + keyHash
+}
+
+func (r *userMemoryIdempotencyRepoStub) clone(in *service.IdempotencyRecord) *service.IdempotencyRecord {
+	if in == nil {
+		return nil
+	}
+	out := *in
+	if in.LockedUntil != nil {
+		v := *in.LockedUntil
+		out.LockedUntil = &v
+	}
+	if in.ResponseBody != nil {
+		v := *in.ResponseBody
+		out.ResponseBody = &v
+	}
+	if in.ResponseStatus != nil {
+		v := *in.ResponseStatus
+		out.ResponseStatus = &v
+	}
+	if in.ErrorReason != nil {
+		v := *in.ErrorReason
+		out.ErrorReason = &v
+	}
+	return &out
+}
+
+func (r *userMemoryIdempotencyRepoStub) CreateProcessing(_ context.Context, record *service.IdempotencyRecord) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	k := r.key(record.Scope, record.IdempotencyKeyHash)
+	if _, ok := r.data[k]; ok {
+		return false, nil
+	}
+	cp := r.clone(record)
+	cp.ID = r.nextID
+	r.nextID++
+	r.data[k] = cp
+	record.ID = cp.ID
+	return true, nil
+}
+
+func (r *userMemoryIdempotencyRepoStub) GetByScopeAndKeyHash(_ context.Context, scope, keyHash string) (*service.IdempotencyRecord, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.clone(r.data[r.key(scope, keyHash)]), nil
+}
+
+func (r *userMemoryIdempotencyRepoStub) TryReclaim(_ context.Context, id int64, fromStatus string, now, newLockedUntil, newExpiresAt time.Time) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		if rec.Status != fromStatus {
+			return false, nil
+		}
+		if rec.LockedUntil != nil && rec.LockedUntil.After(now) {
+			return false, nil
+		}
+		rec.Status = service.IdempotencyStatusProcessing
+		rec.LockedUntil = &newLockedUntil
+		rec.ExpiresAt = newExpiresAt
+		rec.ErrorReason = nil
+		return true, nil
+	}
+	return false, nil
+}
+
+func (r *userMemoryIdempotencyRepoStub) ExtendProcessingLock(_ context.Context, id int64, requestFingerprint string, newLockedUntil, newExpiresAt time.Time) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		if rec.Status != service.IdempotencyStatusProcessing || rec.RequestFingerprint != requestFingerprint {
+			return false, nil
+		}
+		rec.LockedUntil = &newLockedUntil
+		rec.ExpiresAt = newExpiresAt
+		return true, nil
+	}
+	return false, nil
+}
+
+func (r *userMemoryIdempotencyRepoStub) MarkSucceeded(_ context.Context, id int64, responseStatus int, responseBody string, expiresAt time.Time) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		rec.Status = service.IdempotencyStatusSucceeded
+		rec.LockedUntil = nil
+		rec.ExpiresAt = expiresAt
+		rec.ResponseStatus = &responseStatus
+		rec.ResponseBody = &responseBody
+		rec.ErrorReason = nil
+		return nil
+	}
+	return nil
+}
+
+func (r *userMemoryIdempotencyRepoStub) MarkFailedRetryable(_ context.Context, id int64, errorReason string, lockedUntil, expiresAt time.Time) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		rec.Status = service.IdempotencyStatusFailedRetryable
+		rec.LockedUntil = &lockedUntil
+		rec.ExpiresAt = expiresAt
+		rec.ErrorReason = &errorReason
+		return nil
+	}
+	return nil
+}
+
+func (r *userMemoryIdempotencyRepoStub) DeleteExpired(_ context.Context, _ time.Time, _ int) (int64, error) {
+	return 0, nil
+}
+
+func withUserSubject(userID int64) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Set(string(middleware.ContextKeyUser), middleware.AuthSubject{UserID: userID})
+		c.Next()
+	}
+}
+
+func TestExecuteUserIdempotentJSONFallbackWithoutCoordinator(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	service.SetDefaultIdempotencyCoordinator(nil)
+
+	var executed int
+	router := gin.New()
+	router.Use(withUserSubject(1))
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeUserIdempotentJSON(c, "user.test.scope", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed++
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.Equal(t, 1, executed)
+}
+
+func TestExecuteUserIdempotentJSONFailCloseOnStoreUnavailable(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	service.SetDefaultIdempotencyCoordinator(service.NewIdempotencyCoordinator(userStoreUnavailableRepoStub{}, service.DefaultIdempotencyConfig()))
+	t.Cleanup(func() {
+		service.SetDefaultIdempotencyCoordinator(nil)
+	})
+
+	var executed int
+	router := gin.New()
+	router.Use(withUserSubject(2))
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeUserIdempotentJSON(c, "user.test.scope", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed++
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Idempotency-Key", "k1")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusServiceUnavailable, rec.Code)
+	require.Equal(t, 0, executed)
+}
+
+func TestExecuteUserIdempotentJSONConcurrentRetrySingleSideEffectAndReplay(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	repo := newUserMemoryIdempotencyRepoStub()
+	cfg := service.DefaultIdempotencyConfig()
+	cfg.ProcessingTimeout = 2 * time.Second
+	service.SetDefaultIdempotencyCoordinator(service.NewIdempotencyCoordinator(repo, cfg))
+	t.Cleanup(func() {
+		service.SetDefaultIdempotencyCoordinator(nil)
+	})
+
+	var executed atomic.Int32
+	router := gin.New()
+	router.Use(withUserSubject(3))
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeUserIdempotentJSON(c, "user.test.scope", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed.Add(1)
+			time.Sleep(80 * time.Millisecond)
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	call := func() (int, http.Header) {
+		req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Idempotency-Key", "same-user-key")
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+		return rec.Code, rec.Header()
+	}
+
+	var status1, status2 int
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() { defer wg.Done(); status1, _ = call() }()
+	go func() { defer wg.Done(); status2, _ = call() }()
+	wg.Wait()
+
+	require.Contains(t, []int{http.StatusOK, http.StatusConflict}, status1)
+	require.Contains(t, []int{http.StatusOK, http.StatusConflict}, status2)
+	require.Equal(t, int32(1), executed.Load())
+
+	status3, headers3 := call()
+	require.Equal(t, http.StatusOK, status3)
+	require.Equal(t, "true", headers3.Get("X-Idempotency-Replayed"))
+	require.Equal(t, int32(1), executed.Load())
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/logging.go

@@ -0,0 +1,19 @@
+package handler
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func requestLogger(c *gin.Context, component string, fields ...zap.Field) *zap.Logger {
+	base := logger.L()
+	if c != nil && c.Request != nil {
+		base = logger.FromContext(c.Request.Context())
+	}
+
+	if component != "" {
+		fields = append([]zap.Field{zap.String("component", component)}, fields...)
+	}
+	return base.With(fields...)
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/openai_chat_completions.go

@@ -0,0 +1,286 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"time"
+
+	pkghttputil "github.com/Wei-Shaw/sub2api/internal/pkg/httputil"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/tidwall/gjson"
+	"go.uber.org/zap"
+)
+
+// ChatCompletions handles OpenAI Chat Completions API requests.
+// POST /v1/chat/completions
+func (h *OpenAIGatewayHandler) ChatCompletions(c *gin.Context) {
+	streamStarted := false
+	defer h.recoverResponsesPanic(c, &streamStarted)
+
+	requestStart := time.Now()
+
+	apiKey, ok := middleware2.GetAPIKeyFromContext(c)
+	if !ok {
+		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
+		return
+	}
+
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		h.errorResponse(c, http.StatusInternalServerError, "api_error", "User context not found")
+		return
+	}
+	reqLog := requestLogger(
+		c,
+		"handler.openai_gateway.chat_completions",
+		zap.Int64("user_id", subject.UserID),
+		zap.Int64("api_key_id", apiKey.ID),
+		zap.Any("group_id", apiKey.GroupID),
+	)
+
+	if !h.ensureResponsesDependencies(c, reqLog) {
+		return
+	}
+
+	body, err := pkghttputil.ReadRequestBodyWithPrealloc(c.Request)
+	if err != nil {
+		if maxErr, ok := extractMaxBytesError(err); ok {
+			h.errorResponse(c, http.StatusRequestEntityTooLarge, "invalid_request_error", buildBodyTooLargeMessage(maxErr.Limit))
+			return
+		}
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Failed to read request body")
+		return
+	}
+	if len(body) == 0 {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Request body is empty")
+		return
+	}
+
+	if !gjson.ValidBytes(body) {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Failed to parse request body")
+		return
+	}
+
+	modelResult := gjson.GetBytes(body, "model")
+	if !modelResult.Exists() || modelResult.Type != gjson.String || modelResult.String() == "" {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "model is required")
+		return
+	}
+	reqModel := modelResult.String()
+	reqStream := gjson.GetBytes(body, "stream").Bool()
+
+	reqLog = reqLog.With(zap.String("model", reqModel), zap.Bool("stream", reqStream))
+
+	setOpsRequestContext(c, reqModel, reqStream, body)
+
+	if h.errorPassthroughService != nil {
+		service.BindErrorPassthroughService(c, h.errorPassthroughService)
+	}
+
+	subscription, _ := middleware2.GetSubscriptionFromContext(c)
+
+	service.SetOpsLatencyMs(c, service.OpsAuthLatencyMsKey, time.Since(requestStart).Milliseconds())
+	routingStart := time.Now()
+
+	userReleaseFunc, acquired := h.acquireResponsesUserSlot(c, subject.UserID, subject.Concurrency, reqStream, &streamStarted, reqLog)
+	if !acquired {
+		return
+	}
+	if userReleaseFunc != nil {
+		defer userReleaseFunc()
+	}
+
+	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
+		reqLog.Info("openai_chat_completions.billing_eligibility_check_failed", zap.Error(err))
+		status, code, message := billingErrorDetails(err)
+		h.handleStreamingAwareError(c, status, code, message, streamStarted)
+		return
+	}
+
+	sessionHash := h.gatewayService.GenerateSessionHash(c, body)
+	promptCacheKey := h.gatewayService.ExtractSessionID(c, body)
+
+	maxAccountSwitches := h.maxAccountSwitches
+	switchCount := 0
+	failedAccountIDs := make(map[int64]struct{})
+	sameAccountRetryCount := make(map[int64]int)
+	var lastFailoverErr *service.UpstreamFailoverError
+
+	for {
+		c.Set("openai_chat_completions_fallback_model", "")
+		reqLog.Debug("openai_chat_completions.account_selecting", zap.Int("excluded_account_count", len(failedAccountIDs)))
+		selection, scheduleDecision, err := h.gatewayService.SelectAccountWithScheduler(
+			c.Request.Context(),
+			apiKey.GroupID,
+			"",
+			sessionHash,
+			reqModel,
+			failedAccountIDs,
+			service.OpenAIUpstreamTransportAny,
+		)
+		if err != nil {
+			reqLog.Warn("openai_chat_completions.account_select_failed",
+				zap.Error(err),
+				zap.Int("excluded_account_count", len(failedAccountIDs)),
+			)
+			if len(failedAccountIDs) == 0 {
+				defaultModel := ""
+				if apiKey.Group != nil {
+					defaultModel = apiKey.Group.DefaultMappedModel
+				}
+				if defaultModel != "" && defaultModel != reqModel {
+					reqLog.Info("openai_chat_completions.fallback_to_default_model",
+						zap.String("default_mapped_model", defaultModel),
+					)
+					selection, scheduleDecision, err = h.gatewayService.SelectAccountWithScheduler(
+						c.Request.Context(),
+						apiKey.GroupID,
+						"",
+						sessionHash,
+						defaultModel,
+						failedAccountIDs,
+						service.OpenAIUpstreamTransportAny,
+					)
+					if err == nil && selection != nil {
+						c.Set("openai_chat_completions_fallback_model", defaultModel)
+					}
+				}
+				if err != nil {
+					h.handleStreamingAwareError(c, http.StatusServiceUnavailable, "api_error", "Service temporarily unavailable", streamStarted)
+					return
+				}
+			} else {
+				if lastFailoverErr != nil {
+					h.handleFailoverExhausted(c, lastFailoverErr, streamStarted)
+				} else {
+					h.handleStreamingAwareError(c, http.StatusBadGateway, "api_error", "Upstream request failed", streamStarted)
+				}
+				return
+			}
+		}
+		if selection == nil || selection.Account == nil {
+			h.handleStreamingAwareError(c, http.StatusServiceUnavailable, "api_error", "No available accounts", streamStarted)
+			return
+		}
+		account := selection.Account
+		sessionHash = ensureOpenAIPoolModeSessionHash(sessionHash, account)
+		reqLog.Debug("openai_chat_completions.account_selected", zap.Int64("account_id", account.ID), zap.String("account_name", account.Name))
+		_ = scheduleDecision
+		setOpsSelectedAccount(c, account.ID, account.Platform)
+
+		accountReleaseFunc, acquired := h.acquireResponsesAccountSlot(c, apiKey.GroupID, sessionHash, selection, reqStream, &streamStarted, reqLog)
+		if !acquired {
+			return
+		}
+
+		service.SetOpsLatencyMs(c, service.OpsRoutingLatencyMsKey, time.Since(routingStart).Milliseconds())
+		forwardStart := time.Now()
+
+		defaultMappedModel := c.GetString("openai_chat_completions_fallback_model")
+		result, err := h.gatewayService.ForwardAsChatCompletions(c.Request.Context(), c, account, body, promptCacheKey, defaultMappedModel)
+
+		forwardDurationMs := time.Since(forwardStart).Milliseconds()
+		if accountReleaseFunc != nil {
+			accountReleaseFunc()
+		}
+		upstreamLatencyMs, _ := getContextInt64(c, service.OpsUpstreamLatencyMsKey)
+		responseLatencyMs := forwardDurationMs
+		if upstreamLatencyMs > 0 && forwardDurationMs > upstreamLatencyMs {
+			responseLatencyMs = forwardDurationMs - upstreamLatencyMs
+		}
+		service.SetOpsLatencyMs(c, service.OpsResponseLatencyMsKey, responseLatencyMs)
+		if err == nil && result != nil && result.FirstTokenMs != nil {
+			service.SetOpsLatencyMs(c, service.OpsTimeToFirstTokenMsKey, int64(*result.FirstTokenMs))
+		}
+		if err != nil {
+			var failoverErr *service.UpstreamFailoverError
+			if errors.As(err, &failoverErr) {
+				h.gatewayService.ReportOpenAIAccountScheduleResult(account.ID, false, nil)
+				// Pool mode: retry on the same account
+				if failoverErr.RetryableOnSameAccount {
+					retryLimit := account.GetPoolModeRetryCount()
+					if sameAccountRetryCount[account.ID] < retryLimit {
+						sameAccountRetryCount[account.ID]++
+						reqLog.Warn("openai_chat_completions.pool_mode_same_account_retry",
+							zap.Int64("account_id", account.ID),
+							zap.Int("upstream_status", failoverErr.StatusCode),
+							zap.Int("retry_limit", retryLimit),
+							zap.Int("retry_count", sameAccountRetryCount[account.ID]),
+						)
+						select {
+						case <-c.Request.Context().Done():
+							return
+						case <-time.After(sameAccountRetryDelay):
+						}
+						continue
+					}
+				}
+				h.gatewayService.RecordOpenAIAccountSwitch()
+				failedAccountIDs[account.ID] = struct{}{}
+				lastFailoverErr = failoverErr
+				if switchCount >= maxAccountSwitches {
+					h.handleFailoverExhausted(c, failoverErr, streamStarted)
+					return
+				}
+				switchCount++
+				reqLog.Warn("openai_chat_completions.upstream_failover_switching",
+					zap.Int64("account_id", account.ID),
+					zap.Int("upstream_status", failoverErr.StatusCode),
+					zap.Int("switch_count", switchCount),
+					zap.Int("max_switches", maxAccountSwitches),
+				)
+				continue
+			}
+			h.gatewayService.ReportOpenAIAccountScheduleResult(account.ID, false, nil)
+			wroteFallback := h.ensureForwardErrorResponse(c, streamStarted)
+			reqLog.Warn("openai_chat_completions.forward_failed",
+				zap.Int64("account_id", account.ID),
+				zap.Bool("fallback_error_response_written", wroteFallback),
+				zap.Error(err),
+			)
+			return
+		}
+		if result != nil {
+			h.gatewayService.ReportOpenAIAccountScheduleResult(account.ID, true, result.FirstTokenMs)
+		} else {
+			h.gatewayService.ReportOpenAIAccountScheduleResult(account.ID, true, nil)
+		}
+
+		userAgent := c.GetHeader("User-Agent")
+		clientIP := ip.GetClientIP(c)
+
+		h.submitUsageRecordTask(func(ctx context.Context) {
+			if err := h.gatewayService.RecordUsage(ctx, &service.OpenAIRecordUsageInput{
+				Result:           result,
+				APIKey:           apiKey,
+				User:             apiKey.User,
+				Account:          account,
+				Subscription:     subscription,
+				InboundEndpoint:  GetInboundEndpoint(c),
+				UpstreamEndpoint: GetUpstreamEndpoint(c, account.Platform),
+				UserAgent:        userAgent,
+				IPAddress:        clientIP,
+				APIKeyService:    h.apiKeyService,
+			}); err != nil {
+				logger.L().With(
+					zap.String("component", "handler.openai_gateway.chat_completions"),
+					zap.Int64("user_id", subject.UserID),
+					zap.Int64("api_key_id", apiKey.ID),
+					zap.Any("group_id", apiKey.GroupID),
+					zap.String("model", reqModel),
+					zap.Int64("account_id", account.ID),
+				).Error("openai_chat_completions.record_usage_failed", zap.Error(err))
+			}
+		})
+		reqLog.Debug("openai_chat_completions.request_completed",
+			zap.Int64("account_id", account.ID),
+			zap.Int("switch_count", switchCount),
+		)
+		return
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/openai_gateway_compact_log_test.go

@@ -0,0 +1,192 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+var handlerStructuredLogCaptureMu sync.Mutex
+
+type handlerInMemoryLogSink struct {
+	mu     sync.Mutex
+	events []*logger.LogEvent
+}
+
+func (s *handlerInMemoryLogSink) WriteLogEvent(event *logger.LogEvent) {
+	if event == nil {
+		return
+	}
+	cloned := *event
+	if event.Fields != nil {
+		cloned.Fields = make(map[string]any, len(event.Fields))
+		for k, v := range event.Fields {
+			cloned.Fields[k] = v
+		}
+	}
+	s.mu.Lock()
+	s.events = append(s.events, &cloned)
+	s.mu.Unlock()
+}
+
+func (s *handlerInMemoryLogSink) ContainsMessageAtLevel(substr, level string) bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	wantLevel := strings.ToLower(strings.TrimSpace(level))
+	for _, ev := range s.events {
+		if ev == nil {
+			continue
+		}
+		if strings.Contains(ev.Message, substr) && strings.ToLower(strings.TrimSpace(ev.Level)) == wantLevel {
+			return true
+		}
+	}
+	return false
+}
+
+func (s *handlerInMemoryLogSink) ContainsFieldValue(field, substr string) bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	for _, ev := range s.events {
+		if ev == nil || ev.Fields == nil {
+			continue
+		}
+		if v, ok := ev.Fields[field]; ok && strings.Contains(fmt.Sprint(v), substr) {
+			return true
+		}
+	}
+	return false
+}
+
+func captureHandlerStructuredLog(t *testing.T) (*handlerInMemoryLogSink, func()) {
+	t.Helper()
+	handlerStructuredLogCaptureMu.Lock()
+
+	err := logger.Init(logger.InitOptions{
+		Level:       "debug",
+		Format:      "json",
+		ServiceName: "sub2api",
+		Environment: "test",
+		Output: logger.OutputOptions{
+			ToStdout: true,
+			ToFile:   false,
+		},
+		Sampling: logger.SamplingOptions{Enabled: false},
+	})
+	require.NoError(t, err)
+
+	sink := &handlerInMemoryLogSink{}
+	logger.SetSink(sink)
+	return sink, func() {
+		logger.SetSink(nil)
+		handlerStructuredLogCaptureMu.Unlock()
+	}
+}
+
+func TestIsOpenAIRemoteCompactPath(t *testing.T) {
+	require.False(t, isOpenAIRemoteCompactPath(nil))
+
+	gin.SetMode(gin.TestMode)
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/responses/compact", nil)
+	require.True(t, isOpenAIRemoteCompactPath(c))
+
+	c.Request = httptest.NewRequest(http.MethodPost, "/responses/compact/", nil)
+	require.True(t, isOpenAIRemoteCompactPath(c))
+
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/responses", nil)
+	require.False(t, isOpenAIRemoteCompactPath(c))
+}
+
+func TestLogOpenAIRemoteCompactOutcome_Succeeded(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	logSink, restore := captureHandlerStructuredLog(t)
+	defer restore()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/responses/compact", nil)
+	c.Request.Header.Set("User-Agent", "codex_cli_rs/0.104.0")
+	c.Set(opsModelKey, "gpt-5.3-codex")
+	c.Set(opsAccountIDKey, int64(123))
+	c.Header("x-request-id", "rid-compact-ok")
+	c.Status(http.StatusOK)
+
+	h := &OpenAIGatewayHandler{}
+	h.logOpenAIRemoteCompactOutcome(c, time.Now().Add(-8*time.Millisecond))
+
+	require.True(t, logSink.ContainsMessageAtLevel("codex.remote_compact.succeeded", "info"))
+	require.True(t, logSink.ContainsFieldValue("compact_outcome", "succeeded"))
+	require.True(t, logSink.ContainsFieldValue("status_code", "200"))
+	require.True(t, logSink.ContainsFieldValue("path", "/v1/responses/compact"))
+	require.True(t, logSink.ContainsFieldValue("request_model", "gpt-5.3-codex"))
+	require.True(t, logSink.ContainsFieldValue("account_id", "123"))
+	require.True(t, logSink.ContainsFieldValue("upstream_request_id", "rid-compact-ok"))
+}
+
+func TestLogOpenAIRemoteCompactOutcome_Failed(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	logSink, restore := captureHandlerStructuredLog(t)
+	defer restore()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/responses/compact", nil)
+	c.Request.Header.Set("User-Agent", "codex_cli_rs/0.104.0")
+	c.Status(http.StatusBadGateway)
+
+	h := &OpenAIGatewayHandler{}
+	h.logOpenAIRemoteCompactOutcome(c, time.Now())
+
+	require.True(t, logSink.ContainsMessageAtLevel("codex.remote_compact.failed", "warn"))
+	require.True(t, logSink.ContainsFieldValue("compact_outcome", "failed"))
+	require.True(t, logSink.ContainsFieldValue("status_code", "502"))
+	require.True(t, logSink.ContainsFieldValue("path", "/responses/compact"))
+}
+
+func TestLogOpenAIRemoteCompactOutcome_NonCompactSkips(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	logSink, restore := captureHandlerStructuredLog(t)
+	defer restore()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/responses", nil)
+	c.Status(http.StatusOK)
+
+	h := &OpenAIGatewayHandler{}
+	h.logOpenAIRemoteCompactOutcome(c, time.Now())
+
+	require.False(t, logSink.ContainsMessageAtLevel("codex.remote_compact.succeeded", "info"))
+	require.False(t, logSink.ContainsMessageAtLevel("codex.remote_compact.failed", "warn"))
+}
+
+func TestOpenAIResponses_CompactUnauthorizedLogsFailed(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	logSink, restore := captureHandlerStructuredLog(t)
+	defer restore()
+
+	rec := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(rec)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/responses/compact", strings.NewReader(`{"model":"gpt-5.3-codex"}`))
+	c.Request.Header.Set("Content-Type", "application/json")
+	c.Request.Header.Set("User-Agent", "codex_cli_rs/0.104.0")
+
+	h := &OpenAIGatewayHandler{}
+	h.Responses(c)
+
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+	require.True(t, logSink.ContainsMessageAtLevel("codex.remote_compact.failed", "warn"))
+	require.True(t, logSink.ContainsFieldValue("status_code", "401"))
+	require.True(t, logSink.ContainsFieldValue("path", "/v1/responses/compact"))
+}

llm-gateway-competitors/sub2api-tar/backend/internal/handler/openai_gateway_endpoint_normalization_test.go

@@ -0,0 +1,56 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+// TestOpenAIUpstreamEndpoint_ViaGetUpstreamEndpoint verifies that the
+// unified GetUpstreamEndpoint helper produces the same results as the
+// former normalizedOpenAIUpstreamEndpoint for OpenAI platform requests.
+func TestOpenAIUpstreamEndpoint_ViaGetUpstreamEndpoint(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	tests := []struct {
+		name string
+		path string
+		want string
+	}{
+		{
+			name: "responses root maps to responses upstream",
+			path: "/v1/responses",
+			want: EndpointResponses,
+		},
+		{
+			name: "responses compact keeps compact suffix",
+			path: "/openai/v1/responses/compact",
+			want: "/v1/responses/compact",
+		},
+		{
+			name: "responses nested suffix preserved",
+			path: "/openai/v1/responses/compact/detail",
+			want: "/v1/responses/compact/detail",
+		},
+		{
+			name: "non responses path uses platform fallback",
+			path: "/v1/messages",
+			want: EndpointResponses,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rec := httptest.NewRecorder()
+			c, _ := gin.CreateTestContext(rec)
+			c.Request = httptest.NewRequest(http.MethodPost, tt.path, nil)
+
+			got := GetUpstreamEndpoint(c, service.PlatformOpenAI)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}