Aether/_deprecated_py_src/models/endpoint_models.py

"""
ProviderEndpoint 相关的 API 模型定义
"""

from __future__ import annotations

import re
from datetime import datetime
from typing import Any, Literal

from pydantic import BaseModel, ConfigDict, Field, field_validator

from src.models.admin_requests import (
    ClaudeCodeAdvancedConfig,
    FailoverRulesConfig,
    PoolAdvancedConfig,
    ProxyConfig,
)
from src.models.status_snapshot import ProviderKeyStatusSnapshotResponse

# ========== Header Rule 类型定义 ==========
# 请求头规则支持三种操作：
# - set: 设置/覆盖请求头 {"action": "set", "key": "X-Custom", "value": "val"}
# - drop: 删除请求头 {"action": "drop", "key": "X-Unwanted"}
# - rename: 重命名请求头 {"action": "rename", "from": "X-Old", "to": "X-New"}
# 实际验证在 headers.py 的 apply_rules 中处理
HeaderRule = dict[str, Any]

_HEADER_RULE_ACTIONS: frozenset[str] = frozenset({"set", "drop", "rename"})


# ========== Body Rule 类型定义 ==========
# 请求体规则支持六种操作：
# - set: 设置/覆盖字段 {"action": "set", "path": "metadata", "value": {"custom": "val"}}
#     value 中的字符串 {{$original}} 会被替换为该路径的原值（完全匹配时保留类型）
# - drop: 删除字段 {"action": "drop", "path": "unwanted_field"}
# - rename: 重命名字段 {"action": "rename", "from": "old_key", "to": "new_key"}
# - append: 向数组追加元素 {"action": "append", "path": "messages", "value": {...}}
# - insert: 在数组指定位置插入 {"action": "insert", "path": "messages", "index": 0, "value": {...}}
# - regex_replace: 正则替换字符串值 {"action": "regex_replace", "path": "...", "pattern": "...", "replacement": "..."}
# - name_style: 转换命名风格 {"action": "name_style", "path": "tools[*].name", "style": "camelCase"}
# 路径语法支持数组索引：messages[0].content, data[-1], matrix[0][1]
# 路径语法支持通配符：tools[*].name（遍历所有元素）, tools[0-4].name（遍历范围）
# 运行时处理在 request_builder.py 的 apply_body_rules 中；结构校验见 _validate_body_rules
BodyRule = dict[str, Any]

# body_rules 允许的 action 集合
_BODY_RULE_ACTIONS: frozenset[str] = frozenset(
    {"set", "drop", "rename", "append", "insert", "regex_replace", "name_style"}
)

# name_style 允许的风格值
_NAME_STYLE_VALUES: frozenset[str] = frozenset(
    {"snake_case", "camelCase", "PascalCase", "kebab-case", "capitalize"}
)

# regex_replace 允许的 flags 字符
_REGEX_FLAG_CHARS: frozenset[str] = frozenset({"i", "m", "s"})

# condition 允许的操作符
_CONDITION_OPS: frozenset[str] = frozenset(
    {
        "eq",
        "neq",
        "gt",
        "lt",
        "gte",
        "lte",
        "starts_with",
        "ends_with",
        "contains",
        "matches",
        "exists",
        "not_exists",
        "in",
        "type_is",
    }
)

# type_is 允许的类型值
_TYPE_IS_VALUES: frozenset[str] = frozenset(
    {"string", "number", "boolean", "array", "object", "null"}
)

_CONDITION_SOURCES: frozenset[str] = frozenset({"current", "original"})


def parse_re_flags(flags_str: str) -> int:
    """将 flags 字符串（i/m/s）转换为 re 标志位。

    供 endpoint_models 校验和 request_builder 运行时共用。
    """
    result = 0
    for f in flags_str:
        if f == "i":
            result |= re.IGNORECASE
        elif f == "m":
            result |= re.MULTILINE
        elif f == "s":
            result |= re.DOTALL
    return result


def _validate_condition(condition: Any, rule_label: str) -> None:
    """校验单条规则的 condition 结构。"""
    if not isinstance(condition, dict):
        raise ValueError(f"{rule_label}: condition 必须是 JSON 对象")

    has_all = "all" in condition
    has_any = "any" in condition
    if has_all or has_any:
        if has_all and has_any:
            raise ValueError(f"{rule_label}: condition 不能同时包含 all 和 any")

        key = "all" if has_all else "any"
        children = condition.get(key)
        if not isinstance(children, list) or not children:
            raise ValueError(f"{rule_label}: condition.{key} 必须是非空数组")

        for idx, child in enumerate(children):
            _validate_condition(child, f"{rule_label}: condition.{key}[{idx}]")
        return

    source = condition.get("source", "current")
    if not isinstance(source, str) or source not in _CONDITION_SOURCES:
        raise ValueError(
            f"{rule_label}: condition.source 必须是 {sorted(_CONDITION_SOURCES)} 之一，"
            f"当前值: {source!r}"
        )

    op = condition.get("op")
    if not isinstance(op, str) or op not in _CONDITION_OPS:
        raise ValueError(
            f"{rule_label}: condition.op 必须是 {sorted(_CONDITION_OPS)} 之一，" f"当前值: {op!r}"
        )

    path = condition.get("path")
    if not isinstance(path, str) or not path.strip():
        raise ValueError(f"{rule_label}: condition 必须提供非空 path")

    # exists / not_exists 不需要 value
    if op in ("exists", "not_exists"):
        return

    value = condition.get("value")

    # 数值操作符校验
    if op in ("gt", "lt", "gte", "lte"):
        if not isinstance(value, (int, float)) or isinstance(value, bool):
            raise ValueError(f"{rule_label}: condition op={op!r} 的 value 必须为数值")

    # matches 正则校验
    if op == "matches":
        if not isinstance(value, str) or not value:
            raise ValueError(f"{rule_label}: condition op=matches 的 value 必须为非空字符串")
        try:
            re.compile(value)
        except re.error as e:
            raise ValueError(f"{rule_label}: condition op=matches 的 value 不是合法正则: {e}")

    # in 校验
    if op == "in":
        if not isinstance(value, list):
            raise ValueError(f"{rule_label}: condition op=in 的 value 必须为数组")

    # type_is 校验
    if op == "type_is":
        if not isinstance(value, str) or value not in _TYPE_IS_VALUES:
            raise ValueError(
                f"{rule_label}: condition op=type_is 的 value 必须是 "
                f"{sorted(_TYPE_IS_VALUES)} 之一"
            )

    # starts_with / ends_with / contains 对 value 做字符串校验
    if op in ("starts_with", "ends_with"):
        if not isinstance(value, str):
            raise ValueError(f"{rule_label}: condition op={op!r} 的 value 必须为字符串")


