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

"""管理员 Provider 管理路由。"""

from __future__ import annotations

import asyncio
import uuid
from datetime import datetime, timezone
from typing import Any

from fastapi import APIRouter, Depends, Query, Request
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from sqlalchemy import func
from sqlalchemy.orm import Session, load_only

from src.api.base.admin_adapter import AdminApiAdapter
from src.api.base.context import ApiRequestContext
from src.api.base.models_service import invalidate_models_list_cache
from src.api.base.pipeline import get_pipeline
from src.config.constants import CacheTTL
from src.core.enums import ProviderBillingType
from src.core.exceptions import InvalidRequestException, NotFoundException
from src.core.logger import logger
from src.core.model_permissions import match_model_with_pattern, parse_allowed_models_to_list
from src.core.provider_templates.fixed_providers import FIXED_PROVIDERS
from src.core.provider_templates.types import ProviderType
from src.database import get_db
from src.models.admin_requests import CreateProviderRequest, UpdateProviderRequest
from src.models.database import GlobalModel, Provider, ProviderAPIKey, ProviderEndpoint
from src.models.endpoint_models import ProviderWithEndpointsSummary
from src.services.cache.model_cache import ModelCacheService
from src.services.cache.provider_cache import ProviderCacheService
from src.services.provider.delete_task import get_provider_delete_task, submit_provider_delete
from src.utils.cache_decorator import cache_result

from .summary import _build_provider_summary

router = APIRouter(tags=["Provider CRUD"])
pipeline = get_pipeline()


# 映射预览配置（管理后台功能，限制宽松）
MAPPING_PREVIEW_MAX_KEYS = 200
MAPPING_PREVIEW_MAX_MODELS = 500
MAPPING_PREVIEW_TIMEOUT_SECONDS = 10.0


def _should_enable_format_conversion_by_default(provider_type: str | None) -> bool:
    """固定类型 Provider 默认是否开启格式转换。"""
    pt = (provider_type or "custom").strip().lower()
    envelope_provider_types = {
        ProviderType.ANTIGRAVITY.value,
        ProviderType.CLAUDE_CODE.value,
        ProviderType.CODEX.value,
        ProviderType.KIRO.value,
        ProviderType.VERTEX_AI.value,
    }
    return pt in envelope_provider_types


def _normalize_provider_type(provider_type: str | None) -> str:
    return (provider_type or "custom").strip().lower()


def _get_fixed_provider_template(provider_type: str | None) -> Any | None:
    """Return fixed-provider template when provider_type is managed by FIXED_PROVIDERS."""
    normalized = _normalize_provider_type(provider_type)
    try:
        return FIXED_PROVIDERS.get(ProviderType(normalized))
    except Exception:
        return None


def _resolve_new_provider_priority(
    current_min_priority: int | None, requested_priority: int | None
) -> tuple[int, bool]:
    """Resolve insertion priority for a newly created provider.

    Returns ``(priority, needs_shift)``.  When the caller explicitly specifies
    a priority we need to shift existing rows. For auto-top insertion we prefer
    ``min - 1`` when that still stays non-negative; otherwise we clamp to ``0``
    and shift existing rows down to preserve ordering.
    """
    if requested_priority is not None:
        return int(requested_priority), True
    if current_min_priority is not None:
        current_min = int(current_min_priority)
        if current_min <= 0:
            return 0, True
        return current_min - 1, False
    return 100, False


def _merge_pool_advanced_config(
    *,
    provider_config: dict[str, Any] | None,
    pool_advanced: dict[str, Any] | None,
    pool_advanced_in_payload: bool,
) -> tuple[dict[str, Any] | None, bool]:
    """合并 pool_advanced 到 provider.config（任何 provider_type 均可使用）。"""
    merged_config = dict(provider_config or {})
    config_changed = False

    if not pool_advanced_in_payload:
        return merged_config or None, config_changed

    if pool_advanced is None:
        if "pool_advanced" in merged_config:
            merged_config.pop("pool_advanced", None)
            config_changed = True
    else:
        next_value = dict(pool_advanced)
        if merged_config.get("pool_advanced") != next_value:
            merged_config["pool_advanced"] = next_value
            config_changed = True

    return merged_config or None, config_changed


def _merge_failover_rules_config(
    *,
    provider_config: dict[str, Any] | None,
    failover_rules: dict[str, Any] | None,
    failover_rules_in_payload: bool,
) -> tuple[dict[str, Any] | None, bool]:
    """合并 failover_rules 到 provider.config。"""
    merged_config = dict(provider_config or {})
    config_changed = False

    if not failover_rules_in_payload:
        return merged_config or None, config_changed

    if failover_rules is None:
        if "failover_rules" in merged_config:
            merged_config.pop("failover_rules", None)
            config_changed = True
    else:
        next_value = dict(failover_rules)
        if merged_config.get("failover_rules") != next_value:
            merged_config["failover_rules"] = next_value
            config_changed = True

    return merged_config or None, config_changed


