WechatOnCloud/bridge/woc_bridge/ui/orchestrator.py

"""L5 FlowOrchestrator：编排幂等/熔断/会话缓存/队列/Flow。

send_text 流程：
1. 幂等检查（命中返回 skipped=true）
2. DB 校验熔断检查（OPEN 时返回 BRIDGE_CIRCUITED）
3. 入队（自适应 delay_ms：同联系人 1000 / 不同 config.send_delay_ms）
4. 成功且 verified 才写幂等缓存
5. DB 校验失败计数 + 熔断
6. 失败时 session_cache.invalidate(to_wxid)（仅失效当前联系人）
"""

from __future__ import annotations

import asyncio
import logging
import time
from collections import OrderedDict
from typing import Optional, TYPE_CHECKING

from woc_bridge.models import BridgeError

if TYPE_CHECKING:
    from woc_bridge.ui.flows.send_file import SendFileFlow
    from woc_bridge.ui.flows.send_text import SendTextFlow
from woc_bridge.ui.circuit_breaker import CircuitBreaker, CircuitState
from woc_bridge.ui.errors import FlowError, is_retryable
from woc_bridge.ui.flow import FlowContext, FlowResult, FlowState
from woc_bridge.ui.idem_cache import IdemCache

logger = logging.getLogger("woc-bridge")

# 同联系人发送间隔（毫秒），比默认 send_delay_ms 短
_SAME_CONTACT_DELAY_MS = 1000


class SessionCache:
    """会话缓存：LRU 多会话，30s TTL。

    命中时 SendTextFlow 跳过 activate/click_search_box/type_query/open_session 四步，
    直接校验会话仍打开后进入 focus_input。
    多会话缓存提升 30-100 并发人群中重复联系人的命中率。
    """

    def __init__(self, ttl: float = 30.0, max_size: int = 16) -> None:
        self.ttl = ttl
        self.max_size = max_size
        # wxid -> expire_at，按最近使用排序
        self._cache: OrderedDict[str, float] = OrderedDict()

    def get(self, to_wxid: str) -> bool:
        """查询指定 wxid 是否在缓存且未过期。命中时移到队尾（最近使用）。"""
        expire_at = self._cache.get(to_wxid)
        if expire_at is None:
            return False
        if time.monotonic() >= expire_at:
            self._cache.pop(to_wxid, None)
            return False
        self._cache.move_to_end(to_wxid)
        return True

    def set(self, to_wxid: str) -> None:
        """更新缓存。"""
        self._cache[to_wxid] = time.monotonic() + self.ttl
        self._cache.move_to_end(to_wxid)
        # 超限淘汰最久未使用
        while len(self._cache) > self.max_size:
            self._cache.popitem(last=False)

    def invalidate(self, to_wxid: Optional[str] = None) -> None:
        """失效缓存。

        Args:
            to_wxid: 为 None 时清除全部缓存；为具体 wxid 时仅清除该条目
                      （传空字符串不会误清全部）。
        """
        if to_wxid is None:
            self._cache.clear()
        else:
            self._cache.pop(to_wxid, None)


