"""因子元数据模块异常定义。

提供清晰的异常类型帮助定位元数据操作中的问题。
"""


class FactorMetadataError(Exception):
    """因子元数据操作基础异常。"""

    pass


class ValidationError(FactorMetadataError):
    """字段校验失败异常。

    当因子字典缺少核心字段或字段类型不匹配时抛出。

    Attributes:
        field: 校验失败的字段名
        message: 详细错误信息
    """

    def __init__(self, field: str, message: str) -> None:
        self.field = field
        self.message = message
        super().__init__(f"字段 '{field}' 校验失败: {message}")


class DuplicateFactorError(FactorMetadataError):
    """因子重复异常。

    当尝试添加已存在的factor_id时抛出。

    Attributes:
        factor_id: 重复的因子ID
    """

    def __init__(self, factor_id: str) -> None:
        self.factor_id = factor_id
        super().__init__(f"因子 '{factor_id}' 已存在")


class FactorNotFoundError(FactorMetadataError):
    """因子未找到异常。

    当查询不存在的factor_id时抛出。

    Attributes:
        factor_id: 未找到的因子ID
    """

    def __init__(self, factor_id: str) -> None:
        self.factor_id = factor_id
        super().__init__(f"因子 '{factor_id}' 不存在")


class QueryError(FactorMetadataError):
    """DuckDB查询异常。

    当SQL查询执行失败时抛出。

    Attributes:
        sql: 失败的SQL语句
        original_error: 原始异常
    """

    def __init__(self, sql: str, original_error: Exception) -> None:
        self.sql = sql
        self.original_error = original_error
        super().__init__(f"查询执行失败: {original_error}\nSQL: {sql}")


class FileOperationError(FactorMetadataError):
    """文件操作异常。

    当文件读写操作失败时抛出。

    Attributes:
        filepath: 操作的文件路径
        operation: 操作类型（read/write）
        original_error: 原始异常
    """

    def __init__(
        self, filepath: str, operation: str, original_error: Exception
    ) -> None:
        self.filepath = filepath
        self.operation = operation
        self.original_error = original_error
        super().__init__(f"文件{operation}失败 '{filepath}': {original_error}")
