Aether/_deprecated_py_src/api/admin/usage/routes.py

"""管理员使用情况统计路由。"""

from __future__ import annotations

from collections import defaultdict
from dataclasses import dataclass
from datetime import date, datetime, timedelta, timezone
from typing import Any

from fastapi import APIRouter, Depends, HTTPException, Query, Request
from sqlalchemy import case, func
from sqlalchemy.orm import Session, defer

from src.api.base.admin_adapter import AdminApiAdapter
from src.api.base.context import ApiRequestContext
from src.api.base.pipeline import get_pipeline
from src.config.constants import CacheTTL
from src.config.settings import config
from src.core.logger import logger
from src.database import get_db
from src.models.database import (
    ApiKey,
    Provider,
    ProviderAPIKey,
    ProviderEndpoint,
    RequestCandidate,
    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.query import input_context_expr
from src.services.usage.service import UsageService
from src.utils.cache_decorator import cache_result

router = APIRouter(prefix="/api/admin/usage", tags=["Admin - Usage"])
pipeline = get_pipeline()


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 _calculate_token_cache_hit_rate(
    total_input_context: int | None,
    cache_read_tokens: int | None,
) -> float:
    """计算缓存命中率。

    Args:
        total_input_context: 已归一化的总输入上下文 token 数。
            由 query.py 的 input_context_expr() 统一计算，固定为
            input_tokens + cache_read_input_tokens。
        cache_read_tokens: 缓存读取 token 数
    """
    context = int(total_input_context or 0)
    cached = int(cache_read_tokens or 0)
    if context <= 0:
        return 0.0
    return round(cached / context * 100, 2)


# ==================== RESTful Routes ====================


@router.get("/aggregation/stats")
async def get_usage_aggregation(
    request: Request,
    group_by: str = Query(
        ..., description="Aggregation dimension: model, user, provider, or api_format"
    ),
    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:
    """
    获取使用情况聚合统计

    按指定维度聚合使用情况统计数据。

    **查询参数**:
    - `group_by`: 必需，聚合维度，可选值：model（按模型）、user（按用户）、provider（按提供商）、api_format（按 API 格式）
    - `start_date`: 可选，开始日期（ISO 格式）
    - `end_date`: 可选，结束日期（ISO 格式）
    - `limit`: 返回数量限制，默认 20，最大 100

    **返回字段**:
    - 按模型聚合时：model, request_count, total_tokens, total_cost, actual_cost, cache_read_tokens, cache_hit_rate
    - 按用户聚合时：user_id, email, username, request_count, total_tokens, total_cost
    - 按提供商聚合时：provider_id, provider, request_count, total_tokens, total_cost, actual_cost, avg_response_time_ms, success_rate, error_count, cache_read_tokens, cache_hit_rate
    - 按 API 格式聚合时：api_format, request_count, total_tokens, total_cost, actual_cost, avg_response_time_ms, cache_read_tokens, cache_hit_rate
    """
    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(time_range=time_range, limit=limit)
    elif group_by == "user":
        adapter = AdminUsageByUserAdapter(time_range=time_range, limit=limit)
    elif group_by == "provider":
        adapter = AdminUsageByProviderAdapter(time_range=time_range, limit=limit)
    elif group_by == "api_format":
        adapter = AdminUsageByApiFormatAdapter(time_range=time_range, limit=limit)
    else:
        raise HTTPException(
            status_code=400,
            detail=f"Invalid group_by value: {group_by}. Must be one of: model, user, provider, api_format",
        )
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.get("/stats")
async def get_usage_stats(
    request: Request,
    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:
    """
    获取使用情况总体统计

    获取指定时间范围内的使用情况总体统计数据。

    **查询参数**:
    - `start_date`: 可选，开始日期（ISO 格式）
    - `end_date`: 可选，结束日期（ISO 格式）

    **返回字段**:
    - `total_requests`: 总请求数
    - `total_tokens`: 总 token 数
    - `total_cost`: 总成本（美元）
    - `total_actual_cost`: 实际总成本（美元）
    - `avg_response_time`: 平均响应时间（秒）
    - `error_count`: 错误请求数
    - `error_rate`: 错误率（百分比）
    - `cache_stats`: 缓存统计信息（cache_creation_tokens, cache_read_tokens, cache_creation_cost, cache_read_cost）
    """
    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)


@router.get("/heatmap")
async def get_activity_heatmap(
    request: Request,
    db: Session = Depends(get_db),
) -> Any:
    """
    获取活动热力图数据

    获取过去 365 天的活动热力图数据。此接口缓存 5 分钟以减少数据库负载。

    **返回字段**:
    - 按日期聚合的请求数、token 数、成本等统计数据
    """
    adapter = AdminActivityHeatmapAdapter()
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.get("/records")
async def get_usage_records(
    request: Request,
    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),
    db: Session = Depends(get_db),
) -> Any:
    """
    获取使用记录列表

    获取详细的使用记录列表，支持多种筛选条件。

    **查询参数**:
    - `start_date`: 可选，开始日期（ISO 格式）
    - `end_date`: 可选，结束日期（ISO 格式）
    - `search`: 可选，通用搜索关键词（支持用户名、密钥名、模型名、提供商名模糊搜索，多个关键词用空格分隔）
    - `user_id`: 可选，用户 ID 筛选
    - `username`: 可选，用户名模糊搜索
    - `model`: 可选，模型名模糊搜索
    - `provider`: 可选，提供商名称搜索
    - `api_format`: 可选，API 格式筛选（如 openai:chat, claude:chat）
    - `status`: 可选，状态筛选（stream: 流式请求，standard: 标准请求，error: 错误请求，pending: 等待中，streaming: 流式中，completed: 已完成，failed: 失败，active: 活跃请求）
    - `limit`: 返回数量限制，默认 100，最大 500
    - `offset`: 分页偏移量，默认 0

    **返回字段**:
    - `records`: 使用记录列表，包含 id, user_id, user_email, username, api_key, provider, model, target_model,
      model_version, input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens,
      total_tokens, cost, actual_cost, rate_multiplier, response_time_ms, first_byte_time_ms, created_at,
      is_stream, input_price_per_1m, output_price_per_1m, cache_creation_price_per_1m,
      cache_read_price_per_1m, status_code, error_message, status, has_fallback, has_retry,
      has_rectified, api_format, api_key_name
    - `total`: 符合条件的总记录数
    - `limit`: 当前分页限制
    - `offset`: 当前分页偏移量
    """
    time_range = _apply_admin_default_range(
        _build_time_range_params(start_date, end_date, preset, timezone_name, tz_offset_minutes)
    )
    adapter = AdminUsageRecordsAdapter(
        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,
    )
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.get("/active")
async def get_active_requests(
    request: Request,
    ids: str | None = Query(None, description="逗号分隔的请求 ID 列表，用于查询特定请求的状态"),
    db: Session = Depends(get_db),
) -> Any:
    """
    获取活跃请求的状态

    获取当前活跃（pending/streaming 状态）请求的状态信息。这是一个轻量级接口，适合前端轮询。

    **查询参数**:
    - `ids`: 可选，逗号分隔的请求 ID 列表，用于查询特定请求的状态

    **行为说明**:
    - 如果提供 ids 参数，只返回这些 ID 对应请求的最新状态
    - 如果不提供 ids，返回所有 pending/streaming 状态的请求

    **返回字段**:
    - `requests`: 活跃请求列表，包含请求状态信息
    """
    adapter = AdminActiveRequestsAdapter(ids=ids)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.get("/{usage_id}/curl")
async def get_usage_curl_data(
    usage_id: str,
    request: Request,
    db: Session = Depends(get_db),
) -> Any:
    """
    获取使用记录的 cURL 命令数据

    返回重建 cURL 命令所需的 URL、请求头（含明文 API Key）和请求体。

    **路径参数**:
    - `usage_id`: 使用记录 ID

    **返回字段**:
    - `url`: 提供商请求 URL
    - `method`: HTTP 方法
    - `headers`: 提供商请求头（含明文 API Key）
    - `body`: 请求体
    - `curl`: 生成的 cURL 命令字符串
    """
    adapter = AdminUsageCurlAdapter(usage_id=usage_id)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.post("/{usage_id}/replay")
async def replay_usage_request(
    usage_id: str,
    request: Request,
    db: Session = Depends(get_db),
) -> Any:
    """
    回放使用记录请求

    将原始请求重新发送到原始或指定的提供商，并返回响应结果。

    **路径参数**:
    - `usage_id`: 使用记录 ID

    **请求体**:
    - `provider_id`: 可选，目标提供商 ID（不指定则使用原始提供商）
    - `endpoint_id`: 可选，目标端点 ID（不指定则使用原始端点）
    - `body_override`: 可选，覆盖原始请求体

    **返回字段**:
    - `url`: 请求 URL
    - `status_code`: HTTP 状态码
    - `response_headers`: 响应头
    - `response_body`: 响应体
    - `response_time_ms`: 响应时间（毫秒）
    """
    # 从 JSON body 中解析参数
    try:
        json_body = await request.json()
    except Exception:
        json_body = {}

    adapter = AdminUsageReplayAdapter(
        usage_id=usage_id,
        target_provider_id=json_body.get("provider_id"),
        target_endpoint_id=json_body.get("endpoint_id"),
        target_api_key_id=json_body.get("api_key_id"),
        body_override=json_body.get("body_override"),
    )
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


# NOTE: This route must be defined AFTER all other routes to avoid matching
# routes like /stats, /records, /active, /curl, /replay, etc.
@router.get("/{usage_id}")
async def get_usage_detail(
    usage_id: str,
    request: Request,
    include_bodies: bool = Query(True, description="是否返回请求/响应 body 内容"),
    db: Session = Depends(get_db),
) -> Any:
    """
    获取使用记录详情

    获取指定使用记录的详细信息，包括请求/响应的头部和正文。

    **路径参数**:
    - `usage_id`: 使用记录 ID

    **返回字段**:
    - `id`: 记录 ID
    - `request_id`: 请求 ID
    - `user`: 用户信息（id, username, email）
    - `api_key`: API Key 信息（id, name, display）
    - `provider`: 提供商名称
    - `api_format`: API 格式
    - `model`: 请求的模型名称
    - `target_model`: 映射后的目标模型名称
    - `tokens`: Token 统计（input, output, total）
    - `cost`: 成本统计（input, output, total）
    - `cache_creation_input_tokens`: 缓存创建输入 token 数
    - `cache_read_input_tokens`: 缓存读取输入 token 数
    - `cache_creation_cost`: 缓存创建成本
    - `cache_read_cost`: 缓存读取成本
    - `request_cost`: 请求成本
    - `input_price_per_1m`: 输入价格（每百万 token）
    - `output_price_per_1m`: 输出价格（每百万 token）
    - `cache_creation_price_per_1m`: 缓存创建价格（每百万 token）
    - `cache_read_price_per_1m`: 缓存读取价格（每百万 token）
    - `price_per_request`: 每请求价格
    - `request_type`: 请求类型
    - `is_stream`: 是否为流式请求
    - `status_code`: HTTP 状态码
    - `error_message`: 错误信息
    - `response_time_ms`: 响应时间（毫秒）
    - `first_byte_time_ms`: 首字节时间（TTFB，毫秒）
    - `created_at`: 创建时间
    - `request_headers`: 请求头
    - `request_body`: 请求体
    - `provider_request_headers`: 提供商请求头
    - `response_headers`: 提供商响应头
    - `client_response_headers`: 返回给客户端的响应头
    - `response_body`: 响应体
    - `metadata`: 提供商响应元数据
    - `tiered_pricing`: 阶梯计费信息（如适用）
    """
    adapter = AdminUsageDetailAdapter(usage_id=usage_id, include_bodies=include_bodies)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


class AdminUsageStatsAdapter(AdminApiAdapter):
    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", "preset", "timezone", "tz_offset_minutes"],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db
        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 = 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.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),
                "cache_read_tokens": int(stats.cache_read_tokens),
                "cache_creation_cost": float(stats.cache_creation_cost),
                "cache_read_cost": float(stats.cache_read_cost),
            },
        }


