chore: 调整403重试次数跟间隔

* refactor: 自定义业务错误

* refactor: 隐藏服务器错误与统一 panic 响应

.github/workflows/backend-ci.yml

@@ -17,9 +17,12 @@ jobs:
           go-version-file: backend/go.mod
           check-latest: true
           cache: true
-      - name: Run tests
+      - name: Unit tests
         working-directory: backend
-        run: go test ./...
+        run: make test-unit
+      - name: Integration tests
+        working-directory: backend
+        run: make test-integration
 
   golangci-lint:
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -85,6 +85,19 @@ jobs:
           go-version: '1.24'
           cache-dependency-path: backend/go.sum
 
+      # Docker setup for GoReleaser
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to DockerHub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
       - name: Fetch tags with annotations
         run: |
           # 确保获取完整的 annotated tag 信息
@@ -117,87 +130,16 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           TAG_MESSAGE: ${{ steps.tag_message.outputs.message }}
+          GITHUB_REPO_OWNER: ${{ github.repository_owner }}
+          GITHUB_REPO_NAME: ${{ github.event.repository.name }}
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
 
-  # ===========================================================================
-  # Docker Build and Push
-  # ===========================================================================
-  docker:
-    needs: [update-version, build-frontend]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Download VERSION artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: version-file
-          path: backend/cmd/server/
-
-      - name: Download frontend artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: frontend-dist
-          path: backend/internal/web/dist/
-
-      # Extract version from tag
-      - name: Extract version
-        id: version
-        run: |
-          VERSION=${GITHUB_REF#refs/tags/v}
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          echo "Version: $VERSION"
-
-      # Set up Docker Buildx for multi-platform builds
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      # Login to DockerHub
-      - name: Login to DockerHub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      # Extract metadata for Docker
-      - name: Extract Docker metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: |
-            weishaw/sub2api
-          tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}
-            type=raw,value=latest,enable={{is_default_branch}}
-
-      # Build and push Docker image
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          file: ./Dockerfile
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          build-args: |
-            VERSION=${{ steps.version.outputs.version }}
-            COMMIT=${{ github.sha }}
-            DATE=${{ github.event.head_commit.timestamp }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-      # Update DockerHub description (optional)
+      # Update DockerHub description
       - name: Update DockerHub description
         uses: peter-evans/dockerhub-description@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
-          repository: weishaw/sub2api
+          repository: ${{ secrets.DOCKERHUB_USERNAME }}/sub2api
           short-description: "Sub2API - AI API Gateway Platform"
           readme-filepath: ./deploy/DOCKER.md

.gitignore

@@ -28,6 +28,7 @@ node_modules/
 frontend/node_modules/
 frontend/dist/
 *.local
+*.tsbuildinfo
 
 # 日志
 npm-debug.log*
@@ -91,6 +92,13 @@ backend/internal/web/dist/*
 # 后端运行时缓存数据
 backend/data/
 
+# ===================
+# 本地配置文件（包含敏感信息）
+# ===================
+backend/config.yaml
+deploy/config.yaml
+backend/.installed
+
 # ===================
 # 其他
 # ===================

.goreleaser.yaml

@@ -52,10 +52,58 @@ changelog:
   # 禁用自动 changelog，完全使用 tag 消息
   disable: true
 
+# Docker images
+dockers:
+  - id: amd64
+    goos: linux
+    goarch: amd64
+    image_templates:
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-amd64"
+    dockerfile: Dockerfile.goreleaser
+    use: buildx
+    build_flag_templates:
+      - "--platform=linux/amd64"
+      - "--label=org.opencontainers.image.version={{ .Version }}"
+      - "--label=org.opencontainers.image.revision={{ .Commit }}"
+
+  - id: arm64
+    goos: linux
+    goarch: arm64
+    image_templates:
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-arm64"
+    dockerfile: Dockerfile.goreleaser
+    use: buildx
+    build_flag_templates:
+      - "--platform=linux/arm64"
+      - "--label=org.opencontainers.image.version={{ .Version }}"
+      - "--label=org.opencontainers.image.revision={{ .Commit }}"
+
+# Docker manifests for multi-arch support
+docker_manifests:
+  - name_template: "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}"
+    image_templates:
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-amd64"
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-arm64"
+
+  - name_template: "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:latest"
+    image_templates:
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-amd64"
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-arm64"
+
+  - name_template: "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Major }}.{{ .Minor }}"
+    image_templates:
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-amd64"
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-arm64"
+
+  - name_template: "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Major }}"
+    image_templates:
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-amd64"
+      - "{{ .Env.DOCKERHUB_USERNAME }}/sub2api:{{ .Version }}-arm64"
+
 release:
   github:
-    owner: Wei-Shaw
-    name: sub2api
+    owner: "{{ .Env.GITHUB_REPO_OWNER }}"
+    name: "{{ .Env.GITHUB_REPO_NAME }}"
   draft: false
   prerelease: auto
   name_template: "Sub2API {{.Version}}"
@@ -73,7 +121,7 @@ release:
 
     **One-line install (Linux):**
     ```bash
-    curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash
+    curl -sSL https://raw.githubusercontent.com/{{ .Env.GITHUB_REPO_OWNER }}/{{ .Env.GITHUB_REPO_NAME }}/main/deploy/install.sh | sudo bash
     ```
 
     **Manual download:**
@@ -81,5 +129,5 @@ release:
 
     ## 📚 Documentation
 
-    - [GitHub Repository](https://github.com/Wei-Shaw/sub2api)
-    - [Installation Guide](https://github.com/Wei-Shaw/sub2api/blob/main/deploy/README.md)
+    - [GitHub Repository](https://github.com/{{ .Env.GITHUB_REPO_OWNER }}/{{ .Env.GITHUB_REPO_NAME }})
+    - [Installation Guide](https://github.com/{{ .Env.GITHUB_REPO_OWNER }}/{{ .Env.GITHUB_REPO_NAME }}/blob/main/deploy/README.md)

Dockerfile.goreleaser

@@ -0,0 +1,40 @@
+# =============================================================================
+# Sub2API Dockerfile for GoReleaser
+# =============================================================================
+# This Dockerfile is used by GoReleaser to build Docker images.
+# It only packages the pre-built binary, no compilation needed.
+# =============================================================================
+
+FROM alpine:3.19
+
+LABEL maintainer="Wei-Shaw <github.com/Wei-Shaw>"
+LABEL description="Sub2API - AI API Gateway Platform"
+LABEL org.opencontainers.image.source="https://github.com/Wei-Shaw/sub2api"
+
+# Install runtime dependencies
+RUN apk add --no-cache \
+    ca-certificates \
+    tzdata \
+    curl \
+    && rm -rf /var/cache/apk/*
+
+# Create non-root user
+RUN addgroup -g 1000 sub2api && \
+    adduser -u 1000 -G sub2api -s /bin/sh -D sub2api
+
+WORKDIR /app
+
+# Copy pre-built binary from GoReleaser
+COPY sub2api /app/sub2api
+
+# Create data directory
+RUN mkdir -p /app/data && chown -R sub2api:sub2api /app
+
+USER sub2api
+
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:${SERVER_PORT:-8080}/health || exit 1
+
+ENTRYPOINT ["/app/sub2api"]

backend/.golangci.yml

@@ -17,10 +17,19 @@ linters:
         service-no-repository:
           list-mode: original
           files:
-            - internal/service/**
+            - "**/internal/service/**"
           deny:
-            - pkg: sub2api/internal/repository
+            - pkg: github.com/Wei-Shaw/sub2api/internal/repository
               desc: "service must not import repository"
+            - pkg: gorm.io/gorm
+              desc: "service must not import gorm"
+        handler-no-repository:
+          list-mode: original
+          files:
+            - "**/internal/handler/**"
+          deny:
+            - pkg: github.com/Wei-Shaw/sub2api/internal/repository
+              desc: "handler must not import repository"
     errcheck:
       # Report about not checking of errors in type assertions: `a := b.(MyStruct)`.
       # Such cases aren't reported by default.

backend/Makefile

@@ -1,4 +1,4 @@
-.PHONY: wire build build-embed
+.PHONY: wire build build-embed test-unit test-integration test-cover-integration clean-coverage
 
 wire:
 	@echo "生成 Wire 代码..."
@@ -13,4 +13,21 @@ build:
 build-embed:
 	@echo "构建后端（嵌入前端）..."
 	@go build -tags embed -o bin/server ./cmd/server
-	@echo "构建完成: bin/server (with embedded frontend)"
+	@echo "构建完成: bin/server (with embedded frontend)"
+
+test-unit:
+	@go test -tags unit ./... -count=1
+
+test-integration:
+	@go test -tags integration ./... -count=1 -race -parallel=8
+
+test-cover-integration:
+	@echo "运行集成测试并生成覆盖率报告..."
+	@go test -tags=integration -cover -coverprofile=coverage.out -count=1 -race -parallel=8 ./...
+	@go tool cover -func=coverage.out | tail -1
+	@go tool cover -html=coverage.out -o coverage.html
+	@echo "覆盖率报告已生成: coverage.html"
+
+clean-coverage:
+	@rm -f coverage.out coverage.html
+	@echo "覆盖率文件已清理"

backend/cmd/server/main.go

@@ -15,11 +15,11 @@ import (
 	"syscall"
 	"time"
 
-	"sub2api/internal/config"
-	"sub2api/internal/handler"
-	"sub2api/internal/middleware"
-	"sub2api/internal/setup"
-	"sub2api/internal/web"
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/handler"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/setup"
+	"github.com/Wei-Shaw/sub2api/internal/web"
 
 	"github.com/gin-gonic/gin"
 )
@@ -84,7 +84,7 @@ func main() {
 
 func runSetupServer() {
 	r := gin.New()
-	r.Use(gin.Recovery())
+	r.Use(middleware.Recovery())
 	r.Use(middleware.CORS())
 
 	// Register setup routes

backend/cmd/server/wire.go

@@ -4,18 +4,19 @@
 package main
 
 import (
-	"sub2api/internal/config"
-	"sub2api/internal/handler"
-	"sub2api/internal/infrastructure"
-	"sub2api/internal/repository"
-	"sub2api/internal/server"
-	"sub2api/internal/service"
-
 	"context"
 	"log"
 	"net/http"
 	"time"
 
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/handler"
+	"github.com/Wei-Shaw/sub2api/internal/infrastructure"
+	"github.com/Wei-Shaw/sub2api/internal/repository"
+	"github.com/Wei-Shaw/sub2api/internal/server"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
 	"github.com/google/wire"
 	"github.com/redis/go-redis/v9"
 	"gorm.io/gorm"
@@ -35,6 +36,7 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 		// 业务层 ProviderSets
 		repository.ProviderSet,
 		service.ProviderSet,
+		middleware.ProviderSet,
 		handler.ProviderSet,
 
 		// 服务器层 ProviderSet
@@ -62,7 +64,11 @@ func provideServiceBuildInfo(buildInfo handler.BuildInfo) service.BuildInfo {
 func provideCleanup(
 	db *gorm.DB,
 	rdb *redis.Client,
-	services *service.Services,
+	tokenRefresh *service.TokenRefreshService,
+	pricing *service.PricingService,
+	emailQueue *service.EmailQueueService,
+	oauth *service.OAuthService,
+	openaiOAuth *service.OpenAIOAuthService,
 ) func() {
 	return func() {
 		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
@@ -74,23 +80,23 @@ func provideCleanup(
 			fn   func() error
 		}{
 			{"TokenRefreshService", func() error {
-				services.TokenRefresh.Stop()
+				tokenRefresh.Stop()
 				return nil
 			}},
 			{"PricingService", func() error {
-				services.Pricing.Stop()
+				pricing.Stop()
 				return nil
 			}},
 			{"EmailQueueService", func() error {
-				services.EmailQueue.Stop()
+				emailQueue.Stop()
 				return nil
 			}},
 			{"OAuthService", func() error {
-				services.OAuth.Stop()
+				oauth.Stop()
 				return nil
 			}},
 			{"OpenAIOAuthService", func() error {
-				services.OpenAIOAuth.Stop()
+				openaiOAuth.Stop()
 				return nil
 			}},
 			{"Redis", func() error {

backend/cmd/server/wire_gen.go

@@ -8,17 +8,18 @@ package main
 
 import (
 	"context"
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/handler"
+	"github.com/Wei-Shaw/sub2api/internal/handler/admin"
+	"github.com/Wei-Shaw/sub2api/internal/infrastructure"
+	"github.com/Wei-Shaw/sub2api/internal/repository"
+	"github.com/Wei-Shaw/sub2api/internal/server"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 	"gorm.io/gorm"
 	"log"
 	"net/http"
-	"sub2api/internal/config"
-	"sub2api/internal/handler"
-	"sub2api/internal/handler/admin"
-	"sub2api/internal/infrastructure"
-	"sub2api/internal/repository"
-	"sub2api/internal/server"
-	"sub2api/internal/service"
 	"time"
 )
 
@@ -58,7 +59,7 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	apiKeyHandler := handler.NewAPIKeyHandler(apiKeyService)
 	usageLogRepository := repository.NewUsageLogRepository(db)
 	usageService := service.NewUsageService(usageLogRepository, userRepository)
-	usageHandler := handler.NewUsageHandler(usageService, usageLogRepository, apiKeyService)
+	usageHandler := handler.NewUsageHandler(usageService, apiKeyService)
 	redeemCodeRepository := repository.NewRedeemCodeRepository(db)
 	billingCache := repository.NewBillingCache(client)
 	billingCacheService := service.NewBillingCacheService(billingCache, userRepository, userSubscriptionRepository)
@@ -67,7 +68,8 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	redeemService := service.NewRedeemService(redeemCodeRepository, userRepository, subscriptionService, redeemCache, billingCacheService)
 	redeemHandler := handler.NewRedeemHandler(redeemService)
 	subscriptionHandler := handler.NewSubscriptionHandler(subscriptionService)
-	dashboardHandler := admin.NewDashboardHandler(usageLogRepository)
+	dashboardService := service.NewDashboardService(usageLogRepository)
+	dashboardHandler := admin.NewDashboardHandler(dashboardService)
 	accountRepository := repository.NewAccountRepository(db)
 	proxyRepository := repository.NewProxyRepository(db)
 	proxyExitInfoProber := repository.NewProxyExitInfoProber()
@@ -83,7 +85,10 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	accountUsageService := service.NewAccountUsageService(accountRepository, usageLogRepository, claudeUsageFetcher)
 	httpUpstream := repository.NewHTTPUpstream(configConfig)
 	accountTestService := service.NewAccountTestService(accountRepository, oAuthService, openAIOAuthService, httpUpstream)
-	accountHandler := admin.NewAccountHandler(adminService, oAuthService, openAIOAuthService, rateLimitService, accountUsageService, accountTestService, usageLogRepository)
+	concurrencyCache := repository.NewConcurrencyCache(client)
+	concurrencyService := service.NewConcurrencyService(concurrencyCache)
+	crsSyncService := service.NewCRSSyncService(accountRepository, proxyRepository, oAuthService, openAIOAuthService)
+	accountHandler := admin.NewAccountHandler(adminService, oAuthService, openAIOAuthService, rateLimitService, accountUsageService, accountTestService, concurrencyService, crsSyncService)
 	oAuthHandler := admin.NewOAuthHandler(oAuthService)
 	openAIOAuthHandler := admin.NewOpenAIOAuthHandler(openAIOAuthService, adminService)
 	proxyHandler := admin.NewProxyHandler(adminService)
@@ -95,7 +100,7 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	updateService := service.ProvideUpdateService(updateCache, gitHubReleaseClient, serviceBuildInfo)
 	systemHandler := handler.ProvideSystemHandler(updateService)
 	adminSubscriptionHandler := admin.NewSubscriptionHandler(subscriptionService)
-	adminUsageHandler := admin.NewUsageHandler(usageLogRepository, apiKeyRepository, usageService, adminService)
+	adminUsageHandler := admin.NewUsageHandler(usageService, apiKeyService, adminService)
 	adminHandlers := handler.ProvideAdminHandlers(dashboardHandler, adminUserHandler, groupHandler, accountHandler, oAuthHandler, openAIOAuthHandler, proxyHandler, adminRedeemHandler, settingHandler, systemHandler, adminSubscriptionHandler, adminUsageHandler)
 	gatewayCache := repository.NewGatewayCache(client)
 	pricingRemoteClient := repository.NewPricingRemoteClient()
@@ -107,61 +112,18 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	identityCache := repository.NewIdentityCache(client)
 	identityService := service.NewIdentityService(identityCache)
 	gatewayService := service.NewGatewayService(accountRepository, usageLogRepository, userRepository, userSubscriptionRepository, gatewayCache, configConfig, billingService, rateLimitService, billingCacheService, identityService, httpUpstream)
-	concurrencyCache := repository.NewConcurrencyCache(client)
-	concurrencyService := service.NewConcurrencyService(concurrencyCache)
 	gatewayHandler := handler.NewGatewayHandler(gatewayService, userService, concurrencyService, billingCacheService)
 	openAIGatewayService := service.NewOpenAIGatewayService(accountRepository, usageLogRepository, userRepository, userSubscriptionRepository, gatewayCache, configConfig, billingService, rateLimitService, billingCacheService, httpUpstream)
 	openAIGatewayHandler := handler.NewOpenAIGatewayHandler(openAIGatewayService, concurrencyService, billingCacheService)
 	handlerSettingHandler := handler.ProvideSettingHandler(settingService, buildInfo)
 	handlers := handler.ProvideHandlers(authHandler, userHandler, apiKeyHandler, usageHandler, redeemHandler, subscriptionHandler, adminHandlers, gatewayHandler, openAIGatewayHandler, handlerSettingHandler)
-	groupService := service.NewGroupService(groupRepository)
-	accountService := service.NewAccountService(accountRepository, groupRepository)
-	proxyService := service.NewProxyService(proxyRepository)
-	tokenRefreshService := service.ProvideTokenRefreshService(accountRepository, oAuthService, openAIOAuthService, configConfig)
-	services := &service.Services{
-		Auth:          authService,
-		User:          userService,
-		ApiKey:        apiKeyService,
-		Group:         groupService,
-		Account:       accountService,
-		Proxy:         proxyService,
-		Redeem:        redeemService,
-		Usage:         usageService,
-		Pricing:       pricingService,
-		Billing:       billingService,
-		BillingCache:  billingCacheService,
-		Admin:         adminService,
-		Gateway:       gatewayService,
-		OpenAIGateway: openAIGatewayService,
-		OAuth:         oAuthService,
-		OpenAIOAuth:   openAIOAuthService,
-		RateLimit:     rateLimitService,
-		AccountUsage:  accountUsageService,
-		AccountTest:   accountTestService,
-		Setting:       settingService,
-		Email:         emailService,
-		EmailQueue:    emailQueueService,
-		Turnstile:     turnstileService,
-		Subscription:  subscriptionService,
-		Concurrency:   concurrencyService,
-		Identity:      identityService,
-		Update:        updateService,
-		TokenRefresh:  tokenRefreshService,
-	}
-	repositories := &repository.Repositories{
-		User:             userRepository,
-		ApiKey:           apiKeyRepository,
-		Group:            groupRepository,
-		Account:          accountRepository,
-		Proxy:            proxyRepository,
-		RedeemCode:       redeemCodeRepository,
-		UsageLog:         usageLogRepository,
-		Setting:          settingRepository,
-		UserSubscription: userSubscriptionRepository,
-	}
-	engine := server.ProvideRouter(configConfig, handlers, services, repositories)
+	jwtAuthMiddleware := middleware.NewJWTAuthMiddleware(authService, userService)
+	adminAuthMiddleware := middleware.NewAdminAuthMiddleware(authService, userService, settingService)
+	apiKeyAuthMiddleware := middleware.NewApiKeyAuthMiddleware(apiKeyService, subscriptionService)
+	engine := server.ProvideRouter(configConfig, handlers, jwtAuthMiddleware, adminAuthMiddleware, apiKeyAuthMiddleware)
 	httpServer := server.ProvideHTTPServer(configConfig, engine)
-	v := provideCleanup(db, client, services)
+	tokenRefreshService := service.ProvideTokenRefreshService(accountRepository, oAuthService, openAIOAuthService, configConfig)
+	v := provideCleanup(db, client, tokenRefreshService, pricingService, emailQueueService, oAuthService, openAIOAuthService)
 	application := &Application{
 		Server:  httpServer,
 		Cleanup: v,
@@ -186,7 +148,11 @@ func provideServiceBuildInfo(buildInfo handler.BuildInfo) service.BuildInfo {
 func provideCleanup(
 	db *gorm.DB,
 	rdb *redis.Client,
-	services *service.Services,
+	tokenRefresh *service.TokenRefreshService,
+	pricing *service.PricingService,
+	emailQueue *service.EmailQueueService,
+	oauth *service.OAuthService,
+	openaiOAuth *service.OpenAIOAuthService,
 ) func() {
 	return func() {
 		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
@@ -197,23 +163,23 @@ func provideCleanup(
 			fn   func() error
 		}{
 			{"TokenRefreshService", func() error {
-				services.TokenRefresh.Stop()
+				tokenRefresh.Stop()
 				return nil
 			}},
 			{"PricingService", func() error {
-				services.Pricing.Stop()
+				pricing.Stop()
 				return nil
 			}},
 			{"EmailQueueService", func() error {
-				services.EmailQueue.Stop()
+				emailQueue.Stop()
 				return nil
 			}},
 			{"OAuthService", func() error {
-				services.OAuth.Stop()
+				oauth.Stop()
 				return nil
 			}},
 			{"OpenAIOAuthService", func() error {
-				services.OpenAIOAuth.Stop()
+				openaiOAuth.Stop()
 				return nil
 			}},
 			{"Redis", func() error {

backend/config.yaml

@@ -1,38 +0,0 @@
-server:
-  host: "0.0.0.0"
-  port: 8080
-  mode: "debug"  # debug/release
-
-database:
-  host: "127.0.0.1"
-  port: 5432
-  user: "postgres"
-  password: "XZeRr7nkjHWhm8fw"
-  dbname: "sub2api"
-  sslmode: "disable"
-
-redis:
-  host: "127.0.0.1"
-  port: 6379
-  password: ""
-  db: 0
-
-jwt:
-  secret: "your-secret-key-change-in-production"
-  expire_hour: 24
-
-default:
-  admin_email: "admin@sub2api.com"
-  admin_password: "admin123"
-  user_concurrency: 5
-  user_balance: 0
-  api_key_prefix: "sk-"
-  rate_multiplier: 1.0
-
-# Timezone configuration (similar to PHP's date_default_timezone_set)
-# This affects ALL time operations:
-# - Database timestamps
-# - Usage statistics "today" boundary
-# - Subscription expiry times
-# Common values: Asia/Shanghai, America/New_York, Europe/London, UTC
-timezone: "Asia/Shanghai"

backend/go.mod

@@ -1,4 +1,4 @@
-module sub2api
+module github.com/Wei-Shaw/sub2api
 
 go 1.24.0
 
@@ -8,10 +8,16 @@ require (
 	github.com/gin-gonic/gin v1.9.1
 	github.com/golang-jwt/jwt/v5 v5.2.0
 	github.com/google/uuid v1.6.0
+	github.com/google/wire v0.7.0
 	github.com/imroc/req/v3 v3.56.0
 	github.com/lib/pq v1.10.9
-	github.com/redis/go-redis/v9 v9.3.0
+	github.com/redis/go-redis/v9 v9.7.3
 	github.com/spf13/viper v1.18.2
+	github.com/stretchr/testify v1.11.1
+	github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0
+	github.com/testcontainers/testcontainers-go/modules/redis v0.40.0
+	github.com/tidwall/gjson v1.18.0
+	github.com/tidwall/sjson v1.2.5
 	golang.org/x/crypto v0.44.0
 	golang.org/x/net v0.47.0
 	golang.org/x/term v0.37.0
@@ -21,51 +27,99 @@ require (
 )
 
 require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/andybalholm/brotli v1.2.0 // indirect
 	github.com/bytedance/sonic v1.9.1 // indirect
-	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	github.com/cpuguy83/dockercfg v0.3.2 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/docker v28.5.1+incompatible // indirect
+	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/ebitengine/purego v0.8.4 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.2 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.14.0 // indirect
 	github.com/goccy/go-json v0.10.2 // indirect
 	github.com/google/go-querystring v1.1.0 // indirect
 	github.com/google/subcommands v1.2.0 // indirect
-	github.com/google/wire v0.7.0 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
 	github.com/icholy/digest v1.1.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect
-	github.com/jackc/pgx/v5 v5.4.3 // indirect
+	github.com/jackc/pgx/v5 v5.5.4 // indirect
+	github.com/jackc/puddle/v2 v2.2.1 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.18.1 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.4 // indirect
 	github.com/leodido/go-urn v1.2.4 // indirect
-	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mattn/go-isatty v0.0.19 // indirect
+	github.com/mdelapenya/tlscert v0.2.0 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/go-archive v0.1.0 // indirect
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/user v0.4.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/pelletier/go-toml/v2 v2.1.0 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
 	github.com/quic-go/qpack v0.5.1 // indirect
 	github.com/quic-go/quic-go v0.56.0 // indirect
 	github.com/refraction-networking/utls v1.8.1 // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
+	github.com/shirou/gopsutil/v4 v4.25.6 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
 	github.com/spf13/afero v1.11.0 // indirect
 	github.com/spf13/cast v1.6.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
+	github.com/testcontainers/testcontainers-go v0.40.0 // indirect
+	github.com/tidwall/match v1.1.1 // indirect
+	github.com/tidwall/pretty v1.2.0 // indirect
+	github.com/tklauser/go-sysconf v0.3.12 // indirect
+	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.11 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect
+	go.opentelemetry.io/otel v1.37.0 // indirect
+	go.opentelemetry.io/otel/metric v1.37.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.37.0 // indirect
+	go.opentelemetry.io/otel/trace v1.37.0 // indirect
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
 	golang.org/x/arch v0.3.0 // indirect
@@ -75,6 +129,7 @@ require (
 	golang.org/x/sys v0.38.0 // indirect
 	golang.org/x/text v0.31.0 // indirect
 	golang.org/x/tools v0.38.0 // indirect
-	google.golang.org/protobuf v1.31.0 // indirect
+	google.golang.org/grpc v1.75.1 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 )

backend/go.sum

@@ -1,3 +1,11 @@
+dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
+dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8=
+github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 h1:UQHMgLO+TxOElx5B5HZ4hJQsoJ/PvUvKRhJHDQXO8P8=
+github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
 github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
 github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
@@ -7,17 +15,43 @@ github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0
 github.com/bytedance/sonic v1.5.0/go.mod h1:ED5hyg4y6t3/9Ku1R6dU/4KyJ48DZ4jPhfY1O2AihPM=
 github.com/bytedance/sonic v1.9.1 h1:6iJ6NqdoxCDr6mbY8h18oSO+cShGSMRGCEo7F2h0x8s=
 github.com/bytedance/sonic v1.9.1/go.mod h1:i736AoUSYt75HyZLoJW9ERYxcy6eaN6h4BZXU064P/U=
-github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
-github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/chenzhuoyu/base64x v0.0.0-20211019084208-fb5309c8db06/go.mod h1:DH46F32mSOjUmXrMHnKwZdA8wcEefY7UVqBKYGjpdQY=
 github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 h1:qSGYFH7+jGhDF8vLC+iwCD4WpbV1EBDSzWkJODFLams=
 github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311/go.mod h1:b583jCggY9gE99b6G5LEC39OIiVsWj+R97kbl5odCEk=
+github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
+github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
+github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
+github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk=
+github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
+github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
+github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
+github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
+github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
+github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
+github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY=
+github.com/creack/pty v1.1.18/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
+github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/docker v28.5.1+incompatible h1:Bm8DchhSD2J6PsFzxC35TZo4TLGR2PdW/E69rU45NhM=
+github.com/docker/docker v28.5.1+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
+github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
+github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
+github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
+github.com/ebitengine/purego v0.8.4 h1:CF7LEKg5FFOsASUj0+QwaXf8Ht6TlFxg09+S9wz0omw=
+github.com/ebitengine/purego v0.8.4/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
@@ -28,6 +62,13 @@ github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE
 github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
 github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
 github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
+github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
@@ -40,9 +81,8 @@ github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
 github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
 github.com/golang-jwt/jwt/v5 v5.2.0 h1:d/ix8ftRUorsN+5eMIlF4T6J8CAt9rch3My2winC1Jw=
 github.com/golang-jwt/jwt/v5 v5.2.0/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
-github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
 github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8=
@@ -54,6 +94,8 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/wire v0.7.0 h1:JxUKI6+CVBgCO2WToKy/nQk0sS+amI9z9EjVmdaocj4=
 github.com/google/wire v0.7.0/go.mod h1:n6YbUQD9cPKTnHXEBN2DXlOp/mVADhVErcMFb0v3J18=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 h1:NmZ1PKzSTQbuGHw9DGPFomqkkLWMC+vZCkfs+FHv1Vg=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3/go.mod h1:zQrxl1YP88HQlA6i9c63DSVPFklWpGX4OWAc9bFuaH4=
 github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
 github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
 github.com/icholy/digest v1.1.0 h1:HfGg9Irj7i+IX1o1QAmPfIBNu/Q5A5Tu3n/MED9k9H4=
@@ -64,8 +106,10 @@ github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsI
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a h1:bbPeKD0xmW/Y25WS6cokEszi5g+S0QxI/d45PkRi7Nk=
 github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
-github.com/jackc/pgx/v5 v5.4.3 h1:cxFyXhxlvAifxnkKKdlxv8XqUf59tDlYjnV5YYfsJJY=
-github.com/jackc/pgx/v5 v5.4.3/go.mod h1:Ig06C2Vu0t5qXC60W8sqIthScaEnFvojjj9dSljmHRA=
+github.com/jackc/pgx/v5 v5.5.4 h1:Xp2aQS8uXButQdnCMWNmvx6UysWQQC+u1EoizjguY+8=
+github.com/jackc/pgx/v5 v5.5.4/go.mod h1:ez9gk+OAat140fv9ErkZDYFWmXLfV+++K0uAOiwgm1A=
+github.com/jackc/puddle/v2 v2.2.1 h1:RhxXJtFG022u4ibrCSMSiu5aOq1i77R3OHKNJj77OAk=
+github.com/jackc/puddle/v2 v2.2.1/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
 github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
 github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
@@ -85,36 +129,70 @@ github.com/leodido/go-urn v1.2.4 h1:XlAE/cm/ms7TE/VMVoduSpNBoyc2dOxHs5MZSwAN63Q=
 github.com/leodido/go-urn v1.2.4/go.mod h1:7ZrI8mTSeBSHl/UaRyKQW1qZeMgak41ANeCNaVckg+4=
 github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
 github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
-github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
-github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
+github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
+github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mattn/go-isatty v0.0.19 h1:JITubQf0MOLdlGRuRq+jtsDlekdYPia9ZFsB8h/APPA=
 github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mdelapenya/tlscert v0.2.0 h1:7H81W6Z/4weDvZBNOfQte5GpIMo0lGYEeWbkGp5LJHI=
+github.com/mdelapenya/tlscert v0.2.0/go.mod h1:O4njj3ELLnJjGdkN7M/vIVCpZ+Cf0L6muqOG4tLSl8o=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
+github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
+github.com/moby/go-archive v0.1.0 h1:Kk/5rdW/g+H8NHdJW2gsXyZ7UnzvJNOy6VKJqueWdcQ=
+github.com/moby/go-archive v0.1.0/go.mod h1:G9B+YoujNohJmrIYFBpSd54GTUB4lt9S+xVQvsJyFuo=
+github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
+github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
+github.com/moby/sys/atomicwriter v0.1.0 h1:kw5D/EqkBwsBFi0ss9v1VG3wIkVhzGvLklJ+w3A14Sw=
+github.com/moby/sys/atomicwriter v0.1.0/go.mod h1:Ul8oqv2ZMNHOceF643P6FKPXeCmYtlQMvpizfsSoaWs=
+github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
+github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
+github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
+github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
+github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
+github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
+github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
+github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
+github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
+github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
 github.com/pelletier/go-toml/v2 v2.1.0 h1:FnwAJ4oYMvbT/34k9zzHuZNrhlz48GB3/s6at6/MHO4=
 github.com/pelletier/go-toml/v2 v2.1.0/go.mod h1:tJU2Z3ZkXwnxa4DPO899bsyIoywizdUvyaeZurnPPDc=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF4JjgDlrVEn3C11VoGHZN7m8qihwgMEtzYw=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/quic-go/qpack v0.5.1 h1:giqksBPnT/HDtZ6VhtFKgoLOWmlyo9Ei6u9PqzIMbhI=
 github.com/quic-go/qpack v0.5.1/go.mod h1:+PC4XFrEskIVkcLzpEkbLqq1uCoxPhQuvK5rH1ZgaEg=
 github.com/quic-go/quic-go v0.56.0 h1:q/TW+OLismmXAehgFLczhCDTYB3bFmua4D9lsNBWxvY=
 github.com/quic-go/quic-go v0.56.0/go.mod h1:9gx5KsFQtw2oZ6GZTyh+7YEvOxWCL9WZAepnHxgAo6c=
-github.com/redis/go-redis/v9 v9.3.0 h1:RiVDjmig62jIWp7Kk4XVLs0hzV6pI3PyTnnL0cnn0u0=
-github.com/redis/go-redis/v9 v9.3.0/go.mod h1:hdY0cQFCN4fnSYT6TkisLufl/4W5UIXyv0b/CLO2V2M=
+github.com/redis/go-redis/v9 v9.7.3 h1:YpPyAayJV+XErNsatSElgRZZVCwXX9QzkKYNvO7x0wM=
+github.com/redis/go-redis/v9 v9.7.3/go.mod h1:bGUrSggJ9X9GUmZpZNEOQKaANxSGgOEBRltRTZHSvrA=
 github.com/refraction-networking/utls v1.8.1 h1:yNY1kapmQU8JeM1sSw2H2asfTIwWxIkrMJI0pRUOCAo=
 github.com/refraction-networking/utls v1.8.1/go.mod h1:jkSOEkLqn+S/jtpEHPOsVv/4V4EVnelwbMQl4vCWXAM=
-github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
-github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
+github.com/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=
+github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=
 github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6keLGt6kNQ=
 github.com/sagikazarmark/locafero v0.4.0/go.mod h1:Pe1W6UlPYUk/+wc/6KFhbORCfqzgYEpgQ3O5fPuL3H4=
 github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
 github.com/sagikazarmark/slog-shim v0.1.0/go.mod h1:SrcSrq8aKtyuqEI1uvTDTK1arOWRIczQRv+GVI1AkeQ=
+github.com/shirou/gopsutil/v4 v4.25.6 h1:kLysI2JsKorfaFPcYmcJqbzROzsBWEOAtw6A7dIfqXs=
+github.com/shirou/gopsutil/v4 v4.25.6/go.mod h1:PfybzyydfZcN+JMMjkF6Zb8Mq1A/VcogFFg7hj50W9c=
+github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
+github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
 github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo=
 github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0=
 github.com/spf13/afero v1.11.0 h1:WJQKhtpdm3v2IzqG8VMqrr6Rf3UYpEF239Jy9wNepM8=
@@ -128,6 +206,8 @@ github.com/spf13/viper v1.18.2/go.mod h1:EKmWIqdnk5lOcmR72yw6hS+8OPYcwD0jteitLMV
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
@@ -135,16 +215,55 @@ github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
-github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
+github.com/testcontainers/testcontainers-go v0.40.0 h1:pSdJYLOVgLE8YdUY2FHQ1Fxu+aMnb6JfVz1mxk7OeMU=
+github.com/testcontainers/testcontainers-go v0.40.0/go.mod h1:FSXV5KQtX2HAMlm7U3APNyLkkap35zNLxukw9oBi/MY=
+github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0 h1:s2bIayFXlbDFexo96y+htn7FzuhpXLYJNnIuglNKqOk=
+github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0/go.mod h1:h+u/2KoREGTnTl9UwrQ/g+XhasAT8E6dClclAADeXoQ=
+github.com/testcontainers/testcontainers-go/modules/redis v0.40.0 h1:OG4qwcxp2O0re7V7M9lY9w0v6wWgWf7j7rtkpAnGMd0=
+github.com/testcontainers/testcontainers-go/modules/redis v0.40.0/go.mod h1:Bc+EDhKMo5zI5V5zdBkHiMVzeAXbtI4n5isS/nzf6zw=
+github.com/tidwall/gjson v1.14.2/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
+github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.0 h1:RWIZEg2iJ8/g6fDDYzMpobmaoGh5OLl4AXtGUGPcqCs=
+github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
+github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
+github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFAEVmqU=
+github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
+github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk=
+github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.11 h1:BMaWp1Bb6fHwEtbplGBGJ498wD+LKlNSl25MjdZY4dU=
 github.com/ugorji/go/codec v1.2.11/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
+github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
+go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 h1:jq9TW8u3so/bN+JPT166wjOI6/vQPF6Xe7nMNIltagk=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0/go.mod h1:p8pYQP+m5XfbZm9fxtSKAbM6oIllS7s2AfxrChvc7iw=
+go.opentelemetry.io/otel v1.37.0 h1:9zhNfelUvx0KBfu/gb+ZgeAfAgtWrfHJZcAqFC228wQ=
+go.opentelemetry.io/otel v1.37.0/go.mod h1:ehE/umFRLnuLa/vSccNq9oS1ErUlkkK71gMcN34UG8I=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.19.0 h1:Mne5On7VWdx7omSrSSZvM4Kw7cS7NQkOOmLcgscI51U=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.19.0/go.mod h1:IPtUMKL4O3tH5y+iXVyAXqpAwMuzC1IrxVS81rummfE=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0 h1:IeMeyr1aBvBiPVYihXIaeIZba6b8E1bYp7lbdxK8CQg=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0/go.mod h1:oVdCUtjq9MK9BlS7TtucsQwUcXcymNiEDjgDD2jMtZU=
+go.opentelemetry.io/otel/metric v1.37.0 h1:mvwbQS5m0tbmqML4NqK+e3aDiO02vsf/WgbsdpcPoZE=
+go.opentelemetry.io/otel/metric v1.37.0/go.mod h1:04wGrZurHYKOc+RKeye86GwKiTb9FKm1WHtO+4EVr2E=
+go.opentelemetry.io/otel/sdk v1.37.0 h1:ItB0QUqnjesGRvNcmAcU0LyvkVyGJ2xftD29bWdDvKI=
+go.opentelemetry.io/otel/sdk v1.37.0/go.mod h1:VredYzxUvuo2q3WRcDnKDjbdvmO0sCzOvVAiY+yUkAg=
+go.opentelemetry.io/otel/trace v1.37.0 h1:HLdcFNbRQBE2imdSEgm/kwqmQj1Or1l/7bW6mxVK7z4=
+go.opentelemetry.io/otel/trace v1.37.0/go.mod h1:TlgrlQ+PtQO5XFerSPUYG0JSgGyryXewPGyayAWSBS0=
+go.opentelemetry.io/proto/otlp v1.0.0 h1:T0TX0tmXU8a3CbNXzEKGeU5mIVOdf0oykP+u2lIVU/I=
+go.opentelemetry.io/proto/otlp v1.0.0/go.mod h1:Sy6pihPLfYHkr3NkUbEhGHFhINUSI/v80hjKIs5JXpM=
 go.uber.org/atomic v1.9.0 h1:ECmE8Bn/WFTYwEW/bpKD3M8VtR/zQVbavAoalC1PYyE=
 go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc=
 go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
@@ -164,8 +283,14 @@ golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=
 golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
 golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
 golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220704084225-05e143d24a9e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
 golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/term v0.37.0 h1:8EGAD0qCmHYZg6J17DvsMy9/wJ7/D/4pV/wfnld5lTU=
@@ -177,9 +302,15 @@ golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
 golang.org/x/tools v0.38.0 h1:Hx2Xv8hISq8Lm16jvBZ2VQf+RLmbd7wVUsALibYI/IQ=
 golang.org/x/tools v0.38.0/go.mod h1:yEsQ/d/YK8cjh0L6rZlY8tgtlKiBNTL14pGDJPJpYQs=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
-google.golang.org/protobuf v1.31.0 h1:g0LDEJHgrBl9N9r17Ru3sqWhkIx2NB67okBHPwC7hs8=
-google.golang.org/protobuf v1.31.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
+google.golang.org/genproto v0.0.0-20231106174013-bbf56f31fb17 h1:wpZ8pe2x1Q3f2KyT5f8oP/fa9rHAKgFPr/HZdNuS+PQ=
+google.golang.org/genproto/googleapis/api v0.0.0-20250929231259-57b25ae835d4 h1:8XJ4pajGwOlasW+L13MnEGA8W4115jJySQtVfS2/IBU=
+google.golang.org/genproto/googleapis/api v0.0.0-20250929231259-57b25ae835d4/go.mod h1:NnuHhy+bxcg30o7FnVAZbXsPHUDQ9qKWAQKCD7VxFtk=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20250929231259-57b25ae835d4 h1:i8QOKZfYg6AbGVZzUAY3LrNWCKF8O6zFisU9Wl9RER4=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20250929231259-57b25ae835d4/go.mod h1:HSkG/KdJWusxU1F6CNrwNDjBMgisKxGnc5dAZfT0mjQ=
+google.golang.org/grpc v1.75.1 h1:/ODCNEuf9VghjgO3rqLcfg8fiOP0nSluljWFlDxELLI=
+google.golang.org/grpc v1.75.1/go.mod h1:JtPAzKiq4v1xcAB2hydNlWI2RnF85XXcV0mhKXr2ecQ=
+google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
+google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
@@ -192,6 +323,6 @@ gorm.io/driver/postgres v1.5.4 h1:Iyrp9Meh3GmbSuyIAGyjkN+n9K+GHX9b9MqsTL4EJCo=
 gorm.io/driver/postgres v1.5.4/go.mod h1:Bgo89+h0CRcdA33Y6frlaHHVuTdOf87pmyzwW9C/BH0=
 gorm.io/gorm v1.25.5 h1:zR9lOiiYf09VNh5Q1gphfyia1JpiClIWG9hQaxB/mls=
 gorm.io/gorm v1.25.5/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8=
-gotest.tools/v3 v3.5.1 h1:EENdUnS3pdur5nybKYIh2Vfgc8IUNBjxDPSjtiJcOzU=
-gotest.tools/v3 v3.5.1/go.mod h1:isy3WKz7GK6uNw/sbHzfKBLvlvXwUyV06n6brMxxopU=
+gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
+gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
 rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=

backend/internal/handler/admin/account_handler.go

@@ -3,12 +3,12 @@ package admin
 import (
 	"strconv"
 
-	"sub2api/internal/pkg/claude"
-	"sub2api/internal/pkg/openai"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/pkg/timezone"
-	"sub2api/internal/repository"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/claude"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -33,11 +33,21 @@ type AccountHandler struct {
 	rateLimitService    *service.RateLimitService
 	accountUsageService *service.AccountUsageService
 	accountTestService  *service.AccountTestService
-	usageLogRepo        *repository.UsageLogRepository
+	concurrencyService  *service.ConcurrencyService
+	crsSyncService      *service.CRSSyncService
 }
 
 // NewAccountHandler creates a new admin account handler
-func NewAccountHandler(adminService service.AdminService, oauthService *service.OAuthService, openaiOAuthService *service.OpenAIOAuthService, rateLimitService *service.RateLimitService, accountUsageService *service.AccountUsageService, accountTestService *service.AccountTestService, usageLogRepo *repository.UsageLogRepository) *AccountHandler {
+func NewAccountHandler(
+	adminService service.AdminService,
+	oauthService *service.OAuthService,
+	openaiOAuthService *service.OpenAIOAuthService,
+	rateLimitService *service.RateLimitService,
+	accountUsageService *service.AccountUsageService,
+	accountTestService *service.AccountTestService,
+	concurrencyService *service.ConcurrencyService,
+	crsSyncService *service.CRSSyncService,
+) *AccountHandler {
 	return &AccountHandler{
 		adminService:        adminService,
 		oauthService:        oauthService,
@@ -45,7 +55,8 @@ func NewAccountHandler(adminService service.AdminService, oauthService *service.
 		rateLimitService:    rateLimitService,
 		accountUsageService: accountUsageService,
 		accountTestService:  accountTestService,
-		usageLogRepo:        usageLogRepo,
+		concurrencyService:  concurrencyService,
+		crsSyncService:      crsSyncService,
 	}
 }
 
@@ -76,6 +87,25 @@ type UpdateAccountRequest struct {
 	GroupIDs    *[]int64       `json:"group_ids"`
 }
 
+// BulkUpdateAccountsRequest represents the payload for bulk editing accounts
+type BulkUpdateAccountsRequest struct {
+	AccountIDs  []int64        `json:"account_ids" binding:"required,min=1"`
+	Name        string         `json:"name"`
+	ProxyID     *int64         `json:"proxy_id"`
+	Concurrency *int           `json:"concurrency"`
+	Priority    *int           `json:"priority"`
+	Status      string         `json:"status" binding:"omitempty,oneof=active inactive error"`
+	GroupIDs    *[]int64       `json:"group_ids"`
+	Credentials map[string]any `json:"credentials"`
+	Extra       map[string]any `json:"extra"`
+}
+
+// AccountWithConcurrency extends Account with real-time concurrency info
+type AccountWithConcurrency struct {
+	*model.Account
+	CurrentConcurrency int `json:"current_concurrency"`
+}
+
 // List handles listing all accounts with pagination
 // GET /api/v1/admin/accounts
 func (h *AccountHandler) List(c *gin.Context) {
@@ -87,11 +117,32 @@ func (h *AccountHandler) List(c *gin.Context) {
 
 	accounts, total, err := h.adminService.ListAccounts(c.Request.Context(), page, pageSize, platform, accountType, status, search)
 	if err != nil {
-		response.InternalError(c, "Failed to list accounts: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
-	response.Paginated(c, accounts, total, page, pageSize)
+	// Get current concurrency counts for all accounts
+	accountIDs := make([]int64, len(accounts))
+	for i, acc := range accounts {
+		accountIDs[i] = acc.ID
+	}
+
+	concurrencyCounts, err := h.concurrencyService.GetAccountConcurrencyBatch(c.Request.Context(), accountIDs)
+	if err != nil {
+		// Log error but don't fail the request, just use 0 for all
+		concurrencyCounts = make(map[int64]int)
+	}
+
+	// Build response with concurrency info
+	result := make([]AccountWithConcurrency, len(accounts))
+	for i := range accounts {
+		result[i] = AccountWithConcurrency{
+			Account:            &accounts[i],
+			CurrentConcurrency: concurrencyCounts[accounts[i].ID],
+		}
+	}
+
+	response.Paginated(c, result, total, page, pageSize)
 }
 
 // GetByID handles getting an account by ID
@@ -105,7 +156,7 @@ func (h *AccountHandler) GetByID(c *gin.Context) {
 
 	account, err := h.adminService.GetAccount(c.Request.Context(), accountID)
 	if err != nil {
-		response.NotFound(c, "Account not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -133,7 +184,7 @@ func (h *AccountHandler) Create(c *gin.Context) {
 		GroupIDs:    req.GroupIDs,
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to create account: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -167,7 +218,7 @@ func (h *AccountHandler) Update(c *gin.Context) {
 		GroupIDs:    req.GroupIDs,
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to update account: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -185,7 +236,7 @@ func (h *AccountHandler) Delete(c *gin.Context) {
 
 	err = h.adminService.DeleteAccount(c.Request.Context(), accountID)
 	if err != nil {
-		response.InternalError(c, "Failed to delete account: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -197,6 +248,13 @@ type TestAccountRequest struct {
 	ModelID string `json:"model_id"`
 }
 
+type SyncFromCRSRequest struct {
+	BaseURL     string `json:"base_url" binding:"required"`
+	Username    string `json:"username" binding:"required"`
+	Password    string `json:"password" binding:"required"`
+	SyncProxies *bool  `json:"sync_proxies"`
+}
+
 // Test handles testing account connectivity with SSE streaming
 // POST /api/v1/admin/accounts/:id/test
 func (h *AccountHandler) Test(c *gin.Context) {
@@ -217,6 +275,35 @@ func (h *AccountHandler) Test(c *gin.Context) {
 	}
 }
 
+// SyncFromCRS handles syncing accounts from claude-relay-service (CRS)
+// POST /api/v1/admin/accounts/sync/crs
+func (h *AccountHandler) SyncFromCRS(c *gin.Context) {
+	var req SyncFromCRSRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Default to syncing proxies (can be disabled by explicitly setting false)
+	syncProxies := true
+	if req.SyncProxies != nil {
+		syncProxies = *req.SyncProxies
+	}
+
+	result, err := h.crsSyncService.SyncFromCRS(c.Request.Context(), service.SyncFromCRSInput{
+		BaseURL:     req.BaseURL,
+		Username:    req.Username,
+		Password:    req.Password,
+		SyncProxies: syncProxies,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, result)
+}
+
 // Refresh handles refreshing account credentials
 // POST /api/v1/admin/accounts/:id/refresh
 func (h *AccountHandler) Refresh(c *gin.Context) {
@@ -245,7 +332,7 @@ func (h *AccountHandler) Refresh(c *gin.Context) {
 		// Use OpenAI OAuth service to refresh token
 		tokenInfo, err := h.openaiOAuthService.RefreshAccountToken(c.Request.Context(), account)
 		if err != nil {
-			response.InternalError(c, "Failed to refresh credentials: "+err.Error())
+			response.ErrorFrom(c, err)
 			return
 		}
 
@@ -262,7 +349,7 @@ func (h *AccountHandler) Refresh(c *gin.Context) {
 		// Use Anthropic/Claude OAuth service to refresh token
 		tokenInfo, err := h.oauthService.RefreshAccountToken(c.Request.Context(), account)
 		if err != nil {
-			response.InternalError(c, "Failed to refresh credentials: "+err.Error())
+			response.ErrorFrom(c, err)
 			return
 		}
 
@@ -285,7 +372,7 @@ func (h *AccountHandler) Refresh(c *gin.Context) {
 		Credentials: newCredentials,
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to update account credentials: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -314,9 +401,9 @@ func (h *AccountHandler) GetStats(c *gin.Context) {
 	endTime := timezone.StartOfDay(now.AddDate(0, 0, 1))
 	startTime := timezone.StartOfDay(now.AddDate(0, 0, -days+1))
 
-	stats, err := h.usageLogRepo.GetAccountUsageStats(c.Request.Context(), accountID, startTime, endTime)
+	stats, err := h.accountUsageService.GetAccountUsageStats(c.Request.Context(), accountID, startTime, endTime)
 	if err != nil {
-		response.InternalError(c, "Failed to get account stats: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -334,7 +421,7 @@ func (h *AccountHandler) ClearError(c *gin.Context) {
 
 	account, err := h.adminService.ClearAccountError(c.Request.Context(), accountID)
 	if err != nil {
-		response.InternalError(c, "Failed to clear error: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -360,6 +447,136 @@ func (h *AccountHandler) BatchCreate(c *gin.Context) {
 	})
 }
 
+// BatchUpdateCredentialsRequest represents batch credentials update request
+type BatchUpdateCredentialsRequest struct {
+	AccountIDs []int64 `json:"account_ids" binding:"required,min=1"`
+	Field      string  `json:"field" binding:"required,oneof=account_uuid org_uuid intercept_warmup_requests"`
+	Value      any     `json:"value"`
+}
+
+// BatchUpdateCredentials handles batch updating credentials fields
+// POST /api/v1/admin/accounts/batch-update-credentials
+func (h *AccountHandler) BatchUpdateCredentials(c *gin.Context) {
+	var req BatchUpdateCredentialsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Validate value type based on field
+	if req.Field == "intercept_warmup_requests" {
+		// Must be boolean
+		if _, ok := req.Value.(bool); !ok {
+			response.BadRequest(c, "intercept_warmup_requests must be boolean")
+			return
+		}
+	} else {
+		// account_uuid and org_uuid can be string or null
+		if req.Value != nil {
+			if _, ok := req.Value.(string); !ok {
+				response.BadRequest(c, req.Field+" must be string or null")
+				return
+			}
+		}
+	}
+
+	ctx := c.Request.Context()
+	success := 0
+	failed := 0
+	results := []gin.H{}
+
+	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
+		}
+
+		// Update credentials field
+		if account.Credentials == nil {
+			account.Credentials = make(map[string]any)
+		}
+
+		account.Credentials[req.Field] = req.Value
+
+		// Update account
+		updateInput := &service.UpdateAccountInput{
+			Credentials: account.Credentials,
+		}
+
+		_, err = h.adminService.UpdateAccount(ctx, accountID, updateInput)
+		if err != nil {
+			failed++
+			results = append(results, gin.H{
+				"account_id": accountID,
+				"success":    false,
+				"error":      err.Error(),
+			})
+			continue
+		}
+
+		success++
+		results = append(results, gin.H{
+			"account_id": accountID,
+			"success":    true,
+		})
+	}
+
+	response.Success(c, gin.H{
+		"success": success,
+		"failed":  failed,
+		"results": results,
+	})
+}
+
+// BulkUpdate handles bulk updating accounts with selected fields/credentials.
+// POST /api/v1/admin/accounts/bulk-update
+func (h *AccountHandler) BulkUpdate(c *gin.Context) {
+	var req BulkUpdateAccountsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	hasUpdates := req.Name != "" ||
+		req.ProxyID != nil ||
+		req.Concurrency != nil ||
+		req.Priority != nil ||
+		req.Status != "" ||
+		req.GroupIDs != nil ||
+		len(req.Credentials) > 0 ||
+		len(req.Extra) > 0
+
+	if !hasUpdates {
+		response.BadRequest(c, "No updates provided")
+		return
+	}
+
+	result, err := h.adminService.BulkUpdateAccounts(c.Request.Context(), &service.BulkUpdateAccountsInput{
+		AccountIDs:  req.AccountIDs,
+		Name:        req.Name,
+		ProxyID:     req.ProxyID,
+		Concurrency: req.Concurrency,
+		Priority:    req.Priority,
+		Status:      req.Status,
+		GroupIDs:    req.GroupIDs,
+		Credentials: req.Credentials,
+		Extra:       req.Extra,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, result)
+}
+
 // ========== OAuth Handlers ==========
 
 // GenerateAuthURLRequest represents the request for generating auth URL
@@ -378,7 +595,7 @@ func (h *OAuthHandler) GenerateAuthURL(c *gin.Context) {
 
 	result, err := h.oauthService.GenerateAuthURL(c.Request.Context(), req.ProxyID)
 	if err != nil {
-		response.InternalError(c, "Failed to generate auth URL: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -396,7 +613,7 @@ func (h *OAuthHandler) GenerateSetupTokenURL(c *gin.Context) {
 
 	result, err := h.oauthService.GenerateSetupTokenURL(c.Request.Context(), req.ProxyID)
 	if err != nil {
-		response.InternalError(c, "Failed to generate setup token URL: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -425,7 +642,7 @@ func (h *OAuthHandler) ExchangeCode(c *gin.Context) {
 		ProxyID:   req.ProxyID,
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to exchange code: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -447,7 +664,7 @@ func (h *OAuthHandler) ExchangeSetupTokenCode(c *gin.Context) {
 		ProxyID:   req.ProxyID,
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to exchange code: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -475,7 +692,7 @@ func (h *OAuthHandler) CookieAuth(c *gin.Context) {
 		Scope:      "full",
 	})
 	if err != nil {
-		response.BadRequest(c, "Cookie auth failed: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -497,7 +714,7 @@ func (h *OAuthHandler) SetupTokenCookieAuth(c *gin.Context) {
 		Scope:      "inference",
 	})
 	if err != nil {
-		response.BadRequest(c, "Cookie auth failed: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -515,7 +732,7 @@ func (h *AccountHandler) GetUsage(c *gin.Context) {
 
 	usage, err := h.accountUsageService.GetUsage(c.Request.Context(), accountID)
 	if err != nil {
-		response.InternalError(c, "Failed to get usage: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -533,7 +750,7 @@ func (h *AccountHandler) ClearRateLimit(c *gin.Context) {
 
 	err = h.rateLimitService.ClearRateLimit(c.Request.Context(), accountID)
 	if err != nil {
-		response.InternalError(c, "Failed to clear rate limit: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -551,7 +768,7 @@ func (h *AccountHandler) GetTodayStats(c *gin.Context) {
 
 	stats, err := h.accountUsageService.GetTodayStats(c.Request.Context(), accountID)
 	if err != nil {
-		response.InternalError(c, "Failed to get today stats: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -580,7 +797,7 @@ func (h *AccountHandler) SetSchedulable(c *gin.Context) {
 
 	account, err := h.adminService.SetAccountSchedulable(c.Request.Context(), accountID, req.Schedulable)
 	if err != nil {
-		response.InternalError(c, "Failed to update schedulable status: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/admin/dashboard_handler.go

@@ -1,10 +1,10 @@
 package admin
 
 import (
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"strconv"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/pkg/timezone"
-	"sub2api/internal/repository"
 	"time"
 
 	"github.com/gin-gonic/gin"
@@ -12,15 +12,15 @@ import (
 
 // DashboardHandler handles admin dashboard statistics
 type DashboardHandler struct {
-	usageRepo *repository.UsageLogRepository
-	startTime time.Time // Server start time for uptime calculation
+	dashboardService *service.DashboardService
+	startTime        time.Time // Server start time for uptime calculation
 }
 
 // NewDashboardHandler creates a new admin dashboard handler
-func NewDashboardHandler(usageRepo *repository.UsageLogRepository) *DashboardHandler {
+func NewDashboardHandler(dashboardService *service.DashboardService) *DashboardHandler {
 	return &DashboardHandler{
-		usageRepo: usageRepo,
-		startTime: time.Now(),
+		dashboardService: dashboardService,
+		startTime:        time.Now(),
 	}
 }
 
@@ -58,7 +58,7 @@ func parseTimeRange(c *gin.Context) (time.Time, time.Time) {
 // GetStats handles getting dashboard statistics
 // GET /api/v1/admin/dashboard/stats
 func (h *DashboardHandler) GetStats(c *gin.Context) {
-	stats, err := h.usageRepo.GetDashboardStats(c.Request.Context())
+	stats, err := h.dashboardService.GetDashboardStats(c.Request.Context())
 	if err != nil {
 		response.Error(c, 500, "Failed to get dashboard statistics")
 		return
@@ -107,6 +107,10 @@ func (h *DashboardHandler) GetStats(c *gin.Context) {
 		// 系统运行统计
 		"average_duration_ms": stats.AverageDurationMs,
 		"uptime":              uptime,
+
+		// 性能指标
+		"rpm": stats.Rpm,
+		"tpm": stats.Tpm,
 	})
 }
 
@@ -142,7 +146,7 @@ func (h *DashboardHandler) GetUsageTrend(c *gin.Context) {
 		}
 	}
 
-	trend, err := h.usageRepo.GetUsageTrendWithFilters(c.Request.Context(), startTime, endTime, granularity, userID, apiKeyID)
+	trend, err := h.dashboardService.GetUsageTrendWithFilters(c.Request.Context(), startTime, endTime, granularity, userID, apiKeyID)
 	if err != nil {
 		response.Error(c, 500, "Failed to get usage trend")
 		return
@@ -175,7 +179,7 @@ func (h *DashboardHandler) GetModelStats(c *gin.Context) {
 		}
 	}
 
-	stats, err := h.usageRepo.GetModelStatsWithFilters(c.Request.Context(), startTime, endTime, userID, apiKeyID, 0)
+	stats, err := h.dashboardService.GetModelStatsWithFilters(c.Request.Context(), startTime, endTime, userID, apiKeyID)
 	if err != nil {
 		response.Error(c, 500, "Failed to get model statistics")
 		return
@@ -200,7 +204,7 @@ func (h *DashboardHandler) GetApiKeyUsageTrend(c *gin.Context) {
 		limit = 5
 	}
 
-	trend, err := h.usageRepo.GetApiKeyUsageTrend(c.Request.Context(), startTime, endTime, granularity, limit)
+	trend, err := h.dashboardService.GetApiKeyUsageTrend(c.Request.Context(), startTime, endTime, granularity, limit)
 	if err != nil {
 		response.Error(c, 500, "Failed to get API key usage trend")
 		return
@@ -226,7 +230,7 @@ func (h *DashboardHandler) GetUserUsageTrend(c *gin.Context) {
 		limit = 12
 	}
 
-	trend, err := h.usageRepo.GetUserUsageTrend(c.Request.Context(), startTime, endTime, granularity, limit)
+	trend, err := h.dashboardService.GetUserUsageTrend(c.Request.Context(), startTime, endTime, granularity, limit)
 	if err != nil {
 		response.Error(c, 500, "Failed to get user usage trend")
 		return
@@ -259,7 +263,7 @@ func (h *DashboardHandler) GetBatchUsersUsage(c *gin.Context) {
 		return
 	}
 
-	stats, err := h.usageRepo.GetBatchUserUsageStats(c.Request.Context(), req.UserIDs)
+	stats, err := h.dashboardService.GetBatchUserUsageStats(c.Request.Context(), req.UserIDs)
 	if err != nil {
 		response.Error(c, 500, "Failed to get user usage stats")
 		return
@@ -287,7 +291,7 @@ func (h *DashboardHandler) GetBatchApiKeysUsage(c *gin.Context) {
 		return
 	}
 
-	stats, err := h.usageRepo.GetBatchApiKeyUsageStats(c.Request.Context(), req.ApiKeyIDs)
+	stats, err := h.dashboardService.GetBatchApiKeyUsageStats(c.Request.Context(), req.ApiKeyIDs)
 	if err != nil {
 		response.Error(c, 500, "Failed to get API key usage stats")
 		return

backend/internal/handler/admin/group_handler.go

@@ -3,9 +3,9 @@ package admin
 import (
 	"strconv"
 
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -65,7 +65,7 @@ func (h *GroupHandler) List(c *gin.Context) {
 
 	groups, total, err := h.adminService.ListGroups(c.Request.Context(), page, pageSize, platform, status, isExclusive)
 	if err != nil {
-		response.InternalError(c, "Failed to list groups: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -87,7 +87,7 @@ func (h *GroupHandler) GetAll(c *gin.Context) {
 	}
 
 	if err != nil {
-		response.InternalError(c, "Failed to get groups: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -105,7 +105,7 @@ func (h *GroupHandler) GetByID(c *gin.Context) {
 
 	group, err := h.adminService.GetGroup(c.Request.Context(), groupID)
 	if err != nil {
-		response.NotFound(c, "Group not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -133,7 +133,7 @@ func (h *GroupHandler) Create(c *gin.Context) {
 		MonthlyLimitUSD:  req.MonthlyLimitUSD,
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to create group: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -168,7 +168,7 @@ func (h *GroupHandler) Update(c *gin.Context) {
 		MonthlyLimitUSD:  req.MonthlyLimitUSD,
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to update group: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -186,7 +186,7 @@ func (h *GroupHandler) Delete(c *gin.Context) {
 
 	err = h.adminService.DeleteGroup(c.Request.Context(), groupID)
 	if err != nil {
-		response.InternalError(c, "Failed to delete group: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -225,7 +225,7 @@ func (h *GroupHandler) GetGroupAPIKeys(c *gin.Context) {
 
 	keys, total, err := h.adminService.GetGroupAPIKeys(c.Request.Context(), groupID, page, pageSize)
 	if err != nil {
-		response.InternalError(c, "Failed to get group API keys: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/admin/openai_oauth_handler.go

@@ -3,8 +3,8 @@ package admin
 import (
 	"strconv"
 
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -40,7 +40,7 @@ func (h *OpenAIOAuthHandler) GenerateAuthURL(c *gin.Context) {
 
 	result, err := h.openaiOAuthService.GenerateAuthURL(c.Request.Context(), req.ProxyID, req.RedirectURI)
 	if err != nil {
-		response.InternalError(c, "Failed to generate auth URL: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -71,7 +71,7 @@ func (h *OpenAIOAuthHandler) ExchangeCode(c *gin.Context) {
 		ProxyID:     req.ProxyID,
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to exchange code: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -103,7 +103,7 @@ func (h *OpenAIOAuthHandler) RefreshToken(c *gin.Context) {
 
 	tokenInfo, err := h.openaiOAuthService.RefreshToken(c.Request.Context(), req.RefreshToken, proxyURL)
 	if err != nil {
-		response.BadRequest(c, "Failed to refresh token: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -122,7 +122,7 @@ func (h *OpenAIOAuthHandler) RefreshAccountToken(c *gin.Context) {
 	// Get account
 	account, err := h.adminService.GetAccount(c.Request.Context(), accountID)
 	if err != nil {
-		response.NotFound(c, "Account not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -141,7 +141,7 @@ func (h *OpenAIOAuthHandler) RefreshAccountToken(c *gin.Context) {
 	// Use OpenAI OAuth service to refresh token
 	tokenInfo, err := h.openaiOAuthService.RefreshAccountToken(c.Request.Context(), account)
 	if err != nil {
-		response.InternalError(c, "Failed to refresh credentials: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -159,7 +159,7 @@ func (h *OpenAIOAuthHandler) RefreshAccountToken(c *gin.Context) {
 		Credentials: newCredentials,
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to update account credentials: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -192,7 +192,7 @@ func (h *OpenAIOAuthHandler) CreateAccountFromOAuth(c *gin.Context) {
 		ProxyID:     req.ProxyID,
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to exchange code: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -220,7 +220,7 @@ func (h *OpenAIOAuthHandler) CreateAccountFromOAuth(c *gin.Context) {
 		GroupIDs:    req.GroupIDs,
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to create account: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/admin/proxy_handler.go

@@ -4,8 +4,8 @@ import (
 	"strconv"
 	"strings"
 
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -53,7 +53,7 @@ func (h *ProxyHandler) List(c *gin.Context) {
 
 	proxies, total, err := h.adminService.ListProxies(c.Request.Context(), page, pageSize, protocol, status, search)
 	if err != nil {
-		response.InternalError(c, "Failed to list proxies: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -69,7 +69,7 @@ func (h *ProxyHandler) GetAll(c *gin.Context) {
 	if withCount {
 		proxies, err := h.adminService.GetAllProxiesWithAccountCount(c.Request.Context())
 		if err != nil {
-			response.InternalError(c, "Failed to get proxies: "+err.Error())
+			response.ErrorFrom(c, err)
 			return
 		}
 		response.Success(c, proxies)
@@ -78,7 +78,7 @@ func (h *ProxyHandler) GetAll(c *gin.Context) {
 
 	proxies, err := h.adminService.GetAllProxies(c.Request.Context())
 	if err != nil {
-		response.InternalError(c, "Failed to get proxies: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -96,7 +96,7 @@ func (h *ProxyHandler) GetByID(c *gin.Context) {
 
 	proxy, err := h.adminService.GetProxy(c.Request.Context(), proxyID)
 	if err != nil {
-		response.NotFound(c, "Proxy not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -121,7 +121,7 @@ func (h *ProxyHandler) Create(c *gin.Context) {
 		Password: strings.TrimSpace(req.Password),
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to create proxy: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -153,7 +153,7 @@ func (h *ProxyHandler) Update(c *gin.Context) {
 		Status:   strings.TrimSpace(req.Status),
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to update proxy: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -171,7 +171,7 @@ func (h *ProxyHandler) Delete(c *gin.Context) {
 
 	err = h.adminService.DeleteProxy(c.Request.Context(), proxyID)
 	if err != nil {
-		response.InternalError(c, "Failed to delete proxy: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -189,7 +189,7 @@ func (h *ProxyHandler) Test(c *gin.Context) {
 
 	result, err := h.adminService.TestProxy(c.Request.Context(), proxyID)
 	if err != nil {
-		response.InternalError(c, "Failed to test proxy: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -229,7 +229,7 @@ func (h *ProxyHandler) GetProxyAccounts(c *gin.Context) {
 
 	accounts, total, err := h.adminService.GetProxyAccounts(c.Request.Context(), proxyID, page, pageSize)
 	if err != nil {
-		response.InternalError(c, "Failed to get proxy accounts: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -272,7 +272,7 @@ func (h *ProxyHandler) BatchCreate(c *gin.Context) {
 		// Check for duplicates (same host, port, username, password)
 		exists, err := h.adminService.CheckProxyExists(c.Request.Context(), host, item.Port, username, password)
 		if err != nil {
-			response.InternalError(c, "Failed to check proxy existence: "+err.Error())
+			response.ErrorFrom(c, err)
 			return
 		}
 

backend/internal/handler/admin/redeem_handler.go

@@ -6,8 +6,8 @@ import (
 	"fmt"
 	"strconv"
 
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -43,7 +43,7 @@ func (h *RedeemHandler) List(c *gin.Context) {
 
 	codes, total, err := h.adminService.ListRedeemCodes(c.Request.Context(), page, pageSize, codeType, status, search)
 	if err != nil {
-		response.InternalError(c, "Failed to list redeem codes: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -61,7 +61,7 @@ func (h *RedeemHandler) GetByID(c *gin.Context) {
 
 	code, err := h.adminService.GetRedeemCode(c.Request.Context(), codeID)
 	if err != nil {
-		response.NotFound(c, "Redeem code not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -85,7 +85,7 @@ func (h *RedeemHandler) Generate(c *gin.Context) {
 		ValidityDays: req.ValidityDays,
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to generate redeem codes: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -103,7 +103,7 @@ func (h *RedeemHandler) Delete(c *gin.Context) {
 
 	err = h.adminService.DeleteRedeemCode(c.Request.Context(), codeID)
 	if err != nil {
-		response.InternalError(c, "Failed to delete redeem code: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -123,7 +123,7 @@ func (h *RedeemHandler) BatchDelete(c *gin.Context) {
 
 	deleted, err := h.adminService.BatchDeleteRedeemCodes(c.Request.Context(), req.IDs)
 	if err != nil {
-		response.InternalError(c, "Failed to batch delete redeem codes: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -144,7 +144,7 @@ func (h *RedeemHandler) Expire(c *gin.Context) {
 
 	code, err := h.adminService.ExpireRedeemCode(c.Request.Context(), codeID)
 	if err != nil {
-		response.InternalError(c, "Failed to expire redeem code: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -178,7 +178,7 @@ func (h *RedeemHandler) Export(c *gin.Context) {
 	// Get all codes without pagination (use large page size)
 	codes, _, err := h.adminService.ListRedeemCodes(c.Request.Context(), 1, 10000, codeType, status, "")
 	if err != nil {
-		response.InternalError(c, "Failed to export redeem codes: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/admin/setting_handler.go

@@ -1,9 +1,9 @@
 package admin
 
 import (
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -27,7 +27,7 @@ func NewSettingHandler(settingService *service.SettingService, emailService *ser
 func (h *SettingHandler) GetSettings(c *gin.Context) {
 	settings, err := h.settingService.GetAllSettings(c.Request.Context())
 	if err != nil {
-		response.InternalError(c, "Failed to get settings: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -60,6 +60,7 @@ type UpdateSettingsRequest struct {
 	SiteSubtitle string `json:"site_subtitle"`
 	ApiBaseUrl   string `json:"api_base_url"`
 	ContactInfo  string `json:"contact_info"`
+	DocUrl       string `json:"doc_url"`
 
 	// 默认配置
 	DefaultConcurrency int     `json:"default_concurrency"`
@@ -104,19 +105,20 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		SiteSubtitle:        req.SiteSubtitle,
 		ApiBaseUrl:          req.ApiBaseUrl,
 		ContactInfo:         req.ContactInfo,
+		DocUrl:              req.DocUrl,
 		DefaultConcurrency:  req.DefaultConcurrency,
 		DefaultBalance:      req.DefaultBalance,
 	}
 
 	if err := h.settingService.UpdateSettings(c.Request.Context(), settings); err != nil {
-		response.InternalError(c, "Failed to update settings: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
 	// 重新获取设置返回
 	updatedSettings, err := h.settingService.GetAllSettings(c.Request.Context())
 	if err != nil {
-		response.InternalError(c, "Failed to get updated settings: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -164,7 +166,7 @@ func (h *SettingHandler) TestSmtpConnection(c *gin.Context) {
 
 	err := h.emailService.TestSmtpConnectionWithConfig(config)
 	if err != nil {
-		response.BadRequest(c, "SMTP connection test failed: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -250,7 +252,7 @@ func (h *SettingHandler) SendTestEmail(c *gin.Context) {
 `
 
 	if err := h.emailService.SendEmailWithConfig(config, req.Email, subject, body); err != nil {
-		response.BadRequest(c, "Failed to send test email: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -262,7 +264,7 @@ func (h *SettingHandler) SendTestEmail(c *gin.Context) {
 func (h *SettingHandler) GetAdminApiKey(c *gin.Context) {
 	maskedKey, exists, err := h.settingService.GetAdminApiKeyStatus(c.Request.Context())
 	if err != nil {
-		response.InternalError(c, "Failed to get admin API key status: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -277,7 +279,7 @@ func (h *SettingHandler) GetAdminApiKey(c *gin.Context) {
 func (h *SettingHandler) RegenerateAdminApiKey(c *gin.Context) {
 	key, err := h.settingService.GenerateAdminApiKey(c.Request.Context())
 	if err != nil {
-		response.InternalError(c, "Failed to generate admin API key: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -290,7 +292,7 @@ func (h *SettingHandler) RegenerateAdminApiKey(c *gin.Context) {
 // DELETE /api/v1/admin/settings/admin-api-key
 func (h *SettingHandler) DeleteAdminApiKey(c *gin.Context) {
 	if err := h.settingService.DeleteAdminApiKey(c.Request.Context()); err != nil {
-		response.InternalError(c, "Failed to delete admin API key: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/admin/subscription_handler.go

@@ -3,10 +3,10 @@ package admin
 import (
 	"strconv"
 
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -78,7 +78,7 @@ func (h *SubscriptionHandler) List(c *gin.Context) {
 
 	subscriptions, pagination, err := h.subscriptionService.List(c.Request.Context(), page, pageSize, userID, groupID, status)
 	if err != nil {
-		response.InternalError(c, "Failed to list subscriptions: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -96,7 +96,7 @@ func (h *SubscriptionHandler) GetByID(c *gin.Context) {
 
 	subscription, err := h.subscriptionService.GetByID(c.Request.Context(), subscriptionID)
 	if err != nil {
-		response.NotFound(c, "Subscription not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -141,7 +141,7 @@ func (h *SubscriptionHandler) Assign(c *gin.Context) {
 		Notes:        req.Notes,
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to assign subscription: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -168,7 +168,7 @@ func (h *SubscriptionHandler) BulkAssign(c *gin.Context) {
 		Notes:        req.Notes,
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to bulk assign subscriptions: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -192,7 +192,7 @@ func (h *SubscriptionHandler) Extend(c *gin.Context) {
 
 	subscription, err := h.subscriptionService.ExtendSubscription(c.Request.Context(), subscriptionID, req.Days)
 	if err != nil {
-		response.InternalError(c, "Failed to extend subscription: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -210,7 +210,7 @@ func (h *SubscriptionHandler) Revoke(c *gin.Context) {
 
 	err = h.subscriptionService.RevokeSubscription(c.Request.Context(), subscriptionID)
 	if err != nil {
-		response.InternalError(c, "Failed to revoke subscription: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -230,7 +230,7 @@ func (h *SubscriptionHandler) ListByGroup(c *gin.Context) {
 
 	subscriptions, pagination, err := h.subscriptionService.ListGroupSubscriptions(c.Request.Context(), groupID, page, pageSize)
 	if err != nil {
-		response.InternalError(c, "Failed to list group subscriptions: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -248,7 +248,7 @@ func (h *SubscriptionHandler) ListByUser(c *gin.Context) {
 
 	subscriptions, err := h.subscriptionService.ListUserSubscriptions(c.Request.Context(), userID)
 	if err != nil {
-		response.InternalError(c, "Failed to list user subscriptions: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/admin/system_handler.go

@@ -4,9 +4,9 @@ import (
 	"net/http"
 	"time"
 
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/pkg/sysutil"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/sysutil"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )

backend/internal/handler/admin/usage_handler.go

@@ -4,35 +4,32 @@ import (
 	"strconv"
 	"time"
 
-	"sub2api/internal/pkg/pagination"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/pkg/timezone"
-	"sub2api/internal/repository"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
 
 // UsageHandler handles admin usage-related requests
 type UsageHandler struct {
-	usageRepo    *repository.UsageLogRepository
-	apiKeyRepo   *repository.ApiKeyRepository
-	usageService *service.UsageService
-	adminService service.AdminService
+	usageService  *service.UsageService
+	apiKeyService *service.ApiKeyService
+	adminService  service.AdminService
 }
 
 // NewUsageHandler creates a new admin usage handler
 func NewUsageHandler(
-	usageRepo *repository.UsageLogRepository,
-	apiKeyRepo *repository.ApiKeyRepository,
 	usageService *service.UsageService,
+	apiKeyService *service.ApiKeyService,
 	adminService service.AdminService,
 ) *UsageHandler {
 	return &UsageHandler{
-		usageRepo:    usageRepo,
-		apiKeyRepo:   apiKeyRepo,
-		usageService: usageService,
-		adminService: adminService,
+		usageService:  usageService,
+		apiKeyService: apiKeyService,
+		adminService:  adminService,
 	}
 }
 
@@ -84,16 +81,16 @@ func (h *UsageHandler) List(c *gin.Context) {
 	}
 
 	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
-	filters := repository.UsageLogFilters{
+	filters := usagestats.UsageLogFilters{
 		UserID:    userID,
 		ApiKeyID:  apiKeyID,
 		StartTime: startTime,
 		EndTime:   endTime,
 	}
 
-	records, result, err := h.usageRepo.ListWithFilters(c.Request.Context(), params, filters)
+	records, result, err := h.usageService.ListWithFilters(c.Request.Context(), params, filters)
 	if err != nil {
-		response.InternalError(c, "Failed to list usage records: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -161,7 +158,7 @@ func (h *UsageHandler) Stats(c *gin.Context) {
 	if apiKeyID > 0 {
 		stats, err := h.usageService.GetStatsByApiKey(c.Request.Context(), apiKeyID, startTime, endTime)
 		if err != nil {
-			response.InternalError(c, "Failed to get usage statistics: "+err.Error())
+			response.ErrorFrom(c, err)
 			return
 		}
 		response.Success(c, stats)
@@ -171,7 +168,7 @@ func (h *UsageHandler) Stats(c *gin.Context) {
 	if userID > 0 {
 		stats, err := h.usageService.GetStatsByUser(c.Request.Context(), userID, startTime, endTime)
 		if err != nil {
-			response.InternalError(c, "Failed to get usage statistics: "+err.Error())
+			response.ErrorFrom(c, err)
 			return
 		}
 		response.Success(c, stats)
@@ -179,9 +176,9 @@ func (h *UsageHandler) Stats(c *gin.Context) {
 	}
 
 	// Get global stats
-	stats, err := h.usageRepo.GetGlobalStats(c.Request.Context(), startTime, endTime)
+	stats, err := h.usageService.GetGlobalStats(c.Request.Context(), startTime, endTime)
 	if err != nil {
-		response.InternalError(c, "Failed to get usage statistics: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -200,7 +197,7 @@ func (h *UsageHandler) SearchUsers(c *gin.Context) {
 	// Limit to 30 results
 	users, _, err := h.adminService.ListUsers(c.Request.Context(), 1, 30, "", "", keyword)
 	if err != nil {
-		response.InternalError(c, "Failed to search users: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -237,9 +234,9 @@ func (h *UsageHandler) SearchApiKeys(c *gin.Context) {
 		userID = id
 	}
 
-	keys, err := h.apiKeyRepo.SearchApiKeys(c.Request.Context(), userID, keyword, 30)
+	keys, err := h.apiKeyService.SearchApiKeys(c.Request.Context(), userID, keyword, 30)
 	if err != nil {
-		response.InternalError(c, "Failed to search API keys: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/admin/user_handler.go

@@ -3,8 +3,8 @@ package admin
 import (
 	"strconv"
 
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -49,8 +49,9 @@ type UpdateUserRequest struct {
 
 // UpdateBalanceRequest represents balance update request
 type UpdateBalanceRequest struct {
-	Balance   float64 `json:"balance" binding:"required"`
+	Balance   float64 `json:"balance" binding:"required,gt=0"`
 	Operation string  `json:"operation" binding:"required,oneof=set add subtract"`
+	Notes     string  `json:"notes"`
 }
 
 // List handles listing all users with pagination
@@ -63,7 +64,7 @@ func (h *UserHandler) List(c *gin.Context) {
 
 	users, total, err := h.adminService.ListUsers(c.Request.Context(), page, pageSize, status, role, search)
 	if err != nil {
-		response.InternalError(c, "Failed to list users: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -81,7 +82,7 @@ func (h *UserHandler) GetByID(c *gin.Context) {
 
 	user, err := h.adminService.GetUser(c.Request.Context(), userID)
 	if err != nil {
-		response.NotFound(c, "User not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -108,7 +109,7 @@ func (h *UserHandler) Create(c *gin.Context) {
 		AllowedGroups: req.AllowedGroups,
 	})
 	if err != nil {
-		response.BadRequest(c, "Failed to create user: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -143,7 +144,7 @@ func (h *UserHandler) Update(c *gin.Context) {
 		AllowedGroups: req.AllowedGroups,
 	})
 	if err != nil {
-		response.InternalError(c, "Failed to update user: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -161,7 +162,7 @@ func (h *UserHandler) Delete(c *gin.Context) {
 
 	err = h.adminService.DeleteUser(c.Request.Context(), userID)
 	if err != nil {
-		response.InternalError(c, "Failed to delete user: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -183,9 +184,9 @@ func (h *UserHandler) UpdateBalance(c *gin.Context) {
 		return
 	}
 
-	user, err := h.adminService.UpdateUserBalance(c.Request.Context(), userID, req.Balance, req.Operation)
+	user, err := h.adminService.UpdateUserBalance(c.Request.Context(), userID, req.Balance, req.Operation, req.Notes)
 	if err != nil {
-		response.InternalError(c, "Failed to update balance: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -205,7 +206,7 @@ func (h *UserHandler) GetUserAPIKeys(c *gin.Context) {
 
 	keys, total, err := h.adminService.GetUserAPIKeys(c.Request.Context(), userID, page, pageSize)
 	if err != nil {
-		response.InternalError(c, "Failed to get user API keys: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -225,7 +226,7 @@ func (h *UserHandler) GetUserUsage(c *gin.Context) {
 
 	stats, err := h.adminService.GetUserUsageStats(c.Request.Context(), userID, period)
 	if err != nil {
-		response.InternalError(c, "Failed to get user usage: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/api_key_handler.go

@@ -3,10 +3,10 @@ package handler
 import (
 	"strconv"
 
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -57,7 +57,7 @@ func (h *APIKeyHandler) List(c *gin.Context) {
 
 	keys, result, err := h.apiKeyService.List(c.Request.Context(), user.ID, params)
 	if err != nil {
-		response.InternalError(c, "Failed to list API keys: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -87,7 +87,7 @@ func (h *APIKeyHandler) GetByID(c *gin.Context) {
 
 	key, err := h.apiKeyService.GetByID(c.Request.Context(), keyID)
 	if err != nil {
-		response.NotFound(c, "API key not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -128,7 +128,7 @@ func (h *APIKeyHandler) Create(c *gin.Context) {
 	}
 	key, err := h.apiKeyService.Create(c.Request.Context(), user.ID, svcReq)
 	if err != nil {
-		response.InternalError(c, "Failed to create API key: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -173,7 +173,7 @@ func (h *APIKeyHandler) Update(c *gin.Context) {
 
 	key, err := h.apiKeyService.Update(c.Request.Context(), keyID, user.ID, svcReq)
 	if err != nil {
-		response.InternalError(c, "Failed to update API key: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -203,7 +203,7 @@ func (h *APIKeyHandler) Delete(c *gin.Context) {
 
 	err = h.apiKeyService.Delete(c.Request.Context(), keyID, user.ID)
 	if err != nil {
-		response.InternalError(c, "Failed to delete API key: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -227,7 +227,7 @@ func (h *APIKeyHandler) GetAvailableGroups(c *gin.Context) {
 
 	groups, err := h.apiKeyService.GetAvailableGroups(c.Request.Context(), user.ID)
 	if err != nil {
-		response.InternalError(c, "Failed to get available groups: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/auth_handler.go

@@ -1,9 +1,9 @@
 package handler
 
 import (
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -66,14 +66,14 @@ func (h *AuthHandler) Register(c *gin.Context) {
 	// Turnstile 验证（当提供了邮箱验证码时跳过，因为发送验证码时已验证过）
 	if req.VerifyCode == "" {
 		if err := h.authService.VerifyTurnstile(c.Request.Context(), req.TurnstileToken, c.ClientIP()); err != nil {
-			response.BadRequest(c, "Turnstile verification failed: "+err.Error())
+			response.ErrorFrom(c, err)
 			return
 		}
 	}
 
 	token, user, err := h.authService.RegisterWithVerification(c.Request.Context(), req.Email, req.Password, req.VerifyCode)
 	if err != nil {
-		response.BadRequest(c, "Registration failed: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -95,13 +95,13 @@ func (h *AuthHandler) SendVerifyCode(c *gin.Context) {
 
 	// Turnstile 验证
 	if err := h.authService.VerifyTurnstile(c.Request.Context(), req.TurnstileToken, c.ClientIP()); err != nil {
-		response.BadRequest(c, "Turnstile verification failed: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
 	result, err := h.authService.SendVerifyCodeAsync(c.Request.Context(), req.Email)
 	if err != nil {
-		response.BadRequest(c, "Failed to send verification code: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -122,13 +122,13 @@ func (h *AuthHandler) Login(c *gin.Context) {
 
 	// Turnstile 验证
 	if err := h.authService.VerifyTurnstile(c.Request.Context(), req.TurnstileToken, c.ClientIP()); err != nil {
-		response.BadRequest(c, "Turnstile verification failed: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
 	token, user, err := h.authService.Login(c.Request.Context(), req.Email, req.Password)
 	if err != nil {
-		response.Unauthorized(c, "Login failed: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/gateway_handler.go

@@ -10,11 +10,11 @@ import (
 	"strings"
 	"time"
 
-	"sub2api/internal/middleware"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/claude"
-	"sub2api/internal/pkg/openai"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/claude"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -41,13 +41,13 @@ func NewGatewayHandler(gatewayService *service.GatewayService, userService *serv
 // POST /v1/messages
 func (h *GatewayHandler) Messages(c *gin.Context) {
 	// 从context获取apiKey和user（ApiKeyAuth中间件已设置）
-	apiKey, ok := middleware.GetApiKeyFromContext(c)
+	apiKey, ok := middleware2.GetApiKeyFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
 	}
 
-	user, ok := middleware.GetUserFromContext(c)
+	user, ok := middleware2.GetUserFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusInternalServerError, "api_error", "User context not found")
 		return
@@ -79,7 +79,7 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 	streamStarted := false
 
 	// 获取订阅信息（可能为nil）- 提前获取用于后续检查
-	subscription, _ := middleware.GetSubscriptionFromContext(c)
+	subscription, _ := middleware2.GetSubscriptionFromContext(c)
 
 	// 0. 检查wait队列是否已满
 	maxWait := service.CalculateMaxWait(user.Concurrency)
@@ -171,7 +171,7 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 // GET /v1/models
 // Returns different model lists based on the API key's group platform
 func (h *GatewayHandler) Models(c *gin.Context) {
-	apiKey, _ := middleware.GetApiKeyFromContext(c)
+	apiKey, _ := middleware2.GetApiKeyFromContext(c)
 
 	// Return OpenAI models for OpenAI platform groups
 	if apiKey != nil && apiKey.Group != nil && apiKey.Group.Platform == "openai" {
@@ -192,13 +192,13 @@ func (h *GatewayHandler) Models(c *gin.Context) {
 // Usage handles getting account balance for CC Switch integration
 // GET /v1/usage
 func (h *GatewayHandler) Usage(c *gin.Context) {
-	apiKey, ok := middleware.GetApiKeyFromContext(c)
+	apiKey, ok := middleware2.GetApiKeyFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
 	}
 
-	user, ok := middleware.GetUserFromContext(c)
+	user, ok := middleware2.GetUserFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
@@ -206,7 +206,7 @@ func (h *GatewayHandler) Usage(c *gin.Context) {
 
 	// 订阅模式：返回订阅限额信息
 	if apiKey.Group != nil && apiKey.Group.IsSubscriptionType() {
-		subscription, ok := middleware.GetSubscriptionFromContext(c)
+		subscription, ok := middleware2.GetSubscriptionFromContext(c)
 		if !ok {
 			h.errorResponse(c, http.StatusForbidden, "subscription_error", "No active subscription")
 			return
@@ -328,13 +328,13 @@ func (h *GatewayHandler) errorResponse(c *gin.Context, status int, errType, mess
 // 特点：校验订阅/余额，但不计算并发、不记录使用量
 func (h *GatewayHandler) CountTokens(c *gin.Context) {
 	// 从context获取apiKey和user（ApiKeyAuth中间件已设置）
-	apiKey, ok := middleware.GetApiKeyFromContext(c)
+	apiKey, ok := middleware2.GetApiKeyFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
 	}
 
-	user, ok := middleware.GetUserFromContext(c)
+	user, ok := middleware2.GetUserFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusInternalServerError, "api_error", "User context not found")
 		return
@@ -362,7 +362,7 @@ func (h *GatewayHandler) CountTokens(c *gin.Context) {
 	}
 
 	// 获取订阅信息（可能为nil）
-	subscription, _ := middleware.GetSubscriptionFromContext(c)
+	subscription, _ := middleware2.GetSubscriptionFromContext(c)
 
 	// 校验 billing eligibility（订阅/余额）
 	// 【注意】不计算并发，但需要校验订阅/余额

backend/internal/handler/gateway_helper.go

@@ -6,8 +6,8 @@ import (
 	"net/http"
 	"time"
 
-	"sub2api/internal/model"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )

backend/internal/handler/handler.go

@@ -1,7 +1,7 @@
 package handler
 
 import (
-	"sub2api/internal/handler/admin"
+	"github.com/Wei-Shaw/sub2api/internal/handler/admin"
 )
 
 // AdminHandlers contains all admin-related HTTP handlers

backend/internal/handler/openai_gateway_handler.go

@@ -9,9 +9,9 @@ import (
 	"net/http"
 	"time"
 
-	"sub2api/internal/middleware"
-	"sub2api/internal/pkg/openai"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -40,13 +40,13 @@ func NewOpenAIGatewayHandler(
 // POST /openai/v1/responses
 func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
 	// Get apiKey and user from context (set by ApiKeyAuth middleware)
-	apiKey, ok := middleware.GetApiKeyFromContext(c)
+	apiKey, ok := middleware2.GetApiKeyFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
 	}
 
-	user, ok := middleware.GetUserFromContext(c)
+	user, ok := middleware2.GetUserFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusInternalServerError, "api_error", "User context not found")
 		return
@@ -91,7 +91,7 @@ func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
 	streamStarted := false
 
 	// Get subscription info (may be nil)
-	subscription, _ := middleware.GetSubscriptionFromContext(c)
+	subscription, _ := middleware2.GetSubscriptionFromContext(c)
 
 	// 0. Check if wait queue is full
 	maxWait := service.CalculateMaxWait(user.Concurrency)

backend/internal/handler/redeem_handler.go

@@ -1,9 +1,9 @@
 package handler
 
 import (
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -57,7 +57,7 @@ func (h *RedeemHandler) Redeem(c *gin.Context) {
 
 	result, err := h.redeemService.Redeem(c.Request.Context(), user.ID, req.Code)
 	if err != nil {
-		response.BadRequest(c, "Failed to redeem code: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -84,7 +84,7 @@ func (h *RedeemHandler) GetHistory(c *gin.Context) {
 
 	codes, err := h.redeemService.GetUserHistory(c.Request.Context(), user.ID, limit)
 	if err != nil {
-		response.InternalError(c, "Failed to get history: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/setting_handler.go

@@ -1,8 +1,8 @@
 package handler
 
 import (
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -26,7 +26,7 @@ func NewSettingHandler(settingService *service.SettingService, version string) *
 func (h *SettingHandler) GetPublicSettings(c *gin.Context) {
 	settings, err := h.settingService.GetPublicSettings(c.Request.Context())
 	if err != nil {
-		response.InternalError(c, "Failed to get settings: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/subscription_handler.go

@@ -1,9 +1,9 @@
 package handler
 
 import (
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -58,7 +58,7 @@ func (h *SubscriptionHandler) List(c *gin.Context) {
 
 	subscriptions, err := h.subscriptionService.ListUserSubscriptions(c.Request.Context(), u.ID)
 	if err != nil {
-		response.InternalError(c, "Failed to list subscriptions: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -82,7 +82,7 @@ func (h *SubscriptionHandler) GetActive(c *gin.Context) {
 
 	subscriptions, err := h.subscriptionService.ListActiveUserSubscriptions(c.Request.Context(), u.ID)
 	if err != nil {
-		response.InternalError(c, "Failed to get active subscriptions: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -107,7 +107,7 @@ func (h *SubscriptionHandler) GetProgress(c *gin.Context) {
 	// Get all active subscriptions with progress
 	subscriptions, err := h.subscriptionService.ListActiveUserSubscriptions(c.Request.Context(), u.ID)
 	if err != nil {
-		response.InternalError(c, "Failed to get subscriptions: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -146,7 +146,7 @@ func (h *SubscriptionHandler) GetSummary(c *gin.Context) {
 	// Get all active subscriptions
 	subscriptions, err := h.subscriptionService.ListActiveUserSubscriptions(c.Request.Context(), u.ID)
 	if err != nil {
-		response.InternalError(c, "Failed to get subscriptions: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/usage_handler.go

@@ -4,12 +4,11 @@ import (
 	"strconv"
 	"time"
 
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/pkg/timezone"
-	"sub2api/internal/repository"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -17,15 +16,13 @@ import (
 // UsageHandler handles usage-related requests
 type UsageHandler struct {
 	usageService  *service.UsageService
-	usageRepo     *repository.UsageLogRepository
 	apiKeyService *service.ApiKeyService
 }
 
 // NewUsageHandler creates a new UsageHandler
-func NewUsageHandler(usageService *service.UsageService, usageRepo *repository.UsageLogRepository, apiKeyService *service.ApiKeyService) *UsageHandler {
+func NewUsageHandler(usageService *service.UsageService, apiKeyService *service.ApiKeyService) *UsageHandler {
 	return &UsageHandler{
 		usageService:  usageService,
-		usageRepo:     usageRepo,
 		apiKeyService: apiKeyService,
 	}
 }
@@ -58,7 +55,7 @@ func (h *UsageHandler) List(c *gin.Context) {
 		// [Security Fix] Verify API Key ownership to prevent horizontal privilege escalation
 		apiKey, err := h.apiKeyService.GetByID(c.Request.Context(), id)
 		if err != nil {
-			response.NotFound(c, "API key not found")
+			response.ErrorFrom(c, err)
 			return
 		}
 		if apiKey.UserID != user.ID {
@@ -80,7 +77,7 @@ func (h *UsageHandler) List(c *gin.Context) {
 		records, result, err = h.usageService.ListByUser(c.Request.Context(), user.ID, params)
 	}
 	if err != nil {
-		response.InternalError(c, "Failed to list usage records: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -110,7 +107,7 @@ func (h *UsageHandler) GetByID(c *gin.Context) {
 
 	record, err := h.usageService.GetByID(c.Request.Context(), usageID)
 	if err != nil {
-		response.NotFound(c, "Usage record not found")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -207,7 +204,7 @@ func (h *UsageHandler) Stats(c *gin.Context) {
 		stats, err = h.usageService.GetStatsByUser(c.Request.Context(), user.ID, startTime, endTime)
 	}
 	if err != nil {
-		response.InternalError(c, "Failed to get usage statistics: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -260,9 +257,9 @@ func (h *UsageHandler) DashboardStats(c *gin.Context) {
 		return
 	}
 
-	stats, err := h.usageRepo.GetUserDashboardStats(c.Request.Context(), user.ID)
+	stats, err := h.usageService.GetUserDashboardStats(c.Request.Context(), user.ID)
 	if err != nil {
-		response.InternalError(c, "Failed to get dashboard statistics")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -287,9 +284,9 @@ func (h *UsageHandler) DashboardTrend(c *gin.Context) {
 	startTime, endTime := parseUserTimeRange(c)
 	granularity := c.DefaultQuery("granularity", "day")
 
-	trend, err := h.usageRepo.GetUserUsageTrendByUserID(c.Request.Context(), user.ID, startTime, endTime, granularity)
+	trend, err := h.usageService.GetUserUsageTrendByUserID(c.Request.Context(), user.ID, startTime, endTime, granularity)
 	if err != nil {
-		response.InternalError(c, "Failed to get usage trend")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -318,9 +315,9 @@ func (h *UsageHandler) DashboardModels(c *gin.Context) {
 
 	startTime, endTime := parseUserTimeRange(c)
 
-	stats, err := h.usageRepo.GetUserModelStats(c.Request.Context(), user.ID, startTime, endTime)
+	stats, err := h.usageService.GetUserModelStats(c.Request.Context(), user.ID, startTime, endTime)
 	if err != nil {
-		response.InternalError(c, "Failed to get model statistics")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -365,7 +362,7 @@ func (h *UsageHandler) DashboardApiKeysUsage(c *gin.Context) {
 	// Verify ownership of all requested API keys
 	userApiKeys, _, err := h.apiKeyService.List(c.Request.Context(), user.ID, pagination.PaginationParams{Page: 1, PageSize: 1000})
 	if err != nil {
-		response.InternalError(c, "Failed to verify API key ownership")
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -387,9 +384,9 @@ func (h *UsageHandler) DashboardApiKeysUsage(c *gin.Context) {
 		return
 	}
 
-	stats, err := h.usageRepo.GetBatchApiKeyUsageStats(c.Request.Context(), validApiKeyIDs)
+	stats, err := h.usageService.GetBatchApiKeyUsageStats(c.Request.Context(), validApiKeyIDs)
 	if err != nil {
-		response.InternalError(c, "Failed to get API key usage stats")
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/user_handler.go

@@ -1,9 +1,9 @@
 package handler
 
 import (
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/response"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
@@ -49,7 +49,7 @@ func (h *UserHandler) GetProfile(c *gin.Context) {
 
 	userData, err := h.userService.GetByID(c.Request.Context(), user.ID)
 	if err != nil {
-		response.InternalError(c, "Failed to get user profile: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -86,7 +86,7 @@ func (h *UserHandler) ChangePassword(c *gin.Context) {
 	}
 	err := h.userService.ChangePassword(c.Request.Context(), user.ID, svcReq)
 	if err != nil {
-		response.BadRequest(c, "Failed to change password: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 
@@ -120,7 +120,7 @@ func (h *UserHandler) UpdateProfile(c *gin.Context) {
 	}
 	updatedUser, err := h.userService.UpdateProfile(c.Request.Context(), user.ID, svcReq)
 	if err != nil {
-		response.BadRequest(c, "Failed to update profile: "+err.Error())
+		response.ErrorFrom(c, err)
 		return
 	}
 

backend/internal/handler/wire.go

@@ -1,8 +1,8 @@
 package handler
 
 import (
-	"sub2api/internal/handler/admin"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/handler/admin"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/google/wire"
 )

backend/internal/infrastructure/database.go

@@ -1,9 +1,9 @@
 package infrastructure
 
 import (
-	"sub2api/internal/config"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
 
 	"gorm.io/driver/postgres"
 	"gorm.io/gorm"

backend/internal/infrastructure/errors/errors.go

@@ -0,0 +1,158 @@
+package errors
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+)
+
+const (
+	UnknownCode    = http.StatusInternalServerError
+	UnknownReason  = ""
+	UnknownMessage = "internal error"
+)
+
+type Status struct {
+	Code     int32             `json:"code"`
+	Reason   string            `json:"reason,omitempty"`
+	Message  string            `json:"message"`
+	Metadata map[string]string `json:"metadata,omitempty"`
+}
+
+// ApplicationError is the standard error type used to control HTTP responses.
+//
+// Code is expected to be an HTTP status code (e.g. 400/401/403/404/409/500).
+type ApplicationError struct {
+	Status
+	cause error
+}
+
+// Error is kept for backwards compatibility within this package.
+type Error = ApplicationError
+
+func (e *ApplicationError) Error() string {
+	if e == nil {
+		return "<nil>"
+	}
+	if e.cause == nil {
+		return fmt.Sprintf("error: code=%d reason=%q message=%q metadata=%v", e.Code, e.Reason, e.Message, e.Metadata)
+	}
+	return fmt.Sprintf("error: code=%d reason=%q message=%q metadata=%v cause=%v", e.Code, e.Reason, e.Message, e.Metadata, e.cause)
+}
+
+// Unwrap provides compatibility for Go 1.13 error chains.
+func (e *ApplicationError) Unwrap() error { return e.cause }
+
+// Is matches each error in the chain with the target value.
+func (e *ApplicationError) Is(err error) bool {
+	if se := new(ApplicationError); errors.As(err, &se) {
+		return se.Code == e.Code && se.Reason == e.Reason
+	}
+	return false
+}
+
+// WithCause attaches the underlying cause of the error.
+func (e *ApplicationError) WithCause(cause error) *ApplicationError {
+	err := Clone(e)
+	err.cause = cause
+	return err
+}
+
+// WithMetadata deep-copies the given metadata map.
+func (e *ApplicationError) WithMetadata(md map[string]string) *ApplicationError {
+	err := Clone(e)
+	if md == nil {
+		err.Metadata = nil
+		return err
+	}
+	err.Metadata = make(map[string]string, len(md))
+	for k, v := range md {
+		err.Metadata[k] = v
+	}
+	return err
+}
+
+// New returns an error object for the code, message.
+func New(code int, reason, message string) *ApplicationError {
+	return &ApplicationError{
+		Status: Status{
+			Code:    int32(code),
+			Message: message,
+			Reason:  reason,
+		},
+	}
+}
+
+// Newf New(code fmt.Sprintf(format, a...))
+func Newf(code int, reason, format string, a ...any) *ApplicationError {
+	return New(code, reason, fmt.Sprintf(format, a...))
+}
+
+// Errorf returns an error object for the code, message and error info.
+func Errorf(code int, reason, format string, a ...any) error {
+	return New(code, reason, fmt.Sprintf(format, a...))
+}
+
+// Code returns the http code for an error.
+// It supports wrapped errors.
+func Code(err error) int {
+	if err == nil {
+		return http.StatusOK
+	}
+	return int(FromError(err).Code)
+}
+
+// Reason returns the reason for a particular error.
+// It supports wrapped errors.
+func Reason(err error) string {
+	if err == nil {
+		return UnknownReason
+	}
+	return FromError(err).Reason
+}
+
+// Message returns the message for a particular error.
+// It supports wrapped errors.
+func Message(err error) string {
+	if err == nil {
+		return ""
+	}
+	return FromError(err).Message
+}
+
+// Clone deep clone error to a new error.
+func Clone(err *ApplicationError) *ApplicationError {
+	if err == nil {
+		return nil
+	}
+	var metadata map[string]string
+	if err.Metadata != nil {
+		metadata = make(map[string]string, len(err.Metadata))
+		for k, v := range err.Metadata {
+			metadata[k] = v
+		}
+	}
+	return &ApplicationError{
+		cause: err.cause,
+		Status: Status{
+			Code:     err.Code,
+			Reason:   err.Reason,
+			Message:  err.Message,
+			Metadata: metadata,
+		},
+	}
+}
+
+// FromError tries to convert an error to *ApplicationError.
+// It supports wrapped errors.
+func FromError(err error) *ApplicationError {
+	if err == nil {
+		return nil
+	}
+	if se := new(ApplicationError); errors.As(err, &se) {
+		return se
+	}
+
+	// Fall back to a generic internal error.
+	return New(UnknownCode, UnknownReason, UnknownMessage).WithCause(err)
+}

backend/internal/infrastructure/errors/errors_test.go

@@ -0,0 +1,168 @@
+//go:build unit
+
+package errors
+
+import (
+	stderrors "errors"
+	"fmt"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestApplicationError_Basics(t *testing.T) {
+	tests := []struct {
+		name    string
+		err     *ApplicationError
+		want    Status
+		wantIs  bool
+		target  error
+		wrapped error
+	}{
+		{
+			name: "new",
+			err:  New(400, "BAD_REQUEST", "invalid input"),
+			want: Status{
+				Code:    400,
+				Reason:  "BAD_REQUEST",
+				Message: "invalid input",
+			},
+		},
+		{
+			name:   "is_matches_code_and_reason",
+			err:    New(401, "UNAUTHORIZED", "nope"),
+			want:   Status{Code: 401, Reason: "UNAUTHORIZED", Message: "nope"},
+			target: New(401, "UNAUTHORIZED", "ignored message"),
+			wantIs: true,
+		},
+		{
+			name:   "is_does_not_match_reason",
+			err:    New(401, "UNAUTHORIZED", "nope"),
+			want:   Status{Code: 401, Reason: "UNAUTHORIZED", Message: "nope"},
+			target: New(401, "DIFFERENT", "ignored message"),
+			wantIs: false,
+		},
+		{
+			name:    "from_error_unwraps_wrapped_application_error",
+			err:     New(404, "NOT_FOUND", "missing"),
+			wrapped: fmt.Errorf("wrap: %w", New(404, "NOT_FOUND", "missing")),
+			want: Status{
+				Code:    404,
+				Reason:  "NOT_FOUND",
+				Message: "missing",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.err != nil {
+				require.Equal(t, tt.want, tt.err.Status)
+			}
+
+			if tt.target != nil {
+				require.Equal(t, tt.wantIs, stderrors.Is(tt.err, tt.target))
+			}
+
+			if tt.wrapped != nil {
+				got := FromError(tt.wrapped)
+				require.Equal(t, tt.want, got.Status)
+			}
+		})
+	}
+}
+
+func TestApplicationError_WithMetadataDeepCopy(t *testing.T) {
+	tests := []struct {
+		name string
+		md   map[string]string
+	}{
+		{name: "non_nil", md: map[string]string{"a": "1"}},
+		{name: "nil", md: nil},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			appErr := BadRequest("BAD_REQUEST", "invalid input").WithMetadata(tt.md)
+
+			if tt.md == nil {
+				require.Nil(t, appErr.Metadata)
+				return
+			}
+
+			tt.md["a"] = "changed"
+			require.Equal(t, "1", appErr.Metadata["a"])
+		})
+	}
+}
+
+func TestFromError_Generic(t *testing.T) {
+	tests := []struct {
+		name       string
+		err        error
+		wantCode   int32
+		wantReason string
+		wantMsg    string
+	}{
+		{
+			name:       "plain_error",
+			err:        stderrors.New("boom"),
+			wantCode:   UnknownCode,
+			wantReason: UnknownReason,
+			wantMsg:    UnknownMessage,
+		},
+		{
+			name:       "wrapped_plain_error",
+			err:        fmt.Errorf("wrap: %w", io.EOF),
+			wantCode:   UnknownCode,
+			wantReason: UnknownReason,
+			wantMsg:    UnknownMessage,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := FromError(tt.err)
+			require.Equal(t, tt.wantCode, got.Code)
+			require.Equal(t, tt.wantReason, got.Reason)
+			require.Equal(t, tt.wantMsg, got.Message)
+			require.Equal(t, tt.err, got.Unwrap())
+		})
+	}
+}
+
+func TestToHTTP(t *testing.T) {
+	tests := []struct {
+		name           string
+		err            error
+		wantStatusCode int
+		wantBody       Status
+	}{
+		{
+			name:           "nil_error",
+			err:            nil,
+			wantStatusCode: http.StatusOK,
+			wantBody:       Status{Code: int32(http.StatusOK)},
+		},
+		{
+			name:           "application_error",
+			err:            Forbidden("FORBIDDEN", "no access"),
+			wantStatusCode: http.StatusForbidden,
+			wantBody: Status{
+				Code:    int32(http.StatusForbidden),
+				Reason:  "FORBIDDEN",
+				Message: "no access",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			code, body := ToHTTP(tt.err)
+			require.Equal(t, tt.wantStatusCode, code)
+			require.Equal(t, tt.wantBody, body)
+		})
+	}
+}

backend/internal/infrastructure/errors/http.go

@@ -0,0 +1,21 @@
+package errors
+
+import "net/http"
+
+// ToHTTP converts an error into an HTTP status code and a JSON-serializable body.
+//
+// The returned body matches the project's Status shape:
+// { code, reason, message, metadata }.
+func ToHTTP(err error) (statusCode int, body Status) {
+	if err == nil {
+		return http.StatusOK, Status{Code: int32(http.StatusOK)}
+	}
+
+	appErr := FromError(err)
+	if appErr == nil {
+		return http.StatusOK, Status{Code: int32(http.StatusOK)}
+	}
+
+	cloned := Clone(appErr)
+	return int(cloned.Code), cloned.Status
+}

backend/internal/infrastructure/errors/types.go

@@ -0,0 +1,114 @@
+// nolint:mnd
+package errors
+
+import "net/http"
+
+// BadRequest new BadRequest error that is mapped to a 400 response.
+func BadRequest(reason, message string) *ApplicationError {
+	return New(http.StatusBadRequest, reason, message)
+}
+
+// IsBadRequest determines if err is an error which indicates a BadRequest error.
+// It supports wrapped errors.
+func IsBadRequest(err error) bool {
+	return Code(err) == http.StatusBadRequest
+}
+
+// TooManyRequests new TooManyRequests error that is mapped to a 429 response.
+func TooManyRequests(reason, message string) *ApplicationError {
+	return New(http.StatusTooManyRequests, reason, message)
+}
+
+// IsTooManyRequests determines if err is an error which indicates a TooManyRequests error.
+// It supports wrapped errors.
+func IsTooManyRequests(err error) bool {
+	return Code(err) == http.StatusTooManyRequests
+}
+
+// Unauthorized new Unauthorized error that is mapped to a 401 response.
+func Unauthorized(reason, message string) *ApplicationError {
+	return New(http.StatusUnauthorized, reason, message)
+}
+
+// IsUnauthorized determines if err is an error which indicates an Unauthorized error.
+// It supports wrapped errors.
+func IsUnauthorized(err error) bool {
+	return Code(err) == http.StatusUnauthorized
+}
+
+// Forbidden new Forbidden error that is mapped to a 403 response.
+func Forbidden(reason, message string) *ApplicationError {
+	return New(http.StatusForbidden, reason, message)
+}
+
+// IsForbidden determines if err is an error which indicates a Forbidden error.
+// It supports wrapped errors.
+func IsForbidden(err error) bool {
+	return Code(err) == http.StatusForbidden
+}
+
+// NotFound new NotFound error that is mapped to a 404 response.
+func NotFound(reason, message string) *ApplicationError {
+	return New(http.StatusNotFound, reason, message)
+}
+
+// IsNotFound determines if err is an error which indicates an NotFound error.
+// It supports wrapped errors.
+func IsNotFound(err error) bool {
+	return Code(err) == http.StatusNotFound
+}
+
+// Conflict new Conflict error that is mapped to a 409 response.
+func Conflict(reason, message string) *ApplicationError {
+	return New(http.StatusConflict, reason, message)
+}
+
+// IsConflict determines if err is an error which indicates a Conflict error.
+// It supports wrapped errors.
+func IsConflict(err error) bool {
+	return Code(err) == http.StatusConflict
+}
+
+// InternalServer new InternalServer error that is mapped to a 500 response.
+func InternalServer(reason, message string) *ApplicationError {
+	return New(http.StatusInternalServerError, reason, message)
+}
+
+// IsInternalServer determines if err is an error which indicates an Internal error.
+// It supports wrapped errors.
+func IsInternalServer(err error) bool {
+	return Code(err) == http.StatusInternalServerError
+}
+
+// ServiceUnavailable new ServiceUnavailable error that is mapped to an HTTP 503 response.
+func ServiceUnavailable(reason, message string) *ApplicationError {
+	return New(http.StatusServiceUnavailable, reason, message)
+}
+
+// IsServiceUnavailable determines if err is an error which indicates an Unavailable error.
+// It supports wrapped errors.
+func IsServiceUnavailable(err error) bool {
+	return Code(err) == http.StatusServiceUnavailable
+}
+
+// GatewayTimeout new GatewayTimeout error that is mapped to an HTTP 504 response.
+func GatewayTimeout(reason, message string) *ApplicationError {
+	return New(http.StatusGatewayTimeout, reason, message)
+}
+
+// IsGatewayTimeout determines if err is an error which indicates a GatewayTimeout error.
+// It supports wrapped errors.
+func IsGatewayTimeout(err error) bool {
+	return Code(err) == http.StatusGatewayTimeout
+}
+
+// ClientClosed new ClientClosed error that is mapped to an HTTP 499 response.
+func ClientClosed(reason, message string) *ApplicationError {
+	return New(499, reason, message)
+}
+
+// IsClientClosed determines if err is an error which indicates a IsClientClosed error.
+// It supports wrapped errors.
+func IsClientClosed(err error) bool {
+	return Code(err) == 499
+}

backend/internal/infrastructure/redis.go

@@ -1,7 +1,7 @@
 package infrastructure
 
 import (
-	"sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/config"
 
 	"github.com/redis/go-redis/v9"
 )

backend/internal/infrastructure/wire.go

@@ -1,7 +1,7 @@
 package infrastructure
 
 import (
-	"sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/config"
 
 	"github.com/google/wire"
 	"github.com/redis/go-redis/v9"

backend/internal/model/redeem_code.go

@@ -14,6 +14,7 @@ type RedeemCode struct {
 	Status    string     `gorm:"size:20;default:unused;not null" json:"status"` // unused/used
 	UsedBy    *int64     `gorm:"index" json:"used_by"`
 	UsedAt    *time.Time `json:"used_at"`
+	Notes     string     `gorm:"type:text" json:"notes"`
 	CreatedAt time.Time  `gorm:"not null" json:"created_at"`
 
 	// 订阅类型专用字段

backend/internal/model/setting.go

@@ -42,6 +42,7 @@ const (
 	SettingKeySiteSubtitle = "site_subtitle" // 网站副标题
 	SettingKeyApiBaseUrl   = "api_base_url"  // API端点地址（用于客户端配置和导入）
 	SettingKeyContactInfo  = "contact_info"  // 客服联系方式
+	SettingKeyDocUrl       = "doc_url"       // 文档链接
 
 	// 默认配置
 	SettingKeyDefaultConcurrency = "default_concurrency" // 新用户默认并发量
@@ -80,6 +81,7 @@ type SystemSettings struct {
 	SiteSubtitle string `json:"site_subtitle"`
 	ApiBaseUrl   string `json:"api_base_url"`
 	ContactInfo  string `json:"contact_info"`
+	DocUrl       string `json:"doc_url"`
 
 	// 默认配置
 	DefaultConcurrency int     `json:"default_concurrency"`
@@ -97,5 +99,6 @@ type PublicSettings struct {
 	SiteSubtitle        string `json:"site_subtitle"`
 	ApiBaseUrl          string `json:"api_base_url"`
 	ContactInfo         string `json:"contact_info"`
+	DocUrl              string `json:"doc_url"`
 	Version             string `json:"version"`
 }

backend/internal/pkg/response/response.go

@@ -4,14 +4,17 @@ import (
 	"math"
 	"net/http"
 
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
 	"github.com/gin-gonic/gin"
 )
 
 // Response 标准API响应格式
 type Response struct {
-	Code    int    `json:"code"`
-	Message string `json:"message"`
-	Data    any    `json:"data,omitempty"`
+	Code     int               `json:"code"`
+	Message  string            `json:"message"`
+	Reason   string            `json:"reason,omitempty"`
+	Metadata map[string]string `json:"metadata,omitempty"`
+	Data     any               `json:"data,omitempty"`
 }
 
 // PaginatedData 分页数据格式（匹配前端期望）
@@ -44,11 +47,36 @@ func Created(c *gin.Context, data any) {
 // Error 返回错误响应
 func Error(c *gin.Context, statusCode int, message string) {
 	c.JSON(statusCode, Response{
-		Code:    statusCode,
-		Message: message,
+		Code:     statusCode,
+		Message:  message,
+		Reason:   "",
+		Metadata: nil,
 	})
 }
 
+// ErrorWithDetails returns an error response compatible with the existing envelope while
+// optionally providing structured error fields (reason/metadata).
+func ErrorWithDetails(c *gin.Context, statusCode int, message, reason string, metadata map[string]string) {
+	c.JSON(statusCode, Response{
+		Code:     statusCode,
+		Message:  message,
+		Reason:   reason,
+		Metadata: metadata,
+	})
+}
+
+// ErrorFrom converts an ApplicationError (or any error) into the envelope-compatible error response.
+// It returns true if an error was written.
+func ErrorFrom(c *gin.Context, err error) bool {
+	if err == nil {
+		return false
+	}
+
+	statusCode, status := infraerrors.ToHTTP(err)
+	ErrorWithDetails(c, statusCode, status.Message, status.Reason, status.Metadata)
+	return true
+}
+
 // BadRequest 返回400错误
 func BadRequest(c *gin.Context, message string) {
 	Error(c, http.StatusBadRequest, message)

backend/internal/pkg/response/response_test.go

@@ -0,0 +1,171 @@
+//go:build unit
+
+package response
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestErrorWithDetails(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	tests := []struct {
+		name       string
+		statusCode int
+		message    string
+		reason     string
+		metadata   map[string]string
+		want       Response
+	}{
+		{
+			name:       "plain_error",
+			statusCode: http.StatusBadRequest,
+			message:    "invalid request",
+			want: Response{
+				Code:    http.StatusBadRequest,
+				Message: "invalid request",
+			},
+		},
+		{
+			name:       "structured_error",
+			statusCode: http.StatusForbidden,
+			message:    "no access",
+			reason:     "FORBIDDEN",
+			metadata:   map[string]string{"k": "v"},
+			want: Response{
+				Code:     http.StatusForbidden,
+				Message:  "no access",
+				Reason:   "FORBIDDEN",
+				Metadata: map[string]string{"k": "v"},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			c, _ := gin.CreateTestContext(w)
+
+			ErrorWithDetails(c, tt.statusCode, tt.message, tt.reason, tt.metadata)
+
+			require.Equal(t, tt.statusCode, w.Code)
+
+			var got Response
+			require.NoError(t, json.Unmarshal(w.Body.Bytes(), &got))
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestErrorFrom(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	tests := []struct {
+		name         string
+		err          error
+		wantWritten  bool
+		wantHTTPCode int
+		wantBody     Response
+	}{
+		{
+			name:        "nil_error",
+			err:         nil,
+			wantWritten: false,
+		},
+		{
+			name:         "application_error",
+			err:          infraerrors.Forbidden("FORBIDDEN", "no access").WithMetadata(map[string]string{"scope": "admin"}),
+			wantWritten:  true,
+			wantHTTPCode: http.StatusForbidden,
+			wantBody: Response{
+				Code:     http.StatusForbidden,
+				Message:  "no access",
+				Reason:   "FORBIDDEN",
+				Metadata: map[string]string{"scope": "admin"},
+			},
+		},
+		{
+			name:         "bad_request_error",
+			err:          infraerrors.BadRequest("INVALID_REQUEST", "invalid request"),
+			wantWritten:  true,
+			wantHTTPCode: http.StatusBadRequest,
+			wantBody: Response{
+				Code:    http.StatusBadRequest,
+				Message: "invalid request",
+				Reason:  "INVALID_REQUEST",
+			},
+		},
+		{
+			name:         "unauthorized_error",
+			err:          infraerrors.Unauthorized("UNAUTHORIZED", "unauthorized"),
+			wantWritten:  true,
+			wantHTTPCode: http.StatusUnauthorized,
+			wantBody: Response{
+				Code:    http.StatusUnauthorized,
+				Message: "unauthorized",
+				Reason:  "UNAUTHORIZED",
+			},
+		},
+		{
+			name:         "not_found_error",
+			err:          infraerrors.NotFound("NOT_FOUND", "not found"),
+			wantWritten:  true,
+			wantHTTPCode: http.StatusNotFound,
+			wantBody: Response{
+				Code:    http.StatusNotFound,
+				Message: "not found",
+				Reason:  "NOT_FOUND",
+			},
+		},
+		{
+			name:         "conflict_error",
+			err:          infraerrors.Conflict("CONFLICT", "conflict"),
+			wantWritten:  true,
+			wantHTTPCode: http.StatusConflict,
+			wantBody: Response{
+				Code:    http.StatusConflict,
+				Message: "conflict",
+				Reason:  "CONFLICT",
+			},
+		},
+		{
+			name:         "unknown_error_defaults_to_500",
+			err:          errors.New("boom"),
+			wantWritten:  true,
+			wantHTTPCode: http.StatusInternalServerError,
+			wantBody: Response{
+				Code:    http.StatusInternalServerError,
+				Message: infraerrors.UnknownMessage,
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			c, _ := gin.CreateTestContext(w)
+
+			written := ErrorFrom(c, tt.err)
+			require.Equal(t, tt.wantWritten, written)
+
+			if !tt.wantWritten {
+				require.Equal(t, 200, w.Code)
+				require.Empty(t, w.Body.String())
+				return
+			}
+
+			require.Equal(t, tt.wantHTTPCode, w.Code)
+			var got Response
+			require.NoError(t, json.Unmarshal(w.Body.Bytes(), &got))
+			require.Equal(t, tt.wantBody, got)
+		})
+	}
+}

backend/internal/pkg/usagestats/usage_log_types.go

@@ -0,0 +1,209 @@
+package usagestats
+
+import "time"
+
+// DashboardStats 仪表盘统计
+type DashboardStats struct {
+	// 用户统计
+	TotalUsers    int64 `json:"total_users"`
+	TodayNewUsers int64 `json:"today_new_users"` // 今日新增用户数
+	ActiveUsers   int64 `json:"active_users"`    // 今日有请求的用户数
+
+	// API Key 统计
+	TotalApiKeys  int64 `json:"total_api_keys"`
+	ActiveApiKeys int64 `json:"active_api_keys"` // 状态为 active 的 API Key 数
+
+	// 账户统计
+	TotalAccounts     int64 `json:"total_accounts"`
+	NormalAccounts    int64 `json:"normal_accounts"`    // 正常账户数 (schedulable=true, status=active)
+	ErrorAccounts     int64 `json:"error_accounts"`     // 异常账户数 (status=error)
+	RateLimitAccounts int64 `json:"ratelimit_accounts"` // 限流账户数
+	OverloadAccounts  int64 `json:"overload_accounts"`  // 过载账户数
+
+	// 累计 Token 使用统计
+	TotalRequests            int64   `json:"total_requests"`
+	TotalInputTokens         int64   `json:"total_input_tokens"`
+	TotalOutputTokens        int64   `json:"total_output_tokens"`
+	TotalCacheCreationTokens int64   `json:"total_cache_creation_tokens"`
+	TotalCacheReadTokens     int64   `json:"total_cache_read_tokens"`
+	TotalTokens              int64   `json:"total_tokens"`
+	TotalCost                float64 `json:"total_cost"`        // 累计标准计费
+	TotalActualCost          float64 `json:"total_actual_cost"` // 累计实际扣除
+
+	// 今日 Token 使用统计
+	TodayRequests            int64   `json:"today_requests"`
+	TodayInputTokens         int64   `json:"today_input_tokens"`
+	TodayOutputTokens        int64   `json:"today_output_tokens"`
+	TodayCacheCreationTokens int64   `json:"today_cache_creation_tokens"`
+	TodayCacheReadTokens     int64   `json:"today_cache_read_tokens"`
+	TodayTokens              int64   `json:"today_tokens"`
+	TodayCost                float64 `json:"today_cost"`        // 今日标准计费
+	TodayActualCost          float64 `json:"today_actual_cost"` // 今日实际扣除
+
+	// 系统运行统计
+	AverageDurationMs float64 `json:"average_duration_ms"` // 平均响应时间
+
+	// 性能指标
+	Rpm int64 `json:"rpm"` // 近5分钟平均每分钟请求数
+	Tpm int64 `json:"tpm"` // 近5分钟平均每分钟Token数
+}
+
+// TrendDataPoint represents a single point in trend data
+type TrendDataPoint struct {
+	Date         string  `json:"date"`
+	Requests     int64   `json:"requests"`
+	InputTokens  int64   `json:"input_tokens"`
+	OutputTokens int64   `json:"output_tokens"`
+	CacheTokens  int64   `json:"cache_tokens"`
+	TotalTokens  int64   `json:"total_tokens"`
+	Cost         float64 `json:"cost"`        // 标准计费
+	ActualCost   float64 `json:"actual_cost"` // 实际扣除
+}
+
+// ModelStat represents usage statistics for a single model
+type ModelStat struct {
+	Model        string  `json:"model"`
+	Requests     int64   `json:"requests"`
+	InputTokens  int64   `json:"input_tokens"`
+	OutputTokens int64   `json:"output_tokens"`
+	TotalTokens  int64   `json:"total_tokens"`
+	Cost         float64 `json:"cost"`        // 标准计费
+	ActualCost   float64 `json:"actual_cost"` // 实际扣除
+}
+
+// UserUsageTrendPoint represents user usage trend data point
+type UserUsageTrendPoint struct {
+	Date       string  `json:"date"`
+	UserID     int64   `json:"user_id"`
+	Email      string  `json:"email"`
+	Requests   int64   `json:"requests"`
+	Tokens     int64   `json:"tokens"`
+	Cost       float64 `json:"cost"`        // 标准计费
+	ActualCost float64 `json:"actual_cost"` // 实际扣除
+}
+
+// ApiKeyUsageTrendPoint represents API key usage trend data point
+type ApiKeyUsageTrendPoint struct {
+	Date     string `json:"date"`
+	ApiKeyID int64  `json:"api_key_id"`
+	KeyName  string `json:"key_name"`
+	Requests int64  `json:"requests"`
+	Tokens   int64  `json:"tokens"`
+}
+
+// UserDashboardStats 用户仪表盘统计
+type UserDashboardStats struct {
+	// API Key 统计
+	TotalApiKeys  int64 `json:"total_api_keys"`
+	ActiveApiKeys int64 `json:"active_api_keys"`
+
+	// 累计 Token 使用统计
+	TotalRequests            int64   `json:"total_requests"`
+	TotalInputTokens         int64   `json:"total_input_tokens"`
+	TotalOutputTokens        int64   `json:"total_output_tokens"`
+	TotalCacheCreationTokens int64   `json:"total_cache_creation_tokens"`
+	TotalCacheReadTokens     int64   `json:"total_cache_read_tokens"`
+	TotalTokens              int64   `json:"total_tokens"`
+	TotalCost                float64 `json:"total_cost"`        // 累计标准计费
+	TotalActualCost          float64 `json:"total_actual_cost"` // 累计实际扣除
+
+	// 今日 Token 使用统计
+	TodayRequests            int64   `json:"today_requests"`
+	TodayInputTokens         int64   `json:"today_input_tokens"`
+	TodayOutputTokens        int64   `json:"today_output_tokens"`
+	TodayCacheCreationTokens int64   `json:"today_cache_creation_tokens"`
+	TodayCacheReadTokens     int64   `json:"today_cache_read_tokens"`
+	TodayTokens              int64   `json:"today_tokens"`
+	TodayCost                float64 `json:"today_cost"`        // 今日标准计费
+	TodayActualCost          float64 `json:"today_actual_cost"` // 今日实际扣除
+
+	// 性能统计
+	AverageDurationMs float64 `json:"average_duration_ms"`
+
+	// 性能指标
+	Rpm int64 `json:"rpm"` // 近5分钟平均每分钟请求数
+	Tpm int64 `json:"tpm"` // 近5分钟平均每分钟Token数
+}
+
+// UsageLogFilters represents filters for usage log queries
+type UsageLogFilters struct {
+	UserID    int64
+	ApiKeyID  int64
+	StartTime *time.Time
+	EndTime   *time.Time
+}
+
+// UsageStats represents usage statistics
+type UsageStats struct {
+	TotalRequests     int64   `json:"total_requests"`
+	TotalInputTokens  int64   `json:"total_input_tokens"`
+	TotalOutputTokens int64   `json:"total_output_tokens"`
+	TotalCacheTokens  int64   `json:"total_cache_tokens"`
+	TotalTokens       int64   `json:"total_tokens"`
+	TotalCost         float64 `json:"total_cost"`
+	TotalActualCost   float64 `json:"total_actual_cost"`
+	AverageDurationMs float64 `json:"average_duration_ms"`
+}
+
+// BatchUserUsageStats represents usage stats for a single user
+type BatchUserUsageStats struct {
+	UserID          int64   `json:"user_id"`
+	TodayActualCost float64 `json:"today_actual_cost"`
+	TotalActualCost float64 `json:"total_actual_cost"`
+}
+
+// BatchApiKeyUsageStats represents usage stats for a single API key
+type BatchApiKeyUsageStats struct {
+	ApiKeyID        int64   `json:"api_key_id"`
+	TodayActualCost float64 `json:"today_actual_cost"`
+	TotalActualCost float64 `json:"total_actual_cost"`
+}
+
+// AccountUsageHistory represents daily usage history for an account
+type AccountUsageHistory struct {
+	Date       string  `json:"date"`
+	Label      string  `json:"label"`
+	Requests   int64   `json:"requests"`
+	Tokens     int64   `json:"tokens"`
+	Cost       float64 `json:"cost"`
+	ActualCost float64 `json:"actual_cost"`
+}
+
+// AccountUsageSummary represents summary statistics for an account
+type AccountUsageSummary struct {
+	Days              int     `json:"days"`
+	ActualDaysUsed    int     `json:"actual_days_used"`
+	TotalCost         float64 `json:"total_cost"`
+	TotalStandardCost float64 `json:"total_standard_cost"`
+	TotalRequests     int64   `json:"total_requests"`
+	TotalTokens       int64   `json:"total_tokens"`
+	AvgDailyCost      float64 `json:"avg_daily_cost"`
+	AvgDailyRequests  float64 `json:"avg_daily_requests"`
+	AvgDailyTokens    float64 `json:"avg_daily_tokens"`
+	AvgDurationMs     float64 `json:"avg_duration_ms"`
+	Today             *struct {
+		Date     string  `json:"date"`
+		Cost     float64 `json:"cost"`
+		Requests int64   `json:"requests"`
+		Tokens   int64   `json:"tokens"`
+	} `json:"today"`
+	HighestCostDay *struct {
+		Date     string  `json:"date"`
+		Label    string  `json:"label"`
+		Cost     float64 `json:"cost"`
+		Requests int64   `json:"requests"`
+	} `json:"highest_cost_day"`
+	HighestRequestDay *struct {
+		Date     string  `json:"date"`
+		Label    string  `json:"label"`
+		Requests int64   `json:"requests"`
+		Cost     float64 `json:"cost"`
+	} `json:"highest_request_day"`
+}
+
+// AccountUsageStatsResponse represents the full usage statistics response for an account
+type AccountUsageStatsResponse struct {
+	History []AccountUsageHistory `json:"history"`
+	Summary AccountUsageSummary   `json:"summary"`
+	Models  []ModelStat           `json:"models"`
+}

backend/internal/repository/account_repo.go

@@ -2,44 +2,68 @@ package repository
 
 import (
 	"context"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
+	"errors"
 	"time"
 
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 )
 
-type AccountRepository struct {
+type accountRepository struct {
 	db *gorm.DB
 }
 
-func NewAccountRepository(db *gorm.DB) *AccountRepository {
-	return &AccountRepository{db: db}
+func NewAccountRepository(db *gorm.DB) service.AccountRepository {
+	return &accountRepository{db: db}
 }
 
-func (r *AccountRepository) Create(ctx context.Context, account *model.Account) error {
+func (r *accountRepository) Create(ctx context.Context, account *model.Account) error {
 	return r.db.WithContext(ctx).Create(account).Error
 }
 
-func (r *AccountRepository) GetByID(ctx context.Context, id int64) (*model.Account, error) {
+func (r *accountRepository) GetByID(ctx context.Context, id int64) (*model.Account, error) {
 	var account model.Account
-	err := r.db.WithContext(ctx).Preload("Proxy").Preload("AccountGroups").First(&account, id).Error
+	err := r.db.WithContext(ctx).Preload("Proxy").Preload("AccountGroups.Group").First(&account, id).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrAccountNotFound, nil)
 	}
-	// 填充 GroupIDs 虚拟字段
+	// 填充 GroupIDs 和 Groups 虚拟字段
 	account.GroupIDs = make([]int64, 0, len(account.AccountGroups))
+	account.Groups = make([]*model.Group, 0, len(account.AccountGroups))
 	for _, ag := range account.AccountGroups {
 		account.GroupIDs = append(account.GroupIDs, ag.GroupID)
+		if ag.Group != nil {
+			account.Groups = append(account.Groups, ag.Group)
+		}
 	}
 	return &account, nil
 }
 
-func (r *AccountRepository) Update(ctx context.Context, account *model.Account) error {
+func (r *accountRepository) GetByCRSAccountID(ctx context.Context, crsAccountID string) (*model.Account, error) {
+	if crsAccountID == "" {
+		return nil, nil
+	}
+
+	var account model.Account
+	err := r.db.WithContext(ctx).Where("extra->>'crs_account_id' = ?", crsAccountID).First(&account).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return &account, nil
+}
+
+func (r *accountRepository) Update(ctx context.Context, account *model.Account) error {
 	return r.db.WithContext(ctx).Save(account).Error
 }
 
-func (r *AccountRepository) Delete(ctx context.Context, id int64) error {
+func (r *accountRepository) Delete(ctx context.Context, id int64) error {
 	// 先删除账号与分组的绑定关系
 	if err := r.db.WithContext(ctx).Where("account_id = ?", id).Delete(&model.AccountGroup{}).Error; err != nil {
 		return err
@@ -48,12 +72,12 @@ func (r *AccountRepository) Delete(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Delete(&model.Account{}, id).Error
 }
 
-func (r *AccountRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.Account, *pagination.PaginationResult, error) {
+func (r *accountRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.Account, *pagination.PaginationResult, error) {
 	return r.ListWithFilters(ctx, params, "", "", "", "")
 }
 
 // ListWithFilters lists accounts with optional filtering by platform, type, status, and search query
-func (r *AccountRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, platform, accountType, status, search string) ([]model.Account, *pagination.PaginationResult, error) {
+func (r *accountRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, platform, accountType, status, search string) ([]model.Account, *pagination.PaginationResult, error) {
 	var accounts []model.Account
 	var total int64
 
@@ -107,7 +131,7 @@ func (r *AccountRepository) ListWithFilters(ctx context.Context, params paginati
 	}, nil
 }
 
-func (r *AccountRepository) ListByGroup(ctx context.Context, groupID int64) ([]model.Account, error) {
+func (r *accountRepository) ListByGroup(ctx context.Context, groupID int64) ([]model.Account, error) {
 	var accounts []model.Account
 	err := r.db.WithContext(ctx).
 		Joins("JOIN account_groups ON account_groups.account_id = accounts.id").
@@ -118,7 +142,7 @@ func (r *AccountRepository) ListByGroup(ctx context.Context, groupID int64) ([]m
 	return accounts, err
 }
 
-func (r *AccountRepository) ListActive(ctx context.Context) ([]model.Account, error) {
+func (r *accountRepository) ListActive(ctx context.Context) ([]model.Account, error) {
 	var accounts []model.Account
 	err := r.db.WithContext(ctx).
 		Where("status = ?", model.StatusActive).
@@ -128,12 +152,12 @@ func (r *AccountRepository) ListActive(ctx context.Context) ([]model.Account, er
 	return accounts, err
 }
 
-func (r *AccountRepository) UpdateLastUsed(ctx context.Context, id int64) error {
+func (r *accountRepository) UpdateLastUsed(ctx context.Context, id int64) error {
 	now := time.Now()
 	return r.db.WithContext(ctx).Model(&model.Account{}).Where("id = ?", id).Update("last_used_at", now).Error
 }
 
-func (r *AccountRepository) SetError(ctx context.Context, id int64, errorMsg string) error {
+func (r *accountRepository) SetError(ctx context.Context, id int64, errorMsg string) error {
 	return r.db.WithContext(ctx).Model(&model.Account{}).Where("id = ?", id).
 		Updates(map[string]any{
 			"status":        model.StatusError,
@@ -141,7 +165,7 @@ func (r *AccountRepository) SetError(ctx context.Context, id int64, errorMsg str
 		}).Error
 }
 
-func (r *AccountRepository) AddToGroup(ctx context.Context, accountID, groupID int64, priority int) error {
+func (r *accountRepository) AddToGroup(ctx context.Context, accountID, groupID int64, priority int) error {
 	ag := &model.AccountGroup{
 		AccountID: accountID,
 		GroupID:   groupID,
@@ -150,12 +174,12 @@ func (r *AccountRepository) AddToGroup(ctx context.Context, accountID, groupID i
 	return r.db.WithContext(ctx).Create(ag).Error
 }
 
-func (r *AccountRepository) RemoveFromGroup(ctx context.Context, accountID, groupID int64) error {
+func (r *accountRepository) RemoveFromGroup(ctx context.Context, accountID, groupID int64) error {
 	return r.db.WithContext(ctx).Where("account_id = ? AND group_id = ?", accountID, groupID).
 		Delete(&model.AccountGroup{}).Error
 }
 
-func (r *AccountRepository) GetGroups(ctx context.Context, accountID int64) ([]model.Group, error) {
+func (r *accountRepository) GetGroups(ctx context.Context, accountID int64) ([]model.Group, error) {
 	var groups []model.Group
 	err := r.db.WithContext(ctx).
 		Joins("JOIN account_groups ON account_groups.group_id = groups.id").
@@ -164,7 +188,7 @@ func (r *AccountRepository) GetGroups(ctx context.Context, accountID int64) ([]m
 	return groups, err
 }
 
-func (r *AccountRepository) ListByPlatform(ctx context.Context, platform string) ([]model.Account, error) {
+func (r *accountRepository) ListByPlatform(ctx context.Context, platform string) ([]model.Account, error) {
 	var accounts []model.Account
 	err := r.db.WithContext(ctx).
 		Where("platform = ? AND status = ?", platform, model.StatusActive).
@@ -174,7 +198,7 @@ func (r *AccountRepository) ListByPlatform(ctx context.Context, platform string)
 	return accounts, err
 }
 
-func (r *AccountRepository) BindGroups(ctx context.Context, accountID int64, groupIDs []int64) error {
+func (r *accountRepository) BindGroups(ctx context.Context, accountID int64, groupIDs []int64) error {
 	// 删除现有绑定
 	if err := r.db.WithContext(ctx).Where("account_id = ?", accountID).Delete(&model.AccountGroup{}).Error; err != nil {
 		return err
@@ -197,7 +221,7 @@ func (r *AccountRepository) BindGroups(ctx context.Context, accountID int64, gro
 }
 
 // ListSchedulable 获取所有可调度的账号
-func (r *AccountRepository) ListSchedulable(ctx context.Context) ([]model.Account, error) {
+func (r *accountRepository) ListSchedulable(ctx context.Context) ([]model.Account, error) {
 	var accounts []model.Account
 	now := time.Now()
 	err := r.db.WithContext(ctx).
@@ -211,7 +235,7 @@ func (r *AccountRepository) ListSchedulable(ctx context.Context) ([]model.Accoun
 }
 
 // ListSchedulableByGroupID 按组获取可调度的账号
-func (r *AccountRepository) ListSchedulableByGroupID(ctx context.Context, groupID int64) ([]model.Account, error) {
+func (r *accountRepository) ListSchedulableByGroupID(ctx context.Context, groupID int64) ([]model.Account, error) {
 	var accounts []model.Account
 	now := time.Now()
 	err := r.db.WithContext(ctx).
@@ -227,7 +251,7 @@ func (r *AccountRepository) ListSchedulableByGroupID(ctx context.Context, groupI
 }
 
 // ListSchedulableByPlatform 按平台获取可调度的账号
-func (r *AccountRepository) ListSchedulableByPlatform(ctx context.Context, platform string) ([]model.Account, error) {
+func (r *accountRepository) ListSchedulableByPlatform(ctx context.Context, platform string) ([]model.Account, error) {
 	var accounts []model.Account
 	now := time.Now()
 	err := r.db.WithContext(ctx).
@@ -242,7 +266,7 @@ func (r *AccountRepository) ListSchedulableByPlatform(ctx context.Context, platf
 }
 
 // ListSchedulableByGroupIDAndPlatform 按组和平台获取可调度的账号
-func (r *AccountRepository) ListSchedulableByGroupIDAndPlatform(ctx context.Context, groupID int64, platform string) ([]model.Account, error) {
+func (r *accountRepository) ListSchedulableByGroupIDAndPlatform(ctx context.Context, groupID int64, platform string) ([]model.Account, error) {
 	var accounts []model.Account
 	now := time.Now()
 	err := r.db.WithContext(ctx).
@@ -259,7 +283,7 @@ func (r *AccountRepository) ListSchedulableByGroupIDAndPlatform(ctx context.Cont
 }
 
 // SetRateLimited 标记账号为限流状态(429)
-func (r *AccountRepository) SetRateLimited(ctx context.Context, id int64, resetAt time.Time) error {
+func (r *accountRepository) SetRateLimited(ctx context.Context, id int64, resetAt time.Time) error {
 	now := time.Now()
 	return r.db.WithContext(ctx).Model(&model.Account{}).Where("id = ?", id).
 		Updates(map[string]any{
@@ -269,13 +293,13 @@ func (r *AccountRepository) SetRateLimited(ctx context.Context, id int64, resetA
 }
 
 // SetOverloaded 标记账号为过载状态(529)
-func (r *AccountRepository) SetOverloaded(ctx context.Context, id int64, until time.Time) error {
+func (r *accountRepository) SetOverloaded(ctx context.Context, id int64, until time.Time) error {
 	return r.db.WithContext(ctx).Model(&model.Account{}).Where("id = ?", id).
 		Update("overload_until", until).Error
 }
 
 // ClearRateLimit 清除账号的限流状态
-func (r *AccountRepository) ClearRateLimit(ctx context.Context, id int64) error {
+func (r *accountRepository) ClearRateLimit(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Model(&model.Account{}).Where("id = ?", id).
 		Updates(map[string]any{
 			"rate_limited_at":     nil,
@@ -285,7 +309,7 @@ func (r *AccountRepository) ClearRateLimit(ctx context.Context, id int64) error
 }
 
 // UpdateSessionWindow 更新账号的5小时时间窗口信息
-func (r *AccountRepository) UpdateSessionWindow(ctx context.Context, id int64, start, end *time.Time, status string) error {
+func (r *accountRepository) UpdateSessionWindow(ctx context.Context, id int64, start, end *time.Time, status string) error {
 	updates := map[string]any{
 		"session_window_status": status,
 	}
@@ -299,7 +323,79 @@ func (r *AccountRepository) UpdateSessionWindow(ctx context.Context, id int64, s
 }
 
 // SetSchedulable 设置账号的调度开关
-func (r *AccountRepository) SetSchedulable(ctx context.Context, id int64, schedulable bool) error {
+func (r *accountRepository) SetSchedulable(ctx context.Context, id int64, schedulable bool) error {
 	return r.db.WithContext(ctx).Model(&model.Account{}).Where("id = ?", id).
 		Update("schedulable", schedulable).Error
 }
+
+// UpdateExtra updates specific fields in account's Extra JSONB field
+// It merges the updates into existing Extra data without overwriting other fields
+func (r *accountRepository) UpdateExtra(ctx context.Context, id int64, updates map[string]any) error {
+	if len(updates) == 0 {
+		return nil
+	}
+
+	// Get current account to preserve existing Extra data
+	var account model.Account
+	if err := r.db.WithContext(ctx).Select("extra").Where("id = ?", id).First(&account).Error; err != nil {
+		return err
+	}
+
+	// Initialize Extra if nil
+	if account.Extra == nil {
+		account.Extra = make(model.JSONB)
+	}
+
+	// Merge updates into existing Extra
+	for k, v := range updates {
+		account.Extra[k] = v
+	}
+
+	// Save updated Extra
+	return r.db.WithContext(ctx).Model(&model.Account{}).Where("id = ?", id).
+		Update("extra", account.Extra).Error
+}
+
+// BulkUpdate updates multiple accounts with the provided fields.
+// It merges credentials/extra JSONB fields instead of overwriting them.
+func (r *accountRepository) BulkUpdate(ctx context.Context, ids []int64, updates service.AccountBulkUpdate) (int64, error) {
+	if len(ids) == 0 {
+		return 0, nil
+	}
+
+	updateMap := map[string]any{}
+
+	if updates.Name != nil {
+		updateMap["name"] = *updates.Name
+	}
+	if updates.ProxyID != nil {
+		updateMap["proxy_id"] = updates.ProxyID
+	}
+	if updates.Concurrency != nil {
+		updateMap["concurrency"] = *updates.Concurrency
+	}
+	if updates.Priority != nil {
+		updateMap["priority"] = *updates.Priority
+	}
+	if updates.Status != nil {
+		updateMap["status"] = *updates.Status
+	}
+	if len(updates.Credentials) > 0 {
+		updateMap["credentials"] = gorm.Expr("COALESCE(credentials,'{}') || ?", updates.Credentials)
+	}
+	if len(updates.Extra) > 0 {
+		updateMap["extra"] = gorm.Expr("COALESCE(extra,'{}') || ?", updates.Extra)
+	}
+
+	if len(updateMap) == 0 {
+		return 0, nil
+	}
+
+	result := r.db.WithContext(ctx).
+		Model(&model.Account{}).
+		Where("id IN ?", ids).
+		Clauses(clause.Returning{}).
+		Updates(updateMap)
+
+	return result.RowsAffected, result.Error
+}

backend/internal/repository/account_repo_integration_test.go

@@ -0,0 +1,580 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/suite"
+	"gorm.io/gorm"
+)
+
+type AccountRepoSuite struct {
+	suite.Suite
+	ctx  context.Context
+	db   *gorm.DB
+	repo *accountRepository
+}
+
+func (s *AccountRepoSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+	s.repo = NewAccountRepository(s.db).(*accountRepository)
+}
+
+func TestAccountRepoSuite(t *testing.T) {
+	suite.Run(t, new(AccountRepoSuite))
+}
+
+// --- Create / GetByID / Update / Delete ---
+
+func (s *AccountRepoSuite) TestCreate() {
+	account := &model.Account{
+		Name:     "test-create",
+		Platform: model.PlatformAnthropic,
+		Type:     model.AccountTypeOAuth,
+		Status:   model.StatusActive,
+	}
+
+	err := s.repo.Create(s.ctx, account)
+	s.Require().NoError(err, "Create")
+	s.Require().NotZero(account.ID, "expected ID to be set")
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal("test-create", got.Name)
+}
+
+func (s *AccountRepoSuite) TestGetByID_NotFound() {
+	_, err := s.repo.GetByID(s.ctx, 999999)
+	s.Require().Error(err, "expected error for non-existent ID")
+}
+
+func (s *AccountRepoSuite) TestUpdate() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "original"})
+
+	account.Name = "updated"
+	err := s.repo.Update(s.ctx, account)
+	s.Require().NoError(err, "Update")
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err, "GetByID after update")
+	s.Require().Equal("updated", got.Name)
+}
+
+func (s *AccountRepoSuite) TestDelete() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "to-delete"})
+
+	err := s.repo.Delete(s.ctx, account.ID)
+	s.Require().NoError(err, "Delete")
+
+	_, err = s.repo.GetByID(s.ctx, account.ID)
+	s.Require().Error(err, "expected error after delete")
+}
+
+func (s *AccountRepoSuite) TestDelete_WithGroupBindings() {
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-del"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-del"})
+	mustBindAccountToGroup(s.T(), s.db, account.ID, group.ID, 1)
+
+	err := s.repo.Delete(s.ctx, account.ID)
+	s.Require().NoError(err, "Delete should cascade remove bindings")
+
+	var count int64
+	s.db.Model(&model.AccountGroup{}).Where("account_id = ?", account.ID).Count(&count)
+	s.Require().Zero(count, "expected bindings to be removed")
+}
+
+// --- List / ListWithFilters ---
+
+func (s *AccountRepoSuite) TestList() {
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc1"})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc2"})
+
+	accounts, page, err := s.repo.List(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "List")
+	s.Require().Len(accounts, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+func (s *AccountRepoSuite) TestListWithFilters() {
+	tests := []struct {
+		name      string
+		setup     func(db *gorm.DB)
+		platform  string
+		accType   string
+		status    string
+		search    string
+		wantCount int
+		validate  func(accounts []model.Account)
+	}{
+		{
+			name: "filter_by_platform",
+			setup: func(db *gorm.DB) {
+				mustCreateAccount(s.T(), db, &model.Account{Name: "a1", Platform: model.PlatformAnthropic})
+				mustCreateAccount(s.T(), db, &model.Account{Name: "a2", Platform: model.PlatformOpenAI})
+			},
+			platform:  model.PlatformOpenAI,
+			wantCount: 1,
+			validate: func(accounts []model.Account) {
+				s.Require().Equal(model.PlatformOpenAI, accounts[0].Platform)
+			},
+		},
+		{
+			name: "filter_by_type",
+			setup: func(db *gorm.DB) {
+				mustCreateAccount(s.T(), db, &model.Account{Name: "t1", Type: model.AccountTypeOAuth})
+				mustCreateAccount(s.T(), db, &model.Account{Name: "t2", Type: model.AccountTypeApiKey})
+			},
+			accType:   model.AccountTypeApiKey,
+			wantCount: 1,
+			validate: func(accounts []model.Account) {
+				s.Require().Equal(model.AccountTypeApiKey, accounts[0].Type)
+			},
+		},
+		{
+			name: "filter_by_status",
+			setup: func(db *gorm.DB) {
+				mustCreateAccount(s.T(), db, &model.Account{Name: "s1", Status: model.StatusActive})
+				mustCreateAccount(s.T(), db, &model.Account{Name: "s2", Status: model.StatusDisabled})
+			},
+			status:    model.StatusDisabled,
+			wantCount: 1,
+			validate: func(accounts []model.Account) {
+				s.Require().Equal(model.StatusDisabled, accounts[0].Status)
+			},
+		},
+		{
+			name: "filter_by_search",
+			setup: func(db *gorm.DB) {
+				mustCreateAccount(s.T(), db, &model.Account{Name: "alpha-account"})
+				mustCreateAccount(s.T(), db, &model.Account{Name: "beta-account"})
+			},
+			search:    "alpha",
+			wantCount: 1,
+			validate: func(accounts []model.Account) {
+				s.Require().Contains(accounts[0].Name, "alpha")
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			// 每个 case 重新获取隔离资源
+			db := testTx(s.T())
+			repo := NewAccountRepository(db).(*accountRepository)
+			ctx := context.Background()
+
+			tt.setup(db)
+
+			accounts, _, err := repo.ListWithFilters(ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, tt.platform, tt.accType, tt.status, tt.search)
+			s.Require().NoError(err)
+			s.Require().Len(accounts, tt.wantCount)
+			if tt.validate != nil {
+				tt.validate(accounts)
+			}
+		})
+	}
+}
+
+// --- ListByGroup / ListActive / ListByPlatform ---
+
+func (s *AccountRepoSuite) TestListByGroup() {
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-list"})
+	acc1 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1", Status: model.StatusActive})
+	acc2 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2", Status: model.StatusActive})
+	mustBindAccountToGroup(s.T(), s.db, acc1.ID, group.ID, 2)
+	mustBindAccountToGroup(s.T(), s.db, acc2.ID, group.ID, 1)
+
+	accounts, err := s.repo.ListByGroup(s.ctx, group.ID)
+	s.Require().NoError(err, "ListByGroup")
+	s.Require().Len(accounts, 2)
+	// Should be ordered by priority
+	s.Require().Equal(acc2.ID, accounts[0].ID, "expected acc2 first (priority=1)")
+}
+
+func (s *AccountRepoSuite) TestListActive() {
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "active1", Status: model.StatusActive})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "inactive1", Status: model.StatusDisabled})
+
+	accounts, err := s.repo.ListActive(s.ctx)
+	s.Require().NoError(err, "ListActive")
+	s.Require().Len(accounts, 1)
+	s.Require().Equal("active1", accounts[0].Name)
+}
+
+func (s *AccountRepoSuite) TestListByPlatform() {
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "p1", Platform: model.PlatformAnthropic, Status: model.StatusActive})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "p2", Platform: model.PlatformOpenAI, Status: model.StatusActive})
+
+	accounts, err := s.repo.ListByPlatform(s.ctx, model.PlatformAnthropic)
+	s.Require().NoError(err, "ListByPlatform")
+	s.Require().Len(accounts, 1)
+	s.Require().Equal(model.PlatformAnthropic, accounts[0].Platform)
+}
+
+// --- Preload and VirtualFields ---
+
+func (s *AccountRepoSuite) TestPreload_And_VirtualFields() {
+	proxy := mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p1"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g1"})
+
+	account := mustCreateAccount(s.T(), s.db, &model.Account{
+		Name:    "acc1",
+		ProxyID: &proxy.ID,
+	})
+	mustBindAccountToGroup(s.T(), s.db, account.ID, group.ID, 1)
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().NotNil(got.Proxy, "expected Proxy preload")
+	s.Require().Equal(proxy.ID, got.Proxy.ID)
+	s.Require().Len(got.GroupIDs, 1, "expected GroupIDs to be populated")
+	s.Require().Equal(group.ID, got.GroupIDs[0])
+	s.Require().Len(got.Groups, 1, "expected Groups to be populated")
+	s.Require().Equal(group.ID, got.Groups[0].ID)
+
+	accounts, page, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", "", "acc")
+	s.Require().NoError(err, "ListWithFilters")
+	s.Require().Equal(int64(1), page.Total)
+	s.Require().Len(accounts, 1)
+	s.Require().NotNil(accounts[0].Proxy, "expected Proxy preload in list")
+	s.Require().Equal(proxy.ID, accounts[0].Proxy.ID)
+	s.Require().Len(accounts[0].GroupIDs, 1, "expected GroupIDs in list")
+	s.Require().Equal(group.ID, accounts[0].GroupIDs[0])
+}
+
+// --- GroupBinding / AddToGroup / RemoveFromGroup / BindGroups / GetGroups ---
+
+func (s *AccountRepoSuite) TestGroupBinding_And_BindGroups() {
+	g1 := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g1"})
+	g2 := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g2"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc"})
+
+	s.Require().NoError(s.repo.AddToGroup(s.ctx, account.ID, g1.ID, 10), "AddToGroup")
+	groups, err := s.repo.GetGroups(s.ctx, account.ID)
+	s.Require().NoError(err, "GetGroups")
+	s.Require().Len(groups, 1, "expected 1 group")
+	s.Require().Equal(g1.ID, groups[0].ID)
+
+	s.Require().NoError(s.repo.RemoveFromGroup(s.ctx, account.ID, g1.ID), "RemoveFromGroup")
+	groups, err = s.repo.GetGroups(s.ctx, account.ID)
+	s.Require().NoError(err, "GetGroups after remove")
+	s.Require().Empty(groups, "expected 0 groups after remove")
+
+	s.Require().NoError(s.repo.BindGroups(s.ctx, account.ID, []int64{g1.ID, g2.ID}), "BindGroups")
+	groups, err = s.repo.GetGroups(s.ctx, account.ID)
+	s.Require().NoError(err, "GetGroups after bind")
+	s.Require().Len(groups, 2, "expected 2 groups after bind")
+}
+
+func (s *AccountRepoSuite) TestBindGroups_EmptyList() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-empty"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-empty"})
+	mustBindAccountToGroup(s.T(), s.db, account.ID, group.ID, 1)
+
+	s.Require().NoError(s.repo.BindGroups(s.ctx, account.ID, []int64{}), "BindGroups empty")
+
+	groups, err := s.repo.GetGroups(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().Empty(groups, "expected 0 groups after binding empty list")
+}
+
+// --- Schedulable ---
+
+func (s *AccountRepoSuite) TestListSchedulable() {
+	now := time.Now()
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-sched"})
+
+	okAcc := mustCreateAccount(s.T(), s.db, &model.Account{Name: "ok", Schedulable: true})
+	mustBindAccountToGroup(s.T(), s.db, okAcc.ID, group.ID, 1)
+
+	future := now.Add(10 * time.Minute)
+	overloaded := mustCreateAccount(s.T(), s.db, &model.Account{Name: "over", Schedulable: true, OverloadUntil: &future})
+	mustBindAccountToGroup(s.T(), s.db, overloaded.ID, group.ID, 1)
+
+	sched, err := s.repo.ListSchedulable(s.ctx)
+	s.Require().NoError(err, "ListSchedulable")
+	ids := idsOfAccounts(sched)
+	s.Require().Contains(ids, okAcc.ID)
+	s.Require().NotContains(ids, overloaded.ID)
+}
+
+func (s *AccountRepoSuite) TestListSchedulableByGroupID_TimeBoundaries_And_StatusUpdates() {
+	now := time.Now()
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-sched"})
+
+	okAcc := mustCreateAccount(s.T(), s.db, &model.Account{Name: "ok", Schedulable: true})
+	mustBindAccountToGroup(s.T(), s.db, okAcc.ID, group.ID, 1)
+
+	future := now.Add(10 * time.Minute)
+	overloaded := mustCreateAccount(s.T(), s.db, &model.Account{Name: "over", Schedulable: true, OverloadUntil: &future})
+	mustBindAccountToGroup(s.T(), s.db, overloaded.ID, group.ID, 1)
+
+	rateLimited := mustCreateAccount(s.T(), s.db, &model.Account{Name: "rl", Schedulable: true})
+	mustBindAccountToGroup(s.T(), s.db, rateLimited.ID, group.ID, 1)
+	s.Require().NoError(s.repo.SetRateLimited(s.ctx, rateLimited.ID, now.Add(10*time.Minute)), "SetRateLimited")
+
+	s.Require().NoError(s.repo.SetError(s.ctx, overloaded.ID, "boom"), "SetError")
+
+	sched, err := s.repo.ListSchedulableByGroupID(s.ctx, group.ID)
+	s.Require().NoError(err, "ListSchedulableByGroupID")
+	s.Require().Len(sched, 1, "expected only ok account schedulable")
+	s.Require().Equal(okAcc.ID, sched[0].ID)
+
+	s.Require().NoError(s.repo.ClearRateLimit(s.ctx, rateLimited.ID), "ClearRateLimit")
+	sched2, err := s.repo.ListSchedulableByGroupID(s.ctx, group.ID)
+	s.Require().NoError(err, "ListSchedulableByGroupID after ClearRateLimit")
+	s.Require().Len(sched2, 2, "expected 2 schedulable accounts after ClearRateLimit")
+}
+
+func (s *AccountRepoSuite) TestListSchedulableByPlatform() {
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1", Platform: model.PlatformAnthropic, Schedulable: true})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2", Platform: model.PlatformOpenAI, Schedulable: true})
+
+	accounts, err := s.repo.ListSchedulableByPlatform(s.ctx, model.PlatformAnthropic)
+	s.Require().NoError(err)
+	s.Require().Len(accounts, 1)
+	s.Require().Equal(model.PlatformAnthropic, accounts[0].Platform)
+}
+
+func (s *AccountRepoSuite) TestListSchedulableByGroupIDAndPlatform() {
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-sp"})
+	a1 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1", Platform: model.PlatformAnthropic, Schedulable: true})
+	a2 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2", Platform: model.PlatformOpenAI, Schedulable: true})
+	mustBindAccountToGroup(s.T(), s.db, a1.ID, group.ID, 1)
+	mustBindAccountToGroup(s.T(), s.db, a2.ID, group.ID, 2)
+
+	accounts, err := s.repo.ListSchedulableByGroupIDAndPlatform(s.ctx, group.ID, model.PlatformAnthropic)
+	s.Require().NoError(err)
+	s.Require().Len(accounts, 1)
+	s.Require().Equal(a1.ID, accounts[0].ID)
+}
+
+func (s *AccountRepoSuite) TestSetSchedulable() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-sched", Schedulable: true})
+
+	s.Require().NoError(s.repo.SetSchedulable(s.ctx, account.ID, false))
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().False(got.Schedulable)
+}
+
+// --- SetOverloaded / SetRateLimited / ClearRateLimit ---
+
+func (s *AccountRepoSuite) TestSetOverloaded() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-over"})
+	until := time.Date(2025, 6, 15, 12, 0, 0, 0, time.UTC)
+
+	s.Require().NoError(s.repo.SetOverloaded(s.ctx, account.ID, until))
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().NotNil(got.OverloadUntil)
+	s.Require().WithinDuration(until, *got.OverloadUntil, time.Second)
+}
+
+func (s *AccountRepoSuite) TestSetRateLimited() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-rl"})
+	resetAt := time.Date(2025, 6, 15, 14, 0, 0, 0, time.UTC)
+
+	s.Require().NoError(s.repo.SetRateLimited(s.ctx, account.ID, resetAt))
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().NotNil(got.RateLimitedAt)
+	s.Require().NotNil(got.RateLimitResetAt)
+	s.Require().WithinDuration(resetAt, *got.RateLimitResetAt, time.Second)
+}
+
+func (s *AccountRepoSuite) TestClearRateLimit() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-clear"})
+	until := time.Now().Add(1 * time.Hour)
+	s.Require().NoError(s.repo.SetOverloaded(s.ctx, account.ID, until))
+	s.Require().NoError(s.repo.SetRateLimited(s.ctx, account.ID, until))
+
+	s.Require().NoError(s.repo.ClearRateLimit(s.ctx, account.ID))
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().Nil(got.RateLimitedAt)
+	s.Require().Nil(got.RateLimitResetAt)
+	s.Require().Nil(got.OverloadUntil)
+}
+
+// --- UpdateLastUsed ---
+
+func (s *AccountRepoSuite) TestUpdateLastUsed() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-used"})
+	s.Require().Nil(account.LastUsedAt)
+
+	s.Require().NoError(s.repo.UpdateLastUsed(s.ctx, account.ID))
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().NotNil(got.LastUsedAt)
+}
+
+// --- SetError ---
+
+func (s *AccountRepoSuite) TestSetError() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-err", Status: model.StatusActive})
+
+	s.Require().NoError(s.repo.SetError(s.ctx, account.ID, "something went wrong"))
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(model.StatusError, got.Status)
+	s.Require().Equal("something went wrong", got.ErrorMessage)
+}
+
+// --- UpdateSessionWindow ---
+
+func (s *AccountRepoSuite) TestUpdateSessionWindow() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-win"})
+	start := time.Date(2025, 6, 15, 10, 0, 0, 0, time.UTC)
+	end := time.Date(2025, 6, 15, 15, 0, 0, 0, time.UTC)
+
+	s.Require().NoError(s.repo.UpdateSessionWindow(s.ctx, account.ID, &start, &end, "active"))
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().NotNil(got.SessionWindowStart)
+	s.Require().NotNil(got.SessionWindowEnd)
+	s.Require().Equal("active", got.SessionWindowStatus)
+}
+
+// --- UpdateExtra ---
+
+func (s *AccountRepoSuite) TestUpdateExtra_MergesFields() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{
+		Name:  "acc-extra",
+		Extra: model.JSONB{"a": "1"},
+	})
+	s.Require().NoError(s.repo.UpdateExtra(s.ctx, account.ID, map[string]any{"b": "2"}), "UpdateExtra")
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal("1", got.Extra["a"])
+	s.Require().Equal("2", got.Extra["b"])
+}
+
+func (s *AccountRepoSuite) TestUpdateExtra_EmptyUpdates() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-extra-empty"})
+	s.Require().NoError(s.repo.UpdateExtra(s.ctx, account.ID, map[string]any{}))
+}
+
+func (s *AccountRepoSuite) TestUpdateExtra_NilExtra() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-nil-extra", Extra: nil})
+	s.Require().NoError(s.repo.UpdateExtra(s.ctx, account.ID, map[string]any{"key": "val"}))
+
+	got, err := s.repo.GetByID(s.ctx, account.ID)
+	s.Require().NoError(err)
+	s.Require().Equal("val", got.Extra["key"])
+}
+
+// --- GetByCRSAccountID ---
+
+func (s *AccountRepoSuite) TestGetByCRSAccountID() {
+	crsID := "crs-12345"
+	mustCreateAccount(s.T(), s.db, &model.Account{
+		Name:  "acc-crs",
+		Extra: model.JSONB{"crs_account_id": crsID},
+	})
+
+	got, err := s.repo.GetByCRSAccountID(s.ctx, crsID)
+	s.Require().NoError(err)
+	s.Require().NotNil(got)
+	s.Require().Equal("acc-crs", got.Name)
+}
+
+func (s *AccountRepoSuite) TestGetByCRSAccountID_NotFound() {
+	got, err := s.repo.GetByCRSAccountID(s.ctx, "non-existent")
+	s.Require().NoError(err)
+	s.Require().Nil(got)
+}
+
+func (s *AccountRepoSuite) TestGetByCRSAccountID_EmptyString() {
+	got, err := s.repo.GetByCRSAccountID(s.ctx, "")
+	s.Require().NoError(err)
+	s.Require().Nil(got)
+}
+
+// --- BulkUpdate ---
+
+func (s *AccountRepoSuite) TestBulkUpdate() {
+	a1 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "bulk1", Priority: 1})
+	a2 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "bulk2", Priority: 1})
+
+	newPriority := 99
+	affected, err := s.repo.BulkUpdate(s.ctx, []int64{a1.ID, a2.ID}, service.AccountBulkUpdate{
+		Priority: &newPriority,
+	})
+	s.Require().NoError(err)
+	s.Require().GreaterOrEqual(affected, int64(1), "expected at least one affected row")
+
+	got1, _ := s.repo.GetByID(s.ctx, a1.ID)
+	got2, _ := s.repo.GetByID(s.ctx, a2.ID)
+	s.Require().Equal(99, got1.Priority)
+	s.Require().Equal(99, got2.Priority)
+}
+
+func (s *AccountRepoSuite) TestBulkUpdate_MergeCredentials() {
+	a1 := mustCreateAccount(s.T(), s.db, &model.Account{
+		Name:        "bulk-cred",
+		Credentials: model.JSONB{"existing": "value"},
+	})
+
+	_, err := s.repo.BulkUpdate(s.ctx, []int64{a1.ID}, service.AccountBulkUpdate{
+		Credentials: model.JSONB{"new_key": "new_value"},
+	})
+	s.Require().NoError(err)
+
+	got, _ := s.repo.GetByID(s.ctx, a1.ID)
+	s.Require().Equal("value", got.Credentials["existing"])
+	s.Require().Equal("new_value", got.Credentials["new_key"])
+}
+
+func (s *AccountRepoSuite) TestBulkUpdate_MergeExtra() {
+	a1 := mustCreateAccount(s.T(), s.db, &model.Account{
+		Name:  "bulk-extra",
+		Extra: model.JSONB{"existing": "val"},
+	})
+
+	_, err := s.repo.BulkUpdate(s.ctx, []int64{a1.ID}, service.AccountBulkUpdate{
+		Extra: model.JSONB{"new_key": "new_val"},
+	})
+	s.Require().NoError(err)
+
+	got, _ := s.repo.GetByID(s.ctx, a1.ID)
+	s.Require().Equal("val", got.Extra["existing"])
+	s.Require().Equal("new_val", got.Extra["new_key"])
+}
+
+func (s *AccountRepoSuite) TestBulkUpdate_EmptyIDs() {
+	affected, err := s.repo.BulkUpdate(s.ctx, []int64{}, service.AccountBulkUpdate{})
+	s.Require().NoError(err)
+	s.Require().Zero(affected)
+}
+
+func (s *AccountRepoSuite) TestBulkUpdate_EmptyUpdates() {
+	a1 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "bulk-empty"})
+
+	affected, err := s.repo.BulkUpdate(s.ctx, []int64{a1.ID}, service.AccountBulkUpdate{})
+	s.Require().NoError(err)
+	s.Require().Zero(affected)
+}
+
+func idsOfAccounts(accounts []model.Account) []int64 {
+	out := make([]int64, 0, len(accounts))
+	for i := range accounts {
+		out = append(out, accounts[i].ID)
+	}
+	return out
+}

backend/internal/repository/api_key_cache.go

@@ -5,8 +5,7 @@ import (
 	"fmt"
 	"time"
 
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 )
 
@@ -19,7 +18,7 @@ type apiKeyCache struct {
 	rdb *redis.Client
 }
 
-func NewApiKeyCache(rdb *redis.Client) ports.ApiKeyCache {
+func NewApiKeyCache(rdb *redis.Client) service.ApiKeyCache {
 	return &apiKeyCache{rdb: rdb}
 }
 

backend/internal/repository/api_key_cache_integration_test.go

@@ -0,0 +1,125 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type ApiKeyCacheSuite struct {
+	IntegrationRedisSuite
+}
+
+func (s *ApiKeyCacheSuite) TestCreateAttemptCount() {
+	tests := []struct {
+		name string
+		fn   func(ctx context.Context, rdb *redis.Client, cache *apiKeyCache)
+	}{
+		{
+			name: "missing_key_returns_redis_nil",
+			fn: func(ctx context.Context, rdb *redis.Client, cache *apiKeyCache) {
+				userID := int64(1)
+
+				_, err := cache.GetCreateAttemptCount(ctx, userID)
+
+				require.ErrorIs(s.T(), err, redis.Nil, "expected redis.Nil for missing key")
+			},
+		},
+		{
+			name: "increment_increases_count_and_sets_ttl",
+			fn: func(ctx context.Context, rdb *redis.Client, cache *apiKeyCache) {
+				userID := int64(1)
+				key := fmt.Sprintf("%s%d", apiKeyRateLimitKeyPrefix, userID)
+
+				require.NoError(s.T(), cache.IncrementCreateAttemptCount(ctx, userID), "IncrementCreateAttemptCount")
+				require.NoError(s.T(), cache.IncrementCreateAttemptCount(ctx, userID), "IncrementCreateAttemptCount 2")
+
+				count, err := cache.GetCreateAttemptCount(ctx, userID)
+				require.NoError(s.T(), err, "GetCreateAttemptCount")
+				require.Equal(s.T(), 2, count, "count mismatch")
+
+				ttl, err := rdb.TTL(ctx, key).Result()
+				require.NoError(s.T(), err, "TTL")
+				s.AssertTTLWithin(ttl, 1*time.Second, apiKeyRateLimitDuration)
+			},
+		},
+		{
+			name: "delete_removes_key",
+			fn: func(ctx context.Context, rdb *redis.Client, cache *apiKeyCache) {
+				userID := int64(1)
+
+				require.NoError(s.T(), cache.IncrementCreateAttemptCount(ctx, userID))
+				require.NoError(s.T(), cache.DeleteCreateAttemptCount(ctx, userID), "DeleteCreateAttemptCount")
+
+				_, err := cache.GetCreateAttemptCount(ctx, userID)
+				require.ErrorIs(s.T(), err, redis.Nil, "expected redis.Nil after delete")
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			// 每个 case 重新获取隔离资源
+			rdb := testRedis(s.T())
+			cache := &apiKeyCache{rdb: rdb}
+			ctx := context.Background()
+
+			tt.fn(ctx, rdb, cache)
+		})
+	}
+}
+
+func (s *ApiKeyCacheSuite) TestDailyUsage() {
+	tests := []struct {
+		name string
+		fn   func(ctx context.Context, rdb *redis.Client, cache *apiKeyCache)
+	}{
+		{
+			name: "increment_increases_count",
+			fn: func(ctx context.Context, rdb *redis.Client, cache *apiKeyCache) {
+				dailyKey := "daily:sk-test"
+
+				require.NoError(s.T(), cache.IncrementDailyUsage(ctx, dailyKey), "IncrementDailyUsage")
+				require.NoError(s.T(), cache.IncrementDailyUsage(ctx, dailyKey), "IncrementDailyUsage 2")
+
+				n, err := rdb.Get(ctx, dailyKey).Int()
+				require.NoError(s.T(), err, "Get dailyKey")
+				require.Equal(s.T(), 2, n, "expected daily usage=2")
+			},
+		},
+		{
+			name: "set_expiry_sets_ttl",
+			fn: func(ctx context.Context, rdb *redis.Client, cache *apiKeyCache) {
+				dailyKey := "daily:sk-test-expiry"
+
+				require.NoError(s.T(), cache.IncrementDailyUsage(ctx, dailyKey))
+				require.NoError(s.T(), cache.SetDailyUsageExpiry(ctx, dailyKey, 1*time.Hour), "SetDailyUsageExpiry")
+
+				ttl, err := rdb.TTL(ctx, dailyKey).Result()
+				require.NoError(s.T(), err, "TTL dailyKey")
+				require.Greater(s.T(), ttl, time.Duration(0), "expected ttl > 0")
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			rdb := testRedis(s.T())
+			cache := &apiKeyCache{rdb: rdb}
+			ctx := context.Background()
+
+			tt.fn(ctx, rdb, cache)
+		})
+	}
+}
+
+func TestApiKeyCacheSuite(t *testing.T) {
+	suite.Run(t, new(ApiKeyCacheSuite))
+}

backend/internal/repository/api_key_repo.go

@@ -2,51 +2,55 @@ package repository
 
 import (
 	"context"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
 )
 
-type ApiKeyRepository struct {
+type apiKeyRepository struct {
 	db *gorm.DB
 }
 
-func NewApiKeyRepository(db *gorm.DB) *ApiKeyRepository {
-	return &ApiKeyRepository{db: db}
+func NewApiKeyRepository(db *gorm.DB) service.ApiKeyRepository {
+	return &apiKeyRepository{db: db}
 }
 
-func (r *ApiKeyRepository) Create(ctx context.Context, key *model.ApiKey) error {
-	return r.db.WithContext(ctx).Create(key).Error
+func (r *apiKeyRepository) Create(ctx context.Context, key *model.ApiKey) error {
+	err := r.db.WithContext(ctx).Create(key).Error
+	return translatePersistenceError(err, nil, service.ErrApiKeyExists)
 }
 
-func (r *ApiKeyRepository) GetByID(ctx context.Context, id int64) (*model.ApiKey, error) {
+func (r *apiKeyRepository) GetByID(ctx context.Context, id int64) (*model.ApiKey, error) {
 	var key model.ApiKey
 	err := r.db.WithContext(ctx).Preload("User").Preload("Group").First(&key, id).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrApiKeyNotFound, nil)
 	}
 	return &key, nil
 }
 
-func (r *ApiKeyRepository) GetByKey(ctx context.Context, key string) (*model.ApiKey, error) {
+func (r *apiKeyRepository) GetByKey(ctx context.Context, key string) (*model.ApiKey, error) {
 	var apiKey model.ApiKey
 	err := r.db.WithContext(ctx).Preload("User").Preload("Group").Where("key = ?", key).First(&apiKey).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrApiKeyNotFound, nil)
 	}
 	return &apiKey, nil
 }
 
-func (r *ApiKeyRepository) Update(ctx context.Context, key *model.ApiKey) error {
+func (r *apiKeyRepository) Update(ctx context.Context, key *model.ApiKey) error {
 	return r.db.WithContext(ctx).Model(key).Select("name", "group_id", "status", "updated_at").Updates(key).Error
 }
 
-func (r *ApiKeyRepository) Delete(ctx context.Context, id int64) error {
+func (r *apiKeyRepository) Delete(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Delete(&model.ApiKey{}, id).Error
 }
 
-func (r *ApiKeyRepository) ListByUserID(ctx context.Context, userID int64, params pagination.PaginationParams) ([]model.ApiKey, *pagination.PaginationResult, error) {
+func (r *apiKeyRepository) ListByUserID(ctx context.Context, userID int64, params pagination.PaginationParams) ([]model.ApiKey, *pagination.PaginationResult, error) {
 	var keys []model.ApiKey
 	var total int64
 
@@ -73,19 +77,19 @@ func (r *ApiKeyRepository) ListByUserID(ctx context.Context, userID int64, param
 	}, nil
 }
 
-func (r *ApiKeyRepository) CountByUserID(ctx context.Context, userID int64) (int64, error) {
+func (r *apiKeyRepository) CountByUserID(ctx context.Context, userID int64) (int64, error) {
 	var count int64
 	err := r.db.WithContext(ctx).Model(&model.ApiKey{}).Where("user_id = ?", userID).Count(&count).Error
 	return count, err
 }
 
-func (r *ApiKeyRepository) ExistsByKey(ctx context.Context, key string) (bool, error) {
+func (r *apiKeyRepository) ExistsByKey(ctx context.Context, key string) (bool, error) {
 	var count int64
 	err := r.db.WithContext(ctx).Model(&model.ApiKey{}).Where("key = ?", key).Count(&count).Error
 	return count > 0, err
 }
 
-func (r *ApiKeyRepository) ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]model.ApiKey, *pagination.PaginationResult, error) {
+func (r *apiKeyRepository) ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]model.ApiKey, *pagination.PaginationResult, error) {
 	var keys []model.ApiKey
 	var total int64
 
@@ -113,7 +117,7 @@ func (r *ApiKeyRepository) ListByGroupID(ctx context.Context, groupID int64, par
 }
 
 // SearchApiKeys searches API keys by user ID and/or keyword (name)
-func (r *ApiKeyRepository) SearchApiKeys(ctx context.Context, userID int64, keyword string, limit int) ([]model.ApiKey, error) {
+func (r *apiKeyRepository) SearchApiKeys(ctx context.Context, userID int64, keyword string, limit int) ([]model.ApiKey, error) {
 	var keys []model.ApiKey
 
 	db := r.db.WithContext(ctx).Model(&model.ApiKey{})
@@ -135,7 +139,7 @@ func (r *ApiKeyRepository) SearchApiKeys(ctx context.Context, userID int64, keyw
 }
 
 // ClearGroupIDByGroupID 将指定分组的所有 API Key 的 group_id 设为 nil
-func (r *ApiKeyRepository) ClearGroupIDByGroupID(ctx context.Context, groupID int64) (int64, error) {
+func (r *apiKeyRepository) ClearGroupIDByGroupID(ctx context.Context, groupID int64) (int64, error) {
 	result := r.db.WithContext(ctx).Model(&model.ApiKey{}).
 		Where("group_id = ?", groupID).
 		Update("group_id", nil)
@@ -143,7 +147,7 @@ func (r *ApiKeyRepository) ClearGroupIDByGroupID(ctx context.Context, groupID in
 }
 
 // CountByGroupID 获取分组的 API Key 数量
-func (r *ApiKeyRepository) CountByGroupID(ctx context.Context, groupID int64) (int64, error) {
+func (r *apiKeyRepository) CountByGroupID(ctx context.Context, groupID int64) (int64, error) {
 	var count int64
 	err := r.db.WithContext(ctx).Model(&model.ApiKey{}).Where("group_id = ?", groupID).Count(&count).Error
 	return count, err

backend/internal/repository/api_key_repo_integration_test.go

@@ -0,0 +1,355 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/stretchr/testify/suite"
+	"gorm.io/gorm"
+)
+
+type ApiKeyRepoSuite struct {
+	suite.Suite
+	ctx  context.Context
+	db   *gorm.DB
+	repo *apiKeyRepository
+}
+
+func (s *ApiKeyRepoSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+	s.repo = NewApiKeyRepository(s.db).(*apiKeyRepository)
+}
+
+func TestApiKeyRepoSuite(t *testing.T) {
+	suite.Run(t, new(ApiKeyRepoSuite))
+}
+
+// --- Create / GetByID / GetByKey ---
+
+func (s *ApiKeyRepoSuite) TestCreate() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "create@test.com"})
+
+	key := &model.ApiKey{
+		UserID: user.ID,
+		Key:    "sk-create-test",
+		Name:   "Test Key",
+		Status: model.StatusActive,
+	}
+
+	err := s.repo.Create(s.ctx, key)
+	s.Require().NoError(err, "Create")
+	s.Require().NotZero(key.ID, "expected ID to be set")
+
+	got, err := s.repo.GetByID(s.ctx, key.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal("sk-create-test", got.Key)
+}
+
+func (s *ApiKeyRepoSuite) TestGetByID_NotFound() {
+	_, err := s.repo.GetByID(s.ctx, 999999)
+	s.Require().Error(err, "expected error for non-existent ID")
+}
+
+func (s *ApiKeyRepoSuite) TestGetByKey() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "getbykey@test.com"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-key"})
+
+	key := mustCreateApiKey(s.T(), s.db, &model.ApiKey{
+		UserID:  user.ID,
+		Key:     "sk-getbykey",
+		Name:    "My Key",
+		GroupID: &group.ID,
+		Status:  model.StatusActive,
+	})
+
+	got, err := s.repo.GetByKey(s.ctx, key.Key)
+	s.Require().NoError(err, "GetByKey")
+	s.Require().Equal(key.ID, got.ID)
+	s.Require().NotNil(got.User, "expected User preload")
+	s.Require().Equal(user.ID, got.User.ID)
+	s.Require().NotNil(got.Group, "expected Group preload")
+	s.Require().Equal(group.ID, got.Group.ID)
+}
+
+func (s *ApiKeyRepoSuite) TestGetByKey_NotFound() {
+	_, err := s.repo.GetByKey(s.ctx, "non-existent-key")
+	s.Require().Error(err, "expected error for non-existent key")
+}
+
+// --- Update ---
+
+func (s *ApiKeyRepoSuite) TestUpdate() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "update@test.com"})
+	key := mustCreateApiKey(s.T(), s.db, &model.ApiKey{
+		UserID: user.ID,
+		Key:    "sk-update",
+		Name:   "Original",
+		Status: model.StatusActive,
+	})
+
+	key.Name = "Renamed"
+	key.Status = model.StatusDisabled
+	err := s.repo.Update(s.ctx, key)
+	s.Require().NoError(err, "Update")
+
+	got, err := s.repo.GetByID(s.ctx, key.ID)
+	s.Require().NoError(err, "GetByID after update")
+	s.Require().Equal("sk-update", got.Key, "Update should not change key")
+	s.Require().Equal(user.ID, got.UserID, "Update should not change user_id")
+	s.Require().Equal("Renamed", got.Name)
+	s.Require().Equal(model.StatusDisabled, got.Status)
+}
+
+func (s *ApiKeyRepoSuite) TestUpdate_ClearGroupID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "cleargroup@test.com"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-clear"})
+	key := mustCreateApiKey(s.T(), s.db, &model.ApiKey{
+		UserID:  user.ID,
+		Key:     "sk-clear-group",
+		Name:    "Group Key",
+		GroupID: &group.ID,
+	})
+
+	key.GroupID = nil
+	err := s.repo.Update(s.ctx, key)
+	s.Require().NoError(err, "Update")
+
+	got, err := s.repo.GetByID(s.ctx, key.ID)
+	s.Require().NoError(err)
+	s.Require().Nil(got.GroupID, "expected GroupID to be cleared")
+}
+
+// --- Delete ---
+
+func (s *ApiKeyRepoSuite) TestDelete() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "delete@test.com"})
+	key := mustCreateApiKey(s.T(), s.db, &model.ApiKey{
+		UserID: user.ID,
+		Key:    "sk-delete",
+		Name:   "Delete Me",
+	})
+
+	err := s.repo.Delete(s.ctx, key.ID)
+	s.Require().NoError(err, "Delete")
+
+	_, err = s.repo.GetByID(s.ctx, key.ID)
+	s.Require().Error(err, "expected error after delete")
+}
+
+// --- ListByUserID / CountByUserID ---
+
+func (s *ApiKeyRepoSuite) TestListByUserID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "listbyuser@test.com"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-list-1", Name: "Key 1"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-list-2", Name: "Key 2"})
+
+	keys, page, err := s.repo.ListByUserID(s.ctx, user.ID, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "ListByUserID")
+	s.Require().Len(keys, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+func (s *ApiKeyRepoSuite) TestListByUserID_Pagination() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "paging@test.com"})
+	for i := 0; i < 5; i++ {
+		mustCreateApiKey(s.T(), s.db, &model.ApiKey{
+			UserID: user.ID,
+			Key:    "sk-page-" + string(rune('a'+i)),
+			Name:   "Key",
+		})
+	}
+
+	keys, page, err := s.repo.ListByUserID(s.ctx, user.ID, pagination.PaginationParams{Page: 1, PageSize: 2})
+	s.Require().NoError(err)
+	s.Require().Len(keys, 2)
+	s.Require().Equal(int64(5), page.Total)
+	s.Require().Equal(3, page.Pages)
+}
+
+func (s *ApiKeyRepoSuite) TestCountByUserID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "count@test.com"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-count-1", Name: "K1"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-count-2", Name: "K2"})
+
+	count, err := s.repo.CountByUserID(s.ctx, user.ID)
+	s.Require().NoError(err, "CountByUserID")
+	s.Require().Equal(int64(2), count)
+}
+
+// --- ListByGroupID / CountByGroupID ---
+
+func (s *ApiKeyRepoSuite) TestListByGroupID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "listbygroup@test.com"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-list"})
+
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-grp-1", Name: "K1", GroupID: &group.ID})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-grp-2", Name: "K2", GroupID: &group.ID})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-grp-3", Name: "K3"}) // no group
+
+	keys, page, err := s.repo.ListByGroupID(s.ctx, group.ID, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "ListByGroupID")
+	s.Require().Len(keys, 2)
+	s.Require().Equal(int64(2), page.Total)
+	// User preloaded
+	s.Require().NotNil(keys[0].User)
+}
+
+func (s *ApiKeyRepoSuite) TestCountByGroupID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "countgroup@test.com"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-count"})
+
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-gc-1", Name: "K1", GroupID: &group.ID})
+
+	count, err := s.repo.CountByGroupID(s.ctx, group.ID)
+	s.Require().NoError(err, "CountByGroupID")
+	s.Require().Equal(int64(1), count)
+}
+
+// --- ExistsByKey ---
+
+func (s *ApiKeyRepoSuite) TestExistsByKey() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "exists@test.com"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-exists", Name: "K"})
+
+	exists, err := s.repo.ExistsByKey(s.ctx, "sk-exists")
+	s.Require().NoError(err, "ExistsByKey")
+	s.Require().True(exists)
+
+	notExists, err := s.repo.ExistsByKey(s.ctx, "sk-not-exists")
+	s.Require().NoError(err)
+	s.Require().False(notExists)
+}
+
+// --- SearchApiKeys ---
+
+func (s *ApiKeyRepoSuite) TestSearchApiKeys() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "search@test.com"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-search-1", Name: "Production Key"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-search-2", Name: "Development Key"})
+
+	found, err := s.repo.SearchApiKeys(s.ctx, user.ID, "prod", 10)
+	s.Require().NoError(err, "SearchApiKeys")
+	s.Require().Len(found, 1)
+	s.Require().Contains(found[0].Name, "Production")
+}
+
+func (s *ApiKeyRepoSuite) TestSearchApiKeys_NoKeyword() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "searchnokw@test.com"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-nk-1", Name: "K1"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-nk-2", Name: "K2"})
+
+	found, err := s.repo.SearchApiKeys(s.ctx, user.ID, "", 10)
+	s.Require().NoError(err)
+	s.Require().Len(found, 2)
+}
+
+func (s *ApiKeyRepoSuite) TestSearchApiKeys_NoUserID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "searchnouid@test.com"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-nu-1", Name: "TestKey"})
+
+	found, err := s.repo.SearchApiKeys(s.ctx, 0, "testkey", 10)
+	s.Require().NoError(err)
+	s.Require().Len(found, 1)
+}
+
+// --- ClearGroupIDByGroupID ---
+
+func (s *ApiKeyRepoSuite) TestClearGroupIDByGroupID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "cleargrp@test.com"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-clear-bulk"})
+
+	k1 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-clr-1", Name: "K1", GroupID: &group.ID})
+	k2 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-clr-2", Name: "K2", GroupID: &group.ID})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-clr-3", Name: "K3"}) // no group
+
+	affected, err := s.repo.ClearGroupIDByGroupID(s.ctx, group.ID)
+	s.Require().NoError(err, "ClearGroupIDByGroupID")
+	s.Require().Equal(int64(2), affected)
+
+	got1, _ := s.repo.GetByID(s.ctx, k1.ID)
+	got2, _ := s.repo.GetByID(s.ctx, k2.ID)
+	s.Require().Nil(got1.GroupID)
+	s.Require().Nil(got2.GroupID)
+
+	count, _ := s.repo.CountByGroupID(s.ctx, group.ID)
+	s.Require().Zero(count)
+}
+
+// --- Combined CRUD/Search/ClearGroupID (original test preserved as integration) ---
+
+func (s *ApiKeyRepoSuite) TestCRUD_Search_ClearGroupID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "k@example.com"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-k"})
+
+	key := mustCreateApiKey(s.T(), s.db, &model.ApiKey{
+		UserID:  user.ID,
+		Key:     "sk-test-1",
+		Name:    "My Key",
+		GroupID: &group.ID,
+		Status:  model.StatusActive,
+	})
+
+	got, err := s.repo.GetByKey(s.ctx, key.Key)
+	s.Require().NoError(err, "GetByKey")
+	s.Require().Equal(key.ID, got.ID)
+	s.Require().NotNil(got.User)
+	s.Require().Equal(user.ID, got.User.ID)
+	s.Require().NotNil(got.Group)
+	s.Require().Equal(group.ID, got.Group.ID)
+
+	key.Name = "Renamed"
+	key.Status = model.StatusDisabled
+	key.GroupID = nil
+	s.Require().NoError(s.repo.Update(s.ctx, key), "Update")
+
+	got2, err := s.repo.GetByID(s.ctx, key.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal("sk-test-1", got2.Key, "Update should not change key")
+	s.Require().Equal(user.ID, got2.UserID, "Update should not change user_id")
+	s.Require().Equal("Renamed", got2.Name)
+	s.Require().Equal(model.StatusDisabled, got2.Status)
+	s.Require().Nil(got2.GroupID)
+
+	keys, page, err := s.repo.ListByUserID(s.ctx, user.ID, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "ListByUserID")
+	s.Require().Equal(int64(1), page.Total)
+	s.Require().Len(keys, 1)
+
+	exists, err := s.repo.ExistsByKey(s.ctx, "sk-test-1")
+	s.Require().NoError(err, "ExistsByKey")
+	s.Require().True(exists, "expected key to exist")
+
+	found, err := s.repo.SearchApiKeys(s.ctx, user.ID, "renam", 10)
+	s.Require().NoError(err, "SearchApiKeys")
+	s.Require().Len(found, 1)
+	s.Require().Equal(key.ID, found[0].ID)
+
+	// ClearGroupIDByGroupID
+	k2 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{
+		UserID:  user.ID,
+		Key:     "sk-test-2",
+		Name:    "Group Key",
+		GroupID: &group.ID,
+	})
+
+	countBefore, err := s.repo.CountByGroupID(s.ctx, group.ID)
+	s.Require().NoError(err, "CountByGroupID")
+	s.Require().Equal(int64(1), countBefore, "expected 1 key in group before clear")
+
+	affected, err := s.repo.ClearGroupIDByGroupID(s.ctx, group.ID)
+	s.Require().NoError(err, "ClearGroupIDByGroupID")
+	s.Require().Equal(int64(1), affected, "expected 1 affected row")
+
+	got3, err := s.repo.GetByID(s.ctx, k2.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Nil(got3.GroupID, "expected GroupID cleared")
+
+	countAfter, err := s.repo.CountByGroupID(s.ctx, group.ID)
+	s.Require().NoError(err, "CountByGroupID after clear")
+	s.Require().Equal(int64(0), countAfter, "expected 0 keys in group after clear")
+}

backend/internal/repository/billing_cache.go

@@ -8,8 +8,7 @@ import (
 	"strconv"
 	"time"
 
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 )
 
@@ -58,7 +57,7 @@ type billingCache struct {
 	rdb *redis.Client
 }
 
-func NewBillingCache(rdb *redis.Client) ports.BillingCache {
+func NewBillingCache(rdb *redis.Client) service.BillingCache {
 	return &billingCache{rdb: rdb}
 }
 
@@ -90,7 +89,7 @@ func (c *billingCache) InvalidateUserBalance(ctx context.Context, userID int64)
 	return c.rdb.Del(ctx, key).Err()
 }
 
-func (c *billingCache) GetSubscriptionCache(ctx context.Context, userID, groupID int64) (*ports.SubscriptionCacheData, error) {
+func (c *billingCache) GetSubscriptionCache(ctx context.Context, userID, groupID int64) (*service.SubscriptionCacheData, error) {
 	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
 	result, err := c.rdb.HGetAll(ctx, key).Result()
 	if err != nil {
@@ -102,8 +101,8 @@ func (c *billingCache) GetSubscriptionCache(ctx context.Context, userID, groupID
 	return c.parseSubscriptionCache(result)
 }
 
-func (c *billingCache) parseSubscriptionCache(data map[string]string) (*ports.SubscriptionCacheData, error) {
-	result := &ports.SubscriptionCacheData{}
+func (c *billingCache) parseSubscriptionCache(data map[string]string) (*service.SubscriptionCacheData, error) {
+	result := &service.SubscriptionCacheData{}
 
 	result.Status = data[subFieldStatus]
 	if result.Status == "" {
@@ -136,7 +135,7 @@ func (c *billingCache) parseSubscriptionCache(data map[string]string) (*ports.Su
 	return result, nil
 }
 
-func (c *billingCache) SetSubscriptionCache(ctx context.Context, userID, groupID int64, data *ports.SubscriptionCacheData) error {
+func (c *billingCache) SetSubscriptionCache(ctx context.Context, userID, groupID int64, data *service.SubscriptionCacheData) error {
 	if data == nil {
 		return nil
 	}

backend/internal/repository/billing_cache_integration_test.go

@@ -0,0 +1,283 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type BillingCacheSuite struct {
+	IntegrationRedisSuite
+}
+
+func (s *BillingCacheSuite) TestUserBalance() {
+	tests := []struct {
+		name string
+		fn   func(ctx context.Context, rdb *redis.Client, cache service.BillingCache)
+	}{
+		{
+			name: "missing_key_returns_redis_nil",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				_, err := cache.GetUserBalance(ctx, 1)
+				require.ErrorIs(s.T(), err, redis.Nil, "expected redis.Nil for missing balance key")
+			},
+		},
+		{
+			name: "deduct_on_nonexistent_is_noop",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(1)
+				balanceKey := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
+
+				require.NoError(s.T(), cache.DeductUserBalance(ctx, userID, 1), "DeductUserBalance should not error")
+
+				_, err := rdb.Get(ctx, balanceKey).Result()
+				require.ErrorIs(s.T(), err, redis.Nil, "expected missing key after deduct on non-existent")
+			},
+		},
+		{
+			name: "set_and_get_with_ttl",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(2)
+				balanceKey := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
+
+				require.NoError(s.T(), cache.SetUserBalance(ctx, userID, 10.5), "SetUserBalance")
+
+				got, err := cache.GetUserBalance(ctx, userID)
+				require.NoError(s.T(), err, "GetUserBalance")
+				require.Equal(s.T(), 10.5, got, "balance mismatch")
+
+				ttl, err := rdb.TTL(ctx, balanceKey).Result()
+				require.NoError(s.T(), err, "TTL")
+				s.AssertTTLWithin(ttl, 1*time.Second, billingCacheTTL)
+			},
+		},
+		{
+			name: "deduct_reduces_balance",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(3)
+
+				require.NoError(s.T(), cache.SetUserBalance(ctx, userID, 10.5), "SetUserBalance")
+				require.NoError(s.T(), cache.DeductUserBalance(ctx, userID, 2.25), "DeductUserBalance")
+
+				got, err := cache.GetUserBalance(ctx, userID)
+				require.NoError(s.T(), err, "GetUserBalance after deduct")
+				require.Equal(s.T(), 8.25, got, "deduct mismatch")
+			},
+		},
+		{
+			name: "invalidate_removes_key",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(100)
+				balanceKey := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
+
+				require.NoError(s.T(), cache.SetUserBalance(ctx, userID, 50.0), "SetUserBalance")
+
+				exists, err := rdb.Exists(ctx, balanceKey).Result()
+				require.NoError(s.T(), err, "Exists")
+				require.Equal(s.T(), int64(1), exists, "expected balance key to exist")
+
+				require.NoError(s.T(), cache.InvalidateUserBalance(ctx, userID), "InvalidateUserBalance")
+
+				exists, err = rdb.Exists(ctx, balanceKey).Result()
+				require.NoError(s.T(), err, "Exists after invalidate")
+				require.Equal(s.T(), int64(0), exists, "expected balance key to be removed after invalidate")
+
+				_, err = cache.GetUserBalance(ctx, userID)
+				require.ErrorIs(s.T(), err, redis.Nil, "expected redis.Nil after invalidate")
+			},
+		},
+		{
+			name: "deduct_refreshes_ttl",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(103)
+				balanceKey := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
+
+				require.NoError(s.T(), cache.SetUserBalance(ctx, userID, 100.0), "SetUserBalance")
+
+				ttl1, err := rdb.TTL(ctx, balanceKey).Result()
+				require.NoError(s.T(), err, "TTL before deduct")
+				s.AssertTTLWithin(ttl1, 1*time.Second, billingCacheTTL)
+
+				require.NoError(s.T(), cache.DeductUserBalance(ctx, userID, 25.0), "DeductUserBalance")
+
+				balance, err := cache.GetUserBalance(ctx, userID)
+				require.NoError(s.T(), err, "GetUserBalance")
+				require.Equal(s.T(), 75.0, balance, "expected balance 75.0")
+
+				ttl2, err := rdb.TTL(ctx, balanceKey).Result()
+				require.NoError(s.T(), err, "TTL after deduct")
+				s.AssertTTLWithin(ttl2, 1*time.Second, billingCacheTTL)
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			rdb := testRedis(s.T())
+			cache := NewBillingCache(rdb)
+			ctx := context.Background()
+
+			tt.fn(ctx, rdb, cache)
+		})
+	}
+}
+
+func (s *BillingCacheSuite) TestSubscriptionCache() {
+	tests := []struct {
+		name string
+		fn   func(ctx context.Context, rdb *redis.Client, cache service.BillingCache)
+	}{
+		{
+			name: "missing_key_returns_redis_nil",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(10)
+				groupID := int64(20)
+
+				_, err := cache.GetSubscriptionCache(ctx, userID, groupID)
+				require.ErrorIs(s.T(), err, redis.Nil, "expected redis.Nil for missing subscription key")
+			},
+		},
+		{
+			name: "update_usage_on_nonexistent_is_noop",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(11)
+				groupID := int64(21)
+				subKey := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
+
+				require.NoError(s.T(), cache.UpdateSubscriptionUsage(ctx, userID, groupID, 1.0), "UpdateSubscriptionUsage should not error")
+
+				exists, err := rdb.Exists(ctx, subKey).Result()
+				require.NoError(s.T(), err, "Exists")
+				require.Equal(s.T(), int64(0), exists, "expected missing subscription key after UpdateSubscriptionUsage on non-existent")
+			},
+		},
+		{
+			name: "set_and_get_with_ttl",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(12)
+				groupID := int64(22)
+				subKey := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
+
+				data := &service.SubscriptionCacheData{
+					Status:       "active",
+					ExpiresAt:    time.Now().Add(1 * time.Hour),
+					DailyUsage:   1.0,
+					WeeklyUsage:  2.0,
+					MonthlyUsage: 3.0,
+					Version:      7,
+				}
+				require.NoError(s.T(), cache.SetSubscriptionCache(ctx, userID, groupID, data), "SetSubscriptionCache")
+
+				gotSub, err := cache.GetSubscriptionCache(ctx, userID, groupID)
+				require.NoError(s.T(), err, "GetSubscriptionCache")
+				require.Equal(s.T(), "active", gotSub.Status)
+				require.Equal(s.T(), int64(7), gotSub.Version)
+				require.Equal(s.T(), 1.0, gotSub.DailyUsage)
+
+				ttl, err := rdb.TTL(ctx, subKey).Result()
+				require.NoError(s.T(), err, "TTL subKey")
+				s.AssertTTLWithin(ttl, 1*time.Second, billingCacheTTL)
+			},
+		},
+		{
+			name: "update_usage_increments_all_fields",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(13)
+				groupID := int64(23)
+
+				data := &service.SubscriptionCacheData{
+					Status:       "active",
+					ExpiresAt:    time.Now().Add(1 * time.Hour),
+					DailyUsage:   1.0,
+					WeeklyUsage:  2.0,
+					MonthlyUsage: 3.0,
+					Version:      1,
+				}
+				require.NoError(s.T(), cache.SetSubscriptionCache(ctx, userID, groupID, data), "SetSubscriptionCache")
+
+				require.NoError(s.T(), cache.UpdateSubscriptionUsage(ctx, userID, groupID, 0.5), "UpdateSubscriptionUsage")
+
+				gotSub, err := cache.GetSubscriptionCache(ctx, userID, groupID)
+				require.NoError(s.T(), err, "GetSubscriptionCache after update")
+				require.Equal(s.T(), 1.5, gotSub.DailyUsage)
+				require.Equal(s.T(), 2.5, gotSub.WeeklyUsage)
+				require.Equal(s.T(), 3.5, gotSub.MonthlyUsage)
+			},
+		},
+		{
+			name: "invalidate_removes_key",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(101)
+				groupID := int64(10)
+				subKey := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
+
+				data := &service.SubscriptionCacheData{
+					Status:       "active",
+					ExpiresAt:    time.Now().Add(1 * time.Hour),
+					DailyUsage:   1.0,
+					WeeklyUsage:  2.0,
+					MonthlyUsage: 3.0,
+					Version:      1,
+				}
+				require.NoError(s.T(), cache.SetSubscriptionCache(ctx, userID, groupID, data), "SetSubscriptionCache")
+
+				exists, err := rdb.Exists(ctx, subKey).Result()
+				require.NoError(s.T(), err, "Exists")
+				require.Equal(s.T(), int64(1), exists, "expected subscription key to exist")
+
+				require.NoError(s.T(), cache.InvalidateSubscriptionCache(ctx, userID, groupID), "InvalidateSubscriptionCache")
+
+				exists, err = rdb.Exists(ctx, subKey).Result()
+				require.NoError(s.T(), err, "Exists after invalidate")
+				require.Equal(s.T(), int64(0), exists, "expected subscription key to be removed after invalidate")
+
+				_, err = cache.GetSubscriptionCache(ctx, userID, groupID)
+				require.ErrorIs(s.T(), err, redis.Nil, "expected redis.Nil after invalidate")
+			},
+		},
+		{
+			name: "missing_status_returns_parsing_error",
+			fn: func(ctx context.Context, rdb *redis.Client, cache service.BillingCache) {
+				userID := int64(102)
+				groupID := int64(11)
+				subKey := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
+
+				fields := map[string]any{
+					"expires_at":    time.Now().Add(1 * time.Hour).Unix(),
+					"daily_usage":   1.0,
+					"weekly_usage":  2.0,
+					"monthly_usage": 3.0,
+					"version":       1,
+				}
+				require.NoError(s.T(), rdb.HSet(ctx, subKey, fields).Err(), "HSet")
+
+				_, err := cache.GetSubscriptionCache(ctx, userID, groupID)
+				require.Error(s.T(), err, "expected error for missing status field")
+				require.NotErrorIs(s.T(), err, redis.Nil, "expected parsing error, not redis.Nil")
+				require.Equal(s.T(), "invalid cache: missing status", err.Error())
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			rdb := testRedis(s.T())
+			cache := NewBillingCache(rdb)
+			ctx := context.Background()
+
+			tt.fn(ctx, rdb, cache)
+		})
+	}
+}
+
+func TestBillingCacheSuite(t *testing.T) {
+	suite.Run(t, new(BillingCacheSuite))
+}

backend/internal/repository/claude_oauth_service.go

@@ -7,28 +7,37 @@ import (
 	"log"
 	"net/http"
 	"net/url"
+	"strings"
 	"time"
 
-	"sub2api/internal/pkg/oauth"
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/oauth"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/imroc/req/v3"
 )
 
-type claudeOAuthService struct{}
-
 func NewClaudeOAuthClient() service.ClaudeOAuthClient {
-	return &claudeOAuthService{}
+	return &claudeOAuthService{
+		baseURL:       "https://claude.ai",
+		tokenURL:      oauth.TokenURL,
+		clientFactory: createReqClient,
+	}
+}
+
+type claudeOAuthService struct {
+	baseURL       string
+	tokenURL      string
+	clientFactory func(proxyURL string) *req.Client
 }
 
 func (s *claudeOAuthService) GetOrganizationUUID(ctx context.Context, sessionKey, proxyURL string) (string, error) {
-	client := createReqClient(proxyURL)
+	client := s.clientFactory(proxyURL)
 
 	var orgs []struct {
 		UUID string `json:"uuid"`
 	}
 
-	targetURL := "https://claude.ai/api/organizations"
+	targetURL := s.baseURL + "/api/organizations"
 	log.Printf("[OAuth] Step 1: Getting organization UUID from %s", targetURL)
 
 	resp, err := client.R().
@@ -60,9 +69,9 @@ func (s *claudeOAuthService) GetOrganizationUUID(ctx context.Context, sessionKey
 }
 
 func (s *claudeOAuthService) GetAuthorizationCode(ctx context.Context, sessionKey, orgUUID, scope, codeChallenge, state, proxyURL string) (string, error) {
-	client := createReqClient(proxyURL)
+	client := s.clientFactory(proxyURL)
 
-	authURL := fmt.Sprintf("https://claude.ai/v1/oauth/%s/authorize", orgUUID)
+	authURL := fmt.Sprintf("%s/v1/oauth/%s/authorize", s.baseURL, orgUUID)
 
 	reqBody := map[string]any{
 		"response_type":         "code",
@@ -132,27 +141,19 @@ func (s *claudeOAuthService) GetAuthorizationCode(ctx context.Context, sessionKe
 		fullCode = authCode + "#" + responseState
 	}
 
-	log.Printf("[OAuth] Step 2 SUCCESS - Got authorization code: %s...", authCode[:20])
+	log.Printf("[OAuth] Step 2 SUCCESS - Got authorization code: %s...", prefix(authCode, 20))
 	return fullCode, nil
 }
 
 func (s *claudeOAuthService) ExchangeCodeForToken(ctx context.Context, code, codeVerifier, state, proxyURL string) (*oauth.TokenResponse, error) {
-	client := createReqClient(proxyURL)
+	client := s.clientFactory(proxyURL)
 
+	// Parse code which may contain state in format "authCode#state"
 	authCode := code
 	codeState := ""
-	if len(code) > 0 {
-		parts := make([]string, 0, 2)
-		for i, part := range []rune(code) {
-			if part == '#' {
-				authCode = code[:i]
-				codeState = code[i+1:]
-				break
-			}
-		}
-		if len(parts) == 0 {
-			authCode = code
-		}
+	if idx := strings.Index(code, "#"); idx != -1 {
+		authCode = code[:idx]
+		codeState = code[idx+1:]
 	}
 
 	reqBody := map[string]any{
@@ -168,7 +169,7 @@ func (s *claudeOAuthService) ExchangeCodeForToken(ctx context.Context, code, cod
 	}
 
 	reqBodyJSON, _ := json.Marshal(reqBody)
-	log.Printf("[OAuth] Step 3: Exchanging code for token at %s", oauth.TokenURL)
+	log.Printf("[OAuth] Step 3: Exchanging code for token at %s", s.tokenURL)
 	log.Printf("[OAuth] Step 3 Request Body: %s", string(reqBodyJSON))
 
 	var tokenResp oauth.TokenResponse
@@ -178,7 +179,7 @@ func (s *claudeOAuthService) ExchangeCodeForToken(ctx context.Context, code, cod
 		SetHeader("Content-Type", "application/json").
 		SetBody(reqBody).
 		SetSuccessResult(&tokenResp).
-		Post(oauth.TokenURL)
+		Post(s.tokenURL)
 
 	if err != nil {
 		log.Printf("[OAuth] Step 3 FAILED - Request error: %v", err)
@@ -196,7 +197,7 @@ func (s *claudeOAuthService) ExchangeCodeForToken(ctx context.Context, code, cod
 }
 
 func (s *claudeOAuthService) RefreshToken(ctx context.Context, refreshToken, proxyURL string) (*oauth.TokenResponse, error) {
-	client := createReqClient(proxyURL)
+	client := s.clientFactory(proxyURL)
 
 	formData := url.Values{}
 	formData.Set("grant_type", "refresh_token")
@@ -209,7 +210,7 @@ func (s *claudeOAuthService) RefreshToken(ctx context.Context, refreshToken, pro
 		SetContext(ctx).
 		SetFormDataFromValues(formData).
 		SetSuccessResult(&tokenResp).
-		Post(oauth.TokenURL)
+		Post(s.tokenURL)
 
 	if err != nil {
 		return nil, fmt.Errorf("request failed: %w", err)
@@ -233,3 +234,13 @@ func createReqClient(proxyURL string) *req.Client {
 
 	return client
 }
+
+func prefix(s string, n int) string {
+	if n <= 0 {
+		return ""
+	}
+	if len(s) <= n {
+		return s
+	}
+	return s[:n]
+}

backend/internal/repository/claude_oauth_service_test.go

@@ -0,0 +1,343 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/oauth"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type ClaudeOAuthServiceSuite struct {
+	suite.Suite
+	srv    *httptest.Server
+	client *claudeOAuthService
+}
+
+func (s *ClaudeOAuthServiceSuite) TearDownTest() {
+	if s.srv != nil {
+		s.srv.Close()
+		s.srv = nil
+	}
+}
+
+// requestCapture holds captured request data for assertions in the main goroutine.
+type requestCapture struct {
+	path        string
+	method      string
+	cookies     []*http.Cookie
+	body        []byte
+	formValues  url.Values
+	bodyJSON    map[string]any
+	contentType string
+}
+
+func (s *ClaudeOAuthServiceSuite) TestGetOrganizationUUID() {
+	tests := []struct {
+		name       string
+		handler    http.HandlerFunc
+		wantErr    bool
+		errContain string
+		wantUUID   string
+		validate   func(captured requestCapture)
+	}{
+		{
+			name: "success",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", "application/json")
+				_, _ = w.Write([]byte(`[{"uuid":"org-1"}]`))
+			},
+			wantUUID: "org-1",
+			validate: func(captured requestCapture) {
+				require.Equal(s.T(), "/api/organizations", captured.path, "unexpected path")
+				require.Len(s.T(), captured.cookies, 1, "expected 1 cookie")
+				require.Equal(s.T(), "sessionKey", captured.cookies[0].Name)
+				require.Equal(s.T(), "sess", captured.cookies[0].Value)
+			},
+		},
+		{
+			name: "non_200_returns_error",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusUnauthorized)
+				_, _ = w.Write([]byte("unauthorized"))
+			},
+			wantErr:    true,
+			errContain: "401",
+		},
+		{
+			name: "invalid_json_returns_error",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", "application/json")
+				_, _ = w.Write([]byte("not-json"))
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			var captured requestCapture
+
+			s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				captured.path = r.URL.Path
+				captured.cookies = r.Cookies()
+				tt.handler(w, r)
+			}))
+			defer s.srv.Close()
+
+			client, ok := NewClaudeOAuthClient().(*claudeOAuthService)
+			require.True(s.T(), ok, "type assertion failed")
+			s.client = client
+			s.client.baseURL = s.srv.URL
+
+			got, err := s.client.GetOrganizationUUID(context.Background(), "sess", "")
+
+			if tt.wantErr {
+				require.Error(s.T(), err)
+				if tt.errContain != "" {
+					require.ErrorContains(s.T(), err, tt.errContain)
+				}
+				return
+			}
+
+			require.NoError(s.T(), err)
+			require.Equal(s.T(), tt.wantUUID, got)
+			if tt.validate != nil {
+				tt.validate(captured)
+			}
+		})
+	}
+}
+
+func (s *ClaudeOAuthServiceSuite) TestGetAuthorizationCode() {
+	tests := []struct {
+		name     string
+		handler  http.HandlerFunc
+		wantErr  bool
+		wantCode string
+		validate func(captured requestCapture)
+	}{
+		{
+			name: "parses_redirect_uri",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", "application/json")
+				_ = json.NewEncoder(w).Encode(map[string]string{
+					"redirect_uri": oauth.RedirectURI + "?code=AUTH&state=STATE",
+				})
+			},
+			wantCode: "AUTH#STATE",
+			validate: func(captured requestCapture) {
+				require.True(s.T(), strings.HasPrefix(captured.path, "/v1/oauth/") && strings.HasSuffix(captured.path, "/authorize"), "unexpected path: %s", captured.path)
+				require.Equal(s.T(), http.MethodPost, captured.method, "expected POST")
+				require.Len(s.T(), captured.cookies, 1, "expected 1 cookie")
+				require.Equal(s.T(), "sess", captured.cookies[0].Value)
+				require.Equal(s.T(), "org-1", captured.bodyJSON["organization_uuid"])
+				require.Equal(s.T(), oauth.ClientID, captured.bodyJSON["client_id"])
+				require.Equal(s.T(), oauth.RedirectURI, captured.bodyJSON["redirect_uri"])
+				require.Equal(s.T(), "st", captured.bodyJSON["state"])
+			},
+		},
+		{
+			name: "missing_code_returns_error",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", "application/json")
+				_ = json.NewEncoder(w).Encode(map[string]string{
+					"redirect_uri": oauth.RedirectURI + "?state=STATE", // no code
+				})
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			var captured requestCapture
+
+			s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				captured.path = r.URL.Path
+				captured.method = r.Method
+				captured.cookies = r.Cookies()
+				captured.body, _ = io.ReadAll(r.Body)
+				_ = json.Unmarshal(captured.body, &captured.bodyJSON)
+				tt.handler(w, r)
+			}))
+			defer s.srv.Close()
+
+			client, ok := NewClaudeOAuthClient().(*claudeOAuthService)
+			require.True(s.T(), ok, "type assertion failed")
+			s.client = client
+			s.client.baseURL = s.srv.URL
+
+			code, err := s.client.GetAuthorizationCode(context.Background(), "sess", "org-1", oauth.ScopeProfile, "cc", "st", "")
+
+			if tt.wantErr {
+				require.Error(s.T(), err)
+				return
+			}
+
+			require.NoError(s.T(), err)
+			require.Equal(s.T(), tt.wantCode, code)
+			if tt.validate != nil {
+				tt.validate(captured)
+			}
+		})
+	}
+}
+
+func (s *ClaudeOAuthServiceSuite) TestExchangeCodeForToken() {
+	tests := []struct {
+		name     string
+		handler  http.HandlerFunc
+		code     string
+		wantErr  bool
+		wantResp *oauth.TokenResponse
+		validate func(captured requestCapture)
+	}{
+		{
+			name: "sends_state_when_embedded",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", "application/json")
+				_ = json.NewEncoder(w).Encode(oauth.TokenResponse{
+					AccessToken:  "at",
+					TokenType:    "bearer",
+					ExpiresIn:    3600,
+					RefreshToken: "rt",
+					Scope:        "s",
+				})
+			},
+			code: "AUTH#STATE2",
+			wantResp: &oauth.TokenResponse{
+				AccessToken:  "at",
+				RefreshToken: "rt",
+			},
+			validate: func(captured requestCapture) {
+				require.Equal(s.T(), http.MethodPost, captured.method, "expected POST")
+				require.True(s.T(), strings.HasPrefix(captured.contentType, "application/json"), "unexpected content-type")
+				require.Equal(s.T(), "AUTH", captured.bodyJSON["code"])
+				require.Equal(s.T(), "STATE2", captured.bodyJSON["state"])
+				require.Equal(s.T(), oauth.ClientID, captured.bodyJSON["client_id"])
+				require.Equal(s.T(), oauth.RedirectURI, captured.bodyJSON["redirect_uri"])
+				require.Equal(s.T(), "ver", captured.bodyJSON["code_verifier"])
+			},
+		},
+		{
+			name: "non_200_returns_error",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusBadRequest)
+				_, _ = w.Write([]byte("bad request"))
+			},
+			code:    "AUTH",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			var captured requestCapture
+
+			s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				captured.method = r.Method
+				captured.contentType = r.Header.Get("Content-Type")
+				captured.body, _ = io.ReadAll(r.Body)
+				_ = json.Unmarshal(captured.body, &captured.bodyJSON)
+				tt.handler(w, r)
+			}))
+			defer s.srv.Close()
+
+			client, ok := NewClaudeOAuthClient().(*claudeOAuthService)
+			require.True(s.T(), ok, "type assertion failed")
+			s.client = client
+			s.client.tokenURL = s.srv.URL
+
+			resp, err := s.client.ExchangeCodeForToken(context.Background(), tt.code, "ver", "", "")
+
+			if tt.wantErr {
+				require.Error(s.T(), err)
+				return
+			}
+
+			require.NoError(s.T(), err)
+			require.Equal(s.T(), tt.wantResp.AccessToken, resp.AccessToken)
+			require.Equal(s.T(), tt.wantResp.RefreshToken, resp.RefreshToken)
+			if tt.validate != nil {
+				tt.validate(captured)
+			}
+		})
+	}
+}
+
+func (s *ClaudeOAuthServiceSuite) TestRefreshToken() {
+	tests := []struct {
+		name     string
+		handler  http.HandlerFunc
+		wantErr  bool
+		wantResp *oauth.TokenResponse
+		validate func(captured requestCapture)
+	}{
+		{
+			name: "sends_form",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", "application/json")
+				_ = json.NewEncoder(w).Encode(oauth.TokenResponse{AccessToken: "at2", TokenType: "bearer", ExpiresIn: 3600})
+			},
+			wantResp: &oauth.TokenResponse{AccessToken: "at2"},
+			validate: func(captured requestCapture) {
+				require.Equal(s.T(), http.MethodPost, captured.method, "expected POST")
+				require.Equal(s.T(), "refresh_token", captured.formValues.Get("grant_type"))
+				require.Equal(s.T(), "rt", captured.formValues.Get("refresh_token"))
+				require.Equal(s.T(), oauth.ClientID, captured.formValues.Get("client_id"))
+			},
+		},
+		{
+			name: "non_200_returns_error",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusUnauthorized)
+				_, _ = w.Write([]byte("unauthorized"))
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		s.Run(tt.name, func() {
+			var captured requestCapture
+
+			s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				captured.method = r.Method
+				captured.body, _ = io.ReadAll(r.Body)
+				captured.formValues, _ = url.ParseQuery(string(captured.body))
+				tt.handler(w, r)
+			}))
+			defer s.srv.Close()
+
+			client, ok := NewClaudeOAuthClient().(*claudeOAuthService)
+			require.True(s.T(), ok, "type assertion failed")
+			s.client = client
+			s.client.tokenURL = s.srv.URL
+
+			resp, err := s.client.RefreshToken(context.Background(), "rt", "")
+
+			if tt.wantErr {
+				require.Error(s.T(), err)
+				return
+			}
+
+			require.NoError(s.T(), err)
+			require.Equal(s.T(), tt.wantResp.AccessToken, resp.AccessToken)
+			if tt.validate != nil {
+				tt.validate(captured)
+			}
+		})
+	}
+}
+
+func TestClaudeOAuthServiceSuite(t *testing.T) {
+	suite.Run(t, new(ClaudeOAuthServiceSuite))
+}

backend/internal/repository/claude_usage_service.go

@@ -9,13 +9,17 @@ import (
 	"net/url"
 	"time"
 
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 )
 
-type claudeUsageService struct{}
+const defaultClaudeUsageURL = "https://api.anthropic.com/api/oauth/usage"
+
+type claudeUsageService struct {
+	usageURL string
+}
 
 func NewClaudeUsageFetcher() service.ClaudeUsageFetcher {
-	return &claudeUsageService{}
+	return &claudeUsageService{usageURL: defaultClaudeUsageURL}
 }
 
 func (s *claudeUsageService) FetchUsage(ctx context.Context, accessToken, proxyURL string) (*service.ClaudeUsageResponse, error) {
@@ -35,7 +39,7 @@ func (s *claudeUsageService) FetchUsage(ctx context.Context, accessToken, proxyU
 		Timeout:   30 * time.Second,
 	}
 
-	req, err := http.NewRequestWithContext(ctx, "GET", "https://api.anthropic.com/api/oauth/usage", nil)
+	req, err := http.NewRequestWithContext(ctx, "GET", s.usageURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("create request failed: %w", err)
 	}

backend/internal/repository/claude_usage_service_test.go

@@ -0,0 +1,105 @@
+package repository
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type ClaudeUsageServiceSuite struct {
+	suite.Suite
+	srv     *httptest.Server
+	fetcher *claudeUsageService
+}
+
+func (s *ClaudeUsageServiceSuite) TearDownTest() {
+	if s.srv != nil {
+		s.srv.Close()
+		s.srv = nil
+	}
+}
+
+// usageRequestCapture holds captured request data for assertions in the main goroutine.
+type usageRequestCapture struct {
+	authorization string
+	anthropicBeta string
+}
+
+func (s *ClaudeUsageServiceSuite) TestFetchUsage_Success() {
+	var captured usageRequestCapture
+
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		captured.authorization = r.Header.Get("Authorization")
+		captured.anthropicBeta = r.Header.Get("anthropic-beta")
+
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{
+  "five_hour": {"utilization": 12.5, "resets_at": "2025-01-01T00:00:00Z"},
+  "seven_day": {"utilization": 34.0, "resets_at": "2025-01-08T00:00:00Z"},
+  "seven_day_sonnet": {"utilization": 56.0, "resets_at": "2025-01-08T00:00:00Z"}
+}`)
+	}))
+
+	s.fetcher = &claudeUsageService{usageURL: s.srv.URL}
+
+	resp, err := s.fetcher.FetchUsage(context.Background(), "at", "://bad-proxy-url")
+	require.NoError(s.T(), err, "FetchUsage")
+	require.Equal(s.T(), 12.5, resp.FiveHour.Utilization, "FiveHour utilization mismatch")
+	require.Equal(s.T(), 34.0, resp.SevenDay.Utilization, "SevenDay utilization mismatch")
+	require.Equal(s.T(), 56.0, resp.SevenDaySonnet.Utilization, "SevenDaySonnet utilization mismatch")
+
+	// Assertions on captured request data
+	require.Equal(s.T(), "Bearer at", captured.authorization, "Authorization header mismatch")
+	require.Equal(s.T(), "oauth-2025-04-20", captured.anthropicBeta, "anthropic-beta header mismatch")
+}
+
+func (s *ClaudeUsageServiceSuite) TestFetchUsage_NonOK() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+		_, _ = io.WriteString(w, "nope")
+	}))
+
+	s.fetcher = &claudeUsageService{usageURL: s.srv.URL}
+
+	_, err := s.fetcher.FetchUsage(context.Background(), "at", "")
+	require.Error(s.T(), err)
+	require.ErrorContains(s.T(), err, "status 401")
+	require.ErrorContains(s.T(), err, "nope")
+}
+
+func (s *ClaudeUsageServiceSuite) TestFetchUsage_BadJSON() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, "not-json")
+	}))
+
+	s.fetcher = &claudeUsageService{usageURL: s.srv.URL}
+
+	_, err := s.fetcher.FetchUsage(context.Background(), "at", "")
+	require.Error(s.T(), err)
+	require.ErrorContains(s.T(), err, "decode response failed")
+}
+
+func (s *ClaudeUsageServiceSuite) TestFetchUsage_ContextCancel() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Never respond - simulate slow server
+		<-r.Context().Done()
+	}))
+
+	s.fetcher = &claudeUsageService{usageURL: s.srv.URL}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // Cancel immediately
+
+	_, err := s.fetcher.FetchUsage(ctx, "at", "")
+	require.Error(s.T(), err, "expected error for cancelled context")
+}
+
+func TestClaudeUsageServiceSuite(t *testing.T) {
+	suite.Run(t, new(ClaudeUsageServiceSuite))
+}

backend/internal/repository/concurrency_cache.go

@@ -5,60 +5,94 @@ import (
 	"fmt"
 	"time"
 
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 )
 
 const (
-	accountConcurrencyKeyPrefix = "concurrency:account:"
-	userConcurrencyKeyPrefix    = "concurrency:user:"
-	waitQueueKeyPrefix          = "concurrency:wait:"
-	concurrencyTTL              = 5 * time.Minute
+	// Key prefixes for independent slot keys
+	// Format: concurrency:account:{accountID}:{requestID}
+	accountSlotKeyPrefix = "concurrency:account:"
+	// Format: concurrency:user:{userID}:{requestID}
+	userSlotKeyPrefix = "concurrency:user:"
+	// Wait queue keeps counter format: concurrency:wait:{userID}
+	waitQueueKeyPrefix = "concurrency:wait:"
+
+	// Slot TTL - each slot expires independently
+	slotTTL = 5 * time.Minute
 )
 
 var (
+	// acquireScript uses SCAN to count existing slots and creates new slot if under limit
+	// KEYS[1] = pattern for SCAN (e.g., "concurrency:account:2:*")
+	// KEYS[2] = full slot key (e.g., "concurrency:account:2:req_xxx")
+	// ARGV[1] = maxConcurrency
+	// ARGV[2] = TTL in seconds
 	acquireScript = redis.NewScript(`
-		local current = redis.call('GET', KEYS[1])
-		if current == false then
-			current = 0
-		else
-			current = tonumber(current)
-		end
-		if current < tonumber(ARGV[1]) then
-			redis.call('INCR', KEYS[1])
-			redis.call('EXPIRE', KEYS[1], ARGV[2])
+		local pattern = KEYS[1]
+		local slotKey = KEYS[2]
+		local maxConcurrency = tonumber(ARGV[1])
+		local ttl = tonumber(ARGV[2])
+
+		-- Count existing slots using SCAN
+		local cursor = "0"
+		local count = 0
+		repeat
+			local result = redis.call('SCAN', cursor, 'MATCH', pattern, 'COUNT', 100)
+			cursor = result[1]
+			count = count + #result[2]
+		until cursor == "0"
+
+		-- Check if we can acquire a slot
+		if count < maxConcurrency then
+			redis.call('SET', slotKey, '1', 'EX', ttl)
 			return 1
 		end
+
 		return 0
 	`)
 
-	releaseScript = redis.NewScript(`
-		local current = redis.call('GET', KEYS[1])
-		if current ~= false and tonumber(current) > 0 then
-			redis.call('DECR', KEYS[1])
-		end
-		return 1
+	// getCountScript counts slots using SCAN
+	// KEYS[1] = pattern for SCAN
+	getCountScript = redis.NewScript(`
+		local pattern = KEYS[1]
+		local cursor = "0"
+		local count = 0
+		repeat
+			local result = redis.call('SCAN', cursor, 'MATCH', pattern, 'COUNT', 100)
+			cursor = result[1]
+			count = count + #result[2]
+		until cursor == "0"
+		return count
 	`)
 
+	// incrementWaitScript - only sets TTL on first creation to avoid refreshing
+	// KEYS[1] = wait queue key
+	// ARGV[1] = maxWait
+	// ARGV[2] = TTL in seconds
 	incrementWaitScript = redis.NewScript(`
-		local waitKey = KEYS[1]
-		local maxWait = tonumber(ARGV[1])
-		local ttl = tonumber(ARGV[2])
-		local current = redis.call('GET', waitKey)
+		local current = redis.call('GET', KEYS[1])
 		if current == false then
 			current = 0
 		else
 			current = tonumber(current)
 		end
-		if current >= maxWait then
+
+		if current >= tonumber(ARGV[1]) then
 			return 0
 		end
-		redis.call('INCR', waitKey)
-		redis.call('EXPIRE', waitKey, ttl)
+
+		local newVal = redis.call('INCR', KEYS[1])
+
+		-- Only set TTL on first creation to avoid refreshing zombie data
+		if newVal == 1 then
+			redis.call('EXPIRE', KEYS[1], ARGV[2])
+		end
+
 		return 1
 	`)
 
+	// decrementWaitScript - same as before
 	decrementWaitScript = redis.NewScript(`
 		local current = redis.call('GET', KEYS[1])
 		if current ~= false and tonumber(current) > 0 then
@@ -72,53 +106,90 @@ type concurrencyCache struct {
 	rdb *redis.Client
 }
 
-func NewConcurrencyCache(rdb *redis.Client) ports.ConcurrencyCache {
+func NewConcurrencyCache(rdb *redis.Client) service.ConcurrencyCache {
 	return &concurrencyCache{rdb: rdb}
 }
 
-func (c *concurrencyCache) AcquireAccountSlot(ctx context.Context, accountID int64, maxConcurrency int) (bool, error) {
-	key := fmt.Sprintf("%s%d", accountConcurrencyKeyPrefix, accountID)
-	result, err := acquireScript.Run(ctx, c.rdb, []string{key}, maxConcurrency, int(concurrencyTTL.Seconds())).Int()
+// Helper functions for key generation
+func accountSlotKey(accountID int64, requestID string) string {
+	return fmt.Sprintf("%s%d:%s", accountSlotKeyPrefix, accountID, requestID)
+}
+
+func accountSlotPattern(accountID int64) string {
+	return fmt.Sprintf("%s%d:*", accountSlotKeyPrefix, accountID)
+}
+
+func userSlotKey(userID int64, requestID string) string {
+	return fmt.Sprintf("%s%d:%s", userSlotKeyPrefix, userID, requestID)
+}
+
+func userSlotPattern(userID int64) string {
+	return fmt.Sprintf("%s%d:*", userSlotKeyPrefix, userID)
+}
+
+func waitQueueKey(userID int64) string {
+	return fmt.Sprintf("%s%d", waitQueueKeyPrefix, userID)
+}
+
+// Account slot operations
+
+func (c *concurrencyCache) AcquireAccountSlot(ctx context.Context, accountID int64, maxConcurrency int, requestID string) (bool, error) {
+	pattern := accountSlotPattern(accountID)
+	slotKey := accountSlotKey(accountID, requestID)
+
+	result, err := acquireScript.Run(ctx, c.rdb, []string{pattern, slotKey}, maxConcurrency, int(slotTTL.Seconds())).Int()
 	if err != nil {
 		return false, err
 	}
 	return result == 1, nil
 }
 
-func (c *concurrencyCache) ReleaseAccountSlot(ctx context.Context, accountID int64) error {
-	key := fmt.Sprintf("%s%d", accountConcurrencyKeyPrefix, accountID)
-	_, err := releaseScript.Run(ctx, c.rdb, []string{key}).Result()
-	return err
+func (c *concurrencyCache) ReleaseAccountSlot(ctx context.Context, accountID int64, requestID string) error {
+	slotKey := accountSlotKey(accountID, requestID)
+	return c.rdb.Del(ctx, slotKey).Err()
 }
 
 func (c *concurrencyCache) GetAccountConcurrency(ctx context.Context, accountID int64) (int, error) {
-	key := fmt.Sprintf("%s%d", accountConcurrencyKeyPrefix, accountID)
-	return c.rdb.Get(ctx, key).Int()
+	pattern := accountSlotPattern(accountID)
+	result, err := getCountScript.Run(ctx, c.rdb, []string{pattern}).Int()
+	if err != nil {
+		return 0, err
+	}
+	return result, nil
 }
 
-func (c *concurrencyCache) AcquireUserSlot(ctx context.Context, userID int64, maxConcurrency int) (bool, error) {
-	key := fmt.Sprintf("%s%d", userConcurrencyKeyPrefix, userID)
-	result, err := acquireScript.Run(ctx, c.rdb, []string{key}, maxConcurrency, int(concurrencyTTL.Seconds())).Int()
+// User slot operations
+
+func (c *concurrencyCache) AcquireUserSlot(ctx context.Context, userID int64, maxConcurrency int, requestID string) (bool, error) {
+	pattern := userSlotPattern(userID)
+	slotKey := userSlotKey(userID, requestID)
+
+	result, err := acquireScript.Run(ctx, c.rdb, []string{pattern, slotKey}, maxConcurrency, int(slotTTL.Seconds())).Int()
 	if err != nil {
 		return false, err
 	}
 	return result == 1, nil
 }
 
-func (c *concurrencyCache) ReleaseUserSlot(ctx context.Context, userID int64) error {
-	key := fmt.Sprintf("%s%d", userConcurrencyKeyPrefix, userID)
-	_, err := releaseScript.Run(ctx, c.rdb, []string{key}).Result()
-	return err
+func (c *concurrencyCache) ReleaseUserSlot(ctx context.Context, userID int64, requestID string) error {
+	slotKey := userSlotKey(userID, requestID)
+	return c.rdb.Del(ctx, slotKey).Err()
 }
 
 func (c *concurrencyCache) GetUserConcurrency(ctx context.Context, userID int64) (int, error) {
-	key := fmt.Sprintf("%s%d", userConcurrencyKeyPrefix, userID)
-	return c.rdb.Get(ctx, key).Int()
+	pattern := userSlotPattern(userID)
+	result, err := getCountScript.Run(ctx, c.rdb, []string{pattern}).Int()
+	if err != nil {
+		return 0, err
+	}
+	return result, nil
 }
 
+// Wait queue operations
+
 func (c *concurrencyCache) IncrementWaitCount(ctx context.Context, userID int64, maxWait int) (bool, error) {
-	key := fmt.Sprintf("%s%d", waitQueueKeyPrefix, userID)
-	result, err := incrementWaitScript.Run(ctx, c.rdb, []string{key}, maxWait, int(concurrencyTTL.Seconds())).Int()
+	key := waitQueueKey(userID)
+	result, err := incrementWaitScript.Run(ctx, c.rdb, []string{key}, maxWait, int(slotTTL.Seconds())).Int()
 	if err != nil {
 		return false, err
 	}
@@ -126,7 +197,7 @@ func (c *concurrencyCache) IncrementWaitCount(ctx context.Context, userID int64,
 }
 
 func (c *concurrencyCache) DecrementWaitCount(ctx context.Context, userID int64) error {
-	key := fmt.Sprintf("%s%d", waitQueueKeyPrefix, userID)
+	key := waitQueueKey(userID)
 	_, err := decrementWaitScript.Run(ctx, c.rdb, []string{key}).Result()
 	return err
 }

backend/internal/repository/concurrency_cache_integration_test.go

@@ -0,0 +1,231 @@
+//go:build integration
+
+package repository
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type ConcurrencyCacheSuite struct {
+	IntegrationRedisSuite
+	cache service.ConcurrencyCache
+}
+
+func (s *ConcurrencyCacheSuite) SetupTest() {
+	s.IntegrationRedisSuite.SetupTest()
+	s.cache = NewConcurrencyCache(s.rdb)
+}
+
+func (s *ConcurrencyCacheSuite) TestAccountSlot_AcquireAndRelease() {
+	accountID := int64(10)
+	reqID1, reqID2, reqID3 := "req1", "req2", "req3"
+
+	ok, err := s.cache.AcquireAccountSlot(s.ctx, accountID, 2, reqID1)
+	require.NoError(s.T(), err, "AcquireAccountSlot 1")
+	require.True(s.T(), ok)
+
+	ok, err = s.cache.AcquireAccountSlot(s.ctx, accountID, 2, reqID2)
+	require.NoError(s.T(), err, "AcquireAccountSlot 2")
+	require.True(s.T(), ok)
+
+	ok, err = s.cache.AcquireAccountSlot(s.ctx, accountID, 2, reqID3)
+	require.NoError(s.T(), err, "AcquireAccountSlot 3")
+	require.False(s.T(), ok, "expected third acquire to fail")
+
+	cur, err := s.cache.GetAccountConcurrency(s.ctx, accountID)
+	require.NoError(s.T(), err, "GetAccountConcurrency")
+	require.Equal(s.T(), 2, cur, "concurrency mismatch")
+
+	require.NoError(s.T(), s.cache.ReleaseAccountSlot(s.ctx, accountID, reqID1), "ReleaseAccountSlot")
+
+	cur, err = s.cache.GetAccountConcurrency(s.ctx, accountID)
+	require.NoError(s.T(), err, "GetAccountConcurrency after release")
+	require.Equal(s.T(), 1, cur, "expected 1 after release")
+}
+
+func (s *ConcurrencyCacheSuite) TestAccountSlot_TTL() {
+	accountID := int64(11)
+	reqID := "req_ttl_test"
+	slotKey := fmt.Sprintf("%s%d:%s", accountSlotKeyPrefix, accountID, reqID)
+
+	ok, err := s.cache.AcquireAccountSlot(s.ctx, accountID, 5, reqID)
+	require.NoError(s.T(), err, "AcquireAccountSlot")
+	require.True(s.T(), ok)
+
+	ttl, err := s.rdb.TTL(s.ctx, slotKey).Result()
+	require.NoError(s.T(), err, "TTL")
+	s.AssertTTLWithin(ttl, 1*time.Second, slotTTL)
+}
+
+func (s *ConcurrencyCacheSuite) TestAccountSlot_DuplicateReqID() {
+	accountID := int64(12)
+	reqID := "dup-req"
+
+	ok, err := s.cache.AcquireAccountSlot(s.ctx, accountID, 2, reqID)
+	require.NoError(s.T(), err)
+	require.True(s.T(), ok)
+
+	// Acquiring with same reqID should be idempotent
+	ok, err = s.cache.AcquireAccountSlot(s.ctx, accountID, 2, reqID)
+	require.NoError(s.T(), err)
+	require.True(s.T(), ok)
+
+	cur, err := s.cache.GetAccountConcurrency(s.ctx, accountID)
+	require.NoError(s.T(), err)
+	require.Equal(s.T(), 1, cur, "expected concurrency=1 (idempotent)")
+}
+
+func (s *ConcurrencyCacheSuite) TestAccountSlot_ReleaseIdempotent() {
+	accountID := int64(13)
+	reqID := "release-test"
+
+	ok, err := s.cache.AcquireAccountSlot(s.ctx, accountID, 1, reqID)
+	require.NoError(s.T(), err)
+	require.True(s.T(), ok)
+
+	require.NoError(s.T(), s.cache.ReleaseAccountSlot(s.ctx, accountID, reqID), "ReleaseAccountSlot")
+	// Releasing again should not error
+	require.NoError(s.T(), s.cache.ReleaseAccountSlot(s.ctx, accountID, reqID), "ReleaseAccountSlot again")
+	// Releasing non-existent should not error
+	require.NoError(s.T(), s.cache.ReleaseAccountSlot(s.ctx, accountID, "non-existent"), "ReleaseAccountSlot non-existent")
+
+	cur, err := s.cache.GetAccountConcurrency(s.ctx, accountID)
+	require.NoError(s.T(), err)
+	require.Equal(s.T(), 0, cur)
+}
+
+func (s *ConcurrencyCacheSuite) TestAccountSlot_MaxZero() {
+	accountID := int64(14)
+	reqID := "max-zero-test"
+
+	ok, err := s.cache.AcquireAccountSlot(s.ctx, accountID, 0, reqID)
+	require.NoError(s.T(), err)
+	require.False(s.T(), ok, "expected acquire to fail with max=0")
+}
+
+func (s *ConcurrencyCacheSuite) TestUserSlot_AcquireAndRelease() {
+	userID := int64(42)
+	reqID1, reqID2 := "req1", "req2"
+
+	ok, err := s.cache.AcquireUserSlot(s.ctx, userID, 1, reqID1)
+	require.NoError(s.T(), err, "AcquireUserSlot")
+	require.True(s.T(), ok)
+
+	ok, err = s.cache.AcquireUserSlot(s.ctx, userID, 1, reqID2)
+	require.NoError(s.T(), err, "AcquireUserSlot 2")
+	require.False(s.T(), ok, "expected second acquire to fail at max=1")
+
+	cur, err := s.cache.GetUserConcurrency(s.ctx, userID)
+	require.NoError(s.T(), err, "GetUserConcurrency")
+	require.Equal(s.T(), 1, cur, "expected concurrency=1")
+
+	require.NoError(s.T(), s.cache.ReleaseUserSlot(s.ctx, userID, reqID1), "ReleaseUserSlot")
+	// Releasing a non-existent slot should not error
+	require.NoError(s.T(), s.cache.ReleaseUserSlot(s.ctx, userID, "non-existent"), "ReleaseUserSlot non-existent")
+
+	cur, err = s.cache.GetUserConcurrency(s.ctx, userID)
+	require.NoError(s.T(), err, "GetUserConcurrency after release")
+	require.Equal(s.T(), 0, cur, "expected concurrency=0 after release")
+}
+
+func (s *ConcurrencyCacheSuite) TestUserSlot_TTL() {
+	userID := int64(200)
+	reqID := "req_ttl_test"
+	slotKey := fmt.Sprintf("%s%d:%s", userSlotKeyPrefix, userID, reqID)
+
+	ok, err := s.cache.AcquireUserSlot(s.ctx, userID, 5, reqID)
+	require.NoError(s.T(), err, "AcquireUserSlot")
+	require.True(s.T(), ok)
+
+	ttl, err := s.rdb.TTL(s.ctx, slotKey).Result()
+	require.NoError(s.T(), err, "TTL")
+	s.AssertTTLWithin(ttl, 1*time.Second, slotTTL)
+}
+
+func (s *ConcurrencyCacheSuite) TestWaitQueue_IncrementAndDecrement() {
+	userID := int64(20)
+	waitKey := fmt.Sprintf("%s%d", waitQueueKeyPrefix, userID)
+
+	ok, err := s.cache.IncrementWaitCount(s.ctx, userID, 2)
+	require.NoError(s.T(), err, "IncrementWaitCount 1")
+	require.True(s.T(), ok)
+
+	ok, err = s.cache.IncrementWaitCount(s.ctx, userID, 2)
+	require.NoError(s.T(), err, "IncrementWaitCount 2")
+	require.True(s.T(), ok)
+
+	ok, err = s.cache.IncrementWaitCount(s.ctx, userID, 2)
+	require.NoError(s.T(), err, "IncrementWaitCount 3")
+	require.False(s.T(), ok, "expected wait increment over max to fail")
+
+	ttl, err := s.rdb.TTL(s.ctx, waitKey).Result()
+	require.NoError(s.T(), err, "TTL waitKey")
+	s.AssertTTLWithin(ttl, 1*time.Second, slotTTL)
+
+	require.NoError(s.T(), s.cache.DecrementWaitCount(s.ctx, userID), "DecrementWaitCount")
+
+	val, err := s.rdb.Get(s.ctx, waitKey).Int()
+	if !errors.Is(err, redis.Nil) {
+		require.NoError(s.T(), err, "Get waitKey")
+	}
+	require.Equal(s.T(), 1, val, "expected wait count 1")
+}
+
+func (s *ConcurrencyCacheSuite) TestWaitQueue_DecrementNoNegative() {
+	userID := int64(300)
+	waitKey := fmt.Sprintf("%s%d", waitQueueKeyPrefix, userID)
+
+	// Test decrement on non-existent key - should not error and should not create negative value
+	require.NoError(s.T(), s.cache.DecrementWaitCount(s.ctx, userID), "DecrementWaitCount on non-existent key")
+
+	// Verify no key was created or it's not negative
+	val, err := s.rdb.Get(s.ctx, waitKey).Int()
+	if !errors.Is(err, redis.Nil) {
+		require.NoError(s.T(), err, "Get waitKey")
+	}
+	require.GreaterOrEqual(s.T(), val, 0, "expected non-negative wait count after decrement on empty")
+
+	// Set count to 1, then decrement twice
+	ok, err := s.cache.IncrementWaitCount(s.ctx, userID, 5)
+	require.NoError(s.T(), err, "IncrementWaitCount")
+	require.True(s.T(), ok)
+
+	// Decrement once (1 -> 0)
+	require.NoError(s.T(), s.cache.DecrementWaitCount(s.ctx, userID), "DecrementWaitCount")
+
+	// Decrement again on 0 - should not go negative
+	require.NoError(s.T(), s.cache.DecrementWaitCount(s.ctx, userID), "DecrementWaitCount on zero")
+
+	// Verify count is 0, not negative
+	val, err = s.rdb.Get(s.ctx, waitKey).Int()
+	if !errors.Is(err, redis.Nil) {
+		require.NoError(s.T(), err, "Get waitKey after double decrement")
+	}
+	require.GreaterOrEqual(s.T(), val, 0, "expected non-negative wait count")
+}
+
+func (s *ConcurrencyCacheSuite) TestGetAccountConcurrency_Missing() {
+	// When no slots exist, GetAccountConcurrency should return 0
+	cur, err := s.cache.GetAccountConcurrency(s.ctx, 999)
+	require.NoError(s.T(), err)
+	require.Equal(s.T(), 0, cur)
+}
+
+func (s *ConcurrencyCacheSuite) TestGetUserConcurrency_Missing() {
+	// When no slots exist, GetUserConcurrency should return 0
+	cur, err := s.cache.GetUserConcurrency(s.ctx, 999)
+	require.NoError(s.T(), err)
+	require.Equal(s.T(), 0, cur)
+}
+
+func TestConcurrencyCacheSuite(t *testing.T) {
+	suite.Run(t, new(ConcurrencyCacheSuite))
+}

backend/internal/repository/email_cache.go

@@ -5,8 +5,7 @@ import (
 	"encoding/json"
 	"time"
 
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 )
 
@@ -16,24 +15,24 @@ type emailCache struct {
 	rdb *redis.Client
 }
 
-func NewEmailCache(rdb *redis.Client) ports.EmailCache {
+func NewEmailCache(rdb *redis.Client) service.EmailCache {
 	return &emailCache{rdb: rdb}
 }
 
-func (c *emailCache) GetVerificationCode(ctx context.Context, email string) (*ports.VerificationCodeData, error) {
+func (c *emailCache) GetVerificationCode(ctx context.Context, email string) (*service.VerificationCodeData, error) {
 	key := verifyCodeKeyPrefix + email
 	val, err := c.rdb.Get(ctx, key).Result()
 	if err != nil {
 		return nil, err
 	}
-	var data ports.VerificationCodeData
+	var data service.VerificationCodeData
 	if err := json.Unmarshal([]byte(val), &data); err != nil {
 		return nil, err
 	}
 	return &data, nil
 }
 
-func (c *emailCache) SetVerificationCode(ctx context.Context, email string, data *ports.VerificationCodeData, ttl time.Duration) error {
+func (c *emailCache) SetVerificationCode(ctx context.Context, email string, data *service.VerificationCodeData, ttl time.Duration) error {
 	key := verifyCodeKeyPrefix + email
 	val, err := json.Marshal(data)
 	if err != nil {

backend/internal/repository/email_cache_integration_test.go

@@ -0,0 +1,92 @@
+//go:build integration
+
+package repository
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type EmailCacheSuite struct {
+	IntegrationRedisSuite
+	cache service.EmailCache
+}
+
+func (s *EmailCacheSuite) SetupTest() {
+	s.IntegrationRedisSuite.SetupTest()
+	s.cache = NewEmailCache(s.rdb)
+}
+
+func (s *EmailCacheSuite) TestGetVerificationCode_Missing() {
+	_, err := s.cache.GetVerificationCode(s.ctx, "nonexistent@example.com")
+	require.True(s.T(), errors.Is(err, redis.Nil), "expected redis.Nil for missing verification code")
+}
+
+func (s *EmailCacheSuite) TestSetAndGetVerificationCode() {
+	email := "a@example.com"
+	emailTTL := 2 * time.Minute
+	data := &service.VerificationCodeData{Code: "123456", Attempts: 1, CreatedAt: time.Now()}
+
+	require.NoError(s.T(), s.cache.SetVerificationCode(s.ctx, email, data, emailTTL), "SetVerificationCode")
+
+	got, err := s.cache.GetVerificationCode(s.ctx, email)
+	require.NoError(s.T(), err, "GetVerificationCode")
+	require.Equal(s.T(), "123456", got.Code)
+	require.Equal(s.T(), 1, got.Attempts)
+}
+
+func (s *EmailCacheSuite) TestVerificationCode_TTL() {
+	email := "ttl@example.com"
+	emailTTL := 2 * time.Minute
+	data := &service.VerificationCodeData{Code: "654321", Attempts: 0, CreatedAt: time.Now()}
+
+	require.NoError(s.T(), s.cache.SetVerificationCode(s.ctx, email, data, emailTTL), "SetVerificationCode")
+
+	emailKey := verifyCodeKeyPrefix + email
+	ttl, err := s.rdb.TTL(s.ctx, emailKey).Result()
+	require.NoError(s.T(), err, "TTL emailKey")
+	s.AssertTTLWithin(ttl, 1*time.Second, emailTTL)
+}
+
+func (s *EmailCacheSuite) TestDeleteVerificationCode() {
+	email := "delete@example.com"
+	data := &service.VerificationCodeData{Code: "999999", Attempts: 0, CreatedAt: time.Now()}
+
+	require.NoError(s.T(), s.cache.SetVerificationCode(s.ctx, email, data, 2*time.Minute), "SetVerificationCode")
+
+	// Verify it exists
+	_, err := s.cache.GetVerificationCode(s.ctx, email)
+	require.NoError(s.T(), err, "GetVerificationCode before delete")
+
+	// Delete
+	require.NoError(s.T(), s.cache.DeleteVerificationCode(s.ctx, email), "DeleteVerificationCode")
+
+	// Verify it's gone
+	_, err = s.cache.GetVerificationCode(s.ctx, email)
+	require.True(s.T(), errors.Is(err, redis.Nil), "expected redis.Nil after delete")
+}
+
+func (s *EmailCacheSuite) TestDeleteVerificationCode_NonExistent() {
+	// Deleting a non-existent key should not error
+	require.NoError(s.T(), s.cache.DeleteVerificationCode(s.ctx, "nonexistent@example.com"), "DeleteVerificationCode non-existent")
+}
+
+func (s *EmailCacheSuite) TestGetVerificationCode_JSONCorruption() {
+	emailKey := verifyCodeKeyPrefix + "corrupted@example.com"
+
+	require.NoError(s.T(), s.rdb.Set(s.ctx, emailKey, "not-json", 1*time.Minute).Err(), "Set invalid JSON")
+
+	_, err := s.cache.GetVerificationCode(s.ctx, "corrupted@example.com")
+	require.Error(s.T(), err, "expected error for corrupted JSON")
+	require.False(s.T(), errors.Is(err, redis.Nil), "expected decoding error, not redis.Nil")
+}
+
+func TestEmailCacheSuite(t *testing.T) {
+	suite.Run(t, new(EmailCacheSuite))
+}

backend/internal/repository/error_translate.go

@@ -0,0 +1,40 @@
+package repository
+
+import (
+	"errors"
+	"strings"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
+	"gorm.io/gorm"
+)
+
+func translatePersistenceError(err error, notFound, conflict *infraerrors.ApplicationError) error {
+	if err == nil {
+		return nil
+	}
+
+	if notFound != nil && errors.Is(err, gorm.ErrRecordNotFound) {
+		return notFound.WithCause(err)
+	}
+
+	if conflict != nil && isUniqueConstraintViolation(err) {
+		return conflict.WithCause(err)
+	}
+
+	return err
+}
+
+func isUniqueConstraintViolation(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	if errors.Is(err, gorm.ErrDuplicatedKey) {
+		return true
+	}
+
+	msg := strings.ToLower(err.Error())
+	return strings.Contains(msg, "duplicate key") ||
+		strings.Contains(msg, "unique constraint") ||
+		strings.Contains(msg, "duplicate entry")
+}

backend/internal/repository/fixtures_integration_test.go

@@ -0,0 +1,172 @@
+//go:build integration
+
+package repository
+
+import (
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+)
+
+func mustCreateUser(t *testing.T, db *gorm.DB, u *model.User) *model.User {
+	t.Helper()
+	if u.PasswordHash == "" {
+		u.PasswordHash = "test-password-hash"
+	}
+	if u.Role == "" {
+		u.Role = model.RoleUser
+	}
+	if u.Status == "" {
+		u.Status = model.StatusActive
+	}
+	if u.CreatedAt.IsZero() {
+		u.CreatedAt = time.Now()
+	}
+	if u.UpdatedAt.IsZero() {
+		u.UpdatedAt = u.CreatedAt
+	}
+	require.NoError(t, db.Create(u).Error, "create user")
+	return u
+}
+
+func mustCreateGroup(t *testing.T, db *gorm.DB, g *model.Group) *model.Group {
+	t.Helper()
+	if g.Platform == "" {
+		g.Platform = model.PlatformAnthropic
+	}
+	if g.Status == "" {
+		g.Status = model.StatusActive
+	}
+	if g.SubscriptionType == "" {
+		g.SubscriptionType = model.SubscriptionTypeStandard
+	}
+	if g.CreatedAt.IsZero() {
+		g.CreatedAt = time.Now()
+	}
+	if g.UpdatedAt.IsZero() {
+		g.UpdatedAt = g.CreatedAt
+	}
+	require.NoError(t, db.Create(g).Error, "create group")
+	return g
+}
+
+func mustCreateProxy(t *testing.T, db *gorm.DB, p *model.Proxy) *model.Proxy {
+	t.Helper()
+	if p.Protocol == "" {
+		p.Protocol = "http"
+	}
+	if p.Host == "" {
+		p.Host = "127.0.0.1"
+	}
+	if p.Port == 0 {
+		p.Port = 8080
+	}
+	if p.Status == "" {
+		p.Status = model.StatusActive
+	}
+	if p.CreatedAt.IsZero() {
+		p.CreatedAt = time.Now()
+	}
+	if p.UpdatedAt.IsZero() {
+		p.UpdatedAt = p.CreatedAt
+	}
+	require.NoError(t, db.Create(p).Error, "create proxy")
+	return p
+}
+
+func mustCreateAccount(t *testing.T, db *gorm.DB, a *model.Account) *model.Account {
+	t.Helper()
+	if a.Platform == "" {
+		a.Platform = model.PlatformAnthropic
+	}
+	if a.Type == "" {
+		a.Type = model.AccountTypeOAuth
+	}
+	if a.Status == "" {
+		a.Status = model.StatusActive
+	}
+	if !a.Schedulable {
+		a.Schedulable = true
+	}
+	if a.Credentials == nil {
+		a.Credentials = model.JSONB{}
+	}
+	if a.Extra == nil {
+		a.Extra = model.JSONB{}
+	}
+	if a.CreatedAt.IsZero() {
+		a.CreatedAt = time.Now()
+	}
+	if a.UpdatedAt.IsZero() {
+		a.UpdatedAt = a.CreatedAt
+	}
+	require.NoError(t, db.Create(a).Error, "create account")
+	return a
+}
+
+func mustCreateApiKey(t *testing.T, db *gorm.DB, k *model.ApiKey) *model.ApiKey {
+	t.Helper()
+	if k.Status == "" {
+		k.Status = model.StatusActive
+	}
+	if k.CreatedAt.IsZero() {
+		k.CreatedAt = time.Now()
+	}
+	if k.UpdatedAt.IsZero() {
+		k.UpdatedAt = k.CreatedAt
+	}
+	require.NoError(t, db.Create(k).Error, "create api key")
+	return k
+}
+
+func mustCreateRedeemCode(t *testing.T, db *gorm.DB, c *model.RedeemCode) *model.RedeemCode {
+	t.Helper()
+	if c.Status == "" {
+		c.Status = model.StatusUnused
+	}
+	if c.Type == "" {
+		c.Type = model.RedeemTypeBalance
+	}
+	if c.CreatedAt.IsZero() {
+		c.CreatedAt = time.Now()
+	}
+	require.NoError(t, db.Create(c).Error, "create redeem code")
+	return c
+}
+
+func mustCreateSubscription(t *testing.T, db *gorm.DB, s *model.UserSubscription) *model.UserSubscription {
+	t.Helper()
+	if s.Status == "" {
+		s.Status = model.SubscriptionStatusActive
+	}
+	now := time.Now()
+	if s.StartsAt.IsZero() {
+		s.StartsAt = now.Add(-1 * time.Hour)
+	}
+	if s.ExpiresAt.IsZero() {
+		s.ExpiresAt = now.Add(24 * time.Hour)
+	}
+	if s.AssignedAt.IsZero() {
+		s.AssignedAt = now
+	}
+	if s.CreatedAt.IsZero() {
+		s.CreatedAt = now
+	}
+	if s.UpdatedAt.IsZero() {
+		s.UpdatedAt = now
+	}
+	require.NoError(t, db.Create(s).Error, "create user subscription")
+	return s
+}
+
+func mustBindAccountToGroup(t *testing.T, db *gorm.DB, accountID, groupID int64, priority int) {
+	t.Helper()
+	require.NoError(t, db.Create(&model.AccountGroup{
+		AccountID: accountID,
+		GroupID:   groupID,
+		Priority:  priority,
+	}).Error, "create account_group")
+}

backend/internal/repository/gateway_cache.go

@@ -4,8 +4,7 @@ import (
 	"context"
 	"time"
 
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 )
 
@@ -15,7 +14,7 @@ type gatewayCache struct {
 	rdb *redis.Client
 }
 
-func NewGatewayCache(rdb *redis.Client) ports.GatewayCache {
+func NewGatewayCache(rdb *redis.Client) service.GatewayCache {
 	return &gatewayCache{rdb: rdb}
 }
 

backend/internal/repository/gateway_cache_integration_test.go

@@ -0,0 +1,92 @@
+//go:build integration
+
+package repository
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type GatewayCacheSuite struct {
+	IntegrationRedisSuite
+	cache service.GatewayCache
+}
+
+func (s *GatewayCacheSuite) SetupTest() {
+	s.IntegrationRedisSuite.SetupTest()
+	s.cache = NewGatewayCache(s.rdb)
+}
+
+func (s *GatewayCacheSuite) TestGetSessionAccountID_Missing() {
+	_, err := s.cache.GetSessionAccountID(s.ctx, "nonexistent")
+	require.True(s.T(), errors.Is(err, redis.Nil), "expected redis.Nil for missing session")
+}
+
+func (s *GatewayCacheSuite) TestSetAndGetSessionAccountID() {
+	sessionID := "s1"
+	accountID := int64(99)
+	sessionTTL := 1 * time.Minute
+
+	require.NoError(s.T(), s.cache.SetSessionAccountID(s.ctx, sessionID, accountID, sessionTTL), "SetSessionAccountID")
+
+	sid, err := s.cache.GetSessionAccountID(s.ctx, sessionID)
+	require.NoError(s.T(), err, "GetSessionAccountID")
+	require.Equal(s.T(), accountID, sid, "session id mismatch")
+}
+
+func (s *GatewayCacheSuite) TestSessionAccountID_TTL() {
+	sessionID := "s2"
+	accountID := int64(100)
+	sessionTTL := 1 * time.Minute
+
+	require.NoError(s.T(), s.cache.SetSessionAccountID(s.ctx, sessionID, accountID, sessionTTL), "SetSessionAccountID")
+
+	sessionKey := stickySessionPrefix + sessionID
+	ttl, err := s.rdb.TTL(s.ctx, sessionKey).Result()
+	require.NoError(s.T(), err, "TTL sessionKey after Set")
+	s.AssertTTLWithin(ttl, 1*time.Second, sessionTTL)
+}
+
+func (s *GatewayCacheSuite) TestRefreshSessionTTL() {
+	sessionID := "s3"
+	accountID := int64(101)
+	initialTTL := 1 * time.Minute
+	refreshTTL := 3 * time.Minute
+
+	require.NoError(s.T(), s.cache.SetSessionAccountID(s.ctx, sessionID, accountID, initialTTL), "SetSessionAccountID")
+
+	require.NoError(s.T(), s.cache.RefreshSessionTTL(s.ctx, sessionID, refreshTTL), "RefreshSessionTTL")
+
+	sessionKey := stickySessionPrefix + sessionID
+	ttl, err := s.rdb.TTL(s.ctx, sessionKey).Result()
+	require.NoError(s.T(), err, "TTL after Refresh")
+	s.AssertTTLWithin(ttl, 1*time.Second, refreshTTL)
+}
+
+func (s *GatewayCacheSuite) TestRefreshSessionTTL_MissingKey() {
+	// RefreshSessionTTL on a missing key should not error (no-op)
+	err := s.cache.RefreshSessionTTL(s.ctx, "missing-session", 1*time.Minute)
+	require.NoError(s.T(), err, "RefreshSessionTTL on missing key should not error")
+}
+
+func (s *GatewayCacheSuite) TestGetSessionAccountID_CorruptedValue() {
+	sessionID := "corrupted"
+	sessionKey := stickySessionPrefix + sessionID
+
+	// Set a non-integer value
+	require.NoError(s.T(), s.rdb.Set(s.ctx, sessionKey, "not-a-number", 1*time.Minute).Err(), "Set invalid value")
+
+	_, err := s.cache.GetSessionAccountID(s.ctx, sessionID)
+	require.Error(s.T(), err, "expected error for corrupted value")
+	require.False(s.T(), errors.Is(err, redis.Nil), "expected parsing error, not redis.Nil")
+}
+
+func TestGatewayCacheSuite(t *testing.T) {
+	suite.Run(t, new(GatewayCacheSuite))
+}

backend/internal/repository/github_release_service.go

@@ -9,7 +9,7 @@ import (
 	"os"
 	"time"
 
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 )
 
 type githubReleaseClient struct {

backend/internal/repository/github_release_service_test.go

@@ -0,0 +1,328 @@
+package repository
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type GitHubReleaseServiceSuite struct {
+	suite.Suite
+	srv     *httptest.Server
+	client  *githubReleaseClient
+	tempDir string
+}
+
+// testTransport redirects requests to the test server
+type testTransport struct {
+	testServerURL string
+}
+
+func (t *testTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	// Rewrite the URL to point to our test server
+	testURL := t.testServerURL + req.URL.Path
+	newReq, err := http.NewRequestWithContext(req.Context(), req.Method, testURL, req.Body)
+	if err != nil {
+		return nil, err
+	}
+	newReq.Header = req.Header
+	return http.DefaultTransport.RoundTrip(newReq)
+}
+
+func (s *GitHubReleaseServiceSuite) SetupTest() {
+	s.tempDir = s.T().TempDir()
+}
+
+func (s *GitHubReleaseServiceSuite) TearDownTest() {
+	if s.srv != nil {
+		s.srv.Close()
+		s.srv = nil
+	}
+}
+
+func (s *GitHubReleaseServiceSuite) TestDownloadFile_EnforcesMaxSize_ContentLength() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Length", "100")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(bytes.Repeat([]byte("a"), 100))
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	dest := filepath.Join(s.tempDir, "file1.bin")
+	err := s.client.DownloadFile(context.Background(), s.srv.URL, dest, 10)
+	require.Error(s.T(), err, "expected error for oversized download with Content-Length")
+
+	_, statErr := os.Stat(dest)
+	require.Error(s.T(), statErr, "expected file to not exist for rejected download")
+}
+
+func (s *GitHubReleaseServiceSuite) TestDownloadFile_EnforcesMaxSize_Chunked() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Force chunked encoding (unknown Content-Length) by flushing headers before writing.
+		w.WriteHeader(http.StatusOK)
+		if fl, ok := w.(http.Flusher); ok {
+			fl.Flush()
+		}
+		for i := 0; i < 10; i++ {
+			_, _ = w.Write(bytes.Repeat([]byte("b"), 10))
+			if fl, ok := w.(http.Flusher); ok {
+				fl.Flush()
+			}
+		}
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	dest := filepath.Join(s.tempDir, "file2.bin")
+	err := s.client.DownloadFile(context.Background(), s.srv.URL, dest, 10)
+	require.Error(s.T(), err, "expected error for oversized chunked download")
+
+	_, statErr := os.Stat(dest)
+	require.Error(s.T(), statErr, "expected file to be cleaned up for oversized chunked download")
+}
+
+func (s *GitHubReleaseServiceSuite) TestDownloadFile_Success() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		if fl, ok := w.(http.Flusher); ok {
+			fl.Flush()
+		}
+		for i := 0; i < 10; i++ {
+			_, _ = w.Write(bytes.Repeat([]byte("b"), 10))
+			if fl, ok := w.(http.Flusher); ok {
+				fl.Flush()
+			}
+		}
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	dest := filepath.Join(s.tempDir, "file3.bin")
+	err := s.client.DownloadFile(context.Background(), s.srv.URL, dest, 200)
+	require.NoError(s.T(), err, "expected success")
+
+	b, err := os.ReadFile(dest)
+	require.NoError(s.T(), err, "read")
+	require.True(s.T(), strings.HasPrefix(string(b), "b"), "downloaded content should start with 'b'")
+	require.Len(s.T(), b, 100, "downloaded content length mismatch")
+}
+
+func (s *GitHubReleaseServiceSuite) TestDownloadFile_404() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	dest := filepath.Join(s.tempDir, "notfound.bin")
+	err := s.client.DownloadFile(context.Background(), s.srv.URL, dest, 100)
+	require.Error(s.T(), err, "expected error for 404")
+
+	_, statErr := os.Stat(dest)
+	require.Error(s.T(), statErr, "expected file to not exist for 404")
+}
+
+func (s *GitHubReleaseServiceSuite) TestFetchChecksumFile_Success() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("sum"))
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	body, err := s.client.FetchChecksumFile(context.Background(), s.srv.URL)
+	require.NoError(s.T(), err, "FetchChecksumFile")
+	require.Equal(s.T(), "sum", string(body), "checksum body mismatch")
+}
+
+func (s *GitHubReleaseServiceSuite) TestFetchChecksumFile_Non200() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	_, err := s.client.FetchChecksumFile(context.Background(), s.srv.URL)
+	require.Error(s.T(), err, "expected error for non-200")
+}
+
+func (s *GitHubReleaseServiceSuite) TestDownloadFile_ContextCancel() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	dest := filepath.Join(s.tempDir, "cancelled.bin")
+	err := s.client.DownloadFile(ctx, s.srv.URL, dest, 100)
+	require.Error(s.T(), err, "expected error for cancelled context")
+}
+
+func (s *GitHubReleaseServiceSuite) TestDownloadFile_InvalidURL() {
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	dest := filepath.Join(s.tempDir, "invalid.bin")
+	err := s.client.DownloadFile(context.Background(), "://invalid-url", dest, 100)
+	require.Error(s.T(), err, "expected error for invalid URL")
+}
+
+func (s *GitHubReleaseServiceSuite) TestDownloadFile_InvalidDestPath() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("content"))
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	// Use a path that cannot be created (directory doesn't exist)
+	dest := filepath.Join(s.tempDir, "nonexistent", "subdir", "file.bin")
+	err := s.client.DownloadFile(context.Background(), s.srv.URL, dest, 100)
+	require.Error(s.T(), err, "expected error for invalid destination path")
+}
+
+func (s *GitHubReleaseServiceSuite) TestFetchChecksumFile_InvalidURL() {
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	_, err := s.client.FetchChecksumFile(context.Background(), "://invalid-url")
+	require.Error(s.T(), err, "expected error for invalid URL")
+}
+
+func (s *GitHubReleaseServiceSuite) TestFetchLatestRelease_Success() {
+	releaseJSON := `{
+		"tag_name": "v1.0.0",
+		"name": "Release 1.0.0",
+		"body": "Release notes",
+		"html_url": "https://github.com/test/repo/releases/v1.0.0",
+		"assets": [
+			{
+				"name": "app-linux-amd64.tar.gz",
+				"browser_download_url": "https://github.com/test/repo/releases/download/v1.0.0/app-linux-amd64.tar.gz"
+			}
+		]
+	}`
+
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(s.T(), "/repos/test/repo/releases/latest", r.URL.Path)
+		require.Equal(s.T(), "application/vnd.github.v3+json", r.Header.Get("Accept"))
+		require.Equal(s.T(), "Sub2API-Updater", r.Header.Get("User-Agent"))
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(releaseJSON))
+	}))
+
+	// Use custom transport to redirect requests to test server
+	s.client = &githubReleaseClient{
+		httpClient: &http.Client{
+			Transport: &testTransport{testServerURL: s.srv.URL},
+		},
+	}
+
+	release, err := s.client.FetchLatestRelease(context.Background(), "test/repo")
+	require.NoError(s.T(), err)
+	require.Equal(s.T(), "v1.0.0", release.TagName)
+	require.Equal(s.T(), "Release 1.0.0", release.Name)
+	require.Len(s.T(), release.Assets, 1)
+	require.Equal(s.T(), "app-linux-amd64.tar.gz", release.Assets[0].Name)
+}
+
+func (s *GitHubReleaseServiceSuite) TestFetchLatestRelease_Non200() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+
+	s.client = &githubReleaseClient{
+		httpClient: &http.Client{
+			Transport: &testTransport{testServerURL: s.srv.URL},
+		},
+	}
+
+	_, err := s.client.FetchLatestRelease(context.Background(), "test/repo")
+	require.Error(s.T(), err)
+	require.Contains(s.T(), err.Error(), "404")
+}
+
+func (s *GitHubReleaseServiceSuite) TestFetchLatestRelease_InvalidJSON() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("not valid json"))
+	}))
+
+	s.client = &githubReleaseClient{
+		httpClient: &http.Client{
+			Transport: &testTransport{testServerURL: s.srv.URL},
+		},
+	}
+
+	_, err := s.client.FetchLatestRelease(context.Background(), "test/repo")
+	require.Error(s.T(), err)
+}
+
+func (s *GitHubReleaseServiceSuite) TestFetchLatestRelease_ContextCancel() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+
+	s.client = &githubReleaseClient{
+		httpClient: &http.Client{
+			Transport: &testTransport{testServerURL: s.srv.URL},
+		},
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := s.client.FetchLatestRelease(ctx, "test/repo")
+	require.Error(s.T(), err)
+}
+
+func (s *GitHubReleaseServiceSuite) TestFetchChecksumFile_ContextCancel() {
+	s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+
+	client, ok := NewGitHubReleaseClient().(*githubReleaseClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := s.client.FetchChecksumFile(ctx, s.srv.URL)
+	require.Error(s.T(), err)
+}
+
+func TestGitHubReleaseServiceSuite(t *testing.T) {
+	suite.Run(t, new(GitHubReleaseServiceSuite))
+}

backend/internal/repository/group_repo.go

@@ -2,47 +2,52 @@ package repository
 
 import (
 	"context"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 )
 
-type GroupRepository struct {
+type groupRepository struct {
 	db *gorm.DB
 }
 
-func NewGroupRepository(db *gorm.DB) *GroupRepository {
-	return &GroupRepository{db: db}
+func NewGroupRepository(db *gorm.DB) service.GroupRepository {
+	return &groupRepository{db: db}
 }
 
-func (r *GroupRepository) Create(ctx context.Context, group *model.Group) error {
-	return r.db.WithContext(ctx).Create(group).Error
+func (r *groupRepository) Create(ctx context.Context, group *model.Group) error {
+	err := r.db.WithContext(ctx).Create(group).Error
+	return translatePersistenceError(err, nil, service.ErrGroupExists)
 }
 
-func (r *GroupRepository) GetByID(ctx context.Context, id int64) (*model.Group, error) {
+func (r *groupRepository) GetByID(ctx context.Context, id int64) (*model.Group, error) {
 	var group model.Group
 	err := r.db.WithContext(ctx).First(&group, id).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrGroupNotFound, nil)
 	}
 	return &group, nil
 }
 
-func (r *GroupRepository) Update(ctx context.Context, group *model.Group) error {
+func (r *groupRepository) Update(ctx context.Context, group *model.Group) error {
 	return r.db.WithContext(ctx).Save(group).Error
 }
 
-func (r *GroupRepository) Delete(ctx context.Context, id int64) error {
+func (r *groupRepository) Delete(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Delete(&model.Group{}, id).Error
 }
 
-func (r *GroupRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.Group, *pagination.PaginationResult, error) {
+func (r *groupRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.Group, *pagination.PaginationResult, error) {
 	return r.ListWithFilters(ctx, params, "", "", nil)
 }
 
 // ListWithFilters lists groups with optional filtering by platform, status, and is_exclusive
-func (r *GroupRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, platform, status string, isExclusive *bool) ([]model.Group, *pagination.PaginationResult, error) {
+func (r *groupRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, platform, status string, isExclusive *bool) ([]model.Group, *pagination.PaginationResult, error) {
 	var groups []model.Group
 	var total int64
 
@@ -86,7 +91,7 @@ func (r *GroupRepository) ListWithFilters(ctx context.Context, params pagination
 	}, nil
 }
 
-func (r *GroupRepository) ListActive(ctx context.Context) ([]model.Group, error) {
+func (r *groupRepository) ListActive(ctx context.Context) ([]model.Group, error) {
 	var groups []model.Group
 	err := r.db.WithContext(ctx).Where("status = ?", model.StatusActive).Order("id ASC").Find(&groups).Error
 	if err != nil {
@@ -100,7 +105,7 @@ func (r *GroupRepository) ListActive(ctx context.Context) ([]model.Group, error)
 	return groups, nil
 }
 
-func (r *GroupRepository) ListActiveByPlatform(ctx context.Context, platform string) ([]model.Group, error) {
+func (r *groupRepository) ListActiveByPlatform(ctx context.Context, platform string) ([]model.Group, error) {
 	var groups []model.Group
 	err := r.db.WithContext(ctx).Where("status = ? AND platform = ?", model.StatusActive, platform).Order("id ASC").Find(&groups).Error
 	if err != nil {
@@ -114,25 +119,80 @@ func (r *GroupRepository) ListActiveByPlatform(ctx context.Context, platform str
 	return groups, nil
 }
 
-func (r *GroupRepository) ExistsByName(ctx context.Context, name string) (bool, error) {
+func (r *groupRepository) ExistsByName(ctx context.Context, name string) (bool, error) {
 	var count int64
 	err := r.db.WithContext(ctx).Model(&model.Group{}).Where("name = ?", name).Count(&count).Error
 	return count > 0, err
 }
 
-func (r *GroupRepository) GetAccountCount(ctx context.Context, groupID int64) (int64, error) {
+func (r *groupRepository) GetAccountCount(ctx context.Context, groupID int64) (int64, error) {
 	var count int64
 	err := r.db.WithContext(ctx).Model(&model.AccountGroup{}).Where("group_id = ?", groupID).Count(&count).Error
 	return count, err
 }
 
 // DeleteAccountGroupsByGroupID 删除分组与账号的关联关系
-func (r *GroupRepository) DeleteAccountGroupsByGroupID(ctx context.Context, groupID int64) (int64, error) {
+func (r *groupRepository) DeleteAccountGroupsByGroupID(ctx context.Context, groupID int64) (int64, error) {
 	result := r.db.WithContext(ctx).Where("group_id = ?", groupID).Delete(&model.AccountGroup{})
 	return result.RowsAffected, result.Error
 }
 
-// DB 返回底层数据库连接，用于事务处理
-func (r *GroupRepository) DB() *gorm.DB {
-	return r.db
+func (r *groupRepository) DeleteCascade(ctx context.Context, id int64) ([]int64, error) {
+	group, err := r.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	var affectedUserIDs []int64
+	if group.IsSubscriptionType() {
+		var subscriptions []model.UserSubscription
+		if err := r.db.WithContext(ctx).
+			Model(&model.UserSubscription{}).
+			Where("group_id = ?", id).
+			Select("user_id").
+			Find(&subscriptions).Error; err != nil {
+			return nil, err
+		}
+		for _, sub := range subscriptions {
+			affectedUserIDs = append(affectedUserIDs, sub.UserID)
+		}
+	}
+
+	err = r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// 1. 删除订阅类型分组的订阅记录
+		if group.IsSubscriptionType() {
+			if err := tx.Where("group_id = ?", id).Delete(&model.UserSubscription{}).Error; err != nil {
+				return err
+			}
+		}
+
+		// 2. 将 api_keys 中绑定该分组的 group_id 设为 nil
+		if err := tx.Model(&model.ApiKey{}).Where("group_id = ?", id).Update("group_id", nil).Error; err != nil {
+			return err
+		}
+
+		// 3. 从 users.allowed_groups 数组中移除该分组 ID
+		if err := tx.Model(&model.User{}).
+			Where("? = ANY(allowed_groups)", id).
+			Update("allowed_groups", gorm.Expr("array_remove(allowed_groups, ?)", id)).Error; err != nil {
+			return err
+		}
+
+		// 4. 删除 account_groups 中间表的数据
+		if err := tx.Where("group_id = ?", id).Delete(&model.AccountGroup{}).Error; err != nil {
+			return err
+		}
+
+		// 5. 删除分组本身（带锁，避免并发写）
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Delete(&model.Group{}, id).Error; err != nil {
+			return err
+		}
+
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return affectedUserIDs, nil
 }

backend/internal/repository/group_repo_integration_test.go

@@ -0,0 +1,236 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/stretchr/testify/suite"
+	"gorm.io/gorm"
+)
+
+type GroupRepoSuite struct {
+	suite.Suite
+	ctx  context.Context
+	db   *gorm.DB
+	repo *groupRepository
+}
+
+func (s *GroupRepoSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+	s.repo = NewGroupRepository(s.db).(*groupRepository)
+}
+
+func TestGroupRepoSuite(t *testing.T) {
+	suite.Run(t, new(GroupRepoSuite))
+}
+
+// --- Create / GetByID / Update / Delete ---
+
+func (s *GroupRepoSuite) TestCreate() {
+	group := &model.Group{
+		Name:     "test-create",
+		Platform: model.PlatformAnthropic,
+		Status:   model.StatusActive,
+	}
+
+	err := s.repo.Create(s.ctx, group)
+	s.Require().NoError(err, "Create")
+	s.Require().NotZero(group.ID, "expected ID to be set")
+
+	got, err := s.repo.GetByID(s.ctx, group.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal("test-create", got.Name)
+}
+
+func (s *GroupRepoSuite) TestGetByID_NotFound() {
+	_, err := s.repo.GetByID(s.ctx, 999999)
+	s.Require().Error(err, "expected error for non-existent ID")
+}
+
+func (s *GroupRepoSuite) TestUpdate() {
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "original"})
+
+	group.Name = "updated"
+	err := s.repo.Update(s.ctx, group)
+	s.Require().NoError(err, "Update")
+
+	got, err := s.repo.GetByID(s.ctx, group.ID)
+	s.Require().NoError(err, "GetByID after update")
+	s.Require().Equal("updated", got.Name)
+}
+
+func (s *GroupRepoSuite) TestDelete() {
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "to-delete"})
+
+	err := s.repo.Delete(s.ctx, group.ID)
+	s.Require().NoError(err, "Delete")
+
+	_, err = s.repo.GetByID(s.ctx, group.ID)
+	s.Require().Error(err, "expected error after delete")
+}
+
+// --- List / ListWithFilters ---
+
+func (s *GroupRepoSuite) TestList() {
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g1"})
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g2"})
+
+	groups, page, err := s.repo.List(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "List")
+	s.Require().Len(groups, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+func (s *GroupRepoSuite) TestListWithFilters_Platform() {
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g1", Platform: model.PlatformAnthropic})
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g2", Platform: model.PlatformOpenAI})
+
+	groups, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, model.PlatformOpenAI, "", nil)
+	s.Require().NoError(err)
+	s.Require().Len(groups, 1)
+	s.Require().Equal(model.PlatformOpenAI, groups[0].Platform)
+}
+
+func (s *GroupRepoSuite) TestListWithFilters_Status() {
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g1", Status: model.StatusActive})
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g2", Status: model.StatusDisabled})
+
+	groups, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", model.StatusDisabled, nil)
+	s.Require().NoError(err)
+	s.Require().Len(groups, 1)
+	s.Require().Equal(model.StatusDisabled, groups[0].Status)
+}
+
+func (s *GroupRepoSuite) TestListWithFilters_IsExclusive() {
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g1", IsExclusive: false})
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g2", IsExclusive: true})
+
+	isExclusive := true
+	groups, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", &isExclusive)
+	s.Require().NoError(err)
+	s.Require().Len(groups, 1)
+	s.Require().True(groups[0].IsExclusive)
+}
+
+func (s *GroupRepoSuite) TestListWithFilters_AccountCount() {
+	g1 := mustCreateGroup(s.T(), s.db, &model.Group{
+		Name:     "g1",
+		Platform: model.PlatformAnthropic,
+		Status:   model.StatusActive,
+	})
+	g2 := mustCreateGroup(s.T(), s.db, &model.Group{
+		Name:        "g2",
+		Platform:    model.PlatformAnthropic,
+		Status:      model.StatusActive,
+		IsExclusive: true,
+	})
+
+	a := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc1"})
+	mustBindAccountToGroup(s.T(), s.db, a.ID, g1.ID, 1)
+	mustBindAccountToGroup(s.T(), s.db, a.ID, g2.ID, 1)
+
+	isExclusive := true
+	groups, page, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, model.PlatformAnthropic, model.StatusActive, &isExclusive)
+	s.Require().NoError(err, "ListWithFilters")
+	s.Require().Equal(int64(1), page.Total)
+	s.Require().Len(groups, 1)
+	s.Require().Equal(g2.ID, groups[0].ID, "ListWithFilters returned wrong group")
+	s.Require().Equal(int64(1), groups[0].AccountCount, "AccountCount mismatch")
+}
+
+// --- ListActive / ListActiveByPlatform ---
+
+func (s *GroupRepoSuite) TestListActive() {
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "active1", Status: model.StatusActive})
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "inactive1", Status: model.StatusDisabled})
+
+	groups, err := s.repo.ListActive(s.ctx)
+	s.Require().NoError(err, "ListActive")
+	s.Require().Len(groups, 1)
+	s.Require().Equal("active1", groups[0].Name)
+}
+
+func (s *GroupRepoSuite) TestListActiveByPlatform() {
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g1", Platform: model.PlatformAnthropic, Status: model.StatusActive})
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g2", Platform: model.PlatformOpenAI, Status: model.StatusActive})
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "g3", Platform: model.PlatformAnthropic, Status: model.StatusDisabled})
+
+	groups, err := s.repo.ListActiveByPlatform(s.ctx, model.PlatformAnthropic)
+	s.Require().NoError(err, "ListActiveByPlatform")
+	s.Require().Len(groups, 1)
+	s.Require().Equal("g1", groups[0].Name)
+}
+
+// --- ExistsByName ---
+
+func (s *GroupRepoSuite) TestExistsByName() {
+	mustCreateGroup(s.T(), s.db, &model.Group{Name: "existing-group"})
+
+	exists, err := s.repo.ExistsByName(s.ctx, "existing-group")
+	s.Require().NoError(err, "ExistsByName")
+	s.Require().True(exists)
+
+	notExists, err := s.repo.ExistsByName(s.ctx, "non-existing")
+	s.Require().NoError(err)
+	s.Require().False(notExists)
+}
+
+// --- GetAccountCount ---
+
+func (s *GroupRepoSuite) TestGetAccountCount() {
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-count"})
+	a1 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1"})
+	a2 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2"})
+	mustBindAccountToGroup(s.T(), s.db, a1.ID, group.ID, 1)
+	mustBindAccountToGroup(s.T(), s.db, a2.ID, group.ID, 2)
+
+	count, err := s.repo.GetAccountCount(s.ctx, group.ID)
+	s.Require().NoError(err, "GetAccountCount")
+	s.Require().Equal(int64(2), count)
+}
+
+func (s *GroupRepoSuite) TestGetAccountCount_Empty() {
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-empty"})
+
+	count, err := s.repo.GetAccountCount(s.ctx, group.ID)
+	s.Require().NoError(err)
+	s.Require().Zero(count)
+}
+
+// --- DeleteAccountGroupsByGroupID ---
+
+func (s *GroupRepoSuite) TestDeleteAccountGroupsByGroupID() {
+	g := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-del"})
+	a := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-del"})
+	mustBindAccountToGroup(s.T(), s.db, a.ID, g.ID, 1)
+
+	affected, err := s.repo.DeleteAccountGroupsByGroupID(s.ctx, g.ID)
+	s.Require().NoError(err, "DeleteAccountGroupsByGroupID")
+	s.Require().Equal(int64(1), affected, "expected 1 affected row")
+
+	count, err := s.repo.GetAccountCount(s.ctx, g.ID)
+	s.Require().NoError(err, "GetAccountCount")
+	s.Require().Equal(int64(0), count, "expected 0 account groups")
+}
+
+func (s *GroupRepoSuite) TestDeleteAccountGroupsByGroupID_MultipleAccounts() {
+	g := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-multi"})
+	a1 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1"})
+	a2 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2"})
+	a3 := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a3"})
+	mustBindAccountToGroup(s.T(), s.db, a1.ID, g.ID, 1)
+	mustBindAccountToGroup(s.T(), s.db, a2.ID, g.ID, 2)
+	mustBindAccountToGroup(s.T(), s.db, a3.ID, g.ID, 3)
+
+	affected, err := s.repo.DeleteAccountGroupsByGroupID(s.ctx, g.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(int64(3), affected)
+
+	count, _ := s.repo.GetAccountCount(s.ctx, g.ID)
+	s.Require().Zero(count)
+}

backend/internal/repository/http_upstream.go

@@ -5,8 +5,8 @@ import (
 	"net/url"
 	"time"
 
-	"sub2api/internal/config"
-	"sub2api/internal/service/ports"
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 )
 
 // httpUpstreamService is a generic HTTP upstream service that can be used for
@@ -17,7 +17,7 @@ type httpUpstreamService struct {
 }
 
 // NewHTTPUpstream creates a new generic HTTP upstream service
-func NewHTTPUpstream(cfg *config.Config) ports.HTTPUpstream {
+func NewHTTPUpstream(cfg *config.Config) service.HTTPUpstream {
 	responseHeaderTimeout := time.Duration(cfg.Gateway.ResponseHeaderTimeout) * time.Second
 	if responseHeaderTimeout == 0 {
 		responseHeaderTimeout = 300 * time.Second

backend/internal/repository/http_upstream_test.go

@@ -0,0 +1,115 @@
+package repository
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type HTTPUpstreamSuite struct {
+	suite.Suite
+	cfg *config.Config
+}
+
+func (s *HTTPUpstreamSuite) SetupTest() {
+	s.cfg = &config.Config{}
+}
+
+func (s *HTTPUpstreamSuite) TestDefaultResponseHeaderTimeout() {
+	up := NewHTTPUpstream(s.cfg)
+	svc, ok := up.(*httpUpstreamService)
+	require.True(s.T(), ok, "expected *httpUpstreamService")
+	transport, ok := svc.defaultClient.Transport.(*http.Transport)
+	require.True(s.T(), ok, "expected *http.Transport")
+	require.Equal(s.T(), 300*time.Second, transport.ResponseHeaderTimeout, "ResponseHeaderTimeout mismatch")
+}
+
+func (s *HTTPUpstreamSuite) TestCustomResponseHeaderTimeout() {
+	s.cfg.Gateway = config.GatewayConfig{ResponseHeaderTimeout: 7}
+	up := NewHTTPUpstream(s.cfg)
+	svc, ok := up.(*httpUpstreamService)
+	require.True(s.T(), ok, "expected *httpUpstreamService")
+	transport, ok := svc.defaultClient.Transport.(*http.Transport)
+	require.True(s.T(), ok, "expected *http.Transport")
+	require.Equal(s.T(), 7*time.Second, transport.ResponseHeaderTimeout, "ResponseHeaderTimeout mismatch")
+}
+
+func (s *HTTPUpstreamSuite) TestCreateProxyClient_InvalidURLFallsBackToDefault() {
+	s.cfg.Gateway = config.GatewayConfig{ResponseHeaderTimeout: 5}
+	up := NewHTTPUpstream(s.cfg)
+	svc, ok := up.(*httpUpstreamService)
+	require.True(s.T(), ok, "expected *httpUpstreamService")
+
+	got := svc.createProxyClient("://bad-proxy-url")
+	require.Equal(s.T(), svc.defaultClient, got, "expected defaultClient fallback")
+}
+
+func (s *HTTPUpstreamSuite) TestDo_WithoutProxy_GoesDirect() {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.WriteString(w, "direct")
+	}))
+	s.T().Cleanup(upstream.Close)
+
+	up := NewHTTPUpstream(s.cfg)
+
+	req, err := http.NewRequest(http.MethodGet, upstream.URL+"/x", nil)
+	require.NoError(s.T(), err, "NewRequest")
+	resp, err := up.Do(req, "")
+	require.NoError(s.T(), err, "Do")
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	require.Equal(s.T(), "direct", string(b), "unexpected body")
+}
+
+func (s *HTTPUpstreamSuite) TestDo_WithHTTPProxy_UsesProxy() {
+	seen := make(chan string, 1)
+	proxySrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen <- r.RequestURI
+		_, _ = io.WriteString(w, "proxied")
+	}))
+	s.T().Cleanup(proxySrv.Close)
+
+	s.cfg.Gateway = config.GatewayConfig{ResponseHeaderTimeout: 1}
+	up := NewHTTPUpstream(s.cfg)
+
+	req, err := http.NewRequest(http.MethodGet, "http://example.com/test", nil)
+	require.NoError(s.T(), err, "NewRequest")
+	resp, err := up.Do(req, proxySrv.URL)
+	require.NoError(s.T(), err, "Do")
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	require.Equal(s.T(), "proxied", string(b), "unexpected body")
+
+	select {
+	case uri := <-seen:
+		require.Equal(s.T(), "http://example.com/test", uri, "expected absolute-form request URI")
+	default:
+		require.Fail(s.T(), "expected proxy to receive request")
+	}
+}
+
+func (s *HTTPUpstreamSuite) TestDo_EmptyProxy_UsesDirect() {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.WriteString(w, "direct-empty")
+	}))
+	s.T().Cleanup(upstream.Close)
+
+	up := NewHTTPUpstream(s.cfg)
+	req, err := http.NewRequest(http.MethodGet, upstream.URL+"/y", nil)
+	require.NoError(s.T(), err, "NewRequest")
+	resp, err := up.Do(req, "")
+	require.NoError(s.T(), err, "Do with empty proxy")
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	require.Equal(s.T(), "direct-empty", string(b))
+}
+
+func TestHTTPUpstreamSuite(t *testing.T) {
+	suite.Run(t, new(HTTPUpstreamSuite))
+}

backend/internal/repository/identity_cache.go

@@ -6,8 +6,7 @@ import (
 	"fmt"
 	"time"
 
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 )
 
@@ -20,24 +19,24 @@ type identityCache struct {
 	rdb *redis.Client
 }
 
-func NewIdentityCache(rdb *redis.Client) ports.IdentityCache {
+func NewIdentityCache(rdb *redis.Client) service.IdentityCache {
 	return &identityCache{rdb: rdb}
 }
 
-func (c *identityCache) GetFingerprint(ctx context.Context, accountID int64) (*ports.Fingerprint, error) {
+func (c *identityCache) GetFingerprint(ctx context.Context, accountID int64) (*service.Fingerprint, error) {
 	key := fmt.Sprintf("%s%d", fingerprintKeyPrefix, accountID)
 	val, err := c.rdb.Get(ctx, key).Result()
 	if err != nil {
 		return nil, err
 	}
-	var fp ports.Fingerprint
+	var fp service.Fingerprint
 	if err := json.Unmarshal([]byte(val), &fp); err != nil {
 		return nil, err
 	}
 	return &fp, nil
 }
 
-func (c *identityCache) SetFingerprint(ctx context.Context, accountID int64, fp *ports.Fingerprint) error {
+func (c *identityCache) SetFingerprint(ctx context.Context, accountID int64, fp *service.Fingerprint) error {
 	key := fmt.Sprintf("%s%d", fingerprintKeyPrefix, accountID)
 	val, err := json.Marshal(fp)
 	if err != nil {

backend/internal/repository/identity_cache_integration_test.go

@@ -0,0 +1,67 @@
+//go:build integration
+
+package repository
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type IdentityCacheSuite struct {
+	IntegrationRedisSuite
+	cache *identityCache
+}
+
+func (s *IdentityCacheSuite) SetupTest() {
+	s.IntegrationRedisSuite.SetupTest()
+	s.cache = NewIdentityCache(s.rdb).(*identityCache)
+}
+
+func (s *IdentityCacheSuite) TestGetFingerprint_Missing() {
+	_, err := s.cache.GetFingerprint(s.ctx, 1)
+	require.True(s.T(), errors.Is(err, redis.Nil), "expected redis.Nil for missing fingerprint")
+}
+
+func (s *IdentityCacheSuite) TestSetAndGetFingerprint() {
+	fp := &service.Fingerprint{ClientID: "c1", UserAgent: "ua"}
+	require.NoError(s.T(), s.cache.SetFingerprint(s.ctx, 1, fp), "SetFingerprint")
+	gotFP, err := s.cache.GetFingerprint(s.ctx, 1)
+	require.NoError(s.T(), err, "GetFingerprint")
+	require.Equal(s.T(), "c1", gotFP.ClientID)
+	require.Equal(s.T(), "ua", gotFP.UserAgent)
+}
+
+func (s *IdentityCacheSuite) TestFingerprint_TTL() {
+	fp := &service.Fingerprint{ClientID: "c1", UserAgent: "ua"}
+	require.NoError(s.T(), s.cache.SetFingerprint(s.ctx, 2, fp))
+
+	fpKey := fmt.Sprintf("%s%d", fingerprintKeyPrefix, 2)
+	ttl, err := s.rdb.TTL(s.ctx, fpKey).Result()
+	require.NoError(s.T(), err, "TTL fpKey")
+	s.AssertTTLWithin(ttl, 1*time.Second, fingerprintTTL)
+}
+
+func (s *IdentityCacheSuite) TestGetFingerprint_JSONCorruption() {
+	fpKey := fmt.Sprintf("%s%d", fingerprintKeyPrefix, 999)
+	require.NoError(s.T(), s.rdb.Set(s.ctx, fpKey, "invalid-json-data", 1*time.Minute).Err(), "Set invalid JSON")
+
+	_, err := s.cache.GetFingerprint(s.ctx, 999)
+	require.Error(s.T(), err, "expected error for corrupted JSON")
+	require.False(s.T(), errors.Is(err, redis.Nil), "expected decoding error, not redis.Nil")
+}
+
+func (s *IdentityCacheSuite) TestSetFingerprint_Nil() {
+	err := s.cache.SetFingerprint(s.ctx, 100, nil)
+	require.NoError(s.T(), err, "SetFingerprint(nil) should succeed")
+}
+
+func TestIdentityCacheSuite(t *testing.T) {
+	suite.Run(t, new(IdentityCacheSuite))
+}

backend/internal/repository/integration_harness_test.go

@@ -0,0 +1,369 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"log"
+	"os"
+	"os/exec"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+
+	redisclient "github.com/redis/go-redis/v9"
+	tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres"
+	tcredis "github.com/testcontainers/testcontainers-go/modules/redis"
+	gormpostgres "gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+const (
+	redisImageTag    = "redis:8.4-alpine"
+	postgresImageTag = "postgres:18.1-alpine3.23"
+)
+
+var (
+	integrationDB    *gorm.DB
+	integrationRedis *redisclient.Client
+
+	redisNamespaceSeq uint64
+)
+
+func TestMain(m *testing.M) {
+	ctx := context.Background()
+
+	if err := timezone.Init("UTC"); err != nil {
+		log.Printf("failed to init timezone: %v", err)
+		os.Exit(1)
+	}
+
+	if !dockerIsAvailable(ctx) {
+		// In CI we expect Docker to be available so integration tests should fail loudly.
+		if os.Getenv("CI") != "" {
+			log.Printf("docker is not available (CI=true); failing integration tests")
+			os.Exit(1)
+		}
+		log.Printf("docker is not available; skipping integration tests (start Docker to enable)")
+		os.Exit(0)
+	}
+
+	postgresImage := selectDockerImage(ctx, postgresImageTag)
+	pgContainer, err := tcpostgres.Run(
+		ctx,
+		postgresImage,
+		tcpostgres.WithDatabase("sub2api_test"),
+		tcpostgres.WithUsername("postgres"),
+		tcpostgres.WithPassword("postgres"),
+		tcpostgres.BasicWaitStrategies(),
+	)
+	if err != nil {
+		log.Printf("failed to start postgres container: %v", err)
+		os.Exit(1)
+	}
+	defer func() { _ = pgContainer.Terminate(ctx) }()
+
+	redisContainer, err := tcredis.Run(
+		ctx,
+		redisImageTag,
+	)
+	if err != nil {
+		log.Printf("failed to start redis container: %v", err)
+		os.Exit(1)
+	}
+	defer func() { _ = redisContainer.Terminate(ctx) }()
+
+	dsn, err := pgContainer.ConnectionString(ctx, "sslmode=disable", "TimeZone=UTC")
+	if err != nil {
+		log.Printf("failed to get postgres dsn: %v", err)
+		os.Exit(1)
+	}
+
+	integrationDB, err = openGormWithRetry(ctx, dsn, 30*time.Second)
+	if err != nil {
+		log.Printf("failed to open gorm db: %v", err)
+		os.Exit(1)
+	}
+	if err := model.AutoMigrate(integrationDB); err != nil {
+		log.Printf("failed to automigrate db: %v", err)
+		os.Exit(1)
+	}
+
+	redisHost, err := redisContainer.Host(ctx)
+	if err != nil {
+		log.Printf("failed to get redis host: %v", err)
+		os.Exit(1)
+	}
+	redisPort, err := redisContainer.MappedPort(ctx, "6379/tcp")
+	if err != nil {
+		log.Printf("failed to get redis port: %v", err)
+		os.Exit(1)
+	}
+
+	integrationRedis = redisclient.NewClient(&redisclient.Options{
+		Addr: fmt.Sprintf("%s:%d", redisHost, redisPort.Int()),
+		DB:   0,
+	})
+	if err := integrationRedis.Ping(ctx).Err(); err != nil {
+		log.Printf("failed to ping redis: %v", err)
+		os.Exit(1)
+	}
+
+	code := m.Run()
+
+	_ = integrationRedis.Close()
+
+	os.Exit(code)
+}
+
+func dockerIsAvailable(ctx context.Context) bool {
+	cmd := exec.CommandContext(ctx, "docker", "info")
+	cmd.Env = os.Environ()
+	return cmd.Run() == nil
+}
+
+func selectDockerImage(ctx context.Context, preferred string) string {
+	if dockerImageExists(ctx, preferred) {
+		return preferred
+	}
+
+	return preferred
+}
+
+func dockerImageExists(ctx context.Context, image string) bool {
+	cmd := exec.CommandContext(ctx, "docker", "image", "inspect", image)
+	cmd.Env = os.Environ()
+	cmd.Stdout = nil
+	cmd.Stderr = nil
+	return cmd.Run() == nil
+}
+
+func openGormWithRetry(ctx context.Context, dsn string, timeout time.Duration) (*gorm.DB, error) {
+	deadline := time.Now().Add(timeout)
+	var lastErr error
+
+	for time.Now().Before(deadline) {
+		db, err := gorm.Open(gormpostgres.Open(dsn), &gorm.Config{
+			Logger: logger.Default.LogMode(logger.Silent),
+		})
+		if err != nil {
+			lastErr = err
+			time.Sleep(250 * time.Millisecond)
+			continue
+		}
+
+		sqlDB, err := db.DB()
+		if err != nil {
+			lastErr = err
+			time.Sleep(250 * time.Millisecond)
+			continue
+		}
+
+		if err := pingWithTimeout(ctx, sqlDB, 2*time.Second); err != nil {
+			lastErr = err
+			time.Sleep(250 * time.Millisecond)
+			continue
+		}
+
+		return db, nil
+	}
+
+	return nil, fmt.Errorf("db not ready after %s: %w", timeout, lastErr)
+}
+
+func pingWithTimeout(ctx context.Context, db *sql.DB, timeout time.Duration) error {
+	pingCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+	return db.PingContext(pingCtx)
+}
+
+func testTx(t *testing.T) *gorm.DB {
+	t.Helper()
+
+	tx := integrationDB.Begin()
+	require.NoError(t, tx.Error, "begin tx")
+	t.Cleanup(func() {
+		_ = tx.Rollback().Error
+	})
+	return tx
+}
+
+func testRedis(t *testing.T) *redisclient.Client {
+	t.Helper()
+
+	prefix := fmt.Sprintf(
+		"it:%s:%d:%d:",
+		sanitizeRedisNamespace(t.Name()),
+		time.Now().UnixNano(),
+		atomic.AddUint64(&redisNamespaceSeq, 1),
+	)
+
+	opts := *integrationRedis.Options()
+	rdb := redisclient.NewClient(&opts)
+	rdb.AddHook(prefixHook{prefix: prefix})
+
+	t.Cleanup(func() {
+		ctx := context.Background()
+
+		var cursor uint64
+		for {
+			keys, nextCursor, err := integrationRedis.Scan(ctx, cursor, prefix+"*", 500).Result()
+			require.NoError(t, err, "scan redis keys for cleanup")
+			if len(keys) > 0 {
+				require.NoError(t, integrationRedis.Unlink(ctx, keys...).Err(), "unlink redis keys for cleanup")
+			}
+
+			cursor = nextCursor
+			if cursor == 0 {
+				break
+			}
+		}
+
+		_ = rdb.Close()
+	})
+
+	return rdb
+}
+
+func assertTTLWithin(t *testing.T, ttl time.Duration, min, max time.Duration) {
+	t.Helper()
+	require.GreaterOrEqual(t, ttl, min, "ttl should be >= min")
+	require.LessOrEqual(t, ttl, max, "ttl should be <= max")
+}
+
+func sanitizeRedisNamespace(name string) string {
+	name = strings.ReplaceAll(name, "/", "_")
+	name = strings.ReplaceAll(name, " ", "_")
+	return name
+}
+
+type prefixHook struct {
+	prefix string
+}
+
+func (h prefixHook) DialHook(next redisclient.DialHook) redisclient.DialHook { return next }
+
+func (h prefixHook) ProcessHook(next redisclient.ProcessHook) redisclient.ProcessHook {
+	return func(ctx context.Context, cmd redisclient.Cmder) error {
+		h.prefixCmd(cmd)
+		return next(ctx, cmd)
+	}
+}
+
+func (h prefixHook) ProcessPipelineHook(next redisclient.ProcessPipelineHook) redisclient.ProcessPipelineHook {
+	return func(ctx context.Context, cmds []redisclient.Cmder) error {
+		for _, cmd := range cmds {
+			h.prefixCmd(cmd)
+		}
+		return next(ctx, cmds)
+	}
+}
+
+func (h prefixHook) prefixCmd(cmd redisclient.Cmder) {
+	args := cmd.Args()
+	if len(args) < 2 {
+		return
+	}
+
+	prefixOne := func(i int) {
+		if i < 0 || i >= len(args) {
+			return
+		}
+
+		switch v := args[i].(type) {
+		case string:
+			if v != "" && !strings.HasPrefix(v, h.prefix) {
+				args[i] = h.prefix + v
+			}
+		case []byte:
+			s := string(v)
+			if s != "" && !strings.HasPrefix(s, h.prefix) {
+				args[i] = []byte(h.prefix + s)
+			}
+		}
+	}
+
+	switch strings.ToLower(cmd.Name()) {
+	case "get", "set", "setnx", "setex", "psetex", "incr", "decr", "incrby", "expire", "pexpire", "ttl", "pttl",
+		"hgetall", "hget", "hset", "hdel", "hincrbyfloat", "exists":
+		prefixOne(1)
+	case "del", "unlink":
+		for i := 1; i < len(args); i++ {
+			prefixOne(i)
+		}
+	case "eval", "evalsha", "eval_ro", "evalsha_ro":
+		if len(args) < 3 {
+			return
+		}
+		numKeys, err := strconv.Atoi(fmt.Sprint(args[2]))
+		if err != nil || numKeys <= 0 {
+			return
+		}
+		for i := 0; i < numKeys && 3+i < len(args); i++ {
+			prefixOne(3 + i)
+		}
+	case "scan":
+		for i := 2; i+1 < len(args); i++ {
+			if strings.EqualFold(fmt.Sprint(args[i]), "match") {
+				prefixOne(i + 1)
+				break
+			}
+		}
+	}
+}
+
+// IntegrationRedisSuite provides a base suite for Redis integration tests.
+// Embedding suites should call SetupTest to initialize ctx and rdb.
+type IntegrationRedisSuite struct {
+	suite.Suite
+	ctx context.Context
+	rdb *redisclient.Client
+}
+
+// SetupTest initializes ctx and rdb for each test method.
+func (s *IntegrationRedisSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.rdb = testRedis(s.T())
+}
+
+// RequireNoError is a convenience method wrapping require.NoError with s.T().
+func (s *IntegrationRedisSuite) RequireNoError(err error, msgAndArgs ...any) {
+	s.T().Helper()
+	require.NoError(s.T(), err, msgAndArgs...)
+}
+
+// AssertTTLWithin asserts that ttl is within [min, max].
+func (s *IntegrationRedisSuite) AssertTTLWithin(ttl, min, max time.Duration) {
+	s.T().Helper()
+	assertTTLWithin(s.T(), ttl, min, max)
+}
+
+// IntegrationDBSuite provides a base suite for DB (Gorm) integration tests.
+// Embedding suites should call SetupTest to initialize ctx and db.
+type IntegrationDBSuite struct {
+	suite.Suite
+	ctx context.Context
+	db  *gorm.DB
+}
+
+// SetupTest initializes ctx and db for each test method.
+func (s *IntegrationDBSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+}
+
+// RequireNoError is a convenience method wrapping require.NoError with s.T().
+func (s *IntegrationDBSuite) RequireNoError(err error, msgAndArgs ...any) {
+	s.T().Helper()
+	require.NoError(s.T(), err, msgAndArgs...)
+}

backend/internal/repository/openai_oauth_service.go

@@ -6,17 +6,18 @@ import (
 	"net/url"
 	"time"
 
-	"sub2api/internal/pkg/openai"
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/imroc/req/v3"
 )
 
-type openaiOAuthService struct{}
-
 // NewOpenAIOAuthClient creates a new OpenAI OAuth client
-func NewOpenAIOAuthClient() ports.OpenAIOAuthClient {
-	return &openaiOAuthService{}
+func NewOpenAIOAuthClient() service.OpenAIOAuthClient {
+	return &openaiOAuthService{tokenURL: openai.TokenURL}
+}
+
+type openaiOAuthService struct {
+	tokenURL string
 }
 
 func (s *openaiOAuthService) ExchangeCode(ctx context.Context, code, codeVerifier, redirectURI, proxyURL string) (*openai.TokenResponse, error) {
@@ -39,7 +40,7 @@ func (s *openaiOAuthService) ExchangeCode(ctx context.Context, code, codeVerifie
 		SetContext(ctx).
 		SetFormDataFromValues(formData).
 		SetSuccessResult(&tokenResp).
-		Post(openai.TokenURL)
+		Post(s.tokenURL)
 
 	if err != nil {
 		return nil, fmt.Errorf("request failed: %w", err)
@@ -67,7 +68,7 @@ func (s *openaiOAuthService) RefreshToken(ctx context.Context, refreshToken, pro
 		SetContext(ctx).
 		SetFormDataFromValues(formData).
 		SetSuccessResult(&tokenResp).
-		Post(openai.TokenURL)
+		Post(s.tokenURL)
 
 	if err != nil {
 		return nil, fmt.Errorf("request failed: %w", err)

backend/internal/repository/openai_oauth_service_test.go

@@ -0,0 +1,249 @@
+package repository
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type OpenAIOAuthServiceSuite struct {
+	suite.Suite
+	ctx      context.Context
+	srv      *httptest.Server
+	svc      *openaiOAuthService
+	received chan url.Values
+}
+
+func (s *OpenAIOAuthServiceSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.received = make(chan url.Values, 1)
+}
+
+func (s *OpenAIOAuthServiceSuite) TearDownTest() {
+	if s.srv != nil {
+		s.srv.Close()
+		s.srv = nil
+	}
+}
+
+func (s *OpenAIOAuthServiceSuite) setupServer(handler http.HandlerFunc) {
+	s.srv = httptest.NewServer(handler)
+	s.svc = &openaiOAuthService{tokenURL: s.srv.URL}
+}
+
+func (s *OpenAIOAuthServiceSuite) TestExchangeCode_DefaultRedirectURI() {
+	errCh := make(chan string, 1)
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			errCh <- "method mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if err := r.ParseForm(); err != nil {
+			errCh <- "ParseForm failed"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("grant_type"); got != "authorization_code" {
+			errCh <- "grant_type mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("client_id"); got != openai.ClientID {
+			errCh <- "client_id mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("code"); got != "code" {
+			errCh <- "code mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("redirect_uri"); got != openai.DefaultRedirectURI {
+			errCh <- "redirect_uri mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("code_verifier"); got != "ver" {
+			errCh <- "code_verifier mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"access_token":"at","refresh_token":"rt","token_type":"bearer","expires_in":3600}`)
+	}))
+
+	resp, err := s.svc.ExchangeCode(s.ctx, "code", "ver", "", "")
+	require.NoError(s.T(), err, "ExchangeCode")
+	select {
+	case msg := <-errCh:
+		require.Fail(s.T(), msg)
+	default:
+	}
+	require.Equal(s.T(), "at", resp.AccessToken)
+	require.Equal(s.T(), "rt", resp.RefreshToken)
+}
+
+func (s *OpenAIOAuthServiceSuite) TestRefreshToken_FormFields() {
+	errCh := make(chan string, 1)
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseForm(); err != nil {
+			errCh <- "ParseForm failed"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("grant_type"); got != "refresh_token" {
+			errCh <- "grant_type mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("refresh_token"); got != "rt" {
+			errCh <- "refresh_token mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("client_id"); got != openai.ClientID {
+			errCh <- "client_id mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if got := r.PostForm.Get("scope"); got != openai.RefreshScopes {
+			errCh <- "scope mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"access_token":"at2","refresh_token":"rt2","token_type":"bearer","expires_in":3600}`)
+	}))
+
+	resp, err := s.svc.RefreshToken(s.ctx, "rt", "")
+	require.NoError(s.T(), err, "RefreshToken")
+	select {
+	case msg := <-errCh:
+		require.Fail(s.T(), msg)
+	default:
+	}
+	require.Equal(s.T(), "at2", resp.AccessToken)
+	require.Equal(s.T(), "rt2", resp.RefreshToken)
+}
+
+func (s *OpenAIOAuthServiceSuite) TestNonSuccessStatus_IncludesBody() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = io.WriteString(w, "bad")
+	}))
+
+	_, err := s.svc.ExchangeCode(s.ctx, "code", "ver", openai.DefaultRedirectURI, "")
+	require.Error(s.T(), err)
+	require.ErrorContains(s.T(), err, "status 400")
+	require.ErrorContains(s.T(), err, "bad")
+}
+
+func (s *OpenAIOAuthServiceSuite) TestRequestError_ClosedServer() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+	s.srv.Close()
+
+	_, err := s.svc.ExchangeCode(s.ctx, "code", "ver", openai.DefaultRedirectURI, "")
+	require.Error(s.T(), err)
+	require.ErrorContains(s.T(), err, "request failed")
+}
+
+func (s *OpenAIOAuthServiceSuite) TestContextCancel() {
+	started := make(chan struct{})
+	block := make(chan struct{})
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		close(started)
+		<-block
+	}))
+
+	ctx, cancel := context.WithCancel(s.ctx)
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := s.svc.ExchangeCode(ctx, "code", "ver", openai.DefaultRedirectURI, "")
+		done <- err
+	}()
+
+	<-started
+	cancel()
+	close(block)
+
+	err := <-done
+	require.Error(s.T(), err)
+}
+
+func (s *OpenAIOAuthServiceSuite) TestExchangeCode_UsesProvidedRedirectURI() {
+	want := "http://localhost:9999/cb"
+	errCh := make(chan string, 1)
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = r.ParseForm()
+		if got := r.PostForm.Get("redirect_uri"); got != want {
+			errCh <- "redirect_uri mismatch"
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"access_token":"at","token_type":"bearer","expires_in":1}`)
+	}))
+
+	_, err := s.svc.ExchangeCode(s.ctx, "code", "ver", want, "")
+	require.NoError(s.T(), err, "ExchangeCode")
+	select {
+	case msg := <-errCh:
+		require.Fail(s.T(), msg)
+	default:
+	}
+}
+
+func (s *OpenAIOAuthServiceSuite) TestTokenURL_CanBeOverriddenWithQuery() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = r.ParseForm()
+		s.received <- r.PostForm
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"access_token":"at","token_type":"bearer","expires_in":1}`)
+	}))
+	s.svc.tokenURL = s.srv.URL + "?x=1"
+
+	_, err := s.svc.ExchangeCode(s.ctx, "code", "ver", openai.DefaultRedirectURI, "")
+	require.NoError(s.T(), err, "ExchangeCode")
+	select {
+	case <-s.received:
+	default:
+		require.Fail(s.T(), "expected server to receive request")
+	}
+}
+
+func (s *OpenAIOAuthServiceSuite) TestExchangeCode_SuccessButInvalidJSON() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		_, _ = io.WriteString(w, "not-valid-json")
+	}))
+
+	_, err := s.svc.ExchangeCode(s.ctx, "code", "ver", openai.DefaultRedirectURI, "")
+	require.Error(s.T(), err, "expected error for invalid JSON response")
+}
+
+func (s *OpenAIOAuthServiceSuite) TestRefreshToken_NonSuccessStatus() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+		_, _ = io.WriteString(w, "unauthorized")
+	}))
+
+	_, err := s.svc.RefreshToken(s.ctx, "rt", "")
+	require.Error(s.T(), err, "expected error for non-2xx status")
+	require.ErrorContains(s.T(), err, "status 401")
+}
+
+func TestOpenAIOAuthServiceSuite(t *testing.T) {
+	suite.Run(t, new(OpenAIOAuthServiceSuite))
+}

backend/internal/repository/pricing_service.go

@@ -8,7 +8,7 @@ import (
 	"strings"
 	"time"
 
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 )
 
 type pricingRemoteClient struct {

backend/internal/repository/pricing_service_test.go

@@ -0,0 +1,147 @@
+package repository
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type PricingServiceSuite struct {
+	suite.Suite
+	ctx    context.Context
+	srv    *httptest.Server
+	client *pricingRemoteClient
+}
+
+func (s *PricingServiceSuite) SetupTest() {
+	s.ctx = context.Background()
+	client, ok := NewPricingRemoteClient().(*pricingRemoteClient)
+	require.True(s.T(), ok, "type assertion failed")
+	s.client = client
+}
+
+func (s *PricingServiceSuite) TearDownTest() {
+	if s.srv != nil {
+		s.srv.Close()
+		s.srv = nil
+	}
+}
+
+func (s *PricingServiceSuite) setupServer(handler http.HandlerFunc) {
+	s.srv = httptest.NewServer(handler)
+}
+
+func (s *PricingServiceSuite) TestFetchPricingJSON_Success() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/ok" {
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte(`{"ok":true}`))
+			return
+		}
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+
+	body, err := s.client.FetchPricingJSON(s.ctx, s.srv.URL+"/ok")
+	require.NoError(s.T(), err, "FetchPricingJSON")
+	require.Equal(s.T(), `{"ok":true}`, string(body), "body mismatch")
+}
+
+func (s *PricingServiceSuite) TestFetchPricingJSON_NonOKStatus() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+
+	_, err := s.client.FetchPricingJSON(s.ctx, s.srv.URL+"/err")
+	require.Error(s.T(), err, "expected error for non-200 status")
+}
+
+func (s *PricingServiceSuite) TestFetchHashText_ParsesFields() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/hashfile":
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte("abc123  model_prices.json\n"))
+		case "/hashonly":
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte("def456\n"))
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+
+	hash, err := s.client.FetchHashText(s.ctx, s.srv.URL+"/hashfile")
+	require.NoError(s.T(), err, "FetchHashText")
+	require.Equal(s.T(), "abc123", hash, "hash mismatch")
+
+	hash2, err := s.client.FetchHashText(s.ctx, s.srv.URL+"/hashonly")
+	require.NoError(s.T(), err, "FetchHashText")
+	require.Equal(s.T(), "def456", hash2, "hash mismatch")
+}
+
+func (s *PricingServiceSuite) TestFetchHashText_NonOKStatus() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+
+	_, err := s.client.FetchHashText(s.ctx, s.srv.URL+"/nope")
+	require.Error(s.T(), err, "expected error for non-200 status")
+}
+
+func (s *PricingServiceSuite) TestFetchPricingJSON_InvalidURL() {
+	_, err := s.client.FetchPricingJSON(s.ctx, "://invalid-url")
+	require.Error(s.T(), err, "expected error for invalid URL")
+}
+
+func (s *PricingServiceSuite) TestFetchHashText_EmptyBody() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		// empty body
+	}))
+
+	hash, err := s.client.FetchHashText(s.ctx, s.srv.URL+"/empty")
+	require.NoError(s.T(), err, "FetchHashText empty body should not error")
+	require.Equal(s.T(), "", hash, "expected empty hash")
+}
+
+func (s *PricingServiceSuite) TestFetchHashText_WhitespaceOnly() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("   \n"))
+	}))
+
+	hash, err := s.client.FetchHashText(s.ctx, s.srv.URL+"/ws")
+	require.NoError(s.T(), err, "FetchHashText whitespace body should not error")
+	require.Equal(s.T(), "", hash, "expected empty hash after trimming")
+}
+
+func (s *PricingServiceSuite) TestFetchPricingJSON_ContextCancel() {
+	started := make(chan struct{})
+	block := make(chan struct{})
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		close(started)
+		<-block
+	}))
+
+	ctx, cancel := context.WithCancel(s.ctx)
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := s.client.FetchPricingJSON(ctx, s.srv.URL+"/block")
+		done <- err
+	}()
+
+	<-started
+	cancel()
+	close(block)
+
+	err := <-done
+	require.Error(s.T(), err)
+}
+
+func TestPricingServiceSuite(t *testing.T) {
+	suite.Run(t, new(PricingServiceSuite))
+}

backend/internal/repository/proxy_probe_service.go

@@ -11,15 +11,19 @@ import (
 	"net/url"
 	"time"
 
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"golang.org/x/net/proxy"
 )
 
-type proxyProbeService struct{}
-
 func NewProxyExitInfoProber() service.ProxyExitInfoProber {
-	return &proxyProbeService{}
+	return &proxyProbeService{ipInfoURL: defaultIPInfoURL}
+}
+
+const defaultIPInfoURL = "https://ipinfo.io/json"
+
+type proxyProbeService struct {
+	ipInfoURL string
 }
 
 func (s *proxyProbeService) ProbeProxy(ctx context.Context, proxyURL string) (*service.ProxyExitInfo, int64, error) {
@@ -34,7 +38,7 @@ func (s *proxyProbeService) ProbeProxy(ctx context.Context, proxyURL string) (*s
 	}
 
 	startTime := time.Now()
-	req, err := http.NewRequestWithContext(ctx, "GET", "https://ipinfo.io/json", nil)
+	req, err := http.NewRequestWithContext(ctx, "GET", s.ipInfoURL, nil)
 	if err != nil {
 		return nil, 0, fmt.Errorf("failed to create request: %w", err)
 	}

backend/internal/repository/proxy_probe_service_test.go

@@ -0,0 +1,121 @@
+package repository
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type ProxyProbeServiceSuite struct {
+	suite.Suite
+	ctx      context.Context
+	proxySrv *httptest.Server
+	prober   *proxyProbeService
+}
+
+func (s *ProxyProbeServiceSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.prober = &proxyProbeService{ipInfoURL: "http://ipinfo.test/json"}
+}
+
+func (s *ProxyProbeServiceSuite) TearDownTest() {
+	if s.proxySrv != nil {
+		s.proxySrv.Close()
+		s.proxySrv = nil
+	}
+}
+
+func (s *ProxyProbeServiceSuite) setupProxyServer(handler http.HandlerFunc) {
+	s.proxySrv = httptest.NewServer(handler)
+}
+
+func (s *ProxyProbeServiceSuite) TestCreateProxyTransport_InvalidURL() {
+	_, err := createProxyTransport("://bad")
+	require.Error(s.T(), err)
+	require.ErrorContains(s.T(), err, "invalid proxy URL")
+}
+
+func (s *ProxyProbeServiceSuite) TestCreateProxyTransport_UnsupportedScheme() {
+	_, err := createProxyTransport("ftp://127.0.0.1:1")
+	require.Error(s.T(), err)
+	require.ErrorContains(s.T(), err, "unsupported proxy protocol")
+}
+
+func (s *ProxyProbeServiceSuite) TestCreateProxyTransport_Socks5SetsDialer() {
+	tr, err := createProxyTransport("socks5://127.0.0.1:1080")
+	require.NoError(s.T(), err, "createProxyTransport")
+	require.NotNil(s.T(), tr.DialContext, "expected DialContext to be set for socks5")
+}
+
+func (s *ProxyProbeServiceSuite) TestProbeProxy_Success() {
+	seen := make(chan string, 1)
+	s.setupProxyServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen <- r.RequestURI
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"ip":"1.2.3.4","city":"c","region":"r","country":"cc"}`)
+	}))
+
+	info, latencyMs, err := s.prober.ProbeProxy(s.ctx, s.proxySrv.URL)
+	require.NoError(s.T(), err, "ProbeProxy")
+	require.GreaterOrEqual(s.T(), latencyMs, int64(0), "unexpected latency")
+	require.Equal(s.T(), "1.2.3.4", info.IP)
+	require.Equal(s.T(), "c", info.City)
+	require.Equal(s.T(), "r", info.Region)
+	require.Equal(s.T(), "cc", info.Country)
+
+	// Verify proxy received the request
+	select {
+	case uri := <-seen:
+		require.Contains(s.T(), uri, "ipinfo.test", "expected request to go through proxy")
+	default:
+		require.Fail(s.T(), "expected proxy to receive request")
+	}
+}
+
+func (s *ProxyProbeServiceSuite) TestProbeProxy_NonOKStatus() {
+	s.setupProxyServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	}))
+
+	_, _, err := s.prober.ProbeProxy(s.ctx, s.proxySrv.URL)
+	require.Error(s.T(), err)
+	require.ErrorContains(s.T(), err, "status: 503")
+}
+
+func (s *ProxyProbeServiceSuite) TestProbeProxy_InvalidJSON() {
+	s.setupProxyServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, "not-json")
+	}))
+
+	_, _, err := s.prober.ProbeProxy(s.ctx, s.proxySrv.URL)
+	require.Error(s.T(), err)
+	require.ErrorContains(s.T(), err, "failed to parse response")
+}
+
+func (s *ProxyProbeServiceSuite) TestProbeProxy_InvalidIPInfoURL() {
+	s.prober.ipInfoURL = "://invalid-url"
+	s.setupProxyServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	_, _, err := s.prober.ProbeProxy(s.ctx, s.proxySrv.URL)
+	require.Error(s.T(), err, "expected error for invalid ipInfoURL")
+}
+
+func (s *ProxyProbeServiceSuite) TestProbeProxy_ProxyServerClosed() {
+	s.setupProxyServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+	s.proxySrv.Close()
+
+	_, _, err := s.prober.ProbeProxy(s.ctx, s.proxySrv.URL)
+	require.Error(s.T(), err, "expected error when proxy server is closed")
+}
+
+func TestProxyProbeServiceSuite(t *testing.T) {
+	suite.Run(t, new(ProxyProbeServiceSuite))
+}

backend/internal/repository/proxy_repo.go

@@ -2,47 +2,50 @@ package repository
 
 import (
 	"context"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
 )
 
-type ProxyRepository struct {
+type proxyRepository struct {
 	db *gorm.DB
 }
 
-func NewProxyRepository(db *gorm.DB) *ProxyRepository {
-	return &ProxyRepository{db: db}
+func NewProxyRepository(db *gorm.DB) service.ProxyRepository {
+	return &proxyRepository{db: db}
 }
 
-func (r *ProxyRepository) Create(ctx context.Context, proxy *model.Proxy) error {
+func (r *proxyRepository) Create(ctx context.Context, proxy *model.Proxy) error {
 	return r.db.WithContext(ctx).Create(proxy).Error
 }
 
-func (r *ProxyRepository) GetByID(ctx context.Context, id int64) (*model.Proxy, error) {
+func (r *proxyRepository) GetByID(ctx context.Context, id int64) (*model.Proxy, error) {
 	var proxy model.Proxy
 	err := r.db.WithContext(ctx).First(&proxy, id).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrProxyNotFound, nil)
 	}
 	return &proxy, nil
 }
 
-func (r *ProxyRepository) Update(ctx context.Context, proxy *model.Proxy) error {
+func (r *proxyRepository) Update(ctx context.Context, proxy *model.Proxy) error {
 	return r.db.WithContext(ctx).Save(proxy).Error
 }
 
-func (r *ProxyRepository) Delete(ctx context.Context, id int64) error {
+func (r *proxyRepository) Delete(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Delete(&model.Proxy{}, id).Error
 }
 
-func (r *ProxyRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.Proxy, *pagination.PaginationResult, error) {
+func (r *proxyRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.Proxy, *pagination.PaginationResult, error) {
 	return r.ListWithFilters(ctx, params, "", "", "")
 }
 
 // ListWithFilters lists proxies with optional filtering by protocol, status, and search query
-func (r *ProxyRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, protocol, status, search string) ([]model.Proxy, *pagination.PaginationResult, error) {
+func (r *proxyRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, protocol, status, search string) ([]model.Proxy, *pagination.PaginationResult, error) {
 	var proxies []model.Proxy
 	var total int64
 
@@ -81,14 +84,14 @@ func (r *ProxyRepository) ListWithFilters(ctx context.Context, params pagination
 	}, nil
 }
 
-func (r *ProxyRepository) ListActive(ctx context.Context) ([]model.Proxy, error) {
+func (r *proxyRepository) ListActive(ctx context.Context) ([]model.Proxy, error) {
 	var proxies []model.Proxy
 	err := r.db.WithContext(ctx).Where("status = ?", model.StatusActive).Find(&proxies).Error
 	return proxies, err
 }
 
 // ExistsByHostPortAuth checks if a proxy with the same host, port, username, and password exists
-func (r *ProxyRepository) ExistsByHostPortAuth(ctx context.Context, host string, port int, username, password string) (bool, error) {
+func (r *proxyRepository) ExistsByHostPortAuth(ctx context.Context, host string, port int, username, password string) (bool, error) {
 	var count int64
 	err := r.db.WithContext(ctx).Model(&model.Proxy{}).
 		Where("host = ? AND port = ? AND username = ? AND password = ?", host, port, username, password).
@@ -100,7 +103,7 @@ func (r *ProxyRepository) ExistsByHostPortAuth(ctx context.Context, host string,
 }
 
 // CountAccountsByProxyID returns the number of accounts using a specific proxy
-func (r *ProxyRepository) CountAccountsByProxyID(ctx context.Context, proxyID int64) (int64, error) {
+func (r *proxyRepository) CountAccountsByProxyID(ctx context.Context, proxyID int64) (int64, error) {
 	var count int64
 	err := r.db.WithContext(ctx).Model(&model.Account{}).
 		Where("proxy_id = ?", proxyID).
@@ -109,7 +112,7 @@ func (r *ProxyRepository) CountAccountsByProxyID(ctx context.Context, proxyID in
 }
 
 // GetAccountCountsForProxies returns a map of proxy ID to account count for all proxies
-func (r *ProxyRepository) GetAccountCountsForProxies(ctx context.Context) (map[int64]int64, error) {
+func (r *proxyRepository) GetAccountCountsForProxies(ctx context.Context) (map[int64]int64, error) {
 	type result struct {
 		ProxyID int64 `gorm:"column:proxy_id"`
 		Count   int64 `gorm:"column:count"`
@@ -133,7 +136,7 @@ func (r *ProxyRepository) GetAccountCountsForProxies(ctx context.Context) (map[i
 }
 
 // ListActiveWithAccountCount returns all active proxies with account count, sorted by creation time descending
-func (r *ProxyRepository) ListActiveWithAccountCount(ctx context.Context) ([]model.ProxyWithAccountCount, error) {
+func (r *proxyRepository) ListActiveWithAccountCount(ctx context.Context) ([]model.ProxyWithAccountCount, error) {
 	var proxies []model.Proxy
 	err := r.db.WithContext(ctx).
 		Where("status = ?", model.StatusActive).

backend/internal/repository/proxy_repo_integration_test.go

@@ -0,0 +1,302 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/stretchr/testify/suite"
+	"gorm.io/gorm"
+)
+
+type ProxyRepoSuite struct {
+	suite.Suite
+	ctx  context.Context
+	db   *gorm.DB
+	repo *proxyRepository
+}
+
+func (s *ProxyRepoSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+	s.repo = NewProxyRepository(s.db).(*proxyRepository)
+}
+
+func TestProxyRepoSuite(t *testing.T) {
+	suite.Run(t, new(ProxyRepoSuite))
+}
+
+// --- Create / GetByID / Update / Delete ---
+
+func (s *ProxyRepoSuite) TestCreate() {
+	proxy := &model.Proxy{
+		Name:     "test-create",
+		Protocol: "http",
+		Host:     "127.0.0.1",
+		Port:     8080,
+		Status:   model.StatusActive,
+	}
+
+	err := s.repo.Create(s.ctx, proxy)
+	s.Require().NoError(err, "Create")
+	s.Require().NotZero(proxy.ID, "expected ID to be set")
+
+	got, err := s.repo.GetByID(s.ctx, proxy.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal("test-create", got.Name)
+}
+
+func (s *ProxyRepoSuite) TestGetByID_NotFound() {
+	_, err := s.repo.GetByID(s.ctx, 999999)
+	s.Require().Error(err, "expected error for non-existent ID")
+}
+
+func (s *ProxyRepoSuite) TestUpdate() {
+	proxy := mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "original"})
+
+	proxy.Name = "updated"
+	err := s.repo.Update(s.ctx, proxy)
+	s.Require().NoError(err, "Update")
+
+	got, err := s.repo.GetByID(s.ctx, proxy.ID)
+	s.Require().NoError(err, "GetByID after update")
+	s.Require().Equal("updated", got.Name)
+}
+
+func (s *ProxyRepoSuite) TestDelete() {
+	proxy := mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "to-delete"})
+
+	err := s.repo.Delete(s.ctx, proxy.ID)
+	s.Require().NoError(err, "Delete")
+
+	_, err = s.repo.GetByID(s.ctx, proxy.ID)
+	s.Require().Error(err, "expected error after delete")
+}
+
+// --- List / ListWithFilters ---
+
+func (s *ProxyRepoSuite) TestList() {
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p1"})
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p2"})
+
+	proxies, page, err := s.repo.List(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "List")
+	s.Require().Len(proxies, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+func (s *ProxyRepoSuite) TestListWithFilters_Protocol() {
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p1", Protocol: "http"})
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p2", Protocol: "socks5"})
+
+	proxies, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "socks5", "", "")
+	s.Require().NoError(err)
+	s.Require().Len(proxies, 1)
+	s.Require().Equal("socks5", proxies[0].Protocol)
+}
+
+func (s *ProxyRepoSuite) TestListWithFilters_Status() {
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p1", Status: model.StatusActive})
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p2", Status: model.StatusDisabled})
+
+	proxies, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", model.StatusDisabled, "")
+	s.Require().NoError(err)
+	s.Require().Len(proxies, 1)
+	s.Require().Equal(model.StatusDisabled, proxies[0].Status)
+}
+
+func (s *ProxyRepoSuite) TestListWithFilters_Search() {
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "production-proxy"})
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "dev-proxy"})
+
+	proxies, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", "prod")
+	s.Require().NoError(err)
+	s.Require().Len(proxies, 1)
+	s.Require().Contains(proxies[0].Name, "production")
+}
+
+// --- ListActive ---
+
+func (s *ProxyRepoSuite) TestListActive() {
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "active1", Status: model.StatusActive})
+	mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "inactive1", Status: model.StatusDisabled})
+
+	proxies, err := s.repo.ListActive(s.ctx)
+	s.Require().NoError(err, "ListActive")
+	s.Require().Len(proxies, 1)
+	s.Require().Equal("active1", proxies[0].Name)
+}
+
+// --- ExistsByHostPortAuth ---
+
+func (s *ProxyRepoSuite) TestExistsByHostPortAuth() {
+	mustCreateProxy(s.T(), s.db, &model.Proxy{
+		Name:     "p1",
+		Protocol: "http",
+		Host:     "1.2.3.4",
+		Port:     8080,
+		Username: "user",
+		Password: "pass",
+	})
+
+	exists, err := s.repo.ExistsByHostPortAuth(s.ctx, "1.2.3.4", 8080, "user", "pass")
+	s.Require().NoError(err, "ExistsByHostPortAuth")
+	s.Require().True(exists)
+
+	notExists, err := s.repo.ExistsByHostPortAuth(s.ctx, "1.2.3.4", 8080, "wrong", "creds")
+	s.Require().NoError(err)
+	s.Require().False(notExists)
+}
+
+func (s *ProxyRepoSuite) TestExistsByHostPortAuth_NoAuth() {
+	mustCreateProxy(s.T(), s.db, &model.Proxy{
+		Name:     "p-noauth",
+		Protocol: "http",
+		Host:     "5.6.7.8",
+		Port:     8081,
+		Username: "",
+		Password: "",
+	})
+
+	exists, err := s.repo.ExistsByHostPortAuth(s.ctx, "5.6.7.8", 8081, "", "")
+	s.Require().NoError(err)
+	s.Require().True(exists)
+}
+
+// --- CountAccountsByProxyID ---
+
+func (s *ProxyRepoSuite) TestCountAccountsByProxyID() {
+	proxy := mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p-count"})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1", ProxyID: &proxy.ID})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2", ProxyID: &proxy.ID})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a3"}) // no proxy
+
+	count, err := s.repo.CountAccountsByProxyID(s.ctx, proxy.ID)
+	s.Require().NoError(err, "CountAccountsByProxyID")
+	s.Require().Equal(int64(2), count)
+}
+
+func (s *ProxyRepoSuite) TestCountAccountsByProxyID_Zero() {
+	proxy := mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p-zero"})
+
+	count, err := s.repo.CountAccountsByProxyID(s.ctx, proxy.ID)
+	s.Require().NoError(err)
+	s.Require().Zero(count)
+}
+
+// --- GetAccountCountsForProxies ---
+
+func (s *ProxyRepoSuite) TestGetAccountCountsForProxies() {
+	p1 := mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p1"})
+	p2 := mustCreateProxy(s.T(), s.db, &model.Proxy{Name: "p2"})
+
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1", ProxyID: &p1.ID})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2", ProxyID: &p1.ID})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a3", ProxyID: &p2.ID})
+
+	counts, err := s.repo.GetAccountCountsForProxies(s.ctx)
+	s.Require().NoError(err, "GetAccountCountsForProxies")
+	s.Require().Equal(int64(2), counts[p1.ID])
+	s.Require().Equal(int64(1), counts[p2.ID])
+}
+
+func (s *ProxyRepoSuite) TestGetAccountCountsForProxies_Empty() {
+	counts, err := s.repo.GetAccountCountsForProxies(s.ctx)
+	s.Require().NoError(err)
+	s.Require().Empty(counts)
+}
+
+// --- ListActiveWithAccountCount ---
+
+func (s *ProxyRepoSuite) TestListActiveWithAccountCount() {
+	base := time.Date(2025, 1, 1, 12, 0, 0, 0, time.UTC)
+
+	p1 := mustCreateProxy(s.T(), s.db, &model.Proxy{
+		Name:      "p1",
+		Status:    model.StatusActive,
+		CreatedAt: base.Add(-1 * time.Hour),
+	})
+	p2 := mustCreateProxy(s.T(), s.db, &model.Proxy{
+		Name:      "p2",
+		Status:    model.StatusActive,
+		CreatedAt: base,
+	})
+	mustCreateProxy(s.T(), s.db, &model.Proxy{
+		Name:   "p3-inactive",
+		Status: model.StatusDisabled,
+	})
+
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1", ProxyID: &p1.ID})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2", ProxyID: &p1.ID})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a3", ProxyID: &p2.ID})
+
+	withCounts, err := s.repo.ListActiveWithAccountCount(s.ctx)
+	s.Require().NoError(err, "ListActiveWithAccountCount")
+	s.Require().Len(withCounts, 2, "expected 2 active proxies")
+
+	// Sorted by created_at DESC, so p2 first
+	s.Require().Equal(p2.ID, withCounts[0].ID)
+	s.Require().Equal(int64(1), withCounts[0].AccountCount)
+	s.Require().Equal(p1.ID, withCounts[1].ID)
+	s.Require().Equal(int64(2), withCounts[1].AccountCount)
+}
+
+// --- Combined original test ---
+
+func (s *ProxyRepoSuite) TestExistsByHostPortAuth_And_AccountCountAggregates() {
+	p1 := mustCreateProxy(s.T(), s.db, &model.Proxy{
+		Name:      "p1",
+		Protocol:  "http",
+		Host:      "1.2.3.4",
+		Port:      8080,
+		Username:  "u",
+		Password:  "p",
+		CreatedAt: time.Now().Add(-1 * time.Hour),
+		UpdatedAt: time.Now().Add(-1 * time.Hour),
+	})
+	p2 := mustCreateProxy(s.T(), s.db, &model.Proxy{
+		Name:      "p2",
+		Protocol:  "http",
+		Host:      "5.6.7.8",
+		Port:      8081,
+		Username:  "",
+		Password:  "",
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	})
+
+	exists, err := s.repo.ExistsByHostPortAuth(s.ctx, "1.2.3.4", 8080, "u", "p")
+	s.Require().NoError(err, "ExistsByHostPortAuth")
+	s.Require().True(exists, "expected proxy to exist")
+
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a1", ProxyID: &p1.ID})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a2", ProxyID: &p1.ID})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a3", ProxyID: &p2.ID})
+
+	count1, err := s.repo.CountAccountsByProxyID(s.ctx, p1.ID)
+	s.Require().NoError(err, "CountAccountsByProxyID")
+	s.Require().Equal(int64(2), count1, "expected 2 accounts for p1")
+
+	counts, err := s.repo.GetAccountCountsForProxies(s.ctx)
+	s.Require().NoError(err, "GetAccountCountsForProxies")
+	s.Require().Equal(int64(2), counts[p1.ID])
+	s.Require().Equal(int64(1), counts[p2.ID])
+
+	withCounts, err := s.repo.ListActiveWithAccountCount(s.ctx)
+	s.Require().NoError(err, "ListActiveWithAccountCount")
+	s.Require().Len(withCounts, 2, "expected 2 proxies")
+	for _, pc := range withCounts {
+		switch pc.ID {
+		case p1.ID:
+			s.Require().Equal(int64(2), pc.AccountCount, "p1 count mismatch")
+		case p2.ID:
+			s.Require().Equal(int64(1), pc.AccountCount, "p2 count mismatch")
+		default:
+			s.Require().Fail("unexpected proxy id", pc.ID)
+		}
+	}
+}

backend/internal/repository/redeem_cache.go

@@ -5,8 +5,7 @@ import (
 	"fmt"
 	"time"
 
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 )
 
@@ -20,7 +19,7 @@ type redeemCache struct {
 	rdb *redis.Client
 }
 
-func NewRedeemCache(rdb *redis.Client) ports.RedeemCache {
+func NewRedeemCache(rdb *redis.Client) service.RedeemCache {
 	return &redeemCache{rdb: rdb}
 }
 

backend/internal/repository/redeem_cache_integration_test.go

@@ -0,0 +1,105 @@
+//go:build integration
+
+package repository
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type RedeemCacheSuite struct {
+	IntegrationRedisSuite
+	cache *redeemCache
+}
+
+func (s *RedeemCacheSuite) SetupTest() {
+	s.IntegrationRedisSuite.SetupTest()
+	s.cache = NewRedeemCache(s.rdb).(*redeemCache)
+}
+
+func (s *RedeemCacheSuite) TestGetRedeemAttemptCount_Missing() {
+	missingUserID := int64(99999)
+	_, err := s.cache.GetRedeemAttemptCount(s.ctx, missingUserID)
+	require.Error(s.T(), err, "expected redis.Nil for missing rate-limit key")
+	require.True(s.T(), errors.Is(err, redis.Nil))
+}
+
+func (s *RedeemCacheSuite) TestIncrementAndGetRedeemAttemptCount() {
+	userID := int64(1)
+	key := fmt.Sprintf("%s%d", redeemRateLimitKeyPrefix, userID)
+
+	require.NoError(s.T(), s.cache.IncrementRedeemAttemptCount(s.ctx, userID), "IncrementRedeemAttemptCount")
+	count, err := s.cache.GetRedeemAttemptCount(s.ctx, userID)
+	require.NoError(s.T(), err, "GetRedeemAttemptCount")
+	require.Equal(s.T(), 1, count, "count mismatch")
+
+	ttl, err := s.rdb.TTL(s.ctx, key).Result()
+	require.NoError(s.T(), err, "TTL")
+	s.AssertTTLWithin(ttl, 1*time.Second, redeemRateLimitDuration)
+}
+
+func (s *RedeemCacheSuite) TestMultipleIncrements() {
+	userID := int64(2)
+
+	require.NoError(s.T(), s.cache.IncrementRedeemAttemptCount(s.ctx, userID))
+	require.NoError(s.T(), s.cache.IncrementRedeemAttemptCount(s.ctx, userID))
+	require.NoError(s.T(), s.cache.IncrementRedeemAttemptCount(s.ctx, userID))
+
+	count, err := s.cache.GetRedeemAttemptCount(s.ctx, userID)
+	require.NoError(s.T(), err)
+	require.Equal(s.T(), 3, count, "count after 3 increments")
+}
+
+func (s *RedeemCacheSuite) TestAcquireAndReleaseRedeemLock() {
+	ok, err := s.cache.AcquireRedeemLock(s.ctx, "CODE", 10*time.Second)
+	require.NoError(s.T(), err, "AcquireRedeemLock")
+	require.True(s.T(), ok)
+
+	// Second acquire should fail
+	ok, err = s.cache.AcquireRedeemLock(s.ctx, "CODE", 10*time.Second)
+	require.NoError(s.T(), err, "AcquireRedeemLock 2")
+	require.False(s.T(), ok, "expected lock to be held")
+
+	// Release
+	require.NoError(s.T(), s.cache.ReleaseRedeemLock(s.ctx, "CODE"), "ReleaseRedeemLock")
+
+	// Now acquire should succeed
+	ok, err = s.cache.AcquireRedeemLock(s.ctx, "CODE", 10*time.Second)
+	require.NoError(s.T(), err, "AcquireRedeemLock after release")
+	require.True(s.T(), ok)
+}
+
+func (s *RedeemCacheSuite) TestAcquireRedeemLock_TTL() {
+	lockKey := redeemLockKeyPrefix + "CODE2"
+	lockTTL := 15 * time.Second
+
+	ok, err := s.cache.AcquireRedeemLock(s.ctx, "CODE2", lockTTL)
+	require.NoError(s.T(), err, "AcquireRedeemLock CODE2")
+	require.True(s.T(), ok)
+
+	ttl, err := s.rdb.TTL(s.ctx, lockKey).Result()
+	require.NoError(s.T(), err, "TTL lock key")
+	s.AssertTTLWithin(ttl, 1*time.Second, lockTTL)
+}
+
+func (s *RedeemCacheSuite) TestReleaseRedeemLock_Idempotent() {
+	// Release a lock that doesn't exist should not error
+	require.NoError(s.T(), s.cache.ReleaseRedeemLock(s.ctx, "NONEXISTENT"))
+
+	// Acquire, release, release again
+	ok, err := s.cache.AcquireRedeemLock(s.ctx, "IDEMPOTENT", 10*time.Second)
+	require.NoError(s.T(), err)
+	require.True(s.T(), ok)
+	require.NoError(s.T(), s.cache.ReleaseRedeemLock(s.ctx, "IDEMPOTENT"))
+	require.NoError(s.T(), s.cache.ReleaseRedeemLock(s.ctx, "IDEMPOTENT"), "second release should be idempotent")
+}
+
+func TestRedeemCacheSuite(t *testing.T) {
+	suite.Run(t, new(RedeemCacheSuite))
+}

backend/internal/repository/redeem_code_repo.go

@@ -2,57 +2,60 @@ package repository
 
 import (
 	"context"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
 	"time"
 
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+
 	"gorm.io/gorm"
 )
 
-type RedeemCodeRepository struct {
+type redeemCodeRepository struct {
 	db *gorm.DB
 }
 
-func NewRedeemCodeRepository(db *gorm.DB) *RedeemCodeRepository {
-	return &RedeemCodeRepository{db: db}
+func NewRedeemCodeRepository(db *gorm.DB) service.RedeemCodeRepository {
+	return &redeemCodeRepository{db: db}
 }
 
-func (r *RedeemCodeRepository) Create(ctx context.Context, code *model.RedeemCode) error {
+func (r *redeemCodeRepository) Create(ctx context.Context, code *model.RedeemCode) error {
 	return r.db.WithContext(ctx).Create(code).Error
 }
 
-func (r *RedeemCodeRepository) CreateBatch(ctx context.Context, codes []model.RedeemCode) error {
+func (r *redeemCodeRepository) CreateBatch(ctx context.Context, codes []model.RedeemCode) error {
 	return r.db.WithContext(ctx).Create(&codes).Error
 }
 
-func (r *RedeemCodeRepository) GetByID(ctx context.Context, id int64) (*model.RedeemCode, error) {
+func (r *redeemCodeRepository) GetByID(ctx context.Context, id int64) (*model.RedeemCode, error) {
 	var code model.RedeemCode
 	err := r.db.WithContext(ctx).First(&code, id).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrRedeemCodeNotFound, nil)
 	}
 	return &code, nil
 }
 
-func (r *RedeemCodeRepository) GetByCode(ctx context.Context, code string) (*model.RedeemCode, error) {
+func (r *redeemCodeRepository) GetByCode(ctx context.Context, code string) (*model.RedeemCode, error) {
 	var redeemCode model.RedeemCode
 	err := r.db.WithContext(ctx).Where("code = ?", code).First(&redeemCode).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrRedeemCodeNotFound, nil)
 	}
 	return &redeemCode, nil
 }
 
-func (r *RedeemCodeRepository) Delete(ctx context.Context, id int64) error {
+func (r *redeemCodeRepository) Delete(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Delete(&model.RedeemCode{}, id).Error
 }
 
-func (r *RedeemCodeRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.RedeemCode, *pagination.PaginationResult, error) {
+func (r *redeemCodeRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.RedeemCode, *pagination.PaginationResult, error) {
 	return r.ListWithFilters(ctx, params, "", "", "")
 }
 
 // ListWithFilters lists redeem codes with optional filtering by type, status, and search query
-func (r *RedeemCodeRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, codeType, status, search string) ([]model.RedeemCode, *pagination.PaginationResult, error) {
+func (r *redeemCodeRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, codeType, status, search string) ([]model.RedeemCode, *pagination.PaginationResult, error) {
 	var codes []model.RedeemCode
 	var total int64
 
@@ -91,11 +94,11 @@ func (r *RedeemCodeRepository) ListWithFilters(ctx context.Context, params pagin
 	}, nil
 }
 
-func (r *RedeemCodeRepository) Update(ctx context.Context, code *model.RedeemCode) error {
+func (r *redeemCodeRepository) Update(ctx context.Context, code *model.RedeemCode) error {
 	return r.db.WithContext(ctx).Save(code).Error
 }
 
-func (r *RedeemCodeRepository) Use(ctx context.Context, id, userID int64) error {
+func (r *redeemCodeRepository) Use(ctx context.Context, id, userID int64) error {
 	now := time.Now()
 	result := r.db.WithContext(ctx).Model(&model.RedeemCode{}).
 		Where("id = ? AND status = ?", id, model.StatusUnused).
@@ -108,13 +111,13 @@ func (r *RedeemCodeRepository) Use(ctx context.Context, id, userID int64) error
 		return result.Error
 	}
 	if result.RowsAffected == 0 {
-		return gorm.ErrRecordNotFound // 兑换码不存在或已被使用
+		return service.ErrRedeemCodeUsed.WithCause(gorm.ErrRecordNotFound)
 	}
 	return nil
 }
 
 // ListByUser returns all redeem codes used by a specific user
-func (r *RedeemCodeRepository) ListByUser(ctx context.Context, userID int64, limit int) ([]model.RedeemCode, error) {
+func (r *redeemCodeRepository) ListByUser(ctx context.Context, userID int64, limit int) ([]model.RedeemCode, error) {
 	var codes []model.RedeemCode
 	if limit <= 0 {
 		limit = 10

backend/internal/repository/redeem_code_repo_integration_test.go

@@ -0,0 +1,316 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/suite"
+	"gorm.io/gorm"
+)
+
+type RedeemCodeRepoSuite struct {
+	suite.Suite
+	ctx  context.Context
+	db   *gorm.DB
+	repo *redeemCodeRepository
+}
+
+func (s *RedeemCodeRepoSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+	s.repo = NewRedeemCodeRepository(s.db).(*redeemCodeRepository)
+}
+
+func TestRedeemCodeRepoSuite(t *testing.T) {
+	suite.Run(t, new(RedeemCodeRepoSuite))
+}
+
+// --- Create / CreateBatch / GetByID / GetByCode ---
+
+func (s *RedeemCodeRepoSuite) TestCreate() {
+	code := &model.RedeemCode{
+		Code:   "TEST-CREATE",
+		Type:   model.RedeemTypeBalance,
+		Value:  100,
+		Status: model.StatusUnused,
+	}
+
+	err := s.repo.Create(s.ctx, code)
+	s.Require().NoError(err, "Create")
+	s.Require().NotZero(code.ID, "expected ID to be set")
+
+	got, err := s.repo.GetByID(s.ctx, code.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal("TEST-CREATE", got.Code)
+}
+
+func (s *RedeemCodeRepoSuite) TestCreateBatch() {
+	codes := []model.RedeemCode{
+		{Code: "BATCH-1", Type: model.RedeemTypeBalance, Value: 10, Status: model.StatusUnused},
+		{Code: "BATCH-2", Type: model.RedeemTypeBalance, Value: 20, Status: model.StatusUnused},
+	}
+
+	err := s.repo.CreateBatch(s.ctx, codes)
+	s.Require().NoError(err, "CreateBatch")
+
+	got1, err := s.repo.GetByCode(s.ctx, "BATCH-1")
+	s.Require().NoError(err)
+	s.Require().Equal(float64(10), got1.Value)
+
+	got2, err := s.repo.GetByCode(s.ctx, "BATCH-2")
+	s.Require().NoError(err)
+	s.Require().Equal(float64(20), got2.Value)
+}
+
+func (s *RedeemCodeRepoSuite) TestGetByID_NotFound() {
+	_, err := s.repo.GetByID(s.ctx, 999999)
+	s.Require().Error(err, "expected error for non-existent ID")
+}
+
+func (s *RedeemCodeRepoSuite) TestGetByCode() {
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "GET-BY-CODE", Type: model.RedeemTypeBalance})
+
+	got, err := s.repo.GetByCode(s.ctx, "GET-BY-CODE")
+	s.Require().NoError(err, "GetByCode")
+	s.Require().Equal("GET-BY-CODE", got.Code)
+}
+
+func (s *RedeemCodeRepoSuite) TestGetByCode_NotFound() {
+	_, err := s.repo.GetByCode(s.ctx, "NON-EXISTENT")
+	s.Require().Error(err, "expected error for non-existent code")
+}
+
+// --- Delete ---
+
+func (s *RedeemCodeRepoSuite) TestDelete() {
+	code := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "TO-DELETE", Type: model.RedeemTypeBalance})
+
+	err := s.repo.Delete(s.ctx, code.ID)
+	s.Require().NoError(err, "Delete")
+
+	_, err = s.repo.GetByID(s.ctx, code.ID)
+	s.Require().Error(err, "expected error after delete")
+}
+
+// --- List / ListWithFilters ---
+
+func (s *RedeemCodeRepoSuite) TestList() {
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "LIST-1", Type: model.RedeemTypeBalance})
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "LIST-2", Type: model.RedeemTypeBalance})
+
+	codes, page, err := s.repo.List(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "List")
+	s.Require().Len(codes, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+func (s *RedeemCodeRepoSuite) TestListWithFilters_Type() {
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "TYPE-BAL", Type: model.RedeemTypeBalance})
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "TYPE-SUB", Type: model.RedeemTypeSubscription})
+
+	codes, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, model.RedeemTypeSubscription, "", "")
+	s.Require().NoError(err)
+	s.Require().Len(codes, 1)
+	s.Require().Equal(model.RedeemTypeSubscription, codes[0].Type)
+}
+
+func (s *RedeemCodeRepoSuite) TestListWithFilters_Status() {
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "STAT-UNUSED", Type: model.RedeemTypeBalance, Status: model.StatusUnused})
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "STAT-USED", Type: model.RedeemTypeBalance, Status: model.StatusUsed})
+
+	codes, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", model.StatusUsed, "")
+	s.Require().NoError(err)
+	s.Require().Len(codes, 1)
+	s.Require().Equal(model.StatusUsed, codes[0].Status)
+}
+
+func (s *RedeemCodeRepoSuite) TestListWithFilters_Search() {
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "ALPHA-CODE", Type: model.RedeemTypeBalance})
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "BETA-CODE", Type: model.RedeemTypeBalance})
+
+	codes, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", "alpha")
+	s.Require().NoError(err)
+	s.Require().Len(codes, 1)
+	s.Require().Contains(codes[0].Code, "ALPHA")
+}
+
+func (s *RedeemCodeRepoSuite) TestListWithFilters_GroupPreload() {
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-preload"})
+	mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{
+		Code:    "WITH-GROUP",
+		Type:    model.RedeemTypeSubscription,
+		GroupID: &group.ID,
+	})
+
+	codes, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", "")
+	s.Require().NoError(err)
+	s.Require().Len(codes, 1)
+	s.Require().NotNil(codes[0].Group, "expected Group preload")
+	s.Require().Equal(group.ID, codes[0].Group.ID)
+}
+
+// --- Update ---
+
+func (s *RedeemCodeRepoSuite) TestUpdate() {
+	code := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "UPDATE-ME", Type: model.RedeemTypeBalance, Value: 10})
+
+	code.Value = 50
+	err := s.repo.Update(s.ctx, code)
+	s.Require().NoError(err, "Update")
+
+	got, err := s.repo.GetByID(s.ctx, code.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(float64(50), got.Value)
+}
+
+// --- Use ---
+
+func (s *RedeemCodeRepoSuite) TestUse() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "use@test.com"})
+	code := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "USE-ME", Type: model.RedeemTypeBalance, Status: model.StatusUnused})
+
+	err := s.repo.Use(s.ctx, code.ID, user.ID)
+	s.Require().NoError(err, "Use")
+
+	got, err := s.repo.GetByID(s.ctx, code.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(model.StatusUsed, got.Status)
+	s.Require().NotNil(got.UsedBy)
+	s.Require().Equal(user.ID, *got.UsedBy)
+	s.Require().NotNil(got.UsedAt)
+}
+
+func (s *RedeemCodeRepoSuite) TestUse_Idempotency() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "idem@test.com"})
+	code := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "IDEM-CODE", Type: model.RedeemTypeBalance, Status: model.StatusUnused})
+
+	err := s.repo.Use(s.ctx, code.ID, user.ID)
+	s.Require().NoError(err, "Use first time")
+
+	// Second use should fail
+	err = s.repo.Use(s.ctx, code.ID, user.ID)
+	s.Require().Error(err, "Use expected error on second call")
+	s.Require().ErrorIs(err, service.ErrRedeemCodeUsed)
+}
+
+func (s *RedeemCodeRepoSuite) TestUse_AlreadyUsed() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "already@test.com"})
+	code := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{Code: "ALREADY-USED", Type: model.RedeemTypeBalance, Status: model.StatusUsed})
+
+	err := s.repo.Use(s.ctx, code.ID, user.ID)
+	s.Require().Error(err, "expected error for already used code")
+	s.Require().ErrorIs(err, service.ErrRedeemCodeUsed)
+}
+
+// --- ListByUser ---
+
+func (s *RedeemCodeRepoSuite) TestListByUser() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "listby@test.com"})
+	base := time.Date(2025, 1, 1, 12, 0, 0, 0, time.UTC)
+
+	// Create codes with explicit used_at for ordering
+	c1 := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{
+		Code:   "USER-1",
+		Type:   model.RedeemTypeBalance,
+		Status: model.StatusUsed,
+		UsedBy: &user.ID,
+	})
+	s.db.Model(c1).Update("used_at", base)
+
+	c2 := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{
+		Code:   "USER-2",
+		Type:   model.RedeemTypeBalance,
+		Status: model.StatusUsed,
+		UsedBy: &user.ID,
+	})
+	s.db.Model(c2).Update("used_at", base.Add(1*time.Hour))
+
+	codes, err := s.repo.ListByUser(s.ctx, user.ID, 10)
+	s.Require().NoError(err, "ListByUser")
+	s.Require().Len(codes, 2)
+	// Ordered by used_at DESC, so USER-2 first
+	s.Require().Equal("USER-2", codes[0].Code)
+	s.Require().Equal("USER-1", codes[1].Code)
+}
+
+func (s *RedeemCodeRepoSuite) TestListByUser_WithGroupPreload() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "grp@test.com"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-listby"})
+
+	c := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{
+		Code:    "WITH-GRP",
+		Type:    model.RedeemTypeSubscription,
+		Status:  model.StatusUsed,
+		UsedBy:  &user.ID,
+		GroupID: &group.ID,
+	})
+	s.db.Model(c).Update("used_at", time.Now())
+
+	codes, err := s.repo.ListByUser(s.ctx, user.ID, 10)
+	s.Require().NoError(err)
+	s.Require().Len(codes, 1)
+	s.Require().NotNil(codes[0].Group)
+	s.Require().Equal(group.ID, codes[0].Group.ID)
+}
+
+func (s *RedeemCodeRepoSuite) TestListByUser_DefaultLimit() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "deflimit@test.com"})
+	c := mustCreateRedeemCode(s.T(), s.db, &model.RedeemCode{
+		Code:   "DEF-LIM",
+		Type:   model.RedeemTypeBalance,
+		Status: model.StatusUsed,
+		UsedBy: &user.ID,
+	})
+	s.db.Model(c).Update("used_at", time.Now())
+
+	// limit <= 0 should default to 10
+	codes, err := s.repo.ListByUser(s.ctx, user.ID, 0)
+	s.Require().NoError(err)
+	s.Require().Len(codes, 1)
+}
+
+// --- Combined original test ---
+
+func (s *RedeemCodeRepoSuite) TestCreateBatch_Filters_Use_Idempotency_ListByUser() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "rc@example.com"})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-rc"})
+
+	codes := []model.RedeemCode{
+		{Code: "CODEA", Type: model.RedeemTypeBalance, Value: 1, Status: model.StatusUnused, CreatedAt: time.Now()},
+		{Code: "CODEB", Type: model.RedeemTypeSubscription, Value: 0, Status: model.StatusUnused, GroupID: &group.ID, ValidityDays: 7, CreatedAt: time.Now()},
+	}
+	s.Require().NoError(s.repo.CreateBatch(s.ctx, codes), "CreateBatch")
+
+	list, page, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, model.RedeemTypeSubscription, model.StatusUnused, "code")
+	s.Require().NoError(err, "ListWithFilters")
+	s.Require().Equal(int64(1), page.Total)
+	s.Require().Len(list, 1)
+	s.Require().NotNil(list[0].Group, "expected Group preload")
+	s.Require().Equal(group.ID, list[0].Group.ID)
+
+	codeB, err := s.repo.GetByCode(s.ctx, "CODEB")
+	s.Require().NoError(err, "GetByCode")
+	s.Require().NoError(s.repo.Use(s.ctx, codeB.ID, user.ID), "Use")
+	err = s.repo.Use(s.ctx, codeB.ID, user.ID)
+	s.Require().Error(err, "Use expected error on second call")
+	s.Require().ErrorIs(err, service.ErrRedeemCodeUsed)
+
+	codeA, err := s.repo.GetByCode(s.ctx, "CODEA")
+	s.Require().NoError(err, "GetByCode")
+
+	// Use fixed time instead of time.Sleep for deterministic ordering
+	s.db.Model(&model.RedeemCode{}).Where("id = ?", codeB.ID).Update("used_at", time.Date(2025, 1, 1, 12, 0, 0, 0, time.UTC))
+	s.Require().NoError(s.repo.Use(s.ctx, codeA.ID, user.ID), "Use codeA")
+	s.db.Model(&model.RedeemCode{}).Where("id = ?", codeA.ID).Update("used_at", time.Date(2025, 1, 1, 13, 0, 0, 0, time.UTC))
+
+	used, err := s.repo.ListByUser(s.ctx, user.ID, 10)
+	s.Require().NoError(err, "ListByUser")
+	s.Require().Len(used, 2, "expected 2 used codes")
+	s.Require().Equal("CODEA", used[0].Code, "expected newest used code first")
+}

backend/internal/repository/repository.go

@@ -1,14 +0,0 @@
-package repository
-
-// Repositories 所有仓库的集合
-type Repositories struct {
-	User             *UserRepository
-	ApiKey           *ApiKeyRepository
-	Group            *GroupRepository
-	Account          *AccountRepository
-	Proxy            *ProxyRepository
-	RedeemCode       *RedeemCodeRepository
-	UsageLog         *UsageLogRepository
-	Setting          *SettingRepository
-	UserSubscription *UserSubscriptionRepository
-}

backend/internal/repository/setting_repo.go

@@ -2,35 +2,38 @@ package repository
 
 import (
 	"context"
-	"sub2api/internal/model"
 	"time"
 
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
 )
 
 // SettingRepository 系统设置数据访问层
-type SettingRepository struct {
+type settingRepository struct {
 	db *gorm.DB
 }
 
 // NewSettingRepository 创建系统设置仓库实例
-func NewSettingRepository(db *gorm.DB) *SettingRepository {
-	return &SettingRepository{db: db}
+func NewSettingRepository(db *gorm.DB) service.SettingRepository {
+	return &settingRepository{db: db}
 }
 
 // Get 根据Key获取设置值
-func (r *SettingRepository) Get(ctx context.Context, key string) (*model.Setting, error) {
+func (r *settingRepository) Get(ctx context.Context, key string) (*model.Setting, error) {
 	var setting model.Setting
 	err := r.db.WithContext(ctx).Where("key = ?", key).First(&setting).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrSettingNotFound, nil)
 	}
 	return &setting, nil
 }
 
 // GetValue 获取设置值字符串
-func (r *SettingRepository) GetValue(ctx context.Context, key string) (string, error) {
+func (r *settingRepository) GetValue(ctx context.Context, key string) (string, error) {
 	setting, err := r.Get(ctx, key)
 	if err != nil {
 		return "", err
@@ -39,7 +42,7 @@ func (r *SettingRepository) GetValue(ctx context.Context, key string) (string, e
 }
 
 // Set 设置值（存在则更新，不存在则创建）
-func (r *SettingRepository) Set(ctx context.Context, key, value string) error {
+func (r *settingRepository) Set(ctx context.Context, key, value string) error {
 	setting := &model.Setting{
 		Key:       key,
 		Value:     value,
@@ -53,7 +56,7 @@ func (r *SettingRepository) Set(ctx context.Context, key, value string) error {
 }
 
 // GetMultiple 批量获取设置
-func (r *SettingRepository) GetMultiple(ctx context.Context, keys []string) (map[string]string, error) {
+func (r *settingRepository) GetMultiple(ctx context.Context, keys []string) (map[string]string, error) {
 	var settings []model.Setting
 	err := r.db.WithContext(ctx).Where("key IN ?", keys).Find(&settings).Error
 	if err != nil {
@@ -68,7 +71,7 @@ func (r *SettingRepository) GetMultiple(ctx context.Context, keys []string) (map
 }
 
 // SetMultiple 批量设置值
-func (r *SettingRepository) SetMultiple(ctx context.Context, settings map[string]string) error {
+func (r *settingRepository) SetMultiple(ctx context.Context, settings map[string]string) error {
 	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		for key, value := range settings {
 			setting := &model.Setting{
@@ -88,7 +91,7 @@ func (r *SettingRepository) SetMultiple(ctx context.Context, settings map[string
 }
 
 // GetAll 获取所有设置
-func (r *SettingRepository) GetAll(ctx context.Context) (map[string]string, error) {
+func (r *settingRepository) GetAll(ctx context.Context) (map[string]string, error) {
 	var settings []model.Setting
 	err := r.db.WithContext(ctx).Find(&settings).Error
 	if err != nil {
@@ -103,6 +106,6 @@ func (r *SettingRepository) GetAll(ctx context.Context) (map[string]string, erro
 }
 
 // Delete 删除设置
-func (r *SettingRepository) Delete(ctx context.Context, key string) error {
+func (r *settingRepository) Delete(ctx context.Context, key string) error {
 	return r.db.WithContext(ctx).Where("key = ?", key).Delete(&model.Setting{}).Error
 }

backend/internal/repository/setting_repo_integration_test.go

@@ -0,0 +1,109 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/suite"
+	"gorm.io/gorm"
+)
+
+type SettingRepoSuite struct {
+	suite.Suite
+	ctx  context.Context
+	db   *gorm.DB
+	repo *settingRepository
+}
+
+func (s *SettingRepoSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+	s.repo = NewSettingRepository(s.db).(*settingRepository)
+}
+
+func TestSettingRepoSuite(t *testing.T) {
+	suite.Run(t, new(SettingRepoSuite))
+}
+
+func (s *SettingRepoSuite) TestSetAndGetValue() {
+	s.Require().NoError(s.repo.Set(s.ctx, "k1", "v1"), "Set")
+	got, err := s.repo.GetValue(s.ctx, "k1")
+	s.Require().NoError(err, "GetValue")
+	s.Require().Equal("v1", got, "GetValue mismatch")
+}
+
+func (s *SettingRepoSuite) TestSet_Upsert() {
+	s.Require().NoError(s.repo.Set(s.ctx, "k1", "v1"), "Set")
+	s.Require().NoError(s.repo.Set(s.ctx, "k1", "v2"), "Set upsert")
+	got, err := s.repo.GetValue(s.ctx, "k1")
+	s.Require().NoError(err, "GetValue after upsert")
+	s.Require().Equal("v2", got, "upsert mismatch")
+}
+
+func (s *SettingRepoSuite) TestGetValue_Missing() {
+	_, err := s.repo.GetValue(s.ctx, "nonexistent")
+	s.Require().Error(err, "expected error for missing key")
+	s.Require().ErrorIs(err, service.ErrSettingNotFound)
+}
+
+func (s *SettingRepoSuite) TestSetMultiple_AndGetMultiple() {
+	s.Require().NoError(s.repo.SetMultiple(s.ctx, map[string]string{"k2": "v2", "k3": "v3"}), "SetMultiple")
+	m, err := s.repo.GetMultiple(s.ctx, []string{"k2", "k3"})
+	s.Require().NoError(err, "GetMultiple")
+	s.Require().Equal("v2", m["k2"])
+	s.Require().Equal("v3", m["k3"])
+}
+
+func (s *SettingRepoSuite) TestGetMultiple_EmptyKeys() {
+	m, err := s.repo.GetMultiple(s.ctx, []string{})
+	s.Require().NoError(err, "GetMultiple with empty keys")
+	s.Require().Empty(m, "expected empty map")
+}
+
+func (s *SettingRepoSuite) TestGetMultiple_Subset() {
+	s.Require().NoError(s.repo.SetMultiple(s.ctx, map[string]string{"a": "1", "b": "2", "c": "3"}))
+	m, err := s.repo.GetMultiple(s.ctx, []string{"a", "c", "nonexistent"})
+	s.Require().NoError(err, "GetMultiple subset")
+	s.Require().Equal("1", m["a"])
+	s.Require().Equal("3", m["c"])
+	_, exists := m["nonexistent"]
+	s.Require().False(exists, "nonexistent key should not be in map")
+}
+
+func (s *SettingRepoSuite) TestGetAll() {
+	s.Require().NoError(s.repo.SetMultiple(s.ctx, map[string]string{"x": "1", "y": "2"}))
+	all, err := s.repo.GetAll(s.ctx)
+	s.Require().NoError(err, "GetAll")
+	s.Require().GreaterOrEqual(len(all), 2, "expected at least 2 settings")
+	s.Require().Equal("1", all["x"])
+	s.Require().Equal("2", all["y"])
+}
+
+func (s *SettingRepoSuite) TestDelete() {
+	s.Require().NoError(s.repo.Set(s.ctx, "todelete", "val"))
+	s.Require().NoError(s.repo.Delete(s.ctx, "todelete"), "Delete")
+	_, err := s.repo.GetValue(s.ctx, "todelete")
+	s.Require().Error(err, "expected missing key error after Delete")
+	s.Require().ErrorIs(err, service.ErrSettingNotFound)
+}
+
+func (s *SettingRepoSuite) TestDelete_Idempotent() {
+	// Delete a key that doesn't exist should not error
+	s.Require().NoError(s.repo.Delete(s.ctx, "nonexistent_delete"), "Delete nonexistent should be idempotent")
+}
+
+func (s *SettingRepoSuite) TestSetMultiple_Upsert() {
+	s.Require().NoError(s.repo.Set(s.ctx, "upsert_key", "old_value"))
+	s.Require().NoError(s.repo.SetMultiple(s.ctx, map[string]string{"upsert_key": "new_value", "new_key": "new_val"}))
+
+	got, err := s.repo.GetValue(s.ctx, "upsert_key")
+	s.Require().NoError(err)
+	s.Require().Equal("new_value", got, "SetMultiple should upsert existing key")
+
+	got2, err := s.repo.GetValue(s.ctx, "new_key")
+	s.Require().NoError(err)
+	s.Require().Equal("new_val", got2)
+}

backend/internal/repository/turnstile_service.go

@@ -9,13 +9,14 @@ import (
 	"strings"
 	"time"
 
-	"sub2api/internal/service"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 )
 
 const turnstileVerifyURL = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
 
 type turnstileVerifier struct {
 	httpClient *http.Client
+	verifyURL  string
 }
 
 func NewTurnstileVerifier() service.TurnstileVerifier {
@@ -23,6 +24,7 @@ func NewTurnstileVerifier() service.TurnstileVerifier {
 		httpClient: &http.Client{
 			Timeout: 10 * time.Second,
 		},
+		verifyURL: turnstileVerifyURL,
 	}
 }
 
@@ -34,7 +36,7 @@ func (v *turnstileVerifier) VerifyToken(ctx context.Context, secretKey, token, r
 		formData.Set("remoteip", remoteIP)
 	}
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, turnstileVerifyURL, strings.NewReader(formData.Encode()))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, v.verifyURL, strings.NewReader(formData.Encode()))
 	if err != nil {
 		return nil, fmt.Errorf("create request: %w", err)
 	}

backend/internal/repository/turnstile_service_test.go

@@ -0,0 +1,143 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type TurnstileServiceSuite struct {
+	suite.Suite
+	ctx      context.Context
+	srv      *httptest.Server
+	verifier *turnstileVerifier
+	received chan url.Values
+}
+
+func (s *TurnstileServiceSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.received = make(chan url.Values, 1)
+	verifier, ok := NewTurnstileVerifier().(*turnstileVerifier)
+	require.True(s.T(), ok, "type assertion failed")
+	s.verifier = verifier
+}
+
+func (s *TurnstileServiceSuite) TearDownTest() {
+	if s.srv != nil {
+		s.srv.Close()
+		s.srv = nil
+	}
+}
+
+func (s *TurnstileServiceSuite) setupServer(handler http.HandlerFunc) {
+	s.srv = httptest.NewServer(handler)
+	s.verifier.verifyURL = s.srv.URL
+}
+
+func (s *TurnstileServiceSuite) TestVerifyToken_SendsFormAndDecodesJSON() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Capture form data in main goroutine context later
+		body, _ := io.ReadAll(r.Body)
+		values, _ := url.ParseQuery(string(body))
+		s.received <- values
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(service.TurnstileVerifyResponse{Success: true})
+	}))
+
+	resp, err := s.verifier.VerifyToken(s.ctx, "sk", "token", "1.1.1.1")
+	require.NoError(s.T(), err, "VerifyToken")
+	require.NotNil(s.T(), resp)
+	require.True(s.T(), resp.Success, "expected success response")
+
+	// Assert form fields in main goroutine
+	select {
+	case values := <-s.received:
+		require.Equal(s.T(), "sk", values.Get("secret"))
+		require.Equal(s.T(), "token", values.Get("response"))
+		require.Equal(s.T(), "1.1.1.1", values.Get("remoteip"))
+	default:
+		require.Fail(s.T(), "expected server to receive request")
+	}
+}
+
+func (s *TurnstileServiceSuite) TestVerifyToken_ContentType() {
+	var contentType string
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		contentType = r.Header.Get("Content-Type")
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(service.TurnstileVerifyResponse{Success: true})
+	}))
+
+	_, err := s.verifier.VerifyToken(s.ctx, "sk", "token", "1.1.1.1")
+	require.NoError(s.T(), err)
+	require.True(s.T(), strings.HasPrefix(contentType, "application/x-www-form-urlencoded"), "unexpected content-type: %s", contentType)
+}
+
+func (s *TurnstileServiceSuite) TestVerifyToken_EmptyRemoteIP_NotSent() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		values, _ := url.ParseQuery(string(body))
+		s.received <- values
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(service.TurnstileVerifyResponse{Success: true})
+	}))
+
+	_, err := s.verifier.VerifyToken(s.ctx, "sk", "token", "")
+	require.NoError(s.T(), err)
+
+	select {
+	case values := <-s.received:
+		require.Equal(s.T(), "", values.Get("remoteip"), "remoteip should be empty or not sent")
+	default:
+		require.Fail(s.T(), "expected server to receive request")
+	}
+}
+
+func (s *TurnstileServiceSuite) TestVerifyToken_RequestError() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+	s.srv.Close()
+
+	_, err := s.verifier.VerifyToken(s.ctx, "sk", "token", "1.1.1.1")
+	require.Error(s.T(), err, "expected error when server is closed")
+}
+
+func (s *TurnstileServiceSuite) TestVerifyToken_InvalidJSON() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, "not-valid-json")
+	}))
+
+	_, err := s.verifier.VerifyToken(s.ctx, "sk", "token", "1.1.1.1")
+	require.Error(s.T(), err, "expected error for invalid JSON response")
+}
+
+func (s *TurnstileServiceSuite) TestVerifyToken_SuccessFalse() {
+	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(service.TurnstileVerifyResponse{
+			Success:    false,
+			ErrorCodes: []string{"invalid-input-response"},
+		})
+	}))
+
+	resp, err := s.verifier.VerifyToken(s.ctx, "sk", "token", "1.1.1.1")
+	require.NoError(s.T(), err, "VerifyToken should not error on success=false")
+	require.NotNil(s.T(), resp)
+	require.False(s.T(), resp.Success)
+	require.Contains(s.T(), resp.ErrorCodes, "invalid-input-response")
+}
+
+func TestTurnstileServiceSuite(t *testing.T) {
+	suite.Run(t, new(TurnstileServiceSuite))
+}

backend/internal/repository/update_cache.go

@@ -4,8 +4,7 @@ import (
 	"context"
 	"time"
 
-	"sub2api/internal/service/ports"
-
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/redis/go-redis/v9"
 )
 
@@ -15,7 +14,7 @@ type updateCache struct {
 	rdb *redis.Client
 }
 
-func NewUpdateCache(rdb *redis.Client) ports.UpdateCache {
+func NewUpdateCache(rdb *redis.Client) service.UpdateCache {
 	return &updateCache{rdb: rdb}
 }
 

backend/internal/repository/update_cache_integration_test.go

@@ -0,0 +1,73 @@
+//go:build integration
+
+package repository
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+type UpdateCacheSuite struct {
+	IntegrationRedisSuite
+	cache *updateCache
+}
+
+func (s *UpdateCacheSuite) SetupTest() {
+	s.IntegrationRedisSuite.SetupTest()
+	s.cache = NewUpdateCache(s.rdb).(*updateCache)
+}
+
+func (s *UpdateCacheSuite) TestGetUpdateInfo_Missing() {
+	_, err := s.cache.GetUpdateInfo(s.ctx)
+	require.True(s.T(), errors.Is(err, redis.Nil), "expected redis.Nil for missing update info")
+}
+
+func (s *UpdateCacheSuite) TestSetAndGetUpdateInfo() {
+	updateTTL := 5 * time.Minute
+	require.NoError(s.T(), s.cache.SetUpdateInfo(s.ctx, "v1.2.3", updateTTL), "SetUpdateInfo")
+
+	info, err := s.cache.GetUpdateInfo(s.ctx)
+	require.NoError(s.T(), err, "GetUpdateInfo")
+	require.Equal(s.T(), "v1.2.3", info, "update info mismatch")
+}
+
+func (s *UpdateCacheSuite) TestSetUpdateInfo_TTL() {
+	updateTTL := 5 * time.Minute
+	require.NoError(s.T(), s.cache.SetUpdateInfo(s.ctx, "v1.2.3", updateTTL))
+
+	ttl, err := s.rdb.TTL(s.ctx, updateCacheKey).Result()
+	require.NoError(s.T(), err, "TTL updateCacheKey")
+	s.AssertTTLWithin(ttl, 1*time.Second, updateTTL)
+}
+
+func (s *UpdateCacheSuite) TestSetUpdateInfo_Overwrite() {
+	require.NoError(s.T(), s.cache.SetUpdateInfo(s.ctx, "v1.0.0", 5*time.Minute))
+	require.NoError(s.T(), s.cache.SetUpdateInfo(s.ctx, "v2.0.0", 5*time.Minute))
+
+	info, err := s.cache.GetUpdateInfo(s.ctx)
+	require.NoError(s.T(), err)
+	require.Equal(s.T(), "v2.0.0", info, "expected overwritten value")
+}
+
+func (s *UpdateCacheSuite) TestSetUpdateInfo_ZeroTTL() {
+	// TTL=0 means persist forever (no expiry) in Redis SET command
+	require.NoError(s.T(), s.cache.SetUpdateInfo(s.ctx, "v0.0.0", 0))
+
+	info, err := s.cache.GetUpdateInfo(s.ctx)
+	require.NoError(s.T(), err)
+	require.Equal(s.T(), "v0.0.0", info)
+
+	ttl, err := s.rdb.TTL(s.ctx, updateCacheKey).Result()
+	require.NoError(s.T(), err)
+	// TTL=-1 means no expiry, TTL=-2 means key doesn't exist
+	require.Equal(s.T(), time.Duration(-1), ttl, "expected TTL=-1 for key with no expiry")
+}
+
+func TestUpdateCacheSuite(t *testing.T) {
+	suite.Run(t, new(UpdateCacheSuite))
+}

backend/internal/repository/usage_log_repo.go

@@ -2,37 +2,64 @@ package repository
 
 import (
 	"context"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
-	"sub2api/internal/pkg/timezone"
-	"sub2api/internal/pkg/usagestats"
 	"time"
 
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+
 	"gorm.io/gorm"
 )
 
-type UsageLogRepository struct {
+type usageLogRepository struct {
 	db *gorm.DB
 }
 
-func NewUsageLogRepository(db *gorm.DB) *UsageLogRepository {
-	return &UsageLogRepository{db: db}
+func NewUsageLogRepository(db *gorm.DB) service.UsageLogRepository {
+	return &usageLogRepository{db: db}
 }
 
-func (r *UsageLogRepository) Create(ctx context.Context, log *model.UsageLog) error {
+// getPerformanceStats 获取 RPM 和 TPM（近5分钟平均值，可选按用户过滤）
+func (r *usageLogRepository) getPerformanceStats(ctx context.Context, userID int64) (rpm, tpm int64) {
+	fiveMinutesAgo := time.Now().Add(-5 * time.Minute)
+	var perfStats struct {
+		RequestCount int64 `gorm:"column:request_count"`
+		TokenCount   int64 `gorm:"column:token_count"`
+	}
+
+	db := r.db.WithContext(ctx).Model(&model.UsageLog{}).
+		Select(`
+			COUNT(*) as request_count,
+			COALESCE(SUM(input_tokens + output_tokens), 0) as token_count
+		`).
+		Where("created_at >= ?", fiveMinutesAgo)
+
+	if userID > 0 {
+		db = db.Where("user_id = ?", userID)
+	}
+
+	db.Scan(&perfStats)
+	// 返回5分钟平均值
+	return perfStats.RequestCount / 5, perfStats.TokenCount / 5
+}
+
+func (r *usageLogRepository) Create(ctx context.Context, log *model.UsageLog) error {
 	return r.db.WithContext(ctx).Create(log).Error
 }
 
-func (r *UsageLogRepository) GetByID(ctx context.Context, id int64) (*model.UsageLog, error) {
+func (r *usageLogRepository) GetByID(ctx context.Context, id int64) (*model.UsageLog, error) {
 	var log model.UsageLog
 	err := r.db.WithContext(ctx).First(&log, id).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrUsageLogNotFound, nil)
 	}
 	return &log, nil
 }
 
-func (r *UsageLogRepository) ListByUser(ctx context.Context, userID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error) {
+func (r *usageLogRepository) ListByUser(ctx context.Context, userID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error) {
 	var logs []model.UsageLog
 	var total int64
 
@@ -59,7 +86,7 @@ func (r *UsageLogRepository) ListByUser(ctx context.Context, userID int64, param
 	}, nil
 }
 
-func (r *UsageLogRepository) ListByApiKey(ctx context.Context, apiKeyID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error) {
+func (r *usageLogRepository) ListByApiKey(ctx context.Context, apiKeyID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error) {
 	var logs []model.UsageLog
 	var total int64
 
@@ -96,7 +123,7 @@ type UserStats struct {
 	CacheReadTokens int64   `json:"cache_read_tokens"`
 }
 
-func (r *UsageLogRepository) GetUserStats(ctx context.Context, userID int64, startTime, endTime time.Time) (*UserStats, error) {
+func (r *usageLogRepository) GetUserStats(ctx context.Context, userID int64, startTime, endTime time.Time) (*UserStats, error) {
 	var stats UserStats
 	err := r.db.WithContext(ctx).Model(&model.UsageLog{}).
 		Select(`
@@ -113,48 +140,9 @@ func (r *UsageLogRepository) GetUserStats(ctx context.Context, userID int64, sta
 }
 
 // DashboardStats 仪表盘统计
-type DashboardStats struct {
-	// 用户统计
-	TotalUsers    int64 `json:"total_users"`
-	TodayNewUsers int64 `json:"today_new_users"` // 今日新增用户数
-	ActiveUsers   int64 `json:"active_users"`    // 今日有请求的用户数
+type DashboardStats = usagestats.DashboardStats
 
-	// API Key 统计
-	TotalApiKeys  int64 `json:"total_api_keys"`
-	ActiveApiKeys int64 `json:"active_api_keys"` // 状态为 active 的 API Key 数
-
-	// 账户统计
-	TotalAccounts     int64 `json:"total_accounts"`
-	NormalAccounts    int64 `json:"normal_accounts"`    // 正常账户数 (schedulable=true, status=active)
-	ErrorAccounts     int64 `json:"error_accounts"`     // 异常账户数 (status=error)
-	RateLimitAccounts int64 `json:"ratelimit_accounts"` // 限流账户数
-	OverloadAccounts  int64 `json:"overload_accounts"`  // 过载账户数
-
-	// 累计 Token 使用统计
-	TotalRequests            int64   `json:"total_requests"`
-	TotalInputTokens         int64   `json:"total_input_tokens"`
-	TotalOutputTokens        int64   `json:"total_output_tokens"`
-	TotalCacheCreationTokens int64   `json:"total_cache_creation_tokens"`
-	TotalCacheReadTokens     int64   `json:"total_cache_read_tokens"`
-	TotalTokens              int64   `json:"total_tokens"`
-	TotalCost                float64 `json:"total_cost"`        // 累计标准计费
-	TotalActualCost          float64 `json:"total_actual_cost"` // 累计实际扣除
-
-	// 今日 Token 使用统计
-	TodayRequests            int64   `json:"today_requests"`
-	TodayInputTokens         int64   `json:"today_input_tokens"`
-	TodayOutputTokens        int64   `json:"today_output_tokens"`
-	TodayCacheCreationTokens int64   `json:"today_cache_creation_tokens"`
-	TodayCacheReadTokens     int64   `json:"today_cache_read_tokens"`
-	TodayTokens              int64   `json:"today_tokens"`
-	TodayCost                float64 `json:"today_cost"`        // 今日标准计费
-	TodayActualCost          float64 `json:"today_actual_cost"` // 今日实际扣除
-
-	// 系统运行统计
-	AverageDurationMs float64 `json:"average_duration_ms"` // 平均响应时间
-}
-
-func (r *UsageLogRepository) GetDashboardStats(ctx context.Context) (*DashboardStats, error) {
+func (r *usageLogRepository) GetDashboardStats(ctx context.Context) (*DashboardStats, error) {
 	var stats DashboardStats
 	today := timezone.Today()
 
@@ -269,10 +257,13 @@ func (r *UsageLogRepository) GetDashboardStats(ctx context.Context) (*DashboardS
 	stats.TodayCost = todayStats.TodayCost
 	stats.TodayActualCost = todayStats.TodayActualCost
 
+	// 性能指标：RPM 和 TPM（最近1分钟，全局）
+	stats.Rpm, stats.Tpm = r.getPerformanceStats(ctx, 0)
+
 	return &stats, nil
 }
 
-func (r *UsageLogRepository) ListByAccount(ctx context.Context, accountID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error) {
+func (r *usageLogRepository) ListByAccount(ctx context.Context, accountID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error) {
 	var logs []model.UsageLog
 	var total int64
 
@@ -299,7 +290,7 @@ func (r *UsageLogRepository) ListByAccount(ctx context.Context, accountID int64,
 	}, nil
 }
 
-func (r *UsageLogRepository) ListByUserAndTimeRange(ctx context.Context, userID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error) {
+func (r *usageLogRepository) ListByUserAndTimeRange(ctx context.Context, userID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error) {
 	var logs []model.UsageLog
 	err := r.db.WithContext(ctx).
 		Where("user_id = ? AND created_at >= ? AND created_at < ?", userID, startTime, endTime).
@@ -308,7 +299,7 @@ func (r *UsageLogRepository) ListByUserAndTimeRange(ctx context.Context, userID
 	return logs, nil, err
 }
 
-func (r *UsageLogRepository) ListByApiKeyAndTimeRange(ctx context.Context, apiKeyID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error) {
+func (r *usageLogRepository) ListByApiKeyAndTimeRange(ctx context.Context, apiKeyID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error) {
 	var logs []model.UsageLog
 	err := r.db.WithContext(ctx).
 		Where("api_key_id = ? AND created_at >= ? AND created_at < ?", apiKeyID, startTime, endTime).
@@ -317,7 +308,7 @@ func (r *UsageLogRepository) ListByApiKeyAndTimeRange(ctx context.Context, apiKe
 	return logs, nil, err
 }
 
-func (r *UsageLogRepository) ListByAccountAndTimeRange(ctx context.Context, accountID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error) {
+func (r *usageLogRepository) ListByAccountAndTimeRange(ctx context.Context, accountID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error) {
 	var logs []model.UsageLog
 	err := r.db.WithContext(ctx).
 		Where("account_id = ? AND created_at >= ? AND created_at < ?", accountID, startTime, endTime).
@@ -326,7 +317,7 @@ func (r *UsageLogRepository) ListByAccountAndTimeRange(ctx context.Context, acco
 	return logs, nil, err
 }
 
-func (r *UsageLogRepository) ListByModelAndTimeRange(ctx context.Context, modelName string, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error) {
+func (r *usageLogRepository) ListByModelAndTimeRange(ctx context.Context, modelName string, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error) {
 	var logs []model.UsageLog
 	err := r.db.WithContext(ctx).
 		Where("model = ? AND created_at >= ? AND created_at < ?", modelName, startTime, endTime).
@@ -335,12 +326,12 @@ func (r *UsageLogRepository) ListByModelAndTimeRange(ctx context.Context, modelN
 	return logs, nil, err
 }
 
-func (r *UsageLogRepository) Delete(ctx context.Context, id int64) error {
+func (r *usageLogRepository) Delete(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Delete(&model.UsageLog{}, id).Error
 }
 
 // GetAccountTodayStats 获取账号今日统计
-func (r *UsageLogRepository) GetAccountTodayStats(ctx context.Context, accountID int64) (*usagestats.AccountStats, error) {
+func (r *usageLogRepository) GetAccountTodayStats(ctx context.Context, accountID int64) (*usagestats.AccountStats, error) {
 	today := timezone.Today()
 
 	var stats struct {
@@ -370,7 +361,7 @@ func (r *UsageLogRepository) GetAccountTodayStats(ctx context.Context, accountID
 }
 
 // GetAccountWindowStats 获取账号时间窗口内的统计
-func (r *UsageLogRepository) GetAccountWindowStats(ctx context.Context, accountID int64, startTime time.Time) (*usagestats.AccountStats, error) {
+func (r *usageLogRepository) GetAccountWindowStats(ctx context.Context, accountID int64, startTime time.Time) (*usagestats.AccountStats, error) {
 	var stats struct {
 		Requests int64   `gorm:"column:requests"`
 		Tokens   int64   `gorm:"column:tokens"`
@@ -398,50 +389,19 @@ func (r *UsageLogRepository) GetAccountWindowStats(ctx context.Context, accountI
 }
 
 // TrendDataPoint represents a single point in trend data
-type TrendDataPoint struct {
-	Date         string  `json:"date"`
-	Requests     int64   `json:"requests"`
-	InputTokens  int64   `json:"input_tokens"`
-	OutputTokens int64   `json:"output_tokens"`
-	CacheTokens  int64   `json:"cache_tokens"`
-	TotalTokens  int64   `json:"total_tokens"`
-	Cost         float64 `json:"cost"`        // 标准计费
-	ActualCost   float64 `json:"actual_cost"` // 实际扣除
-}
+type TrendDataPoint = usagestats.TrendDataPoint
 
 // ModelStat represents usage statistics for a single model
-type ModelStat struct {
-	Model        string  `json:"model"`
-	Requests     int64   `json:"requests"`
-	InputTokens  int64   `json:"input_tokens"`
-	OutputTokens int64   `json:"output_tokens"`
-	TotalTokens  int64   `json:"total_tokens"`
-	Cost         float64 `json:"cost"`        // 标准计费
-	ActualCost   float64 `json:"actual_cost"` // 实际扣除
-}
+type ModelStat = usagestats.ModelStat
 
 // UserUsageTrendPoint represents user usage trend data point
-type UserUsageTrendPoint struct {
-	Date       string  `json:"date"`
-	UserID     int64   `json:"user_id"`
-	Email      string  `json:"email"`
-	Requests   int64   `json:"requests"`
-	Tokens     int64   `json:"tokens"`
-	Cost       float64 `json:"cost"`        // 标准计费
-	ActualCost float64 `json:"actual_cost"` // 实际扣除
-}
+type UserUsageTrendPoint = usagestats.UserUsageTrendPoint
 
 // ApiKeyUsageTrendPoint represents API key usage trend data point
-type ApiKeyUsageTrendPoint struct {
-	Date     string `json:"date"`
-	ApiKeyID int64  `json:"api_key_id"`
-	KeyName  string `json:"key_name"`
-	Requests int64  `json:"requests"`
-	Tokens   int64  `json:"tokens"`
-}
+type ApiKeyUsageTrendPoint = usagestats.ApiKeyUsageTrendPoint
 
 // GetApiKeyUsageTrend returns usage trend data grouped by API key and date
-func (r *UsageLogRepository) GetApiKeyUsageTrend(ctx context.Context, startTime, endTime time.Time, granularity string, limit int) ([]ApiKeyUsageTrendPoint, error) {
+func (r *usageLogRepository) GetApiKeyUsageTrend(ctx context.Context, startTime, endTime time.Time, granularity string, limit int) ([]ApiKeyUsageTrendPoint, error) {
 	var results []ApiKeyUsageTrendPoint
 
 	// Choose date format based on granularity
@@ -485,7 +445,7 @@ func (r *UsageLogRepository) GetApiKeyUsageTrend(ctx context.Context, startTime,
 }
 
 // GetUserUsageTrend returns usage trend data grouped by user and date
-func (r *UsageLogRepository) GetUserUsageTrend(ctx context.Context, startTime, endTime time.Time, granularity string, limit int) ([]UserUsageTrendPoint, error) {
+func (r *usageLogRepository) GetUserUsageTrend(ctx context.Context, startTime, endTime time.Time, granularity string, limit int) ([]UserUsageTrendPoint, error) {
 	var results []UserUsageTrendPoint
 
 	// Choose date format based on granularity
@@ -531,37 +491,10 @@ func (r *UsageLogRepository) GetUserUsageTrend(ctx context.Context, startTime, e
 }
 
 // UserDashboardStats 用户仪表盘统计
-type UserDashboardStats struct {
-	// API Key 统计
-	TotalApiKeys  int64 `json:"total_api_keys"`
-	ActiveApiKeys int64 `json:"active_api_keys"`
-
-	// 累计 Token 使用统计
-	TotalRequests            int64   `json:"total_requests"`
-	TotalInputTokens         int64   `json:"total_input_tokens"`
-	TotalOutputTokens        int64   `json:"total_output_tokens"`
-	TotalCacheCreationTokens int64   `json:"total_cache_creation_tokens"`
-	TotalCacheReadTokens     int64   `json:"total_cache_read_tokens"`
-	TotalTokens              int64   `json:"total_tokens"`
-	TotalCost                float64 `json:"total_cost"`        // 累计标准计费
-	TotalActualCost          float64 `json:"total_actual_cost"` // 累计实际扣除
-
-	// 今日 Token 使用统计
-	TodayRequests            int64   `json:"today_requests"`
-	TodayInputTokens         int64   `json:"today_input_tokens"`
-	TodayOutputTokens        int64   `json:"today_output_tokens"`
-	TodayCacheCreationTokens int64   `json:"today_cache_creation_tokens"`
-	TodayCacheReadTokens     int64   `json:"today_cache_read_tokens"`
-	TodayTokens              int64   `json:"today_tokens"`
-	TodayCost                float64 `json:"today_cost"`        // 今日标准计费
-	TodayActualCost          float64 `json:"today_actual_cost"` // 今日实际扣除
-
-	// 性能统计
-	AverageDurationMs float64 `json:"average_duration_ms"`
-}
+type UserDashboardStats = usagestats.UserDashboardStats
 
 // GetUserDashboardStats 获取用户专属的仪表盘统计
-func (r *UsageLogRepository) GetUserDashboardStats(ctx context.Context, userID int64) (*UserDashboardStats, error) {
+func (r *usageLogRepository) GetUserDashboardStats(ctx context.Context, userID int64) (*UserDashboardStats, error) {
 	var stats UserDashboardStats
 	today := timezone.Today()
 
@@ -641,11 +574,14 @@ func (r *UsageLogRepository) GetUserDashboardStats(ctx context.Context, userID i
 	stats.TodayCost = todayStats.TodayCost
 	stats.TodayActualCost = todayStats.TodayActualCost
 
+	// 性能指标：RPM 和 TPM（最近1分钟，仅统计该用户的请求）
+	stats.Rpm, stats.Tpm = r.getPerformanceStats(ctx, userID)
+
 	return &stats, nil
 }
 
 // GetUserUsageTrendByUserID 获取指定用户的使用趋势
-func (r *UsageLogRepository) GetUserUsageTrendByUserID(ctx context.Context, userID int64, startTime, endTime time.Time, granularity string) ([]TrendDataPoint, error) {
+func (r *usageLogRepository) GetUserUsageTrendByUserID(ctx context.Context, userID int64, startTime, endTime time.Time, granularity string) ([]TrendDataPoint, error) {
 	var results []TrendDataPoint
 
 	var dateFormat string
@@ -679,7 +615,7 @@ func (r *UsageLogRepository) GetUserUsageTrendByUserID(ctx context.Context, user
 }
 
 // GetUserModelStats 获取指定用户的模型统计
-func (r *UsageLogRepository) GetUserModelStats(ctx context.Context, userID int64, startTime, endTime time.Time) ([]ModelStat, error) {
+func (r *usageLogRepository) GetUserModelStats(ctx context.Context, userID int64, startTime, endTime time.Time) ([]ModelStat, error) {
 	var results []ModelStat
 
 	err := r.db.WithContext(ctx).Model(&model.UsageLog{}).
@@ -705,15 +641,10 @@ func (r *UsageLogRepository) GetUserModelStats(ctx context.Context, userID int64
 }
 
 // UsageLogFilters represents filters for usage log queries
-type UsageLogFilters struct {
-	UserID    int64
-	ApiKeyID  int64
-	StartTime *time.Time
-	EndTime   *time.Time
-}
+type UsageLogFilters = usagestats.UsageLogFilters
 
 // ListWithFilters lists usage logs with optional filters (for admin)
-func (r *UsageLogRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, filters UsageLogFilters) ([]model.UsageLog, *pagination.PaginationResult, error) {
+func (r *usageLogRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, filters UsageLogFilters) ([]model.UsageLog, *pagination.PaginationResult, error) {
 	var logs []model.UsageLog
 	var total int64
 
@@ -758,26 +689,13 @@ func (r *UsageLogRepository) ListWithFilters(ctx context.Context, params paginat
 }
 
 // UsageStats represents usage statistics
-type UsageStats struct {
-	TotalRequests     int64   `json:"total_requests"`
-	TotalInputTokens  int64   `json:"total_input_tokens"`
-	TotalOutputTokens int64   `json:"total_output_tokens"`
-	TotalCacheTokens  int64   `json:"total_cache_tokens"`
-	TotalTokens       int64   `json:"total_tokens"`
-	TotalCost         float64 `json:"total_cost"`
-	TotalActualCost   float64 `json:"total_actual_cost"`
-	AverageDurationMs float64 `json:"average_duration_ms"`
-}
+type UsageStats = usagestats.UsageStats
 
 // BatchUserUsageStats represents usage stats for a single user
-type BatchUserUsageStats struct {
-	UserID          int64   `json:"user_id"`
-	TodayActualCost float64 `json:"today_actual_cost"`
-	TotalActualCost float64 `json:"total_actual_cost"`
-}
+type BatchUserUsageStats = usagestats.BatchUserUsageStats
 
 // GetBatchUserUsageStats gets today and total actual_cost for multiple users
-func (r *UsageLogRepository) GetBatchUserUsageStats(ctx context.Context, userIDs []int64) (map[int64]*BatchUserUsageStats, error) {
+func (r *usageLogRepository) GetBatchUserUsageStats(ctx context.Context, userIDs []int64) (map[int64]*BatchUserUsageStats, error) {
 	if len(userIDs) == 0 {
 		return make(map[int64]*BatchUserUsageStats), nil
 	}
@@ -834,14 +752,10 @@ func (r *UsageLogRepository) GetBatchUserUsageStats(ctx context.Context, userIDs
 }
 
 // BatchApiKeyUsageStats represents usage stats for a single API key
-type BatchApiKeyUsageStats struct {
-	ApiKeyID        int64   `json:"api_key_id"`
-	TodayActualCost float64 `json:"today_actual_cost"`
-	TotalActualCost float64 `json:"total_actual_cost"`
-}
+type BatchApiKeyUsageStats = usagestats.BatchApiKeyUsageStats
 
 // GetBatchApiKeyUsageStats gets today and total actual_cost for multiple API keys
-func (r *UsageLogRepository) GetBatchApiKeyUsageStats(ctx context.Context, apiKeyIDs []int64) (map[int64]*BatchApiKeyUsageStats, error) {
+func (r *usageLogRepository) GetBatchApiKeyUsageStats(ctx context.Context, apiKeyIDs []int64) (map[int64]*BatchApiKeyUsageStats, error) {
 	if len(apiKeyIDs) == 0 {
 		return make(map[int64]*BatchApiKeyUsageStats), nil
 	}
@@ -898,7 +812,7 @@ func (r *UsageLogRepository) GetBatchApiKeyUsageStats(ctx context.Context, apiKe
 }
 
 // GetUsageTrendWithFilters returns usage trend data with optional user/api_key filters
-func (r *UsageLogRepository) GetUsageTrendWithFilters(ctx context.Context, startTime, endTime time.Time, granularity string, userID, apiKeyID int64) ([]TrendDataPoint, error) {
+func (r *usageLogRepository) GetUsageTrendWithFilters(ctx context.Context, startTime, endTime time.Time, granularity string, userID, apiKeyID int64) ([]TrendDataPoint, error) {
 	var results []TrendDataPoint
 
 	var dateFormat string
@@ -937,7 +851,7 @@ func (r *UsageLogRepository) GetUsageTrendWithFilters(ctx context.Context, start
 }
 
 // GetModelStatsWithFilters returns model statistics with optional user/api_key filters
-func (r *UsageLogRepository) GetModelStatsWithFilters(ctx context.Context, startTime, endTime time.Time, userID, apiKeyID, accountID int64) ([]ModelStat, error) {
+func (r *usageLogRepository) GetModelStatsWithFilters(ctx context.Context, startTime, endTime time.Time, userID, apiKeyID, accountID int64) ([]ModelStat, error) {
 	var results []ModelStat
 
 	db := r.db.WithContext(ctx).Model(&model.UsageLog{}).
@@ -971,7 +885,7 @@ func (r *UsageLogRepository) GetModelStatsWithFilters(ctx context.Context, start
 }
 
 // GetGlobalStats gets usage statistics for all users within a time range
-func (r *UsageLogRepository) GetGlobalStats(ctx context.Context, startTime, endTime time.Time) (*UsageStats, error) {
+func (r *usageLogRepository) GetGlobalStats(ctx context.Context, startTime, endTime time.Time) (*UsageStats, error) {
 	var stats struct {
 		TotalRequests     int64   `gorm:"column:total_requests"`
 		TotalInputTokens  int64   `gorm:"column:total_input_tokens"`
@@ -1012,56 +926,16 @@ func (r *UsageLogRepository) GetGlobalStats(ctx context.Context, startTime, endT
 }
 
 // AccountUsageHistory represents daily usage history for an account
-type AccountUsageHistory struct {
-	Date       string  `json:"date"`
-	Label      string  `json:"label"`
-	Requests   int64   `json:"requests"`
-	Tokens     int64   `json:"tokens"`
-	Cost       float64 `json:"cost"`
-	ActualCost float64 `json:"actual_cost"`
-}
+type AccountUsageHistory = usagestats.AccountUsageHistory
 
 // AccountUsageSummary represents summary statistics for an account
-type AccountUsageSummary struct {
-	Days              int     `json:"days"`
-	ActualDaysUsed    int     `json:"actual_days_used"`
-	TotalCost         float64 `json:"total_cost"`
-	TotalStandardCost float64 `json:"total_standard_cost"`
-	TotalRequests     int64   `json:"total_requests"`
-	TotalTokens       int64   `json:"total_tokens"`
-	AvgDailyCost      float64 `json:"avg_daily_cost"`
-	AvgDailyRequests  float64 `json:"avg_daily_requests"`
-	AvgDailyTokens    float64 `json:"avg_daily_tokens"`
-	AvgDurationMs     float64 `json:"avg_duration_ms"`
-	Today             *struct {
-		Date     string  `json:"date"`
-		Cost     float64 `json:"cost"`
-		Requests int64   `json:"requests"`
-		Tokens   int64   `json:"tokens"`
-	} `json:"today"`
-	HighestCostDay *struct {
-		Date     string  `json:"date"`
-		Label    string  `json:"label"`
-		Cost     float64 `json:"cost"`
-		Requests int64   `json:"requests"`
-	} `json:"highest_cost_day"`
-	HighestRequestDay *struct {
-		Date     string  `json:"date"`
-		Label    string  `json:"label"`
-		Requests int64   `json:"requests"`
-		Cost     float64 `json:"cost"`
-	} `json:"highest_request_day"`
-}
+type AccountUsageSummary = usagestats.AccountUsageSummary
 
 // AccountUsageStatsResponse represents the full usage statistics response for an account
-type AccountUsageStatsResponse struct {
-	History []AccountUsageHistory `json:"history"`
-	Summary AccountUsageSummary   `json:"summary"`
-	Models  []ModelStat           `json:"models"`
-}
+type AccountUsageStatsResponse = usagestats.AccountUsageStatsResponse
 
 // GetAccountUsageStats returns comprehensive usage statistics for an account over a time range
-func (r *UsageLogRepository) GetAccountUsageStats(ctx context.Context, accountID int64, startTime, endTime time.Time) (*AccountUsageStatsResponse, error) {
+func (r *usageLogRepository) GetAccountUsageStats(ctx context.Context, accountID int64, startTime, endTime time.Time) (*AccountUsageStatsResponse, error) {
 	daysCount := int(endTime.Sub(startTime).Hours()/24) + 1
 	if daysCount <= 0 {
 		daysCount = 30

backend/internal/repository/usage_log_repo_integration_test.go

@@ -0,0 +1,890 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
+	"github.com/stretchr/testify/suite"
+	"gorm.io/gorm"
+)
+
+type UsageLogRepoSuite struct {
+	suite.Suite
+	ctx  context.Context
+	db   *gorm.DB
+	repo *usageLogRepository
+}
+
+func (s *UsageLogRepoSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+	s.repo = NewUsageLogRepository(s.db).(*usageLogRepository)
+}
+
+func TestUsageLogRepoSuite(t *testing.T) {
+	suite.Run(t, new(UsageLogRepoSuite))
+}
+
+func (s *UsageLogRepoSuite) createUsageLog(user *model.User, apiKey *model.ApiKey, account *model.Account, inputTokens, outputTokens int, cost float64, createdAt time.Time) *model.UsageLog {
+	log := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3",
+		InputTokens:  inputTokens,
+		OutputTokens: outputTokens,
+		TotalCost:    cost,
+		ActualCost:   cost,
+		CreatedAt:    createdAt,
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log))
+	return log
+}
+
+// --- Create / GetByID ---
+
+func (s *UsageLogRepoSuite) TestCreate() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "create@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-create", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-create"})
+
+	log := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3",
+		InputTokens:  10,
+		OutputTokens: 20,
+		TotalCost:    0.5,
+		ActualCost:   0.4,
+	}
+
+	err := s.repo.Create(s.ctx, log)
+	s.Require().NoError(err, "Create")
+	s.Require().NotZero(log.ID)
+}
+
+func (s *UsageLogRepoSuite) TestGetByID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "getbyid@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-getbyid", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-getbyid"})
+
+	log := s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+
+	got, err := s.repo.GetByID(s.ctx, log.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal(log.ID, got.ID)
+	s.Require().Equal(10, got.InputTokens)
+}
+
+func (s *UsageLogRepoSuite) TestGetByID_NotFound() {
+	_, err := s.repo.GetByID(s.ctx, 999999)
+	s.Require().Error(err, "expected error for non-existent ID")
+}
+
+// --- Delete ---
+
+func (s *UsageLogRepoSuite) TestDelete() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "delete@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-delete", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-delete"})
+
+	log := s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+
+	err := s.repo.Delete(s.ctx, log.ID)
+	s.Require().NoError(err, "Delete")
+
+	_, err = s.repo.GetByID(s.ctx, log.ID)
+	s.Require().Error(err, "expected error after delete")
+}
+
+// --- ListByUser ---
+
+func (s *UsageLogRepoSuite) TestListByUser() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "listbyuser@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-listbyuser", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-listbyuser"})
+
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, time.Now())
+
+	logs, page, err := s.repo.ListByUser(s.ctx, user.ID, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "ListByUser")
+	s.Require().Len(logs, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+// --- ListByApiKey ---
+
+func (s *UsageLogRepoSuite) TestListByApiKey() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "listbyapikey@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-listbyapikey", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-listbyapikey"})
+
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, time.Now())
+
+	logs, page, err := s.repo.ListByApiKey(s.ctx, apiKey.ID, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "ListByApiKey")
+	s.Require().Len(logs, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+// --- ListByAccount ---
+
+func (s *UsageLogRepoSuite) TestListByAccount() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "listbyaccount@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-listbyaccount", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-listbyaccount"})
+
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+
+	logs, page, err := s.repo.ListByAccount(s.ctx, account.ID, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "ListByAccount")
+	s.Require().Len(logs, 1)
+	s.Require().Equal(int64(1), page.Total)
+}
+
+// --- GetUserStats ---
+
+func (s *UsageLogRepoSuite) TestGetUserStats() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "userstats@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-userstats", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-userstats"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(1*time.Hour))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+	stats, err := s.repo.GetUserStats(s.ctx, user.ID, startTime, endTime)
+	s.Require().NoError(err, "GetUserStats")
+	s.Require().Equal(int64(2), stats.TotalRequests)
+	s.Require().Equal(int64(25), stats.InputTokens)
+	s.Require().Equal(int64(45), stats.OutputTokens)
+}
+
+// --- ListWithFilters ---
+
+func (s *UsageLogRepoSuite) TestListWithFilters() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "filters@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-filters", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-filters"})
+
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+
+	filters := usagestats.UsageLogFilters{UserID: user.ID}
+	logs, page, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, filters)
+	s.Require().NoError(err, "ListWithFilters")
+	s.Require().Len(logs, 1)
+	s.Require().Equal(int64(1), page.Total)
+}
+
+// --- GetDashboardStats ---
+
+func (s *UsageLogRepoSuite) TestDashboardStats_TodayTotalsAndPerformance() {
+	now := time.Now()
+	todayStart := timezone.Today()
+
+	userToday := mustCreateUser(s.T(), s.db, &model.User{
+		Email:     "today@example.com",
+		CreatedAt: maxTime(todayStart.Add(10*time.Second), now.Add(-10*time.Second)),
+		UpdatedAt: now,
+	})
+	userOld := mustCreateUser(s.T(), s.db, &model.User{
+		Email:     "old@example.com",
+		CreatedAt: todayStart.Add(-24 * time.Hour),
+		UpdatedAt: todayStart.Add(-24 * time.Hour),
+	})
+
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-ul"})
+	apiKey1 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: userToday.ID, Key: "sk-ul-1", Name: "ul1"})
+	mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: userOld.ID, Key: "sk-ul-2", Name: "ul2", Status: model.StatusDisabled})
+
+	resetAt := now.Add(10 * time.Minute)
+	accNormal := mustCreateAccount(s.T(), s.db, &model.Account{Name: "a-normal", Schedulable: true})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a-error", Status: model.StatusError, Schedulable: true})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a-rl", RateLimitedAt: &now, RateLimitResetAt: &resetAt, Schedulable: true})
+	mustCreateAccount(s.T(), s.db, &model.Account{Name: "a-ov", OverloadUntil: &resetAt, Schedulable: true})
+
+	d1, d2, d3 := 100, 200, 300
+	logToday := &model.UsageLog{
+		UserID:              userToday.ID,
+		ApiKeyID:            apiKey1.ID,
+		AccountID:           accNormal.ID,
+		Model:               "claude-3",
+		GroupID:             &group.ID,
+		InputTokens:         10,
+		OutputTokens:        20,
+		CacheCreationTokens: 3,
+		CacheReadTokens:     4,
+		TotalCost:           1.5,
+		ActualCost:          1.2,
+		DurationMs:          &d1,
+		CreatedAt:           maxTime(todayStart.Add(2*time.Minute), now.Add(-2*time.Minute)),
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, logToday), "Create logToday")
+
+	logOld := &model.UsageLog{
+		UserID:       userOld.ID,
+		ApiKeyID:     apiKey1.ID,
+		AccountID:    accNormal.ID,
+		Model:        "claude-3",
+		InputTokens:  5,
+		OutputTokens: 6,
+		TotalCost:    0.7,
+		ActualCost:   0.7,
+		DurationMs:   &d2,
+		CreatedAt:    todayStart.Add(-1 * time.Hour),
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, logOld), "Create logOld")
+
+	logPerf := &model.UsageLog{
+		UserID:       userToday.ID,
+		ApiKeyID:     apiKey1.ID,
+		AccountID:    accNormal.ID,
+		Model:        "claude-3",
+		InputTokens:  1,
+		OutputTokens: 2,
+		TotalCost:    0.1,
+		ActualCost:   0.1,
+		DurationMs:   &d3,
+		CreatedAt:    now.Add(-30 * time.Second),
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, logPerf), "Create logPerf")
+
+	stats, err := s.repo.GetDashboardStats(s.ctx)
+	s.Require().NoError(err, "GetDashboardStats")
+
+	s.Require().Equal(int64(2), stats.TotalUsers, "TotalUsers mismatch")
+	s.Require().Equal(int64(1), stats.TodayNewUsers, "TodayNewUsers mismatch")
+	s.Require().Equal(int64(1), stats.ActiveUsers, "ActiveUsers mismatch")
+	s.Require().Equal(int64(2), stats.TotalApiKeys, "TotalApiKeys mismatch")
+	s.Require().Equal(int64(1), stats.ActiveApiKeys, "ActiveApiKeys mismatch")
+	s.Require().Equal(int64(4), stats.TotalAccounts, "TotalAccounts mismatch")
+	s.Require().Equal(int64(1), stats.ErrorAccounts, "ErrorAccounts mismatch")
+	s.Require().Equal(int64(1), stats.RateLimitAccounts, "RateLimitAccounts mismatch")
+	s.Require().Equal(int64(1), stats.OverloadAccounts, "OverloadAccounts mismatch")
+
+	s.Require().Equal(int64(3), stats.TotalRequests, "TotalRequests mismatch")
+	s.Require().Equal(int64(16), stats.TotalInputTokens, "TotalInputTokens mismatch")
+	s.Require().Equal(int64(28), stats.TotalOutputTokens, "TotalOutputTokens mismatch")
+	s.Require().Equal(int64(3), stats.TotalCacheCreationTokens, "TotalCacheCreationTokens mismatch")
+	s.Require().Equal(int64(4), stats.TotalCacheReadTokens, "TotalCacheReadTokens mismatch")
+	s.Require().Equal(int64(51), stats.TotalTokens, "TotalTokens mismatch")
+	s.Require().Equal(2.3, stats.TotalCost, "TotalCost mismatch")
+	s.Require().Equal(2.0, stats.TotalActualCost, "TotalActualCost mismatch")
+	s.Require().GreaterOrEqual(stats.TodayRequests, int64(1), "expected TodayRequests >= 1")
+	s.Require().GreaterOrEqual(stats.TodayCost, 0.0, "expected TodayCost >= 0")
+
+	wantRpm, wantTpm := s.repo.getPerformanceStats(s.ctx, 0)
+	s.Require().Equal(wantRpm, stats.Rpm, "Rpm mismatch")
+	s.Require().Equal(wantTpm, stats.Tpm, "Tpm mismatch")
+}
+
+// --- GetUserDashboardStats ---
+
+func (s *UsageLogRepoSuite) TestGetUserDashboardStats() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "userdash@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-userdash", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-userdash"})
+
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+
+	stats, err := s.repo.GetUserDashboardStats(s.ctx, user.ID)
+	s.Require().NoError(err, "GetUserDashboardStats")
+	s.Require().Equal(int64(1), stats.TotalApiKeys)
+	s.Require().Equal(int64(1), stats.TotalRequests)
+}
+
+// --- GetAccountTodayStats ---
+
+func (s *UsageLogRepoSuite) TestGetAccountTodayStats() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "acctoday@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-acctoday", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-today"})
+
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+
+	stats, err := s.repo.GetAccountTodayStats(s.ctx, account.ID)
+	s.Require().NoError(err, "GetAccountTodayStats")
+	s.Require().Equal(int64(1), stats.Requests)
+	s.Require().Equal(int64(30), stats.Tokens)
+}
+
+// --- GetBatchUserUsageStats ---
+
+func (s *UsageLogRepoSuite) TestGetBatchUserUsageStats() {
+	user1 := mustCreateUser(s.T(), s.db, &model.User{Email: "batch1@test.com"})
+	user2 := mustCreateUser(s.T(), s.db, &model.User{Email: "batch2@test.com"})
+	apiKey1 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user1.ID, Key: "sk-batch1", Name: "k"})
+	apiKey2 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user2.ID, Key: "sk-batch2", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-batch"})
+
+	s.createUsageLog(user1, apiKey1, account, 10, 20, 0.5, time.Now())
+	s.createUsageLog(user2, apiKey2, account, 15, 25, 0.6, time.Now())
+
+	stats, err := s.repo.GetBatchUserUsageStats(s.ctx, []int64{user1.ID, user2.ID})
+	s.Require().NoError(err, "GetBatchUserUsageStats")
+	s.Require().Len(stats, 2)
+	s.Require().NotNil(stats[user1.ID])
+	s.Require().NotNil(stats[user2.ID])
+}
+
+func (s *UsageLogRepoSuite) TestGetBatchUserUsageStats_Empty() {
+	stats, err := s.repo.GetBatchUserUsageStats(s.ctx, []int64{})
+	s.Require().NoError(err)
+	s.Require().Empty(stats)
+}
+
+// --- GetBatchApiKeyUsageStats ---
+
+func (s *UsageLogRepoSuite) TestGetBatchApiKeyUsageStats() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "batchkey@test.com"})
+	apiKey1 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-batchkey1", Name: "k1"})
+	apiKey2 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-batchkey2", Name: "k2"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-batchkey"})
+
+	s.createUsageLog(user, apiKey1, account, 10, 20, 0.5, time.Now())
+	s.createUsageLog(user, apiKey2, account, 15, 25, 0.6, time.Now())
+
+	stats, err := s.repo.GetBatchApiKeyUsageStats(s.ctx, []int64{apiKey1.ID, apiKey2.ID})
+	s.Require().NoError(err, "GetBatchApiKeyUsageStats")
+	s.Require().Len(stats, 2)
+}
+
+func (s *UsageLogRepoSuite) TestGetBatchApiKeyUsageStats_Empty() {
+	stats, err := s.repo.GetBatchApiKeyUsageStats(s.ctx, []int64{})
+	s.Require().NoError(err)
+	s.Require().Empty(stats)
+}
+
+// --- GetGlobalStats ---
+
+func (s *UsageLogRepoSuite) TestGetGlobalStats() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "global@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-global", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-global"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(1*time.Hour))
+
+	stats, err := s.repo.GetGlobalStats(s.ctx, base.Add(-1*time.Hour), base.Add(2*time.Hour))
+	s.Require().NoError(err, "GetGlobalStats")
+	s.Require().Equal(int64(2), stats.TotalRequests)
+	s.Require().Equal(int64(25), stats.TotalInputTokens)
+	s.Require().Equal(int64(45), stats.TotalOutputTokens)
+}
+
+func maxTime(a, b time.Time) time.Time {
+	if a.After(b) {
+		return a
+	}
+	return b
+}
+
+// --- ListByUserAndTimeRange ---
+
+func (s *UsageLogRepoSuite) TestListByUserAndTimeRange() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "timerange@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-timerange", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-timerange"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(1*time.Hour))
+	s.createUsageLog(user, apiKey, account, 20, 30, 0.7, base.Add(-24*time.Hour)) // outside range
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+	logs, _, err := s.repo.ListByUserAndTimeRange(s.ctx, user.ID, startTime, endTime)
+	s.Require().NoError(err, "ListByUserAndTimeRange")
+	s.Require().Len(logs, 2)
+}
+
+// --- ListByApiKeyAndTimeRange ---
+
+func (s *UsageLogRepoSuite) TestListByApiKeyAndTimeRange() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "keytimerange@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-keytimerange", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-keytimerange"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(30*time.Minute))
+	s.createUsageLog(user, apiKey, account, 20, 30, 0.7, base.Add(-24*time.Hour)) // outside range
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+	logs, _, err := s.repo.ListByApiKeyAndTimeRange(s.ctx, apiKey.ID, startTime, endTime)
+	s.Require().NoError(err, "ListByApiKeyAndTimeRange")
+	s.Require().Len(logs, 2)
+}
+
+// --- ListByAccountAndTimeRange ---
+
+func (s *UsageLogRepoSuite) TestListByAccountAndTimeRange() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "acctimerange@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-acctimerange", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-acctimerange"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(45*time.Minute))
+	s.createUsageLog(user, apiKey, account, 20, 30, 0.7, base.Add(-24*time.Hour)) // outside range
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+	logs, _, err := s.repo.ListByAccountAndTimeRange(s.ctx, account.ID, startTime, endTime)
+	s.Require().NoError(err, "ListByAccountAndTimeRange")
+	s.Require().Len(logs, 2)
+}
+
+// --- ListByModelAndTimeRange ---
+
+func (s *UsageLogRepoSuite) TestListByModelAndTimeRange() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "modeltimerange@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-modeltimerange", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-modeltimerange"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+
+	// Create logs with different models
+	log1 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-opus",
+		InputTokens:  10,
+		OutputTokens: 20,
+		TotalCost:    0.5,
+		ActualCost:   0.5,
+		CreatedAt:    base,
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log1))
+
+	log2 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-opus",
+		InputTokens:  15,
+		OutputTokens: 25,
+		TotalCost:    0.6,
+		ActualCost:   0.6,
+		CreatedAt:    base.Add(30 * time.Minute),
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log2))
+
+	log3 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-sonnet",
+		InputTokens:  20,
+		OutputTokens: 30,
+		TotalCost:    0.7,
+		ActualCost:   0.7,
+		CreatedAt:    base.Add(1 * time.Hour),
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log3))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+	logs, _, err := s.repo.ListByModelAndTimeRange(s.ctx, "claude-3-opus", startTime, endTime)
+	s.Require().NoError(err, "ListByModelAndTimeRange")
+	s.Require().Len(logs, 2)
+}
+
+// --- GetAccountWindowStats ---
+
+func (s *UsageLogRepoSuite) TestGetAccountWindowStats() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "windowstats@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-windowstats", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-windowstats"})
+
+	now := time.Now()
+	windowStart := now.Add(-10 * time.Minute)
+
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, now.Add(-5*time.Minute))
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, now.Add(-3*time.Minute))
+	s.createUsageLog(user, apiKey, account, 20, 30, 0.7, now.Add(-30*time.Minute)) // outside window
+
+	stats, err := s.repo.GetAccountWindowStats(s.ctx, account.ID, windowStart)
+	s.Require().NoError(err, "GetAccountWindowStats")
+	s.Require().Equal(int64(2), stats.Requests)
+	s.Require().Equal(int64(70), stats.Tokens) // (10+20) + (15+25)
+}
+
+// --- GetUserUsageTrendByUserID ---
+
+func (s *UsageLogRepoSuite) TestGetUserUsageTrendByUserID() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "usertrend@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-usertrend", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-usertrend"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(1*time.Hour))
+	s.createUsageLog(user, apiKey, account, 20, 30, 0.7, base.Add(24*time.Hour)) // next day
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(48 * time.Hour)
+	trend, err := s.repo.GetUserUsageTrendByUserID(s.ctx, user.ID, startTime, endTime, "day")
+	s.Require().NoError(err, "GetUserUsageTrendByUserID")
+	s.Require().Len(trend, 2) // 2 different days
+}
+
+func (s *UsageLogRepoSuite) TestGetUserUsageTrendByUserID_HourlyGranularity() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "usertrendhourly@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-usertrendhourly", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-usertrendhourly"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(1*time.Hour))
+	s.createUsageLog(user, apiKey, account, 20, 30, 0.7, base.Add(2*time.Hour))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(3 * time.Hour)
+	trend, err := s.repo.GetUserUsageTrendByUserID(s.ctx, user.ID, startTime, endTime, "hour")
+	s.Require().NoError(err, "GetUserUsageTrendByUserID hourly")
+	s.Require().Len(trend, 3) // 3 different hours
+}
+
+// --- GetUserModelStats ---
+
+func (s *UsageLogRepoSuite) TestGetUserModelStats() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "modelstats@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-modelstats", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-modelstats"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+
+	// Create logs with different models
+	log1 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-opus",
+		InputTokens:  100,
+		OutputTokens: 200,
+		TotalCost:    0.5,
+		ActualCost:   0.5,
+		CreatedAt:    base,
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log1))
+
+	log2 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-sonnet",
+		InputTokens:  50,
+		OutputTokens: 100,
+		TotalCost:    0.2,
+		ActualCost:   0.2,
+		CreatedAt:    base.Add(1 * time.Hour),
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log2))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+	stats, err := s.repo.GetUserModelStats(s.ctx, user.ID, startTime, endTime)
+	s.Require().NoError(err, "GetUserModelStats")
+	s.Require().Len(stats, 2)
+
+	// Should be ordered by total_tokens DESC
+	s.Require().Equal("claude-3-opus", stats[0].Model)
+	s.Require().Equal(int64(300), stats[0].TotalTokens)
+}
+
+// --- GetUsageTrendWithFilters ---
+
+func (s *UsageLogRepoSuite) TestGetUsageTrendWithFilters() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "trendfilters@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-trendfilters", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-trendfilters"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(24*time.Hour))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(48 * time.Hour)
+
+	// Test with user filter
+	trend, err := s.repo.GetUsageTrendWithFilters(s.ctx, startTime, endTime, "day", user.ID, 0)
+	s.Require().NoError(err, "GetUsageTrendWithFilters user filter")
+	s.Require().Len(trend, 2)
+
+	// Test with apiKey filter
+	trend, err = s.repo.GetUsageTrendWithFilters(s.ctx, startTime, endTime, "day", 0, apiKey.ID)
+	s.Require().NoError(err, "GetUsageTrendWithFilters apiKey filter")
+	s.Require().Len(trend, 2)
+
+	// Test with both filters
+	trend, err = s.repo.GetUsageTrendWithFilters(s.ctx, startTime, endTime, "day", user.ID, apiKey.ID)
+	s.Require().NoError(err, "GetUsageTrendWithFilters both filters")
+	s.Require().Len(trend, 2)
+}
+
+func (s *UsageLogRepoSuite) TestGetUsageTrendWithFilters_HourlyGranularity() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "trendfilters-h@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-trendfilters-h", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-trendfilters-h"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(1*time.Hour))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(3 * time.Hour)
+
+	trend, err := s.repo.GetUsageTrendWithFilters(s.ctx, startTime, endTime, "hour", user.ID, 0)
+	s.Require().NoError(err, "GetUsageTrendWithFilters hourly")
+	s.Require().Len(trend, 2)
+}
+
+// --- GetModelStatsWithFilters ---
+
+func (s *UsageLogRepoSuite) TestGetModelStatsWithFilters() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "modelfilters@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-modelfilters", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-modelfilters"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+
+	log1 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-opus",
+		InputTokens:  100,
+		OutputTokens: 200,
+		TotalCost:    0.5,
+		ActualCost:   0.5,
+		CreatedAt:    base,
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log1))
+
+	log2 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-sonnet",
+		InputTokens:  50,
+		OutputTokens: 100,
+		TotalCost:    0.2,
+		ActualCost:   0.2,
+		CreatedAt:    base.Add(1 * time.Hour),
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log2))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+
+	// Test with user filter
+	stats, err := s.repo.GetModelStatsWithFilters(s.ctx, startTime, endTime, user.ID, 0, 0)
+	s.Require().NoError(err, "GetModelStatsWithFilters user filter")
+	s.Require().Len(stats, 2)
+
+	// Test with apiKey filter
+	stats, err = s.repo.GetModelStatsWithFilters(s.ctx, startTime, endTime, 0, apiKey.ID, 0)
+	s.Require().NoError(err, "GetModelStatsWithFilters apiKey filter")
+	s.Require().Len(stats, 2)
+
+	// Test with account filter
+	stats, err = s.repo.GetModelStatsWithFilters(s.ctx, startTime, endTime, 0, 0, account.ID)
+	s.Require().NoError(err, "GetModelStatsWithFilters account filter")
+	s.Require().Len(stats, 2)
+}
+
+// --- GetAccountUsageStats ---
+
+func (s *UsageLogRepoSuite) TestGetAccountUsageStats() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "accstats@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-accstats", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-accstats"})
+
+	base := time.Date(2025, 1, 15, 0, 0, 0, 0, time.UTC)
+
+	// Create logs on different days
+	log1 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-opus",
+		InputTokens:  100,
+		OutputTokens: 200,
+		TotalCost:    0.5,
+		ActualCost:   0.4,
+		CreatedAt:    base.Add(12 * time.Hour),
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log1))
+
+	log2 := &model.UsageLog{
+		UserID:       user.ID,
+		ApiKeyID:     apiKey.ID,
+		AccountID:    account.ID,
+		Model:        "claude-3-sonnet",
+		InputTokens:  50,
+		OutputTokens: 100,
+		TotalCost:    0.2,
+		ActualCost:   0.15,
+		CreatedAt:    base.Add(36 * time.Hour), // next day
+	}
+	s.Require().NoError(s.repo.Create(s.ctx, log2))
+
+	startTime := base
+	endTime := base.Add(72 * time.Hour)
+
+	resp, err := s.repo.GetAccountUsageStats(s.ctx, account.ID, startTime, endTime)
+	s.Require().NoError(err, "GetAccountUsageStats")
+
+	s.Require().Len(resp.History, 2, "expected 2 days of history")
+	s.Require().Equal(int64(2), resp.Summary.TotalRequests)
+	s.Require().Equal(int64(450), resp.Summary.TotalTokens)
+	s.Require().Len(resp.Models, 2)
+}
+
+func (s *UsageLogRepoSuite) TestGetAccountUsageStats_EmptyRange() {
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-emptystats"})
+
+	base := time.Date(2025, 1, 15, 0, 0, 0, 0, time.UTC)
+	startTime := base
+	endTime := base.Add(72 * time.Hour)
+
+	resp, err := s.repo.GetAccountUsageStats(s.ctx, account.ID, startTime, endTime)
+	s.Require().NoError(err, "GetAccountUsageStats empty")
+
+	s.Require().Len(resp.History, 0)
+	s.Require().Equal(int64(0), resp.Summary.TotalRequests)
+}
+
+// --- GetUserUsageTrend ---
+
+func (s *UsageLogRepoSuite) TestGetUserUsageTrend() {
+	user1 := mustCreateUser(s.T(), s.db, &model.User{Email: "usertrend1@test.com"})
+	user2 := mustCreateUser(s.T(), s.db, &model.User{Email: "usertrend2@test.com"})
+	apiKey1 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user1.ID, Key: "sk-usertrend1", Name: "k1"})
+	apiKey2 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user2.ID, Key: "sk-usertrend2", Name: "k2"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-usertrends"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user1, apiKey1, account, 100, 200, 1.0, base)
+	s.createUsageLog(user2, apiKey2, account, 50, 100, 0.5, base)
+	s.createUsageLog(user1, apiKey1, account, 100, 200, 1.0, base.Add(24*time.Hour))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(48 * time.Hour)
+
+	trend, err := s.repo.GetUserUsageTrend(s.ctx, startTime, endTime, "day", 10)
+	s.Require().NoError(err, "GetUserUsageTrend")
+	s.Require().GreaterOrEqual(len(trend), 2)
+}
+
+// --- GetApiKeyUsageTrend ---
+
+func (s *UsageLogRepoSuite) TestGetApiKeyUsageTrend() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "keytrend@test.com"})
+	apiKey1 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-keytrend1", Name: "k1"})
+	apiKey2 := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-keytrend2", Name: "k2"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-keytrends"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey1, account, 100, 200, 1.0, base)
+	s.createUsageLog(user, apiKey2, account, 50, 100, 0.5, base)
+	s.createUsageLog(user, apiKey1, account, 100, 200, 1.0, base.Add(24*time.Hour))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(48 * time.Hour)
+
+	trend, err := s.repo.GetApiKeyUsageTrend(s.ctx, startTime, endTime, "day", 10)
+	s.Require().NoError(err, "GetApiKeyUsageTrend")
+	s.Require().GreaterOrEqual(len(trend), 2)
+}
+
+func (s *UsageLogRepoSuite) TestGetApiKeyUsageTrend_HourlyGranularity() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "keytrendh@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-keytrendh", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-keytrendh"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 100, 200, 1.0, base)
+	s.createUsageLog(user, apiKey, account, 50, 100, 0.5, base.Add(1*time.Hour))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(3 * time.Hour)
+
+	trend, err := s.repo.GetApiKeyUsageTrend(s.ctx, startTime, endTime, "hour", 10)
+	s.Require().NoError(err, "GetApiKeyUsageTrend hourly")
+	s.Require().Len(trend, 2)
+}
+
+// --- ListWithFilters (additional filter tests) ---
+
+func (s *UsageLogRepoSuite) TestListWithFilters_ApiKeyFilter() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "filterskey@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-filterskey", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-filterskey"})
+
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, time.Now())
+
+	filters := usagestats.UsageLogFilters{ApiKeyID: apiKey.ID}
+	logs, page, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, filters)
+	s.Require().NoError(err, "ListWithFilters apiKey")
+	s.Require().Len(logs, 1)
+	s.Require().Equal(int64(1), page.Total)
+}
+
+func (s *UsageLogRepoSuite) TestListWithFilters_TimeRange() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "filterstime@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-filterstime", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-filterstime"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(1*time.Hour))
+	s.createUsageLog(user, apiKey, account, 20, 30, 0.7, base.Add(-24*time.Hour)) // outside range
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+	filters := usagestats.UsageLogFilters{StartTime: &startTime, EndTime: &endTime}
+	logs, page, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, filters)
+	s.Require().NoError(err, "ListWithFilters time range")
+	s.Require().Len(logs, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+func (s *UsageLogRepoSuite) TestListWithFilters_CombinedFilters() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "filterscombined@test.com"})
+	apiKey := mustCreateApiKey(s.T(), s.db, &model.ApiKey{UserID: user.ID, Key: "sk-filterscombined", Name: "k"})
+	account := mustCreateAccount(s.T(), s.db, &model.Account{Name: "acc-filterscombined"})
+
+	base := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
+	s.createUsageLog(user, apiKey, account, 10, 20, 0.5, base)
+	s.createUsageLog(user, apiKey, account, 15, 25, 0.6, base.Add(1*time.Hour))
+
+	startTime := base.Add(-1 * time.Hour)
+	endTime := base.Add(2 * time.Hour)
+	filters := usagestats.UsageLogFilters{
+		UserID:    user.ID,
+		ApiKeyID:  apiKey.ID,
+		StartTime: &startTime,
+		EndTime:   &endTime,
+	}
+	logs, page, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, filters)
+	s.Require().NoError(err, "ListWithFilters combined")
+	s.Require().Len(logs, 2)
+	s.Require().Equal(int64(2), page.Total)
+}

backend/internal/repository/user_repo.go

@@ -2,56 +2,61 @@ package repository
 
 import (
 	"context"
-	"sub2api/internal/model"
-	"sub2api/internal/pkg/pagination"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
 )
 
-type UserRepository struct {
+type userRepository struct {
 	db *gorm.DB
 }
 
-func NewUserRepository(db *gorm.DB) *UserRepository {
-	return &UserRepository{db: db}
+func NewUserRepository(db *gorm.DB) service.UserRepository {
+	return &userRepository{db: db}
 }
 
-func (r *UserRepository) Create(ctx context.Context, user *model.User) error {
-	return r.db.WithContext(ctx).Create(user).Error
+func (r *userRepository) Create(ctx context.Context, user *model.User) error {
+	err := r.db.WithContext(ctx).Create(user).Error
+	return translatePersistenceError(err, nil, service.ErrEmailExists)
 }
 
-func (r *UserRepository) GetByID(ctx context.Context, id int64) (*model.User, error) {
+func (r *userRepository) GetByID(ctx context.Context, id int64) (*model.User, error) {
 	var user model.User
 	err := r.db.WithContext(ctx).First(&user, id).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrUserNotFound, nil)
 	}
 	return &user, nil
 }
 
-func (r *UserRepository) GetByEmail(ctx context.Context, email string) (*model.User, error) {
+func (r *userRepository) GetByEmail(ctx context.Context, email string) (*model.User, error) {
 	var user model.User
 	err := r.db.WithContext(ctx).Where("email = ?", email).First(&user).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrUserNotFound, nil)
 	}
 	return &user, nil
 }
 
-func (r *UserRepository) Update(ctx context.Context, user *model.User) error {
-	return r.db.WithContext(ctx).Save(user).Error
+func (r *userRepository) Update(ctx context.Context, user *model.User) error {
+	err := r.db.WithContext(ctx).Save(user).Error
+	return translatePersistenceError(err, nil, service.ErrEmailExists)
 }
 
-func (r *UserRepository) Delete(ctx context.Context, id int64) error {
+func (r *userRepository) Delete(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Delete(&model.User{}, id).Error
 }
 
-func (r *UserRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.User, *pagination.PaginationResult, error) {
+func (r *userRepository) List(ctx context.Context, params pagination.PaginationParams) ([]model.User, *pagination.PaginationResult, error) {
 	return r.ListWithFilters(ctx, params, "", "", "")
 }
 
 // ListWithFilters lists users with optional filtering by status, role, and search query
-func (r *UserRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, status, role, search string) ([]model.User, *pagination.PaginationResult, error) {
+func (r *userRepository) ListWithFilters(ctx context.Context, params pagination.PaginationParams, status, role, search string) ([]model.User, *pagination.PaginationResult, error) {
 	var users []model.User
 	var total int64
 
@@ -120,13 +125,13 @@ func (r *UserRepository) ListWithFilters(ctx context.Context, params pagination.
 	}, nil
 }
 
-func (r *UserRepository) UpdateBalance(ctx context.Context, id int64, amount float64) error {
+func (r *userRepository) UpdateBalance(ctx context.Context, id int64, amount float64) error {
 	return r.db.WithContext(ctx).Model(&model.User{}).Where("id = ?", id).
 		Update("balance", gorm.Expr("balance + ?", amount)).Error
 }
 
 // DeductBalance 扣减用户余额，仅当余额充足时执行
-func (r *UserRepository) DeductBalance(ctx context.Context, id int64, amount float64) error {
+func (r *userRepository) DeductBalance(ctx context.Context, id int64, amount float64) error {
 	result := r.db.WithContext(ctx).Model(&model.User{}).
 		Where("id = ? AND balance >= ?", id, amount).
 		Update("balance", gorm.Expr("balance - ?", amount))
@@ -134,17 +139,17 @@ func (r *UserRepository) DeductBalance(ctx context.Context, id int64, amount flo
 		return result.Error
 	}
 	if result.RowsAffected == 0 {
-		return gorm.ErrRecordNotFound // 余额不足或用户不存在
+		return service.ErrInsufficientBalance
 	}
 	return nil
 }
 
-func (r *UserRepository) UpdateConcurrency(ctx context.Context, id int64, amount int) error {
+func (r *userRepository) UpdateConcurrency(ctx context.Context, id int64, amount int) error {
 	return r.db.WithContext(ctx).Model(&model.User{}).Where("id = ?", id).
 		Update("concurrency", gorm.Expr("concurrency + ?", amount)).Error
 }
 
-func (r *UserRepository) ExistsByEmail(ctx context.Context, email string) (bool, error) {
+func (r *userRepository) ExistsByEmail(ctx context.Context, email string) (bool, error) {
 	var count int64
 	err := r.db.WithContext(ctx).Model(&model.User{}).Where("email = ?", email).Count(&count).Error
 	return count > 0, err
@@ -152,7 +157,7 @@ func (r *UserRepository) ExistsByEmail(ctx context.Context, email string) (bool,
 
 // RemoveGroupFromAllowedGroups 从所有用户的 allowed_groups 数组中移除指定的分组ID
 // 使用 PostgreSQL 的 array_remove 函数
-func (r *UserRepository) RemoveGroupFromAllowedGroups(ctx context.Context, groupID int64) (int64, error) {
+func (r *userRepository) RemoveGroupFromAllowedGroups(ctx context.Context, groupID int64) (int64, error) {
 	result := r.db.WithContext(ctx).Model(&model.User{}).
 		Where("? = ANY(allowed_groups)", groupID).
 		Update("allowed_groups", gorm.Expr("array_remove(allowed_groups, ?)", groupID))
@@ -160,14 +165,14 @@ func (r *UserRepository) RemoveGroupFromAllowedGroups(ctx context.Context, group
 }
 
 // GetFirstAdmin 获取第一个管理员用户（用于 Admin API Key 认证）
-func (r *UserRepository) GetFirstAdmin(ctx context.Context) (*model.User, error) {
+func (r *userRepository) GetFirstAdmin(ctx context.Context) (*model.User, error) {
 	var user model.User
 	err := r.db.WithContext(ctx).
 		Where("role = ? AND status = ?", model.RoleAdmin, model.StatusActive).
 		Order("id ASC").
 		First(&user).Error
 	if err != nil {
-		return nil, err
+		return nil, translatePersistenceError(err, service.ErrUserNotFound, nil)
 	}
 	return &user, nil
 }

backend/internal/repository/user_repo_integration_test.go

@@ -0,0 +1,449 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/model"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/lib/pq"
+	"github.com/stretchr/testify/suite"
+	"gorm.io/gorm"
+)
+
+type UserRepoSuite struct {
+	suite.Suite
+	ctx  context.Context
+	db   *gorm.DB
+	repo *userRepository
+}
+
+func (s *UserRepoSuite) SetupTest() {
+	s.ctx = context.Background()
+	s.db = testTx(s.T())
+	s.repo = NewUserRepository(s.db).(*userRepository)
+}
+
+func TestUserRepoSuite(t *testing.T) {
+	suite.Run(t, new(UserRepoSuite))
+}
+
+// --- Create / GetByID / GetByEmail / Update / Delete ---
+
+func (s *UserRepoSuite) TestCreate() {
+	user := &model.User{
+		Email:    "create@test.com",
+		Username: "testuser",
+		Role:     model.RoleUser,
+		Status:   model.StatusActive,
+	}
+
+	err := s.repo.Create(s.ctx, user)
+	s.Require().NoError(err, "Create")
+	s.Require().NotZero(user.ID, "expected ID to be set")
+
+	got, err := s.repo.GetByID(s.ctx, user.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal("create@test.com", got.Email)
+}
+
+func (s *UserRepoSuite) TestGetByID_NotFound() {
+	_, err := s.repo.GetByID(s.ctx, 999999)
+	s.Require().Error(err, "expected error for non-existent ID")
+}
+
+func (s *UserRepoSuite) TestGetByEmail() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "byemail@test.com"})
+
+	got, err := s.repo.GetByEmail(s.ctx, user.Email)
+	s.Require().NoError(err, "GetByEmail")
+	s.Require().Equal(user.ID, got.ID)
+}
+
+func (s *UserRepoSuite) TestGetByEmail_NotFound() {
+	_, err := s.repo.GetByEmail(s.ctx, "nonexistent@test.com")
+	s.Require().Error(err, "expected error for non-existent email")
+}
+
+func (s *UserRepoSuite) TestUpdate() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "update@test.com", Username: "original"})
+
+	user.Username = "updated"
+	err := s.repo.Update(s.ctx, user)
+	s.Require().NoError(err, "Update")
+
+	got, err := s.repo.GetByID(s.ctx, user.ID)
+	s.Require().NoError(err, "GetByID after update")
+	s.Require().Equal("updated", got.Username)
+}
+
+func (s *UserRepoSuite) TestDelete() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "delete@test.com"})
+
+	err := s.repo.Delete(s.ctx, user.ID)
+	s.Require().NoError(err, "Delete")
+
+	_, err = s.repo.GetByID(s.ctx, user.ID)
+	s.Require().Error(err, "expected error after delete")
+}
+
+// --- List / ListWithFilters ---
+
+func (s *UserRepoSuite) TestList() {
+	mustCreateUser(s.T(), s.db, &model.User{Email: "list1@test.com"})
+	mustCreateUser(s.T(), s.db, &model.User{Email: "list2@test.com"})
+
+	users, page, err := s.repo.List(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10})
+	s.Require().NoError(err, "List")
+	s.Require().Len(users, 2)
+	s.Require().Equal(int64(2), page.Total)
+}
+
+func (s *UserRepoSuite) TestListWithFilters_Status() {
+	mustCreateUser(s.T(), s.db, &model.User{Email: "active@test.com", Status: model.StatusActive})
+	mustCreateUser(s.T(), s.db, &model.User{Email: "disabled@test.com", Status: model.StatusDisabled})
+
+	users, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, model.StatusActive, "", "")
+	s.Require().NoError(err)
+	s.Require().Len(users, 1)
+	s.Require().Equal(model.StatusActive, users[0].Status)
+}
+
+func (s *UserRepoSuite) TestListWithFilters_Role() {
+	mustCreateUser(s.T(), s.db, &model.User{Email: "user@test.com", Role: model.RoleUser})
+	mustCreateUser(s.T(), s.db, &model.User{Email: "admin@test.com", Role: model.RoleAdmin})
+
+	users, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", model.RoleAdmin, "")
+	s.Require().NoError(err)
+	s.Require().Len(users, 1)
+	s.Require().Equal(model.RoleAdmin, users[0].Role)
+}
+
+func (s *UserRepoSuite) TestListWithFilters_Search() {
+	mustCreateUser(s.T(), s.db, &model.User{Email: "alice@test.com", Username: "Alice"})
+	mustCreateUser(s.T(), s.db, &model.User{Email: "bob@test.com", Username: "Bob"})
+
+	users, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", "alice")
+	s.Require().NoError(err)
+	s.Require().Len(users, 1)
+	s.Require().Contains(users[0].Email, "alice")
+}
+
+func (s *UserRepoSuite) TestListWithFilters_SearchByUsername() {
+	mustCreateUser(s.T(), s.db, &model.User{Email: "u1@test.com", Username: "JohnDoe"})
+	mustCreateUser(s.T(), s.db, &model.User{Email: "u2@test.com", Username: "JaneSmith"})
+
+	users, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", "john")
+	s.Require().NoError(err)
+	s.Require().Len(users, 1)
+	s.Require().Equal("JohnDoe", users[0].Username)
+}
+
+func (s *UserRepoSuite) TestListWithFilters_SearchByWechat() {
+	mustCreateUser(s.T(), s.db, &model.User{Email: "w1@test.com", Wechat: "wx_hello"})
+	mustCreateUser(s.T(), s.db, &model.User{Email: "w2@test.com", Wechat: "wx_world"})
+
+	users, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", "wx_hello")
+	s.Require().NoError(err)
+	s.Require().Len(users, 1)
+	s.Require().Equal("wx_hello", users[0].Wechat)
+}
+
+func (s *UserRepoSuite) TestListWithFilters_LoadsActiveSubscriptions() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "sub@test.com", Status: model.StatusActive})
+	group := mustCreateGroup(s.T(), s.db, &model.Group{Name: "g-sub"})
+
+	_ = mustCreateSubscription(s.T(), s.db, &model.UserSubscription{
+		UserID:    user.ID,
+		GroupID:   group.ID,
+		Status:    model.SubscriptionStatusActive,
+		ExpiresAt: time.Now().Add(1 * time.Hour),
+	})
+	_ = mustCreateSubscription(s.T(), s.db, &model.UserSubscription{
+		UserID:    user.ID,
+		GroupID:   group.ID,
+		Status:    model.SubscriptionStatusExpired,
+		ExpiresAt: time.Now().Add(-1 * time.Hour),
+	})
+
+	users, _, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, "", "", "sub@")
+	s.Require().NoError(err, "ListWithFilters")
+	s.Require().Len(users, 1, "expected 1 user")
+	s.Require().Len(users[0].Subscriptions, 1, "expected 1 active subscription")
+	s.Require().NotNil(users[0].Subscriptions[0].Group, "expected subscription group preload")
+	s.Require().Equal(group.ID, users[0].Subscriptions[0].Group.ID, "group ID mismatch")
+}
+
+func (s *UserRepoSuite) TestListWithFilters_CombinedFilters() {
+	mustCreateUser(s.T(), s.db, &model.User{
+		Email:    "a@example.com",
+		Username: "Alice",
+		Wechat:   "wx_a",
+		Role:     model.RoleUser,
+		Status:   model.StatusActive,
+		Balance:  10,
+	})
+	target := mustCreateUser(s.T(), s.db, &model.User{
+		Email:    "b@example.com",
+		Username: "Bob",
+		Wechat:   "wx_b",
+		Role:     model.RoleAdmin,
+		Status:   model.StatusActive,
+		Balance:  1,
+	})
+	mustCreateUser(s.T(), s.db, &model.User{
+		Email:  "c@example.com",
+		Role:   model.RoleAdmin,
+		Status: model.StatusDisabled,
+	})
+
+	users, page, err := s.repo.ListWithFilters(s.ctx, pagination.PaginationParams{Page: 1, PageSize: 10}, model.StatusActive, model.RoleAdmin, "b@")
+	s.Require().NoError(err, "ListWithFilters")
+	s.Require().Equal(int64(1), page.Total, "ListWithFilters total mismatch")
+	s.Require().Len(users, 1, "ListWithFilters len mismatch")
+	s.Require().Equal(target.ID, users[0].ID, "ListWithFilters result mismatch")
+}
+
+// --- Balance operations ---
+
+func (s *UserRepoSuite) TestUpdateBalance() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "bal@test.com", Balance: 10})
+
+	err := s.repo.UpdateBalance(s.ctx, user.ID, 2.5)
+	s.Require().NoError(err, "UpdateBalance")
+
+	got, err := s.repo.GetByID(s.ctx, user.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(12.5, got.Balance)
+}
+
+func (s *UserRepoSuite) TestUpdateBalance_Negative() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "balneg@test.com", Balance: 10})
+
+	err := s.repo.UpdateBalance(s.ctx, user.ID, -3)
+	s.Require().NoError(err, "UpdateBalance with negative")
+
+	got, err := s.repo.GetByID(s.ctx, user.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(7.0, got.Balance)
+}
+
+func (s *UserRepoSuite) TestDeductBalance() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "deduct@test.com", Balance: 10})
+
+	err := s.repo.DeductBalance(s.ctx, user.ID, 5)
+	s.Require().NoError(err, "DeductBalance")
+
+	got, err := s.repo.GetByID(s.ctx, user.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(5.0, got.Balance)
+}
+
+func (s *UserRepoSuite) TestDeductBalance_InsufficientFunds() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "insuf@test.com", Balance: 5})
+
+	err := s.repo.DeductBalance(s.ctx, user.ID, 999)
+	s.Require().Error(err, "expected error for insufficient balance")
+	s.Require().ErrorIs(err, service.ErrInsufficientBalance)
+}
+
+func (s *UserRepoSuite) TestDeductBalance_ExactAmount() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "exact@test.com", Balance: 10})
+
+	err := s.repo.DeductBalance(s.ctx, user.ID, 10)
+	s.Require().NoError(err, "DeductBalance exact amount")
+
+	got, err := s.repo.GetByID(s.ctx, user.ID)
+	s.Require().NoError(err)
+	s.Require().Zero(got.Balance)
+}
+
+// --- Concurrency ---
+
+func (s *UserRepoSuite) TestUpdateConcurrency() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "conc@test.com", Concurrency: 5})
+
+	err := s.repo.UpdateConcurrency(s.ctx, user.ID, 3)
+	s.Require().NoError(err, "UpdateConcurrency")
+
+	got, err := s.repo.GetByID(s.ctx, user.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(8, got.Concurrency)
+}
+
+func (s *UserRepoSuite) TestUpdateConcurrency_Negative() {
+	user := mustCreateUser(s.T(), s.db, &model.User{Email: "concneg@test.com", Concurrency: 5})
+
+	err := s.repo.UpdateConcurrency(s.ctx, user.ID, -2)
+	s.Require().NoError(err, "UpdateConcurrency negative")
+
+	got, err := s.repo.GetByID(s.ctx, user.ID)
+	s.Require().NoError(err)
+	s.Require().Equal(3, got.Concurrency)
+}
+
+// --- ExistsByEmail ---
+
+func (s *UserRepoSuite) TestExistsByEmail() {
+	mustCreateUser(s.T(), s.db, &model.User{Email: "exists@test.com"})
+
+	exists, err := s.repo.ExistsByEmail(s.ctx, "exists@test.com")
+	s.Require().NoError(err, "ExistsByEmail")
+	s.Require().True(exists)
+
+	notExists, err := s.repo.ExistsByEmail(s.ctx, "notexists@test.com")
+	s.Require().NoError(err)
+	s.Require().False(notExists)
+}
+
+// --- RemoveGroupFromAllowedGroups ---
+
+func (s *UserRepoSuite) TestRemoveGroupFromAllowedGroups() {
+	groupID := int64(42)
+	userA := mustCreateUser(s.T(), s.db, &model.User{
+		Email:         "a1@example.com",
+		AllowedGroups: pq.Int64Array{groupID, 7},
+	})
+	mustCreateUser(s.T(), s.db, &model.User{
+		Email:         "a2@example.com",
+		AllowedGroups: pq.Int64Array{7},
+	})
+
+	affected, err := s.repo.RemoveGroupFromAllowedGroups(s.ctx, groupID)
+	s.Require().NoError(err, "RemoveGroupFromAllowedGroups")
+	s.Require().Equal(int64(1), affected, "expected 1 affected row")
+
+	got, err := s.repo.GetByID(s.ctx, userA.ID)
+	s.Require().NoError(err, "GetByID")
+	for _, id := range got.AllowedGroups {
+		s.Require().NotEqual(groupID, id, "expected groupID to be removed from allowed_groups")
+	}
+}
+
+func (s *UserRepoSuite) TestRemoveGroupFromAllowedGroups_NoMatch() {
+	mustCreateUser(s.T(), s.db, &model.User{
+		Email:         "nomatch@test.com",
+		AllowedGroups: pq.Int64Array{1, 2, 3},
+	})
+
+	affected, err := s.repo.RemoveGroupFromAllowedGroups(s.ctx, 999)
+	s.Require().NoError(err)
+	s.Require().Zero(affected, "expected no affected rows")
+}
+
+// --- GetFirstAdmin ---
+
+func (s *UserRepoSuite) TestGetFirstAdmin() {
+	admin1 := mustCreateUser(s.T(), s.db, &model.User{
+		Email:  "admin1@example.com",
+		Role:   model.RoleAdmin,
+		Status: model.StatusActive,
+	})
+	mustCreateUser(s.T(), s.db, &model.User{
+		Email:  "admin2@example.com",
+		Role:   model.RoleAdmin,
+		Status: model.StatusActive,
+	})
+
+	got, err := s.repo.GetFirstAdmin(s.ctx)
+	s.Require().NoError(err, "GetFirstAdmin")
+	s.Require().Equal(admin1.ID, got.ID, "GetFirstAdmin mismatch")
+}
+
+func (s *UserRepoSuite) TestGetFirstAdmin_NoAdmin() {
+	mustCreateUser(s.T(), s.db, &model.User{
+		Email:  "user@example.com",
+		Role:   model.RoleUser,
+		Status: model.StatusActive,
+	})
+
+	_, err := s.repo.GetFirstAdmin(s.ctx)
+	s.Require().Error(err, "expected error when no admin exists")
+}
+
+func (s *UserRepoSuite) TestGetFirstAdmin_DisabledAdminIgnored() {
+	mustCreateUser(s.T(), s.db, &model.User{
+		Email:  "disabled@example.com",
+		Role:   model.RoleAdmin,
+		Status: model.StatusDisabled,
+	})
+	activeAdmin := mustCreateUser(s.T(), s.db, &model.User{
+		Email:  "active@example.com",
+		Role:   model.RoleAdmin,
+		Status: model.StatusActive,
+	})
+
+	got, err := s.repo.GetFirstAdmin(s.ctx)
+	s.Require().NoError(err, "GetFirstAdmin")
+	s.Require().Equal(activeAdmin.ID, got.ID, "should return only active admin")
+}
+
+// --- Combined original test ---
+
+func (s *UserRepoSuite) TestCRUD_And_Filters_And_AtomicUpdates() {
+	user1 := mustCreateUser(s.T(), s.db, &model.User{
+		Email:    "a@example.com",
+		Username: "Alice",
+		Wechat:   "wx_a",
+		Role:     model.RoleUser,
+		Status:   model.StatusActive,
+		Balance:  10,
+	})
+	user2 := mustCreateUser(s.T(), s.db, &model.User{
+		Email:    "b@example.com",
+		Username: "Bob",
+		Wechat:   "wx_b",
+		Role:     model.RoleAdmin,
+		Status:   model.StatusActive,
+		Balance:  1,
+	})
+	_ = mustCreateUser(s.T(), s.db, &model.User{
+		Email:  "c@example.com",
+		Role:   model.RoleAdmin,
+		Status: model.StatusDisabled,
+	})
+
+	got, err := s.repo.GetByID(s.ctx, user1.ID)
+	s.Require().NoError(err, "GetByID")
+	s.Require().Equal(user1.Email, got.Email, "GetByID email mismatch")
+
+	gotByEmail, err := s.repo.GetByEmail(s.ctx, user2.Email)
+	s.Require().NoError(err, "GetByEmail")
+	s.Require().Equal(user2.ID, gotByEmail.ID, "GetByEmail ID mismatch")
+
+	got.Username = "Alice2"
+	s.Require().NoError(s.repo.Update(s.ctx, got), "Update")
+	got2, err := s.repo.GetByID(s.ctx, user1.ID)
+	s.Require().NoError(err, "GetByID after update")
+	s.Require().Equal("Alice2", got2.Username, "Update did not persist")
+
+	s.Require().NoError(s.repo.UpdateBalance(s.ctx, user1.ID, 2.5), "UpdateBalance")
+	got3, err := s.repo.GetByID(s.ctx, user1.ID)
+	s.Require().NoError(err, "GetByID after UpdateBalance")
+	s.Require().Equal(12.5, got3.Balance, "UpdateBalance mismatch")
+
+	s.Require().NoError(s.repo.DeductBalance(s.ctx, user1.ID, 5), "DeductBalance")
+	got4, err := s.repo.GetByID(s.ctx, user1.ID)
+	s.Require().NoError(err, "GetByID after DeductBalance")
+	s.Require().Equal(7.5, got4.Balance, "DeductBalance mismatch")
+
+	err = s.repo.DeductBalance(s.ctx, user1.ID, 999)
+	s.Require().Error(err, "DeductBalance expected error for insufficient balance")
+	s.Require().ErrorIs(err, service.ErrInsufficientBalance, "DeductBalance unexpected error")
+
+	s.Require().NoError(s.repo.UpdateConcurrency(s.ctx, user1.ID, 3), "UpdateConcurrency")
+	got5, err := s.repo.GetByID(s.ctx, user1.ID)
+	s.Require().NoError(err, "GetByID after UpdateConcurrency")
+	s.Require().Equal(user1.Concurrency+3, got5.Concurrency, "UpdateConcurrency mismatch")
+
+	params := pagination.PaginationParams{Page: 1, PageSize: 10}
+	users, page, err := s.repo.ListWithFilters(s.ctx, params, model.StatusActive, model.RoleAdmin, "b@")
+	s.Require().NoError(err, "ListWithFilters")
+	s.Require().Equal(int64(1), page.Total, "ListWithFilters total mismatch")
+	s.Require().Len(users, 1, "ListWithFilters len mismatch")
+	s.Require().Equal(user2.ID, users[0].ID, "ListWithFilters result mismatch")
+}