"""
TF Tree 专用异常：便于 D03 独立使用及上层（如 studio）统一捕获并转成 HTTP/JSON。
"""
from typing import Any, Optional


class TFTreeError(Exception):
    """树相关异常基类，携带 message 与可选 detail。"""

    def __init__(self, message: str, detail: Optional[dict] = None):
        self.message = message
        self.detail = detail or {}
        super().__init__(message)

    def to_dict(self) -> dict:
        """便于转成 JSON 响应。"""
        out = {"message": self.message}
        if self.detail:
            out["detail"] = self.detail
        return out


class TFTreeNotFoundError(TFTreeError):
    """资源不存在：如外参目录、文件缺失。"""
    pass


class TFTreeValidationError(TFTreeError):
    """校验失败：如根节点不存在、顺序不包含全部变换、参数非法。"""
    pass


class TFTreeKeyError(TFTreeError):
    """变换 key 不存在（如 update/invert 时指定的 source->target）。"""
    pass
