# API 统一响应工具
# 为新建的 API 接口提供标准化的返回格式
# 注意：旧接口暂不强制迁移，新接口统一使用本模块

from flask import jsonify


class ApiResponse:
    """统一的 API 响应格式工具类

    使用示例：
        # 成功响应（返回数据）
        return ApiResponse.success({'recording': recording.to_dict()})

        # 成功响应（带提示消息）
        return ApiResponse.success(message='操作成功')

        # 成功响应（数据 + 消息）
        return ApiResponse.success({'data': result}, '保存成功')

        # 成功响应（自定义状态码）
        return ApiResponse.success({'user': user_data}, status_code=201)

        # 错误响应
        return ApiResponse.error('录音未找到', 404)

        # 错误响应（带详情）
        return ApiResponse.error('参数校验失败', 400, detail='email 格式不正确')

        # 分页响应
        return ApiResponse.paginated(items, pagination_meta)
    """

    @staticmethod
    def success(data=None, message=None, status_code=200):
        """成功响应

        Args:
            data: 业务数据（字典类型），会合并到响应体中
            message: 可选的成功提示消息
            status_code: HTTP 状态码，默认 200

        Returns:
            (Response, status_code) 元组
        """
        response = {}
        if message:
            response['message'] = message
        if data is not None:
            if not isinstance(data, dict):
                raise TypeError('data 必须是字典类型，请使用 paginated() 返回列表数据')
            response.update(data)
        response['success'] = True
        return jsonify(response), status_code

    @staticmethod
    def error(message, status_code=400, detail=None):
        """错误响应

        Args:
            message: 用户友好的错误提示消息
            status_code: HTTP 状态码，默认 400
            detail: 可选的详细错误信息（仅开发环境建议返回）

        Returns:
            (Response, status_code) 元组
        """
        response = {'error': message}
        if detail:
            response['detail'] = detail
        return jsonify(response), status_code

    @staticmethod
    def paginated(items, pagination, status_code=200):
        """分页响应

        Args:
            items: 数据列表
            pagination: 分页元数据字典，包含 page, per_page, total, total_pages, has_next, has_prev
            status_code: HTTP 状态码，默认 200

        Returns:
            (Response, status_code) 元组
        """
        return jsonify({
            'items': items,
            'pagination': pagination,
            'success': True
        }), status_code
