refactor: 调整 server 目录结构

backend/internal/server/http.go

@@ -1,14 +1,13 @@
 package server
 
 import (
-	"github.com/Wei-Shaw/sub2api/internal/config"
-	"github.com/Wei-Shaw/sub2api/internal/handler"
-	"github.com/Wei-Shaw/sub2api/internal/middleware"
-	"github.com/Wei-Shaw/sub2api/internal/repository"
-	"github.com/Wei-Shaw/sub2api/internal/service"
 	"net/http"
 	"time"
 
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/handler"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+
 	"github.com/gin-gonic/gin"
 	"github.com/google/wire"
 )
@@ -20,15 +19,21 @@ var ProviderSet = wire.NewSet(
 )
 
 // ProvideRouter 提供路由器
-func ProvideRouter(cfg *config.Config, handlers *handler.Handlers, services *service.Services, repos *repository.Repositories) *gin.Engine {
+func ProvideRouter(
+	cfg *config.Config,
+	handlers *handler.Handlers,
+	jwtAuth middleware2.JWTAuthMiddleware,
+	adminAuth middleware2.AdminAuthMiddleware,
+	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+) *gin.Engine {
 	if cfg.Server.Mode == "release" {
 		gin.SetMode(gin.ReleaseMode)
 	}
 
 	r := gin.New()
-	r.Use(middleware.Recovery())
+	r.Use(middleware2.Recovery())
 
-	return SetupRouter(r, cfg, handlers, services, repos)
+	return SetupRouter(r, handlers, jwtAuth, adminAuth, apiKeyAuth)
 }
 
 // ProvideHTTPServer 提供 HTTP 服务器

backend/internal/server/middleware/admin_auth.go

@@ -0,0 +1,133 @@
+package middleware
+
+import (
+	"crypto/subtle"
+	"errors"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// NewAdminAuthMiddleware 创建管理员认证中间件
+func NewAdminAuthMiddleware(
+	authService *service.AuthService,
+	userService *service.UserService,
+	settingService *service.SettingService,
+) AdminAuthMiddleware {
+	return AdminAuthMiddleware(adminAuth(authService, userService, settingService))
+}
+
+// adminAuth 管理员认证中间件实现
+// 支持两种认证方式（通过不同的 header 区分）：
+// 1. Admin API Key: x-api-key: <admin-api-key>
+// 2. JWT Token: Authorization: Bearer <jwt-token> (需要管理员角色)
+func adminAuth(
+	authService *service.AuthService,
+	userService *service.UserService,
+	settingService *service.SettingService,
+) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 检查 x-api-key header（Admin API Key 认证）
+		apiKey := c.GetHeader("x-api-key")
+		if apiKey != "" {
+			if !validateAdminApiKey(c, apiKey, settingService, userService) {
+				return
+			}
+			c.Next()
+			return
+		}
+
+		// 检查 Authorization header（JWT 认证）
+		authHeader := c.GetHeader("Authorization")
+		if authHeader != "" {
+			parts := strings.SplitN(authHeader, " ", 2)
+			if len(parts) == 2 && parts[0] == "Bearer" {
+				if !validateJWTForAdmin(c, parts[1], authService, userService) {
+					return
+				}
+				c.Next()
+				return
+			}
+		}
+
+		// 无有效认证信息
+		AbortWithError(c, 401, "UNAUTHORIZED", "Authorization required")
+	}
+}
+
+// validateAdminApiKey 验证管理员 API Key
+func validateAdminApiKey(
+	c *gin.Context,
+	key string,
+	settingService *service.SettingService,
+	userService *service.UserService,
+) bool {
+	storedKey, err := settingService.GetAdminApiKey(c.Request.Context())
+	if err != nil {
+		AbortWithError(c, 500, "INTERNAL_ERROR", "Internal server error")
+		return false
+	}
+
+	// 未配置或不匹配，统一返回相同错误（避免信息泄露）
+	if storedKey == "" || subtle.ConstantTimeCompare([]byte(key), []byte(storedKey)) != 1 {
+		AbortWithError(c, 401, "INVALID_ADMIN_KEY", "Invalid admin API key")
+		return false
+	}
+
+	// 获取真实的管理员用户
+	admin, err := userService.GetFirstAdmin(c.Request.Context())
+	if err != nil {
+		AbortWithError(c, 500, "INTERNAL_ERROR", "No admin user found")
+		return false
+	}
+
+	c.Set(string(ContextKeyUser), admin)
+	c.Set("auth_method", "admin_api_key")
+	return true
+}
+
+// validateJWTForAdmin 验证 JWT 并检查管理员权限
+func validateJWTForAdmin(
+	c *gin.Context,
+	token string,
+	authService *service.AuthService,
+	userService *service.UserService,
+) bool {
+	// 验证 JWT token
+	claims, err := authService.ValidateToken(token)
+	if err != nil {
+		if errors.Is(err, service.ErrTokenExpired) {
+			AbortWithError(c, 401, "TOKEN_EXPIRED", "Token has expired")
+			return false
+		}
+		AbortWithError(c, 401, "INVALID_TOKEN", "Invalid token")
+		return false
+	}
+
+	// 从数据库获取用户
+	user, err := userService.GetByID(c.Request.Context(), claims.UserID)
+	if err != nil {
+		AbortWithError(c, 401, "USER_NOT_FOUND", "User not found")
+		return false
+	}
+
+	// 检查用户状态
+	if !user.IsActive() {
+		AbortWithError(c, 401, "USER_INACTIVE", "User account is not active")
+		return false
+	}
+
+	// 检查管理员权限
+	if user.Role != model.RoleAdmin {
+		AbortWithError(c, 403, "FORBIDDEN", "Admin access required")
+		return false
+	}
+
+	c.Set(string(ContextKeyUser), user)
+	c.Set("auth_method", "jwt")
+
+	return true
+}

backend/internal/server/middleware/admin_only.go

@@ -0,0 +1,28 @@
+package middleware
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/model"
+
+	"github.com/gin-gonic/gin"
+)
+
+// AdminOnly 管理员权限中间件
+// 必须在JWTAuth中间件之后使用
+func AdminOnly() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 从上下文获取用户
+		user, exists := GetUserFromContext(c)
+		if !exists {
+			AbortWithError(c, 401, "UNAUTHORIZED", "User not found in context")
+			return
+		}
+
+		// 检查是否为管理员
+		if user.Role != model.RoleAdmin {
+			AbortWithError(c, 403, "FORBIDDEN", "Admin access required")
+			return
+		}
+
+		c.Next()
+	}
+}

backend/internal/server/middleware/api_key_auth.go