def _merge_claude_code_advanced_config(
    *,
    provider_type: str | None,
    provider_config: dict[str, Any] | None,
    claude_code_advanced: dict[str, Any] | None,
    claude_advanced_in_payload: bool,
) -> tuple[dict[str, Any] | None, bool]:
    """合并并规范 claude_code_advanced，确保仅在 claude_code 下保留。"""
    normalized_provider_type = _normalize_provider_type(provider_type)
    merged_config = dict(provider_config or {})
    config_changed = False

    if normalized_provider_type != ProviderType.CLAUDE_CODE.value:
        if claude_advanced_in_payload and claude_code_advanced is not None:
            raise InvalidRequestException("claude_code_advanced 仅适用于 provider_type=claude_code")
        if "claude_code_advanced" in merged_config:
            merged_config.pop("claude_code_advanced", None)
            config_changed = True
        return merged_config or None, config_changed

    if not claude_advanced_in_payload:
        return merged_config or None, config_changed

    if claude_code_advanced is None:
        if "claude_code_advanced" in merged_config:
            merged_config.pop("claude_code_advanced", None)
            config_changed = True
    else:
        next_value = dict(claude_code_advanced)
        if merged_config.get("claude_code_advanced") != next_value:
            merged_config["claude_code_advanced"] = next_value
            config_changed = True

    return merged_config or None, config_changed


# ========== Response Models ==========


class MappingMatchedModel(BaseModel):
    """匹配到的模型名称"""

    allowed_model: str = Field(..., description="Key 白名单中匹配到的模型名")
    mapping_pattern: str = Field(..., description="匹配的映射规则")


class MappingMatchingGlobalModel(BaseModel):
    """有映射匹配的 GlobalModel"""

    global_model_id: str
    global_model_name: str
    display_name: str
    is_active: bool
    matched_models: list[MappingMatchedModel] = Field(
        default_factory=list, description="匹配到的模型列表"
    )

    model_config = ConfigDict(from_attributes=True)


class MappingMatchingKey(BaseModel):
    """有映射匹配的 Key"""

    key_id: str
    key_name: str
    masked_key: str
    is_active: bool
    allowed_models: list[str] = Field(default_factory=list, description="Key 的模型白名单")
    matching_global_models: list[MappingMatchingGlobalModel] = Field(
        default_factory=list, description="匹配到的 GlobalModel 列表"
    )

    model_config = ConfigDict(from_attributes=True)


class ProviderMappingPreviewResponse(BaseModel):
    """Provider 映射预览响应"""

    provider_id: str
    provider_name: str
    keys: list[MappingMatchingKey] = Field(
        default_factory=list, description="有白名单配置且匹配到映射的 Key 列表"
    )
    total_keys: int = Field(0, description="有匹配结果的 Key 数量")
    total_matches: int = Field(
        0, description="匹配到的 GlobalModel 数量（同一 GlobalModel 被多个 Key 匹配会重复计数）"
    )
    # 截断提示字段
    truncated: bool = Field(False, description="是否因限制而截断结果")
    truncated_keys: int = Field(0, description="被截断的 Key 数量")
    truncated_models: int = Field(0, description="被截断的 GlobalModel 数量")

    model_config = ConfigDict(from_attributes=True)


class ProviderDeleteSubmitResponse(BaseModel):
    task_id: str
    status: str = "pending"
    message: str = ""


class ProviderDeleteTaskResponse(BaseModel):
    task_id: str
    provider_id: str
    status: str
    stage: str = "queued"
    total_keys: int = 0
    deleted_keys: int = 0
    total_endpoints: int = 0
    deleted_endpoints: int = 0
    message: str = ""


@router.get("/")
async def list_providers(
    request: Request,
    skip: int = Query(0, ge=0),
    limit: int = Query(100, ge=1, le=500),
    is_active: bool | None = None,
    db: Session = Depends(get_db),
) -> Any:
    """
    获取提供商列表

    获取所有提供商的基本信息列表，支持分页和状态过滤。

    **查询参数**:
    - `skip`: 跳过的记录数，用于分页，默认为 0
    - `limit`: 返回的最大记录数，范围 1-500，默认为 100
    - `is_active`: 可选的活跃状态过滤，true 仅返回活跃提供商，false 返回禁用提供商，不传则返回全部

    **返回字段**:
    - `id`: 提供商 ID
    - `name`: 提供商名称（唯一）
    - `api_format`: API 格式（如 claude、openai、gemini 等）
    - `base_url`: API 基础 URL
    - `api_key`: API 密钥（脱敏显示）
    - `priority`: 优先级
    - `is_active`: 是否活跃
    - `created_at`: 创建时间
    - `updated_at`: 更新时间
    """
    adapter = AdminListProvidersAdapter(skip=skip, limit=limit, is_active=is_active)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.post("/")
