wecom_it_smart_desk/backend/app/services/matchers/base.py

# =============================================================================
# 企微IT智能服务台 — 匹配器基类 + 匹配结果
# =============================================================================
# 说明：策略模式接口定义，所有匹配器必须继承 BaseMatcher 并实现 match 方法。
# =============================================================================

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional


@dataclass
class MatchResult:
    """匹配结果。

    Attributes:
        matched: 是否命中
        matched_detail: 命中的关键词/正则/意图/分类（用于日志和测试展示）
        match_position: 匹配位置（用于测试展示，如 "位置 12-18"）
    """

    matched: bool
    matched_detail: str = ""
    match_position: str = ""


class BaseMatcher(ABC):
    """匹配器基类 — 策略模式接口。

    每种匹配器实现一种匹配逻辑（关键词/正则/意图/分类），
    由 ExclusionService 责任链按优先级依次调用。
    """

    @abstractmethod
    async def match(
        self,
        message: str,
        condition: str,
        context: Optional[dict] = None,
    ) -> MatchResult:
        """检查消息是否匹配规则条件。

        Args:
            message: 用户消息文本
            condition: 匹配条件
                - keyword: 逗号分隔关键词列表（如 "密码过期,账号锁定"）
                - regex: 正则表达式（如 "密码.*过期"）
                - intent: 逗号分隔意图ID列表（如 "password_reset,account_unlock"）
                - category: 逗号分隔分类名称列表（如 "Outlook,VPN"）
            context: 上下文字典，可含 conversation_id, user_id, db 等

        Returns:
            MatchResult: 匹配结果
        """
        ...