def _validate_header_rules(rules: list[HeaderRule]) -> list[HeaderRule]:
    """校验 header_rules 列表的结构和 condition 合法性。"""
    for idx, rule in enumerate(rules):
        if not isinstance(rule, dict):
            raise ValueError(f"header_rules[{idx}]: 规则必须是 JSON 对象")

        action = rule.get("action")
        if not isinstance(action, str) or action.strip().lower() not in _HEADER_RULE_ACTIONS:
            raise ValueError(
                f"header_rules[{idx}]: action 必须是 {sorted(_HEADER_RULE_ACTIONS)} 之一，"
                f"当前值: {action!r}"
            )
        action = action.strip().lower()

        if action == "set":
            key = rule.get("key")
            value = rule.get("value")
            if not isinstance(key, str) or not key.strip():
                raise ValueError(f"header_rules[{idx}]: set 必须提供非空 key")
            if not isinstance(value, str):
                raise ValueError(f"header_rules[{idx}]: set 的 value 必须为字符串")

        if action == "drop":
            key = rule.get("key")
            if not isinstance(key, str) or not key.strip():
                raise ValueError(f"header_rules[{idx}]: drop 必须提供非空 key")

        if action == "rename":
            from_val = rule.get("from")
            to_val = rule.get("to")
            if not isinstance(from_val, str) or not from_val.strip():
                raise ValueError(f"header_rules[{idx}]: rename 必须提供非空 from")
            if not isinstance(to_val, str) or not to_val.strip():
                raise ValueError(f"header_rules[{idx}]: rename 必须提供非空 to")

        condition = rule.get("condition")
        if condition is not None:
            _validate_condition(condition, f"header_rules[{idx}]")

    return rules


def _validate_body_rules(rules: list[BodyRule]) -> list[BodyRule]:
    """校验 body_rules 列表的结构和正则合法性。

    校验项：
    - 每条规则必须是 dict 且包含合法 action
    - 需要 path 的 action（set/drop/append/insert/regex_replace）必须提供非空 path 字符串
    - rename 必须提供非空 from / to 字符串
    - insert 的 index 必须为整数
    - regex_replace 的 pattern 必须能通过 re.compile 编译，flags 仅允许 i/m/s
    """
    for idx, rule in enumerate(rules):
        if not isinstance(rule, dict):
            raise ValueError(f"body_rules[{idx}]: 规则必须是 JSON 对象")

        action = rule.get("action")
        if not isinstance(action, str) or action.strip().lower() not in _BODY_RULE_ACTIONS:
            raise ValueError(
                f"body_rules[{idx}]: action 必须是 {sorted(_BODY_RULE_ACTIONS)} 之一，"
                f"当前值: {action!r}"
            )
        action = action.strip().lower()

        # ---------- path 校验 ----------
        if action in {"set", "drop", "append", "insert", "regex_replace", "name_style"}:
            path = rule.get("path")
            if not isinstance(path, str) or not path.strip():
                raise ValueError(f"body_rules[{idx}]: action={action!r} 必须提供非空 path")

        # ---------- rename 校验 ----------
        if action == "rename":
            from_val = rule.get("from")
            to_val = rule.get("to")
            if not isinstance(from_val, str) or not from_val.strip():
                raise ValueError(f"body_rules[{idx}]: rename 必须提供非空 from")
            if not isinstance(to_val, str) or not to_val.strip():
                raise ValueError(f"body_rules[{idx}]: rename 必须提供非空 to")

        # ---------- insert 校验 ----------
        if action == "insert":
            index = rule.get("index")
            if not isinstance(index, int) or isinstance(index, bool):
                raise ValueError(f"body_rules[{idx}]: insert 的 index 必须为整数")

        # ---------- regex_replace 校验 ----------
        if action == "regex_replace":
            pattern = rule.get("pattern")
            if not isinstance(pattern, str) or not pattern:
                raise ValueError(f"body_rules[{idx}]: regex_replace 必须提供非空 pattern 字符串")

            replacement = rule.get("replacement", "")
            if not isinstance(replacement, str):
                raise ValueError(f"body_rules[{idx}]: regex_replace 的 replacement 必须为字符串")

            # 校验 flags
            flags_str = rule.get("flags", "")
            re_flags = 0
            if isinstance(flags_str, str) and flags_str:
                invalid_flags = set(flags_str) - _REGEX_FLAG_CHARS
                if invalid_flags:
                    raise ValueError(
                        f"body_rules[{idx}]: regex_replace 的 flags 仅允许 "
                        f"{''.join(sorted(_REGEX_FLAG_CHARS))}，"
                        f"非法字符: {''.join(sorted(invalid_flags))}"
                    )
                re_flags = parse_re_flags(flags_str)

            # 尝试编译正则，捕获语法错误
            try:
                re.compile(pattern, re_flags)
            except re.error as e:
                raise ValueError(
                    f"body_rules[{idx}]: regex_replace 的 pattern 不是合法正则表达式: {e}"
                )

            # 校验 count
            count = rule.get("count", 0)
            if not isinstance(count, int) or count < 0:
                raise ValueError(f"body_rules[{idx}]: regex_replace 的 count 必须为非负整数")

        # ---------- name_style 校验 ----------
        if action == "name_style":
            style = rule.get("style")
            if not isinstance(style, str) or style not in _NAME_STYLE_VALUES:
                raise ValueError(
                    f"body_rules[{idx}]: name_style 的 style 必须是 "
                    f"{sorted(_NAME_STYLE_VALUES)} 之一，当前值: {style!r}"
                )

        # ---------- condition 校验 ----------
        condition = rule.get("condition")
        if condition is not None:
            _validate_condition(condition, f"body_rules[{idx}]")

    return rules


