Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
106 lines
5.7 KiB
Python
106 lines
5.7 KiB
Python
"""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))
|