async def create_provider(request: Request, db: Session = Depends(get_db)) -> Any:
    """
    创建新提供商

    创建一个新的 AI 模型提供商配置。

    **请求体字段**:
    - `name`: 提供商名称（必填，唯一）
    - `description`: 描述信息（可选）
    - `website`: 官网地址（可选）
    - `billing_type`: 计费类型（可选，pay_as_you_go/subscription/prepaid，默认 pay_as_you_go）
    - `monthly_quota_usd`: 月度配额（美元）（可选）
    - `quota_reset_day`: 配额重置日期（1-31）（可选）
    - `quota_last_reset_at`: 上次配额重置时间（可选）
    - `quota_expires_at`: 配额过期时间（可选）
    - `provider_priority`: 提供商优先级（数字越小优先级越高；不传时自动置顶，并将原有提供商顺延一位）
    - `is_active`: 是否启用（默认 true）
    - `concurrent_limit`: 并发限制（可选）
    - `max_retries`: 最大重试次数（可选）
    - `proxy`: 代理配置（可选）
    - `config`: 额外配置信息（JSON，可选）

    **返回字段**:
    - `id`: 新创建的提供商 ID
    - `name`: 提供商名称
    - `message`: 成功提示信息
    """
    adapter = AdminCreateProviderAdapter()
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.patch("/{provider_id}")
async def update_provider(
    provider_id: str, request: Request, db: Session = Depends(get_db)
) -> ProviderWithEndpointsSummary:
    """
    更新提供商配置

    更新指定提供商的配置信息。只需传入需要更新的字段，未传入的字段保持不变。

    **路径参数**:
    - `provider_id`: 提供商 ID

    **请求体字段**（所有字段可选）:
    - `name`: 提供商名称
    - `description`: 描述信息
    - `website`: 官网地址
    - `billing_type`: 计费类型（pay_as_you_go/subscription/prepaid）
    - `monthly_quota_usd`: 月度配额（美元）
    - `quota_reset_day`: 配额重置日期（1-31）
    - `quota_last_reset_at`: 上次配额重置时间
    - `quota_expires_at`: 配额过期时间
    - `provider_priority`: 提供商优先级
    - `is_active`: 是否启用
    - `concurrent_limit`: 并发限制
    - `max_retries`: 最大重试次数
    - `proxy`: 代理配置
    - `config`: 额外配置信息（JSON）

    **返回字段**:
    - `id`: 提供商 ID
    - `name`: 提供商名称
    - `is_active`: 是否启用
    - `message`: 成功提示信息
    """
    adapter = AdminUpdateProviderAdapter(provider_id=provider_id)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.delete("/{provider_id}", response_model=ProviderDeleteSubmitResponse)
async def delete_provider(
    provider_id: str, request: Request, db: Session = Depends(get_db)
) -> ProviderDeleteSubmitResponse:
    """
    删除提供商

    删除指定的提供商。注意：此操作会级联删除关联的端点、密钥和模型配置。

    **路径参数**:
    - `provider_id`: 提供商 ID

    **返回字段**:
    - `task_id`: 后台删除任务 ID
    - `status`: 任务状态
    - `message`: 提交结果提示
    """
    adapter = AdminDeleteProviderAdapter(provider_id=provider_id)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


@router.get("/{provider_id}/delete-task/{task_id}", response_model=ProviderDeleteTaskResponse)
async def get_delete_provider_task_status(
    provider_id: str,
    task_id: str,
    request: Request,
    db: Session = Depends(get_db),
) -> ProviderDeleteTaskResponse:
    """查询 Provider 删除任务状态。"""
    adapter = AdminProviderDeleteTaskStatusAdapter(provider_id=provider_id, task_id=task_id)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


