PayrollManagementSystem/backend/app/core/exceptions.py

"""业务异常定义。

`code` 直接作为 HTTP 状态码返回，使前端拦截器既能读 HTTP 状态也能读响应体的 code。

重要约定：**401 只表示"受保护接口的鉴权失败"**，登录接口自身的失败一律用 400/403。
否则前端"401 即跳登录页"的拦截器会在用户输错密码时触发跳转，导致登录页反复重挂载。
"""

from app.core.constants import (
    CODE_BAD_REQUEST,
    CODE_FORBIDDEN,
    CODE_NOT_FOUND,
    CODE_SERVER_ERROR,
    CODE_UNAUTHORIZED,
)


class AppException(Exception):
    """业务异常基类。业务逻辑中主动抛出，由全局处理器转换为统一响应。"""

    code: int = CODE_SERVER_ERROR
    message: str = "服务端异常"

    def __init__(self, message: str | None = None) -> None:
        self.message = message or self.message
        super().__init__(self.message)


class BadRequestError(AppException):
    """参数错误或业务规则校验不通过。"""

    code = CODE_BAD_REQUEST
    message = "参数错误"


class AuthError(AppException):
    """未认证：令牌缺失、无效、过期或已登出。"""

    code = CODE_UNAUTHORIZED
    message = "登录状态已失效，请重新登录"


class ForbiddenError(AppException):
    """已认证但无权限，或账号被禁用/锁定。"""

    code = CODE_FORBIDDEN
    message = "无权限"


class NotFoundError(AppException):
    """请求的资源不存在。"""

    code = CODE_NOT_FOUND
    message = "资源不存在"


class ConflictError(AppException):
    """授权版本已变化，客户端应刷新后重新核对。"""

    code = 409
    message = "配置已被其他人修改，请刷新后重新核对"