"""
通用响应模型

定义 API 通用的响应结构
"""

from typing import Any, Generic, List, Optional, TypeVar
from pydantic import BaseModel, Field

# 泛型类型变量，用于分页响应
T = TypeVar("T")


class SuccessResponse(BaseModel):
    """
    通用成功响应
    
    Example:
        >>> response = SuccessResponse(message="操作成功")
        >>> response.model_dump()
        {'success': True, 'message': '操作成功'}
    """
    success: bool = Field(default=True, description="是否成功")
    message: str = Field(default="操作成功", description="响应消息")
    
    model_config = {
        "json_schema_extra": {
            "examples": [
                {"success": True, "message": "操作成功"}
            ]
        }
    }


class ErrorResponse(BaseModel):
    """
    错误响应
    
    Example:
        >>> response = ErrorResponse(message="任务不存在", code="TASK_NOT_FOUND")
        >>> response.model_dump()
        {'success': False, 'message': '任务不存在', 'code': 'TASK_NOT_FOUND', 'details': None}
    """
    success: bool = Field(default=False, description="是否成功")
    message: str = Field(..., description="错误消息")
    code: Optional[str] = Field(default=None, description="错误代码")
    details: Optional[Any] = Field(default=None, description="错误详情")
    
    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "success": False,
                    "message": "任务不存在",
                    "code": "TASK_NOT_FOUND",
                    "details": None
                }
            ]
        }
    }


class PaginatedResponse(BaseModel, Generic[T]):
    """
    分页响应基类
    
    泛型参数 T 表示列表项的类型
    
    Example:
        >>> from typing import List
        >>> class TaskListResponse(PaginatedResponse[TaskResponse]):
        ...     pass
    """
    items: List[T] = Field(default_factory=list, description="数据列表")
    total: int = Field(default=0, ge=0, description="总数量")
    limit: int = Field(default=50, ge=1, le=100, description="每页数量")
    offset: int = Field(default=0, ge=0, description="偏移量")
    
    @property
    def has_more(self) -> bool:
        """是否有更多数据"""
        return self.offset + len(self.items) < self.total
    
    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "items": [],
                    "total": 0,
                    "limit": 50,
                    "offset": 0
                }
            ]
        }
    }