ForcePilot/backend/package/yuxi/channels/application/transport/manager.py

"""入站传输管理器。

统一管理 PullerWorker 和 StreamWorker 的生命周期，订阅账号上下线事件，
动态启动/停止账号的传输任务。
"""

from __future__ import annotations

import asyncio
import uuid
from collections.abc import Awaitable, Callable
from typing import Any

from yuxi.channels.application.transport.base_worker import (
    TransportConfig,
)
from yuxi.channels.application.transport.puller_worker import PullerWorker
from yuxi.channels.application.transport.stream_worker import StreamWorker
from yuxi.channels.contract.dtos.channel import AccountFilter, AccountStatus, ChannelType
from yuxi.channels.contract.dtos.health import TransportHealthSnapshot
from yuxi.channels.contract.dtos.plugin import DomainEvent, EventHandler
from yuxi.channels.contract.plugin.extension_point import EventSubscription
from yuxi.channels.contract.plugin.manifest import FailurePolicy
from yuxi.channels.contract.ports.driven import (
    ConfigPort,
    LoggerPort,
    PersistencePort,
)
from yuxi.channels.core.registry import PluginRegistry

__all__ = ["TransportManager"]

# 管理循环的轮询间隔（秒）：仅用于等待取消信号，不参与业务逻辑
_MANAGER_LOOP_INTERVAL_S: float = 1.0


