ForcePilot/backend/package/yuxi/external_systems/integrations/hubspot/operations.py

"""HubSpot discover / preview_tools / create_tools handler 实现 + 元数据发现 +
Search 渲染 + 错误提取器。

handler 签名遵循 ``OperationHandler`` 协议：
``(source_type: str, system_config: dict[str, Any]) -> Awaitable[Any]``。

handler 内部职责：
1. 从 ``system_config`` 提取 ``base_url`` / ``auth_config`` / ``_resolved_token``
2. 构建 ``auth_headers``（token 由 use_cases 层注入到 ``system_config["_resolved_token"]``）
3. 构造带 429 退避的 ``request_fn``，发起元数据发现请求
4. 调用 ``HubSpotConfigGenerator`` 生成工具配置草稿

两层错误处理（见设计文档 §8）：

- **L1**: ``extract_hubspot_error`` — 注册到 ``http_error_extractor_registry``，
  由框架 executor 在运行时工具执行失败时调用，提取友好错误消息字符串。
- **L2**: ``map_hubspot_error`` — 不注册到任何注册表，仅在 handler 内部
  discover/preview/create 阶段失败后调用，将 HTTP 状态码映射为
  ``ExternalSystemError`` 子类。

429 退避分层（见设计文档 §6.4）：
- discover/preview/create 阶段：本模块 ``_request_with_retry`` 实现
- 运行时工具执行：通过工具 ``retry_policy.retry_status_codes: [429]`` 配置
"""

from __future__ import annotations

import asyncio
from collections.abc import Awaitable, Callable
from typing import TYPE_CHECKING, Any

from yuxi.external_systems.exceptions import (
    AccessDeniedError,
    AuthError,
    EntityNotFoundError,
    ExecutionError,
    QuotaExceededError,
    RateLimitExceededError,
)
from yuxi.external_systems.integrations.hubspot.generators import (
    HubSpotConfigGenerator,
)
from yuxi.external_systems.integrations.hubspot.metadata import (
    API_BASE_URL,
    ASSOCIATIONS_PATH_TEMPLATE,
    DEFAULT_STANDARD_OBJECTS,
    PROPERTIES_PATH_TEMPLATE,
    SCHEMAS_PATH,
    STANDARD_OBJECT_TYPE_IDS,
)
from yuxi.external_systems.integrations.schemas import GeneratedToolsDraft

if TYPE_CHECKING:
    import httpx

# discover/preview/create 阶段 429 退避参数
_RETRY_MAX_ATTEMPTS = 5
_RETRY_BASE_DELAY = 1.0

# HubSpot 通用请求头（除 Authorization 外）
_HUBSPOT_HEADERS: dict[str, str] = {
    "Accept": "application/json",
    "Content-Type": "application/json",
}


# ── 错误提取器（L1）──────────────────────────────────────────────────────


def extract_hubspot_error(response: httpx.Response) -> str | None:
    """从 HubSpot 错误响应中提取友好错误信息（L1）。

    HubSpot 错误响应为 JSON 对象，含顶层 ``status`` / ``message`` / ``correlationId``
    与 ``errors`` 数组::

        {
            "status": "error",
            "message": "Property values were not valid",
            "correlationId": "a1b2c3d4-e5f6-7890",
            "errors": [
                {
                    "message": "The property 'email' is required",
                    "in": "propertyName",
                    "code": "REQUIRED_PROPERTY",
                    "context": {"propertyName": ["email"]}
                }
            ],
            "category": "VALIDATION_ERROR"
        }

    Returns:
        拼接后的错误消息字符串（含 message + errors[].code/message + correlationId），
        非 HubSpot 错误格式时返回 None。
    """
    try:
        body = response.json()
    except Exception:
        return None

    if not isinstance(body, dict):
        return None

    if body.get("status") != "error":
        return None

    parts: list[str] = []
    top_message = body.get("message", "")
    if top_message:
        parts.append(top_message)

    errors = body.get("errors") or []
    for err in errors:
        if not isinstance(err, dict):
            continue
        code = err.get("code", "UNKNOWN")
        msg = err.get("message", "")
        context = err.get("context") or {}
        context_hint = f" (context: {context})" if context else ""
        parts.append(f"[{code}] {msg}{context_hint}")

    correlation_id = body.get("correlationId")
    if correlation_id:
        parts.append(f"correlationId: {correlation_id}")

    return "; ".join(parts) if parts else None


