Update to v3.0.11 with HF deployment fixes

- Full upstream v3.0.11 source (frontend/backend/docker now included, fixes BUILD_ERROR)
- Bake config.yaml into image (/run/grok2api/config.yaml) so entrypoint passes
- app_port: 8000 in README so HF routes to the app's listen port
- Data paths moved to /data (HF persistent storage)
- entrypoint ensures /data writable by app user
- Clean out obsolete Python-version files

.dockerignore

@@ -0,0 +1,32 @@
+**
+
+!VERSION
+
+!config.yaml
+
+!backend/
+!backend/go.mod
+!backend/go.sum
+!backend/cmd/
+!backend/cmd/**
+!backend/internal/
+!backend/internal/**
+backend/**/*_test.go
+!backend/docs/
+!backend/docs/docs.go
+
+!frontend/
+!frontend/package.json
+!frontend/pnpm-lock.yaml
+!frontend/index.html
+!frontend/vite.config.ts
+!frontend/tsconfig.json
+!frontend/tsconfig.app.json
+!frontend/tsconfig.node.json
+!frontend/public/
+!frontend/public/**
+!frontend/src/
+!frontend/src/**
+
+!docker/
+!docker/entrypoint.sh

.gitattributes

@@ -0,0 +1,3 @@
+frontend/public/**/*.png filter=lfs diff=lfs merge=lfs -text
+frontend/public/**/*.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/**/*.ico filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,118 @@
+name: Bug 报告
+description: 报告可稳定复现的功能、兼容性或部署问题。
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        感谢反馈问题。请尽量提供最小复现步骤和经过脱敏的日志、请求或响应。
+
+        请勿提交 Access Token、Refresh Token、Cookie、API Key、账号密码或其他敏感信息。安全漏洞请不要通过公开 Issue 披露。
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: 问题模块
+      description: 请选择问题主要出现在哪个模块。
+      options:
+        - OpenAI API 兼容层（Responses / Chat Completions）
+        - 模型同步、映射、路由与定价
+        - 账号、Provider、OAuth 与凭据
+        - 额度、计费与请求审计
+        - 图片、视频与媒体处理
+        - 管理端前端界面
+        - SQLite / PostgreSQL 数据库
+        - Docker、配置、部署与网络出口
+        - 其他
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: 相关 Provider
+      description: 请选择受影响的上游渠道。
+      options:
+        - Grok Build
+        - Grok Web
+        - Grok Console
+        - 多个 Provider
+        - 与 Provider 无关
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: 版本信息
+      description: 请提供版本号、Docker 镜像标签或 Commit SHA。
+      placeholder: "v0.2.99、ghcr.io/chenyme/grok2api:latest、main@abcdef1"
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: 部署与运行环境
+      description: 请填写与问题相关的部署方式、系统、架构、数据库和网络环境。
+      placeholder: |
+        部署方式：Docker Compose / Docker Run / 源码运行
+        操作系统：Debian 13 / Ubuntu 24.04 / macOS ...
+        CPU 架构：amd64 / arm64
+        数据库：SQLite / PostgreSQL
+        反向代理：Nginx / Nginx Proxy Manager / 无
+        出口网络：直连 / HTTP Proxy / SOCKS5 / WARP
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: 复现步骤
+      description: 请提供能够稳定复现问题的最小操作步骤。
+      placeholder: |
+        1. 使用配置……启动服务
+        2. 导入或选择……账号
+        3. 请求……接口
+        4. 出现……错误
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: 预期行为
+      description: 正常情况下应该发生什么？
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: 实际行为
+      description: 实际发生了什么？请包含完整错误信息。
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: 请求、响应、日志与截图
+      description: 请提供脱敏后的最小请求、状态码、响应体、容器日志、请求 ID 或截图。长日志请仅保留问题前后的关键部分。
+      placeholder: 可粘贴内容或直接拖放截图、日志文件；提交前请再次确认内容已经脱敏。
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: 提交前检查
+      options:
+        - label: 我已经搜索现有 Issue 和 Pull Request，确认没有相同问题。
+          required: true
+        - label: 我已经删除 Token、Cookie、API Key、账号凭据和个人信息。
+          required: true
+        - label: 这不是需要私下披露的安全漏洞。
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,95 @@
+name: 文档改进
+description: 报告缺失、错误、过时或难以理解的文档内容。
+title: "[Docs]: "
+labels:
+  - documentation
+body:
+  - type: markdown
+    attributes:
+      value: |
+        请指出具体文档位置，并说明当前内容的问题和建议修改方向。
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: 文档范围
+      options:
+        - README
+        - 配置文件与 config.example.yaml
+        - Docker 与部署说明
+        - Grok Build / Web / Console 账号接入
+        - OpenAI API 兼容与 Swagger 契约
+        - 模型同步、映射、路由与定价
+        - 故障排查与常见问题
+        - 开发规范与项目架构
+        - 管理端界面文案
+        - 其他
+    validations:
+      required: true
+
+  - type: dropdown
+    id: issue_type
+    attributes:
+      label: 问题类型
+      options:
+        - 文档缺失
+        - 内容错误
+        - 内容已过时
+        - 描述不清晰
+        - 缺少示例
+        - 链接失效
+        - 格式或用词不统一
+        - 其他
+    validations:
+      required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: 文档位置
+      description: 请提供文件路径、页面链接、章节名称或 API 路径。
+      placeholder: "README.md#docker、config.example.yaml、/v1/responses"
+    validations:
+      required: true
+
+  - type: textarea
+    id: issue
+    attributes:
+      label: 当前问题
+      description: 当前文档缺少什么、哪里错误或为什么难以理解？
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: 建议修改
+      description: 请描述建议补充、修正或重写的内容；如有条件可提供示例文本。
+    validations:
+      required: false
+
+  - type: dropdown
+    id: audience
+    attributes:
+      label: 主要受众
+      options:
+        - 新用户
+        - API 调用方
+        - Docker 部署者
+        - 系统管理员
+        - 前端开发者
+        - 后端开发者
+        - 项目贡献者
+        - 其他
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: 提交前检查
+      options:
+        - label: 我已经搜索现有 Issue 和 Pull Request，确认没有相同文档问题。
+          required: true
+        - label: 我已经提供尽可能具体的文档位置。
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,114 @@
+name: 功能建议
+description: 提议新的功能、兼容能力或工程改进。
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        请围绕一个明确的问题或使用场景提出建议，并说明预期行为、兼容性和部署影响。
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: 功能模块
+      description: 请选择建议主要影响的模块。
+      options:
+        - OpenAI API 兼容层（Responses / Chat Completions）
+        - 模型同步、映射、路由与定价
+        - 账号、Provider、OAuth 与凭据
+        - 额度、计费与请求审计
+        - 图片、视频与媒体处理
+        - 管理端前端界面
+        - SQLite / PostgreSQL 数据库
+        - Docker、配置、部署与网络出口
+        - 开发体验与工程质量
+        - 其他
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: 相关 Provider
+      options:
+        - Grok Build
+        - Grok Web
+        - Grok Console
+        - 多个 Provider
+        - 新 Provider
+        - 与 Provider 无关
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: 问题与使用场景
+      description: 当前存在什么限制？谁会受到影响？为什么需要解决？
+      placeholder: 请描述实际使用场景，而不仅是功能名称。
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: 建议方案
+      description: 请描述期望的交互、API、配置或运行行为。
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: 验收标准
+      description: 满足哪些可验证条件时，可以认为该功能已经完成？
+      placeholder: |
+        - 当……时，系统应……
+        - API 应返回……
+        - 现有配置和客户端应继续兼容……
+    validations:
+      required: true
+
+  - type: textarea
+    id: api_example
+    attributes:
+      label: API、配置或界面示例
+      description: 如适用，请提供期望的请求响应、配置片段或界面流程。
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 替代方案
+      description: 请描述目前的解决办法、绕过方式或考虑过的其他设计。
+    validations:
+      required: false
+
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: 兼容性、部署与迁移影响
+      description: 请说明是否影响 API 协议、模型命名、配置、数据库、Docker 部署或现有客户端。
+      placeholder: |
+        API 兼容性：
+        配置变更：
+        数据库迁移：
+        Docker / 网络变更：
+        向后兼容性：
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: 提交前检查
+      options:
+        - label: 我已经搜索现有 Issue 和 Pull Request，确认没有相同建议。
+          required: true
+        - label: 该 Issue 只聚焦一个功能或改进方向。
+          required: true
+        - label: 我已经说明用户价值和可验证的验收标准。
+          required: true

.github/workflows/codeql.yml

@@ -0,0 +1,49 @@
+name: CodeQL Advanced
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "0 0 * * *"
+
+concurrency:
+  group: codeql-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: go
+            build-mode: autobuild
+          - language: javascript-typescript
+            build-mode: none
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: /language:${{ matrix.language }}

.github/workflows/ghcr-image.yml

@@ -0,0 +1,219 @@
+name: GHCR Image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*.*.*"
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ghcr-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: backend/go.mod
+          cache-dependency-path: backend/go.sum
+
+      - name: Test backend
+        working-directory: backend
+        run: go test ./...
+
+      - name: Vet backend
+        working-directory: backend
+        run: go vet ./...
+
+      - name: Verify Swagger document
+        run: |
+          make swagger
+          git diff --exit-code -- backend/docs/docs.go backend/docs/swagger.json backend/docs/swagger.yaml
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.5.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint frontend
+        working-directory: frontend
+        run: pnpm lint
+
+      - name: Build frontend
+        working-directory: frontend
+        run: pnpm build
+
+  check_ghcr_image:
+    name: Build image (${{ matrix.arch }})
+    if: github.event_name != 'push'
+    needs: verify
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: ${{ matrix.platform }}
+          push: false
+          cache-from: type=gha,scope=${{ matrix.arch }}
+          provenance: false
+          sbom: false
+
+  build_ghcr_image:
+    name: Publish image (${{ matrix.arch }})
+    if: github.event_name == 'push'
+    needs: verify
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Normalize image name
+        id: image
+        shell: bash
+        run: |
+          image_name=$(printf '%s' "$GITHUB_REPOSITORY" | tr '[:upper:]' '[:lower:]')
+          echo "name=ghcr.io/$image_name" >> "$GITHUB_OUTPUT"
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ steps.image.outputs.name }}
+          tags: |
+            type=ref,event=branch,suffix=-${{ matrix.arch }}
+            type=ref,event=tag,suffix=-${{ matrix.arch }}
+            type=raw,value=latest-${{ matrix.arch }},enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and publish
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: ${{ matrix.platform }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha,scope=${{ matrix.arch }}
+          cache-to: type=gha,scope=${{ matrix.arch }},mode=max
+          provenance: mode=max
+          sbom: true
+
+  merge:
+    name: Merge image
+    if: github.event_name == 'push'
+    needs:
+      - build_ghcr_image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Normalize image name
+        id: image
+        shell: bash
+        run: |
+          image_name=$(printf '%s' "$GITHUB_REPOSITORY" | tr '[:upper:]' '[:lower:]')
+          echo "name=ghcr.io/$image_name" >> "$GITHUB_OUTPUT"
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ steps.image.outputs.name }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create manifest list
+        shell: bash
+        run: |
+          jq -cr '.tags[]' <<< "$DOCKER_METADATA_OUTPUT_JSON" | while read -r tag; do
+            docker buildx imagetools create \
+              -t "$tag" \
+              "${tag}-amd64" \
+              "${tag}-arm64"
+          done
+
+      - name: Inspect image
+        run: docker buildx imagetools inspect "${{ steps.image.outputs.name }}:${{ steps.meta.outputs.version }}"

.github/workflows/stale.yml

@@ -0,0 +1,30 @@
+name: Close inactive issues and PRs
+
+on:
+  schedule:
+    - cron: "30 1 * * *"
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    name: Mark and close inactive issues and PRs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Process stale issues and PRs
+        uses: actions/stale@v10
+        with:
+          days-before-issue-stale: 7
+          days-before-pr-stale: 7
+          days-before-issue-close: 7
+          days-before-pr-close: 7
+          stale-issue-label: stale
+          stale-pr-label: stale
+          stale-issue-message: This issue has had no activity for 7 days. It will be closed in 7 days if there is no further activity.
+          stale-pr-message: This pull request has had no activity for 7 days. It will be closed in 7 days if there is no further activity.
+          close-issue-message: This issue was closed because it had no activity for 7 days after being marked stale.
+          close-pr-message: This pull request was closed because it had no activity for 7 days after being marked stale.

.gitignore

