Plugin_SN_Basis/modules/pruef_ergebnis.py

"""
sn_basis/modules/pruef_ergebnis.py

Erweitertes Ergebnisobjekt für Dateiprüfungen mit Verfahrens-DB-spezifischen Aktionen.
"""

from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Optional, Literal
from pathlib import Path


# =============================================================================
# Erweiterte PruefAktionen für Verfahrens-DB-Workflow
# =============================================================================

PruefAktion = Literal[
    # Basis-Aktionen (bestehend)
    "ok",
    "leer",
    "leereingabe_erlaubt",
    "leereingabe_nicht_erlaubt",
    "standarddatei_vorschlagen",
    "temporaer_erlaubt",
    "temporaer_erzeugen",
    "datei_nicht_gefunden",
    "kein_dateipfad",
    "pfad_nicht_gefunden",
    "url_nicht_erreichbar",
    "netzwerkfehler",
    
    # Layer-spezifisch
    "layer_nicht_gefunden",
    "layer_unsichtbar",
    "falscher_geotyp",
    "layer_leer",
    "falscher_layertyp",
    "falsches_crs",
    "felder_fehlen",
    "datenquelle_unerwartet",
    "layer_nicht_editierbar",
    
    # Dateiendung/Format
    "falsche_endung",
    "pflichtfelder_fehlen",
    
    # Excel/Import
    "kein_header",
    "kein_arbeitsblatt",
    "read_error",
    "open_error",
    "datenabruf",
    
    # 🆕 VERFAHRENS-DB SPEZIFISCH (deine Anforderungen 2.d, 2.e)
    "datei_wird_erzeugt",           # 2.d: Pfad gültig, Datei fehlt → weiter
    "datei_existiert",              # Datei vorhanden → Layer-Entscheidung
    "datei_existiert_ueberschreiben", # 2.e: Nutzer wählt "Überschreiben"
    "datei_existiert_anhaengen",    # 2.e: Nutzer wählt "Anhängen"  
    "datei_existiert_ueberspringen", # 2.e: Nutzer wählt "Überspringen"
    
    # Generisch
    "pruefe_exception",
    "save_exception",
    "save_not_implemented",
    "stil_not_implemented",
    "datei_unbekannt",
    "needs_user_action",
]


@dataclass
class pruef_ergebnis:
    """
    Einheitliches Ergebnisobjekt für Prüfer im Verfahrens-DB-Workflow.

    Attributes
    ----------
    ok : bool
        True wenn Prüfung bestanden und Pipeline fortgesetzt werden kann.
        False signalisiert Fehler oder Nutzerentscheidung erforderlich.
    meldung : Optional[str], optional
        Menschenlesbare Meldung für UI-Dialoge (BY: Pruefmanager).
    aktion : Optional[PruefAktion], optional
        Maschinenlesbarer Aktionscode für nachfolgende Pipeline-Schritte.
    kontext : Optional[Any], optional
        Zusatzkontext: meist `pathlib.Path` für Dateipfade oder Layer-Objekte.

    Verfahrens-DB-spezifische Aktionen:
    
    +-----------------------------+-------------------------------------------------+
    | Aktion                      | Bedeutung                                        |
    +=============================+=================================================+
    | ``datei_wird_erzeugt``      | 2.d: Neues GPKG wird angelegt (Pfad gültig)      |
    +-----------------------------+-------------------------------------------------+
    | ``datei_existiert``         | Datei vorhanden → Layer-Überschreibung prüfen    |
    +-----------------------------+-------------------------------------------------+
    | ``datei_existiert_*``       | 2.e: Nutzerentscheidung für bestehende Datei     |
    +-----------------------------+-------------------------------------------------+
    """

    ok: bool
    meldung: Optional[str] = None
    aktion: Optional[PruefAktion] = None
    kontext: Optional[Any] = None

    def __init__(
        self,
        ok: bool,
        meldung: Optional[str] = None,
        aktion: Optional[PruefAktion] = None,
        kontext: Optional[Any] = None,
    ) -> None:
        """
        Erstellt ein neues Prüfergebnis.

        Parameters
        ----------
        ok : bool
            True für "weiter mit Pipeline", False für "Entscheidung/Fehler".
        meldung : Optional[str]
            UI-Text für Nutzerdialoge.
        aktion : Optional[PruefAktion]
            Maschinenaktion für nachfolgende Verarbeitung.
        kontext : Optional[Any]
            Typischerweise `pathlib.Path` (Dateipfad) oder `QgsVectorLayer`.
        """
        self.ok = ok
        self.meldung = meldung
        self.aktion = aktion
        self.kontext = kontext

    @property
    def ist_verfahrens_db_aktion(self) -> bool:
        """
        Prüft, ob es sich um eine Verfahrens-DB-spezifische Aktion handelt.

        Returns
        -------
        bool
            True für ``datei_wird_erzeugt`` oder ``datei_existiert*``.
        """
        return self.aktion in {
            "datei_wird_erzeugt",
            "datei_existiert",
            "datei_existiert_ueberschreiben",
            "datei_existiert_anhaengen",
            "datei_existiert_ueberspringen",
        }

    @property
    def dateipfad(self) -> Optional[Path]:
        """
        Extrahiert den Dateipfad aus dem Kontext (falls vorhanden).

        Returns
        -------
        Optional[Path]
            `Path`-Objekt oder None.
        """
        if isinstance(self.kontext, Path):
            return self.kontext
        return None

    @property
    def erlaubte_persistierung(self) -> bool:
        """
        Prüft, ob die Pipeline Daten persistieren darf.

        Returns
        -------
        bool
            True für ``datei_wird_erzeugt``, ``datei_existiert_ueberschreiben``,
            ``datei_existiert_anhaengen``.
        """
        return self.aktion in {
            "datei_wird_erzeugt",
            "datei_existiert_ueberschreiben",
            "datei_existiert_anhaengen",
        }