"""
Menschenlesbare Hinweise zu typischen Import-/DB-Fehlern (Universal-CSV).
"""

from __future__ import annotations


def enrich_row_error(message: str, module: str | None = None) -> dict[str, str | None]:
    """
    Ergänzt eine Rohexception-Zeichenkette um ``code`` und ``hint`` für die Fehlerliste im Import.
    """
    low = (message or "").lower()
    out: dict[str, str | None] = {"error": message, "code": None, "hint": None}

    if "numeric field overflow" in low or "numeric value out of range" in low:
        out["code"] = "db_numeric_overflow"
        out["hint"] = (
            "Wert passt nicht in die Datenbank-Spalte (z. B. NUMERIC mit begrenzter Größe). "
            "Häufig: Kilojoule aus dem Export landen im Kalorien-Feld – in der Vorlage für kcal_active/kcal_resting "
            '"source_unit": "kj" setzen. Oder eine falsche CSV-Spalte ist einem kleinen Zielfeld zugeordnet '
            "(z. B. große Zahl in einem HF-Feld)."
        )
        return out

    if "violates check constraint" in low and "source" in low:
        out["code"] = "db_check_constraint_source"
        out["hint"] = (
            "Die Tabelle erlaubt den gesetzten «source»-Wert nicht. "
            "System-Vorlage / Migration zur erlaubten Quelle prüfen (z. B. csv für Universal-Import)."
        )
        return out

    if "current transaction is aborted" in low:
        out["code"] = "transaction_aborted"
        out["hint"] = (
            "Eine frühere Zeile hat einen Datenbankfehler ausgelöst. "
            "Zuerst die niedrigste Zeilennummer in error_details beheben (Vorlage/Daten prüfen)."
        )
        return out

    if "invalid input syntax" in low and "time" in low:
        out["code"] = "db_time_cast"
        out["hint"] = (
            "start_time/end_time passen nicht zum erwarteten Zeitformat in der Datenbank. "
            "Vorlage: Datums- und Zeitanteil konsistent (oft nur Uhrzeit, wenn date separat)."
        )
        return out

    if module == "activity" and "foreign key" in low:
        out["code"] = "db_foreign_key"
        out["hint"] = "Verknüpfung zur Datenbank verletzt (z. B. training_type). Support kontaktieren."

    return out