@@ -0,0 +1,148 @@
+package middleware
+
+import (
+	"errors"
+	"log"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// NewApiKeyAuthMiddleware 创建 API Key 认证中间件
+func NewApiKeyAuthMiddleware(apiKeyService *service.ApiKeyService, subscriptionService *service.SubscriptionService) ApiKeyAuthMiddleware {
+	return ApiKeyAuthMiddleware(apiKeyAuthWithSubscription(apiKeyService, subscriptionService))
+}
+
+// apiKeyAuthWithSubscription API Key认证中间件（支持订阅验证）
+func apiKeyAuthWithSubscription(apiKeyService *service.ApiKeyService, subscriptionService *service.SubscriptionService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 尝试从Authorization header中提取API key (Bearer scheme)
+		authHeader := c.GetHeader("Authorization")
+		var apiKeyString string
+
+		if authHeader != "" {
+			// 验证Bearer scheme
+			parts := strings.SplitN(authHeader, " ", 2)
+			if len(parts) == 2 && parts[0] == "Bearer" {
+				apiKeyString = parts[1]
+			}
+		}
+
+		// 如果Authorization header中没有，尝试从x-api-key header中提取
+		if apiKeyString == "" {
+			apiKeyString = c.GetHeader("x-api-key")
+		}
+
+		// 如果两个header都没有API key
+		if apiKeyString == "" {
+			AbortWithError(c, 401, "API_KEY_REQUIRED", "API key is required in Authorization header (Bearer scheme) or x-api-key header")
+			return
+		}
+
+		// 从数据库验证API key
+		apiKey, err := apiKeyService.GetByKey(c.Request.Context(), apiKeyString)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				AbortWithError(c, 401, "INVALID_API_KEY", "Invalid API key")
+				return
+			}
+			AbortWithError(c, 500, "INTERNAL_ERROR", "Failed to validate API key")
+			return
+		}
+
+		// 检查API key是否激活
+		if !apiKey.IsActive() {
+			AbortWithError(c, 401, "API_KEY_DISABLED", "API key is disabled")
+			return
+		}
+
+		// 检查关联的用户
+		if apiKey.User == nil {
+			AbortWithError(c, 401, "USER_NOT_FOUND", "User associated with API key not found")
+			return
+		}
+
+		// 检查用户状态
+		if !apiKey.User.IsActive() {
+			AbortWithError(c, 401, "USER_INACTIVE", "User account is not active")
+			return
+		}
+
+		// 判断计费方式：订阅模式 vs 余额模式
+		isSubscriptionType := apiKey.Group != nil && apiKey.Group.IsSubscriptionType()
+
+		if isSubscriptionType && subscriptionService != nil {
+			// 订阅模式：验证订阅
+			subscription, err := subscriptionService.GetActiveSubscription(
+				c.Request.Context(),
+				apiKey.User.ID,
+				apiKey.Group.ID,
+			)
+			if err != nil {
+				AbortWithError(c, 403, "SUBSCRIPTION_NOT_FOUND", "No active subscription found for this group")
+				return
+			}
+
+			// 验证订阅状态（是否过期、暂停等）
+			if err := subscriptionService.ValidateSubscription(c.Request.Context(), subscription); err != nil {
+				AbortWithError(c, 403, "SUBSCRIPTION_INVALID", err.Error())
+				return
+			}
+
+			// 激活滑动窗口（首次使用时）
+			if err := subscriptionService.CheckAndActivateWindow(c.Request.Context(), subscription); err != nil {
+				log.Printf("Failed to activate subscription windows: %v", err)
+			}
+
+			// 检查并重置过期窗口
+			if err := subscriptionService.CheckAndResetWindows(c.Request.Context(), subscription); err != nil {
+				log.Printf("Failed to reset subscription windows: %v", err)
+			}
+
+			// 预检查用量限制（使用0作为额外费用进行预检查）
+			if err := subscriptionService.CheckUsageLimits(c.Request.Context(), subscription, apiKey.Group, 0); err != nil {
+				AbortWithError(c, 429, "USAGE_LIMIT_EXCEEDED", err.Error())
+				return
+			}
+
+			// 将订阅信息存入上下文
+			c.Set(string(ContextKeySubscription), subscription)
+		} else {
+			// 余额模式：检查用户余额
+			if apiKey.User.Balance <= 0 {
+				AbortWithError(c, 403, "INSUFFICIENT_BALANCE", "Insufficient account balance")
+				return
+			}
+		}
+
+		// 将API key和用户信息存入上下文
+		c.Set(string(ContextKeyApiKey), apiKey)
+		c.Set(string(ContextKeyUser), apiKey.User)
+
+		c.Next()
+	}
+}
+
+// GetApiKeyFromContext 从上下文中获取API key
+func GetApiKeyFromContext(c *gin.Context) (*model.ApiKey, bool) {
+	value, exists := c.Get(string(ContextKeyApiKey))
+	if !exists {
+		return nil, false
+	}
+	apiKey, ok := value.(*model.ApiKey)
+	return apiKey, ok
+}
+
+// GetSubscriptionFromContext 从上下文中获取订阅信息
+func GetSubscriptionFromContext(c *gin.Context) (*model.UserSubscription, bool) {
+	value, exists := c.Get(string(ContextKeySubscription))
+	if !exists {
+		return nil, false
+	}
+	subscription, ok := value.(*model.UserSubscription)
+	return subscription, ok
+}

backend/internal/server/middleware/cors.go

@@ -0,0 +1,24 @@
+package middleware
+
+import (
+	"github.com/gin-gonic/gin"
+)
+
+// CORS 跨域中间件
+func CORS() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 设置允许跨域的响应头
+		c.Writer.Header().Set("Access-Control-Allow-Origin", "*")
+		c.Writer.Header().Set("Access-Control-Allow-Credentials", "true")
+		c.Writer.Header().Set("Access-Control-Allow-Headers", "Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, accept, origin, Cache-Control, X-Requested-With, X-API-Key")
+		c.Writer.Header().Set("Access-Control-Allow-Methods", "POST, OPTIONS, GET, PUT, DELETE, PATCH")
+
+		// 处理预检请求
+		if c.Request.Method == "OPTIONS" {
+			c.AbortWithStatus(204)
+			return
+		}
+
+		c.Next()
+	}
+}

backend/internal/server/middleware/jwt_auth.go

