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

"""插件 DTO。

定义插件相关的枚举、不可变值对象与 Protocol，包括权限枚举、环境变量、
领域事件、事件处理 Protocol、控制 RPC 处理 Protocol、配置加载 Protocol
与配置解密 Protocol。所有枚举继承 ``str, Enum`` 以支持 JSON 序列化，
DTO 均为 ``dataclass(frozen=True)``，Protocol 使用 ``@runtime_checkable``
装饰以支持 ``isinstance`` 检查。仅依赖标准库，用于插件生命周期、事件
分发、控制 RPC 与配置加载解密。
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime
from enum import StrEnum
from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable

from yuxi.channels.contract.dtos.common import BatchOperationFailure, Operator

if TYPE_CHECKING:
    from yuxi.channels.contract.plugin.manifest import PluginManifest


class Permission(StrEnum):
    """权限等级。

    标识插件或操作所需的用户权限等级，用于权限校验与审计。继承
    ``str, Enum`` 以支持 JSON 序列化与字符串比较。

    取值：
        REQUIRED_USER: 普通需求用户。
        ADMIN_USER: 管理员用户。
        SUPERADMIN_USER: 超级管理员用户。
    """

    REQUIRED_USER = "required_user"
    ADMIN_USER = "admin_user"
    SUPERADMIN_USER = "superadmin_user"


@dataclass(frozen=True)
class EnvVar:
    """环境变量声明。

    描述插件所需的环境变量元信息，包括名称、描述、是否必填、默认值与
    是否敏感，用于插件安装向导的环境变量校验与脱敏渲染。

    字段：
        name: 环境变量名称。
        description: 环境变量描述。
        required: 是否必填（默认 True）。
        default: 默认值（可选）。
        sensitive: 是否敏感（需脱敏，默认 False）。
    """

    name: str
    description: str
    required: bool = True
    default: str | None = None
    sensitive: bool = False


@dataclass(frozen=True)
class DomainEvent:
    """领域事件。

    描述插件生命周期或业务流程中产生的领域事件，包括事件 ID、事件类型、
    负载、时间戳与链路追踪 ID，用于事件总线分发与审计。

    字段：
        event_id: 事件 ID。
        event_type: 事件类型（PluginLoaded | PairingApproved | ConfigChanged | ...）。
        payload: 事件负载。
        timestamp: 事件时间戳。
        trace_id: 链路追踪 ID（可选）。
    """

    event_id: str
    event_type: str
    payload: dict[str, Any]
    timestamp: datetime
    trace_id: str | None = None


@runtime_checkable
class EventHandler(Protocol):
    """事件处理 Protocol。

    由插件实现，用于订阅并处理领域事件。使用 ``@runtime_checkable``
    装饰以支持 ``isinstance`` 检查。事件处理为异步方法，避免阻塞
    事件总线分发线程。
    """

    async def handle(self, event: DomainEvent) -> None:
        """处理领域事件。

        参数：
            event: 领域事件。
        """
        ...


@runtime_checkable
class ConfigLoader(Protocol):
    """配置加载 Protocol。

    由插件实现，用于加载插件配置并返回配置字典。使用
    ``@runtime_checkable`` 装饰以支持 ``isinstance`` 检查。配置加载
    为同步方法，适用于启动期一次性加载场景。
    """

    def load(self) -> dict[str, Any]:
        """加载插件配置。

        返回:
            配置字典。
        """
        ...


@runtime_checkable
class ConfigDecryptor(Protocol):
    """配置解密 Protocol。

    由插件实现，用于解密敏感配置值。使用 ``@runtime_checkable`` 装饰
    以支持 ``isinstance`` 检查。解密为同步方法，适用于配置加载后
    的就地解密场景。
    """

    def decrypt(self, value: str) -> str:
        """解密配置值。

        参数:
            value: 待解密的配置值。

        返回:
            解密后的明文配置值。
        """
        ...


@dataclass(frozen=True)
class PluginSummary:
    """插件摘要（PLG-QUERY-01 列表项）。

    字段：
        plugin_id: 插件唯一标识（manifest.manifest.id）。
        name: 插件显示名称（manifest.manifest.name）。
        version: 插件版本（manifest.manifest.version）。
        channel_type: 绑定渠道类型（manifest.manifest.channel_type.value）。
        state: 当前生命周期状态（LifecycleState.value）。
    """

    plugin_id: str
    name: str
    version: str
    channel_type: str
    state: str


@dataclass(frozen=True)
class PluginDetail:
    """插件详情（PLG-QUERY-02 响应）。

    字段：
        plugin_id: 插件唯一标识。
        name: 插件显示名称。
        version: 插件版本。
        channel_type: 绑定渠道类型。
        state: 当前生命周期状态。
        manifest: 完整 PluginManifest（含内嵌 ChannelManifest 与
            adapters / stages / event_subscriptions / config_sources）。
            ChannelManifest 含 capabilities / provides / depends /
            config_schema / failure_policy / resource_quota 等字段。
    """

    plugin_id: str
    name: str
    version: str
    channel_type: str
    state: str
    manifest: PluginManifest


@dataclass(frozen=True)
class InstallPluginCmd:
    """安装插件命令（PLG-INSTALL）。

    由 ``PluginManagementPort.installPlugin`` 引用，从来源安装插件，需记录
    操作人以满足审计要求（超级管理员）。

    字段：
        operator: 操作人（审计用）。
        source_type: 来源类型（``path`` / ``url`` / ``registry``）。
        source: 来源路径或 URL。
        version: 指定版本（可选）。
        force: 是否强制覆盖已存在插件（默认 False）。
    """

    operator: Operator
    source_type: str
    source: str
    version: str | None = None
    force: bool = False


@dataclass(frozen=True)
class InstallPluginResult:
    """安装插件结果（PLG-INSTALL）。

    字段：
        plugin_id: 插件 ID。
        version: 安装的插件版本。
        installed_at: 安装时间戳。
        requires_load: 是否需要手动加载（默认 True）。
    """

    plugin_id: str
    version: str
    installed_at: datetime
    requires_load: bool = True


@dataclass(frozen=True)
class UninstallPluginResult:
    """卸载插件结果（PLG-UNINSTALL-FILE）。

    字段：
        plugin_id: 插件 ID。
        uninstalled_at: 卸载时间戳。
        files_removed: 已删除的文件列表。
    """

    plugin_id: str
    uninstalled_at: datetime
    files_removed: tuple[str, ...]


@dataclass(frozen=True)
class PluginConfigResult:
    """插件配置查询结果（PLG-CONFIG）。

    字段：
        plugin_id: 插件 ID。
        config: 当前配置值。
        schema: 配置 schema（从 PluginManifest 获取）。
        requires_restart: 是否需要重启生效。
        updated_at: 配置最后更新时间（可选）。
    """

    plugin_id: str
    config: dict[str, Any]
    schema: dict[str, Any]
    requires_restart: bool
    updated_at: datetime | None = None


@dataclass(frozen=True)
class UpdatePluginConfigCmd:
    """更新插件配置命令（PLG-CONFIG-PUT）。

    由 ``PluginManagementPort.updatePluginConfig`` 引用，按 ``apply_mode``
    判断是否需要重启，需记录操作人以满足审计要求。

    字段：
        plugin_id: 插件 ID。
        operator: 操作人（审计用）。
        config: 配置值。
        apply_mode: 应用模式（``hot`` / ``restart_required``）。
    """

    plugin_id: str
    operator: Operator
    config: dict[str, Any]
    apply_mode: str


@dataclass(frozen=True)
class BatchPluginLifecycleSuccessItem:
    """批量插件生命周期成功条目（PLG-BATCH-LIFE）。

    字段：
        plugin_id: 插件 ID。
        new_state: 新生命周期状态。
    """

    plugin_id: str
    new_state: str


@dataclass(frozen=True)
class BatchPluginLifecycleCmd:
    """批量插件生命周期命令（PLG-BATCH-LIFE）。

    逐条独立事务执行批量启动/停止（模式 D），``plugin_ids`` 与 ``filter``
    二选一（同时为空时由 dispatch handler 决定）。

    字段：
        operator: 操作人（审计用）。
        plugin_ids: 显式插件 ID 元组（默认空元组）。
        filter: 筛选条件（含 channel_type / state，可选）。
    """

    operator: Operator
    plugin_ids: tuple[str, ...] = ()
    filter: dict[str, Any] | None = None


@dataclass(frozen=True)
class BatchPluginLifecycleResult:
    """批量插件生命周期结果（PLG-BATCH-LIFE）。

    描述逐条独立事务执行批量启动/停止的执行结果，``failed`` 使用通用
    ``BatchOperationFailure``（``id`` 字段承载 plugin_id）。

    字段：
        total: 待操作插件总数。
        succeeded: 成功条目元组。
        failed: 失败条目元组。
    """

    total: int
    succeeded: tuple[BatchPluginLifecycleSuccessItem, ...]
    failed: tuple[BatchOperationFailure, ...]