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

Definition-basiert (analog zu :mod:`core.copyjob_doc_generator`): die
``RealTimeQueryset.json`` beschreibt die gespeicherten KQL-Abfragen/Tabs.
Rendering aus einem :class:`~core.models.KqlQuerysetInfo`.
"""
from __future__ import annotations

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

KQLQUERYSET_TEMPLATE_FILENAME = "WorkspaceKQLQuerysetvorlage.md"

_MAX_QUERY_CHARS = 2000

__all__ = [
    "KQLQUERYSET_TEMPLATE_FILENAME",
    "DEFAULT_KQLQUERYSET_TEMPLATE",
    "ensure_template",
    "load_template",
    "build_queries_table",
    "build_queries_detail",
    "build_service_hint",
    "build_kqlqueryset_values",
    "render_kqlqueryset",
]


DEFAULT_KQLQUERYSET_TEMPLATE = """# Microsoft Fabric KQL-Queryset-Dokumentation

> **Hinweis:** Diese Dokumentation ist verpflichtend für alle Produktiv-KQL-Querysets.
> 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-Queryset-Name | {{QS_Name}} |
| Beschreibung | {{QS_Beschreibung}} |
| KQL-Queryset-ID | {{QS_ID}} |
| Web-URL | {{QS_WebUrl}} |
| Anzahl Abfragen | {{QS_AnzahlAbfragen}} |
| Erstellt / konfiguriert von | {{QS_ConfiguredBy}} |
| Zuletzt geändert | {{QS_ModifiedTime}} |
| Fachbereich | {{QS_Fachbereich}} |
| Konzerndomäne | {{QS_Konzerndomaene}} |
| Aktuelle Version | 1.0 |
| Status | Produktiv |
| Letzte Aktualisierung | {{QS_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
{{QS_Zielsetzung}}

### 3.2 Fachlicher Anwendungsfall
{{QS_Anwendungsfall}}

### 3.3 Nachgelagerte Verbraucher (Real-Time-Dashboards / Berichte)
{{QS_Konsumenten}}

---

## 4. Aufbau & Struktur

### 4.1 Übersicht der Abfragen

{{QS_AbfragenTabelle}}

### 4.2 Abfragen im Detail

{{QS_AbfragenDetail}}

---

## 5. Datenquellen & Beladung

### 5.1 Verbundene KQL-Datenbanken / Datenquellen

{{QS_DatenquellenTabelle}}

### 5.2 Detailbeschreibung je Datenquelle
{{QS_DatenquellenDetail}}

---

## 6. Inhalt & Nutzung

{{QS_ServiceHinweis}}

### 6.1 Verwendung der Abfragen
{{QS_VerwendungHinweis}}

### 6.2 Parameter & Konfiguration
{{QS_ParameterHinweis}}

### 6.3 Datenqualität

- Umgang mit NULL-/Fehlwerten: {{QS_NullHandling}}
- Datenvalidierungsregeln: {{QS_Validierungsregeln}}
- Aufbewahrung / Historisierung: {{QS_Aufbewahrung}}

### 6.4 Performance-Hinweise

- Abfrage-Optimierung: {{QS_Optimierung}}
- Bekannte Performance-Engpässe: {{QS_PerformanceHinweise}}
- Weitere Maßnahmen: {{QS_Optimierungen}}

---

## 7. Betrieb & Wartung

### 7.1 Nutzung & Orchestrierung

{{QS_Beladung}}

### 7.2 Monitoring & Fehlerbehandlung
{{QS_Monitoring}}

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

---

## 8. Sicherheit & Berechtigungen

### 8.1 Zugriff & Freigaben
{{QS_Zugriffe}}

### 8.2 Sensitivity Labels
{{QS_Labels}}

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

---

## 9. Versionierung & Änderungsverlauf

### 9.1 Repository / Ablage
{{QS_Repository}}

### 9.2 Änderungsprotokoll

| Version | Datum | Änderung | Typ (fachlich/technisch) | Autor |
|-------|-------|---------|--------------------------|-------|
| 1.0 | {{QS_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_queries_table(queries: list[KqlQueryInfo], language: str = "de") -> str:
    """Baut die Übersichtstabelle der Abfragen."""
    if not queries:
        return _t(
            language, "_Keine Abfragen verfügbar._", "_No queries available._"
        )
    header = _t(language, "| Abfrage | Zeichen |", "| Query | Characters |")
    lines = [header, "|---|---|"]
    for q in queries:
        lines.append(f"| {_escape_cell(q.name) or _none(language)} | {len(q.query_text)} |")
    return "\n".join(lines)


def build_queries_detail(queries: list[KqlQueryInfo], language: str = "de") -> str:
    """Baut die Detailabschnitte je Abfrage inkl. (gekürztem) KQL-Codeblock."""
    if not queries:
        return _t(
            language, "_Keine Abfragen verfügbar._", "_No queries available._"
        )
    parts: list[str] = []
    for q in queries:
        name = q.name or _t(language, "(ohne Namen)", "(unnamed)")
        text = q.query_text or ""
        if len(text) > _MAX_QUERY_CHARS:
            suffix = _t(language, "\n… (gekürzt)", "\n… (truncated)")
            text = text[:_MAX_QUERY_CHARS] + suffix
        parts.append(f"#### {name}\n\n```kusto\n{text}\n```")
    return "\n\n".join(parts)


def build_service_hint(language: str = "de") -> str:
    return _t(
        language,
        "> **Hinweis:** Die gespeicherten Abfragen werden aus der Definition "
        "(`RealTimeQueryset.json`) des Microsoft Fabric Service gelesen. "
        "Fachliche Beschreibungen sind manuell zu ergänzen.",
        "> **Note:** The saved queries are read from the definition "
        "(`RealTimeQueryset.json`) of the Microsoft Fabric service. Business "
        "descriptions must be completed manually.",
    )


_MANUAL_PLACEHOLDERS = (
    "KONTAKT_BusinessOwner",
    "KONTAKT_BusinessOwnerMail",
    "KONTAKT_TechOwner",
    "KONTAKT_TechOwnerMail",
    "KONTAKT_DataSteward",
    "KONTAKT_DataStewardMail",
    "KONTAKT_Betrieb",
    "KONTAKT_BetriebMail",
    "QS_Fachbereich",
    "QS_Konzerndomaene",
    "QS_Zielsetzung",
    "QS_Anwendungsfall",
    "QS_Konsumenten",
    "QS_DatenquellenTabelle",
    "QS_DatenquellenDetail",
    "QS_ParameterHinweis",
    "QS_NullHandling",
    "QS_Validierungsregeln",
    "QS_Aufbewahrung",
    "QS_Optimierung",
    "QS_PerformanceHinweise",
    "QS_Optimierungen",
    "QS_Monitoring",
    "QS_BekannteProbleme",
    "QS_Zugriffe",
    "QS_Labels",
    "QS_Risiken",
    "QS_Repository",
    "REVIEW_FachName",
    "REVIEW_FachDatum",
    "REVIEW_FachKommentar",
    "REVIEW_TechName",
    "REVIEW_TechDatum",
    "REVIEW_TechKommentar",
)


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

    values: dict[str, str] = {name: hint for name in _MANUAL_PLACEHOLDERS}
    values.update(
        {
            "QS_Name": qs.name or dash,
            "QS_Beschreibung": qs.description or dash,
            "QS_ID": qs.id or dash,
            "QS_WebUrl": qs.web_url or dash,
            "QS_AnzahlAbfragen": str(len(qs.queries)),
            "QS_ConfiguredBy": qs.configured_by or dash,
            "QS_ModifiedTime": qs.modified_time or dash,
            "QS_ExportDatum": export_date,
            "QS_AbfragenTabelle": build_queries_table(qs.queries, language),
            "QS_AbfragenDetail": build_queries_detail(qs.queries, language),
            "QS_ServiceHinweis": build_service_hint(language),
            "QS_VerwendungHinweis": _t(
                language,
                "_Die Abfragen dienen der interaktiven KQL-Analyse und können in "
                "Real-Time-Dashboards weiterverwendet werden. Bitte konkrete "
                "Verwendung fachlich ergänzen._",
                "_The queries are used for interactive KQL analysis and can be "
                "reused in real-time dashboards. Please complete the concrete "
                "usage manually._",
            ),
            "QS_Beladung": _t(
                language,
                "_Ein KQL-Queryset wird interaktiv genutzt (keine automatische "
                "Beladung). Bitte Nutzung fachlich ergänzen._",
                "_A KQL queryset is used interactively (no automatic loading). "
                "Please complete the usage details manually._",
            ),
        }
    )
    return values


def render_kqlqueryset(
    template_content: str,
    qs: KqlQuerysetInfo,
    export_date: str,
    language: str = "de",
) -> str:
    """Rendert ein eigenständiges KQL-Queryset-Dokument anhand der Vorlage."""
    values = build_kqlqueryset_values(qs, export_date, language)
    rendered, _warnings = TemplateRenderer().render(template_content, values)
    return rendered