@@ -0,0 +1,80 @@
+package middleware
+
+import (
+	"errors"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// NewJWTAuthMiddleware 创建 JWT 认证中间件
+func NewJWTAuthMiddleware(authService *service.AuthService, userService *service.UserService) JWTAuthMiddleware {
+	return JWTAuthMiddleware(jwtAuth(authService, userService))
+}
+
+// jwtAuth JWT认证中间件实现
+func jwtAuth(authService *service.AuthService, userService *service.UserService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 从Authorization header中提取token
+		authHeader := c.GetHeader("Authorization")
+		if authHeader == "" {
+			AbortWithError(c, 401, "UNAUTHORIZED", "Authorization header is required")
+			return
+		}
+
+		// 验证Bearer scheme
+		parts := strings.SplitN(authHeader, " ", 2)
+		if len(parts) != 2 || parts[0] != "Bearer" {
+			AbortWithError(c, 401, "INVALID_AUTH_HEADER", "Authorization header format must be 'Bearer {token}'")
+			return
+		}
+
+		tokenString := parts[1]
+		if tokenString == "" {
+			AbortWithError(c, 401, "EMPTY_TOKEN", "Token cannot be empty")
+			return
+		}
+
+		// 验证token
+		claims, err := authService.ValidateToken(tokenString)
+		if err != nil {
+			if errors.Is(err, service.ErrTokenExpired) {
+				AbortWithError(c, 401, "TOKEN_EXPIRED", "Token has expired")
+				return
+			}
+			AbortWithError(c, 401, "INVALID_TOKEN", "Invalid token")
+			return
+		}
+
+		// 从数据库获取最新的用户信息
+		user, err := userService.GetByID(c.Request.Context(), claims.UserID)
+		if err != nil {
+			AbortWithError(c, 401, "USER_NOT_FOUND", "User not found")
+			return
+		}
+
+		// 检查用户状态
+		if !user.IsActive() {
+			AbortWithError(c, 401, "USER_INACTIVE", "User account is not active")
+			return
+		}
+
+		// 将用户信息存入上下文
+		c.Set(string(ContextKeyUser), user)
+
+		c.Next()
+	}
+}
+
+// GetUserFromContext 从上下文中获取用户
+func GetUserFromContext(c *gin.Context) (*model.User, bool) {
+	value, exists := c.Get(string(ContextKeyUser))
+	if !exists {
+		return nil, false
+	}
+	user, ok := value.(*model.User)
+	return user, ok
+}

backend/internal/server/middleware/logger.go

@@ -0,0 +1,52 @@
+package middleware
+
+import (
+	"log"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Logger 请求日志中间件
+func Logger() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 开始时间
+		startTime := time.Now()
+
+		// 处理请求
+		c.Next()
+
+		// 结束时间
+		endTime := time.Now()
+
+		// 执行时间
+		latency := endTime.Sub(startTime)
+
+		// 请求方法
+		method := c.Request.Method
+
+		// 请求路径
+		path := c.Request.URL.Path
+
+		// 状态码
+		statusCode := c.Writer.Status()
+
+		// 客户端IP
+		clientIP := c.ClientIP()
+
+		// 日志格式: [时间] 状态码 | 延迟 | IP | 方法 路径
+		log.Printf("[GIN] %v | %3d | %13v | %15s | %-7s %s",
+			endTime.Format("2006/01/02 - 15:04:05"),
+			statusCode,
+			latency,
+			clientIP,
+			method,
+			path,
+		)
+
+		// 如果有错误，额外记录错误信息
+		if len(c.Errors) > 0 {
+			log.Printf("[GIN] Errors: %v", c.Errors.String())
+		}
+	}
+}

backend/internal/server/middleware/middleware.go

@@ -0,0 +1,35 @@
+package middleware
+
+import "github.com/gin-gonic/gin"
+
+// ContextKey 定义上下文键类型
+type ContextKey string
+
+const (
+	// ContextKeyUser 用户上下文键
+	ContextKeyUser ContextKey = "user"
+	// ContextKeyApiKey API密钥上下文键
+	ContextKeyApiKey ContextKey = "api_key"
+	// ContextKeySubscription 订阅上下文键
+	ContextKeySubscription ContextKey = "subscription"
+)
+
+// ErrorResponse 标准错误响应结构
+type ErrorResponse struct {
+	Code    string `json:"code"`
+	Message string `json:"message"`
+}
+
+// NewErrorResponse 创建错误响应
+func NewErrorResponse(code, message string) ErrorResponse {
+	return ErrorResponse{
+		Code:    code,
+		Message: message,
+	}
+}
+
+// AbortWithError 中断请求并返回JSON错误
+func AbortWithError(c *gin.Context, statusCode int, code, message string) {
+	c.JSON(statusCode, NewErrorResponse(code, message))
+	c.Abort()
+}

backend/internal/server/middleware/recovery.go

@@ -0,0 +1,64 @@
+package middleware
+
+import (
+	"errors"
+	"net"
+	"net/http"
+	"os"
+	"strings"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/gin-gonic/gin"
+)
+
+// Recovery converts panics into the project's standard JSON error envelope.
+//
+// It preserves Gin's broken-pipe handling by not attempting to write a response
+// when the client connection is already gone.
+func Recovery() gin.HandlerFunc {
+	return gin.CustomRecoveryWithWriter(gin.DefaultErrorWriter, func(c *gin.Context, recovered any) {
+		recoveredErr, _ := recovered.(error)
+
+		if isBrokenPipe(recoveredErr) {
+			if recoveredErr != nil {
+				_ = c.Error(recoveredErr)
+			}
+			c.Abort()
+			return
+		}
+
+		if c.Writer.Written() {
+			c.Abort()
+			return
+		}
+
+		response.ErrorWithDetails(
+			c,
+			http.StatusInternalServerError,
+			infraerrors.UnknownMessage,
+			infraerrors.UnknownReason,
+			nil,
+		)
+		c.Abort()
+	})
+}
+
+func isBrokenPipe(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	var opErr *net.OpError
+	if !errors.As(err, &opErr) {
+		return false
+	}
+
+	var syscallErr *os.SyscallError
+	if !errors.As(opErr.Err, &syscallErr) {
+		return false
+	}
+
+	msg := strings.ToLower(syscallErr.Error())
+	return strings.Contains(msg, "broken pipe") || strings.Contains(msg, "connection reset by peer")
+}

backend/internal/server/middleware/recovery_test.go