# ========== ProviderEndpoint CRUD ==========


class ProviderEndpointCreate(BaseModel):
    """创建 Endpoint 请求"""

    provider_id: str = Field(..., description="Provider ID")
    api_format: str = Field(
        ...,
        description=(
            "Endpoint signature（例如: claude:chat/claude:cli, openai:chat/openai:cli/openai:compact/openai:video, gemini:chat/gemini:cli/gemini:video）"
        ),
    )
    base_url: str = Field(..., min_length=1, max_length=500, description="API 基础 URL")
    custom_path: str | None = Field(default=None, max_length=200, description="自定义请求路径")

    # 请求头配置
    header_rules: list[HeaderRule] | None = Field(
        default=None,
        description="请求头规则列表，支持 set/drop/rename 操作",
    )

    # 请求体配置
    body_rules: list[BodyRule] | None = Field(
        default=None,
        description="请求体规则列表，支持 set/drop/rename/append/insert/regex_replace 操作",
    )

    max_retries: int = Field(default=2, ge=0, le=999, description="最大重试次数")

    # 额外配置
    config: dict[str, Any] | None = Field(default=None, description="额外配置（JSON）")

    # 代理配置
    proxy: ProxyConfig | None = Field(default=None, description="代理配置")

    # 格式转换配置
    format_acceptance_config: dict[str, Any] | None = Field(
        default=None,
        description="格式接受策略配置（跨格式转换开关/白黑名单等）",
    )

    @field_validator("api_format")
    @classmethod
    def validate_api_format(cls, v: str) -> str:
        """验证 API 格式"""
        from src.core.api_format import (
            list_endpoint_definitions,
            resolve_endpoint_definition,
        )
        from src.core.api_format.signature import normalize_signature_key

        normalized = normalize_signature_key(v)
        if resolve_endpoint_definition(normalized) is None:
            allowed = [d.signature_key for d in list_endpoint_definitions()]
            raise ValueError(f"api_format 必须是以下之一: {allowed}")
        return normalized

    @field_validator("base_url")
    @classmethod
    def validate_base_url(cls, v: str) -> str:
        if not re.match(r"^https?://", v, re.IGNORECASE):
            raise ValueError("URL 必须以 http:// 或 https:// 开头")

        return v.rstrip("/")  # 移除末尾斜杠

    @field_validator("body_rules")
    @classmethod
    def validate_body_rules(cls, v: list[BodyRule] | None) -> list[BodyRule] | None:
        """校验 body_rules 结构和正则合法性"""
        if v is None:
            return v
        return _validate_body_rules(v)

    @field_validator("header_rules")
    @classmethod
    def validate_header_rules(cls, v: list[HeaderRule] | None) -> list[HeaderRule] | None:
        """校验 header_rules 结构和 condition 合法性"""
        if v is None:
            return v
        return _validate_header_rules(v)


class ProviderEndpointUpdate(BaseModel):
    """更新 Endpoint 请求"""

    base_url: str | None = Field(
        default=None, min_length=1, max_length=500, description="API 基础 URL"
    )
    custom_path: str | None = Field(default=None, max_length=200, description="自定义请求路径")

    # 请求头配置
    header_rules: list[HeaderRule] | None = Field(
        default=None,
        description="请求头规则列表，支持 set/drop/rename 操作",
    )

    # 请求体配置
    body_rules: list[BodyRule] | None = Field(
        default=None,
        description="请求体规则列表，支持 set/drop/rename/append/insert/regex_replace 操作",
    )

    max_retries: int | None = Field(default=None, ge=0, le=999, description="最大重试次数")
    is_active: bool | None = Field(default=None, description="是否启用")
    config: dict[str, Any] | None = Field(default=None, description="额外配置")
    proxy: ProxyConfig | None = Field(default=None, description="代理配置")

    # 格式转换配置
    format_acceptance_config: dict[str, Any] | None = Field(
        default=None,
        description="格式接受策略配置（跨格式转换开关/白黑名单等）",
    )

    @field_validator("base_url")
    @classmethod
    def validate_base_url(cls, v: str | None) -> str | None:
        """验证 API URL"""
        if v is None:
            return v

        if not re.match(r"^https?://", v, re.IGNORECASE):
            raise ValueError("URL 必须以 http:// 或 https:// 开头")

        return v.rstrip("/")  # 移除末尾斜杠

    @field_validator("body_rules")
    @classmethod
    def validate_body_rules(cls, v: list[BodyRule] | None) -> list[BodyRule] | None:
        """校验 body_rules 结构和正则合法性"""
        if v is None:
            return v
        return _validate_body_rules(v)

    @field_validator("header_rules")
    @classmethod
    def validate_header_rules(cls, v: list[HeaderRule] | None) -> list[HeaderRule] | None:
        """校验 header_rules 结构和 condition 合法性"""
        if v is None:
            return v
        return _validate_header_rules(v)


class ProviderEndpointResponse(BaseModel):
    """Endpoint 响应"""

    id: str
    provider_id: str
    provider_name: str  # 冗余字段，方便前端显示

    # API 配置
    api_format: str
    base_url: str
    custom_path: str | None = None

    # 请求头配置
    header_rules: list[HeaderRule] | None = Field(default=None, description="请求头规则列表")

    # 请求体配置
    body_rules: list[BodyRule] | None = Field(default=None, description="请求体规则列表")

    max_retries: int

    # 状态
    is_active: bool

    # 额外配置
    config: dict[str, Any] | None = None

    # 代理配置（响应中密码已脱敏）
    proxy: dict[str, Any] | None = Field(default=None, description="代理配置（密码已脱敏）")

    # 格式转换配置
    format_acceptance_config: dict[str, Any] | None = Field(
        default=None,
        description="格式接受策略配置（跨格式转换开关/白黑名单等）",
    )

    # 统计（从 Keys 聚合）
    total_keys: int = Field(default=0, description="总 Key 数量")
    active_keys: int = Field(default=0, description="活跃 Key 数量")

    # 时间戳
    created_at: datetime
    updated_at: datetime

    model_config = ConfigDict(from_attributes=True)


