wecom_it_smart_desk/backend/app/schemas/exclusion.py

# =============================================================================
# 企微IT智能服务台 — 代答排除 Pydantic Schema
# =============================================================================
# 说明：代答排除模块的请求/响应数据模型，覆盖管理后台所有接口。
# =============================================================================

from datetime import datetime
from typing import List, Optional

from pydantic import BaseModel, Field


# =============================================================================
# 请求 Schema
# =============================================================================

class ExclusionRuleCreate(BaseModel):
    """新建排除规则请求。

    Attributes:
        rule_name: 规则名称（唯一）
        rule_description: 规则描述
        priority: 优先级（P0/P1/P2/P3）
        match_type: 匹配方式（keyword/regex/intent/category）
        match_condition: 匹配条件
        match_scope: 匹配范围
        action_type: 命中后动作类型
        transfer_message: 转人工提示语
    """

    rule_name: str = Field(..., min_length=1, max_length=200, description="规则名称")
    rule_description: Optional[str] = Field(None, description="规则描述")
    priority: str = Field("P2", description="优先级：P0/P1/P2/P3")
    match_type: str = Field(..., description="匹配方式：keyword/regex/intent/category")
    match_condition: str = Field(..., min_length=1, description="匹配条件")
    match_scope: List[str] = Field(default_factory=lambda: ["ai_auto_reply"], description="匹配范围")
    action_type: str = Field("transfer_human", description="命中后动作类型")
    transfer_message: Optional[str] = Field(None, description="转人工提示语")


class ExclusionRuleUpdate(BaseModel):
    """编辑排除规则请求。

    所有字段可选，仅更新传入的字段。

    Attributes:
        rule_name: 规则名称
        rule_description: 规则描述
        priority: 优先级
        match_type: 匹配方式
        match_condition: 匹配条件
        match_scope: 匹配范围
        action_type: 命中后动作类型
        transfer_message: 转人工提示语
    """

    rule_name: Optional[str] = Field(None, min_length=1, max_length=200, description="规则名称")
    rule_description: Optional[str] = Field(None, description="规则描述")
    priority: Optional[str] = Field(None, description="优先级")
    match_type: Optional[str] = Field(None, description="匹配方式")
    match_condition: Optional[str] = Field(None, description="匹配条件")
    match_scope: Optional[List[str]] = Field(None, description="匹配范围")
    action_type: Optional[str] = Field(None, description="命中后动作类型")
    transfer_message: Optional[str] = Field(None, description="转人工提示语")


class ExclusionRuleToggle(BaseModel):
    """启用/停用规则请求。

    Attributes:
        status: 目标状态（enabled/disabled）
    """

    status: str = Field(..., description="目标状态：enabled/disabled")


class ExclusionTestRequest(BaseModel):
    """测试匹配请求。

    Attributes:
        message: 测试消息文本
        rule_id: 指定规则ID（可选，不指定则测试所有启用规则）
    """

    message: str = Field(..., min_length=1, description="测试消息文本")
    rule_id: Optional[str] = Field(None, description="指定规则ID")


# =============================================================================
# 查询参数 Schema
# =============================================================================

class ExclusionRuleQuery(BaseModel):
    """排除规则列表查询参数。

    Attributes:
        status: 状态筛选
        match_type: 匹配方式筛选
        priority: 优先级筛选
        keyword: 关键词搜索（规则名称/描述）
        page: 页码
        page_size: 每页数量
    """

    status: Optional[str] = Field(None, description="状态筛选")
    match_type: Optional[str] = Field(None, description="匹配方式筛选")
    priority: Optional[str] = Field(None, description="优先级筛选")
    keyword: Optional[str] = Field(None, description="关键词搜索")
    page: int = Field(1, ge=1, description="页码")
    page_size: int = Field(20, ge=1, le=100, description="每页数量")


# =============================================================================
# 响应 Schema
# =============================================================================

class ExclusionRuleResponse(BaseModel):
    """排除规则响应。

    Attributes:
        id: 规则ID
        rule_name: 规则名称
        rule_description: 规则描述
        priority: 优先级
        match_type: 匹配方式
        match_condition: 匹配条件
        match_scope: 匹配范围
        action_type: 命中后动作类型
        transfer_message: 转人工提示语
        status: 状态
        hit_count: 命中次数
        created_by: 创建人ID
        created_at: 创建时间
        updated_at: 更新时间
    """

    id: str = Field(..., description="规则ID")
    rule_name: str = Field(..., description="规则名称")
    rule_description: Optional[str] = Field(None, description="规则描述")
    priority: str = Field(..., description="优先级")
    match_type: str = Field(..., description="匹配方式")
    match_condition: str = Field(..., description="匹配条件")
    match_scope: List[str] = Field(default_factory=list, description="匹配范围")
    action_type: str = Field(..., description="命中后动作类型")
    transfer_message: Optional[str] = Field(None, description="转人工提示语")
    status: str = Field(..., description="状态")
    hit_count: int = Field(0, description="命中次数")
    created_by: str = Field(..., description="创建人ID")
    created_at: Optional[datetime] = Field(None, description="创建时间")
    updated_at: Optional[datetime] = Field(None, description="更新时间")

    model_config = {"from_attributes": True}


class ExclusionTestResponse(BaseModel):
    """测试匹配响应。

    Attributes:
        matched: 是否命中
        matched_detail: 命中详情
        rule_name: 命中的规则名称
        action_type: 命中后动作类型
    """

    matched: bool = Field(False, description="是否命中")
    matched_detail: Optional[str] = Field(None, description="命中详情")
    rule_name: Optional[str] = Field(None, description="命中的规则名称")
    action_type: Optional[str] = Field(None, description="命中后动作类型")


class ExclusionStatsResponse(BaseModel):
    """排除规则统计概要响应。

    Attributes:
        enabled_count: 启用规则数
        disabled_count: 停用规则数
        monthly_hits: 本月命中次数
        monthly_transfers: 本月转人工次数
    """

    enabled_count: int = Field(0, description="启用规则数")
    disabled_count: int = Field(0, description="停用规则数")
    monthly_hits: int = Field(0, description="本月命中次数")
    monthly_transfers: int = Field(0, description="本月转人工次数")