class TransportManager:
    """入站传输全局管理器。

    单例模式管理 PullerWorker 和 StreamWorker，订阅 ChannelAccountOnline/Offline
    事件，根据 transport_mode 与适配器能力动态启动/停止对应账号的传输任务
    （Task 11：pull 仅 Puller、stream 仅 Stream、both 优先 Stream 降级 Puller）。

    职责：
        - 从 PluginRegistry 动态构建 puller/stream 适配器注册表
        - 创建并管理 PullerWorker、StreamWorker 单例
        - 订阅账号上下线事件，驱动 Worker 启动/停止账号任务
        - 提供全局健康状态查询
        - 优雅关停所有传输任务
    """

    def __init__(
        self,
        *,
        plugin_registry: PluginRegistry,
        persistence_port: PersistencePort,
        config_port: ConfigPort,
        event_bus: Any,
        circuit_breaker: Any,
        logger: LoggerPort,
        message_deliverer: Callable[[Any], Awaitable[Any]],
        transport_config: TransportConfig | None = None,
    ) -> None:
        """初始化 TransportManager。

        参数：
            plugin_registry: 插件注册表，用于动态获取渠道适配器。
            persistence_port: 持久化端口，用于游标持久化等。
            config_port: 配置端口。
            event_bus: 事件总线，用于订阅/发布事件。
            circuit_breaker: 熔断器实例。
            logger: 日志端口。
            message_deliverer: 入站消息投递回调。
            transport_config: 传输配置，为 None 时使用默认配置。
        """
        self._plugin_registry = plugin_registry
        self._persistence_port = persistence_port
        self._config_port = config_port
        self._event_bus = event_bus
        self._circuit_breaker = circuit_breaker
        self._logger = logger
        self._message_deliverer = message_deliverer
        self._config = transport_config or TransportConfig()

        self._puller_registry: dict[ChannelType, Any] = {}
        self._stream_connector_registry: dict[ChannelType, Any] = {}
        self._puller_worker: PullerWorker | None = None
        self._stream_worker: StreamWorker | None = None
        self._manager_task: asyncio.Task[None] | None = None
        self._running: bool = False
        self._plugin_id = "transport-manager"

    async def start(self) -> None:
        """启动传输管理器。

        - 构建 puller_registry 和 stream_connector_registry
        - 创建 PullerWorker 和 StreamWorker 实例
        - 启动 Worker
        - 订阅账号上下线事件
        - 启动管理循环任务
        """
        if self._running:
            return

        trace_id = str(uuid.uuid4())

        puller_registry: dict[ChannelType, Any] = {}
        stream_connector_registry: dict[ChannelType, Any] = {}

        for channel_type, plugin_da in self._plugin_registry.listPluginAdapters():
            if plugin_da.puller_adapters:
                puller_registry[channel_type] = plugin_da.puller_adapters[0]
            if plugin_da.stream_connector_adapters:
                stream_connector_registry[channel_type] = plugin_da.stream_connector_adapters[0]

        self._puller_registry = puller_registry
        self._stream_connector_registry = stream_connector_registry

        self._puller_worker = PullerWorker(
            message_deliverer=self._message_deliverer,
            logger=self._logger,
            config_port=self._config_port,
            event_publisher=self._event_bus,
            circuit_breaker=self._circuit_breaker,
            persistence_port=self._persistence_port,
            config=self._config,
        )

        self._stream_worker = StreamWorker(
            message_deliverer=self._message_deliverer,
            logger=self._logger,
            config_port=self._config_port,
            event_publisher=self._event_bus,
            circuit_breaker=self._circuit_breaker,
            config=self._config,
        )

        await self._puller_worker.start()
        await self._stream_worker.start()

        self._registerEventHandlers()

        self._running = True
        self._manager_task = asyncio.create_task(
            self._manager_loop(),
            name="transport-manager-loop",
        )

        await self._logger.info(
            "transport manager started",
            trace_id=trace_id,
            puller_channels=[ct for ct in puller_registry.keys()],
            stream_channels=[ct for ct in stream_connector_registry.keys()],
        )

        # 重启恢复：扫描 DB 中 ACTIVE 状态账号，为每个账号启动传输任务。
        # 系统重启后不会收到 ChannelAccountOnline 事件，必须主动恢复，
        # 否则已上线账号的传输任务（SSE/短轮询）不会启动。
        await self._restoreOnlineAccounts(trace_id)

    async def stop(self, timeout: float = 5.0) -> None:
        """停止传输管理器。

        - 取消事件订阅
        - 取消管理循环任务
        - 停止所有 Worker
        - 等待所有任务完成

        参数：
            timeout: 等待 Worker 停止的超时时间（秒）。
        """
        if not self._running:
            return

        trace_id = str(uuid.uuid4())
        self._running = False

        self._unregisterEventHandlers()

        if self._manager_task is not None and not self._manager_task.done():
            self._manager_task.cancel()
            try:
                await self._manager_task
            except asyncio.CancelledError:
                pass
            self._manager_task = None

        if self._puller_worker is not None:
            await self._puller_worker.stop(timeout)
            self._puller_worker = None

        if self._stream_worker is not None:
            await self._stream_worker.stop(timeout)
            self._stream_worker = None

        await self._logger.info(
            "transport manager stopped",
            trace_id=trace_id,
        )

    def getHealth(self) -> TransportHealthSnapshot:
        """返回传输引擎健康状态（同步，向后兼容）。

        返回：
            ``TransportHealthSnapshot``，包含 running 状态和各 Worker 健康
            子状态（``WorkerHealthSnapshot``）。
        """
        return TransportHealthSnapshot(
            running=self._running,
            puller=self._puller_worker.getHealth() if self._puller_worker else None,
            stream=self._stream_worker.getHealth() if self._stream_worker else None,
        )

    async def getTransportHealth(self) -> TransportHealthSnapshot:
        """返回传输引擎健康状态（实现 TransportHealthPort，FR-18）。

        供 ``HealthAggregator`` 通过 ``TransportHealthPort`` 聚合，暴露每个
        账号的运行状态（running/backoff/stopped/error）。实现幂等、无副作用，
        不抛异常阻塞调用方。

        返回：
            ``TransportHealthSnapshot``，结构见 ``TransportHealthPort`` 协议
            文档。异常时降级返回 ``puller`` / ``stream`` 为 ``None`` 的快照。
        """
        try:
            return self.getHealth()
        except Exception as exc:
            # 健康检查不得抛异常阻塞调用方（与 HealthAggregator 超时降级策略一致）
            await self._logger.warn(
                "transport health query failed, returning empty state",
                error=str(exc),
            )
            return TransportHealthSnapshot(
                running=self._running,
                puller=None,
                stream=None,
            )

    async def _manager_loop(self) -> None:
        """管理循环，等待取消信号。"""
        try:
            while self._running:
                await asyncio.sleep(_MANAGER_LOOP_INTERVAL_S)
        except asyncio.CancelledError:
            pass

    def _registerEventHandlers(self) -> None:
        """注册事件处理器。"""
        self._event_bus.register(
            self._plugin_id,
            EventSubscription(
                event_type="ChannelAccountOnline",
                handler=_AccountEventHandler(self._on_account_online),
                priority=100,
                failure_policy=FailurePolicy.DEGRADE,
            ),
        )
        self._event_bus.register(
            self._plugin_id,
            EventSubscription(
                event_type="ChannelAccountOffline",
                handler=_AccountEventHandler(self._on_account_offline),
                priority=100,
                failure_policy=FailurePolicy.DEGRADE,
            ),
        )
        self._event_bus.register(
            self._plugin_id,
            EventSubscription(
                event_type="ChannelDegraded",
                handler=_AccountEventHandler(self._on_channel_degraded),
                priority=100,
                failure_policy=FailurePolicy.DEGRADE,
            ),
        )
        self._event_bus.register(
            self._plugin_id,
            EventSubscription(
                event_type="ChannelRecovered",
                handler=_AccountEventHandler(self._on_channel_recovered),
                priority=100,
                failure_policy=FailurePolicy.DEGRADE,
            ),
        )
        self._event_bus.register(
            self._plugin_id,
            EventSubscription(
                event_type="TransportErrorOccurred",
                handler=_AccountEventHandler(self._on_transport_error),
                priority=100,
                failure_policy=FailurePolicy.DEGRADE,
            ),
        )
        # 配置热更新订阅（FR-04）：transport.* 配置变更时应用 hot/restart 策略
        for config_event in ("ConfigChanged", "ConfigRollback"):
            self._event_bus.register(
                self._plugin_id,
                EventSubscription(
                    event_type=config_event,
                    handler=_AccountEventHandler(self._on_config_changed),
                    priority=100,
                    failure_policy=FailurePolicy.DEGRADE,
                ),
            )

    def _unregisterEventHandlers(self) -> None:
        """取消事件订阅。"""
        self._event_bus.unregister(self._plugin_id)

    async def _on_account_online(self, event: DomainEvent) -> None:
        """处理账号上线事件。

        从事件 payload 获取 channel_type 和 account_id，根据 transport_mode
        与适配器能力选择启动 Puller 或 Stream 任务（Task 11.1 + 11.2）：
            - ``pull``: 仅启动 Puller
            - ``stream``: 仅启动 Stream
            - ``both``: 优先 Stream，Puller 作为降级（Stream 适配器不可用时启动）

        参数：
            event: ChannelAccountOnline 事件。
        """
        trace_id = event.trace_id or str(uuid.uuid4())
        channel_type_raw = event.payload.get("channel_type")
        account_id = event.payload.get("account_id")
        if channel_type_raw is None or account_id is None:
            await self._logger.warn(
                "account online event missing required fields, skip",
                trace_id=trace_id,
                channel_type=channel_type_raw,
                account_id=account_id,
            )
            return
        channel_type = ChannelType(channel_type_raw)

        await self._logger.info(
            "received account online event",
            trace_id=trace_id,
            channel_type=channel_type,
            account_id=account_id,
        )
        await self._startTransportForAccount(channel_type, account_id, trace_id, source="event")

    async def _startTransportForAccount(
        self,
        channel_type: ChannelType,
        account_id: str,
        trace_id: str,
        source: str = "event",
    ) -> None:
        """为单个账号启动传输任务（事件驱动与重启恢复共用）。

        根据 transport_mode 与适配器能力选择启动 Puller 或 Stream 任务：
            - ``pull``: 仅启动 Puller
            - ``stream``: 仅启动 Stream
            - ``both``: 优先 Stream，Puller 作为降级（Stream 适配器不可用时启动）

        参数：
            channel_type: 渠道类型。
            account_id: 账号 ID。
            trace_id: 链路追踪 ID。
            source: 启动来源（``event`` 事件驱动 / ``restore`` 重启恢复），
                仅用于日志区分。
        """
        transport_mode = await self._resolveTransportMode(channel_type, account_id)
        puller_adapter = self._puller_registry.get(channel_type)
        stream_adapter = self._stream_connector_registry.get(channel_type)

        await self._logger.info(
            "starting transport for account",
            trace_id=trace_id,
            channel_type=channel_type,
            account_id=account_id,
            transport_mode=transport_mode,
            has_puller_adapter=puller_adapter is not None,
            has_stream_adapter=stream_adapter is not None,
            source=source,
        )

        started = False
        if transport_mode == "pull":
            if puller_adapter is not None and self._puller_worker is not None:
                await self._puller_worker.start_account(channel_type, account_id, puller_adapter)
                started = True
        elif transport_mode == "stream":
            if stream_adapter is not None and self._stream_worker is not None:
                await self._stream_worker.start_account(channel_type, account_id, stream_adapter)
                started = True
        else:
            # Task 11.2: both 模式优先 Stream，Puller 作为降级。
            # Stream 适配器可用时仅启动 Stream（Stream 健康时不 poll）；
            # Stream 适配器不可用时降级启动 Puller。
            if stream_adapter is not None and self._stream_worker is not None:
                await self._stream_worker.start_account(channel_type, account_id, stream_adapter)
                started = True
            elif puller_adapter is not None and self._puller_worker is not None:
                await self._puller_worker.start_account(channel_type, account_id, puller_adapter)
                started = True

        # 传输任务成功启动后持久化插件运行态（FR-32）。诊断字段，写入失败
        # 仅告警不中止（与 last_health_check_at 一致的 best-effort 语义）。
        if started:
            await self._touchPluginStatus(channel_type, account_id, "running", trace_id)

    async def _restoreOnlineAccounts(self, trace_id: str) -> None:
        """重启恢复：扫描 DB 中 ACTIVE 状态账号，启动传输任务。

        系统重启后 TransportManager 不会收到 ChannelAccountOnline 事件，
        本方法在 ``start()`` 中被调用，为所有已注册渠道的 ACTIVE 状态账号
        启动传输任务（SSE 或短轮询），实现重启后自动恢复。

        错误隔离：单个账号查询/启动失败不阻塞其他账号，仅记录 warn 日志。
        仅恢复注册表中有 puller 或 stream 适配器的渠道（未注册适配器的
        渠道跳过）。

        参数：
            trace_id: 启动链路追踪 ID。
        """
        restored = 0
        failed = 0
        # 合并 puller 和 stream 注册表的渠道类型，避免遗漏
        channel_types = set(self._puller_registry.keys()) | set(self._stream_connector_registry.keys())

        for channel_type in channel_types:
            try:
                accounts = await self._persistence_port.findAccountsByFilter(
                    AccountFilter(channel_type=channel_type, status=AccountStatus.ACTIVE)
                )
            except Exception as exc:
                await self._logger.warn(
                    "transport restore: failed to query accounts for channel",
                    trace_id=trace_id,
                    channel_type=channel_type,
                    error=str(exc),
                )
                continue

            for account in accounts:
                try:
                    await self._startTransportForAccount(
                        channel_type=channel_type,
                        account_id=account.account_id,
                        trace_id=trace_id,
                        source="restore",
                    )
                    restored += 1
                except Exception as exc:
                    failed += 1
                    await self._logger.warn(
                        "transport restore: failed to start account",
                        trace_id=trace_id,
                        channel_type=channel_type,
                        account_id=account.account_id,
                        error=str(exc),
                    )

        await self._logger.info(
            "transport restore completed",
            trace_id=trace_id,
            restored_accounts=restored,
            failed_accounts=failed,
            channel_count=len(channel_types),
        )

    async def _resolveTransportMode(
        self,
        channel_type: ChannelType,
        account_id: str,
    ) -> str:
        """解析账号的传输模式（Task 11.1）。

        优先使用账号级 ``transport_mode``（``ChannelAccount.transport_mode``），
        账号不存在或读取失败时回退到 manifest 声明的渠道级 ``transport_mode``，
        均不可用时回退到 ``both``。

        参数：
            channel_type: 渠道类型。
            account_id: 渠道账号ID。

        返回：
            传输模式字符串（``pull`` / ``stream`` / ``both``）。
        """
        try:
            account = await self._persistence_port.getChannelAccount(channel_type, account_id)
        except Exception as exc:
            await self._logger.warn(
                "failed to get channel account for transport_mode resolution, fallback to manifest default",
                channel_type=channel_type,
                account_id=account_id,
                error=str(exc),
            )
            account = None

        if account is not None:
            return account.transport_mode

        plugin = self._plugin_registry.getPluginByChannelType(channel_type)
        if plugin is not None:
            return plugin.manifest.transport_mode
        return "both"

    async def _on_account_offline(self, event: DomainEvent) -> None:
        """处理账号下线事件。

        停止对应账号的所有传输任务。

        参数：
            event: ChannelAccountOffline 事件。
        """
        trace_id = event.trace_id or str(uuid.uuid4())
        channel_type_raw = event.payload.get("channel_type")
        account_id = event.payload.get("account_id")
        if channel_type_raw is None or account_id is None:
            await self._logger.warn(
                "account offline event missing required fields, skip",
                trace_id=trace_id,
                channel_type=channel_type_raw,
                account_id=account_id,
            )
            return
        channel_type = ChannelType(channel_type_raw)
        reason = event.payload.get("reason", "offline")

        await self._logger.info(
            "received account offline event, stopping transport",
            trace_id=trace_id,
            channel_type=channel_type,
            account_id=account_id,
            reason=reason,
        )

        if self._puller_worker is not None:
            await self._puller_worker.stop_account(channel_type, account_id, reason)

        if self._stream_worker is not None:
            await self._stream_worker.stop_account(channel_type, account_id, reason)

        # 传输任务停止后持久化插件运行态（FR-32）。
        await self._touchPluginStatus(channel_type, account_id, "stopped", trace_id)

    async def _on_channel_degraded(self, event: DomainEvent) -> None:
        """处理渠道降级事件。

        P0 阶段留空，P1 阶段实现降级逻辑（如暂停非关键任务、调整轮询间隔等）。

        参数：
            event: ChannelDegraded 事件。
        """
        pass

    async def _on_channel_recovered(self, event: DomainEvent) -> None:
        """处理渠道恢复事件。

        P0 阶段留空，P1 阶段实现恢复逻辑。

        参数：
            event: ChannelRecovered 事件。
        """
        pass

    async def _on_transport_error(self, event: DomainEvent) -> None:
        """处理传输错误事件。

        记录日志并将账户插件运行态置为 ``error``（FR-32）。P1 阶段可用于
        监控告警。

        参数：
            event: TransportErrorOccurred 事件。
        """
        trace_id = event.trace_id or str(uuid.uuid4())
        channel_type_raw = event.payload.get("channel_type")
        account_id = event.payload.get("account_id")
        await self._logger.warn(
            "transport error occurred",
            trace_id=trace_id,
            channel_type=channel_type_raw,
            account_id=account_id,
            error_category=event.payload.get("error_category"),
            error_code=event.payload.get("error_code"),
        )
        # 持久化插件运行态为 error（FR-32）。仅当事件携带账户信息时写入。
        if channel_type_raw is not None and account_id is not None:
            await self._touchPluginStatus(
                ChannelType(channel_type_raw), account_id, "error", trace_id
            )

    async def _touchPluginStatus(
        self,
        channel_type: ChannelType,
        account_id: str,
        plugin_status: str,
        trace_id: str,
    ) -> None:
        """更新账户插件运行态（FR-32）。

        传输任务 start/stop/error 后调用 ``PersistencePort.updatePluginStatus``
        持久化插件运行态（running / stopped / error）。诊断字段，best-effort
        写入：失败时仅记录告警，不中止传输主流程（与 ``last_health_check_at``
        一致）。
        """
        try:
            await self._persistence_port.updatePluginStatus(
                channel_type, account_id, plugin_status
            )
        except Exception as exc:
            await self._logger.warn(
                "failed to update plugin_status",
                trace_id=trace_id,
                channel_type=channel_type,
                account_id=account_id,
                plugin_status=plugin_status,
                error=str(exc),
            )

    async def _on_config_changed(self, event: DomainEvent) -> None:
        """处理配置变更事件（FR-04 配置热更新）。

        监听 ``transport.*`` 前缀的全局配置变更，按 hot/restart 模式应用：
        - hot 模式（``stall_timeout_ms`` / ``backoff_schedule`` /
          ``backoff_jitter``）：重新加载 TransportConfig 并更新 Worker 配置，
          当前轮次结束后生效。
        - restart 模式（``max_restart_attempts`` /
          ``graceful_shutdown_timeout_s``）：记录警告日志，需手动重启
          TransportManager 生效（P1 阶段不实现自动重启，避免账号连接中断）。

        参数：
            event: ConfigChanged / ConfigRollback 事件，payload 包含 key。
        """
        key = event.payload.get("key", "")
        if not key.startswith("transport."):
            return
        # 仅处理全局配置（target 为 None 或空），忽略账户级配置
        target = event.payload.get("target")
        if target:
            return

        trace_id = event.trace_id or str(uuid.uuid4())
        if key in _RESTART_REQUIRED_CONFIG_KEYS:
            await self._logger.warn(
                "transport config change requires restart to take effect",
                trace_id=trace_id,
                key=key,
                event_type=event.event_type,
            )
            return

        # 仅对 hot-reloadable 键触发重新加载，忽略未知 transport.* 键
        if key not in _RELOADABLE_CONFIG_KEYS:
            return

        # hot 模式：重新加载配置并更新 Worker
        await self._logger.info(
            "transport config hot reload triggered",
            trace_id=trace_id,
            key=key,
            event_type=event.event_type,
        )
        await self.reloadConfig()

    async def reloadConfig(self) -> None:
        """重新加载传输配置并更新 Worker（FR-04 hot 模式）。

        从 ``ConfigPort`` 读取最新 ``transport.*`` 配置，更新
        ``TransportManager._config`` 及两个 Worker 的 ``_config``。
        Worker 在下一轮循环（退避等待、轮询间隔、心跳间隔）时自动应用新配置。

        幂等：多次调用安全，仅更新配置不重启任务。
        """
        trace_id = str(uuid.uuid4())
        try:
            new_config = await self._loadTransportConfig()
        except Exception as exc:
            await self._logger.error(
                "transport config reload failed, keeping old config",
                trace_id=trace_id,
                error=str(exc),
            )
            return

        self._config = new_config
        if self._puller_worker is not None:
            self._puller_worker._config = new_config
        if self._stream_worker is not None:
            self._stream_worker._config = new_config

        await self._logger.info(
            "transport config reloaded",
            trace_id=trace_id,
            stall_timeout_ms=new_config.stall_timeout_ms,
            backoff_schedule=list(new_config.backoff_schedule),
            backoff_jitter=new_config.backoff_jitter,
        )

    async def _loadTransportConfig(self) -> TransportConfig:
        """从 ConfigPort 加载 TransportConfig。

        复用 BaseTransportWorker._loadConfig 的读取逻辑，集中配置加载
        避免逻辑重复。
        """
        # 委托任一 Worker 的 _loadConfig（两者配置相同），无 Worker 时
        # 直接构造默认配置
        if self._puller_worker is not None:
            return await self._puller_worker._loadConfig()
        if self._stream_worker is not None:
            return await self._stream_worker._loadConfig()
        return TransportConfig()


# transport.* 配置键的热更新模式分类（FR-04）
_RELOADABLE_CONFIG_KEYS: frozenset[str] = frozenset(
    {
        "transport.stall_timeout_ms",
        "transport.backoff_schedule",
        "transport.backoff_jitter",
        "transport.stream_reconnect_backoff_ms",
        "transport.stream_reconnect_max_backoff_ms",
    }
)
_RESTART_REQUIRED_CONFIG_KEYS: frozenset[str] = frozenset(
    {
        "transport.max_restart_attempts",
        "transport.graceful_shutdown_timeout_s",
    }
)


class _AccountEventHandler(EventHandler):
    """账号事件处理器适配器。

    将 EventHandler 接口适配到 TransportManager 的异步处理方法。
    """

    def __init__(self, handler: Callable[[DomainEvent], Awaitable[None]]) -> None:
        self._handler = handler

    async def handle(self, event: DomainEvent) -> None:
        await self._handler(event)