"""Generator für die Fabric KQL-Datenbank-Dokumentation.

Analog zu :mod:`core.warehouse_doc_generator`: eingebaute Standard-Vorlage +
Rendering aus einem :class:`~core.models.KqlDatabaseInfo`. KQL-Datenbanken sind
property-basierte Items (kein ``getDefinition``, nur Lese-Rechte); die Doku
stützt sich auf die Item-Properties (Query-/Ingestion-URI, übergeordnetes
Eventhouse, Datenbanktyp). Das eigentliche KQL-Schema (Tabellen/Funktionen) ist
über den Query-Endpoint erreichbar und fachlich zu ergänzen.
"""
from __future__ import annotations

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

KQLDATABASE_TEMPLATE_FILENAME = "WorkspaceKQLDatenbankvorlage.md"

__all__ = [
    "KQLDATABASE_TEMPLATE_FILENAME",
    "DEFAULT_KQLDATABASE_TEMPLATE",
    "ensure_template",
    "load_template",
    "build_endpoint_section",
    "build_service_hint",
    "build_kqldatabase_values",
    "render_kqldatabase",
]


DEFAULT_KQLDATABASE_TEMPLATE = """# Microsoft Fabric KQL-Datenbank-Dokumentation

> **Hinweis:** Diese Dokumentation ist verpflichtend für alle Produktiv-KQL-Datenbanken.
> 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 |
|-----|------|
| KQL-Datenbank-Name | {{KH_Name}} |
| Beschreibung | {{KH_Beschreibung}} |
| KQL-Datenbank-ID | {{KH_ID}} |
| Web-URL | {{KH_WebUrl}} |
| Datenbanktyp | {{KH_DatabaseType}} |
| Übergeordnetes Eventhouse | {{KH_ParentEventhouse}} |
| Query-Endpoint | {{KH_QueryUri}} |
| Ingestion-Endpoint | {{KH_IngestionUri}} |
| Erstellt / konfiguriert von | {{KH_ConfiguredBy}} |
| Zuletzt geändert | {{KH_ModifiedTime}} |
| Fachbereich | {{KH_Fachbereich}} |
| Konzerndomäne | {{KH_Konzerndomaene}} |
| Aktuelle Version | 1.0 |
| Status | Produktiv |
| Letzte Aktualisierung | {{KH_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
{{KH_Zielsetzung}}

### 3.2 Fachlicher Anwendungsfall
{{KH_Anwendungsfall}}

### 3.3 Nachgelagerte Verbraucher (Semantic Models / Berichte / Real-Time-Dashboards)
{{KH_Konsumenten}}

---

## 4. Aufbau & Zugriff

### 4.1 Verbindung & Endpunkte

{{KH_EndpunktTabelle}}

### 4.2 Datenbankschema (Tabellen / Funktionen / Materialisierte Sichten)
{{KH_Schema}}

---

## 5. Datenquellen & Beladung

### 5.1 Datenquellen / vorgelagerte Prozesse

{{KH_DatenquellenTabelle}}

### 5.2 Detailbeschreibung je Datenquelle
{{KH_DatenquellenDetail}}

---

## 6. Inhalt & Nutzung

{{KH_ServiceHinweis}}

### 6.1 Zugriff über den Query-Endpoint
{{KH_EndpointHinweis}}

### 6.2 Parameter & Konfiguration
{{KH_ParameterHinweis}}

### 6.3 Datenqualität

- Umgang mit NULL-/Fehlwerten: {{KH_NullHandling}}
- Datenvalidierungsregeln: {{KH_Validierungsregeln}}
- Aufbewahrung / Caching-Richtlinie: {{KH_Aufbewahrung}}

### 6.4 Performance-Hinweise

- Update-Policies / Materialisierte Sichten: {{KH_Optimierung}}
- Bekannte Performance-Engpässe: {{KH_PerformanceHinweise}}
- Weitere Maßnahmen: {{KH_Optimierungen}}

---

## 7. Betrieb & Wartung

### 7.1 Beladung & Orchestrierung

{{KH_Beladung}}

### 7.2 Monitoring & Fehlerbehandlung
{{KH_Monitoring}}

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

---

## 8. Sicherheit & Berechtigungen

### 8.1 Zugriff & Freigaben
{{KH_Zugriffe}}

### 8.2 Sensitivity Labels
{{KH_Labels}}

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

---

## 9. Versionierung & Änderungsverlauf

### 9.1 Repository / Ablage
{{KH_Repository}}

### 9.2 Änderungsprotokoll

| Version | Datum | Änderung | Typ (fachlich/technisch) | Autor |
|-------|-------|---------|--------------------------|-------|
| 1.0 | {{KH_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)
"""


def _t(language: str, de: str, en: str) -> str:
    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, "–", "–")