def map_hubspot_error(status_code: int, error_body: dict[str, Any]) -> Exception:
    """将 HubSpot 错误响应转换为 ExternalSystemError 子类（L2）。

    仅在 handler 内部（discover/preview/create 阶段）使用，不注册到框架。
    运行时工具执行的错误由框架 executor 统一包装为 ExecutionError。

    错误码映射见设计文档 §8.3。
    """
    message = error_body.get("message", "") if isinstance(error_body, dict) else ""
    category = error_body.get("category", "") if isinstance(error_body, dict) else ""
    correlation_id = error_body.get("correlationId", "") if isinstance(error_body, dict) else ""
    context_hint = f" (correlationId={correlation_id})" if correlation_id else ""
    full_message = f"HubSpot: {message}{context_hint}" if message else f"HubSpot 错误{context_hint}"

    if status_code == 401:
        return AuthError(f"HubSpot 认证失败: {full_message} (category={category})")
    if status_code == 403:
        return AccessDeniedError(f"HubSpot 访问被拒: {full_message} (category={category})")
    if status_code == 404:
        return EntityNotFoundError(f"HubSpot 资源不存在: {full_message}")
    if status_code == 409:
        return ExecutionError(f"HubSpot 冲突: {full_message}")
    if status_code == 429:
        # RATE_LIMIT_EXCEEDED vs DAILY_LIMIT_EXCEEDED 按 category 区分
        if category == "DAILY_LIMIT_EXCEEDED":
            return QuotaExceededError(f"HubSpot 每日配额耗尽: {full_message}")
        return RateLimitExceededError(
            f"HubSpot 限流: {full_message}",
            retry_after=60,
            limit_type="qps",
        )
    if 500 <= status_code < 600:
        return ExecutionError(f"HubSpot 服务端错误: {full_message} (status={status_code})")
    return ExecutionError(f"HubSpot 未知错误: {full_message} (status={status_code})")


# ── Search API 请求体渲染 ─────────────────────────────────────────────────


def _render_search_body(
    filter_groups: list[dict[str, Any]],
    properties: list[str] | None = None,
    sorts: list[dict[str, Any]] | None = None,
    after: str | None = None,
    limit: int = 50,
) -> dict[str, Any]:
    """渲染 HubSpot Search API 请求体。

    Args:
        filter_groups: 筛选组列表，每组内 filters 为 AND 关系，组间为 OR 关系。
            每条 filter 含 propertyName / operator / value。
            operator 支持: EQ / NEQ / LT / LTE / GT / GTE / BETWEEN / IN / NOT_IN /
            CONTAINS_TOKEN / NOT_CONTAINS_TOKEN / HAS_PROPERTY / NOT_HAS_PROPERTY。
        properties: 返回的属性列表（默认返回全部）。
        sorts: 排序规则列表。
        after: 分页游标（上一页响应的 after 值）。
        limit: 每页记录数（最大 200）。
    """
    body: dict[str, Any] = {"filterGroups": filter_groups}
    if properties:
        body["properties"] = properties
    if sorts:
        body["sorts"] = sorts
    paging: dict[str, Any] = {"limit": min(limit, 200)}
    if after:
        paging["after"] = after
    body["paging"] = paging
    return body


# ── system_config 解析辅助 ────────────────────────────────────────────────


