fix: build usage keeper from source

.dockerignore

@@ -1,4 +1,22 @@
+# git
 .git
-__pycache__
-*.pyc
+.gitignore
+
+# local env and editor files
+.env
+.env.*
+!.env.example
 .DS_Store
+
+# runtime data
+/data/
+*.db
+*.db-*
+backups/
+
+# frontend deps and build cache
+web/node_modules/
+web/dist/
+
+# docs / temp
+.tmp-test.db

.env.example

@@ -0,0 +1,75 @@
+# CPA 服务基础地址。必填：是。默认值：无。
+# Base URL of the CPA service. Required: yes. Default: none.
+CPA_BASE_URL=http://127.0.0.1:8317
+
+# CPA management key，用于拉取管理接口数据。必填：是。默认值：无。
+# CPA management key used to access management endpoints. Required: yes. Default: none.
+CPA_MANAGEMENT_KEY=replace-with-your-management-key
+
+# 是否启用登录保护。必填：否。默认值：false。
+# Whether to enable login protection. Required: no. Default: false.
+AUTH_ENABLED=false
+
+# 登录密码；仅在启用登录保护时必填。默认值：无。
+# Login password; required only when login protection is enabled. Default: none.
+LOGIN_PASSWORD=replace-with-your-login-password
+
+# 登录 session 的有效时长。必填：否。默认值：168h。
+# Lifetime of the login session. Required: no. Default: 168h.
+AUTH_SESSION_TTL=168h
+
+# HTTP 服务监听端口。必填：否。默认值：8080。
+# HTTP listen port for the application. Required: no. Default: 8080.
+APP_PORT=8080
+
+# 留空表示部署在根路径 /；如需部署到子路径，必须以 / 开头，例如 /cpa。允许写成 /cpa/，程序会自动规范成 /cpa；不建议写成不带前导斜杠的 cpa。必填：否。默认值：空（根路径 /）。
+# Leave empty to serve from /. For subpath deployment, the value must start with /, for example /cpa. A trailing slash like /cpa/ is accepted and normalized to /cpa; a value without the leading slash such as cpa is invalid. Required: no. Default: empty (root path /).
+APP_BASE_PATH=
+
+# 项目业务时区，影响 Today、按天聚合、每日 03:00 清理和日志时间。必填：否。默认值：Asia/Shanghai。
+# Project business timezone. Affects Today, daily aggregation, daily 03:00 cleanup, and log timestamps. Required: no. Default: Asia/Shanghai.
+TZ=Asia/Shanghai
+
+# CPA management data stream 的 Redis/RESP TCP 地址。留空时默认使用 CPA_BASE_URL 的主机名加 8317 端口；如果通过 nginx stream 暴露到其它端口，请显式填写 host:port。
+# Redis/RESP TCP address for the CPA management data stream. When empty, defaults to the CPA_BASE_URL hostname plus port 8317; set host:port explicitly when exposed through nginx stream on another port.
+REDIS_QUEUE_ADDR=
+
+# 每次 Redis LPOP 最多拉取的队列记录数。redis/auto 模式会持续 drain，非空批次会立即继续拉取。必填：否。默认值：1000。
+# Maximum queue records per Redis LPOP. redis/auto modes continuously drain and immediately continue after a non-empty batch. Required: no. Default: 1000.
+REDIS_QUEUE_BATCH_SIZE=1000
+
+# Redis 队列为空时的 idle 检查间隔。必填：否。默认值：1s。
+# Idle check interval when the Redis queue is empty. Required: no. Default: 1s.
+REDIS_QUEUE_IDLE_INTERVAL=1s
+
+# 请求 CPA 接口时的超时时间。必填：否。默认值：30s。
+# Timeout for requests to the CPA service. Required: no. Default: 30s.
+REQUEST_TIMEOUT=30s
+
+# 应用工作目录，SQLite 数据库、日志和备份默认都写入这里。Docker 中默认工作目录为 /，因此 ./data 对应 /data；二进制通过 --env 或同目录 .env 加载时，./data 对应 env 文件同目录的 data 子目录。必填：否。默认值：./data。
+# Application work directory. SQLite database, logs, and backups are stored here by default. In Docker the runtime working directory is /, so ./data maps to /data; for binaries loaded with --env or package-local .env, ./data maps to a data directory next to the env file. Required: no. Default: ./data.
+WORK_DIR=./data
+
+# 应用日志级别。必填：否。默认值：info。
+# Application log level. Required: no. Default: info.
+LOG_LEVEL=info
+
+# 是否写入持久化日志文件。必填：否。默认值：true。
+# Whether to write persistent log files. Required: no. Default: true.
+LOG_FILE_ENABLED=true
+
+# 日志文件保留天数；0 表示不自动清理。必填：否。默认值：7。
+# Number of days to retain log files; 0 disables cleanup. Required: no. Default: 7.
+LOG_RETENTION_DAYS=7
+
+# 是否启用 SQLite 数据库备份。必填：否。默认值：true。
+# Whether to enable SQLite database backups. Required: no. Default: true.
+BACKUP_ENABLED=true
+
+# 数据库备份间隔。必填：否。默认值：24h。
+# Database backup interval. Required: no. Default: 24h.
+BACKUP_INTERVAL=24h
+
+# 备份文件保留天数。必填：否。默认值：7。
+# Number of days to retain backup files. Required: no. Default: 7.
+BACKUP_RETENTION_DAYS=7

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+web/src/assets/cli-proxy-api-favicon.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/binary-dev-release.yml

