ForcePilot/backend/server/routers/external_systems/integration_router.py

"""Integration 子域 Router.

外部系统限界上下文的厂商集成目录查询 API。所有端点直接读取
``IntegrationRegistry`` 与 ``IntegrationOperationRegistry`` 注册表全局单例
（代码注册的内存态对象），不引入 use_cases 层——数据源无持久化需求，与
adapter_router / auth_plugin_router 元数据端点保持一致。

设计依据：docs/vibe/v1.1/设计方案/RouterAPI扩展设计/15-integration_router扩展设计方案.md
"""

from __future__ import annotations

from typing import Any

from fastapi import APIRouter, Depends, Query
from yuxi.external_systems.integrations.operation_registry import (
    IntegrationOperationRegistry,
)
from yuxi.external_systems.integrations.registry import IntegrationRegistry
from yuxi.storage.postgres.models_business import User

from server.utils.auth_middleware import get_required_user

integration_router = APIRouter(
    prefix="/integrations",
    tags=["external-systems-integration"],
)


# 列表端点剔除的字段：Schema/配置/依赖说明，避免列表响应过重
_SUMMARY_EXCLUDED_FIELDS = ("connection_extra_schema", "example_config", "dependency_note")


# =============================================================================
# === 静态路径端点（必须在 /{key} 之前声明） ===
# =============================================================================


