"""Generator für die Fabric Lakehouse-Dokumentation.

Analog zu :mod:`core.copyjob_doc_generator` und :mod:`core.notebook_doc_generator`:
enthält die eingebaute Standard-Vorlage für ein eigenständiges Lakehouse-Dokument
sowie die Funktionen, die aus einem :class:`~core.models.LakehouseInfo` das
Platzhalter-Wörterbuch und die Markdown-Tabellen/-Abschnitte erzeugen.

Lakehouses besitzen keine ``getDefinition``; die Dokumentation basiert auf den
Item-Properties (SQL-Analytics-Endpoint, OneLake-Pfade) und der Tabellenliste.
"""
from __future__ import annotations

from core.models import LakehouseInfo, LakehouseTableInfo
from core.template_renderer import TemplateRenderer
from core.workspace_doc_generator import _escape_cell, ensure_template, load_template

# Dateiname der Standard-Vorlage (liegt neben der EXE / im Projektstamm)
LAKEHOUSE_TEMPLATE_FILENAME = "WorkspaceLakehousevorlage.md"

__all__ = [
    "LAKEHOUSE_TEMPLATE_FILENAME",
    "DEFAULT_LAKEHOUSE_TEMPLATE",
    "ensure_template",
    "load_template",
    "build_tables_table",
    "build_tables_detail",
    "build_endpoint_section",
    "build_service_hint",
    "build_lakehouse_values",
    "render_lakehouse",
]


# ---------------------------------------------------------------------------
# Eingebaute Standard-Vorlage (deckungsgleich mit
# PowerBI_Fabric_Lakehouse_Dokumentationsvorlage.md im Projektstamm)
# ---------------------------------------------------------------------------

DEFAULT_LAKEHOUSE_TEMPLATE = """# Microsoft Fabric Lakehouse-Dokumentation

> **Hinweis:** Diese Dokumentation ist verpflichtend für alle Produktiv-Lakehouses.
> Nicht relevante Kapitel können leer bleiben, dürfen jedoch nicht entfernt werden.
> Automatisch befüllte Felder stammen aus dem Microsoft Fabric Service; mit
> _„Manuell zu ergänzen"_ markierte Felder sind fachlich zu vervollständigen.

---

## 1. Metadaten

| Feld | Wert |
|-----|------|
| Lakehouse-Name | {{LH_Name}} |
| Beschreibung | {{LH_Beschreibung}} |
| Lakehouse-ID | {{LH_ID}} |
| Web-URL | {{LH_WebUrl}} |
| Standardschema | {{LH_DefaultSchema}} |
| SQL-Endpoint (Verbindung) | {{LH_SqlConnection}} |
| SQL-Endpoint-ID | {{LH_SqlEndpointId}} |
| SQL-Endpoint-Status | {{LH_SqlStatus}} |
| Erstellt / konfiguriert von | {{LH_ConfiguredBy}} |
| Zuletzt geändert | {{LH_ModifiedTime}} |
| Fachbereich | {{LH_Fachbereich}} |
| Konzerndomäne | {{LH_Konzerndomaene}} |
| Aktuelle Version | 1.0 |
| Status | Produktiv |
| Letzte Aktualisierung | {{LH_ExportDatum}} |

---

## 2. Ansprechpartner & Verantwortlichkeiten

| Rolle | Name / Team | Kontakt |
|-----|-------------|--------|
| Fachlicher Owner | {{KONTAKT_BusinessOwner}} | {{KONTAKT_BusinessOwnerMail}} |
| Technischer Owner | {{KONTAKT_TechOwner}} | {{KONTAKT_TechOwnerMail}} |
| Data Steward | {{KONTAKT_DataSteward}} | {{KONTAKT_DataStewardMail}} |
| Betrieb / Support | {{KONTAKT_Betrieb}} | {{KONTAKT_BetriebMail}} |

---

## 3. Business-Ziel & fachlicher Kontext

### 3.1 Zielsetzung
{{LH_Zielsetzung}}

### 3.2 Fachlicher Anwendungsfall
{{LH_Anwendungsfall}}

### 3.3 Nachgelagerte Verbraucher (Semantic Models / Berichte / Notebooks)
{{LH_Konsumenten}}

---

## 4. Aufbau & Struktur

### 4.1 Übersicht der Tabellen

{{LH_TabellenTabelle}}

### 4.2 Speicher & Endpunkte

{{LH_EndpunktTabelle}}

---

## 5. Datenquellen & Beladung

### 5.1 Datenquellen / vorgelagerte Prozesse

{{LH_DatenquellenTabelle}}

### 5.2 Detailbeschreibung je Datenquelle
{{LH_DatenquellenDetail}}

---

## 6. Inhalt & Nutzung

{{LH_ServiceHinweis}}

### 6.1 Tabellen im Detail

{{LH_TabellenDetail}}

### 6.2 Zugriff über den SQL-Analytics-Endpoint
{{LH_EndpointHinweis}}

### 6.3 Parameter & Konfiguration
{{LH_ParameterHinweis}}

### 6.4 Datenqualität

- Umgang mit NULL-/Fehlwerten: {{LH_NullHandling}}
- Datenvalidierungsregeln: {{LH_Validierungsregeln}}
- Aufbewahrung / Historisierung: {{LH_Aufbewahrung}}

### 6.5 Performance-Hinweise

- Partitionierung / Optimierung (OPTIMIZE, V-Order): {{LH_Optimierung}}
- Bekannte Performance-Engpässe: {{LH_PerformanceHinweise}}
- Weitere Maßnahmen: {{LH_Optimierungen}}

---

## 7. Betrieb & Wartung

### 7.1 Beladung & Orchestrierung

{{LH_Beladung}}

### 7.2 Monitoring & Fehlerbehandlung
{{LH_Monitoring}}

### 7.3 Bekannte Probleme / Technische Schulden
{{LH_BekannteProbleme}}

---

## 8. Sicherheit & Berechtigungen

### 8.1 Zugriff & Freigaben
{{LH_Zugriffe}}

### 8.2 Sensitivity Labels
{{LH_Labels}}

### 8.3 Risiken & Einschränkungen
{{LH_Risiken}}

---

## 9. Versionierung & Änderungsverlauf

### 9.1 Repository / Ablage
{{LH_Repository}}

### 9.2 Änderungsprotokoll

| Version | Datum | Änderung | Typ (fachlich/technisch) | Autor |
|-------|-------|---------|--------------------------|-------|
| 1.0 | {{LH_ExportDatum}} | Automatische Erst-Dokumentation | technisch | Auto-Dokumentation |

---

## 10. Freigabe & Review

| Rolle | Name | Datum | Kommentar |
|-----|------|-------|----------|
| Fachlich | {{REVIEW_FachName}} | {{REVIEW_FachDatum}} | {{REVIEW_FachKommentar}} |
| Technisch | {{REVIEW_TechName}} | {{REVIEW_TechDatum}} | {{REVIEW_TechKommentar}} |

---

## 11. Anhänge & Referenzen
- Übergeordnete Workspace-Dokumentation
- Architekturdiagramme
- Regulatorische Nachweise (separat)
"""