# ========== ProviderAPIKey 相关 ==========


class EndpointAPIKeyCreate(BaseModel):
    """为 Provider 添加 API Key"""

    provider_id: str | None = Field(default=None, description="Provider ID（从 URL 获取）")
    api_formats: list[str] | None = Field(
        default=None,
        min_length=1,
        description="支持的 endpoint signature 列表（必填，路由层校验）",
    )

    api_key: str = Field(
        default="",
        max_length=10000,
        description="API Key（标准认证时必填，将自动加密）",
    )
    auth_type: Literal["api_key", "service_account", "oauth"] = Field(
        default="api_key",
        description="认证类型：api_key（标准 API Key）/ service_account（GCP Service Account）/ oauth（OAuth access_token）",
    )
    auth_config: dict[str, Any] | None = Field(
        default=None,
        description=(
            "认证配置（JSON）：service_account 时存储完整 Service Account JSON；"
            "oauth 时存储 token/refresh/expires_at 等（后端加密存储，不在响应中返回）"
        ),
    )
    name: str = Field(..., min_length=1, max_length=100, description="密钥名称（必填，用于识别）")

    # 成本计算
    rate_multipliers: dict[str, float] | None = Field(
        default=None,
        description="按 endpoint signature 的成本倍率，如 {'claude:cli': 1.0, 'openai:cli': 0.8}",
    )

    # 优先级和限制（数字越小越优先）
    internal_priority: int = Field(default=50, description="Key 内部优先级（提供商优先模式）")
    # rpm_limit: NULL=自适应模式（系统自动学习），数字=固定限制模式
    rpm_limit: int | None = Field(
        default=None, ge=1, le=10000, description="RPM 限制（NULL=自适应模式）"
    )
    allowed_models: list[str] | None = Field(
        default=None,
        description="允许使用的模型列表（null=不限制）",
    )

    # 能力标签
    capabilities: dict[str, bool] | None = Field(
        default=None,
        description="Key 能力标签，如 {'cache_1h': true, 'context_1m': true}",
    )

    # 缓存与熔断配置
    cache_ttl_minutes: int = Field(
        default=5, ge=0, le=60, description="缓存 TTL（分钟），0=禁用，默认5分钟"
    )
    max_probe_interval_minutes: int = Field(
        default=32, ge=0, le=32, description="熔断探测间隔（分钟），范围 0-32"
    )

    # 备注
    note: str | None = Field(default=None, max_length=500, description="备注说明（可选）")

    # 自动获取模型
    auto_fetch_models: bool = Field(
        default=False,
        description="是否启用自动获取模型（启用后系统定时从上游 API 获取可用模型）",
    )

    # 锁定的模型列表
    locked_models: list[str] | None = Field(
        default=None, description="被锁定的模型列表（刷新时不会被删除）"
    )

    # 模型过滤规则（仅当 auto_fetch_models=True 时生效）
    model_include_patterns: list[str] | None = Field(
        default=None, description="模型包含规则（支持 * 和 ? 通配符），空表示包含所有"
    )
    model_exclude_patterns: list[str] | None = Field(
        default=None, description="模型排除规则（支持 * 和 ? 通配符），空表示不排除"
    )

    @field_validator("api_formats")
    @classmethod
    def validate_api_formats(cls, v: list[str] | None) -> list[str] | None:
        """验证 API 格式列表"""
        if v is None:
            return v

        from src.core.api_format import (
            list_endpoint_definitions,
            resolve_endpoint_definition,
        )
        from src.core.api_format.signature import normalize_signature_key

        allowed = [d.signature_key for d in list_endpoint_definitions()]
        validated: list[str] = []
        seen: set[str] = set()
        for fmt in v:
            normalized = normalize_signature_key(fmt)
            if resolve_endpoint_definition(normalized) is None:
                raise ValueError(f"api_formats 必须是以下之一: {allowed}，当前值: {fmt}")
            if normalized in seen:
                continue  # 静默去重
            seen.add(normalized)
            validated.append(normalized)
        return validated

    @field_validator("allowed_models")
    @classmethod
    def validate_allowed_models(cls, v: list[str] | None) -> list[str] | None:
        """
        规范化 allowed_models：去空、去重、保留顺序
        """
        if v is None:
            return v

        if not isinstance(v, list):
            raise ValueError("allowed_models 必须是列表")

        cleaned: list[str] = []
        seen: set[str] = set()
        for item in v:
            if not isinstance(item, str):
                raise ValueError("allowed_models 列表元素必须为字符串")
            name = item.strip()
            if not name or name in seen:
                continue
            seen.add(name)
            cleaned.append(name)
        return cleaned

    @field_validator("api_key")
    @classmethod
    def validate_api_key(cls, v: str) -> str:
        """验证 API Key 基本格式"""
        # 移除首尾空白（长度校验由 Field max_length 处理）
        return v.strip()

    @field_validator("name")
    @classmethod
    def validate_name(cls, v: str) -> str:
        """验证名称（防止 XSS）"""
        # 移除危险的 HTML 标签
        v = re.sub(r"<script.*?</script>", "", v, flags=re.IGNORECASE | re.DOTALL)
        v = re.sub(r"<iframe.*?</iframe>", "", v, flags=re.IGNORECASE | re.DOTALL)
        v = re.sub(r"javascript:", "", v, flags=re.IGNORECASE)
        v = re.sub(r"on\w+\s*=", "", v, flags=re.IGNORECASE)
        return v.strip()

    @field_validator("note")
    @classmethod
    def validate_note(cls, v: str | None) -> str | None:
        """验证备注（防止 XSS）"""
        if v is None:
            return v
        # 移除危险的 HTML 标签
        v = re.sub(r"<script.*?</script>", "", v, flags=re.IGNORECASE | re.DOTALL)
        v = re.sub(r"<iframe.*?</iframe>", "", v, flags=re.IGNORECASE | re.DOTALL)
        v = re.sub(r"javascript:", "", v, flags=re.IGNORECASE)
        v = re.sub(r"on\w+\s*=", "", v, flags=re.IGNORECASE)
        return v.strip()