class FlowOrchestrator:
    """L5 Flow 编排器。

    整合幂等缓存、熔断器、会话缓存、发送队列、Flow 执行。
    """

    def __init__(
        self,
        send_queue,
        idem_cache: IdemCache,
        actions,
        db_reader,
        config,
        send_text_flow: Optional[SendTextFlow] = None,
        send_file_flow: Optional[SendFileFlow] = None,
    ) -> None:
        """初始化编排器。

        Args:
            send_queue: SendQueue 实例
            idem_cache: IdemCache 实例
            actions: L3 Actions 实例
            db_reader: DbReader 实例
            config: BridgeConfig 实例（含 send_delay_ms 等）
            send_text_flow: 可选的 SendTextFlow 实例（用于测试注入）
            send_file_flow: 可选的 SendFileFlow 实例（必须由 app._init_state 注入，
                因 SendFileFlow 依赖 XdotoolDriver，orchestrator 无法惰性创建）
        """
        self.send_queue = send_queue
        self.idem_cache = idem_cache
        self.actions = actions
        self.db_reader = db_reader
        self.config = config
        # LRU 多会话缓存：最多 16 个会话，30s TTL
        self.session_cache = SessionCache(ttl=30.0, max_size=16)
        # DB 校验熔断器：10 次失败 / 30s 恢复（高并发下更宽容）
        self.db_verify_breaker = CircuitBreaker(
            "db_verify", failure_threshold=10, recovery_timeout=30.0
        )
        self._send_text_flow = send_text_flow
        self._send_file_flow = send_file_flow

    def _get_send_text_flow(self):
        """获取 SendTextFlow 实例（惰性创建或使用注入的）。"""
        if self._send_text_flow is not None:
            return self._send_text_flow
        # 惰性导入避免循环依赖
        from woc_bridge.ui.flows.send_text import SendTextFlow
        return SendTextFlow(
            actions=self.actions,
            db_reader=self.db_reader,
            session_cache=self.session_cache,
        )

    def _get_send_file_flow(self):
        """获取 SendFileFlow 实例（必须由 app._init_state 注入）。

        SendFileFlow 依赖 XdotoolDriver（用于 xdotool type 路径），
        orchestrator 未持有 XdotoolDriver 引用，无法惰性创建。
        未注入时抛 BridgeError(BRIDGE_INTERNAL_ERROR)。
        """
        if self._send_file_flow is not None:
            return self._send_file_flow
        raise BridgeError(
            code="BRIDGE_INTERNAL_ERROR",
            message="send_file_flow 未初始化（需在 app._init_state 中注入 SendFileFlow）",
        )

    async def send_text(
        self,
        to_wxid: str,
        content: str,
        display_name: str = "",
        client_request_id: str = "",
    ) -> FlowResult:
        """发送文本消息。

        流程：
        1. 幂等检查
        2. DB 校验熔断检查
        3. 自适应延时入队
        4. 执行 SendTextFlow
        5. 成功且 verified 写幂等缓存
        6. 失败时失效会话缓存

        Args:
            to_wxid: 目标 wxid
            content: 消息内容
            display_name: 显示名（搜索用）
            client_request_id: 客户端幂等 ID

        Returns:
            FlowResult
        """
        started_at = time.monotonic()

        logger.info(
            "[orchestrator] send_text START to_wxid=%s content_len=%d display_name=%s client_request_id=%s",
            to_wxid, len(content), display_name or "(empty)", client_request_id or "(none)",
        )

        # 1. 幂等检查
        cached = self.idem_cache.get(
            "send_text", to_wxid, content, client_request_id
        )
        if cached is not None:
            logger.info(
                "[orchestrator] idem cache hit, skip send (to_wxid=%s)",
                to_wxid,
            )
            # 返回缓存的 FlowResult，标记 skipped
            if isinstance(cached, FlowResult):
                return FlowResult(
                    success=True,
                    local_id=cached.local_id,
                    verified=cached.verified,
                    skipped=True,
                    state=cached.state,
                    duration_ms=(time.monotonic() - started_at) * 1000,
                )
            # 兜底：构造一个 skipped 结果
            return FlowResult(
                success=True,
                skipped=True,
                duration_ms=(time.monotonic() - started_at) * 1000,
            )

        # 2. DB 校验熔断检查
        if not self.db_verify_breaker.allow():
            logger.warning(
                "[orchestrator] db_verify breaker OPEN, reject send (to_wxid=%s)",
                to_wxid,
            )
            return FlowResult(
                success=False,
                error="db_verify circuit breaker open",
                error_code="BRIDGE_CIRCUITED",
                state=FlowState.FAILED,
                duration_ms=(time.monotonic() - started_at) * 1000,
            )

        # 3. 自适应延时：同联系人用短延时
        is_same_contact = self.session_cache.get(to_wxid)
        delay_ms = _SAME_CONTACT_DELAY_MS if is_same_contact else None
        # None 表示用 send_queue 的默认 send_delay_ms
        logger.info(
            "[orchestrator] send_text enqueue: same_contact=%s delay_ms=%s to_wxid=%s",
            is_same_contact, delay_ms, to_wxid,
        )

        # 4. 构造 FlowContext
        ctx = FlowContext(
            to_wxid=to_wxid,
            content=content,
            display_name=display_name,
            client_request_id=client_request_id,
        )

        # 5. 入队执行（带队列等待超时，避免无界排队）
        flow = self._get_send_text_flow()
        try:
            result: FlowResult = await self.send_queue.enqueue(
                lambda: flow.run(ctx),
                delay_ms=delay_ms,
                wait_timeout_ms=self.config.send_queue_wait_timeout_ms,
            )
        except Exception as exc:
            logger.error(
                "[orchestrator] send_queue exception: %s: %s (to_wxid=%s)",
                type(exc).__name__, exc, to_wxid,
            )
            # 失败时仅失效当前联系人会话缓存，避免误伤其它缓存命中
            self.session_cache.invalidate(to_wxid)
            # 保留 BridgeError 的原始错误码（如 RATE_LIMITED），
            # 避免限流/超时等可重试错误被吞成 SEND_FAILED
            error_code = "SEND_FAILED"
            if hasattr(exc, "code") and exc.code:
                error_code = exc.code
            # 传递 details（如 retry_after）供路由层设置 Retry-After 头
            exc_details = None
            if hasattr(exc, "details") and exc.details:
                exc_details = exc.details
            return FlowResult(
                success=False,
                error=str(exc),
                error_code=error_code,
                state=FlowState.FAILED,
                duration_ms=(time.monotonic() - started_at) * 1000,
                details=exc_details,
            )

        # 6. 结果处理
        if result.success and result.verified:
            # 成功且 verified：写幂等缓存
            self.idem_cache.set(
                "send_text", to_wxid, content, result, client_request_id
            )
            self.db_verify_breaker.record_success()
            logger.info(
                "[orchestrator] send_text DONE ✓ to_wxid=%s local_id=%s verified=%s (%.0fms)",
                to_wxid, result.local_id, result.verified,
                (time.monotonic() - started_at) * 1000,
            )
        elif result.success and not result.verified:
            # 发送成功但校验失败：DB 校验熔断计数
            self.db_verify_breaker.record_failure()
            logger.warning(
                "[orchestrator] send success but verify failed, breaker fail_count+1 (to_wxid=%s)",
                to_wxid,
            )
        else:
            # 发送失败：仅失效当前联系人会话缓存，避免误伤其它缓存命中
            self.session_cache.invalidate(to_wxid)
            logger.warning(
                "[orchestrator] send failed: %s (code=%s, to_wxid=%s)",
                result.error, result.error_code, to_wxid,
            )

        return result

    async def send_file(
        self,
        to_wxid: str,
        file_path: str,
        file_type: str = "file",
        client_request_id: Optional[str] = None,
        display_name: Optional[str] = None,
    ) -> dict:
        """文件发送 Flow 编排：幂等检查 + 熔断 + 入队 + DB 校验。

        流程：
        1. 幂等检查（命中返回 skipped=True）
        2. DB 校验熔断检查（OPEN 时返回 BRIDGE_CIRCUITED）
        3. 入队执行 SendFileFlow.execute（路径白名单 + 文件选择器输入 + post_verify）
        4. 成功且 verified 写幂等缓存
        5. DB 校验失败计数 + 熔断
        6. 失败时失效会话缓存

        幂等缓存键：(send_file, to_wxid, file_path, client_request_id)
        （IdemCache API 仅支持 4 段 key，file_path 作为 content 槽位传入）

        Args:
            to_wxid: 目标会话 wxid
            file_path: 文件绝对路径（必须在白名单目录内）
            file_type: "image" / "file" / "video"（仅用于日志，不影响流程）
            client_request_id: 客户端幂等 ID（None 或空字符串表示不参与幂等）
            display_name: 用于微信搜索框定位会话的显示名（备注/昵称），
                          None 时 SendFileFlow 回退到 to_wxid 搜索

        Returns:
            {"success": bool, "verified": bool, "placeholder": False,
             "skipped": bool, "error": Optional[str], "error_code": Optional[str]}

        Raises:
            BridgeError(BRIDGE_INTERNAL_ERROR): send_file_flow 未注入
        """
        started_at = time.monotonic()
        # client_request_id 归一化：None -> ""
        idem_id = client_request_id or ""

        logger.info(
            "[orchestrator] send_file START to_wxid=%s file=%s type=%s display_name=%s client_request_id=%s",
            to_wxid, file_path, file_type, display_name or "(none)", idem_id or "(none)",
        )

        # 1. 幂等检查
        cached = self.idem_cache.get("send_file", to_wxid, file_path, idem_id)
        if cached is not None:
            logger.info(
                "[orchestrator] send_file idem cache hit, skip (to_wxid=%s)",
                to_wxid,
            )
            if isinstance(cached, dict):
                return {
                    "success": cached.get("success", True),
                    "verified": cached.get("verified", False),
                    "placeholder": False,
                    "skipped": True,
                    "error": None,
                    "error_code": None,
                }
            # 兜底：构造一个 skipped 结果
            return {
                "success": True, "verified": False, "placeholder": False,
                "skipped": True, "error": None, "error_code": None,
            }

        # 2. DB 校验熔断检查
        if not self.db_verify_breaker.allow():
            logger.warning(
                "[orchestrator] send_file: db_verify breaker OPEN, reject (to_wxid=%s)",
                to_wxid,
            )
            return {
                "success": False, "verified": False, "placeholder": False,
                "skipped": False,
                "error": "db_verify circuit breaker open",
                "error_code": "BRIDGE_CIRCUITED",
            }

        # 3. 获取 SendFileFlow 实例（未注入时抛 BridgeError）
        flow = self._get_send_file_flow()

        # 4. 入队执行（SendFileFlow.execute 内部完成路径校验 + 文件选择器输入 + post_verify）
        logger.info(
            "[orchestrator] send_file enqueue (pending=%d)",
            self.send_queue.pending_count(),
        )
        try:
            result = await self.send_queue.enqueue(
                lambda: flow.execute(
                    to_wxid, file_path, file_type, display_name=display_name
                ),
                wait_timeout_ms=self.config.send_queue_wait_timeout_ms,
            )
        except BridgeError as exc:
            logger.error(
                "[orchestrator] send_file BridgeError code=%s msg=%s (to_wxid=%s)",
                exc.code, exc.message, to_wxid,
            )
            # 失败时失效当前联系人会话缓存
            self.session_cache.invalidate(to_wxid)
            return {
                "success": False, "verified": False, "placeholder": False,
                "skipped": False,
                "error": exc.message,
                "error_code": exc.code,
            }
        except Exception as exc:
            logger.error(
                "[orchestrator] send_file exception: %s: %s (to_wxid=%s)",
                type(exc).__name__, exc, to_wxid,
            )
            self.session_cache.invalidate(to_wxid)
            return {
                "success": False, "verified": False, "placeholder": False,
                "skipped": False,
                "error": str(exc),
                "error_code": "SEND_FAILED",
            }

        # 5. 结果处理
        # SendFileFlow.execute 返回 {"success": bool, "verified": Optional[bool], "error": Optional[str]}
        # verified=None 表示无法校验（DB 不可用或无基线），不计熔断失败
        success = result.get("success", False)
        verified = result.get("verified", False)

        if success and verified:
            # 成功且 verified：写幂等缓存 + 熔断成功
            self.idem_cache.set(
                "send_file", to_wxid, file_path, result, idem_id
            )
            self.db_verify_breaker.record_success()
            # 更新会话缓存（send_file 打开了 to_wxid 会话）
            self.session_cache.set(to_wxid)
            logger.info(
                "[orchestrator] send_file DONE ✓ to=%s file=%s verified=%s (%.0fms)",
                to_wxid, file_path, verified,
                (time.monotonic() - started_at) * 1000,
            )
        elif success and verified is False:
            # 发送成功但校验失败（真正的超时/未匹配）：DB 校验熔断计数
            self.db_verify_breaker.record_failure()
            self.session_cache.set(to_wxid)
            logger.warning(
                "[orchestrator] send_file success but verify failed, breaker fail_count+1 (to_wxid=%s)",
                to_wxid,
            )
        elif success and verified is None:
            # P0 修复：发送成功但无法校验（DB 不可用或无基线）：
            # 不计熔断失败，避免 DB 不可用时熔断器雪崩阻塞全部发送。
            # 也不写幂等缓存（未校验的结果不应被复用）。
            self.session_cache.set(to_wxid)
            logger.info(
                "[orchestrator] send_file success but verify skipped (DB unavailable), breaker untouched (to_wxid=%s)",
                to_wxid,
            )
        else:
            # 发送失败：仅失效当前联系人会话缓存
            self.session_cache.invalidate(to_wxid)
            logger.warning(
                "[orchestrator] send_file failed: %s (to_wxid=%s)",
                result.get("error"), to_wxid,
            )

        return {
            "success": success,
            "verified": verified,
            "placeholder": False,
            "skipped": False,
            "error": result.get("error"),
            "error_code": None,
        }