"""配对 DTO。 定义 DM 安全与配对审批的不可变值对象，包括配对 ID、配对状态、DM 决策、 DM 策略、配对审批、配对记录与机器人循环预算。所有 DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库，用于 DM 安全策略决策与配对 审批流程。 """ from __future__ import annotations from dataclasses import dataclass from datetime import datetime from enum import StrEnum from yuxi.channels.contract.dtos.channel import ChannelType from yuxi.channels.contract.dtos.common import Operator from yuxi.channels.contract.errors import ValidationError @dataclass(frozen=True) class PairingId: """配对 ID。 标识一次配对审批流程的全局唯一 ID，用于配对记录关联与审计。 字段： value: 配对 ID 字符串。 """ value: str class PairingStatus(StrEnum): """配对状态。 标识配对审批流程的当前状态，用于配对记录查询与状态机流转。继承 ``str, Enum`` 以支持 JSON 序列化与字符串比较。 取值： PENDING: 待审批。 APPROVED: 已批准。 REJECTED: 已拒绝。 EXPIRED: 已过期。 REVOKED: 已撤销（FR-33，已批准的配对被主动撤销）。 """ PENDING = "pending" APPROVED = "approved" REJECTED = "rejected" EXPIRED = "expired" REVOKED = "revoked" class DmDecision(StrEnum): """DM 决策。 描述 DM 消息的处置决策结果，用于入站管道的 DM 安全策略执行。继承 ``str, Enum`` 以支持 JSON 序列化与字符串比较。 取值： ALLOW: 允许。 DENY: 拒绝。 PENDING_PAIRING: 待配对审批。 WHITELIST: 白名单放行。 """ ALLOW = "allow" DENY = "deny" PENDING_PAIRING = "pending_pairing" WHITELIST = "whitelist" class DmPolicy(StrEnum): """DM 策略。 描述渠道账户的 DM 安全策略，用于 DM 决策引擎的策略匹配。继承 ``str, Enum`` 以支持 JSON 序列化与字符串比较。 取值： ALLOW: 允许所有 DM。 DENY: 拒绝所有 DM。 PAIRING_REQUIRED: 需配对审批。 WHITELIST: 白名单。 """ ALLOW = "allow" DENY = "deny" PAIRING_REQUIRED = "pairing_required" WHITELIST = "whitelist" @dataclass(frozen=True) class PairingApproval: """配对审批。 描述一次配对审批的结果，携带配对 ID、渠道账户 ID、对端 ID、状态、 审批人与过期时间，用于审批结果回传与审计。 字段： pairing_id: 配对 ID。 channel_account_id: 渠道账户 ID。 peer_id: 对端 ID。 status: 配对状态。 approver_id: 审批人 ID（待审批时为 None）。 approved_at: 审批时间（待审批时为 None）。 expires_at: 过期时间（可选）。 """ pairing_id: str channel_account_id: str peer_id: str status: PairingStatus approver_id: str | None = None approved_at: datetime | None = None expires_at: datetime | None = None @dataclass(frozen=True) class PairingRecord: """配对记录。 描述一条配对审批的持久化记录，携带配对 ID、渠道账户业务 ID、渠道类型、 对端信息、状态、审批人与全量时间戳，用于管理员审批列表查询（FR-33）、 状态机流转与审计追溯。 ``channel_type`` 与 ``account_id`` 由适配器层在查询时通过 ``channel_accounts`` 表关联填充，供管理后台展示与降级检查使用；``listExpiredPendingPairings`` 等内部场景可不填充（保持 ``None``）。 字段： pairing_id: 配对 ID（业务标识，UUID）。 channel_account_id: 渠道账户业务 ID（字符串，与 ``channel_type`` 共同确定账户作用域）。 channel_type: 渠道类型（可选，适配器层关联填充）。 peer_id: 对端用户 ID。 peer_name: 对端名称（冗余展示字段，可选）。 status: 配对状态。 approver_id: 审批人 ID（待审批时为 ``None``）。 approved_at: 批准时间（approved 状态时填充，可选）。 rejected_at: 拒绝时间（rejected 状态时填充，可选）。 expired_at: 过期生效时间（expired 状态时填充，由定时任务或审批时回填，可选）。 revoked_at: 撤销时间（revoked 状态时填充，FR-33，可选）。 reason: 审批原因 / 拒绝原因 / 撤销原因（可选）。 created_at: 创建时间（可选）。 updated_at: 更新时间（可选）。 expires_at: 过期时间（可选，供过期扫描器重建聚合根调用 ``expireIfOverdue``）。 requested_at: 申请时间（可选，供管理后台按申请时间排序展示）。 version: 乐观锁版本号（默认 1）。 """ pairing_id: str channel_account_id: str peer_id: str status: PairingStatus channel_type: ChannelType | None = None peer_name: str | None = None approver_id: str | None = None approved_at: datetime | None = None rejected_at: datetime | None = None expired_at: datetime | None = None revoked_at: datetime | None = None reason: str | None = None created_at: datetime | None = None updated_at: datetime | None = None expires_at: datetime | None = None requested_at: datetime | None = None version: int = 1 @dataclass(frozen=True) class PairingQuery: """配对查询。 描述配对审批记录的查询条件，支持按渠道类型、账户、对端用户、状态过滤 与分页，用于管理员配对审批列表查询（FR-33 ``pairing/list`` 操作）。 ``channel_type`` 与 ``account_id`` 共同确定渠道账户作用域，仅提供其一 时按提供的条件过滤。 字段： channel_type: 渠道类型（可选）。 account_id: 渠道账户业务 ID（可选）。 peer_id: 对端用户 ID（可选）。 status: 配对状态（可选）。 created_after: 申请时间下界（可选，含，按 ``requested_at`` 过滤）。 created_before: 申请时间上界（可选，含，按 ``requested_at`` 过滤）。 limit: 分页大小（默认 100）。 offset: 分页偏移（默认 0）。 """ channel_type: ChannelType | None = None account_id: str | None = None peer_id: str | None = None status: PairingStatus | None = None created_after: datetime | None = None created_before: datetime | None = None limit: int = 100 offset: int = 0 @dataclass(frozen=True) class BotLoopBudget: """机器人循环预算。 描述机器人回复的速率限制预算，包括每小时最大回复数、冷却时间、当前计数 与上次回复时间，用于防止机器人循环与速率限制。 字段： max_replies_per_hour: 每小时最大回复数。 cooldown_seconds: 冷却时间（秒）。 current_count: 当前计数（默认 0）。 last_reply_at: 上次回复时间（可选）。 """ max_replies_per_hour: int cooldown_seconds: int current_count: int = 0 last_reply_at: datetime | None = None @dataclass(frozen=True) class CreatePairingResult: """创建配对结果（FR-33）。 描述创建配对请求操作的返回结果，包含新创建的配对记录信息。 字段： pairing_id: 配对 ID。 channel_account_id: 渠道账户 ID。 peer_id: 对端 ID。 status: 配对状态（应为 PENDING）。 expires_at: 过期时间。 created_at: 创建时间。 """ pairing_id: str channel_account_id: str peer_id: str status: PairingStatus expires_at: datetime created_at: datetime @dataclass(frozen=True) class BatchPairingCmd: """批量配对命令（PRG-BATCH-ACT）。 由 ``PairingManagementPort.batchApprovePairings`` / ``batchRejectPairings`` 引用，操作类型由调用的方法名隐式确定 （``batchApprovePairings`` → approve，``batchRejectPairings`` → reject）。 字段： pairing_ids: 配对 ID 元组（必填）。 operator: 操作人（审计用）。 reason: 操作原因（可选，最长 512）。 """ pairing_ids: tuple[str, ...] operator: Operator reason: str | None = None def __post_init__(self) -> None: """校验业务规则（PRG-BATCH-ACT）。 - ``pairing_ids`` 非空且长度 ≤ 500。 - ``reason`` 非空时长度 ≤ 512。 在构造时即抛出 ``ValidationError``，避免非法值传播到 dispatch handler 后才暴露（INV-8）。 """ if not self.pairing_ids: raise ValidationError("pairing_ids", "pairing_ids must not be empty") if len(self.pairing_ids) > 500: raise ValidationError( "pairing_ids", f"pairing_ids length must be <= 500, got {len(self.pairing_ids)}", ) if self.reason is not None and len(self.reason) > 512: raise ValidationError( "reason", f"reason length must be <= 512, got {len(self.reason)}", ) @dataclass(frozen=True) class CleanExpiredPairingsCmd: """清理过期配对命令（PRG-CLEAN-EXPIRED）。 由 ``PairingManagementPort.cleanExpiredPairings`` 引用，单一事务批量 更新过期配对为 EXPIRED 状态。 字段： operator: 操作人（审计用）。 channel_type: 渠道类型过滤（可选）。 older_than: 过期时间上界（ISO 8601，缺省取所有过期）。 max_count: 单次最大清理数（默认 500，1-1000）。 """ operator: Operator channel_type: ChannelType | None = None older_than: datetime | None = None max_count: int = 500 def __post_init__(self) -> None: """校验业务规则（PRG-CLEAN-EXPIRED）。 ``max_count`` 必须在 ``[1, 1000]`` 区间，在构造时即抛出 ``ValidationError``，避免非法值传播到 dispatch handler 后才暴露 （INV-8）。 """ if self.max_count < 1 or self.max_count > 1000: raise ValidationError( "max_count", f"max_count must be between 1 and 1000, got {self.max_count}", ) @dataclass(frozen=True) class PairingStatsQuery: """配对统计查询（PRG-STATS）。 描述配对统计的查询条件，由 ``PairingRepositoryPort.getPairingStats`` 消费。``granularity`` 取值 ``hour`` / ``day`` / ``week``，默认 ``day``。 字段： channel_type: 渠道类型过滤（可选）。 start_time: 起始时间（可选，含）。 end_time: 结束时间（可选，含）。 granularity: 时间粒度（默认 ``day``）。 """ channel_type: ChannelType | None = None start_time: datetime | None = None end_time: datetime | None = None granularity: str = "day" def __post_init__(self) -> None: """校验业务规则（PRG-STATS）。 ``granularity`` 必须为 ``hour`` / ``day`` / ``week``，在构造时即 抛出 ``ValidationError``，避免非法值传播到仓储层后才暴露（INV-8）。 """ if self.granularity not in ("hour", "day", "week"): raise ValidationError( "granularity", f"granularity must be 'hour', 'day' or 'week', got {self.granularity!r}", ) @dataclass(frozen=True) class PairingTrendPoint: """配对趋势点（PRG-STATS）。 描述按时间粒度切片的配对趋势数据点，含申请数与批准数。 字段： timestamp: 时间桶起始时间。 requested: 申请数。 approved: 批准数。 """ timestamp: datetime requested: int approved: int @dataclass(frozen=True) class PairingStatsResult: """配对统计结果（PRG-STATS）。 描述配对审批的聚合统计指标，由 ``getPairingStats`` 返回。 字段： total_requested: 申请总数。 approved_count: 批准数。 rejected_count: 拒绝数。 revoked_count: 撤销数。 expired_count: 过期数。 approve_rate: 批准率（0-100）。 avg_approval_seconds: 平均审批时长（秒）。 trend: 配对趋势数据点元组。 """ total_requested: int approved_count: int rejected_count: int revoked_count: int expired_count: int approve_rate: float avg_approval_seconds: float trend: tuple[PairingTrendPoint, ...]