class AdminListProvidersAdapter(AdminApiAdapter):
    def __init__(self, skip: int, limit: int, is_active: bool | None):
        self.skip = skip
        self.limit = limit
        self.is_active = is_active

    @cache_result(
        key_prefix="admin:providers:list",
        ttl=CacheTTL.ADMIN_USAGE_RECORDS,
        user_specific=False,
        vary_by=["skip", "limit", "is_active"],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db
        query = db.query(Provider).options(
            load_only(
                Provider.id,
                Provider.name,
                Provider.provider_priority,
                Provider.is_active,
                Provider.created_at,
                Provider.updated_at,
            )
        )
        if self.is_active is not None:
            query = query.filter(Provider.is_active == self.is_active)
        providers = query.offset(self.skip).limit(self.limit).all()

        data = []
        for provider in providers:
            api_format = getattr(provider, "api_format", None)
            base_url = getattr(provider, "base_url", None)
            api_key = getattr(provider, "api_key", None)
            priority = getattr(provider, "priority", provider.provider_priority)

            data.append(
                {
                    "id": provider.id,
                    "name": provider.name,
                    "api_format": api_format.value if api_format else None,
                    "base_url": base_url,
                    "api_key": "***" if api_key else None,
                    "priority": priority,
                    "is_active": provider.is_active,
                    "created_at": provider.created_at.isoformat(),
                    "updated_at": provider.updated_at.isoformat() if provider.updated_at else None,
                }
            )
        context.add_audit_metadata(
            action="list_providers",
            filter_is_active=self.is_active,
            limit=self.limit,
            skip=self.skip,
            result_count=len(data),
        )
        return data


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

        try:
            # 使用 Pydantic 模型进行验证（自动进行 SQL 注入、XSS、SSRF 检测）
            validated_data = CreateProviderRequest.model_validate(payload)
        except ValidationError as exc:
            # 将 Pydantic 验证错误转换为友好的错误信息
            errors = []
            for error in exc.errors():
                field = " -> ".join(str(x) for x in error["loc"])
                errors.append(f"{field}: {error['msg']}")
            raise InvalidRequestException("输入验证失败: " + "; ".join(errors))

        try:
            # 检查名称是否已存在
            existing = db.query(Provider).filter(Provider.name == validated_data.name).first()
            if existing:
                raise InvalidRequestException(f"提供商名称 '{validated_data.name}' 已存在")

            # 将验证后的数据转换为枚举类型
            billing_type = (
                ProviderBillingType(validated_data.billing_type)
                if validated_data.billing_type
                else ProviderBillingType.PAY_AS_YOU_GO
            )

            # 有 envelope 包装的 Provider 类型（如 ClaudeCode、Antigravity、Codex）需要
            # 格式转换来正确解包上游响应，创建时默认开启 enable_format_conversion。
            pt = _normalize_provider_type(validated_data.provider_type)
            default_enable_format_conversion = _should_enable_format_conversion_by_default(pt)
            provider_config, _ = _merge_claude_code_advanced_config(
                provider_type=pt,
                provider_config=validated_data.config,
                claude_code_advanced=(
                    validated_data.claude_code_advanced.model_dump(exclude_none=True)
                    if validated_data.claude_code_advanced is not None
                    else None
                ),
                claude_advanced_in_payload=validated_data.claude_code_advanced is not None,
            )
            provider_config, _pool_changed = _merge_pool_advanced_config(
                provider_config=provider_config,
                pool_advanced=(
                    validated_data.pool_advanced.model_dump(exclude_none=True)
                    if validated_data.pool_advanced is not None
                    else None
                ),
                pool_advanced_in_payload=validated_data.pool_advanced is not None,
            )
            provider_config, _ = _merge_failover_rules_config(
                provider_config=provider_config,
                failover_rules=(
                    validated_data.failover_rules.model_dump()
                    if validated_data.failover_rules is not None
                    else None
                ),
                failover_rules_in_payload=validated_data.failover_rules is not None,
            )

            current_min_priority = db.query(func.min(Provider.provider_priority)).scalar()
            target_priority, needs_shift = _resolve_new_provider_priority(
                current_min_priority=current_min_priority,
                requested_priority=validated_data.provider_priority,
            )
            if needs_shift:
                db.query(Provider).filter(
                    Provider.provider_priority.isnot(None),
                    Provider.provider_priority >= target_priority,
                ).update(
                    {Provider.provider_priority: Provider.provider_priority + 1},
                    synchronize_session=False,
                )

            # 创建 Provider 对象
            provider = Provider(
                name=validated_data.name,
                provider_type=pt,
                description=validated_data.description,
                website=validated_data.website,
                billing_type=billing_type,
                monthly_quota_usd=validated_data.monthly_quota_usd,
                quota_reset_day=validated_data.quota_reset_day,
                quota_last_reset_at=validated_data.quota_last_reset_at,
                quota_expires_at=validated_data.quota_expires_at,
                provider_priority=target_priority,
                keep_priority_on_conversion=validated_data.keep_priority_on_conversion,
                is_active=validated_data.is_active,
                concurrent_limit=validated_data.concurrent_limit,
                max_retries=validated_data.max_retries,
                proxy=validated_data.proxy.model_dump() if validated_data.proxy else None,
                # 超时配置
                stream_first_byte_timeout=validated_data.stream_first_byte_timeout,
                request_timeout=validated_data.request_timeout,
                config=provider_config or None,
                # 有 envelope 的反代类型默认开启格式转换
                enable_format_conversion=default_enable_format_conversion,
            )

            db.add(provider)
            db.flush()  # flush 获取 ID，但不提交，保持在同一事务中

            # 固定类型 Provider：自动创建并锁定预置 Endpoints（同一事务）
            template = _get_fixed_provider_template(provider.provider_type)
            if template:
                from src.core.api_format.metadata import get_default_body_rules_for_endpoint

                now = datetime.now(timezone.utc)
                for sig in template.endpoint_signatures:
                    endpoint_config: dict[str, str] | None = None
                    if provider.provider_type == ProviderType.CODEX.value and sig == "openai:cli":
                        endpoint_config = {"upstream_stream_policy": "force_stream"}
                    # 获取 provider-scoped 默认 body rules
                    default_body_rules = (
                        get_default_body_rules_for_endpoint(
                            sig, provider_type=provider.provider_type
                        )
                        or None
                    )
                    endpoint = ProviderEndpoint(
                        id=str(uuid.uuid4()),
                        provider_id=provider.id,
                        api_format=sig,
                        api_family=sig.split(":", 1)[0],
                        endpoint_kind=sig.split(":", 1)[1],
                        base_url=template.api_base_url,
                        custom_path=None,
                        header_rules=None,
                        body_rules=default_body_rules,
                        max_retries=provider.max_retries or 2,
                        is_active=True,
                        config=endpoint_config,
                        proxy=None,
                        format_acceptance_config=None,
                        created_at=now,
                        updated_at=now,
                    )
                    db.add(endpoint)

            db.commit()
            db.refresh(provider)

            # 清除 /v1/models 列表缓存
            await invalidate_models_list_cache()

            context.add_audit_metadata(
                action="create_provider",
                provider_id=provider.id,
                provider_name=provider.name,
                billing_type=provider.billing_type.value if provider.billing_type else None,
                is_active=provider.is_active,
                provider_priority=provider.provider_priority,
            )

            return {
                "id": provider.id,
                "name": provider.name,
                "message": "提供商创建成功",
            }
        except InvalidRequestException:
            db.rollback()
            raise
        except Exception:
            db.rollback()
            raise


class AdminUpdateProviderAdapter(AdminApiAdapter):
    def __init__(self, provider_id: str):
        self.provider_id = provider_id

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

        # 查找 Provider
        provider = db.query(Provider).filter(Provider.id == self.provider_id).first()
        if not provider:
            raise NotFoundException("提供商不存在", "provider")

        try:
            # 使用 Pydantic 模型进行验证（自动进行 SQL 注入、XSS、SSRF 检测）
            validated_data = UpdateProviderRequest.model_validate(payload)
        except ValidationError as exc:
            # 将 Pydantic 验证错误转换为友好的错误信息
            errors = []
            for error in exc.errors():
                field = " -> ".join(str(x) for x in error["loc"])
                errors.append(f"{field}: {error['msg']}")
            raise InvalidRequestException("输入验证失败: " + "; ".join(errors))

        try:
            # 更新字段（只更新非 None 的字段）
            update_data = validated_data.model_dump(exclude_unset=True)
            config_in_payload = "config" in update_data
            claude_advanced_in_payload = "claude_code_advanced" in update_data
            pool_advanced_in_payload = "pool_advanced" in update_data
            failover_rules_in_payload = "failover_rules" in update_data
            provider_config = (
                dict(update_data.pop("config") or {})
                if config_in_payload
                else dict(provider.config or {})
            )
            claude_advanced = (
                update_data.pop("claude_code_advanced") if claude_advanced_in_payload else None
            )
            pool_advanced = update_data.pop("pool_advanced") if pool_advanced_in_payload else None
            failover_rules = (
                update_data.pop("failover_rules") if failover_rules_in_payload else None
            )
            target_provider_type = (
                update_data.get("provider_type")
                or getattr(provider, "provider_type", None)
                or "custom"
            )

            provider_config, config_changed_by_claude = _merge_claude_code_advanced_config(
                provider_type=target_provider_type,
                provider_config=provider_config,
                claude_code_advanced=claude_advanced,
                claude_advanced_in_payload=claude_advanced_in_payload,
            )
            provider_config, config_changed_by_pool = _merge_pool_advanced_config(
                provider_config=provider_config,
                pool_advanced=pool_advanced,
                pool_advanced_in_payload=pool_advanced_in_payload,
            )
            provider_config, config_changed_by_failover = _merge_failover_rules_config(
                provider_config=provider_config,
                failover_rules=failover_rules,
                failover_rules_in_payload=failover_rules_in_payload,
            )

            config_touched = (
                config_in_payload
                or claude_advanced_in_payload
                or config_changed_by_claude
                or pool_advanced_in_payload
                or config_changed_by_pool
                or failover_rules_in_payload
                or config_changed_by_failover
            )
            if config_touched:
                update_data["config"] = provider_config

            for field, value in update_data.items():
                if field == "billing_type" and value is not None:
                    # billing_type 需要转换为枚举
                    setattr(provider, field, ProviderBillingType(value))
                elif field == "provider_type" and value is not None:
                    setattr(provider, field, value)
                elif field == "proxy" and value is not None:
                    # proxy 需要转换为 dict（如果是 Pydantic 模型）
                    setattr(
                        provider, field, value if isinstance(value, dict) else value.model_dump()
                    )
                else:
                    setattr(provider, field, value)

            provider.updated_at = datetime.now(timezone.utc)
            db.commit()
            db.refresh(provider)

            # 清除 /v1/models 列表缓存（is_active 变更会影响模型可用性）
            await invalidate_models_list_cache()

            # 如果更新了 is_active，清除 GlobalModel 解析缓存
            # Provider 状态变更会影响模型解析结果
            if "is_active" in update_data:
                await ModelCacheService.invalidate_all_resolve_cache()

            # 如果更新了 billing_type，清除缓存
            if "billing_type" in update_data:
                await ProviderCacheService.invalidate_provider_cache(provider.id)
                logger.debug(f"已清除 Provider 缓存: {provider.id}")

            context.add_audit_metadata(
                action="update_provider",
                provider_id=provider.id,
                changed_fields=list(update_data.keys()),
                is_active=provider.is_active,
                provider_priority=provider.provider_priority,
            )

            return _build_provider_summary(db, provider)
        except InvalidRequestException:
            db.rollback()
            raise
        except Exception:
            db.rollback()
            raise


class AdminDeleteProviderAdapter(AdminApiAdapter):
    def __init__(self, provider_id: str):
        self.provider_id = provider_id

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db
        provider = db.query(Provider).filter(Provider.id == self.provider_id).first()
        if not provider:
            raise NotFoundException("提供商不存在", "provider")

        context.add_audit_metadata(
            action="delete_provider",
            provider_id=provider.id,
            provider_name=provider.name,
        )

        task_id = await submit_provider_delete(provider.id)

        provider_was_active = bool(provider.is_active)
        if provider_was_active:
            provider.is_active = False
            db.commit()
            await invalidate_models_list_cache()
            await ModelCacheService.invalidate_all_resolve_cache()
            await ProviderCacheService.invalidate_provider_cache(provider.id)

        context.add_audit_metadata(
            task_id=task_id,
            provider_deactivated=provider_was_active,
        )
        return {
            "task_id": task_id,
            "status": "pending",
            "message": "删除任务已提交，提供商已进入后台删除队列",
        }


class AdminProviderDeleteTaskStatusAdapter(AdminApiAdapter):
    def __init__(self, provider_id: str, task_id: str):
        self.provider_id = provider_id
        self.task_id = task_id

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        from fastapi import HTTPException

        task = await get_provider_delete_task(self.task_id)
        if task is None or task.provider_id != self.provider_id:
            raise HTTPException(status_code=404, detail="Task not found")
        return ProviderDeleteTaskResponse(
            task_id=task.task_id,
            provider_id=task.provider_id,
            status=task.status,
            stage=task.stage,
            total_keys=task.total_keys,
            deleted_keys=task.deleted_keys,
            total_endpoints=task.total_endpoints,
            deleted_endpoints=task.deleted_endpoints,
            message=task.message,
        )


@router.get(
    "/{provider_id}/mapping-preview",
    response_model=ProviderMappingPreviewResponse,
)
async def get_provider_mapping_preview(
    request: Request,
    provider_id: str,
    db: Session = Depends(get_db),
) -> ProviderMappingPreviewResponse:
    """
    获取 Provider 映射预览

    查看该 Provider 的 Key 白名单能够被哪些 GlobalModel 的映射规则匹配。

    **路径参数**:
    - `provider_id`: Provider ID

    **返回字段**:
    - `provider_id`: Provider ID
    - `provider_name`: Provider 名称
    - `keys`: 有白名单配置的 Key 列表，每个包含：
      - `key_id`: Key ID
      - `key_name`: Key 名称
      - `masked_key`: 脱敏的 Key
      - `allowed_models`: Key 的白名单模型列表
      - `matching_global_models`: 匹配到的 GlobalModel 列表
    - `total_keys`: 有白名单配置的 Key 总数
    - `total_matches`: 匹配到的 GlobalModel 总数
    """
    adapter = AdminGetProviderMappingPreviewAdapter(provider_id=provider_id)

    # 添加超时保护，防止复杂匹配导致的 DoS
    try:
        return await asyncio.wait_for(
            pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode),
            timeout=MAPPING_PREVIEW_TIMEOUT_SECONDS,
        )
    except TimeoutError:
        logger.warning(f"映射预览超时: provider_id={provider_id}")
        raise InvalidRequestException("映射预览超时，请简化配置或稍后重试")


