first commit

backend/internal/handler/admin/antigravity_oauth_handler.go

@@ -0,0 +1,67 @@
+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)
+}

backend/internal/handler/admin/dashboard_handler.go

@@ -0,0 +1,397 @@
+package admin
+
+import (
+	"errors"
+	"strconv"
+	"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, stream
+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 stream *bool
+
+	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 streamStr := c.Query("stream"); streamStr != "" {
+		if streamVal, err := strconv.ParseBool(streamStr); err == nil {
+			stream = &streamVal
+		}
+	}
+
+	trend, err := h.dashboardService.GetUsageTrendWithFilters(c.Request.Context(), startTime, endTime, granularity, userID, apiKeyID, accountID, groupID, model, stream)
+	if err != nil {
+		response.Error(c, 500, "Failed to get usage trend")
+		return
+	}
+
+	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, stream
+func (h *DashboardHandler) GetModelStats(c *gin.Context) {
+	startTime, endTime := parseTimeRange(c)
+
+	// Parse optional filter params
+	var userID, apiKeyID, accountID, groupID int64
+	var stream *bool
+
+	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 streamStr := c.Query("stream"); streamStr != "" {
+		if streamVal, err := strconv.ParseBool(streamStr); err == nil {
+			stream = &streamVal
+		}
+	}
+
+	stats, err := h.dashboardService.GetModelStatsWithFilters(c.Request.Context(), startTime, endTime, userID, apiKeyID, accountID, groupID, stream)
+	if err != nil {
+		response.Error(c, 500, "Failed to get model statistics")
+		return
+	}
+
+	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"),
+	})
+}
+
+// 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, err := h.dashboardService.GetAPIKeyUsageTrend(c.Request.Context(), startTime, endTime, granularity, limit)
+	if err != nil {
+		response.Error(c, 500, "Failed to get API key usage trend")
+		return
+	}
+
+	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, err := h.dashboardService.GetUserUsageTrend(c.Request.Context(), startTime, endTime, granularity, limit)
+	if err != nil {
+		response.Error(c, 500, "Failed to get user usage trend")
+		return
+	}
+
+	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"`
+}
+
+// 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
+	}
+
+	if len(req.UserIDs) == 0 {
+		response.Success(c, gin.H{"stats": map[string]any{}})
+		return
+	}
+
+	stats, err := h.dashboardService.GetBatchUserUsageStats(c.Request.Context(), req.UserIDs)
+	if err != nil {
+		response.Error(c, 500, "Failed to get user usage stats")
+		return
+	}
+
+	response.Success(c, gin.H{"stats": stats})
+}
+
+// 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
+	}
+
+	if len(req.APIKeyIDs) == 0 {
+		response.Success(c, gin.H{"stats": map[string]any{}})
+		return
+	}
+
+	stats, err := h.dashboardService.GetBatchAPIKeyUsageStats(c.Request.Context(), req.APIKeyIDs)
+	if err != nil {
+		response.Error(c, 500, "Failed to get API key usage stats")
+		return
+	}
+
+	response.Success(c, gin.H{"stats": stats})
+}

backend/internal/handler/admin/gemini_oauth_handler.go

@@ -0,0 +1,142 @@
+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") {
+			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)
+}

backend/internal/handler/admin/group_handler.go

@@ -0,0 +1,274 @@
+package admin
+
+import (
+	"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
+}
+
+// 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"`
+	RateMultiplier   float64  `json:"rate_multiplier"`
+	IsExclusive      bool     `json:"is_exclusive"`
+	SubscriptionType string   `json:"subscription_type" binding:"omitempty,oneof=standard subscription"`
+	DailyLimitUSD    *float64 `json:"daily_limit_usd"`
+	WeeklyLimitUSD   *float64 `json:"weekly_limit_usd"`
+	MonthlyLimitUSD  *float64 `json:"monthly_limit_usd"`
+	// 图片生成计费配置（antigravity 和 gemini 平台使用，负数表示清除配置）
+	ImagePrice1K    *float64 `json:"image_price_1k"`
+	ImagePrice2K    *float64 `json:"image_price_2k"`
+	ImagePrice4K    *float64 `json:"image_price_4k"`
+	ClaudeCodeOnly  bool     `json:"claude_code_only"`
+	FallbackGroupID *int64   `json:"fallback_group_id"`
+}
+
+// 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"`
+	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    *float64 `json:"daily_limit_usd"`
+	WeeklyLimitUSD   *float64 `json:"weekly_limit_usd"`
+	MonthlyLimitUSD  *float64 `json:"monthly_limit_usd"`
+	// 图片生成计费配置（antigravity 和 gemini 平台使用，负数表示清除配置）
+	ImagePrice1K    *float64 `json:"image_price_1k"`
+	ImagePrice2K    *float64 `json:"image_price_2k"`
+	ImagePrice4K    *float64 `json:"image_price_4k"`
+	ClaudeCodeOnly  *bool    `json:"claude_code_only"`
+	FallbackGroupID *int64   `json:"fallback_group_id"`
+}
+
+// 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.Group, 0, len(groups))
+	for i := range groups {
+		outGroups = append(outGroups, *dto.GroupFromService(&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.Group, 0, len(groups))
+	for i := range groups {
+		outGroups = append(outGroups, *dto.GroupFromService(&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.GroupFromService(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,
+		WeeklyLimitUSD:   req.WeeklyLimitUSD,
+		MonthlyLimitUSD:  req.MonthlyLimitUSD,
+		ImagePrice1K:     req.ImagePrice1K,
+		ImagePrice2K:     req.ImagePrice2K,
+		ImagePrice4K:     req.ImagePrice4K,
+		ClaudeCodeOnly:   req.ClaudeCodeOnly,
+		FallbackGroupID:  req.FallbackGroupID,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.GroupFromService(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,
+		WeeklyLimitUSD:   req.WeeklyLimitUSD,
+		MonthlyLimitUSD:  req.MonthlyLimitUSD,
+		ImagePrice1K:     req.ImagePrice1K,
+		ImagePrice2K:     req.ImagePrice2K,
+		ImagePrice4K:     req.ImagePrice4K,
+		ClaudeCodeOnly:   req.ClaudeCodeOnly,
+		FallbackGroupID:  req.FallbackGroupID,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.GroupFromService(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)
+}

backend/internal/handler/admin/openai_oauth_handler.go

@@ -0,0 +1,229 @@
+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"
+)
+
+// OpenAIOAuthHandler handles OpenAI OAuth-related operations
+type OpenAIOAuthHandler struct {
+	openaiOAuthService *service.OpenAIOAuthService
+	adminService       service.AdminService
+}
+
+// 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)
+	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"`
+	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,
+		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" binding:"required"`
+	ProxyID      *int64 `json:"proxy_id"`
+}
+
+// RefreshToken refreshes an OpenAI OAuth token
+// POST /api/v1/admin/openai/refresh-token
+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
+	}
+
+	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()
+		}
+	}
+
+	tokenInfo, err := h.openaiOAuthService.RefreshToken(c.Request.Context(), req.RefreshToken, proxyURL)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, tokenInfo)
+}
+
+// RefreshAccountToken refreshes token for a specific OpenAI account
+// POST /api/v1/admin/openai/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
+	}
+
+	// Ensure account is OpenAI platform
+	if !account.IsOpenAI() {
+		response.BadRequest(c, "Account is not an OpenAI account")
+		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 OAuth account from token info
+// POST /api/v1/admin/openai/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"`
+		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,
+		RedirectURI: req.RedirectURI,
+		ProxyID:     req.ProxyID,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Build credentials from token info
+	credentials := h.openaiOAuthService.BuildAccountCredentials(tokenInfo)
+
+	// Use email as default name if not provided
+	name := req.Name
+	if name == "" && tokenInfo.Email != "" {
+		name = tokenInfo.Email
+	}
+	if name == "" {
+		name = "OpenAI OAuth Account"
+	}
+
+	// Create account
+	account, err := h.adminService.CreateAccount(c.Request.Context(), &service.CreateAccountInput{
+		Name:        name,
+		Platform:    "openai",
+		Type:        "oauth",
+		Credentials: credentials,
+		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))
+}

backend/internal/handler/admin/ops_alerts_handler.go

@@ -0,0 +1,602 @@
+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",
+}
+
+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":
+		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)
+}

backend/internal/handler/admin/ops_dashboard_handler.go

@@ -0,0 +1,243 @@
+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"
+)
+
+// 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)
+}
+
+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)
+}

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

backend/internal/handler/admin/ops_realtime_handler.go

@@ -0,0 +1,213 @@
+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)
+}
+
+// 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,
+	})
+}

backend/internal/handler/admin/ops_settings_handler.go

@@ -0,0 +1,194 @@
+package admin
+
+import (
+	"net/http"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"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)
+}
+
+// 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)
+}

backend/internal/handler/admin/ops_ws_handler.go