@@ -0,0 +1,81 @@
+//go:build unit
+
+package middleware
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRecovery(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	tests := []struct {
+		name         string
+		handler      gin.HandlerFunc
+		wantHTTPCode int
+		wantBody     response.Response
+	}{
+		{
+			name: "panic_returns_standard_json_500",
+			handler: func(c *gin.Context) {
+				panic("boom")
+			},
+			wantHTTPCode: http.StatusInternalServerError,
+			wantBody: response.Response{
+				Code:    http.StatusInternalServerError,
+				Message: infraerrors.UnknownMessage,
+			},
+		},
+		{
+			name: "no_panic_passthrough",
+			handler: func(c *gin.Context) {
+				response.Success(c, gin.H{"ok": true})
+			},
+			wantHTTPCode: http.StatusOK,
+			wantBody: response.Response{
+				Code:    0,
+				Message: "success",
+				Data:    map[string]any{"ok": true},
+			},
+		},
+		{
+			name: "panic_after_write_does_not_override_body",
+			handler: func(c *gin.Context) {
+				response.Success(c, gin.H{"ok": true})
+				panic("boom")
+			},
+			wantHTTPCode: http.StatusOK,
+			wantBody: response.Response{
+				Code:    0,
+				Message: "success",
+				Data:    map[string]any{"ok": true},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			r := gin.New()
+			r.Use(Recovery())
+			r.GET("/t", tt.handler)
+
+			w := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodGet, "/t", nil)
+			r.ServeHTTP(w, req)
+
+			require.Equal(t, tt.wantHTTPCode, w.Code)
+
+			var got response.Response
+			require.NoError(t, json.Unmarshal(w.Body.Bytes(), &got))
+			require.Equal(t, tt.wantBody, got)
+		})
+	}
+}

backend/internal/server/middleware/wire.go

@@ -0,0 +1,22 @@
+package middleware
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/google/wire"
+)
+
+// JWTAuthMiddleware JWT 认证中间件类型
+type JWTAuthMiddleware gin.HandlerFunc
+
+// AdminAuthMiddleware 管理员认证中间件类型
+type AdminAuthMiddleware gin.HandlerFunc
+
+// ApiKeyAuthMiddleware API Key 认证中间件类型
+type ApiKeyAuthMiddleware gin.HandlerFunc
+
+// ProviderSet 中间件层的依赖注入
+var ProviderSet = wire.NewSet(
+	NewJWTAuthMiddleware,
+	NewAdminAuthMiddleware,
+	NewApiKeyAuthMiddleware,
+)

backend/internal/server/router.go

@@ -1,312 +1,54 @@
 package server
 
 import (
-	"github.com/Wei-Shaw/sub2api/internal/config"
 	"github.com/Wei-Shaw/sub2api/internal/handler"
-	"github.com/Wei-Shaw/sub2api/internal/middleware"
-	"github.com/Wei-Shaw/sub2api/internal/repository"
-	"github.com/Wei-Shaw/sub2api/internal/service"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/server/routes"
 	"github.com/Wei-Shaw/sub2api/internal/web"
-	"net/http"
 
 	"github.com/gin-gonic/gin"
 )
 
 // SetupRouter 配置路由器中间件和路由
