feat: 统计数据优化 - 支持细粒度时间范围和多维度分析

- 新增 StatsHourly/StatsDaily 预聚合表，支持任意时区的精确统计
- 实现 UTC datetime 范围查询策略，边界数据实时聚合
- 新增统计 API：用户/API Key 维度、成本分析、性能百分位、错误分类
- 新增前端页面：成本分析、性能分析、用户统计
- 新增 TimeRangePicker 组件和统计可视化组件
- 优化 Dashboard 和 Usage 页面支持时间范围筛选

Close #135

src/api/admin/__init__.py

@@ -15,6 +15,7 @@ from .provider_query import router as provider_query_router
 from .provider_strategy import router as provider_strategy_router
 from .providers import router as providers_router
 from .security import router as security_router
+from .stats import router as stats_router
 from .system import router as system_router
 from .usage import router as usage_router
 from .users import router as users_router
@@ -33,6 +34,7 @@ router.include_router(provider_strategy_router)
 router.include_router(adaptive_router)
 router.include_router(models_router)
 router.include_router(security_router)
+router.include_router(stats_router)
 router.include_router(provider_query_router)
 router.include_router(management_tokens_router)
 router.include_router(modules_router)

src/api/admin/stats/__init__.py

@@ -0,0 +1,22 @@
+"""Stats admin routes export."""
+
+from fastapi import APIRouter
+
+from .comparison import router as comparison_router
+from .cost import router as cost_router
+from .errors import router as errors_router
+from .leaderboard import router as leaderboard_router
+from .performance import router as performance_router
+from .quota import router as quota_router
+from .time_series import router as time_series_router
+
+router = APIRouter(prefix="/api/admin/stats", tags=["Admin - Stats"])
+router.include_router(leaderboard_router)
+router.include_router(time_series_router)
+router.include_router(cost_router)
+router.include_router(quota_router)
+router.include_router(performance_router)
+router.include_router(errors_router)
+router.include_router(comparison_router)
+
+__all__ = ["router"]

src/api/admin/stats/common.py

@@ -0,0 +1,196 @@
+"""Shared helpers for admin stats routes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import date, datetime, time, timedelta, timezone
+from typing import Any, Literal
+
+from fastapi import HTTPException
+from sqlalchemy import and_, or_
+
+from src.api.base.pipeline import ApiRequestPipeline
+from src.config.settings import config
+from src.models.database import Usage
+from src.services.system.time_range import TimeRangeParams
+
+pipeline = ApiRequestPipeline()
+
+
+def _apply_admin_default_range(
+    params: TimeRangeParams | None,
+) -> TimeRangeParams | None:
+    """Apply a default range to avoid unbounded scans."""
+    if params is not None:
+        return params
+
+    days = int(getattr(config, "admin_usage_default_days", 0) or 0)
+    if days <= 0:
+        return None
+
+    today = datetime.now(timezone.utc).date()
+    start_date = today - timedelta(days=days - 1)
+    return TimeRangeParams(
+        start_date=start_date,
+        end_date=today,
+        timezone="UTC",
+        tz_offset_minutes=0,
+    ).validate_and_resolve()
+
+
+def _build_time_range_params(
+    start_date: date | None,
+    end_date: date | None,
+    preset: str | None,
+    timezone_name: str | None,
+    tz_offset_minutes: int | None,
+) -> TimeRangeParams | None:
+    if not preset and start_date is None and end_date is None:
+        return None
+    try:
+        return TimeRangeParams(
+            start_date=start_date,
+            end_date=end_date,
+            preset=preset,
+            timezone=timezone_name,
+            tz_offset_minutes=tz_offset_minutes or 0,
+        ).validate_and_resolve()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+def _hash_filters(filters: dict[str, Any]) -> str:
+    raw = json.dumps(filters, sort_keys=True, ensure_ascii=False, default=str)
+    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def _build_time_range_from_days(
+    days: int, timezone_name: str | None, tz_offset_minutes: int | None
+) -> TimeRangeParams:
+    base = TimeRangeParams(
+        preset="today",
+        timezone=timezone_name,
+        tz_offset_minutes=tz_offset_minutes or 0,
+    ).validate_and_resolve()
+    user_today = base.start_date
+    start_date = user_today - timedelta(days=days - 1)
+    return TimeRangeParams(
+        start_date=start_date,
+        end_date=user_today,
+        timezone=timezone_name,
+        tz_offset_minutes=tz_offset_minutes or 0,
+    ).validate_and_resolve()
+
+
+def _linear_regression(values: list[float]) -> tuple[float, float]:
+    n = len(values)
+    if n <= 1:
+        return 0.0, values[0] if values else 0.0
+    xs = list(range(n))
+    sum_x = sum(xs)
+    sum_y = sum(values)
+    sum_x2 = sum(x * x for x in xs)
+    sum_xy = sum(x * y for x, y in zip(xs, values))
+    denom = n * sum_x2 - sum_x * sum_x
+    if denom == 0:
+        return 0.0, values[-1]
+    slope = (n * sum_xy - sum_x * sum_y) / denom
+    intercept = (sum_y - slope * sum_x) / n
+    return slope, intercept
+
+
+def _build_cache_key(
+    leaderboard_type: str,
+    metric: str,
+    time_range: TimeRangeParams | None,
+    filters: dict[str, Any],
+) -> str:
+    start_value = time_range.start_date.isoformat() if time_range else "all"
+    end_value = time_range.end_date.isoformat() if time_range else "all"
+    tz_value = time_range.timezone if time_range else "utc"
+    offset_value = time_range.tz_offset_minutes if time_range else 0
+    return (
+        f"leaderboard:{leaderboard_type}:{metric}:{start_value}:{end_value}:"
+        f"{tz_value}:{offset_value}:{_hash_filters(filters)}"
+    )
+
+
+def _is_today_range(time_range: TimeRangeParams | None) -> bool:
+    if not time_range:
+        return False
+    try:
+        user_today = time_range._get_user_today()
+    except Exception:
+        return False
+    return time_range.end_date == user_today
+
+
+def _split_daily_and_usage_segments(
+    time_range: TimeRangeParams | None,
+    use_daily: bool,
+) -> tuple[tuple[datetime, datetime] | None, list[tuple[datetime, datetime]] | None]:
+    if not time_range:
+        return None, None
+
+    start_utc, end_utc = time_range.to_utc_datetime_range()
+    if not use_daily:
+        return None, [(start_utc, end_utc)]
+
+    complete_dates, head_boundary, tail_boundary = time_range.get_complete_utc_dates()
+    daily_range = None
+    if complete_dates:
+        daily_start = datetime.combine(complete_dates[0], time.min, tzinfo=timezone.utc)
+        daily_end = datetime.combine(
+            complete_dates[-1] + timedelta(days=1), time.min, tzinfo=timezone.utc
+        )
+        daily_range = (daily_start, daily_end)
+
+    usage_segments: list[tuple[datetime, datetime]] = []
+    if head_boundary:
+        usage_segments.append(head_boundary)
+    if tail_boundary:
+        usage_segments.append(tail_boundary)
+
+    if not daily_range and not usage_segments:
+        usage_segments = [(start_utc, end_utc)]
+
+    return daily_range, usage_segments
+
+
+def _apply_usage_time_segments(
+    query: Any, segments: list[tuple[datetime, datetime]] | None
+) -> Any | None:
+    if segments is None:
+        return query
+    if not segments:
+        return None
+
+    conditions = []
+    for start_utc, end_utc in segments:
+        if start_utc >= end_utc:
+            continue
+        conditions.append(and_(Usage.created_at >= start_utc, Usage.created_at < end_utc))
+
+    if not conditions:
+        return None
+
+    return query.filter(or_(*conditions))
+
+
+def _union_queries(queries: list[Any]) -> Any | None:
+    base = None
+    for query in queries:
+        if query is None:
+            continue
+        if base is None:
+            base = query
+        else:
+            base = base.union_all(query)
+    return base
+
+
+def _metric_order(
+    metric: Literal["requests", "tokens", "cost"], order: Literal["asc", "desc"], expr: Any
+) -> Any:
+    return expr.asc() if order == "asc" else expr.desc()

src/api/admin/stats/comparison.py

@@ -0,0 +1,128 @@
+"""Admin comparison stats routes."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import Any, Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from sqlalchemy.orm import Session
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.context import ApiRequestContext
+from src.database import get_db
+from src.services.system.stats_aggregator import AggregatedStats, StatsFilter, query_stats_hybrid
+from src.services.system.time_range import TimeRangeParams
+
+from .common import pipeline
+
+router = APIRouter()
+
+
+class AdminComparisonAdapter(AdminApiAdapter):
+    def __init__(
+        self,
+        current_start: date,
+        current_end: date,
+        comparison_type: Literal["period", "year"],
+        timezone_name: str | None,
+        tz_offset_minutes: int | None,
+    ) -> None:
+        self.current_start = current_start
+        self.current_end = current_end
+        self.comparison_type = comparison_type
+        self.timezone_name = timezone_name
+        self.tz_offset_minutes = tz_offset_minutes
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        if self.current_start > self.current_end:
+            raise HTTPException(status_code=400, detail="current_start must be <= current_end")
+
+        days = (self.current_end - self.current_start).days + 1
+
+        def _safe_year_shift(value: date) -> date:
+            try:
+                return value.replace(year=value.year - 1)
+            except ValueError:
+                return value.replace(year=value.year - 1, day=28)
+
+        if self.comparison_type == "period":
+            comparison_end = self.current_start - timedelta(days=1)
+            comparison_start = comparison_end - timedelta(days=days - 1)
+        else:
+            comparison_start = _safe_year_shift(self.current_start)
+            comparison_end = _safe_year_shift(self.current_end)
+
+        current_range = TimeRangeParams(
+            start_date=self.current_start,
+            end_date=self.current_end,
+            timezone=self.timezone_name,
+            tz_offset_minutes=self.tz_offset_minutes or 0,
+        ).validate_and_resolve()
+        comparison_range = TimeRangeParams(
+            start_date=comparison_start,
+            end_date=comparison_end,
+            timezone=self.timezone_name,
+            tz_offset_minutes=self.tz_offset_minutes or 0,
+        ).validate_and_resolve()
+
+        current_stats = query_stats_hybrid(context.db, current_range, filters=StatsFilter())
+        comparison_stats = query_stats_hybrid(context.db, comparison_range, filters=StatsFilter())
+
+        def _stats_payload(stats: AggregatedStats) -> dict[str, Any]:
+            total_tokens = (
+                stats.input_tokens
+                + stats.output_tokens
+                + stats.cache_creation_tokens
+                + stats.cache_read_tokens
+            )
+            return {
+                "total_requests": stats.total_requests,
+                "total_tokens": total_tokens,
+                "total_cost": float(stats.total_cost),
+                "actual_total_cost": float(stats.actual_total_cost),
+                "avg_response_time_ms": float(stats.avg_response_time_ms),
+                "error_requests": stats.error_requests,
+            }
+
+        def _pct_change(current: float, previous: float) -> float | None:
+            if previous == 0:
+                return None if current != 0 else 0.0
+            return round((current - previous) / previous * 100, 2)
+
+        current_payload = _stats_payload(current_stats)
+        comparison_payload = _stats_payload(comparison_stats)
+        changes = {
+            key: _pct_change(float(current_payload[key]), float(comparison_payload[key]))
+            for key in current_payload.keys()
+        }
+
+        return {
+            "current": current_payload,
+            "comparison": comparison_payload,
+            "change_percent": changes,
+            "current_start": self.current_start.isoformat(),
+            "current_end": self.current_end.isoformat(),
+            "comparison_start": comparison_start.isoformat(),
+            "comparison_end": comparison_end.isoformat(),
+        }
+
+
+@router.get("/comparison")
+async def get_comparison(
+    request: Request,
+    db: Session = Depends(get_db),
+    current_start: date = Query(...),
+    current_end: date = Query(...),
+    comparison_type: Literal["period", "year"] = Query("period"),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+) -> Any:
+    adapter = AdminComparisonAdapter(
+        current_start=current_start,
+        current_end=current_end,
+        comparison_type=comparison_type,
+        timezone_name=timezone_name,
+        tz_offset_minutes=tz_offset_minutes,
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)

src/api/admin/stats/cost.py

