dingdanquanliucheng/backend/app/core/responses.py

"""统一 API 响应格式构造工具。

所有 API 返回值通过 success_payload / success_response 包装，
保证前端收到的 JSON 结构始终为 { code, message, data }。
"""

from typing import Any

from backend.app.core.error_codes import ErrorCode


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

    被路由层直接使用，返回给 FastAPI 框架序列化。

    Args:
        data: 响应数据，可以是字典、列表等任意可序列化对象。
        message: 响应提示信息，默认 "success"。

    Returns:
        dict: 包含 code、message、data 三个字段的响应字典。
    """
    # 成功响应统一走这里，便于后续扩展 trace_id 等字段。
    return {
        "code": ErrorCode.SUCCESS,
        "message": message,
        "data": {} if data is None else data,
    }