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

"""缓存 DTO。

定义缓存端口的值对象，包括锁令牌。所有 DTO 均为
``dataclass(frozen=True)``，仅依赖标准库，用于分布式锁管理。
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime

from yuxi.channels.contract.errors import ValidationError


@dataclass(frozen=True)
class LockToken:
    """锁令牌。

    标识一次分布式锁获取的令牌，携带锁键、令牌值与过期时间，用于锁续期与
    释放校验。``key`` 字段使释放操作能从令牌还原锁键，避免适配器维护跨
    请求的 ``token -> key`` 映射（ADP-023 / INV-5）。

    字段：
        key: 锁键（获取时传入，释放时还原）。
        value: 令牌值。
        expires_at: 过期时间。
    """

    key: str
    value: str
    expires_at: datetime

    def __post_init__(self) -> None:
        """校验 key 与 value 非空。

        ``key`` 与 ``value`` 必须非空，在构造时即抛出 ``ValidationError``，
        避免空锁键或空令牌值导致锁释放校验失效（INV-8）。
        """
        if not self.key:
            raise ValidationError("key", "must not be empty")
        if not self.value:
            raise ValidationError("value", "must not be empty")