@@ -0,0 +1,183 @@
+"""Admin cost stats routes."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.context import ApiRequestContext
+from src.database import get_db
+from src.models.database import Usage
+from src.services.system.stats_aggregator import query_time_series
+from src.services.system.time_range import TimeRangeParams
+
+from .common import (
+    _apply_admin_default_range,
+    _build_time_range_from_days,
+    _build_time_range_params,
+    _linear_regression,
+    pipeline,
+)
+
+router = APIRouter()
+
+
+class AdminCostForecastAdapter(AdminApiAdapter):
+    def __init__(
+        self,
+        time_range: TimeRangeParams | None,
+        days: int,
+        forecast_days: int,
+        timezone_name: str | None,
+        tz_offset_minutes: int | None,
+    ) -> None:
+        self.time_range = time_range
+        self.days = days
+        self.forecast_days = forecast_days
+        self.timezone_name = timezone_name
+        self.tz_offset_minutes = tz_offset_minutes
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        time_range = self.time_range or _build_time_range_from_days(
+            self.days, self.timezone_name, self.tz_offset_minutes
+        )
+        time_range.granularity = "day"
+        try:
+            series = query_time_series(context.db, time_range)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        history = [
+            {"date": item["date"], "total_cost": float(item.get("total_cost", 0.0))}
+            for item in series
+        ]
+
+        values = [item["total_cost"] for item in history]
+        slope, intercept = _linear_regression(values)
+
+        forecast = []
+        if history:
+            last_date = date.fromisoformat(history[-1]["date"])
+        else:
+            last_date = time_range.end_date
+        for i in range(self.forecast_days):
+            idx = len(values) + i
+            predicted = max(0.0, slope * idx + intercept)
+            forecast.append(
+                {
+                    "date": (last_date + timedelta(days=i + 1)).isoformat(),
+                    "total_cost": round(predicted, 4),
+                }
+            )
+
+        return {
+            "history": history,
+            "forecast": forecast,
+            "slope": round(slope, 6),
+            "intercept": round(intercept, 6),
+            "start_date": time_range.start_date.isoformat(),
+            "end_date": time_range.end_date.isoformat(),
+        }
+
+
+@router.get("/cost/forecast")
+async def get_cost_forecast(
+    request: Request,
+    db: Session = Depends(get_db),
+    start_date: date | None = Query(None),
+    end_date: date | None = Query(None),
+    preset: str | None = Query(None),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+    days: int = Query(30, ge=7, le=365),
+    forecast_days: int = Query(7, ge=1, le=90),
+) -> Any:
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
+    )
+    adapter = AdminCostForecastAdapter(
+        time_range=time_range,
+        days=days,
+        forecast_days=forecast_days,
+        timezone_name=timezone_name,
+        tz_offset_minutes=tz_offset_minutes,
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+class AdminCostSavingsAdapter(AdminApiAdapter):
+    def __init__(
+        self,
+        time_range: TimeRangeParams | None,
+        provider_name: str | None,
+        model: str | None,
+    ) -> None:
+        self.time_range = _apply_admin_default_range(time_range)
+        self.provider_name = provider_name
+        self.model = model
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        if not self.time_range:
+            return {
+                "cache_read_tokens": 0,
+                "cache_read_cost": 0.0,
+                "cache_creation_cost": 0.0,
+                "estimated_full_cost": 0.0,
+                "cache_savings": 0.0,
+            }
+
+        start_utc, end_utc = self.time_range.to_utc_datetime_range()
+        query = context.db.query(
+            func.sum(Usage.cache_read_input_tokens).label("cache_read_tokens"),
+            func.sum(Usage.cache_read_cost_usd).label("cache_read_cost"),
+            func.sum(Usage.cache_creation_cost_usd).label("cache_creation_cost"),
+            func.sum(
+                func.coalesce(Usage.output_price_per_1m, 0) * Usage.cache_read_input_tokens
+            ).label("estimated_full_cost_raw"),
+        ).filter(Usage.created_at >= start_utc, Usage.created_at < end_utc)
+        if self.provider_name:
+            query = query.filter(Usage.provider_name == self.provider_name)
+        if self.model:
+            query = query.filter(Usage.model == self.model)
+
+        row = query.first()
+        cache_read_tokens = int(getattr(row, "cache_read_tokens", 0) or 0)
+        cache_read_cost = float(getattr(row, "cache_read_cost", 0) or 0.0)
+        cache_creation_cost = float(getattr(row, "cache_creation_cost", 0) or 0.0)
+        estimated_full_cost = float(getattr(row, "estimated_full_cost_raw", 0) or 0.0) / 1_000_000
+        if estimated_full_cost <= 0 and cache_read_cost > 0:
+            estimated_full_cost = cache_read_cost * 10
+        cache_savings = estimated_full_cost - cache_read_cost
+
+        return {
+            "cache_read_tokens": cache_read_tokens,
+            "cache_read_cost": round(cache_read_cost, 6),
+            "cache_creation_cost": round(cache_creation_cost, 6),
+            "estimated_full_cost": round(estimated_full_cost, 6),
+            "cache_savings": round(cache_savings, 6),
+        }
+
+
+@router.get("/cost/savings")
+async def get_cost_savings(
+    request: Request,
+    db: Session = Depends(get_db),
+    start_date: date | None = Query(None),
+    end_date: date | None = Query(None),
+    preset: str | None = Query(None),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+    provider_name: str | None = Query(None),
+    model: str | None = Query(None),
+) -> Any:
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
+    )
+    adapter = AdminCostSavingsAdapter(
+        time_range=time_range, provider_name=provider_name, model=model
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)

src/api/admin/stats/errors.py

@@ -0,0 +1,111 @@
+"""Admin error stats routes."""
+
+from __future__ import annotations
+
+from datetime import date, timezone
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query, Request
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.context import ApiRequestContext
+from src.database import get_db
+from src.models.database import StatsDailyError, Usage
+from src.services.system.time_range import TimeRangeParams
+
+from .common import _apply_admin_default_range, _build_time_range_params, pipeline
+
+router = APIRouter()
+
+
+class AdminErrorDistributionAdapter(AdminApiAdapter):
+    def __init__(self, time_range: TimeRangeParams | None) -> None:
+        self.time_range = _apply_admin_default_range(time_range)
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        if not self.time_range:
+            return {"distribution": [], "trend": []}
+
+        time_range = self.time_range
+        is_utc = (time_range.timezone in {None, "UTC"}) and time_range.tz_offset_minutes == 0
+        distribution: dict[str, int] = {}
+        trend: dict[str, dict[str, int]] = {}
+
+        if is_utc:
+            start_utc, end_utc = time_range.to_utc_datetime_range()
+            rows = (
+                context.db.query(StatsDailyError)
+                .filter(StatsDailyError.date >= start_utc, StatsDailyError.date < end_utc)
+                .all()
+            )
+            for row in rows:
+                date_str = (
+                    row.date.astimezone(timezone.utc).date().isoformat()
+                    if row.date.tzinfo
+                    else row.date.date().isoformat()
+                )
+                distribution[row.error_category] = distribution.get(row.error_category, 0) + int(
+                    row.count or 0
+                )
+                trend.setdefault(date_str, {})
+                trend[date_str][row.error_category] = trend[date_str].get(
+                    row.error_category, 0
+                ) + int(row.count or 0)
+        else:
+            for local_date, day_start_utc, day_end_utc in time_range.get_local_day_hours():
+                rows = (
+                    context.db.query(
+                        Usage.error_category,
+                        func.count(Usage.id).label("count"),
+                    )
+                    .filter(
+                        Usage.created_at >= day_start_utc,
+                        Usage.created_at < day_end_utc,
+                        Usage.error_category.isnot(None),
+                    )
+                    .group_by(Usage.error_category)
+                    .all()
+                )
+                date_str = local_date.isoformat()
+                for row in rows:
+                    distribution[row.error_category] = distribution.get(
+                        row.error_category, 0
+                    ) + int(row.count or 0)
+                    trend.setdefault(date_str, {})
+                    trend[date_str][row.error_category] = trend[date_str].get(
+                        row.error_category, 0
+                    ) + int(row.count or 0)
+
+        trend_items = []
+        for day in sorted(trend.keys()):
+            counts = trend[day]
+            total = sum(counts.values())
+            trend_items.append({"date": day, "total": total, "categories": counts})
+
+        distribution_items = [
+            {"category": category, "count": count}
+            for category, count in sorted(
+                distribution.items(), key=lambda item: item[1], reverse=True
+            )
+        ]
+
+        return {"distribution": distribution_items, "trend": trend_items}
+
+
+@router.get("/errors/distribution")
+async def get_error_distribution(
+    request: Request,
+    db: Session = Depends(get_db),
+    start_date: date | None = Query(None),
+    end_date: date | None = Query(None),
+    preset: str | None = Query(None),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+) -> Any:
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
+    )
+    adapter = AdminErrorDistributionAdapter(time_range=time_range)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)

src/api/admin/stats/leaderboard.py

@@ -0,0 +1,759 @@
+"""Admin leaderboard stats routes."""
+
+from __future__ import annotations
+
+import json
+from datetime import date
+from typing import Any, Literal
+
+from fastapi import APIRouter, Depends, Query, Request
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.context import ApiRequestContext
+from src.clients.redis_client import get_redis_client_sync
+from src.config.constants import CacheTTL
+from src.core.enums import UserRole
+from src.database import get_db
+from src.models.database import (
+    ApiKey,
+    StatsDailyApiKey,
+    StatsDailyModel,
+    StatsUserDaily,
+    Usage,
+    User,
+)
+from src.services.system.time_range import TimeRangeParams
+
+from .common import (
+    _apply_admin_default_range,
+    _apply_usage_time_segments,
+    _build_cache_key,
+    _build_time_range_params,
+    _is_today_range,
+    _metric_order,
+    _split_daily_and_usage_segments,
+    _union_queries,
+    pipeline,
+)
+
+router = APIRouter()
+
+
+class AdminUserLeaderboardAdapter(AdminApiAdapter):
+    def __init__(
+        self,
+        time_range: TimeRangeParams | None,
+        metric: Literal["requests", "tokens", "cost"],
+        order: Literal["asc", "desc"],
+        limit: int,
+        offset: int,
+        provider_name: str | None,
+        model: str | None,
+        include_inactive: bool,
+        exclude_admin: bool,
+    ) -> None:
+        self.time_range = _apply_admin_default_range(time_range)
+        self.metric = metric
+        self.order = order
+        self.limit = limit
+        self.offset = offset
+        self.provider_name = provider_name
+        self.model = model
+        self.include_inactive = include_inactive
+        self.exclude_admin = exclude_admin
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        db = context.db
+        cacheable = not _is_today_range(self.time_range)
+        redis_client = get_redis_client_sync()
+        cache_key = None
+        if cacheable and redis_client:
+            cache_key = _build_cache_key(
+                "users",
+                self.metric,
+                self.time_range,
+                {
+                    "order": self.order,
+                    "limit": self.limit,
+                    "offset": self.offset,
+                    "provider_name": self.provider_name,
+                    "model": self.model,
+                    "include_inactive": self.include_inactive,
+                    "exclude_admin": self.exclude_admin,
+                },
+            )
+            cached = await redis_client.get(cache_key)
+            if cached:
+                try:
+                    return json.loads(cached)
+                except Exception:
+                    pass
+
+        use_daily = self.time_range is not None and not self.provider_name and not self.model
+        daily_range, usage_segments = _split_daily_and_usage_segments(self.time_range, use_daily)
+
+        daily_query = None
+        if daily_range:
+            daily_query = (
+                db.query(
+                    StatsUserDaily.user_id.label("entity_id"),
+                    func.sum(StatsUserDaily.total_requests).label("requests"),
+                    func.sum(
+                        StatsUserDaily.input_tokens
+                        + StatsUserDaily.output_tokens
+                        + StatsUserDaily.cache_creation_tokens
+                        + StatsUserDaily.cache_read_tokens
+                    ).label("tokens"),
+                    func.sum(StatsUserDaily.total_cost).label("cost"),
+                )
+                .filter(StatsUserDaily.date >= daily_range[0], StatsUserDaily.date < daily_range[1])
+                .group_by(StatsUserDaily.user_id)
+            )
+
+        usage_query = db.query(
+            Usage.user_id.label("entity_id"),
+            func.count(Usage.id).label("requests"),
+            func.sum(
+                Usage.input_tokens
+                + Usage.output_tokens
+                + Usage.cache_creation_input_tokens
+                + Usage.cache_read_input_tokens
+            ).label("tokens"),
+            func.sum(Usage.total_cost_usd).label("cost"),
+        ).filter(
+            Usage.user_id.isnot(None),
+            Usage.status.notin_(["pending", "streaming"]),
+            Usage.provider_name.notin_(["unknown", "pending"]),
+        )
+        if self.provider_name:
+            usage_query = usage_query.filter(Usage.provider_name == self.provider_name)
+        if self.model:
+            usage_query = usage_query.filter(Usage.model == self.model)
+        usage_query = _apply_usage_time_segments(usage_query, usage_segments)
+        if usage_query is not None:
+            usage_query = usage_query.group_by(Usage.user_id)
+
+        union_query = _union_queries([daily_query, usage_query])
+        if union_query is None:
+            return {
+                "items": [],
+                "total": 0,
+                "metric": self.metric,
+                "start_date": self.time_range.start_date.isoformat() if self.time_range else None,
+                "end_date": self.time_range.end_date.isoformat() if self.time_range else None,
+            }
+
+        union_subq = union_query.subquery()
+        agg_subq = (
+            db.query(
+                union_subq.c.entity_id.label("entity_id"),
+                func.sum(union_subq.c.requests).label("requests"),
+                func.sum(union_subq.c.tokens).label("tokens"),
+                func.sum(union_subq.c.cost).label("cost"),
+            )
+            .group_by(union_subq.c.entity_id)
+            .subquery()
+        )
+
+        base_query = (
+            db.query(
+                User.id.label("id"),
+                User.username,
+                User.email,
+                agg_subq.c.requests,
+                agg_subq.c.tokens,
+                agg_subq.c.cost,
+            )
+            .join(agg_subq, agg_subq.c.entity_id == User.id)
+            .filter(User.is_deleted.is_(False))
+        )
+        if not self.include_inactive:
+            base_query = base_query.filter(User.is_active.is_(True))
+        if self.exclude_admin:
+            base_query = base_query.filter(User.role != UserRole.ADMIN)
+
+        metric_expr = {
+            "requests": agg_subq.c.requests,
+            "tokens": agg_subq.c.tokens,
+            "cost": agg_subq.c.cost,
+        }[self.metric]
+        order_expr = _metric_order(self.metric, self.order, metric_expr)
+        rank_expr = func.dense_rank().over(order_by=order_expr).label("rank")
+
+        total = db.query(func.count()).select_from(base_query.subquery()).scalar() or 0
+        rows = (
+            base_query.add_columns(rank_expr, metric_expr.label("metric_value"))
+            .order_by(order_expr)
+            .offset(self.offset)
+            .limit(self.limit)
+            .all()
+        )
+
+        items = []
+        for row in rows:
+            name = row.username or row.email or str(row.id)
+            value = row.metric_value or 0
+            if self.metric in {"requests", "tokens"}:
+                value = int(value)
+            else:
+                value = float(value)
+            items.append(
+                {
+                    "rank": int(row.rank),
+                    "id": row.id,
+                    "name": name,
+                    "value": value,
+                    "requests": int(row.requests or 0),
+                    "tokens": int(row.tokens or 0),
+                    "cost": float(row.cost or 0.0),
+                }
+            )
+
+        context.add_audit_metadata(
+            action="leaderboard_users",
+            start_date=self.time_range.start_date.isoformat() if self.time_range else None,
+            end_date=self.time_range.end_date.isoformat() if self.time_range else None,
+            preset=self.time_range.preset if self.time_range else None,
+            timezone=self.time_range.timezone if self.time_range else None,
+            metric=self.metric,
+            order=self.order,
+            limit=self.limit,
+            offset=self.offset,
+            provider_name=self.provider_name,
+            model=self.model,
+            include_inactive=self.include_inactive,
+            exclude_admin=self.exclude_admin,
+            result_count=len(items),
+            total=total,
+        )
+
+        result = {
+            "items": items,
+            "total": total,
+            "metric": self.metric,
+            "start_date": self.time_range.start_date.isoformat() if self.time_range else None,
+            "end_date": self.time_range.end_date.isoformat() if self.time_range else None,
+        }
+
+        if cacheable and redis_client and cache_key:
+            try:
+                await redis_client.setex(
+                    cache_key, CacheTTL.ADMIN_LEADERBOARD, json.dumps(result, ensure_ascii=False)
+                )
+            except Exception:
+                pass
+
+        return result
+
+
+class AdminApiKeyLeaderboardAdapter(AdminApiAdapter):
+    def __init__(
+        self,
+        time_range: TimeRangeParams | None,
+        metric: Literal["requests", "tokens", "cost"],
+        order: Literal["asc", "desc"],
+        limit: int,
+        offset: int,
+        provider_name: str | None,
+        model: str | None,
+        include_inactive: bool,
+        exclude_admin: bool,
+    ) -> None:
+        self.time_range = _apply_admin_default_range(time_range)
+        self.metric = metric
+        self.order = order
+        self.limit = limit
+        self.offset = offset
+        self.provider_name = provider_name
+        self.model = model
+        self.include_inactive = include_inactive
+        self.exclude_admin = exclude_admin
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        db = context.db
+        cacheable = not _is_today_range(self.time_range)
+        redis_client = get_redis_client_sync()
+        cache_key = None
+        if cacheable and redis_client:
+            cache_key = _build_cache_key(
+                "api_keys",
+                self.metric,
+                self.time_range,
+                {
+                    "order": self.order,
+                    "limit": self.limit,
+                    "offset": self.offset,
+                    "provider_name": self.provider_name,
+                    "model": self.model,
+                    "include_inactive": self.include_inactive,
+                    "exclude_admin": self.exclude_admin,
+                },
+            )
+            cached = await redis_client.get(cache_key)
+            if cached:
+                try:
+                    return json.loads(cached)
+                except Exception:
+                    pass
+
+        use_daily = self.time_range is not None and not self.provider_name and not self.model
+        daily_range, usage_segments = _split_daily_and_usage_segments(self.time_range, use_daily)
+
+        daily_query = None
+        if daily_range:
+            daily_query = (
+                db.query(
+                    StatsDailyApiKey.api_key_id.label("entity_id"),
+                    func.sum(StatsDailyApiKey.total_requests).label("requests"),
+                    func.sum(
+                        StatsDailyApiKey.input_tokens
+                        + StatsDailyApiKey.output_tokens
+                        + StatsDailyApiKey.cache_creation_tokens
+                        + StatsDailyApiKey.cache_read_tokens
+                    ).label("tokens"),
+                    func.sum(StatsDailyApiKey.total_cost).label("cost"),
+                )
+                .filter(
+                    StatsDailyApiKey.date >= daily_range[0], StatsDailyApiKey.date < daily_range[1]
+                )
+                .group_by(StatsDailyApiKey.api_key_id)
+            )
+
+        usage_query = db.query(
+            Usage.api_key_id.label("entity_id"),
+            func.count(Usage.id).label("requests"),
+            func.sum(
+                Usage.input_tokens
+                + Usage.output_tokens
+                + Usage.cache_creation_input_tokens
+                + Usage.cache_read_input_tokens
+            ).label("tokens"),
+            func.sum(Usage.total_cost_usd).label("cost"),
+        ).filter(
+            Usage.api_key_id.isnot(None),
+            Usage.status.notin_(["pending", "streaming"]),
+            Usage.provider_name.notin_(["unknown", "pending"]),
+        )
+        if self.provider_name:
+            usage_query = usage_query.filter(Usage.provider_name == self.provider_name)
+        if self.model:
+            usage_query = usage_query.filter(Usage.model == self.model)
+
+        usage_query = _apply_usage_time_segments(usage_query, usage_segments)
+        if usage_query is None:
+            return {
+                "items": [],
+                "total": 0,
+                "metric": self.metric,
+                "start_date": self.time_range.start_date.isoformat() if self.time_range else None,
+                "end_date": self.time_range.end_date.isoformat() if self.time_range else None,
+            }
+        usage_query = usage_query.group_by(Usage.api_key_id)
+
+        union_query = _union_queries([daily_query, usage_query])
+        if union_query is None:
+            return {
+                "items": [],
+                "total": 0,
+                "metric": self.metric,
+                "start_date": self.time_range.start_date.isoformat() if self.time_range else None,
+                "end_date": self.time_range.end_date.isoformat() if self.time_range else None,
+            }
+
+        union_subq = union_query.subquery()
+        agg_subq = (
+            db.query(
+                union_subq.c.entity_id.label("entity_id"),
+                func.sum(union_subq.c.requests).label("requests"),
+                func.sum(union_subq.c.tokens).label("tokens"),
+                func.sum(union_subq.c.cost).label("cost"),
+            )
+            .group_by(union_subq.c.entity_id)
+            .subquery()
+        )
+
+        base_query = (
+            db.query(
+                ApiKey,
+                User,
+                agg_subq.c.requests,
+                agg_subq.c.tokens,
+                agg_subq.c.cost,
+            )
+            .join(agg_subq, agg_subq.c.entity_id == ApiKey.id)
+            .join(User, User.id == ApiKey.user_id)
+            .filter(User.is_deleted.is_(False))
+        )
+        if not self.include_inactive:
+            base_query = base_query.filter(ApiKey.is_active.is_(True))
+        if self.exclude_admin:
+            base_query = base_query.filter(User.role != UserRole.ADMIN)
+
+        metric_expr = {
+            "requests": agg_subq.c.requests,
+            "tokens": agg_subq.c.tokens,
+            "cost": agg_subq.c.cost,
+        }[self.metric]
+        order_expr = _metric_order(self.metric, self.order, metric_expr)
+        rank_expr = func.dense_rank().over(order_by=order_expr).label("rank")
+
+        total = db.query(func.count()).select_from(base_query.subquery()).scalar() or 0
+        rows = (
+            base_query.add_columns(rank_expr, metric_expr.label("metric_value"))
+            .order_by(order_expr)
+            .offset(self.offset)
+            .limit(self.limit)
+            .all()
+        )
+
+        items = []
+        for row in rows:
+            api_key = row.ApiKey
+            name = api_key.name or api_key.get_display_key()
+            value = row.metric_value or 0
+            if self.metric in {"requests", "tokens"}:
+                value = int(value)
+            else:
+                value = float(value)
+            items.append(
+                {
+                    "rank": int(row.rank),
+                    "id": api_key.id,
+                    "name": name,
+                    "value": value,
+                    "requests": int(row.requests or 0),
+                    "tokens": int(row.tokens or 0),
+                    "cost": float(row.cost or 0.0),
+                }
+            )
+
+        context.add_audit_metadata(
+            action="leaderboard_api_keys",
+            start_date=self.time_range.start_date.isoformat() if self.time_range else None,
+            end_date=self.time_range.end_date.isoformat() if self.time_range else None,
+            preset=self.time_range.preset if self.time_range else None,
+            timezone=self.time_range.timezone if self.time_range else None,
+            metric=self.metric,
+            order=self.order,
+            limit=self.limit,
+            offset=self.offset,
+            provider_name=self.provider_name,
+            model=self.model,
+            include_inactive=self.include_inactive,
+            exclude_admin=self.exclude_admin,
+            result_count=len(items),
+            total=total,
+        )
+
+        result = {
+            "items": items,
+            "total": total,
+            "metric": self.metric,
+            "start_date": self.time_range.start_date.isoformat() if self.time_range else None,
+            "end_date": self.time_range.end_date.isoformat() if self.time_range else None,
+        }
+
+        if cacheable and redis_client and cache_key:
+            try:
+                await redis_client.setex(
+                    cache_key, CacheTTL.ADMIN_LEADERBOARD, json.dumps(result, ensure_ascii=False)
+                )
+            except Exception:
+                pass
+
+        return result
+
+
+class AdminModelLeaderboardAdapter(AdminApiAdapter):
+    def __init__(
+        self,
+        time_range: TimeRangeParams | None,
+        metric: Literal["requests", "tokens", "cost"],
+        order: Literal["asc", "desc"],
+        limit: int,
+        offset: int,
+        provider_name: str | None,
+        model: str | None,
+    ) -> None:
+        self.time_range = _apply_admin_default_range(time_range)
+        self.metric = metric
+        self.order = order
+        self.limit = limit
+        self.offset = offset
+        self.provider_name = provider_name
+        self.model = model
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        db = context.db
+        cacheable = not _is_today_range(self.time_range)
+        redis_client = get_redis_client_sync()
+        cache_key = None
+        if cacheable and redis_client:
+            cache_key = _build_cache_key(
+                "models",
+                self.metric,
+                self.time_range,
+                {
+                    "order": self.order,
+                    "limit": self.limit,
+                    "offset": self.offset,
+                    "provider_name": self.provider_name,
+                    "model": self.model,
+                },
+            )
+            cached = await redis_client.get(cache_key)
+            if cached:
+                try:
+                    return json.loads(cached)
+                except Exception:
+                    pass
+
+        use_daily = self.time_range is not None and not self.provider_name
+        daily_range, usage_segments = _split_daily_and_usage_segments(self.time_range, use_daily)
+
+        daily_query = None
+        if daily_range:
+            daily_query = (
+                db.query(
+                    StatsDailyModel.model.label("entity_id"),
+                    func.sum(StatsDailyModel.total_requests).label("requests"),
+                    func.sum(
+                        StatsDailyModel.input_tokens
+                        + StatsDailyModel.output_tokens
+                        + StatsDailyModel.cache_creation_tokens
+                        + StatsDailyModel.cache_read_tokens
+                    ).label("tokens"),
+                    func.sum(StatsDailyModel.total_cost).label("cost"),
+                )
+                .filter(
+                    StatsDailyModel.date >= daily_range[0], StatsDailyModel.date < daily_range[1]
+                )
+                .group_by(StatsDailyModel.model)
+            )
+            if self.model:
+                daily_query = daily_query.filter(StatsDailyModel.model == self.model)
+
+        usage_query = db.query(
+            Usage.model.label("entity_id"),
+            func.count(Usage.id).label("requests"),
+            func.sum(
+                Usage.input_tokens
+                + Usage.output_tokens
+                + Usage.cache_creation_input_tokens
+                + Usage.cache_read_input_tokens
+            ).label("tokens"),
+            func.sum(Usage.total_cost_usd).label("cost"),
+        ).filter(
+            Usage.status.notin_(["pending", "streaming"]),
+            Usage.provider_name.notin_(["unknown", "pending"]),
+        )
+        if self.provider_name:
+            usage_query = usage_query.filter(Usage.provider_name == self.provider_name)
+        if self.model:
+            usage_query = usage_query.filter(Usage.model == self.model)
+        usage_query = _apply_usage_time_segments(usage_query, usage_segments)
+        if usage_query is not None:
+            usage_query = usage_query.group_by(Usage.model)
+
+        union_query = _union_queries([daily_query, usage_query])
+        if union_query is None:
+            return {
+                "items": [],
+                "total": 0,
+                "metric": self.metric,
+                "start_date": self.time_range.start_date.isoformat() if self.time_range else None,
+                "end_date": self.time_range.end_date.isoformat() if self.time_range else None,
+            }
+
+        union_subq = union_query.subquery()
+        agg_subq = (
+            db.query(
+                union_subq.c.entity_id.label("entity_id"),
+                func.sum(union_subq.c.requests).label("requests"),
+                func.sum(union_subq.c.tokens).label("tokens"),
+                func.sum(union_subq.c.cost).label("cost"),
+            )
+            .group_by(union_subq.c.entity_id)
+            .subquery()
+        )
+
+        base_query = db.query(
+            agg_subq.c.entity_id.label("id"),
+            agg_subq.c.entity_id.label("name"),
+            agg_subq.c.requests,
+            agg_subq.c.tokens,
+            agg_subq.c.cost,
+        )
+
+        metric_expr = {
+            "requests": agg_subq.c.requests,
+            "tokens": agg_subq.c.tokens,
+            "cost": agg_subq.c.cost,
+        }[self.metric]
+        order_expr = _metric_order(self.metric, self.order, metric_expr)
+        rank_expr = func.dense_rank().over(order_by=order_expr).label("rank")
+
+        total = db.query(func.count()).select_from(base_query.subquery()).scalar() or 0
+        rows = (
+            base_query.add_columns(rank_expr, metric_expr.label("metric_value"))
+            .order_by(order_expr)
+            .offset(self.offset)
+            .limit(self.limit)
+            .all()
+        )
+
+        items = []
+        for row in rows:
+            value = row.metric_value or 0
+            if self.metric in {"requests", "tokens"}:
+                value = int(value)
+            else:
+                value = float(value)
+            items.append(
+                {
+                    "rank": int(row.rank),
+                    "id": row.id,
+                    "name": row.name,
+                    "value": value,
+                    "requests": int(row.requests or 0),
+                    "tokens": int(row.tokens or 0),
+                    "cost": float(row.cost or 0.0),
+                }
+            )
+
+        context.add_audit_metadata(
+            action="leaderboard_models",
+            start_date=self.time_range.start_date.isoformat() if self.time_range else None,
+            end_date=self.time_range.end_date.isoformat() if self.time_range else None,
+            preset=self.time_range.preset if self.time_range else None,
+            timezone=self.time_range.timezone if self.time_range else None,
+            metric=self.metric,
+            order=self.order,
+            limit=self.limit,
+            offset=self.offset,
+            provider_name=self.provider_name,
+            model=self.model,
+            result_count=len(items),
+            total=total,
+        )
+
+        result = {
+            "items": items,
+            "total": total,
+            "metric": self.metric,
+            "start_date": self.time_range.start_date.isoformat() if self.time_range else None,
+            "end_date": self.time_range.end_date.isoformat() if self.time_range else None,
+        }
+
+        if cacheable and redis_client and cache_key:
+            try:
+                await redis_client.setex(
+                    cache_key, CacheTTL.ADMIN_LEADERBOARD, json.dumps(result, ensure_ascii=False)
+                )
+            except Exception:
+                pass
+
+        return result
+
+
+@router.get("/leaderboard/users")
+async def get_user_leaderboard(
+    request: Request,
+    db: Session = Depends(get_db),
+    start_date: date | None = Query(None),
+    end_date: date | None = Query(None),
+    preset: str | None = Query(None),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+    metric: Literal["requests", "tokens", "cost"] = Query("requests"),
+    order: Literal["desc", "asc"] = Query("desc"),
+    limit: int = Query(10, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    provider_name: str | None = Query(None),
+    model: str | None = Query(None),
+    include_inactive: bool = Query(False),
+    exclude_admin: bool = Query(False),
+) -> Any:
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
+    )
+    adapter = AdminUserLeaderboardAdapter(
+        time_range=time_range,
+        metric=metric,
+        order=order,
+        limit=limit,
+        offset=offset,
+        provider_name=provider_name,
+        model=model,
+        include_inactive=include_inactive,
+        exclude_admin=exclude_admin,
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@router.get("/leaderboard/api-keys")
+async def get_api_key_leaderboard(
+    request: Request,
+    db: Session = Depends(get_db),
+    start_date: date | None = Query(None),
+    end_date: date | None = Query(None),
+    preset: str | None = Query(None),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+    metric: Literal["requests", "tokens", "cost"] = Query("requests"),
+    order: Literal["desc", "asc"] = Query("desc"),
+    limit: int = Query(10, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    provider_name: str | None = Query(None),
+    model: str | None = Query(None),
+    include_inactive: bool = Query(False),
+    exclude_admin: bool = Query(False),
+) -> Any:
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
+    )
+    adapter = AdminApiKeyLeaderboardAdapter(
+        time_range=time_range,
+        metric=metric,
+        order=order,
+        limit=limit,
+        offset=offset,
+        provider_name=provider_name,
+        model=model,
+        include_inactive=include_inactive,
+        exclude_admin=exclude_admin,
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@router.get("/leaderboard/models")
+async def get_model_leaderboard(
+    request: Request,
+    db: Session = Depends(get_db),
+    start_date: date | None = Query(None),
+    end_date: date | None = Query(None),
+    preset: str | None = Query(None),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+    metric: Literal["requests", "tokens", "cost"] = Query("requests"),
+    order: Literal["desc", "asc"] = Query("desc"),
+    limit: int = Query(10, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    provider_name: str | None = Query(None),
+    model: str | None = Query(None),
+) -> Any:
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
+    )
+    adapter = AdminModelLeaderboardAdapter(
+        time_range=time_range,
+        metric=metric,
+        order=order,
+        limit=limit,
+        offset=offset,
+        provider_name=provider_name,
+        model=model,
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)

src/api/admin/stats/performance.py

@@ -0,0 +1,85 @@
+"""Admin performance stats routes."""
+
+from __future__ import annotations
+
+from datetime import date, timezone
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query, Request
+from sqlalchemy.orm import Session
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.context import ApiRequestContext
+from src.database import get_db
+from src.models.database import StatsDaily
+from src.services.system.stats_aggregator import StatsAggregatorService
+from src.services.system.time_range import TimeRangeParams
+
+from .common import _apply_admin_default_range, _build_time_range_params, pipeline
+
+router = APIRouter()
+
+
+class AdminPercentilesAdapter(AdminApiAdapter):
+    def __init__(self, time_range: TimeRangeParams | None) -> None:
+        self.time_range = _apply_admin_default_range(time_range)
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        if not self.time_range:
+            return []
+
+        time_range = self.time_range
+        is_utc = (time_range.timezone in {None, "UTC"}) and time_range.tz_offset_minutes == 0
+
+        if is_utc:
+            start_utc, end_utc = time_range.to_utc_datetime_range()
+            rows = (
+                context.db.query(StatsDaily)
+                .filter(StatsDaily.date >= start_utc, StatsDaily.date < end_utc)
+                .order_by(StatsDaily.date.asc())
+                .all()
+            )
+            result = []
+            for row in rows:
+                date_str = (
+                    row.date.astimezone(timezone.utc).date().isoformat()
+                    if row.date.tzinfo
+                    else row.date.date().isoformat()
+                )
+                result.append(
+                    {
+                        "date": date_str,
+                        "p50_response_time_ms": row.p50_response_time_ms,
+                        "p90_response_time_ms": row.p90_response_time_ms,
+                        "p99_response_time_ms": row.p99_response_time_ms,
+                        "p50_first_byte_time_ms": row.p50_first_byte_time_ms,
+                        "p90_first_byte_time_ms": row.p90_first_byte_time_ms,
+                        "p99_first_byte_time_ms": row.p99_first_byte_time_ms,
+                    }
+                )
+            return result
+
+        result = []
+        for local_date, day_start_utc, day_end_utc in time_range.get_local_day_hours():
+            percentiles = StatsAggregatorService.compute_daily_percentiles(
+                context.db, day_start_utc, day_end_utc
+            )
+            result.append({"date": local_date.isoformat(), **percentiles})
+        return result
+
+
+@router.get("/performance/percentiles")
+async def get_percentiles(
+    request: Request,
+    db: Session = Depends(get_db),
+    start_date: date | None = Query(None),
+    end_date: date | None = Query(None),
+    preset: str | None = Query(None),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+) -> Any:
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
+    )
+    adapter = AdminPercentilesAdapter(time_range=time_range)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)

src/api/admin/stats/quota.py

@@ -0,0 +1,83 @@
+"""Admin quota usage stats routes."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy.orm import Session
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.context import ApiRequestContext
+from src.core.enums import ProviderBillingType
+from src.database import get_db
+from src.models.database import Provider
+
+from .common import pipeline
+
+router = APIRouter()
+
+
+class AdminQuotaUsageAdapter(AdminApiAdapter):
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        db = context.db
+        providers = (
+            db.query(Provider)
+            .filter(
+                (Provider.billing_type == ProviderBillingType.MONTHLY_QUOTA)
+                | (Provider.monthly_quota_usd.isnot(None))
+            )
+            .all()
+        )
+        now = datetime.now(timezone.utc)
+
+        result = []
+        for provider in providers:
+            quota = provider.monthly_quota_usd or 0.0
+            used = float(provider.monthly_used_usd or 0.0)
+            remaining = max(quota - used, 0.0)
+            usage_percent = round((used / quota) * 100, 2) if quota > 0 else 0.0
+
+            reset_at = provider.quota_last_reset_at
+            if reset_at:
+                days_elapsed = max(1, (now - reset_at).days)
+            else:
+                days_elapsed = max(1, now.day - 1)
+
+            daily_rate = used / days_elapsed if used > 0 else 0.0
+            estimated_exhaust_at = None
+            if daily_rate > 0 and remaining > 0:
+                estimated_exhaust_at = now + timedelta(days=remaining / daily_rate)
+            if provider.quota_expires_at:
+                if not estimated_exhaust_at or provider.quota_expires_at < estimated_exhaust_at:
+                    estimated_exhaust_at = provider.quota_expires_at
+
+            result.append(
+                {
+                    "id": provider.id,
+                    "name": provider.name,
+                    "quota_usd": float(quota),
+                    "used_usd": float(used),
+                    "remaining_usd": float(remaining),
+                    "usage_percent": usage_percent,
+                    "quota_expires_at": (
+                        provider.quota_expires_at.isoformat() if provider.quota_expires_at else None
+                    ),
+                    "estimated_exhaust_at": (
+                        estimated_exhaust_at.isoformat() if estimated_exhaust_at else None
+                    ),
+                }
+            )
+
+        result.sort(key=lambda x: x["usage_percent"], reverse=True)
+        return {"providers": result}
+
+
+@router.get("/providers/quota-usage")
+async def get_quota_usage(
+    request: Request,
+    db: Session = Depends(get_db),
+) -> Any:
+    adapter = AdminQuotaUsageAdapter()
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)

