"""Outbox DTO。 定义发件箱相关的不可变值对象，包括发件箱 ID、发件箱状态枚举、消息 持久化策略枚举、投递回执、多分片回执与发件箱条目。所有 DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库与契约层内部类型，用于 持久化投递、重试控制与死信管理（FR-22）。 """ from __future__ import annotations from dataclasses import dataclass, field from datetime import datetime from enum import StrEnum from typing import TYPE_CHECKING, Any, Literal from yuxi.channels.contract.dtos.channel import ChannelType from yuxi.channels.contract.dtos.common import TrendDataPoint from yuxi.channels.contract.errors import ValidationError if TYPE_CHECKING: from yuxi.channels.contract.dtos.outbound import FormattedMessage @dataclass(frozen=True) class OutboxId: """发件箱 ID。 标识一条发件箱条目的唯一 ID，用于持久化投递追踪与状态同步。 字段： value: 发件箱 ID 字符串。 """ value: str class OutboxStatus(StrEnum): """发件箱状态。 标识发件箱条目的生命周期状态，用于投递流程控制与重试决策。继承 ``str, Enum`` 以支持 JSON 序列化与字符串比较。 取值： PENDING: 待发送。 SENT: 已发送。 SUPPRESSED: 已抑制（栅栏拦截）。 FAILED: 已失败。 SENT_UNCONFIRMED: 已发未确认。 DEAD: 死信（重试超限）。 """ PENDING = "pending" SENT = "sent" SUPPRESSED = "suppressed" FAILED = "failed" SENT_UNCONFIRMED = "sent_unconfirmed" DEAD = "dead" class MessageDurabilityPolicy(StrEnum): """消息持久化策略。 标识消息投递的持久化等级，用于权衡投递可靠性与性能。继承 ``str, Enum`` 以支持 JSON 序列化与字符串比较。 取值： REQUIRED: 必须持久化（强可靠）。 BEST_EFFORT: 尽力持久化。 NONE: 不持久化。 """ REQUIRED = "required" BEST_EFFORT = "best_effort" NONE = "none" @dataclass(frozen=True) class DeliveryReceipt: """投递回执（FR-22）。 描述一次投递的回执信息，包括发件箱 ID、状态、渠道侧消息 ID、重试 次数与下次重试时间，用于投递状态同步与重试调度。 字段： outbox_id: 发件箱 ID。 status: 发件箱状态。 channel_msg_id: 渠道侧消息 ID（可选）。 retry_count: 重试次数（默认 0）。 next_retry_at: 下次重试时间（可选）。 """ outbox_id: str status: OutboxStatus channel_msg_id: str | None = None retry_count: int = 0 next_retry_at: datetime | None = None @dataclass(frozen=True) class MultiPartReceipt: """多分片回执（FR-22）。 描述一条消息在渠道侧拆分为多个分片投递的回执，包括平台消息 ID、 分片类型、序号、可选的话题 / 回复目标 ID 与分片投递结果，用于 多分片消息的状态同步与部分失败判定（FR-22）。 字段： platform_msg_id: 平台消息 ID。 part_type: 分片类型（text / card / attachment）。 sequence: 序号（默认 0）。 topic_id: 话题 ID（可选）。 reply_target_id: 回复目标 ID（可选）。 success: 分片投递是否成功（默认 True）。``False`` 表示该分片 投递失败，``DeliverStage`` 据此判定部分失败。 """ platform_msg_id: str part_type: Literal["text", "card", "attachment"] sequence: int = 0 topic_id: str | None = None reply_target_id: str | None = None success: bool = True @dataclass(frozen=True) class OutboxConfig: """Outbox 配置。 描述发件箱投递相关的可配置参数，由组合根从配置源加载并注入到应用层 阶段，解耦应用层对全局配置的依赖（§6.1 应用服务层禁止依赖具体技术 适配器）。 字段： ttl_seconds: 发件箱条目存活时间（秒），``expires_at`` 缺失时 用于回退计算过期时间。 retry_backoff_schedule: 指数退避序列（秒），由聚合根 ``markFailed`` 计算 ``next_retry_at`` 时使用。 max_retry: 最大重试次数（默认 5，镜像聚合根）。 failed_retry_enabled: 是否启用 FAILED 状态自动重试扫描（默认 True， O-04/H-7）。禁用时恢复扫描器跳过 FAILED 条目，仅由运维通过 batch-retry 端点手动重投。 failed_retry_interval_seconds: FAILED 条目重试最小间隔（秒，默认 300）。 仅扫描 ``updated_at`` 距今超过此间隔的条目，避免刚失败的条目 被立即重试导致风暴。 sent_unconfirmed_timeout_seconds: SENT_UNCONFIRMED 无回执超时（秒， 默认 300）。Scanner 判定 SENT_UNCONFIRMED 消息无回执的超时秒数， 超过此时间视为可能已发送但无回执。 retry_lock_ttl_seconds: Worker 单条消息重试的分布式锁 TTL（秒，默认 60）。覆盖一次网络调用 + DB 持久化 + 事件发布的完整周期。 """ ttl_seconds: int retry_backoff_schedule: tuple[int, ...] max_retry: int = 5 failed_retry_enabled: bool = True failed_retry_interval_seconds: int = 300 sent_unconfirmed_timeout_seconds: int = 300 retry_lock_ttl_seconds: int = 60 def __post_init__(self) -> None: """校验配置参数合法性。""" if self.ttl_seconds <= 0: raise ValidationError("ttl_seconds", "must be a positive integer") if self.max_retry <= 0: raise ValidationError("max_retry", "must be a positive integer") if not self.retry_backoff_schedule: raise ValidationError("retry_backoff_schedule", "must be a non-empty list") if self.failed_retry_interval_seconds <= 0: raise ValidationError( "failed_retry_interval_seconds", "must be a positive integer", ) if self.sent_unconfirmed_timeout_seconds <= 0: raise ValidationError( "sent_unconfirmed_timeout_seconds", "must be a positive integer", ) if self.retry_lock_ttl_seconds <= 0: raise ValidationError( "retry_lock_ttl_seconds", "must be a positive integer", ) @classmethod def default(cls) -> OutboxConfig: """构造默认 OutboxConfig 实例。 集中声明默认值，供装配期在配置缺失时使用，消除应用层 三处重复硬编码（deliver_stage / outbox_mark_failed / outbox_rollback）。 默认值： ttl_seconds: 86400（24 小时）。 retry_backoff_schedule: (60, 120, 300, 600, 1800)（指数退避序列）。 max_retry: 5。 failed_retry_enabled: True（O-04 FAILED 自动重试默认启用）。 failed_retry_interval_seconds: 300（5 分钟最小重试间隔）。 sent_unconfirmed_timeout_seconds: 300（5 分钟无回执超时）。 retry_lock_ttl_seconds: 60（单条重试锁 TTL）。 """ return cls( ttl_seconds=86400, retry_backoff_schedule=(60, 120, 300, 600, 1800), max_retry=5, failed_retry_enabled=True, failed_retry_interval_seconds=300, sent_unconfirmed_timeout_seconds=300, retry_lock_ttl_seconds=60, ) class OutboxConfigHolder: """OutboxConfig 可变持有器，支持运行时热更新。 ``OutboxConfig`` 本身为 ``frozen=True`` 不可变值对象，无法在运行时 修改字段。本持有器封装可变引用，使 ``updateRetryPolicy`` 操作能够 热更新配置，并被同一请求范围内的 handler / pipeline / adapter 共享 读取。跨请求与跨进程一致性通过 ``ConfigPort``（Redis）持久化保证。 使用方式： - 组合根创建 holder 实例并注入到需要读取配置的组件。 - ``OutboxHandler.updateRetryPolicy`` 调用 ``holder.update()`` 热更新。 - 其他组件通过 ``holder.current`` 读取最新配置。 """ def __init__(self, config: OutboxConfig) -> None: self._config = config @property def current(self) -> OutboxConfig: """返回当前持有的 OutboxConfig 实例。""" return self._config def update(self, config: OutboxConfig) -> None: """热更新持有的 OutboxConfig 实例。 参数： config: 新的 OutboxConfig 实例。 """ self._config = config @dataclass(frozen=True) class OutboxEntry: """发件箱条目。 描述一条发件箱条目的完整状态，包括发件箱 ID、消息 ID、渠道账户 ID、状态、持久化策略、重试信息与时间戳，用于持久化投递的全流程 管理（FR-22）。 字段： outbox_id: 发件箱 ID。 message_id: 消息 ID。BEST_EFFORT 轻量记录允许 ``None``（消息持久化 失败但仍需追踪投递状态的降级路径，O-01/C-6）。 channel_account_id: 渠道账户 ID。 status: 发件箱状态。 durability_policy: 消息持久化策略。 retry_count: 重试次数（默认 0）。 max_retry: 最大重试次数（默认 5，镜像聚合根）。 next_retry_at: 下次重试时间（可选）。 last_error: 最近错误信息（可选）。 created_at: 创建时间（可选）。 updated_at: 更新时间（可选）。 expires_at: 过期时间（可选，默认 created_at + 24h，镜像聚合根）。 channel_msg_id: 渠道侧消息 ID（可选，投递成功时填充）。 version: 乐观锁版本号（默认 1，完整更新时用于并发控制）。 channel_session_id: 渠道会话 ID（可选，业务标识 session_id UUID）。 由 ORM ``channel_session_id``（int FK）经 mapper 转换为 ``str`` 业务标识填充。重试 worker 当前仍通过 ORM 反查 ``channel_session_id`` 列（int PK）定位 peer_id，本字段 供其他消费方按业务标识引用会话（FR-22）。 latency_ms: 投递延迟（毫秒，可选）。仅 ``markSent`` 首次调用时 计算，供聚合视图域 analytics 子域延迟分布查询使用。默认 ``None`` 保证向后兼容历史数据。 funnel_node: 漏斗节点（可选，取值 enter / sent / suppressed / failed / dead）。供聚合视图域 analytics 子域漏斗聚合查询 使用。默认 ``None`` 保证向后兼容历史数据。 sent_at: 首次成功投递时间（可选）。``markSent`` 首次调用时写入， 供诊断与 SLA 审计使用。默认 ``None`` 保证向后兼容历史数据。 last_retry_at: 上次重试时间（可选）。``markFailed`` / ``markDeliveryUnconfirmedFailed`` 调用时写入，用于诊断退避 进度与 SLA。默认 ``None`` 保证向后兼容历史数据。 channel_type: 渠道类型（可选）。由列表查询关联 ``channel_accounts`` 表填充，供管理后台展示与级联筛选使用。 idempotency_key: 幂等键（可选）。出站投递幂等控制用，跨重试稳定， 供适配器侧去重与 ``sendMessageContinuation`` 续发定位。 channel_request_id: 渠道请求 ID（可选）。适配器 ``sendMessage`` 等 调用生成的请求标识，供 ``queryMessageByRequestId`` 反查投递结果。 partial_failure: 是否部分失败（默认 False）。多分片投递时部分分片 失败置 True，供下游阶段判定降级与重试策略。 stream_aborted_at_chunk: 流式中断时分片序号（可选）。流式投递被 中断时记录已发送分片序号，供 ``sendMessageContinuation`` 续发。 degraded_reason: 降级原因（可选）。投递降级时记录原因，供可观测性 与审计使用。 delivered_parts: 已成功投递的分片序号列表（默认空列表）。多分片 投递部分失败时记录已投递分片，重试时据此仅发送未投递分片（H-15）。 """ outbox_id: str message_id: str | None channel_account_id: str status: OutboxStatus durability_policy: MessageDurabilityPolicy retry_count: int = 0 max_retry: int = 5 next_retry_at: datetime | None = None last_error: str | None = None created_at: datetime | None = None updated_at: datetime | None = None expires_at: datetime | None = None channel_msg_id: str | None = None version: int = 1 channel_session_id: str | None = None latency_ms: int | None = None funnel_node: Literal["enter", "sent", "suppressed", "failed", "dead"] | None = None sent_at: datetime | None = None last_retry_at: datetime | None = None channel_type: ChannelType | None = None idempotency_key: str | None = None channel_request_id: str | None = None partial_failure: bool = False stream_aborted_at_chunk: int | None = None degraded_reason: str | None = None delivered_parts: list[int] = field(default_factory=list) @dataclass(frozen=True) class RetryContext: """Outbox 重试上下文 DTO（FR-22）。 封装 ``OutboxRetryWorker`` 重试所需的渠道上下文，由 ``PersistencePort.resolveRetryContext`` 解析后返回，消除应用层 对 SQLAlchemy ORM 的直接依赖（INV-1）。 字段： channel_type: 渠道类型字符串（由 manifest 声明，如 ``"feishu"`` / ``"custom"``）。 account_id: 渠道账户业务 ID（str，非 ORM 主键）。 peer_id: 对端 ID（接收方标识）。 message: 完整的格式化消息对象（``FormattedMessage``），保留 ``format`` / ``rich_message`` / ``attachments``，避免重试时 富媒体 / 卡片消息退化为纯文本。 """ channel_type: str account_id: str peer_id: str message: "FormattedMessage" # noqa: UP037 @dataclass(frozen=True) class OutboxQueryFilter: """Outbox 查询过滤条件（OBX-01 / OBX-04）。 描述 outbox 条目列表查询与统计的过滤条件，所有字段可选，未提供时 表示不按该维度过滤。由驱动端口 ``listOutboxEntries`` / ``countOutboxEntries`` 消费，被驱动端口 ``OutboxRepositoryPort`` 实现解析为持久化查询条件。 字段： channel_type: 渠道类型（可选）。 channel_account_id: 渠道账户 ID（可选）。 status: 发件箱状态（可选）。 message_id: 消息 ID（可选）。 channel_msg_id: 渠道侧消息 ID（可选）。 created_after: 创建时间下界（可选，含）。 created_before: 创建时间上界（可选，含）。 channel_session_id: 渠道会话 ID（可选）。 retry_count_min: 最小重试次数下界（可选，含）。仅返回 ``retry_count >= retry_count_min`` 的条目，用于筛选已发生重试 的条目（如排查反复失败的投递）。 message_id_like: 消息 ID 模糊搜索（可选，SQL ``LIKE`` 子串匹配）。 channel_msg_id_like: 渠道侧消息 ID 模糊搜索（可选，SQL ``LIKE``）。 channel_account_id_like: 渠道账户 ID 模糊搜索（可选，SQL ``LIKE``）。 last_error_like: 最近错误关键词筛选（可选，SQL ``LIKE``）。 """ channel_type: ChannelType | None = None channel_account_id: str | None = None status: OutboxStatus | None = None message_id: str | None = None channel_msg_id: str | None = None created_after: datetime | None = None created_before: datetime | None = None channel_session_id: str | None = None retry_count_min: int | None = None message_id_like: str | None = None channel_msg_id_like: str | None = None channel_account_id_like: str | None = None last_error_like: str | None = None def __post_init__(self) -> None: """校验过滤条件合法性。 - ``retry_count_min`` 非空时必须 >= 0。 - ``created_after`` 与 ``created_before`` 同时提供时， ``created_after`` 必须早于 ``created_before``。 """ if self.retry_count_min is not None and self.retry_count_min < 0: raise ValidationError("retry_count_min", "must be a non-negative integer") if ( self.created_after is not None and self.created_before is not None and self.created_after >= self.created_before ): raise ValidationError("time_range", "created_after must be earlier than created_before") def to_dict(self) -> dict[str, Any]: """序列化为 dict，仅包含非 None 字段。 ``channel_type`` 与 ``status`` 序列化为 ``.value`` 字符串， ``datetime`` 序列化为 ISO 8601 字符串，供日志输出与审计记录使用。 """ result: dict[str, Any] = {} if self.channel_type is not None: result["channel_type"] = self.channel_type if self.channel_account_id is not None: result["channel_account_id"] = self.channel_account_id if self.status is not None: result["status"] = self.status.value if self.message_id is not None: result["message_id"] = self.message_id if self.channel_msg_id is not None: result["channel_msg_id"] = self.channel_msg_id if self.created_after is not None: result["created_after"] = self.created_after.isoformat() if self.created_before is not None: result["created_before"] = self.created_before.isoformat() if self.channel_session_id is not None: result["channel_session_id"] = self.channel_session_id if self.retry_count_min is not None: result["retry_count_min"] = self.retry_count_min if self.message_id_like is not None: result["message_id_like"] = self.message_id_like if self.channel_msg_id_like is not None: result["channel_msg_id_like"] = self.channel_msg_id_like if self.channel_account_id_like is not None: result["channel_account_id_like"] = self.channel_account_id_like if self.last_error_like is not None: result["last_error_like"] = self.last_error_like return result @dataclass(frozen=True) class OutboxStats: """Outbox 统计信息（OBX-02）。 描述 outbox 条目按状态分组的计数快照与诊断指标，由 ``getOutboxStats`` 返回，供管理后台展示投递健康度。所有计数仅含 ``is_deleted=0`` 条目。 字段： total: 条目总数。 pending: 待发送条目数。 sent: 已发送条目数。 suppressed: 已抑制条目数。 failed: 已失败条目数。 sent_unconfirmed: 已发未确认条目数。 dead: 死信条目数。 top_errors: 最近错误 Top5，每项含 ``error`` 与 ``count``。 avg_latency_ms: 平均投递延迟（毫秒），无数据时为 ``None``。 oldest_pending_at: 最早 pending 条目创建时间，无 pending 时为 ``None``。 """ total: int pending: int sent: int suppressed: int failed: int sent_unconfirmed: int dead: int top_errors: tuple[dict[str, Any], ...] = () avg_latency_ms: float | None = None oldest_pending_at: datetime | None = None def to_dict(self) -> dict[str, Any]: """序列化为 dict，供控制面结果返回与日志输出使用。""" return { "total": self.total, "pending": self.pending, "sent": self.sent, "suppressed": self.suppressed, "failed": self.failed, "sent_unconfirmed": self.sent_unconfirmed, "dead": self.dead, "top_errors": list(self.top_errors), "avg_latency_ms": self.avg_latency_ms, "oldest_pending_at": self.oldest_pending_at.isoformat() if self.oldest_pending_at else None, } @dataclass(frozen=True) class BatchRetryResult: """批量重投死信结果（OBX-001）。 描述死信批量重投操作的执行结果，包括成功入队数量与失败条目。 字段： retried_count: 成功入队重投的条目数。 failed_count: 重投失败的条目数。 retried_at: 重投执行时间。 """ retried_count: int failed_count: int retried_at: datetime @dataclass(frozen=True) class BatchDeleteResult: """批量删除死信结果（OBX-002）。 描述死信批量删除操作的执行结果，包括成功删除数量。 字段： deleted_count: 成功删除的条目数。 deleted_at: 删除执行时间。 """ deleted_count: int deleted_at: datetime @dataclass(frozen=True) class RetryPolicySnapshot: """重试策略快照（OBX-003）。 描述 Outbox 重试策略的只读快照，用于查询与更新操作返回。 字段： max_retry: 最大重试次数。 ttl_seconds: 条目存活时间（秒）。 retry_backoff_schedule: 指数退避序列（秒）。 updated_at: 策略更新时间（可选，默认策略时为 None）。 """ max_retry: int ttl_seconds: int retry_backoff_schedule: tuple[int, ...] updated_at: datetime | None = None def __post_init__(self) -> None: """校验策略参数合法性。""" if self.max_retry <= 0: raise ValidationError("max_retry", "must be a positive integer") if self.ttl_seconds <= 0: raise ValidationError("ttl_seconds", "must be a positive integer") if not self.retry_backoff_schedule: raise ValidationError("retry_backoff_schedule", "must be a non-empty list") @dataclass(frozen=True) class DeadLetterExportCmd: """死信导出命令（OBX-DL-EXPORT）。 描述死信导出查询条件，由 ``OutboxRepositoryPort.exportDeadLetters`` 消费。 ``format`` 取值 ``json`` / ``csv``，默认 ``json``。 字段： channel_type: 渠道类型过滤（可选）。 created_after: 创建时间下界（可选，含）。 created_before: 创建时间上界（可选，含）。 format: 导出格式（默认 ``json``，``json`` / ``csv``）。 limit: 导出条目上限（默认 10000），防止大规模死信队列 OOM。 """ channel_type: ChannelType | None = None created_after: datetime | None = None created_before: datetime | None = None format: Literal["json", "csv"] = "json" limit: int = 10000 def __post_init__(self) -> None: """校验导出命令参数合法性。 - ``format`` 必须为 ``json`` 或 ``csv``。 - ``created_after`` 与 ``created_before`` 同时提供时， ``created_after`` 必须早于 ``created_before``。 - ``limit`` 必须为正整数。 """ if self.format not in ("json", "csv"): raise ValidationError("format", f"must be 'json' or 'csv', got '{self.format}'") if ( self.created_after is not None and self.created_before is not None and self.created_after >= self.created_before ): raise ValidationError("time_range", "created_after must be earlier than created_before") if not isinstance(self.limit, int) or self.limit <= 0: raise ValidationError("limit", f"must be a positive integer, got {self.limit!r}") @dataclass(frozen=True) class DeadLetterExportResult: """死信导出结果（OBX-DL-EXPORT）。 描述死信导出的返回内容，``content`` 在 ``format=json`` 时为记录元组， 在 ``format=csv`` 时为 CSV 字符串。 字段： format: 导出格式（``json`` / ``csv``）。 filename: 建议的文件名（``dead-letter-{timestamp}.{format}``）。 total_records: 导出记录总数。 content: 导出内容（json 为记录元组，csv 为字符串）。 """ format: str filename: str total_records: int content: tuple[dict[str, Any], ...] | str @dataclass(frozen=True) class OutboxTrendQuery: """投递积压趋势查询（OBX-TREND）。 描述 outbox 积压趋势的查询条件，由 ``OutboxRepositoryPort.getTrend`` 消费。 ``granularity`` 取值 ``minute`` / ``hour`` / ``day``，默认 ``hour``； ``metric`` 取值 ``queue_depth`` / ``retry_count`` / ``dead_count``， 默认 ``queue_depth``。 字段： start_time: 起始时间（必填，含）。 end_time: 结束时间（必填，含）。 channel_type: 渠道类型过滤（可选）。 channel_account_id: 渠道账户业务 ID 过滤（可选）。 granularity: 时间粒度（默认 ``hour``）。 metric: 度量指标（默认 ``queue_depth``）。 """ start_time: datetime end_time: datetime channel_type: ChannelType | None = None channel_account_id: str | None = None granularity: Literal["minute", "hour", "day"] = "hour" metric: Literal["queue_depth", "retry_count", "dead_count"] = "queue_depth" def __post_init__(self) -> None: """校验趋势查询参数合法性。 - ``start_time`` 必须早于 ``end_time``。 - ``granularity`` 必须为 ``minute`` / ``hour`` / ``day``。 - ``metric`` 必须为 ``queue_depth`` / ``retry_count`` / ``dead_count``。 """ if self.start_time >= self.end_time: raise ValidationError("time_range", "start_time must be earlier than end_time") if self.granularity not in ("minute", "hour", "day"): raise ValidationError( "granularity", f"must be 'minute', 'hour' or 'day', got '{self.granularity}'", ) if self.metric not in ("queue_depth", "retry_count", "dead_count"): raise ValidationError( "metric", f"must be 'queue_depth', 'retry_count' or 'dead_count', got '{self.metric}'", ) @dataclass(frozen=True) class OutboxTrendResult: """投递积压趋势结果（OBX-TREND）。 描述按时间粒度聚合后的趋势序列，``series`` 使用通用 ``TrendDataPoint``。 字段： metric: 度量指标。 granularity: 时间粒度。 series: 趋势数据点元组。 """ metric: str granularity: str series: tuple[TrendDataPoint, ...] __all__ = [ "BatchDeleteResult", "BatchRetryResult", "DeadLetterExportCmd", "DeadLetterExportResult", "DeliveryReceipt", "MessageDurabilityPolicy", "MultiPartReceipt", "OutboxConfig", "OutboxConfigHolder", "OutboxEntry", "OutboxId", "OutboxQueryFilter", "OutboxStats", "OutboxStatus", "OutboxTrendQuery", "OutboxTrendResult", "RetryContext", "RetryPolicySnapshot", ]