@@ -0,0 +1,771 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"math"
+	"net"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"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 wsConnCountByIP sync.Map // map[string]*atomic.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 {
+			log.Printf("[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 {
+		log.Printf("[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) {
+		log.Printf("[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) {
+			log.Printf("[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 {
+		log.Printf("[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
+	}
+
+	v, _ := wsConnCountByIP.LoadOrStore(clientIP, &atomic.Int32{})
+	counter, ok := v.(*atomic.Int32)
+	if !ok {
+		return false
+	}
+
+	for {
+		current := counter.Load()
+		if current >= limit {
+			return false
+		}
+		if counter.CompareAndSwap(current, current+1) {
+			return true
+		}
+	}
+}
+
+func releaseOpsWSIPSlot(clientIP string) {
+	if strings.TrimSpace(clientIP) == "" {
+		return
+	}
+
+	v, ok := wsConnCountByIP.Load(clientIP)
+	if !ok {
+		return
+	}
+	counter, ok := v.(*atomic.Int32)
+	if !ok {
+		return
+	}
+	next := counter.Add(-1)
+	if next <= 0 {
+		// Best-effort cleanup; safe even if a new slot was acquired concurrently.
+		wsConnCountByIP.Delete(clientIP)
+	}
+}
+
+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 {
+			log.Printf("[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) {
+					log.Printf("[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 {
+				log.Printf("[OpsWS] write failed: %v", err)
+				cancel()
+				closeConn()
+				wg.Wait()
+				return
+			}
+
+		case <-pingTicker.C:
+			if err := writeWithTimeout(websocket.PingMessage, nil); err != nil {
+				log.Printf("[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 {
+			log.Printf("[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 {
+			log.Printf("[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:
+			log.Printf("[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 {
+			log.Printf("[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 {
+			log.Printf("[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]
+}

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

backend/internal/handler/admin/proxy_handler.go

@@ -0,0 +1,348 @@
+package admin
+
+import (
+	"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.ProxyWithAccountCount, 0, len(proxies))
+	for i := range proxies {
+		out = append(out, *dto.ProxyWithAccountCountFromService(&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.ProxyWithAccountCount, 0, len(proxies))
+		for i := range proxies {
+			out = append(out, *dto.ProxyWithAccountCountFromService(&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.Proxy, 0, len(proxies))
+	for i := range proxies {
+		out = append(out, *dto.ProxyFromService(&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.ProxyFromService(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
+	}
+
+	proxy, err := h.adminService.CreateProxy(c.Request.Context(), &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 {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.ProxyFromService(proxy))
+}
+
+// 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.ProxyFromService(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)
+}
+
+// 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,
+	})
+}

backend/internal/handler/admin/redeem_handler.go

@@ -0,0 +1,244 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/csv"
+	"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"
+)
+
+// RedeemHandler handles admin redeem code management
+type RedeemHandler struct {
+	adminService service.AdminService
+}
+
+// NewRedeemHandler creates a new admin redeem handler
+func NewRedeemHandler(adminService service.AdminService) *RedeemHandler {
+	return &RedeemHandler{
+		adminService: adminService,
+	}
+}
+
+// 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"`
+	Value        float64 `json:"value" binding:"min=0"`
+	GroupID      *int64  `json:"group_id"`                                    // 订阅类型必填
+	ValidityDays int     `json:"validity_days" binding:"omitempty,max=36500"` // 订阅类型使用，默认30天，最大100年
+}
+
+// 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.RedeemCode, 0, len(codes))
+	for i := range codes {
+		out = append(out, *dto.RedeemCodeFromService(&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.RedeemCodeFromService(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
+	}
+
+	codes, err := h.adminService.GenerateRedeemCodes(c.Request.Context(), &service.GenerateRedeemCodesInput{
+		Count:        req.Count,
+		Type:         req.Type,
+		Value:        req.Value,
+		GroupID:      req.GroupID,
+		ValidityDays: req.ValidityDays,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.RedeemCode, 0, len(codes))
+	for i := range codes {
+		out = append(out, *dto.RedeemCodeFromService(&codes[i]))
+	}
+	response.Success(c, out)
+}
+
+// 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.RedeemCodeFromService(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_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)
+		}
+		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,
+			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())
+}

backend/internal/handler/admin/setting_handler.go

@@ -0,0 +1,721 @@
+package admin
+
+import (
+	"log"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"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"
+)
+
+// SettingHandler 系统设置处理器
+type SettingHandler struct {
+	settingService   *service.SettingService
+	emailService     *service.EmailService
+	turnstileService *service.TurnstileService
+	opsService       *service.OpsService
+}
+
+// NewSettingHandler 创建系统设置处理器
+func NewSettingHandler(settingService *service.SettingService, emailService *service.EmailService, turnstileService *service.TurnstileService, opsService *service.OpsService) *SettingHandler {
+	return &SettingHandler{
+		settingService:   settingService,
+		emailService:     emailService,
+		turnstileService: turnstileService,
+		opsService:       opsService,
+	}
+}
+
+// GetSettings 获取所有系统设置
+// GET /api/v1/admin/settings
+func (h *SettingHandler) GetSettings(c *gin.Context) {
+	settings, err := h.settingService.GetAllSettings(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Check if ops monitoring is enabled (respects config.ops.enabled)
+	opsEnabled := h.opsService != nil && h.opsService.IsMonitoringEnabled(c.Request.Context())
+
+	response.Success(c, dto.SystemSettings{
+		RegistrationEnabled:                  settings.RegistrationEnabled,
+		EmailVerifyEnabled:                   settings.EmailVerifyEnabled,
+		SMTPHost:                             settings.SMTPHost,
+		SMTPPort:                             settings.SMTPPort,
+		SMTPUsername:                         settings.SMTPUsername,
+		SMTPPasswordConfigured:               settings.SMTPPasswordConfigured,
+		SMTPFrom:                             settings.SMTPFrom,
+		SMTPFromName:                         settings.SMTPFromName,
+		SMTPUseTLS:                           settings.SMTPUseTLS,
+		TurnstileEnabled:                     settings.TurnstileEnabled,
+		TurnstileSiteKey:                     settings.TurnstileSiteKey,
+		TurnstileSecretKeyConfigured:         settings.TurnstileSecretKeyConfigured,
+		LinuxDoConnectEnabled:                settings.LinuxDoConnectEnabled,
+		LinuxDoConnectClientID:               settings.LinuxDoConnectClientID,
+		LinuxDoConnectClientSecretConfigured: settings.LinuxDoConnectClientSecretConfigured,
+		LinuxDoConnectRedirectURL:            settings.LinuxDoConnectRedirectURL,
+		SiteName:                             settings.SiteName,
+		SiteLogo:                             settings.SiteLogo,
+		SiteSubtitle:                         settings.SiteSubtitle,
+		APIBaseURL:                           settings.APIBaseURL,
+		ContactInfo:                          settings.ContactInfo,
+		DocURL:                               settings.DocURL,
+		HomeContent:                          settings.HomeContent,
+		DefaultConcurrency:                   settings.DefaultConcurrency,
+		DefaultBalance:                       settings.DefaultBalance,
+		EnableModelFallback:                  settings.EnableModelFallback,
+		FallbackModelAnthropic:               settings.FallbackModelAnthropic,
+		FallbackModelOpenAI:                  settings.FallbackModelOpenAI,
+		FallbackModelGemini:                  settings.FallbackModelGemini,
+		FallbackModelAntigravity:             settings.FallbackModelAntigravity,
+		EnableIdentityPatch:                  settings.EnableIdentityPatch,
+		IdentityPatchPrompt:                  settings.IdentityPatchPrompt,
+		OpsMonitoringEnabled:                 opsEnabled && settings.OpsMonitoringEnabled,
+		OpsRealtimeMonitoringEnabled:         settings.OpsRealtimeMonitoringEnabled,
+		OpsQueryModeDefault:                  settings.OpsQueryModeDefault,
+		OpsMetricsIntervalSeconds:            settings.OpsMetricsIntervalSeconds,
+	})
+}
+
+// UpdateSettingsRequest 更新设置请求
+type UpdateSettingsRequest struct {
+	// 注册设置
+	RegistrationEnabled bool `json:"registration_enabled"`
+	EmailVerifyEnabled  bool `json:"email_verify_enabled"`
+
+	// 邮件服务设置
+	SMTPHost     string `json:"smtp_host"`
+	SMTPPort     int    `json:"smtp_port"`
+	SMTPUsername string `json:"smtp_username"`
+	SMTPPassword string `json:"smtp_password"`
+	SMTPFrom     string `json:"smtp_from_email"`
+	SMTPFromName string `json:"smtp_from_name"`
+	SMTPUseTLS   bool   `json:"smtp_use_tls"`
+
+	// Cloudflare Turnstile 设置
+	TurnstileEnabled   bool   `json:"turnstile_enabled"`
+	TurnstileSiteKey   string `json:"turnstile_site_key"`
+	TurnstileSecretKey string `json:"turnstile_secret_key"`
+
+	// LinuxDo Connect OAuth 登录
+	LinuxDoConnectEnabled      bool   `json:"linuxdo_connect_enabled"`
+	LinuxDoConnectClientID     string `json:"linuxdo_connect_client_id"`
+	LinuxDoConnectClientSecret string `json:"linuxdo_connect_client_secret"`
+	LinuxDoConnectRedirectURL  string `json:"linuxdo_connect_redirect_url"`
+
+	// OEM设置
+	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"`
+
+	// 默认配置
+	DefaultConcurrency int     `json:"default_concurrency"`
+	DefaultBalance     float64 `json:"default_balance"`
+
+	// 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"`
+}
+
+// UpdateSettings 更新系统设置
+// PUT /api/v1/admin/settings
+func (h *SettingHandler) UpdateSettings(c *gin.Context) {
+	var req UpdateSettingsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	previousSettings, err := h.settingService.GetAllSettings(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// 验证参数
+	if req.DefaultConcurrency < 1 {
+		req.DefaultConcurrency = 1
+	}
+	if req.DefaultBalance < 0 {
+		req.DefaultBalance = 0
+	}
+	if req.SMTPPort <= 0 {
+		req.SMTPPort = 587
+	}
+
+	// Turnstile 参数验证
+	if req.TurnstileEnabled {
+		// 检查必填字段
+		if req.TurnstileSiteKey == "" {
+			response.BadRequest(c, "Turnstile Site Key is required when enabled")
+			return
+		}
+		// 如果未提供 secret key，使用已保存的值（留空保留当前值）
+		if req.TurnstileSecretKey == "" {
+			if previousSettings.TurnstileSecretKey == "" {
+				response.BadRequest(c, "Turnstile Secret Key is required when enabled")
+				return
+			}
+			req.TurnstileSecretKey = previousSettings.TurnstileSecretKey
+		}
+
+		// 当 site_key 或 secret_key 任一变化时验证（避免配置错误导致无法登录）
+		siteKeyChanged := previousSettings.TurnstileSiteKey != req.TurnstileSiteKey
+		secretKeyChanged := previousSettings.TurnstileSecretKey != req.TurnstileSecretKey
+		if siteKeyChanged || secretKeyChanged {
+			if err := h.turnstileService.ValidateSecretKey(c.Request.Context(), req.TurnstileSecretKey); err != nil {
+				response.ErrorFrom(c, err)
+				return
+			}
+		}
+	}
+
+	// LinuxDo Connect 参数验证
+	if req.LinuxDoConnectEnabled {
+		req.LinuxDoConnectClientID = strings.TrimSpace(req.LinuxDoConnectClientID)
+		req.LinuxDoConnectClientSecret = strings.TrimSpace(req.LinuxDoConnectClientSecret)
+		req.LinuxDoConnectRedirectURL = strings.TrimSpace(req.LinuxDoConnectRedirectURL)
+
+		if req.LinuxDoConnectClientID == "" {
+			response.BadRequest(c, "LinuxDo Client ID is required when enabled")
+			return
+		}
+		if req.LinuxDoConnectRedirectURL == "" {
+			response.BadRequest(c, "LinuxDo Redirect URL is required when enabled")
+			return
+		}
+		if err := config.ValidateAbsoluteHTTPURL(req.LinuxDoConnectRedirectURL); err != nil {
+			response.BadRequest(c, "LinuxDo Redirect URL must be an absolute http(s) URL")
+			return
+		}
+
+		// 如果未提供 client_secret，则保留现有值（如有）。
+		if req.LinuxDoConnectClientSecret == "" {
+			if previousSettings.LinuxDoConnectClientSecret == "" {
+				response.BadRequest(c, "LinuxDo Client Secret is required when enabled")
+				return
+			}
+			req.LinuxDoConnectClientSecret = previousSettings.LinuxDoConnectClientSecret
+		}
+	}
+
+	// Ops metrics collector interval validation (seconds).
+	if req.OpsMetricsIntervalSeconds != nil {
+		v := *req.OpsMetricsIntervalSeconds
+		if v < 60 {
+			v = 60
+		}
+		if v > 3600 {
+			v = 3600
+		}
+		req.OpsMetricsIntervalSeconds = &v
+	}
+
+	settings := &service.SystemSettings{
+		RegistrationEnabled:        req.RegistrationEnabled,
+		EmailVerifyEnabled:         req.EmailVerifyEnabled,
+		SMTPHost:                   req.SMTPHost,
+		SMTPPort:                   req.SMTPPort,
+		SMTPUsername:               req.SMTPUsername,
+		SMTPPassword:               req.SMTPPassword,
+		SMTPFrom:                   req.SMTPFrom,
+		SMTPFromName:               req.SMTPFromName,
+		SMTPUseTLS:                 req.SMTPUseTLS,
+		TurnstileEnabled:           req.TurnstileEnabled,
+		TurnstileSiteKey:           req.TurnstileSiteKey,
+		TurnstileSecretKey:         req.TurnstileSecretKey,
+		LinuxDoConnectEnabled:      req.LinuxDoConnectEnabled,
+		LinuxDoConnectClientID:     req.LinuxDoConnectClientID,
+		LinuxDoConnectClientSecret: req.LinuxDoConnectClientSecret,
+		LinuxDoConnectRedirectURL:  req.LinuxDoConnectRedirectURL,
+		SiteName:                   req.SiteName,
+		SiteLogo:                   req.SiteLogo,
+		SiteSubtitle:               req.SiteSubtitle,
+		APIBaseURL:                 req.APIBaseURL,
+		ContactInfo:                req.ContactInfo,
+		DocURL:                     req.DocURL,
+		HomeContent:                req.HomeContent,
+		DefaultConcurrency:         req.DefaultConcurrency,
+		DefaultBalance:             req.DefaultBalance,
+		EnableModelFallback:        req.EnableModelFallback,
+		FallbackModelAnthropic:     req.FallbackModelAnthropic,
+		FallbackModelOpenAI:        req.FallbackModelOpenAI,
+		FallbackModelGemini:        req.FallbackModelGemini,
+		FallbackModelAntigravity:   req.FallbackModelAntigravity,
+		EnableIdentityPatch:        req.EnableIdentityPatch,
+		IdentityPatchPrompt:        req.IdentityPatchPrompt,
+		OpsMonitoringEnabled: func() bool {
+			if req.OpsMonitoringEnabled != nil {
+				return *req.OpsMonitoringEnabled
+			}
+			return previousSettings.OpsMonitoringEnabled
+		}(),
+		OpsRealtimeMonitoringEnabled: func() bool {
+			if req.OpsRealtimeMonitoringEnabled != nil {
+				return *req.OpsRealtimeMonitoringEnabled
+			}
+			return previousSettings.OpsRealtimeMonitoringEnabled
+		}(),
+		OpsQueryModeDefault: func() string {
+			if req.OpsQueryModeDefault != nil {
+				return *req.OpsQueryModeDefault
+			}
+			return previousSettings.OpsQueryModeDefault
+		}(),
+		OpsMetricsIntervalSeconds: func() int {
+			if req.OpsMetricsIntervalSeconds != nil {
+				return *req.OpsMetricsIntervalSeconds
+			}
+			return previousSettings.OpsMetricsIntervalSeconds
+		}(),
+	}
+
+	if err := h.settingService.UpdateSettings(c.Request.Context(), settings); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	h.auditSettingsUpdate(c, previousSettings, settings, req)
+
+	// 重新获取设置返回
+	updatedSettings, err := h.settingService.GetAllSettings(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.SystemSettings{
+		RegistrationEnabled:                  updatedSettings.RegistrationEnabled,
+		EmailVerifyEnabled:                   updatedSettings.EmailVerifyEnabled,
+		SMTPHost:                             updatedSettings.SMTPHost,
+		SMTPPort:                             updatedSettings.SMTPPort,
+		SMTPUsername:                         updatedSettings.SMTPUsername,
+		SMTPPasswordConfigured:               updatedSettings.SMTPPasswordConfigured,
+		SMTPFrom:                             updatedSettings.SMTPFrom,
+		SMTPFromName:                         updatedSettings.SMTPFromName,
+		SMTPUseTLS:                           updatedSettings.SMTPUseTLS,
+		TurnstileEnabled:                     updatedSettings.TurnstileEnabled,
+		TurnstileSiteKey:                     updatedSettings.TurnstileSiteKey,
+		TurnstileSecretKeyConfigured:         updatedSettings.TurnstileSecretKeyConfigured,
+		LinuxDoConnectEnabled:                updatedSettings.LinuxDoConnectEnabled,
+		LinuxDoConnectClientID:               updatedSettings.LinuxDoConnectClientID,
+		LinuxDoConnectClientSecretConfigured: updatedSettings.LinuxDoConnectClientSecretConfigured,
+		LinuxDoConnectRedirectURL:            updatedSettings.LinuxDoConnectRedirectURL,
+		SiteName:                             updatedSettings.SiteName,
+		SiteLogo:                             updatedSettings.SiteLogo,
+		SiteSubtitle:                         updatedSettings.SiteSubtitle,
+		APIBaseURL:                           updatedSettings.APIBaseURL,
+		ContactInfo:                          updatedSettings.ContactInfo,
+		DocURL:                               updatedSettings.DocURL,
+		HomeContent:                          updatedSettings.HomeContent,
+		DefaultConcurrency:                   updatedSettings.DefaultConcurrency,
+		DefaultBalance:                       updatedSettings.DefaultBalance,
+		EnableModelFallback:                  updatedSettings.EnableModelFallback,
+		FallbackModelAnthropic:               updatedSettings.FallbackModelAnthropic,
+		FallbackModelOpenAI:                  updatedSettings.FallbackModelOpenAI,
+		FallbackModelGemini:                  updatedSettings.FallbackModelGemini,
+		FallbackModelAntigravity:             updatedSettings.FallbackModelAntigravity,
+		EnableIdentityPatch:                  updatedSettings.EnableIdentityPatch,
+		IdentityPatchPrompt:                  updatedSettings.IdentityPatchPrompt,
+		OpsMonitoringEnabled:                 updatedSettings.OpsMonitoringEnabled,
+		OpsRealtimeMonitoringEnabled:         updatedSettings.OpsRealtimeMonitoringEnabled,
+		OpsQueryModeDefault:                  updatedSettings.OpsQueryModeDefault,
+		OpsMetricsIntervalSeconds:            updatedSettings.OpsMetricsIntervalSeconds,
+	})
+}
+
+func (h *SettingHandler) auditSettingsUpdate(c *gin.Context, before *service.SystemSettings, after *service.SystemSettings, req UpdateSettingsRequest) {
+	if before == nil || after == nil {
+		return
+	}
+
+	changed := diffSettings(before, after, req)
+	if len(changed) == 0 {
+		return
+	}
+
+	subject, _ := middleware.GetAuthSubjectFromContext(c)
+	role, _ := middleware.GetUserRoleFromContext(c)
+	log.Printf("AUDIT: settings updated at=%s user_id=%d role=%s changed=%v",
+		time.Now().UTC().Format(time.RFC3339),
+		subject.UserID,
+		role,
+		changed,
+	)
+}
+
+func diffSettings(before *service.SystemSettings, after *service.SystemSettings, req UpdateSettingsRequest) []string {
+	changed := make([]string, 0, 20)
+	if before.RegistrationEnabled != after.RegistrationEnabled {
+		changed = append(changed, "registration_enabled")
+	}
+	if before.EmailVerifyEnabled != after.EmailVerifyEnabled {
+		changed = append(changed, "email_verify_enabled")
+	}
+	if before.SMTPHost != after.SMTPHost {
+		changed = append(changed, "smtp_host")
+	}
+	if before.SMTPPort != after.SMTPPort {
+		changed = append(changed, "smtp_port")
+	}
+	if before.SMTPUsername != after.SMTPUsername {
+		changed = append(changed, "smtp_username")
+	}
+	if req.SMTPPassword != "" {
+		changed = append(changed, "smtp_password")
+	}
+	if before.SMTPFrom != after.SMTPFrom {
+		changed = append(changed, "smtp_from_email")
+	}
+	if before.SMTPFromName != after.SMTPFromName {
+		changed = append(changed, "smtp_from_name")
+	}
+	if before.SMTPUseTLS != after.SMTPUseTLS {
+		changed = append(changed, "smtp_use_tls")
+	}
+	if before.TurnstileEnabled != after.TurnstileEnabled {
+		changed = append(changed, "turnstile_enabled")
+	}
+	if before.TurnstileSiteKey != after.TurnstileSiteKey {
+		changed = append(changed, "turnstile_site_key")
+	}
+	if req.TurnstileSecretKey != "" {
+		changed = append(changed, "turnstile_secret_key")
+	}
+	if before.LinuxDoConnectEnabled != after.LinuxDoConnectEnabled {
+		changed = append(changed, "linuxdo_connect_enabled")
+	}
+	if before.LinuxDoConnectClientID != after.LinuxDoConnectClientID {
+		changed = append(changed, "linuxdo_connect_client_id")
+	}
+	if req.LinuxDoConnectClientSecret != "" {
+		changed = append(changed, "linuxdo_connect_client_secret")
+	}
+	if before.LinuxDoConnectRedirectURL != after.LinuxDoConnectRedirectURL {
+		changed = append(changed, "linuxdo_connect_redirect_url")
+	}
+	if before.SiteName != after.SiteName {
+		changed = append(changed, "site_name")
+	}
+	if before.SiteLogo != after.SiteLogo {
+		changed = append(changed, "site_logo")
+	}
+	if before.SiteSubtitle != after.SiteSubtitle {
+		changed = append(changed, "site_subtitle")
+	}
+	if before.APIBaseURL != after.APIBaseURL {
+		changed = append(changed, "api_base_url")
+	}
+	if before.ContactInfo != after.ContactInfo {
+		changed = append(changed, "contact_info")
+	}
+	if before.DocURL != after.DocURL {
+		changed = append(changed, "doc_url")
+	}
+	if before.HomeContent != after.HomeContent {
+		changed = append(changed, "home_content")
+	}
+	if before.DefaultConcurrency != after.DefaultConcurrency {
+		changed = append(changed, "default_concurrency")
+	}
+	if before.DefaultBalance != after.DefaultBalance {
+		changed = append(changed, "default_balance")
+	}
+	if before.EnableModelFallback != after.EnableModelFallback {
+		changed = append(changed, "enable_model_fallback")
+	}
+	if before.FallbackModelAnthropic != after.FallbackModelAnthropic {
+		changed = append(changed, "fallback_model_anthropic")
+	}
+	if before.FallbackModelOpenAI != after.FallbackModelOpenAI {
+		changed = append(changed, "fallback_model_openai")
+	}
+	if before.FallbackModelGemini != after.FallbackModelGemini {
+		changed = append(changed, "fallback_model_gemini")
+	}
+	if before.FallbackModelAntigravity != after.FallbackModelAntigravity {
+		changed = append(changed, "fallback_model_antigravity")
+	}
+	if before.EnableIdentityPatch != after.EnableIdentityPatch {
+		changed = append(changed, "enable_identity_patch")
+	}
+	if before.IdentityPatchPrompt != after.IdentityPatchPrompt {
+		changed = append(changed, "identity_patch_prompt")
+	}
+	if before.OpsMonitoringEnabled != after.OpsMonitoringEnabled {
+		changed = append(changed, "ops_monitoring_enabled")
+	}
+	if before.OpsRealtimeMonitoringEnabled != after.OpsRealtimeMonitoringEnabled {
+		changed = append(changed, "ops_realtime_monitoring_enabled")
+	}
+	if before.OpsQueryModeDefault != after.OpsQueryModeDefault {
+		changed = append(changed, "ops_query_mode_default")
+	}
+	if before.OpsMetricsIntervalSeconds != after.OpsMetricsIntervalSeconds {
+		changed = append(changed, "ops_metrics_interval_seconds")
+	}
+	return changed
+}
+
+// TestSMTPRequest 测试SMTP连接请求
+type TestSMTPRequest struct {
+	SMTPHost     string `json:"smtp_host" binding:"required"`
+	SMTPPort     int    `json:"smtp_port"`
+	SMTPUsername string `json:"smtp_username"`
+	SMTPPassword string `json:"smtp_password"`
+	SMTPUseTLS   bool   `json:"smtp_use_tls"`
+}
+
+// TestSMTPConnection 测试SMTP连接
+// POST /api/v1/admin/settings/test-smtp
+func (h *SettingHandler) TestSMTPConnection(c *gin.Context) {
+	var req TestSMTPRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if req.SMTPPort <= 0 {
+		req.SMTPPort = 587
+	}
+
+	// 如果未提供密码，从数据库获取已保存的密码
+	password := req.SMTPPassword
+	if password == "" {
+		savedConfig, err := h.emailService.GetSMTPConfig(c.Request.Context())
+		if err == nil && savedConfig != nil {
+			password = savedConfig.Password
+		}
+	}
+
+	config := &service.SMTPConfig{
+		Host:     req.SMTPHost,
+		Port:     req.SMTPPort,
+		Username: req.SMTPUsername,
+		Password: password,
+		UseTLS:   req.SMTPUseTLS,
+	}
+
+	err := h.emailService.TestSMTPConnectionWithConfig(config)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "SMTP connection successful"})
+}
+
+// SendTestEmailRequest 发送测试邮件请求
+type SendTestEmailRequest struct {
+	Email        string `json:"email" binding:"required,email"`
+	SMTPHost     string `json:"smtp_host" binding:"required"`
+	SMTPPort     int    `json:"smtp_port"`
+	SMTPUsername string `json:"smtp_username"`
+	SMTPPassword string `json:"smtp_password"`
+	SMTPFrom     string `json:"smtp_from_email"`
+	SMTPFromName string `json:"smtp_from_name"`
+	SMTPUseTLS   bool   `json:"smtp_use_tls"`
+}
+
+// SendTestEmail 发送测试邮件
+// POST /api/v1/admin/settings/send-test-email
+func (h *SettingHandler) SendTestEmail(c *gin.Context) {
+	var req SendTestEmailRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if req.SMTPPort <= 0 {
+		req.SMTPPort = 587
+	}
+
+	// 如果未提供密码，从数据库获取已保存的密码
+	password := req.SMTPPassword
+	if password == "" {
+		savedConfig, err := h.emailService.GetSMTPConfig(c.Request.Context())
+		if err == nil && savedConfig != nil {
+			password = savedConfig.Password
+		}
+	}
+
+	config := &service.SMTPConfig{
+		Host:     req.SMTPHost,
+		Port:     req.SMTPPort,
+		Username: req.SMTPUsername,
+		Password: password,
+		From:     req.SMTPFrom,
+		FromName: req.SMTPFromName,
+		UseTLS:   req.SMTPUseTLS,
+	}
+
+	siteName := h.settingService.GetSiteName(c.Request.Context())
+	subject := "[" + siteName + "] Test Email"
+	body := `
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background-color: #f5f5f5; margin: 0; padding: 20px; }
+        .container { max-width: 600px; margin: 0 auto; background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+        .header { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 30px; text-align: center; }
+        .content { padding: 40px 30px; text-align: center; }
+        .success { color: #10b981; font-size: 48px; margin-bottom: 20px; }
+        .footer { background-color: #f8f9fa; padding: 20px; text-align: center; color: #999; font-size: 12px; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>` + siteName + `</h1>
+        </div>
+        <div class="content">
+            <div class="success">✓</div>
+            <h2>Email Configuration Successful!</h2>
+            <p>This is a test email to verify your SMTP settings are working correctly.</p>
+        </div>
+        <div class="footer">
+            <p>This is an automated test message.</p>
+        </div>
+    </div>
+</body>
+</html>
+`
+
+	if err := h.emailService.SendEmailWithConfig(config, req.Email, subject, body); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Test email sent successfully"})
+}
+
+// GetAdminAPIKey 获取管理员 API Key 状态
+// GET /api/v1/admin/settings/admin-api-key
+func (h *SettingHandler) GetAdminAPIKey(c *gin.Context) {
+	maskedKey, exists, err := h.settingService.GetAdminAPIKeyStatus(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{
+		"exists":     exists,
+		"masked_key": maskedKey,
+	})
+}
+
+// RegenerateAdminAPIKey 生成/重新生成管理员 API Key
+// POST /api/v1/admin/settings/admin-api-key/regenerate
+func (h *SettingHandler) RegenerateAdminAPIKey(c *gin.Context) {
+	key, err := h.settingService.GenerateAdminAPIKey(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{
+		"key": key, // 完整 key 只在生成时返回一次
+	})
+}
+
+// DeleteAdminAPIKey 删除管理员 API Key
+// DELETE /api/v1/admin/settings/admin-api-key
+func (h *SettingHandler) DeleteAdminAPIKey(c *gin.Context) {
+	if err := h.settingService.DeleteAdminAPIKey(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Admin API key deleted"})
+}
+
+// GetStreamTimeoutSettings 获取流超时处理配置
+// GET /api/v1/admin/settings/stream-timeout
+func (h *SettingHandler) GetStreamTimeoutSettings(c *gin.Context) {
+	settings, err := h.settingService.GetStreamTimeoutSettings(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.StreamTimeoutSettings{
+		Enabled:                settings.Enabled,
+		Action:                 settings.Action,
+		TempUnschedMinutes:     settings.TempUnschedMinutes,
+		ThresholdCount:         settings.ThresholdCount,
+		ThresholdWindowMinutes: settings.ThresholdWindowMinutes,
+	})
+}
+
+// UpdateStreamTimeoutSettingsRequest 更新流超时配置请求
+type UpdateStreamTimeoutSettingsRequest 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"`
+}
+
+// UpdateStreamTimeoutSettings 更新流超时处理配置
+// PUT /api/v1/admin/settings/stream-timeout
+func (h *SettingHandler) UpdateStreamTimeoutSettings(c *gin.Context) {
+	var req UpdateStreamTimeoutSettingsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	settings := &service.StreamTimeoutSettings{
+		Enabled:                req.Enabled,
+		Action:                 req.Action,
+		TempUnschedMinutes:     req.TempUnschedMinutes,
+		ThresholdCount:         req.ThresholdCount,
+		ThresholdWindowMinutes: req.ThresholdWindowMinutes,
+	}
+
+	if err := h.settingService.SetStreamTimeoutSettings(c.Request.Context(), settings); err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	// 重新获取设置返回
+	updatedSettings, err := h.settingService.GetStreamTimeoutSettings(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.StreamTimeoutSettings{
+		Enabled:                updatedSettings.Enabled,
+		Action:                 updatedSettings.Action,
+		TempUnschedMinutes:     updatedSettings.TempUnschedMinutes,
+		ThresholdCount:         updatedSettings.ThresholdCount,
+		ThresholdWindowMinutes: updatedSettings.ThresholdWindowMinutes,
+	})
+}

backend/internal/handler/admin/subscription_handler.go

@@ -0,0 +1,278 @@
+package admin
+
+import (
+	"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"`
+}
+
+// ExtendSubscriptionRequest represents extend subscription request
+type ExtendSubscriptionRequest struct {
+	Days int `json:"days" binding:"required,min=1,max=36500"` // max 100 years
+}
+
+// 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")
+
+	subscriptions, pagination, err := h.subscriptionService.List(c.Request.Context(), page, pageSize, userID, groupID, status)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.UserSubscription, 0, len(subscriptions))
+	for i := range subscriptions {
+		out = append(out, *dto.UserSubscriptionFromService(&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.UserSubscriptionFromService(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.UserSubscriptionFromService(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 extending a subscription
+// 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 ExtendSubscriptionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	subscription, err := h.subscriptionService.ExtendSubscription(c.Request.Context(), subscriptionID, req.Days)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserSubscriptionFromService(subscription))
+}
+
+// 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.UserSubscription, 0, len(subscriptions))
+	for i := range subscriptions {
+		out = append(out, *dto.UserSubscriptionFromService(&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.UserSubscription, 0, len(subscriptions))
+	for i := range subscriptions {
+		out = append(out, *dto.UserSubscriptionFromService(&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
+}

backend/internal/handler/admin/system_handler.go

@@ -0,0 +1,87 @@
+package admin
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/sysutil"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// SystemHandler handles system-related operations
+type SystemHandler struct {
+	updateSvc *service.UpdateService
+}
+
+// NewSystemHandler creates a new SystemHandler
+func NewSystemHandler(updateSvc *service.UpdateService) *SystemHandler {
+	return &SystemHandler{
+		updateSvc: updateSvc,
+	}
+}
+
+// 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) {
+	if err := h.updateSvc.PerformUpdate(c.Request.Context()); err != nil {
+		response.Error(c, http.StatusInternalServerError, err.Error())
+		return
+	}
+	response.Success(c, gin.H{
+		"message":      "Update completed. Please restart the service.",
+		"need_restart": true,
+	})
+}
+
+// Rollback restores the previous version
+// POST /api/v1/admin/system/rollback
+func (h *SystemHandler) Rollback(c *gin.Context) {
+	if err := h.updateSvc.Rollback(); err != nil {
+		response.Error(c, http.StatusInternalServerError, err.Error())
+		return
+	}
+	response.Success(c, gin.H{
+		"message":      "Rollback completed. Please restart the service.",
+		"need_restart": true,
+	})
+}
+
+// RestartService restarts the systemd service
+// POST /api/v1/admin/system/restart
+func (h *SystemHandler) RestartService(c *gin.Context) {
+	// 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()
+	}()
+
+	response.Success(c, gin.H{
+		"message": "Service restart initiated",
+	})
+}

backend/internal/handler/admin/usage_handler.go

@@ -0,0 +1,346 @@
+package admin
+
+import (
+	"strconv"
+	"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/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	"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
+}
+
+// NewUsageHandler creates a new admin usage handler
+func NewUsageHandler(
+	usageService *service.UsageService,
+	apiKeyService *service.APIKeyService,
+	adminService service.AdminService,
+) *UsageHandler {
+	return &UsageHandler{
+		usageService:  usageService,
+		apiKeyService: apiKeyService,
+		adminService:  adminService,
+	}
+}
+
+// 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)
+
+	// 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 stream *bool
+	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
+		}
+		// Set end time to end of day
+		t = t.Add(24*time.Hour - time.Nanosecond)
+		endTime = &t
+	}
+
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
+	filters := usagestats.UsageLogFilters{
+		UserID:      userID,
+		APIKeyID:    apiKeyID,
+		AccountID:   accountID,
+		GroupID:     groupID,
+		Model:       model,
+		Stream:      stream,
+		BillingType: billingType,
+		StartTime:   startTime,
+		EndTime:     endTime,
+	}
+
+	records, result, err := h.usageService.ListWithFilters(c.Request.Context(), params, filters)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.UsageLog, 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 stream *bool
+	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
+		}
+		endTime = endTime.Add(24*time.Hour - time.Nanosecond)
+	} 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,
+		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)
+}

backend/internal/handler/admin/user_attribute_handler.go

@@ -0,0 +1,342 @@
+package admin
+
+import (
+	"strconv"
+
+	"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"`
+}
+
+// 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
+	}
+
+	if len(req.UserIDs) == 0 {
+		response.Success(c, BatchUserAttributesResponse{Attributes: map[int64]map[int64]string{}})
+		return
+	}
+
+	attrs, err := h.attrService.GetBatchUserAttributes(c.Request.Context(), req.UserIDs)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, BatchUserAttributesResponse{Attributes: attrs})
+}

backend/internal/handler/admin/user_handler.go

@@ -0,0 +1,279 @@
+package admin
+
+import (
+	"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"
+)
+
+// UserHandler handles admin user management
+type UserHandler struct {
+	adminService service.AdminService
+}
+
+// NewUserHandler creates a new admin user handler
+func NewUserHandler(adminService service.AdminService) *UserHandler {
+	return &UserHandler{
+		adminService: adminService,
+	}
+}
+
+// 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"`
+}
+
+// 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"`
+}
+
+// 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 len(search) > 100 {
+		search = search[:100]
+	}
+
+	filters := service.UserListFilters{
+		Status:     c.Query("status"),
+		Role:       c.Query("role"),
+		Search:     search,
+		Attributes: parseAttributeFilters(c),
+	}
+
+	users, total, err := h.adminService.ListUsers(c.Request.Context(), page, pageSize, filters)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.User, 0, len(users))
+	for i := range users {
+		out = append(out, *dto.UserFromService(&users[i]))
+	}
+	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.UserFromService(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,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserFromService(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,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserFromService(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
+	}
+
+	user, err := h.adminService.UpdateUserBalance(c.Request.Context(), userID, req.Balance, req.Operation, req.Notes)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.UserFromService(user))
+}
+
+// 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)
+}

backend/internal/handler/api_key_handler.go

@@ -0,0 +1,218 @@
+// Package handler provides HTTP request handlers for the application.
+package handler
+
+import (
+	"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"
+)
+
+// 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 黑名单
+}
+
+// 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 黑名单
+}
+
+// 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}
+
+	keys, result, err := h.apiKeyService.List(c.Request.Context(), subject.UserID, params)
+	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,
+	}
+	key, err := h.apiKeyService.Create(c.Request.Context(), subject.UserID, svcReq)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.APIKeyFromService(key))
+}
+
+// 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,
+	}
+	if req.Name != "" {
+		svcReq.Name = &req.Name
+	}
+	svcReq.GroupID = req.GroupID
+	if req.Status != "" {
+		svcReq.Status = &req.Status
+	}
+
+	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)
+}

