wecom_it_smart_desk/backend/app/schemas/h5.py

# =============================================================================
# 企微IT智能服务台 — H5 用户端 Pydantic Schema
# =============================================================================
# 说明：定义H5用户端专用的请求/响应数据结构
# 包含：摇人请求、OAuth回调、审批链接、软件下载、员工信息等
# =============================================================================

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

from pydantic import BaseModel, Field


# --------------------------------------------------------------------------
# 摇人请求 Schema
# --------------------------------------------------------------------------
class ShakeRequest(BaseModel):
    """摇人请求 Schema。

    用户点击H5页面摇人按钮时发送的请求。

    Attributes:
        employee_id: 企微员工UserID
        employee_name: 员工姓名
    """

    employee_id: str = Field(..., min_length=1, max_length=64, description="企微员工UserID")
    employee_name: str = Field(default="", max_length=128, description="员工姓名")


# --------------------------------------------------------------------------
# 摇人响应 Schema
# --------------------------------------------------------------------------
class ShakeResponse(BaseModel):
    """摇人响应 Schema。

    摇人成功后返回会话信息和趣味话术。

    Attributes:
        conversation: 会话信息（包含ID、状态、标签）
        funny_phrase: 趣味话术内容
    """

    conversation: Dict[str, Any] = Field(..., description="会话信息")
    funny_phrase: str = Field(..., description="趣味话术")


# --------------------------------------------------------------------------
# OAuth2 回调请求 Schema
# --------------------------------------------------------------------------
class OAuthCallbackRequest(BaseModel):
    """OAuth2 回调请求 Schema。

    H5页面通过企微OAuth2授权后，将code传给后端换取员工身份。

    Attributes:
        code: 企微OAuth2授权码
    """

    code: str = Field(..., min_length=1, description="企微OAuth2授权码")


# --------------------------------------------------------------------------
# OAuth2 回调响应 Schema
# --------------------------------------------------------------------------
class OAuthCallbackResponse(BaseModel):
    """OAuth2 回调响应 Schema。

    用授权码换取到的员工身份信息和访问令牌。

    Attributes:
        employee_id: 企微员工UserID
        employee_name: 员工姓名
        token: 访问令牌（用于后续API请求的Bearer Token）
        department: 部门名称
        position: 岗位
        avatar: 头像URL
    """

    employee_id: str = Field(..., description="企微员工UserID")
    employee_name: str = Field(default="", description="员工姓名")
    token: str = Field(..., description="访问令牌")
    department: str = Field(default="", description="部门名称")
    position: str = Field(default="", description="岗位")
    avatar: str = Field(default="", description="头像URL")


# --------------------------------------------------------------------------
# OAuth2 授权URL响应 Schema
# --------------------------------------------------------------------------
class OAuthAuthorizeResponse(BaseModel):
    """OAuth2 授权URL响应 Schema。

    返回企微OAuth2授权链接，前端跳转到此URL进行授权。

    Attributes:
        authorize_url: 企微OAuth2授权URL
    """

    authorize_url: str = Field(..., description="企微OAuth2授权URL")


# --------------------------------------------------------------------------
# 员工信息 Schema
# --------------------------------------------------------------------------
class EmployeeInfo(BaseModel):
    """员工信息 Schema。

    从企微通讯录获取的员工详细信息。

    Attributes:
        employee_id: 企微员工UserID
        employee_name: 员工姓名
        department: 部门名称（逗号分隔）
        position: 岗位
        mobile: 手机号
        email: 邮箱
        avatar: 头像URL
        is_vip: 是否VIP员工
    """

    employee_id: str = Field(..., description="企微员工UserID")
    employee_name: str = Field(default="", description="员工姓名")
    department: str = Field(default="", description="部门名称")
    position: str = Field(default="", description="岗位")
    mobile: str = Field(default="", description="手机号")
    email: str = Field(default="", description="邮箱")
    avatar: str = Field(default="", description="头像URL")
    is_vip: bool = Field(default=False, description="是否VIP员工")


# --------------------------------------------------------------------------
# 审批链接响应 Schema
# --------------------------------------------------------------------------
class ApprovalLinkResponse(BaseModel):
    """审批链接响应 Schema。

    H5用户端AI助手面板中的审批流程链接。

    Attributes:
        id: 链接ID
        category: 分类
        title: 审批名称
        url: 审批链接
        sort_order: 排序权重
    """

    id: str
    category: str
    title: str
    url: str
    sort_order: int

    model_config = {"from_attributes": True}


# --------------------------------------------------------------------------
# 软件下载响应 Schema
# --------------------------------------------------------------------------
class SoftwareDownloadResponse(BaseModel):
    """软件下载响应 Schema。

    H5用户端AI助手面板中的软件下载入口。

    Attributes:
        id: 下载入口ID
        category: 分类
        name: 软件名称
        version: 版本号
        platform: 平台
        download_url: 下载链接
        sort_order: 排序权重
    """

    id: str
    category: str
    name: str
    version: str
    platform: str
    download_url: str
    sort_order: int

    model_config = {"from_attributes": True}


# --------------------------------------------------------------------------
# 审批链接列表响应 Schema
# --------------------------------------------------------------------------
class ApprovalLinkListResponse(BaseModel):
    """审批链接列表响应 Schema。

    Attributes:
        items: 审批链接列表
    """

    items: List[ApprovalLinkResponse]


# --------------------------------------------------------------------------
# 软件下载列表响应 Schema
# --------------------------------------------------------------------------
class SoftwareDownloadListResponse(BaseModel):
    """软件下载列表响应 Schema。

    Attributes:
        items: 软件下载列表
    """

    items: List[SoftwareDownloadResponse]