merge: 合并上游 v0.1.86 到 main 分支

2026-04-13 03:14:46 +08:00 · 2026-02-25 19:02:10 +08:00
parent 1cdaf33272 ded9b6c14e
commit 496173da1f
469 changed files with 65006 additions and 3674 deletions
--- a/backend/internal/handler/admin/account_data.go
+++ b/backend/internal/handler/admin/account_data.go
@@ -175,22 +175,28 @@ func (h *AccountHandler) ImportData(c *gin.Context) {
 		return
 	}

-	dataPayload := req.Data
-	if err := validateDataHeader(dataPayload); err != nil {
+	if err := validateDataHeader(req.Data); err != nil {
 		response.BadRequest(c, err.Error())
 		return
 	}

+	executeAdminIdempotentJSON(c, "admin.accounts.import_data", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		return h.importData(ctx, req)
+	})
+}
+
+func (h *AccountHandler) importData(ctx context.Context, req DataImportRequest) (DataImportResult, error) {
 	skipDefaultGroupBind := true
 	if req.SkipDefaultGroupBind != nil {
 		skipDefaultGroupBind = *req.SkipDefaultGroupBind
 	}

+	dataPayload := req.Data
 	result := DataImportResult{}
-	existingProxies, err := h.listAllProxies(c.Request.Context())
+
+	existingProxies, err := h.listAllProxies(ctx)
 	if err != nil {
-		response.ErrorFrom(c, err)
-		return
+		return result, err
 	}

 	proxyKeyToID := make(map[string]int64, len(existingProxies))
@@ -221,8 +227,8 @@ func (h *AccountHandler) ImportData(c *gin.Context) {
 			proxyKeyToID[key] = existingID
 			result.ProxyReused++
 			if normalizedStatus != "" {
-				if proxy, err := h.adminService.GetProxy(c.Request.Context(), existingID); err == nil && proxy != nil && proxy.Status != normalizedStatus {
-					_, _ = h.adminService.UpdateProxy(c.Request.Context(), existingID, &service.UpdateProxyInput{
+				if proxy, getErr := h.adminService.GetProxy(ctx, existingID); getErr == nil && proxy != nil && proxy.Status != normalizedStatus {
+					_, _ = h.adminService.UpdateProxy(ctx, existingID, &service.UpdateProxyInput{
 						Status: normalizedStatus,
 					})
 				}
@@ -230,7 +236,7 @@ func (h *AccountHandler) ImportData(c *gin.Context) {
 			continue
 		}

-		created, err := h.adminService.CreateProxy(c.Request.Context(), &service.CreateProxyInput{
+		created, createErr := h.adminService.CreateProxy(ctx, &service.CreateProxyInput{
 			Name:     defaultProxyName(item.Name),
 			Protocol: item.Protocol,
 			Host:     item.Host,
@@ -238,13 +244,13 @@ func (h *AccountHandler) ImportData(c *gin.Context) {
 			Username: item.Username,
 			Password: item.Password,
 		})
-		if err != nil {
+		if createErr != nil {
 			result.ProxyFailed++
 			result.Errors = append(result.Errors, DataImportError{
 				Kind:     "proxy",
 				Name:     item.Name,
 				ProxyKey: key,
-				Message:  err.Error(),
+				Message:  createErr.Error(),
 			})
 			continue
 		}
@@ -252,7 +258,7 @@ func (h *AccountHandler) ImportData(c *gin.Context) {
 		result.ProxyCreated++

 		if normalizedStatus != "" && normalizedStatus != created.Status {
-			_, _ = h.adminService.UpdateProxy(c.Request.Context(), created.ID, &service.UpdateProxyInput{
+			_, _ = h.adminService.UpdateProxy(ctx, created.ID, &service.UpdateProxyInput{
 				Status: normalizedStatus,
 			})
 		}
@@ -303,7 +309,7 @@ func (h *AccountHandler) ImportData(c *gin.Context) {
 			SkipDefaultGroupBind: skipDefaultGroupBind,
 		}

-		if _, err := h.adminService.CreateAccount(c.Request.Context(), accountInput); err != nil {
+		if _, err := h.adminService.CreateAccount(ctx, accountInput); err != nil {
 			result.AccountFailed++
 			result.Errors = append(result.Errors, DataImportError{
 				Kind:    "account",
@@ -315,7 +321,7 @@ func (h *AccountHandler) ImportData(c *gin.Context) {
 		result.AccountCreated++
 	}

-	response.Success(c, result)
+	return result, nil
 }

 func (h *AccountHandler) listAllProxies(ctx context.Context) ([]service.Proxy, error) {
--- a/backend/internal/handler/admin/account_handler.go
+++ b/backend/internal/handler/admin/account_handler.go
@@ -2,7 +2,13 @@
 package admin

 import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
 	"errors"
+	"fmt"
+	"net/http"
 	"strconv"
 	"strings"
 	"sync"
@@ -149,6 +155,44 @@ type AccountWithConcurrency struct {
 	ActiveSessions    *int     `json:"active_sessions,omitempty"`     // 当前活跃会话数
 }

+func (h *AccountHandler) buildAccountResponseWithRuntime(ctx context.Context, account *service.Account) AccountWithConcurrency {
+	item := AccountWithConcurrency{
+		Account:            dto.AccountFromService(account),
+		CurrentConcurrency: 0,
+	}
+	if account == nil {
+		return item
+	}
+
+	if h.concurrencyService != nil {
+		if counts, err := h.concurrencyService.GetAccountConcurrencyBatch(ctx, []int64{account.ID}); err == nil {
+			item.CurrentConcurrency = counts[account.ID]
+		}
+	}
+
+	if account.IsAnthropicOAuthOrSetupToken() {
+		if h.accountUsageService != nil && account.GetWindowCostLimit() > 0 {
+			startTime := account.GetCurrentWindowStartTime()
+			if stats, err := h.accountUsageService.GetAccountWindowStats(ctx, account.ID, startTime); err == nil && stats != nil {
+				cost := stats.StandardCost
+				item.CurrentWindowCost = &cost
+			}
+		}
+
+		if h.sessionLimitCache != nil && account.GetMaxSessions() > 0 {
+			idleTimeout := time.Duration(account.GetSessionIdleTimeoutMinutes()) * time.Minute
+			idleTimeouts := map[int64]time.Duration{account.ID: idleTimeout}
+			if sessions, err := h.sessionLimitCache.GetActiveSessionCountBatch(ctx, []int64{account.ID}, idleTimeouts); err == nil {
+				if count, ok := sessions[account.ID]; ok {
+					item.ActiveSessions = &count
+				}
+			}
+		}
+	}
+
+	return item
+}
+
 // List handles listing all accounts with pagination
 // GET /api/v1/admin/accounts
 func (h *AccountHandler) List(c *gin.Context) {
@@ -269,9 +313,71 @@ func (h *AccountHandler) List(c *gin.Context) {
 		result[i] = item
 	}

+	etag := buildAccountsListETag(result, total, page, pageSize, platform, accountType, status, search)
+	if etag != "" {
+		c.Header("ETag", etag)
+		c.Header("Vary", "If-None-Match")
+		if ifNoneMatchMatched(c.GetHeader("If-None-Match"), etag) {
+			c.Status(http.StatusNotModified)
+			return
+		}
+	}
+
 	response.Paginated(c, result, total, page, pageSize)
 }

+func buildAccountsListETag(
+	items []AccountWithConcurrency,
+	total int64,
+	page, pageSize int,
+	platform, accountType, status, search string,
+) string {
+	payload := struct {
+		Total       int64                    `json:"total"`
+		Page        int                      `json:"page"`
+		PageSize    int                      `json:"page_size"`
+		Platform    string                   `json:"platform"`
+		AccountType string                   `json:"type"`
+		Status      string                   `json:"status"`
+		Search      string                   `json:"search"`
+		Items       []AccountWithConcurrency `json:"items"`
+	}{
+		Total:       total,
+		Page:        page,
+		PageSize:    pageSize,
+		Platform:    platform,
+		AccountType: accountType,
+		Status:      status,
+		Search:      search,
+		Items:       items,
+	}
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return ""
+	}
+	sum := sha256.Sum256(raw)
+	return "\"" + hex.EncodeToString(sum[:]) + "\""
+}
+
+func ifNoneMatchMatched(ifNoneMatch, etag string) bool {
+	if etag == "" || ifNoneMatch == "" {
+		return false
+	}
+	for _, token := range strings.Split(ifNoneMatch, ",") {
+		candidate := strings.TrimSpace(token)
+		if candidate == "*" {
+			return true
+		}
+		if candidate == etag {
+			return true
+		}
+		if strings.HasPrefix(candidate, "W/") && strings.TrimPrefix(candidate, "W/") == etag {
+			return true
+		}
+	}
+	return false
+}
+
 // GetByID handles getting an account by ID
 // GET /api/v1/admin/accounts/:id
 func (h *AccountHandler) GetByID(c *gin.Context) {
@@ -287,7 +393,51 @@ func (h *AccountHandler) GetByID(c *gin.Context) {
 		return
 	}

-	response.Success(c, dto.AccountFromService(account))
+	response.Success(c, h.buildAccountResponseWithRuntime(c.Request.Context(), account))
+}
+
+// CheckMixedChannel handles checking mixed channel risk for account-group binding.
+// POST /api/v1/admin/accounts/check-mixed-channel
+func (h *AccountHandler) CheckMixedChannel(c *gin.Context) {
+	var req CheckMixedChannelRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if len(req.GroupIDs) == 0 {
+		response.Success(c, gin.H{"has_risk": false})
+		return
+	}
+
+	accountID := int64(0)
+	if req.AccountID != nil {
+		accountID = *req.AccountID
+	}
+
+	err := h.adminService.CheckMixedChannelRisk(c.Request.Context(), accountID, req.Platform, req.GroupIDs)
+	if err != nil {
+		var mixedErr *service.MixedChannelError
+		if errors.As(err, &mixedErr) {
+			response.Success(c, gin.H{
+				"has_risk": true,
+				"error":    "mixed_channel_warning",
+				"message":  mixedErr.Error(),
+				"details": gin.H{
+					"group_id":         mixedErr.GroupID,
+					"group_name":       mixedErr.GroupName,
+					"current_platform": mixedErr.CurrentPlatform,
+					"other_platform":   mixedErr.OtherPlatform,
+				},
+			})
+			return
+		}
+
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"has_risk": false})
 }

 // CheckMixedChannel handles checking mixed channel risk for account-group binding.
@@ -350,21 +500,27 @@ func (h *AccountHandler) Create(c *gin.Context) {
 	// 确定是否跳过混合渠道检查
 	skipCheck := req.ConfirmMixedChannelRisk != nil && *req.ConfirmMixedChannelRisk

-	account, err := h.adminService.CreateAccount(c.Request.Context(), &service.CreateAccountInput{
-		Name:                  req.Name,
-		Notes:                 req.Notes,
-		Platform:              req.Platform,
-		Type:                  req.Type,
-		Credentials:           req.Credentials,
-		Extra:                 req.Extra,
-		ProxyID:               req.ProxyID,
-		Concurrency:           req.Concurrency,
-		Priority:              req.Priority,
-		RateMultiplier:        req.RateMultiplier,
-		GroupIDs:              req.GroupIDs,
-		ExpiresAt:             req.ExpiresAt,
-		AutoPauseOnExpired:    req.AutoPauseOnExpired,
-		SkipMixedChannelCheck: skipCheck,
+	result, err := executeAdminIdempotent(c, "admin.accounts.create", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		account, execErr := h.adminService.CreateAccount(ctx, &service.CreateAccountInput{
+			Name:                  req.Name,
+			Notes:                 req.Notes,
+			Platform:              req.Platform,
+			Type:                  req.Type,
+			Credentials:           req.Credentials,
+			Extra:                 req.Extra,
+			ProxyID:               req.ProxyID,
+			Concurrency:           req.Concurrency,
+			Priority:              req.Priority,
+			RateMultiplier:        req.RateMultiplier,
+			GroupIDs:              req.GroupIDs,
+			ExpiresAt:             req.ExpiresAt,
+			AutoPauseOnExpired:    req.AutoPauseOnExpired,
+			SkipMixedChannelCheck: skipCheck,
+		})
+		if execErr != nil {
+			return nil, execErr
+		}
+		return h.buildAccountResponseWithRuntime(ctx, account), nil
 	})
 	if err != nil {
 		// 检查是否为混合渠道错误
@@ -378,11 +534,17 @@ func (h *AccountHandler) Create(c *gin.Context) {
 			return
 		}

+		if retryAfter := service.RetryAfterSecondsFromError(err); retryAfter > 0 {
+			c.Header("Retry-After", strconv.Itoa(retryAfter))
+		}
 		response.ErrorFrom(c, err)
 		return
 	}

-	response.Success(c, dto.AccountFromService(account))
+	if result != nil && result.Replayed {
+		c.Header("X-Idempotency-Replayed", "true")
+	}
+	response.Success(c, result.Data)
 }

 // Update handles updating an account
@@ -439,7 +601,7 @@ func (h *AccountHandler) Update(c *gin.Context) {
 		return
 	}

-	response.Success(c, dto.AccountFromService(account))
+	response.Success(c, h.buildAccountResponseWithRuntime(c.Request.Context(), account))
 }

 // Delete handles deleting an account
@@ -697,7 +859,7 @@ func (h *AccountHandler) Refresh(c *gin.Context) {
 		}
 	}

-	response.Success(c, dto.AccountFromService(updatedAccount))
+	response.Success(c, h.buildAccountResponseWithRuntime(c.Request.Context(), updatedAccount))
 }

 // GetStats handles getting account statistics
@@ -755,7 +917,7 @@ func (h *AccountHandler) ClearError(c *gin.Context) {
 		}
 	}

-	response.Success(c, dto.AccountFromService(account))
+	response.Success(c, h.buildAccountResponseWithRuntime(c.Request.Context(), account))
 }

 // BatchCreate handles batch creating accounts
@@ -769,61 +931,62 @@ func (h *AccountHandler) BatchCreate(c *gin.Context) {
 		return
 	}

-	ctx := c.Request.Context()
-	success := 0
-	failed := 0
-	results := make([]gin.H, 0, len(req.Accounts))
+	executeAdminIdempotentJSON(c, "admin.accounts.batch_create", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		success := 0
+		failed := 0
+		results := make([]gin.H, 0, len(req.Accounts))

-	for _, item := range req.Accounts {
-		if item.RateMultiplier != nil && *item.RateMultiplier < 0 {
-			failed++
+		for _, item := range req.Accounts {
+			if item.RateMultiplier != nil && *item.RateMultiplier < 0 {
+				failed++
+				results = append(results, gin.H{
+					"name":    item.Name,
+					"success": false,
+					"error":   "rate_multiplier must be >= 0",
+				})
+				continue
+			}
+
+			skipCheck := item.ConfirmMixedChannelRisk != nil && *item.ConfirmMixedChannelRisk
+
+			account, err := h.adminService.CreateAccount(ctx, &service.CreateAccountInput{
+				Name:                  item.Name,
+				Notes:                 item.Notes,
+				Platform:              item.Platform,
+				Type:                  item.Type,
+				Credentials:           item.Credentials,
+				Extra:                 item.Extra,
+				ProxyID:               item.ProxyID,
+				Concurrency:           item.Concurrency,
+				Priority:              item.Priority,
+				RateMultiplier:        item.RateMultiplier,
+				GroupIDs:              item.GroupIDs,
+				ExpiresAt:             item.ExpiresAt,
+				AutoPauseOnExpired:    item.AutoPauseOnExpired,
+				SkipMixedChannelCheck: skipCheck,
+			})
+			if err != nil {
+				failed++
+				results = append(results, gin.H{
+					"name":    item.Name,
+					"success": false,
+					"error":   err.Error(),
+				})
+				continue
+			}
+			success++
 			results = append(results, gin.H{
 				"name":    item.Name,
-				"success": false,
-				"error":   "rate_multiplier must be >= 0",
+				"id":      account.ID,
+				"success": true,
 			})
-			continue
 		}

-		skipCheck := item.ConfirmMixedChannelRisk != nil && *item.ConfirmMixedChannelRisk
-
-		account, err := h.adminService.CreateAccount(ctx, &service.CreateAccountInput{
-			Name:                  item.Name,
-			Notes:                 item.Notes,
-			Platform:              item.Platform,
-			Type:                  item.Type,
-			Credentials:           item.Credentials,
-			Extra:                 item.Extra,
-			ProxyID:               item.ProxyID,
-			Concurrency:           item.Concurrency,
-			Priority:              item.Priority,
-			RateMultiplier:        item.RateMultiplier,
-			GroupIDs:              item.GroupIDs,
-			ExpiresAt:             item.ExpiresAt,
-			AutoPauseOnExpired:    item.AutoPauseOnExpired,
-			SkipMixedChannelCheck: skipCheck,
-		})
-		if err != nil {
-			failed++
-			results = append(results, gin.H{
-				"name":    item.Name,
-				"success": false,
-				"error":   err.Error(),
-			})
-			continue
-		}
-		success++
-		results = append(results, gin.H{
-			"name":    item.Name,
-			"id":      account.ID,
-			"success": true,
-		})
-	}
-
-	response.Success(c, gin.H{
-		"success": success,
-		"failed":  failed,
-		"results": results,
+		return gin.H{
+			"success": success,
+			"failed":  failed,
+			"results": results,
+		}, nil
 	})
 }

@@ -861,57 +1024,58 @@ func (h *AccountHandler) BatchUpdateCredentials(c *gin.Context) {
 	}

 	ctx := c.Request.Context()
-	success := 0
-	failed := 0
-	results := []gin.H{}

+	// 阶段一：预验证所有账号存在，收集 credentials
+	type accountUpdate struct {
+		ID          int64
+		Credentials map[string]any
+	}
+	updates := make([]accountUpdate, 0, len(req.AccountIDs))
 	for _, accountID := range req.AccountIDs {
-		// Get account
 		account, err := h.adminService.GetAccount(ctx, accountID)
 		if err != nil {
-			failed++
-			results = append(results, gin.H{
-				"account_id": accountID,
-				"success":    false,
-				"error":      "Account not found",
-			})
-			continue
+			response.Error(c, 404, fmt.Sprintf("Account %d not found", accountID))
+			return
 		}
-
-		// Update credentials field
 		if account.Credentials == nil {
 			account.Credentials = make(map[string]any)
 		}
-
 		account.Credentials[req.Field] = req.Value
+		updates = append(updates, accountUpdate{ID: accountID, Credentials: account.Credentials})
+	}

-		// Update account
-		updateInput := &service.UpdateAccountInput{
-			Credentials: account.Credentials,
-		}
-
-		_, err = h.adminService.UpdateAccount(ctx, accountID, updateInput)
-		if err != nil {
+	// 阶段二：依次更新，返回每个账号的成功/失败明细，便于调用方重试
+	success := 0
+	failed := 0
+	successIDs := make([]int64, 0, len(updates))
+	failedIDs := make([]int64, 0, len(updates))
+	results := make([]gin.H, 0, len(updates))
+	for _, u := range updates {
+		updateInput := &service.UpdateAccountInput{Credentials: u.Credentials}
+		if _, err := h.adminService.UpdateAccount(ctx, u.ID, updateInput); err != nil {
 			failed++
+			failedIDs = append(failedIDs, u.ID)
 			results = append(results, gin.H{
-				"account_id": accountID,
+				"account_id": u.ID,
 				"success":    false,
 				"error":      err.Error(),
 			})
 			continue
 		}
-
 		success++
+		successIDs = append(successIDs, u.ID)
 		results = append(results, gin.H{
-			"account_id": accountID,
+			"account_id": u.ID,
 			"success":    true,
 		})
 	}

 	response.Success(c, gin.H{
-		"success": success,
-		"failed":  failed,
-		"results": results,
+		"success":     success,
+		"failed":      failed,
+		"success_ids": successIDs,
+		"failed_ids":  failedIDs,
+		"results":     results,
 	})
 }

@@ -1146,7 +1310,13 @@ func (h *AccountHandler) ClearRateLimit(c *gin.Context) {
 		return
 	}

-	response.Success(c, gin.H{"message": "Rate limit cleared successfully"})
+	account, err := h.adminService.GetAccount(c.Request.Context(), accountID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, h.buildAccountResponseWithRuntime(c.Request.Context(), account))
 }

 // GetTempUnschedulable handles getting temporary unschedulable status
@@ -1236,7 +1406,7 @@ func (h *AccountHandler) SetSchedulable(c *gin.Context) {
 		return
 	}

-	response.Success(c, dto.AccountFromService(account))
+	response.Success(c, h.buildAccountResponseWithRuntime(c.Request.Context(), account))
 }

 // GetAvailableModels handles getting available models for an account
@@ -1362,6 +1532,12 @@ func (h *AccountHandler) GetAvailableModels(c *gin.Context) {
 		return
 	}

+	// Handle Sora accounts
+	if account.Platform == service.PlatformSora {
+		response.Success(c, service.DefaultSoraModels(nil))
+		return
+	}
+
 	// Handle Claude/Anthropic accounts
 	// For OAuth and Setup-Token accounts: return default models
 	if account.IsOAuth() {
--- a/backend/internal/handler/admin/account_handler_passthrough_test.go
+++ b/backend/internal/handler/admin/account_handler_passthrough_test.go
@@ -0,0 +1,66 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAccountHandler_Create_AnthropicAPIKeyPassthroughExtraForwarded(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	adminSvc := newStubAdminService()
+	handler := NewAccountHandler(
+		adminSvc,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+		nil,
+	)
+
+	router := gin.New()
+	router.POST("/api/v1/admin/accounts", handler.Create)
+
+	body := map[string]any{
+		"name":     "anthropic-key-1",
+		"platform": "anthropic",
+		"type":     "apikey",
+		"credentials": map[string]any{
+			"api_key":  "sk-ant-xxx",
+			"base_url": "https://api.anthropic.com",
+		},
+		"extra": map[string]any{
+			"anthropic_passthrough": true,
+		},
+		"concurrency": 1,
+		"priority":    1,
+	}
+	raw, err := json.Marshal(body)
+	require.NoError(t, err)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/accounts", bytes.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.Len(t, adminSvc.createdAccounts, 1)
+
+	created := adminSvc.createdAccounts[0]
+	require.Equal(t, "anthropic", created.Platform)
+	require.Equal(t, "apikey", created.Type)
+	require.NotNil(t, created.Extra)
+	require.Equal(t, true, created.Extra["anthropic_passthrough"])
+}
--- a/backend/internal/handler/admin/admin_basic_handlers_test.go
+++ b/backend/internal/handler/admin/admin_basic_handlers_test.go
@@ -47,6 +47,7 @@ func setupAdminRouter() (*gin.Engine, *stubAdminService) {
 	router.DELETE("/api/v1/admin/proxies/:id", proxyHandler.Delete)
 	router.POST("/api/v1/admin/proxies/batch-delete", proxyHandler.BatchDelete)
 	router.POST("/api/v1/admin/proxies/:id/test", proxyHandler.Test)
+	router.POST("/api/v1/admin/proxies/:id/quality-check", proxyHandler.CheckQuality)
 	router.GET("/api/v1/admin/proxies/:id/stats", proxyHandler.GetStats)
 	router.GET("/api/v1/admin/proxies/:id/accounts", proxyHandler.GetProxyAccounts)

@@ -208,6 +209,11 @@ func TestProxyHandlerEndpoints(t *testing.T) {
 	router.ServeHTTP(rec, req)
 	require.Equal(t, http.StatusOK, rec.Code)

+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/admin/proxies/4/quality-check", nil)
+	router.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
 	rec = httptest.NewRecorder()
 	req = httptest.NewRequest(http.MethodGet, "/api/v1/admin/proxies/4/stats", nil)
 	router.ServeHTTP(rec, req)
--- a/backend/internal/handler/admin/admin_helpers_test.go
+++ b/backend/internal/handler/admin/admin_helpers_test.go
@@ -58,6 +58,96 @@ func TestParseOpsDuration(t *testing.T) {
 	require.False(t, ok)
 }

+func TestParseOpsOpenAITokenStatsDuration(t *testing.T) {
+	tests := []struct {
+		input string
+		want  time.Duration
+		ok    bool
+	}{
+		{input: "30m", want: 30 * time.Minute, ok: true},
+		{input: "1h", want: time.Hour, ok: true},
+		{input: "1d", want: 24 * time.Hour, ok: true},
+		{input: "15d", want: 15 * 24 * time.Hour, ok: true},
+		{input: "30d", want: 30 * 24 * time.Hour, ok: true},
+		{input: "7d", want: 0, ok: false},
+	}
+
+	for _, tt := range tests {
+		got, ok := parseOpsOpenAITokenStatsDuration(tt.input)
+		require.Equal(t, tt.ok, ok, "input=%s", tt.input)
+		require.Equal(t, tt.want, got, "input=%s", tt.input)
+	}
+}
+
+func TestParseOpsOpenAITokenStatsFilter_Defaults(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+
+	before := time.Now().UTC()
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	after := time.Now().UTC()
+
+	require.NoError(t, err)
+	require.NotNil(t, filter)
+	require.Equal(t, "30d", filter.TimeRange)
+	require.Equal(t, 1, filter.Page)
+	require.Equal(t, 20, filter.PageSize)
+	require.Equal(t, 0, filter.TopN)
+	require.Nil(t, filter.GroupID)
+	require.Equal(t, "", filter.Platform)
+	require.True(t, filter.StartTime.Before(filter.EndTime))
+	require.WithinDuration(t, before.Add(-30*24*time.Hour), filter.StartTime, 2*time.Second)
+	require.WithinDuration(t, after, filter.EndTime, 2*time.Second)
+}
+
+func TestParseOpsOpenAITokenStatsFilter_WithTopN(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(
+		http.MethodGet,
+		"/?time_range=1h&platform=openai&group_id=12&top_n=50",
+		nil,
+	)
+
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	require.NoError(t, err)
+	require.Equal(t, "1h", filter.TimeRange)
+	require.Equal(t, "openai", filter.Platform)
+	require.NotNil(t, filter.GroupID)
+	require.Equal(t, int64(12), *filter.GroupID)
+	require.Equal(t, 50, filter.TopN)
+	require.Equal(t, 0, filter.Page)
+	require.Equal(t, 0, filter.PageSize)
+}
+
+func TestParseOpsOpenAITokenStatsFilter_InvalidParams(t *testing.T) {
+	tests := []string{
+		"/?time_range=7d",
+		"/?group_id=0",
+		"/?group_id=abc",
+		"/?top_n=0",
+		"/?top_n=101",
+		"/?top_n=10&page=1",
+		"/?top_n=10&page_size=20",
+		"/?page=0",
+		"/?page_size=0",
+		"/?page_size=101",
+	}
+
+	gin.SetMode(gin.TestMode)
+	for _, rawURL := range tests {
+		w := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest(http.MethodGet, rawURL, nil)
+
+		_, err := parseOpsOpenAITokenStatsFilter(c)
+		require.Error(t, err, "url=%s", rawURL)
+	}
+}
+
 func TestParseOpsTimeRange(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 	w := httptest.NewRecorder()
--- a/backend/internal/handler/admin/admin_service_stub_test.go
+++ b/backend/internal/handler/admin/admin_service_stub_test.go
@@ -348,6 +348,27 @@ func (s *stubAdminService) TestProxy(ctx context.Context, id int64) (*service.Pr
 	return &service.ProxyTestResult{Success: true, Message: "ok"}, nil
 }

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

-	stats, err := h.dashboardService.GetBatchUserUsageStats(c.Request.Context(), req.UserIDs)
+	stats, err := h.dashboardService.GetBatchUserUsageStats(c.Request.Context(), req.UserIDs, time.Time{}, time.Time{})
 	if err != nil {
 		response.Error(c, 500, "Failed to get user usage stats")
 		return
@@ -407,7 +407,7 @@ func (h *DashboardHandler) GetBatchAPIKeysUsage(c *gin.Context) {
 		return
 	}

-	stats, err := h.dashboardService.GetBatchAPIKeyUsageStats(c.Request.Context(), req.APIKeyIDs)
+	stats, err := h.dashboardService.GetBatchAPIKeyUsageStats(c.Request.Context(), req.APIKeyIDs, time.Time{}, time.Time{})
 	if err != nil {
 		response.Error(c, 500, "Failed to get API key usage stats")
 		return
--- a/backend/internal/handler/admin/gemini_oauth_handler.go
+++ b/backend/internal/handler/admin/gemini_oauth_handler.go
@@ -61,7 +61,11 @@ func (h *GeminiOAuthHandler) GenerateAuthURL(c *gin.Context) {
 	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") {
+		if strings.Contains(msg, "OAuth client not configured") ||
+			strings.Contains(msg, "requires your own OAuth Client") ||
+			strings.Contains(msg, "requires a custom OAuth Client") ||
+			strings.Contains(msg, "GEMINI_CLI_OAUTH_CLIENT_SECRET_MISSING") ||
+			strings.Contains(msg, "built-in Gemini CLI OAuth client_secret is not configured") {
 			response.BadRequest(c, "Failed to generate auth URL: "+msg)
 			return
 		}
--- a/backend/internal/handler/admin/group_handler.go
+++ b/backend/internal/handler/admin/group_handler.go
@@ -27,7 +27,7 @@ func NewGroupHandler(adminService service.AdminService) *GroupHandler {
 type CreateGroupRequest struct {
 	Name             string   `json:"name" binding:"required"`
 	Description      string   `json:"description"`
-	Platform         string   `json:"platform" binding:"omitempty,oneof=anthropic openai gemini antigravity"`
+	Platform         string   `json:"platform" binding:"omitempty,oneof=anthropic openai gemini antigravity sora"`
 	RateMultiplier   float64  `json:"rate_multiplier"`
 	IsExclusive      bool     `json:"is_exclusive"`
 	SubscriptionType string   `json:"subscription_type" binding:"omitempty,oneof=standard subscription"`
@@ -38,6 +38,10 @@ type CreateGroupRequest struct {
 	ImagePrice1K                    *float64 `json:"image_price_1k"`
 	ImagePrice2K                    *float64 `json:"image_price_2k"`
 	ImagePrice4K                    *float64 `json:"image_price_4k"`
+	SoraImagePrice360               *float64 `json:"sora_image_price_360"`
+	SoraImagePrice540               *float64 `json:"sora_image_price_540"`
+	SoraVideoPricePerRequest        *float64 `json:"sora_video_price_per_request"`
+	SoraVideoPricePerRequestHD      *float64 `json:"sora_video_price_per_request_hd"`
 	ClaudeCodeOnly                  bool     `json:"claude_code_only"`
 	FallbackGroupID                 *int64   `json:"fallback_group_id"`
 	FallbackGroupIDOnInvalidRequest *int64   `json:"fallback_group_id_on_invalid_request"`
@@ -55,7 +59,7 @@ type CreateGroupRequest struct {
 type UpdateGroupRequest struct {
 	Name             string   `json:"name"`
 	Description      string   `json:"description"`
-	Platform         string   `json:"platform" binding:"omitempty,oneof=anthropic openai gemini antigravity"`
+	Platform         string   `json:"platform" binding:"omitempty,oneof=anthropic openai gemini antigravity sora"`
 	RateMultiplier   *float64 `json:"rate_multiplier"`
 	IsExclusive      *bool    `json:"is_exclusive"`
 	Status           string   `json:"status" binding:"omitempty,oneof=active inactive"`
@@ -67,6 +71,10 @@ type UpdateGroupRequest struct {
 	ImagePrice1K                    *float64 `json:"image_price_1k"`
 	ImagePrice2K                    *float64 `json:"image_price_2k"`
 	ImagePrice4K                    *float64 `json:"image_price_4k"`
+	SoraImagePrice360               *float64 `json:"sora_image_price_360"`
+	SoraImagePrice540               *float64 `json:"sora_image_price_540"`
+	SoraVideoPricePerRequest        *float64 `json:"sora_video_price_per_request"`
+	SoraVideoPricePerRequestHD      *float64 `json:"sora_video_price_per_request_hd"`
 	ClaudeCodeOnly                  *bool    `json:"claude_code_only"`
 	FallbackGroupID                 *int64   `json:"fallback_group_id"`
 	FallbackGroupIDOnInvalidRequest *int64   `json:"fallback_group_id_on_invalid_request"`
@@ -179,6 +187,10 @@ func (h *GroupHandler) Create(c *gin.Context) {
 		ImagePrice1K:                    req.ImagePrice1K,
 		ImagePrice2K:                    req.ImagePrice2K,
 		ImagePrice4K:                    req.ImagePrice4K,
+		SoraImagePrice360:               req.SoraImagePrice360,
+		SoraImagePrice540:               req.SoraImagePrice540,
+		SoraVideoPricePerRequest:        req.SoraVideoPricePerRequest,
+		SoraVideoPricePerRequestHD:      req.SoraVideoPricePerRequestHD,
 		ClaudeCodeOnly:                  req.ClaudeCodeOnly,
 		FallbackGroupID:                 req.FallbackGroupID,
 		FallbackGroupIDOnInvalidRequest: req.FallbackGroupIDOnInvalidRequest,
@@ -225,6 +237,10 @@ func (h *GroupHandler) Update(c *gin.Context) {
 		ImagePrice1K:                    req.ImagePrice1K,
 		ImagePrice2K:                    req.ImagePrice2K,
 		ImagePrice4K:                    req.ImagePrice4K,
+		SoraImagePrice360:               req.SoraImagePrice360,
+		SoraImagePrice540:               req.SoraImagePrice540,
+		SoraVideoPricePerRequest:        req.SoraVideoPricePerRequest,
+		SoraVideoPricePerRequestHD:      req.SoraVideoPricePerRequestHD,
 		ClaudeCodeOnly:                  req.ClaudeCodeOnly,
 		FallbackGroupID:                 req.FallbackGroupID,
 		FallbackGroupIDOnInvalidRequest: req.FallbackGroupIDOnInvalidRequest,
--- a/backend/internal/handler/admin/idempotency_helper.go
+++ b/backend/internal/handler/admin/idempotency_helper.go
@@ -0,0 +1,115 @@
+package admin
+
+import (
+	"context"
+	"strconv"
+	"time"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+type idempotencyStoreUnavailableMode int
+
+const (
+	idempotencyStoreUnavailableFailClose idempotencyStoreUnavailableMode = iota
+	idempotencyStoreUnavailableFailOpen
+)
+
+func executeAdminIdempotent(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	execute func(context.Context) (any, error),
+) (*service.IdempotencyExecuteResult, error) {
+	coordinator := service.DefaultIdempotencyCoordinator()
+	if coordinator == nil {
+		data, err := execute(c.Request.Context())
+		if err != nil {
+			return nil, err
+		}
+		return &service.IdempotencyExecuteResult{Data: data}, nil
+	}
+
+	actorScope := "admin:0"
+	if subject, ok := middleware2.GetAuthSubjectFromContext(c); ok {
+		actorScope = "admin:" + strconv.FormatInt(subject.UserID, 10)
+	}
+
+	return coordinator.Execute(c.Request.Context(), service.IdempotencyExecuteOptions{
+		Scope:          scope,
+		ActorScope:     actorScope,
+		Method:         c.Request.Method,
+		Route:          c.FullPath(),
+		IdempotencyKey: c.GetHeader("Idempotency-Key"),
+		Payload:        payload,
+		RequireKey:     true,
+		TTL:            ttl,
+	}, execute)
+}
+
+func executeAdminIdempotentJSON(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	execute func(context.Context) (any, error),
+) {
+	executeAdminIdempotentJSONWithMode(c, scope, payload, ttl, idempotencyStoreUnavailableFailClose, execute)
+}
+
+func executeAdminIdempotentJSONFailOpenOnStoreUnavailable(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	execute func(context.Context) (any, error),
+) {
+	executeAdminIdempotentJSONWithMode(c, scope, payload, ttl, idempotencyStoreUnavailableFailOpen, execute)
+}
+
+func executeAdminIdempotentJSONWithMode(
+	c *gin.Context,
+	scope string,
+	payload any,
+	ttl time.Duration,
+	mode idempotencyStoreUnavailableMode,
+	execute func(context.Context) (any, error),
+) {
+	result, err := executeAdminIdempotent(c, scope, payload, ttl, execute)
+	if err != nil {
+		if infraerrors.Code(err) == infraerrors.Code(service.ErrIdempotencyStoreUnavail) {
+			strategy := "fail_close"
+			if mode == idempotencyStoreUnavailableFailOpen {
+				strategy = "fail_open"
+			}
+			service.RecordIdempotencyStoreUnavailable(c.FullPath(), scope, "handler_"+strategy)
+			logger.LegacyPrintf("handler.idempotency", "[Idempotency] store unavailable: method=%s route=%s scope=%s strategy=%s", c.Request.Method, c.FullPath(), scope, strategy)
+			if mode == idempotencyStoreUnavailableFailOpen {
+				data, fallbackErr := execute(c.Request.Context())
+				if fallbackErr != nil {
+					response.ErrorFrom(c, fallbackErr)
+					return
+				}
+				c.Header("X-Idempotency-Degraded", "store-unavailable")
+				response.Success(c, data)
+				return
+			}
+		}
+		if retryAfter := service.RetryAfterSecondsFromError(err); retryAfter > 0 {
+			c.Header("Retry-After", strconv.Itoa(retryAfter))
+		}
+		response.ErrorFrom(c, err)
+		return
+	}
+	if result != nil && result.Replayed {
+		c.Header("X-Idempotency-Replayed", "true")
+	}
+	response.Success(c, result.Data)
+}
--- a/backend/internal/handler/admin/idempotency_helper_test.go
+++ b/backend/internal/handler/admin/idempotency_helper_test.go
@@ -0,0 +1,285 @@
+package admin
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type storeUnavailableRepoStub struct{}
+
+func (storeUnavailableRepoStub) CreateProcessing(context.Context, *service.IdempotencyRecord) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) GetByScopeAndKeyHash(context.Context, string, string) (*service.IdempotencyRecord, error) {
+	return nil, errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) TryReclaim(context.Context, int64, string, time.Time, time.Time, time.Time) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) ExtendProcessingLock(context.Context, int64, string, time.Time, time.Time) (bool, error) {
+	return false, errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) MarkSucceeded(context.Context, int64, int, string, time.Time) error {
+	return errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) MarkFailedRetryable(context.Context, int64, string, time.Time, time.Time) error {
+	return errors.New("store unavailable")
+}
+func (storeUnavailableRepoStub) DeleteExpired(context.Context, time.Time, int) (int64, error) {
+	return 0, errors.New("store unavailable")
+}
+
+func TestExecuteAdminIdempotentJSONFailCloseOnStoreUnavailable(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	service.SetDefaultIdempotencyCoordinator(service.NewIdempotencyCoordinator(storeUnavailableRepoStub{}, service.DefaultIdempotencyConfig()))
+	t.Cleanup(func() {
+		service.SetDefaultIdempotencyCoordinator(nil)
+	})
+
+	var executed int
+	router := gin.New()
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeAdminIdempotentJSON(c, "admin.test.high", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed++
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Idempotency-Key", "test-key-1")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusServiceUnavailable, rec.Code)
+	require.Equal(t, 0, executed, "fail-close should block business execution when idempotency store is unavailable")
+}
+
+func TestExecuteAdminIdempotentJSONFailOpenOnStoreUnavailable(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	service.SetDefaultIdempotencyCoordinator(service.NewIdempotencyCoordinator(storeUnavailableRepoStub{}, service.DefaultIdempotencyConfig()))
+	t.Cleanup(func() {
+		service.SetDefaultIdempotencyCoordinator(nil)
+	})
+
+	var executed int
+	router := gin.New()
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeAdminIdempotentJSONFailOpenOnStoreUnavailable(c, "admin.test.medium", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed++
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Idempotency-Key", "test-key-2")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.Equal(t, "store-unavailable", rec.Header().Get("X-Idempotency-Degraded"))
+	require.Equal(t, 1, executed, "fail-open strategy should allow semantic idempotent path to continue")
+}
+
+type memoryIdempotencyRepoStub struct {
+	mu     sync.Mutex
+	nextID int64
+	data   map[string]*service.IdempotencyRecord
+}
+
+func newMemoryIdempotencyRepoStub() *memoryIdempotencyRepoStub {
+	return &memoryIdempotencyRepoStub{
+		nextID: 1,
+		data:   make(map[string]*service.IdempotencyRecord),
+	}
+}
+
+func (r *memoryIdempotencyRepoStub) key(scope, keyHash string) string {
+	return scope + "|" + keyHash
+}
+
+func (r *memoryIdempotencyRepoStub) clone(in *service.IdempotencyRecord) *service.IdempotencyRecord {
+	if in == nil {
+		return nil
+	}
+	out := *in
+	if in.LockedUntil != nil {
+		v := *in.LockedUntil
+		out.LockedUntil = &v
+	}
+	if in.ResponseBody != nil {
+		v := *in.ResponseBody
+		out.ResponseBody = &v
+	}
+	if in.ResponseStatus != nil {
+		v := *in.ResponseStatus
+		out.ResponseStatus = &v
+	}
+	if in.ErrorReason != nil {
+		v := *in.ErrorReason
+		out.ErrorReason = &v
+	}
+	return &out
+}
+
+func (r *memoryIdempotencyRepoStub) CreateProcessing(_ context.Context, record *service.IdempotencyRecord) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	k := r.key(record.Scope, record.IdempotencyKeyHash)
+	if _, ok := r.data[k]; ok {
+		return false, nil
+	}
+	cp := r.clone(record)
+	cp.ID = r.nextID
+	r.nextID++
+	r.data[k] = cp
+	record.ID = cp.ID
+	return true, nil
+}
+
+func (r *memoryIdempotencyRepoStub) GetByScopeAndKeyHash(_ context.Context, scope, keyHash string) (*service.IdempotencyRecord, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.clone(r.data[r.key(scope, keyHash)]), nil
+}
+
+func (r *memoryIdempotencyRepoStub) TryReclaim(_ context.Context, id int64, fromStatus string, now, newLockedUntil, newExpiresAt time.Time) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		if rec.Status != fromStatus {
+			return false, nil
+		}
+		if rec.LockedUntil != nil && rec.LockedUntil.After(now) {
+			return false, nil
+		}
+		rec.Status = service.IdempotencyStatusProcessing
+		rec.LockedUntil = &newLockedUntil
+		rec.ExpiresAt = newExpiresAt
+		rec.ErrorReason = nil
+		return true, nil
+	}
+	return false, nil
+}
+
+func (r *memoryIdempotencyRepoStub) ExtendProcessingLock(_ context.Context, id int64, requestFingerprint string, newLockedUntil, newExpiresAt time.Time) (bool, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		if rec.Status != service.IdempotencyStatusProcessing || rec.RequestFingerprint != requestFingerprint {
+			return false, nil
+		}
+		rec.LockedUntil = &newLockedUntil
+		rec.ExpiresAt = newExpiresAt
+		return true, nil
+	}
+	return false, nil
+}
+
+func (r *memoryIdempotencyRepoStub) MarkSucceeded(_ context.Context, id int64, responseStatus int, responseBody string, expiresAt time.Time) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		rec.Status = service.IdempotencyStatusSucceeded
+		rec.LockedUntil = nil
+		rec.ExpiresAt = expiresAt
+		rec.ResponseStatus = &responseStatus
+		rec.ResponseBody = &responseBody
+		rec.ErrorReason = nil
+		return nil
+	}
+	return nil
+}
+
+func (r *memoryIdempotencyRepoStub) MarkFailedRetryable(_ context.Context, id int64, errorReason string, lockedUntil, expiresAt time.Time) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.data {
+		if rec.ID != id {
+			continue
+		}
+		rec.Status = service.IdempotencyStatusFailedRetryable
+		rec.LockedUntil = &lockedUntil
+		rec.ExpiresAt = expiresAt
+		rec.ErrorReason = &errorReason
+		return nil
+	}
+	return nil
+}
+
+func (r *memoryIdempotencyRepoStub) DeleteExpired(_ context.Context, _ time.Time, _ int) (int64, error) {
+	return 0, nil
+}
+
+func TestExecuteAdminIdempotentJSONConcurrentRetryOnlyOneSideEffect(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	repo := newMemoryIdempotencyRepoStub()
+	cfg := service.DefaultIdempotencyConfig()
+	cfg.ProcessingTimeout = 2 * time.Second
+	service.SetDefaultIdempotencyCoordinator(service.NewIdempotencyCoordinator(repo, cfg))
+	t.Cleanup(func() {
+		service.SetDefaultIdempotencyCoordinator(nil)
+	})
+
+	var executed atomic.Int32
+	router := gin.New()
+	router.POST("/idempotent", func(c *gin.Context) {
+		executeAdminIdempotentJSON(c, "admin.test.concurrent", map[string]any{"a": 1}, time.Minute, func(ctx context.Context) (any, error) {
+			executed.Add(1)
+			time.Sleep(120 * time.Millisecond)
+			return gin.H{"ok": true}, nil
+		})
+	})
+
+	call := func() (int, http.Header) {
+		req := httptest.NewRequest(http.MethodPost, "/idempotent", bytes.NewBufferString(`{"a":1}`))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Idempotency-Key", "same-key")
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+		return rec.Code, rec.Header()
+	}
+
+	var status1, status2 int
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() {
+		defer wg.Done()
+		status1, _ = call()
+	}()
+	go func() {
+		defer wg.Done()
+		status2, _ = call()
+	}()
+	wg.Wait()
+
+	require.Contains(t, []int{http.StatusOK, http.StatusConflict}, status1)
+	require.Contains(t, []int{http.StatusOK, http.StatusConflict}, status2)
+	require.Equal(t, int32(1), executed.Load(), "same idempotency key should execute side-effect only once")
+
+	status3, headers3 := call()
+	require.Equal(t, http.StatusOK, status3)
+	require.Equal(t, "true", headers3.Get("X-Idempotency-Replayed"))
+	require.Equal(t, int32(1), executed.Load())
+}
--- a/backend/internal/handler/admin/openai_oauth_handler.go
+++ b/backend/internal/handler/admin/openai_oauth_handler.go
@@ -2,6 +2,7 @@ package admin

 import (
 	"strconv"
+	"strings"

 	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
@@ -16,6 +17,13 @@ type OpenAIOAuthHandler struct {
 	adminService       service.AdminService
 }

+func oauthPlatformFromPath(c *gin.Context) string {
+	if strings.Contains(c.FullPath(), "/admin/sora/") {
+		return service.PlatformSora
+	}
+	return service.PlatformOpenAI
+}
+
 // NewOpenAIOAuthHandler creates a new OpenAI OAuth handler
 func NewOpenAIOAuthHandler(openaiOAuthService *service.OpenAIOAuthService, adminService service.AdminService) *OpenAIOAuthHandler {
 	return &OpenAIOAuthHandler{
@@ -52,6 +60,7 @@ func (h *OpenAIOAuthHandler) GenerateAuthURL(c *gin.Context) {
 type OpenAIExchangeCodeRequest struct {
 	SessionID   string `json:"session_id" binding:"required"`
 	Code        string `json:"code" binding:"required"`
+	State       string `json:"state" binding:"required"`
 	RedirectURI string `json:"redirect_uri"`
 	ProxyID     *int64 `json:"proxy_id"`
 }
@@ -68,6 +77,7 @@ func (h *OpenAIOAuthHandler) ExchangeCode(c *gin.Context) {
 	tokenInfo, err := h.openaiOAuthService.ExchangeCode(c.Request.Context(), &service.OpenAIExchangeCodeInput{
 		SessionID:   req.SessionID,
 		Code:        req.Code,
+		State:       req.State,
 		RedirectURI: req.RedirectURI,
 		ProxyID:     req.ProxyID,
 	})
@@ -81,18 +91,29 @@ func (h *OpenAIOAuthHandler) ExchangeCode(c *gin.Context) {

 // OpenAIRefreshTokenRequest represents the request for refreshing OpenAI token
 type OpenAIRefreshTokenRequest struct {
-	RefreshToken string `json:"refresh_token" binding:"required"`
+	RefreshToken string `json:"refresh_token"`
+	RT           string `json:"rt"`
+	ClientID     string `json:"client_id"`
 	ProxyID      *int64 `json:"proxy_id"`
 }

 // RefreshToken refreshes an OpenAI OAuth token
 // POST /api/v1/admin/openai/refresh-token
+// POST /api/v1/admin/sora/rt2at
 func (h *OpenAIOAuthHandler) RefreshToken(c *gin.Context) {
 	var req OpenAIRefreshTokenRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		response.BadRequest(c, "Invalid request: "+err.Error())
 		return
 	}
+	refreshToken := strings.TrimSpace(req.RefreshToken)
+	if refreshToken == "" {
+		refreshToken = strings.TrimSpace(req.RT)
+	}
+	if refreshToken == "" {
+		response.BadRequest(c, "refresh_token is required")
+		return
+	}

 	var proxyURL string
 	if req.ProxyID != nil {
@@ -102,7 +123,7 @@ func (h *OpenAIOAuthHandler) RefreshToken(c *gin.Context) {
 		}
 	}

-	tokenInfo, err := h.openaiOAuthService.RefreshToken(c.Request.Context(), req.RefreshToken, proxyURL)
+	tokenInfo, err := h.openaiOAuthService.RefreshTokenWithClientID(c.Request.Context(), refreshToken, proxyURL, strings.TrimSpace(req.ClientID))
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return
@@ -111,8 +132,39 @@ func (h *OpenAIOAuthHandler) RefreshToken(c *gin.Context) {
 	response.Success(c, tokenInfo)
 }

-// RefreshAccountToken refreshes token for a specific OpenAI account
+// ExchangeSoraSessionToken exchanges Sora session token to access token
+// POST /api/v1/admin/sora/st2at
+func (h *OpenAIOAuthHandler) ExchangeSoraSessionToken(c *gin.Context) {
+	var req struct {
+		SessionToken string `json:"session_token"`
+		ST           string `json:"st"`
+		ProxyID      *int64 `json:"proxy_id"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	sessionToken := strings.TrimSpace(req.SessionToken)
+	if sessionToken == "" {
+		sessionToken = strings.TrimSpace(req.ST)
+	}
+	if sessionToken == "" {
+		response.BadRequest(c, "session_token is required")
+		return
+	}
+
+	tokenInfo, err := h.openaiOAuthService.ExchangeSoraSessionToken(c.Request.Context(), sessionToken, req.ProxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, tokenInfo)
+}
+
+// RefreshAccountToken refreshes token for a specific OpenAI/Sora account
 // POST /api/v1/admin/openai/accounts/:id/refresh
+// POST /api/v1/admin/sora/accounts/:id/refresh
 func (h *OpenAIOAuthHandler) RefreshAccountToken(c *gin.Context) {
 	accountID, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -127,9 +179,9 @@ func (h *OpenAIOAuthHandler) RefreshAccountToken(c *gin.Context) {
 		return
 	}

-	// Ensure account is OpenAI platform
-	if !account.IsOpenAI() {
-		response.BadRequest(c, "Account is not an OpenAI account")
+	platform := oauthPlatformFromPath(c)
+	if account.Platform != platform {
+		response.BadRequest(c, "Account platform does not match OAuth endpoint")
 		return
 	}

@@ -167,12 +219,14 @@ func (h *OpenAIOAuthHandler) RefreshAccountToken(c *gin.Context) {
 	response.Success(c, dto.AccountFromService(updatedAccount))
 }

-// CreateAccountFromOAuth creates a new OpenAI OAuth account from token info
+// CreateAccountFromOAuth creates a new OpenAI/Sora OAuth account from token info
 // POST /api/v1/admin/openai/create-from-oauth
+// POST /api/v1/admin/sora/create-from-oauth
 func (h *OpenAIOAuthHandler) CreateAccountFromOAuth(c *gin.Context) {
 	var req struct {
 		SessionID   string  `json:"session_id" binding:"required"`
 		Code        string  `json:"code" binding:"required"`
+		State       string  `json:"state" binding:"required"`
 		RedirectURI string  `json:"redirect_uri"`
 		ProxyID     *int64  `json:"proxy_id"`
 		Name        string  `json:"name"`
@@ -189,6 +243,7 @@ func (h *OpenAIOAuthHandler) CreateAccountFromOAuth(c *gin.Context) {
 	tokenInfo, err := h.openaiOAuthService.ExchangeCode(c.Request.Context(), &service.OpenAIExchangeCodeInput{
 		SessionID:   req.SessionID,
 		Code:        req.Code,
+		State:       req.State,
 		RedirectURI: req.RedirectURI,
 		ProxyID:     req.ProxyID,
 	})
@@ -200,19 +255,25 @@ func (h *OpenAIOAuthHandler) CreateAccountFromOAuth(c *gin.Context) {
 	// Build credentials from token info
 	credentials := h.openaiOAuthService.BuildAccountCredentials(tokenInfo)

+	platform := oauthPlatformFromPath(c)
+
 	// Use email as default name if not provided
 	name := req.Name
 	if name == "" && tokenInfo.Email != "" {
 		name = tokenInfo.Email
 	}
 	if name == "" {
-		name = "OpenAI OAuth Account"
+		if platform == service.PlatformSora {
+			name = "Sora OAuth Account"
+		} else {
+			name = "OpenAI OAuth Account"
+		}
 	}

 	// Create account
 	account, err := h.adminService.CreateAccount(c.Request.Context(), &service.CreateAccountInput{
 		Name:        name,
-		Platform:    "openai",
+		Platform:    platform,
 		Type:        "oauth",
 		Credentials: credentials,
 		ProxyID:     req.ProxyID,
--- a/backend/internal/handler/admin/ops_dashboard_handler.go
+++ b/backend/internal/handler/admin/ops_dashboard_handler.go
@@ -1,6 +1,7 @@
 package admin

 import (
+	"fmt"
 	"net/http"
 	"strconv"
 	"strings"
@@ -218,6 +219,115 @@ func (h *OpsHandler) GetDashboardErrorDistribution(c *gin.Context) {
 	response.Success(c, data)
 }

+// GetDashboardOpenAITokenStats returns OpenAI token efficiency stats grouped by model.
+// GET /api/v1/admin/ops/dashboard/openai-token-stats
+func (h *OpsHandler) GetDashboardOpenAITokenStats(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	data, err := h.opsService.GetOpenAITokenStats(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func parseOpsOpenAITokenStatsFilter(c *gin.Context) (*service.OpsOpenAITokenStatsFilter, error) {
+	if c == nil {
+		return nil, fmt.Errorf("invalid request")
+	}
+
+	timeRange := strings.TrimSpace(c.Query("time_range"))
+	if timeRange == "" {
+		timeRange = "30d"
+	}
+	dur, ok := parseOpsOpenAITokenStatsDuration(timeRange)
+	if !ok {
+		return nil, fmt.Errorf("invalid time_range")
+	}
+	end := time.Now().UTC()
+	start := end.Add(-dur)
+
+	filter := &service.OpsOpenAITokenStatsFilter{
+		TimeRange: timeRange,
+		StartTime: start,
+		EndTime:   end,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+	}
+
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			return nil, fmt.Errorf("invalid group_id")
+		}
+		filter.GroupID = &id
+	}
+
+	topNRaw := strings.TrimSpace(c.Query("top_n"))
+	pageRaw := strings.TrimSpace(c.Query("page"))
+	pageSizeRaw := strings.TrimSpace(c.Query("page_size"))
+	if topNRaw != "" && (pageRaw != "" || pageSizeRaw != "") {
+		return nil, fmt.Errorf("invalid query: top_n cannot be used with page/page_size")
+	}
+
+	if topNRaw != "" {
+		topN, err := strconv.Atoi(topNRaw)
+		if err != nil || topN < 1 || topN > 100 {
+			return nil, fmt.Errorf("invalid top_n")
+		}
+		filter.TopN = topN
+		return filter, nil
+	}
+
+	filter.Page = 1
+	filter.PageSize = 20
+	if pageRaw != "" {
+		page, err := strconv.Atoi(pageRaw)
+		if err != nil || page < 1 {
+			return nil, fmt.Errorf("invalid page")
+		}
+		filter.Page = page
+	}
+	if pageSizeRaw != "" {
+		pageSize, err := strconv.Atoi(pageSizeRaw)
+		if err != nil || pageSize < 1 || pageSize > 100 {
+			return nil, fmt.Errorf("invalid page_size")
+		}
+		filter.PageSize = pageSize
+	}
+	return filter, nil
+}
+
+func parseOpsOpenAITokenStatsDuration(v string) (time.Duration, bool) {
+	switch strings.TrimSpace(v) {
+	case "30m":
+		return 30 * time.Minute, true
+	case "1h":
+		return time.Hour, true
+	case "1d":
+		return 24 * time.Hour, true
+	case "15d":
+		return 15 * 24 * time.Hour, true
+	case "30d":
+		return 30 * 24 * time.Hour, true
+	default:
+		return 0, false
+	}
+}
+
 func pickThroughputBucketSeconds(window time.Duration) int {
 	// Keep buckets predictable and avoid huge responses.
 	switch {
--- a/backend/internal/handler/admin/ops_runtime_logging_handler_test.go
+++ b/backend/internal/handler/admin/ops_runtime_logging_handler_test.go
@@ -0,0 +1,173 @@
+package admin
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type testSettingRepo struct {
+	values map[string]string
+}
+
+func newTestSettingRepo() *testSettingRepo {
+	return &testSettingRepo{values: map[string]string{}}
+}
+
+func (s *testSettingRepo) Get(ctx context.Context, key string) (*service.Setting, error) {
+	v, err := s.GetValue(ctx, key)
+	if err != nil {
+		return nil, err
+	}
+	return &service.Setting{Key: key, Value: v}, nil
+}
+func (s *testSettingRepo) GetValue(ctx context.Context, key string) (string, error) {
+	v, ok := s.values[key]
+	if !ok {
+		return "", service.ErrSettingNotFound
+	}
+	return v, nil
+}
+func (s *testSettingRepo) Set(ctx context.Context, key, value string) error {
+	s.values[key] = value
+	return nil
+}
+func (s *testSettingRepo) GetMultiple(ctx context.Context, keys []string) (map[string]string, error) {
+	out := make(map[string]string, len(keys))
+	for _, k := range keys {
+		if v, ok := s.values[k]; ok {
+			out[k] = v
+		}
+	}
+	return out, nil
+}
+func (s *testSettingRepo) SetMultiple(ctx context.Context, settings map[string]string) error {
+	for k, v := range settings {
+		s.values[k] = v
+	}
+	return nil
+}
+func (s *testSettingRepo) GetAll(ctx context.Context) (map[string]string, error) {
+	out := make(map[string]string, len(s.values))
+	for k, v := range s.values {
+		out[k] = v
+	}
+	return out, nil
+}
+func (s *testSettingRepo) Delete(ctx context.Context, key string) error {
+	delete(s.values, key)
+	return nil
+}
+
+func newOpsRuntimeRouter(handler *OpsHandler, withUser bool) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	if withUser {
+		r.Use(func(c *gin.Context) {
+			c.Set(string(middleware.ContextKeyUser), middleware.AuthSubject{UserID: 7})
+			c.Next()
+		})
+	}
+	r.GET("/runtime/logging", handler.GetRuntimeLogConfig)
+	r.PUT("/runtime/logging", handler.UpdateRuntimeLogConfig)
+	r.POST("/runtime/logging/reset", handler.ResetRuntimeLogConfig)
+	return r
+}
+
+func newRuntimeOpsService(t *testing.T) *service.OpsService {
+	t.Helper()
+	if err := logger.Init(logger.InitOptions{
+		Level:       "info",
+		Format:      "json",
+		ServiceName: "sub2api",
+		Environment: "test",
+		Output: logger.OutputOptions{
+			ToStdout: false,
+			ToFile:   false,
+		},
+	}); err != nil {
+		t.Fatalf("init logger: %v", err)
+	}
+
+	settingRepo := newTestSettingRepo()
+	cfg := &config.Config{
+		Ops: config.OpsConfig{Enabled: true},
+		Log: config.LogConfig{
+			Level:           "info",
+			Caller:          true,
+			StacktraceLevel: "error",
+			Sampling: config.LogSamplingConfig{
+				Enabled:    false,
+				Initial:    100,
+				Thereafter: 100,
+			},
+		},
+	}
+	return service.NewOpsService(nil, settingRepo, cfg, nil, nil, nil, nil, nil, nil, nil, nil)
+}
+
+func TestOpsRuntimeLoggingHandler_GetConfig(t *testing.T) {
+	h := NewOpsHandler(newRuntimeOpsService(t))
+	r := newOpsRuntimeRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/runtime/logging", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d, want 200", w.Code)
+	}
+}
+
+func TestOpsRuntimeLoggingHandler_UpdateUnauthorized(t *testing.T) {
+	h := NewOpsHandler(newRuntimeOpsService(t))
+	r := newOpsRuntimeRouter(h, false)
+
+	body := `{"level":"debug","enable_sampling":false,"sampling_initial":100,"sampling_thereafter":100,"caller":true,"stacktrace_level":"error","retention_days":30}`
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/runtime/logging", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", w.Code)
+	}
+}
+
+func TestOpsRuntimeLoggingHandler_UpdateAndResetSuccess(t *testing.T) {
+	h := NewOpsHandler(newRuntimeOpsService(t))
+	r := newOpsRuntimeRouter(h, true)
+
+	payload := map[string]any{
+		"level":               "debug",
+		"enable_sampling":     false,
+		"sampling_initial":    100,
+		"sampling_thereafter": 100,
+		"caller":              true,
+		"stacktrace_level":    "error",
+		"retention_days":      30,
+	}
+	raw, _ := json.Marshal(payload)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/runtime/logging", bytes.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("update status=%d, want 200, body=%s", w.Code, w.Body.String())
+	}
+
+	w = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/runtime/logging/reset", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("reset status=%d, want 200, body=%s", w.Code, w.Body.String())
+	}
+}
--- a/backend/internal/handler/admin/ops_settings_handler.go
+++ b/backend/internal/handler/admin/ops_settings_handler.go
@@ -4,6 +4,7 @@ import (
 	"net/http"

 	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
 	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/gin-gonic/gin"
 )
@@ -101,6 +102,84 @@ func (h *OpsHandler) UpdateAlertRuntimeSettings(c *gin.Context) {
 	response.Success(c, updated)
 }

+// GetRuntimeLogConfig returns runtime log config (DB-backed).
+// GET /api/v1/admin/ops/runtime/logging
+func (h *OpsHandler) GetRuntimeLogConfig(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	cfg, err := h.opsService.GetRuntimeLogConfig(c.Request.Context())
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get runtime log config")
+		return
+	}
+	response.Success(c, cfg)
+}
+
+// UpdateRuntimeLogConfig updates runtime log config and applies changes immediately.
+// PUT /api/v1/admin/ops/runtime/logging
+func (h *OpsHandler) UpdateRuntimeLogConfig(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	var req service.OpsRuntimeLogConfig
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	updated, err := h.opsService.UpdateRuntimeLogConfig(c.Request.Context(), &req, subject.UserID)
+	if err != nil {
+		response.Error(c, http.StatusBadRequest, err.Error())
+		return
+	}
+	response.Success(c, updated)
+}
+
+// ResetRuntimeLogConfig removes runtime override and falls back to env/yaml baseline.
+// POST /api/v1/admin/ops/runtime/logging/reset
+func (h *OpsHandler) ResetRuntimeLogConfig(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	updated, err := h.opsService.ResetRuntimeLogConfig(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.Error(c, http.StatusBadRequest, err.Error())
+		return
+	}
+	response.Success(c, updated)
+}
+
 // GetAdvancedSettings returns Ops advanced settings (DB-backed).
 // GET /api/v1/admin/ops/advanced-settings
 func (h *OpsHandler) GetAdvancedSettings(c *gin.Context) {
--- a/backend/internal/handler/admin/ops_system_log_handler.go
+++ b/backend/internal/handler/admin/ops_system_log_handler.go
@@ -0,0 +1,174 @@
+package admin
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type opsSystemLogCleanupRequest struct {
+	StartTime string `json:"start_time"`
+	EndTime   string `json:"end_time"`
+
+	Level           string `json:"level"`
+	Component       string `json:"component"`
+	RequestID       string `json:"request_id"`
+	ClientRequestID string `json:"client_request_id"`
+	UserID          *int64 `json:"user_id"`
+	AccountID       *int64 `json:"account_id"`
+	Platform        string `json:"platform"`
+	Model           string `json:"model"`
+	Query           string `json:"q"`
+}
+
+// ListSystemLogs returns indexed system logs.
+// GET /api/v1/admin/ops/system-logs
+func (h *OpsHandler) ListSystemLogs(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	page, pageSize := response.ParsePagination(c)
+	if pageSize > 200 {
+		pageSize = 200
+	}
+
+	start, end, err := parseOpsTimeRange(c, "1h")
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	filter := &service.OpsSystemLogFilter{
+		Page:            page,
+		PageSize:        pageSize,
+		StartTime:       &start,
+		EndTime:         &end,
+		Level:           strings.TrimSpace(c.Query("level")),
+		Component:       strings.TrimSpace(c.Query("component")),
+		RequestID:       strings.TrimSpace(c.Query("request_id")),
+		ClientRequestID: strings.TrimSpace(c.Query("client_request_id")),
+		Platform:        strings.TrimSpace(c.Query("platform")),
+		Model:           strings.TrimSpace(c.Query("model")),
+		Query:           strings.TrimSpace(c.Query("q")),
+	}
+	if v := strings.TrimSpace(c.Query("user_id")); v != "" {
+		id, parseErr := strconv.ParseInt(v, 10, 64)
+		if parseErr != nil || id <= 0 {
+			response.BadRequest(c, "Invalid user_id")
+			return
+		}
+		filter.UserID = &id
+	}
+	if v := strings.TrimSpace(c.Query("account_id")); v != "" {
+		id, parseErr := strconv.ParseInt(v, 10, 64)
+		if parseErr != nil || id <= 0 {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		filter.AccountID = &id
+	}
+
+	result, err := h.opsService.ListSystemLogs(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Paginated(c, result.Logs, int64(result.Total), result.Page, result.PageSize)
+}
+
+// CleanupSystemLogs deletes indexed system logs by filter.
+// POST /api/v1/admin/ops/system-logs/cleanup
+func (h *OpsHandler) CleanupSystemLogs(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	subject, ok := middleware.GetAuthSubjectFromContext(c)
+	if !ok || subject.UserID <= 0 {
+		response.Error(c, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	var req opsSystemLogCleanupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request body")
+		return
+	}
+
+	parseTS := func(raw string) (*time.Time, error) {
+		raw = strings.TrimSpace(raw)
+		if raw == "" {
+			return nil, nil
+		}
+		if t, err := time.Parse(time.RFC3339Nano, raw); err == nil {
+			return &t, nil
+		}
+		t, err := time.Parse(time.RFC3339, raw)
+		if err != nil {
+			return nil, err
+		}
+		return &t, nil
+	}
+	start, err := parseTS(req.StartTime)
+	if err != nil {
+		response.BadRequest(c, "Invalid start_time")
+		return
+	}
+	end, err := parseTS(req.EndTime)
+	if err != nil {
+		response.BadRequest(c, "Invalid end_time")
+		return
+	}
+
+	filter := &service.OpsSystemLogCleanupFilter{
+		StartTime:       start,
+		EndTime:         end,
+		Level:           strings.TrimSpace(req.Level),
+		Component:       strings.TrimSpace(req.Component),
+		RequestID:       strings.TrimSpace(req.RequestID),
+		ClientRequestID: strings.TrimSpace(req.ClientRequestID),
+		UserID:          req.UserID,
+		AccountID:       req.AccountID,
+		Platform:        strings.TrimSpace(req.Platform),
+		Model:           strings.TrimSpace(req.Model),
+		Query:           strings.TrimSpace(req.Query),
+	}
+
+	deleted, err := h.opsService.CleanupSystemLogs(c.Request.Context(), filter, subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, gin.H{"deleted": deleted})
+}
+
+// GetSystemLogIngestionHealth returns sink health metrics.
+// GET /api/v1/admin/ops/system-logs/health
+func (h *OpsHandler) GetSystemLogIngestionHealth(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, h.opsService.GetSystemLogSinkHealth())
+}
--- a/backend/internal/handler/admin/ops_system_log_handler_test.go
+++ b/backend/internal/handler/admin/ops_system_log_handler_test.go
@@ -0,0 +1,233 @@
+package admin
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type responseEnvelope struct {
+	Code    int             `json:"code"`
+	Message string          `json:"message"`
+	Data    json.RawMessage `json:"data"`
+}
+
+func newOpsSystemLogTestRouter(handler *OpsHandler, withUser bool) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	if withUser {
+		r.Use(func(c *gin.Context) {
+			c.Set(string(middleware.ContextKeyUser), middleware.AuthSubject{UserID: 99})
+			c.Next()
+		})
+	}
+	r.GET("/logs", handler.ListSystemLogs)
+	r.POST("/logs/cleanup", handler.CleanupSystemLogs)
+	r.GET("/logs/health", handler.GetSystemLogIngestionHealth)
+	return r
+}
+
+func TestOpsSystemLogHandler_ListUnavailable(t *testing.T) {
+	h := NewOpsHandler(nil)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status=%d, want 503", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_ListInvalidUserID(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs?user_id=abc", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_ListInvalidAccountID(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs?account_id=-1", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_ListMonitoringDisabled(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, &config.Config{
+		Ops: config.OpsConfig{Enabled: false},
+	}, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status=%d, want 404", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_ListSuccess(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs?time_range=30m&page=1&page_size=20", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d, want 200", w.Code)
+	}
+
+	var resp responseEnvelope
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+	if resp.Code != 0 {
+		t.Fatalf("unexpected response code: %+v", resp)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupUnauthorized(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupInvalidPayload(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{bad-json`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupInvalidTime(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"start_time":"bad","request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupInvalidEndTime(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"end_time":"bad","request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d, want 400", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupServiceUnavailable(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status=%d, want 503", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_CleanupMonitoringDisabled(t *testing.T) {
+	svc := service.NewOpsService(nil, nil, &config.Config{
+		Ops: config.OpsConfig{Enabled: false},
+	}, nil, nil, nil, nil, nil, nil, nil, nil)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, true)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/logs/cleanup", bytes.NewBufferString(`{"request_id":"r1"}`))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status=%d, want 404", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_Health(t *testing.T) {
+	sink := service.NewOpsSystemLogSink(nil)
+	svc := service.NewOpsService(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, sink)
+	h := NewOpsHandler(svc)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs/health", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d, want 200", w.Code)
+	}
+}
+
+func TestOpsSystemLogHandler_HealthUnavailableAndMonitoringDisabled(t *testing.T) {
+	h := NewOpsHandler(nil)
+	r := newOpsSystemLogTestRouter(h, false)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/logs/health", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status=%d, want 503", w.Code)
+	}
+
+	svc := service.NewOpsService(nil, nil, &config.Config{
+		Ops: config.OpsConfig{Enabled: false},
+	}, nil, nil, nil, nil, nil, nil, nil, nil)
+	h = NewOpsHandler(svc)
+	r = newOpsSystemLogTestRouter(h, false)
+	w = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/logs/health", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status=%d, want 404", w.Code)
+	}
+}
--- a/backend/internal/handler/admin/ops_ws_handler.go
+++ b/backend/internal/handler/admin/ops_ws_handler.go
@@ -3,7 +3,6 @@ package admin
 import (
 	"context"
 	"encoding/json"
-	"log"
 	"math"
 	"net"
 	"net/http"
@@ -16,6 +15,7 @@ import (
 	"sync/atomic"
 	"time"

+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
 	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/gin-gonic/gin"
 	"github.com/gorilla/websocket"
@@ -252,7 +252,7 @@ func (c *opsWSQPSCache) refresh(parentCtx context.Context) {
 	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)
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] refresh: get window stats failed: %v", err)
 		}
 		return
 	}
@@ -278,7 +278,7 @@ func (c *opsWSQPSCache) refresh(parentCtx context.Context) {

 	msg, err := json.Marshal(payload)
 	if err != nil {
-		log.Printf("[OpsWS] refresh: marshal payload failed: %v", err)
+		logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] refresh: marshal payload failed: %v", err)
 		return
 	}

@@ -338,7 +338,7 @@ func (h *OpsHandler) QPSWSHandler(c *gin.Context) {

 	// 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)
+		logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] connection limit reached: %d/%d", wsConnCount.Load(), opsWSLimits.MaxConns)
 		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "too many connections"})
 		return
 	}
@@ -350,7 +350,7 @@ func (h *OpsHandler) QPSWSHandler(c *gin.Context) {

 	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)
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] per-ip connection limit reached: ip=%s limit=%d", clientIP, opsWSLimits.MaxConnsPerIP)
 			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "too many connections"})
 			return
 		}
@@ -359,7 +359,7 @@ func (h *OpsHandler) QPSWSHandler(c *gin.Context) {

 	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
 	if err != nil {
-		log.Printf("[OpsWS] upgrade failed: %v", err)
+		logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] upgrade failed: %v", err)
 		return
 	}

@@ -452,7 +452,7 @@ func handleQPSWebSocket(parentCtx context.Context, conn *websocket.Conn) {

 		conn.SetReadLimit(qpsWSMaxReadBytes)
 		if err := conn.SetReadDeadline(time.Now().Add(qpsWSPongWait)); err != nil {
-			log.Printf("[OpsWS] set read deadline failed: %v", err)
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] set read deadline failed: %v", err)
 			return
 		}
 		conn.SetPongHandler(func(string) error {
@@ -471,7 +471,7 @@ func handleQPSWebSocket(parentCtx context.Context, conn *websocket.Conn) {
 			_, _, err := conn.ReadMessage()
 			if err != nil {
 				if websocket.IsUnexpectedCloseError(err, websocket.CloseNormalClosure, websocket.CloseGoingAway, websocket.CloseNoStatusReceived) {
-					log.Printf("[OpsWS] read failed: %v", err)
+					logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] read failed: %v", err)
 				}
 				return
 			}
@@ -508,7 +508,7 @@ func handleQPSWebSocket(parentCtx context.Context, conn *websocket.Conn) {
 				continue
 			}
 			if err := writeWithTimeout(websocket.TextMessage, msg); err != nil {
-				log.Printf("[OpsWS] write failed: %v", err)
+				logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] write failed: %v", err)
 				cancel()
 				closeConn()
 				wg.Wait()
@@ -517,7 +517,7 @@ func handleQPSWebSocket(parentCtx context.Context, conn *websocket.Conn) {

 		case <-pingTicker.C:
 			if err := writeWithTimeout(websocket.PingMessage, nil); err != nil {
-				log.Printf("[OpsWS] ping failed: %v", err)
+				logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] ping failed: %v", err)
 				cancel()
 				closeConn()
 				wg.Wait()
@@ -666,14 +666,14 @@ func loadOpsWSProxyConfigFromEnv() OpsWSProxyConfig {
 		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)
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s=%q (expected bool); using default=%v", envOpsWSTrustProxy, v, cfg.TrustProxy)
 		}
 	}

 	if raw := strings.TrimSpace(os.Getenv(envOpsWSTrustedProxies)); raw != "" {
 		prefixes, invalid := parseTrustedProxyList(raw)
 		if len(invalid) > 0 {
-			log.Printf("[OpsWS] invalid %s entries ignored: %s", envOpsWSTrustedProxies, strings.Join(invalid, ", "))
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s entries ignored: %s", envOpsWSTrustedProxies, strings.Join(invalid, ", "))
 		}
 		cfg.TrustedProxies = prefixes
 	}
@@ -684,7 +684,7 @@ func loadOpsWSProxyConfigFromEnv() OpsWSProxyConfig {
 		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)
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s=%q (expected %q or %q); using default=%q", envOpsWSOriginPolicy, v, OriginPolicyStrict, OriginPolicyPermissive, cfg.OriginPolicy)
 		}
 	}

@@ -701,14 +701,14 @@ func loadOpsWSRuntimeLimitsFromEnv() opsWSRuntimeLimits {
 		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)
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s=%q (expected int>0); using default=%d", envOpsWSMaxConns, v, cfg.MaxConns)
 		}
 	}
 	if v := strings.TrimSpace(os.Getenv(envOpsWSMaxConnsPerIP)); v != "" {
 		if parsed, err := strconv.Atoi(v); err == nil && parsed >= 0 {
 			cfg.MaxConnsPerIP = int32(parsed)
 		} else {
-			log.Printf("[OpsWS] invalid %s=%q (expected int>=0); using default=%d", envOpsWSMaxConnsPerIP, v, cfg.MaxConnsPerIP)
+			logger.LegacyPrintf("handler.admin.ops_ws", "[OpsWS] invalid %s=%q (expected int>=0); using default=%d", envOpsWSMaxConnsPerIP, v, cfg.MaxConnsPerIP)
 		}
 	}
 	return cfg
--- a/backend/internal/handler/admin/proxy_handler.go
+++ b/backend/internal/handler/admin/proxy_handler.go
@@ -1,6 +1,7 @@
 package admin

 import (
+	"context"
 	"strconv"
 	"strings"

@@ -130,20 +131,20 @@ func (h *ProxyHandler) Create(c *gin.Context) {
 		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),
+	executeAdminIdempotentJSON(c, "admin.proxies.create", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		proxy, err := h.adminService.CreateProxy(ctx, &service.CreateProxyInput{
+			Name:     strings.TrimSpace(req.Name),
+			Protocol: strings.TrimSpace(req.Protocol),
+			Host:     strings.TrimSpace(req.Host),
+			Port:     req.Port,
+			Username: strings.TrimSpace(req.Username),
+			Password: strings.TrimSpace(req.Password),
+		})
+		if err != nil {
+			return nil, err
+		}
+		return dto.ProxyFromService(proxy), nil
 	})
-	if err != nil {
-		response.ErrorFrom(c, err)
-		return
-	}
-
-	response.Success(c, dto.ProxyFromService(proxy))
 }

 // Update handles updating a proxy
@@ -236,6 +237,24 @@ func (h *ProxyHandler) Test(c *gin.Context) {
 	response.Success(c, result)
 }

+// CheckQuality handles checking proxy quality across common AI targets.
+// POST /api/v1/admin/proxies/:id/quality-check
+func (h *ProxyHandler) CheckQuality(c *gin.Context) {
+	proxyID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid proxy ID")
+		return
+	}
+
+	result, err := h.adminService.CheckProxyQuality(c.Request.Context(), proxyID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, result)
+}
+
 // GetStats handles getting proxy statistics
 // GET /api/v1/admin/proxies/:id/stats
 func (h *ProxyHandler) GetStats(c *gin.Context) {
--- a/backend/internal/handler/admin/redeem_handler.go
+++ b/backend/internal/handler/admin/redeem_handler.go
@@ -2,6 +2,7 @@ package admin

 import (
 	"bytes"
+	"context"
 	"encoding/csv"
 	"fmt"
 	"strconv"
@@ -88,23 +89,24 @@ func (h *RedeemHandler) Generate(c *gin.Context) {
 		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
-	}
+	executeAdminIdempotentJSON(c, "admin.redeem_codes.generate", req, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		codes, execErr := h.adminService.GenerateRedeemCodes(ctx, &service.GenerateRedeemCodesInput{
+			Count:        req.Count,
+			Type:         req.Type,
+			Value:        req.Value,
+			GroupID:      req.GroupID,
+			ValidityDays: req.ValidityDays,
+		})
+		if execErr != nil {
+			return nil, execErr
+		}

-	out := make([]dto.AdminRedeemCode, 0, len(codes))
-	for i := range codes {
-		out = append(out, *dto.RedeemCodeFromServiceAdmin(&codes[i]))
-	}
-	response.Success(c, out)
+		out := make([]dto.AdminRedeemCode, 0, len(codes))
+		for i := range codes {
+			out = append(out, *dto.RedeemCodeFromServiceAdmin(&codes[i]))
+		}
+		return out, nil
+	})
 }

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

 import (
+	"context"
 	"strconv"

 	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
@@ -199,13 +200,20 @@ func (h *SubscriptionHandler) Extend(c *gin.Context) {
 		return
 	}

-	subscription, err := h.subscriptionService.ExtendSubscription(c.Request.Context(), subscriptionID, req.Days)
-	if err != nil {
-		response.ErrorFrom(c, err)
-		return
+	idempotencyPayload := struct {
+		SubscriptionID int64                     `json:"subscription_id"`
+		Body           AdjustSubscriptionRequest `json:"body"`
+	}{
+		SubscriptionID: subscriptionID,
+		Body:           req,
 	}
-
-	response.Success(c, dto.UserSubscriptionFromServiceAdmin(subscription))
+	executeAdminIdempotentJSON(c, "admin.subscriptions.extend", idempotencyPayload, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		subscription, execErr := h.subscriptionService.ExtendSubscription(ctx, subscriptionID, req.Days)
+		if execErr != nil {
+			return nil, execErr
+		}
+		return dto.UserSubscriptionFromServiceAdmin(subscription), nil
+	})
 }

 // Revoke handles revoking a subscription
--- a/backend/internal/handler/admin/system_handler.go
+++ b/backend/internal/handler/admin/system_handler.go
@@ -1,11 +1,15 @@
 package admin

 import (
+	"context"
 	"net/http"
+	"strconv"
+	"strings"
 	"time"

 	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/sysutil"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
 	"github.com/Wei-Shaw/sub2api/internal/service"

 	"github.com/gin-gonic/gin"
@@ -14,12 +18,14 @@ import (
 // SystemHandler handles system-related operations
 type SystemHandler struct {
 	updateSvc *service.UpdateService
+	lockSvc   *service.SystemOperationLockService
 }

 // NewSystemHandler creates a new SystemHandler
-func NewSystemHandler(updateSvc *service.UpdateService) *SystemHandler {
+func NewSystemHandler(updateSvc *service.UpdateService, lockSvc *service.SystemOperationLockService) *SystemHandler {
 	return &SystemHandler{
 		updateSvc: updateSvc,
+		lockSvc:   lockSvc,
 	}
 }

@@ -47,41 +53,125 @@ func (h *SystemHandler) CheckUpdates(c *gin.Context) {
 // 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,
+	operationID := buildSystemOperationID(c, "update")
+	payload := gin.H{"operation_id": operationID}
+	executeAdminIdempotentJSON(c, "admin.system.update", payload, service.DefaultSystemOperationIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		lock, release, err := h.acquireSystemLock(ctx, operationID)
+		if err != nil {
+			return nil, err
+		}
+		var releaseReason string
+		succeeded := false
+		defer func() {
+			release(releaseReason, succeeded)
+		}()
+
+		if err := h.updateSvc.PerformUpdate(ctx); err != nil {
+			releaseReason = "SYSTEM_UPDATE_FAILED"
+			return nil, err
+		}
+		succeeded = true
+
+		return gin.H{
+			"message":      "Update completed. Please restart the service.",
+			"need_restart": true,
+			"operation_id": lock.OperationID(),
+		}, nil
 	})
 }

 // Rollback restores the previous version
 // POST /api/v1/admin/system/rollback
 func (h *SystemHandler) Rollback(c *gin.Context) {
-	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,
+	operationID := buildSystemOperationID(c, "rollback")
+	payload := gin.H{"operation_id": operationID}
+	executeAdminIdempotentJSON(c, "admin.system.rollback", payload, service.DefaultSystemOperationIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		lock, release, err := h.acquireSystemLock(ctx, operationID)
+		if err != nil {
+			return nil, err
+		}
+		var releaseReason string
+		succeeded := false
+		defer func() {
+			release(releaseReason, succeeded)
+		}()
+
+		if err := h.updateSvc.Rollback(); err != nil {
+			releaseReason = "SYSTEM_ROLLBACK_FAILED"
+			return nil, err
+		}
+		succeeded = true
+
+		return gin.H{
+			"message":      "Rollback completed. Please restart the service.",
+			"need_restart": true,
+			"operation_id": lock.OperationID(),
+		}, nil
 	})
 }

 // RestartService restarts the systemd service
 // POST /api/v1/admin/system/restart
 func (h *SystemHandler) RestartService(c *gin.Context) {
-	// 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()
-	}()
+	operationID := buildSystemOperationID(c, "restart")
+	payload := gin.H{"operation_id": operationID}
+	executeAdminIdempotentJSON(c, "admin.system.restart", payload, service.DefaultSystemOperationIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		lock, release, err := h.acquireSystemLock(ctx, operationID)
+		if err != nil {
+			return nil, err
+		}
+		succeeded := false
+		defer func() {
+			release("", succeeded)
+		}()

-	response.Success(c, gin.H{
-		"message": "Service restart initiated",
+		// Schedule service restart in background after sending response
+		// This ensures the client receives the success response before the service restarts
+		go func() {
+			// Wait a moment to ensure the response is sent
+			time.Sleep(500 * time.Millisecond)
+			sysutil.RestartServiceAsync()
+		}()
+		succeeded = true
+		return gin.H{
+			"message":      "Service restart initiated",
+			"operation_id": lock.OperationID(),
+		}, nil
 	})
 }
+
+func (h *SystemHandler) acquireSystemLock(
+	ctx context.Context,
+	operationID string,
+) (*service.SystemOperationLock, func(string, bool), error) {
+	if h.lockSvc == nil {
+		return nil, nil, service.ErrIdempotencyStoreUnavail
+	}
+	lock, err := h.lockSvc.Acquire(ctx, operationID)
+	if err != nil {
+		return nil, nil, err
+	}
+	release := func(reason string, succeeded bool) {
+		releaseCtx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+		defer cancel()
+		_ = h.lockSvc.Release(releaseCtx, lock, succeeded, reason)
+	}
+	return lock, release, nil
+}
+
+func buildSystemOperationID(c *gin.Context, operation string) string {
+	key := strings.TrimSpace(c.GetHeader("Idempotency-Key"))
+	if key == "" {
+		return "sysop-" + operation + "-" + strconv.FormatInt(time.Now().UnixNano(), 36)
+	}
+	actorScope := "admin:0"
+	if subject, ok := middleware2.GetAuthSubjectFromContext(c); ok {
+		actorScope = "admin:" + strconv.FormatInt(subject.UserID, 10)
+	}
+	seed := operation + "|" + actorScope + "|" + c.FullPath() + "|" + key
+	hash := service.HashIdempotencyKey(seed)
+	if len(hash) > 24 {
+		hash = hash[:24]
+	}
+	return "sysop-" + hash
+}
--- a/backend/internal/handler/admin/usage_handler.go
+++ b/backend/internal/handler/admin/usage_handler.go
@@ -1,13 +1,14 @@
 package admin

 import (
-	"log"
+	"context"
 	"net/http"
 	"strconv"
 	"strings"
 	"time"

 	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/logger"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
@@ -378,11 +379,11 @@ func (h *UsageHandler) ListCleanupTasks(c *gin.Context) {
 		operator = subject.UserID
 	}
 	page, pageSize := response.ParsePagination(c)
-	log.Printf("[UsageCleanup] 请求清理任务列表: operator=%d page=%d page_size=%d", operator, page, pageSize)
+	logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 请求清理任务列表: operator=%d page=%d page_size=%d", operator, page, pageSize)
 	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	tasks, result, err := h.cleanupService.ListTasks(c.Request.Context(), params)
 	if err != nil {
-		log.Printf("[UsageCleanup] 查询清理任务列表失败: operator=%d page=%d page_size=%d err=%v", operator, page, pageSize, err)
+		logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 查询清理任务列表失败: operator=%d page=%d page_size=%d err=%v", operator, page, pageSize, err)
 		response.ErrorFrom(c, err)
 		return
 	}
@@ -390,7 +391,7 @@ func (h *UsageHandler) ListCleanupTasks(c *gin.Context) {
 	for i := range tasks {
 		out = append(out, *dto.UsageCleanupTaskFromService(&tasks[i]))
 	}
-	log.Printf("[UsageCleanup] 返回清理任务列表: operator=%d total=%d items=%d page=%d page_size=%d", operator, result.Total, len(out), page, pageSize)
+	logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 返回清理任务列表: operator=%d total=%d items=%d page=%d page_size=%d", operator, result.Total, len(out), page, pageSize)
 	response.Paginated(c, out, result.Total, page, pageSize)
 }

@@ -472,29 +473,36 @@ func (h *UsageHandler) CreateCleanupTask(c *gin.Context) {
 		billingType = *filters.BillingType
 	}

-	log.Printf("[UsageCleanup] 请求创建清理任务: operator=%d start=%s end=%s user_id=%v api_key_id=%v account_id=%v group_id=%v model=%v stream=%v billing_type=%v tz=%q",
-		subject.UserID,
-		filters.StartTime.Format(time.RFC3339),
-		filters.EndTime.Format(time.RFC3339),
-		userID,
-		apiKeyID,
-		accountID,
-		groupID,
-		model,
-		stream,
-		billingType,
-		req.Timezone,
-	)
-
-	task, err := h.cleanupService.CreateTask(c.Request.Context(), filters, subject.UserID)
-	if err != nil {
-		log.Printf("[UsageCleanup] 创建清理任务失败: operator=%d err=%v", subject.UserID, err)
-		response.ErrorFrom(c, err)
-		return
+	idempotencyPayload := struct {
+		OperatorID int64                         `json:"operator_id"`
+		Body       CreateUsageCleanupTaskRequest `json:"body"`
+	}{
+		OperatorID: subject.UserID,
+		Body:       req,
 	}
+	executeAdminIdempotentJSON(c, "admin.usage.cleanup_tasks.create", idempotencyPayload, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 请求创建清理任务: operator=%d start=%s end=%s user_id=%v api_key_id=%v account_id=%v group_id=%v model=%v stream=%v billing_type=%v tz=%q",
+			subject.UserID,
+			filters.StartTime.Format(time.RFC3339),
+			filters.EndTime.Format(time.RFC3339),
+			userID,
+			apiKeyID,
+			accountID,
+			groupID,
+			model,
+			stream,
+			billingType,
+			req.Timezone,
+		)

-	log.Printf("[UsageCleanup] 清理任务已创建: task=%d operator=%d status=%s", task.ID, subject.UserID, task.Status)
-	response.Success(c, dto.UsageCleanupTaskFromService(task))
+		task, err := h.cleanupService.CreateTask(ctx, filters, subject.UserID)
+		if err != nil {
+			logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 创建清理任务失败: operator=%d err=%v", subject.UserID, err)
+			return nil, err
+		}
+		logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 清理任务已创建: task=%d operator=%d status=%s", task.ID, subject.UserID, task.Status)
+		return dto.UsageCleanupTaskFromService(task), nil
+	})
 }

 // CancelCleanupTask handles canceling a usage cleanup task
@@ -515,12 +523,12 @@ func (h *UsageHandler) CancelCleanupTask(c *gin.Context) {
 		response.BadRequest(c, "Invalid task id")
 		return
 	}
-	log.Printf("[UsageCleanup] 请求取消清理任务: task=%d operator=%d", taskID, subject.UserID)
+	logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 请求取消清理任务: task=%d operator=%d", taskID, subject.UserID)
 	if err := h.cleanupService.CancelTask(c.Request.Context(), taskID, subject.UserID); err != nil {
-		log.Printf("[UsageCleanup] 取消清理任务失败: task=%d operator=%d err=%v", taskID, subject.UserID, err)
+		logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 取消清理任务失败: task=%d operator=%d err=%v", taskID, subject.UserID, err)
 		response.ErrorFrom(c, err)
 		return
 	}
-	log.Printf("[UsageCleanup] 清理任务已取消: task=%d operator=%d", taskID, subject.UserID)
+	logger.LegacyPrintf("handler.admin.usage", "[UsageCleanup] 清理任务已取消: task=%d operator=%d", taskID, subject.UserID)
 	response.Success(c, gin.H{"id": taskID, "status": service.UsageCleanupStatusCanceled})
 }
--- a/backend/internal/handler/admin/user_handler.go
+++ b/backend/internal/handler/admin/user_handler.go
@@ -1,6 +1,7 @@
 package admin

 import (
+	"context"
 	"strconv"
 	"strings"

@@ -78,8 +79,8 @@ func (h *UserHandler) List(c *gin.Context) {
 	search := c.Query("search")
 	// 标准化和验证 search 参数
 	search = strings.TrimSpace(search)
-	if len(search) > 100 {
-		search = search[:100]
+	if runes := []rune(search); len(runes) > 100 {
+		search = string(runes[:100])
 	}

 	filters := service.UserListFilters{
@@ -257,13 +258,20 @@ func (h *UserHandler) UpdateBalance(c *gin.Context) {
 		return
 	}

-	user, err := h.adminService.UpdateUserBalance(c.Request.Context(), userID, req.Balance, req.Operation, req.Notes)
-	if err != nil {
-		response.ErrorFrom(c, err)
-		return
+	idempotencyPayload := struct {
+		UserID int64                `json:"user_id"`
+		Body   UpdateBalanceRequest `json:"body"`
+	}{
+		UserID: userID,
+		Body:   req,
 	}
-
-	response.Success(c, dto.UserFromServiceAdmin(user))
+	executeAdminIdempotentJSON(c, "admin.users.balance.update", idempotencyPayload, service.DefaultWriteIdempotencyTTL(), func(ctx context.Context) (any, error) {
+		user, execErr := h.adminService.UpdateUserBalance(ctx, userID, req.Balance, req.Operation, req.Notes)
+		if execErr != nil {
+			return nil, execErr
+		}
+		return dto.UserFromServiceAdmin(user), nil
+	})
 }

 // GetUserAPIKeys handles getting user's API keys