class AdminGetProviderMappingPreviewAdapter(AdminApiAdapter):
    """获取 Provider 映射预览"""

    def __init__(self, provider_id: str):
        self.provider_id = provider_id

    @cache_result(
        key_prefix="admin:providers:mapping-preview",
        ttl=CacheTTL.ADMIN_USAGE_RECORDS,
        user_specific=False,
        vary_by=["provider_id"],
    )
    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        db = context.db

        # 获取 Provider
        provider = (
            db.query(Provider)
            .options(load_only(Provider.id, Provider.name))
            .filter(Provider.id == self.provider_id)
            .first()
        )
        if not provider:
            raise NotFoundException("提供商不存在", "provider")

        # 统计截断情况
        truncated_keys = 0
        truncated_models = 0

        # 获取该 Provider 有白名单配置的 Key（只查询需要的字段）
        keys = (
            db.query(
                ProviderAPIKey.id,
                ProviderAPIKey.name,
                ProviderAPIKey.api_key,
                ProviderAPIKey.is_active,
                ProviderAPIKey.allowed_models,
            )
            .filter(
                ProviderAPIKey.provider_id == self.provider_id,
                ProviderAPIKey.allowed_models.isnot(None),
            )
            .limit(MAPPING_PREVIEW_MAX_KEYS + 1)
            .all()
        )

        if len(keys) > MAPPING_PREVIEW_MAX_KEYS:
            keys = keys[:MAPPING_PREVIEW_MAX_KEYS]
            total_keys_with_allowed_models = (
                db.query(func.count(ProviderAPIKey.id))
                .filter(
                    ProviderAPIKey.provider_id == self.provider_id,
                    ProviderAPIKey.allowed_models.isnot(None),
                )
                .scalar()
                or 0
            )
            truncated_keys = total_keys_with_allowed_models - MAPPING_PREVIEW_MAX_KEYS

        # 只查询有 model_mappings 配置的 GlobalModel（使用 SQLAlchemy JSONB 操作符）
        global_models = (
            db.query(
                GlobalModel.id,
                GlobalModel.name,
                GlobalModel.display_name,
                GlobalModel.is_active,
                GlobalModel.config,
            )
            .filter(
                GlobalModel.config.isnot(None),
                GlobalModel.config["model_mappings"].isnot(None),
                func.jsonb_array_length(GlobalModel.config["model_mappings"]) > 0,
            )
            .limit(MAPPING_PREVIEW_MAX_MODELS + 1)
            .all()
        )

        if len(global_models) > MAPPING_PREVIEW_MAX_MODELS:
            global_models = global_models[:MAPPING_PREVIEW_MAX_MODELS]
            total_models_with_mappings = (
                db.query(func.count(GlobalModel.id))
                .filter(
                    GlobalModel.config.isnot(None),
                    GlobalModel.config["model_mappings"].isnot(None),
                    func.jsonb_array_length(GlobalModel.config["model_mappings"]) > 0,
                )
                .scalar()
                or 0
            )
            truncated_models = total_models_with_mappings - MAPPING_PREVIEW_MAX_MODELS

        # 构建有映射配置的 GlobalModel 映射
        models_with_mappings: dict[str, tuple] = {}  # id -> (model_info, mappings)
        for gm in global_models:
            config = gm.config or {}
            mappings = config.get("model_mappings", [])
            if mappings:
                models_with_mappings[gm.id] = (gm, mappings)

        # 如果没有任何带映射的 GlobalModel，直接返回空结果
        if not models_with_mappings:
            return ProviderMappingPreviewResponse(
                provider_id=provider.id,
                provider_name=provider.name,
                keys=[],
                total_keys=0,
                total_matches=0,
                truncated=truncated_keys > 0 or truncated_models > 0,
                truncated_keys=truncated_keys,
                truncated_models=truncated_models,
            ).model_dump()

        key_infos: list[MappingMatchingKey] = []
        total_matches = 0

        # 创建 CryptoService 实例
        from src.core.crypto import CryptoService

        crypto = CryptoService()

        for key in keys:
            allowed_models_list = parse_allowed_models_to_list(key.allowed_models)
            if not allowed_models_list:
                continue

            # 查找匹配的 GlobalModel
            matching_global_models: list[MappingMatchingGlobalModel] = []

            for gm_id, (gm, mappings) in models_with_mappings.items():
                matched_models: list[MappingMatchedModel] = []

                for allowed_model in allowed_models_list:
                    for mapping_pattern in mappings:
                        if match_model_with_pattern(mapping_pattern, allowed_model):
                            matched_models.append(
                                MappingMatchedModel(
                                    allowed_model=allowed_model,
                                    mapping_pattern=mapping_pattern,
                                )
                            )
                            break  # 一个 allowed_model 只需匹配一个映射

                if matched_models:
                    matching_global_models.append(
                        MappingMatchingGlobalModel(
                            global_model_id=gm.id,
                            global_model_name=gm.name,
                            display_name=gm.display_name,
                            is_active=bool(gm.is_active),
                            matched_models=matched_models,
                        )
                    )
                    total_matches += 1

            if matching_global_models:
                # 只有有匹配结果的 key 才做解密脱敏，减少 CPU 开销
                masked_key = "***"
                if key.api_key:
                    try:
                        decrypted_key = crypto.decrypt(key.api_key, silent=True)
                        if len(decrypted_key) > 8:
                            masked_key = f"{decrypted_key[:4]}***{decrypted_key[-4:]}"
                        else:
                            masked_key = f"{decrypted_key[:2]}***"
                    except Exception:
                        pass

                key_infos.append(
                    MappingMatchingKey(
                        key_id=key.id or "",
                        key_name=key.name or "",
                        masked_key=masked_key,
                        is_active=bool(key.is_active),
                        allowed_models=allowed_models_list,
                        matching_global_models=matching_global_models,
                    )
                )

        is_truncated = truncated_keys > 0 or truncated_models > 0

        return ProviderMappingPreviewResponse(
            provider_id=provider.id,
            provider_name=provider.name,
            keys=key_infos,
            total_keys=len(key_infos),
            total_matches=total_matches,
            truncated=is_truncated,
            truncated_keys=truncated_keys,
            truncated_models=truncated_models,
        ).model_dump()