backend/internal/handler/auth_handler.go

@@ -0,0 +1,240 @@
+package handler
+
+import (
+	"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
+}
+
+// NewAuthHandler creates a new AuthHandler
+func NewAuthHandler(cfg *config.Config, authService *service.AuthService, userService *service.UserService, settingService *service.SettingService, promoService *service.PromoService) *AuthHandler {
+	return &AuthHandler{
+		cfg:          cfg,
+		authService:  authService,
+		userService:  userService,
+		settingSvc:   settingService,
+		promoService: promoService,
+	}
+}
+
+// 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"` // 注册优惠码
+}
+
+// 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"`
+	TokenType   string    `json:"token_type"`
+	User        *dto.User `json:"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 验证（当提供了邮箱验证码时跳过，因为发送验证码时已验证过）
+	if req.VerifyCode == "" {
+		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.RegisterWithVerification(c.Request.Context(), req.Email, req.Password, req.VerifyCode, req.PromoCode)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, AuthResponse{
+		AccessToken: token,
+		TokenType:   "Bearer",
+		User:        dto.UserFromService(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
+	}
+
+	response.Success(c, AuthResponse{
+		AccessToken: token,
+		TokenType:   "Bearer",
+		User:        dto.UserFromService(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) {
+	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,
+	})
+}

backend/internal/handler/auth_linuxdo_oauth.go

@@ -0,0 +1,679 @@
+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)
+	}
+
+	jwtToken, _, err := h.authService.LoginOrRegisterOAuth(c.Request.Context(), email, username)
+	if err != nil {
+		// 避免把内部细节泄露给客户端；给前端保留结构化原因与提示信息即可。
+		redirectOAuthError(c, frontendCallback, "login_failed", infraerrors.Reason(err), infraerrors.Message(err))
+		return
+	}
+
+	fragment := url.Values{}
+	fragment.Set("access_token", jwtToken)
+	fragment.Set("token_type", "Bearer")
+	fragment.Set("redirect", redirectTo)
+	redirectWithFragment(c, frontendCallback, fragment)
+}
+
+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
+}

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"))
+}

backend/internal/handler/dto/mappers.go

@@ -0,0 +1,427 @@
+// Package dto provides data transfer objects for HTTP handlers.
+package dto
+
+import (
+	"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,
+		Notes:         u.Notes,
+		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
+}
+
+func APIKeyFromService(k *service.APIKey) *APIKey {
+	if k == nil {
+		return nil
+	}
+	return &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,
+		CreatedAt:   k.CreatedAt,
+		UpdatedAt:   k.UpdatedAt,
+		User:        UserFromServiceShallow(k.User),
+		Group:       GroupFromServiceShallow(k.Group),
+	}
+}
+
+func GroupFromServiceShallow(g *service.Group) *Group {
+	if g == nil {
+		return nil
+	}
+	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,
+		ClaudeCodeOnly:   g.ClaudeCodeOnly,
+		FallbackGroupID:  g.FallbackGroupID,
+		CreatedAt:        g.CreatedAt,
+		UpdatedAt:        g.UpdatedAt,
+		AccountCount:     g.AccountCount,
+	}
+}
+
+func GroupFromService(g *service.Group) *Group {
+	if g == nil {
+		return nil
+	}
+	out := GroupFromServiceShallow(g)
+	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 AccountFromServiceShallow(a *service.Account) *Account {
+	if a == nil {
+		return nil
+	}
+	return &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,
+		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,
+	}
+}
+
+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,
+		Password:  p.Password,
+		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,
+	}
+}
+
+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
+	}
+	return &RedeemCode{
+		ID:           rc.ID,
+		Code:         rc.Code,
+		Type:         rc.Type,
+		Value:        rc.Value,
+		Status:       rc.Status,
+		UsedBy:       rc.UsedBy,
+		UsedAt:       rc.UsedAt,
+		Notes:        rc.Notes,
+		CreatedAt:    rc.CreatedAt,
+		GroupID:      rc.GroupID,
+		ValidityDays: rc.ValidityDays,
+		User:         UserFromServiceShallow(rc.User),
+		Group:        GroupFromServiceShallow(rc.Group),
+	}
+}
+
+// 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,
+	}
+}
+
+// usageLogFromServiceBase is a helper that converts service UsageLog to DTO.
+// The account parameter allows caller to control what Account info is included.
+// The includeIPAddress parameter controls whether to include the IP address (admin-only).
+func usageLogFromServiceBase(l *service.UsageLog, account *AccountSummary, includeIPAddress bool) *UsageLog {
+	if l == nil {
+		return nil
+	}
+	result := &UsageLog{
+		ID:                    l.ID,
+		UserID:                l.UserID,
+		APIKeyID:              l.APIKeyID,
+		AccountID:             l.AccountID,
+		RequestID:             l.RequestID,
+		Model:                 l.Model,
+		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,
+		AccountRateMultiplier: l.AccountRateMultiplier,
+		BillingType:           l.BillingType,
+		Stream:                l.Stream,
+		DurationMs:            l.DurationMs,
+		FirstTokenMs:          l.FirstTokenMs,
+		ImageCount:            l.ImageCount,
+		ImageSize:             l.ImageSize,
+		UserAgent:             l.UserAgent,
+		CreatedAt:             l.CreatedAt,
+		User:                  UserFromServiceShallow(l.User),
+		APIKey:                APIKeyFromService(l.APIKey),
+		Account:               account,
+		Group:                 GroupFromServiceShallow(l.Group),
+		Subscription:          UserSubscriptionFromService(l.Subscription),
+	}
+	// IP 地址仅对管理员可见
+	if includeIPAddress {
+		result.IPAddress = l.IPAddress
+	}
+	return result
+}
+
+// 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 {
+	return usageLogFromServiceBase(l, nil, false)
+}
+
+// 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) *UsageLog {
+	if l == nil {
+		return nil
+	}
+	return usageLogFromServiceBase(l, AccountSummaryFromService(l.Account), true)
+}
+
+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
+	}
+	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,
+		AssignedBy:         sub.AssignedBy,
+		AssignedAt:         sub.AssignedAt,
+		Notes:              sub.Notes,
+		CreatedAt:          sub.CreatedAt,
+		UpdatedAt:          sub.UpdatedAt,
+		User:               UserFromServiceShallow(sub.User),
+		Group:              GroupFromServiceShallow(sub.Group),
+		AssignedByUser:     UserFromServiceShallow(sub.AssignedByUser),
+	}
+}
+
+func BulkAssignResultFromService(r *service.BulkAssignResult) *BulkAssignResult {
+	if r == nil {
+		return nil
+	}
+	subs := make([]UserSubscription, 0, len(r.Subscriptions))
+	for i := range r.Subscriptions {
+		subs = append(subs, *UserSubscriptionFromService(&r.Subscriptions[i]))
+	}
+	return &BulkAssignResult{
+		SuccessCount:  r.SuccessCount,
+		FailedCount:   r.FailedCount,
+		Subscriptions: subs,
+		Errors:        r.Errors,
+	}
+}
+
+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),
+	}
+}

backend/internal/handler/dto/settings.go

@@ -0,0 +1,77 @@
+package dto
+
+// SystemSettings represents the admin settings API response payload.
+type SystemSettings struct {
+	RegistrationEnabled bool `json:"registration_enabled"`
+	EmailVerifyEnabled  bool `json:"email_verify_enabled"`
+
+	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"`
+
+	DefaultConcurrency int     `json:"default_concurrency"`
+	DefaultBalance     float64 `json:"default_balance"`
+
+	// 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"`
+}
+
+type PublicSettings struct {
+	RegistrationEnabled bool   `json:"registration_enabled"`
+	EmailVerifyEnabled  bool   `json:"email_verify_enabled"`
+	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"`
+	LinuxDoOAuthEnabled bool   `json:"linuxdo_oauth_enabled"`
+	Version             string `json:"version"`
+}
+
+// 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"`
+}