class EndpointAPIKeyUpdate(BaseModel):
    """更新 Endpoint API Key"""

    api_formats: list[str] | None = Field(
        default=None, min_length=1, description="支持的 API 格式列表"
    )

    api_key: str | None = Field(
        default=None,
        max_length=10000,
        description="API Key（标准认证时使用，将自动加密）",
    )
    auth_type: Literal["api_key", "service_account", "oauth"] | None = Field(
        default=None,
        description="认证类型：api_key（标准 API Key）/ service_account（GCP Service Account）/ oauth（OAuth access_token）",
    )
    auth_config: dict[str, Any] | None = Field(
        default=None,
        description=(
            "认证配置（JSON）：service_account 时存储完整 Service Account JSON；"
            "oauth 时存储 token/refresh/expires_at 等（后端加密存储，不在响应中返回）"
        ),
    )
    name: str | None = Field(default=None, min_length=1, max_length=100, description="密钥名称")
    rate_multipliers: dict[str, float] | None = Field(
        default=None,
        description="按 endpoint signature 的成本倍率，如 {'claude:cli': 1.0, 'openai:cli': 0.8}",
    )
    internal_priority: int | None = Field(
        default=None, description="Key 内部优先级（提供商优先模式，数字越小越优先）"
    )
    global_priority_by_format: dict[str, int] | None = Field(
        default=None,
        description="按 endpoint signature 的全局优先级，如 {'claude:chat': 1, 'claude:cli': 2}",
    )
    # rpm_limit: 使用特殊标记区分"未提供"和"设置为 null（自适应模式）"
    # - 不提供字段：不更新
    # - 提供 null：切换为自适应模式
    # - 提供数字：设置固定 RPM 限制
    rpm_limit: int | None = Field(
        default=None, ge=1, le=10000, description="RPM 限制（null=自适应模式）"
    )
    allowed_models: list[str] | None = Field(
        default=None,
        description="允许使用的模型列表（null=不限制）",
    )
    capabilities: dict[str, bool] | None = Field(
        default=None,
        description="Key 能力标签，如 {'cache_1h': true, 'context_1m': true}",
    )
    cache_ttl_minutes: int | None = Field(
        default=None, ge=0, le=60, description="缓存 TTL（分钟），0=禁用"
    )
    max_probe_interval_minutes: int | None = Field(
        default=None, ge=0, le=32, description="熔断探测间隔（分钟），范围 0-32"
    )
    is_active: bool | None = Field(default=None, description="是否启用")
    note: str | None = Field(default=None, max_length=500, description="备注说明")
    auto_fetch_models: bool | None = Field(default=None, description="是否启用自动获取模型")
    locked_models: list[str] | None = Field(
        default=None, description="被锁定的模型列表（刷新时不会被删除）"
    )
    # 模型过滤规则（仅当 auto_fetch_models=True 时生效）
    model_include_patterns: list[str] | None = Field(
        default=None, description="模型包含规则（支持 * 和 ? 通配符），空表示包含所有"
    )
    model_exclude_patterns: list[str] | None = Field(
        default=None, description="模型排除规则（支持 * 和 ? 通配符），空表示不排除"
    )
    # Key 级别代理配置（覆盖 Provider 级别代理）
    # - 不提供：不更新
    # - 提供 null：清除 Key 级别代理，回退到 Provider 级别代理
    # - 提供 ProxyConfig：设置 Key 级别代理
    proxy: ProxyConfig | None = Field(
        default=None,
        description="Key 级别代理配置（覆盖 Provider 级别代理），null=使用 Provider 级别代理",
    )
    fingerprint: dict[str, Any] | None = Field(
        default=None,
        description="请求指纹配置（TLS + HTTP 头部）",
    )

    @field_validator("api_formats")
    @classmethod
    def validate_api_formats(cls, v: list[str] | None) -> list[str] | None:
        """验证 API 格式列表"""
        if v is None:
            return v

        return EndpointAPIKeyCreate.validate_api_formats(v)

    @field_validator("allowed_models")
    @classmethod
    def validate_allowed_models(cls, v: list[str] | None) -> list[str] | None:
        # 与 EndpointAPIKeyCreate 保持一致
        return EndpointAPIKeyCreate.validate_allowed_models(v)

    @field_validator("api_key")
    @classmethod
    def validate_api_key(cls, v: str | None) -> str | None:
        """验证 API Key 基本格式"""
        if v is None:
            return v

        return v.strip()

    @field_validator("name")
    @classmethod
    def validate_name(cls, v: str | None) -> str | None:
        """验证名称（防止 XSS）"""
        if v is None:
            return v

        v = re.sub(r"<script.*?</script>", "", v, flags=re.IGNORECASE | re.DOTALL)
        v = re.sub(r"<iframe.*?</iframe>", "", v, flags=re.IGNORECASE | re.DOTALL)
        v = re.sub(r"javascript:", "", v, flags=re.IGNORECASE)
        v = re.sub(r"on\w+\s*=", "", v, flags=re.IGNORECASE)
        return v.strip()

    @field_validator("note")
    @classmethod
    def validate_note(cls, v: str | None) -> str | None:
        """验证备注（防止 XSS）"""
        if v is None:
            return v

        v = re.sub(r"<script.*?</script>", "", v, flags=re.IGNORECASE | re.DOTALL)
        v = re.sub(r"<iframe.*?</iframe>", "", v, flags=re.IGNORECASE | re.DOTALL)
        v = re.sub(r"javascript:", "", v, flags=re.IGNORECASE)
        v = re.sub(r"on\w+\s*=", "", v, flags=re.IGNORECASE)
        return v.strip()


