# +======================================================================
# | DjangoAdmin 企业数字化开发平台 [ 赋能开发者，助力企业发展 ]
# +----------------------------------------------------------------------
# | Copyright (c) 2021-2026 珊瑚云团队 版权所有
# +----------------------------------------------------------------------
# | 开源协议: Apache-2.0
# | 重要声明: 未经书面许可，不得移除或修改本框架相关版权标识。
# +----------------------------------------------------------------------
# | 官方网站: https://www.djangoadmin.cn
# +----------------------------------------------------------------------
# | 研发团队: 珊瑚云团队 荣誉出品
# +======================================================================
# | 版权和免责声明:
# | 一、知识产权声明
# | 本团队对该软件框架产品（以下简称“本产品”）拥有完整知识产权，包括但不限于商标权、专利权、
# | 著作权、商业秘密等。前述权利均受中华人民共和国及相关国际法律法规保护。未经本团队书面授权，
# | 任何个人或单位不得基于本产品本身申请任何形式的知识产权。
# | 二、使用限制与禁止条款
# | 您理解并同意，禁止将本产品用于以下任何行为：
# | 1. 任何违反中华人民共和国法律法规的用途；
# | 2. 任何侵害他人合法权益（包括但不限于人身权、财产权、知识产权等）的行为；
# | 3. 任何危害国家安全、公共利益及社会道德风尚的行为。
# | 三、责任豁免
# | 因使用本产品而产生的任何损失或法律纠纷（包括但不限于直接损失、间接损失、附带损失、衍生损失
# | 以及因违约、侵权等引发的责任），本团队均不承担任何法律责任。若因违规使用本产品导致任何第三
# | 方提起索赔或行政机关进行调查，您应独立承担全部责任。
# | 四、违约与法律责任
# | 如发现任何违反本声明的行为，本团队有权：
# | 1. 无条件配合公安机关及其他有权机关的调查取证工作；
# | 2. 依法追究相关方的民事责任，并要求赔偿全部损失；
# | 3. 保留进一步采取刑事控告等法律措施的权利。
# | 五、许可范围说明
# | 1、被授权方应视本产品源代码为核心机密信息，负有最高标准的保密与保管义务。禁止以任何形式（包
# | 括但不限于直接或间接的分享、复制、传播、分发、转售、出租、开源、反向工程、反编译、反汇编或通
# | 过网络服务提供给任何第三方）泄露、披露或处置源代码的全部或部分内容。任何未经授权的复制、使用、
# | 传播行为均构成对本团队知识产权的严重侵权，本团队有权依法追究其全部法律责任，并要求赔偿因此造
# | 成的一切经济损失及商誉损害。
# | 2、本产品仅限于公司或个人在法律允许范围内，用于内部且合规的软件产品研发。具体权利义务以《软件
# | 许可协议》附件为准。
# +======================================================================

"""
统一响应结果模块
=============================================================

该模块提供了系统统一的JSON响应格式，确保所有API接口返回格式一致。
包含成功响应和失败响应两种基础方法，支持扩展参数。

响应格式规范：
- code: 状态码，0表示成功，1表示失败（可扩展其他状态码）
- data: 响应数据，成功时返回具体数据，失败时为None
- msg: 提示信息，对操作结果的文字描述
- ok: 布尔值，标识操作是否成功（兼容旧版前端）
- 其他扩展参数：可通过kwargs动态添加

使用示例：
    # 成功响应
    return R.ok(data={"id": 1, "name": "张三"})
    return R.ok(msg="操作成功")

    # 失败响应
    return R.failed(msg="用户名或密码错误")
    return R.failed(msg="服务器内部错误", code=500)

    # 带扩展参数的响应
    return R.ok(data=user_info, total=100, pages=10)
"""

from typing import Any, Optional, Dict

from flask import jsonify

from application.constants.common import MESSAGE_OK, MESSAGE_FAIL