def build_endpoint_section(kh: KqlDatabaseInfo, language: str = "de") -> str:
    """Baut die Tabelle mit Verbindungs-/Endpunkt-Informationen."""
    dash = _none(language)
    header = _t(language, "| Eigenschaft | Wert |", "| Property | Value |")
    query_lbl = _t(language, "Query-Endpoint", "Query endpoint")
    ingest_lbl = _t(language, "Ingestion-Endpoint", "Ingestion endpoint")
    type_lbl = _t(language, "Datenbanktyp", "Database type")
    parent_lbl = _t(language, "Übergeordnetes Eventhouse", "Parent eventhouse")
    lines = [
        header,
        "|---|---|",
        f"| {query_lbl} | {_escape_cell(kh.query_service_uri) or dash} |",
        f"| {ingest_lbl} | {_escape_cell(kh.ingestion_service_uri) or dash} |",
        f"| {type_lbl} | {_escape_cell(kh.database_type) or dash} |",
        f"| {parent_lbl} | {_escape_cell(kh.parent_eventhouse_id) or dash} |",
    ]
    return "\n".join(lines)


def build_service_hint(language: str = "de") -> str:
    return _t(
        language,
        "> **Hinweis:** Die Metadaten stammen aus den KQL-Datenbank-Properties "
        "des Microsoft Fabric Service. Eine KQL-Datenbank besitzt keine "
        "Code-Definition; das Schema (Tabellen/Funktionen) ist über den "
        "Query-Endpoint (KQL) erreichbar und fachlich zu ergänzen.",
        "> **Note:** The metadata comes from the KQL database properties of the "
        "Microsoft Fabric service. A KQL database has no code definition; the "
        "schema (tables/functions) is available via the query endpoint (KQL) "
        "and must be completed manually.",
    )


_MANUAL_PLACEHOLDERS = (
    "KONTAKT_BusinessOwner",
    "KONTAKT_BusinessOwnerMail",
    "KONTAKT_TechOwner",
    "KONTAKT_TechOwnerMail",
    "KONTAKT_DataSteward",
    "KONTAKT_DataStewardMail",
    "KONTAKT_Betrieb",
    "KONTAKT_BetriebMail",
    "KH_Fachbereich",
    "KH_Konzerndomaene",
    "KH_Zielsetzung",
    "KH_Anwendungsfall",
    "KH_Konsumenten",
    "KH_Schema",
    "KH_DatenquellenDetail",
    "KH_ParameterHinweis",
    "KH_NullHandling",
    "KH_Validierungsregeln",
    "KH_Aufbewahrung",
    "KH_Optimierung",
    "KH_PerformanceHinweise",
    "KH_Optimierungen",
    "KH_Monitoring",
    "KH_BekannteProbleme",
    "KH_Zugriffe",
    "KH_Labels",
    "KH_Risiken",
    "KH_Repository",
    "REVIEW_FachName",
    "REVIEW_FachDatum",
    "REVIEW_FachKommentar",
    "REVIEW_TechName",
    "REVIEW_TechDatum",
    "REVIEW_TechKommentar",
)


def build_kqldatabase_values(
    kh: KqlDatabaseInfo, export_date: str, language: str = "de"
) -> dict[str, str]:
    """Baut das Platzhalter-Wörterbuch für die KQL-Datenbank-Vorlage."""
    hint = _manual_hint(language)
    dash = _none(language)

    values: dict[str, str] = {name: hint for name in _MANUAL_PLACEHOLDERS}
    values.update(
        {
            "KH_Name": kh.name or dash,
            "KH_Beschreibung": kh.description or dash,
            "KH_ID": kh.id or dash,
            "KH_WebUrl": kh.web_url or dash,
            "KH_DatabaseType": kh.database_type or dash,
            "KH_ParentEventhouse": kh.parent_eventhouse_id or dash,
            "KH_QueryUri": kh.query_service_uri or dash,
            "KH_IngestionUri": kh.ingestion_service_uri or dash,
            "KH_ConfiguredBy": kh.configured_by or dash,
            "KH_ModifiedTime": kh.modified_time or dash,
            "KH_ExportDatum": export_date,
            "KH_EndpunktTabelle": build_endpoint_section(kh, language),
            "KH_ServiceHinweis": build_service_hint(language),
            "KH_DatenquellenTabelle": _t(
                language,
                "_Vorgelagerte Prozesse (Eventstreams, Pipelines, Notebooks) "
                "werden nicht automatisch ermittelt. Bitte fachlich ergänzen._",
                "_Upstream processes (eventstreams, pipelines, notebooks) are "
                "not determined automatically. Please complete manually._",
            ),
            "KH_EndpointHinweis": _t(
                language,
                f"Die KQL-Datenbank ist über den Query-Endpoint erreichbar: "
                f"`{kh.query_service_uri or dash}`.",
                f"The KQL database is available via the query endpoint: "
                f"`{kh.query_service_uri or dash}`.",
            ),
            "KH_Beladung": _t(
                language,
                "_KQL-Datenbanken werden i. d. R. über Eventstreams, Pipelines "
                "oder Ingestion-Befehle beladen. Bitte Beladung/Orchestrierung "
                "fachlich ergänzen._",
                "_KQL databases are typically loaded via eventstreams, pipelines "
                "or ingestion commands. Please complete the loading/orchestration "
                "details._",
            ),
        }
    )
    return values


def render_kqldatabase(
    template_content: str,
    kh: KqlDatabaseInfo,
    export_date: str,
    language: str = "de",
) -> str:
    """Rendert ein eigenständiges KQL-Datenbank-Dokument anhand der Vorlage."""
    values = build_kqldatabase_values(kh, export_date, language)
    rendered, _warnings = TemplateRenderer().render(template_content, values)
    return rendered