class OAuthOrganizationResponse(BaseModel):
    id: str | None = Field(default=None, description="OAuth 组织/工作区 ID")
    title: str | None = Field(default=None, description="OAuth 组织/工作区标题")
    is_default: bool = Field(default=False, description="是否为默认组织/工作区")
    role: str | None = Field(default=None, description="当前账号在组织中的角色")


class EndpointAPIKeyResponse(BaseModel):
    """Endpoint API Key 响应"""

    id: str

    provider_id: str = Field(..., description="Provider ID")
    api_formats: list[str] = Field(
        default=[],
        description="支持的 endpoint signature 列表（如 openai:chat, claude:cli）",
    )

    # Key 信息（脱敏）
    api_key_masked: str = Field(..., description="脱敏后的 Key")
    api_key_plain: str | None = Field(default=None, description="完整的 Key")
    auth_type: str = Field(
        default="api_key", description="认证类型：api_key / service_account / oauth"
    )
    # auth_config 不在响应中返回（包含敏感信息），前端通过 auth_type 判断类型
    name: str = Field(..., description="密钥名称")

    # 成本计算
    rate_multipliers: dict[str, float] | None = Field(
        default=None,
        description="按 endpoint signature 的成本倍率，如 {'claude:cli': 1.0, 'openai:cli': 0.8}",
    )

    # 优先级和限制
    internal_priority: int = Field(default=50, description="Endpoint 内部优先级")
    global_priority_by_format: dict[str, int] | None = Field(
        default=None, description="按 endpoint signature 的全局优先级"
    )
    rpm_limit: int | None = None
    allowed_models: list[str] | None = None
    capabilities: dict[str, bool] | None = Field(default=None, description="Key 能力标签")

    # OAuth 相关
    oauth_expires_at: int | None = Field(
        default=None, description="OAuth Token 过期时间（Unix 时间戳）"
    )
    oauth_email: str | None = Field(default=None, description="OAuth 账号邮箱")
    oauth_plan_type: str | None = Field(
        default=None, description="OAuth 账号套餐类型（如 free/plus/team/enterprise）"
    )
    oauth_account_id: str | None = Field(default=None, description="OAuth 账号 ID")
    oauth_account_name: str | None = Field(default=None, description="OAuth 当前工作区/账号名称")
    oauth_account_user_id: str | None = Field(
        default=None,
        description="OAuth 账号-工作区联合 ID（如 Codex chatgpt_account_user_id）",
    )
    oauth_organizations: list[OAuthOrganizationResponse] = Field(
        default_factory=list,
        description="OAuth 关联的组织/工作区摘要列表",
    )
    oauth_invalid_at: int | None = Field(
        default=None,
        description="OAuth Token 失效时间（Unix 时间戳，兼容字段；优先使用 status_snapshot.oauth）",
    )
    oauth_invalid_reason: str | None = Field(
        default=None, description="OAuth Token 失效原因（兼容字段；优先使用 status_snapshot.oauth）"
    )
    status_snapshot: ProviderKeyStatusSnapshotResponse = Field(
        default_factory=ProviderKeyStatusSnapshotResponse,
        description="统一的账号/OAuth/额度状态快照",
    )

    # 缓存与熔断配置
    cache_ttl_minutes: int = Field(default=5, description="缓存 TTL（分钟），0=禁用")
    max_probe_interval_minutes: int = Field(default=32, description="熔断探测间隔（分钟）")

    # 按 endpoint signature 的健康度数据
    health_by_format: dict[str, Any] | None = Field(
        default=None, description="按 endpoint signature 存储的健康度数据"
    )
    circuit_breaker_by_format: dict[str, Any] | None = Field(
        default=None, description="按 endpoint signature 存储的熔断器状态"
    )

    # 聚合字段（从 health_by_format 计算，用于列表显示）
    health_score: float = Field(default=1.0, description="健康度（所有格式中的最低值）")
    consecutive_failures: int = Field(default=0, description="连续失败次数")
    last_failure_at: datetime | None = None

    # 聚合熔断器字段
    circuit_breaker_open: bool = Field(default=False, description="熔断器是否打开（任何格式）")
    circuit_breaker_open_at: datetime | None = Field(default=None, description="熔断器打开时间")
    next_probe_at: datetime | None = Field(default=None, description="下次进入半开状态时间")
    half_open_until: datetime | None = Field(default=None, description="半开状态结束时间")
    half_open_successes: int | None = Field(default=0, description="半开状态成功次数")
    half_open_failures: int | None = Field(default=0, description="半开状态失败次数")
    request_results_window: list[dict[str, Any]] | None = Field(
        None, description="请求结果滑动窗口"
    )

    # 使用统计
    request_count: int
    success_count: int
    error_count: int
    success_rate: float = Field(default=0.0, description="成功率")
    avg_response_time_ms: float = Field(default=0.0, description="平均响应时间（毫秒）")

    # 状态
    is_active: bool

    # 自适应 RPM 信息
    is_adaptive: bool = Field(default=False, description="是否为自适应模式（rpm_limit=NULL）")
    learned_rpm_limit: int | None = Field(None, description="学习到的 RPM 限制")
    effective_limit: int | None = Field(None, description="当前有效限制")
    # 滑动窗口利用率采样
    utilization_samples: list[dict[str, Any]] | None = Field(None, description="利用率采样窗口")
    last_probe_increase_at: datetime | None = Field(None, description="上次探测性扩容时间")
    concurrent_429_count: int | None = None
    rpm_429_count: int | None = None
    last_429_at: datetime | None = None
    last_429_type: str | None = None

    # 备注
    note: str | None = None

    # 自动获取模型
    auto_fetch_models: bool = Field(default=False, description="是否启用自动获取模型")
    last_models_fetch_at: datetime | None = Field(None, description="最后获取模型时间")
    last_models_fetch_error: str | None = Field(None, description="最后获取模型错误信息")
    locked_models: list[str] | None = Field(None, description="被锁定的模型列表")
    # 模型过滤规则
    model_include_patterns: list[str] | None = Field(None, description="模型包含规则")
    model_exclude_patterns: list[str] | None = Field(None, description="模型排除规则")

    # 上游元数据（由响应头采集，如 Codex 额度信息）
    upstream_metadata: dict[str, Any] | None = Field(
        None, description="上游元数据（如 Codex 额度信息）"
    )

    # Key 级别代理配置
    proxy: dict[str, Any] | None = Field(
        None, description="Key 级别代理配置（覆盖 Provider 级别代理）"
    )
    fingerprint: dict[str, Any] | None = Field(
        None,
        description="请求指纹配置（TLS + HTTP 头部）",
    )

    # 时间戳
    last_used_at: datetime | None = None
    created_at: datetime
    updated_at: datetime

    model_config = ConfigDict(from_attributes=True)