def ok(
        data: Optional[Any] = None,
        msg: str = MESSAGE_OK,
        code: int = 0,
        **kwargs: Any
) -> jsonify:
    """
    生成成功响应

    构建一个标准的成功响应JSON对象，包含状态码、数据、提示信息等字段。
    支持通过kwargs添加额外的响应字段，便于扩展。

    Args:
        data: 响应数据，可以是任意类型（dict, list, str, int等），默认为None
        msg: 成功提示信息，默认使用常量MESSAGE_OK
        code: 状态码，0表示成功，默认为0
        **kwargs: 额外的键值对参数，会合并到响应体中

    Returns:
        jsonify: 格式化的JSON响应对象

    Examples:
        >>> return R.ok()
        {"code": 0, "data": None, "msg": "操作成功", "ok": True}

        >>> return R.ok(data={"id": 1, "name": "张三"})
        {"code": 0, "data": {"id": 1, "name": "张三"}, "msg": "操作成功", "ok": True}

        >>> return R.ok(msg="创建成功", total=100)
        {"code": 0, "data": None, "msg": "创建成功", "ok": True, "total": 100}
    """
    # 构建基础响应体
    response_body: Dict[str, Any] = {
        "code": code,
        "data": data,
        "msg": msg,
        "ok": True
    }

    # 合并扩展参数
    if kwargs:
        response_body.update(kwargs)

    # 返回JSON响应
    return jsonify(response_body)


def failed(
        msg: str = MESSAGE_FAIL,
        code: int = 1,
        data: Optional[Any] = None,
        **kwargs: Any
) -> jsonify:
    """
    生成失败响应

    构建一个标准的失败响应JSON对象，包含状态码、错误信息等字段。
    支持通过kwargs添加额外的响应字段，便于扩展。

    Args:
        msg: 错误提示信息，默认使用常量MESSAGE_FAIL
        code: 状态码，1表示失败，默认为1（可根据业务需求定义其他错误码）
        data: 错误时的附加数据，通常为None，默认为None
        **kwargs: 额外的键值对参数，会合并到响应体中

    Returns:
        jsonify: 格式化的JSON响应对象

    Examples:
        >>> return R.failed()
        {"code": 1, "data": None, "msg": "操作失败", "ok": False}

        >>> return R.failed(msg="用户名或密码错误")
        {"code": 1, "data": None, "msg": "用户名或密码错误", "ok": False}

        >>> return R.failed(msg="未授权访问", code=401)
        {"code": 401, "data": None, "msg": "未授权访问", "ok": False}

        >>> return R.failed(msg="参数错误", errors={"name": "该字段不能为空"})
        {"code": 1, "data": None, "msg": "参数错误", "ok": False, "errors": {...}}
    """
    # 构建基础响应体
    response_body: Dict[str, Any] = {
        "code": code,
        "data": data,
        "msg": msg,
        "ok": False
    }

    # 合并扩展参数
    if kwargs:
        response_body.update(kwargs)

    # 返回JSON响应
    return jsonify(response_body)


def response(
        data: Optional[Any] = None,
        msg: str = MESSAGE_OK,
        code: int = 0,
        success: bool = True,
        **kwargs: Any
) -> jsonify:
    """
    通用响应生成器（高级用法）

    提供更灵活的响应生成方式，允许自定义所有字段。
    通常推荐使用ok()和failed()两个专用方法，但在需要完全控制响应格式时可以使用此方法。

    Args:
        data: 响应数据
        msg: 提示信息
        code: 状态码
        success: 操作是否成功标识
        **kwargs: 额外的键值对参数

    Returns:
        jsonify: 格式化的JSON响应对象

    Examples:
        >>> return R.response(data=[], msg="查询成功", code=200, success=True)
        {"code": 200, "data": [], "msg": "查询成功", "ok": True}
    """
    response_body: Dict[str, Any] = {
        "code": code,
        "data": data,
        "msg": msg,
        "ok": success
    }

    if kwargs:
        response_body.update(kwargs)

    return jsonify(response_body)


# 为方便使用，定义常用错误码常量（可选）
class Codes:
    """常用状态码定义"""
    SUCCESS = 0
    FAILED = 1
    UNAUTHORIZED = 401  # 未认证
    FORBIDDEN = 403  # 无权限
    NOT_FOUND = 404  # 资源不存在
    VALIDATE_ERROR = 422  # 验证错误
    SERVER_ERROR = 500  # 服务器错误