Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
79 lines
2.0 KiB
Python
79 lines
2.0 KiB
Python
"""队列 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"
|