"""缓存 DTO。

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

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime


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

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

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

    key: str
    value: str
    expires_at: datetime