"""订阅治理轮次日志的聚合与格式化。""" from __future__ import annotations import time from dataclasses import dataclass, field from typing import Collection, Literal, Mapping, Optional from uuid import uuid4 from app.application.subscription.execution import ( SearchBatchSnapshot, SubscriptionExecutionContext, SubscriptionSearchRepository, ) from app.application.subscription.sitebudget import SubscriptionSiteBudgetMetrics SearchTaskOutcome = Literal["completed", "skipped", "failed", "cancelled", "requeued"] _SEARCH_SOURCE_NAMES = { "manual": "手动订阅搜索", "targeted": "指定订阅搜索", "new": "新订阅自动搜索", "fallback": "订阅定时检查", "resume": "等待中的订阅搜索", "inline": "订阅搜索", } _SEARCH_STATE_NAMES = { "completed": "已完成", "failed": "部分订阅没有完成", "cancelled": "已停止", "skipped": "部分订阅这次未搜索", "queued": "部分订阅稍后继续", "running": "仍在处理中", "cancelling": "正在停止", "stopped": "部分订阅稍后继续", } _MATCH_STATE_NAMES = { "completed": "检查完成", "failed": "部分订阅没有完成", "cancelled": "已停止", "skipped": "部分订阅这次未检查", "stopped": "已停止,部分订阅这次未检查", } def _search_source_name(source: str) -> str: """返回搜索来源对应的可读名称。""" return _SEARCH_SOURCE_NAMES.get(source, "订阅搜索") def _search_state_name(state: str) -> str: """返回搜索结束状态对应的可读说明。""" return _SEARCH_STATE_NAMES.get(state, "已结束") def _match_state_name(state: str) -> str: """返回订阅资源检查状态对应的可读说明。""" return _MATCH_STATE_NAMES.get(state, "已结束") def batch_progress_text(batch: Optional[SearchBatchSnapshot]) -> str: """把批次聚合终态转为兼容进度文案。""" if batch is None: return "搜索已安排" if batch.state == "failed": return "搜索结束,部分订阅没有完成" if batch.state == "cancelled": return "搜索已停止" if batch.state == "skipped": return "搜索结束,部分订阅这次未搜索" if batch.state in {"queued", "running", "cancelling"}: return "搜索已安排,系统正在依次处理" if batch.skipped_count: return "搜索结束,部分订阅这次未搜索" return "搜索完成" def inline_search_result(total: int, finished: int) -> tuple[str, dict[str, int]]: """返回兼容搜索的真实终态文案与计数。""" text = ( "搜索完成" if finished == total else "搜索结束,部分订阅这次没有完成" ) return text, {"total": total, "finished": finished} def batch_finished_count( batch: Optional[SearchBatchSnapshot], fallback: int, ) -> int: """返回批次所有终态任务数;批次暂不可读时使用本轮实际完成数。""" if batch is None: return fallback return ( batch.finished_count + batch.failed_count + batch.cancelled_count + batch.skipped_count ) def finish_returned_search_task( *, queue: SubscriptionSearchRepository, task_id: str, lease_token: str, subscription_id: int, execution_context: SubscriptionExecutionContext, system_stopped: bool, cancel_requested: bool, ) -> tuple[Optional[int], SearchTaskOutcome, Optional[str]]: """按 TTL、停机和取消边界收口正常返回的搜索任务。""" download_started = execution_context.download_started if execution_context.is_expired() and not (system_stopped or cancel_requested): if download_started: queue.finish_task( task_id=task_id, lease_token=lease_token, state="completed", error="下载已经提交,虽然搜索用时较长,结果仍然有效", ) return subscription_id, "completed", "ttl_timeout" queue.finish_task( task_id=task_id, lease_token=lease_token, state="failed", error="这次搜索用时过长,已停止,可稍后重试", ) return None, "failed", "ttl_timeout" if system_stopped: if download_started: queue.finish_task( task_id=task_id, lease_token=lease_token, state="completed", error="下载已经提交,系统停止后仍保留这次结果", ) return subscription_id, "completed", "system_stop" queue.release_task(task_id=task_id, lease_token=lease_token) return None, "requeued", "system_stop" if cancel_requested: if download_started: queue.finish_task( task_id=task_id, lease_token=lease_token, state="completed", error="下载已经提交,无法撤回,已保留这次结果", ) return subscription_id, "completed", "cancelled" queue.release_task(task_id=task_id, lease_token=lease_token, cancelled=True) return None, "cancelled", "cancelled" queue.finish_task(task_id=task_id, lease_token=lease_token, state="completed") return subscription_id, "completed", None @dataclass(slots=True) class MatchExecutionSummary: """保存一次 Match 批次的实际订阅执行结果。""" total: int = 0 candidate_count: int = 0 site_count: int = 0 run_id: str = field(default_factory=lambda: uuid4().hex) started_at: float = field(default_factory=time.perf_counter) completed: int = 0 skipped: int = 0 failed: int = 0 admission_conflicts: int = 0 cancelled: int = 0 ttl_timeouts: int = 0 release_failures: int = 0 @classmethod def from_candidates( cls, candidates: Mapping[str, Collection[object]], ) -> MatchExecutionSummary: """按站点分组的完整候选快照初始化轮次计数。""" return cls( candidate_count=sum(len(contexts) for contexts in candidates.values()), site_count=len(candidates), ) @property def finished(self) -> int: """返回已经收口的订阅数量。""" return self.completed + self.skipped + self.failed def record(self, outcome: Optional[str], reason: Optional[str] = None) -> None: """将单订阅结果归入稳定的完成、跳过或失败计数。""" if outcome == "completed": self.completed += 1 elif outcome == "skipped": self.skipped += 1 else: self.failed += 1 if reason == "admission_conflict": self.admission_conflicts += 1 elif reason == "cancelled": self.cancelled += 1 elif reason == "ttl_timeout": self.ttl_timeouts += 1 @property def state(self) -> str: """按已处理数量和任务终态生成轮次状态。""" if self.finished < self.total: return "stopped" if self.failed: return "failed" if self.skipped: return "skipped" return "completed" def start_log(self) -> str: """构造不暴露内部标记的资源检查开始日志。""" return ( f"开始检查订阅资源,共 {self.total} 个订阅、{self.candidate_count} 个资源," f"来自 {self.site_count} 个站点。" ) def finish_log(self) -> str: """构造可直接阅读的资源检查结束日志。""" elapsed_seconds = time.perf_counter() - self.started_at message = ( f"订阅资源检查结束:{_match_state_name(self.state)}。" f"本次检查 {self.finished}/{self.total} 个订阅,完成 {self.completed} 个," f"这次未检查 {self.skipped} 个,失败 {self.failed} 个;" f"共检查 {self.candidate_count} 个资源,来自 {self.site_count} 个站点," f"用时 {elapsed_seconds:.1f} 秒。" ) if self.admission_conflicts: message += f"其中 {self.admission_conflicts} 个订阅正在处理中,本次没有重复检查。" if self.cancelled: message += f"另有 {self.cancelled} 个订阅已停止。" if self.ttl_timeouts: message += f"另有 {self.ttl_timeouts} 个订阅检查时间过长,已停止。" if self.release_failures: message += f"另有 {self.release_failures} 个订阅的搜索状态没有正常恢复,系统稍后会继续检查。" return message def as_data(self, current: Optional[int] = None) -> dict[str, int]: """构造供进度消费者读取的实际计数。""" data = { "total": self.total, "finished": self.finished, "completed": self.completed, "skipped": self.skipped, "failed": self.failed, } if current is not None: data["current"] = current return data @dataclass(slots=True) class SearchExecutionSummary: """聚合一次 Search 消费轮次的任务、站点与候选观测。""" source: str requested: int run_id: str = field(default_factory=lambda: uuid4().hex) batch_id: Optional[str] = None coalesced: int = 0 started_at: float = field(default_factory=time.perf_counter) completed: int = 0 skipped: int = 0 failed: int = 0 cancelled: int = 0 requeued: int = 0 admission_conflicts: int = 0 ttl_timeouts: int = 0 release_failures: int = 0 consumer_conflicts: int = 0 stopped: bool = False round_failed: bool = False site_metrics: SubscriptionSiteBudgetMetrics = field( default_factory=SubscriptionSiteBudgetMetrics ) @property def processed(self) -> int: """返回本轮实际取得并收口或退回队列的任务数。""" return self.completed + self.skipped + self.failed + self.cancelled + self.requeued def record(self, outcome: SearchTaskOutcome, reason: Optional[str] = None) -> None: """记录一个任务结果,并单独统计冲突、取消和 TTL。""" if outcome == "completed": self.completed += 1 elif outcome == "skipped": self.skipped += 1 elif outcome == "failed": self.failed += 1 elif outcome == "cancelled": self.cancelled += 1 else: self.requeued += 1 if reason == "admission_conflict": self.admission_conflicts += 1 elif reason == "ttl_timeout": self.ttl_timeouts += 1 def start_log(self) -> str: """构造不暴露内部术语的 Search 开始日志。""" message = f"开始{_search_source_name(self.source)},共 {self.requested} 个订阅" if self.coalesced: message += f",其中 {self.coalesced} 个已经在处理中" return f"{message}。" def finish_log(self, batch: Optional[SearchBatchSnapshot] = None) -> str: """构造可直接阅读的 Search 结束日志。""" sites = self.site_metrics.snapshot() if self.round_failed: state = "failed" elif batch is not None: state = batch.state elif self.consumer_conflicts: state = "skipped" elif self.requeued or self.stopped: state = "stopped" elif self.failed: state = "failed" elif self.cancelled: state = "cancelled" elif self.skipped: state = "skipped" else: state = "completed" elapsed_seconds = time.perf_counter() - self.started_at message = ( f"{_search_source_name(self.source)}结束:{_search_state_name(state)}。" f"本次处理 {self.processed}/{self.requested} 个,完成 {self.completed} 个," f"这次未搜索 {self.skipped} 个,失败 {self.failed} 个," f"稍后继续 {self.requeued} 个,已停止 {self.cancelled} 个;" f"访问 {sites.site_count} 个站点,发出 {sites.request_count} 次请求," f"找到 {sites.candidate_count} 个资源,用时 {elapsed_seconds:.1f} 秒。" ) unfinished_cleanup = self.release_failures + sites.release_failure_count if unfinished_cleanup: message += f"另有 {unfinished_cleanup} 个搜索状态没有正常恢复,系统稍后会继续处理。" return message