fix: 去掉accept-encoding透传

- Add -tags=embed flag to GoReleaser builds
- Add -tags embed flag to Dockerfile builds
- Fix Dockerfile COPY order to prevent frontend dist being overwritten
- Update README build instructions with embed tag explanation

.github/workflows/backend-ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: backend/go.mod
+          check-latest: true
+          cache: true
+      - name: Run tests
+        working-directory: backend
+        run: go test ./...
+
+  golangci-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: backend/go.mod
+          check-latest: true
+          cache: true
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v9
+        with:
+          version: v2.7
+          args: --timeout=5m
+          working-directory: backend

.gitignore

@@ -81,7 +81,12 @@ build/
 release/
 
 # 后端嵌入的前端构建产物
+# Keep a placeholder file so `//go:embed all:dist` always has a match in CI/lint,
+# while still ignoring generated frontend build outputs.
 backend/internal/web/dist/
+!backend/internal/web/dist/
+backend/internal/web/dist/*
+!backend/internal/web/dist/.keep
 
 # 后端运行时缓存数据
 backend/data/
@@ -92,4 +97,4 @@ backend/data/
 tests
 CLAUDE.md
 .claude
-scripts
+scripts

.goreleaser.yaml

@@ -11,6 +11,8 @@ builds:
     dir: backend
     main: ./cmd/server
     binary: sub2api
+    flags:
+      - -tags=embed
     env:
       - CGO_ENABLED=0
     goos:

Dockerfile

@@ -40,14 +40,15 @@ WORKDIR /app/backend
 COPY backend/go.mod backend/go.sum ./
 RUN go mod download
 
-# Copy frontend dist from previous stage
-COPY --from=frontend-builder /app/frontend/../backend/internal/web/dist ./internal/web/dist
-
-# Copy backend source
+# Copy backend source first
 COPY backend/ ./
 
-# Build the binary (BuildType=release for CI builds)
+# Copy frontend dist from previous stage (must be after backend copy to avoid being overwritten)
+COPY --from=frontend-builder /app/backend/internal/web/dist ./internal/web/dist
+
+# Build the binary (BuildType=release for CI builds, embed frontend)
 RUN CGO_ENABLED=0 GOOS=linux go build \
+    -tags embed \
     -ldflags="-s -w -X main.Commit=${COMMIT} -X main.Date=${DATE:-$(date -u +%Y-%m-%dT%H:%M:%SZ)} -X main.BuildType=release" \
     -o /app/sub2api \
     ./cmd/server

README.md

@@ -216,26 +216,25 @@ Build and run from source code for development or customization.
 git clone https://github.com/Wei-Shaw/sub2api.git
 cd sub2api
 
-# 2. Build backend
-cd backend
-go build -o sub2api ./cmd/server
-
-# 3. Build frontend
-cd ../frontend
+# 2. Build frontend
+cd frontend
 npm install
 npm run build
+# Output will be in ../backend/internal/web/dist/
 
-# 4. Copy frontend build to backend (for embedding)
-cp -r dist ../backend/internal/web/
-
-# 5. Create configuration file
+# 3. Build backend with embedded frontend
 cd ../backend
+go build -tags embed -o sub2api ./cmd/server
+
+# 4. Create configuration file
 cp ../deploy/config.example.yaml ./config.yaml
 
-# 6. Edit configuration
+# 5. Edit configuration
 nano config.yaml
 ```
 
+> **Note:** The `-tags embed` flag embeds the frontend into the binary. Without this flag, the binary will not serve the frontend UI.
+
 **Key configuration in `config.yaml`:**
 
 ```yaml
@@ -266,7 +265,7 @@ default:
 ```
 
 ```bash
-# 7. Run the application
+# 6. Run the application
 ./sub2api
 ```
 

README_CN.md

@@ -216,26 +216,25 @@ docker-compose logs -f
 git clone https://github.com/Wei-Shaw/sub2api.git
 cd sub2api
 
-# 2. 编译后端
-cd backend
-go build -o sub2api ./cmd/server
-
-# 3. 编译前端
-cd ../frontend
+# 2. 编译前端
+cd frontend
 npm install
 npm run build
+# 构建产物输出到 ../backend/internal/web/dist/
 
-# 4. 复制前端构建产物到后端（用于嵌入）
-cp -r dist ../backend/internal/web/
-
-# 5. 创建配置文件
+# 3. 编译后端（嵌入前端）
 cd ../backend
+go build -tags embed -o sub2api ./cmd/server
+
+# 4. 创建配置文件
 cp ../deploy/config.example.yaml ./config.yaml
 
-# 6. 编辑配置
+# 5. 编辑配置
 nano config.yaml
 ```
 
+> **注意：** `-tags embed` 参数会将前端嵌入到二进制文件中。不使用此参数编译的程序将不包含前端界面。
+
 **`config.yaml` 关键配置：**
 
 ```yaml
@@ -266,7 +265,7 @@ default:
 ```
 
 ```bash
-# 7. 运行应用
+# 6. 运行应用
 ./sub2api
 ```
 

backend/.golangci.yml

@@ -0,0 +1,587 @@
+version: "2"
+
+linters:
+  default: none
+  enable:
+    - depguard
+    - errcheck
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+
+  settings:
+    depguard:
+      rules:
+        # Enforce: service must not depend on repository.
+        service-no-repository:
+          list-mode: original
+          files:
+            - internal/service/**
+          deny:
+            - pkg: sub2api/internal/repository
+              desc: "service must not import repository"
+    errcheck:
+      # Report about not checking of errors in type assertions: `a := b.(MyStruct)`.
+      # Such cases aren't reported by default.
+      # Default: false
+      check-type-assertions: true
+      # report about assignment of errors to blank identifier: `num, _ := strconv.Atoi(numStr)`.
+      # Such cases aren't reported by default.
+      # Default: false
+      check-blank: false
+      # To disable the errcheck built-in exclude list.
+      # See `-excludeonly` option in https://github.com/kisielk/errcheck#excluding-functions for details.
+      # Default: false
+      disable-default-exclusions: true
+      # List of functions to exclude from checking, where each entry is a single function to exclude.
+      # See https://github.com/kisielk/errcheck#excluding-functions for details.
+      exclude-functions:
+        - io/ioutil.ReadFile
+        - io.Copy(*bytes.Buffer)
+        - io.Copy(os.Stdout)
+        - fmt.Println
+        - fmt.Print
+        - fmt.Printf
+        - fmt.Fprint
+        - fmt.Fprintf
+        - fmt.Fprintln
+      # Display function signature instead of selector.
+      # Default: false
+      verbose: true
+    ineffassign:
+      # Check escaping variables of type error, may cause false positives.
+      # Default: false
+      check-escaping-errors: true
+    staticcheck:
+      # https://staticcheck.dev/docs/configuration/options/#dot_import_whitelist
+      # Default: ["github.com/mmcloughlin/avo/build", "github.com/mmcloughlin/avo/operand", "github.com/mmcloughlin/avo/reg"]
+      dot-import-whitelist:
+        - fmt
+      # https://staticcheck.dev/docs/configuration/options/#initialisms
+      # Default: ["ACL", "API", "ASCII", "CPU", "CSS", "DNS", "EOF", "GUID", "HTML", "HTTP", "HTTPS", "ID", "IP", "JSON", "QPS", "RAM", "RPC", "SLA", "SMTP", "SQL", "SSH", "TCP", "TLS", "TTL", "UDP", "UI", "GID", "UID", "UUID", "URI", "URL", "UTF8", "VM", "XML", "XMPP", "XSRF", "XSS", "SIP", "RTP", "AMQP", "DB", "TS"]
+      initialisms: [ "ACL", "API", "ASCII", "CPU", "CSS", "DNS", "EOF", "GUID", "HTML", "HTTP", "HTTPS", "ID", "IP", "JSON", "QPS", "RAM", "RPC", "SLA", "SMTP", "SQL", "SSH", "TCP", "TLS", "TTL", "UDP", "UI", "GID", "UID", "UUID", "URI", "URL", "UTF8", "VM", "XML", "XMPP", "XSRF", "XSS", "SIP", "RTP", "AMQP", "DB", "TS" ]
+      # https://staticcheck.dev/docs/configuration/options/#http_status_code_whitelist
+      # Default: ["200", "400", "404", "500"]
+      http-status-code-whitelist: [ "200", "400", "404", "500" ]
+      # SAxxxx checks in https://staticcheck.dev/docs/configuration/options/#checks
+      # Example (to disable some checks): [ "all", "-SA1000", "-SA1001"]
+      # Run `GL_DEBUG=staticcheck golangci-lint run --enable=staticcheck` to see all available checks and enabled by config checks.
+      # Default: ["all", "-ST1000", "-ST1003", "-ST1016", "-ST1020", "-ST1021", "-ST1022"]
+      checks:
+        # Invalid regular expression.
+        # https://staticcheck.dev/docs/checks/#SA1000
+        - SA1000
+        # Invalid template.
+        # https://staticcheck.dev/docs/checks/#SA1001
+        - SA1001
+        # Invalid format in 'time.Parse'.
+        # https://staticcheck.dev/docs/checks/#SA1002
+        - SA1002
+        # Unsupported argument to functions in 'encoding/binary'.
+        # https://staticcheck.dev/docs/checks/#SA1003
+        - SA1003
+        # Suspiciously small untyped constant in 'time.Sleep'.
+        # https://staticcheck.dev/docs/checks/#SA1004
+        - SA1004
+        # Invalid first argument to 'exec.Command'.
+        # https://staticcheck.dev/docs/checks/#SA1005
+        - SA1005
+        # 'Printf' with dynamic first argument and no further arguments.
+        # https://staticcheck.dev/docs/checks/#SA1006
+        - SA1006
+        # Invalid URL in 'net/url.Parse'.
+        # https://staticcheck.dev/docs/checks/#SA1007
+        - SA1007
+        # Non-canonical key in 'http.Header' map.
+        # https://staticcheck.dev/docs/checks/#SA1008
+        - SA1008
+        # '(*regexp.Regexp).FindAll' called with 'n == 0', which will always return zero results.
+        # https://staticcheck.dev/docs/checks/#SA1010
+        - SA1010
+        # Various methods in the "strings" package expect valid UTF-8, but invalid input is provided.
+        # https://staticcheck.dev/docs/checks/#SA1011
+        - SA1011
+        # A nil 'context.Context' is being passed to a function, consider using 'context.TODO' instead.
+        # https://staticcheck.dev/docs/checks/#SA1012
+        - SA1012
+        # 'io.Seeker.Seek' is being called with the whence constant as the first argument, but it should be the second.
+        # https://staticcheck.dev/docs/checks/#SA1013
+        - SA1013
+        # Non-pointer value passed to 'Unmarshal' or 'Decode'.
+        # https://staticcheck.dev/docs/checks/#SA1014
+        - SA1014
+        # Using 'time.Tick' in a way that will leak. Consider using 'time.NewTicker', and only use 'time.Tick' in tests, commands and endless functions.
+        # https://staticcheck.dev/docs/checks/#SA1015
+        - SA1015
+        # Trapping a signal that cannot be trapped.
+        # https://staticcheck.dev/docs/checks/#SA1016
+        - SA1016
+        # Channels used with 'os/signal.Notify' should be buffered.
+        # https://staticcheck.dev/docs/checks/#SA1017
+        - SA1017
+        # 'strings.Replace' called with 'n == 0', which does nothing.
+        # https://staticcheck.dev/docs/checks/#SA1018
+        - SA1018
+        # Using a deprecated function, variable, constant or field.
+        # https://staticcheck.dev/docs/checks/#SA1019
+        - SA1019
+        # Using an invalid host:port pair with a 'net.Listen'-related function.
+        # https://staticcheck.dev/docs/checks/#SA1020
+        - SA1020
+        # Using 'bytes.Equal' to compare two 'net.IP'.
+        # https://staticcheck.dev/docs/checks/#SA1021
+        - SA1021
+        # Modifying the buffer in an 'io.Writer' implementation.
+        # https://staticcheck.dev/docs/checks/#SA1023
+        - SA1023
+        # A string cutset contains duplicate characters.
+        # https://staticcheck.dev/docs/checks/#SA1024
+        - SA1024
+        # It is not possible to use '(*time.Timer).Reset''s return value correctly.
+        # https://staticcheck.dev/docs/checks/#SA1025
+        - SA1025
+        # Cannot marshal channels or functions.
+        # https://staticcheck.dev/docs/checks/#SA1026
+        - SA1026
+        # Atomic access to 64-bit variable must be 64-bit aligned.
+        # https://staticcheck.dev/docs/checks/#SA1027
+        - SA1027
+        # 'sort.Slice' can only be used on slices.
+        # https://staticcheck.dev/docs/checks/#SA1028
+        - SA1028
+        # Inappropriate key in call to 'context.WithValue'.
+        # https://staticcheck.dev/docs/checks/#SA1029
+        - SA1029
+        # Invalid argument in call to a 'strconv' function.
+        # https://staticcheck.dev/docs/checks/#SA1030
+        - SA1030
+        # Overlapping byte slices passed to an encoder.
+        # https://staticcheck.dev/docs/checks/#SA1031
+        - SA1031
+        # Wrong order of arguments to 'errors.Is'.
+        # https://staticcheck.dev/docs/checks/#SA1032
+        - SA1032
+        # 'sync.WaitGroup.Add' called inside the goroutine, leading to a race condition.
+        # https://staticcheck.dev/docs/checks/#SA2000
+        - SA2000
+        # Empty critical section, did you mean to defer the unlock?.
+        # https://staticcheck.dev/docs/checks/#SA2001
+        - SA2001
+        # Called 'testing.T.FailNow' or 'SkipNow' in a goroutine, which isn't allowed.
+        # https://staticcheck.dev/docs/checks/#SA2002
+        - SA2002
+        # Deferred 'Lock' right after locking, likely meant to defer 'Unlock' instead.
+        # https://staticcheck.dev/docs/checks/#SA2003
+        - SA2003
+        # 'TestMain' doesn't call 'os.Exit', hiding test failures.
+        # https://staticcheck.dev/docs/checks/#SA3000
+        - SA3000
+        # Assigning to 'b.N' in benchmarks distorts the results.
+        # https://staticcheck.dev/docs/checks/#SA3001
+        - SA3001
+        # Binary operator has identical expressions on both sides.
+        # https://staticcheck.dev/docs/checks/#SA4000
+        - SA4000
+        # '&*x' gets simplified to 'x', it does not copy 'x'.
+        # https://staticcheck.dev/docs/checks/#SA4001
+        - SA4001
+        # Comparing unsigned values against negative values is pointless.
+        # https://staticcheck.dev/docs/checks/#SA4003
+        - SA4003
+        # The loop exits unconditionally after one iteration.
+        # https://staticcheck.dev/docs/checks/#SA4004
+        - SA4004
+        # Field assignment that will never be observed. Did you mean to use a pointer receiver?.
+        # https://staticcheck.dev/docs/checks/#SA4005
+        - SA4005
+        # A value assigned to a variable is never read before being overwritten. Forgotten error check or dead code?.
+        # https://staticcheck.dev/docs/checks/#SA4006
+        - SA4006
+        # The variable in the loop condition never changes, are you incrementing the wrong variable?.
+        # https://staticcheck.dev/docs/checks/#SA4008
+        - SA4008
+        # A function argument is overwritten before its first use.
+        # https://staticcheck.dev/docs/checks/#SA4009
+        - SA4009
+        # The result of 'append' will never be observed anywhere.
+        # https://staticcheck.dev/docs/checks/#SA4010
+        - SA4010
+        # Break statement with no effect. Did you mean to break out of an outer loop?.
+        # https://staticcheck.dev/docs/checks/#SA4011
+        - SA4011
+        # Comparing a value against NaN even though no value is equal to NaN.
+        # https://staticcheck.dev/docs/checks/#SA4012
+        - SA4012
+        # Negating a boolean twice ('!!b') is the same as writing 'b'. This is either redundant, or a typo.
+        # https://staticcheck.dev/docs/checks/#SA4013
+        - SA4013
+        # An if/else if chain has repeated conditions and no side-effects; if the condition didn't match the first time, it won't match the second time, either.
+        # https://staticcheck.dev/docs/checks/#SA4014
+        - SA4014
+        # Calling functions like 'math.Ceil' on floats converted from integers doesn't do anything useful.
+        # https://staticcheck.dev/docs/checks/#SA4015
+        - SA4015
+        # Certain bitwise operations, such as 'x ^ 0', do not do anything useful.
+        # https://staticcheck.dev/docs/checks/#SA4016
+        - SA4016
+        # Discarding the return values of a function without side effects, making the call pointless.
+        # https://staticcheck.dev/docs/checks/#SA4017
+        - SA4017
+        # Self-assignment of variables.
+        # https://staticcheck.dev/docs/checks/#SA4018
+        - SA4018
+        # Multiple, identical build constraints in the same file.
+        # https://staticcheck.dev/docs/checks/#SA4019
+        - SA4019
+        # Unreachable case clause in a type switch.
+        # https://staticcheck.dev/docs/checks/#SA4020
+        - SA4020
+        # "x = append(y)" is equivalent to "x = y".
+        # https://staticcheck.dev/docs/checks/#SA4021
+        - SA4021
+        # Comparing the address of a variable against nil.
+        # https://staticcheck.dev/docs/checks/#SA4022
+        - SA4022
+        # Impossible comparison of interface value with untyped nil.
+        # https://staticcheck.dev/docs/checks/#SA4023
+        - SA4023
+        # Checking for impossible return value from a builtin function.
+        # https://staticcheck.dev/docs/checks/#SA4024
+        - SA4024
+        # Integer division of literals that results in zero.
+        # https://staticcheck.dev/docs/checks/#SA4025
+        - SA4025
+        # Go constants cannot express negative zero.
+        # https://staticcheck.dev/docs/checks/#SA4026
+        - SA4026
+        # '(*net/url.URL).Query' returns a copy, modifying it doesn't change the URL.
+        # https://staticcheck.dev/docs/checks/#SA4027
+        - SA4027
+        # 'x % 1' is always zero.
+        # https://staticcheck.dev/docs/checks/#SA4028
+        - SA4028
+        # Ineffective attempt at sorting slice.
+        # https://staticcheck.dev/docs/checks/#SA4029
+        - SA4029
+        # Ineffective attempt at generating random number.
+        # https://staticcheck.dev/docs/checks/#SA4030
+        - SA4030
+        # Checking never-nil value against nil.
+        # https://staticcheck.dev/docs/checks/#SA4031
+        - SA4031
+        # Comparing 'runtime.GOOS' or 'runtime.GOARCH' against impossible value.
+        # https://staticcheck.dev/docs/checks/#SA4032
+        - SA4032
+        # Assignment to nil map.
+        # https://staticcheck.dev/docs/checks/#SA5000
+        - SA5000
+        # Deferring 'Close' before checking for a possible error.
+        # https://staticcheck.dev/docs/checks/#SA5001
+        - SA5001
+        # The empty for loop ("for {}") spins and can block the scheduler.
+        # https://staticcheck.dev/docs/checks/#SA5002
+        - SA5002
+        # Defers in infinite loops will never execute.
+        # https://staticcheck.dev/docs/checks/#SA5003
+        - SA5003
+        # "for { select { ..." with an empty default branch spins.
+        # https://staticcheck.dev/docs/checks/#SA5004
+        - SA5004
+        # The finalizer references the finalized object, preventing garbage collection.
+        # https://staticcheck.dev/docs/checks/#SA5005
+        - SA5005
+        # Infinite recursive call.
+        # https://staticcheck.dev/docs/checks/#SA5007
+        - SA5007
+        # Invalid struct tag.
+        # https://staticcheck.dev/docs/checks/#SA5008
+        - SA5008
+        # Invalid Printf call.
+        # https://staticcheck.dev/docs/checks/#SA5009
+        - SA5009
+        # Impossible type assertion.
+        # https://staticcheck.dev/docs/checks/#SA5010
+        - SA5010
+        # Possible nil pointer dereference.
+        # https://staticcheck.dev/docs/checks/#SA5011
+        - SA5011
+        # Passing odd-sized slice to function expecting even size.
+        # https://staticcheck.dev/docs/checks/#SA5012
+        - SA5012
+        # Using 'regexp.Match' or related in a loop, should use 'regexp.Compile'.
+        # https://staticcheck.dev/docs/checks/#SA6000
+        - SA6000
+        # Missing an optimization opportunity when indexing maps by byte slices.
+        # https://staticcheck.dev/docs/checks/#SA6001
+        - SA6001
+        # Storing non-pointer values in 'sync.Pool' allocates memory.
+        # https://staticcheck.dev/docs/checks/#SA6002
+        - SA6002
+        # Converting a string to a slice of runes before ranging over it.
+        # https://staticcheck.dev/docs/checks/#SA6003
+        - SA6003
+        # Inefficient string comparison with 'strings.ToLower' or 'strings.ToUpper'.
+        # https://staticcheck.dev/docs/checks/#SA6005
+        - SA6005
+        # Using io.WriteString to write '[]byte'.
+        # https://staticcheck.dev/docs/checks/#SA6006
+        - SA6006
+        # Defers in range loops may not run when you expect them to.
+        # https://staticcheck.dev/docs/checks/#SA9001
+        - SA9001
+        # Using a non-octal 'os.FileMode' that looks like it was meant to be in octal.
+        # https://staticcheck.dev/docs/checks/#SA9002
+        - SA9002
+        # Empty body in an if or else branch.
+        # https://staticcheck.dev/docs/checks/#SA9003
+        - SA9003
+        # Only the first constant has an explicit type.
+        # https://staticcheck.dev/docs/checks/#SA9004
+        - SA9004
+        # Trying to marshal a struct with no public fields nor custom marshaling.
+        # https://staticcheck.dev/docs/checks/#SA9005
+        - SA9005
+        # Dubious bit shifting of a fixed size integer value.
+        # https://staticcheck.dev/docs/checks/#SA9006
+        - SA9006
+        # Deleting a directory that shouldn't be deleted.
+        # https://staticcheck.dev/docs/checks/#SA9007
+        - SA9007
+        # 'else' branch of a type assertion is probably not reading the right value.
+        # https://staticcheck.dev/docs/checks/#SA9008
+        - SA9008
+        # Ineffectual Go compiler directive.
+        # https://staticcheck.dev/docs/checks/#SA9009
+        - SA9009
+        # Incorrect or missing package comment.
+        # https://staticcheck.dev/docs/checks/#ST1000
+        - ST1000
+        # Dot imports are discouraged.
+        # https://staticcheck.dev/docs/checks/#ST1001
+        - ST1001
+        # Poorly chosen identifier.
+        # https://staticcheck.dev/docs/checks/#ST1003
+        - ST1003
+        # Incorrectly formatted error string.
+        # https://staticcheck.dev/docs/checks/#ST1005
+        - ST1005
+        # Poorly chosen receiver name.
+        # https://staticcheck.dev/docs/checks/#ST1006
+        - ST1006
+        # A function's error value should be its last return value.
+        # https://staticcheck.dev/docs/checks/#ST1008
+        - ST1008
+        # Poorly chosen name for variable of type 'time.Duration'.
+        # https://staticcheck.dev/docs/checks/#ST1011
+        - ST1011
+        # Poorly chosen name for error variable.
+        # https://staticcheck.dev/docs/checks/#ST1012
+        - ST1012
+        # Should use constants for HTTP error codes, not magic numbers.
+        # https://staticcheck.dev/docs/checks/#ST1013
+        - ST1013
+        # A switch's default case should be the first or last case.
+        # https://staticcheck.dev/docs/checks/#ST1015
+        - ST1015
+        # Use consistent method receiver names.
+        # https://staticcheck.dev/docs/checks/#ST1016
+        - ST1016
+        # Don't use Yoda conditions.
+        # https://staticcheck.dev/docs/checks/#ST1017
+        - ST1017
+        # Avoid zero-width and control characters in string literals.
+        # https://staticcheck.dev/docs/checks/#ST1018
+        - ST1018
+        # Importing the same package multiple times.
+        # https://staticcheck.dev/docs/checks/#ST1019
+        - ST1019
+        # The documentation of an exported function should start with the function's name.
+        # https://staticcheck.dev/docs/checks/#ST1020
+        - ST1020
+        # The documentation of an exported type should start with type's name.
+        # https://staticcheck.dev/docs/checks/#ST1021
+        - ST1021
+        # The documentation of an exported variable or constant should start with variable's name.
+        # https://staticcheck.dev/docs/checks/#ST1022
+        - ST1022
+        # Redundant type in variable declaration.
+        # https://staticcheck.dev/docs/checks/#ST1023
+        - ST1023
+        # Use plain channel send or receive instead of single-case select.
+        # https://staticcheck.dev/docs/checks/#S1000
+        - S1000
+        # Replace for loop with call to copy.
+        # https://staticcheck.dev/docs/checks/#S1001
+        - S1001
+        # Omit comparison with boolean constant.
+        # https://staticcheck.dev/docs/checks/#S1002
+        - S1002
+        # Replace call to 'strings.Index' with 'strings.Contains'.
+        # https://staticcheck.dev/docs/checks/#S1003
+        - S1003
+        # Replace call to 'bytes.Compare' with 'bytes.Equal'.
+        # https://staticcheck.dev/docs/checks/#S1004
+        - S1004
+        # Drop unnecessary use of the blank identifier.
+        # https://staticcheck.dev/docs/checks/#S1005
+        - S1005
+        # Use "for { ... }" for infinite loops.
+        # https://staticcheck.dev/docs/checks/#S1006
+        - S1006
+        # Simplify regular expression by using raw string literal.
+        # https://staticcheck.dev/docs/checks/#S1007
+        - S1007
+        # Simplify returning boolean expression.
+        # https://staticcheck.dev/docs/checks/#S1008
+        - S1008
+        # Omit redundant nil check on slices, maps, and channels.
+        # https://staticcheck.dev/docs/checks/#S1009
+        - S1009
+        # Omit default slice index.
+        # https://staticcheck.dev/docs/checks/#S1010
+        - S1010
+        # Use a single 'append' to concatenate two slices.
+        # https://staticcheck.dev/docs/checks/#S1011
+        - S1011
+        # Replace 'time.Now().Sub(x)' with 'time.Since(x)'.
+        # https://staticcheck.dev/docs/checks/#S1012
+        - S1012
+        # Use a type conversion instead of manually copying struct fields.
+        # https://staticcheck.dev/docs/checks/#S1016
+        - S1016
+        # Replace manual trimming with 'strings.TrimPrefix'.
+        # https://staticcheck.dev/docs/checks/#S1017
+        - S1017
+        # Use "copy" for sliding elements.
+        # https://staticcheck.dev/docs/checks/#S1018
+        - S1018
+        # Simplify "make" call by omitting redundant arguments.
+        # https://staticcheck.dev/docs/checks/#S1019
+        - S1019
+        # Omit redundant nil check in type assertion.
+        # https://staticcheck.dev/docs/checks/#S1020
+        - S1020
+        # Merge variable declaration and assignment.
+        # https://staticcheck.dev/docs/checks/#S1021
+        - S1021
+        # Omit redundant control flow.
+        # https://staticcheck.dev/docs/checks/#S1023
+        - S1023
+        # Replace 'x.Sub(time.Now())' with 'time.Until(x)'.
+        # https://staticcheck.dev/docs/checks/#S1024
+        - S1024
+        # Don't use 'fmt.Sprintf("%s", x)' unnecessarily.
+        # https://staticcheck.dev/docs/checks/#S1025
+        - S1025
+        # Simplify error construction with 'fmt.Errorf'.
+        # https://staticcheck.dev/docs/checks/#S1028
+        - S1028
+        # Range over the string directly.
+        # https://staticcheck.dev/docs/checks/#S1029
+        - S1029
+        # Use 'bytes.Buffer.String' or 'bytes.Buffer.Bytes'.
+        # https://staticcheck.dev/docs/checks/#S1030
+        - S1030
+        # Omit redundant nil check around loop.
+        # https://staticcheck.dev/docs/checks/#S1031
+        - S1031
+        # Use 'sort.Ints(x)', 'sort.Float64s(x)', and 'sort.Strings(x)'.
+        # https://staticcheck.dev/docs/checks/#S1032
+        - S1032
+        # Unnecessary guard around call to "delete".
+        # https://staticcheck.dev/docs/checks/#S1033
+        - S1033
+        # Use result of type assertion to simplify cases.
+        # https://staticcheck.dev/docs/checks/#S1034
+        - S1034
+        # Redundant call to 'net/http.CanonicalHeaderKey' in method call on 'net/http.Header'.
+        # https://staticcheck.dev/docs/checks/#S1035
+        - S1035
+        # Unnecessary guard around map access.
+        # https://staticcheck.dev/docs/checks/#S1036
+        - S1036
+        # Elaborate way of sleeping.
+        # https://staticcheck.dev/docs/checks/#S1037
+        - S1037
+        # Unnecessarily complex way of printing formatted string.
+        # https://staticcheck.dev/docs/checks/#S1038
+        - S1038
+        # Unnecessary use of 'fmt.Sprint'.
+        # https://staticcheck.dev/docs/checks/#S1039
+        - S1039
+        # Type assertion to current type.
+        # https://staticcheck.dev/docs/checks/#S1040
+        - S1040
+        # Apply De Morgan's law.
+        # https://staticcheck.dev/docs/checks/#QF1001
+        - QF1001
+        # Convert untagged switch to tagged switch.
+        # https://staticcheck.dev/docs/checks/#QF1002
+        - QF1002
+        # Convert if/else-if chain to tagged switch.
+        # https://staticcheck.dev/docs/checks/#QF1003
+        - QF1003
+        # Use 'strings.ReplaceAll' instead of 'strings.Replace' with 'n == -1'.
+        # https://staticcheck.dev/docs/checks/#QF1004
+        - QF1004
+        # Expand call to 'math.Pow'.
+        # https://staticcheck.dev/docs/checks/#QF1005
+        - QF1005
+        # Lift 'if'+'break' into loop condition.
+        # https://staticcheck.dev/docs/checks/#QF1006
+        - QF1006
+        # Merge conditional assignment into variable declaration.
+        # https://staticcheck.dev/docs/checks/#QF1007
+        - QF1007
+        # Omit embedded fields from selector expression.
+        # https://staticcheck.dev/docs/checks/#QF1008
+        - QF1008
+        # Use 'time.Time.Equal' instead of '==' operator.
+        # https://staticcheck.dev/docs/checks/#QF1009
+        - QF1009
+        # Convert slice of bytes to string when printing it.
+        # https://staticcheck.dev/docs/checks/#QF1010
+        - QF1010
+        # Omit redundant type from variable declaration.
+        # https://staticcheck.dev/docs/checks/#QF1011
+        - QF1011
+        # Use 'fmt.Fprintf(x, ...)' instead of 'x.Write(fmt.Sprintf(...))'.
+        # https://staticcheck.dev/docs/checks/#QF1012
+        - QF1012
+    unused:
+      # Mark all struct fields that have been written to as used.
+      # Default: true
+      field-writes-are-uses: false
+      # Treat IncDec statement (e.g. `i++` or `i--`) as both read and write operation instead of just write.
+      # Default: false
+      post-statements-are-reads: true
+      # Mark all exported fields as used.
+      # default: true
+      exported-fields-are-used: false
+      # Mark all function parameters as used.
+      # default: true
+      parameters-are-used: true
+      # Mark all local variables as used.
+      # default: true
+      local-variables-are-used: false
+      # Mark all identifiers inside generated files as used.
+      # Default: true
+      generated-is-used: false
+
+formatters:
+  enable:
+    - gofmt
+  settings:
+    gofmt:
+      # Simplify code: gofmt with `-s` option.
+      # Default: true
+      simplify: false
+      # Apply the rewrite rules to the source before reformatting.
+      # https://pkg.go.dev/cmd/gofmt
+      # Default: []
+      rewrite-rules:
+        - pattern: 'interface{}'
+          replacement: 'any'
+        - pattern: 'a[b:len(a)]'
+          replacement: 'a[b:]'

backend/Makefile

@@ -1,6 +1,16 @@
-.PHONY: wire
+.PHONY: wire build build-embed
 
 wire:
 	@echo "生成 Wire 代码..."
 	@cd cmd/server && go generate
-	@echo "Wire 代码生成完成"
+	@echo "Wire 代码生成完成"
+
+build:
+	@echo "构建后端（不嵌入前端）..."
+	@go build -o bin/server ./cmd/server
+	@echo "构建完成: bin/server"
+
+build-embed:
+	@echo "构建后端（嵌入前端）..."
+	@go build -tags embed -o bin/server ./cmd/server
+	@echo "构建完成: bin/server (with embedded frontend)"

backend/cmd/server/main.go

@@ -15,6 +15,7 @@ import (
 	"syscall"
 	"time"
 
+	"sub2api/internal/config"
 	"sub2api/internal/handler"
 	"sub2api/internal/middleware"
 	"sub2api/internal/setup"
@@ -94,8 +95,10 @@ func runSetupServer() {
 		r.Use(web.ServeEmbeddedFrontend())
 	}
 
-	addr := ":8080"
-	log.Printf("Setup wizard available at http://localhost%s", addr)
+	// Get server address from config.yaml or environment variables (SERVER_HOST, SERVER_PORT)
+	// This allows users to run setup on a different address if needed
+	addr := config.GetServerAddress()
+	log.Printf("Setup wizard available at http://%s", addr)
 	log.Println("Complete the setup wizard to configure Sub2API")
 
 	if err := r.Run(addr); err != nil {

backend/cmd/server/wire.go

@@ -40,6 +40,9 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 		// 服务器层 ProviderSet
 		server.ProviderSet,
 
+		// BuildInfo provider
+		provideServiceBuildInfo,
+
 		// 清理函数提供者
 		provideCleanup,
 
@@ -49,6 +52,13 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	return nil, nil
 }
 
+func provideServiceBuildInfo(buildInfo handler.BuildInfo) service.BuildInfo {
+	return service.BuildInfo{
+		Version:   buildInfo.Version,
+		BuildType: buildInfo.BuildType,
+	}
+}
+
 func provideCleanup(
 	db *gorm.DB,
 	rdb *redis.Client,
@@ -63,6 +73,10 @@ func provideCleanup(
 			name string
 			fn   func() error
 		}{
+			{"TokenRefreshService", func() error {
+				services.TokenRefresh.Stop()
+				return nil
+			}},
 			{"PricingService", func() error {
 				services.Pricing.Stop()
 				return nil

backend/cmd/server/wire_gen.go

@@ -41,71 +41,78 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	settingRepository := repository.NewSettingRepository(db)
 	settingService := service.NewSettingService(settingRepository, configConfig)
 	client := infrastructure.ProvideRedis(configConfig)
-	emailService := service.NewEmailService(settingRepository, client)
-	turnstileService := service.NewTurnstileService(settingService)
+	emailCache := repository.NewEmailCache(client)
+	emailService := service.NewEmailService(settingRepository, emailCache)
+	turnstileVerifier := repository.NewTurnstileVerifier()
+	turnstileService := service.NewTurnstileService(settingService, turnstileVerifier)
 	emailQueueService := service.ProvideEmailQueueService(emailService)
 	authService := service.NewAuthService(userRepository, configConfig, settingService, emailService, turnstileService, emailQueueService)
 	authHandler := handler.NewAuthHandler(authService)
-	userService := service.NewUserService(userRepository, configConfig)
+	userService := service.NewUserService(userRepository)
 	userHandler := handler.NewUserHandler(userService)
 	apiKeyRepository := repository.NewApiKeyRepository(db)
 	groupRepository := repository.NewGroupRepository(db)
 	userSubscriptionRepository := repository.NewUserSubscriptionRepository(db)
-	apiKeyService := service.NewApiKeyService(apiKeyRepository, userRepository, groupRepository, userSubscriptionRepository, client, configConfig)
+	apiKeyCache := repository.NewApiKeyCache(client)
+	apiKeyService := service.NewApiKeyService(apiKeyRepository, userRepository, groupRepository, userSubscriptionRepository, apiKeyCache, configConfig)
 	apiKeyHandler := handler.NewAPIKeyHandler(apiKeyService)
 	usageLogRepository := repository.NewUsageLogRepository(db)
 	usageService := service.NewUsageService(usageLogRepository, userRepository)
 	usageHandler := handler.NewUsageHandler(usageService, usageLogRepository, apiKeyService)
 	redeemCodeRepository := repository.NewRedeemCodeRepository(db)
-	accountRepository := repository.NewAccountRepository(db)
-	proxyRepository := repository.NewProxyRepository(db)
-	repositories := &repository.Repositories{
-		User:             userRepository,
-		ApiKey:           apiKeyRepository,
-		Group:            groupRepository,
-		Account:          accountRepository,
-		Proxy:            proxyRepository,
-		RedeemCode:       redeemCodeRepository,
-		UsageLog:         usageLogRepository,
-		Setting:          settingRepository,
-		UserSubscription: userSubscriptionRepository,
-	}
-	billingCacheService := service.NewBillingCacheService(client, userRepository, userSubscriptionRepository)
-	subscriptionService := service.NewSubscriptionService(repositories, billingCacheService)
-	redeemService := service.NewRedeemService(redeemCodeRepository, userRepository, subscriptionService, client, billingCacheService)
+	billingCache := repository.NewBillingCache(client)
+	billingCacheService := service.NewBillingCacheService(billingCache, userRepository, userSubscriptionRepository)
+	subscriptionService := service.NewSubscriptionService(groupRepository, userSubscriptionRepository, billingCacheService)
+	redeemCache := repository.NewRedeemCache(client)
+	redeemService := service.NewRedeemService(redeemCodeRepository, userRepository, subscriptionService, redeemCache, billingCacheService)
 	redeemHandler := handler.NewRedeemHandler(redeemService)
 	subscriptionHandler := handler.NewSubscriptionHandler(subscriptionService)
-	adminService := service.NewAdminService(repositories, billingCacheService)
-	dashboardHandler := admin.NewDashboardHandler(adminService, usageLogRepository)
+	dashboardHandler := admin.NewDashboardHandler(usageLogRepository)
+	accountRepository := repository.NewAccountRepository(db)
+	proxyRepository := repository.NewProxyRepository(db)
+	proxyExitInfoProber := repository.NewProxyExitInfoProber()
+	adminService := service.NewAdminService(userRepository, groupRepository, accountRepository, proxyRepository, apiKeyRepository, redeemCodeRepository, billingCacheService, proxyExitInfoProber)
 	adminUserHandler := admin.NewUserHandler(adminService)
 	groupHandler := admin.NewGroupHandler(adminService)
-	oAuthService := service.NewOAuthService(proxyRepository)
-	rateLimitService := service.NewRateLimitService(repositories, configConfig)
-	accountUsageService := service.NewAccountUsageService(repositories, oAuthService)
-	accountTestService := service.NewAccountTestService(repositories, oAuthService)
+	claudeOAuthClient := repository.NewClaudeOAuthClient()
+	oAuthService := service.NewOAuthService(proxyRepository, claudeOAuthClient)
+	rateLimitService := service.NewRateLimitService(accountRepository, configConfig)
+	claudeUsageFetcher := repository.NewClaudeUsageFetcher()
+	accountUsageService := service.NewAccountUsageService(accountRepository, usageLogRepository, claudeUsageFetcher)
+	claudeUpstream := repository.NewClaudeUpstream(configConfig)
+	accountTestService := service.NewAccountTestService(accountRepository, oAuthService, claudeUpstream)
 	accountHandler := admin.NewAccountHandler(adminService, oAuthService, rateLimitService, accountUsageService, accountTestService)
-	oAuthHandler := admin.NewOAuthHandler(oAuthService, adminService)
+	oAuthHandler := admin.NewOAuthHandler(oAuthService)
 	proxyHandler := admin.NewProxyHandler(adminService)
 	adminRedeemHandler := admin.NewRedeemHandler(adminService)
 	settingHandler := admin.NewSettingHandler(settingService, emailService)
-	systemHandler := handler.ProvideSystemHandler(client, buildInfo)
+	updateCache := repository.NewUpdateCache(client)
+	gitHubReleaseClient := repository.NewGitHubReleaseClient()
+	serviceBuildInfo := provideServiceBuildInfo(buildInfo)
+	updateService := service.ProvideUpdateService(updateCache, gitHubReleaseClient, serviceBuildInfo)
+	systemHandler := handler.ProvideSystemHandler(updateService)
 	adminSubscriptionHandler := admin.NewSubscriptionHandler(subscriptionService)
 	adminUsageHandler := admin.NewUsageHandler(usageLogRepository, apiKeyRepository, usageService, adminService)
 	adminHandlers := handler.ProvideAdminHandlers(dashboardHandler, adminUserHandler, groupHandler, accountHandler, oAuthHandler, proxyHandler, adminRedeemHandler, settingHandler, systemHandler, adminSubscriptionHandler, adminUsageHandler)
-	pricingService, err := service.ProvidePricingService(configConfig)
+	gatewayCache := repository.NewGatewayCache(client)
+	pricingRemoteClient := repository.NewPricingRemoteClient()
+	pricingService, err := service.ProvidePricingService(configConfig, pricingRemoteClient)
 	if err != nil {
 		return nil, err
 	}
 	billingService := service.NewBillingService(configConfig, pricingService)
-	identityService := service.NewIdentityService(client)
-	gatewayService := service.NewGatewayService(repositories, client, configConfig, oAuthService, billingService, rateLimitService, billingCacheService, identityService)
-	concurrencyService := service.NewConcurrencyService(client)
+	identityCache := repository.NewIdentityCache(client)
+	identityService := service.NewIdentityService(identityCache)
+	gatewayService := service.NewGatewayService(accountRepository, usageLogRepository, userRepository, userSubscriptionRepository, gatewayCache, configConfig, billingService, rateLimitService, billingCacheService, identityService, claudeUpstream)
+	concurrencyCache := repository.NewConcurrencyCache(client)
+	concurrencyService := service.NewConcurrencyService(concurrencyCache)
 	gatewayHandler := handler.NewGatewayHandler(gatewayService, userService, concurrencyService, billingCacheService)
 	handlerSettingHandler := handler.ProvideSettingHandler(settingService, buildInfo)
 	handlers := handler.ProvideHandlers(authHandler, userHandler, apiKeyHandler, usageHandler, redeemHandler, subscriptionHandler, adminHandlers, gatewayHandler, handlerSettingHandler)
 	groupService := service.NewGroupService(groupRepository)
 	accountService := service.NewAccountService(accountRepository, groupRepository)
 	proxyService := service.NewProxyService(proxyRepository)
+	tokenRefreshService := service.ProvideTokenRefreshService(accountRepository, oAuthService, configConfig)
 	services := &service.Services{
 		Auth:         authService,
 		User:         userService,
@@ -131,6 +138,19 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 		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)
 	httpServer := server.ProvideHTTPServer(configConfig, engine)
@@ -149,6 +169,13 @@ type Application struct {
 	Cleanup func()
 }
 
+func provideServiceBuildInfo(buildInfo handler.BuildInfo) service.BuildInfo {
+	return service.BuildInfo{
+		Version:   buildInfo.Version,
+		BuildType: buildInfo.BuildType,
+	}
+}
+
 func provideCleanup(
 	db *gorm.DB,
 	rdb *redis.Client,
@@ -162,6 +189,10 @@ func provideCleanup(
 			name string
 			fn   func() error
 		}{
+			{"TokenRefreshService", func() error {
+				services.TokenRefresh.Stop()
+				return nil
+			}},
 			{"PricingService", func() error {
 				services.Pricing.Stop()
 				return nil

backend/internal/config/config.go

@@ -8,15 +8,30 @@ import (
 )
 
 type Config struct {
-	Server    ServerConfig    `mapstructure:"server"`
-	Database  DatabaseConfig  `mapstructure:"database"`
-	Redis     RedisConfig     `mapstructure:"redis"`
-	JWT       JWTConfig       `mapstructure:"jwt"`
-	Default   DefaultConfig   `mapstructure:"default"`
-	RateLimit RateLimitConfig `mapstructure:"rate_limit"`
-	Pricing   PricingConfig   `mapstructure:"pricing"`
-	Gateway   GatewayConfig   `mapstructure:"gateway"`
-	Timezone  string          `mapstructure:"timezone"` // e.g. "Asia/Shanghai", "UTC"
+	Server       ServerConfig       `mapstructure:"server"`
+	Database     DatabaseConfig     `mapstructure:"database"`
+	Redis        RedisConfig        `mapstructure:"redis"`
+	JWT          JWTConfig          `mapstructure:"jwt"`
+	Default      DefaultConfig      `mapstructure:"default"`
+	RateLimit    RateLimitConfig    `mapstructure:"rate_limit"`
+	Pricing      PricingConfig      `mapstructure:"pricing"`
+	Gateway      GatewayConfig      `mapstructure:"gateway"`
+	TokenRefresh TokenRefreshConfig `mapstructure:"token_refresh"`
+	Timezone     string             `mapstructure:"timezone"` // e.g. "Asia/Shanghai", "UTC"
+}
+
+// TokenRefreshConfig OAuth token自动刷新配置
+type TokenRefreshConfig struct {
+	// 是否启用自动刷新
+	Enabled bool `mapstructure:"enabled"`
+	// 检查间隔（分钟）
+	CheckIntervalMinutes int `mapstructure:"check_interval_minutes"`
+	// 提前刷新时间（小时），在token过期前多久开始刷新
+	RefreshBeforeExpiryHours float64 `mapstructure:"refresh_before_expiry_hours"`
+	// 最大重试次数
+	MaxRetries int `mapstructure:"max_retries"`
+	// 重试退避基础时间（秒）
+	RetryBackoffSeconds int `mapstructure:"retry_backoff_seconds"`
 }
 
 type PricingConfig struct {
@@ -37,7 +52,7 @@ type PricingConfig struct {
 type ServerConfig struct {
 	Host              string `mapstructure:"host"`
 	Port              int    `mapstructure:"port"`
-	Mode              string `mapstructure:"mode"`               // debug/release
+	Mode              string `mapstructure:"mode"`                // debug/release
 	ReadHeaderTimeout int    `mapstructure:"read_header_timeout"` // 读取请求头超时（秒）
 	IdleTimeout       int    `mapstructure:"idle_timeout"`        // 空闲连接超时（秒）
 }
@@ -148,7 +163,7 @@ func setDefaults() {
 	viper.SetDefault("server.port", 8080)
 	viper.SetDefault("server.mode", "debug")
 	viper.SetDefault("server.read_header_timeout", 30) // 30秒读取请求头
-	viper.SetDefault("server.idle_timeout", 120)      // 120秒空闲超时
+	viper.SetDefault("server.idle_timeout", 120)       // 120秒空闲超时
 
 	// Database
 	viper.SetDefault("database.host", "localhost")
@@ -192,6 +207,13 @@ func setDefaults() {
 
 	// Gateway
 	viper.SetDefault("gateway.response_header_timeout", 300) // 300秒(5分钟)等待上游响应头，LLM高负载时可能排队较久
+
+	// TokenRefresh
+	viper.SetDefault("token_refresh.enabled", true)
+	viper.SetDefault("token_refresh.check_interval_minutes", 5)        // 每5分钟检查一次
+	viper.SetDefault("token_refresh.refresh_before_expiry_hours", 1.5) // 提前1.5小时刷新
+	viper.SetDefault("token_refresh.max_retries", 3)                   // 最多重试3次
+	viper.SetDefault("token_refresh.retry_backoff_seconds", 2)         // 重试退避基础2秒
 }
 
 func (c *Config) Validate() error {
@@ -203,3 +225,29 @@ func (c *Config) Validate() error {
 	}
 	return nil
 }
+
+// GetServerAddress returns the server address (host:port) from config file or environment variable.
+// This is a lightweight function that can be used before full config validation,
+// such as during setup wizard startup.
+// Priority: config.yaml > environment variables > defaults
+func GetServerAddress() string {
+	v := viper.New()
+	v.SetConfigName("config")
+	v.SetConfigType("yaml")
+	v.AddConfigPath(".")
+	v.AddConfigPath("./config")
+	v.AddConfigPath("/etc/sub2api")
+
+	// Support SERVER_HOST and SERVER_PORT environment variables
+	v.AutomaticEnv()
+	v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+	v.SetDefault("server.host", "0.0.0.0")
+	v.SetDefault("server.port", 8080)
+
+	// Try to read config file (ignore errors if not found)
+	_ = v.ReadInConfig()
+
+	host := v.GetString("server.host")
+	port := v.GetInt("server.port")
+	return fmt.Sprintf("%s:%d", host, port)
+}

backend/internal/handler/admin/account_handler.go

@@ -3,6 +3,7 @@ package admin
 import (
 	"strconv"
 
+	"sub2api/internal/pkg/claude"
 	"sub2api/internal/pkg/response"
 	"sub2api/internal/service"
 
@@ -12,14 +13,12 @@ import (
 // OAuthHandler handles OAuth-related operations for accounts
 type OAuthHandler struct {
 	oauthService *service.OAuthService
-	adminService service.AdminService
 }
 
 // NewOAuthHandler creates a new OAuth handler
-func NewOAuthHandler(oauthService *service.OAuthService, adminService service.AdminService) *OAuthHandler {
+func NewOAuthHandler(oauthService *service.OAuthService) *OAuthHandler {
 	return &OAuthHandler{
 		oauthService: oauthService,
-		adminService: adminService,
 	}
 }
 
@@ -45,29 +44,29 @@ func NewAccountHandler(adminService service.AdminService, oauthService *service.
 
 // CreateAccountRequest represents create account request
 type CreateAccountRequest struct {
-	Name        string                 `json:"name" binding:"required"`
-	Platform    string                 `json:"platform" binding:"required"`
-	Type        string                 `json:"type" binding:"required,oneof=oauth setup-token apikey"`
-	Credentials map[string]interface{} `json:"credentials" binding:"required"`
-	Extra       map[string]interface{} `json:"extra"`
-	ProxyID     *int64                 `json:"proxy_id"`
-	Concurrency int                    `json:"concurrency"`
-	Priority    int                    `json:"priority"`
-	GroupIDs    []int64                `json:"group_ids"`
+	Name        string         `json:"name" binding:"required"`
+	Platform    string         `json:"platform" binding:"required"`
+	Type        string         `json:"type" binding:"required,oneof=oauth setup-token apikey"`
+	Credentials map[string]any `json:"credentials" binding:"required"`
+	Extra       map[string]any `json:"extra"`
+	ProxyID     *int64         `json:"proxy_id"`
+	Concurrency int            `json:"concurrency"`
+	Priority    int            `json:"priority"`
+	GroupIDs    []int64        `json:"group_ids"`
 }
 
 // UpdateAccountRequest represents update account request
 // 使用指针类型来区分"未提供"和"设置为0"
 type UpdateAccountRequest struct {
-	Name        string                 `json:"name"`
-	Type        string                 `json:"type" binding:"omitempty,oneof=oauth setup-token apikey"`
-	Credentials map[string]interface{} `json:"credentials"`
-	Extra       map[string]interface{} `json:"extra"`
-	ProxyID     *int64                 `json:"proxy_id"`
-	Concurrency *int                   `json:"concurrency"`
-	Priority    *int                   `json:"priority"`
-	Status      string                 `json:"status" binding:"omitempty,oneof=active inactive"`
-	GroupIDs    *[]int64               `json:"group_ids"`
+	Name        string         `json:"name"`
+	Type        string         `json:"type" binding:"omitempty,oneof=oauth setup-token apikey"`
+	Credentials map[string]any `json:"credentials"`
+	Extra       map[string]any `json:"extra"`
+	ProxyID     *int64         `json:"proxy_id"`
+	Concurrency *int           `json:"concurrency"`
+	Priority    *int           `json:"priority"`
+	Status      string         `json:"status" binding:"omitempty,oneof=active inactive"`
+	GroupIDs    *[]int64       `json:"group_ids"`
 }
 
 // List handles listing all accounts with pagination
@@ -186,6 +185,11 @@ func (h *AccountHandler) Delete(c *gin.Context) {
 	response.Success(c, gin.H{"message": "Account deleted successfully"})
 }
 
+// TestAccountRequest represents the request body for testing an account
+type TestAccountRequest struct {
+	ModelID string `json:"model_id"`
+}
+
 // Test handles testing account connectivity with SSE streaming
 // POST /api/v1/admin/accounts/:id/test
 func (h *AccountHandler) Test(c *gin.Context) {
@@ -195,8 +199,12 @@ func (h *AccountHandler) Test(c *gin.Context) {
 		return
 	}
 
+	var req TestAccountRequest
+	// Allow empty body, model_id is optional
+	_ = c.ShouldBindJSON(&req)
+
 	// Use AccountTestService to test the account with SSE streaming
-	if err := h.accountTestService.TestAccountConnection(c, accountID); err != nil {
+	if err := h.accountTestService.TestAccountConnection(c, accountID, req.ModelID); err != nil {
 		// Error already sent via SSE, just log
 		return
 	}
@@ -231,16 +239,20 @@ func (h *AccountHandler) Refresh(c *gin.Context) {
 		return
 	}
 
-	// Update account credentials
-	newCredentials := map[string]interface{}{
-		"access_token":  tokenInfo.AccessToken,
-		"token_type":    tokenInfo.TokenType,
-		"expires_in":    tokenInfo.ExpiresIn,
-		"expires_at":    tokenInfo.ExpiresAt,
-		"refresh_token": tokenInfo.RefreshToken,
-		"scope":         tokenInfo.Scope,
+	// Copy existing credentials to preserve non-token settings (e.g., intercept_warmup_requests)
+	newCredentials := make(map[string]any)
+	for k, v := range account.Credentials {
+		newCredentials[k] = v
 	}
 
+	// Update token-related fields
+	newCredentials["access_token"] = tokenInfo.AccessToken
+	newCredentials["token_type"] = tokenInfo.TokenType
+	newCredentials["expires_in"] = tokenInfo.ExpiresIn
+	newCredentials["expires_at"] = tokenInfo.ExpiresAt
+	newCredentials["refresh_token"] = tokenInfo.RefreshToken
+	newCredentials["scope"] = tokenInfo.Scope
+
 	updatedAccount, err := h.adminService.UpdateAccount(c.Request.Context(), accountID, &service.UpdateAccountInput{
 		Credentials: newCredentials,
 	})
@@ -535,3 +547,58 @@ func (h *AccountHandler) SetSchedulable(c *gin.Context) {
 
 	response.Success(c, account)
 }
+
+// GetAvailableModels handles getting available models for an account
+// GET /api/v1/admin/accounts/:id/models
+func (h *AccountHandler) GetAvailableModels(c *gin.Context) {
+	accountID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid account ID")
+		return
+	}
+
+	account, err := h.adminService.GetAccount(c.Request.Context(), accountID)
+	if err != nil {
+		response.NotFound(c, "Account not found")
+		return
+	}
+
+	// For OAuth and Setup-Token accounts: return default models
+	if account.IsOAuth() {
+		response.Success(c, claude.DefaultModels)
+		return
+	}
+
+	// For API Key accounts: return models based on model_mapping
+	mapping := account.GetModelMapping()
+	if len(mapping) == 0 {
+		// No mapping configured, return default models
+		response.Success(c, claude.DefaultModels)
+		return
+	}
+
+	// Return mapped models (keys of the mapping are the available model IDs)
+	var models []claude.Model
+	for requestedModel := range mapping {
+		// Try to find display info from default models
+		var found bool
+		for _, dm := range claude.DefaultModels {
+			if dm.ID == requestedModel {
+				models = append(models, dm)
+				found = true
+				break
+			}
+		}
+		// If not found in defaults, create a basic entry
+		if !found {
+			models = append(models, claude.Model{
+				ID:          requestedModel,
+				Type:        "model",
+				DisplayName: requestedModel,
+				CreatedAt:   "",
+			})
+		}
+	}
+
+	response.Success(c, models)
+}

backend/internal/handler/admin/dashboard_handler.go

@@ -5,7 +5,6 @@ import (
 	"sub2api/internal/pkg/response"
 	"sub2api/internal/pkg/timezone"
 	"sub2api/internal/repository"
-	"sub2api/internal/service"
 	"time"
 
 	"github.com/gin-gonic/gin"
@@ -13,17 +12,15 @@ import (
 
 // DashboardHandler handles admin dashboard statistics
 type DashboardHandler struct {
-	adminService service.AdminService
-	usageRepo    *repository.UsageLogRepository
-	startTime    time.Time // Server start time for uptime calculation
+	usageRepo *repository.UsageLogRepository
+	startTime time.Time // Server start time for uptime calculation
 }
 
 // NewDashboardHandler creates a new admin dashboard handler
-func NewDashboardHandler(adminService service.AdminService, usageRepo *repository.UsageLogRepository) *DashboardHandler {
+func NewDashboardHandler(usageRepo *repository.UsageLogRepository) *DashboardHandler {
 	return &DashboardHandler{
-		adminService: adminService,
-		usageRepo:    usageRepo,
-		startTime:    time.Now(),
+		usageRepo: usageRepo,
+		startTime: time.Now(),
 	}
 }
 
@@ -127,12 +124,25 @@ func (h *DashboardHandler) GetRealtimeMetrics(c *gin.Context) {
 
 // GetUsageTrend handles getting usage trend data
 // GET /api/v1/admin/dashboard/trend
-// Query params: start_date, end_date (YYYY-MM-DD), granularity (day/hour)
+// Query params: start_date, end_date (YYYY-MM-DD), granularity (day/hour), user_id, api_key_id
 func (h *DashboardHandler) GetUsageTrend(c *gin.Context) {
 	startTime, endTime := parseTimeRange(c)
 	granularity := c.DefaultQuery("granularity", "day")
 
-	trend, err := h.usageRepo.GetUsageTrend(c.Request.Context(), startTime, endTime, granularity)
+	// Parse optional filter params
+	var userID, apiKeyID int64
+	if userIDStr := c.Query("user_id"); userIDStr != "" {
+		if id, err := strconv.ParseInt(userIDStr, 10, 64); err == nil {
+			userID = id
+		}
+	}
+	if apiKeyIDStr := c.Query("api_key_id"); apiKeyIDStr != "" {
+		if id, err := strconv.ParseInt(apiKeyIDStr, 10, 64); err == nil {
+			apiKeyID = id
+		}
+	}
+
+	trend, err := h.usageRepo.GetUsageTrendWithFilters(c.Request.Context(), startTime, endTime, granularity, userID, apiKeyID)
 	if err != nil {
 		response.Error(c, 500, "Failed to get usage trend")
 		return
@@ -148,11 +158,24 @@ func (h *DashboardHandler) GetUsageTrend(c *gin.Context) {
 
 // GetModelStats handles getting model usage statistics
 // GET /api/v1/admin/dashboard/models
-// Query params: start_date, end_date (YYYY-MM-DD)
+// Query params: start_date, end_date (YYYY-MM-DD), user_id, api_key_id
 func (h *DashboardHandler) GetModelStats(c *gin.Context) {
 	startTime, endTime := parseTimeRange(c)
 
-	stats, err := h.usageRepo.GetModelStats(c.Request.Context(), startTime, endTime)
+	// Parse optional filter params
+	var userID, apiKeyID int64
+	if userIDStr := c.Query("user_id"); userIDStr != "" {
+		if id, err := strconv.ParseInt(userIDStr, 10, 64); err == nil {
+			userID = id
+		}
+	}
+	if apiKeyIDStr := c.Query("api_key_id"); apiKeyIDStr != "" {
+		if id, err := strconv.ParseInt(apiKeyIDStr, 10, 64); err == nil {
+			apiKeyID = id
+		}
+	}
+
+	stats, err := h.usageRepo.GetModelStatsWithFilters(c.Request.Context(), startTime, endTime, userID, apiKeyID)
 	if err != nil {
 		response.Error(c, 500, "Failed to get model statistics")
 		return
@@ -232,7 +255,7 @@ func (h *DashboardHandler) GetBatchUsersUsage(c *gin.Context) {
 	}
 
 	if len(req.UserIDs) == 0 {
-		response.Success(c, gin.H{"stats": map[string]interface{}{}})
+		response.Success(c, gin.H{"stats": map[string]any{}})
 		return
 	}
 
@@ -260,7 +283,7 @@ func (h *DashboardHandler) GetBatchApiKeysUsage(c *gin.Context) {
 	}
 
 	if len(req.ApiKeyIDs) == 0 {
-		response.Success(c, gin.H{"stats": map[string]interface{}{}})
+		response.Success(c, gin.H{"stats": map[string]any{}})
 		return
 	}
 

backend/internal/handler/admin/proxy_handler.go

@@ -2,6 +2,7 @@ package admin
 
 import (
 	"strconv"
+	"strings"
 
 	"sub2api/internal/pkg/response"
 	"sub2api/internal/service"
@@ -112,12 +113,12 @@ func (h *ProxyHandler) Create(c *gin.Context) {
 	}
 
 	proxy, err := h.adminService.CreateProxy(c.Request.Context(), &service.CreateProxyInput{
-		Name:     req.Name,
-		Protocol: req.Protocol,
-		Host:     req.Host,
+		Name:     strings.TrimSpace(req.Name),
+		Protocol: strings.TrimSpace(req.Protocol),
+		Host:     strings.TrimSpace(req.Host),
 		Port:     req.Port,
-		Username: req.Username,
-		Password: req.Password,
+		Username: strings.TrimSpace(req.Username),
+		Password: strings.TrimSpace(req.Password),
 	})
 	if err != nil {
 		response.BadRequest(c, "Failed to create proxy: "+err.Error())
@@ -143,13 +144,13 @@ func (h *ProxyHandler) Update(c *gin.Context) {
 	}
 
 	proxy, err := h.adminService.UpdateProxy(c.Request.Context(), proxyID, &service.UpdateProxyInput{
-		Name:     req.Name,
-		Protocol: req.Protocol,
-		Host:     req.Host,
+		Name:     strings.TrimSpace(req.Name),
+		Protocol: strings.TrimSpace(req.Protocol),
+		Host:     strings.TrimSpace(req.Host),
 		Port:     req.Port,
-		Username: req.Username,
-		Password: req.Password,
-		Status:   req.Status,
+		Username: strings.TrimSpace(req.Username),
+		Password: strings.TrimSpace(req.Password),
+		Status:   strings.TrimSpace(req.Status),
 	})
 	if err != nil {
 		response.InternalError(c, "Failed to update proxy: "+err.Error())
@@ -235,7 +236,6 @@ func (h *ProxyHandler) GetProxyAccounts(c *gin.Context) {
 	response.Paginated(c, accounts, total, page, pageSize)
 }
 
-
 // BatchCreateProxyItem represents a single proxy in batch create request
 type BatchCreateProxyItem struct {
 	Protocol string `json:"protocol" binding:"required,oneof=http https socks5"`
@@ -263,8 +263,14 @@ func (h *ProxyHandler) BatchCreate(c *gin.Context) {
 	skipped := 0
 
 	for _, item := range req.Proxies {
+		// Trim all string fields
+		host := strings.TrimSpace(item.Host)
+		protocol := strings.TrimSpace(item.Protocol)
+		username := strings.TrimSpace(item.Username)
+		password := strings.TrimSpace(item.Password)
+
 		// Check for duplicates (same host, port, username, password)
-		exists, err := h.adminService.CheckProxyExists(c.Request.Context(), item.Host, item.Port, item.Username, item.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())
 			return
@@ -278,11 +284,11 @@ func (h *ProxyHandler) BatchCreate(c *gin.Context) {
 		// Create proxy with default name
 		_, err = h.adminService.CreateProxy(c.Request.Context(), &service.CreateProxyInput{
 			Name:     "default",
-			Protocol: item.Protocol,
-			Host:     item.Host,
+			Protocol: protocol,
+			Host:     host,
 			Port:     item.Port,
-			Username: item.Username,
-			Password: item.Password,
+			Username: username,
+			Password: password,
 		})
 		if err != nil {
 			// If creation fails due to duplicate, count as skipped

backend/internal/handler/admin/redeem_handler.go

@@ -156,10 +156,10 @@ func (h *RedeemHandler) Expire(c *gin.Context) {
 func (h *RedeemHandler) GetStats(c *gin.Context) {
 	// Return mock data for now
 	response.Success(c, gin.H{
-		"total_codes":            0,
-		"active_codes":           0,
-		"used_codes":             0,
-		"expired_codes":          0,
+		"total_codes":             0,
+		"active_codes":            0,
+		"used_codes":              0,
+		"expired_codes":           0,
 		"total_value_distributed": 0.0,
 		"by_type": gin.H{
 			"balance":     0,
@@ -187,7 +187,10 @@ func (h *RedeemHandler) Export(c *gin.Context) {
 	writer := csv.NewWriter(&buf)
 
 	// Write header
-	writer.Write([]string{"id", "code", "type", "value", "status", "used_by", "used_at", "created_at"})
+	if err := writer.Write([]string{"id", "code", "type", "value", "status", "used_by", "used_at", "created_at"}); err != nil {
+		response.InternalError(c, "Failed to export redeem codes: "+err.Error())
+		return
+	}
 
 	// Write data rows
 	for _, code := range codes {
@@ -199,7 +202,7 @@ func (h *RedeemHandler) Export(c *gin.Context) {
 		if code.UsedAt != nil {
 			usedAt = code.UsedAt.Format("2006-01-02 15:04:05")
 		}
-		writer.Write([]string{
+		if err := writer.Write([]string{
 			fmt.Sprintf("%d", code.ID),
 			code.Code,
 			code.Type,
@@ -208,10 +211,17 @@ func (h *RedeemHandler) Export(c *gin.Context) {
 			usedBy,
 			usedAt,
 			code.CreatedAt.Format("2006-01-02 15:04:05"),
-		})
+		}); err != nil {
+			response.InternalError(c, "Failed to export redeem codes: "+err.Error())
+			return
+		}
 	}
 
 	writer.Flush()
+	if err := writer.Error(); err != nil {
+		response.InternalError(c, "Failed to export redeem codes: "+err.Error())
+		return
+	}
 
 	c.Header("Content-Type", "text/csv")
 	c.Header("Content-Disposition", "attachment; filename=redeem_codes.csv")

backend/internal/handler/admin/setting_handler.go

@@ -256,3 +256,43 @@ func (h *SettingHandler) SendTestEmail(c *gin.Context) {
 
 	response.Success(c, gin.H{"message": "Test email sent successfully"})
 }
+
+// GetAdminApiKey 获取管理员 API Key 状态
+// GET /api/v1/admin/settings/admin-api-key
+func (h *SettingHandler) GetAdminApiKey(c *gin.Context) {
+	maskedKey, exists, err := h.settingService.GetAdminApiKeyStatus(c.Request.Context())
+	if err != nil {
+		response.InternalError(c, "Failed to get admin API key status: "+err.Error())
+		return
+	}
+
+	response.Success(c, gin.H{
+		"exists":     exists,
+		"masked_key": maskedKey,
+	})
+}
+
+// RegenerateAdminApiKey 生成/重新生成管理员 API Key
+// POST /api/v1/admin/settings/admin-api-key/regenerate
+func (h *SettingHandler) RegenerateAdminApiKey(c *gin.Context) {
+	key, err := h.settingService.GenerateAdminApiKey(c.Request.Context())
+	if err != nil {
+		response.InternalError(c, "Failed to generate admin API key: "+err.Error())
+		return
+	}
+
+	response.Success(c, gin.H{
+		"key": key, // 完整 key 只在生成时返回一次
+	})
+}
+
+// DeleteAdminApiKey 删除管理员 API Key
+// DELETE /api/v1/admin/settings/admin-api-key
+func (h *SettingHandler) DeleteAdminApiKey(c *gin.Context) {
+	if err := h.settingService.DeleteAdminApiKey(c.Request.Context()); err != nil {
+		response.InternalError(c, "Failed to delete admin API key: "+err.Error())
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Admin API key deleted"})
+}

backend/internal/handler/admin/subscription_handler.go

@@ -4,15 +4,15 @@ import (
 	"strconv"
 
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 	"sub2api/internal/pkg/response"
-	"sub2api/internal/repository"
 	"sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
 
-// toResponsePagination converts repository.PaginationResult to response.PaginationResult
-func toResponsePagination(p *repository.PaginationResult) *response.PaginationResult {
+// toResponsePagination converts pagination.PaginationResult to response.PaginationResult
+func toResponsePagination(p *pagination.PaginationResult) *response.PaginationResult {
 	if p == nil {
 		return nil
 	}

backend/internal/handler/admin/system_handler.go

@@ -9,7 +9,6 @@ import (
 	"sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
-	"github.com/redis/go-redis/v9"
 )
 
 // SystemHandler handles system-related operations
@@ -18,9 +17,9 @@ type SystemHandler struct {
 }
 
 // NewSystemHandler creates a new SystemHandler
-func NewSystemHandler(rdb *redis.Client, version, buildType string) *SystemHandler {
+func NewSystemHandler(updateSvc *service.UpdateService) *SystemHandler {
 	return &SystemHandler{
-		updateSvc: service.NewUpdateService(rdb, version, buildType),
+		updateSvc: updateSvc,
 	}
 }
 

backend/internal/handler/admin/usage_handler.go

@@ -4,6 +4,7 @@ import (
 	"strconv"
 	"time"
 
+	"sub2api/internal/pkg/pagination"
 	"sub2api/internal/pkg/response"
 	"sub2api/internal/pkg/timezone"
 	"sub2api/internal/repository"
@@ -14,10 +15,10 @@ import (
 
 // UsageHandler handles admin usage-related requests
 type UsageHandler struct {
-	usageRepo     *repository.UsageLogRepository
-	apiKeyRepo    *repository.ApiKeyRepository
-	usageService  *service.UsageService
-	adminService  service.AdminService
+	usageRepo    *repository.UsageLogRepository
+	apiKeyRepo   *repository.ApiKeyRepository
+	usageService *service.UsageService
+	adminService service.AdminService
 }
 
 // NewUsageHandler creates a new admin usage handler
@@ -82,7 +83,7 @@ func (h *UsageHandler) List(c *gin.Context) {
 		endTime = &t
 	}
 
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	filters := repository.UsageLogFilters{
 		UserID:    userID,
 		ApiKeyID:  apiKeyID,
@@ -192,7 +193,7 @@ func (h *UsageHandler) Stats(c *gin.Context) {
 func (h *UsageHandler) SearchUsers(c *gin.Context) {
 	keyword := c.Query("q")
 	if keyword == "" {
-		response.Success(c, []interface{}{})
+		response.Success(c, []any{})
 		return
 	}
 

backend/internal/handler/api_key_handler.go

@@ -4,8 +4,8 @@ import (
 	"strconv"
 
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 	"sub2api/internal/pkg/response"
-	"sub2api/internal/repository"
 	"sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
@@ -53,7 +53,7 @@ func (h *APIKeyHandler) List(c *gin.Context) {
 	}
 
 	page, pageSize := response.ParsePagination(c)
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 
 	keys, result, err := h.apiKeyService.List(c.Request.Context(), user.ID, params)
 	if err != nil {

backend/internal/handler/gateway_handler.go

@@ -7,10 +7,12 @@ import (
 	"io"
 	"log"
 	"net/http"
+	"strings"
 	"time"
 
 	"sub2api/internal/middleware"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/claude"
 	"sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
@@ -126,6 +128,16 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 		return
 	}
 
+	// 检查预热请求拦截（在账号选择后、转发前检查）
+	if account.IsInterceptWarmupEnabled() && isWarmupRequest(body) {
+		if req.Stream {
+			sendMockWarmupStream(c, req.Model)
+		} else {
+			sendMockWarmupResponse(c, req.Model)
+		}
+		return
+	}
+
 	// 3. 获取账号并发槽位
 	accountReleaseFunc, err := h.acquireAccountSlotWithWait(c, account, req.Stream, &streamStarted)
 	if err != nil {
@@ -256,7 +268,9 @@ func (h *GatewayHandler) waitForSlotWithPing(c *gin.Context, slotType string, id
 					c.Header("X-Accel-Buffering", "no")
 					*streamStarted = true
 				}
-				fmt.Fprintf(c.Writer, "data: {\"type\": \"ping\"}\n\n")
+				if _, err := fmt.Fprintf(c.Writer, "data: {\"type\": \"ping\"}\n\n"); err != nil {
+					return nil, err
+				}
 				flusher.Flush()
 			}
 
@@ -285,29 +299,8 @@ func (h *GatewayHandler) waitForSlotWithPing(c *gin.Context, slotType string, id
 // Models handles listing available models
 // GET /v1/models
 func (h *GatewayHandler) Models(c *gin.Context) {
-	models := []gin.H{
-		{
-			"id":           "claude-opus-4-5-20251101",
-			"type":         "model",
-			"display_name": "Claude Opus 4.5",
-			"created_at":   "2025-11-01T00:00:00Z",
-		},
-		{
-			"id":           "claude-sonnet-4-5-20250929",
-			"type":         "model",
-			"display_name": "Claude Sonnet 4.5",
-			"created_at":   "2025-09-29T00:00:00Z",
-		},
-		{
-			"id":           "claude-haiku-4-5-20251001",
-			"type":         "model",
-			"display_name": "Claude Haiku 4.5",
-			"created_at":   "2025-10-01T00:00:00Z",
-		},
-	}
-
 	c.JSON(http.StatusOK, gin.H{
-		"data":   models,
+		"data":   claude.DefaultModels,
 		"object": "list",
 	})
 }
@@ -423,7 +416,9 @@ func (h *GatewayHandler) handleStreamingAwareError(c *gin.Context, status int, e
 		if ok {
 			// Send error event in SSE format
 			errorEvent := fmt.Sprintf(`data: {"type": "error", "error": {"type": "%s", "message": "%s"}}`+"\n\n", errType, message)
-			fmt.Fprint(c.Writer, errorEvent)
+			if _, err := fmt.Fprint(c.Writer, errorEvent); err != nil {
+				_ = c.Error(err)
+			}
 			flusher.Flush()
 		}
 		return
@@ -443,3 +438,155 @@ func (h *GatewayHandler) errorResponse(c *gin.Context, status int, errType, mess
 		},
 	})
 }
+
+// CountTokens handles token counting endpoint
+// POST /v1/messages/count_tokens
+// 特点：校验订阅/余额，但不计算并发、不记录使用量
+func (h *GatewayHandler) CountTokens(c *gin.Context) {
+	// 从context获取apiKey和user（ApiKeyAuth中间件已设置）
+	apiKey, ok := middleware.GetApiKeyFromContext(c)
+	if !ok {
+		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
+		return
+	}
+
+	user, ok := middleware.GetUserFromContext(c)
+	if !ok {
+		h.errorResponse(c, http.StatusInternalServerError, "api_error", "User context not found")
+		return
+	}
+
+	// 读取请求体
+	body, err := io.ReadAll(c.Request.Body)
+	if err != nil {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Failed to read request body")
+		return
+	}
+
+	if len(body) == 0 {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Request body is empty")
+		return
+	}
+
+	// 解析请求获取模型名
+	var req struct {
+		Model string `json:"model"`
+	}
+	if err := json.Unmarshal(body, &req); err != nil {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error", "Failed to parse request body")
+		return
+	}
+
+	// 获取订阅信息（可能为nil）
+	subscription, _ := middleware.GetSubscriptionFromContext(c)
+
+	// 校验 billing eligibility（订阅/余额）
+	// 【注意】不计算并发，但需要校验订阅/余额
+	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), user, apiKey, apiKey.Group, subscription); err != nil {
+		h.errorResponse(c, http.StatusForbidden, "billing_error", err.Error())
+		return
+	}
+
+	// 计算粘性会话 hash
+	sessionHash := h.gatewayService.GenerateSessionHash(body)
+
+	// 选择支持该模型的账号
+	account, err := h.gatewayService.SelectAccountForModel(c.Request.Context(), apiKey.GroupID, sessionHash, req.Model)
+	if err != nil {
+		h.errorResponse(c, http.StatusServiceUnavailable, "api_error", "No available accounts: "+err.Error())
+		return
+	}
+
+	// 转发请求（不记录使用量）
+	if err := h.gatewayService.ForwardCountTokens(c.Request.Context(), c, account, body); err != nil {
+		log.Printf("Forward count_tokens request failed: %v", err)
+		// 错误响应已在 ForwardCountTokens 中处理
+		return
+	}
+}
+
+// isWarmupRequest 检测是否为预热请求（标题生成、Warmup等）
+func isWarmupRequest(body []byte) bool {
+	// 快速检查：如果body不包含关键字，直接返回false
+	bodyStr := string(body)
+	if !strings.Contains(bodyStr, "title") && !strings.Contains(bodyStr, "Warmup") {
+		return false
+	}
+
+	// 解析完整请求
+	var req struct {
+		Messages []struct {
+			Content []struct {
+				Type string `json:"type"`
+				Text string `json:"text"`
+			} `json:"content"`
+		} `json:"messages"`
+		System []struct {
+			Text string `json:"text"`
+		} `json:"system"`
+	}
+	if err := json.Unmarshal(body, &req); err != nil {
+		return false
+	}
+
+	// 检查 messages 中的标题提示模式
+	for _, msg := range req.Messages {
+		for _, content := range msg.Content {
+			if content.Type == "text" {
+				if strings.Contains(content.Text, "Please write a 5-10 word title for the following conversation:") ||
+					content.Text == "Warmup" {
+					return true
+				}
+			}
+		}
+	}
+
+	// 检查 system 中的标题提取模式
+	for _, system := range req.System {
+		if strings.Contains(system.Text, "nalyze if this message indicates a new conversation topic. If it does, extract a 2-3 word title") {
+			return true
+		}
+	}
+
+	return false
+}
+
+// sendMockWarmupStream 发送流式 mock 响应（用于预热请求拦截）
+func sendMockWarmupStream(c *gin.Context, model string) {
+	c.Header("Content-Type", "text/event-stream")
+	c.Header("Cache-Control", "no-cache")
+	c.Header("Connection", "keep-alive")
+	c.Header("X-Accel-Buffering", "no")
+
+	events := []string{
+		`event: message_start` + "\n" + `data: {"message":{"content":[],"id":"msg_mock_warmup","model":"` + model + `","role":"assistant","stop_reason":null,"stop_sequence":null,"type":"message","usage":{"input_tokens":10,"output_tokens":0}},"type":"message_start"}`,
+		`event: content_block_start` + "\n" + `data: {"content_block":{"text":"","type":"text"},"index":0,"type":"content_block_start"}`,
+		`event: content_block_delta` + "\n" + `data: {"delta":{"text":"New","type":"text_delta"},"index":0,"type":"content_block_delta"}`,
+		`event: content_block_delta` + "\n" + `data: {"delta":{"text":" Conversation","type":"text_delta"},"index":0,"type":"content_block_delta"}`,
+		`event: content_block_stop` + "\n" + `data: {"index":0,"type":"content_block_stop"}`,
+		`event: message_delta` + "\n" + `data: {"delta":{"stop_reason":"end_turn","stop_sequence":null},"type":"message_delta","usage":{"input_tokens":10,"output_tokens":2}}`,
+		`event: message_stop` + "\n" + `data: {"type":"message_stop"}`,
+	}
+
+	for _, event := range events {
+		_, _ = c.Writer.WriteString(event + "\n\n")
+		c.Writer.Flush()
+		time.Sleep(20 * time.Millisecond)
+	}
+}
+
+// sendMockWarmupResponse 发送非流式 mock 响应（用于预热请求拦截）
+func sendMockWarmupResponse(c *gin.Context, model string) {
+	c.JSON(http.StatusOK, gin.H{
+		"id":          "msg_mock_warmup",
+		"type":        "message",
+		"role":        "assistant",
+		"model":       model,
+		"content":     []gin.H{{"type": "text", "text": "New Conversation"}},
+		"stop_reason": "end_turn",
+		"usage": gin.H{
+			"input_tokens":  10,
+			"output_tokens": 2,
+		},
+	})
+}

backend/internal/handler/usage_handler.go

@@ -5,6 +5,7 @@ import (
 	"time"
 
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 	"sub2api/internal/pkg/response"
 	"sub2api/internal/pkg/timezone"
 	"sub2api/internal/repository"
@@ -68,9 +69,9 @@ func (h *UsageHandler) List(c *gin.Context) {
 		apiKeyID = id
 	}
 
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	var records []model.UsageLog
-	var result *repository.PaginationResult
+	var result *pagination.PaginationResult
 	var err error
 
 	if apiKeyID > 0 {
@@ -357,12 +358,12 @@ func (h *UsageHandler) DashboardApiKeysUsage(c *gin.Context) {
 	}
 
 	if len(req.ApiKeyIDs) == 0 {
-		response.Success(c, gin.H{"stats": map[string]interface{}{}})
+		response.Success(c, gin.H{"stats": map[string]any{}})
 		return
 	}
 
 	// Verify ownership of all requested API keys
-	userApiKeys, _, err := h.apiKeyService.List(c.Request.Context(), user.ID, repository.PaginationParams{Page: 1, PageSize: 1000})
+	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")
 		return
@@ -382,7 +383,7 @@ func (h *UsageHandler) DashboardApiKeysUsage(c *gin.Context) {
 	}
 
 	if len(validApiKeyIDs) == 0 {
-		response.Success(c, gin.H{"stats": map[string]interface{}{}})
+		response.Success(c, gin.H{"stats": map[string]any{}})
 		return
 	}
 

backend/internal/handler/wire.go

@@ -5,7 +5,6 @@ import (
 	"sub2api/internal/service"
 
 	"github.com/google/wire"
-	"github.com/redis/go-redis/v9"
 )
 
 // ProvideAdminHandlers creates the AdminHandlers struct
@@ -37,9 +36,9 @@ func ProvideAdminHandlers(
 	}
 }
 
-// ProvideSystemHandler creates admin.SystemHandler with BuildInfo parameters
-func ProvideSystemHandler(rdb *redis.Client, buildInfo BuildInfo) *admin.SystemHandler {
-	return admin.NewSystemHandler(rdb, buildInfo.Version, buildInfo.BuildType)
+// ProvideSystemHandler creates admin.SystemHandler with UpdateService
+func ProvideSystemHandler(updateService *service.UpdateService) *admin.SystemHandler {
+	return admin.NewSystemHandler(updateService)
 }
 
 // ProvideSettingHandler creates SettingHandler with version from BuildInfo

backend/internal/middleware/admin_auth.go

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

backend/internal/model/account.go

@@ -10,7 +10,7 @@ import (
 )
 
 // JSONB 用于存储JSONB数据
-type JSONB map[string]interface{}
+type JSONB map[string]any
 
 func (j JSONB) Value() (driver.Value, error) {
 	if j == nil {
@@ -19,7 +19,7 @@ func (j JSONB) Value() (driver.Value, error) {
 	return json.Marshal(j)
 }
 
-func (j *JSONB) Scan(value interface{}) error {
+func (j *JSONB) Scan(value any) error {
 	if value == nil {
 		*j = nil
 		return nil
@@ -40,8 +40,8 @@ type Account struct {
 	Extra        JSONB          `gorm:"type:jsonb;default:'{}'" json:"extra"`       // 扩展信息
 	ProxyID      *int64         `gorm:"index" json:"proxy_id"`
 	Concurrency  int            `gorm:"default:3;not null" json:"concurrency"`
-	Priority     int            `gorm:"default:50;not null" json:"priority"`            // 1-100，越小越高
-	Status       string         `gorm:"size:20;default:active;not null" json:"status"`  // active/disabled/error
+	Priority     int            `gorm:"default:50;not null" json:"priority"`           // 1-100，越小越高
+	Status       string         `gorm:"size:20;default:active;not null" json:"status"` // active/disabled/error
 	ErrorMessage string         `gorm:"type:text" json:"error_message"`
 	LastUsedAt   *time.Time     `gorm:"index" json:"last_used_at"`
 	CreatedAt    time.Time      `gorm:"not null" json:"created_at"`
@@ -145,7 +145,7 @@ func (a *Account) GetModelMapping() map[string]string {
 		return nil
 	}
 	// 处理map[string]interface{}类型
-	if m, ok := raw.(map[string]interface{}); ok {
+	if m, ok := raw.(map[string]any); ok {
 		result := make(map[string]string)
 		for k, v := range m {
 			if s, ok := v.(string); ok {
@@ -163,7 +163,7 @@ func (a *Account) GetModelMapping() map[string]string {
 // 如果没有设置模型映射，则支持所有模型
 func (a *Account) IsModelSupported(requestedModel string) bool {
 	mapping := a.GetModelMapping()
-	if mapping == nil || len(mapping) == 0 {
+	if len(mapping) == 0 {
 		return true // 没有映射配置，支持所有模型
 	}
 	_, exists := mapping[requestedModel]
@@ -174,7 +174,7 @@ func (a *Account) IsModelSupported(requestedModel string) bool {
 // 如果没有映射，返回原始模型名
 func (a *Account) GetMappedModel(requestedModel string) string {
 	mapping := a.GetModelMapping()
-	if mapping == nil || len(mapping) == 0 {
+	if len(mapping) == 0 {
 		return requestedModel
 	}
 	if mappedModel, exists := mapping[requestedModel]; exists {
@@ -231,7 +231,7 @@ func (a *Account) GetCustomErrorCodes() []int {
 		return nil
 	}
 	// 处理 []interface{} 类型（JSON反序列化后的格式）
-	if arr, ok := raw.([]interface{}); ok {
+	if arr, ok := raw.([]any); ok {
 		result := make([]int, 0, len(arr))
 		for _, v := range arr {
 			// JSON 数字默认解析为 float64
@@ -263,3 +263,17 @@ func (a *Account) ShouldHandleErrorCode(statusCode int) bool {
 	}
 	return false
 }
+
+// IsInterceptWarmupEnabled 检查是否启用预热请求拦截
+// 启用后，标题生成、Warmup等预热请求将返回mock响应，不消耗上游token
+func (a *Account) IsInterceptWarmupEnabled() bool {
+	if a.Credentials == nil {
+		return false
+	}
+	if v, ok := a.Credentials["intercept_warmup_requests"]; ok {
+		if enabled, ok := v.(bool); ok {
+			return enabled
+		}
+	}
+	return false
+}

backend/internal/model/group.go

@@ -13,13 +13,13 @@ const (
 )
 
 type Group struct {
-	ID             int64          `gorm:"primaryKey" json:"id"`
-	Name           string         `gorm:"uniqueIndex;size:100;not null" json:"name"`
-	Description    string         `gorm:"type:text" json:"description"`
-	Platform       string         `gorm:"size:50;default:anthropic;not null" json:"platform"` // anthropic/openai/gemini
-	RateMultiplier float64        `gorm:"type:decimal(10,4);default:1.0;not null" json:"rate_multiplier"`
-	IsExclusive    bool           `gorm:"default:false;not null" json:"is_exclusive"`
-	Status         string         `gorm:"size:20;default:active;not null" json:"status"` // active/disabled
+	ID             int64   `gorm:"primaryKey" json:"id"`
+	Name           string  `gorm:"uniqueIndex;size:100;not null" json:"name"`
+	Description    string  `gorm:"type:text" json:"description"`
+	Platform       string  `gorm:"size:50;default:anthropic;not null" json:"platform"` // anthropic/openai/gemini
+	RateMultiplier float64 `gorm:"type:decimal(10,4);default:1.0;not null" json:"rate_multiplier"`
+	IsExclusive    bool    `gorm:"default:false;not null" json:"is_exclusive"`
+	Status         string  `gorm:"size:20;default:active;not null" json:"status"` // active/disabled
 
 	// 订阅功能字段
 	SubscriptionType string   `gorm:"size:20;default:standard;not null" json:"subscription_type"` // standard/subscription

backend/internal/model/redeem_code.go

@@ -9,15 +9,15 @@ import (
 type RedeemCode struct {
 	ID        int64      `gorm:"primaryKey" json:"id"`
 	Code      string     `gorm:"uniqueIndex;size:32;not null" json:"code"`
-	Type      string     `gorm:"size:20;default:balance;not null" json:"type"` // balance/concurrency/subscription
-	Value     float64    `gorm:"type:decimal(20,8);not null" json:"value"`     // 面值(USD)或并发数或有效天数
+	Type      string     `gorm:"size:20;default:balance;not null" json:"type"`  // balance/concurrency/subscription
+	Value     float64    `gorm:"type:decimal(20,8);not null" json:"value"`      // 面值(USD)或并发数或有效天数
 	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"`
 	CreatedAt time.Time  `gorm:"not null" json:"created_at"`
 
 	// 订阅类型专用字段
-	GroupID      *int64 `gorm:"index" json:"group_id"`      // 订阅分组ID (仅subscription类型使用)
+	GroupID      *int64 `gorm:"index" json:"group_id"`           // 订阅分组ID (仅subscription类型使用)
 	ValidityDays int    `gorm:"default:30" json:"validity_days"` // 订阅有效天数 (仅subscription类型使用)
 
 	// 关联
@@ -40,8 +40,10 @@ func (r *RedeemCode) CanUse() bool {
 }
 
 // GenerateRedeemCode 生成唯一的兑换码
-func GenerateRedeemCode() string {
+func GenerateRedeemCode() (string, error) {
 	b := make([]byte, 16)
-	rand.Read(b)
-	return hex.EncodeToString(b)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
 }

backend/internal/model/setting.go

@@ -19,17 +19,17 @@ func (Setting) TableName() string {
 // 设置Key常量
 const (
 	// 注册设置
-	SettingKeyRegistrationEnabled = "registration_enabled"  // 是否开放注册
-	SettingKeyEmailVerifyEnabled  = "email_verify_enabled"  // 是否开启邮件验证
+	SettingKeyRegistrationEnabled = "registration_enabled" // 是否开放注册
+	SettingKeyEmailVerifyEnabled  = "email_verify_enabled" // 是否开启邮件验证
 
 	// 邮件服务设置
-	SettingKeySmtpHost     = "smtp_host"     // SMTP服务器地址
-	SettingKeySmtpPort     = "smtp_port"     // SMTP端口
-	SettingKeySmtpUsername = "smtp_username" // SMTP用户名
-	SettingKeySmtpPassword = "smtp_password" // SMTP密码（加密存储）
-	SettingKeySmtpFrom     = "smtp_from"     // 发件人地址
+	SettingKeySmtpHost     = "smtp_host"      // SMTP服务器地址
+	SettingKeySmtpPort     = "smtp_port"      // SMTP端口
+	SettingKeySmtpUsername = "smtp_username"  // SMTP用户名
+	SettingKeySmtpPassword = "smtp_password"  // SMTP密码（加密存储）
+	SettingKeySmtpFrom     = "smtp_from"      // 发件人地址
 	SettingKeySmtpFromName = "smtp_from_name" // 发件人名称
-	SettingKeySmtpUseTLS   = "smtp_use_tls"  // 是否使用TLS
+	SettingKeySmtpUseTLS   = "smtp_use_tls"   // 是否使用TLS
 
 	// Cloudflare Turnstile 设置
 	SettingKeyTurnstileEnabled   = "turnstile_enabled"    // 是否启用 Turnstile 验证
@@ -46,8 +46,14 @@ const (
 	// 默认配置
 	SettingKeyDefaultConcurrency = "default_concurrency" // 新用户默认并发量
 	SettingKeyDefaultBalance     = "default_balance"     // 新用户默认余额
+
+	// 管理员 API Key
+	SettingKeyAdminApiKey = "admin_api_key" // 全局管理员 API Key（用于外部系统集成）
 )
 
+// 管理员 API Key 前缀（与用户 sk- 前缀区分）
+const AdminApiKeyPrefix = "admin-"
+
 // SystemSettings 系统设置结构体（用于API响应）
 type SystemSettings struct {
 	// 注册设置

backend/internal/model/usage_log.go

@@ -37,7 +37,7 @@ type UsageLog struct {
 	OutputCost        float64 `gorm:"type:decimal(20,10);default:0;not null" json:"output_cost"`
 	CacheCreationCost float64 `gorm:"type:decimal(20,10);default:0;not null" json:"cache_creation_cost"`
 	CacheReadCost     float64 `gorm:"type:decimal(20,10);default:0;not null" json:"cache_read_cost"`
-	TotalCost         float64 `gorm:"type:decimal(20,10);default:0;not null" json:"total_cost"`      // 原始总费用
+	TotalCost         float64 `gorm:"type:decimal(20,10);default:0;not null" json:"total_cost"`     // 原始总费用
 	ActualCost        float64 `gorm:"type:decimal(20,10);default:0;not null" json:"actual_cost"`    // 实际扣除费用
 	RateMultiplier    float64 `gorm:"type:decimal(10,4);default:1;not null" json:"rate_multiplier"` // 计费倍率
 

backend/internal/model/user.go

@@ -9,8 +9,8 @@ import (
 )
 
 type User struct {
-	ID    int64  `gorm:"primaryKey" json:"id"`
-	Email string `gorm:"uniqueIndex;size:255;not null" json:"email"`
+	ID            int64          `gorm:"primaryKey" json:"id"`
+	Email         string         `gorm:"uniqueIndex;size:255;not null" json:"email"`
 	PasswordHash  string         `gorm:"size:255;not null" json:"-"`
 	Role          string         `gorm:"size:20;default:user;not null" json:"role"` // admin/user
 	Balance       float64        `gorm:"type:decimal(20,8);default:0;not null" json:"balance"`

backend/internal/pkg/claude/constants.go

@@ -0,0 +1,74 @@
+package claude
+
+// Claude Code 客户端相关常量
+
+// Beta header 常量
+const (
+	BetaOAuth                    = "oauth-2025-04-20"
+	BetaClaudeCode               = "claude-code-20250219"
+	BetaInterleavedThinking      = "interleaved-thinking-2025-05-14"
+	BetaFineGrainedToolStreaming = "fine-grained-tool-streaming-2025-05-14"
+)
+
+// DefaultBetaHeader Claude Code 客户端默认的 anthropic-beta header
+const DefaultBetaHeader = BetaClaudeCode + "," + BetaOAuth + "," + BetaInterleavedThinking + "," + BetaFineGrainedToolStreaming
+
+// HaikuBetaHeader Haiku 模型使用的 anthropic-beta header（不需要 claude-code beta）
+const HaikuBetaHeader = BetaOAuth + "," + BetaInterleavedThinking
+
+// Claude Code 客户端默认请求头
+var DefaultHeaders = map[string]string{
+	"User-Agent":                                "claude-cli/2.0.62 (external, cli)",
+	"X-Stainless-Lang":                          "js",
+	"X-Stainless-Package-Version":               "0.52.0",
+	"X-Stainless-OS":                            "Linux",
+	"X-Stainless-Arch":                          "x64",
+	"X-Stainless-Runtime":                       "node",
+	"X-Stainless-Runtime-Version":               "v22.14.0",
+	"X-Stainless-Retry-Count":                   "0",
+	"X-Stainless-Timeout":                       "60",
+	"X-App":                                     "cli",
+	"Anthropic-Dangerous-Direct-Browser-Access": "true",
+}
+
+// Model 表示一个 Claude 模型
+type Model struct {
+	ID          string `json:"id"`
+	Type        string `json:"type"`
+	DisplayName string `json:"display_name"`
+	CreatedAt   string `json:"created_at"`
+}
+
+// DefaultModels Claude Code 客户端支持的默认模型列表
+var DefaultModels = []Model{
+	{
+		ID:          "claude-opus-4-5-20251101",
+		Type:        "model",
+		DisplayName: "Claude Opus 4.5",
+		CreatedAt:   "2025-11-01T00:00:00Z",
+	},
+	{
+		ID:          "claude-sonnet-4-5-20250929",
+		Type:        "model",
+		DisplayName: "Claude Sonnet 4.5",
+		CreatedAt:   "2025-09-29T00:00:00Z",
+	},
+	{
+		ID:          "claude-haiku-4-5-20251001",
+		Type:        "model",
+		DisplayName: "Claude Haiku 4.5",
+		CreatedAt:   "2025-10-01T00:00:00Z",
+	},
+}
+
+// DefaultModelIDs 返回默认模型的 ID 列表
+func DefaultModelIDs() []string {
+	ids := make([]string, len(DefaultModels))
+	for i, m := range DefaultModels {
+		ids[i] = m.ID
+	}
+	return ids
+}
+
+// DefaultTestModel 测试时使用的默认模型
+const DefaultTestModel = "claude-sonnet-4-5-20250929"

backend/internal/pkg/pagination/pagination.go

@@ -0,0 +1,42 @@
+package pagination
+
+// PaginationParams 分页参数
+type PaginationParams struct {
+	Page     int
+	PageSize int
+}
+
+// PaginationResult 分页结果
+type PaginationResult struct {
+	Total    int64
+	Page     int
+	PageSize int
+	Pages    int
+}
+
+// DefaultPagination 默认分页参数
+func DefaultPagination() PaginationParams {
+	return PaginationParams{
+		Page:     1,
+		PageSize: 20,
+	}
+}
+
+// Offset 计算偏移量
+func (p PaginationParams) Offset() int {
+	if p.Page < 1 {
+		p.Page = 1
+	}
+	return (p.Page - 1) * p.PageSize
+}
+
+// Limit 获取限制数
+func (p PaginationParams) Limit() int {
+	if p.PageSize < 1 {
+		return 20
+	}
+	if p.PageSize > 100 {
+		return 100
+	}
+	return p.PageSize
+}

backend/internal/pkg/response/response.go

@@ -9,22 +9,22 @@ import (
 
 // Response 标准API响应格式
 type Response struct {
-	Code    int         `json:"code"`
-	Message string      `json:"message"`
-	Data    interface{} `json:"data,omitempty"`
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Data    any    `json:"data,omitempty"`
 }
 
 // PaginatedData 分页数据格式（匹配前端期望）
 type PaginatedData struct {
-	Items    interface{} `json:"items"`
-	Total    int64       `json:"total"`
-	Page     int         `json:"page"`
-	PageSize int         `json:"page_size"`
-	Pages    int         `json:"pages"`
+	Items    any   `json:"items"`
+	Total    int64 `json:"total"`
+	Page     int   `json:"page"`
+	PageSize int   `json:"page_size"`
+	Pages    int   `json:"pages"`
 }
 
 // Success 返回成功响应
-func Success(c *gin.Context, data interface{}) {
+func Success(c *gin.Context, data any) {
 	c.JSON(http.StatusOK, Response{
 		Code:    0,
 		Message: "success",
@@ -33,7 +33,7 @@ func Success(c *gin.Context, data interface{}) {
 }
 
 // Created 返回创建成功响应
-func Created(c *gin.Context, data interface{}) {
+func Created(c *gin.Context, data any) {
 	c.JSON(http.StatusCreated, Response{
 		Code:    0,
 		Message: "success",
@@ -75,7 +75,7 @@ func InternalError(c *gin.Context, message string) {
 }
 
 // Paginated 返回分页数据
-func Paginated(c *gin.Context, items interface{}, total int64, page, pageSize int) {
+func Paginated(c *gin.Context, items any, total int64, page, pageSize int) {
 	pages := int(math.Ceil(float64(total) / float64(pageSize)))
 	if pages < 1 {
 		pages = 1
@@ -90,7 +90,7 @@ func Paginated(c *gin.Context, items interface{}, total int64, page, pageSize in
 	})
 }
 
-// PaginationResult 分页结果（与repository.PaginationResult兼容）
+// PaginationResult 分页结果（与pagination.PaginationResult兼容）
 type PaginationResult struct {
 	Total    int64
 	Page     int
@@ -99,7 +99,7 @@ type PaginationResult struct {
 }
 
 // PaginatedWithResult 使用PaginationResult返回分页数据
-func PaginatedWithResult(c *gin.Context, items interface{}, pagination *PaginationResult) {
+func PaginatedWithResult(c *gin.Context, items any, pagination *PaginationResult) {
 	if pagination == nil {
 		Success(c, PaginatedData{
 			Items:    items,

backend/internal/pkg/timezone/timezone_test.go

@@ -37,11 +37,15 @@ func TestInitInvalidTimezone(t *testing.T) {
 
 func TestTimeNowAffected(t *testing.T) {
 	// Reset to UTC first
-	Init("UTC")
+	if err := Init("UTC"); err != nil {
+		t.Fatalf("Init failed with UTC: %v", err)
+	}
 	utcNow := time.Now()
 
 	// Switch to Shanghai (UTC+8)
-	Init("Asia/Shanghai")
+	if err := Init("Asia/Shanghai"); err != nil {
+		t.Fatalf("Init failed with Asia/Shanghai: %v", err)
+	}
 	shanghaiNow := time.Now()
 
 	// The times should be the same instant, but different timezone representation
@@ -58,7 +62,9 @@ func TestTimeNowAffected(t *testing.T) {
 }
 
 func TestToday(t *testing.T) {
-	Init("Asia/Shanghai")
+	if err := Init("Asia/Shanghai"); err != nil {
+		t.Fatalf("Init failed with Asia/Shanghai: %v", err)
+	}
 
 	today := Today()
 	now := Now()
@@ -75,7 +81,9 @@ func TestToday(t *testing.T) {
 }
 
 func TestStartOfDay(t *testing.T) {
-	Init("Asia/Shanghai")
+	if err := Init("Asia/Shanghai"); err != nil {
+		t.Fatalf("Init failed with Asia/Shanghai: %v", err)
+	}
 
 	// Create a time at 15:30:45
 	testTime := time.Date(2024, 6, 15, 15, 30, 45, 123456789, Location())
@@ -91,7 +99,9 @@ func TestTruncateVsStartOfDay(t *testing.T) {
 	// This test demonstrates why Truncate(24*time.Hour) can be problematic
 	// and why StartOfDay is more reliable for timezone-aware code
 
-	Init("Asia/Shanghai")
+	if err := Init("Asia/Shanghai"); err != nil {
+		t.Fatalf("Init failed with Asia/Shanghai: %v", err)
+	}
 
 	now := Now()
 

backend/internal/pkg/usagestats/account_stats.go

@@ -0,0 +1,8 @@
+package usagestats
+
+// AccountStats 账号使用统计
+type AccountStats struct {
+	Requests int64   `json:"requests"`
+	Tokens   int64   `json:"tokens"`
+	Cost     float64 `json:"cost"`
+}

backend/internal/repository/account_repo.go

@@ -3,6 +3,7 @@ package repository
 import (
 	"context"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 	"time"
 
 	"gorm.io/gorm"
@@ -47,12 +48,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 PaginationParams) ([]model.Account, *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 PaginationParams, platform, accountType, status, search string) ([]model.Account, *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
 
@@ -94,7 +95,7 @@ func (r *AccountRepository) ListWithFilters(ctx context.Context, params Paginati
 		pages++
 	}
 
-	return accounts, &PaginationResult{
+	return accounts, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -130,7 +131,7 @@ func (r *AccountRepository) UpdateLastUsed(ctx context.Context, id int64) 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]interface{}{
+		Updates(map[string]any{
 			"status":        model.StatusError,
 			"error_message": errorMsg,
 		}).Error
@@ -225,8 +226,8 @@ func (r *AccountRepository) ListSchedulableByGroupID(ctx context.Context, groupI
 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]interface{}{
-			"rate_limited_at":    now,
+		Updates(map[string]any{
+			"rate_limited_at":     now,
 			"rate_limit_reset_at": resetAt,
 		}).Error
 }
@@ -240,7 +241,7 @@ func (r *AccountRepository) SetOverloaded(ctx context.Context, id int64, until t
 // ClearRateLimit 清除账号的限流状态
 func (r *AccountRepository) ClearRateLimit(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Model(&model.Account{}).Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"rate_limited_at":     nil,
 			"rate_limit_reset_at": nil,
 			"overload_until":      nil,
@@ -249,7 +250,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 {
-	updates := map[string]interface{}{
+	updates := map[string]any{
 		"session_window_status": status,
 	}
 	if start != nil {

backend/internal/repository/api_key_cache.go

@@ -0,0 +1,51 @@
+package repository
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"sub2api/internal/service/ports"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	apiKeyRateLimitKeyPrefix = "apikey:ratelimit:"
+	apiKeyRateLimitDuration  = 24 * time.Hour
+)
+
+type apiKeyCache struct {
+	rdb *redis.Client
+}
+
+func NewApiKeyCache(rdb *redis.Client) ports.ApiKeyCache {
+	return &apiKeyCache{rdb: rdb}
+}
+
+func (c *apiKeyCache) GetCreateAttemptCount(ctx context.Context, userID int64) (int, error) {
+	key := fmt.Sprintf("%s%d", apiKeyRateLimitKeyPrefix, userID)
+	return c.rdb.Get(ctx, key).Int()
+}
+
+func (c *apiKeyCache) IncrementCreateAttemptCount(ctx context.Context, userID int64) error {
+	key := fmt.Sprintf("%s%d", apiKeyRateLimitKeyPrefix, userID)
+	pipe := c.rdb.Pipeline()
+	pipe.Incr(ctx, key)
+	pipe.Expire(ctx, key, apiKeyRateLimitDuration)
+	_, err := pipe.Exec(ctx)
+	return err
+}
+
+func (c *apiKeyCache) DeleteCreateAttemptCount(ctx context.Context, userID int64) error {
+	key := fmt.Sprintf("%s%d", apiKeyRateLimitKeyPrefix, userID)
+	return c.rdb.Del(ctx, key).Err()
+}
+
+func (c *apiKeyCache) IncrementDailyUsage(ctx context.Context, apiKey string) error {
+	return c.rdb.Incr(ctx, apiKey).Err()
+}
+
+func (c *apiKeyCache) SetDailyUsageExpiry(ctx context.Context, apiKey string, ttl time.Duration) error {
+	return c.rdb.Expire(ctx, apiKey, ttl).Err()
+}

backend/internal/repository/api_key_repo.go

@@ -3,6 +3,7 @@ package repository
 import (
 	"context"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
 )
@@ -45,7 +46,7 @@ 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 PaginationParams) ([]model.ApiKey, *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
 
@@ -64,7 +65,7 @@ func (r *ApiKeyRepository) ListByUserID(ctx context.Context, userID int64, param
 		pages++
 	}
 
-	return keys, &PaginationResult{
+	return keys, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -84,7 +85,7 @@ func (r *ApiKeyRepository) ExistsByKey(ctx context.Context, key string) (bool, e
 	return count > 0, err
 }
 
-func (r *ApiKeyRepository) ListByGroupID(ctx context.Context, groupID int64, params PaginationParams) ([]model.ApiKey, *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
 
@@ -103,7 +104,7 @@ func (r *ApiKeyRepository) ListByGroupID(ctx context.Context, groupID int64, par
 		pages++
 	}
 
-	return keys, &PaginationResult{
+	return keys, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),

backend/internal/repository/billing_cache.go

@@ -0,0 +1,174 @@
+package repository
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log"
+	"strconv"
+	"time"
+
+	"sub2api/internal/service/ports"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	billingBalanceKeyPrefix = "billing:balance:"
+	billingSubKeyPrefix     = "billing:sub:"
+	billingCacheTTL         = 5 * time.Minute
+)
+
+const (
+	subFieldStatus       = "status"
+	subFieldExpiresAt    = "expires_at"
+	subFieldDailyUsage   = "daily_usage"
+	subFieldWeeklyUsage  = "weekly_usage"
+	subFieldMonthlyUsage = "monthly_usage"
+	subFieldVersion      = "version"
+)
+
+var (
+	deductBalanceScript = redis.NewScript(`
+		local current = redis.call('GET', KEYS[1])
+		if current == false then
+			return 0
+		end
+		local newVal = tonumber(current) - tonumber(ARGV[1])
+		redis.call('SET', KEYS[1], newVal)
+		redis.call('EXPIRE', KEYS[1], ARGV[2])
+		return 1
+	`)
+
+	updateSubUsageScript = redis.NewScript(`
+		local exists = redis.call('EXISTS', KEYS[1])
+		if exists == 0 then
+			return 0
+		end
+		local cost = tonumber(ARGV[1])
+		redis.call('HINCRBYFLOAT', KEYS[1], 'daily_usage', cost)
+		redis.call('HINCRBYFLOAT', KEYS[1], 'weekly_usage', cost)
+		redis.call('HINCRBYFLOAT', KEYS[1], 'monthly_usage', cost)
+		redis.call('EXPIRE', KEYS[1], ARGV[2])
+		return 1
+	`)
+)
+
+type billingCache struct {
+	rdb *redis.Client
+}
+
+func NewBillingCache(rdb *redis.Client) ports.BillingCache {
+	return &billingCache{rdb: rdb}
+}
+
+func (c *billingCache) GetUserBalance(ctx context.Context, userID int64) (float64, error) {
+	key := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
+	val, err := c.rdb.Get(ctx, key).Result()
+	if err != nil {
+		return 0, err
+	}
+	return strconv.ParseFloat(val, 64)
+}
+
+func (c *billingCache) SetUserBalance(ctx context.Context, userID int64, balance float64) error {
+	key := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
+	return c.rdb.Set(ctx, key, balance, billingCacheTTL).Err()
+}
+
+func (c *billingCache) DeductUserBalance(ctx context.Context, userID int64, amount float64) error {
+	key := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
+	_, err := deductBalanceScript.Run(ctx, c.rdb, []string{key}, amount, int(billingCacheTTL.Seconds())).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		log.Printf("Warning: deduct balance cache failed for user %d: %v", userID, err)
+	}
+	return nil
+}
+
+func (c *billingCache) InvalidateUserBalance(ctx context.Context, userID int64) error {
+	key := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
+	return c.rdb.Del(ctx, key).Err()
+}
+
+func (c *billingCache) GetSubscriptionCache(ctx context.Context, userID, groupID int64) (*ports.SubscriptionCacheData, error) {
+	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
+	result, err := c.rdb.HGetAll(ctx, key).Result()
+	if err != nil {
+		return nil, err
+	}
+	if len(result) == 0 {
+		return nil, redis.Nil
+	}
+	return c.parseSubscriptionCache(result)
+}
+
+func (c *billingCache) parseSubscriptionCache(data map[string]string) (*ports.SubscriptionCacheData, error) {
+	result := &ports.SubscriptionCacheData{}
+
+	result.Status = data[subFieldStatus]
+	if result.Status == "" {
+		return nil, errors.New("invalid cache: missing status")
+	}
+
+	if expiresStr, ok := data[subFieldExpiresAt]; ok {
+		expiresAt, err := strconv.ParseInt(expiresStr, 10, 64)
+		if err == nil {
+			result.ExpiresAt = time.Unix(expiresAt, 0)
+		}
+	}
+
+	if dailyStr, ok := data[subFieldDailyUsage]; ok {
+		result.DailyUsage, _ = strconv.ParseFloat(dailyStr, 64)
+	}
+
+	if weeklyStr, ok := data[subFieldWeeklyUsage]; ok {
+		result.WeeklyUsage, _ = strconv.ParseFloat(weeklyStr, 64)
+	}
+
+	if monthlyStr, ok := data[subFieldMonthlyUsage]; ok {
+		result.MonthlyUsage, _ = strconv.ParseFloat(monthlyStr, 64)
+	}
+
+	if versionStr, ok := data[subFieldVersion]; ok {
+		result.Version, _ = strconv.ParseInt(versionStr, 10, 64)
+	}
+
+	return result, nil
+}
+
+func (c *billingCache) SetSubscriptionCache(ctx context.Context, userID, groupID int64, data *ports.SubscriptionCacheData) error {
+	if data == nil {
+		return nil
+	}
+
+	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
+
+	fields := map[string]any{
+		subFieldStatus:       data.Status,
+		subFieldExpiresAt:    data.ExpiresAt.Unix(),
+		subFieldDailyUsage:   data.DailyUsage,
+		subFieldWeeklyUsage:  data.WeeklyUsage,
+		subFieldMonthlyUsage: data.MonthlyUsage,
+		subFieldVersion:      data.Version,
+	}
+
+	pipe := c.rdb.Pipeline()
+	pipe.HSet(ctx, key, fields)
+	pipe.Expire(ctx, key, billingCacheTTL)
+	_, err := pipe.Exec(ctx)
+	return err
+}
+
+func (c *billingCache) UpdateSubscriptionUsage(ctx context.Context, userID, groupID int64, cost float64) error {
+	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
+	_, err := updateSubUsageScript.Run(ctx, c.rdb, []string{key}, cost, int(billingCacheTTL.Seconds())).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		log.Printf("Warning: update subscription usage cache failed for user %d group %d: %v", userID, groupID, err)
+	}
+	return nil
+}
+
+func (c *billingCache) InvalidateSubscriptionCache(ctx context.Context, userID, groupID int64) error {
+	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
+	return c.rdb.Del(ctx, key).Err()
+}

backend/internal/repository/claude_oauth_service.go

@@ -0,0 +1,235 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"net/url"
+	"time"
+
+	"sub2api/internal/pkg/oauth"
+	"sub2api/internal/service"
+
+	"github.com/imroc/req/v3"
+)
+
+type claudeOAuthService struct{}
+
+func NewClaudeOAuthClient() service.ClaudeOAuthClient {
+	return &claudeOAuthService{}
+}
+
+func (s *claudeOAuthService) GetOrganizationUUID(ctx context.Context, sessionKey, proxyURL string) (string, error) {
+	client := createReqClient(proxyURL)
+
+	var orgs []struct {
+		UUID string `json:"uuid"`
+	}
+
+	targetURL := "https://claude.ai/api/organizations"
+	log.Printf("[OAuth] Step 1: Getting organization UUID from %s", targetURL)
+
+	resp, err := client.R().
+		SetContext(ctx).
+		SetCookies(&http.Cookie{
+			Name:  "sessionKey",
+			Value: sessionKey,
+		}).
+		SetSuccessResult(&orgs).
+		Get(targetURL)
+
+	if err != nil {
+		log.Printf("[OAuth] Step 1 FAILED - Request error: %v", err)
+		return "", fmt.Errorf("request failed: %w", err)
+	}
+
+	log.Printf("[OAuth] Step 1 Response - Status: %d, Body: %s", resp.StatusCode, resp.String())
+
+	if !resp.IsSuccessState() {
+		return "", fmt.Errorf("failed to get organizations: status %d, body: %s", resp.StatusCode, resp.String())
+	}
+
+	if len(orgs) == 0 {
+		return "", fmt.Errorf("no organizations found")
+	}
+
+	log.Printf("[OAuth] Step 1 SUCCESS - Got org UUID: %s", orgs[0].UUID)
+	return orgs[0].UUID, nil
+}
+
+func (s *claudeOAuthService) GetAuthorizationCode(ctx context.Context, sessionKey, orgUUID, scope, codeChallenge, state, proxyURL string) (string, error) {
+	client := createReqClient(proxyURL)
+
+	authURL := fmt.Sprintf("https://claude.ai/v1/oauth/%s/authorize", orgUUID)
+
+	reqBody := map[string]any{
+		"response_type":         "code",
+		"client_id":             oauth.ClientID,
+		"organization_uuid":     orgUUID,
+		"redirect_uri":          oauth.RedirectURI,
+		"scope":                 scope,
+		"state":                 state,
+		"code_challenge":        codeChallenge,
+		"code_challenge_method": "S256",
+	}
+
+	reqBodyJSON, _ := json.Marshal(reqBody)
+	log.Printf("[OAuth] Step 2: Getting authorization code from %s", authURL)
+	log.Printf("[OAuth] Step 2 Request Body: %s", string(reqBodyJSON))
+
+	var result struct {
+		RedirectURI string `json:"redirect_uri"`
+	}
+
+	resp, err := client.R().
+		SetContext(ctx).
+		SetCookies(&http.Cookie{
+			Name:  "sessionKey",
+			Value: sessionKey,
+		}).
+		SetHeader("Accept", "application/json").
+		SetHeader("Accept-Language", "en-US,en;q=0.9").
+		SetHeader("Cache-Control", "no-cache").
+		SetHeader("Origin", "https://claude.ai").
+		SetHeader("Referer", "https://claude.ai/new").
+		SetHeader("Content-Type", "application/json").
+		SetBody(reqBody).
+		SetSuccessResult(&result).
+		Post(authURL)
+
+	if err != nil {
+		log.Printf("[OAuth] Step 2 FAILED - Request error: %v", err)
+		return "", fmt.Errorf("request failed: %w", err)
+	}
+
+	log.Printf("[OAuth] Step 2 Response - Status: %d, Body: %s", resp.StatusCode, resp.String())
+
+	if !resp.IsSuccessState() {
+		return "", fmt.Errorf("failed to get authorization code: status %d, body: %s", resp.StatusCode, resp.String())
+	}
+
+	if result.RedirectURI == "" {
+		return "", fmt.Errorf("no redirect_uri in response")
+	}
+
+	parsedURL, err := url.Parse(result.RedirectURI)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse redirect_uri: %w", err)
+	}
+
+	queryParams := parsedURL.Query()
+	authCode := queryParams.Get("code")
+	responseState := queryParams.Get("state")
+
+	if authCode == "" {
+		return "", fmt.Errorf("no authorization code in redirect_uri")
+	}
+
+	fullCode := authCode
+	if responseState != "" {
+		fullCode = authCode + "#" + responseState
+	}
+
+	log.Printf("[OAuth] Step 2 SUCCESS - Got authorization code: %s...", authCode[:20])
+	return fullCode, nil
+}
+
+func (s *claudeOAuthService) ExchangeCodeForToken(ctx context.Context, code, codeVerifier, state, proxyURL string) (*oauth.TokenResponse, error) {
+	client := createReqClient(proxyURL)
+
+	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
+		}
+	}
+
+	reqBody := map[string]any{
+		"code":          authCode,
+		"grant_type":    "authorization_code",
+		"client_id":     oauth.ClientID,
+		"redirect_uri":  oauth.RedirectURI,
+		"code_verifier": codeVerifier,
+	}
+
+	if codeState != "" {
+		reqBody["state"] = codeState
+	}
+
+	reqBodyJSON, _ := json.Marshal(reqBody)
+	log.Printf("[OAuth] Step 3: Exchanging code for token at %s", oauth.TokenURL)
+	log.Printf("[OAuth] Step 3 Request Body: %s", string(reqBodyJSON))
+
+	var tokenResp oauth.TokenResponse
+
+	resp, err := client.R().
+		SetContext(ctx).
+		SetHeader("Content-Type", "application/json").
+		SetBody(reqBody).
+		SetSuccessResult(&tokenResp).
+		Post(oauth.TokenURL)
+
+	if err != nil {
+		log.Printf("[OAuth] Step 3 FAILED - Request error: %v", err)
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+
+	log.Printf("[OAuth] Step 3 Response - Status: %d, Body: %s", resp.StatusCode, resp.String())
+
+	if !resp.IsSuccessState() {
+		return nil, fmt.Errorf("token exchange failed: status %d, body: %s", resp.StatusCode, resp.String())
+	}
+
+	log.Printf("[OAuth] Step 3 SUCCESS - Got access token")
+	return &tokenResp, nil
+}
+
+func (s *claudeOAuthService) RefreshToken(ctx context.Context, refreshToken, proxyURL string) (*oauth.TokenResponse, error) {
+	client := createReqClient(proxyURL)
+
+	formData := url.Values{}
+	formData.Set("grant_type", "refresh_token")
+	formData.Set("refresh_token", refreshToken)
+	formData.Set("client_id", oauth.ClientID)
+
+	var tokenResp oauth.TokenResponse
+
+	resp, err := client.R().
+		SetContext(ctx).
+		SetFormDataFromValues(formData).
+		SetSuccessResult(&tokenResp).
+		Post(oauth.TokenURL)
+
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+
+	if !resp.IsSuccessState() {
+		return nil, fmt.Errorf("token refresh failed: status %d, body: %s", resp.StatusCode, resp.String())
+	}
+
+	return &tokenResp, nil
+}
+
+func createReqClient(proxyURL string) *req.Client {
+	client := req.C().
+		ImpersonateChrome().
+		SetTimeout(60 * time.Second)
+
+	if proxyURL != "" {
+		client.SetProxyURL(proxyURL)
+	}
+
+	return client
+}

backend/internal/repository/claude_service.go

@@ -0,0 +1,64 @@
+package repository
+
+import (
+	"net/http"
+	"net/url"
+	"time"
+
+	"sub2api/internal/config"
+	"sub2api/internal/service"
+)
+
+type claudeUpstreamService struct {
+	defaultClient *http.Client
+	cfg           *config.Config
+}
+
+func NewClaudeUpstream(cfg *config.Config) service.ClaudeUpstream {
+	responseHeaderTimeout := time.Duration(cfg.Gateway.ResponseHeaderTimeout) * time.Second
+	if responseHeaderTimeout == 0 {
+		responseHeaderTimeout = 300 * time.Second
+	}
+
+	transport := &http.Transport{
+		MaxIdleConns:          100,
+		MaxIdleConnsPerHost:   10,
+		IdleConnTimeout:       90 * time.Second,
+		ResponseHeaderTimeout: responseHeaderTimeout,
+	}
+
+	return &claudeUpstreamService{
+		defaultClient: &http.Client{Transport: transport},
+		cfg:           cfg,
+	}
+}
+
+func (s *claudeUpstreamService) Do(req *http.Request, proxyURL string) (*http.Response, error) {
+	if proxyURL == "" {
+		return s.defaultClient.Do(req)
+	}
+	client := s.createProxyClient(proxyURL)
+	return client.Do(req)
+}
+
+func (s *claudeUpstreamService) createProxyClient(proxyURL string) *http.Client {
+	parsedURL, err := url.Parse(proxyURL)
+	if err != nil {
+		return s.defaultClient
+	}
+
+	responseHeaderTimeout := time.Duration(s.cfg.Gateway.ResponseHeaderTimeout) * time.Second
+	if responseHeaderTimeout == 0 {
+		responseHeaderTimeout = 300 * time.Second
+	}
+
+	transport := &http.Transport{
+		Proxy:                 http.ProxyURL(parsedURL),
+		MaxIdleConns:          100,
+		MaxIdleConnsPerHost:   10,
+		IdleConnTimeout:       90 * time.Second,
+		ResponseHeaderTimeout: responseHeaderTimeout,
+	}
+
+	return &http.Client{Transport: transport}
+}

backend/internal/repository/claude_usage_service.go

@@ -0,0 +1,63 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+
+	"sub2api/internal/service"
+)
+
+type claudeUsageService struct{}
+
+func NewClaudeUsageFetcher() service.ClaudeUsageFetcher {
+	return &claudeUsageService{}
+}
+
+func (s *claudeUsageService) FetchUsage(ctx context.Context, accessToken, proxyURL string) (*service.ClaudeUsageResponse, error) {
+	transport, ok := http.DefaultTransport.(*http.Transport)
+	if !ok {
+		return nil, fmt.Errorf("failed to get default transport")
+	}
+	transport = transport.Clone()
+	if proxyURL != "" {
+		if parsedURL, err := url.Parse(proxyURL); err == nil {
+			transport.Proxy = http.ProxyURL(parsedURL)
+		}
+	}
+
+	client := &http.Client{
+		Transport: transport,
+		Timeout:   30 * time.Second,
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "GET", "https://api.anthropic.com/api/oauth/usage", nil)
+	if err != nil {
+		return nil, fmt.Errorf("create request failed: %w", err)
+	}
+
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+	req.Header.Set("anthropic-beta", "oauth-2025-04-20")
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("API returned status %d: %s", resp.StatusCode, string(body))
+	}
+
+	var usageResp service.ClaudeUsageResponse
+	if err := json.NewDecoder(resp.Body).Decode(&usageResp); err != nil {
+		return nil, fmt.Errorf("decode response failed: %w", err)
+	}
+
+	return &usageResp, nil
+}

backend/internal/repository/concurrency_cache.go

@@ -0,0 +1,132 @@
+package repository
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"sub2api/internal/service/ports"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	accountConcurrencyKeyPrefix = "concurrency:account:"
+	userConcurrencyKeyPrefix    = "concurrency:user:"
+	waitQueueKeyPrefix          = "concurrency:wait:"
+	concurrencyTTL              = 5 * time.Minute
+)
+
+var (
+	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])
+			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
+	`)
+
+	incrementWaitScript = redis.NewScript(`
+		local waitKey = KEYS[1]
+		local maxWait = tonumber(ARGV[1])
+		local ttl = tonumber(ARGV[2])
+		local current = redis.call('GET', waitKey)
+		if current == false then
+			current = 0
+		else
+			current = tonumber(current)
+		end
+		if current >= maxWait then
+			return 0
+		end
+		redis.call('INCR', waitKey)
+		redis.call('EXPIRE', waitKey, ttl)
+		return 1
+	`)
+
+	decrementWaitScript = 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
+	`)
+)
+
+type concurrencyCache struct {
+	rdb *redis.Client
+}
+
+func NewConcurrencyCache(rdb *redis.Client) ports.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()
+	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) GetAccountConcurrency(ctx context.Context, accountID int64) (int, error) {
+	key := fmt.Sprintf("%s%d", accountConcurrencyKeyPrefix, accountID)
+	return c.rdb.Get(ctx, key).Int()
+}
+
+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()
+	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) GetUserConcurrency(ctx context.Context, userID int64) (int, error) {
+	key := fmt.Sprintf("%s%d", userConcurrencyKeyPrefix, userID)
+	return c.rdb.Get(ctx, key).Int()
+}
+
+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()
+	if err != nil {
+		return false, err
+	}
+	return result == 1, nil
+}
+
+func (c *concurrencyCache) DecrementWaitCount(ctx context.Context, userID int64) error {
+	key := fmt.Sprintf("%s%d", waitQueueKeyPrefix, userID)
+	_, err := decrementWaitScript.Run(ctx, c.rdb, []string{key}).Result()
+	return err
+}

backend/internal/repository/email_cache.go

@@ -0,0 +1,48 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"sub2api/internal/service/ports"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const verifyCodeKeyPrefix = "verify_code:"
+
+type emailCache struct {
+	rdb *redis.Client
+}
+
+func NewEmailCache(rdb *redis.Client) ports.EmailCache {
+	return &emailCache{rdb: rdb}
+}
+
+func (c *emailCache) GetVerificationCode(ctx context.Context, email string) (*ports.VerificationCodeData, error) {
+	key := verifyCodeKeyPrefix + email
+	val, err := c.rdb.Get(ctx, key).Result()
+	if err != nil {
+		return nil, err
+	}
+	var data ports.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 {
+	key := verifyCodeKeyPrefix + email
+	val, err := json.Marshal(data)
+	if err != nil {
+		return err
+	}
+	return c.rdb.Set(ctx, key, val, ttl).Err()
+}
+
+func (c *emailCache) DeleteVerificationCode(ctx context.Context, email string) error {
+	key := verifyCodeKeyPrefix + email
+	return c.rdb.Del(ctx, key).Err()
+}

backend/internal/repository/gateway_cache.go

@@ -0,0 +1,35 @@
+package repository
+
+import (
+	"context"
+	"time"
+
+	"sub2api/internal/service/ports"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const stickySessionPrefix = "sticky_session:"
+
+type gatewayCache struct {
+	rdb *redis.Client
+}
+
+func NewGatewayCache(rdb *redis.Client) ports.GatewayCache {
+	return &gatewayCache{rdb: rdb}
+}
+
+func (c *gatewayCache) GetSessionAccountID(ctx context.Context, sessionHash string) (int64, error) {
+	key := stickySessionPrefix + sessionHash
+	return c.rdb.Get(ctx, key).Int64()
+}
+
+func (c *gatewayCache) SetSessionAccountID(ctx context.Context, sessionHash string, accountID int64, ttl time.Duration) error {
+	key := stickySessionPrefix + sessionHash
+	return c.rdb.Set(ctx, key, accountID, ttl).Err()
+}
+
+func (c *gatewayCache) RefreshSessionTTL(ctx context.Context, sessionHash string, ttl time.Duration) error {
+	key := stickySessionPrefix + sessionHash
+	return c.rdb.Expire(ctx, key, ttl).Err()
+}

backend/internal/repository/github_release_service.go

@@ -0,0 +1,116 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"time"
+
+	"sub2api/internal/service"
+)
+
+type githubReleaseClient struct {
+	httpClient *http.Client
+}
+
+func NewGitHubReleaseClient() service.GitHubReleaseClient {
+	return &githubReleaseClient{
+		httpClient: &http.Client{
+			Timeout: 30 * time.Second,
+		},
+	}
+}
+
+func (c *githubReleaseClient) FetchLatestRelease(ctx context.Context, repo string) (*service.GitHubRelease, error) {
+	url := fmt.Sprintf("https://api.github.com/repos/%s/releases/latest", repo)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Accept", "application/vnd.github.v3+json")
+	req.Header.Set("User-Agent", "Sub2API-Updater")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("GitHub API returned %d", resp.StatusCode)
+	}
+
+	var release service.GitHubRelease
+	if err := json.NewDecoder(resp.Body).Decode(&release); err != nil {
+		return nil, err
+	}
+
+	return &release, nil
+}
+
+func (c *githubReleaseClient) DownloadFile(ctx context.Context, url, dest string, maxSize int64) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return err
+	}
+
+	client := &http.Client{Timeout: 10 * time.Minute}
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("download returned %d", resp.StatusCode)
+	}
+
+	// SECURITY: Check Content-Length if available
+	if resp.ContentLength > maxSize {
+		return fmt.Errorf("file too large: %d bytes (max %d)", resp.ContentLength, maxSize)
+	}
+
+	out, err := os.Create(dest)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = out.Close() }()
+
+	// SECURITY: Use LimitReader to enforce max download size even if Content-Length is missing/wrong
+	limited := io.LimitReader(resp.Body, maxSize+1)
+	written, err := io.Copy(out, limited)
+	if err != nil {
+		return err
+	}
+
+	// Check if we hit the limit (downloaded more than maxSize)
+	if written > maxSize {
+		_ = os.Remove(dest) // Clean up partial file (best-effort)
+		return fmt.Errorf("download exceeded maximum size of %d bytes", maxSize)
+	}
+
+	return nil
+}
+
+func (c *githubReleaseClient) FetchChecksumFile(ctx context.Context, url string) ([]byte, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	return io.ReadAll(resp.Body)
+}

backend/internal/repository/group_repo.go

@@ -3,6 +3,7 @@ package repository
 import (
 	"context"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
 )
@@ -36,12 +37,12 @@ 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 PaginationParams) ([]model.Group, *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 PaginationParams, platform, status string, isExclusive *bool) ([]model.Group, *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
 
@@ -77,7 +78,7 @@ func (r *GroupRepository) ListWithFilters(ctx context.Context, params Pagination
 		pages++
 	}
 
-	return groups, &PaginationResult{
+	return groups, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),

backend/internal/repository/identity_cache.go

@@ -0,0 +1,47 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"sub2api/internal/service/ports"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	fingerprintKeyPrefix = "fingerprint:"
+	fingerprintTTL       = 24 * time.Hour
+)
+
+type identityCache struct {
+	rdb *redis.Client
+}
+
+func NewIdentityCache(rdb *redis.Client) ports.IdentityCache {
+	return &identityCache{rdb: rdb}
+}
+
+func (c *identityCache) GetFingerprint(ctx context.Context, accountID int64) (*ports.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
+	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 {
+	key := fmt.Sprintf("%s%d", fingerprintKeyPrefix, accountID)
+	val, err := json.Marshal(fp)
+	if err != nil {
+		return err
+	}
+	return c.rdb.Set(ctx, key, val, fingerprintTTL).Err()
+}

backend/internal/repository/pricing_service.go

@@ -0,0 +1,73 @@
+package repository
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"sub2api/internal/service"
+)
+
+type pricingRemoteClient struct {
+	httpClient *http.Client
+}
+
+func NewPricingRemoteClient() service.PricingRemoteClient {
+	return &pricingRemoteClient{
+		httpClient: &http.Client{
+			Timeout: 30 * time.Second,
+		},
+	}
+}
+
+func (c *pricingRemoteClient) FetchPricingJSON(ctx context.Context, url string) ([]byte, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	return io.ReadAll(resp.Body)
+}
+
+func (c *pricingRemoteClient) FetchHashText(ctx context.Context, url string) (string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return "", err
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", err
+	}
+
+	// 哈希文件格式：hash  filename 或者纯 hash
+	hash := strings.TrimSpace(string(body))
+	parts := strings.Fields(hash)
+	if len(parts) > 0 {
+		return parts[0], nil
+	}
+	return hash, nil
+}

backend/internal/repository/proxy_probe_service.go

@@ -0,0 +1,104 @@
+package repository
+
+import (
+	"context"
+	"crypto/tls"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"time"
+
+	"sub2api/internal/service"
+
+	"golang.org/x/net/proxy"
+)
+
+type proxyProbeService struct{}
+
+func NewProxyExitInfoProber() service.ProxyExitInfoProber {
+	return &proxyProbeService{}
+}
+
+func (s *proxyProbeService) ProbeProxy(ctx context.Context, proxyURL string) (*service.ProxyExitInfo, int64, error) {
+	transport, err := createProxyTransport(proxyURL)
+	if err != nil {
+		return nil, 0, fmt.Errorf("failed to create proxy transport: %w", err)
+	}
+
+	client := &http.Client{
+		Transport: transport,
+		Timeout:   15 * time.Second,
+	}
+
+	startTime := time.Now()
+	req, err := http.NewRequestWithContext(ctx, "GET", "https://ipinfo.io/json", nil)
+	if err != nil {
+		return nil, 0, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, 0, fmt.Errorf("proxy connection failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	latencyMs := time.Since(startTime).Milliseconds()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, latencyMs, fmt.Errorf("request failed with status: %d", resp.StatusCode)
+	}
+
+	var ipInfo struct {
+		IP      string `json:"ip"`
+		City    string `json:"city"`
+		Region  string `json:"region"`
+		Country string `json:"country"`
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, latencyMs, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if err := json.Unmarshal(body, &ipInfo); err != nil {
+		return nil, latencyMs, fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	return &service.ProxyExitInfo{
+		IP:      ipInfo.IP,
+		City:    ipInfo.City,
+		Region:  ipInfo.Region,
+		Country: ipInfo.Country,
+	}, latencyMs, nil
+}
+
+func createProxyTransport(proxyURL string) (*http.Transport, error) {
+	parsedURL, err := url.Parse(proxyURL)
+	if err != nil {
+		return nil, fmt.Errorf("invalid proxy URL: %w", err)
+	}
+
+	transport := &http.Transport{
+		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
+	}
+
+	switch parsedURL.Scheme {
+	case "http", "https":
+		transport.Proxy = http.ProxyURL(parsedURL)
+	case "socks5":
+		dialer, err := proxy.FromURL(parsedURL, proxy.Direct)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create socks5 dialer: %w", err)
+		}
+		transport.DialContext = func(ctx context.Context, network, addr string) (net.Conn, error) {
+			return dialer.Dial(network, addr)
+		}
+	default:
+		return nil, fmt.Errorf("unsupported proxy protocol: %s", parsedURL.Scheme)
+	}
+
+	return transport, nil
+}

backend/internal/repository/proxy_repo.go

@@ -3,6 +3,7 @@ package repository
 import (
 	"context"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
 )
@@ -36,12 +37,12 @@ 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 PaginationParams) ([]model.Proxy, *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 PaginationParams, protocol, status, search string) ([]model.Proxy, *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
 
@@ -72,7 +73,7 @@ func (r *ProxyRepository) ListWithFilters(ctx context.Context, params Pagination
 		pages++
 	}
 
-	return proxies, &PaginationResult{
+	return proxies, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),

backend/internal/repository/redeem_cache.go

@@ -0,0 +1,49 @@
+package repository
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"sub2api/internal/service/ports"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	redeemRateLimitKeyPrefix = "redeem:ratelimit:"
+	redeemLockKeyPrefix      = "redeem:lock:"
+	redeemRateLimitDuration  = 24 * time.Hour
+)
+
+type redeemCache struct {
+	rdb *redis.Client
+}
+
+func NewRedeemCache(rdb *redis.Client) ports.RedeemCache {
+	return &redeemCache{rdb: rdb}
+}
+
+func (c *redeemCache) GetRedeemAttemptCount(ctx context.Context, userID int64) (int, error) {
+	key := fmt.Sprintf("%s%d", redeemRateLimitKeyPrefix, userID)
+	return c.rdb.Get(ctx, key).Int()
+}
+
+func (c *redeemCache) IncrementRedeemAttemptCount(ctx context.Context, userID int64) error {
+	key := fmt.Sprintf("%s%d", redeemRateLimitKeyPrefix, userID)
+	pipe := c.rdb.Pipeline()
+	pipe.Incr(ctx, key)
+	pipe.Expire(ctx, key, redeemRateLimitDuration)
+	_, err := pipe.Exec(ctx)
+	return err
+}
+
+func (c *redeemCache) AcquireRedeemLock(ctx context.Context, code string, ttl time.Duration) (bool, error) {
+	key := redeemLockKeyPrefix + code
+	return c.rdb.SetNX(ctx, key, 1, ttl).Result()
+}
+
+func (c *redeemCache) ReleaseRedeemLock(ctx context.Context, code string) error {
+	key := redeemLockKeyPrefix + code
+	return c.rdb.Del(ctx, key).Err()
+}

backend/internal/repository/redeem_code_repo.go

@@ -3,6 +3,7 @@ package repository
 import (
 	"context"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 	"time"
 
 	"gorm.io/gorm"
@@ -46,12 +47,12 @@ 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 PaginationParams) ([]model.RedeemCode, *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 PaginationParams, codeType, status, search string) ([]model.RedeemCode, *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
 
@@ -82,7 +83,7 @@ func (r *RedeemCodeRepository) ListWithFilters(ctx context.Context, params Pagin
 		pages++
 	}
 
-	return codes, &PaginationResult{
+	return codes, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -98,7 +99,7 @@ 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).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"status":  model.StatusUsed,
 			"used_by": userID,
 			"used_at": now,

backend/internal/repository/repository.go

@@ -12,44 +12,3 @@ type Repositories struct {
 	Setting          *SettingRepository
 	UserSubscription *UserSubscriptionRepository
 }
-
-// PaginationParams 分页参数
-type PaginationParams struct {
-	Page     int
-	PageSize int
-}
-
-// PaginationResult 分页结果
-type PaginationResult struct {
-	Total    int64
-	Page     int
-	PageSize int
-	Pages    int
-}
-
-// DefaultPagination 默认分页参数
-func DefaultPagination() PaginationParams {
-	return PaginationParams{
-		Page:     1,
-		PageSize: 20,
-	}
-}
-
-// Offset 计算偏移量
-func (p PaginationParams) Offset() int {
-	if p.Page < 1 {
-		p.Page = 1
-	}
-	return (p.Page - 1) * p.PageSize
-}
-
-// Limit 获取限制数
-func (p PaginationParams) Limit() int {
-	if p.PageSize < 1 {
-		return 20
-	}
-	if p.PageSize > 100 {
-		return 100
-	}
-	return p.PageSize
-}

backend/internal/repository/turnstile_service.go

@@ -0,0 +1,55 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"sub2api/internal/service"
+)
+
+const turnstileVerifyURL = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
+
+type turnstileVerifier struct {
+	httpClient *http.Client
+}
+
+func NewTurnstileVerifier() service.TurnstileVerifier {
+	return &turnstileVerifier{
+		httpClient: &http.Client{
+			Timeout: 10 * time.Second,
+		},
+	}
+}
+
+func (v *turnstileVerifier) VerifyToken(ctx context.Context, secretKey, token, remoteIP string) (*service.TurnstileVerifyResponse, error) {
+	formData := url.Values{}
+	formData.Set("secret", secretKey)
+	formData.Set("response", token)
+	if remoteIP != "" {
+		formData.Set("remoteip", remoteIP)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, turnstileVerifyURL, strings.NewReader(formData.Encode()))
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := v.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("send request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	var result service.TurnstileVerifyResponse
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode response: %w", err)
+	}
+
+	return &result, nil
+}

backend/internal/repository/update_cache.go

@@ -0,0 +1,28 @@
+package repository
+
+import (
+	"context"
+	"time"
+
+	"sub2api/internal/service/ports"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const updateCacheKey = "update:latest"
+
+type updateCache struct {
+	rdb *redis.Client
+}
+
+func NewUpdateCache(rdb *redis.Client) ports.UpdateCache {
+	return &updateCache{rdb: rdb}
+}
+
+func (c *updateCache) GetUpdateInfo(ctx context.Context) (string, error) {
+	return c.rdb.Get(ctx, updateCacheKey).Result()
+}
+
+func (c *updateCache) SetUpdateInfo(ctx context.Context, data string, ttl time.Duration) error {
+	return c.rdb.Set(ctx, updateCacheKey, data, ttl).Err()
+}

backend/internal/repository/usage_log_repo.go

@@ -3,7 +3,9 @@ package repository
 import (
 	"context"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 	"sub2api/internal/pkg/timezone"
+	"sub2api/internal/pkg/usagestats"
 	"time"
 
 	"gorm.io/gorm"
@@ -30,7 +32,7 @@ func (r *UsageLogRepository) GetByID(ctx context.Context, id int64) (*model.Usag
 	return &log, nil
 }
 
-func (r *UsageLogRepository) ListByUser(ctx context.Context, userID int64, params PaginationParams) ([]model.UsageLog, *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
 
@@ -49,7 +51,7 @@ func (r *UsageLogRepository) ListByUser(ctx context.Context, userID int64, param
 		pages++
 	}
 
-	return logs, &PaginationResult{
+	return logs, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -57,7 +59,7 @@ func (r *UsageLogRepository) ListByUser(ctx context.Context, userID int64, param
 	}, nil
 }
 
-func (r *UsageLogRepository) ListByApiKey(ctx context.Context, apiKeyID int64, params PaginationParams) ([]model.UsageLog, *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
 
@@ -76,7 +78,7 @@ func (r *UsageLogRepository) ListByApiKey(ctx context.Context, apiKeyID int64, p
 		pages++
 	}
 
-	return logs, &PaginationResult{
+	return logs, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -270,7 +272,7 @@ func (r *UsageLogRepository) GetDashboardStats(ctx context.Context) (*DashboardS
 	return &stats, nil
 }
 
-func (r *UsageLogRepository) ListByAccount(ctx context.Context, accountID int64, params PaginationParams) ([]model.UsageLog, *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
 
@@ -289,7 +291,7 @@ func (r *UsageLogRepository) ListByAccount(ctx context.Context, accountID int64,
 		pages++
 	}
 
-	return logs, &PaginationResult{
+	return logs, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -297,7 +299,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, *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).
@@ -306,7 +308,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, *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).
@@ -315,7 +317,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, *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).
@@ -324,7 +326,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, *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).
@@ -337,15 +339,8 @@ func (r *UsageLogRepository) Delete(ctx context.Context, id int64) error {
 	return r.db.WithContext(ctx).Delete(&model.UsageLog{}, id).Error
 }
 
-// AccountStats 账号使用统计
-type AccountStats struct {
-	Requests int64   `json:"requests"`
-	Tokens   int64   `json:"tokens"`
-	Cost     float64 `json:"cost"`
-}
-
 // GetAccountTodayStats 获取账号今日统计
-func (r *UsageLogRepository) GetAccountTodayStats(ctx context.Context, accountID int64) (*AccountStats, error) {
+func (r *UsageLogRepository) GetAccountTodayStats(ctx context.Context, accountID int64) (*usagestats.AccountStats, error) {
 	today := timezone.Today()
 
 	var stats struct {
@@ -367,7 +362,7 @@ func (r *UsageLogRepository) GetAccountTodayStats(ctx context.Context, accountID
 		return nil, err
 	}
 
-	return &AccountStats{
+	return &usagestats.AccountStats{
 		Requests: stats.Requests,
 		Tokens:   stats.Tokens,
 		Cost:     stats.Cost,
@@ -375,7 +370,7 @@ func (r *UsageLogRepository) GetAccountTodayStats(ctx context.Context, accountID
 }
 
 // GetAccountWindowStats 获取账号时间窗口内的统计
-func (r *UsageLogRepository) GetAccountWindowStats(ctx context.Context, accountID int64, startTime time.Time) (*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"`
@@ -395,7 +390,7 @@ func (r *UsageLogRepository) GetAccountWindowStats(ctx context.Context, accountI
 		return nil, err
 	}
 
-	return &AccountStats{
+	return &usagestats.AccountStats{
 		Requests: stats.Requests,
 		Tokens:   stats.Tokens,
 		Cost:     stats.Cost,
@@ -436,75 +431,13 @@ type UserUsageTrendPoint struct {
 	ActualCost float64 `json:"actual_cost"` // 实际扣除
 }
 
-// GetUsageTrend returns usage trend data grouped by date
-// granularity: "day" or "hour"
-func (r *UsageLogRepository) GetUsageTrend(ctx context.Context, startTime, endTime time.Time, granularity string) ([]TrendDataPoint, error) {
-	var results []TrendDataPoint
-
-	// Choose date format based on granularity
-	var dateFormat string
-	if granularity == "hour" {
-		dateFormat = "YYYY-MM-DD HH24:00"
-	} else {
-		dateFormat = "YYYY-MM-DD"
-	}
-
-	err := r.db.WithContext(ctx).Model(&model.UsageLog{}).
-		Select(`
-			TO_CHAR(created_at, ?) as date,
-			COUNT(*) as requests,
-			COALESCE(SUM(input_tokens), 0) as input_tokens,
-			COALESCE(SUM(output_tokens), 0) as output_tokens,
-			COALESCE(SUM(cache_creation_tokens + cache_read_tokens), 0) as cache_tokens,
-			COALESCE(SUM(input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens), 0) as total_tokens,
-			COALESCE(SUM(total_cost), 0) as cost,
-			COALESCE(SUM(actual_cost), 0) as actual_cost
-		`, dateFormat).
-		Where("created_at >= ? AND created_at < ?", startTime, endTime).
-		Group("date").
-		Order("date ASC").
-		Scan(&results).Error
-
-	if err != nil {
-		return nil, err
-	}
-
-	return results, nil
-}
-
-// GetModelStats returns usage statistics grouped by model
-func (r *UsageLogRepository) GetModelStats(ctx context.Context, startTime, endTime time.Time) ([]ModelStat, error) {
-	var results []ModelStat
-
-	err := r.db.WithContext(ctx).Model(&model.UsageLog{}).
-		Select(`
-			model,
-			COUNT(*) as requests,
-			COALESCE(SUM(input_tokens), 0) as input_tokens,
-			COALESCE(SUM(output_tokens), 0) as output_tokens,
-			COALESCE(SUM(input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens), 0) as total_tokens,
-			COALESCE(SUM(total_cost), 0) as cost,
-			COALESCE(SUM(actual_cost), 0) as actual_cost
-		`).
-		Where("created_at >= ? AND created_at < ?", startTime, endTime).
-		Group("model").
-		Order("total_tokens DESC").
-		Scan(&results).Error
-
-	if err != nil {
-		return nil, err
-	}
-
-	return results, nil
-}
-
 // 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"`
+	Date     string `json:"date"`
+	ApiKeyID int64  `json:"api_key_id"`
+	KeyName  string `json:"key_name"`
+	Requests int64  `json:"requests"`
+	Tokens   int64  `json:"tokens"`
 }
 
 // GetApiKeyUsageTrend returns usage trend data grouped by API key and date
@@ -780,7 +713,7 @@ type UsageLogFilters struct {
 }
 
 // ListWithFilters lists usage logs with optional filters (for admin)
-func (r *UsageLogRepository) ListWithFilters(ctx context.Context, params PaginationParams, filters UsageLogFilters) ([]model.UsageLog, *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
 
@@ -816,7 +749,7 @@ func (r *UsageLogRepository) ListWithFilters(ctx context.Context, params Paginat
 		pages++
 	}
 
-	return logs, &PaginationResult{
+	return logs, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -838,7 +771,7 @@ type UsageStats struct {
 
 // BatchUserUsageStats represents usage stats for a single user
 type BatchUserUsageStats struct {
-	UserID         int64   `json:"user_id"`
+	UserID          int64   `json:"user_id"`
 	TodayActualCost float64 `json:"today_actual_cost"`
 	TotalActualCost float64 `json:"total_actual_cost"`
 }
@@ -964,6 +897,76 @@ func (r *UsageLogRepository) GetBatchApiKeyUsageStats(ctx context.Context, apiKe
 	return result, nil
 }
 
+// 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) {
+	var results []TrendDataPoint
+
+	var dateFormat string
+	if granularity == "hour" {
+		dateFormat = "YYYY-MM-DD HH24:00"
+	} else {
+		dateFormat = "YYYY-MM-DD"
+	}
+
+	db := r.db.WithContext(ctx).Model(&model.UsageLog{}).
+		Select(`
+			TO_CHAR(created_at, ?) as date,
+			COUNT(*) as requests,
+			COALESCE(SUM(input_tokens), 0) as input_tokens,
+			COALESCE(SUM(output_tokens), 0) as output_tokens,
+			COALESCE(SUM(cache_creation_tokens + cache_read_tokens), 0) as cache_tokens,
+			COALESCE(SUM(input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens), 0) as total_tokens,
+			COALESCE(SUM(total_cost), 0) as cost,
+			COALESCE(SUM(actual_cost), 0) as actual_cost
+		`, dateFormat).
+		Where("created_at >= ? AND created_at < ?", startTime, endTime)
+
+	if userID > 0 {
+		db = db.Where("user_id = ?", userID)
+	}
+	if apiKeyID > 0 {
+		db = db.Where("api_key_id = ?", apiKeyID)
+	}
+
+	err := db.Group("date").Order("date ASC").Scan(&results).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return results, nil
+}
+
+// GetModelStatsWithFilters returns model statistics with optional user/api_key filters
+func (r *UsageLogRepository) GetModelStatsWithFilters(ctx context.Context, startTime, endTime time.Time, userID, apiKeyID int64) ([]ModelStat, error) {
+	var results []ModelStat
+
+	db := r.db.WithContext(ctx).Model(&model.UsageLog{}).
+		Select(`
+			model,
+			COUNT(*) as requests,
+			COALESCE(SUM(input_tokens), 0) as input_tokens,
+			COALESCE(SUM(output_tokens), 0) as output_tokens,
+			COALESCE(SUM(input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens), 0) as total_tokens,
+			COALESCE(SUM(total_cost), 0) as cost,
+			COALESCE(SUM(actual_cost), 0) as actual_cost
+		`).
+		Where("created_at >= ? AND created_at < ?", startTime, endTime)
+
+	if userID > 0 {
+		db = db.Where("user_id = ?", userID)
+	}
+	if apiKeyID > 0 {
+		db = db.Where("api_key_id = ?", apiKeyID)
+	}
+
+	err := db.Group("model").Order("total_tokens DESC").Scan(&results).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return results, nil
+}
+
 // GetGlobalStats gets usage statistics for all users within a time range
 func (r *UsageLogRepository) GetGlobalStats(ctx context.Context, startTime, endTime time.Time) (*UsageStats, error) {
 	var stats struct {

backend/internal/repository/user_repo.go

@@ -3,6 +3,7 @@ package repository
 import (
 	"context"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
 )
@@ -45,12 +46,12 @@ 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 PaginationParams) ([]model.User, *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 PaginationParams, status, role, search string) ([]model.User, *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
 
@@ -81,7 +82,7 @@ func (r *UserRepository) ListWithFilters(ctx context.Context, params PaginationP
 		pages++
 	}
 
-	return users, &PaginationResult{
+	return users, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -128,3 +129,15 @@ func (r *UserRepository) RemoveGroupFromAllowedGroups(ctx context.Context, group
 	return result.RowsAffected, result.Error
 }
 
+// GetFirstAdmin 获取第一个管理员用户（用于 Admin API Key 认证）
+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 &user, nil
+}

backend/internal/repository/user_subscription_repo.go

@@ -5,6 +5,7 @@ import (
 	"time"
 
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 
 	"gorm.io/gorm"
 )
@@ -100,7 +101,7 @@ func (r *UserSubscriptionRepository) ListActiveByUserID(ctx context.Context, use
 }
 
 // ListByGroupID 获取分组的所有订阅（分页）
-func (r *UserSubscriptionRepository) ListByGroupID(ctx context.Context, groupID int64, params PaginationParams) ([]model.UserSubscription, *PaginationResult, error) {
+func (r *UserSubscriptionRepository) ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]model.UserSubscription, *pagination.PaginationResult, error) {
 	var subs []model.UserSubscription
 	var total int64
 
@@ -126,7 +127,7 @@ func (r *UserSubscriptionRepository) ListByGroupID(ctx context.Context, groupID
 		pages++
 	}
 
-	return subs, &PaginationResult{
+	return subs, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -135,7 +136,7 @@ func (r *UserSubscriptionRepository) ListByGroupID(ctx context.Context, groupID
 }
 
 // List 获取所有订阅（分页，支持筛选）
-func (r *UserSubscriptionRepository) List(ctx context.Context, params PaginationParams, userID, groupID *int64, status string) ([]model.UserSubscription, *PaginationResult, error) {
+func (r *UserSubscriptionRepository) List(ctx context.Context, params pagination.PaginationParams, userID, groupID *int64, status string) ([]model.UserSubscription, *pagination.PaginationResult, error) {
 	var subs []model.UserSubscription
 	var total int64
 
@@ -172,7 +173,7 @@ func (r *UserSubscriptionRepository) List(ctx context.Context, params Pagination
 		pages++
 	}
 
-	return subs, &PaginationResult{
+	return subs, &pagination.PaginationResult{
 		Total:    total,
 		Page:     params.Page,
 		PageSize: params.Limit(),
@@ -184,7 +185,7 @@ func (r *UserSubscriptionRepository) List(ctx context.Context, params Pagination
 func (r *UserSubscriptionRepository) IncrementUsage(ctx context.Context, id int64, costUSD float64) error {
 	return r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"daily_usage_usd":   gorm.Expr("daily_usage_usd + ?", costUSD),
 			"weekly_usage_usd":  gorm.Expr("weekly_usage_usd + ?", costUSD),
 			"monthly_usage_usd": gorm.Expr("monthly_usage_usd + ?", costUSD),
@@ -196,7 +197,7 @@ func (r *UserSubscriptionRepository) IncrementUsage(ctx context.Context, id int6
 func (r *UserSubscriptionRepository) ResetDailyUsage(ctx context.Context, id int64, newWindowStart time.Time) error {
 	return r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"daily_usage_usd":    0,
 			"daily_window_start": newWindowStart,
 			"updated_at":         time.Now(),
@@ -207,7 +208,7 @@ func (r *UserSubscriptionRepository) ResetDailyUsage(ctx context.Context, id int
 func (r *UserSubscriptionRepository) ResetWeeklyUsage(ctx context.Context, id int64, newWindowStart time.Time) error {
 	return r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"weekly_usage_usd":    0,
 			"weekly_window_start": newWindowStart,
 			"updated_at":          time.Now(),
@@ -218,7 +219,7 @@ func (r *UserSubscriptionRepository) ResetWeeklyUsage(ctx context.Context, id in
 func (r *UserSubscriptionRepository) ResetMonthlyUsage(ctx context.Context, id int64, newWindowStart time.Time) error {
 	return r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"monthly_usage_usd":    0,
 			"monthly_window_start": newWindowStart,
 			"updated_at":           time.Now(),
@@ -229,7 +230,7 @@ func (r *UserSubscriptionRepository) ResetMonthlyUsage(ctx context.Context, id i
 func (r *UserSubscriptionRepository) ActivateWindows(ctx context.Context, id int64, activateTime time.Time) error {
 	return r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"daily_window_start":   activateTime,
 			"weekly_window_start":  activateTime,
 			"monthly_window_start": activateTime,
@@ -241,7 +242,7 @@ func (r *UserSubscriptionRepository) ActivateWindows(ctx context.Context, id int
 func (r *UserSubscriptionRepository) UpdateStatus(ctx context.Context, id int64, status string) error {
 	return r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"status":     status,
 			"updated_at": time.Now(),
 		}).Error
@@ -251,7 +252,7 @@ func (r *UserSubscriptionRepository) UpdateStatus(ctx context.Context, id int64,
 func (r *UserSubscriptionRepository) ExtendExpiry(ctx context.Context, id int64, newExpiresAt time.Time) error {
 	return r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"expires_at": newExpiresAt,
 			"updated_at": time.Now(),
 		}).Error
@@ -261,7 +262,7 @@ func (r *UserSubscriptionRepository) ExtendExpiry(ctx context.Context, id int64,
 func (r *UserSubscriptionRepository) UpdateNotes(ctx context.Context, id int64, notes string) error {
 	return r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"notes":      notes,
 			"updated_at": time.Now(),
 		}).Error
@@ -280,7 +281,7 @@ func (r *UserSubscriptionRepository) ListExpired(ctx context.Context) ([]model.U
 func (r *UserSubscriptionRepository) BatchUpdateExpiredStatus(ctx context.Context) (int64, error) {
 	result := r.db.WithContext(ctx).Model(&model.UserSubscription{}).
 		Where("status = ? AND expires_at <= ?", model.SubscriptionStatusActive, time.Now()).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"status":     model.SubscriptionStatusExpired,
 			"updated_at": time.Now(),
 		})

backend/internal/repository/wire.go

@@ -1,6 +1,8 @@
 package repository
 
 import (
+	"sub2api/internal/service/ports"
+
 	"github.com/google/wire"
 )
 
@@ -16,4 +18,34 @@ var ProviderSet = wire.NewSet(
 	NewSettingRepository,
 	NewUserSubscriptionRepository,
 	wire.Struct(new(Repositories), "*"),
+
+	// Cache implementations
+	NewGatewayCache,
+	NewBillingCache,
+	NewApiKeyCache,
+	NewConcurrencyCache,
+	NewEmailCache,
+	NewIdentityCache,
+	NewRedeemCache,
+	NewUpdateCache,
+
+	// HTTP service ports (DI Strategy A: return interface directly)
+	NewTurnstileVerifier,
+	NewPricingRemoteClient,
+	NewGitHubReleaseClient,
+	NewProxyExitInfoProber,
+	NewClaudeUsageFetcher,
+	NewClaudeOAuthClient,
+	NewClaudeUpstream,
+
+	// Bind concrete repositories to service port interfaces
+	wire.Bind(new(ports.UserRepository), new(*UserRepository)),
+	wire.Bind(new(ports.ApiKeyRepository), new(*ApiKeyRepository)),
+	wire.Bind(new(ports.GroupRepository), new(*GroupRepository)),
+	wire.Bind(new(ports.AccountRepository), new(*AccountRepository)),
+	wire.Bind(new(ports.ProxyRepository), new(*ProxyRepository)),
+	wire.Bind(new(ports.RedeemCodeRepository), new(*RedeemCodeRepository)),
+	wire.Bind(new(ports.UsageLogRepository), new(*UsageLogRepository)),
+	wire.Bind(new(ports.SettingRepository), new(*SettingRepository)),
+	wire.Bind(new(ports.UserSubscriptionRepository), new(*UserSubscriptionRepository)),
 )

backend/internal/server/router.go

@@ -132,7 +132,7 @@ func registerRoutes(r *gin.Engine, h *handler.Handlers, s *service.Services, rep
 
 		// 管理员接口
 		admin := v1.Group("/admin")
-		admin.Use(middleware.JWTAuth(s.Auth, repos.User), middleware.AdminOnly())
+		admin.Use(middleware.AdminAuth(s.Auth, repos.User, s.Setting))
 		{
 			// 仪表盘
 			dashboard := admin.Group("/dashboard")
@@ -189,6 +189,7 @@ func registerRoutes(r *gin.Engine, h *handler.Handlers, s *service.Services, rep
 				accounts.GET("/:id/today-stats", h.Admin.Account.GetTodayStats)
 				accounts.POST("/:id/clear-rate-limit", h.Admin.Account.ClearRateLimit)
 				accounts.POST("/:id/schedulable", h.Admin.Account.SetSchedulable)
+				accounts.GET("/:id/models", h.Admin.Account.GetAvailableModels)
 				accounts.POST("/batch", h.Admin.Account.BatchCreate)
 
 				// OAuth routes
@@ -235,6 +236,10 @@ func registerRoutes(r *gin.Engine, h *handler.Handlers, s *service.Services, rep
 				adminSettings.PUT("", h.Admin.Setting.UpdateSettings)
 				adminSettings.POST("/test-smtp", h.Admin.Setting.TestSmtpConnection)
 				adminSettings.POST("/send-test-email", h.Admin.Setting.SendTestEmail)
+				// Admin API Key 管理
+				adminSettings.GET("/admin-api-key", h.Admin.Setting.GetAdminApiKey)
+				adminSettings.POST("/admin-api-key/regenerate", h.Admin.Setting.RegenerateAdminApiKey)
+				adminSettings.DELETE("/admin-api-key", h.Admin.Setting.DeleteAdminApiKey)
 			}
 
 			// 系统管理
@@ -281,6 +286,7 @@ func registerRoutes(r *gin.Engine, h *handler.Handlers, s *service.Services, rep
 	gateway.Use(middleware.ApiKeyAuthWithSubscription(s.ApiKey, s.Subscription))
 	{
 		gateway.POST("/messages", h.Gateway.Messages)
+		gateway.POST("/messages/count_tokens", h.Gateway.CountTokens)
 		gateway.GET("/models", h.Gateway.Models)
 		gateway.GET("/usage", h.Gateway.Usage)
 	}

backend/internal/service/account_service.go

@@ -5,7 +5,8 @@ import (
 	"errors"
 	"fmt"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/pkg/pagination"
+	"sub2api/internal/service/ports"
 
 	"gorm.io/gorm"
 )
@@ -16,37 +17,37 @@ var (
 
 // CreateAccountRequest 创建账号请求
 type CreateAccountRequest struct {
-	Name        string                 `json:"name"`
-	Platform    string                 `json:"platform"`
-	Type        string                 `json:"type"`
-	Credentials map[string]interface{} `json:"credentials"`
-	Extra       map[string]interface{} `json:"extra"`
-	ProxyID     *int64                 `json:"proxy_id"`
-	Concurrency int                    `json:"concurrency"`
-	Priority    int                    `json:"priority"`
-	GroupIDs    []int64                `json:"group_ids"`
+	Name        string         `json:"name"`
+	Platform    string         `json:"platform"`
+	Type        string         `json:"type"`
+	Credentials map[string]any `json:"credentials"`
+	Extra       map[string]any `json:"extra"`
+	ProxyID     *int64         `json:"proxy_id"`
+	Concurrency int            `json:"concurrency"`
+	Priority    int            `json:"priority"`
+	GroupIDs    []int64        `json:"group_ids"`
 }
 
 // UpdateAccountRequest 更新账号请求
 type UpdateAccountRequest struct {
-	Name        *string                 `json:"name"`
-	Credentials *map[string]interface{} `json:"credentials"`
-	Extra       *map[string]interface{} `json:"extra"`
-	ProxyID     *int64                  `json:"proxy_id"`
-	Concurrency *int                    `json:"concurrency"`
-	Priority    *int                    `json:"priority"`
-	Status      *string                 `json:"status"`
-	GroupIDs    *[]int64                `json:"group_ids"`
+	Name        *string         `json:"name"`
+	Credentials *map[string]any `json:"credentials"`
+	Extra       *map[string]any `json:"extra"`
+	ProxyID     *int64          `json:"proxy_id"`
+	Concurrency *int            `json:"concurrency"`
+	Priority    *int            `json:"priority"`
+	Status      *string         `json:"status"`
+	GroupIDs    *[]int64        `json:"group_ids"`
 }
 
 // AccountService 账号管理服务
 type AccountService struct {
-	accountRepo *repository.AccountRepository
-	groupRepo   *repository.GroupRepository
+	accountRepo ports.AccountRepository
+	groupRepo   ports.GroupRepository
 }
 
 // NewAccountService 创建账号服务实例
-func NewAccountService(accountRepo *repository.AccountRepository, groupRepo *repository.GroupRepository) *AccountService {
+func NewAccountService(accountRepo ports.AccountRepository, groupRepo ports.GroupRepository) *AccountService {
 	return &AccountService{
 		accountRepo: accountRepo,
 		groupRepo:   groupRepo,
@@ -108,7 +109,7 @@ func (s *AccountService) GetByID(ctx context.Context, id int64) (*model.Account,
 }
 
 // List 获取账号列表
-func (s *AccountService) List(ctx context.Context, params repository.PaginationParams) ([]model.Account, *repository.PaginationResult, error) {
+func (s *AccountService) List(ctx context.Context, params pagination.PaginationParams) ([]model.Account, *pagination.PaginationResult, error) {
 	accounts, pagination, err := s.accountRepo.List(ctx, params)
 	if err != nil {
 		return nil, nil, fmt.Errorf("list accounts: %w", err)

backend/internal/service/account_test_service.go

@@ -10,12 +10,12 @@ import (
 	"io"
 	"log"
 	"net/http"
-	"net/url"
 	"strconv"
 	"strings"
 	"time"
 
-	"sub2api/internal/repository"
+	"sub2api/internal/pkg/claude"
+	"sub2api/internal/service/ports"
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
@@ -23,7 +23,6 @@ import (
 
 const (
 	testClaudeAPIURL = "https://api.anthropic.com/v1/messages"
-	testModel        = "claude-sonnet-4-5-20250929"
 )
 
 // TestEvent represents a SSE event for account testing
@@ -37,39 +36,44 @@ type TestEvent struct {
 
 // AccountTestService handles account testing operations
 type AccountTestService struct {
-	repos        *repository.Repositories
-	oauthService *OAuthService
-	httpClient   *http.Client
+	accountRepo    ports.AccountRepository
+	oauthService   *OAuthService
+	claudeUpstream ClaudeUpstream
 }
 
 // NewAccountTestService creates a new AccountTestService
-func NewAccountTestService(repos *repository.Repositories, oauthService *OAuthService) *AccountTestService {
+func NewAccountTestService(accountRepo ports.AccountRepository, oauthService *OAuthService, claudeUpstream ClaudeUpstream) *AccountTestService {
 	return &AccountTestService{
-		repos:        repos,
-		oauthService: oauthService,
-		httpClient: &http.Client{
-			Timeout: 60 * time.Second,
-		},
+		accountRepo:    accountRepo,
+		oauthService:   oauthService,
+		claudeUpstream: claudeUpstream,
 	}
 }
 
 // generateSessionString generates a Claude Code style session string
-func generateSessionString() string {
+func generateSessionString() (string, error) {
 	bytes := make([]byte, 32)
-	rand.Read(bytes)
+	if _, err := rand.Read(bytes); err != nil {
+		return "", err
+	}
 	hex64 := hex.EncodeToString(bytes)
 	sessionUUID := uuid.New().String()
-	return fmt.Sprintf("user_%s_account__session_%s", hex64, sessionUUID)
+	return fmt.Sprintf("user_%s_account__session_%s", hex64, sessionUUID), nil
 }
 
-// createTestPayload creates a minimal test request payload for OAuth/Setup Token accounts
-func createTestPayload() map[string]interface{} {
-	return map[string]interface{}{
-		"model": testModel,
-		"messages": []map[string]interface{}{
+// createTestPayload creates a Claude Code style test request payload
+func createTestPayload(modelID string) (map[string]any, error) {
+	sessionID, err := generateSessionString()
+	if err != nil {
+		return nil, err
+	}
+
+	return map[string]any{
+		"model": modelID,
+		"messages": []map[string]any{
 			{
 				"role": "user",
-				"content": []map[string]interface{}{
+				"content": []map[string]any{
 					{
 						"type": "text",
 						"text": "hi",
@@ -80,7 +84,7 @@ func createTestPayload() map[string]interface{} {
 				},
 			},
 		},
-		"system": []map[string]interface{}{
+		"system": []map[string]any{
 			{
 				"type": "text",
 				"text": "You are Claude Code, Anthropic's official CLI for Claude.",
@@ -90,47 +94,50 @@ func createTestPayload() map[string]interface{} {
 			},
 		},
 		"metadata": map[string]string{
-			"user_id": generateSessionString(),
+			"user_id": sessionID,
 		},
 		"max_tokens":  1024,
 		"temperature": 1,
 		"stream":      true,
-	}
-}
-
-// createApiKeyTestPayload creates a simpler test request payload for API Key accounts
-func createApiKeyTestPayload(model string) map[string]interface{} {
-	return map[string]interface{}{
-		"model": model,
-		"messages": []map[string]interface{}{
-			{
-				"role":    "user",
-				"content": "hi",
-			},
-		},
-		"max_tokens": 1024,
-		"stream":     true,
-	}
+	}, nil
 }
 
 // TestAccountConnection tests an account's connection by sending a test request
-func (s *AccountTestService) TestAccountConnection(c *gin.Context, accountID int64) error {
+// All account types use full Claude Code client characteristics, only auth header differs
+// modelID is optional - if empty, defaults to claude.DefaultTestModel
+func (s *AccountTestService) TestAccountConnection(c *gin.Context, accountID int64, modelID string) error {
 	ctx := c.Request.Context()
 
 	// Get account
-	account, err := s.repos.Account.GetByID(ctx, accountID)
+	account, err := s.accountRepo.GetByID(ctx, accountID)
 	if err != nil {
 		return s.sendErrorAndEnd(c, "Account not found")
 	}
 
-	// Determine authentication method based on account type
+	// Determine the model to use
+	testModelID := modelID
+	if testModelID == "" {
+		testModelID = claude.DefaultTestModel
+	}
+
+	// For API Key accounts with model mapping, map the model
+	if account.Type == "apikey" {
+		mapping := account.GetModelMapping()
+		if len(mapping) > 0 {
+			if mappedModel, exists := mapping[testModelID]; exists {
+				testModelID = mappedModel
+			}
+		}
+	}
+
+	// Determine authentication method and API URL
 	var authToken string
-	var authType string // "bearer" for OAuth, "apikey" for API Key
+	var useBearer bool
 	var apiURL string
 
 	if account.IsOAuth() {
-		// OAuth or Setup Token account
-		authType = "bearer"
+		// OAuth or Setup Token - use Bearer token
+		useBearer = true
 		apiURL = testClaudeAPIURL
 		authToken = account.GetCredential("access_token")
 		if authToken == "" {
@@ -141,7 +148,7 @@ func (s *AccountTestService) TestAccountConnection(c *gin.Context, accountID int
 		needRefresh := false
 		if expiresAtStr := account.GetCredential("expires_at"); expiresAtStr != "" {
 			expiresAt, err := strconv.ParseInt(expiresAtStr, 10, 64)
-			if err == nil && time.Now().Unix()+300 > expiresAt { // 5 minute buffer
+			if err == nil && time.Now().Unix()+300 > expiresAt {
 				needRefresh = true
 			}
 		}
@@ -154,19 +161,17 @@ func (s *AccountTestService) TestAccountConnection(c *gin.Context, accountID int
 			authToken = tokenInfo.AccessToken
 		}
 	} else if account.Type == "apikey" {
-		// API Key account
-		authType = "apikey"
+		// API Key - use x-api-key header
+		useBearer = false
 		authToken = account.GetCredential("api_key")
 		if authToken == "" {
 			return s.sendErrorAndEnd(c, "No API key available")
 		}
 
-		// Get base URL (use default if not set)
 		apiURL = account.GetBaseURL()
 		if apiURL == "" {
 			apiURL = "https://api.anthropic.com"
 		}
-		// Append /v1/messages endpoint
 		apiURL = strings.TrimSuffix(apiURL, "/") + "/v1/messages"
 	} else {
 		return s.sendErrorAndEnd(c, fmt.Sprintf("Unsupported account type: %s", account.Type))
@@ -179,61 +184,49 @@ func (s *AccountTestService) TestAccountConnection(c *gin.Context, accountID int
 	c.Writer.Header().Set("X-Accel-Buffering", "no")
 	c.Writer.Flush()
 
-	// Create test request payload
-	var payload map[string]interface{}
-	var actualModel string
-	if authType == "apikey" {
-		// Use simpler payload for API Key (without Claude Code specific fields)
-		// Apply model mapping if configured
-		actualModel = account.GetMappedModel(testModel)
-		payload = createApiKeyTestPayload(actualModel)
-	} else {
-		actualModel = testModel
-		payload = createTestPayload()
+	// Create Claude Code style payload (same for all account types)
+	payload, err := createTestPayload(testModelID)
+	if err != nil {
+		return s.sendErrorAndEnd(c, "Failed to create test payload")
 	}
 	payloadBytes, _ := json.Marshal(payload)
 
-	// Send test_start event with model info
-	s.sendEvent(c, TestEvent{Type: "test_start", Model: actualModel})
+	// Send test_start event
+	s.sendEvent(c, TestEvent{Type: "test_start", Model: testModelID})
 
 	req, err := http.NewRequestWithContext(ctx, "POST", apiURL, bytes.NewReader(payloadBytes))
 	if err != nil {
 		return s.sendErrorAndEnd(c, "Failed to create request")
 	}
 
-	// Set headers based on auth type
+	// Set common headers
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("anthropic-version", "2023-06-01")
+	req.Header.Set("anthropic-beta", claude.DefaultBetaHeader)
 
-	if authType == "bearer" {
+	// Apply Claude Code client headers
+	for key, value := range claude.DefaultHeaders {
+		req.Header.Set(key, value)
+	}
+
+	// Set authentication header
+	if useBearer {
 		req.Header.Set("Authorization", "Bearer "+authToken)
-		req.Header.Set("anthropic-beta", "prompt-caching-2024-07-31,interleaved-thinking-2025-05-14,output-128k-2025-02-19")
 	} else {
-		// API Key uses x-api-key header
 		req.Header.Set("x-api-key", authToken)
 	}
 
-	// Configure proxy if account has one
-	transport := http.DefaultTransport.(*http.Transport).Clone()
+	// Get proxy URL
+	proxyURL := ""
 	if account.ProxyID != nil && account.Proxy != nil {
-		proxyURL := account.Proxy.URL()
-		if proxyURL != "" {
-			if parsedURL, err := url.Parse(proxyURL); err == nil {
-				transport.Proxy = http.ProxyURL(parsedURL)
-			}
-		}
+		proxyURL = account.Proxy.URL()
 	}
 
-	client := &http.Client{
-		Transport: transport,
-		Timeout:   60 * time.Second,
-	}
-
-	resp, err := client.Do(req)
+	resp, err := s.claudeUpstream.Do(req, proxyURL)
 	if err != nil {
 		return s.sendErrorAndEnd(c, fmt.Sprintf("Request failed: %s", err.Error()))
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
 		body, _ := io.ReadAll(resp.Body)
@@ -252,7 +245,6 @@ func (s *AccountTestService) processStream(c *gin.Context, body io.Reader) error
 		line, err := reader.ReadString('\n')
 		if err != nil {
 			if err == io.EOF {
-				// Stream ended, send complete event
 				s.sendEvent(c, TestEvent{Type: "test_complete", Success: true})
 				return nil
 			}
@@ -270,7 +262,7 @@ func (s *AccountTestService) processStream(c *gin.Context, body io.Reader) error
 			return nil
 		}
 
-		var data map[string]interface{}
+		var data map[string]any
 		if err := json.Unmarshal([]byte(jsonStr), &data); err != nil {
 			continue
 		}
@@ -279,7 +271,7 @@ func (s *AccountTestService) processStream(c *gin.Context, body io.Reader) error
 
 		switch eventType {
 		case "content_block_delta":
-			if delta, ok := data["delta"].(map[string]interface{}); ok {
+			if delta, ok := data["delta"].(map[string]any); ok {
 				if text, ok := delta["text"].(string); ok {
 					s.sendEvent(c, TestEvent{Type: "content", Text: text})
 				}
@@ -289,7 +281,7 @@ func (s *AccountTestService) processStream(c *gin.Context, body io.Reader) error
 			return nil
 		case "error":
 			errorMsg := "Unknown error"
-			if errData, ok := data["error"].(map[string]interface{}); ok {
+			if errData, ok := data["error"].(map[string]any); ok {
 				if msg, ok := errData["message"].(string); ok {
 					errorMsg = msg
 				}
@@ -302,7 +294,10 @@ func (s *AccountTestService) processStream(c *gin.Context, body io.Reader) error
 // sendEvent sends a SSE event to the client
 func (s *AccountTestService) sendEvent(c *gin.Context, event TestEvent) {
 	eventJSON, _ := json.Marshal(event)
-	fmt.Fprintf(c.Writer, "data: %s\n\n", eventJSON)
+	if _, err := fmt.Fprintf(c.Writer, "data: %s\n\n", eventJSON); err != nil {
+		log.Printf("failed to write SSE event: %v", err)
+		return
+	}
 	c.Writer.Flush()
 }
 

backend/internal/service/account_usage_service.go

@@ -2,17 +2,13 @@ package service
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
-	"io"
 	"log"
-	"net/http"
-	"net/url"
 	"sync"
 	"time"
 
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/service/ports"
 )
 
 // usageCache 用于缓存usage数据
@@ -35,10 +31,10 @@ type WindowStats struct {
 
 // UsageProgress 使用量进度
 type UsageProgress struct {
-	Utilization      float64      `json:"utilization"`                  // 使用率百分比 (0-100+，100表示100%)
-	ResetsAt         *time.Time   `json:"resets_at"`                    // 重置时间
-	RemainingSeconds int          `json:"remaining_seconds"`            // 距重置剩余秒数
-	WindowStats      *WindowStats `json:"window_stats,omitempty"`       // 窗口期统计（从窗口开始到当前的使用量）
+	Utilization      float64      `json:"utilization"`            // 使用率百分比 (0-100+，100表示100%)
+	ResetsAt         *time.Time   `json:"resets_at"`              // 重置时间
+	RemainingSeconds int          `json:"remaining_seconds"`      // 距重置剩余秒数
+	WindowStats      *WindowStats `json:"window_stats,omitempty"` // 窗口期统计（从窗口开始到当前的使用量）
 }
 
 // UsageInfo 账号使用量信息
@@ -65,21 +61,24 @@ type ClaudeUsageResponse struct {
 	} `json:"seven_day_sonnet"`
 }
 
+// ClaudeUsageFetcher fetches usage data from Anthropic OAuth API
+type ClaudeUsageFetcher interface {
+	FetchUsage(ctx context.Context, accessToken, proxyURL string) (*ClaudeUsageResponse, error)
+}
+
 // AccountUsageService 账号使用量查询服务
 type AccountUsageService struct {
-	repos        *repository.Repositories
-	oauthService *OAuthService
-	httpClient   *http.Client
+	accountRepo  ports.AccountRepository
+	usageLogRepo ports.UsageLogRepository
+	usageFetcher ClaudeUsageFetcher
 }
 
 // NewAccountUsageService 创建AccountUsageService实例
-func NewAccountUsageService(repos *repository.Repositories, oauthService *OAuthService) *AccountUsageService {
+func NewAccountUsageService(accountRepo ports.AccountRepository, usageLogRepo ports.UsageLogRepository, usageFetcher ClaudeUsageFetcher) *AccountUsageService {
 	return &AccountUsageService{
-		repos:        repos,
-		oauthService: oauthService,
-		httpClient: &http.Client{
-			Timeout: 30 * time.Second,
-		},
+		accountRepo:  accountRepo,
+		usageLogRepo: usageLogRepo,
+		usageFetcher: usageFetcher,
 	}
 }
 
@@ -88,7 +87,7 @@ func NewAccountUsageService(repos *repository.Repositories, oauthService *OAuthS
 // Setup Token账号: 根据session_window推算5h窗口，7d数据不可用（没有profile scope）
 // API Key账号: 不支持usage查询
 func (s *AccountUsageService) GetUsage(ctx context.Context, accountID int64) (*UsageInfo, error) {
-	account, err := s.repos.Account.GetByID(ctx, accountID)
+	account, err := s.accountRepo.GetByID(ctx, accountID)
 	if err != nil {
 		return nil, fmt.Errorf("get account failed: %w", err)
 	}
@@ -97,8 +96,10 @@ func (s *AccountUsageService) GetUsage(ctx context.Context, accountID int64) (*U
 	if account.CanGetUsage() {
 		// 检查缓存
 		if cached, ok := usageCacheMap.Load(accountID); ok {
-			cache := cached.(*usageCache)
-			if time.Since(cache.timestamp) < cacheTTL {
+			cache, ok := cached.(*usageCache)
+			if !ok {
+				usageCacheMap.Delete(accountID)
+			} else if time.Since(cache.timestamp) < cacheTTL {
 				return cache.data, nil
 			}
 		}
@@ -148,7 +149,7 @@ func (s *AccountUsageService) addWindowStats(ctx context.Context, account *model
 		startTime = time.Now().Add(-5 * time.Hour)
 	}
 
-	stats, err := s.repos.UsageLog.GetAccountWindowStats(ctx, account.ID, startTime)
+	stats, err := s.usageLogRepo.GetAccountWindowStats(ctx, account.ID, startTime)
 	if err != nil {
 		log.Printf("Failed to get window stats for account %d: %v", account.ID, err)
 		return
@@ -163,7 +164,7 @@ func (s *AccountUsageService) addWindowStats(ctx context.Context, account *model
 
 // GetTodayStats 获取账号今日统计
 func (s *AccountUsageService) GetTodayStats(ctx context.Context, accountID int64) (*WindowStats, error) {
-	stats, err := s.repos.UsageLog.GetAccountTodayStats(ctx, accountID)
+	stats, err := s.usageLogRepo.GetAccountTodayStats(ctx, accountID)
 	if err != nil {
 		return nil, fmt.Errorf("get today stats failed: %w", err)
 	}
@@ -177,58 +178,23 @@ func (s *AccountUsageService) GetTodayStats(ctx context.Context, accountID int64
 
 // fetchOAuthUsage 从Anthropic API获取OAuth账号的使用量
 func (s *AccountUsageService) fetchOAuthUsage(ctx context.Context, account *model.Account) (*UsageInfo, error) {
-	// 获取access token（从credentials中获取）
 	accessToken := account.GetCredential("access_token")
 	if accessToken == "" {
 		return nil, fmt.Errorf("no access token available")
 	}
 
-	// 获取代理配置
-	transport := http.DefaultTransport.(*http.Transport).Clone()
+	var proxyURL string
 	if account.ProxyID != nil && account.Proxy != nil {
-		proxyURL := account.Proxy.URL()
-		if proxyURL != "" {
-			if parsedURL, err := url.Parse(proxyURL); err == nil {
-				transport.Proxy = http.ProxyURL(parsedURL)
-			}
-		}
+		proxyURL = account.Proxy.URL()
 	}
 
-	client := &http.Client{
-		Transport: transport,
-		Timeout:   30 * time.Second,
-	}
-
-	// 构建请求
-	req, err := http.NewRequestWithContext(ctx, "GET", "https://api.anthropic.com/api/oauth/usage", nil)
+	usageResp, err := s.usageFetcher.FetchUsage(ctx, accessToken, proxyURL)
 	if err != nil {
-		return nil, fmt.Errorf("create request failed: %w", err)
+		return nil, err
 	}
 
-	req.Header.Set("Authorization", "Bearer "+accessToken)
-	req.Header.Set("anthropic-beta", "oauth-2025-04-20")
-
-	// 发送请求
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("request failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(resp.Body)
-		return nil, fmt.Errorf("API returned status %d: %s", resp.StatusCode, string(body))
-	}
-
-	// 解析响应
-	var usageResp ClaudeUsageResponse
-	if err := json.NewDecoder(resp.Body).Decode(&usageResp); err != nil {
-		return nil, fmt.Errorf("decode response failed: %w", err)
-	}
-
-	// 转换为UsageInfo
 	now := time.Now()
-	return s.buildUsageInfo(&usageResp, &now), nil
+	return s.buildUsageInfo(usageResp, &now), nil
 }
 
 // parseTime 尝试多种格式解析时间

backend/internal/service/admin_service.go

@@ -2,20 +2,15 @@ package service
 
 import (
 	"context"
-	"crypto/tls"
-	"encoding/json"
 	"errors"
 	"fmt"
-	"io"
-	"net"
-	"net/http"
-	"net/url"
+	"log"
 	"time"
 
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/pkg/pagination"
+	"sub2api/internal/service/ports"
 
-	"golang.org/x/net/proxy"
 	"gorm.io/gorm"
 )
 
@@ -29,7 +24,7 @@ type AdminService interface {
 	DeleteUser(ctx context.Context, id int64) error
 	UpdateUserBalance(ctx context.Context, userID int64, balance float64, operation string) (*model.User, error)
 	GetUserAPIKeys(ctx context.Context, userID int64, page, pageSize int) ([]model.ApiKey, int64, error)
-	GetUserUsageStats(ctx context.Context, userID int64, period string) (interface{}, error)
+	GetUserUsageStats(ctx context.Context, userID int64, period string) (any, error)
 
 	// Group management
 	ListGroups(ctx context.Context, page, pageSize int, platform, status string, isExclusive *bool) ([]model.Group, int64, error)
@@ -119,8 +114,8 @@ type CreateAccountInput struct {
 	Name        string
 	Platform    string
 	Type        string
-	Credentials map[string]interface{}
-	Extra       map[string]interface{}
+	Credentials map[string]any
+	Extra       map[string]any
 	ProxyID     *int64
 	Concurrency int
 	Priority    int
@@ -130,8 +125,8 @@ type CreateAccountInput struct {
 type UpdateAccountInput struct {
 	Name        string
 	Type        string // Account type: oauth, setup-token, apikey
-	Credentials map[string]interface{}
-	Extra       map[string]interface{}
+	Credentials map[string]any
+	Extra       map[string]any
 	ProxyID     *int64
 	Concurrency *int // 使用指针区分"未提供"和"设置为0"
 	Priority    *int // 使用指针区分"未提供"和"设置为0"
@@ -177,37 +172,57 @@ type ProxyTestResult struct {
 	Country   string `json:"country,omitempty"`
 }
 
+// ProxyExitInfo represents proxy exit information from ipinfo.io
+type ProxyExitInfo struct {
+	IP      string
+	City    string
+	Region  string
+	Country string
+}
+
+// ProxyExitInfoProber tests proxy connectivity and retrieves exit information
+type ProxyExitInfoProber interface {
+	ProbeProxy(ctx context.Context, proxyURL string) (*ProxyExitInfo, int64, error)
+}
+
 // adminServiceImpl implements AdminService
 type adminServiceImpl struct {
-	userRepo            *repository.UserRepository
-	groupRepo           *repository.GroupRepository
-	accountRepo         *repository.AccountRepository
-	proxyRepo           *repository.ProxyRepository
-	apiKeyRepo          *repository.ApiKeyRepository
-	redeemCodeRepo      *repository.RedeemCodeRepository
-	usageLogRepo        *repository.UsageLogRepository
-	userSubRepo         *repository.UserSubscriptionRepository
+	userRepo            ports.UserRepository
+	groupRepo           ports.GroupRepository
+	accountRepo         ports.AccountRepository
+	proxyRepo           ports.ProxyRepository
+	apiKeyRepo          ports.ApiKeyRepository
+	redeemCodeRepo      ports.RedeemCodeRepository
 	billingCacheService *BillingCacheService
+	proxyProber         ProxyExitInfoProber
 }
 
 // NewAdminService creates a new AdminService
-func NewAdminService(repos *repository.Repositories, billingCacheService *BillingCacheService) AdminService {
+func NewAdminService(
+	userRepo ports.UserRepository,
+	groupRepo ports.GroupRepository,
+	accountRepo ports.AccountRepository,
+	proxyRepo ports.ProxyRepository,
+	apiKeyRepo ports.ApiKeyRepository,
+	redeemCodeRepo ports.RedeemCodeRepository,
+	billingCacheService *BillingCacheService,
+	proxyProber ProxyExitInfoProber,
+) AdminService {
 	return &adminServiceImpl{
-		userRepo:            repos.User,
-		groupRepo:           repos.Group,
-		accountRepo:         repos.Account,
-		proxyRepo:           repos.Proxy,
-		apiKeyRepo:          repos.ApiKey,
-		redeemCodeRepo:      repos.RedeemCode,
-		usageLogRepo:        repos.UsageLog,
-		userSubRepo:         repos.UserSubscription,
+		userRepo:            userRepo,
+		groupRepo:           groupRepo,
+		accountRepo:         accountRepo,
+		proxyRepo:           proxyRepo,
+		apiKeyRepo:          apiKeyRepo,
+		redeemCodeRepo:      redeemCodeRepo,
 		billingCacheService: billingCacheService,
+		proxyProber:         proxyProber,
 	}
 }
 
 // User management implementations
 func (s *adminServiceImpl) ListUsers(ctx context.Context, page, pageSize int, status, role, search string) ([]model.User, int64, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	users, result, err := s.userRepo.ListWithFilters(ctx, params, status, role, search)
 	if err != nil {
 		return nil, 0, err
@@ -289,7 +304,9 @@ func (s *adminServiceImpl) UpdateUser(ctx context.Context, id int64, input *Upda
 			go func() {
 				cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 				defer cancel()
-				s.billingCacheService.InvalidateUserBalance(cacheCtx, id)
+				if err := s.billingCacheService.InvalidateUserBalance(cacheCtx, id); err != nil {
+					log.Printf("invalidate user balance cache failed: user_id=%d err=%v", id, err)
+				}
 			}()
 		}
 	}
@@ -297,8 +314,13 @@ func (s *adminServiceImpl) UpdateUser(ctx context.Context, id int64, input *Upda
 	// Create adjustment records for balance/concurrency changes
 	balanceDiff := user.Balance - oldBalance
 	if balanceDiff != 0 {
+		code, err := model.GenerateRedeemCode()
+		if err != nil {
+			log.Printf("failed to generate adjustment redeem code: %v", err)
+			return user, nil
+		}
 		adjustmentRecord := &model.RedeemCode{
-			Code:   model.GenerateRedeemCode(),
+			Code:   code,
 			Type:   model.AdjustmentTypeAdminBalance,
 			Value:  balanceDiff,
 			Status: model.StatusUsed,
@@ -307,15 +329,19 @@ func (s *adminServiceImpl) UpdateUser(ctx context.Context, id int64, input *Upda
 		now := time.Now()
 		adjustmentRecord.UsedAt = &now
 		if err := s.redeemCodeRepo.Create(ctx, adjustmentRecord); err != nil {
-			// Log error but don't fail the update
-			// The user update has already succeeded
+			log.Printf("failed to create balance adjustment redeem code: %v", err)
 		}
 	}
 
 	concurrencyDiff := user.Concurrency - oldConcurrency
 	if concurrencyDiff != 0 {
+		code, err := model.GenerateRedeemCode()
+		if err != nil {
+			log.Printf("failed to generate adjustment redeem code: %v", err)
+			return user, nil
+		}
 		adjustmentRecord := &model.RedeemCode{
-			Code:   model.GenerateRedeemCode(),
+			Code:   code,
 			Type:   model.AdjustmentTypeAdminConcurrency,
 			Value:  float64(concurrencyDiff),
 			Status: model.StatusUsed,
@@ -324,8 +350,7 @@ func (s *adminServiceImpl) UpdateUser(ctx context.Context, id int64, input *Upda
 		now := time.Now()
 		adjustmentRecord.UsedAt = &now
 		if err := s.redeemCodeRepo.Create(ctx, adjustmentRecord); err != nil {
-			// Log error but don't fail the update
-			// The user update has already succeeded
+			log.Printf("failed to create concurrency adjustment redeem code: %v", err)
 		}
 	}
 
@@ -368,7 +393,9 @@ func (s *adminServiceImpl) UpdateUserBalance(ctx context.Context, userID int64,
 		go func() {
 			cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
-			s.billingCacheService.InvalidateUserBalance(cacheCtx, userID)
+			if err := s.billingCacheService.InvalidateUserBalance(cacheCtx, userID); err != nil {
+				log.Printf("invalidate user balance cache failed: user_id=%d err=%v", userID, err)
+			}
 		}()
 	}
 
@@ -376,7 +403,7 @@ func (s *adminServiceImpl) UpdateUserBalance(ctx context.Context, userID int64,
 }
 
 func (s *adminServiceImpl) GetUserAPIKeys(ctx context.Context, userID int64, page, pageSize int) ([]model.ApiKey, int64, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	keys, result, err := s.apiKeyRepo.ListByUserID(ctx, userID, params)
 	if err != nil {
 		return nil, 0, err
@@ -384,9 +411,9 @@ func (s *adminServiceImpl) GetUserAPIKeys(ctx context.Context, userID int64, pag
 	return keys, result.Total, nil
 }
 
-func (s *adminServiceImpl) GetUserUsageStats(ctx context.Context, userID int64, period string) (interface{}, error) {
+func (s *adminServiceImpl) GetUserUsageStats(ctx context.Context, userID int64, period string) (any, error) {
 	// Return mock data for now
-	return map[string]interface{}{
+	return map[string]any{
 		"period":          period,
 		"total_requests":  0,
 		"total_cost":      0.0,
@@ -397,7 +424,7 @@ func (s *adminServiceImpl) GetUserUsageStats(ctx context.Context, userID int64,
 
 // Group management implementations
 func (s *adminServiceImpl) ListGroups(ctx context.Context, page, pageSize int, platform, status string, isExclusive *bool) ([]model.Group, int64, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	groups, result, err := s.groupRepo.ListWithFilters(ctx, params, platform, status, isExclusive)
 	if err != nil {
 		return nil, 0, err
@@ -559,7 +586,9 @@ func (s *adminServiceImpl) DeleteGroup(ctx context.Context, id int64) error {
 			cacheCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 			defer cancel()
 			for _, userID := range affectedUserIDs {
-				s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
+				if err := s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID); err != nil {
+					log.Printf("invalidate subscription cache failed: user_id=%d group_id=%d err=%v", userID, groupID, err)
+				}
 			}
 		}()
 	}
@@ -568,7 +597,7 @@ func (s *adminServiceImpl) DeleteGroup(ctx context.Context, id int64) error {
 }
 
 func (s *adminServiceImpl) GetGroupAPIKeys(ctx context.Context, groupID int64, page, pageSize int) ([]model.ApiKey, int64, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	keys, result, err := s.apiKeyRepo.ListByGroupID(ctx, groupID, params)
 	if err != nil {
 		return nil, 0, err
@@ -578,7 +607,7 @@ func (s *adminServiceImpl) GetGroupAPIKeys(ctx context.Context, groupID int64, p
 
 // Account management implementations
 func (s *adminServiceImpl) ListAccounts(ctx context.Context, page, pageSize int, platform, accountType, status, search string) ([]model.Account, int64, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	accounts, result, err := s.accountRepo.ListWithFilters(ctx, params, platform, accountType, status, search)
 	if err != nil {
 		return nil, 0, err
@@ -626,10 +655,10 @@ func (s *adminServiceImpl) UpdateAccount(ctx context.Context, id int64, input *U
 	if input.Type != "" {
 		account.Type = input.Type
 	}
-	if input.Credentials != nil && len(input.Credentials) > 0 {
+	if len(input.Credentials) > 0 {
 		account.Credentials = model.JSONB(input.Credentials)
 	}
-	if input.Extra != nil && len(input.Extra) > 0 {
+	if len(input.Extra) > 0 {
 		account.Extra = model.JSONB(input.Extra)
 	}
 	if input.ProxyID != nil {
@@ -696,7 +725,7 @@ func (s *adminServiceImpl) SetAccountSchedulable(ctx context.Context, id int64,
 
 // Proxy management implementations
 func (s *adminServiceImpl) ListProxies(ctx context.Context, page, pageSize int, protocol, status, search string) ([]model.Proxy, int64, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	proxies, result, err := s.proxyRepo.ListWithFilters(ctx, params, protocol, status, search)
 	if err != nil {
 		return nil, 0, err
@@ -781,7 +810,7 @@ func (s *adminServiceImpl) CheckProxyExists(ctx context.Context, host string, po
 
 // Redeem code management implementations
 func (s *adminServiceImpl) ListRedeemCodes(ctx context.Context, page, pageSize int, codeType, status, search string) ([]model.RedeemCode, int64, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	codes, result, err := s.redeemCodeRepo.ListWithFilters(ctx, params, codeType, status, search)
 	if err != nil {
 		return nil, 0, err
@@ -811,8 +840,12 @@ func (s *adminServiceImpl) GenerateRedeemCodes(ctx context.Context, input *Gener
 
 	codes := make([]model.RedeemCode, 0, input.Count)
 	for i := 0; i < input.Count; i++ {
+		codeValue, err := model.GenerateRedeemCode()
+		if err != nil {
+			return nil, err
+		}
 		code := model.RedeemCode{
-			Code:   model.GenerateRedeemCode(),
+			Code:   codeValue,
 			Type:   input.Type,
 			Value:  input.Value,
 			Status: model.StatusUnused,
@@ -865,79 +898,12 @@ func (s *adminServiceImpl) TestProxy(ctx context.Context, id int64) (*ProxyTestR
 		return nil, err
 	}
 
-	return testProxyConnection(ctx, proxy)
-}
-
-// testProxyConnection tests proxy connectivity by requesting ipinfo.io/json
-func testProxyConnection(ctx context.Context, proxy *model.Proxy) (*ProxyTestResult, error) {
 	proxyURL := proxy.URL()
-
-	// Create HTTP client with proxy
-	transport, err := createProxyTransport(proxyURL)
+	exitInfo, latencyMs, err := s.proxyProber.ProbeProxy(ctx, proxyURL)
 	if err != nil {
 		return &ProxyTestResult{
 			Success: false,
-			Message: fmt.Sprintf("Failed to create proxy transport: %v", err),
-		}, nil
-	}
-
-	client := &http.Client{
-		Transport: transport,
-		Timeout:   15 * time.Second,
-	}
-
-	// Measure latency
-	startTime := time.Now()
-
-	req, err := http.NewRequestWithContext(ctx, "GET", "https://ipinfo.io/json", nil)
-	if err != nil {
-		return &ProxyTestResult{
-			Success: false,
-			Message: fmt.Sprintf("Failed to create request: %v", err),
-		}, nil
-	}
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return &ProxyTestResult{
-			Success: false,
-			Message: fmt.Sprintf("Proxy connection failed: %v", err),
-		}, nil
-	}
-	defer resp.Body.Close()
-
-	latencyMs := time.Since(startTime).Milliseconds()
-
-	if resp.StatusCode != http.StatusOK {
-		return &ProxyTestResult{
-			Success:   false,
-			Message:   fmt.Sprintf("Request failed with status: %d", resp.StatusCode),
-			LatencyMs: latencyMs,
-		}, nil
-	}
-
-	// Parse ipinfo.io response
-	var ipInfo struct {
-		IP      string `json:"ip"`
-		City    string `json:"city"`
-		Region  string `json:"region"`
-		Country string `json:"country"`
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return &ProxyTestResult{
-			Success:   true,
-			Message:   "Proxy is accessible but failed to read response",
-			LatencyMs: latencyMs,
-		}, nil
-	}
-
-	if err := json.Unmarshal(body, &ipInfo); err != nil {
-		return &ProxyTestResult{
-			Success:   true,
-			Message:   "Proxy is accessible but failed to parse response",
-			LatencyMs: latencyMs,
+			Message: err.Error(),
 		}, nil
 	}
 
@@ -945,38 +911,9 @@ func testProxyConnection(ctx context.Context, proxy *model.Proxy) (*ProxyTestRes
 		Success:   true,
 		Message:   "Proxy is accessible",
 		LatencyMs: latencyMs,
-		IPAddress: ipInfo.IP,
-		City:      ipInfo.City,
-		Region:    ipInfo.Region,
-		Country:   ipInfo.Country,
+		IPAddress: exitInfo.IP,
+		City:      exitInfo.City,
+		Region:    exitInfo.Region,
+		Country:   exitInfo.Country,
 	}, nil
 }
-
-// createProxyTransport creates an HTTP transport with the given proxy URL
-func createProxyTransport(proxyURL string) (*http.Transport, error) {
-	parsedURL, err := url.Parse(proxyURL)
-	if err != nil {
-		return nil, fmt.Errorf("invalid proxy URL: %w", err)
-	}
-
-	transport := &http.Transport{
-		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-	}
-
-	switch parsedURL.Scheme {
-	case "http", "https":
-		transport.Proxy = http.ProxyURL(parsedURL)
-	case "socks5":
-		dialer, err := proxy.FromURL(parsedURL, proxy.Direct)
-		if err != nil {
-			return nil, fmt.Errorf("failed to create socks5 dialer: %w", err)
-		}
-		transport.DialContext = func(ctx context.Context, network, addr string) (net.Conn, error) {
-			return dialer.Dial(network, addr)
-		}
-	default:
-		return nil, fmt.Errorf("unsupported proxy protocol: %s", parsedURL.Scheme)
-	}
-
-	return transport, nil
-}

backend/internal/service/api_key_service.go

@@ -8,8 +8,9 @@ import (
 	"fmt"
 	"sub2api/internal/config"
 	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
 	"sub2api/internal/pkg/timezone"
-	"sub2api/internal/repository"
+	"sub2api/internal/service/ports"
 	"time"
 
 	"github.com/redis/go-redis/v9"
@@ -17,18 +18,16 @@ import (
 )
 
 var (
-	ErrApiKeyNotFound      = errors.New("api key not found")
-	ErrGroupNotAllowed     = errors.New("user is not allowed to bind this group")
-	ErrApiKeyExists        = errors.New("api key already exists")
-	ErrApiKeyTooShort      = errors.New("api key must be at least 16 characters")
-	ErrApiKeyInvalidChars  = errors.New("api key can only contain letters, numbers, underscores, and hyphens")
-	ErrApiKeyRateLimited   = errors.New("too many failed attempts, please try again later")
+	ErrApiKeyNotFound     = errors.New("api key not found")
+	ErrGroupNotAllowed    = errors.New("user is not allowed to bind this group")
+	ErrApiKeyExists       = errors.New("api key already exists")
+	ErrApiKeyTooShort     = errors.New("api key must be at least 16 characters")
+	ErrApiKeyInvalidChars = errors.New("api key can only contain letters, numbers, underscores, and hyphens")
+	ErrApiKeyRateLimited  = errors.New("too many failed attempts, please try again later")
 )
 
 const (
-	apiKeyRateLimitKeyPrefix = "apikey:create_rate_limit:"
-	apiKeyMaxErrorsPerHour   = 20
-	apiKeyRateLimitDuration  = time.Hour
+	apiKeyMaxErrorsPerHour = 20
 )
 
 // CreateApiKeyRequest 创建API Key请求
@@ -47,21 +46,21 @@ type UpdateApiKeyRequest struct {
 
 // ApiKeyService API Key服务
 type ApiKeyService struct {
-	apiKeyRepo  *repository.ApiKeyRepository
-	userRepo    *repository.UserRepository
-	groupRepo   *repository.GroupRepository
-	userSubRepo *repository.UserSubscriptionRepository
-	rdb         *redis.Client
+	apiKeyRepo  ports.ApiKeyRepository
+	userRepo    ports.UserRepository
+	groupRepo   ports.GroupRepository
+	userSubRepo ports.UserSubscriptionRepository
+	cache       ports.ApiKeyCache
 	cfg         *config.Config
 }
 
 // NewApiKeyService 创建API Key服务实例
 func NewApiKeyService(
-	apiKeyRepo *repository.ApiKeyRepository,
-	userRepo *repository.UserRepository,
-	groupRepo *repository.GroupRepository,
-	userSubRepo *repository.UserSubscriptionRepository,
-	rdb *redis.Client,
+	apiKeyRepo ports.ApiKeyRepository,
+	userRepo ports.UserRepository,
+	groupRepo ports.GroupRepository,
+	userSubRepo ports.UserSubscriptionRepository,
+	cache ports.ApiKeyCache,
 	cfg *config.Config,
 ) *ApiKeyService {
 	return &ApiKeyService{
@@ -69,7 +68,7 @@ func NewApiKeyService(
 		userRepo:    userRepo,
 		groupRepo:   groupRepo,
 		userSubRepo: userSubRepo,
-		rdb:         rdb,
+		cache:       cache,
 		cfg:         cfg,
 	}
 }
@@ -101,10 +100,13 @@ func (s *ApiKeyService) ValidateCustomKey(key string) error {
 
 	// 检查字符：只允许字母、数字、下划线、连字符
 	for _, c := range key {
-		if !((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
-			(c >= '0' && c <= '9') || c == '_' || c == '-') {
-			return ErrApiKeyInvalidChars
+		if (c >= 'a' && c <= 'z') ||
+			(c >= 'A' && c <= 'Z') ||
+			(c >= '0' && c <= '9') ||
+			c == '_' || c == '-' {
+			continue
 		}
+		return ErrApiKeyInvalidChars
 	}
 
 	return nil
@@ -112,13 +114,11 @@ func (s *ApiKeyService) ValidateCustomKey(key string) error {
 
 // checkApiKeyRateLimit 检查用户创建自定义Key的错误次数是否超限
 func (s *ApiKeyService) checkApiKeyRateLimit(ctx context.Context, userID int64) error {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return nil
 	}
 
-	key := fmt.Sprintf("%s%d", apiKeyRateLimitKeyPrefix, userID)
-
-	count, err := s.rdb.Get(ctx, key).Int()
+	count, err := s.cache.GetCreateAttemptCount(ctx, userID)
 	if err != nil && !errors.Is(err, redis.Nil) {
 		// Redis 出错时不阻止用户操作
 		return nil
@@ -133,16 +133,11 @@ func (s *ApiKeyService) checkApiKeyRateLimit(ctx context.Context, userID int64)
 
 // incrementApiKeyErrorCount 增加用户创建自定义Key的错误计数
 func (s *ApiKeyService) incrementApiKeyErrorCount(ctx context.Context, userID int64) {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return
 	}
 
-	key := fmt.Sprintf("%s%d", apiKeyRateLimitKeyPrefix, userID)
-
-	pipe := s.rdb.Pipeline()
-	pipe.Incr(ctx, key)
-	pipe.Expire(ctx, key, apiKeyRateLimitDuration)
-	_, _ = pipe.Exec(ctx)
+	_ = s.cache.IncrementCreateAttemptCount(ctx, userID)
 }
 
 // canUserBindGroup 检查用户是否可以绑定指定分组
@@ -237,7 +232,7 @@ func (s *ApiKeyService) Create(ctx context.Context, userID int64, req CreateApiK
 }
 
 // List 获取用户的API Key列表
-func (s *ApiKeyService) List(ctx context.Context, userID int64, params repository.PaginationParams) ([]model.ApiKey, *repository.PaginationResult, error) {
+func (s *ApiKeyService) List(ctx context.Context, userID int64, params pagination.PaginationParams) ([]model.ApiKey, *pagination.PaginationResult, error) {
 	keys, pagination, err := s.apiKeyRepo.ListByUserID(ctx, userID, params)
 	if err != nil {
 		return nil, nil, fmt.Errorf("list api keys: %w", err)
@@ -272,7 +267,7 @@ func (s *ApiKeyService) GetByKey(ctx context.Context, key string) (*model.ApiKey
 	}
 
 	// 缓存到Redis（可选，TTL设置为5分钟）
-	if s.rdb != nil {
+	if s.cache != nil {
 		// 这里可以序列化并缓存API Key
 		_ = cacheKey // 使用变量避免未使用错误
 	}
@@ -325,9 +320,8 @@ func (s *ApiKeyService) Update(ctx context.Context, id int64, userID int64, req
 	if req.Status != nil {
 		apiKey.Status = *req.Status
 		// 如果状态改变，清除Redis缓存
-		if s.rdb != nil {
-			cacheKey := fmt.Sprintf("apikey:%s", apiKey.Key)
-			_ = s.rdb.Del(ctx, cacheKey)
+		if s.cache != nil {
+			_ = s.cache.DeleteCreateAttemptCount(ctx, apiKey.UserID)
 		}
 	}
 
@@ -354,9 +348,8 @@ func (s *ApiKeyService) Delete(ctx context.Context, id int64, userID int64) erro
 	}
 
 	// 清除Redis缓存
-	if s.rdb != nil {
-		cacheKey := fmt.Sprintf("apikey:%s", apiKey.Key)
-		_ = s.rdb.Del(ctx, cacheKey)
+	if s.cache != nil {
+		_ = s.cache.DeleteCreateAttemptCount(ctx, apiKey.UserID)
 	}
 
 	if err := s.apiKeyRepo.Delete(ctx, id); err != nil {
@@ -399,13 +392,13 @@ func (s *ApiKeyService) ValidateKey(ctx context.Context, key string) (*model.Api
 // IncrementUsage 增加API Key使用次数（可选：用于统计）
 func (s *ApiKeyService) IncrementUsage(ctx context.Context, keyID int64) error {
 	// 使用Redis计数器
-	if s.rdb != nil {
+	if s.cache != nil {
 		cacheKey := fmt.Sprintf("apikey:usage:%d:%s", keyID, timezone.Now().Format("2006-01-02"))
-		if err := s.rdb.Incr(ctx, cacheKey).Err(); err != nil {
+		if err := s.cache.IncrementDailyUsage(ctx, cacheKey); err != nil {
 			return fmt.Errorf("increment usage: %w", err)
 		}
 		// 设置24小时过期
-		_ = s.rdb.Expire(ctx, cacheKey, 24*time.Hour)
+		_ = s.cache.SetDailyUsageExpiry(ctx, cacheKey, 24*time.Hour)
 	}
 	return nil
 }

backend/internal/service/auth_service.go

@@ -7,7 +7,7 @@ import (
 	"log"
 	"sub2api/internal/config"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/service/ports"
 	"time"
 
 	"github.com/golang-jwt/jwt/v5"
@@ -35,7 +35,7 @@ type JWTClaims struct {
 
 // AuthService 认证服务
 type AuthService struct {
-	userRepo          *repository.UserRepository
+	userRepo          ports.UserRepository
 	cfg               *config.Config
 	settingService    *SettingService
 	emailService      *EmailService
@@ -45,7 +45,7 @@ type AuthService struct {
 
 // NewAuthService 创建认证服务实例
 func NewAuthService(
-	userRepo *repository.UserRepository,
+	userRepo ports.UserRepository,
 	cfg *config.Config,
 	settingService *SettingService,
 	emailService *EmailService,
@@ -278,7 +278,7 @@ func (s *AuthService) Login(ctx context.Context, email, password string) (string
 
 // ValidateToken 验证JWT token并返回用户声明
 func (s *AuthService) ValidateToken(tokenString string) (*JWTClaims, error) {
-	token, err := jwt.ParseWithClaims(tokenString, &JWTClaims{}, func(token *jwt.Token) (interface{}, error) {
+	token, err := jwt.ParseWithClaims(tokenString, &JWTClaims{}, func(token *jwt.Token) (any, error) {
 		// 验证签名方法
 		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
 			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])

backend/internal/service/billing_cache_service.go

@@ -5,30 +5,10 @@ import (
 	"errors"
 	"fmt"
 	"log"
-	"strconv"
 	"time"
 
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
-
-	"github.com/redis/go-redis/v9"
-)
-
-// 缓存Key前缀和TTL
-const (
-	billingBalanceKeyPrefix = "billing:balance:"
-	billingSubKeyPrefix     = "billing:sub:"
-	billingCacheTTL         = 5 * time.Minute
-)
-
-// 订阅缓存Hash字段
-const (
-	subFieldStatus       = "status"
-	subFieldExpiresAt    = "expires_at"
-	subFieldDailyUsage   = "daily_usage"
-	subFieldWeeklyUsage  = "weekly_usage"
-	subFieldMonthlyUsage = "monthly_usage"
-	subFieldVersion      = "version"
+	"sub2api/internal/service/ports"
 )
 
 // 错误定义
@@ -38,35 +18,6 @@ var (
 	ErrSubscriptionInvalid = errors.New("subscription is invalid or expired")
 )
 
-// 预编译的Lua脚本
-var (
-	// deductBalanceScript: 扣减余额缓存，key不存在则忽略
-	deductBalanceScript = redis.NewScript(`
-		local current = redis.call('GET', KEYS[1])
-		if current == false then
-			return 0
-		end
-		local newVal = tonumber(current) - tonumber(ARGV[1])
-		redis.call('SET', KEYS[1], newVal)
-		redis.call('EXPIRE', KEYS[1], ARGV[2])
-		return 1
-	`)
-
-	// updateSubUsageScript: 更新订阅用量缓存，key不存在则忽略
-	updateSubUsageScript = redis.NewScript(`
-		local exists = redis.call('EXISTS', KEYS[1])
-		if exists == 0 then
-			return 0
-		end
-		local cost = tonumber(ARGV[1])
-		redis.call('HINCRBYFLOAT', KEYS[1], 'daily_usage', cost)
-		redis.call('HINCRBYFLOAT', KEYS[1], 'weekly_usage', cost)
-		redis.call('HINCRBYFLOAT', KEYS[1], 'monthly_usage', cost)
-		redis.call('EXPIRE', KEYS[1], ARGV[2])
-		return 1
-	`)
-)
-
 // subscriptionCacheData 订阅缓存数据结构（内部使用）
 type subscriptionCacheData struct {
 	Status       string
@@ -80,15 +31,15 @@ type subscriptionCacheData struct {
 // BillingCacheService 计费缓存服务
 // 负责余额和订阅数据的缓存管理，提供高性能的计费资格检查
 type BillingCacheService struct {
-	rdb      *redis.Client
-	userRepo *repository.UserRepository
-	subRepo  *repository.UserSubscriptionRepository
+	cache    ports.BillingCache
+	userRepo ports.UserRepository
+	subRepo  ports.UserSubscriptionRepository
 }
 
 // NewBillingCacheService 创建计费缓存服务
-func NewBillingCacheService(rdb *redis.Client, userRepo *repository.UserRepository, subRepo *repository.UserSubscriptionRepository) *BillingCacheService {
+func NewBillingCacheService(cache ports.BillingCache, userRepo ports.UserRepository, subRepo ports.UserSubscriptionRepository) *BillingCacheService {
 	return &BillingCacheService{
-		rdb:      rdb,
+		cache:    cache,
 		userRepo: userRepo,
 		subRepo:  subRepo,
 	}
@@ -100,24 +51,19 @@ func NewBillingCacheService(rdb *redis.Client, userRepo *repository.UserReposito
 
 // GetUserBalance 获取用户余额（优先从缓存读取）
 func (s *BillingCacheService) GetUserBalance(ctx context.Context, userID int64) (float64, error) {
-	if s.rdb == nil {
+	if s.cache == nil {
 		// Redis不可用，直接查询数据库
 		return s.getUserBalanceFromDB(ctx, userID)
 	}
 
-	key := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
-
 	// 尝试从缓存读取
-	val, err := s.rdb.Get(ctx, key).Result()
+	balance, err := s.cache.GetUserBalance(ctx, userID)
 	if err == nil {
-		balance, parseErr := strconv.ParseFloat(val, 64)
-		if parseErr == nil {
-			return balance, nil
-		}
+		return balance, nil
 	}
 
-	// 缓存未命中或解析错误，从数据库读取
-	balance, err := s.getUserBalanceFromDB(ctx, userID)
+	// 缓存未命中，从数据库读取
+	balance, err = s.getUserBalanceFromDB(ctx, userID)
 	if err != nil {
 		return 0, err
 	}
@@ -143,39 +89,28 @@ func (s *BillingCacheService) getUserBalanceFromDB(ctx context.Context, userID i
 
 // setBalanceCache 设置余额缓存
 func (s *BillingCacheService) setBalanceCache(ctx context.Context, userID int64, balance float64) {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return
 	}
-	key := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
-	if err := s.rdb.Set(ctx, key, balance, billingCacheTTL).Err(); err != nil {
+	if err := s.cache.SetUserBalance(ctx, userID, balance); err != nil {
 		log.Printf("Warning: set balance cache failed for user %d: %v", userID, err)
 	}
 }
 
 // DeductBalanceCache 扣减余额缓存（异步调用，用于扣费后更新缓存）
 func (s *BillingCacheService) DeductBalanceCache(ctx context.Context, userID int64, amount float64) error {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return nil
 	}
-
-	key := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
-
-	// 使用预编译的Lua脚本原子性扣减，如果key不存在则忽略
-	_, err := deductBalanceScript.Run(ctx, s.rdb, []string{key}, amount, int(billingCacheTTL.Seconds())).Result()
-	if err != nil && !errors.Is(err, redis.Nil) {
-		log.Printf("Warning: deduct balance cache failed for user %d: %v", userID, err)
-	}
-	return nil
+	return s.cache.DeductUserBalance(ctx, userID, amount)
 }
 
 // InvalidateUserBalance 失效用户余额缓存
 func (s *BillingCacheService) InvalidateUserBalance(ctx context.Context, userID int64) error {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return nil
 	}
-
-	key := fmt.Sprintf("%s%d", billingBalanceKeyPrefix, userID)
-	if err := s.rdb.Del(ctx, key).Err(); err != nil {
+	if err := s.cache.InvalidateUserBalance(ctx, userID); err != nil {
 		log.Printf("Warning: invalidate balance cache failed for user %d: %v", userID, err)
 		return err
 	}
@@ -188,19 +123,14 @@ func (s *BillingCacheService) InvalidateUserBalance(ctx context.Context, userID
 
 // GetSubscriptionStatus 获取订阅状态（优先从缓存读取）
 func (s *BillingCacheService) GetSubscriptionStatus(ctx context.Context, userID, groupID int64) (*subscriptionCacheData, error) {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return s.getSubscriptionFromDB(ctx, userID, groupID)
 	}
 
-	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
-
 	// 尝试从缓存读取
-	result, err := s.rdb.HGetAll(ctx, key).Result()
-	if err == nil && len(result) > 0 {
-		data, parseErr := s.parseSubscriptionCache(result)
-		if parseErr == nil {
-			return data, nil
-		}
+	cacheData, err := s.cache.GetSubscriptionCache(ctx, userID, groupID)
+	if err == nil && cacheData != nil {
+		return s.convertFromPortsData(cacheData), nil
 	}
 
 	// 缓存未命中，从数据库读取
@@ -219,6 +149,28 @@ func (s *BillingCacheService) GetSubscriptionStatus(ctx context.Context, userID,
 	return data, nil
 }
 
+func (s *BillingCacheService) convertFromPortsData(data *ports.SubscriptionCacheData) *subscriptionCacheData {
+	return &subscriptionCacheData{
+		Status:       data.Status,
+		ExpiresAt:    data.ExpiresAt,
+		DailyUsage:   data.DailyUsage,
+		WeeklyUsage:  data.WeeklyUsage,
+		MonthlyUsage: data.MonthlyUsage,
+		Version:      data.Version,
+	}
+}
+
+func (s *BillingCacheService) convertToPortsData(data *subscriptionCacheData) *ports.SubscriptionCacheData {
+	return &ports.SubscriptionCacheData{
+		Status:       data.Status,
+		ExpiresAt:    data.ExpiresAt,
+		DailyUsage:   data.DailyUsage,
+		WeeklyUsage:  data.WeeklyUsage,
+		MonthlyUsage: data.MonthlyUsage,
+		Version:      data.Version,
+	}
+}
+
 // getSubscriptionFromDB 从数据库获取订阅数据
 func (s *BillingCacheService) getSubscriptionFromDB(ctx context.Context, userID, groupID int64) (*subscriptionCacheData, error) {
 	sub, err := s.subRepo.GetActiveByUserIDAndGroupID(ctx, userID, groupID)
@@ -236,90 +188,30 @@ func (s *BillingCacheService) getSubscriptionFromDB(ctx context.Context, userID,
 	}, nil
 }
 
-// parseSubscriptionCache 解析订阅缓存数据
-func (s *BillingCacheService) parseSubscriptionCache(data map[string]string) (*subscriptionCacheData, error) {
-	result := &subscriptionCacheData{}
-
-	result.Status = data[subFieldStatus]
-	if result.Status == "" {
-		return nil, errors.New("invalid cache: missing status")
-	}
-
-	if expiresStr, ok := data[subFieldExpiresAt]; ok {
-		expiresAt, err := strconv.ParseInt(expiresStr, 10, 64)
-		if err == nil {
-			result.ExpiresAt = time.Unix(expiresAt, 0)
-		}
-	}
-
-	if dailyStr, ok := data[subFieldDailyUsage]; ok {
-		result.DailyUsage, _ = strconv.ParseFloat(dailyStr, 64)
-	}
-
-	if weeklyStr, ok := data[subFieldWeeklyUsage]; ok {
-		result.WeeklyUsage, _ = strconv.ParseFloat(weeklyStr, 64)
-	}
-
-	if monthlyStr, ok := data[subFieldMonthlyUsage]; ok {
-		result.MonthlyUsage, _ = strconv.ParseFloat(monthlyStr, 64)
-	}
-
-	if versionStr, ok := data[subFieldVersion]; ok {
-		result.Version, _ = strconv.ParseInt(versionStr, 10, 64)
-	}
-
-	return result, nil
-}
-
 // setSubscriptionCache 设置订阅缓存
 func (s *BillingCacheService) setSubscriptionCache(ctx context.Context, userID, groupID int64, data *subscriptionCacheData) {
-	if s.rdb == nil || data == nil {
+	if s.cache == nil || data == nil {
 		return
 	}
-
-	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
-
-	fields := map[string]interface{}{
-		subFieldStatus:       data.Status,
-		subFieldExpiresAt:    data.ExpiresAt.Unix(),
-		subFieldDailyUsage:   data.DailyUsage,
-		subFieldWeeklyUsage:  data.WeeklyUsage,
-		subFieldMonthlyUsage: data.MonthlyUsage,
-		subFieldVersion:      data.Version,
-	}
-
-	pipe := s.rdb.Pipeline()
-	pipe.HSet(ctx, key, fields)
-	pipe.Expire(ctx, key, billingCacheTTL)
-	if _, err := pipe.Exec(ctx); err != nil {
+	if err := s.cache.SetSubscriptionCache(ctx, userID, groupID, s.convertToPortsData(data)); err != nil {
 		log.Printf("Warning: set subscription cache failed for user %d group %d: %v", userID, groupID, err)
 	}
 }
 
 // UpdateSubscriptionUsage 更新订阅用量缓存（异步调用，用于扣费后更新缓存）
 func (s *BillingCacheService) UpdateSubscriptionUsage(ctx context.Context, userID, groupID int64, costUSD float64) error {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return nil
 	}
-
-	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
-
-	// 使用预编译的Lua脚本原子性增加用量，如果key不存在则忽略
-	_, err := updateSubUsageScript.Run(ctx, s.rdb, []string{key}, costUSD, int(billingCacheTTL.Seconds())).Result()
-	if err != nil && !errors.Is(err, redis.Nil) {
-		log.Printf("Warning: update subscription usage cache failed for user %d group %d: %v", userID, groupID, err)
-	}
-	return nil
+	return s.cache.UpdateSubscriptionUsage(ctx, userID, groupID, costUSD)
 }
 
 // InvalidateSubscription 失效指定订阅缓存
 func (s *BillingCacheService) InvalidateSubscription(ctx context.Context, userID, groupID int64) error {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return nil
 	}
-
-	key := fmt.Sprintf("%s%d:%d", billingSubKeyPrefix, userID, groupID)
-	if err := s.rdb.Del(ctx, key).Err(); err != nil {
+	if err := s.cache.InvalidateSubscriptionCache(ctx, userID, groupID); err != nil {
 		log.Printf("Warning: invalidate subscription cache failed for user %d group %d: %v", userID, groupID, err)
 		return err
 	}

backend/internal/service/billing_service.go

@@ -259,11 +259,11 @@ func (s *BillingService) GetEstimatedCost(model string, estimatedInputTokens, es
 }
 
 // GetPricingServiceStatus 获取价格服务状态
-func (s *BillingService) GetPricingServiceStatus() map[string]interface{} {
+func (s *BillingService) GetPricingServiceStatus() map[string]any {
 	if s.pricingService != nil {
 		return s.pricingService.GetStatus()
 	}
-	return map[string]interface{}{
+	return map[string]any{
 		"model_count":  len(s.fallbackPrices),
 		"last_updated": "using fallback",
 		"local_hash":   "N/A",

backend/internal/service/concurrency_service.go

@@ -2,101 +2,30 @@ package service
 
 import (
 	"context"
-	"fmt"
 	"log"
 	"time"
 
-	"github.com/redis/go-redis/v9"
+	"sub2api/internal/service/ports"
 )
 
 const (
-	// Redis key prefixes
-	accountConcurrencyKey = "concurrency:account:"
-	userConcurrencyKey    = "concurrency:user:"
-	userWaitCountKey      = "concurrency:wait:"
-
-	// TTL for concurrency keys (auto-release safety net)
-	concurrencyKeyTTL = 10 * time.Minute
-
-	// Wait polling interval
-	waitPollInterval = 100 * time.Millisecond
-
-	// Default max wait time
-	defaultMaxWait = 60 * time.Second
-
 	// Default extra wait slots beyond concurrency limit
 	defaultExtraWaitSlots = 20
 )
 
-// Pre-compiled Lua scripts for better performance
-var (
-	// acquireScript: increment counter if below max, return 1 if successful
-	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])
-			return 1
-		end
-		return 0
-	`)
-
-	// releaseScript: decrement counter, but don't go below 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
-	`)
-
-	// incrementWaitScript: increment wait counter if below max, return 1 if successful
-	incrementWaitScript = redis.NewScript(`
-		local waitKey = KEYS[1]
-		local maxWait = tonumber(ARGV[1])
-		local ttl = tonumber(ARGV[2])
-		local current = redis.call('GET', waitKey)
-		if current == false then
-			current = 0
-		else
-			current = tonumber(current)
-		end
-		if current >= maxWait then
-			return 0
-		end
-		redis.call('INCR', waitKey)
-		redis.call('EXPIRE', waitKey, ttl)
-		return 1
-	`)
-
-	// decrementWaitScript: decrement wait counter, but don't go below 0
-	decrementWaitScript = 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
-	`)
-)
-
 // ConcurrencyService manages concurrent request limiting for accounts and users
 type ConcurrencyService struct {
-	rdb *redis.Client
+	cache ports.ConcurrencyCache
 }
 
 // NewConcurrencyService creates a new ConcurrencyService
-func NewConcurrencyService(rdb *redis.Client) *ConcurrencyService {
-	return &ConcurrencyService{rdb: rdb}
+func NewConcurrencyService(cache ports.ConcurrencyCache) *ConcurrencyService {
+	return &ConcurrencyService{cache: cache}
 }
 
 // AcquireResult represents the result of acquiring a concurrency slot
 type AcquireResult struct {
-	Acquired   bool
+	Acquired    bool
 	ReleaseFunc func() // Must be called when done (typically via defer)
 }
 
@@ -104,20 +33,6 @@ type AcquireResult struct {
 // If the account is at max concurrency, it waits until a slot is available or timeout.
 // Returns a release function that MUST be called when the request completes.
 func (s *ConcurrencyService) AcquireAccountSlot(ctx context.Context, accountID int64, maxConcurrency int) (*AcquireResult, error) {
-	key := fmt.Sprintf("%s%d", accountConcurrencyKey, accountID)
-	return s.acquireSlot(ctx, key, maxConcurrency)
-}
-
-// AcquireUserSlot attempts to acquire a concurrency slot for a user.
-// If the user is at max concurrency, it waits until a slot is available or timeout.
-// Returns a release function that MUST be called when the request completes.
-func (s *ConcurrencyService) AcquireUserSlot(ctx context.Context, userID int64, maxConcurrency int) (*AcquireResult, error) {
-	key := fmt.Sprintf("%s%d", userConcurrencyKey, userID)
-	return s.acquireSlot(ctx, key, maxConcurrency)
-}
-
-// acquireSlot is the core implementation for acquiring a concurrency slot
-func (s *ConcurrencyService) acquireSlot(ctx context.Context, key string, maxConcurrency int) (*AcquireResult, error) {
 	// If maxConcurrency is 0 or negative, no limit
 	if maxConcurrency <= 0 {
 		return &AcquireResult{
@@ -126,73 +41,64 @@ func (s *ConcurrencyService) acquireSlot(ctx context.Context, key string, maxCon
 		}, nil
 	}
 
-	// Try to acquire immediately
-	acquired, err := s.tryAcquire(ctx, key, maxConcurrency)
+	acquired, err := s.cache.AcquireAccountSlot(ctx, accountID, maxConcurrency)
 	if err != nil {
 		return nil, err
 	}
 
 	if acquired {
 		return &AcquireResult{
-			Acquired:    true,
-			ReleaseFunc: s.makeReleaseFunc(key),
+			Acquired: true,
+			ReleaseFunc: func() {
+				bgCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+				defer cancel()
+				if err := s.cache.ReleaseAccountSlot(bgCtx, accountID); err != nil {
+					log.Printf("Warning: failed to release account slot for %d: %v", accountID, err)
+				}
+			},
 		}, nil
 	}
 
-	// Not acquired, return with Acquired=false
-	// The caller (gateway handler) will handle waiting with ping support
 	return &AcquireResult{
 		Acquired:    false,
 		ReleaseFunc: nil,
 	}, nil
 }
 
-// tryAcquire attempts to increment the counter if below max
-// Uses pre-compiled Lua script for atomicity and performance
-func (s *ConcurrencyService) tryAcquire(ctx context.Context, key string, maxConcurrency int) (bool, error) {
-	result, err := acquireScript.Run(ctx, s.rdb, []string{key}, maxConcurrency, int(concurrencyKeyTTL.Seconds())).Int()
+// AcquireUserSlot attempts to acquire a concurrency slot for a user.
+// If the user is at max concurrency, it waits until a slot is available or timeout.
+// Returns a release function that MUST be called when the request completes.
+func (s *ConcurrencyService) AcquireUserSlot(ctx context.Context, userID int64, maxConcurrency int) (*AcquireResult, error) {
+	// If maxConcurrency is 0 or negative, no limit
+	if maxConcurrency <= 0 {
+		return &AcquireResult{
+			Acquired:    true,
+			ReleaseFunc: func() {}, // no-op
+		}, nil
+	}
+
+	acquired, err := s.cache.AcquireUserSlot(ctx, userID, maxConcurrency)
 	if err != nil {
-		return false, fmt.Errorf("acquire slot failed: %w", err)
+		return nil, err
 	}
-	return result == 1, nil
-}
 
-// makeReleaseFunc creates a function to release a concurrency slot
-func (s *ConcurrencyService) makeReleaseFunc(key string) func() {
-	return func() {
-		// Use background context to ensure release even if original context is cancelled
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-		defer cancel()
-
-		if err := releaseScript.Run(ctx, s.rdb, []string{key}).Err(); err != nil {
-			// Log error but don't panic - TTL will eventually clean up
-			log.Printf("Warning: failed to release concurrency slot for %s: %v", key, err)
-		}
+	if acquired {
+		return &AcquireResult{
+			Acquired: true,
+			ReleaseFunc: func() {
+				bgCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+				defer cancel()
+				if err := s.cache.ReleaseUserSlot(bgCtx, userID); err != nil {
+					log.Printf("Warning: failed to release user slot for %d: %v", userID, err)
+				}
+			},
+		}, nil
 	}
-}
 
-// GetCurrentCount returns the current concurrency count for debugging/monitoring
-func (s *ConcurrencyService) GetCurrentCount(ctx context.Context, key string) (int, error) {
-	val, err := s.rdb.Get(ctx, key).Int()
-	if err == redis.Nil {
-		return 0, nil
-	}
-	if err != nil {
-		return 0, err
-	}
-	return val, nil
-}
-
-// GetAccountCurrentCount returns current concurrency count for an account
-func (s *ConcurrencyService) GetAccountCurrentCount(ctx context.Context, accountID int64) (int, error) {
-	key := fmt.Sprintf("%s%d", accountConcurrencyKey, accountID)
-	return s.GetCurrentCount(ctx, key)
-}
-
-// GetUserCurrentCount returns current concurrency count for a user
-func (s *ConcurrencyService) GetUserCurrentCount(ctx context.Context, userID int64) (int, error) {
-	key := fmt.Sprintf("%s%d", userConcurrencyKey, userID)
-	return s.GetCurrentCount(ctx, key)
+	return &AcquireResult{
+		Acquired:    false,
+		ReleaseFunc: nil,
+	}, nil
 }
 
 // ============================================
@@ -203,44 +109,36 @@ func (s *ConcurrencyService) GetUserCurrentCount(ctx context.Context, userID int
 // Returns true if successful, false if the wait queue is full.
 // maxWait should be user.Concurrency + defaultExtraWaitSlots
 func (s *ConcurrencyService) IncrementWaitCount(ctx context.Context, userID int64, maxWait int) (bool, error) {
-	if s.rdb == nil {
+	if s.cache == nil {
 		// Redis not available, allow request
 		return true, nil
 	}
 
-	key := fmt.Sprintf("%s%d", userWaitCountKey, userID)
-	result, err := incrementWaitScript.Run(ctx, s.rdb, []string{key}, maxWait, int(concurrencyKeyTTL.Seconds())).Int()
+	result, err := s.cache.IncrementWaitCount(ctx, userID, maxWait)
 	if err != nil {
 		// On error, allow the request to proceed (fail open)
 		log.Printf("Warning: increment wait count failed for user %d: %v", userID, err)
 		return true, nil
 	}
-	return result == 1, nil
+	return result, nil
 }
 
 // DecrementWaitCount decrements the wait queue counter for a user.
 // Should be called when a request completes or exits the wait queue.
 func (s *ConcurrencyService) DecrementWaitCount(ctx context.Context, userID int64) {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return
 	}
 
-	key := fmt.Sprintf("%s%d", userWaitCountKey, userID)
 	// Use background context to ensure decrement even if original context is cancelled
 	bgCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 
-	if err := decrementWaitScript.Run(bgCtx, s.rdb, []string{key}).Err(); err != nil {
+	if err := s.cache.DecrementWaitCount(bgCtx, userID); err != nil {
 		log.Printf("Warning: decrement wait count failed for user %d: %v", userID, err)
 	}
 }
 
-// GetUserWaitCount returns current wait queue count for a user
-func (s *ConcurrencyService) GetUserWaitCount(ctx context.Context, userID int64) (int, error) {
-	key := fmt.Sprintf("%s%d", userWaitCountKey, userID)
-	return s.GetCurrentCount(ctx, key)
-}
-
 // CalculateMaxWait calculates the maximum wait queue size for a user
 // maxWait = userConcurrency + defaultExtraWaitSlots
 func CalculateMaxWait(userConcurrency int) int {

backend/internal/service/email_service.go

@@ -4,17 +4,14 @@ import (
 	"context"
 	"crypto/rand"
 	"crypto/tls"
-	"encoding/json"
 	"errors"
 	"fmt"
 	"math/big"
 	"net/smtp"
 	"strconv"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/service/ports"
 	"time"
-
-	"github.com/redis/go-redis/v9"
 )
 
 var (
@@ -25,19 +22,11 @@ var (
 )
 
 const (
-	verifyCodeKeyPrefix  = "email_verify:"
-	verifyCodeTTL        = 15 * time.Minute
-	verifyCodeCooldown   = 1 * time.Minute
+	verifyCodeTTL         = 15 * time.Minute
+	verifyCodeCooldown    = 1 * time.Minute
 	maxVerifyCodeAttempts = 5
 )
 
-// verifyCodeData Redis 中存储的验证码数据
-type verifyCodeData struct {
-	Code      string    `json:"code"`
-	Attempts  int       `json:"attempts"`
-	CreatedAt time.Time `json:"created_at"`
-}
-
 // SmtpConfig SMTP配置
 type SmtpConfig struct {
 	Host     string
@@ -51,15 +40,15 @@ type SmtpConfig struct {
 
 // EmailService 邮件服务
 type EmailService struct {
-	settingRepo *repository.SettingRepository
-	rdb         *redis.Client
+	settingRepo ports.SettingRepository
+	cache       ports.EmailCache
 }
 
 // NewEmailService 创建邮件服务实例
-func NewEmailService(settingRepo *repository.SettingRepository, rdb *redis.Client) *EmailService {
+func NewEmailService(settingRepo ports.SettingRepository, cache ports.EmailCache) *EmailService {
 	return &EmailService{
 		settingRepo: settingRepo,
-		rdb:         rdb,
+		cache:       cache,
 	}
 }
 
@@ -144,13 +133,13 @@ func (s *EmailService) sendMailTLS(addr string, auth smtp.Auth, from, to string,
 	if err != nil {
 		return fmt.Errorf("tls dial: %w", err)
 	}
-	defer conn.Close()
+	defer func() { _ = conn.Close() }()
 
 	client, err := smtp.NewClient(conn, host)
 	if err != nil {
 		return fmt.Errorf("new smtp client: %w", err)
 	}
-	defer client.Close()
+	defer func() { _ = client.Close() }()
 
 	if err = client.Auth(auth); err != nil {
 		return fmt.Errorf("smtp auth: %w", err)
@@ -201,10 +190,8 @@ func (s *EmailService) GenerateVerifyCode() (string, error) {
 
 // SendVerifyCode 发送验证码邮件
 func (s *EmailService) SendVerifyCode(ctx context.Context, email, siteName string) error {
-	key := verifyCodeKeyPrefix + email
-
 	// 检查是否在冷却期内
-	existing, err := s.getVerifyCodeData(ctx, key)
+	existing, err := s.cache.GetVerificationCode(ctx, email)
 	if err == nil && existing != nil {
 		if time.Since(existing.CreatedAt) < verifyCodeCooldown {
 			return ErrVerifyCodeTooFrequent
@@ -218,12 +205,12 @@ func (s *EmailService) SendVerifyCode(ctx context.Context, email, siteName strin
 	}
 
 	// 保存验证码到 Redis
-	data := &verifyCodeData{
+	data := &ports.VerificationCodeData{
 		Code:      code,
 		Attempts:  0,
 		CreatedAt: time.Now(),
 	}
-	if err := s.setVerifyCodeData(ctx, key, data); err != nil {
+	if err := s.cache.SetVerificationCode(ctx, email, data, verifyCodeTTL); err != nil {
 		return fmt.Errorf("save verify code: %w", err)
 	}
 
@@ -241,9 +228,7 @@ func (s *EmailService) SendVerifyCode(ctx context.Context, email, siteName strin
 
 // VerifyCode 验证验证码
 func (s *EmailService) VerifyCode(ctx context.Context, email, code string) error {
-	key := verifyCodeKeyPrefix + email
-
-	data, err := s.getVerifyCodeData(ctx, key)
+	data, err := s.cache.GetVerificationCode(ctx, email)
 	if err != nil || data == nil {
 		return ErrInvalidVerifyCode
 	}
@@ -256,7 +241,7 @@ func (s *EmailService) VerifyCode(ctx context.Context, email, code string) error
 	// 验证码不匹配
 	if data.Code != code {
 		data.Attempts++
-		_ = s.setVerifyCodeData(ctx, key, data)
+		_ = s.cache.SetVerificationCode(ctx, email, data, verifyCodeTTL)
 		if data.Attempts >= maxVerifyCodeAttempts {
 			return ErrVerifyCodeMaxAttempts
 		}
@@ -264,32 +249,10 @@ func (s *EmailService) VerifyCode(ctx context.Context, email, code string) error
 	}
 
 	// 验证成功，删除验证码
-	s.rdb.Del(ctx, key)
+	_ = s.cache.DeleteVerificationCode(ctx, email)
 	return nil
 }
 
-// getVerifyCodeData 从 Redis 获取验证码数据
-func (s *EmailService) getVerifyCodeData(ctx context.Context, key string) (*verifyCodeData, error) {
-	val, err := s.rdb.Get(ctx, key).Result()
-	if err != nil {
-		return nil, err
-	}
-	var data verifyCodeData
-	if err := json.Unmarshal([]byte(val), &data); err != nil {
-		return nil, err
-	}
-	return &data, nil
-}
-
-// setVerifyCodeData 保存验证码数据到 Redis
-func (s *EmailService) setVerifyCodeData(ctx context.Context, key string, data *verifyCodeData) error {
-	val, err := json.Marshal(data)
-	if err != nil {
-		return err
-	}
-	return s.rdb.Set(ctx, key, val, verifyCodeTTL).Err()
-}
-
 // buildVerifyCodeEmailBody 构建验证码邮件HTML内容
 func (s *EmailService) buildVerifyCodeEmailBody(code, siteName string) string {
 	return fmt.Sprintf(`
@@ -340,13 +303,13 @@ func (s *EmailService) TestSmtpConnectionWithConfig(config *SmtpConfig) error {
 		if err != nil {
 			return fmt.Errorf("tls connection failed: %w", err)
 		}
-		defer conn.Close()
+		defer func() { _ = conn.Close() }()
 
 		client, err := smtp.NewClient(conn, config.Host)
 		if err != nil {
 			return fmt.Errorf("smtp client creation failed: %w", err)
 		}
-		defer client.Close()
+		defer func() { _ = client.Close() }()
 
 		auth := smtp.PlainAuth("", config.Username, config.Password, config.Host)
 		if err = client.Auth(auth); err != nil {
@@ -361,7 +324,7 @@ func (s *EmailService) TestSmtpConnectionWithConfig(config *SmtpConfig) error {
 	if err != nil {
 		return fmt.Errorf("smtp connection failed: %w", err)
 	}
-	defer client.Close()
+	defer func() { _ = client.Close() }()
 
 	auth := smtp.PlainAuth("", config.Username, config.Password, config.Host)
 	if err = client.Auth(auth); err != nil {

backend/internal/service/gateway_service.go

@@ -12,25 +12,27 @@ import (
 	"io"
 	"log"
 	"net/http"
-	"net/url"
 	"regexp"
-	"strconv"
 	"strings"
 	"time"
 
 	"sub2api/internal/config"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/pkg/claude"
+	"sub2api/internal/service/ports"
 
 	"github.com/gin-gonic/gin"
-	"github.com/redis/go-redis/v9"
 )
 
+// ClaudeUpstream handles HTTP requests to Claude API
+type ClaudeUpstream interface {
+	Do(req *http.Request, proxyURL string) (*http.Response, error)
+}
+
 const (
-	claudeAPIURL        = "https://api.anthropic.com/v1/messages?beta=true"
-	stickySessionPrefix = "sticky_session:"
-	stickySessionTTL    = time.Hour // 粘性会话TTL
-	tokenRefreshBuffer  = 5 * 60    // 提前5分钟刷新token
+	claudeAPIURL            = "https://api.anthropic.com/v1/messages?beta=true"
+	claudeAPICountTokensURL = "https://api.anthropic.com/v1/messages/count_tokens?beta=true"
+	stickySessionTTL        = time.Hour // 粘性会话TTL
 )
 
 // allowedHeaders 白名单headers（参考CRS项目）
@@ -51,7 +53,6 @@ var allowedHeaders = map[string]bool{
 	"anthropic-beta":                            true,
 	"accept-language":                           true,
 	"sec-fetch-mode":                            true,
-	"accept-encoding":                           true,
 	"user-agent":                                true,
 	"content-type":                              true,
 }
@@ -76,58 +77,57 @@ type ForwardResult struct {
 
 // GatewayService handles API gateway operations
 type GatewayService struct {
-	repos               *repository.Repositories
-	rdb                 *redis.Client
+	accountRepo         ports.AccountRepository
+	usageLogRepo        ports.UsageLogRepository
+	userRepo            ports.UserRepository
+	userSubRepo         ports.UserSubscriptionRepository
+	cache               ports.GatewayCache
 	cfg                 *config.Config
-	oauthService        *OAuthService
 	billingService      *BillingService
 	rateLimitService    *RateLimitService
 	billingCacheService *BillingCacheService
 	identityService     *IdentityService
-	httpClient          *http.Client
+	claudeUpstream      ClaudeUpstream
 }
 
 // NewGatewayService creates a new GatewayService
-func NewGatewayService(repos *repository.Repositories, rdb *redis.Client, cfg *config.Config, oauthService *OAuthService, billingService *BillingService, rateLimitService *RateLimitService, billingCacheService *BillingCacheService, identityService *IdentityService) *GatewayService {
-	// 计算响应头超时时间
-	responseHeaderTimeout := time.Duration(cfg.Gateway.ResponseHeaderTimeout) * time.Second
-	if responseHeaderTimeout == 0 {
-		responseHeaderTimeout = 300 * time.Second // 默认5分钟，LLM高负载时可能排队较久
-	}
-
-	transport := &http.Transport{
-		MaxIdleConns:          100,
-		MaxIdleConnsPerHost:   10,
-		IdleConnTimeout:       90 * time.Second,
-		ResponseHeaderTimeout: responseHeaderTimeout, // 等待上游响应头的超时
-		// 注意：不设置整体 Timeout，让流式响应可以无限时间传输
-	}
+func NewGatewayService(
+	accountRepo ports.AccountRepository,
+	usageLogRepo ports.UsageLogRepository,
+	userRepo ports.UserRepository,
+	userSubRepo ports.UserSubscriptionRepository,
+	cache ports.GatewayCache,
+	cfg *config.Config,
+	billingService *BillingService,
+	rateLimitService *RateLimitService,
+	billingCacheService *BillingCacheService,
+	identityService *IdentityService,
+	claudeUpstream ClaudeUpstream,
+) *GatewayService {
 	return &GatewayService{
-		repos:               repos,
-		rdb:                 rdb,
+		accountRepo:         accountRepo,
+		usageLogRepo:        usageLogRepo,
+		userRepo:            userRepo,
+		userSubRepo:         userSubRepo,
+		cache:               cache,
 		cfg:                 cfg,
-		oauthService:        oauthService,
 		billingService:      billingService,
 		rateLimitService:    rateLimitService,
 		billingCacheService: billingCacheService,
 		identityService:     identityService,
-		httpClient: &http.Client{
-			Transport: transport,
-			// 不设置 Timeout：流式请求可能持续十几分钟
-			// 超时控制由 Transport.ResponseHeaderTimeout 负责（只控制等待响应头）
-		},
+		claudeUpstream:      claudeUpstream,
 	}
 }
 
 // GenerateSessionHash 从请求体计算粘性会话hash
 func (s *GatewayService) GenerateSessionHash(body []byte) string {
-	var req map[string]interface{}
+	var req map[string]any
 	if err := json.Unmarshal(body, &req); err != nil {
 		return ""
 	}
 
 	// 1. 最高优先级：从metadata.user_id提取session_xxx
-	if metadata, ok := req["metadata"].(map[string]interface{}); ok {
+	if metadata, ok := req["metadata"].(map[string]any); ok {
 		if userID, ok := metadata["user_id"].(string); ok {
 			re := regexp.MustCompile(`session_([a-f0-9-]{36})`)
 			if match := re.FindStringSubmatch(userID); len(match) > 1 {
@@ -151,8 +151,8 @@ func (s *GatewayService) GenerateSessionHash(body []byte) string {
 	}
 
 	// 4. 最后fallback: 使用第一条消息
-	if messages, ok := req["messages"].([]interface{}); ok && len(messages) > 0 {
-		if firstMsg, ok := messages[0].(map[string]interface{}); ok {
+	if messages, ok := req["messages"].([]any); ok && len(messages) > 0 {
+		if firstMsg, ok := messages[0].(map[string]any); ok {
 			msgText := s.extractTextFromContent(firstMsg["content"])
 			if msgText != "" {
 				return s.hashContent(msgText)
@@ -163,14 +163,14 @@ func (s *GatewayService) GenerateSessionHash(body []byte) string {
 	return ""
 }
 
-func (s *GatewayService) extractCacheableContent(req map[string]interface{}) string {
+func (s *GatewayService) extractCacheableContent(req map[string]any) string {
 	var content string
 
 	// 检查system中的cacheable内容
-	if system, ok := req["system"].([]interface{}); ok {
+	if system, ok := req["system"].([]any); ok {
 		for _, part := range system {
-			if partMap, ok := part.(map[string]interface{}); ok {
-				if cc, ok := partMap["cache_control"].(map[string]interface{}); ok {
+			if partMap, ok := part.(map[string]any); ok {
+				if cc, ok := partMap["cache_control"].(map[string]any); ok {
 					if cc["type"] == "ephemeral" {
 						if text, ok := partMap["text"].(string); ok {
 							content += text
@@ -182,13 +182,13 @@ func (s *GatewayService) extractCacheableContent(req map[string]interface{}) str
 	}
 
 	// 检查messages中的cacheable内容
-	if messages, ok := req["messages"].([]interface{}); ok {
+	if messages, ok := req["messages"].([]any); ok {
 		for _, msg := range messages {
-			if msgMap, ok := msg.(map[string]interface{}); ok {
-				if msgContent, ok := msgMap["content"].([]interface{}); ok {
+			if msgMap, ok := msg.(map[string]any); ok {
+				if msgContent, ok := msgMap["content"].([]any); ok {
 					for _, part := range msgContent {
-						if partMap, ok := part.(map[string]interface{}); ok {
-							if cc, ok := partMap["cache_control"].(map[string]interface{}); ok {
+						if partMap, ok := part.(map[string]any); ok {
+							if cc, ok := partMap["cache_control"].(map[string]any); ok {
 								if cc["type"] == "ephemeral" {
 									// 找到cacheable内容，提取第一条消息的文本
 									return s.extractTextFromContent(msgMap["content"])
@@ -204,14 +204,14 @@ func (s *GatewayService) extractCacheableContent(req map[string]interface{}) str
 	return content
 }
 
-func (s *GatewayService) extractTextFromSystem(system interface{}) string {
+func (s *GatewayService) extractTextFromSystem(system any) string {
 	switch v := system.(type) {
 	case string:
 		return v
-	case []interface{}:
+	case []any:
 		var texts []string
 		for _, part := range v {
-			if partMap, ok := part.(map[string]interface{}); ok {
+			if partMap, ok := part.(map[string]any); ok {
 				if text, ok := partMap["text"].(string); ok {
 					texts = append(texts, text)
 				}
@@ -222,14 +222,14 @@ func (s *GatewayService) extractTextFromSystem(system interface{}) string {
 	return ""
 }
 
-func (s *GatewayService) extractTextFromContent(content interface{}) string {
+func (s *GatewayService) extractTextFromContent(content any) string {
 	switch v := content.(type) {
 	case string:
 		return v
-	case []interface{}:
+	case []any:
 		var texts []string
 		for _, part := range v {
-			if partMap, ok := part.(map[string]interface{}); ok {
+			if partMap, ok := part.(map[string]any); ok {
 				if partMap["type"] == "text" {
 					if text, ok := partMap["text"].(string); ok {
 						texts = append(texts, text)
@@ -249,7 +249,7 @@ func (s *GatewayService) hashContent(content string) string {
 
 // replaceModelInBody 替换请求体中的model字段
 func (s *GatewayService) replaceModelInBody(body []byte, newModel string) []byte {
-	var req map[string]interface{}
+	var req map[string]any
 	if err := json.Unmarshal(body, &req); err != nil {
 		return body
 	}
@@ -270,14 +270,16 @@ func (s *GatewayService) SelectAccount(ctx context.Context, groupID *int64, sess
 func (s *GatewayService) SelectAccountForModel(ctx context.Context, groupID *int64, sessionHash string, requestedModel string) (*model.Account, error) {
 	// 1. 查询粘性会话
 	if sessionHash != "" {
-		accountID, err := s.rdb.Get(ctx, stickySessionPrefix+sessionHash).Int64()
+		accountID, err := s.cache.GetSessionAccountID(ctx, sessionHash)
 		if err == nil && accountID > 0 {
-			account, err := s.repos.Account.GetByID(ctx, accountID)
+			account, err := s.accountRepo.GetByID(ctx, accountID)
 			// 使用IsSchedulable代替IsActive，确保限流/过载账号不会被选中
 			// 同时检查模型支持
 			if err == nil && account.IsSchedulable() && (requestedModel == "" || account.IsModelSupported(requestedModel)) {
 				// 续期粘性会话
-				s.rdb.Expire(ctx, stickySessionPrefix+sessionHash, stickySessionTTL)
+				if err := s.cache.RefreshSessionTTL(ctx, sessionHash, stickySessionTTL); err != nil {
+					log.Printf("refresh session ttl failed: session=%s err=%v", sessionHash, err)
+				}
 				return account, nil
 			}
 		}
@@ -287,9 +289,9 @@ func (s *GatewayService) SelectAccountForModel(ctx context.Context, groupID *int
 	var accounts []model.Account
 	var err error
 	if groupID != nil {
-		accounts, err = s.repos.Account.ListSchedulableByGroupID(ctx, *groupID)
+		accounts, err = s.accountRepo.ListSchedulableByGroupID(ctx, *groupID)
 	} else {
-		accounts, err = s.repos.Account.ListSchedulable(ctx)
+		accounts, err = s.accountRepo.ListSchedulable(ctx)
 	}
 	if err != nil {
 		return nil, fmt.Errorf("query accounts failed: %w", err)
@@ -327,7 +329,9 @@ func (s *GatewayService) SelectAccountForModel(ctx context.Context, groupID *int
 
 	// 4. 建立粘性绑定
 	if sessionHash != "" {
-		s.rdb.Set(ctx, stickySessionPrefix+sessionHash, selected.ID, stickySessionTTL)
+		if err := s.cache.SetSessionAccountID(ctx, sessionHash, selected.ID, stickySessionTTL); err != nil {
+			log.Printf("set session account failed: session=%s account_id=%d err=%v", sessionHash, selected.ID, err)
+		}
 	}
 
 	return selected, nil
@@ -352,37 +356,10 @@ func (s *GatewayService) GetAccessToken(ctx context.Context, account *model.Acco
 
 func (s *GatewayService) getOAuthToken(ctx context.Context, account *model.Account) (string, string, error) {
 	accessToken := account.GetCredential("access_token")
-	expiresAtStr := account.GetCredential("expires_at")
-
-	// 检查是否需要刷新
-	needRefresh := false
-	if expiresAtStr != "" {
-		expiresAt, err := strconv.ParseInt(expiresAtStr, 10, 64)
-		if err == nil && time.Now().Unix()+tokenRefreshBuffer > expiresAt {
-			needRefresh = true
-		}
+	if accessToken == "" {
+		return "", "", errors.New("access_token not found in credentials")
 	}
-
-	if needRefresh || accessToken == "" {
-		tokenInfo, err := s.oauthService.RefreshAccountToken(ctx, account)
-		if err != nil {
-			return "", "", fmt.Errorf("refresh token failed: %w", err)
-		}
-
-		// 更新账号凭证
-		account.Credentials["access_token"] = tokenInfo.AccessToken
-		account.Credentials["expires_at"] = strconv.FormatInt(tokenInfo.ExpiresAt, 10)
-		if tokenInfo.RefreshToken != "" {
-			account.Credentials["refresh_token"] = tokenInfo.RefreshToken
-		}
-
-		if err := s.repos.Account.Update(ctx, account); err != nil {
-			log.Printf("Failed to update account credentials: %v", err)
-		}
-
-		return tokenInfo.AccessToken, "oauth", nil
-	}
-
+	// Token刷新由后台 TokenRefreshService 处理，此处只返回当前token
 	return accessToken, "oauth", nil
 }
 
@@ -418,48 +395,25 @@ func (s *GatewayService) Forward(ctx context.Context, c *gin.Context, account *m
 	}
 
 	// 构建上游请求
-	upstreamResult, err := s.buildUpstreamRequest(ctx, c, account, body, token, tokenType)
+	upstreamReq, err := s.buildUpstreamRequest(ctx, c, account, body, token, tokenType)
 	if err != nil {
 		return nil, err
 	}
 
-	// 选择使用的client：如果有代理则使用独立的client，否则使用共享的httpClient
-	httpClient := s.httpClient
-	if upstreamResult.Client != nil {
-		httpClient = upstreamResult.Client
+	// 获取代理URL
+	proxyURL := ""
+	if account.ProxyID != nil && account.Proxy != nil {
+		proxyURL = account.Proxy.URL()
 	}
 
 	// 发送请求
-	resp, err := httpClient.Do(upstreamResult.Request)
+	resp, err := s.claudeUpstream.Do(upstreamReq, proxyURL)
 	if err != nil {
 		return nil, fmt.Errorf("upstream request failed: %w", err)
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 
-	// 处理401错误：刷新token重试
-	if resp.StatusCode == http.StatusUnauthorized && tokenType == "oauth" {
-		resp.Body.Close()
-		token, tokenType, err = s.forceRefreshToken(ctx, account)
-		if err != nil {
-			return nil, fmt.Errorf("token refresh failed: %w", err)
-		}
-		upstreamResult, err = s.buildUpstreamRequest(ctx, c, account, body, token, tokenType)
-		if err != nil {
-			return nil, err
-		}
-		// 重试时也需要使用正确的client
-		httpClient = s.httpClient
-		if upstreamResult.Client != nil {
-			httpClient = upstreamResult.Client
-		}
-		resp, err = httpClient.Do(upstreamResult.Request)
-		if err != nil {
-			return nil, fmt.Errorf("retry request failed: %w", err)
-		}
-		defer resp.Body.Close()
-	}
-
-	// 处理错误响应
+	// 处理错误响应（包括401，由后台TokenRefreshService维护token有效性）
 	if resp.StatusCode >= 400 {
 		return s.handleErrorResponse(ctx, resp, c, account)
 	}
@@ -491,13 +445,7 @@ func (s *GatewayService) Forward(ctx context.Context, c *gin.Context, account *m
 	}, nil
 }
 
-// buildUpstreamRequestResult contains the request and optional custom client for proxy
-type buildUpstreamRequestResult struct {
-	Request *http.Request
-	Client  *http.Client // nil means use default s.httpClient
-}
-
-func (s *GatewayService) buildUpstreamRequest(ctx context.Context, c *gin.Context, account *model.Account, body []byte, token, tokenType string) (*buildUpstreamRequestResult, error) {
+func (s *GatewayService) buildUpstreamRequest(ctx context.Context, c *gin.Context, account *model.Account, body []byte, token, tokenType string) (*http.Request, error) {
 	// 确定目标URL
 	targetURL := claudeAPIURL
 	if account.Type == model.AccountTypeApiKey {
@@ -506,7 +454,7 @@ func (s *GatewayService) buildUpstreamRequest(ctx context.Context, c *gin.Contex
 	}
 
 	// OAuth账号：应用统一指纹
-	var fingerprint *Fingerprint
+	var fingerprint *ports.Fingerprint
 	if account.IsOAuth() && s.identityService != nil {
 		// 1. 获取或创建指纹（包含随机生成的ClientID）
 		fp, err := s.identityService.GetOrCreateFingerprint(ctx, account.ID, c.Request.Header)
@@ -566,48 +514,16 @@ func (s *GatewayService) buildUpstreamRequest(ctx context.Context, c *gin.Contex
 		req.Header.Set("anthropic-beta", s.getBetaHeader(body, c.GetHeader("anthropic-beta")))
 	}
 
-	// 配置代理 - 创建独立的client避免并发修改共享httpClient
-	var customClient *http.Client
-	if account.ProxyID != nil && account.Proxy != nil {
-		proxyURL := account.Proxy.URL()
-		if proxyURL != "" {
-			if parsedURL, err := url.Parse(proxyURL); err == nil {
-				// 计算响应头超时时间（与默认 Transport 保持一致）
-				responseHeaderTimeout := time.Duration(s.cfg.Gateway.ResponseHeaderTimeout) * time.Second
-				if responseHeaderTimeout == 0 {
-					responseHeaderTimeout = 300 * time.Second
-				}
-				transport := &http.Transport{
-					Proxy:                 http.ProxyURL(parsedURL),
-					MaxIdleConns:          100,
-					MaxIdleConnsPerHost:   10,
-					IdleConnTimeout:       90 * time.Second,
-					ResponseHeaderTimeout: responseHeaderTimeout,
-				}
-				// 创建独立的client，避免并发时修改共享的s.httpClient.Transport
-				customClient = &http.Client{
-					Transport: transport,
-				}
-			}
-		}
-	}
-
-	return &buildUpstreamRequestResult{
-		Request: req,
-		Client:  customClient,
-	}, nil
+	return req, nil
 }
 
 // getBetaHeader 处理anthropic-beta header
 // 对于OAuth账号，需要确保包含oauth-2025-04-20
 func (s *GatewayService) getBetaHeader(body []byte, clientBetaHeader string) string {
-	const oauthBeta = "oauth-2025-04-20"
-	const claudeCodeBeta = "claude-code-20250219"
-
 	// 如果客户端传了anthropic-beta
 	if clientBetaHeader != "" {
 		// 已包含oauth beta则直接返回
-		if strings.Contains(clientBetaHeader, oauthBeta) {
+		if strings.Contains(clientBetaHeader, claude.BetaOAuth) {
 			return clientBetaHeader
 		}
 
@@ -620,7 +536,7 @@ func (s *GatewayService) getBetaHeader(body []byte, clientBetaHeader string) str
 		// 在claude-code-20250219后面插入oauth beta
 		claudeCodeIdx := -1
 		for i, p := range parts {
-			if p == claudeCodeBeta {
+			if p == claude.BetaClaudeCode {
 				claudeCodeIdx = i
 				break
 			}
@@ -630,18 +546,18 @@ func (s *GatewayService) getBetaHeader(body []byte, clientBetaHeader string) str
 			// 在claude-code后面插入
 			newParts := make([]string, 0, len(parts)+1)
 			newParts = append(newParts, parts[:claudeCodeIdx+1]...)
-			newParts = append(newParts, oauthBeta)
+			newParts = append(newParts, claude.BetaOAuth)
 			newParts = append(newParts, parts[claudeCodeIdx+1:]...)
 			return strings.Join(newParts, ",")
 		}
 
 		// 没有claude-code，放在第一位
-		return oauthBeta + "," + clientBetaHeader
+		return claude.BetaOAuth + "," + clientBetaHeader
 	}
 
 	// 客户端没传，根据模型生成
 	var modelID string
-	var reqMap map[string]interface{}
+	var reqMap map[string]any
 	if json.Unmarshal(body, &reqMap) == nil {
 		if m, ok := reqMap["model"].(string); ok {
 			modelID = m
@@ -650,29 +566,10 @@ func (s *GatewayService) getBetaHeader(body []byte, clientBetaHeader string) str
 
 	// haiku模型不需要claude-code beta
 	if strings.Contains(strings.ToLower(modelID), "haiku") {
-		return "oauth-2025-04-20,interleaved-thinking-2025-05-14"
+		return claude.HaikuBetaHeader
 	}
 
-	return "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14"
-}
-
-func (s *GatewayService) forceRefreshToken(ctx context.Context, account *model.Account) (string, string, error) {
-	tokenInfo, err := s.oauthService.RefreshAccountToken(ctx, account)
-	if err != nil {
-		return "", "", err
-	}
-
-	account.Credentials["access_token"] = tokenInfo.AccessToken
-	account.Credentials["expires_at"] = strconv.FormatInt(tokenInfo.ExpiresAt, 10)
-	if tokenInfo.RefreshToken != "" {
-		account.Credentials["refresh_token"] = tokenInfo.RefreshToken
-	}
-
-	if err := s.repos.Account.Update(ctx, account); err != nil {
-		log.Printf("Failed to update account credentials: %v", err)
-	}
-
-	return tokenInfo.AccessToken, "oauth", nil
+	return claude.DefaultBetaHeader
 }
 
 func (s *GatewayService) handleErrorResponse(ctx context.Context, resp *http.Response, c *gin.Context, account *model.Account) (*ForwardResult, error) {
@@ -781,7 +678,9 @@ func (s *GatewayService) handleStreamingResponse(ctx context.Context, resp *http
 		}
 
 		// 转发行
-		fmt.Fprintf(w, "%s\n", line)
+		if _, err := fmt.Fprintf(w, "%s\n", line); err != nil {
+			return &streamingResult{usage: usage, firstTokenMs: firstTokenMs}, err
+		}
 		flusher.Flush()
 
 		// 解析usage数据
@@ -810,7 +709,7 @@ func (s *GatewayService) replaceModelInSSELine(line, fromModel, toModel string)
 		return line
 	}
 
-	var event map[string]interface{}
+	var event map[string]any
 	if err := json.Unmarshal([]byte(data), &event); err != nil {
 		return line
 	}
@@ -820,7 +719,7 @@ func (s *GatewayService) replaceModelInSSELine(line, fromModel, toModel string)
 		return line
 	}
 
-	msg, ok := event["message"].(map[string]interface{})
+	msg, ok := event["message"].(map[string]any)
 	if !ok {
 		return line
 	}
@@ -902,7 +801,7 @@ func (s *GatewayService) handleNonStreamingResponse(ctx context.Context, resp *h
 
 // replaceModelInResponseBody 替换响应体中的model字段
 func (s *GatewayService) replaceModelInResponseBody(body []byte, fromModel, toModel string) []byte {
-	var resp map[string]interface{}
+	var resp map[string]any
 	if err := json.Unmarshal(body, &resp); err != nil {
 		return body
 	}
@@ -1000,7 +899,7 @@ func (s *GatewayService) RecordUsage(ctx context.Context, input *RecordUsageInpu
 		usageLog.SubscriptionID = &subscription.ID
 	}
 
-	if err := s.repos.UsageLog.Create(ctx, usageLog); err != nil {
+	if err := s.usageLogRepo.Create(ctx, usageLog); err != nil {
 		log.Printf("Create usage log failed: %v", err)
 	}
 
@@ -1008,7 +907,7 @@ func (s *GatewayService) RecordUsage(ctx context.Context, input *RecordUsageInpu
 	if isSubscriptionBilling {
 		// 订阅模式：更新订阅用量（使用 TotalCost 原始费用，不考虑倍率）
 		if cost.TotalCost > 0 {
-			if err := s.repos.UserSubscription.IncrementUsage(ctx, subscription.ID, cost.TotalCost); err != nil {
+			if err := s.userSubRepo.IncrementUsage(ctx, subscription.ID, cost.TotalCost); err != nil {
 				log.Printf("Increment subscription usage failed: %v", err)
 			}
 			// 异步更新订阅缓存
@@ -1023,7 +922,7 @@ func (s *GatewayService) RecordUsage(ctx context.Context, input *RecordUsageInpu
 	} else {
 		// 余额模式：扣除用户余额（使用 ActualCost 考虑倍率后的费用）
 		if cost.ActualCost > 0 {
-			if err := s.repos.User.DeductBalance(ctx, user.ID, cost.ActualCost); err != nil {
+			if err := s.userRepo.DeductBalance(ctx, user.ID, cost.ActualCost); err != nil {
 				log.Printf("Deduct balance failed: %v", err)
 			}
 			// 异步更新余额缓存
@@ -1038,9 +937,164 @@ func (s *GatewayService) RecordUsage(ctx context.Context, input *RecordUsageInpu
 	}
 
 	// 更新账号最后使用时间
-	if err := s.repos.Account.UpdateLastUsed(ctx, account.ID); err != nil {
+	if err := s.accountRepo.UpdateLastUsed(ctx, account.ID); err != nil {
 		log.Printf("Update last used failed: %v", err)
 	}
 
 	return nil
 }
+
+// ForwardCountTokens 转发 count_tokens 请求到上游 API
+// 特点：不记录使用量、仅支持非流式响应
+func (s *GatewayService) ForwardCountTokens(ctx context.Context, c *gin.Context, account *model.Account, body []byte) error {
+	// 应用模型映射（仅对 apikey 类型账号）
+	if account.Type == model.AccountTypeApiKey {
+		var req struct {
+			Model string `json:"model"`
+		}
+		if err := json.Unmarshal(body, &req); err == nil && req.Model != "" {
+			mappedModel := account.GetMappedModel(req.Model)
+			if mappedModel != req.Model {
+				body = s.replaceModelInBody(body, mappedModel)
+				log.Printf("CountTokens model mapping applied: %s -> %s (account: %s)", req.Model, mappedModel, account.Name)
+			}
+		}
+	}
+
+	// 获取凭证
+	token, tokenType, err := s.GetAccessToken(ctx, account)
+	if err != nil {
+		s.countTokensError(c, http.StatusBadGateway, "upstream_error", "Failed to get access token")
+		return err
+	}
+
+	// 构建上游请求
+	upstreamReq, err := s.buildCountTokensRequest(ctx, c, account, body, token, tokenType)
+	if err != nil {
+		s.countTokensError(c, http.StatusInternalServerError, "api_error", "Failed to build request")
+		return err
+	}
+
+	// 获取代理URL
+	proxyURL := ""
+	if account.ProxyID != nil && account.Proxy != nil {
+		proxyURL = account.Proxy.URL()
+	}
+
+	// 发送请求
+	resp, err := s.claudeUpstream.Do(upstreamReq, proxyURL)
+	if err != nil {
+		s.countTokensError(c, http.StatusBadGateway, "upstream_error", "Request failed")
+		return fmt.Errorf("upstream request failed: %w", err)
+	}
+	defer func() {
+		_ = resp.Body.Close()
+	}()
+
+	// 读取响应体
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		s.countTokensError(c, http.StatusBadGateway, "upstream_error", "Failed to read response")
+		return err
+	}
+
+	// 处理错误响应
+	if resp.StatusCode >= 400 {
+		// 标记账号状态（429/529等）
+		s.rateLimitService.HandleUpstreamError(ctx, account, resp.StatusCode, resp.Header, respBody)
+
+		// 返回简化的错误响应
+		errMsg := "Upstream request failed"
+		switch resp.StatusCode {
+		case 429:
+			errMsg = "Rate limit exceeded"
+		case 529:
+			errMsg = "Service overloaded"
+		}
+		s.countTokensError(c, resp.StatusCode, "upstream_error", errMsg)
+		return fmt.Errorf("upstream error: %d", resp.StatusCode)
+	}
+
+	// 透传成功响应
+	c.Data(resp.StatusCode, "application/json", respBody)
+	return nil
+}
+
+// buildCountTokensRequest 构建 count_tokens 上游请求
+func (s *GatewayService) buildCountTokensRequest(ctx context.Context, c *gin.Context, account *model.Account, body []byte, token, tokenType string) (*http.Request, error) {
+	// 确定目标 URL
+	targetURL := claudeAPICountTokensURL
+	if account.Type == model.AccountTypeApiKey {
+		baseURL := account.GetBaseURL()
+		targetURL = baseURL + "/v1/messages/count_tokens"
+	}
+
+	// OAuth 账号：应用统一指纹和重写 userID
+	if account.IsOAuth() && s.identityService != nil {
+		fp, err := s.identityService.GetOrCreateFingerprint(ctx, account.ID, c.Request.Header)
+		if err == nil {
+			accountUUID := account.GetExtraString("account_uuid")
+			if accountUUID != "" && fp.ClientID != "" {
+				if newBody, err := s.identityService.RewriteUserID(body, account.ID, accountUUID, fp.ClientID); err == nil && len(newBody) > 0 {
+					body = newBody
+				}
+			}
+		}
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", targetURL, bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+
+	// 设置认证头
+	if tokenType == "oauth" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	} else {
+		req.Header.Set("x-api-key", token)
+	}
+
+	// 白名单透传 headers
+	for key, values := range c.Request.Header {
+		lowerKey := strings.ToLower(key)
+		if allowedHeaders[lowerKey] {
+			for _, v := range values {
+				req.Header.Add(key, v)
+			}
+		}
+	}
+
+	// OAuth 账号：应用指纹到请求头
+	if account.IsOAuth() && s.identityService != nil {
+		fp, _ := s.identityService.GetOrCreateFingerprint(ctx, account.ID, c.Request.Header)
+		if fp != nil {
+			s.identityService.ApplyFingerprint(req, fp)
+		}
+	}
+
+	// 确保必要的 headers 存在
+	if req.Header.Get("Content-Type") == "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if req.Header.Get("anthropic-version") == "" {
+		req.Header.Set("anthropic-version", "2023-06-01")
+	}
+
+	// OAuth 账号：处理 anthropic-beta header
+	if tokenType == "oauth" {
+		req.Header.Set("anthropic-beta", s.getBetaHeader(body, c.GetHeader("anthropic-beta")))
+	}
+
+	return req, nil
+}
+
+// countTokensError 返回 count_tokens 错误响应
+func (s *GatewayService) countTokensError(c *gin.Context, status int, errType, message string) {
+	c.JSON(status, gin.H{
+		"type": "error",
+		"error": gin.H{
+			"type":    errType,
+			"message": message,
+		},
+	})
+}

backend/internal/service/group_service.go

@@ -5,7 +5,8 @@ import (
 	"errors"
 	"fmt"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/pkg/pagination"
+	"sub2api/internal/service/ports"
 
 	"gorm.io/gorm"
 )
@@ -34,11 +35,11 @@ type UpdateGroupRequest struct {
 
 // GroupService 分组管理服务
 type GroupService struct {
-	groupRepo *repository.GroupRepository
+	groupRepo ports.GroupRepository
 }
 
 // NewGroupService 创建分组服务实例
-func NewGroupService(groupRepo *repository.GroupRepository) *GroupService {
+func NewGroupService(groupRepo ports.GroupRepository) *GroupService {
 	return &GroupService{
 		groupRepo: groupRepo,
 	}
@@ -84,7 +85,7 @@ func (s *GroupService) GetByID(ctx context.Context, id int64) (*model.Group, err
 }
 
 // List 获取分组列表
-func (s *GroupService) List(ctx context.Context, params repository.PaginationParams) ([]model.Group, *repository.PaginationResult, error) {
+func (s *GroupService) List(ctx context.Context, params pagination.PaginationParams) ([]model.Group, *pagination.PaginationResult, error) {
 	groups, pagination, err := s.groupRepo.List(ctx, params)
 	if err != nil {
 		return nil, nil, fmt.Errorf("list groups: %w", err)
@@ -166,7 +167,7 @@ func (s *GroupService) Delete(ctx context.Context, id int64) error {
 }
 
 // GetStats 获取分组统计信息
-func (s *GroupService) GetStats(ctx context.Context, id int64) (map[string]interface{}, error) {
+func (s *GroupService) GetStats(ctx context.Context, id int64) (map[string]any, error) {
 	group, err := s.groupRepo.GetByID(ctx, id)
 	if err != nil {
 		if errors.Is(err, gorm.ErrRecordNotFound) {
@@ -181,7 +182,7 @@ func (s *GroupService) GetStats(ctx context.Context, id int64) (map[string]inter
 		return nil, fmt.Errorf("get account count: %w", err)
 	}
 
-	stats := map[string]interface{}{
+	stats := map[string]any{
 		"id":              group.ID,
 		"name":            group.Name,
 		"rate_multiplier": group.RateMultiplier,

backend/internal/service/identity_service.go

@@ -11,14 +11,8 @@ import (
 	"net/http"
 	"regexp"
 	"strconv"
+	"sub2api/internal/service/ports"
 	"time"
-
-	"github.com/redis/go-redis/v9"
-)
-
-const (
-	// Redis key prefix
-	identityFingerprintKey = "identity:fingerprint:"
 )
 
 // 预编译正则表达式（避免每次调用重新编译）
@@ -29,20 +23,8 @@ var (
 	userAgentVersionRegex = regexp.MustCompile(`/(\d+)\.(\d+)\.(\d+)`)
 )
 
-// Fingerprint 存储的指纹数据结构
-type Fingerprint struct {
-	ClientID                string `json:"client_id"`                    // 64位hex客户端ID（首次随机生成）
-	UserAgent               string `json:"user_agent"`                   // User-Agent
-	StainlessLang           string `json:"x_stainless_lang"`             // x-stainless-lang
-	StainlessPackageVersion string `json:"x_stainless_package_version"`  // x-stainless-package-version
-	StainlessOS             string `json:"x_stainless_os"`               // x-stainless-os
-	StainlessArch           string `json:"x_stainless_arch"`             // x-stainless-arch
-	StainlessRuntime        string `json:"x_stainless_runtime"`          // x-stainless-runtime
-	StainlessRuntimeVersion string `json:"x_stainless_runtime_version"`  // x-stainless-runtime-version
-}
-
 // 默认指纹值（当客户端未提供时使用）
-var defaultFingerprint = Fingerprint{
+var defaultFingerprint = ports.Fingerprint{
 	UserAgent:               "claude-cli/2.0.62 (external, cli)",
 	StainlessLang:           "js",
 	StainlessPackageVersion: "0.52.0",
@@ -54,39 +36,31 @@ var defaultFingerprint = Fingerprint{
 
 // IdentityService 管理OAuth账号的请求身份指纹
 type IdentityService struct {
-	rdb *redis.Client
+	cache ports.IdentityCache
 }
 
 // NewIdentityService 创建新的IdentityService
-func NewIdentityService(rdb *redis.Client) *IdentityService {
-	return &IdentityService{rdb: rdb}
+func NewIdentityService(cache ports.IdentityCache) *IdentityService {
+	return &IdentityService{cache: cache}
 }
 
 // GetOrCreateFingerprint 获取或创建账号的指纹
 // 如果缓存存在，检测user-agent版本，新版本则更新
 // 如果缓存不存在，生成随机ClientID并从请求头创建指纹，然后缓存
-func (s *IdentityService) GetOrCreateFingerprint(ctx context.Context, accountID int64, headers http.Header) (*Fingerprint, error) {
-	key := identityFingerprintKey + strconv.FormatInt(accountID, 10)
-
-	// 尝试从Redis获取缓存的指纹
-	data, err := s.rdb.Get(ctx, key).Bytes()
-	if err == nil && len(data) > 0 {
-		// 缓存存在，解析指纹
-		var cached Fingerprint
-		if err := json.Unmarshal(data, &cached); err == nil {
-			// 检查客户端的user-agent是否是更新版本
-			clientUA := headers.Get("User-Agent")
-			if clientUA != "" && isNewerVersion(clientUA, cached.UserAgent) {
-				// 更新user-agent
-				cached.UserAgent = clientUA
-				// 保存更新后的指纹
-				if newData, err := json.Marshal(cached); err == nil {
-					s.rdb.Set(ctx, key, newData, 0) // 永不过期
-				}
-				log.Printf("Updated fingerprint user-agent for account %d: %s", accountID, clientUA)
-			}
-			return &cached, nil
+func (s *IdentityService) GetOrCreateFingerprint(ctx context.Context, accountID int64, headers http.Header) (*ports.Fingerprint, error) {
+	// 尝试从缓存获取指纹
+	cached, err := s.cache.GetFingerprint(ctx, accountID)
+	if err == nil && cached != nil {
+		// 检查客户端的user-agent是否是更新版本
+		clientUA := headers.Get("User-Agent")
+		if clientUA != "" && isNewerVersion(clientUA, cached.UserAgent) {
+			// 更新user-agent
+			cached.UserAgent = clientUA
+			// 保存更新后的指纹
+			_ = s.cache.SetFingerprint(ctx, accountID, cached)
+			log.Printf("Updated fingerprint user-agent for account %d: %s", accountID, clientUA)
 		}
+		return cached, nil
 	}
 
 	// 缓存不存在或解析失败，创建新指纹
@@ -95,11 +69,9 @@ func (s *IdentityService) GetOrCreateFingerprint(ctx context.Context, accountID
 	// 生成随机ClientID
 	fp.ClientID = generateClientID()
 
-	// 保存到Redis（永不过期）
-	if data, err := json.Marshal(fp); err == nil {
-		if err := s.rdb.Set(ctx, key, data, 0).Err(); err != nil {
-			log.Printf("Warning: failed to cache fingerprint for account %d: %v", accountID, err)
-		}
+	// 保存到缓存（永不过期）
+	if err := s.cache.SetFingerprint(ctx, accountID, fp); err != nil {
+		log.Printf("Warning: failed to cache fingerprint for account %d: %v", accountID, err)
 	}
 
 	log.Printf("Created new fingerprint for account %d with client_id: %s", accountID, fp.ClientID)
@@ -107,8 +79,8 @@ func (s *IdentityService) GetOrCreateFingerprint(ctx context.Context, accountID
 }
 
 // createFingerprintFromHeaders 从请求头创建指纹
-func (s *IdentityService) createFingerprintFromHeaders(headers http.Header) *Fingerprint {
-	fp := &Fingerprint{}
+func (s *IdentityService) createFingerprintFromHeaders(headers http.Header) *ports.Fingerprint {
+	fp := &ports.Fingerprint{}
 
 	// 获取User-Agent
 	if ua := headers.Get("User-Agent"); ua != "" {
@@ -137,7 +109,7 @@ func getHeaderOrDefault(headers http.Header, key, defaultValue string) string {
 }
 
 // ApplyFingerprint 将指纹应用到请求头（覆盖原有的x-stainless-*头）
-func (s *IdentityService) ApplyFingerprint(req *http.Request, fp *Fingerprint) {
+func (s *IdentityService) ApplyFingerprint(req *http.Request, fp *ports.Fingerprint) {
 	if fp == nil {
 		return
 	}
@@ -177,12 +149,12 @@ func (s *IdentityService) RewriteUserID(body []byte, accountID int64, accountUUI
 	}
 
 	// 解析JSON
-	var reqMap map[string]interface{}
+	var reqMap map[string]any
 	if err := json.Unmarshal(body, &reqMap); err != nil {
 		return body, nil
 	}
 
-	metadata, ok := reqMap["metadata"].(map[string]interface{})
+	metadata, ok := reqMap["metadata"].(map[string]any)
 	if !ok {
 		return body, nil
 	}

backend/internal/service/oauth_service.go

@@ -2,32 +2,36 @@ package service
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 	"log"
-	"net/http"
-	"net/url"
-	"strings"
 	"time"
 
 	"sub2api/internal/model"
 	"sub2api/internal/pkg/oauth"
-	"sub2api/internal/repository"
-
-	"github.com/imroc/req/v3"
+	"sub2api/internal/service/ports"
 )
 
+// ClaudeOAuthClient handles HTTP requests for Claude OAuth flows
+type ClaudeOAuthClient interface {
+	GetOrganizationUUID(ctx context.Context, sessionKey, proxyURL string) (string, error)
+	GetAuthorizationCode(ctx context.Context, sessionKey, orgUUID, scope, codeChallenge, state, proxyURL string) (string, error)
+	ExchangeCodeForToken(ctx context.Context, code, codeVerifier, state, proxyURL string) (*oauth.TokenResponse, error)
+	RefreshToken(ctx context.Context, refreshToken, proxyURL string) (*oauth.TokenResponse, error)
+}
+
 // OAuthService handles OAuth authentication flows
 type OAuthService struct {
 	sessionStore *oauth.SessionStore
-	proxyRepo    *repository.ProxyRepository
+	proxyRepo    ports.ProxyRepository
+	oauthClient  ClaudeOAuthClient
 }
 
 // NewOAuthService creates a new OAuth service
-func NewOAuthService(proxyRepo *repository.ProxyRepository) *OAuthService {
+func NewOAuthService(proxyRepo ports.ProxyRepository, oauthClient ClaudeOAuthClient) *OAuthService {
 	return &OAuthService{
 		sessionStore: oauth.NewSessionStore(),
 		proxyRepo:    proxyRepo,
+		oauthClient:  oauthClient,
 	}
 }
 
@@ -210,177 +214,21 @@ func (s *OAuthService) CookieAuth(ctx context.Context, input *CookieAuthInput) (
 
 // getOrganizationUUID gets the organization UUID from claude.ai using sessionKey
 func (s *OAuthService) getOrganizationUUID(ctx context.Context, sessionKey, proxyURL string) (string, error) {
-	client := s.createReqClient(proxyURL)
-
-	var orgs []struct {
-		UUID string `json:"uuid"`
-	}
-
-	targetURL := "https://claude.ai/api/organizations"
-	log.Printf("[OAuth] Step 1: Getting organization UUID from %s", targetURL)
-
-	resp, err := client.R().
-		SetContext(ctx).
-		SetCookies(&http.Cookie{
-			Name:  "sessionKey",
-			Value: sessionKey,
-		}).
-		SetSuccessResult(&orgs).
-		Get(targetURL)
-
-	if err != nil {
-		log.Printf("[OAuth] Step 1 FAILED - Request error: %v", err)
-		return "", fmt.Errorf("request failed: %w", err)
-	}
-
-	log.Printf("[OAuth] Step 1 Response - Status: %d, Body: %s", resp.StatusCode, resp.String())
-
-	if !resp.IsSuccessState() {
-		return "", fmt.Errorf("failed to get organizations: status %d, body: %s", resp.StatusCode, resp.String())
-	}
-
-	if len(orgs) == 0 {
-		return "", fmt.Errorf("no organizations found")
-	}
-
-	log.Printf("[OAuth] Step 1 SUCCESS - Got org UUID: %s", orgs[0].UUID)
-	return orgs[0].UUID, nil
+	return s.oauthClient.GetOrganizationUUID(ctx, sessionKey, proxyURL)
 }
 
 // getAuthorizationCode gets the authorization code using sessionKey
 func (s *OAuthService) getAuthorizationCode(ctx context.Context, sessionKey, orgUUID, scope, codeChallenge, state, proxyURL string) (string, error) {
-	client := s.createReqClient(proxyURL)
-
-	authURL := fmt.Sprintf("https://claude.ai/v1/oauth/%s/authorize", orgUUID)
-
-	// Build request body - must include organization_uuid as per CRS
-	reqBody := map[string]interface{}{
-		"response_type":         "code",
-		"client_id":             oauth.ClientID,
-		"organization_uuid":     orgUUID, // Required field!
-		"redirect_uri":          oauth.RedirectURI,
-		"scope":                 scope,
-		"state":                 state,
-		"code_challenge":        codeChallenge,
-		"code_challenge_method": "S256",
-	}
-
-	reqBodyJSON, _ := json.Marshal(reqBody)
-	log.Printf("[OAuth] Step 2: Getting authorization code from %s", authURL)
-	log.Printf("[OAuth] Step 2 Request Body: %s", string(reqBodyJSON))
-
-	// Response contains redirect_uri with code, not direct code field
-	var result struct {
-		RedirectURI string `json:"redirect_uri"`
-	}
-
-	resp, err := client.R().
-		SetContext(ctx).
-		SetCookies(&http.Cookie{
-			Name:  "sessionKey",
-			Value: sessionKey,
-		}).
-		SetHeader("Accept", "application/json").
-		SetHeader("Accept-Language", "en-US,en;q=0.9").
-		SetHeader("Cache-Control", "no-cache").
-		SetHeader("Origin", "https://claude.ai").
-		SetHeader("Referer", "https://claude.ai/new").
-		SetHeader("Content-Type", "application/json").
-		SetBody(reqBody).
-		SetSuccessResult(&result).
-		Post(authURL)
-
-	if err != nil {
-		log.Printf("[OAuth] Step 2 FAILED - Request error: %v", err)
-		return "", fmt.Errorf("request failed: %w", err)
-	}
-
-	log.Printf("[OAuth] Step 2 Response - Status: %d, Body: %s", resp.StatusCode, resp.String())
-
-	if !resp.IsSuccessState() {
-		return "", fmt.Errorf("failed to get authorization code: status %d, body: %s", resp.StatusCode, resp.String())
-	}
-
-	if result.RedirectURI == "" {
-		return "", fmt.Errorf("no redirect_uri in response")
-	}
-
-	// Parse redirect_uri to extract code and state
-	parsedURL, err := url.Parse(result.RedirectURI)
-	if err != nil {
-		return "", fmt.Errorf("failed to parse redirect_uri: %w", err)
-	}
-
-	queryParams := parsedURL.Query()
-	authCode := queryParams.Get("code")
-	responseState := queryParams.Get("state")
-
-	if authCode == "" {
-		return "", fmt.Errorf("no authorization code in redirect_uri")
-	}
-
-	// Combine code with state if present (as CRS does)
-	fullCode := authCode
-	if responseState != "" {
-		fullCode = authCode + "#" + responseState
-	}
-
-	log.Printf("[OAuth] Step 2 SUCCESS - Got authorization code: %s...", authCode[:20])
-	return fullCode, nil
+	return s.oauthClient.GetAuthorizationCode(ctx, sessionKey, orgUUID, scope, codeChallenge, state, proxyURL)
 }
 
 // exchangeCodeForToken exchanges authorization code for tokens
 func (s *OAuthService) exchangeCodeForToken(ctx context.Context, code, codeVerifier, state, proxyURL string) (*TokenInfo, error) {
-	client := s.createReqClient(proxyURL)
-
-	// Parse code#state format if present
-	authCode := code
-	codeState := ""
-	if parts := strings.Split(code, "#"); len(parts) > 1 {
-		authCode = parts[0]
-		codeState = parts[1]
-	}
-
-	// Build JSON body as CRS does (not form data!)
-	reqBody := map[string]interface{}{
-		"code":          authCode,
-		"grant_type":    "authorization_code",
-		"client_id":     oauth.ClientID,
-		"redirect_uri":  oauth.RedirectURI,
-		"code_verifier": codeVerifier,
-	}
-
-	// Add state if present
-	if codeState != "" {
-		reqBody["state"] = codeState
-	}
-
-	reqBodyJSON, _ := json.Marshal(reqBody)
-	log.Printf("[OAuth] Step 3: Exchanging code for token at %s", oauth.TokenURL)
-	log.Printf("[OAuth] Step 3 Request Body: %s", string(reqBodyJSON))
-
-	var tokenResp oauth.TokenResponse
-
-	resp, err := client.R().
-		SetContext(ctx).
-		SetHeader("Content-Type", "application/json").
-		SetBody(reqBody).
-		SetSuccessResult(&tokenResp).
-		Post(oauth.TokenURL)
-
+	tokenResp, err := s.oauthClient.ExchangeCodeForToken(ctx, code, codeVerifier, state, proxyURL)
 	if err != nil {
-		log.Printf("[OAuth] Step 3 FAILED - Request error: %v", err)
-		return nil, fmt.Errorf("request failed: %w", err)
+		return nil, err
 	}
 
-	log.Printf("[OAuth] Step 3 Response - Status: %d, Body: %s", resp.StatusCode, resp.String())
-
-	if !resp.IsSuccessState() {
-		return nil, fmt.Errorf("token exchange failed: status %d, body: %s", resp.StatusCode, resp.String())
-	}
-
-	log.Printf("[OAuth] Step 3 SUCCESS - Got access token")
-
 	tokenInfo := &TokenInfo{
 		AccessToken:  tokenResp.AccessToken,
 		TokenType:    tokenResp.TokenType,
@@ -390,7 +238,6 @@ func (s *OAuthService) exchangeCodeForToken(ctx context.Context, code, codeVerif
 		Scope:        tokenResp.Scope,
 	}
 
-	// Extract org_uuid and account_uuid from response
 	if tokenResp.Organization != nil && tokenResp.Organization.UUID != "" {
 		tokenInfo.OrgUUID = tokenResp.Organization.UUID
 		log.Printf("[OAuth] Got org_uuid: %s", tokenInfo.OrgUUID)
@@ -405,27 +252,9 @@ func (s *OAuthService) exchangeCodeForToken(ctx context.Context, code, codeVerif
 
 // RefreshToken refreshes an OAuth token
 func (s *OAuthService) RefreshToken(ctx context.Context, refreshToken string, proxyURL string) (*TokenInfo, error) {
-	client := s.createReqClient(proxyURL)
-
-	formData := url.Values{}
-	formData.Set("grant_type", "refresh_token")
-	formData.Set("refresh_token", refreshToken)
-	formData.Set("client_id", oauth.ClientID)
-
-	var tokenResp oauth.TokenResponse
-
-	resp, err := client.R().
-		SetContext(ctx).
-		SetFormDataFromValues(formData).
-		SetSuccessResult(&tokenResp).
-		Post(oauth.TokenURL)
-
+	tokenResp, err := s.oauthClient.RefreshToken(ctx, refreshToken, proxyURL)
 	if err != nil {
-		return nil, fmt.Errorf("request failed: %w", err)
-	}
-
-	if !resp.IsSuccessState() {
-		return nil, fmt.Errorf("token refresh failed: status %d, body: %s", resp.StatusCode, resp.String())
+		return nil, err
 	}
 
 	return &TokenInfo{
@@ -455,17 +284,3 @@ func (s *OAuthService) RefreshAccountToken(ctx context.Context, account *model.A
 
 	return s.RefreshToken(ctx, refreshToken, proxyURL)
 }
-
-// createReqClient creates a req client with Chrome impersonation and optional proxy
-func (s *OAuthService) createReqClient(proxyURL string) *req.Client {
-	client := req.C().
-		ImpersonateChrome().  // Impersonate Chrome browser to bypass Cloudflare
-		SetTimeout(60 * time.Second)
-
-	// Set proxy if specified
-	if proxyURL != "" {
-		client.SetProxyURL(proxyURL)
-	}
-
-	return client
-}

backend/internal/service/ports/account.go

@@ -0,0 +1,35 @@
+package ports
+
+import (
+	"context"
+	"time"
+
+	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
+)
+
+type AccountRepository interface {
+	Create(ctx context.Context, account *model.Account) error
+	GetByID(ctx context.Context, id int64) (*model.Account, error)
+	Update(ctx context.Context, account *model.Account) error
+	Delete(ctx context.Context, id int64) error
+
+	List(ctx context.Context, params pagination.PaginationParams) ([]model.Account, *pagination.PaginationResult, error)
+	ListWithFilters(ctx context.Context, params pagination.PaginationParams, platform, accountType, status, search string) ([]model.Account, *pagination.PaginationResult, error)
+	ListByGroup(ctx context.Context, groupID int64) ([]model.Account, error)
+	ListActive(ctx context.Context) ([]model.Account, error)
+	ListByPlatform(ctx context.Context, platform string) ([]model.Account, error)
+
+	UpdateLastUsed(ctx context.Context, id int64) error
+	SetError(ctx context.Context, id int64, errorMsg string) error
+	SetSchedulable(ctx context.Context, id int64, schedulable bool) error
+	BindGroups(ctx context.Context, accountID int64, groupIDs []int64) error
+
+	ListSchedulable(ctx context.Context) ([]model.Account, error)
+	ListSchedulableByGroupID(ctx context.Context, groupID int64) ([]model.Account, error)
+
+	SetRateLimited(ctx context.Context, id int64, resetAt time.Time) error
+	SetOverloaded(ctx context.Context, id int64, until time.Time) error
+	ClearRateLimit(ctx context.Context, id int64) error
+	UpdateSessionWindow(ctx context.Context, id int64, start, end *time.Time, status string) error
+}

backend/internal/service/ports/api_key.go

@@ -0,0 +1,24 @@
+package ports
+
+import (
+	"context"
+
+	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
+)
+
+type ApiKeyRepository interface {
+	Create(ctx context.Context, key *model.ApiKey) error
+	GetByID(ctx context.Context, id int64) (*model.ApiKey, error)
+	GetByKey(ctx context.Context, key string) (*model.ApiKey, error)
+	Update(ctx context.Context, key *model.ApiKey) error
+	Delete(ctx context.Context, id int64) error
+
+	ListByUserID(ctx context.Context, userID int64, params pagination.PaginationParams) ([]model.ApiKey, *pagination.PaginationResult, error)
+	CountByUserID(ctx context.Context, userID int64) (int64, error)
+	ExistsByKey(ctx context.Context, key string) (bool, error)
+	ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]model.ApiKey, *pagination.PaginationResult, error)
+	SearchApiKeys(ctx context.Context, userID int64, keyword string, limit int) ([]model.ApiKey, error)
+	ClearGroupIDByGroupID(ctx context.Context, groupID int64) (int64, error)
+	CountByGroupID(ctx context.Context, groupID int64) (int64, error)
+}

backend/internal/service/ports/api_key_cache.go

@@ -0,0 +1,16 @@
+package ports
+
+import (
+	"context"
+	"time"
+)
+
+// ApiKeyCache defines cache operations for API key service
+type ApiKeyCache interface {
+	GetCreateAttemptCount(ctx context.Context, userID int64) (int, error)
+	IncrementCreateAttemptCount(ctx context.Context, userID int64) error
+	DeleteCreateAttemptCount(ctx context.Context, userID int64) error
+
+	IncrementDailyUsage(ctx context.Context, apiKey string) error
+	SetDailyUsageExpiry(ctx context.Context, apiKey string, ttl time.Duration) error
+}

backend/internal/service/ports/billing_cache.go

@@ -0,0 +1,31 @@
+package ports
+
+import (
+	"context"
+	"time"
+)
+
+// SubscriptionCacheData represents cached subscription data
+type SubscriptionCacheData struct {
+	Status       string
+	ExpiresAt    time.Time
+	DailyUsage   float64
+	WeeklyUsage  float64
+	MonthlyUsage float64
+	Version      int64
+}
+
+// BillingCache defines cache operations for billing service
+type BillingCache interface {
+	// Balance operations
+	GetUserBalance(ctx context.Context, userID int64) (float64, error)
+	SetUserBalance(ctx context.Context, userID int64, balance float64) error
+	DeductUserBalance(ctx context.Context, userID int64, amount float64) error
+	InvalidateUserBalance(ctx context.Context, userID int64) error
+
+	// Subscription operations
+	GetSubscriptionCache(ctx context.Context, userID, groupID int64) (*SubscriptionCacheData, error)
+	SetSubscriptionCache(ctx context.Context, userID, groupID int64, data *SubscriptionCacheData) error
+	UpdateSubscriptionUsage(ctx context.Context, userID, groupID int64, cost float64) error
+	InvalidateSubscriptionCache(ctx context.Context, userID, groupID int64) error
+}

backend/internal/service/ports/concurrency_cache.go

@@ -0,0 +1,19 @@
+package ports
+
+import "context"
+
+// ConcurrencyCache defines cache operations for concurrency service
+type ConcurrencyCache interface {
+	// Slot management
+	AcquireAccountSlot(ctx context.Context, accountID int64, maxConcurrency int) (bool, error)
+	ReleaseAccountSlot(ctx context.Context, accountID int64) error
+	GetAccountConcurrency(ctx context.Context, accountID int64) (int, error)
+
+	AcquireUserSlot(ctx context.Context, userID int64, maxConcurrency int) (bool, error)
+	ReleaseUserSlot(ctx context.Context, userID int64) error
+	GetUserConcurrency(ctx context.Context, userID int64) (int, error)
+
+	// Wait queue
+	IncrementWaitCount(ctx context.Context, userID int64, maxWait int) (bool, error)
+	DecrementWaitCount(ctx context.Context, userID int64) error
+}

backend/internal/service/ports/email_cache.go

@@ -0,0 +1,20 @@
+package ports
+
+import (
+	"context"
+	"time"
+)
+
+// VerificationCodeData represents verification code data
+type VerificationCodeData struct {
+	Code      string
+	Attempts  int
+	CreatedAt time.Time
+}
+
+// EmailCache defines cache operations for email service
+type EmailCache interface {
+	GetVerificationCode(ctx context.Context, email string) (*VerificationCodeData, error)
+	SetVerificationCode(ctx context.Context, email string, data *VerificationCodeData, ttl time.Duration) error
+	DeleteVerificationCode(ctx context.Context, email string) error
+}

backend/internal/service/ports/gateway_cache.go

@@ -0,0 +1,13 @@
+package ports
+
+import (
+	"context"
+	"time"
+)
+
+// GatewayCache defines cache operations for gateway service
+type GatewayCache interface {
+	GetSessionAccountID(ctx context.Context, sessionHash string) (int64, error)
+	SetSessionAccountID(ctx context.Context, sessionHash string, accountID int64, ttl time.Duration) error
+	RefreshSessionTTL(ctx context.Context, sessionHash string, ttl time.Duration) error
+}

backend/internal/service/ports/group.go

@@ -0,0 +1,28 @@
+package ports
+
+import (
+	"context"
+
+	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
+
+	"gorm.io/gorm"
+)
+
+type GroupRepository interface {
+	Create(ctx context.Context, group *model.Group) error
+	GetByID(ctx context.Context, id int64) (*model.Group, error)
+	Update(ctx context.Context, group *model.Group) error
+	Delete(ctx context.Context, id int64) error
+
+	List(ctx context.Context, params pagination.PaginationParams) ([]model.Group, *pagination.PaginationResult, error)
+	ListWithFilters(ctx context.Context, params pagination.PaginationParams, platform, status string, isExclusive *bool) ([]model.Group, *pagination.PaginationResult, error)
+	ListActive(ctx context.Context) ([]model.Group, error)
+	ListActiveByPlatform(ctx context.Context, platform string) ([]model.Group, error)
+
+	ExistsByName(ctx context.Context, name string) (bool, error)
+	GetAccountCount(ctx context.Context, groupID int64) (int64, error)
+	DeleteAccountGroupsByGroupID(ctx context.Context, groupID int64) (int64, error)
+
+	DB() *gorm.DB
+}

backend/internal/service/ports/identity_cache.go

@@ -0,0 +1,21 @@
+package ports
+
+import "context"
+
+// Fingerprint represents account fingerprint data
+type Fingerprint struct {
+	ClientID                string
+	UserAgent               string
+	StainlessLang           string
+	StainlessPackageVersion string
+	StainlessOS             string
+	StainlessArch           string
+	StainlessRuntime        string
+	StainlessRuntimeVersion string
+}
+
+// IdentityCache defines cache operations for identity service
+type IdentityCache interface {
+	GetFingerprint(ctx context.Context, accountID int64) (*Fingerprint, error)
+	SetFingerprint(ctx context.Context, accountID int64, fp *Fingerprint) error
+}

backend/internal/service/ports/proxy.go

@@ -0,0 +1,23 @@
+package ports
+
+import (
+	"context"
+
+	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
+)
+
+type ProxyRepository interface {
+	Create(ctx context.Context, proxy *model.Proxy) error
+	GetByID(ctx context.Context, id int64) (*model.Proxy, error)
+	Update(ctx context.Context, proxy *model.Proxy) error
+	Delete(ctx context.Context, id int64) error
+
+	List(ctx context.Context, params pagination.PaginationParams) ([]model.Proxy, *pagination.PaginationResult, error)
+	ListWithFilters(ctx context.Context, params pagination.PaginationParams, protocol, status, search string) ([]model.Proxy, *pagination.PaginationResult, error)
+	ListActive(ctx context.Context) ([]model.Proxy, error)
+	ListActiveWithAccountCount(ctx context.Context) ([]model.ProxyWithAccountCount, error)
+
+	ExistsByHostPortAuth(ctx context.Context, host string, port int, username, password string) (bool, error)
+	CountAccountsByProxyID(ctx context.Context, proxyID int64) (int64, error)
+}

backend/internal/service/ports/redeem_cache.go

@@ -0,0 +1,15 @@
+package ports
+
+import (
+	"context"
+	"time"
+)
+
+// RedeemCache defines cache operations for redeem service
+type RedeemCache interface {
+	GetRedeemAttemptCount(ctx context.Context, userID int64) (int, error)
+	IncrementRedeemAttemptCount(ctx context.Context, userID int64) error
+
+	AcquireRedeemLock(ctx context.Context, code string, ttl time.Duration) (bool, error)
+	ReleaseRedeemLock(ctx context.Context, code string) error
+}

backend/internal/service/ports/redeem_code.go

@@ -0,0 +1,22 @@
+package ports
+
+import (
+	"context"
+
+	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
+)
+
+type RedeemCodeRepository interface {
+	Create(ctx context.Context, code *model.RedeemCode) error
+	CreateBatch(ctx context.Context, codes []model.RedeemCode) error
+	GetByID(ctx context.Context, id int64) (*model.RedeemCode, error)
+	GetByCode(ctx context.Context, code string) (*model.RedeemCode, error)
+	Update(ctx context.Context, code *model.RedeemCode) error
+	Delete(ctx context.Context, id int64) error
+	Use(ctx context.Context, id, userID int64) error
+
+	List(ctx context.Context, params pagination.PaginationParams) ([]model.RedeemCode, *pagination.PaginationResult, error)
+	ListWithFilters(ctx context.Context, params pagination.PaginationParams, codeType, status, search string) ([]model.RedeemCode, *pagination.PaginationResult, error)
+	ListByUser(ctx context.Context, userID int64, limit int) ([]model.RedeemCode, error)
+}

backend/internal/service/ports/setting.go

@@ -0,0 +1,17 @@
+package ports
+
+import (
+	"context"
+
+	"sub2api/internal/model"
+)
+
+type SettingRepository interface {
+	Get(ctx context.Context, key string) (*model.Setting, error)
+	GetValue(ctx context.Context, key string) (string, error)
+	Set(ctx context.Context, key, value string) error
+	GetMultiple(ctx context.Context, keys []string) (map[string]string, error)
+	SetMultiple(ctx context.Context, settings map[string]string) error
+	GetAll(ctx context.Context) (map[string]string, error)
+	Delete(ctx context.Context, key string) error
+}

backend/internal/service/ports/update_cache.go

@@ -0,0 +1,12 @@
+package ports
+
+import (
+	"context"
+	"time"
+)
+
+// UpdateCache defines cache operations for update service
+type UpdateCache interface {
+	GetUpdateInfo(ctx context.Context) (string, error)
+	SetUpdateInfo(ctx context.Context, data string, ttl time.Duration) error
+}

backend/internal/service/ports/usage_log.go

@@ -0,0 +1,28 @@
+package ports
+
+import (
+	"context"
+	"time"
+
+	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
+	"sub2api/internal/pkg/usagestats"
+)
+
+type UsageLogRepository interface {
+	Create(ctx context.Context, log *model.UsageLog) error
+	GetByID(ctx context.Context, id int64) (*model.UsageLog, error)
+	Delete(ctx context.Context, id int64) error
+
+	ListByUser(ctx context.Context, userID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error)
+	ListByApiKey(ctx context.Context, apiKeyID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error)
+	ListByAccount(ctx context.Context, accountID int64, params pagination.PaginationParams) ([]model.UsageLog, *pagination.PaginationResult, error)
+
+	ListByUserAndTimeRange(ctx context.Context, userID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error)
+	ListByApiKeyAndTimeRange(ctx context.Context, apiKeyID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error)
+	ListByAccountAndTimeRange(ctx context.Context, accountID int64, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error)
+	ListByModelAndTimeRange(ctx context.Context, modelName string, startTime, endTime time.Time) ([]model.UsageLog, *pagination.PaginationResult, error)
+
+	GetAccountWindowStats(ctx context.Context, accountID int64, startTime time.Time) (*usagestats.AccountStats, error)
+	GetAccountTodayStats(ctx context.Context, accountID int64) (*usagestats.AccountStats, error)
+}

backend/internal/service/ports/user.go

@@ -0,0 +1,26 @@
+package ports
+
+import (
+	"context"
+
+	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
+)
+
+type UserRepository interface {
+	Create(ctx context.Context, user *model.User) error
+	GetByID(ctx context.Context, id int64) (*model.User, error)
+	GetByEmail(ctx context.Context, email string) (*model.User, error)
+	GetFirstAdmin(ctx context.Context) (*model.User, error)
+	Update(ctx context.Context, user *model.User) error
+	Delete(ctx context.Context, id int64) error
+
+	List(ctx context.Context, params pagination.PaginationParams) ([]model.User, *pagination.PaginationResult, error)
+	ListWithFilters(ctx context.Context, params pagination.PaginationParams, status, role, search string) ([]model.User, *pagination.PaginationResult, error)
+
+	UpdateBalance(ctx context.Context, id int64, amount float64) error
+	DeductBalance(ctx context.Context, id int64, amount float64) error
+	UpdateConcurrency(ctx context.Context, id int64, amount int) error
+	ExistsByEmail(ctx context.Context, email string) (bool, error)
+	RemoveGroupFromAllowedGroups(ctx context.Context, groupID int64) (int64, error)
+}

backend/internal/service/ports/user_subscription.go

@@ -0,0 +1,36 @@
+package ports
+
+import (
+	"context"
+	"time"
+
+	"sub2api/internal/model"
+	"sub2api/internal/pkg/pagination"
+)
+
+type UserSubscriptionRepository interface {
+	Create(ctx context.Context, sub *model.UserSubscription) error
+	GetByID(ctx context.Context, id int64) (*model.UserSubscription, error)
+	GetByUserIDAndGroupID(ctx context.Context, userID, groupID int64) (*model.UserSubscription, error)
+	GetActiveByUserIDAndGroupID(ctx context.Context, userID, groupID int64) (*model.UserSubscription, error)
+	Update(ctx context.Context, sub *model.UserSubscription) error
+	Delete(ctx context.Context, id int64) error
+
+	ListByUserID(ctx context.Context, userID int64) ([]model.UserSubscription, error)
+	ListActiveByUserID(ctx context.Context, userID int64) ([]model.UserSubscription, error)
+	ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]model.UserSubscription, *pagination.PaginationResult, error)
+	List(ctx context.Context, params pagination.PaginationParams, userID, groupID *int64, status string) ([]model.UserSubscription, *pagination.PaginationResult, error)
+
+	ExistsByUserIDAndGroupID(ctx context.Context, userID, groupID int64) (bool, error)
+	ExtendExpiry(ctx context.Context, subscriptionID int64, newExpiresAt time.Time) error
+	UpdateStatus(ctx context.Context, subscriptionID int64, status string) error
+	UpdateNotes(ctx context.Context, subscriptionID int64, notes string) error
+
+	ActivateWindows(ctx context.Context, id int64, start time.Time) error
+	ResetDailyUsage(ctx context.Context, id int64, newWindowStart time.Time) error
+	ResetWeeklyUsage(ctx context.Context, id int64, newWindowStart time.Time) error
+	ResetMonthlyUsage(ctx context.Context, id int64, newWindowStart time.Time) error
+	IncrementUsage(ctx context.Context, id int64, costUSD float64) error
+
+	BatchUpdateExpiredStatus(ctx context.Context) (int64, error)
+}

backend/internal/service/pricing_service.go

@@ -1,13 +1,12 @@
 package service
 
 import (
+	"context"
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
-	"io"
 	"log"
-	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
@@ -20,13 +19,19 @@ import (
 // LiteLLMModelPricing LiteLLM价格数据结构
 // 只保留我们需要的字段，使用指针来处理可能缺失的值
 type LiteLLMModelPricing struct {
-	InputCostPerToken            float64 `json:"input_cost_per_token"`
-	OutputCostPerToken           float64 `json:"output_cost_per_token"`
-	CacheCreationInputTokenCost  float64 `json:"cache_creation_input_token_cost"`
-	CacheReadInputTokenCost      float64 `json:"cache_read_input_token_cost"`
-	LiteLLMProvider              string  `json:"litellm_provider"`
-	Mode                         string  `json:"mode"`
-	SupportsPromptCaching        bool    `json:"supports_prompt_caching"`
+	InputCostPerToken           float64 `json:"input_cost_per_token"`
+	OutputCostPerToken          float64 `json:"output_cost_per_token"`
+	CacheCreationInputTokenCost float64 `json:"cache_creation_input_token_cost"`
+	CacheReadInputTokenCost     float64 `json:"cache_read_input_token_cost"`
+	LiteLLMProvider             string  `json:"litellm_provider"`
+	Mode                        string  `json:"mode"`
+	SupportsPromptCaching       bool    `json:"supports_prompt_caching"`
+}
+
+// PricingRemoteClient 远程价格数据获取接口
+type PricingRemoteClient interface {
+	FetchPricingJSON(ctx context.Context, url string) ([]byte, error)
+	FetchHashText(ctx context.Context, url string) (string, error)
 }
 
 // LiteLLMRawEntry 用于解析原始JSON数据
@@ -42,11 +47,12 @@ type LiteLLMRawEntry struct {
 
 // PricingService 动态价格服务
 type PricingService struct {
-	cfg         *config.Config
-	mu          sync.RWMutex
-	pricingData map[string]*LiteLLMModelPricing
-	lastUpdated time.Time
-	localHash   string
+	cfg          *config.Config
+	remoteClient PricingRemoteClient
+	mu           sync.RWMutex
+	pricingData  map[string]*LiteLLMModelPricing
+	lastUpdated  time.Time
+	localHash    string
 
 	// 停止信号
 	stopCh chan struct{}
@@ -54,11 +60,12 @@ type PricingService struct {
 }
 
 // NewPricingService 创建价格服务
-func NewPricingService(cfg *config.Config) *PricingService {
+func NewPricingService(cfg *config.Config, remoteClient PricingRemoteClient) *PricingService {
 	s := &PricingService{
-		cfg:         cfg,
-		pricingData: make(map[string]*LiteLLMModelPricing),
-		stopCh:      make(chan struct{}),
+		cfg:          cfg,
+		remoteClient: remoteClient,
+		pricingData:  make(map[string]*LiteLLMModelPricing),
+		stopCh:       make(chan struct{}),
 	}
 	return s
 }
@@ -199,21 +206,13 @@ func (s *PricingService) syncWithRemote() error {
 func (s *PricingService) downloadPricingData() error {
 	log.Printf("[Pricing] Downloading from %s", s.cfg.Pricing.RemoteURL)
 
-	client := &http.Client{Timeout: 30 * time.Second}
-	resp, err := client.Get(s.cfg.Pricing.RemoteURL)
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	body, err := s.remoteClient.FetchPricingJSON(ctx, s.cfg.Pricing.RemoteURL)
 	if err != nil {
 		return fmt.Errorf("download failed: %w", err)
 	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("download failed: HTTP %d", resp.StatusCode)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return fmt.Errorf("read response failed: %w", err)
-	}
 
 	// 解析JSON数据（使用灵活的解析方式）
 	data, err := s.parsePricingData(body)
@@ -367,29 +366,10 @@ func (s *PricingService) useFallbackPricing() error {
 
 // fetchRemoteHash 从远程获取哈希值
 func (s *PricingService) fetchRemoteHash() (string, error) {
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Get(s.cfg.Pricing.HashURL)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
 
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("HTTP %d", resp.StatusCode)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", err
-	}
-
-	// 哈希文件格式：hash  filename 或者纯 hash
-	hash := strings.TrimSpace(string(body))
-	parts := strings.Fields(hash)
-	if len(parts) > 0 {
-		return parts[0], nil
-	}
-	return hash, nil
+	return s.remoteClient.FetchHashText(ctx, s.cfg.Pricing.HashURL)
 }
 
 // computeFileHash 计算文件哈希
@@ -466,14 +446,14 @@ func (s *PricingService) extractBaseName(model string) string {
 func (s *PricingService) matchByModelFamily(model string) *LiteLLMModelPricing {
 	// Claude模型系列匹配规则
 	familyPatterns := map[string][]string{
-		"opus-4.5":       {"claude-opus-4.5", "claude-opus-4-5"},
-		"opus-4":         {"claude-opus-4", "claude-3-opus"},
-		"sonnet-4.5":     {"claude-sonnet-4.5", "claude-sonnet-4-5"},
-		"sonnet-4":       {"claude-sonnet-4", "claude-3-5-sonnet"},
-		"sonnet-3.5":     {"claude-3-5-sonnet", "claude-3.5-sonnet"},
-		"sonnet-3":       {"claude-3-sonnet"},
-		"haiku-3.5":      {"claude-3-5-haiku", "claude-3.5-haiku"},
-		"haiku-3":        {"claude-3-haiku"},
+		"opus-4.5":   {"claude-opus-4.5", "claude-opus-4-5"},
+		"opus-4":     {"claude-opus-4", "claude-3-opus"},
+		"sonnet-4.5": {"claude-sonnet-4.5", "claude-sonnet-4-5"},
+		"sonnet-4":   {"claude-sonnet-4", "claude-3-5-sonnet"},
+		"sonnet-3.5": {"claude-3-5-sonnet", "claude-3.5-sonnet"},
+		"sonnet-3":   {"claude-3-sonnet"},
+		"haiku-3.5":  {"claude-3-5-haiku", "claude-3.5-haiku"},
+		"haiku-3":    {"claude-3-haiku"},
 	}
 
 	// 确定模型属于哪个系列
@@ -535,11 +515,11 @@ func (s *PricingService) matchByModelFamily(model string) *LiteLLMModelPricing {
 }
 
 // GetStatus 获取服务状态
-func (s *PricingService) GetStatus() map[string]interface{} {
+func (s *PricingService) GetStatus() map[string]any {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
-	return map[string]interface{}{
+	return map[string]any{
 		"model_count":  len(s.pricingData),
 		"last_updated": s.lastUpdated,
 		"local_hash":   s.localHash[:min(8, len(s.localHash))],

backend/internal/service/proxy_service.go

@@ -5,7 +5,8 @@ import (
 	"errors"
 	"fmt"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/pkg/pagination"
+	"sub2api/internal/service/ports"
 
 	"gorm.io/gorm"
 )
@@ -37,11 +38,11 @@ type UpdateProxyRequest struct {
 
 // ProxyService 代理管理服务
 type ProxyService struct {
-	proxyRepo *repository.ProxyRepository
+	proxyRepo ports.ProxyRepository
 }
 
 // NewProxyService 创建代理服务实例
-func NewProxyService(proxyRepo *repository.ProxyRepository) *ProxyService {
+func NewProxyService(proxyRepo ports.ProxyRepository) *ProxyService {
 	return &ProxyService{
 		proxyRepo: proxyRepo,
 	}
@@ -80,7 +81,7 @@ func (s *ProxyService) GetByID(ctx context.Context, id int64) (*model.Proxy, err
 }
 
 // List 获取代理列表
-func (s *ProxyService) List(ctx context.Context, params repository.PaginationParams) ([]model.Proxy, *repository.PaginationResult, error) {
+func (s *ProxyService) List(ctx context.Context, params pagination.PaginationParams) ([]model.Proxy, *pagination.PaginationResult, error) {
 	proxies, pagination, err := s.proxyRepo.List(ctx, params)
 	if err != nil {
 		return nil, nil, fmt.Errorf("list proxies: %w", err)

backend/internal/service/ratelimit_service.go

@@ -9,20 +9,20 @@ import (
 
 	"sub2api/internal/config"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/service/ports"
 )
 
 // RateLimitService 处理限流和过载状态管理
 type RateLimitService struct {
-	repos *repository.Repositories
-	cfg   *config.Config
+	accountRepo ports.AccountRepository
+	cfg         *config.Config
 }
 
 // NewRateLimitService 创建RateLimitService实例
-func NewRateLimitService(repos *repository.Repositories, cfg *config.Config) *RateLimitService {
+func NewRateLimitService(accountRepo ports.AccountRepository, cfg *config.Config) *RateLimitService {
 	return &RateLimitService{
-		repos: repos,
-		cfg:   cfg,
+		accountRepo: accountRepo,
+		cfg:         cfg,
 	}
 }
 
@@ -62,7 +62,7 @@ func (s *RateLimitService) HandleUpstreamError(ctx context.Context, account *mod
 
 // handleAuthError 处理认证类错误(401/403)，停止账号调度
 func (s *RateLimitService) handleAuthError(ctx context.Context, account *model.Account, errorMsg string) {
-	if err := s.repos.Account.SetError(ctx, account.ID, errorMsg); err != nil {
+	if err := s.accountRepo.SetError(ctx, account.ID, errorMsg); err != nil {
 		log.Printf("SetError failed for account %d: %v", account.ID, err)
 		return
 	}
@@ -77,7 +77,7 @@ func (s *RateLimitService) handle429(ctx context.Context, account *model.Account
 	if resetTimestamp == "" {
 		// 没有重置时间，使用默认5分钟
 		resetAt := time.Now().Add(5 * time.Minute)
-		if err := s.repos.Account.SetRateLimited(ctx, account.ID, resetAt); err != nil {
+		if err := s.accountRepo.SetRateLimited(ctx, account.ID, resetAt); err != nil {
 			log.Printf("SetRateLimited failed for account %d: %v", account.ID, err)
 		}
 		return
@@ -88,7 +88,7 @@ func (s *RateLimitService) handle429(ctx context.Context, account *model.Account
 	if err != nil {
 		log.Printf("Parse reset timestamp failed: %v", err)
 		resetAt := time.Now().Add(5 * time.Minute)
-		if err := s.repos.Account.SetRateLimited(ctx, account.ID, resetAt); err != nil {
+		if err := s.accountRepo.SetRateLimited(ctx, account.ID, resetAt); err != nil {
 			log.Printf("SetRateLimited failed for account %d: %v", account.ID, err)
 		}
 		return
@@ -97,7 +97,7 @@ func (s *RateLimitService) handle429(ctx context.Context, account *model.Account
 	resetAt := time.Unix(ts, 0)
 
 	// 标记限流状态
-	if err := s.repos.Account.SetRateLimited(ctx, account.ID, resetAt); err != nil {
+	if err := s.accountRepo.SetRateLimited(ctx, account.ID, resetAt); err != nil {
 		log.Printf("SetRateLimited failed for account %d: %v", account.ID, err)
 		return
 	}
@@ -105,7 +105,7 @@ func (s *RateLimitService) handle429(ctx context.Context, account *model.Account
 	// 根据重置时间反推5h窗口
 	windowEnd := resetAt
 	windowStart := resetAt.Add(-5 * time.Hour)
-	if err := s.repos.Account.UpdateSessionWindow(ctx, account.ID, &windowStart, &windowEnd, "rejected"); err != nil {
+	if err := s.accountRepo.UpdateSessionWindow(ctx, account.ID, &windowStart, &windowEnd, "rejected"); err != nil {
 		log.Printf("UpdateSessionWindow failed for account %d: %v", account.ID, err)
 	}
 
@@ -121,7 +121,7 @@ func (s *RateLimitService) handle529(ctx context.Context, account *model.Account
 	}
 
 	until := time.Now().Add(time.Duration(cooldownMinutes) * time.Minute)
-	if err := s.repos.Account.SetOverloaded(ctx, account.ID, until); err != nil {
+	if err := s.accountRepo.SetOverloaded(ctx, account.ID, until); err != nil {
 		log.Printf("SetOverloaded failed for account %d: %v", account.ID, err)
 		return
 	}
@@ -152,13 +152,13 @@ func (s *RateLimitService) UpdateSessionWindow(ctx context.Context, account *mod
 		log.Printf("Account %d: initializing 5h window from %v to %v (status: %s)", account.ID, start, end, status)
 	}
 
-	if err := s.repos.Account.UpdateSessionWindow(ctx, account.ID, windowStart, windowEnd, status); err != nil {
+	if err := s.accountRepo.UpdateSessionWindow(ctx, account.ID, windowStart, windowEnd, status); err != nil {
 		log.Printf("UpdateSessionWindow failed for account %d: %v", account.ID, err)
 	}
 
 	// 如果状态为allowed且之前有限流，说明窗口已重置，清除限流状态
 	if status == "allowed" && account.IsRateLimited() {
-		if err := s.repos.Account.ClearRateLimit(ctx, account.ID); err != nil {
+		if err := s.accountRepo.ClearRateLimit(ctx, account.ID); err != nil {
 			log.Printf("ClearRateLimit failed for account %d: %v", account.ID, err)
 		}
 	}
@@ -166,5 +166,5 @@ func (s *RateLimitService) UpdateSessionWindow(ctx context.Context, account *mod
 
 // ClearRateLimit 清除账号的限流状态
 func (s *RateLimitService) ClearRateLimit(ctx context.Context, accountID int64) error {
-	return s.repos.Account.ClearRateLimit(ctx, accountID)
+	return s.accountRepo.ClearRateLimit(ctx, accountID)
 }

backend/internal/service/redeem_service.go

@@ -8,7 +8,8 @@ import (
 	"fmt"
 	"strings"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/pkg/pagination"
+	"sub2api/internal/service/ports"
 	"time"
 
 	"github.com/redis/go-redis/v9"
@@ -25,11 +26,9 @@ var (
 )
 
 const (
-	redeemRateLimitKeyPrefix = "redeem:rate_limit:"
-	redeemLockKeyPrefix      = "redeem:lock:"
-	redeemMaxErrorsPerHour   = 20
-	redeemRateLimitDuration  = time.Hour
-	redeemLockDuration       = 10 * time.Second // 锁超时时间，防止死锁
+	redeemMaxErrorsPerHour  = 20
+	redeemRateLimitDuration = time.Hour
+	redeemLockDuration      = 10 * time.Second // 锁超时时间，防止死锁
 )
 
 // GenerateCodesRequest 生成兑换码请求
@@ -49,26 +48,26 @@ type RedeemCodeResponse struct {
 
 // RedeemService 兑换码服务
 type RedeemService struct {
-	redeemRepo          *repository.RedeemCodeRepository
-	userRepo            *repository.UserRepository
+	redeemRepo          ports.RedeemCodeRepository
+	userRepo            ports.UserRepository
 	subscriptionService *SubscriptionService
-	rdb                 *redis.Client
+	cache               ports.RedeemCache
 	billingCacheService *BillingCacheService
 }
 
 // NewRedeemService 创建兑换码服务实例
 func NewRedeemService(
-	redeemRepo *repository.RedeemCodeRepository,
-	userRepo *repository.UserRepository,
+	redeemRepo ports.RedeemCodeRepository,
+	userRepo ports.UserRepository,
 	subscriptionService *SubscriptionService,
-	rdb *redis.Client,
+	cache ports.RedeemCache,
 	billingCacheService *BillingCacheService,
 ) *RedeemService {
 	return &RedeemService{
 		redeemRepo:          redeemRepo,
 		userRepo:            userRepo,
 		subscriptionService: subscriptionService,
-		rdb:                 rdb,
+		cache:               cache,
 		billingCacheService: billingCacheService,
 	}
 }
@@ -139,13 +138,11 @@ func (s *RedeemService) GenerateCodes(ctx context.Context, req GenerateCodesRequ
 
 // checkRedeemRateLimit 检查用户兑换错误次数是否超限
 func (s *RedeemService) checkRedeemRateLimit(ctx context.Context, userID int64) error {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return nil
 	}
 
-	key := fmt.Sprintf("%s%d", redeemRateLimitKeyPrefix, userID)
-
-	count, err := s.rdb.Get(ctx, key).Int()
+	count, err := s.cache.GetRedeemAttemptCount(ctx, userID)
 	if err != nil && !errors.Is(err, redis.Nil) {
 		// Redis 出错时不阻止用户操作
 		return nil
@@ -160,27 +157,21 @@ func (s *RedeemService) checkRedeemRateLimit(ctx context.Context, userID int64)
 
 // incrementRedeemErrorCount 增加用户兑换错误计数
 func (s *RedeemService) incrementRedeemErrorCount(ctx context.Context, userID int64) {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return
 	}
 
-	key := fmt.Sprintf("%s%d", redeemRateLimitKeyPrefix, userID)
-
-	pipe := s.rdb.Pipeline()
-	pipe.Incr(ctx, key)
-	pipe.Expire(ctx, key, redeemRateLimitDuration)
-	_, _ = pipe.Exec(ctx)
+	_ = s.cache.IncrementRedeemAttemptCount(ctx, userID)
 }
 
 // acquireRedeemLock 尝试获取兑换码的分布式锁
 // 返回 true 表示获取成功，false 表示锁已被占用
 func (s *RedeemService) acquireRedeemLock(ctx context.Context, code string) bool {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return true // 无 Redis 时降级为不加锁
 	}
 
-	key := redeemLockKeyPrefix + code
-	ok, err := s.rdb.SetNX(ctx, key, "1", redeemLockDuration).Result()
+	ok, err := s.cache.AcquireRedeemLock(ctx, code, redeemLockDuration)
 	if err != nil {
 		// Redis 出错时不阻止操作，依赖数据库层面的状态检查
 		return true
@@ -190,12 +181,11 @@ func (s *RedeemService) acquireRedeemLock(ctx context.Context, code string) bool
 
 // releaseRedeemLock 释放兑换码的分布式锁
 func (s *RedeemService) releaseRedeemLock(ctx context.Context, code string) {
-	if s.rdb == nil {
+	if s.cache == nil {
 		return
 	}
 
-	key := redeemLockKeyPrefix + code
-	s.rdb.Del(ctx, key)
+	_ = s.cache.ReleaseRedeemLock(ctx, code)
 }
 
 // Redeem 使用兑换码
@@ -264,7 +254,7 @@ func (s *RedeemService) Redeem(ctx context.Context, userID int64, code string) (
 			go func() {
 				cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 				defer cancel()
-				s.billingCacheService.InvalidateUserBalance(cacheCtx, userID)
+				_ = s.billingCacheService.InvalidateUserBalance(cacheCtx, userID)
 			}()
 		}
 
@@ -295,7 +285,7 @@ func (s *RedeemService) Redeem(ctx context.Context, userID int64, code string) (
 			go func() {
 				cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 				defer cancel()
-				s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
+				_ = s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
 			}()
 		}
 
@@ -337,7 +327,7 @@ func (s *RedeemService) GetByCode(ctx context.Context, code string) (*model.Rede
 }
 
 // List 获取兑换码列表（管理员功能）
-func (s *RedeemService) List(ctx context.Context, params repository.PaginationParams) ([]model.RedeemCode, *repository.PaginationResult, error) {
+func (s *RedeemService) List(ctx context.Context, params pagination.PaginationParams) ([]model.RedeemCode, *pagination.PaginationResult, error) {
 	codes, pagination, err := s.redeemRepo.List(ctx, params)
 	if err != nil {
 		return nil, nil, fmt.Errorf("list redeem codes: %w", err)
@@ -369,12 +359,12 @@ func (s *RedeemService) Delete(ctx context.Context, id int64) error {
 }
 
 // GetStats 获取兑换码统计信息
-func (s *RedeemService) GetStats(ctx context.Context) (map[string]interface{}, error) {
+func (s *RedeemService) GetStats(ctx context.Context) (map[string]any, error) {
 	// TODO: 实现统计逻辑
 	// 统计未使用、已使用的兑换码数量
 	// 统计总面值等
 
-	stats := map[string]interface{}{
+	stats := map[string]any{
 		"total_codes":  0,
 		"unused_codes": 0,
 		"used_codes":   0,

backend/internal/service/service.go

@@ -26,4 +26,6 @@ type Services struct {
 	Subscription *SubscriptionService
 	Concurrency  *ConcurrencyService
 	Identity     *IdentityService
+	Update       *UpdateService
+	TokenRefresh *TokenRefreshService
 }

backend/internal/service/setting_service.go

@@ -2,12 +2,14 @@ package service
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"strconv"
 	"sub2api/internal/config"
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/service/ports"
 
 	"gorm.io/gorm"
 )
@@ -18,12 +20,12 @@ var (
 
 // SettingService 系统设置服务
 type SettingService struct {
-	settingRepo *repository.SettingRepository
+	settingRepo ports.SettingRepository
 	cfg         *config.Config
 }
 
 // NewSettingService 创建系统设置服务实例
-func NewSettingService(settingRepo *repository.SettingRepository, cfg *config.Config) *SettingService {
+func NewSettingService(settingRepo ports.SettingRepository, cfg *config.Config) *SettingService {
 	return &SettingService{
 		settingRepo: settingRepo,
 		cfg:         cfg,
@@ -262,3 +264,63 @@ func (s *SettingService) GetTurnstileSecretKey(ctx context.Context) string {
 	}
 	return value
 }
+
+// GenerateAdminApiKey 生成新的管理员 API Key
+func (s *SettingService) GenerateAdminApiKey(ctx context.Context) (string, error) {
+	// 生成 32 字节随机数 = 64 位十六进制字符
+	bytes := make([]byte, 32)
+	if _, err := rand.Read(bytes); err != nil {
+		return "", fmt.Errorf("generate random bytes: %w", err)
+	}
+
+	key := model.AdminApiKeyPrefix + hex.EncodeToString(bytes)
+
+	// 存储到 settings 表
+	if err := s.settingRepo.Set(ctx, model.SettingKeyAdminApiKey, key); err != nil {
+		return "", fmt.Errorf("save admin api key: %w", err)
+	}
+
+	return key, nil
+}
+
+// GetAdminApiKeyStatus 获取管理员 API Key 状态
+// 返回脱敏的 key、是否存在、错误
+func (s *SettingService) GetAdminApiKeyStatus(ctx context.Context) (maskedKey string, exists bool, err error) {
+	key, err := s.settingRepo.GetValue(ctx, model.SettingKeyAdminApiKey)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return "", false, nil
+		}
+		return "", false, err
+	}
+	if key == "" {
+		return "", false, nil
+	}
+
+	// 脱敏：显示前 10 位和后 4 位
+	if len(key) > 14 {
+		maskedKey = key[:10] + "..." + key[len(key)-4:]
+	} else {
+		maskedKey = key
+	}
+
+	return maskedKey, true, nil
+}
+
+// GetAdminApiKey 获取完整的管理员 API Key（仅供内部验证使用）
+// 如果未配置返回空字符串和 nil 错误，只有数据库错误时才返回 error
+func (s *SettingService) GetAdminApiKey(ctx context.Context) (string, error) {
+	key, err := s.settingRepo.GetValue(ctx, model.SettingKeyAdminApiKey)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return "", nil // 未配置，返回空字符串
+		}
+		return "", err // 数据库错误
+	}
+	return key, nil
+}
+
+// DeleteAdminApiKey 删除管理员 API Key
+func (s *SettingService) DeleteAdminApiKey(ctx context.Context) error {
+	return s.settingRepo.Delete(ctx, model.SettingKeyAdminApiKey)
+}

backend/internal/service/subscription_service.go

@@ -4,10 +4,12 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log"
 	"time"
 
 	"sub2api/internal/model"
-	"sub2api/internal/repository"
+	"sub2api/internal/pkg/pagination"
+	"sub2api/internal/service/ports"
 )
 
 var (
@@ -23,14 +25,16 @@ var (
 
 // SubscriptionService 订阅服务
 type SubscriptionService struct {
-	repos               *repository.Repositories
+	groupRepo           ports.GroupRepository
+	userSubRepo         ports.UserSubscriptionRepository
 	billingCacheService *BillingCacheService
 }
 
 // NewSubscriptionService 创建订阅服务
-func NewSubscriptionService(repos *repository.Repositories, billingCacheService *BillingCacheService) *SubscriptionService {
+func NewSubscriptionService(groupRepo ports.GroupRepository, userSubRepo ports.UserSubscriptionRepository, billingCacheService *BillingCacheService) *SubscriptionService {
 	return &SubscriptionService{
-		repos:               repos,
+		groupRepo:           groupRepo,
+		userSubRepo:         userSubRepo,
 		billingCacheService: billingCacheService,
 	}
 }
@@ -47,7 +51,7 @@ type AssignSubscriptionInput struct {
 // AssignSubscription 分配订阅给用户（不允许重复分配）
 func (s *SubscriptionService) AssignSubscription(ctx context.Context, input *AssignSubscriptionInput) (*model.UserSubscription, error) {
 	// 检查分组是否存在且为订阅类型
-	group, err := s.repos.Group.GetByID(ctx, input.GroupID)
+	group, err := s.groupRepo.GetByID(ctx, input.GroupID)
 	if err != nil {
 		return nil, fmt.Errorf("group not found: %w", err)
 	}
@@ -56,7 +60,7 @@ func (s *SubscriptionService) AssignSubscription(ctx context.Context, input *Ass
 	}
 
 	// 检查是否已存在订阅
-	exists, err := s.repos.UserSubscription.ExistsByUserIDAndGroupID(ctx, input.UserID, input.GroupID)
+	exists, err := s.userSubRepo.ExistsByUserIDAndGroupID(ctx, input.UserID, input.GroupID)
 	if err != nil {
 		return nil, err
 	}
@@ -75,7 +79,7 @@ func (s *SubscriptionService) AssignSubscription(ctx context.Context, input *Ass
 		go func() {
 			cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
-			s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
+			_ = s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
 		}()
 	}
 
@@ -90,7 +94,7 @@ func (s *SubscriptionService) AssignSubscription(ctx context.Context, input *Ass
 // 如果没有订阅：创建新订阅
 func (s *SubscriptionService) AssignOrExtendSubscription(ctx context.Context, input *AssignSubscriptionInput) (*model.UserSubscription, bool, error) {
 	// 检查分组是否存在且为订阅类型
-	group, err := s.repos.Group.GetByID(ctx, input.GroupID)
+	group, err := s.groupRepo.GetByID(ctx, input.GroupID)
 	if err != nil {
 		return nil, false, fmt.Errorf("group not found: %w", err)
 	}
@@ -99,7 +103,7 @@ func (s *SubscriptionService) AssignOrExtendSubscription(ctx context.Context, in
 	}
 
 	// 查询是否已有订阅
-	existingSub, err := s.repos.UserSubscription.GetByUserIDAndGroupID(ctx, input.UserID, input.GroupID)
+	existingSub, err := s.userSubRepo.GetByUserIDAndGroupID(ctx, input.UserID, input.GroupID)
 	if err != nil {
 		// 不存在记录是正常情况，其他错误需要返回
 		existingSub = nil
@@ -124,13 +128,13 @@ func (s *SubscriptionService) AssignOrExtendSubscription(ctx context.Context, in
 		}
 
 		// 更新过期时间
-		if err := s.repos.UserSubscription.ExtendExpiry(ctx, existingSub.ID, newExpiresAt); err != nil {
+		if err := s.userSubRepo.ExtendExpiry(ctx, existingSub.ID, newExpiresAt); err != nil {
 			return nil, false, fmt.Errorf("extend subscription: %w", err)
 		}
 
 		// 如果订阅已过期或被暂停，恢复为active状态
 		if existingSub.Status != model.SubscriptionStatusActive {
-			if err := s.repos.UserSubscription.UpdateStatus(ctx, existingSub.ID, model.SubscriptionStatusActive); err != nil {
+			if err := s.userSubRepo.UpdateStatus(ctx, existingSub.ID, model.SubscriptionStatusActive); err != nil {
 				return nil, false, fmt.Errorf("update subscription status: %w", err)
 			}
 		}
@@ -142,8 +146,8 @@ func (s *SubscriptionService) AssignOrExtendSubscription(ctx context.Context, in
 				newNotes += "\n"
 			}
 			newNotes += input.Notes
-			if err := s.repos.UserSubscription.UpdateNotes(ctx, existingSub.ID, newNotes); err != nil {
-				// 备注更新失败不影响主流程
+			if err := s.userSubRepo.UpdateNotes(ctx, existingSub.ID, newNotes); err != nil {
+				log.Printf("update subscription notes failed: sub_id=%d err=%v", existingSub.ID, err)
 			}
 		}
 
@@ -153,12 +157,12 @@ func (s *SubscriptionService) AssignOrExtendSubscription(ctx context.Context, in
 			go func() {
 				cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 				defer cancel()
-				s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
+				_ = s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
 			}()
 		}
 
 		// 返回更新后的订阅
-		sub, err := s.repos.UserSubscription.GetByID(ctx, existingSub.ID)
+		sub, err := s.userSubRepo.GetByID(ctx, existingSub.ID)
 		return sub, true, err // true 表示是续期
 	}
 
@@ -174,7 +178,7 @@ func (s *SubscriptionService) AssignOrExtendSubscription(ctx context.Context, in
 		go func() {
 			cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
-			s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
+			_ = s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
 		}()
 	}
 
@@ -205,12 +209,12 @@ func (s *SubscriptionService) createSubscription(ctx context.Context, input *Ass
 		sub.AssignedBy = &input.AssignedBy
 	}
 
-	if err := s.repos.UserSubscription.Create(ctx, sub); err != nil {
+	if err := s.userSubRepo.Create(ctx, sub); err != nil {
 		return nil, err
 	}
 
 	// 重新获取完整订阅信息（包含关联）
-	return s.repos.UserSubscription.GetByID(ctx, sub.ID)
+	return s.userSubRepo.GetByID(ctx, sub.ID)
 }
 
 // BulkAssignSubscriptionInput 批量分配订阅输入
@@ -260,12 +264,12 @@ func (s *SubscriptionService) BulkAssignSubscription(ctx context.Context, input
 // RevokeSubscription 撤销订阅
 func (s *SubscriptionService) RevokeSubscription(ctx context.Context, subscriptionID int64) error {
 	// 先获取订阅信息用于失效缓存
-	sub, err := s.repos.UserSubscription.GetByID(ctx, subscriptionID)
+	sub, err := s.userSubRepo.GetByID(ctx, subscriptionID)
 	if err != nil {
 		return err
 	}
 
-	if err := s.repos.UserSubscription.Delete(ctx, subscriptionID); err != nil {
+	if err := s.userSubRepo.Delete(ctx, subscriptionID); err != nil {
 		return err
 	}
 
@@ -275,7 +279,7 @@ func (s *SubscriptionService) RevokeSubscription(ctx context.Context, subscripti
 		go func() {
 			cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
-			s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
+			_ = s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
 		}()
 	}
 
@@ -284,20 +288,20 @@ func (s *SubscriptionService) RevokeSubscription(ctx context.Context, subscripti
 
 // ExtendSubscription 延长订阅
 func (s *SubscriptionService) ExtendSubscription(ctx context.Context, subscriptionID int64, days int) (*model.UserSubscription, error) {
-	sub, err := s.repos.UserSubscription.GetByID(ctx, subscriptionID)
+	sub, err := s.userSubRepo.GetByID(ctx, subscriptionID)
 	if err != nil {
 		return nil, ErrSubscriptionNotFound
 	}
 
 	// 计算新的过期时间
 	newExpiresAt := sub.ExpiresAt.AddDate(0, 0, days)
-	if err := s.repos.UserSubscription.ExtendExpiry(ctx, subscriptionID, newExpiresAt); err != nil {
+	if err := s.userSubRepo.ExtendExpiry(ctx, subscriptionID, newExpiresAt); err != nil {
 		return nil, err
 	}
 
 	// 如果订阅已过期，恢复为active状态
 	if sub.Status == model.SubscriptionStatusExpired {
-		if err := s.repos.UserSubscription.UpdateStatus(ctx, subscriptionID, model.SubscriptionStatusActive); err != nil {
+		if err := s.userSubRepo.UpdateStatus(ctx, subscriptionID, model.SubscriptionStatusActive); err != nil {
 			return nil, err
 		}
 	}
@@ -308,21 +312,21 @@ func (s *SubscriptionService) ExtendSubscription(ctx context.Context, subscripti
 		go func() {
 			cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
-			s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
+			_ = s.billingCacheService.InvalidateSubscription(cacheCtx, userID, groupID)
 		}()
 	}
 
-	return s.repos.UserSubscription.GetByID(ctx, subscriptionID)
+	return s.userSubRepo.GetByID(ctx, subscriptionID)
 }
 
 // GetByID 根据ID获取订阅
 func (s *SubscriptionService) GetByID(ctx context.Context, id int64) (*model.UserSubscription, error) {
-	return s.repos.UserSubscription.GetByID(ctx, id)
+	return s.userSubRepo.GetByID(ctx, id)
 }
 
 // GetActiveSubscription 获取用户对特定分组的有效订阅
 func (s *SubscriptionService) GetActiveSubscription(ctx context.Context, userID, groupID int64) (*model.UserSubscription, error) {
-	sub, err := s.repos.UserSubscription.GetActiveByUserIDAndGroupID(ctx, userID, groupID)
+	sub, err := s.userSubRepo.GetActiveByUserIDAndGroupID(ctx, userID, groupID)
 	if err != nil {
 		return nil, ErrSubscriptionNotFound
 	}
@@ -331,24 +335,29 @@ func (s *SubscriptionService) GetActiveSubscription(ctx context.Context, userID,
 
 // ListUserSubscriptions 获取用户的所有订阅
 func (s *SubscriptionService) ListUserSubscriptions(ctx context.Context, userID int64) ([]model.UserSubscription, error) {
-	return s.repos.UserSubscription.ListByUserID(ctx, userID)
+	return s.userSubRepo.ListByUserID(ctx, userID)
 }
 
 // ListActiveUserSubscriptions 获取用户的所有有效订阅
 func (s *SubscriptionService) ListActiveUserSubscriptions(ctx context.Context, userID int64) ([]model.UserSubscription, error) {
-	return s.repos.UserSubscription.ListActiveByUserID(ctx, userID)
+	return s.userSubRepo.ListActiveByUserID(ctx, userID)
 }
 
 // ListGroupSubscriptions 获取分组的所有订阅
-func (s *SubscriptionService) ListGroupSubscriptions(ctx context.Context, groupID int64, page, pageSize int) ([]model.UserSubscription, *repository.PaginationResult, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
-	return s.repos.UserSubscription.ListByGroupID(ctx, groupID, params)
+func (s *SubscriptionService) ListGroupSubscriptions(ctx context.Context, groupID int64, page, pageSize int) ([]model.UserSubscription, *pagination.PaginationResult, error) {
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
+	return s.userSubRepo.ListByGroupID(ctx, groupID, params)
 }
 
 // List 获取所有订阅（分页，支持筛选）
-func (s *SubscriptionService) List(ctx context.Context, page, pageSize int, userID, groupID *int64, status string) ([]model.UserSubscription, *repository.PaginationResult, error) {
-	params := repository.PaginationParams{Page: page, PageSize: pageSize}
-	return s.repos.UserSubscription.List(ctx, params, userID, groupID, status)
+func (s *SubscriptionService) List(ctx context.Context, page, pageSize int, userID, groupID *int64, status string) ([]model.UserSubscription, *pagination.PaginationResult, error) {
+	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
+	return s.userSubRepo.List(ctx, params, userID, groupID, status)
+}
+
+// startOfDay 返回给定时间所在日期的零点（保持原时区）
+func startOfDay(t time.Time) time.Time {
+	return time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location())
 }
 
 // CheckAndActivateWindow 检查并激活窗口（首次使用时）
@@ -357,39 +366,50 @@ func (s *SubscriptionService) CheckAndActivateWindow(ctx context.Context, sub *m
 		return nil
 	}
 
-	now := time.Now()
-	return s.repos.UserSubscription.ActivateWindows(ctx, sub.ID, now)
+	// 使用当天零点作为窗口起始时间
+	windowStart := startOfDay(time.Now())
+	return s.userSubRepo.ActivateWindows(ctx, sub.ID, windowStart)
 }
 
 // CheckAndResetWindows 检查并重置过期的窗口
 func (s *SubscriptionService) CheckAndResetWindows(ctx context.Context, sub *model.UserSubscription) error {
-	now := time.Now()
+	// 使用当天零点作为新窗口起始时间
+	windowStart := startOfDay(time.Now())
+	needsInvalidateCache := false
 
 	// 日窗口重置（24小时）
 	if sub.NeedsDailyReset() {
-		if err := s.repos.UserSubscription.ResetDailyUsage(ctx, sub.ID, now); err != nil {
+		if err := s.userSubRepo.ResetDailyUsage(ctx, sub.ID, windowStart); err != nil {
 			return err
 		}
-		sub.DailyWindowStart = &now
+		sub.DailyWindowStart = &windowStart
 		sub.DailyUsageUSD = 0
+		needsInvalidateCache = true
 	}
 
 	// 周窗口重置（7天）
 	if sub.NeedsWeeklyReset() {
-		if err := s.repos.UserSubscription.ResetWeeklyUsage(ctx, sub.ID, now); err != nil {
+		if err := s.userSubRepo.ResetWeeklyUsage(ctx, sub.ID, windowStart); err != nil {
 			return err
 		}
-		sub.WeeklyWindowStart = &now
+		sub.WeeklyWindowStart = &windowStart
 		sub.WeeklyUsageUSD = 0
+		needsInvalidateCache = true
 	}
 
 	// 月窗口重置（30天）
 	if sub.NeedsMonthlyReset() {
-		if err := s.repos.UserSubscription.ResetMonthlyUsage(ctx, sub.ID, now); err != nil {
+		if err := s.userSubRepo.ResetMonthlyUsage(ctx, sub.ID, windowStart); err != nil {
 			return err
 		}
-		sub.MonthlyWindowStart = &now
+		sub.MonthlyWindowStart = &windowStart
 		sub.MonthlyUsageUSD = 0
+		needsInvalidateCache = true
+	}
+
+	// 如果有窗口被重置，失效 Redis 缓存以保持一致性
+	if needsInvalidateCache && s.billingCacheService != nil {
+		_ = s.billingCacheService.InvalidateSubscription(ctx, sub.UserID, sub.GroupID)
 	}
 
 	return nil
@@ -411,7 +431,7 @@ func (s *SubscriptionService) CheckUsageLimits(ctx context.Context, sub *model.U
 
 // RecordUsage 记录使用量到订阅
 func (s *SubscriptionService) RecordUsage(ctx context.Context, subscriptionID int64, costUSD float64) error {
-	return s.repos.UserSubscription.IncrementUsage(ctx, subscriptionID, costUSD)
+	return s.userSubRepo.IncrementUsage(ctx, subscriptionID, costUSD)
 }
 
 // SubscriptionProgress 订阅进度
@@ -438,14 +458,14 @@ type UsageWindowProgress struct {
 
 // GetSubscriptionProgress 获取订阅使用进度
 func (s *SubscriptionService) GetSubscriptionProgress(ctx context.Context, subscriptionID int64) (*SubscriptionProgress, error) {
-	sub, err := s.repos.UserSubscription.GetByID(ctx, subscriptionID)
+	sub, err := s.userSubRepo.GetByID(ctx, subscriptionID)
 	if err != nil {
 		return nil, ErrSubscriptionNotFound
 	}
 
 	group := sub.Group
 	if group == nil {
-		group, err = s.repos.Group.GetByID(ctx, sub.GroupID)
+		group, err = s.groupRepo.GetByID(ctx, sub.GroupID)
 		if err != nil {
 			return nil, err
 		}
@@ -535,7 +555,7 @@ func (s *SubscriptionService) GetSubscriptionProgress(ctx context.Context, subsc
 
 // GetUserSubscriptionsWithProgress 获取用户所有订阅及进度
 func (s *SubscriptionService) GetUserSubscriptionsWithProgress(ctx context.Context, userID int64) ([]SubscriptionProgress, error) {
-	subs, err := s.repos.UserSubscription.ListActiveByUserID(ctx, userID)
+	subs, err := s.userSubRepo.ListActiveByUserID(ctx, userID)
 	if err != nil {
 		return nil, err
 	}
@@ -554,7 +574,7 @@ func (s *SubscriptionService) GetUserSubscriptionsWithProgress(ctx context.Conte
 
 // UpdateExpiredSubscriptions 更新过期订阅状态（定时任务调用）
 func (s *SubscriptionService) UpdateExpiredSubscriptions(ctx context.Context) (int64, error) {
-	return s.repos.UserSubscription.BatchUpdateExpiredStatus(ctx)
+	return s.userSubRepo.BatchUpdateExpiredStatus(ctx)
 }
 
 // ValidateSubscription 验证订阅是否有效
@@ -567,7 +587,7 @@ func (s *SubscriptionService) ValidateSubscription(ctx context.Context, sub *mod
 	}
 	if sub.IsExpired() {
 		// 更新状态
-		_ = s.repos.UserSubscription.UpdateStatus(ctx, sub.ID, model.SubscriptionStatusExpired)
+		_ = s.userSubRepo.UpdateStatus(ctx, sub.ID, model.SubscriptionStatusExpired)
 		return ErrSubscriptionExpired
 	}
 	return nil