backend/internal/handler/dto/types.go

@@ -0,0 +1,295 @@
+package dto
+
+import "time"
+
+type User struct {
+	ID            int64     `json:"id"`
+	Email         string    `json:"email"`
+	Username      string    `json:"username"`
+	Notes         string    `json:"notes"`
+	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"`
+}
+
+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"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
+
+	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"`
+
+	// Claude Code 客户端限制
+	ClaudeCodeOnly  bool   `json:"claude_code_only"`
+	FallbackGroupID *int64 `json:"fallback_group_id"`
+
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+
+	AccountGroups []AccountGroup `json:"account_groups,omitempty"`
+	AccountCount  int64          `json:"account_count,omitempty"`
+}
+
+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"`
+	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"`
+
+	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"`
+}
+
+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"`
+	Notes     string     `json:"notes"`
+	CreatedAt time.Time  `json:"created_at"`
+
+	GroupID      *int64 `json:"group_id"`
+	ValidityDays int    `json:"validity_days"`
+
+	User  *User  `json:"user,omitempty"`
+	Group *Group `json:"group,omitempty"`
+}
+
+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"`
+
+	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"`
+	AccountRateMultiplier *float64 `json:"account_rate_multiplier"`
+
+	BillingType  int8 `json:"billing_type"`
+	Stream       bool `json:"stream"`
+	DurationMs   *int `json:"duration_ms"`
+	FirstTokenMs *int `json:"first_token_ms"`
+
+	// 图片生成字段
+	ImageCount int     `json:"image_count"`
+	ImageSize  *string `json:"image_size"`
+
+	// User-Agent
+	UserAgent *string `json:"user_agent"`
+
+	// IP 地址（仅管理员可见）
+	IPAddress *string `json:"ip_address,omitempty"`
+
+	CreatedAt time.Time `json:"created_at"`
+
+	User         *User             `json:"user,omitempty"`
+	APIKey       *APIKey           `json:"api_key,omitempty"`
+	Account      *AccountSummary   `json:"account,omitempty"` // Use minimal AccountSummary to prevent data leakage
+	Group        *Group            `json:"group,omitempty"`
+	Subscription *UserSubscription `json:"subscription,omitempty"`
+}
+
+// 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"`
+
+	AssignedBy *int64    `json:"assigned_by"`
+	AssignedAt time.Time `json:"assigned_at"`
+	Notes      string    `json:"notes"`
+
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+
+	User           *User  `json:"user,omitempty"`
+	Group          *Group `json:"group,omitempty"`
+	AssignedByUser *User  `json:"assigned_by_user,omitempty"`
+}
+
+type BulkAssignResult struct {
+	SuccessCount  int                `json:"success_count"`
+	FailedCount   int                `json:"failed_count"`
+	Subscriptions []UserSubscription `json:"subscriptions"`
+	Errors        []string           `json:"errors"`
+}
+
+// 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"`
+}

backend/internal/handler/gateway_handler.go

