Aether/src/api/admin/monitoring/trace.py

"""
请求链路追踪 API 端点
"""

from dataclasses import dataclass
from datetime import datetime
from typing import List, Optional

from fastapi import APIRouter, Depends, HTTPException, Query, Request
from pydantic import BaseModel, ConfigDict
from sqlalchemy.orm import Session

from src.api.base.admin_adapter import AdminApiAdapter
from src.api.base.pipeline import ApiRequestPipeline
from src.database import get_db
from src.models.database import Provider, ProviderEndpoint, ProviderAPIKey
from src.core.crypto import crypto_service
from src.services.request.candidate import RequestCandidateService

router = APIRouter(prefix="/api/admin/monitoring/trace", tags=["Admin - Monitoring: Trace"])
pipeline = ApiRequestPipeline()


class CandidateResponse(BaseModel):
    """候选记录响应"""

    id: str
    request_id: str
    candidate_index: int
    retry_index: int = 0  # 重试序号（从0开始）
    provider_id: Optional[str] = None
    provider_name: Optional[str] = None
    provider_website: Optional[str] = None  # Provider 官网
    endpoint_id: Optional[str] = None
    endpoint_name: Optional[str] = None  # 端点显示名称（api_format）
    key_id: Optional[str] = None
    key_name: Optional[str] = None  # 密钥名称
    key_preview: Optional[str] = None  # 密钥脱敏预览（如 sk-***abc）
    key_capabilities: Optional[dict] = None  # Key 支持的能力
    required_capabilities: Optional[dict] = None  # 请求实际需要的能力标签
    status: str  # 'pending', 'success', 'failed', 'skipped'
    skip_reason: Optional[str] = None
    is_cached: bool = False
    # 执行结果字段
    status_code: Optional[int] = None
    error_type: Optional[str] = None
    error_message: Optional[str] = None
    latency_ms: Optional[int] = None
    concurrent_requests: Optional[int] = None
    extra_data: Optional[dict] = None
    created_at: datetime
    started_at: Optional[datetime] = None
    finished_at: Optional[datetime] = None

    model_config = ConfigDict(from_attributes=True)


class RequestTraceResponse(BaseModel):
    """请求追踪完整响应"""

    request_id: str
    total_candidates: int
    final_status: str  # 'success', 'failed', 'streaming', 'pending'
    total_latency_ms: int
    candidates: List[CandidateResponse]


@router.get("/{request_id}", response_model=RequestTraceResponse)
async def get_request_trace(
    request_id: str,
    request: Request,
    db: Session = Depends(get_db),
):
    """获取特定请求的完整追踪信息"""

    adapter = AdminGetRequestTraceAdapter(request_id=request_id)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.get("/stats/provider/{provider_id}")
async def get_provider_failure_rate(
    provider_id: str,
    request: Request,
    limit: int = Query(100, ge=1, le=1000, description="统计最近的尝试数量"),
    db: Session = Depends(get_db),
):
    """
    获取某个 Provider 的失败率统计

    需要管理员权限
    """
    adapter = AdminProviderFailureRateAdapter(provider_id=provider_id, limit=limit)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


# -------- 请求追踪适配器 --------


