"""integrations 层数据结构。

定义两个 Pydantic BaseModel：

- ``IntegrationMetadata``：厂商集成元数据（内存态），由各集成包在启动时自注册，
  供前端集成目录展示与 use_cases 层查询。不持久化到数据库。
- ``GeneratedToolsDraft``：工具生成草稿，由 ``create_tools`` handler 返回，
  由 use_cases 层统一持久化到 ORM。集成包不反向依赖 tool_service，
  遵循"草稿生成与持久化职责分离"原则。

放置位置说明：放在 ``integrations/schemas.py`` 而非 ``core/models.py``，因为：
- ``core/models.py`` 是 dataclass（不依赖 Pydantic），与 ORM 一一对齐
- ``IntegrationMetadata`` 是 Pydantic BaseModel（需 JSON Schema 序列化），
  且为 integrations 层专属数据结构
- ``core/contracts.py`` 端口返回类型使用 ``Any``，运行时 core 不依赖本文件
"""

from __future__ import annotations

from typing import Any

from pydantic import BaseModel, ConfigDict, Field


class IntegrationMetadata(BaseModel):
    """厂商集成元数据（内存态）。

    由厂商集成包在应用启动时通过 ``integrations/discovery`` 自动发现并注册，
    不持久化到数据库。供前端集成目录展示与 use_cases 层查询。
    """

    model_config = ConfigDict(extra="forbid")

    key: str = Field(..., min_length=1, max_length=64, description="厂商唯一标识，如 salesforce")
    display_name: str = Field(..., min_length=1, max_length=128, description="展示名称")
    description: str = Field(default="", max_length=512, description="简要描述")
    adapter_type: str = Field(..., max_length=32, description="运行时协议适配器，如 http")
    source_types: list[str] = Field(..., min_length=1, description="该集成注册的 source_type 列表")
    supported_auth_types: list[str] = Field(default_factory=list, description="支持的认证类型列表")
    tags: list[str] = Field(default_factory=list, description="分类标签")
    icon: str | None = Field(default=None, description="图标标识（前端消费）")
    docs_url: str | None = Field(default=None, description="官方文档链接")
    connection_extra_schema: dict[str, Any] | None = Field(default=None, description="连接配置额外字段的 JSON Schema")
    example_config: dict[str, Any] | None = Field(default=None, description="推荐配置示例")
    dependency_note: str | None = Field(default=None, description="依赖说明（密钥/前置条件）")


class GeneratedToolsDraft(BaseModel):
    """工具生成草稿（不直接持久化）。

    由 ``IntegrationOperationRegistry.create_tools`` 返回，由 use_cases 层
    （``import_service`` / ``integration_tool_service``）统一持久化到 ORM。
    集成包不反向依赖 tool_service，遵循"草稿生成与持久化职责分离"原则。
    """

    model_config = ConfigDict(extra="forbid")

    tool_configs: list[dict[str, Any]] = Field(
        ..., description="待持久化的工具配置草稿列表（每项为 ExternalToolCreateInput 兼容的 dict）"
    )
    override_existing: bool = Field(default=False, description="slug 已存在时是否覆盖")