src/api/admin/stats/routes.py

@@ -0,0 +1,5 @@
+"""Admin stats routes (compat export)."""
+
+from . import router
+
+__all__ = ["router"]

src/api/admin/stats/time_series.py

@@ -0,0 +1,75 @@
+"""Admin time series stats routes."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Any, Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from sqlalchemy.orm import Session
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.context import ApiRequestContext
+from src.database import get_db
+from src.services.system.stats_aggregator import TimeSeriesFilter, query_time_series
+from src.services.system.time_range import TimeRangeParams
+
+from .common import _apply_admin_default_range, _build_time_range_params, pipeline
+
+router = APIRouter()
+
+
+class AdminTimeSeriesAdapter(AdminApiAdapter):
+    def __init__(
+        self,
+        time_range: TimeRangeParams | None,
+        user_id: str | None,
+        model: str | None,
+        provider_name: str | None,
+    ) -> None:
+        self.time_range = _apply_admin_default_range(time_range)
+        self.user_id = user_id
+        self.model = model
+        self.provider_name = provider_name
+
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
+        if not self.time_range:
+            return []
+        try:
+            return query_time_series(
+                context.db,
+                self.time_range,
+                filters=TimeSeriesFilter(
+                    user_id=self.user_id, model=self.model, provider_name=self.provider_name
+                ),
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.get("/time-series")
+async def get_time_series(
+    request: Request,
+    db: Session = Depends(get_db),
+    start_date: date | None = Query(None),
+    end_date: date | None = Query(None),
+    preset: str | None = Query(None),
+    granularity: Literal["hour", "day", "week", "month"] = Query("day"),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(0),
+    user_id: str | None = Query(None),
+    model: str | None = Query(None),
+    provider_name: str | None = Query(None),
+) -> Any:
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
+    )
+    if time_range:
+        time_range.granularity = granularity
+    adapter = AdminTimeSeriesAdapter(
+        time_range=time_range,
+        user_id=user_id,
+        model=model,
+        provider_name=provider_name,
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)

src/api/admin/usage/routes.py

@@ -4,11 +4,11 @@ from __future__ import annotations
 
 from collections import defaultdict
 from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
+from datetime import date, datetime, timedelta, timezone
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
-from sqlalchemy import func
+from sqlalchemy import case, func
 from sqlalchemy.orm import Session
 
 from src.api.base.admin_adapter import AdminApiAdapter
@@ -26,6 +26,8 @@ from src.models.database import (
     Usage,
     User,
 )
+from src.services.system.stats_aggregator import AggregatedStats, StatsFilter, query_stats_hybrid
+from src.services.system.time_range import TimeRangeParams
 from src.services.usage.service import UsageService
 from src.utils.cache_decorator import cache_result
 
@@ -34,22 +36,45 @@ pipeline = ApiRequestPipeline()
 
 
 def _apply_admin_default_range(
-    start_date: datetime | None, end_date: datetime | None
-) -> tuple[datetime | None, datetime | None]:
-    """
-    Apply a default time range for admin usage endpoints to protect DB from unbounded scans.
-
-    Enabled by setting ADMIN_USAGE_DEFAULT_DAYS>0.
-    """
-    if start_date is not None or end_date is not None:
-        return start_date, end_date
+    params: TimeRangeParams | None,
+) -> TimeRangeParams | None:
+    """Apply a default range to avoid unbounded scans."""
+    if params is not None:
+        return params
 
     days = int(getattr(config, "admin_usage_default_days", 0) or 0)
     if days <= 0:
-        return start_date, end_date
+        return None
 
-    now = datetime.now(timezone.utc)
-    return now - timedelta(days=days), now
+    today = datetime.now(timezone.utc).date()
+    start_date = today - timedelta(days=days - 1)
+    return TimeRangeParams(
+        start_date=start_date,
+        end_date=today,
+        timezone="UTC",
+        tz_offset_minutes=0,
+    ).validate_and_resolve()
+
+
+def _build_time_range_params(
+    start_date: date | None,
+    end_date: date | None,
+    preset: str | None,
+    timezone_name: str | None,
+    tz_offset_minutes: int | None,
+) -> TimeRangeParams | None:
+    if not preset and start_date is None and end_date is None:
+        return None
+    try:
+        return TimeRangeParams(
+            start_date=start_date,
+            end_date=end_date,
+            preset=preset,
+            timezone=timezone_name,
+            tz_offset_minutes=tz_offset_minutes or 0,
+        ).validate_and_resolve()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
 
 
 # ==================== RESTful Routes ====================
@@ -61,8 +86,11 @@ async def get_usage_aggregation(
     group_by: str = Query(
         ..., description="Aggregation dimension: model, user, provider, or api_format"
     ),
-    start_date: datetime | None = None,
-    end_date: datetime | None = None,
+    start_date: date | None = None,
+    end_date: date | None = None,
+    preset: str | None = None,
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = None,
     limit: int = Query(20, ge=1, le=100),
     db: Session = Depends(get_db),
 ) -> Any:
@@ -83,16 +111,18 @@ async def get_usage_aggregation(
     - 按提供商聚合时：provider_id, provider, request_count, total_tokens, total_cost, actual_cost, avg_response_time_ms, success_rate, error_count
     - 按 API 格式聚合时：api_format, request_count, total_tokens, total_cost, actual_cost, avg_response_time_ms
     """
