"""业务异常与鉴权错误码（对齐 JWT-RBAC 手册）。

NotFoundError 继承 LookupError：服务层既有 `raise LookupError`（customer/product
not found）自动获得精确类型与 404 语义，调用方 except LookupError 无需改动
（B5 评审 P3-1 的收敛锚点）。
"""

from __future__ import annotations


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


class PermissionDenied(PermissionError):
    """归属/权限拒绝（HTTP 403）；code 对齐 JWT 手册 §6.1 错误码。"""

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


class StateConflict(ValueError):
    """状态机冲突（HTTP 409；如处置非 pending_review 的预警单）。"""


class ApiError(Exception):
    """业务 HTTP 错误（统一错误体出口 · 手册 §10，B7 挂账④）。

    error_code 取手册 §10 AUTH 系列（AUTH_401_*）或通用码
    （NOT_FOUND / STATE_CONFLICT / BAD_REQUEST）；register_error_handlers
    转为 {error_code, message, trace_id, request_id} 响应。
    """

    def __init__(self, status_code: int, error_code: str, message: str) -> None:
        super().__init__(message)
        self.status_code = status_code
        self.error_code = error_code
        self.message = message