def _build_auth_headers(system_config: dict[str, Any]) -> dict[str, str]:
    """从 system_config 提取 token，构建 HubSpot 请求头。

    system_config 中 token 由 use_cases 层通过 ``token_manager.get_token`` 预处理后
    注入到 ``system_config["_resolved_token"]["access_token"]``。handler 不自行换取
    token——token 获取是 use_cases 层的职责。
    """
    token_info = system_config.get("_resolved_token")
    if not isinstance(token_info, dict) or not token_info.get("access_token"):
        raise AuthError("hubspot: system_config 缺少 _resolved_token，use_cases 层未注入 token")
    access_token = token_info["access_token"]
    headers = dict(_HUBSPOT_HEADERS)
    headers["Authorization"] = f"Bearer {access_token}"
    return headers


def _resolve_base_url(system_config: dict[str, Any]) -> str:
    """从 system_config 提取 base_url，默认 ``https://api.hubapi.com``。"""
    connection_config = system_config.get("connection_config") or {}
    base_url = connection_config.get("base_url") or API_BASE_URL
    return str(base_url).rstrip("/")


def _resolve_auth_type(system_config: dict[str, Any]) -> str:
    """从 system_config 提取 auth_type，默认 private_app_token。"""
    return str(system_config.get("auth_type", "private_app_token"))


def _resolve_selected_objects(system_config: dict[str, Any]) -> list[str]:
    """从 system_config 提取用户选择的标准对象 FQN 列表。

    默认返回 ``DEFAULT_STANDARD_OBJECTS``（contacts / companies / deals / tickets）。
    """
    discovery_options = system_config.get("discovery_options") or {}
    selected = discovery_options.get("selected_objects")
    if selected:
        return list(selected)
    return list(DEFAULT_STANDARD_OBJECTS)


def _resolve_association_pairs(
    system_config: dict[str, Any],
) -> list[tuple[str, str]]:
    """从 system_config 提取需要发现关联标签的对象对列表。

    返回 ``[(from_type, to_type), ...]``，默认空列表（不发现关联）。
    ``discovery_options.association_pairs`` 格式：``[{"from": "0-1", "to": "0-2"}]``。
    """
    discovery_options = system_config.get("discovery_options") or {}
    pairs_raw = discovery_options.get("association_pairs") or []
    pairs: list[tuple[str, str]] = []
    for pair in pairs_raw:
        if not isinstance(pair, dict):
            continue
        from_type = pair.get("from")
        to_type = pair.get("to")
        if from_type and to_type:
            pairs.append((str(from_type), str(to_type)))
    return pairs


# ── 429 退避 HTTP 请求 ────────────────────────────────────────────────────


async def _request_with_retry(
    method: str,
    url: str,
    headers: dict[str, str],
    *,
    max_retries: int = _RETRY_MAX_ATTEMPTS,
    base_delay: float = _RETRY_BASE_DELAY,
) -> httpx.Response:
    """handler 内部 HTTP 调用的 429 退避（仅用于 discover/preview/create 阶段）。

    优先使用响应头 ``Retry-After``，否则指数退避（``base_delay * 2 ** attempt``）。
    运行时工具执行的 429 退避由框架 executor + 工具 retry_policy 处理。

    非 2xx 响应（非 429）通过 ``map_hubspot_error`` 转换为 ExternalSystemError 子类。
    网络层异常（超时 / 连接错误）转换为 ``ExecutionError``。
    """
    import httpx

    try:
        async with httpx.AsyncClient() as client:
            last_response: httpx.Response | None = None
            for attempt in range(max_retries + 1):
                response = await client.request(method, url, headers=headers)
                if response.status_code != 429:
                    last_response = response
                    break
                if attempt == max_retries:
                    retry_after_header = response.headers.get("Retry-After", "60")
                    try:
                        retry_after = int(retry_after_header)
                    except ValueError:
                        retry_after = 60
                    raise RateLimitExceededError(
                        f"HubSpot 限流，已重试 {max_retries} 次仍失败: {url}",
                        retry_after=retry_after,
                        limit_type="qps",
                    )
                retry_after_header = response.headers.get("Retry-After")
                if retry_after_header:
                    try:
                        delay = float(retry_after_header)
                    except ValueError:
                        delay = base_delay * (2**attempt)
                else:
                    delay = base_delay * (2**attempt)
                await asyncio.sleep(delay)
    except httpx.RequestError as exc:
        raise ExecutionError(f"HubSpot 网络请求失败: {exc}") from exc

    assert last_response is not None
    if last_response.is_success:
        return last_response
    try:
        error_body = last_response.json()
    except Exception:
        error_body = {"message": last_response.text}
    raise map_hubspot_error(last_response.status_code, error_body)


