ForcePilot/backend/package/yuxi/channels/infrastructure/scheduler.py

"""channels 模块的定时任务 handler 注册入口。

本模块是 channels 限界上下文接入 scheduler 限界上下文的唯一登记点，
对齐 scheduler 上下文设计方案 §14.3 的"业务域 container 主动注册"模式。

与 ``infrastructure/channel_use_cases.py`` 同级，遵循 channels 的分层约定：
装配逻辑集中在 ``infrastructure/``，包根不出现装配代码。

对外暴露：

- ``register_scheduler_handlers(registry)``：业务模块注册函数，由 worker
  启动钩子（``services/run_worker.py`` 的 ``_worker_startup``）统一调用。
  内部实例化本模块的 handler 并调用 ``registry.register(handler)``。

边界规范：
- 本模块是 channels 接入 scheduler 的**唯一装配点**
- handler 的依赖（如 ``session_factory``）在函数内部构造，不暴露给装配层
- 新增 handler 时，在本函数内追加 ``registry.register(...)`` 即可，无需改
  ``run_worker.py``（前提：本模块已登记在 ``_BUSINESS_HANDLER_REGISTRARS``）
- handler 禁止依赖 channels api 进程内存态（``PluginRegistry`` /
  ``DegradationManager`` / ``EventBus`` 等），只能通过 ``session_factory``
  + DB 查询，确保在 worker 进程独立可运行
"""

from __future__ import annotations

from yuxi.channels.application.extension.scheduler_handlers.channel_outbox_terminal_cleanup_handler import (
    ChannelOutboxTerminalCleanupHandler,
)
from yuxi.channels.application.extension.scheduler_handlers.channel_pairing_terminal_cleanup_handler import (
    ChannelPairingTerminalCleanupHandler,
)
from yuxi.channels.application.extension.scheduler_handlers.channel_report_cleanup_handler import (
    ChannelReportCleanupHandler,
)
from yuxi.channels.application.extension.scheduler_handlers.channel_report_handler import (
    ChannelReportHandler,
)
from yuxi.channels.application.extension.scheduler_handlers.channel_session_inactive_cleanup_handler import (
    ChannelSessionInactiveCleanupHandler,
)
from yuxi.channels.infrastructure.channel_use_cases import (
    create_channel_outbox_terminal_cleanup_handler_dependencies,
    create_channel_pairing_terminal_cleanup_handler_dependencies,
    create_channel_report_cleanup_handler_dependencies,
    create_channel_report_handler_dependencies,
    create_channel_session_inactive_cleanup_handler_dependencies,
)
from yuxi.scheduler.framework.runtime import HandlerRegistry
from yuxi.storage.postgres.manager import pg_manager

__all__ = ["register_scheduler_handlers"]


def register_scheduler_handlers(registry: HandlerRegistry) -> None:
    """向 scheduler 注册 channels 模块的定时任务 handler。

    由 worker 启动钩子在装配阶段统一调用。新增 handler 时在此函数内追加
    ``registry.register(...)`` 即可。

    注册的 handler 分两类：

    1. **一次性任务执行器**（``ChannelReportHandler``）：由 ``scheduled_tasks``
       表的 ``schedule_kind="at"`` + ``delete_after_run=True`` 触发，按
       ``report_id`` 生成一次性聚合视图报告。
    2. **运维型周期清理 handler**（FR-04 ~ FR-08）：由 ``schedule_kind="interval"``
       周期触发，清理超期终态记录与回收卡死任务，避免表无限增长。worker 进程
       不注入 api 进程内存态（``EventBus`` / ``PluginRegistry`` 等），通过
       ``session_factory`` 创建独立 DB 会话执行清理。

    Args:
        registry: worker 进程级 handler 注册表。
    """
    session_factory = pg_manager.get_async_session_context

    # ChannelReportHandler：一次性报告生成（RPT-05 异步执行器）
    # 依赖通过 create_channel_report_handler_dependencies 装配：
    # - session_factory：worker 进程级 session 工厂
    # - analytics_view_port / dashboard_view_port：None（已在 api 进程装配，
    #   worker 进程暂未注入，ChannelReportHandler 对 None 端口抛
    #   NotImplementedError，报告状态变 failed）
    # - logger：StructuredLoggerAdapter 实例
    report_deps = create_channel_report_handler_dependencies(session_factory)
    registry.register(ChannelReportHandler(**report_deps))

    # ─────────────────────────────────────────────────────────────────────
    # P1 运维型周期清理 handler（FR-04 ~ FR-08）
    # ─────────────────────────────────────────────────────────────────────

    # FR-04：清理长期 inactive 的临时会话（is_temporary=true 且 last_message_at 超时）
    session_cleanup_deps = create_channel_session_inactive_cleanup_handler_dependencies(session_factory)
    registry.register(ChannelSessionInactiveCleanupHandler(**session_cleanup_deps))

    # FR-05：物理清理超期 DEAD / SENT 终态 Outbox 条目，best-effort 发布
    # OutboxEntryPurgedEvent（event_publisher=None，worker 进程未注入）
    outbox_cleanup_deps = create_channel_outbox_terminal_cleanup_handler_dependencies(session_factory)
    registry.register(ChannelOutboxTerminalCleanupHandler(**outbox_cleanup_deps))

    # FR-06：物理清理超期终态配对记录（EXPIRED / REJECTED / REVOKED）
    pairing_cleanup_deps = create_channel_pairing_terminal_cleanup_handler_dependencies(session_factory)
    registry.register(ChannelPairingTerminalCleanupHandler(**pairing_cleanup_deps))

    # FR-08：清理终态报表 + 回收卡死 generating 报表
    report_cleanup_deps = create_channel_report_cleanup_handler_dependencies(session_factory)
    registry.register(ChannelReportCleanupHandler(**report_cleanup_deps))