@@ -0,0 +1,874 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/antigravity"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/claude"
+	pkgerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// GatewayHandler handles API gateway requests
+type GatewayHandler struct {
+	gatewayService            *service.GatewayService
+	geminiCompatService       *service.GeminiMessagesCompatService
+	antigravityGatewayService *service.AntigravityGatewayService
+	userService               *service.UserService
+	billingCacheService       *service.BillingCacheService
+	concurrencyHelper         *ConcurrencyHelper
+}
+
+// NewGatewayHandler creates a new GatewayHandler
+func NewGatewayHandler(
+	gatewayService *service.GatewayService,
+	geminiCompatService *service.GeminiMessagesCompatService,
+	antigravityGatewayService *service.AntigravityGatewayService,
+	userService *service.UserService,
+	concurrencyService *service.ConcurrencyService,
+	billingCacheService *service.BillingCacheService,
+	cfg *config.Config,
+) *GatewayHandler {
+	pingInterval := time.Duration(0)
+	if cfg != nil {
+		pingInterval = time.Duration(cfg.Concurrency.PingInterval) * time.Second
+	}
+	return &GatewayHandler{
+		gatewayService:            gatewayService,
+		geminiCompatService:       geminiCompatService,
+		antigravityGatewayService: antigravityGatewayService,
+		userService:               userService,
+		billingCacheService:       billingCacheService,
+		concurrencyHelper:         NewConcurrencyHelper(concurrencyService, SSEPingFormatClaude, pingInterval),
+	}
+}
+
+// Messages handles Claude API compatible messages endpoint
+// POST /v1/messages
+func (h *GatewayHandler) Messages(c *gin.Context) {
+	// 从context获取apiKey和user（ApiKeyAuth中间件已设置）
+	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
+	}
+
+	// 读取请求体
+	body, err := io.ReadAll(c.Request.Body)
+	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
+	}
+
+	// 检查是否为 Claude Code 客户端，设置到 context 中
+	SetClaudeCodeClientContext(c, body)
+
+	setOpsRequestContext(c, "", false, body)
+
+	parsedReq, err := service.ParseGatewayRequest(body)
+	if err != nil {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Failed to parse request body")
+		return
+	}
+	reqModel := parsedReq.Model
+	reqStream := parsedReq.Stream
+
+	setOpsRequestContext(c, reqModel, reqStream, body)
+
+	// 验证 model 必填
+	if reqModel == "" {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "model is required")
+		return
+	}
+
+	// Track if we've started streaming (for error handling)
+	streamStarted := false
+
+	// 获取订阅信息（可能为nil）- 提前获取用于后续检查
+	subscription, _ := middleware2.GetSubscriptionFromContext(c)
+
+	// 0. 检查wait队列是否已满
+	maxWait := service.CalculateMaxWait(subject.Concurrency)
+	canWait, err := h.concurrencyHelper.IncrementWaitCount(c.Request.Context(), subject.UserID, maxWait)
+	waitCounted := false
+	if err != nil {
+		log.Printf("Increment wait count failed: %v", err)
+		// On error, allow request to proceed
+	} else if !canWait {
+		h.errorResponse(c, http.StatusTooManyRequests, "rate_limit_error", "Too many pending requests, please retry later")
+		return
+	}
+	if err == nil && canWait {
+		waitCounted = true
+	}
+	// Ensure we decrement if we exit before acquiring the user slot.
+	defer func() {
+		if waitCounted {
+			h.concurrencyHelper.DecrementWaitCount(c.Request.Context(), subject.UserID)
+		}
+	}()
+
+	// 1. 首先获取用户并发槽位
+	userReleaseFunc, err := h.concurrencyHelper.AcquireUserSlotWithWait(c, subject.UserID, subject.Concurrency, reqStream, &streamStarted)
+	if err != nil {
+		log.Printf("User concurrency acquire failed: %v", err)
+		h.handleConcurrencyError(c, err, "user", streamStarted)
+		return
+	}
+	// User slot acquired: no longer waiting in the queue.
+	if waitCounted {
+		h.concurrencyHelper.DecrementWaitCount(c.Request.Context(), subject.UserID)
+		waitCounted = false
+	}
+	// 在请求结束或 Context 取消时确保释放槽位，避免客户端断开造成泄漏
+	userReleaseFunc = wrapReleaseOnDone(c.Request.Context(), userReleaseFunc)
+	if userReleaseFunc != nil {
+		defer userReleaseFunc()
+	}
+
+	// 2. 【新增】Wait后二次检查余额/订阅
+	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
+		log.Printf("Billing eligibility check failed after wait: %v", err)
+		status, code, message := billingErrorDetails(err)
+		h.handleStreamingAwareError(c, status, code, message, streamStarted)
+		return
+	}
+
+	// 计算粘性会话hash
+	sessionHash := h.gatewayService.GenerateSessionHash(parsedReq)
+
+	// 获取平台：优先使用强制平台（/antigravity 路由，中间件已设置 request.Context），否则使用分组平台
+	platform := ""
+	if forcePlatform, ok := middleware2.GetForcePlatformFromContext(c); ok {
+		platform = forcePlatform
+	} else if apiKey.Group != nil {
+		platform = apiKey.Group.Platform
+	}
+	sessionKey := sessionHash
+	if platform == service.PlatformGemini && sessionHash != "" {
+		sessionKey = "gemini:" + sessionHash
+	}
+
+	if platform == service.PlatformGemini {
+		const maxAccountSwitches = 3
+		switchCount := 0
+		failedAccountIDs := make(map[int64]struct{})
+		lastFailoverStatus := 0
+
+		for {
+			selection, err := h.gatewayService.SelectAccountWithLoadAwareness(c.Request.Context(), apiKey.GroupID, sessionKey, reqModel, failedAccountIDs)
+			if err != nil {
+				if len(failedAccountIDs) == 0 {
+					h.handleStreamingAwareError(c, http.StatusServiceUnavailable, "api_error", "No available accounts: "+err.Error(), streamStarted)
+					return
+				}
+				h.handleFailoverExhausted(c, lastFailoverStatus, streamStarted)
+				return
+			}
+			account := selection.Account
+			setOpsSelectedAccount(c, account.ID)
+
+			// 检查预热请求拦截（在账号选择后、转发前检查）
+			if account.IsInterceptWarmupEnabled() && isWarmupRequest(body) {
+				if selection.Acquired && selection.ReleaseFunc != nil {
+					selection.ReleaseFunc()
+				}
+				if reqStream {
+					sendMockWarmupStream(c, reqModel)
+				} else {
+					sendMockWarmupResponse(c, reqModel)
+				}
+				return
+			}
+
+			// 3. 获取账号并发槽位
+			accountReleaseFunc := selection.ReleaseFunc
+			if !selection.Acquired {
+				if selection.WaitPlan == nil {
+					h.handleStreamingAwareError(c, http.StatusServiceUnavailable, "api_error", "No available accounts", streamStarted)
+					return
+				}
+				accountWaitCounted := false
+				canWait, err := h.concurrencyHelper.IncrementAccountWaitCount(c.Request.Context(), account.ID, selection.WaitPlan.MaxWaiting)
+				if err != nil {
+					log.Printf("Increment account wait count failed: %v", err)
+				} else if !canWait {
+					log.Printf("Account wait queue full: account=%d", account.ID)
+					h.handleStreamingAwareError(c, http.StatusTooManyRequests, "rate_limit_error", "Too many pending requests, please retry later", streamStarted)
+					return
+				}
+				if err == nil && canWait {
+					accountWaitCounted = true
+				}
+				// Ensure the wait counter is decremented if we exit before acquiring the slot.
+				defer func() {
+					if accountWaitCounted {
+						h.concurrencyHelper.DecrementAccountWaitCount(c.Request.Context(), account.ID)
+					}
+				}()
+
+				accountReleaseFunc, err = h.concurrencyHelper.AcquireAccountSlotWithWaitTimeout(
+					c,
+					account.ID,
+					selection.WaitPlan.MaxConcurrency,
+					selection.WaitPlan.Timeout,
+					reqStream,
+					&streamStarted,
+				)
+				if err != nil {
+					log.Printf("Account concurrency acquire failed: %v", err)
+					h.handleConcurrencyError(c, err, "account", streamStarted)
+					return
+				}
+				// Slot acquired: no longer waiting in queue.
+				if accountWaitCounted {
+					h.concurrencyHelper.DecrementAccountWaitCount(c.Request.Context(), account.ID)
+					accountWaitCounted = false
+				}
+				if err := h.gatewayService.BindStickySession(c.Request.Context(), apiKey.GroupID, sessionKey, account.ID); err != nil {
+					log.Printf("Bind sticky session failed: %v", err)
+				}
+			}
+			// 账号槽位/等待计数需要在超时或断开时安全回收
+			accountReleaseFunc = wrapReleaseOnDone(c.Request.Context(), accountReleaseFunc)
+
+			// 转发请求 - 根据账号平台分流
+			var result *service.ForwardResult
+			if account.Platform == service.PlatformAntigravity {
+				result, err = h.antigravityGatewayService.ForwardGemini(c.Request.Context(), c, account, reqModel, "generateContent", reqStream, body)
+			} else {
+				result, err = h.geminiCompatService.Forward(c.Request.Context(), c, account, body)
+			}
+			if accountReleaseFunc != nil {
+				accountReleaseFunc()
+			}
+			if err != nil {
+				var failoverErr *service.UpstreamFailoverError
+				if errors.As(err, &failoverErr) {
+					failedAccountIDs[account.ID] = struct{}{}
+					lastFailoverStatus = failoverErr.StatusCode
+					if switchCount >= maxAccountSwitches {
+						h.handleFailoverExhausted(c, lastFailoverStatus, streamStarted)
+						return
+					}
+					switchCount++
+					log.Printf("Account %d: upstream error %d, switching account %d/%d", account.ID, failoverErr.StatusCode, switchCount, maxAccountSwitches)
+					continue
+				}
+				// 错误响应已在Forward中处理，这里只记录日志
+				log.Printf("Forward request failed: %v", err)
+				return
+			}
+
+			// 捕获请求信息（用于异步记录，避免在 goroutine 中访问 gin.Context）
+			userAgent := c.GetHeader("User-Agent")
+			clientIP := ip.GetClientIP(c)
+
+			// 异步记录使用量（subscription已在函数开头获取）
+			go func(result *service.ForwardResult, usedAccount *service.Account, ua, clientIP string) {
+				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+				defer cancel()
+				if err := h.gatewayService.RecordUsage(ctx, &service.RecordUsageInput{
+					Result:       result,
+					APIKey:       apiKey,
+					User:         apiKey.User,
+					Account:      usedAccount,
+					Subscription: subscription,
+					UserAgent:    ua,
+					IPAddress:    clientIP,
+				}); err != nil {
+					log.Printf("Record usage failed: %v", err)
+				}
+			}(result, account, userAgent, clientIP)
+			return
+		}
+	}
+
+	const maxAccountSwitches = 10
+	switchCount := 0
+	failedAccountIDs := make(map[int64]struct{})
+	lastFailoverStatus := 0
+
+	for {
+		// 选择支持该模型的账号
+		selection, err := h.gatewayService.SelectAccountWithLoadAwareness(c.Request.Context(), apiKey.GroupID, sessionKey, reqModel, failedAccountIDs)
+		if err != nil {
+			if len(failedAccountIDs) == 0 {
+				h.handleStreamingAwareError(c, http.StatusServiceUnavailable, "api_error", "No available accounts: "+err.Error(), streamStarted)
+				return
+			}
+			h.handleFailoverExhausted(c, lastFailoverStatus, streamStarted)
+			return
+		}
+		account := selection.Account
+		setOpsSelectedAccount(c, account.ID)
+
+		// 检查预热请求拦截（在账号选择后、转发前检查）
+		if account.IsInterceptWarmupEnabled() && isWarmupRequest(body) {
+			if selection.Acquired && selection.ReleaseFunc != nil {
+				selection.ReleaseFunc()
+			}
+			if reqStream {
+				sendMockWarmupStream(c, reqModel)
+			} else {
+				sendMockWarmupResponse(c, reqModel)
+			}
+			return
+		}
+
+		// 3. 获取账号并发槽位
+		accountReleaseFunc := selection.ReleaseFunc
+		if !selection.Acquired {
+			if selection.WaitPlan == nil {
+				h.handleStreamingAwareError(c, http.StatusServiceUnavailable, "api_error", "No available accounts", streamStarted)
+				return
+			}
+			accountWaitCounted := false
+			canWait, err := h.concurrencyHelper.IncrementAccountWaitCount(c.Request.Context(), account.ID, selection.WaitPlan.MaxWaiting)
+			if err != nil {
+				log.Printf("Increment account wait count failed: %v", err)
+			} else if !canWait {
+				log.Printf("Account wait queue full: account=%d", account.ID)
+				h.handleStreamingAwareError(c, http.StatusTooManyRequests, "rate_limit_error", "Too many pending requests, please retry later", streamStarted)
+				return
+			}
+			if err == nil && canWait {
+				accountWaitCounted = true
+			}
+			defer func() {
+				if accountWaitCounted {
+					h.concurrencyHelper.DecrementAccountWaitCount(c.Request.Context(), account.ID)
+				}
+			}()
+
+			accountReleaseFunc, err = h.concurrencyHelper.AcquireAccountSlotWithWaitTimeout(
+				c,
+				account.ID,
+				selection.WaitPlan.MaxConcurrency,
+				selection.WaitPlan.Timeout,
+				reqStream,
+				&streamStarted,
+			)
+			if err != nil {
+				log.Printf("Account concurrency acquire failed: %v", err)
+				h.handleConcurrencyError(c, err, "account", streamStarted)
+				return
+			}
+			if accountWaitCounted {
+				h.concurrencyHelper.DecrementAccountWaitCount(c.Request.Context(), account.ID)
+				accountWaitCounted = false
+			}
+			if err := h.gatewayService.BindStickySession(c.Request.Context(), apiKey.GroupID, sessionKey, account.ID); err != nil {
+				log.Printf("Bind sticky session failed: %v", err)
+			}
+		}
+		// 账号槽位/等待计数需要在超时或断开时安全回收
+		accountReleaseFunc = wrapReleaseOnDone(c.Request.Context(), accountReleaseFunc)
+
+		// 转发请求 - 根据账号平台分流
+		var result *service.ForwardResult
+		if account.Platform == service.PlatformAntigravity {
+			result, err = h.antigravityGatewayService.Forward(c.Request.Context(), c, account, body)
+		} else {
+			result, err = h.gatewayService.Forward(c.Request.Context(), c, account, parsedReq)
+		}
+		if accountReleaseFunc != nil {
+			accountReleaseFunc()
+		}
+		if err != nil {
+			var failoverErr *service.UpstreamFailoverError
+			if errors.As(err, &failoverErr) {
+				failedAccountIDs[account.ID] = struct{}{}
+				lastFailoverStatus = failoverErr.StatusCode
+				if switchCount >= maxAccountSwitches {
+					h.handleFailoverExhausted(c, lastFailoverStatus, streamStarted)
+					return
+				}
+				switchCount++
+				log.Printf("Account %d: upstream error %d, switching account %d/%d", account.ID, failoverErr.StatusCode, switchCount, maxAccountSwitches)
+				continue
+			}
+			// 错误响应已在Forward中处理，这里只记录日志
+			log.Printf("Account %d: Forward request failed: %v", account.ID, err)
+			return
+		}
+
+		// 捕获请求信息（用于异步记录，避免在 goroutine 中访问 gin.Context）
+		userAgent := c.GetHeader("User-Agent")
+		clientIP := ip.GetClientIP(c)
+
+		// 异步记录使用量（subscription已在函数开头获取）
+		go func(result *service.ForwardResult, usedAccount *service.Account, ua, clientIP string) {
+			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			defer cancel()
+			if err := h.gatewayService.RecordUsage(ctx, &service.RecordUsageInput{
+				Result:       result,
+				APIKey:       apiKey,
+				User:         apiKey.User,
+				Account:      usedAccount,
+				Subscription: subscription,
+				UserAgent:    ua,
+				IPAddress:    clientIP,
+			}); err != nil {
+				log.Printf("Record usage failed: %v", err)
+			}
+		}(result, account, userAgent, clientIP)
+		return
+	}
+}
+
+// Models handles listing available models
+// GET /v1/models
+// Returns models based on account configurations (model_mapping whitelist)
+// Falls back to default models if no whitelist is configured
+func (h *GatewayHandler) Models(c *gin.Context) {
+	apiKey, _ := middleware2.GetAPIKeyFromContext(c)
+
+	var groupID *int64
+	var platform string
+
+	if apiKey != nil && apiKey.Group != nil {
+		groupID = &apiKey.Group.ID
+		platform = apiKey.Group.Platform
+	}
+
+	// Get available models from account configurations (without platform filter)
+	availableModels := h.gatewayService.GetAvailableModels(c.Request.Context(), groupID, "")
+
+	if len(availableModels) > 0 {
+		// Build model list from whitelist
+		models := make([]claude.Model, 0, len(availableModels))
+		for _, modelID := range availableModels {
+			models = append(models, claude.Model{
+				ID:          modelID,
+				Type:        "model",
+				DisplayName: modelID,
+				CreatedAt:   "2024-01-01T00:00:00Z",
+			})
+		}
+		c.JSON(http.StatusOK, gin.H{
+			"object": "list",
+			"data":   models,
+		})
+		return
+	}
+
+	// Fallback to default models
+	if platform == "openai" {
+		c.JSON(http.StatusOK, gin.H{
+			"object": "list",
+			"data":   openai.DefaultModels,
+		})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"object": "list",
+		"data":   claude.DefaultModels,
+	})
+}
+
+// AntigravityModels 返回 Antigravity 支持的全部模型
+// GET /antigravity/models
+func (h *GatewayHandler) AntigravityModels(c *gin.Context) {
+	c.JSON(http.StatusOK, gin.H{
+		"object": "list",
+		"data":   antigravity.DefaultModels(),
+	})
+}
+
+// Usage handles getting account balance for CC Switch integration
+// GET /v1/usage
+func (h *GatewayHandler) Usage(c *gin.Context) {
+	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.StatusUnauthorized, "authentication_error", "Invalid API key")
+		return
+	}
+
+	// 订阅模式：返回订阅限额信息
+	if apiKey.Group != nil && apiKey.Group.IsSubscriptionType() {
+		subscription, ok := middleware2.GetSubscriptionFromContext(c)
+		if !ok {
+			h.errorResponse(c, http.StatusForbidden, "subscription_error", "No active subscription")
+			return
+		}
+
+		remaining := h.calculateSubscriptionRemaining(apiKey.Group, subscription)
+		c.JSON(http.StatusOK, gin.H{
+			"isValid":   true,
+			"planName":  apiKey.Group.Name,
+			"remaining": remaining,
+			"unit":      "USD",
+		})
+		return
+	}
+
+	// 余额模式：返回钱包余额
+	latestUser, err := h.userService.GetByID(c.Request.Context(), subject.UserID)
+	if err != nil {
+		h.errorResponse(c, http.StatusInternalServerError, "api_error", "Failed to get user info")
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"isValid":   true,
+		"planName":  "钱包余额",
+		"remaining": latestUser.Balance,
+		"unit":      "USD",
+	})
+}
+
+// calculateSubscriptionRemaining 计算订阅剩余可用额度
+// 逻辑：
+// 1. 如果日/周/月任一限额达到100%，返回0
+// 2. 否则返回所有已配置周期中剩余额度的最小值
+func (h *GatewayHandler) calculateSubscriptionRemaining(group *service.Group, sub *service.UserSubscription) float64 {
+	var remainingValues []float64
+
+	// 检查日限额
+	if group.HasDailyLimit() {
+		remaining := *group.DailyLimitUSD - sub.DailyUsageUSD
+		if remaining <= 0 {
+			return 0
+		}
+		remainingValues = append(remainingValues, remaining)
+	}
+
+	// 检查周限额
+	if group.HasWeeklyLimit() {
+		remaining := *group.WeeklyLimitUSD - sub.WeeklyUsageUSD
+		if remaining <= 0 {
+			return 0
+		}
+		remainingValues = append(remainingValues, remaining)
+	}
+
+	// 检查月限额
+	if group.HasMonthlyLimit() {
+		remaining := *group.MonthlyLimitUSD - sub.MonthlyUsageUSD
+		if remaining <= 0 {
+			return 0
+		}
+		remainingValues = append(remainingValues, remaining)
+	}
+
+	// 如果没有配置任何限额，返回-1表示无限制
+	if len(remainingValues) == 0 {
+		return -1
+	}
+
+	// 返回最小值
+	min := remainingValues[0]
+	for _, v := range remainingValues[1:] {
+		if v < min {
+			min = v
+		}
+	}
+	return min
+}
+
+// handleConcurrencyError handles concurrency-related errors with proper 429 response
+func (h *GatewayHandler) handleConcurrencyError(c *gin.Context, err error, slotType string, streamStarted bool) {
+	h.handleStreamingAwareError(c, http.StatusTooManyRequests, "rate_limit_error",
+		fmt.Sprintf("Concurrency limit exceeded for %s, please retry later", slotType), streamStarted)
+}
+
+func (h *GatewayHandler) handleFailoverExhausted(c *gin.Context, statusCode int, streamStarted bool) {
+	status, errType, errMsg := h.mapUpstreamError(statusCode)
+	h.handleStreamingAwareError(c, status, errType, errMsg, streamStarted)
+}
+
+func (h *GatewayHandler) mapUpstreamError(statusCode int) (int, string, string) {
+	switch statusCode {
+	case 401:
+		return http.StatusBadGateway, "upstream_error", "Upstream authentication failed, please contact administrator"
+	case 403:
+		return http.StatusBadGateway, "upstream_error", "Upstream access forbidden, please contact administrator"
+	case 429:
+		return http.StatusTooManyRequests, "rate_limit_error", "Upstream rate limit exceeded, please retry later"
+	case 529:
+		return http.StatusServiceUnavailable, "overloaded_error", "Upstream service overloaded, please retry later"
+	case 500, 502, 503, 504:
+		return http.StatusBadGateway, "upstream_error", "Upstream service temporarily unavailable"
+	default:
+		return http.StatusBadGateway, "upstream_error", "Upstream request failed"
+	}
+}
+
+// handleStreamingAwareError handles errors that may occur after streaming has started
+func (h *GatewayHandler) handleStreamingAwareError(c *gin.Context, status int, errType, message string, streamStarted bool) {
+	if streamStarted {
+		// Stream already started, send error as SSE event then close
+		flusher, ok := c.Writer.(http.Flusher)
+		if ok {
+			// Send error event in SSE format with proper JSON marshaling
+			errorData := map[string]any{
+				"type": "error",
+				"error": map[string]string{
+					"type":    errType,
+					"message": message,
+				},
+			}
+			jsonBytes, err := json.Marshal(errorData)
+			if err != nil {
+				_ = c.Error(err)
+				return
+			}
+			errorEvent := fmt.Sprintf("data: %s\n\n", string(jsonBytes))
+			if _, err := fmt.Fprint(c.Writer, errorEvent); err != nil {
+				_ = c.Error(err)
+			}
+			flusher.Flush()
+		}
+		return
+	}
+
+	// Normal case: return JSON response with proper status code
+	h.errorResponse(c, status, errType, message)
+}
+
+// errorResponse 返回Claude API格式的错误响应
+func (h *GatewayHandler) errorResponse(c *gin.Context, status int, errType, message string) {
+	c.JSON(status, gin.H{
+		"type": "error",
+		"error": gin.H{
+			"type":    errType,
+			"message": message,
+		},
+	})
+}
+
+// CountTokens handles token counting endpoint
+// POST /v1/messages/count_tokens
+// 特点：校验订阅/余额，但不计算并发、不记录使用量
+func (h *GatewayHandler) CountTokens(c *gin.Context) {
+	// 从context获取apiKey和user（ApiKeyAuth中间件已设置）
+	apiKey, ok := middleware2.GetAPIKeyFromContext(c)
+	if !ok {
+		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
+		return
+	}
+
+	_, ok = middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		h.errorResponse(c, http.StatusInternalServerError, "api_error", "User context not found")
+		return
+	}
+
+	// 读取请求体
+	body, err := io.ReadAll(c.Request.Body)
+	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
+	}
+
+	setOpsRequestContext(c, "", false, body)
+
+	parsedReq, err := service.ParseGatewayRequest(body)
+	if err != nil {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Failed to parse request body")
+		return
+	}
+
+	// 验证 model 必填
+	if parsedReq.Model == "" {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "model is required")
+		return
+	}
+
+	setOpsRequestContext(c, parsedReq.Model, parsedReq.Stream, body)
+
+	// 获取订阅信息（可能为nil）
+	subscription, _ := middleware2.GetSubscriptionFromContext(c)
+
+	// 校验 billing eligibility（订阅/余额）
+	// 【注意】不计算并发，但需要校验订阅/余额
+	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
+		status, code, message := billingErrorDetails(err)
+		h.errorResponse(c, status, code, message)
+		return
+	}
+
+	// 计算粘性会话 hash
+	sessionHash := h.gatewayService.GenerateSessionHash(parsedReq)
+
+	// 选择支持该模型的账号
+	account, err := h.gatewayService.SelectAccountForModel(c.Request.Context(), apiKey.GroupID, sessionHash, parsedReq.Model)
+	if err != nil {
+		h.errorResponse(c, http.StatusServiceUnavailable, "api_error", "No available accounts: "+err.Error())
+		return
+	}
+	setOpsSelectedAccount(c, account.ID)
+
+	// 转发请求（不记录使用量）
+	if err := h.gatewayService.ForwardCountTokens(c.Request.Context(), c, account, parsedReq); err != nil {
+		log.Printf("Forward count_tokens request failed: %v", err)
+		// 错误响应已在 ForwardCountTokens 中处理
+		return
+	}
+}
+
+// isWarmupRequest 检测是否为预热请求（标题生成、Warmup等）
+func isWarmupRequest(body []byte) bool {
+	// 快速检查：如果body不包含关键字，直接返回false
+	bodyStr := string(body)
+	if !strings.Contains(bodyStr, "title") && !strings.Contains(bodyStr, "Warmup") {
+		return false
+	}
+
+	// 解析完整请求
+	var req struct {
+		Messages []struct {
+			Content []struct {
+				Type string `json:"type"`
+				Text string `json:"text"`
+			} `json:"content"`
+		} `json:"messages"`
+		System []struct {
+			Text string `json:"text"`
+		} `json:"system"`
+	}
+	if err := json.Unmarshal(body, &req); err != nil {
+		return false
+	}
+
+	// 检查 messages 中的标题提示模式
+	for _, msg := range req.Messages {
+		for _, content := range msg.Content {
+			if content.Type == "text" {
+				if strings.Contains(content.Text, "Please write a 5-10 word title for the following conversation:") ||
+					content.Text == "Warmup" {
+					return true
+				}
+			}
+		}
+	}
+
+	// 检查 system 中的标题提取模式
+	for _, system := range req.System {
+		if strings.Contains(system.Text, "nalyze if this message indicates a new conversation topic. If it does, extract a 2-3 word title") {
+			return true
+		}
+	}
+
+	return false
+}
+
+// sendMockWarmupStream 发送流式 mock 响应（用于预热请求拦截）
+func sendMockWarmupStream(c *gin.Context, model string) {
+	c.Header("Content-Type", "text/event-stream")
+	c.Header("Cache-Control", "no-cache")
+	c.Header("Connection", "keep-alive")
+	c.Header("X-Accel-Buffering", "no")
+
+	// Build message_start event with proper JSON marshaling
+	messageStart := map[string]any{
+		"type": "message_start",
+		"message": map[string]any{
+			"id":            "msg_mock_warmup",
+			"type":          "message",
+			"role":          "assistant",
+			"model":         model,
+			"content":       []any{},
+			"stop_reason":   nil,
+			"stop_sequence": nil,
+			"usage": map[string]int{
+				"input_tokens":  10,
+				"output_tokens": 0,
+			},
+		},
+	}
+	messageStartJSON, _ := json.Marshal(messageStart)
+
+	events := []string{
+		`event: message_start` + "\n" + `data: ` + string(messageStartJSON),
+		`event: content_block_start` + "\n" + `data: {"content_block":{"text":"","type":"text"},"index":0,"type":"content_block_start"}`,
+		`event: content_block_delta` + "\n" + `data: {"delta":{"text":"New","type":"text_delta"},"index":0,"type":"content_block_delta"}`,
+		`event: content_block_delta` + "\n" + `data: {"delta":{"text":" Conversation","type":"text_delta"},"index":0,"type":"content_block_delta"}`,
+		`event: content_block_stop` + "\n" + `data: {"index":0,"type":"content_block_stop"}`,
+		`event: message_delta` + "\n" + `data: {"delta":{"stop_reason":"end_turn","stop_sequence":null},"type":"message_delta","usage":{"input_tokens":10,"output_tokens":2}}`,
+		`event: message_stop` + "\n" + `data: {"type":"message_stop"}`,
+	}
+
+	for _, event := range events {
+		_, _ = c.Writer.WriteString(event + "\n\n")
+		c.Writer.Flush()
+		time.Sleep(20 * time.Millisecond)
+	}
+}
+
+// sendMockWarmupResponse 发送非流式 mock 响应（用于预热请求拦截）
+func sendMockWarmupResponse(c *gin.Context, model string) {
+	c.JSON(http.StatusOK, gin.H{
+		"id":          "msg_mock_warmup",
+		"type":        "message",
+		"role":        "assistant",
+		"model":       model,
+		"content":     []gin.H{{"type": "text", "text": "New Conversation"}},
+		"stop_reason": "end_turn",
+		"usage": gin.H{
+			"input_tokens":  10,
+			"output_tokens": 2,
+		},
+	})
+}
+
+func billingErrorDetails(err error) (status int, code, message string) {
+	if errors.Is(err, service.ErrBillingServiceUnavailable) {
+		msg := pkgerrors.Message(err)
+		if msg == "" {
+			msg = "Billing service temporarily unavailable. Please retry later."
+		}
+		return http.StatusServiceUnavailable, "billing_service_error", msg
+	}
+	msg := pkgerrors.Message(err)
+	if msg == "" {
+		msg = err.Error()
+	}
+	return http.StatusForbidden, "billing_error", msg
+}

