"""控制面 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.channel import ChannelType
from yuxi.channels.contract.dtos.common import FailureDetail, Operator
from yuxi.channels.contract.errors import ValidationError


@dataclass(frozen=True)
class ControlCmd:
    """控制命令。

    由控制面端口方法引用，描述一次控制面操作请求，携带操作类型、目标渠道、
    参数与操作人。操作类型覆盖 wizard / doctor / whitelist / directory /
    pairing / config / session / plugin / health / diagnostics / audit /
    message 等场景。

    字段：
        operation: 操作类型。
        target_channel: 目标渠道类型（可选）。
        params: 操作参数（可选）。
        operator: 操作人（审计用）。
    """

    operation: str
    operator: Operator
    target_channel: ChannelType | None = None
    params: dict[str, Any] | None = None

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

        ``operation`` 必须非空，在构造时即抛出 ``ValidationError``，
        adapter 不再做该校验（INV-8）。
        """
        if not self.operation:
            raise ValidationError("operation", "must not be empty")


@dataclass(frozen=True)
class ControlResult:
    """控制结果。

    描述控制面操作的执行结果，携带状态、数据与错误详情，用于结果汇报与
    错误聚合。集合字段使用 tuple 以保证不可变。

    字段：
        status: 执行状态（success | failed | partial）。
        data: 返回数据（可选）。
        errors: 错误详情列表（默认空 tuple）。
    """

    status: str
    data: dict[str, Any] | None = None
    errors: tuple[FailureDetail, ...] = ()