"""
统一响应格式

提供标准化的 JSON 响应格式
"""
from flask import jsonify
from typing import Any, Dict, Optional


def success_response(data: Any = None, message: str = "操作成功", **kwargs) -> tuple:
    """
    成功响应
    
    Args:
        data: 响应数据
        message: 成功消息
        **kwargs: 其他额外字段
        
    Returns:
        tuple: (response, status_code)
    """
    response = {
        'success': True,
        'status': 'success',
        'message': message
    }
    
    if data is not None:
        response['data'] = data
    
    # 添加额外字段
    response.update(kwargs)
    
    return jsonify(response), 200


def error_response(message: str = "操作失败", code: int = 400, **kwargs) -> tuple:
    """
    错误响应
    
    Args:
        message: 错误消息
        code: HTTP 状态码
        **kwargs: 其他额外字段
        
    Returns:
        tuple: (response, status_code)
    """
    response = {
        'success': False,
        'status': 'error',
        'message': message,
        'code': code
    }
    
    # 添加额外字段
    response.update(kwargs)
    
    return jsonify(response), code


def paginated_response(
    items: list,
    page: int,
    per_page: int,
    total: int,
    message: str = "获取成功"
) -> tuple:
    """
    分页响应
    
    Args:
        items: 数据列表
        page: 当前页码
        per_page: 每页数量
        total: 总数量
        message: 消息
        
    Returns:
        tuple: (response, status_code)
    """
    total_pages = (total + per_page - 1) // per_page if per_page > 0 else 0
    
    response = {
        'success': True,
        'status': 'success',
        'message': message,
        'data': items,
        'pagination': {
            'page': page,
            'per_page': per_page,
            'total': total,
            'total_pages': total_pages,
            'has_prev': page > 1,
            'has_next': page < total_pages
        }
    }
    
    return jsonify(response), 200


def validation_error_response(errors: Dict[str, list]) -> tuple:
    """
    验证错误响应
    
    Args:
        errors: 字段错误字典 {'field': ['error1', 'error2']}
        
    Returns:
        tuple: (response, status_code)
    """
    return error_response(
        message="数据验证失败",
        code=422,
        errors=errors
    )