backend/internal/handler/gateway_helper.go

@@ -0,0 +1,323 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"math/rand"
+	"net/http"
+	"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()
+
+// SetClaudeCodeClientContext 检查请求是否来自 Claude Code 客户端，并设置到 context 中
+// 返回更新后的 context
+func SetClaudeCodeClientContext(c *gin.Context, body []byte) {
+	// 解析请求体为 map
+	var bodyMap map[string]any
+	if len(body) > 0 {
+		_ = json.Unmarshal(body, &bodyMap)
+	}
+
+	// 验证是否为 Claude Code 客户端
+	isClaudeCode := claudeCodeValidator.Validate(c.Request, bodyMap)
+
+	// 更新 request context
+	ctx := service.SetClaudeCodeClient(c.Request.Context(), isClaudeCode)
+	c.Request = c.Request.WithContext(ctx)
+}
+
+// 并发槽位等待相关常量
+//
+// 性能优化说明：
+// 原实现使用固定间隔（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.
+// 用于避免客户端断开或上游超时导致的并发槽位泄漏。
+// 修复：添加 quit channel 确保 goroutine 及时退出，避免泄露
+func wrapReleaseOnDone(ctx context.Context, releaseFunc func()) func() {
+	if releaseFunc == nil {
+		return nil
+	}
+	var once sync.Once
+	quit := make(chan struct{})
+
+	release := func() {
+		once.Do(func() {
+			releaseFunc()
+			close(quit) // 通知监听 goroutine 退出
+		})
+	}
+
+	go func() {
+		select {
+		case <-ctx.Done():
+			// Context 取消时释放资源
+			release()
+		case <-quit:
+			// 正常释放已完成，goroutine 退出
+			return
+		}
+	}()
+
+	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)
+}
+
+// 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
+	result, err := h.concurrencyService.AcquireUserSlot(ctx, userID, maxConcurrency)
+	if err != nil {
+		return nil, err
+	}
+
+	if result.Acquired {
+		return result.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
+	result, err := h.concurrencyService.AcquireAccountSlot(ctx, accountID, maxConcurrency)
+	if err != nil {
+		return nil, err
+	}
+
+	if result.Acquired {
+		return result.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)
+}
+
+// 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) (func(), error) {
+	ctx, cancel := context.WithTimeout(c.Request.Context(), timeout)
+	defer cancel()
+
+	// Try immediate acquire first (avoid unnecessary wait)
+	var result *service.AcquireResult
+	var err error
+	if slotType == "user" {
+		result, err = h.concurrencyService.AcquireUserSlot(ctx, id, maxConcurrency)
+	} else {
+		result, err = h.concurrencyService.AcquireAccountSlot(ctx, id, maxConcurrency)
+	}
+	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()
+	rng := rand.New(rand.NewSource(time.Now().UnixNano()))
+
+	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
+			var result *service.AcquireResult
+			var err error
+
+			if slotType == "user" {
+				result, err = h.concurrencyService.AcquireUserSlot(ctx, id, maxConcurrency)
+			} else {
+				result, err = h.concurrencyService.AcquireAccountSlot(ctx, id, maxConcurrency)
+			}
+
+			if err != nil {
+				return nil, err
+			}
+
+			if result.Acquired {
+				return result.ReleaseFunc, nil
+			}
+			backoff = nextBackoff(backoff, rng)
+			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)
+}
+
+// nextBackoff 计算下一次退避时间
+// 性能优化：使用指数退避 + 随机抖动，避免惊群效应
+// current: 当前退避时间
+// rng: 随机数生成器（可为 nil，此时不添加抖动）
+// 返回值：下一次退避时间（100ms ~ 2s 之间）
+func nextBackoff(current time.Duration, rng *rand.Rand) time.Duration {
+	// 指数退避：当前时间 * 1.5
+	next := time.Duration(float64(current) * backoffMultiplier)
+	if next > maxBackoff {
+		next = maxBackoff
+	}
+	if rng == nil {
+		return next
+	}
+	// 添加 ±20% 的随机抖动（jitter 范围 0.8 ~ 1.2）
+	// 抖动可以分散多个请求的重试时间点，避免同时冲击 Redis
+	jitter := 0.8 + rng.Float64()*0.4
+	jittered := time.Duration(float64(next) * jitter)
+	if jittered < initialBackoff {
+		return initialBackoff
+	}
+	if jittered > maxBackoff {
+		return maxBackoff
+	}
+	return jittered
+}

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()
+	}
+}

backend/internal/handler/gemini_v1beta_handler.go