-func SetupRouter(r *gin.Engine, cfg *config.Config, handlers *handler.Handlers, services *service.Services, repos *repository.Repositories) *gin.Engine {
+func SetupRouter(
+	r *gin.Engine,
+	handlers *handler.Handlers,
+	jwtAuth middleware2.JWTAuthMiddleware,
+	adminAuth middleware2.AdminAuthMiddleware,
+	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+) *gin.Engine {
 	// 应用中间件
-	r.Use(middleware.Logger())
-	r.Use(middleware.CORS())
-
-	// 注册路由
-	registerRoutes(r, handlers, services, repos)
+	r.Use(middleware2.Logger())
+	r.Use(middleware2.CORS())
 
 	// Serve embedded frontend if available
 	if web.HasEmbeddedFrontend() {
 		r.Use(web.ServeEmbeddedFrontend())
 	}
 
+	// 注册路由
+	registerRoutes(r, handlers, jwtAuth, adminAuth, apiKeyAuth)
+
 	return r
 }
 
 // registerRoutes 注册所有 HTTP 路由
-func registerRoutes(r *gin.Engine, h *handler.Handlers, s *service.Services, repos *repository.Repositories) {
-	// 健康检查
-	r.GET("/health", func(c *gin.Context) {
-		c.JSON(http.StatusOK, gin.H{"status": "ok"})
-	})
-
-	// Claude Code 遥测日志（忽略，直接返回200）
-	r.POST("/api/event_logging/batch", func(c *gin.Context) {
-		c.Status(http.StatusOK)
-	})
-
-	// Setup status endpoint (always returns needs_setup: false in normal mode)
-	// This is used by the frontend to detect when the service has restarted after setup
-	r.GET("/setup/status", func(c *gin.Context) {
-		c.JSON(http.StatusOK, gin.H{
-			"code": 0,
-			"data": gin.H{
-				"needs_setup": false,
-				"step":        "completed",
-			},
-		})
-	})
+func registerRoutes(
+	r *gin.Engine,
+	h *handler.Handlers,
+	jwtAuth middleware2.JWTAuthMiddleware,
+	adminAuth middleware2.AdminAuthMiddleware,
+	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+) {
+	// 通用路由（健康检查、状态等）
+	routes.RegisterCommonRoutes(r)
 
 	// API v1
 	v1 := r.Group("/api/v1")
-	{
-		// 公开接口
-		auth := v1.Group("/auth")
-		{
-			auth.POST("/register", h.Auth.Register)
-			auth.POST("/login", h.Auth.Login)
-			auth.POST("/send-verify-code", h.Auth.SendVerifyCode)
-		}
 
-		// 公开设置（无需认证）
-		settings := v1.Group("/settings")
-		{
-			settings.GET("/public", h.Setting.GetPublicSettings)
-		}
-
-		// 需要认证的接口
-		authenticated := v1.Group("")
-		authenticated.Use(middleware.JWTAuth(s.Auth, repos.User))
-		{
-			// 当前用户信息
-			authenticated.GET("/auth/me", h.Auth.GetCurrentUser)
-
-			// 用户接口
-			user := authenticated.Group("/user")
-			{
-				user.GET("/profile", h.User.GetProfile)
-				user.PUT("/password", h.User.ChangePassword)
-				user.PUT("", h.User.UpdateProfile)
-			}
-
-			// API Key管理
-			keys := authenticated.Group("/keys")
-			{
-				keys.GET("", h.APIKey.List)
-				keys.GET("/:id", h.APIKey.GetByID)
-				keys.POST("", h.APIKey.Create)
-				keys.PUT("/:id", h.APIKey.Update)
-				keys.DELETE("/:id", h.APIKey.Delete)
-			}
-
-			// 用户可用分组（非管理员接口）
-			groups := authenticated.Group("/groups")
-			{
-				groups.GET("/available", h.APIKey.GetAvailableGroups)
-			}
-
-			// 使用记录
-			usage := authenticated.Group("/usage")
-			{
-				usage.GET("", h.Usage.List)
-				usage.GET("/:id", h.Usage.GetByID)
-				usage.GET("/stats", h.Usage.Stats)
-				// User dashboard endpoints
-				usage.GET("/dashboard/stats", h.Usage.DashboardStats)
-				usage.GET("/dashboard/trend", h.Usage.DashboardTrend)
-				usage.GET("/dashboard/models", h.Usage.DashboardModels)
-				usage.POST("/dashboard/api-keys-usage", h.Usage.DashboardApiKeysUsage)
-			}
-
-			// 卡密兑换
-			redeem := authenticated.Group("/redeem")
-			{
-				redeem.POST("", h.Redeem.Redeem)
-				redeem.GET("/history", h.Redeem.GetHistory)
-			}
-
-			// 用户订阅
-			subscriptions := authenticated.Group("/subscriptions")
-			{
-				subscriptions.GET("", h.Subscription.List)
-				subscriptions.GET("/active", h.Subscription.GetActive)
-				subscriptions.GET("/progress", h.Subscription.GetProgress)
-				subscriptions.GET("/summary", h.Subscription.GetSummary)
-			}
-		}
-
-		// 管理员接口
-		admin := v1.Group("/admin")
-		admin.Use(middleware.AdminAuth(s.Auth, repos.User, s.Setting))
-		{
-			// 仪表盘
-			dashboard := admin.Group("/dashboard")
-			{
-				dashboard.GET("/stats", h.Admin.Dashboard.GetStats)
-				dashboard.GET("/realtime", h.Admin.Dashboard.GetRealtimeMetrics)
-				dashboard.GET("/trend", h.Admin.Dashboard.GetUsageTrend)
-				dashboard.GET("/models", h.Admin.Dashboard.GetModelStats)
-				dashboard.GET("/api-keys-trend", h.Admin.Dashboard.GetApiKeyUsageTrend)
-				dashboard.GET("/users-trend", h.Admin.Dashboard.GetUserUsageTrend)
-				dashboard.POST("/users-usage", h.Admin.Dashboard.GetBatchUsersUsage)
-				dashboard.POST("/api-keys-usage", h.Admin.Dashboard.GetBatchApiKeysUsage)
-			}
-
-			// 用户管理
-			users := admin.Group("/users")
-			{
-				users.GET("", h.Admin.User.List)
-				users.GET("/:id", h.Admin.User.GetByID)
-				users.POST("", h.Admin.User.Create)
-				users.PUT("/:id", h.Admin.User.Update)
-				users.DELETE("/:id", h.Admin.User.Delete)
-				users.POST("/:id/balance", h.Admin.User.UpdateBalance)
-				users.GET("/:id/api-keys", h.Admin.User.GetUserAPIKeys)
-				users.GET("/:id/usage", h.Admin.User.GetUserUsage)
-			}
-
-			// 分组管理
-			groups := admin.Group("/groups")
-			{
-				groups.GET("", h.Admin.Group.List)
-				groups.GET("/all", h.Admin.Group.GetAll)
-				groups.GET("/:id", h.Admin.Group.GetByID)
-				groups.POST("", h.Admin.Group.Create)
-				groups.PUT("/:id", h.Admin.Group.Update)
-				groups.DELETE("/:id", h.Admin.Group.Delete)
-				groups.GET("/:id/stats", h.Admin.Group.GetStats)
-				groups.GET("/:id/api-keys", h.Admin.Group.GetGroupAPIKeys)
-			}
-
-			// 账号管理
-			accounts := admin.Group("/accounts")
-			{
-				accounts.GET("", h.Admin.Account.List)
-				accounts.GET("/:id", h.Admin.Account.GetByID)
-				accounts.POST("", h.Admin.Account.Create)
-				accounts.POST("/sync/crs", h.Admin.Account.SyncFromCRS)
-				accounts.PUT("/:id", h.Admin.Account.Update)
-				accounts.DELETE("/:id", h.Admin.Account.Delete)
-				accounts.POST("/:id/test", h.Admin.Account.Test)
-				accounts.POST("/:id/refresh", h.Admin.Account.Refresh)
-				accounts.GET("/:id/stats", h.Admin.Account.GetStats)
-				accounts.POST("/:id/clear-error", h.Admin.Account.ClearError)
-				accounts.GET("/:id/usage", h.Admin.Account.GetUsage)
-				accounts.GET("/:id/today-stats", h.Admin.Account.GetTodayStats)
-				accounts.POST("/:id/clear-rate-limit", h.Admin.Account.ClearRateLimit)
-				accounts.POST("/:id/schedulable", h.Admin.Account.SetSchedulable)
-				accounts.GET("/:id/models", h.Admin.Account.GetAvailableModels)
-				accounts.POST("/batch", h.Admin.Account.BatchCreate)
-				accounts.POST("/batch-update-credentials", h.Admin.Account.BatchUpdateCredentials)
-				accounts.POST("/bulk-update", h.Admin.Account.BulkUpdate)
-
-				// Claude OAuth routes
-				accounts.POST("/generate-auth-url", h.Admin.OAuth.GenerateAuthURL)
-				accounts.POST("/generate-setup-token-url", h.Admin.OAuth.GenerateSetupTokenURL)
-				accounts.POST("/exchange-code", h.Admin.OAuth.ExchangeCode)
-				accounts.POST("/exchange-setup-token-code", h.Admin.OAuth.ExchangeSetupTokenCode)
-				accounts.POST("/cookie-auth", h.Admin.OAuth.CookieAuth)
-				accounts.POST("/setup-token-cookie-auth", h.Admin.OAuth.SetupTokenCookieAuth)
-			}
-
-			// OpenAI OAuth routes
-			openai := admin.Group("/openai")
-			{
-				openai.POST("/generate-auth-url", h.Admin.OpenAIOAuth.GenerateAuthURL)
-				openai.POST("/exchange-code", h.Admin.OpenAIOAuth.ExchangeCode)
-				openai.POST("/refresh-token", h.Admin.OpenAIOAuth.RefreshToken)
-				openai.POST("/accounts/:id/refresh", h.Admin.OpenAIOAuth.RefreshAccountToken)
-				openai.POST("/create-from-oauth", h.Admin.OpenAIOAuth.CreateAccountFromOAuth)
-			}
-
-			// 代理管理
-			proxies := admin.Group("/proxies")
-			{
-				proxies.GET("", h.Admin.Proxy.List)
-				proxies.GET("/all", h.Admin.Proxy.GetAll)
-				proxies.GET("/:id", h.Admin.Proxy.GetByID)
-				proxies.POST("", h.Admin.Proxy.Create)
-				proxies.PUT("/:id", h.Admin.Proxy.Update)
-				proxies.DELETE("/:id", h.Admin.Proxy.Delete)
-				proxies.POST("/:id/test", h.Admin.Proxy.Test)
-				proxies.GET("/:id/stats", h.Admin.Proxy.GetStats)
-				proxies.GET("/:id/accounts", h.Admin.Proxy.GetProxyAccounts)
-				proxies.POST("/batch", h.Admin.Proxy.BatchCreate)
-			}
-
-			// 卡密管理
-			codes := admin.Group("/redeem-codes")
-			{
-				codes.GET("", h.Admin.Redeem.List)
-				codes.GET("/stats", h.Admin.Redeem.GetStats)
-				codes.GET("/export", h.Admin.Redeem.Export)
-				codes.GET("/:id", h.Admin.Redeem.GetByID)
-				codes.POST("/generate", h.Admin.Redeem.Generate)
-				codes.DELETE("/:id", h.Admin.Redeem.Delete)
-				codes.POST("/batch-delete", h.Admin.Redeem.BatchDelete)
-				codes.POST("/:id/expire", h.Admin.Redeem.Expire)
-			}
-
-			// 系统设置
-			adminSettings := admin.Group("/settings")
-			{
-				adminSettings.GET("", h.Admin.Setting.GetSettings)
-				adminSettings.PUT("", h.Admin.Setting.UpdateSettings)
-				adminSettings.POST("/test-smtp", h.Admin.Setting.TestSmtpConnection)
-				adminSettings.POST("/send-test-email", h.Admin.Setting.SendTestEmail)
-				// Admin API Key 管理
-				adminSettings.GET("/admin-api-key", h.Admin.Setting.GetAdminApiKey)
-				adminSettings.POST("/admin-api-key/regenerate", h.Admin.Setting.RegenerateAdminApiKey)
-				adminSettings.DELETE("/admin-api-key", h.Admin.Setting.DeleteAdminApiKey)
-			}
-
-			// 系统管理
-			system := admin.Group("/system")
-			{
-				system.GET("/version", h.Admin.System.GetVersion)
-				system.GET("/check-updates", h.Admin.System.CheckUpdates)
-				system.POST("/update", h.Admin.System.PerformUpdate)
-				system.POST("/rollback", h.Admin.System.Rollback)
-				system.POST("/restart", h.Admin.System.RestartService)
-			}
-
-			// 订阅管理
-			subscriptions := admin.Group("/subscriptions")
-			{
-				subscriptions.GET("", h.Admin.Subscription.List)
-				subscriptions.GET("/:id", h.Admin.Subscription.GetByID)
-				subscriptions.GET("/:id/progress", h.Admin.Subscription.GetProgress)
-				subscriptions.POST("/assign", h.Admin.Subscription.Assign)
-				subscriptions.POST("/bulk-assign", h.Admin.Subscription.BulkAssign)
-				subscriptions.POST("/:id/extend", h.Admin.Subscription.Extend)
-				subscriptions.DELETE("/:id", h.Admin.Subscription.Revoke)
-			}
-
-			// 分组下的订阅列表
-			admin.GET("/groups/:id/subscriptions", h.Admin.Subscription.ListByGroup)
-
-			// 用户下的订阅列表
-			admin.GET("/users/:id/subscriptions", h.Admin.Subscription.ListByUser)
-
-			// 使用记录管理
-			usage := admin.Group("/usage")
-			{
-				usage.GET("", h.Admin.Usage.List)
-				usage.GET("/stats", h.Admin.Usage.Stats)
-				usage.GET("/search-users", h.Admin.Usage.SearchUsers)
-				usage.GET("/search-api-keys", h.Admin.Usage.SearchApiKeys)
-			}
-		}
-	}
-
-	// API网关（Claude API兼容）
-	gateway := r.Group("/v1")
-	gateway.Use(middleware.ApiKeyAuthWithSubscription(s.ApiKey, s.Subscription))
-	{
-		gateway.POST("/messages", h.Gateway.Messages)
-		gateway.POST("/messages/count_tokens", h.Gateway.CountTokens)
-		gateway.GET("/models", h.Gateway.Models)
-		gateway.GET("/usage", h.Gateway.Usage)
-		// OpenAI Responses API
-		gateway.POST("/responses", h.OpenAIGateway.Responses)
-	}
-
-	// OpenAI Responses API（不带v1前缀的别名）
-	r.POST("/responses", middleware.ApiKeyAuthWithSubscription(s.ApiKey, s.Subscription), h.OpenAIGateway.Responses)
+	// 注册各模块路由
+	routes.RegisterAuthRoutes(v1, h, jwtAuth)
+	routes.RegisterUserRoutes(v1, h, jwtAuth)
+	routes.RegisterAdminRoutes(v1, h, adminAuth)
+	routes.RegisterGatewayRoutes(r, h, apiKeyAuth)
 }

backend/internal/server/routes/admin.go

@@ -0,0 +1,221 @@
+package routes
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/handler"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RegisterAdminRoutes 注册管理员路由
+func RegisterAdminRoutes(
+	v1 *gin.RouterGroup,
+	h *handler.Handlers,
+	adminAuth middleware.AdminAuthMiddleware,
+) {
+	admin := v1.Group("/admin")
+	admin.Use(gin.HandlerFunc(adminAuth))
+	{
+		// 仪表盘
+		registerDashboardRoutes(admin, h)
+
+		// 用户管理
+		registerUserManagementRoutes(admin, h)
+
+		// 分组管理
+		registerGroupRoutes(admin, h)
+
+		// 账号管理
+		registerAccountRoutes(admin, h)
+
+		// OpenAI OAuth
+		registerOpenAIOAuthRoutes(admin, h)
+
+		// 代理管理
+		registerProxyRoutes(admin, h)
+
+		// 卡密管理
+		registerRedeemCodeRoutes(admin, h)
+
+		// 系统设置
+		registerSettingsRoutes(admin, h)
+
+		// 系统管理
+		registerSystemRoutes(admin, h)
+
+		// 订阅管理
+		registerSubscriptionRoutes(admin, h)
+
+		// 使用记录管理
+		registerUsageRoutes(admin, h)
+	}
+}
+
+func registerDashboardRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	dashboard := admin.Group("/dashboard")
+	{
+		dashboard.GET("/stats", h.Admin.Dashboard.GetStats)
+		dashboard.GET("/realtime", h.Admin.Dashboard.GetRealtimeMetrics)
+		dashboard.GET("/trend", h.Admin.Dashboard.GetUsageTrend)
+		dashboard.GET("/models", h.Admin.Dashboard.GetModelStats)
+		dashboard.GET("/api-keys-trend", h.Admin.Dashboard.GetApiKeyUsageTrend)
+		dashboard.GET("/users-trend", h.Admin.Dashboard.GetUserUsageTrend)
+		dashboard.POST("/users-usage", h.Admin.Dashboard.GetBatchUsersUsage)
+		dashboard.POST("/api-keys-usage", h.Admin.Dashboard.GetBatchApiKeysUsage)
+	}
+}
+
+func registerUserManagementRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	users := admin.Group("/users")
+	{
+		users.GET("", h.Admin.User.List)
+		users.GET("/:id", h.Admin.User.GetByID)
+		users.POST("", h.Admin.User.Create)
+		users.PUT("/:id", h.Admin.User.Update)
+		users.DELETE("/:id", h.Admin.User.Delete)
+		users.POST("/:id/balance", h.Admin.User.UpdateBalance)
+		users.GET("/:id/api-keys", h.Admin.User.GetUserAPIKeys)
+		users.GET("/:id/usage", h.Admin.User.GetUserUsage)
+	}
+}
+
+func registerGroupRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	groups := admin.Group("/groups")
+	{
+		groups.GET("", h.Admin.Group.List)
+		groups.GET("/all", h.Admin.Group.GetAll)
+		groups.GET("/:id", h.Admin.Group.GetByID)
+		groups.POST("", h.Admin.Group.Create)
+		groups.PUT("/:id", h.Admin.Group.Update)
+		groups.DELETE("/:id", h.Admin.Group.Delete)
+		groups.GET("/:id/stats", h.Admin.Group.GetStats)
+		groups.GET("/:id/api-keys", h.Admin.Group.GetGroupAPIKeys)
+	}
+}
+
+func registerAccountRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	accounts := admin.Group("/accounts")
+	{
+		accounts.GET("", h.Admin.Account.List)
+		accounts.GET("/:id", h.Admin.Account.GetByID)
+		accounts.POST("", h.Admin.Account.Create)
+		accounts.POST("/sync/crs", h.Admin.Account.SyncFromCRS)
+		accounts.PUT("/:id", h.Admin.Account.Update)
+		accounts.DELETE("/:id", h.Admin.Account.Delete)
+		accounts.POST("/:id/test", h.Admin.Account.Test)
+		accounts.POST("/:id/refresh", h.Admin.Account.Refresh)
+		accounts.GET("/:id/stats", h.Admin.Account.GetStats)
+		accounts.POST("/:id/clear-error", h.Admin.Account.ClearError)
+		accounts.GET("/:id/usage", h.Admin.Account.GetUsage)
+		accounts.GET("/:id/today-stats", h.Admin.Account.GetTodayStats)
+		accounts.POST("/:id/clear-rate-limit", h.Admin.Account.ClearRateLimit)
+		accounts.POST("/:id/schedulable", h.Admin.Account.SetSchedulable)
+		accounts.GET("/:id/models", h.Admin.Account.GetAvailableModels)
+		accounts.POST("/batch", h.Admin.Account.BatchCreate)
+		accounts.POST("/batch-update-credentials", h.Admin.Account.BatchUpdateCredentials)
+		accounts.POST("/bulk-update", h.Admin.Account.BulkUpdate)
+
+		// Claude OAuth routes
+		accounts.POST("/generate-auth-url", h.Admin.OAuth.GenerateAuthURL)
+		accounts.POST("/generate-setup-token-url", h.Admin.OAuth.GenerateSetupTokenURL)
+		accounts.POST("/exchange-code", h.Admin.OAuth.ExchangeCode)
+		accounts.POST("/exchange-setup-token-code", h.Admin.OAuth.ExchangeSetupTokenCode)
+		accounts.POST("/cookie-auth", h.Admin.OAuth.CookieAuth)
+		accounts.POST("/setup-token-cookie-auth", h.Admin.OAuth.SetupTokenCookieAuth)
+	}
+}
+
+func registerOpenAIOAuthRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	openai := admin.Group("/openai")
+	{
+		openai.POST("/generate-auth-url", h.Admin.OpenAIOAuth.GenerateAuthURL)
+		openai.POST("/exchange-code", h.Admin.OpenAIOAuth.ExchangeCode)
+		openai.POST("/refresh-token", h.Admin.OpenAIOAuth.RefreshToken)
+		openai.POST("/accounts/:id/refresh", h.Admin.OpenAIOAuth.RefreshAccountToken)
+		openai.POST("/create-from-oauth", h.Admin.OpenAIOAuth.CreateAccountFromOAuth)
+	}
+}
+
+func registerProxyRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	proxies := admin.Group("/proxies")
+	{
+		proxies.GET("", h.Admin.Proxy.List)
+		proxies.GET("/all", h.Admin.Proxy.GetAll)
+		proxies.GET("/:id", h.Admin.Proxy.GetByID)
+		proxies.POST("", h.Admin.Proxy.Create)
+		proxies.PUT("/:id", h.Admin.Proxy.Update)
+		proxies.DELETE("/:id", h.Admin.Proxy.Delete)
+		proxies.POST("/:id/test", h.Admin.Proxy.Test)
+		proxies.GET("/:id/stats", h.Admin.Proxy.GetStats)
+		proxies.GET("/:id/accounts", h.Admin.Proxy.GetProxyAccounts)
+		proxies.POST("/batch", h.Admin.Proxy.BatchCreate)
+	}
+}
+
+func registerRedeemCodeRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	codes := admin.Group("/redeem-codes")
+	{
+		codes.GET("", h.Admin.Redeem.List)
+		codes.GET("/stats", h.Admin.Redeem.GetStats)
+		codes.GET("/export", h.Admin.Redeem.Export)
+		codes.GET("/:id", h.Admin.Redeem.GetByID)
+		codes.POST("/generate", h.Admin.Redeem.Generate)
+		codes.DELETE("/:id", h.Admin.Redeem.Delete)
+		codes.POST("/batch-delete", h.Admin.Redeem.BatchDelete)
+		codes.POST("/:id/expire", h.Admin.Redeem.Expire)
+	}
+}
+
+func registerSettingsRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	adminSettings := admin.Group("/settings")
+	{
+		adminSettings.GET("", h.Admin.Setting.GetSettings)
+		adminSettings.PUT("", h.Admin.Setting.UpdateSettings)
+		adminSettings.POST("/test-smtp", h.Admin.Setting.TestSmtpConnection)
+		adminSettings.POST("/send-test-email", h.Admin.Setting.SendTestEmail)
+		// Admin API Key 管理
+		adminSettings.GET("/admin-api-key", h.Admin.Setting.GetAdminApiKey)
+		adminSettings.POST("/admin-api-key/regenerate", h.Admin.Setting.RegenerateAdminApiKey)
+		adminSettings.DELETE("/admin-api-key", h.Admin.Setting.DeleteAdminApiKey)
+	}
+}
+
+func registerSystemRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	system := admin.Group("/system")
+	{
+		system.GET("/version", h.Admin.System.GetVersion)
+		system.GET("/check-updates", h.Admin.System.CheckUpdates)
+		system.POST("/update", h.Admin.System.PerformUpdate)
+		system.POST("/rollback", h.Admin.System.Rollback)
+		system.POST("/restart", h.Admin.System.RestartService)
+	}
+}
+
+func registerSubscriptionRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	subscriptions := admin.Group("/subscriptions")
+	{
+		subscriptions.GET("", h.Admin.Subscription.List)
+		subscriptions.GET("/:id", h.Admin.Subscription.GetByID)
+		subscriptions.GET("/:id/progress", h.Admin.Subscription.GetProgress)
+		subscriptions.POST("/assign", h.Admin.Subscription.Assign)
+		subscriptions.POST("/bulk-assign", h.Admin.Subscription.BulkAssign)
+		subscriptions.POST("/:id/extend", h.Admin.Subscription.Extend)
+		subscriptions.DELETE("/:id", h.Admin.Subscription.Revoke)
+	}
+
+	// 分组下的订阅列表
+	admin.GET("/groups/:id/subscriptions", h.Admin.Subscription.ListByGroup)
+
+	// 用户下的订阅列表
+	admin.GET("/users/:id/subscriptions", h.Admin.Subscription.ListByUser)
+}
+
+func registerUsageRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	usage := admin.Group("/usage")
+	{
+		usage.GET("", h.Admin.Usage.List)
+		usage.GET("/stats", h.Admin.Usage.Stats)
+		usage.GET("/search-users", h.Admin.Usage.SearchUsers)
+		usage.GET("/search-api-keys", h.Admin.Usage.SearchApiKeys)
+	}
+}