@dataclass
class AdminGetRequestTraceAdapter(AdminApiAdapter):
    request_id: str

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

        # 只查询 candidates
        candidates = RequestCandidateService.get_candidates_by_request_id(db, self.request_id)

        # 如果没有数据，返回 404
        if not candidates:
            raise HTTPException(status_code=404, detail="Request not found")

        # 计算总延迟（只统计已完成的候选：success 或 failed）
        # 使用显式的 is not None 检查，避免过滤掉 0ms 的快速响应
        total_latency = sum(
            c.latency_ms
            for c in candidates
            if c.status in ("success", "failed") and c.latency_ms is not None
        )

        # 判断最终状态：
        # 1. status="success" 即视为成功（无论 status_code 是什么）
        #    - 流式请求即使客户端断开（499），只要 Provider 成功返回数据，也算成功
        # 2. 同时检查 status_code 在 200-299 范围，作为额外的成功判断条件
        #    - 用于兼容非流式请求或未正确设置 status 的旧数据
        # 3. status="streaming" 表示流式请求正在进行中
        # 4. status="pending" 表示请求尚未开始执行
        has_success = any(
            c.status == "success"
            or (c.status_code is not None and 200 <= c.status_code < 300)
            for c in candidates
        )
        has_streaming = any(c.status == "streaming" for c in candidates)
        has_pending = any(c.status == "pending" for c in candidates)

        if has_success:
            final_status = "success"
        elif has_streaming:
            # 有候选正在流式传输中
            final_status = "streaming"
        elif has_pending:
            # 有候选正在等待执行
            final_status = "pending"
        else:
            final_status = "failed"

        # 批量加载 provider 信息，避免 N+1 查询
        provider_ids = {c.provider_id for c in candidates if c.provider_id}
        provider_map = {}
        provider_website_map = {}
        if provider_ids:
            providers = db.query(Provider).filter(Provider.id.in_(provider_ids)).all()
            for p in providers:
                provider_map[p.id] = p.name
                provider_website_map[p.id] = p.website

        # 批量加载 endpoint 信息
        endpoint_ids = {c.endpoint_id for c in candidates if c.endpoint_id}
        endpoint_map = {}
        if endpoint_ids:
            endpoints = db.query(ProviderEndpoint).filter(ProviderEndpoint.id.in_(endpoint_ids)).all()
            endpoint_map = {e.id: e.api_format for e in endpoints}

        # 批量加载 key 信息
        key_ids = {c.key_id for c in candidates if c.key_id}
        key_map = {}
        key_preview_map = {}
        key_capabilities_map = {}
        if key_ids:
            keys = db.query(ProviderAPIKey).filter(ProviderAPIKey.id.in_(key_ids)).all()
            for k in keys:
                key_map[k.id] = k.name
                key_capabilities_map[k.id] = k.capabilities
                # 生成脱敏预览：先解密再脱敏
                try:
                    decrypted_key = crypto_service.decrypt(k.api_key)
                    if len(decrypted_key) > 8:
                        # 检测常见前缀模式
                        prefix_end = 0
                        for prefix in ["sk-", "key-", "api-", "ak-"]:
                            if decrypted_key.lower().startswith(prefix):
                                prefix_end = len(prefix)
                                break
                        if prefix_end > 0:
                            key_preview_map[k.id] = f"{decrypted_key[:prefix_end]}***{decrypted_key[-4:]}"
                        else:
                            key_preview_map[k.id] = f"{decrypted_key[:4]}***{decrypted_key[-4:]}"
                    elif len(decrypted_key) > 4:
                        key_preview_map[k.id] = f"***{decrypted_key[-4:]}"
                    else:
                        key_preview_map[k.id] = "***"
                except Exception:
                    key_preview_map[k.id] = "***"

        # 构建 candidate 响应列表
        candidate_responses: List[CandidateResponse] = []
        for candidate in candidates:
            provider_name = (
                provider_map.get(candidate.provider_id) if candidate.provider_id else None
            )
            provider_website = (
                provider_website_map.get(candidate.provider_id) if candidate.provider_id else None
            )
            endpoint_name = (
                endpoint_map.get(candidate.endpoint_id) if candidate.endpoint_id else None
            )
            key_name = (
                key_map.get(candidate.key_id) if candidate.key_id else None
            )
            key_preview = (
                key_preview_map.get(candidate.key_id) if candidate.key_id else None
            )
            key_capabilities = (
                key_capabilities_map.get(candidate.key_id) if candidate.key_id else None
            )

            candidate_responses.append(
                CandidateResponse(
                    id=candidate.id,
                    request_id=candidate.request_id,
                    candidate_index=candidate.candidate_index,
                    retry_index=candidate.retry_index,
                    provider_id=candidate.provider_id,
                    provider_name=provider_name,
                    provider_website=provider_website,
                    endpoint_id=candidate.endpoint_id,
                    endpoint_name=endpoint_name,
                    key_id=candidate.key_id,
                    key_name=key_name,
                    key_preview=key_preview,
                    key_capabilities=key_capabilities,
                    required_capabilities=candidate.required_capabilities,
                    status=candidate.status,
                    skip_reason=candidate.skip_reason,
                    is_cached=candidate.is_cached,
                    status_code=candidate.status_code,
                    error_type=candidate.error_type,
                    error_message=candidate.error_message,
                    latency_ms=candidate.latency_ms,
                    concurrent_requests=candidate.concurrent_requests,
                    extra_data=candidate.extra_data,
                    created_at=candidate.created_at,
                    started_at=candidate.started_at,
                    finished_at=candidate.finished_at,
                )
            )

        response = RequestTraceResponse(
            request_id=self.request_id,
            total_candidates=len(candidates),
            final_status=final_status,
            total_latency_ms=total_latency,
            candidates=candidate_responses,
        )
        context.add_audit_metadata(
            action="trace_request_detail",
            request_id=self.request_id,
            total_candidates=len(candidates),
            final_status=final_status,
            total_latency_ms=total_latency,
        )
        return response


@dataclass
class AdminProviderFailureRateAdapter(AdminApiAdapter):
    provider_id: str
    limit: int

    async def handle(self, context):  # type: ignore[override]
        result = RequestCandidateService.get_candidate_stats_by_provider(
            db=context.db,
            provider_id=self.provider_id,
            limit=self.limit,
        )
        context.add_audit_metadata(
            action="trace_provider_failure_rate",
            provider_id=self.provider_id,
            limit=self.limit,
            total_attempts=result.get("total_attempts"),
            failure_rate=result.get("failure_rate"),
        )
        return result