def _make_request_fn() -> Callable[..., Awaitable[httpx.Response]]:
    """构造带 429 退避的 request_fn，供元数据发现函数使用。"""

    async def request_fn(method: str, url: str, headers: dict[str, str]) -> httpx.Response:
        return await _request_with_retry(method, url, headers)

    return request_fn


# ── 元数据发现函数 ────────────────────────────────────────────────────────


async def _discover_schemas(
    request_fn: Callable[..., Awaitable[httpx.Response]],
    base_url: str,
    headers: dict[str, str],
) -> list[dict[str, Any]]:
    """调用 ``GET /crm/v3/schemas`` 获取自定义对象 schema 列表。

    自定义对象类型 ID 为 ``2-XXX``；标准对象 schema 不在此处列出。
    """
    response = await request_fn("GET", f"{base_url}{SCHEMAS_PATH}", headers)
    data = response.json()
    return data.get("results", []) if isinstance(data, dict) else []


async def _discover_properties(
    request_fn: Callable[..., Awaitable[httpx.Response]],
    base_url: str,
    object_type_id: str,
    headers: dict[str, str],
) -> list[dict[str, Any]]:
    """调用 ``GET /crm/v3/properties/{objectTypeId}`` 获取对象属性元数据。"""
    path = PROPERTIES_PATH_TEMPLATE.format(object_type_id=object_type_id)
    response = await request_fn("GET", f"{base_url}{path}", headers)
    data = response.json()
    return data.get("results", []) if isinstance(data, dict) else []


async def _discover_association_labels(
    request_fn: Callable[..., Awaitable[httpx.Response]],
    base_url: str,
    from_type: str,
    to_type: str,
    headers: dict[str, str],
) -> list[dict[str, Any]]:
    """调用 ``GET /crm/v4/associations/{from}/{to}/labels`` 获取关联类型标签。"""
    path = ASSOCIATIONS_PATH_TEMPLATE.format(**{"from": from_type, "to": to_type})
    response = await request_fn("GET", f"{base_url}{path}", headers)
    data = response.json()
    return data.get("results", []) if isinstance(data, dict) else []


# ── 三个 OperationHandler 实现 ────────────────────────────────────────────


async def discover_hubspot(
    source_type: str,
    system_config: dict[str, Any],
) -> list[dict[str, Any]]:
    """discover handler：发现 HubSpot 可用对象列表（标准对象 + 自定义对象 Schemas）。

    Returns:
        对象摘要列表，每项含 ``object_type_id`` / ``name`` / ``is_standard`` /
        ``label``。
    """
    base_url = _resolve_base_url(system_config)
    auth_headers = _build_auth_headers(system_config)
    selected_objects = _resolve_selected_objects(system_config)
    request_fn = _make_request_fn()

    # 标准对象（用户选择的）
    results: list[dict[str, Any]] = []
    for fqn in selected_objects:
        type_id = STANDARD_OBJECT_TYPE_IDS.get(fqn, fqn)
        results.append(
            {
                "object_type_id": type_id,
                "name": fqn,
                "label": fqn.replace("_", " ").title(),
                "is_standard": True,
            }
        )

    # 自定义对象（Schemas API）
    custom_schemas = await _discover_schemas(request_fn, base_url, auth_headers)
    for schema in custom_schemas:
        type_id = schema.get("objectTypeId", "")
        name = schema.get("name", type_id)
        labels = schema.get("labels") or {}
        label = labels.get("singular", name) if isinstance(labels, dict) else name
        results.append(
            {
                "object_type_id": type_id,
                "name": name,
                "label": label,
                "is_standard": False,
            }
        )

    return results