# ========== 健康监控相关 ==========


class FormatHealthData(BaseModel):
    """单个 API 格式的健康度数据"""

    health_score: float = 1.0
    error_rate: float = 0.0
    window_size: int = 0
    consecutive_failures: int = 0
    last_failure_at: str | None = None
    circuit_breaker: dict[str, Any] = Field(default_factory=dict)


class HealthStatusResponse(BaseModel):
    """健康状态响应（支持按格式查询）"""

    # 基础信息
    key_id: str
    key_is_active: bool
    key_statistics: dict[str, Any] | None = None

    # 整体健康度（取所有格式中的最低值）
    key_health_score: float = 1.0
    any_circuit_open: bool = False

    # 按格式的健康度数据
    health_by_format: dict[str, FormatHealthData] | None = None

    # 单格式查询时的字段
    api_format: str | None = None
    key_consecutive_failures: int | None = None
    key_last_failure_at: str | None = None

    # 单格式查询时的熔断器状态
    circuit_breaker_open: bool = False
    circuit_breaker_open_at: str | None = None
    next_probe_at: str | None = None
    half_open_until: str | None = None
    half_open_successes: int = 0
    half_open_failures: int = 0


class HealthSummaryResponse(BaseModel):
    """健康状态摘要"""

    endpoints: dict[str, int] = Field(..., description="Endpoint 统计 (total, active, unhealthy)")
    keys: dict[str, int] = Field(..., description="Key 统计 (total, active, unhealthy)")


# ========== RPM 控制相关 ==========


class KeyRpmStatusResponse(BaseModel):
    """Key RPM 状态响应"""

    key_id: str = Field(..., description="Key ID")
    current_rpm: int = Field(default=0, description="当前 RPM 计数")
    rpm_limit: int | None = Field(default=None, description="RPM 限制")


class KeyPriorityItem(BaseModel):
    """单个 Key 优先级项"""

    key_id: str = Field(..., description="Key ID")
    internal_priority: int = Field(..., ge=0, description="Key 内部优先级（数字越小越优先）")


class BatchUpdateKeyPriorityRequest(BaseModel):
    """批量更新 Key 优先级请求"""

    priorities: list[KeyPriorityItem] = Field(..., min_length=1, description="Key 优先级列表")


# ========== 提供商摘要（增强版） ==========


class ProviderUpdateRequest(BaseModel):
    """Provider 基础配置更新请求"""

    name: str | None = Field(None, min_length=1, max_length=100)
    description: str | None = None
    website: str | None = Field(None, max_length=500, description="主站网站")
    provider_priority: int | None = Field(None, description="提供商优先级(数字越小越优先)")
    keep_priority_on_conversion: bool | None = Field(
        None,
        description="格式转换时是否保持优先级（True=保持原优先级，False=需要转换时降级）",
    )
    enable_format_conversion: bool | None = Field(
        None,
        description="是否允许格式转换（提供商级别开关）",
    )
    is_active: bool | None = None
    billing_type: str | None = Field(
        None, description="计费类型：monthly_quota/pay_as_you_go/free_tier"
    )
    monthly_quota_usd: float | None = Field(None, ge=0, description="订阅配额（美元）")
    quota_reset_day: int | None = Field(None, ge=1, le=31, description="配额重置日（1-31）")
    quota_expires_at: datetime | None = Field(None, description="配额过期时间")
    # 请求配置（从 Endpoint 迁移）
    max_retries: int | None = Field(None, ge=0, le=10, description="最大重试次数")
    proxy: dict[str, Any] | None = Field(None, description="代理配置")
    # 超时配置（秒），为空时使用全局配置
    stream_first_byte_timeout: float | None = Field(
        None, ge=1, le=300, description="流式请求首字节超时（秒）"
    )
    request_timeout: float | None = Field(
        None, ge=1, le=600, description="非流式请求整体超时（秒）"
    )
    claude_code_advanced: ClaudeCodeAdvancedConfig | None = Field(
        None, description="Claude Code 高级配置"
    )
    pool_advanced: PoolAdvancedConfig | None = Field(None, description="通用号池配置")
    failover_rules: FailoverRulesConfig | None = Field(None, description="故障转移规则配置")