+    time_range = _apply_admin_default_range(
+        _build_time_range_params(start_date, end_date, preset, timezone_name, tz_offset_minutes)
+    )
+
     if group_by == "model":
-        adapter = AdminUsageByModelAdapter(start_date=start_date, end_date=end_date, limit=limit)
+        adapter = AdminUsageByModelAdapter(time_range=time_range, limit=limit)
     elif group_by == "user":
-        adapter = AdminUsageByUserAdapter(start_date=start_date, end_date=end_date, limit=limit)
+        adapter = AdminUsageByUserAdapter(time_range=time_range, limit=limit)
     elif group_by == "provider":
-        adapter = AdminUsageByProviderAdapter(start_date=start_date, end_date=end_date, limit=limit)
+        adapter = AdminUsageByProviderAdapter(time_range=time_range, limit=limit)
     elif group_by == "api_format":
-        adapter = AdminUsageByApiFormatAdapter(
-            start_date=start_date, end_date=end_date, limit=limit
-        )
+        adapter = AdminUsageByApiFormatAdapter(time_range=time_range, limit=limit)
     else:
         raise HTTPException(
             status_code=400,
@@ -104,8 +134,11 @@ async def get_usage_aggregation(
 @router.get("/stats")
 async def get_usage_stats(
     request: Request,
-    start_date: datetime | None = None,
-    end_date: datetime | None = None,
+    start_date: date | None = None,
+    end_date: date | None = None,
+    preset: str | None = None,
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = None,
     db: Session = Depends(get_db),
 ) -> Any:
     """
@@ -127,7 +160,10 @@ async def get_usage_stats(
     - `error_rate`: 错误率（百分比）
     - `cache_stats`: 缓存统计信息（cache_creation_tokens, cache_read_tokens, cache_creation_cost, cache_read_cost）
     """
-    adapter = AdminUsageStatsAdapter(start_date=start_date, end_date=end_date)
+    time_range = _apply_admin_default_range(
+        _build_time_range_params(start_date, end_date, preset, timezone_name, tz_offset_minutes)
+    )
+    adapter = AdminUsageStatsAdapter(time_range=time_range)
     return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
 
 
@@ -151,13 +187,17 @@ async def get_activity_heatmap(
 @router.get("/records")
 async def get_usage_records(
     request: Request,
-    start_date: datetime | None = None,
-    end_date: datetime | None = None,
+    start_date: date | None = None,
+    end_date: date | None = None,
+    preset: str | None = None,
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = None,
     search: str | None = None,  # 通用搜索：用户名、密钥名、模型名、提供商名
     user_id: str | None = None,
     username: str | None = None,
     model: str | None = None,
     provider: str | None = None,
+    api_format: str | None = None,  # API 格式筛选（如 openai:chat, claude:chat）
     status: str | None = None,  # stream, standard, error
     limit: int = Query(100, ge=1, le=500),
     offset: int = Query(0, ge=0),
@@ -176,6 +216,7 @@ async def get_usage_records(
     - `username`: 可选，用户名模糊搜索
     - `model`: 可选，模型名模糊搜索
     - `provider`: 可选，提供商名称搜索
+    - `api_format`: 可选，API 格式筛选（如 openai:chat, claude:chat）
     - `status`: 可选，状态筛选（stream: 流式请求，standard: 标准请求，error: 错误请求，pending: 等待中，streaming: 流式中，completed: 已完成，failed: 失败，active: 活跃请求）
     - `limit`: 返回数量限制，默认 100，最大 500
     - `offset`: 分页偏移量，默认 0
@@ -190,14 +231,17 @@ async def get_usage_records(
     - `limit`: 当前分页限制
     - `offset`: 当前分页偏移量
     """
+    time_range = _apply_admin_default_range(
+        _build_time_range_params(start_date, end_date, preset, timezone_name, tz_offset_minutes)
+    )
     adapter = AdminUsageRecordsAdapter(
-        start_date=start_date,
-        end_date=end_date,
+        time_range=time_range,
         search=search,
         user_id=user_id,
         username=username,
         model=model,
         provider=provider,
+        api_format=api_format,
         status=status,
         limit=limit,
         offset=offset,
@@ -288,73 +332,87 @@ async def get_usage_detail(
 
 
 class AdminUsageStatsAdapter(AdminApiAdapter):
-    def __init__(self, start_date: datetime | None, end_date: datetime | None):
-        self.start_date, self.end_date = _apply_admin_default_range(start_date, end_date)
+    def __init__(self, time_range: TimeRangeParams | None):
+        self.time_range = _apply_admin_default_range(time_range)
+        self.start_date = self.time_range.start_date if self.time_range else None
+        self.end_date = self.time_range.end_date if self.time_range else None
+        self.preset = self.time_range.preset if self.time_range else None
+        self.timezone = self.time_range.timezone if self.time_range else None
+        self.tz_offset_minutes = self.time_range.tz_offset_minutes if self.time_range else None
 
     @cache_result(
         key_prefix="admin:usage:stats",
         ttl=CacheTTL.ADMIN_USAGE_AGGREGATION,
         user_specific=False,
-        vary_by=["start_date", "end_date"],
+        vary_by=["start_date", "end_date", "preset", "timezone", "tz_offset_minutes"],
     )
     async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
-        # Perf: use a single aggregate query (avoid 3 full scans).
-        from sqlalchemy import case
-
         db = context.db
-        query = db.query(Usage)
-        if self.start_date:
-            query = query.filter(Usage.created_at >= self.start_date)
-        if self.end_date:
-            query = query.filter(Usage.created_at <= self.end_date)
-
-        stats = query.with_entities(
-            func.count(Usage.id).label("total_requests"),
-            func.sum(Usage.total_tokens).label("total_tokens"),
-            func.sum(Usage.total_cost_usd).label("total_cost"),
-            func.sum(Usage.actual_total_cost_usd).label("total_actual_cost"),
-            func.avg(Usage.response_time_ms).label("avg_response_time_ms"),
-            func.sum(Usage.cache_creation_input_tokens).label("cache_creation_tokens"),
-            func.sum(Usage.cache_read_input_tokens).label("cache_read_tokens"),
-            func.sum(Usage.cache_creation_cost_usd).label("cache_creation_cost"),
-            func.sum(Usage.cache_read_cost_usd).label("cache_read_cost"),
-            func.sum(
-                case(
-                    (
-                        (Usage.status_code >= 400) | (Usage.error_message.isnot(None)),
-                        1,
-                    ),
-                    else_=0,
-                )
-            ).label("error_count"),
-        ).first()
+        if self.time_range:
+            stats = query_stats_hybrid(db, self.time_range, filters=StatsFilter())
+        else:
+            error_cond = (Usage.status_code >= 400) | (Usage.error_message.isnot(None))
+            row = db.query(
+                func.count(Usage.id).label("total_requests"),
+                func.sum(case((error_cond, 1), else_=0)).label("error_requests"),
+                func.sum(Usage.input_tokens).label("input_tokens"),
+                func.sum(Usage.output_tokens).label("output_tokens"),
+                func.sum(Usage.cache_creation_input_tokens).label("cache_creation_tokens"),
+                func.sum(Usage.cache_read_input_tokens).label("cache_read_tokens"),
+                func.sum(Usage.cache_creation_cost_usd).label("cache_creation_cost"),
+                func.sum(Usage.cache_read_cost_usd).label("cache_read_cost"),
+                func.sum(Usage.total_cost_usd).label("total_cost"),
+                func.sum(Usage.actual_total_cost_usd).label("actual_total_cost"),
+                func.sum(Usage.response_time_ms).label("total_response_time_ms"),
+            ).first()
+            total_requests = int(getattr(row, "total_requests", 0) or 0)
+            error_requests = int(getattr(row, "error_requests", 0) or 0)
+            stats = AggregatedStats(
+                total_requests=total_requests,
+                success_requests=total_requests - error_requests,
+                error_requests=error_requests,
+                input_tokens=int(getattr(row, "input_tokens", 0) or 0),
+                output_tokens=int(getattr(row, "output_tokens", 0) or 0),
+                cache_creation_tokens=int(getattr(row, "cache_creation_tokens", 0) or 0),
+                cache_read_tokens=int(getattr(row, "cache_read_tokens", 0) or 0),
+                cache_creation_cost=float(getattr(row, "cache_creation_cost", 0) or 0.0),
+                cache_read_cost=float(getattr(row, "cache_read_cost", 0) or 0.0),
+                total_cost=float(getattr(row, "total_cost", 0) or 0.0),
+                actual_total_cost=float(getattr(row, "actual_total_cost", 0) or 0.0),
+                total_response_time_ms=float(getattr(row, "total_response_time_ms", 0) or 0.0),
+            )
 
         context.add_audit_metadata(
             action="usage_stats",
             start_date=self.start_date.isoformat() if self.start_date else None,
             end_date=self.end_date.isoformat() if self.end_date else None,
+            preset=self.preset,
+            timezone=self.timezone,
         )
-
-        total_requests = int(stats.total_requests or 0) if stats else 0
-        avg_response_time_ms = float(stats.avg_response_time_ms or 0) if stats else 0
-        avg_response_time = avg_response_time_ms / 1000.0
-        error_count = int(stats.error_count or 0) if stats else 0
+        total_requests = stats.total_requests
+        avg_response_time = stats.avg_response_time_ms / 1000.0
+        error_count = stats.error_requests
 
         return {
             "total_requests": total_requests,
-            "total_tokens": int(stats.total_tokens or 0) if stats else 0,
-            "total_cost": float(stats.total_cost or 0) if stats else 0,
-            "total_actual_cost": float(stats.total_actual_cost or 0) if stats else 0,
+            "total_tokens": int(
+                stats.input_tokens
+                + stats.output_tokens
+                + stats.cache_creation_tokens
+                + stats.cache_read_tokens
+            ),
+            "total_cost": float(stats.total_cost),
+            "total_actual_cost": float(stats.actual_total_cost),
             "avg_response_time": round(avg_response_time, 2),
             "error_count": error_count,
             "error_rate": (
                 round((error_count / total_requests) * 100, 2) if total_requests > 0 else 0
             ),
             "cache_stats": {
-                "cache_creation_tokens": (int(stats.cache_creation_tokens or 0) if stats else 0),
-                "cache_read_tokens": int(stats.cache_read_tokens or 0) if stats else 0,
-                "cache_creation_cost": (float(stats.cache_creation_cost or 0) if stats else 0),
-                "cache_read_cost": float(stats.cache_read_cost or 0) if stats else 0,
+                "cache_creation_tokens": int(stats.cache_creation_tokens),
+                "cache_read_tokens": int(stats.cache_read_tokens),
+                "cache_creation_cost": float(stats.cache_creation_cost),
+                "cache_read_cost": float(stats.cache_read_cost),
             },
         }
 
@@ -373,15 +431,20 @@ class AdminActivityHeatmapAdapter(AdminApiAdapter):
 
 
 class AdminUsageByModelAdapter(AdminApiAdapter):
-    def __init__(self, start_date: datetime | None, end_date: datetime | None, limit: int):
-        self.start_date, self.end_date = _apply_admin_default_range(start_date, end_date)
+    def __init__(self, time_range: TimeRangeParams | None, limit: int):
+        self.time_range = _apply_admin_default_range(time_range)
+        self.start_date = self.time_range.start_date if self.time_range else None
+        self.end_date = self.time_range.end_date if self.time_range else None
+        self.preset = self.time_range.preset if self.time_range else None
+        self.timezone = self.time_range.timezone if self.time_range else None
+        self.tz_offset_minutes = self.time_range.tz_offset_minutes if self.time_range else None
         self.limit = limit
 
     @cache_result(
         key_prefix="admin:usage:agg:model",
         ttl=CacheTTL.ADMIN_USAGE_AGGREGATION,
         user_specific=False,
-        vary_by=["start_date", "end_date", "limit"],
+        vary_by=["start_date", "end_date", "preset", "timezone", "tz_offset_minutes", "limit"],
     )
     async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
@@ -397,10 +460,9 @@ class AdminUsageByModelAdapter(AdminApiAdapter):
         # 过滤掉 unknown/pending provider_name（请求未到达任何提供商）
         query = query.filter(Usage.provider_name.notin_(["unknown", "pending"]))
 
-        if self.start_date:
-            query = query.filter(Usage.created_at >= self.start_date)
-        if self.end_date:
-            query = query.filter(Usage.created_at <= self.end_date)
+        if self.time_range:
+            start_utc, end_utc = self.time_range.to_utc_datetime_range()
+            query = query.filter(Usage.created_at >= start_utc, Usage.created_at < end_utc)
 
         query = query.group_by(Usage.model).order_by(func.count(Usage.id).desc()).limit(self.limit)
         stats = query.all()
@@ -408,6 +470,8 @@ class AdminUsageByModelAdapter(AdminApiAdapter):
             action="usage_by_model",
             start_date=self.start_date.isoformat() if self.start_date else None,
             end_date=self.end_date.isoformat() if self.end_date else None,
+            preset=self.preset,
+            timezone=self.timezone,
             limit=self.limit,
             result_count=len(stats),
         )
@@ -425,15 +489,20 @@ class AdminUsageByModelAdapter(AdminApiAdapter):
 
 
 class AdminUsageByUserAdapter(AdminApiAdapter):
-    def __init__(self, start_date: datetime | None, end_date: datetime | None, limit: int):
-        self.start_date, self.end_date = _apply_admin_default_range(start_date, end_date)
+    def __init__(self, time_range: TimeRangeParams | None, limit: int):
+        self.time_range = _apply_admin_default_range(time_range)
+        self.start_date = self.time_range.start_date if self.time_range else None
+        self.end_date = self.time_range.end_date if self.time_range else None
+        self.preset = self.time_range.preset if self.time_range else None
+        self.timezone = self.time_range.timezone if self.time_range else None
+        self.tz_offset_minutes = self.time_range.tz_offset_minutes if self.time_range else None
         self.limit = limit
 
     @cache_result(
         key_prefix="admin:usage:agg:user",
         ttl=CacheTTL.ADMIN_USAGE_AGGREGATION,
         user_specific=False,
-        vary_by=["start_date", "end_date", "limit"],
+        vary_by=["start_date", "end_date", "preset", "timezone", "tz_offset_minutes", "limit"],
     )
     async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
@@ -450,10 +519,9 @@ class AdminUsageByUserAdapter(AdminApiAdapter):
             .group_by(User.id, User.email, User.username)
         )
 
-        if self.start_date:
-            query = query.filter(Usage.created_at >= self.start_date)
-        if self.end_date:
-            query = query.filter(Usage.created_at <= self.end_date)
+        if self.time_range:
+            start_utc, end_utc = self.time_range.to_utc_datetime_range()
+            query = query.filter(Usage.created_at >= start_utc, Usage.created_at < end_utc)
 
         query = query.order_by(func.count(Usage.id).desc()).limit(self.limit)
         stats = query.all()
@@ -462,6 +530,8 @@ class AdminUsageByUserAdapter(AdminApiAdapter):
             action="usage_by_user",
             start_date=self.start_date.isoformat() if self.start_date else None,
             end_date=self.end_date.isoformat() if self.end_date else None,
+            preset=self.preset,
+            timezone=self.timezone,
             limit=self.limit,
             result_count=len(stats),
         )
@@ -480,15 +550,20 @@ class AdminUsageByUserAdapter(AdminApiAdapter):
 
 
 class AdminUsageByProviderAdapter(AdminApiAdapter):
-    def __init__(self, start_date: datetime | None, end_date: datetime | None, limit: int):
-        self.start_date, self.end_date = _apply_admin_default_range(start_date, end_date)
+    def __init__(self, time_range: TimeRangeParams | None, limit: int):
+        self.time_range = _apply_admin_default_range(time_range)
+        self.start_date = self.time_range.start_date if self.time_range else None
+        self.end_date = self.time_range.end_date if self.time_range else None
+        self.preset = self.time_range.preset if self.time_range else None
+        self.timezone = self.time_range.timezone if self.time_range else None
+        self.tz_offset_minutes = self.time_range.tz_offset_minutes if self.time_range else None
         self.limit = limit
 
     @cache_result(
         key_prefix="admin:usage:agg:provider",
         ttl=CacheTTL.ADMIN_USAGE_AGGREGATION,
         user_specific=False,
-        vary_by=["start_date", "end_date", "limit"],
+        vary_by=["start_date", "end_date", "preset", "timezone", "tz_offset_minutes", "limit"],
     )
     async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
@@ -511,10 +586,12 @@ class AdminUsageByProviderAdapter(AdminApiAdapter):
             RequestCandidate.status.in_(["success", "failed"]),
         )
 
-        if self.start_date:
-            attempt_query = attempt_query.filter(RequestCandidate.created_at >= self.start_date)
-        if self.end_date:
-            attempt_query = attempt_query.filter(RequestCandidate.created_at <= self.end_date)
+        if self.time_range:
+            start_utc, end_utc = self.time_range.to_utc_datetime_range()
+            attempt_query = attempt_query.filter(
+                RequestCandidate.created_at >= start_utc,
+                RequestCandidate.created_at < end_utc,
+            )
 
         attempt_stats = (
             attempt_query.group_by(RequestCandidate.provider_id)
@@ -537,10 +614,11 @@ class AdminUsageByProviderAdapter(AdminApiAdapter):
             Usage.status.notin_(["pending", "streaming"]),
         )
 
-        if self.start_date:
-            usage_query = usage_query.filter(Usage.created_at >= self.start_date)
-        if self.end_date:
-            usage_query = usage_query.filter(Usage.created_at <= self.end_date)
+        if self.time_range:
+            start_utc, end_utc = self.time_range.to_utc_datetime_range()
+            usage_query = usage_query.filter(
+                Usage.created_at >= start_utc, Usage.created_at < end_utc
+            )
 
         usage_stats = usage_query.group_by(Usage.provider_id).all()
         usage_map = {str(u.provider_id): u for u in usage_stats}
@@ -566,6 +644,8 @@ class AdminUsageByProviderAdapter(AdminApiAdapter):
             action="usage_by_provider",
             start_date=self.start_date.isoformat() if self.start_date else None,
             end_date=self.end_date.isoformat() if self.end_date else None,
+            preset=self.preset,
+            timezone=self.timezone,
             limit=self.limit,
             result_count=len(attempt_stats),
         )
@@ -599,15 +679,20 @@ class AdminUsageByProviderAdapter(AdminApiAdapter):
 
 
 class AdminUsageByApiFormatAdapter(AdminApiAdapter):
-    def __init__(self, start_date: datetime | None, end_date: datetime | None, limit: int):
-        self.start_date, self.end_date = _apply_admin_default_range(start_date, end_date)
+    def __init__(self, time_range: TimeRangeParams | None, limit: int):
+        self.time_range = _apply_admin_default_range(time_range)
+        self.start_date = self.time_range.start_date if self.time_range else None
+        self.end_date = self.time_range.end_date if self.time_range else None
+        self.preset = self.time_range.preset if self.time_range else None
+        self.timezone = self.time_range.timezone if self.time_range else None
+        self.tz_offset_minutes = self.time_range.tz_offset_minutes if self.time_range else None
         self.limit = limit
 
     @cache_result(
         key_prefix="admin:usage:agg:api_format",
         ttl=CacheTTL.ADMIN_USAGE_AGGREGATION,
         user_specific=False,
-        vary_by=["start_date", "end_date", "limit"],
+        vary_by=["start_date", "end_date", "preset", "timezone", "tz_offset_minutes", "limit"],
     )
     async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
@@ -626,10 +711,9 @@ class AdminUsageByApiFormatAdapter(AdminApiAdapter):
         # 只统计有 api_format 的记录
         query = query.filter(Usage.api_format.isnot(None))
 
-        if self.start_date:
-            query = query.filter(Usage.created_at >= self.start_date)
-        if self.end_date:
-            query = query.filter(Usage.created_at <= self.end_date)
+        if self.time_range:
+            start_utc, end_utc = self.time_range.to_utc_datetime_range()
+            query = query.filter(Usage.created_at >= start_utc, Usage.created_at < end_utc)
 
         query = (
             query.group_by(Usage.api_format).order_by(func.count(Usage.id).desc()).limit(self.limit)
@@ -640,6 +724,8 @@ class AdminUsageByApiFormatAdapter(AdminApiAdapter):
             action="usage_by_api_format",
             start_date=self.start_date.isoformat() if self.start_date else None,
             end_date=self.end_date.isoformat() if self.end_date else None,
+            preset=self.preset,
+            timezone=self.timezone,
             limit=self.limit,
             result_count=len(stats),
         )
@@ -660,23 +746,29 @@ class AdminUsageByApiFormatAdapter(AdminApiAdapter):
 class AdminUsageRecordsAdapter(AdminApiAdapter):
     def __init__(
         self,
-        start_date: datetime | None,
-        end_date: datetime | None,
+        time_range: TimeRangeParams | None,
         search: str | None,
         user_id: str | None,
         username: str | None,
         model: str | None,
         provider: str | None,
+        api_format: str | None,
         status: str | None,
         limit: int,
         offset: int,
     ):
-        self.start_date, self.end_date = _apply_admin_default_range(start_date, end_date)
+        self.time_range = _apply_admin_default_range(time_range)
+        self.start_date = self.time_range.start_date if self.time_range else None
+        self.end_date = self.time_range.end_date if self.time_range else None
+        self.preset = self.time_range.preset if self.time_range else None
+        self.timezone = self.time_range.timezone if self.time_range else None
+        self.tz_offset_minutes = self.time_range.tz_offset_minutes if self.time_range else None
         self.search = search
         self.user_id = user_id
         self.username = username
         self.model = model
         self.provider = provider
+        self.api_format = api_format
         self.status = status
         self.limit = limit
         self.offset = offset
@@ -688,11 +780,15 @@ class AdminUsageRecordsAdapter(AdminApiAdapter):
         vary_by=[
             "start_date",
             "end_date",
+            "preset",
+            "timezone",
+            "tz_offset_minutes",
             "search",
             "user_id",
             "username",
             "model",
             "provider",
+            "api_format",
             "status",
             "limit",
             "offset",
@@ -748,6 +844,9 @@ class AdminUsageRecordsAdapter(AdminApiAdapter):
             # 提供商筛选：前端为下拉框精确值，使用精确匹配以启用索引
             # 如需模糊搜索，请使用 search 参数。
             query = query.filter(Provider.name == self.provider)
+        if self.api_format:
+            # API 格式筛选：精确匹配（大小写不敏感）
+            query = query.filter(func.lower(Usage.api_format) == self.api_format.lower())
         if self.status:
             # 状态筛选
             # 旧的筛选值（基于 is_stream 和 status_code）：stream, standard, error
@@ -773,10 +872,9 @@ class AdminUsageRecordsAdapter(AdminApiAdapter):
             elif self.status == "active":
                 # 活跃请求：pending 或 streaming 状态
                 query = query.filter(Usage.status.in_(["pending", "streaming"]))
-        if self.start_date:
-            query = query.filter(Usage.created_at >= self.start_date)
-        if self.end_date:
-            query = query.filter(Usage.created_at <= self.end_date)
+        if self.time_range:
+            start_utc, end_utc = self.time_range.to_utc_datetime_range()
+            query = query.filter(Usage.created_at >= start_utc, Usage.created_at < end_utc)
 
         # Perf: avoid Query.count() building a subquery selecting many columns
         total = int(query.with_entities(func.count(Usage.id)).scalar() or 0)
@@ -875,6 +973,8 @@ class AdminUsageRecordsAdapter(AdminApiAdapter):
             action="usage_records",
             start_date=self.start_date.isoformat() if self.start_date else None,
             end_date=self.end_date.isoformat() if self.end_date else None,
+            preset=self.preset,
+            timezone=self.timezone,
             search=self.search,
             user_id=self.user_id,
             username=self.username,

src/api/dashboard/routes.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
+from datetime import date, datetime, timedelta, timezone
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
@@ -27,7 +27,12 @@ from src.models.database import (
     Usage,
 )
 from src.models.database import User as DBUser
-from src.services.system.stats_aggregator import StatsAggregatorService
+from src.services.system.stats_aggregator import (
+    StatsAggregatorService,
+    TimeSeriesFilter,
+    query_time_series,
+)
+from src.services.system.time_range import TimeRangeParams
 from src.utils.cache_decorator import cache_result
 
 router = APIRouter(prefix="/api/dashboard", tags=["Dashboard"])
@@ -55,6 +60,29 @@ def format_tokens(num: int) -> str:
         return f"{millions:.2f}M"
 
 
+def _build_time_range_params(
+    start_date: date | None,
+    end_date: date | None,
+    preset: str | None,
+    timezone_name: str | None,
+    tz_offset_minutes: int | None,
+    granularity: str | None = None,
+) -> TimeRangeParams | None:
+    if not preset and start_date is None and end_date is None:
+        return None
+    try:
+        return TimeRangeParams(
+            start_date=start_date,
+            end_date=end_date,
+            preset=preset,
+            granularity=granularity or "day",
+            timezone=timezone_name,
+            tz_offset_minutes=tz_offset_minutes or 0,
+        ).validate_and_resolve()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
 @router.get("/stats")
 async def get_dashboard_stats(request: Request, db: Session = Depends(get_db)) -> Any:
     """
@@ -136,6 +164,12 @@ async def get_provider_status(request: Request, db: Session = Depends(get_db)) -
 async def get_daily_stats(
     request: Request,
     days: int = Query(7, ge=1, le=30),
+    start_date: date | None = Query(None, description="开始日期（YYYY-MM-DD）"),
+    end_date: date | None = Query(None, description="结束日期（YYYY-MM-DD）"),
+    preset: str | None = Query(None, description="时间预设（today/last7days 等）"),
+    granularity: str = Query("day", description="时间粒度: hour/day/week/month"),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(None, description="时区偏移（分钟）"),
     db: Session = Depends(get_db),
 ) -> Any:
     """
@@ -160,7 +194,30 @@ async def get_daily_stats(
     - `model_summary`: 模型使用汇总，按费用排序
     - `period`: 统计周期信息（start_date, end_date, days）
     """
-    adapter = DashboardDailyStatsAdapter(days=days)
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes, granularity
+    )
+    if time_range is None:
+        # fallback to days
+        tmp = TimeRangeParams(
+            start_date=None,
+            end_date=None,
+            preset="today",
+            granularity=granularity,
+            timezone=timezone_name,
+            tz_offset_minutes=tz_offset_minutes or 0,
+        )
+        user_today = tmp._get_user_today()
+        start = user_today - timedelta(days=days - 1)
+        time_range = TimeRangeParams(
+            start_date=start,
+            end_date=user_today,
+            granularity=granularity,
+            timezone=timezone_name,
+            tz_offset_minutes=tz_offset_minutes or 0,
+        ).validate_and_resolve()
+
+    adapter = DashboardDailyStatsAdapter(time_range=time_range, days=days)
     return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
 
 
@@ -194,21 +251,12 @@ class AdminDashboardStatsAdapter(AdminApiAdapter):
     )
     async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         """管理员仪表盘统计 - 使用预聚合数据优化性能"""
-        from zoneinfo import ZoneInfo
-
-        from src.services.system.stats_aggregator import APP_TIMEZONE
-
         db = context.db
-        # 使用业务时区计算日期，与 stats_daily 表保持一致
-        app_tz = ZoneInfo(APP_TIMEZONE)
-        now_local = datetime.now(app_tz)
-        today_local = now_local.replace(hour=0, minute=0, second=0, microsecond=0)
-        # 转换为 UTC 用于与 stats_daily.date 比较（存储的是业务日期对应的 UTC 开始时间）
-        today = today_local.astimezone(timezone.utc)
-        yesterday = (today_local - timedelta(days=1)).astimezone(timezone.utc)
-        # 本月第一天（自然月）
-        month_start_local = today_local.replace(day=1)
-        month_start = month_start_local.astimezone(timezone.utc)
+        # 使用 UTC 日期，与 stats_daily.date 一致
+        now_utc = datetime.now(timezone.utc)
+        today = now_utc.replace(hour=0, minute=0, second=0, microsecond=0)
+        yesterday = today - timedelta(days=1)
+        month_start = today.replace(day=1)
 
         # ==================== 使用预聚合数据 ====================
         # 今日实时数据只查询一次，避免重复扫描 Usage 表
@@ -887,20 +935,169 @@ class DashboardProviderStatusAdapter(DashboardAdapter):
 @dataclass
 class DashboardDailyStatsAdapter(DashboardAdapter):
     days: int
+    time_range: TimeRangeParams | None = None
+    start_date: date | None = None
+    end_date: date | None = None
+    preset: str | None = None
+    granularity: str | None = None
+    timezone: str | None = None
+    tz_offset_minutes: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.time_range:
+            self.start_date = self.time_range.start_date
+            self.end_date = self.time_range.end_date
+            self.preset = self.time_range.preset
+            self.granularity = self.time_range.granularity
+            self.timezone = self.time_range.timezone
+            self.tz_offset_minutes = self.time_range.tz_offset_minutes
 
     @cache_result(
-        key_prefix="dashboard:daily:stats", ttl=CacheTTL.DASHBOARD_DAILY, user_specific=True
+        key_prefix="dashboard:daily:stats",
+        ttl=CacheTTL.DASHBOARD_DAILY,
+        user_specific=True,
+        vary_by=[
+            "start_date",
+            "end_date",
+            "preset",
+            "granularity",
+            "timezone",
+            "tz_offset_minutes",
+        ],
     )
     async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
-        from zoneinfo import ZoneInfo
-
-        from src.services.system.stats_aggregator import APP_TIMEZONE
-
         db = context.db
         user = context.user
         is_admin = user.role == UserRole.ADMIN
 
+        if self.time_range:
+            try:
+                series = query_time_series(
+                    db,
+                    self.time_range,
+                    filters=TimeSeriesFilter(user_id=user.id) if not is_admin else None,
+                )
+            except ValueError as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+            formatted = []
+            for item in series:
+                total_tokens = (
+                    item["input_tokens"]
+                    + item["output_tokens"]
+                    + item.get("cache_creation_tokens", 0)
+                    + item.get("cache_read_tokens", 0)
+                )
+                formatted.append(
+                    {
+                        "date": item["date"],
+                        "requests": item["total_requests"],
+                        "tokens": total_tokens,
+                        "cost": item["total_cost"],
+                        "avg_response_time": (item.get("avg_response_time_ms", 0.0) / 1000.0),
+                        "unique_models": 0,
+                        "unique_providers": 0,
+                        "fallback_count": 0,
+                    }
+                )
+
+            # Model summary (use Usage directly for now)
+            start_utc, end_utc = self.time_range.to_utc_datetime_range()
+            model_query = db.query(
+                Usage.model,
+                func.count(Usage.id).label("requests"),
+                func.sum(Usage.total_tokens).label("tokens"),
+                func.sum(Usage.total_cost_usd).label("cost"),
+            ).filter(Usage.created_at >= start_utc, Usage.created_at < end_utc)
+            if not is_admin:
+                model_query = model_query.filter(Usage.user_id == user.id)
+            model_stats = (
+                model_query.group_by(Usage.model)
+                .order_by(func.sum(Usage.total_cost_usd).desc())
+                .all()
+            )
+            model_summary = [
+                {
+                    "model": stat.model,
+                    "requests": stat.requests or 0,
+                    "tokens": int(stat.tokens or 0),
+                    "cost": float(stat.cost or 0),
+                    "avg_response_time": 0,
+                    "cost_per_request": float(stat.cost or 0) / max(stat.requests or 1, 1),
+                    "tokens_per_request": int(stat.tokens or 0) / max(stat.requests or 1, 1),
+                }
+                for stat in model_stats
+            ]
+
+            # Daily model breakdown (aligned to local days)
+            breakdown_map: dict[str, list[dict]] = {}
+            for local_date, day_start, day_end in self.time_range.get_local_day_hours():
+                day_query = db.query(
+                    Usage.model,
+                    func.count(Usage.id).label("requests"),
+                    func.sum(Usage.total_tokens).label("tokens"),
+                    func.sum(Usage.total_cost_usd).label("cost"),
+                ).filter(Usage.created_at >= day_start, Usage.created_at < day_end)
+                if not is_admin:
+                    day_query = day_query.filter(Usage.user_id == user.id)
+                day_stats = day_query.group_by(Usage.model).all()
+                breakdown_map[local_date.isoformat()] = [
+                    {
+                        "model": stat.model,
+                        "requests": stat.requests or 0,
+                        "tokens": int(stat.tokens or 0),
+                        "cost": float(stat.cost or 0),
+                    }
+                    for stat in day_stats
+                    if stat.model
+                ]
+
+            for item in formatted:
+                item["model_breakdown"] = breakdown_map.get(item["date"], [])
+
+            provider_summary = None
+            if is_admin:
+                provider_stats = (
+                    db.query(
+                        Usage.provider_name,
+                        func.count(Usage.id).label("requests"),
+                        func.sum(Usage.total_tokens).label("tokens"),
+                        func.sum(Usage.total_cost_usd).label("cost"),
+                    )
+                    .filter(Usage.created_at >= start_utc, Usage.created_at < end_utc)
+                    .group_by(Usage.provider_name)
+                    .all()
+                )
+                provider_summary = [
+                    {
+                        "provider": stat.provider_name or "Unknown",
+                        "requests": stat.requests or 0,
+                        "tokens": int(stat.tokens or 0),
+                        "cost": float(stat.cost or 0),
+                    }
+                    for stat in provider_stats
+                    if (stat.provider_name or "").lower() != "unknown"
+                ]
+                provider_summary.sort(key=lambda x: x["cost"], reverse=True)
+
+            result = {
+                "daily_stats": formatted,
+                "model_summary": model_summary,
+                "period": {
+                    "start_date": self.time_range.start_date.isoformat(),
+                    "end_date": self.time_range.end_date.isoformat(),
+                    "days": (self.time_range.end_date - self.time_range.start_date).days + 1,
+                },
+            }
+            if is_admin and provider_summary is not None:
+                result["provider_summary"] = provider_summary
+            return result
+
         # 使用业务时区计算日期，确保每日统计与业务日期一致
+        from zoneinfo import ZoneInfo
+
+        from src.services.system.stats_aggregator import APP_TIMEZONE
+
         app_tz = ZoneInfo(APP_TIMEZONE)
         now_local = datetime.now(app_tz)
         today_local = now_local.replace(hour=0, minute=0, second=0, microsecond=0)

src/api/user_me/routes.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import date, datetime, timedelta, timezone
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
@@ -33,6 +33,7 @@ from src.models.api import (
     UpdateProfileRequest,
 )
 from src.models.database import ApiKey, GlobalModel, Model, Provider, Usage, User
+from src.services.system.time_range import TimeRangeParams
 from src.services.usage.service import UsageService
 from src.services.user.apikey import ApiKeyService
 from src.services.user.preference import PreferenceService
@@ -41,6 +42,27 @@ router = APIRouter(prefix="/api/users/me", tags=["User Profile"])
 pipeline = ApiRequestPipeline()
 
 
+def _build_time_range_params(
+    start_date: date | None,
+    end_date: date | None,
+    preset: str | None,
+    timezone_name: str | None,
+    tz_offset_minutes: int | None,
+) -> TimeRangeParams | None:
+    if not preset and start_date is None and end_date is None:
+        return None
+    try:
+        return TimeRangeParams(
+            start_date=start_date,
+            end_date=end_date,
+            preset=preset,
+            timezone=timezone_name,
+            tz_offset_minutes=tz_offset_minutes or 0,
+        ).validate_and_resolve()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
 @router.get("")
 async def get_my_profile(request: Request, db: Session = Depends(get_db)) -> Any:
     """
@@ -176,8 +198,11 @@ async def toggle_my_api_key(key_id: str, request: Request, db: Session = Depends
 @router.get("/usage")
 async def get_my_usage(
     request: Request,
-    start_date: datetime | None = Query(None, description="开始时间（ISO 格式）"),
-    end_date: datetime | None = Query(None, description="结束时间（ISO 格式）"),
+    start_date: date | None = Query(None, description="开始日期（YYYY-MM-DD）"),
+    end_date: date | None = Query(None, description="结束日期（YYYY-MM-DD）"),
+    preset: str | None = Query(None, description="时间预设（today/last7days 等）"),
+    timezone_name: str | None = Query(None, alias="timezone"),
+    tz_offset_minutes: int | None = Query(None, description="时区偏移（分钟）"),
     search: str | None = Query(None, description="搜索关键词（密钥名、模型名）"),
     limit: int = Query(100, ge=1, le=200, description="每页记录数，默认100，最大200"),
     offset: int = Query(0, ge=0, le=2000, description="偏移量，用于分页，最大2000"),
@@ -197,9 +222,10 @@ async def get_my_usage(
     - `records`: 详细使用记录列表
     - `pagination`: 分页信息
     """
-    adapter = GetUsageAdapter(
-        start_date=start_date, end_date=end_date, search=search, limit=limit, offset=offset
+    time_range = _build_time_range_params(
+        start_date, end_date, preset, timezone_name, tz_offset_minutes
     )
+    adapter = GetUsageAdapter(time_range=time_range, search=search, limit=limit, offset=offset)
     return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
 
 
@@ -728,8 +754,7 @@ class ToggleMyApiKeyAdapter(AuthenticatedApiAdapter):
 class GetUsageAdapter(AuthenticatedApiAdapter):
     """获取用户使用统计的适配器"""
 
-    start_date: datetime | None
-    end_date: datetime | None
+    time_range: TimeRangeParams | None
     search: str | None = None
     limit: int = 100
     offset: int = 0
@@ -743,11 +768,14 @@ class GetUsageAdapter(AuthenticatedApiAdapter):
 
         db = context.db
         user = context.user
+        start_utc = end_utc = None
+        if self.time_range:
+            start_utc, end_utc = self.time_range.to_utc_datetime_range()
         summary_list = UsageService.get_usage_summary(
             db=db,
             user_id=user.id,
-            start_date=self.start_date,
-            end_date=self.end_date,
+            start_date=start_utc,
+            end_date=end_utc,
         )
 
         # 过滤掉 unknown/pending provider 的记录（请求未到达任何提供商）
@@ -858,10 +886,8 @@ class GetUsageAdapter(AuthenticatedApiAdapter):
             .outerjoin(ProviderEndpoint, Usage.provider_endpoint_id == ProviderEndpoint.id)
             .filter(Usage.user_id == user.id)
         )
-        if self.start_date:
-            query = query.filter(Usage.created_at >= self.start_date)
-        if self.end_date:
-            query = query.filter(Usage.created_at <= self.end_date)
+        if start_utc and end_utc:
+            query = query.filter(Usage.created_at >= start_utc, Usage.created_at < end_utc)
 
         # 通用搜索：密钥名、模型名
         # 支持空格分隔的组合搜索，多个关键词之间是 AND 关系
@@ -925,10 +951,10 @@ class GetUsageAdapter(AuthenticatedApiAdapter):
             Usage.status_code == 200,
             Usage.response_time_ms.isnot(None),
         )
-        if self.start_date:
-            avg_resp_query = avg_resp_query.filter(Usage.created_at >= self.start_date)
-        if self.end_date:
-            avg_resp_query = avg_resp_query.filter(Usage.created_at <= self.end_date)
+        if start_utc and end_utc:
+            avg_resp_query = avg_resp_query.filter(
+                Usage.created_at >= start_utc, Usage.created_at < end_utc
+            )
         avg_response_ms = avg_resp_query.scalar() or 0
         avg_response_time = float(avg_response_ms) / 1000.0 if avg_response_ms else 0
 

src/config/constants.py

@@ -32,6 +32,9 @@ class CacheTTL:
     ADMIN_USAGE_AGGREGATION = 30  # 30秒
     ADMIN_USAGE_RECORDS = 10  # 10秒（列表页短缓存，避免轮询/重复刷新打爆 DB）
 
+    # Admin leaderboard (heavier, slower moving)
+    ADMIN_LEADERBOARD = 300  # 5分钟
+
     # 并发锁 TTL - 防止死锁
     CONCURRENCY_LOCK = 600  # 10分钟
 

src/core/enums.py

@@ -29,3 +29,19 @@ class AuthSource(str, Enum):
     LOCAL = "local"  # 本地认证
     LDAP = "ldap"  # LDAP 认证
     OAUTH = "oauth"  # OAuth 认证（账号首创来源）
+
+
+class ErrorCategory(str, Enum):
+    """错误分类枚举"""
+
+    RATE_LIMIT = "rate_limit"
+    AUTH = "auth"
+    INVALID_REQUEST = "invalid_request"
+    NOT_FOUND = "not_found"
+    CONTENT_FILTER = "content_filter"
+    CONTEXT_LENGTH = "context_length"
+    SERVER_ERROR = "server_error"
+    TIMEOUT = "timeout"
+    NETWORK = "network"
+    CANCELLED = "cancelled"
+    UNKNOWN = "unknown"

src/models/database.py

@@ -344,6 +344,7 @@ class Usage(Base):
     is_stream = Column(Boolean, default=False)  # 是否为流式请求
     status_code = Column(Integer)
     error_message = Column(Text, nullable=True)
+    error_category = Column(String(50), nullable=True, index=True)
     response_time_ms = Column(Integer)  # 总响应时间（毫秒）
     first_byte_time_ms = Column(Integer, nullable=True)  # 首字时间/TTFB（毫秒）
 
@@ -1944,6 +1945,147 @@ class RequestCandidate(Base):
 # ==================== 统计数据模型 ====================
 
 
+class StatsHourly(Base):
+    """小时级统计快照 - 用于时间序列查询"""
+
+    __tablename__ = "stats_hourly"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+
+    # 小时起点 (UTC)
+    hour_utc = Column(DateTime(timezone=True), nullable=False, unique=True, index=True)
+
+    # 请求统计
+    total_requests = Column(Integer, default=0, nullable=False)
+    success_requests = Column(Integer, default=0, nullable=False)
+    error_requests = Column(Integer, default=0, nullable=False)
+
+    # Token 统计
+    input_tokens = Column(BigInteger, default=0, nullable=False)
+    output_tokens = Column(BigInteger, default=0, nullable=False)
+    cache_creation_tokens = Column(BigInteger, default=0, nullable=False)
+    cache_read_tokens = Column(BigInteger, default=0, nullable=False)
+
+    # 成本统计 (USD)
+    total_cost = Column(Float, default=0.0, nullable=False)
+    actual_total_cost = Column(Float, default=0.0, nullable=False)
+
+    # 性能统计
+    avg_response_time_ms = Column(Float, default=0.0, nullable=False)
+
+    # 完成标记
+    is_complete = Column(Boolean, default=False, nullable=False)
+    aggregated_at = Column(DateTime(timezone=True), nullable=True)
+
+    # 时间戳
+    created_at = Column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (Index("idx_stats_hourly_hour", "hour_utc"),)
+
+
+class StatsHourlyUser(Base):
+    """小时级用户维度统计"""
+
+    __tablename__ = "stats_hourly_user"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    hour_utc = Column(DateTime(timezone=True), nullable=False, index=True)
+    user_id = Column(String(36), nullable=False, index=True)
+
+    total_requests = Column(Integer, default=0, nullable=False)
+    success_requests = Column(Integer, default=0, nullable=False)
+    error_requests = Column(Integer, default=0, nullable=False)
+    input_tokens = Column(BigInteger, default=0, nullable=False)
+    output_tokens = Column(BigInteger, default=0, nullable=False)
+    total_cost = Column(Float, default=0.0, nullable=False)
+
+    created_at = Column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint("hour_utc", "user_id", name="uq_stats_hourly_user"),
+        Index("idx_stats_hourly_user_hour", "hour_utc"),
+        Index("idx_stats_hourly_user_user_hour", "user_id", "hour_utc"),
+    )
+
+
+class StatsHourlyModel(Base):
+    """小时级模型维度统计"""
+
+    __tablename__ = "stats_hourly_model"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    hour_utc = Column(DateTime(timezone=True), nullable=False, index=True)
+    model = Column(String(100), nullable=False, index=True)
+
+    total_requests = Column(Integer, default=0, nullable=False)
+    input_tokens = Column(BigInteger, default=0, nullable=False)
+    output_tokens = Column(BigInteger, default=0, nullable=False)
+    total_cost = Column(Float, default=0.0, nullable=False)
+    avg_response_time_ms = Column(Float, default=0.0, nullable=False)
+
+    created_at = Column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint("hour_utc", "model", name="uq_stats_hourly_model"),
+        Index("idx_stats_hourly_model_hour", "hour_utc"),
+        Index("idx_stats_hourly_model_model_hour", "model", "hour_utc"),
+    )
+
+
+class StatsHourlyProvider(Base):
+    """小时级提供商维度统计"""
+
+    __tablename__ = "stats_hourly_provider"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    hour_utc = Column(DateTime(timezone=True), nullable=False, index=True)
+    provider_name = Column(String(100), nullable=False, index=True)
+
+    total_requests = Column(Integer, default=0, nullable=False)
+    input_tokens = Column(BigInteger, default=0, nullable=False)
+    output_tokens = Column(BigInteger, default=0, nullable=False)
+    total_cost = Column(Float, default=0.0, nullable=False)
+
+    created_at = Column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint("hour_utc", "provider_name", name="uq_stats_hourly_provider"),
+        Index("idx_stats_hourly_provider_hour", "hour_utc"),
+    )
+
+
 class StatsDaily(Base):
     """每日统计快照 - 用于快速查询历史数据"""
 