async def preview_hubspot_tools(
    source_type: str,
    system_config: dict[str, Any],
) -> list[dict[str, Any]]:
    """preview_tools handler：预览将生成的工具列表。

    Returns:
        工具预览列表，每项为 ExternalToolCreateInput 兼容的 dict。
    """
    payload = await _build_generator_payload(system_config)
    generator = HubSpotConfigGenerator()
    return await generator.generate(payload)


async def create_hubspot_tools(
    source_type: str,
    system_config: dict[str, Any],
) -> GeneratedToolsDraft:
    """create_tools handler：生成工具草稿（不直接持久化）。

    Returns:
        GeneratedToolsDraft，由 use_cases 层统一持久化。
    """
    payload = await _build_generator_payload(system_config)
    generator = HubSpotConfigGenerator()
    tool_configs = await generator.generate(payload)
    return GeneratedToolsDraft(tool_configs=tool_configs, override_existing=False)


# ── 生成器 payload 构造 ───────────────────────────────────────────────────


async def _build_generator_payload(system_config: dict[str, Any]) -> dict[str, Any]:
    """从 system_config 构造生成器 payload。

    流程：
    1. 解析 base_url / auth_headers / auth_type / auth_config
    2. 解析用户选择的标准对象 FQN 列表
    3. 发现自定义对象 Schemas
    4. 为每个对象（标准 + 自定义）发现属性元数据
    5. 可选：发现关联标签（基于 discovery_options.association_pairs）
    6. 汇总为生成器 payload
    """
    base_url = _resolve_base_url(system_config)
    auth_headers = _build_auth_headers(system_config)
    auth_type = _resolve_auth_type(system_config)
    auth_config = system_config.get("auth_config") or {}
    selected_objects = _resolve_selected_objects(system_config)
    association_pairs = _resolve_association_pairs(system_config)
    request_fn = _make_request_fn()

    # 发现自定义对象 Schemas
    custom_schemas = await _discover_schemas(request_fn, base_url, auth_headers)

    # 合并标准对象与自定义对象 → (objectTypeId, fqn) 列表
    all_objects: list[tuple[str, str]] = []
    for fqn in selected_objects:
        type_id = STANDARD_OBJECT_TYPE_IDS.get(fqn, fqn)
        all_objects.append((type_id, fqn))
    for schema in custom_schemas:
        type_id = schema.get("objectTypeId", "")
        fqn = schema.get("name", type_id)
        if type_id:
            all_objects.append((type_id, fqn))

    # 为每个对象发现属性元数据
    properties_map: dict[str, list[dict[str, Any]]] = {}
    for type_id, _fqn in all_objects:
        properties_map[type_id] = await _discover_properties(request_fn, base_url, type_id, auth_headers)

    # 可选：发现关联标签
    association_labels: list[dict[str, Any]] = []
    for from_type, to_type in association_pairs:
        labels = await _discover_association_labels(request_fn, base_url, from_type, to_type, auth_headers)
        if labels:
            association_labels.append({"from": from_type, "to": to_type, "labels": labels})

    return {
        "standard_objects": selected_objects,
        "custom_schemas": custom_schemas,
        "properties_map": properties_map,
        "association_labels": association_labels,
        "base_url": base_url,
        "auth_type": auth_type,
        "auth_config": auth_config,
    }