"""项目级异常定义

异常层次:
    ReimbursementError          — 所有业务异常的基类
    ├── ExtractionError         — 文档提取失败（单个文件/批量全失败）
    ├── BrowserError            — 浏览器自动化失败
    └── ValidationError         — 校验失败（规则校验/语义校验）

使用规则:
    - 模块内部: 捕获具体异常 → 记录日志 → 截图(如适用) → re-raise
    - 模块边界: 不吞异常，向上传播
    - 顶层 (routes.py / orchestrator.py): 统一捕获 ReimbursementError
    - 可恢复场景: 返回结构化结果而非 raise
"""

from __future__ import annotations

from typing import Any


class ReimbursementError(Exception):
    """业务异常基类"""

    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
        super().__init__(message)
        self.details = details or {}


class ExtractionError(ReimbursementError):
    """文档提取失败"""

    def __init__(
        self,
        message: str,
        failed_files: list[str] | None = None,
        details: dict[str, Any] | None = None,
    ) -> None:
        super().__init__(message, details)
        self.failed_files = failed_files or []


class BrowserError(ReimbursementError):
    """浏览器自动化操作失败"""

    pass


class ValidationError(ReimbursementError):
    """校验失败"""

    def __init__(
        self,
        message: str,
        missing_fields: list[str] | None = None,
        details: dict[str, Any] | None = None,
    ) -> None:
        super().__init__(message, details)
        self.missing_fields = missing_fields or []