@@ -1975,12 +2117,22 @@ class StatsDaily(Base):
 
     # 性能统计
     avg_response_time_ms = Column(Float, default=0.0, nullable=False)
+    p50_response_time_ms = Column(Integer, nullable=True)
+    p90_response_time_ms = Column(Integer, nullable=True)
+    p99_response_time_ms = Column(Integer, nullable=True)
+    p50_first_byte_time_ms = Column(Integer, nullable=True)
+    p90_first_byte_time_ms = Column(Integer, nullable=True)
+    p99_first_byte_time_ms = Column(Integer, nullable=True)
     fallback_count = Column(Integer, default=0, nullable=False)  # Provider 切换次数
 
     # 使用维度统计
     unique_models = Column(Integer, default=0, server_default="0", nullable=False)
     unique_providers = Column(Integer, default=0, server_default="0", nullable=False)
 
+    # 完成标记
+    is_complete = Column(Boolean, default=False, nullable=False)
+    aggregated_at = Column(DateTime(timezone=True), nullable=True)
+
     # 时间戳
     created_at = Column(
         DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False
@@ -2084,6 +2236,82 @@ class StatsDailyProvider(Base):
     )
 
 
+class StatsDailyApiKey(Base):
+    """API Key 每日统计"""
+
+    __tablename__ = "stats_daily_api_key"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    api_key_id = Column(String(36), ForeignKey("api_keys.id", ondelete="CASCADE"), nullable=False)
+    date = Column(DateTime(timezone=True), nullable=False, index=True)
+
+    total_requests = Column(Integer, default=0, nullable=False)
+    success_requests = Column(Integer, default=0, nullable=False)
+    error_requests = Column(Integer, default=0, nullable=False)
+
+    input_tokens = Column(BigInteger, default=0, nullable=False)
+    output_tokens = Column(BigInteger, default=0, nullable=False)
+    cache_creation_tokens = Column(BigInteger, default=0, nullable=False)
+    cache_read_tokens = Column(BigInteger, default=0, nullable=False)
+
+    total_cost = Column(Float, default=0.0, nullable=False)
+
+    created_at = Column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint("api_key_id", "date", name="uq_stats_daily_api_key"),
+        Index("idx_stats_daily_api_key_date", "date"),
+        Index("idx_stats_daily_api_key_key_date", "api_key_id", "date"),
+        Index("idx_stats_daily_api_key_date_requests", "date", "total_requests"),
+        Index("idx_stats_daily_api_key_date_cost", "date", "total_cost"),
+    )
+
+    api_key = relationship("ApiKey")
+
+
+class StatsDailyError(Base):
+    """每日错误统计"""
+
+    __tablename__ = "stats_daily_error"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    date = Column(DateTime(timezone=True), nullable=False, index=True)
+    error_category = Column(String(50), nullable=False)
+    provider_name = Column(String(100), nullable=True)
+    model = Column(String(100), nullable=True)
+    count = Column(Integer, default=0, nullable=False)
+
+    created_at = Column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "date",
+            "error_category",
+            "provider_name",
+            "model",
+            name="uq_stats_daily_error",
+        ),
+        Index("idx_stats_daily_error_date", "date"),
+        Index("idx_stats_daily_error_category", "date", "error_category"),
+    )
+
+
 class StatsSummary(Base):
     """全局统计汇总 - 单行记录，存储截止到昨天的累计数据"""
 