# ---------------------------------------------------------------------------
# Lokalisierungs-Hilfen
# ---------------------------------------------------------------------------

def _t(language: str, de: str, en: str) -> str:
    """Wählt den Text je nach Sprache (Default: Deutsch)."""
    return en if (language or "de").lower().startswith("en") else de


def _manual_hint(language: str) -> str:
    return _t(language, "_Manuell zu ergänzen_", "_To be completed_")


def _none(language: str) -> str:
    return _t(language, "–", "–")


# ---------------------------------------------------------------------------
# Tabellen-/Abschnitts-Generierung
# ---------------------------------------------------------------------------

def build_tables_table(
    tables: list[LakehouseTableInfo], language: str = "de"
) -> str:
    """Baut die Übersichtstabelle der Lakehouse-Tabellen."""
    if not tables:
        return _t(
            language,
            "_Keine Tabellen verfügbar._",
            "_No tables available._",
        )
    header = _t(
        language,
        "| Tabelle | Typ | Format |",
        "| Table | Type | Format |",
    )
    dash = _none(language)
    lines = [header, "|---|---|---|"]
    for tbl in tables:
        lines.append(
            f"| {_escape_cell(tbl.name)} | "
            f"{_escape_cell(tbl.table_type) or dash} | "
            f"{_escape_cell(tbl.table_format) or dash} |"
        )
    return "\n".join(lines)


def build_tables_detail(
    tables: list[LakehouseTableInfo], language: str = "de"
) -> str:
    """Baut die Detailtabelle inkl. Speicherort je Tabelle."""
    if not tables:
        return _t(
            language,
            "_Keine Tabellen verfügbar._",
            "_No tables available._",
        )
    header = _t(
        language,
        "| Tabelle | Typ | Format | Speicherort |",
        "| Table | Type | Format | Location |",
    )
    dash = _none(language)
    lines = [header, "|---|---|---|---|"]
    for tbl in tables:
        lines.append(
            f"| {_escape_cell(tbl.name)} | "
            f"{_escape_cell(tbl.table_type) or dash} | "
            f"{_escape_cell(tbl.table_format) or dash} | "
            f"{_escape_cell(tbl.location) or dash} |"
        )
    return "\n".join(lines)


def build_endpoint_section(lh: LakehouseInfo, language: str = "de") -> str:
    """Baut die Tabelle mit Speicher- und Endpunkt-Informationen."""
    dash = _none(language)
    header = _t(
        language,
        "| Ressource | Wert |",
        "| Resource | Value |",
    )
    tables_lbl = _t(language, "OneLake – Tables-Pfad", "OneLake – Tables path")
    files_lbl = _t(language, "OneLake – Files-Pfad", "OneLake – Files path")
    sql_lbl = _t(language, "SQL-Endpoint (Verbindung)", "SQL endpoint (connection)")
    lines = [
        header,
        "|---|---|",
        f"| {tables_lbl} | {_escape_cell(lh.onelake_tables_path) or dash} |",
        f"| {files_lbl} | {_escape_cell(lh.onelake_files_path) or dash} |",
        f"| {sql_lbl} | {_escape_cell(lh.sql_connection_string) or dash} |",
    ]
    return "\n".join(lines)


