FunctionalScaffold/src/functional_scaffold/api/models.py

"""API 数据模型"""

from enum import Enum
from pydantic import BaseModel, Field, ConfigDict
from typing import Any, Dict, Optional


class InvokeRequest(BaseModel):
    """同步调用请求"""

    model_config = ConfigDict(json_schema_extra={"example": {"number": 17}})

    number: int = Field(..., description="待判断的整数")


class InvokeResponse(BaseModel):
    """同步调用响应"""

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "request_id": "550e8400-e29b-41d4-a716-446655440000",
                "status": "success",
                "result": {
                    "number": 17,
                    "is_prime": True,
                    "factors": [],
                    "algorithm": "trial_division",
                },
                "metadata": {
                    "algorithm": "PrimeChecker",
                    "version": "1.0.0",
                    "elapsed_time": 0.001,
                },
            }
        }
    )

    request_id: str = Field(..., description="请求唯一标识")
    status: str = Field(..., description="处理状态")
    result: Dict[str, Any] = Field(..., description="算法执行结果")
    metadata: Dict[str, Any] = Field(..., description="元数据信息")


class HealthResponse(BaseModel):
    """健康检查响应"""

    status: str = Field(..., description="健康状态")
    timestamp: float = Field(..., description="时间戳")


class ReadinessResponse(BaseModel):
    """就绪检查响应"""

    status: str = Field(..., description="就绪状态")
    timestamp: float = Field(..., description="时间戳")
    checks: Optional[Dict[str, bool]] = Field(None, description="各项检查结果")


class ErrorResponse(BaseModel):
    """错误响应"""

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "error": "VALIDATION_ERROR",
                "message": "number must be an integer",
                "details": {"field": "number", "value": "abc"},
                "request_id": "550e8400-e29b-41d4-a716-446655440000",
            }
        }
    )

    error: str = Field(..., description="错误代码")
    message: str = Field(..., description="错误消息")
    details: Optional[Dict[str, Any]] = Field(None, description="错误详情")
    request_id: Optional[str] = Field(None, description="请求ID")


class JobStatus(str, Enum):
    """任务状态枚举"""

    PENDING = "pending"  # 等待执行
    RUNNING = "running"  # 执行中
    COMPLETED = "completed"  # 已完成
    FAILED = "failed"  # 执行失败


class JobRequest(BaseModel):
    """异步任务请求"""

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "algorithm": "PrimeChecker",
                "params": {"number": 17},
                "webhook": "https://example.com/callback",
            }
        }
    )

    algorithm: str = Field(..., description="算法名称")
    params: Dict[str, Any] = Field(..., description="算法参数")
    webhook: Optional[str] = Field(None, description="回调 URL")


class JobCreateResponse(BaseModel):
    """任务创建响应"""

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "job_id": "a1b2c3d4e5f6",
                "status": "pending",
                "message": "任务已创建",
                "created_at": "2026-02-02T10:00:00Z",
            }
        }
    )

    job_id: str = Field(..., description="任务唯一标识")
    status: JobStatus = Field(..., description="任务状态")
    message: str = Field(..., description="状态消息")
    created_at: str = Field(..., description="创建时间（ISO 8601）")


class JobStatusResponse(BaseModel):
    """任务状态查询响应"""

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "job_id": "a1b2c3d4e5f6",
                "status": "completed",
                "algorithm": "PrimeChecker",
                "created_at": "2026-02-02T10:00:00Z",
                "started_at": "2026-02-02T10:00:01Z",
                "completed_at": "2026-02-02T10:00:02Z",
                "result": {"number": 17, "is_prime": True},
                "error": None,
                "metadata": {"elapsed_time": 0.001},
            }
        }
    )

    job_id: str = Field(..., description="任务唯一标识")
    status: JobStatus = Field(..., description="任务状态")
    algorithm: str = Field(..., description="算法名称")
    created_at: str = Field(..., description="创建时间（ISO 8601）")
    started_at: Optional[str] = Field(None, description="开始执行时间（ISO 8601）")
    completed_at: Optional[str] = Field(None, description="完成时间（ISO 8601）")
    result: Optional[Dict[str, Any]] = Field(None, description="执行结果（仅完成时返回）")
    error: Optional[str] = Field(None, description="错误信息（仅失败时返回）")
    metadata: Optional[Dict[str, Any]] = Field(None, description="元数据信息")


class ConcurrencyStatusResponse(BaseModel):
    """并发状态响应"""

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "max_concurrent": 10,
                "available_slots": 7,
                "running_jobs": 3,
            }
        }
    )

    max_concurrent: int = Field(..., description="最大并发任务数")
    available_slots: int = Field(..., description="当前可用槽位数")
    running_jobs: int = Field(..., description="当前运行中的任务数")