refactor(openai): simplify connection and endpoint module files

Restore connection.rs for production and integration tests by folding the
heartbeat tests into the existing connection test module. Keep all heartbeat
coverage while satisfying the workspace layout rules without a subdirectory.

Rename provider_endpoint.rs to endpoint.rs in production and tests. Update
module declarations, imports and frozen file manifests to match.

Validation: gateway application tests (36 passed), all gateway-api tests
(263 passed), workspace rustfmt, and strict gateway-api Clippy with all
targets and features.

Co-authored-by: Codex <noreply@openai.com>

.github/dependabot.yml

@@ -21,6 +21,11 @@ updates:
       day: monday
       time: '09:10'
       timezone: Asia/Shanghai
+    # 固定官方 Codex Desktop 的 TLS 指纹；升级前必须抓取握手并比对扩展顺序。
+    ignore:
+      - dependency-name: hyper-rustls
+      - dependency-name: reqwest
+      - dependency-name: rustls
     groups:
       minor-and-patch:
         update-types:
@@ -34,6 +39,8 @@ updates:
       day: monday
       time: '09:20'
       timezone: Asia/Shanghai
+    cooldown:
+      default-days: 1
     groups:
       minor-and-patch:
         update-types:

.github/workflows/_container.yml

@@ -19,30 +19,33 @@ jobs:
     env:
       COMPOSE_PROJECT_NAME: cpr-ci-${{ github.run_id }}-${{ github.run_attempt }}
       CPR_IMAGE: codex-proxy-rs:ci-${{ inputs.ref }}
-      CPR_ADMIN_DEFAULT_PASSWORD: 'admin @:/?#%2F ci password'
-      CPR_POSTGRES_PASSWORD: 'pg @:/?#%2F ci'
-      CPR_REDIS_PASSWORD: 'redis @:/?#%2F ci'
-      CPR_SMOKE_PORT: '18080'
       TRIVY_QUIET: 'true'
       TRIVY_SKIP_VERSION_CHECK: 'true'
     steps:
-      - name: Define isolated runtime paths
+      - name: Define isolated runtime values
         shell: bash
         run: |
+          set -euo pipefail
+          admin_password="$(openssl rand -hex 24)"
+          postgres_password="$(openssl rand -hex 24)"
+          redis_password="$(openssl rand -hex 24)"
+          echo "::add-mask::$admin_password"
+          echo "::add-mask::$postgres_password"
+          echo "::add-mask::$redis_password"
           {
-            echo "CPR_CONFIG_FILE=$GITHUB_WORKSPACE/.runtime/ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT/config.yaml"
-            echo "CPR_DATA_DIR=$GITHUB_WORKSPACE/.runtime/ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT/data"
-            echo "CPR_LOG_DIR=$GITHUB_WORKSPACE/.runtime/ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT/logs"
             echo "DIAGNOSTICS_DIR=$RUNNER_TEMP/codex-proxy-rs-diagnostics"
+            echo "CI_ADMIN_PASSWORD=$admin_password"
+            echo "CI_POSTGRES_PASSWORD=$postgres_password"
+            echo "CI_REDIS_PASSWORD=$redis_password"
           } >> "$GITHUB_ENV"
 
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Build runtime image
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
@@ -52,6 +55,9 @@ jobs:
           target: runtime
           load: true
           tags: ${{ env.CPR_IMAGE }}
+          no-cache-filters: |
+            runtime-base
+            runtime
           cache-from: type=gha,scope=runtime-ci
           cache-to: type=gha,mode=max,scope=runtime-ci
 
@@ -73,7 +79,7 @@ jobs:
           ${{ hashFiles('trivy-results.sarif') != '' &&
               (github.event_name != 'pull_request' ||
                github.event.pull_request.head.repo.full_name == github.repository) }}
-        uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
         with:
           sarif_file: trivy-results.sarif
           category: runtime-container
@@ -94,19 +100,35 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          runtime_dir="$(dirname "$CPR_CONFIG_FILE")"
-          mkdir -p "$runtime_dir" "$DIAGNOSTICS_DIR"
-          sudo install -d -m 0770 -o "$(id -u)" -g 10001 "$CPR_DATA_DIR" "$CPR_LOG_DIR"
-          cp deploy/config.example.yaml "$CPR_CONFIG_FILE"
-          sudo chown "$(id -u):10001" "$CPR_CONFIG_FILE"
-          chmod 0640 "$CPR_CONFIG_FILE"
+          umask 0077
+          # Bind roots hand off ownership to the image-specific database users.
+          # Sticky directories keep that initialization compatible with user-namespaced runners.
+          install -d -m 1777 .runtime/postgres .runtime/redis
+          mkdir -p "$DIAGNOSTICS_DIR"
+          sudo install -d -m 0770 -o "$(id -u)" -g 10001 \
+            .runtime/data .runtime/logs
+          ruby <<'RUBY'
+          path = "deploy/config.example.yaml"
+          content = File.read(path)
+          replacements = {
+            "password: &postgres_password ''" => "password: &postgres_password '#{ENV.fetch("CI_POSTGRES_PASSWORD")}'",
+            "password: &redis_password ''" => "password: &redis_password '#{ENV.fetch("CI_REDIS_PASSWORD")}'",
+            "default_password: ''" => "default_password: '#{ENV.fetch("CI_ADMIN_PASSWORD")}'",
+          }
+          replacements.each do |placeholder, configured|
+            raise "missing config placeholder: #{placeholder}" unless content.sub!(placeholder, configured)
+          end
+          File.write("deploy/config.yaml", content)
+          RUBY
+          sudo chown "$(id -u):10001" deploy/config.yaml
+          chmod 0640 deploy/config.yaml
 
       - name: Validate Docker Compose
         shell: bash
         run: |
           set -euo pipefail
           docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/docker-compose.yml -f deploy/docker-compose.smoke.yml config --quiet
+            -f deploy/compose.yaml config --quiet
 
       - name: Configure Redis host memory overcommit
         shell: bash
@@ -120,25 +142,25 @@ jobs:
         run: |
           set -euo pipefail
           compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/docker-compose.yml -f deploy/docker-compose.smoke.yml)
+            -f deploy/compose.yaml)
           "${compose[@]}" up -d --no-build --wait postgres redis
-          test "$("${compose[@]}" exec -T -e PGPASSWORD="$CPR_POSTGRES_PASSWORD" postgres \
+          test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
             psql -At -U codex_proxy -d codex_proxy -c "SHOW TimeZone;" | tr -d '\r')" = Asia/Shanghai
-          "${compose[@]}" exec -T -e PGPASSWORD="$CPR_POSTGRES_PASSWORD" postgres \
+          "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
             psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
             "CREATE TABLE cpr_ci_persistence_probe (value text PRIMARY KEY); INSERT INTO cpr_ci_persistence_probe VALUES ('persisted');"
-          "${compose[@]}" exec -T -e REDISCLI_AUTH="$CPR_REDIS_PASSWORD" redis \
+          "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
             redis-cli SET cpr:ci:persistence-probe persisted
           "${compose[@]}" up -d --no-build --wait --force-recreate postgres redis
-          test "$("${compose[@]}" exec -T -e PGPASSWORD="$CPR_POSTGRES_PASSWORD" postgres \
+          test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
             psql -At -U codex_proxy -d codex_proxy -c \
             "SELECT value FROM cpr_ci_persistence_probe;")" = persisted
-          test "$("${compose[@]}" exec -T -e REDISCLI_AUTH="$CPR_REDIS_PASSWORD" redis \
+          test "$("${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
             redis-cli --raw GET cpr:ci:persistence-probe | tr -d '\r')" = persisted
-          "${compose[@]}" exec -T -e PGPASSWORD="$CPR_POSTGRES_PASSWORD" postgres \
+          "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
             psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
             "DROP TABLE cpr_ci_persistence_probe;"
-          "${compose[@]}" exec -T -e REDISCLI_AUTH="$CPR_REDIS_PASSWORD" redis \
+          "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
             redis-cli DEL cpr:ci:persistence-probe
 
       - name: Start and verify application
@@ -146,24 +168,24 @@ jobs:
         run: |
           set -euo pipefail
           compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/docker-compose.yml -f deploy/docker-compose.smoke.yml)
+            -f deploy/compose.yaml)
           "${compose[@]}" up -d --no-build --wait codex-proxy-rs
           status="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
-            "http://127.0.0.1:${CPR_SMOKE_PORT}/healthz")"
+            "http://127.0.0.1:8080/healthz")"
           test "$status" = 204
           test "$("${compose[@]}" exec -T codex-proxy-rs id -u | tr -d '\r')" = 10001
           test "$("${compose[@]}" exec -T codex-proxy-rs id -g | tr -d '\r')" = 10001
           test "$("${compose[@]}" exec -T codex-proxy-rs date +%z | tr -d '\r')" = +0800
           test "$("${compose[@]}" exec -T codex-proxy-rs cat /etc/timezone | tr -d '\r')" = Asia/Shanghai
           "${compose[@]}" exec -T codex-proxy-rs sh -c \
-            'touch /app/data/.ci-write /app/logs/.ci-write && rm /app/data/.ci-write /app/logs/.ci-write'
+            'touch /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write && rm /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write'
 
       - name: Verify clean logs and graceful shutdown
         shell: bash
         run: |
           set -euo pipefail
           compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/docker-compose.yml -f deploy/docker-compose.smoke.yml)
+            -f deploy/compose.yaml)
           "${compose[@]}" stop --timeout 30 codex-proxy-rs
           container_id="$("${compose[@]}" ps -a -q codex-proxy-rs)"
           test -n "$container_id"
@@ -195,7 +217,7 @@ jobs:
           mkdir -p "$DIAGNOSTICS_DIR"
           raw_dir="$(mktemp -d)"
           compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/docker-compose.yml -f deploy/docker-compose.smoke.yml)
+            -f deploy/compose.yaml)
           "${compose[@]}" config > "$raw_dir/compose-config.yaml" 2>&1
           "${compose[@]}" ps -a > "$raw_dir/compose-ps.txt" 2>&1
           "${compose[@]}" logs --no-color --timestamps > "$raw_dir/compose.log" 2>&1
@@ -207,9 +229,9 @@ jobs:
           raw_dir = ENV.fetch("RAW_DIR")
           output_dir = ENV.fetch("OUTPUT_DIR")
           secrets = [
-            ENV.fetch("CPR_ADMIN_DEFAULT_PASSWORD"),
-            ENV.fetch("CPR_POSTGRES_PASSWORD"),
-            ENV.fetch("CPR_REDIS_PASSWORD"),
+            ENV.fetch("CI_ADMIN_PASSWORD"),
+            ENV.fetch("CI_POSTGRES_PASSWORD"),
+            ENV.fetch("CI_REDIS_PASSWORD"),
           ]
           encoded_secrets = secrets.map do |secret|
             secret.encode("UTF-8").bytes.map do |byte|
@@ -243,6 +265,5 @@ jobs:
         shell: bash
         run: |
           docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/docker-compose.yml -f deploy/docker-compose.smoke.yml \
-            down --volumes --remove-orphans || true
-          sudo rm -rf "$GITHUB_WORKSPACE/.runtime/ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+            -f deploy/compose.yaml down --remove-orphans || true
+          sudo rm -rf "$GITHUB_WORKSPACE/.runtime" "$GITHUB_WORKSPACE/deploy/config.yaml"

.github/workflows/_quality.yml

@@ -12,16 +12,29 @@ on:
         required: false
         default: false
         type: boolean
+      run_backend:
+        description: Run backend quality checks
+        required: false
+        default: true
+        type: boolean
+      run_frontend:
+        description: Run frontend quality checks
+        required: false
+        default: true
+        type: boolean
 
 permissions:
   contents: read
 
 jobs:
   backend:
+    if: inputs.run_backend
     runs-on: ubuntu-latest
     timeout-minutes: 30
     env:
       CARGO_TERM_COLOR: always
+      # Rust 1.97 编译 AWS SDK 调试信息需要更大的 codegen 线程栈。
+      RUST_MIN_STACK: 16777216
       CPR_TEST_DATABASE_URL: postgres://codex_proxy:codex_proxy@127.0.0.1:5432/codex_proxy
       CPR_TEST_REDIS_URL: redis://127.0.0.1:6379
     services:
@@ -50,9 +63,44 @@ jobs:
           --health-retries 10
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
+          # PR 场景需要 base 提交做冻结清单的 append-only 比对。
+          fetch-depth: ${{ github.event_name == 'pull_request' && 0 || 1 }}
+
+      # 已应用迁移的字节被 sqlx 启动校验钉死：改动已发布迁移会让所有
+      # 存量部署重启即失败。冻结清单保证旧文件不被改、新文件必须入册。
+      - name: Migration freeze check
+        working-directory: backend/migrations
+        shell: bash
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          set -euo pipefail
+          sha256sum --check --strict .frozen-sha256
+          for file in *.sql; do
+            if ! awk '{print $2}' .frozen-sha256 | grep -Fxq "$file"; then
+              echo "::error file=backend/migrations/$file::migration $file is not frozen; append its sha256 to backend/migrations/.frozen-sha256"
+              exit 1
+            fi
+          done
+          # 清单自证不足以防「改迁移 + 同 PR 刷新清单行」：校验对新哈希通过。
+          # 对 PR，断言 .frozen-sha256 相对 base 只增不改——base 里的每一行
+          # 必须原样保留（改哈希＝删行，删迁移＝删行，都会被挡）。
+          if [ -n "${BASE_SHA:-}" ]; then
+            base_manifest="$(git show "${BASE_SHA}:backend/migrations/.frozen-sha256" 2>/dev/null || true)"
+            if [ -n "$base_manifest" ]; then
+              while IFS= read -r line; do
+                [ -z "$line" ] && continue
+                if ! grep -Fxq "$line" .frozen-sha256; then
+                  file="$(printf '%s' "$line" | awk '{print $2}')"
+                  echo "::error file=backend/migrations/.frozen-sha256::frozen migration $file was modified or removed; released migrations are append-only — add a new numbered migration instead"
+                  exit 1
+                fi
+              done <<< "$base_manifest"
+            fi
+          fi
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
@@ -60,7 +108,7 @@ jobs:
           components: rustfmt,clippy
 
       - name: Cache Rust
-        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
         with:
           workspaces: backend -> target
 
@@ -70,30 +118,53 @@ jobs:
 
       - name: Rust clippy
         working-directory: backend
-        run: cargo clippy --all-targets --all-features --locked
+        run: cargo clippy --all-targets --all-features --locked -- -D warnings
+
+      - name: Configure PostgreSQL and Redis test authentication
+        shell: bash
+        run: |
+          set -euo pipefail
+          postgres_password="$(openssl rand -hex 24)"
+          redis_password="$(openssl rand -hex 24)"
+          echo "::add-mask::$postgres_password"
+          echo "::add-mask::$redis_password"
+          docker exec --env PGPASSWORD=codex_proxy "${{ job.services.postgres.id }}" psql \
+            --username=codex_proxy --dbname=codex_proxy \
+            --set=ON_ERROR_STOP=1 \
+            --command="ALTER USER codex_proxy WITH PASSWORD '${postgres_password}'" >/dev/null
+          docker exec --env PGPASSWORD="$postgres_password" "${{ job.services.postgres.id }}" psql \
+            --username=codex_proxy --dbname=codex_proxy \
+            --set=ON_ERROR_STOP=1 --command='SELECT 1' >/dev/null
+          docker exec "${{ job.services.redis.id }}" redis-cli CONFIG SET requirepass "$redis_password" >/dev/null
+          docker exec "${{ job.services.redis.id }}" redis-cli --no-auth-warning -a "$redis_password" ping >/dev/null
+          {
+            echo "CPR_TEST_DATABASE_URL=postgres://codex_proxy:${postgres_password}@127.0.0.1:5432/codex_proxy"
+            echo "CPR_TEST_REDIS_URL=redis://:${redis_password}@127.0.0.1:6379"
+          } >> "$GITHUB_ENV"
 
       - name: Rust tests
         working-directory: backend
         run: cargo test --test main --locked
 
   frontend:
+    if: inputs.run_frontend
     runs-on: ubuntu-latest
     timeout-minutes: 15
     env:
       CI: 'true'
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
         with:
           version: 11.7.0
 
       - name: Setup Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
           cache: pnpm
@@ -122,7 +193,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
 

.github/workflows/ci.yml

@@ -3,8 +3,12 @@ name: CI
 on:
   push:
     branches:
-      - '**'
+      - main
+    paths-ignore:
+      - 'release/version.yaml'
   pull_request:
+    branches:
+      - main
 
 permissions:
   contents: read
@@ -18,19 +22,28 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     outputs:
+      backend: ${{ steps.filter.outputs.backend }}
+      frontend: ${{ steps.filter.outputs.frontend }}
       container: ${{ steps.filter.outputs.container }}
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
           fetch-depth: 0
 
-      - name: Detect container changes
+      - name: Detect affected checks
         id: filter
-        uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
+        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
         with:
           filters: |
+            backend:
+              - 'backend/**'
+              - 'release/version.yaml'
+              - '.github/workflows/**'
+            frontend:
+              - 'frontend/**'
+              - '.github/workflows/**'
             container:
               - 'backend/**'
               - 'frontend/**'
@@ -41,12 +54,15 @@ jobs:
               - '.github/workflows/ci.yml'
 
   quality:
+    needs: changes
     uses: ./.github/workflows/_quality.yml
     with:
       ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      run_backend: ${{ needs.changes.outputs.backend == 'true' }}
+      run_frontend: ${{ needs.changes.outputs.frontend == 'true' }}
 
   container:
-    needs: [changes, quality]
+    needs: changes
     if: needs.changes.outputs.container == 'true'
     permissions:
       contents: read

.github/workflows/release.yml

@@ -1,9 +1,6 @@
 name: Release
 
 on:
-  push:
-    tags:
-      - 'v*'
   workflow_dispatch:
     inputs:
       tag:
@@ -15,7 +12,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: release-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+  group: release-${{ inputs.tag }}
   cancel-in-progress: false
 
 env:
@@ -29,6 +26,7 @@ jobs:
     outputs:
       tag: ${{ steps.version.outputs.tag }}
       version: ${{ steps.version.outputs.version }}
+      docker_version: ${{ steps.version.outputs.docker_version }}
       build_time: ${{ steps.version.outputs.build_time }}
       git_sha: ${{ steps.version.outputs.git_sha }}
       platform_matrix: ${{ steps.version.outputs.platform_matrix }}
@@ -40,16 +38,16 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
+          ref: ${{ inputs.tag }}
           fetch-depth: 0
 
       - name: Read release metadata
         id: version
         shell: bash
         env:
-          RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+          RELEASE_TAG: ${{ inputs.tag }}
         run: |
           ruby <<'RUBY' >> "$GITHUB_OUTPUT"
           require "json"
@@ -104,7 +102,7 @@ jobs:
               require_string(platform, key, "#{platforms_path}: platforms[#{index}]")
             end
             archive = platform["archive"]
-            fail("#{platforms_path}: platforms[#{index}].archive must be tar.gz or zip") unless ["tar.gz", "zip"].include?(archive)
+            fail("#{platforms_path}: platforms[#{index}].archive must be tar.gz") unless archive == "tar.gz"
             platform_key = "#{platform["os"]}-#{platform["arch"]}"
             fail("#{platforms_path}: duplicate platform #{platform_key}") if seen_platforms[platform_key]
             seen_platforms[platform_key] = true
@@ -146,6 +144,8 @@ jobs:
 
           puts "tag=#{release_tag}"
           puts "version=#{version}"
+          # Docker tags forbid "+", so semver build metadata maps to "-" in image tags.
+          puts "docker_version=#{version.tr("+", "-")}"
           puts "build_time=#{Time.now.utc.iso8601}"
           puts "git_sha=#{git_sha.strip}"
           puts "platform_matrix=#{matrix}"
@@ -163,9 +163,18 @@ jobs:
       ref: ${{ needs.release-info.outputs.git_sha }}
       upload_frontend: true
 
+  container:
+    needs: [release-info]
+    permissions:
+      contents: read
+      security-events: write
+    uses: ./.github/workflows/_container.yml
+    with:
+      ref: ${{ needs.release-info.outputs.git_sha }}
+
   build-docker-binary:
     name: build-docker-binary (${{ matrix.os }}-${{ matrix.arch }})
-    needs: [release-info, quality]
+    needs: release-info
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.release-info.outputs.docker_matrix) }}
@@ -174,7 +183,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -185,9 +194,9 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             backend/target
-          key: cargo-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock') }}
+          key: cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
           restore-keys: |
-            cargo-${{ runner.os }}-${{ matrix.target }}-
+            cargo-v2-${{ runner.os }}-${{ matrix.target }}-
 
       - name: Build binary
         shell: bash
@@ -205,7 +214,7 @@ jobs:
             -v "$HOME/.cargo:/cargo" \
             -v "$PWD/..:/workspace" \
             -w /workspace/backend \
-            rust:1.97-bookworm@sha256:7d0723df719e7f213b69dc7c8c595985c3f4b060cfbee4f7bc0e347a86fe3b6a \
+            rust:1.97-bookworm@sha256:77fac8b98f9f46062bb680b6d25d5bcaabfc400143952ebc572e924bcbedc3fa \
             cargo build --release --locked --target "${{ matrix.target }}" --bin codex-proxy-rs
           cp "target/${{ matrix.target }}/release/${{ matrix.binary }}" "../dist/binaries/${{ matrix.os }}-${{ matrix.arch }}/${{ matrix.binary }}"
         working-directory: backend
@@ -225,7 +234,7 @@ jobs:
 
   build-binary:
     name: build-binary (${{ matrix.os }}-${{ matrix.arch }})
-    needs: [release-info, quality]
+    needs: release-info
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.release-info.outputs.non_docker_matrix) }}
@@ -234,7 +243,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -250,9 +259,9 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             backend/target
-          key: cargo-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock') }}
+          key: cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
           restore-keys: |
-            cargo-${{ runner.os }}-${{ matrix.target }}-
+            cargo-v2-${{ runner.os }}-${{ matrix.target }}-
 
       - name: Build binary
         shell: bash
@@ -286,7 +295,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -321,7 +330,6 @@ jobs:
           import pathlib
           import shutil
           import tarfile
-          import zipfile
 
           APP_NAME = "codex-proxy-rs"
 
@@ -357,8 +365,7 @@ jobs:
 
               binary_dest = package_root / platform["binary"]
               shutil.copy2(binary_src, binary_dest)
-              if platform["os"] != "windows":
-                  binary_dest.chmod(0o755)
+              binary_dest.chmod(0o755)
               shutil.copytree(frontend_dir, web_dist, dirs_exist_ok=True)
 
               archive_name = f"{APP_NAME}_{version}_{platform['os']}_{platform['arch']}.{platform['archive']}"
@@ -366,11 +373,6 @@ jobs:
               if platform["archive"] == "tar.gz":
                   with tarfile.open(archive_path, "w:gz") as archive:
                       archive.add(package_root, arcname=APP_NAME)
-              elif platform["archive"] == "zip":
-                  with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as archive:
-                      for path in sorted(package_root.rglob("*")):
-                          if path.is_file():
-                              archive.write(path, path.relative_to(package_dir))
               else:
                   raise SystemExit(f"Unsupported archive format: {platform['archive']}")
               archives.append(archive_path)
@@ -382,7 +384,7 @@ jobs:
           PY
 
       - name: Generate release asset provenance
-        uses: actions/attest@a1948c3f048ba23858d222213b7c278aabede763 # v4.1.1
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
           subject-path: dist/release/*
 
@@ -412,7 +414,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -455,10 +457,10 @@ jobs:
           PY
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Login to GHCR
-        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -475,8 +477,11 @@ jobs:
           push: true
           build-args: |
             CPR_PREBUILT_DIR=dist/docker
-          cache-from: type=gha,scope=runtime-prebuilt-${{ matrix.os }}-${{ matrix.arch }}
-          cache-to: type=gha,mode=max,scope=runtime-prebuilt-${{ matrix.os }}-${{ matrix.arch }}
+          no-cache-filters: |
+            runtime-base
+            runtime-prebuilt
+          cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache-${{ matrix.os }}-${{ matrix.arch }}
+          cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache-${{ matrix.os }}-${{ matrix.arch }},mode=min
           provenance: mode=max
           sbom: true
           labels: |
@@ -501,7 +506,7 @@ jobs:
           exit-code: '1'
 
   publish:
-    needs: [release-info, package-assets, build-docker-image]
+    needs: [release-info, package-assets, build-docker-image, container]
     runs-on: ubuntu-latest
     timeout-minutes: 20
     permissions:
@@ -512,7 +517,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -523,13 +528,13 @@ jobs:
           path: dist/release
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Install Cosign
         uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
 
       - name: Login to GHCR
-        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -539,7 +544,7 @@ jobs:
         id: manifest
         shell: bash
         env:
-          VERSION: ${{ needs.release-info.outputs.version }}
+          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
           GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
           DOCKER_PLATFORMS: ${{ needs.release-info.outputs.docker_platforms }}
           PRERELEASE: ${{ needs.release-info.outputs.prerelease }}
@@ -562,7 +567,7 @@ jobs:
           fi
 
           target_args=(
-            -t "${image}:${VERSION}"
+            -t "${image}:${DOCKER_VERSION}"
             -t "${image}:sha-${GIT_SHA}"
           )
           if [ "$PRERELEASE" != true ]; then
@@ -570,7 +575,7 @@ jobs:
           fi
           docker buildx imagetools create "${target_args[@]}" "${sources[@]}"
 
-          inspect_output="$(docker buildx imagetools inspect "${image}:${VERSION}")"
+          inspect_output="$(docker buildx imagetools inspect "${image}:${DOCKER_VERSION}")"
           platform_list="$(awk '$1 == "Platform:" { print $2 }' <<< "${inspect_output}")"
           for platform in "${platforms[@]}"; do
             if ! grep -Eq "^${platform}(/|$)" <<< "${platform_list}"; then
@@ -580,7 +585,7 @@ jobs:
             fi
           done
 
-          digest="$(docker buildx imagetools inspect "${image}:${VERSION}" --format '{{ .Manifest.Digest }}')"
+          digest="$(docker buildx imagetools inspect "${image}:${DOCKER_VERSION}" --format '{{ .Manifest.Digest }}')"
           if [ -z "${digest}" ]; then
             echo "missing image digest"
             exit 1
@@ -588,7 +593,7 @@ jobs:
           echo "digest=${digest}" >> "$GITHUB_OUTPUT"
 
       - name: Generate container provenance attestation
-        uses: actions/attest@a1948c3f048ba23858d222213b7c278aabede763 # v4.1.1
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           subject-digest: ${{ steps.manifest.outputs.digest }}
@@ -598,7 +603,7 @@ jobs:
         shell: bash
         env:
           DIGEST: ${{ steps.manifest.outputs.digest }}
-          VERSION: ${{ needs.release-info.outputs.version }}
+          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
           GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
           PRERELEASE: ${{ needs.release-info.outputs.prerelease }}
         run: |
@@ -609,7 +614,7 @@ jobs:
           fi
 
           image="${REGISTRY}/${IMAGE_NAME}"
-          tags=("${image}:${VERSION}" "${image}:sha-${GIT_SHA}")
+          tags=("${image}:${DOCKER_VERSION}" "${image}:sha-${GIT_SHA}")
           if [ "$PRERELEASE" != true ]; then
             tags+=("${image}:latest")
           fi
@@ -621,7 +626,7 @@ jobs:
           cosign sign --yes "${images[@]}"
 
       - name: Publish GitHub Release
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           tag_name: ${{ needs.release-info.outputs.tag }}
           generate_release_notes: true
@@ -629,12 +634,15 @@ jobs:
           prerelease: ${{ needs.release-info.outputs.prerelease == 'true' }}
           make_latest: ${{ needs.release-info.outputs.prerelease == 'true' && 'false' || 'true' }}
           body: |
+            > [!WARNING]
+            > **Upgrading across major versions?** Online upgrades across major versions are not supported. Deploy the new major fresh with a new `.runtime/` data directory, then re-import or re-authorize provider accounts and client keys. See the [upgrade notes](https://github.com/${{ github.repository }}/blob/main/deploy/README.md#镜像升级与源码构建).
+
             ## 📥 Installation
 
             **Docker:**
             ```bash
             # GitHub Container Registry
-            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.release-info.outputs.version }}
+            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.release-info.outputs.docker_version }}
             ```
 
             **Manual download:**

.github/workflows/security-scan.yml

@@ -3,8 +3,10 @@ name: Security Scan
 on:
   push:
     branches:
-      - '**'
+      - main
   pull_request:
+    branches:
+      - main
   schedule:
     - cron: '0 3 * * 1'
 
@@ -21,7 +23,7 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
@@ -29,7 +31,7 @@ jobs:
         uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
 
       - name: Cache Rust
-        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
         with:
           workspaces: backend -> target
 
@@ -45,17 +47,17 @@ jobs:
     timeout-minutes: 15
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
         with:
           version: 11.7.0
 
       - name: Setup Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
           cache: pnpm

.gitignore

@@ -1,5 +1,5 @@
 # Rust
-/backend/target/
+/backend/**/target/
 *.profraw
 *.profdata
 
@@ -19,13 +19,7 @@
 *.log
 
 # Local configuration and secrets
-.env
-.env.*
-!.env.example
-!**/.env.example
-/.envrc
-/config.yaml
-/backend/config.yaml
+/deploy/config.yaml
 
 # Editors and operating systems
 /.idea/
@@ -41,6 +35,7 @@ Thumbs.db
 /.codex-ws-audit/
 /.agents/
 /.reasonix/
+/.claude
 /.worktrees/
 /worktrees/
 /.cargo/

README.md

@@ -1,226 +1,165 @@
+<!-- prettier-ignore -->
 <div align="center">
-  <h1>Codex Proxy RS</h1>
-  <p>OpenAI Responses 兼容的 Codex 多账号网关</p>
-  <p>
-    <a href="https://www.rust-lang.org/"><img alt="Rust 1.97" src="https://img.shields.io/badge/Rust-1.97-000?style=flat-square&amp;logo=rust" /></a>
-    <a href="https://github.com/tokio-rs/axum"><img alt="Axum 0.8" src="https://img.shields.io/badge/Axum-0.8-2f7d95?style=flat-square" /></a>
-    <a href="https://vuejs.org/"><img alt="Vue 3.5" src="https://img.shields.io/badge/Vue-3.5-42b883?style=flat-square&amp;logo=vuedotjs&amp;logoColor=white" /></a>
-    <a href="https://vite.dev/"><img alt="Vite 8" src="https://img.shields.io/badge/Vite-8-646cff?style=flat-square&amp;logo=vite&amp;logoColor=white" /></a>
-    <a href="https://www.postgresql.org/"><img alt="PostgreSQL 18" src="https://img.shields.io/badge/PostgreSQL-18-4169e1?style=flat-square&amp;logo=postgresql&amp;logoColor=white" /></a>
-    <a href="https://redis.io/"><img alt="Redis 8" src="https://img.shields.io/badge/Redis-8-ff4438?style=flat-square&amp;logo=redis&amp;logoColor=white" /></a>
-    <a href="https://opensource.org/license/mit"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" /></a>
-  </p>
-  <p>
-    <a href="#快速部署">快速部署</a>
-    ·
-    <a href="#客户端接入">客户端接入</a>
-    ·
-    <a href="docs/architecture.md">架构说明</a>
-  </p>
-</div>
 
-Codex Proxy RS 为多个 Codex 账号提供统一的 Responses API。客户端使用同一个服务地址和 API Key；账号调度、并发限制、额度检查、故障换号和会话续接都在服务端完成。
+<img src="frontend/public/favicon.svg" alt="Codex Proxy RS" width="80" height="80" />
+
+# Codex Proxy RS
+
+集中管理 OpenAI、xAI 账号，为 Codex 和兼容客户端提供统一的访问地址与密钥。
+
+[![CI](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/zyycn/codex-proxy-rs?display_name=tag&sort=semver&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/releases)
+[![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
+[![MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/license/mit)
+
+[快速开始](#快速开始) · [客户端接入](#客户端接入) · [常见问题](#常见问题) · [部署说明](deploy/README.md)
+
+</div>
 
 ## 功能
 
-- 兼容 `/v1/responses`、SSE、官方 Responses WebSocket 和模型查询。
-- 客户端与上游均可使用 HTTP/SSE 或 WebSocket。
-- 提供 `smart`、额度重置优先、轮询和粘性四种账号调度策略。
-- 单个账号发生额度、认证、模型或传输故障时，继续使用账号池中的其他可用账号。
-- 支持跨账号会话续接，并隔离不同账号的会话状态。
-- 提供账号、API Key、模型映射、运行参数、用量、错误记录和系统更新管理界面。
-- 使用 PostgreSQL 保存权威业务数据，使用 Redis 保存管理会话、租约、模型快照和响应归属。
-- 内置日志轮转、遥测保留期清理和 PostgreSQL/Redis 健康检查。
+- 在网页中添加账号，查看额度、请求记录和费用，刷新或重新授权过期账号。
+- 用账号分组控制不同密钥可使用的账号，设置并发和请求频率。
+- 接入 Codex CLI、桌面端和支持 Responses API 的客户端。
+- 支持流式对话、WebSocket、图片生成与编辑、Codex 独立搜索。
+- 支持 S3/R2 数据库备份、同大版本在线更新和回滚。
 
-除账号调度和会话恢复外，请求与响应尽量保持原有语义。
+支持 OpenAI、xAI 账号，但图片与独立搜索目前仅通过 OpenAI 提供。模型和功能是否可用取决于上游账号权限。
+**不支持 `/v1/chat/completions`**；仅支持该接口的客户端不能直接接入。
 
-## 快速部署
+## 快速开始
 
-需要 Docker Engine 和 Docker Compose Plugin。下面的 Compose 默认使用：
+使用 Docker Compose 部署发布镜像 `ghcr.io/zyycn/codex-proxy-rs:latest`，同时启动 PostgreSQL 和 Redis。
+以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。已有部署请先看
+[升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置。
 
-- 应用镜像：`ghcr.io/zyycn/codex-proxy-rs:latest`
-- PostgreSQL 18
-- Redis 8
-- 管理端地址：`http://127.0.0.1:8080`
-
-### 1. 获取项目
+### 1. 下载部署文件并配置
 
 ```bash
-git clone https://github.com/zyycn/codex-proxy-rs.git
+mkdir -p codex-proxy-rs/deploy
 cd codex-proxy-rs
-```
 
-### 2. 创建配置
+curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/compose.yaml \
+  -o deploy/compose.yaml
+curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/config.example.yaml \
+  -o deploy/config.example.yaml
 
-```bash
 mkdir -p .runtime/data .runtime/logs
-cp deploy/config.example.yaml .runtime/config.yaml
-cp deploy/.env.example deploy/.env
-chmod 0600 deploy/.env
-```
-
-编辑 `deploy/.env`：
-
-```dotenv
-CPR_ADMIN_DEFAULT_PASSWORD='<管理员密码，至少 12 个字符>'
-CPR_POSTGRES_PASSWORD='<PostgreSQL 密码>'
-CPR_REDIS_PASSWORD='<Redis 密码>'
-```
-
-`deploy/.env` 已被 Git 忽略。应用会安全地把 PostgreSQL 和 Redis 密码写入运行时连接 URL，不需要把真实密码填入 `.runtime/config.yaml`。
-
-Linux 宿主机需要保证容器用户 `10001:10001` 可以读写数据和日志目录：
-
-```bash
+install -d -m 0750 .runtime/postgres .runtime/redis
+cp deploy/config.example.yaml deploy/config.yaml
+sudo chown "$(id -u):10001" deploy/config.yaml
+chmod 0640 deploy/config.yaml
 sudo chown -R "$(id -u):10001" .runtime/data .runtime/logs
 chmod 0770 .runtime/data .runtime/logs
-sudo chown "$(id -u):10001" .runtime/config.yaml
-chmod 0640 .runtime/config.yaml
 ```
 
-### 3. 启动
+分别生成数据库和 Redis 密码：
 
 ```bash
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml config
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml pull
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d --no-build
+openssl rand -hex 24
+openssl rand -hex 24
 ```
 
-检查服务：
+编辑 `deploy/config.yaml`，填好以下三项：
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| `store.database.password` | 第一个生成的 48 位十六进制密码 |
+| `store.redis.password` | 第二个生成的 48 位十六进制密码 |
+| `admin.default_password` | 管理员初始密码，至少 12 位，不能包含 `$` |
+
+不需要创建 `.env`。管理员初始密码只在首次创建账号时使用。
+
+### 2. 启动服务
 
 ```bash
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml ps
+docker compose -f deploy/compose.yaml config --quiet
+docker compose -f deploy/compose.yaml pull
+docker compose -f deploy/compose.yaml up -d --no-build --wait
 curl -i http://127.0.0.1:8080/healthz
 ```
 
-`/healthz` 正常时返回 `204 No Content`。随后打开 <http://127.0.0.1:8080>：
+健康检查返回 `204 No Content` 后，打开 `http://127.0.0.1:8080`，
+使用 `admin@cpr.local` 和刚设置的管理员密码登录。
 
-- 用户名：`admin@cpr.local`
-- 密码：`deploy/.env` 中的 `CPR_ADMIN_DEFAULT_PASSWORD`
+默认地址只能在服务器本机访问。从其他设备使用时，需要配置
+[HTTPS 反向代理](deploy/README.md#公网访问)。
 
-首次登录后导入账号，在“API 密钥”页面创建客户端 Key。
+### 3. 添加账号和密钥
 
-### 本地构建镜像
+1. 在「账号」中添加 OpenAI 或 xAI 账号。OpenAI 支持 OAuth 授权、AT/RT 和账号 JSON；xAI 支持 OAuth 授权和账号 JSON。
+2. 按需创建账号分组，并把账号加入分组。
+3. 创建客户端密钥，选择可用分组。**不选分组表示可使用全部账号**。
+4. 点击该密钥的「使用密钥」，复制客户端配置。
 
-需要验证当前源码时，不拉取 GHCR 镜像，直接构建：
-
-```bash
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml build codex-proxy-rs
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d
-```
+只导入 AT 的账号不能自动续期。xAI 暂不支持用 API Key 导入上游账号。
 
 ## 客户端接入
 
-OpenAI 兼容客户端填写：
+### Codex CLI 和桌面端
 
-- Base URL：`http://127.0.0.1:8080/v1`
-- API Key：管理端创建的 `sk_...` 客户端 Key
+在「使用密钥」中按系统复制 `config.toml` 和 `auth.json`，也可以通过 CCSwitch 导入。
+已有文件先备份，再合并配置并重启 Codex。客户端使用代理密钥，OpenAI 账号登录状态由服务端管理。
 
-Responses 请求示例：
+新配置已启用原生生图。可以直接提出需求，例如：
+
+> 帮我做一个咖啡店首页，生成一张咖啡主题配图并用到页面中。
+
+是否调用生图由 Codex 根据任务决定，也可以明确要求生成图片。需要支持生图的客户端、模型和 OpenAI 账号；
+普通对话可用不代表账号一定有生图额度。
+
+完整配置和旧版配置迁移见 [客户端配置](deploy/README.md#客户端配置)。
+
+### 其他客户端
+
+选择支持 **Responses API** 的客户端，填写：
+
+| 配置 | 值 |
+| --- | --- |
+| Base URL | `http://127.0.0.1:8080/v1`，远程使用时换成服务器的 HTTPS 地址 |
+| API Key | 管理端创建的 `sk_...` 密钥 |
+
+可先检查密钥是否能读取模型列表：
 
 ```bash
-curl http://127.0.0.1:8080/v1/responses \
-  -H 'Authorization: Bearer <client-api-key>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "model": "<model-id>",
-    "input": "Reply with pong.",
-    "stream": false
-  }'
+curl http://127.0.0.1:8080/v1/models \
+  -H 'Authorization: Bearer <client-api-key>'
 ```
 
-可用接口：
+接口列表与请求示例见 [接口文档](docs/api.md)。
 
-| 路由 | 说明 |
-| --- | --- |
-| `POST /v1/responses` | Responses 非流式或 SSE 流式请求 |
-| `GET /v1/responses` | 官方 Responses WebSocket |
-| `POST /v1/responses/review` | Review 请求 |
-| `GET /v1/models` | 模型列表 |
-| `GET /v1/models/catalog` | 模型目录 |
-| `GET /v1/models/{model_id}` | 模型详情 |
-| `GET /v1/models/{model_id}/info` | 模型运行信息 |
+## 常见问题
 
-Compose 默认只监听宿主机 `127.0.0.1`。需要从其他设备访问时，应在前面配置 HTTPS 反向代理，不要直接暴露 PostgreSQL 和 Redis 端口。
+### 仍然要求登录，或无法生成图片
 
-## 管理端
+重新从管理端复制配置，确认修改的是客户端实际读取的用户配置目录，然后完全退出并重启客户端。
+保留仅含代理密钥的 `auth.json` 不会使新配置失效。详细检查步骤见
+[登录与生图排查](deploy/README.md#登录与生图排查)。
 
-管理端提供以下页面：
+### 没有可用账号或模型
 
-- Dashboard：请求趋势、服务状态、账号概览和最近请求。
-- 账号：导入、导出、OAuth、连接测试、quota 和 token 刷新。
-- API 密钥：创建、停用、删除和客户端接入信息。
-- 用量：请求记录、token、延迟、模型分布和运维错误。
-- 设置：模型别名、账号调度策略、单账号并发、请求间隔和刷新参数。
-- 系统：版本检查、更新、重启和回滚。
+检查账号是否启用、凭据是否过期、额度是否耗尽，以及密钥绑定的分组是否包含可用账号。
+「恢复账号」只清除本地错误状态，不能恢复上游权限或增加额度。
 
-管理端登录会话保存在 Redis，并按 `admin.session_ttl_minutes` 自动过期。
+### 如何更新或查看日志
 
-## 配置
-
-启动配置位于 `.runtime/config.yaml`，模板见 [deploy/config.example.yaml](deploy/config.example.yaml)。
-
-| 配置段 | 用途 |
-| --- | --- |
-| `server` | HTTP 监听地址和端口 |
-| `api` | Codex 上游地址 |
-| `database`、`redis` | PostgreSQL 与 Redis 连接 |
-| `quota` | quota 刷新周期和耗尽账号过滤 |
-| `tls` | 上游 HTTP 协议偏好 |
-| `ws_pool` | WebSocket 连接池与首事件超时 |
-| `fingerprint` | Codex Desktop 请求指纹 |
-| `admin` | 默认管理员和登录会话 TTL |
-| `logging` | 日志级别、目录、大小和保留期 |
-| `telemetry` | 请求事实记录开关 |
-
-模型别名、调度策略、单账号并发、请求间隔和刷新参数由管理端保存到 PostgreSQL，可在运行中更新。请求事实、运维错误和聚合时间桶由后台任务按各自保留期自动清理。
-
-## 数据与升级
-
-| 数据 | 默认位置 |
-| --- | --- |
-| 账号、API Key、设置、用量和错误记录 | Compose 命名卷 `postgres-data` |
-| 管理会话、租约、模型快照和响应归属 | Compose 命名卷 `redis-data` |
-| 身份派生密钥和更新状态 | `.runtime/data` |
-| 文件日志 | `.runtime/logs` |
-| 启动配置 | `.runtime/config.yaml` |
-| Docker 密钥 | `deploy/.env` |
-
-普通升级只替换应用镜像：
+同一大版本内拉取发布镜像并重建应用容器：
 
 ```bash
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml pull codex-proxy-rs
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d --no-build
+docker compose -f deploy/compose.yaml pull codex-proxy-rs
+docker compose -f deploy/compose.yaml up -d --no-build codex-proxy-rs
+docker compose -f deploy/compose.yaml logs --tail=100 -f codex-proxy-rs
 ```
 
-更新镜像不会删除数据库卷，但仍应在升级前备份 PostgreSQL 和 `.runtime/data`。
+> [!WARNING]
+> 升级前先备份。跨大版本需使用新的数据目录重新部署，不支持直接沿用旧库在线升级。
+> `.runtime/` 包含数据库和运行数据，请勿删除；账号文件、密钥和日志也不要公开分享。
 
-不要使用 `docker compose down -v` 做普通升级，该命令会删除 PostgreSQL 与 Redis 命名卷。
+## 文档
 
-`.runtime/data/identity_hmac_secret` 必须长期保留。丢失该文件会改变全部账号的 installation ID 和账号作用域身份。
-
-## 查看状态
-
-```bash
-# 容器状态
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml ps
-
-# 应用日志
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml logs -f codex-proxy-rs
-
-# PostgreSQL 和 Redis 日志
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml logs postgres redis
-
-# 展开并检查最终 Compose 配置
-docker compose --env-file deploy/.env -f deploy/docker-compose.yml config
-```
-
-`/healthz` 返回 `503` 时，先检查 PostgreSQL 和 Redis 的健康状态。容器反复重启时，再检查 `.runtime/config.yaml`、`deploy/.env` 和 `.runtime/data`、`.runtime/logs` 的权限。
-
-## 架构
-
-模块边界、请求链路、存储归属和后台任务见 [架构说明](docs/architecture.md)。
-
-## License
-
-MIT
+- [客户端接入与生图](deploy/README.md#客户端配置)
+- [部署、备份与恢复](deploy/README.md)
+- [API 参考](docs/api.md)
+- [系统架构](docs/architecture.md)
+- [管理端主题](docs/theme.md)
+- [数据库迁移](backend/migrations/README.md)

backend/Cargo.toml

@@ -1,73 +1,29 @@
-[package]
-name = "codex-proxy-rs"
+[workspace]
+members = [
+    "apps/gateway",
+    "crates/gateway-admin",
+    "crates/gateway-api",
+    "crates/gateway-core",
+    "crates/gateway-host",
+    "crates/gateway-protocol",
+    "crates/gateway-store",
+    "crates/providers/openai",
+    "crates/providers/xai",
+]
+resolver = "3"
+
+[workspace.package]
+version = "0.0.0"
 edition = "2024"
 license = "MIT"
 publish = false
 rust-version = "1.97"
 
-[dependencies]
-argon2 = "0.5.3"
-async-trait = "0.1.89"
-axum = { version = "0.8.9", default-features = false, features = ["http1", "json", "query", "tokio", "tracing"] }
-base64 = "0.22.1"
-bytes = "1.11.1"
-chrono = { version = "0.4.45", features = ["serde", "clock"] }
-config = { version = "0.15.23", default-features = false, features = ["yaml"] }
-dirs = "6.0.0"
-flate2 = "1.1.9"
-futures = "0.3.32"
-hex = "0.4.3"
-hmac = "0.13.0"
-hyper = { version = "1.10.1", features = ["http1", "server"] }
-hyper-util = { version = "0.1.20", features = ["tokio"] }
-indexmap = { version = "2.0", features = ["serde"] }
-ipnet = "2.12.0"
-percent-encoding = "2.3.2"
-rand = "0.10.1"
-# Enables password_hash::rand_core::OsRng for argon2 0.5.
-rand_core = { version = "0.6.4", features = ["getrandom"] }
-redis = { version = "1.3.0", default-features = false, features = ["tokio-comp", "connection-manager", "script"] }
-# Pinned to the Codex Desktop 26.707.41301 HTTP stack; re-audit a newer Desktop before upgrading.
-reqwest = { version = "=0.12.28", default-features = false, features = ["json", "stream", "cookies", "rustls-tls-native-roots", "gzip", "brotli", "zstd", "deflate", "http2"] }
-rustls = { version = "=0.23.36", default-features = false, features = ["ring", "std", "tls12"] }
-rustls-native-certs = "0.8.4"
-rustls-pki-types = "1.14.1"
-secrecy = "0.10.3"
-semver = "1.0.27"
-serde = { version = "1.0.228", features = ["derive"] }
-serde_json = { version = "1.0.150", features = ["preserve_order"] }
-sha2 = "0.11.0"
-sqlx = { version = "0.9.0", default-features = false, features = ["runtime-tokio", "tls-rustls", "postgres", "chrono", "json"] }
-subtle = "2.6.1"
-tar = "0.4.44"
-thiserror = "2.0.18"
-tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt-multi-thread", "signal", "fs", "time", "sync", "net"] }
-tokio-util = { version = "0.7.18", features = ["rt"] }
-tokio-tungstenite = { version = "0.28.0", features = ["proxy", "rustls-tls-native-roots"] }
-tower = { version = "0.5.3", features = ["util"] }
-tower-http = { version = "0.6.11", features = ["trace", "cors", "request-id", "timeout", "fs"] }
-tracing = "0.1.44"
-tracing-appender = "0.2.5"
-tracing-subscriber = { version = "0.3.23", features = ["env-filter", "json"] }
-tungstenite = { version = "0.27.0", features = ["deflate", "proxy"] }
-url = "2.5.8"
-uuid = { version = "1.23.3", features = ["v4", "v7", "serde"] }
-
-[dev-dependencies]
-sqlx = { version = "0.9.0", default-features = false, features = ["derive"] }
-tempfile = "3.27.0"
-tokio = { version = "1.52.3", default-features = false, features = ["test-util"] }
-wiremock = "0.6.5"
-
-[patch.crates-io]
-tokio-tungstenite = { git = "https://github.com/openai-oss-forks/tokio-tungstenite", rev = "0e5b2d73aa18dd9f0a50ee9ff199d5aef7594186" }
-tungstenite = { git = "https://github.com/openai-oss-forks/tungstenite-rs", rev = "4fffad30fe373adbdcffab9545e9e9bf4f2fc19f" }
-
-[lints.rust]
+[workspace.lints.rust]
 warnings = "deny"
 unsafe_code = "forbid"
 
-[lints.clippy]
+[workspace.lints.clippy]
 all = { level = "deny", priority = 10 }
 redundant_clone = { level = "deny", priority = 9 }
 large_enum_variant = { level = "warn", priority = 8 }

backend/apps/gateway/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "codex-proxy-rs"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+rust-version.workspace = true
+autotests = false
+
+[[test]]
+name = "main"
+path = "tests/main.rs"
+
+[dependencies]
+gateway-admin = { path = "../../crates/gateway-admin" }
+gateway-api = { path = "../../crates/gateway-api" }
+gateway-core = { path = "../../crates/gateway-core" }
+gateway-host = { path = "../../crates/gateway-host" }
+gateway-store = { path = "../../crates/gateway-store" }
+provider-openai = { path = "../../crates/providers/openai" }
+provider-xai = { path = "../../crates/providers/xai" }
+serde = { version = "1.0.228", features = ["derive"] }
+thiserror = "2.0.18"
+tokio = { version = "1.52.3", default-features = false, features = ["rt-multi-thread"] }
+
+[dev-dependencies]
+config = { version = "0.15.23", default-features = false, features = ["yaml"] }
+serde_json = "1"
+syn = { version = "3.0.3", features = ["full", "visit"] }
+tempfile = "3.27.0"
+
+[lints]
+workspace = true

backend/apps/gateway/src/bootstrap.rs

@@ -0,0 +1,132 @@
+//! 网关唯一组合根：加载包级配置并连接各 Bundle。
+
+use gateway_core::engine::provider::{ProviderRegistry, RegistryError};
+use gateway_host::{ConfigError, HostConfig, LoadableConfig};
+use serde::Deserialize;
+
+const CONFIG_SCHEMA_VERSION: u32 = 1;
+
+/// 顶层配置只组合各包拥有的配置段，不解释任何业务字段。
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct GatewayConfig {
+    schema_version: u32,
+    host: HostConfig,
+    store: gateway_store::StoreConfig,
+    admin: gateway_admin::AdminConfig,
+    api: gateway_api::ApiConfig,
+    openai: provider_openai::OpenAiConfig,
+    xai: provider_xai::XaiConfig,
+    #[serde(default, rename = "services")]
+    _compose_services: Option<serde::de::IgnoredAny>,
+}
+
+impl LoadableConfig for GatewayConfig {
+    fn resolve_and_validate(&mut self, source_dir: &std::path::Path) -> Result<(), ConfigError> {
+        if self.schema_version != CONFIG_SCHEMA_VERSION {
+            return Err(ConfigError::InvalidField("schema_version"));
+        }
+        self.host.resolve_and_validate(source_dir)?;
+        let runtime_data_dir = self.host.runtime_data_dir().to_path_buf();
+        self.store
+            .resolve_and_validate(&runtime_data_dir)
+            .map_err(|_| ConfigError::InvalidField("store"))?;
+        self.admin
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("admin"))?;
+        self.api
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("api"))?;
+        self.openai
+            .resolve_and_validate(&runtime_data_dir)
+            .map_err(|_| ConfigError::InvalidField("openai"))?;
+        self.xai
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("xai"))?;
+        Ok(())
+    }
+}
+
+/// 按冻结顺序初始化全部 Bundle，并把进程阻塞权交给 Host。
+pub async fn run() -> Result<(), BootstrapError> {
+    let config = gateway_host::load_config::<GatewayConfig>()?;
+    let GatewayConfig {
+        schema_version: _,
+        host,
+        store,
+        admin,
+        api,
+        openai,
+        xai,
+        _compose_services: _,
+    } = config;
+
+    let host = gateway_host::initialize(host).await?;
+    host.report_startup_ready("Host");
+    let mut store = gateway_store::initialize(store).await?;
+    host.report_startup_ready("Store");
+    let provider_ports = store.provider_ports();
+    let mut openai = provider_openai::initialize(openai, provider_ports.clone()).await?;
+    host.report_startup_ready("OpenAI Provider");
+    let mut xai = provider_xai::initialize(xai, provider_ports).await?;
+    host.report_startup_ready("xAI Provider");
+    let providers = ProviderRegistry::new([openai.core_provider(), xai.core_provider()])?;
+    let mut core = gateway_core::initialize(store.core_ports(), providers).await?;
+    host.report_startup_ready("Core");
+    let mut admin = gateway_admin::initialize(
+        admin,
+        store.admin_ports(),
+        vec![openai.admin_provider(), xai.admin_provider()],
+        core.snapshot_control(),
+        core.account_probe(),
+        host.client_distribution_resolver(),
+        host.system_operations(),
+    )
+    .await?;
+    host.report_startup_ready("Admin");
+
+    let mut probes = store.health_probes();
+    probes.extend(core.health_probes());
+    let api = gateway_api::initialize(
+        api,
+        core.execution_service(),
+        admin.services(),
+        probes,
+        host.worker_health(),
+        host.connection_lifecycle(),
+    )?;
+    host.report_startup_ready("API");
+
+    let mut plan = store.take_worker_contributions();
+    plan.extend(core.take_worker_contributions());
+    plan.extend(openai.take_worker_contributions());
+    plan.extend(xai.take_worker_contributions());
+    plan.extend(admin.take_worker_contributions());
+    host.start_workers(plan, store.worker_leader_lease())?;
+    host.report_startup_ready("Workers");
+    host.serve(api.router()).await?;
+    Ok(())
+}
+
+/// 组合根只保留包级错误分类，不展开内部实现或敏感配置。
+#[derive(Debug, thiserror::Error)]
+pub enum BootstrapError {
+    #[error(transparent)]
+    Config(#[from] gateway_host::ConfigError),
+    #[error(transparent)]
+    Host(#[from] gateway_host::HostError),
+    #[error(transparent)]
+    Store(#[from] gateway_store::StoreError),
+    #[error(transparent)]
+    OpenAi(#[from] provider_openai::OpenAiInitializeError),
+    #[error(transparent)]
+    Xai(#[from] provider_xai::XaiInitializeError),
+    #[error(transparent)]
+    Registry(#[from] RegistryError),
+    #[error(transparent)]
+    Core(#[from] gateway_core::CoreError),
+    #[error(transparent)]
+    Admin(#[from] gateway_admin::model::AdminError),
+    #[error(transparent)]
+    Api(#[from] gateway_api::ApiError),
+}

backend/apps/gateway/src/lib.rs

@@ -0,0 +1,3 @@
+//! 网关进程组装根。
+
+pub mod bootstrap;

backend/apps/gateway/src/main.rs

@@ -0,0 +1,35 @@
+use std::{env, error::Error, io};
+
+use provider_openai::ensure_rustls_provider;
+
+fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
+    ensure_rustls_provider();
+    let mut arguments = env::args_os().skip(1);
+    match arguments.next().as_deref().and_then(|value| value.to_str()) {
+        None | Some("serve") => {
+            reject_extra_arguments(arguments)?;
+            runtime()?.block_on(codex_proxy_rs::bootstrap::run())?;
+            Ok(())
+        }
+        Some(command) => {
+            Err(invalid_cli(&format!("unknown command {command:?}; expected serve")).into())
+        }
+    }
+}
+
+fn runtime() -> Result<tokio::runtime::Runtime, io::Error> {
+    tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()
+}
+
+fn reject_extra_arguments(mut arguments: impl Iterator) -> Result<(), io::Error> {
+    if arguments.next().is_some() {
+        return Err(invalid_cli("unexpected extra command arguments"));
+    }
+    Ok(())
+}
+
+fn invalid_cli(message: &str) -> io::Error {
+    io::Error::new(io::ErrorKind::InvalidInput, message)
+}

backend/apps/gateway/tests/architecture.rs

@@ -0,0 +1,584 @@
+//! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验。
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fs,
+    path::{Path, PathBuf},
+};
+
+use syn::{Item, visit::Visit};
+
+/// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则。
+pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
+    "apps/gateway",
+    "crates/gateway-admin",
+    "crates/gateway-api",
+    "crates/gateway-core",
+    "crates/gateway-host",
+    "crates/gateway-protocol",
+    "crates/gateway-store",
+    "crates/providers/openai",
+    "crates/providers/xai",
+];
+
+#[test]
+fn workspace_member_list_matches_the_frozen_dag_scope() {
+    let manifest =
+        fs::read_to_string(backend_root().join("Cargo.toml")).expect("read workspace manifest");
+    for member in WORKSPACE_MEMBERS {
+        assert!(
+            manifest.contains(&format!("\"{member}\"")),
+            "workspace must include {member}"
+        );
+    }
+    let member_count = manifest
+        .lines()
+        .map(str::trim)
+        .filter(|line| line.starts_with("\"apps/") || line.starts_with("\"crates/"))
+        .count();
+    assert_eq!(
+        member_count,
+        WORKSPACE_MEMBERS.len(),
+        "new workspace members must extend the dependency DAG rules"
+    );
+}
+
+#[test]
+fn gateway_core_depends_on_no_http_db_redis_or_provider_crate() {
+    assert_no_dependency(
+        "crates/gateway-core",
+        &[
+            "axum",
+            "hyper",
+            "reqwest",
+            "sqlx",
+            "redis",
+            "gateway-host",
+            "gateway-store",
+            "provider-openai",
+            "provider-xai",
+        ],
+    );
+}
+
+#[test]
+fn core_value_owners_do_not_depend_on_execution_or_routing() {
+    let root = backend_root().join("crates/gateway-core/src");
+    for relative in super::rust_files(&root) {
+        let allowed: Option<&[&str]> = match relative.to_str().expect("source path") {
+            "validation.rs" => Some(&[]),
+            "identity.rs" => Some(&["validation"]),
+            "upstream.rs" => Some(&["validation"]),
+            "event.rs" => Some(&["metering", "operation", "upstream", "validation"]),
+            "account/store.rs" => Some(&["account", "error", "identity", "validation"]),
+            path if path.starts_with("policy/") => Some(&["account", "policy", "validation"]),
+            path if path.starts_with("account/") => Some(&["account", "identity", "validation"]),
+            _ => None,
+        };
+        let Some(allowed) = allowed else { continue };
+        let source = fs::read_to_string(root.join(&relative)).expect("read core source");
+        let syntax = syn::parse_file(&source).expect("parse core source");
+        let mut references = CrateReferences::default();
+        references.visit_file(&syntax);
+        for dependency in references.0 {
+            assert!(
+                allowed.contains(&dependency.as_str()),
+                "{} must not depend on crate::{dependency}",
+                relative.display()
+            );
+        }
+    }
+}
+
+#[derive(Default)]
+struct CrateReferences(BTreeSet<String>);
+
+impl<'ast> Visit<'ast> for CrateReferences {
+    fn visit_path(&mut self, path: &'ast syn::Path) {
+        let mut segments = path.segments.iter();
+        if segments
+            .next()
+            .is_some_and(|segment| segment.ident == "crate")
+            && let Some(owner) = segments.next()
+        {
+            self.0.insert(owner.ident.to_string());
+        }
+        syn::visit::visit_path(self, path);
+    }
+
+    fn visit_item_use(&mut self, item: &'ast syn::ItemUse) {
+        self.use_tree(&item.tree, false);
+    }
+}
+
+impl CrateReferences {
+    fn use_tree(&mut self, tree: &syn::UseTree, crate_root: bool) {
+        match tree {
+            syn::UseTree::Path(path) if crate_root => {
+                self.0.insert(path.ident.to_string());
+            }
+            syn::UseTree::Name(name) if crate_root => {
+                self.0.insert(name.ident.to_string());
+            }
+            syn::UseTree::Rename(rename) if crate_root => {
+                self.0.insert(rename.ident.to_string());
+            }
+            syn::UseTree::Path(path) => self.use_tree(&path.tree, path.ident == "crate"),
+            syn::UseTree::Group(group) => {
+                for item in &group.items {
+                    self.use_tree(item, crate_root);
+                }
+            }
+            syn::UseTree::Glob(_) if crate_root => {
+                self.0.insert("*".to_owned());
+            }
+            _ => {}
+        }
+    }
+}
+
+#[test]
+fn gateway_protocol_has_no_workspace_dependencies() {
+    for name in dependency_names("crates/gateway-protocol") {
+        assert!(
+            !name.starts_with("gateway-") && !name.starts_with("provider-"),
+            "gateway-protocol must not depend on workspace crate `{name}`"
+        );
+    }
+}
+
+#[test]
+fn provider_crates_do_not_depend_on_each_other() {
+    assert_no_dependency("crates/providers/openai", &["provider-xai"]);
+    assert_no_dependency("crates/providers/xai", &["provider-openai"]);
+}
+
+#[test]
+fn gateway_admin_stays_free_of_infrastructure_dependencies() {
+    assert_no_dependency(
+        "crates/gateway-admin",
+        &["axum", "sqlx", "redis", "reqwest"],
+    );
+}
+
+/// workspace 包名到冻结成员路径的映射。
+const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
+    ("codex-proxy-rs", "apps/gateway"),
+    ("gateway-admin", "crates/gateway-admin"),
+    ("gateway-api", "crates/gateway-api"),
+    ("gateway-core", "crates/gateway-core"),
+    ("gateway-host", "crates/gateway-host"),
+    ("gateway-protocol", "crates/gateway-protocol"),
+    ("gateway-store", "crates/gateway-store"),
+    ("provider-openai", "crates/providers/openai"),
+    ("provider-xai", "crates/providers/xai"),
+];
+
+/// Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
+const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
+    ("crates/gateway-api", &["admin", "openai"]),
+    (
+        "crates/gateway-host",
+        &[
+            "client_distribution",
+            "config",
+            "serve",
+            "system_update",
+            "workers",
+        ],
+    ),
+    ("crates/gateway-store", &["backup", "postgres", "redis"]),
+    (
+        "crates/providers/openai",
+        &["config", "credential", "transport"],
+    ),
+    (
+        "crates/providers/xai",
+        &["config", "credential", "transport"],
+    ),
+];
+
+/// 不对应单一生产模块、而是校验 crate/workspace 整体契约的根级测试场景。
+const ROOT_TEST_SCENARIOS: &[(&str, &[&str])] = &[
+    ("apps/gateway", &["architecture"]),
+    ("crates/gateway-api", &["architecture"]),
+];
+
+/// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表。
+const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
+    ("codex-proxy-rs", "gateway-admin"),
+    ("codex-proxy-rs", "gateway-api"),
+    ("codex-proxy-rs", "gateway-core"),
+    ("codex-proxy-rs", "gateway-host"),
+    ("codex-proxy-rs", "gateway-store"),
+    ("codex-proxy-rs", "provider-openai"),
+    ("codex-proxy-rs", "provider-xai"),
+    ("gateway-admin", "gateway-core"),
+    ("gateway-api", "gateway-admin"),
+    ("gateway-api", "gateway-core"),
+    ("gateway-api", "gateway-protocol"),
+    ("gateway-host", "gateway-admin"),
+    ("gateway-host", "gateway-core"),
+    ("gateway-store", "gateway-admin"),
+    ("gateway-store", "gateway-core"),
+    ("provider-openai", "gateway-admin"),
+    ("provider-openai", "gateway-core"),
+    ("provider-openai", "gateway-protocol"),
+    ("provider-xai", "gateway-admin"),
+    ("provider-xai", "gateway-core"),
+    ("provider-xai", "gateway-protocol"),
+];
+
+#[test]
+fn workspace_internal_dependency_edges_match_frozen_dag() {
+    let metadata = cargo_metadata_json();
+    let actual = workspace_runtime_dependency_edges(&metadata);
+    let mut expected: Vec<(String, String)> = ALLOWED_INTERNAL_EDGES
+        .iter()
+        .map(|(from, to)| ((*from).to_owned(), (*to).to_owned()))
+        .collect();
+    expected.sort();
+
+    assert_eq!(
+        actual, expected,
+        "workspace internal dependency edges diverged from the frozen DAG"
+    );
+}
+
+#[test]
+fn runtime_dependency_edges_exclude_dev_build_and_external_dependencies() {
+    let metadata = serde_json::json!({
+        "packages": [
+            {
+                "name": "gateway-api",
+                "dependencies": [
+                    { "name": "gateway-core", "kind": null },
+                    { "name": "gateway-store", "kind": "dev" },
+                    { "name": "gateway-host", "kind": "build" },
+                    { "name": "serde", "kind": null }
+                ]
+            },
+            {
+                "name": "external-package",
+                "dependencies": [{ "name": "gateway-core", "kind": null }]
+            }
+        ]
+    });
+
+    assert_eq!(
+        workspace_runtime_dependency_edges(&metadata),
+        vec![("gateway-api".to_owned(), "gateway-core".to_owned())]
+    );
+}
+
+fn workspace_runtime_dependency_edges(metadata: &serde_json::Value) -> Vec<(String, String)> {
+    let packages = metadata["packages"]
+        .as_array()
+        .expect("cargo metadata packages");
+    let internal_names: std::collections::BTreeSet<&str> =
+        PACKAGE_TO_MEMBER.iter().map(|(name, _)| *name).collect();
+
+    let mut actual: Vec<(String, String)> = Vec::new();
+    for package in packages {
+        let name = package["name"].as_str().expect("package name");
+        if !internal_names.contains(name) {
+            continue;
+        }
+        for dependency in package["dependencies"].as_array().into_iter().flatten() {
+            let dep_name = dependency["name"].as_str().expect("dependency name");
+            if !internal_names.contains(dep_name) {
+                continue;
+            }
+            if dependency.get("kind").expect("dependency kind").is_null() {
+                actual.push((name.to_owned(), dep_name.to_owned()));
+            }
+        }
+    }
+
+    actual.sort();
+    actual
+}
+
+#[test]
+fn adapter_public_module_surfaces_match_allowlist() {
+    for (member, allowed) in ADAPTER_PUBLIC_MODULES {
+        let root = backend_root().join(member).join("src/lib.rs");
+        let source = fs::read_to_string(&root).expect("read adapter crate root");
+        let syntax = syn::parse_file(&source).expect("parse adapter crate root");
+        let actual = syntax
+            .items
+            .iter()
+            .filter_map(|item| match item {
+                Item::Mod(module) if matches!(module.vis, syn::Visibility::Public(_)) => {
+                    Some(module.ident.to_string())
+                }
+                _ => None,
+            })
+            .collect::<BTreeSet<_>>();
+        let expected = allowed
+            .iter()
+            .map(|module| (*module).to_owned())
+            .collect::<BTreeSet<_>>();
+        assert_eq!(
+            actual,
+            expected,
+            "{} public module surface diverged from its allowlist",
+            root.display()
+        );
+    }
+}
+
+#[test]
+fn production_sources_do_not_host_tests() {
+    for member in WORKSPACE_MEMBERS {
+        let src = backend_root().join(member).join("src");
+        let sources = super::rust_files(&src);
+        assert!(!sources.is_empty(), "{member} has no production sources");
+        for relative in sources {
+            let path = src.join(relative);
+            let source = fs::read_to_string(&path).expect("read production source");
+            assert!(
+                !source.contains("#[cfg(test)]"),
+                "{} hosts tests in production src",
+                path.display()
+            );
+        }
+    }
+}
+
+#[test]
+fn workspace_modules_follow_conventional_file_layout() {
+    for member in WORKSPACE_MEMBERS {
+        let member_root = backend_root().join(member);
+        assert_module_tree(&member_root.join("src"), &["lib.rs", "main.rs"]);
+
+        let tests = member_root.join("tests");
+        if tests.is_dir() {
+            assert_module_tree(&tests, &["main.rs"]);
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ModuleLayout {
+    File,
+    Directory,
+}
+
+#[test]
+fn integration_tests_mirror_production_module_tree() {
+    for member in WORKSPACE_MEMBERS {
+        let member_root = backend_root().join(member);
+        let tests_root = member_root.join("tests");
+        if !tests_root.is_dir() {
+            continue;
+        }
+
+        let production = module_layouts(&member_root.join("src"), &["lib.rs", "main.rs"]);
+        let tests = module_layouts(&tests_root, &["main.rs"]);
+        for (module, test_layout) in tests {
+            if module == Path::new("support") {
+                continue;
+            }
+
+            if let Some(production_layout) = production.get(&module) {
+                assert_eq!(
+                    test_layout,
+                    *production_layout,
+                    "{} must mirror the production module layout for {}",
+                    tests_root.join(module.with_extension("rs")).display(),
+                    member_root.join("src").join(&module).display(),
+                );
+                continue;
+            }
+
+            let has_production_owner = module
+                .parent()
+                .into_iter()
+                .flat_map(Path::ancestors)
+                .take_while(|ancestor| !ancestor.as_os_str().is_empty())
+                .any(|ancestor| production.contains_key(ancestor));
+            assert!(
+                has_production_owner || root_test_scenario_allowed(member, &module),
+                "{} has no mirrored production module owner",
+                tests_root.join(module.with_extension("rs")).display(),
+            );
+        }
+    }
+}
+
+fn module_layouts(root: &Path, crate_roots: &[&str]) -> BTreeMap<PathBuf, ModuleLayout> {
+    super::rust_files(root)
+        .into_iter()
+        .filter(|relative| {
+            !crate_roots
+                .iter()
+                .any(|candidate| relative == Path::new(candidate))
+        })
+        .map(|relative| {
+            if relative.file_name().and_then(|value| value.to_str()) == Some("mod.rs") {
+                (
+                    relative.parent().expect("mod.rs parent").to_path_buf(),
+                    ModuleLayout::Directory,
+                )
+            } else {
+                (relative.with_extension(""), ModuleLayout::File)
+            }
+        })
+        .collect()
+}
+
+fn root_test_scenario_allowed(member: &str, module: &Path) -> bool {
+    let Some(module) = module.to_str() else {
+        return false;
+    };
+    ROOT_TEST_SCENARIOS
+        .iter()
+        .any(|(candidate, scenarios)| *candidate == member && scenarios.contains(&module))
+}
+
+fn assert_module_tree(root: &Path, crate_roots: &[&str]) {
+    let files = super::rust_files(root);
+    for relative in &files {
+        if crate_roots
+            .iter()
+            .any(|candidate| relative == Path::new(candidate))
+        {
+            continue;
+        }
+
+        let file_name = relative
+            .file_name()
+            .and_then(|value| value.to_str())
+            .expect("Rust source file name");
+        let parent = relative.parent().expect("Rust source parent");
+        let module_name = if file_name == "mod.rs" {
+            parent
+                .file_name()
+                .and_then(|value| value.to_str())
+                .expect("mod.rs module name")
+        } else {
+            relative
+                .file_stem()
+                .and_then(|value| value.to_str())
+                .expect("Rust source module name")
+        };
+
+        if file_name != "mod.rs" {
+            assert_ne!(
+                parent.file_name().and_then(|value| value.to_str()),
+                Some(module_name),
+                "{} repeats its parent module name",
+                root.join(relative).display()
+            );
+            let child_directory = relative.with_extension("");
+            assert!(
+                !files
+                    .iter()
+                    .any(|candidate| candidate.starts_with(&child_directory)),
+                "{} mixes a leaf module with a same-name module directory",
+                root.join(relative).display()
+            );
+        }
+
+        let declaration_parents = if parent.as_os_str().is_empty()
+            || (file_name == "mod.rs"
+                && parent
+                    .parent()
+                    .is_some_and(|ancestor| ancestor.as_os_str().is_empty()))
+        {
+            crate_roots
+                .iter()
+                .map(|candidate| root.join(candidate))
+                .collect::<Vec<_>>()
+        } else {
+            let declaration_directory = if file_name == "mod.rs" {
+                parent.parent().expect("nested mod.rs parent")
+            } else {
+                parent
+            };
+            vec![root.join(declaration_directory).join("mod.rs")]
+        };
+        let declaration_count = declaration_parents
+            .iter()
+            .map(|path| external_module_declaration_count(path, module_name))
+            .sum::<usize>();
+        assert_eq!(
+            declaration_count,
+            1,
+            "{} must be declared exactly once by its parent module",
+            root.join(relative).display()
+        );
+    }
+}
+
+fn external_module_declaration_count(path: &Path, module_name: &str) -> usize {
+    if !path.is_file() {
+        return 0;
+    }
+    let source = fs::read_to_string(path).expect("read parent module source");
+    let syntax = syn::parse_file(&source).expect("parse parent module source");
+    syntax
+        .items
+        .iter()
+        .filter(|item| {
+            matches!(
+                item,
+                Item::Mod(module)
+                    if module.content.is_none() && module.ident == module_name
+            )
+        })
+        .count()
+}
+
+pub(super) fn backend_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("../..")
+        .canonicalize()
+        .expect("backend workspace root")
+}
+
+fn cargo_metadata_json() -> serde_json::Value {
+    let output = std::process::Command::new("cargo")
+        .args(["metadata", "--format-version", "1", "--no-deps"])
+        .current_dir(backend_root())
+        .output()
+        .expect("run cargo metadata");
+    assert!(
+        output.status.success(),
+        "cargo metadata failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    serde_json::from_slice(&output.stdout).expect("parse cargo metadata")
+}
+
+/// 提取成员 `[dependencies]` 段内声明的依赖名;段落以下一个 `[` 表头结束。
+fn dependency_names(member: &str) -> Vec<String> {
+    let manifest = fs::read_to_string(backend_root().join(member).join("Cargo.toml"))
+        .expect("read member manifest");
+    let mut in_dependencies = false;
+    let mut names = Vec::new();
+    for line in manifest.lines() {
+        let line = line.trim();
+        if line.starts_with('[') {
+            in_dependencies = line == "[dependencies]";
+            continue;
+        }
+        if !in_dependencies || line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+        if let Some((name, _)) = line.split_once('=') {
+            names.push(name.trim().to_owned());
+        }
+    }
+    names
+}
+
+fn assert_no_dependency(member: &str, forbidden: &[&str]) {
+    for name in dependency_names(member) {
+        assert!(
+            !forbidden.contains(&name.as_str()),
+            "{member} must not depend on `{name}`"
+        );
+    }
+}

backend/apps/gateway/tests/bootstrap.rs

@@ -0,0 +1,205 @@
+use std::{fs, process::Command};
+
+use codex_proxy_rs::bootstrap::GatewayConfig;
+use gateway_host::LoadableConfig;
+
+const CONFIG_EXAMPLE: &str = include_str!("../../../../deploy/config.example.yaml");
+const POSTGRES_PASSWORD: &str = "111111111111111111111111111111111111111111111111";
+const REDIS_PASSWORD: &str = "222222222222222222222222222222222222222222222222";
+const ADMIN_PASSWORD: &str = "test-admin-password";
+const TOPOLOGY_CHILD_ENV: &str = "CPR_TEST_TOPOLOGY_CHILD";
+
+#[test]
+fn config_loader_should_load_complete_terminal_example() {
+    parse_config(&valid_config()).expect("terminal config example");
+}
+
+#[test]
+fn config_loader_should_resolve_paths_relative_to_config_file() {
+    let (config, _directory) = parse_config(&valid_config()).expect("resolved config");
+    let debug = format!("{config:?}");
+    assert!(debug.contains(".runtime/data"));
+    assert!(debug.contains(".runtime/logs"));
+    assert!(debug.contains("frontend/dist"));
+}
+
+#[test]
+fn config_loader_should_reject_missing_runtime_data_dir() {
+    let config = valid_config().replace("  runtime_data_dir: '../.runtime/data'\n", "");
+
+    assert!(parse_config(&config).is_err());
+}
+
+#[test]
+fn config_loader_should_inject_connection_passwords_into_urls() {
+    parse_config(&valid_config()).expect("Store validates password injection into both URLs");
+}
+
+#[test]
+fn config_loader_should_apply_only_explicit_topology_overrides() {
+    let invalid = valid_config()
+        .replace("host: '127.0.0.1'", "host: ''")
+        .replace("port: 8080", "port: 0")
+        .replace(
+            "url: 'postgres://codex_proxy@127.0.0.1:5432/codex_proxy'",
+            "url: 'invalid-postgres-url'",
+        )
+        .replace("url: 'redis://127.0.0.1:6379/'", "url: 'invalid-redis-url'")
+        .replace(POSTGRES_PASSWORD, "invalid-postgres-password")
+        .replace(REDIS_PASSWORD, "invalid-redis-password");
+    if std::env::var_os(TOPOLOGY_CHILD_ENV).is_some() {
+        parse_config(&invalid).expect("explicit package-owned environment overrides");
+        return;
+    }
+    assert!(parse_config(&invalid).is_err());
+    let status = Command::new(std::env::current_exe().expect("current test executable"))
+        .args([
+            "--exact",
+            "bootstrap::config_loader_should_apply_only_explicit_topology_overrides",
+        ])
+        .env(TOPOLOGY_CHILD_ENV, "1")
+        .env("CPR_SERVER_HOST", "127.0.0.1")
+        .env("CPR_SERVER_PORT", "8080")
+        .env(
+            "CPR_DATABASE_URL",
+            "postgres://codex_proxy@127.0.0.1:5432/codex_proxy",
+        )
+        .env("CPR_REDIS_URL", "redis://127.0.0.1:6379/")
+        .env("CPR_DATABASE_PASSWORD", POSTGRES_PASSWORD)
+        .env("CPR_REDIS_PASSWORD", REDIS_PASSWORD)
+        .status()
+        .expect("run isolated environment override test");
+    assert!(status.success());
+}
+
+#[test]
+fn bootstrap_config_debug_should_redact_all_passwords() {
+    let (config, _directory) = parse_config(&valid_config()).expect("config");
+    let debug = format!("{config:?}");
+    assert!(!debug.contains(POSTGRES_PASSWORD));
+    assert!(!debug.contains(REDIS_PASSWORD));
+    assert!(!debug.contains(ADMIN_PASSWORD));
+    assert!(debug.contains("[REDACTED]"));
+}
+
+#[test]
+fn config_loader_should_reject_unknown_fields() {
+    assert_rejected(format!(
+        "{}\nunknown_terminal_field: true\n",
+        valid_config()
+    ));
+}
+
+#[test]
+fn config_loader_should_reject_removed_tls_section() {
+    assert_rejected(valid_config().replace("openai:\n", "openai:\n  tls: {}\n"));
+}
+
+#[test]
+fn config_loader_should_reject_missing_explicit_fields() {
+    assert_rejected(valid_config().replace("  request_id_header: 'x-request-id'\n", ""));
+}
+
+#[test]
+fn config_loader_should_reject_unsupported_schema_version() {
+    assert_rejected(valid_config().replace("schema_version: 1", "schema_version: 2"));
+}
+
+#[test]
+fn config_loader_should_reject_embedded_database_password() {
+    assert_rejected(valid_config().replace(
+        "postgres://codex_proxy@127.0.0.1:5432/codex_proxy",
+        "postgres://codex_proxy:embedded@127.0.0.1:5432/codex_proxy",
+    ));
+}
+
+#[test]
+fn config_loader_should_reject_non_hex_postgres_password() {
+    assert_rejected(valid_config().replace(POSTGRES_PASSWORD, &"g".repeat(48)));
+}
+
+#[test]
+fn config_loader_should_reject_wrong_length_redis_password() {
+    assert_rejected(valid_config().replace(REDIS_PASSWORD, "1234"));
+}
+
+#[test]
+fn config_loader_should_reject_weak_admin_password() {
+    assert_rejected(valid_config().replace(ADMIN_PASSWORD, "password"));
+}
+
+#[test]
+fn config_loader_should_reject_admin_password_with_compose_interpolation() {
+    assert_rejected(valid_config().replace(ADMIN_PASSWORD, "unsafe$password"));
+}
+
+#[test]
+fn config_loader_should_reject_removed_fingerprint_section() {
+    assert_rejected(valid_config().replace(
+        "openai:\n",
+        "openai:\n  fingerprint:\n    browser: removed\n",
+    ));
+}
+
+#[test]
+fn config_loader_should_reject_invalid_codex_cli_version() {
+    assert_rejected(valid_config().replace("codex_version: '0.153.4'", "codex_version: 'latest'"));
+}
+
+#[test]
+fn config_loader_should_reject_disabled_all_log_outputs() {
+    assert_rejected(
+        valid_config()
+            .replace("stdout: true", "stdout: false")
+            .replace("enabled: true", "enabled: false"),
+    );
+}
+
+#[test]
+fn config_loader_should_reject_zero_server_port() {
+    assert_rejected(valid_config().replace("port: 8080", "port: 0"));
+}
+
+#[test]
+fn config_loader_should_reject_invalid_desktop_profile_fields() {
+    assert_rejected(valid_config().replace("desktop_build: '8109'", "desktop_build: 'build'"));
+}
+
+fn assert_rejected(config: String) {
+    assert!(parse_config(&config).is_err());
+}
+
+fn valid_config() -> String {
+    CONFIG_EXAMPLE
+        .replacen(
+            "password: &postgres_password ''",
+            &format!("password: &postgres_password '{POSTGRES_PASSWORD}'"),
+            1,
+        )
+        .replacen(
+            "password: &redis_password ''",
+            &format!("password: &redis_password '{REDIS_PASSWORD}'"),
+            1,
+        )
+        .replace(
+            "default_password: ''",
+            &format!("default_password: '{ADMIN_PASSWORD}'"),
+        )
+}
+
+fn parse_config(config: &str) -> Result<(GatewayConfig, tempfile::TempDir), String> {
+    let directory = tempfile::tempdir().map_err(|error| error.to_string())?;
+    let deploy = directory.path().join("deploy");
+    fs::create_dir(&deploy).map_err(|error| error.to_string())?;
+    let path = deploy.join("config.yaml");
+    fs::write(&path, config).map_err(|error| error.to_string())?;
+    let mut config = config::Config::builder()
+        .add_source(config::File::from(path).required(true))
+        .build()
+        .and_then(config::Config::try_deserialize::<GatewayConfig>)
+        .map_err(|error| error.to_string())?;
+    config
+        .resolve_and_validate(&deploy)
+        .map_err(|error| error.to_string())?;
+    Ok((config, directory))
+}

backend/apps/gateway/tests/main.rs

@@ -0,0 +1,156 @@
+mod architecture;
+mod bootstrap;
+
+use std::{
+    collections::BTreeSet,
+    fs,
+    path::{Path, PathBuf},
+};
+
+use syn::{Attribute, Item, Meta};
+
+#[test]
+fn app_tree_matches_frozen_terminal_manifest() {
+    let root = Path::new(env!("CARGO_MANIFEST_DIR"));
+    assert_eq!(
+        rust_files(&root.join("src")),
+        BTreeSet::from([
+            PathBuf::from("bootstrap.rs"),
+            PathBuf::from("lib.rs"),
+            PathBuf::from("main.rs"),
+        ]),
+    );
+    assert_eq!(
+        rust_files(&root.join("tests")),
+        BTreeSet::from([
+            PathBuf::from("architecture.rs"),
+            PathBuf::from("bootstrap.rs"),
+            PathBuf::from("main.rs"),
+        ]),
+    );
+}
+
+#[test]
+fn cargo_library_root_is_conventional_lib() {
+    let manifest = fs::read_to_string(Path::new(env!("CARGO_MANIFEST_DIR")).join("Cargo.toml"))
+        .expect("read app Cargo.toml");
+    assert!(!manifest.contains("[lib]"));
+    assert!(
+        Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("src/lib.rs")
+            .is_file()
+    );
+}
+
+#[test]
+fn workspace_production_files_have_no_hidden_modules_or_test_hooks() {
+    for member in architecture::WORKSPACE_MEMBERS {
+        let root = architecture::backend_root().join(member).join("src");
+        for relative in rust_files(&root) {
+            let path = root.join(relative);
+            let source = fs::read_to_string(&path).expect("read production source");
+            assert!(
+                !source.contains("include!("),
+                "{} uses include!",
+                path.display()
+            );
+            let syntax = syn::parse_file(&source).expect("parse production source");
+            for item in &syntax.items {
+                if let Item::Mod(module) = item {
+                    assert!(
+                        module.content.is_none(),
+                        "{} has an inline module",
+                        path.display()
+                    );
+                }
+                for attribute in item_attrs(item) {
+                    assert!(
+                        !is_path_or_test_cfg(attribute),
+                        "{} has a production test/path hook",
+                        path.display(),
+                    );
+                }
+            }
+        }
+    }
+}
+
+#[test]
+fn bootstrap_owns_only_bundle_wiring() {
+    let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
+    let bootstrap = fs::read_to_string(root.join("bootstrap.rs")).expect("read bootstrap");
+    for forbidden in [
+        "sqlx::",
+        "redis::",
+        "Repository",
+        "impl Provider",
+        "impl ExecutionService",
+        "tokio::spawn",
+        "access_token",
+        "refresh_token",
+    ] {
+        assert!(
+            !bootstrap.contains(forbidden),
+            "bootstrap owns `{forbidden}`"
+        );
+    }
+    assert!(bootstrap.lines().count() <= 300);
+}
+
+fn rust_files(root: &Path) -> BTreeSet<PathBuf> {
+    let mut result = BTreeSet::new();
+    collect_rust_files(root, root, &mut result);
+    result
+}
+
+fn collect_rust_files(root: &Path, current: &Path, result: &mut BTreeSet<PathBuf>) {
+    for entry in fs::read_dir(current).expect("read app tree") {
+        let path = entry.expect("read app tree entry").path();
+        if path.is_dir() {
+            collect_rust_files(root, &path, result);
+        } else if path.extension().is_some_and(|extension| extension == "rs") {
+            result.insert(
+                path.strip_prefix(root)
+                    .expect("relative app path")
+                    .to_path_buf(),
+            );
+        }
+    }
+}
+
+fn is_path_or_test_cfg(attribute: &Attribute) -> bool {
+    if attribute.path().is_ident("path") {
+        return true;
+    }
+    if !attribute.path().is_ident("cfg") && !attribute.path().is_ident("cfg_attr") {
+        return false;
+    }
+    let Meta::List(list) = &attribute.meta else {
+        return false;
+    };
+    list.tokens
+        .to_string()
+        .split(|character: char| !character.is_ascii_alphanumeric() && character != '_')
+        .any(|segment| segment == "test" || segment.starts_with("test_"))
+}
+
+fn item_attrs(item: &Item) -> &[Attribute] {
+    match item {
+        Item::Const(item) => &item.attrs,
+        Item::Enum(item) => &item.attrs,
+        Item::ExternCrate(item) => &item.attrs,
+        Item::Fn(item) => &item.attrs,
+        Item::ForeignMod(item) => &item.attrs,
+        Item::Impl(item) => &item.attrs,
+        Item::Macro(item) => &item.attrs,
+        Item::Mod(item) => &item.attrs,
+        Item::Static(item) => &item.attrs,
+        Item::Struct(item) => &item.attrs,
+        Item::Trait(item) => &item.attrs,
+        Item::TraitAlias(item) => &item.attrs,
+        Item::Type(item) => &item.attrs,
+        Item::Union(item) => &item.attrs,
+        Item::Use(item) => &item.attrs,
+        _ => &[],
+    }
+}

backend/crates/gateway-admin/Cargo.toml

@@ -0,0 +1,41 @@
+[package]
+name = "gateway-admin"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+rust-version.workspace = true
+autotests = false
+
+[[test]]
+name = "main"
+path = "tests/main.rs"
+
+[dependencies]
+argon2 = "0.6.0"
+async-trait = "0.1.89"
+base64 = "0.23.0"
+bytes = "1.11.1"
+chrono = "0.4.45"
+futures = "0.3.32"
+gateway-core = { path = "../gateway-core" }
+hex = "0.4.3"
+rand_core = { version = "0.6.4", features = ["getrandom"] }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
+secrecy = { version = "0.10.3", features = ["serde"] }
+subtle = "2.6.1"
+thiserror = "2.0.18"
+tracing = "0.1.44"
+uuid = { version = "1.23.3", features = ["v7"] }
+cron = "0.17"
+chrono-tz = "0.10"
+tokio = { version = "1.52", features = ["rt", "time", "macros", "sync"] }
+
+[dev-dependencies]
+sha2 = "0.11"
+tempfile = "3"
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt"] }
+
+[lints]
+workspace = true

backend/crates/gateway-admin/src/backup/mod.rs

@@ -0,0 +1,4 @@
+//! 备份纯策略与 Worker 任务。
+
+pub mod policy;
+pub mod task;

backend/crates/gateway-admin/src/backup/policy.rs

@@ -0,0 +1,161 @@
+//! 备份纯策略：Cron 推进与保留候选。
+//!
+//! 本模块不持有任何端口或对象，是 `BackupService` 与 `BackupTask` 共用的纯函数集。
+
+use std::str::FromStr;
+
+use chrono::{DateTime, Duration, TimeZone as _, Utc};
+use chrono_tz::Tz;
+use cron::Schedule;
+
+use crate::model::backup::{BackupError, BackupRecord, BackupStatus, code};
+
+/// 向历史回溯的最大范围（分钟）。覆盖 Feb 29 + 特定星期等罕见组合的最长间隔。
+const MAX_BACKDATE_MINUTES: i64 = 40 * 366 * 24 * 60;
+
+/// 已解析并校验的备份计划。
+#[derive(Debug, Clone)]
+pub struct BackupSchedule {
+    schedule: Schedule,
+    timezone: Tz,
+}
+
+impl BackupSchedule {
+    /// 解析并校验 5 段 Cron 与 IANA 时区。
+    ///
+    /// # Errors
+    ///
+    /// Cron 非法或时区不是 IANA 名称时返回 [`BackupError`]。
+    pub fn parse(cron_expression: &str, schedule_timezone: &str) -> Result<Self, BackupError> {
+        let expression = format!("0 {cron_expression}");
+        let schedule = Schedule::from_str(&expression).map_err(|_| {
+            BackupError::new(code::INVALID_CRON, "Cron 表达式必须是 5 段格式".to_owned())
+        })?;
+        let timezone = schedule_timezone.parse::<Tz>().map_err(|_| {
+            BackupError::new(code::INVALID_TIMEZONE, "时区必须是 IANA 名称".to_owned())
+        })?;
+        Ok(Self { schedule, timezone })
+    }
+
+    /// 返回最接近 `at`（含 `at` 所在分钟）的最近一次触发时间。
+    ///
+    /// 若过去 `MAX_BACKDATE_MINUTES` 内没有任何触发（极罕见的稀疏计划或超长停机），
+    /// 返回 `None`，调用方不应为历史点补任务。
+    #[must_use]
+    pub fn last_firing_at_or_before(&self, at: DateTime<Utc>) -> Option<DateTime<Utc>> {
+        let high_min = at.timestamp().div_euclid(60);
+        let low_min = high_min.saturating_sub(MAX_BACKDATE_MINUTES);
+
+        // 检查窗口内是否存在触发；不存在则直接返回 None。
+        let low_instant = instant(low_min, self.timezone)?;
+        if self
+            .schedule
+            .after(&low_instant)
+            .next()
+            .is_none_or(|firing| firing.timestamp() > high_min * 60 + 59)
+        {
+            return None;
+        }
+
+        // 二分查找最小的 u（分钟）使 after(u) > high；prev = after(u - 1 分钟)。
+        let mut lo = low_min;
+        let mut hi = high_min;
+        while lo < hi {
+            let mid = lo + (hi - lo) / 2;
+            if self
+                .firing_after(mid)
+                .is_some_and(|firing| firing > high_min)
+            {
+                hi = mid;
+            } else {
+                lo = mid + 1;
+            }
+        }
+        self.firing_after(lo - 1)
+            .filter(|&firing| firing <= high_min)
+            .and_then(|firing| Utc.timestamp_opt(firing * 60, 0).single())
+    }
+
+    /// 返回第一个严格晚于 `at` 的触发时间。
+    #[must_use]
+    pub fn next_after(&self, at: DateTime<Utc>) -> Option<DateTime<Utc>> {
+        let local = at.with_timezone(&self.timezone);
+        self.schedule
+            .after(&local)
+            .next()
+            .map(|firing| firing.with_timezone(&Utc))
+    }
+
+    /// `after(u 分钟)` 返回的第一个触发时间（分钟索引），用于二分搜索。
+    fn firing_after(&self, minute_index: i64) -> Option<i64> {
+        let instant = instant(minute_index, self.timezone)?;
+        self.schedule
+            .after(&instant)
+            .next()
+            .map(|firing| firing.timestamp().div_euclid(60))
+    }
+}
+
+/// 构造指定分钟索引（UTC epoch 分钟）在目标时区下的 `DateTime`。
+fn instant(minute_index: i64, timezone: Tz) -> Option<DateTime<Tz>> {
+    timezone.timestamp_opt(minute_index * 60, 0).single()
+}
+
+/// 一条记录被纳入删除流程的原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RetentionReason {
+    /// 超过 `retention_days`。
+    Days,
+    /// 超过 `retention_count`。
+    Count,
+}
+
+/// 保留决策。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RetentionDecision {
+    pub record_id: String,
+    pub reason: RetentionReason,
+}
+
+/// 从按完成时间倒序的 completed 计划备份中决定纳入删除流程的记录。
+///
+/// 自动保留规则：
+/// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理。
+/// - 自动计划备份满足任一启用阈值即可进入删除。
+/// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）。
+/// - 手动备份不进入本规则；手工/计划记录各自的 `expires_at` 由到期扫描处理。
+#[must_use]
+pub fn decide_retention(
+    retention_days: u32,
+    retention_count: u32,
+    now: DateTime<Utc>,
+    scheduled_completed_desc: &[BackupRecord],
+) -> Vec<RetentionDecision> {
+    let mut decisions = Vec::new();
+    for (index, record) in scheduled_completed_desc.iter().enumerate() {
+        if record.status != BackupStatus::Completed {
+            continue;
+        }
+        // 最近一个成功的计划备份永远保留。
+        if index == 0 {
+            continue;
+        }
+        let expired_by_days = retention_days > 0
+            && record.completed_at.is_some_and(|completed_at| {
+                completed_at <= now - Duration::days(i64::from(retention_days))
+            });
+        let exceeded_count =
+            retention_count > 0 && index >= usize::try_from(retention_count).unwrap_or(usize::MAX);
+        if expired_by_days || exceeded_count {
+            decisions.push(RetentionDecision {
+                record_id: record.id.clone(),
+                reason: if expired_by_days {
+                    RetentionReason::Days
+                } else {
+                    RetentionReason::Count
+                },
+            });
+        }
+    }
+    decisions
+}

backend/crates/gateway-admin/src/backup/task.rs

@@ -0,0 +1,648 @@
+//! Backup Worker 贡献：单个可取消 `DaemonTask` 承担调度、执行、删除收敛与保留清理。
+//!
+//! 当前部署边界是单副本，因此不需要 Redis lease、fencing token 或 heartbeat。长时间
+//! `pg_dump` 与上传由本 Daemon 自身持有；Host 只负责 panic 后重启、健康与关闭。
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use chrono::{DateTime, Utc};
+use futures::future::BoxFuture;
+use gateway_core::{
+    lifecycle::CancellationToken,
+    task::{DaemonTask, WorkerTaskError},
+};
+use tracing::{info, warn};
+
+use crate::{
+    model::backup::{
+        BackupError, BackupObjectMetadata, BackupRecord, BackupStatus, BackupStorageConfig,
+        BackupTriggerKind, build_backup_seed, code,
+    },
+    ports::backup::{
+        BackupObjectStorePort, BackupRepository, DatabaseDumpPort, DumpRequest,
+        StatusTransitionUpdate, UploadObjectRequest,
+    },
+};
+
+impl From<BackupError> for WorkerTaskError {
+    fn from(error: BackupError) -> Self {
+        WorkerTaskError::safe(error.message())
+    }
+}
+
+use super::policy::{BackupSchedule, decide_retention};
+
+/// 循环间隔：管理员修改 Cron 后该时长内生效；无工作时可取消等待。
+const BACKUP_LOOP_INTERVAL: Duration = Duration::from_secs(30);
+/// 每个循环最多执行的保留删除数量。
+const RETENTION_BATCH_SIZE: usize = 10;
+/// 保留扫描一次读取的 completed 计划备份上限。
+const RETENTION_SCAN_LIMIT: u32 = 1000;
+/// 每个循环最多完成的待删除记录数量。
+const PENDING_DELETION_BATCH: u32 = 20;
+
+/// 备份 Daemon 任务。
+pub struct BackupTask {
+    repository: Arc<dyn BackupRepository>,
+    dump: Arc<dyn DatabaseDumpPort>,
+    object_store: Arc<dyn BackupObjectStorePort>,
+}
+
+impl BackupTask {
+    /// 组合仓储、导出器与对象存储适配器。
+    #[must_use]
+    pub fn new(
+        repository: Arc<dyn BackupRepository>,
+        dump: Arc<dyn DatabaseDumpPort>,
+        object_store: Arc<dyn BackupObjectStorePort>,
+    ) -> Self {
+        Self {
+            repository,
+            dump,
+            object_store,
+        }
+    }
+}
+
+impl DaemonTask for BackupTask {
+    fn run(&self, cancellation: CancellationToken) -> BoxFuture<'_, Result<(), WorkerTaskError>> {
+        Box::pin(async move { self.run_daemon(cancellation).await })
+    }
+}
+
+impl BackupTask {
+    async fn run_daemon(&self, cancellation: CancellationToken) -> Result<(), WorkerTaskError> {
+        loop {
+            if cancellation.is_cancelled() {
+                return Ok(());
+            }
+            self.run_cycle(&cancellation).await?;
+
+            tokio::select! {
+                _ = cancellation.cancelled() => return Ok(()),
+                _ = tokio::time::sleep(BACKUP_LOOP_INTERVAL) => {}
+            }
+        }
+    }
+
+    /// 执行一个周期：推进计划、恢复中间态、删除收敛、领取执行一个任务、保留清理。
+    ///
+    /// 对外暴露以便集成测试逐周期驱动；daemon 循环内部复用。
+    ///
+    /// # Errors
+    ///
+    /// 仓储或基础设施不可用、任务执行失败时返回 [`WorkerTaskError`]。
+    pub async fn run_cycle(&self, cancellation: &CancellationToken) -> Result<(), WorkerTaskError> {
+        if cancellation.is_cancelled() {
+            return Ok(());
+        }
+        self.advance_schedule(Utc::now()).await?;
+        self.recover_intermediate(cancellation).await?;
+        self.finish_pending_deletions().await?;
+        self.process_next_task(cancellation).await?;
+        self.run_retention_batch(Utc::now()).await?;
+        Ok(())
+    }
+
+    /// 推进到期计划并幂等插入 scheduled 任务。
+    async fn advance_schedule(&self, now: DateTime<Utc>) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        if !settings.schedule_enabled {
+            return Ok(());
+        }
+        let cron = settings.cron_expression.as_deref().unwrap_or_default();
+        let timezone = settings.schedule_timezone.as_deref().unwrap_or_default();
+        if cron.is_empty() || timezone.is_empty() {
+            return Ok(());
+        }
+        let schedule = BackupSchedule::parse(cron, timezone)
+            .map_err(|_| WorkerTaskError::safe("backup schedule is invalid"))?;
+
+        let due = match settings.next_run_at {
+            Some(next_run_at) if next_run_at <= now => true,
+            Some(_) => false,
+            None => {
+                // 刚启用计划但尚无游标：直接初始化。
+                if let Some(next_run_at) = schedule.next_after(now) {
+                    let _ = self
+                        .repository
+                        .advance_schedule_cursor(next_run_at, cron, timezone)
+                        .await
+                        .map_err(repo_error)?;
+                }
+                return Ok(());
+            }
+        };
+        if !due {
+            return Ok(());
+        }
+
+        let scheduled_at = match schedule.last_firing_at_or_before(now) {
+            Some(scheduled_at) => scheduled_at,
+            None => {
+                // 无法从计划推导最近到期时间：推进游标避免反复触发。
+                if let Some(next_run_at) = schedule.next_after(now) {
+                    let _ = self
+                        .repository
+                        .advance_schedule_cursor(next_run_at, cron, timezone)
+                        .await
+                        .map_err(repo_error)?;
+                }
+                return Ok(());
+            }
+        };
+        let prefix = settings.prefix.as_deref().unwrap_or_default();
+        let expires_at = if settings.retention_days > 0 {
+            Some(now + chrono::Duration::days(i64::from(settings.retention_days)))
+        } else {
+            None
+        };
+        let seed = build_backup_seed(
+            BackupTriggerKind::Scheduled,
+            Some(scheduled_at),
+            prefix,
+            now,
+            expires_at,
+        )
+        .map_err(infra_error)?;
+        let inserted = self
+            .repository
+            .insert_scheduled_record(seed)
+            .await
+            .map_err(repo_error)?;
+        if inserted {
+            info!(scheduled_at = %scheduled_at, "计划备份任务已创建");
+        } else {
+            warn!(scheduled_at = %scheduled_at, "计划时间点冲突，跳过并推进游标");
+        }
+        if let Some(next_run_at) = schedule.next_after(now) {
+            let _ = self
+                .repository
+                .advance_schedule_cursor(next_run_at, cron, timezone)
+                .await
+                .map_err(repo_error)?;
+        }
+        Ok(())
+    }
+
+    /// 恢复中间状态（dumping/uploading/deleting）。
+    async fn recover_intermediate(
+        &self,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let records = self
+            .repository
+            .list_intermediate_records()
+            .await
+            .map_err(repo_error)?;
+        for record in records {
+            match record.status {
+                BackupStatus::Dumping => self.recover_dumping(&record, cancellation).await?,
+                BackupStatus::Uploading => self.recover_uploading(&record, cancellation).await?,
+                _ => {}
+            }
+        }
+        Ok(())
+    }
+
+    /// dumping：有完整暂存则继续上传，否则清理暂存并标记失败。
+    async fn recover_dumping(
+        &self,
+        record: &BackupRecord,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        match self.dump.inspect_staging(&record.id).await? {
+            Some(artifact) => {
+                let now = Utc::now();
+                let update = StatusTransitionUpdate {
+                    size_bytes: Some(artifact.size_bytes),
+                    sha256: Some(artifact.sha256.clone()),
+                    ..Default::default()
+                };
+                let Some(uploading_record) = self
+                    .repository
+                    .transition_status(
+                        &record.id,
+                        BackupStatus::Dumping,
+                        BackupStatus::Uploading,
+                        update,
+                        now,
+                    )
+                    .await
+                    .map_err(repo_error)?
+                else {
+                    return Ok(());
+                };
+                self.upload_and_verify(
+                    &uploading_record,
+                    &artifact.path,
+                    artifact.size_bytes,
+                    &artifact.sha256,
+                    now,
+                    cancellation,
+                )
+                .await?;
+            }
+            None => {
+                let _ = self.dump.cleanup_staging(&record.id).await;
+                self.fail_task(record, code::PG_DUMP_FAILED, "导出进程中断，暂存归档不完整")
+                    .await?;
+            }
+        }
+        Ok(())
+    }
+
+    /// uploading：远端匹配则补记完成，有完整暂存则重试上传，否则失败。
+    async fn recover_uploading(
+        &self,
+        record: &BackupRecord,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Ok(());
+        };
+        if let Some(remote) = self
+            .object_store
+            .head_object(&config, &record.object_key)
+            .await?
+            && record.size_bytes == Some(remote.size_bytes)
+            && record.sha256.as_deref() == Some(remote.sha256.as_str())
+        {
+            let now = Utc::now();
+            self.repository
+                .transition_status(
+                    &record.id,
+                    BackupStatus::Uploading,
+                    BackupStatus::Completed,
+                    StatusTransitionUpdate::default(),
+                    now,
+                )
+                .await
+                .map_err(repo_error)?;
+            return Ok(());
+        }
+        match self.dump.inspect_staging(&record.id).await? {
+            Some(artifact) => {
+                self.upload_and_verify(
+                    record,
+                    &artifact.path,
+                    artifact.size_bytes,
+                    &artifact.sha256,
+                    Utc::now(),
+                    cancellation,
+                )
+                .await
+            }
+            None => {
+                self.fail_task(
+                    record,
+                    code::S3_UPLOAD_FAILED,
+                    "远端对象缺失且本地无完整暂存",
+                )
+                .await
+            }
+        }
+    }
+
+    /// 完成待删除记录（deleting → DeleteObject → 硬删除）。
+    async fn finish_pending_deletions(&self) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Ok(());
+        };
+        let records = self
+            .repository
+            .list_pending_deletions(PENDING_DELETION_BATCH)
+            .await
+            .map_err(repo_error)?;
+        for record in records {
+            if self
+                .object_store
+                .delete_object(&config, &record.object_key)
+                .await
+                .is_ok()
+            {
+                self.repository
+                    .delete_record(&record.id)
+                    .await
+                    .map_err(repo_error)?;
+            }
+        }
+        Ok(())
+    }
+
+    /// 领取一个 queued 任务并执行导出、上传与远端校验。
+    async fn process_next_task(
+        &self,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let now = Utc::now();
+        let Some(record) = self
+            .repository
+            .claim_next_queued(now)
+            .await
+            .map_err(repo_error)?
+        else {
+            return Ok(());
+        };
+        info!(
+            backup_id = %record.id,
+            attempt = record.attempt_count,
+            "领取备份任务"
+        );
+        if let Err(error) = self.execute_task(&record, cancellation).await {
+            warn!(backup_id = %record.id, error = %error, "备份任务执行失败");
+        }
+        Ok(())
+    }
+
+    /// 执行单个任务；内部处理全部状态迁移。
+    async fn execute_task(
+        &self,
+        record: &BackupRecord,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        if BackupStorageConfig::from_settings(&settings).is_none() {
+            return self
+                .fail_task(record, code::INVALID_CONFIG, "备份存储配置不完整")
+                .await;
+        }
+        if !settings.storage_verified() {
+            return self
+                .fail_task(record, code::INVALID_CONFIG, "备份存储配置尚未通过连接测试")
+                .await;
+        }
+
+        let now = Utc::now();
+        let artifact = match self
+            .dump
+            .dump(DumpRequest {
+                backup_id: record.id.clone(),
+                cancellation: cancellation.clone(),
+            })
+            .await
+        {
+            Ok(artifact) => artifact,
+            Err(error) => {
+                let (error_code, message) = classify_dump_error(error);
+                return self.fail_task(record, error_code, message).await;
+            }
+        };
+
+        // dumping → uploading，持久化 size/sha256。
+        let update = StatusTransitionUpdate {
+            size_bytes: Some(artifact.size_bytes),
+            sha256: Some(artifact.sha256.clone()),
+            ..Default::default()
+        };
+        let Some(uploading_record) = self
+            .repository
+            .transition_status(
+                &record.id,
+                BackupStatus::Dumping,
+                BackupStatus::Uploading,
+                update,
+                now,
+            )
+            .await
+            .map_err(repo_error)?
+        else {
+            return Ok(());
+        };
+
+        self.upload_and_verify(
+            &uploading_record,
+            &artifact.path,
+            artifact.size_bytes,
+            &artifact.sha256,
+            now,
+            cancellation,
+        )
+        .await?;
+        let _ = self.dump.cleanup_staging(&record.id).await;
+        Ok(())
+    }
+
+    /// 上传 + 远端校验，内部完成终态迁移。
+    async fn upload_and_verify(
+        &self,
+        record: &BackupRecord,
+        source: &std::path::Path,
+        size_bytes: u64,
+        sha256: &str,
+        now: DateTime<Utc>,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Ok(());
+        };
+        let store = self.object_store.clone();
+        let metadata =
+            BackupObjectMetadata::new(record.id.clone(), sha256.to_owned(), now, size_bytes);
+        if let Err(error) = store
+            .upload_file(
+                &config,
+                UploadObjectRequest {
+                    object_key: record.object_key.clone(),
+                    source: source.to_path_buf(),
+                    metadata,
+                    cancellation: cancellation.clone(),
+                },
+            )
+            .await
+        {
+            let _ = store.delete_object(&config, &record.object_key).await;
+            self.fail_task(
+                record,
+                error.code(),
+                format!("上传到对象存储失败：{}", error.message()),
+            )
+            .await?;
+            return Ok(());
+        }
+
+        match store.head_object(&config, &record.object_key).await {
+            Ok(Some(remote)) if remote.size_bytes == size_bytes && remote.sha256 == sha256 => {
+                if self
+                    .repository
+                    .transition_status(
+                        &record.id,
+                        BackupStatus::Uploading,
+                        BackupStatus::Completed,
+                        StatusTransitionUpdate::default(),
+                        Utc::now(),
+                    )
+                    .await
+                    .map_err(repo_error)?
+                    .is_some()
+                {
+                    info!(
+                        backup_id = %record.id,
+                        size_bytes,
+                        "备份完成"
+                    );
+                }
+            }
+            Ok(Some(remote)) => {
+                let size_matches = remote.size_bytes == size_bytes;
+                let sha256_matches = remote.sha256 == sha256;
+                warn!(
+                    backup_id = %record.id,
+                    expected_size_bytes = size_bytes,
+                    remote_size_bytes = remote.size_bytes,
+                    sha256_matches,
+                    "备份远端对象校验不一致"
+                );
+                let _ = store.delete_object(&config, &record.object_key).await;
+                self.fail_task(
+                    record,
+                    code::REMOTE_VERIFICATION_FAILED,
+                    match (size_matches, sha256_matches) {
+                        (false, true) => "远端对象大小不一致",
+                        (true, false) => "远端对象 sha256 校验值不一致",
+                        (false, false) => "远端对象大小和 sha256 校验值均不一致",
+                        (true, true) => "远端对象校验状态异常",
+                    },
+                )
+                .await?;
+            }
+            Ok(None) => {
+                warn!(backup_id = %record.id, "上传完成后未找到远端对象");
+                self.fail_task(
+                    record,
+                    code::REMOTE_VERIFICATION_FAILED,
+                    "上传完成后未找到远端对象",
+                )
+                .await?;
+            }
+            Err(error) => {
+                let _ = store.delete_object(&config, &record.object_key).await;
+                self.fail_task(
+                    record,
+                    error.code(),
+                    format!("远端对象校验失败：{}", error.message()),
+                )
+                .await?;
+            }
+        }
+        Ok(())
+    }
+
+    /// 把活跃任务写入失败终态并清理暂存。
+    async fn fail_task(
+        &self,
+        record: &BackupRecord,
+        error_code: &'static str,
+        message: impl Into<String>,
+    ) -> Result<(), WorkerTaskError> {
+        let message = message.into();
+        warn!(
+            backup_id = %record.id,
+            error_code,
+            error_message = %message,
+            "备份任务失败"
+        );
+        let now = Utc::now();
+        let update = StatusTransitionUpdate {
+            error_code: Some(error_code.to_string()),
+            error_message: Some(message),
+            completed_at: Some(now),
+            ..Default::default()
+        };
+        let _ = self
+            .repository
+            .transition_status(&record.id, record.status, BackupStatus::Failed, update, now)
+            .await
+            .map_err(repo_error)?;
+        let _ = self.dump.cleanup_staging(&record.id).await;
+        Ok(())
+    }
+
+    /// 执行一小批到期保留清理：先处理 `expires_at` 已到期的记录，再按天数/份数清理计划备份。
+    async fn run_retention_batch(&self, now: DateTime<Utc>) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+
+        // 1. expires_at 已到期的记录（手动或计划）无条件进入删除。
+        let expired = self
+            .repository
+            .list_expired_records(RETENTION_BATCH_SIZE as u32)
+            .await
+            .map_err(repo_error)?;
+        for record in expired {
+            let Some(record) = self
+                .repository
+                .transition_to_deleting(&record.id, now)
+                .await
+                .map_err(repo_error)?
+            else {
+                continue;
+            };
+            self.finalize_deletion(&record).await?;
+        }
+
+        // 2. 计划备份按 retentionDays / retentionCount 清理。
+        let records = self
+            .repository
+            .list_scheduled_completed_desc(RETENTION_SCAN_LIMIT)
+            .await
+            .map_err(repo_error)?;
+        let decisions = decide_retention(
+            settings.retention_days,
+            settings.retention_count,
+            now,
+            &records,
+        );
+        for decision in decisions.into_iter().take(RETENTION_BATCH_SIZE) {
+            let Some(record) = self
+                .repository
+                .transition_to_deleting(&decision.record_id, now)
+                .await
+                .map_err(repo_error)?
+            else {
+                continue;
+            };
+            self.finalize_deletion(&record).await?;
+        }
+        Ok(())
+    }
+
+    /// 对已进入 deleting 的记录执行对象删除并硬删除记录行。
+    async fn finalize_deletion(&self, record: &BackupRecord) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Ok(());
+        };
+        if self
+            .object_store
+            .delete_object(&config, &record.object_key)
+            .await
+            .is_ok()
+        {
+            self.repository
+                .delete_record(&record.id)
+                .await
+                .map_err(repo_error)?;
+        }
+        Ok(())
+    }
+}
+
+fn classify_dump_error(error: BackupError) -> (&'static str, &'static str) {
+    match error.code() {
+        code::CANCELLED => (code::CANCELLED, "备份已取消"),
+        code::STAGING_SPACE_EXHAUSTED => (code::STAGING_SPACE_EXHAUSTED, "暂存磁盘空间不足"),
+        _ => (code::PG_DUMP_FAILED, "数据库导出失败"),
+    }
+}
+
+fn repo_error(error: crate::ports::store::AdminStoreError) -> WorkerTaskError {
+    WorkerTaskError::safe(format!("backup store failed: {error}"))
+}
+
+fn infra_error(error: BackupError) -> WorkerTaskError {
+    WorkerTaskError::safe(error.message())
+}

backend/crates/gateway-admin/src/lib.rs

@@ -0,0 +1,373 @@
+//! 管理控制面的语义模型、用例与外部能力端口。
+//!
+//! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现。
+
+use std::{fmt, path::Path, sync::Arc, time::Duration};
+
+use gateway_core::{
+    engine::probe::AccountProbe,
+    routing::ProviderKind,
+    runtime::SnapshotControl,
+    task::{
+        DaemonRestartPolicy, WorkerContribution, WorkerId, WorkerKind, WorkerRegistration,
+        WorkerRunnable,
+    },
+};
+use secrecy::{ExposeSecret as _, SecretString};
+use serde::Deserialize;
+
+pub mod backup;
+pub mod model;
+pub mod ports;
+mod use_case;
+
+pub use use_case::{
+    account_groups::AccountGroupService, accounts::AccountsService, auth::AuthService,
+    backup::BackupService, client_distribution::ClientDistributionService,
+    client_keys::ClientKeyService, observability::ObservabilityService, openai::OpenAiService,
+    settings::SettingsService, system::SystemService, xai::XaiService,
+};
+
+use model::{AdminError, AdminErrorKind};
+use ports::{
+    client_distribution::ClientDistributionResolver,
+    provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind, ProviderAdminRegistry},
+    store::AdminStorePorts,
+    system::SystemOperations,
+};
+use use_case::{
+    account_groups::DefaultAccountGroupService, accounts::DefaultAccountsService,
+    auth::DefaultAuthService, backup::DefaultBackupService,
+    client_distribution::DefaultClientDistributionService, client_keys::DefaultClientKeyService,
+    observability::DefaultObservabilityService, openai::DefaultOpenAiService,
+    settings::DefaultSettingsService, system::DefaultSystemService, xai::DefaultXaiService,
+};
+
+const OPENAI_PROVIDER_KIND: &str = "openai";
+const XAI_PROVIDER_KIND: &str = "xai";
+const MINIMUM_INITIAL_PASSWORD_BYTES: usize = 12;
+const WEAK_INITIAL_PASSWORDS: &[&str] = &[
+    "",
+    "admin",
+    "123456",
+    "password",
+    "changeme",
+    "change-me",
+    "replace-me",
+    "codex-proxy-rs",
+];
+
+const BACKUP_WORKER_OWNER: &str = "backup";
+
+/// 只用于首次幂等创建默认管理员的启动密码。
+#[derive(Clone, Deserialize)]
+#[serde(transparent)]
+pub struct InitialAdminPassword(SecretString);
+
+impl InitialAdminPassword {
+    #[must_use]
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(SecretString::from(value.into()))
+    }
+
+    fn expose(&self) -> &str {
+        self.0.expose_secret()
+    }
+}
+
+impl PartialEq for InitialAdminPassword {
+    fn eq(&self, other: &Self) -> bool {
+        self.expose() == other.expose()
+    }
+}
+
+impl Eq for InitialAdminPassword {}
+
+impl fmt::Debug for InitialAdminPassword {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("InitialAdminPassword([REDACTED])")
+    }
+}
+
+/// 管理控制面的启动配置。
+#[derive(Clone, Deserialize, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct AdminConfig {
+    pub session_ttl_minutes: u64,
+    pub default_username: String,
+    pub default_password: InitialAdminPassword,
+}
+
+impl AdminConfig {
+    /// 校验 Admin-owned 字段；当前配置不含相对路径。
+    ///
+    /// # Errors
+    ///
+    /// 用户名、会话有效期或初始密码不满足安全约束时返回错误。
+    pub fn resolve_and_validate(&mut self, _source_dir: &Path) -> Result<(), AdminConfigError> {
+        if self.default_username.trim().is_empty()
+            || self.default_username.chars().any(char::is_control)
+        {
+            return Err(AdminConfigError::InvalidField("admin.default_username"));
+        }
+        if self.session_ttl_minutes == 0 || i64::try_from(self.session_ttl_minutes).is_err() {
+            return Err(AdminConfigError::InvalidField("admin.session_ttl_minutes"));
+        }
+        let password = self.default_password.expose().trim();
+        if password.len() < MINIMUM_INITIAL_PASSWORD_BYTES
+            || password.contains('$')
+            || WEAK_INITIAL_PASSWORDS.contains(&password.to_ascii_lowercase().as_str())
+        {
+            return Err(AdminConfigError::WeakInitialPassword);
+        }
+        Ok(())
+    }
+}
+
+impl fmt::Debug for AdminConfig {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("AdminConfig")
+            .field("session_ttl_minutes", &self.session_ttl_minutes)
+            .field("default_username", &self.default_username)
+            .field("default_password", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// Admin-owned 启动配置错误；不回显任何配置值。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum AdminConfigError {
+    #[error("配置字段 `{0}` 不合法")]
+    InvalidField(&'static str),
+    #[error("admin.default_password 不符合初始密码策略")]
+    WeakInitialPassword,
+}
+
+/// API 持有的管理资源能力集合。
+///
+/// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块。
+#[derive(Clone)]
+pub struct AdminServices {
+    auth: Arc<dyn AuthService>,
+    accounts: Arc<dyn AccountsService>,
+    account_groups: Arc<dyn AccountGroupService>,
+    client_keys: Arc<dyn ClientKeyService>,
+    client_distribution: Arc<dyn ClientDistributionService>,
+    observability: Arc<dyn ObservabilityService>,
+    settings: Arc<dyn SettingsService>,
+    system: Arc<dyn SystemService>,
+    openai: Arc<dyn OpenAiService>,
+    xai: Arc<dyn XaiService>,
+    backups: Arc<dyn BackupService>,
+}
+
+impl AdminServices {
+    #[must_use]
+    pub fn auth(&self) -> &dyn AuthService {
+        self.auth.as_ref()
+    }
+
+    #[must_use]
+    pub fn accounts(&self) -> &dyn AccountsService {
+        self.accounts.as_ref()
+    }
+
+    #[must_use]
+    pub fn account_groups(&self) -> &dyn AccountGroupService {
+        self.account_groups.as_ref()
+    }
+
+    #[must_use]
+    pub fn client_keys(&self) -> &dyn ClientKeyService {
+        self.client_keys.as_ref()
+    }
+
+    #[must_use]
+    pub fn client_distribution(&self) -> &dyn ClientDistributionService {
+        self.client_distribution.as_ref()
+    }
+
+    #[must_use]
+    pub fn observability(&self) -> &dyn ObservabilityService {
+        self.observability.as_ref()
+    }
+
+    #[must_use]
+    pub fn settings(&self) -> &dyn SettingsService {
+        self.settings.as_ref()
+    }
+
+    #[must_use]
+    pub fn system(&self) -> &dyn SystemService {
+        self.system.as_ref()
+    }
+
+    #[must_use]
+    pub fn openai(&self) -> &dyn OpenAiService {
+        self.openai.as_ref()
+    }
+
+    #[must_use]
+    pub fn xai(&self) -> &dyn XaiService {
+        self.xai.as_ref()
+    }
+
+    #[must_use]
+    pub fn backups(&self) -> &dyn BackupService {
+        self.backups.as_ref()
+    }
+}
+
+/// Admin 初始化完成后的封闭能力包。
+pub struct AdminBundle {
+    services: AdminServices,
+    worker_contributions: Vec<WorkerContribution>,
+}
+
+impl AdminBundle {
+    #[must_use]
+    pub fn services(&self) -> AdminServices {
+        self.services.clone()
+    }
+
+    /// 取出 Backup Worker 贡献；只能调用一次，与其它 Bundle 的贡献一并交给 Host。
+    pub fn take_worker_contributions(&mut self) -> Vec<WorkerContribution> {
+        std::mem::take(&mut self.worker_contributions)
+    }
+}
+
+/// 校验配置、建立动态 Provider 注册表并完成默认管理员幂等初始化。
+///
+/// # Errors
+///
+/// 配置非法、Provider 注册冲突/缺失或默认管理员初始化失败时返回错误。
+pub async fn initialize(
+    mut config: AdminConfig,
+    store: AdminStorePorts,
+    providers: Vec<Arc<dyn ProviderAdmin>>,
+    snapshot: Arc<dyn SnapshotControl>,
+    probe: Arc<dyn AccountProbe>,
+    client_distribution: Arc<dyn ClientDistributionResolver>,
+    system: Arc<dyn SystemOperations>,
+) -> Result<AdminBundle, AdminError> {
+    config
+        .resolve_and_validate(Path::new("."))
+        .map_err(|error| AdminError::invalid(error.to_string()))?;
+    let registry = ProviderAdminRegistry::new(providers).map_err(map_provider_registry_error)?;
+    let openai = registry
+        .require(&provider_kind(OPENAI_PROVIDER_KIND)?)
+        .map_err(map_provider_registry_error)?;
+    let xai = registry
+        .require(&provider_kind(XAI_PROVIDER_KIND)?)
+        .map_err(map_provider_registry_error)?;
+
+    let auth = Arc::new(DefaultAuthService::new(
+        config.default_username,
+        config.session_ttl_minutes,
+        store.auth(),
+    ));
+    auth.ensure_default_admin(config.default_password.expose())
+        .await?;
+
+    let accounts = Arc::new(DefaultAccountsService::new(
+        store.accounts(),
+        store.account_runtime(),
+        registry.clone(),
+        snapshot.clone(),
+        probe.clone(),
+    ));
+    let backup_ports = store.backup();
+    let backups = Arc::new(DefaultBackupService::new(
+        backup_ports.repository(),
+        backup_ports.object_store(),
+        store.auth(),
+        snapshot.clone(),
+    ));
+    let backup_task = backup::task::BackupTask::new(
+        backup_ports.repository(),
+        backup_ports.dump(),
+        backup_ports.object_store(),
+    );
+    let services = AdminServices {
+        auth,
+        accounts,
+        account_groups: Arc::new(DefaultAccountGroupService::new(
+            store.account_groups(),
+            store.account_runtime(),
+            snapshot.clone(),
+        )),
+        client_keys: Arc::new(DefaultClientKeyService::new(
+            store.client_keys(),
+            snapshot.clone(),
+        )),
+        client_distribution: Arc::new(DefaultClientDistributionService::new(client_distribution)),
+        observability: Arc::new(DefaultObservabilityService::new(
+            store.observability(),
+            store.accounts(),
+            store.settings(),
+            registry,
+        )),
+        settings: Arc::new(DefaultSettingsService::new(
+            store.settings(),
+            snapshot.clone(),
+        )),
+        system: Arc::new(DefaultSystemService::new(system)),
+        openai: Arc::new(DefaultOpenAiService::new(
+            openai,
+            store.accounts(),
+            snapshot.clone(),
+        )),
+        xai: Arc::new(DefaultXaiService::new(
+            xai,
+            store.accounts(),
+            snapshot.clone(),
+        )),
+        backups,
+    };
+    let worker_contributions = backup_worker_contribution(backup_task)?;
+    Ok(AdminBundle {
+        services,
+        worker_contributions,
+    })
+}
+
+/// Backup Worker 注册：单个可取消 Daemon，owner 固定为 `backup`。
+fn backup_worker_contribution(
+    task: backup::task::BackupTask,
+) -> Result<Vec<WorkerContribution>, AdminError> {
+    let id = WorkerId::try_new(WorkerKind::Backup, BACKUP_WORKER_OWNER)
+        .map_err(|_| AdminError::internal("备份 Worker ID 不合法"))?;
+    let restart = DaemonRestartPolicy::try_new(Duration::from_secs(1), Duration::from_secs(60))
+        .map_err(|_| AdminError::internal("备份 Worker 重启策略不合法"))?;
+    let registration = WorkerRegistration::try_new(
+        id,
+        WorkerRunnable::Daemon {
+            restart,
+            task: Box::new(task),
+        },
+    )
+    .map_err(|_| AdminError::internal("备份 Worker 注册信息不合法"))?;
+    Ok(vec![WorkerContribution::Registration(registration)])
+}
+
+fn provider_kind(value: &'static str) -> Result<ProviderKind, AdminError> {
+    ProviderKind::new(value).map_err(|_| AdminError::internal("内置 Provider 类型不合法"))
+}
+
+fn map_provider_registry_error(error: ProviderAdminError) -> AdminError {
+    let kind = match error.kind() {
+        ProviderAdminErrorKind::Invalid | ProviderAdminErrorKind::Unsupported => {
+            AdminErrorKind::Invalid
+        }
+        ProviderAdminErrorKind::NotFound => AdminErrorKind::NotFound,
+        ProviderAdminErrorKind::Conflict => AdminErrorKind::Conflict,
+        ProviderAdminErrorKind::Ambiguous => AdminErrorKind::UpstreamResultUnknown,
+        ProviderAdminErrorKind::Unavailable | ProviderAdminErrorKind::CredentialRefreshRequired => {
+            AdminErrorKind::Unavailable
+        }
+        ProviderAdminErrorKind::BadGateway => AdminErrorKind::BadGateway,
+        ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
+    };
+    AdminError::new(kind, "Provider 注册表初始化失败")
+}

backend/crates/gateway-admin/src/model/account_groups.rs

@@ -0,0 +1,152 @@
+//! Provider-neutral account group commands and projections.
+
+use std::collections::BTreeMap;
+
+use chrono::{DateTime, Utc};
+use gateway_core::{account::AccountStatusFacts, routing::AccountGroupId};
+
+use super::{PageSize, Revision, observability::DecimalAmount};
+
+/// Canonical `#RRGGBBAA` color persisted with an account group.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupColor(String);
+
+impl AccountGroupColor {
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    #[must_use]
+    pub fn parse(value: &str) -> Option<Self> {
+        (value.len() == 9
+            && value.starts_with('#')
+            && value[1..].bytes().all(|byte| byte.is_ascii_hexdigit()))
+        .then(|| Self(value.to_ascii_uppercase()))
+    }
+}
+
+/// Group member availability at the current observation time.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AccountGroupAccountSummary {
+    pub available: u64,
+    pub limited: u64,
+    pub total: u64,
+}
+
+/// Group scheduling slots derived from available accounts and runtime leases.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AccountGroupCapacity {
+    pub used_slots: Option<u64>,
+    pub total_slots: u64,
+}
+
+/// Successful, downstream-committed USD request costs for group accounts.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupUsage {
+    pub today_usd: DecimalAmount,
+    /// 当前 usage retention 窗口内、按请求发生时 routing group 快照归属的累计成本。
+    pub retained_total_usd: DecimalAmount,
+}
+
+/// 当前页账号组 membership 对应的持久账号事实；运行态在 Admin query service 合并。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupMemberFact {
+    pub group_id: AccountGroupId,
+    pub account_id: String,
+    pub status: AccountStatusFacts,
+    pub total_slots: u64,
+}
+
+/// Lightweight group reference embedded in account and client-key views.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupRef {
+    pub id: AccountGroupId,
+    pub name: String,
+    pub color: AccountGroupColor,
+    pub enabled: bool,
+}
+
+/// Account group list query.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupListQuery {
+    pub page: u32,
+    pub page_size: PageSize,
+    pub search: Option<String>,
+    pub enabled: Option<bool>,
+}
+
+/// Complete account group summary.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupRecord {
+    pub id: AccountGroupId,
+    pub name: String,
+    pub description: Option<String>,
+    pub color: AccountGroupColor,
+    pub enabled: bool,
+    pub member_count: u64,
+    pub provider_counts: BTreeMap<String, u64>,
+    pub client_key_count: u64,
+    pub account_summary: AccountGroupAccountSummary,
+    pub capacity: AccountGroupCapacity,
+    pub usage: AccountGroupUsage,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// Paginated account groups.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupPage {
+    pub config_revision: Revision,
+    pub items: Vec<AccountGroupRecord>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+/// Create an account group.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CreateAccountGroup {
+    pub name: String,
+    pub description: Option<String>,
+    pub color: AccountGroupColor,
+}
+
+/// Store-ready create command with a generated stable ID.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NewAccountGroup {
+    pub id: AccountGroupId,
+    pub name: String,
+    pub description: Option<String>,
+    pub color: AccountGroupColor,
+}
+
+/// Update an account group's descriptive fields.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateAccountGroup {
+    pub id: AccountGroupId,
+    pub name: String,
+    pub description: Option<String>,
+    pub color: AccountGroupColor,
+}
+
+/// Enable or disable an account group.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SetAccountGroupEnabled {
+    pub id: AccountGroupId,
+    pub enabled: bool,
+}
+
+/// Delete an account group that is not referenced by a client key.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeleteAccountGroup {
+    pub id: AccountGroupId,
+}
+
+/// Result of any account-group mutation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupMutation {
+    pub config_revision: Revision,
+    pub id: AccountGroupId,
+    pub record: Option<AccountGroupRecord>,
+}

backend/crates/gateway-admin/src/model/accounts.rs

@@ -0,0 +1,277 @@
+//! 多 Provider 账号目录与连接测试的公共事实。
+
+use std::{collections::BTreeMap, pin::Pin};
+
+use chrono::{DateTime, Utc};
+use futures::Stream;
+
+use gateway_core::{
+    engine::probe::AccountProbeErrorSource, error::GatewayErrorKind, routing::ProviderKind,
+    upstream::UpstreamSendState,
+};
+
+use super::{PageSize, Revision, account_groups::AccountGroupRef, observability::TimeRange};
+
+pub use gateway_core::account::{
+    AccountConcurrencyLimit, AccountErrorReason, AccountStatus, AccountStatusFacts,
+    AccountStatusProjection, AccountWeight, CredentialState, QuotaAccessState, QuotaEvidence,
+    QuotaState, resolve_account_status,
+};
+
+/// 账号列表排序字段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccountSortField {
+    Email,
+    Status,
+    PlanType,
+    Usage,
+    LastUsedAt,
+    ExpiresAt,
+}
+
+/// 账号列表排序方向。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SortDirection {
+    Asc,
+    Desc,
+}
+
+/// 一组完整的账号排序规则。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AccountSort {
+    pub field: AccountSortField,
+    pub direction: SortDirection,
+}
+
+/// 账号列表的存储查询条件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountListQuery {
+    pub page: u32,
+    pub page_size: PageSize,
+    pub provider_kind: Option<ProviderKind>,
+    pub group_filter: Option<AccountGroupFilter>,
+    pub search: Option<String>,
+    pub status: Option<AccountStatus>,
+    pub sort: Option<AccountSort>,
+}
+
+/// Admin query service 从运行态存储取得的当前账号冷却快照。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AccountRuntimeSnapshot {
+    pub rate_limited_until: BTreeMap<String, DateTime<Utc>>,
+    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零。
+    pub in_flight: Option<BTreeMap<String, u64>>,
+}
+
+/// Optional account membership filter.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AccountGroupFilter {
+    Group(gateway_core::routing::AccountGroupId),
+    Ungrouped,
+}
+
+/// 账号公共存储投影；Provider 专属字段不进入此结构。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountRecord {
+    pub id: String,
+    pub provider_kind: ProviderKind,
+    pub groups: Vec<AccountGroupRef>,
+    pub name: String,
+    pub email: Option<String>,
+    pub upstream_user_id: Option<String>,
+    pub upstream_account_id: Option<String>,
+    pub plan_type: Option<String>,
+    pub authentication_kind: String,
+    pub credential_revision: Revision,
+    pub has_refresh_token: bool,
+    pub access_token_expires_at: Option<DateTime<Utc>>,
+    pub next_refresh_at: Option<DateTime<Utc>>,
+    pub enabled: bool,
+    pub concurrency_limit: Option<AccountConcurrencyLimit>,
+    pub weight: AccountWeight,
+    pub credential_state: CredentialState,
+    pub credential_observed_at: DateTime<Utc>,
+    pub quota: QuotaState,
+    pub last_error_reason: Option<AccountErrorReason>,
+    pub last_error_message: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// 单一货币的账号成本聚合。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountCost {
+    pub currency: String,
+    pub amount: super::observability::DecimalAmount,
+}
+
+/// 账号在一个模型上的历史用量。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountModelUsage {
+    pub model: String,
+    pub request_count: u64,
+    pub success_count: u64,
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+    pub cached_tokens: Option<u64>,
+    pub cache_write_tokens: Option<u64>,
+    pub reasoning_tokens: Option<u64>,
+    pub image_input_tokens: Option<u64>,
+    pub image_output_tokens: Option<u64>,
+    pub image_request_count: u64,
+    pub image_request_failed_count: u64,
+    pub total_tokens: Option<u64>,
+    pub cost_coverage: super::observability::CostCoverage,
+    pub costs: Vec<AccountCost>,
+    pub last_used_at: DateTime<Utc>,
+}
+
+/// 账号在一个小时窗口内的请求数。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountRequestBucket {
+    pub bucket_start: DateTime<Utc>,
+    pub request_count: u64,
+}
+
+/// 账号历史用量聚合。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountUsage {
+    pub account_id: String,
+    pub request_count: u64,
+    pub success_count: u64,
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+    pub cached_tokens: Option<u64>,
+    pub cache_write_tokens: Option<u64>,
+    pub reasoning_tokens: Option<u64>,
+    pub image_input_tokens: Option<u64>,
+    pub image_output_tokens: Option<u64>,
+    pub image_request_count: u64,
+    pub image_request_failed_count: u64,
+    pub total_tokens: Option<u64>,
+    pub cost_coverage: super::observability::CostCoverage,
+    pub costs: Vec<AccountCost>,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub request_buckets: Vec<AccountRequestBucket>,
+    pub models: Vec<AccountModelUsage>,
+}
+
+/// 某个账号在调用方指定时间窗口内的本地用量查询。
+///
+/// `key` 只用于把聚合结果关联回调用方的窗口，不承载 Provider 私有语义。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountUsageWindowQuery {
+    pub account_id: String,
+    pub key: String,
+    pub range: TimeRange,
+}
+
+/// 一个账号时间窗口用量查询的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountUsageWindowResult {
+    pub account_id: String,
+    pub key: String,
+    pub usage: AccountUsage,
+}
+
+/// 账号列表页所需的完整存储事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountPage {
+    pub config_revision: Revision,
+    pub items: Vec<AccountPageItem>,
+    pub total: u64,
+    pub summary: AccountSummary,
+}
+
+/// 同一状态快照下的账号事实与唯一状态投影。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountPageItem {
+    pub account: AccountRecord,
+    pub projection: AccountStatusProjection,
+}
+
+/// 统一账号目录的全局状态计数，不受当前筛选和分页影响。
+///
+/// 计数与 [`AccountStatus`] 一一对应，由 store 按派生状态聚合。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AccountSummary {
+    pub total: u64,
+    pub normal: u64,
+    pub quota_exhausted: u64,
+    pub rate_limited: u64,
+    pub disabled: u64,
+    pub error: u64,
+}
+
+/// 账号可编辑事实的一次性替换命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateAccount {
+    pub account_id: String,
+    pub enabled: bool,
+    pub concurrency_limit: Option<AccountConcurrencyLimit>,
+    pub weight: AccountWeight,
+    pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
+}
+
+/// 账号更新结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountUpdateResult {
+    pub config_revision: Revision,
+    pub account_id: gateway_core::account::ProviderAccountId,
+}
+
+/// 一批账号可编辑事实的一次性替换命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BatchUpdateAccounts {
+    pub account_ids: Vec<String>,
+    pub enabled: bool,
+    pub concurrency_limit: Option<AccountConcurrencyLimit>,
+    pub weight: AccountWeight,
+    pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
+}
+
+/// 批量账号更新结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountsUpdateResult {
+    pub config_revision: Revision,
+    pub account_ids: Vec<gateway_core::account::ProviderAccountId>,
+}
+
+/// 账号批量删除命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeleteAccounts {
+    pub account_ids: Vec<String>,
+}
+
+/// 账号连接测试的语义事件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AccountConnectionTestEvent {
+    Started {
+        model: String,
+    },
+    Request {
+        model: String,
+        input_text: String,
+        stream: bool,
+        store: bool,
+    },
+    Content {
+        text: String,
+    },
+    Completed,
+    Failed {
+        source: AccountProbeErrorSource,
+        gateway_error_code: GatewayErrorKind,
+        send_state: Option<UpstreamSendState>,
+        message: String,
+        provider_error_code: Option<String>,
+        provider_error_type: Option<String>,
+        upstream_status: Option<u16>,
+        upstream_content_type: Option<String>,
+        upstream_body: Option<String>,
+    },
+}
+
+/// 每次连接测试独占的有限事件流。
+pub type AccountConnectionTestEventStream =
+    Pin<Box<dyn Stream<Item = AccountConnectionTestEvent> + Send + 'static>>;

backend/crates/gateway-admin/src/model/auth.rs

@@ -0,0 +1,106 @@
+//! 管理员认证、会话和安全审计事实。
+
+use chrono::{DateTime, Utc};
+
+use super::{MutationActor, MutationContext, Revision};
+
+/// 会话审计使用的稳定管理员标识。
+#[must_use]
+pub fn admin_session_actor_ref(admin_user_id: &str) -> String {
+    format!("admin:{admin_user_id}")
+}
+
+/// 已认证的管理主体。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AdminPrincipal {
+    Session { admin_user_id: String },
+    ApiKey,
+}
+
+/// 传给管理用例的安全请求上下文。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdminRequestContext {
+    pub principal: AdminPrincipal,
+    pub request_id: String,
+}
+
+impl AdminRequestContext {
+    #[must_use]
+    pub fn mutation_context(&self) -> MutationContext {
+        let actor = match &self.principal {
+            AdminPrincipal::Session { admin_user_id } => MutationActor::AdminSession {
+                admin_user_id: admin_user_id.clone(),
+            },
+            AdminPrincipal::ApiKey => MutationActor::AdminApiKey,
+        };
+        MutationContext {
+            actor,
+            request_id: self.request_id.clone(),
+        }
+    }
+}
+
+/// 管理员登录命令。
+#[derive(Clone, PartialEq, Eq)]
+pub struct LoginCommand {
+    pub username: Option<String>,
+    pub password: String,
+}
+
+impl std::fmt::Debug for LoginCommand {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("LoginCommand")
+            .field("username", &self.username)
+            .field("password", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// 登录成功后返回的会话事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LoginResult {
+    pub session_id: String,
+    pub expires_at: DateTime<Utc>,
+}
+
+/// 登录状态机可被 API 精确映射的失败类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum LoginError {
+    #[error("invalid administrator credentials")]
+    InvalidCredentials,
+    #[error("administrator authentication is unavailable")]
+    Unavailable,
+}
+
+/// Redis 中可恢复的管理员会话。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdminSession {
+    pub admin_user_id: String,
+    pub expires_at: DateTime<Utc>,
+}
+
+/// 安全审计事件类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AuditActorKind {
+    AdminSession,
+    AdminApiKey,
+    System,
+    Anonymous,
+}
+
+/// 管理写操作留下的最小审计事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdminAuditEvent {
+    pub id: String,
+    pub actor_kind: AuditActorKind,
+    pub actor_admin_user_id: Option<String>,
+    pub actor_ref: String,
+    pub request_id: Option<String>,
+    pub action: String,
+    pub entity_kind: String,
+    pub entity_ref: String,
+    pub config_revision: Option<Revision>,
+    pub changed_fields: Vec<String>,
+    pub occurred_at: DateTime<Utc>,
+}

backend/crates/gateway-admin/src/model/backup/code.rs

@@ -0,0 +1,34 @@
+//! 备份领域的稳定错误码。
+
+/// 配置或参数非法。
+pub const INVALID_CONFIG: &str = "backup.invalid_config";
+/// Cron 表达式非法。
+pub const INVALID_CRON: &str = "backup.invalid_cron";
+/// IANA 时区非法。
+pub const INVALID_TIMEZONE: &str = "backup.invalid_timezone";
+/// 记录不存在。
+pub const RECORD_NOT_FOUND: &str = "backup.record_not_found";
+/// 已存在活跃任务，拒绝创建。
+pub const ACTIVE_TASK_CONFLICT: &str = "backup.active_task_conflict";
+/// 记录状态与期望不符，无法迁移。
+pub const STATE_CONFLICT: &str = "backup.state_conflict";
+/// 已有记录时禁止切换存储目标。
+pub const STORAGE_IDENTITY_LOCKED: &str = "backup.storage_identity_locked";
+/// `pg_dump` 非零退出或失败。
+pub const PG_DUMP_FAILED: &str = "backup.pg_dump_failed";
+/// 暂存磁盘空间不足。
+pub const STAGING_SPACE_EXHAUSTED: &str = "backup.staging_space_exhausted";
+/// S3 认证失败。
+pub const S3_AUTH_FAILED: &str = "backup.s3_auth_failed";
+/// S3 权限拒绝。
+pub const S3_PERMISSION_DENIED: &str = "backup.s3_permission_denied";
+/// S3 上传失败。
+pub const S3_UPLOAD_FAILED: &str = "backup.s3_upload_failed";
+/// 远端对象校验失败。
+pub const REMOTE_VERIFICATION_FAILED: &str = "backup.remote_verification_failed";
+/// 任务被取消。
+pub const CANCELLED: &str = "backup.cancelled";
+/// 仓储或对象存储暂不可用。
+pub const STORE_UNAVAILABLE: &str = "backup.store_unavailable";
+/// 上游 S3 服务返回无效或失败响应。
+pub const UPSTREAM_FAILURE: &str = "backup.upstream_failure";

backend/crates/gateway-admin/src/model/backup/mod.rs

@@ -0,0 +1,533 @@
+//! S3 备份领域模型、状态机与稳定错误。
+//!
+//! 领域类型只携带事实，不承载基础设施细节。Secret 使用 [`secrecy::SecretString`]，
+//! 全流程不实现 `Serialize`，避免被错误地写入 wire 或日志。管理员身份等审计事实
+//! 只存在于 `admin_audit_events`，本模型不重复保存。
+
+use std::fmt;
+
+use chrono::{DateTime, Utc};
+use secrecy::SecretString;
+use uuid::Uuid;
+
+use super::PageSize;
+
+/// 备份触发来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BackupTriggerKind {
+    Manual,
+    Scheduled,
+}
+
+impl BackupTriggerKind {
+    /// 稳定持久化值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Manual => "manual",
+            Self::Scheduled => "scheduled",
+        }
+    }
+
+    /// 解析持久化值。
+    #[must_use]
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "manual" => Some(Self::Manual),
+            "scheduled" => Some(Self::Scheduled),
+            _ => None,
+        }
+    }
+}
+
+impl fmt::Display for BackupTriggerKind {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(self.as_str())
+    }
+}
+
+/// 备份任务状态机（六状态）。
+///
+/// 迁移 `backup_records_lifecycle_ck` 与字段空值语义共同定义合法持久化行；
+/// [`Self::allows_transition_to`] 只约束领域内的显式状态迁移，两层都必须满足。
+/// 删除成功后记录行被硬删除，因此不存在 `deleted` 终态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum BackupStatus {
+    Queued,
+    Dumping,
+    Uploading,
+    Completed,
+    Failed,
+    Deleting,
+}
+
+impl BackupStatus {
+    /// 稳定持久化值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Queued => "queued",
+            Self::Dumping => "dumping",
+            Self::Uploading => "uploading",
+            Self::Completed => "completed",
+            Self::Failed => "failed",
+            Self::Deleting => "deleting",
+        }
+    }
+
+    /// 解析持久化值。
+    #[must_use]
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "queued" => Some(Self::Queued),
+            "dumping" => Some(Self::Dumping),
+            "uploading" => Some(Self::Uploading),
+            "completed" => Some(Self::Completed),
+            "failed" => Some(Self::Failed),
+            "deleting" => Some(Self::Deleting),
+            _ => None,
+        }
+    }
+
+    /// 该状态是否消耗全局活跃名额。
+    #[must_use]
+    pub const fn is_active(self) -> bool {
+        matches!(self, Self::Queued | Self::Dumping | Self::Uploading)
+    }
+
+    /// 该状态是否允许进入删除流程。
+    #[must_use]
+    pub const fn can_be_deleted(self) -> bool {
+        matches!(self, Self::Completed | Self::Failed)
+    }
+
+    /// 领域内允许的显式迁移。
+    #[must_use]
+    pub fn allows_transition_to(self, target: BackupStatus) -> bool {
+        matches!(
+            (self, target),
+            (Self::Queued, Self::Dumping)
+                | (Self::Queued, Self::Failed)
+                | (Self::Dumping, Self::Uploading)
+                | (Self::Dumping, Self::Failed)
+                | (Self::Uploading, Self::Completed)
+                | (Self::Uploading, Self::Failed)
+                | (Self::Completed, Self::Deleting)
+                | (Self::Failed, Self::Deleting)
+        )
+    }
+}
+
+impl fmt::Display for BackupStatus {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(self.as_str())
+    }
+}
+
+/// S3 存储配置更新命令；`secret_access_key` 为 `None` 表示保留旧值。
+#[derive(Clone)]
+pub struct UpdateBackupStorageCommand {
+    pub endpoint: String,
+    pub region: String,
+    pub bucket: String,
+    pub access_key_id: String,
+    pub secret_access_key: Option<SecretString>,
+    pub prefix: String,
+    pub force_path_style: bool,
+}
+
+impl fmt::Debug for UpdateBackupStorageCommand {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("UpdateBackupStorageCommand")
+            .field("endpoint", &self.endpoint)
+            .field("region", &self.region)
+            .field("bucket", &self.bucket)
+            .field("access_key_id", &self.access_key_id)
+            .field("secret_access_key", &self.secret_access_key.is_some())
+            .field("prefix", &self.prefix)
+            .field("force_path_style", &self.force_path_style)
+            .finish()
+    }
+}
+
+/// 调度配置更新命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateBackupScheduleCommand {
+    pub schedule_enabled: bool,
+    pub cron_expression: String,
+    pub schedule_timezone: String,
+    pub retention_days: u32,
+    pub retention_count: u32,
+}
+
+/// 完整保存的备份设置（含 Secret）。
+///
+/// 只从仓储读取；不实现 `Serialize`，防止 Secret 进入 wire 或日志。
+#[derive(Clone)]
+pub struct BackupSettings {
+    pub storage_revision: u64,
+    pub endpoint: Option<String>,
+    pub region: Option<String>,
+    pub bucket: Option<String>,
+    pub access_key_id: Option<String>,
+    pub secret_access_key: Option<SecretString>,
+    pub prefix: Option<String>,
+    pub force_path_style: bool,
+    pub schedule_enabled: bool,
+    pub cron_expression: Option<String>,
+    pub schedule_timezone: Option<String>,
+    pub retention_days: u32,
+    pub retention_count: u32,
+    pub next_run_at: Option<DateTime<Utc>>,
+    pub last_verified_at: Option<DateTime<Utc>>,
+    pub updated_at: DateTime<Utc>,
+}
+
+impl fmt::Debug for BackupSettings {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("BackupSettings")
+            .field("storage_revision", &self.storage_revision)
+            .field("endpoint", &self.endpoint)
+            .field("region", &self.region)
+            .field("bucket", &self.bucket)
+            .field("access_key_id", &self.access_key_id)
+            .field("secret_access_key", &self.secret_access_key.is_some())
+            .field("prefix", &self.prefix)
+            .field("force_path_style", &self.force_path_style)
+            .field("schedule_enabled", &self.schedule_enabled)
+            .field("cron_expression", &self.cron_expression)
+            .field("schedule_timezone", &self.schedule_timezone)
+            .field("retention_days", &self.retention_days)
+            .field("retention_count", &self.retention_count)
+            .field("next_run_at", &self.next_run_at)
+            .field("last_verified_at", &self.last_verified_at)
+            .field("updated_at", &self.updated_at)
+            .finish()
+    }
+}
+
+impl BackupSettings {
+    /// S3 存储配置是否完整（bucket/region/密钥/前缀齐全）。
+    #[must_use]
+    pub fn storage_configured(&self) -> bool {
+        self.endpoint.is_some()
+            && self.region.is_some()
+            && self.bucket.is_some()
+            && self.access_key_id.is_some()
+            && self.secret_access_key.is_some()
+            && self.prefix.is_some()
+    }
+
+    /// 探测是否已对当前 revision 成功；`last_verified_at` 非空即表示当前配置已通过探针。
+    #[must_use]
+    pub fn storage_verified(&self) -> bool {
+        self.last_verified_at.is_some()
+    }
+}
+
+/// 已经校验并可用于对象存储操作的存储配置快照。
+#[derive(Clone)]
+pub struct BackupStorageConfig {
+    pub storage_revision: u64,
+    pub endpoint: String,
+    pub region: String,
+    pub bucket: String,
+    pub access_key_id: String,
+    pub secret_access_key: SecretString,
+    pub prefix: String,
+    pub force_path_style: bool,
+}
+
+impl fmt::Debug for BackupStorageConfig {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("BackupStorageConfig")
+            .field("storage_revision", &self.storage_revision)
+            .field("endpoint", &self.endpoint)
+            .field("region", &self.region)
+            .field("bucket", &self.bucket)
+            .field("access_key_id", &self.access_key_id)
+            .field("secret_access_key", &"[REDACTED]")
+            .field("prefix", &self.prefix)
+            .field("force_path_style", &self.force_path_style)
+            .finish()
+    }
+}
+
+impl BackupStorageConfig {
+    /// 从完整设置推导对象存储配置；设置不完整时返回 `None`。
+    #[must_use]
+    pub fn from_settings(settings: &BackupSettings) -> Option<Self> {
+        Some(Self {
+            storage_revision: settings.storage_revision,
+            endpoint: settings.endpoint.clone()?,
+            region: settings.region.clone()?,
+            bucket: settings.bucket.clone()?,
+            access_key_id: settings.access_key_id.clone()?,
+            secret_access_key: settings.secret_access_key.clone()?,
+            prefix: settings.prefix.clone()?,
+            force_path_style: settings.force_path_style,
+        })
+    }
+}
+
+/// 一条备份记录。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupRecord {
+    pub id: String,
+    pub trigger_kind: BackupTriggerKind,
+    pub status: BackupStatus,
+    pub scheduled_at: Option<DateTime<Utc>>,
+    pub object_key: String,
+    pub size_bytes: Option<u64>,
+    pub sha256: Option<String>,
+    pub attempt_count: u32,
+    pub error_code: Option<String>,
+    pub error_message: Option<String>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub completed_at: Option<DateTime<Utc>>,
+    /// 创建时确定的过期时间；手工和计划备份均可设置，到期自动清理。
+    pub expires_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// 备份记录分页查询。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupRecordListQuery {
+    pub page: u32,
+    pub page_size: PageSize,
+    pub status: Option<BackupStatus>,
+    pub trigger: Option<BackupTriggerKind>,
+}
+
+/// 备份记录分页结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupRecordPage {
+    pub items: Vec<BackupRecord>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: PageSize,
+}
+
+impl BackupRecordPage {
+    /// 计算总页数；空集合视为一页。
+    #[must_use]
+    pub fn total_pages(&self) -> u32 {
+        let size = u64::from(self.page_size.get());
+        if self.total == 0 {
+            1
+        } else {
+            self.total.div_ceil(size).min(u64::from(u32::MAX)) as u32
+        }
+    }
+}
+
+/// 创建备份任务的持久化数据；id 与对象 key 由领域生成。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupRecordSeed {
+    pub id: String,
+    pub trigger_kind: BackupTriggerKind,
+    pub scheduled_at: Option<DateTime<Utc>>,
+    pub object_key: String,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+/// 连接测试结果；只携带稳定阶段与脱敏消息。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConnectionTestResult {
+    pub ok: bool,
+    pub stage: &'static str,
+    pub code: Option<&'static str>,
+    pub message: String,
+}
+
+/// 对象存储探测阶段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConnectionTestStage {
+    PutObject,
+    HeadObject,
+    GetObject,
+    DeleteObject,
+}
+
+impl ConnectionTestStage {
+    /// 稳定 wire 值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::PutObject => "putObject",
+            Self::HeadObject => "headObject",
+            Self::GetObject => "getObject",
+            Self::DeleteObject => "deleteObject",
+        }
+    }
+}
+
+/// 上传到对象存储并期望远端校验的归档 metadata。
+///
+/// `size_bytes` 在上传时不写入 metadata，但 `HeadObject` 会返回远端大小，
+/// 用于与本地归档校验一致。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupObjectMetadata {
+    pub backup_id: String,
+    pub sha256: String,
+    pub created_at: DateTime<Utc>,
+    pub size_bytes: u64,
+}
+
+impl BackupObjectMetadata {
+    /// 构造上传 metadata。
+    #[must_use]
+    pub const fn new(
+        backup_id: String,
+        sha256: String,
+        created_at: DateTime<Utc>,
+        size_bytes: u64,
+    ) -> Self {
+        Self {
+            backup_id,
+            sha256,
+            created_at,
+            size_bytes,
+        }
+    }
+}
+
+/// 短时下载地址结果。
+#[derive(Clone, PartialEq, Eq)]
+pub struct DownloadUrlResult {
+    pub url: String,
+    pub file_name: String,
+    pub expires_in: std::time::Duration,
+}
+
+impl fmt::Debug for DownloadUrlResult {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("DownloadUrlResult")
+            .field("url", &"[REDACTED]")
+            .field("file_name", &self.file_name)
+            .field("expires_in", &self.expires_in)
+            .finish()
+    }
+}
+
+/// 备份基础设施错误：只携带稳定错误码与脱敏消息。
+///
+/// 该类型不构成第二套 kind 枚举；`gateway-admin` 边界统一映射为既有
+/// `AdminErrorKind`。稳定 `error_code` 同时用于任务记录、日志与 UI。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{message}")]
+pub struct BackupError {
+    code: &'static str,
+    message: String,
+}
+
+impl BackupError {
+    /// 构造基础设施错误。
+    #[must_use]
+    pub const fn new(code: &'static str, message: String) -> Self {
+        Self { code, message }
+    }
+
+    /// 稳定错误码，例如 `backup.s3_auth_failed`。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        self.code
+    }
+
+    /// 脱敏后的可操作消息。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+/// 构造稳定错误码常量。
+pub mod code;
+
+/// 构建对象 key：`{prefix}/YYYY/MM/DD/codex-proxy-rs_{UTC seconds}_{backup id}.dump`。
+///
+/// 规范化规则：prefix 不得为空、不得以前导 `/` 开头、不得包含 `..`、反斜杠或控制字符；
+/// 输出统一使用 `/` 分隔且不含空段。
+pub fn build_object_key(
+    prefix: &str,
+    backup_id: &str,
+    at: DateTime<Utc>,
+) -> Result<String, BackupError> {
+    let prefix = normalize_prefix(prefix)?;
+    Ok(format!(
+        "{prefix}/{}/{:02}/{:02}/codex-proxy-rs_{}_{}.dump",
+        at.format("%Y"),
+        at.format("%m"),
+        at.format("%d"),
+        at.format("%Y%m%d_%H%M%S"),
+        short_backup_id(backup_id),
+    ))
+}
+
+/// 下载文件名：`codex-proxy-rs_{短 id}.dump`，与对象 key 的文件名一致。
+#[must_use]
+pub fn build_download_file_name(backup_id: &str) -> String {
+    format!("codex-proxy-rs_{}.dump", short_backup_id(backup_id))
+}
+
+/// 截取备份 id 的可读短标识：去掉 `backup_` 前缀，最多保留 8 位 hex。
+#[must_use]
+fn short_backup_id(backup_id: &str) -> String {
+    let hex = backup_id.strip_prefix("backup_").unwrap_or(backup_id);
+    hex.get(..8).unwrap_or(hex).to_owned()
+}
+
+/// 规范化并校验对象 prefix。
+///
+/// 返回去掉尾部 `/` 的规范 prefix；空串、前导 `/`、`..` 段、反斜杠和控制字符均拒绝。
+pub fn normalize_prefix(prefix: &str) -> Result<String, BackupError> {
+    if prefix.is_empty() || prefix.starts_with('/') {
+        return Err(BackupError::new(
+            code::INVALID_CONFIG,
+            "存储对象前缀必须非空且不能以前导 / 开头".to_owned(),
+        ));
+    }
+    if prefix.bytes().any(|byte| byte.is_ascii_control()) || prefix.contains('\\') {
+        return Err(BackupError::new(
+            code::INVALID_CONFIG,
+            "存储对象前缀包含非法字符".to_owned(),
+        ));
+    }
+    if prefix.split('/').any(|segment| segment == "..") {
+        return Err(BackupError::new(
+            code::INVALID_CONFIG,
+            "存储对象前缀不能包含 .. 路径段".to_owned(),
+        ));
+    }
+    Ok(prefix.trim_end_matches('/').to_owned())
+}
+
+/// 生成新的备份记录 id。
+#[must_use]
+pub fn new_backup_id() -> String {
+    format!("backup_{}", Uuid::now_v7().simple())
+}
+
+/// 从触发类型与计划时间构造可持久化 seed；id 与对象 key 一次生成保持一致。
+pub fn build_backup_seed(
+    trigger_kind: BackupTriggerKind,
+    scheduled_at: Option<DateTime<Utc>>,
+    prefix: &str,
+    at: DateTime<Utc>,
+    expires_at: Option<DateTime<Utc>>,
+) -> Result<BackupRecordSeed, BackupError> {
+    let id = new_backup_id();
+    let object_key = build_object_key(prefix, &id, at)?;
+    Ok(BackupRecordSeed {
+        id,
+        trigger_kind,
+        scheduled_at,
+        object_key,
+        expires_at,
+    })
+}

backend/crates/gateway-admin/src/model/client_distribution.rs

@@ -0,0 +1,58 @@
+//! 管理设置页使用的 Codex 客户端下载信息。
+
+use chrono::{DateTime, Utc};
+
+/// Windows 安装包架构。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum ClientArchitecture {
+    X64,
+    Arm64,
+}
+
+impl ClientArchitecture {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::X64 => "x64",
+            Self::Arm64 => "arm64",
+        }
+    }
+}
+
+/// 下载地址的可信来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientDownloadSource {
+    MicrosoftStore,
+    OfficialOpenAi,
+}
+
+impl ClientDownloadSource {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::MicrosoftStore => "microsoft_store",
+            Self::OfficialOpenAi => "official_openai",
+        }
+    }
+}
+
+/// 一个已经过 Host 校验、可以直接交给浏览器下载的安装包。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientDownloadPackage {
+    pub architecture: ClientArchitecture,
+    pub source: ClientDownloadSource,
+    pub version: Option<String>,
+    pub file_name: String,
+    pub size_bytes: Option<u64>,
+    pub download_url: String,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+/// Codex Desktop Windows 下载解析结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CodexDesktopWindowsDownloads {
+    pub resolved_at: DateTime<Utc>,
+    pub cached: bool,
+    pub warning: Option<String>,
+    pub packages: Vec<ClientDownloadPackage>,
+}

backend/crates/gateway-admin/src/model/client_keys.rs

@@ -0,0 +1,219 @@
+//! Client API Key 的 Command、Result 与安全秘密类型。
+
+use std::{fmt, num::NonZeroU16};
+
+use chrono::{DateTime, Utc};
+
+use gateway_core::{
+    policy::{ClientApiKeyId, RateLimits},
+    routing::{AccountGroupId, ProviderKind},
+};
+
+use super::{AdminModelError, Revision, account_groups::AccountGroupRef};
+
+/// Client Key 列表保持旧 HTTP 合同允许的完整非零 `u16` 页大小。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct ClientKeyPageSize(NonZeroU16);
+
+impl ClientKeyPageSize {
+    /// 创建 1 至 65535 的 Client Key 页大小。
+    ///
+    /// # Errors
+    ///
+    /// `value` 为零时返回 [`AdminModelError::InvalidClientKeyPageSize`]。
+    pub fn new(value: u16) -> Result<Self, AdminModelError> {
+        NonZeroU16::new(value)
+            .map(Self)
+            .ok_or(AdminModelError::InvalidClientKeyPageSize)
+    }
+
+    #[must_use]
+    pub const fn get(self) -> u16 {
+        self.0.get()
+    }
+}
+
+/// Client Key 列表排序字段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientKeySortField {
+    Name,
+    Enabled,
+    CreatedAt,
+    LastUsedAt,
+}
+
+/// Client Key 列表排序方向。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SortDirection {
+    Asc,
+    Desc,
+}
+
+/// Client Key 列表排序规则。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ClientKeySort {
+    pub field: ClientKeySortField,
+    pub direction: SortDirection,
+}
+
+/// 与排序字段绑定的游标值。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ClientKeyCursorValue {
+    Name(String),
+    Enabled(bool),
+    CreatedAt(DateTime<Utc>),
+    LastUsedAt(Option<DateTime<Utc>>),
+}
+
+/// Client Key 的稳定键集游标。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyCursor {
+    pub sort: ClientKeySort,
+    pub value: ClientKeyCursorValue,
+    pub id: ClientApiKeyId,
+}
+
+/// Client Key 列表查询。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyListQuery {
+    pub cursor: Option<ClientKeyCursor>,
+    pub page_size: ClientKeyPageSize,
+    pub search: Option<String>,
+    pub sort: ClientKeySort,
+}
+
+/// 不含完整明文 Key 的管理投影。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyRecord {
+    pub id: ClientApiKeyId,
+    pub name: String,
+    pub label: Option<String>,
+    pub groups: Vec<AccountGroupRef>,
+    pub provider_kinds: Vec<ProviderKind>,
+    pub prefix: String,
+    pub enabled: bool,
+    pub limits: RateLimits,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// Client Key 列表页。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyPage {
+    pub config_revision: Revision,
+    pub items: Vec<ClientKeyRecord>,
+    pub total: u64,
+    pub next_cursor: Option<ClientKeyCursor>,
+}
+
+/// 仅在创建或显式 reveal 时跨越管理边界的明文 Key。
+#[derive(Clone, PartialEq, Eq)]
+pub struct ClientKeySecret {
+    pub record: ClientKeyRecord,
+    plaintext: String,
+}
+
+impl ClientKeySecret {
+    #[must_use]
+    pub fn new(record: ClientKeyRecord, plaintext: impl Into<String>) -> Self {
+        Self {
+            record,
+            plaintext: plaintext.into(),
+        }
+    }
+
+    #[must_use]
+    pub fn expose_for_response(&self) -> &str {
+        &self.plaintext
+    }
+}
+
+impl fmt::Debug for ClientKeySecret {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ClientKeySecret")
+            .field("record", &self.record)
+            .field("plaintext", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// API 提交的 Client Key 创建命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CreateClientKey {
+    pub name: String,
+    pub label: Option<String>,
+    pub group_ids: Vec<AccountGroupId>,
+    pub limits: RateLimits,
+}
+
+/// 管理用例生成 ID 与明文后的持久化命令。
+#[derive(Clone, PartialEq, Eq)]
+pub struct NewClientKey {
+    pub id: ClientApiKeyId,
+    pub name: String,
+    pub label: Option<String>,
+    pub group_ids: Vec<AccountGroupId>,
+    pub limits: RateLimits,
+    pub plaintext: String,
+}
+
+impl fmt::Debug for NewClientKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("NewClientKey")
+            .field("id", &self.id)
+            .field("name", &self.name)
+            .field("group_ids", &self.group_ids)
+            .field("plaintext", &"[REDACTED]")
+            .finish_non_exhaustive()
+    }
+}
+
+/// 修改 Client Key 的公开策略字段。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateClientKey {
+    pub id: ClientApiKeyId,
+    pub name: String,
+    pub label: Option<String>,
+    pub group_ids: Vec<AccountGroupId>,
+    pub limits: RateLimits,
+}
+
+/// 修改 Client Key 启用状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SetClientKeyEnabled {
+    pub id: ClientApiKeyId,
+    pub enabled: bool,
+}
+
+/// 删除 Client Key。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeleteClientKey {
+    pub id: ClientApiKeyId,
+}
+
+/// Client Key 创建结果；完整明文仅存在于该一次性结果中。
+pub struct CreatedClientKey {
+    pub config_revision: Revision,
+    pub secret: ClientKeySecret,
+}
+
+impl fmt::Debug for CreatedClientKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("CreatedClientKey")
+            .field("config_revision", &self.config_revision)
+            .field("secret", &self.secret)
+            .finish()
+    }
+}
+
+/// Client Key 普通写操作结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyMutation {
+    pub config_revision: Revision,
+    pub record: Option<ClientKeyRecord>,
+    pub id: ClientApiKeyId,
+}

backend/crates/gateway-admin/src/model/mod.rs

@@ -0,0 +1,180 @@
+//! 管理控制面使用的 Command、Result 与稳定值对象。
+
+use std::num::{NonZeroU16, NonZeroU64};
+
+pub mod account_groups;
+pub mod accounts;
+pub mod auth;
+pub mod backup;
+pub mod client_distribution;
+pub mod client_keys;
+pub mod observability;
+pub mod provider_credentials;
+pub mod settings;
+pub mod system;
+
+/// 管理用例对外返回的稳定错误分类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AdminErrorKind {
+    Invalid,
+    Unauthorized,
+    NotFound,
+    Conflict,
+    RateLimited,
+    BadGateway,
+    UpstreamResultUnknown,
+    Unavailable,
+    Internal,
+}
+
+/// 不携带基础设施细节、可安全返回给管理员的管理用例错误。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{message}")]
+pub struct AdminError {
+    kind: AdminErrorKind,
+    message: String,
+}
+
+impl AdminError {
+    #[must_use]
+    pub fn new(kind: AdminErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+        }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> AdminErrorKind {
+        self.kind
+    }
+
+    /// 返回已脱敏、可公开给管理员的文案。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    #[must_use]
+    pub fn invalid(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Invalid, message)
+    }
+
+    #[must_use]
+    pub fn bad_request(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Invalid, message)
+    }
+
+    #[must_use]
+    pub fn not_found(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::NotFound, message)
+    }
+
+    #[must_use]
+    pub fn conflict(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Conflict, message)
+    }
+
+    #[must_use]
+    pub fn bad_gateway(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::BadGateway, message)
+    }
+
+    #[must_use]
+    pub fn upstream_result_unknown(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::UpstreamResultUnknown, message)
+    }
+
+    #[must_use]
+    pub fn unavailable(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Unavailable, message)
+    }
+
+    #[must_use]
+    pub fn internal(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Internal, message)
+    }
+}
+
+/// PostgreSQL 中所有正整数 revision 的管理层表示。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Revision(NonZeroU64);
+
+impl Revision {
+    /// 创建正整数 revision。
+    ///
+    /// # Errors
+    ///
+    /// `value` 为零时返回 [`AdminModelError::ZeroRevision`]。
+    pub fn new(value: u64) -> Result<Self, AdminModelError> {
+        NonZeroU64::new(value)
+            .map(Self)
+            .ok_or(AdminModelError::ZeroRevision)
+    }
+
+    #[must_use]
+    pub const fn get(self) -> u64 {
+        self.0.get()
+    }
+}
+
+/// 管理列表统一使用的受限页大小。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct PageSize(NonZeroU16);
+
+impl PageSize {
+    pub const MAX: u16 = 200;
+
+    /// 创建 1 至 200 的页大小。
+    ///
+    /// # Errors
+    ///
+    /// `value` 不在有效范围时返回 [`AdminModelError::InvalidPageSize`]。
+    pub fn new(value: u16) -> Result<Self, AdminModelError> {
+        if value > Self::MAX {
+            return Err(AdminModelError::InvalidPageSize(value));
+        }
+        NonZeroU16::new(value)
+            .map(Self)
+            .ok_or(AdminModelError::InvalidPageSize(value))
+    }
+
+    #[must_use]
+    pub const fn get(self) -> u16 {
+        self.0.get()
+    }
+}
+
+/// 可审计管理写操作的发起者。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum MutationActor {
+    AdminSession { admin_user_id: String },
+    AdminApiKey,
+    System,
+}
+
+/// 管理写操作必须携带的审计上下文。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MutationContext {
+    pub actor: MutationActor,
+    pub request_id: String,
+}
+
+/// 领域值对象构造失败。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum AdminModelError {
+    #[error("revision must be greater than zero")]
+    ZeroRevision,
+    #[error("page size {0} is outside 1..=200")]
+    InvalidPageSize(u16),
+    #[error("client key page size must be inside 1..=65535")]
+    InvalidClientKeyPageSize,
+    #[error("request outcome must be 1..=256 bytes without control characters")]
+    InvalidRequestOutcome,
+    #[error("time range must be positive and no longer than 366 days")]
+    InvalidTimeRange,
+    #[error("decimal amount is not a non-negative numeric(20,10) value")]
+    InvalidDecimalAmount,
+    #[error("latency percentile must be finite and non-negative")]
+    InvalidLatencyPercentile,
+}

backend/crates/gateway-admin/src/model/settings.rs

@@ -0,0 +1,100 @@
+//! Runtime settings 与明文管理员 API Key 的语义模型。
+
+use std::{collections::BTreeMap, fmt};
+
+use chrono::{DateTime, Utc};
+
+use gateway_core::routing::{PublicModelId, UpstreamModelId};
+
+use super::Revision;
+
+/// 客户端模型到上游模型的全局精确映射。
+pub type ModelMappings = BTreeMap<PublicModelId, UpstreamModelId>;
+
+/// 账号调度策略；由 Core 拥有稳定值与 wire 映射。
+pub use gateway_core::account::RotationStrategy;
+
+/// 完整运行设置事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RuntimeSettings {
+    pub config_revision: Revision,
+    pub model_mappings: ModelMappings,
+    pub refresh_margin_seconds: u64,
+    pub refresh_concurrency: u32,
+    pub max_concurrent_per_account: u32,
+    pub request_interval_ms: u64,
+    pub rotation_strategy: RotationStrategy,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
+    pub usage_retention_days: u32,
+    pub ops_event_retention_days: u32,
+    pub audit_retention_days: u32,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// 原子替换运行设置的命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReplaceRuntimeSettings {
+    pub model_mappings: ModelMappings,
+    pub refresh_margin_seconds: u64,
+    pub refresh_concurrency: u32,
+    pub max_concurrent_per_account: u32,
+    pub request_interval_ms: u64,
+    pub rotation_strategy: RotationStrategy,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
+    pub usage_retention_days: u32,
+    pub ops_event_retention_days: u32,
+    pub audit_retention_days: u32,
+}
+
+/// 明文管理员 API Key；按产品约束明文落库，但禁止 Debug 泄漏。
+#[derive(Clone, PartialEq, Eq)]
+pub struct AdminApiKey(String);
+
+impl AdminApiKey {
+    #[must_use]
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+
+    #[must_use]
+    pub fn expose_for_auth(&self) -> &str {
+        &self.0
+    }
+
+    /// 仅供显式 regenerate 响应读取一次。
+    #[must_use]
+    pub fn expose_for_response(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for AdminApiKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("AdminApiKey([REDACTED])")
+    }
+}
+
+/// 管理员 API Key 更新结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AdminApiKeyMutation {
+    pub config_revision: Revision,
+    pub exists: bool,
+}
+
+/// 新管理员 API Key 的一次性返回结果。
+pub struct RegeneratedAdminApiKey {
+    pub mutation: AdminApiKeyMutation,
+    pub key: AdminApiKey,
+}
+
+impl fmt::Debug for RegeneratedAdminApiKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("RegeneratedAdminApiKey")
+            .field("mutation", &self.mutation)
+            .field("key", &"[REDACTED]")
+            .finish()
+    }
+}

backend/crates/gateway-admin/src/model/system.rs

@@ -0,0 +1,129 @@
+//! 版本、自更新、回滚与进程重启的 UTC 语义模型。
+
+use chrono::{DateTime, Utc};
+
+/// 当前运行版本及更新检查摘要。
+///
+/// `deployment_mode_label` 之类的本地化字符串由 API 根据原始枚举值生成。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemVersion {
+    pub version: String,
+    pub git_sha: String,
+    pub build_time: String,
+    pub deployment_mode: String,
+    pub update_channel: String,
+    pub latest_version: String,
+    pub has_update: bool,
+    pub update_cached: bool,
+    pub update_warning: Option<String>,
+}
+
+/// 发布源提供的完整更新详情。
+///
+/// 部署模式与构建类型的展示标签归 API；其余字段均为 Host 已确认的原始事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemUpdateDetail {
+    pub current_version: String,
+    pub latest_version: String,
+    pub has_update: bool,
+    pub deployment_mode: String,
+    pub build_type: String,
+    pub release_url: Option<String>,
+    pub notes: Option<String>,
+    pub cached: bool,
+    pub update_supported: bool,
+    pub unsupported_reason: Option<String>,
+    pub warning: Option<String>,
+}
+
+/// 系统操作类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemOperationKind {
+    Update,
+    Rollback,
+    Restart,
+}
+
+/// 系统操作状态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemOperationStatus {
+    Idle,
+    Running,
+    Succeeded,
+    Failed,
+}
+
+/// 持久化系统操作的完整状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemOperationState {
+    pub operation_id: Option<String>,
+    pub kind: Option<SystemOperationKind>,
+    pub status: SystemOperationStatus,
+    pub target_version: Option<String>,
+    pub message: Option<String>,
+    pub error: Option<String>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub finished_at: Option<DateTime<Utc>>,
+}
+
+/// 最近一次系统操作及版本交换状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemUpdateStatus {
+    pub previous_version: Option<String>,
+    pub current_version: Option<String>,
+    pub operation: SystemOperationState,
+}
+
+/// 自更新日志级别。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemUpdateEventLevel {
+    Info,
+    Warning,
+    Success,
+    Error,
+}
+
+/// 一条已脱敏的系统更新事件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemUpdateEvent {
+    pub id: String,
+    pub operation_id: Option<String>,
+    pub level: SystemUpdateEventLevel,
+    pub step: Option<String>,
+    pub message: String,
+    pub terminal: bool,
+    pub progress_percent: Option<u8>,
+    pub occurred_at: DateTime<Utc>,
+}
+
+/// 已受理的异步系统操作；不同 wire shape 由枚举保持为合法状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SystemOperationAccepted {
+    Update {
+        operation_id: String,
+        deployment_mode: String,
+        message: String,
+        need_restart: bool,
+        target_version: String,
+    },
+    Rollback {
+        operation_id: String,
+        message: String,
+        need_restart: bool,
+    },
+    Restart {
+        operation_id: String,
+        message: String,
+    },
+}
+
+impl SystemOperationAccepted {
+    #[must_use]
+    pub const fn kind(&self) -> SystemOperationKind {
+        match self {
+            Self::Update { .. } => SystemOperationKind::Update,
+            Self::Rollback { .. } => SystemOperationKind::Rollback,
+            Self::Restart { .. } => SystemOperationKind::Restart,
+        }
+    }
+}

backend/crates/gateway-admin/src/ports/backup.rs

@@ -0,0 +1,442 @@
+//! 备份控制面所需的持久化与基础设施能力。
+//!
+//! 端口方法只接受/返回领域类型与既有错误体系：`BackupRepository` 复用
+//! `AdminStoreError`；`DatabaseDumpPort` 与 `BackupObjectStorePort` 返回只携带稳定
+//! 错误码的 [`BackupError`]。`gateway-store` 实现全部端口；`gateway-admin` 拥有
+//! 状态机、Cron、保留策略与 BackupTask 算法。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+
+use crate::model::Revision;
+use crate::model::{
+    MutationContext,
+    backup::{
+        BackupError, BackupObjectMetadata, BackupRecord, BackupRecordListQuery, BackupRecordPage,
+        BackupRecordSeed, BackupSettings, BackupStatus, BackupStorageConfig, ConnectionTestResult,
+        UpdateBackupScheduleCommand, UpdateBackupStorageCommand,
+    },
+};
+use crate::ports::store::AdminStoreResult;
+
+/// Worker 状态迁移携带的字段更新；`None` 字段不写入。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct StatusTransitionUpdate {
+    pub size_bytes: Option<u64>,
+    pub sha256: Option<String>,
+    pub error_code: Option<String>,
+    pub error_message: Option<String>,
+    pub completed_at: Option<DateTime<Utc>>,
+}
+
+/// 备份配置、任务与计划游标的 PostgreSQL 仓储端口。
+#[async_trait]
+pub trait BackupRepository: Send + Sync {
+    /// 读取完整设置（含 Secret）。
+    async fn load_settings(&self) -> AdminStoreResult<BackupSettings>;
+
+    /// 同事务更新 S3 存储配置、递增 revision、清空验证状态并写审计事件。
+    ///
+    /// 已有记录时禁止切换 endpoint/region/bucket/path-style（存储身份锁定）。
+    /// 返回更新后的设置与新的全局 `config_revision`。
+    async fn update_storage_settings(
+        &self,
+        command: UpdateBackupStorageCommand,
+        context: &MutationContext,
+    ) -> AdminStoreResult<(BackupSettings, Revision)>;
+
+    /// 同事务更新调度配置、推进计划游标并写审计事件。
+    async fn update_schedule_settings(
+        &self,
+        command: UpdateBackupScheduleCommand,
+        next_run_at: Option<DateTime<Utc>>,
+        context: &MutationContext,
+    ) -> AdminStoreResult<BackupSettings>;
+
+    /// CAS 记录探针成功；`storage_revision` 与当前配置不一致时丢弃结果（返回 `false`）。
+    async fn record_verification(
+        &self,
+        storage_revision: u64,
+        at: DateTime<Utc>,
+    ) -> AdminStoreResult<bool>;
+
+    /// 插入 queued 任务；存在活跃任务时返回 `backup.active_task_conflict`。
+    async fn insert_backup_record(&self, seed: BackupRecordSeed) -> AdminStoreResult<BackupRecord>;
+
+    /// 幂等插入 scheduled 任务；同一时间点或活跃冲突时返回 `false`（调用方推进游标即可）。
+    async fn insert_scheduled_record(&self, seed: BackupRecordSeed) -> AdminStoreResult<bool>;
+
+    /// 分页查询记录。
+    async fn list_backup_records(
+        &self,
+        query: BackupRecordListQuery,
+    ) -> AdminStoreResult<BackupRecordPage>;
+
+    /// 读取单条记录。
+    async fn load_backup_record(&self, id: &str) -> AdminStoreResult<Option<BackupRecord>>;
+
+    /// 读取中间状态记录（dumping/uploading），供启动恢复。
+    async fn list_intermediate_records(&self) -> AdminStoreResult<Vec<BackupRecord>>;
+
+    /// 读取等待完成墓碑的记录（status = deleting）。
+    async fn list_pending_deletions(&self, limit: u32) -> AdminStoreResult<Vec<BackupRecord>>;
+
+    /// 读取 `expires_at` 已到期且非活跃的记录（completed/failed），供保留清理。
+    async fn list_expired_records(&self, limit: u32) -> AdminStoreResult<Vec<BackupRecord>>;
+
+    /// 原子领取最旧的 queued 任务并迁移到 dumping；无任务返回 `None`。
+    async fn claim_next_queued(&self, now: DateTime<Utc>)
+    -> AdminStoreResult<Option<BackupRecord>>;
+
+    /// 条件迁移状态：要求当前状态一致；不匹配返回 `None`。
+    async fn transition_status(
+        &self,
+        id: &str,
+        from: BackupStatus,
+        to: BackupStatus,
+        update: StatusTransitionUpdate,
+        now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>>;
+
+    /// 迁移到删除流程（completed/failed → deleting）；供管理员与保留策略调用。
+    async fn transition_to_deleting(
+        &self,
+        id: &str,
+        now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>>;
+
+    /// 远端删除成功后硬删除记录行。
+    async fn delete_record(&self, id: &str) -> AdminStoreResult<()>;
+
+    /// 条件推进计划游标；仅当计划表达式和时区仍是 `expected_*` 时才写入，返回是否推进。
+    async fn advance_schedule_cursor(
+        &self,
+        next_run_at: DateTime<Utc>,
+        expected_cron: &str,
+        expected_timezone: &str,
+    ) -> AdminStoreResult<bool>;
+
+    /// 按完成时间倒序读取 completed 计划备份，供保留策略扫描（最多 `limit` 条）。
+    async fn list_scheduled_completed_desc(
+        &self,
+        limit: u32,
+    ) -> AdminStoreResult<Vec<BackupRecord>>;
+}
+
+/// `pg_dump` 导出与本地暂存端口。
+#[async_trait]
+pub trait DatabaseDumpPort: Send + Sync {
+    /// 创建归档；完成后原子落盘。取消时终止子进程并清理部分文件。
+    async fn dump(&self, request: DumpRequest) -> Result<DumpArtifact, BackupError>;
+
+    /// 检查暂存目录是否存在完整归档。
+    async fn inspect_staging(&self, backup_id: &str)
+    -> Result<Option<StagedArtifact>, BackupError>;
+
+    /// 清理暂存目录中该备份的全部文件。
+    async fn cleanup_staging(&self, backup_id: &str) -> Result<(), BackupError>;
+}
+
+/// 一次 `pg_dump` 请求。
+#[derive(Debug, Clone)]
+pub struct DumpRequest {
+    pub backup_id: String,
+    pub cancellation: gateway_core::lifecycle::CancellationToken,
+}
+
+/// 已完成并落盘的归档事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DumpArtifact {
+    pub path: PathBuf,
+    pub size_bytes: u64,
+    pub sha256: String,
+}
+
+/// 暂存目录中已存在的完整归档。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StagedArtifact {
+    pub path: PathBuf,
+    pub size_bytes: u64,
+    pub sha256: String,
+}
+
+/// S3 兼容对象存储适配器端口。
+///
+/// 方法接受已经校验的存储配置；SDK client 的构造与缓存属于 adapter 实现细节。
+#[async_trait]
+pub trait BackupObjectStorePort: Send + Sync {
+    /// 对专用探针对象执行 Put/Head/Get/Delete。
+    async fn test_connection(
+        &self,
+        config: &BackupStorageConfig,
+    ) -> Result<ConnectionTestResult, BackupError>;
+
+    /// 分片流式上传本地归档；取消时中止 multipart 并返回 `backup.cancelled`。
+    async fn upload_file(
+        &self,
+        config: &BackupStorageConfig,
+        request: UploadObjectRequest,
+    ) -> Result<(), BackupError>;
+
+    /// 读取对象大小与 metadata；对象不存在返回 `Ok(None)`。
+    async fn head_object(
+        &self,
+        config: &BackupStorageConfig,
+        object_key: &str,
+    ) -> Result<Option<BackupObjectMetadata>, BackupError>;
+
+    /// 删除对象；对象不存在视为成功。
+    async fn delete_object(
+        &self,
+        config: &BackupStorageConfig,
+        object_key: &str,
+    ) -> Result<(), BackupError>;
+
+    /// 创建短时预签名下载 URL。
+    async fn presigned_download(
+        &self,
+        config: &BackupStorageConfig,
+        object_key: &str,
+        file_name: &str,
+        ttl: Duration,
+    ) -> Result<String, BackupError>;
+}
+
+/// 一次对象上传请求。
+#[derive(Debug, Clone)]
+pub struct UploadObjectRequest {
+    pub object_key: String,
+    pub source: PathBuf,
+    pub metadata: BackupObjectMetadata,
+    pub cancellation: gateway_core::lifecycle::CancellationToken,
+}
+
+/// 备份控制面所需的全部 Store 能力集合。
+#[derive(Clone)]
+pub struct BackupStorePorts {
+    repository: Arc<dyn BackupRepository>,
+    dump: Arc<dyn DatabaseDumpPort>,
+    object_store: Arc<dyn BackupObjectStorePort>,
+}
+
+impl BackupStorePorts {
+    /// 组合备份端口。
+    #[must_use]
+    pub fn new(
+        repository: Arc<dyn BackupRepository>,
+        dump: Arc<dyn DatabaseDumpPort>,
+        object_store: Arc<dyn BackupObjectStorePort>,
+    ) -> Self {
+        Self {
+            repository,
+            dump,
+            object_store,
+        }
+    }
+
+    /// 备份任务/配置仓储。
+    #[must_use]
+    pub fn repository(&self) -> Arc<dyn BackupRepository> {
+        self.repository.clone()
+    }
+
+    /// `pg_dump` 导出与暂存。
+    #[must_use]
+    pub fn dump(&self) -> Arc<dyn DatabaseDumpPort> {
+        self.dump.clone()
+    }
+
+    /// S3/R2 对象存储适配器。
+    #[must_use]
+    pub fn object_store(&self) -> Arc<dyn BackupObjectStorePort> {
+        self.object_store.clone()
+    }
+
+    /// 测试与不可用路径使用的空实现；任何调用都返回不可用错误。
+    #[doc(hidden)]
+    #[must_use]
+    pub fn disabled() -> Self {
+        Self {
+            repository: Arc::new(UnavailableBackupRepository),
+            dump: Arc::new(UnavailableDumpPort),
+            object_store: Arc::new(UnavailableObjectStore),
+        }
+    }
+}
+
+struct UnavailableBackupRepository;
+
+#[async_trait]
+impl BackupRepository for UnavailableBackupRepository {
+    async fn load_settings(&self) -> AdminStoreResult<BackupSettings> {
+        Err(disabled_store())
+    }
+    async fn update_storage_settings(
+        &self,
+        _command: UpdateBackupStorageCommand,
+        _context: &MutationContext,
+    ) -> AdminStoreResult<(BackupSettings, Revision)> {
+        Err(disabled_store())
+    }
+    async fn update_schedule_settings(
+        &self,
+        _command: UpdateBackupScheduleCommand,
+        _next_run_at: Option<DateTime<Utc>>,
+        _context: &MutationContext,
+    ) -> AdminStoreResult<BackupSettings> {
+        Err(disabled_store())
+    }
+    async fn record_verification(
+        &self,
+        _storage_revision: u64,
+        _at: DateTime<Utc>,
+    ) -> AdminStoreResult<bool> {
+        Err(disabled_store())
+    }
+    async fn insert_backup_record(
+        &self,
+        _seed: BackupRecordSeed,
+    ) -> AdminStoreResult<BackupRecord> {
+        Err(disabled_store())
+    }
+    async fn insert_scheduled_record(&self, _seed: BackupRecordSeed) -> AdminStoreResult<bool> {
+        Err(disabled_store())
+    }
+    async fn list_backup_records(
+        &self,
+        _query: BackupRecordListQuery,
+    ) -> AdminStoreResult<BackupRecordPage> {
+        Err(disabled_store())
+    }
+    async fn load_backup_record(&self, _id: &str) -> AdminStoreResult<Option<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn list_intermediate_records(&self) -> AdminStoreResult<Vec<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn list_pending_deletions(&self, _limit: u32) -> AdminStoreResult<Vec<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn list_expired_records(&self, _limit: u32) -> AdminStoreResult<Vec<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn claim_next_queued(
+        &self,
+        _now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn transition_status(
+        &self,
+        _id: &str,
+        _from: BackupStatus,
+        _to: BackupStatus,
+        _update: StatusTransitionUpdate,
+        _now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn transition_to_deleting(
+        &self,
+        _id: &str,
+        _now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn delete_record(&self, _id: &str) -> AdminStoreResult<()> {
+        Err(disabled_store())
+    }
+    async fn advance_schedule_cursor(
+        &self,
+        _next_run_at: DateTime<Utc>,
+        _expected_cron: &str,
+        _expected_timezone: &str,
+    ) -> AdminStoreResult<bool> {
+        Err(disabled_store())
+    }
+    async fn list_scheduled_completed_desc(
+        &self,
+        _limit: u32,
+    ) -> AdminStoreResult<Vec<BackupRecord>> {
+        Err(disabled_store())
+    }
+}
+
+struct UnavailableDumpPort;
+
+#[async_trait]
+impl DatabaseDumpPort for UnavailableDumpPort {
+    async fn dump(&self, _request: DumpRequest) -> Result<DumpArtifact, BackupError> {
+        Err(disabled_infra())
+    }
+    async fn inspect_staging(
+        &self,
+        _backup_id: &str,
+    ) -> Result<Option<StagedArtifact>, BackupError> {
+        Err(disabled_infra())
+    }
+    async fn cleanup_staging(&self, _backup_id: &str) -> Result<(), BackupError> {
+        Err(disabled_infra())
+    }
+}
+
+struct UnavailableObjectStore;
+
+#[async_trait]
+impl BackupObjectStorePort for UnavailableObjectStore {
+    async fn test_connection(
+        &self,
+        _config: &BackupStorageConfig,
+    ) -> Result<ConnectionTestResult, BackupError> {
+        Err(disabled_infra())
+    }
+    async fn upload_file(
+        &self,
+        _config: &BackupStorageConfig,
+        _request: UploadObjectRequest,
+    ) -> Result<(), BackupError> {
+        Err(disabled_infra())
+    }
+    async fn head_object(
+        &self,
+        _config: &BackupStorageConfig,
+        _object_key: &str,
+    ) -> Result<Option<BackupObjectMetadata>, BackupError> {
+        Err(disabled_infra())
+    }
+    async fn delete_object(
+        &self,
+        _config: &BackupStorageConfig,
+        _object_key: &str,
+    ) -> Result<(), BackupError> {
+        Err(disabled_infra())
+    }
+    async fn presigned_download(
+        &self,
+        _config: &BackupStorageConfig,
+        _object_key: &str,
+        _file_name: &str,
+        _ttl: std::time::Duration,
+    ) -> Result<String, BackupError> {
+        Err(disabled_infra())
+    }
+}
+
+fn disabled_store() -> crate::ports::store::AdminStoreError {
+    crate::ports::store::AdminStoreError::new(
+        crate::ports::store::AdminStoreErrorKind::Unavailable,
+        "backup",
+        "backup store is disabled in this configuration",
+    )
+}
+
+fn disabled_infra() -> BackupError {
+    BackupError::new(
+        crate::model::backup::code::STORE_UNAVAILABLE,
+        "backup infrastructure is disabled in this configuration".to_owned(),
+    )
+}

backend/crates/gateway-admin/src/ports/client_distribution.rs

@@ -0,0 +1,10 @@
+//! 客户端安装包解析的外部能力端口。
+
+use async_trait::async_trait;
+
+use crate::model::client_distribution::CodexDesktopWindowsDownloads;
+
+#[async_trait]
+pub trait ClientDistributionResolver: Send + Sync {
+    async fn resolve_codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads;
+}

backend/crates/gateway-admin/src/ports/mod.rs

@@ -0,0 +1,7 @@
+//! 管理用例依赖的外部能力端口。
+
+pub mod backup;
+pub mod client_distribution;
+pub mod provider;
+pub mod store;
+pub mod system;

backend/crates/gateway-admin/src/ports/provider.rs

@@ -0,0 +1,249 @@
+//! Provider 管理能力与动态注册表。
+
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+use gateway_core::{
+    account::ProviderAccountId,
+    operation::Operation,
+    routing::{ProviderKind, UpstreamModelId},
+};
+
+use crate::model::observability::{
+    CalculatedBillingBreakdown, DashboardWireProfile, ProviderBillingInput,
+};
+use crate::model::provider_credentials::{
+    AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
+    PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
+    PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
+    PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput, ProviderModels,
+    ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+    ProviderResetCreditResult, ProviderResetCredits,
+};
+
+/// Provider 管理失败的稳定分类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProviderAdminErrorKind {
+    Invalid,
+    Unsupported,
+    NotFound,
+    Conflict,
+    /// Provider 已发起不可逆操作，但无法确认最终执行结果。
+    Ambiguous,
+    Unavailable,
+    CredentialRefreshRequired,
+    BadGateway,
+    Internal,
+}
+
+/// 不携带 OAuth 请求材料的管理错误。
+///
+/// `message` 是 Provider 局部诊断，可能包含原始上游正文；通用管理用例不得自动把它作为公开文案。
+/// 只有明确拥有原始诊断合同的调用方才能读取，`Debug` 始终只记录是否存在。
+#[derive(Clone, PartialEq, Eq, thiserror::Error)]
+#[error("provider admin operation failed: {kind:?}")]
+pub struct ProviderAdminError {
+    kind: ProviderAdminErrorKind,
+    message: Option<String>,
+}
+
+impl std::fmt::Debug for ProviderAdminError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("ProviderAdminError")
+            .field("kind", &self.kind)
+            .field("message", &self.message.as_ref().map(|_| "<redacted>"))
+            .finish()
+    }
+}
+
+impl ProviderAdminError {
+    #[must_use]
+    pub const fn new(kind: ProviderAdminErrorKind) -> Self {
+        Self {
+            kind,
+            message: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_message(mut self, message: impl Into<String>) -> Self {
+        self.message = Some(message.into());
+        self
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> ProviderAdminErrorKind {
+        self.kind
+    }
+
+    #[must_use]
+    pub fn message(&self) -> Option<&str> {
+        self.message.as_deref()
+    }
+}
+
+/// 一个具体 Provider 对管理控制面提供的解析、验证、上游交互与运行时资源回收能力。
+///
+/// 数据变更由 Provider 返回 prepared facts；config revision、审计与 PostgreSQL 事务
+/// 全部由 [`crate::ports::store::AccountStore`] 提交。运行时资源通知只在事务成功后发生。
+#[async_trait]
+pub trait ProviderAdmin: Send + Sync {
+    fn provider_kind(&self) -> &ProviderKind;
+
+    /// 账号已经由控制面提交为不可调度状态，释放 Provider 持有的账号级运行时资源。
+    ///
+    /// 无账号级运行时资源的 Provider 不需要执行额外操作。该通知发生在 Store 事务
+    /// 成功之后，不参与事务成败，也不得恢复或改写已经提交的账号状态。
+    async fn account_unavailable(&self, account_id: &ProviderAccountId);
+
+    /// 账号资格事实已经由控制面提交，失效 Provider 持有的可重建派生状态。
+    ///
+    /// 该通知发生在 Store 事务成功之后、下一份 RuntimeSnapshot 编译之前；通知
+    /// 不参与已提交事务成败。没有账号派生状态的 Provider 可使用默认空实现。
+    async fn account_facts_changed(&self, _account_ids: &[ProviderAccountId]) {}
+
+    /// 生成一次连接测试所需的 Provider-owned operation；Core 负责实际执行与落账。
+    fn connection_test_operation(
+        &self,
+        upstream_model: &UpstreamModelId,
+        input_text: &str,
+    ) -> Result<Operation, ProviderAdminError>;
+
+    /// 返回该 Provider 实际持有的 Dashboard 上游身份画像。
+    fn dashboard_wire_profile(&self) -> Option<DashboardWireProfile>;
+
+    /// 使用 Provider-owned 价格规则恢复持久请求的逐项费用。
+    fn calculated_billing(
+        &self,
+        input: &ProviderBillingInput,
+    ) -> Result<Option<CalculatedBillingBreakdown>, ProviderAdminError>;
+
+    async fn prepare_import(
+        &self,
+        command: PrepareCredentialImport,
+    ) -> Result<PreparedCredentialImport, ProviderAdminError>;
+
+    async fn start_authorization(
+        &self,
+        pending: PendingAuthorizationMutation,
+    ) -> Result<AuthorizationStarted, ProviderAdminError>;
+
+    async fn complete_authorization(
+        &self,
+        command: CompleteAuthorization,
+    ) -> Result<PreparedAuthorizationCommit, ProviderAdminError>;
+
+    async fn prepare_rotation(
+        &self,
+        command: PrepareCredentialRotation,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError>;
+
+    async fn prepare_refresh(
+        &self,
+        command: PrepareCredentialRefresh,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError>;
+
+    async fn quota(
+        &self,
+        request: ProviderQuotaRequest,
+    ) -> Result<ProviderQuota, ProviderAdminError>;
+
+    /// 查询 Provider 官方个人资料统计；不支持该能力的 Provider 使用默认拒绝。
+    async fn profile_statistics(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 打开 Provider 官方头像字节流；不支持该能力的 Provider 使用默认拒绝。
+    async fn profile_avatar(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 查询 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    async fn reset_credits(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderResetCredits, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 消费 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    async fn consume_reset_credit(
+        &self,
+        _command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    async fn models(
+        &self,
+        account_id: &ProviderAccountId,
+        refresh: bool,
+    ) -> Result<ProviderModels, ProviderAdminError>;
+
+    async fn export_credentials(
+        &self,
+        credentials: Vec<ProviderExportCredentialInput>,
+    ) -> Result<ProviderExport, ProviderAdminError>;
+}
+
+/// 按 ProviderKind 动态发现管理能力；不含具体 Provider 分支。
+#[derive(Clone)]
+pub struct ProviderAdminRegistry {
+    providers: Arc<BTreeMap<ProviderKind, Arc<dyn ProviderAdmin>>>,
+}
+
+impl ProviderAdminRegistry {
+    /// 创建无重复 ProviderKind 的注册表。
+    ///
+    /// # Errors
+    ///
+    /// 重复注册同一 ProviderKind 时返回 Conflict。
+    pub fn new(
+        providers: impl IntoIterator<Item = Arc<dyn ProviderAdmin>>,
+    ) -> Result<Self, ProviderAdminError> {
+        let mut registered = BTreeMap::new();
+        for provider in providers {
+            let kind = provider.provider_kind().clone();
+            if registered.insert(kind, provider).is_some() {
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+            }
+        }
+        Ok(Self {
+            providers: Arc::new(registered),
+        })
+    }
+
+    pub fn require(
+        &self,
+        provider_kind: &ProviderKind,
+    ) -> Result<Arc<dyn ProviderAdmin>, ProviderAdminError> {
+        self.providers
+            .get(provider_kind)
+            .cloned()
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 返回所有已注册 Provider 的 Dashboard 上游身份画像。
+    pub fn dashboard_wire_profiles(&self) -> Vec<DashboardWireProfile> {
+        self.providers
+            .values()
+            .filter_map(|provider| provider.dashboard_wire_profile())
+            .collect()
+    }
+
+    /// 动态分派 Provider-owned 费用规则，不含任何具体 Provider 分支。
+    pub fn calculated_billing(
+        &self,
+        provider_kind: &ProviderKind,
+        input: &ProviderBillingInput,
+    ) -> Result<Option<CalculatedBillingBreakdown>, ProviderAdminError> {
+        self.require(provider_kind)?.calculated_billing(input)
+    }
+}

backend/crates/gateway-admin/src/ports/store.rs

@@ -0,0 +1,474 @@
+//! 管理控制面所需的持久化能力。
+//!
+//! 端口按业务资源拆分，方法使用领域模型，不暴露连接池、事务或 Redis client。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use futures::stream::BoxStream;
+
+use super::backup::BackupStorePorts;
+use crate::model::{
+    MutationContext, Revision,
+    account_groups::{
+        AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+        DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+    },
+    accounts::{
+        AccountListQuery, AccountPage, AccountPageItem, AccountRuntimeSnapshot,
+        AccountUpdateResult, AccountUsage, AccountUsageWindowQuery, AccountUsageWindowResult,
+        AccountsUpdateResult, BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
+    },
+    auth::{AdminAuditEvent, AdminSession},
+    client_keys::{
+        ClientKeyListQuery, ClientKeyPage, ClientKeyRecord, ClientKeySecret, DeleteClientKey,
+        NewClientKey, SetClientKeyEnabled, UpdateClientKey,
+    },
+    observability::{
+        DashboardObservation, DashboardRuntimeSlots, DiagnosticDimension, DiagnosticObservation,
+        OpsErrorPage, OpsErrorQuery, RequestMetricPoint, TimeRange, UsageCalculatedBillingFact,
+        UsageDetail, UsageFilter, UsageOverview, UsagePage, UsageQuery,
+    },
+    provider_credentials::{
+        AuthorizationCommit, CredentialDetails, CredentialImportCommit, CredentialImportResult,
+        CredentialListQuery, CredentialMutationResult, CredentialPage, CredentialRotationCommit,
+        ProviderExportCredentialInput,
+    },
+    settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
+};
+
+/// 管理端可判定的持久化失败类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AdminStoreErrorKind {
+    Invalid,
+    NotFound,
+    StaleRevision,
+    Conflict,
+    Unavailable,
+}
+
+/// 隐藏数据库实现细节的持久化错误。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{resource} store operation failed: {message}")]
+pub struct AdminStoreError {
+    kind: AdminStoreErrorKind,
+    resource: &'static str,
+    message: String,
+}
+
+impl AdminStoreError {
+    #[must_use]
+    pub fn new(
+        kind: AdminStoreErrorKind,
+        resource: &'static str,
+        message: impl Into<String>,
+    ) -> Self {
+        Self {
+            kind,
+            resource,
+            message: message.into(),
+        }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> AdminStoreErrorKind {
+        self.kind
+    }
+
+    #[must_use]
+    pub const fn resource(&self) -> &'static str {
+        self.resource
+    }
+}
+
+pub type AdminStoreResult<T> = Result<T, AdminStoreError>;
+
+/// 账号目录与公共账号写操作。
+#[async_trait]
+pub trait AccountStore: Send + Sync {
+    async fn list_accounts(
+        &self,
+        query: AccountListQuery,
+        runtime: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<AccountPage>;
+
+    async fn load_account(
+        &self,
+        account_id: &str,
+        runtime: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<Option<AccountPageItem>>;
+
+    async fn load_account_usage(
+        &self,
+        range: TimeRange,
+        account_ids: &[String],
+    ) -> AdminStoreResult<Vec<AccountUsage>>;
+
+    async fn load_account_usage_by_windows(
+        &self,
+        windows: &[AccountUsageWindowQuery],
+    ) -> AdminStoreResult<Vec<AccountUsageWindowResult>>;
+
+    async fn list_credentials(
+        &self,
+        provider_kind: &gateway_core::routing::ProviderKind,
+        query: CredentialListQuery,
+    ) -> AdminStoreResult<CredentialPage>;
+
+    async fn credential_details(
+        &self,
+        provider_kind: &gateway_core::routing::ProviderKind,
+        account_id: &gateway_core::account::ProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>>;
+
+    async fn load_credentials_for_export(
+        &self,
+        provider_kind: &gateway_core::routing::ProviderKind,
+        account_ids: &[gateway_core::account::ProviderAccountId],
+    ) -> AdminStoreResult<Vec<ProviderExportCredentialInput>>;
+
+    async fn commit_credential_import(
+        &self,
+        command: CredentialImportCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<CredentialImportResult>;
+
+    async fn commit_authorization(
+        &self,
+        command: AuthorizationCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<CredentialMutationResult>;
+
+    async fn commit_credential_rotation(
+        &self,
+        command: CredentialRotationCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<CredentialMutationResult>;
+
+    async fn commit_credential_refresh(
+        &self,
+        command: CredentialRotationCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<CredentialMutationResult>;
+
+    async fn update_account(
+        &self,
+        command: UpdateAccount,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountUpdateResult>;
+
+    async fn recover_account(
+        &self,
+        account_id: &gateway_core::account::ProviderAccountId,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountUpdateResult>;
+
+    async fn batch_update_accounts(
+        &self,
+        command: BatchUpdateAccounts,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountsUpdateResult>;
+
+    async fn delete_accounts(
+        &self,
+        command: DeleteAccounts,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+
+    async fn record_credential_export(
+        &self,
+        account_ids: &[gateway_core::account::ProviderAccountId],
+        context: &MutationContext,
+    ) -> AdminStoreResult<()>;
+}
+
+/// 可丢失账号运行态的管理读端口；跨存储编排由 Admin application service 拥有。
+#[async_trait]
+pub trait AccountRuntimeStore: Send + Sync {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot>;
+
+    async fn account_runtime(
+        &self,
+        account_ids: &[String],
+    ) -> AdminStoreResult<AccountRuntimeSnapshot>;
+}
+
+/// 管理员密码、会话和安全审计。
+#[async_trait]
+pub trait AuthStore: Send + Sync {
+    async fn load_password_hash(&self, admin_user_id: &str) -> AdminStoreResult<Option<String>>;
+
+    async fn create_password_hash_if_absent(
+        &self,
+        admin_user_id: &str,
+        password_hash: &str,
+    ) -> AdminStoreResult<bool>;
+
+    async fn load_admin_api_key(&self) -> AdminStoreResult<Option<AdminApiKey>>;
+
+    async fn load_session(&self, session_id: &str) -> AdminStoreResult<Option<AdminSession>>;
+
+    async fn store_session(&self, session_id: &str, session: &AdminSession)
+    -> AdminStoreResult<()>;
+
+    async fn delete_session(&self, session_id: &str) -> AdminStoreResult<Option<AdminSession>>;
+
+    async fn append_audit_event(&self, event: AdminAuditEvent) -> AdminStoreResult<()>;
+}
+
+/// Client API Key 管理写入。
+#[async_trait]
+pub trait ClientKeyStore: Send + Sync {
+    async fn list_client_keys(&self, query: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage>;
+
+    async fn reveal_client_key(
+        &self,
+        id: &gateway_core::policy::ClientApiKeyId,
+    ) -> AdminStoreResult<Option<ClientKeySecret>>;
+
+    async fn create_client_key(
+        &self,
+        command: NewClientKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)>;
+
+    async fn update_client_key(
+        &self,
+        command: UpdateClientKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)>;
+
+    async fn set_client_key_enabled(
+        &self,
+        command: SetClientKeyEnabled,
+        context: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)>;
+
+    async fn delete_client_key(
+        &self,
+        command: DeleteClientKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+}
+
+/// Provider-neutral account group management transactions.
+#[async_trait]
+pub trait AccountGroupStore: Send + Sync {
+    async fn list_account_groups(
+        &self,
+        query: AccountGroupListQuery,
+    ) -> AdminStoreResult<AccountGroupPage>;
+
+    async fn load_account_group_members(
+        &self,
+        group_ids: &[gateway_core::routing::AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>>;
+
+    async fn create_account_group(
+        &self,
+        command: NewAccountGroup,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation>;
+
+    async fn update_account_group(
+        &self,
+        command: UpdateAccountGroup,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation>;
+
+    async fn set_account_group_enabled(
+        &self,
+        command: SetAccountGroupEnabled,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation>;
+
+    async fn delete_account_group(
+        &self,
+        command: DeleteAccountGroup,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation>;
+}
+
+/// 逐条读取的已计算费用事实；消费结束或丢弃时释放查询资源。
+pub type UsageCalculatedBillingStream<'a> =
+    BoxStream<'a, AdminStoreResult<UsageCalculatedBillingFact>>;
+
+/// 用量、趋势、诊断与运维错误的只读能力。
+#[async_trait]
+pub trait ObservabilityStore: Send + Sync {
+    /// 返回历史统计区间和指定观测时刻下的实时账号状态。
+    async fn dashboard_summary(
+        &self,
+        range: TimeRange,
+        observed_at: DateTime<Utc>,
+    ) -> AdminStoreResult<DashboardObservation>;
+
+    /// 返回 Dashboard 可选的实时槽位事实。
+    ///
+    /// 该状态来自可丢失的运行时存储；无实现或运行时存储不可用时返回 `None`，不影响
+    /// 持久观测数据的读取。
+    async fn dashboard_runtime_slots(
+        &self,
+        _observed_at: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<DashboardRuntimeSlots>> {
+        Ok(None)
+    }
+
+    async fn dashboard_trend(&self, range: TimeRange) -> AdminStoreResult<Vec<RequestMetricPoint>>;
+
+    async fn usage_trend(
+        &self,
+        range: TimeRange,
+        filter: UsageFilter,
+    ) -> AdminStoreResult<Vec<RequestMetricPoint>>;
+
+    /// 流式返回可由 Provider 重新校验的已计算费用事实，不保证顺序。
+    /// 查询及解码错误由流返回；调用方应逐条聚合，避免收集整个区间。
+    fn usage_calculated_billing_facts(
+        &self,
+        range: TimeRange,
+        filter: UsageFilter,
+    ) -> UsageCalculatedBillingStream<'_>;
+
+    async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage>;
+
+    async fn usage_record_detail(&self, request_id: &str) -> AdminStoreResult<UsageDetail>;
+
+    async fn usage_summary(
+        &self,
+        range: TimeRange,
+        filter: UsageFilter,
+    ) -> AdminStoreResult<UsageOverview>;
+
+    async fn usage_diagnostics(
+        &self,
+        range: TimeRange,
+        filter: UsageFilter,
+        dimension: DiagnosticDimension,
+    ) -> AdminStoreResult<Vec<DiagnosticObservation>>;
+
+    async fn list_ops_errors(&self, query: OpsErrorQuery) -> AdminStoreResult<OpsErrorPage>;
+}
+
+/// Runtime settings 与管理员 API Key 写入。
+#[async_trait]
+pub trait SettingsStore: Send + Sync {
+    async fn load_runtime_settings(&self) -> AdminStoreResult<RuntimeSettings>;
+
+    async fn admin_api_key_exists(&self) -> AdminStoreResult<bool>;
+
+    async fn replace_runtime_settings(
+        &self,
+        command: ReplaceRuntimeSettings,
+        context: &MutationContext,
+    ) -> AdminStoreResult<RuntimeSettings>;
+
+    async fn replace_admin_api_key(
+        &self,
+        key: AdminApiKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation>;
+
+    async fn delete_admin_api_key(
+        &self,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation>;
+}
+
+/// 账号目录、运行态与分组所需的 Store 能力集合。
+#[derive(Clone)]
+pub struct AdminAccountStorePorts {
+    accounts: Arc<dyn AccountStore>,
+    runtime: Arc<dyn AccountRuntimeStore>,
+    groups: Arc<dyn AccountGroupStore>,
+}
+
+impl AdminAccountStorePorts {
+    #[must_use]
+    pub fn new(
+        accounts: Arc<dyn AccountStore>,
+        runtime: Arc<dyn AccountRuntimeStore>,
+        groups: Arc<dyn AccountGroupStore>,
+    ) -> Self {
+        Self {
+            accounts,
+            runtime,
+            groups,
+        }
+    }
+}
+
+/// 管理用例所需能力的封闭集合。
+///
+/// 字段保持私有，每个 getter 只交出一种明确能力。该类型不提供通用拆包入口。
+#[derive(Clone)]
+pub struct AdminStorePorts {
+    accounts: AdminAccountStorePorts,
+    auth: Arc<dyn AuthStore>,
+    client_keys: Arc<dyn ClientKeyStore>,
+    observability: Arc<dyn ObservabilityStore>,
+    settings: Arc<dyn SettingsStore>,
+    backup: BackupStorePorts,
+}
+
+impl AdminStorePorts {
+    #[must_use]
+    pub fn new(
+        accounts: AdminAccountStorePorts,
+        auth: Arc<dyn AuthStore>,
+        client_keys: Arc<dyn ClientKeyStore>,
+        observability: Arc<dyn ObservabilityStore>,
+        settings: Arc<dyn SettingsStore>,
+        backup: BackupStorePorts,
+    ) -> Self {
+        Self {
+            accounts,
+            auth,
+            client_keys,
+            observability,
+            settings,
+            backup,
+        }
+    }
+
+    #[must_use]
+    pub fn accounts(&self) -> Arc<dyn AccountStore> {
+        self.accounts.accounts.clone()
+    }
+
+    #[must_use]
+    pub fn account_runtime(&self) -> Arc<dyn AccountRuntimeStore> {
+        self.accounts.runtime.clone()
+    }
+
+    #[must_use]
+    pub fn account_groups(&self) -> Arc<dyn AccountGroupStore> {
+        self.accounts.groups.clone()
+    }
+
+    #[must_use]
+    pub fn auth(&self) -> Arc<dyn AuthStore> {
+        self.auth.clone()
+    }
+
+    #[must_use]
+    pub fn client_keys(&self) -> Arc<dyn ClientKeyStore> {
+        self.client_keys.clone()
+    }
+
+    #[must_use]
+    pub fn observability(&self) -> Arc<dyn ObservabilityStore> {
+        self.observability.clone()
+    }
+
+    #[must_use]
+    pub fn settings(&self) -> Arc<dyn SettingsStore> {
+        self.settings.clone()
+    }
+
+    #[must_use]
+    pub fn backup(&self) -> BackupStorePorts {
+        self.backup.clone()
+    }
+}

backend/crates/gateway-admin/src/ports/system.rs

@@ -0,0 +1,76 @@
+//! Host 为系统管理用例提供的进程与操作系统能力。
+
+use std::pin::Pin;
+
+use async_trait::async_trait;
+use futures::Stream;
+
+use crate::model::system::{
+    SystemOperationAccepted, SystemUpdateDetail, SystemUpdateEvent, SystemUpdateStatus,
+    SystemVersion,
+};
+
+/// Host 系统操作失败类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemOperationErrorKind {
+    Invalid,
+    Conflict,
+    Upstream,
+    Internal,
+}
+
+/// 不泄漏路径、命令行或发布凭据的系统操作错误。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("system operation failed: {message}")]
+pub struct SystemOperationError {
+    kind: SystemOperationErrorKind,
+    message: String,
+}
+
+impl SystemOperationError {
+    #[must_use]
+    pub fn new(kind: SystemOperationErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+        }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> SystemOperationErrorKind {
+        self.kind
+    }
+
+    /// 返回 Host 已完成脱敏的客户端安全消息。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+/// 每个订阅者独占的系统事件流。
+pub type SystemUpdateEventStream = Pin<Box<dyn Stream<Item = SystemUpdateEvent> + Send + 'static>>;
+
+/// 版本、自更新、回滚和重启能力；实现唯一归 gateway-host。
+#[async_trait]
+pub trait SystemOperations: Send + Sync {
+    async fn version(&self) -> Result<SystemVersion, SystemOperationError>;
+
+    async fn update_detail(
+        &self,
+        refresh: bool,
+    ) -> Result<SystemUpdateDetail, SystemOperationError>;
+
+    fn update_events(&self) -> SystemUpdateEventStream;
+
+    async fn perform_update(
+        &self,
+        target_version: Option<String>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError>;
+
+    async fn update_status(&self) -> Result<SystemUpdateStatus, SystemOperationError>;
+
+    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError>;
+
+    async fn restart(&self) -> Result<SystemOperationAccepted, SystemOperationError>;
+}

backend/crates/gateway-admin/src/use_case/account_groups.rs

@@ -0,0 +1,242 @@
+//! Account group management use cases.
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::Arc,
+    time::SystemTime,
+};
+
+use async_trait::async_trait;
+use gateway_core::{
+    account::{AccountStatus, resolve_account_status},
+    routing::AccountGroupId,
+    runtime::SnapshotControl,
+};
+use uuid::Uuid;
+
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        account_groups::{
+            AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupListQuery,
+            AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage, AccountGroupRecord,
+            CreateAccountGroup, DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled,
+            UpdateAccountGroup,
+        },
+    },
+    ports::store::{AccountGroupStore, AccountRuntimeStore},
+};
+
+use super::{map_store_error, publish_committed};
+
+/// API-facing account group management service.
+#[async_trait]
+pub trait AccountGroupService: Send + Sync {
+    async fn list(&self, query: AccountGroupListQuery) -> Result<AccountGroupPage, AdminError>;
+    async fn create(
+        &self,
+        context: &MutationContext,
+        command: CreateAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError>;
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError>;
+    async fn set_enabled(
+        &self,
+        context: &MutationContext,
+        command: SetAccountGroupEnabled,
+    ) -> Result<AccountGroupMutation, AdminError>;
+    async fn delete(
+        &self,
+        context: &MutationContext,
+        command: DeleteAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError>;
+}
+
+pub(crate) struct DefaultAccountGroupService {
+    store: Arc<dyn AccountGroupStore>,
+    runtime: Arc<dyn AccountRuntimeStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultAccountGroupService {
+    #[must_use]
+    pub(crate) fn new(
+        store: Arc<dyn AccountGroupStore>,
+        runtime: Arc<dyn AccountRuntimeStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            store,
+            runtime,
+            snapshot,
+        }
+    }
+
+    async fn enrich_records(&self, records: &mut [AccountGroupRecord]) -> Result<(), AdminError> {
+        if records.is_empty() {
+            return Ok(());
+        }
+        let group_ids = records
+            .iter()
+            .map(|record| record.id.clone())
+            .collect::<Vec<_>>();
+        let members = self
+            .store
+            .load_account_group_members(&group_ids)
+            .await
+            .map_err(|error| map_store_error(error, "account group members"))?;
+        let account_ids = members
+            .iter()
+            .map(|member| member.account_id.clone())
+            .collect::<BTreeSet<_>>()
+            .into_iter()
+            .collect::<Vec<_>>();
+        let runtime = match self.runtime.account_runtime(&account_ids).await {
+            Ok(runtime) => runtime,
+            Err(error) => {
+                tracing::warn!(error = %error, "account group runtime projection is unavailable");
+                Default::default()
+            }
+        };
+        project_group_runtime(records, &members, &runtime);
+        Ok(())
+    }
+
+    async fn publish(
+        &self,
+        result: Result<AccountGroupMutation, crate::ports::store::AdminStoreError>,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        let mut result = result.map_err(|error| map_store_error(error, "account group"))?;
+        if let Some(record) = result.record.as_mut() {
+            self.enrich_records(std::slice::from_mut(record)).await?;
+        }
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+}
+
+#[async_trait]
+impl AccountGroupService for DefaultAccountGroupService {
+    async fn list(&self, query: AccountGroupListQuery) -> Result<AccountGroupPage, AdminError> {
+        let mut page = self
+            .store
+            .list_account_groups(query)
+            .await
+            .map_err(|error| map_store_error(error, "account group"))?;
+        self.enrich_records(&mut page.items).await?;
+        Ok(page)
+    }
+
+    async fn create(
+        &self,
+        context: &MutationContext,
+        command: CreateAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        let id = AccountGroupId::new(format!("grp_{}", Uuid::now_v7().simple()))
+            .map_err(|_| AdminError::internal("创建账号组 ID 失败"))?;
+        self.publish(
+            self.store
+                .create_account_group(
+                    NewAccountGroup {
+                        id,
+                        name: command.name,
+                        description: command.description,
+                        color: command.color,
+                    },
+                    context,
+                )
+                .await,
+        )
+        .await
+    }
+
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        self.publish(self.store.update_account_group(command, context).await)
+            .await
+    }
+
+    async fn set_enabled(
+        &self,
+        context: &MutationContext,
+        command: SetAccountGroupEnabled,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        self.publish(self.store.set_account_group_enabled(command, context).await)
+            .await
+    }
+
+    async fn delete(
+        &self,
+        context: &MutationContext,
+        command: DeleteAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        self.publish(self.store.delete_account_group(command, context).await)
+            .await
+    }
+}
+
+fn project_group_runtime(
+    records: &mut [AccountGroupRecord],
+    members: &[AccountGroupMemberFact],
+    runtime: &crate::model::accounts::AccountRuntimeSnapshot,
+) {
+    let now = SystemTime::now();
+    let mut status_by_account = BTreeMap::new();
+    let mut slots_by_account = BTreeMap::new();
+    let mut accounts_by_group = BTreeMap::<&str, Vec<&str>>::new();
+    for member in members {
+        let mut status = member.status.clone();
+        status.rate_limited_until = runtime
+            .rate_limited_until
+            .get(&member.account_id)
+            .copied()
+            .map(Into::into);
+        status_by_account
+            .entry(member.account_id.as_str())
+            .or_insert_with(|| resolve_account_status(&status, now).status);
+        slots_by_account
+            .entry(member.account_id.as_str())
+            .or_insert(member.total_slots);
+        accounts_by_group
+            .entry(member.group_id.as_str())
+            .or_default()
+            .push(member.account_id.as_str());
+    }
+    for record in records {
+        let account_ids = accounts_by_group
+            .get(record.id.as_str())
+            .map_or(&[][..], Vec::as_slice);
+        let available_ids = account_ids
+            .iter()
+            .copied()
+            .filter(|account_id| status_by_account.get(account_id) == Some(&AccountStatus::Normal))
+            .collect::<Vec<_>>();
+        let total = u64::try_from(account_ids.len()).unwrap_or(u64::MAX);
+        let available = u64::try_from(available_ids.len()).unwrap_or(u64::MAX);
+        record.account_summary = AccountGroupAccountSummary {
+            available,
+            limited: total.saturating_sub(available),
+            total,
+        };
+        record.capacity = AccountGroupCapacity {
+            used_slots: if available_ids.is_empty() {
+                Some(0)
+            } else {
+                runtime.in_flight.as_ref().map(|in_flight| {
+                    available_ids.iter().fold(0_u64, |sum, account_id| {
+                        sum.saturating_add(in_flight.get(*account_id).copied().unwrap_or(0))
+                    })
+                })
+            },
+            total_slots: available_ids.iter().fold(0_u64, |sum, account_id| {
+                sum.saturating_add(slots_by_account.get(*account_id).copied().unwrap_or(0))
+            }),
+        };
+    }
+}

backend/crates/gateway-admin/src/use_case/accounts.rs

@@ -0,0 +1,765 @@
+//! 统一账号目录与跨 Provider 动态分派。
+
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+use chrono::{Duration, Utc};
+use futures::StreamExt as _;
+use gateway_core::{
+    account::ProviderAccountId,
+    engine::probe::{AccountProbe, AccountProbeRequest},
+    routing::{ProviderKind, UpstreamModelId},
+    runtime::SnapshotControl,
+};
+
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        accounts::{
+            AccountConnectionTestEvent, AccountConnectionTestEventStream, AccountListQuery,
+            AccountPageItem, AccountUpdateResult, AccountUsageWindowQuery, AccountsUpdateResult,
+            BatchUpdateAccounts, UpdateAccount,
+        },
+        observability::TimeRange,
+        provider_credentials::{
+            AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
+            ConsumeProviderResetCredit, PrepareCredentialRefresh, ProviderModels,
+            ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+            ProviderQuotaWindow, ProviderResetCreditResult, ProviderResetCredits,
+            QuotaLocalUsageAttribution,
+        },
+    },
+    ports::{
+        provider::ProviderAdminRegistry,
+        store::{AccountRuntimeStore, AccountStore},
+    },
+};
+
+use super::{
+    commit_credential_refresh, map_provider_error, map_store_error, publish_committed,
+    validate_prepared_rotation,
+};
+
+const CONNECTION_TEST_INPUT: &str = "Reply with exactly OK.";
+
+/// 统一账号页消费的服务。
+#[async_trait]
+pub trait AccountsService: Send + Sync {
+    async fn list(&self, query: AccountListQuery) -> Result<AccountDirectoryPage, AdminError>;
+
+    async fn export(
+        &self,
+        context: &MutationContext,
+        account_ids: Vec<ProviderAccountId>,
+    ) -> Result<AccountExportBundle, AdminError>;
+
+    async fn refresh(
+        &self,
+        context: &MutationContext,
+        account_id: ProviderAccountId,
+    ) -> Result<AccountRefreshResult, AdminError>;
+
+    async fn recover(
+        &self,
+        context: &MutationContext,
+        account_id: ProviderAccountId,
+    ) -> Result<AccountRefreshResult, AdminError>;
+
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateAccount,
+    ) -> Result<AccountUpdateResult, AdminError>;
+
+    async fn batch_update(
+        &self,
+        context: &MutationContext,
+        command: BatchUpdateAccounts,
+    ) -> Result<AccountsUpdateResult, AdminError>;
+
+    async fn quota(
+        &self,
+        account_id: &ProviderAccountId,
+        refresh: bool,
+    ) -> Result<AccountDirectoryItem, AdminError>;
+
+    async fn profile_statistics(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持账号统计"))
+    }
+
+    async fn profile_avatar(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持账号头像"))
+    }
+
+    async fn reset_credits(
+        &self,
+        _context: &MutationContext,
+        _account_id: ProviderAccountId,
+    ) -> Result<ProviderResetCredits, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持重置额度"))
+    }
+
+    async fn consume_reset_credit(
+        &self,
+        _context: &MutationContext,
+        _command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持重置额度"))
+    }
+
+    async fn models(
+        &self,
+        account_id: &ProviderAccountId,
+        refresh: bool,
+    ) -> Result<ProviderModels, AdminError>;
+
+    async fn test_connection(
+        &self,
+        account_id: ProviderAccountId,
+        upstream_model: UpstreamModelId,
+    ) -> Result<AccountConnectionTestEventStream, AdminError>;
+}
+
+pub(crate) struct DefaultAccountsService {
+    accounts: Arc<dyn AccountStore>,
+    account_runtime: Arc<dyn AccountRuntimeStore>,
+    providers: ProviderAdminRegistry,
+    snapshot: Arc<dyn SnapshotControl>,
+    probe: Arc<dyn AccountProbe>,
+    reset_credit_locks:
+        Arc<futures::lock::Mutex<BTreeMap<ProviderAccountId, Arc<futures::lock::Mutex<()>>>>>,
+}
+
+impl DefaultAccountsService {
+    #[must_use]
+    pub(crate) fn new(
+        accounts: Arc<dyn AccountStore>,
+        account_runtime: Arc<dyn AccountRuntimeStore>,
+        providers: ProviderAdminRegistry,
+        snapshot: Arc<dyn SnapshotControl>,
+        probe: Arc<dyn AccountProbe>,
+    ) -> Self {
+        Self {
+            accounts,
+            account_runtime,
+            providers,
+            snapshot,
+            probe,
+            reset_credit_locks: Arc::new(futures::lock::Mutex::new(BTreeMap::new())),
+        }
+    }
+
+    async fn reset_credit_lock(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Arc<futures::lock::Mutex<()>> {
+        let mut locks = self.reset_credit_locks.lock().await;
+        Arc::clone(
+            locks
+                .entry(account_id.clone())
+                .or_insert_with(|| Arc::new(futures::lock::Mutex::new(()))),
+        )
+    }
+
+    async fn load_account(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<AccountPageItem, AdminError> {
+        let runtime = self
+            .account_runtime
+            .account_runtime(&[account_id.as_str().to_owned()])
+            .await
+            .map_err(|error| map_store_error(error, "account runtime"))?;
+        self.accounts
+            .load_account(account_id.as_str(), runtime)
+            .await
+            .map_err(|error| map_store_error(error, "provider account"))?
+            .ok_or_else(|| AdminError::not_found("Provider 账号不存在"))
+    }
+
+    async fn provider_for_account(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<
+        (
+            AccountPageItem,
+            Arc<dyn crate::ports::provider::ProviderAdmin>,
+        ),
+        AdminError,
+    > {
+        let item = self.load_account(account_id).await?;
+        let provider = self
+            .providers
+            .require(&item.account.provider_kind)
+            .map_err(|error| map_provider_error(error, "provider account"))?;
+        Ok((item, provider))
+    }
+
+    async fn attach_quota_local_usage(
+        &self,
+        accounts: &[AccountPageItem],
+        quotas: &mut [ProviderQuota],
+    ) -> Result<(), AdminError> {
+        let windows = accounts
+            .iter()
+            .zip(quotas.iter())
+            .flat_map(|(item, quota)| {
+                quota
+                    .windows
+                    .iter()
+                    .filter_map(|window| quota_usage_window(&item.account.id, window))
+            })
+            .collect::<Vec<_>>();
+        if windows.is_empty() {
+            return Ok(());
+        }
+        let usage_by_window = self
+            .accounts
+            .load_account_usage_by_windows(&windows)
+            .await
+            .map_err(|error| map_store_error(error, "quota window usage"))?
+            .into_iter()
+            .map(|result| ((result.account_id, result.key), result.usage))
+            .collect::<BTreeMap<_, _>>();
+        for (item, quota) in accounts.iter().zip(quotas) {
+            for window in &mut quota.windows {
+                if window.local_usage.is_none()
+                    && window.local_usage_attribution == QuotaLocalUsageAttribution::AccountWide
+                {
+                    let key = (item.account.id.clone(), window.key.clone());
+                    if let Some(usage) = usage_by_window.get(&key) {
+                        window.local_usage = Some(usage.clone());
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    async fn load_directory_item(
+        &self,
+        account_id: &ProviderAccountId,
+        refresh_quota: bool,
+    ) -> Result<AccountDirectoryItem, AdminError> {
+        let (stored, provider) = self.provider_for_account(account_id).await?;
+        let account = &stored.account;
+        let now = Utc::now();
+        let rolling_range = TimeRange {
+            start: now - Duration::hours(24),
+            end: now,
+        };
+        let ids = vec![account.id.clone()];
+        let rolling_usage = self
+            .accounts
+            .load_account_usage(rolling_range, &ids)
+            .await
+            .map_err(|error| map_store_error(error, "rolling account usage"))?;
+        let rolling_usage = rolling_usage.into_iter().next();
+        let mut quota = provider
+            .quota(ProviderQuotaRequest {
+                account_id: account_id.clone(),
+                refresh: refresh_quota,
+                rolling_usage: rolling_usage.clone(),
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "provider quota"))?;
+        let stored = if refresh_quota {
+            self.load_account(account_id).await?
+        } else {
+            stored
+        };
+        self.attach_quota_local_usage(
+            std::slice::from_ref(&stored),
+            std::slice::from_mut(&mut quota),
+        )
+        .await?;
+        let usage = quota.representative_window_usage().cloned();
+        Ok(AccountDirectoryItem {
+            projection: stored.projection,
+            usage,
+            account: stored.account,
+            quota,
+        })
+    }
+}
+
+#[async_trait]
+impl AccountsService for DefaultAccountsService {
+    async fn list(&self, query: AccountListQuery) -> Result<AccountDirectoryPage, AdminError> {
+        let runtime = self
+            .account_runtime
+            .active_rate_limits()
+            .await
+            .map_err(|error| map_store_error(error, "account runtime"))?;
+        let page = self
+            .accounts
+            .list_accounts(query, runtime)
+            .await
+            .map_err(|error| map_store_error(error, "account directory"))?;
+        let now = Utc::now();
+        let rolling_range = TimeRange {
+            start: now - Duration::hours(24),
+            end: now,
+        };
+        let ids = page
+            .items
+            .iter()
+            .map(|item| item.account.id.clone())
+            .collect::<Vec<_>>();
+        let rolling_usage = self
+            .accounts
+            .load_account_usage(rolling_range, &ids)
+            .await
+            .map_err(|error| map_store_error(error, "rolling account usage"))?;
+        let rolling_usage = rolling_usage
+            .into_iter()
+            .map(|usage| (usage.account_id.clone(), usage))
+            .collect::<BTreeMap<_, _>>();
+        let mut quotas = futures::future::join_all(page.items.iter().map(|item| async {
+            let account = &item.account;
+            let account_id = ProviderAccountId::new(account.id.clone())
+                .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))?;
+            // 单个账号的 quota 投影失败（Provider 未注册或 quota 读取失败）不拖垮整页：
+            // 该账号降级为空额度投影，其余账号与页面状态照常返回。
+            let provider = match self.providers.require(&account.provider_kind) {
+                Ok(provider) => provider,
+                Err(error) => {
+                    tracing::warn!(
+                        account_id = %account.id,
+                        error = %error,
+                        "account directory provider is not registered; showing empty quota"
+                    );
+                    return Ok(empty_quota());
+                }
+            };
+            match provider
+                .quota(ProviderQuotaRequest {
+                    account_id,
+                    refresh: false,
+                    rolling_usage: rolling_usage.get(&account.id).cloned(),
+                })
+                .await
+            {
+                Ok(quota) => Ok(quota),
+                Err(error) => {
+                    tracing::warn!(
+                        account_id = %account.id,
+                        error = %error,
+                        "account directory quota projection failed; showing empty quota"
+                    );
+                    Ok(empty_quota())
+                }
+            }
+        }))
+        .await
+        .into_iter()
+        .collect::<Result<Vec<_>, AdminError>>()?;
+        self.attach_quota_local_usage(&page.items, &mut quotas)
+            .await?;
+        let items = page
+            .items
+            .into_iter()
+            .zip(quotas)
+            .map(|(item, quota)| {
+                let usage = quota.representative_window_usage().cloned();
+                AccountDirectoryItem {
+                    usage,
+                    account: item.account,
+                    projection: item.projection,
+                    quota,
+                }
+            })
+            .collect();
+        Ok(AccountDirectoryPage {
+            config_revision: page.config_revision,
+            items,
+            total: page.total,
+            summary: page.summary,
+        })
+    }
+
+    async fn export(
+        &self,
+        context: &MutationContext,
+        account_ids: Vec<ProviderAccountId>,
+    ) -> Result<AccountExportBundle, AdminError> {
+        if account_ids.is_empty() || account_ids.len() > 200 {
+            return Err(AdminError::invalid("账号导出数量必须在 1 到 200 之间"));
+        }
+        let exported_ids = account_ids.clone();
+        let mut grouped = BTreeMap::<ProviderKind, Vec<ProviderAccountId>>::new();
+        for account_id in account_ids {
+            let account = self.load_account(&account_id).await?;
+            grouped
+                .entry(account.account.provider_kind)
+                .or_default()
+                .push(account_id);
+        }
+        if grouped.values().any(|ids| {
+            let unique = ids.iter().collect::<std::collections::BTreeSet<_>>();
+            unique.len() != ids.len()
+        }) {
+            return Err(AdminError::invalid("账号导出列表包含重复 ID"));
+        }
+        let mut documents = Vec::with_capacity(grouped.len());
+        for (provider_kind, ids) in grouped {
+            let provider = self
+                .providers
+                .require(&provider_kind)
+                .map_err(|error| map_provider_error(error, "provider account export"))?;
+            let credentials = self
+                .accounts
+                .load_credentials_for_export(&provider_kind, &ids)
+                .await
+                .map_err(|error| map_store_error(error, "provider account export"))?;
+            documents.push(
+                provider
+                    .export_credentials(credentials)
+                    .await
+                    .map_err(|error| map_provider_error(error, "provider account export"))?,
+            );
+        }
+        self.accounts
+            .record_credential_export(&exported_ids, context)
+            .await
+            .map_err(|error| map_store_error(error, "provider account export audit"))?;
+        Ok(AccountExportBundle {
+            exported_at: Utc::now(),
+            documents,
+        })
+    }
+
+    async fn refresh(
+        &self,
+        context: &MutationContext,
+        account_id: ProviderAccountId,
+    ) -> Result<AccountRefreshResult, AdminError> {
+        let (stored, provider) = self.provider_for_account(&account_id).await?;
+        let account = stored.account;
+        let prepared = provider
+            .prepare_refresh(PrepareCredentialRefresh {
+                account: account.clone(),
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "provider credential refresh"))?;
+        validate_prepared_rotation(&account, &prepared, "provider credential refresh")?;
+        let result = commit_credential_refresh(
+            self.accounts.as_ref(),
+            prepared,
+            context,
+            "provider credential refresh",
+        )
+        .await?;
+        provider
+            .account_facts_changed(std::slice::from_ref(&result.account_id))
+            .await;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        let account = self.load_directory_item(&result.account_id, false).await?;
+        Ok(AccountRefreshResult {
+            config_revision: result.config_revision,
+            account,
+        })
+    }
+
+    async fn recover(
+        &self,
+        context: &MutationContext,
+        account_id: ProviderAccountId,
+    ) -> Result<AccountRefreshResult, AdminError> {
+        let (_, provider) = self.provider_for_account(&account_id).await?;
+        let result = self
+            .accounts
+            .recover_account(&account_id, context)
+            .await
+            .map_err(|error| map_store_error(error, "provider account recovery"))?;
+        provider
+            .account_facts_changed(std::slice::from_ref(&account_id))
+            .await;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        let account = self.load_directory_item(&account_id, false).await?;
+        Ok(AccountRefreshResult {
+            config_revision: result.config_revision,
+            account,
+        })
+    }
+
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateAccount,
+    ) -> Result<AccountUpdateResult, AdminError> {
+        let account_id = ProviderAccountId::new(command.account_id.clone())
+            .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))?;
+        let (_, provider) = self.provider_for_account(&account_id).await?;
+        let enabled = command.enabled;
+        let result = self
+            .accounts
+            .update_account(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "provider account"))?;
+        if !enabled {
+            provider.account_unavailable(&account_id).await;
+        }
+        provider
+            .account_facts_changed(std::slice::from_ref(&account_id))
+            .await;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    async fn batch_update(
+        &self,
+        context: &MutationContext,
+        command: BatchUpdateAccounts,
+    ) -> Result<AccountsUpdateResult, AdminError> {
+        let account_ids = command
+            .account_ids
+            .iter()
+            .map(|id| {
+                ProviderAccountId::new(id.clone())
+                    .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        let mut providers = BTreeMap::<
+            ProviderKind,
+            (
+                Arc<dyn crate::ports::provider::ProviderAdmin>,
+                Vec<ProviderAccountId>,
+            ),
+        >::new();
+        for account_id in &account_ids {
+            let (item, provider) = self.provider_for_account(account_id).await?;
+            providers
+                .entry(item.account.provider_kind)
+                .or_insert_with(|| (provider, Vec::new()))
+                .1
+                .push(account_id.clone());
+        }
+        let enabled = command.enabled;
+        let result = self
+            .accounts
+            .batch_update_accounts(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "provider accounts"))?;
+        for (provider, provider_ids) in providers.values() {
+            if !enabled {
+                for account_id in provider_ids {
+                    provider.account_unavailable(account_id).await;
+                }
+            }
+            provider.account_facts_changed(provider_ids).await;
+        }
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    async fn quota(
+        &self,
+        account_id: &ProviderAccountId,
+        refresh: bool,
+    ) -> Result<AccountDirectoryItem, AdminError> {
+        self.load_directory_item(account_id, refresh).await
+    }
+
+    async fn profile_statistics(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, AdminError> {
+        let (_, provider) = self.provider_for_account(account_id).await?;
+        provider
+            .profile_statistics(account_id)
+            .await
+            .map_err(|error| map_provider_error(error, "provider profile statistics"))
+    }
+
+    async fn profile_avatar(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, AdminError> {
+        let (_, provider) = self.provider_for_account(account_id).await?;
+        provider
+            .profile_avatar(account_id)
+            .await
+            .map_err(|error| map_provider_error(error, "provider profile avatar"))
+    }
+
+    async fn reset_credits(
+        &self,
+        context: &MutationContext,
+        account_id: ProviderAccountId,
+    ) -> Result<ProviderResetCredits, AdminError> {
+        let (_, provider) = self.provider_for_account(&account_id).await?;
+        match provider.reset_credits(&account_id).await {
+            Ok(credits) => Ok(credits),
+            Err(error)
+                if error.kind()
+                    == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired =>
+            {
+                self.refresh(context, account_id.clone()).await?;
+                let (_, provider) = self.provider_for_account(&account_id).await?;
+                provider
+                    .reset_credits(&account_id)
+                    .await
+                    .map_err(map_reset_credits_error_after_refresh)
+            }
+            Err(error) => Err(map_provider_error(error, "provider reset credits")),
+        }
+    }
+
+    async fn consume_reset_credit(
+        &self,
+        context: &MutationContext,
+        command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, AdminError> {
+        let account_id = command.account_id.clone();
+        // 覆盖 credential refresh + 同键重试的完整账号级临界区，避免 401 两次调用
+        // 之间插入另一笔不可逆消费。
+        let lock = self.reset_credit_lock(&account_id).await;
+        let _guard = lock.lock().await;
+        let (_, provider) = self.provider_for_account(&account_id).await?;
+        match provider.consume_reset_credit(command.clone()).await {
+            Ok(result) => Ok(result),
+            Err(error)
+                if error.kind()
+                    == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired =>
+            {
+                self.refresh(context, account_id.clone()).await?;
+                let (_, provider) = self.provider_for_account(&account_id).await?;
+                provider
+                    .consume_reset_credit(command)
+                    .await
+                    .map_err(map_reset_credits_error_after_refresh)
+            }
+            Err(error) => Err(map_provider_error(error, "provider reset-credit consume")),
+        }
+    }
+
+    async fn models(
+        &self,
+        account_id: &ProviderAccountId,
+        refresh: bool,
+    ) -> Result<ProviderModels, AdminError> {
+        let (_, provider) = self.provider_for_account(account_id).await?;
+        provider
+            .models(account_id, refresh)
+            .await
+            .map_err(|error| map_provider_error(error, "provider model catalog"))
+    }
+
+    async fn test_connection(
+        &self,
+        account_id: ProviderAccountId,
+        upstream_model: UpstreamModelId,
+    ) -> Result<AccountConnectionTestEventStream, AdminError> {
+        let (stored, provider) = self.provider_for_account(&account_id).await?;
+        let account = stored.account;
+        let model = upstream_model.as_str().to_owned();
+        let operation = provider
+            .connection_test_operation(&upstream_model, CONNECTION_TEST_INPUT)
+            .map_err(|error| map_provider_error(error, "provider connection test"))?;
+        let initial = vec![
+            AccountConnectionTestEvent::Started {
+                model: model.clone(),
+            },
+            AccountConnectionTestEvent::Request {
+                model,
+                input_text: CONNECTION_TEST_INPUT.to_owned(),
+                stream: true,
+                store: false,
+            },
+        ];
+        let probe = Arc::clone(&self.probe);
+        let terminal = futures::stream::once(async move {
+            let result = probe
+                .probe(AccountProbeRequest {
+                    account_id,
+                    provider_kind: account.provider_kind,
+                    upstream_model,
+                    operation,
+                })
+                .await;
+            match result {
+                Ok(result) => result
+                    .text
+                    .into_iter()
+                    .map(|text| AccountConnectionTestEvent::Content { text })
+                    .chain(std::iter::once(AccountConnectionTestEvent::Completed))
+                    .collect(),
+                Err(error) => {
+                    let upstream_status = error
+                        .upstream_response()
+                        .map(gateway_core::engine::probe::AccountProbeUpstreamResponse::status);
+                    let upstream_content_type = error
+                        .upstream_response()
+                        .and_then(|response| response.content_type())
+                        .and_then(|value| std::str::from_utf8(value).ok())
+                        .map(ToOwned::to_owned);
+                    let upstream_body = error
+                        .upstream_response()
+                        .map(|response| String::from_utf8_lossy(response.body()).into_owned());
+                    let message = error.client_message().to_owned();
+                    vec![AccountConnectionTestEvent::Failed {
+                        source: error.source(),
+                        gateway_error_code: error.kind(),
+                        send_state: error.send_state(),
+                        message,
+                        provider_error_code: error.client_error_code().map(ToOwned::to_owned),
+                        provider_error_type: error.client_error_type().map(ToOwned::to_owned),
+                        upstream_status,
+                        upstream_content_type,
+                        upstream_body,
+                    }]
+                }
+            }
+        })
+        .flat_map(futures::stream::iter);
+        Ok(Box::pin(futures::stream::iter(initial).chain(terminal)))
+    }
+}
+
+fn map_reset_credits_error_after_refresh(
+    error: crate::ports::provider::ProviderAdminError,
+) -> AdminError {
+    if error.kind() == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired {
+        return AdminError::bad_gateway("上游服务拒绝了刷新后的凭据");
+    }
+    map_provider_error(error, "provider reset credits")
+}
+
+/// 账号目录中单个账号 quota 读取失败时使用的空额度投影。
+fn empty_quota() -> ProviderQuota {
+    ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: Vec::new(),
+        limit_reached: false,
+        provider_data: None,
+    }
+}
+
+fn quota_usage_window(
+    account_id: &str,
+    window: &ProviderQuotaWindow,
+) -> Option<AccountUsageWindowQuery> {
+    if window.local_usage.is_some()
+        || window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide
+    {
+        return None;
+    }
+    let reset_at = window.reset_at?;
+    let seconds = i64::try_from(window.window_seconds?).ok()?;
+    let start = reset_at.checked_sub_signed(Duration::seconds(seconds))?;
+    let range = TimeRange::new(start, reset_at).ok()?;
+    // 上游百分比以该 reset 边界定义；以当前时间回推会让本地 Token 属于另一窗口。
+    Some(AccountUsageWindowQuery {
+        account_id: account_id.to_owned(),
+        key: window.key.clone(),
+        range,
+    })
+}

backend/crates/gateway-admin/src/use_case/auth.rs

@@ -0,0 +1,222 @@
+//! 管理员认证状态机。
+
+use std::sync::Arc;
+
+use argon2::{Argon2, PasswordHash, PasswordHasher, PasswordVerifier};
+use async_trait::async_trait;
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use chrono::{Duration, Utc};
+use rand_core::{OsRng, RngCore as _};
+use subtle::ConstantTimeEq as _;
+use uuid::Uuid;
+
+use crate::{
+    model::{
+        AdminError,
+        auth::{
+            AdminAuditEvent, AdminSession, AuditActorKind, LoginCommand, LoginError, LoginResult,
+        },
+    },
+    ports::store::AuthStore,
+};
+
+use super::map_store_error;
+
+/// API 鉴权与管理员登录消费的统一服务。
+#[async_trait]
+pub trait AuthService: Send + Sync {
+    async fn ensure_default_admin(&self, password: &str) -> Result<bool, AdminError>;
+    async fn resolve_admin_user_id(
+        &self,
+        session_id: Option<&str>,
+    ) -> Result<Option<String>, AdminError>;
+    async fn verify_admin_api_key(&self, key: &str) -> Result<bool, AdminError>;
+    async fn login(&self, command: LoginCommand) -> Result<LoginResult, LoginError>;
+    async fn validate_session(&self, session_id: Option<&str>) -> Result<bool, AdminError>;
+    async fn logout(&self, session_id: &str) -> Result<(), AdminError>;
+}
+
+/// 会话有效期上限(366 天);超出的配置按上限截断,保证 TTL 构造与
+/// `Utc::now() + session_ttl` 永不越界。
+const MAX_SESSION_TTL_MINUTES: i64 = 366 * 24 * 60;
+
+/// 单管理员认证策略的最终实现。
+pub(crate) struct DefaultAuthService {
+    default_admin_user_id: String,
+    session_ttl: Duration,
+    store: Arc<dyn AuthStore>,
+}
+
+impl DefaultAuthService {
+    #[must_use]
+    pub(crate) fn new(
+        default_admin_user_id: impl Into<String>,
+        session_ttl_minutes: u64,
+        store: Arc<dyn AuthStore>,
+    ) -> Self {
+        let minutes = i64::try_from(session_ttl_minutes)
+            .unwrap_or(MAX_SESSION_TTL_MINUTES)
+            .clamp(1, MAX_SESSION_TTL_MINUTES);
+        Self {
+            default_admin_user_id: default_admin_user_id.into(),
+            session_ttl: Duration::minutes(minutes),
+            store,
+        }
+    }
+
+    fn auth_audit(&self, action: &str, occurred_at: chrono::DateTime<Utc>) -> AdminAuditEvent {
+        AdminAuditEvent {
+            id: format!("audit_{}", Uuid::now_v7().simple()),
+            actor_kind: AuditActorKind::AdminSession,
+            actor_admin_user_id: Some(self.default_admin_user_id.clone()),
+            actor_ref: crate::model::auth::admin_session_actor_ref(&self.default_admin_user_id),
+            request_id: None,
+            action: action.to_owned(),
+            entity_kind: "admin_session".to_owned(),
+            entity_ref: self.default_admin_user_id.clone(),
+            config_revision: None,
+            changed_fields: Vec::new(),
+            occurred_at,
+        }
+    }
+}
+
+#[async_trait]
+impl AuthService for DefaultAuthService {
+    async fn ensure_default_admin(&self, password: &str) -> Result<bool, AdminError> {
+        let hash = hash_admin_password(password)?;
+        self.store
+            .create_password_hash_if_absent(&self.default_admin_user_id, &hash)
+            .await
+            .map_err(|error| map_store_error(error, "administrator"))
+    }
+
+    async fn resolve_admin_user_id(
+        &self,
+        session_id: Option<&str>,
+    ) -> Result<Option<String>, AdminError> {
+        let Some(session_id) = session_id else {
+            return Ok(None);
+        };
+        self.store
+            .load_session(session_id)
+            .await
+            .map(|session| {
+                session
+                    .filter(|session| session.expires_at > Utc::now())
+                    .map(|session| session.admin_user_id)
+            })
+            .map_err(|error| map_store_error(error, "administrator session"))
+    }
+
+    async fn verify_admin_api_key(&self, key: &str) -> Result<bool, AdminError> {
+        if !valid_admin_api_key_shape(key) {
+            return Ok(false);
+        }
+        let stored = self
+            .store
+            .load_admin_api_key()
+            .await
+            .map_err(|error| map_store_error(error, "administrator API key"))?;
+        Ok(stored.as_ref().is_some_and(|stored| {
+            let stored = stored.expose_for_auth();
+            key.len() == stored.len() && bool::from(key.as_bytes().ct_eq(stored.as_bytes()))
+        }))
+    }
+
+    async fn login(&self, command: LoginCommand) -> Result<LoginResult, LoginError> {
+        if command
+            .username
+            .as_deref()
+            .unwrap_or(&self.default_admin_user_id)
+            != self.default_admin_user_id
+        {
+            return Err(LoginError::InvalidCredentials);
+        }
+        let hash = self
+            .store
+            .load_password_hash(&self.default_admin_user_id)
+            .await
+            .map_err(|_| LoginError::Unavailable)?
+            .ok_or(LoginError::InvalidCredentials)?;
+        if !verify_admin_password(&command.password, &hash).map_err(|_| LoginError::Unavailable)? {
+            return Err(LoginError::InvalidCredentials);
+        }
+
+        let session_id = random_session_token();
+        let expires_at = Utc::now() + self.session_ttl;
+        self.store
+            .store_session(
+                &session_id,
+                &AdminSession {
+                    admin_user_id: self.default_admin_user_id.clone(),
+                    expires_at,
+                },
+            )
+            .await
+            .map_err(|_| LoginError::Unavailable)?;
+        if self
+            .store
+            .append_audit_event(self.auth_audit("admin.login", Utc::now()))
+            .await
+            .is_err()
+        {
+            let _ = self.store.delete_session(&session_id).await;
+            return Err(LoginError::Unavailable);
+        }
+        Ok(LoginResult {
+            session_id,
+            expires_at,
+        })
+    }
+
+    async fn validate_session(&self, session_id: Option<&str>) -> Result<bool, AdminError> {
+        Ok(self.resolve_admin_user_id(session_id).await?.is_some())
+    }
+
+    async fn logout(&self, session_id: &str) -> Result<(), AdminError> {
+        let session = self
+            .store
+            .delete_session(session_id)
+            .await
+            .map_err(|error| map_store_error(error, "administrator session"))?;
+        if let Some(session) = session {
+            let mut event = self.auth_audit("admin.logout", Utc::now());
+            event.actor_admin_user_id = Some(session.admin_user_id.clone());
+            event.actor_ref = crate::model::auth::admin_session_actor_ref(&session.admin_user_id);
+            event.entity_ref = session.admin_user_id;
+            self.store
+                .append_audit_event(event)
+                .await
+                .map_err(|error| map_store_error(error, "administrator audit"))?;
+        }
+        Ok(())
+    }
+}
+
+fn hash_admin_password(password: &str) -> Result<String, AdminError> {
+    Argon2::default()
+        .hash_password(password.as_bytes())
+        .map(|hash| hash.to_string())
+        .map_err(|_| AdminError::internal("管理员密码哈希失败"))
+}
+
+fn verify_admin_password(password: &str, encoded: &str) -> Result<bool, AdminError> {
+    let hash = PasswordHash::new(encoded)
+        .map_err(|_| AdminError::internal("已保存的管理员密码哈希不合法"))?;
+    Ok(Argon2::default()
+        .verify_password(password.as_bytes(), &hash)
+        .is_ok())
+}
+
+fn random_session_token() -> String {
+    let mut bytes = [0_u8; 32];
+    OsRng.fill_bytes(&mut bytes);
+    format!("session_{}", URL_SAFE_NO_PAD.encode(bytes))
+}
+
+fn valid_admin_api_key_shape(value: &str) -> bool {
+    value.len() == 70
+        && value.starts_with("admin-")
+        && value[6..].bytes().all(|byte| byte.is_ascii_hexdigit())
+}

backend/crates/gateway-admin/src/use_case/backup.rs

@@ -0,0 +1,437 @@
+//! 备份配置、手动创建、下载与删除用例。
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use gateway_core::runtime::SnapshotControl;
+use secrecy::ExposeSecret as _;
+use uuid::Uuid;
+
+use crate::model::{
+    AdminError, AdminErrorKind, MutationContext,
+    auth::{AdminAuditEvent, AuditActorKind},
+    backup::{
+        BackupError, BackupRecord, BackupRecordListQuery, BackupRecordPage, BackupSettings,
+        BackupStatus, BackupStorageConfig, BackupTriggerKind, ConnectionTestResult,
+        DownloadUrlResult, UpdateBackupScheduleCommand, UpdateBackupStorageCommand,
+        build_backup_seed, code,
+    },
+};
+use crate::ports::{
+    backup::{BackupObjectStorePort, BackupRepository},
+    store::AuthStore,
+};
+
+use super::map_store_error;
+
+/// 默认下载地址有效期。
+const DOWNLOAD_TTL: Duration = Duration::from_secs(5 * 60);
+
+/// API 消费的备份管理服务。
+#[async_trait]
+pub trait BackupService: Send + Sync {
+    async fn load_settings(&self) -> Result<BackupSettings, AdminError>;
+
+    async fn update_storage(
+        &self,
+        context: &MutationContext,
+        command: UpdateBackupStorageCommand,
+    ) -> Result<BackupSettings, AdminError>;
+
+    async fn update_schedule(
+        &self,
+        context: &MutationContext,
+        command: UpdateBackupScheduleCommand,
+    ) -> Result<BackupSettings, AdminError>;
+
+    async fn test_connection(
+        &self,
+        context: &MutationContext,
+    ) -> Result<ConnectionTestResult, AdminError>;
+
+    async fn create_backup(
+        &self,
+        context: &MutationContext,
+        expires_at: Option<DateTime<Utc>>,
+    ) -> Result<BackupRecord, AdminError>;
+
+    async fn list_records(
+        &self,
+        query: BackupRecordListQuery,
+    ) -> Result<BackupRecordPage, AdminError>;
+
+    async fn download_url(
+        &self,
+        context: &MutationContext,
+        backup_id: &str,
+    ) -> Result<DownloadUrlResult, AdminError>;
+
+    async fn delete_backup(
+        &self,
+        context: &MutationContext,
+        backup_id: &str,
+    ) -> Result<BackupRecord, AdminError>;
+}
+
+pub(crate) struct DefaultBackupService {
+    repository: Arc<dyn BackupRepository>,
+    object_store: Arc<dyn BackupObjectStorePort>,
+    auth: Arc<dyn AuthStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultBackupService {
+    #[must_use]
+    pub(crate) fn new(
+        repository: Arc<dyn BackupRepository>,
+        object_store: Arc<dyn BackupObjectStorePort>,
+        auth: Arc<dyn AuthStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            repository,
+            object_store,
+            auth,
+            snapshot,
+        }
+    }
+}
+
+#[async_trait]
+impl BackupService for DefaultBackupService {
+    async fn load_settings(&self) -> Result<BackupSettings, AdminError> {
+        self.repository
+            .load_settings()
+            .await
+            .map_err(|error| map_store_error(error, "backup settings"))
+    }
+
+    async fn update_storage(
+        &self,
+        context: &MutationContext,
+        command: UpdateBackupStorageCommand,
+    ) -> Result<BackupSettings, AdminError> {
+        validate_storage(&command)?;
+        let (settings, revision) = self
+            .repository
+            .update_storage_settings(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "backup storage"))?;
+        super::publish_committed(self.snapshot.as_ref(), revision).await?;
+        Ok(settings)
+    }
+
+    async fn update_schedule(
+        &self,
+        context: &MutationContext,
+        command: UpdateBackupScheduleCommand,
+    ) -> Result<BackupSettings, AdminError> {
+        validate_schedule(&command)?;
+        let next_run_at = if command.schedule_enabled {
+            Some(
+                crate::backup::policy::BackupSchedule::parse(
+                    &command.cron_expression,
+                    &command.schedule_timezone,
+                )
+                .map_err(map_backup_error)?
+                .next_after(Utc::now())
+                .ok_or_else(|| AdminError::bad_request("无法从计划推导下次执行时间"))?,
+            )
+        } else {
+            None
+        };
+        self.repository
+            .update_schedule_settings(command, next_run_at, context)
+            .await
+            .map_err(|error| map_store_error(error, "backup schedule"))
+    }
+
+    async fn test_connection(
+        &self,
+        context: &MutationContext,
+    ) -> Result<ConnectionTestResult, AdminError> {
+        let settings = self
+            .repository
+            .load_settings()
+            .await
+            .map_err(|error| map_store_error(error, "backup settings"))?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Ok(ConnectionTestResult {
+                ok: false,
+                stage: "putObject",
+                code: Some(code::INVALID_CONFIG),
+                message: "备份存储配置不完整，无法执行连接测试".to_owned(),
+            });
+        };
+        let result = self
+            .object_store
+            .test_connection(&config)
+            .await
+            .map_err(map_backup_error)?;
+        if result.ok {
+            let _ = self
+                .repository
+                .record_verification(config.storage_revision, Utc::now())
+                .await
+                .map_err(|error| map_store_error(error, "backup settings"))?;
+        }
+        self.append_audit(
+            context,
+            "backup.s3_connection_tested",
+            "backup_settings",
+            vec![],
+        )
+        .await?;
+        Ok(result)
+    }
+
+    async fn create_backup(
+        &self,
+        context: &MutationContext,
+        expires_at: Option<DateTime<Utc>>,
+    ) -> Result<BackupRecord, AdminError> {
+        let settings = self
+            .repository
+            .load_settings()
+            .await
+            .map_err(|error| map_store_error(error, "backup settings"))?;
+        if !settings.storage_configured() {
+            return Err(AdminError::bad_request(
+                "备份存储配置不完整，请先保存存储配置",
+            ));
+        }
+        if !settings.storage_verified() {
+            return Err(AdminError::bad_request(
+                "备份存储尚未通过连接测试，请先测试存储配置",
+            ));
+        }
+        let prefix = settings.prefix.as_deref().unwrap_or_default();
+        let seed = build_backup_seed(
+            BackupTriggerKind::Manual,
+            None,
+            prefix,
+            Utc::now(),
+            expires_at,
+        )
+        .map_err(map_backup_error)?;
+        let record = self
+            .repository
+            .insert_backup_record(seed)
+            .await
+            .map_err(|error| map_store_error(error, "backup record"))?;
+        self.append_audit(context, "backup.created", "backup", vec![record.id.clone()])
+            .await?;
+        Ok(record)
+    }
+
+    async fn list_records(
+        &self,
+        query: BackupRecordListQuery,
+    ) -> Result<BackupRecordPage, AdminError> {
+        self.repository
+            .list_backup_records(query)
+            .await
+            .map_err(|error| map_store_error(error, "backup records"))
+    }
+
+    async fn download_url(
+        &self,
+        context: &MutationContext,
+        backup_id: &str,
+    ) -> Result<DownloadUrlResult, AdminError> {
+        let record = self.require_record(backup_id).await?;
+        if record.status != BackupStatus::Completed {
+            return Err(AdminError::conflict(
+                "只有 completed 的备份才能创建下载地址",
+            ));
+        }
+        let settings = self
+            .repository
+            .load_settings()
+            .await
+            .map_err(|error| map_store_error(error, "backup settings"))?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Err(AdminError::bad_request("备份存储配置不完整"));
+        };
+        let file_name = crate::model::backup::build_download_file_name(backup_id);
+        let url = self
+            .object_store
+            .presigned_download(&config, &record.object_key, &file_name, DOWNLOAD_TTL)
+            .await
+            .map_err(map_backup_error)?;
+        self.append_audit(
+            context,
+            "backup.download_url_created",
+            "backup",
+            vec![backup_id.to_owned()],
+        )
+        .await?;
+        Ok(DownloadUrlResult {
+            url,
+            file_name,
+            expires_in: DOWNLOAD_TTL,
+        })
+    }
+
+    async fn delete_backup(
+        &self,
+        context: &MutationContext,
+        backup_id: &str,
+    ) -> Result<BackupRecord, AdminError> {
+        let record = self.require_record(backup_id).await?;
+        if !record.status.can_be_deleted() {
+            return Err(AdminError::conflict(
+                "只有 completed 或 failed 的备份才能删除",
+            ));
+        }
+        let now = Utc::now();
+        let deleting = self
+            .repository
+            .transition_to_deleting(backup_id, now)
+            .await
+            .map_err(|error| map_store_error(error, "backup record"))?
+            .ok_or_else(|| AdminError::conflict("备份记录已进入删除流程"))?;
+        self.append_audit(
+            context,
+            "backup.delete_requested",
+            "backup",
+            vec![backup_id.to_owned()],
+        )
+        .await?;
+        Ok(deleting)
+    }
+}
+
+impl DefaultBackupService {
+    async fn require_record(&self, backup_id: &str) -> Result<BackupRecord, AdminError> {
+        self.repository
+            .load_backup_record(backup_id)
+            .await
+            .map_err(|error| map_store_error(error, "backup record"))?
+            .ok_or_else(|| AdminError::not_found("备份记录不存在"))
+    }
+
+    async fn append_audit(
+        &self,
+        context: &MutationContext,
+        action: &str,
+        entity_ref: &str,
+        changed_fields: Vec<String>,
+    ) -> Result<(), AdminError> {
+        let actor_kind = match context.actor {
+            crate::model::MutationActor::AdminSession { .. } => AuditActorKind::AdminSession,
+            crate::model::MutationActor::AdminApiKey => AuditActorKind::AdminApiKey,
+            crate::model::MutationActor::System => AuditActorKind::System,
+        };
+        let actor_ref = match &context.actor {
+            crate::model::MutationActor::AdminSession { admin_user_id } => {
+                crate::model::auth::admin_session_actor_ref(admin_user_id)
+            }
+            crate::model::MutationActor::AdminApiKey => "admin_api_key".to_owned(),
+            crate::model::MutationActor::System => "system".to_owned(),
+        };
+        let actor_admin_user_id = match &context.actor {
+            crate::model::MutationActor::AdminSession { admin_user_id } => {
+                Some(admin_user_id.clone())
+            }
+            _ => None,
+        };
+        let event = AdminAuditEvent {
+            id: format!("audit_{}", Uuid::now_v7().simple()),
+            actor_kind,
+            actor_admin_user_id,
+            actor_ref,
+            request_id: Some(context.request_id.clone()),
+            action: action.to_owned(),
+            entity_kind: "backup".to_owned(),
+            entity_ref: entity_ref.to_owned(),
+            config_revision: None,
+            changed_fields,
+            occurred_at: Utc::now(),
+        };
+        self.auth
+            .append_audit_event(event)
+            .await
+            .map_err(|error| map_store_error(error, "backup audit"))
+    }
+}
+
+/// 校验存储配置；空串视为非法，Secret 缺省表示保留旧值。
+fn validate_storage(command: &UpdateBackupStorageCommand) -> Result<(), AdminError> {
+    validate_endpoint(&command.endpoint)?;
+    validate_nonempty("region", &command.region)?;
+    validate_nonempty("bucket", &command.bucket)?;
+    validate_nonempty("accessKeyId", &command.access_key_id)?;
+    if let Some(secret) = command.secret_access_key.as_ref() {
+        let value = secret.expose_secret();
+        if value.is_empty() {
+            return Err(AdminError::bad_request(
+                "secretAccessKey 不能为空字符串；缺省表示保留旧值",
+            ));
+        }
+        validate_length("secretAccessKey", value, 512)?;
+    }
+    crate::model::backup::normalize_prefix(&command.prefix).map_err(map_backup_error)?;
+    Ok(())
+}
+
+fn validate_endpoint(value: &str) -> Result<(), AdminError> {
+    if value.is_empty() {
+        return Err(AdminError::bad_request("endpoint 不能为空"));
+    }
+    if !value.starts_with("https://") {
+        return Err(AdminError::bad_request(
+            "endpoint 必须使用 HTTPS；仅测试或显式开发配置允许 HTTP",
+        ));
+    }
+    if value.contains('@') || value.bytes().any(|byte| byte.is_ascii_control()) {
+        return Err(AdminError::bad_request("endpoint 格式非法"));
+    }
+    validate_length("endpoint", value, 2048)
+}
+
+fn validate_nonempty(field: &str, value: &str) -> Result<(), AdminError> {
+    if value.is_empty() {
+        return Err(AdminError::bad_request(format!("{field} 不能为空")));
+    }
+    validate_length(field, value, 255)
+}
+
+fn validate_length(field: &str, value: &str, max: usize) -> Result<(), AdminError> {
+    if value.len() > max || value.bytes().any(|byte| byte.is_ascii_control()) {
+        return Err(AdminError::bad_request(format!(
+            "{field} 超出长度或包含非法字符"
+        )));
+    }
+    Ok(())
+}
+
+/// 校验调度配置并解析 Cron 与时区。
+fn validate_schedule(command: &UpdateBackupScheduleCommand) -> Result<(), AdminError> {
+    if command.cron_expression.trim().is_empty() {
+        return Err(AdminError::bad_request("cronExpression 不能为空"));
+    }
+    crate::backup::policy::BackupSchedule::parse(
+        &command.cron_expression,
+        &command.schedule_timezone,
+    )
+    .map_err(map_backup_error)?;
+    Ok(())
+}
+
+/// 备份基础设施错误到既有 `AdminErrorKind` 的唯一边界映射。
+fn map_backup_error(error: BackupError) -> AdminError {
+    match error.code() {
+        code::INVALID_CONFIG | code::INVALID_CRON | code::INVALID_TIMEZONE => {
+            AdminError::bad_request(error.message().to_owned())
+        }
+        code::RECORD_NOT_FOUND => AdminError::not_found(error.message().to_owned()),
+        code::ACTIVE_TASK_CONFLICT | code::STATE_CONFLICT | code::STORAGE_IDENTITY_LOCKED => {
+            AdminError::conflict(error.message().to_owned())
+        }
+        code::STORE_UNAVAILABLE => AdminError::new(AdminErrorKind::Unavailable, "备份服务暂不可用"),
+        _ => AdminError::bad_gateway("备份服务请求失败"),
+    }
+}

backend/crates/gateway-admin/src/use_case/client_distribution.rs

@@ -0,0 +1,33 @@
+//! Codex 客户端下载信息用例。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use crate::{
+    model::client_distribution::CodexDesktopWindowsDownloads,
+    ports::client_distribution::ClientDistributionResolver,
+};
+
+#[async_trait]
+pub trait ClientDistributionService: Send + Sync {
+    async fn codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads;
+}
+
+pub(crate) struct DefaultClientDistributionService {
+    resolver: Arc<dyn ClientDistributionResolver>,
+}
+
+impl DefaultClientDistributionService {
+    #[must_use]
+    pub(crate) const fn new(resolver: Arc<dyn ClientDistributionResolver>) -> Self {
+        Self { resolver }
+    }
+}
+
+#[async_trait]
+impl ClientDistributionService for DefaultClientDistributionService {
+    async fn codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads {
+        self.resolver.resolve_codex_desktop_windows(refresh).await
+    }
+}

backend/crates/gateway-admin/src/use_case/client_keys.rs

@@ -0,0 +1,203 @@
+//! Client API Key 管理用例。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use gateway_core::policy::ClientApiKeyId;
+use gateway_core::runtime::SnapshotControl;
+use rand_core::{OsRng, RngCore as _};
+use uuid::Uuid;
+
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        client_keys::{
+            ClientKeyCursorValue, ClientKeyListQuery, ClientKeyMutation, ClientKeyPage,
+            ClientKeySecret, ClientKeySortField, CreateClientKey, CreatedClientKey,
+            DeleteClientKey, NewClientKey, SetClientKeyEnabled, UpdateClientKey,
+        },
+    },
+    ports::store::ClientKeyStore,
+};
+
+use super::{map_store_error, publish_committed};
+
+/// API 消费的 Client Key 管理服务。
+#[async_trait]
+pub trait ClientKeyService: Send + Sync {
+    async fn list(&self, query: ClientKeyListQuery) -> Result<ClientKeyPage, AdminError>;
+    async fn reveal(&self, id: &ClientApiKeyId) -> Result<ClientKeySecret, AdminError>;
+    async fn create(
+        &self,
+        context: &MutationContext,
+        command: CreateClientKey,
+    ) -> Result<CreatedClientKey, AdminError>;
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateClientKey,
+    ) -> Result<ClientKeyMutation, AdminError>;
+    async fn set_enabled(
+        &self,
+        context: &MutationContext,
+        command: SetClientKeyEnabled,
+    ) -> Result<ClientKeyMutation, AdminError>;
+    async fn delete(
+        &self,
+        context: &MutationContext,
+        command: DeleteClientKey,
+    ) -> Result<ClientKeyMutation, AdminError>;
+}
+
+pub(crate) struct DefaultClientKeyService {
+    store: Arc<dyn ClientKeyStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultClientKeyService {
+    #[must_use]
+    pub(crate) fn new(store: Arc<dyn ClientKeyStore>, snapshot: Arc<dyn SnapshotControl>) -> Self {
+        Self { store, snapshot }
+    }
+}
+
+#[async_trait]
+impl ClientKeyService for DefaultClientKeyService {
+    async fn list(&self, query: ClientKeyListQuery) -> Result<ClientKeyPage, AdminError> {
+        validate_cursor(&query)?;
+        self.store
+            .list_client_keys(query)
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))
+    }
+
+    async fn reveal(&self, id: &ClientApiKeyId) -> Result<ClientKeySecret, AdminError> {
+        self.store
+            .reveal_client_key(id)
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))?
+            .ok_or_else(|| AdminError::not_found("Client API Key 不存在"))
+    }
+
+    async fn create(
+        &self,
+        context: &MutationContext,
+        command: CreateClientKey,
+    ) -> Result<CreatedClientKey, AdminError> {
+        let id = ClientApiKeyId::new(format!("key_{}", Uuid::now_v7().simple()))
+            .map_err(|_| AdminError::internal("创建 Client API Key ID 失败"))?;
+        let mut bytes = [0_u8; 32];
+        OsRng.fill_bytes(&mut bytes);
+        let plaintext = format!("sk_{}", URL_SAFE_NO_PAD.encode(bytes));
+        let (config_revision, record) = self
+            .store
+            .create_client_key(
+                NewClientKey {
+                    id,
+                    name: command.name,
+                    label: command.label,
+                    group_ids: command.group_ids,
+                    limits: command.limits,
+                    plaintext: plaintext.clone(),
+                },
+                context,
+            )
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))?;
+        publish_committed(self.snapshot.as_ref(), config_revision).await?;
+        Ok(CreatedClientKey {
+            config_revision,
+            secret: ClientKeySecret::new(record, plaintext),
+        })
+    }
+
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateClientKey,
+    ) -> Result<ClientKeyMutation, AdminError> {
+        let id = command.id.clone();
+        let (config_revision, record) = self
+            .store
+            .update_client_key(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))?;
+        publish_committed(self.snapshot.as_ref(), config_revision).await?;
+        Ok(ClientKeyMutation {
+            config_revision,
+            record: Some(record),
+            id,
+        })
+    }
+
+    async fn set_enabled(
+        &self,
+        context: &MutationContext,
+        command: SetClientKeyEnabled,
+    ) -> Result<ClientKeyMutation, AdminError> {
+        let id = command.id.clone();
+        let (config_revision, record) =
+            self.store
+                .set_client_key_enabled(command, context)
+                .await
+                .map_err(|error| map_store_error(error, "client API key"))?;
+        publish_committed(self.snapshot.as_ref(), config_revision).await?;
+        Ok(ClientKeyMutation {
+            config_revision,
+            record: Some(record),
+            id,
+        })
+    }
+
+    async fn delete(
+        &self,
+        context: &MutationContext,
+        command: DeleteClientKey,
+    ) -> Result<ClientKeyMutation, AdminError> {
+        let id = command.id.clone();
+        let config_revision = self
+            .store
+            .delete_client_key(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))?;
+        publish_committed(self.snapshot.as_ref(), config_revision).await?;
+        Ok(ClientKeyMutation {
+            config_revision,
+            record: None,
+            id,
+        })
+    }
+}
+
+fn validate_cursor(query: &ClientKeyListQuery) -> Result<(), AdminError> {
+    let Some(cursor) = &query.cursor else {
+        return Ok(());
+    };
+    if cursor.sort != query.sort {
+        return Err(AdminError::invalid(
+            "Client API Key 游标排序与查询条件不一致",
+        ));
+    }
+    let matches = matches!(
+        (cursor.sort.field, &cursor.value),
+        (ClientKeySortField::Name, ClientKeyCursorValue::Name(value)) if !value.trim().is_empty()
+    ) || matches!(
+        (cursor.sort.field, &cursor.value),
+        (
+            ClientKeySortField::Enabled,
+            ClientKeyCursorValue::Enabled(_)
+        ) | (
+            ClientKeySortField::CreatedAt,
+            ClientKeyCursorValue::CreatedAt(_)
+        ) | (
+            ClientKeySortField::LastUsedAt,
+            ClientKeyCursorValue::LastUsedAt(_)
+        )
+    );
+    if matches {
+        Ok(())
+    } else {
+        Err(AdminError::invalid("Client API Key 游标不合法"))
+    }
+}

backend/crates/gateway-admin/src/use_case/mod.rs

@@ -0,0 +1,330 @@
+//! 管理控制面的用例实现。
+
+pub mod account_groups;
+pub mod accounts;
+pub mod auth;
+pub mod backup;
+pub mod client_distribution;
+pub mod client_keys;
+pub mod observability;
+pub mod openai;
+pub mod settings;
+pub mod system;
+pub mod xai;
+
+use crate::{
+    model::{
+        AdminError, AdminErrorKind, MutationContext,
+        accounts::DeleteAccounts,
+        provider_credentials::{
+            AuthorizationMutationTarget, CredentialDeletion, CredentialDeletionResult,
+            CredentialDetails, CredentialMutationResult, CredentialRotationCommit,
+            PendingAuthorizationMutation, PreparedAuthorizationCommit,
+            PreparedAuthorizationCredential, PreparedCredentialImport, PreparedCredentialRotation,
+            StartAuthorization,
+        },
+    },
+    ports::{
+        provider::ProviderAdmin,
+        store::{AccountStore, AdminStoreError, AdminStoreErrorKind},
+    },
+};
+use gateway_core::{
+    account::ProviderAccountId,
+    routing::{ConfigRevision, ProviderKind},
+    runtime::SnapshotControl,
+};
+
+fn map_store_error(error: AdminStoreError, resource: &'static str) -> AdminError {
+    let kind = match error.kind() {
+        AdminStoreErrorKind::Invalid => AdminErrorKind::Invalid,
+        AdminStoreErrorKind::NotFound => AdminErrorKind::NotFound,
+        AdminStoreErrorKind::StaleRevision | AdminStoreErrorKind::Conflict => {
+            AdminErrorKind::Conflict
+        }
+        AdminStoreErrorKind::Unavailable => AdminErrorKind::Unavailable,
+    };
+    tracing::warn!(resource, error_kind = ?error.kind(), "admin store operation failed");
+    let message = match kind {
+        AdminErrorKind::Invalid => "请求参数不合法",
+        AdminErrorKind::NotFound => "请求的资源不存在",
+        AdminErrorKind::Conflict => "当前资源状态冲突，请刷新后重试",
+        AdminErrorKind::Unavailable => "依赖服务暂不可用",
+        _ => "服务内部错误",
+    };
+    AdminError::new(kind, message)
+}
+
+fn map_provider_error(
+    error: crate::ports::provider::ProviderAdminError,
+    resource: &'static str,
+) -> AdminError {
+    use crate::ports::provider::ProviderAdminErrorKind;
+
+    let kind = match error.kind() {
+        ProviderAdminErrorKind::Invalid => AdminErrorKind::Invalid,
+        ProviderAdminErrorKind::Unsupported => AdminErrorKind::Invalid,
+        ProviderAdminErrorKind::NotFound => AdminErrorKind::NotFound,
+        ProviderAdminErrorKind::Conflict => AdminErrorKind::Conflict,
+        ProviderAdminErrorKind::Ambiguous => AdminErrorKind::UpstreamResultUnknown,
+        ProviderAdminErrorKind::Unavailable => AdminErrorKind::Unavailable,
+        ProviderAdminErrorKind::CredentialRefreshRequired => AdminErrorKind::Unavailable,
+        ProviderAdminErrorKind::BadGateway => AdminErrorKind::BadGateway,
+        ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
+    };
+    tracing::warn!(resource, error_kind = ?error.kind(), "admin provider operation failed");
+    let message = match kind {
+        AdminErrorKind::Invalid => "Provider 请求不合法",
+        AdminErrorKind::NotFound => "Provider 资源不存在",
+        AdminErrorKind::Conflict => "Provider 资源状态冲突，请刷新后重试",
+        AdminErrorKind::BadGateway => "上游服务请求失败",
+        AdminErrorKind::UpstreamResultUnknown => "上游执行结果未知，请刷新状态后再决定是否重试",
+        AdminErrorKind::Unavailable => "Provider 服务暂不可用",
+        AdminErrorKind::Internal => "服务内部错误",
+        _ => "Provider 操作失败",
+    };
+    AdminError::new(kind, message)
+}
+
+async fn publish_committed(
+    snapshot: &dyn SnapshotControl,
+    revision: crate::model::Revision,
+) -> Result<(), AdminError> {
+    let revision = ConfigRevision::new(revision.get())
+        .map_err(|_| AdminError::internal("已提交的配置版本不合法"))?;
+    snapshot.publish_committed(revision).await;
+    Ok(())
+}
+
+async fn required_credential(
+    accounts: &dyn AccountStore,
+    provider_kind: &ProviderKind,
+    account_id: &ProviderAccountId,
+    resource: &'static str,
+) -> Result<CredentialDetails, AdminError> {
+    accounts
+        .credential_details(provider_kind, account_id)
+        .await
+        .map_err(|error| map_store_error(error, resource))?
+        .ok_or_else(|| AdminError::not_found("Provider 凭据不存在"))
+}
+
+async fn pending_authorization(
+    accounts: &dyn AccountStore,
+    provider_kind: &ProviderKind,
+    command: &StartAuthorization,
+    resource: &'static str,
+) -> Result<PendingAuthorizationMutation, AdminError> {
+    let target = match &command.reauthorization {
+        Some(account_id) => {
+            required_credential(accounts, provider_kind, account_id, resource).await?;
+            AuthorizationMutationTarget::Reauthorize {
+                account_id: account_id.clone(),
+            }
+        }
+        None => AuthorizationMutationTarget::Create {
+            name: command.name.clone(),
+        },
+    };
+    Ok(PendingAuthorizationMutation::new(
+        provider_kind.clone(),
+        target,
+        crate::model::provider_credentials::AuthorizationOwnerBinding::from_context(
+            &command.context,
+        ),
+    ))
+}
+
+fn validate_prepared_import(
+    provider_kind: &ProviderKind,
+    prepared: &PreparedCredentialImport,
+    _resource: &'static str,
+) -> Result<(), AdminError> {
+    if prepared.provider_kind != *provider_kind
+        || prepared
+            .credentials
+            .iter()
+            .any(|credential| credential.provider_kind != *provider_kind)
+    {
+        return Err(AdminError::conflict("Provider 准备结果与请求范围不一致"));
+    }
+    Ok(())
+}
+
+fn validate_prepared_rotation(
+    account: &crate::model::accounts::AccountRecord,
+    prepared: &PreparedCredentialRotation,
+    _resource: &'static str,
+) -> Result<(), AdminError> {
+    let facts = prepared.facts();
+    if facts.account_id.as_str() != account.id.as_str()
+        || facts.provider_kind != account.provider_kind
+    {
+        return Err(AdminError::conflict("Provider 准备结果与当前凭据不一致"));
+    }
+    Ok(())
+}
+
+async fn validate_authorization_commit(
+    provider_kind: &ProviderKind,
+    context: &MutationContext,
+    prepared: PreparedAuthorizationCommit,
+    resource: &'static str,
+) -> Result<PreparedAuthorizationCommit, AdminError> {
+    if prepared.pending.provider_kind() != provider_kind
+        || !prepared.pending.owner_binding().matches_context(context)
+    {
+        let validation_error = AdminError::conflict("OAuth 授权绑定已失效，请重新发起授权");
+        if let Err(error) = prepared.abort().await {
+            tracing::warn!(
+                resource,
+                settlement_error = %error,
+                "OAuth authorization claim release failed after preparation validation"
+            );
+            return Err(error);
+        }
+        return Err(validation_error);
+    }
+    let matches_target = match (prepared.pending.target(), &prepared.credential) {
+        (
+            AuthorizationMutationTarget::Create { .. },
+            PreparedAuthorizationCredential::Create(credential),
+        ) => credential.provider_kind == *provider_kind,
+        (
+            AuthorizationMutationTarget::Reauthorize { account_id },
+            PreparedAuthorizationCredential::Reauthorize(credential),
+        ) => {
+            let facts = credential.facts();
+            facts.provider_kind == *provider_kind && facts.account_id == *account_id
+        }
+        _ => false,
+    };
+    if !matches_target {
+        let validation_error = AdminError::conflict("OAuth 凭据与待提交目标不一致");
+        if let Err(error) = prepared.abort().await {
+            tracing::warn!(
+                resource,
+                settlement_error = %error,
+                "OAuth authorization claim release failed after preparation validation"
+            );
+            return Err(error);
+        }
+        return Err(validation_error);
+    }
+    Ok(prepared)
+}
+
+async fn commit_authorization(
+    accounts: &dyn AccountStore,
+    prepared: PreparedAuthorizationCommit,
+    context: &MutationContext,
+    resource: &'static str,
+) -> Result<CredentialMutationResult, AdminError> {
+    let crate::model::provider_credentials::AuthorizationCommitSettlement {
+        command,
+        credential_guard,
+        authorization_guard,
+    } = prepared.into_commit();
+    match accounts.commit_authorization(command, context).await {
+        Ok(result) => {
+            if let Some(guard) = credential_guard {
+                guard.finish();
+            }
+            if let Some(guard) = authorization_guard {
+                guard.commit().await?;
+            }
+            Ok(result)
+        }
+        Err(error) => {
+            drop(credential_guard);
+            if let Some(guard) = authorization_guard
+                && let Err(settlement_error) = guard.abort().await
+            {
+                tracing::warn!(
+                    resource,
+                    store_error = %error,
+                    settlement_error = %settlement_error,
+                    "OAuth authorization claim release failed after Store commit failure"
+                );
+                return Err(settlement_error);
+            }
+            Err(map_store_error(error, resource))
+        }
+    }
+}
+
+async fn commit_credential_rotation(
+    accounts: &dyn AccountStore,
+    prepared: PreparedCredentialRotation,
+    context: &MutationContext,
+    resource: &'static str,
+) -> Result<CredentialMutationResult, AdminError> {
+    let (facts, guard) = prepared.into_parts();
+    match accounts
+        .commit_credential_rotation(CredentialRotationCommit { prepared: facts }, context)
+        .await
+    {
+        Ok(result) => {
+            guard.finish();
+            Ok(result)
+        }
+        Err(error) => {
+            drop(guard);
+            Err(map_store_error(error, resource))
+        }
+    }
+}
+
+async fn commit_credential_refresh(
+    accounts: &dyn AccountStore,
+    prepared: PreparedCredentialRotation,
+    context: &MutationContext,
+    resource: &'static str,
+) -> Result<CredentialMutationResult, AdminError> {
+    let (facts, guard) = prepared.into_parts();
+    match accounts
+        .commit_credential_refresh(CredentialRotationCommit { prepared: facts }, context)
+        .await
+    {
+        Ok(result) => {
+            guard.finish();
+            Ok(result)
+        }
+        Err(error) => {
+            drop(guard);
+            Err(map_store_error(error, resource))
+        }
+    }
+}
+
+async fn delete_credentials(
+    accounts: &dyn AccountStore,
+    provider: &dyn ProviderAdmin,
+    command: CredentialDeletion,
+    resource: &'static str,
+) -> Result<CredentialDeletionResult, AdminError> {
+    for account_id in &command.account_ids {
+        required_credential(accounts, provider.provider_kind(), account_id, resource).await?;
+    }
+    let account_ids = command.account_ids;
+    let revision = accounts
+        .delete_accounts(
+            DeleteAccounts {
+                account_ids: account_ids
+                    .iter()
+                    .map(|account_id| account_id.as_str().to_owned())
+                    .collect(),
+            },
+            &command.context,
+        )
+        .await
+        .map_err(|error| map_store_error(error, resource))?;
+    for account_id in &account_ids {
+        provider.account_unavailable(account_id).await;
+    }
+    provider.account_facts_changed(&account_ids).await;
+    Ok(CredentialDeletionResult {
+        config_revision: revision,
+        account_ids,
+    })
+}

backend/crates/gateway-admin/src/use_case/openai.rs

@@ -0,0 +1,260 @@
+//! OpenAI 管理资源的中立 ProviderAdmin 委托。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use gateway_core::{account::ProviderAccountId, runtime::SnapshotControl};
+
+use crate::{
+    model::{
+        AdminError,
+        provider_credentials::{
+            AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
+            CredentialDeletionResult, CredentialDetails, CredentialImportCommit,
+            CredentialImportResult, CredentialListQuery, CredentialMutationResult, CredentialPage,
+            ImportCredentials, PrepareCredentialImport, PrepareCredentialRotation,
+            ProviderQuotaRequest, RotateCredential, StartAuthorization,
+        },
+    },
+    ports::{provider::ProviderAdmin, store::AccountStore},
+};
+
+use super::{
+    commit_authorization, commit_credential_rotation, delete_credentials, map_provider_error,
+    map_store_error, pending_authorization, publish_committed, required_credential,
+    validate_authorization_commit, validate_prepared_import, validate_prepared_rotation,
+};
+
+/// OpenAI 固定管理路由消费的服务。
+#[async_trait]
+pub trait OpenAiService: Send + Sync {
+    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError>;
+    async fn details(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<CredentialDetails, AdminError>;
+    async fn import_document(
+        &self,
+        command: ImportCredentials,
+    ) -> Result<CredentialImportResult, AdminError>;
+    async fn start_authorization(
+        &self,
+        command: StartAuthorization,
+    ) -> Result<AuthorizationStarted, AdminError>;
+    async fn complete_authorization(
+        &self,
+        command: CompleteAuthorization,
+    ) -> Result<CredentialMutationResult, AdminError>;
+    async fn rotate(
+        &self,
+        command: RotateCredential,
+    ) -> Result<CredentialMutationResult, AdminError>;
+    async fn delete(
+        &self,
+        command: CredentialDeletion,
+    ) -> Result<CredentialDeletionResult, AdminError>;
+}
+
+pub(crate) struct DefaultOpenAiService {
+    provider: Arc<dyn ProviderAdmin>,
+    accounts: Arc<dyn AccountStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultOpenAiService {
+    #[must_use]
+    pub(crate) fn new(
+        provider: Arc<dyn ProviderAdmin>,
+        accounts: Arc<dyn AccountStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            provider,
+            accounts,
+            snapshot,
+        }
+    }
+
+    fn observe_initial_quotas(&self, account_ids: &[ProviderAccountId], request_id: &str) {
+        let provider = Arc::clone(&self.provider);
+        let account_ids = account_ids.to_vec();
+        let request_id = request_id.to_owned();
+        tokio::spawn(async move {
+            for account_id in account_ids {
+                if let Err(error) = provider
+                    .quota(ProviderQuotaRequest {
+                        account_id: account_id.clone(),
+                        refresh: true,
+                        rolling_usage: None,
+                    })
+                    .await
+                {
+                    tracing::warn!(
+                        request_id,
+                        account_id = %account_id.as_str(),
+                        quota_error = ?error.kind(),
+                        "OpenAI initial quota observation failed"
+                    );
+                }
+            }
+        });
+    }
+}
+
+#[async_trait]
+impl OpenAiService for DefaultOpenAiService {
+    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError> {
+        self.accounts
+            .list_credentials(self.provider.provider_kind(), query)
+            .await
+            .map_err(|error| map_store_error(error, "OpenAI credential"))
+    }
+
+    async fn details(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<CredentialDetails, AdminError> {
+        required_credential(
+            self.accounts.as_ref(),
+            self.provider.provider_kind(),
+            account_id,
+            "OpenAI credential",
+        )
+        .await
+    }
+
+    async fn import_document(
+        &self,
+        command: ImportCredentials,
+    ) -> Result<CredentialImportResult, AdminError> {
+        let context = command.context;
+        let prepared = self
+            .provider
+            .prepare_import(PrepareCredentialImport {
+                document: command.document,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "OpenAI credential import"))?;
+        validate_prepared_import(
+            self.provider.provider_kind(),
+            &prepared,
+            "OpenAI credential import",
+        )?;
+        let result = self
+            .accounts
+            .commit_credential_import(CredentialImportCommit { prepared }, &context)
+            .await
+            .map_err(|error| map_store_error(error, "OpenAI credential import"))?;
+        self.provider
+            .account_facts_changed(&result.credential_ids)
+            .await;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        // 导入完成后立即做一次观察；失败不回滚已经提交的 credential。
+        self.observe_initial_quotas(&result.credential_ids, &context.request_id);
+        Ok(result)
+    }
+
+    async fn start_authorization(
+        &self,
+        command: StartAuthorization,
+    ) -> Result<AuthorizationStarted, AdminError> {
+        let pending = pending_authorization(
+            self.accounts.as_ref(),
+            self.provider.provider_kind(),
+            &command,
+            "OpenAI credential",
+        )
+        .await?;
+        self.provider
+            .start_authorization(pending)
+            .await
+            .map_err(|error| map_provider_error(error, "OpenAI authorization"))
+    }
+
+    async fn complete_authorization(
+        &self,
+        command: CompleteAuthorization,
+    ) -> Result<CredentialMutationResult, AdminError> {
+        let context = command.context.clone();
+        let prepared = self
+            .provider
+            .complete_authorization(command)
+            .await
+            .map_err(|error| map_provider_error(error, "OpenAI authorization"))?;
+        let prepared = validate_authorization_commit(
+            self.provider.provider_kind(),
+            &context,
+            prepared,
+            "OpenAI authorization",
+        )
+        .await?;
+        let result = commit_authorization(
+            self.accounts.as_ref(),
+            prepared,
+            &context,
+            "OpenAI authorization",
+        )
+        .await?;
+        self.provider
+            .account_facts_changed(std::slice::from_ref(&result.account_id))
+            .await;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        self.observe_initial_quotas(
+            std::slice::from_ref(&result.account_id),
+            &context.request_id,
+        );
+        Ok(result)
+    }
+
+    async fn rotate(
+        &self,
+        command: RotateCredential,
+    ) -> Result<CredentialMutationResult, AdminError> {
+        let context = command.mutation.context;
+        let account_id = command.mutation.account_id;
+        let details = required_credential(
+            self.accounts.as_ref(),
+            self.provider.provider_kind(),
+            &account_id,
+            "OpenAI credential rotation",
+        )
+        .await?;
+        let account = details.credential;
+        let prepared = self
+            .provider
+            .prepare_rotation(PrepareCredentialRotation {
+                account: account.clone(),
+                provider_material: command.provider_material,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "OpenAI credential rotation"))?;
+        validate_prepared_rotation(&account, &prepared, "OpenAI credential rotation")?;
+        let result = commit_credential_rotation(
+            self.accounts.as_ref(),
+            prepared,
+            &context,
+            "OpenAI credential rotation",
+        )
+        .await?;
+        self.provider
+            .account_facts_changed(std::slice::from_ref(&result.account_id))
+            .await;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    async fn delete(
+        &self,
+        command: CredentialDeletion,
+    ) -> Result<CredentialDeletionResult, AdminError> {
+        let result = delete_credentials(
+            self.accounts.as_ref(),
+            self.provider.as_ref(),
+            command,
+            "OpenAI credential",
+        )
+        .await?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+}

backend/crates/gateway-admin/src/use_case/settings.rs

@@ -0,0 +1,135 @@
+//! Runtime settings 与管理员 API Key 用例。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use gateway_core::policy::CodexClientVersion;
+use gateway_core::runtime::SnapshotControl;
+use rand_core::{OsRng, RngCore as _};
+
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        settings::{
+            AdminApiKey, AdminApiKeyMutation, RegeneratedAdminApiKey, ReplaceRuntimeSettings,
+            RuntimeSettings,
+        },
+    },
+    ports::store::SettingsStore,
+};
+
+use super::{map_store_error, publish_committed};
+
+/// API 消费的 Runtime settings 管理服务。
+#[async_trait]
+pub trait SettingsService: Send + Sync {
+    async fn load(&self) -> Result<RuntimeSettings, AdminError>;
+    async fn replace(
+        &self,
+        context: &MutationContext,
+        command: ReplaceRuntimeSettings,
+    ) -> Result<RuntimeSettings, AdminError>;
+    async fn admin_api_key_exists(&self) -> Result<bool, AdminError>;
+    async fn regenerate_admin_api_key(
+        &self,
+        context: &MutationContext,
+    ) -> Result<RegeneratedAdminApiKey, AdminError>;
+    async fn delete_admin_api_key(
+        &self,
+        context: &MutationContext,
+    ) -> Result<AdminApiKeyMutation, AdminError>;
+}
+
+pub(crate) struct DefaultSettingsService {
+    store: Arc<dyn SettingsStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultSettingsService {
+    #[must_use]
+    pub(crate) fn new(store: Arc<dyn SettingsStore>, snapshot: Arc<dyn SnapshotControl>) -> Self {
+        Self { store, snapshot }
+    }
+}
+
+#[async_trait]
+impl SettingsService for DefaultSettingsService {
+    async fn load(&self) -> Result<RuntimeSettings, AdminError> {
+        self.store
+            .load_runtime_settings()
+            .await
+            .map_err(|error| map_store_error(error, "runtime settings"))
+    }
+
+    async fn replace(
+        &self,
+        context: &MutationContext,
+        command: ReplaceRuntimeSettings,
+    ) -> Result<RuntimeSettings, AdminError> {
+        validate_settings(&command)?;
+        let settings = self
+            .store
+            .replace_runtime_settings(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "runtime settings"))?;
+        publish_committed(self.snapshot.as_ref(), settings.config_revision).await?;
+        Ok(settings)
+    }
+
+    async fn admin_api_key_exists(&self) -> Result<bool, AdminError> {
+        self.store
+            .admin_api_key_exists()
+            .await
+            .map_err(|error| map_store_error(error, "administrator API key"))
+    }
+
+    async fn regenerate_admin_api_key(
+        &self,
+        context: &MutationContext,
+    ) -> Result<RegeneratedAdminApiKey, AdminError> {
+        let mut bytes = [0_u8; 32];
+        OsRng.fill_bytes(&mut bytes);
+        let key = AdminApiKey::new(format!("admin-{}", hex::encode(bytes)));
+        let mutation = self
+            .store
+            .replace_admin_api_key(key.clone(), context)
+            .await
+            .map_err(|error| map_store_error(error, "administrator API key"))?;
+        publish_committed(self.snapshot.as_ref(), mutation.config_revision).await?;
+        Ok(RegeneratedAdminApiKey { mutation, key })
+    }
+
+    async fn delete_admin_api_key(
+        &self,
+        context: &MutationContext,
+    ) -> Result<AdminApiKeyMutation, AdminError> {
+        let mutation = self
+            .store
+            .delete_admin_api_key(context)
+            .await
+            .map_err(|error| map_store_error(error, "administrator API key"))?;
+        publish_committed(self.snapshot.as_ref(), mutation.config_revision).await?;
+        Ok(mutation)
+    }
+}
+
+fn validate_settings(command: &ReplaceRuntimeSettings) -> Result<(), AdminError> {
+    let valid = command.refresh_margin_seconds > 0
+        && command.refresh_concurrency > 0
+        && command.max_concurrent_per_account > 0
+        && command.usage_retention_days >= 31
+        && command.ops_event_retention_days > 0
+        && command.audit_retention_days > 0
+        && valid_client_version(command.min_codex_desktop_version.as_deref())
+        && valid_client_version(command.min_codex_cli_version.as_deref())
+        && i64::try_from(command.request_interval_ms).is_ok();
+    if valid {
+        Ok(())
+    } else {
+        Err(AdminError::invalid("运行时设置不满足约束"))
+    }
+}
+
+fn valid_client_version(value: Option<&str>) -> bool {
+    value.is_none_or(|value| CodexClientVersion::parse(value).is_ok())
+}

backend/crates/gateway-admin/src/use_case/system.rs

@@ -0,0 +1,105 @@
+//! 系统管理用例。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use crate::{
+    model::{
+        AdminError, AdminErrorKind,
+        system::{SystemOperationAccepted, SystemUpdateDetail, SystemUpdateStatus, SystemVersion},
+    },
+    ports::system::{
+        SystemOperationError, SystemOperationErrorKind, SystemOperations, SystemUpdateEventStream,
+    },
+};
+
+/// API 消费的系统管理服务。
+#[async_trait]
+pub trait SystemService: Send + Sync {
+    async fn version(&self) -> Result<SystemVersion, AdminError>;
+    async fn update_detail(&self, refresh: bool) -> Result<SystemUpdateDetail, AdminError>;
+    fn update_events(&self) -> SystemUpdateEventStream;
+    async fn perform_update(
+        &self,
+        target_version: Option<String>,
+    ) -> Result<SystemOperationAccepted, AdminError>;
+    async fn update_status(&self) -> Result<SystemUpdateStatus, AdminError>;
+    async fn rollback(&self) -> Result<SystemOperationAccepted, AdminError>;
+    async fn restart(&self) -> Result<SystemOperationAccepted, AdminError>;
+}
+
+/// 保持 Host 能力窄边界的默认系统用例。
+pub(crate) struct DefaultSystemService {
+    operations: Arc<dyn SystemOperations>,
+}
+
+impl DefaultSystemService {
+    #[must_use]
+    pub(crate) const fn new(operations: Arc<dyn SystemOperations>) -> Self {
+        Self { operations }
+    }
+}
+
+#[async_trait]
+impl SystemService for DefaultSystemService {
+    async fn version(&self) -> Result<SystemVersion, AdminError> {
+        self.operations.version().await.map_err(map_system_error)
+    }
+
+    async fn update_detail(&self, refresh: bool) -> Result<SystemUpdateDetail, AdminError> {
+        self.operations
+            .update_detail(refresh)
+            .await
+            .map_err(map_system_error)
+    }
+
+    fn update_events(&self) -> SystemUpdateEventStream {
+        self.operations.update_events()
+    }
+
+    async fn perform_update(
+        &self,
+        target_version: Option<String>,
+    ) -> Result<SystemOperationAccepted, AdminError> {
+        let target_version = target_version
+            .map(|version| version.trim().to_owned())
+            .filter(|version| !version.is_empty());
+        self.operations
+            .perform_update(target_version)
+            .await
+            .map_err(map_system_error)
+    }
+
+    async fn update_status(&self) -> Result<SystemUpdateStatus, AdminError> {
+        self.operations
+            .update_status()
+            .await
+            .map_err(map_system_error)
+    }
+
+    async fn rollback(&self) -> Result<SystemOperationAccepted, AdminError> {
+        self.operations.rollback().await.map_err(map_system_error)
+    }
+
+    async fn restart(&self) -> Result<SystemOperationAccepted, AdminError> {
+        self.operations.restart().await.map_err(map_system_error)
+    }
+}
+
+fn map_system_error(error: SystemOperationError) -> AdminError {
+    let kind = match error.kind() {
+        SystemOperationErrorKind::Invalid => AdminErrorKind::Invalid,
+        SystemOperationErrorKind::Conflict => AdminErrorKind::Conflict,
+        SystemOperationErrorKind::Upstream => AdminErrorKind::BadGateway,
+        SystemOperationErrorKind::Internal => AdminErrorKind::Internal,
+    };
+    let message = match kind {
+        AdminErrorKind::Invalid => "系统操作请求不合法",
+        AdminErrorKind::Conflict => "系统当前状态不允许执行该操作",
+        AdminErrorKind::BadGateway => "系统更新服务请求失败",
+        AdminErrorKind::Internal => "系统操作失败",
+        _ => "系统操作失败",
+    };
+    AdminError::new(kind, message)
+}

backend/crates/gateway-admin/src/use_case/xai.rs

@@ -0,0 +1,175 @@
+//! xAI 管理资源的中立 ProviderAdmin 委托。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use gateway_core::runtime::SnapshotControl;
+
+use crate::{
+    model::{
+        AdminError,
+        provider_credentials::{
+            AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
+            CredentialDeletionResult, CredentialImportCommit, CredentialImportResult,
+            CredentialListQuery, CredentialMutationResult, CredentialPage, ImportCredentials,
+            PrepareCredentialImport, ProviderQuotaRequest, StartAuthorization,
+        },
+    },
+    ports::{provider::ProviderAdmin, store::AccountStore},
+};
+
+use super::{
+    commit_authorization, delete_credentials, map_provider_error, map_store_error,
+    pending_authorization, publish_committed, validate_authorization_commit,
+    validate_prepared_import,
+};
+
+/// xAI 固定管理路由消费的服务。
+#[async_trait]
+pub trait XaiService: Send + Sync {
+    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError>;
+    async fn import_document(
+        &self,
+        command: ImportCredentials,
+    ) -> Result<CredentialImportResult, AdminError>;
+    async fn start_authorization(
+        &self,
+        command: StartAuthorization,
+    ) -> Result<AuthorizationStarted, AdminError>;
+    async fn complete_authorization(
+        &self,
+        command: CompleteAuthorization,
+    ) -> Result<CredentialMutationResult, AdminError>;
+    async fn delete(
+        &self,
+        command: CredentialDeletion,
+    ) -> Result<CredentialDeletionResult, AdminError>;
+}
+
+pub(crate) struct DefaultXaiService {
+    provider: Arc<dyn ProviderAdmin>,
+    accounts: Arc<dyn AccountStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultXaiService {
+    #[must_use]
+    pub(crate) fn new(
+        provider: Arc<dyn ProviderAdmin>,
+        accounts: Arc<dyn AccountStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            provider,
+            accounts,
+            snapshot,
+        }
+    }
+}
+
+#[async_trait]
+impl XaiService for DefaultXaiService {
+    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError> {
+        self.accounts
+            .list_credentials(self.provider.provider_kind(), query)
+            .await
+            .map_err(|error| map_store_error(error, "xAI credential"))
+    }
+
+    async fn import_document(
+        &self,
+        command: ImportCredentials,
+    ) -> Result<CredentialImportResult, AdminError> {
+        let context = command.context;
+        let prepared = self
+            .provider
+            .prepare_import(PrepareCredentialImport {
+                document: command.document,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "xAI credential import"))?;
+        validate_prepared_import(
+            self.provider.provider_kind(),
+            &prepared,
+            "xAI credential import",
+        )?;
+        let result = self
+            .accounts
+            .commit_credential_import(CredentialImportCommit { prepared }, &context)
+            .await
+            .map_err(|error| map_store_error(error, "xAI credential import"))?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        // 导入已经提交，额度属于可重建观察事实；单个账号查询失败由周期任务重试。
+        for account_id in &result.credential_ids {
+            let _ = self
+                .provider
+                .quota(ProviderQuotaRequest {
+                    account_id: account_id.clone(),
+                    refresh: true,
+                    rolling_usage: None,
+                })
+                .await;
+        }
+        Ok(result)
+    }
+
+    async fn start_authorization(
+        &self,
+        command: StartAuthorization,
+    ) -> Result<AuthorizationStarted, AdminError> {
+        let pending = pending_authorization(
+            self.accounts.as_ref(),
+            self.provider.provider_kind(),
+            &command,
+            "xAI credential",
+        )
+        .await?;
+        self.provider
+            .start_authorization(pending)
+            .await
+            .map_err(|error| map_provider_error(error, "xAI authorization"))
+    }
+
+    async fn complete_authorization(
+        &self,
+        command: CompleteAuthorization,
+    ) -> Result<CredentialMutationResult, AdminError> {
+        let context = command.context.clone();
+        let prepared = self
+            .provider
+            .complete_authorization(command)
+            .await
+            .map_err(|error| map_provider_error(error, "xAI authorization"))?;
+        let prepared = validate_authorization_commit(
+            self.provider.provider_kind(),
+            &context,
+            prepared,
+            "xAI authorization",
+        )
+        .await?;
+        let result = commit_authorization(
+            self.accounts.as_ref(),
+            prepared,
+            &context,
+            "xAI authorization",
+        )
+        .await?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    async fn delete(
+        &self,
+        command: CredentialDeletion,
+    ) -> Result<CredentialDeletionResult, AdminError> {
+        let result = delete_credentials(
+            self.accounts.as_ref(),
+            self.provider.as_ref(),
+            command,
+            "xAI credential",
+        )
+        .await?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+}

backend/crates/gateway-admin/tests/backup/mod.rs

@@ -0,0 +1,5 @@
+//! 备份模块测试：镜像 src/backup/ 的 policy 与 task。
+
+mod policy;
+pub mod support;
+mod task;

backend/crates/gateway-admin/tests/backup/policy.rs

@@ -0,0 +1,171 @@
+//! 备份调度与保留策略（backup/policy.rs）的纯逻辑测试。
+
+use chrono::{Duration, TimeZone as _, Utc};
+
+use gateway_admin::{
+    backup::policy::{BackupSchedule, RetentionReason, decide_retention},
+    model::backup::{BackupRecord, BackupStatus, BackupTriggerKind},
+};
+
+fn record(
+    id: &str,
+    trigger: BackupTriggerKind,
+    status: BackupStatus,
+    created_at: chrono::DateTime<Utc>,
+    completed_at: Option<chrono::DateTime<Utc>>,
+) -> BackupRecord {
+    BackupRecord {
+        id: id.to_owned(),
+        trigger_kind: trigger,
+        status,
+        scheduled_at: if trigger == BackupTriggerKind::Scheduled {
+            Some(created_at)
+        } else {
+            None
+        },
+        object_key: format!("k/{id}"),
+        size_bytes: Some(1),
+        sha256: Some("a".repeat(64)),
+        attempt_count: 0,
+        error_code: None,
+        error_message: None,
+        started_at: Some(created_at),
+        completed_at,
+        expires_at: None,
+        created_at,
+        updated_at: created_at,
+    }
+}
+
+#[test]
+fn parse_rejects_bad_cron_and_timezone() {
+    assert!(BackupSchedule::parse("61 * * * *", "Asia/Shanghai").is_err());
+    assert!(BackupSchedule::parse("0 2 * * *", "Not/AZone").is_err());
+    assert!(BackupSchedule::parse("0 2 * * *", "Asia/Shanghai").is_ok());
+}
+
+#[test]
+fn next_after_is_strictly_later() {
+    let schedule = BackupSchedule::parse("0 2 * * *", "Asia/Shanghai").unwrap();
+    let at = Utc.with_ymd_and_hms(2026, 8, 1, 18, 0, 0).unwrap();
+    let next = schedule.next_after(at).unwrap();
+    assert_eq!(next, Utc.with_ymd_and_hms(2026, 8, 2, 18, 0, 0).unwrap());
+}
+
+#[test]
+fn last_firing_is_at_or_before() {
+    let schedule = BackupSchedule::parse("0 2 * * *", "Asia/Shanghai").unwrap();
+    // 北京时间 02:00 = 前一日 18:00 UTC。
+    let before = Utc.with_ymd_and_hms(2026, 8, 1, 17, 59, 0).unwrap();
+    assert_eq!(
+        schedule.last_firing_at_or_before(before).unwrap(),
+        Utc.with_ymd_and_hms(2026, 7, 31, 18, 0, 0).unwrap()
+    );
+    let exact = Utc.with_ymd_and_hms(2026, 8, 1, 18, 0, 0).unwrap();
+    assert_eq!(schedule.last_firing_at_or_before(exact).unwrap(), exact);
+    let after = Utc.with_ymd_and_hms(2026, 8, 1, 19, 0, 0).unwrap();
+    assert_eq!(schedule.last_firing_at_or_before(after).unwrap(), exact);
+}
+
+#[test]
+fn dst_spring_forward_skips_missing_hour() {
+    let schedule = BackupSchedule::parse("30 2 * * *", "America/New_York").unwrap();
+    let at = Utc.with_ymd_and_hms(2026, 3, 8, 6, 29, 0).unwrap(); // 01:29 EST
+    let next = schedule.next_after(at).unwrap();
+    assert_eq!(next, Utc.with_ymd_and_hms(2026, 3, 9, 6, 30, 0).unwrap());
+    let at_after_spring = Utc.with_ymd_and_hms(2026, 3, 8, 10, 0, 0).unwrap(); // 06:00 EDT
+    let last = schedule.last_firing_at_or_before(at_after_spring).unwrap();
+    assert_eq!(last, Utc.with_ymd_and_hms(2026, 3, 7, 7, 30, 0).unwrap());
+}
+
+#[test]
+fn retention_count_keeps_newest_n() {
+    let now = Utc::now();
+    let base = now - Duration::days(10);
+    let records = vec![
+        record(
+            "newest",
+            BackupTriggerKind::Scheduled,
+            BackupStatus::Completed,
+            base + Duration::days(2),
+            Some(base + Duration::days(2)),
+        ),
+        record(
+            "middle",
+            BackupTriggerKind::Scheduled,
+            BackupStatus::Completed,
+            base + Duration::days(1),
+            Some(base + Duration::days(1)),
+        ),
+        record(
+            "oldest",
+            BackupTriggerKind::Scheduled,
+            BackupStatus::Completed,
+            base,
+            Some(base),
+        ),
+    ];
+    let decisions = decide_retention(0, 2, now, &records);
+    let ids: Vec<_> = decisions.iter().map(|d| d.record_id.as_str()).collect();
+    assert_eq!(ids, vec!["oldest"]);
+    assert_eq!(decisions[0].reason, RetentionReason::Count);
+}
+
+#[test]
+fn retention_days_deletes_old_scheduled_but_keeps_newest() {
+    let now = Utc::now();
+    let records = vec![
+        record(
+            "recent",
+            BackupTriggerKind::Scheduled,
+            BackupStatus::Completed,
+            now - Duration::days(1),
+            Some(now - Duration::days(1)),
+        ),
+        record(
+            "ancient",
+            BackupTriggerKind::Scheduled,
+            BackupStatus::Completed,
+            now - Duration::days(40),
+            Some(now - Duration::days(40)),
+        ),
+    ];
+    let decisions = decide_retention(30, 0, now, &records);
+    let ids: Vec<_> = decisions.iter().map(|d| d.record_id.as_str()).collect();
+    assert_eq!(ids, vec!["ancient"]);
+}
+
+#[test]
+fn newest_scheduled_never_auto_deleted_even_when_ancient() {
+    let now = Utc::now();
+    let records = vec![record(
+        "sole",
+        BackupTriggerKind::Scheduled,
+        BackupStatus::Completed,
+        now - Duration::days(400),
+        Some(now - Duration::days(400)),
+    )];
+    assert!(decide_retention(30, 1, now, &records).is_empty());
+}
+
+#[test]
+fn disabled_thresholds_delete_nothing() {
+    let now = Utc::now();
+    let records = vec![
+        record(
+            "newest",
+            BackupTriggerKind::Scheduled,
+            BackupStatus::Completed,
+            now - Duration::days(2),
+            Some(now - Duration::days(2)),
+        ),
+        record(
+            "old",
+            BackupTriggerKind::Scheduled,
+            BackupStatus::Completed,
+            now - Duration::days(90),
+            Some(now - Duration::days(90)),
+        ),
+    ];
+    assert!(decide_retention(0, 0, now, &records).is_empty());
+}

backend/crates/gateway-admin/tests/backup/support.rs

@@ -0,0 +1,664 @@
+//! 备份测试共享 fixture：内存 fake 端口与辅助函数。
+//!
+//! 用内存 fake 端口驱动编排层，不依赖 MinIO/真实 S3。
+//! s3.rs / pg_dump.rs 是 SDK 薄适配器，协议正确性交给 aws-sdk / pg_dump 保证。
+//! 供 backup::task 与 use_case::backup 的测试复用。
+
+use std::sync::Mutex;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use gateway_admin::{
+    model::{
+        MutationActor, MutationContext, Revision,
+        auth::AdminAuditEvent,
+        backup::{
+            BackupError, BackupObjectMetadata, BackupRecord, BackupRecordListQuery,
+            BackupRecordPage, BackupRecordSeed, BackupSettings, BackupStatus, BackupStorageConfig,
+            BackupTriggerKind, ConnectionTestResult, UpdateBackupScheduleCommand,
+            UpdateBackupStorageCommand,
+        },
+    },
+    ports::{
+        backup::{
+            BackupObjectStorePort, BackupRepository, DatabaseDumpPort, DumpArtifact, DumpRequest,
+            StagedArtifact, StatusTransitionUpdate, UploadObjectRequest,
+        },
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult, AuthStore},
+    },
+};
+use secrecy::SecretString;
+use sha2::{Digest as _, Sha256};
+use tempfile::TempDir;
+
+/// 假归档内容；dump 与上传校验共用同一字节与校验值。
+pub(crate) const DUMP_CONTENT: &[u8] = b"custom-format-archive-bytes-0123456789";
+
+/// 计算一段内容的 SHA-256 十六进制。
+pub(crate) fn sha256_hex(content: &[u8]) -> String {
+    hex::encode(Sha256::digest(content))
+}
+
+/// 返回 32 位十六进制的合法备份记录 id。
+pub(crate) fn backup_id(suffix: &str) -> String {
+    format!("backup_{}", sha256_hex(suffix.as_bytes()))
+}
+
+/// 已配置且已通过连接测试的设置快照。
+pub(crate) fn configured_settings() -> BackupSettings {
+    let now = Utc::now();
+    BackupSettings {
+        storage_revision: 1,
+        endpoint: Some("https://s3.example.com".to_owned()),
+        region: Some("auto".to_owned()),
+        bucket: Some("backup-bucket".to_owned()),
+        access_key_id: Some("ak".to_owned()),
+        secret_access_key: Some(SecretString::from("sk-value")),
+        prefix: Some("codex".to_owned()),
+        force_path_style: false,
+        schedule_enabled: false,
+        cron_expression: None,
+        schedule_timezone: None,
+        retention_days: 0,
+        retention_count: 0,
+        next_run_at: None,
+        last_verified_at: Some(now),
+        updated_at: now,
+    }
+}
+
+/// 从 seed 构造 queued 记录。
+pub(crate) fn queued_record(seed: &BackupRecordSeed) -> BackupRecord {
+    let now = Utc::now();
+    BackupRecord {
+        id: seed.id.clone(),
+        trigger_kind: seed.trigger_kind,
+        status: BackupStatus::Queued,
+        scheduled_at: seed.scheduled_at,
+        object_key: seed.object_key.clone(),
+        size_bytes: None,
+        sha256: None,
+        attempt_count: 0,
+        error_code: None,
+        error_message: None,
+        started_at: None,
+        completed_at: None,
+        expires_at: seed.expires_at,
+        created_at: now,
+        updated_at: now,
+    }
+}
+
+/// 内存版备份仓储。
+pub(crate) struct FakeBackupRepository {
+    settings: Mutex<BackupSettings>,
+    records: Mutex<Vec<BackupRecord>>,
+}
+
+impl FakeBackupRepository {
+    pub(crate) fn new(settings: BackupSettings) -> Self {
+        Self {
+            settings: Mutex::new(settings),
+            records: Mutex::new(Vec::new()),
+        }
+    }
+
+    /// 测试辅助：读取当前全部记录。
+    pub(crate) fn all_records(&self) -> Vec<BackupRecord> {
+        self.records.lock().expect("records").clone()
+    }
+
+    /// 测试辅助：强制把一条记录标记为指定时间完成的 completed。
+    pub(crate) fn set_completed(&self, id: &str, completed_at: DateTime<Utc>) {
+        let mut records = self.records.lock().expect("records");
+        if let Some(record) = records.iter_mut().find(|record| record.id == id) {
+            record.status = BackupStatus::Completed;
+            record.completed_at = Some(completed_at);
+            record.updated_at = Utc::now();
+        }
+    }
+
+    /// 测试辅助：强制把一条记录迁移到指定状态。
+    pub(crate) fn force_status(&self, id: &str, status: BackupStatus) {
+        let mut records = self.records.lock().expect("records");
+        if let Some(record) = records.iter_mut().find(|record| record.id == id) {
+            record.status = status;
+            if matches!(status, BackupStatus::Completed | BackupStatus::Failed) {
+                record.completed_at = Some(Utc::now());
+            }
+            record.updated_at = Utc::now();
+        }
+    }
+}
+
+#[async_trait]
+impl BackupRepository for FakeBackupRepository {
+    async fn load_settings(&self) -> AdminStoreResult<BackupSettings> {
+        Ok(self.settings.lock().expect("settings").clone())
+    }
+
+    async fn update_storage_settings(
+        &self,
+        command: UpdateBackupStorageCommand,
+        _context: &MutationContext,
+    ) -> AdminStoreResult<(BackupSettings, Revision)> {
+        let mut settings = self.settings.lock().expect("settings");
+        settings.storage_revision += 1;
+        settings.endpoint = Some(command.endpoint);
+        settings.region = Some(command.region);
+        settings.bucket = Some(command.bucket);
+        settings.access_key_id = Some(command.access_key_id);
+        if let Some(secret) = command.secret_access_key {
+            settings.secret_access_key = Some(secret);
+        }
+        settings.prefix = Some(command.prefix);
+        settings.force_path_style = command.force_path_style;
+        settings.last_verified_at = None;
+        settings.updated_at = Utc::now();
+        let revision = Revision::new(settings.storage_revision).map_err(|_| {
+            AdminStoreError::new(AdminStoreErrorKind::Invalid, "backup", "zero revision")
+        })?;
+        Ok((settings.clone(), revision))
+    }
+
+    async fn update_schedule_settings(
+        &self,
+        command: UpdateBackupScheduleCommand,
+        next_run_at: Option<DateTime<Utc>>,
+        _context: &MutationContext,
+    ) -> AdminStoreResult<BackupSettings> {
+        let mut settings = self.settings.lock().expect("settings");
+        settings.schedule_enabled = command.schedule_enabled;
+        settings.cron_expression = Some(command.cron_expression);
+        settings.schedule_timezone = Some(command.schedule_timezone);
+        settings.retention_days = command.retention_days;
+        settings.retention_count = command.retention_count;
+        settings.next_run_at = next_run_at;
+        settings.updated_at = Utc::now();
+        Ok(settings.clone())
+    }
+
+    async fn record_verification(
+        &self,
+        storage_revision: u64,
+        at: DateTime<Utc>,
+    ) -> AdminStoreResult<bool> {
+        let mut settings = self.settings.lock().expect("settings");
+        if settings.storage_revision != storage_revision {
+            return Ok(false);
+        }
+        settings.last_verified_at = Some(at);
+        Ok(true)
+    }
+
+    async fn insert_backup_record(&self, seed: BackupRecordSeed) -> AdminStoreResult<BackupRecord> {
+        let mut records = self.records.lock().expect("records");
+        if records.iter().any(|record| record.status.is_active()) {
+            return Err(AdminStoreError::new(
+                AdminStoreErrorKind::Conflict,
+                "backup record",
+                "an active backup task already exists",
+            ));
+        }
+        let record = queued_record(&seed);
+        records.push(record.clone());
+        Ok(record)
+    }
+
+    async fn insert_scheduled_record(&self, seed: BackupRecordSeed) -> AdminStoreResult<bool> {
+        let mut records = self.records.lock().expect("records");
+        if records.iter().any(|record| record.status.is_active())
+            || records.iter().any(|record| {
+                record.trigger_kind == BackupTriggerKind::Scheduled
+                    && record.scheduled_at == seed.scheduled_at
+            })
+        {
+            return Ok(false);
+        }
+        records.push(queued_record(&seed));
+        Ok(true)
+    }
+
+    async fn list_backup_records(
+        &self,
+        query: BackupRecordListQuery,
+    ) -> AdminStoreResult<BackupRecordPage> {
+        let records = self.records.lock().expect("records");
+        let mut items = records
+            .iter()
+            .filter(|record| {
+                query.status.is_none_or(|status| record.status == status)
+                    && query
+                        .trigger
+                        .is_none_or(|trigger| record.trigger_kind == trigger)
+            })
+            .cloned()
+            .collect::<Vec<_>>();
+        items.sort_by(|a, b| {
+            b.created_at
+                .cmp(&a.created_at)
+                .then_with(|| b.id.cmp(&a.id))
+        });
+        let total = items.len() as u64;
+        let offset =
+            (u64::from(query.page.saturating_sub(1)) * u64::from(query.page_size.get())) as usize;
+        let limit = usize::from(query.page_size.get());
+        items = items.into_iter().skip(offset).take(limit).collect();
+        Ok(BackupRecordPage {
+            items,
+            total,
+            page: query.page,
+            page_size: query.page_size,
+        })
+    }
+
+    async fn load_backup_record(&self, id: &str) -> AdminStoreResult<Option<BackupRecord>> {
+        Ok(self
+            .records
+            .lock()
+            .expect("records")
+            .iter()
+            .find(|record| record.id == id)
+            .cloned())
+    }
+
+    async fn list_intermediate_records(&self) -> AdminStoreResult<Vec<BackupRecord>> {
+        Ok(self
+            .records
+            .lock()
+            .expect("records")
+            .iter()
+            .filter(|record| {
+                matches!(
+                    record.status,
+                    BackupStatus::Dumping | BackupStatus::Uploading
+                )
+            })
+            .cloned()
+            .collect())
+    }
+
+    async fn list_pending_deletions(&self, _limit: u32) -> AdminStoreResult<Vec<BackupRecord>> {
+        Ok(self
+            .records
+            .lock()
+            .expect("records")
+            .iter()
+            .filter(|record| record.status == BackupStatus::Deleting)
+            .cloned()
+            .collect())
+    }
+
+    async fn list_expired_records(&self, _limit: u32) -> AdminStoreResult<Vec<BackupRecord>> {
+        let now = Utc::now();
+        Ok(self
+            .records
+            .lock()
+            .expect("records")
+            .iter()
+            .filter(|record| {
+                record
+                    .expires_at
+                    .is_some_and(|expires_at| expires_at <= now)
+                    && matches!(
+                        record.status,
+                        BackupStatus::Completed | BackupStatus::Failed
+                    )
+            })
+            .cloned()
+            .collect())
+    }
+
+    async fn claim_next_queued(
+        &self,
+        now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        let mut records = self.records.lock().expect("records");
+        let Some(record) = records
+            .iter_mut()
+            .find(|record| record.status == BackupStatus::Queued)
+        else {
+            return Ok(None);
+        };
+        record.status = BackupStatus::Dumping;
+        record.started_at = Some(now);
+        record.attempt_count += 1;
+        record.updated_at = now;
+        Ok(Some(record.clone()))
+    }
+
+    async fn transition_status(
+        &self,
+        id: &str,
+        from: BackupStatus,
+        to: BackupStatus,
+        update: StatusTransitionUpdate,
+        now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        let mut records = self.records.lock().expect("records");
+        let Some(record) = records
+            .iter_mut()
+            .find(|record| record.id == id && record.status == from)
+        else {
+            return Ok(None);
+        };
+        record.status = to;
+        if let Some(size) = update.size_bytes {
+            record.size_bytes = Some(size);
+        }
+        if let Some(sha256) = update.sha256 {
+            record.sha256 = Some(sha256);
+        }
+        if let Some(code) = update.error_code {
+            record.error_code = Some(code);
+        }
+        if let Some(message) = update.error_message {
+            record.error_message = Some(message);
+        }
+        record.completed_at = update.completed_at.or_else(|| {
+            matches!(to, BackupStatus::Completed | BackupStatus::Failed).then_some(now)
+        });
+        record.updated_at = now;
+        Ok(Some(record.clone()))
+    }
+
+    async fn transition_to_deleting(
+        &self,
+        id: &str,
+        now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        let mut records = self.records.lock().expect("records");
+        let Some(record) = records
+            .iter_mut()
+            .find(|record| record.id == id && record.status.can_be_deleted())
+        else {
+            return Ok(None);
+        };
+        record.status = BackupStatus::Deleting;
+        record.updated_at = now;
+        Ok(Some(record.clone()))
+    }
+
+    async fn delete_record(&self, id: &str) -> AdminStoreResult<()> {
+        let mut records = self.records.lock().expect("records");
+        records.retain(|record| record.id != id);
+        Ok(())
+    }
+
+    async fn advance_schedule_cursor(
+        &self,
+        next_run_at: DateTime<Utc>,
+        _expected_cron: &str,
+        _expected_timezone: &str,
+    ) -> AdminStoreResult<bool> {
+        let mut settings = self.settings.lock().expect("settings");
+        settings.next_run_at = Some(next_run_at);
+        Ok(true)
+    }
+
+    async fn list_scheduled_completed_desc(
+        &self,
+        _limit: u32,
+    ) -> AdminStoreResult<Vec<BackupRecord>> {
+        let mut records = self
+            .records
+            .lock()
+            .expect("records")
+            .iter()
+            .filter(|record| {
+                record.trigger_kind == BackupTriggerKind::Scheduled
+                    && record.status == BackupStatus::Completed
+            })
+            .cloned()
+            .collect::<Vec<_>>();
+        records.sort_by(|a, b| {
+            b.completed_at
+                .cmp(&a.completed_at)
+                .then_with(|| b.id.cmp(&a.id))
+        });
+        Ok(records)
+    }
+}
+
+/// 假 `pg_dump` 端口：把固定内容写入临时文件作为归档；可注入失败。
+pub(crate) struct FakeDumpPort {
+    dir: TempDir,
+    fail_dump: bool,
+}
+
+impl FakeDumpPort {
+    pub(crate) fn new() -> Self {
+        Self {
+            dir: tempfile::tempdir().expect("temp dir"),
+            fail_dump: false,
+        }
+    }
+
+    /// 让下一次 `dump` 返回 `backup.pg_dump_failed`。
+    pub(crate) fn fail_next_dump(mut self) -> Self {
+        self.fail_dump = true;
+        self
+    }
+
+    fn artifact(&self, backup_id: &str) -> DumpArtifact {
+        let path = self.dir.path().join(format!("{backup_id}.dump"));
+        std::fs::write(&path, DUMP_CONTENT).expect("write artifact");
+        DumpArtifact {
+            path,
+            size_bytes: DUMP_CONTENT.len() as u64,
+            sha256: sha256_hex(DUMP_CONTENT),
+        }
+    }
+}
+
+#[async_trait]
+impl DatabaseDumpPort for FakeDumpPort {
+    async fn dump(
+        &self,
+        request: DumpRequest,
+    ) -> Result<DumpArtifact, gateway_admin::model::backup::BackupError> {
+        if self.fail_dump {
+            return Err(gateway_admin::model::backup::BackupError::new(
+                gateway_admin::model::backup::code::PG_DUMP_FAILED,
+                "pg_dump failed".to_owned(),
+            ));
+        }
+        if request.cancellation.is_cancelled() {
+            return Err(gateway_admin::model::backup::BackupError::new(
+                gateway_admin::model::backup::code::CANCELLED,
+                "cancelled".to_owned(),
+            ));
+        }
+        Ok(self.artifact(&request.backup_id))
+    }
+
+    async fn inspect_staging(
+        &self,
+        backup_id: &str,
+    ) -> Result<Option<StagedArtifact>, gateway_admin::model::backup::BackupError> {
+        let path = self.dir.path().join(format!("{backup_id}.dump"));
+        if !path.exists() {
+            return Ok(None);
+        }
+        Ok(Some(StagedArtifact {
+            path,
+            size_bytes: DUMP_CONTENT.len() as u64,
+            sha256: sha256_hex(DUMP_CONTENT),
+        }))
+    }
+
+    async fn cleanup_staging(
+        &self,
+        _backup_id: &str,
+    ) -> Result<(), gateway_admin::model::backup::BackupError> {
+        Ok(())
+    }
+}
+
+/// 内存版对象存储：把上传内容按 key 保存并支持 Head/Delete/预签名。
+pub(crate) struct FakeObjectStore {
+    pub(crate) objects: Mutex<std::collections::HashMap<String, Vec<u8>>>,
+    upload_error: Option<BackupError>,
+}
+
+impl FakeObjectStore {
+    pub(crate) fn new() -> Self {
+        Self {
+            objects: Mutex::new(std::collections::HashMap::new()),
+            upload_error: None,
+        }
+    }
+
+    /// 让上传返回指定的脱敏 S3 错误。
+    pub(crate) fn fail_upload(mut self, code: &'static str, message: impl Into<String>) -> Self {
+        self.upload_error = Some(BackupError::new(code, message.into()));
+        self
+    }
+
+    pub(crate) fn object(&self, key: &str) -> Option<Vec<u8>> {
+        self.objects.lock().expect("objects").get(key).cloned()
+    }
+}
+
+#[async_trait]
+impl BackupObjectStorePort for FakeObjectStore {
+    async fn test_connection(
+        &self,
+        _config: &BackupStorageConfig,
+    ) -> Result<ConnectionTestResult, gateway_admin::model::backup::BackupError> {
+        Ok(ConnectionTestResult {
+            ok: true,
+            stage: "deleteObject",
+            code: None,
+            message: "连接测试成功".to_owned(),
+        })
+    }
+
+    async fn upload_file(
+        &self,
+        _config: &BackupStorageConfig,
+        request: UploadObjectRequest,
+    ) -> Result<(), gateway_admin::model::backup::BackupError> {
+        if let Some(error) = &self.upload_error {
+            return Err(error.clone());
+        }
+        let content = std::fs::read(&request.source).map_err(|_| {
+            gateway_admin::model::backup::BackupError::new(
+                gateway_admin::model::backup::code::S3_UPLOAD_FAILED,
+                "read source".to_owned(),
+            )
+        })?;
+        self.objects
+            .lock()
+            .expect("objects")
+            .insert(request.object_key, content);
+        Ok(())
+    }
+
+    async fn head_object(
+        &self,
+        _config: &BackupStorageConfig,
+        object_key: &str,
+    ) -> Result<Option<BackupObjectMetadata>, gateway_admin::model::backup::BackupError> {
+        let Some(content) = self.object(object_key) else {
+            return Ok(None);
+        };
+        Ok(Some(BackupObjectMetadata::new(
+            "backup-test".to_owned(),
+            sha256_hex(&content),
+            Utc::now(),
+            content.len() as u64,
+        )))
+    }
+
+    async fn delete_object(
+        &self,
+        _config: &BackupStorageConfig,
+        object_key: &str,
+    ) -> Result<(), gateway_admin::model::backup::BackupError> {
+        self.objects.lock().expect("objects").remove(object_key);
+        Ok(())
+    }
+
+    async fn presigned_download(
+        &self,
+        _config: &BackupStorageConfig,
+        object_key: &str,
+        _file_name: &str,
+        _ttl: std::time::Duration,
+    ) -> Result<String, gateway_admin::model::backup::BackupError> {
+        Ok(format!("https://presigned.example.com/{object_key}"))
+    }
+}
+
+/// 记录审计事件的假 AuthStore。
+pub(crate) struct FakeAuthStore {
+    audit: Mutex<Vec<AdminAuditEvent>>,
+}
+
+impl FakeAuthStore {
+    pub(crate) fn new() -> Self {
+        Self {
+            audit: Mutex::new(Vec::new()),
+        }
+    }
+
+    pub(crate) fn audit_actions(&self) -> Vec<String> {
+        self.audit
+            .lock()
+            .expect("audit")
+            .iter()
+            .map(|event| event.action.clone())
+            .collect()
+    }
+}
+
+#[async_trait]
+impl AuthStore for FakeAuthStore {
+    async fn load_password_hash(&self, _admin_user_id: &str) -> AdminStoreResult<Option<String>> {
+        Ok(None)
+    }
+    async fn create_password_hash_if_absent(
+        &self,
+        _admin_user_id: &str,
+        _password_hash: &str,
+    ) -> AdminStoreResult<bool> {
+        Ok(true)
+    }
+    async fn load_admin_api_key(
+        &self,
+    ) -> AdminStoreResult<Option<gateway_admin::model::settings::AdminApiKey>> {
+        Ok(None)
+    }
+    async fn load_session(
+        &self,
+        _session_id: &str,
+    ) -> AdminStoreResult<Option<gateway_admin::model::auth::AdminSession>> {
+        Ok(None)
+    }
+    async fn store_session(
+        &self,
+        _session_id: &str,
+        _session: &gateway_admin::model::auth::AdminSession,
+    ) -> AdminStoreResult<()> {
+        Ok(())
+    }
+    async fn delete_session(
+        &self,
+        _session_id: &str,
+    ) -> AdminStoreResult<Option<gateway_admin::model::auth::AdminSession>> {
+        Ok(None)
+    }
+    async fn append_audit_event(&self, event: AdminAuditEvent) -> AdminStoreResult<()> {
+        self.audit.lock().expect("audit").push(event);
+        Ok(())
+    }
+}
+
+/// 系统发起者上下文。
+pub(crate) fn system_context() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "backup-runtime-test".to_owned(),
+    }
+}

backend/crates/gateway-admin/tests/backup/task.rs

@@ -0,0 +1,237 @@
+//! BackupTask 执行链测试：驱动内存 fake 端口跑完整 dump/upload/verify/retention 流程。
+
+use std::sync::Arc;
+
+use chrono::{Duration, Utc};
+use gateway_admin::{
+    backup::task::BackupTask,
+    model::backup::{
+        BackupRecordSeed, BackupStatus, BackupTriggerKind, UpdateBackupScheduleCommand, code,
+    },
+    ports::backup::{BackupRepository, DatabaseDumpPort, DumpRequest},
+};
+use gateway_core::lifecycle::CancellationToken;
+
+use super::support::{
+    DUMP_CONTENT, FakeBackupRepository, FakeDumpPort, FakeObjectStore, backup_id,
+    configured_settings, sha256_hex, system_context,
+};
+
+#[tokio::test]
+async fn backup_task_runs_full_dump_upload_verify_pipeline() {
+    let repository = Arc::new(FakeBackupRepository::new(configured_settings()));
+    let dump = Arc::new(FakeDumpPort::new());
+    let object_store = Arc::new(FakeObjectStore::new());
+
+    let seed = BackupRecordSeed {
+        id: backup_id("manual"),
+        trigger_kind: BackupTriggerKind::Manual,
+        scheduled_at: None,
+        object_key: "codex/2026/08/01/manual.dump".to_owned(),
+        expires_at: None,
+    };
+    repository
+        .insert_backup_record(seed.clone())
+        .await
+        .expect("insert queued");
+
+    let task = BackupTask::new(repository.clone(), dump.clone(), object_store.clone());
+    task.run_cycle(&CancellationToken::new())
+        .await
+        .expect("run cycle");
+
+    let records = repository.all_records();
+    assert_eq!(records.len(), 1);
+    let finished = &records[0];
+    assert_eq!(finished.status, BackupStatus::Completed);
+    assert_eq!(finished.size_bytes, Some(DUMP_CONTENT.len() as u64));
+    assert_eq!(
+        finished.sha256.as_deref(),
+        Some(sha256_hex(DUMP_CONTENT).as_str())
+    );
+
+    // 对象已上传且内容与本地归档一致。
+    let stored = object_store
+        .object(&seed.object_key)
+        .expect("uploaded object exists");
+    assert_eq!(stored.as_slice(), DUMP_CONTENT);
+}
+
+#[tokio::test]
+async fn backup_task_marks_failed_when_dump_port_fails() {
+    let repository = Arc::new(FakeBackupRepository::new(configured_settings()));
+    let dump = Arc::new(FakeDumpPort::new().fail_next_dump());
+    let object_store = Arc::new(FakeObjectStore::new());
+
+    let seed = BackupRecordSeed {
+        id: backup_id("fail"),
+        trigger_kind: BackupTriggerKind::Manual,
+        scheduled_at: None,
+        object_key: "codex/2026/08/01/fail.dump".to_owned(),
+        expires_at: None,
+    };
+    repository
+        .insert_backup_record(seed.clone())
+        .await
+        .expect("insert queued");
+
+    let task = BackupTask::new(repository.clone(), dump.clone(), object_store.clone());
+    task.run_cycle(&CancellationToken::new())
+        .await
+        .expect("run cycle");
+
+    let records = repository.all_records();
+    let failed = &records[0];
+    assert_eq!(failed.status, BackupStatus::Failed);
+    assert_eq!(failed.error_code.as_deref(), Some("backup.pg_dump_failed"));
+    assert!(failed.completed_at.is_some());
+    // 归档未上传，对象不存在。
+    assert!(object_store.object(&seed.object_key).is_none());
+}
+
+#[tokio::test]
+async fn backup_task_marks_failed_with_the_upload_error() {
+    let repository = Arc::new(FakeBackupRepository::new(configured_settings()));
+    let dump = Arc::new(FakeDumpPort::new());
+    let object_store =
+        Arc::new(FakeObjectStore::new().fail_upload(code::S3_UPLOAD_FAILED, "对象存储拒绝上传"));
+    let seed = BackupRecordSeed {
+        id: backup_id("upload-failure"),
+        trigger_kind: BackupTriggerKind::Manual,
+        scheduled_at: None,
+        object_key: "codex/2026/08/01/upload-failure.dump".to_owned(),
+        expires_at: None,
+    };
+    repository
+        .insert_backup_record(seed.clone())
+        .await
+        .expect("insert queued");
+
+    let task = BackupTask::new(repository.clone(), dump, object_store);
+    task.run_cycle(&CancellationToken::new())
+        .await
+        .expect("run cycle");
+
+    let records = repository.all_records();
+    let failed = &records[0];
+    assert_eq!(failed.status, BackupStatus::Failed);
+    assert_eq!(failed.error_code.as_deref(), Some(code::S3_UPLOAD_FAILED));
+    assert_eq!(
+        failed.error_message.as_deref(),
+        Some("上传到对象存储失败：对象存储拒绝上传")
+    );
+}
+
+#[tokio::test]
+async fn backup_task_recovery_marks_failed_with_the_upload_error() {
+    let repository = Arc::new(FakeBackupRepository::new(configured_settings()));
+    let dump = Arc::new(FakeDumpPort::new());
+    let object_store =
+        Arc::new(FakeObjectStore::new().fail_upload(code::S3_UPLOAD_FAILED, "对象存储拒绝上传"));
+    let seed = BackupRecordSeed {
+        id: backup_id("recovered-upload-failure"),
+        trigger_kind: BackupTriggerKind::Manual,
+        scheduled_at: None,
+        object_key: "codex/2026/08/01/recovered-upload-failure.dump".to_owned(),
+        expires_at: None,
+    };
+    repository
+        .insert_backup_record(seed.clone())
+        .await
+        .expect("insert queued");
+    let cancellation = CancellationToken::new();
+    dump.dump(DumpRequest {
+        backup_id: seed.id.clone(),
+        cancellation: cancellation.clone(),
+    })
+    .await
+    .expect("stage dump");
+    repository.force_status(&seed.id, BackupStatus::Dumping);
+
+    let task = BackupTask::new(repository.clone(), dump, object_store);
+    task.run_cycle(&cancellation).await.expect("run cycle");
+
+    let records = repository.all_records();
+    let failed = &records[0];
+    assert_eq!(failed.status, BackupStatus::Failed);
+    assert_eq!(failed.error_code.as_deref(), Some(code::S3_UPLOAD_FAILED));
+    assert_eq!(
+        failed.error_message.as_deref(),
+        Some("上传到对象存储失败：对象存储拒绝上传")
+    );
+}
+
+#[tokio::test]
+async fn retention_cleans_expired_scheduled_backups() {
+    let repository = Arc::new(FakeBackupRepository::new(configured_settings()));
+    let dump = Arc::new(FakeDumpPort::new());
+    let object_store = Arc::new(FakeObjectStore::new());
+
+    // 造一条旧 completed 计划备份（超过 retention_days）与一条新备份。
+    let old_seed = BackupRecordSeed {
+        id: backup_id("old"),
+        trigger_kind: BackupTriggerKind::Scheduled,
+        scheduled_at: Some(Utc::now() - Duration::days(40)),
+        object_key: "codex/2026/06/01/old.dump".to_owned(),
+        expires_at: None,
+    };
+    let new_seed = BackupRecordSeed {
+        id: backup_id("new"),
+        trigger_kind: BackupTriggerKind::Scheduled,
+        scheduled_at: Some(Utc::now() - Duration::days(1)),
+        object_key: "codex/2026/07/01/new.dump".to_owned(),
+        expires_at: None,
+    };
+    repository
+        .insert_scheduled_record(old_seed.clone())
+        .await
+        .expect("insert old");
+    // 旧备份 40 天前完成（释放活跃名额），再插入新备份。
+    let now = Utc::now();
+    repository.set_completed(&backup_id("old"), now - Duration::days(40));
+    repository
+        .insert_scheduled_record(new_seed.clone())
+        .await
+        .expect("insert new");
+    // 新备份 1 天前完成。
+    repository.set_completed(&backup_id("new"), now - Duration::days(1));
+    // 两个对象都已上传。
+    object_store
+        .objects
+        .lock()
+        .expect("objects")
+        .insert(old_seed.object_key.clone(), DUMP_CONTENT.to_vec());
+    object_store
+        .objects
+        .lock()
+        .expect("objects")
+        .insert(new_seed.object_key.clone(), DUMP_CONTENT.to_vec());
+
+    // 设置 retention_days = 30。
+    repository
+        .update_schedule_settings(
+            UpdateBackupScheduleCommand {
+                schedule_enabled: false,
+                cron_expression: "0 2 * * *".to_owned(),
+                schedule_timezone: "Asia/Shanghai".to_owned(),
+                retention_days: 30,
+                retention_count: 0,
+            },
+            None,
+            &system_context(),
+        )
+        .await
+        .expect("set retention");
+
+    let task = BackupTask::new(repository.clone(), dump.clone(), object_store.clone());
+    task.run_cycle(&CancellationToken::new())
+        .await
+        .expect("run cycle");
+
+    // 旧备份被硬删除，对象被删除；新备份保留。
+    let records = repository.all_records();
+    let ids: Vec<_> = records.iter().map(|record| record.id.as_str()).collect();
+    assert_eq!(ids, vec![backup_id("new").as_str()]);
+    assert!(object_store.object(&old_seed.object_key).is_none());
+    assert!(object_store.object(&new_seed.object_key).is_some());
+}

backend/crates/gateway-admin/tests/main.rs

@@ -0,0 +1,268 @@
+use std::str::FromStr as _;
+
+use chrono::{TimeDelta, Utc};
+use gateway_core::account::OpaqueProviderData;
+
+use gateway_admin::{
+    model::{
+        PageSize, Revision,
+        accounts::AccountUsage,
+        auth::LoginCommand,
+        client_keys::ClientKeyPageSize,
+        observability::{DecimalAmount, RequestOutcome, TimeRange},
+        provider_credentials::{
+            CredentialCommitGuard, ProviderDocument, ProviderQuota, ProviderQuotaWindow,
+            QuotaLocalUsageAttribution,
+        },
+        settings::AdminApiKey,
+    },
+    ports::store::{AccountStore, AuthStore, ClientKeyStore, ObservabilityStore, SettingsStore},
+};
+
+mod backup;
+mod model;
+mod use_case;
+
+#[test]
+fn revision_should_reject_zero() {
+    assert!(Revision::new(0).is_err());
+}
+
+#[test]
+fn page_size_should_accept_frozen_upper_bound() {
+    assert_eq!(PageSize::new(200).map(PageSize::get), Ok(200));
+}
+
+#[test]
+fn page_size_should_reject_value_above_frozen_upper_bound() {
+    assert!(PageSize::new(201).is_err());
+}
+
+#[test]
+fn client_key_page_size_should_keep_the_full_nonzero_u16_contract() {
+    assert!(ClientKeyPageSize::new(0).is_err());
+    assert_eq!(
+        ClientKeyPageSize::new(u16::MAX).map(ClientKeyPageSize::get),
+        Ok(u16::MAX)
+    );
+}
+
+#[test]
+fn request_outcome_filter_should_preserve_known_and_bounded_other_values() {
+    let known = RequestOutcome::new("succeeded").expect("known outcome");
+    let other = RequestOutcome::new("provider_future_state").expect("other outcome");
+
+    assert_eq!(known, RequestOutcome::Succeeded);
+    assert!(matches!(&other, RequestOutcome::Other(_)));
+    assert_eq!(other.as_str(), "provider_future_state");
+    assert!(RequestOutcome::new("").is_err());
+    assert!(RequestOutcome::new("a".repeat(RequestOutcome::MAX_BYTES + 1)).is_err());
+    assert!(RequestOutcome::new("future\nstate").is_err());
+}
+
+#[test]
+fn time_range_should_accept_exactly_366_days() {
+    let end = Utc::now();
+    assert!(TimeRange::new(end - TimeDelta::days(366), end).is_ok());
+}
+
+#[test]
+fn time_range_should_reject_more_than_366_days() {
+    let end = Utc::now();
+    assert!(TimeRange::new(end - TimeDelta::days(366) - TimeDelta::seconds(1), end).is_err());
+}
+
+#[test]
+fn decimal_amount_should_canonicalize_redundant_zeroes() {
+    assert_eq!(
+        DecimalAmount::from_str("00012.34000").map(|amount| amount.to_string()),
+        Ok("12.34".to_owned())
+    );
+}
+
+#[test]
+fn admin_api_key_debug_should_redact_plaintext() {
+    let key = AdminApiKey::new("secret-admin-key");
+    assert!(!format!("{key:?}").contains("secret-admin-key"));
+}
+
+#[test]
+fn login_command_debug_should_redact_password() {
+    let command = LoginCommand {
+        username: None,
+        password: "secret-password".to_owned(),
+    };
+    assert!(!format!("{command:?}").contains("secret-password"));
+}
+
+#[test]
+fn all_store_capability_traits_should_be_object_safe() {
+    fn assert_object_safe<T: ?Sized + Send + Sync>() {}
+
+    assert_object_safe::<dyn AccountStore>();
+    assert_object_safe::<dyn AuthStore>();
+    assert_object_safe::<dyn ClientKeyStore>();
+    assert_object_safe::<dyn ObservabilityStore>();
+    assert_object_safe::<dyn SettingsStore>();
+
+    fn assert_send_object_safe<T: ?Sized + Send>() {}
+    assert_send_object_safe::<dyn CredentialCommitGuard>();
+}
+
+#[test]
+fn provider_document_debug_should_not_expose_opaque_material() {
+    let document = ProviderDocument::new(OpaqueProviderData::new(Default::default()));
+    assert_eq!(
+        format!("{document:?}"),
+        "ProviderDocument([PROVIDER_OWNED])"
+    );
+}
+
+#[test]
+fn representative_quota_should_prefer_short_window_and_highest_usage() {
+    let quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![
+            quota_window("monthly", Some(2_592_000), Some(99.0)),
+            quota_window("shortTerm", Some(604_800), Some(80.0)),
+            quota_window("shortTerm", Some(18_000), Some(30.0)),
+            quota_window("shortTerm", Some(14_400), Some(45.0)),
+        ],
+        limit_reached: false,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_used_percent(), Some(45.0));
+}
+
+#[test]
+fn representative_quota_should_prefer_account_wide_window_over_model_specific_window() {
+    let mut model_specific = quota_window("shortTerm", Some(18_000), Some(64.0));
+    model_specific.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable;
+    let quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![
+            model_specific,
+            quota_window("shortTerm", Some(604_800), Some(5.0)),
+        ],
+        limit_reached: false,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_used_percent(), Some(5.0));
+}
+
+#[test]
+fn representative_window_usage_should_accept_account_wide_rolling_window_without_reset() {
+    let usage = AccountUsage {
+        account_id: "acct_xai".to_owned(),
+        request_count: 5,
+        success_count: 5,
+        input_tokens: Some(100),
+        output_tokens: Some(20),
+        cached_tokens: Some(80),
+        cache_write_tokens: Some(0),
+        reasoning_tokens: Some(0),
+        image_input_tokens: Some(0),
+        image_output_tokens: Some(0),
+        image_request_count: 0,
+        image_request_failed_count: 0,
+        total_tokens: Some(120),
+        cost_coverage: Default::default(),
+        costs: Vec::new(),
+        last_used_at: Some(Utc::now()),
+        request_buckets: Vec::new(),
+        models: Vec::new(),
+    };
+    let quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![ProviderQuotaWindow {
+            key: "free-rolling-24h".to_owned(),
+            group: "shortTerm".to_owned(),
+            label: "日限额".to_owned(),
+            limit_id: None,
+            limit_name: None,
+            role: None,
+            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+            window_seconds: Some(86_400),
+            used_percent: None,
+            reset_at: None,
+            limit_reached: false,
+            local_usage: Some(usage.clone()),
+            provider_data: None,
+        }],
+        limit_reached: false,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_window_usage(), Some(&usage));
+}
+
+#[test]
+fn exhausted_quota_should_project_full_usage_to_only_the_representative_window() {
+    let mut quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![
+            quota_window("monthly", Some(2_592_000), Some(99.0)),
+            quota_window("shortTerm", Some(604_800), Some(80.0)),
+            quota_window("shortTerm", Some(18_000), Some(30.0)),
+            quota_window("shortTerm", Some(14_400), Some(95.0)),
+        ],
+        limit_reached: true,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_used_percent(), Some(100.0));
+    quota.apply_limit_reached_display();
+
+    assert_eq!(quota.windows[0].used_percent, Some(99.0));
+    assert_eq!(quota.windows[1].used_percent, Some(80.0));
+    assert_eq!(quota.windows[2].used_percent, Some(30.0));
+    assert_eq!(quota.windows[3].used_percent, Some(100.0));
+    assert!(quota.windows[3].limit_reached);
+}
+
+#[test]
+fn exhausted_quota_should_preserve_the_provider_identified_reached_window() {
+    let mut reached = quota_window("monthly", Some(2_592_000), Some(98.0));
+    reached.limit_reached = true;
+    let mut quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![reached, quota_window("shortTerm", Some(18_000), Some(95.0))],
+        limit_reached: true,
+        provider_data: None,
+    };
+
+    quota.apply_limit_reached_display();
+
+    assert_eq!(quota.windows[0].used_percent, Some(100.0));
+    assert_eq!(quota.windows[1].used_percent, Some(95.0));
+    assert!(!quota.windows[1].limit_reached);
+}
+
+fn quota_window(
+    group: &str,
+    window_seconds: Option<u64>,
+    used_percent: Option<f64>,
+) -> ProviderQuotaWindow {
+    ProviderQuotaWindow {
+        key: group.to_owned(),
+        group: group.to_owned(),
+        label: group.to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: None,
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds,
+        used_percent,
+        reset_at: None,
+        limit_reached: false,
+        local_usage: None,
+        provider_data: None,
+    }
+}

backend/crates/gateway-admin/tests/model/backup/mod.rs

@@ -0,0 +1,104 @@
+//! 备份领域模型（model/backup）的纯逻辑测试。
+
+use chrono::{TimeZone as _, Utc};
+use secrecy::SecretString;
+
+use gateway_admin::model::backup::{
+    BackupSettings, BackupStatus, BackupStorageConfig, BackupTriggerKind, build_object_key,
+};
+
+#[test]
+fn status_machine_rejects_invalid_transitions() {
+    assert!(BackupStatus::Queued.allows_transition_to(BackupStatus::Dumping));
+    assert!(BackupStatus::Dumping.allows_transition_to(BackupStatus::Uploading));
+    assert!(BackupStatus::Uploading.allows_transition_to(BackupStatus::Completed));
+    assert!(BackupStatus::Completed.allows_transition_to(BackupStatus::Deleting));
+    assert!(!BackupStatus::Queued.allows_transition_to(BackupStatus::Completed));
+    assert!(!BackupStatus::Completed.allows_transition_to(BackupStatus::Dumping));
+    assert!(!BackupStatus::Deleting.allows_transition_to(BackupStatus::Failed));
+    assert!(!BackupStatus::Deleting.allows_transition_to(BackupStatus::Completed));
+}
+
+#[test]
+fn status_classification() {
+    assert!(BackupStatus::Queued.is_active());
+    assert!(BackupStatus::Uploading.is_active());
+    assert!(!BackupStatus::Completed.is_active());
+    assert!(BackupStatus::Completed.can_be_deleted());
+    assert!(BackupStatus::Failed.can_be_deleted());
+    assert!(!BackupStatus::Queued.can_be_deleted());
+}
+
+#[test]
+fn object_key_shape() {
+    let at = Utc.with_ymd_and_hms(2026, 8, 1, 12, 30, 0).unwrap();
+    let key = build_object_key("production/backups", "backup_abc", at).unwrap();
+    assert_eq!(
+        key,
+        "production/backups/2026/08/01/codex-proxy-rs_20260801_123000_abc.dump"
+    );
+}
+
+#[test]
+fn object_key_rejects_dangerous_prefixes() {
+    let at = Utc::now();
+    assert!(build_object_key("/leading", "backup_x", at).is_err());
+    assert!(build_object_key("a/../b", "backup_x", at).is_err());
+    assert!(build_object_key("a\\b", "backup_x", at).is_err());
+    assert!(build_object_key("a\u{0001}b", "backup_x", at).is_err());
+    assert!(build_object_key("", "backup_x", at).is_err());
+    assert!(build_object_key("trailing//", "backup_x", at).is_ok());
+}
+
+#[test]
+fn trigger_and_status_roundtrip() {
+    for status in [
+        BackupStatus::Queued,
+        BackupStatus::Dumping,
+        BackupStatus::Uploading,
+        BackupStatus::Completed,
+        BackupStatus::Failed,
+        BackupStatus::Deleting,
+    ] {
+        assert_eq!(BackupStatus::parse(status.as_str()), Some(status));
+    }
+    assert_eq!(
+        BackupTriggerKind::parse("manual"),
+        Some(BackupTriggerKind::Manual)
+    );
+    assert_eq!(
+        BackupTriggerKind::parse("scheduled"),
+        Some(BackupTriggerKind::Scheduled)
+    );
+    assert_eq!(BackupTriggerKind::parse("unknown"), None);
+    assert_eq!(BackupStatus::parse("skipped"), None);
+    assert_eq!(BackupStatus::parse("deleted"), None);
+    assert_eq!(BackupStatus::parse("unknown"), None);
+}
+
+#[test]
+fn config_from_settings_redacts_secret_in_debug() {
+    let mut settings = BackupSettings {
+        storage_revision: 3,
+        endpoint: Some("https://example.com".to_owned()),
+        region: Some("auto".to_owned()),
+        bucket: Some("b".to_owned()),
+        access_key_id: Some("ak".to_owned()),
+        secret_access_key: Some(SecretString::from("sk-secret")),
+        prefix: Some("p".to_owned()),
+        force_path_style: false,
+        schedule_enabled: false,
+        cron_expression: None,
+        schedule_timezone: None,
+        retention_days: 0,
+        retention_count: 0,
+        next_run_at: None,
+        last_verified_at: None,
+        updated_at: Utc::now(),
+    };
+    assert!(!format!("{:?}", settings).contains("sk-secret"));
+    let config = BackupStorageConfig::from_settings(&settings).unwrap();
+    assert!(!format!("{config:?}").contains("sk-secret"));
+    settings.endpoint = None;
+    assert!(BackupStorageConfig::from_settings(&settings).is_none());
+}

backend/crates/gateway-admin/tests/model/mod.rs

@@ -0,0 +1,4 @@
+//! 模型模块测试：镜像 src/model/ 中带逻辑的模块。
+
+mod backup;
+mod provider_credentials;

backend/crates/gateway-admin/tests/model/provider_credentials.rs

@@ -0,0 +1,134 @@
+use gateway_admin::model::provider_credentials::{
+    AuthorizationMutationTarget, AuthorizationOwnerBinding, PendingAuthorizationMutation,
+    ProviderQuota, ProviderQuotaWindow, ProviderQuotaWindowRole, QuotaLocalUsageAttribution,
+};
+use gateway_admin::model::{MutationActor, MutationContext};
+use gateway_core::account::ProviderAccountId;
+use gateway_core::routing::ProviderKind;
+use serde_json::{Value, json};
+
+#[test]
+fn dashboard_quota_should_preserve_unknown_and_actual_window_facts() {
+    let mut quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: Vec::new(),
+        limit_reached: false,
+        provider_data: None,
+    };
+    assert!(quota.representative_window().is_none());
+    assert!(quota.representative_used_percent().is_none());
+
+    let rolling = ProviderQuotaWindow {
+        key: "provider_rolling".to_owned(),
+        group: "requests".to_owned(),
+        label: "Provider rolling window".to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: Some(ProviderQuotaWindowRole::Primary),
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(86_400),
+        used_percent: None,
+        reset_at: None,
+        limit_reached: false,
+        local_usage: None,
+        provider_data: None,
+    };
+    quota.windows.push(rolling.clone());
+    assert_eq!(quota.representative_window(), Some(&rolling));
+    assert!(quota.representative_used_percent().is_none());
+
+    quota.windows[0].used_percent = Some(99.6);
+    quota.apply_limit_reached_display();
+    let actual = quota.representative_window().expect("actual window");
+    assert_eq!(actual.used_percent, Some(99.6));
+    assert!(
+        !actual.limit_reached,
+        "display rounding cannot exhaust quota"
+    );
+    assert_eq!(actual.window_seconds, Some(86_400));
+    assert_eq!(actual.reset_at, None);
+
+    quota.windows.insert(
+        0,
+        ProviderQuotaWindow {
+            key: "model_specific".to_owned(),
+            used_percent: Some(100.0),
+            local_usage_attribution: QuotaLocalUsageAttribution::Unavailable,
+            ..rolling
+        },
+    );
+    assert_eq!(
+        quota
+            .representative_window()
+            .map(|window| window.key.as_str()),
+        Some("provider_rolling")
+    );
+}
+
+#[test]
+fn pending_mutation_v1_should_round_trip_all_targets_and_owners() {
+    for provider in ["openai", "xai"] {
+        for target in [
+            AuthorizationMutationTarget::Create {
+                name: "account".to_owned(),
+            },
+            AuthorizationMutationTarget::Reauthorize {
+                account_id: ProviderAccountId::new("acct_1").expect("account id"),
+            },
+        ] {
+            for actor in [
+                MutationActor::AdminSession {
+                    admin_user_id: "admin-1".to_owned(),
+                },
+                MutationActor::AdminApiKey,
+                MutationActor::System,
+            ] {
+                let expected = PendingAuthorizationMutation::new(
+                    ProviderKind::new(provider).expect("provider"),
+                    target.clone(),
+                    AuthorizationOwnerBinding::from_context(&MutationContext {
+                        actor,
+                        request_id: "request-1".to_owned(),
+                    }),
+                );
+                assert_eq!(
+                    PendingAuthorizationMutation::from_storage_v1(Value::Object(
+                        expected.to_storage_v1()
+                    )),
+                    Ok(expected),
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn pending_mutation_v1_should_keep_existing_storage_fields_and_reject_invalid_documents() {
+    let legacy = json!({
+        "provider_kind": "openai",
+        "target": { "kind": "reauthorize", "account_id": "acct_1" },
+        "owner": { "kind": "admin_session", "admin_user_id": "admin-1" },
+        "started_request_id": "request-1"
+    });
+    let restored =
+        PendingAuthorizationMutation::from_storage_v1(legacy.clone()).expect("v1 document");
+    assert_eq!(Value::Object(restored.to_storage_v1()), legacy);
+    for (pointer, invalid) in [
+        ("/provider_kind", json!("")),
+        ("/target/account_id", json!("")),
+        ("/target/kind", json!("other")),
+        ("/owner/kind", json!("other")),
+        ("/started_request_id", json!(null)),
+    ] {
+        let mut document = legacy.clone();
+        *document.pointer_mut(pointer).expect("field") = invalid;
+        assert!(
+            PendingAuthorizationMutation::from_storage_v1(document).is_err(),
+            "{pointer}"
+        );
+    }
+    let mut document = legacy;
+    document["schema_version"] = json!(2);
+    assert!(PendingAuthorizationMutation::from_storage_v1(document).is_err());
+}

backend/crates/gateway-admin/tests/use_case/account_groups.rs

@@ -0,0 +1,236 @@
+use std::{
+    collections::BTreeMap,
+    str::FromStr as _,
+    sync::{Arc, Mutex},
+};
+
+use async_trait::async_trait;
+use chrono::{Duration, Utc};
+use gateway_admin::{
+    model::{
+        MutationContext, PageSize, Revision,
+        account_groups::{
+            AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupColor,
+            AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+            AccountGroupRecord, AccountGroupUsage, DeleteAccountGroup, NewAccountGroup,
+            SetAccountGroupEnabled, UpdateAccountGroup,
+        },
+        accounts::AccountRuntimeSnapshot,
+        observability::DecimalAmount,
+    },
+    ports::store::{
+        AccountGroupStore, AccountRuntimeStore, AdminStoreError, AdminStoreErrorKind,
+        AdminStoreResult,
+    },
+};
+use gateway_core::{
+    account::{AccountStatusFacts, CredentialState, QuotaState},
+    routing::AccountGroupId,
+};
+
+use super::AdminHarness;
+
+const GROUP_ID: &str = "grp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+#[tokio::test]
+async fn group_query_service_enriches_only_current_page_members_with_runtime_facts() {
+    let groups = Arc::new(FakeGroupStore::default());
+    let runtime = Arc::new(FakeRuntimeStore::default());
+    let service = AdminHarness::new()
+        .account_groups(groups.clone())
+        .account_runtime(runtime.clone())
+        .build()
+        .await;
+
+    let page = service
+        .account_groups()
+        .list(AccountGroupListQuery {
+            page: 1,
+            page_size: PageSize::new(20).expect("page size"),
+            search: None,
+            enabled: None,
+        })
+        .await
+        .expect("list projected account groups");
+
+    assert_eq!(
+        groups
+            .requested_groups
+            .lock()
+            .expect("requested groups")
+            .as_slice(),
+        [GROUP_ID]
+    );
+    assert_eq!(
+        runtime
+            .requested_accounts
+            .lock()
+            .expect("requested accounts")
+            .as_slice(),
+        ["acct_available", "acct_limited"]
+    );
+    let group = &page.items[0];
+    assert_eq!(
+        group.account_summary,
+        AccountGroupAccountSummary {
+            available: 1,
+            limited: 1,
+            total: 2,
+        }
+    );
+    assert_eq!(
+        group.capacity,
+        AccountGroupCapacity {
+            used_slots: Some(2),
+            total_slots: 4,
+        }
+    );
+}
+
+#[derive(Default)]
+struct FakeGroupStore {
+    requested_groups: Mutex<Vec<String>>,
+}
+
+#[async_trait]
+impl AccountGroupStore for FakeGroupStore {
+    async fn list_account_groups(
+        &self,
+        query: AccountGroupListQuery,
+    ) -> AdminStoreResult<AccountGroupPage> {
+        Ok(AccountGroupPage {
+            config_revision: Revision::new(1).expect("revision"),
+            items: vec![group_record()],
+            total: 1,
+            page: query.page,
+            page_size: query.page_size.get(),
+        })
+    }
+
+    async fn load_account_group_members(
+        &self,
+        group_ids: &[AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>> {
+        *self.requested_groups.lock().expect("requested groups") = group_ids
+            .iter()
+            .map(|group_id| group_id.as_str().to_owned())
+            .collect();
+        Ok(vec![member("acct_available", 4), member("acct_limited", 3)])
+    }
+
+    async fn create_account_group(
+        &self,
+        _: NewAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn update_account_group(
+        &self,
+        _: UpdateAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn set_account_group_enabled(
+        &self,
+        _: SetAccountGroupEnabled,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn delete_account_group(
+        &self,
+        _: DeleteAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+}
+
+#[derive(Default)]
+struct FakeRuntimeStore {
+    requested_accounts: Mutex<Vec<String>>,
+}
+
+#[async_trait]
+impl AccountRuntimeStore for FakeRuntimeStore {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+
+    async fn account_runtime(
+        &self,
+        account_ids: &[String],
+    ) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        *self.requested_accounts.lock().expect("requested accounts") = account_ids.to_vec();
+        Ok(AccountRuntimeSnapshot {
+            rate_limited_until: BTreeMap::from([(
+                "acct_limited".to_owned(),
+                Utc::now() + Duration::minutes(5),
+            )]),
+            in_flight: Some(BTreeMap::from([("acct_available".to_owned(), 2)])),
+        })
+    }
+}
+
+fn group_record() -> AccountGroupRecord {
+    let now = Utc::now();
+    AccountGroupRecord {
+        id: group_id(),
+        name: "Primary".to_owned(),
+        description: None,
+        color: AccountGroupColor::parse("#2563EBFF").expect("color"),
+        enabled: true,
+        member_count: 2,
+        provider_counts: BTreeMap::from([("openai".to_owned(), 2)]),
+        client_key_count: 1,
+        account_summary: AccountGroupAccountSummary {
+            available: 0,
+            limited: 0,
+            total: 0,
+        },
+        capacity: AccountGroupCapacity {
+            used_slots: None,
+            total_slots: 0,
+        },
+        usage: AccountGroupUsage {
+            today_usd: DecimalAmount::from_str("1").expect("today usage"),
+            retained_total_usd: DecimalAmount::from_str("3").expect("retained usage"),
+        },
+        created_at: now,
+        updated_at: now,
+    }
+}
+
+fn member(account_id: &str, total_slots: u64) -> AccountGroupMemberFact {
+    AccountGroupMemberFact {
+        group_id: group_id(),
+        account_id: account_id.to_owned(),
+        status: AccountStatusFacts {
+            enabled: true,
+            credential_state: CredentialState::Ready,
+            access_token_expires_at: None,
+            quota: QuotaState::default(),
+            rate_limited_until: None,
+            last_error_reason: None,
+            last_error_message: None,
+        },
+        total_slots,
+    }
+}
+
+fn group_id() -> AccountGroupId {
+    AccountGroupId::new(GROUP_ID).expect("group ID")
+}
+
+fn unused() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "account group",
+        "unused test operation",
+    )
+}

backend/crates/gateway-admin/tests/use_case/auth.rs

@@ -0,0 +1,153 @@
+use std::{collections::BTreeMap, sync::Mutex};
+
+use async_trait::async_trait;
+use chrono::{TimeDelta, Utc};
+
+use gateway_admin::{
+    model::{
+        auth::{AdminAuditEvent, AdminSession, LoginCommand},
+        settings::AdminApiKey,
+    },
+    ports::store::{AdminStoreResult, AuthStore},
+};
+
+#[derive(Default)]
+struct MemoryAuthStore {
+    password_hash: Mutex<Option<String>>,
+    sessions: Mutex<BTreeMap<String, AdminSession>>,
+    audits: Mutex<Vec<AdminAuditEvent>>,
+}
+
+#[async_trait]
+impl AuthStore for MemoryAuthStore {
+    async fn load_password_hash(&self, _: &str) -> AdminStoreResult<Option<String>> {
+        Ok(self.password_hash.lock().expect("password hash").clone())
+    }
+
+    async fn create_password_hash_if_absent(
+        &self,
+        _: &str,
+        password_hash: &str,
+    ) -> AdminStoreResult<bool> {
+        let mut stored = self.password_hash.lock().expect("password hash");
+        if stored.is_some() {
+            return Ok(false);
+        }
+        *stored = Some(password_hash.to_owned());
+        Ok(true)
+    }
+
+    async fn load_admin_api_key(&self) -> AdminStoreResult<Option<AdminApiKey>> {
+        Ok(None)
+    }
+
+    async fn load_session(&self, session_id: &str) -> AdminStoreResult<Option<AdminSession>> {
+        Ok(self
+            .sessions
+            .lock()
+            .expect("sessions")
+            .get(session_id)
+            .cloned())
+    }
+
+    async fn store_session(
+        &self,
+        session_id: &str,
+        session: &AdminSession,
+    ) -> AdminStoreResult<()> {
+        self.sessions
+            .lock()
+            .expect("sessions")
+            .insert(session_id.to_owned(), session.clone());
+        Ok(())
+    }
+
+    async fn delete_session(&self, session_id: &str) -> AdminStoreResult<Option<AdminSession>> {
+        Ok(self.sessions.lock().expect("sessions").remove(session_id))
+    }
+
+    async fn append_audit_event(&self, event: AdminAuditEvent) -> AdminStoreResult<()> {
+        self.audits.lock().expect("audits").push(event);
+        Ok(())
+    }
+}
+
+#[tokio::test]
+async fn successful_login_should_create_expiring_session_and_audit() {
+    let store = std::sync::Arc::new(MemoryAuthStore::default());
+    let services = super::AdminHarness::new().auth(store.clone()).build().await;
+
+    let result = services
+        .auth()
+        .login(LoginCommand {
+            username: Some("admin".to_owned()),
+            password: "strong-test-password".to_owned(),
+        })
+        .await
+        .expect("login");
+
+    assert!(
+        services
+            .auth()
+            .validate_session(Some(&result.session_id))
+            .await
+            .expect("validate")
+    );
+    assert_eq!(store.audits.lock().expect("audits").len(), 1);
+}
+
+#[tokio::test]
+async fn repeated_default_initialization_should_not_replace_password() {
+    let store = std::sync::Arc::new(MemoryAuthStore::default());
+    super::AdminHarness::new()
+        .auth(store.clone())
+        .default_password("first-strong-password")
+        .build()
+        .await;
+    let services = super::AdminHarness::new()
+        .auth(store)
+        .default_password("second-strong-password")
+        .build()
+        .await;
+
+    assert!(
+        services
+            .auth()
+            .login(LoginCommand {
+                username: Some("admin".to_owned()),
+                password: "first-strong-password".to_owned(),
+            })
+            .await
+            .is_ok()
+    );
+}
+
+#[tokio::test]
+async fn login_with_huge_session_ttl_should_clamp_expiry_instead_of_panicking() {
+    let store = std::sync::Arc::new(MemoryAuthStore::default());
+    let services = super::AdminHarness::new()
+        .auth(store.clone())
+        .session_ttl_minutes(i64::MAX as u64)
+        .build()
+        .await;
+
+    let before = Utc::now();
+    let result = services
+        .auth()
+        .login(LoginCommand {
+            username: Some("admin".to_owned()),
+            password: "strong-test-password".to_owned(),
+        })
+        .await
+        .expect("login with huge session TTL");
+
+    assert!(result.expires_at > before);
+    assert!(result.expires_at <= before + TimeDelta::days(366) + TimeDelta::minutes(1));
+    assert!(
+        services
+            .auth()
+            .validate_session(Some(&result.session_id))
+            .await
+            .expect("validate")
+    );
+}

backend/crates/gateway-admin/tests/use_case/backup.rs

@@ -0,0 +1,104 @@
+//! BackupService 用例测试：通过 AdminHarness 注入 fake 备份端口构造真实服务。
+
+use std::sync::Arc;
+
+use gateway_admin::model::backup::BackupStatus;
+use gateway_admin::ports::backup::BackupStorePorts;
+
+use crate::backup::support::{
+    FakeAuthStore, FakeBackupRepository, FakeDumpPort, FakeObjectStore, configured_settings,
+    system_context,
+};
+
+use super::AdminHarness;
+
+#[tokio::test]
+async fn backup_service_creates_downloads_and_deletes_with_audit() {
+    let repository = Arc::new(FakeBackupRepository::new(configured_settings()));
+    let dump = Arc::new(FakeDumpPort::new());
+    let object_store = Arc::new(FakeObjectStore::new());
+    let auth = Arc::new(FakeAuthStore::new());
+
+    let services = AdminHarness::new()
+        .auth(auth.clone())
+        .backup(BackupStorePorts::new(
+            repository.clone(),
+            dump,
+            object_store,
+        ))
+        .build()
+        .await;
+
+    // 创建手动备份 → queued + 审计。
+    let created = services
+        .backups()
+        .create_backup(&system_context(), None)
+        .await
+        .expect("create backup");
+    assert_eq!(created.status, BackupStatus::Queued);
+    assert!(created.object_key.starts_with("codex/"));
+    assert!(
+        auth.audit_actions()
+            .iter()
+            .any(|action| action == "backup.created")
+    );
+
+    // 下载地址要求 completed 记录。
+    repository.force_status(&created.id, BackupStatus::Completed);
+    let download = services
+        .backups()
+        .download_url(&system_context(), &created.id)
+        .await
+        .expect("download url");
+    assert!(download.url.starts_with("https://presigned.example.com/"));
+    assert!(
+        auth.audit_actions()
+            .iter()
+            .any(|action| action == "backup.download_url_created")
+    );
+
+    // 删除 → deleting + 审计。
+    let deleting = services
+        .backups()
+        .delete_backup(&system_context(), &created.id)
+        .await
+        .expect("delete backup");
+    assert_eq!(deleting.status, BackupStatus::Deleting);
+    assert!(
+        auth.audit_actions()
+            .iter()
+            .any(|action| action == "backup.delete_requested")
+    );
+}
+
+#[tokio::test]
+async fn backup_service_rejects_download_of_non_completed_record() {
+    let repository = Arc::new(FakeBackupRepository::new(configured_settings()));
+    let dump = Arc::new(FakeDumpPort::new());
+    let object_store = Arc::new(FakeObjectStore::new());
+    let auth = Arc::new(FakeAuthStore::new());
+
+    let services = AdminHarness::new()
+        .auth(auth.clone())
+        .backup(BackupStorePorts::new(
+            repository.clone(),
+            dump,
+            object_store,
+        ))
+        .build()
+        .await;
+
+    let created = services
+        .backups()
+        .create_backup(&system_context(), None)
+        .await
+        .expect("create backup");
+
+    // queued 记录不能创建下载地址。
+    let error = services
+        .backups()
+        .download_url(&system_context(), &created.id)
+        .await
+        .expect_err("non-completed record must be rejected");
+    assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::Conflict);
+}

backend/crates/gateway-admin/tests/use_case/client_keys.rs

@@ -0,0 +1,127 @@
+use async_trait::async_trait;
+use gateway_core::policy::ClientApiKeyId;
+
+use gateway_admin::{
+    model::{
+        AdminErrorKind, MutationContext, Revision,
+        client_keys::{
+            ClientKeyCursor, ClientKeyCursorValue, ClientKeyListQuery, ClientKeyPage,
+            ClientKeyPageSize, ClientKeyRecord, ClientKeySecret, ClientKeySort, ClientKeySortField,
+            DeleteClientKey, NewClientKey, SetClientKeyEnabled, SortDirection, UpdateClientKey,
+        },
+    },
+    ports::store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult, ClientKeyStore},
+};
+
+struct UnusedClientKeyStore;
+
+#[async_trait]
+impl ClientKeyStore for UnusedClientKeyStore {
+    async fn list_client_keys(&self, query: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage> {
+        assert_eq!(query.page_size.get(), u16::MAX);
+        Ok(ClientKeyPage {
+            config_revision: Revision::new(1).expect("revision"),
+            items: Vec::new(),
+            total: 0,
+            next_cursor: None,
+        })
+    }
+
+    async fn reveal_client_key(
+        &self,
+        _: &ClientApiKeyId,
+    ) -> AdminStoreResult<Option<ClientKeySecret>> {
+        Err(unused())
+    }
+
+    async fn create_client_key(
+        &self,
+        _: NewClientKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
+        Err(unused())
+    }
+
+    async fn update_client_key(
+        &self,
+        _: UpdateClientKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
+        Err(unused())
+    }
+
+    async fn set_client_key_enabled(
+        &self,
+        _: SetClientKeyEnabled,
+        _: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
+        Err(unused())
+    }
+
+    async fn delete_client_key(
+        &self,
+        _: DeleteClientKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unused())
+    }
+}
+
+#[tokio::test]
+async fn client_key_cursor_should_reject_value_that_does_not_match_sort() {
+    let services = super::AdminHarness::new()
+        .client_keys(std::sync::Arc::new(UnusedClientKeyStore))
+        .build()
+        .await;
+    let sort = ClientKeySort {
+        field: ClientKeySortField::Name,
+        direction: SortDirection::Asc,
+    };
+    let error = services
+        .client_keys()
+        .list(ClientKeyListQuery {
+            cursor: Some(ClientKeyCursor {
+                sort,
+                value: ClientKeyCursorValue::Enabled(true),
+                id: ClientApiKeyId::new("key_cursor").expect("key ID"),
+            }),
+            page_size: ClientKeyPageSize::new(50).expect("page size"),
+            search: None,
+            sort,
+        })
+        .await
+        .expect_err("mismatched cursor must fail");
+
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+}
+
+#[tokio::test]
+async fn client_key_list_should_forward_the_full_nonzero_u16_page_size() {
+    let services = super::AdminHarness::new()
+        .client_keys(std::sync::Arc::new(UnusedClientKeyStore))
+        .build()
+        .await;
+    let page = services
+        .client_keys()
+        .list(ClientKeyListQuery {
+            cursor: None,
+            page_size: ClientKeyPageSize::new(u16::MAX).expect("maximum page size"),
+            search: None,
+            sort: ClientKeySort {
+                field: ClientKeySortField::CreatedAt,
+                direction: SortDirection::Desc,
+            },
+        })
+        .await
+        .expect("maximum page size should reach store");
+
+    assert_eq!(page.total, 0);
+}
+
+fn unused() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "client key",
+        "unused in this test",
+    )
+}

backend/crates/gateway-admin/tests/use_case/mod.rs

@@ -0,0 +1,857 @@
+mod account_groups;
+mod accounts;
+mod auth;
+mod backup;
+mod client_keys;
+mod observability;
+mod openai;
+mod settings;
+mod system;
+mod xai;
+
+use std::{
+    str::FromStr,
+    sync::{Arc, Mutex},
+};
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use futures::future::BoxFuture;
+use gateway_admin::{
+    AdminConfig, AdminServices, InitialAdminPassword,
+    model::{
+        MutationContext, Revision,
+        account_groups::{
+            AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+            DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+        },
+        accounts::{
+            AccountListQuery, AccountPage, AccountRuntimeSnapshot, AccountUpdateResult,
+            AccountUsage, AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
+            BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
+        },
+        auth::{AdminAuditEvent, AdminSession},
+        client_distribution::CodexDesktopWindowsDownloads,
+        client_keys::{
+            ClientKeyListQuery, ClientKeyPage, ClientKeyRecord, ClientKeySecret, DeleteClientKey,
+            NewClientKey, SetClientKeyEnabled, UpdateClientKey,
+        },
+        observability::{
+            DashboardDesktopRelease, DashboardObservation, DashboardWireAttribute,
+            DashboardWireProfile, DashboardWireTarget, DesktopReleaseStatus, DiagnosticDimension,
+            DiagnosticObservation, OpsErrorPage, OpsErrorQuery, RequestMetricPoint, TimeRange,
+            UsageDetail, UsageFilter, UsageOverview, UsagePage, UsageQuery,
+        },
+        provider_credentials::{
+            AuthorizationCommit, AuthorizationStarted, CompleteAuthorization, CredentialDetails,
+            CredentialImportCommit, CredentialImportResult, CredentialListQuery,
+            CredentialMutationResult, CredentialPage, CredentialRotationCommit,
+            PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
+            PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
+            PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput,
+            ProviderModels, ProviderQuota,
+        },
+        settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
+        system::{SystemOperationAccepted, SystemUpdateDetail, SystemUpdateStatus, SystemVersion},
+    },
+    ports::{
+        backup::BackupStorePorts,
+        client_distribution::ClientDistributionResolver,
+        provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind},
+        store::{
+            AccountGroupStore, AccountRuntimeStore, AccountStore, AdminAccountStorePorts,
+            AdminStoreError, AdminStoreErrorKind, AdminStorePorts, AdminStoreResult, AuthStore,
+            ClientKeyStore, ObservabilityStore, SettingsStore,
+        },
+        system::{
+            SystemOperationError, SystemOperationErrorKind, SystemOperations,
+            SystemUpdateEventStream,
+        },
+    },
+};
+use gateway_core::{
+    account::ProviderAccountId,
+    engine::probe::{AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult},
+    error::{GatewayError, GatewayErrorKind},
+    policy::ClientApiKeyId,
+    routing::{ConfigRevision, ProviderKind},
+    runtime::SnapshotControl,
+};
+
+pub(super) struct AdminHarness {
+    default_password: String,
+    session_ttl_minutes: u64,
+    accounts: Arc<dyn AccountStore>,
+    account_runtime: Arc<dyn AccountRuntimeStore>,
+    account_groups: Arc<dyn AccountGroupStore>,
+    auth: Arc<dyn AuthStore>,
+    client_keys: Arc<dyn ClientKeyStore>,
+    observability: Arc<dyn ObservabilityStore>,
+    settings: Arc<dyn SettingsStore>,
+    backup: BackupStorePorts,
+    providers: Vec<Arc<dyn ProviderAdmin>>,
+    probe: Arc<dyn AccountProbe>,
+    system: Arc<dyn SystemOperations>,
+}
+
+impl AdminHarness {
+    pub(super) fn new() -> Self {
+        let unavailable = Arc::new(UnavailableStore);
+        Self {
+            default_password: "strong-test-password".to_owned(),
+            session_ttl_minutes: 60,
+            accounts: unavailable.clone(),
+            account_runtime: unavailable.clone(),
+            account_groups: Arc::new(UnavailableAccountGroupStore),
+            auth: Arc::new(BootstrapAuthStore::default()),
+            client_keys: unavailable.clone(),
+            observability: unavailable.clone(),
+            settings: unavailable,
+            backup: BackupStorePorts::disabled(),
+            providers: vec![
+                Arc::new(UnavailableProvider::new("openai")),
+                Arc::new(UnavailableProvider::new("xai")),
+            ],
+            probe: Arc::new(UnavailableProbe),
+            system: Arc::new(UnavailableSystem),
+        }
+    }
+
+    pub(super) fn default_password(mut self, password: &str) -> Self {
+        self.default_password = password.to_owned();
+        self
+    }
+
+    pub(super) fn session_ttl_minutes(mut self, minutes: u64) -> Self {
+        self.session_ttl_minutes = minutes;
+        self
+    }
+
+    pub(super) fn accounts(mut self, store: Arc<dyn AccountStore>) -> Self {
+        self.accounts = store;
+        self
+    }
+
+    pub(super) fn account_runtime(mut self, store: Arc<dyn AccountRuntimeStore>) -> Self {
+        self.account_runtime = store;
+        self
+    }
+
+    pub(super) fn account_groups(mut self, store: Arc<dyn AccountGroupStore>) -> Self {
+        self.account_groups = store;
+        self
+    }
+
+    pub(super) fn auth(mut self, store: Arc<dyn AuthStore>) -> Self {
+        self.auth = store;
+        self
+    }
+
+    pub(super) fn client_keys(mut self, store: Arc<dyn ClientKeyStore>) -> Self {
+        self.client_keys = store;
+        self
+    }
+
+    pub(super) fn observability(mut self, store: Arc<dyn ObservabilityStore>) -> Self {
+        self.observability = store;
+        self
+    }
+
+    pub(super) fn settings(mut self, store: Arc<dyn SettingsStore>) -> Self {
+        self.settings = store;
+        self
+    }
+
+    pub(super) fn backup(mut self, backup: BackupStorePorts) -> Self {
+        self.backup = backup;
+        self
+    }
+
+    pub(super) fn provider(mut self, provider: Arc<dyn ProviderAdmin>) -> Self {
+        self.providers
+            .retain(|registered| registered.provider_kind() != provider.provider_kind());
+        self.providers.push(provider);
+        self
+    }
+
+    pub(super) fn probe(mut self, probe: Arc<dyn AccountProbe>) -> Self {
+        self.probe = probe;
+        self
+    }
+
+    pub(super) fn system(mut self, system: Arc<dyn SystemOperations>) -> Self {
+        self.system = system;
+        self
+    }
+
+    pub(super) async fn build(self) -> AdminServices {
+        gateway_admin::initialize(
+            AdminConfig {
+                session_ttl_minutes: self.session_ttl_minutes,
+                default_username: "admin".to_owned(),
+                default_password: InitialAdminPassword::new(self.default_password),
+            },
+            AdminStorePorts::new(
+                AdminAccountStorePorts::new(
+                    self.accounts,
+                    self.account_runtime,
+                    self.account_groups,
+                ),
+                self.auth,
+                self.client_keys,
+                self.observability,
+                self.settings,
+                self.backup,
+            ),
+            self.providers,
+            Arc::new(NoopSnapshot),
+            self.probe,
+            Arc::new(NoopClientDistribution),
+            self.system,
+        )
+        .await
+        .expect("initialize admin test harness")
+        .services()
+    }
+}
+
+struct NoopClientDistribution;
+
+#[async_trait]
+impl ClientDistributionResolver for NoopClientDistribution {
+    async fn resolve_codex_desktop_windows(&self, _: bool) -> CodexDesktopWindowsDownloads {
+        CodexDesktopWindowsDownloads {
+            resolved_at: Utc::now(),
+            cached: false,
+            warning: None,
+            packages: Vec::new(),
+        }
+    }
+}
+
+#[derive(Default)]
+struct BootstrapAuthStore {
+    password_hash: Mutex<Option<String>>,
+}
+
+#[async_trait]
+impl AuthStore for BootstrapAuthStore {
+    async fn load_password_hash(&self, _: &str) -> AdminStoreResult<Option<String>> {
+        Ok(self.password_hash.lock().expect("password hash").clone())
+    }
+
+    async fn create_password_hash_if_absent(
+        &self,
+        _: &str,
+        password_hash: &str,
+    ) -> AdminStoreResult<bool> {
+        let mut stored = self.password_hash.lock().expect("password hash");
+        if stored.is_some() {
+            return Ok(false);
+        }
+        *stored = Some(password_hash.to_owned());
+        Ok(true)
+    }
+
+    async fn load_admin_api_key(&self) -> AdminStoreResult<Option<AdminApiKey>> {
+        Ok(None)
+    }
+
+    async fn load_session(&self, _: &str) -> AdminStoreResult<Option<AdminSession>> {
+        Ok(None)
+    }
+
+    async fn store_session(&self, _: &str, _: &AdminSession) -> AdminStoreResult<()> {
+        Err(unavailable("admin session"))
+    }
+
+    async fn delete_session(&self, _: &str) -> AdminStoreResult<Option<AdminSession>> {
+        Err(unavailable("admin session"))
+    }
+
+    async fn append_audit_event(&self, _: AdminAuditEvent) -> AdminStoreResult<()> {
+        Ok(())
+    }
+}
+
+struct UnavailableStore;
+
+struct UnavailableAccountGroupStore;
+
+#[async_trait]
+impl AccountGroupStore for UnavailableAccountGroupStore {
+    async fn list_account_groups(
+        &self,
+        _: AccountGroupListQuery,
+    ) -> AdminStoreResult<AccountGroupPage> {
+        Err(unavailable("account groups"))
+    }
+
+    async fn load_account_group_members(
+        &self,
+        _: &[gateway_core::routing::AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>> {
+        Err(unavailable("account group members"))
+    }
+
+    async fn create_account_group(
+        &self,
+        _: NewAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unavailable("account group create"))
+    }
+
+    async fn update_account_group(
+        &self,
+        _: UpdateAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unavailable("account group update"))
+    }
+
+    async fn set_account_group_enabled(
+        &self,
+        _: SetAccountGroupEnabled,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unavailable("account group state"))
+    }
+
+    async fn delete_account_group(
+        &self,
+        _: DeleteAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unavailable("account group delete"))
+    }
+}
+
+#[async_trait]
+impl AccountStore for UnavailableStore {
+    async fn list_accounts(
+        &self,
+        _: AccountListQuery,
+        _: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<AccountPage> {
+        Err(unavailable("accounts"))
+    }
+
+    async fn load_account(
+        &self,
+        _: &str,
+        _: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<Option<gateway_admin::model::accounts::AccountPageItem>> {
+        Err(unavailable("account"))
+    }
+
+    async fn load_account_usage(
+        &self,
+        _: TimeRange,
+        _: &[String],
+    ) -> AdminStoreResult<Vec<AccountUsage>> {
+        Err(unavailable("account usage"))
+    }
+
+    async fn load_account_usage_by_windows(
+        &self,
+        _: &[AccountUsageWindowQuery],
+    ) -> AdminStoreResult<Vec<AccountUsageWindowResult>> {
+        Err(unavailable("account quota window usage"))
+    }
+
+    async fn list_credentials(
+        &self,
+        _: &ProviderKind,
+        _: CredentialListQuery,
+    ) -> AdminStoreResult<CredentialPage> {
+        Err(unavailable("credentials"))
+    }
+
+    async fn credential_details(
+        &self,
+        _: &ProviderKind,
+        _: &ProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>> {
+        Err(unavailable("credential"))
+    }
+
+    async fn load_credentials_for_export(
+        &self,
+        _: &ProviderKind,
+        _: &[ProviderAccountId],
+    ) -> AdminStoreResult<Vec<ProviderExportCredentialInput>> {
+        Err(unavailable("credential export"))
+    }
+
+    async fn commit_credential_import(
+        &self,
+        _: CredentialImportCommit,
+        _: &MutationContext,
+    ) -> AdminStoreResult<CredentialImportResult> {
+        Err(unavailable("credential import"))
+    }
+
+    async fn commit_authorization(
+        &self,
+        _: AuthorizationCommit,
+        _: &MutationContext,
+    ) -> AdminStoreResult<CredentialMutationResult> {
+        Err(unavailable("authorization"))
+    }
+
+    async fn commit_credential_rotation(
+        &self,
+        _: CredentialRotationCommit,
+        _: &MutationContext,
+    ) -> AdminStoreResult<CredentialMutationResult> {
+        Err(unavailable("credential rotation"))
+    }
+
+    async fn commit_credential_refresh(
+        &self,
+        _: CredentialRotationCommit,
+        _: &MutationContext,
+    ) -> AdminStoreResult<CredentialMutationResult> {
+        Err(unavailable("credential refresh"))
+    }
+
+    async fn update_account(
+        &self,
+        _: UpdateAccount,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountUpdateResult> {
+        Err(unavailable("account enabled"))
+    }
+
+    async fn recover_account(
+        &self,
+        _: &ProviderAccountId,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountUpdateResult> {
+        Err(unavailable("account recovery"))
+    }
+
+    async fn batch_update_accounts(
+        &self,
+        _: BatchUpdateAccounts,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountsUpdateResult> {
+        Err(unavailable("account batch update"))
+    }
+
+    async fn delete_accounts(
+        &self,
+        _: DeleteAccounts,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable("account delete"))
+    }
+
+    async fn record_credential_export(
+        &self,
+        _: &[ProviderAccountId],
+        _: &MutationContext,
+    ) -> AdminStoreResult<()> {
+        Err(unavailable("credential export audit"))
+    }
+}
+
+#[async_trait]
+impl AccountRuntimeStore for UnavailableStore {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+
+    async fn account_runtime(&self, _: &[String]) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+}
+
+#[async_trait]
+impl ClientKeyStore for UnavailableStore {
+    async fn list_client_keys(&self, _: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage> {
+        Err(unavailable("client key list"))
+    }
+
+    async fn reveal_client_key(
+        &self,
+        _: &ClientApiKeyId,
+    ) -> AdminStoreResult<Option<ClientKeySecret>> {
+        Err(unavailable("client key"))
+    }
+
+    async fn create_client_key(
+        &self,
+        _: NewClientKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
+        Err(unavailable("client key create"))
+    }
+
+    async fn update_client_key(
+        &self,
+        _: UpdateClientKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
+        Err(unavailable("client key update"))
+    }
+
+    async fn set_client_key_enabled(
+        &self,
+        _: SetClientKeyEnabled,
+        _: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
+        Err(unavailable("client key enabled"))
+    }
+
+    async fn delete_client_key(
+        &self,
+        _: DeleteClientKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable("client key delete"))
+    }
+}
+
+#[async_trait]
+impl ObservabilityStore for UnavailableStore {
+    async fn dashboard_summary(
+        &self,
+        _: TimeRange,
+        _: DateTime<Utc>,
+    ) -> AdminStoreResult<DashboardObservation> {
+        Err(unavailable("dashboard"))
+    }
+
+    async fn dashboard_trend(&self, _: TimeRange) -> AdminStoreResult<Vec<RequestMetricPoint>> {
+        Err(unavailable("dashboard trend"))
+    }
+
+    async fn usage_trend(
+        &self,
+        _: TimeRange,
+        _: UsageFilter,
+    ) -> AdminStoreResult<Vec<RequestMetricPoint>> {
+        Err(unavailable("usage trend"))
+    }
+
+    fn usage_calculated_billing_facts(
+        &self,
+        _: TimeRange,
+        _: UsageFilter,
+    ) -> gateway_admin::ports::store::UsageCalculatedBillingStream<'_> {
+        Box::pin(futures::stream::once(async {
+            Err(unavailable("usage billing facts"))
+        }))
+    }
+
+    async fn list_usage_records(&self, _: UsageQuery) -> AdminStoreResult<UsagePage> {
+        Err(unavailable("usage records"))
+    }
+
+    async fn usage_record_detail(&self, _: &str) -> AdminStoreResult<UsageDetail> {
+        Err(unavailable("usage detail"))
+    }
+
+    async fn usage_summary(&self, _: TimeRange, _: UsageFilter) -> AdminStoreResult<UsageOverview> {
+        Err(unavailable("usage summary"))
+    }
+
+    async fn usage_diagnostics(
+        &self,
+        _: TimeRange,
+        _: UsageFilter,
+        _: DiagnosticDimension,
+    ) -> AdminStoreResult<Vec<DiagnosticObservation>> {
+        Err(unavailable("usage diagnostics"))
+    }
+
+    async fn list_ops_errors(&self, _: OpsErrorQuery) -> AdminStoreResult<OpsErrorPage> {
+        Err(unavailable("ops errors"))
+    }
+}
+
+#[async_trait]
+impl SettingsStore for UnavailableStore {
+    async fn load_runtime_settings(&self) -> AdminStoreResult<RuntimeSettings> {
+        Err(unavailable("settings"))
+    }
+
+    async fn admin_api_key_exists(&self) -> AdminStoreResult<bool> {
+        Err(unavailable("admin API key"))
+    }
+
+    async fn replace_runtime_settings(
+        &self,
+        _: ReplaceRuntimeSettings,
+        _: &MutationContext,
+    ) -> AdminStoreResult<RuntimeSettings> {
+        Err(unavailable("settings"))
+    }
+
+    async fn replace_admin_api_key(
+        &self,
+        _: AdminApiKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation> {
+        Err(unavailable("admin API key"))
+    }
+
+    async fn delete_admin_api_key(
+        &self,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation> {
+        Err(unavailable("admin API key"))
+    }
+}
+
+struct UnavailableProvider {
+    kind: ProviderKind,
+    dashboard_profile: Option<DashboardWireProfile>,
+    calculated_billing: Option<gateway_admin::model::observability::CalculatedBillingBreakdown>,
+}
+
+impl UnavailableProvider {
+    fn new(kind: &str) -> Self {
+        Self {
+            kind: ProviderKind::new(kind).expect("provider kind"),
+            dashboard_profile: None,
+            calculated_billing: None,
+        }
+    }
+}
+
+#[async_trait]
+impl ProviderAdmin for UnavailableProvider {
+    fn provider_kind(&self) -> &ProviderKind {
+        &self.kind
+    }
+
+    async fn account_unavailable(&self, _: &ProviderAccountId) {}
+
+    fn connection_test_operation(
+        &self,
+        _: &gateway_core::routing::UpstreamModelId,
+        _: &str,
+    ) -> Result<gateway_core::operation::Operation, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+
+    fn dashboard_wire_profile(&self) -> Option<DashboardWireProfile> {
+        self.dashboard_profile.clone()
+    }
+
+    fn calculated_billing(
+        &self,
+        _: &gateway_admin::model::observability::ProviderBillingInput,
+    ) -> Result<
+        Option<gateway_admin::model::observability::CalculatedBillingBreakdown>,
+        ProviderAdminError,
+    > {
+        Ok(self.calculated_billing.clone())
+    }
+
+    async fn prepare_import(
+        &self,
+        _: PrepareCredentialImport,
+    ) -> Result<PreparedCredentialImport, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+
+    async fn start_authorization(
+        &self,
+        _: PendingAuthorizationMutation,
+    ) -> Result<AuthorizationStarted, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+
+    async fn complete_authorization(
+        &self,
+        _: CompleteAuthorization,
+    ) -> Result<PreparedAuthorizationCommit, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+
+    async fn prepare_rotation(
+        &self,
+        _: PrepareCredentialRotation,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+
+    async fn prepare_refresh(
+        &self,
+        _: PrepareCredentialRefresh,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+
+    async fn quota(
+        &self,
+        _: gateway_admin::model::provider_credentials::ProviderQuotaRequest,
+    ) -> Result<ProviderQuota, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+
+    async fn models(
+        &self,
+        _: &ProviderAccountId,
+        _: bool,
+    ) -> Result<ProviderModels, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+
+    async fn export_credentials(
+        &self,
+        _: Vec<ProviderExportCredentialInput>,
+    ) -> Result<ProviderExport, ProviderAdminError> {
+        Err(unsupported_provider())
+    }
+}
+
+pub(super) fn dashboard_profile_provider() -> Arc<dyn ProviderAdmin> {
+    Arc::new(UnavailableProvider {
+        kind: ProviderKind::new("openai").expect("provider kind"),
+        dashboard_profile: Some(DashboardWireProfile {
+            provider: "openai".to_owned(),
+            product: "gateway-admin-test".to_owned(),
+            version: "test".to_owned(),
+            build: Some("test".to_owned()),
+            target: DashboardWireTarget {
+                os_type: "linux".to_owned(),
+                os_version: "test".to_owned(),
+                arch: "x86_64".to_owned(),
+                terminal: "test".to_owned(),
+            },
+            user_agent: "gateway-admin-test".to_owned(),
+            attributes: vec![DashboardWireAttribute {
+                label: "Core".to_owned(),
+                value: "test".to_owned(),
+            }],
+            verified_at: Some(chrono::Utc::now()),
+            release: Some(DashboardDesktopRelease {
+                status: DesktopReleaseStatus::Unchecked,
+                checked_at: None,
+                latest_version: None,
+                latest_build: None,
+                published_at: None,
+                minimum_system_version: None,
+                hardware_requirements: None,
+                download_url: None,
+                download_size: None,
+                signature_present: None,
+                error: None,
+            }),
+        }),
+        calculated_billing: None,
+    })
+}
+
+pub(super) fn calculated_billing_provider() -> Arc<dyn ProviderAdmin> {
+    let amount = |value| gateway_admin::model::observability::CurrencyCost {
+        currency: "USD".to_owned(),
+        amount: gateway_admin::model::observability::DecimalAmount::from_str(value)
+            .expect("test billing amount"),
+    };
+    Arc::new(UnavailableProvider {
+        kind: ProviderKind::new("openai").expect("provider kind"),
+        dashboard_profile: None,
+        calculated_billing: Some(
+            gateway_admin::model::observability::CalculatedBillingBreakdown {
+                input_amount: amount("0.8"),
+                output_amount: amount("0.2"),
+                cache_read_amount: amount("0"),
+                cache_write_amount: amount("0"),
+                standard_amount: amount("1"),
+                total_amount: amount("1.25"),
+                input_price_per_million: amount("0"),
+                output_price_per_million: amount("0"),
+                cache_read_price_per_million: amount("0"),
+                cache_write_price_per_million: amount("0"),
+                service_tier: None,
+                multiplier_percent: 125,
+            },
+        ),
+    })
+}
+
+struct NoopSnapshot;
+
+impl SnapshotControl for NoopSnapshot {
+    fn publish_committed(&self, _: ConfigRevision) -> BoxFuture<'_, ()> {
+        Box::pin(async {})
+    }
+}
+
+struct UnavailableProbe;
+
+impl AccountProbe for UnavailableProbe {
+    fn probe(
+        &self,
+        _: AccountProbeRequest,
+    ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
+        Box::pin(async {
+            Err(GatewayError::new(
+                GatewayErrorKind::Internal,
+                "test account probe is unavailable",
+            )
+            .into())
+        })
+    }
+}
+
+struct UnavailableSystem;
+
+#[async_trait]
+impl SystemOperations for UnavailableSystem {
+    async fn version(&self) -> Result<SystemVersion, SystemOperationError> {
+        Err(unavailable_system())
+    }
+
+    async fn update_detail(&self, _: bool) -> Result<SystemUpdateDetail, SystemOperationError> {
+        Err(unavailable_system())
+    }
+
+    fn update_events(&self) -> SystemUpdateEventStream {
+        Box::pin(futures::stream::empty())
+    }
+
+    async fn perform_update(
+        &self,
+        _: Option<String>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
+        Err(unavailable_system())
+    }
+
+    async fn update_status(&self) -> Result<SystemUpdateStatus, SystemOperationError> {
+        Err(unavailable_system())
+    }
+
+    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+        Err(unavailable_system())
+    }
+
+    async fn restart(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+        Err(unavailable_system())
+    }
+}
+
+fn unavailable(resource: &'static str) -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        resource,
+        "unavailable in this test",
+    )
+}
+
+fn unsupported_provider() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::Unsupported)
+}
+
+fn unavailable_system() -> SystemOperationError {
+    SystemOperationError::new(
+        SystemOperationErrorKind::Internal,
+        "unavailable in this test",
+    )
+}

backend/crates/gateway-admin/tests/use_case/observability.rs

@@ -0,0 +1,926 @@
+use std::{
+    str::FromStr as _,
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, AtomicUsize, Ordering},
+    },
+    time::Duration as StdDuration,
+};
+
+use async_trait::async_trait;
+use chrono::{DateTime, Duration, Timelike as _, Utc};
+
+use gateway_admin::{
+    AdminServices,
+    model::{
+        MutationContext, PageSize, Revision,
+        observability::{
+            AccountPoolMetrics, AttemptMetrics, CostCoverage, CurrencyCost, DashboardObservation,
+            DashboardRuntimeSlots, DiagnosticDimension, DiagnosticObservation, Granularity,
+            HealthStatus, LatencyPercentiles, OpsErrorPage, OpsErrorQuery, PercentileMilliseconds,
+            RequestMetricPoint, RequestMetrics, TimeRange, TrendKind, UsageBilling,
+            UsageCalculatedBillingFact, UsageDetail, UsageFilter, UsageListRecord, UsageOverview,
+            UsagePage, UsageQuery, china_day_start,
+        },
+        settings::{
+            AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RotationStrategy,
+            RuntimeSettings,
+        },
+    },
+    ports::store::{AdminStoreResult, ObservabilityStore, SettingsStore},
+};
+
+#[test]
+fn external_observability_range_accepts_exactly_366_days() {
+    let end = Utc::now();
+    let range = TimeRange::new(end - Duration::days(366), end)
+        .expect("366-day external range should be accepted");
+    assert_eq!(range.end, end);
+}
+
+#[test]
+fn external_observability_range_rejects_over_366_days_and_reversed_range() {
+    let end = Utc::now();
+    assert!(TimeRange::new(end - Duration::days(367), end).is_err());
+    assert!(TimeRange::new(end, end).is_err());
+    assert!(TimeRange::new(end + Duration::seconds(1), end).is_err());
+}
+
+#[tokio::test]
+async fn health_timeline_should_keep_exactly_china_day_quarter_hour_slots() {
+    let now = Utc::now();
+    let day_start = china_day_start(now);
+    let current_slot = quarter_hour_start(now);
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
+    store.replace_trend(vec![
+        health_metric_point(
+            day_start - Duration::minutes(15),
+            RequestMetrics {
+                success_count: 100,
+                ..RequestMetrics::default()
+            },
+        ),
+        health_metric_point(
+            current_slot,
+            RequestMetrics {
+                success_count: 2,
+                ..RequestMetrics::default()
+            },
+        ),
+        health_metric_point(
+            current_slot + Duration::minutes(15),
+            RequestMetrics {
+                success_count: 100,
+                ..RequestMetrics::default()
+            },
+        ),
+    ]);
+    let services = observability_services(store).await;
+
+    let timeline = services
+        .observability()
+        .dashboard_summary(observation_range(now), TrendKind::Usage)
+        .await
+        .expect("dashboard summary")
+        .health_timeline;
+
+    assert_eq!(timeline.points.len(), 96);
+    assert_eq!(
+        timeline.points.first().map(|point| point.bucket_start),
+        Some(day_start)
+    );
+    assert_eq!(
+        timeline.points.last().map(|point| point.bucket_start),
+        Some(day_start + Duration::minutes(95 * 15))
+    );
+    assert_eq!(timeline.success_requests, 2);
+    assert_eq!(
+        timeline
+            .points
+            .iter()
+            .find(|point| point.bucket_start == current_slot)
+            .map(|point| point.status),
+        Some(HealthStatus::LowSample)
+    );
+    assert!(timeline.points.iter().all(|point| {
+        point.bucket_start <= quarter_hour_start(Utc::now())
+            || (point.status == HealthStatus::Future && point.success_requests == 0)
+    }));
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_derive_first_token_average_from_trend() {
+    let now = Utc::now();
+    let current_slot = quarter_hour_start(now);
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
+    store.replace_trend(vec![
+        health_metric_point(
+            current_slot - Duration::minutes(15),
+            RequestMetrics {
+                first_token_latency_sum_ms: 120,
+                first_token_latency_count: 2,
+                ..RequestMetrics::default()
+            },
+        ),
+        health_metric_point(
+            current_slot,
+            RequestMetrics {
+                first_token_latency_sum_ms: 180,
+                first_token_latency_count: 1,
+                ..RequestMetrics::default()
+            },
+        ),
+    ]);
+    let services = observability_services(store).await;
+
+    let summary = services
+        .observability()
+        .dashboard_summary(observation_range(now), TrendKind::Usage)
+        .await
+        .expect("dashboard summary");
+
+    assert_eq!(summary.average_first_token_latency_ms, Some(100));
+}
+
+#[tokio::test]
+async fn health_timeline_should_match_legacy_status_precedence_and_thresholds() {
+    let now = Utc::now();
+    let current_slot = quarter_hour_start(now);
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
+    let services = observability_services(store.clone()).await;
+    let fixtures = [
+        (
+            RequestMetrics {
+                failure_count: 1,
+                cancelled_count: 1,
+                incomplete_count: 1,
+                caller_error_count: 1,
+                ..RequestMetrics::default()
+            },
+            HealthStatus::NoData,
+            None,
+        ),
+        (
+            RequestMetrics {
+                failure_count: 3,
+                ..RequestMetrics::default()
+            },
+            HealthStatus::Unavailable,
+            Some(0.0),
+        ),
+        (
+            RequestMetrics {
+                success_count: 1,
+                failure_count: 1,
+                ..RequestMetrics::default()
+            },
+            HealthStatus::LowSample,
+            Some(50.0),
+        ),
+        (
+            RequestMetrics {
+                success_count: 98,
+                failure_count: 2,
+                ..RequestMetrics::default()
+            },
+            HealthStatus::Unstable,
+            Some(98.0),
+        ),
+        (
+            RequestMetrics {
+                success_count: 99,
+                failure_count: 1,
+                ..RequestMetrics::default()
+            },
+            HealthStatus::Stable,
+            Some(99.0),
+        ),
+    ];
+
+    for (index, (metrics, expected_status, expected_reliability)) in
+        fixtures.into_iter().enumerate()
+    {
+        store.replace_trend(vec![health_metric_point(current_slot, metrics)]);
+        let range_end =
+            now + Duration::seconds(i64::try_from(index).expect("fixture index fits i64") * 2);
+        let timeline = services
+            .observability()
+            .dashboard_summary(observation_range(range_end), TrendKind::Usage)
+            .await
+            .expect("dashboard summary")
+            .health_timeline;
+        let point = timeline
+            .points
+            .iter()
+            .find(|point| point.bucket_start == current_slot)
+            .expect("current health slot");
+        assert_eq!(point.status, expected_status);
+        assert_eq!(point.reliability_percent, expected_reliability);
+    }
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_project_rebuildable_runtime_slots() {
+    let now = Utc::now();
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
+    store.replace_runtime_slots(Some(DashboardRuntimeSlots {
+        inherited_accounts: 2,
+        overridden_slots: 5,
+        used_slots: Some(2),
+    }));
+    let services = observability_services(store).await;
+
+    let capacity = services
+        .observability()
+        .dashboard_summary(observation_range(now), TrendKind::Usage)
+        .await
+        .expect("dashboard summary")
+        .capacity;
+
+    assert_eq!(capacity.total_slots, 7);
+    assert_eq!(capacity.used_slots, Some(2));
+    assert_eq!(capacity.available_slots, Some(5));
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_share_one_current_observation_time_across_runtime_facts() {
+    let historical_end = Utc::now() - Duration::hours(1);
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(
+        historical_end,
+    )));
+    let services = observability_services(store.clone()).await;
+
+    services
+        .observability()
+        .dashboard_summary(observation_range(historical_end), TrendKind::Usage)
+        .await
+        .expect("dashboard summary");
+
+    let (summary_observed_at, slots_observed_at) = store.observed_times();
+    assert_eq!(summary_observed_at, slots_observed_at);
+    assert!(summary_observed_at.is_some_and(|value| value > historical_end));
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_coalesce_concurrent_requests_in_one_short_window() {
+    let end_bucket = Utc::now().timestamp().div_euclid(2) * 2;
+    let first_end = DateTime::from_timestamp(end_bucket, 100_000_000).expect("first end");
+    let second_end = DateTime::from_timestamp(end_bucket, 900_000_000).expect("second end");
+    let first_range = TimeRange::new(china_day_start(first_end), first_end).expect("first range");
+    let second_range =
+        TimeRange::new(china_day_start(second_end), second_end).expect("second range");
+    let store = Arc::new(FixtureObservabilityStore::new(first_range));
+    store.set_dashboard_delay(StdDuration::from_millis(20));
+    let services = observability_services(store.clone()).await;
+    let observability = services.observability();
+
+    let (first, second) = tokio::join!(
+        observability.dashboard_summary(first_range, TrendKind::Usage),
+        observability.dashboard_summary(second_range, TrendKind::Errors),
+    );
+
+    first.expect("first dashboard summary");
+    second.expect("second dashboard summary");
+    assert_eq!(store.dashboard_summary_calls(), 1);
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_reload_after_the_short_window_changes() {
+    let end_bucket = Utc::now().timestamp().div_euclid(2) * 2;
+    let first_end = DateTime::from_timestamp(end_bucket, 100_000_000).expect("first end");
+    let second_end = first_end + Duration::seconds(2);
+    let first_range = TimeRange::new(china_day_start(first_end), first_end).expect("first range");
+    let second_range =
+        TimeRange::new(china_day_start(second_end), second_end).expect("second range");
+    let store = Arc::new(FixtureObservabilityStore::new(first_range));
+    let services = observability_services(store.clone()).await;
+    let observability = services.observability();
+
+    observability
+        .dashboard_summary(first_range, TrendKind::Usage)
+        .await
+        .expect("first dashboard summary");
+    observability
+        .dashboard_summary(second_range, TrendKind::Usage)
+        .await
+        .expect("second dashboard summary");
+
+    assert_eq!(store.dashboard_summary_calls(), 2);
+}
+
+#[tokio::test]
+async fn observability_services_should_calculate_usage_insights_and_diagnostic_shares() {
+    let now = Utc::now();
+    let range = observation_range(now);
+    let store = Arc::new(FixtureObservabilityStore::new(range));
+    let metrics = RequestMetrics {
+        request_count: 10,
+        success_count: 6,
+        failure_count: 4,
+        caller_error_count: 2,
+        input_tokens: 800,
+        output_tokens: 200,
+        total_tokens: 1_000,
+        latency_count: 5,
+        admission_decision_count: 10,
+        admission_decision_percentiles: LatencyPercentiles {
+            p50_ms: Some(PercentileMilliseconds::new(2.0).expect("admission P50")),
+            p95_ms: Some(PercentileMilliseconds::new(5.0).expect("admission P95")),
+            p99_ms: Some(PercentileMilliseconds::new(8.0).expect("admission P99")),
+        },
+        account_selection_wait_count: 8,
+        account_selection_wait_percentiles: LatencyPercentiles {
+            p50_ms: Some(PercentileMilliseconds::new(10.0).expect("selection P50")),
+            p95_ms: Some(PercentileMilliseconds::new(40.0).expect("selection P95")),
+            p99_ms: Some(PercentileMilliseconds::new(70.0).expect("selection P99")),
+        },
+        output_throughput_p10: Some(40),
+        output_throughput_p50: Some(50),
+        output_throughput_p90: Some(60),
+        capacity_sample_count: 8,
+        capacity_utilization_avg_basis_points: Some(6_500),
+        capacity_utilization_p95_basis_points: Some(8_000),
+        ..RequestMetrics::default()
+    };
+    store.replace_overview(UsageOverview {
+        range,
+        requests: metrics.clone(),
+        attempts: AttemptMetrics {
+            attempt_count: 12,
+            cost_coverage: CostCoverage {
+                calculated_count: 10,
+                ..CostCoverage::default()
+            },
+            costs: vec![CurrencyCost {
+                currency: "USD".to_owned(),
+                amount: gateway_admin::model::observability::DecimalAmount::from_str("1.25")
+                    .expect("USD cost"),
+            }],
+            ..AttemptMetrics::default()
+        },
+        providers: Vec::new(),
+    });
+    store.replace_trend(vec![RequestMetricPoint {
+        bucket_start: quarter_hour_start(now),
+        granularity: Granularity::FifteenMinutes,
+        metrics,
+        cost_coverage: CostCoverage::default(),
+        costs: vec![CurrencyCost {
+            currency: "USD".to_owned(),
+            amount: gateway_admin::model::observability::DecimalAmount::from_str("0.25")
+                .expect("bucket USD cost"),
+        }],
+    }]);
+    store.replace_calculated_billing_facts(vec![UsageCalculatedBillingFact {
+        bucket_start: quarter_hour_start(now),
+        provider_kind: "openai".to_owned(),
+        upstream_model_id: "gpt-5.5".to_owned(),
+        service_tier: None,
+        input_tokens: Some(800),
+        output_tokens: Some(200),
+        cached_tokens: Some(0),
+        cache_write_tokens: Some(0),
+        total: CurrencyCost {
+            currency: "USD".to_owned(),
+            amount: gateway_admin::model::observability::DecimalAmount::from_str("1.25")
+                .expect("calculated total"),
+        },
+    }]);
+    store.replace_diagnostics(vec![diagnostic("openai", 3), diagnostic("xai", 1)]);
+    let services = observability_services_with_calculated_billing(store).await;
+
+    let insights = services
+        .observability()
+        .usage_insights(range, UsageFilter::default())
+        .await
+        .expect("usage insights");
+    let diagnostics = services
+        .observability()
+        .diagnostics(range, UsageFilter::default(), DiagnosticDimension::Provider)
+        .await
+        .expect("usage diagnostics");
+
+    assert_eq!(insights.health.total_requests, 10);
+    assert_eq!(insights.health.failed_requests, 2);
+    assert_eq!(insights.health.success_rate, 0.75);
+    assert_eq!(insights.health.completion_rate, 1.0);
+    assert_eq!(insights.granularity, Granularity::FifteenMinutes);
+    assert_eq!(insights.performance.latency_coverage, 0.5);
+    assert_eq!(insights.performance.admission_decision_coverage, 1.0);
+    assert_eq!(insights.performance.account_selection_wait_coverage, 0.8);
+    assert_eq!(insights.performance.capacity_coverage, 0.8);
+    assert_eq!(insights.performance.output_throughput_p50, Some(50));
+    assert_eq!(insights.cost.tokens_per_request, 100.0);
+    assert_eq!(
+        insights
+            .cost
+            .estimated_cost
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("1.25")
+    );
+    assert_eq!(
+        insights
+            .cost
+            .cost_per_request
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("0.125")
+    );
+    assert_eq!(
+        insights.cost.points[0]
+            .estimated_cost
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("0.25")
+    );
+    assert_eq!(
+        insights
+            .cost
+            .standard_cost
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("1")
+    );
+    assert_eq!(
+        insights.cost.points[0]
+            .standard_cost
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("1")
+    );
+    assert_eq!(
+        insights
+            .cost
+            .no_cache_cost
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("1.25")
+    );
+    assert_eq!(
+        insights
+            .cost
+            .tier_premium
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("0.25")
+    );
+    assert_eq!(diagnostics.items[0].request_share, 0.75);
+    assert_eq!(diagnostics.items[1].request_share, 0.25);
+    assert!((diagnostics.items[0].impact_score - 0.075).abs() < 1e-9);
+}
+
+#[tokio::test]
+async fn usage_records_should_tolerate_records_that_fail_billing_enrichment() {
+    let now = Utc::now();
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
+    let invalid_kind = "x".repeat(65);
+    store.replace_usage_records(vec![
+        total_record(
+            "request_invalid_kind",
+            Some(&invalid_kind),
+            "calculated",
+            now,
+        ),
+        total_record(
+            "request_unregistered_kind",
+            Some("anthropic"),
+            "calculated",
+            now,
+        ),
+        total_record("request_enriched", Some("openai"), "calculated", now),
+    ]);
+    let services = observability_services_with_calculated_billing(store).await;
+
+    let page = services
+        .observability()
+        .usage_records(usage_query(now))
+        .await
+        .expect("one bad record must not fail the whole usage list");
+
+    assert_eq!(page.items.len(), 3);
+    assert!(
+        matches!(page.items[0].billing, Some(UsageBilling::Total { .. })),
+        "invalid Provider kind keeps the stored total"
+    );
+    assert!(
+        matches!(page.items[1].billing, Some(UsageBilling::Total { .. })),
+        "unregistered Provider kind keeps the stored total"
+    );
+    assert!(
+        matches!(page.items[2].billing, Some(UsageBilling::Calculated(_))),
+        "healthy record is still enriched"
+    );
+}
+
+#[tokio::test]
+async fn usage_records_should_enrich_provider_reported_totals_when_pricing_matches() {
+    let now = Utc::now();
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
+    store.replace_usage_records(vec![total_record(
+        "request_provider_reported",
+        Some("openai"),
+        "provider_reported",
+        now,
+    )]);
+    let services = observability_services_with_calculated_billing(store).await;
+
+    let page = services
+        .observability()
+        .usage_records(usage_query(now))
+        .await
+        .expect("usage records");
+
+    assert!(matches!(
+        page.items[0].billing,
+        Some(UsageBilling::Calculated(_))
+    ));
+}
+
+#[tokio::test]
+async fn usage_insights_should_reject_partial_costs_when_billing_stream_fails() {
+    let now = Utc::now();
+    let range = observation_range(now);
+    let store = Arc::new(FixtureObservabilityStore::new(range));
+    store.replace_calculated_billing_facts(vec![UsageCalculatedBillingFact {
+        bucket_start: quarter_hour_start(now),
+        provider_kind: "openai".to_owned(),
+        upstream_model_id: "gpt-5.5".to_owned(),
+        service_tier: None,
+        input_tokens: Some(800),
+        output_tokens: Some(200),
+        cached_tokens: Some(0),
+        cache_write_tokens: Some(0),
+        total: CurrencyCost {
+            currency: "USD".to_owned(),
+            amount: "1.25".parse().expect("cost"),
+        },
+    }]);
+    store.billing_stream_fails.store(true, Ordering::SeqCst);
+    let services = observability_services_with_calculated_billing(store).await;
+    assert!(
+        services
+            .observability()
+            .usage_insights(range, UsageFilter::default())
+            .await
+            .is_err()
+    );
+}
+
+struct FixtureObservabilityStore {
+    trend: Mutex<Vec<RequestMetricPoint>>,
+    overview: Mutex<UsageOverview>,
+    calculated_billing_facts: Mutex<Vec<UsageCalculatedBillingFact>>,
+    billing_stream_fails: AtomicBool,
+    diagnostics: Mutex<Vec<DiagnosticObservation>>,
+    runtime_slots: Mutex<Option<DashboardRuntimeSlots>>,
+    summary_observed_at: Mutex<Option<DateTime<Utc>>>,
+    slots_observed_at: Mutex<Option<DateTime<Utc>>>,
+    usage_records: Mutex<Vec<UsageListRecord>>,
+    dashboard_delay: Mutex<StdDuration>,
+    dashboard_summary_calls: AtomicUsize,
+}
+
+impl FixtureObservabilityStore {
+    fn new(range: TimeRange) -> Self {
+        Self {
+            trend: Mutex::new(Vec::new()),
+            overview: Mutex::new(UsageOverview {
+                range,
+                requests: RequestMetrics::default(),
+                attempts: AttemptMetrics::default(),
+                providers: Vec::new(),
+            }),
+            calculated_billing_facts: Mutex::new(Vec::new()),
+            billing_stream_fails: AtomicBool::new(false),
+            diagnostics: Mutex::new(Vec::new()),
+            runtime_slots: Mutex::new(None),
+            summary_observed_at: Mutex::new(None),
+            slots_observed_at: Mutex::new(None),
+            usage_records: Mutex::new(Vec::new()),
+            dashboard_delay: Mutex::new(StdDuration::ZERO),
+            dashboard_summary_calls: AtomicUsize::new(0),
+        }
+    }
+
+    fn set_dashboard_delay(&self, delay: StdDuration) {
+        *self.dashboard_delay.lock().expect("dashboard delay") = delay;
+    }
+
+    fn dashboard_summary_calls(&self) -> usize {
+        self.dashboard_summary_calls.load(Ordering::Relaxed)
+    }
+
+    fn replace_trend(&self, trend: Vec<RequestMetricPoint>) {
+        *self.trend.lock().expect("trend") = trend;
+    }
+
+    fn replace_overview(&self, overview: UsageOverview) {
+        *self.overview.lock().expect("overview") = overview;
+    }
+
+    fn replace_calculated_billing_facts(&self, facts: Vec<UsageCalculatedBillingFact>) {
+        *self
+            .calculated_billing_facts
+            .lock()
+            .expect("calculated billing facts") = facts;
+    }
+
+    fn replace_diagnostics(&self, diagnostics: Vec<DiagnosticObservation>) {
+        *self.diagnostics.lock().expect("diagnostics") = diagnostics;
+    }
+
+    fn replace_runtime_slots(&self, runtime_slots: Option<DashboardRuntimeSlots>) {
+        *self.runtime_slots.lock().expect("runtime slots") = runtime_slots;
+    }
+
+    fn observed_times(&self) -> (Option<DateTime<Utc>>, Option<DateTime<Utc>>) {
+        (
+            *self
+                .summary_observed_at
+                .lock()
+                .expect("summary observed at"),
+            *self.slots_observed_at.lock().expect("slots observed at"),
+        )
+    }
+
+    fn replace_usage_records(&self, records: Vec<UsageListRecord>) {
+        *self.usage_records.lock().expect("usage records") = records;
+    }
+}
+
+#[async_trait]
+impl ObservabilityStore for FixtureObservabilityStore {
+    async fn dashboard_summary(
+        &self,
+        range: TimeRange,
+        observed_at: DateTime<Utc>,
+    ) -> AdminStoreResult<DashboardObservation> {
+        self.dashboard_summary_calls.fetch_add(1, Ordering::Relaxed);
+        *self
+            .summary_observed_at
+            .lock()
+            .expect("summary observed at") = Some(observed_at);
+        let dashboard_delay = *self.dashboard_delay.lock().expect("dashboard delay");
+        if !dashboard_delay.is_zero() {
+            tokio::time::sleep(dashboard_delay).await;
+        }
+        Ok(DashboardObservation {
+            range,
+            totals: Default::default(),
+            provider_accounts: AccountPoolMetrics::default(),
+            trend: self.trend.lock().expect("trend").clone(),
+            account_usage: Vec::new(),
+            recent_requests: Vec::new(),
+        })
+    }
+
+    async fn dashboard_runtime_slots(
+        &self,
+        observed_at: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<DashboardRuntimeSlots>> {
+        *self.slots_observed_at.lock().expect("slots observed at") = Some(observed_at);
+        Ok(*self.runtime_slots.lock().expect("runtime slots"))
+    }
+
+    async fn dashboard_trend(&self, _: TimeRange) -> AdminStoreResult<Vec<RequestMetricPoint>> {
+        Ok(self.trend.lock().expect("trend").clone())
+    }
+
+    async fn usage_trend(
+        &self,
+        _: TimeRange,
+        _: UsageFilter,
+    ) -> AdminStoreResult<Vec<RequestMetricPoint>> {
+        Ok(self.trend.lock().expect("trend").clone())
+    }
+
+    fn usage_calculated_billing_facts(
+        &self,
+        _: TimeRange,
+        _: UsageFilter,
+    ) -> gateway_admin::ports::store::UsageCalculatedBillingStream<'_> {
+        let facts = self
+            .calculated_billing_facts
+            .lock()
+            .expect("calculated billing facts")
+            .clone();
+        let error = self
+            .billing_stream_fails
+            .load(Ordering::SeqCst)
+            .then(|| Err(super::unavailable("billing stream failed")));
+        Box::pin(futures::stream::iter(
+            facts.into_iter().map(Ok).chain(error),
+        ))
+    }
+
+    async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage> {
+        let items = self.usage_records.lock().expect("usage records").clone();
+        let total = u64::try_from(items.len()).unwrap_or(u64::MAX);
+        Ok(UsagePage {
+            items,
+            current_page: query.current_page,
+            page_size: query.page_size.get(),
+            total,
+        })
+    }
+
+    async fn usage_record_detail(&self, _: &str) -> AdminStoreResult<UsageDetail> {
+        Err(super::unavailable("usage detail"))
+    }
+
+    async fn usage_summary(&self, _: TimeRange, _: UsageFilter) -> AdminStoreResult<UsageOverview> {
+        Ok(self.overview.lock().expect("overview").clone())
+    }
+
+    async fn usage_diagnostics(
+        &self,
+        _: TimeRange,
+        _: UsageFilter,
+        _: DiagnosticDimension,
+    ) -> AdminStoreResult<Vec<DiagnosticObservation>> {
+        Ok(self.diagnostics.lock().expect("diagnostics").clone())
+    }
+
+    async fn list_ops_errors(&self, _: OpsErrorQuery) -> AdminStoreResult<OpsErrorPage> {
+        Err(super::unavailable("ops errors"))
+    }
+}
+
+struct FixtureSettingsStore;
+
+#[async_trait]
+impl SettingsStore for FixtureSettingsStore {
+    async fn load_runtime_settings(&self) -> AdminStoreResult<RuntimeSettings> {
+        Ok(RuntimeSettings {
+            config_revision: Revision::new(1).expect("revision"),
+            model_mappings: Default::default(),
+            refresh_margin_seconds: 300,
+            refresh_concurrency: 2,
+            max_concurrent_per_account: 1,
+            request_interval_ms: 0,
+            rotation_strategy: RotationStrategy::Smart,
+            min_codex_desktop_version: None,
+            min_codex_cli_version: None,
+            usage_retention_days: 31,
+            ops_event_retention_days: 30,
+            audit_retention_days: 30,
+            updated_at: Utc::now(),
+        })
+    }
+
+    async fn admin_api_key_exists(&self) -> AdminStoreResult<bool> {
+        Err(super::unavailable("admin API key"))
+    }
+
+    async fn replace_runtime_settings(
+        &self,
+        _: ReplaceRuntimeSettings,
+        _: &MutationContext,
+    ) -> AdminStoreResult<RuntimeSettings> {
+        Err(super::unavailable("settings"))
+    }
+
+    async fn replace_admin_api_key(
+        &self,
+        _: AdminApiKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation> {
+        Err(super::unavailable("admin API key"))
+    }
+
+    async fn delete_admin_api_key(
+        &self,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation> {
+        Err(super::unavailable("admin API key"))
+    }
+}
+
+async fn observability_services(store: Arc<FixtureObservabilityStore>) -> AdminServices {
+    super::AdminHarness::new()
+        .observability(store)
+        .settings(Arc::new(FixtureSettingsStore))
+        .provider(super::dashboard_profile_provider())
+        .build()
+        .await
+}
+
+async fn observability_services_with_calculated_billing(
+    store: Arc<FixtureObservabilityStore>,
+) -> AdminServices {
+    super::AdminHarness::new()
+        .observability(store)
+        .settings(Arc::new(FixtureSettingsStore))
+        .provider(super::calculated_billing_provider())
+        .build()
+        .await
+}
+
+fn observation_range(end: DateTime<Utc>) -> TimeRange {
+    TimeRange::new(end - Duration::hours(24), end).expect("observation range")
+}
+
+fn usage_query(now: DateTime<Utc>) -> UsageQuery {
+    UsageQuery {
+        range: observation_range(now),
+        filter: UsageFilter::default(),
+        current_page: 1,
+        page_size: PageSize::new(50).expect("page size"),
+    }
+}
+
+fn total_record(
+    id: &str,
+    provider_kind: Option<&str>,
+    source: &str,
+    now: DateTime<Utc>,
+) -> UsageListRecord {
+    UsageListRecord {
+        id: id.to_owned(),
+        endpoint: "/v1/responses".to_owned(),
+        client_transport: "http_sse".to_owned(),
+        requested_model_id: Some("gpt-5.5".to_owned()),
+        provider_kind: provider_kind.map(str::to_owned),
+        provider_account_ref: None,
+        provider_account_name: None,
+        provider_account_email: None,
+        provider_account_authentication_kind: None,
+        upstream_model_id: Some("gpt-5.5".to_owned()),
+        upstream_transport: None,
+        service_tier: None,
+        input_tokens: Some(800),
+        output_tokens: Some(200),
+        cached_tokens: Some(0),
+        cache_write_tokens: Some(0),
+        reasoning_tokens: Some(0),
+        image_input_tokens: None,
+        image_output_tokens: None,
+        total_tokens: Some(1_000),
+        cost_source: source.to_owned(),
+        cost_amount: None,
+        cost_currency: None,
+        billing: Some(UsageBilling::Total {
+            source: source.to_owned(),
+            total: CurrencyCost {
+                currency: "USD".to_owned(),
+                amount: gateway_admin::model::observability::DecimalAmount::from_str("1.25")
+                    .expect("billing total"),
+            },
+        }),
+        transport_decision_wait_ms: None,
+        connect_ms: None,
+        headers_ms: None,
+        first_event_ms: None,
+        first_reasoning_ms: None,
+        first_text_ms: None,
+        first_token_ms: None,
+        provider_processing_ms: None,
+        latency_ms: Some(100),
+        admission_decision_ms: None,
+        account_selection_wait_ms: None,
+        capacity_used_slots: None,
+        capacity_total_slots: None,
+        client_ip: None,
+        user_agent: None,
+        reasoning_effort: None,
+        reasoning_preset: None,
+        subagent_kind: None,
+        compact: false,
+        started_at: now,
+    }
+}
+
+fn health_metric_point(bucket_start: DateTime<Utc>, metrics: RequestMetrics) -> RequestMetricPoint {
+    RequestMetricPoint {
+        bucket_start,
+        granularity: Granularity::FifteenMinutes,
+        metrics,
+        cost_coverage: CostCoverage::default(),
+        costs: Vec::new(),
+    }
+}
+
+fn diagnostic(name: &str, request_count: u64) -> DiagnosticObservation {
+    DiagnosticObservation {
+        first_token_p95_ms: None,
+        non_completion_count: 0,
+        retry_count: 0,
+        key: name.to_owned(),
+        name: name.to_owned(),
+        request_count,
+        success_count: request_count,
+        failure_count: 0,
+        attempt_count: request_count,
+        total_tokens: request_count.saturating_mul(100),
+        average_latency_ms: Some(100),
+        latency_p95_ms: Some(200),
+        cost_coverage: CostCoverage::default(),
+        costs: Vec::new(),
+    }
+}
+
+fn quarter_hour_start(value: DateTime<Utc>) -> DateTime<Utc> {
+    let elapsed = value.timestamp().rem_euclid(15 * 60);
+    value - Duration::seconds(elapsed) - Duration::nanoseconds(i64::from(value.nanosecond()))
+}

backend/crates/gateway-admin/tests/use_case/openai.rs

@@ -0,0 +1,389 @@
+use std::sync::Arc;
+
+use gateway_core::account::ProviderAccountId;
+
+use gateway_admin::{
+    AdminServices,
+    model::provider_credentials::{
+        AuthorizationMutationTarget, CompleteAuthorization, CredentialDeletion, ImportCredentials,
+        ProviderQuotaRequest, StartAuthorization,
+    },
+    ports::provider::ProviderAdminErrorKind,
+};
+
+use super::accounts::{
+    FakeAccountStore, FakeProviderAdmin, context, document, events, recorded, revision,
+};
+
+#[tokio::test]
+async fn openai_delete_should_commit_then_release_provider_resources() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = service(provider, store.clone()).await;
+
+    services
+        .openai()
+        .delete(deletion("acct_test"))
+        .await
+        .expect("delete credential");
+
+    assert_eq!(
+        recorded(&events),
+        [
+            "store.credential_details",
+            "store.delete",
+            "provider.account_unavailable",
+            "provider.account_facts_changed",
+        ]
+    );
+    assert_eq!(store.audit_requests(), ["request-openai"]);
+}
+
+#[tokio::test]
+async fn openai_import_should_prepare_before_atomic_store_commit() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = service(provider.clone(), store.clone()).await;
+
+    services
+        .openai()
+        .import_document(ImportCredentials {
+            context: context("import-openai"),
+            document: document(),
+        })
+        .await
+        .expect("import credential");
+
+    await_quota_requests(&provider, 1).await;
+
+    assert_eq!(
+        recorded(&events),
+        [
+            "provider.prepare_import",
+            "store.commit_import",
+            "provider.account_facts_changed",
+            "provider.quota",
+        ]
+    );
+    assert_eq!(
+        provider.quota_requests(),
+        [ProviderQuotaRequest {
+            account_id: ProviderAccountId::new("acct_prepared").expect("account ID"),
+            refresh: true,
+            rolling_usage: None,
+        }]
+    );
+    assert_eq!(store.audit_requests(), ["import-openai"]);
+}
+
+#[tokio::test]
+async fn openai_import_should_refresh_quota_for_every_imported_account() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    provider.set_import_account_ids(&["acct_first", "acct_second"]);
+    let store = FakeAccountStore::new("openai", events);
+    let services = service(provider.clone(), store).await;
+
+    let result = services
+        .openai()
+        .import_document(ImportCredentials {
+            context: context("import-openai-batch"),
+            document: document(),
+        })
+        .await
+        .expect("import credentials");
+
+    await_quota_requests(&provider, 2).await;
+
+    assert_eq!(
+        result.credential_ids,
+        [
+            ProviderAccountId::new("acct_first").expect("first account ID"),
+            ProviderAccountId::new("acct_second").expect("second account ID"),
+        ]
+    );
+    assert_eq!(
+        provider.quota_requests(),
+        [
+            ProviderQuotaRequest {
+                account_id: ProviderAccountId::new("acct_first").expect("first account ID"),
+                refresh: true,
+                rolling_usage: None,
+            },
+            ProviderQuotaRequest {
+                account_id: ProviderAccountId::new("acct_second").expect("second account ID"),
+                refresh: true,
+                rolling_usage: None,
+            },
+        ]
+    );
+}
+
+#[tokio::test]
+async fn openai_import_should_remain_successful_when_quota_refresh_fails() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    provider.fail_next_quota(ProviderAdminErrorKind::Unavailable);
+    let store = FakeAccountStore::new("openai", events);
+    let services = service(provider.clone(), store).await;
+
+    let result = services
+        .openai()
+        .import_document(ImportCredentials {
+            context: context("import-openai-quota-failure"),
+            document: document(),
+        })
+        .await
+        .expect("committed import remains successful");
+
+    await_quota_requests(&provider, 1).await;
+
+    assert_eq!(
+        result.credential_ids,
+        [ProviderAccountId::new("acct_prepared").expect("account ID")]
+    );
+    assert_eq!(provider.quota_requests().len(), 1);
+}
+
+#[tokio::test]
+async fn openai_authorization_create_should_observe_initial_quota() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = service(provider.clone(), store.clone()).await;
+
+    services
+        .openai()
+        .start_authorization(StartAuthorization {
+            context: context("oauth-start-openai-create"),
+            name: "new OpenAI credential".to_owned(),
+            reauthorization: None,
+        })
+        .await
+        .expect("start authorization");
+    services
+        .openai()
+        .complete_authorization(CompleteAuthorization {
+            context: context("oauth-start-openai-create"),
+            flow_id: "flow-test".to_owned(),
+            callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+        })
+        .await
+        .expect("complete authorization");
+
+    await_quota_requests(&provider, 1).await;
+
+    assert_eq!(
+        recorded(&events),
+        [
+            "provider.start_authorization",
+            "provider.complete_authorization",
+            "store.commit_authorization",
+            "provider.account_facts_changed",
+            "provider.quota",
+        ]
+    );
+    assert_eq!(
+        provider.quota_requests(),
+        [ProviderQuotaRequest {
+            account_id: ProviderAccountId::new("acct_prepared").expect("account ID"),
+            refresh: true,
+            rolling_usage: None,
+        }]
+    );
+    assert_eq!(store.audit_requests(), ["oauth-start-openai-create"]);
+}
+
+#[tokio::test]
+async fn openai_authorization_create_should_remain_successful_when_initial_quota_fails() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    provider.fail_next_quota(ProviderAdminErrorKind::Unavailable);
+    let store = FakeAccountStore::new("openai", events);
+    let services = service(provider.clone(), store).await;
+
+    services
+        .openai()
+        .start_authorization(StartAuthorization {
+            context: context("oauth-start-openai-quota-failure"),
+            name: "new OpenAI credential".to_owned(),
+            reauthorization: None,
+        })
+        .await
+        .expect("start authorization");
+    let result = services
+        .openai()
+        .complete_authorization(CompleteAuthorization {
+            context: context("oauth-start-openai-quota-failure"),
+            flow_id: "flow-test".to_owned(),
+            callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+        })
+        .await
+        .expect("quota observation must not fail authorization");
+
+    await_quota_requests(&provider, 1).await;
+
+    assert_eq!(result.account_id.as_str(), "acct_prepared");
+    assert_eq!(provider.quota_requests().len(), 1);
+}
+
+#[tokio::test]
+async fn openai_authorization_store_failure_should_release_claim_for_retry() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    provider.retry_authorization_after_abort();
+    let store = FakeAccountStore::new("openai", events.clone());
+    store.fail_next_commit();
+    let services = service(provider.clone(), store).await;
+    let command = || CompleteAuthorization {
+        context: context("oauth-store-retry"),
+        flow_id: "flow-test".to_owned(),
+        callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+    };
+
+    services
+        .openai()
+        .start_authorization(StartAuthorization {
+            context: context("oauth-store-retry"),
+            name: "new OpenAI credential".to_owned(),
+            reauthorization: None,
+        })
+        .await
+        .expect("start authorization");
+    services
+        .openai()
+        .complete_authorization(command())
+        .await
+        .expect_err("Store commit must fail");
+    services
+        .openai()
+        .complete_authorization(command())
+        .await
+        .expect("released claim must permit retry");
+
+    await_quota_requests(&provider, 1).await;
+
+    assert_eq!(
+        recorded(&events),
+        [
+            "provider.start_authorization",
+            "provider.complete_authorization",
+            "store.commit_authorization",
+            "authorization_guard.abort",
+            "provider.complete_authorization",
+            "store.commit_authorization",
+            "authorization_guard.commit",
+            "provider.account_facts_changed",
+            "provider.quota",
+        ]
+    );
+    assert!(provider.pending().is_none());
+}
+
+#[tokio::test]
+async fn openai_import_provider_error_should_not_touch_store_transaction() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    provider.fail_next(ProviderAdminErrorKind::Invalid);
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = service(provider, store).await;
+
+    services
+        .openai()
+        .import_document(ImportCredentials {
+            context: context("import-openai-error"),
+            document: document(),
+        })
+        .await
+        .expect_err("invalid Provider document");
+
+    assert_eq!(recorded(&events), ["provider.prepare_import"]);
+}
+
+#[tokio::test]
+async fn openai_reauthorization_should_commit_after_credential_revision_advances() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = service(provider.clone(), store.clone()).await;
+    services
+        .openai()
+        .start_authorization(StartAuthorization {
+            context: context("oauth-start-openai"),
+            name: "reauthorize".to_owned(),
+            reauthorization: Some(ProviderAccountId::new("acct_test").expect("account ID")),
+        })
+        .await
+        .expect("start reauthorization");
+
+    let pending = provider.pending().expect("pending envelope");
+    assert_eq!(pending.provider_kind().as_str(), "openai");
+    assert_eq!(
+        pending.owner_binding().started_request_id(),
+        "oauth-start-openai"
+    );
+    assert!(matches!(
+        pending.target(),
+        AuthorizationMutationTarget::Reauthorize { account_id }
+            if account_id.as_str() == "acct_test"
+    ));
+    assert!(!format!("{pending:?}").contains("admin-test"));
+
+    provider.set_current_credential_revision(revision(2));
+
+    let result = services
+        .openai()
+        .complete_authorization(CompleteAuthorization {
+            context: context("oauth-complete-openai"),
+            flow_id: "flow-test".to_owned(),
+            callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+        })
+        .await
+        .expect("complete reauthorization");
+
+    await_quota_requests(&provider, 1).await;
+
+    assert_eq!(result.credential_revision, Some(revision(3)));
+
+    assert_eq!(
+        recorded(&events),
+        [
+            "store.credential_details",
+            "provider.start_authorization",
+            "provider.complete_authorization",
+            "store.commit_authorization",
+            "guard.finish",
+            "provider.account_facts_changed",
+            "provider.quota",
+        ]
+    );
+    assert_eq!(provider.quota_requests().len(), 1);
+    assert_eq!(store.audit_requests(), ["oauth-complete-openai"]);
+}
+
+async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>) -> AdminServices {
+    super::AdminHarness::new()
+        .provider(provider)
+        .accounts(store)
+        .build()
+        .await
+}
+
+async fn await_quota_requests(provider: &FakeProviderAdmin, expected: usize) {
+    for _ in 0..100 {
+        if provider.quota_requests().len() == expected {
+            return;
+        }
+        tokio::task::yield_now().await;
+    }
+    assert_eq!(provider.quota_requests().len(), expected);
+}
+
+fn deletion(account_id: &str) -> CredentialDeletion {
+    CredentialDeletion {
+        context: context("request-openai"),
+        account_ids: vec![ProviderAccountId::new(account_id).expect("account ID")],
+    }
+}

backend/crates/gateway-admin/tests/use_case/settings.rs

@@ -0,0 +1,89 @@
+use async_trait::async_trait;
+
+use gateway_admin::{
+    model::{
+        AdminErrorKind, MutationContext,
+        settings::{
+            AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RotationStrategy,
+            RuntimeSettings,
+        },
+    },
+    ports::store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult, SettingsStore},
+};
+
+struct UnusedSettingsStore;
+
+#[async_trait]
+impl SettingsStore for UnusedSettingsStore {
+    async fn load_runtime_settings(&self) -> AdminStoreResult<RuntimeSettings> {
+        Err(unused())
+    }
+
+    async fn admin_api_key_exists(&self) -> AdminStoreResult<bool> {
+        Err(unused())
+    }
+
+    async fn replace_runtime_settings(
+        &self,
+        _: ReplaceRuntimeSettings,
+        _: &MutationContext,
+    ) -> AdminStoreResult<RuntimeSettings> {
+        Err(unused())
+    }
+
+    async fn replace_admin_api_key(
+        &self,
+        _: AdminApiKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation> {
+        Err(unused())
+    }
+
+    async fn delete_admin_api_key(
+        &self,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation> {
+        Err(unused())
+    }
+}
+
+#[tokio::test]
+async fn settings_should_reject_zero_refresh_margin_before_store_call() {
+    let services = super::AdminHarness::new()
+        .settings(std::sync::Arc::new(UnusedSettingsStore))
+        .build()
+        .await;
+    let error = services
+        .settings()
+        .replace(
+            &MutationContext {
+                actor: gateway_admin::model::MutationActor::System,
+                request_id: "request-settings".to_owned(),
+            },
+            ReplaceRuntimeSettings {
+                model_mappings: Default::default(),
+                refresh_margin_seconds: 0,
+                refresh_concurrency: 1,
+                max_concurrent_per_account: 1,
+                request_interval_ms: 0,
+                rotation_strategy: RotationStrategy::Smart,
+                min_codex_desktop_version: None,
+                min_codex_cli_version: None,
+                usage_retention_days: 31,
+                ops_event_retention_days: 30,
+                audit_retention_days: 30,
+            },
+        )
+        .await
+        .expect_err("invalid settings");
+
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+}
+
+fn unused() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "settings",
+        "unused in this test",
+    )
+}

backend/crates/gateway-admin/tests/use_case/system.rs

@@ -0,0 +1,115 @@
+use std::sync::Mutex;
+
+use async_trait::async_trait;
+
+use gateway_admin::{
+    model::system::{
+        SystemOperationAccepted, SystemOperationState, SystemOperationStatus, SystemUpdateDetail,
+        SystemUpdateStatus, SystemVersion,
+    },
+    ports::system::{SystemOperationError, SystemOperations, SystemUpdateEventStream},
+};
+
+#[derive(Default)]
+struct RecordingSystemOperations {
+    target: Mutex<Option<Option<String>>>,
+}
+
+#[async_trait]
+impl SystemOperations for RecordingSystemOperations {
+    async fn version(&self) -> Result<SystemVersion, SystemOperationError> {
+        Ok(SystemVersion {
+            version: "1.0.0".to_owned(),
+            git_sha: "unknown".to_owned(),
+            build_time: "unknown".to_owned(),
+            deployment_mode: "source".to_owned(),
+            update_channel: "stable".to_owned(),
+            latest_version: "1.0.0".to_owned(),
+            has_update: false,
+            update_cached: false,
+            update_warning: None,
+        })
+    }
+
+    async fn update_detail(&self, _: bool) -> Result<SystemUpdateDetail, SystemOperationError> {
+        Ok(SystemUpdateDetail {
+            current_version: "1.0.0".to_owned(),
+            latest_version: "1.0.0".to_owned(),
+            has_update: false,
+            deployment_mode: "source".to_owned(),
+            build_type: "source".to_owned(),
+            release_url: None,
+            notes: None,
+            cached: false,
+            update_supported: false,
+            unsupported_reason: Some("source build".to_owned()),
+            warning: None,
+        })
+    }
+
+    fn update_events(&self) -> SystemUpdateEventStream {
+        Box::pin(futures::stream::empty())
+    }
+
+    async fn perform_update(
+        &self,
+        target_version: Option<String>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
+        *self.target.lock().expect("target") = Some(target_version.clone());
+        Ok(SystemOperationAccepted::Update {
+            operation_id: "operation-update".to_owned(),
+            deployment_mode: "source".to_owned(),
+            message: "accepted".to_owned(),
+            need_restart: true,
+            target_version: target_version.unwrap_or_else(|| "latest".to_owned()),
+        })
+    }
+
+    async fn update_status(&self) -> Result<SystemUpdateStatus, SystemOperationError> {
+        Ok(SystemUpdateStatus {
+            previous_version: None,
+            current_version: Some("1.0.0".to_owned()),
+            operation: SystemOperationState {
+                operation_id: None,
+                kind: None,
+                status: SystemOperationStatus::Idle,
+                target_version: None,
+                message: None,
+                error: None,
+                started_at: None,
+                finished_at: None,
+            },
+        })
+    }
+
+    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+        Ok(SystemOperationAccepted::Rollback {
+            operation_id: "operation-rollback".to_owned(),
+            message: "accepted".to_owned(),
+            need_restart: true,
+        })
+    }
+
+    async fn restart(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+        Ok(SystemOperationAccepted::Restart {
+            operation_id: "operation-restart".to_owned(),
+            message: "accepted".to_owned(),
+        })
+    }
+}
+
+#[tokio::test]
+async fn system_update_should_normalize_blank_target_to_latest() {
+    let operations = std::sync::Arc::new(RecordingSystemOperations::default());
+    let services = super::AdminHarness::new()
+        .system(operations.clone())
+        .build()
+        .await;
+    services
+        .system()
+        .perform_update(Some("   ".to_owned()))
+        .await
+        .expect("perform update");
+
+    assert_eq!(*operations.target.lock().expect("target"), Some(None));
+}

backend/crates/gateway-admin/tests/use_case/xai.rs

@@ -0,0 +1,109 @@
+use std::sync::Arc;
+
+use gateway_core::account::ProviderAccountId;
+
+use gateway_admin::{
+    AdminServices,
+    model::provider_credentials::{ImportCredentials, ProviderQuotaRequest},
+    ports::provider::ProviderAdminErrorKind,
+};
+
+use super::accounts::{FakeAccountStore, FakeProviderAdmin, context, document, events, recorded};
+
+#[tokio::test]
+async fn xai_import_should_prepare_before_atomic_store_commit() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("xai", events.clone());
+    let store = FakeAccountStore::new("xai", events.clone());
+    let services = service(provider.clone(), store.clone()).await;
+
+    services
+        .xai()
+        .import_document(ImportCredentials {
+            context: context("import-xai"),
+            document: document(),
+        })
+        .await
+        .expect("import xAI credential");
+
+    assert_eq!(
+        recorded(&events),
+        [
+            "provider.prepare_import",
+            "store.commit_import",
+            "provider.quota"
+        ]
+    );
+    assert_eq!(
+        provider.quota_requests(),
+        [ProviderQuotaRequest {
+            account_id: ProviderAccountId::new("acct_prepared").expect("account ID"),
+            refresh: true,
+            rolling_usage: None,
+        }]
+    );
+    assert_eq!(store.audit_requests(), ["import-xai"]);
+}
+
+#[tokio::test]
+async fn xai_import_should_refresh_quota_for_every_imported_account() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("xai", events.clone());
+    provider.set_import_account_ids(&["acct_first", "acct_second"]);
+    let store = FakeAccountStore::new("xai", events);
+    let services = service(provider.clone(), store).await;
+
+    services
+        .xai()
+        .import_document(ImportCredentials {
+            context: context("import-xai-batch"),
+            document: document(),
+        })
+        .await
+        .expect("import credentials");
+
+    assert_eq!(
+        provider.quota_requests(),
+        [
+            ProviderQuotaRequest {
+                account_id: ProviderAccountId::new("acct_first").expect("first account ID"),
+                refresh: true,
+                rolling_usage: None,
+            },
+            ProviderQuotaRequest {
+                account_id: ProviderAccountId::new("acct_second").expect("second account ID"),
+                refresh: true,
+                rolling_usage: None,
+            },
+        ]
+    );
+}
+
+#[tokio::test]
+async fn xai_import_should_remain_successful_when_quota_refresh_fails() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("xai", events.clone());
+    provider.fail_next_quota(ProviderAdminErrorKind::Unavailable);
+    let store = FakeAccountStore::new("xai", events);
+    let services = service(provider.clone(), store).await;
+
+    let result = services
+        .xai()
+        .import_document(ImportCredentials {
+            context: context("import-xai-quota-failure"),
+            document: document(),
+        })
+        .await
+        .expect("committed import remains successful");
+
+    assert_eq!(result.credential_ids.len(), 1);
+    assert_eq!(provider.quota_requests().len(), 1);
+}
+
+async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>) -> AdminServices {
+    super::AdminHarness::new()
+        .provider(provider)
+        .accounts(store)
+        .build()
+        .await
+}

backend/crates/gateway-api/Cargo.toml

@@ -0,0 +1,41 @@
+[package]
+name = "gateway-api"
+version = "0.1.0"
+edition = "2024"
+license = "MIT"
+publish = false
+rust-version = "1.97"
+autotests = false
+
+[[test]]
+name = "main"
+path = "tests/main.rs"
+
+[dependencies]
+axum = { version = "0.8.9", default-features = false, features = ["json", "query", "ws"] }
+base64 = "0.23.0"
+bytes = "1.11.1"
+chrono = { version = "0.4.45", features = ["serde"] }
+futures = "0.3.32"
+gateway-admin = { path = "../gateway-admin" }
+gateway-core = { path = "../gateway-core" }
+gateway-protocol = { path = "../gateway-protocol" }
+secrecy = "0.10"
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
+thiserror = "2.0.18"
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "sync", "time"] }
+tower-http = { version = "0.7.0", features = ["cors", "fs", "request-id", "timeout", "trace"] }
+tracing = "0.1.44"
+url = "2.5.8"
+uuid = { version = "1.23.3", features = ["v7"] }
+
+[dev-dependencies]
+async-trait = "0.1.89"
+axum = { version = "0.8.9", default-features = false, features = ["http1", "tokio"] }
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "net", "rt-multi-thread", "test-util"] }
+tokio-tungstenite = "0.29.0"
+tower = { version = "0.5.3", features = ["util"] }
+
+[lints]
+workspace = true

backend/crates/gateway-api/src/admin/account_groups.rs

@@ -0,0 +1,416 @@
+//! Account group HTTP wire and fixed routes.
+
+use std::collections::BTreeMap;
+
+use axum::{
+    Router,
+    extract::State,
+    http::StatusCode,
+    response::IntoResponse,
+    routing::{get, post},
+};
+use chrono::{DateTime, Utc};
+use gateway_admin::model::{
+    PageSize,
+    account_groups::{
+        AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupColor, AccountGroupListQuery,
+        AccountGroupMutation, AccountGroupPage, AccountGroupRecord, AccountGroupUsage,
+        CreateAccountGroup, DeleteAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+    },
+};
+use gateway_core::routing::AccountGroupId;
+use serde::{Deserialize, Serialize};
+
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    PageMeta, WireValidationError, wire::map_admin_service_error,
+};
+
+const DEFAULT_PAGE_SIZE: u32 = 50;
+const MAX_PAGE_SIZE: u32 = 200;
+
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct ListAccountGroupsQuery {
+    page: Option<u32>,
+    page_size: Option<u32>,
+    search: Option<String>,
+    enabled: Option<bool>,
+}
+
+impl ListAccountGroupsQuery {
+    fn into_command(self) -> Result<AccountGroupListQuery, WireValidationError> {
+        let page = self.page.unwrap_or(1);
+        let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
+        if page == 0 || page_size == 0 || page_size > MAX_PAGE_SIZE {
+            return Err(WireValidationError::new("page"));
+        }
+        let search = self
+            .search
+            .map(|value| value.trim().to_owned())
+            .filter(|value| !value.is_empty());
+        if search
+            .as_deref()
+            .is_some_and(|value| value.len() > 256 || value.chars().any(char::is_control))
+        {
+            return Err(WireValidationError::new("search"));
+        }
+        Ok(AccountGroupListQuery {
+            page,
+            page_size: PageSize::new(
+                u16::try_from(page_size).map_err(|_| WireValidationError::new("pageSize"))?,
+            )
+            .map_err(|_| WireValidationError::new("pageSize"))?,
+            search,
+            enabled: self.enabled,
+        })
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct CreateAccountGroupRequest {
+    name: String,
+    description: Option<String>,
+    color: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct UpdateAccountGroupRequest {
+    id: String,
+    name: String,
+    description: Option<String>,
+    color: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct AccountGroupIdRequest {
+    id: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AccountGroupView {
+    id: String,
+    name: String,
+    description: Option<String>,
+    color: String,
+    enabled: bool,
+    member_count: u64,
+    provider_counts: BTreeMap<String, u64>,
+    client_key_count: u64,
+    account_summary: AccountGroupAccountSummaryView,
+    capacity: AccountGroupCapacityView,
+    usage: AccountGroupUsageView,
+    created_at: DateTime<Utc>,
+    updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AccountGroupAccountSummaryView {
+    available: u64,
+    limited: u64,
+    total: u64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AccountGroupCapacityView {
+    used_slots: Option<u64>,
+    total_slots: u64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AccountGroupUsageView {
+    today_usd: String,
+    retained_total_usd: String,
+}
+
+impl From<AccountGroupRecord> for AccountGroupView {
+    fn from(record: AccountGroupRecord) -> Self {
+        Self {
+            id: record.id.to_string(),
+            name: record.name,
+            description: record.description,
+            color: record.color.as_str().to_owned(),
+            enabled: record.enabled,
+            member_count: record.member_count,
+            provider_counts: record.provider_counts,
+            client_key_count: record.client_key_count,
+            account_summary: account_summary_view(record.account_summary),
+            capacity: capacity_view(record.capacity),
+            usage: usage_view(record.usage),
+            created_at: record.created_at,
+            updated_at: record.updated_at,
+        }
+    }
+}
+
+fn account_summary_view(summary: AccountGroupAccountSummary) -> AccountGroupAccountSummaryView {
+    AccountGroupAccountSummaryView {
+        available: summary.available,
+        limited: summary.limited,
+        total: summary.total,
+    }
+}
+
+fn capacity_view(capacity: AccountGroupCapacity) -> AccountGroupCapacityView {
+    AccountGroupCapacityView {
+        used_slots: capacity.used_slots,
+        total_slots: capacity.total_slots,
+    }
+}
+
+fn usage_view(usage: AccountGroupUsage) -> AccountGroupUsageView {
+    AccountGroupUsageView {
+        today_usd: usage.today_usd.to_string(),
+        retained_total_usd: usage.retained_total_usd.to_string(),
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AccountGroupPageData {
+    items: Vec<AccountGroupView>,
+    page: PageMeta,
+    config_revision: u64,
+}
+
+impl From<AccountGroupPage> for AccountGroupPageData {
+    fn from(page: AccountGroupPage) -> Self {
+        let total_pages = if page.total == 0 {
+            0
+        } else {
+            page.total.div_ceil(u64::from(page.page_size))
+        };
+        Self {
+            items: page.items.into_iter().map(Into::into).collect(),
+            page: PageMeta::new(
+                page.page,
+                u32::from(page.page_size),
+                page.total,
+                u32::try_from(total_pages).unwrap_or(u32::MAX),
+            ),
+            config_revision: page.config_revision.get(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AccountGroupMutationData {
+    id: String,
+    record: Option<AccountGroupView>,
+    config_revision: u64,
+}
+
+impl From<AccountGroupMutation> for AccountGroupMutationData {
+    fn from(mutation: AccountGroupMutation) -> Self {
+        Self {
+            id: mutation.id.to_string(),
+            record: mutation.record.map(Into::into),
+            config_revision: mutation.config_revision.get(),
+        }
+    }
+}
+
+/// Construct all fixed account-group management routes.
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/account-groups", get(list::<S>))
+        .route("/api/admin/account-groups/create", post(create::<S>))
+        .route("/api/admin/account-groups/update", post(update::<S>))
+        .route("/api/admin/account-groups/enable", post(enable::<S>))
+        .route("/api/admin/account-groups/disable", post(disable::<S>))
+        .route("/api/admin/account-groups/delete", post(delete::<S>))
+}
+
+async fn list<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ListAccountGroupsQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .account_groups()
+        .list(query.into_command().map_err(map_wire_error)?)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountGroupPageData::from(result)),
+    ))
+}
+
+async fn create<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<CreateAccountGroupRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    validate_group_fields(&request.name, request.description.as_deref())?;
+    mutation_response(
+        StatusCode::CREATED,
+        state
+            .admin_services()
+            .account_groups()
+            .create(
+                &auth.context().mutation_context(),
+                CreateAccountGroup {
+                    name: request.name,
+                    description: request.description,
+                    color: group_color(&request.color)?,
+                },
+            )
+            .await,
+    )
+}
+
+async fn update<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateAccountGroupRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    validate_group_fields(&request.name, request.description.as_deref())?;
+    mutation_response(
+        StatusCode::OK,
+        state
+            .admin_services()
+            .account_groups()
+            .update(
+                &auth.context().mutation_context(),
+                UpdateAccountGroup {
+                    id: group_id(request.id)?,
+                    name: request.name,
+                    description: request.description,
+                    color: group_color(&request.color)?,
+                },
+            )
+            .await,
+    )
+}
+
+async fn enable<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    set_enabled(auth, state, request, true).await
+}
+
+async fn disable<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    set_enabled(auth, state, request, false).await
+}
+
+async fn set_enabled<S>(
+    auth: AdminAuth,
+    state: S,
+    request: AccountGroupIdRequest,
+    enabled: bool,
+) -> Result<AdminResponse<AdminEnvelope<AccountGroupMutationData>>, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    mutation_response(
+        StatusCode::OK,
+        state
+            .admin_services()
+            .account_groups()
+            .set_enabled(
+                &auth.context().mutation_context(),
+                SetAccountGroupEnabled {
+                    id: group_id(request.id)?,
+                    enabled,
+                },
+            )
+            .await,
+    )
+}
+
+async fn delete<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    mutation_response(
+        StatusCode::OK,
+        state
+            .admin_services()
+            .account_groups()
+            .delete(
+                &auth.context().mutation_context(),
+                DeleteAccountGroup {
+                    id: group_id(request.id)?,
+                },
+            )
+            .await,
+    )
+}
+
+fn mutation_response(
+    status: StatusCode,
+    result: Result<AccountGroupMutation, gateway_admin::model::AdminError>,
+) -> Result<AdminResponse<AdminEnvelope<AccountGroupMutationData>>, AdminError> {
+    let result = result.map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        status,
+        AdminEnvelope::ok(AccountGroupMutationData::from(result)),
+    ))
+}
+
+fn group_id(value: String) -> Result<AccountGroupId, AdminError> {
+    AccountGroupId::new(value).map_err(|_| AdminError::bad_request("账号组 ID 不合法"))
+}
+
+fn group_color(value: &str) -> Result<AccountGroupColor, AdminError> {
+    AccountGroupColor::parse(value).ok_or_else(|| AdminError::bad_request("账号组颜色不合法"))
+}
+
+fn validate_group_fields(name: &str, description: Option<&str>) -> Result<(), AdminError> {
+    if name.trim() != name
+        || name.is_empty()
+        || name.chars().count() > 100
+        || name.chars().any(char::is_control)
+        || description
+            .is_some_and(|value| value.len() > 4096 || value.chars().any(char::is_control))
+    {
+        return Err(AdminError::bad_request("账号组请求不合法"));
+    }
+    Ok(())
+}
+
+fn map_wire_error(_: WireValidationError) -> AdminError {
+    AdminError::bad_request("账号组查询参数不合法")
+}
+
+fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
+    map_admin_service_error(error)
+}

backend/crates/gateway-api/src/admin/accounts/credentials.rs

@@ -0,0 +1,488 @@
+//! Provider-owned 凭据请求、命令转换与敏感材料校验。
+
+use super::*;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum AccountProvider {
+    OpenAi,
+    Xai,
+}
+
+impl AccountProvider {
+    fn parse(value: &str) -> Result<Self, WireValidationError> {
+        match value.trim() {
+            "openai" => Ok(Self::OpenAi),
+            "xai" => Ok(Self::Xai),
+            _ => Err(WireValidationError::new("provider")),
+        }
+    }
+}
+
+/// Provider-owned 账号导入请求；公共 API 不解释 `data` 内部字段。
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountImportRequest {
+    pub provider: String,
+    pub data: Value,
+}
+
+impl AccountImportRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        AccountProvider::parse(&self.provider)?;
+        if !self.data.is_object()
+            || serde_json::to_vec(&self.data)
+                .map_or(true, |encoded| encoded.len() > MAX_IMPORT_DATA_BYTES)
+        {
+            return Err(WireValidationError::new("data"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, ImportCredentials), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            ImportCredentials {
+                context,
+                document: provider_document(self.data, "data")?,
+            },
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct StartAccountAuthorizationRequest {
+    pub provider: String,
+    pub name: String,
+    pub account_id: Option<String>,
+}
+
+impl StartAccountAuthorizationRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        AccountProvider::parse(&self.provider)?;
+        require_text(&self.name, MAX_NAME_BYTES, "name")?;
+        if let Some(account_id) = self.account_id.as_deref() {
+            require_account_id(account_id, "accountId")?;
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, StartAuthorization), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        let reauthorization = self
+            .account_id
+            .map(ProviderAccountId::new)
+            .transpose()
+            .map_err(|_| WireValidationError::new("accountId"))?;
+        Ok((
+            provider,
+            StartAuthorization {
+                context,
+                name: self.name,
+                reauthorization,
+            },
+        ))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct CompleteAccountAuthorizationRequest {
+    pub provider: String,
+    pub flow_id: String,
+    pub callback_url: String,
+}
+
+impl CompleteAccountAuthorizationRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        let provider = AccountProvider::parse(&self.provider)?;
+        match provider {
+            AccountProvider::OpenAi => {
+                if !URL_SAFE_NO_PAD
+                    .decode(&self.flow_id)
+                    .is_ok_and(|decoded| decoded.len() == 32)
+                {
+                    return Err(WireValidationError::new("flowId"));
+                }
+            }
+            AccountProvider::Xai => require_wire_id(&self.flow_id, "flowId")?,
+        }
+        require_text(&self.callback_url, MAX_CALLBACK_URL_BYTES, "callbackUrl")
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, CompleteAuthorization), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            CompleteAuthorization {
+                context,
+                flow_id: self.flow_id,
+                callback_url: self.callback_url,
+            },
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateAccountRequest {
+    pub account_id: String,
+    pub enabled: bool,
+    #[serde(deserialize_with = "deserialize_required_nullable")]
+    pub concurrency_limit: Option<u64>,
+    pub weight: u64,
+    pub group_ids: Vec<String>,
+}
+
+impl UpdateAccountRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        parse_concurrency_limit(self.concurrency_limit)?;
+        parse_account_weight(self.weight)?;
+        validate_wire_group_ids(&self.group_ids)?;
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<UpdateAccount, WireValidationError> {
+        self.validate()?;
+        Ok(UpdateAccount {
+            account_id: self.account_id,
+            enabled: self.enabled,
+            concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,
+            weight: parse_account_weight(self.weight)?,
+            group_ids: validate_wire_group_ids(&self.group_ids)?,
+        })
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UpdatedAccountData {
+    pub account_id: String,
+    pub config_revision: u64,
+}
+
+impl From<AccountUpdateResult> for UpdatedAccountData {
+    fn from(result: AccountUpdateResult) -> Self {
+        Self {
+            account_id: result.account_id.to_string(),
+            config_revision: result.config_revision.get(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountDeletionRequest {
+    pub provider: String,
+    pub account_ids: Vec<String>,
+}
+
+impl AccountDeletionRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        AccountProvider::parse(&self.provider)?;
+        if self.account_ids.is_empty() || self.account_ids.len() > MAX_ACCOUNT_DELETE_BATCH {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        let mut unique = BTreeSet::new();
+        for account_id in &self.account_ids {
+            require_account_id(account_id, "accountIds")?;
+            if !unique.insert(account_id.as_str()) {
+                return Err(WireValidationError::new("accountIds"));
+            }
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, CredentialDeletion), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            CredentialDeletion {
+                context,
+                account_ids: self
+                    .account_ids
+                    .into_iter()
+                    .map(ProviderAccountId::new)
+                    .collect::<Result<Vec<_>, _>>()
+                    .map_err(|_| WireValidationError::new("accountIds"))?,
+            },
+        ))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RotateAccountRequest {
+    pub provider: String,
+    pub account_id: String,
+    pub access_token: String,
+    pub refresh_token: Option<String>,
+    pub id_token: Option<String>,
+}
+
+impl RotateAccountRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        if AccountProvider::parse(&self.provider)? != AccountProvider::OpenAi {
+            return Err(WireValidationError::new("provider"));
+        }
+        require_account_id(&self.account_id, "accountId")?;
+        validate_oauth_material(
+            &self.access_token,
+            self.refresh_token.as_deref(),
+            self.id_token.as_deref(),
+        )
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<RotateCredential, WireValidationError> {
+        self.validate()?;
+        let mut material = Map::new();
+        material.insert("access_token".to_owned(), Value::String(self.access_token));
+        material.insert(
+            "refresh_token".to_owned(),
+            self.refresh_token.map_or(Value::Null, Value::String),
+        );
+        material.insert(
+            "id_token".to_owned(),
+            self.id_token.map_or(Value::Null, Value::String),
+        );
+        Ok(RotateCredential {
+            mutation: CredentialMutation {
+                context,
+                account_id: ProviderAccountId::new(self.account_id)
+                    .map_err(|_| WireValidationError::new("accountId"))?,
+            },
+            provider_material: ProviderDocument::new(OpaqueProviderData::new(material)),
+        })
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountImportData {
+    pub imported_count: usize,
+    pub account_ids: Vec<String>,
+}
+
+impl AccountImportData {
+    pub fn from_result(result: CredentialImportResult) -> Self {
+        let account_ids = result
+            .credential_ids
+            .into_iter()
+            .map(|account_id| account_id.to_string())
+            .collect::<Vec<_>>();
+        Self {
+            imported_count: account_ids.len(),
+            account_ids,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountAuthorizationData {
+    pub flow_id: String,
+    pub authorization_url: String,
+    pub expires_at: DateTime<Utc>,
+}
+
+impl From<AuthorizationStarted> for AccountAuthorizationData {
+    fn from(started: AuthorizationStarted) -> Self {
+        Self {
+            flow_id: started.flow_id,
+            authorization_url: started.authorization_url,
+            expires_at: started.expires_at,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountMutationData {
+    pub account_id: String,
+}
+
+impl From<CredentialMutationResult> for AccountMutationData {
+    fn from(result: CredentialMutationResult) -> Self {
+        Self {
+            account_id: result.account_id.to_string(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountDeletionData {
+    pub deleted_count: usize,
+    pub account_ids: Vec<String>,
+}
+
+impl From<CredentialDeletionResult> for AccountDeletionData {
+    fn from(result: CredentialDeletionResult) -> Self {
+        let account_ids = result
+            .account_ids
+            .into_iter()
+            .map(|account_id| account_id.to_string())
+            .collect::<Vec<_>>();
+        Self {
+            deleted_count: account_ids.len(),
+            account_ids,
+        }
+    }
+}
+
+pub(super) fn require_account_id(
+    value: &str,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.trim().is_empty()
+        || value.len() > 128
+        || value.chars().any(char::is_control)
+        || !value.starts_with("acct_")
+    {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+pub(super) fn parse_concurrency_limit(
+    value: Option<u64>,
+) -> Result<Option<AccountConcurrencyLimit>, WireValidationError> {
+    value
+        .map(|value| {
+            u32::try_from(value)
+                .ok()
+                .and_then(AccountConcurrencyLimit::new)
+                .ok_or_else(|| WireValidationError::new("concurrencyLimit"))
+        })
+        .transpose()
+}
+
+pub(super) fn deserialize_required_nullable<'de, D>(
+    deserializer: D,
+) -> Result<Option<u64>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    Option::<u64>::deserialize(deserializer)
+}
+
+pub(super) fn parse_account_weight(value: u64) -> Result<AccountWeight, WireValidationError> {
+    u16::try_from(value)
+        .ok()
+        .and_then(AccountWeight::new)
+        .ok_or_else(|| WireValidationError::new("weight"))
+}
+
+pub(super) fn validate_wire_group_ids(
+    values: &[String],
+) -> Result<Vec<AccountGroupId>, WireValidationError> {
+    if values.len() > MAX_ACCOUNT_GROUP_BATCH
+        || values.iter().collect::<BTreeSet<_>>().len() != values.len()
+    {
+        return Err(WireValidationError::new("groupIds"));
+    }
+    values
+        .iter()
+        .cloned()
+        .map(|value| AccountGroupId::new(value).map_err(|_| WireValidationError::new("groupIds")))
+        .collect()
+}
+
+fn provider_document(
+    value: Value,
+    field: &'static str,
+) -> Result<ProviderDocument, WireValidationError> {
+    match value {
+        Value::Object(document) => Ok(ProviderDocument::new(OpaqueProviderData::new(document))),
+        _ => Err(WireValidationError::new(field)),
+    }
+}
+
+fn require_wire_id(value: &str, field: &'static str) -> Result<(), WireValidationError> {
+    require_text(value, MAX_ID_BYTES, field)?;
+    if value.starts_with("__")
+        || !value
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.' | b':'))
+    {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn require_text(
+    value: &str,
+    max_bytes: usize,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.trim().is_empty() || value.len() > max_bytes || value.chars().any(char::is_control) {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn validate_oauth_material(
+    access_token: &str,
+    refresh_token: Option<&str>,
+    id_token: Option<&str>,
+) -> Result<(), WireValidationError> {
+    if access_token.len() > MAX_ACCESS_TOKEN_BYTES
+        || !valid_visible_ascii(access_token)
+        || !valid_compact_jwt_shape(access_token)
+    {
+        return Err(WireValidationError::new("accessToken"));
+    }
+    if refresh_token.is_some_and(|token| {
+        token.len() > MAX_REFRESH_TOKEN_BYTES
+            || !valid_visible_ascii(token)
+            || token == access_token
+    }) {
+        return Err(WireValidationError::new("refreshToken"));
+    }
+    if id_token.is_some_and(|token| {
+        token.len() > MAX_ID_TOKEN_BYTES
+            || !valid_visible_ascii(token)
+            || !valid_compact_jwt_shape(token)
+    }) {
+        return Err(WireValidationError::new("idToken"));
+    }
+    Ok(())
+}
+
+fn valid_compact_jwt_shape(value: &str) -> bool {
+    let mut segments = value.split('.');
+    matches!(
+        (segments.next(), segments.next(), segments.next(), segments.next()),
+        (Some(header), Some(payload), Some(signature), None)
+            if !header.is_empty() && !payload.is_empty() && !signature.is_empty()
+    )
+}
+
+fn valid_visible_ascii(value: &str) -> bool {
+    !value.is_empty() && value.bytes().all(|byte| (0x21..=0x7e).contains(&byte))
+}
+
+pub(super) fn provider_document_value(document: ProviderDocument) -> Value {
+    Value::Object(document.into_provider_data().into_inner())
+}

backend/crates/gateway-api/src/admin/accounts/handlers.rs

@@ -0,0 +1,573 @@
+//! 账号管理路由与 HTTP handler 编排。
+
+use super::*;
+
+/// 构造统一账号管理路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/accounts", get(list_accounts::<S>))
+        .route("/api/admin/accounts/detail", get(account_detail::<S>))
+        .route("/api/admin/accounts/export", get(export_accounts::<S>))
+        .route("/api/admin/accounts/import", post(import_accounts::<S>))
+        .route("/api/admin/accounts/refresh", post(refresh_account::<S>))
+        .route("/api/admin/accounts/recover", post(recover_account::<S>))
+        .route("/api/admin/accounts/rotate", post(rotate_account::<S>))
+        .route("/api/admin/accounts/update", post(update_account::<S>))
+        .route("/api/admin/accounts/delete", post(delete_accounts::<S>))
+        .route(
+            "/api/admin/accounts/batch-update",
+            post(batch_update_accounts::<S>),
+        )
+        .route("/api/admin/accounts/quota", get(account_quota::<S>))
+        .route(
+            "/api/admin/accounts/profile-statistics",
+            get(account_profile_statistics::<S>),
+        )
+        .route(
+            "/api/admin/accounts/profile-avatar",
+            get(account_profile_avatar::<S>),
+        )
+        .route(
+            "/api/admin/accounts/reset-credits",
+            get(account_reset_credits::<S>).post(consume_account_reset_credit::<S>),
+        )
+        .route(
+            "/api/admin/accounts/quota/refresh",
+            post(refresh_account_quota::<S>),
+        )
+        .route("/api/admin/accounts/models", get(account_models::<S>))
+        .route(
+            "/api/admin/accounts/models/refresh",
+            post(refresh_account_models::<S>),
+        )
+        .route(
+            "/api/admin/accounts/connection-test",
+            get(test_account_connection::<S>),
+        )
+        .route(
+            "/api/admin/accounts/oauth/start",
+            post(start_account_authorization::<S>),
+        )
+        .route(
+            "/api/admin/accounts/oauth/complete",
+            post(complete_account_authorization::<S>),
+        )
+}
+
+async fn batch_update_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<BatchUpdateAccountsRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .batch_update(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(BatchUpdatedAccountsData::from(result)),
+    ))
+}
+
+async fn list_accounts<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ListQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = query.validate().map_err(map_wire_error)?;
+    let page = command.page;
+    let page_size = command.page_size.get();
+    let result = state
+        .admin_services()
+        .accounts()
+        .list(command)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_page_data(result, page, page_size, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_detail<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn export_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountExportQuery>,
+) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let ids = query.into_ids().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .export(&auth.context().mutation_context(), ids)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountExportData::from_result(result);
+    let mut response = AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)).into_response();
+    response
+        .headers_mut()
+        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
+    Ok(response)
+}
+
+async fn import_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountImportRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .import_document(command)
+                .await
+        }
+        AccountProvider::Xai => state.admin_services().xai().import_document(command).await,
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountImportData::from_result(result)),
+    ))
+}
+
+async fn start_account_authorization<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<StartAccountAuthorizationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .start_authorization(command)
+                .await
+        }
+        AccountProvider::Xai => {
+            state
+                .admin_services()
+                .xai()
+                .start_authorization(command)
+                .await
+        }
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountAuthorizationData::from(result)),
+    ))
+}
+
+async fn complete_account_authorization<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<CompleteAccountAuthorizationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .complete_authorization(command)
+                .await
+        }
+        AccountProvider::Xai => {
+            state
+                .admin_services()
+                .xai()
+                .complete_authorization(command)
+                .await
+        }
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountMutationData::from(result)),
+    ))
+}
+
+async fn rotate_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<RotateAccountRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .openai()
+        .rotate(command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountMutationData::from(result)),
+    ))
+}
+
+async fn update_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateAccountRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .update(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(UpdatedAccountData::from(result)),
+    ))
+}
+
+async fn delete_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountDeletionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => state.admin_services().openai().delete(command).await,
+        AccountProvider::Xai => state.admin_services().xai().delete(command).await,
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountDeletionData::from(result)),
+    ))
+}
+
+async fn refresh_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountRefreshRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .refresh(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_refresh_data(result, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn recover_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .recover(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_refresh_data(result, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_quota<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_profile_statistics<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .profile_statistics(&account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountProfileStatisticsData::from(result)),
+    ))
+}
+
+async fn account_profile_avatar<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountProfileAvatarQuery>,
+) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let avatar = state
+        .admin_services()
+        .accounts()
+        .profile_avatar(&account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(profile_avatar_response(avatar))
+}
+
+/// 将 Provider 头像流投影为受保护的同源 HTTP 响应。
+#[must_use]
+pub fn profile_avatar_response(avatar: ProviderProfileAvatar) -> Response {
+    let ProviderProfileAvatar {
+        content_type,
+        content_length,
+        etag,
+        body,
+    } = avatar;
+    let mut response = Response::new(Body::from_stream(body));
+    *response.status_mut() = StatusCode::OK;
+    let headers = response.headers_mut();
+    headers.insert(
+        header::CONTENT_TYPE,
+        content_type
+            .and_then(|value| HeaderValue::from_str(&value).ok())
+            .unwrap_or_else(|| HeaderValue::from_static("application/octet-stream")),
+    );
+    if let Some(value) =
+        content_length.and_then(|length| HeaderValue::from_str(&length.to_string()).ok())
+    {
+        headers.insert(header::CONTENT_LENGTH, value);
+    }
+    if let Some(value) = etag.and_then(|value| HeaderValue::from_str(&value).ok()) {
+        headers.insert(header::ETAG, value);
+    }
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static("private, max-age=3600"),
+    );
+    headers.insert(
+        HeaderName::from_static("x-content-type-options"),
+        HeaderValue::from_static("nosniff"),
+    );
+    headers.insert(
+        HeaderName::from_static("cross-origin-resource-policy"),
+        HeaderValue::from_static("same-origin"),
+    );
+    headers.insert(
+        HeaderName::from_static("content-security-policy"),
+        HeaderValue::from_static("sandbox; default-src 'none'"),
+    );
+    response
+}
+
+async fn refresh_account_quota<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, true)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_reset_credits<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .reset_credits(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountResetCreditsData::from(result)),
+    ))
+}
+
+async fn consume_account_reset_credit<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountResetCreditConsumeRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .consume_reset_credit(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountResetCreditResultData::from(result)),
+    ))
+}
+
+async fn account_models<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .models(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_models_data(result);
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn refresh_account_models<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .models(&account_id, true)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_models_data(result);
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn test_account_connection<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountTestQuery>,
+) -> Result<Sse<impl Stream<Item = Result<Event, Infallible>>>, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (account_id, upstream_model) = query.into_command().map_err(map_wire_error)?;
+    let stream = state
+        .admin_services()
+        .accounts()
+        .test_connection(account_id, upstream_model)
+        .await
+        .map_err(map_service_error)?
+        .map(|event| {
+            let event = AccountConnectionTestEvent::from(event);
+            let data = serde_json::to_string(&event.data).unwrap_or_else(|_| "{}".to_owned());
+            Ok(Event::default().data(data))
+        });
+    Ok(Sse::new(stream).keep_alive(KeepAlive::default()))
+}

backend/crates/gateway-api/src/admin/accounts/mod.rs

@@ -0,0 +1,81 @@
+//! 管理端账号目录的 HTTP 合同、凭据动作、路由处理与安全响应投影。
+
+use std::{collections::BTreeSet, convert::Infallible, fmt};
+
+use axum::{
+    Router,
+    body::Body,
+    extract::State,
+    http::{HeaderName, HeaderValue, StatusCode, header},
+    response::{
+        IntoResponse, Response,
+        sse::{Event, KeepAlive, Sse},
+    },
+    routing::{get, post},
+};
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use chrono::{DateTime, FixedOffset, Utc};
+use futures::{Stream, StreamExt as _};
+use gateway_admin::model::{
+    AdminError as AdminServiceError, PageSize,
+    accounts::{
+        AccountConcurrencyLimit, AccountConnectionTestEvent as DomainConnectionTestEvent,
+        AccountCost, AccountGroupFilter, AccountListQuery, AccountModelUsage, AccountSort,
+        AccountSortField, AccountStatus as DomainAccountStatus, AccountUpdateResult, AccountUsage,
+        AccountWeight, AccountsUpdateResult, BatchUpdateAccounts, SortDirection, UpdateAccount,
+    },
+    provider_credentials::{
+        AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
+        AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
+        CredentialDeletion, CredentialDeletionResult, CredentialImportResult, CredentialMutation,
+        CredentialMutationResult, ImportCredentials, ProviderDocument, ProviderModels,
+        ProviderProfileActivityInsights, ProviderProfileAvatar, ProviderProfileDailyUsage,
+        ProviderProfileInvocation, ProviderProfileStatistics, ProviderProfileStatisticsSummary,
+        ProviderQuota, ProviderQuotaWindow, ProviderResetCredit, ProviderResetCreditResult,
+        ProviderResetCredits, RotateCredential, StartAuthorization,
+    },
+};
+use gateway_core::{
+    account::{OpaqueProviderData, ProviderAccountId},
+    routing::{AccountGroupId, ProviderKind, UpstreamModelId},
+};
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::{Map, Value};
+use uuid::{Uuid, Version};
+
+use super::presenter::{format_compact_number, format_decimal_currency, format_number};
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    PageMeta, WireValidationError,
+};
+
+const DEFAULT_PAGE_SIZE: u32 = 50;
+const MAX_PAGE_SIZE: u32 = 200;
+const MAX_SEARCH_BYTES: usize = 256;
+const MAX_ID_BYTES: usize = 256;
+const MAX_NAME_BYTES: usize = 512;
+const MAX_IMPORT_DATA_BYTES: usize = 64 * 1024 * 1024;
+const MAX_ACCESS_TOKEN_BYTES: usize = 16 * 1024;
+const MAX_REFRESH_TOKEN_BYTES: usize = 64 * 1024;
+const MAX_ID_TOKEN_BYTES: usize = 16 * 1024;
+const MAX_CALLBACK_URL_BYTES: usize = 64 * 1024;
+const MAX_ACCOUNT_DELETE_BATCH: usize = 200;
+const MAX_ACCOUNT_GROUP_BATCH: usize = 1000;
+const MAX_AVATAR_VERSION_BYTES: usize = 32;
+
+mod credentials;
+mod handlers;
+mod presenter;
+mod wire;
+
+pub use credentials::*;
+pub use handlers::{profile_avatar_response, router};
+pub(super) use presenter::quota_window_view;
+pub use wire::*;
+
+use credentials::{
+    AccountProvider, deserialize_required_nullable, parse_account_weight, parse_concurrency_limit,
+    provider_document_value, require_account_id, validate_wire_group_ids,
+};
+use presenter::*;
+use wire::BatchUpdatedAccountsData;

backend/crates/gateway-api/src/admin/accounts/presenter.rs

@@ -0,0 +1,417 @@
+//! Admin 领域结果到安全 HTTP wire 的展示投影。
+
+use super::*;
+
+pub(super) fn account_page_data(
+    result: AccountDirectoryPage,
+    page: u32,
+    page_size: u16,
+    now: DateTime<Utc>,
+) -> AccountPageData {
+    let total_pages = if result.total == 0 {
+        0
+    } else {
+        u32::try_from(result.total.div_ceil(u64::from(page_size))).unwrap_or(u32::MAX)
+    };
+    AccountPageData {
+        items: result
+            .items
+            .into_iter()
+            .map(|item| account_view(item, now))
+            .collect(),
+        page: PageMeta::new(page, u32::from(page_size), result.total, total_pages),
+        summary: AccountSummaryView {
+            total: result.summary.total,
+            normal: result.summary.normal,
+            quota_exhausted: result.summary.quota_exhausted,
+            rate_limited: result.summary.rate_limited,
+            disabled: result.summary.disabled,
+            error: result.summary.error,
+        },
+    }
+}
+
+pub(super) fn account_refresh_data(
+    result: AccountRefreshResult,
+    now: DateTime<Utc>,
+) -> AccountRefreshData {
+    AccountRefreshData {
+        account: account_view(result.account, now),
+    }
+}
+
+pub(super) fn account_models_data(result: ProviderModels) -> AccountModelsData {
+    AccountModelsData {
+        models: result
+            .models
+            .into_iter()
+            .map(|model| {
+                let id = model.id.to_string();
+                AccountModelView {
+                    label: id.clone(),
+                    id,
+                }
+            })
+            .collect(),
+    }
+}
+
+pub(super) fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> AccountView {
+    let AccountDirectoryItem {
+        account,
+        projection,
+        usage,
+        quota,
+    } = item;
+    let status = projection.status.as_str().to_owned();
+    let rate_limited_until = projection.rate_limited_until.map(DateTime::<Utc>::from);
+    let expires_at = account.access_token_expires_at.as_ref().map(china_rfc3339);
+    let added_at = china_rfc3339(&account.created_at);
+    let updated_at = china_rfc3339(&account.updated_at);
+    let (quota, refresh_token_expires_at) = account_quota_view(quota, rate_limited_until, now);
+    AccountView {
+        id: account.id.clone(),
+        name: account.name,
+        provider: account.provider_kind.to_string(),
+        groups: account
+            .groups
+            .into_iter()
+            .map(|group| AccountGroupRefView {
+                id: group.id.to_string(),
+                name: group.name,
+                color: group.color.as_str().to_owned(),
+                enabled: group.enabled,
+            })
+            .collect(),
+        resource_ref: account.id,
+        email: account.email,
+        account_id: account.upstream_account_id,
+        user_id: account.upstream_user_id,
+        label: None,
+        plan_type: account.plan_type,
+        authentication_kind: account.authentication_kind,
+        has_refresh_token: account.has_refresh_token,
+        status,
+        error_reason: projection
+            .error_reason
+            .map(|reason| reason.as_str().to_owned()),
+        error_message: projection.error_message,
+        enabled: account.enabled,
+        concurrency_limit: account.concurrency_limit.map(|limit| limit.get()),
+        weight: account.weight.get(),
+        access_token_expires_at: expires_at,
+        access_token_expires_at_display: account
+            .access_token_expires_at
+            .as_ref()
+            .map(china_datetime),
+        refresh_token_expires_at,
+        next_refresh_at: account.next_refresh_at.map(|value| china_rfc3339(&value)),
+        added_at,
+        added_at_display: china_datetime(&account.created_at),
+        updated_at,
+        updated_at_display: china_datetime(&account.updated_at),
+        quota,
+        usage: account_usage_view(usage, now),
+    }
+}
+
+pub(super) fn account_quota_view(
+    mut quota: ProviderQuota,
+    rate_limited_until: Option<DateTime<Utc>>,
+    now: DateTime<Utc>,
+) -> (AccountQuotaView, Option<String>) {
+    quota.apply_limit_reached_display();
+    let refresh_token_expires_at = quota
+        .refresh_token_expires_at
+        .map(|value| china_rfc3339(&value));
+    let refreshed_at_display = quota
+        .observed_at
+        .map_or_else(|| "—".to_owned(), |value| relative_time(value, now));
+    let windows = quota.windows.into_iter().map(quota_window_view).collect();
+    let rate_limited_until = rate_limited_until.map(|until| china_datetime(&until));
+    (
+        AccountQuotaView {
+            refreshed_at_display,
+            limit_reached: quota.limit_reached,
+            rate_limited_until,
+            windows,
+        },
+        refresh_token_expires_at,
+    )
+}
+
+pub(crate) fn quota_window_view(window: ProviderQuotaWindow) -> AccountQuotaWindowView {
+    let ProviderQuotaWindow {
+        key,
+        group,
+        label,
+        limit_id,
+        limit_name,
+        role,
+        local_usage_attribution: _,
+        window_seconds,
+        used_percent,
+        reset_at,
+        limit_reached,
+        local_usage,
+        provider_data: _,
+    } = window;
+    let label_display = limit_name
+        .as_ref()
+        .map_or_else(|| label.clone(), |name| format!("{name} · {label}"));
+    AccountQuotaWindowView {
+        label_display,
+        window_label_display: label,
+        key,
+        group,
+        limit_id,
+        limit_name,
+        role: role.map(|value| value.as_str().to_owned()),
+        window_seconds,
+        used_percent,
+        used_percent_display: used_percent
+            .map_or_else(|| "—".to_owned(), |value| format!("{value:.1}%")),
+        limit_reached,
+        local_usage: local_usage.as_ref().map(quota_local_usage),
+        reset_at_display: reset_at.map_or_else(|| "—".to_owned(), |value| china_datetime(&value)),
+    }
+}
+
+pub(super) fn quota_local_usage(usage: &AccountUsage) -> Value {
+    let total_tokens = usage.total_tokens.unwrap_or_default();
+    serde_json::json!({
+        "requestCount": usage.request_count,
+        "requestCountDisplay": format_number(usage.request_count),
+        "inputTokens": usage.input_tokens.unwrap_or_default(),
+        "inputTokensDisplay": display_optional_tokens(usage.input_tokens),
+        "outputTokens": usage.output_tokens.unwrap_or_default(),
+        "outputTokensDisplay": display_optional_tokens(usage.output_tokens),
+        "cachedTokens": usage.cached_tokens.unwrap_or_default(),
+        "cachedTokensDisplay": display_optional_tokens(usage.cached_tokens),
+        "imageInputTokens": usage.image_input_tokens.unwrap_or_default(),
+        "imageInputTokensDisplay": display_optional_tokens(usage.image_input_tokens),
+        "imageOutputTokens": usage.image_output_tokens.unwrap_or_default(),
+        "imageOutputTokensDisplay": display_optional_tokens(usage.image_output_tokens),
+        "imageRequestCount": usage.image_request_count,
+        "imageRequestFailedCount": usage.image_request_failed_count,
+        "totalTokens": total_tokens,
+        "totalTokensDisplay": format_compact_number(total_tokens),
+        "requestBuckets": usage.request_buckets.iter().map(|bucket| serde_json::json!({
+            "bucketStart": bucket.bucket_start,
+            "requestCount": bucket.request_count,
+        })).collect::<Vec<_>>(),
+    })
+}
+
+pub(super) fn account_usage_view(
+    usage: Option<AccountUsage>,
+    now: DateTime<Utc>,
+) -> AccountUsageView {
+    let Some(usage) = usage else {
+        return empty_account_usage();
+    };
+    let known_count = usage
+        .cost_coverage
+        .provider_reported_count
+        .saturating_add(usage.cost_coverage.calculated_count);
+    let cost_estimate_status = if known_count == 0 {
+        "unknown"
+    } else if usage.cost_coverage.unavailable_count > 0 {
+        "partial"
+    } else {
+        "known"
+    };
+    AccountUsageView {
+        request_count: Some(usage.request_count),
+        request_count_display: format_number(usage.request_count),
+        input_tokens: usage.input_tokens,
+        input_tokens_display: display_optional_tokens(usage.input_tokens),
+        output_tokens: usage.output_tokens,
+        output_tokens_display: display_optional_tokens(usage.output_tokens),
+        cached_tokens: usage.cached_tokens,
+        cached_tokens_display: display_optional_tokens(usage.cached_tokens),
+        reasoning_tokens: usage.reasoning_tokens,
+        reasoning_tokens_display: display_optional_tokens(usage.reasoning_tokens),
+        image_input_tokens: usage.image_input_tokens,
+        image_input_tokens_display: display_optional_tokens(usage.image_input_tokens),
+        image_output_tokens: usage.image_output_tokens,
+        image_output_tokens_display: display_optional_tokens(usage.image_output_tokens),
+        image_request_count: Some(usage.image_request_count),
+        image_request_count_display: format_number(usage.image_request_count),
+        image_request_failed_count: Some(usage.image_request_failed_count),
+        image_request_failed_count_display: format_number(usage.image_request_failed_count),
+        total_tokens: usage.total_tokens,
+        total_tokens_display: display_optional_tokens(usage.total_tokens),
+        created_tokens: usage.cache_write_tokens,
+        created_tokens_display: display_optional_tokens(usage.cache_write_tokens),
+        read_tokens: usage.cached_tokens,
+        read_tokens_display: display_optional_tokens(usage.cached_tokens),
+        last_used_at: usage.last_used_at.map(|value| china_rfc3339(&value)),
+        last_used_at_display: usage
+            .last_used_at
+            .map_or_else(|| "—".to_owned(), |value| relative_time(value, now)),
+        cost_estimate_status: cost_estimate_status.to_owned(),
+        known_cost_count: Some(known_count),
+        partial_cost_count: Some(u64::from(cost_estimate_status == "partial")),
+        unknown_cost_count: Some(usage.cost_coverage.unavailable_count),
+        costs: usage.costs.iter().map(account_currency_cost_view).collect(),
+        models: usage
+            .models
+            .into_iter()
+            .map(|model| account_model_usage_view(model, now))
+            .collect(),
+    }
+}
+
+pub(super) fn account_model_usage_view(
+    usage: AccountModelUsage,
+    now: DateTime<Utc>,
+) -> ModelUsageView {
+    let known_count = usage
+        .cost_coverage
+        .provider_reported_count
+        .saturating_add(usage.cost_coverage.calculated_count);
+    let cost_estimate_status = if known_count == 0 {
+        "unknown"
+    } else if usage.cost_coverage.unavailable_count > 0 {
+        "partial"
+    } else {
+        "known"
+    };
+    let usd = usage
+        .costs
+        .iter()
+        .find(|cost| cost.currency.eq_ignore_ascii_case("USD"));
+    ModelUsageView {
+        model: usage.model,
+        request_count: usage.request_count,
+        request_count_display: format_number(usage.request_count),
+        success_rate: (usage.request_count > 0)
+            .then(|| usage.success_count as f64 * 100.0 / usage.request_count as f64),
+        success_rate_display: if usage.request_count == 0 {
+            "—".to_owned()
+        } else {
+            format!(
+                "{:.1}%",
+                usage.success_count as f64 * 100.0 / usage.request_count as f64
+            )
+        },
+        input_tokens: usage.input_tokens,
+        input_tokens_display: display_optional_tokens(usage.input_tokens),
+        output_tokens: usage.output_tokens,
+        output_tokens_display: display_optional_tokens(usage.output_tokens),
+        cached_tokens: usage.cached_tokens,
+        cached_tokens_display: display_optional_tokens(usage.cached_tokens),
+        image_input_tokens: usage.image_input_tokens,
+        image_input_tokens_display: display_optional_tokens(usage.image_input_tokens),
+        image_output_tokens: usage.image_output_tokens,
+        image_output_tokens_display: display_optional_tokens(usage.image_output_tokens),
+        image_request_count: usage.image_request_count,
+        image_request_count_display: format_number(usage.image_request_count),
+        image_request_failed_count: usage.image_request_failed_count,
+        image_request_failed_count_display: format_number(usage.image_request_failed_count),
+        total_tokens: usage.total_tokens,
+        total_tokens_display: display_optional_tokens(usage.total_tokens),
+        billing_amount_usd: usd.map(|cost| cost.amount.as_str().to_owned()),
+        billing_amount_usd_display: usd.map_or_else(
+            || "—".to_owned(),
+            |cost| format_decimal_currency(cost.amount.as_str(), "USD"),
+        ),
+        cost_estimate_status: cost_estimate_status.to_owned(),
+        known_cost_count: known_count,
+        partial_cost_count: u64::from(cost_estimate_status == "partial"),
+        unknown_cost_count: usage.cost_coverage.unavailable_count,
+        costs: usage.costs.iter().map(account_currency_cost_view).collect(),
+        last_used_at: china_rfc3339(&usage.last_used_at),
+        last_used_at_display: relative_time(usage.last_used_at, now),
+    }
+}
+
+pub(super) fn account_currency_cost_view(cost: &AccountCost) -> CurrencyCostView {
+    CurrencyCostView {
+        currency: cost.currency.clone(),
+        estimated_amount: cost.amount.as_str().to_owned(),
+        estimated_amount_display: format_decimal_currency(cost.amount.as_str(), &cost.currency),
+    }
+}
+
+pub(super) fn display_optional_tokens(value: Option<u64>) -> String {
+    value.map_or_else(|| "—".to_owned(), format_compact_number)
+}
+
+pub(super) fn empty_account_usage() -> AccountUsageView {
+    AccountUsageView {
+        request_count: None,
+        request_count_display: "—".to_owned(),
+        input_tokens: None,
+        input_tokens_display: "—".to_owned(),
+        output_tokens: None,
+        output_tokens_display: "—".to_owned(),
+        cached_tokens: None,
+        cached_tokens_display: "—".to_owned(),
+        reasoning_tokens: None,
+        reasoning_tokens_display: "—".to_owned(),
+        image_input_tokens: None,
+        image_input_tokens_display: "—".to_owned(),
+        image_output_tokens: None,
+        image_output_tokens_display: "—".to_owned(),
+        image_request_count: None,
+        image_request_count_display: "—".to_owned(),
+        image_request_failed_count: None,
+        image_request_failed_count_display: "—".to_owned(),
+        total_tokens: None,
+        total_tokens_display: "—".to_owned(),
+        created_tokens: None,
+        created_tokens_display: "—".to_owned(),
+        read_tokens: None,
+        read_tokens_display: "—".to_owned(),
+        last_used_at: None,
+        last_used_at_display: "—".to_owned(),
+        cost_estimate_status: "unavailable".to_owned(),
+        known_cost_count: None,
+        partial_cost_count: None,
+        unknown_cost_count: None,
+        costs: Vec::new(),
+        models: Vec::new(),
+    }
+}
+
+pub(super) fn relative_time(value: DateTime<Utc>, now: DateTime<Utc>) -> String {
+    let elapsed = now.signed_duration_since(value);
+    if elapsed.num_seconds() < 0 {
+        return china_datetime(&value);
+    }
+    if elapsed.num_seconds() < 60 {
+        return "刚刚".to_owned();
+    }
+    if elapsed.num_minutes() < 60 {
+        return format!("{} 分钟前", elapsed.num_minutes());
+    }
+    if elapsed.num_hours() < 24 {
+        return format!("{} 小时前", elapsed.num_hours());
+    }
+    format!("{} 天前", elapsed.num_days())
+}
+
+pub(super) fn china_offset() -> FixedOffset {
+    FixedOffset::east_opt(8 * 60 * 60).expect("UTC+8 is a valid fixed offset")
+}
+
+pub(super) fn china_rfc3339(value: &DateTime<Utc>) -> String {
+    value.with_timezone(&china_offset()).to_rfc3339()
+}
+
+pub(super) fn china_datetime(value: &DateTime<Utc>) -> String {
+    value
+        .with_timezone(&china_offset())
+        .format("%Y-%m-%d %H:%M:%S")
+        .to_string()
+}
+
+pub(super) fn map_wire_error(error: WireValidationError) -> AdminError {
+    AdminError::bad_request(format!("{} 字段不合法", error.field()))
+}
+
+pub(super) fn map_service_error(error: AdminServiceError) -> AdminError {
+    super::super::wire::map_admin_service_error(error)
+}

backend/crates/gateway-api/src/admin/accounts/wire.rs

@@ -0,0 +1,840 @@
+//! 账号管理请求、响应与查询 wire contract。
+
+use super::*;
+
+/// 账号列表查询参数。
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ListQuery {
+    pub page: Option<u32>,
+    pub page_size: Option<u32>,
+    pub provider: Option<String>,
+    pub group_id: Option<String>,
+    pub search: Option<String>,
+    pub status: Option<String>,
+    pub sort_by: Option<String>,
+    pub sort_direction: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct BatchUpdateAccountsRequest {
+    pub account_ids: Vec<String>,
+    pub enabled: bool,
+    #[serde(deserialize_with = "deserialize_required_nullable")]
+    pub concurrency_limit: Option<u64>,
+    pub weight: u64,
+    pub group_ids: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct BatchUpdatedAccountsData {
+    account_ids: Vec<String>,
+    config_revision: u64,
+}
+
+impl From<AccountsUpdateResult> for BatchUpdatedAccountsData {
+    fn from(result: AccountsUpdateResult) -> Self {
+        Self {
+            account_ids: result
+                .account_ids
+                .into_iter()
+                .map(|id| id.to_string())
+                .collect(),
+            config_revision: result.config_revision.get(),
+        }
+    }
+}
+
+impl BatchUpdateAccountsRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        if self.account_ids.is_empty()
+            || self.account_ids.len() > MAX_ACCOUNT_GROUP_BATCH
+            || self
+                .account_ids
+                .iter()
+                .any(|id| require_account_id(id, "accountIds").is_err())
+            || self.account_ids.iter().collect::<BTreeSet<_>>().len() != self.account_ids.len()
+        {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        validate_wire_group_ids(&self.group_ids)?;
+        parse_concurrency_limit(self.concurrency_limit)?;
+        parse_account_weight(self.weight)?;
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<BatchUpdateAccounts, WireValidationError> {
+        self.validate()?;
+        Ok(BatchUpdateAccounts {
+            account_ids: self.account_ids,
+            enabled: self.enabled,
+            concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,
+            weight: parse_account_weight(self.weight)?,
+            group_ids: validate_wire_group_ids(&self.group_ids)?,
+        })
+    }
+}
+
+impl ListQuery {
+    /// 解析并校验全部 wire 字段，生成 Admin 查询命令。
+    pub fn validate(self) -> Result<AccountListQuery, WireValidationError> {
+        let page = self.page.unwrap_or(1);
+        if page == 0 {
+            return Err(WireValidationError::new("page"));
+        }
+        let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
+        if page_size == 0 || page_size > MAX_PAGE_SIZE {
+            return Err(WireValidationError::new("pageSize"));
+        }
+        let provider_kind = parse_provider(self.provider.as_deref().unwrap_or("all"))?;
+        let group_filter = match self.group_id.as_deref().map(str::trim) {
+            None | Some("") => None,
+            Some("ungrouped") => Some(AccountGroupFilter::Ungrouped),
+            Some(value) => Some(AccountGroupFilter::Group(
+                AccountGroupId::new(value.to_owned())
+                    .map_err(|_| WireValidationError::new("groupId"))?,
+            )),
+        };
+        let search = self
+            .search
+            .map(|value| value.trim().to_owned())
+            .filter(|value| !value.is_empty());
+        if search.as_deref().is_some_and(|value| {
+            value.len() > MAX_SEARCH_BYTES || value.chars().any(char::is_control)
+        }) {
+            return Err(WireValidationError::new("search"));
+        }
+        let status = match self.status.as_deref().map(str::trim) {
+            None | Some("") => None,
+            Some(value) => Some(
+                DomainAccountStatus::parse(&value.to_ascii_lowercase())
+                    .ok_or_else(|| WireValidationError::new("status"))?,
+            ),
+        };
+        let sort = match (self.sort_by.as_deref(), self.sort_direction.as_deref()) {
+            (None, None) => None,
+            (Some(field), Some(direction)) => Some(AccountSort {
+                field: parse_sort_field(field).ok_or_else(|| WireValidationError::new("sortBy"))?,
+                direction: parse_sort_direction(direction)
+                    .ok_or_else(|| WireValidationError::new("sortDirection"))?,
+            }),
+            _ => return Err(WireValidationError::new("sort")),
+        };
+        Ok(AccountListQuery {
+            page,
+            page_size: PageSize::new(
+                u16::try_from(page_size).map_err(|_| WireValidationError::new("pageSize"))?,
+            )
+            .map_err(|_| WireValidationError::new("pageSize"))?,
+            provider_kind,
+            group_filter,
+            search,
+            status,
+            sort,
+        })
+    }
+}
+
+fn parse_provider(value: &str) -> Result<Option<ProviderKind>, WireValidationError> {
+    let value = value.trim();
+    if value.is_empty() || value.eq_ignore_ascii_case("all") {
+        return Ok(None);
+    }
+    ProviderKind::new(value.to_owned())
+        .map(Some)
+        .map_err(|_| WireValidationError::new("provider"))
+}
+
+fn parse_sort_field(value: &str) -> Option<AccountSortField> {
+    match value.trim() {
+        "email" => Some(AccountSortField::Email),
+        "status" => Some(AccountSortField::Status),
+        "planType" => Some(AccountSortField::PlanType),
+        "usage" => Some(AccountSortField::Usage),
+        "lastUsedAt" => Some(AccountSortField::LastUsedAt),
+        "expiresAt" => Some(AccountSortField::ExpiresAt),
+        _ => None,
+    }
+}
+
+fn parse_sort_direction(value: &str) -> Option<SortDirection> {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "asc" => Some(SortDirection::Asc),
+        "desc" => Some(SortDirection::Desc),
+        _ => None,
+    }
+}
+
+/// 账号列表响应数据。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountPageData {
+    pub items: Vec<AccountView>,
+    pub page: PageMeta,
+    pub summary: AccountSummaryView,
+}
+
+/// 账号概览计数。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountSummaryView {
+    pub total: u64,
+    pub normal: u64,
+    pub quota_exhausted: u64,
+    pub rate_limited: u64,
+    pub disabled: u64,
+    pub error: u64,
+}
+
+/// 一条安全账号视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountView {
+    pub id: String,
+    pub name: String,
+    pub provider: String,
+    pub groups: Vec<AccountGroupRefView>,
+    pub resource_ref: String,
+    pub email: Option<String>,
+    pub account_id: Option<String>,
+    pub user_id: Option<String>,
+    pub label: Option<String>,
+    pub plan_type: Option<String>,
+    pub authentication_kind: String,
+    pub has_refresh_token: bool,
+    pub status: String,
+    /// `status == "error"` 时的具体原因；其余状态为 `null`。
+    pub error_reason: Option<String>,
+    /// 最近一次失败的上游错误描述；仅错误状态存在。
+    pub error_message: Option<String>,
+    pub enabled: bool,
+    pub concurrency_limit: Option<u32>,
+    pub weight: u16,
+    pub access_token_expires_at: Option<String>,
+    pub access_token_expires_at_display: Option<String>,
+    pub refresh_token_expires_at: Option<String>,
+    pub next_refresh_at: Option<String>,
+    pub added_at: String,
+    pub added_at_display: String,
+    pub updated_at: String,
+    pub updated_at_display: String,
+    pub quota: AccountQuotaView,
+    pub usage: AccountUsageView,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountGroupRefView {
+    pub id: String,
+    pub name: String,
+    pub color: String,
+    pub enabled: bool,
+}
+
+/// Provider quota 安全视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaView {
+    pub refreshed_at_display: String,
+    pub limit_reached: bool,
+    /// 429 临时限流（Redis 冷却）到期时间展示；非限流中为 `null`。
+    pub rate_limited_until: Option<String>,
+    pub windows: Vec<AccountQuotaWindowView>,
+}
+
+/// 一个 quota 时间窗口。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaWindowView {
+    pub key: String,
+    pub group: String,
+    pub limit_id: Option<String>,
+    pub limit_name: Option<String>,
+    pub role: Option<String>,
+    pub window_seconds: Option<u64>,
+    pub label_display: String,
+    pub window_label_display: String,
+    pub used_percent: Option<f64>,
+    pub used_percent_display: String,
+    pub limit_reached: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub local_usage: Option<serde_json::Value>,
+    pub reset_at_display: String,
+}
+
+/// 账号观测用量。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountUsageView {
+    pub request_count: Option<u64>,
+    pub request_count_display: String,
+    pub input_tokens: Option<u64>,
+    pub input_tokens_display: String,
+    pub output_tokens: Option<u64>,
+    pub output_tokens_display: String,
+    pub cached_tokens: Option<u64>,
+    pub cached_tokens_display: String,
+    pub reasoning_tokens: Option<u64>,
+    pub reasoning_tokens_display: String,
+    pub image_input_tokens: Option<u64>,
+    pub image_input_tokens_display: String,
+    pub image_output_tokens: Option<u64>,
+    pub image_output_tokens_display: String,
+    pub image_request_count: Option<u64>,
+    pub image_request_count_display: String,
+    pub image_request_failed_count: Option<u64>,
+    pub image_request_failed_count_display: String,
+    pub total_tokens: Option<u64>,
+    pub total_tokens_display: String,
+    pub created_tokens: Option<u64>,
+    pub created_tokens_display: String,
+    pub read_tokens: Option<u64>,
+    pub read_tokens_display: String,
+    pub last_used_at: Option<String>,
+    pub last_used_at_display: String,
+    pub cost_estimate_status: String,
+    pub known_cost_count: Option<u64>,
+    pub partial_cost_count: Option<u64>,
+    pub unknown_cost_count: Option<u64>,
+    pub costs: Vec<CurrencyCostView>,
+    pub models: Vec<ModelUsageView>,
+}
+
+/// 凭据在单个上游模型上的观测用量。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ModelUsageView {
+    pub model: String,
+    pub request_count: u64,
+    pub request_count_display: String,
+    pub success_rate: Option<f64>,
+    pub success_rate_display: String,
+    pub input_tokens: Option<u64>,
+    pub input_tokens_display: String,
+    pub output_tokens: Option<u64>,
+    pub output_tokens_display: String,
+    pub cached_tokens: Option<u64>,
+    pub cached_tokens_display: String,
+    pub image_input_tokens: Option<u64>,
+    pub image_input_tokens_display: String,
+    pub image_output_tokens: Option<u64>,
+    pub image_output_tokens_display: String,
+    pub image_request_count: u64,
+    pub image_request_count_display: String,
+    pub image_request_failed_count: u64,
+    pub image_request_failed_count_display: String,
+    pub total_tokens: Option<u64>,
+    pub total_tokens_display: String,
+    pub billing_amount_usd: Option<String>,
+    pub billing_amount_usd_display: String,
+    pub cost_estimate_status: String,
+    pub known_cost_count: u64,
+    pub partial_cost_count: u64,
+    pub unknown_cost_count: u64,
+    pub costs: Vec<CurrencyCostView>,
+    pub last_used_at: String,
+    pub last_used_at_display: String,
+}
+
+/// 单一货币的可查询成本。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CurrencyCostView {
+    pub currency: String,
+    pub estimated_amount: String,
+    pub estimated_amount_display: String,
+}
+
+/// 账号详情类 GET 的固定 ID query。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountIdQuery {
+    pub account_id: String,
+}
+
+impl AccountIdQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 头像 GET 的固定 query；`version` 只参与浏览器缓存键，不进入上游请求。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountProfileAvatarQuery {
+    pub account_id: String,
+    pub version: Option<String>,
+}
+
+impl AccountProfileAvatarQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.version.as_deref().is_some_and(|version| {
+            version.is_empty()
+                || version.len() > MAX_AVATAR_VERSION_BYTES
+                || !version.bytes().all(|byte| byte.is_ascii_alphanumeric())
+        }) {
+            return Err(WireValidationError::new("version"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 敏感导出的固定 query；IDs 使用逗号分隔，禁止隐式导出全部账号。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountExportQuery {
+    pub account_ids: String,
+    pub confirm: String,
+}
+
+impl AccountExportQuery {
+    pub fn into_ids(self) -> Result<Vec<ProviderAccountId>, WireValidationError> {
+        if self.confirm != "export_sensitive_accounts" {
+            return Err(WireValidationError::new("confirm"));
+        }
+        let ids = self
+            .account_ids
+            .split(',')
+            .map(str::trim)
+            .filter(|id| !id.is_empty())
+            .map(ToOwned::to_owned)
+            .collect::<Vec<_>>();
+        if ids.is_empty()
+            || ids.len() > 200
+            || ids
+                .iter()
+                .any(|id| require_account_id(id, "accountIds").is_err())
+        {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        let unique = ids.iter().collect::<BTreeSet<_>>();
+        if unique.len() != ids.len() {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        ids.into_iter()
+            .map(|id| {
+                ProviderAccountId::new(id).map_err(|_| WireValidationError::new("accountIds"))
+            })
+            .collect()
+    }
+}
+
+/// 账号运行期动作。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountActionRequest {
+    pub account_id: String,
+}
+
+impl AccountActionRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 主动额度重置卡消费请求。幂等键由 UI 生成并在不确定重试时复用，与官方一致。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountResetCreditConsumeRequest {
+    pub account_id: String,
+    #[serde(default)]
+    pub credit_id: Option<String>,
+    pub redeem_request_id: String,
+}
+
+impl AccountResetCreditConsumeRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.credit_id.as_deref().is_some_and(|value| {
+            let value = value.trim();
+            value.is_empty() || value.len() > 512 || value.chars().any(char::is_control)
+        }) {
+            return Err(WireValidationError::new("creditId"));
+        }
+        let value = self.redeem_request_id.trim();
+        let redeem_request_id =
+            Uuid::parse_str(value).map_err(|_| WireValidationError::new("redeemRequestId"))?;
+        if redeem_request_id.get_version() != Some(Version::Random)
+            || redeem_request_id.hyphenated().to_string() != value
+        {
+            return Err(WireValidationError::new("redeemRequestId"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<ConsumeProviderResetCredit, WireValidationError> {
+        self.validate()?;
+        Ok(ConsumeProviderResetCredit {
+            account_id: ProviderAccountId::new(self.account_id)
+                .map_err(|_| WireValidationError::new("accountId"))?,
+            credit_id: self.credit_id.map(|value| value.trim().to_owned()),
+            redeem_request_id: Uuid::parse_str(&self.redeem_request_id)
+                .map_err(|_| WireValidationError::new("redeemRequestId"))?,
+        })
+    }
+}
+
+/// 手工 OAuth 刷新会变更持久 credential。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountRefreshRequest {
+    pub account_id: String,
+}
+
+impl AccountRefreshRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_command(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 连接测试 query；测试仍经唯一 Core/Provider 模型请求路径执行。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountTestQuery {
+    pub account_id: String,
+    pub model_id: String,
+}
+
+impl AccountTestQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.model_id.trim().is_empty() || self.model_id.chars().any(char::is_control) {
+            return Err(WireValidationError::new("modelId"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+    ) -> Result<(ProviderAccountId, UpstreamModelId), WireValidationError> {
+        self.validate()?;
+        Ok((
+            ProviderAccountId::new(self.account_id)
+                .map_err(|_| WireValidationError::new("accountId"))?,
+            UpstreamModelId::new(self.model_id).map_err(|_| WireValidationError::new("modelId"))?,
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountModelView {
+    pub id: String,
+    pub label: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountModelsData {
+    pub models: Vec<AccountModelView>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountRefreshData {
+    pub account: AccountView,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountQuotaData {
+    pub account: AccountView,
+}
+
+/// Provider 官方个人资料统计响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileStatisticsData {
+    pub display_name: Option<String>,
+    pub username: Option<String>,
+    pub image_url: Option<String>,
+    pub has_stats_error: bool,
+    pub summary: AccountProfileStatisticsSummaryView,
+    pub daily_usage: Option<Vec<AccountProfileDailyUsageView>>,
+    pub activity_insights: AccountProfileActivityInsightsView,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileStatisticsSummaryView {
+    pub total_text_tokens: Option<u64>,
+    pub peak_tokens: Option<u64>,
+    pub longest_task_duration_ms: Option<u64>,
+    pub current_streak_days: Option<u64>,
+    pub longest_streak_days: Option<u64>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileDailyUsageView {
+    pub date: String,
+    pub tokens: u64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileActivityInsightsView {
+    pub fast_mode_percent: Option<f64>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_effort_percent: Option<f64>,
+    pub skills_explored: Option<u64>,
+    pub total_skills_used: Option<u64>,
+    pub total_threads: Option<u64>,
+    pub invocations: Option<Vec<AccountProfileInvocationView>>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileInvocationView {
+    #[serde(rename = "type")]
+    pub invocation_type: String,
+    pub plugin_id: Option<String>,
+    pub plugin_name: Option<String>,
+    pub skill_id: Option<String>,
+    pub skill_name: Option<String>,
+    pub usage_count: Option<u64>,
+}
+
+impl From<ProviderProfileStatistics> for AccountProfileStatisticsData {
+    fn from(statistics: ProviderProfileStatistics) -> Self {
+        Self {
+            display_name: statistics.display_name,
+            username: statistics.username,
+            image_url: statistics.image_url,
+            has_stats_error: statistics.has_stats_error,
+            summary: profile_statistics_summary_view(statistics.summary),
+            daily_usage: statistics
+                .daily_usage
+                .map(|daily| daily.into_iter().map(profile_daily_usage_view).collect()),
+            activity_insights: profile_activity_insights_view(statistics.activity_insights),
+        }
+    }
+}
+
+const fn profile_statistics_summary_view(
+    summary: ProviderProfileStatisticsSummary,
+) -> AccountProfileStatisticsSummaryView {
+    AccountProfileStatisticsSummaryView {
+        total_text_tokens: summary.total_text_tokens,
+        peak_tokens: summary.peak_tokens,
+        longest_task_duration_ms: summary.longest_task_duration_ms,
+        current_streak_days: summary.current_streak_days,
+        longest_streak_days: summary.longest_streak_days,
+    }
+}
+
+fn profile_daily_usage_view(daily: ProviderProfileDailyUsage) -> AccountProfileDailyUsageView {
+    AccountProfileDailyUsageView {
+        date: daily.date.to_string(),
+        tokens: daily.tokens,
+    }
+}
+
+fn profile_activity_insights_view(
+    insights: ProviderProfileActivityInsights,
+) -> AccountProfileActivityInsightsView {
+    AccountProfileActivityInsightsView {
+        fast_mode_percent: insights.fast_mode_percent,
+        reasoning_effort: insights.reasoning_effort,
+        reasoning_effort_percent: insights.reasoning_effort_percent,
+        skills_explored: insights.skills_explored,
+        total_skills_used: insights.total_skills_used,
+        total_threads: insights.total_threads,
+        invocations: insights.invocations.map(|invocations| {
+            invocations
+                .into_iter()
+                .map(profile_invocation_view)
+                .collect()
+        }),
+    }
+}
+
+fn profile_invocation_view(invocation: ProviderProfileInvocation) -> AccountProfileInvocationView {
+    AccountProfileInvocationView {
+        invocation_type: invocation.invocation_type,
+        plugin_id: invocation.plugin_id,
+        plugin_name: invocation.plugin_name,
+        skill_id: invocation.skill_id,
+        skill_name: invocation.skill_name,
+        usage_count: invocation.usage_count,
+    }
+}
+
+/// 主动额度重置卡列表响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditsData {
+    pub available_count: u64,
+    pub credits: Vec<AccountResetCreditView>,
+}
+
+/// 一张安全主动额度重置卡视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditView {
+    pub id: String,
+    pub status: Option<String>,
+    pub title: Option<String>,
+    pub expires_at: Option<String>,
+    pub reset_type: Option<String>,
+}
+
+/// 主动额度重置卡消费响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditResultData {
+    pub code: String,
+    pub credit: Option<AccountResetCreditView>,
+}
+
+impl From<ProviderResetCredit> for AccountResetCreditView {
+    fn from(credit: ProviderResetCredit) -> Self {
+        Self {
+            id: credit.id,
+            status: credit.status,
+            title: credit.title,
+            expires_at: credit.expires_at.map(|value| value.to_rfc3339()),
+            reset_type: credit.reset_type,
+        }
+    }
+}
+
+impl From<ProviderResetCredits> for AccountResetCreditsData {
+    fn from(credits: ProviderResetCredits) -> Self {
+        Self {
+            available_count: credits.available_count,
+            credits: credits
+                .credits
+                .into_iter()
+                .map(AccountResetCreditView::from)
+                .collect(),
+        }
+    }
+}
+
+impl From<ProviderResetCreditResult> for AccountResetCreditResultData {
+    fn from(result: ProviderResetCreditResult) -> Self {
+        Self {
+            code: result.code,
+            credit: result.credit.map(AccountResetCreditView::from),
+        }
+    }
+}
+
+/// Provider-owned 明文导出文档；Debug 永远不输出内部 JSON。
+#[derive(Serialize)]
+#[serde(transparent)]
+pub struct AccountExportData(Value);
+
+impl AccountExportData {
+    #[must_use]
+    pub const fn new(value: Value) -> Self {
+        Self(value)
+    }
+
+    pub(super) fn from_result(bundle: AccountExportBundle) -> Self {
+        let documents = bundle
+            .documents
+            .into_iter()
+            .map(|document| {
+                serde_json::json!({
+                    "provider": document.provider_kind.to_string(),
+                    "document": provider_document_value(document.document),
+                })
+            })
+            .collect::<Vec<_>>();
+        Self::new(serde_json::json!({
+            "exportedAt": bundle.exported_at.to_rfc3339(),
+            "documents": documents,
+        }))
+    }
+}
+
+impl fmt::Debug for AccountExportData {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("AccountExportData(<redacted>)")
+    }
+}
+
+pub struct AccountConnectionTestEvent {
+    pub data: Value,
+}
+
+impl From<DomainConnectionTestEvent> for AccountConnectionTestEvent {
+    fn from(event: DomainConnectionTestEvent) -> Self {
+        let data = match event {
+            DomainConnectionTestEvent::Started { model } => serde_json::json!({
+                "type": "test_start",
+                "model": model,
+                "text": "正在连接上游 Responses"
+            }),
+            DomainConnectionTestEvent::Request {
+                model,
+                input_text,
+                stream,
+                store,
+            } => serde_json::json!({
+                "type": "request",
+                "payload": {
+                    "model": model,
+                    "input": [{
+                        "role": "user",
+                        "content": [{ "type": "input_text", "text": input_text }]
+                    }],
+                    "stream": stream,
+                    "store": store
+                }
+            }),
+            DomainConnectionTestEvent::Content { text } => {
+                serde_json::json!({ "type": "content", "text": text })
+            }
+            DomainConnectionTestEvent::Completed => serde_json::json!({
+                "type": "test_complete",
+                "success": true
+            }),
+            DomainConnectionTestEvent::Failed {
+                source,
+                gateway_error_code,
+                send_state,
+                message,
+                provider_error_code,
+                provider_error_type,
+                upstream_status,
+                upstream_content_type,
+                upstream_body,
+            } => serde_json::json!({
+                "type": "error",
+                "source": source.as_str(),
+                "gatewayErrorCode": gateway_error_code.as_str(),
+                "sendState": send_state.map(gateway_core::upstream::UpstreamSendState::as_str),
+                "error": message,
+                "providerErrorCode": provider_error_code,
+                "providerErrorType": provider_error_type,
+                "upstreamStatus": upstream_status,
+                "upstreamContentType": upstream_content_type,
+                "upstreamBody": upstream_body
+            }),
+        };
+        Self { data }
+    }
+}

backend/crates/gateway-api/src/admin/auth.rs

@@ -0,0 +1,284 @@
+//! 管理员登录、会话与管理请求鉴权接线。
+
+use std::fmt;
+
+use axum::{
+    Router,
+    extract::{FromRequestParts, State},
+    http::{HeaderMap, HeaderValue, StatusCode, header::SET_COOKIE, request::Parts},
+    response::{IntoResponse, Response},
+    routing::{get, post},
+};
+use gateway_admin::{
+    AdminServices,
+    model::auth::{AdminPrincipal, AdminRequestContext, LoginCommand, LoginError},
+};
+use serde::{Deserialize, Serialize};
+use tower_http::request_id::RequestId;
+
+use super::{AdminEnvelope, AdminError, AdminJson, AdminResponse};
+
+const REQUEST_ID_HEADER: &str = "x-request-id";
+const ADMIN_SESSION_COOKIE: &str = "cpr_admin_session";
+const ADMIN_SESSION_COOKIE_ATTRS: &str = "Path=/; Secure; HttpOnly; SameSite=Lax";
+
+/// 所有管理 HTTP 模块从 state 消费同一个认证用例端口。
+pub trait AdminSessionState {
+    fn admin_services(&self) -> &AdminServices;
+}
+
+/// 已通过管理员会话或部署级管理 API Key 鉴权的请求。
+pub struct AdminAuth {
+    context: AdminRequestContext,
+}
+
+impl AdminAuth {
+    #[must_use]
+    pub const fn context(&self) -> &AdminRequestContext {
+        &self.context
+    }
+}
+
+impl<S> FromRequestParts<S> for AdminAuth
+where
+    S: AdminSessionState + Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let principal = require_admin_auth(state, &parts.headers).await?;
+        let request_id = admin_request_id(parts).ok_or_else(AdminError::internal)?;
+        Ok(Self {
+            context: AdminRequestContext {
+                principal,
+                request_id,
+            },
+        })
+    }
+}
+
+/// request-id 层按配置的 header 名注入，同时写入与名字无关的扩展；
+/// 优先读扩展，使自定义 header 名不会让管理请求失去请求上下文。
+/// header 回退覆盖未装配该层的调用方。
+fn admin_request_id(parts: &Parts) -> Option<String> {
+    parts
+        .extensions
+        .get::<RequestId>()
+        .map(RequestId::header_value)
+        .or_else(|| parts.headers.get(REQUEST_ID_HEADER))
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToOwned::to_owned)
+}
+
+pub async fn require_admin_session<S>(state: &S, headers: &HeaderMap) -> Result<String, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    match state
+        .admin_services()
+        .auth()
+        .resolve_admin_user_id(admin_session_cookie(headers).as_deref())
+        .await
+    {
+        Ok(Some(admin_user_id)) => Ok(admin_user_id),
+        Ok(None) => Err(AdminError::admin_session_required()),
+        Err(_) => Err(AdminError::internal()),
+    }
+}
+
+async fn require_admin_auth<S>(state: &S, headers: &HeaderMap) -> Result<AdminPrincipal, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    if let Some(api_key) = admin_api_key_header(headers) {
+        return match state
+            .admin_services()
+            .auth()
+            .verify_admin_api_key(&api_key)
+            .await
+        {
+            Ok(true) => Ok(AdminPrincipal::ApiKey),
+            Ok(false) => Err(AdminError::invalid_admin_api_key()),
+            Err(_) => Err(AdminError::internal()),
+        };
+    }
+
+    require_admin_session(state, headers)
+        .await
+        .map(|admin_user_id| AdminPrincipal::Session { admin_user_id })
+}
+
+fn admin_api_key_header(headers: &HeaderMap) -> Option<String> {
+    let value = headers.get("x-api-key")?.to_str().ok()?.trim();
+    (!value.is_empty()).then(|| value.to_owned())
+}
+
+/// 管理员登录请求；密码不得进入 Debug。
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AdminLoginRequest {
+    username: Option<String>,
+    password: String,
+}
+
+impl AdminLoginRequest {
+    /// 取出认证用例所需字段。
+    #[must_use]
+    pub fn into_parts(self) -> (Option<String>, String) {
+        (self.username, self.password)
+    }
+}
+
+impl fmt::Debug for AdminLoginRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("AdminLoginRequest")
+            .field("username", &self.username)
+            .field("password", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// 登录成功响应。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminLoginData {
+    expires_at: String,
+}
+
+impl AdminLoginData {
+    #[must_use]
+    pub fn new(expires_at: String) -> Self {
+        Self { expires_at }
+    }
+}
+
+/// 管理员会话状态响应。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminSessionStatusData {
+    authenticated: bool,
+}
+
+impl AdminSessionStatusData {
+    #[must_use]
+    pub const fn new(authenticated: bool) -> Self {
+        Self { authenticated }
+    }
+}
+
+/// 登出成功响应。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+pub struct AdminLogoutData {
+    message: &'static str,
+}
+
+impl AdminLogoutData {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            message: "Logged out successfully",
+        }
+    }
+}
+
+impl Default for AdminLogoutData {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// 构造固定 GET/POST 管理员认证路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/auth/login", post(login::<S>))
+        .route("/api/admin/auth/status", get(session_status::<S>))
+        .route("/api/admin/auth/logout", post(logout::<S>))
+}
+
+async fn login<S>(
+    State(state): State<S>,
+    AdminJson(payload): AdminJson<AdminLoginRequest>,
+) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (username, password) = payload.into_parts();
+    let session = state
+        .admin_services()
+        .auth()
+        .login(LoginCommand { username, password })
+        .await
+        .map_err(map_login_error)?;
+    let mut response = AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AdminLoginData::new(session.expires_at.to_rfc3339())),
+    )
+    .into_response();
+    let cookie = format!(
+        "{ADMIN_SESSION_COOKIE}={}; {ADMIN_SESSION_COOKIE_ATTRS}",
+        session.session_id
+    );
+    response.headers_mut().insert(
+        SET_COOKIE,
+        HeaderValue::from_str(&cookie).map_err(|_| AdminError::internal())?,
+    );
+    Ok(response)
+}
+
+async fn session_status<S>(
+    State(state): State<S>,
+    headers: HeaderMap,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let authenticated = state
+        .admin_services()
+        .auth()
+        .validate_session(admin_session_cookie(&headers).as_deref())
+        .await
+        .map_err(|_| AdminError::internal())?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AdminSessionStatusData::new(authenticated)),
+    ))
+}
+
+async fn logout<S>(State(state): State<S>, headers: HeaderMap) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    if let Some(session_id) = admin_session_cookie(&headers) {
+        let _ = state.admin_services().auth().logout(&session_id).await;
+    }
+    let mut response =
+        AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(AdminLogoutData::new()))
+            .into_response();
+    let cookie = format!("{ADMIN_SESSION_COOKIE}=; {ADMIN_SESSION_COOKIE_ATTRS}; Max-Age=0");
+    response.headers_mut().insert(
+        SET_COOKIE,
+        HeaderValue::from_str(&cookie).map_err(|_| AdminError::internal())?,
+    );
+    Ok(response)
+}
+
+fn admin_session_cookie(headers: &HeaderMap) -> Option<String> {
+    let cookie = headers.get("cookie")?.to_str().ok()?;
+    cookie.split(';').find_map(|part| {
+        let (name, value) = part.trim().split_once('=')?;
+        (name == ADMIN_SESSION_COOKIE).then(|| value.to_owned())
+    })
+}
+
+fn map_login_error(error: LoginError) -> AdminError {
+    match error {
+        LoginError::InvalidCredentials => AdminError::invalid_admin_credentials(),
+        LoginError::Unavailable => AdminError::internal(),
+    }
+}

backend/crates/gateway-api/src/admin/backups.rs

@@ -0,0 +1,459 @@
+//! 备份设置、计划、手动创建、记录、下载与删除路由。
+//!
+//! 路径统一位于 `/api/admin/settings/backups/*`，内部由独立 `BackupService` 承担业务。
+
+use axum::{
+    Router,
+    extract::State,
+    http::StatusCode,
+    response::IntoResponse,
+    routing::{get, post},
+};
+use chrono::{DateTime, Utc};
+use gateway_admin::model::backup::{
+    BackupRecord, BackupSettings, BackupStatus, BackupTriggerKind, ConnectionTestResult,
+    UpdateBackupScheduleCommand, UpdateBackupStorageCommand,
+};
+use secrecy::{ExposeSecret as _, SecretString};
+use serde::{Deserialize, Serialize};
+
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminPageData, AdminQuery, AdminResponse,
+    AdminSessionState, PageMeta, wire::map_admin_service_error,
+};
+
+/// 备份设置视图；`secretAccessKey` 返回已保存的明文凭据，由前端掩码显示。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BackupSettingsView {
+    pub storage_revision: u64,
+    pub endpoint: Option<String>,
+    pub region: Option<String>,
+    pub bucket: Option<String>,
+    pub access_key_id: Option<String>,
+    pub secret_access_key: Option<String>,
+    pub prefix: Option<String>,
+    pub force_path_style: bool,
+    pub verified: bool,
+    pub schedule_enabled: bool,
+    pub cron_expression: Option<String>,
+    pub schedule_timezone: Option<String>,
+    pub retention_days: u32,
+    pub retention_count: u32,
+    pub next_run_at: Option<DateTime<Utc>>,
+    pub last_verified_at: Option<DateTime<Utc>>,
+    pub updated_at: DateTime<Utc>,
+}
+
+impl From<BackupSettings> for BackupSettingsView {
+    fn from(settings: BackupSettings) -> Self {
+        let verified = settings.storage_verified();
+        Self {
+            storage_revision: settings.storage_revision,
+            endpoint: settings.endpoint,
+            region: settings.region,
+            bucket: settings.bucket,
+            access_key_id: settings.access_key_id,
+            secret_access_key: settings
+                .secret_access_key
+                .map(|secret| secret.expose_secret().to_owned()),
+            prefix: settings.prefix,
+            force_path_style: settings.force_path_style,
+            verified,
+            schedule_enabled: settings.schedule_enabled,
+            cron_expression: settings.cron_expression,
+            schedule_timezone: settings.schedule_timezone,
+            retention_days: settings.retention_days,
+            retention_count: settings.retention_count,
+            next_run_at: settings.next_run_at,
+            last_verified_at: settings.last_verified_at,
+            updated_at: settings.updated_at,
+        }
+    }
+}
+
+/// 更新 S3 存储配置请求；`secretAccessKey` 缺省表示保留旧值。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateBackupStorageRequest {
+    pub endpoint: String,
+    pub region: String,
+    pub bucket: String,
+    pub access_key_id: String,
+    #[serde(default)]
+    pub secret_access_key: Option<String>,
+    pub prefix: String,
+    pub force_path_style: bool,
+}
+
+/// 更新调度配置请求。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateBackupScheduleRequest {
+    pub schedule_enabled: bool,
+    pub cron_expression: String,
+    pub schedule_timezone: String,
+    pub retention_days: u32,
+    pub retention_count: u32,
+}
+
+/// 备份记录 wire 视图。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BackupRecordView {
+    pub id: String,
+    pub trigger_kind: String,
+    pub status: String,
+    pub scheduled_at: Option<DateTime<Utc>>,
+    pub object_key: String,
+    pub size_bytes: Option<u64>,
+    pub sha256: Option<String>,
+    pub attempt_count: u32,
+    pub error_code: Option<String>,
+    pub error_message: Option<String>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub completed_at: Option<DateTime<Utc>>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+impl From<BackupRecord> for BackupRecordView {
+    fn from(record: BackupRecord) -> Self {
+        Self {
+            id: record.id,
+            trigger_kind: record.trigger_kind.to_string(),
+            status: record.status.to_string(),
+            scheduled_at: record.scheduled_at,
+            object_key: record.object_key,
+            size_bytes: record.size_bytes,
+            sha256: record.sha256,
+            attempt_count: record.attempt_count,
+            error_code: record.error_code,
+            error_message: record.error_message,
+            started_at: record.started_at,
+            completed_at: record.completed_at,
+            expires_at: record.expires_at,
+            created_at: record.created_at,
+            updated_at: record.updated_at,
+        }
+    }
+}
+
+/// 记录列表查询参数。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BackupRecordsQuery {
+    pub page: Option<u32>,
+    pub page_size: Option<u16>,
+    pub status: Option<String>,
+    pub trigger: Option<String>,
+}
+
+/// 下载地址请求。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct BackupIdRequest {
+    pub backup_id: String,
+}
+
+/// 下载地址响应。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DownloadUrlView {
+    pub url: String,
+    pub file_name: String,
+    pub expires_in_seconds: u64,
+}
+
+impl From<gateway_admin::model::backup::DownloadUrlResult> for DownloadUrlView {
+    fn from(result: gateway_admin::model::backup::DownloadUrlResult) -> Self {
+        Self {
+            url: result.url,
+            file_name: result.file_name,
+            expires_in_seconds: result.expires_in.as_secs(),
+        }
+    }
+}
+
+/// 连接测试响应。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ConnectionTestView {
+    pub ok: bool,
+    pub stage: String,
+    pub code: Option<String>,
+    pub message: String,
+}
+
+impl From<ConnectionTestResult> for ConnectionTestView {
+    fn from(result: ConnectionTestResult) -> Self {
+        Self {
+            ok: result.ok,
+            stage: result.stage.to_owned(),
+            code: result.code.map(str::to_owned),
+            message: result.message,
+        }
+    }
+}
+
+/// 构造固定 GET/POST 备份路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/settings/backups", get(backup_settings::<S>))
+        .route(
+            "/api/admin/settings/backups/storage/update",
+            post(update_backup_storage::<S>),
+        )
+        .route(
+            "/api/admin/settings/backups/storage/test",
+            post(test_backup_storage::<S>),
+        )
+        .route(
+            "/api/admin/settings/backups/schedule/update",
+            post(update_backup_schedule::<S>),
+        )
+        .route(
+            "/api/admin/settings/backups/records",
+            get(backup_records::<S>),
+        )
+        .route(
+            "/api/admin/settings/backups/create",
+            post(create_backup::<S>),
+        )
+        .route(
+            "/api/admin/settings/backups/download-url",
+            post(download_backup_url::<S>),
+        )
+        .route(
+            "/api/admin/settings/backups/delete",
+            post(delete_backup::<S>),
+        )
+}
+
+async fn backup_settings<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let settings = state
+        .admin_services()
+        .backups()
+        .load_settings()
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(BackupSettingsView::from(settings)),
+    ))
+}
+
+async fn update_backup_storage<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateBackupStorageRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = UpdateBackupStorageCommand {
+        endpoint: request.endpoint,
+        region: request.region,
+        bucket: request.bucket,
+        access_key_id: request.access_key_id,
+        secret_access_key: request.secret_access_key.map(SecretString::from),
+        prefix: request.prefix,
+        force_path_style: request.force_path_style,
+    };
+    let settings = state
+        .admin_services()
+        .backups()
+        .update_storage(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(BackupSettingsView::from(settings)),
+    ))
+}
+
+async fn test_backup_storage<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .backups()
+        .test_connection(&auth.context().mutation_context())
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(ConnectionTestView::from(result)),
+    ))
+}
+
+async fn update_backup_schedule<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateBackupScheduleRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = UpdateBackupScheduleCommand {
+        schedule_enabled: request.schedule_enabled,
+        cron_expression: request.cron_expression,
+        schedule_timezone: request.schedule_timezone,
+        retention_days: request.retention_days,
+        retention_count: request.retention_count,
+    };
+    let settings = state
+        .admin_services()
+        .backups()
+        .update_schedule(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(BackupSettingsView::from(settings)),
+    ))
+}
+
+async fn backup_records<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<BackupRecordsQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let page_size = gateway_admin::model::PageSize::new(query.page_size.unwrap_or(20))
+        .map_err(|_| AdminError::bad_request("pageSize 不合法"))?;
+    let page = query.page.unwrap_or(1);
+    if page == 0 {
+        return Err(AdminError::bad_request("page 不合法"));
+    }
+    let status = match query.status.as_deref() {
+        None => None,
+        Some(value) => BackupStatus::parse(value)
+            .map(Some)
+            .ok_or_else(|| AdminError::bad_request("status 不合法"))?,
+    };
+    let trigger = match query.trigger.as_deref() {
+        None => None,
+        Some(value) => BackupTriggerKind::parse(value)
+            .map(Some)
+            .ok_or_else(|| AdminError::bad_request("trigger 不合法"))?,
+    };
+    let domain_query = gateway_admin::model::backup::BackupRecordListQuery {
+        page,
+        page_size,
+        status,
+        trigger,
+    };
+    let page_result = state
+        .admin_services()
+        .backups()
+        .list_records(domain_query)
+        .await
+        .map_err(map_service_error)?;
+    let meta = PageMeta::new(
+        page_result.page,
+        u32::from(page_result.page_size.get()),
+        page_result.total,
+        page_result.total_pages(),
+    );
+    let items: Vec<BackupRecordView> = page_result
+        .items
+        .into_iter()
+        .map(BackupRecordView::from)
+        .collect();
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AdminPageData::new(items, meta)),
+    ))
+}
+
+async fn create_backup<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    body: Option<AdminJson<CreateBackupRequest>>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let expires_at = body
+        .and_then(|body| body.0.expires_in_days)
+        .filter(|&days| days > 0)
+        .map(|days| Utc::now() + chrono::Duration::days(i64::from(days)));
+    let record = state
+        .admin_services()
+        .backups()
+        .create_backup(&auth.context().mutation_context(), expires_at)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::ACCEPTED,
+        AdminEnvelope::ok(BackupRecordView::from(record)),
+    ))
+}
+
+/// 创建备份请求；`expiresInDays` 为 0 或缺省表示不设置过期时间。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct CreateBackupRequest {
+    pub expires_in_days: Option<u32>,
+}
+
+async fn download_backup_url<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<BackupIdRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .backups()
+        .download_url(&auth.context().mutation_context(), &request.backup_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(DownloadUrlView::from(result)),
+    ))
+}
+
+async fn delete_backup<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<BackupIdRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let record = state
+        .admin_services()
+        .backups()
+        .delete_backup(&auth.context().mutation_context(), &request.backup_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(BackupRecordView::from(record)),
+    ))
+}
+
+fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
+    map_admin_service_error(error)
+}

backend/crates/gateway-api/src/admin/client_keys.rs

@@ -0,0 +1,834 @@
+//! Client API Key 管理 wire contract。
+
+use std::fmt;
+
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use chrono::{DateTime, Utc};
+use gateway_admin::model::client_keys::{
+    ClientKeyCursor, ClientKeyCursorValue as DomainCursorValue, ClientKeyListQuery,
+    ClientKeyMutation, ClientKeyPage, ClientKeyPageSize, ClientKeyRecord, ClientKeySecret,
+    ClientKeySort as DomainSort, ClientKeySortField as DomainSortField, CreateClientKey,
+    CreatedClientKey, DeleteClientKey, SetClientKeyEnabled, SortDirection, UpdateClientKey,
+};
+use gateway_core::{
+    policy::{ClientApiKeyId, RateLimits},
+    routing::AccountGroupId,
+};
+use serde::{Deserialize, Serialize};
+
+use axum::{
+    Router,
+    extract::State,
+    http::{HeaderValue, StatusCode, header::CACHE_CONTROL},
+    response::{IntoResponse, Response},
+    routing::{get, post},
+};
+
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    WireValidationError, wire::map_admin_service_error,
+};
+
+const MAX_CURSOR_BYTES: usize = 512;
+const MAX_SEARCH_BYTES: usize = 256;
+const DEFAULT_PAGE_SIZE: u16 = 50;
+
+/// Client Key 列表查询。
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ListClientKeysQuery {
+    cursor: Option<String>,
+    limit: Option<u16>,
+    search: Option<String>,
+    sort_by: Option<String>,
+    sort_direction: Option<String>,
+}
+
+impl ListClientKeysQuery {
+    /// 校验 wire 边界并直接构造管理用例查询。
+    pub fn into_command(self) -> Result<ClientKeyListQuery, WireValidationError> {
+        if self
+            .cursor
+            .as_deref()
+            .is_some_and(|cursor| cursor.is_empty() || cursor.len() > MAX_CURSOR_BYTES)
+        {
+            return Err(WireValidationError::new("cursor"));
+        }
+        if self.limit == Some(0) {
+            return Err(WireValidationError::new("limit"));
+        }
+        let search = self.search.map(|search| search.trim().to_owned());
+        if search.as_deref().is_some_and(|search| {
+            search.len() > MAX_SEARCH_BYTES
+                || search.chars().any(char::is_control)
+                || contains_client_key_material(search)
+        }) {
+            return Err(WireValidationError::new("search"));
+        }
+        let sort = ClientKeySort::parse(
+            self.sort_by.as_deref().unwrap_or("createdAt"),
+            self.sort_direction.as_deref().unwrap_or("desc"),
+        )?;
+        let cursor = self
+            .cursor
+            .as_deref()
+            .map(decode_client_key_cursor)
+            .transpose()?
+            .map(domain_cursor)
+            .transpose()?;
+        let page_size = ClientKeyPageSize::new(self.limit.unwrap_or(DEFAULT_PAGE_SIZE))
+            .map_err(|_| WireValidationError::new("limit"))?;
+        Ok(ClientKeyListQuery {
+            cursor,
+            page_size,
+            search: search.filter(|search| !search.is_empty()),
+            sort: domain_sort(sort),
+        })
+    }
+}
+
+/// Client Key 数据库排序字段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum ClientKeySortField {
+    Name,
+    Enabled,
+    CreatedAt,
+    LastUsedAt,
+}
+
+/// Client Key 数据库排序方向。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ClientKeySortDirection {
+    Asc,
+    Desc,
+}
+
+/// 已校验且会写入自描述游标的排序组合。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ClientKeySort {
+    pub field: ClientKeySortField,
+    pub direction: ClientKeySortDirection,
+}
+
+impl ClientKeySort {
+    fn parse(field: &str, direction: &str) -> Result<Self, WireValidationError> {
+        let field = match field {
+            "name" => ClientKeySortField::Name,
+            "enabled" => ClientKeySortField::Enabled,
+            "createdAt" => ClientKeySortField::CreatedAt,
+            "lastUsedAt" => ClientKeySortField::LastUsedAt,
+            _ => return Err(WireValidationError::new("sortBy")),
+        };
+        let direction = match direction {
+            "asc" => ClientKeySortDirection::Asc,
+            "desc" => ClientKeySortDirection::Desc,
+            _ => return Err(WireValidationError::new("sortDirection")),
+        };
+        Ok(Self { field, direction })
+    }
+}
+
+/// 创建 Client Key 请求。
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct CreateClientKeyRequest {
+    name: String,
+    label: Option<String>,
+    group_ids: Vec<String>,
+    max_concurrency: u64,
+    requests_per_minute: u64,
+}
+
+impl CreateClientKeyRequest {
+    /// 校验 wire 边界并直接构造管理用例命令。
+    pub fn into_command(self) -> Result<CreateClientKey, WireValidationError> {
+        validate_required_text(&self.name, "name")?;
+        validate_optional_text(self.label.as_deref(), "label")?;
+        let group_ids = validate_group_ids(self.group_ids)?;
+        validate_limit(self.max_concurrency, "maxConcurrency")?;
+        validate_limit(self.requests_per_minute, "requestsPerMinute")?;
+        Ok(CreateClientKey {
+            name: self.name,
+            label: self.label,
+            group_ids,
+            limits: RateLimits {
+                max_concurrency: self.max_concurrency,
+                requests_per_minute: self.requests_per_minute,
+            },
+        })
+    }
+}
+
+/// 更新 Client Key 请求。
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateClientKeyRequest {
+    id: String,
+    name: String,
+    label: Option<String>,
+    group_ids: Vec<String>,
+    max_concurrency: u64,
+    requests_per_minute: u64,
+}
+
+impl UpdateClientKeyRequest {
+    /// 校验 wire 边界并直接构造管理用例命令。
+    pub fn into_command(self) -> Result<UpdateClientKey, WireValidationError> {
+        validate_required_text(&self.id, "id")?;
+        validate_required_text(&self.name, "name")?;
+        validate_optional_text(self.label.as_deref(), "label")?;
+        let group_ids = validate_group_ids(self.group_ids)?;
+        validate_limit(self.max_concurrency, "maxConcurrency")?;
+        validate_limit(self.requests_per_minute, "requestsPerMinute")?;
+        Ok(UpdateClientKey {
+            id: client_key_id(self.id, "clientKeyMutationNotFound")?,
+            name: self.name,
+            label: self.label,
+            group_ids,
+            limits: RateLimits {
+                max_concurrency: self.max_concurrency,
+                requests_per_minute: self.requests_per_minute,
+            },
+        })
+    }
+}
+
+/// 只携带 ID 的 Client Key mutation 请求。
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ClientKeyMutationRequest {
+    id: String,
+}
+
+/// 读取一次完整 Key 的 ID query。
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ClientKeyIdQuery {
+    id: String,
+}
+
+impl ClientKeyIdQuery {
+    pub fn into_id(self) -> Result<String, WireValidationError> {
+        validate_required_text(&self.id, "id")?;
+        Ok(self.id)
+    }
+
+    fn into_domain_id(self) -> Result<ClientApiKeyId, WireValidationError> {
+        client_key_id(self.into_id()?, "clientKeyRevealNotFound")
+    }
+}
+
+impl ClientKeyMutationRequest {
+    /// 校验请求并取出 ID。
+    pub fn into_id(self) -> Result<String, WireValidationError> {
+        validate_required_text(&self.id, "id")?;
+        Ok(self.id)
+    }
+
+    fn into_domain_id(self) -> Result<ClientApiKeyId, WireValidationError> {
+        client_key_id(self.into_id()?, "clientKeyMutationNotFound")
+    }
+}
+
+/// 不含完整 Key 的管理端安全视图。
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ClientKeyView {
+    id: String,
+    name: String,
+    label: Option<String>,
+    routing_scope: &'static str,
+    groups: Vec<ClientKeyGroupView>,
+    provider_kinds: Vec<String>,
+    prefix: String,
+    enabled: bool,
+    max_concurrency: u64,
+    requests_per_minute: u64,
+    created_at: DateTime<Utc>,
+    updated_at: DateTime<Utc>,
+    last_used_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ClientKeyGroupView {
+    id: String,
+    name: String,
+    color: String,
+    enabled: bool,
+}
+
+impl From<ClientKeyRecord> for ClientKeyView {
+    fn from(record: ClientKeyRecord) -> Self {
+        let routing_scope = if record.groups.is_empty() {
+            "all"
+        } else {
+            "groups"
+        };
+        Self {
+            id: record.id.to_string(),
+            name: record.name,
+            label: record.label,
+            routing_scope,
+            groups: record
+                .groups
+                .into_iter()
+                .map(|group| ClientKeyGroupView {
+                    id: group.id.to_string(),
+                    name: group.name,
+                    color: group.color.as_str().to_owned(),
+                    enabled: group.enabled,
+                })
+                .collect(),
+            provider_kinds: record
+                .provider_kinds
+                .into_iter()
+                .map(|provider| provider.to_string())
+                .collect(),
+            prefix: record.prefix,
+            enabled: record.enabled,
+            max_concurrency: record.limits.max_concurrency,
+            requests_per_minute: record.limits.requests_per_minute,
+            created_at: record.created_at,
+            updated_at: record.updated_at,
+            last_used_at: record.last_used_at,
+        }
+    }
+}
+
+/// Client Key 列表响应数据。
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ClientKeyListData {
+    items: Vec<ClientKeyView>,
+    next_cursor: Option<String>,
+    total: u64,
+}
+
+impl ClientKeyListData {
+    /// 构造 Client Key 列表响应。
+    #[must_use]
+    pub fn new(items: Vec<ClientKeyView>, next_cursor: Option<String>, total: u64) -> Self {
+        Self {
+            items,
+            next_cursor,
+            total,
+        }
+    }
+}
+
+impl TryFrom<ClientKeyPage> for ClientKeyListData {
+    type Error = WireValidationError;
+
+    fn try_from(page: ClientKeyPage) -> Result<Self, Self::Error> {
+        let next_cursor = page
+            .next_cursor
+            .map(wire_cursor)
+            .transpose()?
+            .as_ref()
+            .map(encode_client_key_cursor)
+            .transpose()?;
+        Ok(Self::new(
+            page.items.into_iter().map(Into::into).collect(),
+            next_cursor,
+            page.total,
+        ))
+    }
+}
+
+/// Client Key 创建响应；完整值只允许出现在本次序列化结果中。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CreatedClientKeyData {
+    id: String,
+    prefix: String,
+    plaintext_key: String,
+}
+
+impl CreatedClientKeyData {
+    /// 构造一次性创建响应。
+    #[must_use]
+    pub fn new(id: String, prefix: String, plaintext_key: String) -> Self {
+        Self {
+            id,
+            prefix,
+            plaintext_key,
+        }
+    }
+}
+
+impl From<CreatedClientKey> for CreatedClientKeyData {
+    fn from(created: CreatedClientKey) -> Self {
+        Self::new(
+            created.secret.record.id.to_string(),
+            created.secret.record.prefix.clone(),
+            created.secret.expose_for_response().to_owned(),
+        )
+    }
+}
+
+impl fmt::Debug for CreatedClientKeyData {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("CreatedClientKeyData")
+            .field("id", &self.id)
+            .field("prefix", &self.prefix)
+            .field("plaintext_key", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// 仅由显式 reveal 返回一次的完整明文 Key。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RevealedClientKeyData {
+    id: String,
+    plaintext_key: String,
+}
+
+impl RevealedClientKeyData {
+    #[must_use]
+    pub fn new(id: String, plaintext_key: String) -> Self {
+        Self { id, plaintext_key }
+    }
+}
+
+impl From<ClientKeySecret> for RevealedClientKeyData {
+    fn from(secret: ClientKeySecret) -> Self {
+        Self::new(
+            secret.record.id.to_string(),
+            secret.expose_for_response().to_owned(),
+        )
+    }
+}
+
+impl fmt::Debug for RevealedClientKeyData {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("RevealedClientKeyData")
+            .field("id", &self.id)
+            .field("plaintext_key", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// Client Key mutation 响应数据。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MutatedClientKeyData {
+    id: String,
+}
+
+impl MutatedClientKeyData {
+    /// 构造 mutation 响应。
+    #[must_use]
+    pub fn new(id: String) -> Self {
+        Self { id }
+    }
+}
+
+impl From<ClientKeyMutation> for MutatedClientKeyData {
+    fn from(mutation: ClientKeyMutation) -> Self {
+        Self::new(mutation.id.to_string())
+    }
+}
+
+/// 解码后的 Client Key 游标字段。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyCursorData {
+    pub sort: ClientKeySort,
+    pub value: ClientKeyCursorValue,
+    pub id: String,
+}
+
+/// 游标中与排序字段严格对应的最后一行值。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", content = "value", rename_all = "camelCase")]
+pub enum ClientKeyCursorValue {
+    Name(String),
+    Enabled(bool),
+    CreatedAt(DateTime<Utc>),
+    LastUsedAt(Option<DateTime<Utc>>),
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct CursorWire {
+    sort: ClientKeySort,
+    value: ClientKeyCursorValue,
+    id: String,
+}
+
+/// 把 owner 游标编码为不透明 wire 值。
+pub fn encode_client_key_cursor(
+    cursor: &ClientKeyCursorData,
+) -> Result<String, WireValidationError> {
+    validate_client_key_cursor(cursor)?;
+    let bytes = serde_json::to_vec(&CursorWire {
+        sort: cursor.sort,
+        value: cursor.value.clone(),
+        id: cursor.id.clone(),
+    })
+    .map_err(|_| WireValidationError::new("cursor"))?;
+    Ok(URL_SAFE_NO_PAD.encode(bytes))
+}
+
+/// 解码并严格校验 Client Key 游标。
+pub fn decode_client_key_cursor(encoded: &str) -> Result<ClientKeyCursorData, WireValidationError> {
+    if encoded.is_empty() || encoded.len() > MAX_CURSOR_BYTES {
+        return Err(WireValidationError::new("cursor"));
+    }
+    let bytes = URL_SAFE_NO_PAD
+        .decode(encoded)
+        .map_err(|_| WireValidationError::new("cursor"))?;
+    let cursor: CursorWire =
+        serde_json::from_slice(&bytes).map_err(|_| WireValidationError::new("cursor"))?;
+    let cursor = ClientKeyCursorData {
+        sort: cursor.sort,
+        value: cursor.value,
+        id: cursor.id,
+    };
+    validate_client_key_cursor(&cursor)?;
+    Ok(cursor)
+}
+
+fn validate_client_key_cursor(cursor: &ClientKeyCursorData) -> Result<(), WireValidationError> {
+    validate_required_text(&cursor.id, "cursor")?;
+    let matching = matches!(
+        (cursor.sort.field, &cursor.value),
+        (ClientKeySortField::Name, ClientKeyCursorValue::Name(value)) if !value.trim().is_empty()
+    ) || matches!(
+        (cursor.sort.field, &cursor.value),
+        (
+            ClientKeySortField::Enabled,
+            ClientKeyCursorValue::Enabled(_)
+        ) | (
+            ClientKeySortField::CreatedAt,
+            ClientKeyCursorValue::CreatedAt(_)
+        ) | (
+            ClientKeySortField::LastUsedAt,
+            ClientKeyCursorValue::LastUsedAt(_)
+        )
+    );
+    if matching {
+        Ok(())
+    } else {
+        Err(WireValidationError::new("cursor"))
+    }
+}
+
+const fn domain_sort(sort: ClientKeySort) -> DomainSort {
+    DomainSort {
+        field: match sort.field {
+            ClientKeySortField::Name => DomainSortField::Name,
+            ClientKeySortField::Enabled => DomainSortField::Enabled,
+            ClientKeySortField::CreatedAt => DomainSortField::CreatedAt,
+            ClientKeySortField::LastUsedAt => DomainSortField::LastUsedAt,
+        },
+        direction: match sort.direction {
+            ClientKeySortDirection::Asc => SortDirection::Asc,
+            ClientKeySortDirection::Desc => SortDirection::Desc,
+        },
+    }
+}
+
+const fn wire_sort(sort: DomainSort) -> ClientKeySort {
+    ClientKeySort {
+        field: match sort.field {
+            DomainSortField::Name => ClientKeySortField::Name,
+            DomainSortField::Enabled => ClientKeySortField::Enabled,
+            DomainSortField::CreatedAt => ClientKeySortField::CreatedAt,
+            DomainSortField::LastUsedAt => ClientKeySortField::LastUsedAt,
+        },
+        direction: match sort.direction {
+            SortDirection::Asc => ClientKeySortDirection::Asc,
+            SortDirection::Desc => ClientKeySortDirection::Desc,
+        },
+    }
+}
+
+fn domain_cursor(cursor: ClientKeyCursorData) -> Result<ClientKeyCursor, WireValidationError> {
+    let value = match cursor.value {
+        ClientKeyCursorValue::Name(value) => DomainCursorValue::Name(value),
+        ClientKeyCursorValue::Enabled(value) => DomainCursorValue::Enabled(value),
+        ClientKeyCursorValue::CreatedAt(value) => DomainCursorValue::CreatedAt(value),
+        ClientKeyCursorValue::LastUsedAt(value) => DomainCursorValue::LastUsedAt(value),
+    };
+    Ok(ClientKeyCursor {
+        sort: domain_sort(cursor.sort),
+        value,
+        id: client_key_id(cursor.id, "cursor")?,
+    })
+}
+
+fn wire_cursor(cursor: ClientKeyCursor) -> Result<ClientKeyCursorData, WireValidationError> {
+    let value = match cursor.value {
+        DomainCursorValue::Name(value) => ClientKeyCursorValue::Name(value),
+        DomainCursorValue::Enabled(value) => ClientKeyCursorValue::Enabled(value),
+        DomainCursorValue::CreatedAt(value) => ClientKeyCursorValue::CreatedAt(value),
+        DomainCursorValue::LastUsedAt(value) => ClientKeyCursorValue::LastUsedAt(value),
+    };
+    let cursor = ClientKeyCursorData {
+        sort: wire_sort(cursor.sort),
+        value,
+        id: cursor.id.to_string(),
+    };
+    validate_client_key_cursor(&cursor)?;
+    Ok(cursor)
+}
+
+fn client_key_id(
+    value: String,
+    field: &'static str,
+) -> Result<ClientApiKeyId, WireValidationError> {
+    ClientApiKeyId::new(value).map_err(|_| WireValidationError::new(field))
+}
+
+fn validate_limit(value: u64, field: &'static str) -> Result<(), WireValidationError> {
+    if i64::try_from(value).is_err() {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn validate_required_text(value: &str, field: &'static str) -> Result<(), WireValidationError> {
+    if value.trim().is_empty() {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn validate_group_ids(values: Vec<String>) -> Result<Vec<AccountGroupId>, WireValidationError> {
+    if values.len() > 1000
+        || values
+            .iter()
+            .collect::<std::collections::BTreeSet<_>>()
+            .len()
+            != values.len()
+    {
+        return Err(WireValidationError::new("groupIds"));
+    }
+    values
+        .into_iter()
+        .map(|value| AccountGroupId::new(value).map_err(|_| WireValidationError::new("groupIds")))
+        .collect()
+}
+
+fn validate_optional_text(
+    value: Option<&str>,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.is_some_and(|value| value.trim().is_empty()) {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn contains_client_key_material(value: &str) -> bool {
+    value.as_bytes().windows(46).any(|window| {
+        &window[..3] == b"sk_"
+            && window[3..]
+                .iter()
+                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
+    })
+}
+
+/// 构造固定 GET/POST 且 ID 仅位于 query/body 的 Client API Key 路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/client-keys", get(list_client_keys::<S>))
+        .route(
+            "/api/admin/client-keys/create",
+            post(create_client_key::<S>),
+        )
+        .route("/api/admin/client-keys/reveal", get(reveal_client_key::<S>))
+        .route(
+            "/api/admin/client-keys/update",
+            post(update_client_key::<S>),
+        )
+        .route(
+            "/api/admin/client-keys/disable",
+            post(disable_client_key::<S>),
+        )
+        .route(
+            "/api/admin/client-keys/enable",
+            post(enable_client_key::<S>),
+        )
+        .route(
+            "/api/admin/client-keys/delete",
+            post(delete_client_key::<S>),
+        )
+}
+
+async fn list_client_keys<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ListClientKeysQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .client_keys()
+        .list(query.into_command().map_err(map_wire_error)?)
+        .await
+        .map_err(map_service_error)?;
+    let data = ClientKeyListData::try_from(result).map_err(|_| AdminError::internal())?;
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn create_client_key<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(payload): AdminJson<CreateClientKeyRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = payload.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .client_keys()
+        .create(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(CreatedClientKeyData::from(result)),
+    ))
+}
+
+async fn reveal_client_key<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ClientKeyIdQuery>,
+) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let id = query.into_domain_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .client_keys()
+        .reveal(&id)
+        .await
+        .map_err(map_service_error)?;
+    let mut response = AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(RevealedClientKeyData::from(result)),
+    )
+    .into_response();
+    response
+        .headers_mut()
+        .insert(CACHE_CONTROL, HeaderValue::from_static("no-store"));
+    Ok(response)
+}
+
+async fn update_client_key<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(payload): AdminJson<UpdateClientKeyRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = payload.into_command().map_err(map_wire_error)?;
+    mutation_response(
+        state
+            .admin_services()
+            .client_keys()
+            .update(&auth.context().mutation_context(), command)
+            .await,
+    )
+}
+
+async fn disable_client_key<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let id = payload.into_domain_id().map_err(map_wire_error)?;
+    mutation_response(
+        state
+            .admin_services()
+            .client_keys()
+            .set_enabled(
+                &auth.context().mutation_context(),
+                SetClientKeyEnabled { id, enabled: false },
+            )
+            .await,
+    )
+}
+
+async fn enable_client_key<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let id = payload.into_domain_id().map_err(map_wire_error)?;
+    mutation_response(
+        state
+            .admin_services()
+            .client_keys()
+            .set_enabled(
+                &auth.context().mutation_context(),
+                SetClientKeyEnabled { id, enabled: true },
+            )
+            .await,
+    )
+}
+
+async fn delete_client_key<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let id = payload.into_domain_id().map_err(map_wire_error)?;
+    mutation_response(
+        state
+            .admin_services()
+            .client_keys()
+            .delete(&auth.context().mutation_context(), DeleteClientKey { id })
+            .await,
+    )
+}
+
+fn mutation_response(
+    result: Result<ClientKeyMutation, gateway_admin::model::AdminError>,
+) -> Result<AdminResponse<AdminEnvelope<MutatedClientKeyData>>, AdminError> {
+    let data = result.map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(MutatedClientKeyData::from(data)),
+    ))
+}
+
+fn map_wire_error(error: WireValidationError) -> AdminError {
+    match error.field() {
+        "cursor" => AdminError::bad_request("Client API Key 游标不合法"),
+        "clientKeyRevealNotFound" | "clientKeyMutationNotFound" => {
+            AdminError::not_found("Client API Key 不存在")
+        }
+        _ => AdminError::bad_request("Client API Key 请求不合法"),
+    }
+}
+
+fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
+    map_admin_service_error(error)
+}

backend/crates/gateway-api/src/admin/extract.rs

@@ -0,0 +1,87 @@
+//! 管理端 JSON 与 Query extractor 的稳定 rejection 映射。
+
+use axum::{
+    Json,
+    extract::{
+        FromRequest, FromRequestParts, OptionalFromRequest, Query, Request,
+        rejection::{JsonRejection, QueryRejection},
+    },
+    http::{StatusCode, request::Parts},
+};
+use serde::de::DeserializeOwned;
+
+use super::AdminError;
+
+/// 将 Axum JSON rejection 收口为管理端错误信封。
+pub struct AdminJson<T>(pub T);
+
+impl<T, S> FromRequest<S> for AdminJson<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request(request: Request, state: &S) -> Result<Self, Self::Rejection> {
+        <Json<T> as FromRequest<S>>::from_request(request, state)
+            .await
+            .map(|Json(value)| Self(value))
+            .map_err(map_json_rejection)
+    }
+}
+
+impl<T, S> OptionalFromRequest<S> for AdminJson<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request(request: Request, state: &S) -> Result<Option<Self>, Self::Rejection> {
+        <Json<T> as OptionalFromRequest<S>>::from_request(request, state)
+            .await
+            .map(|value| value.map(|Json(value)| Self(value)))
+            .map_err(map_json_rejection)
+    }
+}
+
+/// 将 Axum Query rejection 收口为管理端错误信封。
+pub struct AdminQuery<T>(pub T);
+
+impl<T, S> FromRequestParts<S> for AdminQuery<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        Query::<T>::from_request_parts(parts, state)
+            .await
+            .map(|Query(value)| Self(value))
+            .map_err(map_query_rejection)
+    }
+}
+
+fn map_json_rejection(rejection: JsonRejection) -> AdminError {
+    let status = rejection.status();
+    match rejection {
+        JsonRejection::JsonSyntaxError(_) => AdminError::malformed_json(),
+        JsonRejection::JsonDataError(_) => {
+            AdminError::invalid_request(StatusCode::UNPROCESSABLE_ENTITY, "请求字段不合法")
+        }
+        JsonRejection::MissingJsonContentType(_) => AdminError::invalid_request(
+            StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            "请求必须使用 application/json",
+        ),
+        JsonRejection::BytesRejection(_) if status == StatusCode::PAYLOAD_TOO_LARGE => {
+            AdminError::invalid_request(status, "请求体过大")
+        }
+        JsonRejection::BytesRejection(_) => AdminError::internal(),
+        _ => AdminError::invalid_request(status, "请求体不合法"),
+    }
+}
+
+fn map_query_rejection(_: QueryRejection) -> AdminError {
+    AdminError::bad_request("请求参数不合法")
+}

backend/crates/gateway-api/src/admin/mod.rs

@@ -0,0 +1,64 @@
+//! 管理端 HTTP adapter、wire contract 与固定路由。
+
+use axum::{
+    Router,
+    http::{HeaderValue, header},
+    middleware,
+    response::Response,
+    routing::any,
+};
+
+pub mod account_groups;
+pub mod accounts;
+pub mod auth;
+pub mod backups;
+pub mod client_keys;
+mod extract;
+pub mod observability;
+pub mod presenter;
+pub mod settings;
+pub mod system;
+pub mod wire;
+
+pub use auth::{AdminAuth, AdminSessionState};
+pub use extract::{AdminJson, AdminQuery};
+pub use wire::{
+    ADMIN_OK_CODE, ADMIN_OK_MESSAGE, AdminEnvelope, AdminError, AdminErrorBody, AdminErrorCode,
+    AdminPageData, AdminResponse, PageMeta, WireValidationError,
+};
+
+/// 构造完整且固定的 `/api/admin` 路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .merge(account_groups::router::<S>())
+        .merge(accounts::router::<S>())
+        .merge(auth::router::<S>())
+        .merge(backups::router::<S>())
+        .merge(client_keys::router::<S>())
+        .merge(observability::router::<S>())
+        .merge(settings::router::<S>())
+        .merge(system::router::<S>())
+        .method_not_allowed_fallback(method_not_allowed)
+        .route("/api/admin", any(admin_not_found))
+        .route("/api/admin/{*path}", any(admin_not_found))
+        .layer(middleware::map_response(no_store))
+}
+
+async fn method_not_allowed() -> AdminError {
+    AdminError::method_not_allowed()
+}
+
+async fn admin_not_found() -> AdminError {
+    AdminError::admin_route_not_found()
+}
+
+async fn no_store(mut response: Response) -> Response {
+    response
+        .headers_mut()
+        .entry(header::CACHE_CONTROL)
+        .or_insert(HeaderValue::from_static("no-store"));
+    response
+}

backend/crates/gateway-api/src/admin/observability/mod.rs

@@ -0,0 +1,25 @@
+//! Dashboard、用量与诊断查询的 wire 映射和固定路由。
+
+use std::collections::BTreeMap;
+
+use axum::{Router, extract::State, http::StatusCode, response::IntoResponse, routing::get};
+use chrono::{DateTime, Duration, Utc};
+use gateway_admin::model::{PageSize as DomainPageSize, observability as domain};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use super::presenter::{format_compact_number, format_decimal_currency, format_number};
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminQuery, AdminResponse, AdminSessionState,
+    WireValidationError, wire::map_admin_service_error,
+};
+
+mod presenter;
+mod query;
+mod routes;
+mod wire;
+
+pub(crate) use presenter::*;
+pub use query::*;
+pub use routes::*;
+pub use wire::*;

backend/crates/gateway-api/src/admin/observability/query.rs

@@ -0,0 +1,370 @@
+//! 查询 wire 类型、校验与领域命令映射。
+
+use super::*;
+
+/// 观测列表默认页大小。
+pub const DEFAULT_PAGE_SIZE: u16 = 50;
+/// 观测列表允许的最大页大小。
+pub const MAX_PAGE_SIZE: u16 = 100;
+
+/// Dashboard 查询参数。
+#[derive(Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct DashboardQuery {
+    pub kind: Option<String>,
+    pub start_time: Option<String>,
+    pub end_time: Option<String>,
+}
+
+impl DashboardQuery {
+    /// 解析 dashboard 趋势类型。
+    pub fn trend_kind(&self) -> Result<TrendKind, WireValidationError> {
+        TrendKind::parse(self.kind.as_deref())
+    }
+}
+
+/// 逻辑请求列表、汇总和洞察查询参数。
+#[derive(Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UsageQuery {
+    pub current_page: Option<u32>,
+    pub page_size: Option<u16>,
+    pub kind: Option<String>,
+    pub outcome: Option<String>,
+    pub client_api_key_id: Option<String>,
+    pub provider: Option<String>,
+    pub request_id: Option<String>,
+    pub account_id: Option<String>,
+    pub route: Option<String>,
+    pub model: Option<String>,
+    pub status_code: Option<i64>,
+    pub transport: Option<String>,
+    pub attempt_index: Option<i64>,
+    pub response_id: Option<String>,
+    pub upstream_request_id: Option<String>,
+    pub search: Option<String>,
+    pub start_time: Option<String>,
+    pub end_time: Option<String>,
+}
+
+impl UsageQuery {
+    /// 校验 Element Plus 风格的页码分页字段。
+    pub fn validate_pagination(&self) -> Result<(u32, u16), WireValidationError> {
+        let current_page = self.current_page.unwrap_or(1);
+        if current_page == 0 {
+            return Err(WireValidationError::new("currentPage"));
+        }
+        let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
+        if page_size == 0 || page_size > MAX_PAGE_SIZE {
+            return Err(WireValidationError::new("pageSize"));
+        }
+        Ok((current_page, page_size))
+    }
+}
+
+/// 详情查询参数。
+#[derive(Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct DetailQuery {
+    pub id: String,
+}
+
+impl DetailQuery {
+    /// 校验详情 ID，错误不回显输入值。
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_text(&self.id, "id")
+    }
+}
+
+/// 诊断聚合查询参数。
+#[derive(Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct DiagnosticsQuery {
+    pub dimension: Option<String>,
+    pub start_time: Option<String>,
+    pub end_time: Option<String>,
+    pub provider: Option<String>,
+    pub model: Option<String>,
+    pub status_code: Option<i64>,
+    pub search: Option<String>,
+}
+
+impl DiagnosticsQuery {
+    /// 解析诊断维度。
+    pub fn dimension(&self) -> Result<DiagnosticDimension, WireValidationError> {
+        DiagnosticDimension::parse(self.dimension.as_deref())
+    }
+}
+
+/// 运维错误查询参数。
+#[derive(Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct OpsQuery {
+    pub current_page: Option<u32>,
+    pub page_size: Option<u16>,
+    pub kind: Option<String>,
+    pub client_api_key_id: Option<String>,
+    pub provider: Option<String>,
+    pub request_id: Option<String>,
+    pub account_id: Option<String>,
+    pub model: Option<String>,
+    pub status_code: Option<i64>,
+    pub client_status_code: Option<i64>,
+    pub upstream_status_code: Option<i64>,
+    pub transport: Option<String>,
+    pub attempt_index: Option<i64>,
+    pub response_id: Option<String>,
+    pub upstream_request_id: Option<String>,
+    pub search: Option<String>,
+    pub start_time: Option<String>,
+    pub end_time: Option<String>,
+}
+
+impl OpsQuery {
+    /// 校验 Element Plus 风格的页码分页字段。
+    pub fn validate_pagination(&self) -> Result<(u32, u16), WireValidationError> {
+        let current_page = self.current_page.unwrap_or(1);
+        if current_page == 0 {
+            return Err(WireValidationError::new("currentPage"));
+        }
+        let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
+        if page_size == 0 || page_size > MAX_PAGE_SIZE {
+            return Err(WireValidationError::new("pageSize"));
+        }
+        Ok((current_page, page_size))
+    }
+}
+
+/// Dashboard 趋势类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum TrendKind {
+    Usage,
+    Latency,
+    Errors,
+}
+
+impl TrendKind {
+    /// 从 query 值解析趋势类型。
+    pub fn parse(value: Option<&str>) -> Result<Self, WireValidationError> {
+        match trimmed(value) {
+            None | Some("usage") => Ok(Self::Usage),
+            Some("latency") => Ok(Self::Latency),
+            Some("errors") => Ok(Self::Errors),
+            Some(_) => Err(WireValidationError::new("kind")),
+        }
+    }
+}
+
+/// 诊断聚合维度。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DiagnosticDimension {
+    Model,
+    Account,
+    ApiKey,
+    Provider,
+    Transport,
+    Failure,
+    Status,
+}
+
+impl DiagnosticDimension {
+    /// 从 query 值解析诊断维度。
+    pub fn parse(value: Option<&str>) -> Result<Self, WireValidationError> {
+        match trimmed(value) {
+            None | Some("model") => Ok(Self::Model),
+            Some("account") => Ok(Self::Account),
+            Some("apiKey" | "api_key") => Ok(Self::ApiKey),
+            Some("provider") => Ok(Self::Provider),
+            Some("transport") => Ok(Self::Transport),
+            Some("failureClass" | "failure_class") => Ok(Self::Failure),
+            Some("status") => Ok(Self::Status),
+            Some(_) => Err(WireValidationError::new("dimension")),
+        }
+    }
+
+    /// 返回终态响应中的稳定维度名称。
+    #[must_use]
+    pub const fn display_name(self) -> &'static str {
+        match self {
+            Self::Model => "model",
+            Self::Account => "account",
+            Self::ApiKey => "apiKey",
+            Self::Provider => "provider",
+            Self::Transport => "transport",
+            Self::Failure => "failureClass",
+            Self::Status => "status",
+        }
+    }
+}
+
+/// 解析 RFC3339 时间；错误不回显原始值。
+pub fn parse_datetime(value: Option<&str>) -> Result<Option<DateTime<Utc>>, WireValidationError> {
+    let Some(value) = trimmed(value) else {
+        return Ok(None);
+    };
+    DateTime::parse_from_rfc3339(value)
+        .map(|value| Some(value.with_timezone(&Utc)))
+        .map_err(|_| WireValidationError::new("timeRange"))
+}
+
+/// 解析 HTTP 状态码。
+pub fn parse_status(value: Option<i64>) -> Result<Option<u16>, WireValidationError> {
+    value
+        .map(|value| {
+            u16::try_from(value)
+                .ok()
+                .filter(|value| (100..=599).contains(value))
+                .ok_or_else(|| WireValidationError::new("statusCode"))
+        })
+        .transpose()
+}
+
+/// 解析尝试序号。
+pub fn parse_attempt_index(value: Option<i64>) -> Result<Option<u32>, WireValidationError> {
+    value
+        .map(|value| {
+            u32::try_from(value)
+                .ok()
+                .filter(|value| *value > 0 && *value <= i32::MAX as u32)
+                .ok_or_else(|| WireValidationError::new("attemptIndex"))
+        })
+        .transpose()
+}
+
+pub(crate) fn require_text(value: &str, field: &'static str) -> Result<(), WireValidationError> {
+    if value.trim().is_empty() {
+        Err(WireValidationError::new(field))
+    } else {
+        Ok(())
+    }
+}
+
+pub(crate) fn trimmed(value: Option<&str>) -> Option<&str> {
+    value.map(str::trim).filter(|value| !value.is_empty())
+}
+
+pub(crate) fn domain_trend_kind(kind: TrendKind) -> domain::TrendKind {
+    match kind {
+        TrendKind::Usage => domain::TrendKind::Usage,
+        TrendKind::Latency => domain::TrendKind::Latency,
+        TrendKind::Errors => domain::TrendKind::Errors,
+    }
+}
+
+pub(crate) fn domain_diagnostic_dimension(
+    dimension: DiagnosticDimension,
+) -> domain::DiagnosticDimension {
+    match dimension {
+        DiagnosticDimension::Model => domain::DiagnosticDimension::Model,
+        DiagnosticDimension::Account => domain::DiagnosticDimension::Account,
+        DiagnosticDimension::ApiKey => domain::DiagnosticDimension::ApiKey,
+        DiagnosticDimension::Provider => domain::DiagnosticDimension::Provider,
+        DiagnosticDimension::Transport => domain::DiagnosticDimension::Transport,
+        DiagnosticDimension::Failure => domain::DiagnosticDimension::Failure,
+        DiagnosticDimension::Status => domain::DiagnosticDimension::Status,
+    }
+}
+
+pub(crate) fn request_outcome(
+    value: Option<String>,
+) -> Result<Option<domain::RequestOutcome>, WireValidationError> {
+    non_empty(value)
+        .map(|value| {
+            domain::RequestOutcome::new(value).map_err(|_| WireValidationError::new("outcome"))
+        })
+        .transpose()
+}
+
+pub(crate) fn usage_range(
+    start: Option<&str>,
+    end: Option<&str>,
+) -> Result<domain::TimeRange, WireValidationError> {
+    let end = parse_datetime(end)?.unwrap_or_else(Utc::now);
+    let start = parse_datetime(start)?.unwrap_or(end - Duration::days(7));
+    domain::TimeRange::new(start, end).map_err(|_| WireValidationError::new("timeRange"))
+}
+
+pub(crate) fn dashboard_today_range(
+    start: Option<&str>,
+    end: Option<&str>,
+) -> Result<domain::TimeRange, WireValidationError> {
+    let end = parse_datetime(end)?.unwrap_or_else(Utc::now);
+    let start = parse_datetime(start)?.unwrap_or_else(|| domain::china_day_start(end));
+    domain::TimeRange::new(start, end).map_err(|_| WireValidationError::new("timeRange"))
+}
+
+pub(crate) fn usage_filter(query: &UsageQuery) -> Result<domain::UsageFilter, WireValidationError> {
+    let outcome = query.outcome.clone().or_else(|| {
+        non_empty(query.kind.clone()).filter(|value| {
+            matches!(
+                value.as_str(),
+                "running" | "succeeded" | "failed" | "cancelled" | "incomplete"
+            )
+        })
+    });
+    Ok(domain::UsageFilter {
+        client_api_key_ref: non_empty(query.client_api_key_id.clone()),
+        request_id: non_empty(query.request_id.clone()),
+        provider_account_ref: non_empty(query.account_id.clone()),
+        operation: non_empty(query.route.clone()),
+        provider_kind: non_empty(query.provider.clone()),
+        model: non_empty(query.model.clone()),
+        outcome: request_outcome(outcome)?,
+        status_code: parse_status(query.status_code)?,
+        transport: non_empty(query.transport.clone()),
+        attempt_index: parse_attempt_index(query.attempt_index)?,
+        response_id: non_empty(query.response_id.clone()),
+        upstream_request_id: non_empty(query.upstream_request_id.clone()),
+        search: non_empty(query.search.clone()),
+    })
+}
+
+pub(crate) fn usage_command(query: &UsageQuery) -> Result<domain::UsageQuery, WireValidationError> {
+    let (current_page, page_size) = query.validate_pagination()?;
+    let page_size_value =
+        DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
+    Ok(domain::UsageQuery {
+        range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
+        filter: usage_filter(query)?,
+        current_page,
+        page_size: page_size_value,
+    })
+}
+
+pub(crate) fn ops_command(query: &OpsQuery) -> Result<domain::OpsErrorQuery, WireValidationError> {
+    let (current_page, page_size) = query.validate_pagination()?;
+    let page_size_value =
+        DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
+    let status_code = parse_status(
+        query
+            .upstream_status_code
+            .or(query.client_status_code)
+            .or(query.status_code),
+    )?;
+    Ok(domain::OpsErrorQuery {
+        range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
+        filter: domain::OpsErrorFilter {
+            client_api_key_ref: non_empty(query.client_api_key_id.clone()),
+            request_id: non_empty(query.request_id.clone()),
+            provider_kind: non_empty(query.provider.clone()),
+            provider_account_ref: non_empty(query.account_id.clone()),
+            operation: non_empty(query.kind.clone()),
+            model: non_empty(query.model.clone()),
+            transport: non_empty(query.transport.clone()),
+            attempt_index: parse_attempt_index(query.attempt_index)?,
+            response_id: non_empty(query.response_id.clone()),
+            upstream_request_id: non_empty(query.upstream_request_id.clone()),
+            status_code,
+            search: non_empty(query.search.clone()),
+        },
+        current_page,
+        page_size: page_size_value,
+    })
+}
+
+pub(crate) fn non_empty(value: Option<String>) -> Option<String> {
+    value
+        .map(|value| value.trim().to_owned())
+        .filter(|value| !value.is_empty())
+}

backend/crates/gateway-api/src/admin/observability/routes.rs

@@ -0,0 +1,212 @@
+//! 固定 `/api/admin` 观测路由与 handler。
+
+use super::*;
+
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/dashboard/summary", get(dashboard_summary::<S>))
+        .route("/api/admin/dashboard/trend", get(dashboard_trend::<S>))
+        .route("/api/admin/usage/records", get(usage_records::<S>))
+        .route(
+            "/api/admin/usage/records/detail",
+            get(usage_record_detail::<S>),
+        )
+        .route(
+            "/api/admin/usage/records/summary",
+            get(usage_records_summary::<S>),
+        )
+        .route(
+            "/api/admin/usage/insights/overview",
+            get(usage_insights_overview::<S>),
+        )
+        .route(
+            "/api/admin/usage/insights/diagnostics",
+            get(usage_insights_diagnostics::<S>),
+        )
+        .route("/api/admin/operations/errors", get(ops_errors::<S>))
+}
+
+pub(crate) async fn dashboard_summary<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<DashboardQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let kind = query.trend_kind().map_err(map_wire_error)?;
+    // 概览默认按中国时区当日统计，与单独趋势接口保持同一口径。
+    let range = dashboard_today_range(query.start_time.as_deref(), query.end_time.as_deref())
+        .map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .observability()
+        .dashboard_summary(range, domain_trend_kind(kind))
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(dashboard_view(result, kind)),
+    ))
+}
+
+pub(crate) async fn dashboard_trend<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<DashboardQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let kind = query.trend_kind().map_err(map_wire_error)?;
+    let range = dashboard_today_range(query.start_time.as_deref(), query.end_time.as_deref())
+        .map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .observability()
+        .dashboard_trend(range, domain_trend_kind(kind))
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(trend_view(result, kind)),
+    ))
+}
+
+pub(crate) async fn usage_records<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = usage_command(&query).map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .observability()
+        .usage_records(command)
+        .await
+        .map_err(map_service_error)?;
+    let data = usage_page_view(result);
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+pub(crate) async fn usage_record_detail<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<DetailQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    query.validate().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .observability()
+        .usage_record_detail(query.id.trim())
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(usage_detail_view(result)),
+    ))
+}
+
+pub(crate) async fn usage_records_summary<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let range = usage_range(query.start_time.as_deref(), query.end_time.as_deref())
+        .map_err(map_wire_error)?;
+    let filter = usage_filter(&query).map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .observability()
+        .usage_summary(range, filter)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(usage_summary_view(result)),
+    ))
+}
+
+pub(crate) async fn usage_insights_overview<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let range = usage_range(query.start_time.as_deref(), query.end_time.as_deref())
+        .map_err(map_wire_error)?;
+    let filter = usage_filter(&query).map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .observability()
+        .usage_insights(range, filter)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(usage_insights_view(result)),
+    ))
+}
+
+pub(crate) async fn usage_insights_diagnostics<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<DiagnosticsQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let dimension = query.dimension().map_err(map_wire_error)?;
+    let range = usage_range(query.start_time.as_deref(), query.end_time.as_deref())
+        .map_err(map_wire_error)?;
+    let filter = domain::UsageFilter {
+        provider_kind: non_empty(query.provider),
+        model: non_empty(query.model),
+        status_code: parse_status(query.status_code).map_err(map_wire_error)?,
+        search: non_empty(query.search),
+        ..domain::UsageFilter::default()
+    };
+    let result = state
+        .admin_services()
+        .observability()
+        .diagnostics(range, filter, domain_diagnostic_dimension(dimension))
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(diagnostics_view(result, dimension)),
+    ))
+}
+
+pub(crate) async fn ops_errors<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<OpsQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = ops_command(&query).map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .observability()
+        .ops_errors(command)
+        .await
+        .map_err(map_service_error)?;
+    let data = ops_page_view(result);
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}

backend/crates/gateway-api/src/admin/observability/wire.rs

@@ -0,0 +1,824 @@
+//! 响应 DTO 与固定 wire 形状。
+
+use super::*;
+
+/// 观测列表响应数据。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PageData<T> {
+    pub items: Vec<T>,
+    pub current_page: u32,
+    pub page_size: u16,
+    pub total: u64,
+}
+
+/// Token 详情展示。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TokenDetailsView {
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+    pub cached_tokens: Option<u64>,
+    pub cache_write_tokens: Option<u64>,
+    pub reasoning_tokens: Option<u64>,
+    pub image_input_tokens: Option<u64>,
+    pub image_output_tokens: Option<u64>,
+    pub total_tokens: Option<u64>,
+    pub input_tokens_display: String,
+    pub output_tokens_display: String,
+    pub cached_tokens_display: String,
+    pub cache_write_tokens_display: String,
+    pub reasoning_tokens_display: String,
+    pub image_input_tokens_display: String,
+    pub image_output_tokens_display: String,
+    pub total_tokens_display: String,
+}
+
+/// 按货币展示的成本。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CostView {
+    pub currency: String,
+    pub estimated_amount: String,
+}
+
+/// 成本覆盖状态计数。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CostCoverageView {
+    pub known: u64,
+    pub partial: u64,
+    pub unknown: u64,
+    pub not_billable: u64,
+}
+
+/// Provider 受控价格规则生成的单次请求费用明细展示。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BillingView {
+    pub input_amount_display: String,
+    pub output_amount_display: String,
+    pub cache_read_amount_display: String,
+    pub cache_write_amount_display: String,
+    pub standard_amount_display: String,
+    pub total_amount_display: String,
+    pub input_price_display: String,
+    pub output_price_display: String,
+    pub cache_read_price_display: String,
+    pub cache_write_price_display: String,
+    pub service_tier_display: String,
+    pub multiplier_display: String,
+}
+
+/// 使用记录表格的窄展示。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageListRecordView {
+    pub id: String,
+    pub provider: Option<String>,
+    pub authentication_kind: Option<String>,
+    pub account_id: Option<String>,
+    pub account_email: Option<String>,
+    pub account_name: Option<String>,
+    pub route: String,
+    pub model: Option<String>,
+    pub requested_model: Option<String>,
+    pub upstream_model: Option<String>,
+    pub service_tier: Option<String>,
+    pub client_transport: String,
+    pub upstream_transport: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: bool,
+    pub token_details: TokenDetailsView,
+    pub billing: Option<BillingView>,
+    pub latency_details: UsageLatencyDetailsView,
+    pub first_token_latency_ms: Option<u64>,
+    pub latency_ms: Option<u64>,
+    pub created_at: DateTime<Utc>,
+    pub created_at_display: String,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+}
+
+/// 单条逻辑请求详情展示。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageRecordView {
+    pub id: String,
+    pub request_id: String,
+    pub client_api_key_id: Option<String>,
+    pub routing_scope: String,
+    pub routing_group_refs: Vec<String>,
+    pub routing_group_names_snapshot: Vec<String>,
+    pub kind: String,
+    pub provider: Option<String>,
+    pub authentication_kind: Option<String>,
+    pub account_id: Option<String>,
+    pub account_email: Option<String>,
+    pub account_name: Option<String>,
+    pub route: String,
+    pub model: Option<String>,
+    pub requested_model: Option<String>,
+    pub upstream_model: Option<String>,
+    pub service_tier: Option<String>,
+    pub status_code: Option<i64>,
+    pub client_transport: String,
+    pub upstream_transport: Option<String>,
+    pub protocol: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub http_version: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub client_status_code: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub upstream_status_code: Option<i64>,
+    pub websocket_pool: Option<WebSocketPoolMetadataView>,
+    pub image_generation_requested: bool,
+    pub image_generation_succeeded: Option<bool>,
+    pub latency_details: UsageLatencyDetailsView,
+    pub attempt_index: Option<i64>,
+    pub attempt_count: u64,
+    pub response_id: Option<String>,
+    pub upstream_request_id: Option<String>,
+    pub latency_ms: Option<u64>,
+    pub first_token_ms: Option<u64>,
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+    pub cached_tokens: Option<u64>,
+    pub cache_write_tokens: Option<u64>,
+    pub reasoning_tokens: Option<u64>,
+    pub image_input_tokens: Option<u64>,
+    pub image_output_tokens: Option<u64>,
+    pub message: String,
+    /// Provider 安全观测；Core 字段由顶层字段提供，不再复制进 metadata。
+    pub metadata: BTreeMap<String, Value>,
+    pub created_at: DateTime<Utc>,
+    pub created_at_display: String,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub compact: Option<bool>,
+    pub request_kind: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub token_details: TokenDetailsView,
+    pub billing: Option<BillingView>,
+    pub costs: Vec<CostView>,
+    pub cost_coverage: CostCoverageView,
+    pub first_token_latency_ms: Option<u64>,
+    pub first_token_latency_ms_display: String,
+    pub latency_ms_display: String,
+    pub logical_outcome: String,
+}
+
+/// WebSocket 池决策的稳定形状；与 Provider 选择逻辑无关。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WebSocketPoolMetadataView {
+    pub kind: String,
+}
+
+/// 逻辑请求在上游和输出阶段测得的时延事实。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageLatencyDetailsView {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub admission_decision_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub account_selection_wait_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub capacity_used_slots: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub capacity_total_slots: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transport_decision_wait_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ws_connect_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub upstream_headers_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub first_event_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub first_reasoning_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub first_text_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub first_token_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub openai_processing_ms: Option<u64>,
+}
+
+/// 单次上游尝试展示。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageAttemptView {
+    pub id: String,
+    pub attempt_index: u32,
+    pub trigger: String,
+    pub provider: String,
+    pub model: Option<String>,
+    pub transport: String,
+    pub send_state: String,
+    pub outcome: String,
+    pub downstream_committed: bool,
+    pub status_code: Option<u16>,
+    pub provider_error_code: Option<String>,
+    pub failure_class: Option<String>,
+    pub cost_estimate_status: String,
+    pub estimated_cost_amount: Option<String>,
+    pub estimated_cost_currency: Option<String>,
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+    pub cached_tokens: Option<u64>,
+    pub total_tokens: Option<u64>,
+    pub first_token_ms: Option<u64>,
+    pub latency_ms: Option<u64>,
+    pub credential_name: Option<String>,
+    pub account_id: Option<String>,
+    pub account_name: Option<String>,
+    pub account_email: Option<String>,
+    pub authentication_kind: Option<String>,
+    pub started_at: DateTime<Utc>,
+    pub completed_at: Option<DateTime<Utc>>,
+}
+
+/// 逻辑请求详情与其尝试列表。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageRecordDetailView {
+    pub trace: Option<serde_json::Value>,
+    pub related_requests: Vec<serde_json::Value>,
+    #[serde(flatten)]
+    pub request: UsageRecordView,
+    pub attempts: Vec<UsageAttemptView>,
+    /// 尝试列表是否完整；best-effort 下恒为 false。
+    pub attempts_complete: bool,
+}
+
+/// Dashboard 趋势数据。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TrendData {
+    pub kind: TrendKind,
+    pub points: Vec<TrendPointView>,
+    pub summary: Vec<TrendSummaryView>,
+}
+
+/// Dashboard 单个趋势桶。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TrendPointView {
+    pub time: String,
+    pub bucket: DateTime<Utc>,
+    pub label: String,
+    pub requests: String,
+    pub requests_value: u64,
+    pub input_tokens: String,
+    pub input_tokens_value: u64,
+    pub output_tokens: String,
+    pub output_tokens_value: u64,
+    pub cached_tokens: String,
+    pub cached_tokens_value: u64,
+    pub cache_hit_rate_value: f64,
+    pub tokens_value: u64,
+    pub errors: String,
+    pub errors_value: u64,
+    pub latency: String,
+    pub latency_value: Option<u64>,
+    pub max_latency: String,
+    pub max_latency_value: Option<u64>,
+    pub min_latency: String,
+    pub min_latency_value: Option<u64>,
+    pub success_rate: String,
+    pub success_rate_value: Option<f64>,
+    pub first_token_p50_ms: Option<f64>,
+    pub first_token_p95_ms: Option<f64>,
+    pub latency_p95_ms: Option<f64>,
+    pub output_throughput_p50: Option<u64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub capacity_utilization: Option<f64>,
+}
+
+/// Dashboard 趋势摘要。
+#[derive(Debug, Serialize)]
+pub struct TrendSummaryView {
+    pub label: String,
+    pub value: String,
+    pub ratio: Option<String>,
+}
+
+/// Dashboard 卡片集合。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardCardsView {
+    pub credentials: DashboardCredentialsCardView,
+    pub traffic: DashboardTrafficCardView,
+    pub tokens: DashboardTokensCardView,
+    pub cache: DashboardCacheCardView,
+}
+
+/// Dashboard 上游凭据卡片。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardCredentialsCardView {
+    pub total: String,
+    pub total_value: u64,
+    pub available: String,
+    pub available_value: u64,
+    pub unavailable: String,
+    pub unavailable_value: u64,
+}
+
+/// Dashboard 流量卡片。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardTrafficCardView {
+    pub today_requests: String,
+    pub today_requests_value: u64,
+    pub yesterday_requests_value: u64,
+    pub total_requests: String,
+}
+
+/// Dashboard token 卡片。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardTokensCardView {
+    pub today_tokens: String,
+    pub today_tokens_value: u64,
+    pub yesterday_tokens_value: u64,
+    pub total_tokens: String,
+    pub total_billing_amount_usd: String,
+}
+
+/// Dashboard 缓存卡片。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardCacheCardView {
+    pub today_hit_rate: String,
+    pub today_hit_rate_value: Option<f64>,
+    pub yesterday_hit_rate_value: Option<f64>,
+    pub total_hit_rate: String,
+    pub total_cached_tokens: String,
+    pub average_first_token_latency_ms: String,
+}
+
+/// 旧 Dashboard 账号概览卡片所需的 Provider 安全投影。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardAccountUsageView {
+    pub id: String,
+    pub provider: String,
+    pub authentication_kind: String,
+    pub email: String,
+    pub plan_type: Option<String>,
+    pub tokens: String,
+    pub request_count: u64,
+    pub request_buckets: Vec<DashboardAccountRequestBucketView>,
+    pub quota_used_percent: Option<f64>,
+    pub usage_window: Option<crate::admin::accounts::AccountQuotaWindowView>,
+    pub metric_label: String,
+    pub metric_value: String,
+    pub last_used: String,
+}
+
+/// Dashboard 账号单小时请求数。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardAccountRequestBucketView {
+    pub bucket_start: DateTime<Utc>,
+    pub request_count: u64,
+}
+
+/// Provider 账号池的持久事实汇总。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardPoolSummaryView {
+    pub total: u64,
+    pub normal: u64,
+    pub quota_exhausted: u64,
+    pub rate_limited: u64,
+    pub disabled: u64,
+    pub error: u64,
+}
+
+/// 同 target 账号调度容量；Redis 未提供聚合事实时运行中槽位保持空值。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardCapacityInfoView {
+    pub max_concurrent_per_account: u64,
+    pub total_slots: u64,
+    pub used_slots: Option<u64>,
+    pub available_slots: Option<u64>,
+}
+
+/// 逻辑请求指标展示。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RequestMetricsView {
+    pub request_count: u64,
+    pub success_count: u64,
+    pub failure_count: u64,
+    pub cancelled_count: u64,
+    pub incomplete_count: u64,
+    pub caller_error_count: u64,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cached_tokens: u64,
+    pub cache_write_tokens: u64,
+    pub reasoning_tokens: u64,
+    pub total_tokens: u64,
+}
+
+/// 上游尝试指标展示。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AttemptMetricsView {
+    pub attempt_count: u64,
+    pub success_count: u64,
+    pub failure_count: u64,
+    pub cancelled_count: u64,
+    pub incomplete_count: u64,
+    pub rate_limited_count: u64,
+    pub auth_failure_count: u64,
+    pub provider5xx_count: u64,
+    pub cost_coverage: CostCoverageView,
+    pub costs: Vec<CostView>,
+}
+
+/// 健康时间线单点。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HealthTimelinePointView {
+    pub time: String,
+    pub status: String,
+    pub reliability_display: String,
+    pub success_requests: u64,
+    pub failed_requests: u64,
+    pub cancelled_requests: u64,
+    pub incomplete_requests: u64,
+    pub caller_error_requests: u64,
+}
+
+/// Dashboard 健康时间线。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HealthTimelineView {
+    pub title: String,
+    pub description: String,
+    pub reliability_display: String,
+    pub status: String,
+    pub success_requests: u64,
+    pub failed_requests: u64,
+    pub cancelled_requests: u64,
+    pub incomplete_requests: u64,
+    pub caller_error_requests: u64,
+    pub points: Vec<HealthTimelinePointView>,
+}
+
+/// Dashboard 展示的实际 Provider 上游请求身份。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardWireProfileView {
+    pub provider: String,
+    pub product: String,
+    pub version: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub build: Option<String>,
+    pub target: DashboardWireTargetView,
+    pub user_agent: String,
+    pub attributes: Vec<DashboardWireAttributeView>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub verified_at: Option<DateTime<Utc>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub release: Option<DashboardDesktopReleaseView>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardWireAttributeView {
+    pub label: String,
+    pub value: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardWireTargetView {
+    pub os_type: String,
+    pub os_version: String,
+    pub arch: String,
+    pub terminal: String,
+}
+
+/// 发布检查与启动画像分离；未检查时使用明确的 `unchecked` 状态。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardDesktopReleaseView {
+    pub status: DashboardDesktopReleaseStatusView,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub checked_at: Option<DateTime<Utc>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub latest_version: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub latest_build: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<String>,
+}
+
+/// Dashboard 发布检查的稳定 wire 状态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DashboardDesktopReleaseStatusView {
+    Unchecked,
+    Aligned,
+    ReviewRequired,
+    CheckFailed,
+}
+
+impl From<domain::DesktopReleaseStatus> for DashboardDesktopReleaseStatusView {
+    fn from(status: domain::DesktopReleaseStatus) -> Self {
+        match status {
+            domain::DesktopReleaseStatus::Unchecked => Self::Unchecked,
+            domain::DesktopReleaseStatus::Current => Self::Aligned,
+            domain::DesktopReleaseStatus::UpdateAvailable => Self::ReviewRequired,
+            domain::DesktopReleaseStatus::Failed => Self::CheckFailed,
+        }
+    }
+}
+
+/// Dashboard 汇总响应数据。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardDataView {
+    pub cards: DashboardCardsView,
+    pub trend: TrendData,
+    pub health_timeline: HealthTimelineView,
+    pub wire_profiles: Vec<DashboardWireProfileView>,
+    pub account_usage: Vec<DashboardAccountUsageView>,
+    pub usage_records: Vec<UsageListRecordView>,
+    pub pool_summary: DashboardPoolSummaryView,
+    pub capacity_info: DashboardCapacityInfoView,
+    pub rotation_strategy: String,
+}
+
+/// 用量汇总响应数据。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageSummaryView {
+    pub total_requests: String,
+    pub input_tokens: String,
+    pub output_tokens: String,
+    pub cached_tokens: String,
+    pub cache_write_tokens: String,
+    pub total_tokens: String,
+    pub average_latency_ms: String,
+    pub logical_requests: RequestMetricsView,
+    pub attempts: AttemptMetricsView,
+}
+
+/// 洞察健康趋势点。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct OverviewHealthPointView {
+    pub bucket: DateTime<Utc>,
+    pub label: String,
+    pub total_requests: u64,
+    pub success_requests: u64,
+    pub failed_requests: u64,
+    pub cancelled_requests: u64,
+    pub incomplete_requests: u64,
+    pub caller_error_requests: u64,
+    pub error_rate: f64,
+}
+
+/// 洞察健康摘要。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct OverviewHealthView {
+    pub total_requests: u64,
+    pub success_requests: u64,
+    pub failed_requests: u64,
+    pub cancelled_requests: u64,
+    pub incomplete_requests: u64,
+    pub caller_error_requests: u64,
+    pub success_rate: f64,
+    pub completion_rate: f64,
+    pub request_change_rate: Option<f64>,
+    pub success_rate_change: Option<f64>,
+    pub points: Vec<OverviewHealthPointView>,
+}
+
+/// 洞察性能趋势点。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct OverviewPerformancePointView {
+    pub bucket: DateTime<Utc>,
+    pub label: String,
+    pub latency_p50_ms: Option<f64>,
+    pub latency_p95_ms: Option<f64>,
+    pub latency_p99_ms: Option<f64>,
+    pub first_token_p50_ms: Option<f64>,
+    pub first_token_p95_ms: Option<f64>,
+    pub first_token_p99_ms: Option<f64>,
+    pub admission_decision_p50_ms: Option<f64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p50_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization: Option<f64>,
+    pub capacity_utilization_p95: Option<f64>,
+}
+
+/// 洞察性能摘要。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct OverviewPerformanceView {
+    pub latency_p50_ms: Option<f64>,
+    pub latency_p95_ms: Option<f64>,
+    pub latency_p99_ms: Option<f64>,
+    pub first_token_p50_ms: Option<f64>,
+    pub first_token_p95_ms: Option<f64>,
+    pub first_token_p99_ms: Option<f64>,
+    pub admission_decision_p50_ms: Option<f64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p50_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization: Option<f64>,
+    pub capacity_utilization_p95: Option<f64>,
+    pub latency_coverage: f64,
+    pub first_token_coverage: f64,
+    pub admission_decision_coverage: f64,
+    pub account_selection_wait_coverage: f64,
+    pub capacity_coverage: f64,
+    pub points: Vec<OverviewPerformancePointView>,
+}
+
+/// 洞察成本趋势点。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct OverviewCostPointView {
+    pub bucket: DateTime<Utc>,
+    pub label: String,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cached_tokens: u64,
+    pub total_tokens: u64,
+    pub estimated_cost: Option<String>,
+    pub standard_cost: Option<String>,
+    pub no_cache_cost: Option<String>,
+    pub cache_savings: Option<String>,
+    pub cached_token_rate: f64,
+    pub cache_hit_request_rate: Option<f64>,
+}
+
+/// 洞察成本摘要。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct OverviewCostView {
+    pub estimated_cost: Option<String>,
+    pub standard_cost: Option<String>,
+    pub no_cache_cost: Option<String>,
+    pub cache_savings: Option<String>,
+    pub tier_premium: Option<String>,
+    pub cost_per_request: Option<String>,
+    pub cost_per_successful_request: Option<String>,
+    pub tokens_per_request: f64,
+    pub cached_token_rate: f64,
+    pub cache_hit_request_rate: Option<f64>,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cached_tokens: u64,
+    pub total_tokens: u64,
+    pub points: Vec<OverviewCostPointView>,
+    pub costs: Vec<CostView>,
+    pub coverage: CostCoverageView,
+}
+
+/// Provider 维度洞察摘要。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ProviderOverviewView {
+    pub provider: String,
+    pub request_count: u64,
+    pub attempt_count: u64,
+    pub failure_count: u64,
+    pub total_tokens: u64,
+}
+
+/// 用量洞察总响应。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageInsightsOverviewView {
+    pub granularity: String,
+    pub health: OverviewHealthView,
+    pub performance: OverviewPerformanceView,
+    pub cost: OverviewCostView,
+    pub attempts: AttemptMetricsView,
+    pub providers: Vec<ProviderOverviewView>,
+}
+
+/// 诊断聚合项目。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DiagnosticItemView {
+    pub key: String,
+    pub name: String,
+    pub request_count: u64,
+    pub success_count: u64,
+    pub error_count: u64,
+    pub error_rate: f64,
+    pub request_share: f64,
+    pub average_latency_ms: Option<u64>,
+    pub latency_p95_ms: Option<u64>,
+    pub first_token_p95_ms: Option<u64>,
+    pub non_completion_count: u64,
+    pub non_completion_rate: f64,
+    pub retry_count: u64,
+    pub retry_rate: f64,
+    pub impact_score: f64,
+    pub estimated_cost: Option<String>,
+    pub attempt_count: u64,
+    pub total_tokens: u64,
+}
+
+/// 诊断聚合响应。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DiagnosticsView {
+    pub dimension: String,
+    pub items: Vec<DiagnosticItemView>,
+}
+
+/// 运维错误项目。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct OpsErrorView {
+    pub id: String,
+    pub request_id: Option<String>,
+    pub client_api_key_id: Option<String>,
+    pub kind: String,
+    pub operation: String,
+    pub protocol: Option<String>,
+    pub client_transport: Option<String>,
+    pub provider: Option<String>,
+    pub authentication_kind: Option<String>,
+    pub account_id: Option<String>,
+    pub account_name: Option<String>,
+    pub account_email: Option<String>,
+    pub route: String,
+    pub model: Option<String>,
+    pub requested_model: Option<String>,
+    pub upstream_model: Option<String>,
+    pub service_tier: Option<String>,
+    pub client_status_code: Option<i64>,
+    pub upstream_status_code: Option<i64>,
+    pub transport: Option<String>,
+    pub attempt_index: Option<u32>,
+    pub failure_class: String,
+    pub upstream_send_state: Option<String>,
+    pub provider_error_code: Option<String>,
+    pub response_id: Option<String>,
+    pub upstream_request_id: Option<String>,
+    pub latency_ms: Option<u64>,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub request_kind: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: Option<bool>,
+    pub message: String,
+    /// 上游错误正文或 WebSocket close/error frame 原文；不做脱敏。
+    pub raw_upstream_error: Option<String>,
+    pub metadata: OpsErrorMetadataView,
+    pub created_at: DateTime<Utc>,
+    pub created_at_display: String,
+}
+
+/// 运维错误安全元数据；只保留可查询的标识，不回显秘密材料。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct OpsErrorMetadataView {
+    pub source: String,
+    pub component: String,
+    pub attempt_id: Option<String>,
+    pub account_label: Option<String>,
+    pub continuation_affinity_hash: Option<String>,
+    pub continuation_previous_response_id_hash: Option<String>,
+    pub continuation_unavailable_reason: Option<String>,
+    pub upstream_connection_id: Option<String>,
+    pub upstream_connection_exit_reason: Option<String>,
+    pub upstream_connection_age_ms: Option<u64>,
+    pub upstream_connection_idle_ms: Option<u64>,
+    pub recovery_request_id: Option<String>,
+    pub recovered_at: Option<DateTime<Utc>>,
+    pub recovery_attempt_count: u32,
+    pub recovery_retry_delay_ms: Option<u64>,
+    pub recovery_total_latency_ms: Option<u64>,
+}

backend/crates/gateway-api/src/admin/presenter.rs

@@ -0,0 +1,71 @@
+//! Admin API 的展示层辅助：数值格式化。
+//!
+//! 当前 wire 仍保留 display 字段；统一由本模块提供，避免 accounts/observability
+//! 各自维护格式化规则。
+
+use gateway_core::metering::Decimal;
+
+/// 千分位格式化。
+#[must_use]
+pub fn format_number(value: u64) -> String {
+    let text = value.to_string();
+    let mut output = String::with_capacity(text.len() + text.len() / 3);
+    for (index, character) in text.chars().rev().enumerate() {
+        if index > 0 && index % 3 == 0 {
+            output.push(',');
+        }
+        output.push(character);
+    }
+    output.chars().rev().collect()
+}
+
+/// 紧凑格式化：≥1000 时用 K/M/B/T/P 后缀，否则千分位。
+#[must_use]
+pub fn format_compact_number(value: u64) -> String {
+    if value < 1_000 {
+        return format_number(value);
+    }
+    for (suffix, threshold) in [
+        ("P", 1_000_000_000_000_000_u64),
+        ("T", 1_000_000_000_000_u64),
+        ("B", 1_000_000_000_u64),
+        ("M", 1_000_000_u64),
+        ("K", 1_000_u64),
+    ] {
+        if value >= threshold {
+            let scaled = value as f64 / threshold as f64;
+            return format!("{scaled:.1}{suffix}").replace(".0", "");
+        }
+    }
+    format_number(value)
+}
+
+/// 货币展示格式化。USD 常规金额保留两位，小于 1 美元时最多保留四位。
+#[must_use]
+pub fn format_decimal_currency(amount: &str, currency: &str) -> String {
+    if currency != "USD" {
+        return format!("{currency} {amount}");
+    }
+
+    const DECIMAL_SCALE: u128 = 10_000_000_000;
+    let scaled = amount.parse::<Decimal>().unwrap_or_default().scaled();
+    let precision = if scaled != 0 && scaled < DECIMAL_SCALE {
+        4_u32
+    } else {
+        2_u32
+    };
+    let rounding_unit = 10_u128.pow(10 - precision);
+    let rounded = (scaled + rounding_unit / 2) / rounding_unit;
+    let display_scale = 10_u128.pow(precision);
+    let whole = rounded / display_scale;
+    let fraction = rounded % display_scale;
+    let mut display = format!("{whole}.{fraction:0width$}", width = precision as usize);
+    while display.ends_with('0')
+        && display
+            .split_once('.')
+            .is_some_and(|(_, fraction)| fraction.len() > 2)
+    {
+        display.pop();
+    }
+    format!("${display}")
+}

backend/crates/gateway-api/src/admin/settings.rs

@@ -0,0 +1,446 @@
+//! Runtime settings、旧设置页聚合投影与明文 Admin API Key wire。
+
+use std::{collections::BTreeMap, fmt};
+
+use axum::{
+    Router,
+    extract::State,
+    http::StatusCode,
+    response::IntoResponse,
+    routing::{get, post},
+};
+use chrono::{DateTime, Utc};
+use gateway_admin::model::client_distribution::{
+    ClientDownloadPackage, CodexDesktopWindowsDownloads,
+};
+use gateway_admin::model::settings::{
+    ModelMappings as DomainModelMappings, ReplaceRuntimeSettings, RotationStrategy, RuntimeSettings,
+};
+use gateway_core::policy::CodexClientVersion;
+use gateway_core::routing::{PublicModelId, UpstreamModelId};
+use serde::{Deserialize, Serialize};
+
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    WireValidationError, wire::map_admin_service_error,
+};
+
+/// 客户端模型到上游模型的全局精确映射。
+pub type ModelMappings = BTreeMap<String, String>;
+
+/// 运行配置投影与设置页字段的聚合响应。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeSettingsView {
+    pub model_mappings: ModelMappings,
+    pub refresh_margin_seconds: u64,
+    pub refresh_concurrency: u64,
+    pub max_concurrent_per_account: u64,
+    pub request_interval_ms: u64,
+    pub rotation_strategy: String,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
+    pub usage_retention_days: u64,
+    pub ops_event_retention_days: u64,
+    pub audit_retention_days: u64,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// 原子替换全局运行参数的请求。
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateRuntimeSettingsRequest {
+    pub model_mappings: ModelMappings,
+    pub refresh_margin_seconds: u64,
+    pub refresh_concurrency: u64,
+    pub max_concurrent_per_account: u64,
+    pub request_interval_ms: u64,
+    pub rotation_strategy: String,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
+    pub usage_retention_days: u64,
+    pub ops_event_retention_days: u64,
+    pub audit_retention_days: u64,
+}
+
+impl UpdateRuntimeSettingsRequest {
+    /// 校验公共运行参数。
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        validate_model_mappings(&self.model_mappings)?;
+        for (value, field) in [
+            (self.refresh_margin_seconds, "refreshMarginSeconds"),
+            (self.refresh_concurrency, "refreshConcurrency"),
+            (self.max_concurrent_per_account, "maxConcurrentPerAccount"),
+            (self.usage_retention_days, "usageRetentionDays"),
+            (self.ops_event_retention_days, "opsEventRetentionDays"),
+            (self.audit_retention_days, "auditRetentionDays"),
+        ] {
+            require_positive_i64(value, field)?;
+        }
+        if i64::try_from(self.request_interval_ms).is_err() {
+            return Err(WireValidationError::new("requestIntervalMs"));
+        }
+        if RotationStrategy::parse(&self.rotation_strategy).is_none() {
+            return Err(WireValidationError::new("rotationStrategy"));
+        }
+        validate_optional_client_version(
+            self.min_codex_desktop_version.as_deref(),
+            "minCodexDesktopVersion",
+        )?;
+        validate_optional_client_version(
+            self.min_codex_cli_version.as_deref(),
+            "minCodexCliVersion",
+        )?;
+        Ok(())
+    }
+
+    fn into_command(self) -> Result<ReplaceRuntimeSettings, WireValidationError> {
+        self.validate()?;
+        Ok(ReplaceRuntimeSettings {
+            model_mappings: domain_model_mappings(self.model_mappings)?,
+            refresh_margin_seconds: self.refresh_margin_seconds,
+            refresh_concurrency: u32::try_from(self.refresh_concurrency)
+                .map_err(|_| WireValidationError::new("settingsRefreshConcurrencyOverflow"))?,
+            max_concurrent_per_account: u32::try_from(self.max_concurrent_per_account)
+                .map_err(|_| WireValidationError::new("settingsMaxConcurrencyOverflow"))?,
+            request_interval_ms: self.request_interval_ms,
+            rotation_strategy: RotationStrategy::parse(&self.rotation_strategy)
+                .ok_or_else(|| WireValidationError::new("rotationStrategy"))?,
+            min_codex_desktop_version: self.min_codex_desktop_version,
+            min_codex_cli_version: self.min_codex_cli_version,
+            usage_retention_days: u32::try_from(self.usage_retention_days)
+                .map_err(|_| WireValidationError::new("settingsUsageRetentionOverflow"))?,
+            ops_event_retention_days: u32::try_from(self.ops_event_retention_days)
+                .map_err(|_| WireValidationError::new("settingsOpsRetentionOverflow"))?,
+            audit_retention_days: u32::try_from(self.audit_retention_days)
+                .map_err(|_| WireValidationError::new("settingsAuditRetentionOverflow"))?,
+        })
+    }
+}
+
+impl From<RuntimeSettings> for RuntimeSettingsView {
+    fn from(settings: RuntimeSettings) -> Self {
+        Self {
+            model_mappings: wire_model_mappings(settings.model_mappings),
+            refresh_margin_seconds: settings.refresh_margin_seconds,
+            refresh_concurrency: u64::from(settings.refresh_concurrency),
+            max_concurrent_per_account: u64::from(settings.max_concurrent_per_account),
+            request_interval_ms: settings.request_interval_ms,
+            rotation_strategy: settings.rotation_strategy.as_str().to_owned(),
+            min_codex_desktop_version: settings.min_codex_desktop_version,
+            min_codex_cli_version: settings.min_codex_cli_version,
+            usage_retention_days: u64::from(settings.usage_retention_days),
+            ops_event_retention_days: u64::from(settings.ops_event_retention_days),
+            audit_retention_days: u64::from(settings.audit_retention_days),
+            updated_at: settings.updated_at,
+        }
+    }
+}
+
+/// 管理 API Key 状态；状态读取不回显完整值。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminApiKeyStatus {
+    pub exists: bool,
+}
+
+/// 管理 API Key 重新生成响应。
+#[derive(Serialize)]
+pub struct RegeneratedAdminApiKey {
+    pub key: String,
+}
+
+impl fmt::Debug for RegeneratedAdminApiKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("RegeneratedAdminApiKey")
+            .field("key", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// 管理 API Key 删除响应。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+pub struct DeletedAdminApiKey {
+    pub message: &'static str,
+}
+
+#[derive(Debug, Clone, Copy, Default, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+struct ClientDownloadsQuery {
+    refresh: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ClientDownloadPackageView {
+    architecture: String,
+    source: String,
+    version: Option<String>,
+    file_name: String,
+    size_bytes: Option<u64>,
+    download_url: String,
+    expires_at: Option<DateTime<Utc>>,
+}
+
+impl From<ClientDownloadPackage> for ClientDownloadPackageView {
+    fn from(package: ClientDownloadPackage) -> Self {
+        Self {
+            architecture: package.architecture.as_str().to_owned(),
+            source: package.source.as_str().to_owned(),
+            version: package.version,
+            file_name: package.file_name,
+            size_bytes: package.size_bytes,
+            download_url: package.download_url,
+            expires_at: package.expires_at,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct CodexDesktopWindowsDownloadsView {
+    resolved_at: DateTime<Utc>,
+    cached: bool,
+    warning: Option<String>,
+    packages: Vec<ClientDownloadPackageView>,
+}
+
+impl From<CodexDesktopWindowsDownloads> for CodexDesktopWindowsDownloadsView {
+    fn from(downloads: CodexDesktopWindowsDownloads) -> Self {
+        Self {
+            resolved_at: downloads.resolved_at,
+            cached: downloads.cached,
+            warning: downloads.warning,
+            packages: downloads.packages.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl Default for DeletedAdminApiKey {
+    fn default() -> Self {
+        Self {
+            message: "Admin API key deleted",
+        }
+    }
+}
+
+/// 构造固定 GET/POST 设置路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/settings", get(settings::<S>))
+        .route("/api/admin/settings/update", post(update_settings::<S>))
+        .route(
+            "/api/admin/settings/client-downloads/codex-desktop/windows",
+            get(codex_desktop_windows_downloads::<S>),
+        )
+        .route(
+            "/api/admin/settings/admin-api-key",
+            get(admin_api_key_status::<S>),
+        )
+        .route(
+            "/api/admin/settings/admin-api-key/delete",
+            post(delete_admin_api_key::<S>),
+        )
+        .route(
+            "/api/admin/settings/admin-api-key/regenerate",
+            post(regenerate_admin_api_key::<S>),
+        )
+}
+
+async fn codex_desktop_windows_downloads<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ClientDownloadsQuery>,
+) -> impl IntoResponse
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let downloads = state
+        .admin_services()
+        .client_distribution()
+        .codex_desktop_windows(query.refresh)
+        .await;
+    AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(CodexDesktopWindowsDownloadsView::from(downloads)),
+    )
+}
+
+async fn settings<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .settings()
+        .load()
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(RuntimeSettingsView::from(result)),
+    ))
+}
+
+async fn update_settings<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateRuntimeSettingsRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .settings()
+        .replace(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(RuntimeSettingsView::from(result)),
+    ))
+}
+
+async fn admin_api_key_status<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let exists = state
+        .admin_services()
+        .settings()
+        .admin_api_key_exists()
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AdminApiKeyStatus { exists }),
+    ))
+}
+
+async fn regenerate_admin_api_key<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .settings()
+        .regenerate_admin_api_key(&auth.context().mutation_context())
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(RegeneratedAdminApiKey {
+            key: result.key.expose_for_response().to_owned(),
+        }),
+    ))
+}
+
+async fn delete_admin_api_key<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    state
+        .admin_services()
+        .settings()
+        .delete_admin_api_key(&auth.context().mutation_context())
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(DeletedAdminApiKey::default()),
+    ))
+}
+
+fn require_positive_i64(value: u64, field: &'static str) -> Result<(), WireValidationError> {
+    if value == 0 || i64::try_from(value).is_err() {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn validate_model_mappings(mappings: &ModelMappings) -> Result<(), WireValidationError> {
+    if mappings.len() > 512 {
+        return Err(WireValidationError::new("modelMappings"));
+    }
+    for (requested, upstream) in mappings {
+        if !valid_model_name(requested, 256) || !valid_model_name(upstream, 256) {
+            return Err(WireValidationError::new("modelMappings"));
+        }
+    }
+    Ok(())
+}
+
+fn domain_model_mappings(
+    mappings: ModelMappings,
+) -> Result<DomainModelMappings, WireValidationError> {
+    mappings
+        .into_iter()
+        .map(|(requested, upstream)| {
+            Ok((
+                PublicModelId::new(requested)
+                    .map_err(|_| WireValidationError::new("modelMappings"))?,
+                UpstreamModelId::new(upstream)
+                    .map_err(|_| WireValidationError::new("modelMappings"))?,
+            ))
+        })
+        .collect()
+}
+
+fn wire_model_mappings(mappings: DomainModelMappings) -> ModelMappings {
+    mappings
+        .into_iter()
+        .map(|(requested, upstream)| (requested.to_string(), upstream.to_string()))
+        .collect()
+}
+
+fn valid_model_name(value: &str, max_len: usize) -> bool {
+    !value.is_empty()
+        && value.len() <= max_len
+        && !value.bytes().any(|byte| byte.is_ascii_control())
+}
+
+fn validate_optional_client_version(
+    value: Option<&str>,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.is_some_and(|value| CodexClientVersion::parse(value).is_err()) {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn map_wire_error(error: WireValidationError) -> AdminError {
+    let message = match error.field() {
+        "settingsRefreshConcurrencyOverflow" => "refreshConcurrency 不合法".to_owned(),
+        "settingsMaxConcurrencyOverflow" => "maxConcurrentPerAccount 不合法".to_owned(),
+        "settingsUsageRetentionOverflow" => "usageRetentionDays 不合法".to_owned(),
+        "settingsOpsRetentionOverflow" => "opsEventRetentionDays 不合法".to_owned(),
+        "settingsAuditRetentionOverflow" => "auditRetentionDays 不合法".to_owned(),
+        "minCodexDesktopVersion" => "Codex Desktop 最低版本格式不合法".to_owned(),
+        "minCodexCliVersion" => "Codex CLI 最低版本格式不合法".to_owned(),
+        field => format!("{field} 字段不合法"),
+    };
+    AdminError::bad_request(message)
+}
+
+fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
+    map_admin_service_error(error)
+}

backend/crates/gateway-api/src/admin/system.rs

@@ -0,0 +1,481 @@
+//! 系统管理接口的查询与请求 wire contract。
+//!
+//! 这里不依赖更新服务或进程控制；应用层通过窄端口提供系统操作事实。
+
+use std::convert::Infallible;
+
+use axum::{
+    Router,
+    extract::State,
+    http::StatusCode,
+    response::{
+        IntoResponse,
+        sse::{Event, KeepAlive, Sse},
+    },
+    routing::{get, post},
+};
+use futures::{Stream, StreamExt};
+use gateway_admin::model::system::{
+    SystemOperationAccepted, SystemOperationKind, SystemOperationState, SystemOperationStatus,
+    SystemUpdateDetail, SystemUpdateEvent, SystemUpdateEventLevel, SystemUpdateStatus,
+    SystemVersion,
+};
+use serde::{Deserialize, Serialize};
+
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    wire::map_admin_service_error,
+};
+
+/// 更新详情查询参数。
+#[derive(Debug, Clone, Default, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateDetailQuery {
+    refresh: Option<bool>,
+}
+
+impl UpdateDetailQuery {
+    /// 是否强制从发布源刷新。
+    #[must_use]
+    pub fn refresh(&self) -> bool {
+        self.refresh.unwrap_or(false)
+    }
+}
+
+/// 执行更新请求。
+#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateRequest {
+    target_version: String,
+}
+
+impl UpdateRequest {
+    /// 取出确认的目标版本原值，由更新领域负责版本规范化和校验。
+    #[must_use]
+    pub fn into_target_version(self) -> String {
+        self.target_version
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SystemVersionView {
+    version: String,
+    git_sha: String,
+    build_time: String,
+    deployment_mode: String,
+    deployment_mode_label: String,
+    update_channel: String,
+    latest_version: String,
+    has_update: bool,
+    update_cached: bool,
+    update_warning: Option<String>,
+}
+
+impl From<SystemVersion> for SystemVersionView {
+    fn from(version: SystemVersion) -> Self {
+        Self {
+            deployment_mode_label: deployment_mode_label(&version.deployment_mode).to_owned(),
+            version: version.version,
+            git_sha: version.git_sha,
+            build_time: version.build_time,
+            deployment_mode: version.deployment_mode,
+            update_channel: version.update_channel,
+            latest_version: version.latest_version,
+            has_update: version.has_update,
+            update_cached: version.update_cached,
+            update_warning: version.update_warning,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SystemUpdateDetailView {
+    current_version: String,
+    latest_version: String,
+    has_update: bool,
+    deployment_mode: String,
+    deployment_mode_label: String,
+    build_type: String,
+    build_type_label: String,
+    release_url: Option<String>,
+    notes: Option<String>,
+    cached: bool,
+    update_supported: bool,
+    unsupported_reason: Option<String>,
+    warning: Option<String>,
+}
+
+impl From<SystemUpdateDetail> for SystemUpdateDetailView {
+    fn from(detail: SystemUpdateDetail) -> Self {
+        Self {
+            deployment_mode_label: deployment_mode_label(&detail.deployment_mode).to_owned(),
+            build_type_label: build_type_label(&detail.build_type),
+            current_version: detail.current_version,
+            latest_version: detail.latest_version,
+            has_update: detail.has_update,
+            deployment_mode: detail.deployment_mode,
+            build_type: detail.build_type,
+            release_url: detail.release_url,
+            notes: detail.notes,
+            cached: detail.cached,
+            update_supported: detail.update_supported,
+            unsupported_reason: detail.unsupported_reason,
+            warning: detail.warning,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SystemOperationStateView {
+    operation_id: Option<String>,
+    kind: Option<&'static str>,
+    status: &'static str,
+    target_version: Option<String>,
+    message: Option<String>,
+    error: Option<String>,
+    started_at: Option<String>,
+    finished_at: Option<String>,
+}
+
+impl From<SystemOperationState> for SystemOperationStateView {
+    fn from(operation: SystemOperationState) -> Self {
+        Self {
+            operation_id: operation.operation_id,
+            kind: operation.kind.map(operation_kind_name),
+            status: operation_status_name(operation.status),
+            target_version: operation.target_version,
+            message: operation.message,
+            error: operation.error,
+            started_at: operation.started_at.map(|value| value.to_rfc3339()),
+            finished_at: operation.finished_at.map(|value| value.to_rfc3339()),
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SystemUpdateStatusView {
+    previous_version: Option<String>,
+    current_version: Option<String>,
+    operation: SystemOperationStateView,
+}
+
+impl From<SystemUpdateStatus> for SystemUpdateStatusView {
+    fn from(status: SystemUpdateStatus) -> Self {
+        Self {
+            previous_version: status.previous_version,
+            current_version: status.current_version,
+            operation: status.operation.into(),
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct UpdateAcceptedView {
+    operation_id: String,
+    deployment_mode: String,
+    message: String,
+    need_restart: bool,
+    target_version: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RollbackAcceptedView {
+    message: String,
+    need_restart: bool,
+    operation_id: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RestartAcceptedView {
+    message: String,
+    operation_id: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SystemUpdateEventView {
+    id: String,
+    operation_id: Option<String>,
+    level: &'static str,
+    step: Option<String>,
+    message: String,
+    terminal: bool,
+    progress_percent: Option<u8>,
+    at: String,
+}
+
+/// 构造固定 GET/POST 系统管理路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/system/version", get(version::<S>))
+        .route("/api/admin/system/update/detail", get(update_detail::<S>))
+        .route(
+            "/api/admin/system/update/events",
+            get(update_event_stream::<S>),
+        )
+        .route("/api/admin/system/update", post(perform_update::<S>))
+        .route("/api/admin/system/update/status", get(update_status::<S>))
+        .route("/api/admin/system/rollback", post(rollback::<S>))
+        .route("/api/admin/system/restart", post(restart::<S>))
+}
+
+async fn version<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let version = state
+        .admin_services()
+        .system()
+        .version()
+        .await
+        .map_err(map_system_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(SystemVersionView::from(version)),
+    ))
+}
+
+async fn update_detail<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<UpdateDetailQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let detail = state
+        .admin_services()
+        .system()
+        .update_detail(query.refresh())
+        .await
+        .map_err(map_system_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(SystemUpdateDetailView::from(detail)),
+    ))
+}
+
+async fn update_event_stream<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<Sse<impl Stream<Item = Result<Event, Infallible>>>, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let stream = state
+        .admin_services()
+        .system()
+        .update_events()
+        .map(|message| {
+            let id = message.id.clone();
+            let data = SystemUpdateEventView::from(message).into_json().to_string();
+            Ok(Event::default().event("update").id(id).data(data))
+        });
+    Ok(Sse::new(stream).keep_alive(KeepAlive::default()))
+}
+
+async fn perform_update<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    payload: Option<AdminJson<UpdateRequest>>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .system()
+        .perform_update(payload.map(|AdminJson(value)| value.into_target_version()))
+        .await
+        .map_err(map_system_error)?;
+    let SystemOperationAccepted::Update {
+        operation_id,
+        deployment_mode,
+        message,
+        need_restart,
+        target_version,
+    } = result
+    else {
+        return Err(AdminError::internal());
+    };
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(UpdateAcceptedView {
+            operation_id,
+            deployment_mode,
+            message,
+            need_restart,
+            target_version,
+        }),
+    ))
+}
+
+async fn update_status<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let status = state
+        .admin_services()
+        .system()
+        .update_status()
+        .await
+        .map_err(map_system_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(SystemUpdateStatusView::from(status)),
+    ))
+}
+
+async fn rollback<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .system()
+        .rollback()
+        .await
+        .map_err(map_system_error)?;
+    let SystemOperationAccepted::Rollback {
+        operation_id,
+        message,
+        need_restart,
+    } = result
+    else {
+        return Err(AdminError::internal());
+    };
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(RollbackAcceptedView {
+            message,
+            need_restart,
+            operation_id,
+        }),
+    ))
+}
+
+async fn restart<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .system()
+        .restart()
+        .await
+        .map_err(map_system_error)?;
+    let SystemOperationAccepted::Restart {
+        operation_id,
+        message,
+    } = result
+    else {
+        return Err(AdminError::internal());
+    };
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(RestartAcceptedView {
+            message,
+            operation_id,
+        }),
+    ))
+}
+
+impl From<SystemUpdateEvent> for SystemUpdateEventView {
+    fn from(event: SystemUpdateEvent) -> Self {
+        Self {
+            id: event.id,
+            operation_id: event.operation_id,
+            level: update_event_level_name(event.level),
+            step: event.step,
+            message: event.message,
+            terminal: event.terminal,
+            progress_percent: event.progress_percent,
+            at: event.occurred_at.to_rfc3339(),
+        }
+    }
+}
+
+impl SystemUpdateEventView {
+    fn into_json(self) -> serde_json::Value {
+        serde_json::json!({
+            "id": self.id,
+            "operationId": self.operation_id,
+            "level": self.level,
+            "step": self.step,
+            "message": self.message,
+            "terminal": self.terminal,
+            "progressPercent": self.progress_percent,
+            "at": self.at,
+        })
+    }
+}
+
+fn deployment_mode_label(mode: &str) -> &'static str {
+    match mode {
+        "docker" => "Docker",
+        "binary" => "二进制",
+        _ => "源码运行",
+    }
+}
+
+fn build_type_label(build_type: &str) -> String {
+    match build_type {
+        "release" => "正式构建",
+        "source" => "源码构建",
+        "dev" => "开发构建",
+        value => value,
+    }
+    .to_owned()
+}
+
+const fn operation_kind_name(kind: SystemOperationKind) -> &'static str {
+    match kind {
+        SystemOperationKind::Update => "update",
+        SystemOperationKind::Rollback => "rollback",
+        SystemOperationKind::Restart => "restart",
+    }
+}
+
+const fn operation_status_name(status: SystemOperationStatus) -> &'static str {
+    match status {
+        SystemOperationStatus::Idle => "idle",
+        SystemOperationStatus::Running => "running",
+        SystemOperationStatus::Succeeded => "succeeded",
+        SystemOperationStatus::Failed => "failed",
+    }
+}
+
+const fn update_event_level_name(level: SystemUpdateEventLevel) -> &'static str {
+    match level {
+        SystemUpdateEventLevel::Info => "info",
+        SystemUpdateEventLevel::Warning => "warning",
+        SystemUpdateEventLevel::Success => "success",
+        SystemUpdateEventLevel::Error => "error",
+    }
+}
+
+fn map_system_error(error: gateway_admin::model::AdminError) -> AdminError {
+    map_admin_service_error(error)
+}

backend/crates/gateway-api/src/admin/wire.rs

@@ -0,0 +1,455 @@
+//! 管理端公共 wire、响应信封与脱敏错误。
+
+use std::fmt;
+
+use axum::{
+    Json,
+    http::StatusCode,
+    response::{IntoResponse, Response},
+};
+use serde::{Deserialize, Serialize};
+
+/// 管理端 wire 字段校验错误；只携带稳定字段名，不回显输入值。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WireValidationError {
+    field: &'static str,
+}
+
+impl WireValidationError {
+    /// 构造字段校验错误。
+    #[must_use]
+    pub const fn new(field: &'static str) -> Self {
+        Self { field }
+    }
+
+    /// 返回未通过校验的字段名。
+    #[must_use]
+    pub const fn field(self) -> &'static str {
+        self.field
+    }
+}
+
+/// 成功响应的稳定业务码。
+pub const ADMIN_OK_CODE: u32 = 200;
+
+/// 成功响应的稳定消息。
+pub const ADMIN_OK_MESSAGE: &str = "OK";
+
+/// 页码分页元数据。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PageMeta {
+    page: u32,
+    page_size: u32,
+    total: u64,
+    total_pages: u32,
+}
+
+impl PageMeta {
+    /// 由分页 owner 已经校验并计算的事实构造 wire metadata。
+    #[must_use]
+    pub const fn new(page: u32, page_size: u32, total: u64, total_pages: u32) -> Self {
+        Self {
+            page,
+            page_size,
+            total,
+            total_pages,
+        }
+    }
+
+    /// 当前页，从 1 开始。
+    #[must_use]
+    pub const fn page(self) -> u32 {
+        self.page
+    }
+
+    /// 每页数量。
+    #[must_use]
+    pub const fn page_size(self) -> u32 {
+        self.page_size
+    }
+
+    /// 全部记录数量。
+    #[must_use]
+    pub const fn total(self) -> u64 {
+        self.total
+    }
+
+    /// 总页数。
+    #[must_use]
+    pub const fn total_pages(self) -> u32 {
+        self.total_pages
+    }
+}
+
+/// 管理端稳定业务错误码。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct AdminErrorCode(u32);
+
+impl AdminErrorCode {
+    /// JSON 解析失败。
+    pub const MALFORMED_JSON: Self = Self(40000);
+    /// 请求参数或状态不合法。
+    pub const BAD_REQUEST: Self = Self(40001);
+    /// 时间范围不合法。
+    pub const INVALID_TIME_RANGE: Self = Self(40002);
+    /// 模型来源不合法。
+    pub const INVALID_MODEL_SOURCE: Self = Self(40003);
+    /// 缺少管理员会话。
+    pub const SESSION_REQUIRED: Self = Self(40101);
+    /// 管理员登录凭据错误。
+    pub const INVALID_CREDENTIALS: Self = Self(40102);
+    /// 管理 API Key 错误。
+    pub const INVALID_API_KEY: Self = Self(40103);
+    /// 资源不存在。
+    pub const NOT_FOUND: Self = Self(40401);
+    /// 配置 revision 或资源状态冲突。
+    pub const CONFLICT: Self = Self(40901);
+    /// 管理员登录尝试过多。
+    pub const TOO_MANY_LOGIN_ATTEMPTS: Self = Self(42901);
+    /// 设置持久化失败。
+    pub const SETTINGS_PERSIST: Self = Self(50000);
+    /// 未分类内部错误。
+    pub const INTERNAL: Self = Self(50001);
+    /// 用量记录的账号投影失败。
+    pub const USAGE_RECORD_ACCOUNTS: Self = Self(50002);
+    /// 上游网关失败。
+    pub const BAD_GATEWAY: Self = Self(50201);
+    /// 不可逆上游操作的执行结果未知。
+    pub const UPSTREAM_RESULT_UNKNOWN: Self = Self(50202);
+    /// 依赖的服务暂不可用。
+    pub const SERVICE_UNAVAILABLE: Self = Self(50301);
+
+    /// 返回用于 JSON wire contract 的数值。
+    #[must_use]
+    pub const fn value(self) -> u32 {
+        self.0
+    }
+}
+
+/// 管理端错误响应正文。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminErrorBody {
+    code: AdminErrorCode,
+    message: String,
+    data: (),
+}
+
+impl AdminErrorBody {
+    /// 构造不携带业务数据的管理端错误正文。
+    #[must_use]
+    pub fn new(code: AdminErrorCode, message: impl Into<String>) -> Self {
+        Self {
+            code,
+            message: message.into(),
+            data: (),
+        }
+    }
+
+    /// 稳定业务错误码。
+    #[must_use]
+    pub const fn code(&self) -> AdminErrorCode {
+        self.code
+    }
+
+    /// 安全的客户端错误消息。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+/// 管理端 HTTP 错误。
+pub struct AdminError {
+    status: StatusCode,
+    body: AdminErrorBody,
+}
+
+#[derive(Debug, Clone, Copy)]
+struct AdminErrorSpec {
+    status: StatusCode,
+    code: AdminErrorCode,
+    message: &'static str,
+}
+
+impl AdminErrorSpec {
+    const fn new(status: StatusCode, code: AdminErrorCode, message: &'static str) -> Self {
+        Self {
+            status,
+            code,
+            message,
+        }
+    }
+}
+
+const MALFORMED_JSON: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_REQUEST,
+    AdminErrorCode::MALFORMED_JSON,
+    "请求体不是合法 JSON",
+);
+const BAD_REQUEST: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_REQUEST,
+    AdminErrorCode::BAD_REQUEST,
+    "请求参数不合法",
+);
+const INVALID_TIME_RANGE: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_REQUEST,
+    AdminErrorCode::INVALID_TIME_RANGE,
+    "时间范围不合法",
+);
+const SESSION_REQUIRED: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::UNAUTHORIZED,
+    AdminErrorCode::SESSION_REQUIRED,
+    "需要管理员登录",
+);
+const INVALID_CREDENTIALS: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::UNAUTHORIZED,
+    AdminErrorCode::INVALID_CREDENTIALS,
+    "管理员用户名或密码错误",
+);
+const INVALID_API_KEY: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::UNAUTHORIZED,
+    AdminErrorCode::INVALID_API_KEY,
+    "管理 API Key 无效",
+);
+const ADMIN_ROUTE_NOT_FOUND: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::NOT_FOUND,
+    AdminErrorCode::NOT_FOUND,
+    "管理接口不存在",
+);
+const METHOD_NOT_ALLOWED: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::METHOD_NOT_ALLOWED,
+    AdminErrorCode::BAD_REQUEST,
+    "请求方法不受支持",
+);
+const TOO_MANY_LOGIN_ATTEMPTS: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::TOO_MANY_REQUESTS,
+    AdminErrorCode::TOO_MANY_LOGIN_ATTEMPTS,
+    "登录尝试过多，请稍后重试",
+);
+const INTERNAL: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::INTERNAL_SERVER_ERROR,
+    AdminErrorCode::INTERNAL,
+    "服务内部错误",
+);
+const BAD_GATEWAY: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_GATEWAY,
+    AdminErrorCode::BAD_GATEWAY,
+    "上游服务请求失败",
+);
+const UPSTREAM_RESULT_UNKNOWN: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_GATEWAY,
+    AdminErrorCode::UPSTREAM_RESULT_UNKNOWN,
+    "上游执行结果未知，请刷新状态后再决定是否重试",
+);
+const SERVICE_UNAVAILABLE: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::SERVICE_UNAVAILABLE,
+    AdminErrorCode::SERVICE_UNAVAILABLE,
+    "依赖服务暂不可用",
+);
+
+impl AdminError {
+    fn new(status: StatusCode, code: AdminErrorCode, message: impl Into<String>) -> Self {
+        Self {
+            status,
+            body: AdminErrorBody::new(code, message),
+        }
+    }
+
+    fn from_spec(spec: AdminErrorSpec) -> Self {
+        Self::new(spec.status, spec.code, spec.message)
+    }
+
+    pub fn malformed_json() -> Self {
+        Self::from_spec(MALFORMED_JSON)
+    }
+
+    pub fn invalid_request(status: StatusCode, message: &'static str) -> Self {
+        Self::new(status, BAD_REQUEST.code, message)
+    }
+
+    pub fn invalid_time_range() -> Self {
+        Self::from_spec(INVALID_TIME_RANGE)
+    }
+
+    pub fn admin_route_not_found() -> Self {
+        Self::from_spec(ADMIN_ROUTE_NOT_FOUND)
+    }
+
+    pub fn method_not_allowed() -> Self {
+        Self::from_spec(METHOD_NOT_ALLOWED)
+    }
+
+    pub fn bad_request(message: impl Into<String>) -> Self {
+        Self::new(BAD_REQUEST.status, BAD_REQUEST.code, message)
+    }
+
+    pub fn admin_session_required() -> Self {
+        Self::from_spec(SESSION_REQUIRED)
+    }
+
+    pub fn invalid_admin_credentials() -> Self {
+        Self::from_spec(INVALID_CREDENTIALS)
+    }
+
+    pub fn invalid_admin_api_key() -> Self {
+        Self::from_spec(INVALID_API_KEY)
+    }
+
+    pub fn too_many_login_attempts() -> Self {
+        Self::from_spec(TOO_MANY_LOGIN_ATTEMPTS)
+    }
+
+    pub fn conflict(message: impl Into<String>) -> Self {
+        Self::new(StatusCode::CONFLICT, AdminErrorCode::CONFLICT, message)
+    }
+
+    pub fn not_found(message: impl Into<String>) -> Self {
+        Self::new(StatusCode::NOT_FOUND, AdminErrorCode::NOT_FOUND, message)
+    }
+
+    pub fn internal() -> Self {
+        Self::from_spec(INTERNAL)
+    }
+
+    pub fn bad_gateway() -> Self {
+        Self::from_spec(BAD_GATEWAY)
+    }
+
+    pub fn upstream_result_unknown() -> Self {
+        Self::from_spec(UPSTREAM_RESULT_UNKNOWN)
+    }
+
+    pub fn service_unavailable() -> Self {
+        Self::from_spec(SERVICE_UNAVAILABLE)
+    }
+}
+
+/// 把管理用例的稳定错误分类映射到既有 HTTP 错误 contract。
+pub(crate) fn map_admin_service_error(error: gateway_admin::model::AdminError) -> AdminError {
+    use gateway_admin::model::AdminErrorKind;
+
+    match error.kind() {
+        AdminErrorKind::Invalid => AdminError::bad_request(error.message()),
+        AdminErrorKind::Unauthorized => AdminError::admin_session_required(),
+        AdminErrorKind::NotFound => AdminError::not_found(error.message()),
+        AdminErrorKind::Conflict => AdminError::conflict(error.message()),
+        AdminErrorKind::RateLimited => AdminError::too_many_login_attempts(),
+        AdminErrorKind::BadGateway => AdminError::bad_gateway(),
+        AdminErrorKind::UpstreamResultUnknown => AdminError::upstream_result_unknown(),
+        AdminErrorKind::Unavailable => AdminError::service_unavailable(),
+        AdminErrorKind::Internal => AdminError::internal(),
+    }
+}
+
+impl IntoResponse for AdminError {
+    fn into_response(self) -> Response {
+        (self.status, Json(self.body)).into_response()
+    }
+}
+
+impl fmt::Display for AdminError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.body.message())
+    }
+}
+
+/// 带独立 HTTP 状态的管理端响应。
+pub struct AdminResponse<T: Serialize> {
+    status: StatusCode,
+    body: T,
+}
+
+impl<T: Serialize> AdminResponse<T> {
+    #[must_use]
+    pub fn new(status: StatusCode, body: T) -> Self {
+        Self { status, body }
+    }
+}
+
+impl<T: Serialize> IntoResponse for AdminResponse<T> {
+    fn into_response(self) -> Response {
+        (self.status, Json(self.body)).into_response()
+    }
+}
+
+/// 管理端响应信封。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminEnvelope<T> {
+    code: u32,
+    message: String,
+    data: T,
+}
+
+impl<T> AdminEnvelope<T> {
+    /// 构造稳定的成功响应。
+    #[must_use]
+    pub fn ok(data: T) -> Self {
+        Self {
+            code: ADMIN_OK_CODE,
+            message: ADMIN_OK_MESSAGE.to_owned(),
+            data,
+        }
+    }
+
+    /// 稳定业务码。
+    #[must_use]
+    pub const fn code(&self) -> u32 {
+        self.code
+    }
+
+    /// 稳定业务消息。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// 响应数据。
+    #[must_use]
+    pub const fn data(&self) -> &T {
+        &self.data
+    }
+
+    /// 取出响应数据。
+    #[must_use]
+    pub fn into_data(self) -> T {
+        self.data
+    }
+}
+
+/// 页码分页响应数据。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminPageData<T> {
+    items: Vec<T>,
+    page: PageMeta,
+}
+
+impl<T> AdminPageData<T> {
+    /// 组合查询 owner 返回的当前页数据与分页事实。
+    #[must_use]
+    pub const fn new(items: Vec<T>, page: PageMeta) -> Self {
+        Self { items, page }
+    }
+
+    /// 当前页记录。
+    #[must_use]
+    pub fn items(&self) -> &[T] {
+        &self.items
+    }
+
+    /// 分页元数据。
+    #[must_use]
+    pub const fn page(&self) -> PageMeta {
+        self.page
+    }
+
+    /// 拆分分页数据。
+    #[must_use]
+    pub fn into_parts(self) -> (Vec<T>, PageMeta) {
+        (self.items, self.page)
+    }
+}

backend/crates/gateway-api/src/health.rs

@@ -0,0 +1,86 @@
+//! `/healthz` 对 Core、Store 与 Host 关键 worker 健康事实的聚合。
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use axum::{extract::State, http::StatusCode};
+use futures::future::join_all;
+use gateway_core::health::{
+    HealthProbe, HealthState, WorkerHealthKey, WorkerHealthSnapshot, WorkerHealthSource,
+    WorkerRuntimeState,
+};
+use gateway_core::task::WorkerKind;
+
+use crate::ApiState;
+
+const HEALTH_CHECK_TIMEOUT: Duration = Duration::from_secs(2);
+
+#[derive(Clone)]
+pub(crate) struct HealthStatus {
+    probes: Arc<[Arc<dyn HealthProbe>]>,
+    workers: Arc<dyn WorkerHealthSource>,
+}
+
+impl HealthStatus {
+    #[must_use]
+    pub(crate) fn new(
+        probes: Vec<Arc<dyn HealthProbe>>,
+        workers: Arc<dyn WorkerHealthSource>,
+    ) -> Self {
+        Self {
+            probes: probes.into(),
+            workers,
+        }
+    }
+
+    pub(crate) async fn healthy(&self) -> bool {
+        if !self
+            .workers
+            .snapshot()
+            .iter()
+            .filter(|worker| worker_affects_healthz(worker))
+            .all(worker_is_healthy)
+        {
+            return false;
+        }
+        let checks = self.probes.iter().map(|probe| probe.check());
+        tokio::time::timeout(HEALTH_CHECK_TIMEOUT, join_all(checks))
+            .await
+            .is_ok_and(|states| {
+                states
+                    .into_iter()
+                    .all(|state| matches!(state, HealthState::Healthy))
+            })
+    }
+}
+
+pub(crate) async fn healthz(State(state): State<ApiState>) -> StatusCode {
+    if state.health().healthy().await {
+        StatusCode::NO_CONTENT
+    } else {
+        StatusCode::SERVICE_UNAVAILABLE
+    }
+}
+
+fn worker_affects_healthz(worker: &WorkerHealthSnapshot) -> bool {
+    let WorkerHealthKey::Task(id) = &worker.key else {
+        return false;
+    };
+    !matches!(
+        id.kind(),
+        WorkerKind::OAuthRefresh | WorkerKind::QuotaCatalogHealth
+    )
+}
+
+fn worker_is_healthy(worker: &WorkerHealthSnapshot) -> bool {
+    match worker.state {
+        WorkerRuntimeState::Disabled | WorkerRuntimeState::Standby => true,
+        WorkerRuntimeState::Running => worker.consecutive_failures == 0,
+        WorkerRuntimeState::AcquiringLease | WorkerRuntimeState::Idle => {
+            worker.consecutive_failures == 0 && worker.last_success_at.is_some()
+        }
+        WorkerRuntimeState::Starting
+        | WorkerRuntimeState::BackingOff
+        | WorkerRuntimeState::Stopped => false,
+    }
+}

backend/crates/gateway-api/src/lib.rs

@@ -0,0 +1,249 @@
+//! 客户端与管理端 HTTP 协议 adapter。
+//!
+//! 本 crate 只负责请求解码、Core/Admin 调用和 HTTP/WS/SSE delivery。
+
+use std::collections::BTreeSet;
+use std::path::{Path, PathBuf};
+use std::str::FromStr as _;
+use std::sync::Arc;
+use std::time::Duration;
+
+use axum::Router;
+use axum::http::{HeaderName, HeaderValue, Method, Request, StatusCode};
+use axum::routing::get;
+use gateway_admin::AdminServices;
+use gateway_core::engine::execution::ExecutionService;
+use gateway_core::health::{HealthProbe, WorkerHealthSource};
+use gateway_core::lifecycle::ConnectionLifecycle;
+use serde::Deserialize;
+use tower_http::cors::CorsLayer;
+use tower_http::request_id::{MakeRequestUuid, PropagateRequestIdLayer, SetRequestIdLayer};
+use tower_http::services::{ServeDir, ServeFile};
+use tower_http::timeout::TimeoutLayer;
+use tower_http::trace::TraceLayer;
+use url::Url;
+
+const WEB_DIST_ENV: &str = "CPR_WEB_DIST_DIR";
+
+use crate::health::HealthStatus;
+use crate::openai::service::OpenAiService;
+
+pub mod admin;
+mod health;
+pub mod openai;
+
+/// API-owned HTTP 与静态资源配置。
+#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct ApiConfig {
+    pub asset_directory: PathBuf,
+    pub cors_allowed_origins: Vec<String>,
+    pub request_timeout_seconds: Option<u64>,
+    pub request_id_header: String,
+}
+
+impl ApiConfig {
+    /// 解析静态资源相对路径并校验全部 HTTP 配置。
+    ///
+    /// # Errors
+    ///
+    /// 路径为空、origin/header 非法或 timeout 为零时返回脱敏错误。
+    pub fn resolve_and_validate(&mut self, source_dir: &Path) -> Result<(), ApiConfigError> {
+        match std::env::var(WEB_DIST_ENV) {
+            Ok(value) if value.trim().is_empty() => {
+                return Err(ApiConfigError::InvalidAssetDirectory);
+            }
+            Ok(value) => self.asset_directory = PathBuf::from(value),
+            Err(std::env::VarError::NotPresent) => {}
+            Err(std::env::VarError::NotUnicode(_)) => {
+                return Err(ApiConfigError::InvalidAssetDirectory);
+            }
+        }
+        if self.asset_directory.as_os_str().is_empty() {
+            return Err(ApiConfigError::InvalidAssetDirectory);
+        }
+        if self.asset_directory.is_relative() {
+            self.asset_directory = source_dir.join(&self.asset_directory);
+        }
+        if self.request_timeout_seconds == Some(0) {
+            return Err(ApiConfigError::InvalidRequestTimeout);
+        }
+        let header = HeaderName::from_str(&self.request_id_header)
+            .map_err(|_| ApiConfigError::InvalidRequestIdHeader)?;
+        self.request_id_header = header.as_str().to_owned();
+
+        let mut origins = Vec::with_capacity(self.cors_allowed_origins.len());
+        let mut unique = BTreeSet::new();
+        for origin in &self.cors_allowed_origins {
+            let origin = validate_origin(origin)?;
+            if !unique.insert(origin.clone()) {
+                return Err(ApiConfigError::DuplicateCorsOrigin);
+            }
+            origins.push(origin);
+        }
+        self.cors_allowed_origins = origins;
+        Ok(())
+    }
+}
+
+/// API 配置非法的稳定分类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum ApiConfigError {
+    #[error("API asset directory is invalid")]
+    InvalidAssetDirectory,
+    #[error("API CORS origin is invalid")]
+    InvalidCorsOrigin,
+    #[error("API CORS origin is duplicated")]
+    DuplicateCorsOrigin,
+    #[error("API request timeout is invalid")]
+    InvalidRequestTimeout,
+    #[error("API request ID header is invalid")]
+    InvalidRequestIdHeader,
+}
+
+/// 完成组装的唯一 API router。
+pub struct ApiBundle {
+    router: Router,
+}
+
+impl ApiBundle {
+    pub fn router(self) -> Router {
+        self.router
+    }
+}
+
+/// 组装客户端、管理端、健康检查和静态资源路由。
+pub fn initialize(
+    mut config: ApiConfig,
+    execution: Arc<dyn ExecutionService>,
+    admin: AdminServices,
+    probes: Vec<Arc<dyn HealthProbe>>,
+    worker_health: Arc<dyn WorkerHealthSource>,
+    lifecycle: Arc<dyn ConnectionLifecycle>,
+) -> Result<ApiBundle, ApiError> {
+    config
+        .resolve_and_validate(Path::new("."))
+        .map_err(ApiError::Config)?;
+    let request_id_header = HeaderName::from_str(&config.request_id_header)
+        .map_err(|_| ApiError::Config(ApiConfigError::InvalidRequestIdHeader))?;
+    let state = ApiState {
+        admin,
+        openai: OpenAiService::new(execution, lifecycle),
+        health: HealthStatus::new(probes, worker_health),
+    };
+    let index = config.asset_directory.join("index.html");
+    let mut router = Router::new()
+        .route("/healthz", get(health::healthz))
+        .merge(openai::router::router())
+        .merge(admin::router::<ApiState>())
+        .fallback_service(ServeDir::new(config.asset_directory).fallback(ServeFile::new(index)));
+    if !config.cors_allowed_origins.is_empty() {
+        let origins = config
+            .cors_allowed_origins
+            .iter()
+            .map(|origin| {
+                HeaderValue::from_str(origin)
+                    .map_err(|_| ApiError::Config(ApiConfigError::InvalidCorsOrigin))
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        // credentials 模式禁止通配 allow_headers；显式列出鉴权与内容协商头。
+        router = router.layer(
+            CorsLayer::new()
+                .allow_origin(origins)
+                .allow_methods([Method::GET, Method::POST])
+                .allow_headers([
+                    axum::http::header::AUTHORIZATION,
+                    axum::http::header::CONTENT_TYPE,
+                    HeaderName::from_static("x-api-key"),
+                    request_id_header.clone(),
+                ])
+                .allow_credentials(true),
+        );
+    }
+    if let Some(seconds) = config.request_timeout_seconds {
+        router = router.layer(TimeoutLayer::with_status_code(
+            StatusCode::REQUEST_TIMEOUT,
+            Duration::from_secs(seconds),
+        ));
+    }
+    // Trace 必须在 SetRequestId 内侧，span 才能捕获本服务生成的 request_id；
+    // 默认 DEBUG span 会被 info 日志过滤器丢弃，这里显式用 info_span。
+    let trace_layer = TraceLayer::new_for_http().make_span_with({
+        let request_id_header = request_id_header.clone();
+        move |request: &Request<_>| {
+            let request_id = request
+                .headers()
+                .get(&request_id_header)
+                .and_then(|value| value.to_str().ok())
+                .unwrap_or_default();
+            tracing::info_span!(
+                "request",
+                request_id = %request_id,
+                method = %request.method().as_str(),
+                uri = %request.uri().path(),
+            )
+        }
+    })
+    .on_request(|_request: &Request<_>, _span: &tracing::Span| {
+        tracing::info!(target: "request_trace", stage = "http.received", "HTTP request received");
+    })
+    .on_response(|response: &axum::http::Response<_>, latency: Duration, _span: &tracing::Span| {
+        tracing::info!(target: "request_trace", stage = "http.response", status = response.status().as_u16(),
+            headers_ms = latency.as_millis(), "HTTP response headers ready");
+    });
+    let router = router
+        .layer(PropagateRequestIdLayer::new(request_id_header.clone()))
+        .layer(trace_layer)
+        .layer(SetRequestIdLayer::new(request_id_header, MakeRequestUuid))
+        .with_state(state);
+    Ok(ApiBundle { router })
+}
+
+/// API 初始化失败的脱敏分类。
+#[derive(Debug, thiserror::Error)]
+pub enum ApiError {
+    #[error(transparent)]
+    Config(ApiConfigError),
+}
+
+#[derive(Clone)]
+pub(crate) struct ApiState {
+    admin: AdminServices,
+    openai: OpenAiService,
+    health: HealthStatus,
+}
+
+impl ApiState {
+    #[must_use]
+    pub(crate) const fn openai(&self) -> &OpenAiService {
+        &self.openai
+    }
+
+    #[must_use]
+    pub(crate) const fn health(&self) -> &HealthStatus {
+        &self.health
+    }
+}
+
+impl admin::AdminSessionState for ApiState {
+    fn admin_services(&self) -> &AdminServices {
+        &self.admin
+    }
+}
+
+fn validate_origin(raw: &str) -> Result<String, ApiConfigError> {
+    let url = Url::parse(raw).map_err(|_| ApiConfigError::InvalidCorsOrigin)?;
+    if !matches!(url.scheme(), "http" | "https")
+        || url.host_str().is_none()
+        || !url.username().is_empty()
+        || url.password().is_some()
+        || url.path() != "/"
+        || url.query().is_some()
+        || url.fragment().is_some()
+    {
+        return Err(ApiConfigError::InvalidCorsOrigin);
+    }
+    let origin = url.origin().ascii_serialization();
+    HeaderValue::from_str(&origin).map_err(|_| ApiConfigError::InvalidCorsOrigin)?;
+    Ok(origin)
+}

backend/crates/gateway-api/src/openai/auth.rs

@@ -0,0 +1,242 @@
+//! OpenAI 客户端协议的 Bearer API key 认证。
+
+use axum::{
+    http::{HeaderMap, header::AUTHORIZATION},
+    response::{IntoResponse, Response},
+};
+use gateway_core::engine::execution::AuthenticatedClient;
+use gateway_core::policy::{ClientVersionRejection, CodexClientKind, CodexClientVersion};
+
+use super::{
+    error::{
+        client_version_rejection_response, missing_client_api_key_response,
+        runtime_unavailable_response,
+    },
+    service::OpenAiService,
+};
+
+/// Client API key 鉴权失败原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientApiKeyAuthError {
+    /// 缺失 Authorization 头。
+    MissingAuthorization,
+    /// Authorization 头不是合法的 Bearer token。
+    MalformedAuthorization,
+    /// Bearer token 不是 client API key 格式。
+    InvalidKeyFormat,
+    /// Key 不存在、已禁用或 wire 格式无效。
+    InvalidKey,
+    /// RuntimeSnapshot 一致性保护暂停接收新请求。
+    RuntimeUnavailable,
+}
+
+/// Client API Key 或最低版本准入失败。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ClientAccessError {
+    Authentication(ClientApiKeyAuthError),
+    Version(ClientVersionRejection),
+}
+
+impl From<ClientApiKeyAuthError> for ClientAccessError {
+    fn from(error: ClientApiKeyAuthError) -> Self {
+        Self::Authentication(error)
+    }
+}
+
+impl From<ClientVersionRejection> for ClientAccessError {
+    fn from(error: ClientVersionRejection) -> Self {
+        Self::Version(error)
+    }
+}
+
+/// 从有界请求头中识别出的客户端及其可选合法版本。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct IdentifiedCodexClient {
+    kind: CodexClientKind,
+    version: Option<CodexClientVersion>,
+}
+
+impl IdentifiedCodexClient {
+    #[must_use]
+    pub const fn kind(&self) -> CodexClientKind {
+        self.kind
+    }
+
+    #[must_use]
+    pub const fn version(&self) -> Option<&CodexClientVersion> {
+        self.version.as_ref()
+    }
+}
+
+impl ClientApiKeyAuthError {
+    /// 返回可用于日志和指标的稳定失败原因。
+    #[must_use]
+    pub const fn reason(self) -> &'static str {
+        match self {
+            Self::MissingAuthorization => "missing_authorization",
+            Self::MalformedAuthorization => "malformed_authorization",
+            Self::InvalidKeyFormat => "invalid_key_format",
+            Self::InvalidKey => "invalid_key",
+            Self::RuntimeUnavailable => "runtime_unavailable",
+        }
+    }
+}
+
+/// 从请求头提取 Bearer Client API key。
+///
+/// # Errors
+///
+/// Header 缺失、Bearer 语法错误或不是网关 Client Key 前缀时返回稳定错误。
+pub fn bearer_client_api_key(headers: &HeaderMap) -> Result<&str, ClientApiKeyAuthError> {
+    let raw = headers
+        .get(AUTHORIZATION)
+        .ok_or(ClientApiKeyAuthError::MissingAuthorization)?
+        .to_str()
+        .map_err(|_| ClientApiKeyAuthError::MalformedAuthorization)?;
+    let token = raw
+        .strip_prefix("Bearer ")
+        .ok_or(ClientApiKeyAuthError::MalformedAuthorization)?
+        .trim();
+    if token.is_empty() {
+        return Err(ClientApiKeyAuthError::MalformedAuthorization);
+    }
+    if !token.starts_with("sk_") {
+        return Err(ClientApiKeyAuthError::InvalidKeyFormat);
+    }
+    Ok(token)
+}
+
+pub(crate) fn authenticate_client(
+    service: &OpenAiService,
+    headers: &HeaderMap,
+) -> Result<AuthenticatedClient, ClientAccessError> {
+    let key = bearer_client_api_key(headers)?;
+    let client = service.authenticate(key)?;
+    if let Some(identified) = identify_codex_client(headers) {
+        client
+            .snapshot()
+            .min_codex_client_versions()
+            .enforce(identified.kind(), identified.version())?;
+    }
+    Ok(client)
+}
+
+pub(crate) fn client_access_error_response(error: ClientAccessError) -> Response {
+    match error {
+        ClientAccessError::Authentication(error) => {
+            log_client_api_key_auth_failure(error);
+            if error == ClientApiKeyAuthError::RuntimeUnavailable {
+                runtime_unavailable_response().into_response()
+            } else {
+                missing_client_api_key_response().into_response()
+            }
+        }
+        ClientAccessError::Version(error) => {
+            tracing::info!(
+                client = error.kind().as_str(),
+                current_version = error.current().map(ToString::to_string),
+                min_version = %error.min(),
+                "Codex client version requirement rejected request"
+            );
+            client_version_rejection_response(&error).into_response()
+        }
+    }
+}
+
+/// Desktop 优先于其内嵌的 CLI/Core 标记；未知客户端保持兼容并返回 `None`。
+#[must_use]
+pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClient> {
+    const MAXIMUM_HEADER_LENGTH: usize = 4096;
+
+    let originator = bounded_ascii_header(headers, "originator", MAXIMUM_HEADER_LENGTH);
+    let user_agent = bounded_ascii_header(headers, "user-agent", MAXIMUM_HEADER_LENGTH);
+    let is_desktop = originator.is_some_and(|value| value.eq_ignore_ascii_case("Codex Desktop"))
+        || user_agent.is_some_and(|value| contains_ascii_case_insensitive(value, "Codex Desktop"));
+    if is_desktop {
+        let explicit_version = bounded_ascii_header(headers, "version", MAXIMUM_HEADER_LENGTH);
+        let version = match explicit_version {
+            Some(value) => CodexClientVersion::parse(value).ok(),
+            None => user_agent
+                .and_then(desktop_version_from_user_agent)
+                .and_then(|value| CodexClientVersion::parse(value).ok()),
+        };
+        return Some(IdentifiedCodexClient {
+            kind: CodexClientKind::Desktop,
+            version,
+        });
+    }
+
+    let user_agent = user_agent?;
+    for product in user_agent.split(|character: char| {
+        character.is_ascii_whitespace() || matches!(character, '(' | ')' | ';' | ',' | '[' | ']')
+    }) {
+        for prefix in ["codex_cli_rs", "codex-cli"] {
+            if product.eq_ignore_ascii_case(prefix) {
+                return Some(IdentifiedCodexClient {
+                    kind: CodexClientKind::Cli,
+                    version: None,
+                });
+            }
+            let Some((name, version)) = product.split_once('/') else {
+                continue;
+            };
+            if name.eq_ignore_ascii_case(prefix) {
+                return Some(IdentifiedCodexClient {
+                    kind: CodexClientKind::Cli,
+                    version: CodexClientVersion::parse(version).ok(),
+                });
+            }
+        }
+    }
+    None
+}
+
+fn bounded_ascii_header<'a>(
+    headers: &'a HeaderMap,
+    name: &'static str,
+    maximum_length: usize,
+) -> Option<&'a str> {
+    let value = headers.get(name)?.to_str().ok()?;
+    if !value.is_ascii() {
+        return None;
+    }
+    Some(&value[..value.len().min(maximum_length)])
+}
+
+fn desktop_version_from_user_agent(user_agent: &str) -> Option<&str> {
+    let marker = "Codex Desktop;";
+    let start = find_ascii_case_insensitive(user_agent, marker)? + marker.len();
+    let version = user_agent[start..]
+        .trim_start()
+        .split([')', ' ', ';', ','])
+        .next()?;
+    (!version.is_empty()).then_some(version)
+}
+
+fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool {
+    find_ascii_case_insensitive(haystack, needle).is_some()
+}
+
+fn find_ascii_case_insensitive(haystack: &str, needle: &str) -> Option<usize> {
+    haystack
+        .as_bytes()
+        .windows(needle.len())
+        .position(|window| window.eq_ignore_ascii_case(needle.as_bytes()))
+}
+
+fn log_client_api_key_auth_failure(error: ClientApiKeyAuthError) {
+    match error {
+        ClientApiKeyAuthError::RuntimeUnavailable => {
+            tracing::warn!(
+                auth_failure = error.reason(),
+                "Client API key authorization failed"
+            );
+        }
+        _ => {
+            tracing::info!(
+                auth_failure = error.reason(),
+                "Client API key authorization failed"
+            );
+        }
+    }
+}

backend/crates/gateway-api/src/openai/endpoint.rs

@@ -0,0 +1,124 @@
+//! OpenAI Provider 原生非流式 JSON 端点的公共交付边界。
+
+use axum::{
+    body::{Body, Bytes},
+    http::{HeaderName, HeaderValue, StatusCode, header::CONTENT_TYPE},
+    response::{IntoResponse, Response},
+};
+use gateway_core::engine::execution::StartedExecution;
+use gateway_core::event::{ProviderEvent, ProviderResponseHeader};
+
+use super::{
+    error::{engine_error_response, protocol_error_response},
+    responses::{PendingExecution, ProtocolError, ProtocolErrorBody},
+};
+
+/// 收集一个 Provider 原生 JSON 响应，并在 Core commit 后按原始 bytes 交付。
+pub(super) async fn collect_raw_json_response(started: StartedExecution) -> Response {
+    let mut execution = PendingExecution::new(started.session);
+    let Some(session) = execution.session_mut() else {
+        return invalid_upstream_response();
+    };
+    let events = match session.collect_uncommitted().await {
+        Ok(events) => events,
+        Err(error) => {
+            let response = engine_error_response(&error);
+            return execution.record_response_status(response).await;
+        }
+    };
+    let body = match raw_json_body(events) {
+        Some(body) => body,
+        None => {
+            let response = invalid_upstream_response();
+            let response = execution.record_response_status(response).await;
+            execution.cancel_and_finalize().await;
+            return response;
+        }
+    };
+    let status = session
+        .response_status_code()
+        .and_then(|status| StatusCode::from_u16(status).ok())
+        .filter(StatusCode::is_success)
+        .unwrap_or(StatusCode::OK);
+    let response_headers = session.response_headers().to_vec();
+    let response = json_body_response(body, status, &response_headers);
+    let Some(session) = execution.session_mut() else {
+        return invalid_upstream_response();
+    };
+    if let Err(error) = session.commit_downstream(Some(status.as_u16())).await {
+        execution.cancel_and_finalize().await;
+        let response = engine_error_response(&error);
+        return execution.record_response_status(response).await;
+    }
+    if !session.is_finalized() {
+        execution.cancel_and_finalize().await;
+        return invalid_upstream_response();
+    }
+    execution.disarm();
+    response
+}
+
+fn raw_json_body(events: Vec<ProviderEvent>) -> Option<Bytes> {
+    let mut body = None;
+    for event in events {
+        let (_, wire) = event.into_parts();
+        let Some(wire) = wire.filter(|wire| wire.protocol() == "openai") else {
+            continue;
+        };
+        let Some(raw) = wire.into_raw_json_body() else {
+            continue;
+        };
+        if body.replace(raw).is_some() {
+            return None;
+        }
+    }
+    body
+}
+
+fn json_body_response(
+    body: Bytes,
+    status: StatusCode,
+    response_headers: &[ProviderResponseHeader],
+) -> Response {
+    let mut response = Response::new(Body::from(body));
+    *response.status_mut() = status;
+    response
+        .headers_mut()
+        .insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+    apply_response_headers(response, response_headers)
+}
+
+fn apply_response_headers(
+    mut response: Response,
+    response_headers: &[ProviderResponseHeader],
+) -> Response {
+    let connection_options = super::responses::response_connection_options(response_headers);
+    for header in response_headers {
+        if !super::responses::response_header_is_forwardable(header.name(), &connection_options) {
+            continue;
+        }
+        let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
+            continue;
+        };
+        let Ok(value) = HeaderValue::from_bytes(header.value()) else {
+            continue;
+        };
+        response.headers_mut().append(name, value);
+    }
+    response
+}
+
+fn invalid_upstream_response() -> Response {
+    protocol_error_response(
+        StatusCode::BAD_GATEWAY,
+        ProtocolErrorBody {
+            error: ProtocolError {
+                kind: "server_error",
+                code: "invalid_upstream_response",
+                message: "The gateway could not forward the upstream JSON response.".to_owned(),
+                param: None,
+            },
+        },
+    )
+    .into_response()
+}

backend/crates/gateway-api/src/openai/error.rs

@@ -0,0 +1,259 @@
+//! OpenAI 客户端协议的稳定错误响应。
+
+use axum::{
+    Json,
+    body::Body,
+    http::{HeaderName, HeaderValue, StatusCode, header::CONTENT_TYPE},
+    response::{IntoResponse, Response},
+};
+use gateway_core::{
+    engine::EngineError,
+    error::{GatewayError, GatewayErrorKind},
+    policy::{ClientVersionRejection, CodexClientKind},
+};
+use serde_json::{Value, json};
+
+use super::responses::ProtocolErrorBody;
+
+/// OpenAI 风格错误响应。
+pub fn openai_error_response(
+    status: StatusCode,
+    message: &str,
+    error_type: &str,
+    code: &str,
+) -> (StatusCode, Json<Value>) {
+    (
+        status,
+        Json(json!({
+            "error": {
+                "message": message,
+                "type": error_type,
+                "code": code
+            }
+        })),
+    )
+}
+
+/// 严格协议 decoder/encoder 返回的安全错误 body。
+pub fn protocol_error_response(status: StatusCode, body: ProtocolErrorBody) -> Response {
+    (status, Json(body.into_value())).into_response()
+}
+
+/// 下游 Client API Key 无效。
+pub fn missing_client_api_key_response() -> (StatusCode, Json<Value>) {
+    openai_error_response(
+        StatusCode::UNAUTHORIZED,
+        "Missing or invalid API key",
+        "invalid_request_error",
+        "invalid_api_key",
+    )
+}
+
+/// RuntimeSnapshot 当前不允许接收新的配置依赖请求。
+pub fn runtime_unavailable_response() -> (StatusCode, Json<Value>) {
+    openai_error_response(
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Gateway runtime configuration is temporarily unavailable",
+        "server_error",
+        "runtime_configuration_unavailable",
+    )
+}
+
+/// 已识别 Codex 客户端不满足最低版本要求。
+pub fn client_version_rejection_response(
+    rejection: &ClientVersionRejection,
+) -> (StatusCode, Json<Value>) {
+    let client_label = match rejection.kind() {
+        CodexClientKind::Desktop => "Codex Desktop",
+        CodexClientKind::Cli => "Codex CLI",
+    };
+    let (message, code, current_version) = match rejection.current() {
+        Some(current) => (
+            format!(
+                "{client_label} {current} is below the minimum required version {}. Upgrade {client_label} and retry.",
+                rejection.min()
+            ),
+            "client_version_too_old",
+            Some(current.to_string()),
+        ),
+        None => (
+            format!(
+                "A valid {client_label} version is required. Upgrade to version {} or newer and retry.",
+                rejection.min()
+            ),
+            "client_version_unavailable",
+            None,
+        ),
+    };
+    (
+        StatusCode::UPGRADE_REQUIRED,
+        Json(json!({
+            "error": {
+                "message": message,
+                "type": "invalid_request_error",
+                "code": code,
+                "client": rejection.kind().as_str(),
+                "current_version": current_version,
+                "min_version": rejection.min().to_string()
+            }
+        })),
+    )
+}
+
+/// 对外模型不存在。
+pub fn model_not_found_response() -> (StatusCode, Json<Value>) {
+    openai_error_response(
+        StatusCode::NOT_FOUND,
+        "The requested model does not exist or is not available",
+        "invalid_request_error",
+        "model_not_found",
+    )
+}
+
+/// 将 core Engine 错误收敛为稳定 Gateway 分类。
+#[must_use]
+pub fn gateway_error_from_engine(error: &EngineError) -> GatewayError {
+    match error {
+        EngineError::Provider(error) => GatewayError::from_provider(error),
+        EngineError::Cancelled => {
+            GatewayError::new(GatewayErrorKind::Cancelled, "request was cancelled")
+        }
+        EngineError::Deadline => {
+            GatewayError::new(GatewayErrorKind::Timeout, "gateway request timed out")
+        }
+        EngineError::ProviderNotRegistered { .. } | EngineError::EmptyRoutingPlan => {
+            GatewayError::new(
+                GatewayErrorKind::NoAvailableProvider,
+                "no upstream provider is currently available for this request",
+            )
+        }
+        EngineError::Store(_)
+        | EngineError::ProviderMetadataMismatch
+        | EngineError::ContinuationPinMismatch
+        | EngineError::RequiredAccountMismatch
+        | EngineError::AccountOutsideClientScope
+        | EngineError::DownstreamCommitRequired
+        | EngineError::NoActiveAttempt
+        | EngineError::InvalidDeliveryState => {
+            GatewayError::new(GatewayErrorKind::Internal, "gateway execution failed")
+        }
+    }
+}
+
+/// Gateway 错误的 OpenAI HTTP 表达。
+pub fn gateway_error_response(error: &GatewayError) -> Response {
+    let (status, default_type, default_code) = gateway_error_contract(error.kind());
+    openai_error_response(
+        status,
+        error.client_message(),
+        error.client_error_type().unwrap_or(default_type),
+        error.client_error_code().unwrap_or(default_code),
+    )
+    .into_response()
+}
+
+/// 在下游尚未提交时优先交付 Provider 的原始 HTTP 失败响应。
+pub fn engine_error_response(error: &EngineError) -> Response {
+    if let EngineError::Provider(error) = error
+        && let Some(upstream) = error.client_visible_upstream_response()
+        && let Ok(status) = StatusCode::from_u16(upstream.status())
+    {
+        let mut response = Response::new(Body::from(upstream.body().clone()));
+        *response.status_mut() = status;
+        if let Some(content_type) = upstream.content_type()
+            && let Ok(content_type) = HeaderValue::from_bytes(content_type)
+        {
+            response.headers_mut().insert(CONTENT_TYPE, content_type);
+        }
+        for header in upstream.headers() {
+            let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
+                continue;
+            };
+            let Ok(value) = HeaderValue::from_bytes(header.value()) else {
+                continue;
+            };
+            response.headers_mut().append(name, value);
+        }
+        return response;
+    }
+    gateway_error_response(&gateway_error_from_engine(error))
+}
+
+/// Gateway 错误稳定映射，供 HTTP、SSE 和 WebSocket 共用。
+#[must_use]
+pub const fn gateway_error_contract(
+    kind: GatewayErrorKind,
+) -> (StatusCode, &'static str, &'static str) {
+    match kind {
+        GatewayErrorKind::InvalidRequest => (
+            StatusCode::BAD_REQUEST,
+            "invalid_request_error",
+            "invalid_request",
+        ),
+        GatewayErrorKind::Unsupported => (
+            StatusCode::BAD_REQUEST,
+            "invalid_request_error",
+            "unsupported_capability",
+        ),
+        GatewayErrorKind::Unauthorized => (
+            StatusCode::UNAUTHORIZED,
+            "invalid_request_error",
+            "invalid_api_key",
+        ),
+        GatewayErrorKind::PolicyDenied => (
+            StatusCode::FORBIDDEN,
+            "invalid_request_error",
+            "policy_denied",
+        ),
+        GatewayErrorKind::ModelNotFound => (
+            StatusCode::NOT_FOUND,
+            "invalid_request_error",
+            "model_not_found",
+        ),
+        GatewayErrorKind::NoAvailableProvider => (
+            StatusCode::SERVICE_UNAVAILABLE,
+            "server_error",
+            "no_available_provider",
+        ),
+        GatewayErrorKind::AccountCapacityUnavailable => (
+            StatusCode::SERVICE_UNAVAILABLE,
+            "server_error",
+            "account_capacity_unavailable",
+        ),
+        GatewayErrorKind::ProviderInfrastructureUnavailable => (
+            StatusCode::SERVICE_UNAVAILABLE,
+            "server_error",
+            "provider_infrastructure_unavailable",
+        ),
+        GatewayErrorKind::RateLimited => (
+            StatusCode::TOO_MANY_REQUESTS,
+            "rate_limit_error",
+            "rate_limit_exceeded",
+        ),
+        GatewayErrorKind::UpstreamUnavailable => (
+            StatusCode::BAD_GATEWAY,
+            "server_error",
+            "upstream_unavailable",
+        ),
+        GatewayErrorKind::Timeout => (
+            StatusCode::GATEWAY_TIMEOUT,
+            "server_error",
+            "request_timeout",
+        ),
+        GatewayErrorKind::Cancelled => (
+            StatusCode::REQUEST_TIMEOUT,
+            "server_error",
+            "request_cancelled",
+        ),
+        GatewayErrorKind::Internal => (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "server_error",
+            "internal_error",
+        ),
+        _ => (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "server_error",
+            "internal_error",
+        ),
+    }
+}

backend/crates/gateway-api/src/openai/images/http.rs

@@ -0,0 +1,119 @@
+//! Codex Images 非流式 HTTP adapter。
+
+use std::net::SocketAddr;
+
+use axum::{
+    body::Bytes,
+    extract::{Extension, State, connect_info::ConnectInfo},
+    http::HeaderMap,
+    response::Response,
+};
+use gateway_core::error::{GatewayError, GatewayErrorKind};
+use gateway_core::operation::{ImageRequest, ImageRequestKind, Operation, RawJsonPayload};
+use serde_json::Value;
+
+use crate::ApiState;
+use crate::openai::{
+    auth::{authenticate_client, client_access_error_response},
+    endpoint::collect_raw_json_response,
+    error::gateway_error_response,
+    responses::{OpenAiRequestHeaders, request_client_context},
+};
+
+const OPENAI_PROTOCOL: &str = "openai";
+const IMAGE_TURN_ID_CONTEXT_KEY: &str = "image_turn_id";
+
+/// `POST /v1/images/generations`。
+pub(crate) async fn image_generations(
+    State(state): State<ApiState>,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Response {
+    handle_image_request(
+        state,
+        connect_info,
+        headers,
+        body,
+        ImageRequestKind::Generation,
+        "/v1/images/generations",
+    )
+    .await
+}
+
+/// `POST /v1/images/edits`。
+pub(crate) async fn image_edits(
+    State(state): State<ApiState>,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Response {
+    handle_image_request(
+        state,
+        connect_info,
+        headers,
+        body,
+        ImageRequestKind::Edit,
+        "/v1/images/edits",
+    )
+    .await
+}
+
+async fn handle_image_request(
+    state: ApiState,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    body: Bytes,
+    kind: ImageRequestKind,
+    endpoint: &'static str,
+) -> Response {
+    let service = state.openai();
+    let client = match authenticate_client(service, &headers) {
+        Ok(client) => client,
+        Err(error) => return client_access_error_response(error),
+    };
+    let (client_ip, user_agent) = request_client_context(
+        &headers,
+        connect_info.map(|Extension(ConnectInfo(address))| address),
+    );
+    let operation = match image_operation(body, &headers, kind) {
+        Ok(operation) => operation,
+        Err(error) => return gateway_error_response(&error),
+    };
+    let started = match service
+        .start_provider_endpoint(client, operation, client_ip, user_agent, endpoint)
+        .await
+    {
+        Ok(started) => started,
+        Err(error) => return gateway_error_response(&error),
+    };
+    collect_raw_json_response(started).await
+}
+
+fn image_operation(
+    body: Bytes,
+    headers: &HeaderMap,
+    kind: ImageRequestKind,
+) -> Result<Operation, GatewayError> {
+    let mut context = OpenAiRequestHeaders::from_headers(headers).session_context();
+    if let Some(turn_id) = headers
+        .get("x-codex-image-turn-id")
+        .and_then(|value| value.to_str().ok())
+    {
+        context.insert(
+            IMAGE_TURN_ID_CONTEXT_KEY.to_owned(),
+            Value::String(turn_id.to_owned()),
+        );
+    }
+    let payload = RawJsonPayload::new(OPENAI_PROTOCOL, body)
+        .map_err(|_| {
+            GatewayError::new(
+                GatewayErrorKind::Internal,
+                "OpenAI protocol identifier is invalid",
+            )
+        })?
+        .with_context(context);
+    Ok(Operation::GenerateImage(ImageRequest::from_raw_json(
+        kind, payload,
+    )))
+}

backend/crates/gateway-api/src/openai/images/mod.rs

@@ -0,0 +1,5 @@
+//! OpenAI/Codex Images JSON 透明 adapter。
+
+mod http;
+
+pub(crate) use http::{image_edits, image_generations};

backend/crates/gateway-api/src/openai/mod.rs

@@ -0,0 +1,11 @@
+//! OpenAI 客户端协议 adapter。
+
+pub mod auth;
+mod endpoint;
+pub mod error;
+pub mod images;
+pub mod models;
+pub mod responses;
+pub mod router;
+pub mod search;
+pub(crate) mod service;