def build_service_hint(language: str = "de") -> str:
    """Baut den Hinweis zur Datenherkunft/Extraktion."""
    return _t(
        language,
        "> **Hinweis:** Die Struktur wird aus den Lakehouse-Properties und der "
        "Tabellenliste (`/tables`) des Microsoft Fabric Service gelesen. Ein "
        "Lakehouse besitzt keine Code-Definition; fachliche Beschreibungen sind "
        "manuell zu ergänzen.",
        "> **Note:** The structure is read from the lakehouse properties and the "
        "table list (`/tables`) of the Microsoft Fabric service. A lakehouse has "
        "no code definition; business descriptions must be completed manually.",
    )


# ---------------------------------------------------------------------------
# Platzhalter-Werte & Rendering
# ---------------------------------------------------------------------------

_MANUAL_PLACEHOLDERS = (
    "KONTAKT_BusinessOwner",
    "KONTAKT_BusinessOwnerMail",
    "KONTAKT_TechOwner",
    "KONTAKT_TechOwnerMail",
    "KONTAKT_DataSteward",
    "KONTAKT_DataStewardMail",
    "KONTAKT_Betrieb",
    "KONTAKT_BetriebMail",
    "LH_Fachbereich",
    "LH_Konzerndomaene",
    "LH_Zielsetzung",
    "LH_Anwendungsfall",
    "LH_Konsumenten",
    "LH_DatenquellenDetail",
    "LH_ParameterHinweis",
    "LH_NullHandling",
    "LH_Validierungsregeln",
    "LH_Aufbewahrung",
    "LH_Optimierung",
    "LH_PerformanceHinweise",
    "LH_Optimierungen",
    "LH_Monitoring",
    "LH_BekannteProbleme",
    "LH_Zugriffe",
    "LH_Labels",
    "LH_Risiken",
    "LH_Repository",
    "REVIEW_FachName",
    "REVIEW_FachDatum",
    "REVIEW_FachKommentar",
    "REVIEW_TechName",
    "REVIEW_TechDatum",
    "REVIEW_TechKommentar",
)


def build_lakehouse_values(
    lh: LakehouseInfo, export_date: str, language: str = "de"
) -> dict[str, str]:
    """Baut das Platzhalter-Wörterbuch für die Lakehouse-Vorlage."""
    hint = _manual_hint(language)
    dash = _none(language)

    values: dict[str, str] = {name: hint for name in _MANUAL_PLACEHOLDERS}
    values.update(
        {
            "LH_Name": lh.name or dash,
            "LH_Beschreibung": lh.description or dash,
            "LH_ID": lh.id or dash,
            "LH_WebUrl": lh.web_url or dash,
            "LH_DefaultSchema": lh.default_schema or dash,
            "LH_SqlConnection": lh.sql_connection_string or dash,
            "LH_SqlEndpointId": lh.sql_endpoint_id or dash,
            "LH_SqlStatus": lh.sql_provisioning_status or dash,
            "LH_ConfiguredBy": lh.configured_by or dash,
            "LH_ModifiedTime": lh.modified_time or dash,
            "LH_ExportDatum": export_date,
            "LH_TabellenTabelle": build_tables_table(lh.tables, language),
            "LH_TabellenDetail": build_tables_detail(lh.tables, language),
            "LH_EndpunktTabelle": build_endpoint_section(lh, language),
            "LH_ServiceHinweis": build_service_hint(language),
            "LH_DatenquellenTabelle": _t(
                language,
                "_Vorgelagerte Prozesse (Pipelines, Dataflows, Notebooks) werden "
                "nicht automatisch ermittelt. Bitte fachlich ergänzen._",
                "_Upstream processes (pipelines, dataflows, notebooks) are not "
                "determined automatically. Please complete manually._",
            ),
            "LH_EndpointHinweis": _t(
                language,
                f"Die Tabellen sind lesend über den SQL-Analytics-Endpoint "
                f"erreichbar: `{lh.sql_connection_string or dash}`.",
                f"The tables are available read-only via the SQL analytics "
                f"endpoint: `{lh.sql_connection_string or dash}`.",
            ),
            "LH_Beladung": _t(
                language,
                "_Lakehouses werden i. d. R. über Pipelines, Dataflows oder "
                "Notebooks beladen. Bitte Beladung/Orchestrierung fachlich "
                "ergänzen._",
                "_Lakehouses are typically loaded via pipelines, dataflows or "
                "notebooks. Please complete the loading/orchestration details._",
            ),
        }
    )
    return values


def render_lakehouse(
    template_content: str,
    lh: LakehouseInfo,
    export_date: str,
    language: str = "de",
) -> str:
    """Rendert ein eigenständiges Lakehouse-Dokument anhand der Vorlage."""
    values = build_lakehouse_values(lh, export_date, language)
    rendered, _warnings = TemplateRenderer().render(template_content, values)
    return rendered