class AdminActivityHeatmapAdapter(AdminApiAdapter):
    """Activity heatmap adapter with Redis caching."""

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        result = await UsageService.get_cached_heatmap(
            db=context.db,
            user_id=None,
            include_actual_cost=True,
        )
        context.add_audit_metadata(action="activity_heatmap")
        return result


class AdminUsageByModelAdapter(AdminApiAdapter):
    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", "preset", "timezone", "tz_offset_minutes", "limit"],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db
        query = db.query(
            Usage.model,
            func.count(Usage.id).label("request_count"),
            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("actual_cost"),
            func.sum(Usage.cache_read_input_tokens).label("cache_read_tokens"),
            func.sum(input_context_expr()).label("total_input_context"),
            func.sum(Usage.output_tokens).label("output_tokens"),
            func.sum(Usage.cache_creation_input_tokens).label("cache_creation_tokens"),
        )
        # 过滤掉 pending/streaming 状态的请求（尚未完成的请求不应计入统计）
        query = query.filter(Usage.status.notin_(["pending", "streaming"]))
        # 过滤掉 unknown/pending provider_name（请求未到达任何提供商）
        query = query.filter(Usage.provider_name.notin_(["unknown", "pending"]))

        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()
        context.add_audit_metadata(
            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),
        )

        return [
            {
                "model": model,
                "request_count": count,
                "total_tokens": int(tokens or 0),
                "total_input_context": int(total_input_context or 0),
                "output_tokens": int(output_tokens or 0),
                "total_cost": float(cost or 0),
                "actual_cost": float(actual_cost or 0),
                "cache_read_tokens": int(cache_read_tokens or 0),
                "cache_creation_tokens": int(cache_creation_tokens or 0),
                "cache_hit_rate": _calculate_token_cache_hit_rate(
                    total_input_context=total_input_context,
                    cache_read_tokens=cache_read_tokens,
                ),
            }
            for (
                model,
                count,
                tokens,
                cost,
                actual_cost,
                cache_read_tokens,
                total_input_context,
                output_tokens,
                cache_creation_tokens,
            ) in stats
        ]


class AdminUsageByUserAdapter(AdminApiAdapter):
    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", "preset", "timezone", "tz_offset_minutes", "limit"],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db
        query = (
            db.query(
                User.id,
                User.email,
                User.username,
                func.count(Usage.id).label("request_count"),
                func.sum(Usage.total_tokens).label("total_tokens"),
                func.sum(Usage.total_cost_usd).label("total_cost"),
            )
            .join(Usage, Usage.user_id == User.id)
            .group_by(User.id, User.email, User.username)
        )

        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()

        context.add_audit_metadata(
            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),
        )

        return [
            {
                "user_id": user_id,
                "email": email,
                "username": username,
                "request_count": count,
                "total_tokens": int(tokens or 0),
                "total_cost": float(cost or 0),
            }
            for user_id, email, username, count, tokens, cost in stats
        ]