class ProviderWithEndpointsSummary(BaseModel):
    """Provider 和 Endpoints 摘要"""

    # Provider 基本信息
    id: str
    name: str
    provider_type: str | None = Field(
        default=None,
        description="Provider 类型（custom/claude_code/codex/gemini_cli/antigravity）",
    )
    description: str | None = None
    website: str | None = None
    provider_priority: int = Field(default=100, description="提供商优先级(数字越小越优先)")
    keep_priority_on_conversion: bool = Field(
        default=False,
        description="格式转换时是否保持优先级（True=保持原优先级，False=需要转换时降级）",
    )
    enable_format_conversion: bool = Field(
        default=True,
        description="是否允许格式转换（提供商级别开关）",
    )
    is_active: bool

    # 计费相关字段
    billing_type: str | None = None
    monthly_quota_usd: float | None = None
    monthly_used_usd: float | None = None
    quota_reset_day: int | None = Field(default=None, description="配额重置周期（天数）")
    quota_last_reset_at: datetime | None = Field(default=None, description="当前周期开始时间")
    quota_expires_at: datetime | None = Field(default=None, description="配额过期时间")

    # 请求配置（从 Endpoint 迁移）
    max_retries: int | None = Field(default=2, description="最大重试次数")
    proxy: dict[str, Any] | None = Field(default=None, description="代理配置")
    # 超时配置（秒），为空时使用全局配置
    stream_first_byte_timeout: float | None = Field(
        default=None, description="流式请求首字节超时（秒）"
    )
    request_timeout: float | None = Field(default=None, description="非流式请求整体超时（秒）")
    claude_code_advanced: ClaudeCodeAdvancedConfig | None = Field(
        default=None, description="Claude Code 高级配置"
    )
    pool_advanced: PoolAdvancedConfig | None = Field(default=None, description="通用号池配置")
    failover_rules: FailoverRulesConfig | None = Field(default=None, description="故障转移规则配置")

    # Endpoint 统计
    total_endpoints: int = Field(default=0, description="总 Endpoint 数量")
    active_endpoints: int = Field(default=0, description="活跃 Endpoint 数量")

    # Key 统计（所有 Endpoints 的 Keys）
    total_keys: int = Field(default=0, description="总 Key 数量")
    active_keys: int = Field(default=0, description="活跃 Key 数量")

    # Model 统计
    total_models: int = Field(default=0, description="总模型数量")
    active_models: int = Field(default=0, description="活跃模型数量")
    global_model_ids: list[str] = Field(default=[], description="活跃模型关联的全局模型 ID 列表")

    # API 格式列表
    api_formats: list[str] = Field(default=[], description="支持的 API 格式列表")

    # Endpoint 健康度详情
    endpoint_health_details: list[dict[str, Any]] = Field(
        default=[],
        description="每个 Endpoint 的健康度详情 [{api_format: str, health_score: float, is_active: bool}]",
    )

    # 健康度统计
    avg_health_score: float = Field(default=1.0, description="平均健康度")
    unhealthy_endpoints: int = Field(
        default=0, description="不健康的端点数量（health_score < 0.5）"
    )

    # Provider Ops 配置状态
    ops_configured: bool = Field(default=False, description="是否配置了扩展操作（余额监控等）")
    ops_architecture_id: str | None = Field(
        default=None, description="扩展操作使用的架构 ID（如 cubence, anyrouter）"
    )

    # 时间戳
    created_at: datetime
    updated_at: datetime

    model_config = ConfigDict(from_attributes=True)


class ProviderSummaryPageResponse(BaseModel):
    """Provider 摘要分页响应"""

    total: int
    page: int
    page_size: int
    items: list[ProviderWithEndpointsSummary]


# ========== 健康监控可视化模型 ==========


class EndpointHealthEvent(BaseModel):
    """单个端点的请求事件"""

    timestamp: datetime
    status: str
    status_code: int | None = None
    latency_ms: int | None = None
    error_type: str | None = None
    error_message: str | None = None


class EndpointHealthMonitor(BaseModel):
    """端点健康监控信息"""

    endpoint_id: str
    api_format: str
    is_active: bool
    total_attempts: int
    success_count: int
    failed_count: int
    skipped_count: int
    success_rate: float = Field(default=1.0, description="最近事件窗口的成功率")
    last_event_at: datetime | None = None
    events: list[EndpointHealthEvent] = Field(default_factory=list)


class ProviderEndpointHealthMonitorResponse(BaseModel):
    """Provider 下所有端点的健康监控"""

    provider_id: str
    provider_name: str
    generated_at: datetime
    endpoints: list[EndpointHealthMonitor] = Field(default_factory=list)


class ApiFormatHealthMonitor(BaseModel):
    """按 API 格式聚合的健康监控信息"""

    api_format: str
    total_attempts: int
    success_count: int
    failed_count: int
    skipped_count: int
    success_rate: float = Field(default=1.0, description="最近事件窗口的成功率")
    provider_count: int = Field(default=0, description="参与统计的 Provider 数量")
    key_count: int = Field(default=0, description="参与统计的 API Key 数量")
    last_event_at: datetime | None = None
    events: list[EndpointHealthEvent] = Field(default_factory=list)
    timeline: list[str] = Field(
        default_factory=list,
        description="Usage 表生成的健康时间线（healthy/warning/unhealthy/unknown）",
    )
    time_range_start: datetime | None = Field(
        default=None, description="时间线所覆盖区间的开始时间"
    )
    time_range_end: datetime | None = Field(default=None, description="时间线所覆盖区间的结束时间")


class ApiFormatHealthMonitorResponse(BaseModel):
    """所有 API 格式的健康监控汇总"""

    generated_at: datetime
    formats: list[ApiFormatHealthMonitor] = Field(default_factory=list)


# ========== 公开健康监控模型（不含敏感信息） ==========


class PublicHealthEvent(BaseModel):
    """公开版单个请求事件（不含敏感信息如 provider_id、key_id）"""

    timestamp: datetime
    status: str
    status_code: int | None = None
    latency_ms: int | None = None
    error_type: str | None = None


class PublicApiFormatHealthMonitor(BaseModel):
    """公开版 API 格式健康监控信息（不含敏感信息）"""

    api_format: str
    api_path: str = Field(default="/", description="该 API 格式的本站请求路径")
    total_attempts: int = Field(default=0, description="总请求次数")
    success_count: int = Field(default=0, description="成功次数")
    failed_count: int = Field(default=0, description="失败次数")
    skipped_count: int = Field(default=0, description="跳过次数")
    success_rate: float = Field(default=1.0, description="成功率")
    last_event_at: datetime | None = None
    events: list[PublicHealthEvent] = Field(default_factory=list, description="事件列表")
    timeline: list[str] = Field(
        default_factory=list,
        description="Usage 表生成的健康时间线（healthy/warning/unhealthy/unknown）",
    )
    time_range_start: datetime | None = Field(default=None, description="时间线覆盖区间开始时间")
    time_range_end: datetime | None = Field(default=None, description="时间线覆盖区间结束时间")


class PublicApiFormatHealthMonitorResponse(BaseModel):
    """公开版健康监控汇总（不含敏感信息）"""

    generated_at: datetime
    formats: list[PublicApiFormatHealthMonitor] = Field(default_factory=list)