wecom_it_smart_desk/backend/app/schemas/auth.py

# =============================================================================
# 企微IT智能服务台 — 认证 API Schema
# =============================================================================
# 说明：定义认证相关的请求/响应数据结构
# 包含：统一认证API的请求/响应 Schema
# 三端认证重构：取消OTP/账号密码登录，统一为企微扫码认证
# =============================================================================

from datetime import datetime
from typing import List, Optional

from pydantic import BaseModel, Field


# --------------------------------------------------------------------------
# 登录方式合法值
# --------------------------------------------------------------------------
VALID_LOGIN_METHODS = {"oauth", "qrcode", "bind"}

# --------------------------------------------------------------------------
# 登录来源合法值
# --------------------------------------------------------------------------
VALID_LOGIN_SOURCES = {"h5", "agent", "admin"}

# --------------------------------------------------------------------------
# 登录状态合法值
# --------------------------------------------------------------------------
VALID_LOGIN_STATUSES = {"success", "failed", "cancelled"}


# --------------------------------------------------------------------------
# Token 验证响应 Schema
# --------------------------------------------------------------------------
class TokenVerifyRequest(BaseModel):
    """Token 验证请求 Schema。

    用于验证 Token 有效性。

    Attributes:
        token: 要验证的 Token 字符串
    """

    token: str = Field(..., description="要验证的 Token 字符串")


class TokenVerifyResponse(BaseModel):
    """Token 验证响应 Schema。

    Attributes:
        valid: Token 是否有效
        employee_id: 员工ID
        name: 员工姓名
        roles: 角色列表
        current_role: 当前角色
        login_source: 登录来源
        expires_in: 剩余有效期(秒)
    """

    valid: bool = Field(..., description="Token 是否有效")
    employee_id: Optional[str] = Field(None, description="员工ID")
    name: Optional[str] = Field(None, description="员工姓名")
    roles: List[str] = Field(default_factory=list, description="角色列表")
    current_role: Optional[str] = Field(None, description="当前角色")
    login_source: Optional[str] = Field(None, description="登录来源")
    expires_in: Optional[int] = Field(None, description="剩余有效期(秒)")


# --------------------------------------------------------------------------
# 当前用户信息响应 Schema
# --------------------------------------------------------------------------
class CurrentUserResponse(BaseModel):
    """当前用户信息响应 Schema。

    Attributes:
        employee_id: 员工ID
        name: 员工姓名
        avatar: 头像URL
        department: 部门
        roles: 角色列表
        current_role: 当前角色
        login_source: 登录来源
    """

    employee_id: str = Field(..., description="员工ID")
    name: str = Field(..., description="员工姓名")
    avatar: str = Field(default="", description="头像URL")
    department: str = Field(default="", description="部门")
    roles: List[str] = Field(default_factory=list, description="角色列表")
    current_role: str = Field(..., description="当前角色")
    login_source: str = Field(default="", description="登录来源")


# --------------------------------------------------------------------------
# 登录日志响应 Schema
# --------------------------------------------------------------------------
class LoginLogResponse(BaseModel):
    """登录日志响应 Schema。

    Attributes:
        id: 日志ID
        employee_id: 员工ID
        corp_id: 企业ID
        login_method: 登录方式
        login_source: 登录来源
        ip_address: 客户端IP
        user_agent: 客户端User-Agent
        status: 登录状态
        fail_reason: 失败原因
        created_at: 登录时间
    """

    id: str = Field(..., description="日志ID")
    employee_id: Optional[str] = Field(None, description="员工ID")
    corp_id: str = Field(..., description="企业ID")
    login_method: str = Field(..., description="登录方式")
    login_source: str = Field(..., description="登录来源")
    ip_address: Optional[str] = Field(None, description="客户端IP")
    user_agent: Optional[str] = Field(None, description="客户端User-Agent")
    status: str = Field(..., description="登录状态")
    fail_reason: Optional[str] = Field(None, description="失败原因")
    created_at: datetime = Field(..., description="登录时间")

    model_config = {"from_attributes": True}


# --------------------------------------------------------------------------
# 登录日志列表响应 Schema
# --------------------------------------------------------------------------
class LoginLogListResponse(BaseModel):
    """登录日志列表响应 Schema。

    Attributes:
        items: 日志列表
        total: 总数
    """

    items: List[LoginLogResponse] = Field(default_factory=list, description="日志列表")
    total: int = Field(..., description="总数")


# --------------------------------------------------------------------------
# 统一认证响应 Schema
# --------------------------------------------------------------------------
class UnifiedAuthResponse(BaseModel):
    """统一认证响应 Schema。

    Attributes:
        token: 访问令牌
        employee_id: 员工ID
        name: 员工姓名
        avatar: 头像URL
        department: 部门
        roles: 角色列表
        current_role: 当前角色
        login_source: 登录来源
        expires_in: 有效期(秒)
    """

    token: str = Field(..., description="访问令牌")
    employee_id: str = Field(..., description="员工ID")
    name: str = Field(..., description="员工姓名")
    avatar: str = Field(default="", description="头像URL")
    department: str = Field(default="", description="部门")
    roles: List[str] = Field(default_factory=list, description="角色列表")
    current_role: str = Field(..., description="当前角色")
    login_source: str = Field(..., description="登录来源")
    expires_in: int = Field(..., description="有效期(秒)")


# --------------------------------------------------------------------------
# 登出响应 Schema
# --------------------------------------------------------------------------
class LogoutResponse(BaseModel):
    """登出响应 Schema。

    Attributes:
        success: 是否成功
        message: 消息
    """

    success: bool = Field(..., description="是否成功")
    message: str = Field(..., description="消息")


# --------------------------------------------------------------------------
# 角色切换请求 Schema
# --------------------------------------------------------------------------
class SwitchRoleRequest(BaseModel):
    """角色切换请求 Schema。

    Attributes:
        role: 目标角色
    """

    role: str = Field(..., description="目标角色")


class SwitchRoleResponse(BaseModel):
    """角色切换响应 Schema。

    Attributes:
        success: 是否成功
        current_role: 当前角色
        message: 消息
    """

    success: bool = Field(..., description="是否成功")
    current_role: str = Field(..., description="当前角色")
    message: str = Field(..., description="消息")


# --------------------------------------------------------------------------
# 账号绑定请求 Schema
# --------------------------------------------------------------------------
class BindAccountRequest(BaseModel):
    """账号绑定请求 Schema。

    用于互联企业用户绑定已有账号。

    Attributes:
        employee_id: 员工UserID（企微 userid）
        corp_id: 企业ID（可选，默认使用系统配置的主企业ID）
        bind_type: 绑定方式（existing=绑定已有账号, new=申请新账号）
        employee_no: 员工工号（bind_type=existing 时必填）
        real_name: 真实姓名（bind_type=new 时必填）
        department: 部门
        phone: 手机号
    """

    employee_id: str = Field(..., description="员工UserID（企微 userid）")
    corp_id: Optional[str] = Field(None, description="企业ID（可选，默认使用系统配置）")
    bind_type: Optional[str] = Field("existing", description="绑定方式")
    employee_no: Optional[str] = Field(None, description="员工工号")
    real_name: Optional[str] = Field(None, description="真实姓名")
    department: Optional[str] = Field(None, description="部门")
    phone: Optional[str] = Field(None, description="手机号")