class AdminUsageByProviderAdapter(AdminApiAdapter):
    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", "preset", "timezone", "tz_offset_minutes", "limit"],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db

        # 从 request_candidates 表统计每个 Provider 的尝试次数和成功率
        # 这样可以正确统计 Fallback 场景（一个请求可能尝试多个 Provider）
        from sqlalchemy import case

        attempt_query = db.query(
            RequestCandidate.provider_id,
            func.count(RequestCandidate.id).label("attempt_count"),
            func.sum(case((RequestCandidate.status == "success", 1), else_=0)).label(
                "success_count"
            ),
            func.sum(case((RequestCandidate.status == "failed", 1), else_=0)).label("failed_count"),
            func.avg(RequestCandidate.latency_ms).label("avg_latency_ms"),
        ).filter(
            RequestCandidate.provider_id.isnot(None),
            # 只统计实际执行的尝试（排除 available/skipped 状态）
            RequestCandidate.status.in_(["success", "failed"]),
        )

        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)
            .order_by(func.count(RequestCandidate.id).desc())
            .limit(self.limit)
            .all()
        )

        # 从 Usage 表获取 token 和费用统计（基于成功的请求）
        usage_query = db.query(
            Usage.provider_id,
            func.count(Usage.id).label("request_count"),
            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("actual_cost"),
            func.avg(Usage.response_time_ms).label("avg_response_time_ms"),
            func.sum(Usage.cache_read_input_tokens).label("cache_read_tokens"),
            func.sum(input_context_expr()).label("total_input_context"),
            func.sum(Usage.output_tokens).label("output_tokens"),
            func.sum(Usage.cache_creation_input_tokens).label("cache_creation_tokens"),
        ).filter(
            Usage.provider_id.isnot(None),
            # 过滤掉 pending/streaming 状态的请求
            Usage.status.notin_(["pending", "streaming"]),
        )

        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}

        # 获取所有相关的 Provider ID
        provider_ids = set()
        for stat in attempt_stats:
            if stat.provider_id:
                provider_ids.add(stat.provider_id)
        for stat in usage_stats:
            if stat.provider_id:
                provider_ids.add(stat.provider_id)

        # 获取 Provider 名称映射
        provider_map = {}
        if provider_ids:
            providers_data = (
                db.query(Provider.id, Provider.name).filter(Provider.id.in_(provider_ids)).all()
            )
            provider_map = {str(p.id): p.name for p in providers_data}

        context.add_audit_metadata(
            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),
        )

        result = []
        for stat in attempt_stats:
            provider_id_str = str(stat.provider_id) if stat.provider_id else None
            attempt_count = stat.attempt_count or 0
            success_count = int(stat.success_count or 0)
            failed_count = int(stat.failed_count or 0)
            success_rate = (success_count / attempt_count * 100) if attempt_count > 0 else 0

            # 从 usage_map 获取 token 和费用信息
            usage_stat = usage_map.get(provider_id_str)

            result.append(
                {
                    "provider_id": provider_id_str,
                    "provider": provider_map.get(provider_id_str, "Unknown"),
                    "request_count": attempt_count,  # 尝试次数
                    "total_tokens": int(usage_stat.total_tokens or 0) if usage_stat else 0,
                    "total_input_context": (
                        int(usage_stat.total_input_context or 0) if usage_stat else 0
                    ),
                    "output_tokens": int(usage_stat.output_tokens or 0) if usage_stat else 0,
                    "total_cost": float(usage_stat.total_cost or 0) if usage_stat else 0,
                    "actual_cost": float(usage_stat.actual_cost or 0) if usage_stat else 0,
                    "avg_response_time_ms": float(stat.avg_latency_ms or 0),
                    "success_rate": round(success_rate, 2),
                    "error_count": failed_count,
                    "cache_read_tokens": (
                        int(usage_stat.cache_read_tokens or 0) if usage_stat else 0
                    ),
                    "cache_creation_tokens": (
                        int(usage_stat.cache_creation_tokens or 0) if usage_stat else 0
                    ),
                    "cache_hit_rate": _calculate_token_cache_hit_rate(
                        total_input_context=(usage_stat.total_input_context if usage_stat else 0),
                        cache_read_tokens=(usage_stat.cache_read_tokens if usage_stat else 0),
                    ),
                }
            )

        return result


class AdminUsageByApiFormatAdapter(AdminApiAdapter):
    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", "preset", "timezone", "tz_offset_minutes", "limit"],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db
        query = db.query(
            Usage.api_format,
            func.count(Usage.id).label("request_count"),
            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("actual_cost"),
            func.avg(Usage.response_time_ms).label("avg_response_time_ms"),
            func.sum(Usage.cache_read_input_tokens).label("cache_read_tokens"),
            func.sum(input_context_expr()).label("total_input_context"),
            func.sum(Usage.output_tokens).label("output_tokens"),
            func.sum(Usage.cache_creation_input_tokens).label("cache_creation_tokens"),
        )
        # 过滤掉 pending/streaming 状态的请求
        query = query.filter(Usage.status.notin_(["pending", "streaming"]))
        # 过滤掉 unknown/pending provider_name
        query = query.filter(Usage.provider_name.notin_(["unknown", "pending"]))
        # 只统计有 api_format 的记录
        query = query.filter(Usage.api_format.isnot(None))

        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)
        )
        stats = query.all()

        context.add_audit_metadata(
            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),
        )

        return [
            {
                "api_format": api_format or "unknown",
                "request_count": count,
                "total_tokens": int(tokens or 0),
                "total_input_context": int(total_input_context or 0),
                "output_tokens": int(output_tokens or 0),
                "total_cost": float(cost or 0),
                "actual_cost": float(actual_cost or 0),
                "avg_response_time_ms": float(avg_response_time or 0),
                "cache_read_tokens": int(cache_read_tokens or 0),
                "cache_creation_tokens": int(cache_creation_tokens or 0),
                "cache_hit_rate": _calculate_token_cache_hit_rate(
                    total_input_context=total_input_context,
                    cache_read_tokens=cache_read_tokens,
                ),
            }
            for (
                api_format,
                count,
                tokens,
                cost,
                actual_cost,
                avg_response_time,
                cache_read_tokens,
                total_input_context,
                output_tokens,
                cache_creation_tokens,
            ) in stats
        ]


