chore: bump version to 3.2.9

Co-authored-by: Codex <noreply@openai.com>
fix(openai): align OAuth token refresh
2026-11-07 08:05:32 +00:00 · 2026-08-17 11:38:49 +08:00 · 2026-08-17 11:14:03 +08:00 · 2026-08-16 13:28:28 +08:00 · 2026-08-15 23:31:04 +08:00 · 2026-08-15 20:38:48 +08:00
488 changed files with 68749 additions and 28515 deletions
@@ -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:
@@ -55,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

@@ -76,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@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
+        uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
        with:
          sarif_file: trivy-results.sarif
          category: runtime-container
@@ -106,7 +106,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

@@ -157,7 +157,7 @@ jobs:
          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

@@ -32,7 +32,7 @@ jobs:

      - 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:
@@ -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:
@@ -43,14 +40,14 @@ jobs:
      - name: Checkout
        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"
@@ -188,9 +185,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
@@ -253,9 +250,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
@@ -378,7 +375,7 @@ jobs:
          PY

      - name: Generate release asset provenance
-        uses: actions/attest@f7c74d28b9d84cb8768d0b8ca14a4bac6ef463e6 # v4.2.0
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: dist/release/*

@@ -454,7 +451,7 @@ jobs:
        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0

      - name: Login to GHCR
-        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
@@ -471,8 +468,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: |
@@ -525,7 +525,7 @@ jobs:
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2

      - name: Login to GHCR
-        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
@@ -584,7 +584,7 @@ jobs:
          echo "digest=${digest}" >> "$GITHUB_OUTPUT"

      - name: Generate container provenance attestation
-        uses: actions/attest@f7c74d28b9d84cb8768d0b8ca14a4bac6ef463e6 # v4.2.0
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          subject-digest: ${{ steps.manifest.outputs.digest }}
@@ -626,7 +626,7 @@ jobs:
          make_latest: ${{ needs.release-info.outputs.prerelease == 'true' && 'false' || 'true' }}
          body: |
            > [!WARNING]
-            > **Upgrading across major versions?** Database schema and configuration are only compatible within a major version, and the one-click self-update refuses cross-major targets (releases before 3.0 lack this gate — do not use their built-in update to reach a newer major). Deploy the new major fresh (new `.runtime/` data directory) and re-import or re-authorize provider accounts and client keys. See the [upgrade notes](https://github.com/${{ github.repository }}/blob/main/deploy/README.md#镜像升级与源码构建).
+            > **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

@@ -31,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

@@ -52,7 +52,7 @@ jobs:
          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

@@ -35,6 +35,7 @@ Thumbs.db
 /.codex-ws-audit/
 /.agents/
 /.reasonix/
+/.claude
 /.worktrees/
 /worktrees/
 /.cargo/
@@ -21,15 +21,16 @@

 ## 能力

-| 领域     | 实现                                                                        |
-| -------- | --------------------------------------------------------------------------- |
-| 协议     | OpenAI Responses JSON、SSE、WebSocket 与模型目录                             |
-| Provider | 固定 OpenAI、xAI 两个 Provider；各自管理 OAuth、账号、额度与模型目录          |
-| 路由     | Client Key 绑定 Provider、全局模型映射、会话亲和与同 Provider 安全 fallback   |
-| 透明边界 | OpenAI SSE 与 WebSocket 均原样转发上游字节；xAI 在 `providers/xai` 内做 Grok 与 Responses 协议转换 |
-| 延续     | OpenAI native/replay continuation；xAI 使用客户端提交的完整历史                |
-| 管理     | Client Key、账号、模型目录、设置、观测、系统更新与 OAuth                       |
-| 计量     | 模型请求 Token、费用、延迟、账号与 Provider 归因                               |
+| 领域     | 实现                                                                                                  |
+| -------- | ----------------------------------------------------------------------------------------------------- |
+| 协议     | OpenAI Responses JSON、SSE、WebSocket 与模型目录                                                       |
+| Provider | 固定 OpenAI、xAI 两个 Provider；各自管理 OAuth、账号、额度与模型目录                                    |
+| 路由     | Client Key 绑定 Provider、全局模型映射、会话亲和与同 Provider 安全 fallback                             |
+| 透明边界 | OpenAI 请求保留未知字段和字段顺序，SSE 与 WebSocket 原样转发业务字节；xAI 在 Provider 内做协议转换          |
+| 延续     | OpenAI native/replay continuation；xAI 使用客户端提交的完整历史                                          |
+| 账号     | 导入、OAuth、credential 刷新、主动额度刷新，以及正常响应中的被动额度/状态观测                              |
+| 管理     | Client Key、账号、模型目录、设置、观测、系统更新与 OAuth                                                 |
+| 计量     | 模型请求 Token、费用、延迟、账号与 Provider 归因，并记录响应确认的实际 `service_tier`                      |

 ## 快速开始

@@ -93,6 +94,11 @@ curl -i http://127.0.0.1:8080/healthz
 3. 按需配置客户端模型到上游模型的全局映射；未命中映射的模型名原样透传。
 4. 创建 `sk_...` Client Key，绑定 `openai` 或 `xai`，并设置速率与并发限制。

+OpenAI 账号导入和首次 OAuth 创建在 credential 提交后会立即尝试一次额度观测；额度接口临时失败不会
+回滚已提交的账号。Free、K12 等套餐共用同一套额度与状态转换逻辑，套餐字段只作为账号事实并隔离
+对应的模型目录 cache。credential 刷新、额度刷新和正常请求中的被动额度观测是三条独立链路，详见
+[账号接口](docs/api.md#5-账号)。
+
 > [!IMPORTANT]
 > xAI 使用 OAuth session，不支持把 xAI API Key 作为上游 credential。

@@ -145,7 +151,7 @@ curl http://127.0.0.1:8080/v1/responses \
 ## 运维

 ```bash
-# 升级
+# 实例升级
 docker compose -f deploy/compose.yaml pull codex-proxy-rs
 docker compose -f deploy/compose.yaml up -d --no-build

@@ -162,10 +168,8 @@ docker compose -f deploy/compose.yaml up -d
 > 运行状态。

 > [!WARNING]
-> 跨大版本不是原地升级：数据库 schema 与配置只在同一大版本内兼容，内置一键自更新
-> 会拒绝跨大版本目标（3.0 之前的旧版没有这道门禁，不要用旧版界面的一键更新跨大版本）。
-> 升级到新的大版本需要全新部署（全新 `.runtime/` 数据目录），并重新导入或重新授权
-> Provider 账号与客户端 Key。
+> 不支持跨大版本在线升级。升级到新的大版本时，请使用全新的 `.runtime/` 数据目录重新部署，
+> 并重新导入或重新授权 Provider 账号与客户端 Key。

 Compose 默认只绑定 `127.0.0.1`。公网接入应使用 HTTPS 反向代理，转发 WebSocket
 upgrade 与真实客户端 IP；不要暴露 PostgreSQL 或 Redis。
@@ -178,8 +182,10 @@ upgrade 与真实客户端 IP；不要暴露 PostgreSQL 或 Redis。
 release/publish <version>
 ```

-脚本会更新 `release/version.yaml`、创建约定提交与带注释的 `v<version>` tag，并原子推送分支和 tag。
-不要手工修改版本后单独打 tag。
+脚本依赖已登录的 GitHub CLI（`gh auth login`）。它会更新 `release/version.yaml`、创建约定提交与带
+注释的 `v<version>` tag，原子推送分支和 tag，再从发布分支触发 Release 构建，使构建缓存可以跨版本
+复用。不要手工修改版本后单独打 tag。该脚本不会登录服务器，也不会改变任何运行实例；源码提交、
+仓库发版和实例升级是三个独立状态。

 ## 文档

@@ -25,6 +25,7 @@ tokio = { version = "1.52.3", default-features = false, features = ["rt-multi-th

 [dev-dependencies]
 config = { version = "0.15.23", default-features = false, features = ["yaml"] }
+serde_json = "1"
 syn = { version = "3.0.3", features = ["full"] }
 tempfile = "3.27.0"

@@ -72,7 +72,7 @@ pub async fn run() -> Result<(), BootstrapError> {
    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 admin = gateway_admin::initialize(
+    let mut admin = gateway_admin::initialize(
        admin,
        store.admin_ports(),
        vec![openai.admin_provider(), xai.admin_provider()],
@@ -99,6 +99,7 @@ pub async fn run() -> Result<(), BootstrapError> {
    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?;
@@ -1,6 +1,9 @@
 use std::{env, error::Error, io};

+use provider_openai::transport::tls::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") => {
@@ -82,6 +82,91 @@ fn gateway_admin_stays_free_of_infrastructure_dependencies() {
    );
 }

+/// 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"),
+];
+
+/// 冻结的 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 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;
+            }
+            let is_runtime_edge = dependency["dep_kinds"]
+                .as_array()
+                .map(|kinds| {
+                    kinds
+                        .iter()
+                        .any(|kind| kind["kind"].as_str() == Some("normal"))
+                })
+                .unwrap_or(true);
+            if is_runtime_edge {
+                actual.push((name.to_owned(), dep_name.to_owned()));
+            }
+        }
+    }
+
+    let mut expected: Vec<(String, String)> = ALLOWED_INTERNAL_EDGES
+        .iter()
+        .map(|(from, to)| ((*from).to_owned(), (*to).to_owned()))
+        .collect();
+    actual.sort();
+    expected.sort();
+
+    assert_eq!(
+        actual, expected,
+        "workspace internal dependency edges diverged from the frozen DAG"
+    );
+}
+
 #[test]
 fn production_sources_do_not_host_tests() {
    for member in WORKSPACE_MEMBERS {
@@ -107,6 +192,20 @@ fn backend_root() -> PathBuf {
        .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"))
@@ -134,8 +134,11 @@ fn config_loader_should_reject_removed_fingerprint_section() {
 }

 #[test]
-fn config_loader_should_reject_invalid_codex_core_version() {
-    assert_rejected(valid_config().replace("codex_version: '0.145.0'", "codex_version: 'latest'"));
+fn config_loader_should_reject_invalid_codex_cli_version() {
+    assert_rejected(valid_config().replace(
+        "codex_version: '0.147.0-alpha.6.6'",
+        "codex_version: 'latest'",
+    ));
 }

 #[test]
@@ -154,7 +157,7 @@ fn config_loader_should_reject_zero_server_port() {

 #[test]
 fn config_loader_should_reject_invalid_desktop_profile_fields() {
-    assert_rejected(valid_config().replace("desktop_build: '5828'", "desktop_build: 'build'"));
+    assert_rejected(valid_config().replace("desktop_build: '6415'", "desktop_build: 'build'"));
 }

 fn assert_rejected(config: String) {
@@ -26,9 +26,14 @@ 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"] }

 [dev-dependencies]
-serde_json = { version = "1.0.150", features = ["preserve_order"] }
+serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
+sha2 = "0.11"
+tempfile = "3"
 tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt"] }

 [lints]
@@ -0,0 +1,4 @@
+//! 备份纯策略与 Worker 任务。
+
+pub mod policy;
+pub mod task;
@@ -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 计划备份中决定纳入删除流程的记录。
+///
+/// 规则（`docs/s3-backup-design-audit.md` §4.4）：
+/// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理。
+/// - 自动计划备份满足任一启用阈值即可进入删除。
+/// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）。
+/// - 手动备份不受自动阈值影响；无 TTL，仅由管理员手动删除。
+#[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
+}
@@ -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::{
+    engine::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())
+}
@@ -2,23 +2,28 @@
 //!
 //! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现。

-use std::{fmt, path::Path, sync::Arc};
+use std::{fmt, path::Path, sync::Arc, time::Duration};

 use gateway_core::{
    engine::probe::AccountProbe,
    routing::{ProviderKind, snapshot::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::{
-    accounts::AccountsService, auth::AuthService, client_keys::ClientKeyService,
-    observability::ObservabilityService, openai::OpenAiService, settings::SettingsService,
-    system::SystemService, xai::XaiService,
+    account_groups::AccountGroupService, accounts::AccountsService, auth::AuthService,
+    backup::BackupService, client_keys::ClientKeyService, observability::ObservabilityService,
+    openai::OpenAiService, settings::SettingsService, system::SystemService, xai::XaiService,
 };

 use model::{AdminError, AdminErrorKind};
@@ -28,10 +33,10 @@ use ports::{
    system::SystemOperations,
 };
 use use_case::{
-    accounts::DefaultAccountsService, auth::DefaultAuthService,
-    client_keys::DefaultClientKeyService, observability::DefaultObservabilityService,
-    openai::DefaultOpenAiService, settings::DefaultSettingsService, system::DefaultSystemService,
-    xai::DefaultXaiService,
+    account_groups::DefaultAccountGroupService, accounts::DefaultAccountsService,
+    auth::DefaultAuthService, backup::DefaultBackupService, client_keys::DefaultClientKeyService,
+    observability::DefaultObservabilityService, openai::DefaultOpenAiService,
+    settings::DefaultSettingsService, system::DefaultSystemService, xai::DefaultXaiService,
 };

 const OPENAI_PROVIDER_KIND: &str = "openai";
@@ -48,6 +53,8 @@ const WEAK_INITIAL_PASSWORDS: &[&str] = &[
    "codex-proxy-rs",
 ];

+const BACKUP_WORKER_OWNER: &str = "backup";
+
 /// 只用于首次幂等创建默认管理员的启动密码。
 #[derive(Clone, Deserialize)]
 #[serde(transparent)]
@@ -140,12 +147,14 @@ pub enum AdminConfigError {
 pub struct AdminServices {
    auth: Arc<dyn AuthService>,
    accounts: Arc<dyn AccountsService>,
+    account_groups: Arc<dyn AccountGroupService>,
    client_keys: Arc<dyn ClientKeyService>,
    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 {
@@ -159,6 +168,11 @@ impl AdminServices {
        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()
@@ -188,11 +202,17 @@ impl AdminServices {
    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 {
@@ -200,6 +220,11 @@ impl AdminBundle {
    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 注册表并完成默认管理员幂等初始化。
@@ -236,14 +261,29 @@ pub async fn initialize(

    let accounts = Arc::new(DefaultAccountsService::new(
        store.accounts(),
-        store.settings(),
        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(),
+            snapshot.clone(),
+        )),
        client_keys: Arc::new(DefaultClientKeyService::new(
            store.client_keys(),
            snapshot.clone(),
@@ -268,8 +308,32 @@ pub async fn initialize(
            store.accounts(),
            snapshot.clone(),
        )),
+        backups,
    };
-    Ok(AdminBundle { services })
+    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("Backup worker id is invalid"))?;
+    let restart = DaemonRestartPolicy::try_new(Duration::from_secs(1), Duration::from_secs(60))
+        .map_err(|_| AdminError::internal("Backup worker restart policy is invalid"))?;
+    let registration = WorkerRegistration::try_new(
+        id,
+        WorkerRunnable::Daemon {
+            restart,
+            task: Box::new(task),
+        },
+    )
+    .map_err(|_| AdminError::internal("Backup worker registration is invalid"))?;
+    Ok(vec![WorkerContribution::Registration(registration)])
 }

 fn provider_kind(value: &'static str) -> Result<ProviderKind, AdminError> {
@@ -0,0 +1,142 @@
+//! Provider-neutral account group commands and projections.
+
+use std::collections::BTreeMap;
+
+use chrono::{DateTime, Utc};
+use gateway_core::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,
+    pub total_usd: DecimalAmount,
+}
+
+/// 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>,
+}
@@ -7,20 +7,13 @@ use futures::Stream;

 use gateway_core::routing::ProviderKind;

-use super::{PageSize, Revision, observability::TimeRange};
+use super::{PageSize, Revision, account_groups::AccountGroupRef, observability::TimeRange};

-/// Provider 账号当前可用性；权威定义与字符串编解码在 gateway-core，此处仅复用。
-pub use gateway_core::engine::credential::AccountAvailability;
-
-/// 管理页使用的归一化账号状态。
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum AccountStatus {
-    Active,
-    Expired,
-    QuotaExhausted,
-    Disabled,
-    Banned,
-}
+pub use gateway_core::engine::credential::{
+    AccountConcurrencyLimit, AccountErrorReason, AccountStatus, AccountStatusFacts,
+    AccountStatusProjection, AccountWeight, CredentialState, QuotaAccessState, QuotaEvidence,
+    QuotaState, resolve_account_status,
+};

 /// 账号列表排序字段。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -53,19 +46,28 @@ 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>,
 }

+/// 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: String,
+    pub upstream_user_id: Option<String>,
    pub upstream_account_id: Option<String>,
    pub plan_type: Option<String>,
    pub authentication_kind: String,
@@ -74,11 +76,13 @@ pub struct AccountRecord {
    pub access_token_expires_at: Option<DateTime<Utc>>,
    pub next_refresh_at: Option<DateTime<Utc>>,
    pub enabled: bool,
-    pub availability: AccountAvailability,
-    pub availability_reason: Option<String>,
-    pub cooldown_until: Option<DateTime<Utc>>,
-    pub availability_observed_at: DateTime<Utc>,
-    pub quota_observed_at: Option<DateTime<Utc>>,
+    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>,
 }
@@ -163,25 +167,63 @@ pub struct AccountUsageWindowResult {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountPage {
    pub config_revision: Revision,
-    pub items: Vec<AccountRecord>,
+    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 active: u64,
+    pub normal: u64,
    pub quota_exhausted: u64,
-    pub unavailable: u64,
+    pub rate_limited: u64,
+    pub disabled: u64,
+    pub error: u64,
 }

-/// 账号启停写入命令。
+/// 账号可编辑事实的一次性替换命令。
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SetAccountEnabled {
+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::engine::credential::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::engine::credential::ProviderAccountId>,
 }

 /// 账号批量删除命令。
@@ -205,14 +247,14 @@ pub enum AccountConnectionTestEvent {
    Content {
        text: String,
    },
-    Completed {
-        account_status: AccountStatus,
-    },
+    Completed,
    Failed {
        message: String,
        provider_error_code: Option<String>,
        provider_error_type: Option<String>,
-        account_status: AccountStatus,
+        upstream_status: Option<u16>,
+        upstream_content_type: Option<String>,
+        upstream_body: Option<String>,
    },
 }

@@ -0,0 +1,566 @@
+//! 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 {
+    /// 配置或参数非法。
+    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";
+}
+
+/// 构建对象 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,
+    })
+}
@@ -6,10 +6,10 @@ use chrono::{DateTime, Utc};

 use gateway_core::{
    policy::{ClientApiKeyId, RateLimits},
-    routing::ProviderKind,
+    routing::{AccountGroupId, ProviderKind},
 };

-use super::{AdminModelError, Revision};
+use super::{AdminModelError, Revision, account_groups::AccountGroupRef};

 /// Client Key 列表保持旧 HTTP 合同允许的完整非零 `u16` 页大小。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -88,7 +88,8 @@ pub struct ClientKeyRecord {
    pub id: ClientApiKeyId,
    pub name: String,
    pub label: Option<String>,
-    pub provider_kind: ProviderKind,
+    pub groups: Vec<AccountGroupRef>,
+    pub provider_kinds: Vec<ProviderKind>,
    pub prefix: String,
    pub enabled: bool,
    pub limits: RateLimits,
@@ -143,7 +144,7 @@ impl fmt::Debug for ClientKeySecret {
 pub struct CreateClientKey {
    pub name: String,
    pub label: Option<String>,
-    pub provider_kind: ProviderKind,
+    pub group_ids: Vec<AccountGroupId>,
    pub limits: RateLimits,
 }

@@ -153,7 +154,7 @@ pub struct NewClientKey {
    pub id: ClientApiKeyId,
    pub name: String,
    pub label: Option<String>,
-    pub provider_kind: ProviderKind,
+    pub group_ids: Vec<AccountGroupId>,
    pub limits: RateLimits,
    pub plaintext: String,
 }
@@ -164,7 +165,7 @@ impl fmt::Debug for NewClientKey {
            .debug_struct("NewClientKey")
            .field("id", &self.id)
            .field("name", &self.name)
-            .field("provider_kind", &self.provider_kind)
+            .field("group_ids", &self.group_ids)
            .field("plaintext", &"[REDACTED]")
            .finish_non_exhaustive()
    }
@@ -176,7 +177,7 @@ pub struct UpdateClientKey {
    pub id: ClientApiKeyId,
    pub name: String,
    pub label: Option<String>,
-    pub provider_kind: ProviderKind,
+    pub group_ids: Vec<AccountGroupId>,
    pub limits: RateLimits,
 }

@@ -2,8 +2,10 @@

 use std::num::{NonZeroU16, NonZeroU64};

+pub mod account_groups;
 pub mod accounts;
 pub mod auth;
+pub mod backup;
 pub mod client_keys;
 pub mod observability;
 pub mod provider_credentials;
@@ -50,6 +52,11 @@ impl AdminError {
        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)
@@ -60,6 +67,11 @@ impl AdminError {
        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 unavailable(message: impl Into<String>) -> Self {
        Self::new(AdminErrorKind::Unavailable, message)
@@ -204,42 +204,22 @@ impl DecimalAmount {
    /// 精确相加两个 `numeric(20,10)` 金额。
    #[must_use]
    pub fn checked_add(&self, other: &Self) -> Option<Self> {
-        let sum = scaled_amount(&self.0)?.checked_add(scaled_amount(&other.0)?)?;
-        Self::from_scaled(sum)
+        Self::from_decimal(self.to_decimal()?.checked_add(other.to_decimal()?)?)
    }

    /// 将金额按非零请求数均分，保留最多十位小数。
    #[must_use]
    pub fn checked_div_u64(&self, divisor: u64) -> Option<Self> {
-        let divisor = u128::from(divisor);
-        (divisor != 0)
-            .then(|| scaled_amount(&self.0)?.checked_div(divisor))
-            .flatten()
-            .and_then(Self::from_scaled)
+        Self::from_decimal(self.to_decimal()?.checked_div_u64(divisor)?)
    }

-    fn from_scaled(value: u128) -> Option<Self> {
-        if value >= 10_u128.pow(20) {
-            return None;
-        }
-        let whole = value / 10_u128.pow(10);
-        let fraction = value % 10_u128.pow(10);
-        let value = if fraction == 0 {
-            whole.to_string()
-        } else {
-            format!("{whole}.{fraction:010}")
-                .trim_end_matches('0')
-                .to_owned()
-        };
-        Some(Self(value))
+    fn to_decimal(&self) -> Option<gateway_core::accounting::Decimal> {
+        self.0.parse().ok()
    }
-}

-fn scaled_amount(value: &str) -> Option<u128> {
-    let (whole, fraction) = value.split_once('.').unwrap_or((value, ""));
-    let whole = whole.parse::<u128>().ok()?;
-    let fraction = format!("{fraction:0<10}").parse::<u128>().ok()?;
-    whole.checked_mul(10_u128.pow(10))?.checked_add(fraction)
+    fn from_decimal(value: gateway_core::accounting::Decimal) -> Option<Self> {
+        Some(Self(value.canonical()))
+    }
 }

 impl FromStr for DecimalAmount {
@@ -330,6 +310,7 @@ pub struct LatencyPercentiles {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderBillingInput {
    pub upstream_model_id: String,
+    pub service_tier: Option<String>,
    pub input_tokens: Option<u64>,
    pub output_tokens: Option<u64>,
    pub cached_tokens: Option<u64>,
@@ -345,6 +326,7 @@ pub struct UsageCalculatedBillingFact {
    pub bucket_start: DateTime<Utc>,
    pub provider_kind: String,
    pub upstream_model_id: String,
+    pub service_tier: Option<String>,
    pub input_tokens: Option<u64>,
    pub output_tokens: Option<u64>,
    pub cached_tokens: Option<u64>,
@@ -457,18 +439,15 @@ pub struct RequestMetricPoint {
    pub costs: Vec<CurrencyCost>,
 }

-/// 账号池容量统计。
+/// 账号池的统一五态统计。
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct AccountPoolMetrics {
    pub total: u64,
-    pub enabled: u64,
-    pub unavailable: u64,
-    pub active: u64,
-    pub expired: u64,
+    pub normal: u64,
    pub quota_exhausted: u64,
-    pub refreshing: Option<u64>,
+    pub rate_limited: u64,
    pub disabled: u64,
-    pub banned: u64,
+    pub error: u64,
 }

 /// Dashboard 中一个账号的模型级用量事实。
@@ -499,7 +478,7 @@ pub struct DashboardAccountRequestBucket {
    pub request_count: u64,
 }

-/// Dashboard 中一个账号的完整用量与公共状态事实。
+/// Dashboard 中一个账号的完整用量事实。
 #[derive(Debug, Clone, PartialEq)]
 pub struct DashboardAccountUsage {
    pub account_id: String,
@@ -508,8 +487,6 @@ pub struct DashboardAccountUsage {
    pub name: String,
    pub email: Option<String>,
    pub plan_type: Option<String>,
-    pub enabled: bool,
-    pub availability: String,
    pub request_count: u64,
    pub success_count: u64,
    pub input_tokens: Option<u64>,
@@ -536,18 +513,31 @@ pub struct DashboardAccountUsage {
 /// Dashboard 当前账号池的可重建运行时槽位事实。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct DashboardRuntimeSlots {
-    /// 与持久账号池指标相同谓词下可参与调度的账号数。
-    pub active_accounts: u64,
+    /// 继承运行参数默认并发上限的可调度账号数。
+    pub inherited_accounts: u64,
+    /// 已配置账号级并发上限的可调度账号槽位总数。
+    pub overridden_slots: u64,
    /// Redis 可用时的实时 in-flight 槽位总数；不可用时为 `None`。
    pub used_slots: Option<u64>,
 }

-/// 仪表盘所需的公共观测事实。
+/// 仪表盘卡片脚注展示的全历史累计。
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct DashboardTotals {
+    pub request_count: u64,
+    pub input_tokens: u64,
+    pub cached_tokens: u64,
+    pub total_tokens: u64,
+    pub billing_usd: Option<DecimalAmount>,
+}
+
+/// 仪表盘所需的当前区间事实及全历史累计。
 #[derive(Debug, Clone, PartialEq)]
 pub struct DashboardObservation {
    pub range: TimeRange,
    pub requests: RequestMetrics,
    pub attempts: AttemptMetrics,
+    pub totals: DashboardTotals,
    pub provider_accounts: AccountPoolMetrics,
    pub trend: Vec<RequestMetricPoint>,
    pub account_usage: Vec<DashboardAccountUsage>,
@@ -560,6 +550,9 @@ pub struct UsageRecord {
    pub id: String,
    pub client_api_key_ref: String,
    pub config_revision: u64,
+    pub routing_scope: String,
+    pub routing_group_refs: Vec<String>,
+    pub routing_group_names_snapshot: Vec<String>,
    pub protocol: String,
    pub operation: String,
    pub endpoint: String,
@@ -574,6 +567,7 @@ pub struct UsageRecord {
    pub upstream_transport: Option<String>,
    pub http_version: Option<String>,
    pub websocket_pool: Option<String>,
+    pub service_tier: Option<String>,
    /// Provider 已筛选的专有观测 JSON；管理领域保持不透明。
    pub provider_metadata_json: Option<String>,
    pub attempt_count: u32,
@@ -642,6 +636,9 @@ pub struct UsageAttempt {
    pub operation: String,
    pub provider_kind: Option<String>,
    pub provider_account_ref: Option<String>,
+    pub provider_account_name: Option<String>,
+    pub provider_account_email: Option<String>,
+    pub provider_account_authentication_kind: Option<String>,
    pub upstream_model_id: Option<String>,
    pub upstream_transport: Option<String>,
    pub upstream_send_state: Option<String>,
@@ -702,6 +699,7 @@ pub struct UsageSummary {
 /// 单个诊断维度值的聚合结果。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DiagnosticObservation {
+    pub key: String,
    pub name: String,
    pub request_count: u64,
    pub success_count: u64,
@@ -709,6 +707,7 @@ pub struct DiagnosticObservation {
    pub attempt_count: u64,
    pub total_tokens: u64,
    pub average_latency_ms: Option<u64>,
+    pub latency_p95_ms: Option<u64>,
    pub cost_coverage: CostCoverage,
    pub costs: Vec<CurrencyCost>,
 }
@@ -723,8 +722,12 @@ pub struct OpsError {
    pub client_api_key_ref: Option<String>,
    pub component: String,
    pub operation: String,
+    pub endpoint: Option<String>,
    pub provider_kind: Option<String>,
    pub provider_account_ref: Option<String>,
+    pub provider_account_name: Option<String>,
+    pub provider_account_email: Option<String>,
+    pub provider_account_authentication_kind: Option<String>,
    pub upstream_model_id: Option<String>,
    pub upstream_transport: Option<String>,
    pub failure_kind: String,
@@ -1018,6 +1021,7 @@ pub struct UsageInsights {
 /// 已完成分母计算的诊断项。
 #[derive(Debug, Clone, PartialEq)]
 pub struct DiagnosticsItem {
+    pub key: String,
    pub name: String,
    pub request_count: u64,
    pub success_count: u64,
@@ -1025,6 +1029,7 @@ pub struct DiagnosticsItem {
    pub error_rate: f64,
    pub request_share: f64,
    pub average_latency_ms: Option<u64>,
+    pub latency_p95_ms: Option<u64>,
    pub estimated_cost: Option<DecimalAmount>,
    pub attempt_count: u64,
    pub total_tokens: u64,
@@ -5,13 +5,13 @@ use std::fmt;
 use async_trait::async_trait;
 use chrono::{DateTime, Utc};
 use gateway_core::{
-    engine::credential::{OpaqueProviderData, ProviderAccountId},
+    engine::credential::{OpaqueProviderData, ProviderAccountId, ProviderAccountIdentity},
    routing::{ProviderKind, UpstreamModelId},
 };

 use super::{
    AdminError, MutationActor, MutationContext, PageSize, Revision,
-    accounts::{AccountAvailability, AccountRecord, AccountStatus, AccountSummary, AccountUsage},
+    accounts::{AccountRecord, AccountSummary, AccountUsage, CredentialState},
 };

 /// Provider-owned JSON；公共层只搬运且 Debug 不输出值。
@@ -52,24 +52,24 @@ pub struct CredentialCursor {
 /// Provider credential 列表查询。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialListQuery {
-    pub availability: Option<CredentialAvailabilityFilter>,
+    pub credential_state: Option<CredentialStateFilter>,
    pub enabled: Option<bool>,
    pub window: CredentialListWindow,
 }

-/// Credential 可用性筛选；支持一个 wire 值对应多个持久状态。
+/// Credential 状态筛选。
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub enum CredentialAvailabilityFilter {
-    Exact(AccountAvailability),
-    AnyOf(Vec<AccountAvailability>),
+pub enum CredentialStateFilter {
+    Exact(CredentialState),
+    AnyOf(Vec<CredentialState>),
 }

-impl CredentialAvailabilityFilter {
+impl CredentialStateFilter {
    #[must_use]
-    pub fn matches(&self, availability: AccountAvailability) -> bool {
+    pub fn matches(&self, credential_state: CredentialState) -> bool {
        match self {
-            Self::Exact(expected) => *expected == availability,
-            Self::AnyOf(expected) => expected.contains(&availability),
+            Self::Exact(expected) => *expected == credential_state,
+            Self::AnyOf(expected) => expected.contains(&credential_state),
        }
    }
 }
@@ -143,7 +143,7 @@ pub struct PreparedCredentialCreate {
    pub provider_kind: ProviderKind,
    pub name: String,
    pub email: Option<String>,
-    pub upstream_user_id: String,
+    pub upstream_user_id: Option<String>,
    pub upstream_account_id: Option<String>,
    pub plan_type: Option<String>,
    pub authentication_kind: String,
@@ -152,10 +152,8 @@ pub struct PreparedCredentialCreate {
    pub access_token_expires_at: Option<DateTime<Utc>>,
    pub next_refresh_at: Option<DateTime<Utc>>,
    pub enabled: bool,
-    pub availability: AccountAvailability,
-    pub availability_reason: Option<String>,
-    pub cooldown_until: Option<DateTime<Utc>>,
-    pub availability_observed_at: DateTime<Utc>,
+    pub credential_state: CredentialState,
+    pub credential_observed_at: DateTime<Utc>,
 }

 /// Provider 对一份导入文档的完整验证结果。
@@ -496,6 +494,7 @@ pub struct PreparedCredentialRotationFacts {
    pub account_id: ProviderAccountId,
    pub provider_kind: ProviderKind,
    pub expected_credential_revision: Revision,
+    pub replacement_identity: Option<ProviderAccountIdentity>,
    pub name: String,
    pub email: Option<String>,
    pub plan_type: Option<String>,
@@ -562,6 +561,15 @@ impl fmt::Debug for RotateCredential {
    }
 }

+/// 通用账号用量能否可靠归属到一个 Provider quota 窗口。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum QuotaLocalUsageAttribution {
+    /// 窗口覆盖账号的全部请求，可按账号与时间范围聚合。
+    AccountWide,
+    /// 窗口需要 Provider / 模型级归属，通用账号聚合不可用。
+    Unavailable,
+}
+
 /// 一个 Provider quota 窗口的公共投影。
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderQuotaWindow {
@@ -569,9 +577,11 @@ pub struct ProviderQuotaWindow {
    pub group: String,
    pub label: String,
    pub source: Option<String>,
+    pub local_usage_attribution: QuotaLocalUsageAttribution,
    pub window_seconds: Option<u64>,
    pub used_percent: Option<f64>,
    pub reset_at: Option<DateTime<Utc>>,
+    pub limit_reached: bool,
    pub local_usage: Option<AccountUsage>,
    pub provider_data: Option<ProviderDocument>,
 }
@@ -590,35 +600,105 @@ pub struct ProviderQuota {
    pub observed_at: Option<DateTime<Utc>>,
    pub refresh_token_expires_at: Option<DateTime<Utc>>,
    pub windows: Vec<ProviderQuotaWindow>,
+    /// 展示用快照级触顶事实（顶层或任一窗口触顶）；不参与账号五态派生。
+    pub limit_reached: bool,
    pub provider_data: Option<ProviderDocument>,
 }

 impl ProviderQuota {
+    /// 返回账号展开面板使用的当前额度窗口用量。
+    ///
+    /// Provider 已提供账号级本地用量时，固定窗口和无固定重置点的滚动窗口
+    /// 都可作为代表用量；优先级与 Dashboard 代表性额度窗口一致，
+    /// 同一优先级保持 Provider 投影顺序。
+    #[must_use]
+    pub fn representative_window_usage(&self) -> Option<&AccountUsage> {
+        self.windows
+            .iter()
+            .enumerate()
+            .filter(|(_, window)| {
+                window.local_usage_attribution == QuotaLocalUsageAttribution::AccountWide
+                    && window.window_seconds.is_some()
+                    && window.local_usage.is_some()
+            })
+            .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
+            .and_then(|(_, window)| window.local_usage.as_ref())
+    }
+
    /// 返回 Dashboard 使用的代表性额度比例。
    ///
    /// 优先使用短周期窗口，再依次使用周、月和其它窗口；同一优先级取较高的已用比例。
    /// 这里只解释跨 Provider 共享的窗口语义，绝不读取 Provider 私有 JSON。
    #[must_use]
    pub fn representative_used_percent(&self) -> Option<f64> {
+        if self.limit_reached {
+            return Some(100.0);
+        }
+        self.representative_used_window()
+            .map(|(_, used_percent)| used_percent)
+    }
+
+    /// 将已确认的账号级额度耗尽事实投影到展示窗口。
+    ///
+    /// Provider 已指出具体触顶窗口时只归一化这些窗口；否则归一化 Dashboard
+    /// 同样会选择的代表窗口，避免把多个独立额度窗口全部伪造成已用尽。
+    pub fn apply_limit_reached_display(&mut self) {
+        if !self.limit_reached {
+            return;
+        }
+        let reached_windows = self
+            .windows
+            .iter()
+            .enumerate()
+            .filter_map(|(index, window)| window.limit_reached.then_some(index))
+            .collect::<Vec<_>>();
+        if !reached_windows.is_empty() {
+            for index in reached_windows {
+                self.windows[index].used_percent = Some(100.0);
+            }
+            return;
+        }
+        let representative = self
+            .representative_used_window()
+            .map(|(index, _)| index)
+            .or_else(|| {
+                self.windows
+                    .iter()
+                    .enumerate()
+                    .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
+                    .map(|(index, _)| index)
+            });
+        if let Some(index) = representative {
+            self.windows[index].used_percent = Some(100.0);
+            self.windows[index].limit_reached = true;
+        }
+    }
+
+    fn representative_used_window(&self) -> Option<(usize, f64)> {
        self.windows
            .iter()
+            .enumerate()
            .filter_map(|window| {
+                let (index, window) = window;
                let used_percent = window
                    .used_percent
                    .filter(|value| value.is_finite())
                    .map(|value| value.clamp(0.0, 100.0))?;
-                Some((quota_usage_priority(window), used_percent))
+                Some((index, quota_usage_priority(window), used_percent))
            })
-            .fold(None::<(u8, f64)>, |selected, candidate| match selected {
-                Some(current)
-                    if current.0 < candidate.0
-                        || (current.0 == candidate.0 && current.1 >= candidate.1) =>
-                {
+            .fold(
+                None::<(usize, u8, f64)>,
+                |selected, candidate| match selected {
                    Some(current)
-                }
-                _ => Some(candidate),
-            })
-            .map(|(_, used_percent)| used_percent)
+                        if current.1 < candidate.1
+                            || (current.1 == candidate.1 && current.2 >= candidate.2) =>
+                    {
+                        Some(current)
+                    }
+                    _ => Some(candidate),
+                },
+            )
+            .map(|(index, _, used_percent)| (index, used_percent))
    }
 }

@@ -685,7 +765,7 @@ impl fmt::Debug for ProviderExport {
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountDirectoryItem {
    pub account: AccountRecord,
-    pub status: AccountStatus,
+    pub projection: gateway_core::engine::credential::AccountStatusProjection,
    pub usage: Option<super::accounts::AccountUsage>,
    pub quota: ProviderQuota,
 }
@@ -11,14 +11,8 @@ use super::Revision;
 /// 客户端模型到上游模型的全局精确映射。
 pub type ModelMappings = BTreeMap<PublicModelId, UpstreamModelId>;

-/// 账号调度策略。
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum RotationStrategy {
-    Smart,
-    QuotaResetPriority,
-    RoundRobin,
-    Sticky,
-}
+/// 账号调度策略；由 Core 拥有稳定值与 wire 映射。
+pub use gateway_core::engine::credential::RotationStrategy;

 /// 完整运行设置事实。
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -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::engine::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::engine::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(),
+    )
+}
@@ -1,5 +1,6 @@
 //! 管理用例依赖的外部能力端口。

+pub mod backup;
 pub mod provider;
 pub mod store;
 pub mod system;
@@ -31,23 +31,51 @@ pub enum ProviderAdminErrorKind {
    Internal,
 }

-/// 不泄漏 OAuth material 与 Provider 响应体的管理错误。
-#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+/// 不携带 OAuth 请求材料的管理错误。
+///
+/// `message` 用于当前认证管理请求展示；上游没有标准 `error.message` 时，
+/// Provider 可以按其官方契约回退为完整的非成功响应正文。
+#[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 }
+        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 对管理控制面提供的解析、验证、上游交互与运行时资源回收能力。
@@ -64,6 +92,12 @@ pub trait ProviderAdmin: Send + Sync {
    /// 成功之后，不参与事务成败，也不得恢复或改写已经提交的账号状态。
    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,
@@ -7,11 +7,17 @@ use std::sync::Arc;
 use async_trait::async_trait;
 use chrono::{DateTime, Utc};

+use super::backup::BackupStorePorts;
 use crate::model::{
    MutationContext, Revision,
+    account_groups::{
+        AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, DeleteAccountGroup,
+        NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+    },
    accounts::{
-        AccountListQuery, AccountPage, AccountRecord, AccountUsage, AccountUsageWindowQuery,
-        AccountUsageWindowResult, DeleteAccounts, SetAccountEnabled,
+        AccountListQuery, AccountPage, AccountPageItem, AccountUpdateResult, AccountUsage,
+        AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
+        BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
    },
    auth::{AdminAuditEvent, AdminSession},
    client_keys::{
@@ -82,7 +88,7 @@ pub type AdminStoreResult<T> = Result<T, AdminStoreError>;
 pub trait AccountStore: Send + Sync {
    async fn list_accounts(&self, query: AccountListQuery) -> AdminStoreResult<AccountPage>;

-    async fn load_account(&self, account_id: &str) -> AdminStoreResult<Option<AccountRecord>>;
+    async fn load_account(&self, account_id: &str) -> AdminStoreResult<Option<AccountPageItem>>;

    async fn load_account_usage(
        &self,
@@ -137,11 +143,23 @@ pub trait AccountStore: Send + Sync {
        context: &MutationContext,
    ) -> AdminStoreResult<CredentialMutationResult>;

-    async fn set_account_enabled(
+    async fn update_account(
        &self,
-        command: SetAccountEnabled,
+        command: UpdateAccount,
        context: &MutationContext,
-    ) -> AdminStoreResult<Revision>;
+    ) -> AdminStoreResult<AccountUpdateResult>;
+
+    async fn recover_account(
+        &self,
+        account_id: &gateway_core::engine::credential::ProviderAccountId,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountUpdateResult>;
+
+    async fn batch_update_accounts(
+        &self,
+        command: BatchUpdateAccounts,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountsUpdateResult>;

    async fn delete_accounts(
        &self,
@@ -214,10 +232,48 @@ pub trait ClientKeyStore: Send + Sync {
    ) -> 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 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>;
+}
+
 /// 用量、趋势、诊断与运维错误的只读能力。
 #[async_trait]
 pub trait ObservabilityStore: Send + Sync {
-    async fn dashboard_summary(&self, range: TimeRange) -> AdminStoreResult<DashboardObservation>;
+    /// 返回历史统计区间和指定观测时刻下的实时账号状态。
+    async fn dashboard_summary(
+        &self,
+        range: TimeRange,
+        observed_at: DateTime<Utc>,
+    ) -> AdminStoreResult<DashboardObservation>;

    /// 返回 Dashboard 可选的实时槽位事实。
    ///
@@ -296,27 +352,33 @@ pub trait SettingsStore: Send + Sync {
 #[derive(Clone)]
 pub struct AdminStorePorts {
    accounts: Arc<dyn AccountStore>,
+    account_groups: Arc<dyn AccountGroupStore>,
    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: Arc<dyn AccountStore>,
+        account_groups: Arc<dyn AccountGroupStore>,
        auth: Arc<dyn AuthStore>,
        client_keys: Arc<dyn ClientKeyStore>,
        observability: Arc<dyn ObservabilityStore>,
        settings: Arc<dyn SettingsStore>,
+        backup: BackupStorePorts,
    ) -> Self {
        Self {
            accounts,
+            account_groups,
            auth,
            client_keys,
            observability,
            settings,
+            backup,
        }
    }

@@ -325,6 +387,11 @@ impl AdminStorePorts {
        self.accounts.clone()
    }

+    #[must_use]
+    pub fn account_groups(&self) -> Arc<dyn AccountGroupStore> {
+        self.account_groups.clone()
+    }
+
    #[must_use]
    pub fn auth(&self) -> Arc<dyn AuthStore> {
        self.auth.clone()
@@ -344,4 +411,9 @@ impl AdminStorePorts {
    pub fn settings(&self) -> Arc<dyn SettingsStore> {
        self.settings.clone()
    }
+
+    #[must_use]
+    pub fn backup(&self) -> BackupStorePorts {
+        self.backup.clone()
+    }
 }
@@ -0,0 +1,130 @@
+//! Account group management use cases.
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use gateway_core::routing::{AccountGroupId, snapshot::SnapshotControl};
+use uuid::Uuid;
+
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        account_groups::{
+            AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, CreateAccountGroup,
+            DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+        },
+    },
+    ports::store::AccountGroupStore,
+};
+
+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>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultAccountGroupService {
+    #[must_use]
+    pub(crate) fn new(
+        store: Arc<dyn AccountGroupStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self { store, snapshot }
+    }
+
+    async fn publish(
+        &self,
+        result: Result<AccountGroupMutation, crate::ports::store::AdminStoreError>,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        let result = result.map_err(|error| map_store_error(error, "account group"))?;
+        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> {
+        self.store
+            .list_account_groups(query)
+            .await
+            .map_err(|error| map_store_error(error, "account group"))
+    }
+
+    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("Failed to create account group 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
+    }
+}
@@ -18,19 +18,17 @@ use crate::{
        AdminError, MutationContext,
        accounts::{
            AccountConnectionTestEvent, AccountConnectionTestEventStream, AccountListQuery,
-            AccountRecord, AccountStatus, AccountUsageWindowQuery,
+            AccountPageItem, AccountUpdateResult, AccountUsageWindowQuery, AccountsUpdateResult,
+            BatchUpdateAccounts, UpdateAccount,
        },
        observability::TimeRange,
        provider_credentials::{
            AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
            PrepareCredentialRefresh, ProviderModels, ProviderQuota, ProviderQuotaRequest,
-            ProviderQuotaWindow,
+            ProviderQuotaWindow, QuotaLocalUsageAttribution,
        },
    },
-    ports::{
-        provider::ProviderAdminRegistry,
-        store::{AccountStore, SettingsStore},
-    },
+    ports::{provider::ProviderAdminRegistry, store::AccountStore},
 };

 use super::{
@@ -57,6 +55,24 @@ pub trait AccountsService: Send + Sync {
        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,
@@ -78,7 +94,6 @@ pub trait AccountsService: Send + Sync {

 pub(crate) struct DefaultAccountsService {
    accounts: Arc<dyn AccountStore>,
-    settings: Arc<dyn SettingsStore>,
    providers: ProviderAdminRegistry,
    snapshot: Arc<dyn SnapshotControl>,
    probe: Arc<dyn AccountProbe>,
@@ -88,14 +103,12 @@ impl DefaultAccountsService {
    #[must_use]
    pub(crate) const fn new(
        accounts: Arc<dyn AccountStore>,
-        settings: Arc<dyn SettingsStore>,
        providers: ProviderAdminRegistry,
        snapshot: Arc<dyn SnapshotControl>,
        probe: Arc<dyn AccountProbe>,
    ) -> Self {
        Self {
            accounts,
-            settings,
            providers,
            snapshot,
            probe,
@@ -105,7 +118,7 @@ impl DefaultAccountsService {
    async fn load_account(
        &self,
        account_id: &ProviderAccountId,
-    ) -> Result<AccountRecord, AdminError> {
+    ) -> Result<AccountPageItem, AdminError> {
        self.accounts
            .load_account(account_id.as_str())
            .await
@@ -118,32 +131,32 @@ impl DefaultAccountsService {
        account_id: &ProviderAccountId,
    ) -> Result<
        (
-            AccountRecord,
+            AccountPageItem,
            Arc<dyn crate::ports::provider::ProviderAdmin>,
        ),
        AdminError,
    > {
-        let account = self.load_account(account_id).await?;
+        let item = self.load_account(account_id).await?;
        let provider = self
            .providers
-            .require(&account.provider_kind)
+            .require(&item.account.provider_kind)
            .map_err(|error| map_provider_error(error, "provider account"))?;
-        Ok((account, provider))
+        Ok((item, provider))
    }

    async fn attach_quota_local_usage(
        &self,
-        accounts: &[AccountRecord],
+        accounts: &[AccountPageItem],
        quotas: &mut [ProviderQuota],
    ) -> Result<(), AdminError> {
        let windows = accounts
            .iter()
            .zip(quotas.iter())
-            .flat_map(|(account, quota)| {
+            .flat_map(|(item, quota)| {
                quota
                    .windows
                    .iter()
-                    .filter_map(|window| quota_usage_window(&account.id, window))
+                    .filter_map(|window| quota_usage_window(&item.account.id, window))
            })
            .collect::<Vec<_>>();
        if windows.is_empty() {
@@ -157,10 +170,12 @@ impl DefaultAccountsService {
            .into_iter()
            .map(|result| ((result.account_id, result.key), result.usage))
            .collect::<BTreeMap<_, _>>();
-        for (account, quota) in accounts.iter().zip(quotas) {
+        for (item, quota) in accounts.iter().zip(quotas) {
            for window in &mut quota.windows {
-                if window.local_usage.is_none() {
-                    let key = (account.id.clone(), window.key.clone());
+                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());
                    }
@@ -175,33 +190,19 @@ impl DefaultAccountsService {
        account_id: &ProviderAccountId,
        refresh_quota: bool,
    ) -> Result<AccountDirectoryItem, AdminError> {
-        let (account, provider) = self.provider_for_account(account_id).await?;
-        let settings = self
-            .settings
-            .load_runtime_settings()
-            .await
-            .map_err(|error| map_store_error(error, "runtime settings"))?;
+        let (stored, provider) = self.provider_for_account(account_id).await?;
+        let account = &stored.account;
        let now = Utc::now();
-        let retained_range = retained_usage_range(now, settings.usage_retention_days);
        let rolling_range = TimeRange {
            start: now - Duration::hours(24),
            end: now,
        };
        let ids = vec![account.id.clone()];
-        let (usage, rolling_usage) = futures::try_join!(
-            async {
-                self.accounts
-                    .load_account_usage(retained_range, &ids)
-                    .await
-                    .map_err(|error| map_store_error(error, "account usage"))
-            },
-            async {
-                self.accounts
-                    .load_account_usage(rolling_range, &ids)
-                    .await
-                    .map_err(|error| map_store_error(error, "rolling account usage"))
-            },
-        )?;
+        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 {
@@ -212,14 +213,15 @@ impl DefaultAccountsService {
            .await
            .map_err(|error| map_provider_error(error, "provider quota"))?;
        self.attach_quota_local_usage(
-            std::slice::from_ref(&account),
+            std::slice::from_ref(&stored),
            std::slice::from_mut(&mut quota),
        )
        .await?;
+        let usage = quota.representative_window_usage().cloned();
        Ok(AccountDirectoryItem {
-            status: account_status(&account, now),
-            usage: usage.into_iter().next(),
-            account,
+            projection: stored.projection,
+            usage,
+            account: stored.account,
            quota,
        })
    }
@@ -228,13 +230,12 @@ impl DefaultAccountsService {
 #[async_trait]
 impl AccountsService for DefaultAccountsService {
    async fn list(&self, query: AccountListQuery) -> Result<AccountDirectoryPage, AdminError> {
-        let (page, settings) = futures::try_join!(
-            self.accounts.list_accounts(query),
-            self.settings.load_runtime_settings(),
-        )
-        .map_err(|error| map_store_error(error, "account directory"))?;
+        let page = self
+            .accounts
+            .list_accounts(query)
+            .await
+            .map_err(|error| map_store_error(error, "account directory"))?;
        let now = Utc::now();
-        let retained_range = retained_usage_range(now, settings.usage_retention_days);
        let rolling_range = TimeRange {
            start: now - Duration::hours(24),
            end: now,
@@ -242,36 +243,52 @@ impl AccountsService for DefaultAccountsService {
        let ids = page
            .items
            .iter()
-            .map(|account| account.id.clone())
+            .map(|item| item.account.id.clone())
            .collect::<Vec<_>>();
-        let (usage, rolling_usage) = futures::try_join!(
-            self.accounts.load_account_usage(retained_range, &ids),
-            self.accounts.load_account_usage(rolling_range, &ids),
-        )
-        .map_err(|error| map_store_error(error, "account usage"))?;
-        let usage = usage
-            .into_iter()
-            .map(|usage| (usage.account_id.clone(), usage))
-            .collect::<BTreeMap<_, _>>();
+        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(|account| async {
+        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("Invalid provider account ID"))?;
-            let provider = self
-                .providers
-                .require(&account.provider_kind)
-                .map_err(|error| map_provider_error(error, "provider quota"))?;
-            provider
+            // 单个账号的 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
-                .map_err(|error| map_provider_error(error, "provider quota"))
+            {
+                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()
@@ -282,11 +299,14 @@ impl AccountsService for DefaultAccountsService {
            .items
            .into_iter()
            .zip(quotas)
-            .map(|(account, quota)| AccountDirectoryItem {
-                status: account_status(&account, now),
-                usage: usage.get(&account.id).cloned(),
-                account,
-                quota,
+            .map(|(item, quota)| {
+                let usage = quota.representative_window_usage().cloned();
+                AccountDirectoryItem {
+                    usage,
+                    account: item.account,
+                    projection: item.projection,
+                    quota,
+                }
            })
            .collect();
        Ok(AccountDirectoryPage {
@@ -312,7 +332,7 @@ impl AccountsService for DefaultAccountsService {
        for account_id in account_ids {
            let account = self.load_account(&account_id).await?;
            grouped
-                .entry(account.provider_kind)
+                .entry(account.account.provider_kind)
                .or_default()
                .push(account_id);
        }
@@ -355,7 +375,8 @@ impl AccountsService for DefaultAccountsService {
        context: &MutationContext,
        account_id: ProviderAccountId,
    ) -> Result<AccountRefreshResult, AdminError> {
-        let (account, provider) = self.provider_for_account(&account_id).await?;
+        let (stored, provider) = self.provider_for_account(&account_id).await?;
+        let account = stored.account;
        let prepared = provider
            .prepare_refresh(PrepareCredentialRefresh {
                account: account.clone(),
@@ -370,6 +391,9 @@ impl AccountsService for DefaultAccountsService {
            "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 {
@@ -378,6 +402,98 @@ impl AccountsService for DefaultAccountsService {
        })
    }

+    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("Invalid provider account 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("Invalid provider account 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,
@@ -403,8 +519,8 @@ impl AccountsService for DefaultAccountsService {
        account_id: ProviderAccountId,
        upstream_model: UpstreamModelId,
    ) -> Result<AccountConnectionTestEventStream, AdminError> {
-        let (account, provider) = self.provider_for_account(&account_id).await?;
-        let initial_status = account_status(&account, Utc::now());
+        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)
@@ -421,8 +537,6 @@ impl AccountsService for DefaultAccountsService {
            },
        ];
        let probe = Arc::clone(&self.probe);
-        let accounts = Arc::clone(&self.accounts);
-        let stored_account_id = account.id.clone();
        let terminal = futures::stream::once(async move {
            let result = probe
                .probe(AccountProbeRequest {
@@ -432,29 +546,35 @@ impl AccountsService for DefaultAccountsService {
                    operation,
                })
                .await;
-            let status = accounts
-                .load_account(&stored_account_id)
-                .await
-                .ok()
-                .flatten()
-                .map_or(initial_status, |account| {
-                    account_status(&account, Utc::now())
-                });
            match result {
                Ok(result) => result
                    .text
                    .into_iter()
                    .map(|text| AccountConnectionTestEvent::Content { text })
-                    .chain(std::iter::once(AccountConnectionTestEvent::Completed {
-                        account_status: status,
-                    }))
+                    .chain(std::iter::once(AccountConnectionTestEvent::Completed))
                    .collect(),
-                Err(error) => vec![AccountConnectionTestEvent::Failed {
-                    message: error.client_message().to_owned(),
-                    provider_error_code: error.client_error_code().map(ToOwned::to_owned),
-                    provider_error_type: error.client_error_type().map(ToOwned::to_owned),
-                    account_status: status,
-                }],
+                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 {
+                        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);
@@ -462,33 +582,14 @@ impl AccountsService for DefaultAccountsService {
    }
 }

-fn account_status(account: &AccountRecord, now: chrono::DateTime<Utc>) -> AccountStatus {
-    if !account.enabled {
-        AccountStatus::Disabled
-    } else {
-        match account.availability {
-            crate::model::accounts::AccountAvailability::Banned => AccountStatus::Banned,
-            crate::model::accounts::AccountAvailability::QuotaExhausted => {
-                AccountStatus::QuotaExhausted
-            }
-            crate::model::accounts::AccountAvailability::Expired
-            | crate::model::accounts::AccountAvailability::Invalid => AccountStatus::Expired,
-            _ if account
-                .access_token_expires_at
-                .is_some_and(|expires_at| expires_at <= now) =>
-            {
-                AccountStatus::Expired
-            }
-            _ => AccountStatus::Active,
-        }
-    }
-}
-
-fn retained_usage_range(now: chrono::DateTime<Utc>, retention_days: u32) -> TimeRange {
-    // 账号留存投影是内部查询，不受外部观测接口 366 天上限约束。
-    TimeRange {
-        start: now - Duration::days(i64::from(retention_days)),
-        end: now,
+/// 账号目录中单个账号 quota 读取失败时使用的空额度投影。
+fn empty_quota() -> ProviderQuota {
+    ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: Vec::new(),
+        limit_reached: false,
+        provider_data: None,
    }
 }

@@ -496,7 +597,9 @@ fn quota_usage_window(
    account_id: &str,
    window: &ProviderQuotaWindow,
 ) -> Option<AccountUsageWindowQuery> {
-    if window.local_usage.is_some() {
+    if window.local_usage.is_some()
+        || window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide
+    {
        return None;
    }
    let reset_at = window.reset_at?;
@@ -0,0 +1,437 @@
+//! 备份配置、手动创建、下载与删除用例。
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use gateway_core::routing::snapshot::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 } => admin_user_id.clone(),
+            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, error.message().to_owned())
+        }
+        _ => AdminError::bad_gateway(error.message().to_owned()),
+    }
+}
@@ -97,7 +97,7 @@ impl ClientKeyService for DefaultClientKeyService {
                    id,
                    name: command.name,
                    label: command.label,
-                    provider_kind: command.provider_kind,
+                    group_ids: command.group_ids,
                    limits: command.limits,
                    plaintext: plaintext.clone(),
                },
@@ -1,7 +1,9 @@
 //! 管理控制面的用例实现。

+pub mod account_groups;
 pub mod accounts;
 pub mod auth;
+pub mod backup;
 pub mod client_keys;
 pub mod observability;
 pub mod openai;
@@ -12,11 +14,11 @@ pub mod xai;
 use crate::{
    model::{
        AdminError, AdminErrorKind, MutationContext,
-        accounts::{DeleteAccounts, SetAccountEnabled},
+        accounts::DeleteAccounts,
        provider_credentials::{
            AuthorizationMutationTarget, CredentialDeletion, CredentialDeletionResult,
-            CredentialDetails, CredentialMutation, CredentialMutationResult,
-            CredentialRotationCommit, PendingAuthorizationMutation, PreparedAuthorizationCommit,
+            CredentialDetails, CredentialMutationResult, CredentialRotationCommit,
+            PendingAuthorizationMutation, PreparedAuthorizationCommit,
            PreparedAuthorizationCredential, PreparedCredentialImport, PreparedCredentialRotation,
            StartAuthorization,
        },
@@ -57,7 +59,11 @@ fn map_provider_error(
        ProviderAdminErrorKind::Unavailable => AdminErrorKind::Unavailable,
        ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
    };
-    AdminError::new(kind, format!("{resource} operation failed"))
+    let message = error
+        .message()
+        .map(ToOwned::to_owned)
+        .unwrap_or_else(|| format!("{resource} operation failed"));
+    AdminError::new(kind, message)
 }

 async fn publish_committed(
@@ -279,41 +285,6 @@ async fn commit_credential_refresh(
    }
 }

-async fn set_credential_enabled(
-    accounts: &dyn AccountStore,
-    provider: &dyn ProviderAdmin,
-    command: CredentialMutation,
-    enabled: bool,
-    resource: &'static str,
-) -> Result<CredentialMutationResult, AdminError> {
-    required_credential(
-        accounts,
-        provider.provider_kind(),
-        &command.account_id,
-        resource,
-    )
-    .await?;
-    let account_id = command.account_id;
-    let revision = accounts
-        .set_account_enabled(
-            SetAccountEnabled {
-                account_id: account_id.as_str().to_owned(),
-                enabled,
-            },
-            &command.context,
-        )
-        .await
-        .map_err(|error| map_store_error(error, resource))?;
-    if !enabled {
-        provider.account_unavailable(&account_id).await;
-    }
-    Ok(CredentialMutationResult {
-        config_revision: revision,
-        account_id,
-        credential_revision: None,
-    })
-}
-
 async fn delete_credentials(
    accounts: &dyn AccountStore,
    provider: &dyn ProviderAdmin,
@@ -339,6 +310,7 @@ async fn delete_credentials(
    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,
@@ -98,10 +98,11 @@ impl ObservabilityService for DefaultObservabilityService {
        range: TimeRange,
        kind: TrendKind,
    ) -> Result<DashboardResult, AdminError> {
+        let observed_at = Utc::now();
        let (mut observation, settings, runtime_slots) = futures::try_join!(
-            self.store.dashboard_summary(range),
+            self.store.dashboard_summary(range, observed_at),
            self.settings.load_runtime_settings(),
-            self.store.dashboard_runtime_slots(range.end),
+            self.store.dashboard_runtime_slots(observed_at),
        )
        .map_err(|error| map_store_error(error, "dashboard"))?;
        self.enrich_billing(&mut observation.recent_requests);
@@ -112,15 +113,10 @@ impl ObservabilityService for DefaultObservabilityService {
        let today =
            dashboard_period_metrics(&observation.trend, today_start, observation.range.end);
        let yesterday = dashboard_period_metrics(&observation.trend, yesterday_start, today_start);
-        let total_billing_usd = observation
-            .attempts
-            .costs
-            .iter()
-            .find(|cost| cost.currency == "USD")
-            .map(|cost| cost.amount.clone());
+        let total_billing_usd = observation.totals.billing_usd.clone();
        let total_cached_token_rate = rate_or_zero(
-            observation.requests.cached_tokens,
-            observation.requests.input_tokens,
+            observation.totals.cached_tokens,
+            observation.totals.input_tokens,
        );
        let average_first_token_latency_ms = average(
            observation.requests.first_token_latency_sum_ms,
@@ -130,12 +126,20 @@ impl ObservabilityService for DefaultObservabilityService {
        let health_timeline = health_timeline_at(&observation.trend, Utc::now());
        let wire_profiles = self.providers.dashboard_wire_profiles();
        let max_concurrent_per_account = u64::from(settings.max_concurrent_per_account);
-        let active_accounts = runtime_slots
-            .as_ref()
-            .map_or(observation.provider_accounts.active, |slots| {
-                slots.active_accounts
-            });
-        let total_slots = active_accounts.saturating_mul(max_concurrent_per_account);
+        let total_slots = runtime_slots.as_ref().map_or_else(
+            || {
+                observation
+                    .provider_accounts
+                    .normal
+                    .saturating_mul(max_concurrent_per_account)
+            },
+            |slots| {
+                slots
+                    .inherited_accounts
+                    .saturating_mul(max_concurrent_per_account)
+                    .saturating_add(slots.overridden_slots)
+            },
+        );
        let used_slots = runtime_slots.and_then(|slots| slots.used_slots);
        Ok(DashboardResult {
            capacity: DashboardCapacity {
@@ -247,6 +251,7 @@ impl ObservabilityService for DefaultObservabilityService {
            items: items
                .into_iter()
                .map(|item| DiagnosticsItem {
+                    key: item.key,
                    name: item.name,
                    request_count: item.request_count,
                    success_count: item.request_count.saturating_sub(item.failure_count),
@@ -254,6 +259,7 @@ impl ObservabilityService for DefaultObservabilityService {
                    error_rate: rate_or_zero(item.failure_count, item.request_count),
                    request_share: rate_or_zero(item.request_count, total_requests),
                    average_latency_ms: item.average_latency_ms,
+                    latency_p95_ms: item.latency_p95_ms,
                    estimated_cost: usd_cost(&item.costs),
                    attempt_count: item.attempt_count,
                    total_tokens: item.total_tokens,
@@ -428,6 +434,7 @@ fn recover_standard_costs(
        };
        let input = ProviderBillingInput {
            upstream_model_id: fact.upstream_model_id,
+            service_tier: fact.service_tier,
            input_tokens: fact.input_tokens,
            output_tokens: fact.output_tokens,
            cached_tokens: fact.cached_tokens,
@@ -486,19 +493,18 @@ impl DefaultObservabilityService {
        });
        let quota_used = futures::future::join_all(quota_reads).await;
        for (account, used_percent) in accounts.iter_mut().zip(quota_used) {
-            account.quota_used_percent = used_percent
-                .or_else(|| (account.availability == "quota_exhausted").then_some(100.0));
+            account.quota_used_percent = used_percent;
        }
    }

-    /// 逐条尽力把 calculated 总额升级为完整分解；单条脏数据（非法 Provider kind
-    /// 或费用规则失败）只保留该条已存的总额，不影响整页返回。
+    /// 逐条尽力把可校验的总额升级为完整分解；单条脏数据（非法 Provider kind、
+    /// 不支持的来源或费用规则失败）只保留该条已存的总额，不影响整页返回。
    fn enrich_billing(&self, records: &mut [crate::model::observability::UsageRecord]) {
        for record in records {
            let Some(UsageBilling::Total { source, total }) = record.billing.as_ref() else {
                continue;
            };
-            if source != "calculated" {
+            if !matches!(source.as_str(), "calculated" | "provider_reported") {
                continue;
            }
            let (Some(provider), Some(upstream_model_id)) = (
@@ -512,6 +518,7 @@ impl DefaultObservabilityService {
            };
            let input = ProviderBillingInput {
                upstream_model_id: upstream_model_id.clone(),
+                service_tier: record.service_tier.clone(),
                input_tokens: record.input_tokens,
                output_tokens: record.output_tokens,
                cached_tokens: record.cached_tokens,
@@ -11,10 +11,9 @@ use crate::{
        provider_credentials::{
            AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
            CredentialDeletionResult, CredentialDetails, CredentialImportCommit,
-            CredentialImportResult, CredentialListQuery, CredentialMutation,
-            CredentialMutationResult, CredentialPage, ImportCredentials, PrepareCredentialImport,
-            PrepareCredentialRotation, PreparedAuthorizationCredential, ProviderQuotaRequest,
-            RotateCredential, StartAuthorization,
+            CredentialImportResult, CredentialListQuery, CredentialMutationResult, CredentialPage,
+            ImportCredentials, PrepareCredentialImport, PrepareCredentialRotation,
+            ProviderQuotaRequest, RotateCredential, StartAuthorization,
        },
    },
    ports::{provider::ProviderAdmin, store::AccountStore},
@@ -23,8 +22,7 @@ use crate::{
 use super::{
    commit_authorization, commit_credential_rotation, delete_credentials, map_provider_error,
    map_store_error, pending_authorization, publish_committed, required_credential,
-    set_credential_enabled, validate_authorization_commit, validate_prepared_import,
-    validate_prepared_rotation,
+    validate_authorization_commit, validate_prepared_import, validate_prepared_rotation,
 };

 /// OpenAI 固定管理路由消费的服务。
@@ -51,14 +49,6 @@ pub trait OpenAiService: Send + Sync {
        &self,
        command: RotateCredential,
    ) -> Result<CredentialMutationResult, AdminError>;
-    async fn enable(
-        &self,
-        command: CredentialMutation,
-    ) -> Result<CredentialMutationResult, AdminError>;
-    async fn disable(
-        &self,
-        command: CredentialMutation,
-    ) -> Result<CredentialMutationResult, AdminError>;
    async fn delete(
        &self,
        command: CredentialDeletion,
@@ -85,25 +75,29 @@ impl DefaultOpenAiService {
        }
    }

-    async fn observe_initial_quotas(&self, account_ids: &[ProviderAccountId], request_id: &str) {
-        for account_id in account_ids {
-            if let Err(error) = self
-                .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"
-                );
+    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"
+                    );
+                }
            }
-        }
+        });
    }
 }

@@ -151,10 +145,12 @@ impl OpenAiService for DefaultOpenAiService {
            .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)
-            .await;
+        self.observe_initial_quotas(&result.credential_ids, &context.request_id);
        Ok(result)
    }

@@ -192,10 +188,6 @@ impl OpenAiService for DefaultOpenAiService {
            "OpenAI authorization",
        )
        .await?;
-        let creates_account = matches!(
-            &prepared.credential,
-            PreparedAuthorizationCredential::Create(_)
-        );
        let result = commit_authorization(
            self.accounts.as_ref(),
            prepared,
@@ -203,14 +195,14 @@ impl OpenAiService for DefaultOpenAiService {
            "OpenAI authorization",
        )
        .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        if creates_account {
-            self.observe_initial_quotas(
-                std::slice::from_ref(&result.account_id),
-                &context.request_id,
-            )
+        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)
    }

@@ -244,38 +236,9 @@ impl OpenAiService for DefaultOpenAiService {
            "OpenAI credential rotation",
        )
        .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        Ok(result)
-    }
-
-    async fn enable(
-        &self,
-        command: CredentialMutation,
-    ) -> Result<CredentialMutationResult, AdminError> {
-        let result = set_credential_enabled(
-            self.accounts.as_ref(),
-            self.provider.as_ref(),
-            command,
-            true,
-            "OpenAI credential",
-        )
-        .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        Ok(result)
-    }
-
-    async fn disable(
-        &self,
-        command: CredentialMutation,
-    ) -> Result<CredentialMutationResult, AdminError> {
-        let result = set_credential_enabled(
-            self.accounts.as_ref(),
-            self.provider.as_ref(),
-            command,
-            false,
-            "OpenAI credential",
-        )
-        .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)
    }
@@ -11,8 +11,8 @@ use crate::{
        provider_credentials::{
            AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
            CredentialDeletionResult, CredentialImportCommit, CredentialImportResult,
-            CredentialListQuery, CredentialMutation, CredentialMutationResult, CredentialPage,
-            ImportCredentials, PrepareCredentialImport, ProviderQuotaRequest, StartAuthorization,
+            CredentialListQuery, CredentialMutationResult, CredentialPage, ImportCredentials,
+            PrepareCredentialImport, ProviderQuotaRequest, StartAuthorization,
        },
    },
    ports::{provider::ProviderAdmin, store::AccountStore},
@@ -20,8 +20,8 @@ use crate::{

 use super::{
    commit_authorization, delete_credentials, map_provider_error, map_store_error,
-    pending_authorization, publish_committed, set_credential_enabled,
-    validate_authorization_commit, validate_prepared_import,
+    pending_authorization, publish_committed, validate_authorization_commit,
+    validate_prepared_import,
 };

 /// xAI 固定管理路由消费的服务。
@@ -40,14 +40,6 @@ pub trait XaiService: Send + Sync {
        &self,
        command: CompleteAuthorization,
    ) -> Result<CredentialMutationResult, AdminError>;
-    async fn enable(
-        &self,
-        command: CredentialMutation,
-    ) -> Result<CredentialMutationResult, AdminError>;
-    async fn disable(
-        &self,
-        command: CredentialMutation,
-    ) -> Result<CredentialMutationResult, AdminError>;
    async fn delete(
        &self,
        command: CredentialDeletion,
@@ -166,38 +158,6 @@ impl XaiService for DefaultXaiService {
        Ok(result)
    }

-    async fn enable(
-        &self,
-        command: CredentialMutation,
-    ) -> Result<CredentialMutationResult, AdminError> {
-        let result = set_credential_enabled(
-            self.accounts.as_ref(),
-            self.provider.as_ref(),
-            command,
-            true,
-            "xAI credential",
-        )
-        .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        Ok(result)
-    }
-
-    async fn disable(
-        &self,
-        command: CredentialMutation,
-    ) -> Result<CredentialMutationResult, AdminError> {
-        let result = set_credential_enabled(
-            self.accounts.as_ref(),
-            self.provider.as_ref(),
-            command,
-            false,
-            "xAI credential",
-        )
-        .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        Ok(result)
-    }
-
    async fn delete(
        &self,
        command: CredentialDeletion,
@@ -0,0 +1,5 @@
+//! 备份模块测试：镜像 src/backup/ 的 policy 与 task。
+
+mod policy;
+pub mod support;
+mod task;
@@ -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());
+}
@@ -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(),
+    }
+}
@@ -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::engine::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());
+}
@@ -6,17 +6,21 @@ use gateway_core::engine::credential::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]
@@ -125,12 +129,102 @@ fn representative_quota_should_prefer_short_window_and_highest_usage() {
            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_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(),
+            source: 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>,
@@ -141,9 +235,11 @@ fn quota_window(
        group: group.to_owned(),
        label: group.to_owned(),
        source: None,
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
        window_seconds,
        used_percent,
        reset_at: None,
+        limit_reached: false,
        local_usage: None,
        provider_data: None,
    }
@@ -0,0 +1,104 @@
+//! 备份领域模型（model/backup.rs）的纯逻辑测试。
+
+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());
+}
@@ -0,0 +1,3 @@
+//! 模型模块测试：镜像 src/model/ 中带逻辑的模块。
+
+mod backup;
@@ -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);
+}
@@ -1,5 +1,6 @@
 mod accounts;
 mod auth;
+mod backup;
 mod client_keys;
 mod observability;
 mod openai;
@@ -13,14 +14,20 @@ use std::{
 };

 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, AccountGroupMutation, AccountGroupPage, DeleteAccountGroup,
+            NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+        },
        accounts::{
-            AccountListQuery, AccountPage, AccountRecord, AccountUsage, AccountUsageWindowQuery,
-            AccountUsageWindowResult, DeleteAccounts, SetAccountEnabled,
+            AccountListQuery, AccountPage, AccountUpdateResult, AccountUsage,
+            AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
+            BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
        },
        auth::{AdminAuditEvent, AdminSession},
        client_keys::{
@@ -46,10 +53,11 @@ use gateway_admin::{
        system::{SystemOperationAccepted, SystemUpdateDetail, SystemUpdateStatus, SystemVersion},
    },
    ports::{
+        backup::BackupStorePorts,
        provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind},
        store::{
-            AccountStore, AdminStoreError, AdminStoreErrorKind, AdminStorePorts, AdminStoreResult,
-            AuthStore, ClientKeyStore, ObservabilityStore, SettingsStore,
+            AccountGroupStore, AccountStore, AdminStoreError, AdminStoreErrorKind, AdminStorePorts,
+            AdminStoreResult, AuthStore, ClientKeyStore, ObservabilityStore, SettingsStore,
        },
        system::{
            SystemOperationError, SystemOperationErrorKind, SystemOperations,
@@ -60,7 +68,7 @@ use gateway_admin::{
 use gateway_core::{
    engine::{
        credential::ProviderAccountId,
-        probe::{AccountProbe, AccountProbeRequest, AccountProbeResult},
+        probe::{AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult},
    },
    error::{GatewayError, GatewayErrorKind},
    policy::ClientApiKeyId,
@@ -75,6 +83,7 @@ pub(super) struct AdminHarness {
    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>,
@@ -91,6 +100,7 @@ impl AdminHarness {
            client_keys: unavailable.clone(),
            observability: unavailable.clone(),
            settings: unavailable,
+            backup: BackupStorePorts::disabled(),
            providers: vec![
                Arc::new(UnavailableProvider::new("openai")),
                Arc::new(UnavailableProvider::new("xai")),
@@ -135,6 +145,11 @@ impl AdminHarness {
        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());
@@ -161,10 +176,12 @@ impl AdminHarness {
            },
            AdminStorePorts::new(
                self.accounts,
+                Arc::new(UnavailableAccountGroupStore),
                self.auth,
                self.client_keys,
                self.observability,
                self.settings,
+                self.backup,
            ),
            self.providers,
            Arc::new(NoopSnapshot),
@@ -224,13 +241,60 @@ impl AuthStore for BootstrapAuthStore {

 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 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) -> AdminStoreResult<AccountPage> {
        Err(unavailable("accounts"))
    }

-    async fn load_account(&self, _: &str) -> AdminStoreResult<Option<AccountRecord>> {
+    async fn load_account(
+        &self,
+        _: &str,
+    ) -> AdminStoreResult<Option<gateway_admin::model::accounts::AccountPageItem>> {
        Err(unavailable("account"))
    }

@@ -305,14 +369,30 @@ impl AccountStore for UnavailableStore {
        Err(unavailable("credential refresh"))
    }

-    async fn set_account_enabled(
+    async fn update_account(
        &self,
-        _: SetAccountEnabled,
+        _: UpdateAccount,
        _: &MutationContext,
-    ) -> AdminStoreResult<Revision> {
+    ) -> 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,
@@ -378,7 +458,11 @@ impl ClientKeyStore for UnavailableStore {

 #[async_trait]
 impl ObservabilityStore for UnavailableStore {
-    async fn dashboard_summary(&self, _: TimeRange) -> AdminStoreResult<DashboardObservation> {
+    async fn dashboard_summary(
+        &self,
+        _: TimeRange,
+        _: DateTime<Utc>,
+    ) -> AdminStoreResult<DashboardObservation> {
        Err(unavailable("dashboard"))
    }

@@ -647,12 +731,13 @@ impl AccountProbe for UnavailableProbe {
    fn probe(
        &self,
        _: AccountProbeRequest,
-    ) -> BoxFuture<'_, Result<AccountProbeResult, GatewayError>> {
+    ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
        Box::pin(async {
            Err(GatewayError::new(
                GatewayErrorKind::Internal,
                "test account probe is unavailable",
-            ))
+            )
+            .into())
        })
    }
 }
@@ -183,7 +183,8 @@ 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 {
-        active_accounts: 3,
+        inherited_accounts: 2,
+        overridden_slots: 5,
        used_slots: Some(2),
    }));
    let services = observability_services(store).await;
@@ -195,9 +196,28 @@ async fn dashboard_summary_should_project_rebuildable_runtime_slots() {
        .expect("dashboard summary")
        .capacity;

-    assert_eq!(capacity.total_slots, 3);
+    assert_eq!(capacity.total_slots, 7);
    assert_eq!(capacity.used_slots, Some(2));
-    assert_eq!(capacity.available_slots, Some(1));
+    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]
@@ -249,6 +269,7 @@ async fn observability_services_should_calculate_usage_insights_and_diagnostic_s
        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),
@@ -326,9 +347,19 @@ async fn usage_records_should_tolerate_records_that_fail_billing_enrichment() {
    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
    let invalid_kind = "x".repeat(65);
    store.replace_usage_records(vec![
-        calculated_total_record("request_invalid_kind", Some(&invalid_kind), now),
-        calculated_total_record("request_unregistered_kind", Some("anthropic"), now),
-        calculated_total_record("request_enriched", Some("openai"), now),
+        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;

@@ -353,12 +384,38 @@ async fn usage_records_should_tolerate_records_that_fail_billing_enrichment() {
    );
 }

+#[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(_))
+    ));
+}
+
 struct FixtureObservabilityStore {
    trend: Mutex<Vec<RequestMetricPoint>>,
    overview: Mutex<UsageOverview>,
    calculated_billing_facts: Mutex<Vec<UsageCalculatedBillingFact>>,
    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<UsageRecord>>,
 }

@@ -375,6 +432,8 @@ impl FixtureObservabilityStore {
            calculated_billing_facts: Mutex::new(Vec::new()),
            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()),
        }
    }
@@ -402,6 +461,16 @@ impl FixtureObservabilityStore {
        *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<UsageRecord>) {
        *self.usage_records.lock().expect("usage records") = records;
    }
@@ -409,11 +478,20 @@ impl FixtureObservabilityStore {

 #[async_trait]
 impl ObservabilityStore for FixtureObservabilityStore {
-    async fn dashboard_summary(&self, range: TimeRange) -> AdminStoreResult<DashboardObservation> {
+    async fn dashboard_summary(
+        &self,
+        range: TimeRange,
+        observed_at: DateTime<Utc>,
+    ) -> AdminStoreResult<DashboardObservation> {
+        *self
+            .summary_observed_at
+            .lock()
+            .expect("summary observed at") = Some(observed_at);
        Ok(DashboardObservation {
            range,
            requests: RequestMetrics::default(),
            attempts: AttemptMetrics::default(),
+            totals: Default::default(),
            provider_accounts: AccountPoolMetrics::default(),
            trend: self.trend.lock().expect("trend").clone(),
            account_usage: Vec::new(),
@@ -423,8 +501,9 @@ impl ObservabilityStore for FixtureObservabilityStore {

    async fn dashboard_runtime_slots(
        &self,
-        _: DateTime<Utc>,
+        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"))
    }

@@ -566,15 +645,19 @@ fn usage_query(now: DateTime<Utc>) -> UsageQuery {
    }
 }

-fn calculated_total_record(
+fn total_record(
    id: &str,
    provider_kind: Option<&str>,
+    source: &str,
    now: DateTime<Utc>,
 ) -> UsageRecord {
    UsageRecord {
        id: id.to_owned(),
        client_api_key_ref: "key_billing".to_owned(),
        config_revision: 1,
+        routing_scope: "all".to_owned(),
+        routing_group_refs: Vec::new(),
+        routing_group_names_snapshot: Vec::new(),
        protocol: "openai".to_owned(),
        operation: "generate".to_owned(),
        endpoint: "/v1/responses".to_owned(),
@@ -589,6 +672,7 @@ fn calculated_total_record(
        upstream_transport: None,
        http_version: None,
        websocket_pool: None,
+        service_tier: None,
        provider_metadata_json: None,
        attempt_count: 1,
        upstream_send_state: "sent".to_owned(),
@@ -611,11 +695,11 @@ fn calculated_total_record(
        image_input_tokens: None,
        image_output_tokens: None,
        total_tokens: Some(1_000),
-        cost_source: "calculated".to_owned(),
+        cost_source: source.to_owned(),
        cost_amount: None,
        cost_currency: None,
        billing: Some(UsageBilling::Total {
-            source: "calculated".to_owned(),
+            source: source.to_owned(),
            total: CurrencyCost {
                currency: "USD".to_owned(),
                amount: gateway_admin::model::observability::DecimalAmount::from_str("1.25")
@@ -658,6 +742,7 @@ fn health_metric_point(bucket_start: DateTime<Utc>, metrics: RequestMetrics) ->

 fn diagnostic(name: &str, request_count: u64) -> DiagnosticObservation {
    DiagnosticObservation {
+        key: name.to_owned(),
        name: name.to_owned(),
        request_count,
        success_count: request_count,
@@ -665,6 +750,7 @@ fn diagnostic(name: &str, request_count: u64) -> DiagnosticObservation {
        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(),
    }
@@ -5,8 +5,8 @@ use gateway_core::engine::credential::ProviderAccountId;
 use gateway_admin::{
    AdminServices,
    model::provider_credentials::{
-        AuthorizationMutationTarget, CompleteAuthorization, CredentialDeletion, CredentialMutation,
-        ImportCredentials, ProviderQuotaRequest, StartAuthorization,
+        AuthorizationMutationTarget, CompleteAuthorization, CredentialDeletion, ImportCredentials,
+        ProviderQuotaRequest, StartAuthorization,
    },
    ports::provider::ProviderAdminErrorKind,
 };
@@ -15,50 +15,6 @@ use super::accounts::{
    FakeAccountStore, FakeProviderAdmin, context, document, events, recorded, revision,
 };

-#[tokio::test]
-async fn openai_enable_should_use_scoped_store_without_provider_mutation() {
-    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()
-        .enable(mutation("acct_test"))
-        .await
-        .expect("enable credential");
-
-    assert_eq!(
-        recorded(&events),
-        ["store.credential_details", "store.set_enabled"]
-    );
-    assert_eq!(store.audit_requests(), ["request-openai"]);
-}
-
-#[tokio::test]
-async fn openai_disable_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()
-        .disable(mutation("acct_test"))
-        .await
-        .expect("disable credential");
-
-    assert_eq!(
-        recorded(&events),
-        [
-            "store.credential_details",
-            "store.set_enabled",
-            "provider.account_unavailable",
-        ]
-    );
-    assert_eq!(store.audit_requests(), ["request-openai"]);
-}
-
 #[tokio::test]
 async fn openai_delete_should_commit_then_release_provider_resources() {
    let events = events();
@@ -78,31 +34,12 @@ async fn openai_delete_should_commit_then_release_provider_resources() {
            "store.credential_details",
            "store.delete",
            "provider.account_unavailable",
+            "provider.account_facts_changed",
        ]
    );
    assert_eq!(store.audit_requests(), ["request-openai"]);
 }

-#[tokio::test]
-async fn openai_disable_store_failure_should_not_release_provider_resources() {
-    let events = events();
-    let provider = FakeProviderAdmin::new("openai", events.clone());
-    let store = FakeAccountStore::new("openai", events.clone());
-    store.fail_next_commit();
-    let services = service(provider, store).await;
-
-    services
-        .openai()
-        .disable(mutation("acct_test"))
-        .await
-        .expect_err("failed Store transaction");
-
-    assert_eq!(
-        recorded(&events),
-        ["store.credential_details", "store.set_enabled"]
-    );
-}
-
 #[tokio::test]
 async fn openai_import_should_prepare_before_atomic_store_commit() {
    let events = events();
@@ -119,11 +56,14 @@ async fn openai_import_should_prepare_before_atomic_store_commit() {
        .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",
        ]
    );
@@ -155,6 +95,8 @@ async fn openai_import_should_refresh_quota_for_every_imported_account() {
        .await
        .expect("import credentials");

+    await_quota_requests(&provider, 2).await;
+
    assert_eq!(
        result.credential_ids,
        [
@@ -196,6 +138,8 @@ async fn openai_import_should_remain_successful_when_quota_refresh_fails() {
        .await
        .expect("committed import remains successful");

+    await_quota_requests(&provider, 1).await;
+
    assert_eq!(
        result.credential_ids,
        [ProviderAccountId::new("acct_prepared").expect("account ID")]
@@ -229,12 +173,15 @@ async fn openai_authorization_create_should_observe_initial_quota() {
        .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",
        ]
    );
@@ -276,6 +223,8 @@ async fn openai_authorization_create_should_remain_successful_when_initial_quota
        .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);
 }
@@ -314,6 +263,8 @@ async fn openai_authorization_store_failure_should_release_claim_for_retry() {
        .await
        .expect("released claim must permit retry");

+    await_quota_requests(&provider, 1).await;
+
    assert_eq!(
        recorded(&events),
        [
@@ -324,6 +275,7 @@ async fn openai_authorization_store_failure_should_release_claim_for_retry() {
            "provider.complete_authorization",
            "store.commit_authorization",
            "authorization_guard.commit",
+            "provider.account_facts_changed",
            "provider.quota",
        ]
    );
@@ -391,6 +343,8 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
        .await
        .expect("complete reauthorization");

+    await_quota_requests(&provider, 1).await;
+
    assert_eq!(result.credential_revision, Some(revision(3)));

    assert_eq!(
@@ -401,8 +355,11 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
            "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"]);
 }

@@ -414,11 +371,14 @@ async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>)
        .await
 }

-fn mutation(account_id: &str) -> CredentialMutation {
-    CredentialMutation {
-        context: context("request-openai"),
-        account_id: ProviderAccountId::new(account_id).expect("account ID"),
+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 {
@@ -4,36 +4,12 @@ use gateway_core::engine::credential::ProviderAccountId;

 use gateway_admin::{
    AdminServices,
-    model::provider_credentials::{CredentialMutation, ImportCredentials, ProviderQuotaRequest},
+    model::provider_credentials::{ImportCredentials, ProviderQuotaRequest},
    ports::provider::ProviderAdminErrorKind,
 };

 use super::accounts::{FakeAccountStore, FakeProviderAdmin, context, document, events, recorded};

-#[tokio::test]
-async fn xai_disable_should_commit_then_notify_the_stateless_provider() {
-    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()
-        .disable(mutation("acct_test"))
-        .await
-        .expect("disable credential");
-
-    assert_eq!(
-        recorded(&events),
-        [
-            "store.credential_details",
-            "store.set_enabled",
-            "provider.account_unavailable",
-        ]
-    );
-    assert_eq!(store.audit_requests(), ["request-xai"]);
-}
-
 #[tokio::test]
 async fn xai_import_should_prepare_before_atomic_store_commit() {
    let events = events();
@@ -131,10 +107,3 @@ async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>)
        .build()
        .await
 }
-
-fn mutation(account_id: &str) -> CredentialMutation {
-    CredentialMutation {
-        context: context("request-xai"),
-        account_id: ProviderAccountId::new(account_id).expect("account ID"),
-    }
-}
@@ -20,8 +20,9 @@ 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 = ["preserve_order"] }
+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", "time"] }
 tower-http = { version = "0.7.0", features = ["cors", "fs", "request-id", "timeout", "trace"] }
@@ -31,7 +32,9 @@ uuid = { version = "1.23.3", features = ["v7"] }

 [dev-dependencies]
 async-trait = "0.1.89"
-tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt"] }
+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"] }
+tokio-tungstenite = "0.29.0"
 tower = { version = "0.5.3", features = ["util"] }

 [lints]
@@ -0,0 +1,417 @@
+//! Account group HTTP wire and fixed routes.
+
+use std::collections::BTreeMap;
+
+use axum::{
+    Json, Router,
+    extract::{Query, 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, 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,
+    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(),
+        total_usd: usage.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>,
+    Query(query): Query<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>,
+    Json(request): Json<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>,
+    Json(request): Json<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>,
+    Json(request): Json<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>,
+    Json(request): Json<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>,
+    Json(request): Json<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("Invalid account group ID"))
+}
+
+fn group_color(value: &str) -> Result<AccountGroupColor, AdminError> {
+    AccountGroupColor::parse(value)
+        .ok_or_else(|| AdminError::bad_request("Invalid account group color"))
+}
+
+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("Invalid account group request"));
+    }
+    Ok(())
+}
+
+fn map_wire_error(_: WireValidationError) -> AdminError {
+    AdminError::bad_request("Invalid account group query")
+}
+
+fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
+    map_admin_service_error(error, "Account group repository unavailable")
+}
@@ -16,11 +16,12 @@ 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, AdminErrorKind, PageSize,
+    AdminError as AdminServiceError, PageSize,
    accounts::{
-        AccountConnectionTestEvent as DomainConnectionTestEvent, AccountCost, AccountListQuery,
-        AccountModelUsage, AccountSort, AccountSortField, AccountStatus as DomainAccountStatus,
-        AccountUsage, SortDirection,
+        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,
@@ -32,11 +33,12 @@ use gateway_admin::model::{
 };
 use gateway_core::{
    engine::credential::{OpaqueProviderData, ProviderAccountId},
-    routing::{ProviderKind, UpstreamModelId},
+    routing::{AccountGroupId, ProviderKind, UpstreamModelId},
 };
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize};
 use serde_json::{Map, Value};

+use super::presenter::{format_compact_number, format_decimal_currency, format_number};
 use super::{
    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState, PageMeta,
    WireValidationError,
@@ -50,8 +52,10 @@ 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;

 /// 账号列表查询参数。
 #[derive(Debug, Clone, Default, Deserialize)]
@@ -60,12 +64,74 @@ 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")]
+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(())
+    }
+
+    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> {
@@ -78,6 +144,14 @@ impl ListQuery {
            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())
@@ -90,7 +164,8 @@ impl ListQuery {
        let status = match self.status.as_deref().map(str::trim) {
            None | Some("") => None,
            Some(value) => Some(
-                parse_account_status(value).ok_or_else(|| WireValidationError::new("status"))?,
+                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()) {
@@ -109,6 +184,7 @@ impl ListQuery {
            )
            .map_err(|_| WireValidationError::new("pageSize"))?,
            provider_kind,
+            group_filter,
            search,
            status,
            sort,
@@ -126,17 +202,6 @@ fn parse_provider(value: &str) -> Result<Option<ProviderKind>, WireValidationErr
        .map_err(|_| WireValidationError::new("provider"))
 }

-fn parse_account_status(value: &str) -> Option<DomainAccountStatus> {
-    match value.trim().to_ascii_lowercase().as_str() {
-        "active" => Some(DomainAccountStatus::Active),
-        "expired" => Some(DomainAccountStatus::Expired),
-        "quota_exhausted" => Some(DomainAccountStatus::QuotaExhausted),
-        "disabled" => Some(DomainAccountStatus::Disabled),
-        "banned" => Some(DomainAccountStatus::Banned),
-        _ => None,
-    }
-}
-
 fn parse_sort_field(value: &str) -> Option<AccountSortField> {
    match value.trim() {
        "email" => Some(AccountSortField::Email),
@@ -171,9 +236,11 @@ pub struct AccountPageData {
 #[serde(rename_all = "camelCase")]
 pub struct AccountSummaryView {
    pub total: u64,
-    pub active: u64,
+    pub normal: u64,
    pub quota_exhausted: u64,
-    pub unavailable: u64,
+    pub rate_limited: u64,
+    pub disabled: u64,
+    pub error: u64,
 }

 /// 一条安全账号视图。
@@ -183,6 +250,7 @@ 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>,
@@ -192,10 +260,13 @@ pub struct AccountView {
    pub authentication_kind: String,
    pub has_refresh_token: bool,
    pub status: String,
-    pub display_status: String,
-    pub token_refreshing: bool,
-    pub availability: 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>,
@@ -208,11 +279,23 @@ pub struct AccountView {
    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>,
 }

@@ -226,6 +309,7 @@ pub struct AccountQuotaWindowView {
    pub 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,
@@ -522,22 +606,25 @@ impl From<DomainConnectionTestEvent> for AccountConnectionTestEvent {
            DomainConnectionTestEvent::Content { text } => {
                serde_json::json!({ "type": "content", "text": text })
            }
-            DomainConnectionTestEvent::Completed { account_status } => serde_json::json!({
+            DomainConnectionTestEvent::Completed => serde_json::json!({
                "type": "test_complete",
-                "success": true,
-                "accountStatus": account_status_name(account_status)
+                "success": true
            }),
            DomainConnectionTestEvent::Failed {
                message,
                provider_error_code,
                provider_error_type,
-                account_status,
+                upstream_status,
+                upstream_content_type,
+                upstream_body,
            } => serde_json::json!({
                "type": "error",
                "error": message,
                "providerErrorCode": provider_error_code,
                "providerErrorType": provider_error_type,
-                "accountStatus": account_status_name(account_status)
+                "upstreamStatus": upstream_status,
+                "upstreamContentType": upstream_content_type,
+                "upstreamBody": upstream_body
            }),
        };
        Self { data }
@@ -680,31 +767,49 @@ impl CompleteAccountAuthorizationRequest {

 #[derive(Debug, Clone, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct AccountMutationRequest {
-    pub provider: String,
+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 AccountMutationRequest {
+impl UpdateAccountRequest {
    pub fn validate(&self) -> Result<(), WireValidationError> {
-        AccountProvider::parse(&self.provider)?;
-        require_account_id(&self.account_id, "accountId")
+        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(())
    }

-    fn into_command(
-        self,
-        context: gateway_admin::model::MutationContext,
-    ) -> Result<(AccountProvider, CredentialMutation), WireValidationError> {
+    fn into_command(self) -> Result<UpdateAccount, WireValidationError> {
        self.validate()?;
-        let provider = AccountProvider::parse(&self.provider)?;
-        Ok((
-            provider,
-            CredentialMutation {
-                context,
-                account_id: ProviderAccountId::new(self.account_id)
-                    .map_err(|_| WireValidationError::new("accountId"))?,
-            },
-        ))
+        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(),
+        }
    }
 }

@@ -759,6 +864,7 @@ pub struct RotateAccountRequest {
    pub account_id: String,
    pub access_token: String,
    pub refresh_token: Option<String>,
+    pub id_token: Option<String>,
 }

 impl RotateAccountRequest {
@@ -767,7 +873,11 @@ impl RotateAccountRequest {
            return Err(WireValidationError::new("provider"));
        }
        require_account_id(&self.account_id, "accountId")?;
-        validate_oauth_material(&self.access_token, self.refresh_token.as_deref())
+        validate_oauth_material(
+            &self.access_token,
+            self.refresh_token.as_deref(),
+            self.id_token.as_deref(),
+        )
    }

    fn into_command(
@@ -781,6 +891,10 @@ impl RotateAccountRequest {
            "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,
@@ -799,8 +913,8 @@ pub struct AccountImportData {
    pub account_ids: Vec<String>,
 }

-impl From<CredentialImportResult> for AccountImportData {
-    fn from(result: CredentialImportResult) -> Self {
+impl AccountImportData {
+    pub fn from_result(result: CredentialImportResult) -> Self {
        let account_ids = result
            .credential_ids
            .into_iter()
@@ -877,6 +991,46 @@ fn require_account_id(value: &str, field: &'static str) -> Result<(), WireValida
    Ok(())
 }

+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()
+}
+
+fn deserialize_required_nullable<'de, D>(deserializer: D) -> Result<Option<u64>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    Option::<u64>::deserialize(deserializer)
+}
+
+fn parse_account_weight(value: u64) -> Result<AccountWeight, WireValidationError> {
+    u16::try_from(value)
+        .ok()
+        .and_then(AccountWeight::new)
+        .ok_or_else(|| WireValidationError::new("weight"))
+}
+
+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()
+}
+
 /// 构造统一账号管理路由。
 pub fn router<S>() -> Router<S>
 where
@@ -888,10 +1042,14 @@ where
        .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/enable", post(enable_account::<S>))
-        .route("/api/admin/accounts/disable", post(disable_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/quota/refresh",
@@ -916,6 +1074,27 @@ where
        )
 }

+async fn batch_update_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    Json(request): Json<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>,
@@ -1005,7 +1184,7 @@ where
    .map_err(map_service_error)?;
    Ok(AdminResponse::new(
        StatusCode::CREATED,
-        AdminEnvelope::ok(AccountImportData::from(result)),
+        AdminEnvelope::ok(AccountImportData::from_result(result)),
    ))
 }

@@ -1100,64 +1279,24 @@ where
    ))
 }

-async fn enable_account<S>(
+async fn update_account<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<AccountMutationRequest>,
+    Json(request): Json<UpdateAccountRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
 {
-    mutate_account(auth, state, request, AccountMutationAction::Enable).await
-}
-
-async fn disable_account<S>(
-    auth: AdminAuth,
-    State(state): State<S>,
-    Json(request): Json<AccountMutationRequest>,
-) -> Result<impl IntoResponse, AdminError>
-where
-    S: AdminSessionState + Send + Sync,
-{
-    mutate_account(auth, state, request, AccountMutationAction::Disable).await
-}
-
-#[derive(Clone, Copy)]
-enum AccountMutationAction {
-    Enable,
-    Disable,
-}
-
-async fn mutate_account<S>(
-    auth: AdminAuth,
-    state: S,
-    request: AccountMutationRequest,
-    action: AccountMutationAction,
-) -> 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, action) {
-        (AccountProvider::OpenAi, AccountMutationAction::Enable) => {
-            state.admin_services().openai().enable(command).await
-        }
-        (AccountProvider::OpenAi, AccountMutationAction::Disable) => {
-            state.admin_services().openai().disable(command).await
-        }
-        (AccountProvider::Xai, AccountMutationAction::Enable) => {
-            state.admin_services().xai().enable(command).await
-        }
-        (AccountProvider::Xai, AccountMutationAction::Disable) => {
-            state.admin_services().xai().disable(command).await
-        }
-    }
-    .map_err(map_service_error)?;
+    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(AccountMutationData::from(result)),
+        AdminEnvelope::ok(UpdatedAccountData::from(result)),
    ))
 }

@@ -1202,6 +1341,25 @@ where
    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
 }

+async fn recover_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    Json(request): Json<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>,
@@ -1325,9 +1483,11 @@ fn account_page_data(
        page: PageMeta::new(page, u32::from(page_size), result.total, total_pages),
        summary: AccountSummaryView {
            total: result.summary.total,
-            active: result.summary.active,
+            normal: result.summary.normal,
            quota_exhausted: result.summary.quota_exhausted,
-            unavailable: result.summary.unavailable,
+            rate_limited: result.summary.rate_limited,
+            disabled: result.summary.disabled,
+            error: result.summary.error,
        },
    }
 }
@@ -1357,32 +1517,46 @@ fn account_models_data(result: ProviderModels) -> AccountModelsData {
 fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> AccountView {
    let AccountDirectoryItem {
        account,
-        status,
+        projection,
        usage,
        quota,
    } = item;
-    let status = account_status_name(status).to_owned();
+    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, now);
+    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: Some(account.upstream_user_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: status.clone(),
-        display_status: status,
-        token_refreshing: false,
-        availability: account.availability.as_str().to_owned(),
+        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
@@ -1400,9 +1574,11 @@ fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> AccountView {
 }

 fn account_quota_view(
-    quota: ProviderQuota,
+    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));
@@ -1410,9 +1586,12 @@ fn account_quota_view(
        .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,
@@ -1425,9 +1604,11 @@ fn quota_window_view(window: ProviderQuotaWindow) -> AccountQuotaWindowView {
        group,
        label,
        source: _,
+        local_usage_attribution: _,
        window_seconds,
        used_percent,
        reset_at,
+        limit_reached,
        local_usage,
        provider_data: _,
    } = window;
@@ -1439,6 +1620,7 @@ fn quota_window_view(window: ProviderQuotaWindow) -> AccountQuotaWindowView {
        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)),
    }
@@ -1462,7 +1644,7 @@ fn quota_local_usage(usage: &AccountUsage) -> Value {
        "imageRequestCount": usage.image_request_count,
        "imageRequestFailedCount": usage.image_request_failed_count,
        "totalTokens": total_tokens,
-        "totalTokensDisplay": format_tokens(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,
@@ -1574,7 +1756,7 @@ fn account_model_usage_view(usage: AccountModelUsage, now: DateTime<Utc>) -> Mod
        billing_amount_usd: usd.map(|cost| cost.amount.as_str().to_owned()),
        billing_amount_usd_display: usd.map_or_else(
            || "—".to_owned(),
-            |cost| format!("${}", cost.amount.as_str()),
+            |cost| format_decimal_currency(cost.amount.as_str(), "USD"),
        ),
        cost_estimate_status: cost_estimate_status.to_owned(),
        known_cost_count: known_count,
@@ -1595,7 +1777,7 @@ fn account_currency_cost_view(cost: &AccountCost) -> CurrencyCostView {
 }

 fn display_optional_tokens(value: Option<u64>) -> String {
-    value.map_or_else(|| "—".to_owned(), format_tokens)
+    value.map_or_else(|| "—".to_owned(), format_compact_number)
 }

 fn empty_account_usage() -> AccountUsageView {
@@ -1669,6 +1851,7 @@ fn require_text(
 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)
@@ -1683,6 +1866,13 @@ fn validate_oauth_material(
    }) {
        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(())
 }

@@ -1703,47 +1893,6 @@ fn provider_document_value(document: ProviderDocument) -> Value {
    Value::Object(document.into_provider_data().into_inner())
 }

-fn account_status_name(status: DomainAccountStatus) -> &'static str {
-    match status {
-        DomainAccountStatus::Active => "active",
-        DomainAccountStatus::Expired => "expired",
-        DomainAccountStatus::QuotaExhausted => "quota_exhausted",
-        DomainAccountStatus::Disabled => "disabled",
-        DomainAccountStatus::Banned => "banned",
-    }
-}
-
-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()
-}
-
-fn format_tokens(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)
-}
-
 fn relative_time(value: DateTime<Utc>, now: DateTime<Utc>) -> String {
    let elapsed = now.signed_duration_since(value);
    if elapsed.num_seconds() < 0 {
@@ -1781,16 +1930,5 @@ fn map_wire_error(error: WireValidationError) -> AdminError {
 }

 fn map_service_error(error: AdminServiceError) -> AdminError {
-    match error.kind() {
-        AdminErrorKind::Invalid => AdminError::bad_request(error.to_string()),
-        AdminErrorKind::Unauthorized => AdminError::admin_session_required(),
-        AdminErrorKind::NotFound => AdminError::not_found(error.to_string()),
-        AdminErrorKind::Conflict => AdminError::conflict(error.to_string()),
-        AdminErrorKind::RateLimited => AdminError::too_many_login_attempts(),
-        AdminErrorKind::BadGateway => AdminError::bad_gateway(error.to_string()),
-        AdminErrorKind::Unavailable => {
-            AdminError::service_unavailable("Account directory unavailable")
-        }
-        AdminErrorKind::Internal => AdminError::internal(error.to_string()),
-    }
+    super::wire::map_admin_service_error(error, "Account directory unavailable")
 }
@@ -0,0 +1,459 @@
+//! 备份设置、计划、手动创建、记录、下载与删除路由。
+//!
+//! 路径统一位于 `/api/admin/settings/backups/*`，内部由独立 `BackupService` 承担业务。
+
+use axum::{
+    Json, Router,
+    extract::{Query, 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, AdminPageData, 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>,
+    Json(request): Json<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>,
+    Json(request): Json<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>,
+    Query(query): Query<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("Invalid pageSize"))?;
+    let page = query.page.unwrap_or(1);
+    if page == 0 {
+        return Err(AdminError::bad_request("Invalid page"));
+    }
+    let status = match query.status.as_deref() {
+        None => None,
+        Some(value) => BackupStatus::parse(value)
+            .map(Some)
+            .ok_or_else(|| AdminError::bad_request("Invalid status"))?,
+    };
+    let trigger = match query.trigger.as_deref() {
+        None => None,
+        Some(value) => BackupTriggerKind::parse(value)
+            .map(Some)
+            .ok_or_else(|| AdminError::bad_request("Invalid 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<Json<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>,
+    Json(request): Json<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>,
+    Json(request): Json<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, "Backup service unavailable")
+}
@@ -12,7 +12,7 @@ use gateway_admin::model::client_keys::{
 };
 use gateway_core::{
    policy::{ClientApiKeyId, RateLimits},
-    routing::ProviderKind,
+    routing::AccountGroupId,
 };
 use serde::{Deserialize, Serialize};

@@ -137,7 +137,7 @@ impl ClientKeySort {
 pub struct CreateClientKeyRequest {
    name: String,
    label: Option<String>,
-    provider_kind: String,
+    group_ids: Vec<String>,
    max_concurrency: u64,
    requests_per_minute: u64,
 }
@@ -147,14 +147,13 @@ impl CreateClientKeyRequest {
    pub fn into_command(self) -> Result<CreateClientKey, WireValidationError> {
        validate_required_text(&self.name, "name")?;
        validate_optional_text(self.label.as_deref(), "label")?;
-        validate_provider_kind(&self.provider_kind)?;
+        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,
-            provider_kind: ProviderKind::new(self.provider_kind)
-                .map_err(|_| WireValidationError::new("providerKind"))?,
+            group_ids,
            limits: RateLimits {
                max_concurrency: self.max_concurrency,
                requests_per_minute: self.requests_per_minute,
@@ -170,7 +169,7 @@ pub struct UpdateClientKeyRequest {
    id: String,
    name: String,
    label: Option<String>,
-    provider_kind: String,
+    group_ids: Vec<String>,
    max_concurrency: u64,
    requests_per_minute: u64,
 }
@@ -181,15 +180,14 @@ impl UpdateClientKeyRequest {
        validate_required_text(&self.id, "id")?;
        validate_required_text(&self.name, "name")?;
        validate_optional_text(self.label.as_deref(), "label")?;
-        validate_provider_kind(&self.provider_kind)?;
+        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,
-            provider_kind: ProviderKind::new(self.provider_kind)
-                .map_err(|_| WireValidationError::new("providerKind"))?,
+            group_ids,
            limits: RateLimits {
                max_concurrency: self.max_concurrency,
                requests_per_minute: self.requests_per_minute,
@@ -242,7 +240,9 @@ pub struct ClientKeyView {
    id: String,
    name: String,
    label: Option<String>,
-    provider_kind: String,
+    routing_scope: &'static str,
+    groups: Vec<ClientKeyGroupView>,
+    provider_kinds: Vec<String>,
    prefix: String,
    enabled: bool,
    max_concurrency: u64,
@@ -252,13 +252,42 @@ pub struct ClientKeyView {
    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,
-            provider_kind: record.provider_kind.to_string(),
+            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,
@@ -572,21 +601,20 @@ fn validate_required_text(value: &str, field: &'static str) -> Result<(), WireVa
    Ok(())
 }

-fn validate_provider_kind(value: &str) -> Result<(), WireValidationError> {
-    let valid = !value.is_empty()
-        && value.len() <= 64
-        && value.bytes().enumerate().all(|(index, byte)| {
-            byte.is_ascii_lowercase()
-                || byte.is_ascii_digit()
-                || (byte == b'-' && index > 0 && index + 1 < value.len())
-        })
-        && !value.starts_with('-')
-        && !value.ends_with('-');
-    if valid {
-        Ok(())
-    } else {
-        Err(WireValidationError::new("providerKind"))
+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(
@@ -7,10 +7,13 @@ use axum::{
    response::Response,
 };

+pub mod account_groups;
 pub mod accounts;
 pub mod auth;
+pub mod backups;
 pub mod client_keys;
 pub mod observability;
+pub mod presenter;
 pub mod settings;
 pub mod system;
 pub mod wire;
@@ -27,8 +30,10 @@ 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>())
@@ -0,0 +1,32 @@
+//! Dashboard、用量与诊断查询的 wire 映射和固定路由。
+
+use std::{collections::BTreeMap, num::NonZeroU32};
+
+use axum::{
+    Router,
+    extract::{Query, State},
+    http::StatusCode,
+    response::IntoResponse,
+    routing::get,
+};
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+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, AdminResponse, AdminSessionState, PageMeta,
+    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::*;
@@ -0,0 +1,453 @@
+//! 查询 wire 类型、校验与领域命令映射。
+
+use super::*;
+
+use base64::Engine as _;
+
+/// 观测列表默认页大小。
+pub const DEFAULT_PAGE_SIZE: u16 = 50;
+/// 观测列表允许的最大页大小。
+pub const MAX_PAGE_SIZE: u16 = 100;
+/// 游标编码在 HTTP 层解码前允许的最大长度。
+pub const MAX_CURSOR_BYTES: usize = 1024;
+
+/// 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 page: Option<u32>,
+    pub page_size: Option<u16>,
+    pub cursor: Option<String>,
+    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 {
+    /// 校验分页字段，不改变仓储层的分页 owner。
+    pub fn validate_page(&self) -> Result<(u32, u16), 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"));
+        }
+        Ok((page, page_size))
+    }
+
+    /// 校验游标的 wire 边界；编码和排序语义由应用层负责。
+    pub fn validate_cursor(&self) -> Result<(), WireValidationError> {
+        validate_cursor(self.cursor.as_deref())
+    }
+}
+
+/// 详情查询参数。
+#[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 page: Option<u32>,
+    pub page_size: Option<u16>,
+    pub cursor: Option<String>,
+    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 route: 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 failure_class: Option<String>,
+    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 {
+    /// 校验分页字段。
+    pub fn validate_page(&self) -> Result<(u32, u16), 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"));
+        }
+        Ok((page, page_size))
+    }
+
+    /// 校验游标的 wire 边界。
+    pub fn validate_cursor(&self) -> Result<(), WireValidationError> {
+        validate_cursor(self.cursor.as_deref())
+    }
+}
+
+/// 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 validate_cursor(value: Option<&str>) -> Result<(), WireValidationError> {
+    if value.is_some_and(|value| value.is_empty() || value.len() > MAX_CURSOR_BYTES) {
+        return Err(WireValidationError::new("cursor"));
+    }
+    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, u32, u16), WireValidationError> {
+    let (page, page_size) = query.validate_page()?;
+    query.validate_cursor()?;
+    let page_number = NonZeroU32::new(page)
+        .map(domain::PageNumber::new)
+        .ok_or_else(|| WireValidationError::new("page"))?;
+    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)?,
+            cursor: decode_observability_cursor(query.cursor.as_deref())?,
+            page: page_number,
+            page_size: page_size_value,
+        },
+        page,
+        page_size,
+    ))
+}
+
+pub(crate) fn ops_command(
+    query: &OpsQuery,
+) -> Result<(domain::OpsErrorQuery, u32, u16), WireValidationError> {
+    let (page, page_size) = query.validate_page()?;
+    query.validate_cursor()?;
+    let page_number = NonZeroU32::new(page)
+        .map(domain::PageNumber::new)
+        .ok_or_else(|| WireValidationError::new("page"))?;
+    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.route.clone()).or_else(|| 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()),
+                failure_kind: non_empty(query.failure_class.clone()),
+                status_code,
+                search: non_empty(query.search.clone()),
+            },
+            cursor: decode_observability_cursor(query.cursor.as_deref())?,
+            page: page_number,
+            page_size: page_size_value,
+        },
+        page,
+        page_size,
+    ))
+}
+
+pub(crate) fn decode_observability_cursor(
+    value: Option<&str>,
+) -> Result<Option<domain::ObservabilityCursor>, WireValidationError> {
+    value
+        .map(|encoded| {
+            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 wire: CursorWire =
+                serde_json::from_slice(&bytes).map_err(|_| WireValidationError::new("cursor"))?;
+            if wire.stable_id.trim().is_empty() {
+                return Err(WireValidationError::new("cursor"));
+            }
+            Ok(domain::ObservabilityCursor {
+                observed_at: wire.observed_at,
+                stable_id: wire.stable_id,
+            })
+        })
+        .transpose()
+}
+
+pub(crate) fn encode_observability_cursor(
+    cursor: &domain::ObservabilityCursor,
+) -> Result<String, WireValidationError> {
+    let bytes = serde_json::to_vec(&CursorWire {
+        observed_at: cursor.observed_at,
+        stable_id: cursor.stable_id.clone(),
+    })
+    .map_err(|_| WireValidationError::new("cursor"))?;
+    Ok(URL_SAFE_NO_PAD.encode(bytes))
+}
+
+pub(crate) fn non_empty(value: Option<String>) -> Option<String> {
+    value
+        .map(|value| value.trim().to_owned())
+        .filter(|value| !value.is_empty())
+}
@@ -0,0 +1,214 @@
+//! 固定 `/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>,
+    Query(query): Query<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>,
+    Query(query): Query<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>,
+    Query(query): Query<UsageQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (command, page, page_size) = 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, page, page_size)
+        .map_err(|_| AdminError::internal("Failed to encode observability cursor"))?;
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+pub(crate) async fn usage_record_detail<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    Query(query): Query<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>,
+    Query(query): Query<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>,
+    Query(query): Query<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>,
+    Query(query): Query<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>,
+    Query(query): Query<OpsQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (command, page, page_size) = 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, page, page_size)
+        .map_err(|_| AdminError::internal("Failed to encode observability cursor"))?;
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
@@ -0,0 +1,712 @@
+//! 响应 DTO 与固定 wire 形状。
+
+use super::*;
+
+/// 观测列表游标的稳定 wire 形状。
+#[derive(Clone, Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct CursorWire {
+    pub observed_at: DateTime<Utc>,
+    pub stable_id: String,
+}
+
+/// 观测列表响应数据。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PageData<T> {
+    pub items: Vec<T>,
+    pub page: PageMeta,
+    pub next_cursor: Option<String>,
+}
+
+/// 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 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: String,
+    pub requested_model: Option<String>,
+    pub upstream_model: Option<String>,
+    pub service_tier: Option<String>,
+    pub status_code: Option<i64>,
+    pub 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 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: 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 {
+    #[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>,
+}
+
+/// 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 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<UsageRecordView>,
+    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 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 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>,
+}
+
+/// 洞察性能摘要。
+#[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 latency_coverage: f64,
+    pub first_token_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 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 cost_per_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 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 provider: Option<String>,
+    pub authentication_kind: Option<String>,
+    pub account_id: Option<String>,
+    pub route: String,
+    pub model: 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 response_id: Option<String>,
+    pub upstream_request_id: Option<String>,
+    pub latency_ms: Option<u64>,
+    pub message: 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>,
+}
@@ -0,0 +1,71 @@
+//! Admin API 的展示层辅助：数值格式化。
+//!
+//! 按 docs/project-redundancy-boundary-audit.md BE-02 的目标，display 字段最终
+//! 迁移到前端；过渡期统一由本模块提供，避免 accounts/observability 各自维护。
+
+use gateway_core::accounting::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}")
+}
@@ -72,10 +72,7 @@ impl UpdateRuntimeSettingsRequest {
        if i64::try_from(self.request_interval_ms).is_err() {
            return Err(WireValidationError::new("requestIntervalMs"));
        }
-        if !matches!(
-            self.rotation_strategy.as_str(),
-            "smart" | "quota_reset_priority" | "round_robin" | "sticky"
-        ) {
+        if RotationStrategy::parse(&self.rotation_strategy).is_none() {
            return Err(WireValidationError::new("rotationStrategy"));
        }
        Ok(())
@@ -91,7 +88,7 @@ impl UpdateRuntimeSettingsRequest {
            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: parse_rotation_strategy(&self.rotation_strategy)
+            rotation_strategy: RotationStrategy::parse(&self.rotation_strategy)
                .ok_or_else(|| WireValidationError::new("rotationStrategy"))?,
            usage_retention_days: u32::try_from(self.usage_retention_days)
                .map_err(|_| WireValidationError::new("settingsUsageRetentionOverflow"))?,
@@ -111,7 +108,7 @@ impl From<RuntimeSettings> for RuntimeSettingsView {
            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: rotation_strategy_name(settings.rotation_strategy).to_owned(),
+            rotation_strategy: settings.rotation_strategy.as_str().to_owned(),
            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),
@@ -319,25 +316,6 @@ fn wire_model_mappings(mappings: DomainModelMappings) -> ModelMappings {
        .collect()
 }

-fn parse_rotation_strategy(value: &str) -> Option<RotationStrategy> {
-    match value {
-        "smart" => Some(RotationStrategy::Smart),
-        "quota_reset_priority" => Some(RotationStrategy::QuotaResetPriority),
-        "round_robin" => Some(RotationStrategy::RoundRobin),
-        "sticky" => Some(RotationStrategy::Sticky),
-        _ => None,
-    }
-}
-
-const fn rotation_strategy_name(strategy: RotationStrategy) -> &'static str {
-    match strategy {
-        RotationStrategy::Smart => "smart",
-        RotationStrategy::QuotaResetPriority => "quota_reset_priority",
-        RotationStrategy::RoundRobin => "round_robin",
-        RotationStrategy::Sticky => "sticky",
-    }
-}
-
 fn valid_model_name(value: &str, max_len: usize) -> bool {
    !value.is_empty()
        && value.len() <= max_len
@@ -9,7 +9,7 @@ use std::sync::Arc;
 use std::time::Duration;

 use axum::Router;
-use axum::http::{HeaderName, HeaderValue, Method, StatusCode};
+use axum::http::{HeaderName, HeaderValue, Method, Request, StatusCode};
 use axum::routing::get;
 use gateway_admin::AdminServices;
 use gateway_core::engine::execution::ExecutionService;
@@ -166,10 +166,32 @@ pub fn initialize(
            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_and_query()
+                    .map(axum::http::uri::PathAndQuery::as_str)
+                    .unwrap_or_default(),
+            )
+        }
+    });
    let router = router
        .layer(PropagateRequestIdLayer::new(request_id_header.clone()))
+        .layer(trace_layer)
        .layer(SetRequestIdLayer::new(request_id_header, MakeRequestUuid))
-        .layer(TraceLayer::new_for_http())
        .with_state(state);
    Ok(ApiBundle { router })
 }
@@ -2,12 +2,13 @@

 use axum::{
    Json,
-    http::StatusCode,
+    body::Body,
+    http::{HeaderName, HeaderValue, StatusCode, header::CONTENT_TYPE},
    response::{IntoResponse, Response},
 };
 use gateway_core::{
-    engine::{EngineError, UpstreamSendState},
-    error::{GatewayError, GatewayErrorKind, ProviderErrorKind},
+    engine::EngineError,
+    error::{GatewayError, GatewayErrorKind},
 };
 use serde_json::{Value, json};

@@ -71,19 +72,6 @@ pub fn model_not_found_response() -> (StatusCode, Json<Value>) {
 #[must_use]
 pub fn gateway_error_from_engine(error: &EngineError) -> GatewayError {
    match error {
-        EngineError::Provider(error)
-            if error.kind() == ProviderErrorKind::Unavailable
-                && error.send_state() == UpstreamSendState::NotSent =>
-        {
-            let gateway = GatewayError::new(
-                GatewayErrorKind::NoAvailableProvider,
-                "no upstream provider is currently available for this request",
-            );
-            match error.client_visible_upstream_error() {
-                Some(upstream) => gateway.with_client_visible_upstream_error(upstream.clone()),
-                None => gateway,
-            }
-        }
        EngineError::Provider(error) => GatewayError::from_provider(error),
        EngineError::Cancelled => {
            GatewayError::new(GatewayErrorKind::Cancelled, "request was cancelled")
@@ -101,6 +89,7 @@ pub fn gateway_error_from_engine(error: &EngineError) -> GatewayError {
        | EngineError::ProviderMetadataMismatch
        | EngineError::ContinuationPinMismatch
        | EngineError::RequiredAccountMismatch
+        | EngineError::AccountOutsideClientScope
        | EngineError::DownstreamCommitRequired
        | EngineError::NoActiveAttempt
        | EngineError::InvalidDeliveryState => {
@@ -121,6 +110,33 @@ pub fn gateway_error_response(error: &GatewayError) -> Response {
    .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(
@@ -157,6 +173,16 @@ pub const fn gateway_error_contract(
            "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",
@@ -152,9 +152,6 @@ pub enum ResponseEncodeError {
    /// 协议原生流缺少可返回的终态 response object。
    #[error("responses wire stream has no terminal response")]
    MissingWireTerminal,
-    /// 协议原生事件携带了不一致的响应身份。
-    #[error("responses wire stream changed its response identity")]
-    WireIdentityChanged,
    /// 终态 response object 无法序列化为完整 HTTP JSON 响应。
    #[error("responses wire terminal serialization failed")]
    Serialization,
@@ -167,7 +164,7 @@ impl ResponseEncodeError {
        ProtocolErrorBody {
            error: ProtocolError {
                kind: "server_error",
-                code: "invalid_canonical_response",
+                code: "invalid_upstream_response",
                message: "The gateway could not forward the upstream response.".to_owned(),
                param: None,
            },
@@ -8,7 +8,7 @@ use axum::{
    body::{Body, Bytes},
    extract::{Extension, State, connect_info::ConnectInfo},
    http::{
-        HeaderMap, HeaderValue, StatusCode,
+        HeaderMap, HeaderName, HeaderValue, StatusCode,
        header::{CACHE_CONTROL, CONTENT_TYPE, USER_AGENT},
    },
    response::{IntoResponse, Response},
@@ -25,8 +25,8 @@ use crate::ApiState;
 use crate::openai::{
    auth::{authenticate_client, authentication_error_response},
    error::{
-        gateway_error_contract, gateway_error_from_engine, gateway_error_response,
-        protocol_error_response, runtime_unavailable_response,
+        engine_error_response, gateway_error_contract, gateway_error_from_engine,
+        gateway_error_response, protocol_error_response, runtime_unavailable_response,
    },
 };

@@ -180,7 +180,7 @@ pub async fn collect_execution_response(session: Box<dyn ExecutionSession>) -> R
    let events = match session.collect_uncommitted().await {
        Ok(events) => events,
        Err(error) => {
-            let response = gateway_error_response(&gateway_error_from_engine(&error));
+            let response = engine_error_response(&error);
            return execution.record_response_status(response).await;
        }
    };
@@ -206,7 +206,7 @@ pub async fn collect_execution_response(session: Box<dyn ExecutionSession>) -> R
        .await
    {
        execution.cancel_and_finalize().await;
-        let response = gateway_error_response(&gateway_error_from_engine(&error));
+        let response = engine_error_response(&error);
        return execution.record_response_status(response).await;
    }
    if !session.is_finalized() {
@@ -237,9 +237,7 @@ fn encode_collected_events(
 ) -> Result<Vec<u8>, BufferedResponseEncodeError> {
    let mut encoder = OpenAiResponsesEncoder::new();
    for event in events {
-        encoder
-            .push_sse(event)
-            .map_err(BufferedResponseEncodeError::Canonical)?;
+        encoder.push_sse(event);
    }
    let response = encoder
        .finish()
@@ -253,23 +251,25 @@ fn json_body_response(encoded: Vec<u8>, response_headers: &[ProviderResponseHead
    response
        .headers_mut()
        .insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
-    apply_safe_response_headers(response, response_headers)
+    apply_response_headers(response, response_headers)
 }

-fn apply_safe_response_headers(
+fn apply_response_headers(
    mut response: Response,
    response_headers: &[ProviderResponseHeader],
 ) -> Response {
+    let connection_options = super::response_connection_options(response_headers);
    for header in response_headers {
-        let Some(name) = super::safe_response_header_name(header.name()) else {
+        if !super::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_str(header.value().as_str()) else {
+        let Ok(value) = HeaderValue::from_bytes(header.value()) else {
            continue;
        };
-        response
-            .headers_mut()
-            .insert(axum::http::header::HeaderName::from_static(name), value);
+        response.headers_mut().append(name, value);
    }
    response
 }
@@ -295,7 +295,7 @@ pub async fn stream_execution_response(
            return response;
        }
        Err(error) => {
-            let response = gateway_error_response(&gateway_error_from_engine(&error));
+            let response = engine_error_response(&error);
            return execution.record_response_status(response).await;
        }
    };
@@ -310,18 +310,7 @@ pub async fn stream_execution_response(
    let mut encoder = OpenAiResponsesEncoder::new();
    let mut frames = Vec::new();
    for event in &first_events {
-        match encoder.push_sse(event) {
-            Ok(encoded) => frames.extend(encoded),
-            Err(error) => {
-                let response = protocol_error_response(
-                    StatusCode::INTERNAL_SERVER_ERROR,
-                    error.protocol_body(),
-                );
-                let response = execution.record_response_status(response).await;
-                execution.cancel_and_finalize().await;
-                return response;
-            }
-        }
+        frames.extend(encoder.push_sse(event));
    }
    if frames.is_empty() {
        let response = internal_gateway_response("gateway commit batch encoded no output");
@@ -338,7 +327,7 @@ pub async fn stream_execution_response(
        .await
    {
        execution.cancel_and_finalize().await;
-        let response = gateway_error_response(&gateway_error_from_engine(&error));
+        let response = engine_error_response(&error);
        return execution.record_response_status(response).await;
    }
    let Some(session) = execution.into_session() else {
@@ -371,7 +360,7 @@ fn event_stream_response(body: Body, response_headers: &[ProviderResponseHeader]
    response
        .headers_mut()
        .insert(CACHE_CONTROL, HeaderValue::from_static("no-cache"));
-    apply_safe_response_headers(response, response_headers)
+    apply_response_headers(response, response_headers)
 }

 fn internal_gateway_response(message: &'static str) -> Response {
@@ -403,15 +392,10 @@ impl PendingExecution {
    }

    async fn record_response_status(&mut self, response: Response) -> Response {
-        let Some(session) = self.session.as_mut() else {
-            return internal_gateway_response("gateway response session is unavailable");
-        };
-        if session
-            .record_client_status(response.status().as_u16())
-            .await
-            .is_err()
-        {
-            return internal_gateway_response("gateway client status could not be persisted");
+        if let Some(session) = self.session.as_mut() {
+            let _ = session
+                .record_client_status(response.status().as_u16())
+                .await;
        }
        response
    }
@@ -499,10 +483,16 @@ impl ResponsesStreamState {
                    .session
                    .as_ref()
                    .is_some_and(|session| session.is_finalized());
-                self.finish_with_gateway_error(GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response ended without a terminal event",
-                ));
+                if self.execution_terminal {
+                    self.pending
+                        .push_back(Bytes::from_static(DONE_SSE_FRAME.as_bytes()));
+                    self.output_finished = true;
+                } else {
+                    self.finish_with_gateway_error(GatewayError::new(
+                        GatewayErrorKind::Internal,
+                        "gateway response ended without finalizing the execution",
+                    ));
+                }
            }
            Err(error) => {
                self.execution_terminal = self
@@ -521,18 +511,11 @@ impl ResponsesStreamState {
    }

    async fn push_event(&mut self, event: ProviderEvent) {
-        match self.encoder.push_sse(&event) {
-            Ok(frames) => {
-                if self.encoder.is_completed() {
-                    self.finish_completed(frames).await;
-                } else {
-                    self.pending.extend(frames);
-                }
-            }
-            Err(error) => {
-                self.cancel_execution().await;
-                self.finish_with_encode_error(error);
-            }
+        let frames = self.encoder.push_sse(&event);
+        if self.encoder.is_completed() {
+            self.finish_completed(frames).await;
+        } else {
+            self.pending.extend(frames);
        }
    }

@@ -607,20 +590,6 @@ impl ResponsesStreamState {
            .push_back(Bytes::from_static(DONE_SSE_FRAME.as_bytes()));
        self.output_finished = true;
    }
-
-    fn finish_with_encode_error(&mut self, error: ResponseEncodeError) {
-        let protocol = error.protocol_body().error;
-        self.pending
-            .push_back(Bytes::from(response_failed_sse_event_with_id(
-                self.encoder.response_id(),
-                protocol.kind,
-                protocol.code,
-                &protocol.message,
-            )));
-        self.pending
-            .push_back(Bytes::from_static(DONE_SSE_FRAME.as_bytes()));
-        self.output_finished = true;
-    }
 }

 impl Drop for ResponsesStreamState {
@@ -17,13 +17,63 @@ pub use response::OpenAiResponsesEncoder;
 pub(crate) use websocket::responses_websocket;
 pub use websocket::{ResponseCreateFrameError, decode_response_create_with_context};

-pub(super) fn safe_response_header_name(name: &str) -> Option<&'static str> {
-    match name {
-        "x-request-id" => Some("x-request-id"),
-        "openai-model" => Some("openai-model"),
-        "x-models-etag" => Some("x-models-etag"),
-        "x-reasoning-included" => Some("x-reasoning-included"),
-        "openai-processing-ms" => Some("openai-processing-ms"),
-        _ => None,
+use gateway_core::event::ProviderResponseHeader;
+
+pub(super) fn response_connection_options(headers: &[ProviderResponseHeader]) -> Vec<String> {
+    headers
+        .iter()
+        .filter(|header| header.name().trim().eq_ignore_ascii_case("connection"))
+        .filter_map(|header| std::str::from_utf8(header.value()).ok())
+        .flat_map(|value| value.split(','))
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(str::to_ascii_lowercase)
+        .collect()
+}
+
+pub(super) fn response_header_is_forwardable(name: &str, connection_options: &[String]) -> bool {
+    let name = name.trim().to_ascii_lowercase();
+    if connection_options
+        .iter()
+        .any(|option| option.eq_ignore_ascii_case(&name))
+        || name.starts_with("sec-websocket-")
+    {
+        return false;
    }
+
+    !matches!(
+        name.as_str(),
+        "connection"
+            | "keep-alive"
+            | "proxy-connection"
+            | "te"
+            | "trailer"
+            | "transfer-encoding"
+            | "upgrade"
+            | "content-length"
+            | "content-type"
+            | "content-encoding"
+            | "authorization"
+            | "x-api-key"
+            | "www-authenticate"
+            | "authentication-info"
+            | "proxy-authenticate"
+            | "proxy-authorization"
+            | "proxy-authentication-info"
+            | "cookie"
+            | "cookie2"
+            | "set-cookie"
+            | "set-cookie2"
+            | "chatgpt-account-id"
+            | "chatgpt-organization-id"
+            | "chatgpt-org-id"
+            | "chatgpt-project-id"
+            | "openai-organization"
+            | "openai-project"
+            | "x-openai-organization"
+            | "x-openai-project"
+            | "x-codex-installation-id"
+            | "x-codex-turn-state"
+            | "x-codex-turn-metadata"
+    )
 }
@@ -3,6 +3,7 @@
 use std::{fmt, net::IpAddr};

 use axum::http::HeaderMap;
+use base64::{Engine as _, engine::general_purpose::STANDARD};
 use gateway_core::operation::{GenerateRequest, Operation, ProtocolPayload, ProviderSessionState};
 use gateway_protocol::openai::{
    X_OPENAI_INTERNAL_CODEX_RESPONSES_LITE_HEADER, X_OPENAI_MEMGEN_REQUEST_HEADER,
@@ -14,6 +15,7 @@ use super::error::RequestDecodeError;
 const OPENAI_PROTOCOL: &str = "openai";
 const REVIEW_SUBAGENT: &str = "review";
 const OPENAI_SUBAGENT_KEY: &str = "x-openai-subagent";
+const PASSTHROUGH_HEADERS_CONTEXT_KEY: &str = "opaque_request_headers";

 #[derive(Clone, Default)]
 pub struct OpenAiRequestHeaders {
@@ -34,6 +36,7 @@ pub struct OpenAiRequestHeaders {
    responses_lite: Option<String>,
    memgen_request: Option<String>,
    subagent: Option<String>,
+    passthrough_headers: Vec<Value>,
 }

 impl OpenAiRequestHeaders {
@@ -57,12 +60,8 @@ impl OpenAiRequestHeaders {
            turn_id: header_string(headers, "x-codex-turn-id"),
            responses_lite: header_string(headers, X_OPENAI_INTERNAL_CODEX_RESPONSES_LITE_HEADER),
            memgen_request: header_string(headers, X_OPENAI_MEMGEN_REQUEST_HEADER),
-            subagent: header_string(headers, OPENAI_SUBAGENT_KEY).filter(|value| {
-                matches!(
-                    value.as_str(),
-                    "review" | "compact" | "memory_consolidation" | "collab_spawn"
-                )
-            }),
+            subagent: header_string(headers, OPENAI_SUBAGENT_KEY),
+            passthrough_headers: passthrough_headers(headers),
        }
    }

@@ -108,6 +107,12 @@ impl OpenAiRequestHeaders {
        insert_protocol_context(&mut context, "turn_id", self.turn_id.as_ref());
        insert_protocol_context(&mut context, "responses_lite", self.responses_lite.as_ref());
        insert_protocol_context(&mut context, "memgen_request", self.memgen_request.as_ref());
+        if !self.passthrough_headers.is_empty() {
+            context.insert(
+                PASSTHROUGH_HEADERS_CONTEXT_KEY.to_owned(),
+                Value::Array(self.passthrough_headers.clone()),
+            );
+        }
        if let Some(use_websocket) = use_websocket {
            context.insert("use_websocket".to_owned(), Value::Bool(use_websocket));
        }
@@ -322,13 +327,14 @@ pub(super) fn decode_request_object(
    review: bool,
    request_headers: &OpenAiRequestHeaders,
 ) -> Result<DecodedResponsesRequest, RequestDecodeError> {
-    // `use_websocket` 只影响本地 transport。无论值是否可识别，都不得进入上游 body。
-    let use_websocket = object
-        .remove("use_websocket")
-        .and_then(|value| value.as_bool());
+    // 仅消费已识别的本地 transport 开关；未知同名值保留给未来上游协议。
+    let use_websocket = object.get("use_websocket").and_then(Value::as_bool);
+    if use_websocket.is_some() {
+        object.remove("use_websocket");
+    }

-    let model = required_non_empty_string(&object, "model", "model")?.trim();
-    if model.is_empty() {
+    let model = required_non_empty_string(&object, "model", "model")?;
+    if model.trim().is_empty() {
        return Err(RequestDecodeError::EmptyField {
            field: "model".to_owned(),
        });
@@ -345,7 +351,6 @@ pub(super) fn decode_request_object(
    let continuation = object
        .get("previous_response_id")
        .and_then(Value::as_str)
-        .filter(|response_id| !response_id.is_empty())
        .map(|response_id| ContinuationIntent::PreviousResponseId(response_id.to_owned()))
        .unwrap_or(ContinuationIntent::None);

@@ -376,26 +381,107 @@ fn inject_subagent_metadata(body: &mut Map<String, Value>, subagent: &str) {
    let metadata = body
        .entry("client_metadata".to_owned())
        .or_insert_with(|| Value::Object(Map::new()));
-    if !metadata.is_object() {
-        *metadata = Value::Object(Map::new());
-    }
-    if let Some(metadata) = metadata.as_object_mut() {
-        metadata.insert(
-            OPENAI_SUBAGENT_KEY.to_owned(),
-            Value::String(subagent.to_owned()),
-        );
-    }
+    let Some(metadata) = metadata.as_object_mut() else {
+        return;
+    };
+    metadata.insert(
+        OPENAI_SUBAGENT_KEY.to_owned(),
+        Value::String(subagent.to_owned()),
+    );
 }

 fn header_string(headers: &HeaderMap, name: &str) -> Option<String> {
    headers
        .get(name)
        .and_then(|value| value.to_str().ok())
-        .map(str::trim)
-        .filter(|value| !value.is_empty())
        .map(ToOwned::to_owned)
 }

+fn passthrough_headers(headers: &HeaderMap) -> Vec<Value> {
+    let connection_headers = headers
+        .get_all("connection")
+        .iter()
+        .filter_map(|value| value.to_str().ok())
+        .flat_map(|value| value.split(','))
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(str::to_ascii_lowercase)
+        .collect::<Vec<_>>();
+
+    headers
+        .iter()
+        .filter(|(name, _)| passthrough_header_name(name.as_str(), &connection_headers))
+        .map(|(name, value)| {
+            Value::Array(vec![
+                Value::String(name.as_str().to_owned()),
+                Value::String(STANDARD.encode(value.as_bytes())),
+            ])
+        })
+        .collect()
+}
+
+fn passthrough_header_name(name: &str, connection_headers: &[String]) -> bool {
+    if connection_headers
+        .iter()
+        .any(|connection_header| connection_header.eq_ignore_ascii_case(name))
+        || name.starts_with("sec-websocket-")
+        || name.starts_with("x-grok-")
+        || name.starts_with("x-xai-")
+    {
+        return false;
+    }
+
+    !matches!(
+        name,
+        // 逐跳头、上游 authority 和重序列化后的实体长度由 transport 重建。
+        "connection"
+            | "keep-alive"
+            | "proxy-connection"
+            | "proxy-authenticate"
+            | "proxy-authorization"
+            | "te"
+            | "trailer"
+            | "transfer-encoding"
+            | "upgrade"
+            | "host"
+            | "content-length"
+            // 下游连接诊断事实只用于本地观测，不能伪装成 OpenAI 请求事实。
+            | "forwarded"
+            | "x-forwarded-for"
+            | "x-forwarded-host"
+            | "x-forwarded-proto"
+            | "x-forwarded-port"
+            | "x-real-ip"
+            | "true-client-ip"
+            | "cf-connecting-ip"
+            | "x-request-id"
+            // 下游鉴权和账号 cookie 绝不能成为上游账号身份。
+            | "authorization"
+            | "x-api-key"
+            | "cookie"
+            | "cookie2"
+            | "chatgpt-account-id"
+            | "chatgpt-organization-id"
+            | "chatgpt-org-id"
+            | "chatgpt-project-id"
+            | "openai-organization"
+            | "openai-project"
+            | "x-openai-organization"
+            | "x-openai-project"
+            // installation ID 始终由当前 lease 重建。
+            | "x-codex-installation-id"
+            // 上游指纹必须由运行时画像统一生成，客户端 originator/User-Agent
+            // 不能透传覆盖，避免不同下游客户端暴露不一致的设备指纹。
+            | "originator"
+            | "user-agent"
+            // 设备 attestation/integrity 头只能由官方客户端或网关自身生成，
+            // 客户端注入的 x-oai-attestation / X-OAI-IS 不得透传上游。
+            | "x-oai-attestation"
+            | "x-oai-is"
+            | "x-oai-is-update"
+    )
+}
+
 fn required_non_empty_string<'a>(
    object: &'a Map<String, Value>,
    key: &str,
@@ -11,15 +11,14 @@ const OPENAI_PROTOCOL: &str = "openai";

 /// OpenAI Responses wire 的转发器。
 ///
-/// OpenAI Provider 与 xAI adapter 都必须交付 OpenAI wire。这里仅保留同一
-/// 响应的身份和终态校验，不再从 canonical facts 重建客户端 JSON；因此
-/// OpenAI 上游的未知字段、字段顺序和事件语义不会被 API 层二次解释。
+/// OpenAI Provider 与 xAI adapter 都必须交付 OpenAI wire。wire 是客户端交付
+/// 与终态判断的事实来源；canonical facts 只在 wire 暂未携带 ID 时提供旁路观测，
+/// 不得反过来拒绝或改写上游事件。
 #[derive(Debug, Default)]
 pub struct OpenAiResponsesEncoder {
    response_id: Option<String>,
    wire_terminal: Option<Value>,
    wire_failure: bool,
-    canonical_completed: bool,
 }

 impl OpenAiResponsesEncoder {
@@ -30,53 +29,41 @@ impl OpenAiResponsesEncoder {
            response_id: None,
            wire_terminal: None,
            wire_failure: false,
-            canonical_completed: false,
        }
    }

    /// 消费一个 Provider event，并返回 SSE frames。
-    ///
-    /// # Errors
-    ///
-    /// 同一响应身份变化时返回错误。
-    pub fn push_sse(&mut self, event: &ProviderEvent) -> Result<Vec<Bytes>, ResponseEncodeError> {
-        self.observe_identity(event)?;
+    pub fn push_sse(&mut self, event: &ProviderEvent) -> Vec<Bytes> {
+        self.observe_canonical_identity(event);
        let Some(wire) = openai_wire(event) else {
-            return Ok(Vec::new());
+            return Vec::new();
        };
-        self.observe_wire_terminal(wire);
+        self.observe_wire(wire);
        if let Some(raw_sse_frame) = wire.raw_sse_frame() {
-            return Ok(vec![raw_sse_frame.clone()]);
+            return vec![raw_sse_frame.clone()];
        }
-        Ok(vec![Bytes::from(encode_sse_event_with_metadata(
+        vec![Bytes::from(encode_sse_event_with_metadata(
            wire.event_type().unwrap_or_default(),
            &wire.data().to_string(),
            wire.sse_id(),
            wire.sse_retry(),
-        ))])
+        ))]
    }

    /// 消费一个 Provider event，并返回 WebSocket JSON messages。
-    ///
-    /// # Errors
-    ///
-    /// 同一响应身份变化时返回错误。
-    pub fn push_websocket(
-        &mut self,
-        event: &ProviderEvent,
-    ) -> Result<Vec<String>, ResponseEncodeError> {
-        self.observe_identity(event)?;
+    pub fn push_websocket(&mut self, event: &ProviderEvent) -> Vec<String> {
+        self.observe_canonical_identity(event);
        let Some(wire) = openai_wire(event).filter(|wire| wire.has_json_data()) else {
-            return Ok(Vec::new());
+            return Vec::new();
        };
-        self.observe_wire_terminal(wire);
-        Ok(vec![wire.data().to_string()])
+        self.observe_wire(wire);
+        vec![wire.data().to_string()]
    }

-    /// 返回是否已经看到同一响应的 canonical 与 wire 终态。
+    /// 返回是否已经看到客户端可见的 wire 终态。
    #[must_use]
    pub fn is_completed(&self) -> bool {
-        self.wire_terminal.is_some() && self.canonical_completed
+        self.wire_terminal.is_some()
    }

    /// 返回是否已把 Provider 原生失败 event 交付给客户端。
@@ -95,39 +82,31 @@ impl OpenAiResponsesEncoder {
    ///
    /// # Errors
    ///
-    /// 缺少 wire 或 canonical 终态时返回错误。
+    /// 缺少可转换为非流式响应的 wire 终态时返回错误。
    pub fn finish(self) -> Result<Value, ResponseEncodeError> {
-        if self.canonical_completed {
-            self.wire_terminal
-                .ok_or(ResponseEncodeError::MissingWireTerminal)
-        } else {
-            Err(ResponseEncodeError::MissingWireTerminal)
-        }
+        self.wire_terminal
+            .ok_or(ResponseEncodeError::MissingWireTerminal)
    }

-    fn observe_identity(&mut self, event: &ProviderEvent) -> Result<(), ResponseEncodeError> {
+    fn observe_canonical_identity(&mut self, event: &ProviderEvent) {
        for fact in event.canonical_facts() {
            let metadata = match fact {
-                GatewayEvent::Started(metadata) => metadata,
-                GatewayEvent::Completed(metadata) => {
-                    self.canonical_completed = true;
-                    metadata
-                }
+                GatewayEvent::Started(metadata) | GatewayEvent::Completed(metadata) => metadata,
                _ => continue,
            };
-            if self
-                .response_id
-                .as_deref()
-                .is_some_and(|current| current != metadata.response_id())
-            {
-                return Err(ResponseEncodeError::WireIdentityChanged);
-            }
            self.response_id = Some(metadata.response_id().to_owned());
        }
-        Ok(())
    }

-    fn observe_wire_terminal(&mut self, wire: &ProtocolWireEvent) {
+    fn observe_wire(&mut self, wire: &ProtocolWireEvent) {
+        if let Some(response_id) = wire
+            .data()
+            .pointer("/response/id")
+            .or_else(|| wire.data().get("response_id"))
+            .and_then(Value::as_str)
+        {
+            self.response_id = Some(response_id.to_owned());
+        }
        let effective_type = wire
            .event_type()
            .or_else(|| wire.data().get("type").and_then(Value::as_str));
@@ -9,7 +9,7 @@ use axum::{
        connect_info::ConnectInfo,
        ws::{CloseFrame, Message, WebSocket, WebSocketUpgrade, close_code},
    },
-    http::{HeaderMap, StatusCode},
+    http::{HeaderMap, HeaderName, StatusCode},
    response::{IntoResponse, Response},
 };
 use futures::StreamExt;
@@ -27,7 +27,6 @@ use crate::{
    openai::{
        auth::{authenticate_client, authentication_error_response},
        error::{gateway_error_contract, gateway_error_from_engine, runtime_unavailable_response},
-        router::MAX_CLIENT_REQUEST_BODY_BYTES,
        service::OpenAiService,
    },
 };
@@ -102,8 +101,10 @@ impl ResponsesWebSocketAdapter {
            _connection_guard: connection_guard,
        };
        websocket
-            .max_message_size(MAX_CLIENT_REQUEST_BODY_BYTES)
-            .max_frame_size(MAX_CLIENT_REQUEST_BODY_BYTES)
+            // 覆盖 axum/tungstenite 的私有 64 MiB message 与 16 MiB frame 默认值。
+            // Responses JSON 的协议可接受性由上游决定，代理不另设 wire 长度上限。
+            .max_message_size(usize::MAX)
+            .max_frame_size(usize::MAX)
            .on_upgrade(move |socket| async move {
                serve_responses_websocket(socket, session).await;
            })
@@ -303,18 +304,7 @@ async fn forward_execution(
        if let Some(update) = event.take_session_update() {
            provider_state = Some(update);
        }
-        match encoder.push_websocket(event) {
-            Ok(messages) => first_messages.extend(messages),
-            Err(error) => {
-                return send_protocol_error(
-                    socket,
-                    StatusCode::INTERNAL_SERVER_ERROR,
-                    error.protocol_body(),
-                    &request_id,
-                )
-                .await;
-            }
-        }
+        first_messages.extend(encoder.push_websocket(event));
    }
    if first_messages.is_empty() {
        let error = GatewayError::new(
@@ -336,9 +326,7 @@ async fn forward_execution(
        {
            return outcome;
        }
-        if let Err(error) = commit_connection_replay(replay, &encoder, provider_state.take()) {
-            return send_gateway_error(socket, &error, &request_id).await;
-        }
+        commit_connection_replay(replay, &encoder, provider_state.take());
        if !send_text(
            socket,
            response_metadata_event(&request_id, &response_headers),
@@ -378,18 +366,7 @@ async fn forward_execution(
                    if let Some(update) = event.take_session_update() {
                        provider_state = Some(update);
                    }
-                    match encoder.push_websocket(event) {
-                        Ok(encoded) => messages.extend(encoded),
-                        Err(error) => {
-                            return send_protocol_error(
-                                socket,
-                                StatusCode::INTERNAL_SERVER_ERROR,
-                                error.protocol_body(),
-                                &request_id,
-                            )
-                            .await;
-                        }
-                    }
+                    messages.extend(encoder.push_websocket(event));
                }
                if encoder.is_completed() {
                    if let Err(outcome) =
@@ -397,11 +374,7 @@ async fn forward_execution(
                    {
                        return outcome;
                    }
-                    if let Err(error) =
-                        commit_connection_replay(replay, &encoder, provider_state.take())
-                    {
-                        return send_gateway_error(socket, &error, &request_id).await;
-                    }
+                    commit_connection_replay(replay, &encoder, provider_state.take());
                    if !send_messages(socket, messages).await {
                        return ForwardOutcome::Disconnect;
                    }
@@ -413,9 +386,17 @@ async fn forward_execution(
                }
            }
            ActiveInput::Event(Ok(None)) => {
+                if execution
+                    .session_mut()
+                    .is_some_and(|session| session.is_finalized())
+                {
+                    commit_connection_replay(replay, &encoder, provider_state.take());
+                    execution.disarm();
+                    return ForwardOutcome::Continue;
+                }
                let error = GatewayError::new(
                    GatewayErrorKind::Internal,
-                    "gateway response ended without a terminal event",
+                    "gateway response ended without finalizing the execution",
                );
                return send_gateway_error(socket, &error, &request_id).await;
            }
@@ -441,15 +422,10 @@ fn commit_connection_replay(
    replay: &mut ConnectionReplaySnapshot,
    encoder: &OpenAiResponsesEncoder,
    provider_state: Option<ProviderSessionState>,
-) -> Result<(), GatewayError> {
-    let response_id = encoder.response_id().ok_or_else(|| {
-        GatewayError::new(
-            GatewayErrorKind::Internal,
-            "gateway completed a response without an identity",
-        )
-    })?;
-    replay.commit(response_id.to_owned(), provider_state);
-    Ok(())
+) {
+    if let Some(response_id) = encoder.response_id() {
+        replay.commit(response_id.to_owned(), provider_state);
+    }
 }

 async fn confirm_completed_execution(
@@ -595,21 +571,24 @@ fn response_metadata_event(
    request_id: &str,
    response_headers: &[ProviderResponseHeader],
 ) -> String {
-    let mut headers = response_headers
-        .iter()
-        .filter_map(|header| {
-            super::safe_response_header_name(header.name()).map(|name| {
-                (
-                    name.to_owned(),
-                    Value::String(header.value().as_str().to_owned()),
-                )
-            })
-        })
-        .collect::<Map<String, Value>>();
-    headers.insert(
-        "x-request-id".to_owned(),
-        Value::String(request_id.to_owned()),
-    );
+    let connection_options = super::response_connection_options(response_headers);
+    let mut headers = Map::new();
+    for header in response_headers {
+        if !super::response_header_is_forwardable(header.name(), &connection_options) {
+            continue;
+        }
+        let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
+            continue;
+        };
+        let Ok(value) = std::str::from_utf8(header.value()) else {
+            continue;
+        };
+        // 官方 response.metadata 使用 string map，无法表达同名多值；后值保持既有覆盖语义。
+        headers.insert(name.as_str().to_owned(), Value::String(value.to_owned()));
+    }
+    headers
+        .entry("x-request-id".to_owned())
+        .or_insert_with(|| Value::String(request_id.to_owned()));
    json!({
        "type": "response.metadata",
        "headers": headers,
@@ -13,9 +13,6 @@ use super::{

 use crate::ApiState;

-/// OpenAI 请求正文上限。
-pub const MAX_CLIENT_REQUEST_BODY_BYTES: usize = 16 * 1024 * 1024;
-
 /// 构造 OpenAI 客户端协议路由。
 pub(crate) fn router() -> Router<ApiState> {
    Router::new()
@@ -26,5 +23,7 @@ pub(crate) fn router() -> Router<ApiState> {
        .route("/v1/models/{model_id}/info", get(model_info))
        // 官方 OpenAI 模型详情合同使用 path ID；它不属于 Admin API 约束。
        .route("/v1/models/{model_id}", get(model_detail))
-        .layer(DefaultBodyLimit::max(MAX_CLIENT_REQUEST_BODY_BYTES))
+        // Responses 正文属于 OpenAI/Codex 协议；代理不能用私有大小上限提前拒绝
+        // 上游本可接受的未来 payload。
+        .layer(DefaultBodyLimit::disable())
 }
@@ -81,16 +81,10 @@ impl OpenAiService {
                    "requested model was not found",
                )
            })?;
-        if !self.execution.contains_public_model(&client, &public_model) {
-            return Err(GatewayError::new(
-                GatewayErrorKind::ModelNotFound,
-                "requested model was not found",
-            ));
-        }
        let previous_response_id = match metadata.continuation() {
            ContinuationIntent::None => None,
            ContinuationIntent::PreviousResponseId(value) => {
-                PreviousResponseId::new(value.clone()).ok()
+                Some(PreviousResponseId::new(value.clone()))
            }
        };
        self.execution
@@ -0,0 +1,271 @@
+use axum::{
+    Router,
+    body::{Body, to_bytes},
+    http::{Method, Request, StatusCode, header},
+};
+use gateway_api::admin::account_groups;
+use serde_json::{Value, json};
+use tower::ServiceExt as _;
+
+use super::{AdminTestFixture, AdminTestState, PRIMARY_GROUP_ID};
+
+const SESSION_COOKIE: &str = "cpr_admin_session=valid-session";
+
+#[tokio::test]
+async fn list_route_should_keep_camel_case_group_and_page_wire() {
+    let fixture = authenticated_fixture().await;
+    let response = request(
+        router(&fixture),
+        Method::GET,
+        "/api/admin/account-groups?page=1&pageSize=1&search=alpha&enabled=true",
+        None,
+        true,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let value = response_json(response).await;
+    assert_eq!(value["data"]["page"]["page"], 1);
+    assert_eq!(value["data"]["page"]["pageSize"], 1);
+    assert_eq!(value["data"]["page"]["total"], 1);
+    assert_eq!(value["data"]["page"]["totalPages"], 1);
+    assert_eq!(value["data"]["configRevision"], 7);
+    assert_eq!(value["data"]["items"][0]["id"], PRIMARY_GROUP_ID);
+    assert_eq!(value["data"]["items"][0]["memberCount"], 2);
+    assert_eq!(value["data"]["items"][0]["providerCounts"]["openai"], 1);
+    assert_eq!(value["data"]["items"][0]["clientKeyCount"], 2);
+    assert_eq!(value["data"]["items"][0]["accountSummary"]["available"], 1);
+    assert_eq!(value["data"]["items"][0]["accountSummary"]["limited"], 1);
+    assert_eq!(value["data"]["items"][0]["accountSummary"]["total"], 2);
+    assert_eq!(value["data"]["items"][0]["capacity"]["usedSlots"], 0);
+    assert_eq!(value["data"]["items"][0]["capacity"]["totalSlots"], 1);
+    assert_eq!(value["data"]["items"][0]["usage"]["todayUsd"], "1.25");
+    assert_eq!(value["data"]["items"][0]["usage"]["totalUsd"], "5.5");
+    assert!(value["data"]["items"][0].get("member_count").is_none());
+}
+
+#[tokio::test]
+async fn create_route_should_create_an_empty_group() {
+    let fixture = authenticated_fixture().await;
+    let response = request(
+        router(&fixture),
+        Method::POST,
+        "/api/admin/account-groups/create",
+        Some(json!({
+            "name": "Gamma routing",
+            "description": "New traffic pool",
+            "color": "#a855f780"
+        })),
+        true,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::CREATED);
+    let value = response_json(response).await;
+    assert!(
+        value["data"]["id"]
+            .as_str()
+            .is_some_and(|id| id.starts_with("grp_") && id.len() == 36)
+    );
+    assert_eq!(value["data"]["record"]["name"], "Gamma routing");
+    assert_eq!(value["data"]["record"]["memberCount"], 0);
+    assert_eq!(value["data"]["record"]["color"], "#A855F780");
+    assert_eq!(value["data"]["configRevision"], 8);
+}
+
+#[tokio::test]
+async fn update_route_should_replace_group_fields() {
+    let fixture = authenticated_fixture().await;
+    let response = request(
+        router(&fixture),
+        Method::POST,
+        "/api/admin/account-groups/update",
+        Some(json!({
+            "id": PRIMARY_GROUP_ID,
+            "name": "Renamed routing",
+            "description": null,
+            "color": "#F43F5ECC"
+        })),
+        true,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let value = response_json(response).await;
+    assert_eq!(value["data"]["record"]["name"], "Renamed routing");
+    assert!(value["data"]["record"]["description"].is_null());
+    assert_eq!(value["data"]["record"]["color"], "#F43F5ECC");
+}
+
+#[tokio::test]
+async fn enable_and_disable_routes_should_set_explicit_group_state() {
+    let fixture = authenticated_fixture().await;
+    let disabled = request(
+        router(&fixture),
+        Method::POST,
+        "/api/admin/account-groups/disable",
+        Some(json!({ "id": PRIMARY_GROUP_ID })),
+        true,
+    )
+    .await;
+    let enabled = request(
+        router(&fixture),
+        Method::POST,
+        "/api/admin/account-groups/enable",
+        Some(json!({ "id": PRIMARY_GROUP_ID })),
+        true,
+    )
+    .await;
+
+    assert_eq!(disabled.status(), StatusCode::OK);
+    assert!(
+        !response_json(disabled).await["data"]["record"]["enabled"]
+            .as_bool()
+            .expect("disabled flag")
+    );
+    assert_eq!(enabled.status(), StatusCode::OK);
+    assert!(
+        response_json(enabled).await["data"]["record"]["enabled"]
+            .as_bool()
+            .expect("enabled flag")
+    );
+}
+
+#[tokio::test]
+async fn delete_route_should_return_deleted_id_without_a_live_record() {
+    let fixture = authenticated_fixture().await;
+    let response = request(
+        router(&fixture),
+        Method::POST,
+        "/api/admin/account-groups/delete",
+        Some(json!({ "id": PRIMARY_GROUP_ID })),
+        true,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let value = response_json(response).await;
+    assert_eq!(value["data"]["id"], PRIMARY_GROUP_ID);
+    assert!(value["data"]["record"].is_null());
+}
+
+#[tokio::test]
+async fn list_route_should_reject_unknown_and_invalid_pagination_fields() {
+    let fixture = authenticated_fixture().await;
+    for uri in [
+        "/api/admin/account-groups?other=true",
+        "/api/admin/account-groups?page=0",
+        "/api/admin/account-groups?pageSize=0",
+        "/api/admin/account-groups?pageSize=201",
+    ] {
+        let response = request(router(&fixture), Method::GET, uri, None, true).await;
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST, "{uri}");
+    }
+}
+
+#[tokio::test]
+async fn mutation_route_should_reject_unknown_json_fields() {
+    let fixture = authenticated_fixture().await;
+    let response = request(
+        router(&fixture),
+        Method::POST,
+        "/api/admin/account-groups/create",
+        Some(json!({
+            "name": "Unknown field",
+            "description": null,
+            "color": "#2563EBFF",
+            "providerKind": "openai"
+        })),
+        true,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::UNPROCESSABLE_ENTITY);
+}
+
+#[tokio::test]
+async fn create_route_should_reject_six_digit_color_without_alpha() {
+    let fixture = authenticated_fixture().await;
+    let response = request(
+        router(&fixture),
+        Method::POST,
+        "/api/admin/account-groups/create",
+        Some(json!({
+            "name": "Opaque legacy color",
+            "description": null,
+            "color": "#2563EB"
+        })),
+        true,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn account_group_routes_should_require_admin_authentication() {
+    let fixture = AdminTestFixture::new().await;
+    let get_response = request(
+        router(&fixture),
+        Method::GET,
+        "/api/admin/account-groups",
+        None,
+        false,
+    )
+    .await;
+    let post_response = request(
+        router(&fixture),
+        Method::POST,
+        "/api/admin/account-groups/create",
+        Some(json!({ "name": "Unauthorized", "description": null, "color": "#2563EBFF" })),
+        false,
+    )
+    .await;
+
+    assert_eq!(get_response.status(), StatusCode::UNAUTHORIZED);
+    assert_eq!(post_response.status(), StatusCode::UNAUTHORIZED);
+}
+
+async fn authenticated_fixture() -> AdminTestFixture {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    fixture
+}
+
+fn router(fixture: &AdminTestFixture) -> Router {
+    account_groups::router::<AdminTestState>().with_state(fixture.state())
+}
+
+async fn request(
+    router: Router,
+    method: Method,
+    uri: &str,
+    body: Option<Value>,
+    authenticated: bool,
+) -> axum::response::Response {
+    let mut builder = Request::builder()
+        .method(method)
+        .uri(uri)
+        .header("x-request-id", "req_account_groups");
+    if authenticated {
+        builder = builder.header(header::COOKIE, SESSION_COOKIE);
+    }
+    let body = match body {
+        Some(value) => {
+            builder = builder.header(header::CONTENT_TYPE, "application/json");
+            Body::from(serde_json::to_vec(&value).expect("serialize request body"))
+        }
+        None => Body::empty(),
+    };
+    router
+        .oneshot(builder.body(body).expect("account group request"))
+        .await
+        .expect("account group response")
+}
+
+async fn response_json(response: axum::response::Response) -> Value {
+    let body = to_bytes(response.into_body(), 64 * 1024)
+        .await
+        .expect("account group response body");
+    serde_json::from_slice(&body).expect("account group response JSON")
+}
@@ -10,7 +10,7 @@ mod query {
            "pageSize": 20,
            "provider": "xai",
            "search": "  operator  ",
-            "status": "active",
+            "status": "normal",
            "sortBy": "lastUsedAt",
            "sortDirection": "desc"
        }))
@@ -23,7 +23,7 @@ mod query {
            Some(ref provider) if provider.as_str() == "xai"
        ));
        assert_eq!(query.search.as_deref(), Some("operator"));
-        assert_eq!(query.status, Some(AccountStatus::Active));
+        assert_eq!(query.status, Some(AccountStatus::Normal));
        assert_eq!(
            query.sort.expect("sort").field,
            AccountSortField::LastUsedAt
@@ -34,6 +34,19 @@ mod query {
        );
    }

+    #[test]
+    fn account_query_should_parse_rate_limited_status() {
+        let query: ListQuery = serde_json::from_value(json!({
+            "status": "rate_limited"
+        }))
+        .expect("deserialize account query");
+
+        assert_eq!(
+            query.validate().expect("validate account query").status,
+            Some(AccountStatus::RateLimited)
+        );
+    }
+
    #[test]
    fn account_query_should_reject_unbounded_page_size() {
        let query: ListQuery =
@@ -57,8 +70,138 @@ mod query {
    }
 }

+mod batch_update {
+    use gateway_api::admin::accounts::{BatchUpdateAccountsRequest, UpdateAccountRequest};
+    use serde_json::json;
+
+    #[test]
+    fn batch_update_should_accept_complete_atomic_payload() {
+        let request: BatchUpdateAccountsRequest = serde_json::from_value(json!({
+            "accountIds": ["acct_openai", "acct_xai"],
+            "enabled": false,
+            "concurrencyLimit": null,
+            "weight": 1,
+            "groupIds": ["grp_00000000000000000000000000000001"]
+        }))
+        .expect("deserialize batch update");
+
+        request.validate().expect("validate batch update");
+    }
+
+    #[test]
+    fn batch_update_should_reject_duplicate_or_invalid_account_ids() {
+        for account_ids in [
+            json!(["acct_same", "acct_same"]),
+            json!(["not-an-account"]),
+            json!([]),
+        ] {
+            let request: BatchUpdateAccountsRequest = serde_json::from_value(json!({
+                "accountIds": account_ids,
+                "enabled": true,
+                "concurrencyLimit": 8,
+                "weight": 100,
+                "groupIds": []
+            }))
+            .expect("deserialize invalid batch update");
+            assert_eq!(
+                request.validate().expect_err("reject account IDs").field(),
+                "accountIds"
+            );
+        }
+    }
+
+    #[test]
+    fn batch_update_should_require_enabled_and_reject_unknown_fields() {
+        assert!(
+            serde_json::from_value::<BatchUpdateAccountsRequest>(json!({
+            "accountIds": ["acct_test"],
+            "concurrencyLimit": null,
+            "weight": 1,
+            "groupIds": []
+            }))
+            .is_err()
+        );
+        assert!(
+            serde_json::from_value::<BatchUpdateAccountsRequest>(json!({
+                "accountIds": ["acct_test"],
+                "enabled": true,
+                "concurrencyLimit": null,
+                "weight": 1,
+                "groupIds": [],
+                "legacy": true
+            }))
+            .is_err()
+        );
+    }
+
+    #[test]
+    fn batch_update_should_reject_invalid_scheduling_bounds_and_missing_fields() {
+        for (concurrency_limit, weight, field) in [
+            (json!(0), json!(1), "concurrencyLimit"),
+            (json!(4294967296_u64), json!(1), "concurrencyLimit"),
+            (json!(null), json!(0), "weight"),
+            (json!(null), json!(101), "weight"),
+        ] {
+            let request: BatchUpdateAccountsRequest = serde_json::from_value(json!({
+                "accountIds": ["acct_test"],
+                "enabled": true,
+                "concurrencyLimit": concurrency_limit,
+                "weight": weight,
+                "groupIds": []
+            }))
+            .expect("deserialize invalid scheduling");
+            assert_eq!(
+                request.validate().expect_err("reject scheduling").field(),
+                field
+            );
+        }
+        assert!(
+            serde_json::from_value::<BatchUpdateAccountsRequest>(json!({
+                "accountIds": ["acct_test"],
+                "enabled": true,
+                "weight": 1,
+                "groupIds": []
+            }))
+            .is_err()
+        );
+        assert!(
+            serde_json::from_value::<BatchUpdateAccountsRequest>(json!({
+                "accountIds": ["acct_test"],
+                "enabled": true,
+                "concurrencyLimit": null,
+                "groupIds": []
+            }))
+            .is_err()
+        );
+    }
+
+    #[test]
+    fn single_update_should_require_the_same_complete_scheduling_contract() {
+        let request: UpdateAccountRequest = serde_json::from_value(json!({
+            "accountId": "acct_test",
+            "enabled": true,
+            "concurrencyLimit": 4294967295_u64,
+            "weight": 100,
+            "groupIds": []
+        }))
+        .expect("deserialize single update");
+        request.validate().expect("validate single update");
+
+        assert!(
+            serde_json::from_value::<UpdateAccountRequest>(json!({
+                "accountId": "acct_test",
+                "enabled": true,
+                "weight": 1,
+                "groupIds": []
+            }))
+            .is_err()
+        );
+    }
+}
+
 mod response {
    use gateway_api::admin::accounts::AccountUsageView;
+    use gateway_api::admin::presenter::format_decimal_currency;

    #[test]
    fn account_usage_view_should_keep_unobserved_numbers_null() {
@@ -99,12 +242,22 @@ mod response {
        assert!(value["totalTokens"].is_null());
        assert_eq!(value["createdTokensDisplay"], "-");
    }
+
+    #[test]
+    fn account_usage_currency_should_limit_usd_to_four_fraction_digits() {
+        assert_eq!(format_decimal_currency("0.1204956", "USD"), "$0.1205");
+        assert_eq!(format_decimal_currency("0.99996", "USD"), "$1.00");
+        assert_eq!(format_decimal_currency("0.0300", "USD"), "$0.03");
+        assert_eq!(format_decimal_currency("12.3456", "USD"), "$12.35");
+        assert_eq!(format_decimal_currency("0.1204956", "CNY"), "CNY 0.1204956");
+    }
 }

 mod actions {
+    use base64::Engine as _;
    use gateway_admin::model::{
        Revision,
-        accounts::{AccountConnectionTestEvent as DomainConnectionTestEvent, AccountStatus},
+        accounts::AccountConnectionTestEvent as DomainConnectionTestEvent,
        provider_credentials::{
            CredentialDeletionResult, CredentialImportResult, CredentialMutationResult,
        },
@@ -113,7 +266,8 @@ mod actions {
        AccountActionRequest, AccountConnectionTestEvent, AccountDeletionData,
        AccountDeletionRequest, AccountExportData, AccountExportQuery, AccountIdQuery,
        AccountImportData, AccountImportRequest, AccountMutationData, AccountRefreshRequest,
-        AccountTestQuery, RotateAccountRequest, StartAccountAuthorizationRequest,
+        AccountTestQuery, CompleteAccountAuthorizationRequest, RotateAccountRequest,
+        StartAccountAuthorizationRequest,
    };
    use gateway_core::engine::credential::ProviderAccountId;
    use serde_json::json;
@@ -194,7 +348,8 @@ mod actions {
            "provider": "openai",
            "accountId": "acct_1",
            "accessToken": "header.payload.signature",
-            "refreshToken": "refresh-token"
+            "refreshToken": "refresh-token",
+            "idToken": "id-header.id-payload.id-signature"
        }))
        .expect("decode rotation");
        assert!(rotation.validate().is_ok());
@@ -256,6 +411,35 @@ mod actions {
            }))
            .is_err()
        );
+        assert!(
+            serde_json::from_value::<AccountImportRequest>(json!({
+                "provider": "openai",
+                "data": {},
+                "groupIds": []
+            }))
+            .is_err()
+        );
+    }
+
+    #[test]
+    fn oauth_complete_should_not_accept_group_assignment() {
+        let flow_id = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode([7_u8; 32]);
+        let request: CompleteAccountAuthorizationRequest = serde_json::from_value(json!({
+            "provider": "openai",
+            "flowId": flow_id,
+            "callbackUrl": "http://localhost/callback?code=ok"
+        }))
+        .expect("decode OAuth completion");
+        assert!(request.validate().is_ok());
+        assert!(
+            serde_json::from_value::<CompleteAccountAuthorizationRequest>(json!({
+                "provider": "xai",
+                "flowId": "flow_test",
+                "callbackUrl": "http://localhost/callback?code=ok",
+                "groupIds": []
+            }))
+            .is_err()
+        );
    }

    #[test]
@@ -292,7 +476,7 @@ mod actions {

    #[test]
    fn account_import_response_should_emit_account_ids() {
-        let response = AccountImportData::from(CredentialImportResult {
+        let response = AccountImportData::from_result(CredentialImportResult {
            config_revision: Revision::new(8).expect("revision"),
            credential_ids: vec![ProviderAccountId::new("acct_imported").expect("account ID")],
        });
@@ -330,14 +514,14 @@ mod actions {
            DomainConnectionTestEvent::Content {
                text: "OK".to_owned(),
            },
-            DomainConnectionTestEvent::Completed {
-                account_status: AccountStatus::Active,
-            },
+            DomainConnectionTestEvent::Completed {},
            DomainConnectionTestEvent::Failed {
                message: "upstream unavailable".to_owned(),
                provider_error_code: Some("usage_exhausted".to_owned()),
                provider_error_type: Some("invalid_request_error".to_owned()),
-                account_status: AccountStatus::Active,
+                upstream_status: Some(429),
+                upstream_content_type: Some("application/json".to_owned()),
+                upstream_body: Some(r#"{"error":{"type":"usage_limit_reached"}}"#.to_owned()),
            },
        ]
        .map(|event| AccountConnectionTestEvent::from(event).data);
@@ -362,13 +546,15 @@ mod actions {
                    }
                }),
                json!({ "type": "content", "text": "OK" }),
-                json!({ "type": "test_complete", "success": true, "accountStatus": "active" }),
+                json!({ "type": "test_complete", "success": true }),
                json!({
                    "type": "error",
                    "error": "upstream unavailable",
                    "providerErrorCode": "usage_exhausted",
                    "providerErrorType": "invalid_request_error",
-                    "accountStatus": "active"
+                    "upstreamStatus": 429,
+                    "upstreamContentType": "application/json",
+                    "upstreamBody": r#"{"error":{"type":"usage_limit_reached"}}"#
                }),
            ]
        );
@@ -105,7 +105,7 @@ fn client_key_mutations_should_validate_text_limits_and_unknown_fields() {
    let valid = serde_json::from_value::<CreateClientKeyRequest>(json!({
        "name": "terminal key",
        "label": "production",
-        "providerKind": "openai",
+        "groupIds": [],
        "maxConcurrency": 2,
        "requestsPerMinute": 60
    }))
@@ -118,7 +118,7 @@ fn client_key_mutations_should_validate_text_limits_and_unknown_fields() {
        (
            json!({
                "name": " ",
-                "providerKind": "openai",
+                "groupIds": [],
                "maxConcurrency": 0,
                "requestsPerMinute": 0
            }),
@@ -127,7 +127,7 @@ fn client_key_mutations_should_validate_text_limits_and_unknown_fields() {
        (
            json!({
                "name": "key",
-                "providerKind": "openai",
+                "groupIds": [],
                "maxConcurrency": u64::MAX,
                "requestsPerMinute": 0
            }),
@@ -150,7 +150,7 @@ fn client_key_mutations_should_validate_text_limits_and_unknown_fields() {
            "id": "key_1",
            "expectedConfigRevision": 1,
            "name": "key",
-            "providerKind": "openai",
+            "groupIds": [],
            "maxConcurrency": 0,
            "requestsPerMinute": 0,
            "tokensPerMinute": 0
@@ -161,7 +161,7 @@ fn client_key_mutations_should_validate_text_limits_and_unknown_fields() {
        serde_json::from_value::<CreateClientKeyRequest>(json!({
            "expectedConfigRevision": 7,
            "name": "terminal key",
-            "providerKind": "openai",
+            "groupIds": [],
            "maxConcurrency": 2,
            "requestsPerMinute": 60
        }))
@@ -210,7 +210,10 @@ fn client_key_responses_should_keep_shape_and_redact_creation_debug() {
        id: gateway_core::policy::ClientApiKeyId::new("key_visible").expect("Client Key ID"),
        name: "visible".to_owned(),
        label: None,
-        provider_kind: gateway_core::routing::ProviderKind::new("openai").expect("Provider kind"),
+        groups: Vec::new(),
+        provider_kinds: vec![
+            gateway_core::routing::ProviderKind::new("openai").expect("Provider kind"),
+        ],
        prefix: "sk_visible12".to_owned(),
        enabled: true,
        limits: gateway_core::policy::RateLimits {
@@ -226,7 +229,11 @@ fn client_key_responses_should_keep_shape_and_redact_creation_debug() {
    assert!(list.get("configRevision").is_none());
    assert_eq!(list["total"], 1);
    assert_eq!(list["items"][0]["id"], "key_visible");
-    assert_eq!(list["items"][0]["providerKind"], "openai");
+    assert_eq!(
+        list["items"][0]["providerKinds"],
+        serde_json::json!(["openai"])
+    );
+    assert_eq!(list["items"][0]["routingScope"], "all");
    assert_eq!(list["items"][0]["maxConcurrency"], 2);
    assert_eq!(list["items"][0]["requestsPerMinute"], 60);
    assert!(list["items"][0].get("tokensPerMinute").is_none());
@@ -7,15 +7,22 @@ use std::{
 };

 use async_trait::async_trait;
-use chrono::{Duration, Utc};
+use chrono::{DateTime, Duration, Utc};
 use futures::future::BoxFuture;
 use gateway_admin::{
    AdminConfig, AdminServices, InitialAdminPassword,
    model::{
        MutationContext, Revision,
+        account_groups::{
+            AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupColor,
+            AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, AccountGroupRecord,
+            AccountGroupUsage, DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled,
+            UpdateAccountGroup,
+        },
        accounts::{
-            AccountListQuery, AccountPage, AccountRecord, AccountUsage, AccountUsageWindowQuery,
-            AccountUsageWindowResult, DeleteAccounts, SetAccountEnabled,
+            AccountListQuery, AccountPage, AccountPageItem, AccountUpdateResult, AccountUsage,
+            AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
+            BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
        },
        auth::{AdminAuditEvent, AdminSession},
        client_keys::{
@@ -23,9 +30,9 @@ use gateway_admin::{
            NewClientKey, SetClientKeyEnabled, UpdateClientKey,
        },
        observability::{
-            DashboardObservation, DiagnosticDimension, DiagnosticObservation, OpsErrorPage,
-            OpsErrorQuery, RequestMetricPoint, TimeRange, UsageDetail, UsageFilter, UsageOverview,
-            UsagePage, UsageQuery, UsageRecord,
+            DashboardObservation, DecimalAmount, DiagnosticDimension, DiagnosticObservation,
+            OpsError, OpsErrorPage, OpsErrorQuery, RequestMetricPoint, TimeRange, UsageDetail,
+            UsageFilter, UsageOverview, UsagePage, UsageQuery, UsageRecord,
        },
        provider_credentials::{
            AuthorizationCommit, AuthorizationStarted, CompleteAuthorization, CredentialDetails,
@@ -45,8 +52,8 @@ use gateway_admin::{
    ports::{
        provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind},
        store::{
-            AccountStore, AdminStoreError, AdminStoreErrorKind, AdminStorePorts, AdminStoreResult,
-            AuthStore, ClientKeyStore, ObservabilityStore, SettingsStore,
+            AccountGroupStore, AccountStore, AdminStoreError, AdminStoreErrorKind, AdminStorePorts,
+            AdminStoreResult, AuthStore, ClientKeyStore, ObservabilityStore, SettingsStore,
        },
        system::{
            SystemOperationError, SystemOperationErrorKind, SystemOperations,
@@ -58,15 +65,15 @@ use gateway_api::admin::AdminSessionState;
 use gateway_core::{
    engine::{
        credential::ProviderAccountId,
-        probe::{AccountProbe, AccountProbeRequest, AccountProbeResult},
+        probe::{AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult},
    },
-    error::GatewayError,
    policy::{ClientApiKeyId, RateLimits},
    routing::{
        ConfigRevision, ProviderKind, PublicModelId, UpstreamModelId, snapshot::SnapshotControl,
    },
 };

+mod account_groups;
 mod accounts;
 mod auth;
 mod client_keys;
@@ -80,6 +87,11 @@ pub(super) struct AdminTestFixture {
    pub auth: Arc<MemoryAuthStore>,
    pub settings: Arc<MemorySettingsStore>,
    pub usage_records: Arc<Mutex<Vec<UsageRecord>>>,
+    pub usage_detail: Arc<Mutex<Option<UsageDetail>>>,
+    pub diagnostics: Arc<Mutex<Vec<DiagnosticObservation>>>,
+    pub ops_errors: Arc<Mutex<Vec<OpsError>>>,
+    pub dashboard_observation: Arc<Mutex<Option<DashboardObservation>>>,
+    pub dashboard_summary_range: Arc<Mutex<Option<TimeRange>>>,
 }

 impl AdminTestFixture {
@@ -92,16 +104,29 @@ impl AdminTestFixture {
        let auth = Arc::new(MemoryAuthStore::new(api_key.clone()));
        let settings = Arc::new(MemorySettingsStore::new(api_key));
        let client_keys = Arc::new(MemoryClientKeyStore);
+        let account_groups = Arc::new(MemoryAccountGroupStore::new());
        let usage_records = Arc::new(Mutex::new(Vec::new()));
+        let usage_detail = Arc::new(Mutex::new(None));
+        let diagnostics = Arc::new(Mutex::new(Vec::new()));
+        let ops_errors = Arc::new(Mutex::new(Vec::new()));
+        let dashboard_observation = Arc::new(Mutex::new(None));
+        let dashboard_summary_range = Arc::new(Mutex::new(None));
        let unused = Arc::new(UnusedStore {
            usage_records: Arc::clone(&usage_records),
+            usage_detail: Arc::clone(&usage_detail),
+            diagnostics: Arc::clone(&diagnostics),
+            ops_errors: Arc::clone(&ops_errors),
+            dashboard_observation: Arc::clone(&dashboard_observation),
+            dashboard_summary_range: Arc::clone(&dashboard_summary_range),
        });
        let stores = AdminStorePorts::new(
            unused.clone(),
+            account_groups.clone(),
            auth.clone(),
            client_keys.clone(),
            unused,
            settings.clone(),
+            gateway_admin::ports::backup::BackupStorePorts::disabled(),
        );
        let providers: Vec<Arc<dyn ProviderAdmin>> = vec![
            Arc::new(UnusedProvider::new("openai")),
@@ -126,6 +151,11 @@ impl AdminTestFixture {
            auth,
            settings,
            usage_records,
+            usage_detail,
+            diagnostics,
+            ops_errors,
+            dashboard_observation,
+            dashboard_summary_range,
        }
    }

@@ -325,6 +355,204 @@ impl SettingsStore for MemorySettingsStore {

 pub(super) struct MemoryClientKeyStore;

+pub(super) const PRIMARY_GROUP_ID: &str = "grp_11111111111111111111111111111111";
+pub(super) const SECONDARY_GROUP_ID: &str = "grp_22222222222222222222222222222222";
+
+struct MemoryAccountGroupState {
+    revision: Revision,
+    groups: BTreeMap<gateway_core::routing::AccountGroupId, AccountGroupRecord>,
+}
+
+pub(super) struct MemoryAccountGroupStore {
+    state: Mutex<MemoryAccountGroupState>,
+}
+
+impl MemoryAccountGroupStore {
+    fn new() -> Self {
+        let now = Utc::now();
+        let primary_id = group_id(PRIMARY_GROUP_ID);
+        let secondary_id = group_id(SECONDARY_GROUP_ID);
+        let groups = BTreeMap::from([
+            (
+                primary_id.clone(),
+                AccountGroupRecord {
+                    id: primary_id,
+                    name: "Alpha routing".to_owned(),
+                    description: Some("Primary traffic".to_owned()),
+                    color: group_color("#2563ebff"),
+                    enabled: true,
+                    member_count: 2,
+                    provider_counts: BTreeMap::from([
+                        ("openai".to_owned(), 1),
+                        ("xai".to_owned(), 1),
+                    ]),
+                    client_key_count: 2,
+                    account_summary: account_summary(1, 1, 2),
+                    capacity: capacity(Some(0), 1),
+                    usage: usage("1.25", "5.5"),
+                    created_at: now,
+                    updated_at: now,
+                },
+            ),
+            (
+                secondary_id.clone(),
+                AccountGroupRecord {
+                    id: secondary_id,
+                    name: "Beta routing".to_owned(),
+                    description: None,
+                    color: group_color("#64748B80"),
+                    enabled: false,
+                    member_count: 0,
+                    provider_counts: BTreeMap::new(),
+                    client_key_count: 0,
+                    account_summary: account_summary(0, 0, 0),
+                    capacity: capacity(Some(0), 0),
+                    usage: usage("0", "0"),
+                    created_at: now,
+                    updated_at: now,
+                },
+            ),
+        ]);
+        Self {
+            state: Mutex::new(MemoryAccountGroupState {
+                revision: Revision::new(7).expect("revision"),
+                groups,
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl AccountGroupStore for MemoryAccountGroupStore {
+    async fn list_account_groups(
+        &self,
+        query: AccountGroupListQuery,
+    ) -> AdminStoreResult<AccountGroupPage> {
+        let state = self.state.lock().expect("account groups");
+        let search = query.search.as_ref().map(|value| value.to_lowercase());
+        let mut matching = state
+            .groups
+            .values()
+            .filter(|record| {
+                query
+                    .enabled
+                    .is_none_or(|enabled| record.enabled == enabled)
+            })
+            .filter(|record| {
+                search.as_ref().is_none_or(|search| {
+                    record.name.to_lowercase().contains(search)
+                        || record
+                            .description
+                            .as_ref()
+                            .is_some_and(|description| description.to_lowercase().contains(search))
+                })
+            })
+            .cloned()
+            .collect::<Vec<_>>();
+        matching.sort_by(|left, right| left.name.cmp(&right.name));
+        let total = matching.len() as u64;
+        let page_size = usize::from(query.page_size.get());
+        let offset = usize::try_from(query.page.saturating_sub(1))
+            .unwrap_or(usize::MAX)
+            .saturating_mul(page_size);
+        let items = matching.into_iter().skip(offset).take(page_size).collect();
+        Ok(AccountGroupPage {
+            config_revision: state.revision,
+            items,
+            total,
+            page: query.page,
+            page_size: query.page_size.get(),
+        })
+    }
+
+    async fn create_account_group(
+        &self,
+        command: NewAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        let mut state = self.state.lock().expect("account groups");
+        let now = Utc::now();
+        let record = AccountGroupRecord {
+            id: command.id.clone(),
+            name: command.name,
+            description: command.description,
+            color: command.color,
+            enabled: true,
+            member_count: 0,
+            provider_counts: BTreeMap::new(),
+            client_key_count: 0,
+            account_summary: account_summary(0, 0, 0),
+            capacity: capacity(Some(0), 0),
+            usage: usage("0", "0"),
+            created_at: now,
+            updated_at: now,
+        };
+        state.groups.insert(command.id.clone(), record);
+        mutation(&mut state, command.id, true)
+    }
+
+    async fn update_account_group(
+        &self,
+        command: UpdateAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        let mut state = self.state.lock().expect("account groups");
+        let record = state
+            .groups
+            .get_mut(&command.id)
+            .ok_or_else(|| not_found("account group"))?;
+        record.name = command.name;
+        record.description = command.description;
+        record.color = command.color;
+        record.updated_at = Utc::now();
+        mutation(&mut state, command.id, true)
+    }
+
+    async fn set_account_group_enabled(
+        &self,
+        command: SetAccountGroupEnabled,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        let mut state = self.state.lock().expect("account groups");
+        let record = state
+            .groups
+            .get_mut(&command.id)
+            .ok_or_else(|| not_found("account group"))?;
+        record.enabled = command.enabled;
+        record.updated_at = Utc::now();
+        mutation(&mut state, command.id, true)
+    }
+
+    async fn delete_account_group(
+        &self,
+        command: DeleteAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        let mut state = self.state.lock().expect("account groups");
+        if state.groups.remove(&command.id).is_none() {
+            return Err(not_found("account group"));
+        }
+        mutation(&mut state, command.id, false)
+    }
+}
+
+fn group_id(value: &str) -> gateway_core::routing::AccountGroupId {
+    gateway_core::routing::AccountGroupId::new(value).expect("account group ID")
+}
+
+fn mutation(
+    state: &mut MemoryAccountGroupState,
+    id: gateway_core::routing::AccountGroupId,
+    include_record: bool,
+) -> AdminStoreResult<AccountGroupMutation> {
+    state.revision = next_revision(state.revision);
+    Ok(AccountGroupMutation {
+        config_revision: state.revision,
+        record: include_record.then(|| state.groups.get(&id).expect("group record").clone()),
+        id,
+    })
+}
+
 #[async_trait]
 impl ClientKeyStore for MemoryClientKeyStore {
    async fn list_client_keys(&self, _: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage> {
@@ -346,7 +574,8 @@ impl ClientKeyStore for MemoryClientKeyStore {
                id: id.clone(),
                name: "revealed".to_owned(),
                label: None,
-                provider_kind: ProviderKind::new("openai").expect("provider kind"),
+                groups: Vec::new(),
+                provider_kinds: vec![ProviderKind::new("openai").expect("provider kind")],
                prefix: "sk_aaaaaaaaa".to_owned(),
                enabled: true,
                limits: RateLimits::unlimited(),
@@ -393,6 +622,11 @@ impl ClientKeyStore for MemoryClientKeyStore {

 struct UnusedStore {
    usage_records: Arc<Mutex<Vec<UsageRecord>>>,
+    usage_detail: Arc<Mutex<Option<UsageDetail>>>,
+    diagnostics: Arc<Mutex<Vec<DiagnosticObservation>>>,
+    ops_errors: Arc<Mutex<Vec<OpsError>>>,
+    dashboard_observation: Arc<Mutex<Option<DashboardObservation>>>,
+    dashboard_summary_range: Arc<Mutex<Option<TimeRange>>>,
 }

 #[async_trait]
@@ -401,7 +635,7 @@ impl AccountStore for UnusedStore {
        Err(unavailable("account list"))
    }

-    async fn load_account(&self, _: &str) -> AdminStoreResult<Option<AccountRecord>> {
+    async fn load_account(&self, _: &str) -> AdminStoreResult<Option<AccountPageItem>> {
        Err(unavailable("account"))
    }

@@ -476,14 +710,30 @@ impl AccountStore for UnusedStore {
        Err(unavailable("credential refresh"))
    }

-    async fn set_account_enabled(
+    async fn update_account(
        &self,
-        _: SetAccountEnabled,
+        _: UpdateAccount,
        _: &MutationContext,
-    ) -> AdminStoreResult<Revision> {
+    ) -> 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,
@@ -503,8 +753,20 @@ impl AccountStore for UnusedStore {

 #[async_trait]
 impl ObservabilityStore for UnusedStore {
-    async fn dashboard_summary(&self, _: TimeRange) -> AdminStoreResult<DashboardObservation> {
-        Err(unavailable("dashboard"))
+    async fn dashboard_summary(
+        &self,
+        range: TimeRange,
+        _: DateTime<Utc>,
+    ) -> AdminStoreResult<DashboardObservation> {
+        *self
+            .dashboard_summary_range
+            .lock()
+            .expect("dashboard summary range") = Some(range);
+        self.dashboard_observation
+            .lock()
+            .expect("dashboard observation")
+            .clone()
+            .ok_or_else(|| unavailable("dashboard"))
    }

    async fn dashboard_trend(&self, _: TimeRange) -> AdminStoreResult<Vec<RequestMetricPoint>> {
@@ -538,7 +800,11 @@ impl ObservabilityStore for UnusedStore {
    }

    async fn usage_record_detail(&self, _: &str) -> AdminStoreResult<UsageDetail> {
-        Err(unavailable("usage detail"))
+        self.usage_detail
+            .lock()
+            .expect("usage detail")
+            .clone()
+            .ok_or_else(|| unavailable("usage detail"))
    }

    async fn usage_summary(&self, _: TimeRange, _: UsageFilter) -> AdminStoreResult<UsageOverview> {
@@ -551,11 +817,16 @@ impl ObservabilityStore for UnusedStore {
        _: UsageFilter,
        _: DiagnosticDimension,
    ) -> AdminStoreResult<Vec<DiagnosticObservation>> {
-        Err(unavailable("usage diagnostics"))
+        Ok(self.diagnostics.lock().expect("diagnostics").clone())
    }

    async fn list_ops_errors(&self, _: OpsErrorQuery) -> AdminStoreResult<OpsErrorPage> {
-        Err(unavailable("ops errors"))
+        let items = self.ops_errors.lock().expect("ops errors").clone();
+        Ok(OpsErrorPage {
+            total: items.len() as u64,
+            items,
+            next_cursor: None,
+        })
    }
 }

@@ -675,7 +946,7 @@ impl AccountProbe for NoopProbe {
    fn probe(
        &self,
        _: AccountProbeRequest,
-    ) -> BoxFuture<'_, Result<AccountProbeResult, GatewayError>> {
+    ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
        Box::pin(async { panic!("unused account probe") })
    }
 }
@@ -746,6 +1017,32 @@ fn next_revision(revision: Revision) -> Revision {
    Revision::new(revision.get().saturating_add(1)).expect("next revision")
 }

+fn account_summary(available: u64, limited: u64, total: u64) -> AccountGroupAccountSummary {
+    AccountGroupAccountSummary {
+        available,
+        limited,
+        total,
+    }
+}
+
+fn group_color(value: &str) -> AccountGroupColor {
+    AccountGroupColor::parse(value).expect("group color")
+}
+
+fn capacity(used_slots: Option<u64>, total_slots: u64) -> AccountGroupCapacity {
+    AccountGroupCapacity {
+        used_slots,
+        total_slots,
+    }
+}
+
+fn usage(today_usd: &str, total_usd: &str) -> AccountGroupUsage {
+    AccountGroupUsage {
+        today_usd: today_usd.parse::<DecimalAmount>().expect("today cost"),
+        total_usd: total_usd.parse::<DecimalAmount>().expect("total cost"),
+    }
+}
+
 fn unavailable(resource: &'static str) -> AdminStoreError {
    AdminStoreError::new(
        AdminStoreErrorKind::Unavailable,
@@ -754,6 +1051,10 @@ fn unavailable(resource: &'static str) -> AdminStoreError {
    )
 }

+fn not_found(resource: &'static str) -> AdminStoreError {
+    AdminStoreError::new(AdminStoreErrorKind::NotFound, resource, "not found")
+}
+
 fn unsupported_provider() -> ProviderAdminError {
    ProviderAdminError::new(ProviderAdminErrorKind::Unsupported)
 }
@@ -1,456 +0,0 @@
-mod query {
-    use gateway_api::admin::observability::{
-        DashboardQuery, DiagnosticDimension, DiagnosticsQuery, OpsQuery, TrendKind, UsageQuery,
-        parse_attempt_index, parse_datetime, parse_status,
-    };
-    use serde_json::json;
-
-    #[test]
-    fn dashboard_query_should_parse_terminal_trend_kinds() {
-        let query: DashboardQuery = serde_json::from_value(json!({"kind": "errors"})).unwrap();
-        assert_eq!(query.trend_kind().unwrap(), TrendKind::Errors);
-    }
-
-    #[test]
-    fn dashboard_query_should_reject_unknown_trend_kind() {
-        let query: DashboardQuery = serde_json::from_value(json!({"kind": "secret"})).unwrap();
-        assert_eq!(query.trend_kind().unwrap_err().field(), "kind");
-    }
-
-    #[test]
-    fn usage_query_should_bound_page_size_and_cursor() {
-        let query: UsageQuery = serde_json::from_value(json!({
-            "page": 2,
-            "pageSize": 100,
-            "cursor": "opaque"
-        }))
-        .unwrap();
-        assert_eq!(query.validate_page().unwrap(), (2, 100));
-        assert!(query.validate_cursor().is_ok());
-    }
-
-    #[test]
-    fn usage_query_should_reject_zero_page() {
-        let query: UsageQuery = serde_json::from_value(json!({"page": 0})).unwrap();
-        assert_eq!(query.validate_page().unwrap_err().field(), "page");
-    }
-
-    #[test]
-    fn ops_query_should_reject_page_size_above_terminal_limit() {
-        let query: OpsQuery = serde_json::from_value(json!({"pageSize": 101})).unwrap();
-        assert_eq!(query.validate_page().unwrap_err().field(), "pageSize");
-    }
-
-    #[test]
-    fn diagnostics_query_should_keep_wire_dimension_name() {
-        let query: DiagnosticsQuery =
-            serde_json::from_value(json!({"dimension": "failure_class"})).unwrap();
-        assert_eq!(query.dimension().unwrap(), DiagnosticDimension::Failure);
-        assert_eq!(DiagnosticDimension::Failure.display_name(), "failureClass");
-    }
-
-    #[test]
-    fn scalar_query_parsers_should_reject_out_of_range_values_without_echoing_input() {
-        assert_eq!(parse_status(Some(99)).unwrap_err().field(), "statusCode");
-        assert_eq!(
-            parse_attempt_index(Some(0)).unwrap_err().field(),
-            "attemptIndex"
-        );
-        assert_eq!(
-            parse_datetime(Some("not-a-time")).unwrap_err().field(),
-            "timeRange"
-        );
-    }
-}
-
-mod response {
-    use chrono::{TimeZone, Utc};
-    use gateway_admin::model::observability::DesktopReleaseStatus;
-    use gateway_api::admin::observability::{
-        BillingView, CostCoverageView, CursorWire, DashboardAccountRequestBucketView,
-        DashboardAccountUsageView, DashboardDesktopReleaseStatusView, DashboardWireAttributeView,
-        DashboardWireProfileView, DashboardWireTargetView, PageData, PageMeta, TokenDetailsView,
-        TrendData, TrendKind, TrendPointView, TrendSummaryView,
-    };
-    use serde_json::json;
-
-    #[test]
-    fn usage_page_should_keep_terminal_camel_case_shape() {
-        let data = PageData {
-            items: vec![json!({"id": "request_1"})],
-            page: PageMeta::new(1, 50, 1, 1),
-            next_cursor: Some("cursor".to_owned()),
-        };
-        let value = serde_json::to_value(data).unwrap();
-        assert_eq!(value["page"]["pageSize"], 50);
-        assert_eq!(value["nextCursor"], "cursor");
-    }
-
-    #[test]
-    fn dashboard_wire_profiles_should_keep_provider_specific_attributes() {
-        let value = serde_json::to_value(DashboardWireProfileView {
-            provider: "xai".to_owned(),
-            product: "Grok Build".to_owned(),
-            version: "0.2.106".to_owned(),
-            build: None,
-            target: DashboardWireTargetView {
-                os_type: "linux".to_owned(),
-                os_version: "—".to_owned(),
-                arch: "x86_64".to_owned(),
-                terminal: "headless".to_owned(),
-            },
-            user_agent: "grok-shell/0.2.106 (linux; x86_64)".to_owned(),
-            attributes: vec![DashboardWireAttributeView {
-                label: "客户端标识".to_owned(),
-                value: "grok-shell".to_owned(),
-            }],
-            verified_at: None,
-            release: None,
-        })
-        .expect("dashboard profile");
-
-        assert_eq!(value["provider"], "xai");
-        assert_eq!(value["version"], "0.2.106");
-        assert_eq!(value["attributes"][0]["label"], "客户端标识");
-        assert!(value.get("release").is_none());
-        assert!(value.get("verifiedAt").is_none());
-    }
-
-    #[test]
-    fn dashboard_account_usage_should_keep_daily_request_timeline() {
-        let bucket_start = Utc.timestamp_opt(0, 0).single().unwrap();
-        let value = serde_json::to_value(DashboardAccountUsageView {
-            id: "account_1".to_owned(),
-            provider: "xai".to_owned(),
-            authentication_kind: "oauth".to_owned(),
-            email: "account@example.com".to_owned(),
-            plan_type: Some("free".to_owned()),
-            tokens: "—".to_owned(),
-            request_count: 3,
-            request_buckets: vec![DashboardAccountRequestBucketView {
-                bucket_start,
-                request_count: 3,
-            }],
-            quota_used_percent: None,
-            last_used: "刚刚".to_owned(),
-        })
-        .expect("dashboard account usage");
-
-        assert_eq!(value["requestCount"], 3);
-        assert_eq!(
-            value["requestBuckets"][0]["bucketStart"],
-            "1970-01-01T00:00:00Z"
-        );
-        assert_eq!(value["requestBuckets"][0]["requestCount"], 3);
-    }
-
-    #[test]
-    fn trend_wire_should_serialize_kind_and_values_without_store_types() {
-        let now = Utc.timestamp_opt(0, 0).single().unwrap();
-        let data = TrendData {
-            kind: TrendKind::Usage,
-            points: vec![TrendPointView {
-                time: "08:00".to_owned(),
-                bucket: now,
-                label: "01-01 08:00".to_owned(),
-                requests: "1".to_owned(),
-                requests_value: 1,
-                input_tokens: "2".to_owned(),
-                input_tokens_value: 2,
-                output_tokens: "3".to_owned(),
-                output_tokens_value: 3,
-                cached_tokens: "0".to_owned(),
-                cached_tokens_value: 0,
-                cache_hit_rate_value: 0.0,
-                tokens_value: 5,
-                errors: "0".to_owned(),
-                errors_value: 0,
-                latency: "1 ms".to_owned(),
-                latency_value: Some(1),
-                first_token_latency: "1 ms".to_owned(),
-                first_token_latency_value: Some(1),
-                max_latency: "1 ms".to_owned(),
-                max_latency_value: Some(1),
-                min_latency: "1 ms".to_owned(),
-                min_latency_value: Some(1),
-                success_rate: "100.0%".to_owned(),
-                success_rate_value: Some(100.0),
-            }],
-            summary: vec![TrendSummaryView {
-                label: "输入".to_owned(),
-                value: "2".to_owned(),
-                ratio: None,
-            }],
-        };
-        let value = serde_json::to_value(data).unwrap();
-        assert_eq!(value["kind"], "usage");
-        assert_eq!(value["points"][0]["requestsValue"], 1);
-    }
-
-    #[test]
-    fn sensitive_response_views_do_not_require_debug_or_add_secret_fields() {
-        let coverage = CostCoverageView {
-            known: 1,
-            partial: 0,
-            unknown: 0,
-            not_billable: 0,
-        };
-        let token_details = TokenDetailsView {
-            input_tokens: Some(1),
-            output_tokens: Some(2),
-            cached_tokens: None,
-            cache_write_tokens: None,
-            reasoning_tokens: None,
-            image_input_tokens: None,
-            image_output_tokens: None,
-            total_tokens: Some(3),
-            input_tokens_display: "1".to_owned(),
-            output_tokens_display: "2".to_owned(),
-            cached_tokens_display: "-".to_owned(),
-            cache_write_tokens_display: "-".to_owned(),
-            reasoning_tokens_display: "-".to_owned(),
-            image_input_tokens_display: "-".to_owned(),
-            image_output_tokens_display: "-".to_owned(),
-            total_tokens_display: "3".to_owned(),
-        };
-        let cursor = CursorWire {
-            observed_at: Utc.timestamp_opt(0, 0).single().unwrap(),
-            stable_id: "request_1".to_owned(),
-        };
-        let value = serde_json::to_value((&coverage, &token_details, &cursor)).unwrap();
-        assert!(value.to_string().contains("known"));
-        assert!(!value.to_string().contains("secret"));
-    }
-
-    #[test]
-    fn billing_view_should_preserve_the_original_detail_contract() {
-        let value = serde_json::to_value(BillingView {
-            input_amount_display: "$0.03".to_owned(),
-            output_amount_display: "$0.00".to_owned(),
-            cache_read_amount_display: "$0.14".to_owned(),
-            cache_write_amount_display: "$0.00".to_owned(),
-            standard_amount_display: "$0.17".to_owned(),
-            total_amount_display: "$0.17".to_owned(),
-            input_price_display: "$10.0000 / 1M Token".to_owned(),
-            output_price_display: "$60.0000 / 1M Token".to_owned(),
-            cache_read_price_display: "$1.0000 / 1M Token".to_owned(),
-            cache_write_price_display: "$12.5000 / 1M Token".to_owned(),
-            service_tier_display: "Fast".to_owned(),
-            multiplier_display: "1.00x".to_owned(),
-        })
-        .expect("billing view");
-
-        assert_eq!(value["inputAmountDisplay"], "$0.03");
-        assert_eq!(value["cacheReadPriceDisplay"], "$1.0000 / 1M Token");
-        assert_eq!(value["serviceTierDisplay"], "Fast");
-        assert_eq!(value["multiplierDisplay"], "1.00x");
-    }
-
-    #[test]
-    fn desktop_release_status_should_preserve_the_existing_dashboard_wire_values() {
-        for (domain, expected) in [
-            (DesktopReleaseStatus::Unchecked, "unchecked"),
-            (DesktopReleaseStatus::Current, "aligned"),
-            (DesktopReleaseStatus::UpdateAvailable, "review_required"),
-            (DesktopReleaseStatus::Failed, "check_failed"),
-        ] {
-            let status = DashboardDesktopReleaseStatusView::from(domain);
-            assert_eq!(serde_json::to_value(status).unwrap(), expected);
-        }
-    }
-}
-
-#[tokio::test]
-async fn usage_route_should_forward_a_bounded_unknown_outcome_filter() {
-    use axum::{
-        body::Body,
-        http::{Request, StatusCode, header},
-    };
-    use gateway_api::admin::observability;
-    use tower::ServiceExt as _;
-
-    use super::{AdminTestFixture, AdminTestState};
-
-    let fixture = AdminTestFixture::new().await;
-    fixture.auth.insert_session("valid-session");
-    let response = observability::router::<AdminTestState>()
-        .with_state(fixture.state())
-        .oneshot(
-            Request::builder()
-                .uri("/api/admin/usage/records?outcome=provider_future_state")
-                .header(header::COOKIE, "cpr_admin_session=valid-session")
-                .header("x-request-id", "req_usage_other_outcome")
-                .body(Body::empty())
-                .expect("usage request"),
-        )
-        .await
-        .expect("usage response");
-
-    assert_eq!(response.status(), StatusCode::OK);
-}
-
-#[tokio::test]
-async fn usage_route_should_expose_image_and_websocket_facts() {
-    use axum::{
-        body::{Body, to_bytes},
-        http::{Request, StatusCode, header},
-    };
-    use chrono::Utc;
-    use gateway_admin::model::observability::{RequestOutcome, UsageRecord};
-    use gateway_api::admin::observability;
-    use tower::ServiceExt as _;
-
-    use super::{AdminTestFixture, AdminTestState};
-
-    let fixture = AdminTestFixture::new().await;
-    fixture.auth.insert_session("valid-session");
-    fixture
-        .usage_records
-        .lock()
-        .expect("usage records")
-        .push(UsageRecord {
-            id: "request_endpoint".to_owned(),
-            client_api_key_ref: "key_endpoint".to_owned(),
-            config_revision: 1,
-            protocol: "openai".to_owned(),
-            operation: "generate".to_owned(),
-            endpoint: "/v1/responses".to_owned(),
-            client_transport: "http_sse".to_owned(),
-            requested_model_id: "grok-4.5".to_owned(),
-            provider_kind: Some("xai".to_owned()),
-            provider_account_ref: None,
-            provider_account_name: None,
-            provider_account_email: None,
-            provider_account_authentication_kind: Some("oauth".to_owned()),
-            upstream_model_id: Some("grok-4.5".to_owned()),
-            upstream_transport: Some("http_sse".to_owned()),
-            http_version: Some("h2".to_owned()),
-            websocket_pool: Some("reuse".to_owned()),
-            provider_metadata_json: Some(
-                serde_json::json!({
-                    "effectiveModel": "grok-4.5",
-                    "requestSummary": {"inputItemsCount": 2},
-                    "transport": "must-not-overwrite-core",
-                })
-                .to_string(),
-            ),
-            attempt_count: 1,
-            upstream_send_state: "sent".to_owned(),
-            downstream_committed_at: None,
-            outcome: RequestOutcome::Succeeded,
-            client_status_code: Some(200),
-            upstream_status_code: Some(200),
-            client_response_id: Some("resp_usage_metadata".to_owned()),
-            upstream_request_id: Some("upstream_usage_metadata".to_owned()),
-            upstream_response_id: None,
-            error_kind: None,
-            provider_error_code: None,
-            error_message: None,
-            retry_after_ms: None,
-            input_tokens: Some(1),
-            output_tokens: Some(1),
-            cached_tokens: Some(0),
-            cache_write_tokens: Some(0),
-            reasoning_tokens: Some(0),
-            image_input_tokens: Some(31),
-            image_output_tokens: Some(9),
-            total_tokens: Some(2),
-            cost_source: "unavailable".to_owned(),
-            cost_amount: None,
-            cost_currency: None,
-            billing: None,
-            transport_decision_wait_ms: Some(7),
-            connect_ms: Some(11),
-            headers_ms: Some(13),
-            first_event_ms: Some(17),
-            first_reasoning_ms: Some(19),
-            first_text_ms: Some(23),
-            first_token_ms: Some(19),
-            provider_processing_ms: Some(29),
-            latency_ms: Some(31),
-            client_ip: Some("127.0.0.1".to_owned()),
-            user_agent: Some("usage-metadata-test".to_owned()),
-            reasoning_effort: Some("max".to_owned()),
-            reasoning_preset: Some("ultra".to_owned()),
-            request_kind: Some("review".to_owned()),
-            subagent_kind: Some("worker".to_owned()),
-            compact: true,
-            image_generation_requested: true,
-            image_generation_succeeded: Some(true),
-            started_at: Utc::now(),
-            deadline_at: Utc::now(),
-            completed_at: Some(Utc::now()),
-        });
-    let response = observability::router::<AdminTestState>()
-        .with_state(fixture.state())
-        .oneshot(
-            Request::builder()
-                .uri("/api/admin/usage/records")
-                .header(header::COOKIE, "cpr_admin_session=valid-session")
-                .header("x-request-id", "req_usage_endpoint")
-                .body(Body::empty())
-                .expect("usage request"),
-        )
-        .await
-        .expect("usage response");
-    assert_eq!(response.status(), StatusCode::OK);
-    let body = to_bytes(response.into_body(), 1024 * 1024)
-        .await
-        .expect("usage response body");
-    let value: serde_json::Value = serde_json::from_slice(&body).expect("usage response JSON");
-
-    assert_eq!(
-        serde_json::json!({
-            "route": value["data"]["items"][0]["route"],
-            "authenticationKind": value["data"]["items"][0]["authenticationKind"],
-            "imageInputTokens": value["data"]["items"][0]["tokenDetails"]["imageInputTokens"],
-            "imageOutputTokens": value["data"]["items"][0]["tokenDetails"]["imageOutputTokens"],
-            "websocketPool": value["data"]["items"][0]["metadata"]["websocketPool"],
-            "imageGenerationRequested": value["data"]["items"][0]["metadata"]["imageGenerationRequested"],
-            "imageGenerationSucceeded": value["data"]["items"][0]["metadata"]["imageGenerationSucceeded"],
-            "requestedModel": value["data"]["items"][0]["metadata"]["requestedModel"],
-            "upstreamModel": value["data"]["items"][0]["metadata"]["upstreamModel"],
-            "clientIp": value["data"]["items"][0]["metadata"]["clientIp"],
-            "userAgent": value["data"]["items"][0]["metadata"]["userAgent"],
-            "reasoningEffort": value["data"]["items"][0]["metadata"]["reasoningEffort"],
-            "reasoningPreset": value["data"]["items"][0]["metadata"]["reasoningPreset"],
-            "requestKind": value["data"]["items"][0]["metadata"]["requestKind"],
-            "subagentKind": value["data"]["items"][0]["metadata"]["subagentKind"],
-            "compact": value["data"]["items"][0]["metadata"]["compact"],
-            "transport": value["data"]["items"][0]["metadata"]["transport"],
-            "transportDecisionWaitMs": value["data"]["items"][0]["metadata"]["latencyDetails"]["transportDecisionWaitMs"],
-            "wsConnectMs": value["data"]["items"][0]["metadata"]["latencyDetails"]["wsConnectMs"],
-            "firstReasoningMs": value["data"]["items"][0]["metadata"]["latencyDetails"]["firstReasoningMs"],
-            "firstTextMs": value["data"]["items"][0]["metadata"]["latencyDetails"]["firstTextMs"],
-            "firstTokenMs": value["data"]["items"][0]["metadata"]["latencyDetails"]["firstTokenMs"],
-            "effectiveModel": value["data"]["items"][0]["metadata"]["effectiveModel"],
-            "requestSummary": value["data"]["items"][0]["metadata"]["requestSummary"],
-        }),
-        serde_json::json!({
-            "route": "/v1/responses",
-            "authenticationKind": "oauth",
-            "imageInputTokens": 31,
-            "imageOutputTokens": 9,
-            "websocketPool": {"kind": "reuse"},
-            "imageGenerationRequested": true,
-            "imageGenerationSucceeded": true,
-            "requestedModel": "grok-4.5",
-            "upstreamModel": "grok-4.5",
-            "clientIp": "127.0.0.1",
-            "userAgent": "usage-metadata-test",
-            "reasoningEffort": "max",
-            "reasoningPreset": "ultra",
-            "requestKind": "review",
-            "subagentKind": "worker",
-            "compact": true,
-            "transport": "http_sse",
-            "transportDecisionWaitMs": 7,
-            "wsConnectMs": 11,
-            "firstReasoningMs": 19,
-            "firstTextMs": 23,
-            "firstTokenMs": 19,
-            "effectiveModel": "grok-4.5",
-            "requestSummary": {"inputItemsCount": 2},
-        })
-    );
-}
@@ -0,0 +1,4 @@
+//! Admin 观测 wire/路由的固定合同测试。
+
+mod query;
+mod response;
@@ -0,0 +1,64 @@
+//! 查询 wire 校验的固定合同测试。
+
+use gateway_api::admin::observability::{
+    DashboardQuery, DiagnosticDimension, DiagnosticsQuery, OpsQuery, TrendKind, UsageQuery,
+    parse_attempt_index, parse_datetime, parse_status,
+};
+use serde_json::json;
+
+#[test]
+fn dashboard_query_should_parse_terminal_trend_kinds() {
+    let query: DashboardQuery = serde_json::from_value(json!({"kind": "errors"})).unwrap();
+    assert_eq!(query.trend_kind().unwrap(), TrendKind::Errors);
+}
+
+#[test]
+fn dashboard_query_should_reject_unknown_trend_kind() {
+    let query: DashboardQuery = serde_json::from_value(json!({"kind": "secret"})).unwrap();
+    assert_eq!(query.trend_kind().unwrap_err().field(), "kind");
+}
+
+#[test]
+fn usage_query_should_bound_page_size_and_cursor() {
+    let query: UsageQuery = serde_json::from_value(json!({
+        "page": 2,
+        "pageSize": 100,
+        "cursor": "opaque"
+    }))
+    .unwrap();
+    assert_eq!(query.validate_page().unwrap(), (2, 100));
+    assert!(query.validate_cursor().is_ok());
+}
+
+#[test]
+fn usage_query_should_reject_zero_page() {
+    let query: UsageQuery = serde_json::from_value(json!({"page": 0})).unwrap();
+    assert_eq!(query.validate_page().unwrap_err().field(), "page");
+}
+
+#[test]
+fn ops_query_should_reject_page_size_above_terminal_limit() {
+    let query: OpsQuery = serde_json::from_value(json!({"pageSize": 101})).unwrap();
+    assert_eq!(query.validate_page().unwrap_err().field(), "pageSize");
+}
+
+#[test]
+fn diagnostics_query_should_keep_wire_dimension_name() {
+    let query: DiagnosticsQuery =
+        serde_json::from_value(json!({"dimension": "failure_class"})).unwrap();
+    assert_eq!(query.dimension().unwrap(), DiagnosticDimension::Failure);
+    assert_eq!(DiagnosticDimension::Failure.display_name(), "failureClass");
+}
+
+#[test]
+fn scalar_query_parsers_should_reject_out_of_range_values_without_echoing_input() {
+    assert_eq!(parse_status(Some(99)).unwrap_err().field(), "statusCode");
+    assert_eq!(
+        parse_attempt_index(Some(0)).unwrap_err().field(),
+        "attemptIndex"
+    );
+    assert_eq!(
+        parse_datetime(Some("not-a-time")).unwrap_err().field(),
+        "timeRange"
+    );
+}
@@ -0,0 +1,993 @@
+//! 响应 DTO 与固定 wire 形状的合同测试。
+
+use chrono::{TimeZone, Utc};
+use gateway_admin::model::observability::DesktopReleaseStatus;
+use gateway_api::admin::PageMeta;
+use gateway_api::admin::observability::{
+    BillingView, CostCoverageView, CursorWire, DashboardAccountRequestBucketView,
+    DashboardAccountUsageView, DashboardDesktopReleaseStatusView, DashboardWireAttributeView,
+    DashboardWireProfileView, DashboardWireTargetView, PageData, TokenDetailsView, TrendData,
+    TrendKind, TrendPointView, TrendSummaryView,
+};
+use serde_json::json;
+
+#[test]
+fn usage_page_should_keep_terminal_camel_case_shape() {
+    let data = PageData {
+        items: vec![json!({"id": "request_1"})],
+        page: PageMeta::new(1, 50, 1, 1),
+        next_cursor: Some("cursor".to_owned()),
+    };
+    let value = serde_json::to_value(data).unwrap();
+    assert_eq!(value["page"]["pageSize"], 50);
+    assert_eq!(value["nextCursor"], "cursor");
+}
+
+#[test]
+fn dashboard_wire_profiles_should_keep_provider_specific_attributes() {
+    let value = serde_json::to_value(DashboardWireProfileView {
+        provider: "xai".to_owned(),
+        product: "Grok Build".to_owned(),
+        version: "0.2.106".to_owned(),
+        build: None,
+        target: DashboardWireTargetView {
+            os_type: "linux".to_owned(),
+            os_version: "—".to_owned(),
+            arch: "x86_64".to_owned(),
+            terminal: "headless".to_owned(),
+        },
+        user_agent: "grok-shell/0.2.106 (linux; x86_64)".to_owned(),
+        attributes: vec![DashboardWireAttributeView {
+            label: "客户端标识".to_owned(),
+            value: "grok-shell".to_owned(),
+        }],
+        verified_at: None,
+        release: None,
+    })
+    .expect("dashboard profile");
+
+    assert_eq!(value["provider"], "xai");
+    assert_eq!(value["version"], "0.2.106");
+    assert_eq!(value["attributes"][0]["label"], "客户端标识");
+    assert!(value.get("release").is_none());
+    assert!(value.get("verifiedAt").is_none());
+}
+
+#[test]
+fn dashboard_account_usage_should_keep_daily_request_timeline() {
+    let bucket_start = Utc.timestamp_opt(0, 0).single().unwrap();
+    let value = serde_json::to_value(DashboardAccountUsageView {
+        id: "account_1".to_owned(),
+        provider: "xai".to_owned(),
+        authentication_kind: "oauth".to_owned(),
+        email: "account@example.com".to_owned(),
+        plan_type: Some("free".to_owned()),
+        tokens: "—".to_owned(),
+        request_count: 3,
+        request_buckets: vec![DashboardAccountRequestBucketView {
+            bucket_start,
+            request_count: 3,
+        }],
+        quota_used_percent: None,
+        last_used: "刚刚".to_owned(),
+    })
+    .expect("dashboard account usage");
+
+    assert_eq!(value["requestCount"], 3);
+    assert_eq!(
+        value["requestBuckets"][0]["bucketStart"],
+        "1970-01-01T00:00:00Z"
+    );
+    assert_eq!(value["requestBuckets"][0]["requestCount"], 3);
+}
+
+#[test]
+fn trend_wire_should_serialize_kind_and_values_without_store_types() {
+    let now = Utc.timestamp_opt(0, 0).single().unwrap();
+    let data = TrendData {
+        kind: TrendKind::Usage,
+        points: vec![TrendPointView {
+            time: "08:00".to_owned(),
+            bucket: now,
+            label: "01-01 08:00".to_owned(),
+            requests: "1".to_owned(),
+            requests_value: 1,
+            input_tokens: "2".to_owned(),
+            input_tokens_value: 2,
+            output_tokens: "3".to_owned(),
+            output_tokens_value: 3,
+            cached_tokens: "0".to_owned(),
+            cached_tokens_value: 0,
+            cache_hit_rate_value: 0.0,
+            tokens_value: 5,
+            errors: "0".to_owned(),
+            errors_value: 0,
+            latency: "1 ms".to_owned(),
+            latency_value: Some(1),
+            max_latency: "1 ms".to_owned(),
+            max_latency_value: Some(1),
+            min_latency: "1 ms".to_owned(),
+            min_latency_value: Some(1),
+            success_rate: "100.0%".to_owned(),
+            success_rate_value: Some(100.0),
+        }],
+        summary: vec![TrendSummaryView {
+            label: "输入".to_owned(),
+            value: "2".to_owned(),
+            ratio: None,
+        }],
+    };
+    let value = serde_json::to_value(data).unwrap();
+    assert_eq!(value["kind"], "usage");
+    assert_eq!(value["points"][0]["requestsValue"], 1);
+}
+
+#[test]
+fn sensitive_response_views_do_not_require_debug_or_add_secret_fields() {
+    let coverage = CostCoverageView {
+        known: 1,
+        partial: 0,
+        unknown: 0,
+        not_billable: 0,
+    };
+    let token_details = TokenDetailsView {
+        input_tokens: Some(1),
+        output_tokens: Some(2),
+        cached_tokens: None,
+        cache_write_tokens: None,
+        reasoning_tokens: None,
+        image_input_tokens: None,
+        image_output_tokens: None,
+        total_tokens: Some(3),
+        input_tokens_display: "1".to_owned(),
+        output_tokens_display: "2".to_owned(),
+        cached_tokens_display: "-".to_owned(),
+        cache_write_tokens_display: "-".to_owned(),
+        reasoning_tokens_display: "-".to_owned(),
+        image_input_tokens_display: "-".to_owned(),
+        image_output_tokens_display: "-".to_owned(),
+        total_tokens_display: "3".to_owned(),
+    };
+    let cursor = CursorWire {
+        observed_at: Utc.timestamp_opt(0, 0).single().unwrap(),
+        stable_id: "request_1".to_owned(),
+    };
+    let value = serde_json::to_value((&coverage, &token_details, &cursor)).unwrap();
+    assert!(value.to_string().contains("known"));
+    assert!(!value.to_string().contains("secret"));
+}
+
+#[test]
+fn billing_view_should_preserve_the_original_detail_contract() {
+    let value = serde_json::to_value(BillingView {
+        input_amount_display: "$0.03".to_owned(),
+        output_amount_display: "$0.00".to_owned(),
+        cache_read_amount_display: "$0.14".to_owned(),
+        cache_write_amount_display: "$0.00".to_owned(),
+        standard_amount_display: "$0.17".to_owned(),
+        total_amount_display: "$0.17".to_owned(),
+        input_price_display: "$10.0000 / 1M Token".to_owned(),
+        output_price_display: "$60.0000 / 1M Token".to_owned(),
+        cache_read_price_display: "$1.0000 / 1M Token".to_owned(),
+        cache_write_price_display: "$12.5000 / 1M Token".to_owned(),
+        service_tier_display: "Fast".to_owned(),
+        multiplier_display: "1.00x".to_owned(),
+    })
+    .expect("billing view");
+
+    assert_eq!(value["inputAmountDisplay"], "$0.03");
+    assert_eq!(value["cacheReadPriceDisplay"], "$1.0000 / 1M Token");
+    assert_eq!(value["serviceTierDisplay"], "Fast");
+    assert_eq!(value["multiplierDisplay"], "1.00x");
+}
+
+#[test]
+fn desktop_release_status_should_preserve_the_existing_dashboard_wire_values() {
+    for (domain, expected) in [
+        (DesktopReleaseStatus::Unchecked, "unchecked"),
+        (DesktopReleaseStatus::Current, "aligned"),
+        (DesktopReleaseStatus::UpdateAvailable, "review_required"),
+        (DesktopReleaseStatus::Failed, "check_failed"),
+    ] {
+        let status = DashboardDesktopReleaseStatusView::from(domain);
+        assert_eq!(serde_json::to_value(status).unwrap(), expected);
+    }
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_include_quota_exhaustion_in_unavailable_headline_count() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode, header},
+    };
+    use chrono::{Duration, Utc};
+    use gateway_admin::model::observability::{
+        AccountPoolMetrics, AttemptMetrics, DashboardObservation, RequestMetrics, TimeRange,
+    };
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let now = Utc::now();
+    *fixture
+        .dashboard_observation
+        .lock()
+        .expect("dashboard observation") = Some(DashboardObservation {
+        range: TimeRange::new(now - Duration::hours(1), now).expect("dashboard range"),
+        requests: RequestMetrics::default(),
+        attempts: AttemptMetrics::default(),
+        totals: Default::default(),
+        provider_accounts: AccountPoolMetrics {
+            total: 807,
+            normal: 15,
+            quota_exhausted: 785,
+            rate_limited: 0,
+            disabled: 3,
+            error: 4,
+        },
+        trend: Vec::new(),
+        account_usage: Vec::new(),
+        recent_requests: Vec::new(),
+    });
+
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/dashboard/summary")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_dashboard_account_summary")
+                .body(Body::empty())
+                .expect("dashboard request"),
+        )
+        .await
+        .expect("dashboard response");
+    let status = response.status();
+    let body = to_bytes(response.into_body(), 1024 * 1024)
+        .await
+        .expect("dashboard response body");
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("dashboard response JSON");
+    assert_eq!(status, StatusCode::OK, "{value}");
+
+    assert_eq!(
+        (
+            &value["data"]["cards"]["credentials"]["totalValue"],
+            &value["data"]["cards"]["credentials"]["availableValue"],
+            &value["data"]["cards"]["credentials"]["unavailableValue"],
+        ),
+        (
+            &serde_json::json!(807),
+            &serde_json::json!(15),
+            &serde_json::json!(792)
+        ),
+    );
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_use_lifetime_totals_for_card_footers() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode, header},
+    };
+    use chrono::{Duration, Utc};
+    use gateway_admin::model::observability::{
+        AccountPoolMetrics, AttemptMetrics, DashboardObservation, DashboardTotals, RequestMetrics,
+        TimeRange,
+    };
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let now = Utc::now();
+    let range_requests = RequestMetrics {
+        request_count: 2,
+        input_tokens: 8,
+        cached_tokens: 2,
+        total_tokens: 12,
+        ..RequestMetrics::default()
+    };
+    *fixture
+        .dashboard_observation
+        .lock()
+        .expect("dashboard observation") = Some(DashboardObservation {
+        range: TimeRange::new(now - Duration::hours(1), now).expect("dashboard range"),
+        requests: range_requests,
+        attempts: AttemptMetrics::default(),
+        totals: DashboardTotals {
+            request_count: 42,
+            input_tokens: 800,
+            cached_tokens: 200,
+            total_tokens: 840,
+            billing_usd: None,
+        },
+        provider_accounts: AccountPoolMetrics::default(),
+        trend: Vec::new(),
+        account_usage: Vec::new(),
+        recent_requests: Vec::new(),
+    });
+
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/dashboard/summary")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_dashboard_lifetime_totals")
+                .body(Body::empty())
+                .expect("dashboard request"),
+        )
+        .await
+        .expect("dashboard response");
+    let status = response.status();
+    let body = to_bytes(response.into_body(), 1024 * 1024)
+        .await
+        .expect("dashboard response body");
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("dashboard response JSON");
+    assert_eq!(status, StatusCode::OK, "{value}");
+
+    assert_eq!(
+        (
+            &value["data"]["cards"]["traffic"]["totalRequests"],
+            &value["data"]["cards"]["tokens"]["totalTokens"],
+            &value["data"]["cards"]["cache"]["totalHitRate"],
+            &value["data"]["cards"]["cache"]["totalCachedTokens"],
+        ),
+        (
+            &serde_json::json!("42"),
+            &serde_json::json!("840"),
+            &serde_json::json!("25.0%"),
+            &serde_json::json!("200"),
+        ),
+    );
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_default_to_current_china_day() {
+    use axum::{
+        body::Body,
+        http::{Request, StatusCode, header},
+    };
+    use chrono::{Duration, Utc};
+    use gateway_admin::model::observability::{
+        AccountPoolMetrics, AttemptMetrics, DashboardObservation, RequestMetrics, TimeRange,
+        china_day_start,
+    };
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let now = Utc::now();
+    *fixture
+        .dashboard_observation
+        .lock()
+        .expect("dashboard observation") = Some(DashboardObservation {
+        range: TimeRange::new(now - Duration::hours(1), now).expect("dashboard range"),
+        requests: RequestMetrics::default(),
+        attempts: AttemptMetrics::default(),
+        totals: Default::default(),
+        provider_accounts: AccountPoolMetrics::default(),
+        trend: Vec::new(),
+        account_usage: Vec::new(),
+        recent_requests: Vec::new(),
+    });
+
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/dashboard/summary")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_dashboard_today_range")
+                .body(Body::empty())
+                .expect("dashboard request"),
+        )
+        .await
+        .expect("dashboard response");
+    let range = fixture
+        .dashboard_summary_range
+        .lock()
+        .expect("dashboard summary range")
+        .take()
+        .expect("recorded dashboard summary range");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(range.start, china_day_start(range.end));
+}
+
+#[tokio::test]
+async fn usage_detail_should_keep_attempt_snapshot_contract() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode, header},
+    };
+    use chrono::Utc;
+    use gateway_admin::model::observability::{UsageAttempt, UsageDetail};
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let now = Utc::now();
+    fixture
+        .usage_detail
+        .lock()
+        .expect("usage detail")
+        .replace(UsageDetail {
+            request: usage_record_with_account(
+                "req_detail",
+                "acct_snap_a",
+                "Snapshot Alpha",
+                "alpha@example.invalid",
+                "oauth",
+                now,
+            ),
+            attempts: vec![UsageAttempt {
+                source: "ops_event".to_owned(),
+                id: "ops_detail".to_owned(),
+                attempt_index: 1,
+                component: "routing".to_owned(),
+                operation: "fallback".to_owned(),
+                provider_kind: Some("openai".to_owned()),
+                provider_account_ref: Some("acct_snap_b".to_owned()),
+                provider_account_name: Some("Snapshot Beta".to_owned()),
+                provider_account_email: Some("beta@example.invalid".to_owned()),
+                provider_account_authentication_kind: Some("api_key".to_owned()),
+                upstream_model_id: Some("upstream-b".to_owned()),
+                upstream_transport: Some("http_sse".to_owned()),
+                upstream_send_state: Some("sent".to_owned()),
+                outcome: gateway_admin::model::observability::RequestOutcome::Failed,
+                downstream_committed: false,
+                status_code: Some(429),
+                provider_error_code: Some("rate_limit".to_owned()),
+                failure_kind: Some("rate_limited".to_owned()),
+                retry_after_ms: Some(1_000),
+                upstream_request_id: None,
+                latency_ms: Some(120),
+                message: Some("limited".to_owned()),
+                input_tokens: None,
+                output_tokens: None,
+                cached_tokens: None,
+                cache_write_tokens: None,
+                reasoning_tokens: None,
+                total_tokens: None,
+                cost_source: Some("unavailable".to_owned()),
+                cost_amount: None,
+                cost_currency: None,
+                occurred_at: now,
+            }],
+        });
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/usage/records/detail?id=req_detail")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_usage_detail_snapshot")
+                .body(Body::empty())
+                .expect("usage detail request"),
+        )
+        .await
+        .expect("usage detail response");
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = to_bytes(response.into_body(), 1024 * 1024)
+        .await
+        .expect("usage detail body");
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("usage detail JSON");
+    assert_eq!(
+        serde_json::json!({
+            "accountId": value["data"]["accountId"],
+            "accountName": value["data"]["accountName"],
+            "accountEmail": value["data"]["accountEmail"],
+            "authenticationKind": value["data"]["authenticationKind"],
+            "attemptCredentialName": value["data"]["attempts"][0]["credentialName"],
+            "attemptAccountId": value["data"]["attempts"][0]["accountId"],
+            "attemptAccountName": value["data"]["attempts"][0]["accountName"],
+            "attemptAccountEmail": value["data"]["attempts"][0]["accountEmail"],
+            "attemptAuthenticationKind": value["data"]["attempts"][0]["authenticationKind"],
+        }),
+        serde_json::json!({
+            "accountId": "acct_snap_a",
+            "accountName": "Snapshot Alpha",
+            "accountEmail": "alpha@example.invalid",
+            "authenticationKind": "oauth",
+            "attemptCredentialName": "Snapshot Beta",
+            "attemptAccountId": "acct_snap_b",
+            "attemptAccountName": "Snapshot Beta",
+            "attemptAccountEmail": "beta@example.invalid",
+            "attemptAuthenticationKind": "api_key",
+        })
+    );
+}
+
+#[tokio::test]
+async fn ops_errors_should_keep_account_label_and_authentication_contract() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode, header},
+    };
+    use chrono::Utc;
+    use gateway_admin::model::observability::OpsError;
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    fixture
+        .ops_errors
+        .lock()
+        .expect("ops errors")
+        .push(OpsError {
+            source: "model_request".to_owned(),
+            event_id: "err_snapshot".to_owned(),
+            request_id: Some("req_err".to_owned()),
+            attempt_index: Some(1),
+            client_api_key_ref: Some("key_err".to_owned()),
+            component: "model_request".to_owned(),
+            operation: "responses".to_owned(),
+            endpoint: Some("/v1/responses".to_owned()),
+            provider_kind: Some("openai".to_owned()),
+            provider_account_ref: Some("acct_err".to_owned()),
+            provider_account_name: None,
+            provider_account_email: Some("err@example.invalid".to_owned()),
+            provider_account_authentication_kind: Some("api_key".to_owned()),
+            upstream_model_id: Some("upstream-err".to_owned()),
+            upstream_transport: Some("http_sse".to_owned()),
+            failure_kind: "upstream_error".to_owned(),
+            client_status_code: Some(502),
+            upstream_status_code: Some(502),
+            provider_error_code: Some("upstream".to_owned()),
+            client_response_id: None,
+            upstream_request_id: None,
+            latency_ms: Some(90),
+            message: "snapshot error".to_owned(),
+            occurrence_count: 1,
+            occurred_at: Utc::now(),
+            stable_sort_id: "model_request:req_err".to_owned(),
+        });
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/operations/errors")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_ops_errors_snapshot")
+                .body(Body::empty())
+                .expect("ops errors request"),
+        )
+        .await
+        .expect("ops errors response");
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = to_bytes(response.into_body(), 1024 * 1024)
+        .await
+        .expect("ops errors body");
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("ops errors JSON");
+    assert_eq!(
+        serde_json::json!({
+            "provider": value["data"]["items"][0]["provider"],
+            "authenticationKind": value["data"]["items"][0]["authenticationKind"],
+            "kind": value["data"]["items"][0]["kind"],
+            "accountId": value["data"]["items"][0]["accountId"],
+            "accountLabel": value["data"]["items"][0]["metadata"]["accountLabel"],
+            "clientStatusCode": value["data"]["items"][0]["clientStatusCode"],
+            "route": value["data"]["items"][0]["route"],
+        }),
+        serde_json::json!({
+            "provider": "openai",
+            "authenticationKind": "api_key",
+            "kind": "model_request",
+            "accountId": "acct_err",
+            "accountLabel": "err@example.invalid",
+            "clientStatusCode": 502,
+            "route": "/v1/responses",
+        })
+    );
+}
+
+#[tokio::test]
+async fn diagnostics_should_keep_stable_key_and_display_name_contract() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode, header},
+    };
+    use gateway_admin::model::observability::{CostCoverage, DiagnosticObservation};
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    fixture
+        .diagnostics
+        .lock()
+        .expect("diagnostics")
+        .push(DiagnosticObservation {
+            key: "acct_diag".to_owned(),
+            name: "diag@example.invalid".to_owned(),
+            request_count: 2,
+            success_count: 2,
+            failure_count: 0,
+            attempt_count: 2,
+            total_tokens: 200,
+            average_latency_ms: Some(100),
+            latency_p95_ms: Some(3800),
+            cost_coverage: CostCoverage::default(),
+            costs: Vec::new(),
+        });
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/usage/insights/diagnostics?dimension=account")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_diagnostics_snapshot")
+                .body(Body::empty())
+                .expect("diagnostics request"),
+        )
+        .await
+        .expect("diagnostics response");
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = to_bytes(response.into_body(), 1024 * 1024)
+        .await
+        .expect("diagnostics body");
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("diagnostics JSON");
+    assert_eq!(
+        (
+            &value["data"]["items"][0]["key"],
+            &value["data"]["items"][0]["name"],
+            &value["data"]["items"][0]["latencyP95Ms"],
+            &value["data"]["dimension"],
+        ),
+        (
+            &serde_json::json!("acct_diag"),
+            &serde_json::json!("diag@example.invalid"),
+            &serde_json::json!(3800),
+            &serde_json::json!("account"),
+        )
+    );
+}
+
+fn usage_record_with_account(
+    id: &str,
+    account_id: &str,
+    name: &str,
+    email: &str,
+    authentication_kind: &str,
+    started_at: chrono::DateTime<chrono::Utc>,
+) -> gateway_admin::model::observability::UsageRecord {
+    use gateway_admin::model::observability::{RequestOutcome, UsageRecord};
+
+    UsageRecord {
+        id: id.to_owned(),
+        client_api_key_ref: "key_detail".to_owned(),
+        config_revision: 1,
+        routing_scope: "all".to_owned(),
+        routing_group_refs: Vec::new(),
+        routing_group_names_snapshot: Vec::new(),
+        protocol: "openai".to_owned(),
+        operation: "responses".to_owned(),
+        endpoint: "/v1/responses".to_owned(),
+        client_transport: "http_sse".to_owned(),
+        requested_model_id: "coding".to_owned(),
+        provider_kind: Some("openai".to_owned()),
+        provider_account_ref: Some(account_id.to_owned()),
+        provider_account_name: Some(name.to_owned()),
+        provider_account_email: Some(email.to_owned()),
+        provider_account_authentication_kind: Some(authentication_kind.to_owned()),
+        upstream_model_id: Some("upstream-model".to_owned()),
+        upstream_transport: Some("http_sse".to_owned()),
+        http_version: Some("h2".to_owned()),
+        websocket_pool: None,
+        service_tier: None,
+        provider_metadata_json: None,
+        attempt_count: 1,
+        upstream_send_state: "sent".to_owned(),
+        downstream_committed_at: Some(started_at),
+        outcome: RequestOutcome::Succeeded,
+        client_status_code: Some(200),
+        upstream_status_code: Some(200),
+        client_response_id: None,
+        upstream_request_id: None,
+        upstream_response_id: None,
+        error_kind: None,
+        provider_error_code: None,
+        error_message: None,
+        retry_after_ms: None,
+        input_tokens: Some(1),
+        output_tokens: Some(1),
+        cached_tokens: Some(0),
+        cache_write_tokens: Some(0),
+        reasoning_tokens: Some(0),
+        image_input_tokens: Some(0),
+        image_output_tokens: Some(0),
+        total_tokens: Some(2),
+        cost_source: "unavailable".to_owned(),
+        cost_amount: None,
+        cost_currency: None,
+        billing: None,
+        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: None,
+        client_ip: None,
+        user_agent: None,
+        reasoning_effort: None,
+        reasoning_preset: None,
+        request_kind: None,
+        subagent_kind: None,
+        compact: false,
+        image_generation_requested: false,
+        image_generation_succeeded: None,
+        started_at,
+        deadline_at: started_at + chrono::Duration::seconds(30),
+        completed_at: Some(started_at),
+    }
+}
+
+#[tokio::test]
+async fn usage_route_should_forward_a_bounded_unknown_outcome_filter() {
+    use axum::{
+        body::Body,
+        http::{Request, StatusCode, header},
+    };
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/usage/records?outcome=provider_future_state")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_usage_other_outcome")
+                .body(Body::empty())
+                .expect("usage request"),
+        )
+        .await
+        .expect("usage response");
+
+    assert_eq!(response.status(), StatusCode::OK);
+}
+
+#[tokio::test]
+async fn usage_route_should_expose_image_and_websocket_facts() {
+    use std::str::FromStr as _;
+
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode, header},
+    };
+    use chrono::Utc;
+    use gateway_admin::model::observability::{
+        CalculatedBillingBreakdown, CurrencyCost, DecimalAmount, RequestOutcome, UsageBilling,
+        UsageRecord,
+    };
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let usd = |amount: &str| CurrencyCost {
+        currency: "USD".to_owned(),
+        amount: DecimalAmount::from_str(amount).expect("USD amount"),
+    };
+    fixture
+        .usage_records
+        .lock()
+        .expect("usage records")
+        .push(UsageRecord {
+            id: "request_endpoint".to_owned(),
+            client_api_key_ref: "key_endpoint".to_owned(),
+            config_revision: 1,
+            routing_scope: "groups".to_owned(),
+            routing_group_refs: vec!["grp_usage".to_owned()],
+            routing_group_names_snapshot: vec!["Usage group".to_owned()],
+            protocol: "openai".to_owned(),
+            operation: "generate".to_owned(),
+            endpoint: "/v1/responses".to_owned(),
+            client_transport: "http_sse".to_owned(),
+            requested_model_id: "grok-4.5".to_owned(),
+            provider_kind: Some("xai".to_owned()),
+            provider_account_ref: Some("acct_snapshot".to_owned()),
+            provider_account_name: Some("Snapshot Alpha".to_owned()),
+            provider_account_email: Some("alpha@example.invalid".to_owned()),
+            provider_account_authentication_kind: Some("oauth".to_owned()),
+            upstream_model_id: Some("grok-4.5".to_owned()),
+            upstream_transport: Some("http_sse".to_owned()),
+            http_version: Some("h2".to_owned()),
+            websocket_pool: Some("reuse".to_owned()),
+            service_tier: Some("priority".to_owned()),
+            provider_metadata_json: Some(
+                serde_json::json!({
+                    "effectiveModel": "grok-4.5",
+                    "requestSummary": {"inputItemsCount": 2},
+                    "transport": "must-not-overwrite-core",
+                })
+                .to_string(),
+            ),
+            attempt_count: 1,
+            upstream_send_state: "sent".to_owned(),
+            downstream_committed_at: None,
+            outcome: RequestOutcome::Succeeded,
+            client_status_code: Some(200),
+            upstream_status_code: Some(200),
+            client_response_id: Some("resp_usage_metadata".to_owned()),
+            upstream_request_id: Some("upstream_usage_metadata".to_owned()),
+            upstream_response_id: None,
+            error_kind: None,
+            provider_error_code: None,
+            error_message: None,
+            retry_after_ms: None,
+            input_tokens: Some(1),
+            output_tokens: Some(1),
+            cached_tokens: Some(0),
+            cache_write_tokens: Some(0),
+            reasoning_tokens: Some(0),
+            image_input_tokens: Some(31),
+            image_output_tokens: Some(9),
+            total_tokens: Some(2),
+            cost_source: "unavailable".to_owned(),
+            cost_amount: None,
+            cost_currency: None,
+            billing: Some(UsageBilling::Calculated(Box::new(
+                CalculatedBillingBreakdown {
+                    input_amount: usd("0.03"),
+                    output_amount: usd("0.07"),
+                    cache_read_amount: usd("0.00"),
+                    cache_write_amount: usd("0.00"),
+                    standard_amount: usd("0.10"),
+                    total_amount: usd("0.10"),
+                    input_price_per_million: usd("10.0000"),
+                    output_price_per_million: usd("60.0000"),
+                    cache_read_price_per_million: usd("1.0000"),
+                    cache_write_price_per_million: usd("12.5000"),
+                    service_tier: Some("priority".to_owned()),
+                    multiplier_percent: 100,
+                },
+            ))),
+            transport_decision_wait_ms: Some(7),
+            connect_ms: Some(11),
+            headers_ms: Some(13),
+            first_event_ms: Some(17),
+            first_reasoning_ms: Some(19),
+            first_text_ms: Some(23),
+            first_token_ms: Some(19),
+            provider_processing_ms: Some(29),
+            latency_ms: Some(31),
+            client_ip: Some("127.0.0.1".to_owned()),
+            user_agent: Some("usage-metadata-test".to_owned()),
+            reasoning_effort: Some("max".to_owned()),
+            reasoning_preset: Some("ultra".to_owned()),
+            request_kind: Some("review".to_owned()),
+            subagent_kind: Some("worker".to_owned()),
+            compact: true,
+            image_generation_requested: true,
+            image_generation_succeeded: Some(true),
+            started_at: Utc::now(),
+            deadline_at: Utc::now(),
+            completed_at: Some(Utc::now()),
+        });
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/usage/records")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_usage_endpoint")
+                .body(Body::empty())
+                .expect("usage request"),
+        )
+        .await
+        .expect("usage response");
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = to_bytes(response.into_body(), 1024 * 1024)
+        .await
+        .expect("usage response body");
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("usage response JSON");
+
+    assert_eq!(
+        value["data"]["items"][0]["billing"]["inputPriceDisplay"],
+        "$10 / 1M Token"
+    );
+    assert_eq!(
+        value["data"]["items"][0]["billing"]["outputPriceDisplay"],
+        "$60 / 1M Token"
+    );
+    assert_eq!(
+        value["data"]["items"][0]["billing"]["cacheWritePriceDisplay"],
+        "$12.5 / 1M Token"
+    );
+
+    assert_eq!(
+        serde_json::json!({
+            "route": value["data"]["items"][0]["route"],
+            "routingScope": value["data"]["items"][0]["routingScope"],
+            "routingGroupRefs": value["data"]["items"][0]["routingGroupRefs"],
+            "routingGroupNamesSnapshot": value["data"]["items"][0]["routingGroupNamesSnapshot"],
+            "serviceTier": value["data"]["items"][0]["serviceTier"],
+            "accountId": value["data"]["items"][0]["accountId"],
+            "accountName": value["data"]["items"][0]["accountName"],
+            "accountEmail": value["data"]["items"][0]["accountEmail"],
+            "authenticationKind": value["data"]["items"][0]["authenticationKind"],
+            "imageInputTokens": value["data"]["items"][0]["tokenDetails"]["imageInputTokens"],
+            "imageOutputTokens": value["data"]["items"][0]["tokenDetails"]["imageOutputTokens"],
+            "websocketPool": value["data"]["items"][0]["websocketPool"],
+            "imageGenerationRequested": value["data"]["items"][0]["imageGenerationRequested"],
+            "imageGenerationSucceeded": value["data"]["items"][0]["imageGenerationSucceeded"],
+            "requestedModel": value["data"]["items"][0]["requestedModel"],
+            "upstreamModel": value["data"]["items"][0]["upstreamModel"],
+            "clientIp": value["data"]["items"][0]["clientIp"],
+            "userAgent": value["data"]["items"][0]["userAgent"],
+            "reasoningEffort": value["data"]["items"][0]["reasoningEffort"],
+            "reasoningPreset": value["data"]["items"][0]["reasoningPreset"],
+            "requestKind": value["data"]["items"][0]["requestKind"],
+            "subagentKind": value["data"]["items"][0]["subagentKind"],
+            "compact": value["data"]["items"][0]["compact"],
+            "transport": value["data"]["items"][0]["transport"],
+            "transportDecisionWaitMs": value["data"]["items"][0]["latencyDetails"]["transportDecisionWaitMs"],
+            "wsConnectMs": value["data"]["items"][0]["latencyDetails"]["wsConnectMs"],
+            "firstReasoningMs": value["data"]["items"][0]["latencyDetails"]["firstReasoningMs"],
+            "firstTextMs": value["data"]["items"][0]["latencyDetails"]["firstTextMs"],
+            "firstTokenMs": value["data"]["items"][0]["latencyDetails"]["firstTokenMs"],
+            "effectiveModel": value["data"]["items"][0]["metadata"]["effectiveModel"],
+            "requestSummary": value["data"]["items"][0]["metadata"]["requestSummary"],
+        }),
+        serde_json::json!({
+            "route": "/v1/responses",
+            "routingScope": "groups",
+            "routingGroupRefs": ["grp_usage"],
+            "routingGroupNamesSnapshot": ["Usage group"],
+            "serviceTier": "priority",
+            "accountId": "acct_snapshot",
+            "accountName": "Snapshot Alpha",
+            "accountEmail": "alpha@example.invalid",
+            "authenticationKind": "oauth",
+            "imageInputTokens": 31,
+            "imageOutputTokens": 9,
+            "websocketPool": {"kind": "reuse"},
+            "imageGenerationRequested": true,
+            "imageGenerationSucceeded": true,
+            "requestedModel": "grok-4.5",
+            "upstreamModel": "grok-4.5",
+            "clientIp": "127.0.0.1",
+            "userAgent": "usage-metadata-test",
+            "reasoningEffort": "max",
+            "reasoningPreset": "ultra",
+            "requestKind": "review",
+            "subagentKind": "worker",
+            "compact": true,
+            "transport": "http_sse",
+            "transportDecisionWaitMs": 7,
+            "wsConnectMs": 11,
+            "firstReasoningMs": 19,
+            "firstTextMs": 23,
+            "firstTokenMs": 19,
+            "effectiveModel": "grok-4.5",
+            "requestSummary": {"inputItemsCount": 2},
+        })
+    );
+}
@@ -62,6 +62,123 @@ fn settings_request_should_reject_unknown_rotation_strategy() {
    assert_eq!(request.validate().unwrap_err().field(), "rotationStrategy");
 }

+#[test]
+fn settings_response_should_cover_the_full_runtime_settings_contract() {
+    use std::collections::BTreeMap;
+
+    use chrono::{TimeZone, Utc};
+    use gateway_admin::model::Revision;
+    use gateway_admin::model::settings::RuntimeSettings;
+    use gateway_api::admin::settings::RuntimeSettingsView;
+    use gateway_core::engine::credential::RotationStrategy;
+    use gateway_core::routing::{PublicModelId, UpstreamModelId};
+
+    let settings = RuntimeSettings {
+        config_revision: Revision::new(7).expect("revision"),
+        model_mappings: BTreeMap::from_iter([
+            (
+                PublicModelId::new("gpt-5.4").expect("public model"),
+                UpstreamModelId::new("gpt-5.5").expect("upstream model"),
+            ),
+            (
+                PublicModelId::new("grok-latest").expect("public model"),
+                UpstreamModelId::new("grok-4.5").expect("upstream model"),
+            ),
+        ]),
+        refresh_margin_seconds: 1800,
+        refresh_concurrency: 4,
+        max_concurrent_per_account: 5,
+        request_interval_ms: 25,
+        rotation_strategy: RotationStrategy::RoundRobin,
+        usage_retention_days: 32,
+        ops_event_retention_days: 31,
+        audit_retention_days: 91,
+        updated_at: Utc
+            .with_ymd_and_hms(2026, 8, 2, 10, 30, 0)
+            .single()
+            .expect("timestamp"),
+    };
+
+    let value = serde_json::to_value(RuntimeSettingsView::from(settings)).expect("serialize view");
+    assert_eq!(
+        value,
+        json!({
+            "modelMappings": {
+                "gpt-5.4": "gpt-5.5",
+                "grok-latest": "grok-4.5"
+            },
+            "refreshMarginSeconds": 1800,
+            "refreshConcurrency": 4,
+            "maxConcurrentPerAccount": 5,
+            "requestIntervalMs": 25,
+            "rotationStrategy": "round_robin",
+            "usageRetentionDays": 32,
+            "opsEventRetentionDays": 31,
+            "auditRetentionDays": 91,
+            "updatedAt": "2026-08-02T10:30:00Z"
+        })
+    );
+}
+
+#[test]
+fn settings_request_and_response_fields_should_stay_in_lockstep() {
+    use std::collections::{BTreeMap, BTreeSet};
+
+    use gateway_admin::model::Revision;
+    use gateway_admin::model::settings::RuntimeSettings;
+    use gateway_api::admin::settings::RuntimeSettingsView;
+    use gateway_core::engine::credential::RotationStrategy;
+    use gateway_core::routing::{PublicModelId, UpstreamModelId};
+
+    let request: UpdateRuntimeSettingsRequest =
+        serde_json::from_value(update_body()).expect("decode settings");
+    request.validate().expect("fixture settings must validate");
+
+    let request_fields: BTreeSet<String> = update_body()
+        .as_object()
+        .expect("request body object")
+        .keys()
+        .cloned()
+        .collect();
+    let settings = RuntimeSettings {
+        config_revision: Revision::new(7).expect("revision"),
+        model_mappings: request
+            .model_mappings
+            .iter()
+            .map(|(public, upstream)| {
+                Ok((
+                    PublicModelId::new(public.clone())?,
+                    UpstreamModelId::new(upstream.clone())?,
+                ))
+            })
+            .collect::<Result<BTreeMap<_, _>, gateway_core::error::IdentifierError>>()
+            .expect("valid model mappings"),
+        refresh_margin_seconds: request.refresh_margin_seconds,
+        refresh_concurrency: u32::try_from(request.refresh_concurrency).expect("u32"),
+        max_concurrent_per_account: u32::try_from(request.max_concurrent_per_account).expect("u32"),
+        request_interval_ms: request.request_interval_ms,
+        rotation_strategy: RotationStrategy::parse(&request.rotation_strategy)
+            .expect("fixture rotation strategy"),
+        usage_retention_days: u32::try_from(request.usage_retention_days).expect("u32"),
+        ops_event_retention_days: u32::try_from(request.ops_event_retention_days).expect("u32"),
+        audit_retention_days: u32::try_from(request.audit_retention_days).expect("u32"),
+        updated_at: chrono::Utc::now(),
+    };
+
+    let response_fields: BTreeSet<String> =
+        serde_json::to_value(RuntimeSettingsView::from(settings))
+            .expect("serialize view")
+            .as_object()
+            .expect("view object")
+            .keys()
+            .cloned()
+            .collect();
+    let mut expected_fields = request_fields;
+    expected_fields.insert("updatedAt".to_owned());
+
+    assert_eq!(response_fields, expected_fields);
+}
+
 #[test]
 fn settings_request_should_reject_unknown_revision_field() {
    let mut body = update_body();
@@ -33,11 +33,18 @@ fn source_tree_should_match_frozen_machine_manifest() {
    let mut actual = rust_files(&root.join("src"));
    actual.sort();
    let mut expected = vec![
+        "src/admin/account_groups.rs",
        "src/admin/accounts.rs",
        "src/admin/auth.rs",
+        "src/admin/backups.rs",
        "src/admin/client_keys.rs",
        "src/admin/mod.rs",
-        "src/admin/observability.rs",
+        "src/admin/observability/mod.rs",
+        "src/admin/observability/presenter.rs",
+        "src/admin/observability/query.rs",
+        "src/admin/observability/routes.rs",
+        "src/admin/observability/wire.rs",
+        "src/admin/presenter.rs",
        "src/admin/settings.rs",
        "src/admin/system.rs",
        "src/admin/wire.rs",
@@ -67,11 +74,14 @@ fn test_tree_should_match_frozen_rust_mirror() {
    let mut actual = rust_files(&root.join("tests"));
    actual.sort();
    let mut expected = vec![
+        "tests/admin/account_groups.rs",
        "tests/admin/accounts.rs",
        "tests/admin/auth.rs",
        "tests/admin/client_keys.rs",
        "tests/admin/mod.rs",
-        "tests/admin/observability.rs",
+        "tests/admin/observability/mod.rs",
+        "tests/admin/observability/query.rs",
+        "tests/admin/observability/response.rs",
        "tests/admin/settings.rs",
        "tests/admin/system.rs",
        "tests/admin/wire.rs",
@@ -58,6 +58,30 @@ fn no_available_provider_error_should_map_to_service_unavailable() {
    );
 }

+#[test]
+fn account_capacity_error_should_map_to_service_unavailable() {
+    assert_eq!(
+        gateway_error_contract(GatewayErrorKind::AccountCapacityUnavailable),
+        (
+            StatusCode::SERVICE_UNAVAILABLE,
+            "server_error",
+            "account_capacity_unavailable",
+        )
+    );
+}
+
+#[test]
+fn provider_infrastructure_error_should_map_to_service_unavailable() {
+    assert_eq!(
+        gateway_error_contract(GatewayErrorKind::ProviderInfrastructureUnavailable),
+        (
+            StatusCode::SERVICE_UNAVAILABLE,
+            "server_error",
+            "provider_infrastructure_unavailable",
+        )
+    );
+}
+
 #[test]
 fn rate_limited_error_should_map_to_openai_retryable_status() {
    assert_eq!(
@@ -122,30 +146,32 @@ fn engine_provider_error_should_preserve_retry_classification() {
 #[test]
 fn local_provider_capacity_exhaustion_should_map_to_service_unavailable() {
    let error = EngineError::Provider(ProviderError::new(
-        ProviderErrorKind::Unavailable,
+        ProviderErrorKind::AccountCapacityUnavailable,
        UpstreamSendState::NotSent,
    ));

    assert_eq!(
        gateway_error_from_engine(&error),
        GatewayError::new(
-            GatewayErrorKind::NoAvailableProvider,
-            "no upstream provider is currently available for this request"
+            GatewayErrorKind::AccountCapacityUnavailable,
+            "all eligible upstream accounts are temporarily busy"
        )
    );
 }

 #[test]
-fn local_provider_capacity_exhaustion_should_preserve_safe_provider_detail() {
+fn no_eligible_provider_account_should_preserve_safe_provider_detail() {
    let detail = ClientVisibleUpstreamError::new(
        "no account is eligible for the requested model",
        Some("no_eligible_account".to_owned()),
        Some("account_unavailable_error".to_owned()),
-    )
-    .expect("safe provider detail");
+    );
    let error = EngineError::Provider(
-        ProviderError::new(ProviderErrorKind::Unavailable, UpstreamSendState::NotSent)
-            .with_client_visible_upstream_error(detail),
+        ProviderError::new(
+            ProviderErrorKind::NoEligibleAccount,
+            UpstreamSendState::NotSent,
+        )
+        .with_client_visible_upstream_error(detail),
    );
    let gateway = gateway_error_from_engine(&error);

@@ -165,6 +191,22 @@ fn local_provider_capacity_exhaustion_should_preserve_safe_provider_detail() {
    );
 }

+#[test]
+fn provider_infrastructure_failure_should_have_a_distinct_client_contract() {
+    let error = EngineError::Provider(ProviderError::new(
+        ProviderErrorKind::ProviderInfrastructureUnavailable,
+        UpstreamSendState::NotSent,
+    ));
+
+    assert_eq!(
+        gateway_error_from_engine(&error),
+        GatewayError::new(
+            GatewayErrorKind::ProviderInfrastructureUnavailable,
+            "provider account infrastructure is temporarily unavailable"
+        )
+    );
+}
+
 #[test]
 fn no_eligible_provider_account_should_map_to_service_unavailable() {
    let error = EngineError::Provider(ProviderError::new(
@@ -182,16 +224,18 @@ fn no_eligible_provider_account_should_map_to_service_unavailable() {
 }

 #[test]
-fn sent_provider_unavailability_should_remain_bad_gateway() {
-    let error = EngineError::Provider(ProviderError::new(
-        ProviderErrorKind::Unavailable,
-        UpstreamSendState::Sent,
-    ));
+fn provider_unavailability_should_remain_bad_gateway_regardless_of_send_state() {
+    for send_state in [UpstreamSendState::NotSent, UpstreamSendState::Sent] {
+        let error = EngineError::Provider(ProviderError::new(
+            ProviderErrorKind::Unavailable,
+            send_state,
+        ));

-    assert_eq!(
-        gateway_error_from_engine(&error).kind(),
-        GatewayErrorKind::UpstreamUnavailable
-    );
+        assert_eq!(
+            gateway_error_from_engine(&error).kind(),
+            GatewayErrorKind::UpstreamUnavailable
+        );
+    }
 }

 #[test]
@@ -327,14 +371,11 @@ fn openai_error_response_should_preserve_only_safe_contract_fields() {
 async fn gateway_error_response_should_expose_only_structured_client_visible_upstream_fields() {
    let error = GatewayError::from_provider(
        &ProviderError::new(ProviderErrorKind::QuotaExhausted, UpstreamSendState::Sent)
-            .with_client_visible_upstream_error(
-                ClientVisibleUpstreamError::new(
-                    "Your Codex quota is exhausted",
-                    Some("quota_exhausted".to_owned()),
-                    Some("rate_limit_error".to_owned()),
-                )
-                .expect("safe structured upstream error"),
-            ),
+            .with_client_visible_upstream_error(ClientVisibleUpstreamError::new(
+                "Your Codex quota is exhausted",
+                Some("quota_exhausted".to_owned()),
+                Some("rate_limit_error".to_owned()),
+            )),
    );

    let response = gateway_error_response(&error);
@@ -4,7 +4,7 @@ mod models;
 mod responses;
 mod router;

-use std::collections::BTreeSet;
+use std::collections::{BTreeMap, BTreeSet};
 use std::num::NonZeroU32;
 use std::sync::Arc;
 use std::time::{Duration, SystemTime};
@@ -18,7 +18,9 @@ use gateway_core::engine::admission::{
 use gateway_core::engine::continuation::{
    NativeContinuationPin, NativeContinuationPort, NativeContinuationStoreError, PreviousResponseId,
 };
-use gateway_core::engine::credential::{AccountSelectionPolicy, RotationStrategy};
+use gateway_core::engine::credential::{
+    AccountSelectionPolicy, ProviderAccountId, RotationStrategy,
+};
 use gateway_core::engine::execution::{
    AuthenticatedClient, ClientApiKeyUsageSink, DefaultExecutionService, ExecutionService,
    ProviderCircuitDecision, ProviderCircuitError, ProviderCircuitPort,
@@ -34,8 +36,8 @@ use gateway_core::lifecycle::{ConnectionDraining, ConnectionGuard, ConnectionLif
 use gateway_core::policy::{ClientApiKeyId, ClientPolicy, PlaintextClientApiKey, RateLimits};
 use gateway_core::routing::snapshot::RuntimeSnapshotHandle;
 use gateway_core::routing::{
-    ConfigRevision, ModelCapabilities, ProviderKind, ProviderModel, RuntimeSnapshot,
-    UpstreamModelId,
+    ClientRoutingScope, ConfigRevision, FrozenAccountScope, ModelCapabilities, ProviderKind,
+    ProviderModel, RuntimeAccount, RuntimeAccountDirectory, RuntimeSnapshot, UpstreamModelId,
 };

 pub(super) async fn api_router(execution: Arc<dyn ExecutionService>) -> axum::Router {
@@ -94,6 +96,10 @@ impl ClientApiKeyUsageSink for IgnoredClientApiKeyUsage {

 fn snapshot(plaintext: &str, provider_name: &str) -> RuntimeSnapshot {
    let provider = ProviderKind::new(provider_name).expect("provider");
+    let account_directory = Arc::new(RuntimeAccountDirectory::new(BTreeMap::from([(
+        ProviderAccountId::new("acct_api_test").expect("account ID"),
+        RuntimeAccount::new(provider.clone(), BTreeSet::new()),
+    )])));
    let capabilities = ModelCapabilities::new(
        BTreeSet::from([gateway_core::operation::OperationKind::Generate]),
        Some(16_000),
@@ -119,12 +125,16 @@ fn snapshot(plaintext: &str, provider_name: &str) -> RuntimeSnapshot {
        vec![ClientPolicy::new(
            ClientApiKeyId::new("key_api_test").expect("key ID"),
            PlaintextClientApiKey::new(plaintext).expect("plaintext key"),
-            provider,
+            Arc::new(FrozenAccountScope::new(
+                Arc::clone(&account_directory),
+                ClientRoutingScope::all_accounts(),
+            )),
            true,
            RateLimits::unlimited(),
        )],
    )
    .expect("runtime snapshot")
+    .with_account_directory(account_directory)
 }

 #[derive(Default)]
@@ -260,6 +270,7 @@ struct UnusedContinuation;
 impl NativeContinuationPort for UnusedContinuation {
    fn resolve<'a>(
        &'a self,
+        _: &'a ClientApiKeyId,
        _: &'a PreviousResponseId,
    ) -> BoxFuture<'a, Result<Option<NativeContinuationPin>, NativeContinuationStoreError>> {
        Box::pin(async { unreachable!("authentication fixture does not execute") })
@@ -8,7 +8,10 @@ use std::sync::{
 use axum::{
    body::{Body, to_bytes},
    extract::connect_info::ConnectInfo,
-    http::{HeaderMap, Request, StatusCode, header::AUTHORIZATION},
+    http::{
+        HeaderMap, HeaderValue, Request, StatusCode,
+        header::{AUTHORIZATION, CONTENT_TYPE},
+    },
 };
 use bytes::Bytes;
 use futures::future::{BoxFuture, pending};
@@ -18,8 +21,8 @@ use gateway_core::engine::execution::{
 };
 use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError, UpstreamSendState};
 use gateway_core::error::{
-    ClientVisibleUpstreamError, GatewayError, GatewayErrorKind, ProviderError, ProviderErrorKind,
-    SafeUpstreamValue,
+    ClientVisibleUpstreamError, ClientVisibleUpstreamResponse, GatewayError, GatewayErrorKind,
+    ProviderError, ProviderErrorKind,
 };
 use gateway_core::event::{
    ContentItem, ContentKind, GatewayEvent, ProtocolWireEvent, ProviderEvent,
@@ -101,6 +104,8 @@ struct ContextCaptureExecution {

 #[derive(Debug, Clone, PartialEq)]
 struct CapturedClientContext {
+    public_model: String,
+    wire_model: Option<String>,
    client_ip: Option<IpAddr>,
    user_agent: Option<String>,
    endpoint: String,
@@ -109,6 +114,7 @@ struct CapturedClientContext {
    client_metadata: Option<Value>,
    protocol_context: Option<Value>,
    prompt_cache_key: Option<String>,
+    previous_response_id: Option<String>,
 }

 impl ExecutionService for ContextCaptureExecution {
@@ -124,11 +130,14 @@ impl ExecutionService for ContextCaptureExecution {
    }

    fn public_models(&self, _: &AuthenticatedClient) -> Vec<PublicModelId> {
-        Vec::new()
+        ["model-a", "model-b"]
+            .into_iter()
+            .map(|model| PublicModelId::new(model).expect("catalog model"))
+            .collect()
    }

-    fn contains_public_model(&self, _: &AuthenticatedClient, _: &PublicModelId) -> bool {
-        true
+    fn contains_public_model(&self, _: &AuthenticatedClient, model: &PublicModelId) -> bool {
+        matches!(model.as_str(), "model-a" | "model-b")
    }

    fn start(
@@ -136,11 +145,16 @@ impl ExecutionService for ContextCaptureExecution {
        request: StartExecution,
    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
        Box::pin(async move {
+            let public_model = request.public_model.as_str().to_owned();
            let operation_kind = request.operation.kind();
            let generation = match &request.operation {
                Operation::Generate(generation) => Some(generation),
                _ => None,
            };
+            let wire_model = generation
+                .and_then(|generation| generation.protocol_payload().body().get("model"))
+                .and_then(Value::as_str)
+                .map(ToOwned::to_owned);
            let (client_metadata, protocol_context, prompt_cache_key, input) =
                generation.map_or((None, None, None, None), |generation| {
                    let payload = generation.protocol_payload();
@@ -152,7 +166,14 @@ impl ExecutionService for ContextCaptureExecution {
                        payload.body().get("input").cloned(),
                    )
                });
+            let previous_response_id = request
+                .metadata
+                .previous_response_id
+                .as_ref()
+                .map(|value| value.as_str().to_owned());
            *self.observed.lock().expect("context capture lock") = Some(CapturedClientContext {
+                public_model,
+                wire_model,
                client_ip: request.metadata.client_ip,
                user_agent: request.metadata.user_agent,
                endpoint: request.metadata.endpoint,
@@ -161,6 +182,7 @@ impl ExecutionService for ContextCaptureExecution {
                client_metadata,
                protocol_context,
                prompt_cache_key,
+                previous_response_id,
            });
            Err(GatewayError::new(
                GatewayErrorKind::Internal,
@@ -503,14 +525,18 @@ async fn request_context_should_resolve_forwarded_precedence_and_peer_fallback()
    assert_eq!(
        captured_client_context(headers, peer).await,
        CapturedClientContext {
+            public_model: "smart-code".to_owned(),
+            wire_model: Some("smart-code".to_owned()),
            client_ip: Some("198.51.100.1".parse().expect("expected IP")),
            user_agent: Some("Codex-CLI/1.0".to_owned()),
            endpoint: "/v1/responses".to_owned(),
            operation_kind: OperationKind::Generate,
            input: Some(json!("hello")),
            client_metadata: None,
+            // 客户端 User-Agent 仅用于本地展示，不再透传给上游指纹上下文。
            protocol_context: None,
            prompt_cache_key: None,
+            previous_response_id: None,
        }
    );

@@ -533,14 +559,58 @@ async fn request_context_should_resolve_forwarded_precedence_and_peer_fallback()
 }

 #[tokio::test]
-async fn http_request_should_forward_safe_codex_headers_without_projecting_xai_headers() {
+async fn stale_model_catalog_should_not_block_a_new_model_request() {
+    let model = "  gpt-future-codex  ";
+    let captured = captured_http_request(
+        "openai",
+        json!({"model": model, "input": "hello"}),
+        HeaderMap::new(),
+        None,
+    )
+    .await;
+
+    assert_eq!(captured.public_model, model);
+    assert_eq!(captured.wire_model.as_deref(), Some(model));
+}
+
+#[tokio::test]
+async fn http_request_should_pass_opaque_previous_response_id_to_core() {
+    for response_id in [
+        format!("resp_{}", "x".repeat(257)),
+        "resp_control\0opaque".to_owned(),
+        String::new(),
+    ] {
+        let captured = captured_http_request(
+            "openai",
+            json!({
+                "model": "smart-code",
+                "input": "continue",
+                "previous_response_id": response_id.clone()
+            }),
+            HeaderMap::new(),
+            None,
+        )
+        .await;
+
+        assert_eq!(
+            captured.previous_response_id.as_deref(),
+            Some(response_id.as_str())
+        );
+    }
+}
+
+#[tokio::test]
+async fn http_request_should_forward_codex_headers_without_projecting_xai_headers() {
    let peer = "192.0.2.10:443".parse().expect("peer address");
    let mut headers = HeaderMap::new();
    headers.insert("x-codex-turn-state", "turn-state".parse().expect("header"));
    headers.insert("conversation-id", "conversation-1".parse().expect("header"));
    headers.insert("session-id", "session-1".parse().expect("header"));
    headers.insert("x-grok-turn-idx", "7".parse().expect("header"));
-    headers.insert("x-openai-subagent", "compact".parse().expect("header"));
+    headers.insert(
+        "x-openai-subagent",
+        "future_codex_mode".parse().expect("header"),
+    );
    headers.insert(
        "x-openai-internal-codex-responses-lite",
        "true".parse().expect("header"),
@@ -566,10 +636,33 @@ async fn http_request_should_forward_safe_codex_headers_without_projecting_xai_h
            .client_metadata
            .as_ref()
            .and_then(|metadata| metadata.get("x-openai-subagent")),
-        Some(&json!("compact"))
+        Some(&json!("future_codex_mode"))
    );
 }

+#[tokio::test]
+async fn subagent_header_should_not_replace_non_object_client_metadata() {
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        "x-openai-subagent",
+        "future_codex_mode".parse().expect("header"),
+    );
+
+    let captured = captured_http_request(
+        "openai",
+        json!({
+            "model": "smart-code",
+            "input": "preserve metadata",
+            "client_metadata": "opaque-client-value"
+        }),
+        headers,
+        None,
+    )
+    .await;
+
+    assert_eq!(captured.client_metadata, Some(json!("opaque-client-value")));
+}
+
 #[tokio::test]
 async fn xai_private_headers_should_not_enter_openai_request_facts() {
    let peer = "192.0.2.10:443".parse().expect("peer address");
@@ -632,6 +725,43 @@ async fn review_route_should_inject_review_subagent_and_record_its_endpoint() {
    );
 }

+#[tokio::test]
+async fn review_route_should_not_replace_non_object_client_metadata() {
+    let observed = Arc::new(Mutex::new(None));
+    let execution = Arc::new(ContextCaptureExecution {
+        observed: Arc::clone(&observed),
+        client: authenticated_client("sk_context_test"),
+    });
+    let request = Request::post("/v1/responses/review")
+        .header(AUTHORIZATION, "Bearer sk_context_test")
+        .body(Body::from(
+            json!({
+                "model": "smart-code",
+                "input": "review this",
+                "client_metadata": ["opaque", "client", "value"]
+            })
+            .to_string(),
+        ))
+        .expect("review request");
+
+    let response = api_router(execution)
+        .await
+        .oneshot(request)
+        .await
+        .expect("review response");
+    let captured = observed
+        .lock()
+        .expect("review capture lock")
+        .clone()
+        .expect("captured review request");
+
+    assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
+    assert_eq!(
+        captured.client_metadata,
+        Some(json!(["opaque", "client", "value"]))
+    );
+}
+
 #[tokio::test]
 async fn streaming_encodes_first_frame_before_commit_and_http_delivery() {
    let trace = Arc::new(Trace::default());
@@ -653,19 +783,22 @@ async fn streaming_encodes_first_frame_before_commit_and_http_delivery() {
 }

 #[tokio::test]
-async fn streaming_response_forwards_only_allowlisted_provider_headers() {
+async fn streaming_response_should_append_ordinary_headers_and_skip_unrepresentable_or_sensitive_ones()
+ {
    let trace = Arc::new(Trace::default());
    let headers = vec![
-        ProviderResponseHeader::new(
-            "x-models-etag",
-            SafeUpstreamValue::new("models-v2").expect("etag"),
-        )
-        .expect("safe header"),
+        ProviderResponseHeader::new("x-models-etag", Bytes::from_static(b"models-v2")),
+        ProviderResponseHeader::new("x-future-multi", Bytes::from_static(b"first")),
+        ProviderResponseHeader::new("x-future-multi", Bytes::from_static(b"second")),
+        ProviderResponseHeader::new("x-future-bytes", Bytes::from_static(b"\xffopaque")),
        ProviderResponseHeader::new(
            "authorization",
-            SafeUpstreamValue::new("should-not-cross-boundary").expect("header value"),
-        )
-        .expect("syntactically safe header"),
+            Bytes::from_static(b"should-not-cross-boundary"),
+        ),
+        ProviderResponseHeader::new("connection", Bytes::from_static(b"x-hop-secret")),
+        ProviderResponseHeader::new("x-hop-secret", Bytes::from_static(b"hop-secret")),
+        ProviderResponseHeader::new("content-type", Bytes::from_static(b"application/private")),
+        ProviderResponseHeader::new("bad\0name", Bytes::from_static(b"unrepresentable")),
    ];
    let session = FakeSession::streaming(
        Arc::clone(&trace),
@@ -685,7 +818,29 @@ async fn streaming_response_forwards_only_allowlisted_provider_headers() {
            .and_then(|value| value.to_str().ok()),
        Some("models-v2")
    );
+    assert_eq!(
+        response
+            .headers()
+            .get_all("x-future-multi")
+            .iter()
+            .map(HeaderValue::as_bytes)
+            .collect::<Vec<_>>(),
+        vec![b"first".as_slice(), b"second".as_slice()]
+    );
+    assert_eq!(
+        response
+            .headers()
+            .get("x-future-bytes")
+            .map(HeaderValue::as_bytes),
+        Some(b"\xffopaque".as_slice())
+    );
    assert!(response.headers().get("authorization").is_none());
+    assert!(response.headers().get("connection").is_none());
+    assert!(response.headers().get("x-hop-secret").is_none());
+    assert_eq!(
+        response.headers().get(CONTENT_TYPE),
+        Some(&HeaderValue::from_static("text/event-stream"))
+    );
    std::mem::forget(response);
 }

@@ -801,7 +956,107 @@ async fn streaming_rate_limit_before_first_frame_should_persist_the_returned_429
 }

 #[tokio::test]
-async fn streaming_postcommit_encode_failure_cancels_without_second_commit() {
+async fn streaming_upstream_http_failure_before_first_frame_should_preserve_raw_response() {
+    let trace = Arc::new(Trace::default());
+    let raw_body = Bytes::from_static(
+        b"{\"error\":{\"message\":\"rate limited\",\"future_field\":{\"kept\":true}},\"top_level\":17}\x00",
+    );
+    let error = ProviderError::new(ProviderErrorKind::RateLimited, UpstreamSendState::Sent)
+        .with_client_visible_upstream_response(
+            ClientVisibleUpstreamResponse::new(
+                429,
+                Some(b"application/problem+json; charset=utf-8".to_vec()),
+                raw_body.clone(),
+            )
+            .with_headers(vec![
+                ProviderResponseHeader::new("retry-after", Bytes::from_static(b"17")),
+                ProviderResponseHeader::new("x-request-id", Bytes::from_static(b"req-failure")),
+                ProviderResponseHeader::new("x-future-error", Bytes::from_static(b"first")),
+                ProviderResponseHeader::new("x-future-error", Bytes::from_static(b"second")),
+                ProviderResponseHeader::new("x-future-bytes", Bytes::from_static(b"\xffopaque")),
+            ]),
+        );
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![NextStep::Error(EngineError::Provider(error))],
+    );
+
+    let response = stream_execution_response(Box::new(session), None).await;
+
+    assert_eq!(response.status(), StatusCode::TOO_MANY_REQUESTS);
+    assert_eq!(
+        response
+            .headers()
+            .get(CONTENT_TYPE)
+            .map(|value| value.as_bytes()),
+        Some(b"application/problem+json; charset=utf-8".as_slice())
+    );
+    assert_eq!(
+        response
+            .headers()
+            .get("retry-after")
+            .map(|value| value.as_bytes()),
+        Some(b"17".as_slice())
+    );
+    assert_eq!(
+        response
+            .headers()
+            .get("x-request-id")
+            .map(|value| value.as_bytes()),
+        Some(b"req-failure".as_slice())
+    );
+    assert_eq!(
+        response
+            .headers()
+            .get_all("x-future-error")
+            .iter()
+            .map(|value| value.as_bytes())
+            .collect::<Vec<_>>(),
+        vec![b"first".as_slice(), b"second".as_slice()]
+    );
+    assert_eq!(
+        response
+            .headers()
+            .get("x-future-bytes")
+            .map(|value| value.as_bytes()),
+        Some(b"\xffopaque".as_slice())
+    );
+    assert_eq!(
+        to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("read raw error body"),
+        raw_body
+    );
+    assert_eq!(trace.client_statuses(), vec![429]);
+}
+
+#[tokio::test]
+async fn buffered_upstream_http_failure_should_preserve_raw_response() {
+    let trace = Arc::new(Trace::default());
+    let raw_body = Bytes::from_static(b"not-json\xffstill-upstream");
+    let error = ProviderError::new(ProviderErrorKind::Unavailable, UpstreamSendState::Sent)
+        .with_client_visible_upstream_response(ClientVisibleUpstreamResponse::new(
+            503,
+            Some(b"application/octet-stream".to_vec()),
+            raw_body.clone(),
+        ));
+    let session = FakeSession::buffered(Arc::clone(&trace), vec![started(), completed()])
+        .with_collect_error(EngineError::Provider(error));
+
+    let response = collect_execution_response(Box::new(session)).await;
+
+    assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+    assert_eq!(
+        to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("read raw error body"),
+        raw_body
+    );
+    assert_eq!(trace.client_statuses(), vec![503]);
+}
+
+#[tokio::test]
+async fn streaming_canonical_identity_change_does_not_interrupt_wire_delivery() {
    let trace = Arc::new(Trace::default());
    let session = FakeSession::streaming(
        Arc::clone(&trace),
@@ -811,7 +1066,7 @@ async fn streaming_postcommit_encode_failure_cancels_without_second_commit() {
                mismatched_terminal_event(),
                CommitRequirement::AlreadyCommitted,
            )),
-            NextStep::FinalizeCancelled,
+            NextStep::FinalizeSuccess,
        ],
    );

@@ -820,12 +1075,16 @@ async fn streaming_postcommit_encode_failure_cancels_without_second_commit() {
        .await
        .expect("read SSE body");

-    assert!(String::from_utf8_lossy(&body).contains("response.failed"));
+    let body = String::from_utf8_lossy(&body);
+    assert!(body.contains("response.completed"));
+    assert!(body.contains("resp_other"));
+    assert!(!body.contains("response.failed"));
+    assert!(body.ends_with("data: [DONE]\n\n"));
    assert_eq!(trace.client_statuses(), vec![200]);
-    assert!(trace.is_cancelled());
+    assert!(!trace.is_cancelled());
    assert_eq!(
        trace.snapshot(),
-        vec!["next_event", "commit", "next_event", "cancel_finalize"]
+        vec!["next_event", "commit", "next_event", "next_end"]
    );
 }

@@ -874,6 +1133,38 @@ async fn streaming_success_should_emit_terminal_event_and_done_marker() {
    );
 }

+#[tokio::test]
+async fn streaming_finalized_unknown_wire_should_end_cleanly_without_synthetic_failure() {
+    let trace = Arc::new(Trace::default());
+    let raw = Bytes::from_static(
+        b"event: response.future_terminal\ndata: {\"type\":\"response.future_terminal\",\"opaque\":true}\n\n",
+    );
+    let event = ProviderEvent::wire(
+        ProtocolWireEvent::raw_sse("openai", raw.clone()).expect("raw future event"),
+    );
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![
+            NextStep::Event(delivery_provider(
+                event,
+                CommitRequirement::CommitBeforeDelivery,
+            )),
+            NextStep::FinalizeSuccess,
+        ],
+    );
+
+    let response = stream_execution_response(Box::new(session), None).await;
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read transparent SSE body");
+
+    assert!(body.as_ref().starts_with(raw.as_ref()));
+    assert!(body.as_ref().ends_with(b"data: [DONE]\n\n"));
+    assert!(!String::from_utf8_lossy(&body).contains("response.failed"));
+    assert!(!trace.is_cancelled());
+    assert_eq!(trace.snapshot(), vec!["next_event", "commit", "next_end"]);
+}
+
 #[tokio::test]
 async fn streaming_completed_event_without_finalized_execution_should_fail_closed() {
    let trace = Arc::new(Trace::default());
@@ -942,14 +1233,11 @@ async fn streaming_empty_terminal_should_emit_failure_done_and_cancel_execution(
 async fn streaming_error_should_emit_client_visible_upstream_details() {
    let trace = Arc::new(Trace::default());
    let error = ProviderError::new(ProviderErrorKind::RateLimited, UpstreamSendState::Sent)
-        .with_client_visible_upstream_error(
-            ClientVisibleUpstreamError::new(
-                "Your Codex quota is exhausted",
-                Some("quota_exhausted".to_owned()),
-                Some("rate_limit_error".to_owned()),
-            )
-            .expect("safe structured upstream error"),
-        );
+        .with_client_visible_upstream_error(ClientVisibleUpstreamError::new(
+            "Your Codex quota is exhausted",
+            Some("quota_exhausted".to_owned()),
+            Some("rate_limit_error".to_owned()),
+        ));
    let session = FakeSession::streaming(
        Arc::clone(&trace),
        vec![
@@ -1055,6 +1343,86 @@ async fn streaming_upstream_wire_failure_should_not_be_rewritten_as_a_gateway_er
    );
 }

+#[tokio::test]
+async fn atomic_uncommitted_upstream_failure_batch_should_be_forwarded_once() {
+    let trace = Arc::new(Trace::default());
+    let raw_created = Bytes::from_static(
+        b"event: response.created\r\ndata: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_atomic_api\",\"model\":\"public-model\",\"status\":\"in_progress\"}}\r\n\r\n",
+    );
+    let raw_failure = Bytes::from_static(
+        b"event: response.failed\r\ndata: {\"type\":\"response.failed\",\"response\":{\"id\":\"resp_atomic_api\",\"status\":\"failed\",\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"atomic upstream marker\"}}}\r\n\r\n",
+    );
+    let started_wire = ProviderEvent::canonical_with_wire(
+        vec![started()],
+        ProtocolWireEvent::json_with_raw_sse_metadata(
+            "openai",
+            Some("response.created".to_owned()),
+            json!({
+                "type": "response.created",
+                "response": {
+                    "id": "resp_atomic_api",
+                    "model": "public-model",
+                    "status": "in_progress"
+                }
+            }),
+            raw_created.clone(),
+            None,
+            None,
+        )
+        .expect("valid upstream started wire"),
+    );
+    let failed_wire = ProviderEvent::wire(
+        ProtocolWireEvent::json_with_raw_sse_metadata(
+            "openai",
+            Some("response.failed".to_owned()),
+            json!({
+                "type": "response.failed",
+                "response": {
+                    "id": "resp_atomic_api",
+                    "status": "failed",
+                    "error": {
+                        "code": "rate_limit_exceeded",
+                        "message": "atomic upstream marker"
+                    }
+                }
+            }),
+            raw_failure.clone(),
+            None,
+            None,
+        )
+        .expect("valid upstream failure wire"),
+    );
+    let batch = CoordinatedEvent::try_batch(
+        vec![started_wire, failed_wire],
+        CommitRequirement::CommitBeforeDelivery,
+    )
+    .expect("atomic failure delivery");
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![
+            NextStep::Event(batch),
+            NextStep::Error(EngineError::Provider(ProviderError::new(
+                ProviderErrorKind::RateLimited,
+                UpstreamSendState::Sent,
+            ))),
+        ],
+    );
+
+    let response = stream_execution_response(Box::new(session), None).await;
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read SSE body");
+    let body = String::from_utf8(body.to_vec()).expect("SSE is UTF-8");
+
+    assert_eq!(body.matches("atomic upstream marker").count(), 1);
+    assert_eq!(body.matches("event: response.failed").count(), 1);
+    assert!(body.contains(std::str::from_utf8(&raw_created).expect("created frame")));
+    assert!(body.contains(std::str::from_utf8(&raw_failure).expect("failure frame")));
+    assert!(!body.contains("upstream capacity is temporarily unavailable"));
+    assert!(body.ends_with("data: [DONE]\n\n"));
+    assert_eq!(trace.snapshot(), vec!["next_event", "commit", "next_error"]);
+}
+
 #[tokio::test]
 async fn streaming_second_commit_request_should_fail_and_finalize_once() {
    let trace = Arc::new(Trace::default());
@@ -1132,13 +1500,10 @@ async fn buffered_response_commits_only_after_complete_json_is_encoded() {
 }

 #[tokio::test]
-async fn buffered_response_forwards_allowlisted_provider_headers() {
+async fn buffered_response_forwards_long_ordinary_provider_header_values() {
    let trace = Arc::new(Trace::default());
-    let header = ProviderResponseHeader::new(
-        "openai-model",
-        SafeUpstreamValue::new("gpt-5.5-effective").expect("model header"),
-    )
-    .expect("safe header");
+    let model = format!("gpt-{}", "x".repeat(512));
+    let header = ProviderResponseHeader::new("openai-model", Bytes::from(model.clone()));
    let session = FakeSession::buffered(Arc::clone(&trace), vec![started(), completed()])
        .with_response_headers(vec![header]);

@@ -1149,7 +1514,7 @@ async fn buffered_response_forwards_allowlisted_provider_headers() {
            .headers()
            .get("openai-model")
            .and_then(|value| value.to_str().ok()),
-        Some("gpt-5.5-effective")
+        Some(model.as_str())
    );
 }

@@ -2,6 +2,7 @@ mod http;
 mod websocket;

 use axum::http::{HeaderMap, HeaderValue};
+use base64::{Engine as _, engine::general_purpose::STANDARD};
 use bytes::Bytes;
 use gateway_api::openai::responses::{
    ContinuationIntent, DecodedResponsesRequest, OpenAiRequestHeaders, OpenAiResponsesEncoder,
@@ -117,6 +118,28 @@ fn decoder_should_preserve_the_openai_body_and_only_derive_stable_routing_facts(
    assert!(decoded.metadata().store());
 }

+#[test]
+fn decoder_should_preserve_opaque_client_model_values() {
+    for model in [
+        format!("future-{}", "x".repeat(512)),
+        "future\0model".to_owned(),
+        "  future-model  ".to_owned(),
+    ] {
+        let decoded = generate_request(json!({
+            "model": model.clone(),
+            "input": "hello"
+        }));
+
+        assert_eq!(decoded.metadata().public_model(), model);
+        assert_eq!(
+            openai_wire_body(&decoded)
+                .get("model")
+                .and_then(Value::as_str),
+            Some(model.as_str())
+        );
+    }
+}
+
 #[test]
 fn decoder_should_preserve_compaction_trigger_for_the_openai_provider() {
    let decoded = generate_request(json!({
@@ -149,6 +172,21 @@ fn decoder_should_keep_transport_override_out_of_the_openai_wire_body() {
    );
 }

+#[test]
+fn decoder_should_preserve_unrecognized_use_websocket_values() {
+    let decoded = generate_request(json!({
+        "model": "smart-code",
+        "input": "hello",
+        "use_websocket": {"future": "transport-mode"}
+    }));
+
+    assert_eq!(
+        openai_wire_body(&decoded).get("use_websocket"),
+        Some(&json!({"future": "transport-mode"}))
+    );
+    assert!(!openai_protocol_context(&decoded).contains_key("use_websocket"));
+}
+
 #[test]
 fn decoder_should_preserve_connection_metadata_outside_the_openai_wire_body() {
    let mut headers = HeaderMap::new();
@@ -170,10 +208,155 @@ fn decoder_should_preserve_connection_metadata_outside_the_openai_wire_body() {
            ("turn_state".to_owned(), json!("turn-state")),
            ("turn_metadata".to_owned(), json!("{\"kind\":\"review\"}")),
            ("conversation_id".to_owned(), json!("conversation")),
+            (
+                "opaque_request_headers".to_owned(),
+                json!([
+                    ["x-codex-turn-state", STANDARD.encode(b"turn-state")],
+                    [
+                        "x-codex-turn-metadata",
+                        STANDARD.encode(br#"{"kind":"review"}"#)
+                    ],
+                    ["conversation-id", STANDARD.encode(b"conversation")]
+                ]),
+            ),
        ])
    );
 }

+#[test]
+fn decoder_should_preserve_ordinary_request_headers_as_opaque_multivalues() {
+    let mut headers = HeaderMap::new();
+    headers.append(
+        "x-openai-future-mode",
+        HeaderValue::from_static("future-ascii"),
+    );
+    headers.append(
+        "x-openai-future-mode",
+        HeaderValue::from_bytes(b"\x80\xff").expect("opaque header bytes"),
+    );
+    headers.append("version", HeaderValue::from_static("future-v1"));
+    headers.append(
+        "version",
+        HeaderValue::from_bytes(b"future-\x80").expect("opaque known header bytes"),
+    );
+    headers.insert(
+        "accept",
+        HeaderValue::from_static("application/vnd.openai.responses+json"),
+    );
+    headers.insert(
+        "content-type",
+        HeaderValue::from_static("application/vnd.openai.responses.request+json"),
+    );
+    headers.insert(
+        "user-agent",
+        HeaderValue::from_static("Codex future-client"),
+    );
+    headers.insert("originator", HeaderValue::from_static("future-codex"));
+    headers.append(
+        "openai-beta",
+        HeaderValue::from_static("future_responses=v2"),
+    );
+    headers.append("openai-beta", HeaderValue::from_static("future_tools=v3"));
+    headers.insert(
+        "x-openai-internal-codex-residency",
+        HeaderValue::from_static("future-region"),
+    );
+    headers.insert(
+        "x-codex-turn-state",
+        HeaderValue::from_static("same-account-turn"),
+    );
+
+    headers.insert(
+        "connection",
+        HeaderValue::from_static("keep-alive, x-private-hop"),
+    );
+    headers.insert("x-private-hop", HeaderValue::from_static("drop-me"));
+    headers.insert("host", HeaderValue::from_static("downstream.invalid"));
+    headers.insert("content-length", HeaderValue::from_static("999"));
+    headers.insert("authorization", HeaderValue::from_static("Bearer client"));
+    headers.insert("x-api-key", HeaderValue::from_static("client-key"));
+    headers.insert("cookie", HeaderValue::from_static("client=cookie"));
+    headers.insert(
+        "chatgpt-account-id",
+        HeaderValue::from_static("client-account"),
+    );
+    headers.insert(
+        "chatgpt-project-id",
+        HeaderValue::from_static("client-project"),
+    );
+    headers.insert(
+        "x-codex-installation-id",
+        HeaderValue::from_static("client-installation"),
+    );
+    headers.insert(
+        "x-oai-attestation",
+        HeaderValue::from_static("client-attestation"),
+    );
+    headers.insert("x-oai-is", HeaderValue::from_static("client-is"));
+    headers.insert(
+        "x-oai-is-update",
+        HeaderValue::from_static("client-is-update"),
+    );
+
+    let decoded =
+        decode_request_with_headers(br#"{"model":"smart-code","input":"hello"}"#, &headers)
+            .expect("opaque request headers should not affect body decoding");
+    let entries = openai_protocol_context(&decoded)
+        .get("opaque_request_headers")
+        .and_then(Value::as_array)
+        .expect("opaque request header context");
+    let values = |target: &str| {
+        entries
+            .iter()
+            .filter_map(Value::as_array)
+            .filter(|entry| entry.first().and_then(Value::as_str) == Some(target))
+            .filter_map(|entry| entry.get(1).and_then(Value::as_str))
+            .map(|encoded| STANDARD.decode(encoded).expect("valid base64 header value"))
+            .collect::<Vec<_>>()
+    };
+
+    assert_eq!(
+        values("x-openai-future-mode"),
+        vec![b"future-ascii".to_vec(), b"\x80\xff".to_vec()]
+    );
+    assert_eq!(
+        values("version"),
+        vec![b"future-v1".to_vec(), b"future-\x80".to_vec()]
+    );
+    assert_eq!(
+        values("openai-beta"),
+        vec![b"future_responses=v2".to_vec(), b"future_tools=v3".to_vec()]
+    );
+    for preserved in [
+        "accept",
+        "content-type",
+        "x-openai-internal-codex-residency",
+        "x-codex-turn-state",
+    ] {
+        assert_eq!(values(preserved).len(), 1, "missing {preserved}");
+    }
+    for excluded in [
+        "connection",
+        "x-private-hop",
+        "host",
+        "content-length",
+        "authorization",
+        "x-api-key",
+        "cookie",
+        "chatgpt-account-id",
+        "chatgpt-project-id",
+        "x-codex-installation-id",
+        // 上游指纹由运行时画像统一生成，客户端不得覆盖。
+        "user-agent",
+        "originator",
+        "x-oai-attestation",
+        "x-oai-is",
+        "x-oai-is-update",
+    ] {
+        assert!(values(excluded).is_empty(), "unexpected {excluded}");
+    }
+}
+
 #[test]
 fn decoder_should_preserve_unknown_nested_values_without_debug_disclosure() {
    let secret = "nested-private-value";
@@ -191,25 +374,51 @@ fn decoder_should_preserve_unknown_nested_values_without_debug_disclosure() {
 }

 #[test]
-fn decoder_should_preserve_continuation_and_mark_the_routing_requirement() {
-    let decoded = generate_request(json!({
-        "model": "smart-code",
-        "input": "continue",
-        "previous_response_id": "resp_private_continuation"
-    }));
+fn decoder_should_preserve_unknown_arbitrary_precision_numbers() {
+    let number = "12345678901234567890123456789012345678901234567890";
+    let body = format!(r#"{{"model":"smart-code","input":"hello","future_number":{number}}}"#);

-    assert!(matches!(
-        decoded.metadata().continuation(),
-        ContinuationIntent::PreviousResponseId(value) if value == "resp_private_continuation"
-    ));
-    assert!(
-        decoded
-            .operation()
-            .capability_requirements()
-            .features()
-            .contains(&Feature::NativeContinuation)
-    );
-    assert!(!format!("{decoded:?}").contains("resp_private_continuation"));
+    let decoded = decode_request_with_headers(body.as_bytes(), &HeaderMap::new())
+        .expect("opaque numeric field should decode");
+    let encoded = serde_json::to_string(openai_wire_body(&decoded)).expect("encode request body");
+
+    assert!(encoded.contains(&format!(r#""future_number":{number}"#)));
+}
+
+#[test]
+fn decoder_should_preserve_opaque_continuation_and_mark_the_routing_requirement() {
+    for response_id in [
+        "resp_private_continuation".to_owned(),
+        format!("resp_{}\0opaque", "x".repeat(257)),
+        String::new(),
+    ] {
+        let decoded = generate_request(json!({
+            "model": "smart-code",
+            "input": "continue",
+            "previous_response_id": response_id.clone()
+        }));
+
+        assert!(matches!(
+            decoded.metadata().continuation(),
+            ContinuationIntent::PreviousResponseId(value) if value == &response_id
+        ));
+        assert_eq!(
+            openai_wire_body(&decoded)
+                .get("previous_response_id")
+                .and_then(Value::as_str),
+            Some(response_id.as_str())
+        );
+        assert!(
+            decoded
+                .operation()
+                .capability_requirements()
+                .features()
+                .contains(&Feature::NativeContinuation)
+        );
+        if !response_id.is_empty() {
+            assert!(!format!("{decoded:?}").contains(&response_id));
+        }
+    }
 }

 #[test]
@@ -242,10 +451,12 @@ fn decoder_should_not_reject_large_bodies_using_catalog_context_limits() {
    .to_string();
    let decoded = decode_request(body.as_bytes()).expect("large request should decode");

-    let plan = super::snapshot("sk_context_test", "openai")
+    let snapshot = super::snapshot("sk_context_test", "openai");
+    let plan = snapshot
        .plan(
            &PublicModelId::new(decoded.metadata().public_model()).expect("public model"),
            decoded.operation(),
+            snapshot.all_account_scope(),
            &RoutingContext::default(),
        )
        .expect("large body must not be locally context-gated");
@@ -316,7 +527,7 @@ fn transparent_encoder_should_forward_raw_sse_frames_unknown_events_and_terminal
    let mut encoder = OpenAiResponsesEncoder::new();
    let frames = events
        .iter()
-        .flat_map(|event| encoder.push_sse(event).expect("wire event should encode"))
+        .flat_map(|event| encoder.push_sse(event))
        .collect::<Vec<_>>();
    let response = encoder.finish().expect("wire response should finish");
    let body = frames
@@ -370,15 +581,11 @@ fn transparent_encoder_should_use_identical_json_for_sse_and_websocket() {

    let sse = events
        .iter()
-        .flat_map(|event| sse_encoder.push_sse(event).expect("SSE wire event"))
+        .flat_map(|event| sse_encoder.push_sse(event))
        .collect::<Vec<_>>();
    let websocket = events
        .iter()
-        .flat_map(|event| {
-            websocket_encoder
-                .push_websocket(event)
-                .expect("WebSocket wire event")
-        })
+        .flat_map(|event| websocket_encoder.push_websocket(event))
        .collect::<Vec<_>>();
    let sse_text = String::from_utf8(
        sse.iter()
@@ -400,8 +607,40 @@ fn transparent_encoder_should_use_identical_json_for_sse_and_websocket() {
 }

 #[test]
-fn transparent_encoder_should_require_matching_canonical_and_wire_terminals() {
+fn transparent_encoder_should_follow_wire_when_canonical_identity_changes() {
    let mut encoder = OpenAiResponsesEncoder::new();
+    let started = openai_wire_event(
+        vec![GatewayEvent::Started(ResponseMeta::new(
+            "resp_1", "gpt-test",
+        ))],
+        "response.created",
+        json!({"type": "response.created", "response": {"id": "wire_resp_1"}}),
+    );
+    encoder.push_sse(&started);
+    let changed_identity = openai_wire_event(
+        vec![GatewayEvent::Completed(ResponseMeta::new(
+            "resp_2", "gpt-test",
+        ))],
+        "response.completed",
+        json!({"type": "response.completed", "response": {"id": "wire_resp_2"}}),
+    );
+
+    let completed = encoder.push_sse(&changed_identity);
+
+    assert_eq!(completed.len(), 1);
+    assert!(encoder.is_completed());
+    assert_eq!(encoder.response_id(), Some("wire_resp_2"));
+    assert_eq!(
+        encoder
+            .finish()
+            .expect("wire terminal remains authoritative"),
+        json!({"id": "wire_resp_2"})
+    );
+}
+
+#[test]
+fn transparent_encoder_should_only_require_wire_terminal_for_buffered_conversion() {
+    let mut missing_terminal = OpenAiResponsesEncoder::new();
    let started = openai_wire_event(
        vec![GatewayEvent::Started(ResponseMeta::new(
            "resp_1", "gpt-test",
@@ -409,24 +648,8 @@ fn transparent_encoder_should_require_matching_canonical_and_wire_terminals() {
        "response.created",
        json!({"type": "response.created", "response": {"id": "resp_1"}}),
    );
-    encoder.push_sse(&started).expect("started event");
-    let changed_identity = openai_wire_event(
-        vec![GatewayEvent::Completed(ResponseMeta::new(
-            "resp_2", "gpt-test",
-        ))],
-        "response.completed",
-        json!({"type": "response.completed", "response": {"id": "resp_2"}}),
-    );

-    assert_eq!(
-        encoder
-            .push_sse(&changed_identity)
-            .expect_err("identity changes must fail"),
-        ResponseEncodeError::WireIdentityChanged
-    );
-
-    let mut missing_terminal = OpenAiResponsesEncoder::new();
-    missing_terminal.push_sse(&started).expect("started event");
+    missing_terminal.push_sse(&started);
    assert_eq!(
        missing_terminal
            .finish()
@@ -1,14 +1,35 @@
+use std::sync::{
+    Arc,
+    atomic::{AtomicBool, AtomicUsize, Ordering},
+};
+use std::time::{Duration, SystemTime};
+
 use axum::{
    body::Body,
    http::{Request, StatusCode, header::AUTHORIZATION},
 };
+use bytes::Bytes;
+use futures::{SinkExt, StreamExt, future::BoxFuture};
 use gateway_api::openai::responses::ResponseCreateFrameError;
+use gateway_core::engine::execution::{
+    AuthenticatedClient, ClientAuthenticationError, ExecutionService, ExecutionSession,
+    StartExecution, StartedExecution,
+};
+use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError, UpstreamSendState};
+use gateway_core::error::{GatewayError, ProviderError, ProviderErrorKind};
+use gateway_core::event::{
+    GatewayEvent, ProtocolWireEvent, ProviderEvent, ProviderResponseHeader, ResponseMeta,
+};
 use gateway_core::operation::Operation;
-use serde_json::json;
+use gateway_core::routing::PublicModelId;
+use serde_json::{Value, json};
+use tokio_tungstenite::connect_async;
+use tokio_tungstenite::tungstenite::Message as ClientMessage;
+use tokio_tungstenite::tungstenite::client::IntoClientRequest;
 use tower::ServiceExt;

 use super::decode_response_create;
-use crate::openai::{api_router, models::ModelsExecution};
+use crate::openai::{api_router, authenticated_client, models::ModelsExecution};

 #[test]
 fn response_create_should_default_to_the_websocket_streaming_contract() {
@@ -148,11 +169,403 @@ fn response_create_should_reject_non_boolean_stream_without_disclosing_body_valu
    assert!(!rendered.contains(opaque_stream_value));
 }

-// `serve_responses_websocket`/`forward_execution` 只有拿到 `hyper::upgrade::OnUpgrade`
-// 的真实 HTTP/1.1 升级连接才会运行;本 crate 的依赖图按 axum `ws` feature 编译
-// hyper(无 `http1`),测试进程内不存在能完成升级的服务端,`hyper::upgrade` 也不
-// 提供公开构造器。集成测试因此止步于 upgrade 边界:会话循环内的事件转发、错误帧
-// 与断连取消仍未被覆盖,需要 dev 依赖开启 `http1` 或 socket 泛化后才能落地。
+#[derive(Default)]
+struct AtomicFailureTrace {
+    next_calls: AtomicUsize,
+    committed: AtomicBool,
+    finalized: AtomicBool,
+}
+
+struct AtomicFailureSession {
+    trace: Arc<AtomicFailureTrace>,
+    response_headers: Vec<ProviderResponseHeader>,
+}
+
+impl ExecutionSession for AtomicFailureSession {
+    fn next_event(&mut self) -> BoxFuture<'_, Result<Option<CoordinatedEvent>, EngineError>> {
+        Box::pin(async move {
+            match self.trace.next_calls.fetch_add(1, Ordering::AcqRel) {
+                0 => Ok(Some(atomic_failure_batch())),
+                1 => {
+                    self.trace.finalized.store(true, Ordering::Release);
+                    Err(EngineError::Provider(ProviderError::new(
+                        ProviderErrorKind::RateLimited,
+                        UpstreamSendState::Sent,
+                    )))
+                }
+                _ => Ok(None),
+            }
+        })
+    }
+
+    fn collect_uncommitted(&mut self) -> BoxFuture<'_, Result<Vec<ProviderEvent>, EngineError>> {
+        Box::pin(async { Err(EngineError::InvalidDeliveryState) })
+    }
+
+    fn response_headers(&self) -> &[ProviderResponseHeader] {
+        &self.response_headers
+    }
+
+    fn commit_downstream(&mut self, _: Option<u16>) -> BoxFuture<'_, Result<(), EngineError>> {
+        Box::pin(async move {
+            self.trace.committed.store(true, Ordering::Release);
+            Ok(())
+        })
+    }
+
+    fn record_client_status(&mut self, _: u16) -> BoxFuture<'_, Result<(), EngineError>> {
+        Box::pin(async { Ok(()) })
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.trace.finalized.load(Ordering::Acquire)
+    }
+
+    fn cancel(&self) {}
+
+    fn detach_finalize(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move {
+            self.trace.finalized.store(true, Ordering::Release);
+        })
+    }
+}
+
+struct AtomicFailureExecution {
+    client: AuthenticatedClient,
+    trace: Arc<AtomicFailureTrace>,
+    response_headers: Vec<ProviderResponseHeader>,
+}
+
+impl ExecutionService for AtomicFailureExecution {
+    fn authenticate(
+        &self,
+        plaintext: &str,
+    ) -> Result<AuthenticatedClient, ClientAuthenticationError> {
+        (plaintext == "sk_ws_atomic")
+            .then(|| self.client.clone())
+            .ok_or(ClientAuthenticationError::InvalidKey)
+    }
+
+    fn public_models(&self, _: &AuthenticatedClient) -> Vec<PublicModelId> {
+        vec![PublicModelId::new("model-a").expect("public model")]
+    }
+
+    fn contains_public_model(&self, _: &AuthenticatedClient, model: &PublicModelId) -> bool {
+        model.as_str() == "model-a"
+    }
+
+    fn start(
+        &self,
+        request: StartExecution,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move {
+            Ok(StartedExecution {
+                request_id: gateway_core::engine::ModelRequestId::new("req_ws_atomic")
+                    .expect("request id"),
+                created_at: SystemTime::now(),
+                stream: request.metadata.stream,
+                session: Box::new(AtomicFailureSession {
+                    trace: Arc::clone(&self.trace),
+                    response_headers: self.response_headers.clone(),
+                }),
+            })
+        })
+    }
+}
+
+fn atomic_failure_batch() -> CoordinatedEvent {
+    let started = ProviderEvent::canonical_with_wire(
+        vec![GatewayEvent::Started(ResponseMeta::new(
+            "resp_ws_atomic",
+            "model-a",
+        ))],
+        ProtocolWireEvent::json(
+            "openai",
+            Some("response.created".to_owned()),
+            json!({
+                "type": "response.created",
+                "response": {
+                    "id": "resp_ws_atomic",
+                    "model": "model-a",
+                    "status": "in_progress"
+                }
+            }),
+        )
+        .expect("created wire"),
+    );
+    let failed = ProviderEvent::wire(
+        ProtocolWireEvent::json(
+            "openai",
+            Some("response.failed".to_owned()),
+            json!({
+                "type": "response.failed",
+                "response": {
+                    "id": "resp_ws_atomic",
+                    "status": "failed",
+                    "error": {
+                        "code": "rate_limit_exceeded",
+                        "message": "websocket atomic upstream marker"
+                    }
+                }
+            }),
+        )
+        .expect("failed wire"),
+    );
+    CoordinatedEvent::try_batch(
+        vec![started, failed],
+        CommitRequirement::CommitBeforeDelivery,
+    )
+    .expect("atomic WebSocket batch")
+}
+
+#[tokio::test]
+async fn websocket_atomic_upstream_failure_batch_should_be_forwarded_once() {
+    let trace = Arc::new(AtomicFailureTrace::default());
+    let execution = Arc::new(AtomicFailureExecution {
+        client: authenticated_client("sk_ws_atomic"),
+        trace: Arc::clone(&trace),
+        response_headers: Vec::new(),
+    });
+    let app = api_router(execution).await;
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind WebSocket test server");
+    let address = listener.local_addr().expect("test server address");
+    let server = tokio::spawn(async move {
+        axum::serve(listener, app)
+            .await
+            .expect("serve WebSocket test router");
+    });
+    let mut request = format!("ws://{address}/v1/responses")
+        .into_client_request()
+        .expect("WebSocket request");
+    request.headers_mut().insert(
+        AUTHORIZATION,
+        "Bearer sk_ws_atomic".parse().expect("authorization"),
+    );
+    let (mut socket, response) = connect_async(request).await.expect("upgrade WebSocket");
+    assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
+    socket
+        .send(ClientMessage::Text(
+            json!({
+                "type": "response.create",
+                "model": "model-a",
+                "input": "hello"
+            })
+            .to_string()
+            .into(),
+        ))
+        .await
+        .expect("send response.create");
+
+    let mut messages = Vec::<Value>::new();
+    loop {
+        let message = tokio::time::timeout(Duration::from_secs(2), socket.next())
+            .await
+            .expect("WebSocket response timeout")
+            .expect("WebSocket remains open")
+            .expect("valid WebSocket frame");
+        let ClientMessage::Text(text) = message else {
+            continue;
+        };
+        let value: Value = serde_json::from_str(&text).expect("JSON WebSocket event");
+        let failed = value.get("type").and_then(Value::as_str) == Some("response.failed");
+        messages.push(value);
+        if failed {
+            break;
+        }
+    }
+
+    assert_eq!(
+        messages
+            .iter()
+            .filter(|message| message.get("type").and_then(Value::as_str) == Some("response.failed"))
+            .count(),
+        1
+    );
+    let failed = messages
+        .iter()
+        .find(|message| message.get("type").and_then(Value::as_str) == Some("response.failed"))
+        .expect("upstream failed event");
+    assert_eq!(
+        failed
+            .pointer("/response/error/message")
+            .and_then(Value::as_str),
+        Some("websocket atomic upstream marker")
+    );
+    assert!(trace.committed.load(Ordering::Acquire));
+    assert_eq!(trace.next_calls.load(Ordering::Acquire), 2);
+    assert!(trace.finalized.load(Ordering::Acquire));
+
+    socket.close(None).await.expect("close WebSocket");
+    server.abort();
+}
+
+#[tokio::test]
+async fn websocket_response_metadata_should_preserve_ordinary_headers_without_blocking_events() {
+    let trace = Arc::new(AtomicFailureTrace::default());
+    let execution = Arc::new(AtomicFailureExecution {
+        client: authenticated_client("sk_ws_atomic"),
+        trace,
+        response_headers: vec![
+            ProviderResponseHeader::new("x-future-header", Bytes::from_static(b"future-value")),
+            ProviderResponseHeader::new("x-future-multi", Bytes::from_static(b"first")),
+            ProviderResponseHeader::new("x-future-multi", Bytes::from_static(b"second")),
+            ProviderResponseHeader::new("x-future-bytes", Bytes::from_static(b"\xffopaque")),
+            ProviderResponseHeader::new("bad\0name", Bytes::from_static(b"unrepresentable")),
+            ProviderResponseHeader::new(
+                "authorization",
+                Bytes::from_static(b"should-not-cross-boundary"),
+            ),
+            ProviderResponseHeader::new("connection", Bytes::from_static(b"x-private-hop")),
+            ProviderResponseHeader::new("x-private-hop", Bytes::from_static(b"private-hop")),
+            ProviderResponseHeader::new("content-type", Bytes::from_static(b"application/private")),
+            ProviderResponseHeader::new("x-request-id", Bytes::from_static(b"req_upstream")),
+        ],
+    });
+    let app = api_router(execution).await;
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind WebSocket test server");
+    let address = listener.local_addr().expect("test server address");
+    let server = tokio::spawn(async move {
+        axum::serve(listener, app)
+            .await
+            .expect("serve WebSocket test router");
+    });
+    let mut request = format!("ws://{address}/v1/responses")
+        .into_client_request()
+        .expect("WebSocket request");
+    request.headers_mut().insert(
+        AUTHORIZATION,
+        "Bearer sk_ws_atomic".parse().expect("authorization"),
+    );
+    let (mut socket, response) = connect_async(request).await.expect("upgrade WebSocket");
+    assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
+    socket
+        .send(ClientMessage::Text(
+            json!({
+                "type": "response.create",
+                "model": "model-a",
+                "input": "hello"
+            })
+            .to_string()
+            .into(),
+        ))
+        .await
+        .expect("send response.create");
+
+    let mut metadata = None;
+    let mut saw_failed = false;
+    while metadata.is_none() || !saw_failed {
+        let message = tokio::time::timeout(Duration::from_secs(2), socket.next())
+            .await
+            .expect("WebSocket response timeout")
+            .expect("WebSocket remains open")
+            .expect("valid WebSocket frame");
+        let ClientMessage::Text(text) = message else {
+            continue;
+        };
+        let value: Value = serde_json::from_str(&text).expect("JSON WebSocket event");
+        match value.get("type").and_then(Value::as_str) {
+            Some("response.metadata") => metadata = Some(value),
+            Some("response.failed") => saw_failed = true,
+            _ => {}
+        }
+    }
+
+    let headers = metadata
+        .as_ref()
+        .and_then(|value| value.get("headers"))
+        .and_then(Value::as_object)
+        .expect("response metadata headers");
+    assert_eq!(headers.get("x-future-header"), Some(&json!("future-value")));
+    // 官方 metadata 是 string map，同名多值只能保持既有的后值覆盖语义。
+    assert_eq!(headers.get("x-future-multi"), Some(&json!("second")));
+    assert_eq!(headers.get("x-request-id"), Some(&json!("req_upstream")));
+    for omitted in [
+        "x-future-bytes",
+        "bad\0name",
+        "authorization",
+        "connection",
+        "x-private-hop",
+        "content-type",
+    ] {
+        assert!(
+            !headers.contains_key(omitted),
+            "unexpected metadata header: {omitted:?}"
+        );
+    }
+    assert!(saw_failed);
+
+    socket.close(None).await.expect("close WebSocket");
+    server.abort();
+}
+
+#[tokio::test]
+async fn websocket_response_create_should_not_have_a_private_16_mib_frame_limit() {
+    let trace = Arc::new(AtomicFailureTrace::default());
+    let execution = Arc::new(AtomicFailureExecution {
+        client: authenticated_client("sk_ws_atomic"),
+        trace,
+        response_headers: Vec::new(),
+    });
+    let app = api_router(execution).await;
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind WebSocket test server");
+    let address = listener.local_addr().expect("test server address");
+    let server = tokio::spawn(async move {
+        axum::serve(listener, app)
+            .await
+            .expect("serve WebSocket test router");
+    });
+    let mut request = format!("ws://{address}/v1/responses")
+        .into_client_request()
+        .expect("WebSocket request");
+    request.headers_mut().insert(
+        AUTHORIZATION,
+        "Bearer sk_ws_atomic".parse().expect("authorization"),
+    );
+    let (mut socket, response) = connect_async(request).await.expect("upgrade WebSocket");
+    assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
+    let payload = json!({
+        "type": "response.create",
+        "model": "model-a",
+        "input": "x".repeat(16 * 1024 * 1024 + 1),
+    })
+    .to_string();
+    assert!(payload.len() > 16 * 1024 * 1024);
+
+    socket
+        .send(ClientMessage::Text(payload.into()))
+        .await
+        .expect("send response.create above the former frame limit");
+
+    let mut saw_upstream_event = false;
+    for _ in 0..3 {
+        let message = tokio::time::timeout(Duration::from_secs(10), socket.next())
+            .await
+            .expect("WebSocket response timeout")
+            .expect("WebSocket remains open")
+            .expect("valid WebSocket frame");
+        let ClientMessage::Text(text) = message else {
+            continue;
+        };
+        let value: Value = serde_json::from_str(&text).expect("JSON WebSocket event");
+        if matches!(
+            value.get("type").and_then(Value::as_str),
+            Some("response.created" | "response.failed")
+        ) {
+            saw_upstream_event = true;
+            break;
+        }
+    }
+    assert!(saw_upstream_event);
+
+    socket.close(None).await.expect("close WebSocket");
+    server.abort();
+}

 const TEST_WEBSOCKET_KEY: &str = "AAAAAAAAAAAAAAAAAAAAAA==";

@@ -1,57 +1,29 @@
 use axum::{
-    Router,
-    body::{Body, Bytes},
-    extract::DefaultBodyLimit,
+    body::Body,
    http::{Method, Request, StatusCode},
-    routing::post,
 };
-use gateway_api::openai::router::MAX_CLIENT_REQUEST_BODY_BYTES;
 use tower::ServiceExt;

 use super::api_router_with_origins;
 use super::models::ModelsExecution;

-fn body_limit_app() -> Router {
-    Router::new()
-        .route(
-            "/v1/responses",
-            post(|body: Bytes| async move {
-                if body.len() == MAX_CLIENT_REQUEST_BODY_BYTES {
-                    StatusCode::NO_CONTENT
-                } else {
-                    StatusCode::INTERNAL_SERVER_ERROR
-                }
-            }),
-        )
-        .layer(DefaultBodyLimit::max(MAX_CLIENT_REQUEST_BODY_BYTES))
-}
+const REMOVED_BODY_LIMIT_BYTES: usize = 16 * 1024 * 1024;

 #[tokio::test]
-async fn responses_body_limit_should_accept_exactly_sixteen_mibibytes() {
-    let response = body_limit_app()
+async fn responses_body_should_accept_payload_above_the_removed_private_limit() {
+    let router = api_router_with_origins(ModelsExecution::new(), Vec::new()).await;
+    let response = router
        .oneshot(
            Request::post("/v1/responses")
-                .body(Body::from(vec![b'a'; MAX_CLIENT_REQUEST_BODY_BYTES]))
-                .expect("build exact-limit request"),
+                .body(Body::from(vec![b'a'; REMOVED_BODY_LIMIT_BYTES + 1]))
+                .expect("build request above the removed limit"),
        )
        .await
-        .expect("route exact-limit request");
+        .expect("route request above the removed limit");

-    assert_eq!(response.status(), StatusCode::NO_CONTENT);
-}
-
-#[tokio::test]
-async fn responses_body_limit_should_reject_one_byte_over_sixteen_mibibytes() {
-    let response = body_limit_app()
-        .oneshot(
-            Request::post("/v1/responses")
-                .body(Body::from(vec![b'a'; MAX_CLIENT_REQUEST_BODY_BYTES + 1]))
-                .expect("build over-limit request"),
-        )
-        .await
-        .expect("route over-limit request");
-
-    assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
+    // The handler sees the body and rejects the missing credentials. A restored body limit
+    // would return 413 before authentication runs.
+    assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
 }

 #[tokio::test]
@@ -17,8 +17,9 @@ bytes = "1.11.1"
 futures = "0.3.32"
 futures-timer = "3.0.3"
 serde = { version = "1.0.228", features = ["derive"] }
-serde_json = { version = "1.0.150", features = ["preserve_order"] }
+serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 thiserror = "2.0.18"
+tracing = "0.1.44"
 uuid = { version = "1.23.3", features = ["v7"] }

 [lints]
@@ -39,6 +39,30 @@ impl Decimal {
            .filter(|value| *value <= MAX_SCALED_DECIMAL)
            .map(Self)
    }
+
+    /// 除以非零整数，保留最多十位小数。
+    #[must_use]
+    pub fn checked_div_u64(self, divisor: u64) -> Option<Self> {
+        let divisor = u128::from(divisor);
+        (divisor != 0)
+            .then(|| self.0.checked_div(divisor))
+            .flatten()
+            .and_then(|value| Self::from_scaled(value).ok())
+    }
+
+    /// 去尾零的 canonical 字符串，用于 wire 序列化。
+    #[must_use]
+    pub fn canonical(self) -> String {
+        let integer = self.0 / DECIMAL_SCALE;
+        let fraction = self.0 % DECIMAL_SCALE;
+        if fraction == 0 {
+            integer.to_string()
+        } else {
+            let fraction = format!("{fraction:010}");
+            let trimmed = fraction.trim_end_matches('0');
+            format!("{integer}.{trimmed}")
+        }
+    }
 }

 impl FromStr for Decimal {
@@ -8,24 +8,22 @@ use std::fmt;
 use futures::future::BoxFuture;

 use crate::engine::credential::ProviderAccountId;
-use crate::error::{IdentifierError, SafeUpstreamValue, validate_text};
 use crate::operation::ProviderSessionState;
+use crate::policy::ClientApiKeyId;
 use crate::routing::ProviderKind;

-/// 客户端传入的 previous response ID。
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+/// 客户端或 Provider 传递的 opaque response handle。
+///
+/// Codex 定义这个值的语义和格式。网关只将其作为亲和查找键或同账号上游
+/// continuation 的载体，不得按私有长度、字符集或前缀规则拒绝、归一化或改写。
+#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct PreviousResponseId(String);

 impl PreviousResponseId {
-    /// 校验并创建 previous response ID。
-    ///
-    /// # Errors
-    ///
-    /// ID 为空、过长或包含控制字符时返回错误。
-    pub fn new(value: impl Into<String>) -> Result<Self, IdentifierError> {
-        let value = value.into();
-        validate_text(&value, 256, false, None)?;
-        Ok(Self(value))
+    /// 按原样创建 opaque response handle。
+    #[must_use]
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
    }

    #[must_use]
@@ -34,6 +32,12 @@ impl PreviousResponseId {
    }
 }

+impl fmt::Debug for PreviousResponseId {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("PreviousResponseId(<redacted>)")
+    }
+}
+
 /// Provider 原生 response handle 的续接范围。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum NativeContinuationScope {
@@ -45,14 +49,15 @@ pub enum NativeContinuationScope {

 /// 从可丢失会话亲和存储恢复的 native previous-response pin。
 ///
-/// 该值不依赖调用方 API Key；它只阻止 native handle 与不透明 Provider state
-/// 被发送到错误的 Provider 或账号。
+/// 该值同时绑定调用方 API Key、Provider 与账号，阻止 native handle 和不透明
+/// Provider state 被跨租户或跨上游目标复用。
 #[derive(Clone, PartialEq)]
 pub struct NativeContinuationPin {
    /// 客户端提交、用于查找可丢失会话亲和记录的 response ID。
    previous_response_id: PreviousResponseId,
    /// Provider 原生 response handle。
-    upstream_response_id: SafeUpstreamValue,
+    upstream_response_id: PreviousResponseId,
+    client_api_key_id: ClientApiKeyId,
    provider: ProviderKind,
    account: ProviderAccountId,
    scope: NativeContinuationScope,
@@ -63,13 +68,15 @@ impl NativeContinuationPin {
    #[must_use]
    pub const fn new(
        previous_response_id: PreviousResponseId,
-        upstream_response_id: SafeUpstreamValue,
+        upstream_response_id: PreviousResponseId,
+        client_api_key_id: ClientApiKeyId,
        provider: ProviderKind,
        account: ProviderAccountId,
    ) -> Self {
        Self {
            previous_response_id,
            upstream_response_id,
+            client_api_key_id,
            provider,
            account,
            scope: NativeContinuationScope::ConnectionLocal,
@@ -98,10 +105,20 @@ impl NativeContinuationPin {

    /// 返回只允许发送给已冻结 Provider 目标的原生上游 handle。
    #[must_use]
-    pub const fn upstream_response_id(&self) -> &SafeUpstreamValue {
+    pub const fn upstream_response_id(&self) -> &PreviousResponseId {
        &self.upstream_response_id
    }

+    #[must_use]
+    pub const fn client_api_key_id(&self) -> &ClientApiKeyId {
+        &self.client_api_key_id
+    }
+
+    #[must_use]
+    pub fn matches_client(&self, client_api_key_id: &ClientApiKeyId) -> bool {
+        self.client_api_key_id == *client_api_key_id
+    }
+
    #[must_use]
    pub const fn provider(&self) -> &ProviderKind {
        &self.provider
@@ -136,6 +153,7 @@ impl fmt::Debug for NativeContinuationPin {
            .debug_struct("NativeContinuationPin")
            .field("previous_response_id", &"<redacted>")
            .field("upstream_response_id", &"<redacted>")
+            .field("client_api_key_id", &self.client_api_key_id)
            .field("provider", &self.provider)
            .field("account", &self.account)
            .field("scope", &self.scope)
@@ -187,17 +205,71 @@ impl fmt::Debug for ContinuationBinding {
    }
 }

-#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
-#[error("native continuation store is unavailable")]
-pub struct NativeContinuationStoreError;
+/// Native continuation lookup 的稳定失败分类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum NativeContinuationStoreErrorKind {
+    /// Redis 等可丢失协调存储暂不可用；调用方可以按外部 continuation fail-open。
+    Unavailable,
+    /// 存储中的记录无法还原为可信 pin；不得将原始 handle 继续透传上游。
+    InvalidData,
+    /// 已存在的记录属于另一个客户端 API Key；必须 fail closed。
+    OwnershipMismatch,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("native continuation store failed: {kind:?}: {detail}")]
+pub struct NativeContinuationStoreError {
+    kind: NativeContinuationStoreErrorKind,
+    detail: String,
+}
+
+impl NativeContinuationStoreError {
+    /// 构造可 fail-open 的协调存储不可用错误；`detail` 不应包含 response handle。
+    #[must_use]
+    pub fn unavailable(detail: impl Into<String>) -> Self {
+        Self {
+            kind: NativeContinuationStoreErrorKind::Unavailable,
+            detail: detail.into(),
+        }
+    }
+
+    /// 构造必须 fail closed 的无效记录错误；`detail` 不应包含 response handle。
+    #[must_use]
+    pub fn invalid_data(detail: impl Into<String>) -> Self {
+        Self {
+            kind: NativeContinuationStoreErrorKind::InvalidData,
+            detail: detail.into(),
+        }
+    }
+
+    /// 构造不泄露记录归属细节的跨调用方错误。
+    #[must_use]
+    pub fn ownership_mismatch() -> Self {
+        Self {
+            kind: NativeContinuationStoreErrorKind::OwnershipMismatch,
+            detail: "continuation belongs to a different client API key".to_owned(),
+        }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> NativeContinuationStoreErrorKind {
+        self.kind
+    }
+
+    #[must_use]
+    pub fn detail(&self) -> &str {
+        &self.detail
+    }
+}

 /// 可丢失的 previous-response 亲和存储端口。
 ///
-/// 亲和记录不按调用方 API Key 隔离：与旧版一样，response ID 是会话级 opaque
-/// handle；Redis 不可用或超时必须由调用方 fail-open。
+/// 亲和记录按调用方 API Key 隔离；Redis 不可用或超时必须由调用方 fail-open，
+/// 但命中其他 Key 的记录必须 fail closed。
 pub trait NativeContinuationPort: Send + Sync {
    fn resolve<'a>(
        &'a self,
+        client_api_key_id: &'a ClientApiKeyId,
        previous_response_id: &'a PreviousResponseId,
    ) -> BoxFuture<'a, Result<Option<NativeContinuationPin>, NativeContinuationStoreError>>;

@@ -3,6 +3,7 @@
 use std::collections::BTreeSet;
 use std::fmt;
 use std::net::IpAddr;
+use std::num::NonZeroU32;
 use std::sync::Arc;
 use std::time::{Duration, SystemTime};

@@ -14,10 +15,14 @@ use crate::engine::admission::{
    ClientAdmissionDecision, ClientAdmissionPort, ClientAdmissionRejection, ClientAdmissionRequest,
 };
 use crate::engine::continuation::{
-    ContinuationBinding, NativeContinuationPin, NativeContinuationPort, PreviousResponseId,
+    ContinuationBinding, NativeContinuationPin, NativeContinuationPort,
+    NativeContinuationStoreErrorKind, PreviousResponseId,
 };
 use crate::engine::coordinator::ResponseExecutionSession;
-use crate::engine::probe::{AccountProbe, AccountProbeRequest, AccountProbeResult};
+use crate::engine::probe::{
+    AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult,
+    AccountProbeUpstreamResponse,
+};
 use crate::engine::provider::ProviderRegistry;
 use crate::engine::{
    AttemptCoordinator, AttemptRecord, CancellationToken, CoordinatedEvent, EngineError,
@@ -36,7 +41,7 @@ use crate::routing::{
 };

 const MODEL_REQUEST_DEADLINE: Duration = Duration::from_secs(10 * 60);
-const CONTINUATION_AFFINITY_TIMEOUT: Duration = Duration::from_millis(100);
+const COORDINATION_TIMEOUT: Duration = Duration::from_millis(100);

 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClientTransport {
@@ -170,6 +175,22 @@ pub enum ProviderCircuitDecision {
 #[error("provider circuit store is unavailable")]
 pub struct ProviderCircuitError;

+/// Provider circuit 的可重建协调策略；由 Core 拥有并交给 Store adapter 执行。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ProviderCircuitPolicy {
+    pub failure_threshold: NonZeroU32,
+    pub open_duration: Duration,
+}
+
+impl Default for ProviderCircuitPolicy {
+    fn default() -> Self {
+        Self {
+            failure_threshold: NonZeroU32::new(3).unwrap_or(NonZeroU32::MIN),
+            open_duration: Duration::from_secs(30),
+        }
+    }
+}
+
 pub trait ProviderCircuitPort: Send + Sync {
    fn decision<'a>(
        &'a self,
@@ -233,15 +254,6 @@ impl DefaultExecutionService {
        request.client.policy.authorize().map_err(|_| {
            GatewayError::new(GatewayErrorKind::PolicyDenied, "client API key is disabled")
        })?;
-        if !request.client.snapshot.contains_public_model_for_provider(
-            &request.public_model,
-            request.client.policy.provider_kind(),
-        ) {
-            return Err(GatewayError::new(
-                GatewayErrorKind::ModelNotFound,
-                "requested model was not found",
-            ));
-        }
        let started_at = SystemTime::now();
        let deadline_at = started_at
            .checked_add(MODEL_REQUEST_DEADLINE)
@@ -250,23 +262,86 @@ impl DefaultExecutionService {
            })?;
        let request_id = new_request_id()?;
        let routing_context = self
-            .route_context(request.client.policy.provider_kind())
+            .route_context(request.client.policy.account_scope().provider_kinds())
            .await?;
        let plan = request
            .client
            .snapshot
-            .plan(&request.public_model, &request.operation, &routing_context)
+            .plan(
+                &request.public_model,
+                &request.operation,
+                Arc::clone(request.client.policy.account_scope()),
+                &routing_context,
+            )
            .map_err(map_routing_error)?;
        let continuation = match request.metadata.previous_response_id.as_ref() {
            Some(previous) => {
-                let resolve = self.continuation.resolve(previous).fuse();
-                let timeout = Delay::new(CONTINUATION_AFFINITY_TIMEOUT).fuse();
+                let resolve = self
+                    .continuation
+                    .resolve(request.client.policy.key_id(), previous)
+                    .fuse();
+                let timeout = Delay::new(COORDINATION_TIMEOUT).fuse();
                pin_mut!(resolve, timeout);
                let pin = select_biased! {
-                    result = resolve => result.ok().flatten(),
+                    result = resolve => match result {
+                        Ok(pin) => pin,
+                        Err(error)
+                            if error.kind() == NativeContinuationStoreErrorKind::Unavailable =>
+                        {
+                            tracing::debug!(
+                                request_id = request_id.as_str(),
+                                %error,
+                                "Continuation affinity 查询失败，退化为外部续接"
+                            );
+                            None
+                        }
+                        Err(error)
+                            if error.kind()
+                                == NativeContinuationStoreErrorKind::OwnershipMismatch =>
+                        {
+                            return Err(GatewayError::new(
+                                GatewayErrorKind::PolicyDenied,
+                                "continuation does not belong to this client API key",
+                            ));
+                        }
+                        Err(error) => {
+                            tracing::warn!(
+                                request_id = request_id.as_str(),
+                                %error,
+                                "Continuation affinity 记录无效，已拒绝续接"
+                            );
+                            return Err(GatewayError::new(
+                                GatewayErrorKind::Internal,
+                                "continuation state is invalid",
+                            ));
+                        }
+                    },
                    _ = timeout => None,
                };
                match pin {
+                    Some(pin) if !pin.matches_client(request.client.policy.key_id()) => {
+                        return Err(GatewayError::new(
+                            GatewayErrorKind::PolicyDenied,
+                            "continuation does not belong to this client API key",
+                        ));
+                    }
+                    Some(pin) if !request.client.policy.account_scope().allows(pin.account()) => {
+                        return Err(GatewayError::new(
+                            GatewayErrorKind::PolicyDenied,
+                            "continuation account is outside the client account scope",
+                        ));
+                    }
+                    Some(pin)
+                        if !plan
+                            .candidates()
+                            .iter()
+                            .any(|candidate| candidate.provider() == pin.provider()) =>
+                    {
+                        return Err(GatewayError::new(
+                            GatewayErrorKind::NoAvailableProvider,
+                            "continuation provider is not available",
+                        ));
+                    }
                    Some(pin) => {
                        attach_continuation_session_state(&mut request.operation, &pin);
                        ContinuationBinding::Pinned(pin)
@@ -339,14 +414,19 @@ impl DefaultExecutionService {
            client_api_key_id: request.client.policy.key_id().clone(),
            model_request_id: request_id.clone(),
        };
-        let observation = self
-            .providers
-            .request_observation(request.client.policy.provider_kind(), &request.operation);
+        let observation = plan
+            .candidates()
+            .first()
+            .map_or_else(Default::default, |candidate| {
+                self.providers
+                    .request_observation(candidate.provider(), &request.operation)
+            });
        let new_request = NewModelRequest {
            id: request_id.clone(),
            client_api_key_id: Some(request.client.policy.key_id().clone()),
            client_api_key_ref: request.client.policy.key_id().clone(),
            config_revision: plan.config_revision(),
+            routing: request.client.policy.account_scope().routing_snapshot(),
            protocol: request.metadata.protocol,
            operation: request.operation.kind(),
            endpoint: request.metadata.endpoint,
@@ -396,19 +476,42 @@ impl DefaultExecutionService {

    async fn route_context(
        &self,
-        provider_kind: &ProviderKind,
+        provider_kinds: &BTreeSet<ProviderKind>,
    ) -> Result<RoutingContext, GatewayError> {
-        let blocked_providers = match self.circuits.decision(provider_kind).await.map_err(|_| {
-            GatewayError::new(
-                GatewayErrorKind::NoAvailableProvider,
-                "provider health state is temporarily unavailable",
-            )
-        })? {
-            ProviderCircuitDecision::Allow => BTreeSet::new(),
-            ProviderCircuitDecision::BlockedUntil(_) => BTreeSet::from([provider_kind.clone()]),
-        };
+        let decisions = futures::future::join_all(provider_kinds.iter().map(|provider_kind| {
+            let circuits = Arc::clone(&self.circuits);
+            async move {
+                let decision = circuits.decision(provider_kind).fuse();
+                let timeout = Delay::new(COORDINATION_TIMEOUT).fuse();
+                pin_mut!(decision, timeout);
+                let decision = select_biased! {
+                    result = decision => Some(result),
+                    _ = timeout => None,
+                };
+                (provider_kind, decision)
+            }
+        }))
+        .await;
+        let mut blocked_providers = BTreeSet::new();
+        for (provider_kind, decision) in decisions {
+            match decision {
+                Some(Ok(ProviderCircuitDecision::BlockedUntil(_))) => {
+                    blocked_providers.insert(provider_kind.clone());
+                }
+                Some(Err(error)) => tracing::warn!(
+                    provider = provider_kind.as_str(),
+                    %error,
+                    "Provider circuit 读取失败，按可重建协调状态 fail-open"
+                ),
+                None => tracing::warn!(
+                    provider = provider_kind.as_str(),
+                    "Provider circuit 读取超时，按可重建协调状态 fail-open"
+                ),
+                Some(Ok(ProviderCircuitDecision::Allow)) => {}
+            }
+        }
        Ok(RoutingContext {
-            provider_kind: Some(provider_kind.clone()),
+            required_provider: None,
            blocked_providers,
        })
    }
@@ -416,7 +519,7 @@ impl DefaultExecutionService {
    async fn probe_inner(
        &self,
        request: AccountProbeRequest,
-    ) -> Result<AccountProbeResult, GatewayError> {
+    ) -> Result<AccountProbeResult, AccountProbeError> {
        let AccountProbeRequest {
            account_id,
            provider_kind,
@@ -439,11 +542,16 @@ impl DefaultExecutionService {
                GatewayError::new(GatewayErrorKind::Unsupported, "requested model is invalid")
            })?;
        let routing_context = RoutingContext {
-            provider_kind: Some(provider_kind),
+            required_provider: Some(provider_kind),
            ..RoutingContext::default()
        };
        let plan = snapshot
-            .plan(&public_model, &operation, &routing_context)
+            .plan(
+                &public_model,
+                &operation,
+                snapshot.all_account_scope(),
+                &routing_context,
+            )
            .map_err(map_routing_error)?;
        let started_at = SystemTime::now();
        let deadline_at = started_at
@@ -459,6 +567,7 @@ impl DefaultExecutionService {
            client_api_key_id: None,
            client_api_key_ref: actor,
            config_revision: plan.config_revision(),
+            routing: crate::routing::AccountRoutingSnapshot::all(),
            protocol: "admin_connection_test".to_owned(),
            operation: operation.kind(),
            endpoint: "/api/admin/accounts/connection-test".to_owned(),
@@ -525,26 +634,55 @@ impl DefaultExecutionService {
        })
    }

-    /// 探测失败先落库再转成客户端错误；转换会丢掉上游状态码与 provider code。
+    /// 探测失败先记录脱敏分类事实，再把请求局部的原始上游响应交给认证管理端。
    async fn observe_probe_failure(
        &self,
        observed: &ProbeObservation,
        started_at: SystemTime,
        error: &EngineError,
-    ) -> GatewayError {
+    ) -> AccountProbeError {
+        let upstream_response = match error {
+            EngineError::Provider(provider_error) => provider_error
+                .client_visible_upstream_response()
+                .map(AccountProbeUpstreamResponse::from_client_response),
+            _ => None,
+        };
        if let EngineError::Provider(provider_error) = error {
-            let _ = self
+            let latency = started_at.elapsed().unwrap_or_default();
+            let latency_ms = u64::try_from(latency.as_millis()).unwrap_or(u64::MAX);
+            tracing::warn!(
+                target: "gateway_probe",
+                provider_kind = observed.provider_kind.as_str(),
+                account_id = observed.account_id.as_str(),
+                upstream_model = observed.upstream_model.as_str(),
+                failure_kind = provider_error.kind().as_str(),
+                send_state = ?provider_error.send_state(),
+                upstream_status = ?provider_error.upstream_status(),
+                provider_error_code = ?provider_error.upstream_code().map(|code| code.as_str()),
+                latency_ms,
+                "账号连接测试失败"
+            );
+            if let Err(store_error) = self
                .observations
                .record_probe_failure(ProbeFailure {
                    provider_kind: observed.provider_kind.clone(),
                    account_id: observed.account_id.clone(),
                    upstream_model_id: observed.upstream_model.clone(),
                    error: provider_error.clone(),
-                    latency: started_at.elapsed().unwrap_or_default(),
+                    latency,
                })
-                .await;
+                .await
+            {
+                tracing::warn!(
+                    operation = "record_probe_failure",
+                    provider_kind = observed.provider_kind.as_str(),
+                    account_id = observed.account_id.as_str(),
+                    error_kind = ?store_error.kind(),
+                    "账号连接测试观测写入失败，测试结果不受影响"
+                );
+            }
        }
-        gateway_error_from_engine(error)
+        AccountProbeError::new(gateway_error_from_engine(error), upstream_response)
    }
 }

@@ -624,19 +762,19 @@ impl ExecutionService for DefaultExecutionService {
    fn public_models(&self, client: &AuthenticatedClient) -> Vec<PublicModelId> {
        client
            .snapshot
-            .public_models_for_provider(client.policy.provider_kind())
+            .public_models_for_scope(client.policy.account_scope())
    }

    fn public_model_profiles(&self, client: &AuthenticatedClient) -> Vec<PublicModelProfile> {
        client
            .snapshot
-            .public_model_profiles_for_provider(client.policy.provider_kind())
+            .public_model_profiles_for_scope(client.policy.account_scope())
    }

    fn contains_public_model(&self, client: &AuthenticatedClient, model: &PublicModelId) -> bool {
        client
            .snapshot
-            .contains_public_model_for_provider(model, client.policy.provider_kind())
+            .contains_public_model_for_scope(model, client.policy.account_scope())
    }

    fn start(
@@ -651,7 +789,7 @@ impl AccountProbe for DefaultExecutionService {
    fn probe(
        &self,
        request: AccountProbeRequest,
-    ) -> BoxFuture<'_, Result<AccountProbeResult, GatewayError>> {
+    ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
        Box::pin(async move { self.probe_inner(request).await })
    }
 }
@@ -664,10 +802,13 @@ struct AdmissionLease {

 impl AdmissionLease {
    async fn release(self) {
-        let _ = self
+        if let Err(error) = self
            .port
            .release(&self.client_api_key_id, &self.model_request_id)
-            .await;
+            .await
+        {
+            tracing::warn!(%error, "Client admission 释放失败，依赖租约 TTL 收敛");
+        }
    }
 }

@@ -742,13 +883,7 @@ impl DefaultExecutionSession {
            return;
        };
        self.continuation_recorded = true;
-        let record = self.continuation.record(pin).fuse();
-        let timeout = Delay::new(CONTINUATION_AFFINITY_TIMEOUT).fuse();
-        pin_mut!(record, timeout);
-        select_biased! {
-            _ = record => {},
-            _ = timeout => {},
-        }
+        record_native_continuation(self.continuation.as_ref(), pin).await;
    }

    async fn finalize_detached(&mut self) {
@@ -756,8 +891,10 @@ impl DefaultExecutionSession {
            return;
        };
        core.cancel();
-        if !core.is_finalized() {
-            let _ = core.cancel_and_finalize().await;
+        if !core.is_finalized()
+            && let Err(error) = core.cancel_and_finalize().await
+        {
+            tracing::warn!(%error, "Detached execution 终态收敛失败");
        }
        let pending = core
            .provider_attempt_outcomes()
@@ -878,7 +1015,43 @@ async fn publish_provider_attempt_outcomes(
            }
            Some(_) => continue,
        };
-        let _ = result;
+        if let Err(error) = result {
+            tracing::warn!(
+                provider = outcome.provider_kind().as_str(),
+                %error,
+                "Provider circuit feedback 写入失败，数据面不受影响"
+            );
+        }
+    }
+}
+
+async fn record_native_continuation(
+    continuation: &dyn NativeContinuationPort,
+    pin: NativeContinuationPin,
+) {
+    let provider = pin.provider().as_str().to_owned();
+    let account = pin.account().as_str().to_owned();
+    let record = continuation.record(pin).fuse();
+    let timeout = Delay::new(COORDINATION_TIMEOUT).fuse();
+    pin_mut!(record, timeout);
+    select_biased! {
+        result = record => {
+            if let Err(error) = result {
+                tracing::warn!(
+                    provider = %provider,
+                    account = %account,
+                    %error,
+                    "Continuation affinity 写入失败，后续请求将退化为外部续接"
+                );
+            }
+        },
+        _ = timeout => {
+            tracing::warn!(
+                provider = %provider,
+                account = %account,
+                "Continuation affinity 后台写入超时，已丢弃本次亲和记录"
+            );
+        },
    }
 }

@@ -902,7 +1075,8 @@ fn new_request_id() -> Result<ModelRequestId, GatewayError> {

 fn map_routing_error(error: crate::error::RoutingError) -> GatewayError {
    match error {
-        crate::error::RoutingError::NoCapableProvider { .. } => GatewayError::new(
+        crate::error::RoutingError::NoCapableProvider { .. }
+        | crate::error::RoutingError::EmptyAccountScope => GatewayError::new(
            GatewayErrorKind::NoAvailableProvider,
            "no provider can execute this request",
        ),
@@ -233,6 +233,7 @@ pub struct AccountAttemptContext {
    state_owner: Option<ProviderAccountStateOwner>,
    credential_recovery_attempted: bool,
    diagnostic_required_account: bool,
+    account_scope: Option<Arc<crate::routing::FrozenAccountScope>>,
 }

 impl AccountAttemptContext {
@@ -248,6 +249,7 @@ impl AccountAttemptContext {
            state_owner,
            credential_recovery_attempted: false,
            diagnostic_required_account: false,
+            account_scope: None,
        }
    }

@@ -266,9 +268,17 @@ impl AccountAttemptContext {
            state_owner,
            credential_recovery_attempted: false,
            diagnostic_required_account: true,
+            account_scope: None,
        }
    }

+    /// 附着普通请求认证时冻结的账号范围。
+    #[must_use]
+    pub fn with_account_scope(mut self, scope: Arc<crate::routing::FrozenAccountScope>) -> Self {
+        self.account_scope = Some(scope);
+        self
+    }
+
    /// 标记本请求已对即将选择的固定账号执行过一次凭据恢复。
    #[must_use]
    pub const fn with_credential_recovery_attempted(mut self, attempted: bool) -> Self {
@@ -301,6 +311,11 @@ impl AccountAttemptContext {
    pub const fn is_diagnostic_required_account(&self) -> bool {
        self.diagnostic_required_account
    }
+
+    #[must_use]
+    pub const fn account_scope(&self) -> Option<&Arc<crate::routing::FrozenAccountScope>> {
+        self.account_scope.as_ref()
+    }
 }

 /// 请求中 Provider 账号绑定状态的唯一归属。
@@ -506,6 +521,12 @@ impl AttemptContext {
        self.account.is_diagnostic_required_account()
    }

+    /// 普通请求认证时冻结的账号范围；管理端诊断为 `None`。
+    #[must_use]
+    pub const fn account_scope(&self) -> Option<&Arc<crate::routing::FrozenAccountScope>> {
+        self.account.account_scope()
+    }
+
    #[must_use]
    pub const fn continuation(&self) -> Option<&ContinuationBinding> {
        self.continuation.as_ref()
@@ -529,6 +550,7 @@ pub struct NewModelRequest {
    pub client_api_key_id: Option<ClientApiKeyId>,
    pub client_api_key_ref: ClientApiKeyId,
    pub config_revision: ConfigRevision,
+    pub routing: crate::routing::AccountRoutingSnapshot,
    pub protocol: String,
    pub operation: OperationKind,
    pub endpoint: String,
@@ -615,6 +637,7 @@ pub struct ModelRequestFinalization {
    pub upstream_transport: Option<String>,
    pub http_version: Option<String>,
    pub websocket_pool: Option<String>,
+    pub service_tier: Option<String>,
    /// Provider 已筛选的专有观测 JSON；Core 不解释字段。
    pub provider_metadata_json: Option<String>,
    pub error: Option<GatewayError>,
@@ -748,6 +771,8 @@ pub enum EngineError {
    ContinuationPinMismatch,
    #[error("provider did not use the account required by this execution")]
    RequiredAccountMismatch,
+    #[error("provider selected an account outside the frozen client scope")]
+    AccountOutsideClientScope,
    #[error("provider execution failed")]
    Provider(ProviderError),
    #[error("request was cancelled")]
@@ -1,8 +1,11 @@
 //! 管理端账号连通性测试的真实执行链端口。

+use std::fmt;
+
+use bytes::Bytes;
 use futures::future::BoxFuture;

-use crate::error::GatewayError;
+use crate::error::{ClientVisibleUpstreamResponse, GatewayError, GatewayErrorKind};
 use crate::routing::{ProviderKind, UpstreamModelId};
 use crate::{engine::credential::ProviderAccountId, operation::Operation};

@@ -19,9 +22,111 @@ pub struct AccountProbeResult {
    pub text: Vec<String>,
 }

+/// 仅供当前管理端连接测试展示的原始上游失败响应。
+///
+/// 正文不进入 `Debug`、日志或持久化；Core 只在探测终态从原始 Provider 错误显式复制。
+#[derive(PartialEq, Eq)]
+pub struct AccountProbeUpstreamResponse {
+    status: u16,
+    content_type: Option<Vec<u8>>,
+    body: Bytes,
+}
+
+impl AccountProbeUpstreamResponse {
+    pub(crate) fn from_client_response(response: &ClientVisibleUpstreamResponse) -> Self {
+        Self {
+            status: response.status(),
+            content_type: response.content_type().map(<[u8]>::to_vec),
+            body: response.body().clone(),
+        }
+    }
+
+    #[must_use]
+    pub const fn status(&self) -> u16 {
+        self.status
+    }
+
+    #[must_use]
+    pub fn content_type(&self) -> Option<&[u8]> {
+        self.content_type.as_deref()
+    }
+
+    #[must_use]
+    pub const fn body(&self) -> &Bytes {
+        &self.body
+    }
+}
+
+impl fmt::Debug for AccountProbeUpstreamResponse {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("AccountProbeUpstreamResponse")
+            .field("status", &self.status)
+            .field(
+                "content_type",
+                &self.content_type.as_ref().map(|_| "<present>"),
+            )
+            .field("body", &"<redacted>")
+            .finish()
+    }
+}
+
+/// 管理端连接测试的终态错误。
+///
+/// `gateway` 保留稳定分类，`upstream_response` 只面向本次认证管理请求展示源响应。
+#[derive(Debug)]
+pub struct AccountProbeError {
+    gateway: GatewayError,
+    upstream_response: Option<AccountProbeUpstreamResponse>,
+}
+
+impl AccountProbeError {
+    #[must_use]
+    pub const fn new(
+        gateway: GatewayError,
+        upstream_response: Option<AccountProbeUpstreamResponse>,
+    ) -> Self {
+        Self {
+            gateway,
+            upstream_response,
+        }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> GatewayErrorKind {
+        self.gateway.kind()
+    }
+
+    #[must_use]
+    pub fn client_message(&self) -> &str {
+        self.gateway.client_message()
+    }
+
+    #[must_use]
+    pub fn client_error_type(&self) -> Option<&str> {
+        self.gateway.client_error_type()
+    }
+
+    #[must_use]
+    pub fn client_error_code(&self) -> Option<&str> {
+        self.gateway.client_error_code()
+    }
+
+    #[must_use]
+    pub const fn upstream_response(&self) -> Option<&AccountProbeUpstreamResponse> {
+        self.upstream_response.as_ref()
+    }
+}
+
+impl From<GatewayError> for AccountProbeError {
+    fn from(gateway: GatewayError) -> Self {
+        Self::new(gateway, None)
+    }
+}
+
 pub trait AccountProbe: Send + Sync {
    fn probe(
        &self,
        request: AccountProbeRequest,
-    ) -> BoxFuture<'_, Result<AccountProbeResult, GatewayError>>;
+    ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>>;
 }
--- a/Show More
+++ b/Show More