@@ -0,0 +1,435 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/antigravity"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/gemini"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/googleapi"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// 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
+	}
+
+	// 检查平台：优先使用强制平台（/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"
+
+	body, err := io.ReadAll(c.Request.Body)
+	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 {
+		log.Printf("Increment wait count failed: %v", err)
+	} else if !canWait {
+		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
+	userReleaseFunc, err := geminiConcurrency.AcquireUserSlotWithWait(c, authSubject.UserID, authSubject.Concurrency, stream, &streamStarted)
+	if err != nil {
+		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 {
+		status, _, message := billingErrorDetails(err)
+		googleError(c, status, message)
+		return
+	}
+
+	// 3) select account (sticky session based on request body)
+	parsedReq, _ := service.ParseGatewayRequest(body)
+	sessionHash := h.gatewayService.GenerateSessionHash(parsedReq)
+	sessionKey := sessionHash
+	if sessionHash != "" {
+		sessionKey = "gemini:" + sessionHash
+	}
+	const maxAccountSwitches = 3
+	switchCount := 0
+	failedAccountIDs := make(map[int64]struct{})
+	lastFailoverStatus := 0
+
+	for {
+		selection, err := h.gatewayService.SelectAccountWithLoadAwareness(c.Request.Context(), apiKey.GroupID, sessionKey, modelName, failedAccountIDs)
+		if err != nil {
+			if len(failedAccountIDs) == 0 {
+				googleError(c, http.StatusServiceUnavailable, "No available Gemini accounts: "+err.Error())
+				return
+			}
+			handleGeminiFailoverExhausted(c, lastFailoverStatus)
+			return
+		}
+		account := selection.Account
+		setOpsSelectedAccount(c, 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 {
+				log.Printf("Increment account wait count failed: %v", err)
+			} else if !canWait {
+				log.Printf("Account wait queue full: account=%d", account.ID)
+				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 {
+				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 {
+				log.Printf("Bind sticky session failed: %v", err)
+			}
+		}
+		// 账号槽位/等待计数需要在超时或断开时安全回收
+		accountReleaseFunc = wrapReleaseOnDone(c.Request.Context(), accountReleaseFunc)
+
+		// 5) forward (根据平台分流)
+		var result *service.ForwardResult
+		if account.Platform == service.PlatformAntigravity {
+			result, err = h.antigravityGatewayService.ForwardGemini(c.Request.Context(), c, account, modelName, action, stream, body)
+		} else {
+			result, err = h.geminiCompatService.ForwardNative(c.Request.Context(), c, account, modelName, action, stream, body)
+		}
+		if accountReleaseFunc != nil {
+			accountReleaseFunc()
+		}
+		if err != nil {
+			var failoverErr *service.UpstreamFailoverError
+			if errors.As(err, &failoverErr) {
+				failedAccountIDs[account.ID] = struct{}{}
+				if switchCount >= maxAccountSwitches {
+					lastFailoverStatus = failoverErr.StatusCode
+					handleGeminiFailoverExhausted(c, lastFailoverStatus)
+					return
+				}
+				lastFailoverStatus = failoverErr.StatusCode
+				switchCount++
+				log.Printf("Gemini account %d: upstream error %d, switching account %d/%d", account.ID, failoverErr.StatusCode, switchCount, maxAccountSwitches)
+				continue
+			}
+			// ForwardNative already wrote the response
+			log.Printf("Gemini native forward failed: %v", err)
+			return
+		}
+
+		// 捕获请求信息（用于异步记录，避免在 goroutine 中访问 gin.Context）
+		userAgent := c.GetHeader("User-Agent")
+		clientIP := ip.GetClientIP(c)
+
+		// 6) record usage async
+		go func(result *service.ForwardResult, usedAccount *service.Account, ua, ip string) {
+			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			defer cancel()
+			if err := h.gatewayService.RecordUsage(ctx, &service.RecordUsageInput{
+				Result:       result,
+				APIKey:       apiKey,
+				User:         apiKey.User,
+				Account:      usedAccount,
+				Subscription: subscription,
+				UserAgent:    ua,
+				IPAddress:    ip,
+			}); err != nil {
+				log.Printf("Record usage failed: %v", err)
+			}
+		}(result, account, userAgent, clientIP)
+		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 handleGeminiFailoverExhausted(c *gin.Context, statusCode int) {
+	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
+}

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

backend/internal/handler/handler.go

@@ -0,0 +1,46 @@
+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
+	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
+}
+
+// Handlers contains all HTTP handlers
+type Handlers struct {
+	Auth          *AuthHandler
+	User          *UserHandler
+	APIKey        *APIKeyHandler
+	Usage         *UsageHandler
+	Redeem        *RedeemHandler
+	Subscription  *SubscriptionHandler
+	Admin         *AdminHandlers
+	Gateway       *GatewayHandler
+	OpenAIGateway *OpenAIGatewayHandler
+	Setting       *SettingHandler
+}
+
+// BuildInfo contains build-time information
+type BuildInfo struct {
+	Version   string
+	BuildType string // "source" for manual builds, "release" for CI builds
+}

backend/internal/handler/openai_gateway_handler.go

@@ -0,0 +1,367 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// OpenAIGatewayHandler handles OpenAI API gateway requests
+type OpenAIGatewayHandler struct {
+	gatewayService      *service.OpenAIGatewayService
+	billingCacheService *service.BillingCacheService
+	concurrencyHelper   *ConcurrencyHelper
+}
+
+// NewOpenAIGatewayHandler creates a new OpenAIGatewayHandler
+func NewOpenAIGatewayHandler(
+	gatewayService *service.OpenAIGatewayService,
+	concurrencyService *service.ConcurrencyService,
+	billingCacheService *service.BillingCacheService,
+	cfg *config.Config,
+) *OpenAIGatewayHandler {
+	pingInterval := time.Duration(0)
+	if cfg != nil {
+		pingInterval = time.Duration(cfg.Concurrency.PingInterval) * time.Second
+	}
+	return &OpenAIGatewayHandler{
+		gatewayService:      gatewayService,
+		billingCacheService: billingCacheService,
+		concurrencyHelper:   NewConcurrencyHelper(concurrencyService, SSEPingFormatComment, pingInterval),
+	}
+}
+
+// Responses handles OpenAI Responses API endpoint
+// POST /openai/v1/responses
+func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
+	// Get apiKey and user from context (set by ApiKeyAuth middleware)
+	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
+	}
+
+	// Read request body
+	body, err := io.ReadAll(c.Request.Body)
+	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
+	}
+
+	setOpsRequestContext(c, "", false, body)
+
+	// Parse request body to map for potential modification
+	var reqBody map[string]any
+	if err := json.Unmarshal(body, &reqBody); err != nil {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Failed to parse request body")
+		return
+	}
+
+	// Extract model and stream
+	reqModel, _ := reqBody["model"].(string)
+	reqStream, _ := reqBody["stream"].(bool)
+
+	// 验证 model 必填
+	if reqModel == "" {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "model is required")
+		return
+	}
+
+	userAgent := c.GetHeader("User-Agent")
+	if !openai.IsCodexCLIRequest(userAgent) {
+		existingInstructions, _ := reqBody["instructions"].(string)
+		if strings.TrimSpace(existingInstructions) == "" {
+			if instructions := strings.TrimSpace(service.GetOpenCodeInstructions()); instructions != "" {
+				reqBody["instructions"] = instructions
+				// Re-serialize body
+				body, err = json.Marshal(reqBody)
+				if err != nil {
+					h.errorResponse(c, http.StatusInternalServerError, "api_error", "Failed to process request")
+					return
+				}
+			}
+		}
+	}
+
+	setOpsRequestContext(c, reqModel, reqStream, body)
+
+	// 提前校验 function_call_output 是否具备可关联上下文，避免上游 400。
+	// 要求 previous_response_id，或 input 内存在带 call_id 的 tool_call/function_call，
+	// 或带 id 且与 call_id 匹配的 item_reference。
+	if service.HasFunctionCallOutput(reqBody) {
+		previousResponseID, _ := reqBody["previous_response_id"].(string)
+		if strings.TrimSpace(previousResponseID) == "" && !service.HasToolCallContext(reqBody) {
+			if service.HasFunctionCallOutputMissingCallID(reqBody) {
+				log.Printf("[OpenAI Handler] function_call_output 缺少 call_id: model=%s", reqModel)
+				h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "function_call_output requires call_id or previous_response_id; if relying on history, ensure store=true and reuse previous_response_id")
+				return
+			}
+			callIDs := service.FunctionCallOutputCallIDs(reqBody)
+			if !service.HasItemReferenceForCallIDs(reqBody, callIDs) {
+				log.Printf("[OpenAI Handler] function_call_output 缺少匹配的 item_reference: model=%s", reqModel)
+				h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "function_call_output requires item_reference ids matching each call_id, or previous_response_id/tool_call context; if relying on history, ensure store=true and reuse previous_response_id")
+				return
+			}
+		}
+	}
+
+	// Track if we've started streaming (for error handling)
+	streamStarted := false
+
+	// Get subscription info (may be nil)
+	subscription, _ := middleware2.GetSubscriptionFromContext(c)
+
+	// 0. Check if wait queue is full
+	maxWait := service.CalculateMaxWait(subject.Concurrency)
+	canWait, err := h.concurrencyHelper.IncrementWaitCount(c.Request.Context(), subject.UserID, maxWait)
+	waitCounted := false
+	if err != nil {
+		log.Printf("Increment wait count failed: %v", err)
+		// On error, allow request to proceed
+	} else if !canWait {
+		h.errorResponse(c, http.StatusTooManyRequests, "rate_limit_error", "Too many pending requests, please retry later")
+		return
+	}
+	if err == nil && canWait {
+		waitCounted = true
+	}
+	defer func() {
+		if waitCounted {
+			h.concurrencyHelper.DecrementWaitCount(c.Request.Context(), subject.UserID)
+		}
+	}()
+
+	// 1. First acquire user concurrency slot
+	userReleaseFunc, err := h.concurrencyHelper.AcquireUserSlotWithWait(c, subject.UserID, subject.Concurrency, reqStream, &streamStarted)
+	if err != nil {
+		log.Printf("User concurrency acquire failed: %v", err)
+		h.handleConcurrencyError(c, err, "user", streamStarted)
+		return
+	}
+	// User slot acquired: no longer waiting.
+	if waitCounted {
+		h.concurrencyHelper.DecrementWaitCount(c.Request.Context(), subject.UserID)
+		waitCounted = false
+	}
+	// 确保请求取消时也会释放槽位，避免长连接被动中断造成泄漏
+	userReleaseFunc = wrapReleaseOnDone(c.Request.Context(), userReleaseFunc)
+	if userReleaseFunc != nil {
+		defer userReleaseFunc()
+	}
+
+	// 2. Re-check billing eligibility after wait
+	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
+		log.Printf("Billing eligibility check failed after wait: %v", err)
+		status, code, message := billingErrorDetails(err)
+		h.handleStreamingAwareError(c, status, code, message, streamStarted)
+		return
+	}
+
+	// Generate session hash (from header for OpenAI)
+	sessionHash := h.gatewayService.GenerateSessionHash(c)
+
+	const maxAccountSwitches = 3
+	switchCount := 0
+	failedAccountIDs := make(map[int64]struct{})
+	lastFailoverStatus := 0
+
+	for {
+		// Select account supporting the requested model
+		log.Printf("[OpenAI Handler] Selecting account: groupID=%v model=%s", apiKey.GroupID, reqModel)
+		selection, err := h.gatewayService.SelectAccountWithLoadAwareness(c.Request.Context(), apiKey.GroupID, sessionHash, reqModel, failedAccountIDs)
+		if err != nil {
+			log.Printf("[OpenAI Handler] SelectAccount failed: %v", err)
+			if len(failedAccountIDs) == 0 {
+				h.handleStreamingAwareError(c, http.StatusServiceUnavailable, "api_error", "No available accounts: "+err.Error(), streamStarted)
+				return
+			}
+			h.handleFailoverExhausted(c, lastFailoverStatus, streamStarted)
+			return
+		}
+		account := selection.Account
+		log.Printf("[OpenAI Handler] Selected account: id=%d name=%s", account.ID, account.Name)
+		setOpsSelectedAccount(c, account.ID)
+
+		// 3. Acquire account concurrency slot
+		accountReleaseFunc := selection.ReleaseFunc
+		if !selection.Acquired {
+			if selection.WaitPlan == nil {
+				h.handleStreamingAwareError(c, http.StatusServiceUnavailable, "api_error", "No available accounts", streamStarted)
+				return
+			}
+			accountWaitCounted := false
+			canWait, err := h.concurrencyHelper.IncrementAccountWaitCount(c.Request.Context(), account.ID, selection.WaitPlan.MaxWaiting)
+			if err != nil {
+				log.Printf("Increment account wait count failed: %v", err)
+			} else if !canWait {
+				log.Printf("Account wait queue full: account=%d", account.ID)
+				h.handleStreamingAwareError(c, http.StatusTooManyRequests, "rate_limit_error", "Too many pending requests, please retry later", streamStarted)
+				return
+			}
+			if err == nil && canWait {
+				accountWaitCounted = true
+			}
+			defer func() {
+				if accountWaitCounted {
+					h.concurrencyHelper.DecrementAccountWaitCount(c.Request.Context(), account.ID)
+				}
+			}()
+
+			accountReleaseFunc, err = h.concurrencyHelper.AcquireAccountSlotWithWaitTimeout(
+				c,
+				account.ID,
+				selection.WaitPlan.MaxConcurrency,
+				selection.WaitPlan.Timeout,
+				reqStream,
+				&streamStarted,
+			)
+			if err != nil {
+				log.Printf("Account concurrency acquire failed: %v", err)
+				h.handleConcurrencyError(c, err, "account", streamStarted)
+				return
+			}
+			if accountWaitCounted {
+				h.concurrencyHelper.DecrementAccountWaitCount(c.Request.Context(), account.ID)
+				accountWaitCounted = false
+			}
+			if err := h.gatewayService.BindStickySession(c.Request.Context(), apiKey.GroupID, sessionHash, account.ID); err != nil {
+				log.Printf("Bind sticky session failed: %v", err)
+			}
+		}
+		// 账号槽位/等待计数需要在超时或断开时安全回收
+		accountReleaseFunc = wrapReleaseOnDone(c.Request.Context(), accountReleaseFunc)
+
+		// Forward request
+		result, err := h.gatewayService.Forward(c.Request.Context(), c, account, body)
+		if accountReleaseFunc != nil {
+			accountReleaseFunc()
+		}
+		if err != nil {
+			var failoverErr *service.UpstreamFailoverError
+			if errors.As(err, &failoverErr) {
+				failedAccountIDs[account.ID] = struct{}{}
+				if switchCount >= maxAccountSwitches {
+					lastFailoverStatus = failoverErr.StatusCode
+					h.handleFailoverExhausted(c, lastFailoverStatus, streamStarted)
+					return
+				}
+				lastFailoverStatus = failoverErr.StatusCode
+				switchCount++
+				log.Printf("Account %d: upstream error %d, switching account %d/%d", account.ID, failoverErr.StatusCode, switchCount, maxAccountSwitches)
+				continue
+			}
+			// Error response already handled in Forward, just log
+			log.Printf("Account %d: Forward request failed: %v", account.ID, err)
+			return
+		}
+
+		// 捕获请求信息（用于异步记录，避免在 goroutine 中访问 gin.Context）
+		userAgent := c.GetHeader("User-Agent")
+		clientIP := ip.GetClientIP(c)
+
+		// Async record usage
+		go func(result *service.OpenAIForwardResult, usedAccount *service.Account, ua, ip string) {
+			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			defer cancel()
+			if err := h.gatewayService.RecordUsage(ctx, &service.OpenAIRecordUsageInput{
+				Result:       result,
+				APIKey:       apiKey,
+				User:         apiKey.User,
+				Account:      usedAccount,
+				Subscription: subscription,
+				UserAgent:    ua,
+				IPAddress:    ip,
+			}); err != nil {
+				log.Printf("Record usage failed: %v", err)
+			}
+		}(result, account, userAgent, clientIP)
+		return
+	}
+}
+
+// handleConcurrencyError handles concurrency-related errors with proper 429 response
+func (h *OpenAIGatewayHandler) handleConcurrencyError(c *gin.Context, err error, slotType string, streamStarted bool) {
+	h.handleStreamingAwareError(c, http.StatusTooManyRequests, "rate_limit_error",
+		fmt.Sprintf("Concurrency limit exceeded for %s, please retry later", slotType), streamStarted)
+}
+
+func (h *OpenAIGatewayHandler) handleFailoverExhausted(c *gin.Context, statusCode int, streamStarted bool) {
+	status, errType, errMsg := h.mapUpstreamError(statusCode)
+	h.handleStreamingAwareError(c, status, errType, errMsg, streamStarted)
+}
+
+func (h *OpenAIGatewayHandler) mapUpstreamError(statusCode int) (int, string, string) {
+	switch statusCode {
+	case 401:
+		return http.StatusBadGateway, "upstream_error", "Upstream authentication failed, please contact administrator"
+	case 403:
+		return http.StatusBadGateway, "upstream_error", "Upstream access forbidden, please contact administrator"
+	case 429:
+		return http.StatusTooManyRequests, "rate_limit_error", "Upstream rate limit exceeded, please retry later"
+	case 529:
+		return http.StatusServiceUnavailable, "upstream_error", "Upstream service overloaded, please retry later"
+	case 500, 502, 503, 504:
+		return http.StatusBadGateway, "upstream_error", "Upstream service temporarily unavailable"
+	default:
+		return http.StatusBadGateway, "upstream_error", "Upstream request failed"
+	}
+}
+
+// handleStreamingAwareError handles errors that may occur after streaming has started
+func (h *OpenAIGatewayHandler) handleStreamingAwareError(c *gin.Context, status int, errType, message string, streamStarted bool) {
+	if streamStarted {
+		// Stream already started, send error as SSE event then close
+		flusher, ok := c.Writer.(http.Flusher)
+		if ok {
+			// Send error event in OpenAI SSE format
+			errorEvent := fmt.Sprintf(`event: error`+"\n"+`data: {"error": {"type": "%s", "message": "%s"}}`+"\n\n", errType, message)
+			if _, err := fmt.Fprint(c.Writer, errorEvent); err != nil {
+				_ = c.Error(err)
+			}
+			flusher.Flush()
+		}
+		return
+	}
+
+	// Normal case: return JSON response with proper status code
+	h.errorResponse(c, status, errType, message)
+}
+
+// errorResponse returns OpenAI API format error response
+func (h *OpenAIGatewayHandler) errorResponse(c *gin.Context, status int, errType, message string) {
+	c.JSON(status, gin.H{
+		"error": gin.H{
+			"type":    errType,
+			"message": message,
+		},
+	})
+}

backend/internal/handler/redeem_handler.go

@@ -0,0 +1,85 @@
+package handler
+
+import (
+	"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"
+)
+
+// RedeemHandler handles redeem code-related requests
+type RedeemHandler struct {
+	redeemService *service.RedeemService
+}
+
+// NewRedeemHandler creates a new RedeemHandler
+func NewRedeemHandler(redeemService *service.RedeemService) *RedeemHandler {
+	return &RedeemHandler{
+		redeemService: redeemService,
+	}
+}
+
+// RedeemRequest represents the redeem code request payload
+type RedeemRequest struct {
+	Code string `json:"code" binding:"required"`
+}
+
+// RedeemResponse represents the redeem response
+type RedeemResponse struct {
+	Message        string   `json:"message"`
+	Type           string   `json:"type"`
+	Value          float64  `json:"value"`
+	NewBalance     *float64 `json:"new_balance,omitempty"`
+	NewConcurrency *int     `json:"new_concurrency,omitempty"`
+}
+
+// Redeem handles redeeming a code
+// POST /api/v1/redeem
+func (h *RedeemHandler) Redeem(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var req RedeemRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	result, err := h.redeemService.Redeem(c.Request.Context(), subject.UserID, req.Code)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.RedeemCodeFromService(result))
+}
+
+// GetHistory returns the user's redemption history
+// GET /api/v1/redeem/history
+func (h *RedeemHandler) GetHistory(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	// Default limit is 25
+	limit := 25
+
+	codes, err := h.redeemService.GetUserHistory(c.Request.Context(), subject.UserID, limit)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.RedeemCode, 0, len(codes))
+	for i := range codes {
+		out = append(out, *dto.RedeemCodeFromService(&codes[i]))
+	}
+	response.Success(c, out)
+}

backend/internal/handler/request_body_limit.go

@@ -0,0 +1,27 @@
+package handler
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+)
+
+func extractMaxBytesError(err error) (*http.MaxBytesError, bool) {
+	var maxErr *http.MaxBytesError
+	if errors.As(err, &maxErr) {
+		return maxErr, true
+	}
+	return nil, false
+}
+
+func formatBodyLimit(limit int64) string {
+	const mb = 1024 * 1024
+	if limit >= mb {
+		return fmt.Sprintf("%dMB", limit/mb)
+	}
+	return fmt.Sprintf("%dB", limit)
+}
+
+func buildBodyTooLargeMessage(limit int64) string {
+	return fmt.Sprintf("Request body too large, limit is %s", formatBodyLimit(limit))
+}

backend/internal/handler/request_body_limit_test.go

@@ -0,0 +1,45 @@
+package handler
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRequestBodyLimitTooLarge(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	limit := int64(16)
+	router := gin.New()
+	router.Use(middleware.RequestBodyLimit(limit))
+	router.POST("/test", func(c *gin.Context) {
+		_, err := io.ReadAll(c.Request.Body)
+		if err != nil {
+			if maxErr, ok := extractMaxBytesError(err); ok {
+				c.JSON(http.StatusRequestEntityTooLarge, gin.H{
+					"error": buildBodyTooLargeMessage(maxErr.Limit),
+				})
+				return
+			}
+			c.JSON(http.StatusBadRequest, gin.H{
+				"error": "read_failed",
+			})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true})
+	})
+
+	payload := bytes.Repeat([]byte("a"), int(limit+1))
+	req := httptest.NewRequest(http.MethodPost, "/test", bytes.NewReader(payload))
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusRequestEntityTooLarge, recorder.Code)
+	require.Contains(t, recorder.Body.String(), buildBodyTooLargeMessage(limit))
+}

backend/internal/handler/setting_handler.go

@@ -0,0 +1,49 @@
+package handler
+
+import (
+	"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"
+)
+
+// SettingHandler 公开设置处理器（无需认证）
+type SettingHandler struct {
+	settingService *service.SettingService
+	version        string
+}
+
+// NewSettingHandler 创建公开设置处理器
+func NewSettingHandler(settingService *service.SettingService, version string) *SettingHandler {
+	return &SettingHandler{
+		settingService: settingService,
+		version:        version,
+	}
+}
+
+// GetPublicSettings 获取公开设置
+// GET /api/v1/settings/public
+func (h *SettingHandler) GetPublicSettings(c *gin.Context) {
+	settings, err := h.settingService.GetPublicSettings(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, dto.PublicSettings{
+		RegistrationEnabled: settings.RegistrationEnabled,
+		EmailVerifyEnabled:  settings.EmailVerifyEnabled,
+		TurnstileEnabled:    settings.TurnstileEnabled,
+		TurnstileSiteKey:    settings.TurnstileSiteKey,
+		SiteName:            settings.SiteName,
+		SiteLogo:            settings.SiteLogo,
+		SiteSubtitle:        settings.SiteSubtitle,
+		APIBaseURL:          settings.APIBaseURL,
+		ContactInfo:         settings.ContactInfo,
+		DocURL:              settings.DocURL,
+		HomeContent:         settings.HomeContent,
+		LinuxDoOAuthEnabled: settings.LinuxDoOAuthEnabled,
+		Version:             h.version,
+	})
+}

backend/internal/handler/subscription_handler.go

