wecom_it_smart_desk/backend/app/schemas/triage.py

# =============================================================================
# 企微IT智能服务台 — 分诊交互 Pydantic Schema
# =============================================================================
# 说明：分诊模块的请求/响应数据模型，覆盖 H5 端和坐席端所有接口。
# =============================================================================

from datetime import datetime
from typing import Any, Dict, List, Optional

from pydantic import BaseModel, Field


# =============================================================================
# 基础嵌套模型
# =============================================================================

class TriageOption(BaseModel):
    """分诊选项。

    Attributes:
        label: 选项标签文本
        probability: AI 推荐概率（0.0-1.0）
    """

    label: str = Field(..., description="选项标签文本")
    probability: Optional[float] = Field(None, ge=0.0, le=1.0, description="AI推荐概率")


class TriageStep(BaseModel):
    """分诊步骤。

    Attributes:
        question: 步骤问题文本
        options: 选项列表
    """

    question: str = Field(..., description="步骤问题文本")
    options: List[TriageOption] = Field(default_factory=list, description="选项列表")


# =============================================================================
# H5 端请求 Schema
# =============================================================================

class TriageStartRequest(BaseModel):
    """发起分诊请求。

    Attributes:
        conversation_id: 会话ID
        question: 员工问题文本
    """

    conversation_id: str = Field(..., description="会话ID")
    question: str = Field(..., min_length=1, description="员工问题文本")


class TriageStepRequest(BaseModel):
    """提交步骤选择请求。

    Attributes:
        triage_id: 分诊会话ID
        step_index: 当前步骤序号（0-based）
        selected_label: 选择的选项标签
    """

    triage_id: str = Field(..., description="分诊会话ID")
    step_index: int = Field(..., ge=0, description="当前步骤序号")
    selected_label: str = Field(..., description="选择的选项标签")


class TriageSkipRequest(BaseModel):
    """跳过步骤请求。

    Attributes:
        triage_id: 分诊会话ID
        step_index: 要跳过的步骤序号
    """

    triage_id: str = Field(..., description="分诊会话ID")
    step_index: int = Field(..., ge=0, description="要跳过的步骤序号")


class TriageTransferRequest(BaseModel):
    """转人工请求。

    Attributes:
        triage_id: 分诊会话ID
        context: 已收集的上下文列表
    """

    triage_id: str = Field(..., description="分诊会话ID")
    context: List[str] = Field(default_factory=list, description="已收集的上下文列表")


class TriageCompleteRequest(BaseModel):
    """分诊完成请求。

    Attributes:
        triage_id: 分诊会话ID
        context: 已收集的上下文列表
    """

    triage_id: str = Field(..., description="分诊会话ID")
    context: List[str] = Field(default_factory=list, description="已收集的上下文列表")


# =============================================================================
# H5 端响应 Schema
# =============================================================================

class TriageStartResponse(BaseModel):
    """发起分诊响应。

    Attributes:
        triage_id: 分诊会话ID
        steps: 分诊步骤列表
        total: 总步骤数
        confidence: AI 置信度
        urgency: 紧急度
        suggested_route: AI 建议路由
    """

    triage_id: str = Field(..., description="分诊会话ID")
    steps: List[TriageStep] = Field(default_factory=list, description="分诊步骤列表")
    total: int = Field(0, description="总步骤数")
    confidence: Optional[float] = Field(None, description="AI 置信度")
    urgency: str = Field("medium", description="紧急度")
    suggested_route: Optional[str] = Field(None, description="AI 建议路由")


class TriageStepResponse(BaseModel):
    """提交步骤选择响应。

    Attributes:
        next_step: 下一步骤数据（无下一步时为 null）
        collected_context: 已收集的上下文列表
    """

    next_step: Optional[TriageStep] = Field(None, description="下一步骤数据")
    collected_context: List[str] = Field(default_factory=list, description="已收集的上下文列表")


class TriageTransferResponse(BaseModel):
    """转人工响应。

    Attributes:
        conversation_id: 会话ID
        status: 会话状态
    """

    conversation_id: str = Field(..., description="会话ID")
    status: str = Field("waiting_agent", description="会话状态")


class TriageCompleteResponse(BaseModel):
    """分诊完成响应。

    Attributes:
        reply: AI 生成的最终回复
        confidence: AI 置信度
    """

    reply: str = Field(..., description="AI 生成的最终回复")
    confidence: float = Field(0.0, description="AI 置信度")


# =============================================================================
# 坐席端请求 Schema
# =============================================================================

class TriageRouteRequest(BaseModel):
    """坐席路由操作请求。

    Attributes:
        route_action: 路由动作（ai_self/human/auto_approval/skip）
        route_note: 路由备注
    """

    route_action: str = Field(..., description="路由动作：ai_self/human/auto_approval/skip")
    route_note: Optional[str] = Field(None, description="路由备注")


class TriageExcludeOptionsRequest(BaseModel):
    """坐席排除/推荐分诊选项请求。

    Attributes:
        excluded_labels: 要排除的选项标签列表
        recommended_label: 推荐的选项标签
    """

    excluded_labels: List[str] = Field(default_factory=list, description="要排除的选项标签列表")
    recommended_label: Optional[str] = Field(None, description="推荐的选项标签")