class AdminUsageRecordsAdapter(AdminApiAdapter):
    def __init__(
        self,
        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.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

    @cache_result(
        key_prefix="admin:usage:records",
        ttl=3,  # 使用记录页强调实时性，避免 15s 缓存导致列表滞后
        user_specific=False,
        vary_by=[
            "start_date",
            "end_date",
            "preset",
            "timezone",
            "tz_offset_minutes",
            "search",
            "user_id",
            "username",
            "model",
            "provider",
            "api_format",
            "status",
            "limit",
            "offset",
        ],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        from sqlalchemy import or_
        from sqlalchemy.orm import load_only

        from src.utils.database_helpers import escape_like_pattern, safe_truncate_escaped

        db = context.db

        # -- 构建轻量 count 查询（仅按需 JOIN） --
        needs_user_join = bool(self.search or self.username)
        needs_provider_join = bool(self.search or self.provider)
        needs_apikey_join = bool(self.search)

        count_query = db.query(func.count(Usage.id))
        if needs_user_join:
            count_query = count_query.outerjoin(User, Usage.user_id == User.id)
        if needs_provider_join:
            count_query = count_query.outerjoin(Provider, Usage.provider_id == Provider.id)
        if needs_apikey_join:
            count_query = count_query.outerjoin(ApiKey, Usage.api_key_id == ApiKey.id)

        # -- 构建数据查询（完整 JOIN） --
        usage_model_version = (
            Usage.request_metadata["model_version"].as_string().label("model_version")
        )

        query = (
            db.query(Usage, User, ProviderEndpoint, ProviderAPIKey, ApiKey, usage_model_version)
            .outerjoin(User, Usage.user_id == User.id)
            .outerjoin(ProviderEndpoint, Usage.provider_endpoint_id == ProviderEndpoint.id)
            .outerjoin(ProviderAPIKey, Usage.provider_api_key_id == ProviderAPIKey.id)
            .outerjoin(ApiKey, Usage.api_key_id == ApiKey.id)
        )

        # 如果需要按 Provider 名称搜索/筛选，统一在这里 JOIN
        if self.search or self.provider:
            query = query.join(Provider, Usage.provider_id == Provider.id, isouter=True)

        # 通用搜索：用户名、密钥名、模型名、提供商名
        # 支持空格分隔的组合搜索，多个关键词之间是 AND 关系
        # 限制：最多 10 个关键词，转义后每个关键词最长 100 字符
        if self.search:
            keywords = [kw for kw in self.search.strip().split() if kw][:10]
            for keyword in keywords:
                escaped = safe_truncate_escaped(escape_like_pattern(keyword), 100)
                search_pattern = f"%{escaped}%"
                search_filter = or_(
                    User.username.ilike(search_pattern, escape="\\"),
                    ApiKey.name.ilike(search_pattern, escape="\\"),
                    Usage.model.ilike(search_pattern, escape="\\"),
                    Provider.name.ilike(search_pattern, escape="\\"),
                )
                query = query.filter(search_filter)
                count_query = count_query.filter(search_filter)

        if self.user_id:
            query = query.filter(Usage.user_id == self.user_id)
            count_query = count_query.filter(Usage.user_id == self.user_id)
        if self.username:
            # 支持用户名模糊搜索
            escaped = escape_like_pattern(self.username)
            username_filter = User.username.ilike(f"%{escaped}%", escape="\\")
            query = query.filter(username_filter)
            count_query = count_query.filter(username_filter)
        if self.model:
            # 模型筛选：前端为下拉框精确值，使用精确匹配以启用索引
            # 如需模糊搜索，请使用 search 参数。
            query = query.filter(Usage.model == self.model)
            count_query = count_query.filter(Usage.model == self.model)
        if self.provider:
            # 提供商筛选：前端为下拉框精确值，使用精确匹配以启用索引
            # 如需模糊搜索，请使用 search 参数。
            query = query.filter(Provider.name == self.provider)
            count_query = count_query.filter(Provider.name == self.provider)
        if self.api_format:
            # API 格式筛选：精确匹配（大小写不敏感）
            api_format_filter = func.lower(Usage.api_format) == self.api_format.lower()
            query = query.filter(api_format_filter)
            count_query = count_query.filter(api_format_filter)
        if self.status:
            # 状态筛选
            # 旧的筛选值（基于 is_stream 和 status_code）：stream, standard, error
            # 新的筛选值（基于 status 字段）：pending, streaming, completed, failed, active
            status_filter = None
            if self.status == "stream":
                status_filter = Usage.is_stream == True  # noqa: E712
            elif self.status == "standard":
                status_filter = Usage.is_stream == False  # noqa: E712
            elif self.status == "error":
                status_filter = (Usage.status_code >= 400) | (Usage.error_message.isnot(None))
            elif self.status in ("pending", "streaming", "completed", "cancelled"):
                # 新的状态筛选：直接按 status 字段过滤
                status_filter = Usage.status == self.status
            elif self.status == "failed":
                # 失败请求需要同时考虑新旧两种判断方式：
                # 1. 新方式：status = "failed"
                # 2. 旧方式：status_code >= 400 或 error_message 不为空
                status_filter = (
                    (Usage.status == "failed")
                    | (Usage.status_code >= 400)
                    | (Usage.error_message.isnot(None))
                )
            elif self.status == "active":
                # 活跃请求：pending 或 streaming 状态
                status_filter = Usage.status.in_(["pending", "streaming"])
            elif self.status == "has_retry":
                # 发生重试：存在 retry_index > 0 的已执行候选
                retry_subq = (
                    db.query(RequestCandidate.request_id)
                    .filter(
                        RequestCandidate.status.in_(["success", "failed"]),
                        RequestCandidate.retry_index > 0,
                    )
                    .distinct()
                    .subquery()
                )
                status_filter = Usage.request_id.in_(retry_subq)
            elif self.status == "has_fallback":
                # 发生转移：同一请求有多个不同 candidate_index 的已执行候选
                fallback_subq = (
                    db.query(RequestCandidate.request_id)
                    .filter(RequestCandidate.status.in_(["success", "failed"]))
                    .group_by(RequestCandidate.request_id)
                    .having(func.count(func.distinct(RequestCandidate.candidate_index)) > 1)
                    .subquery()
                )
                status_filter = Usage.request_id.in_(fallback_subq)

            if status_filter is not None:
                query = query.filter(status_filter)
                count_query = count_query.filter(status_filter)

        if self.time_range:
            start_utc, end_utc = self.time_range.to_utc_datetime_range()
            time_filter_start = Usage.created_at >= start_utc
            time_filter_end = Usage.created_at < end_utc
            query = query.filter(time_filter_start, time_filter_end)
            count_query = count_query.filter(time_filter_start, time_filter_end)

        # Perf: count query uses fewer JOINs than the data query
        total = int(count_query.scalar() or 0)

        # Perf: do not load large request/response columns or full request_metadata for list view
        query = query.options(
            load_only(
                Usage.id,
                Usage.request_id,
                Usage.user_id,
                Usage.api_key_id,
                Usage.provider_name,
                Usage.provider_id,
                Usage.provider_endpoint_id,
                Usage.provider_api_key_id,
                Usage.model,
                Usage.target_model,
                Usage.input_tokens,
                Usage.output_tokens,
                Usage.cache_creation_input_tokens,
                Usage.cache_read_input_tokens,
                Usage.total_tokens,
                Usage.total_cost_usd,
                Usage.actual_total_cost_usd,
                Usage.rate_multiplier,
                Usage.response_time_ms,
                Usage.first_byte_time_ms,
                Usage.created_at,
                Usage.is_stream,
                Usage.status_code,
                Usage.error_message,
                Usage.status,
                Usage.api_format,
                Usage.endpoint_api_format,
                Usage.has_format_conversion,
                Usage.input_price_per_1m,
                Usage.output_price_per_1m,
                Usage.cache_creation_price_per_1m,
                Usage.cache_read_price_per_1m,
            ),
            load_only(User.id, User.email, User.username),
            load_only(ProviderEndpoint.id, ProviderEndpoint.api_format),
            load_only(ProviderAPIKey.id, ProviderAPIKey.name),
            load_only(ApiKey.id, ApiKey.name, ApiKey.key_encrypted),
        )
        records = (
            query.order_by(Usage.created_at.desc()).offset(self.offset).limit(self.limit).all()
        )

        request_ids = [usage.request_id for usage, _, _, _, _, _ in records if usage.request_id]
        fallback_map = {}
        retry_map = {}
        rectified_map = {}
        if request_ids:
            # 查询每个请求的候选执行情况
            # 只统计实际执行的候选（success 或 failed），不包括 skipped/pending/available
            executed_candidates = (
                db.query(
                    RequestCandidate.request_id,
                    RequestCandidate.candidate_index,
                    RequestCandidate.retry_index,
                    RequestCandidate.extra_data,
                )
                .filter(
                    RequestCandidate.request_id.in_(request_ids),
                    RequestCandidate.status.in_(["success", "failed"]),
                )
                .all()
            )

            # 按 request_id 分组分析
            request_candidates: dict[str, list[tuple[int, int, dict]]] = defaultdict(list)
            for req_id, candidate_idx, retry_idx, extra_data in executed_candidates:
                request_candidates[req_id].append((candidate_idx, retry_idx, extra_data or {}))

            for req_id, candidates in request_candidates.items():
                # 提取所有不同的 candidate_index
                unique_candidates = {c[0] for c in candidates}
                # 如果有多个不同的 candidate_index，说明发生了 Fallback（Provider 切换）
                fallback_map[req_id] = len(unique_candidates) > 1

                # 检查是否有重试：同一个 candidate_index 有多个 retry_index
                has_retry = False
                for candidate_idx in unique_candidates:
                    retry_indices = [c[1] for c in candidates if c[0] == candidate_idx]
                    if len(retry_indices) > 1 or (retry_indices and max(retry_indices) > 0):
                        has_retry = True
                        break
                retry_map[req_id] = has_retry

                # 检查是否有整流：任意候选的 extra_data 中有 rectified=True
                rectified_map[req_id] = any(c[2].get("rectified", False) for c in candidates)

        context.add_audit_metadata(
            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,
            model=self.model,
            provider=self.provider,
            status=self.status,
            limit=self.limit,
            offset=self.offset,
            total=total,
        )

        # 构建 provider_id -> Provider 名称的映射，避免 N+1 查询
        provider_ids = list(
            {usage.provider_id for usage, _, _, _, _, _ in records if usage.provider_id}
        )
        provider_map = {}
        if provider_ids:
            providers_data = (
                db.query(Provider.id, Provider.name).filter(Provider.id.in_(provider_ids)).all()
            )
            provider_map = {str(p.id): p.name for p in providers_data}

        data = []
        api_key_display_cache: dict[str, str] = {}
        for usage, user, endpoint, provider_api_key, user_api_key, model_version in records:
            actual_cost = (
                float(usage.actual_total_cost_usd)
                if usage.actual_total_cost_usd is not None
                else 0.0
            )
            rate_multiplier = (
                float(usage.rate_multiplier) if usage.rate_multiplier is not None else 1.0
            )

            # 提供商名称优先级：关联的 Provider 表 > usage.provider_name 字段
            provider_name = usage.provider_name
            if usage.provider_id and str(usage.provider_id) in provider_map:
                provider_name = provider_map[str(usage.provider_id)]

            # 格式转换追踪（兼容历史数据：尽量回填可展示信息）
            api_format = usage.api_format or (
                endpoint.api_format if endpoint and endpoint.api_format else None
            )
            endpoint_api_format = usage.endpoint_api_format or (
                endpoint.api_format if endpoint else None
            )

            has_format_conversion = usage.has_format_conversion
            if has_format_conversion is None:
                client_fmt = str(api_format or "").upper()
                endpoint_fmt = str(endpoint_api_format or "").upper()
                has_format_conversion = bool(
                    client_fmt and endpoint_fmt and client_fmt != endpoint_fmt
                )

            data.append(
                {
                    "id": usage.id,
                    "user_id": user.id if user else None,
                    "user_email": user.email if user else "已删除用户",
                    "username": user.username if user else "已删除用户",
                    "api_key": (
                        {
                            "id": user_api_key.id,
                            "name": user_api_key.name,
                            "display": api_key_display_cache.setdefault(
                                user_api_key.id, user_api_key.get_display_key()
                            ),
                        }
                        if user_api_key
                        else None
                    ),
                    "provider": provider_name,
                    "model": usage.model,
                    "target_model": usage.target_model,  # 映射后的目标模型名
                    "input_tokens": usage.input_tokens,
                    "output_tokens": usage.output_tokens,
                    "cache_creation_input_tokens": usage.cache_creation_input_tokens,
                    "cache_read_input_tokens": usage.cache_read_input_tokens,
                    "total_tokens": usage.total_tokens,
                    "cost": float(usage.total_cost_usd),
                    "actual_cost": actual_cost,
                    "rate_multiplier": rate_multiplier,
                    "response_time_ms": usage.response_time_ms,
                    "first_byte_time_ms": usage.first_byte_time_ms,  # 首字时间 (TTFB)
                    "created_at": usage.created_at.isoformat(),
                    "is_stream": usage.is_stream,
                    "input_price_per_1m": usage.input_price_per_1m,
                    "output_price_per_1m": usage.output_price_per_1m,
                    "cache_creation_price_per_1m": usage.cache_creation_price_per_1m,
                    "cache_read_price_per_1m": usage.cache_read_price_per_1m,
                    "status_code": usage.status_code,
                    "error_message": usage.error_message,
                    "status": usage.status,  # 请求状态: pending, streaming, completed, failed
                    "has_fallback": fallback_map.get(usage.request_id, False),
                    "has_retry": retry_map.get(usage.request_id, False),
                    "has_rectified": rectified_map.get(usage.request_id, False),
                    "api_format": api_format,
                    "endpoint_api_format": endpoint_api_format,
                    "has_format_conversion": bool(has_format_conversion),
                    "api_key_name": provider_api_key.name if provider_api_key else None,
                    "model_version": model_version,  # Provider 返回的实际模型版本（轻量字段）
                }
            )

        return {
            "records": data,
            "total": total,
            "limit": self.limit,
            "offset": self.offset,
        }


class AdminActiveRequestsAdapter(AdminApiAdapter):
    """轻量级活跃请求状态查询适配器"""

    def __init__(self, ids: str | None):
        self.ids = ids

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        from src.services.usage import UsageService

        db = context.db
        id_list = None
        if self.ids:
            id_list = [id.strip() for id in self.ids.split(",") if id.strip()]
            if not id_list:
                return {"requests": []}

        requests = UsageService.get_active_requests_status(
            db=db,
            ids=id_list,
            include_admin_fields=True,
            maintain_status=True,
        )
        return {"requests": requests}


@dataclass
class AdminUsageDetailAdapter(AdminApiAdapter):
    """Get detailed usage record with request/response body"""

    usage_id: str
    include_bodies: bool = True

    def _build_usage_detail_query(self, db: Session) -> Any:
        query = db.query(
            Usage,
            case(
                (
                    (Usage.request_body.isnot(None)) | (Usage.request_body_compressed.isnot(None)),
                    True,
                ),
                else_=False,
            ).label("has_request_body"),
            case(
                (
                    (Usage.provider_request_body.isnot(None))
                    | (Usage.provider_request_body_compressed.isnot(None)),
                    True,
                ),
                else_=False,
            ).label("has_provider_request_body"),
            case(
                (
                    (Usage.response_body.isnot(None))
                    | (Usage.response_body_compressed.isnot(None)),
                    True,
                ),
                else_=False,
            ).label("has_response_body"),
            case(
                (
                    (Usage.client_response_body.isnot(None))
                    | (Usage.client_response_body_compressed.isnot(None)),
                    True,
                ),
                else_=False,
            ).label("has_client_response_body"),
        )

        if not self.include_bodies:
            query = query.options(
                defer(Usage.request_body),
                defer(Usage.provider_request_body),
                defer(Usage.response_body),
                defer(Usage.client_response_body),
                defer(Usage.request_body_compressed),
                defer(Usage.provider_request_body_compressed),
                defer(Usage.response_body_compressed),
                defer(Usage.client_response_body_compressed),
            )

        return query

    def _load_usage_detail_row(self, db: Session) -> Any:
        usage_row = self._build_usage_detail_query(db).filter(Usage.id == self.usage_id).first()
        if usage_row:
            return usage_row
        return self._build_usage_detail_query(db).filter(Usage.request_id == self.usage_id).first()

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db
        # 先通过主键 id 查找，如果找不到再尝试通过 request_id 查找
        usage_row = self._load_usage_detail_row(db)
        if not usage_row:
            raise HTTPException(status_code=404, detail="Usage record not found")

        (
            usage_record,
            has_request_body,
            has_provider_request_body,
            has_response_body,
            has_client_response_body,
        ) = usage_row

        user = db.query(User).filter(User.id == usage_record.user_id).first()
        api_key = db.query(ApiKey).filter(ApiKey.id == usage_record.api_key_id).first()

        # 获取阶梯计费信息
        tiered_pricing_info = await self._get_tiered_pricing_info(db, usage_record)

        context.add_audit_metadata(
            action="usage_detail",
            usage_id=self.usage_id,
        )

        # 提取视频/图像/音频计费信息
        video_billing_info = self._extract_video_billing_info(usage_record)

        request_body = usage_record.get_request_body() if self.include_bodies else None
        provider_request_body = (
            usage_record.get_provider_request_body() if self.include_bodies else None
        )
        response_body = usage_record.get_response_body() if self.include_bodies else None
        client_response_body = (
            usage_record.get_client_response_body() if self.include_bodies else None
        )

        return {
            "id": usage_record.id,
            "request_id": usage_record.request_id,
            "user": {
                "id": user.id if user else None,
                "username": user.username if user else "Unknown",
                "email": user.email if user else None,
            },
            "api_key": {
                "id": api_key.id if api_key else None,
                "name": api_key.name if api_key else None,
                "display": api_key.get_display_key() if api_key else None,
            },
            "provider": usage_record.provider_name,
            "api_format": usage_record.api_format,
            "model": usage_record.model,
            "target_model": usage_record.target_model,
            "tokens": {
                "input": usage_record.input_tokens,
                "output": usage_record.output_tokens,
                "total": usage_record.total_tokens,
            },
            "cost": {
                "input": float(usage_record.input_cost_usd or 0),
                "output": float(usage_record.output_cost_usd or 0),
                "total": float(usage_record.total_cost_usd or 0),
            },
            "cache_creation_input_tokens": usage_record.cache_creation_input_tokens,
            "cache_read_input_tokens": usage_record.cache_read_input_tokens,
            "cache_creation_input_tokens_5m": usage_record.cache_creation_input_tokens_5m or 0,
            "cache_creation_input_tokens_1h": usage_record.cache_creation_input_tokens_1h or 0,
            "cache_creation_cost": float(getattr(usage_record, "cache_creation_cost_usd", 0) or 0),
            "cache_read_cost": float(getattr(usage_record, "cache_read_cost_usd", 0) or 0),
            "request_cost": float(getattr(usage_record, "request_cost_usd", 0) or 0),
            "input_price_per_1m": (
                float(usage_record.input_price_per_1m)
                if usage_record.input_price_per_1m is not None
                else None
            ),
            "output_price_per_1m": (
                float(usage_record.output_price_per_1m)
                if usage_record.output_price_per_1m is not None
                else None
            ),
            "cache_creation_price_per_1m": (
                float(usage_record.cache_creation_price_per_1m)
                if usage_record.cache_creation_price_per_1m is not None
                else None
            ),
            "cache_read_price_per_1m": (
                float(usage_record.cache_read_price_per_1m)
                if usage_record.cache_read_price_per_1m is not None
                else None
            ),
            "price_per_request": (
                float(usage_record.price_per_request)
                if usage_record.price_per_request is not None
                else None
            ),
            "request_type": usage_record.request_type,
            "is_stream": usage_record.is_stream,
            "status_code": usage_record.status_code,
            "error_message": usage_record.error_message,
            "status": usage_record.status,
            "response_time_ms": usage_record.response_time_ms,
            "first_byte_time_ms": usage_record.first_byte_time_ms,  # 首字时间 (TTFB)
            "created_at": usage_record.created_at.isoformat() if usage_record.created_at else None,
            "has_request_body": has_request_body,
            "has_provider_request_body": has_provider_request_body,
            "has_response_body": has_response_body,
            "has_client_response_body": has_client_response_body,
            "request_headers": usage_record.request_headers,
            "request_body": request_body,
            "provider_request_headers": usage_record.provider_request_headers,
            "provider_request_body": provider_request_body,
            "response_headers": usage_record.response_headers,
            "client_response_headers": usage_record.client_response_headers,
            "response_body": response_body,
            "client_response_body": client_response_body,
            "metadata": usage_record.request_metadata,
            "tiered_pricing": tiered_pricing_info,
            "video_billing": video_billing_info,
        }

    async def _get_tiered_pricing_info(self, db: Session, usage_record: Any) -> dict | None:
        """获取阶梯计费信息"""
        from src.services.model.cost import ModelCostService

        # 计算总输入上下文（用于阶梯判定）：输入 + 缓存创建 + 缓存读取
        input_tokens = usage_record.input_tokens or 0
        cache_creation_tokens = usage_record.cache_creation_input_tokens or 0
        cache_read_tokens = usage_record.cache_read_input_tokens or 0
        total_input_context = input_tokens + cache_creation_tokens + cache_read_tokens

        # 尝试获取模型的阶梯配置（带来源信息）
        cost_service = ModelCostService(db)
        pricing_result = await cost_service.get_tiered_pricing_with_source_async(
            usage_record.provider_name, usage_record.model
        )

        if not pricing_result:
            return None

        tiered_pricing = pricing_result.get("pricing")
        pricing_source = pricing_result.get("source")  # 'provider' 或 'global'

        if not tiered_pricing or not tiered_pricing.get("tiers"):
            return None

        tiers = tiered_pricing.get("tiers", [])
        if not tiers:
            return None

        # 找到命中的阶梯
        tier_index = None
        matched_tier = None
        for i, tier in enumerate(tiers):
            up_to = tier.get("up_to")
            if up_to is None or total_input_context <= up_to:
                tier_index = i
                matched_tier = tier
                break

        # 如果都没匹配，使用最后一个阶梯
        if tier_index is None and tiers:
            tier_index = len(tiers) - 1
            matched_tier = tiers[-1]

        return {
            "total_input_context": total_input_context,
            "tier_index": tier_index,
            "tier_count": len(tiers),
            "current_tier": matched_tier,
            "tiers": tiers,
            "source": pricing_source,  # 定价来源: 'provider' 或 'global'
        }

    def _extract_video_billing_info(self, usage_record: Any) -> dict | None:
        """
        从 request_metadata.billing_snapshot 和 dimensions 中提取视频/图像/音频计费信息。

        返回结构:
        {
            "task_type": "video" | "image" | "audio",
            "duration_seconds": 10.5,  # 视频时长（秒）
            "resolution": "1080p",     # 分辨率
            "video_price_per_second": 0.1,  # 每秒单价
            "video_cost": 1.05,        # 视频费用
            "rule_name": "...",        # 计费规则名称
            "expression": "...",       # 计费公式
            "status": "complete",      # 计费状态
        }
        """
        request_type = getattr(usage_record, "request_type", None)
        if request_type not in {"video", "image", "audio"}:
            return None

        metadata = getattr(usage_record, "request_metadata", None)
        if not metadata:
            return None

        billing_snapshot = metadata.get("billing_snapshot") if isinstance(metadata, dict) else None
        dimensions = metadata.get("dimensions") if isinstance(metadata, dict) else None

        result: dict = {
            "task_type": request_type,
        }

        # 从 billing_snapshot 中提取计费规则信息
        if billing_snapshot and isinstance(billing_snapshot, dict):
            result["rule_name"] = billing_snapshot.get("rule_name")
            result["expression"] = billing_snapshot.get("expression")
            result["status"] = billing_snapshot.get("status")
            result["cost"] = billing_snapshot.get("cost")

            # 从 dimensions_used 中提取维度
            dims_used = billing_snapshot.get("dimensions_used")
            if dims_used and isinstance(dims_used, dict):
                if "duration_seconds" in dims_used:
                    result["duration_seconds"] = dims_used["duration_seconds"]
                if "video_resolution_key" in dims_used:
                    result["resolution"] = dims_used["video_resolution_key"]
                if "video_price_per_second" in dims_used:
                    result["video_price_per_second"] = dims_used["video_price_per_second"]
                if "video_cost" in dims_used:
                    result["video_cost"] = dims_used["video_cost"]

        # 补充从 dimensions 中提取（备用）
        if dimensions and isinstance(dimensions, dict):
            if "duration_seconds" not in result and "duration_seconds" in dimensions:
                result["duration_seconds"] = dimensions["duration_seconds"]
            if "resolution" not in result and "video_resolution_key" in dimensions:
                result["resolution"] = dimensions["video_resolution_key"]

        # 如果没有有意义的视频计费信息，返回 None
        has_video_info = (
            result.get("duration_seconds")
            or result.get("resolution")
            or result.get("video_cost")
            or result.get("cost")
        )
        if not has_video_info:
            return None

        return result


# ==================== cURL 导出 & 请求回放 ====================


def _find_usage_record(db: Session, usage_id: str) -> Usage:
    """按 id 或 request_id 查找 Usage 记录，找不到则抛 404。"""
    record = db.query(Usage).filter(Usage.id == usage_id).first()
    if not record:
        record = db.query(Usage).filter(Usage.request_id == usage_id).first()
    if not record:
        raise HTTPException(status_code=404, detail="Usage record not found")
    return record


def _build_provider_url_safe(
    endpoint: ProviderEndpoint,
    model_name: str | None,
    is_stream: bool,
    provider_key: ProviderAPIKey | None,
    decrypted_auth_config: dict[str, Any] | None = None,
) -> str:
    """构建 Provider URL，build_provider_url 失败时回退到 base_url + custom_path/默认路径。"""
    from src.services.provider.transport import build_provider_url

    try:
        return build_provider_url(
            endpoint,
            path_params={"model": model_name} if model_name else None,
            is_stream=is_stream,
            key=provider_key,
            decrypted_auth_config=decrypted_auth_config,
        )
    except Exception:
        base = (endpoint.base_url or "").rstrip("/")
        if endpoint.custom_path:
            return f"{base}{endpoint.custom_path}"
        # 尝试使用 API 格式的默认路径
        try:
            from src.core.api_format.metadata import get_default_path_for_endpoint

            ep_sig = (getattr(endpoint, "api_format", "") or "").strip().lower()
            if ep_sig:
                path = get_default_path_for_endpoint(ep_sig)
                if model_name:
                    # Gemini 路径含 {action}，回退时固定用非流式操作
                    action = "streamGenerateContent" if is_stream else "generateContent"
                    try:
                        path = path.format(model=model_name, action=action)
                    except KeyError:
                        pass
                elif "{model}" in path:
                    # model 为空且路径含模板变量，无法构造有效路径，回退到纯 base URL
                    return base
                return f"{base}{path}"
        except Exception:
            pass
        return base


def _build_fresh_headers(
    auth_headers: dict[str, str],
    endpoint: ProviderEndpoint,
) -> dict[str, str]:
    """从零构建请求头：Content-Type + 认证头 + endpoint header_rules 额外头。"""
    from src.core.api_format.headers import get_extra_headers_from_endpoint

    headers: dict[str, str] = {"Content-Type": "application/json"}
    headers.update(auth_headers)
    extra = get_extra_headers_from_endpoint(endpoint)
    if extra:
        headers.update(extra)
    return headers


async def _resolve_provider_auth(
    provider_key: ProviderAPIKey,
    endpoint: ProviderEndpoint,
    db: Session,
) -> tuple[dict[str, str], dict[str, Any] | None]:
    """解析 Provider Key 的认证信息，返回 (认证头字典, 解密后的 auth_config)。

    支持: api_key / oauth / vertex_ai 三种 auth_type。
    """
    from src.core.api_format.metadata import get_auth_config_for_endpoint
    from src.core.crypto import crypto_service

    auth_type = str(getattr(provider_key, "auth_type", "api_key") or "api_key").lower()
    auth_headers: dict[str, str] = {}
    decrypted_auth_config: dict[str, Any] | None = None

    if auth_type == "oauth":
        from src.services.provider.oauth_token import resolve_oauth_access_token
        from src.services.proxy_node.resolver import resolve_effective_proxy

        # 获取 Provider 对象以读取 proxy 和 provider_type
        provider_obj = db.query(Provider).filter(Provider.id == provider_key.provider_id).first()
        provider_type = (
            str(getattr(provider_obj, "provider_type", "") or "").lower() if provider_obj else ""
        )

        # Antigravity 使用 gemini:chat 端点格式
        ep_format = str(getattr(endpoint, "api_format", "") or "")
        if provider_type == "antigravity" and not ep_format:
            ep_format = "gemini:chat"

        resolved = await resolve_oauth_access_token(
            key_id=str(provider_key.id),
            encrypted_api_key=str(provider_key.api_key or ""),
            encrypted_auth_config=(
                str(provider_key.auth_config)
                if getattr(provider_key, "auth_config", None) is not None
                else None
            ),
            provider_proxy_config=(
                resolve_effective_proxy(
                    getattr(provider_obj, "proxy", None),
                    getattr(provider_key, "proxy", None),
                )
                if provider_obj
                else None
            ),
            endpoint_api_format=ep_format,
        )
        access_token = resolved.access_token or ""
        auth_headers["Authorization"] = f"Bearer {access_token}"
        decrypted_auth_config = resolved.decrypted_auth_config

        # Codex 等需要 account_id
        if decrypted_auth_config:
            account_id = decrypted_auth_config.get("account_id")
            if account_id:
                auth_headers["chatgpt-account-id"] = str(account_id)

    elif auth_type in ("service_account", "vertex_ai"):
        from src.api.handlers.base.request_builder import get_provider_auth

        auth_info = await get_provider_auth(endpoint, provider_key)
        if auth_info:
            auth_headers[auth_info.auth_header] = auth_info.auth_value
        else:
            # 回退
            decrypted_key = crypto_service.decrypt(provider_key.api_key)
            auth_headers["Authorization"] = f"Bearer {decrypted_key}"

    else:
        # 标准 API Key
        decrypted_key = crypto_service.decrypt(provider_key.api_key)

        # 根据 endpoint signature 确定认证头名称和类型
        api_family = str(getattr(endpoint, "api_family", "") or "").lower()
        api_kind = str(getattr(endpoint, "endpoint_kind", "") or "").lower()
        if api_family and api_kind:
            endpoint_sig = f"{api_family}:{api_kind}"
        else:
            endpoint_sig = str(getattr(endpoint, "api_format", "") or "") or "openai:chat"

        auth_header, auth_type_cfg = get_auth_config_for_endpoint(endpoint_sig)
        auth_value = f"Bearer {decrypted_key}" if auth_type_cfg == "bearer" else decrypted_key
        auth_headers[auth_header] = auth_value

    return auth_headers, decrypted_auth_config


@dataclass
class AdminUsageCurlAdapter(AdminApiAdapter):
    """Generate cURL command data from a usage record."""

    usage_id: str

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        import json as _json
        import shlex

        db = context.db
        usage_record = _find_usage_record(db, self.usage_id)

        # 获取端点和密钥
        endpoint_id = usage_record.provider_endpoint_id
        key_id = usage_record.provider_api_key_id

        # 兜底：Usage 记录缺少 provider 信息时，从 RequestCandidate 表查找
        if not endpoint_id or not key_id:
            from src.models.database import RequestCandidate as RC

            candidate = (
                db.query(RC)
                .filter(
                    RC.request_id == usage_record.request_id,
                    RC.status.in_(["success", "failed", "streaming"]),
                )
                .order_by(RC.candidate_index.desc(), RC.retry_index.desc())
                .first()
            )
            if candidate:
                endpoint_id = endpoint_id or candidate.endpoint_id
                key_id = key_id or candidate.key_id

        endpoint = None
        if endpoint_id:
            endpoint = db.query(ProviderEndpoint).filter(ProviderEndpoint.id == endpoint_id).first()
        provider_key = None
        if key_id:
            provider_key = db.query(ProviderAPIKey).filter(ProviderAPIKey.id == key_id).first()

        # 解析认证信息
        stored_headers = usage_record.provider_request_headers or {}
        headers: dict[str, str] = {}
        auth_headers: dict[str, str] = {}
        decrypted_auth_config: dict[str, Any] | None = None

        if provider_key and endpoint:
            try:
                auth_headers, decrypted_auth_config = await _resolve_provider_auth(
                    provider_key, endpoint, db
                )

                if stored_headers:
                    # 有存储的请求头：替换被脱敏的认证头为真实值
                    headers = dict(stored_headers)
                    auth_lower_keys = {k.lower() for k in auth_headers}
                    for key_name in list(headers.keys()):
                        if key_name.lower() in auth_lower_keys:
                            del headers[key_name]
                    headers.update(auth_headers)
                else:
                    headers = _build_fresh_headers(auth_headers, endpoint)
            except Exception:
                headers = dict(stored_headers)
        else:
            headers = dict(stored_headers)

        # 重建请求 URL（在认证解析之后，以便传递 decrypted_auth_config 给 Vertex AI 等场景）
        url: str | None = None
        if endpoint:
            model_name = usage_record.target_model or usage_record.model
            url = _build_provider_url_safe(
                endpoint,
                model_name,
                usage_record.is_stream or False,
                provider_key,
                decrypted_auth_config,
            )

        # 确保始终有 Content-Type
        if not any(k.lower() == "content-type" for k in headers):
            headers["Content-Type"] = "application/json"

        # 获取请求体
        body = usage_record.get_request_body()

        # 生成 cURL 命令
        curl_parts = ["curl"]
        if url:
            curl_parts.append(shlex.quote(url))
        curl_parts.append("-X POST")

        for h_key, h_value in headers.items():
            curl_parts.append(f"-H {shlex.quote(f'{h_key}: {h_value}')}")

        if body:
            body_str = _json.dumps(body, ensure_ascii=False)
            curl_parts.append(f"-d {shlex.quote(body_str)}")

        curl_command = " \\\n  ".join(curl_parts)

        context.add_audit_metadata(
            action="usage_curl",
            usage_id=self.usage_id,
        )

        return {
            "url": url,
            "method": "POST",
            "headers": headers,
            "body": body,
            "curl": curl_command,
        }


def _resolve_replay_mode(same_provider: bool, same_endpoint: bool) -> str:
    if same_provider and same_endpoint:
        return "same_endpoint_reuse"
    if same_provider:
        return "same_provider_remap"
    return "cross_provider_remap"


async def _resolve_replay_model_name(
    db: Session,
    *,
    source_model: str,
    target_provider: Provider,
    target_endpoint: ProviderEndpoint,
    target_api_key: ProviderAPIKey | None,
) -> tuple[str, str]:
    """按当前 replay 目标重新解析模型名，并返回 mapping_source。"""
    from src.services.model.mapper import ModelMapperMiddleware

    target_api_format = (getattr(target_endpoint, "api_format", "") or "").strip().lower()

    mapper = ModelMapperMiddleware(db)
    mapping = await mapper.get_mapping(source_model, str(target_provider.id))

    if mapping and mapping.model:
        affinity_key = target_api_key.id if target_api_key else None
        mapped_name = mapping.model.select_provider_model_name(
            affinity_key, api_format=target_api_format
        )
        return mapped_name, "model_mapping"

    logger.debug(
        "[replay] No explicit model mapping for '{}' on provider '{}' (endpoint={}, api_format={}); "
        "forwarding original source model",
        source_model,
        target_provider.name or str(target_provider.id),
        str(getattr(target_endpoint, "id", "") or "unknown"),
        target_api_format or "unknown",
    )

    # Keep replay aligned with the normal request path: if no global-model mapping exists,
    # forward the original source model name and let the target provider validate it.
    return source_model, "none"


def _apply_replay_model_to_body(
    body: dict[str, Any],
    resolved_model: str,
    target_api_format: str | None,
) -> None:
    """根据目标格式决定是否写入 body.model。"""
    from src.core.api_format.metadata import resolve_endpoint_definition

    target_meta = resolve_endpoint_definition(target_api_format) if target_api_format else None
    if target_meta is not None and not target_meta.model_in_body:
        body.pop("model", None)
        return

    body["model"] = resolved_model


@dataclass
class AdminUsageReplayAdapter(AdminApiAdapter):
    """Replay a usage record request to the same or a different provider."""

    usage_id: str
    target_provider_id: str | None = None
    target_endpoint_id: str | None = None
    target_api_key_id: str | None = None
    body_override: dict | None = None

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        del context
        raise HTTPException(
            status_code=503,
            detail="Admin usage replay requires Rust maintenance backend",
        )


# ==================== 缓存亲和性分析 ====================


@router.get("/cache-affinity/ttl-analysis")
async def analyze_cache_affinity_ttl(
    request: Request,
    user_id: str | None = Query(None, description="指定用户 ID"),
    api_key_id: str | None = Query(None, description="指定 API Key ID"),
    hours: int = Query(168, ge=1, le=720, description="分析最近多少小时的数据"),
    db: Session = Depends(get_db),
) -> Any:
    """
    分析用户请求间隔分布，推荐合适的缓存亲和性 TTL。

    通过分析同一用户连续请求之间的时间间隔，判断用户的使用模式：
    - 高频用户（间隔短）：5 分钟 TTL 足够
    - 中频用户：15-30 分钟 TTL
    - 低频用户（间隔长）：需要 60 分钟 TTL
    """
    adapter = CacheAffinityTTLAnalysisAdapter(
        user_id=user_id,
        api_key_id=api_key_id,
        hours=hours,
    )
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.get("/cache-affinity/hit-analysis")
async def analyze_cache_hit(
    request: Request,
    user_id: str | None = Query(None, description="指定用户 ID"),
    api_key_id: str | None = Query(None, description="指定 API Key ID"),
    hours: int = Query(168, ge=1, le=720, description="分析最近多少小时的数据"),
    db: Session = Depends(get_db),
) -> Any:
    """
    分析缓存命中情况。

    返回缓存命中率、节省的费用等统计信息。
    """
    adapter = CacheHitAnalysisAdapter(
        user_id=user_id,
        api_key_id=api_key_id,
        hours=hours,
    )
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


class CacheAffinityTTLAnalysisAdapter(AdminApiAdapter):
    """缓存亲和性 TTL 分析适配器"""

    def __init__(
        self,
        user_id: str | None,
        api_key_id: str | None,
        hours: int,
    ):
        self.user_id = user_id
        self.api_key_id = api_key_id
        self.hours = hours

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db

        result = UsageService.analyze_cache_affinity_ttl(
            db=db,
            user_id=self.user_id,
            api_key_id=self.api_key_id,
            hours=self.hours,
        )

        context.add_audit_metadata(
            action="cache_affinity_ttl_analysis",
            user_id=self.user_id,
            api_key_id=self.api_key_id,
            hours=self.hours,
            total_users_analyzed=result.get("total_users_analyzed", 0),
        )

        return result


class CacheHitAnalysisAdapter(AdminApiAdapter):
    """缓存命中分析适配器"""

    def __init__(
        self,
        user_id: str | None,
        api_key_id: str | None,
        hours: int,
    ):
        self.user_id = user_id
        self.api_key_id = api_key_id
        self.hours = hours

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db

        result = UsageService.get_cache_hit_analysis(
            db=db,
            user_id=self.user_id,
            api_key_id=self.api_key_id,
            hours=self.hours,
        )

        context.add_audit_metadata(
            action="cache_hit_analysis",
            user_id=self.user_id,
            api_key_id=self.api_key_id,
            hours=self.hours,
        )

        return result


@router.get("/cache-affinity/interval-timeline")
async def get_interval_timeline(
    request: Request,
    hours: int = Query(24, ge=1, le=720, description="分析最近多少小时的数据"),
    limit: int = Query(3000, ge=100, le=50000, description="最大返回数据点数量"),
    user_id: str | None = Query(None, description="指定用户 ID"),
    include_user_info: bool = Query(False, description="是否包含用户信息（用于管理员多用户视图）"),
    db: Session = Depends(get_db),
) -> Any:
    """
    获取请求间隔时间线数据，用于散点图展示。

    返回每个请求的时间点和与上一个请求的间隔（分钟），
    可用于可视化用户请求模式。

    当 include_user_info=true 且未指定 user_id 时，返回数据会包含:
    - points 中每个点包含 user_id 字段
    - users 字段包含 user_id -> username 的映射
    """
    adapter = IntervalTimelineAdapter(
        hours=hours,
        limit=limit,
        user_id=user_id,
        include_user_info=include_user_info,
    )
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


class IntervalTimelineAdapter(AdminApiAdapter):
    """请求间隔时间线适配器"""

    def __init__(
        self,
        hours: int,
        limit: int,
        user_id: str | None = None,
        include_user_info: bool = False,
    ):
        self.hours = hours
        self.limit = limit
        self.user_id = user_id
        self.include_user_info = include_user_info

    @cache_result(
        key_prefix="admin:usage:interval_timeline",
        ttl=CacheTTL.ADMIN_USAGE_AGGREGATION,
        user_specific=False,
        vary_by=["hours", "limit", "user_id", "include_user_info"],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db

        result = UsageService.get_interval_timeline(
            db=db,
            hours=self.hours,
            limit=self.limit,
            user_id=self.user_id,
            include_user_info=self.include_user_info,
        )

        context.add_audit_metadata(
            action="interval_timeline",
            hours=self.hours,
            limit=self.limit,
            user_id=self.user_id,
            include_user_info=self.include_user_info,
            total_points=result.get("total_points", 0),
        )

        return result