@@ -0,0 +1,45 @@
+# OS and editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Local environment and secrets
+# 注意: HF 部署需要 config.yaml 入库（打进镜像），所以不忽略它
+.env
+.env.*
+!.env.example
+/docs/*
+/docs/rules/*
+/backend/docs/goal/
+*.har
+*.pcap
+*.pcapng
+
+# Runtime data
+/data/
+/backend/data/
+*.log
+
+# Go
+/.gocache/
+/.gocache-*/
+/backend/grok2api
+/backend/coverage.out
+*.coverprofile
+*.test
+
+# Frontend
+/.pnpm-store/
+/frontend/node_modules/
+/frontend/dist/
+/frontend/.cache/
+/frontend/*.tsbuildinfo
+
+# Temporary files
+/release/
+/.tmp/
+/tmp/

Dockerfile

@@ -0,0 +1,73 @@
+ARG NODE_VERSION=22
+ARG GO_VERSION=1.26
+ARG ALPINE_VERSION=3.23
+
+FROM --platform=$BUILDPLATFORM node:${NODE_VERSION}-alpine AS frontend-builder
+
+WORKDIR /src/frontend
+RUN corepack enable
+
+COPY frontend/package.json frontend/pnpm-lock.yaml ./
+RUN --mount=type=cache,id=grok2api-pnpm,target=/pnpm/store \
+    pnpm config set store-dir /pnpm/store && \
+    pnpm fetch --frozen-lockfile
+
+RUN --mount=type=cache,id=grok2api-pnpm,target=/pnpm/store \
+    pnpm config set store-dir /pnpm/store && \
+    pnpm install --offline --frozen-lockfile
+
+COPY frontend/index.html frontend/vite.config.ts frontend/tsconfig.json frontend/tsconfig.app.json frontend/tsconfig.node.json ./
+COPY frontend/public ./public
+COPY frontend/src ./src
+RUN --mount=type=cache,id=grok2api-tsc,target=/src/frontend/.cache,sharing=locked \
+    pnpm build
+
+
+FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS backend-builder
+
+ARG TARGETOS
+ARG TARGETARCH
+
+WORKDIR /src/backend
+RUN apk add --no-cache ca-certificates git
+
+COPY backend/go.mod backend/go.sum ./
+RUN --mount=type=cache,id=grok2api-go-mod,target=/go/pkg/mod,sharing=locked \
+    go mod download
+
+COPY backend/cmd ./cmd
+COPY backend/internal ./internal
+COPY backend/docs/docs.go ./docs/docs.go
+RUN --mount=type=cache,id=grok2api-go-mod,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,id=grok2api-go-build,target=/root/.cache/go-build,sharing=locked \
+    CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
+    go build -buildvcs=false -trimpath -ldflags="-s -w" -o /out/grok2api ./cmd/grok2api
+
+
+FROM alpine:${ALPINE_VERSION}
+
+ENV TZ=Asia/Shanghai \
+    GROK2API_CONFIG_SOURCE=/run/grok2api/config.yaml
+
+RUN apk add --no-cache ca-certificates su-exec tzdata openssl && \
+    addgroup -S -g 10001 grok2api && \
+    adduser -S -D -H -u 10001 -G grok2api grok2api && \
+    mkdir -p /app /run/grok2api && \
+    chown -R grok2api:grok2api /app /run/grok2api
+
+WORKDIR /app
+
+COPY --from=backend-builder --chmod=0755 /out/grok2api /app/grok2api
+COPY --from=frontend-builder /src/frontend/dist /app/frontend/dist
+COPY VERSION /app/VERSION
+COPY --chmod=0755 docker/entrypoint.sh /usr/local/bin/grok2api-entrypoint
+# Hugging Face Spaces: 把配置打进镜像（HF 无卷挂载，靠 entrypoint 落盘）
+COPY config.yaml /run/grok2api/config.yaml
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD wget -qO- http://127.0.0.1:8000/healthz >/dev/null || exit 1
+
+ENTRYPOINT ["/usr/local/bin/grok2api-entrypoint"]
+CMD ["/app/grok2api", "--config", "/app/config.yaml", "--listen", "0.0.0.0:8000"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chenyme
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,14 @@
+.PHONY: run swagger
+
+CONFIG ?= $(CURDIR)/config.yaml
+
+run:
+	cd backend && GOCACHE=$(CURDIR)/.gocache go run ./cmd/grok2api --config "$(abspath $(CONFIG))" $(RUN_ARGS)
+
+swagger:
+	cd backend && GOCACHE=$(CURDIR)/.gocache go run github.com/swaggo/swag/cmd/swag@v1.16.6 init \
+		-g main.go \
+		-d cmd/grok2api,internal/transport/http \
+		--parseInternal \
+		--output docs \
+		--outputTypes go,json,yaml

README.md

@@ -0,0 +1,34 @@
+---
+title: Grok2API
+emoji: 🚀
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 8000
+pinned: false
+---
+
+# Grok2API - Hugging Face Spaces 部署版 (v3.0.11)
+
+Grok Build / Grok Web / Grok Console 多账号 API 网关，OpenAI / Anthropic 兼容接口。
+本仓库为 [chenyme/grok2api](https://github.com/chenyme/grok2api) v3.0.11 的 HF Spaces 适配版。
+
+## 部署要点
+
+1. **端口**：`app_port: 8000`（上方 YAML 头块），与容器内监听端口一致。
+2. **配置**：`config.yaml` 已打进 Docker 镜像（`/run/grok2api/config.yaml`），
+   密钥/管理员密码直接写在文件里。**公开空间下这些值可见，建议把 Space 设为 Private。**
+3. **数据持久化**：数据库与媒体文件存放在 `/data`（HF Persistent Storage 挂载点）。
+   请在 Space Settings 中开启 Persistent Storage，否则重启后数据丢失。
+4. **管理员登录**：部署完成后访问本 Space 根路径进入管理后台，
+   用户名 `admin`，密码见 `config.yaml` 的 `bootstrapAdmin.password`，
+   首次登录后请在管理端修改密码。
+
+## 环境变量
+
+本版 Go 服务**不读取**旧版 Python 时代的环境变量（`APP_KEY`、`API_KEY`、
+`BOOTSTRAP_ADMIN_PASSWORD` 等均无效），所有配置都在 `config.yaml` 中完成。
+
+## 许可证
+
+MIT License

README.zh-CN.md

@@ -0,0 +1,359 @@
+<p align="center">
+  <img alt="Grok2API" src="./frontend/public/grok2api.png" width="720" />
+</p>
+
+<p align="center">
+  <strong>面向 Grok Build、Grok Web 与 Grok Console 的多账号 API 网关</strong>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> | 简体中文
+</p>
+
+<p align="center">
+  <a href="./backend/go.mod"><img alt="Go" src="https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white" /></a>
+  <a href="./frontend/package.json"><img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=111827" /></a>
+  <a href="https://github.com/chenyme/grok2api/pkgs/container/grok2api"><img alt="Docker" src="https://img.shields.io/badge/Docker-amd64%20%7C%20arm64-2496ED?logo=docker&logoColor=white" /></a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/19868?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-19868" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/19868" alt="chenyme%2Fgrok2api | Trendshift" width="250" height="55"/></a>
+</p>
+
+> [!TIP]
+> 推荐个人新项目 [DEEIX-AI / DEEIX-Chat](https://github.com/DEEIX-AI/DEEIX-Chat)：面向多模型路由、对话、文件、工具、计费与运维的一体化轻量 AI 平台。
+
+> [!NOTE]
+> 本项目仅供技术研究与学习交流。使用时请务必遵循 Grok 官方的使用条款及当地法律法规，否则一切后果自负！
+
+## 赞助商
+
+> [希望赞助这个项目？](mailto:chenyme03@gmail.com)
+
+<table>
+<tr>
+<td width="200" align="center" valign="middle"><a href="https://www.krill-ai.com/register?invite=KJ2VGIRVAE"><img src="https://raw.githubusercontent.com/Krill-ai-org/krill-ai-static/refs/heads/main/krill-logo/Eng/250x150.png" alt="Krill AI" width="160"></a></td>
+<td valign="middle">感谢 Krill AI 赞助了本项目！Krill 提供 GPT / Claude / Gemini / 多款国产模型的官方稳定极速的 API 中转服务，支持企业级定制、报销开票、7×16h 专属技术支持。更有独家适配的 WebSocket 连接，畅享极速首字速度。Krill 为本项目提供了特别优惠，使用<a href="https://www.krill-ai.com/register?invite=KJ2VGIRVAE">此链接</a>注册并在下订单时填写「grok2api」优惠码，首购套餐可享 Codex 77 折优惠！</td>
+</tr>
+<tr>
+<td width="200" align="center" valign="middle"><a href="https://github.com/DEEIX-AI/DEEIX-Chat"><img src="frontend/public/sponner/deeix-chat_deeix-ai.png" alt="DEEIX AI / DEEIX Chat" width="160"></a></td>
+<td valign="middle">DEEIX-Chat 是一款开源可部署的 AI Chat 平台，面向需要长期、稳定、统一使用多模型能力的个人、团队与企业，将模型、对话、文件、工具调用与后台管理整合为一套可部署、可扩展的系统。点击 <a href="https://github.com/DEEIX-AI/DEEIX-Chat">此处</a> 开始部署！</td>
+</tr>
+<tr>
+<td width="200" align="center" valign="middle"><a href="https://www.right.codes/register"><img src="frontend/public/sponner/rightcode.jpg" alt="RightCode" width="160"></a></td>
+<td valign="middle">Right Code 是一个企业级 AI Agent 分发平台，主要提供稳定的 Claude Code、Codex、Gemini 等模型的中转服务。充值即可开票，企业、团队用户一对一对接。感谢 Right Code 提供的 Tokens 支持，点击 <a href="https://www.right.codes/register">此处</a> 注册并开始使用！</td>
+</tr>
+</table>
+
+<br>
+
+## 项目简介
+
+Grok2API 是一个内置 React 管理端的 Go 网关。它分别管理 Grok Build、Grok Web 和 Grok Console 账号池，并对外提供统一的 OpenAI 与 Anthropic 兼容接口。
+
+### 项目架构
+
+```mermaid
+flowchart LR
+    %% 颜色定义
+    classDef access fill:#e1f5fe,stroke:#01579b
+    classDef core fill:#fff3e0,stroke:#e65100
+    classDef providers fill:#f3e5f5,stroke:#4a148c
+    classDef infra fill:#e8f5e9,stroke:#1b5e20
+    classDef upstream fill:#fce4ec,stroke:#880e4f
+
+    subgraph Access["接入域"]
+        direction LR
+        Clients["API 客户端"]
+        Admin["React 管理端"]
+    end
+
+    subgraph Core["网关核心域"]
+        direction LR
+        Management["管理服务<br/>账号 · 模型 · 密钥 · 设置"]
+        Sync["账号同步<br/>凭据 · 额度 · 模型"]
+        Gateway["网关服务<br/>协议 · 路由 · 选号 · 重试"]
+        Audit["审计服务<br/>用量 · 客户端计费"]
+        Management --> Sync
+        Gateway -.-> Audit
+    end
+
+    subgraph Providers["Provider 渠道域"]
+        direction LR
+        Registry["Provider 注册表"]
+        Build["Grok Build<br/>OAuth · 动态模型 · Billing"]
+        Web["Grok Web<br/>SSO · 远端额度 · 媒体"]
+        Console["Grok Console<br/>SSO · 本地窗口 · 无状态"]
+        Registry --> Build
+        Registry --> Web
+        Registry --> Console
+    end
+
+    subgraph Infra["共享基础设施域"]
+        direction LR
+        Egress["出口管理器<br/>作用域 · 代理池 · ���退 · Clearance"]
+        Database[("SQLite / PostgreSQL")]
+        Runtime[("Memory / Redis")]
+    end
+
+    Upstream["🌐 Grok 上游"]
+
+    %% 跨域调用
+    Clients --> Gateway
+    Admin --> Management
+    Gateway --> Registry
+    Sync --> Registry
+    Build -->|grok_build| Egress
+    Web -->|grok_web / asset| Egress
+    Console -->|grok_console| Egress
+    Egress --> Upstream
+    Management --> Database
+    Audit --> Database
+    Gateway <--> Runtime
+
+    %% 应用样式
+    class Clients,Admin access
+    class Management,Sync,Gateway,Audit core
+    class Registry,Build,Web,Console providers
+    class Egress,Database,Runtime infra
+    class Upstream upstream
+```
+
+网关通过 Provider 注册表分发请求，账号同步负责刷新凭据、额度和模型。三个渠道独立维护账号状态并使用隔离的出口作用域；请求结束后统一结算用量、审计和客户端计费。
+
+### 核心能力
+
+| 模块 | 能力 |
+| :-- | :-- |
+| 接口 | Responses、Chat Completions、Anthropic Messages、Images 与异步 Videos |
+| 客户端 | Codex、Claude Code，以及 OpenAI/Anthropic 兼容 SDK |
+| 账号 | 批量导入导出、额度同步、凭据续期、转换、账号工具与清理 |
+| 路由 | 模型发现、Provider 限定、会话粘滞、额度/并发门禁和有界切换 |
+| 会话 | stored response、compact、Prompt Cache 亲和与可选 reasoning replay |
+| 媒体 | 图片生成与编辑、视频任务、本地归档及 URL/Base64/SSE 输出 |
+| 出口 | HTTP/SOCKS/Resin、订阅、探测、代理池、调配、回退与 FlareSolverr |
+| 运维 | Dashboard、模型路由、客户端密钥、审计、运行设置和媒体库 |
+
+### Provider 边界
+
+| Provider | 认证 | 模型 | 主要能力 |
+| :-- | :-- | :-- | :-- |
+| Grok Build | OAuth / 设备授权 | 按账号动态发现 | Responses、Chat、Messages、compact、stored response、视频 |
+| Grok Web | SSO | 内置并按等级过滤 | Responses、Chat、Messages、图片、图片编辑、视频 |
+| Grok Console | SSO | 内置 | 无状态 Responses、Chat、Messages |
+
+三个 Provider 独立维护凭据、额度、健康、冷却、并发与模型能力。故障切换不会跨 Provider 混用账号状态。
+
+## 快速部署
+
+官方镜像支持 `linux/amd64` 和 `linux/arm64`。
+
+```bash
+git clone https://github.com/chenyme/grok2api.git
+cd grok2api
+cp config.example.yaml config.yaml
+```
+
+生成密钥并写入 `config.yaml`：
+
+```bash
+openssl rand -hex 32
+openssl rand -base64 32
+```
+
+```yaml
+secrets:
+  jwtSecret: "替换为生成的 Hex 密钥"
+  credentialEncryptionKey: "替换为生成的 Base64 密钥"
+
+bootstrapAdmin:
+  username: "admin"
+  password: "替换为强密码"
+```
+
+启动服务：
+
+```bash
+docker compose pull
+docker compose up -d
+docker compose logs -f grok2api
+```
+
+访问 `http://127.0.0.1:8000`。镜像已包含前端，SQLite 数据库与本地媒体保存在 Compose 数据卷中。
+
+### 源码运行
+
+```bash
+cp config.example.yaml config.yaml
+make run
+```
+
+单独运行前端开发服务：
+
+```bash
+cd frontend
+pnpm install
+pnpm dev
+```
+
+## 初始化网关
+
+1. 使用初始管理员登录。
+2. 接入 Build、Web 或 Console 账号。
+3. 等待额度和模型能力同步完成。
+4. 在“模型路由”中确认公开模型。
+5. 在“客户端密钥”中创建密钥。
+6. 使用该密钥调用 `/v1/*`。
+
+首次登录后请修改管理员密码，并从配置中删除 `bootstrapAdmin`。账号写入后不要更换 `credentialEncryptionKey`。
+
+### 账号操作
+
+| Provider | 接入或导入 | 导出 |
+| :-- | :-- | :-- |
+| Build | 设备授权、JSON/JSONL | 可重新导入的账号文件 |
+| Web | 粘贴/TXT SSO、JSON/JSONL | 可重新导入的账号文件 |
+| Console | 粘贴/TXT SSO、JSON/JSONL | 可重新导入的账号文件 |
+
+导入兼容 UTF-8 BOM。批量额度同步、Build 凭据续期、Web→Build/Console 转换、账号工具和账号清理均显示实时进度。
+
+Web 账号工具支持接受协议、设置对应 20–40 岁的随机生日和开启 NSFW；已完成步骤会记录并在后续执行时跳过。
+
+系统支持自动删除长期处于 `reauthRequired` 的账号，默认关闭；存在活动推理租约或视频任务的账号不会被删除。
+
+> [!TIP]
+> 从 Python 版迁移时，请将 Grok Web SSO 导出为 TXT，再导入“Grok Web”。旧数据库和号池元数据不兼容。
+
+## 模型与路由
+
+Build 模型根据账号能力动态发现；Web、Console 使用内置目录。请以模型页面或 `GET /v1/models` 为准，README 不再维护容易过期的静态模型清单。
+
+公开模型名通常不带 Provider。内部路由使用 `Build/`、`Web/` 或 `Console/` 前缀；带前缀名称可显式限定来源。
+
+Web 可与对应的 Build、Console 建立一对一弱关联。关联只共享匿名出口身份和来源展示，不合并凭据、额度、健康、冷却、并发、模型能力或计费。
+
+### Codex、Claude Code 与 Prompt Cache
+
+Responses 与 Messages 支持流式、工具、推理、多轮会话和 compact。客户端会话信号会保持稳定，用于 Grok Build Prompt Cache 亲和；实际命中仍要求上游账号兼容且请求前缀未变化。
+
+Responses 与 Chat Completions 按 OpenAI 语义报告输入总量；Messages 按 Anthropic 语义分开报告未缓存输入和缓存读取。审计保留输入总量与缓存部分，用于计费对账。
+
+## API
+
+推理接口使用客户端密钥：
+
+```http
+Authorization: Bearer g2a_xxx_xxx
+```
+
+| 方法 | 路径 | 用途 |
+| :-- | :-- | :-- |
+| `GET` | `/healthz`、`/readyz` | 存活与就绪检查 |
+| `GET` | `/v1/models` | 当前可服务模型 |
+| `POST` | `/v1/responses` | Responses JSON/SSE |
+| `POST` | `/v1/responses/compact` | 压缩支持的 Response 会话 |
+| `GET`、`DELETE` | `/v1/responses/{id}` | 查询或删除 stored response |
+| `POST` | `/v1/chat/completions` | Chat Completions JSON/SSE |
+| `POST` | `/v1/messages` | Anthropic Messages JSON/SSE |
+| `POST` | `/v1/images/generations`、`/v1/images/edits` | 生成或编辑图片 |
+| `POST`、`GET` | `/v1/videos/*` | 创建和查询视频任务 |
+| `GET` | `/v1/media/images/{asset_id}`、`/v1/media/videos/{asset_id}` | 读取归档媒体 |
+
+stored response 和 compact 取决于最终 Provider。登录管理端后可在 `/docs` 查看当前模型与调用示例；仅在 `server.swaggerEnabled: true` 时提供 Swagger。
+
+客户端密钥支持模型白名单，以及可选的 RPM、并发、用量和截止日期限制。
+
+```bash
+curl http://127.0.0.1:8000/v1/responses \
+  -H "Authorization: Bearer g2a_xxx_xxx" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "your-model",
+    "input": "用三句话解释量子隧穿。",
+    "stream": true
+  }'
+```
+
+## 出口与 Cloudflare
+
+出口节点按 Build、Web、Console 或 Web 资源隔离。管理端支持：
+
+- HTTP、HTTPS、SOCKS4/4A、SOCKS5/5H 与 Resin
+- 订阅和文本/Base64 导入
+- 批量探测、筛选、删除、分配与均衡
+- 按作用域配置无回退、直连或固定节点
+- 代理池模式，单次连接失败不会触发全局冷却
+
+Resin 用户名支持 `{account}`：
+
+```text
+socks5h://Default.{account}:RESIN_PROXY_TOKEN@resin:2260
+```
+
+占位符会替换为稳定的匿名身份。已关联的 Web、Build、Console 可共享该身份，不直接使用 Token 或 Email。
+
+如需自动维护 Web/Console Cloudflare Clearance：
+
+```bash
+docker compose --profile flaresolverr up -d
+```
+
+随后在 **运行设置 → 媒体与网络 → Clearance** 选择 `FlareSolverr`，地址填写 `http://flaresolverr:8191`。
+
+出口层只重试可以确认发生在请求提交前的连接故障，不会重放已经提交的生成请求、认证失败、额度耗尽或上游限流。
+
+## 配置与部署
+
+`config.yaml` 保存启动配置；Provider 和运维参数由管理端维护，未标记“重启生效”的设置支持热加载。
+
+| 场景 | 数据库 | 运行态 | 媒体 |
+| :-- | :-- | :-- | :-- |
+| 单实例 | SQLite | Memory | 本地目录 |
+| 多实例 | PostgreSQL | Redis | 共享且可读写的目录 |
+
+多实例需要为每个副本设置唯一的 `deployment.instanceID`，统一使用同一个 `clusterID`；只有媒体目录已正确共享时才设置 `sharedMedia: true`。
+
+重要的可选设置：
+
+- `audit.ledgerMode`：`observe` 仅报告账本故障；`enforce` 可暂停新推理以保护计费准确性。
+- `routing.segmentedSelectorEnabled`：用于大型账号池，同时保留完整选号回退与原子门禁。
+- Build 响应头超时和精确匹配的 403 失效规则支持热加载。
+- “同步最新版本”可应用已验证的 Grok Build 客户端版本和 User-Agent。
+
+## 生产检查
+
+- 使用 HTTPS，并启用 `auth.secureCookies`。
+- 公网部署保持 Swagger 关闭。
+- 使用强密钥并妥善备份；不要提交凭据、Cookie、账号导出或数据库。
+- 备份 `config.yaml`、数据库和媒体目录。
+- 多实例同时使用 PostgreSQL、Redis 与共享媒体。
+- 公网服务前置反向代理与访问控制。
+
+## 开发验证
+
+```bash
+cd backend
+go test ./...
+go test -race ./...
+go vet ./...
+go build ./cmd/grok2api
+```
+
+```bash
+cd frontend
+pnpm install --frozen-lockfile
+pnpm lint
+pnpm build
+```
+
+修改公开 API 注释后重新生成 Swagger：
+
+```bash
+make swagger
+```
+
+## 相关文档
+
+- [English README](./README.md)
+- [后端说明](./backend/README.md)
+- [前端说明](./frontend/README.md)

VERSION

@@ -0,0 +1 @@
+v3.0.11

backend/Makefile

@@ -0,0 +1,5 @@
+.PHONY: run
+
+# 在 backend/ 目录复用项目根目录的启动入口和配置路径。
+run:
+	$(MAKE) -C .. run

backend/README.md

@@ -0,0 +1,82 @@
+# Grok2API Backend
+
+Grok2API 的 Go 后端，负责上游账号调度、协议转换、额度管理、请求审计和管理 API，并可直接托管前端构建产物。
+
+## 技术栈
+
+- Go 1.26、Gin、GORM
+- SQLite / PostgreSQL
+- Memory / Redis
+- Grok Build OAuth、Grok Web SSO 与 Grok Console SSO Provider
+
+## 本地运行
+
+配置文件位于仓库根目录。首次运行前创建本地配置并设置安全密钥：
+
+```bash
+cp config.example.yaml config.yaml
+openssl rand -hex 32
+openssl rand -base64 32
+```
+
+将生成值写入 `config.yaml` 的 `secrets`，并修改 `bootstrapAdmin` 初始密码，然后启动：
+
+```bash
+cd backend
+go run ./cmd/grok2api
+```
+
+服务默认监听 `http://127.0.0.1:8000`。也可以显式指定配置文件或监听地址：
+
+```bash
+go run ./cmd/grok2api --config /path/to/config.yaml --listen 0.0.0.0:8000
+```
+
+## 配置与存储
+
+启动配置统一由根目录 `config.yaml` 管理，启动阶段字段见 [`config.example.yaml`](../config.example.yaml)。Provider、服务容量、批量任务、路由、媒体、审计和客户端密钥默认限制由管理端设置页持久化；除页面明确标记“重启生效”的字段外均会热加载。
+
+| 场景 | 数据库 | 运行态存储 |
+| --- | --- | --- |
+| 本地开发 / 单实例 | SQLite | Memory |
+| 多实例部署 | PostgreSQL | Redis |
+
+关系型数据库保存账号、凭据、模型、额度、客户端密钥、审计和媒体任务；Redis 仅承载限流、并发租约、粘滞路由、分布式锁和事件通知。敏感凭据使用 `credentialEncryptionKey` 加密，该密钥必须长期保留且不得提交到版本库。
+
+运行设置与代理参数由管理端设置页维护；数据库驱动、监听地址、Redis、JWT 与加密密钥仍通过 YAML 配置并在启动时生效。
+
+## 服务入口
+
+- `/v1/*`：兼容 API
+- `/api/admin/v1/*`：管理 API
+- `/healthz`、`/readyz`：健康与就绪探针
+- `/swagger/index.html`：公开 API Swagger，仅在 `server.swaggerEnabled: true` 时注册
+- `frontend.staticPath`：前端静态目录，默认 `./frontend/dist`
+
+详细协议说明见 [`docs`](./docs)。
+
+修改公开接口注释后，在仓库根目录执行 `make swagger` 更新 `backend/docs/docs.go`、`swagger.json` 与 `swagger.yaml`。生产配置应保持 `server.swaggerEnabled: false`。
+
+## 代码结构
+
+```text
+cmd/grok2api/       进程入口
+internal/domain/    领域模型与规则
+internal/application/ 应用服务与用例
+internal/infra/     数据库、Provider、运行态与安全实现
+internal/transport/ HTTP 路由、鉴权与协议适配
+internal/repository/ 持久化接口
+```
+
+依赖方向保持为 Transport → Application → Domain，基础设施通过接口接入，不在领域层依赖 HTTP、数据库或具体 Provider。
+
+三个 Provider 通过声明式 Definition 和小型能力接口注册：Build 使用远程模型目录与 Billing，Web 使用按等级过滤的静态目录与上游额度窗口，Console 使用静态目录和无状态 Responses。Gateway 只根据能力声明完成路由与调度，不在通用 Handler 中拼装 Provider 私有请求。
+
+## 验证
+
+```bash
+go test ./...
+go test -race ./...
+go vet ./...
+go build ./cmd/grok2api
+```

backend/cmd/grok2api/main.go

@@ -0,0 +1,24 @@
+package main
+
+// @title Grok2API
+// @version 1.0
+// @description Grok Build 与 Grok Web 多账号 API 网关。
+// @BasePath /
+// @securityDefinitions.apikey BearerAuth
+// @in header
+// @name Authorization
+// @description 使用 "Bearer g2a_xxx_xxx"。
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/chenyme/grok2api/backend/internal/cli"
+)
+
+func main() {
+	if err := cli.Run(os.Args[1:]); err != nil {
+		_, _ = fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

backend/docs/docs.go

@@ -0,0 +1,809 @@
+// Package docs Code generated by swaggo/swag. DO NOT EDIT
+package docs
+
+import "github.com/swaggo/swag"
+
+const docTemplate = `{
+    "schemes": {{ marshal .Schemes }},
+    "swagger": "2.0",
+    "info": {
+        "description": "{{escape .Description}}",
+        "title": "{{.Title}}",
+        "contact": {},
+        "version": "{{.Version}}"
+    },
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
+    "paths": {
+        "/healthz": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "System"
+                ],
+                "summary": "存活检查",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "boolean"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/readyz": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "System"
+                ],
+                "summary": "就绪检查",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "boolean"
+                            }
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "boolean"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/chat/completions": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "支持 JSON 与 SSE、图片输入和函数工具。",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Chat"
+                ],
+                "summary": "创建 Chat Completion",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerChatRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/images/edits": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Images"
+                ],
+                "summary": "编辑图片",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerImageEditRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/images/generations": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Images"
+                ],
+                "summary": "生成图片",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerImageGenerationRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/media/images/{asset_id}": {
+            "get": {
+                "produces": [
+                    "image/png"
+                ],
+                "tags": [
+                    "Images"
+                ],
+                "summary": "获取归档图片",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Asset ID",
+                        "name": "asset_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found"
+                    }
+                }
+            }
+        },
+        "/v1/messages": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Messages"
+                ],
+                "summary": "创建 Anthropic Message",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "default": "2023-06-01",
+                        "description": "Anthropic API version",
+                        "name": "anthropic-version",
+                        "in": "header",
+                        "required": true
+                    },
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerMessagesRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/models": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Models"
+                ],
+                "summary": "获取可用模型",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/responses": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "支持 JSON 与 SSE；stream=true 时返回 text/event-stream。",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Responses"
+                ],
+                "summary": "创建 Response",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerResponsesRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/responses/compact": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Responses"
+                ],
+                "summary": "压缩 Response 上下文",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerResponsesRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/responses/{response_id}": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Responses"
+                ],
+                "summary": "查询 Response",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Response ID",
+                        "name": "response_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Responses"
+                ],
+                "summary": "删除 Response",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Response ID",
+                        "name": "response_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/videos/generations": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Videos"
+                ],
+                "summary": "创建异步视频任务",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerVideoGenerationRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/videos/{request_id}": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Videos"
+                ],
+                "summary": "查询异步视频任务",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Request ID",
+                        "name": "request_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "httpserver.SwaggerChatRequest": {
+            "type": "object",
+            "properties": {
+                "messages": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/httpserver.SwaggerMessage"
+                    }
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-chat-fast"
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerImageEditRequest": {
+            "type": "object",
+            "properties": {
+                "aspect_ratio": {
+                    "type": "string",
+                    "example": "1:1"
+                },
+                "image": {
+                    "$ref": "#/definitions/httpserver.SwaggerImageReference"
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-imagine-image-edit"
+                },
+                "n": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "partial_images": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "prompt": {
+                    "type": "string",
+                    "example": "Change the background to black"
+                },
+                "resolution": {
+                    "type": "string",
+                    "example": "1k"
+                },
+                "response_format": {
+                    "type": "string",
+                    "example": "url"
+                },
+                "size": {
+                    "type": "string",
+                    "example": "1024x1024"
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerImageGenerationRequest": {
+            "type": "object",
+            "properties": {
+                "aspect_ratio": {
+                    "type": "string",
+                    "example": "16:9"
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-imagine-image-quality"
+                },
+                "n": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "partial_images": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "prompt": {
+                    "type": "string",
+                    "example": "A cinematic city at night"
+                },
+                "resolution": {
+                    "type": "string",
+                    "example": "2k"
+                },
+                "response_format": {
+                    "type": "string",
+                    "example": "url"
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerImageReference": {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "example": "https://example.com/source.png"
+                }
+            }
+        },
+        "httpserver.SwaggerMessage": {
+            "type": "object",
+            "properties": {
+                "content": {},
+                "role": {
+                    "type": "string",
+                    "example": "user"
+                }
+            }
+        },
+        "httpserver.SwaggerMessagesRequest": {
+            "type": "object",
+            "properties": {
+                "max_tokens": {
+                    "type": "integer",
+                    "example": 1024
+                },
+                "messages": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/httpserver.SwaggerMessage"
+                    }
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-chat-expert"
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerResponsesRequest": {
+            "type": "object",
+            "properties": {
+                "input": {},
+                "model": {
+                    "type": "string",
+                    "example": "grok-chat-auto"
+                },
+                "previous_response_id": {
+                    "type": "string"
+                },
+                "prompt_cache_key": {
+                    "type": "string"
+                },
+                "store": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerVideoGenerationRequest": {
+            "type": "object",
+            "properties": {
+                "aspect_ratio": {
+                    "type": "string",
+                    "example": "16:9"
+                },
+                "duration": {
+                    "type": "integer",
+                    "example": 8
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-imagine-video"
+                },
+                "prompt": {
+                    "type": "string",
+                    "example": "A cinematic tracking shot in the rain"
+                },
+                "resolution": {
+                    "type": "string",
+                    "example": "720p"
+                }
+            }
+        }
+    },
+    "securityDefinitions": {
+        "BearerAuth": {
+            "description": "使用 \"Bearer g2a_xxx_xxx\"。",
+            "type": "apiKey",
+            "name": "Authorization",
+            "in": "header"
+        }
+    }
+}`
+
+// SwaggerInfo holds exported Swagger Info so clients can modify it
+var SwaggerInfo = &swag.Spec{
+	Version:          "1.0",
+	Host:             "",
+	BasePath:         "/",
+	Schemes:          []string{},
+	Title:            "Grok2API",
+	Description:      "Grok Build 与 Grok Web 多账号 API 网关。",
+	InfoInstanceName: "swagger",
+	SwaggerTemplate:  docTemplate,
+	LeftDelim:        "{{",
+	RightDelim:       "}}",
+}
+
+func init() {
+	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
+}

backend/docs/swagger.json

@@ -0,0 +1,784 @@
+{
+    "swagger": "2.0",
+    "info": {
+        "description": "Grok Build 与 Grok Web 多账号 API 网关。",
+        "title": "Grok2API",
+        "contact": {},
+        "version": "1.0"
+    },
+    "basePath": "/",
+    "paths": {
+        "/healthz": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "System"
+                ],
+                "summary": "存活检查",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "boolean"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/readyz": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "System"
+                ],
+                "summary": "就绪检查",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "boolean"
+                            }
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "boolean"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/chat/completions": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "支持 JSON 与 SSE、图片输入和函数工具。",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Chat"
+                ],
+                "summary": "创建 Chat Completion",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerChatRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/images/edits": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Images"
+                ],
+                "summary": "编辑图片",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerImageEditRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/images/generations": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Images"
+                ],
+                "summary": "生成图片",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerImageGenerationRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/media/images/{asset_id}": {
+            "get": {
+                "produces": [
+                    "image/png"
+                ],
+                "tags": [
+                    "Images"
+                ],
+                "summary": "获取归档图片",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Asset ID",
+                        "name": "asset_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found"
+                    }
+                }
+            }
+        },
+        "/v1/messages": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Messages"
+                ],
+                "summary": "创建 Anthropic Message",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "default": "2023-06-01",
+                        "description": "Anthropic API version",
+                        "name": "anthropic-version",
+                        "in": "header",
+                        "required": true
+                    },
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerMessagesRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/models": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Models"
+                ],
+                "summary": "获取可用模型",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/responses": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "支持 JSON 与 SSE；stream=true 时返回 text/event-stream。",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Responses"
+                ],
+                "summary": "创建 Response",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerResponsesRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/responses/compact": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Responses"
+                ],
+                "summary": "压缩 Response 上下文",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerResponsesRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/responses/{response_id}": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Responses"
+                ],
+                "summary": "查询 Response",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Response ID",
+                        "name": "response_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Responses"
+                ],
+                "summary": "删除 Response",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Response ID",
+                        "name": "response_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/videos/generations": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Videos"
+                ],
+                "summary": "创建异步视频任务",
+                "parameters": [
+                    {
+                        "description": "请求",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/httpserver.SwaggerVideoGenerationRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/v1/videos/{request_id}": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Videos"
+                ],
+                "summary": "查询异步视频任务",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Request ID",
+                        "name": "request_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "httpserver.SwaggerChatRequest": {
+            "type": "object",
+            "properties": {
+                "messages": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/httpserver.SwaggerMessage"
+                    }
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-chat-fast"
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerImageEditRequest": {
+            "type": "object",
+            "properties": {
+                "aspect_ratio": {
+                    "type": "string",
+                    "example": "1:1"
+                },
+                "image": {
+                    "$ref": "#/definitions/httpserver.SwaggerImageReference"
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-imagine-image-edit"
+                },
+                "n": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "partial_images": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "prompt": {
+                    "type": "string",
+                    "example": "Change the background to black"
+                },
+                "resolution": {
+                    "type": "string",
+                    "example": "1k"
+                },
+                "response_format": {
+                    "type": "string",
+                    "example": "url"
+                },
+                "size": {
+                    "type": "string",
+                    "example": "1024x1024"
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerImageGenerationRequest": {
+            "type": "object",
+            "properties": {
+                "aspect_ratio": {
+                    "type": "string",
+                    "example": "16:9"
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-imagine-image-quality"
+                },
+                "n": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "partial_images": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "prompt": {
+                    "type": "string",
+                    "example": "A cinematic city at night"
+                },
+                "resolution": {
+                    "type": "string",
+                    "example": "2k"
+                },
+                "response_format": {
+                    "type": "string",
+                    "example": "url"
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerImageReference": {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "example": "https://example.com/source.png"
+                }
+            }
+        },
+        "httpserver.SwaggerMessage": {
+            "type": "object",
+            "properties": {
+                "content": {},
+                "role": {
+                    "type": "string",
+                    "example": "user"
+                }
+            }
+        },
+        "httpserver.SwaggerMessagesRequest": {
+            "type": "object",
+            "properties": {
+                "max_tokens": {
+                    "type": "integer",
+                    "example": 1024
+                },
+                "messages": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/httpserver.SwaggerMessage"
+                    }
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-chat-expert"
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerResponsesRequest": {
+            "type": "object",
+            "properties": {
+                "input": {},
+                "model": {
+                    "type": "string",
+                    "example": "grok-chat-auto"
+                },
+                "previous_response_id": {
+                    "type": "string"
+                },
+                "prompt_cache_key": {
+                    "type": "string"
+                },
+                "store": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "stream": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "httpserver.SwaggerVideoGenerationRequest": {
+            "type": "object",
+            "properties": {
+                "aspect_ratio": {
+                    "type": "string",
+                    "example": "16:9"
+                },
+                "duration": {
+                    "type": "integer",
+                    "example": 8
+                },
+                "model": {
+                    "type": "string",
+                    "example": "grok-imagine-video"
+                },
+                "prompt": {
+                    "type": "string",
+                    "example": "A cinematic tracking shot in the rain"
+                },
+                "resolution": {
+                    "type": "string",
+                    "example": "720p"
+                }
+            }
+        }
+    },
+    "securityDefinitions": {
+        "BearerAuth": {
+            "description": "使用 \"Bearer g2a_xxx_xxx\"。",
+            "type": "apiKey",
+            "name": "Authorization",
+            "in": "header"
+        }
+    }
+}

backend/docs/swagger.yaml

@@ -0,0 +1,514 @@
+basePath: /
+definitions:
+  httpserver.SwaggerChatRequest:
+    properties:
+      messages:
+        items:
+          $ref: '#/definitions/httpserver.SwaggerMessage'
+        type: array
+      model:
+        example: grok-chat-fast
+        type: string
+      stream:
+        example: false
+        type: boolean
+    type: object
+  httpserver.SwaggerImageEditRequest:
+    properties:
+      aspect_ratio:
+        example: "1:1"
+        type: string
+      image:
+        $ref: '#/definitions/httpserver.SwaggerImageReference'
+      model:
+        example: grok-imagine-image-edit
+        type: string
+      "n":
+        example: 1
+        type: integer
+      partial_images:
+        example: 0
+        type: integer
+      prompt:
+        example: Change the background to black
+        type: string
+      resolution:
+        example: 1k
+        type: string
+      response_format:
+        example: url
+        type: string
+      size:
+        example: 1024x1024
+        type: string
+      stream:
+        example: false
+        type: boolean
+    type: object
+  httpserver.SwaggerImageGenerationRequest:
+    properties:
+      aspect_ratio:
+        example: "16:9"
+        type: string
+      model:
+        example: grok-imagine-image-quality
+        type: string
+      "n":
+        example: 1
+        type: integer
+      partial_images:
+        example: 0
+        type: integer
+      prompt:
+        example: A cinematic city at night
+        type: string
+      resolution:
+        example: 2k
+        type: string
+      response_format:
+        example: url
+        type: string
+      stream:
+        example: false
+        type: boolean
+    type: object
+  httpserver.SwaggerImageReference:
+    properties:
+      url:
+        example: https://example.com/source.png
+        type: string
+    type: object
+  httpserver.SwaggerMessage:
+    properties:
+      content: {}
+      role:
+        example: user
+        type: string
+    type: object
+  httpserver.SwaggerMessagesRequest:
+    properties:
+      max_tokens:
+        example: 1024
+        type: integer
+      messages:
+        items:
+          $ref: '#/definitions/httpserver.SwaggerMessage'
+        type: array
+      model:
+        example: grok-chat-expert
+        type: string
+      stream:
+        example: false
+        type: boolean
+    type: object
+  httpserver.SwaggerResponsesRequest:
+    properties:
+      input: {}
+      model:
+        example: grok-chat-auto
+        type: string
+      previous_response_id:
+        type: string
+      prompt_cache_key:
+        type: string
+      store:
+        example: false
+        type: boolean
+      stream:
+        example: false
+        type: boolean
+    type: object
+  httpserver.SwaggerVideoGenerationRequest:
+    properties:
+      aspect_ratio:
+        example: "16:9"
+        type: string
+      duration:
+        example: 8
+        type: integer
+      model:
+        example: grok-imagine-video
+        type: string
+      prompt:
+        example: A cinematic tracking shot in the rain
+        type: string
+      resolution:
+        example: 720p
+        type: string
+    type: object
+info:
+  contact: {}
+  description: Grok Build 与 Grok Web 多账号 API 网关。
+  title: Grok2API
+  version: "1.0"
+paths:
+  /healthz:
+    get:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties:
+              type: boolean
+            type: object
+      summary: 存活检查
+      tags:
+      - System
+  /readyz:
+    get:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties:
+              type: boolean
+            type: object
+        "503":
+          description: Service Unavailable
+          schema:
+            additionalProperties:
+              type: boolean
+            type: object
+      summary: 就绪检查
+      tags:
+      - System
+  /v1/chat/completions:
+    post:
+      consumes:
+      - application/json
+      description: 支持 JSON 与 SSE、图片输入和函数工具。
+      parameters:
+      - description: 请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/httpserver.SwaggerChatRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 创建 Chat Completion
+      tags:
+      - Chat
+  /v1/images/edits:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: 请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/httpserver.SwaggerImageEditRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 编辑图片
+      tags:
+      - Images
+  /v1/images/generations:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: 请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/httpserver.SwaggerImageGenerationRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 生成图片
+      tags:
+      - Images
+  /v1/media/images/{asset_id}:
+    get:
+      parameters:
+      - description: Asset ID
+        in: path
+        name: asset_id
+        required: true
+        type: string
+      produces:
+      - image/png
+      responses:
+        "200":
+          description: OK
+          schema:
+            type: file
+        "404":
+          description: Not Found
+      summary: 获取归档图片
+      tags:
+      - Images
+  /v1/messages:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - default: "2023-06-01"
+        description: Anthropic API version
+        in: header
+        name: anthropic-version
+        required: true
+        type: string
+      - description: 请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/httpserver.SwaggerMessagesRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 创建 Anthropic Message
+      tags:
+      - Messages
+  /v1/models:
+    get:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "401":
+          description: Unauthorized
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 获取可用模型
+      tags:
+      - Models
+  /v1/responses:
+    post:
+      consumes:
+      - application/json
+      description: 支持 JSON 与 SSE；stream=true 时返回 text/event-stream。
+      parameters:
+      - description: 请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/httpserver.SwaggerResponsesRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+        "401":
+          description: Unauthorized
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 创建 Response
+      tags:
+      - Responses
+  /v1/responses/{response_id}:
+    delete:
+      parameters:
+      - description: Response ID
+        in: path
+        name: response_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "404":
+          description: Not Found
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 删除 Response
+      tags:
+      - Responses
+    get:
+      parameters:
+      - description: Response ID
+        in: path
+        name: response_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "404":
+          description: Not Found
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 查询 Response
+      tags:
+      - Responses
+  /v1/responses/compact:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: 请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/httpserver.SwaggerResponsesRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 压缩 Response 上下文
+      tags:
+      - Responses
+  /v1/videos/{request_id}:
+    get:
+      parameters:
+      - description: Request ID
+        in: path
+        name: request_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "404":
+          description: Not Found
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 查询异步视频任务
+      tags:
+      - Videos
+  /v1/videos/generations:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: 请求
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/httpserver.SwaggerVideoGenerationRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties: true
+            type: object
+      security:
+      - BearerAuth: []
+      summary: 创建异步视频任务
+      tags:
+      - Videos
+securityDefinitions:
+  BearerAuth:
+    description: 使用 "Bearer g2a_xxx_xxx"。
+    in: header
+    name: Authorization
+    type: apiKey
+swagger: "2.0"

backend/go.mod

@@ -0,0 +1,87 @@
+module github.com/chenyme/grok2api/backend
+
+go 1.26
+
+require (
+	github.com/bdandy/go-socks4 v1.2.3
+	github.com/bogdanfinn/fhttp v0.6.8
+	github.com/bogdanfinn/tls-client v1.15.1
+	github.com/bogdanfinn/websocket v1.5.5-barnius
+	github.com/gin-gonic/gin v1.12.0
+	github.com/glebarez/sqlite v1.11.0
+	github.com/golang-jwt/jwt/v5 v5.3.1
+	github.com/google/uuid v1.6.0
+	github.com/redis/go-redis/v9 v9.21.0
+	github.com/swaggo/files v1.0.1
+	github.com/swaggo/gin-swagger v1.6.1
+	github.com/swaggo/swag v1.16.6
+	golang.org/x/crypto v0.54.0
+	golang.org/x/net v0.56.0
+	golang.org/x/sync v0.22.0
+	google.golang.org/protobuf v1.36.10
+	gopkg.in/yaml.v3 v3.0.1
+	gorm.io/driver/postgres v1.6.0
+	gorm.io/gorm v1.31.2
+)
+
+require (
+	github.com/KyleBanks/depth v1.2.1 // indirect
+	github.com/PuerkitoBio/purell v1.1.1 // indirect
+	github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
+	github.com/andybalholm/brotli v1.2.0 // indirect
+	github.com/bdandy/go-errors v1.2.2 // indirect
+	github.com/bogdanfinn/quic-go-utls v1.0.9-utls // indirect
+	github.com/bogdanfinn/utls v1.7.7-barnius // indirect
+	github.com/bytedance/gopkg v0.1.3 // indirect
+	github.com/bytedance/sonic v1.15.0 // indirect
+	github.com/bytedance/sonic/loader v0.5.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/cloudwego/base64x v0.1.6 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
+	github.com/gin-contrib/sse v1.1.0 // indirect
+	github.com/glebarez/go-sqlite v1.21.2 // indirect
+	github.com/go-openapi/jsonpointer v0.19.5 // indirect
+	github.com/go-openapi/jsonreference v0.19.6 // indirect
+	github.com/go-openapi/spec v0.20.4 // indirect
+	github.com/go-openapi/swag v0.19.15 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.30.1 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
+	github.com/goccy/go-yaml v1.19.2 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/pgx/v5 v5.6.0 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/compress v1.18.2 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mailru/easyjson v0.7.6 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/quic-go/qpack v0.6.0 // indirect
+	github.com/quic-go/quic-go v0.59.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/tam7t/hpkp v0.0.0-20160821193359-2b70b4024ed5 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.3.1 // indirect
+	go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	golang.org/x/arch v0.22.0 // indirect
+	golang.org/x/mod v0.37.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
+	golang.org/x/tools v0.47.0 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	modernc.org/libc v1.22.5 // indirect
+	modernc.org/mathutil v1.5.0 // indirect
+	modernc.org/memory v1.5.0 // indirect
+	modernc.org/sqlite v1.23.1 // indirect
+)

backend/go.sum

@@ -0,0 +1,255 @@
+github.com/KyleBanks/depth v1.2.1 h1:5h8fQADFrWtarTdtDudMmGsC7GPbOAu6RVB3ffsVFHc=
+github.com/KyleBanks/depth v1.2.1/go.mod h1:jzSb9d0L43HxTQfT+oSA1EEp2q+ne2uh6XgeJcm8brE=
+github.com/PuerkitoBio/purell v1.1.1 h1:WEQqlqaGbrPkxLJWfBwQmfEAE1Z7ONdDLqrN38tNFfI=
+github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
+github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 h1:d+Bc7a5rLufV/sSk/8dngufqelfh6jnri85riMAaF/M=
+github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE=
+github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/bdandy/go-errors v1.2.2 h1:WdFv/oukjTJCLa79UfkGmwX7ZxONAihKu4V0mLIs11Q=
+github.com/bdandy/go-errors v1.2.2/go.mod h1:NkYHl4Fey9oRRdbB1CoC6e84tuqQHiqrOcZpqFEkBxM=
+github.com/bdandy/go-socks4 v1.2.3 h1:Q6Y2heY1GRjCtHbmlKfnwrKVU/k81LS8mRGLRlmDlic=
+github.com/bdandy/go-socks4 v1.2.3/go.mod h1:98kiVFgpdogR8aIGLWLvjDVZ8XcKPsSI/ypGrO+bqHI=
+github.com/bogdanfinn/fhttp v0.6.8 h1:LiQyHOY3i0QoxxNB7nq27/nGNNbtPj0fuBPozhR7Ws4=
+github.com/bogdanfinn/fhttp v0.6.8/go.mod h1:A+EKDzMx2hb4IUbMx4TlkoHnaJEiLl8r/1Ss1Y+5e5M=
+github.com/bogdanfinn/quic-go-utls v1.0.9-utls h1:tV6eDEiRbRCcepALSzxR94JUVD3N3ACIiRLgyc2Ep8s=
+github.com/bogdanfinn/quic-go-utls v1.0.9-utls/go.mod h1:aHph9B9H9yPOt5xnhWKSOum27DJAqpiHzwX+gjvaXcg=
+github.com/bogdanfinn/tls-client v1.15.1 h1:KiFAlED55DJ8Fcocn+/1nX6PrDFcttIHAf/GDkV6KN8=
+github.com/bogdanfinn/tls-client v1.15.1/go.mod h1:LsU6mXVn8MOFDwTkyRfI7V1BZM1p0wf2ZfZsICW/1fM=
+github.com/bogdanfinn/utls v1.7.7-barnius h1:OuJ497cc7F3yKNVHRsYPQdGggmk5x6+V5ZlrCR7fOLU=
+github.com/bogdanfinn/utls v1.7.7-barnius/go.mod h1:aAK1VZQlpKZClF1WEQeq6kyclbkPq4hz6xTbB5xSlmg=
+github.com/bogdanfinn/websocket v1.5.5-barnius h1:bY+qnxpai1qe7Jmjx+Sds/cmOSpuuLoR8x61rWltjOI=
+github.com/bogdanfinn/websocket v1.5.5-barnius/go.mod h1:gvvEw6pTKHb7yOiFvIfAFTStQWyrm25BMVCTj5wRSsI=
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
+github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
+github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
+github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
+github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
+github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
+github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
+github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
+github.com/gin-contrib/gzip v0.0.6 h1:NjcunTcGAj5CO1gn4N8jHOSIeRFHIbn51z6K+xaN4d4=
+github.com/gin-contrib/gzip v0.0.6/go.mod h1:QOJlmV2xmayAjkNS2Y8NQsMneuRShOU/kjovCXNuzzk=
+github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
+github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
+github.com/gin-gonic/gin v1.12.0 h1:b3YAbrZtnf8N//yjKeU2+MQsh2mY5htkZidOM7O0wG8=
+github.com/gin-gonic/gin v1.12.0/go.mod h1:VxccKfsSllpKshkBWgVgRniFFAzFb9csfngsqANjnLc=
+github.com/glebarez/go-sqlite v1.21.2 h1:3a6LFC4sKahUunAmynQKLZceZCOzUthkRkEAl9gAXWo=
+github.com/glebarez/go-sqlite v1.21.2/go.mod h1:sfxdZyhQjTM2Wry3gVYWaW072Ri1WMdWJi0k6+3382k=
+github.com/glebarez/sqlite v1.11.0 h1:wSG0irqzP6VurnMEpFGer5Li19RpIRi2qvQz++w0GMw=
+github.com/glebarez/sqlite v1.11.0/go.mod h1:h8/o8j5wiAsqSPoWELDUdJXhjAhsVliSn7bWZjOhrgQ=
+github.com/go-openapi/jsonpointer v0.19.3/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
+github.com/go-openapi/jsonpointer v0.19.5 h1:gZr+CIYByUqjcgeLXnQu2gHYQC9o73G2XUeOFYEICuY=
+github.com/go-openapi/jsonpointer v0.19.5/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
+github.com/go-openapi/jsonreference v0.19.6 h1:UBIxjkht+AWIgYzCDSv2GN+E/togfwXUJFRTWhl2Jjs=
+github.com/go-openapi/jsonreference v0.19.6/go.mod h1:diGHMEHg2IqXZGKxqyvWdfWU/aim5Dprw5bqpKkTvns=
+github.com/go-openapi/spec v0.20.4 h1:O8hJrt0UMnhHcluhIdUgCLRWyM2x7QkBXRvOs7m+O1M=
+github.com/go-openapi/spec v0.20.4/go.mod h1:faYFR1CvsJZ0mNsmsphTMSoRrNV3TEDoAM7FOEWeq8I=
+github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk=
+github.com/go-openapi/swag v0.19.15 h1:D2NRCBzS9/pEY3gP9Nl8aDqGUcPFrwG2p+CNFrLyrCM=
+github.com/go-openapi/swag v0.19.15/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
+github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
+github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
+github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
+github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/pprof v0.0.0-20221118152302-e6195bd50e26 h1:Xim43kblpZXfIBQsbuBVKCudVG457BR2GZFIz3uw3hQ=
+github.com/google/pprof v0.0.0-20221118152302-e6195bd50e26/go.mod h1:dDKJzRmX4S37WGHujM7tX//fmj1uioxKzKxz3lo4HJo=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.6.0 h1:SWJzexBzPL5jb0GEsrPMLIsi/3jOo7RHlzTjcAeDrPY=
+github.com/jackc/pgx/v5 v5.6.0/go.mod h1:DNZ/vlrUnhWCoFGxHAG8U2ljioxukquj7utPDgtQdTw=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/compress v1.18.2 h1:iiPHWW0YrcFgpBYhsA6D1+fqHssJscY/Tm/y2Uqnapk=
+github.com/klauspost/compress v1.18.2/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mailru/easyjson v0.0.0-20190614124828-94de47d64c63/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
+github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
+github.com/mailru/easyjson v0.7.6 h1:8yTIVnZgCoiM1TgqoeTl+LfU5Jg6/xL3QhGQnimLYnA=
+github.com/mailru/easyjson v0.7.6/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
+github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
+github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
+github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SAw=
+github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
+github.com/redis/go-redis/v9 v9.21.0 h1:FPBE4hhbAke+TLmcY3WkpbDffJEomdqPn3HYiqAtL9E=
+github.com/redis/go-redis/v9 v9.21.0/go.mod h1:v/M13XI1PVCDcm01VtPFOADfZtHf8YW3baQf57KlIkA=
+github.com/remyoudompheng/bigfft v0.0.0-20200410134404-eec4a21b6bb0/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/swaggo/files v1.0.1 h1:J1bVJ4XHZNq0I46UU90611i9/YzdrF7x92oX1ig5IdE=
+github.com/swaggo/files v1.0.1/go.mod h1:0qXmMNH6sXNf+73t65aKeB+ApmgxdnkQzVTAj2uaMUg=
+github.com/swaggo/gin-swagger v1.6.1 h1:Ri06G4gc9N4t4k8hekMigJ9zKTFSlqj/9paAQCQs7cY=
+github.com/swaggo/gin-swagger v1.6.1/go.mod h1:LQ+hJStHakCWRiK/YNYtJOu4mR2FP+pxLnILT/qNiTw=
+github.com/swaggo/swag v1.16.6 h1:qBNcx53ZaX+M5dxVyTrgQ0PJ/ACK+NzhwcbieTt+9yI=
+github.com/swaggo/swag v1.16.6/go.mod h1:ngP2etMK5a0P3QBizic5MEwpRmluJZPHjXcMoj4Xesg=
+github.com/tam7t/hpkp v0.0.0-20160821193359-2b70b4024ed5 h1:YqAladjX7xpA6BM04leXMWAEjS0mTZ5kUU9KRBriQJc=
+github.com/tam7t/hpkp v0.0.0-20160821193359-2b70b4024ed5/go.mod h1:2JjD2zLQYH5HO74y5+aE3remJQvl6q4Sn6aWA2wD1Ng=
+github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
+github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
+github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
+github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
+go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
+go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
+go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
+golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
+golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
+golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
+golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM=
+golang.org/x/net v0.0.0-20211104170005-ce137452f963/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
+golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210420072515-93ed5bcd2bfe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
+golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
+golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
+golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
+google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/postgres v1.6.0 h1:2dxzU8xJ+ivvqTRph34QX+WrRaJlmfyPqXmoGVjMBa4=
+gorm.io/driver/postgres v1.6.0/go.mod h1:vUw0mrGgrTK+uPHEhAdV4sfFELrByKVGnaVRkXDhtWo=
+gorm.io/driver/sqlite v1.6.0 h1:WHRRrIiulaPiPFmDcod6prc4l2VGVWHz80KspNsxSfQ=
+gorm.io/driver/sqlite v1.6.0/go.mod h1:AO9V1qIQddBESngQUKWL9yoH93HIeA1X6V633rBwyT8=
+gorm.io/gorm v1.31.2 h1:3o8FXNo9v9S858gil+3LlZA1LkCOzgb4g5BL64FgaCo=
+gorm.io/gorm v1.31.2/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=
+modernc.org/libc v1.22.5 h1:91BNch/e5B0uPbJFgqbxXuOnxBQjlS//icfQEGmvyjE=
+modernc.org/libc v1.22.5/go.mod h1:jj+Z7dTNX8fBScMVNRAYZ/jF91K8fdT2hYMThc3YjBY=
+modernc.org/mathutil v1.5.0 h1:rV0Ko/6SfM+8G+yKiyI830l3Wuz1zRutdslNoQ0kfiQ=
+modernc.org/mathutil v1.5.0/go.mod h1:mZW8CKdRPY1v87qxC/wUdX5O1qDzXMP5TH3wjfpga6E=
+modernc.org/memory v1.5.0 h1:N+/8c5rE6EqugZwHii4IFsaJ7MUhoWX07J5tC/iI5Ds=
+modernc.org/memory v1.5.0/go.mod h1:PkUhL0Mugw21sHPeskwZW4D6VscE/GQJOnIpCnW6pSU=
+modernc.org/sqlite v1.23.1 h1:nrSBg4aRQQwq59JpvGEQ15tNxoO5pX/kUjcRNwSAGQM=
+modernc.org/sqlite v1.23.1/go.mod h1:OrDj17Mggn6MhE+iPbBNf7RGKODDE9NFT0f3EwDzJqk=

backend/internal/app/application.go

@@ -0,0 +1,764 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	accountapp "github.com/chenyme/grok2api/backend/internal/application/account"
+	accountsyncapp "github.com/chenyme/grok2api/backend/internal/application/accountsync"
+	"github.com/chenyme/grok2api/backend/internal/application/adminauth"
+	auditapp "github.com/chenyme/grok2api/backend/internal/application/audit"
+	clientkeyapp "github.com/chenyme/grok2api/backend/internal/application/clientkey"
+	dashboardapp "github.com/chenyme/grok2api/backend/internal/application/dashboard"
+	egressapp "github.com/chenyme/grok2api/backend/internal/application/egress"
+	"github.com/chenyme/grok2api/backend/internal/application/gateway"
+	invalidationapp "github.com/chenyme/grok2api/backend/internal/application/invalidation"
+	mediaapp "github.com/chenyme/grok2api/backend/internal/application/media"
+	modelapp "github.com/chenyme/grok2api/backend/internal/application/model"
+	quotarecoveryapp "github.com/chenyme/grok2api/backend/internal/application/quotarecovery"
+	settingsapp "github.com/chenyme/grok2api/backend/internal/application/settings"
+	updatecheckapp "github.com/chenyme/grok2api/backend/internal/application/updatecheck"
+	"github.com/chenyme/grok2api/backend/internal/buildinfo"
+	"github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/config"
+	infraegress "github.com/chenyme/grok2api/backend/internal/infra/egress"
+	inframedia "github.com/chenyme/grok2api/backend/internal/infra/media"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	cliprovider "github.com/chenyme/grok2api/backend/internal/infra/provider/cli"
+	consoleprovider "github.com/chenyme/grok2api/backend/internal/infra/provider/console"
+	webprovider "github.com/chenyme/grok2api/backend/internal/infra/provider/web"
+	"github.com/chenyme/grok2api/backend/internal/infra/runtime/memory"
+	redisruntime "github.com/chenyme/grok2api/backend/internal/infra/runtime/redis"
+	"github.com/chenyme/grok2api/backend/internal/infra/security"
+	"github.com/chenyme/grok2api/backend/internal/pkg/batch"
+	"github.com/chenyme/grok2api/backend/internal/pkg/perfmetrics"
+	"github.com/chenyme/grok2api/backend/internal/pkg/reasoningreplay"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+	httpserver "github.com/chenyme/grok2api/backend/internal/transport/http"
+	httpmiddleware "github.com/chenyme/grok2api/backend/internal/transport/http/middleware"
+)
+
+const (
+	responseOwnershipCleanupBatchSize = 1000
+	webResponseStateCleanupBatchSize  = 50
+	responseCleanupMaxBatches         = 100
+	responseCleanupInterval           = 5 * time.Minute
+	responseCleanupBudget             = 30 * time.Second
+	responseCleanupLockTTL            = 2 * time.Minute
+)
+
+// Application 管理后端进程生命周期和本地后台任务。
+type Application struct {
+	logger          *slog.Logger
+	database        *relational.Database
+	server          *http.Server
+	audits          *auditapp.Service
+	responses       repository.ResponseRepository
+	cleanupLock     repository.DistributedLock
+	runtime         io.Closer
+	settingsBus     repository.SettingsChangeBus
+	invalidationBus repository.InvalidationBus
+	settings        *settingsapp.Service
+	gateway         *gateway.Service
+	media           *mediaapp.Service
+	quotaRecovery   *quotarecoveryapp.Service
+	accounts        *accountapp.Service
+	models          *modelapp.Service
+	clientKeys      *clientkeyapp.Service
+	updates         *updatecheckapp.Service
+	invalidations   *invalidationapp.Service
+	accountRepo     repository.AccountRepository
+	modelRepo       repository.ModelRepository
+	providers       *provider.Registry
+	web             *webprovider.Adapter
+	egress          *infraegress.Manager
+	egressOps       *egressapp.Service
+	startup         *startupState
+}
+
+// New 完成数据库、Provider、应用服务和 HTTP 路由装配。
+func New(ctx context.Context, cfg config.Config, logger *slog.Logger) (*Application, error) {
+	var database *relational.Database
+	var err error
+	switch cfg.Database.Driver {
+	case "sqlite":
+		database, err = relational.OpenSQLite(ctx, cfg.Database.SQLite.Path)
+	case "postgres":
+		database, err = relational.OpenPostgres(ctx, cfg.Database.Postgres.DSN, cfg.Database.Postgres.MaxOpenConns, cfg.Database.Postgres.MaxIdleConns)
+	default:
+		return nil, fmt.Errorf("不支持的数据库驱动: %s", cfg.Database.Driver)
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := database.InitializeSchema(ctx); err != nil {
+		database.Close()
+		return nil, err
+	}
+	cipher, err := security.NewCipher(cfg.Secrets.CredentialEncryptionKey)
+	if err != nil {
+		database.Close()
+		return nil, err
+	}
+
+	adminRepo := relational.NewAdminRepository(database)
+	sessionRepo := relational.NewAdminSessionRepository(database)
+	accountRepo := relational.NewAccountRepository(database)
+	modelRepo := relational.NewModelRepository(database)
+	clientKeyRepo := relational.NewClientKeyRepository(database)
+	auditRepo := relational.NewAuditRepository(database)
+	responseRepo := relational.NewResponseRepository(database)
+	dashboardRepo := relational.NewDashboardRepository(database)
+	runtimeSettingsRepo := relational.NewRuntimeSettingsRepository(database, cipher)
+	egressRepo := relational.NewEgressRepository(database)
+	mediaJobRepo := relational.NewMediaJobRepository(database)
+	mediaAssetRepo := relational.NewMediaAssetRepository(database)
+	mediaUploadTicketRepo := relational.NewMediaUploadTicketRepository(database)
+	loadedConfig, settingsUpdatedAt, settingsRevision, err := settingsapp.LoadPersisted(ctx, cfg, runtimeSettingsRepo)
+	if err != nil {
+		database.Close()
+		return nil, err
+	}
+	cfg = loadedConfig
+	localMediaStore, err := inframedia.NewLocalStore(cfg.Media.Local.Path)
+	if err != nil {
+		database.Close()
+		return nil, err
+	}
+	if err := preflightDeployment(cfg); err != nil {
+		database.Close()
+		return nil, err
+	}
+	var rateLimiter repository.RateLimiter
+	var concurrency repository.ConcurrencyLimiter
+	var sticky repository.StickySessionRepository
+	var reasoningReplayStore repository.ReasoningReplayRepository
+	var deviceSessions repository.DeviceSessionRepository
+	var refreshLock repository.DistributedLock
+	var settingsBus repository.SettingsChangeBus
+	var quotaQueue repository.QuotaRecoveryQueue
+	var quotaRefreshState repository.QuotaRefreshCoordinator
+	var observedModelStore repository.ObservedModelStateRepository
+	var invalidationBus repository.InvalidationBus
+	var runtimeStore io.Closer
+	runtimeHealth := func(context.Context) error { return nil }
+	switch cfg.RuntimeStore.Driver {
+	case "redis":
+		redisStore, openErr := redisruntime.Open(ctx, redisruntime.Config{
+			Address: cfg.RuntimeStore.Redis.Address, Username: cfg.RuntimeStore.Redis.Username,
+			Password: cfg.RuntimeStore.Redis.Password, Database: cfg.RuntimeStore.Redis.Database,
+			KeyPrefix: cfg.RuntimeStore.Redis.KeyPrefix, TLS: cfg.RuntimeStore.Redis.TLS,
+			ConcurrencyLease: cfg.Server.RequestTimeout.Value() + time.Minute,
+		})
+		if openErr != nil {
+			database.Close()
+			return nil, openErr
+		}
+		runtimeStore = redisStore
+		invalidationBus = redisStore
+		runtimeHealth = redisStore.Ping
+		rateLimiter = redisStore
+		concurrency = redisruntime.NewConcurrencyLimiter(redisStore)
+		sticky = redisStore
+		reasoningReplayStore = redisruntime.NewReasoningReplayStore(redisStore)
+		deviceSessions = redisruntime.NewDeviceSessionStore(redisStore)
+		refreshLock = redisruntime.NewLockStore(redisStore)
+		settingsBus = redisStore
+		quotaQueue = redisStore
+		quotaRefreshState = redisStore
+		observedModelStore = redisStore
+	case "memory":
+		rateLimiter = memory.NewRateLimiter()
+		concurrency = memory.NewConcurrencyLimiter()
+		sticky = memory.NewStickyStore()
+		reasoningReplayStore = memory.NewReasoningReplayStore(cfg.Routing.ReasoningReplayMaxEntries)
+		deviceSessions = memory.NewDeviceSessionStore()
+		refreshLock = memory.NewLockStore()
+		quotaQueue = memory.NewQuotaRecoveryQueue()
+		quotaRefreshState = memory.NewQuotaRefreshCoordinator()
+	default:
+		database.Close()
+		return nil, fmt.Errorf("不支持的运行态驱动: %s", cfg.RuntimeStore.Driver)
+	}
+	logger.Info("deployment_topology", "replicas", cfg.Deployment.Replicas, "instance_id", cfg.Deployment.InstanceID, "cluster_id", cfg.Deployment.ClusterID, "database", cfg.Database.Driver, "runtime_store", cfg.RuntimeStore.Driver, "media_driver", cfg.Media.Driver, "shared_media", cfg.Deployment.SharedMedia)
+	mediaService := mediaapp.NewServiceWithTickets(mediaAssetRepo, mediaJobRepo, mediaUploadTicketRepo, localMediaStore, refreshLock, mediaConfig(cfg))
+
+	egressManager := infraegress.NewManager(egressRepo, cipher)
+	egressManager.SetLogger(logger)
+	egressManager.SetClearanceLock(refreshLock)
+	egressManager.UpdateClearanceConfig(clearanceConfig(cfg))
+	egressManager.UpdateBuildResponseHeaderTimeout(cfg.Provider.Build.ResponseHeaderTimeout.Value())
+	cliAdapter := cliprovider.NewAdapter(cliprovider.Config{
+		BaseURL: cfg.Provider.Build.BaseURL, FallbackBaseURL: config.NormalizeBuildFallbackBaseURL(cfg.Provider.Build.FallbackBaseURL),
+		ClientVersion: cfg.Provider.Build.ClientVersion, ClientIdentifier: cfg.Provider.Build.ClientIdentifier,
+		TokenAuth: cfg.Provider.Build.TokenAuth, UserAgent: cfg.Provider.Build.UserAgent,
+		ResponseHeaderTimeout: cfg.Provider.Build.ResponseHeaderTimeout.Value(),
+	}, cipher)
+	cliAdapter.SetLogger(logger)
+	cliAdapter.SetEgress(egressManager)
+	cliAdapter.SetVideoUploadIssuer(mediaService)
+	reasoningReplay := reasoningreplay.New(reasoningReplayStore, reasoningreplay.Config{
+		Enabled: cfg.Routing.ReasoningReplayEnabled,
+		TTL:     cfg.Routing.ReasoningReplayTTL.Value(),
+	}, logger)
+	cliAdapter.SetReasoningReplay(reasoningReplay)
+	webAdapter := webprovider.NewAdapter(webProviderConfig(cfg), egressManager, cipher, responseRepo, mediaService)
+	webAdapter.SetLogger(logger)
+	consoleAdapter := consoleprovider.NewAdapter(consoleProviderConfig(cfg), egressManager, cipher)
+	providers := provider.NewRegistry(cliAdapter, webAdapter, consoleAdapter)
+	if err := providers.Validate(); err != nil {
+		if runtimeStore != nil {
+			_ = runtimeStore.Close()
+		}
+		database.Close()
+		return nil, fmt.Errorf("校验 Provider 注册表: %w", err)
+	}
+	adminService := adminauth.NewService(adminRepo, sessionRepo, security.NewTokenService(cfg.Secrets.JWTSecret), cfg.Auth.AccessTokenTTL.Value(), cfg.Auth.RefreshTokenTTL.Value())
+	adminService.SetLoginRateLimiter(rateLimiter)
+	if err := adminService.Bootstrap(ctx, cfg.BootstrapAdmin.Username, cfg.BootstrapAdmin.Password); err != nil {
+		if runtimeStore != nil {
+			_ = runtimeStore.Close()
+		}
+		database.Close()
+		return nil, err
+	}
+	bulkPool := batch.NewSharedPool(maxBatchConcurrency(cfg.Batch), concurrency, "bulk:upstream")
+	importPool := batch.NewSharedChildPool(cfg.Batch.ImportConcurrency, concurrency, "bulk:import", bulkPool)
+	conversionPool := batch.NewSharedChildPool(cfg.Batch.ConversionConcurrency, concurrency, "bulk:conversion", bulkPool)
+	syncPool := batch.NewSharedChildPool(cfg.Batch.SyncConcurrency, concurrency, "bulk:sync", bulkPool)
+	refreshPool := batch.NewSharedChildPool(cfg.Batch.RefreshConcurrency, concurrency, "bulk:refresh", bulkPool)
+	for _, pool := range []*batch.Pool{importPool, conversionPool, syncPool, refreshPool} {
+		pool.UpdateJitter(cfg.Batch.RandomDelay.Value())
+	}
+	accountService := accountapp.NewService(accountRepo, auditRepo, deviceSessions, sticky, providers, cipher, refreshLock)
+	cliAdapter.SetFallbackMarker(accountService)
+	accountService.SetLogger(logger)
+	accountService.UpdateAutoCleanConfig(accountAutoCleanConfig(cfg.Accounts))
+	accountService.SetConcurrencyLimiter(concurrency)
+	accountService.SetQuotaRecoveryQueue(quotaQueue)
+	accountService.SetQuotaRefreshCoordinator(quotaRefreshState)
+	accountService.SetObservedModelStore(observedModelStore)
+	accountService.SetTaskPools(conversionPool, syncPool, refreshPool)
+	windows, err := accountRepo.ListQuotaRecoveryWindows(ctx, 100000)
+	if err != nil {
+		if runtimeStore != nil {
+			_ = runtimeStore.Close()
+		}
+		database.Close()
+		return nil, fmt.Errorf("加载 Web 额度恢复事件: %w", err)
+	}
+	for _, window := range windows {
+		if window.ResetAt != nil {
+			if err := quotaQueue.ScheduleQuotaRecovery(ctx, account.QuotaRecoveryEvent{AccountID: window.AccountID, Mode: window.Mode, DueAt: *window.ResetAt}); err != nil {
+				if runtimeStore != nil {
+					_ = runtimeStore.Close()
+				}
+				database.Close()
+				return nil, fmt.Errorf("恢复 Web 额度事件: %w", err)
+			}
+		}
+	}
+	modelService := modelapp.NewService(modelRepo, accountRepo, accountService, providers)
+	modelService.SetBulkPool(syncPool)
+	modelService.SetLogger(logger)
+	if err := modelRepo.ReplaceProviderRoutes(ctx, account.ProviderWeb, webprovider.Routes()); err != nil {
+		if runtimeStore != nil {
+			_ = runtimeStore.Close()
+		}
+		database.Close()
+		return nil, fmt.Errorf("初始化 Grok Web 模型目录: %w", err)
+	}
+	if err := modelRepo.ReplaceProviderRoutes(ctx, account.ProviderConsole, consoleprovider.Routes()); err != nil {
+		if runtimeStore != nil {
+			_ = runtimeStore.Close()
+		}
+		database.Close()
+		return nil, fmt.Errorf("初始化 Grok Console 模型目录: %w", err)
+	}
+	accountSyncService := accountsyncapp.NewService(logger, accountService, accountService, accountService, modelService)
+	accountSyncService.SetBulkPool(importPool)
+	accountSyncService.UpdateConcurrency(cfg.Batch.ImportConcurrency)
+	egressService := egressapp.NewService(egressRepo, cipher, infraegress.DefaultUserAgent, accountRepo)
+	egressService.SetClearanceManager(egressManager)
+	egressService.SetNodeProber(egressManager)
+	egressService.SetOperationsConfigInvalidator(egressManager)
+	clientKeyService := clientkeyapp.NewService(clientKeyRepo, rateLimiter, concurrency, cfg.ClientKeyDefaults.RPMLimit, cfg.ClientKeyDefaults.MaxConcurrent, cipher)
+	auditService := auditapp.NewService(auditRepo, logger, cfg.Audit.BufferSize, cfg.Audit.BatchSize, cfg.Audit.FlushInterval.Value())
+	auditService.UpdateWriterConfig(cfg.Audit.BatchSize, cfg.Audit.FlushInterval.Value(), cfg.Audit.CommitDelay.Value())
+	auditService.UpdateLedgerConfig(auditLedgerConfig(cfg.Audit))
+	auditService.SetCommitObserver(clientKeyService.CompleteBillingBatch)
+	auditService.SetDropObserver(clientKeyService.ReleaseBillingProtectionBatch)
+	dashboardService := dashboardapp.NewService(dashboardRepo)
+	selector := gateway.NewSelector(accountRepo, concurrency, sticky, providers, cfg.Routing.StickyTTL.Value(), cfg.Routing.CooldownBase.Value(), cfg.Routing.CooldownMax.Value(), cfg.Routing.CapacityWait.Value())
+	selector.UpdatePreferFreeBuild(cfg.Routing.PreferFreeBuild)
+	selector.UpdateSegmentedSelector(cfg.Routing.SegmentedSelectorEnabled, cfg.Routing.SegmentedMinCandidates, cfg.Routing.SegmentedWindowSize)
+	invalidationService := invalidationapp.NewService(invalidationBus, invalidationSourceInstance(cfg), func(event repository.InvalidationEvent) {
+		selector.ApplyInvalidation(event)
+		clientKeyService.ApplyInvalidation(event)
+	}, logger)
+	accountRepo.SetInvalidationObserver(invalidationService.Notify)
+	modelRepo.SetInvalidationObserver(invalidationService.Notify)
+	clientKeyRepo.SetInvalidationObserver(invalidationService.Notify)
+	gatewayService := gateway.NewService(modelService, auditService, accountService, clientKeyService, providers, selector, responseRepo, cfg.Routing.MaxAttempts)
+	gatewayService.SetLogger(logger)
+	gatewayService.UpdateBuildForbiddenReauthPolicy(cfg.Accounts.MarkBuildForbiddenReauth, cfg.Accounts.BuildForbiddenReauthCodes)
+	gatewayService.UpdateRequestTimeout(cfg.Server.RequestTimeout.Value())
+	gatewayService.ConfigureMedia(mediaJobRepo, cfg.Provider.Web.MediaConcurrency)
+	gatewayService.ConfigureMediaAssets(mediaService)
+	quotaRecoveryService := quotarecoveryapp.NewService(logger, quotaQueue, accountService, cfg.Provider.Web.RecoveryBackoffBase.Value(), cfg.Provider.Web.RecoveryBackoffMax.Value())
+	quotaRecoveryService.SetBulkPool(syncPool)
+	inferenceConcurrency := httpmiddleware.NewConcurrencyGate(cfg.Server.MaxConcurrentRequests)
+	var notifySettings func(context.Context)
+	if settingsBus != nil {
+		notifySettings = func(notifyCtx context.Context) {
+			publishCtx, cancel := context.WithTimeout(context.WithoutCancel(notifyCtx), 3*time.Second)
+			defer cancel()
+			if err := settingsBus.PublishSettingsChanged(publishCtx); err != nil {
+				logger.Warn("settings_change_publish_failed", "error", err)
+			}
+		}
+	}
+	settingsService := settingsapp.NewService(cfg, settingsUpdatedAt, settingsRevision, runtimeSettingsRepo, notifySettings, func(next config.Config) {
+		inferenceConcurrency.UpdateLimit(next.Server.MaxConcurrentRequests)
+		bulkPool.UpdateLimit(maxBatchConcurrency(next.Batch))
+		importPool.UpdateLimit(next.Batch.ImportConcurrency)
+		conversionPool.UpdateLimit(next.Batch.ConversionConcurrency)
+		syncPool.UpdateLimit(next.Batch.SyncConcurrency)
+		refreshPool.UpdateLimit(next.Batch.RefreshConcurrency)
+		for _, pool := range []*batch.Pool{importPool, conversionPool, syncPool, refreshPool} {
+			pool.UpdateJitter(next.Batch.RandomDelay.Value())
+		}
+		cliAdapter.UpdateConfig(cliprovider.Config{
+			BaseURL: next.Provider.Build.BaseURL, FallbackBaseURL: config.NormalizeBuildFallbackBaseURL(next.Provider.Build.FallbackBaseURL),
+			ClientVersion: next.Provider.Build.ClientVersion, ClientIdentifier: next.Provider.Build.ClientIdentifier,
+			TokenAuth: next.Provider.Build.TokenAuth, UserAgent: next.Provider.Build.UserAgent,
+			ResponseHeaderTimeout: next.Provider.Build.ResponseHeaderTimeout.Value(),
+		})
+		egressManager.UpdateBuildResponseHeaderTimeout(next.Provider.Build.ResponseHeaderTimeout.Value())
+		webAdapter.UpdateConfig(webProviderConfig(next))
+		egressManager.UpdateClearanceConfig(clearanceConfig(next))
+		consoleAdapter.UpdateConfig(consoleProviderConfig(next))
+		mediaService.UpdateConfig(mediaConfig(next))
+		quotaRecoveryService.UpdateConfig(next.Provider.Web.RecoveryBackoffBase.Value(), next.Provider.Web.RecoveryBackoffMax.Value())
+		accountSyncService.UpdateConcurrency(next.Batch.ImportConcurrency)
+		selector.UpdateConfig(next.Routing.StickyTTL.Value(), next.Routing.CooldownBase.Value(), next.Routing.CooldownMax.Value(), next.Routing.CapacityWait.Value())
+		selector.UpdatePreferFreeBuild(next.Routing.PreferFreeBuild)
+		selector.UpdateSegmentedSelector(next.Routing.SegmentedSelectorEnabled, next.Routing.SegmentedMinCandidates, next.Routing.SegmentedWindowSize)
+		reasoningReplay.UpdateConfig(reasoningreplay.Config{Enabled: next.Routing.ReasoningReplayEnabled, TTL: next.Routing.ReasoningReplayTTL.Value()})
+		gatewayService.UpdateMaxAttempts(next.Routing.MaxAttempts)
+		gatewayService.UpdateBuildForbiddenReauthPolicy(next.Accounts.MarkBuildForbiddenReauth, next.Accounts.BuildForbiddenReauthCodes)
+		auditService.UpdateWriterConfig(next.Audit.BatchSize, next.Audit.FlushInterval.Value(), next.Audit.CommitDelay.Value())
+		auditService.UpdateLedgerConfig(auditLedgerConfig(next.Audit))
+		clientKeyService.UpdateDefaults(next.ClientKeyDefaults.RPMLimit, next.ClientKeyDefaults.MaxConcurrent)
+		accountService.UpdateAutoCleanConfig(accountAutoCleanConfig(next.Accounts))
+	})
+	updateService := updatecheckapp.NewService(buildinfo.CurrentVersion(), nil)
+
+	startup := newStartupState(len(windows))
+	readiness := func(readyCtx context.Context) httpserver.ReadinessSnapshot {
+		return readinessSnapshot(readyCtx, startup, runtimeHealth, modelRepo, accountRepo, providers, auditService)
+	}
+	router := httpserver.New(httpserver.Dependencies{Logger: logger, RequestTimeout: cfg.Server.RequestTimeout.Value(), MaxBodyBytes: cfg.Server.MaxBodyBytes, ConcurrencyGate: inferenceConcurrency, SecureCookies: cfg.Auth.SecureCookies, SwaggerEnabled: cfg.Server.SwaggerEnabled, PublicAPIBaseURL: cfg.Frontend.EffectivePublicAPIBaseURL(), FrontendStaticPath: cfg.Frontend.StaticPath, Readiness: readiness, TrafficReady: startup.acceptsTraffic, AdminAuth: adminService, Accounts: accountService, AccountSync: accountSyncService, Models: modelService, ClientKeys: clientKeyService, Audits: auditService, Dashboard: dashboardService, Gateway: gatewayService, Media: mediaService, Settings: settingsService, Egress: egressService, Updates: updateService})
+	server := &http.Server{Addr: cfg.Server.Listen, Handler: router, ReadHeaderTimeout: 10 * time.Second, ReadTimeout: cfg.Server.ReadTimeout.Value(), IdleTimeout: 2 * time.Minute, MaxHeaderBytes: 64 << 10}
+	return &Application{
+		logger: logger, database: database, server: server,
+		audits: auditService, responses: responseRepo, cleanupLock: refreshLock, runtime: runtimeStore,
+		settingsBus: settingsBus, invalidationBus: invalidationBus, settings: settingsService, gateway: gatewayService, media: mediaService, quotaRecovery: quotaRecoveryService, accounts: accountService, models: modelService, clientKeys: clientKeyService, updates: updateService, invalidations: invalidationService,
+		accountRepo: accountRepo, modelRepo: modelRepo, providers: providers, web: webAdapter, egress: egressManager, egressOps: egressService, startup: startup,
+	}, nil
+}
+
+func invalidationSourceInstance(cfg config.Config) string {
+	if value := strings.TrimSpace(cfg.Deployment.InstanceID); value != "" {
+		return value
+	}
+	return fmt.Sprintf("process-%d", time.Now().UnixNano())
+}
+
+func maxBatchConcurrency(value config.BatchConfig) int {
+	return max(value.ImportConcurrency, value.ConversionConcurrency, value.SyncConcurrency, value.RefreshConcurrency)
+}
+
+func webProviderConfig(cfg config.Config) webprovider.Config {
+	return webprovider.Config{
+		BaseURL: cfg.Provider.Web.BaseURL, QuotaTimeoutSeconds: int(cfg.Provider.Web.QuotaTimeout.Value().Seconds()),
+		StatsigMode: cfg.Provider.Web.StatsigMode, StatsigManualValue: cfg.Provider.Web.StatsigManualValue,
+		StatsigSignerURL:   cfg.Provider.Web.StatsigSignerURL,
+		ChatTimeoutSeconds: int(cfg.Provider.Web.ChatTimeout.Value().Seconds()), ImageTimeoutSeconds: int(cfg.Provider.Web.ImageTimeout.Value().Seconds()),
+		VideoTimeoutSeconds: int(cfg.Provider.Web.VideoTimeout.Value().Seconds()), MaxInputImageBytes: cfg.Media.MaxImageBytes,
+		AllowNSFW: cfg.Provider.Web.AllowNSFW,
+	}
+}
+
+func clearanceConfig(cfg config.Config) infraegress.ClearanceConfig {
+	return infraegress.ClearanceConfig{
+		Mode: cfg.Provider.Web.ClearanceMode, FlareSolverrURL: cfg.Provider.Web.FlareSolverrURL,
+		TargetURL: cfg.Provider.Web.BaseURL, Timeout: cfg.Provider.Web.ClearanceTimeout.Value(),
+		RefreshInterval: cfg.Provider.Web.ClearanceRefresh.Value(),
+	}
+}
+
+func consoleProviderConfig(cfg config.Config) consoleprovider.Config {
+	return consoleprovider.Config{
+		BaseURL: cfg.Provider.Console.BaseURL, SessionBaseURL: cfg.Provider.Web.BaseURL,
+		TimeoutSeconds: int(cfg.Provider.Console.ChatTimeout.Value().Seconds()),
+	}
+}
+
+func accountAutoCleanConfig(value config.AccountsConfig) accountapp.AutoCleanConfig {
+	return accountapp.AutoCleanConfig{
+		Enabled:         value.AutoCleanReauthEnabled,
+		Interval:        value.AutoCleanReauthInterval.Value(),
+		MinAge:          value.AutoCleanReauthMinAge.Value(),
+		IncludeDisabled: value.AutoCleanIncludeDisabled,
+	}
+}
+
+func auditLedgerConfig(value config.AuditConfig) auditapp.LedgerConfig {
+	return auditapp.LedgerConfig{
+		Mode:                      auditapp.LedgerMode(value.LedgerMode),
+		FailureThreshold:          value.LedgerFailureThreshold,
+		UnhealthyGrace:            value.LedgerUnhealthyGrace.Value(),
+		QueueHighWatermarkPercent: value.LedgerQueueHighWatermarkPct,
+	}
+}
+
+func mediaConfig(cfg config.Config) mediaapp.Config {
+	return mediaapp.Config{
+		PublicBaseURL: cfg.Frontend.EffectivePublicAPIBaseURL(),
+		MaxImageBytes: cfg.Media.MaxImageBytes, MaxTotalBytes: cfg.Media.MaxTotalBytes,
+		CleanupThresholdPercent: cfg.Media.CleanupThresholdPercent, CleanupInterval: cfg.Media.CleanupInterval.Value(),
+	}
+}
+
+// Run 启动 HTTP 服务和本地后台维护任务。
+func (a *Application) Run(ctx context.Context) error {
+	a.audits.Start()
+	defer func() {
+		closeCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		if err := a.audits.Close(closeCtx); err != nil {
+			a.logger.Warn("audit_shutdown_failed", "error", err)
+		}
+	}()
+	runCtx, cancelBackground := context.WithCancel(ctx)
+	var background sync.WaitGroup
+	defer func() {
+		cancelBackground()
+		background.Wait()
+	}()
+	errCh := make(chan error, 1)
+	go func() {
+		a.logger.Info("server_started", "listen", a.server.Addr)
+		errCh <- a.server.ListenAndServe()
+	}()
+	a.reconcileStartup(runCtx)
+	startBackground := func(name string, task func(context.Context) error) {
+		background.Add(1)
+		go func() {
+			defer background.Done()
+			a.runSupervisedTask(runCtx, name, task)
+		}()
+	}
+	if a.invalidationBus != nil {
+		startBackground("invalidation_publisher", a.invalidations.RunPublisher)
+		startBackground("invalidation_subscriber", a.invalidations.RunSubscriber)
+	}
+	startBackground("settings_reconcile", func(taskCtx context.Context) error {
+		a.runPeriodicTask(taskCtx, 30*time.Second, "settings_reconcile", func(runCtx context.Context) error {
+			return a.settings.ReloadPersisted(runCtx)
+		})
+		return nil
+	})
+	startBackground("performance_metrics", func(taskCtx context.Context) error {
+		a.runPeriodicTask(taskCtx, time.Minute, "performance_metrics", func(context.Context) error {
+			a.logPerformanceMetrics()
+			return nil
+		})
+		return nil
+	})
+	startBackground("release_check", func(taskCtx context.Context) error {
+		a.updates.Check(taskCtx)
+		a.runPeriodicTask(taskCtx, 24*time.Hour, "release_check", func(checkCtx context.Context) error {
+			a.updates.Check(checkCtx)
+			return nil
+		})
+		return nil
+	})
+	startBackground("billing_reservation_cleanup", func(taskCtx context.Context) error {
+		a.runPeriodicTask(taskCtx, 10*time.Minute, "billing_reservation_cleanup", func(runCtx context.Context) error {
+			_, err := a.clientKeys.CleanupExpiredBilling(runCtx, 1000)
+			return err
+		})
+		return nil
+	})
+	startBackground("model_cooldown_cleanup", func(taskCtx context.Context) error {
+		a.runPeriodicTask(taskCtx, 10*time.Minute, "model_cooldown_cleanup", func(runCtx context.Context) error {
+			_, err := a.accountRepo.PruneExpiredModelQuotaBlocks(runCtx, time.Now().UTC(), 1000)
+			return err
+		})
+		return nil
+	})
+	startBackground("response_ownership_cleanup", func(taskCtx context.Context) error {
+		a.runPeriodicTask(taskCtx, responseCleanupInterval, "response_ownership_cleanup", func(runCtx context.Context) error {
+			return a.cleanupExpiredResponses(runCtx, time.Now().UTC())
+		})
+		return nil
+	})
+	startBackground("quota_recovery", func(taskCtx context.Context) error {
+		a.quotaRecovery.Run(taskCtx)
+		return nil
+	})
+	startBackground("web_quota_refresh", func(taskCtx context.Context) error {
+		a.accounts.RunWebQuotaRefresh(taskCtx)
+		return nil
+	})
+	startBackground("credential_refresh", func(taskCtx context.Context) error {
+		a.accounts.RunCredentialRefresh(taskCtx)
+		return nil
+	})
+	startBackground("account_auto_clean", func(taskCtx context.Context) error {
+		a.accounts.RunAccountAutoClean(taskCtx)
+		return nil
+	})
+	startBackground("statsig_warmup", func(taskCtx context.Context) error {
+		a.runStatsigWarmup(taskCtx)
+		return nil
+	})
+	startBackground("web_quota_startup_catchup", func(taskCtx context.Context) error {
+		a.runWebQuotaCatchup(taskCtx)
+		return nil
+	})
+	startBackground("model_catalog_startup_catchup", func(taskCtx context.Context) error {
+		a.runModelCatalogCatchup(taskCtx)
+		return nil
+	})
+	startBackground("video_recovery", func(taskCtx context.Context) error {
+		a.gateway.RunVideoRecovery(taskCtx)
+		return nil
+	})
+	startBackground("video_workers", func(taskCtx context.Context) error {
+		a.gateway.RunVideoWorkers(taskCtx)
+		return nil
+	})
+	startBackground("media_cleanup", func(taskCtx context.Context) error {
+		a.media.RunCleanup(taskCtx, func(err error) {
+			a.logger.Warn("media_cleanup_failed", "error", err)
+		})
+		return nil
+	})
+	startBackground("clearance_refresh", func(taskCtx context.Context) error {
+		if err := a.egress.RefreshDueClearances(taskCtx, false); err != nil {
+			a.logger.Warn("clearance_initial_refresh_failed", "error", err)
+		}
+		a.runPeriodicTask(taskCtx, time.Minute, "clearance_refresh", func(runCtx context.Context) error {
+			if err := a.egress.RefreshDueClearances(runCtx, false); err != nil {
+				a.logger.Warn("clearance_refresh_failed", "error", err)
+			}
+			return nil
+		})
+		return nil
+	})
+	startBackground("egress_operations", func(taskCtx context.Context) error {
+		if err := a.egressOps.RunMaintenance(taskCtx); err != nil {
+			a.logger.Warn("egress_operations_initial_run_failed", "error", err)
+		}
+		a.runPeriodicTask(taskCtx, time.Minute, "egress_operations", a.egressOps.RunMaintenance)
+		return nil
+	})
+	if a.settingsBus != nil {
+		startBackground("settings_change_listener", func(taskCtx context.Context) error {
+			return a.settingsBus.ListenSettingsChanges(taskCtx, func(eventCtx context.Context) error {
+				reloadCtx, cancel := context.WithTimeout(eventCtx, 5*time.Second)
+				defer cancel()
+				if err := a.settings.ReloadPersisted(reloadCtx); err != nil {
+					a.logger.Warn("settings_reload_failed", "error", err)
+				}
+				return nil
+			})
+		})
+	}
+	a.queueDueWebQuotaRefresh(runCtx)
+	select {
+	case <-ctx.Done():
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		if err := a.server.Shutdown(shutdownCtx); err != nil {
+			return fmt.Errorf("关闭 HTTP 服务: %w", err)
+		}
+		return nil
+	case err := <-errCh:
+		if errors.Is(err, http.ErrServerClosed) {
+			return nil
+		}
+		return err
+	}
+}
+
+func (a *Application) cleanupExpiredResponses(ctx context.Context, now time.Time) error {
+	cleanupCtx, cancel := context.WithTimeout(ctx, responseCleanupBudget)
+	defer cancel()
+	if a.cleanupLock != nil {
+		release, acquired, err := a.cleanupLock.Acquire(cleanupCtx, "response-ownership-cleanup", responseCleanupLockTTL)
+		if err != nil {
+			return err
+		}
+		if !acquired {
+			return nil
+		}
+		defer release()
+	}
+	var totalOwnership, totalWebState int64
+	for range responseCleanupMaxBatches {
+		if err := cleanupCtx.Err(); err != nil {
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+			a.recordResponseCleanup(totalOwnership, totalWebState, true)
+			return nil
+		}
+		result, err := a.responses.DeleteExpired(cleanupCtx, now, responseOwnershipCleanupBatchSize, webResponseStateCleanupBatchSize)
+		if err != nil {
+			if errors.Is(err, context.DeadlineExceeded) && ctx.Err() == nil {
+				a.recordResponseCleanup(totalOwnership, totalWebState, true)
+				return nil
+			}
+			return err
+		}
+		totalOwnership += result.OwnershipDeleted
+		totalWebState += result.WebStateDeleted
+		if !result.HasMore {
+			a.recordResponseCleanup(totalOwnership, totalWebState, false)
+			return nil
+		}
+	}
+	a.recordResponseCleanup(totalOwnership, totalWebState, true)
+	return nil
+}
+
+func (a *Application) recordResponseCleanup(ownershipDeleted, webStateDeleted int64, backlog bool) {
+	outcome := "complete"
+	if backlog {
+		outcome = "backlog"
+		a.logger.Warn("response_cleanup_backlog", "ownership_deleted", ownershipDeleted, "web_state_deleted", webStateDeleted)
+	}
+	labels := perfmetrics.Labels{Subsystem: "response", Operation: "cleanup", Outcome: outcome}
+	perfmetrics.Default.Add("response_cleanup_ownership_rows", labels, ownershipDeleted)
+	perfmetrics.Default.Add("response_cleanup_web_state_rows", labels, webStateDeleted)
+}
+
+func (a *Application) logPerformanceMetrics() {
+	stats := a.database.Stats()
+	databaseLabels := perfmetrics.Labels{Subsystem: "database", Operation: a.database.Dialect()}
+	perfmetrics.Default.SetGauge("db_open_connections", databaseLabels, int64(stats.OpenConnections))
+	perfmetrics.Default.SetGauge("db_in_use_connections", databaseLabels, int64(stats.InUse))
+	perfmetrics.Default.SetGauge("db_idle_connections", databaseLabels, int64(stats.Idle))
+	perfmetrics.Default.SetGauge("db_wait_count", databaseLabels, stats.WaitCount)
+	perfmetrics.Default.SetGauge("db_wait_duration_us", databaseLabels, stats.WaitDuration.Microseconds())
+	if a.audits != nil {
+		a.audits.LedgerSnapshot()
+	}
+	if a.accounts != nil {
+		quota := a.accounts.QuotaRefreshStats()
+		labels := perfmetrics.Labels{Subsystem: "quota", Operation: "refresh"}
+		perfmetrics.Default.SetGauge("quota_refresh_pending", labels, int64(quota.Pending))
+		perfmetrics.Default.SetGauge("quota_refresh_queued", labels, int64(quota.Queued))
+		perfmetrics.Default.SetGauge("quota_refresh_running", labels, int64(quota.Running))
+	}
+	for _, sample := range perfmetrics.Default.CollectAndReset() {
+		a.logger.Info("performance_metric",
+			"name", sample.Name,
+			"subsystem", sample.Labels.Subsystem,
+			"operation", sample.Labels.Operation,
+			"provider", sample.Labels.Provider,
+			"plane", sample.Labels.Plane,
+			"stage", sample.Labels.Stage,
+			"ordinal", sample.Labels.Ordinal,
+			"outcome", sample.Labels.Outcome,
+			"count", sample.Count,
+			"total", sample.Total,
+			"maximum", sample.Maximum,
+			"gauge", sample.Gauge,
+			"has_gauge", sample.HasGauge,
+		)
+	}
+}
+
+func (a *Application) Close() error {
+	var runtimeErr error
+	if a.runtime != nil {
+		runtimeErr = a.runtime.Close()
+	}
+	return errors.Join(runtimeErr, a.database.Close())
+}
+
+func (a *Application) runPeriodicTask(ctx context.Context, interval time.Duration, name string, task func(context.Context) error) {
+	timer := time.NewTimer(interval)
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-timer.C:
+			runCtx, cancel := context.WithTimeout(ctx, minDuration(interval, 5*time.Minute))
+			err := task(runCtx)
+			cancel()
+			if err != nil {
+				a.logger.Warn(name+"_failed", "error", err)
+			}
+			resetTimer(timer, interval)
+		}
+	}
+}
+
+func (a *Application) runSupervisedTask(ctx context.Context, name string, task func(context.Context) error) {
+	backoff := time.Second
+	for {
+		err := batch.Do(ctx, task)
+		if ctx.Err() != nil {
+			return
+		}
+		if err == nil {
+			err = errors.New("后台任务意外退出")
+		}
+		var panicErr *batch.PanicError
+		if errors.As(err, &panicErr) {
+			a.logger.Error("background_task_restarting", "task", name, "backoff", backoff, "error", panicErr, "stack", string(panicErr.Stack))
+		} else {
+			a.logger.Error("background_task_restarting", "task", name, "backoff", backoff, "error", err)
+		}
+		timer := time.NewTimer(backoff)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return
+		case <-timer.C:
+		}
+		backoff = min(backoff*2, 30*time.Second)
+	}
+}
+
+func resetTimer(timer *time.Timer, interval time.Duration) {
+	if !timer.Stop() {
+		select {
+		case <-timer.C:
+		default:
+		}
+	}
+	timer.Reset(interval)
+}
+
+func minDuration(left, right time.Duration) time.Duration {
+	if left < right {
+		return left
+	}
+	return right
+}

backend/internal/app/console_routes_test.go

@@ -0,0 +1,32 @@
+package app
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/chenyme/grok2api/backend/internal/domain/account"
+	consoleprovider "github.com/chenyme/grok2api/backend/internal/infra/provider/console"
+)
+
+func TestConsoleRoutesUseStableProviderNamespace(t *testing.T) {
+	routes := consoleprovider.Routes()
+	if len(routes) == 0 {
+		t.Fatal("console catalog is empty")
+	}
+	seen := make(map[string]bool, len(routes))
+	for _, route := range routes {
+		if route.Provider != account.ProviderConsole || !strings.HasPrefix(route.PublicID, "Console/") {
+			t.Fatalf("non-canonical console route = %#v", route)
+		}
+		if seen[route.PublicID] {
+			t.Fatalf("duplicate console public id %q", route.PublicID)
+		}
+		seen[route.PublicID] = true
+	}
+	if seen["Console/grok-4.3-console"] {
+		t.Fatal("legacy conflict suffix leaked into canonical Console model IDs")
+	}
+	if !seen["Console/grok-4.3"] {
+		t.Fatal("canonical Console/grok-4.3 route is missing")
+	}
+}

backend/internal/app/startup.go

@@ -0,0 +1,444 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	accountapp "github.com/chenyme/grok2api/backend/internal/application/account"
+	auditapp "github.com/chenyme/grok2api/backend/internal/application/audit"
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+	httpserver "github.com/chenyme/grok2api/backend/internal/transport/http"
+)
+
+const (
+	startupRecoveryBudget    = 20 * time.Second
+	startupCriticalWindow    = 2 * time.Minute
+	startupCriticalLimit     = 100
+	statsigWarmupInterval    = 15 * time.Minute
+	webQuotaStaleAfter       = 30 * time.Minute
+	webQuotaCatchupEvery     = 30 * time.Minute
+	modelCatalogStaleAfter   = 24 * time.Hour
+	modelCatalogCatchupEvery = 6 * time.Hour
+)
+
+type startupReport struct {
+	StartedAt                time.Time
+	CompletedAt              *time.Time
+	Credentials              accountapp.CredentialStartupReport
+	CooldownsRestored        int
+	QuotaRecoveriesRestored  int
+	DueWebQuotasQueued       int
+	StatsigKeysWarmed        int
+	StaleWebQuotasFound      int
+	StaleWebQuotasSynced     int
+	StaleModelCatalogsFound  int
+	StaleModelCatalogsSynced int
+	ErrorCount               int
+}
+
+type startupState struct {
+	mu        sync.RWMutex
+	phase     string
+	updatedAt time.Time
+	report    startupReport
+	statsig   httpserver.ReadinessComponent
+}
+
+func newStartupState(restoredQuotaRecoveries int) *startupState {
+	now := time.Now().UTC()
+	return &startupState{
+		phase:     "booting",
+		updatedAt: now,
+		report: startupReport{
+			StartedAt:               now,
+			QuotaRecoveriesRestored: restoredQuotaRecoveries,
+		},
+		statsig: httpserver.ReadinessComponent{State: "cold"},
+	}
+}
+
+func (s *startupState) setPhase(phase string) {
+	s.mu.Lock()
+	s.phase = phase
+	s.updatedAt = time.Now().UTC()
+	if phase == "running" {
+		completed := s.updatedAt
+		s.report.CompletedAt = &completed
+	}
+	s.mu.Unlock()
+}
+
+func (s *startupState) updateReport(update func(*startupReport)) {
+	s.mu.Lock()
+	update(&s.report)
+	s.updatedAt = time.Now().UTC()
+	s.mu.Unlock()
+}
+
+func (s *startupState) recordError(err error) {
+	if err == nil {
+		return
+	}
+	s.updateReport(func(report *startupReport) {
+		report.ErrorCount++
+	})
+}
+
+func (s *startupState) setStatsig(state, detail string, warmed int) {
+	s.mu.Lock()
+	s.statsig = httpserver.ReadinessComponent{State: state, Detail: detail}
+	if warmed > 0 {
+		s.report.StatsigKeysWarmed = warmed
+	}
+	s.updatedAt = time.Now().UTC()
+	s.mu.Unlock()
+}
+
+func (s *startupState) snapshot() (string, time.Time, startupReport, httpserver.ReadinessComponent) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.phase, s.updatedAt, s.report, s.statsig
+}
+
+func (s *startupState) acceptsTraffic() bool {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.phase == "running"
+}
+
+func readinessSnapshot(
+	ctx context.Context,
+	state *startupState,
+	runtimeHealth func(context.Context) error,
+	models repository.ModelRepository,
+	accounts repository.AccountRepository,
+	providers *provider.Registry,
+	ledger *auditapp.Service,
+) httpserver.ReadinessSnapshot {
+	phase, updatedAt, report, statsig := state.snapshot()
+	snapshot := httpserver.ReadinessSnapshot{
+		Ready: false, State: phase, UpdatedAt: updatedAt, Startup: newReadinessStartupReport(report),
+		Components: map[string]httpserver.ReadinessComponent{
+			"runtime_store":  {State: "unknown"},
+			"billing_ledger": {State: "unknown"},
+			"grok_build":     {State: "unknown"},
+			"grok_web":       {State: "unknown"},
+			"statsig":        statsig,
+		},
+	}
+	if phase != "running" {
+		return snapshot
+	}
+	ledgerDegraded := false
+	healthCtx, cancel := context.WithTimeout(ctx, time.Second)
+	err := runtimeHealth(healthCtx)
+	cancel()
+	if err != nil {
+		snapshot.State = "not_ready"
+		snapshot.Components["runtime_store"] = httpserver.ReadinessComponent{State: "unavailable", Detail: "运行态存储不可用"}
+		return snapshot
+	}
+	snapshot.Components["runtime_store"] = httpserver.ReadinessComponent{State: "ready"}
+	if ledger != nil {
+		ledgerState := ledger.LedgerSnapshot()
+		if ledgerState.Ready {
+			snapshot.Components["billing_ledger"] = httpserver.ReadinessComponent{State: "ready"}
+		} else {
+			detail := fmt.Sprintf("审计账本不可用；连续失败 %d 次，丢失 %d 条，队列 %d/%d", ledgerState.ConsecutiveFailures, ledgerState.Dropped, ledgerState.QueueDepth, ledgerState.QueueCapacity)
+			snapshot.Components["billing_ledger"] = httpserver.ReadinessComponent{State: "degraded", Detail: detail}
+			if ledgerState.Irrecoverable || ledgerState.Mode == auditapp.LedgerModeEnforce {
+				snapshot.State = "not_ready"
+				return snapshot
+			}
+			ledgerDegraded = true
+		}
+	}
+
+	routes, err := models.ListConfiguredEnabled(ctx)
+	if err != nil {
+		snapshot.State = "not_ready"
+		snapshot.Components["model_routes"] = httpserver.ReadinessComponent{State: "unavailable", Detail: "模���路由读取失败"}
+		return snapshot
+	}
+	if len(routes) == 0 {
+		snapshot.State = "not_ready"
+		snapshot.Components["model_routes"] = httpserver.ReadinessComponent{State: "unavailable", Detail: "没有启用的模型路由"}
+		return snapshot
+	}
+	snapshot.Components["model_routes"] = httpserver.ReadinessComponent{State: "ready", Detail: fmt.Sprintf("%d 条已启用路由", len(routes))}
+
+	required := make(map[accountdomain.Provider]bool, 3)
+	usable := make(map[accountdomain.Provider]bool, 3)
+	providerErrors := make(map[accountdomain.Provider]bool, 3)
+	now := time.Now().UTC()
+	for _, route := range routes {
+		required[route.Provider] = true
+		if usable[route.Provider] || route.SupportedAccounts == 0 {
+			continue
+		}
+		candidates, listErr := accounts.ListRoutingCandidates(ctx, route.Provider, route.ID, route.UpstreamModel, providers.QuotaMode(route.Provider, route.UpstreamModel))
+		if listErr != nil {
+			providerErrors[route.Provider] = true
+			continue
+		}
+		for _, candidate := range candidates {
+			if !startupCandidateUsable(candidate, now, providers) {
+				continue
+			}
+			material, materialErr := accounts.GetCredentialMaterial(ctx, candidate.Credential.ID, candidate.Credential.Provider)
+			if materialErr != nil {
+				if !errors.Is(materialErr, repository.ErrNotFound) {
+					providerErrors[route.Provider] = true
+				}
+				continue
+			}
+			if material.EncryptedAccessToken != "" {
+				usable[route.Provider] = true
+				break
+			}
+		}
+	}
+
+	readyProviders := 0
+	unavailableProviders := 0
+	for _, providerValue := range accountdomain.Providers() {
+		name := string(providerValue)
+		if !required[providerValue] {
+			snapshot.Components[name] = httpserver.ReadinessComponent{State: "disabled"}
+			continue
+		}
+		if usable[providerValue] {
+			readyProviders++
+			snapshot.Components[name] = httpserver.ReadinessComponent{State: "ready"}
+			continue
+		}
+		unavailableProviders++
+		detail := "当前没有可用于已启用路由的账号"
+		if providerErrors[providerValue] {
+			detail = "账号候选状态读取失败"
+		}
+		snapshot.Components[name] = httpserver.ReadinessComponent{State: "unavailable", Detail: detail}
+	}
+	if required[accountdomain.ProviderWeb] && usable[accountdomain.ProviderWeb] && statsig.State != "warm" {
+		component := snapshot.Components[string(accountdomain.ProviderWeb)]
+		if statsig.State == "warming" || statsig.State == "cold" {
+			component.State = "warming"
+		} else {
+			component.State = "degraded"
+		}
+		component.Detail = "Statsig 尚未完成预热；请求仍可按需刷新"
+		snapshot.Components[string(accountdomain.ProviderWeb)] = component
+		unavailableProviders++
+	}
+	if readyProviders == 0 {
+		snapshot.State = "not_ready"
+		return snapshot
+	}
+	snapshot.Ready = true
+	if unavailableProviders > 0 || ledgerDegraded {
+		snapshot.State = "degraded"
+	} else {
+		snapshot.State = "ready"
+	}
+	return snapshot
+}
+
+// newReadinessStartupReport 只公开稳定统计，不把启动错误原文暴露到无鉴权就绪端点。
+func newReadinessStartupReport(report startupReport) *httpserver.ReadinessStartupReport {
+	return &httpserver.ReadinessStartupReport{
+		StartedAt:   report.StartedAt,
+		CompletedAt: report.CompletedAt,
+		Credentials: httpserver.ReadinessCredentialReport{
+			SchedulesBackfilled: report.Credentials.SchedulesBackfilled,
+			CriticalFound:       report.Credentials.CriticalFound,
+			Refreshed:           report.Credentials.Refreshed,
+			Failed:              report.Credentials.Failed,
+		},
+		CooldownsRestored:        report.CooldownsRestored,
+		QuotaRecoveriesRestored:  report.QuotaRecoveriesRestored,
+		DueWebQuotasQueued:       report.DueWebQuotasQueued,
+		StatsigKeysWarmed:        report.StatsigKeysWarmed,
+		StaleWebQuotasFound:      report.StaleWebQuotasFound,
+		StaleWebQuotasSynced:     report.StaleWebQuotasSynced,
+		StaleModelCatalogsFound:  report.StaleModelCatalogsFound,
+		StaleModelCatalogsSynced: report.StaleModelCatalogsSynced,
+		ErrorCount:               report.ErrorCount,
+	}
+}
+
+func startupCandidateUsable(candidate accountdomain.RoutingCandidate, now time.Time, providers *provider.Registry) bool {
+	credential := candidate.Credential
+	if credential.AuthType == "" || credential.AuthStatus != accountdomain.AuthStatusActive {
+		return false
+	}
+	refreshable := credential.AuthType == accountdomain.AuthTypeOAuth
+	if providers != nil {
+		refreshable = providers.SupportsCredentialRefresh(credential.Provider)
+	}
+	if refreshable && !credential.ExpiresAt.IsZero() && !now.Before(credential.ExpiresAt) {
+		return false
+	}
+	if credential.CooldownUntil != nil && now.Before(*credential.CooldownUntil) {
+		return false
+	}
+	if candidate.ModelCapabilityKnown && !candidate.SupportsModel {
+		return false
+	}
+	if candidate.ModelQuotaBlock != nil && now.Before(candidate.ModelQuotaBlock.CooldownUntil) {
+		return false
+	}
+	if candidate.QuotaRecovery != nil && candidate.QuotaRecovery.Status != accountdomain.QuotaRecoveryStatusActive {
+		return false
+	}
+	if candidate.Billing != nil && candidate.Billing.IsExhausted(credential.MinimumRemaining) {
+		return false
+	}
+	return candidate.QuotaWindow == nil || candidate.QuotaWindow.Remaining > 0
+}
+
+func (a *Application) reconcileStartup(ctx context.Context) {
+	a.startup.setPhase("reconciling")
+	recoveryCtx, cancel := context.WithTimeout(ctx, startupRecoveryBudget)
+	defer cancel()
+
+	if _, err := a.clientKeys.CleanupExpiredBilling(recoveryCtx, 1000); err != nil {
+		a.logger.Warn("billing_reservation_cleanup_failed", "error", err)
+		a.startup.recordError(err)
+	}
+	if err := a.gateway.RecoverVideoJobs(recoveryCtx); err != nil {
+		a.logger.Warn("video_job_recovery_failed", "error", err)
+		a.startup.recordError(err)
+	}
+	if _, err := a.accountRepo.PruneExpiredModelQuotaBlocks(recoveryCtx, time.Now().UTC(), 1000); err != nil {
+		a.logger.Warn("model_cooldown_cleanup_failed", "error", err)
+		a.startup.recordError(err)
+	}
+	for _, providerValue := range accountdomain.Providers() {
+		values, err := a.accountRepo.ListEnabled(recoveryCtx, providerValue)
+		if err != nil {
+			a.startup.recordError(err)
+			continue
+		}
+		now := time.Now().UTC()
+		a.startup.updateReport(func(report *startupReport) {
+			for _, value := range values {
+				if value.CooldownUntil != nil && now.Before(*value.CooldownUntil) {
+					report.CooldownsRestored++
+				}
+			}
+		})
+	}
+	report, err := a.accounts.RecoverCriticalCredentials(recoveryCtx, startupCriticalWindow, startupCriticalLimit)
+	a.startup.updateReport(func(startup *startupReport) { startup.Credentials = report })
+	if err != nil && ctx.Err() == nil {
+		a.logger.Warn("credential_startup_recovery_incomplete", "error", err, "found", report.CriticalFound, "refreshed", report.Refreshed, "failed", report.Failed)
+		a.startup.recordError(err)
+	}
+	a.startup.setPhase("running")
+	a.logger.Info("startup_reconciliation_completed", "credentials_backfilled", report.SchedulesBackfilled, "critical_found", report.CriticalFound, "credentials_refreshed", report.Refreshed, "credentials_failed", report.Failed)
+}
+
+func (a *Application) runStatsigWarmup(ctx context.Context) {
+	timer := time.NewTimer(0)
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-timer.C:
+		}
+		a.startup.setStatsig("warming", "正在预热共享签名", 0)
+		values, err := a.accountRepo.ListEnabled(ctx, accountdomain.ProviderWeb)
+		if err == nil && len(values) == 0 {
+			a.startup.setStatsig("disabled", "没有启用的 Grok Web 账号", 0)
+		} else if err == nil {
+			warmCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+			var warmed int
+			warmed, err = a.web.WarmStatsig(warmCtx, values[0])
+			cancel()
+			if err == nil {
+				a.startup.setStatsig("warm", "共享签名已预热", warmed)
+			}
+		}
+		if err != nil && ctx.Err() == nil {
+			a.logger.Warn("web_statsig_warmup_failed", "error", err)
+			a.startup.setStatsig("unavailable", "预热失败，将由请求按需重试", 0)
+		}
+		resetTimer(timer, statsigWarmupInterval)
+	}
+}
+
+func (a *Application) queueDueWebQuotaRefresh(ctx context.Context) {
+	windows, err := a.accounts.ListDueWebQuotaWindows(ctx, time.Now().UTC(), 1000)
+	if err != nil {
+		a.logger.Warn("web_quota_startup_catchup_failed", "error", err)
+		a.startup.recordError(err)
+		return
+	}
+	for _, window := range windows {
+		a.accounts.QueueWebQuotaRefresh(window.AccountID, window.Mode)
+	}
+	a.startup.updateReport(func(report *startupReport) { report.DueWebQuotasQueued = len(windows) })
+	if len(windows) > 0 {
+		a.logger.Info("web_quota_startup_catchup_queued", "count", len(windows))
+	}
+}
+
+func (a *Application) runWebQuotaCatchup(ctx context.Context) {
+	timer := time.NewTimer(5 * time.Second)
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-timer.C:
+		}
+		ids, err := a.accountRepo.ListStaleWebQuotaAccountIDs(ctx, time.Now().UTC().Add(-webQuotaStaleAfter), 100)
+		if err == nil && len(ids) > 0 {
+			runCtx, cancel := context.WithTimeout(ctx, 2*time.Minute)
+			var succeeded int
+			succeeded, _, err = a.accounts.SyncWebQuotaAccounts(runCtx, ids)
+			cancel()
+			a.startup.updateReport(func(report *startupReport) {
+				report.StaleWebQuotasFound = len(ids)
+				report.StaleWebQuotasSynced = succeeded
+			})
+		}
+		if err != nil && ctx.Err() == nil {
+			a.logger.Warn("web_quota_stale_catchup_failed", "error", err)
+		}
+		resetTimer(timer, webQuotaCatchupEvery)
+	}
+}
+
+func (a *Application) runModelCatalogCatchup(ctx context.Context) {
+	timer := time.NewTimer(20 * time.Second)
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-timer.C:
+		}
+		ids, err := a.modelRepo.ListStaleAccountSyncIDs(ctx, time.Now().UTC().Add(-modelCatalogStaleAfter), 100)
+		if err == nil && len(ids) > 0 {
+			runCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+			var succeeded int
+			succeeded, _, err = a.models.SyncAccounts(runCtx, ids)
+			cancel()
+			a.startup.updateReport(func(report *startupReport) {
+				report.StaleModelCatalogsFound = len(ids)
+				report.StaleModelCatalogsSynced = succeeded
+			})
+		}
+		if err != nil && ctx.Err() == nil {
+			a.logger.Warn("model_catalog_stale_catchup_failed", "error", err)
+		}
+		resetTimer(timer, modelCatalogCatchupEvery)
+	}
+}

backend/internal/app/startup_test.go

@@ -0,0 +1,144 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	modeldomain "github.com/chenyme/grok2api/backend/internal/domain/model"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+)
+
+func TestReadinessStartupReportDoesNotExposeInternalErrors(t *testing.T) {
+	state := newStartupState(0)
+	state.recordError(errors.New("postgres://private-host/internal"))
+	_, _, report, _ := state.snapshot()
+	payload, err := json.Marshal(newReadinessStartupReport(report))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(payload), "private-host") || !strings.Contains(string(payload), `"errorCount":1`) {
+		t.Fatalf("public readiness leaked internal error: %s", payload)
+	}
+}
+
+func TestReadinessKeepsBuildReadyWhenWebIsUnavailable(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "readiness.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer database.Close()
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	models := relational.NewModelRepository(database)
+	now := time.Now().UTC()
+	build, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "build-ready", SourceKey: "build-ready",
+		EncryptedAccessToken: "access", EncryptedRefreshToken: "refresh", ExpiresAt: now.Add(time.Hour),
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, MaxConcurrent: 1,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := models.UpsertRoutes(ctx, []modeldomain.Route{
+		{PublicID: "build-model", Provider: accountdomain.ProviderBuild, UpstreamModel: "build-model", Capability: modeldomain.CapabilityResponses, Enabled: true},
+		{PublicID: "web-model", Provider: accountdomain.ProviderWeb, UpstreamModel: "web-model", Capability: modeldomain.CapabilityChat, Enabled: true},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := models.ReplaceAccountCapabilities(ctx, build.ID, []string{"build-model"}, now); err != nil {
+		t.Fatal(err)
+	}
+	state := newStartupState(0)
+	state.setPhase("running")
+	state.setStatsig("unavailable", "test", 0)
+	snapshot := readinessSnapshot(ctx, state, func(context.Context) error { return nil }, models, accounts, provider.NewRegistry(), nil)
+	if !snapshot.Ready || snapshot.State != "degraded" {
+		t.Fatalf("snapshot = %#v", snapshot)
+	}
+	if snapshot.Components["grok_build"].State != "ready" || snapshot.Components["grok_web"].State != "unavailable" {
+		t.Fatalf("components = %#v", snapshot.Components)
+	}
+}
+
+func TestReadinessRejectsAccountWithoutAccessToken(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "readiness-missing-access.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer database.Close()
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	models := relational.NewModelRepository(database)
+	now := time.Now().UTC()
+	build, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, AuthType: accountdomain.AuthTypeOAuth,
+		Name: "refresh-only", SourceKey: "refresh-only", EncryptedRefreshToken: "refresh",
+		ExpiresAt: now.Add(time.Hour), Enabled: true, AuthStatus: accountdomain.AuthStatusActive, MaxConcurrent: 1,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := models.UpsertRoutes(ctx, []modeldomain.Route{{
+		PublicID: "build-model", Provider: accountdomain.ProviderBuild, UpstreamModel: "build-model", Capability: modeldomain.CapabilityResponses, Enabled: true,
+	}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := models.ReplaceAccountCapabilities(ctx, build.ID, []string{"build-model"}, now); err != nil {
+		t.Fatal(err)
+	}
+	state := newStartupState(0)
+	state.setPhase("running")
+	snapshot := readinessSnapshot(ctx, state, func(context.Context) error { return nil }, models, accounts, provider.NewRegistry(), nil)
+	if snapshot.Ready || snapshot.Components["grok_build"].State != "unavailable" {
+		t.Fatalf("snapshot = %#v", snapshot)
+	}
+}
+
+func TestReadinessRestoresPersistedCooldownWithoutUpstreamProbe(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "cooldown-readiness.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer database.Close()
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	models := relational.NewModelRepository(database)
+	now := time.Now().UTC()
+	cooldownUntil := now.Add(10 * time.Minute)
+	build, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "cooling", SourceKey: "cooling",
+		EncryptedAccessToken: "access", EncryptedRefreshToken: "refresh", ExpiresAt: now.Add(time.Hour),
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, MaxConcurrent: 1, CooldownUntil: &cooldownUntil,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := models.UpsertRoutes(ctx, []modeldomain.Route{{PublicID: "build-model", Provider: accountdomain.ProviderBuild, UpstreamModel: "build-model", Capability: modeldomain.CapabilityResponses, Enabled: true}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := models.ReplaceAccountCapabilities(ctx, build.ID, []string{"build-model"}, now); err != nil {
+		t.Fatal(err)
+	}
+	state := newStartupState(0)
+	state.setPhase("running")
+	snapshot := readinessSnapshot(ctx, state, func(context.Context) error { return nil }, models, accounts, provider.NewRegistry(), nil)
+	if snapshot.Ready || snapshot.State != "not_ready" || snapshot.Components["grok_build"].State != "unavailable" {
+		t.Fatalf("snapshot = %#v", snapshot)
+	}
+}

backend/internal/app/topology.go

@@ -0,0 +1,72 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/chenyme/grok2api/backend/internal/infra/config"
+)
+
+const sharedMediaMarkerName = ".grok2api-cluster"
+
+// preflightDeployment validates the operator-declared shared media mount with a stable cluster marker and a read/write probe.
+func preflightDeployment(cfg config.Config) error {
+	if cfg.Deployment.Replicas <= 1 {
+		return nil
+	}
+	directory := cfg.Media.Local.Path
+	markerPath := filepath.Join(directory, sharedMediaMarkerName)
+	want := strings.TrimSpace(cfg.Deployment.ClusterID) + "\n"
+	current, err := os.ReadFile(markerPath)
+	if errors.Is(err, os.ErrNotExist) {
+		file, createErr := os.OpenFile(markerPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
+		if createErr == nil {
+			if _, writeErr := file.WriteString(want); writeErr != nil {
+				_ = file.Close()
+				return fmt.Errorf("write shared media cluster marker: %w", writeErr)
+			}
+			if closeErr := file.Close(); closeErr != nil {
+				return fmt.Errorf("close shared media cluster marker: %w", closeErr)
+			}
+			current = []byte(want)
+		} else if errors.Is(createErr, os.ErrExist) {
+			current, err = os.ReadFile(markerPath)
+			if err != nil {
+				return fmt.Errorf("read shared media cluster marker: %w", err)
+			}
+		} else {
+			return fmt.Errorf("create shared media cluster marker: %w", createErr)
+		}
+	} else if err != nil {
+		return fmt.Errorf("read shared media cluster marker: %w", err)
+	}
+	if string(current) != want {
+		return fmt.Errorf("shared media cluster marker mismatch: configured cluster %q does not own %s", cfg.Deployment.ClusterID, markerPath)
+	}
+
+	probe, err := os.CreateTemp(directory, ".grok2api-preflight-")
+	if err != nil {
+		return fmt.Errorf("create shared media preflight file: %w", err)
+	}
+	probePath := probe.Name()
+	defer os.Remove(probePath)
+	payload := []byte(strings.TrimSpace(cfg.Deployment.InstanceID))
+	if _, err := probe.Write(payload); err != nil {
+		_ = probe.Close()
+		return fmt.Errorf("write shared media preflight file: %w", err)
+	}
+	if err := probe.Close(); err != nil {
+		return fmt.Errorf("close shared media preflight file: %w", err)
+	}
+	readBack, err := os.ReadFile(probePath)
+	if err != nil {
+		return fmt.Errorf("read shared media preflight file: %w", err)
+	}
+	if string(readBack) != string(payload) {
+		return errors.New("shared media preflight read-back mismatch")
+	}
+	return nil
+}

backend/internal/app/topology_test.go

@@ -0,0 +1,32 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/chenyme/grok2api/backend/internal/infra/config"
+)
+
+func TestPreflightDeploymentCreatesAndValidatesSharedMediaMarker(t *testing.T) {
+	directory := t.TempDir()
+	cfg := config.Config{
+		Deployment: config.DeploymentConfig{Replicas: 2, InstanceID: "replica-a", ClusterID: "cluster-a", SharedMedia: true},
+		Media:      config.MediaConfig{Local: config.LocalMediaConfig{Path: directory}},
+	}
+	if err := preflightDeployment(cfg); err != nil {
+		t.Fatal(err)
+	}
+	marker, err := os.ReadFile(filepath.Join(directory, sharedMediaMarkerName))
+	if err != nil || string(marker) != "cluster-a\n" {
+		t.Fatalf("marker = %q, err = %v", marker, err)
+	}
+	cfg.Deployment.InstanceID = "replica-b"
+	if err := preflightDeployment(cfg); err != nil {
+		t.Fatal(err)
+	}
+	cfg.Deployment.ClusterID = "cluster-b"
+	if err := preflightDeployment(cfg); err == nil {
+		t.Fatal("expected cluster marker mismatch")
+	}
+}

backend/internal/application/account/account_cleanup_test.go

@@ -0,0 +1,157 @@
+package account
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/runtime/memory"
+	"github.com/chenyme/grok2api/backend/internal/infra/security"
+)
+
+func TestCleanupAccountsDeletesOnlySelectedCurrentStatuses(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 19, 12, 0, 0, 0, time.UTC)
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "account-cleanup.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	token, err := cipher.Encrypt("cleanup-token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	repo := relational.NewAccountRepository(database)
+	service := NewService(repo, nil, nil, memory.NewStickyStore(), nil, cipher, nil)
+	service.now = func() time.Time { return now }
+
+	create := func(name string, providerValue accountdomain.Provider, mutate func(*accountdomain.Credential)) uint64 {
+		t.Helper()
+		value, _, createErr := repo.UpsertByIdentity(ctx, accountdomain.Credential{
+			Provider: providerValue, AuthType: accountdomain.AuthTypeSSO, Name: name, SourceKey: fmt.Sprintf("cleanup-%s", name),
+			EncryptedAccessToken: token, Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+		})
+		if createErr != nil {
+			t.Fatal(createErr)
+		}
+		if mutate != nil {
+			mutate(&value)
+			value, createErr = repo.Update(ctx, value)
+			if createErr != nil {
+				t.Fatal(createErr)
+			}
+		}
+		return value.ID
+	}
+
+	normalID := create("normal", accountdomain.ProviderBuild, nil)
+	disabledID := create("disabled", accountdomain.ProviderBuild, func(value *accountdomain.Credential) { value.Enabled = false })
+	invalidID := create("invalid", accountdomain.ProviderBuild, func(value *accountdomain.Credential) { value.AuthStatus = accountdomain.AuthStatusReauthRequired })
+	coolingID := create("cooling", accountdomain.ProviderBuild, func(value *accountdomain.Credential) { until := now.Add(time.Hour); value.CooldownUntil = &until })
+	expiredCooldownID := create("expired-cooldown", accountdomain.ProviderBuild, func(value *accountdomain.Credential) { until := now.Add(-time.Hour); value.CooldownUntil = &until })
+	otherProviderID := create("web-disabled", accountdomain.ProviderWeb, func(value *accountdomain.Credential) { value.Enabled = false })
+
+	result, err := service.CleanupAccounts(ctx, accountdomain.ProviderBuild, []CleanupStatus{CleanupStatusDisabled, CleanupStatusReauthRequired, CleanupStatusCooldown, CleanupStatusDisabled}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Deleted != 3 || result.RootsDeleted != 3 || result.LinkedDeleted != 0 || result.Skipped != 0 {
+		t.Fatalf("result = %#v", result)
+	}
+	for _, id := range []uint64{disabledID, invalidID, coolingID} {
+		if _, err := repo.Get(ctx, id); err == nil {
+			t.Fatalf("account %d was not deleted", id)
+		}
+	}
+	for _, id := range []uint64{normalID, expiredCooldownID, otherProviderID} {
+		if _, err := repo.Get(ctx, id); err != nil {
+			t.Fatalf("account %d should remain: %v", id, err)
+		}
+	}
+}
+
+func TestCleanupAccountsRequiresStatus(t *testing.T) {
+	service := NewService(nil, nil, nil, nil, nil, nil, nil)
+	if _, err := service.CleanupAccounts(context.Background(), accountdomain.ProviderBuild, nil, nil); err == nil {
+		t.Fatal("empty cleanup status unexpectedly succeeded")
+	}
+	// Linked targets cannot include the root provider or an invalid provider.
+	if _, err := service.CleanupAccounts(context.Background(), accountdomain.ProviderBuild, []CleanupStatus{CleanupStatusDisabled}, []accountdomain.Provider{accountdomain.ProviderBuild}); err == nil {
+		t.Fatal("self-target cleanup unexpectedly succeeded")
+	}
+	if _, err := service.CleanupAccounts(context.Background(), accountdomain.ProviderBuild, []CleanupStatus{CleanupStatusDisabled}, []accountdomain.Provider{accountdomain.Provider("nope")}); err == nil {
+		t.Fatal("invalid target cleanup unexpectedly succeeded")
+	}
+}
+
+// Cleanup with linked targets removes peers regardless of peer state and reports exact counts.
+func TestCleanupAccountsWithLinkedTargets(t *testing.T) {
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-cleanup-linked.db")
+	now := time.Now().UTC()
+	service.now = func() time.Time { return now }
+
+	web, build, console := seedLinkedTrio(t, repo, strings.Repeat("7", 64), "u-cleanup")
+	// Mark the Web root invalid while keeping active peers to verify peer state is ignored.
+	web.AuthStatus = accountdomain.AuthStatusReauthRequired
+	if _, err := repo.Update(ctx, web); err != nil {
+		t.Fatal(err)
+	}
+	healthyWeb := mustUpsertLinked(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "healthy", SourceKey: "sso:" + strings.Repeat("8", 64),
+	})
+
+	result, err := service.CleanupAccounts(ctx, accountdomain.ProviderWeb, []CleanupStatus{CleanupStatusReauthRequired}, []accountdomain.Provider{accountdomain.ProviderBuild, accountdomain.ProviderConsole})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Deleted != 3 || result.RootsDeleted != 1 || result.LinkedDeleted != 2 || result.Skipped != 0 {
+		t.Fatalf("result = %#v", result)
+	}
+	assertAccountMissing(t, repo, web.ID)
+	assertAccountMissing(t, repo, build.ID)
+	assertAccountMissing(t, repo, console.ID)
+	assertAccountPresent(t, repo, healthyWeb.ID)
+}
+
+// Cleanup preview counts roots and linked targets without deleting rows.
+func TestPreviewCleanupCountsWithoutDeleting(t *testing.T) {
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-cleanup-preview.db")
+	now := time.Now().UTC()
+	service.now = func() time.Time { return now }
+
+	web, build, console := seedLinkedTrio(t, repo, strings.Repeat("9", 64), "u-preview")
+	web.Enabled = false
+	if _, err := repo.Update(ctx, web); err != nil {
+		t.Fatal(err)
+	}
+
+	preview, err := service.PreviewCleanup(ctx, accountdomain.ProviderWeb, []CleanupStatus{CleanupStatusDisabled, CleanupStatusCooldown}, []accountdomain.Provider{accountdomain.ProviderBuild, accountdomain.ProviderConsole})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if preview.RootsByStatus["disabled"] != 1 || preview.RootsByStatus["cooldown"] != 0 || preview.RootCount != 1 || preview.Total != 3 {
+		t.Fatalf("preview = %#v", preview)
+	}
+	assertAccountPresent(t, repo, web.ID)
+	assertAccountPresent(t, repo, build.ID)
+	assertAccountPresent(t, repo, console.ID)
+
+	if _, err := service.PreviewCleanup(ctx, accountdomain.ProviderWeb, nil, nil); err == nil {
+		t.Fatal("empty statuses preview unexpectedly succeeded")
+	}
+}

backend/internal/application/account/auto_clean.go

@@ -0,0 +1,265 @@
+package account
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+// AutoCleanConfig 是账号自动清理策略；由 app 层从运行设置映射，不依赖 infra/config。
+type AutoCleanConfig struct {
+	Enabled         bool
+	Interval        time.Duration
+	MinAge          time.Duration
+	IncludeDisabled bool
+}
+
+const (
+	autoCleanReauthBatchSize   = 100
+	autoCleanReauthMaxScans    = 50
+	autoCleanReauthMaxDeletes  = 10
+	autoCleanReauthLockKey     = "account-auto-clean:reauth"
+	autoCleanReauthLockTTL     = 5 * time.Minute
+	autoCleanReauthRunTimeout  = 4 * time.Minute
+	autoCleanRuntimeWriteLimit = 3 * time.Second
+)
+
+// UpdateAutoCleanConfig 热更新账号自动清理策略。
+// 仅在策略实际变化时唤醒调度器；唤醒只重排 timer，不会直接硬删。
+func (s *Service) UpdateAutoCleanConfig(value AutoCleanConfig) {
+	value = normalizeAutoCleanConfig(value)
+	s.autoCleanMu.Lock()
+	if s.autoClean == value {
+		s.autoCleanMu.Unlock()
+		return
+	}
+	s.autoClean = value
+	s.autoCleanRevision++
+	s.autoCleanMu.Unlock()
+	select {
+	case s.autoCleanWake <- struct{}{}:
+	default:
+	}
+}
+
+func normalizeAutoCleanConfig(value AutoCleanConfig) AutoCleanConfig {
+	if value.Interval < time.Minute {
+		value.Interval = time.Minute
+	}
+	if value.Interval > time.Hour {
+		value.Interval = time.Hour
+	}
+	if value.MinAge < time.Minute {
+		value.MinAge = time.Minute
+	}
+	if value.MinAge > 30*24*time.Hour {
+		value.MinAge = 30 * 24 * time.Hour
+	}
+	return value
+}
+
+func (s *Service) autoCleanSnapshot() (AutoCleanConfig, uint64) {
+	s.autoCleanMu.RLock()
+	defer s.autoCleanMu.RUnlock()
+	return s.autoClean, s.autoCleanRevision
+}
+
+func (s *Service) autoCleanConfig() AutoCleanConfig {
+	value, _ := s.autoCleanSnapshot()
+	return value
+}
+
+func (s *Service) autoCleanRevisionCurrent(expected uint64, cfg AutoCleanConfig) bool {
+	current, revision := s.autoCleanSnapshot()
+	return revision == expected && current == cfg
+}
+
+func autoCleanInterval(cfg AutoCleanConfig) time.Duration {
+	if !cfg.Enabled {
+		return time.Hour
+	}
+	return normalizeAutoCleanConfig(cfg).Interval
+}
+
+// RunAccountAutoClean 在启用时周期性删除过期的 reauthRequired 账号；默认关闭。
+// timer 绑定配置 revision，旧 timer 即使与热更新同时就绪也只能重排，不能使用新配置执行删除。
+func (s *Service) RunAccountAutoClean(ctx context.Context) {
+	// NewService / 启动接线可能已向 wake 写入；启动时统一按最新快照排程。
+	select {
+	case <-s.autoCleanWake:
+	default:
+	}
+	cfg, scheduledRevision := s.autoCleanSnapshot()
+	timer := time.NewTimer(autoCleanInterval(cfg))
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-s.autoCleanWake:
+			cfg, scheduledRevision = s.autoCleanSnapshot()
+			resetCredentialRefreshTimer(timer, autoCleanInterval(cfg))
+		case <-timer.C:
+			current, revision := s.autoCleanSnapshot()
+			if revision == scheduledRevision && current.Enabled {
+				if err := s.runAutoCleanReauthRevision(ctx, current, revision); err != nil && ctx.Err() == nil {
+					s.logger.Warn("account_auto_clean_failed", "error", err)
+				}
+			}
+			cfg, scheduledRevision = s.autoCleanSnapshot()
+			resetCredentialRefreshTimer(timer, autoCleanInterval(cfg))
+		}
+	}
+}
+
+// runAutoCleanReauth 保留给同包测试与维护调用；生产调度使用带 revision 的实现。
+func (s *Service) runAutoCleanReauth(ctx context.Context, cfg AutoCleanConfig) error {
+	_, revision := s.autoCleanSnapshot()
+	return s.runAutoCleanReauthRevision(ctx, cfg, revision)
+}
+
+func (s *Service) runAutoCleanReauthRevision(ctx context.Context, cfg AutoCleanConfig, revision uint64) error {
+	if !cfg.Enabled || !s.autoCleanRevisionCurrent(revision, cfg) {
+		return nil
+	}
+	runCtx, cancel := context.WithTimeout(ctx, autoCleanReauthRunTimeout)
+	defer cancel()
+	if s.refreshLock != nil {
+		release, acquired, err := s.refreshLock.Acquire(runCtx, autoCleanReauthLockKey, autoCleanReauthLockTTL)
+		if err != nil {
+			return err
+		}
+		if !acquired {
+			s.logger.Debug("account_auto_clean_skipped", "reason", "lock_contended")
+			return nil
+		}
+		if release != nil {
+			defer release()
+		}
+	}
+
+	markedBefore := s.now().Add(-cfg.MinAge)
+	var afterID uint64
+	scanned := 0
+	deleted := 0
+	skipped := 0
+	activeSkipped := 0
+	scanBatches := 0
+	deleteBatches := 0
+	limitReached := false
+	exhausted := false
+	for scanBatches < autoCleanReauthMaxScans && deleteBatches < autoCleanReauthMaxDeletes {
+		if !s.autoCleanRevisionCurrent(revision, cfg) {
+			break
+		}
+		candidates, err := s.accounts.ListAutoCleanReauthCandidates(runCtx, markedBefore, cfg.IncludeDisabled, afterID, autoCleanReauthBatchSize)
+		if err != nil {
+			if scanned > 0 || deleted > 0 || skipped > 0 {
+				s.logger.Warn("auto_clean_reauth_partial", "deleted", deleted, "scanned", scanned, "skipped", skipped, "error", err)
+			}
+			return err
+		}
+		if len(candidates) == 0 {
+			exhausted = true
+			break
+		}
+		scanBatches++
+		scanned += len(candidates)
+		afterID = candidates[len(candidates)-1]
+		deletable, active, err := s.excludeAccountsWithActiveLeases(runCtx, candidates)
+		if err != nil {
+			return err
+		}
+		activeSkipped += active
+		skipped += active
+		if !s.autoCleanRevisionCurrent(revision, cfg) {
+			break
+		}
+		if len(deletable) == 0 {
+			if len(candidates) < autoCleanReauthBatchSize {
+				exhausted = true
+				break
+			}
+			continue
+		}
+		deleteBatches++
+		ids, err := s.accounts.DeleteAutoCleanReauthCandidates(runCtx, markedBefore, cfg.IncludeDisabled, deletable)
+		if err != nil {
+			if scanned > 0 || deleted > 0 || skipped > 0 {
+				s.logger.Warn("auto_clean_reauth_partial", "deleted", deleted, "scanned", scanned, "skipped", skipped, "error", err)
+			}
+			return err
+		}
+		deleted += len(ids)
+		skipped += len(deletable) - len(ids)
+		if len(ids) > 0 {
+			s.logger.Debug("auto_clean_reauth_batch_deleted", "account_ids", ids)
+			if failures, cleanupErr := s.clearDeletedAccountRuntimeState(runCtx, ids); cleanupErr != nil {
+				s.logger.Warn("auto_clean_reauth_runtime_cleanup_failed", "failures", failures, "error", cleanupErr)
+			}
+		}
+		if len(candidates) < autoCleanReauthBatchSize {
+			exhausted = true
+			break
+		}
+	}
+	limitReached = !exhausted && (scanBatches == autoCleanReauthMaxScans || deleteBatches == autoCleanReauthMaxDeletes)
+	if deleted > 0 {
+		s.invalidateBuildBotFlagCache()
+	}
+	if scanned > 0 || deleted > 0 || skipped > 0 {
+		s.logger.Info("auto_clean_reauth", "deleted", deleted, "scanned", scanned, "skipped", skipped, "active_skipped", activeSkipped, "scan_batches", scanBatches, "delete_batches", deleteBatches, "limit_reached", limitReached, "min_age", cfg.MinAge.String(), "include_disabled", cfg.IncludeDisabled)
+	}
+	return nil
+}
+
+func (s *Service) excludeAccountsWithActiveLeases(ctx context.Context, ids []uint64) ([]uint64, int, error) {
+	if len(ids) == 0 || s.concurrency == nil {
+		return append([]uint64(nil), ids...), 0, nil
+	}
+	keys := make([]string, len(ids))
+	for index, id := range ids {
+		keys[index] = repository.AccountConcurrencyKey(id)
+	}
+	values := make(map[string]int, len(keys))
+	if reader, ok := s.concurrency.(repository.ConcurrencySnapshotReader); ok {
+		current, err := reader.CurrentMany(ctx, keys)
+		if err != nil {
+			return nil, 0, err
+		}
+		values = current
+	} else {
+		for _, key := range keys {
+			current, err := s.concurrency.Current(ctx, key)
+			if err != nil {
+				return nil, 0, err
+			}
+			values[key] = current
+		}
+	}
+	deletable := make([]uint64, 0, len(ids))
+	active := 0
+	for index, id := range ids {
+		if values[keys[index]] > 0 {
+			active++
+			continue
+		}
+		deletable = append(deletable, id)
+	}
+	return deletable, active, nil
+}
+
+func (s *Service) clearDeletedAccountRuntimeState(ctx context.Context, ids []uint64) (int, error) {
+	cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), autoCleanRuntimeWriteLimit)
+	defer cancel()
+	failures, firstErr := s.deleteStickyAccounts(cleanupCtx, ids)
+	for _, id := range ids {
+		s.clearRefreshState(id)
+	}
+	if failures == 0 {
+		return 0, nil
+	}
+	return failures, fmt.Errorf("清理已删除账号的会话粘滞状态失败: %w", firstErr)
+}

backend/internal/application/account/auto_clean_test.go

@@ -0,0 +1,528 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/runtime/memory"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+func TestAutoCleanReauthRespectsMinAgeAndIncludeDisabled(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 20, 12, 0, 0, 0, time.UTC)
+	service, repo := newAutoCleanTestService(t, now)
+
+	aged := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "aged-reauth", SourceKey: "aged-reauth",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusReauthRequired,
+		ReauthMarkedAt: ptrTime(now.Add(-2 * time.Hour)),
+	})
+	fresh := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "fresh-reauth", SourceKey: "fresh-reauth",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusReauthRequired,
+		ReauthMarkedAt: ptrTime(now.Add(-10 * time.Minute)),
+	})
+	activePermanent := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "active-permanent", SourceKey: "active-permanent",
+		EncryptedAccessToken: "x", EncryptedRefreshToken: "r", Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+		RefreshPermanent: true, ExpiresAt: now.Add(time.Hour),
+	})
+	cooldownUntil := now.Add(time.Hour)
+	cooldown := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "cooldown", SourceKey: "cooldown",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+		CooldownUntil: &cooldownUntil,
+	})
+	disabledAged := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "disabled-aged", SourceKey: "disabled-aged",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusReauthRequired,
+		ReauthMarkedAt: ptrTime(now.Add(-3 * time.Hour)),
+	})
+	disabledAged.Enabled = false
+	var err error
+	disabledAged, err = repo.Update(ctx, disabledAged)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Flag off is a no-op.
+	service.UpdateAutoCleanConfig(AutoCleanConfig{
+		Enabled: false, Interval: 10 * time.Minute, MinAge: time.Hour,
+	})
+	if err := service.runAutoCleanReauth(ctx, service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	assertPresent(t, repo, aged.ID)
+	assertPresent(t, repo, fresh.ID)
+	assertPresent(t, repo, disabledAged.ID)
+
+	// Enabled without include-disabled: only aged enabled reauth is deleted.
+	service.UpdateAutoCleanConfig(AutoCleanConfig{
+		Enabled: true, Interval: 10 * time.Minute, MinAge: time.Hour, IncludeDisabled: false,
+	})
+	if err := service.runAutoCleanReauth(ctx, service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	assertMissing(t, repo, aged.ID)
+	assertPresent(t, repo, fresh.ID)
+	assertPresent(t, repo, activePermanent.ID)
+	assertPresent(t, repo, cooldown.ID)
+	assertPresent(t, repo, disabledAged.ID)
+
+	// Include disabled: aged disabled reauth is deleted; fresh remains.
+	service.UpdateAutoCleanConfig(AutoCleanConfig{
+		Enabled: true, Interval: 10 * time.Minute, MinAge: time.Hour, IncludeDisabled: true,
+	})
+	if err := service.runAutoCleanReauth(ctx, service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	assertMissing(t, repo, disabledAged.ID)
+	assertPresent(t, repo, fresh.ID)
+	assertPresent(t, repo, activePermanent.ID)
+	assertPresent(t, repo, cooldown.ID)
+
+	// Advance clock past minAge for the remaining fresh reauth.
+	service.now = func() time.Time { return now.Add(2 * time.Hour) }
+	if err := service.runAutoCleanReauth(ctx, service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	assertMissing(t, repo, fresh.ID)
+	assertPresent(t, repo, activePermanent.ID)
+	assertPresent(t, repo, cooldown.ID)
+}
+
+func TestMarkReauthRequiredSetsAnchorAndEditDoesNotReset(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 20, 15, 0, 0, 0, time.UTC)
+	service, repo := newAutoCleanTestService(t, now)
+
+	value := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "anchor", SourceKey: "anchor",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err := service.MarkReauthRequired(ctx, value.ID, "token rejected"); err != nil {
+		t.Fatal(err)
+	}
+	marked, err := repo.Get(ctx, value.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if marked.AuthStatus != accountdomain.AuthStatusReauthRequired || marked.ReauthMarkedAt == nil {
+		t.Fatalf("expected reauth anchor, got %#v", marked)
+	}
+	anchor := *marked.ReauthMarkedAt
+
+	// Ordinary edit must not reset reauth_marked_at.
+	marked.Name = "anchor-renamed"
+	if _, err := repo.Update(ctx, marked); err != nil {
+		t.Fatal(err)
+	}
+	afterEdit, err := repo.Get(ctx, value.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if afterEdit.ReauthMarkedAt == nil || !afterEdit.ReauthMarkedAt.Equal(anchor) {
+		t.Fatalf("reauth_marked_at reset by edit: before=%s after=%v", anchor, afterEdit.ReauthMarkedAt)
+	}
+}
+
+func TestAutoCleanReauthMultiBatch(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 20, 18, 0, 0, 0, time.UTC)
+	service, repo := newAutoCleanTestService(t, now)
+
+	const total = 105
+	ids := make([]uint64, 0, total)
+	for i := 0; i < total; i++ {
+		value := mustUpsert(t, repo, accountdomain.Credential{
+			Provider: accountdomain.ProviderBuild, Name: "batch-" + itoa(i), SourceKey: "batch-" + itoa(i),
+			EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusReauthRequired,
+			ReauthMarkedAt: ptrTime(now.Add(-2 * time.Hour)),
+		})
+		ids = append(ids, value.ID)
+	}
+
+	// 直接验证 repo 分批：第一批最多 100，且 nextAfter 前进。
+	candidates, err := repo.ListAutoCleanReauthCandidates(ctx, now.Add(-time.Hour), false, 0, 100)
+	if err != nil {
+		t.Fatal(err)
+	}
+	deleted, err := repo.DeleteAutoCleanReauthCandidates(ctx, now.Add(-time.Hour), false, candidates)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(candidates) != 100 || len(deleted) != 100 || candidates[len(candidates)-1] == 0 {
+		t.Fatalf("first batch candidates=%d deleted=%d nextAfter=%d", len(candidates), len(deleted), candidates[len(candidates)-1])
+	}
+	remaining := 0
+	for _, id := range ids {
+		if _, getErr := repo.Get(ctx, id); getErr == nil {
+			remaining++
+		}
+	}
+	if remaining != 5 {
+		t.Fatalf("remaining after first batch = %d", remaining)
+	}
+
+	// 应用层应扫完全部剩余。
+	service.UpdateAutoCleanConfig(AutoCleanConfig{
+		Enabled: true, Interval: 10 * time.Minute, MinAge: time.Hour,
+	})
+	if err := service.runAutoCleanReauth(ctx, service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range ids {
+		assertMissing(t, repo, id)
+	}
+}
+
+func TestSecondMarkReauthKeepsOriginalAnchor(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 20, 16, 0, 0, 0, time.UTC)
+	service, repo := newAutoCleanTestService(t, now)
+	value := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "second-mark", SourceKey: "second-mark",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err := service.MarkReauthRequired(ctx, value.ID, "first"); err != nil {
+		t.Fatal(err)
+	}
+	first, err := repo.Get(ctx, value.ID)
+	if err != nil || first.ReauthMarkedAt == nil {
+		t.Fatalf("first mark = %#v err=%v", first, err)
+	}
+	anchor := *first.ReauthMarkedAt
+	time.Sleep(5 * time.Millisecond)
+	if err := service.MarkReauthRequired(ctx, value.ID, "second"); err != nil {
+		t.Fatal(err)
+	}
+	second, err := repo.Get(ctx, value.ID)
+	if err != nil || second.ReauthMarkedAt == nil || !second.ReauthMarkedAt.Equal(anchor) {
+		t.Fatalf("anchor reset: first=%s second=%v", anchor, second.ReauthMarkedAt)
+	}
+}
+
+func TestRunAccountAutoCleanDoesNotDeleteOnEnableOrWake(t *testing.T) {
+	now := time.Date(2026, 7, 20, 19, 0, 0, 0, time.UTC)
+	service, repo := newAutoCleanTestService(t, now)
+	aged := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "wake-aged", SourceKey: "wake-aged",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusReauthRequired,
+		ReauthMarkedAt: ptrTime(now.Add(-2 * time.Hour)),
+	})
+
+	// 启用只写入配置并唤醒；本身不删除。
+	service.UpdateAutoCleanConfig(AutoCleanConfig{
+		Enabled: true, Interval: time.Minute, MinAge: time.Hour,
+	})
+	assertPresent(t, repo, aged.ID)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		service.RunAccountAutoClean(ctx)
+	}()
+
+	// 启动时会 drain 启动前 wake 并 arm timer；热更 wake 只重排 timer。
+	time.Sleep(150 * time.Millisecond)
+	assertPresent(t, repo, aged.ID)
+
+	service.UpdateAutoCleanConfig(AutoCleanConfig{
+		Enabled: true, Interval: time.Minute, MinAge: time.Hour, IncludeDisabled: true,
+	})
+	time.Sleep(150 * time.Millisecond)
+	assertPresent(t, repo, aged.ID)
+
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("auto-clean scheduler did not stop")
+	}
+	assertPresent(t, repo, aged.ID)
+}
+
+func newAutoCleanTestService(t *testing.T, now time.Time) (*Service, *relational.AccountRepository) {
+	t.Helper()
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "auto-clean.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	repo := relational.NewAccountRepository(database)
+	service := NewService(repo, nil, nil, memory.NewStickyStore(), nil, nil, nil)
+	service.now = func() time.Time { return now }
+	return service, repo
+}
+
+func mustUpsert(t *testing.T, repo *relational.AccountRepository, value accountdomain.Credential) accountdomain.Credential {
+	t.Helper()
+	out, _, err := repo.UpsertByIdentity(context.Background(), value)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func assertMissing(t *testing.T, repo *relational.AccountRepository, id uint64) {
+	t.Helper()
+	if _, err := repo.Get(context.Background(), id); err == nil {
+		t.Fatalf("account %d still present", id)
+	} else if !errors.Is(err, repository.ErrNotFound) {
+		t.Fatalf("account %d get error: %v", id, err)
+	}
+}
+
+func assertPresent(t *testing.T, repo *relational.AccountRepository, id uint64) {
+	t.Helper()
+	if _, err := repo.Get(context.Background(), id); err != nil {
+		t.Fatalf("account %d missing or error: %v", id, err)
+	}
+}
+
+func ptrTime(value time.Time) *time.Time { return &value }
+
+func itoa(value int) string {
+	if value == 0 {
+		return "0"
+	}
+	var buf [12]byte
+	i := len(buf)
+	for value > 0 {
+		i--
+		buf[i] = byte('0' + value%10)
+		value /= 10
+	}
+	return string(buf[i:])
+}
+
+func TestUpdateAutoCleanConfigClamps(t *testing.T) {
+	service, _ := newAutoCleanTestService(t, time.Date(2026, 7, 20, 12, 0, 0, 0, time.UTC))
+	service.UpdateAutoCleanConfig(AutoCleanConfig{
+		Enabled: true, Interval: 30 * time.Second, MinAge: 10 * time.Second, IncludeDisabled: true,
+	})
+	cfg := service.autoCleanConfig()
+	if cfg.Interval != time.Minute || cfg.MinAge != time.Minute || !cfg.IncludeDisabled || !cfg.Enabled {
+		t.Fatalf("low clamp = %#v", cfg)
+	}
+	service.UpdateAutoCleanConfig(AutoCleanConfig{
+		Enabled: false, Interval: 2 * time.Hour, MinAge: 40 * 24 * time.Hour,
+	})
+	cfg = service.autoCleanConfig()
+	if cfg.Interval != time.Hour || cfg.MinAge != 30*24*time.Hour || cfg.Enabled {
+		t.Fatalf("high clamp = %#v", cfg)
+	}
+	if got := autoCleanInterval(AutoCleanConfig{Enabled: false, Interval: time.Minute}); got != time.Hour {
+		t.Fatalf("disabled interval = %s", got)
+	}
+	if got := autoCleanInterval(AutoCleanConfig{Enabled: true, Interval: 5 * time.Minute}); got != 5*time.Minute {
+		t.Fatalf("enabled interval = %s", got)
+	}
+}
+
+func TestAutoCleanSkipsActiveInferenceLease(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 20, 22, 0, 0, 0, time.UTC)
+	service, repo := newAutoCleanTestService(t, now)
+	limiter := memory.NewConcurrencyLimiter()
+	service.SetConcurrencyLimiter(limiter)
+	value := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "active-lease", SourceKey: "active-lease",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusReauthRequired,
+		ReauthMarkedAt: ptrTime(now.Add(-2 * time.Hour)),
+	})
+	release, acquired, err := limiter.Acquire(ctx, repository.AccountConcurrencyKey(value.ID), 1)
+	if err != nil || !acquired {
+		t.Fatalf("acquire lease: acquired=%v err=%v", acquired, err)
+	}
+	service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: time.Minute, MinAge: time.Hour})
+	if err := service.runAutoCleanReauth(ctx, service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	assertPresent(t, repo, value.ID)
+	release()
+	if err := service.runAutoCleanReauth(ctx, service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	assertMissing(t, repo, value.ID)
+}
+
+func TestAutoCleanConfigRevisionRejectsOldTimerAndUnchangedUpdateDoesNotWake(t *testing.T) {
+	service, _ := newAutoCleanTestService(t, time.Date(2026, 7, 20, 23, 0, 0, 0, time.UTC))
+	service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: 5 * time.Minute, MinAge: time.Hour})
+	select {
+	case <-service.autoCleanWake:
+	default:
+		t.Fatal("initial config update did not wake scheduler")
+	}
+	cfg, revision := service.autoCleanSnapshot()
+	service.UpdateAutoCleanConfig(cfg)
+	select {
+	case <-service.autoCleanWake:
+		t.Fatal("unchanged config woke scheduler")
+	default:
+	}
+	service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: 5 * time.Minute, MinAge: 2 * time.Hour})
+	if service.autoCleanRevisionCurrent(revision, cfg) {
+		t.Fatal("old timer revision remained executable after config update")
+	}
+}
+
+type deniedAutoCleanLock struct{}
+
+func (deniedAutoCleanLock) Acquire(context.Context, string, time.Duration) (func(), bool, error) {
+	return nil, false, nil
+}
+
+func TestAutoCleanSkipsWhenDistributedLockIsHeld(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 21, 0, 0, 0, 0, time.UTC)
+	service, repo := newAutoCleanTestService(t, now)
+	service.refreshLock = deniedAutoCleanLock{}
+	value := mustUpsert(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "locked", SourceKey: "locked",
+		EncryptedAccessToken: "x", Enabled: true, AuthStatus: accountdomain.AuthStatusReauthRequired,
+		ReauthMarkedAt: ptrTime(now.Add(-2 * time.Hour)),
+	})
+	service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: time.Minute, MinAge: time.Hour})
+	if err := service.runAutoCleanReauth(ctx, service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	assertPresent(t, repo, value.ID)
+}
+
+type endlessAutoCleanRepository struct {
+	repository.AccountRepository
+	listCalls   int
+	deleteCalls int
+	deletedIDs  []uint64
+}
+
+func (r *endlessAutoCleanRepository) ListAutoCleanReauthCandidates(_ context.Context, _ time.Time, _ bool, afterID uint64, _ int) ([]uint64, error) {
+	r.listCalls++
+	ids := make([]uint64, autoCleanReauthBatchSize)
+	for index := range ids {
+		ids[index] = afterID + uint64(index) + 1
+	}
+	return ids, nil
+}
+
+func (r *endlessAutoCleanRepository) DeleteAutoCleanReauthCandidates(_ context.Context, _ time.Time, _ bool, ids []uint64) ([]uint64, error) {
+	r.deleteCalls++
+	r.deletedIDs = append(r.deletedIDs, ids...)
+	return append([]uint64(nil), ids...), nil
+}
+
+func TestAutoCleanLimitsWorkPerTick(t *testing.T) {
+	repo := &endlessAutoCleanRepository{}
+	service := NewService(repo, nil, nil, nil, nil, nil, nil)
+	service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: time.Minute, MinAge: time.Hour})
+	if err := service.runAutoCleanReauth(context.Background(), service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	if repo.listCalls != autoCleanReauthMaxDeletes || repo.deleteCalls != autoCleanReauthMaxDeletes {
+		t.Fatalf("calls list=%d delete=%d", repo.listCalls, repo.deleteCalls)
+	}
+}
+
+type activeKeyConcurrency struct {
+	active map[string]struct{}
+	all    bool
+}
+
+func (*activeKeyConcurrency) Acquire(context.Context, string, int) (func(), bool, error) {
+	return func() {}, true, nil
+}
+
+func (l *activeKeyConcurrency) Current(_ context.Context, key string) (int, error) {
+	if l.all {
+		return 1, nil
+	}
+	if _, ok := l.active[key]; ok {
+		return 1, nil
+	}
+	return 0, nil
+}
+
+func (l *activeKeyConcurrency) CurrentMany(_ context.Context, keys []string) (map[string]int, error) {
+	values := make(map[string]int, len(keys))
+	for _, key := range keys {
+		current, _ := l.Current(context.Background(), key)
+		values[key] = current
+	}
+	return values, nil
+}
+
+func TestAutoCleanActiveOnlyPagesDoNotConsumeDeleteBudget(t *testing.T) {
+	repo := &endlessAutoCleanRepository{}
+	service := NewService(repo, nil, nil, nil, nil, nil, nil)
+	active := make(map[string]struct{}, 2*autoCleanReauthBatchSize)
+	for id := uint64(1); id <= 2*autoCleanReauthBatchSize; id++ {
+		active[repository.AccountConcurrencyKey(id)] = struct{}{}
+	}
+	service.SetConcurrencyLimiter(&activeKeyConcurrency{active: active})
+	service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: time.Minute, MinAge: time.Hour})
+	if err := service.runAutoCleanReauth(context.Background(), service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	if repo.listCalls != autoCleanReauthMaxDeletes+2 || repo.deleteCalls != autoCleanReauthMaxDeletes {
+		t.Fatalf("calls list=%d delete=%d", repo.listCalls, repo.deleteCalls)
+	}
+	if len(repo.deletedIDs) == 0 || repo.deletedIDs[0] != 2*autoCleanReauthBatchSize+1 {
+		t.Fatalf("first deleted id=%v", repo.deletedIDs)
+	}
+}
+
+func TestAutoCleanActiveOnlySourceIsBoundedByScanBudget(t *testing.T) {
+	repo := &endlessAutoCleanRepository{}
+	service := NewService(repo, nil, nil, nil, nil, nil, nil)
+	service.SetConcurrencyLimiter(&activeKeyConcurrency{all: true})
+	service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: time.Minute, MinAge: time.Hour})
+	if err := service.runAutoCleanReauth(context.Background(), service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	if repo.listCalls != autoCleanReauthMaxScans || repo.deleteCalls != 0 {
+		t.Fatalf("calls list=%d delete=%d", repo.listCalls, repo.deleteCalls)
+	}
+}
+
+type configChangingConcurrency struct {
+	service *Service
+	once    bool
+}
+
+func (c *configChangingConcurrency) Acquire(context.Context, string, int) (func(), bool, error) {
+	return func() {}, true, nil
+}
+
+func (c *configChangingConcurrency) Current(context.Context, string) (int, error) {
+	if !c.once {
+		c.once = true
+		c.service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: 5 * time.Minute, MinAge: 2 * time.Hour})
+	}
+	return 0, nil
+}
+
+func TestAutoCleanPolicyChangeAbortsBeforeDelete(t *testing.T) {
+	repo := &endlessAutoCleanRepository{}
+	service := NewService(repo, nil, nil, nil, nil, nil, nil)
+	service.SetConcurrencyLimiter(&configChangingConcurrency{service: service})
+	service.UpdateAutoCleanConfig(AutoCleanConfig{Enabled: true, Interval: 5 * time.Minute, MinAge: time.Hour})
+	if err := service.runAutoCleanReauth(context.Background(), service.autoCleanConfig()); err != nil {
+		t.Fatal(err)
+	}
+	if repo.deleteCalls != 0 {
+		t.Fatalf("delete calls after policy change=%d", repo.deleteCalls)
+	}
+}

backend/internal/application/account/batch_quota_test.go

@@ -0,0 +1,93 @@
+package account
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	"github.com/chenyme/grok2api/backend/internal/infra/runtime/memory"
+	"github.com/chenyme/grok2api/backend/internal/infra/security"
+)
+
+func TestBatchRefreshQuotaSupportsWebAndConsole(t *testing.T) {
+	for _, providerValue := range []accountdomain.Provider{accountdomain.ProviderWeb, accountdomain.ProviderConsole} {
+		t.Run(string(providerValue), func(t *testing.T) {
+			ctx := context.Background()
+			database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "quota.db"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = database.Close() })
+			if err := database.InitializeSchema(ctx); err != nil {
+				t.Fatal(err)
+			}
+			cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+			if err != nil {
+				t.Fatal(err)
+			}
+			encryptedToken, err := cipher.Encrypt("test-token")
+			if err != nil {
+				t.Fatal(err)
+			}
+			repository := relational.NewAccountRepository(database)
+			ids := make([]uint64, 0, 2)
+			for index := 1; index <= 2; index++ {
+				value, _, createErr := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+					Provider: providerValue, AuthType: accountdomain.AuthTypeSSO,
+					Name: fmt.Sprintf("account-%d", index), SourceKey: fmt.Sprintf("source-%d", index),
+					EncryptedAccessToken: encryptedToken, Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+				})
+				if createErr != nil {
+					t.Fatal(createErr)
+				}
+				ids = append(ids, value.ID)
+			}
+			adapter := &selectedQuotaAdapter{providerValue: providerValue}
+			service := NewService(repository, nil, nil, nil, provider.NewRegistry(adapter), cipher, memory.NewLockStore())
+
+			succeeded, failed, err := service.BatchRefreshQuota(ctx, ids)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if succeeded != 2 || failed != 0 || adapter.calls.Load() != 2 {
+				t.Fatalf("succeeded=%d failed=%d calls=%d", succeeded, failed, adapter.calls.Load())
+			}
+			windows, err := repository.GetQuotaWindows(ctx, ids)
+			if err != nil {
+				t.Fatal(err)
+			}
+			for _, id := range ids {
+				if len(windows[id]) != 1 || windows[id][0].Remaining != 7 {
+					t.Fatalf("account %d windows = %#v", id, windows[id])
+				}
+			}
+		})
+	}
+}
+
+type selectedQuotaAdapter struct {
+	providerValue accountdomain.Provider
+	calls         atomic.Int64
+}
+
+func (a *selectedQuotaAdapter) Provider() accountdomain.Provider { return a.providerValue }
+
+func (a *selectedQuotaAdapter) SyncQuota(_ context.Context, _ accountdomain.Credential) (provider.QuotaSnapshot, error) {
+	a.calls.Add(1)
+	now := time.Now().UTC()
+	return provider.QuotaSnapshot{
+		Tier: accountdomain.WebTierSuper, SyncedAt: now,
+		Windows: []accountdomain.QuotaWindow{{Mode: "default", Remaining: 7, Total: 10, SyncedAt: &now, UpdatedAt: now}},
+	}, nil
+}
+
+func (a *selectedQuotaAdapter) SyncQuotaMode(_ context.Context, _ accountdomain.Credential, mode string) (accountdomain.QuotaWindow, error) {
+	return accountdomain.QuotaWindow{Mode: mode}, nil
+}

backend/internal/application/account/batch_update_test.go

@@ -0,0 +1,79 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"slices"
+	"testing"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+type batchUpdateRepository struct {
+	repository.AccountRepository
+	updateErr  error
+	updatedIDs []uint64
+}
+
+func (r *batchUpdateRepository) UpdateMany(_ context.Context, providerValue accountdomain.Provider, ids []uint64, _ repository.AccountUpdates) (int64, error) {
+	if providerValue != accountdomain.ProviderBuild {
+		return 0, errors.New("unexpected provider")
+	}
+	r.updatedIDs = append([]uint64(nil), ids...)
+	if r.updateErr != nil {
+		return 0, r.updateErr
+	}
+	return int64(len(ids)), nil
+}
+
+func TestBatchUpdateSupportsMoreThanAdminPageLimit(t *testing.T) {
+	ids := make([]uint64, 2501)
+	for index := range ids {
+		ids[index] = uint64(index + 1)
+	}
+	repo := &batchUpdateRepository{}
+	service := NewService(repo, nil, nil, nil, nil, nil, nil)
+	maxConcurrent := 3
+
+	updated, err := service.BatchUpdate(context.Background(), accountdomain.ProviderBuild, ids, UpdateInput{MaxConcurrent: &maxConcurrent})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if updated != int64(len(ids)) || !slices.Equal(repo.updatedIDs, ids) {
+		t.Fatalf("updated = %d, ids = %d", updated, len(repo.updatedIDs))
+	}
+}
+
+func TestBatchUpdatePreservesProviderMismatchSemantics(t *testing.T) {
+	ids := make([]uint64, 501)
+	for index := range ids {
+		ids[index] = uint64(index + 1)
+	}
+	repo := &batchUpdateRepository{updateErr: repository.ErrAccountPoolMismatch}
+	service := NewService(repo, nil, nil, nil, nil, nil, nil)
+	maxConcurrent := 3
+
+	_, err := service.BatchUpdate(context.Background(), accountdomain.ProviderBuild, ids, UpdateInput{MaxConcurrent: &maxConcurrent})
+	if !errors.Is(err, ErrAccountPoolMismatch) {
+		t.Fatalf("error = %v, want account pool mismatch", err)
+	}
+}
+
+func TestBatchUpdateRetainsBoundedRequestSize(t *testing.T) {
+	ids := make([]uint64, maxBatchUpdateAccounts+1)
+	for index := range ids {
+		ids[index] = uint64(index + 1)
+	}
+	repo := &batchUpdateRepository{}
+	service := NewService(repo, nil, nil, nil, nil, nil, nil)
+	maxConcurrent := 3
+
+	_, err := service.BatchUpdate(context.Background(), accountdomain.ProviderBuild, ids, UpdateInput{MaxConcurrent: &maxConcurrent})
+	if !errors.Is(err, ErrInvalidInput) {
+		t.Fatalf("error = %v, want invalid input", err)
+	}
+	if len(repo.updatedIDs) != 0 {
+		t.Fatal("oversized update reached repository")
+	}
+}

backend/internal/application/account/build_super_entitlement_test.go

@@ -0,0 +1,189 @@
+package account
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	"github.com/chenyme/grok2api/backend/internal/infra/security"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+func openAccountService(t *testing.T) (*Service, repository.AccountRepository) {
+	t.Helper()
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "build-super.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	audits := relational.NewAuditRepository(database)
+	cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	service := NewService(accounts, audits, nil, nil, nil, cipher, nil)
+	return service, accounts
+}
+
+type credentialMetadataAdapterStub struct {
+	calls *atomic.Int32
+}
+
+func (credentialMetadataAdapterStub) Provider() accountdomain.Provider {
+	return accountdomain.ProviderBuild
+}
+
+func (s credentialMetadataAdapterStub) CredentialMetadata(credential accountdomain.Credential) provider.CredentialMetadata {
+	if s.calls != nil {
+		s.calls.Add(1)
+	}
+	return provider.CredentialMetadata{BuildBotFlagged: credential.ID == 1}
+}
+
+func TestBuildBotFlagSummaryUsesShortLivedCache(t *testing.T) {
+	ctx := context.Background()
+	service, accounts := openAccountService(t)
+	var calls atomic.Int32
+	service.providers = provider.NewRegistry(credentialMetadataAdapterStub{calls: &calls})
+	if _, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "flagged", SourceKey: "cached-build-bot-flag",
+		EncryptedAccessToken: "enc", AuthStatus: accountdomain.AuthStatusActive, Enabled: true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := service.buildBotFlaggedAccountIDs(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := service.buildBotFlaggedAccountIDs(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if got := calls.Load(); got != 1 {
+		t.Fatalf("metadata inspections = %d, want 1", got)
+	}
+	service.invalidateBuildBotFlagCache()
+	if _, err := service.buildBotFlaggedAccountIDs(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if got := calls.Load(); got != 2 {
+		t.Fatalf("metadata inspections after invalidation = %d, want 2", got)
+	}
+}
+
+func TestAccountViewsIncludeBuildBotFlagMetadata(t *testing.T) {
+	ctx := context.Background()
+	service, accounts := openAccountService(t)
+	service.providers = provider.NewRegistry(credentialMetadataAdapterStub{})
+	build, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "flagged", SourceKey: "build-bot-flag",
+		EncryptedAccessToken: "enc", AuthStatus: accountdomain.AuthStatusActive, Enabled: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	view, err := service.Get(ctx, build.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !view.BuildBotFlagged {
+		t.Fatal("single account view did not include bot flag metadata")
+	}
+	views, _, err := service.List(ctx, 1, 20, "", ListFilter{Provider: string(accountdomain.ProviderBuild)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(views) != 1 || !views[0].BuildBotFlagged {
+		t.Fatalf("list views = %#v", views)
+	}
+	normal, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "normal", SourceKey: "build-normal",
+		EncryptedAccessToken: "enc", AuthStatus: accountdomain.AuthStatusActive, Enabled: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	views, total, err := service.List(ctx, 1, 20, "", ListFilter{Provider: string(accountdomain.ProviderBuild), Risk: "flagged"})
+	if err != nil || total != 1 || len(views) != 1 || views[0].Credential.ID != build.ID {
+		t.Fatalf("flagged views=%#v total=%d err=%v", views, total, err)
+	}
+	views, total, err = service.List(ctx, 1, 20, "", ListFilter{Provider: string(accountdomain.ProviderBuild), Risk: "normal"})
+	if err != nil || total != 1 || len(views) != 1 || views[0].Credential.ID != normal.ID {
+		t.Fatalf("normal views=%#v total=%d err=%v", views, total, err)
+	}
+	if _, _, err := service.List(ctx, 1, 20, "", ListFilter{Provider: string(accountdomain.ProviderWeb), Risk: "flagged"}); !errors.Is(err, ErrInvalidFilter) {
+		t.Fatalf("non-Build risk filter err = %v", err)
+	}
+	summary, err := service.Summary(ctx)
+	if err != nil || summary.Risk != 1 {
+		t.Fatalf("summary=%#v err=%v", summary, err)
+	}
+}
+
+func TestUpdateBuildSuperEntitledBuildOnly(t *testing.T) {
+	ctx := context.Background()
+	service, accounts := openAccountService(t)
+	build, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "build", SourceKey: "build-super-patch",
+		EncryptedAccessToken: "enc", AuthStatus: accountdomain.AuthStatusActive, Enabled: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	web, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web", SourceKey: "web-super-patch",
+		EncryptedAccessToken: "enc", AuthStatus: accountdomain.AuthStatusActive, Enabled: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	trueVal := true
+	view, err := service.Update(ctx, build.ID, UpdateInput{BuildSuperEntitled: &trueVal})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !view.Credential.BuildSuperEntitled {
+		t.Fatalf("build entitlement not set: %#v", view.Credential)
+	}
+	if view.Quota.Type != QuotaTypePaid || view.Quota.Source != "buildSuperEntitlement" || view.Quota.Confidence != "confirmed" {
+		t.Fatalf("quota = %#v", view.Quota)
+	}
+	// 零 Billing 数值保持未知/零。
+	if view.Quota.LimitKnown || view.Quota.Used != 0 || view.Quota.Limit != 0 {
+		t.Fatalf("must not fabricate limits: %#v", view.Quota)
+	}
+	if _, err := service.Update(ctx, web.ID, UpdateInput{BuildSuperEntitled: &trueVal}); !errors.Is(err, ErrInvalidInput) {
+		t.Fatalf("web update err = %v", err)
+	}
+	xaiMode := accountdomain.BuildRouteXAI
+	view, err = service.Update(ctx, build.ID, UpdateInput{BuildRouteMode: &xaiMode})
+	if err != nil || view.Credential.BuildRouteMode != accountdomain.BuildRouteXAI {
+		t.Fatalf("route update view=%#v err=%v", view.Credential, err)
+	}
+	if _, err := service.Update(ctx, web.ID, UpdateInput{BuildRouteMode: &xaiMode}); !errors.Is(err, ErrInvalidInput) {
+		t.Fatalf("web route update err = %v", err)
+	}
+	invalidMode := accountdomain.BuildRouteMode("invalid")
+	if _, err := service.Update(ctx, build.ID, UpdateInput{BuildRouteMode: &invalidMode}); !errors.Is(err, ErrInvalidInput) {
+		t.Fatalf("invalid route update err = %v", err)
+	}
+	// 清除 entitlement
+	falseVal := false
+	view, err = service.Update(ctx, build.ID, UpdateInput{BuildSuperEntitled: &falseVal})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if view.Credential.BuildSuperEntitled || view.Quota.Type != QuotaTypeUnknown {
+		t.Fatalf("cleared view = %#v quota=%#v", view.Credential, view.Quota)
+	}
+}

backend/internal/application/account/console_quota_test.go

@@ -0,0 +1,25 @@
+package account
+
+import (
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+)
+
+func TestPreserveActiveQuotaWindowsUntilReset(t *testing.T) {
+	now := time.Now().UTC()
+	future := now.Add(time.Hour)
+	past := now.Add(-time.Second)
+	incoming := []accountdomain.QuotaWindow{{Mode: "console", Remaining: 20, Total: 20}}
+
+	active := preserveActiveQuotaWindows([]accountdomain.QuotaWindow{{Mode: "console", Remaining: 7, Total: 20, ResetAt: &future}}, incoming, now)
+	if len(active) != 1 || active[0].Remaining != 7 {
+		t.Fatalf("active window = %#v", active)
+	}
+
+	expired := preserveActiveQuotaWindows([]accountdomain.QuotaWindow{{Mode: "console", Remaining: 0, Total: 20, ResetAt: &past}}, incoming, now)
+	if len(expired) != 1 || expired[0].Remaining != 20 {
+		t.Fatalf("expired window = %#v", expired)
+	}
+}

backend/internal/application/account/conversion_test.go

@@ -0,0 +1,278 @@
+package account
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	"github.com/chenyme/grok2api/backend/internal/infra/runtime/memory"
+	"github.com/chenyme/grok2api/backend/internal/infra/security"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+func TestConvertWebAccountsToBuildIsIdempotent(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "conversion.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	encryptedSSO, err := cipher.Encrypt("test-sso")
+	if err != nil {
+		t.Fatal(err)
+	}
+	repository := relational.NewAccountRepository(database)
+	webAccount, _, err := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web", SourceKey: "web-source",
+		EncryptedAccessToken: encryptedSSO, Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &buildConversionAdapter{}
+	service := NewService(repository, nil, nil, nil, provider.NewRegistry(adapter), cipher, memory.NewLockStore())
+	first, err := service.ConvertWebAccountsToBuild(ctx, []uint64{webAccount.ID})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first.Created != 1 || first.Linked != 0 || first.Skipped != 0 || first.Failed != 0 || len(first.BuildAccountIDs) != 1 {
+		t.Fatalf("first conversion = %#v", first)
+	}
+	var secondProgress [][2]int
+	second, err := service.ConvertWebAccountsToBuildWithProgress(ctx, []uint64{webAccount.ID}, nil, func(completed, total int) error {
+		secondProgress = append(secondProgress, [2]int{completed, total})
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if second.Created != 0 || second.Linked != 0 || second.Skipped != 1 || second.Failed != 0 || adapter.calls.Load() != 1 {
+		t.Fatalf("second conversion = %#v, calls = %d", second, adapter.calls.Load())
+	}
+	if len(secondProgress) != 1 || secondProgress[0] != [2]int{0, 0} {
+		t.Fatalf("second progress = %#v", secondProgress)
+	}
+	linkedWeb, err := repository.Get(ctx, webAccount.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if linkedWeb.LinkedAccountID != first.BuildAccountIDs[0] || linkedWeb.LinkedProvider != accountdomain.ProviderBuild {
+		t.Fatalf("linked web account = %#v", linkedWeb)
+	}
+}
+
+func TestConvertWebAccountsToBuildAllRefreshesLinkedCredential(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "conversion-refresh.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	encryptedSSO, err := cipher.Encrypt("test-sso")
+	if err != nil {
+		t.Fatal(err)
+	}
+	repository := relational.NewAccountRepository(database)
+	webAccount, _, err := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web", SourceKey: "web-source",
+		EncryptedAccessToken: encryptedSSO, Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &buildConversionAdapter{}
+	service := NewService(repository, nil, nil, nil, provider.NewRegistry(adapter), cipher, memory.NewLockStore())
+	first, err := service.ConvertWebAccountsToBuild(ctx, []uint64{webAccount.ID})
+	if err != nil {
+		t.Fatal(err)
+	}
+	refreshed, err := service.ConvertWebAccountsToBuildWithStrategy(ctx, []uint64{webAccount.ID}, BuildConversionAll, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if refreshed.Created != 0 || refreshed.Linked != 1 || refreshed.Skipped != 0 || refreshed.Failed != 0 || len(refreshed.BuildAccountIDs) != 1 {
+		t.Fatalf("refreshed conversion = %#v", refreshed)
+	}
+	if refreshed.BuildAccountIDs[0] != first.BuildAccountIDs[0] || adapter.calls.Load() != 2 {
+		t.Fatalf("build ids first=%v refreshed=%v calls=%d", first.BuildAccountIDs, refreshed.BuildAccountIDs, adapter.calls.Load())
+	}
+	buildAccount, err := repository.Get(ctx, first.BuildAccountIDs[0])
+	if err != nil {
+		t.Fatal(err)
+	}
+	accessToken, err := cipher.Decrypt(buildAccount.EncryptedAccessToken)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if accessToken != "access-2" {
+		t.Fatalf("access token = %q", accessToken)
+	}
+}
+
+func TestConvertAllWebAccountsToBuildUsesUnlinkedPool(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "conversion-all.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	encryptedSSO, err := cipher.Encrypt("test-sso")
+	if err != nil {
+		t.Fatal(err)
+	}
+	repository := relational.NewAccountRepository(database)
+	createWeb := func(name, source string) accountdomain.Credential {
+		value, _, createErr := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+			Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: name, SourceKey: source,
+			EncryptedAccessToken: encryptedSSO, Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+		})
+		if createErr != nil {
+			t.Fatal(createErr)
+		}
+		return value
+	}
+	firstWeb := createWeb("web-1", "web-source-1")
+	createWeb("web-2", "web-source-2")
+	adapter := &buildConversionAdapter{}
+	service := NewService(repository, nil, nil, nil, provider.NewRegistry(adapter), cipher, memory.NewLockStore())
+	if _, err := service.ConvertWebAccountsToBuild(ctx, []uint64{firstWeb.ID}); err != nil {
+		t.Fatal(err)
+	}
+	observed := make([]uint64, 0, 1)
+	progress := make([][2]int, 0, 2)
+	result, err := service.ConvertAllWebAccountsToBuildWithProgress(ctx, func(accountID uint64) error {
+		observed = append(observed, accountID)
+		return nil
+	}, func(completed, total int) error {
+		progress = append(progress, [2]int{completed, total})
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Created != 1 || result.Linked != 0 || result.Skipped != 0 || result.Failed != 0 || adapter.calls.Load() != 2 || len(observed) != 1 || observed[0] != result.BuildAccountIDs[0] {
+		t.Fatalf("all conversion = %#v, calls = %d", result, adapter.calls.Load())
+	}
+	if len(progress) != 2 || progress[0] != [2]int{0, 1} || progress[1] != [2]int{1, 1} {
+		t.Fatalf("progress = %#v", progress)
+	}
+	empty, err := service.ConvertAllWebAccountsToBuild(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if empty.Created != 0 || empty.Linked != 0 || empty.Skipped != 0 || empty.Failed != 0 || len(empty.BuildAccountIDs) != 0 || adapter.calls.Load() != 2 {
+		t.Fatalf("empty conversion = %#v, calls = %d", empty, adapter.calls.Load())
+	}
+	resynced, err := service.ConvertAllWebAccountsToBuildWithStrategy(ctx, BuildConversionAll, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resynced.Created != 0 || resynced.Linked != 2 || resynced.Skipped != 0 || resynced.Failed != 0 || len(resynced.BuildAccountIDs) != 2 || adapter.calls.Load() != 4 {
+		t.Fatalf("resynced conversion = %#v, calls = %d", resynced, adapter.calls.Load())
+	}
+}
+
+func TestConvertAllWebAccountsToBuildProcessesMoreThanLegacyLimitInBatches(t *testing.T) {
+	const totalAccounts = maxBuildConversionAccounts + 1
+	cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	encryptedSSO, err := cipher.Encrypt("test-sso")
+	if err != nil {
+		t.Fatal(err)
+	}
+	repository := &conversionBatchRepository{total: totalAccounts, encryptedSSO: encryptedSSO}
+	adapter := &buildConversionAdapter{}
+	service := NewService(repository, nil, nil, nil, provider.NewRegistry(adapter), cipher, memory.NewLockStore())
+	progress := make([][2]int, 0, totalAccounts+1)
+	result, err := service.ConvertAllWebAccountsToBuildWithProgress(context.Background(), nil, func(completed, total int) error {
+		progress = append(progress, [2]int{completed, total})
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Created != totalAccounts || result.Linked != 0 || result.Skipped != 0 || result.Failed != 0 || len(result.BuildAccountIDs) != totalAccounts {
+		t.Fatalf("conversion result = %#v", result)
+	}
+	if adapter.calls.Load() != totalAccounts || repository.listCalls != 2 {
+		t.Fatalf("adapter calls = %d, repository batches = %d", adapter.calls.Load(), repository.listCalls)
+	}
+	if len(progress) != totalAccounts+1 || progress[0] != [2]int{0, totalAccounts} || progress[len(progress)-1] != [2]int{totalAccounts, totalAccounts} {
+		t.Fatalf("progress first=%v last=%v count=%d", progress[0], progress[len(progress)-1], len(progress))
+	}
+}
+
+type conversionBatchRepository struct {
+	repository.AccountRepository
+	total        int
+	encryptedSSO string
+	listCalls    int
+	nextBuildID  atomic.Uint64
+}
+
+func (r *conversionBatchRepository) ListUnlinkedWebAccountIDs(_ context.Context, afterID uint64, limit int) ([]uint64, int64, error) {
+	r.listCalls++
+	ids := make([]uint64, 0, limit)
+	for id := afterID + 1; id <= uint64(r.total) && len(ids) < limit; id++ {
+		ids = append(ids, id)
+	}
+	return ids, int64(r.total), nil
+}
+
+func (r *conversionBatchRepository) Get(_ context.Context, id uint64) (accountdomain.Credential, error) {
+	return accountdomain.Credential{
+		ID: id, Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO,
+		Name: fmt.Sprintf("web-%d", id), SourceKey: fmt.Sprintf("web-source-%d", id),
+		EncryptedAccessToken: r.encryptedSSO, Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	}, nil
+}
+
+func (r *conversionBatchRepository) UpsertByIdentity(_ context.Context, value accountdomain.Credential) (accountdomain.Credential, bool, error) {
+	value.ID = 10_000 + r.nextBuildID.Add(1)
+	return value, true, nil
+}
+
+func (r *conversionBatchRepository) LinkWebToBuild(context.Context, uint64, uint64) error { return nil }
+
+type buildConversionAdapter struct{ calls atomic.Int64 }
+
+func (a *buildConversionAdapter) Provider() accountdomain.Provider { return accountdomain.ProviderWeb }
+
+func (a *buildConversionAdapter) ConvertToBuild(_ context.Context, credential accountdomain.Credential) (provider.CredentialSeed, error) {
+	call := a.calls.Add(1)
+	return provider.CredentialSeed{
+		Provider: accountdomain.ProviderBuild, AuthType: accountdomain.AuthTypeOAuth, Name: "build", UserID: credential.SourceKey,
+		SourceKey: fmt.Sprintf("converted:%s:%d", credential.SourceKey, call), OIDCClientID: "client",
+		AccessToken: fmt.Sprintf("access-%d", call), RefreshToken: fmt.Sprintf("refresh-%d", call), ExpiresAt: time.Now().UTC().Add(time.Hour),
+	}, nil
+}

backend/internal/application/account/credential_refresh_test.go

@@ -0,0 +1,706 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	"github.com/chenyme/grok2api/backend/internal/infra/runtime/memory"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+func TestEnsureCredentialReusesRotatedTokenAndThrottlesForcedRefresh(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 11, 12, 0, 0, 0, time.UTC)
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+
+	first, err := service.EnsureCredential(ctx, credential, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if adapter.refreshCount.Load() != 1 || first.EncryptedAccessToken != "access-1" {
+		t.Fatalf("first refresh = %#v, count = %d", first, adapter.refreshCount.Load())
+	}
+
+	fromStaleRequest, err := service.EnsureCredential(ctx, credential, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if adapter.refreshCount.Load() != 1 || fromStaleRequest.EncryptedAccessToken != first.EncryptedAccessToken {
+		t.Fatalf("stale request caused another refresh: count = %d", adapter.refreshCount.Load())
+	}
+
+	duringCooldown, err := service.EnsureCredential(ctx, first, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if adapter.refreshCount.Load() != 1 || duringCooldown.EncryptedAccessToken != first.EncryptedAccessToken {
+		t.Fatalf("forced refresh cooldown failed: count = %d", adapter.refreshCount.Load())
+	}
+
+	now = now.Add(forcedRefreshMinInterval + time.Second)
+	afterCooldown, err := service.EnsureCredential(ctx, first, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if adapter.refreshCount.Load() != 2 || afterCooldown.EncryptedAccessToken != "access-2" {
+		t.Fatalf("refresh after cooldown = %#v, count = %d", afterCooldown, adapter.refreshCount.Load())
+	}
+
+	manual, err := service.ensureCredential(ctx, afterCooldown, ensureCredentialOptions{force: true, bypassCooldown: true, retryPermanentOnce: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if adapter.refreshCount.Load() != 3 || manual.EncryptedAccessToken != "access-3" {
+		t.Fatalf("manual refresh did not bypass cooldown: count = %d", adapter.refreshCount.Load())
+	}
+}
+
+func TestEnsureCredentialCollapsesConcurrentForcedRefreshes(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 11, 12, 0, 0, 0, time.UTC)
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+	adapter.delay = 30 * time.Millisecond
+
+	const callers = 20
+	start := make(chan struct{})
+	errors := make(chan error, callers)
+	var workers sync.WaitGroup
+	workers.Add(callers)
+	for range callers {
+		go func() {
+			defer workers.Done()
+			<-start
+			value, err := service.EnsureCredential(ctx, credential, true)
+			if err == nil && value.EncryptedAccessToken != "access-1" {
+				err = fmt.Errorf("access token = %q", value.EncryptedAccessToken)
+			}
+			errors <- err
+		}()
+	}
+	close(start)
+	workers.Wait()
+	close(errors)
+	for err := range errors {
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	if adapter.refreshCount.Load() != 1 {
+		t.Fatalf("refresh count = %d", adapter.refreshCount.Load())
+	}
+}
+
+func TestEnsureCredentialCollapsesRefreshAcrossServiceInstances(t *testing.T) {
+	ctx := context.Background()
+	now := time.Now().UTC()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "credential-refresh-multi-instance.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer database.Close()
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	repository := relational.NewAccountRepository(database)
+	credential, _, err := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "multi-instance", SourceKey: "multi-instance",
+		EncryptedAccessToken: "access-0", EncryptedRefreshToken: "refresh-0", ExpiresAt: now.Add(time.Hour),
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, MaxConcurrent: 1,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &credentialRefreshAdapter{delay: 40 * time.Millisecond}
+	registry := provider.NewRegistry(adapter)
+	lock := memory.NewLockStore()
+	first := NewService(repository, nil, nil, nil, registry, nil, lock)
+	second := NewService(repository, nil, nil, nil, registry, nil, lock)
+	start := make(chan struct{})
+	errors := make(chan error, 2)
+	for _, service := range []*Service{first, second} {
+		go func(service *Service) {
+			<-start
+			_, refreshErr := service.EnsureCredential(ctx, credential, true)
+			errors <- refreshErr
+		}(service)
+	}
+	close(start)
+	for range 2 {
+		if err := <-errors; err != nil {
+			t.Fatal(err)
+		}
+	}
+	if adapter.refreshCount.Load() != 1 {
+		t.Fatalf("refresh count = %d", adapter.refreshCount.Load())
+	}
+}
+
+func TestEnsureCredentialRefreshesWhenAccessTokenIsMissing(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 11, 12, 0, 0, 0, time.UTC)
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+	credential, err := service.accounts.UpdateTokens(ctx, credential.ID, "", "refresh-only", now.Add(time.Hour))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	refreshed, err := service.EnsureCredential(ctx, credential, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if adapter.refreshCount.Load() != 1 || refreshed.EncryptedAccessToken != "access-1" {
+		t.Fatalf("refresh-only credential was not refreshed: %#v, count = %d", refreshed, adapter.refreshCount.Load())
+	}
+}
+
+func TestCredentialRefreshSchedulerRefreshesOnlyDueAccounts(t *testing.T) {
+	ctx := context.Background()
+	now := time.Now().UTC()
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return time.Now().UTC() }
+	dueAt := now.Add(-time.Minute)
+	credential.RefreshDueAt = &dueAt
+	credential, err := service.accounts.Update(ctx, credential)
+	if err != nil {
+		t.Fatal(err)
+	}
+	far, _, err := service.accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "far", SourceKey: "far",
+		EncryptedAccessToken: "far-access", EncryptedRefreshToken: "far-refresh", ExpiresAt: now.Add(6 * time.Hour),
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, MaxConcurrent: 1,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	runCtx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() {
+		service.RunCredentialRefresh(runCtx)
+		close(done)
+	}()
+	t.Cleanup(func() {
+		cancel()
+		select {
+		case <-done:
+		case <-time.After(time.Second):
+			t.Fatal("credential refresh scheduler did not stop")
+		}
+	})
+
+	deadline := time.Now().Add(2 * time.Second)
+	var updated accountdomain.Credential
+	for time.Now().Before(deadline) {
+		updated, err = service.accounts.Get(ctx, credential.ID)
+		if err == nil && adapter.refreshCount.Load() == 1 && updated.LastRefreshAt != nil && updated.RefreshFailureCount == 0 {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	if adapter.refreshCount.Load() != 1 {
+		t.Fatalf("refresh count = %d", adapter.refreshCount.Load())
+	}
+	if err != nil {
+		t.Fatal(err)
+	}
+	if updated.RefreshDueAt == nil || !updated.RefreshDueAt.After(time.Now()) || updated.LastRefreshAt == nil || updated.RefreshFailureCount != 0 {
+		t.Fatalf("updated credential = %#v", updated)
+	}
+	farUpdated, err := service.accounts.Get(ctx, far.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if farUpdated.EncryptedAccessToken != "far-access" || farUpdated.LastRefreshAt != nil {
+		t.Fatalf("far credential was refreshed: %#v", farUpdated)
+	}
+}
+
+func TestStartupRecoveryPreservesFutureRefreshSchedule(t *testing.T) {
+	now := time.Now().UTC()
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+	originalDue := credential.RefreshDueAt
+
+	report, err := service.RecoverCriticalCredentials(context.Background(), 2*time.Minute, 100)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if report.CriticalFound != 0 || adapter.refreshCount.Load() != 0 {
+		t.Fatalf("report=%#v refreshes=%d", report, adapter.refreshCount.Load())
+	}
+	stored, err := service.accounts.Get(context.Background(), credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if originalDue == nil || stored.RefreshDueAt == nil || !stored.RefreshDueAt.Equal(*originalDue) {
+		t.Fatalf("refresh due changed: before=%v after=%v", originalDue, stored.RefreshDueAt)
+	}
+}
+
+func TestStartupRecoveryRefreshesExpiredCredential(t *testing.T) {
+	now := time.Now().UTC()
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+	expired, err := service.accounts.UpdateTokens(context.Background(), credential.ID, credential.EncryptedAccessToken, credential.EncryptedRefreshToken, now.Add(-time.Minute))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if expired.RefreshDueAt == nil || expired.RefreshDueAt.After(now) {
+		t.Fatalf("expired refresh due = %v", expired.RefreshDueAt)
+	}
+
+	report, err := service.RecoverCriticalCredentials(context.Background(), 2*time.Minute, 100)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if report.CriticalFound != 1 || report.Refreshed != 1 || report.Failed != 0 || adapter.refreshCount.Load() != 1 {
+		t.Fatalf("report=%#v refreshes=%d", report, adapter.refreshCount.Load())
+	}
+}
+
+func TestStartupRecoveryRespectsContextBudget(t *testing.T) {
+	now := time.Now().UTC()
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+	if _, err := service.accounts.UpdateTokens(context.Background(), credential.ID, credential.EncryptedAccessToken, credential.EncryptedRefreshToken, now.Add(-time.Minute)); err != nil {
+		t.Fatal(err)
+	}
+	adapter.delay = time.Second
+	ctx, cancel := context.WithTimeout(context.Background(), 25*time.Millisecond)
+	defer cancel()
+	started := time.Now()
+	_, err := service.RecoverCriticalCredentials(ctx, 2*time.Minute, 100)
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("err = %v", err)
+	}
+	if elapsed := time.Since(started); elapsed > 250*time.Millisecond {
+		t.Fatalf("startup recovery exceeded budget: %s", elapsed)
+	}
+}
+
+func TestCredentialRefreshDueQueryStaysBoundedForLargePool(t *testing.T) {
+	ctx := context.Background()
+	now := time.Now().UTC()
+	service, _, _ := newCredentialRefreshTestService(t, now)
+	values := make([]accountdomain.Credential, 0, 1000)
+	for index := range 1000 {
+		name := fmt.Sprintf("large-%04d", index)
+		values = append(values, accountdomain.Credential{
+			Provider: accountdomain.ProviderBuild, Name: name, SourceKey: name,
+			EncryptedAccessToken: "access", EncryptedRefreshToken: "refresh", ExpiresAt: now.Add(time.Minute),
+			Enabled: true, AuthStatus: accountdomain.AuthStatusActive, MaxConcurrent: 1,
+		})
+	}
+	if _, err := service.accounts.UpsertManyByIdentity(ctx, values); err != nil {
+		t.Fatal(err)
+	}
+	ids, err := service.accounts.ListDueCredentialRefreshIDs(ctx, now, credentialRefreshBatchSize)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(ids) != credentialRefreshBatchSize {
+		t.Fatalf("due batch size = %d", len(ids))
+	}
+	next, err := service.accounts.NextCredentialRefreshDueAt(ctx)
+	if err != nil || next == nil || next.After(now) {
+		t.Fatalf("next due = %v, err = %v", next, err)
+	}
+}
+
+func TestCredentialRefreshFailureDistinguishesTransientAndPermanent(t *testing.T) {
+	ctx := context.Background()
+	now := time.Now().UTC()
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+
+	adapter.refreshErr = &provider.CredentialRefreshError{Status: 503, Code: "oauth_unavailable", Message: "Please retry later", Response: `{"error":"oauth_unavailable","message":"Please retry later"}`}
+	if _, err := service.EnsureCredential(ctx, credential, true); err == nil {
+		t.Fatal("transient refresh unexpectedly succeeded")
+	}
+	transient, err := service.accounts.Get(ctx, credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if transient.AuthStatus != accountdomain.AuthStatusActive || transient.RefreshFailureCount != 1 || transient.LastRefreshErrorStatus != 503 || transient.LastRefreshErrorCode != "oauth_unavailable" || transient.LastRefreshErrorMessage != "Please retry later" || transient.LastRefreshErrorResponse == "" || transient.RefreshPermanent || transient.RefreshDueAt == nil || !transient.RefreshDueAt.After(now) {
+		t.Fatalf("transient state = %#v", transient)
+	}
+
+	service.clearRefreshState(credential.ID)
+	adapter.refreshErr = &provider.CredentialRefreshError{Status: 400, Code: "invalid_grant", Message: "Refresh token has expired", Response: `{"error":"invalid_grant","error_description":"Refresh token has expired"}`, Permanent: true}
+	if _, err := service.EnsureCredential(ctx, transient, true); err == nil {
+		t.Fatal("permanent refresh unexpectedly succeeded")
+	}
+	permanent, err := service.accounts.Get(ctx, credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if permanent.AuthStatus != accountdomain.AuthStatusActive || permanent.RefreshFailureCount != 2 || permanent.LastRefreshErrorStatus != 400 || permanent.LastRefreshErrorCode != "invalid_grant" || permanent.LastRefreshErrorMessage != "Refresh token has expired" || permanent.LastRefreshErrorResponse == "" || !permanent.RefreshPermanent || permanent.RefreshDueAt == nil || !permanent.RefreshDueAt.Equal(permanent.ExpiresAt) {
+		t.Fatalf("permanent with valid token should stay active: %#v", permanent)
+	}
+	dueIDs, err := service.accounts.ListDueCredentialRefreshIDs(ctx, now, credentialRefreshBatchSize)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(dueIDs) != 0 {
+		t.Fatalf("permanent refresh failure remained immediately due: %#v", dueIDs)
+	}
+	dueAtExpiry, err := service.accounts.ListDueCredentialRefreshIDs(ctx, permanent.ExpiresAt, credentialRefreshBatchSize)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(dueAtExpiry) != 1 || dueAtExpiry[0] != credential.ID {
+		t.Fatalf("permanent refresh failure was not scheduled at expiry: %#v", dueAtExpiry)
+	}
+	refreshCount := adapter.refreshCount.Load()
+	service.now = func() time.Time { return permanent.ExpiresAt.Add(-time.Minute) }
+	usable, err := service.EnsureCredential(ctx, permanent, false)
+	if err != nil {
+		t.Fatalf("valid access token was rejected after permanent refresh failure: %v", err)
+	}
+	if usable.EncryptedAccessToken != permanent.EncryptedAccessToken || adapter.refreshCount.Load() != refreshCount {
+		t.Fatalf("usable token = %#v, refresh count = %d", usable, adapter.refreshCount.Load())
+	}
+	service.now = func() time.Time { return now }
+	if _, err := service.EnsureCredential(ctx, permanent, true); err == nil {
+		t.Fatal("forced retry after permanent failure unexpectedly succeeded")
+	}
+	permanent, err = service.accounts.Get(ctx, credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !permanent.RefreshPermanent || permanent.RefreshDueAt == nil || !permanent.RefreshDueAt.Equal(permanent.ExpiresAt) || adapter.refreshCount.Load() != refreshCount {
+		t.Fatalf("permanent refresh state retried or changed: %#v, refresh count = %d", permanent, adapter.refreshCount.Load())
+	}
+
+	service.clearRefreshState(credential.ID)
+	expiredCredential := permanent
+	expiredCredential.ExpiresAt = now.Add(-time.Minute)
+	if _, err := service.accounts.UpdateTokens(ctx, permanent.ID, permanent.EncryptedAccessToken, permanent.EncryptedRefreshToken, expiredCredential.ExpiresAt); err != nil {
+		t.Fatal(err)
+	}
+	adapter.refreshErr = &provider.CredentialRefreshError{Status: 400, Code: "invalid_grant", Permanent: true}
+	expiredState, _ := service.accounts.Get(ctx, credential.ID)
+	if expiredState.RefreshPermanent {
+		t.Fatalf("token update did not clear permanent refresh failure: %#v", expiredState)
+	}
+	if _, err := service.EnsureCredential(ctx, expiredState, true); err == nil {
+		t.Fatal("permanent refresh with expired token unexpectedly succeeded")
+	}
+	finalState, err := service.accounts.Get(ctx, credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if finalState.AuthStatus != accountdomain.AuthStatusReauthRequired {
+		t.Fatalf("permanent with expired token should be reauthRequired: %#v", finalState)
+	}
+	manualCount := adapter.refreshCount.Load()
+	manualOptions := ensureCredentialOptions{force: true, bypassCooldown: true, retryPermanentOnce: true}
+	if _, err := service.ensureCredential(ctx, finalState, manualOptions); err == nil {
+		t.Fatal("manual retry should surface the repeated invalid_grant")
+	}
+	if adapter.refreshCount.Load() != manualCount+1 {
+		t.Fatalf("manual retry did not issue exactly one oauth request: before=%d after=%d", manualCount, adapter.refreshCount.Load())
+	}
+	adapter.refreshErr = nil
+	latest, err := service.accounts.Get(ctx, finalState.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	recovered, err := service.ensureCredential(ctx, latest, manualOptions)
+	if err != nil {
+		t.Fatalf("manual retry did not recover credential: %v", err)
+	}
+	if recovered.AuthStatus != accountdomain.AuthStatusActive || recovered.RefreshPermanent || recovered.LastRefreshErrorCode != "" {
+		t.Fatalf("manual recovery state = %#v", recovered)
+	}
+}
+
+func TestCredentialDecryptFailedAllowsRetryAfterKeyRecovery(t *testing.T) {
+	ctx := context.Background()
+	now := time.Now().UTC()
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+
+	// 旧行为会把 decrypt_failed 标 permanent；模拟已落库的 permanent 状态。
+	if err := service.accounts.UpdateCredentialRefreshFailure(ctx, credential.ID, repository.CredentialRefreshFailure{Count: 1, RetryAt: now.Add(time.Hour), Code: "credential_decrypt_failed", Message: "Stored credential could not be decrypted", Permanent: true}); err != nil {
+		t.Fatal(err)
+	}
+	stuck, err := service.accounts.Get(ctx, credential.ID)
+	if err != nil || !stuck.RefreshPermanent || stuck.LastRefreshErrorCode != "credential_decrypt_failed" {
+		t.Fatalf("setup stuck state = %#v err=%v", stuck, err)
+	}
+
+	// 密钥恢复后：手动 force 必须能再次发起刷新。
+	adapter.refreshErr = nil
+	service.clearRefreshState(credential.ID)
+	recovered, err := service.EnsureCredential(ctx, stuck, true)
+	if err != nil {
+		t.Fatalf("force refresh after decrypt_failed should retry: %v", err)
+	}
+	if recovered.RefreshPermanent || recovered.LastRefreshErrorStatus != 0 || recovered.LastRefreshErrorCode != "" || recovered.LastRefreshErrorMessage != "" || recovered.LastRefreshErrorResponse != "" || adapter.refreshCount.Load() < 1 {
+		t.Fatalf("decrypt_failed was not cleared after successful refresh: %#v count=%d", recovered, adapter.refreshCount.Load())
+	}
+
+	// invalid_grant 仍须保持永久阻断。
+	service.clearRefreshState(credential.ID)
+	adapter.refreshErr = &provider.CredentialRefreshError{Status: 400, Code: "invalid_grant", Permanent: true}
+	if _, err := service.EnsureCredential(ctx, recovered, true); err == nil {
+		t.Fatal("invalid_grant should fail")
+	}
+	blocked, err := service.accounts.Get(ctx, credential.ID)
+	if err != nil || !blocked.RefreshPermanent || blocked.LastRefreshErrorCode != "invalid_grant" {
+		t.Fatalf("invalid_grant permanent state = %#v err=%v", blocked, err)
+	}
+	// force 也不得再打 OAuth（真正永久）
+	count := adapter.refreshCount.Load()
+	if _, err := service.EnsureCredential(ctx, blocked, true); err == nil {
+		t.Fatal("invalid_grant force should still be blocked")
+	}
+	if adapter.refreshCount.Load() != count {
+		t.Fatalf("invalid_grant forced another oauth call: before=%d after=%d", count, adapter.refreshCount.Load())
+	}
+}
+
+func TestRefreshAllTokensSkipsUnrefreshableAccounts(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 11, 12, 0, 0, 0, time.UTC)
+	service, _, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+	for _, value := range []accountdomain.Credential{
+		{Provider: accountdomain.ProviderBuild, Name: "refreshable-2", SourceKey: "refreshable-2", EncryptedAccessToken: "access-2", EncryptedRefreshToken: "refresh-2", ExpiresAt: now.Add(time.Hour), Enabled: true, AuthStatus: accountdomain.AuthStatusActive},
+		{Provider: accountdomain.ProviderBuild, Name: "not-refreshable", SourceKey: "not-refreshable", EncryptedAccessToken: "access-3", ExpiresAt: now.Add(time.Hour), Enabled: true, AuthStatus: accountdomain.AuthStatusActive},
+	} {
+		if _, _, err := service.accounts.UpsertByIdentity(ctx, value); err != nil {
+			t.Fatal(err)
+		}
+	}
+	invalid, _, err := service.accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "invalid-refreshable", SourceKey: "invalid-refreshable",
+		EncryptedAccessToken: "access-invalid", EncryptedRefreshToken: "refresh-invalid", ExpiresAt: now.Add(time.Hour), Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	invalid.AuthStatus = accountdomain.AuthStatusReauthRequired
+	if _, err := service.accounts.Update(ctx, invalid); err != nil {
+		t.Fatal(err)
+	}
+
+	progress := make([][2]int, 0, 4)
+	succeeded, failed, skipped, err := service.RefreshAllTokensWithProgress(ctx, func(completed, total int) error {
+		progress = append(progress, [2]int{completed, total})
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if succeeded != 3 || failed != 0 || skipped != 1 || adapter.refreshCount.Load() != 3 {
+		t.Fatalf("result = %d/%d/%d, refresh count = %d", succeeded, failed, skipped, adapter.refreshCount.Load())
+	}
+	if len(progress) != 4 || progress[0] != [2]int{0, 3} || progress[1] != [2]int{1, 3} || progress[2] != [2]int{2, 3} || progress[3] != [2]int{3, 3} {
+		t.Fatalf("progress = %#v", progress)
+	}
+	recovered, err := service.accounts.Get(ctx, invalid.ID)
+	if err != nil || recovered.AuthStatus != accountdomain.AuthStatusActive {
+		t.Fatalf("invalid account was not recovered: %#v err=%v", recovered, err)
+	}
+}
+
+func TestBatchRefreshTokensRefreshesOnlySelectedEligibleAccounts(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 19, 10, 0, 0, 0, time.UTC)
+	service, refreshable, adapter := newCredentialRefreshTestService(t, now)
+	service.now = func() time.Time { return now }
+	selected := []uint64{refreshable.ID}
+	var invalidID uint64
+	for _, value := range []accountdomain.Credential{
+		{Provider: accountdomain.ProviderBuild, Name: "missing-refresh", SourceKey: "missing-refresh", EncryptedAccessToken: "access", Enabled: true, AuthStatus: accountdomain.AuthStatusActive},
+		{Provider: accountdomain.ProviderBuild, Name: "disabled", SourceKey: "disabled", EncryptedAccessToken: "access", EncryptedRefreshToken: "refresh", Enabled: true, AuthStatus: accountdomain.AuthStatusActive},
+		{Provider: accountdomain.ProviderBuild, Name: "invalid", SourceKey: "invalid", EncryptedAccessToken: "access", EncryptedRefreshToken: "refresh", Enabled: true, AuthStatus: accountdomain.AuthStatusActive},
+	} {
+		created, _, err := service.accounts.UpsertByIdentity(ctx, value)
+		if err != nil {
+			t.Fatal(err)
+		}
+		needsUpdate := false
+		if value.Name == "disabled" {
+			created.Enabled = false
+			needsUpdate = true
+		}
+		if value.Name == "invalid" {
+			created.AuthStatus = accountdomain.AuthStatusReauthRequired
+			invalidID = created.ID
+			needsUpdate = true
+		}
+		if needsUpdate {
+			created, err = service.accounts.Update(ctx, created)
+			if err != nil {
+				t.Fatal(err)
+			}
+		}
+		selected = append(selected, created.ID)
+	}
+
+	succeeded, failed, skipped, err := service.BatchRefreshTokens(ctx, append(selected, refreshable.ID))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if succeeded != 2 || failed != 0 || skipped != 2 || adapter.refreshCount.Load() != 2 {
+		t.Fatalf("result = %d/%d/%d, refresh count = %d", succeeded, failed, skipped, adapter.refreshCount.Load())
+	}
+	updated, err := service.accounts.Get(ctx, refreshable.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if updated.EncryptedAccessToken == "" || updated.EncryptedAccessToken == "access-0" {
+		t.Fatalf("refreshed access token = %q", updated.EncryptedAccessToken)
+	}
+	recovered, err := service.accounts.Get(ctx, invalidID)
+	if err != nil || recovered.AuthStatus != accountdomain.AuthStatusActive {
+		t.Fatalf("selected invalid account was not recovered: %#v err=%v", recovered, err)
+	}
+}
+
+func TestRefreshBillingCollapsesConcurrentRequests(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 7, 11, 12, 0, 0, 0, time.UTC)
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	adapter.billingDelay = 30 * time.Millisecond
+	const callers = 20
+	start := make(chan struct{})
+	errors := make(chan error, callers)
+	var workers sync.WaitGroup
+	workers.Add(callers)
+	for range callers {
+		go func() {
+			defer workers.Done()
+			<-start
+			_, err := service.RefreshBilling(ctx, credential.ID)
+			errors <- err
+		}()
+	}
+	close(start)
+	workers.Wait()
+	close(errors)
+	for err := range errors {
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	if adapter.billingCount.Load() != 1 {
+		t.Fatalf("billing count = %d", adapter.billingCount.Load())
+	}
+}
+
+func newCredentialRefreshTestService(t *testing.T, now time.Time) (*Service, accountdomain.Credential, *credentialRefreshAdapter) {
+	t.Helper()
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "credential-refresh.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	repository := relational.NewAccountRepository(database)
+	credential, _, err := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider:              accountdomain.ProviderBuild,
+		Name:                  "refresh-test",
+		SourceKey:             "refresh-test",
+		EncryptedAccessToken:  "access-0",
+		EncryptedRefreshToken: "refresh-0",
+		ExpiresAt:             now.Add(time.Hour),
+		Enabled:               true,
+		AuthStatus:            accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &credentialRefreshAdapter{}
+	service := NewService(repository, nil, nil, nil, provider.NewRegistry(adapter), nil, nil)
+	return service, credential, adapter
+}
+
+type credentialRefreshAdapter struct {
+	refreshCount atomic.Int64
+	billingCount atomic.Int64
+	delay        time.Duration
+	billingDelay time.Duration
+	billing      accountdomain.Billing
+	billingErr   error
+	refreshErr   error
+}
+
+func (a *credentialRefreshAdapter) Provider() accountdomain.Provider {
+	return accountdomain.ProviderBuild
+}
+
+func (a *credentialRefreshAdapter) Definition() provider.Definition {
+	return provider.Definition{
+		Provider: accountdomain.ProviderBuild, Quota: provider.QuotaBilling,
+		Credential: provider.CredentialSurface{
+			Refresh: true,
+		},
+	}
+}
+
+func (a *credentialRefreshAdapter) RefreshCredential(ctx context.Context, _ accountdomain.Credential) (provider.RefreshedCredential, error) {
+	if a.delay > 0 {
+		timer := time.NewTimer(a.delay)
+		defer timer.Stop()
+		select {
+		case <-ctx.Done():
+			return provider.RefreshedCredential{}, ctx.Err()
+		case <-timer.C:
+		}
+	}
+	count := a.refreshCount.Add(1)
+	if a.refreshErr != nil {
+		return provider.RefreshedCredential{}, a.refreshErr
+	}
+	return provider.RefreshedCredential{EncryptedAccessToken: fmt.Sprintf("access-%d", count), EncryptedRefreshToken: fmt.Sprintf("refresh-%d", count), ExpiresAt: time.Now().UTC().Add(time.Hour)}, nil
+}
+
+func (a *credentialRefreshAdapter) ForwardResponse(context.Context, provider.ResponseResourceRequest) (*provider.Response, error) {
+	return nil, nil
+}
+
+func (a *credentialRefreshAdapter) ListModels(context.Context, accountdomain.Credential) ([]string, error) {
+	return nil, nil
+}
+
+func (a *credentialRefreshAdapter) GetBilling(context.Context, accountdomain.Credential) (accountdomain.Billing, error) {
+	if a.billingDelay > 0 {
+		time.Sleep(a.billingDelay)
+	}
+	a.billingCount.Add(1)
+	return a.billing, a.billingErr
+}
+
+func (a *credentialRefreshAdapter) StartDeviceAuthorization(context.Context) (provider.DeviceAuthorization, error) {
+	return provider.DeviceAuthorization{}, nil
+}
+
+func (a *credentialRefreshAdapter) PollDeviceAuthorization(context.Context, string) (provider.CredentialSeed, error) {
+	return provider.CredentialSeed{}, nil
+}
+
+func (a *credentialRefreshAdapter) ParseImportedCredentials([]byte) ([]provider.CredentialSeed, error) {
+	return nil, nil
+}
+func (a *credentialRefreshAdapter) MarshalCredentials([]provider.CredentialSeed) ([]byte, error) {
+	return nil, nil
+}

backend/internal/application/account/credential_scheduler.go

@@ -0,0 +1,183 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+)
+
+// CredentialStartupReport 汇总启动阶段的凭据调度与恢复结果。
+type CredentialStartupReport struct {
+	SchedulesBackfilled int
+	CriticalFound       int
+	Refreshed           int
+	Failed              int
+}
+
+// ReconcileCredentialSchedules 为升级前账号补齐持久化调度，不解密凭据，也不访问上游。
+func (s *Service) ReconcileCredentialSchedules(ctx context.Context) (int, error) {
+	total := 0
+	for {
+		count, err := s.accounts.BackfillCredentialRefreshSchedules(ctx, s.now(), credentialRefreshBatchSize)
+		total += count
+		if err != nil || count < credentialRefreshBatchSize {
+			return total, err
+		}
+	}
+}
+
+// RecoverCriticalCredentials 在启动预算内仅恢复缺失、已过期、两分钟内到期或失败重试到期的凭据。
+func (s *Service) RecoverCriticalCredentials(ctx context.Context, expiresWithin time.Duration, limit int) (CredentialStartupReport, error) {
+	report := CredentialStartupReport{}
+	backfilled, err := s.ReconcileCredentialSchedules(ctx)
+	report.SchedulesBackfilled = backfilled
+	if err != nil {
+		return report, err
+	}
+	if limit < 1 || limit > credentialRefreshBatchSize {
+		limit = credentialRefreshBatchSize
+	}
+	now := s.now()
+	ids, err := s.accounts.ListCriticalCredentialRefreshIDs(ctx, now, now.Add(expiresWithin), limit)
+	if err != nil {
+		return report, err
+	}
+	report.CriticalFound = len(ids)
+	if len(ids) == 0 {
+		return report, nil
+	}
+	report.Refreshed, report.Failed, err = s.runAccountBatch(ctx, "credential_startup_recovery", ids, s.refreshPool, nil, func(workCtx context.Context, id uint64) error {
+		taskCtx, cancel := context.WithTimeout(workCtx, credentialRefreshTimeout)
+		defer cancel()
+		credential, getErr := s.accounts.Get(taskCtx, id)
+		if getErr != nil {
+			return getErr
+		}
+		if credential.RefreshPermanent && !isRecoverableRefreshErrorCode(credential.LastRefreshErrorCode) {
+			if !credential.ExpiresAt.IsZero() && credential.ExpiresAt.After(s.now()) {
+				return nil
+			}
+			return s.MarkReauthRequired(taskCtx, id, permanentRefreshExpiredReason)
+		}
+		// 临界凭据不受进程内强制刷新节流影响；分布式账号锁和旋转 Token 比对仍避免重复 OAuth。
+		_, refreshErr := s.ensureCredential(taskCtx, credential, ensureCredentialOptions{force: true, bypassCooldown: true})
+		return refreshErr
+	})
+	if err != nil && !errors.Is(err, context.Canceled) && !errors.Is(err, context.DeadlineExceeded) {
+		return report, err
+	}
+	return report, err
+}
+
+// WakeCredentialRefresh 合并调度唤醒；导入、手动刷新和失败退避更新不会阻塞调用方。
+func (s *Service) WakeCredentialRefresh() {
+	select {
+	case s.credentialRefreshWake <- struct{}{}:
+	default:
+	}
+}
+
+// RunCredentialRefresh 使用单个 Timer 和数据库到期索引驱动刷新，内存占用与账号总数无关。
+func (s *Service) RunCredentialRefresh(ctx context.Context) {
+	timer := time.NewTimer(0)
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-s.credentialRefreshWake:
+		case <-timer.C:
+		}
+		runFailed := false
+		if err := s.refreshDueCredentials(ctx); err != nil && ctx.Err() == nil {
+			s.logger.Warn("credential_refresh_scheduler_failed", "error", err)
+			runFailed = true
+		}
+		delay, err := s.nextCredentialRefreshDelay(ctx)
+		if err != nil && ctx.Err() == nil {
+			s.logger.Warn("credential_refresh_schedule_read_failed", "error", err)
+			delay = credentialRefreshSafetyPoll
+		}
+		if runFailed && delay < 30*time.Second {
+			delay = 30 * time.Second
+		}
+		resetCredentialRefreshTimer(timer, delay)
+	}
+}
+
+func (s *Service) refreshDueCredentials(ctx context.Context) error {
+	if _, err := s.ReconcileCredentialSchedules(ctx); err != nil {
+		return err
+	}
+	for {
+		ids, err := s.accounts.ListDueCredentialRefreshIDs(ctx, s.now(), credentialRefreshBatchSize)
+		if err != nil {
+			return err
+		}
+		if len(ids) == 0 {
+			return nil
+		}
+		_, failed, batchErr := s.runAccountBatch(ctx, "credential_auto_refresh", ids, s.refreshPool, nil, func(workCtx context.Context, id uint64) error {
+			taskCtx, cancel := context.WithTimeout(workCtx, credentialRefreshTimeout)
+			defer cancel()
+			credential, err := s.accounts.Get(taskCtx, id)
+			if err != nil {
+				return err
+			}
+			if !credential.Enabled || credential.AuthStatus != accountdomain.AuthStatusActive || s.providers == nil || !s.providers.SupportsCredentialRefresh(credential.Provider) || credential.EncryptedRefreshToken == "" {
+				return nil
+			}
+			if credential.RefreshPermanent && !isRecoverableRefreshErrorCode(credential.LastRefreshErrorCode) {
+				if !credential.ExpiresAt.IsZero() && credential.ExpiresAt.After(s.now()) {
+					return nil
+				}
+				return s.MarkReauthRequired(taskCtx, id, permanentRefreshExpiredReason)
+			}
+			if credential.RefreshDueAt != nil && credential.RefreshDueAt.After(s.now()) {
+				return nil
+			}
+			_, err = s.ensureCredential(taskCtx, credential, ensureCredentialOptions{force: true, respectSchedule: true})
+			return err
+		})
+		if batchErr != nil {
+			return fmt.Errorf("自动刷新批次执行失败: %w", batchErr)
+		}
+		if failed > 0 {
+			return fmt.Errorf("自动刷新批次失败 %d/%d", failed, len(ids))
+		}
+		if len(ids) < credentialRefreshBatchSize {
+			return nil
+		}
+	}
+}
+
+func (s *Service) nextCredentialRefreshDelay(ctx context.Context) (time.Duration, error) {
+	next, err := s.accounts.NextCredentialRefreshDueAt(ctx)
+	if err != nil {
+		return 0, err
+	}
+	delay := credentialRefreshSafetyPoll
+	if next != nil {
+		until := next.Sub(s.now())
+		if until < delay {
+			delay = until
+		}
+	}
+	if delay < 100*time.Millisecond {
+		delay = 100 * time.Millisecond
+	}
+	return delay, nil
+}
+
+func resetCredentialRefreshTimer(timer *time.Timer, delay time.Duration) {
+	if !timer.Stop() {
+		select {
+		case <-timer.C:
+		default:
+		}
+	}
+	timer.Reset(delay)
+}

backend/internal/application/account/export_test.go

@@ -0,0 +1,288 @@
+package account
+
+import (
+	"context"
+	"encoding/base64"
+	"path/filepath"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	cliprovider "github.com/chenyme/grok2api/backend/internal/infra/provider/cli"
+	consoleprovider "github.com/chenyme/grok2api/backend/internal/infra/provider/console"
+	webprovider "github.com/chenyme/grok2api/backend/internal/infra/provider/web"
+	"github.com/chenyme/grok2api/backend/internal/infra/security"
+)
+
+func TestExportCredentialsRoundTripsImportFormat(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "export.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer database.Close()
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	accessToken, err := cipher.Encrypt("access-token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	refreshToken, err := cipher.Encrypt("refresh-token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	expiresAt := time.Date(2026, 7, 12, 12, 0, 0, 0, time.UTC)
+	repository := relational.NewAccountRepository(database)
+	created, _, err := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "primary", Email: "user@example.com", UserID: "user-1",
+		SourceKey: "export-test", OIDCClientID: "client-1", EncryptedAccessToken: accessToken,
+		EncryptedRefreshToken: refreshToken, ExpiresAt: expiresAt, Enabled: false,
+		AuthStatus: accountdomain.AuthStatusActive, Priority: 1, MaxConcurrent: 8,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := cliprovider.NewAdapter(cliprovider.Config{}, cipher)
+	service := NewService(repository, nil, nil, nil, provider.NewRegistry(adapter), cipher, nil)
+
+	result, err := service.ExportCredentials(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	selectedResult, err := service.ExportProviderCredentialsByIDs(ctx, accountdomain.ProviderBuild, []uint64{created.ID})
+	if err != nil || selectedResult.Count != 1 {
+		t.Fatalf("selected export result = %#v, error = %v", selectedResult, err)
+	}
+	if _, err := service.ExportProviderCredentialsByIDs(ctx, accountdomain.ProviderWeb, []uint64{created.ID}); err == nil {
+		t.Fatal("expected cross-provider selected export to fail")
+	}
+	if _, err := service.ExportProviderCredentialsCursor(ctx, accountdomain.ProviderBuild, 0, 0, maxCredentialExportAccounts+1); err == nil {
+		t.Fatal("expected oversized export page to fail")
+	}
+	values, err := adapter.ParseImportedCredentials(result.Data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Count != 1 || len(values) != 1 {
+		t.Fatalf("export count = %d, imported values = %d", result.Count, len(values))
+	}
+	value := values[0]
+	if value.Name != "primary" || value.Email != "user@example.com" || value.UserID != "user-1" || value.OIDCClientID != "client-1" || value.AccessToken != "access-token" || value.RefreshToken != "refresh-token" || !value.ExpiresAt.Equal(expiresAt) {
+		t.Fatalf("round-trip credential = %#v", value)
+	}
+	progress := make([][2]int, 0, 2)
+	if _, err := service.ImportCredentialsWithProgress(ctx, result.Data, nil, func(completed, total int) error {
+		progress = append(progress, [2]int{completed, total})
+		return nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if len(progress) != 2 || progress[0] != [2]int{0, 1} || progress[1] != [2]int{1, 1} {
+		t.Fatalf("import progress = %#v", progress)
+	}
+
+	multiProgress := make([][2]int, 0, 3)
+	multiResult, err := service.ImportCredentialDocumentsWithProgress(ctx, [][]byte{
+		result.Data,
+		result.Data,
+		[]byte(`{"provider":"grok_build","name":"secondary","access_token":"second-access","refresh_token":"second-refresh","user_id":"user-2"}`),
+	}, nil, func(completed, total int) error {
+		multiProgress = append(multiProgress, [2]int{completed, total})
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if multiResult.Created != 1 || multiResult.Updated != 1 {
+		t.Fatalf("multi-file import result = %#v", multiResult)
+	}
+	if len(multiProgress) != 3 || multiProgress[0] != [2]int{0, 2} || multiProgress[2] != [2]int{2, 2} {
+		t.Fatalf("multi-file import progress = %#v", multiProgress)
+	}
+}
+
+func TestExportProviderCredentialsCursorKeepsStableSnapshot(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "cursor-export.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	accessToken, err := cipher.Encrypt("access-token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	repository := relational.NewAccountRepository(database)
+	createAccount := func(name string) accountdomain.Credential {
+		t.Helper()
+		value, _, createErr := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+			Provider: accountdomain.ProviderBuild, Name: name, SourceKey: "cursor-" + name,
+			UserID: name, EncryptedAccessToken: accessToken, Enabled: true,
+			AuthStatus: accountdomain.AuthStatusActive, Priority: 1, MaxConcurrent: 8,
+		})
+		if createErr != nil {
+			t.Fatal(createErr)
+		}
+		return value
+	}
+	first := createAccount("first")
+	second := createAccount("second")
+	third := createAccount("third")
+	adapter := cliprovider.NewAdapter(cliprovider.Config{}, cipher)
+	service := NewService(repository, nil, nil, nil, provider.NewRegistry(adapter), cipher, nil)
+
+	pageOne, err := service.ExportProviderCredentialsCursor(ctx, accountdomain.ProviderBuild, 0, 0, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if pageOne.Count != 2 || !pageOne.HasMore || pageOne.NextID != second.ID || pageOne.SnapshotMaxID != third.ID {
+		t.Fatalf("first cursor page = %#v", pageOne)
+	}
+	createAccount("new-after-snapshot")
+	pageTwo, err := service.ExportProviderCredentialsCursor(ctx, accountdomain.ProviderBuild, pageOne.NextID, pageOne.SnapshotMaxID, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	values, err := adapter.ParseImportedCredentials(pageTwo.Data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if pageTwo.Count != 1 || pageTwo.HasMore || pageTwo.NextID != third.ID || len(values) != 1 || values[0].Name != "third" {
+		t.Fatalf("second cursor page = %#v, values = %#v", pageTwo, values)
+	}
+	if first.ID >= second.ID || second.ID >= third.ID {
+		t.Fatalf("test account IDs are not monotonic: %d, %d, %d", first.ID, second.ID, third.ID)
+	}
+	if _, err := service.ExportProviderCredentialsCursor(ctx, accountdomain.ProviderBuild, second.ID, 0, 2); err == nil {
+		t.Fatal("expected continuation without snapshot boundary to fail")
+	}
+}
+
+func TestValidateCredentialExportCountRejectsPartialReads(t *testing.T) {
+	for _, test := range []struct {
+		name     string
+		expected int
+		total    int64
+		actual   int
+		wantErr  bool
+	}{
+		{name: "exact", expected: 2, total: 2, actual: 2},
+		{name: "missing at count", expected: 2, total: 1, actual: 1, wantErr: true},
+		{name: "deleted after count", expected: 2, total: 2, actual: 1, wantErr: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			err := validateCredentialExportCount(test.expected, test.total, test.actual)
+			if (err != nil) != test.wantErr {
+				t.Fatalf("validateCredentialExportCount() error = %v, wantErr %v", err, test.wantErr)
+			}
+		})
+	}
+}
+
+func TestExportProviderCredentialsRoundTripsSSOProviders(t *testing.T) {
+	for _, test := range []struct {
+		name          string
+		providerValue accountdomain.Provider
+		adapter       provider.Adapter
+		webTier       accountdomain.WebTier
+	}{
+		{name: "web", providerValue: accountdomain.ProviderWeb, adapter: webprovider.NewAdapter(webprovider.Config{}, nil, nil, nil, nil), webTier: accountdomain.WebTierSuper},
+		{name: "console", providerValue: accountdomain.ProviderConsole, adapter: consoleprovider.NewAdapter(consoleprovider.Config{}, nil, nil)},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			ctx := context.Background()
+			nsfwAt := time.Date(2026, 7, 18, 8, 0, 0, 0, time.UTC)
+			tosAt := nsfwAt.Add(-time.Hour)
+			birthDateAt := tosAt.Add(-time.Hour)
+			database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "export-sso.db"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = database.Close() })
+			if err := database.InitializeSchema(ctx); err != nil {
+				t.Fatal(err)
+			}
+			cipher, err := security.NewCipher(base64.StdEncoding.EncodeToString(make([]byte, 32)))
+			if err != nil {
+				t.Fatal(err)
+			}
+			token, err := cipher.Encrypt("sso-token")
+			if err != nil {
+				t.Fatal(err)
+			}
+			cookies, err := cipher.Encrypt("cf_clearance=clearance-token")
+			if err != nil {
+				t.Fatal(err)
+			}
+			repository := relational.NewAccountRepository(database)
+			created, _, err := repository.UpsertByIdentity(ctx, accountdomain.Credential{
+				Provider: test.providerValue, AuthType: accountdomain.AuthTypeSSO, WebTier: test.webTier,
+				Name: test.name + "-account", SourceKey: test.name + "-export-test",
+				EncryptedAccessToken: token, EncryptedCloudflareCookie: cookies,
+				Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+				WebNSFWEnabledAt: &nsfwAt, WebTermsAcceptedAt: &tosAt,
+				WebTermsAcceptedVersion: accountdomain.CurrentWebTermsVersion, WebBirthDateSetAt: &birthDateAt,
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			// 模拟旧账号先按 SSO 来源创建，后续身份同步再补齐邮箱与 user_id；
+			// 回导必须命中原账号，不能因新身份字段生成重复记录。
+			created.Email = test.name + "@example.com"
+			created.UserID = test.name + "-user-id"
+			if _, err := repository.Update(ctx, created); err != nil {
+				t.Fatal(err)
+			}
+			service := NewService(repository, nil, nil, nil, provider.NewRegistry(test.adapter), cipher, nil)
+
+			result, err := service.ExportProviderCredentials(ctx, test.providerValue)
+			if err != nil {
+				t.Fatal(err)
+			}
+			codec, ok := test.adapter.(provider.CredentialCodecAdapter)
+			if !ok {
+				t.Fatal("adapter does not implement credential codec")
+			}
+			values, err := codec.ParseImportedCredentials(result.Data)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if result.Count != 1 || len(values) != 1 || values[0].Provider != test.providerValue || values[0].AccessToken != "sso-token" || values[0].CloudflareCookies != "cf_clearance=clearance-token" || values[0].Email != test.name+"@example.com" || values[0].UserID != test.name+"-user-id" {
+				t.Fatalf("round-trip result = %#v, values = %#v", result, values)
+			}
+			if test.providerValue == accountdomain.ProviderWeb && (values[0].WebTier != accountdomain.WebTierSuper || values[0].WebNSFWEnabledAt == nil || !values[0].WebNSFWEnabledAt.Equal(nsfwAt) || values[0].WebTermsAcceptedAt == nil || !values[0].WebTermsAcceptedAt.Equal(tosAt) || values[0].WebTermsAcceptedVersion != accountdomain.CurrentWebTermsVersion || values[0].WebBirthDateSetAt == nil || !values[0].WebBirthDateSetAt.Equal(birthDateAt)) {
+				t.Fatalf("web metadata = %#v", values[0])
+			}
+			var imported ImportResult
+			if test.providerValue == accountdomain.ProviderWeb {
+				imported, err = service.ImportWebCredentialsWithProgress(ctx, result.Data, nil, nil)
+			} else {
+				imported, err = service.ImportConsoleCredentialsWithProgress(ctx, result.Data, nil, nil)
+			}
+			if err != nil || len(imported.AccountIDs) != 1 {
+				t.Fatalf("reimport result = %#v, error = %v", imported, err)
+			}
+			stored, err := repository.Get(ctx, imported.AccountIDs[0])
+			if err != nil || stored.Email != test.name+"@example.com" || stored.UserID != test.name+"-user-id" {
+				t.Fatalf("reimported account = %#v, error = %v", stored, err)
+			}
+			if test.providerValue == accountdomain.ProviderWeb && (stored.WebNSFWEnabledAt == nil || !stored.WebNSFWEnabledAt.Equal(nsfwAt) || stored.WebTermsAcceptedAt == nil || !stored.WebTermsAcceptedAt.Equal(tosAt) || stored.WebTermsAcceptedVersion != accountdomain.CurrentWebTermsVersion || stored.WebBirthDateSetAt == nil || !stored.WebBirthDateSetAt.Equal(birthDateAt)) {
+				t.Fatalf("reimported web metadata = %#v", stored)
+			}
+		})
+	}
+}

backend/internal/application/account/linked_delete_test.go

@@ -0,0 +1,264 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+func TestBatchDeleteWithLinkedRemovesPeersAndKeepsUntargetedWeb(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-linked-delete.db")
+	web, build, console := seedLinkedTrio(t, repo, strings.Repeat("1", 64), "u1")
+
+	result, err := service.BatchDeleteWithLinked(ctx, accountdomain.ProviderBuild, []uint64{build.ID}, []accountdomain.Provider{accountdomain.ProviderConsole})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Deleted != 2 || result.LinkedDeleted != 1 {
+		t.Fatalf("result = %#v", result)
+	}
+	assertAccountMissing(t, repo, build.ID)
+	assertAccountMissing(t, repo, console.ID)
+	assertAccountPresent(t, repo, web.ID)
+
+	web2 := mustUpsertLinked(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web2", SourceKey: "sso:" + strings.Repeat("2", 64),
+	})
+	deleted, err := service.BatchDelete(ctx, []uint64{web2.ID})
+	if err != nil || deleted != 1 {
+		t.Fatalf("legacy batch delete deleted=%d err=%v", deleted, err)
+	}
+}
+
+func TestBatchDeleteWithLinkedWebDeletesBuildAndConsole(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-linked-delete-web.db")
+	web, build, console := seedLinkedTrio(t, repo, strings.Repeat("a", 64), "u-web")
+
+	result, err := service.BatchDeleteWithLinked(ctx, accountdomain.ProviderWeb, []uint64{web.ID}, []accountdomain.Provider{accountdomain.ProviderBuild, accountdomain.ProviderConsole})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Deleted != 3 || result.RootsDeleted != 1 || result.LinkedDeleted != 2 {
+		t.Fatalf("result = %#v", result)
+	}
+	assertAccountMissing(t, repo, web.ID)
+	assertAccountMissing(t, repo, build.ID)
+	assertAccountMissing(t, repo, console.ID)
+}
+
+func TestBatchDeleteWithLinkedMixedBatchOnlyExpandsLinkedRoots(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-linked-delete-mix.db")
+	webLinked, _, console := seedLinkedTrio(t, repo, strings.Repeat("b", 64), "u-mix")
+	webOnly := mustUpsertLinked(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web-only", SourceKey: "sso:" + strings.Repeat("c", 64),
+	})
+
+	result, err := service.BatchDeleteWithLinked(ctx, accountdomain.ProviderWeb, []uint64{webLinked.ID, webOnly.ID}, []accountdomain.Provider{accountdomain.ProviderConsole})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Deleted != 3 {
+		t.Fatalf("result = %#v", result)
+	}
+	assertAccountMissing(t, repo, webLinked.ID)
+	assertAccountMissing(t, repo, webOnly.ID)
+	assertAccountMissing(t, repo, console.ID)
+}
+
+func TestPreviewLinkedDeleteCountsWithoutDeleting(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-linked-preview.db")
+	web, build, console := seedLinkedTrio(t, repo, strings.Repeat("d", 64), "u-prev")
+
+	res, err := service.PreviewLinkedDelete(ctx, accountdomain.ProviderWeb, []uint64{web.ID}, []accountdomain.Provider{accountdomain.ProviderBuild, accountdomain.ProviderConsole})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.RootIDs) != 1 || res.LinkedByProvider[accountdomain.ProviderBuild] != 1 || res.LinkedByProvider[accountdomain.ProviderConsole] != 1 || len(res.FinalIDs) != 3 {
+		t.Fatalf("preview = %#v", res)
+	}
+	assertAccountPresent(t, repo, web.ID)
+	assertAccountPresent(t, repo, build.ID)
+	assertAccountPresent(t, repo, console.ID)
+}
+
+func TestBatchDeleteWithLinkedEmptyTargetsDeletesRootOnly(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-linked-empty-targets.db")
+	web, build, console := seedLinkedTrio(t, repo, strings.Repeat("e", 64), "u-empty")
+
+	result, err := service.BatchDeleteWithLinked(ctx, accountdomain.ProviderWeb, []uint64{web.ID}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Deleted != 1 || result.LinkedDeleted != 0 {
+		t.Fatalf("result = %#v", result)
+	}
+	assertAccountMissing(t, repo, web.ID)
+	assertAccountPresent(t, repo, build.ID)
+	assertAccountPresent(t, repo, console.ID)
+}
+
+func TestBatchDeleteWithLinkedInvalidTarget(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-linked-bad-target.db")
+	web, _, _ := seedLinkedTrio(t, repo, strings.Repeat("f", 64), "u-bad")
+
+	if _, err := service.BatchDeleteWithLinked(ctx, accountdomain.ProviderWeb, []uint64{web.ID}, []accountdomain.Provider{accountdomain.Provider("nope")}); err == nil {
+		t.Fatal("expected invalid target error")
+	}
+	if _, err := service.BatchDeleteWithLinked(ctx, accountdomain.ProviderWeb, []uint64{web.ID}, []accountdomain.Provider{accountdomain.ProviderWeb}); err == nil {
+		t.Fatal("expected self-target error")
+	}
+	assertAccountPresent(t, repo, web.ID)
+}
+
+func TestDeleteMissingAccountReturnsNotFound(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	_, service := newLinkedDeleteTestService(t, "svc-delete-missing.db")
+
+	if err := service.Delete(ctx, 9_999_999); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("Delete missing: err=%v", err)
+	}
+	if _, err := service.DeleteWithLinked(ctx, accountdomain.ProviderWeb, 9_999_999, []accountdomain.Provider{accountdomain.ProviderBuild}); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("DeleteWithLinked missing: err=%v", err)
+	}
+}
+
+func TestDeleteWithLinkedRejectsRootFromAnotherProvider(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	repo, service := newLinkedDeleteTestService(t, "svc-delete-provider-mismatch.db")
+	web, _, _ := seedLinkedTrio(t, repo, strings.Repeat("9", 64), "u-provider-mismatch")
+
+	_, err := service.DeleteWithLinked(ctx, accountdomain.ProviderBuild, web.ID, []accountdomain.Provider{accountdomain.ProviderConsole})
+	if !errors.Is(err, ErrConflict) {
+		t.Fatalf("provider mismatch error = %v", err)
+	}
+	assertAccountPresent(t, repo, web.ID)
+}
+
+func TestFinishLinkedDeleteUsesBatchStickyCleanup(t *testing.T) {
+	sticky := &stickyBatchStub{}
+	service := &Service{sticky: sticky}
+	service.finishLinkedDelete(context.Background(), []uint64{3, 5, 8})
+	if sticky.singleCalls != 0 {
+		t.Fatalf("single-account cleanup calls = %d", sticky.singleCalls)
+	}
+	if len(sticky.batchCalls) != 1 || len(sticky.batchCalls[0]) != 3 || sticky.batchCalls[0][0] != 3 || sticky.batchCalls[0][2] != 8 {
+		t.Fatalf("batch cleanup calls = %#v", sticky.batchCalls)
+	}
+}
+
+func newLinkedDeleteTestService(t *testing.T, dbName string) (*relational.AccountRepository, *Service) {
+	t.Helper()
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), dbName))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	repo := relational.NewAccountRepository(database)
+	return repo, &Service{accounts: repo, sticky: stickyStub{}, logger: nil}
+}
+
+func seedLinkedTrio(t *testing.T, repo *relational.AccountRepository, digest, userID string) (web, build, console accountdomain.Credential) {
+	t.Helper()
+	ctx := context.Background()
+	web = mustUpsertLinked(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web", SourceKey: "sso:" + digest, UserID: userID,
+	})
+	build = mustUpsertLinked(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, AuthType: accountdomain.AuthTypeOAuth, Name: "build", SourceKey: "build-" + digest[:8], UserID: userID,
+	})
+	console = mustUpsertLinked(t, repo, accountdomain.Credential{
+		Provider: accountdomain.ProviderConsole, AuthType: accountdomain.AuthTypeSSO, Name: "console", SourceKey: "console-sso:" + digest, UserID: userID,
+	})
+	if err := repo.LinkWebToBuild(ctx, web.ID, build.ID); err != nil {
+		t.Fatal(err)
+	}
+	if err := repo.ReconcileProviderLinks(ctx, web.ID); err != nil {
+		t.Fatal(err)
+	}
+	return web, build, console
+}
+
+func mustUpsertLinked(t *testing.T, repo *relational.AccountRepository, value accountdomain.Credential) accountdomain.Credential {
+	t.Helper()
+	value.EncryptedAccessToken = "encrypted"
+	value.Enabled = true
+	value.AuthStatus = accountdomain.AuthStatusActive
+	value.Priority = accountdomain.DefaultPriority
+	value.MaxConcurrent = accountdomain.DefaultMaxConcurrent
+	stored, _, err := repo.UpsertByIdentity(context.Background(), value)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return stored
+}
+
+func assertAccountMissing(t *testing.T, repo *relational.AccountRepository, id uint64) {
+	t.Helper()
+	if _, err := repo.Get(context.Background(), id); !errors.Is(err, repository.ErrNotFound) {
+		t.Fatalf("account %d should be missing, err=%v", id, err)
+	}
+}
+
+func assertAccountPresent(t *testing.T, repo *relational.AccountRepository, id uint64) {
+	t.Helper()
+	if _, err := repo.Get(context.Background(), id); err != nil {
+		t.Fatalf("account %d should remain: %v", id, err)
+	}
+}
+
+type stickyStub struct{}
+
+func (stickyStub) Get(context.Context, string, time.Time) (uint64, bool, error) {
+	return 0, false, nil
+}
+func (stickyStub) Bind(context.Context, string, uint64, time.Time, time.Time) (uint64, error) {
+	return 0, nil
+}
+func (stickyStub) Set(context.Context, string, uint64, time.Time) error { return nil }
+func (stickyStub) DeleteByAccount(context.Context, uint64) error        { return nil }
+
+type stickyBatchStub struct {
+	singleCalls int
+	batchCalls  [][]uint64
+}
+
+func (*stickyBatchStub) Get(context.Context, string, time.Time) (uint64, bool, error) {
+	return 0, false, nil
+}
+func (*stickyBatchStub) Bind(context.Context, string, uint64, time.Time, time.Time) (uint64, error) {
+	return 0, nil
+}
+func (*stickyBatchStub) Set(context.Context, string, uint64, time.Time) error { return nil }
+func (s *stickyBatchStub) DeleteByAccount(context.Context, uint64) error {
+	s.singleCalls++
+	return nil
+}
+func (s *stickyBatchStub) DeleteByAccounts(_ context.Context, ids []uint64) error {
+	s.batchCalls = append(s.batchCalls, append([]uint64(nil), ids...))
+	return nil
+}

backend/internal/application/account/list_filter_test.go

@@ -0,0 +1,64 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+)
+
+func TestListRejectsInvalidWebFilters(t *testing.T) {
+	tests := []struct {
+		name   string
+		filter ListFilter
+	}{
+		{name: "agreement on non-Web provider", filter: ListFilter{Provider: string(accountdomain.ProviderBuild), Agreement: "nsfwEnabled"}},
+		{name: "web association value on Build provider", filter: ListFilter{Provider: string(accountdomain.ProviderBuild), Association: "buildLinked"}},
+		{name: "web association value on Console provider", filter: ListFilter{Provider: string(accountdomain.ProviderConsole), Association: "allLinked"}},
+		{name: "webLinked on Web provider", filter: ListFilter{Provider: string(accountdomain.ProviderWeb), Association: "webLinked"}},
+		{name: "association without provider", filter: ListFilter{Association: "webLinked"}},
+		{name: "invalid agreement", filter: ListFilter{Provider: string(accountdomain.ProviderWeb), Agreement: "invalid"}},
+		{name: "invalid association", filter: ListFilter{Provider: string(accountdomain.ProviderWeb), Association: "invalid"}},
+	}
+
+	service := &Service{}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if _, _, err := service.List(context.Background(), 1, 20, "", test.filter); !errors.Is(err, ErrInvalidFilter) {
+				t.Fatalf("List() error = %v, want %v", err, ErrInvalidFilter)
+			}
+		})
+	}
+}
+
+// Validate provider-specific association filters: Web supports six values; Build and Console support Web links only.
+func TestValidAssociationFilterPerProvider(t *testing.T) {
+	web := string(accountdomain.ProviderWeb)
+	build := string(accountdomain.ProviderBuild)
+	console := string(accountdomain.ProviderConsole)
+	tests := []struct {
+		provider    string
+		association string
+		want        bool
+	}{
+		{web, "", true},
+		{build, "", true},
+		{"", "", true},
+		{web, "buildLinked", true},
+		{web, "allUnlinked", true},
+		{web, "webLinked", false},
+		{build, "webLinked", true},
+		{build, "webUnlinked", true},
+		{build, "consoleLinked", false},
+		{console, "webLinked", true},
+		{console, "webUnlinked", true},
+		{console, "buildLinked", false},
+		{"", "webLinked", false},
+	}
+	for _, test := range tests {
+		if got := validAssociationFilter(test.provider, test.association); got != test.want {
+			t.Fatalf("validAssociationFilter(%q, %q) = %v, want %v", test.provider, test.association, got, test.want)
+		}
+	}
+}

backend/internal/application/account/paid_quota_recovery_test.go

@@ -0,0 +1,57 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+func TestPaidQuotaCreatesPeriodProbeAndClearsAfterRecovery(t *testing.T) {
+	now := time.Now().UTC()
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	periodEnd := now.Add(time.Hour).Format(time.RFC3339)
+	adapter.billing = accountdomain.Billing{MonthlyLimit: 100, Used: 100, BillingPeriodEnd: periodEnd}
+	if _, err := service.RefreshBilling(context.Background(), credential.ID); err != nil {
+		t.Fatal(err)
+	}
+	recovery, err := service.accounts.GetQuotaRecovery(context.Background(), credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if recovery.Kind != accountdomain.QuotaRecoveryKindPaid || recovery.Status != accountdomain.QuotaRecoveryStatusExhausted || recovery.NextProbeAt == nil || recovery.NextProbeAt.Format(time.RFC3339) != periodEnd {
+		t.Fatalf("recovery = %#v", recovery)
+	}
+
+	adapter.billing = accountdomain.Billing{MonthlyLimit: 100, Used: 0, BillingPeriodEnd: now.Add(31 * 24 * time.Hour).Format(time.RFC3339)}
+	recovered, err := service.ProbePaidQuota(context.Background(), credential)
+	if err != nil || !recovered {
+		t.Fatalf("recovered = %v, err = %v", recovered, err)
+	}
+	if _, err := service.accounts.GetQuotaRecovery(context.Background(), credential.ID); !errors.Is(err, repository.ErrNotFound) {
+		t.Fatalf("paid recovery state should be cleared, err = %v", err)
+	}
+	if adapter.billingCount.Load() != 2 {
+		t.Fatalf("billing probes = %d", adapter.billingCount.Load())
+	}
+}
+
+func TestPaidQuotaStillExhaustedBacksOffAfterDueProbe(t *testing.T) {
+	now := time.Now().UTC()
+	service, credential, adapter := newCredentialRefreshTestService(t, now)
+	adapter.billing = accountdomain.Billing{MonthlyLimit: 100, Used: 100, BillingPeriodEnd: now.Add(-time.Minute).Format(time.RFC3339)}
+	recovered, err := service.ProbePaidQuota(context.Background(), credential)
+	if err != nil || recovered {
+		t.Fatalf("recovered = %v, err = %v", recovered, err)
+	}
+	recovery, err := service.accounts.GetQuotaRecovery(context.Background(), credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if recovery.NextProbeAt == nil || recovery.NextProbeAt.Before(time.Now().UTC().Add(14*time.Minute)) {
+		t.Fatalf("next probe should be backed off, recovery = %#v", recovery)
+	}
+}

backend/internal/application/account/provider_links.go

@@ -0,0 +1,85 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+)
+
+type providerLinkRepository interface {
+	ReconcileProviderLinks(ctx context.Context, accountID uint64) error
+	UpdateIdentityMetadata(ctx context.Context, accountID uint64, email, userID, teamID string) error
+}
+
+// SyncAccountIdentity best-effort fills stable Web/Console identity metadata and reconciles trusted links.
+// Definitive unauthorized signals mark the current Provider account as reauthRequired and remove it from scheduling;
+// other synchronization failures do not affect account health.
+func (s *Service) SyncAccountIdentity(ctx context.Context, id uint64) error {
+	_, err, _ := s.identitySyncs.Do(fmt.Sprintf("%d", id), func() (any, error) {
+		return nil, s.syncAccountIdentity(ctx, id)
+	})
+	return err
+}
+
+func (s *Service) syncAccountIdentity(ctx context.Context, id uint64) error {
+	links, ok := s.accounts.(providerLinkRepository)
+	if !ok {
+		return nil
+	}
+	value, err := s.accounts.Get(ctx, id)
+	if err != nil {
+		return mapRepositoryError(err)
+	}
+	if value.Provider != accountdomain.ProviderWeb && value.Provider != accountdomain.ProviderConsole {
+		return nil
+	}
+	// Session 身份只需成功补充一次；已有 user_id 或 email 时仅做本地关联协调，
+	// 不再重复访问上游。没有任何身份数据的失败账号会在后续同步时重试。
+	if strings.TrimSpace(value.UserID) != "" || strings.TrimSpace(value.Email) != "" {
+		return mapRepositoryError(links.ReconcileProviderLinks(ctx, id))
+	}
+	if s.providers == nil {
+		return fmt.Errorf("Provider 注册表未初始化")
+	}
+	adapter, ok := s.providers.AccountIdentity(value.Provider)
+	if !ok {
+		return nil
+	}
+	identity, err := adapter.SyncAccountIdentity(ctx, value)
+	if err != nil {
+		if errors.Is(err, provider.ErrUnauthorized) {
+			markErr := s.markSSOCredentialRejected(ctx, value, fmt.Sprintf("%s SSO credential rejected", value.Provider))
+			return errors.Join(err, markErr)
+		}
+		return err
+	}
+	if len(identity.Email) > 255 || len(identity.UserID) > 255 || len(identity.TeamID) > 255 {
+		return fmt.Errorf("Grok Web Session 身份字段超过安全上限")
+	}
+	if err := links.UpdateIdentityMetadata(ctx, id, identity.Email, identity.UserID, identity.TeamID); err != nil {
+		return mapRepositoryError(err)
+	}
+	return mapRepositoryError(links.ReconcileProviderLinks(ctx, id))
+}
+
+func (s *Service) reconcileProviderLinksBestEffort(ctx context.Context, id uint64) {
+	links, ok := s.accounts.(providerLinkRepository)
+	if !ok {
+		return
+	}
+	if err := links.ReconcileProviderLinks(ctx, id); err != nil {
+		s.logger.Warn("account_provider_link_reconcile_failed", "account_id", id, "error", err)
+	}
+}
+
+func (s *Service) syncAccountIdentityBestEffort(ctx context.Context, id uint64) error {
+	if err := s.SyncAccountIdentity(ctx, id); err != nil {
+		s.logger.Warn("account_identity_sync_failed", "account_id", id, "error", err)
+		return err
+	}
+	return nil
+}

backend/internal/application/account/provider_links_test.go

@@ -0,0 +1,172 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"testing"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+)
+
+func TestSyncAccountIdentityLinksUniqueBuildWithoutSharingState(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	service, repo, adapter := newWebAccountSettingsTestService(t)
+	web, _, err := repo.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web", SourceKey: "sso:" + "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+		EncryptedAccessToken: "encrypted", Enabled: true, AuthStatus: accountdomain.AuthStatusActive, Priority: 7, MaxConcurrent: 3,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	build, _, err := repo.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, AuthType: accountdomain.AuthTypeOAuth, Name: "build", SourceKey: "build", UserID: "user-1",
+		EncryptedAccessToken: "encrypted", Enabled: false, AuthStatus: accountdomain.AuthStatusReauthRequired, Priority: 1, MaxConcurrent: 8,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	build.Enabled = false
+	build, err = repo.Update(ctx, build)
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter.identity = provider.AccountIdentity{UserID: "user-1", Email: "user@example.com"}
+	if err := service.SyncAccountIdentity(ctx, web.ID); err != nil {
+		t.Fatal(err)
+	}
+	web, err = repo.Get(ctx, web.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	build, err = repo.Get(ctx, build.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if web.UserID != "user-1" || web.Email != "user@example.com" || len(web.LinkedAccounts) != 1 || web.LinkedAccounts[0].ID != build.ID {
+		t.Fatalf("web = %#v", web)
+	}
+	if !web.Enabled || web.AuthStatus != accountdomain.AuthStatusActive || web.Priority != 7 || web.MaxConcurrent != 3 {
+		t.Fatalf("web operational state changed: %#v", web)
+	}
+	if build.Enabled || build.AuthStatus != accountdomain.AuthStatusReauthRequired {
+		t.Fatalf("build operational state changed: %#v", build)
+	}
+	if err := service.SyncAccountIdentity(ctx, web.ID); err != nil {
+		t.Fatal(err)
+	}
+	if adapter.identityCalls != 1 {
+		t.Fatalf("identity calls = %d", adapter.identityCalls)
+	}
+}
+
+func TestSyncAccountIdentityUnauthorizedInvalidatesCurrentProviderAccount(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	service, repo, adapter := newWebAccountSettingsTestService(t)
+	web, _, err := repo.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web", SourceKey: "sso:" + "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+		EncryptedAccessToken: "encrypted", Enabled: true, AuthStatus: accountdomain.AuthStatusActive, Priority: 1, MaxConcurrent: 8,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter.identityErr = provider.ErrUnauthorized
+	if err := service.SyncAccountIdentity(ctx, web.ID); !errors.Is(err, provider.ErrUnauthorized) {
+		t.Fatalf("err = %v", err)
+	}
+	web, err = repo.Get(ctx, web.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if web.AuthStatus != accountdomain.AuthStatusReauthRequired || !web.Enabled || web.FailureCount != 0 {
+		t.Fatalf("identity unauthorized state = %#v", web)
+	}
+}
+
+func TestSyncAccountIdentityDoesNotRepeatWhenEmailIsKnown(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	service, repo, adapter := newWebAccountSettingsTestService(t)
+	web, _, err := repo.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web", Email: "known@example.com",
+		SourceKey:            "sso:" + "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+		EncryptedAccessToken: "encrypted", Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter.identity = provider.AccountIdentity{UserID: "stable-user", Email: "known@example.com"}
+	if err := service.SyncAccountIdentity(ctx, web.ID); err != nil {
+		t.Fatal(err)
+	}
+	web, err = repo.Get(ctx, web.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if web.UserID != "" || web.Email != "known@example.com" || adapter.identityCalls != 0 {
+		t.Fatalf("identity was fetched again: user_id=%q email=%q calls=%d", web.UserID, web.Email, adapter.identityCalls)
+	}
+}
+
+func TestSyncConsoleAccountIdentityLinksUniqueWebAccountOnce(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "console-identity.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	repo := relational.NewAccountRepository(database)
+	web, _, err := repo.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO, Name: "web",
+		SourceKey: "sso:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+		UserID:    "same-user", EncryptedAccessToken: "encrypted", Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	console, _, err := repo.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderConsole, AuthType: accountdomain.AuthTypeSSO, Name: "console",
+		SourceKey:            "console-sso:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+		EncryptedAccessToken: "encrypted", Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &consoleIdentityAdapterStub{identity: provider.AccountIdentity{UserID: "same-user", Email: "same@example.com"}}
+	service := NewService(repo, nil, nil, nil, provider.NewRegistry(adapter), nil, nil)
+	if err := service.SyncAccountIdentity(ctx, console.ID); err != nil {
+		t.Fatal(err)
+	}
+	if err := service.SyncAccountIdentity(ctx, console.ID); err != nil {
+		t.Fatal(err)
+	}
+	console, err = repo.Get(ctx, console.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if adapter.calls != 1 || console.UserID != "same-user" || len(console.LinkedAccounts) != 1 || console.LinkedAccounts[0].ID != web.ID {
+		t.Fatalf("calls=%d console=%#v", adapter.calls, console)
+	}
+}
+
+type consoleIdentityAdapterStub struct {
+	identity provider.AccountIdentity
+	calls    int
+}
+
+func (*consoleIdentityAdapterStub) Provider() accountdomain.Provider {
+	return accountdomain.ProviderConsole
+}
+
+func (a *consoleIdentityAdapterStub) SyncAccountIdentity(context.Context, accountdomain.Credential) (provider.AccountIdentity, error) {
+	a.calls++
+	return a.identity, nil
+}

backend/internal/application/account/quota_refresh_redis_integration_test.go

@@ -0,0 +1,147 @@
+package account
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	redisruntime "github.com/chenyme/grok2api/backend/internal/infra/runtime/redis"
+	redisclient "github.com/redis/go-redis/v9"
+)
+
+func TestRedisQuotaRefreshCrossInstanceTrailing(t *testing.T) {
+	address := os.Getenv("TEST_REDIS_ADDRESS")
+	if address == "" {
+		t.Skip("TEST_REDIS_ADDRESS is not configured")
+	}
+	databaseNumber, err := redisTestDatabaseNumber()
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx := context.Background()
+	cleanup := redisclient.NewClient(&redisclient.Options{
+		Addr: address, Username: os.Getenv("TEST_REDIS_USERNAME"), Password: os.Getenv("TEST_REDIS_PASSWORD"), DB: databaseNumber,
+	})
+	defer cleanup.Close()
+	if err := cleanup.FlushDB(ctx).Err(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		if err := cleanup.FlushDB(ctx).Err(); err != nil {
+			t.Errorf("flush Redis test database: %v", err)
+		}
+	}()
+
+	prefix := "grok2api:quota-refresh-integration:" + time.Now().UTC().Format("20060102150405.000000000") + ":"
+	config := redisruntime.Config{
+		Address: address, Username: os.Getenv("TEST_REDIS_USERNAME"), Password: os.Getenv("TEST_REDIS_PASSWORD"), Database: databaseNumber,
+		KeyPrefix: prefix, ConcurrencyLease: time.Minute,
+	}
+	firstRuntime, err := redisruntime.Open(ctx, config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer firstRuntime.Close()
+	secondRuntime, err := redisruntime.Open(ctx, config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer secondRuntime.Close()
+
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "quota-refresh-redis-integration.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer database.Close()
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	credential, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO,
+		Name: "redis-cross-instance", SourceKey: "redis-cross-instance", EncryptedAccessToken: "encrypted",
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, WebTier: accountdomain.WebTierSuper,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &quotaCountingAdapter{modeStarted: make(chan struct{}, 4), modeRelease: make(chan struct{}, 4)}
+	registry := provider.NewRegistry(adapter)
+	first := NewService(accounts, nil, nil, nil, registry, nil, redisruntime.NewLockStore(firstRuntime))
+	second := NewService(accounts, nil, nil, nil, registry, nil, redisruntime.NewLockStore(secondRuntime))
+	first.SetQuotaRefreshCoordinator(firstRuntime)
+	second.SetQuotaRefreshCoordinator(secondRuntime)
+
+	runCtx, cancel := context.WithCancel(ctx)
+	done := make(chan struct{}, 2)
+	go func() { first.RunWebQuotaRefresh(runCtx); done <- struct{}{} }()
+	go func() { second.RunWebQuotaRefresh(runCtx); done <- struct{}{} }()
+	t.Cleanup(func() {
+		for range 4 {
+			adapter.modeRelease <- struct{}{}
+		}
+		cancel()
+		<-done
+		<-done
+	})
+
+	first.QueueQuotaRefresh(credential.ID, "weekly")
+	select {
+	case <-adapter.modeStarted:
+	case <-time.After(3 * time.Second):
+		t.Fatal("first Redis-backed refresh did not start")
+	}
+	second.QueueQuotaRefresh(credential.ID, "weekly")
+	deadline := time.Now().Add(3 * time.Second)
+	for {
+		generation, dirty, generationErr := secondRuntime.QuotaRefreshGeneration(ctx, credential.ID, "weekly")
+		if generationErr != nil {
+			t.Fatal(generationErr)
+		}
+		if generation >= 2 && dirty {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("shared Redis generation = %d, dirty = %v", generation, dirty)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	adapter.modeRelease <- struct{}{}
+	select {
+	case <-adapter.modeStarted:
+	case <-time.After(3 * time.Second):
+		t.Fatal("Redis-backed trailing refresh did not start")
+	}
+	adapter.modeRelease <- struct{}{}
+
+	deadline = time.Now().Add(3 * time.Second)
+	for adapter.modeCalls.Load() != 2 && time.Now().Before(deadline) {
+		time.Sleep(10 * time.Millisecond)
+	}
+	if calls := adapter.modeCalls.Load(); calls != 2 {
+		t.Fatalf("Redis-backed refresh calls = %d, want 2", calls)
+	}
+	time.Sleep(2 * webQuotaRefreshRetryInterval)
+	if calls := adapter.modeCalls.Load(); calls != 2 {
+		t.Fatalf("Redis-backed losing instance performed duplicate refresh: %d", calls)
+	}
+}
+
+func redisTestDatabaseNumber() (int, error) {
+	raw := os.Getenv("TEST_REDIS_DATABASE")
+	if raw == "" {
+		return 0, nil
+	}
+	value, err := strconv.Atoi(raw)
+	if err != nil || value < 0 {
+		return 0, fmt.Errorf("TEST_REDIS_DATABASE = %q", raw)
+	}
+	return value, nil
+}

backend/internal/application/account/quota_refresh_test.go

@@ -0,0 +1,620 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/infra/persistence/relational"
+	"github.com/chenyme/grok2api/backend/internal/infra/provider"
+	"github.com/chenyme/grok2api/backend/internal/infra/runtime/memory"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+func TestWebQuotaRefreshDeduplicatesPerMode(t *testing.T) {
+	service := NewService(nil, nil, nil, nil, nil, nil, nil)
+	service.QueueWebQuotaRefresh(42, "fast")
+	service.QueueWebQuotaRefresh(42, "expert")
+	service.QueueWebQuotaRefresh(42, "fast")
+
+	service.quotaRefreshMu.Lock()
+	defer service.quotaRefreshMu.Unlock()
+	if len(service.quotaRefreshes) != 2 {
+		t.Fatalf("refresh states = %#v", service.quotaRefreshes)
+	}
+	if service.quotaRefreshes["42:fast"].generation != 2 || !service.quotaRefreshes["42:fast"].queued {
+		t.Fatal("duplicate fast refresh was not coalesced into the queued generation")
+	}
+	if service.quotaRefreshes["42:expert"].generation != 1 || !service.quotaRefreshes["42:expert"].queued {
+		t.Fatal("independent expert refresh state is invalid")
+	}
+	if len(service.quotaRefreshQueue) != 2 {
+		t.Fatalf("queued refreshes = %d", len(service.quotaRefreshQueue))
+	}
+}
+
+func TestWeeklyQuotaRefreshPreservesTrailingSnapshot(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "weekly-quota-refresh.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	credential, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO,
+		Name: "weekly", SourceKey: "weekly", EncryptedAccessToken: "encrypted",
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, WebTier: accountdomain.WebTierSuper,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &quotaCountingAdapter{
+		modeStarted: make(chan struct{}, 2),
+		modeRelease: make(chan struct{}, 2),
+	}
+	service := NewService(accounts, nil, nil, nil, provider.NewRegistry(adapter), nil, nil)
+
+	service.QueueQuotaRefresh(credential.ID, "weekly")
+	request := <-service.quotaRefreshQueue
+	done := make(chan struct{})
+	go func() {
+		service.runWebQuotaRefresh(ctx, request)
+		close(done)
+	}()
+
+	select {
+	case <-adapter.modeStarted:
+	case <-time.After(time.Second):
+		t.Fatal("first weekly refresh did not start")
+	}
+	service.QueueQuotaRefresh(credential.ID, "weekly")
+	adapter.modeRelease <- struct{}{}
+
+	select {
+	case <-adapter.modeStarted:
+	case <-time.After(time.Second):
+		t.Fatal("trailing weekly refresh did not start")
+	}
+	adapter.modeRelease <- struct{}{}
+
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("weekly refresh did not finish")
+	}
+	if adapter.modeCalls.Load() != 2 {
+		t.Fatalf("weekly refresh calls = %d, want 2", adapter.modeCalls.Load())
+	}
+	service.quotaRefreshMu.Lock()
+	_, exists := service.quotaRefreshes[request.key]
+	service.quotaRefreshMu.Unlock()
+	if exists {
+		t.Fatal("completed weekly refresh retained queue state")
+	}
+}
+
+func TestQuotaRefreshQueueOverflowRetainsDirtyState(t *testing.T) {
+	service := NewService(nil, nil, nil, nil, nil, nil, nil)
+	service.quotaRefreshQueue = make(chan webQuotaRefreshRequest, 1)
+	service.QueueQuotaRefresh(1, "fast")
+	service.QueueQuotaRefresh(2, "fast")
+
+	service.quotaRefreshMu.Lock()
+	state := service.quotaRefreshes["2:fast"]
+	if state == nil || state.generation != 1 || state.queued || state.running {
+		service.quotaRefreshMu.Unlock()
+		t.Fatalf("overflow state = %#v", state)
+	}
+	service.quotaRefreshMu.Unlock()
+
+	first := <-service.quotaRefreshQueue
+	if first.accountID != 1 {
+		t.Fatalf("first queued account = %d", first.accountID)
+	}
+	service.requeueQuotaRefreshes()
+	second := <-service.quotaRefreshQueue
+	if second.accountID != 2 || second.mode != "fast" {
+		t.Fatalf("recovered request = %#v", second)
+	}
+	service.quotaRefreshMu.Lock()
+	recovered := service.quotaRefreshes["2:fast"]
+	service.quotaRefreshMu.Unlock()
+	if recovered == nil || !recovered.queued || recovered.running {
+		t.Fatalf("recovered state = %#v", recovered)
+	}
+}
+
+func TestQuotaRefreshCrossInstanceGenerationTriggersSingleTrailingRefresh(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "quota-cross-instance.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	credential, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO,
+		Name: "cross-instance", SourceKey: "cross-instance", EncryptedAccessToken: "encrypted",
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, WebTier: accountdomain.WebTierSuper,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &quotaCountingAdapter{modeStarted: make(chan struct{}, 4), modeRelease: make(chan struct{}, 4)}
+	registry := provider.NewRegistry(adapter)
+	coordinator := memory.NewQuotaRefreshCoordinator()
+	lock := memory.NewLockStore()
+	first := NewService(accounts, nil, nil, nil, registry, nil, lock)
+	second := NewService(accounts, nil, nil, nil, registry, nil, lock)
+	first.SetQuotaRefreshCoordinator(coordinator)
+	second.SetQuotaRefreshCoordinator(coordinator)
+	runCtx, cancel := context.WithCancel(ctx)
+	done := make(chan struct{}, 2)
+	go func() { first.RunWebQuotaRefresh(runCtx); done <- struct{}{} }()
+	go func() { second.RunWebQuotaRefresh(runCtx); done <- struct{}{} }()
+	t.Cleanup(func() {
+		for range 4 {
+			adapter.modeRelease <- struct{}{}
+		}
+		cancel()
+		<-done
+		<-done
+	})
+
+	first.QueueQuotaRefresh(credential.ID, "weekly")
+	select {
+	case <-adapter.modeStarted:
+	case <-time.After(2 * time.Second):
+		t.Fatal("first refresh did not start")
+	}
+	second.QueueQuotaRefresh(credential.ID, "weekly")
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		generation, dirty, generationErr := coordinator.QuotaRefreshGeneration(ctx, credential.ID, "weekly")
+		if generationErr != nil {
+			t.Fatal(generationErr)
+		}
+		if generation >= 2 && dirty {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("shared generation = %d, dirty = %v", generation, dirty)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	adapter.modeRelease <- struct{}{}
+	select {
+	case <-adapter.modeStarted:
+	case <-time.After(2 * time.Second):
+		t.Fatal("trailing refresh did not start")
+	}
+	adapter.modeRelease <- struct{}{}
+
+	deadline = time.Now().Add(2 * time.Second)
+	for adapter.modeCalls.Load() != 2 && time.Now().Before(deadline) {
+		time.Sleep(10 * time.Millisecond)
+	}
+	if calls := adapter.modeCalls.Load(); calls != 2 {
+		t.Fatalf("refresh calls = %d, want 2", calls)
+	}
+	time.Sleep(2 * webQuotaRefreshRetryInterval)
+	if calls := adapter.modeCalls.Load(); calls != 2 {
+		t.Fatalf("losing instance performed duplicate refresh: %d", calls)
+	}
+}
+
+func TestRefreshQuotaModeDoesNotTriggerFullProviderSyncForAutoTier(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "quota-mode.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	credential, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO,
+		Name: "web-auto", SourceKey: "web-auto", EncryptedAccessToken: "encrypted",
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, WebTier: accountdomain.WebTierAuto,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &quotaCountingAdapter{}
+	service := NewService(accounts, nil, nil, nil, provider.NewRegistry(adapter), nil, nil)
+	window, err := service.RefreshQuotaMode(ctx, credential.ID, "fast")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if window.Mode != "fast" || adapter.modeCalls.Load() != 1 || adapter.fullCalls.Load() != 0 {
+		t.Fatalf("window = %#v, mode calls = %d, full calls = %d", window, adapter.modeCalls.Load(), adapter.fullCalls.Load())
+	}
+	stored, err := accounts.Get(ctx, credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stored.WebTier != accountdomain.WebTierAuto {
+		t.Fatalf("single-mode sync changed tier to %q", stored.WebTier)
+	}
+
+	service.QueueQuotaRefresh(credential.ID, "fast")
+	service.QueueQuotaRefresh(credential.ID, "fast")
+	request := <-service.quotaRefreshQueue
+	service.runWebQuotaRefresh(ctx, request)
+	if adapter.modeCalls.Load() != 2 || adapter.fullCalls.Load() != 0 {
+		t.Fatalf("coalesced mode calls = %d, full calls = %d", adapter.modeCalls.Load(), adapter.fullCalls.Load())
+	}
+	service.quotaRefreshMu.Lock()
+	_, queued := service.quotaRefreshes[request.key]
+	service.quotaRefreshMu.Unlock()
+	if queued {
+		t.Fatal("completed coalesced refresh retained queue state")
+	}
+
+	service.refreshLock = deniedQuotaRefreshLock{}
+	service.QueueQuotaRefresh(credential.ID, "fast")
+	request = <-service.quotaRefreshQueue
+	service.runWebQuotaRefresh(ctx, request)
+	if adapter.modeCalls.Load() != 2 {
+		t.Fatalf("worker without distributed lease made %d mode calls", adapter.modeCalls.Load())
+	}
+}
+
+func TestObserveResponseModelCoalescesUnchangedValues(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "observed-model.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	base := relational.NewAccountRepository(database)
+	credential, _, err := base.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, AuthType: accountdomain.AuthTypeOAuth,
+		Name: "observed", SourceKey: "observed", EncryptedAccessToken: "encrypted",
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	accounts := &observedModelCountingRepository{AccountRepository: base}
+	service := NewService(accounts, nil, nil, nil, nil, nil, nil)
+	now := time.Now().UTC()
+	service.now = func() time.Time { return now }
+
+	if err := service.ObserveResponseModel(ctx, credential.ID, "grok-4.5"); err != nil {
+		t.Fatal(err)
+	}
+	if err := service.ObserveResponseModel(ctx, credential.ID, "grok-4.5"); err != nil {
+		t.Fatal(err)
+	}
+	now = now.Add(observedModelPersistInterval - time.Second)
+	if err := service.ObserveResponseModel(ctx, credential.ID, "grok-4.5"); err != nil {
+		t.Fatal(err)
+	}
+	if calls := accounts.calls.Load(); calls != 1 {
+		t.Fatalf("unchanged model writes = %d, want 1", calls)
+	}
+
+	now = now.Add(2 * time.Second)
+	if err := service.ObserveResponseModel(ctx, credential.ID, "grok-4.5"); err != nil {
+		t.Fatal(err)
+	}
+	if err := service.ObserveResponseModel(ctx, credential.ID, "grok-4.5-mini"); err != nil {
+		t.Fatal(err)
+	}
+	if calls := accounts.calls.Load(); calls != 3 {
+		t.Fatalf("interval and model transition writes = %d, want 3", calls)
+	}
+}
+
+func TestObserveResponseModelRefreshesAfterCrossInstanceStateChange(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "observed-model-shared.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	base := relational.NewAccountRepository(database)
+	credential, _, err := base.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, AuthType: accountdomain.AuthTypeOAuth,
+		Name: "observed-shared", SourceKey: "observed-shared", EncryptedAccessToken: "encrypted",
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	accounts := &observedModelCountingRepository{AccountRepository: base}
+	shared := &observedModelTestStore{values: make(map[uint64]repository.ObservedModelState)}
+	service := NewService(accounts, nil, nil, nil, nil, nil, nil)
+	service.SetObservedModelStore(shared)
+	now := time.Now().UTC()
+	service.now = func() time.Time { return now }
+	if err := service.ObserveResponseModel(ctx, credential.ID, "grok-4.5"); err != nil {
+		t.Fatal(err)
+	}
+	shared.mu.Lock()
+	shared.values[credential.ID] = repository.ObservedModelState{Model: "grok-4.5-build-free", ObservedAt: now}
+	shared.mu.Unlock()
+	now = now.Add(observedModelLocalCacheTTL + time.Second)
+	if err := service.ObserveResponseModel(ctx, credential.ID, "grok-4.5"); err != nil {
+		t.Fatal(err)
+	}
+	if calls := accounts.calls.Load(); calls != 2 {
+		t.Fatalf("cross-instance model change was suppressed, writes = %d", calls)
+	}
+}
+
+func TestObserveResponseModelCoalescesConcurrentFirstWrite(t *testing.T) {
+	accounts := &observedModelBlockingRepository{
+		started: make(chan struct{}),
+		release: make(chan struct{}),
+	}
+	service := NewService(accounts, nil, nil, nil, nil, nil, nil)
+	const workers = 32
+	start := make(chan struct{})
+	var launched sync.WaitGroup
+	launched.Add(workers)
+	errorsCh := make(chan error, workers)
+	var wait sync.WaitGroup
+	wait.Add(workers)
+	for range workers {
+		go func() {
+			defer wait.Done()
+			launched.Done()
+			<-start
+			errorsCh <- service.ObserveResponseModel(context.Background(), 42, "grok-4.5")
+		}()
+	}
+	launched.Wait()
+	close(start)
+	<-accounts.started
+	time.Sleep(25 * time.Millisecond)
+	close(accounts.release)
+	wait.Wait()
+	close(errorsCh)
+	for err := range errorsCh {
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	if calls := accounts.calls.Load(); calls != 1 {
+		t.Fatalf("concurrent unchanged model writes = %d, want 1", calls)
+	}
+}
+
+func TestObserveResponseModelKeepsNewerLocalStateAfterOutOfOrderCompletion(t *testing.T) {
+	accounts := &observedModelOrderingRepository{
+		olderStarted: make(chan struct{}),
+		olderRelease: make(chan struct{}),
+	}
+	service := NewService(accounts, nil, nil, nil, nil, nil, nil)
+	current := time.Now().UTC()
+	var nowMu sync.RWMutex
+	service.now = func() time.Time {
+		nowMu.RLock()
+		defer nowMu.RUnlock()
+		return current
+	}
+	olderDone := make(chan error, 1)
+	go func() {
+		olderDone <- service.ObserveResponseModel(context.Background(), 42, "grok-older")
+	}()
+	<-accounts.olderStarted
+	nowMu.Lock()
+	current = current.Add(time.Minute)
+	nowMu.Unlock()
+	if err := service.ObserveResponseModel(context.Background(), 42, "grok-newer"); err != nil {
+		t.Fatal(err)
+	}
+	close(accounts.olderRelease)
+	if err := <-olderDone; err != nil {
+		t.Fatal(err)
+	}
+	if err := service.ObserveResponseModel(context.Background(), 42, "grok-newer"); err != nil {
+		t.Fatal(err)
+	}
+	if calls := accounts.calls.Load(); calls != 2 {
+		t.Fatalf("out-of-order writes = %d, want 2", calls)
+	}
+}
+
+type observedModelCountingRepository struct {
+	repository.AccountRepository
+	calls atomic.Int64
+}
+
+type observedModelBlockingRepository struct {
+	repository.AccountRepository
+	calls   atomic.Int64
+	started chan struct{}
+	release chan struct{}
+	once    sync.Once
+}
+
+type observedModelOrderingRepository struct {
+	repository.AccountRepository
+	calls        atomic.Int64
+	olderStarted chan struct{}
+	olderRelease chan struct{}
+}
+
+type observedModelTestStore struct {
+	mu     sync.Mutex
+	values map[uint64]repository.ObservedModelState
+}
+
+func (s *observedModelTestStore) GetObservedModelState(_ context.Context, accountID uint64) (repository.ObservedModelState, bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	value, ok := s.values[accountID]
+	return value, ok, nil
+}
+
+func (s *observedModelTestStore) SetObservedModelState(_ context.Context, accountID uint64, value repository.ObservedModelState, _ time.Duration) error {
+	s.mu.Lock()
+	s.values[accountID] = value
+	s.mu.Unlock()
+	return nil
+}
+
+func (r *observedModelCountingRepository) UpdateObservedModel(ctx context.Context, id uint64, model string, observedAt time.Time) error {
+	r.calls.Add(1)
+	return r.AccountRepository.UpdateObservedModel(ctx, id, model, observedAt)
+}
+
+func (r *observedModelBlockingRepository) UpdateObservedModel(context.Context, uint64, string, time.Time) error {
+	r.calls.Add(1)
+	r.once.Do(func() { close(r.started) })
+	<-r.release
+	return nil
+}
+
+func (r *observedModelOrderingRepository) UpdateObservedModel(_ context.Context, _ uint64, model string, _ time.Time) error {
+	r.calls.Add(1)
+	if model == "grok-older" {
+		close(r.olderStarted)
+		<-r.olderRelease
+	}
+	return nil
+}
+
+func TestRefreshQuotaFetchesWebIdentityOnlyUntilDataExists(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "quota-identity.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	credential, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO,
+		Name: "web-identity", SourceKey: "web-identity", EncryptedAccessToken: "encrypted",
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive, WebTier: accountdomain.WebTierAuto,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &quotaCountingAdapter{}
+	service := NewService(accounts, nil, nil, nil, provider.NewRegistry(adapter), nil, nil)
+	for range 2 {
+		if _, err := service.RefreshQuota(ctx, credential.ID); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if adapter.fullCalls.Load() != 2 || adapter.identityCalls.Load() != 1 {
+		t.Fatalf("quota calls=%d identity calls=%d", adapter.fullCalls.Load(), adapter.identityCalls.Load())
+	}
+	stored, err := accounts.Get(ctx, credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stored.Email != "identity@example.com" {
+		t.Fatalf("email = %q", stored.Email)
+	}
+}
+
+func TestRefreshQuotaUnauthorizedMarksWebAccountInvalid(t *testing.T) {
+	ctx := context.Background()
+	database, err := relational.OpenSQLite(ctx, filepath.Join(t.TempDir(), "quota-unauthorized.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = database.Close() })
+	if err := database.InitializeSchema(ctx); err != nil {
+		t.Fatal(err)
+	}
+	accounts := relational.NewAccountRepository(database)
+	credential, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderWeb, AuthType: accountdomain.AuthTypeSSO,
+		Name: "web-unauthorized", SourceKey: "web-unauthorized", EncryptedAccessToken: "encrypted",
+		Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapter := &quotaCountingAdapter{fullErr: provider.ErrUnauthorized}
+	service := NewService(accounts, nil, nil, nil, provider.NewRegistry(adapter), nil, nil)
+	if _, err := service.RefreshQuota(ctx, credential.ID); !errors.Is(err, provider.ErrUnauthorized) {
+		t.Fatalf("err = %v", err)
+	}
+	stored, err := accounts.Get(ctx, credential.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stored.AuthStatus != accountdomain.AuthStatusReauthRequired || !stored.Enabled {
+		t.Fatalf("account state = %#v", stored)
+	}
+}
+
+type deniedQuotaRefreshLock struct{}
+
+func (deniedQuotaRefreshLock) Acquire(context.Context, string, time.Duration) (func(), bool, error) {
+	return nil, false, nil
+}
+
+type quotaCountingAdapter struct {
+	modeCalls     atomic.Int64
+	fullCalls     atomic.Int64
+	identityCalls atomic.Int64
+	fullErr       error
+	modeStarted   chan struct{}
+	modeRelease   chan struct{}
+}
+
+func (a *quotaCountingAdapter) Provider() accountdomain.Provider { return accountdomain.ProviderWeb }
+
+func (a *quotaCountingAdapter) Definition() provider.Definition {
+	return provider.Definition{
+		Provider: accountdomain.ProviderWeb, ModelNamespace: accountdomain.ProviderWeb.ModelNamespace(),
+		Quota: provider.QuotaRemoteWindow, Credential: provider.CredentialSurface{AuthType: accountdomain.AuthTypeSSO},
+	}
+}
+
+func (a *quotaCountingAdapter) SyncQuota(context.Context, accountdomain.Credential) (provider.QuotaSnapshot, error) {
+	a.fullCalls.Add(1)
+	return provider.QuotaSnapshot{}, a.fullErr
+}
+
+func (a *quotaCountingAdapter) SyncAccountIdentity(context.Context, accountdomain.Credential) (provider.AccountIdentity, error) {
+	a.identityCalls.Add(1)
+	return provider.AccountIdentity{Email: "identity@example.com"}, nil
+}
+
+func (a *quotaCountingAdapter) SyncQuotaMode(_ context.Context, credential accountdomain.Credential, mode string) (accountdomain.QuotaWindow, error) {
+	a.modeCalls.Add(1)
+	if a.modeStarted != nil {
+		a.modeStarted <- struct{}{}
+	}
+	if a.modeRelease != nil {
+		<-a.modeRelease
+	}
+	now := time.Now().UTC()
+	resetAt := now.Add(time.Hour)
+	return accountdomain.QuotaWindow{
+		AccountID: credential.ID, Mode: mode, Remaining: 0, Total: 30,
+		WindowSeconds: 3600, ResetAt: &resetAt, SyncedAt: &now, Source: accountdomain.QuotaSourceUpstream, UpdatedAt: now,
+	}, nil
+}

backend/internal/application/account/quota_test.go

@@ -0,0 +1,256 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"slices"
+	"testing"
+	"time"
+
+	accountdomain "github.com/chenyme/grok2api/backend/internal/domain/account"
+	"github.com/chenyme/grok2api/backend/internal/repository"
+)
+
+type quotaResetRepository struct {
+	repository.AccountRepository
+	countBatchSizes []int
+	resetBatchSizes []int
+}
+
+func (r *quotaResetRepository) CountProviderAccountsByIDs(_ context.Context, provider accountdomain.Provider, ids []uint64) (int64, error) {
+	if provider != accountdomain.ProviderBuild {
+		return 0, nil
+	}
+	r.countBatchSizes = append(r.countBatchSizes, len(ids))
+	return int64(len(ids)), nil
+}
+
+func (r *quotaResetRepository) ResetQuotaState(_ context.Context, provider accountdomain.Provider, ids []uint64) error {
+	if provider != accountdomain.ProviderBuild {
+		return errors.New("unexpected provider")
+	}
+	r.resetBatchSizes = append(r.resetBatchSizes, len(ids))
+	return nil
+}
+
+func TestNewQuotaViewFreeUsesObservedRollingTokens(t *testing.T) {
+	quota := newQuotaView(&accountdomain.Billing{IsUnifiedBillingUser: true}, 250_000, nil, "grok-4.5-build-free", false)
+	if quota.Type != QuotaTypeFree || quota.Unit != "tokens" || quota.Limit != 500_000 || quota.LimitKnown || quota.Confidence != "observed" {
+		t.Fatalf("quota = %#v", quota)
+	}
+	if quota.Used != 250_000 || quota.Remaining != 250_000 || quota.UsagePercent != 50 || quota.WindowHours != 24 || !quota.Observed {
+		t.Fatalf("quota = %#v", quota)
+	}
+}
+
+func TestNewQuotaViewPaidUsesMonthlyBilling(t *testing.T) {
+	quota := newQuotaView(&accountdomain.Billing{MonthlyLimit: 200, Used: 50, BillingPeriodStart: "start", BillingPeriodEnd: "end"}, 900_000, nil, "", false)
+	if quota.Type != QuotaTypePaid || quota.Unit != "credits" || quota.Limit != 200 {
+		t.Fatalf("quota = %#v", quota)
+	}
+	if quota.Used != 50 || quota.Remaining != 150 || quota.UsagePercent != 25 || quota.Observed || !quota.LimitKnown {
+		t.Fatalf("quota = %#v", quota)
+	}
+}
+
+func TestNewQuotaViewPaidShowsBillingProbeState(t *testing.T) {
+	now := time.Now().UTC()
+	next := now.Add(time.Hour)
+	quota := newQuotaView(&accountdomain.Billing{MonthlyLimit: 100, Used: 100}, 0, &accountdomain.QuotaRecovery{
+		Kind: accountdomain.QuotaRecoveryKindPaid, Status: accountdomain.QuotaRecoveryStatusExhausted,
+		ExhaustedAt: &now, NextProbeAt: &next,
+	}, "", false)
+	if quota.Type != QuotaTypePaid || quota.Status != QuotaStatusWaitingReset || quota.NextProbeAt == nil {
+		t.Fatalf("quota = %#v", quota)
+	}
+}
+
+func TestNewQuotaViewUnknownWithoutBillingSnapshot(t *testing.T) {
+	quota := newQuotaView(nil, 100, nil, "", false)
+	if quota.Type != QuotaTypeUnknown {
+		t.Fatalf("quota = %#v", quota)
+	}
+}
+
+func TestNewQuotaViewEstimatesFreeFromObservedZeroBillingProfile(t *testing.T) {
+	quota := newQuotaView(&accountdomain.Billing{PlanName: "Free", IsUnifiedBillingUser: true, TopUpMethod: "TOP_UP_METHOD_SAVED_PAYMENT_METHOD"}, 100, nil, "", false)
+	if quota.Type != QuotaTypeFree || quota.Source != "billingProfile" || quota.Confidence != "estimated" || quota.Limit != 500_000 || quota.LimitKnown {
+		t.Fatalf("quota = %#v", quota)
+	}
+}
+
+func TestNewQuotaViewInfersFreeFromSuccessfulZeroBillingSnapshot(t *testing.T) {
+	quota := newQuotaView(&accountdomain.Billing{
+		IsUnifiedBillingUser: true, UsagePeriodType: "USAGE_PERIOD_TYPE_WEEKLY", SyncedAt: time.Now().UTC(),
+	}, 100, nil, "", false)
+	if quota.Type != QuotaTypeFree || quota.Source != "billingProfile" || quota.Confidence != "estimated" {
+		t.Fatalf("quota = %#v", quota)
+	}
+}
+
+func TestNewQuotaViewTreatsZeroUsageSuperGrokAsPaid(t *testing.T) {
+	quota := newQuotaView(&accountdomain.Billing{
+		PlanName: "SuperGrok", IsUnifiedBillingUser: true,
+		UsagePeriodType: "USAGE_PERIOD_TYPE_WEEKLY", CreditUsagePercent: 0,
+	}, 0, nil, "", false)
+	if quota.Type != QuotaTypePaid || quota.Unit != "percent" || quota.Limit != 100 || quota.Remaining != 100 || quota.Confidence != "observed" {
+		t.Fatalf("quota = %#v", quota)
+	}
+}
+
+func TestNewQuotaViewUsesConfirmedExhaustion(t *testing.T) {
+	now := time.Now().UTC()
+	next := now.Add(24 * time.Hour)
+	quota := newQuotaView(&accountdomain.Billing{}, 250_000, &accountdomain.QuotaRecovery{
+		Status: accountdomain.QuotaRecoveryStatusExhausted, ConfirmedUsed: 1_065_387,
+		ConfirmedLimit: 1_000_000, ExhaustedAt: &now, NextProbeAt: &next, LastConfirmedAt: &now,
+	}, "", false)
+	if quota.Type != QuotaTypeFree || quota.Status != QuotaStatusWaitingReset || !quota.Confirmed {
+		t.Fatalf("quota = %#v", quota)
+	}
+	if quota.Used != 1_065_387 || quota.Limit != 1_000_000 || quota.Remaining != 0 || quota.NextProbeAt == nil || !quota.LimitKnown {
+		t.Fatalf("quota = %#v", quota)
+	}
+}
+
+func TestNewQuotaViewBuildSuperEntitlementOverridesFreeSignals(t *testing.T) {
+	now := time.Now().UTC()
+	next := now.Add(time.Hour)
+	// 零 Billing profile + entitlement → paid/Super，不伪造额度。
+	quota := newQuotaView(&accountdomain.Billing{IsUnifiedBillingUser: true, TopUpMethod: "TOP_UP_METHOD_SAVED_PAYMENT_METHOD"}, 100, nil, "grok-4.5-build-free", true)
+	if quota.Type != QuotaTypePaid || quota.Source != "buildSuperEntitlement" || quota.Confidence != "confirmed" || !quota.Confirmed {
+		t.Fatalf("entitlement quota = %#v", quota)
+	}
+	if quota.LimitKnown || quota.Used != 0 || quota.Limit != 0 || quota.Unit != "" {
+		t.Fatalf("must not fabricate limits: %#v", quota)
+	}
+	// Free recovery 不得把 entitlement 账号降回 Free。
+	quota = newQuotaView(&accountdomain.Billing{}, 250_000, &accountdomain.QuotaRecovery{
+		Kind: accountdomain.QuotaRecoveryKindFree, Status: accountdomain.QuotaRecoveryStatusExhausted,
+		ConfirmedUsed: 1_000_000, ConfirmedLimit: 1_000_000, ExhaustedAt: &now, NextProbeAt: &next,
+	}, "", true)
+	if quota.Type != QuotaTypePaid || quota.Source != "buildSuperEntitlement" {
+		t.Fatalf("entitlement must override free recovery: %#v", quota)
+	}
+	// Billing paid 仍优先展示真实额度。
+	quota = newQuotaView(&accountdomain.Billing{MonthlyLimit: 200, Used: 50}, 0, nil, "", true)
+	if quota.Type != QuotaTypePaid || quota.Source != "upstreamBilling" || quota.Limit != 200 {
+		t.Fatalf("paid billing must win: %#v", quota)
+	}
+}
+
+func TestBatchResetQuotaStatePreservesBillingAndClearsLocalBlocks(t *testing.T) {
+	ctx := context.Background()
+	service, accounts := openAccountService(t)
+	credential, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+		Provider: accountdomain.ProviderBuild, Name: "build", SourceKey: "quota-reset-build",
+		EncryptedAccessToken: "encrypted", Enabled: true, AuthStatus: accountdomain.AuthStatusActive,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	now := time.Now().UTC()
+	next := now.Add(24 * time.Hour)
+	if err := accounts.SaveBilling(ctx, accountdomain.Billing{AccountID: credential.ID, PlanName: "free", Used: 42, SyncedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	if err := accounts.SaveQuotaRecovery(ctx, accountdomain.QuotaRecovery{
+		AccountID: credential.ID, Kind: accountdomain.QuotaRecoveryKindFree, Status: accountdomain.QuotaRecoveryStatusExhausted,
+		ExhaustedAt: &now, NextProbeAt: &next, UpdatedAt: now,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := accounts.UpsertModelQuotaBlock(ctx, accountdomain.ModelQuotaBlock{
+		AccountID: credential.ID, UpstreamModel: "grok-test", Reason: "model_quota_depleted", CooldownUntil: next,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := accounts.UpsertModelQuotaBlock(ctx, accountdomain.ModelQuotaBlock{
+		AccountID: credential.ID, UpstreamModel: "grok-denied", Reason: "model_access_denied", CooldownUntil: next,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	reset, err := service.BatchResetQuotaState(ctx, []uint64{credential.ID})
+	if err != nil || reset != 1 {
+		t.Fatalf("reset = %d, err = %v", reset, err)
+	}
+	if _, err := accounts.GetQuotaRecovery(ctx, credential.ID); !errors.Is(err, repository.ErrNotFound) {
+		t.Fatalf("quota recovery should be cleared, err = %v", err)
+	}
+	billing, err := accounts.GetBilling(ctx, credential.ID)
+	if err != nil || billing.Used != 42 {
+		t.Fatalf("billing = %#v, err = %v", billing, err)
+	}
+	candidates, err := accounts.ListRoutingCandidates(ctx, accountdomain.ProviderBuild, 0, "grok-test", "")
+	if err != nil || len(candidates) != 1 || candidates[0].ModelQuotaBlock != nil {
+		t.Fatalf("candidates = %#v, err = %v", candidates, err)
+	}
+	candidates, err = accounts.ListRoutingCandidates(ctx, accountdomain.ProviderBuild, 0, "grok-denied", "")
+	if err != nil || len(candidates) != 1 || candidates[0].ModelQuotaBlock == nil || candidates[0].ModelQuotaBlock.Reason != "model_access_denied" {
+		t.Fatalf("access denial must be preserved, candidates = %#v, err = %v", candidates, err)
+	}
+}
+
+func TestResetAllBuildQuotaStateOnlyProcessesEnabledBuildAccounts(t *testing.T) {
+	ctx := context.Background()
+	service, accounts := openAccountService(t)
+	create := func(providerValue accountdomain.Provider, sourceKey string, enabled bool) accountdomain.Credential {
+		value, _, err := accounts.UpsertByIdentity(ctx, accountdomain.Credential{
+			Provider: providerValue, Name: sourceKey, SourceKey: sourceKey,
+			EncryptedAccessToken: "encrypted", Enabled: enabled, AuthStatus: accountdomain.AuthStatusActive,
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return value
+	}
+	enabledBuild := create(accountdomain.ProviderBuild, "reset-all-enabled", true)
+	disabledBuild := create(accountdomain.ProviderBuild, "reset-all-disabled", false)
+	web := create(accountdomain.ProviderWeb, "reset-all-web", true)
+	disabledBuild.Enabled = false
+	if _, err := accounts.Update(ctx, disabledBuild); err != nil {
+		t.Fatal(err)
+	}
+	now := time.Now().UTC()
+	next := now.Add(24 * time.Hour)
+	for _, value := range []accountdomain.Credential{enabledBuild, disabledBuild, web} {
+		if err := accounts.SaveQuotaRecovery(ctx, accountdomain.QuotaRecovery{
+			AccountID: value.ID, Kind: accountdomain.QuotaRecoveryKindFree, Status: accountdomain.QuotaRecoveryStatusExhausted,
+			ExhaustedAt: &now, NextProbeAt: &next, UpdatedAt: now,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	reset, err := service.ResetAllBuildQuotaState(ctx)
+	if err != nil || reset != 1 {
+		t.Fatalf("reset = %d, err = %v", reset, err)
+	}
+	if _, err := accounts.GetQuotaRecovery(ctx, enabledBuild.ID); !errors.Is(err, repository.ErrNotFound) {
+		t.Fatalf("enabled Build recovery should be cleared, err = %v", err)
+	}
+	for _, value := range []accountdomain.Credential{disabledBuild, web} {
+		if _, err := accounts.GetQuotaRecovery(ctx, value.ID); err != nil {
+			t.Fatalf("recovery for account %d should remain, err = %v", value.ID, err)
+		}
+	}
+}
+
+func TestBatchResetQuotaStateChunksMoreThanAdminPageLimit(t *testing.T) {
+	repo := &quotaResetRepository{}
+	service := &Service{accounts: repo}
+	ids := make([]uint64, 2501)
+	for index := range ids {
+		ids[index] = uint64(index + 1)
+	}
+
+	reset, err := service.BatchResetQuotaState(context.Background(), ids)
+	if err != nil || reset != len(ids) {
+		t.Fatalf("reset = %d, err = %v", reset, err)
+	}
+	want := []int{500, 500, 500, 500, 500, 1}
+	if !slices.Equal(repo.countBatchSizes, want) || !slices.Equal(repo.resetBatchSizes, want) {
+		t.Fatalf("count batches = %v, reset batches = %v, want %v", repo.countBatchSizes, repo.resetBatchSizes, want)
+	}
+}