# ========== Claude Code Pool Management ==========


class PoolKeyStatus(BaseModel):
    """Single key's pool status."""

    key_id: str
    key_name: str
    is_active: bool
    cooldown_reason: str | None = None
    cooldown_ttl_seconds: int | None = None
    cost_window_usage: int = 0
    cost_limit: int | None = None
    sticky_sessions: int = 0
    lru_score: float | None = None

    model_config = ConfigDict(from_attributes=True)


class PoolStatusResponse(BaseModel):
    """Pool status for a Provider with pool config."""

    provider_id: str
    provider_name: str
    pool_enabled: bool = False
    total_keys: int = 0
    total_sticky_sessions: int = 0
    keys: list[PoolKeyStatus] = Field(default_factory=list)

    model_config = ConfigDict(from_attributes=True)


@router.get("/{provider_id}/pool-status", response_model=PoolStatusResponse)
async def get_pool_status(
    request: Request,
    provider_id: str,
    db: Session = Depends(get_db),
) -> PoolStatusResponse:
    """获取 Provider 的号池状态。"""
    adapter = AdminProviderPoolStatusAdapter(provider_id=provider_id)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


async def _get_pool_status_response(db: Session, provider_id: str) -> PoolStatusResponse:
    """获取 Provider 的号池状态。"""
    provider = db.query(Provider).filter(Provider.id == provider_id).first()
    if not provider:
        raise NotFoundException("提供商不存在", "provider")

    from src.services.provider.pool import redis_ops as pool_redis
    from src.services.provider.pool.config import parse_pool_config

    pcfg = parse_pool_config(provider.config)
    if pcfg is None:
        return PoolStatusResponse(
            provider_id=provider.id,
            provider_name=provider.name,
            pool_enabled=False,
        )

    keys = db.query(ProviderAPIKey).filter(ProviderAPIKey.provider_id == provider_id).all()

    key_ids = [str(k.id) for k in keys]
    pid = str(provider.id)

    import asyncio

    # Batch fetch pool state (parallel)
    lru_coro = (
        pool_redis.get_lru_scores(pid, key_ids) if pcfg.lru_enabled else asyncio.sleep(0, result={})
    )
    cooldowns, cooldown_ttls, lru_scores, cost_totals, total_sticky = await asyncio.gather(
        pool_redis.batch_get_cooldowns(pid, key_ids),
        pool_redis.batch_get_cooldown_ttls(pid, key_ids),
        lru_coro,
        pool_redis.batch_get_cost_totals(pid, key_ids, pcfg.cost_window_seconds),
        pool_redis.get_sticky_session_count(pid),
    )

    # Sticky count per key requires SCAN+MGET; batch with gather.
    sticky_counts: dict[str, int] = {}
    if key_ids:
        counts = await asyncio.gather(
            *(pool_redis.get_key_sticky_count(pid, kid) for kid in key_ids)
        )
        sticky_counts = dict(zip(key_ids, counts))

    key_statuses: list[PoolKeyStatus] = []
    for k in keys:
        kid = str(k.id)
        cd_reason = cooldowns.get(kid)

        key_statuses.append(
            PoolKeyStatus(
                key_id=kid,
                key_name=k.name or "",
                is_active=bool(k.is_active),
                cooldown_reason=cd_reason,
                cooldown_ttl_seconds=cooldown_ttls.get(kid) if cd_reason else None,
                cost_window_usage=cost_totals.get(kid, 0),
                cost_limit=pcfg.cost_limit_per_key_tokens,
                sticky_sessions=sticky_counts.get(kid, 0),
                lru_score=lru_scores.get(kid),
            )
        )

    return PoolStatusResponse(
        provider_id=provider.id,
        provider_name=provider.name,
        pool_enabled=True,
        total_keys=len(keys),
        total_sticky_sessions=total_sticky,
        keys=key_statuses,
    )


