"""
公共响应模型模块

提供全系统统一的 API 响应数据模型和便捷函数，包括：
- 成功/失败消息体
- 空数据体
- 标准化成功响应构造函数
"""

from typing import Any

from pydantic import BaseModel, Field

from backend.app.core.error_codes import ErrorCode


class MessageData(BaseModel):
    """通用消息响应数据模型，用于返回操作结果提示信息。"""

    success: bool = True
    """操作是否成功"""

    detail: str | None = None
    """详细说明信息，如错误原因或提示内容"""


class EmptyData(BaseModel):
    """空数据占位模型，用于无需返回业务数据的接口响应。"""
    pass


def success_payload(data: Any, message: str = "success") -> dict[str, Any]:
    """构造标准成功响应字典。

    Args:
        data: 响应业务数据
        message: 响应提示信息，默认为 "success"

    Returns:
        包含 code、message、data 三个字段的标准响应字典
    """
    return {
        "code": ErrorCode.SUCCESS,
        "message": message,
        "data": data,
    }