"""Webhook 通用信封模型。

提供通用泛型信封模型 ``WebhookRequest[PayloadT]`` 和
``WebhookResponse[DataT]``。

这些模型在 Hezor2 服务端（校验 & 构造响应）和 SDK 客户端
（请求构建 & 响应解析）之间共享，适用于所有 Webhook 功能，
不限于 Creation 领域。
"""

from typing import Generic, TypeVar

from pydantic import BaseModel, Field

# ---------------------------------------------------------------------------
# 泛型类型变量
# ---------------------------------------------------------------------------

PayloadT = TypeVar("PayloadT")
DataT = TypeVar("DataT")


# ---------------------------------------------------------------------------
# 通用信封模型（Generic Envelope）
# ---------------------------------------------------------------------------


class WebhookRequest(BaseModel, Generic[PayloadT]):
    """通用 Webhook 请求。

    所有 Webhook 功能统一通过 action/payload 模式调用。
    可通过泛型参数指定 payload 类型以获得类型安全：

    - ``WebhookRequest[dict]`` — 未校验的原始 payload
    - ``WebhookRequest[PublishCreationPayload]`` — 强类型 payload

    Parameters
    ----------
    action : str
        操作类型，用于路由到具体的处理逻辑。
    payload : PayloadT
        操作负载，结构由 action 决定。

    Examples
    --------
    >>> request = WebhookRequest(
    ...     action="publish_creation_report",
    ...     payload={
    ...         "task_id": "monthly_report",
    ...         "creation_result": {"creation_id": "rpt_xxx"},
    ...     },
    ... )
    """

    action: str = Field(
        ...,
        description="操作类型",
        examples=["publish_creation_report", "get_report_status"],
    )
    payload: PayloadT = Field(  # type: ignore[assignment]
        default_factory=dict,
        description="操作负载，结构由 action 决定",
    )


class WebhookResponse(BaseModel, Generic[DataT]):
    """通用 Webhook 响应。

    可通过泛型参数指定 ``data`` 字段的类型：

    - ``WebhookResponse[dict]`` — 未解析的原始 data
    - ``WebhookResponse[ReportMetadata]`` — 强类型 data

    Parameters
    ----------
    action : str
        对应请求的操作类型。
    status : str
        处理状态。
    data : DataT or None
        响应数据，结构由 action 决定。
    message : str
        响应消息。

    Examples
    --------
    >>> resp = WebhookResponse(
    ...     action="generate_report_id",
    ...     status="ok",
    ...     data={"report_ids": ["rpt_001"]},
    ...     message="Generated 1 report ID(s)",
    ... )
    """

    action: str = Field(..., description="操作类型")
    status: str = Field(..., description="处理状态")
    data: DataT | None = Field(default=None, description="响应数据")
    message: str = Field(default="", description="响应消息")


__all__ = [
    "DataT",
    "PayloadT",
    "WebhookRequest",
    "WebhookResponse",
]