@@ -0,0 +1,188 @@
+package handler
+
+import (
+	"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"
+)
+
+// SubscriptionSummaryItem represents a subscription item in summary
+type SubscriptionSummaryItem struct {
+	ID              int64   `json:"id"`
+	GroupID         int64   `json:"group_id"`
+	GroupName       string  `json:"group_name"`
+	Status          string  `json:"status"`
+	DailyUsedUSD    float64 `json:"daily_used_usd,omitempty"`
+	DailyLimitUSD   float64 `json:"daily_limit_usd,omitempty"`
+	WeeklyUsedUSD   float64 `json:"weekly_used_usd,omitempty"`
+	WeeklyLimitUSD  float64 `json:"weekly_limit_usd,omitempty"`
+	MonthlyUsedUSD  float64 `json:"monthly_used_usd,omitempty"`
+	MonthlyLimitUSD float64 `json:"monthly_limit_usd,omitempty"`
+	ExpiresAt       *string `json:"expires_at,omitempty"`
+}
+
+// SubscriptionProgressInfo represents subscription with progress info
+type SubscriptionProgressInfo struct {
+	Subscription *dto.UserSubscription         `json:"subscription"`
+	Progress     *service.SubscriptionProgress `json:"progress"`
+}
+
+// SubscriptionHandler handles user subscription operations
+type SubscriptionHandler struct {
+	subscriptionService *service.SubscriptionService
+}
+
+// NewSubscriptionHandler creates a new user subscription handler
+func NewSubscriptionHandler(subscriptionService *service.SubscriptionService) *SubscriptionHandler {
+	return &SubscriptionHandler{
+		subscriptionService: subscriptionService,
+	}
+}
+
+// List handles listing current user's subscriptions
+// GET /api/v1/subscriptions
+func (h *SubscriptionHandler) List(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not found in context")
+		return
+	}
+
+	subscriptions, err := h.subscriptionService.ListUserSubscriptions(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.UserSubscription, 0, len(subscriptions))
+	for i := range subscriptions {
+		out = append(out, *dto.UserSubscriptionFromService(&subscriptions[i]))
+	}
+	response.Success(c, out)
+}
+
+// GetActive handles getting current user's active subscriptions
+// GET /api/v1/subscriptions/active
+func (h *SubscriptionHandler) GetActive(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not found in context")
+		return
+	}
+
+	subscriptions, err := h.subscriptionService.ListActiveUserSubscriptions(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.UserSubscription, 0, len(subscriptions))
+	for i := range subscriptions {
+		out = append(out, *dto.UserSubscriptionFromService(&subscriptions[i]))
+	}
+	response.Success(c, out)
+}
+
+// GetProgress handles getting subscription progress for current user
+// GET /api/v1/subscriptions/progress
+func (h *SubscriptionHandler) GetProgress(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not found in context")
+		return
+	}
+
+	// Get all active subscriptions with progress
+	subscriptions, err := h.subscriptionService.ListActiveUserSubscriptions(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	result := make([]SubscriptionProgressInfo, 0, len(subscriptions))
+	for i := range subscriptions {
+		sub := &subscriptions[i]
+		progress, err := h.subscriptionService.GetSubscriptionProgress(c.Request.Context(), sub.ID)
+		if err != nil {
+			// Skip subscriptions with errors
+			continue
+		}
+		result = append(result, SubscriptionProgressInfo{
+			Subscription: dto.UserSubscriptionFromService(sub),
+			Progress:     progress,
+		})
+	}
+
+	response.Success(c, result)
+}
+
+// GetSummary handles getting a summary of current user's subscription status
+// GET /api/v1/subscriptions/summary
+func (h *SubscriptionHandler) GetSummary(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not found in context")
+		return
+	}
+
+	// Get all active subscriptions
+	subscriptions, err := h.subscriptionService.ListActiveUserSubscriptions(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var totalUsed float64
+	items := make([]SubscriptionSummaryItem, 0, len(subscriptions))
+
+	for _, sub := range subscriptions {
+		item := SubscriptionSummaryItem{
+			ID:             sub.ID,
+			GroupID:        sub.GroupID,
+			Status:         sub.Status,
+			DailyUsedUSD:   sub.DailyUsageUSD,
+			WeeklyUsedUSD:  sub.WeeklyUsageUSD,
+			MonthlyUsedUSD: sub.MonthlyUsageUSD,
+		}
+
+		// Add group info if preloaded
+		if sub.Group != nil {
+			item.GroupName = sub.Group.Name
+			if sub.Group.DailyLimitUSD != nil {
+				item.DailyLimitUSD = *sub.Group.DailyLimitUSD
+			}
+			if sub.Group.WeeklyLimitUSD != nil {
+				item.WeeklyLimitUSD = *sub.Group.WeeklyLimitUSD
+			}
+			if sub.Group.MonthlyLimitUSD != nil {
+				item.MonthlyLimitUSD = *sub.Group.MonthlyLimitUSD
+			}
+		}
+
+		// Format expiration time
+		if !sub.ExpiresAt.IsZero() {
+			formatted := sub.ExpiresAt.Format("2006-01-02T15:04:05Z07:00")
+			item.ExpiresAt = &formatted
+		}
+
+		// Track total usage (use monthly as the most comprehensive)
+		totalUsed += sub.MonthlyUsageUSD
+
+		items = append(items, item)
+	}
+
+	summary := struct {
+		ActiveCount   int                       `json:"active_count"`
+		TotalUsedUSD  float64                   `json:"total_used_usd"`
+		Subscriptions []SubscriptionSummaryItem `json:"subscriptions"`
+	}{
+		ActiveCount:   len(subscriptions),
+		TotalUsedUSD:  totalUsed,
+		Subscriptions: items,
+	}
+
+	response.Success(c, summary)
+}

backend/internal/handler/usage_handler.go

@@ -0,0 +1,402 @@
+package handler
+
+import (
+	"strconv"
+	"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/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// UsageHandler handles usage-related requests
+type UsageHandler struct {
+	usageService  *service.UsageService
+	apiKeyService *service.APIKeyService
+}
+
+// NewUsageHandler creates a new UsageHandler
+func NewUsageHandler(usageService *service.UsageService, apiKeyService *service.APIKeyService) *UsageHandler {
+	return &UsageHandler{
+		usageService:  usageService,
+		apiKeyService: apiKeyService,
+	}
+}
+
+// List handles listing usage records with pagination
+// GET /api/v1/usage
+func (h *UsageHandler) List(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+
+	var apiKeyID int64
+	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
+		}
+
+		// [Security Fix] Verify API Key ownership to prevent horizontal privilege escalation
+		apiKey, err := h.apiKeyService.GetByID(c.Request.Context(), id)
+		if err != nil {
+			response.ErrorFrom(c, err)
+			return
+		}
+		if apiKey.UserID != subject.UserID {
+			response.Forbidden(c, "Not authorized to access this API key's usage records")
+			return
+		}
+
+		apiKeyID = id
+	}
+
+	// Parse additional filters
+	model := c.Query("model")
+
+	var stream *bool
+	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
+		}
+		// Set end time to end of day
+		t = t.Add(24*time.Hour - time.Nanosecond)
+		endTime = &t
+	}
+
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
+	filters := usagestats.UsageLogFilters{
+		UserID:      subject.UserID, // Always filter by current user for security
+		APIKeyID:    apiKeyID,
+		Model:       model,
+		Stream:      stream,
+		BillingType: billingType,
+		StartTime:   startTime,
+		EndTime:     endTime,
+	}
+
+	records, result, err := h.usageService.ListWithFilters(c.Request.Context(), params, filters)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]dto.UsageLog, 0, len(records))
+	for i := range records {
+		out = append(out, *dto.UsageLogFromService(&records[i]))
+	}
+	response.Paginated(c, out, result.Total, page, pageSize)
+}
+
+// GetByID handles getting a single usage record
+// GET /api/v1/usage/:id
+func (h *UsageHandler) GetByID(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	usageID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid usage ID")
+		return
+	}
+
+	record, err := h.usageService.GetByID(c.Request.Context(), usageID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// 验证所有权
+	if record.UserID != subject.UserID {
+		response.Forbidden(c, "Not authorized to access this record")
+		return
+	}
+
+	response.Success(c, dto.UsageLogFromService(record))
+}
+
+// Stats handles getting usage statistics
+// GET /api/v1/usage/stats
+func (h *UsageHandler) Stats(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var apiKeyID int64
+	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
+		}
+
+		// [Security Fix] Verify API Key ownership to prevent horizontal privilege escalation
+		apiKey, err := h.apiKeyService.GetByID(c.Request.Context(), id)
+		if err != nil {
+			response.NotFound(c, "API key not found")
+			return
+		}
+		if apiKey.UserID != subject.UserID {
+			response.Forbidden(c, "Not authorized to access this API key's statistics")
+			return
+		}
+
+		apiKeyID = id
+	}
+
+	// 获取时间范围参数
+	userTZ := c.Query("timezone") // Get user's timezone from request
+	now := timezone.NowInUserLocation(userTZ)
+	var startTime, endTime time.Time
+
+	// 优先使用 start_date 和 end_date 参数
+	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
+		}
+		// 设置结束时间为当天结束
+		endTime = endTime.Add(24*time.Hour - time.Nanosecond)
+	} else {
+		// 使用 period 参数
+		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
+	}
+
+	var stats *service.UsageStats
+	var err error
+	if apiKeyID > 0 {
+		stats, err = h.usageService.GetStatsByAPIKey(c.Request.Context(), apiKeyID, startTime, endTime)
+	} else {
+		stats, err = h.usageService.GetStatsByUser(c.Request.Context(), subject.UserID, startTime, endTime)
+	}
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, stats)
+}
+
+// parseUserTimeRange parses start_date, end_date query parameters for user dashboard
+// Uses user's timezone if provided, otherwise falls back to server timezone
+func parseUserTimeRange(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
+}
+
+// DashboardStats handles getting user dashboard statistics
+// GET /api/v1/usage/dashboard/stats
+func (h *UsageHandler) DashboardStats(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	stats, err := h.usageService.GetUserDashboardStats(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, stats)
+}
+
+// DashboardTrend handles getting user usage trend data
+// GET /api/v1/usage/dashboard/trend
+func (h *UsageHandler) DashboardTrend(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	startTime, endTime := parseUserTimeRange(c)
+	granularity := c.DefaultQuery("granularity", "day")
+
+	trend, err := h.usageService.GetUserUsageTrendByUserID(c.Request.Context(), subject.UserID, startTime, endTime, granularity)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	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,
+	})
+}
+
+// DashboardModels handles getting user model usage statistics
+// GET /api/v1/usage/dashboard/models
+func (h *UsageHandler) DashboardModels(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	startTime, endTime := parseUserTimeRange(c)
+
+	stats, err := h.usageService.GetUserModelStats(c.Request.Context(), subject.UserID, startTime, endTime)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	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"),
+	})
+}
+
+// BatchAPIKeysUsageRequest represents the request for batch API keys usage
+type BatchAPIKeysUsageRequest struct {
+	APIKeyIDs []int64 `json:"api_key_ids" binding:"required"`
+}
+
+// DashboardAPIKeysUsage handles getting usage stats for user's own API keys
+// POST /api/v1/usage/dashboard/api-keys-usage
+func (h *UsageHandler) DashboardAPIKeysUsage(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var req BatchAPIKeysUsageRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if len(req.APIKeyIDs) == 0 {
+		response.Success(c, gin.H{"stats": map[string]any{}})
+		return
+	}
+
+	// Limit the number of API key IDs to prevent SQL parameter overflow
+	if len(req.APIKeyIDs) > 100 {
+		response.BadRequest(c, "Too many API key IDs (maximum 100 allowed)")
+		return
+	}
+
+	validAPIKeyIDs, err := h.apiKeyService.VerifyOwnership(c.Request.Context(), subject.UserID, req.APIKeyIDs)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	if len(validAPIKeyIDs) == 0 {
+		response.Success(c, gin.H{"stats": map[string]any{}})
+		return
+	}
+
+	stats, err := h.usageService.GetBatchAPIKeyUsageStats(c.Request.Context(), validAPIKeyIDs)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"stats": stats})
+}

backend/internal/handler/user_handler.go

@@ -0,0 +1,112 @@
+package handler
+
+import (
+	"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"
+)
+
+// UserHandler handles user-related requests
+type UserHandler struct {
+	userService *service.UserService
+}
+
+// NewUserHandler creates a new UserHandler
+func NewUserHandler(userService *service.UserService) *UserHandler {
+	return &UserHandler{
+		userService: userService,
+	}
+}
+
+// ChangePasswordRequest represents the change password request payload
+type ChangePasswordRequest struct {
+	OldPassword string `json:"old_password" binding:"required"`
+	NewPassword string `json:"new_password" binding:"required,min=6"`
+}
+
+// UpdateProfileRequest represents the update profile request payload
+type UpdateProfileRequest struct {
+	Username *string `json:"username"`
+}
+
+// GetProfile handles getting user profile
+// GET /api/v1/users/me
+func (h *UserHandler) GetProfile(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	userData, err := h.userService.GetByID(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// 清空notes字段，普通用户不应看到备注
+	userData.Notes = ""
+
+	response.Success(c, dto.UserFromService(userData))
+}
+
+// ChangePassword handles changing user password
+// POST /api/v1/users/me/password
+func (h *UserHandler) ChangePassword(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var req ChangePasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	svcReq := service.ChangePasswordRequest{
+		CurrentPassword: req.OldPassword,
+		NewPassword:     req.NewPassword,
+	}
+	err := h.userService.ChangePassword(c.Request.Context(), subject.UserID, svcReq)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Password changed successfully"})
+}
+
+// UpdateProfile handles updating user profile
+// PUT /api/v1/users/me
+func (h *UserHandler) UpdateProfile(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var req UpdateProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	svcReq := service.UpdateProfileRequest{
+		Username: req.Username,
+	}
+	updatedUser, err := h.userService.UpdateProfile(c.Request.Context(), subject.UserID, svcReq)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// 清空notes字段，普通用户不应看到备注
+	updatedUser.Notes = ""
+
+	response.Success(c, dto.UserFromService(updatedUser))
+}

backend/internal/handler/wire.go

@@ -0,0 +1,123 @@
+package handler
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/handler/admin"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/google/wire"
+)
+
+// ProvideAdminHandlers creates the AdminHandlers struct
+func ProvideAdminHandlers(
+	dashboardHandler *admin.DashboardHandler,
+	userHandler *admin.UserHandler,
+	groupHandler *admin.GroupHandler,
+	accountHandler *admin.AccountHandler,
+	oauthHandler *admin.OAuthHandler,
+	openaiOAuthHandler *admin.OpenAIOAuthHandler,
+	geminiOAuthHandler *admin.GeminiOAuthHandler,
+	antigravityOAuthHandler *admin.AntigravityOAuthHandler,
+	proxyHandler *admin.ProxyHandler,
+	redeemHandler *admin.RedeemHandler,
+	promoHandler *admin.PromoHandler,
+	settingHandler *admin.SettingHandler,
+	opsHandler *admin.OpsHandler,
+	systemHandler *admin.SystemHandler,
+	subscriptionHandler *admin.SubscriptionHandler,
+	usageHandler *admin.UsageHandler,
+	userAttributeHandler *admin.UserAttributeHandler,
+) *AdminHandlers {
+	return &AdminHandlers{
+		Dashboard:        dashboardHandler,
+		User:             userHandler,
+		Group:            groupHandler,
+		Account:          accountHandler,
+		OAuth:            oauthHandler,
+		OpenAIOAuth:      openaiOAuthHandler,
+		GeminiOAuth:      geminiOAuthHandler,
+		AntigravityOAuth: antigravityOAuthHandler,
+		Proxy:            proxyHandler,
+		Redeem:           redeemHandler,
+		Promo:            promoHandler,
+		Setting:          settingHandler,
+		Ops:              opsHandler,
+		System:           systemHandler,
+		Subscription:     subscriptionHandler,
+		Usage:            usageHandler,
+		UserAttribute:    userAttributeHandler,
+	}
+}
+
+// ProvideSystemHandler creates admin.SystemHandler with UpdateService
+func ProvideSystemHandler(updateService *service.UpdateService) *admin.SystemHandler {
+	return admin.NewSystemHandler(updateService)
+}
+
+// ProvideSettingHandler creates SettingHandler with version from BuildInfo
+func ProvideSettingHandler(settingService *service.SettingService, buildInfo BuildInfo) *SettingHandler {
+	return NewSettingHandler(settingService, buildInfo.Version)
+}
+
+// ProvideHandlers creates the Handlers struct
+func ProvideHandlers(
+	authHandler *AuthHandler,
+	userHandler *UserHandler,
+	apiKeyHandler *APIKeyHandler,
+	usageHandler *UsageHandler,
+	redeemHandler *RedeemHandler,
+	subscriptionHandler *SubscriptionHandler,
+	adminHandlers *AdminHandlers,
+	gatewayHandler *GatewayHandler,
+	openaiGatewayHandler *OpenAIGatewayHandler,
+	settingHandler *SettingHandler,
+) *Handlers {
+	return &Handlers{
+		Auth:          authHandler,
+		User:          userHandler,
+		APIKey:        apiKeyHandler,
+		Usage:         usageHandler,
+		Redeem:        redeemHandler,
+		Subscription:  subscriptionHandler,
+		Admin:         adminHandlers,
+		Gateway:       gatewayHandler,
+		OpenAIGateway: openaiGatewayHandler,
+		Setting:       settingHandler,
+	}
+}
+
+// ProviderSet is the Wire provider set for all handlers
+var ProviderSet = wire.NewSet(
+	// Top-level handlers
+	NewAuthHandler,
+	NewUserHandler,
+	NewAPIKeyHandler,
+	NewUsageHandler,
+	NewRedeemHandler,
+	NewSubscriptionHandler,
+	NewGatewayHandler,
+	NewOpenAIGatewayHandler,
+	ProvideSettingHandler,
+
+	// Admin handlers
+	admin.NewDashboardHandler,
+	admin.NewUserHandler,
+	admin.NewGroupHandler,
+	admin.NewAccountHandler,
+	admin.NewOAuthHandler,
+	admin.NewOpenAIOAuthHandler,
+	admin.NewGeminiOAuthHandler,
+	admin.NewAntigravityOAuthHandler,
+	admin.NewProxyHandler,
+	admin.NewRedeemHandler,
+	admin.NewPromoHandler,
+	admin.NewSettingHandler,
+	admin.NewOpsHandler,
+	ProvideSystemHandler,
+	admin.NewSubscriptionHandler,
+	admin.NewUsageHandler,
+	admin.NewUserAttributeHandler,
+
+	// AdminHandlers and Handlers constructors
+	ProvideAdminHandlers,
+	ProvideHandlers,
+)