@integration_router.get("", response_model=dict)
async def list_integrations(
    adapter_type: str | None = Query(None, max_length=32, description="按适配器类型精确过滤"),
    tags: str | None = Query(None, max_length=256, description="按标签过滤，多个标签以逗号分隔（OR 关系）"),
    keyword: str | None = Query(
        None, max_length=128, description="模糊匹配 display_name / description（大小写不敏感）"
    ),
    limit: int = Query(50, ge=1, le=200, description="分页大小，最大 200"),
    offset: int = Query(0, ge=0, description="分页偏移"),
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询厂商集成目录列表，支持按适配器类型、标签、关键词过滤与分页。

    列表项返回精简字段（剔除 connection_extra_schema / example_config /
    dependency_note），适合前端集成市场页表格展示。``total`` 为满足筛选
    条件的全量总数（由 count_integrations 计算），非当前分页条数。
    """
    tags_list: list[str] | None = None
    if tags is not None:
        tags_list = [t.strip() for t in tags.split(",") if t.strip()]
        if not tags_list:
            tags_list = None

    metadata_list = IntegrationRegistry.list_integrations(
        adapter_type=adapter_type,
        tags=tags_list,
        keyword=keyword,
        limit=limit,
        offset=offset,
    )
    total = IntegrationRegistry.count_integrations(
        adapter_type=adapter_type,
        tags=tags_list,
        keyword=keyword,
    )
    items = [
        {k: v for k, v in metadata.model_dump().items() if k not in _SUMMARY_EXCLUDED_FIELDS}
        for metadata in metadata_list
    ]
    return {
        "success": True,
        "data": {
            "items": items,
            "total": total,
            "limit": limit,
            "offset": offset,
        },
    }


@integration_router.get("/overview", response_model=dict)
async def get_integrations_overview(
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询厂商集成的分组总览（按 adapter_type 分组 + 标签统计）。

    通过 filter_integrations 获取全量集成（无分页），按 ``adapter_type``
    分组构造 ``by_adapter_type`` 字典（每组仅含精简字段），并统计每个标签
    出现次数构造 ``by_tag`` 字典。适合前端管理页树形渲染与统计卡片。
    """
    metadata_list = IntegrationRegistry.filter_integrations()

    by_adapter_type: dict[str, list[dict[str, Any]]] = {}
    by_tag: dict[str, int] = {}
    for metadata in metadata_list:
        by_adapter_type.setdefault(metadata.adapter_type, []).append(
            {
                "key": metadata.key,
                "display_name": metadata.display_name,
                "adapter_type": metadata.adapter_type,
                "tags": metadata.tags,
            }
        )
        for tag in metadata.tags:
            by_tag[tag] = by_tag.get(tag, 0) + 1

    return {
        "success": True,
        "data": {
            "by_adapter_type": by_adapter_type,
            "total": len(metadata_list),
            "by_tag": by_tag,
        },
    }


@integration_router.get("/categories", response_model=dict)
async def get_integration_categories(
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询厂商集成的分类标签树（基于 tags 字段聚合）。

    通过 filter_integrations 获取全量集成（无分页），每个标签返回
    ``count`` 与 ``integrations``（key 列表），按 ``count`` 降序、
    ``tag`` 升序排序。适合前端集成市场页分类筛选侧边栏。
    """
    metadata_list = IntegrationRegistry.filter_integrations()

    tag_to_integrations: dict[str, list[str]] = {}
    for metadata in metadata_list:
        for tag in metadata.tags:
            tag_to_integrations.setdefault(tag, []).append(metadata.key)

    items = [{"tag": tag, "count": len(keys), "integrations": keys} for tag, keys in tag_to_integrations.items()]
    items.sort(key=lambda it: (-it["count"], it["tag"]))

    return {
        "success": True,
        "data": {"items": items, "total": len(items)},
    }


@integration_router.get("/adapter-types", response_model=dict)
async def get_integration_adapter_types(
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询所有厂商集成涉及的适配器类型（去重），用于前端过滤选项。

    仅返回有厂商集成的适配器类型（当前全部为 http），与 adapter_router 的
    ``GET /adapters``（所有注册协议适配器）语义不同。
    """
    adapter_types = IntegrationRegistry.list_adapter_types()
    return {
        "success": True,
        "data": {"items": adapter_types, "total": len(adapter_types)},
    }


@integration_router.get("/source-types", response_model=dict)
async def get_integration_source_types(
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询所有已注册操作 handler 的数据源类型（含操作支持矩阵）。

    对每个 source_type 调用 ``list_operations`` 获取已注册操作，按
    ``source_type`` 升序排序。适合前端"工具生成"页的 source_type 选择。
    仅返回厂商 source_type，不含 openapi / postman 等通用 source_type
    （通用 source_type 走资产导入流程，未注册操作 handler）。
    """
    source_types = IntegrationOperationRegistry.list_source_types()
    items = [
        {
            "source_type": source_type,
            "operations": IntegrationOperationRegistry.list_operations(source_type),
        }
        for source_type in sorted(source_types)
    ]
    return {
        "success": True,
        "data": {"items": items, "total": len(items)},
    }


# =============================================================================
# === 路径参数端点（/{key}） ===
# =============================================================================


@integration_router.get("/{key}", response_model=dict)
async def get_integration_detail(
    key: str,
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询指定厂商集成的完整详情（含所有 12 个字段）。

    ``get_integration_or_raise`` 未找到时抛 ``EntityNotFoundError`` (404)，
    由全局处理器统一映射。返回 ``model_dump()`` 完整字段，包含
    connection_extra_schema / example_config / dependency_note。
    """
    metadata = IntegrationRegistry.get_integration_or_raise(key)
    return {"success": True, "data": metadata.model_dump()}


@integration_router.get("/{key}/operations", response_model=dict)
async def get_integration_operations(
    key: str,
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询指定厂商集成已注册的操作 handler 列表（按 source_type 分组）。

    遍历 ``metadata.source_types``，对每个 source_type 调用
    ``list_operations`` 获取已注册操作。``operations_by_source_type`` 为
    ``{source_type: [operations]}`` 字典；``supported_operations`` 为所有
    source_type 操作的并集（去重，按字母升序排序）。

    ``get_integration_or_raise`` 未找到时抛 ``EntityNotFoundError`` (404)。
    """
    metadata = IntegrationRegistry.get_integration_or_raise(key)

    operations_by_source_type: dict[str, list[str]] = {}
    for source_type in metadata.source_types:
        operations_by_source_type[source_type] = IntegrationOperationRegistry.list_operations(source_type)

    supported_operations = sorted(set(op for ops in operations_by_source_type.values() for op in ops))

    return {
        "success": True,
        "data": {
            "key": key,
            "operations_by_source_type": operations_by_source_type,
            "supported_operations": supported_operations,
        },
    }


@integration_router.get("/{key}/connection-schema", response_model=dict)
async def get_integration_connection_schema(
    key: str,
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """获取厂商集成的连接配置 JSON Schema，用于前端动态表单渲染。

    返回 ``connection_extra_schema`` 字段（可能为 None，表示该集成无额外
    连接配置）。与详情端点的差异：本端点仅返回 Schema，适合前端表单渲染
    时独立获取。

    ``get_integration_or_raise`` 未找到时抛 ``EntityNotFoundError`` (404)。
    """
    metadata = IntegrationRegistry.get_integration_or_raise(key)
    return {
        "success": True,
        "data": {
            "key": key,
            "connection_extra_schema": metadata.connection_extra_schema,
        },
    }


@integration_router.get("/{key}/example-config", response_model=dict)
async def get_integration_example_config(
    key: str,
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """获取厂商集成的推荐配置示例，用于前端表单预填与配置引导。

    返回 ``example_config`` 字段（可能为 None，表示该集成无推荐配置）。

    ``get_integration_or_raise`` 未找到时抛 ``EntityNotFoundError`` (404)。
    """
    metadata = IntegrationRegistry.get_integration_or_raise(key)
    return {
        "success": True,
        "data": {
            "key": key,
            "example_config": metadata.example_config,
        },
    }