# =============================================================================
# 坐席端响应 Schema
# =============================================================================

class TriageSessionResponse(BaseModel):
    """分诊会话列表项响应。

    Attributes:
        id: 分诊会话ID
        conversation_id: 会话ID
        user_id: 员工ID
        user_name: 员工姓名
        user_dept: 员工部门
        request_title: 问题标题
        problem_type: 问题类型
        problem_category: 问题分类
        confidence: AI 置信度
        urgency: 紧急度
        suggested_route: AI 建议路由
        status: 分诊状态
        route_action: 路由动作
        route_note: 路由备注
        operator_id: 操作坐席ID
        created_at: 创建时间
        operated_at: 操作时间
    """

    id: str = Field(..., description="分诊会话ID")
    conversation_id: str = Field(..., description="会话ID")
    user_id: str = Field(..., description="员工ID")
    user_name: Optional[str] = Field(None, description="员工姓名")
    user_dept: Optional[str] = Field(None, description="员工部门")
    request_title: str = Field(..., description="问题标题")
    problem_type: Optional[str] = Field(None, description="问题类型")
    problem_category: Optional[str] = Field(None, description="问题分类")
    confidence: Optional[float] = Field(None, description="AI 置信度")
    urgency: str = Field("medium", description="紧急度")
    suggested_route: Optional[str] = Field(None, description="AI 建议路由")
    status: str = Field("pending", description="分诊状态")
    route_action: Optional[str] = Field(None, description="路由动作")
    route_note: Optional[str] = Field(None, description="路由备注")
    operator_id: Optional[str] = Field(None, description="操作坐席ID")
    created_at: Optional[datetime] = Field(None, description="创建时间")
    operated_at: Optional[datetime] = Field(None, description="操作时间")

    model_config = {"from_attributes": True}


class TriageDetailResponse(BaseModel):
    """分诊详情响应（含完整数据）。

    Attributes:
        id: 分诊会话ID
        conversation_id: 会话ID
        user_id: 员工ID
        user_name: 员工姓名
        user_dept: 员工部门
        user_level: 员工IT技能等级
        device_info: 设备信息
        request_title: 问题标题
        request_content: 问题原文
        source: 来源渠道
        problem_type: 问题类型
        problem_category: 问题分类
        confidence: AI 置信度
        urgency: 紧急度
        suggested_route: AI 建议路由
        matched_knowledge: 匹配到的知识条目
        match_score: 知识匹配分数
        context_tags: 上下文标签列表
        triage_steps: 分诊步骤数据
        collected_context: 已收集的上下文列表
        status: 分诊状态
        route_action: 路由动作
        route_note: 路由备注
        operator_id: 操作坐席ID
        created_at: 创建时间
        updated_at: 更新时间
        operated_at: 操作时间
    """

    id: str = Field(..., description="分诊会话ID")
    conversation_id: str = Field(..., description="会话ID")
    user_id: str = Field(..., description="员工ID")
    user_name: Optional[str] = Field(None, description="员工姓名")
    user_dept: Optional[str] = Field(None, description="员工部门")
    user_level: Optional[str] = Field(None, description="员工IT技能等级")
    device_info: Optional[str] = Field(None, description="设备信息")
    request_title: str = Field(..., description="问题标题")
    request_content: str = Field(..., description="问题原文")
    source: str = Field("wecom_h5", description="来源渠道")
    problem_type: Optional[str] = Field(None, description="问题类型")
    problem_category: Optional[str] = Field(None, description="问题分类")
    confidence: Optional[float] = Field(None, description="AI 置信度")
    urgency: str = Field("medium", description="紧急度")
    suggested_route: Optional[str] = Field(None, description="AI 建议路由")
    matched_knowledge: Optional[str] = Field(None, description="匹配到的知识条目")
    match_score: Optional[float] = Field(None, description="知识匹配分数")
    context_tags: List[str] = Field(default_factory=list, description="上下文标签列表")
    triage_steps: List[Dict[str, Any]] = Field(default_factory=list, description="分诊步骤数据")
    collected_context: List[str] = Field(default_factory=list, description="已收集的上下文列表")
    status: str = Field("pending", description="分诊状态")
    route_action: Optional[str] = Field(None, description="路由动作")
    route_note: Optional[str] = Field(None, description="路由备注")
    operator_id: Optional[str] = Field(None, description="操作坐席ID")
    created_at: Optional[datetime] = Field(None, description="创建时间")
    updated_at: Optional[datetime] = Field(None, description="更新时间")
    operated_at: Optional[datetime] = Field(None, description="操作时间")

    model_config = {"from_attributes": True}


class TriageStatsResponse(BaseModel):
    """分诊看板统计概要响应。

    Attributes:
        pending_total: 待分诊总数
        today_triaged: 今日已分诊数
        ai_self_count: AI 自答数
        human_count: 转人工数
        auto_approval_count: 自动审批数
        avg_duration_sec: 平均耗时（秒）
    """

    pending_total: int = Field(0, description="待分诊总数")
    today_triaged: int = Field(0, description="今日已分诊数")
    ai_self_count: int = Field(0, description="AI 自答数")
    human_count: int = Field(0, description="转人工数")
    auto_approval_count: int = Field(0, description="自动审批数")
    avg_duration_sec: float = Field(0.0, description="平均耗时（秒）")