"""业务异常体系 — 统一错误类型，供路由层和 service 层使用。

路由层通过 main.py 的 @app.exception_handler(AppError) 统一捕获，
转为对应 HTTP 状态码 + JSON 响应。
"""

from __future__ import annotations


class AppError(Exception):
    """所有业务异常的基类。"""

    def __init__(self, message: str = "", *, detail: str = ""):
        self.message = message or detail or self.__class__.__name__
        super().__init__(self.message)


class NotFoundError(AppError):
    """资源不存在（404）。"""


class ValidationError(AppError):
    """请求参数校验失败（400）。"""


class ExternalAPIError(AppError):
    """外部 API 调用失败（502）。"""


class PdfProcessError(AppError):
    """PDF 处理错误（500）。"""


class ConflictError(AppError):
    """资源冲突（409）— 如锁冲突、并发任务冲突。"""