@source: 260313 heath-infer-step01

"""
@source: 260313 heath-infer-step01
@extracted: 2026-03-14
@description: 데이터 파이프라인용 계층형 예외 체계.
              기본 PipelineError + 5개 구체 예외 (로드/검증/변환/외부서비스/충돌해결).

사용법:
    from preprocessing_exceptions import DataLoadError, DataValidationError

    try:
        load_data("path/to/file.json")
    except DataLoadError as e:
        print(f"Stage: {e.stage}, Details: {e.details}")

    # Stage + details 포함 예외
    raise DataValidationError(
        message="필수 필드 누락",
        stage="Stage 2",
        details={"missing_fields": ["name", "id"]}
    )
"""
from typing import Any


class PipelineError(Exception):
    """파이프라인 기본 예외"""

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

    def __str__(self) -> str:
        base = self.message
        if self.stage:
            base = f"[{self.stage}] {base}"
        if self.details:
            details_str = ", ".join(f"{k}={v}" for k, v in self.details.items())
            base = f"{base} ({details_str})"
        return base


class DataLoadError(PipelineError):
    """데이터 로드 실패

    - 파일 없음
    - 인코딩 오류
    - 파일 읽기 권한 없음
    """
    pass


class DataValidationError(PipelineError):
    """데이터 검증 실패

    - 필수 필드 누락
    - 데이터 형식 불일치
    - 참조 무결성 오류
    """
    pass


class DataTransformError(PipelineError):
    """데이터 변환 실패

    - ID 정규화 실패
    - 빈도 파싱 오류
    - 날짜 형식 오류
    """
    pass


class ExternalServiceError(PipelineError):
    """외부 서비스 연동 실패

    - API 연결 실패
    - 다운로드 실패
    - 타임아웃
    """
    pass


class ConflictResolutionError(PipelineError):
    """충돌 해결 실패

    - 자동 해결 불가능한 충돌
    - 데이터 불일치
    """
    pass