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

"""队列 DTO。

定义队列端口的命令与值对象，包括入队命令、任务 ID 与任务状态。所有 DTO
均为 ``dataclass(frozen=True)``，仅依赖标准库，用于异步任务的入队与
状态追踪。
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime
from enum import StrEnum
from typing import Any

from yuxi.channels.contract.errors import ValidationError


@dataclass(frozen=True)
class EnqueueCmd:
    """入队命令（QUE-001）。

    由队列端口方法引用，描述一次异步任务入队请求，携带任务名称、负载、
    计划执行时间与幂等键，用于异步任务调度。

    字段：
        task_name: 任务名称。
        payload: 任务负载。
        scheduled_at: 计划执行时间（可选）。
        idempotency_key: 幂等键（可选）。
    """

    task_name: str
    payload: dict[str, Any]
    scheduled_at: datetime | None = None
    idempotency_key: str | None = None

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

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


@dataclass(frozen=True)
class JobId:
    """任务 ID。

    标识一次异步任务的唯一 ID，用于任务状态查询与结果关联。

    字段：
        value: 任务 ID 字符串。
    """

    value: str


class JobStatus(StrEnum):
    """任务状态。

    标识异步任务的执行状态，用于任务状态查询与结果聚合。继承
    ``str, Enum`` 以支持 JSON 序列化与字符串比较。

    取值：
        QUEUED: 已入队。
        RUNNING: 执行中。
        COMPLETED: 已完成。
        FAILED: 已失败。
        CANCELLED: 已取消。
    """

    QUEUED = "queued"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"
    CANCELLED = "cancelled"