src/services/system/maintenance_scheduler.py

@@ -123,14 +123,24 @@ class MaintenanceScheduler:
 
         scheduler = get_scheduler()
 
-        # 注册定时任务（使用业务时区）
-        # 统计聚合任务 - 凌晨 1 点执行
+        # 注册定时任务
+        # 统计聚合任务 - UTC 00:05 执行
         scheduler.add_cron_job(
             self._scheduled_stats_aggregation,
-            hour=1,
-            minute=0,
+            hour=0,
+            minute=5,
             job_id="stats_aggregation",
             name="统计数据聚合",
+            timezone="UTC",
+        )
+        # 小时统计聚合任务 - 每小时 05 分执行（UTC）
+        scheduler.add_cron_job(
+            self._scheduled_hourly_stats_aggregation,
+            hour="*",
+            minute=5,
+            job_id="stats_hourly_aggregation",
+            name="统计小时数据聚合",
+            timezone="UTC",
         )
         # 统计聚合补偿任务 - 每 30 分钟检查缺失并回填
         scheduler.add_interval_job(
@@ -231,6 +241,10 @@ class MaintenanceScheduler:
         """统计聚合任务（定时调用）"""
         await self._perform_stats_aggregation(backfill=backfill)
 
+    async def _scheduled_hourly_stats_aggregation(self) -> None:
+        """小时统计聚合任务（定时调用）"""
+        await self._perform_hourly_stats_aggregation()
+
     async def _scheduled_cleanup(self) -> None:
         """清理任务（定时调用）"""
         await self._perform_cleanup()
@@ -282,17 +296,12 @@ class MaintenanceScheduler:
 
                 logger.info("开始执行统计数据聚合...")
 
-                from zoneinfo import ZoneInfo
-
                 from src.models.database import StatsDaily
                 from src.models.database import User as DBUser
-                from src.services.system.scheduler import APP_TIMEZONE
 
-                # 使用业务时区计算日期，确保与定时任务触发时间一致
-                # 定时任务在 Asia/Shanghai 凌晨 1 点触发，此时应聚合 Asia/Shanghai 的"昨天"
-                app_tz = ZoneInfo(APP_TIMEZONE)
-                now_local = datetime.now(app_tz)
-                today_local = now_local.replace(hour=0, minute=0, second=0, microsecond=0)
+                # 使用 UTC 日期，定时任务在 UTC 00:05 触发，聚合 UTC 昨天
+                now_utc = datetime.now(timezone.utc)
+                today_utc = now_utc.replace(hour=0, minute=0, second=0, microsecond=0)
 
                 if backfill:
                     # 启动时检查并回填缺失的日期
@@ -314,14 +323,15 @@ class MaintenanceScheduler:
                     # 非首次运行，检查最近是否有缺失的日期需要回填
                     from src.models.database import StatsDailyModel, StatsDailyProvider
 
-                    yesterday_business_date = today_local.date() - timedelta(days=1)
+                    yesterday_utc_date = today_utc.date() - timedelta(days=1)
                     max_backfill_days: int = (
                         SystemConfigService.get_config(db, "max_stats_backfill_days", 30) or 30
                     )
 
                     # 计算回填检查的起始日期
-                    check_start_date = yesterday_business_date - timedelta(
-                        days=max_backfill_days - 1
+                    check_start_date = yesterday_utc_date - timedelta(days=max_backfill_days - 1)
+                    check_start_dt = datetime.combine(
+                        check_start_date, datetime.min.time(), tzinfo=timezone.utc
                     )
 
                     # 获取 StatsDaily 和 StatsDailyModel 中已有数据的日期集合
@@ -330,41 +340,39 @@ class MaintenanceScheduler:
                     existing_provider_dates = set()
 
                     daily_stats = (
-                        db.query(StatsDaily.date)
-                        .filter(StatsDaily.date >= check_start_date.isoformat())
-                        .all()
+                        db.query(StatsDaily.date).filter(StatsDaily.date >= check_start_dt).all()
                     )
                     for (stat_date,) in daily_stats:
                         if stat_date.tzinfo is None:
                             stat_date = stat_date.replace(tzinfo=timezone.utc)
-                        existing_daily_dates.add(stat_date.astimezone(app_tz).date())
+                        existing_daily_dates.add(stat_date.date())
 
                     model_stats = (
                         db.query(StatsDailyModel.date)
-                        .filter(StatsDailyModel.date >= check_start_date.isoformat())
+                        .filter(StatsDailyModel.date >= check_start_dt)
                         .distinct()
                         .all()
                     )
                     for (stat_date,) in model_stats:
                         if stat_date.tzinfo is None:
                             stat_date = stat_date.replace(tzinfo=timezone.utc)
-                        existing_model_dates.add(stat_date.astimezone(app_tz).date())
+                        existing_model_dates.add(stat_date.date())
 
                     provider_stats = (
                         db.query(StatsDailyProvider.date)
-                        .filter(StatsDailyProvider.date >= check_start_date.isoformat())
+                        .filter(StatsDailyProvider.date >= check_start_dt)
                         .distinct()
                         .all()
                     )
                     for (stat_date,) in provider_stats:
                         if stat_date.tzinfo is None:
                             stat_date = stat_date.replace(tzinfo=timezone.utc)
-                        existing_provider_dates.add(stat_date.astimezone(app_tz).date())
+                        existing_provider_dates.add(stat_date.date())
 
                     # 找出需要回填的日期
                     all_dates = set()
                     current = check_start_date
-                    while current <= yesterday_business_date:
+                    while current <= yesterday_utc_date:
                         all_dates.add(current)
                         current += timedelta(days=1)
 
@@ -389,43 +397,17 @@ class MaintenanceScheduler:
                         )
 
                         users = db.query(DBUser.id).filter(DBUser.is_active.is_(True)).all()
+                        user_ids = [user_id for (user_id,) in users]
 
                         failed_dates = 0
-                        failed_users = 0
-
                         for current_date in sorted_dates:
                             try:
-                                current_date_local = datetime.combine(
-                                    current_date, datetime.min.time(), tzinfo=app_tz
+                                current_date_utc = datetime.combine(
+                                    current_date, datetime.min.time(), tzinfo=timezone.utc
+                                )
+                                StatsAggregatorService.aggregate_daily_stats_bundle(
+                                    db, current_date_utc, user_ids=user_ids
                                 )
-                                # 只在缺失时才聚合对应的表
-                                if current_date in missing_daily_dates:
-                                    StatsAggregatorService.aggregate_daily_stats(
-                                        db, current_date_local
-                                    )
-                                if current_date in missing_model_dates:
-                                    StatsAggregatorService.aggregate_daily_model_stats(
-                                        db, current_date_local
-                                    )
-                                if current_date in missing_provider_dates:
-                                    StatsAggregatorService.aggregate_daily_provider_stats(
-                                        db, current_date_local
-                                    )
-                                # 用户统计在任一缺失时都回填
-                                for (user_id,) in users:
-                                    try:
-                                        StatsAggregatorService.aggregate_user_daily_stats(
-                                            db, user_id, current_date_local
-                                        )
-                                    except Exception as e:
-                                        failed_users += 1
-                                        logger.warning(
-                                            f"回填用户 {user_id} 日期 {current_date} 失败: {e}"
-                                        )
-                                        try:
-                                            db.rollback()
-                                        except Exception as rollback_err:
-                                            logger.error(f"回滚失败: {rollback_err}")
                             except Exception as e:
                                 failed_dates += 1
                                 logger.warning(f"回填日期 {current_date} 失败: {e}")
@@ -436,10 +418,10 @@ class MaintenanceScheduler:
 
                         StatsAggregatorService.update_summary(db)
 
-                        if failed_dates > 0 or failed_users > 0:
+                        if failed_dates > 0:
                             logger.warning(
                                 f"回填完成，共处理 {len(dates_to_process)} 天，"
-                                f"失败: {failed_dates} 天, {failed_users} 个用户记录"
+                                f"失败: {failed_dates} 天"
                             )
                         else:
                             logger.info(f"缺失数据回填完成，共处理 {len(dates_to_process)} 天")
@@ -447,25 +429,14 @@ class MaintenanceScheduler:
                         logger.info("统计数据已是最新，无需回填")
                     return
 
-                # 定时任务：聚合昨天的数据
-                yesterday_local = today_local - timedelta(days=1)
-
-                StatsAggregatorService.aggregate_daily_stats(db, yesterday_local)
-                StatsAggregatorService.aggregate_daily_model_stats(db, yesterday_local)
-                StatsAggregatorService.aggregate_daily_provider_stats(db, yesterday_local)
-
+                # 定时任务：聚合昨天 (UTC) 的数据
+                yesterday_utc = today_utc - timedelta(days=1)
                 users = db.query(DBUser.id).filter(DBUser.is_active.is_(True)).all()
-                for (user_id,) in users:
-                    try:
-                        StatsAggregatorService.aggregate_user_daily_stats(
-                            db, user_id, yesterday_local
-                        )
-                    except Exception as e:
-                        logger.warning(f"聚合用户 {user_id} 统计数据失败: {e}")
-                        try:
-                            db.rollback()
-                        except Exception:
-                            pass
+                user_ids = [user_id for (user_id,) in users]
+
+                StatsAggregatorService.aggregate_daily_stats_bundle(
+                    db, yesterday_utc, user_ids=user_ids
+                )
 
                 StatsAggregatorService.update_summary(db)
 
@@ -480,6 +451,27 @@ class MaintenanceScheduler:
             finally:
                 db.close()
 
+    async def _perform_hourly_stats_aggregation(self) -> None:
+        """执行小时统计聚合任务"""
+        db = create_session()
+        try:
+            if not SystemConfigService.get_config(db, "enable_stats_aggregation", True):
+                logger.info("统计聚合已禁用，跳过小时聚合任务")
+                return
+
+            now_utc = datetime.now(timezone.utc)
+            last_hour = now_utc.replace(minute=0, second=0, microsecond=0) - timedelta(hours=1)
+            StatsAggregatorService.aggregate_hourly_stats_bundle(db, last_hour)
+            logger.info(f"小时统计聚合完成: {last_hour.isoformat()}")
+        except Exception as e:
+            logger.exception(f"小时统计聚合任务执行失败: {e}")
+            try:
+                db.rollback()
+            except Exception:
+                pass
+        finally:
+            db.close()
+
     async def _perform_pending_cleanup(self) -> None:
         """执行 pending 状态清理"""
         db = create_session()

src/services/system/scheduler.py

@@ -41,10 +41,11 @@ class TaskScheduler:
     def add_cron_job(
         self,
         func: Callable[..., Any],
-        hour: int,
+        hour: int | str,
         minute: int = 0,
         job_id: str | None = None,
         name: str | None = None,
+        timezone: str | None = None,
         **kwargs: Any,
     ) -> Any:
         """
@@ -58,7 +59,8 @@ class TaskScheduler:
             name: 任务名称（用于日志）
             **kwargs: 传递给任务函数的参数
         """
-        trigger = CronTrigger(hour=hour, minute=minute, timezone=APP_TIMEZONE)
+        trigger_timezone = timezone or APP_TIMEZONE
+        trigger = CronTrigger(hour=hour, minute=minute, timezone=trigger_timezone)
 
         job_id = job_id or func.__name__
         display_name = name or job_id
@@ -74,7 +76,7 @@ class TaskScheduler:
 
         logger.info(
             f"已注册定时任务: {display_name}, "
-            f"执行时间: {hour:02d}:{minute:02d} ({APP_TIMEZONE})"
+            f"执行时间: {hour}:{minute:02d} ({trigger_timezone})"
         )
 
     def add_interval_job(

src/services/system/time_range.py

@@ -0,0 +1,241 @@
+"""Time range utilities for stats queries."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta, timezone
+from typing import Literal
+
+from pydantic import BaseModel, model_validator
+
+
+class TimeRangeParams(BaseModel):
+    """
+    Time range parameters (local-date semantics).
+
+    Rules:
+    1) Inputs are user-local dates, backend converts to UTC datetime range.
+    2) Range is half-open: [start, end).
+    """
+
+    start_date: date | None = None
+    end_date: date | None = None
+
+    preset: (
+        Literal[
+            "today",
+            "yesterday",
+            "last7days",
+            "last30days",
+            "last90days",
+            "this_week",
+            "last_week",
+            "this_month",
+            "last_month",
+            "this_year",
+        ]
+        | None
+    ) = None
+
+    granularity: Literal["hour", "day", "week", "month"] = "day"
+
+    timezone: str | None = None
+    tz_offset_minutes: int = 0
+
+    @model_validator(mode="after")
+    def validate_and_resolve(self) -> "TimeRangeParams":
+        """Validate and resolve preset to concrete dates."""
+        if self.preset:
+            user_today = self._get_user_today()
+            match self.preset:
+                case "today":
+                    self.start_date = self.end_date = user_today
+                case "yesterday":
+                    self.start_date = self.end_date = user_today - timedelta(days=1)
+                case "last7days":
+                    self.start_date = user_today - timedelta(days=6)
+                    self.end_date = user_today
+                case "last30days":
+                    self.start_date = user_today - timedelta(days=29)
+                    self.end_date = user_today
+                case "last90days":
+                    self.start_date = user_today - timedelta(days=89)
+                    self.end_date = user_today
+                case "this_week":
+                    self.start_date = user_today - timedelta(days=user_today.weekday())
+                    self.end_date = user_today
+                case "last_week":
+                    week_start = user_today - timedelta(days=user_today.weekday())
+                    self.start_date = week_start - timedelta(days=7)
+                    self.end_date = week_start - timedelta(days=1)
+                case "this_month":
+                    self.start_date = user_today.replace(day=1)
+                    self.end_date = user_today
+                case "last_month":
+                    first_of_this_month = user_today.replace(day=1)
+                    self.end_date = first_of_this_month - timedelta(days=1)
+                    self.start_date = self.end_date.replace(day=1)
+                case "this_year":
+                    self.start_date = user_today.replace(month=1, day=1)
+                    self.end_date = user_today
+
+        if not self.preset and (self.start_date is None or self.end_date is None):
+            raise ValueError("Either preset or both start_date and end_date must be provided")
+
+        if self.start_date and self.end_date and self.start_date > self.end_date:
+            raise ValueError("start_date must be <= end_date")
+
+        if self.start_date and self.end_date:
+            max_days = 365
+            days = (self.end_date - self.start_date).days
+            if days > max_days:
+                raise ValueError(f"Query range cannot exceed {max_days} days")
+
+        if self.granularity == "hour":
+            if self.start_date != self.end_date:
+                raise ValueError("Hour granularity only supports single day query")
+
+        return self
+
+    def validate_for_time_series(self) -> "TimeRangeParams":
+        """Extra validation for time series queries."""
+        if self.granularity == "hour" and self.start_date != self.end_date:
+            raise ValueError("Hour granularity only supports single day query")
+        if self.start_date and self.end_date:
+            days_inclusive = (self.end_date - self.start_date).days + 1
+            max_days_for_time_series = 90
+            if days_inclusive > max_days_for_time_series:
+                raise ValueError(
+                    f"Time series query range cannot exceed {max_days_for_time_series} days "
+                    f"(requested {days_inclusive} days). "
+                    "For longer ranges, use aggregated statistics instead."
+                )
+        return self
+
+    def _get_user_today(self) -> date:
+        """Get user-local 'today'."""
+        if self.timezone:
+            try:
+                from zoneinfo import ZoneInfo
+
+                user_tz = ZoneInfo(self.timezone)
+                return datetime.now(user_tz).date()
+            except Exception:
+                pass
+
+        user_now = datetime.now(timezone.utc) + timedelta(minutes=self.tz_offset_minutes)
+        return user_now.date()
+
+    def _get_tz_offset_for_date(self, local_date: date) -> timedelta:
+        """Get timezone offset for a local date (DST-aware if timezone is provided)."""
+        if self.timezone:
+            try:
+                from zoneinfo import ZoneInfo
+
+                user_tz = ZoneInfo(self.timezone)
+                local_midnight = datetime.combine(local_date, time.min)
+                local_aware = local_midnight.replace(tzinfo=user_tz)
+                return local_aware.utcoffset() or timedelta(0)
+            except Exception:
+                pass
+        return timedelta(minutes=self.tz_offset_minutes)
+
+    def to_utc_datetime_range(self) -> tuple[datetime, datetime]:
+        """Convert to UTC datetime range (half-open)."""
+        start_offset = self._get_tz_offset_for_date(self.start_date)
+        end_offset = self._get_tz_offset_for_date(self.end_date + timedelta(days=1))
+
+        local_start = datetime.combine(self.start_date, time.min)
+        local_end = datetime.combine(self.end_date + timedelta(days=1), time.min)
+
+        start_utc = (local_start - start_offset).replace(tzinfo=timezone.utc)
+        end_utc = (local_end - end_offset).replace(tzinfo=timezone.utc)
+        return start_utc, end_utc
+
+    def get_complete_utc_dates(
+        self,
+    ) -> tuple[list[date], tuple[datetime, datetime] | None, tuple[datetime, datetime] | None]:
+        """Split into complete UTC days + head/tail boundaries."""
+        start_utc, end_utc = self.to_utc_datetime_range()
+
+        if (
+            start_utc.hour == 0
+            and start_utc.minute == 0
+            and start_utc.second == 0
+            and start_utc.microsecond == 0
+        ):
+            first_complete_date = start_utc.date()
+            head_boundary = None
+        else:
+            first_complete_date = start_utc.date() + timedelta(days=1)
+            head_boundary = (
+                start_utc,
+                datetime.combine(first_complete_date, time.min, tzinfo=timezone.utc),
+            )
+
+        if (
+            end_utc.hour == 0
+            and end_utc.minute == 0
+            and end_utc.second == 0
+            and end_utc.microsecond == 0
+        ):
+            last_complete_date = end_utc.date() - timedelta(days=1)
+            tail_boundary = None
+        else:
+            last_complete_date = end_utc.date() - timedelta(days=1)
+            tail_start = datetime.combine(end_utc.date(), time.min, tzinfo=timezone.utc)
+            tail_boundary = (tail_start, end_utc)
+
+        complete_dates = []
+        if first_complete_date <= last_complete_date:
+            current = first_complete_date
+            while current <= last_complete_date:
+                complete_dates.append(current)
+                current += timedelta(days=1)
+
+        return complete_dates, head_boundary, tail_boundary
+
+    def get_local_day_hours(self) -> list[tuple[date, datetime, datetime]]:
+        """Return local-day mapped UTC ranges for time-series."""
+        result = []
+        current_date = self.start_date
+        while current_date <= self.end_date:
+            offset = self._get_tz_offset_for_date(current_date)
+            local_start = datetime.combine(current_date, time.min)
+            local_end = datetime.combine(current_date + timedelta(days=1), time.min)
+            day_start_utc = (local_start - offset).replace(tzinfo=timezone.utc)
+            day_end_utc = (
+                local_end - self._get_tz_offset_for_date(current_date + timedelta(days=1))
+            ).replace(tzinfo=timezone.utc)
+            result.append((current_date, day_start_utc, day_end_utc))
+            current_date += timedelta(days=1)
+        return result
+
+
+def split_time_range_for_hourly(start_utc: datetime, end_utc: datetime) -> tuple[
+    tuple[datetime, datetime] | None,
+    list[datetime],
+    tuple[datetime, datetime] | None,
+]:
+    """Split into head fragment, complete hours, tail fragment."""
+    first_hour = start_utc.replace(minute=0, second=0, microsecond=0)
+    if start_utc > first_hour:
+        first_hour += timedelta(hours=1)
+        head_fragment = (start_utc, first_hour) if first_hour <= end_utc else None
+    else:
+        head_fragment = None
+        first_hour = start_utc
+
+    last_hour = end_utc.replace(minute=0, second=0, microsecond=0)
+    if end_utc > last_hour:
+        tail_fragment = (last_hour, end_utc) if last_hour >= first_hour else None
+    else:
+        tail_fragment = None
+        last_hour = end_utc
+
+    complete_hours = []
+    current = first_hour
+    while current < last_hour:
+        complete_hours.append(current)
+        current += timedelta(hours=1)
+
+    return head_fragment, complete_hours, tail_fragment

src/services/usage/error_classifier.py

@@ -0,0 +1,70 @@
+"""Error classification helpers for Usage records."""
+
+from __future__ import annotations
+
+from src.core.enums import ErrorCategory
+
+_STATUS_CODE_MAP: dict[int, ErrorCategory] = {
+    400: ErrorCategory.INVALID_REQUEST,
+    401: ErrorCategory.AUTH,
+    403: ErrorCategory.AUTH,
+    404: ErrorCategory.NOT_FOUND,
+    408: ErrorCategory.TIMEOUT,
+    429: ErrorCategory.RATE_LIMIT,
+    500: ErrorCategory.SERVER_ERROR,
+    502: ErrorCategory.SERVER_ERROR,
+    503: ErrorCategory.SERVER_ERROR,
+    504: ErrorCategory.TIMEOUT,
+}
+
+_CONTEXT_LENGTH_PATTERNS = (
+    "context_length_exceeded",
+    "maximum context length",
+    "too many tokens",
+    "input is too long",
+)
+
+_CONTENT_FILTER_PATTERNS = (
+    "content_filter",
+    "content_policy",
+    "safety_block",
+    "blocked by content",
+)
+
+_NETWORK_PATTERNS = ("connection", "network", "dns", "socket")
+
+
+def classify_error(
+    status_code: int | None,
+    error_message: str | None,
+    status: str | None = None,
+) -> ErrorCategory:
+    """Map provider errors to ErrorCategory."""
+    if status and status.lower() == "cancelled":
+        return ErrorCategory.CANCELLED
+
+    if status_code is not None:
+        mapped = _STATUS_CODE_MAP.get(status_code)
+        if mapped:
+            return mapped
+
+    if error_message:
+        msg_lower = error_message.lower()
+        if any(p in msg_lower for p in _CONTEXT_LENGTH_PATTERNS):
+            return ErrorCategory.CONTEXT_LENGTH
+        if any(p in msg_lower for p in _CONTENT_FILTER_PATTERNS):
+            return ErrorCategory.CONTENT_FILTER
+        if "rate limit" in msg_lower or "rate_limit" in msg_lower:
+            return ErrorCategory.RATE_LIMIT
+        if "timeout" in msg_lower or "timed out" in msg_lower:
+            return ErrorCategory.TIMEOUT
+        if any(p in msg_lower for p in _NETWORK_PATTERNS):
+            return ErrorCategory.NETWORK
+
+    if status_code is not None:
+        if status_code >= 500:
+            return ErrorCategory.SERVER_ERROR
+        if status_code >= 400:
+            return ErrorCategory.INVALID_REQUEST
+
+    return ErrorCategory.UNKNOWN

src/services/usage/service.py

@@ -27,6 +27,7 @@ from src.models.database import (
 )
 from src.services.model.cost import ModelCostService
 from src.services.system.config import SystemConfigService
+from src.services.usage.error_classifier import classify_error
 
 
 @dataclass
@@ -335,6 +336,10 @@ class UsageService:
             actual_request_cost = request_cost * actual_rate_multiplier
             actual_total_cost = total_cost * actual_rate_multiplier
 
+        error_category = None
+        if status_code >= 400 or error_message or status in {"failed", "cancelled"}:
+            error_category = classify_error(status_code, error_message, status).value
+
         return {
             "user_id": user.id if user else None,
             "api_key_id": api_key.id if api_key else None,
@@ -376,6 +381,7 @@ class UsageService:
             "is_stream": is_stream,
             "status_code": status_code,
             "error_message": error_message,
+            "error_category": error_category,
             "response_time_ms": response_time_ms,
             "first_byte_time_ms": first_byte_time_ms,
             "status": status,
@@ -586,6 +592,7 @@ class UsageService:
         existing_usage.status = usage_params["status"]
         existing_usage.status_code = usage_params["status_code"]
         existing_usage.error_message = usage_params["error_message"]
+        existing_usage.error_category = usage_params.get("error_category")
         existing_usage.response_time_ms = usage_params["response_time_ms"]
         existing_usage.first_byte_time_ms = usage_params["first_byte_time_ms"]
 
@@ -2068,7 +2075,7 @@ class UsageService:
         if start_date:
             query = query.filter(Usage.created_at >= start_date)
         if end_date:
-            query = query.filter(Usage.created_at <= end_date)
+            query = query.filter(Usage.created_at < end_date)
 
         # 使用跨数据库兼容的日期函数
         from src.utils.database_helpers import date_trunc_portable
@@ -2108,7 +2115,7 @@ class UsageService:
         if start_date:
             summary = summary.filter(Usage.created_at >= start_date)
         if end_date:
-            summary = summary.filter(Usage.created_at <= end_date)
+            summary = summary.filter(Usage.created_at < end_date)
 
         summary = summary.group_by(date_func, Usage.provider_name, Usage.model).all()