"""业务异常定义：解耦服务层与 Web 框架。"""

from typing import Any, Optional


class AppError(Exception):
    """业务异常基类，由全局异常处理器捕获并转为 HTTP 响应。"""

    status_code: int = 500
    detail: str = "服务器内部错误"
    extra: Optional[Any] = None

    def __init__(self, detail: Optional[str] = None, extra: Optional[Any] = None):
        if detail is not None:
            self.detail = detail
        if extra is not None:
            self.extra = extra
        super().__init__(self.detail)


class NotFoundError(AppError):
    status_code = 404
    detail = "资源不存在"


class ValidationError(AppError):
    status_code = 400
    detail = "请求参数错误"


class ConflictError(AppError):
    status_code = 409
    detail = "资源冲突"


class ForbiddenError(AppError):
    status_code = 403
    detail = "无权限访问"


class BillingBlockedError(AppError):
    status_code = 402
    detail = "额度不足，请升级套餐"