"""
统一 API 响应格式

遵循 AGENTS.md 规范：
成功：{ "code": 0, "message": "success", "data": {} }
失败：{ "code": 非0错误码, "message": "错误描述", "data": null }
"""

from typing import Any, Generic, TypeVar

from pydantic import BaseModel, Field

T = TypeVar("T")


class ApiResponse(BaseModel, Generic[T]):
    """统一 API 响应模型"""

    code: int = Field(description="状态码，0 表示成功")
    message: str = Field(description="描述信息")
    data: T | None = Field(default=None, description="响应数据，失败时为 null")


def success_response(data: Any = None, message: str = "success") -> dict:
    """
    构建成功响应

    Args:
        data: 响应数据，可为任意 JSON 可序列化类型
        message: 成功描述

    Returns:
        符合规范的响应字典
    """
    return {
        "code": 0,
        "message": message,
        "data": data,
    }


def error_response(code: int, message: str) -> dict:
    """
    构建失败响应

    Args:
        code: 非零错误码
        message: 错误描述

    Returns:
        符合规范的响应字典
    """
    return {
        "code": code,
        "message": message,
        "data": None,
    }


# 常用错误码
class ErrorCode:
    """错误码常量"""

    UNAUTHORIZED = 401
    FORBIDDEN = 403
    NOT_FOUND = 404
    VALIDATION_ERROR = 422
    INTERNAL_ERROR = 500