@router.post("/{provider_id}/pool/clear-cooldown/{key_id}")
async def clear_pool_cooldown(
    request: Request,
    provider_id: str,
    key_id: str,
    db: Session = Depends(get_db),
) -> dict[str, str]:
    """手动清除指定 Key 的号池冷却状态。"""
    adapter = AdminProviderClearPoolCooldownAdapter(provider_id=provider_id, key_id=key_id)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


async def _clear_pool_cooldown_response(db: Session, provider_id: str, key_id: str) -> dict[str, str]:
    """手动清除指定 Key 的号池冷却状态。"""
    provider = db.query(Provider).filter(Provider.id == provider_id).first()
    if not provider:
        raise NotFoundException("提供商不存在", "provider")

    key = (
        db.query(ProviderAPIKey)
        .filter(ProviderAPIKey.id == key_id, ProviderAPIKey.provider_id == provider_id)
        .first()
    )
    if not key:
        raise NotFoundException("密钥不存在", "key")

    from src.services.provider.pool import redis_ops as pool_redis

    await pool_redis.clear_cooldown(str(provider.id), str(key.id))
    return {"message": f"已清除 Key {key.name or key_id} 的冷却状态"}


@router.post("/{provider_id}/pool/reset-cost/{key_id}")
async def reset_pool_cost(
    request: Request,
    provider_id: str,
    key_id: str,
    db: Session = Depends(get_db),
) -> dict[str, str]:
    """重置指定 Key 的号池成本窗口。"""
    adapter = AdminProviderResetPoolCostAdapter(provider_id=provider_id, key_id=key_id)
    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)