@@ -0,0 +1,304 @@
+name: Publish dev binaries
+
+on:
+  workflow_dispatch:
+    inputs:
+      specific_name:
+        description: 'Optional binary package name suffix; defaults to the current branch name, for example pr-123 or feature-login-test'
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  resolve-dev-name:
+    runs-on: ubuntu-24.04
+    outputs:
+      specific_name: ${{ steps.dev_name.outputs.specific_name }}
+    steps:
+      - name: Validate branch ref
+        if: ${{ !startsWith(github.ref, 'refs/heads/') || github.ref_name == 'main' }}
+        run: |
+          echo "Manual dev binary publishing must be run from a non-main branch." >&2
+          echo "Current ref: $GITHUB_REF" >&2
+          exit 1
+
+      - name: Resolve specific binary package name
+        id: dev_name
+        env:
+          INPUT_NAME: ${{ inputs.specific_name }}
+        run: |
+          raw_name="${INPUT_NAME:-$GITHUB_REF_NAME}"
+          specific_name=$(printf '%s' "$raw_name" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9._-]+/-/g; s/^[^a-z0-9]+//; s/[._-]+$//' | cut -c1-96)
+
+          if [[ -z "$INPUT_NAME" ]]; then
+            case "$specific_name" in
+              dev|latest|sha-*)
+                specific_name=$(printf '%s-%s' "$specific_name" "${GITHUB_SHA::7}" | cut -c1-96)
+                ;;
+            esac
+          fi
+
+          if [[ ! "$specific_name" =~ ^[a-z0-9][a-z0-9._-]{0,95}$ ]]; then
+            echo "Unable to generate a valid binary package name from: $raw_name" >&2
+            exit 1
+          fi
+
+          case "$specific_name" in
+            dev|latest|sha-*)
+              echo "Invalid binary package name: $specific_name is reserved." >&2
+              exit 1
+              ;;
+          esac
+
+          echo "specific_name=$specific_name" >> "$GITHUB_OUTPUT"
+          echo "Using specific binary package name: $specific_name"
+
+  binary-dev-linux:
+    runs-on: ubuntu-24.04
+    needs: resolve-dev-name
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            cc: gcc
+            asset_arch: amd64
+          - goos: linux
+            goarch: arm64
+            cc: aarch64-linux-gnu-gcc
+            asset_arch: arm64
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: stable
+          check-latest: true
+          cache: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install build dependencies
+        run: sudo apt-get update && sudo apt-get install -y build-essential gcc-aarch64-linux-gnu
+
+      - name: Install frontend dependencies
+        run: npm --prefix ./web ci
+
+      - name: Build frontend
+        run: npm --prefix ./web run build
+
+      - name: Build binary package
+        env:
+          PACKAGE_SUFFIX: ${{ needs.resolve-dev-name.outputs.specific_name }}
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CC: ${{ matrix.cc }}
+          ASSET_ARCH: ${{ matrix.asset_arch }}
+        run: |
+          set -euo pipefail
+          package_name="cpa-usage-keeper_dev_${PACKAGE_SUFFIX}_${GITHUB_SHA::7}_${GOOS}_${ASSET_ARCH}"
+          package_dir="dist/${package_name}"
+          mkdir -p "${package_dir}/data"
+
+          CGO_ENABLED=1 GOOS="${GOOS}" GOARCH="${GOARCH}" CC="${CC}" \
+            go build -trimpath -ldflags="-s -w" -o "${package_dir}/cpa-usage-keeper" ./cmd/server/main.go
+          cp .env.example README.md README.en.md LICENSE CONTRIBUTORS.md "${package_dir}/"
+          tar -czf "dist/${package_name}.tar.gz" -C dist "${package_name}"
+
+      - name: Upload binary package artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: cpa-usage-keeper-dev-${{ needs.resolve-dev-name.outputs.specific_name }}-${{ matrix.goos }}-${{ matrix.asset_arch }}
+          path: dist/cpa-usage-keeper_dev_${{ needs.resolve-dev-name.outputs.specific_name }}_*_${{ matrix.goos }}_${{ matrix.asset_arch }}.tar.gz
+          if-no-files-found: error
+
+  binary-dev-darwin:
+    runs-on: ${{ matrix.runs_on }}
+    needs: resolve-dev-name
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: darwin
+            goarch: amd64
+            asset_arch: amd64
+            runs_on: macos-15-intel
+          - goos: darwin
+            goarch: arm64
+            asset_arch: arm64
+            runs_on: macos-15
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: stable
+          check-latest: true
+          cache: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install frontend dependencies
+        run: npm --prefix ./web ci
+
+      - name: Build frontend
+        run: npm --prefix ./web run build
+
+      - name: Build binary package
+        env:
+          PACKAGE_SUFFIX: ${{ needs.resolve-dev-name.outputs.specific_name }}
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          ASSET_ARCH: ${{ matrix.asset_arch }}
+        run: |
+          set -euo pipefail
+          package_name="cpa-usage-keeper_dev_${PACKAGE_SUFFIX}_${GITHUB_SHA::7}_${GOOS}_${ASSET_ARCH}"
+          package_dir="dist/${package_name}"
+          mkdir -p "${package_dir}/data"
+
+          CGO_ENABLED=1 GOOS="${GOOS}" GOARCH="${GOARCH}" \
+            go build -trimpath -ldflags="-s -w" -o "${package_dir}/cpa-usage-keeper" ./cmd/server/main.go
+          cp .env.example README.md README.en.md LICENSE CONTRIBUTORS.md "${package_dir}/"
+          tar -czf "dist/${package_name}.tar.gz" -C dist "${package_name}"
+
+      - name: Upload binary package artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: cpa-usage-keeper-dev-${{ needs.resolve-dev-name.outputs.specific_name }}-${{ matrix.goos }}-${{ matrix.asset_arch }}
+          path: dist/cpa-usage-keeper_dev_${{ needs.resolve-dev-name.outputs.specific_name }}_*_${{ matrix.goos }}_${{ matrix.asset_arch }}.tar.gz
+          if-no-files-found: error
+
+  binary-dev-windows:
+    runs-on: ${{ matrix.runs_on }}
+    needs: resolve-dev-name
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goarch: amd64
+            asset_arch: amd64
+            runs_on: windows-2025
+            msystem: UCRT64
+            install: mingw-w64-ucrt-x86_64-gcc
+            cc: gcc
+          - goarch: arm64
+            asset_arch: arm64
+            runs_on: windows-11-arm
+            msystem: CLANGARM64
+            install: mingw-w64-clang-aarch64-gcc
+            cc: gcc
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: stable
+          check-latest: true
+          cache: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Set up MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: ${{ matrix.msystem }}
+          update: true
+          path-type: inherit
+          install: ${{ matrix.install }}
+
+      - name: Install frontend dependencies
+        shell: bash
+        run: npm --prefix ./web ci
+
+      - name: Build frontend
+        shell: bash
+        run: npm --prefix ./web run build
+
+      - name: Build binary package
+        shell: msys2 {0}
+        env:
+          PACKAGE_SUFFIX: ${{ needs.resolve-dev-name.outputs.specific_name }}
+          GOOS: windows
+          GOARCH: ${{ matrix.goarch }}
+          ASSET_ARCH: ${{ matrix.asset_arch }}
+          CC: ${{ matrix.cc }}
+        run: |
+          set -euo pipefail
+          package_name="cpa-usage-keeper_dev_${PACKAGE_SUFFIX}_${GITHUB_SHA::7}_${GOOS}_${ASSET_ARCH}"
+          package_dir="dist/${package_name}"
+          mkdir -p "${package_dir}/data"
+
+          CGO_ENABLED=1 GOOS="${GOOS}" GOARCH="${GOARCH}" CC="${CC}" \
+            go build -trimpath -ldflags="-s -w" -o "${package_dir}/cpa-usage-keeper.exe" ./cmd/server/main.go
+          cp .env.example README.md README.en.md LICENSE CONTRIBUTORS.md "${package_dir}/"
+
+      - name: Archive binary package
+        shell: pwsh
+        env:
+          PACKAGE_SUFFIX: ${{ needs.resolve-dev-name.outputs.specific_name }}
+          ASSET_ARCH: ${{ matrix.asset_arch }}
+        run: |
+          $shortSha = "${env:GITHUB_SHA}".Substring(0, 7)
+          $packageName = "cpa-usage-keeper_dev_${env:PACKAGE_SUFFIX}_${shortSha}_windows_${env:ASSET_ARCH}"
+          Compress-Archive -Path "dist/$packageName" -DestinationPath "dist/$packageName.zip"
+
+      - name: Upload binary package artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: cpa-usage-keeper-dev-${{ needs.resolve-dev-name.outputs.specific_name }}-windows-${{ matrix.asset_arch }}
+          path: dist/cpa-usage-keeper_dev_${{ needs.resolve-dev-name.outputs.specific_name }}_*_windows_${{ matrix.asset_arch }}.zip
+          if-no-files-found: error
+
+  publish-dev-artifacts:
+    runs-on: ubuntu-24.04
+    needs:
+      - resolve-dev-name
+      - binary-dev-linux
+      - binary-dev-darwin
+      - binary-dev-windows
+    steps:
+      - name: Download binary package artifacts
+        uses: actions/download-artifact@v6
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Generate checksums
+        run: |
+          set -euo pipefail
+          cd dist
+          sha256sum *.tar.gz *.zip > checksums.txt
+
+      - name: Upload dev binary packages
+        uses: actions/upload-artifact@v6
+        with:
+          name: cpa-usage-keeper-dev-binaries-${{ github.run_id }}
+          path: |
+            dist/*.tar.gz
+            dist/*.zip
+            dist/checksums.txt
+          if-no-files-found: error

.github/workflows/binary-release.yml

@@ -0,0 +1,251 @@
+name: Publish release binaries
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  binary-release-linux:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            cc: gcc
+            asset_arch: amd64
+          - goos: linux
+            goarch: arm64
+            cc: aarch64-linux-gnu-gcc
+            asset_arch: arm64
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: stable
+          check-latest: true
+          cache: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install build dependencies
+        run: sudo apt-get update && sudo apt-get install -y build-essential gcc-aarch64-linux-gnu
+
+      - name: Install frontend dependencies
+        run: npm --prefix ./web ci
+
+      - name: Build frontend
+        run: npm --prefix ./web run build
+
+      - name: Build binary package
+        env:
+          VERSION: ${{ github.ref_name }}
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CC: ${{ matrix.cc }}
+          ASSET_ARCH: ${{ matrix.asset_arch }}
+        run: |
+          set -euo pipefail
+          package_name="cpa-usage-keeper_${VERSION}_${GOOS}_${ASSET_ARCH}"
+          package_dir="dist/${package_name}"
+          mkdir -p "${package_dir}/data"
+
+          CGO_ENABLED=1 GOOS="${GOOS}" GOARCH="${GOARCH}" CC="${CC}" \
+            go build -trimpath -ldflags="-s -w" -o "${package_dir}/cpa-usage-keeper" ./cmd/server/main.go
+          cp .env.example README.md README.en.md LICENSE CONTRIBUTORS.md "${package_dir}/"
+          tar -czf "dist/${package_name}.tar.gz" -C dist "${package_name}"
+
+      - name: Upload binary package artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: cpa-usage-keeper-${{ github.ref_name }}-${{ matrix.goos }}-${{ matrix.asset_arch }}
+          path: dist/cpa-usage-keeper_${{ github.ref_name }}_${{ matrix.goos }}_${{ matrix.asset_arch }}.tar.gz
+          if-no-files-found: error
+
+  binary-release-darwin:
+    runs-on: ${{ matrix.runs_on }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: darwin
+            goarch: amd64
+            asset_arch: amd64
+            runs_on: macos-15-intel
+          - goos: darwin
+            goarch: arm64
+            asset_arch: arm64
+            runs_on: macos-15
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: stable
+          check-latest: true
+          cache: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install frontend dependencies
+        run: npm --prefix ./web ci
+
+      - name: Build frontend
+        run: npm --prefix ./web run build
+
+      - name: Build binary package
+        env:
+          VERSION: ${{ github.ref_name }}
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          ASSET_ARCH: ${{ matrix.asset_arch }}
+        run: |
+          set -euo pipefail
+          package_name="cpa-usage-keeper_${VERSION}_${GOOS}_${ASSET_ARCH}"
+          package_dir="dist/${package_name}"
+          mkdir -p "${package_dir}/data"
+
+          CGO_ENABLED=1 GOOS="${GOOS}" GOARCH="${GOARCH}" \
+            go build -trimpath -ldflags="-s -w" -o "${package_dir}/cpa-usage-keeper" ./cmd/server/main.go
+          cp .env.example README.md README.en.md LICENSE CONTRIBUTORS.md "${package_dir}/"
+          tar -czf "dist/${package_name}.tar.gz" -C dist "${package_name}"
+
+      - name: Upload binary package artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: cpa-usage-keeper-${{ github.ref_name }}-${{ matrix.goos }}-${{ matrix.asset_arch }}
+          path: dist/cpa-usage-keeper_${{ github.ref_name }}_${{ matrix.goos }}_${{ matrix.asset_arch }}.tar.gz
+          if-no-files-found: error
+
+  binary-release-windows:
+    runs-on: ${{ matrix.runs_on }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goarch: amd64
+            asset_arch: amd64
+            runs_on: windows-2025
+            msystem: UCRT64
+            install: mingw-w64-ucrt-x86_64-gcc
+            cc: gcc
+          - goarch: arm64
+            asset_arch: arm64
+            runs_on: windows-11-arm
+            msystem: CLANGARM64
+            install: mingw-w64-clang-aarch64-gcc
+            cc: gcc
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: stable
+          check-latest: true
+          cache: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Set up MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: ${{ matrix.msystem }}
+          update: true
+          path-type: inherit
+          install: ${{ matrix.install }}
+
+      - name: Install frontend dependencies
+        shell: bash
+        run: npm --prefix ./web ci
+
+      - name: Build frontend
+        shell: bash
+        run: npm --prefix ./web run build
+
+      - name: Build binary package
+        shell: msys2 {0}
+        env:
+          VERSION: ${{ github.ref_name }}
+          GOOS: windows
+          GOARCH: ${{ matrix.goarch }}
+          ASSET_ARCH: ${{ matrix.asset_arch }}
+          CC: ${{ matrix.cc }}
+        run: |
+          set -euo pipefail
+          package_name="cpa-usage-keeper_${VERSION}_${GOOS}_${ASSET_ARCH}"
+          package_dir="dist/${package_name}"
+          mkdir -p "${package_dir}/data"
+
+          CGO_ENABLED=1 GOOS="${GOOS}" GOARCH="${GOARCH}" CC="${CC}" \
+            go build -trimpath -ldflags="-s -w" -o "${package_dir}/cpa-usage-keeper.exe" ./cmd/server/main.go
+          cp .env.example README.md README.en.md LICENSE CONTRIBUTORS.md "${package_dir}/"
+
+      - name: Archive binary package
+        shell: pwsh
+        env:
+          VERSION: ${{ github.ref_name }}
+          ASSET_ARCH: ${{ matrix.asset_arch }}
+        run: |
+          $packageName = "cpa-usage-keeper_${env:VERSION}_windows_${env:ASSET_ARCH}"
+          Compress-Archive -Path "dist/$packageName" -DestinationPath "dist/$packageName.zip"
+
+      - name: Upload binary package artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: cpa-usage-keeper-${{ github.ref_name }}-windows-${{ matrix.asset_arch }}
+          path: dist/cpa-usage-keeper_${{ github.ref_name }}_windows_${{ matrix.asset_arch }}.zip
+          if-no-files-found: error
+
+  publish-release:
+    runs-on: ubuntu-24.04
+    needs:
+      - binary-release-linux
+      - binary-release-darwin
+      - binary-release-windows
+    steps:
+      - name: Download binary package artifacts
+        uses: actions/download-artifact@v6
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Generate checksums
+        run: |
+          set -euo pipefail
+          cd dist
+          sha256sum *.tar.gz *.zip > checksums.txt
+
+      - name: Upload release assets
+        uses: softprops/action-gh-release@v3
+        with:
+          files: |
+            dist/*.tar.gz
+            dist/*.zip
+            dist/checksums.txt

.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  backend:
+    runs-on: ${{ matrix.runs-on }}
+    strategy:
+      fail-fast: false
+      matrix:
+        runs-on:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.22'
+          cache: true
+
+      - name: Set up MSYS2
+        if: ${{ runner.os == 'Windows' }}
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: UCRT64
+          update: true
+          path-type: inherit
+          install: mingw-w64-ucrt-x86_64-gcc
+
+      - name: Run backend tests
+        if: ${{ runner.os != 'Windows' }}
+        run: go test ./cmd/... ./internal/...
+
+      - name: Run backend tests
+        if: ${{ runner.os == 'Windows' }}
+        shell: msys2 {0}
+        run: go test ./cmd/... ./internal/...
+
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install frontend dependencies
+        run: npm --prefix ./web ci
+
+      - name: Run frontend tests
+        run: npm --prefix ./web run test
+
+      - name: Run frontend lint
+        run: npm --prefix ./web run lint
+
+      - name: Run frontend typecheck
+        run: npm --prefix ./web run typecheck
+
+      - name: Build frontend
+        run: npm --prefix ./web run build

.github/workflows/docker-dev-publish.yml

@@ -0,0 +1,91 @@
+name: Publish dev Docker image
+
+on:
+  workflow_dispatch:
+    inputs:
+      specific_tag:
+        description: 'Optional Docker tag to publish; defaults to the current branch name, for example pr-123 or feature-login-test'
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  docker-dev:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate branch ref
+        if: ${{ !startsWith(github.ref, 'refs/heads/') || github.ref_name == 'main' }}
+        run: |
+          echo "Manual dev Docker publishing must be run from a non-main branch." >&2
+          echo "Current ref: $GITHUB_REF" >&2
+          exit 1
+
+      - name: Resolve specific Docker tag
+        id: dev_tag
+        env:
+          INPUT_TAG: ${{ inputs.specific_tag }}
+        run: |
+          raw_tag="${INPUT_TAG:-$GITHUB_REF_NAME}"
+          specific_tag=$(printf '%s' "$raw_tag" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9._-]+/-/g; s/^[^a-z0-9]+//; s/[._-]+$//' | cut -c1-128)
+
+          if [[ -z "$INPUT_TAG" ]]; then
+            case "$specific_tag" in
+              dev|latest|sha-*)
+                specific_tag=$(printf '%s-%s' "$specific_tag" "${GITHUB_SHA::7}" | cut -c1-128)
+                ;;
+            esac
+          fi
+
+          if [[ ! "$specific_tag" =~ ^[a-z0-9][a-z0-9._-]{0,127}$ ]]; then
+            echo "Unable to generate a valid Docker tag from: $raw_tag" >&2
+            exit 1
+          fi
+
+          case "$specific_tag" in
+            dev|latest|sha-*)
+              echo "Invalid Docker tag: $specific_tag is reserved." >&2
+              exit 1
+              ;;
+          esac
+
+          echo "specific_tag=$specific_tag" >> "$GITHUB_OUTPUT"
+          echo "Using specific Docker tag: $specific_tag"
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Convert image name to lowercase
+        id: repo
+        run: echo "image=ghcr.io/${GITHUB_REPOSITORY@L}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ steps.repo.outputs.image }}
+          tags: |
+            type=raw,value=dev
+            type=raw,value=${{ steps.dev_tag.outputs.specific_tag }}
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/docker-publish.yml

@@ -0,0 +1,54 @@
+name: Publish release Docker image
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Convert image name to lowercase
+        id: repo
+        run: echo "image=ghcr.io/${GITHUB_REPOSITORY@L}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ steps.repo.outputs.image }}
+          tags: |
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=sha,prefix=sha-
+            type=ref,event=tag,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=semver,pattern={{version}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=semver,pattern={{major}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -0,0 +1,46 @@
+# internal docs
+.dev-docs/
+.claude/
+.worktrees/
+
+# local environment files
+.env
+.env.*
+!.env.example
+!deploy/.env.example
+
+# runtime data
+/data/
+/test/
+*.db
+*.db-*
+.tmp-test.db
+backups/
+.runtime-test/
+
+# frontend dependencies and build output
+web/node_modules/
+web/dist/
+web/dist-ssr/
+
+# logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# local overrides
+*.local
+
+# editor and OS files
+.DS_Store
+.vscode/
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

CONTRIBUTORS.md

@@ -0,0 +1,7 @@
+# Contributors
+
+This project is made possible by the work and ideas of the people below.
+
+## Acknowledgements
+
+- [luispater](https://github.com/luispater) — Author of CPA, the upstream project that this usage keeper integrates with.

Dockerfile

@@ -1,16 +1,36 @@
-FROM ghcr.io/willxup/cpa-usage-keeper:latest
+# syntax=docker/dockerfile:1
 
-ENV APP_PORT=8080 \
-    CPA_BASE_URL=https://pjpjq-daili.hf.space \
-    REDIS_QUEUE_ADDR=127.0.0.1:9 \
-    AUTH_ENABLED=true \
-    TZ=Asia/Shanghai \
-    WORK_DIR=/data \
-    LOG_FILE_ENABLED=true \
-    BACKUP_ENABLED=true
+FROM node:22-alpine AS web-builder
+WORKDIR /app/web
+COPY web/package.json web/package-lock.json ./
+RUN npm ci
+COPY web/ ./
+RUN npm run build
 
-COPY entrypoint.space.sh /usr/local/bin/entrypoint.space.sh
-RUN chmod +x /usr/local/bin/entrypoint.space.sh
+FROM golang:1.22-alpine AS go-builder
+WORKDIR /app
+RUN apk add --no-cache build-base
+COPY go.mod go.sum ./
+RUN go mod download
+COPY cmd/ ./cmd/
+COPY internal/ ./internal/
+COPY --from=web-builder /app/web/dist ./web/dist
+COPY web/static.go ./web/static.go
+RUN CGO_ENABLED=1 GOOS=linux go build -o /out/cpa-usage-keeper ./cmd/server/main.go
 
-ENTRYPOINT ["/usr/local/bin/entrypoint.space.sh"]
+FROM alpine:3.20
+WORKDIR /
+RUN apk add --no-cache ca-certificates tzdata su-exec \
+	&& addgroup -S app \
+	&& adduser -S -G app app \
+	&& mkdir -p /data \
+	&& chown -R app:app /data
+COPY --from=go-builder /out/cpa-usage-keeper /app/cpa-usage-keeper
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN sed -i 's/\r$//' /usr/local/bin/docker-entrypoint.sh \
+	&& chmod +x /usr/local/bin/docker-entrypoint.sh
+VOLUME ["/data"]
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 CMD wget -q --spider "http://127.0.0.1:${APP_PORT:-8080}${APP_BASE_PATH:-}/healthz" || exit 1
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
 CMD ["/app/cpa-usage-keeper"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will
+
+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,16 @@
+.PHONY: verify verify-backend verify-frontend verify-docker
+
+verify: verify-backend verify-frontend
+
+verify-backend:
+	go test ./cmd/... ./internal/...
+
+verify-frontend:
+	npm --prefix ./web ci
+	npm --prefix ./web run test
+	npm --prefix ./web run lint
+	npm --prefix ./web run typecheck
+	npm --prefix ./web run build
+
+verify-docker:
+	docker build -t cpa-usage-keeper:ci .

README.en.md

@@ -0,0 +1,223 @@
+# CPA Usage Keeper
+
+[中文说明](./README.md)
+
+CPA Usage Keeper is a standalone CPA usage persistence and dashboard service.
+
+It relies on [CLIProxyAPI (CPA)](https://github.com/router-for-me/CLIProxyAPI) as the backend CPA data source and adds persistent storage and statistical analysis capabilities on top of CPA. The service consumes events from the CPA Redis usage queue into SQLite, periodically pulls CPA metadata, exposes aggregation APIs, and serves a built-in web dashboard for usage, pricing, request health, and model/API statistics.
+
+![cpa-usage-keeper-screenshot](https://images.bitskyline.com/i/2026/05/1pmg6l.png)
+
+## Features
+
+- CPA usage persistence in SQLite
+- Aggregated usage and pricing APIs
+- Built-in React dashboard
+- Optional password login protection
+- Local SQLite database backups with retention
+- Docker / Docker Compose deployment
+
+## Project Structure
+
+```text
+cmd/                 Application entrypoint
+internal/api/        HTTP routes and handlers
+internal/app/        App wiring and startup
+internal/auth/       In-memory session auth
+internal/backup/     SQLite database backup management
+internal/config/     Environment config loading
+internal/cpa/        CPA client and types
+internal/models/     GORM models
+internal/poller/     Background sync loop
+internal/repository/ SQLite access and aggregations
+internal/service/    Sync, usage, and pricing services
+web/                 React + TypeScript frontend
+```
+
+## Configuration
+
+Copy the example config:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `CPA_BASE_URL` | Yes | - | CPA server URL |
+| `CPA_MANAGEMENT_KEY` | Yes | - | CPA management key |
+| `AUTH_ENABLED` | No | `false` | Enable login protection |
+| `LOGIN_PASSWORD` | When auth is enabled | - | Login password |
+| `AUTH_SESSION_TTL` | No | `168h` | Session lifetime |
+| `APP_PORT` | No | `8080` | HTTP listen port |
+| `APP_BASE_PATH` | No | root path | Subpath prefix such as `/cpa`; empty means `/` |
+| `TZ` | No | `Asia/Shanghai` | Project business timezone; affects Today, daily aggregation, scheduled tasks, and log timestamps |
+| `REDIS_QUEUE_ADDR` | No | `CPA_BASE_URL` hostname + `8317` | CPA Redis/RESP TCP address; set `host:port` for non-default ports |
+| `REDIS_QUEUE_BATCH_SIZE` | No | `1000` | Maximum queue records per pull |
+| `REDIS_QUEUE_IDLE_INTERVAL` | No | `1s` | Empty queue check interval |
+| `REQUEST_TIMEOUT` | No | `30s` | CPA request timeout |
+| `WORK_DIR` | No | `./data` | Application work directory; database, logs, and backups default to `app.db`, `logs/`, and `backups/` under it |
+| `LOG_LEVEL` | No | `info` | Log level |
+| `LOG_FILE_ENABLED` | No | `true` | Write persistent log files |
+| `LOG_RETENTION_DAYS` | No | `7` | Log retention days; `0` disables cleanup |
+| `BACKUP_ENABLED` | No | `true` | Enable SQLite database backups |
+| `BACKUP_INTERVAL` | No | `24h` | Database backup interval |
+| `BACKUP_RETENTION_DAYS` | No | `7` | Backup retention days |
+
+`APP_BASE_PATH` must be empty or start with `/`; for example `/cpa`. `/cpa/` is normalized to `/cpa`.
+
+Security and data notes:
+
+- SQLite database backups store original data from the application database, and backup files are not encrypted.
+- Browser-facing APIs redact key-like source/lookup fields or map them to stable public identifiers, but raw database values are unchanged.
+- For public deployments, enable `AUTH_ENABLED=true` and terminate HTTPS at your reverse proxy.
+- Login sessions are stored in process memory and become invalid after restart.
+- Redis inbox raw messages are cleaned up automatically: successful rows are kept until the end of the current day, and failed rows are kept for 7 days.
+
+## Development
+
+### Prerequisites
+
+- Go 1.22+
+- Node.js 22+
+- npm
+- A running [CLIProxyAPI (CPA)](https://github.com/router-for-me/CLIProxyAPI) instance
+
+### Run locally
+
+1. Create your local config:
+
+```bash
+cp .env.example .env
+```
+
+2. Start the backend:
+
+```bash
+go run ./cmd/server/main.go
+```
+
+3. In another terminal, install frontend dependencies and start the dev server:
+
+```bash
+npm --prefix ./web ci
+npm --prefix ./web run dev -- --host 127.0.0.1
+```
+
+4. Build the frontend for production:
+
+```bash
+npm --prefix ./web run build
+```
+
+### Tests
+
+Run the full local verification baseline:
+
+```bash
+make verify
+```
+
+Or run checks individually:
+
+```bash
+go test ./cmd/... ./internal/...
+npm --prefix ./web run test
+npm --prefix ./web run lint
+npm --prefix ./web run typecheck
+npm --prefix ./web run build
+```
+
+## Docker
+
+If CPA is already running on the host:
+
+```bash
+# TZ sets the container timezone; log timestamps are displayed in this timezone.
+docker run -d \
+  --name cpa-usage-keeper \
+  --add-host=host.docker.internal:host-gateway \
+  -p 8080:8080 \
+  -v "$(pwd)/keeper/data:/data" \
+  -e TZ=Asia/Shanghai \
+  -e CPA_BASE_URL=http://host.docker.internal:8317 \
+  -e CPA_MANAGEMENT_KEY=replace-with-your-management-key \
+  -e REDIS_QUEUE_ADDR=host.docker.internal:8317 \
+  -e AUTH_ENABLED=true \
+  -e LOGIN_PASSWORD=replace-with-your-login-password \
+  ghcr.io/willxup/cpa-usage-keeper:latest
+```
+
+`/data` stores the SQLite database, backups, and log files. Mount it to persistent storage.
+
+## Docker Compose
+
+The repository includes a minimal `docker-compose.yaml` example for running CPA and CPA Usage Keeper together:
+
+```yaml
+services:
+  cli-proxy-api:
+    image: eceasy/cli-proxy-api:latest
+    container_name: cli-proxy-api
+    restart: unless-stopped
+    ports:
+      - "8317:8317"
+      - "1455:1455"
+    volumes:
+      - ./cpa/config.yaml:/CLIProxyAPI/config.yaml
+      - ./cpa/auths:/root/.cli-proxy-api
+      - ./cpa/logs:/CLIProxyAPI/logs
+    networks:
+      - cpa-network
+
+  cpa-usage-keeper:
+    image: ghcr.io/willxup/cpa-usage-keeper:latest
+    container_name: cpa-usage-keeper
+    restart: unless-stopped
+    depends_on:
+      - cli-proxy-api
+    ports:
+      - "8080:8080"
+    environment:
+      TZ: Asia/Shanghai # Sets the container timezone; log timestamps use this timezone.
+      CPA_BASE_URL: http://cli-proxy-api:8317
+      CPA_MANAGEMENT_KEY: replace-with-your-management-key
+      REDIS_QUEUE_ADDR: cli-proxy-api:8317
+      AUTH_ENABLED: true
+      LOGIN_PASSWORD: replace-with-your-login-password
+    volumes:
+      - ./keeper:/data
+    networks:
+      - cpa-network
+
+networks:
+  cpa-network:
+    driver: bridge
+```
+
+Start:
+
+```bash
+docker compose up -d
+```
+
+Stop:
+
+```bash
+docker compose down
+```
+
+CPA files are stored under `./cpa`, and CPA Usage Keeper data is stored under `./keeper`.
+
+## Subpath reverse proxy
+
+When serving under `/cpa`, set `APP_BASE_PATH=/cpa` and keep the prefix in your reverse proxy:
+
+```nginx
+location /cpa/ {
+    proxy_pass http://127.0.0.1:8080;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```

README.md

@@ -8,25 +8,230 @@ app_port: 8080
 pinned: false
 ---
 
-# Daili Usage Keeper
+# CPA Usage Keeper
 
-A standalone [CPA Usage Keeper](https://github.com/Willxup/cpa-usage-keeper) Space for `pjpjq/daili`.
+[English README](./README.en.md)
 
-This Space intentionally runs separately from the main CPA Space so the proxy path is not coupled to usage visualization.
+`CPA Usage Keeper` 是一个独立的 CPA 用量持久化与可视化服务。
 
-Required secret before it starts the real dashboard:
+它依赖 [CLIProxyAPI（CPA）](https://github.com/router-for-me/CLIProxyAPI) 作为后端 CPA 数据来源，目标是在 CPA 之上补充持久化存储与统计分析能力。服务会从 CPA Redis usage 队列消费事件并写入 SQLite，定时拉取 CPA metadata，暴露聚合 API，并提供内置 Web Dashboard 用于查看 usage、pricing、request health 和 model/API 维度的统计信息。
 
-- `CPA_MANAGEMENT_KEY`: management key for `https://pjpjq-daili.hf.space`
+![cpa-usage-keeper-screenshot](https://images.bitskyline.com/i/2026/05/1pmg6l.png)
 
-Default variables:
+## 功能特性
 
-- `CPA_BASE_URL=https://pjpjq-daili.hf.space`
-- `REDIS_QUEUE_ADDR=127.0.0.1:9` to force fast HTTP fallback to CPA `/v0/management/usage-queue`, because Hugging Face Spaces cannot reach the raw CPA TCP/RESP port across Spaces.
-- `AUTH_ENABLED=true`; set `LOGIN_PASSWORD` as a Space secret. The Space can be public while the dashboard remains password protected.
+- CPA usage 数据持久化到 SQLite
+- usage 聚合 API 与 pricing API
+- 内置 React Dashboard
+- 可选密码登录保护
+- SQLite 数据库本地备份与保留策略
+- Docker / Docker Compose 部署
 
-Persistent history requires Hugging Face persistent storage or another backup strategy for `/data`.
+## 项目结构
 
-Runtime secrets configured on Hugging Face:
+```text
+cmd/                 应用入口
+internal/api/        HTTP 路由与处理器
+internal/app/        应用装配与启动
+internal/auth/       内存 session 鉴权
+internal/backup/     SQLite 数据库备份管理
+internal/config/     环境配置加载
+internal/cpa/        CPA 客户端与类型定义
+internal/models/     GORM 模型
+internal/poller/     后台同步轮询
+internal/repository/ SQLite 访问与聚合逻辑
+internal/service/    同步、usage 与 pricing 服务
+web/                 React + TypeScript 前端
+```
 
-- `CPA_MANAGEMENT_KEY`
-- `LOGIN_PASSWORD`
+## 配置
+
+复制配置模板：
+
+```bash
+cp .env.example .env
+```
+
+| 变量 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `CPA_BASE_URL` | 是 | - | CPA 服务地址 |
+| `CPA_MANAGEMENT_KEY` | 是 | - | CPA management key |
+| `AUTH_ENABLED` | 否 | `false` | 是否启用登录保护 |
+| `LOGIN_PASSWORD` | 鉴权启用时必填 | - | 登录密码 |
+| `AUTH_SESSION_TTL` | 否 | `168h` | Session 生命周期 |
+| `APP_PORT` | 否 | `8080` | HTTP 监听端口 |
+| `APP_BASE_PATH` | 否 | 根路径 | 子路径部署前缀，例如 `/cpa`；留空表示 `/` |
+| `TZ` | 否 | `Asia/Shanghai` | 项目业务时区，影响 Today、按天聚合、定时任务和日志时间 |
+| `REDIS_QUEUE_ADDR` | 否 | `CPA_BASE_URL` 主机名 + `8317` | CPA Redis/RESP TCP 地址；非默认端口时填写 `host:port` |
+| `REDIS_QUEUE_BATCH_SIZE` | 否 | `1000` | 每次最多拉取的队列记录数 |
+| `REDIS_QUEUE_IDLE_INTERVAL` | 否 | `1s` | 队列为空时的检查间隔 |
+| `REQUEST_TIMEOUT` | 否 | `30s` | CPA 请求超时 |
+| `WORK_DIR` | 否 | `./data` | 应用工作目录；数据库、日志和备份默认分别写入 `app.db`、`logs/`、`backups/` |
+| `LOG_LEVEL` | 否 | `info` | 日志级别 |
+| `LOG_FILE_ENABLED` | 否 | `true` | 是否写入持久化日志文件 |
+| `LOG_RETENTION_DAYS` | 否 | `7` | 日志保留天数；`0` 表示不自动清理 |
+| `BACKUP_ENABLED` | 否 | `true` | 是否启用 SQLite 数据库备份 |
+| `BACKUP_INTERVAL` | 否 | `24h` | 数据库备份间隔 |
+| `BACKUP_RETENTION_DAYS` | 否 | `7` | 备份保留天数 |
+
+`APP_BASE_PATH` 必须为空或以 `/` 开头；例如 `/cpa`，`/cpa/` 会规范为 `/cpa`。
+
+安全与数据说明：
+
+- SQLite 数据库备份会保存应用数据库中的原始数据，备份文件不做加密。
+- 面向浏览器的 API 会对 key-like source/lookup 字段做脱敏或稳定公开标识映射，但不会修改数据库原始值。
+- 公开部署建议开启 `AUTH_ENABLED=true`，并在反向代理层配置 HTTPS。
+- 登录 session 存在服务进程内存中，服务重启后已登录 session 会失效。
+- Redis inbox 原始消息会自动清理：成功数据保留到当天结束后清理，失败数据保留 7 天。
+
+## 本地开发
+
+### 前置依赖
+
+- Go 1.22+
+- Node.js 22+
+- npm
+- 已运行的 [CLIProxyAPI（CPA）](https://github.com/router-for-me/CLIProxyAPI)
+
+### 本地启动
+
+1. 复制本地配置：
+
+```bash
+cp .env.example .env
+```
+
+2. 启动后端：
+
+```bash
+go run ./cmd/server/main.go
+```
+
+3. 在另一个终端安装前端依赖并启动开发服务器：
+
+```bash
+npm --prefix ./web ci
+npm --prefix ./web run dev -- --host 127.0.0.1
+```
+
+4. 构建前端生产产物：
+
+```bash
+npm --prefix ./web run build
+```
+
+### 测试
+
+运行完整的本地验证基线：
+
+```bash
+make verify
+```
+
+也可以单独运行各项检查：
+
+```bash
+go test ./cmd/... ./internal/...
+npm --prefix ./web run test
+npm --prefix ./web run lint
+npm --prefix ./web run typecheck
+npm --prefix ./web run build
+```
+
+## Docker
+
+如果 CPA 已在宿主机运行：
+
+```bash
+# TZ 设置容器时区，日志时间会按该时区显示。
+docker run -d \
+  --name cpa-usage-keeper \
+  --add-host=host.docker.internal:host-gateway \
+  -p 8080:8080 \
+  -v "$(pwd)/keeper/data:/data" \
+  -e TZ=Asia/Shanghai \
+  -e CPA_BASE_URL=http://host.docker.internal:8317 \
+  -e CPA_MANAGEMENT_KEY=replace-with-your-management-key \
+  -e REDIS_QUEUE_ADDR=host.docker.internal:8317 \
+  -e AUTH_ENABLED=true \
+  -e LOGIN_PASSWORD=replace-with-your-login-password \
+  ghcr.io/willxup/cpa-usage-keeper:latest
+```
+
+`/data` 用于保存 SQLite 数据库、备份文件和日志文件，请挂载到持久化目录。
+
+## Docker Compose
+
+仓库提供了一个最简 `docker-compose.yaml` 示例，用于同时部署 CPA 和 CPA Usage Keeper：
+
+```yaml
+services:
+  cli-proxy-api:
+    image: eceasy/cli-proxy-api:latest
+    container_name: cli-proxy-api
+    restart: unless-stopped
+    ports:
+      - "8317:8317"
+      - "1455:1455"
+    volumes:
+      - ./cpa/config.yaml:/CLIProxyAPI/config.yaml
+      - ./cpa/auths:/root/.cli-proxy-api
+      - ./cpa/logs:/CLIProxyAPI/logs
+    networks:
+      - cpa-network
+
+  cpa-usage-keeper:
+    image: ghcr.io/willxup/cpa-usage-keeper:latest
+    container_name: cpa-usage-keeper
+    restart: unless-stopped
+    depends_on:
+      - cli-proxy-api
+    ports:
+      - "8080:8080"
+    environment:
+      TZ: Asia/Shanghai # 设置容器时区，日志时间会按该时区显示。
+      CPA_BASE_URL: http://cli-proxy-api:8317
+      CPA_MANAGEMENT_KEY: replace-with-your-management-key
+      REDIS_QUEUE_ADDR: cli-proxy-api:8317
+      AUTH_ENABLED: true
+      LOGIN_PASSWORD: replace-with-your-login-password
+    volumes:
+      - ./keeper:/data
+    networks:
+      - cpa-network
+
+networks:
+  cpa-network:
+    driver: bridge
+```
+
+启动：
+
+```bash
+docker compose up -d
+```
+
+停止：
+
+```bash
+docker compose down
+```
+
+CPA 文件放在 `./cpa`，CPA Usage Keeper 数据放在 `./keeper`。
+
+## 子路径反代
+
+部署到 `/cpa` 时设置 `APP_BASE_PATH=/cpa`，并在反向代理中保留该前缀：
+
+```nginx
+location /cpa/ {
+    proxy_pass http://127.0.0.1:8080;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+## Daili Space deployment
+
+This Space builds CPA Usage Keeper from source and connects to `https://pjpjq-daili.hf.space` through CPA's HTTP `/v0/management/usage-queue` fallback. Dashboard auth is enabled with `LOGIN_PASSWORD`.

cmd/server/main.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"flag"
+	"log"
+	"os"
+
+	"cpa-usage-keeper/internal/app"
+)
+
+func main() {
+	envFile := flag.String("env", "", "path to env file")
+	flag.Parse()
+
+	application, err := app.NewWithOptions(app.Options{EnvFile: *envFile})
+	if err != nil {
+		log.Fatalf("initialize app: %v", err)
+	}
+	defer application.Close()
+
+	if err := application.Run(); err != nil {
+		log.Printf("run app: %v", err)
+		if closeErr := application.Close(); closeErr != nil {
+			log.Printf("close app: %v", closeErr)
+		}
+		os.Exit(1)
+	}
+}

docker-compose.example.yml

@@ -0,0 +1,28 @@
+services:
+  cpa-usage-keeper:
+    image: ghcr.io/willxup/cpa-usage-keeper:latest
+    ports:
+      - "8080:8080"
+    environment:
+      CPA_BASE_URL: ${CPA_BASE_URL}
+      CPA_MANAGEMENT_KEY: ${CPA_MANAGEMENT_KEY}
+      AUTH_ENABLED: ${AUTH_ENABLED:-false}
+      LOGIN_PASSWORD: ${LOGIN_PASSWORD:-}
+      AUTH_SESSION_TTL: ${AUTH_SESSION_TTL:-168h}
+      APP_PORT: ${APP_PORT:-8080}
+      APP_BASE_PATH: ${APP_BASE_PATH:-}
+      TZ: ${TZ:-Asia/Shanghai}
+      REDIS_QUEUE_ADDR: ${REDIS_QUEUE_ADDR:-}
+      REDIS_QUEUE_BATCH_SIZE: ${REDIS_QUEUE_BATCH_SIZE:-1000}
+      REDIS_QUEUE_IDLE_INTERVAL: ${REDIS_QUEUE_IDLE_INTERVAL:-1s}
+      REQUEST_TIMEOUT: ${REQUEST_TIMEOUT:-30s}
+      WORK_DIR: ${WORK_DIR:-./data}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      LOG_FILE_ENABLED: ${LOG_FILE_ENABLED:-true}
+      LOG_RETENTION_DAYS: ${LOG_RETENTION_DAYS:-7}
+      BACKUP_ENABLED: ${BACKUP_ENABLED:-true}
+      BACKUP_INTERVAL: ${BACKUP_INTERVAL:-24h}
+      BACKUP_RETENTION_DAYS: ${BACKUP_RETENTION_DAYS:-7}
+    volumes:
+      - ./data:/data
+    restart: unless-stopped

docker-entrypoint.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+set -eu
+
+ensure_writable_dir() {
+  dir="$1"
+  if [ -z "$dir" ]; then
+    return
+  fi
+  mkdir -p "$dir"
+  chown -R app:app "$dir"
+}
+
+work_dir="${WORK_DIR:-./data}"
+ensure_writable_dir "$work_dir"
+
+case "${BACKUP_ENABLED:-true}" in
+  false|FALSE|False|0)
+    ;;
+  *)
+    ensure_writable_dir "$work_dir/backups"
+    ;;
+esac
+
+case "${LOG_FILE_ENABLED:-true}" in
+  false|FALSE|False|0)
+    ;;
+  *)
+    ensure_writable_dir "$work_dir/logs"
+    ;;
+esac
+
+exec su-exec app "$@"

go.mod

@@ -0,0 +1,43 @@
+module cpa-usage-keeper
+
+go 1.22
+
+require (
+	github.com/gin-gonic/gin v1.10.0
+	github.com/joho/godotenv v1.5.1
+	github.com/sirupsen/logrus v1.9.3
+	gorm.io/driver/sqlite v1.5.7
+	gorm.io/gorm v1.25.12
+)
+
+require (
+	github.com/bytedance/sonic v1.11.6 // indirect
+	github.com/bytedance/sonic/loader v0.1.1 // indirect
+	github.com/cloudwego/base64x v0.1.4 // indirect
+	github.com/cloudwego/iasm v0.2.0 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
+	github.com/gin-contrib/sse v0.1.0 // 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.20.0 // indirect
+	github.com/goccy/go-json v0.10.2 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-sqlite3 v1.14.22 // 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.2 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.2.12 // indirect
+	golang.org/x/arch v0.8.0 // indirect
+	golang.org/x/crypto v0.23.0 // indirect
+	golang.org/x/net v0.25.0 // indirect
+	golang.org/x/sys v0.20.0 // indirect
+	golang.org/x/text v0.15.0 // indirect
+	google.golang.org/protobuf v1.34.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,104 @@
+github.com/bytedance/sonic v1.11.6 h1:oUp34TzMlL+OY1OUWxHqsdkgC/Zfc85zGqw9siXjrc0=
+github.com/bytedance/sonic v1.11.6/go.mod h1:LysEHSvpvDySVdC2f87zGWf6CIKJcAvqab1ZaiQtds4=
+github.com/bytedance/sonic/loader v0.1.1 h1:c+e5Pt1k/cy5wMveRDyk2X4B9hF4g7an8N3zCYjJFNM=
+github.com/bytedance/sonic/loader v0.1.1/go.mod h1:ncP89zfokxS5LZrJxl5z0UJcsk4M4yY2JpfqGeCtNLU=
+github.com/cloudwego/base64x v0.1.4 h1:jwCgWpFanWmN8xoIUHa2rtzmkd5J2plF/dnLS6Xd/0Y=
+github.com/cloudwego/base64x v0.1.4/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJgA0rcu/8w=
+github.com/cloudwego/iasm v0.2.0 h1:1KNIy1I1H9hNNFEEH3DVnI4UujN+1zjpuk6gwHLTssg=
+github.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=
+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/gabriel-vasile/mimetype v1.4.3 h1:in2uUcidCuFcDKtdcBxlR0rJ1+fsokWf+uqxgUFjbI0=
+github.com/gabriel-vasile/mimetype v1.4.3/go.mod h1:d8uq/6HKRL6CGdk+aubisF/M5GcPfT7nKyLpA0lbSSk=
+github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
+github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
+github.com/gin-gonic/gin v1.10.0 h1:nTuyha1TYqgedzytsKYqna+DfLos46nTv2ygFy86HFU=
+github.com/gin-gonic/gin v1.10.0/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
+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.20.0 h1:K9ISHbSaI0lyB2eWMPJo+kOS/FBExVwjEviJTixqxL8=
+github.com/go-playground/validator/v10 v10.20.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
+github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
+github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
+github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+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/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+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/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
+github.com/klauspost/cpuid/v2 v2.2.7 h1:ZWSB3igEs+d0qvnxR/ZBzXVmxkgt8DdzP6m9pfuVLDM=
+github.com/klauspost/cpuid/v2 v2.2.7/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws=
+github.com/knz/go-libedit v1.10.1/go.mod h1:MZTVkCWyz0oBc7JOWP3wNAzd002ZbM/5hgShxwh4x8M=
+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/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/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
+github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
+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/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
+github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
+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.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.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
+github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
+github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
+golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
+golang.org/x/arch v0.8.0 h1:3wRIsP3pM4yUptoR96otTUOXI367OS0+c9eeRi9doIc=
+golang.org/x/arch v0.8.0/go.mod h1:FEVrYAQjsQXMVJ1nsMoVVXPZg6p2JE2mx8psSWTDQys=
+golang.org/x/crypto v0.23.0 h1:dIJU/v2J8Mdglj/8rJ6UUOM3Zc9zLZxVZwwxMooUSAI=
+golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
+golang.org/x/net v0.25.0 h1:d/OCCoBEUq33pjydKrGQhw7IlUPI2Oylr+8qLx49kac=
+golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
+golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/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.20.0 h1:Od9JTbYCk261bKm4M/mw7AklTlFYIa0bIp9BgSm1S8Y=
+golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.15.0 h1:h1V/4gjBv8v9cjcR6+AR5+/cIYK5N/WAgiv4xlsEtAk=
+golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=
+google.golang.org/protobuf v1.34.1/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/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/sqlite v1.5.7 h1:8NvsrhP0ifM7LX9G4zPB97NwovUakUxc+2V2uuf3Z1I=
+gorm.io/driver/sqlite v1.5.7/go.mod h1:U+J8craQU6Fzkcvu8oLeAQmi50TkwPEhHDEjQZXDah4=
+gorm.io/gorm v1.25.12 h1:I0u8i2hWQItBq1WfE0o2+WuL9+8L21K9e2HHSTE/0f8=
+gorm.io/gorm v1.25.12/go.mod h1:xh7N7RHfYlNc5EmcI/El95gXusucDrQnHXe0+CgWcLQ=
+nullprogram.com/x/optparse v1.0.0/go.mod h1:KdyPE+Igbe0jQUrVfMqDMeJQIJZEuyV7pjYmp6pbG50=
+rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=

internal/api/auth.go

@@ -0,0 +1,199 @@
+package api
+
+import (
+	"crypto/subtle"
+	"net"
+	"net/http"
+	"sync"
+	"time"
+
+	"cpa-usage-keeper/internal/auth"
+	"github.com/gin-gonic/gin"
+)
+
+const sessionCookieName = "cpa_usage_keeper_session"
+
+const maxFailedLoginAttempts = 5
+
+type AuthConfig struct {
+	Enabled       bool
+	LoginPassword string
+	SessionTTL    time.Duration
+	BasePath      string
+}
+
+type authHandler struct {
+	config   AuthConfig
+	sessions *auth.SessionManager
+
+	mu             sync.Mutex
+	failedAttempts map[string]int
+}
+
+type loginRequest struct {
+	Password string `json:"password"`
+}
+
+type sessionResponse struct {
+	Authenticated bool `json:"authenticated"`
+}
+
+func NewAuthHandler(config AuthConfig, sessions *auth.SessionManager) *authHandler {
+	return &authHandler{config: config, sessions: sessions, failedAttempts: make(map[string]int)}
+}
+
+func (h *authHandler) registerRoutes(router gin.IRoutes) {
+	router.GET("/session", h.getSession)
+	router.POST("/login", h.login)
+	router.POST("/logout", h.logout)
+}
+
+func (h *authHandler) middleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if h == nil || !h.config.Enabled {
+			c.Next()
+			return
+		}
+		if h.sessions == nil {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "authentication required"})
+			return
+		}
+
+		token, err := c.Cookie(sessionCookieName)
+		if err != nil || !h.sessions.Validate(token) {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "authentication required"})
+			return
+		}
+
+		c.Next()
+	}
+}
+
+func (h *authHandler) getSession(c *gin.Context) {
+	if h == nil || !h.config.Enabled {
+		c.JSON(http.StatusOK, sessionResponse{Authenticated: true})
+		return
+	}
+	if h.sessions == nil {
+		c.JSON(http.StatusOK, sessionResponse{Authenticated: false})
+		return
+	}
+
+	token, err := c.Cookie(sessionCookieName)
+	if err != nil {
+		c.JSON(http.StatusOK, sessionResponse{Authenticated: false})
+		return
+	}
+
+	c.JSON(http.StatusOK, sessionResponse{Authenticated: h.sessions.Validate(token)})
+}
+
+func (h *authHandler) login(c *gin.Context) {
+	if h == nil || !h.config.Enabled {
+		c.Status(http.StatusNoContent)
+		return
+	}
+	if h.sessions == nil {
+		writeInternalError(c, "session manager is not configured", nil)
+		return
+	}
+
+	var request loginRequest
+	if err := c.ShouldBindJSON(&request); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	clientKey := loginClientKey(c)
+	passwordMatches := subtle.ConstantTimeCompare([]byte(request.Password), []byte(h.config.LoginPassword)) == 1
+	if h.tooManyFailedAttempts(clientKey) && !passwordMatches {
+		c.JSON(http.StatusTooManyRequests, gin.H{"error": "too many failed login attempts"})
+		return
+	}
+
+	if !passwordMatches {
+		h.recordFailedAttempt(clientKey)
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid password"})
+		return
+	}
+	h.clearFailedAttempts(clientKey)
+
+	token, expiresAt, err := h.sessions.Create()
+	if err != nil {
+		writeInternalError(c, "create auth session failed", err)
+		return
+	}
+
+	secure := c.Request.TLS != nil || c.GetHeader("X-Forwarded-Proto") == "https"
+	cookiePath := h.config.BasePath
+	if cookiePath == "" {
+		cookiePath = "/"
+	}
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name:     sessionCookieName,
+		Value:    token,
+		Path:     cookiePath,
+		HttpOnly: true,
+		Secure:   secure,
+		SameSite: http.SameSiteLaxMode,
+		Expires:  expiresAt,
+		MaxAge:   int(time.Until(expiresAt).Seconds()),
+	})
+	c.Status(http.StatusNoContent)
+}
+
+func (h *authHandler) logout(c *gin.Context) {
+	if h == nil || !h.config.Enabled {
+		c.Status(http.StatusNoContent)
+		return
+	}
+	if h.sessions != nil {
+		if token, err := c.Cookie(sessionCookieName); err == nil {
+			h.sessions.Delete(token)
+		}
+	}
+	clearSessionCookie(c, h.config.BasePath)
+	c.Status(http.StatusNoContent)
+}
+
+func (h *authHandler) tooManyFailedAttempts(key string) bool {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return h.failedAttempts[key] >= maxFailedLoginAttempts
+}
+
+func (h *authHandler) recordFailedAttempt(key string) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	h.failedAttempts[key]++
+}
+
+func (h *authHandler) clearFailedAttempts(key string) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	delete(h.failedAttempts, key)
+}
+
+func loginClientKey(c *gin.Context) string {
+	host, _, err := net.SplitHostPort(c.Request.RemoteAddr)
+	if err == nil && host != "" {
+		return host
+	}
+	return c.ClientIP()
+}
+
+func clearSessionCookie(c *gin.Context, basePath string) {
+	cookiePath := basePath
+	if cookiePath == "" {
+		cookiePath = "/"
+	}
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name:     sessionCookieName,
+		Value:    "",
+		Path:     cookiePath,
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+		Expires:  time.Unix(0, 0),
+		MaxAge:   -1,
+	})
+}

internal/api/auth_test.go

@@ -0,0 +1,225 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"cpa-usage-keeper/internal/auth"
+)
+
+func TestAuthSessionReportsAuthenticatedWhenDisabled(t *testing.T) {
+	router := NewRouter(nil, nil, nil, nil, AuthConfig{Enabled: false}, nil, "")
+	resp := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/auth/session", nil)
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK || !contains(resp.Body.String(), `"authenticated":true`) {
+		t.Fatalf("unexpected response: %d %s", resp.Code, resp.Body.String())
+	}
+}
+
+func TestAuthProtectedRouteRequiresSessionWhenEnabled(t *testing.T) {
+	sessions := auth.NewSessionManager(time.Hour)
+	config := AuthConfig{Enabled: true, LoginPassword: "secret", SessionTTL: time.Hour}
+	router := NewRouter(nil, nil, nil, nil, config, NewAuthHandler(config, sessions), "")
+	resp := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/overview", nil)
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusUnauthorized {
+		t.Fatalf("expected status 401, got %d", resp.Code)
+	}
+}
+
+func TestAuthLoginSetsCookieAndUnlocksProtectedRoute(t *testing.T) {
+	sessions := auth.NewSessionManager(time.Hour)
+	config := AuthConfig{Enabled: true, LoginPassword: "secret", SessionTTL: time.Hour}
+	handler := NewAuthHandler(config, sessions)
+	router := NewRouter(nil, nil, nil, nil, config, handler, "")
+
+	loginResp := httptest.NewRecorder()
+	loginReq := httptest.NewRequest(http.MethodPost, "/api/v1/auth/login", strings.NewReader(`{"password":"secret"}`))
+	loginReq.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(loginResp, loginReq)
+
+	if loginResp.Code != http.StatusNoContent {
+		t.Fatalf("expected login status 204, got %d", loginResp.Code)
+	}
+	cookie := loginResp.Result().Cookies()
+	if len(cookie) == 0 {
+		t.Fatal("expected auth cookie to be set")
+	}
+	if cookie[0].Name != sessionCookieName {
+		t.Fatalf("expected cookie %q, got %q", sessionCookieName, cookie[0].Name)
+	}
+	if cookie[0].Path != "/" {
+		t.Fatalf("expected root cookie path '/', got %q", cookie[0].Path)
+	}
+
+	usageResp := httptest.NewRecorder()
+	usageReq := httptest.NewRequest(http.MethodGet, "/api/v1/usage/overview", nil)
+	usageReq.AddCookie(cookie[0])
+	router.ServeHTTP(usageResp, usageReq)
+
+	if usageResp.Code != http.StatusOK {
+		t.Fatalf("expected protected route to succeed, got %d %s", usageResp.Code, usageResp.Body.String())
+	}
+}
+
+func TestAuthLoginRejectsWrongPassword(t *testing.T) {
+	sessions := auth.NewSessionManager(time.Hour)
+	config := AuthConfig{Enabled: true, LoginPassword: "secret", SessionTTL: time.Hour}
+	router := NewRouter(nil, nil, nil, nil, config, NewAuthHandler(config, sessions), "")
+	resp := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/auth/login", strings.NewReader(`{"password":"wrong"}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusUnauthorized {
+		t.Fatalf("expected status 401, got %d", resp.Code)
+	}
+}
+
+func TestAuthLoginRateLimitsRepeatedFailures(t *testing.T) {
+	sessions := auth.NewSessionManager(time.Hour)
+	config := AuthConfig{Enabled: true, LoginPassword: "secret", SessionTTL: time.Hour}
+	router := NewRouter(nil, nil, nil, nil, config, NewAuthHandler(config, sessions), "")
+
+	for i := 0; i < 5; i++ {
+		resp := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/auth/login", strings.NewReader(`{"password":"wrong"}`))
+		req.Header.Set("Content-Type", "application/json")
+		req.RemoteAddr = "198.51.100.1:1234"
+		router.ServeHTTP(resp, req)
+		if resp.Code != http.StatusUnauthorized {
+			t.Fatalf("expected failed attempt %d to return 401, got %d", i+1, resp.Code)
+		}
+	}
+
+	resp := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/auth/login", strings.NewReader(`{"password":"wrong"}`))
+	req.Header.Set("Content-Type", "application/json")
+	req.RemoteAddr = "198.51.100.1:1234"
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusTooManyRequests {
+		t.Fatalf("expected repeated failed attempts to return 429, got %d", resp.Code)
+	}
+}
+
+func TestAuthLoginAllowsCorrectPasswordAfterRateLimitThreshold(t *testing.T) {
+	sessions := auth.NewSessionManager(time.Hour)
+	config := AuthConfig{Enabled: true, LoginPassword: "secret", SessionTTL: time.Hour}
+	router := NewRouter(nil, nil, nil, nil, config, NewAuthHandler(config, sessions), "")
+
+	for i := 0; i < 5; i++ {
+		resp := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/auth/login", strings.NewReader(`{"password":"wrong"}`))
+		req.Header.Set("Content-Type", "application/json")
+		req.RemoteAddr = "198.51.100.2:1234"
+		router.ServeHTTP(resp, req)
+		if resp.Code != http.StatusUnauthorized {
+			t.Fatalf("expected failed attempt %d to return 401, got %d", i+1, resp.Code)
+		}
+	}
+
+	resp := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/auth/login", strings.NewReader(`{"password":"secret"}`))
+	req.Header.Set("Content-Type", "application/json")
+	req.RemoteAddr = "198.51.100.2:1234"
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusNoContent {
+		t.Fatalf("expected correct password to clear failed attempts and login, got %d", resp.Code)
+	}
+}
+
+func TestAuthLogoutDeletesSessionCookie(t *testing.T) {
+	sessions := auth.NewSessionManager(time.Hour)
+	config := AuthConfig{Enabled: true, LoginPassword: "secret", SessionTTL: time.Hour}
+	handler := NewAuthHandler(config, sessions)
+	router := NewRouter(nil, nil, nil, nil, config, handler, "")
+
+	loginResp := httptest.NewRecorder()
+	loginReq := httptest.NewRequest(http.MethodPost, "/api/v1/auth/login", strings.NewReader(`{"password":"secret"}`))
+	loginReq.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(loginResp, loginReq)
+	if loginResp.Code != http.StatusNoContent {
+		t.Fatalf("expected login status 204, got %d", loginResp.Code)
+	}
+	cookies := loginResp.Result().Cookies()
+	if len(cookies) == 0 {
+		t.Fatal("expected auth cookie to be set")
+	}
+
+	logoutResp := httptest.NewRecorder()
+	logoutReq := httptest.NewRequest(http.MethodPost, "/api/v1/auth/logout", nil)
+	logoutReq.AddCookie(cookies[0])
+	router.ServeHTTP(logoutResp, logoutReq)
+	if logoutResp.Code != http.StatusNoContent {
+		t.Fatalf("expected logout status 204, got %d", logoutResp.Code)
+	}
+	clearCookies := logoutResp.Result().Cookies()
+	if len(clearCookies) == 0 || clearCookies[0].Name != sessionCookieName || clearCookies[0].MaxAge >= 0 {
+		t.Fatalf("expected logout to clear session cookie, got %+v", clearCookies)
+	}
+
+	usageResp := httptest.NewRecorder()
+	usageReq := httptest.NewRequest(http.MethodGet, "/api/v1/usage/overview", nil)
+	usageReq.AddCookie(cookies[0])
+	router.ServeHTTP(usageResp, usageReq)
+	if usageResp.Code != http.StatusUnauthorized {
+		t.Fatalf("expected logged out session to be rejected, got %d", usageResp.Code)
+	}
+}
+
+func TestSubpathAuthUsesPrefixedRoutesAndCookiePath(t *testing.T) {
+	sessions := auth.NewSessionManager(time.Hour)
+	config := AuthConfig{Enabled: true, LoginPassword: "secret", SessionTTL: time.Hour, BasePath: "/cpa"}
+	handler := NewAuthHandler(config, sessions)
+	router := NewRouter(nil, nil, nil, nil, config, handler, "/cpa")
+
+	sessionResp := httptest.NewRecorder()
+	sessionReq := httptest.NewRequest(http.MethodGet, "/cpa/api/v1/auth/session", nil)
+	router.ServeHTTP(sessionResp, sessionReq)
+	if sessionResp.Code != http.StatusOK || !contains(sessionResp.Body.String(), `"authenticated":false`) {
+		t.Fatalf("unexpected session response: %d %s", sessionResp.Code, sessionResp.Body.String())
+	}
+
+	loginResp := httptest.NewRecorder()
+	loginReq := httptest.NewRequest(http.MethodPost, "/cpa/api/v1/auth/login", strings.NewReader(`{"password":"secret"}`))
+	loginReq.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(loginResp, loginReq)
+	if loginResp.Code != http.StatusNoContent {
+		t.Fatalf("expected login status 204, got %d", loginResp.Code)
+	}
+	cookies := loginResp.Result().Cookies()
+	if len(cookies) == 0 {
+		t.Fatal("expected auth cookie to be set")
+	}
+	if cookies[0].Path != "/cpa" {
+		t.Fatalf("expected subpath cookie path '/cpa', got %q", cookies[0].Path)
+	}
+
+	usageResp := httptest.NewRecorder()
+	usageReq := httptest.NewRequest(http.MethodGet, "/cpa/api/v1/usage/overview", nil)
+	usageReq.AddCookie(cookies[0])
+	router.ServeHTTP(usageResp, usageReq)
+	if usageResp.Code != http.StatusOK {
+		t.Fatalf("expected protected route under subpath to succeed, got %d %s", usageResp.Code, usageResp.Body.String())
+	}
+
+	unprefixedResp := httptest.NewRecorder()
+	unprefixedReq := httptest.NewRequest(http.MethodGet, "/api/v1/usage/overview", nil)
+	unprefixedReq.AddCookie(cookies[0])
+	router.ServeHTTP(unprefixedResp, unprefixedReq)
+	if unprefixedResp.Code != http.StatusNotFound {
+		t.Fatalf("expected unprefixed route to 404, got %d", unprefixedResp.Code)
+	}
+}

internal/api/errors.go

@@ -0,0 +1,15 @@
+package api
+
+import (
+	"log/slog"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+func writeInternalError(c *gin.Context, message string, err error) {
+	if err != nil {
+		slog.Error(message, "error", err)
+	}
+	c.JSON(http.StatusInternalServerError, gin.H{"error": "internal server error"})
+}

internal/api/health.go

@@ -0,0 +1,13 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+func registerHealthRoutes(router gin.IRoutes) {
+	router.GET("/healthz", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+}

internal/api/pricing.go

@@ -0,0 +1,145 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+
+	"cpa-usage-keeper/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type usedModelsResponse struct {
+	Models []string `json:"models"`
+}
+
+type pricingEntryResponse struct {
+	Model                string  `json:"model"`
+	PromptPricePer1M     float64 `json:"prompt_price_per_1m"`
+	CompletionPricePer1M float64 `json:"completion_price_per_1m"`
+	CachePricePer1M      float64 `json:"cache_price_per_1m"`
+}
+
+type pricingListResponse struct {
+	Pricing []pricingEntryResponse `json:"pricing"`
+}
+
+type updatePricingRequest struct {
+	Model                string  `json:"model"`
+	PromptPricePer1M     float64 `json:"prompt_price_per_1m"`
+	CompletionPricePer1M float64 `json:"completion_price_per_1m"`
+	CachePricePer1M      float64 `json:"cache_price_per_1m"`
+}
+
+func registerPricingRoutes(router gin.IRoutes, pricingProvider service.PricingProvider) {
+	router.GET("/models/used", func(c *gin.Context) {
+		if pricingProvider == nil {
+			c.JSON(http.StatusOK, usedModelsResponse{Models: []string{}})
+			return
+		}
+
+		models, err := pricingProvider.ListUsedModels(c.Request.Context())
+		if err != nil {
+			writeInternalError(c, "list used models failed", err)
+			return
+		}
+
+		c.JSON(http.StatusOK, usedModelsResponse{Models: models})
+	})
+
+	router.GET("/pricing", func(c *gin.Context) {
+		if pricingProvider == nil {
+			c.JSON(http.StatusOK, pricingListResponse{Pricing: []pricingEntryResponse{}})
+			return
+		}
+
+		settings, err := pricingProvider.ListPricing(c.Request.Context())
+		if err != nil {
+			writeInternalError(c, "list pricing failed", err)
+			return
+		}
+
+		response := make([]pricingEntryResponse, 0, len(settings))
+		for _, setting := range settings {
+			response = append(response, pricingEntryResponse{
+				Model:                setting.Model,
+				PromptPricePer1M:     setting.PromptPricePer1M,
+				CompletionPricePer1M: setting.CompletionPricePer1M,
+				CachePricePer1M:      setting.CachePricePer1M,
+			})
+		}
+		c.JSON(http.StatusOK, pricingListResponse{Pricing: response})
+	})
+
+	router.PUT("/pricing", func(c *gin.Context) {
+		updatePricing(c, pricingProvider, "")
+	})
+
+	router.PUT("/pricing/:model", func(c *gin.Context) {
+		updatePricing(c, pricingProvider, c.Param("model"))
+	})
+
+	router.DELETE("/pricing", func(c *gin.Context) {
+		if pricingProvider == nil {
+			c.JSON(http.StatusNotImplemented, gin.H{"error": "pricing provider is not configured"})
+			return
+		}
+		model := strings.TrimSpace(c.Query("model"))
+		if model == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "model is required"})
+			return
+		}
+		if err := pricingProvider.DeletePricing(c.Request.Context(), model); err != nil {
+			if strings.Contains(err.Error(), "required") {
+				c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+				return
+			}
+			writeInternalError(c, "delete pricing failed", err)
+			return
+		}
+		c.Status(http.StatusNoContent)
+	})
+}
+
+func updatePricing(c *gin.Context, pricingProvider service.PricingProvider, pathModel string) {
+	if pricingProvider == nil {
+		c.JSON(http.StatusNotImplemented, gin.H{"error": "pricing provider is not configured"})
+		return
+	}
+
+	var request updatePricingRequest
+	if err := c.ShouldBindJSON(&request); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	model := strings.TrimSpace(pathModel)
+	if model == "" {
+		model = strings.TrimSpace(request.Model)
+	}
+	if model == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "model is required"})
+		return
+	}
+
+	setting, err := pricingProvider.UpdatePricing(c.Request.Context(), service.UpdatePricingInput{
+		Model:                model,
+		PromptPricePer1M:     request.PromptPricePer1M,
+		CompletionPricePer1M: request.CompletionPricePer1M,
+		CachePricePer1M:      request.CachePricePer1M,
+	})
+	if err != nil {
+		if strings.Contains(err.Error(), "has not been used") || strings.Contains(err.Error(), "required") || strings.Contains(err.Error(), "non-negative") {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		writeInternalError(c, "update pricing failed", err)
+		return
+	}
+
+	c.JSON(http.StatusOK, pricingEntryResponse{
+		Model:                setting.Model,
+		PromptPricePer1M:     setting.PromptPricePer1M,
+		CompletionPricePer1M: setting.CompletionPricePer1M,
+		CachePricePer1M:      setting.CachePricePer1M,
+	})
+}

internal/api/pricing_test.go

@@ -0,0 +1,144 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"cpa-usage-keeper/internal/models"
+	"cpa-usage-keeper/internal/service"
+)
+
+type pricingStub struct {
+	usedModels []string
+	pricing    []models.ModelPriceSetting
+	updated    *models.ModelPriceSetting
+	lastUpdate *service.UpdatePricingInput
+	deleted    string
+	err        error
+}
+
+func (s pricingStub) ListUsedModels(context.Context) ([]string, error) {
+	return s.usedModels, s.err
+}
+
+func (s pricingStub) ListPricing(context.Context) ([]models.ModelPriceSetting, error) {
+	return s.pricing, s.err
+}
+
+func (s *pricingStub) UpdatePricing(_ context.Context, input service.UpdatePricingInput) (*models.ModelPriceSetting, error) {
+	s.lastUpdate = &input
+	return s.updated, s.err
+}
+
+func (s *pricingStub) DeletePricing(_ context.Context, model string) error {
+	s.deleted = model
+	return s.err
+}
+
+func TestPricingRoutesReturnEmptyResponsesWithoutProvider(t *testing.T) {
+	router := NewRouter(nil, nil, nil, nil, AuthConfig{}, nil, "")
+
+	usedReq := httptest.NewRequest(http.MethodGet, "/api/v1/models/used", nil)
+	usedResp := httptest.NewRecorder()
+	router.ServeHTTP(usedResp, usedReq)
+	if usedResp.Code != http.StatusOK || !contains(usedResp.Body.String(), `"models":[]`) {
+		t.Fatalf("unexpected used models response: %d %s", usedResp.Code, usedResp.Body.String())
+	}
+
+	pricingReq := httptest.NewRequest(http.MethodGet, "/api/v1/pricing", nil)
+	pricingResp := httptest.NewRecorder()
+	router.ServeHTTP(pricingResp, pricingReq)
+	if pricingResp.Code != http.StatusOK || !contains(pricingResp.Body.String(), `"pricing":[]`) {
+		t.Fatalf("unexpected pricing response: %d %s", pricingResp.Code, pricingResp.Body.String())
+	}
+}
+
+func TestPricingRoutesReturnConfiguredData(t *testing.T) {
+	router := NewRouter(nil, nil, nil, &pricingStub{
+		usedModels: []string{"claude-sonnet"},
+		pricing: []models.ModelPriceSetting{{
+			Model:                "claude-sonnet",
+			PromptPricePer1M:     3,
+			CompletionPricePer1M: 15,
+			CachePricePer1M:      0.3,
+		}},
+	}, AuthConfig{}, nil, "")
+
+	usedReq := httptest.NewRequest(http.MethodGet, "/api/v1/models/used", nil)
+	usedResp := httptest.NewRecorder()
+	router.ServeHTTP(usedResp, usedReq)
+	if usedResp.Code != http.StatusOK || !contains(usedResp.Body.String(), `claude-sonnet`) {
+		t.Fatalf("unexpected used models response: %d %s", usedResp.Code, usedResp.Body.String())
+	}
+
+	pricingReq := httptest.NewRequest(http.MethodGet, "/api/v1/pricing", nil)
+	pricingResp := httptest.NewRecorder()
+	router.ServeHTTP(pricingResp, pricingReq)
+	if pricingResp.Code != http.StatusOK || !contains(pricingResp.Body.String(), `"prompt_price_per_1m":3`) {
+		t.Fatalf("unexpected pricing response: %d %s", pricingResp.Code, pricingResp.Body.String())
+	}
+}
+
+func TestUpdatePricingRoute(t *testing.T) {
+	provider := &pricingStub{
+		updated: &models.ModelPriceSetting{
+			Model:                "claude-sonnet",
+			PromptPricePer1M:     3,
+			CompletionPricePer1M: 15,
+			CachePricePer1M:      0.3,
+		},
+	}
+	router := NewRouter(nil, nil, nil, provider, AuthConfig{}, nil, "")
+
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/pricing/claude-sonnet", strings.NewReader(`{"prompt_price_per_1m":3,"completion_price_per_1m":15,"cache_price_per_1m":0.3}`))
+	req.Header.Set("Content-Type", "application/json")
+	resp := httptest.NewRecorder()
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK || !contains(resp.Body.String(), `"model":"claude-sonnet"`) {
+		t.Fatalf("unexpected update response: %d %s", resp.Code, resp.Body.String())
+	}
+}
+
+func TestUpdatePricingRouteAcceptsModelInBody(t *testing.T) {
+	provider := &pricingStub{
+		updated: &models.ModelPriceSetting{
+			Model:                "openai/gpt-4.1",
+			PromptPricePer1M:     3,
+			CompletionPricePer1M: 15,
+			CachePricePer1M:      0.3,
+		},
+	}
+	router := NewRouter(nil, nil, nil, provider, AuthConfig{}, nil, "")
+
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/pricing", strings.NewReader(`{"model":"openai/gpt-4.1","prompt_price_per_1m":3,"completion_price_per_1m":15,"cache_price_per_1m":0.3}`))
+	req.Header.Set("Content-Type", "application/json")
+	resp := httptest.NewRecorder()
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK || !contains(resp.Body.String(), `"model":"openai/gpt-4.1"`) {
+		t.Fatalf("unexpected update response: %d %s", resp.Code, resp.Body.String())
+	}
+	if provider.lastUpdate == nil || provider.lastUpdate.Model != "openai/gpt-4.1" {
+		t.Fatalf("expected model from body to be passed through, got %+v", provider.lastUpdate)
+	}
+}
+
+func TestDeletePricingRoute(t *testing.T) {
+	provider := &pricingStub{}
+	router := NewRouter(nil, nil, nil, provider, AuthConfig{}, nil, "")
+
+	req := httptest.NewRequest(http.MethodDelete, "/api/v1/pricing?model=openai%2Fgpt-4.1", nil)
+	resp := httptest.NewRecorder()
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusNoContent {
+		t.Fatalf("expected status 204, got %d %s", resp.Code, resp.Body.String())
+	}
+	if provider.deleted != "openai/gpt-4.1" {
+		t.Fatalf("expected model to be deleted, got %q", provider.deleted)
+	}
+}

internal/api/router.go

@@ -0,0 +1,272 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"io/fs"
+	"log/slog"
+	"net/http"
+	"path"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"cpa-usage-keeper/internal/poller"
+	"cpa-usage-keeper/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+const appBasePathPlaceholder = "__APP_BASE_PATH__"
+const manualSyncRateLimitWindow = time.Second
+
+type syncLimiter struct {
+	mu       sync.Mutex
+	window   time.Duration
+	lastSync time.Time
+}
+
+func (l *syncLimiter) allow(now time.Time) bool {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if !l.lastSync.IsZero() && now.Sub(l.lastSync) < l.window {
+		return false
+	}
+	l.lastSync = now
+	return true
+}
+
+type StatusProvider interface {
+	Status() poller.Status
+}
+
+type SyncRunner interface {
+	SyncNow(ctx context.Context) error
+}
+
+type syncUserMessageError interface {
+	UserMessage() string
+}
+
+func NewRouter(
+	staticFS fs.FS,
+	statusProvider StatusProvider,
+	usageProvider service.UsageProvider,
+	pricingProvider service.PricingProvider,
+	authConfig AuthConfig,
+	authHandler *authHandler,
+	basePath string,
+	usageIdentityProviders ...service.UsageIdentityProvider,
+) *gin.Engine {
+	router := gin.New()
+	router.Use(gin.Recovery())
+
+	appGroup := router.Group(basePath)
+	registerHealthRoutes(appGroup)
+
+	apiV1 := appGroup.Group("/api/v1")
+	apiV1.GET("/ping", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"message": "ok"})
+	})
+
+	authGroup := apiV1.Group("/auth")
+	if authHandler == nil {
+		authHandler = NewAuthHandler(authConfig, nil)
+	}
+	authHandler.registerRoutes(authGroup)
+
+	var usageIdentityProvider service.UsageIdentityProvider
+	if len(usageIdentityProviders) > 0 {
+		usageIdentityProvider = usageIdentityProviders[0]
+	}
+
+	protected := apiV1.Group("")
+	protected.Use(authHandler.middleware())
+	registerStatusRoutes(protected, statusProvider)
+	registerSyncRoutes(protected, statusProvider, &syncLimiter{window: manualSyncRateLimitWindow})
+	registerUsageOverviewRoute(protected, usageProvider)
+	registerUsageAnalysisRoute(protected, usageProvider)
+	registerUsageEventsRoute(protected, usageProvider, usageIdentityProvider)
+	registerUsageCredentialsRoute(protected, usageProvider, usageIdentityProvider)
+	registerUsageIdentityRoutes(protected, usageIdentityProvider)
+	registerPricingRoutes(protected, pricingProvider)
+
+	if staticFS != nil {
+		if indexFile, err := staticFS.Open("index.html"); err == nil {
+			_ = indexFile.Close()
+			httpFS := http.FS(staticFS)
+			serveIndex := func(c *gin.Context) {
+				indexHTML, err := renderIndexHTML(staticFS, basePath)
+				if err != nil {
+					c.Status(http.StatusNotFound)
+					return
+				}
+				c.Data(http.StatusOK, "text/html; charset=utf-8", indexHTML)
+			}
+
+			appGroup.GET("/", serveIndex)
+			assetsFS, _ := fs.Sub(staticFS, "assets")
+			appGroup.StaticFS("/assets", http.FS(assetsFS))
+			router.NoRoute(func(c *gin.Context) {
+				requestPath, ok := stripBasePath(basePath, c.Request.URL.Path)
+				if !ok {
+					c.Status(http.StatusNotFound)
+					return
+				}
+				if strings.HasPrefix(requestPath, "/api/") {
+					c.Status(http.StatusNotFound)
+					return
+				}
+
+				if assetPath, ok := staticAssetPath(requestPath); ok {
+					if assetFile, err := staticFS.Open(assetPath); err == nil {
+						_ = assetFile.Close()
+						c.FileFromFS(assetPath, httpFS)
+						return
+					}
+				}
+
+				serveIndex(c)
+			})
+		}
+	}
+
+	return router
+}
+
+func renderIndexHTML(staticFS fs.FS, basePath string) ([]byte, error) {
+	indexFile, err := staticFS.Open("index.html")
+	if err != nil {
+		return nil, err
+	}
+	defer indexFile.Close()
+	indexHTML, err := io.ReadAll(indexFile)
+	if err != nil {
+		return nil, err
+	}
+
+	return bytes.ReplaceAll(
+		indexHTML,
+		[]byte(strconv.Quote(appBasePathPlaceholder)),
+		[]byte(strconv.Quote(basePath)),
+	), nil
+}
+
+func cleanURLPath(requestPath string) string {
+	cleaned := path.Clean(requestPath)
+	if cleaned == "." {
+		return "/"
+	}
+	if !strings.HasPrefix(cleaned, "/") {
+		return "/" + cleaned
+	}
+	return cleaned
+}
+
+func staticAssetPath(requestPath string) (string, bool) {
+	cleaned := cleanURLPath(requestPath)
+	if strings.Contains(cleaned, "\\") {
+		return "", false
+	}
+	relPath := strings.TrimPrefix(cleaned, "/")
+	if relPath == "" {
+		return "", false
+	}
+	return relPath, true
+}
+
+func stripBasePath(basePath, requestPath string) (string, bool) {
+	cleaned := cleanURLPath(requestPath)
+	if basePath == "" {
+		return cleaned, true
+	}
+	if cleaned == basePath {
+		return "/", true
+	}
+	if !strings.HasPrefix(cleaned, basePath+"/") {
+		return "", false
+	}
+	trimmed := strings.TrimPrefix(cleaned, basePath)
+	if trimmed == "" {
+		return "/", true
+	}
+	return trimmed, true
+}
+
+type statusResponse struct {
+	Running     bool       `json:"running"`
+	SyncRunning bool       `json:"sync_running"`
+	Timezone    string     `json:"timezone"`
+	LastRunAt   *time.Time `json:"last_run_at,omitempty"`
+	LastError   string     `json:"last_error,omitempty"`
+	LastWarning string     `json:"last_warning,omitempty"`
+	LastStatus  string     `json:"last_status,omitempty"`
+}
+
+func registerStatusRoutes(router gin.IRoutes, statusProvider StatusProvider) {
+	router.GET("/status", func(c *gin.Context) {
+		if statusProvider == nil {
+			c.JSON(http.StatusOK, statusResponse{Timezone: time.Local.String()})
+			return
+		}
+
+		c.JSON(http.StatusOK, buildStatusResponse(statusProvider.Status()))
+	})
+}
+
+func manualSyncErrorMessage(err error) string {
+	var userMessage syncUserMessageError
+	if errors.As(err, &userMessage) && userMessage.UserMessage() != "" {
+		return userMessage.UserMessage()
+	}
+	return "manual sync failed"
+}
+
+func registerSyncRoutes(router gin.IRoutes, statusProvider StatusProvider, limiter *syncLimiter) {
+	router.POST("/sync", func(c *gin.Context) {
+		if limiter != nil && !limiter.allow(time.Now()) {
+			c.JSON(http.StatusTooManyRequests, gin.H{"error": "sync rate limit exceeded"})
+			return
+		}
+
+		syncRunner, ok := statusProvider.(SyncRunner)
+		if !ok || syncRunner == nil {
+			writeInternalError(c, "sync runner is not configured", nil)
+			return
+		}
+
+		if err := syncRunner.SyncNow(c.Request.Context()); err != nil {
+			if errors.Is(err, poller.ErrSyncAlreadyRunning) {
+				c.JSON(http.StatusConflict, gin.H{"error": "sync already running"})
+				return
+			}
+			slog.Error("manual sync failed", "error", err)
+			c.JSON(http.StatusInternalServerError, gin.H{"error": manualSyncErrorMessage(err)})
+			return
+		}
+
+		if statusProvider, ok := syncRunner.(StatusProvider); ok {
+			c.JSON(http.StatusOK, buildStatusResponse(statusProvider.Status()))
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"sync_running": false})
+	})
+}
+
+func buildStatusResponse(status poller.Status) statusResponse {
+	response := statusResponse{
+		Running:     status.Running,
+		SyncRunning: status.SyncRunning,
+		Timezone:    time.Local.String(),
+		LastError:   status.LastError,
+		LastWarning: status.LastWarning,
+		LastStatus:  status.LastStatus,
+	}
+	if !status.LastRunAt.IsZero() {
+		lastRunAt := status.LastRunAt.UTC()
+		response.LastRunAt = &lastRunAt
+	}
+	return response
+}

internal/api/router_test.go

@@ -0,0 +1,321 @@
+package api
+
+import (
+	"context"
+	"io/fs"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"cpa-usage-keeper/internal/poller"
+)
+
+func testStaticFS(t *testing.T, files map[string]string) fs.FS {
+	t.Helper()
+	staticFS := fstest.MapFS{}
+	for name, content := range files {
+		staticFS[name] = &fstest.MapFile{Data: []byte(content), Mode: 0o644}
+	}
+	return staticFS
+}
+
+type statusStub struct {
+	status poller.Status
+}
+
+type syncStatusStub struct {
+	status poller.Status
+	calls  int
+	err    error
+}
+
+type userFacingSyncError struct {
+	message string
+}
+
+func (e userFacingSyncError) Error() string {
+	return e.message
+}
+
+func (e userFacingSyncError) UserMessage() string {
+	return e.message
+}
+
+func (s statusStub) Status() poller.Status {
+	return s.status
+}
+
+func (s *syncStatusStub) Status() poller.Status {
+	return s.status
+}
+
+func (s *syncStatusStub) SyncNow(context.Context) error {
+	s.calls++
+	return s.err
+}
+
+func TestHealthzReturnsOK(t *testing.T) {
+	router := NewRouter(nil, nil, nil, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+}
+
+func TestStatusReturnsPollerState(t *testing.T) {
+	lastRunAt := time.Date(2026, 4, 16, 12, 0, 0, 0, time.UTC)
+	router := NewRouter(nil, statusStub{status: poller.Status{
+		Running:     true,
+		SyncRunning: false,
+		LastRunAt:   lastRunAt,
+		LastError:   "boom",
+		LastWarning: "metadata unavailable",
+		LastStatus:  "completed_with_warnings",
+	}}, nil, nil, AuthConfig{}, nil, "")
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/status", nil)
+	resp := httptest.NewRecorder()
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	body := resp.Body.String()
+	if !(contains(body, `"running":true`) && contains(body, `"sync_running":false`) && contains(body, `"last_error":"boom"`) && contains(body, `"last_warning":"metadata unavailable"`) && contains(body, `"last_status":"completed_with_warnings"`) && contains(body, `"last_run_at":"2026-04-16T12:00:00Z"`)) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+}
+
+func TestStatusReturnsProjectTimezone(t *testing.T) {
+	previousLocal := time.Local
+	location, err := time.LoadLocation("Asia/Shanghai")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	t.Cleanup(func() { time.Local = previousLocal })
+	time.Local = location
+
+	router := NewRouter(nil, nil, nil, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/status", nil)
+	resp := httptest.NewRecorder()
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	if body := resp.Body.String(); !contains(body, `"timezone":"Asia/Shanghai"`) {
+		t.Fatalf("expected status response to include project timezone, got %s", body)
+	}
+}
+
+func TestStatusReturnsEmptyStateWithoutProvider(t *testing.T) {
+	router := NewRouter(nil, nil, nil, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/status", nil)
+	resp := httptest.NewRecorder()
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	if body := resp.Body.String(); !contains(body, `"running":false`) || !contains(body, `"sync_running":false`) || !contains(body, `"timezone":`) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+}
+
+func TestManualSyncTriggersSyncRunner(t *testing.T) {
+	lastRunAt := time.Date(2026, 4, 16, 12, 0, 0, 0, time.UTC)
+	syncer := &syncStatusStub{status: poller.Status{Running: true, LastRunAt: lastRunAt, LastStatus: "completed"}}
+	router := NewRouter(nil, syncer, nil, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/sync", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	if syncer.calls != 1 {
+		t.Fatalf("expected sync runner to be called once, got %d", syncer.calls)
+	}
+	body := resp.Body.String()
+	if !(contains(body, `"last_status":"completed"`) && contains(body, `"last_run_at":"2026-04-16T12:00:00Z"`)) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+}
+
+func TestManualSyncReturnsConflictWhenAlreadyRunning(t *testing.T) {
+	syncer := &syncStatusStub{err: poller.ErrSyncAlreadyRunning}
+	router := NewRouter(nil, syncer, nil, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/sync", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusConflict {
+		t.Fatalf("expected status 409, got %d", resp.Code)
+	}
+}
+
+func TestManualSyncReturnsWarningsAsError(t *testing.T) {
+	syncer := &syncStatusStub{
+		status: poller.Status{LastStatus: "completed_with_warnings", LastWarning: "metadata unavailable"},
+		err:    poller.ErrSyncCompletedWithWarnings,
+	}
+	router := NewRouter(nil, syncer, nil, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/sync", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusInternalServerError {
+		t.Fatalf("expected status 500, got %d", resp.Code)
+	}
+	if body := resp.Body.String(); !contains(body, `"error":"manual sync failed"`) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+}
+
+func TestManualSyncReturnsUserFacingStageError(t *testing.T) {
+	syncer := &syncStatusStub{err: userFacingSyncError{message: "metadata sync failed"}}
+	router := NewRouter(nil, syncer, nil, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/sync", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusInternalServerError {
+		t.Fatalf("expected status 500, got %d", resp.Code)
+	}
+	if body := resp.Body.String(); !contains(body, `"error":"metadata sync failed"`) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+}
+
+func TestManualSyncRateLimitsRepeatedRequests(t *testing.T) {
+	syncer := &syncStatusStub{status: poller.Status{LastStatus: "completed"}}
+	router := NewRouter(nil, syncer, nil, nil, AuthConfig{}, nil, "")
+
+	firstResp := httptest.NewRecorder()
+	firstReq := httptest.NewRequest(http.MethodPost, "/api/v1/sync", nil)
+	router.ServeHTTP(firstResp, firstReq)
+	if firstResp.Code != http.StatusOK {
+		t.Fatalf("expected first sync to return 200, got %d", firstResp.Code)
+	}
+
+	secondResp := httptest.NewRecorder()
+	secondReq := httptest.NewRequest(http.MethodPost, "/api/v1/sync", nil)
+	router.ServeHTTP(secondResp, secondReq)
+	if secondResp.Code != http.StatusTooManyRequests {
+		t.Fatalf("expected second sync within one second to return 429, got %d", secondResp.Code)
+	}
+	if syncer.calls != 1 {
+		t.Fatalf("expected rate-limited sync not to call runner again, got %d calls", syncer.calls)
+	}
+}
+
+func TestSubpathRoutesOnlyServePrefixedEndpoints(t *testing.T) {
+	lastRunAt := time.Date(2026, 4, 16, 12, 0, 0, 0, time.UTC)
+	router := NewRouter(nil, statusStub{status: poller.Status{
+		Running:   true,
+		LastRunAt: lastRunAt,
+	}}, nil, nil, AuthConfig{BasePath: "/cpa"}, nil, "/cpa")
+
+	for _, testCase := range []struct {
+		path       string
+		statusCode int
+	}{
+		{path: "/cpa/healthz", statusCode: http.StatusOK},
+		{path: "/cpa/api/v1/status", statusCode: http.StatusOK},
+		{path: "/healthz", statusCode: http.StatusNotFound},
+		{path: "/api/v1/status", statusCode: http.StatusNotFound},
+	} {
+		resp := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, testCase.path, nil)
+		router.ServeHTTP(resp, req)
+		if resp.Code != testCase.statusCode {
+			t.Fatalf("expected %s to return %d, got %d", testCase.path, testCase.statusCode, resp.Code)
+		}
+	}
+}
+
+func TestSubpathStaticRoutesServeOnlyUnderPrefix(t *testing.T) {
+	staticFS := testStaticFS(t, map[string]string{
+		"index.html":    `<html><head><script>window.__APP_BASE_PATH__ = "__APP_BASE_PATH__";</script></head><body>app</body></html>`,
+		"assets/app.js": "console.log('ok')",
+	})
+
+	router := NewRouter(staticFS, nil, nil, nil, AuthConfig{BasePath: "/cpa"}, nil, "/cpa")
+
+	for _, testCase := range []struct {
+		path       string
+		statusCode int
+		contains   string
+	}{
+		{path: "/cpa/", statusCode: http.StatusOK, contains: `window.__APP_BASE_PATH__ = "/cpa";`},
+		{path: "/cpa/dashboard", statusCode: http.StatusOK, contains: `window.__APP_BASE_PATH__ = "/cpa";`},
+		{path: "/cpa/assets/app.js", statusCode: http.StatusOK, contains: "console.log('ok')"},
+		{path: "/cpa/missing.html", statusCode: http.StatusOK, contains: `window.__APP_BASE_PATH__ = "/cpa";`},
+		{path: "/foo", statusCode: http.StatusNotFound},
+		{path: "/assets/app.js", statusCode: http.StatusNotFound},
+		{path: "/cpa/api/unknown", statusCode: http.StatusNotFound},
+	} {
+		resp := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, testCase.path, nil)
+		router.ServeHTTP(resp, req)
+		if resp.Code != testCase.statusCode {
+			t.Fatalf("expected %s to return %d, got %d", testCase.path, testCase.statusCode, resp.Code)
+		}
+		if testCase.contains != "" && !contains(resp.Body.String(), testCase.contains) {
+			t.Fatalf("expected %s response to contain %q, got %s", testCase.path, testCase.contains, resp.Body.String())
+		}
+	}
+}
+
+func TestCleanURLPathUsesSlashSemantics(t *testing.T) {
+	if cleaned := cleanURLPath("/cpa//dashboard/../assets/app.js"); cleaned != "/cpa/assets/app.js" {
+		t.Fatalf("expected slash-normalized URL path, got %q", cleaned)
+	}
+}
+
+func TestStaticAssetPathRejectsBackslashTraversal(t *testing.T) {
+	if _, ok := staticAssetPath(`/..\.env`); ok {
+		t.Fatal("expected backslash traversal path to be rejected")
+	}
+}
+
+func TestRootStaticRouteInjectsEmptyBasePath(t *testing.T) {
+	staticFS := testStaticFS(t, map[string]string{
+		"index.html": `<html><head><script>window.__APP_BASE_PATH__ = "__APP_BASE_PATH__";</script></head><body>app</body></html>`,
+	})
+
+	router := NewRouter(staticFS, nil, nil, nil, AuthConfig{}, nil, "")
+	resp := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	if !contains(resp.Body.String(), `window.__APP_BASE_PATH__ = "";`) {
+		t.Fatalf("expected injected empty base path, got %s", resp.Body.String())
+	}
+}
+
+func contains(s, sub string) bool {
+	return len(sub) == 0 || (len(s) >= len(sub) && (func() bool { return stringContains(s, sub) })())
+}
+
+func stringContains(s, sub string) bool {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}

internal/api/usage_analysis.go

@@ -0,0 +1,126 @@
+package api
+
+import (
+	"net/http"
+	"time"
+
+	"cpa-usage-keeper/internal/redact"
+	"cpa-usage-keeper/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type usageAnalysisResponse struct {
+	APIs   []usageAnalysisAPIPayload   `json:"apis"`
+	Models []usageAnalysisModelPayload `json:"models"`
+}
+
+type usageAnalysisAPIPayload struct {
+	APIKey          string                      `json:"api_key"`
+	DisplayName     string                      `json:"display_name"`
+	TotalRequests   int64                       `json:"total_requests"`
+	SuccessCount    int64                       `json:"success_count"`
+	FailureCount    int64                       `json:"failure_count"`
+	InputTokens     int64                       `json:"input_tokens"`
+	OutputTokens    int64                       `json:"output_tokens"`
+	ReasoningTokens int64                       `json:"reasoning_tokens"`
+	CachedTokens    int64                       `json:"cached_tokens"`
+	TotalTokens     int64                       `json:"total_tokens"`
+	Models          []usageAnalysisModelPayload `json:"models"`
+}
+
+type usageAnalysisModelPayload struct {
+	Model              string `json:"model"`
+	TotalRequests      int64  `json:"total_requests"`
+	SuccessCount       int64  `json:"success_count"`
+	FailureCount       int64  `json:"failure_count"`
+	InputTokens        int64  `json:"input_tokens"`
+	OutputTokens       int64  `json:"output_tokens"`
+	ReasoningTokens    int64  `json:"reasoning_tokens"`
+	CachedTokens       int64  `json:"cached_tokens"`
+	TotalTokens        int64  `json:"total_tokens"`
+	TotalLatencyMS     int64  `json:"total_latency_ms"`
+	LatencySampleCount int64  `json:"latency_sample_count"`
+}
+
+func registerUsageAnalysisRoute(router gin.IRoutes, usageProvider service.UsageProvider) {
+	router.GET("/usage/analysis", func(c *gin.Context) {
+		if usageProvider == nil {
+			c.JSON(http.StatusOK, usageAnalysisResponse{APIs: []usageAnalysisAPIPayload{}, Models: []usageAnalysisModelPayload{}})
+			return
+		}
+
+		filter, err := parseUsageFilterQuery(c.Request, time.Now().UTC())
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+
+		analysis, err := usageProvider.GetUsageAnalysis(c.Request.Context(), filter)
+		if err != nil {
+			writeInternalError(c, "get usage analysis failed", err)
+			return
+		}
+
+		c.JSON(http.StatusOK, buildUsageAnalysisPayload(analysis))
+	})
+}
+
+func buildUsageAnalysisPayload(snapshot *service.UsageAnalysisSnapshot) usageAnalysisResponse {
+	if snapshot == nil {
+		return usageAnalysisResponse{APIs: []usageAnalysisAPIPayload{}, Models: []usageAnalysisModelPayload{}}
+	}
+
+	apis := make([]usageAnalysisAPIPayload, 0, len(snapshot.APIs))
+	for _, api := range snapshot.APIs {
+		models := make([]usageAnalysisModelPayload, 0, len(api.Models))
+		for _, model := range api.Models {
+			models = append(models, usageAnalysisModelPayload{
+				Model:              model.Model,
+				TotalRequests:      model.TotalRequests,
+				SuccessCount:       model.SuccessCount,
+				FailureCount:       model.FailureCount,
+				InputTokens:        model.InputTokens,
+				OutputTokens:       model.OutputTokens,
+				ReasoningTokens:    model.ReasoningTokens,
+				CachedTokens:       model.CachedTokens,
+				TotalTokens:        model.TotalTokens,
+				TotalLatencyMS:     model.TotalLatencyMS,
+				LatencySampleCount: model.LatencySampleCount,
+			})
+		}
+		apiKey := redact.APIAlias(api.APIKey)
+		displayName := redact.APIKeyDisplayName(api.APIKey)
+		apis = append(apis, usageAnalysisAPIPayload{
+			APIKey:          apiKey,
+			DisplayName:     displayName,
+			TotalRequests:   api.TotalRequests,
+			SuccessCount:    api.SuccessCount,
+			FailureCount:    api.FailureCount,
+			InputTokens:     api.InputTokens,
+			OutputTokens:    api.OutputTokens,
+			ReasoningTokens: api.ReasoningTokens,
+			CachedTokens:    api.CachedTokens,
+			TotalTokens:     api.TotalTokens,
+			Models:          models,
+		})
+	}
+
+	models := make([]usageAnalysisModelPayload, 0, len(snapshot.Models))
+	for _, model := range snapshot.Models {
+		models = append(models, usageAnalysisModelPayload{
+			Model:              model.Model,
+			TotalRequests:      model.TotalRequests,
+			SuccessCount:       model.SuccessCount,
+			FailureCount:       model.FailureCount,
+			InputTokens:        model.InputTokens,
+			OutputTokens:       model.OutputTokens,
+			ReasoningTokens:    model.ReasoningTokens,
+			CachedTokens:       model.CachedTokens,
+			TotalTokens:        model.TotalTokens,
+			TotalLatencyMS:     model.TotalLatencyMS,
+			LatencySampleCount: model.LatencySampleCount,
+		})
+	}
+
+	return usageAnalysisResponse{APIs: apis, Models: models}
+}

internal/api/usage_analysis_test.go

@@ -0,0 +1,128 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"cpa-usage-keeper/internal/cpa"
+	"cpa-usage-keeper/internal/redact"
+	"cpa-usage-keeper/internal/service"
+)
+
+type usageAnalysisStub struct {
+	analysis      *service.UsageAnalysisSnapshot
+	err           error
+	lastFilter    service.UsageFilter
+	analysisCalls int
+}
+
+func (s *usageAnalysisStub) GetUsageWithFilter(context.Context, service.UsageFilter) (*cpa.StatisticsSnapshot, error) {
+	return nil, nil
+}
+
+func (s *usageAnalysisStub) GetUsageOverview(context.Context, service.UsageFilter) (*service.UsageOverviewSnapshot, error) {
+	return nil, nil
+}
+
+func (s *usageAnalysisStub) ListUsageEvents(context.Context, service.UsageFilter) (*service.UsageEventsPage, error) {
+	return nil, nil
+}
+
+func (s *usageAnalysisStub) ListUsageEventFilterOptions(context.Context, service.UsageFilter) (*service.UsageEventFilterOptions, error) {
+	return nil, nil
+}
+
+func (s *usageAnalysisStub) ListUsageCredentialStats(context.Context, service.UsageFilter) ([]service.UsageCredentialStat, error) {
+	return nil, nil
+}
+
+func (s *usageAnalysisStub) GetUsageAnalysis(_ context.Context, filter service.UsageFilter) (*service.UsageAnalysisSnapshot, error) {
+	s.lastFilter = filter
+	s.analysisCalls++
+	return s.analysis, s.err
+}
+
+func TestUsageAnalysisReturnsAggregatedRows(t *testing.T) {
+	provider := &usageAnalysisStub{analysis: &service.UsageAnalysisSnapshot{
+		APIs: []service.UsageAnalysisAPIStat{{
+			APIKey:        "provider-a",
+			DisplayName:   "provider-a",
+			TotalRequests: 2,
+			SuccessCount:  1,
+			FailureCount:  1,
+			TotalTokens:   42,
+			Models: []service.UsageAnalysisModelStat{{
+				Model:              "claude-sonnet",
+				TotalRequests:      2,
+				SuccessCount:       1,
+				FailureCount:       1,
+				InputTokens:        30,
+				OutputTokens:       9,
+				ReasoningTokens:    2,
+				CachedTokens:       1,
+				TotalTokens:        42,
+				TotalLatencyMS:     350,
+				LatencySampleCount: 2,
+			}},
+		}},
+		Models: []service.UsageAnalysisModelStat{{
+			Model:              "claude-sonnet",
+			TotalRequests:      2,
+			SuccessCount:       1,
+			FailureCount:       1,
+			InputTokens:        30,
+			OutputTokens:       9,
+			ReasoningTokens:    2,
+			CachedTokens:       1,
+			TotalTokens:        42,
+			TotalLatencyMS:     350,
+			LatencySampleCount: 2,
+		}},
+	}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/analysis?range=24h", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	body := resp.Body.String()
+	if !contains(body, `"apis":[`) || !contains(body, `"models":[`) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+	if !contains(body, `"display_name":"prov**er-a"`) {
+		t.Fatalf("expected display name in response body: %s", body)
+	}
+	if !contains(body, `"api_key":"`+redact.APIAlias("provider-a")+`"`) {
+		t.Fatalf("expected redacted api key alias in response body: %s", body)
+	}
+	if !contains(body, `"model":"claude-sonnet"`) || !contains(body, `"latency_sample_count":2`) || !contains(body, `"total_latency_ms":350`) {
+		t.Fatalf("expected model latency aggregates in response body: %s", body)
+	}
+	if provider.analysisCalls != 1 {
+		t.Fatalf("expected GetUsageAnalysis to be called once, got %d", provider.analysisCalls)
+	}
+	if provider.lastFilter.Range != "24h" {
+		t.Fatalf("expected range to be passed through, got %+v", provider.lastFilter)
+	}
+	if provider.lastFilter.StartTime == nil || provider.lastFilter.EndTime == nil {
+		t.Fatalf("expected resolved time bounds in filter, got %+v", provider.lastFilter)
+	}
+}
+
+func TestUsageAnalysisRequiresAuthWhenEnabled(t *testing.T) {
+	router := NewRouter(nil, nil, &usageAnalysisStub{}, nil, AuthConfig{Enabled: true, LoginPassword: "secret", SessionTTL: time.Hour}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/analysis", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusUnauthorized {
+		t.Fatalf("expected status 401, got %d", resp.Code)
+	}
+}

internal/api/usage_credentials.go

@@ -0,0 +1,93 @@
+package api
+
+import (
+	"net/http"
+	"time"
+
+	"cpa-usage-keeper/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type usageCredentialsResponse struct {
+	Credentials []usageCredentialPayload `json:"credentials"`
+}
+
+type usageCredentialPayload struct {
+	Source       string `json:"source"`
+	SourceType   string `json:"source_type,omitempty"`
+	SourceKey    string `json:"source_key,omitempty"`
+	SuccessCount int64  `json:"success_count"`
+	FailureCount int64  `json:"failure_count"`
+	TotalCount   int64  `json:"total_count"`
+}
+
+func registerUsageCredentialsRoute(
+	router gin.IRoutes,
+	usageProvider service.UsageProvider,
+	usageIdentityProvider service.UsageIdentityProvider,
+) {
+	router.GET("/usage/credentials", func(c *gin.Context) {
+		if usageProvider == nil {
+			c.JSON(http.StatusOK, usageCredentialsResponse{Credentials: []usageCredentialPayload{}})
+			return
+		}
+
+		filter, err := parseUsageFilterQuery(c.Request, time.Now().UTC())
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+
+		rows, err := usageProvider.ListUsageCredentialStats(c.Request.Context(), filter)
+		if err != nil {
+			writeInternalError(c, "list usage credential stats failed", err)
+			return
+		}
+
+		identities, err := loadUsageResolutionData(c, usageIdentityProvider)
+		if err != nil {
+			writeInternalError(c, "load usage resolution data failed", err)
+			return
+		}
+		resolver := newUsageSourceResolver(identities)
+		c.JSON(http.StatusOK, usageCredentialsResponse{Credentials: buildUsageCredentialsPayload(rows, resolver)})
+	})
+}
+
+func buildUsageCredentialsPayload(rows []service.UsageCredentialStat, resolver usageSourceResolver) []usageCredentialPayload {
+	if len(rows) == 0 {
+		return []usageCredentialPayload{}
+	}
+
+	buckets := make(map[string]*usageCredentialPayload, len(rows))
+	orderedKeys := make([]string, 0, len(rows))
+	for _, row := range rows {
+		resolved := resolver.resolve(row.Source, row.AuthIndex)
+		bucketKey := resolved.SourceKey
+		if bucketKey == "" {
+			bucketKey = resolved.DisplayName
+		}
+		payload, ok := buckets[bucketKey]
+		if !ok {
+			payload = &usageCredentialPayload{
+				Source:     resolved.DisplayName,
+				SourceType: resolved.SourceType,
+				SourceKey:  resolved.SourceKey,
+			}
+			buckets[bucketKey] = payload
+			orderedKeys = append(orderedKeys, bucketKey)
+		}
+		if row.Failed {
+			payload.FailureCount += row.RequestCount
+		} else {
+			payload.SuccessCount += row.RequestCount
+		}
+		payload.TotalCount = payload.SuccessCount + payload.FailureCount
+	}
+
+	result := make([]usageCredentialPayload, 0, len(orderedKeys))
+	for _, key := range orderedKeys {
+		result = append(result, *buckets[key])
+	}
+	return result
+}

internal/api/usage_events.go

@@ -0,0 +1,245 @@
+package api
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"cpa-usage-keeper/internal/models"
+	"cpa-usage-keeper/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type usageEventsResponse struct {
+	Events     []usageEventPayload       `json:"events"`
+	Models     []string                  `json:"models"`
+	Sources    []usageSourceFilterOption `json:"sources"`
+	TotalCount int64                     `json:"total_count"`
+	Page       int                       `json:"page"`
+	PageSize   int                       `json:"page_size"`
+	TotalPages int                       `json:"total_pages"`
+}
+
+type usageSourceFilterOption struct {
+	Value string `json:"value"`
+	Label string `json:"label"`
+}
+
+type usageEventFilterOptionsResponse struct {
+	Models  []string                  `json:"models"`
+	Sources []usageSourceFilterOption `json:"sources"`
+}
+
+type usageEventPayload struct {
+	ID         uint                   `json:"id,omitempty"`
+	Timestamp  string                 `json:"timestamp"`
+	Model      string                 `json:"model"`
+	Source     string                 `json:"source"`
+	SourceRaw  string                 `json:"source_raw,omitempty"`
+	SourceType string                 `json:"source_type,omitempty"`
+	SourceKey  string                 `json:"source_key,omitempty"`
+	AuthIndex  string                 `json:"auth_index,omitempty"`
+	Failed     bool                   `json:"failed"`
+	LatencyMS  int64                  `json:"latency_ms"`
+	Tokens     usageEventTokenPayload `json:"tokens"`
+}
+
+type usageEventTokenPayload struct {
+	InputTokens     int64 `json:"input_tokens"`
+	OutputTokens    int64 `json:"output_tokens"`
+	ReasoningTokens int64 `json:"reasoning_tokens"`
+	CachedTokens    int64 `json:"cached_tokens"`
+	TotalTokens     int64 `json:"total_tokens"`
+}
+
+func registerUsageEventsRoute(
+	router gin.IRoutes,
+	usageProvider service.UsageProvider,
+	usageIdentityProvider service.UsageIdentityProvider,
+) {
+	router.GET("/usage/events/filters", func(c *gin.Context) {
+		if usageProvider == nil {
+			c.JSON(http.StatusOK, usageEventFilterOptionsResponse{Models: []string{}, Sources: []usageSourceFilterOption{}})
+			return
+		}
+
+		options, err := usageProvider.ListUsageEventFilterOptions(c.Request.Context(), service.UsageFilter{})
+		if err != nil {
+			writeInternalError(c, "list usage event filter options failed", err)
+			return
+		}
+
+		identities, err := loadUsageResolutionData(c, usageIdentityProvider)
+		if err != nil {
+			writeInternalError(c, "load usage resolution data failed", err)
+			return
+		}
+		c.JSON(http.StatusOK, usageEventFilterOptionsResponse{
+			Models:  options.Models,
+			Sources: buildUsageSourceFilterOptions(options.Sources, identities),
+		})
+	})
+
+	router.GET("/usage/events", func(c *gin.Context) {
+		if usageProvider == nil {
+			c.JSON(http.StatusOK, usageEventsResponse{Events: []usageEventPayload{}, Models: []string{}, Sources: []usageSourceFilterOption{}, Page: 1, PageSize: service.DefaultUsageEventsLimit})
+			return
+		}
+
+		filter, err := parseUsageFilterQuery(c.Request, time.Now().UTC())
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		if err := applyUsageEventsSourceFilter(&filter); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+
+		rows, err := usageProvider.ListUsageEvents(c.Request.Context(), filter)
+		if err != nil {
+			writeInternalError(c, "list usage events failed", err)
+			return
+		}
+
+		identities, err := loadUsageResolutionData(c, usageIdentityProvider)
+		if err != nil {
+			writeInternalError(c, "load usage resolution data failed", err)
+			return
+		}
+		c.JSON(http.StatusOK, usageEventsResponse{
+			Events:     buildUsageEventsPayload(rows.Events),
+			Models:     rows.Models,
+			Sources:    buildUsageSourceFilterOptions(rows.Sources, identities),
+			TotalCount: rows.TotalCount,
+			Page:       rows.Page,
+			PageSize:   rows.PageSize,
+			TotalPages: rows.TotalPages,
+		})
+	})
+}
+
+func applyUsageEventsSourceFilter(filter *service.UsageFilter) error {
+	if filter == nil {
+		return nil
+	}
+	source := strings.TrimSpace(filter.Source)
+	if source == "" {
+		return nil
+	}
+	if value, ok := strings.CutPrefix(source, "auth:"); ok {
+		value = strings.TrimSpace(value)
+		if value == "" {
+			return fmt.Errorf("source auth filter value is required")
+		}
+		filter.AuthType = "oauth"
+		filter.AuthIndex = value
+		filter.Source = value
+		filter.Provider = ""
+		return nil
+	}
+	if value, ok := strings.CutPrefix(source, "provider:"); ok {
+		value = strings.TrimSpace(value)
+		if value == "" {
+			return fmt.Errorf("source provider filter value is required")
+		}
+		filter.AuthType = "apikey"
+		filter.Provider = value
+		filter.Source = ""
+		filter.AuthIndex = ""
+	}
+	return nil
+}
+
+func buildUsageEventsPayload(rows []service.UsageEventRecord) []usageEventPayload {
+	if len(rows) == 0 {
+		return []usageEventPayload{}
+	}
+	payload := make([]usageEventPayload, 0, len(rows))
+	for _, row := range rows {
+		source, sourceKey := usageEventPublicSource(row)
+		payload = append(payload, usageEventPayload{
+			ID:        row.ID,
+			Timestamp: row.Timestamp.UTC().Format(time.RFC3339),
+			Model:     row.Model,
+			Source:    source,
+			SourceKey: sourceKey,
+			AuthIndex: row.AuthIndex,
+			Failed:    row.Failed,
+			LatencyMS: row.LatencyMS,
+			Tokens: usageEventTokenPayload{
+				InputTokens:     row.InputTokens,
+				OutputTokens:    row.OutputTokens,
+				ReasoningTokens: row.ReasoningTokens,
+				CachedTokens:    row.CachedTokens,
+				TotalTokens:     row.TotalTokens,
+			},
+		})
+	}
+	return payload
+}
+
+func usageEventPublicSource(row service.UsageEventRecord) (string, string) {
+	switch strings.TrimSpace(row.AuthType) {
+	case "apikey":
+		provider := strings.TrimSpace(row.Provider)
+		if provider == "" {
+			provider = "AI Provider"
+		}
+		return provider, "provider:" + provider
+	case "oauth":
+		source := firstNonEmptyString(row.Source, row.AuthIndex, "unknown")
+		return source, "auth:" + source
+	default:
+		if provider := strings.TrimSpace(row.Provider); provider != "" {
+			return provider, "provider:" + provider
+		}
+		source := firstNonEmptyString(row.Source, row.AuthIndex, "unknown")
+		return source, "auth:" + source
+	}
+}
+
+func buildUsageSourceFilterOptions(sources []string, identities []models.UsageIdentity) []usageSourceFilterOption {
+	if len(identities) == 0 {
+		return []usageSourceFilterOption{}
+	}
+	options := make([]usageSourceFilterOption, 0, len(identities))
+	seen := make(map[string]struct{}, len(identities))
+	for _, identity := range identities {
+		if identity.TotalRequests == 0 {
+			continue
+		}
+		option, ok := usageSourceFilterOptionFromIdentity(identity)
+		if !ok {
+			continue
+		}
+		if _, exists := seen[option.Value]; exists {
+			continue
+		}
+		seen[option.Value] = struct{}{}
+		options = append(options, option)
+	}
+	return options
+}
+
+func usageSourceFilterOptionFromIdentity(identity models.UsageIdentity) (usageSourceFilterOption, bool) {
+	switch identity.AuthType {
+	case models.UsageIdentityAuthTypeAuthFile:
+		value := strings.TrimSpace(identity.Identity)
+		if value == "" {
+			return usageSourceFilterOption{}, false
+		}
+		label := firstNonEmptyString(identity.Name, value)
+		return usageSourceFilterOption{Value: "auth:" + value, Label: label}, true
+	case models.UsageIdentityAuthTypeAIProvider:
+		provider := safeAIProviderDisplayValue(identity.Provider, identity.Identity, "")
+		label := firstNonEmptyString(provider, safeAIProviderDisplayValue(identity.Name, identity.Identity, ""), safeAIProviderDisplayValue(identity.Type, identity.Identity, ""))
+		if label == "" {
+			return usageSourceFilterOption{}, false
+		}
+		return usageSourceFilterOption{Value: "provider:" + label, Label: label}, true
+	default:
+		return usageSourceFilterOption{}, false
+	}
+}

internal/api/usage_events_test.go

@@ -0,0 +1,295 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"cpa-usage-keeper/internal/cpa"
+	"cpa-usage-keeper/internal/models"
+	"cpa-usage-keeper/internal/service"
+)
+
+type usageEventsStub struct {
+	events             []service.UsageEventRecord
+	eventsPage         *service.UsageEventsPage
+	eventFilterOptions *service.UsageEventFilterOptions
+	credentialStats    []service.UsageCredentialStat
+	err                error
+	lastFilter         service.UsageFilter
+	filterCalls        int
+	filterOptionCalls  int
+	credentialsCalls   int
+}
+
+func (s *usageEventsStub) GetUsageWithFilter(context.Context, service.UsageFilter) (*cpa.StatisticsSnapshot, error) {
+	return nil, nil
+}
+
+func (s *usageEventsStub) GetUsageOverview(context.Context, service.UsageFilter) (*service.UsageOverviewSnapshot, error) {
+	return nil, nil
+}
+
+func (s *usageEventsStub) ListUsageEvents(_ context.Context, filter service.UsageFilter) (*service.UsageEventsPage, error) {
+	s.lastFilter = filter
+	s.filterCalls++
+	if s.eventsPage != nil {
+		return s.eventsPage, s.err
+	}
+	return &service.UsageEventsPage{Events: s.events, TotalCount: int64(len(s.events)), Page: 1, PageSize: service.DefaultUsageEventsLimit, TotalPages: 1}, s.err
+}
+
+func (s *usageEventsStub) ListUsageEventFilterOptions(_ context.Context, filter service.UsageFilter) (*service.UsageEventFilterOptions, error) {
+	s.lastFilter = filter
+	s.filterOptionCalls++
+	if s.eventFilterOptions != nil {
+		return s.eventFilterOptions, s.err
+	}
+	return &service.UsageEventFilterOptions{}, s.err
+}
+
+func (s *usageEventsStub) ListUsageCredentialStats(_ context.Context, filter service.UsageFilter) ([]service.UsageCredentialStat, error) {
+	s.lastFilter = filter
+	s.credentialsCalls++
+	return s.credentialStats, s.err
+}
+
+func (s *usageEventsStub) GetUsageAnalysis(context.Context, service.UsageFilter) (*service.UsageAnalysisSnapshot, error) {
+	return nil, s.err
+}
+
+func TestUsageEventsReturnsFilteredRows(t *testing.T) {
+	provider := &usageEventsStub{events: []service.UsageEventRecord{{
+		ID:              42,
+		Timestamp:       time.Date(2026, 4, 22, 11, 0, 0, 0, time.UTC),
+		Model:           "claude-sonnet",
+		AuthType:        "apikey",
+		Provider:        "OpenAI Mirror",
+		Source:          "sk-provider-key",
+		AuthIndex:       "2",
+		Failed:          false,
+		LatencyMS:       321,
+		InputTokens:     10,
+		OutputTokens:    5,
+		ReasoningTokens: 2,
+		CachedTokens:    1,
+		TotalTokens:     18,
+	}}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/events?range=24h", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	body := resp.Body.String()
+	if !contains(body, `"events":[`) || !contains(body, `"model":"claude-sonnet"`) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+	if !contains(body, `"id":42`) || !contains(body, `"total_count":1`) || !contains(body, `"page":1`) || !contains(body, `"page_size":100`) || !contains(body, `"total_pages":1`) {
+		t.Fatalf("expected pagination metadata and event id in response body: %s", body)
+	}
+	if !contains(body, `"source":"OpenAI Mirror"`) {
+		t.Fatalf("expected resolved source display in response body: %s", body)
+	}
+	if contains(body, `sk-provider-key`) || contains(body, `sk-provider-prefix`) {
+		t.Fatalf("expected raw source values to be redacted from response body: %s", body)
+	}
+	if contains(body, `"source_type"`) || !contains(body, `"source_key":"provider:OpenAI Mirror"`) {
+		t.Fatalf("expected provider source key from usage event provider only, got %s", body)
+	}
+	if !contains(body, `"auth_index":"2"`) {
+		t.Fatalf("expected auth index in response body: %s", body)
+	}
+	if provider.filterCalls != 1 {
+		t.Fatalf("expected ListUsageEvents to be called once, got %d", provider.filterCalls)
+	}
+	if provider.lastFilter.Range != "24h" {
+		t.Fatalf("expected range to be passed through, got %+v", provider.lastFilter)
+	}
+	if provider.lastFilter.Page != 1 || provider.lastFilter.PageSize != 100 || provider.lastFilter.Offset != 0 {
+		t.Fatalf("expected default pagination to be passed through, got %+v", provider.lastFilter)
+	}
+	if provider.lastFilter.StartTime == nil || provider.lastFilter.EndTime == nil {
+		t.Fatalf("expected resolved time bounds in filter, got %+v", provider.lastFilter)
+	}
+}
+
+func TestUsageEventsPassesPaginationAndProviderSourceFilter(t *testing.T) {
+	provider := &usageEventsStub{eventsPage: &service.UsageEventsPage{Events: []service.UsageEventRecord{}, TotalCount: 0, Page: 3, PageSize: 100, TotalPages: 0}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/events?page=3&page_size=100&model=claude-sonnet&source=provider:OpenAI%20Mirror&result=failed", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	if provider.lastFilter.Page != 3 || provider.lastFilter.PageSize != 100 || provider.lastFilter.Offset != 200 {
+		t.Fatalf("expected pagination filter, got %+v", provider.lastFilter)
+	}
+	if provider.lastFilter.Model != "claude-sonnet" || provider.lastFilter.AuthType != "apikey" || provider.lastFilter.Provider != "OpenAI Mirror" || provider.lastFilter.Source != "" || provider.lastFilter.Result != "failed" {
+		t.Fatalf("expected provider source filter to be translated, got %+v", provider.lastFilter)
+	}
+	body := resp.Body.String()
+	if !contains(body, `"page":3`) || !contains(body, `"page_size":100`) || !contains(body, `"total_count":0`) || !contains(body, `"total_pages":0`) {
+		t.Fatalf("expected response pagination metadata, got %s", body)
+	}
+}
+
+func TestUsageEventsPassesAuthSourceFilter(t *testing.T) {
+	provider := &usageEventsStub{eventsPage: &service.UsageEventsPage{Events: []service.UsageEventRecord{}, TotalCount: 0, Page: 1, PageSize: 100, TotalPages: 0}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/events?source=auth:2", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	if provider.lastFilter.AuthType != "oauth" || provider.lastFilter.AuthIndex != "2" || provider.lastFilter.Source != "2" {
+		t.Fatalf("expected auth source filter to be translated, got %+v", provider.lastFilter)
+	}
+}
+
+func TestUsageEventsRejectsEmptyPrefixedSourceFilter(t *testing.T) {
+	for _, path := range []string{"/api/v1/usage/events?source=auth:", "/api/v1/usage/events?source=provider:"} {
+		t.Run(path, func(t *testing.T) {
+			provider := &usageEventsStub{eventsPage: &service.UsageEventsPage{Events: []service.UsageEventRecord{}, TotalCount: 0, Page: 1, PageSize: 100, TotalPages: 0}}
+			router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "")
+			req := httptest.NewRequest(http.MethodGet, path, nil)
+			resp := httptest.NewRecorder()
+
+			router.ServeHTTP(resp, req)
+
+			if resp.Code != http.StatusBadRequest {
+				t.Fatalf("expected status 400, got %d with body %s", resp.Code, resp.Body.String())
+			}
+			if provider.filterCalls != 0 {
+				t.Fatalf("expected invalid source filter not to query events, got %d calls", provider.filterCalls)
+			}
+		})
+	}
+}
+
+func TestUsageEventsReturnsFilterOptions(t *testing.T) {
+	provider := &usageEventsStub{eventsPage: &service.UsageEventsPage{
+		Events: []service.UsageEventRecord{{
+			ID: 7, Timestamp: time.Date(2026, 4, 22, 11, 0, 0, 0, time.UTC), Model: "gpt-5", AuthType: "apikey", Provider: "Provider A", Source: "source-a", Failed: true,
+		}},
+		Models:     []string{"claude-sonnet", "gpt-5"},
+		Sources:    []string{"source-a", "source-b"},
+		TotalCount: 2, Page: 1, PageSize: 20, TotalPages: 1,
+	}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "", usageIdentitiesStub{items: []models.UsageIdentity{{ID: 1, Name: "sk-source-prefix", AuthType: models.UsageIdentityAuthTypeAIProvider, AuthTypeName: "apikey", Identity: "source-a", Type: "openai", Provider: "Provider A", TotalRequests: 1}, {ID: 2, Name: "Provider A", AuthType: models.UsageIdentityAuthTypeAIProvider, AuthTypeName: "apikey", Identity: "source-b", Type: "openai", Provider: "Provider A", TotalRequests: 1}, {ID: 3, Name: "Auth User", AuthType: models.UsageIdentityAuthTypeAuthFile, AuthTypeName: "oauth", Identity: "auth-1", Type: "claude", Provider: "Claude", TotalRequests: 1}}})
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/events", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	body := resp.Body.String()
+	if !contains(body, `"models":["claude-sonnet","gpt-5"]`) {
+		t.Fatalf("expected model filter options, got %s", body)
+	}
+	if !contains(body, `"sources":[`) || !contains(body, `"value":"auth:auth-1"`) || !contains(body, `"label":"Auth User"`) || !contains(body, `"value":"provider:Provider A"`) || !contains(body, `"label":"Provider A"`) {
+		t.Fatalf("expected prefixed source filter options, got %s", body)
+	}
+	if contains(body, `"value":"source-a"`) || contains(body, `"value":"source-b"`) || contains(body, `"provider:1"`) || contains(body, `"provider:2"`) || contains(body, `sk-source-prefix`) {
+		t.Fatalf("expected raw source filter values to be redacted, got %s", body)
+	}
+}
+
+func TestUsageEventFilterOptionsReturnsStableModelsAndSources(t *testing.T) {
+	provider := &usageEventsStub{eventFilterOptions: &service.UsageEventFilterOptions{
+		Models:  []string{"claude-sonnet", "gpt-5"},
+		Sources: []string{"source-a", "source-b"},
+	}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "", usageIdentitiesStub{items: []models.UsageIdentity{{ID: 1, Name: "sk-source-prefix", AuthType: models.UsageIdentityAuthTypeAIProvider, AuthTypeName: "apikey", Identity: "source-a", Type: "openai", Provider: "Provider A", TotalRequests: 3}, {ID: 2, Name: "Provider A", AuthType: models.UsageIdentityAuthTypeAIProvider, AuthTypeName: "apikey", Identity: "source-b", Type: "openai", Provider: "Provider A"}, {ID: 3, Name: "Auth User", AuthType: models.UsageIdentityAuthTypeAuthFile, AuthTypeName: "oauth", Identity: "auth-1", Type: "claude", Provider: "Claude", TotalRequests: 2}, {ID: 4, Name: "Zero Request User", AuthType: models.UsageIdentityAuthTypeAuthFile, AuthTypeName: "oauth", Identity: "auth-zero", Type: "claude", Provider: "Claude"}, {ID: 5, Name: "Zero Provider", AuthType: models.UsageIdentityAuthTypeAIProvider, AuthTypeName: "apikey", Identity: "source-zero", Type: "openai", Provider: "Zero Provider"}}})
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/events/filters?range=24h&model=ignored&source=ignored&result=failed&page=3&page_size=20", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	if provider.filterOptionCalls != 1 || provider.filterCalls != 0 {
+		t.Fatalf("expected filter options endpoint only, events=%d filterOptions=%d", provider.filterCalls, provider.filterOptionCalls)
+	}
+	if provider.lastFilter.Range != "" || provider.lastFilter.StartTime != nil || provider.lastFilter.EndTime != nil || provider.lastFilter.Model != "" || provider.lastFilter.Source != "" || provider.lastFilter.Result != "" || provider.lastFilter.Page != 0 || provider.lastFilter.PageSize != 0 {
+		t.Fatalf("expected filters endpoint to ignore query filters, got %+v", provider.lastFilter)
+	}
+	body := resp.Body.String()
+	if !contains(body, `"models":["claude-sonnet","gpt-5"]`) {
+		t.Fatalf("expected stable model filter options, got %s", body)
+	}
+	if !contains(body, `"sources":[`) || !contains(body, `"value":"auth:auth-1"`) || !contains(body, `"label":"Auth User"`) || !contains(body, `"value":"provider:Provider A"`) || !contains(body, `"label":"Provider A"`) {
+		t.Fatalf("expected stable prefixed source filter options, got %s", body)
+	}
+	if contains(body, `"value":"source-a"`) || contains(body, `"value":"source-b"`) || contains(body, `"provider:1"`) || contains(body, `"provider:2"`) || contains(body, `sk-source-prefix`) {
+		t.Fatalf("expected raw source filter values to be redacted, got %s", body)
+	}
+	if contains(body, `Zero Request User`) || contains(body, `Zero Provider`) || contains(body, `auth-zero`) || contains(body, `source-zero`) {
+		t.Fatalf("expected zero-request source filter options to be omitted, got %s", body)
+	}
+}
+
+func TestUsageCredentialsReturnsAggregatedRows(t *testing.T) {
+	provider := &usageEventsStub{credentialStats: []service.UsageCredentialStat{{
+		Source:       "sk-provider-key",
+		AuthIndex:    "2",
+		Failed:       false,
+		RequestCount: 3,
+	}, {
+		Source:       "sk-provider-key",
+		AuthIndex:    "2",
+		Failed:       true,
+		RequestCount: 1,
+	}}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "", usageIdentitiesStub{items: []models.UsageIdentity{{ID: 1, Name: "sk-provider-prefix", AuthType: models.UsageIdentityAuthTypeAIProvider, AuthTypeName: "apikey", Identity: "sk-provider-key", Type: "openai", Provider: "OpenAI Mirror"}}})
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/credentials?range=24h", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	body := resp.Body.String()
+	if !contains(body, `"credentials":[`) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+	if !contains(body, `"source":"OpenAI Mirror"`) {
+		t.Fatalf("expected resolved source display in response body: %s", body)
+	}
+	if !contains(body, `"source_type":"openai"`) {
+		t.Fatalf("expected source type in response body: %s", body)
+	}
+	if !contains(body, `"source_key":"provider:1"`) {
+		t.Fatalf("expected source key in response body: %s", body)
+	}
+	if contains(body, `sk-provider-key`) || contains(body, `sk-provider-prefix`) {
+		t.Fatalf("expected raw source values to be redacted from response body: %s", body)
+	}
+	if !contains(body, `"success_count":3`) || !contains(body, `"failure_count":1`) || !contains(body, `"total_count":4`) {
+		t.Fatalf("expected aggregated counts in response body: %s", body)
+	}
+	if provider.credentialsCalls != 1 {
+		t.Fatalf("expected ListUsageCredentialStats to be called once, got %d", provider.credentialsCalls)
+	}
+	if provider.lastFilter.Range != "24h" {
+		t.Fatalf("expected range to be passed through, got %+v", provider.lastFilter)
+	}
+	if provider.lastFilter.StartTime == nil || provider.lastFilter.EndTime == nil {
+		t.Fatalf("expected resolved time bounds in filter, got %+v", provider.lastFilter)
+	}
+}

internal/api/usage_filter.go

@@ -0,0 +1,141 @@
+package api
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"cpa-usage-keeper/internal/service"
+)
+
+var presetUsageRangeDurations = map[string]time.Duration{
+	"4h":  4 * time.Hour,
+	"8h":  8 * time.Hour,
+	"12h": 12 * time.Hour,
+	"24h": 24 * time.Hour,
+	"7d":  7 * 24 * time.Hour,
+}
+
+var allowedUsageEventsPageSizes = map[int]struct{}{
+	20:   {},
+	50:   {},
+	100:  {},
+	500:  {},
+	1000: {},
+}
+
+func parseUsageTimeFilterQuery(req *http.Request, anchor time.Time) (service.UsageFilter, error) {
+	filter, err := parseUsageFilterQuery(req, anchor)
+	if err != nil {
+		return service.UsageFilter{}, err
+	}
+	filter.Limit = 0
+	filter.Page = 0
+	filter.PageSize = 0
+	filter.Offset = 0
+	filter.Model = ""
+	filter.Source = ""
+	filter.AuthIndex = ""
+	filter.Result = ""
+	return filter, nil
+}
+
+func parseCustomUsageRangeBoundary(value string, endOfDay bool) (time.Time, error) {
+	if date, err := time.ParseInLocation(time.DateOnly, value, time.Local); err == nil {
+		if endOfDay {
+			return date.AddDate(0, 0, 1).Add(-time.Nanosecond), nil
+		}
+		return date, nil
+	}
+	return time.Parse(time.RFC3339, value)
+}
+
+func parseUsageFilterQuery(req *http.Request, anchor time.Time) (service.UsageFilter, error) {
+	if req == nil {
+		return service.UsageFilter{}, nil
+	}
+
+	rangeValue := strings.TrimSpace(req.URL.Query().Get("range"))
+	if rangeValue == "" {
+		rangeValue = "all"
+	}
+
+	filter := service.UsageFilter{Range: rangeValue, Limit: service.DefaultUsageEventsLimit, Page: 1, PageSize: service.DefaultUsageEventsLimit}
+	query := req.URL.Query()
+	if pageValue := strings.TrimSpace(query.Get("page")); pageValue != "" {
+		page, err := strconv.Atoi(pageValue)
+		if err != nil || page < 1 {
+			return service.UsageFilter{}, fmt.Errorf("invalid page %q", pageValue)
+		}
+		filter.Page = page
+	}
+	pageSizeValue := strings.TrimSpace(query.Get("page_size"))
+	if pageSizeValue == "" {
+		pageSizeValue = strings.TrimSpace(query.Get("limit"))
+	}
+	if pageSizeValue != "" {
+		pageSize, err := strconv.Atoi(pageSizeValue)
+		if err != nil {
+			return service.UsageFilter{}, fmt.Errorf("invalid page_size %q", pageSizeValue)
+		}
+		if _, ok := allowedUsageEventsPageSizes[pageSize]; !ok {
+			return service.UsageFilter{}, fmt.Errorf("invalid page_size %q", pageSizeValue)
+		}
+		filter.PageSize = pageSize
+		filter.Limit = pageSize
+	}
+	filter.Offset = (filter.Page - 1) * filter.PageSize
+	filter.Model = strings.TrimSpace(query.Get("model"))
+	filter.Source = strings.TrimSpace(query.Get("source"))
+	filter.AuthIndex = strings.TrimSpace(query.Get("auth_index"))
+	filter.Result = strings.TrimSpace(query.Get("result"))
+	if filter.Result != "" && filter.Result != "success" && filter.Result != "failed" {
+		return service.UsageFilter{}, fmt.Errorf("invalid result %q", filter.Result)
+	}
+	switch rangeValue {
+	case "all":
+		return filter, nil
+	case "today":
+		localAnchor := anchor.In(time.Local)
+		localStart := time.Date(localAnchor.Year(), localAnchor.Month(), localAnchor.Day(), 0, 0, 0, 0, time.Local)
+		startTime := localStart.UTC()
+		endTime := localStart.AddDate(0, 0, 1).Add(-time.Nanosecond).UTC()
+		filter.StartTime = &startTime
+		filter.EndTime = &endTime
+		return filter, nil
+	case "custom":
+		startValue := strings.TrimSpace(req.URL.Query().Get("start"))
+		endValue := strings.TrimSpace(req.URL.Query().Get("end"))
+		if startValue == "" || endValue == "" {
+			return service.UsageFilter{}, fmt.Errorf("custom range requires start and end")
+		}
+		startTime, err := parseCustomUsageRangeBoundary(startValue, false)
+		if err != nil {
+			return service.UsageFilter{}, fmt.Errorf("invalid start: %w", err)
+		}
+		endTime, err := parseCustomUsageRangeBoundary(endValue, true)
+		if err != nil {
+			return service.UsageFilter{}, fmt.Errorf("invalid end: %w", err)
+		}
+		startTime = startTime.UTC()
+		endTime = endTime.UTC()
+		if startTime.After(endTime) {
+			return service.UsageFilter{}, fmt.Errorf("custom range start must be before end")
+		}
+		filter.StartTime = &startTime
+		filter.EndTime = &endTime
+		return filter, nil
+	default:
+		duration, ok := presetUsageRangeDurations[rangeValue]
+		if !ok {
+			return service.UsageFilter{}, fmt.Errorf("unsupported usage range %q", rangeValue)
+		}
+		endTime := anchor.UTC()
+		startTime := endTime.Add(-duration)
+		filter.StartTime = &startTime
+		filter.EndTime = &endTime
+		return filter, nil
+	}
+}

internal/api/usage_filter_test.go

@@ -0,0 +1,209 @@
+package api
+
+import (
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+func TestParseUsageFilterQueryPresetRange(t *testing.T) {
+	req := httptest.NewRequest("GET", "/api/v1/usage/overview?range=24h", nil)
+	anchor := time.Date(2026, 4, 22, 12, 0, 0, 0, time.UTC)
+
+	filter, err := parseUsageFilterQuery(req, anchor)
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.Range != "24h" {
+		t.Fatalf("expected range to be preserved, got %+v", filter)
+	}
+	if filter.StartTime == nil || filter.EndTime == nil {
+		t.Fatalf("expected preset range to resolve concrete times, got %+v", filter)
+	}
+	if !filter.EndTime.Equal(anchor) {
+		t.Fatalf("expected preset range end to use anchor time, got %+v", filter)
+	}
+	if !filter.StartTime.Equal(anchor.Add(-24 * time.Hour)) {
+		t.Fatalf("expected preset range start to subtract 24h, got %+v", filter)
+	}
+}
+
+func TestParseUsageFilterQueryTodayRangeUsesLocalDayBoundary(t *testing.T) {
+	previousLocal := time.Local
+	location, err := time.LoadLocation("Asia/Shanghai")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	t.Cleanup(func() { time.Local = previousLocal })
+	time.Local = location
+
+	req := httptest.NewRequest("GET", "/api/v1/usage/overview?range=today", nil)
+	anchor := time.Date(2026, 4, 22, 12, 34, 56, 0, time.UTC)
+
+	filter, err := parseUsageFilterQuery(req, anchor)
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.Range != "today" {
+		t.Fatalf("expected today range to be preserved, got %+v", filter)
+	}
+	if filter.StartTime == nil || filter.EndTime == nil {
+		t.Fatalf("expected today range to resolve concrete times, got %+v", filter)
+	}
+	expectedStart := time.Date(2026, 4, 22, 0, 0, 0, 0, location).UTC()
+	expectedEnd := time.Date(2026, 4, 23, 0, 0, 0, 0, location).Add(-time.Nanosecond).UTC()
+	if !filter.StartTime.Equal(expectedStart) {
+		t.Fatalf("expected today start %s, got %s", expectedStart, *filter.StartTime)
+	}
+	if !filter.EndTime.Equal(expectedEnd) {
+		t.Fatalf("expected today end %s, got %s", expectedEnd, *filter.EndTime)
+	}
+}
+
+func TestParseUsageFilterQueryTodayRangeUsesLocalDSTBoundary(t *testing.T) {
+	previousLocal := time.Local
+	location, err := time.LoadLocation("America/New_York")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	t.Cleanup(func() { time.Local = previousLocal })
+	time.Local = location
+
+	req := httptest.NewRequest("GET", "/api/v1/usage/overview?range=today", nil)
+	anchor := time.Date(2026, 3, 8, 12, 0, 0, 0, location)
+
+	filter, err := parseUsageFilterQuery(req, anchor)
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.StartTime == nil || filter.EndTime == nil {
+		t.Fatalf("expected today range to resolve concrete times, got %+v", filter)
+	}
+	expectedStart := time.Date(2026, 3, 8, 0, 0, 0, 0, location).UTC()
+	expectedEnd := time.Date(2026, 3, 9, 0, 0, 0, 0, location).Add(-time.Nanosecond).UTC()
+	if !filter.StartTime.Equal(expectedStart) {
+		t.Fatalf("expected DST today start %s, got %s", expectedStart, *filter.StartTime)
+	}
+	if !filter.EndTime.Equal(expectedEnd) {
+		t.Fatalf("expected DST today end %s, got %s", expectedEnd, *filter.EndTime)
+	}
+}
+
+func TestParseUsageFilterQueryCustomRange(t *testing.T) {
+	req := httptest.NewRequest("GET", "/api/v1/usage/overview?range=custom&start=2026-04-20T00:00:00Z&end=2026-04-21T23:59:59Z", nil)
+
+	filter, err := parseUsageFilterQuery(req, time.Time{})
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.StartTime == nil || filter.EndTime == nil {
+		t.Fatalf("expected custom range bounds, got %+v", filter)
+	}
+	if !filter.StartTime.Equal(time.Date(2026, 4, 20, 0, 0, 0, 0, time.UTC)) {
+		t.Fatalf("unexpected custom start: %+v", filter)
+	}
+	if !filter.EndTime.Equal(time.Date(2026, 4, 21, 23, 59, 59, 0, time.UTC)) {
+		t.Fatalf("unexpected custom end: %+v", filter)
+	}
+}
+
+func TestParseUsageFilterQueryCustomDateRangeUsesLocalDayBoundary(t *testing.T) {
+	previousLocal := time.Local
+	location, err := time.LoadLocation("Asia/Shanghai")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	t.Cleanup(func() { time.Local = previousLocal })
+	time.Local = location
+
+	req := httptest.NewRequest("GET", "/api/v1/usage/overview?range=custom&start=2026-04-20&end=2026-04-21", nil)
+
+	filter, err := parseUsageFilterQuery(req, time.Time{})
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.StartTime == nil || filter.EndTime == nil {
+		t.Fatalf("expected custom date range bounds, got %+v", filter)
+	}
+	expectedStart := time.Date(2026, 4, 20, 0, 0, 0, 0, location).UTC()
+	expectedEnd := time.Date(2026, 4, 22, 0, 0, 0, 0, location).Add(-time.Nanosecond).UTC()
+	if !filter.StartTime.Equal(expectedStart) {
+		t.Fatalf("expected custom date start %s, got %s", expectedStart, *filter.StartTime)
+	}
+	if !filter.EndTime.Equal(expectedEnd) {
+		t.Fatalf("expected custom date end %s, got %s", expectedEnd, *filter.EndTime)
+	}
+}
+
+func TestParseUsageFilterQueryRejectsInvalidCustomRange(t *testing.T) {
+	req := httptest.NewRequest("GET", "/api/v1/usage/overview?range=custom&start=2026-04-21T00:00:00Z&end=2026-04-20T23:59:59Z", nil)
+
+	_, err := parseUsageFilterQuery(req, time.Time{})
+	if err == nil {
+		t.Fatal("expected invalid custom range error")
+	}
+}
+
+func TestParseUsageFilterQueryDefaultsEventsPagination(t *testing.T) {
+	req := httptest.NewRequest("GET", "/api/v1/usage/events?range=all", nil)
+
+	filter, err := parseUsageFilterQuery(req, time.Time{})
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.Page != 1 || filter.PageSize != 100 || filter.Offset != 0 {
+		t.Fatalf("expected default pagination, got %+v", filter)
+	}
+}
+
+func TestParseUsageFilterQueryAcceptsEventsPaginationAndFilters(t *testing.T) {
+	req := httptest.NewRequest("GET", "/api/v1/usage/events?page=3&page_size=100&model=%20claude-sonnet%20&source=%20source-a%20&auth_index=%202%20", nil)
+
+	filter, err := parseUsageFilterQuery(req, time.Time{})
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.Page != 3 || filter.PageSize != 100 || filter.Offset != 200 {
+		t.Fatalf("expected page 3/page size 100 offset 200, got %+v", filter)
+	}
+	if filter.Model != "claude-sonnet" || filter.Source != "source-a" || filter.AuthIndex != "2" {
+		t.Fatalf("expected trimmed server-side filters, got %+v", filter)
+	}
+}
+
+func TestParseUsageFilterQueryUsesLimitAsPageSizeAlias(t *testing.T) {
+	req := httptest.NewRequest("GET", "/api/v1/usage/events?limit=20", nil)
+
+	filter, err := parseUsageFilterQuery(req, time.Time{})
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.Page != 1 || filter.PageSize != 20 || filter.Offset != 0 {
+		t.Fatalf("expected limit alias to set page size, got %+v", filter)
+	}
+}
+
+func TestParseUsageFilterQueryPrefersPageSizeOverLimit(t *testing.T) {
+	req := httptest.NewRequest("GET", "/api/v1/usage/events?page_size=50&limit=20", nil)
+
+	filter, err := parseUsageFilterQuery(req, time.Time{})
+	if err != nil {
+		t.Fatalf("parseUsageFilterQuery returned error: %v", err)
+	}
+	if filter.PageSize != 50 {
+		t.Fatalf("expected page_size to win over limit, got %+v", filter)
+	}
+}
+
+func TestParseUsageFilterQueryRejectsInvalidEventsPagination(t *testing.T) {
+	tests := []string{
+		"/api/v1/usage/events?page=0",
+		"/api/v1/usage/events?page_size=25",
+	}
+	for _, path := range tests {
+		req := httptest.NewRequest("GET", path, nil)
+		if _, err := parseUsageFilterQuery(req, time.Time{}); err == nil {
+			t.Fatalf("expected pagination error for %s", path)
+		}
+	}
+}

internal/api/usage_identities.go

@@ -0,0 +1,125 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+	"time"
+
+	"cpa-usage-keeper/internal/models"
+	"cpa-usage-keeper/internal/redact"
+	"cpa-usage-keeper/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type usageIdentitiesResponse struct {
+	Identities []usageIdentityResponse `json:"identities"`
+}
+
+type usageIdentityResponse struct {
+	ID                         uint                         `json:"id"`
+	Name                       string                       `json:"name"`
+	AuthType                   models.UsageIdentityAuthType `json:"auth_type"`
+	AuthTypeName               string                       `json:"auth_type_name"`
+	Identity                   string                       `json:"identity"`
+	Type                       string                       `json:"type"`
+	Provider                   string                       `json:"provider"`
+	TotalRequests              int64                        `json:"total_requests"`
+	SuccessCount               int64                        `json:"success_count"`
+	FailureCount               int64                        `json:"failure_count"`
+	InputTokens                int64                        `json:"input_tokens"`
+	OutputTokens               int64                        `json:"output_tokens"`
+	ReasoningTokens            int64                        `json:"reasoning_tokens"`
+	CachedTokens               int64                        `json:"cached_tokens"`
+	TotalTokens                int64                        `json:"total_tokens"`
+	LastAggregatedUsageEventID uint                         `json:"last_aggregated_usage_event_id"`
+	FirstUsedAt                *time.Time                   `json:"first_used_at,omitempty"`
+	LastUsedAt                 *time.Time                   `json:"last_used_at,omitempty"`
+	StatsUpdatedAt             *time.Time                   `json:"stats_updated_at,omitempty"`
+	IsDeleted                  bool                         `json:"is_deleted"`
+	CreatedAt                  time.Time                    `json:"created_at"`
+	UpdatedAt                  time.Time                    `json:"updated_at"`
+	DeletedAt                  *time.Time                   `json:"deleted_at,omitempty"`
+}
+
+func registerUsageIdentityRoutes(router gin.IRoutes, usageIdentityProvider service.UsageIdentityProvider) {
+	router.GET("/usage/identities", func(c *gin.Context) {
+		if usageIdentityProvider == nil {
+			c.JSON(http.StatusOK, usageIdentitiesResponse{Identities: []usageIdentityResponse{}})
+			return
+		}
+
+		items, err := usageIdentityProvider.ListUsageIdentities(c.Request.Context())
+		if err != nil {
+			writeInternalError(c, "list usage identities failed", err)
+			return
+		}
+
+		response := make([]usageIdentityResponse, 0, len(items))
+		for _, item := range items {
+			response = append(response, mapUsageIdentityResponse(item))
+		}
+		c.JSON(http.StatusOK, usageIdentitiesResponse{Identities: response})
+	})
+}
+
+func mapUsageIdentityResponse(item models.UsageIdentity) usageIdentityResponse {
+	identity := item.Identity
+	name := item.Name
+	identityType := item.Type
+	provider := item.Provider
+	if item.AuthType == models.UsageIdentityAuthTypeAIProvider {
+		identity = redact.APIKeyDisplayName(item.Identity)
+		identityType = safeAIProviderDisplayValue(item.Type, item.Identity, item.AuthTypeName)
+		provider = safeAIProviderDisplayValue(item.Provider, item.Identity, firstNonEmptyString(identityType, identity))
+		name = safeAIProviderDisplayValue(item.Name, item.Identity, firstNonEmptyString(provider, identityType, identity))
+	}
+
+	return usageIdentityResponse{
+		ID:                         item.ID,
+		Name:                       name,
+		AuthType:                   item.AuthType,
+		AuthTypeName:               item.AuthTypeName,
+		Identity:                   identity,
+		Type:                       identityType,
+		Provider:                   provider,
+		TotalRequests:              item.TotalRequests,
+		SuccessCount:               item.SuccessCount,
+		FailureCount:               item.FailureCount,
+		InputTokens:                item.InputTokens,
+		OutputTokens:               item.OutputTokens,
+		ReasoningTokens:            item.ReasoningTokens,
+		CachedTokens:               item.CachedTokens,
+		TotalTokens:                item.TotalTokens,
+		LastAggregatedUsageEventID: item.LastAggregatedUsageEventID,
+		FirstUsedAt:                item.FirstUsedAt,
+		LastUsedAt:                 item.LastUsedAt,
+		StatsUpdatedAt:             item.StatsUpdatedAt,
+		IsDeleted:                  item.IsDeleted,
+		CreatedAt:                  item.CreatedAt,
+		UpdatedAt:                  item.UpdatedAt,
+		DeletedAt:                  item.DeletedAt,
+	}
+}
+
+func safeAIProviderDisplayValue(value, rawIdentity, fallback string) string {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return fallback
+	}
+	if isSensitiveUsageIdentityValue(trimmed, rawIdentity) {
+		return fallback
+	}
+	return trimmed
+}
+
+func isSensitiveUsageIdentityValue(value, rawIdentity string) bool {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return false
+	}
+	if raw := strings.TrimSpace(rawIdentity); raw != "" && strings.Contains(trimmed, raw) {
+		return true
+	}
+	lower := strings.ToLower(trimmed)
+	return strings.Contains(lower, "sk-") || strings.Contains(lower, "aiza") || strings.Contains(lower, "cr_") || strings.Contains(lower, "cr-")
+}

internal/api/usage_identities_test.go

@@ -0,0 +1,144 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"cpa-usage-keeper/internal/models"
+	"cpa-usage-keeper/internal/redact"
+)
+
+type usageIdentitiesStub struct {
+	items []models.UsageIdentity
+	err   error
+}
+
+func (s usageIdentitiesStub) ListUsageIdentities(context.Context) ([]models.UsageIdentity, error) {
+	return s.items, s.err
+}
+
+func TestUsageIdentitiesRouteReturnsMetadataStatsAndDeletedRows(t *testing.T) {
+	firstUsedAt := time.Date(2026, 5, 4, 8, 0, 0, 0, time.UTC)
+	lastUsedAt := time.Date(2026, 5, 4, 9, 0, 0, 0, time.UTC)
+	statsUpdatedAt := time.Date(2026, 5, 4, 10, 0, 0, 0, time.UTC)
+	createdAt := time.Date(2026, 5, 3, 8, 0, 0, 0, time.UTC)
+	updatedAt := time.Date(2026, 5, 4, 10, 30, 0, 0, time.UTC)
+	deletedAt := time.Date(2026, 5, 4, 11, 0, 0, 0, time.UTC)
+
+	router := NewRouter(nil, nil, nil, nil, AuthConfig{}, nil, "", usageIdentitiesStub{items: []models.UsageIdentity{
+		{
+			ID:                         1,
+			Name:                       "Claude Desktop",
+			AuthType:                   models.UsageIdentityAuthTypeAuthFile,
+			AuthTypeName:               "oauth",
+			Identity:                   "2",
+			Type:                       "auth-file",
+			Provider:                   "anthropic",
+			TotalRequests:              10,
+			SuccessCount:               8,
+			FailureCount:               2,
+			InputTokens:                100,
+			OutputTokens:               200,
+			ReasoningTokens:            30,
+			CachedTokens:               40,
+			TotalTokens:                370,
+			LastAggregatedUsageEventID: 99,
+			FirstUsedAt:                &firstUsedAt,
+			LastUsedAt:                 &lastUsedAt,
+			StatsUpdatedAt:             &statsUpdatedAt,
+			CreatedAt:                  createdAt,
+			UpdatedAt:                  updatedAt,
+		},
+		{
+			ID:           2,
+			Name:         "Deleted Provider",
+			AuthType:     models.UsageIdentityAuthTypeAIProvider,
+			AuthTypeName: "apikey",
+			Identity:     "sk-deleted-provider-secret",
+			Type:         "openai",
+			Provider:     "OpenAI",
+			IsDeleted:    true,
+			DeletedAt:    &deletedAt,
+			CreatedAt:    createdAt,
+			UpdatedAt:    updatedAt,
+		},
+	}})
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/identities", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	body := resp.Body.String()
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d: %s", resp.Code, body)
+	}
+	if !contains(body, `"identities":[`) || !contains(body, `"id":1`) || !contains(body, `"identity":"2"`) {
+		t.Fatalf("expected auth file identity row in response, got %s", body)
+	}
+	for _, expected := range []string{
+		`"name":"Claude Desktop"`,
+		`"auth_type":1`,
+		`"auth_type_name":"oauth"`,
+		`"type":"auth-file"`,
+		`"provider":"anthropic"`,
+		`"total_requests":10`,
+		`"success_count":8`,
+		`"failure_count":2`,
+		`"input_tokens":100`,
+		`"output_tokens":200`,
+		`"reasoning_tokens":30`,
+		`"cached_tokens":40`,
+		`"total_tokens":370`,
+		`"last_aggregated_usage_event_id":99`,
+		`"first_used_at":"2026-05-04T08:00:00Z"`,
+		`"last_used_at":"2026-05-04T09:00:00Z"`,
+		`"stats_updated_at":"2026-05-04T10:00:00Z"`,
+		`"is_deleted":true`,
+		`"deleted_at":"2026-05-04T11:00:00Z"`,
+	} {
+		if !contains(body, expected) {
+			t.Fatalf("expected %s in response body: %s", expected, body)
+		}
+	}
+}
+
+func TestUsageIdentitiesRouteMasksAIProviderIdentity(t *testing.T) {
+	rawLookupKey := "sk-live-secret-value"
+	rawPrefix := "sk-live-prefix"
+	maskedLookupKey := redact.APIKeyDisplayName(rawLookupKey)
+	router := NewRouter(nil, nil, nil, nil, AuthConfig{}, nil, "", usageIdentitiesStub{items: []models.UsageIdentity{
+		{ID: 1, Name: rawPrefix, AuthType: models.UsageIdentityAuthTypeAIProvider, AuthTypeName: "apikey", Identity: rawLookupKey, Type: "openai " + rawLookupKey, Provider: "OpenAI " + rawPrefix},
+	}})
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/identities", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	body := resp.Body.String()
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d: %s", resp.Code, body)
+	}
+	if contains(body, rawLookupKey) || contains(body, rawPrefix) {
+		t.Fatalf("expected raw AI provider lookup values to be hidden, got %s", body)
+	}
+	if !contains(body, `"identity":"`+maskedLookupKey+`"`) {
+		t.Fatalf("expected masked AI provider identity %q in response body: %s", maskedLookupKey, body)
+	}
+}
+
+func TestUsageIdentityReplacesLegacyMetadataRoutes(t *testing.T) {
+	router := NewRouter(nil, nil, nil, nil, AuthConfig{}, nil, "", usageIdentitiesStub{})
+	for _, path := range []string{"/api/v1/auth-files", "/api/v1/provider-metadata"} {
+		req := httptest.NewRequest(http.MethodGet, path, nil)
+		resp := httptest.NewRecorder()
+
+		router.ServeHTTP(resp, req)
+
+		if resp.Code != http.StatusNotFound {
+			t.Fatalf("expected %s to return 404, got %d: %s", path, resp.Code, resp.Body.String())
+		}
+	}
+}

internal/api/usage_overview.go

@@ -0,0 +1,335 @@
+package api
+
+import (
+	"net/http"
+	"time"
+
+	"cpa-usage-keeper/internal/cpa"
+	"cpa-usage-keeper/internal/redact"
+	"cpa-usage-keeper/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type usageOverviewResponse struct {
+	Usage         usageOverviewPayload       `json:"usage"`
+	Summary       usageOverviewSummary       `json:"summary"`
+	Series        usageOverviewSeries        `json:"series"`
+	HourlySeries  usageOverviewSeries        `json:"hourly_series"`
+	DailySeries   usageOverviewSeries        `json:"daily_series"`
+	ServiceHealth usageOverviewServiceHealth `json:"service_health"`
+	Timezone      string                     `json:"timezone"`
+	RangeStart    *time.Time                 `json:"range_start,omitempty"`
+	RangeEnd      *time.Time                 `json:"range_end,omitempty"`
+}
+
+type usageOverviewPayload struct {
+	TotalRequests  int64                               `json:"total_requests"`
+	SuccessCount   int64                               `json:"success_count"`
+	FailureCount   int64                               `json:"failure_count"`
+	TotalTokens    int64                               `json:"total_tokens"`
+	APIs           map[string]usageOverviewAPISnapshot `json:"apis"`
+	RequestsByDay  map[string]int64                    `json:"requests_by_day"`
+	RequestsByHour map[string]int64                    `json:"requests_by_hour"`
+	TokensByDay    map[string]int64                    `json:"tokens_by_day"`
+	TokensByHour   map[string]int64                    `json:"tokens_by_hour"`
+}
+
+type usageOverviewSummary struct {
+	RequestCount    int64   `json:"request_count"`
+	TokenCount      int64   `json:"token_count"`
+	WindowMinutes   int64   `json:"window_minutes"`
+	RPM             float64 `json:"rpm"`
+	TPM             float64 `json:"tpm"`
+	TotalCost       float64 `json:"total_cost"`
+	CostAvailable   bool    `json:"cost_available"`
+	CachedTokens    int64   `json:"cached_tokens"`
+	ReasoningTokens int64   `json:"reasoning_tokens"`
+}
+
+type usageOverviewSeries struct {
+	Requests        map[string]int64                   `json:"requests"`
+	Tokens          map[string]int64                   `json:"tokens"`
+	RPM             map[string]float64                 `json:"rpm"`
+	TPM             map[string]float64                 `json:"tpm"`
+	Cost            map[string]float64                 `json:"cost"`
+	InputTokens     map[string]int64                   `json:"input_tokens"`
+	OutputTokens    map[string]int64                   `json:"output_tokens"`
+	CachedTokens    map[string]int64                   `json:"cached_tokens"`
+	ReasoningTokens map[string]int64                   `json:"reasoning_tokens"`
+	Models          map[string]usageOverviewSeriesLine `json:"models"`
+}
+
+type usageOverviewSeriesLine struct {
+	Requests        map[string]int64   `json:"requests"`
+	Tokens          map[string]int64   `json:"tokens"`
+	RPM             map[string]float64 `json:"rpm"`
+	TPM             map[string]float64 `json:"tpm"`
+	Cost            map[string]float64 `json:"cost"`
+	InputTokens     map[string]int64   `json:"input_tokens"`
+	OutputTokens    map[string]int64   `json:"output_tokens"`
+	CachedTokens    map[string]int64   `json:"cached_tokens"`
+	ReasoningTokens map[string]int64   `json:"reasoning_tokens"`
+}
+
+type usageOverviewServiceHealth struct {
+	TotalSuccess  int64                             `json:"total_success"`
+	TotalFailure  int64                             `json:"total_failure"`
+	SuccessRate   float64                           `json:"success_rate"`
+	Rows          int                               `json:"rows"`
+	Columns       int                               `json:"columns"`
+	BucketSeconds int64                             `json:"bucket_seconds"`
+	WindowStart   time.Time                         `json:"window_start"`
+	WindowEnd     time.Time                         `json:"window_end"`
+	BlockDetails  []usageOverviewServiceHealthBlock `json:"block_details"`
+}
+
+type usageOverviewServiceHealthBlock struct {
+	StartTime time.Time `json:"start_time"`
+	EndTime   time.Time `json:"end_time"`
+	Success   int64     `json:"success"`
+	Failure   int64     `json:"failure"`
+	Rate      float64   `json:"rate"`
+}
+
+type usageOverviewAPISnapshot struct {
+	DisplayName   string                                `json:"display_name,omitempty"`
+	TotalRequests int64                                 `json:"total_requests"`
+	SuccessCount  int64                                 `json:"success_count"`
+	FailureCount  int64                                 `json:"failure_count"`
+	TotalTokens   int64                                 `json:"total_tokens"`
+	Models        map[string]usageOverviewModelSnapshot `json:"models"`
+}
+
+type usageOverviewModelSnapshot struct {
+	TotalRequests int64 `json:"total_requests"`
+	SuccessCount  int64 `json:"success_count"`
+	FailureCount  int64 `json:"failure_count"`
+	TotalTokens   int64 `json:"total_tokens"`
+}
+
+func registerUsageOverviewRoute(router gin.IRoutes, usageProvider service.UsageProvider) {
+	router.GET("/usage/overview", func(c *gin.Context) {
+		if usageProvider == nil {
+			c.JSON(http.StatusOK, usageOverviewResponse{
+				Usage:         buildUsageOverviewPayload(nil),
+				Summary:       usageOverviewSummary{},
+				Series:        emptyUsageOverviewSeries(),
+				HourlySeries:  emptyUsageOverviewSeries(),
+				DailySeries:   emptyUsageOverviewSeries(),
+				ServiceHealth: usageOverviewServiceHealth{BlockDetails: []usageOverviewServiceHealthBlock{}},
+				Timezone:      time.Local.String(),
+			})
+			return
+		}
+
+		filter, err := parseUsageFilterQuery(c.Request, time.Now().UTC())
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+
+		overview, err := usageProvider.GetUsageOverview(c.Request.Context(), filter)
+		if err != nil {
+			writeInternalError(c, "get usage overview failed", err)
+			return
+		}
+
+		var usage *cpa.StatisticsSnapshot
+		if overview != nil {
+			usage = overview.Usage
+		}
+		redactedUsage := redact.UsageSnapshot(usage)
+		c.JSON(http.StatusOK, usageOverviewResponse{
+			Usage:         buildUsageOverviewPayload(redactedUsage),
+			Summary:       buildUsageOverviewSummary(overview),
+			Series:        buildUsageOverviewSeries(overview),
+			HourlySeries:  buildUsageOverviewHourlySeries(overview),
+			DailySeries:   buildUsageOverviewDailySeries(overview),
+			ServiceHealth: buildUsageOverviewServiceHealth(overview),
+			Timezone:      time.Local.String(),
+			RangeStart:    filter.StartTime,
+			RangeEnd:      filter.EndTime,
+		})
+	})
+}
+
+func buildUsageOverviewPayload(snapshot *cpa.StatisticsSnapshot) usageOverviewPayload {
+	if snapshot == nil {
+		return usageOverviewPayload{
+			APIs:           map[string]usageOverviewAPISnapshot{},
+			RequestsByDay:  map[string]int64{},
+			RequestsByHour: map[string]int64{},
+			TokensByDay:    map[string]int64{},
+			TokensByHour:   map[string]int64{},
+		}
+	}
+
+	payload := usageOverviewPayload{
+		TotalRequests:  snapshot.TotalRequests,
+		SuccessCount:   snapshot.SuccessCount,
+		FailureCount:   snapshot.FailureCount,
+		TotalTokens:    snapshot.TotalTokens,
+		RequestsByDay:  cloneInt64Map(snapshot.RequestsByDay),
+		RequestsByHour: cloneInt64Map(snapshot.RequestsByHour),
+		TokensByDay:    cloneInt64Map(snapshot.TokensByDay),
+		TokensByHour:   cloneInt64Map(snapshot.TokensByHour),
+		APIs:           map[string]usageOverviewAPISnapshot{},
+	}
+
+	for apiName, apiSnapshot := range snapshot.APIs {
+		payloadAPI := usageOverviewAPISnapshot{
+			DisplayName:   apiSnapshot.DisplayName,
+			TotalRequests: apiSnapshot.TotalRequests,
+			SuccessCount:  apiSnapshot.SuccessCount,
+			FailureCount:  apiSnapshot.FailureCount,
+			TotalTokens:   apiSnapshot.TotalTokens,
+			Models:        map[string]usageOverviewModelSnapshot{},
+		}
+		for modelName, modelSnapshot := range apiSnapshot.Models {
+			payloadAPI.Models[modelName] = usageOverviewModelSnapshot{
+				TotalRequests: modelSnapshot.TotalRequests,
+				SuccessCount:  modelSnapshot.SuccessCount,
+				FailureCount:  modelSnapshot.FailureCount,
+				TotalTokens:   modelSnapshot.TotalTokens,
+			}
+		}
+		payload.APIs[apiName] = payloadAPI
+	}
+
+	return payload
+}
+
+func buildUsageOverviewSummary(overview *service.UsageOverviewSnapshot) usageOverviewSummary {
+	if overview == nil {
+		return usageOverviewSummary{}
+	}
+	return usageOverviewSummary{
+		RequestCount:    overview.Summary.RequestCount,
+		TokenCount:      overview.Summary.TokenCount,
+		WindowMinutes:   overview.Summary.WindowMinutes,
+		RPM:             overview.Summary.RPM,
+		TPM:             overview.Summary.TPM,
+		TotalCost:       overview.Summary.TotalCost,
+		CostAvailable:   overview.Summary.CostAvailable,
+		CachedTokens:    overview.Summary.CachedTokens,
+		ReasoningTokens: overview.Summary.ReasoningTokens,
+	}
+}
+
+func emptyUsageOverviewSeries() usageOverviewSeries {
+	return usageOverviewSeries{
+		Requests:        map[string]int64{},
+		Tokens:          map[string]int64{},
+		RPM:             map[string]float64{},
+		TPM:             map[string]float64{},
+		Cost:            map[string]float64{},
+		InputTokens:     map[string]int64{},
+		OutputTokens:    map[string]int64{},
+		CachedTokens:    map[string]int64{},
+		ReasoningTokens: map[string]int64{},
+		Models:          map[string]usageOverviewSeriesLine{},
+	}
+}
+
+func mapUsageOverviewSeriesLine(series service.UsageOverviewSeries) usageOverviewSeriesLine {
+	return usageOverviewSeriesLine{
+		Requests:        cloneInt64Map(series.Requests),
+		Tokens:          cloneInt64Map(series.Tokens),
+		RPM:             cloneFloat64Map(series.RPM),
+		TPM:             cloneFloat64Map(series.TPM),
+		Cost:            cloneFloat64Map(series.Cost),
+		InputTokens:     cloneInt64Map(series.InputTokens),
+		OutputTokens:    cloneInt64Map(series.OutputTokens),
+		CachedTokens:    cloneInt64Map(series.CachedTokens),
+		ReasoningTokens: cloneInt64Map(series.ReasoningTokens),
+	}
+}
+
+func mapUsageOverviewSeries(series service.UsageOverviewSeries) usageOverviewSeries {
+	models := make(map[string]usageOverviewSeriesLine, len(series.Models))
+	for model, modelSeries := range series.Models {
+		models[model] = mapUsageOverviewSeriesLine(modelSeries)
+	}
+	return usageOverviewSeries{
+		Requests:        cloneInt64Map(series.Requests),
+		Tokens:          cloneInt64Map(series.Tokens),
+		RPM:             cloneFloat64Map(series.RPM),
+		TPM:             cloneFloat64Map(series.TPM),
+		Cost:            cloneFloat64Map(series.Cost),
+		InputTokens:     cloneInt64Map(series.InputTokens),
+		OutputTokens:    cloneInt64Map(series.OutputTokens),
+		CachedTokens:    cloneInt64Map(series.CachedTokens),
+		ReasoningTokens: cloneInt64Map(series.ReasoningTokens),
+		Models:          models,
+	}
+}
+
+func buildUsageOverviewSeries(overview *service.UsageOverviewSnapshot) usageOverviewSeries {
+	if overview == nil {
+		return emptyUsageOverviewSeries()
+	}
+	return mapUsageOverviewSeries(overview.Series)
+}
+
+func buildUsageOverviewHourlySeries(overview *service.UsageOverviewSnapshot) usageOverviewSeries {
+	if overview == nil {
+		return emptyUsageOverviewSeries()
+	}
+	return mapUsageOverviewSeries(overview.HourlySeries)
+}
+
+func buildUsageOverviewDailySeries(overview *service.UsageOverviewSnapshot) usageOverviewSeries {
+	if overview == nil {
+		return emptyUsageOverviewSeries()
+	}
+	return mapUsageOverviewSeries(overview.DailySeries)
+}
+
+func buildUsageOverviewServiceHealth(overview *service.UsageOverviewSnapshot) usageOverviewServiceHealth {
+	if overview == nil {
+		return usageOverviewServiceHealth{BlockDetails: []usageOverviewServiceHealthBlock{}}
+	}
+	blocks := make([]usageOverviewServiceHealthBlock, 0, len(overview.Health.BlockDetails))
+	for _, block := range overview.Health.BlockDetails {
+		blocks = append(blocks, usageOverviewServiceHealthBlock{
+			StartTime: block.StartTime,
+			EndTime:   block.EndTime,
+			Success:   block.Success,
+			Failure:   block.Failure,
+			Rate:      block.Rate,
+		})
+	}
+	return usageOverviewServiceHealth{
+		TotalSuccess:  overview.Health.TotalSuccess,
+		TotalFailure:  overview.Health.TotalFailure,
+		SuccessRate:   overview.Health.SuccessRate,
+		Rows:          overview.Health.Rows,
+		Columns:       overview.Health.Columns,
+		BucketSeconds: overview.Health.BucketSeconds,
+		WindowStart:   overview.Health.WindowStart,
+		WindowEnd:     overview.Health.WindowEnd,
+		BlockDetails:  blocks,
+	}
+}
+
+func cloneInt64Map(source map[string]int64) map[string]int64 {
+	if len(source) == 0 {
+		return map[string]int64{}
+	}
+	cloned := make(map[string]int64, len(source))
+	for key, value := range source {
+		cloned[key] = value
+	}
+	return cloned
+}
+
+func cloneFloat64Map(source map[string]float64) map[string]float64 {
+	if len(source) == 0 {
+		return map[string]float64{}
+	}
+	cloned := make(map[string]float64, len(source))
+	for key, value := range source {
+		cloned[key] = value
+	}
+	return cloned
+}

internal/api/usage_overview_test.go

@@ -0,0 +1,196 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"cpa-usage-keeper/internal/cpa"
+	"cpa-usage-keeper/internal/service"
+)
+
+type usageFilterStub struct {
+	usage         *cpa.StatisticsSnapshot
+	overview      *service.UsageOverviewSnapshot
+	err           error
+	lastFilter    service.UsageFilter
+	filterCalls   int
+	overviewCalls int
+}
+
+func (s *usageFilterStub) GetUsageWithFilter(_ context.Context, filter service.UsageFilter) (*cpa.StatisticsSnapshot, error) {
+	s.lastFilter = filter
+	s.filterCalls++
+	return s.usage, s.err
+}
+
+func (s *usageFilterStub) GetUsageOverview(_ context.Context, filter service.UsageFilter) (*service.UsageOverviewSnapshot, error) {
+	s.lastFilter = filter
+	s.overviewCalls++
+	return s.overview, s.err
+}
+
+func (s *usageFilterStub) ListUsageEvents(context.Context, service.UsageFilter) (*service.UsageEventsPage, error) {
+	return nil, s.err
+}
+
+func (s *usageFilterStub) ListUsageEventFilterOptions(context.Context, service.UsageFilter) (*service.UsageEventFilterOptions, error) {
+	return nil, s.err
+}
+
+func (s *usageFilterStub) ListUsageCredentialStats(context.Context, service.UsageFilter) ([]service.UsageCredentialStat, error) {
+	return nil, s.err
+}
+
+func (s *usageFilterStub) GetUsageAnalysis(context.Context, service.UsageFilter) (*service.UsageAnalysisSnapshot, error) {
+	return nil, s.err
+}
+
+func mustParseTime(t *testing.T, value string) time.Time {
+	t.Helper()
+	parsed, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		t.Fatalf("time.Parse returned error: %v", err)
+	}
+	return parsed
+}
+
+func TestUsageOverviewResponseIncludesResolvedRangeAndTimezone(t *testing.T) {
+	previousLocal := time.Local
+	location, err := time.LoadLocation("Asia/Shanghai")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	t.Cleanup(func() { time.Local = previousLocal })
+	time.Local = location
+
+	provider := &usageFilterStub{overview: &service.UsageOverviewSnapshot{}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/overview?range=custom&start=2026-04-20&end=2026-04-21", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	expectedStart := time.Date(2026, 4, 20, 0, 0, 0, 0, location).UTC().Format(time.RFC3339Nano)
+	expectedEnd := time.Date(2026, 4, 22, 0, 0, 0, 0, location).Add(-time.Nanosecond).UTC().Format(time.RFC3339Nano)
+	body := resp.Body.String()
+	if !contains(body, `"timezone":"Asia/Shanghai"`) || !contains(body, `"range_start":"`+expectedStart+`"`) || !contains(body, `"range_end":"`+expectedEnd+`"`) {
+		t.Fatalf("expected overview response to include resolved range and timezone, got %s", body)
+	}
+}
+
+func TestUsageOverviewReturnsFilteredSnapshot(t *testing.T) {
+	provider := &usageFilterStub{overview: &service.UsageOverviewSnapshot{
+		Usage: &cpa.StatisticsSnapshot{
+			TotalRequests: 1,
+			SuccessCount:  1,
+			TotalTokens:   20,
+			RequestsByHour: map[string]int64{
+				"2026-04-22T11:00:00Z": 1,
+			},
+			TokensByHour: map[string]int64{
+				"2026-04-22T11:00:00Z": 20,
+			},
+			APIs: map[string]cpa.APISnapshot{
+				"provider-a": {
+					TotalRequests: 1,
+					SuccessCount:  1,
+					TotalTokens:   20,
+					Models: map[string]cpa.ModelSnapshot{
+						"claude-sonnet": {
+							TotalRequests: 1,
+							SuccessCount:  1,
+							TotalTokens:   20,
+						},
+					},
+				},
+			},
+		},
+		Summary: service.UsageOverviewSummary{
+			RequestCount:    1,
+			TokenCount:      20,
+			WindowMinutes:   1440,
+			RPM:             1.0 / 1440.0,
+			TPM:             20.0 / 1440.0,
+			TotalCost:       0.123,
+			CostAvailable:   true,
+			CachedTokens:    2,
+			ReasoningTokens: 3,
+		},
+		Series: service.UsageOverviewSeries{
+			Requests:        map[string]int64{"2026-04-22T11:00:00Z": 1},
+			Tokens:          map[string]int64{"2026-04-22T11:00:00Z": 20},
+			RPM:             map[string]float64{"2026-04-22T11:00:00Z": 1.0 / 60.0},
+			TPM:             map[string]float64{"2026-04-22T11:00:00Z": 20.0 / 60.0},
+			Cost:            map[string]float64{"2026-04-22T11:00:00Z": 0.123},
+			InputTokens:     map[string]int64{"2026-04-22T11:00:00Z": 11},
+			OutputTokens:    map[string]int64{"2026-04-22T11:00:00Z": 7},
+			CachedTokens:    map[string]int64{"2026-04-22T11:00:00Z": 2},
+			ReasoningTokens: map[string]int64{"2026-04-22T11:00:00Z": 3},
+		},
+		Health: service.UsageOverviewHealth{
+			TotalSuccess: 1,
+			TotalFailure: 0,
+			SuccessRate:  100,
+			BlockDetails: []service.UsageOverviewHealthBlock{{
+				StartTime: mustParseTime(t, "2026-04-22T11:00:00Z"),
+				EndTime:   mustParseTime(t, "2026-04-22T11:15:00Z"),
+				Success:   1,
+				Failure:   0,
+				Rate:      1,
+			}},
+		},
+	}}
+	router := NewRouter(nil, nil, provider, nil, AuthConfig{}, nil, "")
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/usage/overview?range=24h", nil)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.Code)
+	}
+	body := resp.Body.String()
+	if !contains(body, `"usage":`) || !contains(body, `"total_requests":1`) {
+		t.Fatalf("unexpected response body: %s", body)
+	}
+	if !contains(body, `"summary":{"request_count":1,"token_count":20`) {
+		t.Fatalf("expected backend summary in response body: %s", body)
+	}
+	if !contains(body, `"cost_available":true`) {
+		t.Fatalf("expected backend cost availability in response body: %s", body)
+	}
+	if !contains(body, `"series":{"requests":{"2026-04-22T11:00:00Z":1}`) {
+		t.Fatalf("expected backend series in response body: %s", body)
+	}
+	if !contains(body, `"input_tokens":{"2026-04-22T11:00:00Z":11}`) ||
+		!contains(body, `"output_tokens":{"2026-04-22T11:00:00Z":7}`) ||
+		!contains(body, `"cached_tokens":{"2026-04-22T11:00:00Z":2}`) ||
+		!contains(body, `"reasoning_tokens":{"2026-04-22T11:00:00Z":3}`) {
+		t.Fatalf("expected token breakdown series in response body: %s", body)
+	}
+	if !contains(body, `"service_health":{"total_success":1,"total_failure":0,"success_rate":100`) ||
+		!contains(body, `"block_details":[{"start_time":"2026-04-22T11:00:00Z","end_time":"2026-04-22T11:15:00Z","success":1,"failure":0,"rate":1}]`) {
+		t.Fatalf("expected service health in response body: %s", body)
+	}
+	if contains(body, `"details":`) {
+		t.Fatalf("expected overview response to omit request details: %s", body)
+	}
+	if provider.filterCalls != 0 {
+		t.Fatalf("expected GetUsageWithFilter not to be called, got %d", provider.filterCalls)
+	}
+	if provider.overviewCalls != 1 {
+		t.Fatalf("expected GetUsageOverview to be called once, got %d", provider.overviewCalls)
+	}
+	if provider.lastFilter.Range != "24h" {
+		t.Fatalf("expected range to be passed through, got %+v", provider.lastFilter)
+	}
+	if provider.lastFilter.StartTime == nil || provider.lastFilter.EndTime == nil {
+		t.Fatalf("expected resolved time bounds in filter, got %+v", provider.lastFilter)
+	}
+}

internal/api/usage_resolution.go

@@ -0,0 +1,17 @@
+package api
+
+import (
+	"cpa-usage-keeper/internal/models"
+	"cpa-usage-keeper/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+func loadUsageResolutionData(
+	c *gin.Context,
+	usageIdentityProvider service.UsageIdentityProvider,
+) ([]models.UsageIdentity, error) {
+	if usageIdentityProvider == nil {
+		return []models.UsageIdentity{}, nil
+	}
+	return usageIdentityProvider.ListUsageIdentities(c.Request.Context())
+}

internal/api/usage_source_resolution.go

@@ -0,0 +1,167 @@
+package api
+
+import (
+	"strconv"
+	"strings"
+
+	"cpa-usage-keeper/internal/models"
+	"cpa-usage-keeper/internal/redact"
+)
+
+type usageSourceResolver struct {
+	authIdentities     map[string]models.UsageIdentity
+	providerIdentities map[string]models.UsageIdentity
+	providerRawByKey   map[string]string
+}
+
+func newUsageSourceResolver(identities []models.UsageIdentity) usageSourceResolver {
+	authIdentities := make(map[string]models.UsageIdentity, len(identities))
+	providerIdentities := make(map[string]models.UsageIdentity, len(identities))
+	providerRawByKey := make(map[string]string, len(identities))
+	for _, identity := range identities {
+		key := strings.TrimSpace(identity.Identity)
+		if key == "" {
+			continue
+		}
+		switch identity.AuthType {
+		case models.UsageIdentityAuthTypeAuthFile:
+			authIdentities[key] = identity
+		case models.UsageIdentityAuthTypeAIProvider:
+			providerIdentities[key] = identity
+			resolved := usageSourceResolutionFromIdentity(identity, key)
+			if resolved.SourceKey != "" {
+				providerRawByKey[resolved.SourceKey] = key
+			}
+		}
+	}
+
+	return usageSourceResolver{
+		authIdentities:     authIdentities,
+		providerIdentities: providerIdentities,
+		providerRawByKey:   providerRawByKey,
+	}
+}
+
+type usageSourceResolution struct {
+	DisplayName string
+	SourceType  string
+	SourceKey   string
+}
+
+func usageSourceResolutionFromIdentity(item models.UsageIdentity, fallbackIdentity string) usageSourceResolution {
+	identityType := safeAIProviderDisplayValue(item.Type, fallbackIdentity, "")
+	displayName := firstNonEmptyString(
+		safeAIProviderDisplayValue(item.Name, fallbackIdentity, ""),
+		safeAIProviderDisplayValue(item.Provider, fallbackIdentity, ""),
+		identityType,
+		redact.APIKeyDisplayName(fallbackIdentity),
+	)
+	sourceKey := "provider:" + uintToString(item.ID)
+	if item.ID == 0 {
+		sourceKey = "provider:" + redact.APIKeyDisplayName(fallbackIdentity)
+	}
+	return usageSourceResolution{
+		DisplayName: displayName,
+		SourceType:  identityType,
+		SourceKey:   sourceKey,
+	}
+}
+
+func (r usageSourceResolver) rawSourceForPublicValue(value string) string {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return ""
+	}
+	if raw, ok := r.providerRawByKey[trimmed]; ok {
+		return raw
+	}
+	return trimmed
+}
+
+func (r usageSourceResolver) resolve(rawSource string, authIndex string) usageSourceResolution {
+	normalizedSource := strings.TrimSpace(rawSource)
+	if normalizedSource != "" {
+		if item, ok := r.providerIdentities[normalizedSource]; ok {
+			return usageSourceResolutionFromIdentity(item, normalizedSource)
+		}
+	}
+
+	normalizedAuthIndex := strings.TrimSpace(authIndex)
+	if normalizedAuthIndex != "" {
+		if identity, ok := r.authIdentities[normalizedAuthIndex]; ok {
+			displayName := firstNonEmptyString(identity.Name, normalizedAuthIndex)
+			return usageSourceResolution{
+				DisplayName: displayName,
+				SourceType:  firstNonEmptyString(identity.Type, identity.Provider),
+				SourceKey:   "auth:" + normalizedAuthIndex,
+			}
+		}
+	}
+
+	if normalizedSource == "" {
+		return usageSourceResolution{DisplayName: "-", SourceKey: "raw:-"}
+	}
+	if looksLikeEmail(normalizedSource) {
+		return usageSourceResolution{
+			DisplayName: normalizedSource,
+			SourceKey:   "email:" + normalizedSource,
+		}
+	}
+	if inferredProvider := inferUsageProviderType(normalizedSource); inferredProvider != "" {
+		return usageSourceResolution{
+			DisplayName: inferredProvider,
+			SourceType:  inferredProvider,
+			SourceKey:   "provider:fallback:" + inferredProvider,
+		}
+	}
+	masked := redact.APIKeyDisplayName(normalizedSource)
+	return usageSourceResolution{
+		DisplayName: masked,
+		SourceKey:   "raw:" + masked,
+	}
+}
+
+func uintToString(value uint) string {
+	return strconv.FormatUint(uint64(value), 10)
+}
+
+func firstNonEmptyString(values ...string) string {
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
+
+func looksLikeEmail(value string) bool {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return false
+	}
+	atIndex := strings.Index(trimmed, "@")
+	return atIndex > 0 && atIndex < len(trimmed)-1 && strings.Contains(trimmed[atIndex+1:], ".")
+}
+
+func inferUsageProviderType(source string) string {
+	value := strings.ToLower(strings.TrimSpace(source))
+	switch {
+	case value == "":
+		return ""
+	case strings.Contains(value, "ampcode"):
+		return "ampcode"
+	case strings.HasPrefix(value, "sk-ant-") || strings.Contains(value, "anthropic") || strings.Contains(value, "claude"):
+		return "claude"
+	case strings.HasPrefix(value, "sk-proj-") || strings.HasPrefix(value, "sk-") || strings.Contains(value, "openai") || strings.Contains(value, "gpt"):
+		return "openai"
+	case strings.HasPrefix(value, "aiza") || strings.Contains(value, "gemini"):
+		return "gemini"
+	case strings.Contains(value, "vertex"):
+		return "vertex"
+	case strings.Contains(value, "codex"):
+		return "codex"
+	default:
+		return ""
+	}
+}

internal/app/app.go

@@ -0,0 +1,217 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"sync"
+
+	"cpa-usage-keeper/internal/api"
+	"cpa-usage-keeper/internal/auth"
+	"cpa-usage-keeper/internal/config"
+	"cpa-usage-keeper/internal/cpa"
+	"cpa-usage-keeper/internal/logging"
+	"cpa-usage-keeper/internal/poller"
+	"cpa-usage-keeper/internal/repository"
+	"cpa-usage-keeper/internal/service"
+	webui "cpa-usage-keeper/web"
+	"github.com/gin-gonic/gin"
+	"github.com/sirupsen/logrus"
+	"gorm.io/gorm"
+)
+
+type Runner interface {
+	Run(ctx context.Context) error
+	Status() poller.Status
+	SyncNow(ctx context.Context) error
+}
+
+type Options struct {
+	EnvFile string
+}
+
+type App struct {
+	Config            *config.Config
+	DB                *gorm.DB
+	Router            *gin.Engine
+	Poller            Runner
+	Maintenance       *StorageCleanupRunner
+	MetadataSync      *MetadataSyncRunner
+	BackupMaintenance *DatabaseBackupRunner
+	LogCloser         io.Closer
+
+	backgroundCancel context.CancelFunc
+	backgroundWG     sync.WaitGroup
+}
+
+func New() (*App, error) {
+	return NewWithOptions(Options{})
+}
+
+func NewWithOptions(options Options) (*App, error) {
+	cfg, err := config.Load(config.LoadOptions{EnvFile: options.EnvFile})
+	if err != nil {
+		return nil, err
+	}
+
+	return NewWithConfig(*cfg)
+}
+
+func NewWithConfig(cfg config.Config) (*App, error) {
+	logCloser, err := logging.Configure(cfg)
+	if err != nil {
+		return nil, err
+	}
+
+	db, err := repository.OpenDatabase(cfg)
+	if err != nil {
+		_ = logCloser.Close()
+		return nil, err
+	}
+
+	syncService := service.NewSyncService(db, cfg)
+	backgroundPoller := poller.NewRedisDrain(syncService, poller.RedisDrainConfig{
+		IdleInterval: cfg.RedisQueueIdleInterval,
+		ErrorBackoff: cfg.RedisQueueErrorBackoff,
+	})
+	var backupMaintenance *DatabaseBackupRunner
+	if cfg.BackupEnabled {
+		sqlDB, err := db.DB()
+		if err != nil {
+			_ = closeGormDB(db)
+			_ = logCloser.Close()
+			return nil, err
+		}
+		backupStore := newDatabaseBackupStore(sqlDB, cfg.BackupDir)
+		backupMaintenance = NewDatabaseBackupRunner(backupStore, backupStore, cfg.BackupInterval, cfg.BackupRetentionDays)
+	}
+
+	usageService := service.NewUsageService(db)
+	usageIdentityService := service.NewUsageIdentityService(db)
+	pricingModelsClient := cpa.NewClient(cfg.CPABaseURL, cfg.CPAManagementKey, cfg.RequestTimeout)
+	pricingService := service.NewPricingService(db, pricingModelsClient)
+	sessionManager := auth.NewSessionManager(cfg.AuthSessionTTL)
+	authHandler := api.NewAuthHandler(api.AuthConfig{
+		Enabled:       cfg.AuthEnabled,
+		LoginPassword: cfg.LoginPassword,
+		SessionTTL:    cfg.AuthSessionTTL,
+		BasePath:      cfg.AppBasePath,
+	}, sessionManager)
+
+	return &App{
+		Config:            &cfg,
+		DB:                db,
+		Poller:            backgroundPoller,
+		Maintenance:       NewStorageCleanupRunner(syncService),
+		MetadataSync:      NewMetadataSyncRunner(syncService, cfg.MetadataSyncInterval),
+		BackupMaintenance: backupMaintenance,
+		LogCloser:         logCloser,
+		Router: api.NewRouter(
+			webui.Static,
+			newManualSyncRunner(backgroundPoller, syncService),
+			usageService,
+			pricingService,
+			api.AuthConfig{
+				Enabled:       cfg.AuthEnabled,
+				LoginPassword: cfg.LoginPassword,
+				SessionTTL:    cfg.AuthSessionTTL,
+				BasePath:      cfg.AppBasePath,
+			},
+			authHandler,
+			cfg.AppBasePath,
+			usageIdentityService,
+		),
+	}, nil
+}
+
+func closeGormDB(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		return err
+	}
+	return sqlDB.Close()
+}
+
+func (a *App) Close() error {
+	if a == nil {
+		return nil
+	}
+
+	a.stopBackgroundTasks()
+
+	var closeErr error
+	if a.DB != nil {
+		closeErr = errors.Join(closeErr, closeGormDB(a.DB))
+		a.DB = nil
+	}
+	if a.LogCloser != nil {
+		closeErr = errors.Join(closeErr, a.LogCloser.Close())
+		a.LogCloser = nil
+	}
+	return closeErr
+}
+
+func (a *App) Run() error {
+	if a == nil || a.Router == nil || a.Config == nil {
+		return fmt.Errorf("application is not initialized")
+	}
+
+	ctx := a.startBackgroundContext()
+	defer a.stopBackgroundTasks()
+	if a.Poller != nil {
+		a.startBackgroundTask(func() {
+			if err := a.Poller.Run(ctx); err != nil {
+				logrus.Errorf("poller stopped: %v", err)
+			}
+		})
+	}
+	if a.Maintenance != nil {
+		a.startBackgroundTask(func() {
+			if err := a.Maintenance.Run(ctx); err != nil {
+				logrus.Errorf("maintenance cleanup stopped: %v", err)
+			}
+		})
+	}
+	if a.MetadataSync != nil {
+		a.startBackgroundTask(func() {
+			if err := a.MetadataSync.Run(ctx); err != nil {
+				logrus.Errorf("metadata sync stopped: %v", err)
+			}
+		})
+	}
+	if a.BackupMaintenance != nil {
+		a.startBackgroundTask(func() {
+			if err := a.BackupMaintenance.Run(ctx); err != nil {
+				logrus.Errorf("database backup stopped: %v", err)
+			}
+		})
+	}
+
+	return a.Router.Run(":" + a.Config.AppPort)
+}
+
+func (a *App) startBackgroundContext() context.Context {
+	ctx, cancel := context.WithCancel(context.Background())
+	a.backgroundCancel = cancel
+	return ctx
+}
+
+func (a *App) startBackgroundTask(run func()) {
+	a.backgroundWG.Add(1)
+	go func() {
+		defer a.backgroundWG.Done()
+		run()
+	}()
+}
+
+func (a *App) stopBackgroundTasks() {
+	if a.backgroundCancel != nil {
+		a.backgroundCancel()
+		a.backgroundCancel = nil
+	}
+	a.backgroundWG.Wait()
+}

internal/app/app_test.go

@@ -0,0 +1,239 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"testing"
+	"time"
+
+	"cpa-usage-keeper/internal/config"
+	"cpa-usage-keeper/internal/poller"
+	"github.com/gin-gonic/gin"
+	"github.com/sirupsen/logrus"
+)
+
+func TestAppCloseClosesDatabase(t *testing.T) {
+	app, err := NewWithConfig(testAppConfig(t))
+	if err != nil {
+		t.Fatalf("NewWithConfig returned error: %v", err)
+	}
+	sqlDB, err := app.DB.DB()
+	if err != nil {
+		t.Fatalf("load sql db: %v", err)
+	}
+
+	if err := app.Close(); err != nil {
+		t.Fatalf("Close returned error: %v", err)
+	}
+
+	if err := sqlDB.Ping(); err == nil {
+		t.Fatal("expected database ping to fail after app close")
+	}
+}
+
+func TestNewWithConfigBuildsRedisDrainAndRouter(t *testing.T) {
+	app, err := NewWithConfig(testAppConfig(t))
+	if err != nil {
+		t.Fatalf("NewWithConfig returned error: %v", err)
+	}
+	defer app.Close()
+	if app.Poller == nil {
+		t.Fatal("expected poller to be initialized")
+	}
+	if app.Router == nil {
+		t.Fatal("expected router to be initialized")
+	}
+	if app.LogCloser == nil {
+		t.Fatal("expected log closer to be initialized")
+	}
+	if app.BackupMaintenance == nil {
+		t.Fatal("expected database backup runner to be initialized")
+	}
+	if app.MetadataSync == nil {
+		t.Fatal("expected metadata sync runner to be initialized")
+	}
+}
+
+func TestNewWithConfigSkipsBackupRunnerWhenDisabled(t *testing.T) {
+	cfg := testAppConfig(t)
+	cfg.BackupEnabled = false
+	app, err := NewWithConfig(cfg)
+	if err != nil {
+		t.Fatalf("NewWithConfig returned error: %v", err)
+	}
+	defer app.Close()
+	if app.BackupMaintenance != nil {
+		t.Fatal("expected database backup runner to be skipped when backups are disabled")
+	}
+}
+
+func TestNewWithConfigSelectsRedisDrain(t *testing.T) {
+	app, err := NewWithConfig(testAppConfig(t))
+	if err != nil {
+		t.Fatalf("NewWithConfig returned error: %v", err)
+	}
+	defer app.Close()
+	if _, ok := app.Poller.(*poller.RedisDrain); !ok {
+		t.Fatalf("expected redis to use redis drain, got %T", app.Poller)
+	}
+	if app.Maintenance == nil {
+		t.Fatal("expected maintenance cleanup runner to be initialized")
+	}
+}
+
+func TestNewWithConfigCreatesIndependentMaintenanceRunner(t *testing.T) {
+	app, err := NewWithConfig(testAppConfig(t))
+	if err != nil {
+		t.Fatalf("NewWithConfig returned error: %v", err)
+	}
+	defer app.Close()
+	if app.Poller == nil {
+		t.Fatal("expected sync poller to be initialized")
+	}
+	if app.Maintenance == nil {
+		t.Fatal("expected independent maintenance runner to be initialized")
+	}
+}
+
+func TestRunStartsPollerAndMaintenanceIndependently(t *testing.T) {
+	cfg := testAppConfig(t)
+	cfg.AppPort = "invalid-port"
+	pollerStarted := make(chan struct{})
+	maintenanceStarted := make(chan struct{})
+	metadataStarted := make(chan struct{})
+	backupStarted := make(chan struct{})
+	maintenance := NewStorageCleanupRunner(&maintenanceSyncStub{})
+	maintenance.sleep = func(context.Context, time.Duration) bool {
+		close(maintenanceStarted)
+		return false
+	}
+	metadataRunner := NewMetadataSyncRunner(&metadataSyncStub{}, time.Second)
+	metadataRunner.sleep = func(context.Context, time.Duration) bool {
+		close(metadataStarted)
+		return false
+	}
+	backupRunner := NewDatabaseBackupRunner(&databaseBackupWriterStub{}, nil, time.Second, 0)
+	backupRunner.sleep = func(context.Context, time.Duration) bool {
+		close(backupStarted)
+		return false
+	}
+	app := &App{
+		Config:            &cfg,
+		Router:            gin.New(),
+		Poller:            &appRunStub{started: pollerStarted},
+		Maintenance:       maintenance,
+		MetadataSync:      metadataRunner,
+		BackupMaintenance: backupRunner,
+	}
+
+	if err := app.Run(); err == nil {
+		t.Fatal("expected Run to return an error for invalid port")
+	}
+	select {
+	case <-pollerStarted:
+	case <-time.After(time.Second):
+		t.Fatal("expected poller runner to start")
+	}
+	select {
+	case <-maintenanceStarted:
+	case <-time.After(time.Second):
+		t.Fatal("expected maintenance runner to start")
+	}
+	select {
+	case <-metadataStarted:
+	case <-time.After(time.Second):
+		t.Fatal("expected metadata sync runner to start")
+	}
+	select {
+	case <-backupStarted:
+	case <-time.After(time.Second):
+		t.Fatal("expected database backup runner to start")
+	}
+}
+
+func TestRunCancelsBackgroundTasksWhenRouterStops(t *testing.T) {
+	cfg := testAppConfig(t)
+	cfg.AppPort = "invalid-port"
+	backupStarted := make(chan struct{})
+	backupCanceled := make(chan struct{})
+	backupRunner := NewDatabaseBackupRunner(&databaseBackupWriterStub{}, nil, time.Second, 0)
+	backupRunner.sleep = func(ctx context.Context, _ time.Duration) bool {
+		close(backupStarted)
+		<-ctx.Done()
+		close(backupCanceled)
+		return false
+	}
+	app := &App{
+		Config:            &cfg,
+		Router:            gin.New(),
+		BackupMaintenance: backupRunner,
+	}
+
+	if err := app.Run(); err == nil {
+		t.Fatal("expected Run to return an error for invalid port")
+	}
+	select {
+	case <-backupStarted:
+	case <-time.After(time.Second):
+		t.Fatal("expected database backup runner to start")
+	}
+	select {
+	case <-backupCanceled:
+	case <-time.After(time.Second):
+		t.Fatal("expected database backup runner context to be canceled")
+	}
+}
+
+type appRunStub struct {
+	started chan struct{}
+}
+
+func (s *appRunStub) Run(context.Context) error {
+	close(s.started)
+	return nil
+}
+
+func (s *appRunStub) Status() poller.Status {
+	return poller.Status{}
+}
+
+func (s *appRunStub) SyncNow(context.Context) error {
+	return nil
+}
+
+func captureAppInfoLogs(t *testing.T) *bytes.Buffer {
+	t.Helper()
+	var logs bytes.Buffer
+	previousOutput := logrus.StandardLogger().Out
+	previousFormatter := logrus.StandardLogger().Formatter
+	previousLevel := logrus.GetLevel()
+	logrus.SetOutput(&logs)
+	logrus.SetFormatter(&logrus.TextFormatter{DisableTimestamp: true})
+	logrus.SetLevel(logrus.InfoLevel)
+	t.Cleanup(func() {
+		logrus.SetOutput(previousOutput)
+		logrus.SetFormatter(previousFormatter)
+		logrus.SetLevel(previousLevel)
+	})
+	return &logs
+}
+
+func testAppConfig(t *testing.T) config.Config {
+	t.Helper()
+	return config.Config{
+		AppPort:                "8080",
+		CPABaseURL:             "https://cpa.example.com",
+		CPAManagementKey:       "secret",
+		RedisQueueIdleInterval: time.Second,
+		RedisQueueErrorBackoff: 10 * time.Second,
+		MetadataSyncInterval:   30 * time.Second,
+		SQLitePath:             t.TempDir() + "/app.db",
+		BackupEnabled:          true,
+		BackupDir:              t.TempDir() + "/backups",
+		BackupRetentionDays:    7,
+		RequestTimeout:         5 * time.Second,
+		LogLevel:               "info",
+		LogFileEnabled:         false,
+		LogRetentionDays:       7,
+	}
+}

internal/app/backup_runner.go

@@ -0,0 +1,218 @@
+package app
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"os"
+	"sync"
+	"time"
+
+	"cpa-usage-keeper/internal/backup"
+	"github.com/sirupsen/logrus"
+)
+
+type DatabaseBackupWriter interface {
+	WriteDatabase(context.Context, time.Time) (string, error)
+}
+
+type DatabaseBackupCleaner interface {
+	Cleanup(retentionDays int, now time.Time) (int, error)
+}
+
+type DatabaseBackupHistory interface {
+	LastBackupAt() (time.Time, bool, error)
+}
+
+type databaseBackupStore struct {
+	db     *sql.DB
+	dir    string
+	writer *backup.Writer
+}
+
+func newDatabaseBackupStore(db *sql.DB, dir string) *databaseBackupStore {
+	return &databaseBackupStore{db: db, dir: dir, writer: backup.NewWriter(dir)}
+}
+
+func (s *databaseBackupStore) WriteDatabase(ctx context.Context, backupAt time.Time) (string, error) {
+	return s.writer.WriteDatabase(ctx, s.db, backupAt)
+}
+
+func (s *databaseBackupStore) Cleanup(retentionDays int, now time.Time) (int, error) {
+	return s.writer.Cleanup(retentionDays, now)
+}
+
+func (s *databaseBackupStore) LastBackupAt() (time.Time, bool, error) {
+	files, err := backup.ListFiles(s.dir)
+	if err != nil {
+		return time.Time{}, false, err
+	}
+	var latest time.Time
+	for _, file := range files {
+		info, err := os.Stat(file)
+		if err != nil {
+			return time.Time{}, false, err
+		}
+		if info.ModTime().After(latest) {
+			latest = info.ModTime()
+		}
+	}
+	return latest, !latest.IsZero(), nil
+}
+
+type DatabaseBackupRunner struct {
+	writer        DatabaseBackupWriter
+	cleaner       DatabaseBackupCleaner
+	history       DatabaseBackupHistory
+	interval      time.Duration
+	retentionDays int
+	lastBackupAt  time.Time
+	retryDelay    time.Duration
+	retryAttempts int
+	pendingRetry  bool
+	now           func() time.Time
+	sleep         func(context.Context, time.Duration) bool
+
+	mu      sync.Mutex
+	running bool
+}
+
+func NewDatabaseBackupRunner(writer DatabaseBackupWriter, cleaner DatabaseBackupCleaner, interval time.Duration, retentionDays int) *DatabaseBackupRunner {
+	history, _ := writer.(DatabaseBackupHistory)
+	return &DatabaseBackupRunner{
+		writer:        writer,
+		cleaner:       cleaner,
+		history:       history,
+		interval:      interval,
+		retentionDays: retentionDays,
+		retryDelay:    15 * time.Minute,
+		now:           time.Now,
+		sleep:         maintenanceSleepContext,
+	}
+}
+
+func (r *DatabaseBackupRunner) Run(ctx context.Context) error {
+	if err := r.validate(); err != nil {
+		return err
+	}
+	logrus.Info("database backup task started")
+	r.setRunning(true)
+	defer r.setRunning(false)
+
+	for {
+		now := r.now()
+		delay := r.nextDelay(now)
+		if delay < 0 {
+			delay = 0
+		}
+		if !r.sleep(ctx, delay) {
+			return nil
+		}
+		backupAt := r.now()
+		if _, err := r.writer.WriteDatabase(ctx, backupAt); err != nil {
+			logrus.WithError(err).Error("database backup failed")
+			r.retryAttempts++
+			r.pendingRetry = r.retryAttempts <= 3
+		} else {
+			r.lastBackupAt = backupAt
+			r.retryAttempts = 0
+			r.pendingRetry = false
+		}
+		r.cleanup(backupAt)
+	}
+}
+
+func (r *DatabaseBackupRunner) nextDelay(now time.Time) time.Duration {
+	if r.pendingRetry {
+		return r.retryDelay
+	}
+	if r.usesDailySchedule() {
+		return r.nextDailyDelay(now)
+	}
+	lastBackupAt, ok := r.lastBackupAtFromHistory()
+	if !ok {
+		return 0
+	}
+	return lastBackupAt.Add(r.interval).Sub(now)
+}
+
+func (r *DatabaseBackupRunner) cleanup(now time.Time) {
+	if r.cleaner == nil || r.retentionDays <= 0 {
+		return
+	}
+	if _, err := r.cleaner.Cleanup(r.retentionDays, now); err != nil {
+		logrus.WithError(err).Error("database backup cleanup failed")
+	}
+}
+
+func (r *DatabaseBackupRunner) nextDailyDelay(now time.Time) time.Duration {
+	localNow := now.In(time.Local)
+	nextBackupAt := nextDailyBackupAt(localNow)
+	if lastBackupAt, ok := r.lastBackupAtFromHistory(); ok {
+		lastLocalBackup := lastBackupAt.In(time.Local)
+		lastBackupDay := time.Date(lastLocalBackup.Year(), lastLocalBackup.Month(), lastLocalBackup.Day(), 4, 0, 0, 0, time.Local)
+		candidate := lastBackupDay.AddDate(0, 0, r.dailyScheduleDays())
+		if localNow.Before(candidate) {
+			nextBackupAt = candidate
+		}
+	}
+	return nextBackupAt.Sub(localNow)
+}
+
+func (r *DatabaseBackupRunner) usesDailySchedule() bool {
+	return r.interval >= 24*time.Hour && r.interval%(24*time.Hour) == 0
+}
+
+func (r *DatabaseBackupRunner) dailyScheduleDays() int {
+	return int(r.interval / (24 * time.Hour))
+}
+
+func (r *DatabaseBackupRunner) lastBackupAtFromHistory() (time.Time, bool) {
+	lastBackupAt := r.lastBackupAt
+	if r.history != nil {
+		storedBackupAt, ok, err := r.history.LastBackupAt()
+		if err != nil {
+			logrus.WithError(err).Error("load last database backup time failed")
+		} else if ok && storedBackupAt.After(lastBackupAt) {
+			lastBackupAt = storedBackupAt
+		}
+	}
+	return lastBackupAt, !lastBackupAt.IsZero()
+}
+
+func nextDailyBackupAt(now time.Time) time.Time {
+	localNow := now.In(time.Local)
+	backupAt := time.Date(localNow.Year(), localNow.Month(), localNow.Day(), 4, 0, 0, 0, time.Local)
+	if !localNow.Before(backupAt) {
+		backupAt = backupAt.AddDate(0, 0, 1)
+	}
+	return backupAt
+}
+
+func (r *DatabaseBackupRunner) validate() error {
+	if r == nil {
+		return fmt.Errorf("database backup runner is nil")
+	}
+	if r.writer == nil {
+		return fmt.Errorf("database backup writer is nil")
+	}
+	if r.interval <= 0 {
+		return fmt.Errorf("database backup interval must be positive")
+	}
+	if r.retryDelay <= 0 {
+		r.retryDelay = 15 * time.Minute
+	}
+	if r.now == nil {
+		r.now = time.Now
+	}
+	if r.sleep == nil {
+		r.sleep = maintenanceSleepContext
+	}
+	return nil
+}
+
+func (r *DatabaseBackupRunner) setRunning(running bool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.running = running
+}

internal/app/backup_runner_test.go

@@ -0,0 +1,264 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestNextDailyBackupAtUsesLocal0400(t *testing.T) {
+	previousLocal := time.Local
+	time.Local = time.FixedZone("Test/Local", 8*60*60)
+	t.Cleanup(func() { time.Local = previousLocal })
+
+	before := time.Date(2026, 4, 16, 3, 30, 0, 0, time.Local)
+	if got := nextDailyBackupAt(before); !got.Equal(time.Date(2026, 4, 16, 4, 0, 0, 0, time.Local)) {
+		t.Fatalf("expected same-day 04:00 backup, got %s", got)
+	}
+	after := time.Date(2026, 4, 16, 4, 1, 0, 0, time.Local)
+	if got := nextDailyBackupAt(after); !got.Equal(time.Date(2026, 4, 17, 4, 0, 0, 0, time.Local)) {
+		t.Fatalf("expected next-day 04:00 backup, got %s", got)
+	}
+}
+
+func TestDatabaseBackupRunnerRunsAtScheduledTime(t *testing.T) {
+	writer := &databaseBackupWriterStub{}
+	cleaner := &databaseBackupCleanerStub{}
+	runner := NewDatabaseBackupRunner(writer, cleaner, 24*time.Hour, 30)
+	now := time.Date(2026, 4, 16, 3, 45, 0, 0, time.Local)
+	runner.now = func() time.Time { return now }
+	sleepCalls := 0
+	runner.sleep = func(context.Context, time.Duration) bool {
+		sleepCalls++
+		if sleepCalls == 1 {
+			return true
+		}
+		return false
+	}
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	if writer.calls != 1 {
+		t.Fatalf("expected one database backup, got %d", writer.calls)
+	}
+	if cleaner.calls != 1 {
+		t.Fatalf("expected one backup cleanup, got %d", cleaner.calls)
+	}
+	if cleaner.retentionDays != 30 {
+		t.Fatalf("expected cleanup retention 30, got %d", cleaner.retentionDays)
+	}
+}
+
+func TestDatabaseBackupRunnerWaitsUntilNext0400AfterDailyScheduleWithoutTodaysBackup(t *testing.T) {
+	writer := &databaseBackupWriterStub{}
+	runner := NewDatabaseBackupRunner(writer, nil, 24*time.Hour, 0)
+	now := time.Date(2026, 4, 16, 4, 5, 0, 0, time.Local)
+	writer.lastBackupAt = now.AddDate(0, 0, -1)
+	runner.now = func() time.Time { return now }
+	var delay time.Duration
+	runner.sleep = func(_ context.Context, d time.Duration) bool {
+		delay = d
+		return false
+	}
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	expected := time.Date(2026, 4, 17, 4, 0, 0, 0, time.Local).Sub(now)
+	if delay != expected {
+		t.Fatalf("expected next 04:00 backup delay %s, got %s", expected, delay)
+	}
+}
+
+func TestDatabaseBackupRunnerWaitsUntilTomorrowAfterTodaysDailyBackup(t *testing.T) {
+	writer := &databaseBackupWriterStub{}
+	runner := NewDatabaseBackupRunner(writer, nil, 24*time.Hour, 0)
+	now := time.Date(2026, 4, 16, 4, 5, 0, 0, time.Local)
+	writer.lastBackupAt = time.Date(2026, 4, 16, 4, 0, 0, 0, time.Local)
+	runner.now = func() time.Time { return now }
+	var delay time.Duration
+	runner.sleep = func(_ context.Context, d time.Duration) bool {
+		delay = d
+		return false
+	}
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	expected := time.Date(2026, 4, 17, 4, 0, 0, 0, time.Local).Sub(now)
+	if delay != expected {
+		t.Fatalf("expected next daily backup delay %s, got %s", expected, delay)
+	}
+}
+
+func TestDatabaseBackupRunnerUsesDailyScheduleForMultipleOf24Hours(t *testing.T) {
+	writer := &databaseBackupWriterStub{}
+	runner := NewDatabaseBackupRunner(writer, nil, 48*time.Hour, 0)
+	now := time.Date(2026, 4, 16, 4, 5, 0, 0, time.Local)
+	writer.lastBackupAt = time.Date(2026, 4, 15, 10, 0, 0, 0, time.Local)
+	runner.now = func() time.Time { return now }
+	var delay time.Duration
+	runner.sleep = func(_ context.Context, d time.Duration) bool {
+		delay = d
+		return false
+	}
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	expected := time.Date(2026, 4, 17, 4, 0, 0, 0, time.Local).Sub(now)
+	if delay != expected {
+		t.Fatalf("expected next 48h daily schedule delay %s, got %s", expected, delay)
+	}
+}
+
+func TestDatabaseBackupRunnerUsesExistingBackupForIntervalSchedule(t *testing.T) {
+	writer := &databaseBackupWriterStub{}
+	runner := NewDatabaseBackupRunner(writer, nil, 10*time.Second, 0)
+	now := time.Date(2026, 4, 16, 3, 45, 0, 0, time.Local)
+	writer.lastBackupAt = now.Add(-4 * time.Second)
+	runner.now = func() time.Time { return now }
+	var delays []time.Duration
+	sleepCalls := 0
+	runner.sleep = func(_ context.Context, d time.Duration) bool {
+		sleepCalls++
+		delays = append(delays, d)
+		return sleepCalls == 1
+	}
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	if len(delays) == 0 || delays[0] != 6*time.Second {
+		t.Fatalf("expected first interval delay 6s, got %+v", delays)
+	}
+	if writer.calls != 1 {
+		t.Fatalf("expected one database backup, got %d", writer.calls)
+	}
+}
+
+func TestDatabaseBackupRunnerRunsImmediatelyWhenIntervalBackupIsExpired(t *testing.T) {
+	writer := &databaseBackupWriterStub{}
+	runner := NewDatabaseBackupRunner(writer, nil, 10*time.Second, 0)
+	now := time.Date(2026, 4, 16, 3, 45, 0, 0, time.Local)
+	writer.lastBackupAt = now.Add(-11 * time.Second)
+	runner.now = func() time.Time { return now }
+	var delays []time.Duration
+	sleepCalls := 0
+	runner.sleep = func(_ context.Context, d time.Duration) bool {
+		sleepCalls++
+		delays = append(delays, d)
+		return sleepCalls == 1
+	}
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	if len(delays) == 0 || delays[0] != 0 {
+		t.Fatalf("expected immediate backup for expired interval, got delays %+v", delays)
+	}
+}
+
+func TestDatabaseBackupRunnerCleansAfterBackupFailure(t *testing.T) {
+	logs := captureAppInfoLogs(t)
+	writer := &databaseBackupWriterStub{err: errors.New("disk full")}
+	cleaner := &databaseBackupCleanerStub{}
+	runner := NewDatabaseBackupRunner(writer, cleaner, time.Second, 30)
+	runner.now = func() time.Time { return time.Date(2026, 4, 16, 3, 45, 0, 0, time.Local) }
+	sleepCalls := 0
+	runner.sleep = func(context.Context, time.Duration) bool {
+		sleepCalls++
+		return sleepCalls == 1
+	}
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	if writer.calls != 1 {
+		t.Fatalf("expected one database backup attempt, got %d", writer.calls)
+	}
+	if cleaner.calls != 1 {
+		t.Fatalf("expected cleanup after failed backup, got %d calls", cleaner.calls)
+	}
+	content := logs.String()
+	if !strings.Contains(content, "level=error") || !strings.Contains(content, "msg=\"database backup failed\"") {
+		t.Fatalf("expected database backup failure error log, got %q", content)
+	}
+}
+
+func TestDatabaseBackupRunnerRetriesDailyBackupAfterFailure(t *testing.T) {
+	writer := &databaseBackupWriterStub{err: errors.New("temporary failure")}
+	runner := NewDatabaseBackupRunner(writer, nil, 24*time.Hour, 0)
+	now := time.Date(2026, 4, 16, 3, 59, 0, 0, time.Local)
+	runner.now = func() time.Time { return now }
+	var delays []time.Duration
+	sleepCalls := 0
+	runner.sleep = func(_ context.Context, d time.Duration) bool {
+		delays = append(delays, d)
+		sleepCalls++
+		switch sleepCalls {
+		case 1:
+			now = time.Date(2026, 4, 16, 4, 0, 0, 0, time.Local)
+		case 2:
+			now = time.Date(2026, 4, 16, 4, 15, 0, 0, time.Local)
+		case 3:
+			now = time.Date(2026, 4, 16, 4, 30, 0, 0, time.Local)
+		case 4:
+			now = time.Date(2026, 4, 16, 4, 45, 0, 0, time.Local)
+		default:
+			return false
+		}
+		return true
+	}
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+	expectedDelays := []time.Duration{time.Minute, 15 * time.Minute, 15 * time.Minute, 15 * time.Minute, 23*time.Hour + 15*time.Minute}
+	if len(delays) != len(expectedDelays) {
+		t.Fatalf("expected delays %+v, got %+v", expectedDelays, delays)
+	}
+	for i, expected := range expectedDelays {
+		if delays[i] != expected {
+			t.Fatalf("expected delay %d to be %s, got %s", i, expected, delays[i])
+		}
+	}
+	if writer.calls != 4 {
+		t.Fatalf("expected initial attempt plus 3 retries, got %d attempts", writer.calls)
+	}
+}
+
+type databaseBackupWriterStub struct {
+	calls        int
+	err          error
+	lastBackupAt time.Time
+}
+
+func (s *databaseBackupWriterStub) WriteDatabase(_ context.Context, backupAt time.Time) (string, error) {
+	s.calls++
+	if s.err == nil {
+		s.lastBackupAt = backupAt
+	}
+	return "/tmp/database.db", s.err
+}
+
+func (s *databaseBackupWriterStub) LastBackupAt() (time.Time, bool, error) {
+	return s.lastBackupAt, !s.lastBackupAt.IsZero(), nil
+}
+
+type databaseBackupCleanerStub struct {
+	calls         int
+	retentionDays int
+	now           time.Time
+	err           error
+}
+
+func (s *databaseBackupCleanerStub) Cleanup(retentionDays int, now time.Time) (int, error) {
+	s.calls++
+	s.retentionDays = retentionDays
+	s.now = now
+	return 0, s.err
+}

internal/app/maintenance.go

@@ -0,0 +1,98 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/sirupsen/logrus"
+)
+
+type StorageCleanupSyncer interface {
+	CleanupStorage(ctx context.Context) error
+}
+
+type StorageCleanupRunner struct {
+	syncer StorageCleanupSyncer
+	now    func() time.Time
+	sleep  func(context.Context, time.Duration) bool
+
+	mu      sync.Mutex
+	running bool
+}
+
+func NewStorageCleanupRunner(syncer StorageCleanupSyncer) *StorageCleanupRunner {
+	return &StorageCleanupRunner{
+		syncer: syncer,
+		now:    time.Now,
+		sleep:  maintenanceSleepContext,
+	}
+}
+
+// Run 每天按项目本地时区 03:00 执行一次统一存储清理，失败只记录日志，不终止后台任务。
+func (r *StorageCleanupRunner) Run(ctx context.Context) error {
+	if err := r.validate(); err != nil {
+		return err
+	}
+	logrus.Info("storage cleanup task started")
+	r.setRunning(true)
+	defer r.setRunning(false)
+
+	for {
+		now := r.now()
+		delay := nextDailyCleanupAt(now).Sub(now)
+		if delay < 0 {
+			delay = 0
+		}
+		if !r.sleep(ctx, delay) {
+			return nil
+		}
+		if err := r.syncer.CleanupStorage(ctx); err != nil {
+			logrus.WithError(err).Error("storage cleanup failed")
+		}
+	}
+}
+
+// nextDailyCleanupAt 用 time.Local 计算下一次 03:00，因此 TZ 同时控制业务日期边界和清理触发时间。
+func nextDailyCleanupAt(now time.Time) time.Time {
+	localNow := now.In(time.Local)
+	cleanupAt := time.Date(localNow.Year(), localNow.Month(), localNow.Day(), 3, 0, 0, 0, time.Local)
+	if !localNow.Before(cleanupAt) {
+		cleanupAt = cleanupAt.AddDate(0, 0, 1)
+	}
+	return cleanupAt
+}
+
+func (r *StorageCleanupRunner) validate() error {
+	if r == nil {
+		return fmt.Errorf("storage cleanup runner is nil")
+	}
+	if r.syncer == nil {
+		return fmt.Errorf("storage cleanup syncer is nil")
+	}
+	if r.now == nil {
+		r.now = time.Now
+	}
+	if r.sleep == nil {
+		r.sleep = maintenanceSleepContext
+	}
+	return nil
+}
+
+func maintenanceSleepContext(ctx context.Context, d time.Duration) bool {
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return false
+	case <-timer.C:
+		return true
+	}
+}
+
+func (r *StorageCleanupRunner) setRunning(running bool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.running = running
+}

internal/app/maintenance_test.go

@@ -0,0 +1,107 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sirupsen/logrus"
+)
+
+type maintenanceSyncStub struct {
+	cleanupCalls int
+}
+
+func (s *maintenanceSyncStub) CleanupStorage(context.Context) error {
+	s.cleanupCalls++
+	return nil
+}
+
+func TestNextDailyCleanupAtUsesLocalThreeAM(t *testing.T) {
+	previousLocal := time.Local
+	location, err := time.LoadLocation("Asia/Shanghai")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	time.Local = location
+	t.Cleanup(func() { time.Local = previousLocal })
+
+	before := nextDailyCleanupAt(time.Date(2026, 4, 26, 18, 30, 0, 0, time.UTC))
+	if !before.Equal(time.Date(2026, 4, 26, 19, 0, 0, 0, time.UTC)) {
+		t.Fatalf("expected same local day 03:00 cleanup, got %s", before)
+	}
+	after := nextDailyCleanupAt(time.Date(2026, 4, 26, 20, 30, 0, 0, time.UTC))
+	if !after.Equal(time.Date(2026, 4, 27, 19, 0, 0, 0, time.UTC)) {
+		t.Fatalf("expected next local day 03:00 cleanup, got %s", after)
+	}
+}
+
+func TestStorageCleanupRunnerLogsTaskStart(t *testing.T) {
+	logs := captureMaintenanceInfoLogs(t)
+	syncer := &maintenanceSyncStub{}
+	runner := NewStorageCleanupRunner(syncer)
+	runner.now = func() time.Time { return time.Date(2026, 4, 26, 18, 30, 0, 0, time.UTC) }
+	runner.sleep = func(context.Context, time.Duration) bool { return false }
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatalf("cleanup runner returned error: %v", err)
+	}
+
+	content := logs.String()
+	if !strings.Contains(content, "level=info") || !strings.Contains(content, "msg=\"storage cleanup task started\"") {
+		t.Fatalf("expected storage cleanup start info log, got %q", content)
+	}
+}
+
+func TestStorageCleanupRunnerRunsAtScheduledTime(t *testing.T) {
+	syncer := &maintenanceSyncStub{}
+	runner := NewStorageCleanupRunner(syncer)
+	previousLocal := time.Local
+	location, err := time.LoadLocation("Asia/Shanghai")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	time.Local = location
+	t.Cleanup(func() { time.Local = previousLocal })
+	runner.now = func() time.Time { return time.Date(2026, 4, 26, 18, 30, 0, 0, time.UTC) }
+	ctx, cancel := context.WithCancel(context.Background())
+	calls := 0
+	runner.sleep = func(_ context.Context, d time.Duration) bool {
+		calls++
+		if calls == 1 {
+			if d != 30*time.Minute {
+				t.Fatalf("expected cleanup sleep until local 03:00, got %s", d)
+			}
+			return true
+		}
+		cancel()
+		return false
+	}
+
+	if err := runner.Run(ctx); err != nil {
+		t.Fatalf("cleanup runner returned error: %v", err)
+	}
+
+	if syncer.cleanupCalls != 1 {
+		t.Fatalf("expected cleanup loop to run once, got %d", syncer.cleanupCalls)
+	}
+}
+
+func captureMaintenanceInfoLogs(t *testing.T) *bytes.Buffer {
+	t.Helper()
+	var logs bytes.Buffer
+	previousOutput := logrus.StandardLogger().Out
+	previousFormatter := logrus.StandardLogger().Formatter
+	previousLevel := logrus.GetLevel()
+	logrus.SetOutput(&logs)
+	logrus.SetFormatter(&logrus.TextFormatter{DisableTimestamp: true})
+	logrus.SetLevel(logrus.InfoLevel)
+	t.Cleanup(func() {
+		logrus.SetOutput(previousOutput)
+		logrus.SetFormatter(previousFormatter)
+		logrus.SetLevel(previousLevel)
+	})
+	return &logs
+}

internal/app/manual_sync.go

@@ -0,0 +1,60 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"cpa-usage-keeper/internal/poller"
+)
+
+type manualSyncRunner struct {
+	redis    Runner
+	metadata MetadataSyncer
+}
+
+type manualSyncStageError struct {
+	message string
+	err     error
+}
+
+func (e manualSyncStageError) Error() string {
+	return fmt.Sprintf("%s: %v", e.message, e.err)
+}
+
+func (e manualSyncStageError) Unwrap() error {
+	return e.err
+}
+
+func (e manualSyncStageError) UserMessage() string {
+	return e.message
+}
+
+func newManualSyncRunner(redis Runner, metadata MetadataSyncer) *manualSyncRunner {
+	return &manualSyncRunner{redis: redis, metadata: metadata}
+}
+
+func (r *manualSyncRunner) Status() poller.Status {
+	if r == nil || r.redis == nil {
+		return poller.Status{}
+	}
+	return r.redis.Status()
+}
+
+func (r *manualSyncRunner) SyncNow(ctx context.Context) error {
+	if r == nil {
+		return fmt.Errorf("manual sync runner is nil")
+	}
+	if r.redis == nil {
+		return fmt.Errorf("manual redis syncer is nil")
+	}
+	if err := r.redis.SyncNow(ctx); err != nil {
+		return manualSyncStageError{message: "redis sync failed", err: err}
+	}
+	if r.metadata == nil {
+		return fmt.Errorf("manual metadata syncer is nil")
+	}
+	if err := r.metadata.SyncMetadata(ctx); err != nil {
+		return manualSyncStageError{message: "metadata sync failed", err: err}
+	}
+	return nil
+}

internal/app/manual_sync_test.go

@@ -0,0 +1,100 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+
+	"cpa-usage-keeper/internal/poller"
+)
+
+type manualRedisSyncStub struct {
+	status poller.Status
+	err    error
+	calls  int
+	order  *[]string
+}
+
+func (s *manualRedisSyncStub) Run(context.Context) error {
+	return nil
+}
+
+func (s *manualRedisSyncStub) Status() poller.Status {
+	return s.status
+}
+
+func (s *manualRedisSyncStub) SyncNow(context.Context) error {
+	s.calls++
+	if s.order != nil {
+		*s.order = append(*s.order, "redis")
+	}
+	return s.err
+}
+
+type manualMetadataSyncStub struct {
+	err   error
+	calls int
+	order *[]string
+}
+
+func (s *manualMetadataSyncStub) SyncMetadata(context.Context) error {
+	s.calls++
+	if s.order != nil {
+		*s.order = append(*s.order, "metadata")
+	}
+	return s.err
+}
+
+func TestManualSyncRunnerRunsRedisThenMetadata(t *testing.T) {
+	var order []string
+	redis := &manualRedisSyncStub{status: poller.Status{LastStatus: "completed"}, order: &order}
+	metadata := &manualMetadataSyncStub{order: &order}
+	runner := newManualSyncRunner(redis, metadata)
+
+	if err := runner.SyncNow(context.Background()); err != nil {
+		t.Fatalf("SyncNow returned error: %v", err)
+	}
+	if !reflect.DeepEqual(order, []string{"redis", "metadata"}) {
+		t.Fatalf("expected redis then metadata sync, got %v", order)
+	}
+	if runner.Status().LastStatus != "completed" {
+		t.Fatalf("expected status to delegate to redis runner, got %+v", runner.Status())
+	}
+}
+
+func TestManualSyncRunnerReturnsRedisErrorWithoutMetadata(t *testing.T) {
+	redisErr := errors.New("redis failed")
+	redis := &manualRedisSyncStub{err: redisErr}
+	metadata := &manualMetadataSyncStub{}
+	runner := newManualSyncRunner(redis, metadata)
+
+	err := runner.SyncNow(context.Background())
+	if !errors.Is(err, redisErr) {
+		t.Fatalf("expected redis error, got %v", err)
+	}
+	if err == nil || err.Error() != "redis sync failed: redis failed" {
+		t.Fatalf("expected redis-specific sync error, got %v", err)
+	}
+	if metadata.calls != 0 {
+		t.Fatalf("expected metadata sync not to run after redis failure, got %d calls", metadata.calls)
+	}
+}
+
+func TestManualSyncRunnerReturnsMetadataError(t *testing.T) {
+	metadataErr := errors.New("metadata failed")
+	redis := &manualRedisSyncStub{}
+	metadata := &manualMetadataSyncStub{err: metadataErr}
+	runner := newManualSyncRunner(redis, metadata)
+
+	err := runner.SyncNow(context.Background())
+	if !errors.Is(err, metadataErr) {
+		t.Fatalf("expected metadata error, got %v", err)
+	}
+	if err == nil || err.Error() != "metadata sync failed: metadata failed" {
+		t.Fatalf("expected metadata-specific sync error, got %v", err)
+	}
+	if redis.calls != 1 || metadata.calls != 1 {
+		t.Fatalf("expected redis and metadata to run once, got redis=%d metadata=%d", redis.calls, metadata.calls)
+	}
+}

internal/app/metadata_sync.go

@@ -0,0 +1,74 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/sirupsen/logrus"
+)
+
+type MetadataSyncer interface {
+	SyncMetadata(ctx context.Context) error
+}
+
+type MetadataSyncRunner struct {
+	syncer   MetadataSyncer
+	interval time.Duration
+	sleep    func(context.Context, time.Duration) bool
+
+	mu      sync.Mutex
+	running bool
+}
+
+func NewMetadataSyncRunner(syncer MetadataSyncer, interval time.Duration) *MetadataSyncRunner {
+	return &MetadataSyncRunner{
+		syncer:   syncer,
+		interval: interval,
+		sleep:    maintenanceSleepContext,
+	}
+}
+
+// Run 启动独立 metadata 同步任务：启动后立即执行一次，之后按固定间隔刷新 auth files 和 provider metadata。
+func (r *MetadataSyncRunner) Run(ctx context.Context) error {
+	if err := r.validate(); err != nil {
+		return err
+	}
+	logrus.Info("metadata sync task started")
+	r.setRunning(true)
+	defer r.setRunning(false)
+
+	delay := time.Duration(0)
+	for {
+		if !r.sleep(ctx, delay) {
+			return nil
+		}
+		if err := r.syncer.SyncMetadata(ctx); err != nil {
+			logrus.WithError(err).Error("metadata sync failed")
+		}
+		delay = r.interval
+	}
+}
+
+func (r *MetadataSyncRunner) validate() error {
+	if r == nil {
+		return fmt.Errorf("metadata sync runner is nil")
+	}
+	if r.syncer == nil {
+		return fmt.Errorf("metadata syncer is nil")
+	}
+	if r.interval <= 0 {
+		return fmt.Errorf("metadata sync interval must be positive")
+	}
+	if r.sleep == nil {
+		r.sleep = maintenanceSleepContext
+	}
+	return nil
+}
+
+func (r *MetadataSyncRunner) setRunning(running bool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.running = running
+}