"""Datenmodelle für die Dokumentations-Generierung.

Definiert die Strukturen für Platzhalter-Einträge, Unterkategorien und
Hauptkategorien, die der DocGenerator verwendet, um die Vorlagendokumentation
zu erzeugen.
"""

from dataclasses import dataclass, field


@dataclass
class PlaceholderEntry:
    """Ein Platzhalter-Eintrag in der Dokumentation."""

    name: str
    """Platzhalter-Name, z.B. 'META_ReportName'."""

    prefix: str
    """Zugehöriger Präfix, z.B. 'META_'."""

    category: str
    """Hauptkategorie: 'beschreibende_metadaten' | 'backenddaten' | 'frontenddaten'."""

    subcategory: str
    """Unterkategorie, z.B. 'bericht_metadaten'."""

    fill_mode: str
    """Befüllungsmodus: 'automatisch' | 'manuell'."""

    metadata_path: str | None
    """Pfad aus MAPPING_RULES, z.B. 'report_name'. None wenn manuell."""

    availability: dict[str, bool]
    """Verfügbarkeit pro Verbindungstyp, z.B. {'fabric': True, 'local': True, 'pbip': True}."""

    description: str
    """Kurzbeschreibung des Platzhalters (max 120 Zeichen)."""


@dataclass
class SubcategorySection:
    """Eine Unterkategorie mit ihren Platzhaltern."""

    name: str
    """Interner Name der Unterkategorie, z.B. 'bericht_metadaten'."""

    display_name: str
    """Angezeigter Name (sprachabhängig), z.B. 'Bericht-Metadaten'."""

    prefixes: list[str]
    """Zugehörige Präfixe, z.B. ['META_']."""

    placeholders: list[PlaceholderEntry] = field(default_factory=list)
    """Liste aller Platzhalter in dieser Unterkategorie."""

    generated_sections: list[str] = field(default_factory=list)
    """Automatisch generierte Abschnitte, z.B. ['DS_Architektur', 'DS_Lineage']."""


@dataclass
class CategorySection:
    """Eine Hauptkategorie."""

    name: str
    """Interner Name, z.B. 'beschreibende_metadaten'."""

    display_name: str
    """Angezeigter Name (sprachabhängig), z.B. 'Beschreibende Metadaten'."""

    description: str
    """Beschreibung der Kategorie (1-3 Sätze)."""

    subcategories: list[SubcategorySection] = field(default_factory=list)
    """Liste der Unterkategorien."""
