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

"""生命周期 DTO。

定义插件生命周期端口的命令与结果值对象，包括生命周期命令与生命周期结果。
所有 DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库，用于插件的加载、
启动、暂停、恢复、停止、卸载、重载等生命周期操作的命令传递与结果返回。
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any, Literal

from yuxi.channels.contract.errors import ValidationError


@dataclass(frozen=True)
class LifecycleCmd:
    """生命周期命令（PLG-001）。

    由生命周期端口方法引用，描述一次插件生命周期操作请求，携带事件类型、
    插件 ID 与操作参数。事件类型覆盖 load / start / pause / resume / stop /
    unload / reload 等场景。

    字段：
        event: 生命周期事件（load | start | pause | resume | stop | unload | reload）。
        plugin_id: 插件 ID。
        params: 操作参数（可选）。
    """

    event: Literal["load", "start", "pause", "resume", "stop", "unload", "reload"]
    plugin_id: str
    params: dict[str, Any] | None = None

    def __post_init__(self) -> None:
        """校验必填字段非空与事件取值。

        ``plugin_id`` 必须非空，``event`` 必须为 ``load`` / ``start`` /
        ``pause`` / ``resume`` / ``stop`` / ``unload`` / ``reload`` 之一，
        在构造时即抛出 ``ValidationError``，adapter 不再做该校验（INV-8）。
        """
        if not self.plugin_id:
            raise ValidationError("plugin_id", "must not be empty")
        if self.event not in (
            "load",
            "start",
            "pause",
            "resume",
            "stop",
            "unload",
            "reload",
        ):
            raise ValidationError(
                "event",
                "must be one of: load, start, pause, resume, stop, unload, reload",
            )


@dataclass(frozen=True)
class LifecycleResult:
    """生命周期结果（PLG-001）。

    描述插件生命周期操作的执行结果，携带状态与错误信息，用于结果汇报与
    异常归因。状态覆盖 discovered / resolved / loaded / initialized / started /
    paused / stopped / unloaded / failed 等场景。

    字段：
        state: 生命周期状态。
        error: 错误信息（可选）。
        error_code: 错误码（用例服务捕获异常时填充，默认空字符串）。
        trace_id: 追踪 ID（用例服务捕获异常时填充，默认空字符串）。
    """

    state: Literal[
        "discovered", "resolved", "loaded", "initialized", "started", "paused", "stopped", "unloaded", "failed"
    ]
    error: str | None = None
    error_code: str = ""
    trace_id: str = ""