backend/internal/server/routes/auth.go

@@ -0,0 +1,36 @@
+package routes
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/handler"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RegisterAuthRoutes 注册认证相关路由
+func RegisterAuthRoutes(
+	v1 *gin.RouterGroup,
+	h *handler.Handlers,
+	jwtAuth middleware.JWTAuthMiddleware,
+) {
+	// 公开接口
+	auth := v1.Group("/auth")
+	{
+		auth.POST("/register", h.Auth.Register)
+		auth.POST("/login", h.Auth.Login)
+		auth.POST("/send-verify-code", h.Auth.SendVerifyCode)
+	}
+
+	// 公开设置（无需认证）
+	settings := v1.Group("/settings")
+	{
+		settings.GET("/public", h.Setting.GetPublicSettings)
+	}
+
+	// 需要认证的当前用户信息
+	authenticated := v1.Group("")
+	authenticated.Use(gin.HandlerFunc(jwtAuth))
+	{
+		authenticated.GET("/auth/me", h.Auth.GetCurrentUser)
+	}
+}

backend/internal/server/routes/common.go

@@ -0,0 +1,32 @@
+package routes
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RegisterCommonRoutes 注册通用路由（健康检查、状态等）
+func RegisterCommonRoutes(r *gin.Engine) {
+	// 健康检查
+	r.GET("/health", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+
+	// Claude Code 遥测日志（忽略，直接返回200）
+	r.POST("/api/event_logging/batch", func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+
+	// Setup status endpoint (always returns needs_setup: false in normal mode)
+	// This is used by the frontend to detect when the service has restarted after setup
+	r.GET("/setup/status", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{
+			"code": 0,
+			"data": gin.H{
+				"needs_setup": false,
+				"step":        "completed",
+			},
+		})
+	})
+}