async def _reset_pool_cost_response(db: Session, provider_id: str, key_id: str) -> dict[str, str]:
    """重置指定 Key 的号池成本窗口。"""
    provider = db.query(Provider).filter(Provider.id == provider_id).first()
    if not provider:
        raise NotFoundException("提供商不存在", "provider")

    key = (
        db.query(ProviderAPIKey)
        .filter(ProviderAPIKey.id == key_id, ProviderAPIKey.provider_id == provider_id)
        .first()
    )
    if not key:
        raise NotFoundException("密钥不存在", "key")

    from src.services.provider.pool import redis_ops as pool_redis

    await pool_redis.clear_cost(str(provider.id), str(key.id))
    return {"message": f"已重置 Key {key.name or key_id} 的成本窗口"}


class AdminProviderPoolStatusAdapter(AdminApiAdapter):
    def __init__(self, provider_id: str):
        self.provider_id = provider_id

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


class AdminProviderClearPoolCooldownAdapter(AdminApiAdapter):
    def __init__(self, provider_id: str, key_id: str):
        self.provider_id = provider_id
        self.key_id = key_id

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        return await _clear_pool_cooldown_response(context.db, self.provider_id, self.key_id)


class AdminProviderResetPoolCostAdapter(AdminApiAdapter):
    def __init__(self, provider_id: str, key_id: str):
        self.provider_id = provider_id
        self.key_id = key_id

    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
        return await _reset_pool_cost_response(context.db, self.provider_id, self.key_id)