wecom_it_smart_desk/backend/app/api/queue.py

# =============================================================================
# 企微IT智能服务台 — 排队综合查询 API
# =============================================================================
# 说明：提供排队位置、平台统计、坐席看板等综合查询接口
#
# 路由：
#   GET /api/h5/queue/status       — 员工端综合排队状态
#   GET /api/agent/queue/dashboard — 坐席端排队看板数据
# =============================================================================

import logging
from typing import Optional

from fastapi import APIRouter, Depends, Header, Query
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from app.database import get_db
from app.models.conversation import Conversation
from app.services.queue_service import get_queue_service
from app.utils.response import AppException, success_response

logger = logging.getLogger(__name__)

router = APIRouter(tags=["queue"])


# =============================================================================
# H5 端：综合排队状态
# =============================================================================
@router.get("/h5/queue/status")
async def get_queue_status(
    employee_id: str = Query(..., description="员工ID"),
    db: AsyncSession = Depends(get_db),
):
    """获取综合排队状态（排队位置+段位+平台统计+答题状态+积分）。

    供 H5 端 QueueWaiting.vue 组件初始化时调用。
    包含三段排序的排队位置、平台实时统计、答题插队进度、员工积分等级。

    Args:
        employee_id: 员工企微 UserID

    Returns:
        综合状态数据
    """
    queue_service = get_queue_service()

    # 查找员工当前活跃会话（排队中或服务中）
    stmt = select(Conversation).where(
        Conversation.employee_id == employee_id,
        Conversation.status.in_(["ai_handling", "queued", "serving", "pending_close"]),
    ).order_by(Conversation.created_at.desc())

    result = await db.execute(stmt)
    conversation = result.scalars().first()

    if not conversation:
        # 无活跃会话 — 返回平台统计+默认积分
        platform_stats = await queue_service.get_platform_stats(db)
        points_info = await queue_service._get_employee_points(db, employee_id)
        return success_response(data={
            "conversation_status": None,
            "queue": {
                "position": 0,
                "segment": "none",
                "segment_label": "无活跃会话",
                "ahead_count": 0,
                "estimated_wait_sec": 0,
                "estimated_wait_text": "—",
                "queue_priority": 0,
            },
            "platform": platform_stats,
            "points": points_info,
            "quiz": {
                "answered_in_session": 0,
                "queue_priority": 0,
                "max_priority": 2,
                "remaining_for_next_jump": 0,
                "can_jump_more": False,
            },
            "info_locked": False,
        })

    # 有活跃会话 — 返回综合状态
    status = await queue_service.get_comprehensive_status(db, conversation)
    return success_response(data=status)


# =============================================================================
# 坐席端：排队看板
# =============================================================================
@router.get("/agent/queue/dashboard")
async def get_agent_queue_dashboard(
    authorization: Optional[str] = Header(None, alias="Authorization"),
    db: AsyncSession = Depends(get_db),
):
    """获取坐席端排队看板数据。

    返回排队分段统计、平台统计、按三段排序的排队列表。
    供坐席端 ConversationList.vue 的"排队等候"区段展示。

    Returns:
        看板数据（分段统计+排队列表）
    """
    queue_service = get_queue_service()
    dashboard = await queue_service.get_agent_dashboard(db)
    return success_response(data=dashboard)