ForcePilot/backend/package/yuxi/channels/contract/dtos/outbound.py

"""出站 DTO。

定义出站管道的富消息与最终输出值对象，包括富消息按钮、富消息选项、
富消息、富消息字段、出站负载、格式化消息、可信消息与最终消息。
所有 DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库与契约层内部
类型，用于出站消息的格式化、可信注入与最终投递。集合字段使用 tuple
以保证 frozen dataclass 的不可变语义。
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any

from yuxi.channels.contract.dtos.common import Attachment, MessageFormat
from yuxi.channels.contract.errors import ValidationError


@dataclass(frozen=True)
class RichMessageButton:
    """富消息按钮。

    描述富消息中的可点击按钮，由适配器按渠道协议渲染为对应交互元素。

    字段：
        label: 按钮显示文本。
        action: 按钮动作标识。
        value: 按钮动作携带的值（可选）。
    """

    label: str
    action: str
    value: str | None = None


@dataclass(frozen=True)
class RichMessageOption:
    """富消息选项。

    描述富消息中的可选项，用于下拉 / 列表类交互组件。

    字段：
        label: 选项显示文本。
        value: 选项值。
    """

    label: str
    value: str


@dataclass(frozen=True)
class RichMessageSelect:
    """富消息下拉选择器组件。

    字段：
        name: 表单字段名。
        label: 显示标签。
        options: 可选项列表。
        placeholder: 占位文本，可选。
        default_value: 默认值，可选。
    """

    name: str
    label: str
    options: tuple[RichMessageOption, ...]
    placeholder: str | None = None
    default_value: str | None = None


@dataclass(frozen=True)
class RichMessageDatePicker:
    """富消息日期选择器组件。

    字段：
        name: 表单字段名。
        label: 显示标签。
        placeholder: 占位文本，可选。
        default_value: 默认日期（ISO 格式），可选。
        min_date: 最小可选日期（ISO 格式），可选。
        max_date: 最大可选日期（ISO 格式），可选。
    """

    name: str
    label: str
    placeholder: str | None = None
    default_value: str | None = None
    min_date: str | None = None
    max_date: str | None = None


@dataclass(frozen=True)
class RichMessageCheckbox:
    """富消息复选框组件。

    字段：
        name: 表单字段名。
        label: 显示标签。
        options: 可选项列表。
        default_values: 默认选中值列表。
    """

    name: str
    label: str
    options: tuple[RichMessageOption, ...]
    default_values: tuple[str, ...] = ()


@dataclass(frozen=True)
class RichMessageInput:
    """富消息输入框组件。

    字段：
        name: 表单字段名。
        label: 显示标签。
        placeholder: 占位文本，可选。
        default_value: 默认值，可选。
        max_length: 最大输入长度，可选。
        input_type: 输入类型（text/number/email 等），默认 text。
    """

    name: str
    label: str
    placeholder: str | None = None
    default_value: str | None = None
    max_length: int | None = None
    input_type: str = "text"


@dataclass(frozen=True)
class RichMessage:
    """富消息。

    描述结构化的富消息内容，包括标题、正文、描述、图片、视频与交互元素
    （按钮 / 选项），由适配器按渠道协议渲染。集合字段使用 tuple 以
    保证不可变。

    字段：
        text: 正文文本。
        title: 标题（可选）。
        description: 描述（可选）。
        image_url: 图片 URL（可选，向后兼容）。
        video_url: 视频 URL（可选，FR-50）。
        attachments: 多附件列表（承载多图、文件等，FR-50）。
        buttons: 按钮列表（默认空 tuple）。
        options: 选项列表（默认空 tuple）。
        metadata: 渠道侧元数据（可选）。
        selects: 下拉选择器组件列表。
        date_pickers: 日期选择器组件列表。
        checkboxes: 复选框组件列表。
        inputs: 输入框组件列表。
    """

    text: str
    title: str | None = None
    description: str | None = None
    image_url: str | None = None
    video_url: str | None = None
    attachments: tuple[Attachment, ...] = ()
    buttons: tuple[RichMessageButton, ...] = ()
    options: tuple[RichMessageOption, ...] = ()
    metadata: dict[str, Any] | None = None
    selects: tuple[RichMessageSelect, ...] = ()
    date_pickers: tuple[RichMessageDatePicker, ...] = ()
    checkboxes: tuple[RichMessageCheckbox, ...] = ()
    inputs: tuple[RichMessageInput, ...] = ()


@dataclass(frozen=True)
class RichMessageFields:
    """富消息字段。

    包装富消息与其回退格式，用于出站负载携带富消息渲染信息，当渠道
    不支持富消息时按回退格式渲染。

    字段：
        rich_message: 富消息内容。
        fallback_format: 回退格式（默认 MARKDOWN）。
    """

    rich_message: RichMessage
    fallback_format: MessageFormat = MessageFormat.MARKDOWN


@dataclass(frozen=True)
class OutboundPayload:
    """出站负载。

    描述出站管道的统一负载，关联 Agent 运行 ID，携带流式分块、可选的
    富消息字段与附件列表，用于驱动出站消息的格式化与投递。

    字段：
        agent_run_id: 关联的 Agent 运行 ID。
        stream_chunks: 流式分块列表（默认空 tuple）。
        rich_message_fields: 富消息字段（可选）。
        attachments: 附件列表（默认空 tuple，FR-51）。
    """

    agent_run_id: str | None = None
    stream_chunks: tuple[str, ...] = ()
    rich_message_fields: RichMessageFields | None = None
    attachments: tuple[Attachment, ...] = ()


@dataclass(frozen=True)
class FormattedMessage:
    """格式化消息。

    描述经格式化后的消息内容，携带文本、格式、可选的富消息与附件列表，
    用于适配器按渠道协议渲染最终消息。

    字段：
        content: 消息文本内容。
        format: 消息格式（默认 TEXT）。
        rich_message: 渲染后的渠道原生富消息对象（可选，由
            RichMessageAdapter.renderRichMessage 产生，类型由具体适配器
            决定）。
        attachments: 附件列表（默认空 tuple，FR-51）。
    """

    content: str
    format: MessageFormat = MessageFormat.TEXT
    rich_message: Any = None
    attachments: tuple[Attachment, ...] = ()


@dataclass(frozen=True)
class TrustedMessage:
    """可信消息。

    描述经服务端强制注入发送者身份与所有者标记的消息，用于可信注入
    边界（FR-25），确保渠道侧无法伪造发送者。

    字段：
        content: 消息文本内容。
        sender_id: 发送者 ID（服务端强制注入）。
        is_owner: 是否为会话所有者（服务端强制注入，默认 False）。
        rich_message: 渲染后的渠道原生富消息对象（可选，从
            FormattedMessage 透传，FR-08）。
    """

    content: str
    sender_id: str
    is_owner: bool = False
    rich_message: Any = None

    def __post_init__(self) -> None:
        """校验必填字段非空。

        ``content`` 与 ``sender_id`` 必须非空，在构造时即抛出
        ``ValidationError``，避免空消息内容或空发送者身份传播到渠道
        适配器（INV-8）。
        """
        if not self.content:
            raise ValidationError("content", "must not be empty")
        if not self.sender_id:
            raise ValidationError("sender_id", "must not be empty")


@dataclass(frozen=True)
class FinalMessage:
    """最终消息。

    描述出站管道最终投递至渠道适配器的消息，携带文本、发送者 ID 与
    可选前缀，前缀用于所有者标记等场景。

    字段：
        content: 消息文本内容。
        sender_id: 发送者 ID。
        prefix: 前缀（可选，如所有者标记）。
        rich_message: 渲染后的渠道原生富消息对象（可选，从
            TrustedMessage 透传，FR-08）。
    """

    content: str
    sender_id: str
    prefix: str | None = None
    rich_message: Any = None

    def __post_init__(self) -> None:
        """校验必填字段非空。

        ``content`` 与 ``sender_id`` 必须非空，在构造时即抛出
        ``ValidationError``，避免空消息内容或空发送者身份投递到渠道
        （INV-8）。
        """
        if not self.content:
            raise ValidationError("content", "must not be empty")
        if not self.sender_id:
            raise ValidationError("sender_id", "must not be empty")


@dataclass(frozen=True)
class BatchSendItem:
    """批量发送单条结果。

    描述 ``OutboundAdapter.batchSendMessages`` 单条投递结果，与
    ``MultiPartReceipt`` 区别：``MultiPartReceipt`` 描述**同一条**逻辑
    消息拆分为多个分片的回执，``BatchSendItem`` 描述**同一负载**投递到
    多个 peer 的逐条结果。

    字段：
        peer_id: 接收目标 ID。
        channel_msg_id: 渠道侧消息 ID（成功时非空，失败时为空字符串）。
        success: 是否投递成功。
        error: 失败时的错误信息（可选，成功时为 ``None``）。
    """

    peer_id: str
    channel_msg_id: str
    success: bool
    error: str | None = None


@dataclass(frozen=True)
class BatchSendResult:
    """批量发送结果。

    描述 ``OutboundAdapter.batchSendMessages`` 的聚合结果，包含逐条结果
    与汇总统计。集合字段使用 tuple 以保证 frozen dataclass 的不可变语义。

    字段：
        total: 总投递目标数。
        succeeded: 成功的目标 ID 元组。
        failed: 失败条目元组（含目标 ID 与错误信息）。
        items: 逐条结果元组（含成功与失败）。
    """

    total: int
    succeeded: tuple[str, ...]
    failed: tuple[BatchSendItem, ...]
    items: tuple[BatchSendItem, ...]