backend/internal/server/routes/gateway.go

@@ -0,0 +1,30 @@
+package routes
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/handler"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RegisterGatewayRoutes 注册 API 网关路由（Claude/OpenAI 兼容）
+func RegisterGatewayRoutes(
+	r *gin.Engine,
+	h *handler.Handlers,
+	apiKeyAuth middleware.ApiKeyAuthMiddleware,
+) {
+	// API网关（Claude API兼容）
+	gateway := r.Group("/v1")
+	gateway.Use(gin.HandlerFunc(apiKeyAuth))
+	{
+		gateway.POST("/messages", h.Gateway.Messages)
+		gateway.POST("/messages/count_tokens", h.Gateway.CountTokens)
+		gateway.GET("/models", h.Gateway.Models)
+		gateway.GET("/usage", h.Gateway.Usage)
+		// OpenAI Responses API
+		gateway.POST("/responses", h.OpenAIGateway.Responses)
+	}
+
+	// OpenAI Responses API（不带v1前缀的别名）
+	r.POST("/responses", gin.HandlerFunc(apiKeyAuth), h.OpenAIGateway.Responses)
+}

backend/internal/server/routes/user.go

@@ -0,0 +1,72 @@
+package routes
+
+import (
+	"github.com/Wei-Shaw/sub2api/internal/handler"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RegisterUserRoutes 注册用户相关路由（需要认证）
+func RegisterUserRoutes(
+	v1 *gin.RouterGroup,
+	h *handler.Handlers,
+	jwtAuth middleware.JWTAuthMiddleware,
+) {
+	authenticated := v1.Group("")
+	authenticated.Use(gin.HandlerFunc(jwtAuth))
+	{
+		// 用户接口
+		user := authenticated.Group("/user")
+		{
+			user.GET("/profile", h.User.GetProfile)
+			user.PUT("/password", h.User.ChangePassword)
+			user.PUT("", h.User.UpdateProfile)
+		}
+
+		// API Key管理
+		keys := authenticated.Group("/keys")
+		{
+			keys.GET("", h.APIKey.List)
+			keys.GET("/:id", h.APIKey.GetByID)
+			keys.POST("", h.APIKey.Create)
+			keys.PUT("/:id", h.APIKey.Update)
+			keys.DELETE("/:id", h.APIKey.Delete)
+		}
+
+		// 用户可用分组（非管理员接口）
+		groups := authenticated.Group("/groups")
+		{
+			groups.GET("/available", h.APIKey.GetAvailableGroups)
+		}
+
+		// 使用记录
+		usage := authenticated.Group("/usage")
+		{
+			usage.GET("", h.Usage.List)
+			usage.GET("/:id", h.Usage.GetByID)
+			usage.GET("/stats", h.Usage.Stats)
+			// User dashboard endpoints
+			usage.GET("/dashboard/stats", h.Usage.DashboardStats)
+			usage.GET("/dashboard/trend", h.Usage.DashboardTrend)
+			usage.GET("/dashboard/models", h.Usage.DashboardModels)
+			usage.POST("/dashboard/api-keys-usage", h.Usage.DashboardApiKeysUsage)
+		}
+
+		// 卡密兑换
+		redeem := authenticated.Group("/redeem")
+		{
+			redeem.POST("", h.Redeem.Redeem)
+			redeem.GET("/history", h.Redeem.GetHistory)
+		}
+
+		// 用户订阅
+		subscriptions := authenticated.Group("/subscriptions")
+		{
+			subscriptions.GET("", h.Subscription.List)
+			subscriptions.GET("/active", h.Subscription.GetActive)
+			subscriptions.GET("/progress", h.Subscription.GetProgress)
+			subscriptions.GET("/summary", h.Subscription.GetSummary)
+		}
+	}
+}