"""
DRF 标准 JSON 响应封装（Rules/python.mdc: 类型注解与 docstrings）。

提供 SuccessResponse（分页）、DetailResponse（单条）、ErrorResponse（错误）。
"""

from __future__ import annotations

from typing import Any

from rest_framework.response import Response


class SuccessResponse(Response):
    """
    标准成功响应，带分页结构。

    用法: SuccessResponse(data=...) 或 SuccessResponse(data, page=1, limit=10, total=100)。
    默认 code=2000，不对外支持其他返回码。
    """

    def __init__(
        self,
        data: Any = None,
        msg: str = "success",
        status: int | None = None,
        template_name: str | None = None,
        headers: dict[str, str] | None = None,
        exception: bool = False,
        content_type: str | None = None,
        page: int = 1,
        limit: int = 1,
        total: int = 1,
    ) -> None:
        std_data: dict[str, Any] = {
            "code": 2000,
            "data": {"page": page, "limit": limit, "total": total, "data": data},
            "msg": msg,
        }
        super().__init__(std_data, status, template_name, headers, exception, content_type)


class DetailResponse(Response):
    """
    不包含分页的成功响应，用于单条数据查询。

    用法: DetailResponse(data=...)。
    默认 code=2000。
    """

    def __init__(
        self,
        data: Any = None,
        msg: str = "success",
        status: int | None = None,
        template_name: str | None = None,
        headers: dict[str, str] | None = None,
        exception: bool = False,
        content_type: str | None = None,
    ) -> None:
        std_data: dict[str, Any] = {"code": 2000, "data": data, "msg": msg}
        super().__init__(std_data, status, template_name, headers, exception, content_type)


class ErrorResponse(Response):
    """
    标准错误响应。

    用法: ErrorResponse(msg="xxx") 或 ErrorResponse(code=404, msg="未找到")。
    默认 code=400。
    """

    def __init__(
        self,
        data: Any = None,
        msg: str = "error",
        code: int = 400,
        status: int | None = None,
        template_name: str | None = None,
        headers: dict[str, str] | None = None,
        exception: bool = False,
        content_type: str | None = None,
    ) -> None:
        std_data: dict[str, Any] = {"code": code, "data": data, "msg": msg}
        super().__init__(std_data, status, template_name, headers, exception, content_type)
