Refactoring #19: Benutzerfreundliche deutsche KI-Fehlermeldungen im Begründungsbereich

Neue Klasse AiFailureMessageTranslator übersetzt technische englische Fehlertexte (z.B. HTTP-Statuscodes, Verbindungsfehler) in lesbare deutsche Benutzerhinweise. GuiBatchRunTab nutzt den Translator vor der Anzeige; das Datenmodell (aiFailureMessage) bleibt unverändert. Unit-Tests decken alle definierten Mapping-Fälle ab. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-24 08:25:46 +02:00
parent b87e8498e6
commit 3a98304a5c
3 changed files with 192 additions and 1 deletions
@@ -0,0 +1,54 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+/**
+ * Übersetzt technische KI-Fehlermeldungen in benutzerfreundliche deutsche Texte.
+ * <p>
+ * Die Klasse wertet die rohe, englischsprachige Fehlermeldung aus dem
+ * Verarbeitungsversuch aus und liefert eine für den Endbenutzer lesbare
+ * Beschreibung des Fehlergrunds. Das ursprüngliche Datenmodell bleibt
+ * unverändert; die Übersetzung findet ausschließlich in der Darstellungsschicht
+ * statt.
+ * <p>
+ * Die Mustererkennung erfolgt ohne Berücksichtigung der Groß-/Kleinschreibung
+ * und prüft die definierten Schlüsselbegriffe in festgelegter Reihenfolge,
+ * damit spezifischere Muster vor allgemeineren greifen.
+ */
+final class AiFailureMessageTranslator {
+
+    private AiFailureMessageTranslator() {
+    }
+
+    /**
+     * Liefert eine benutzerfreundliche deutsche Fehlermeldung für die angegebene
+     * technische Fehlerbeschreibung.
+     * <p>
+     * Ist {@code technicalMessage} {@code null} oder leer, wird der allgemeine
+     * Fallback-Text zurückgegeben.
+     *
+     * @param technicalMessage die rohe technische Fehlermeldung; darf {@code null} sein
+     * @return eine nicht-leere deutsche Benutzerfehlermeldung
+     */
+    static String translate(String technicalMessage) {
+        if (technicalMessage == null || technicalMessage.isBlank()) {
+            return "KI-Aufruf fehlgeschlagen. Details im Anwendungslog.";
+        }
+        String lower = technicalMessage.toLowerCase(java.util.Locale.ROOT);
+
+        if (lower.contains("http_401")) {
+            return "KI-Dienst: Ungültiger API-Schlüssel. Bitte in den Einstellungen prüfen.";
+        }
+        if (lower.contains("http_403")) {
+            return "KI-Dienst: Zugriff verweigert. Bitte API-Schlüssel und Berechtigungen prüfen.";
+        }
+        if (lower.contains("http_429")) {
+            return "KI-Dienst: Anfragelimit erreicht. Bitte später erneut versuchen.";
+        }
+        if (lower.contains("http_5")) {
+            return "KI-Dienst vorübergehend nicht erreichbar. Bitte später erneut versuchen.";
+        }
+        if (lower.contains("connection") || lower.contains("timeout") || lower.contains("refused")) {
+            return "KI-Dienst nicht erreichbar. Bitte Netzwerkverbindung prüfen.";
+        }
+        return "KI-Aufruf fehlgeschlagen. Details im Anwendungslog.";
+    }
+}
@@ -901,7 +901,9 @@ public final class GuiBatchRunTab {
                reasoning -> builder.append(reasoning),
                () -> {
                    row.aiFailureMessage().ifPresent(msg ->
-                            builder.append("\u26A0 Fehler: ").append(msg).append("\n\n"));
+                            builder.append("\u26A0 Fehler: ")
+                                    .append(AiFailureMessageTranslator.translate(msg))
+                                    .append("\n\n"));
                    builder.append(NO_REASONING_TEXT);
                });
        return builder.toString();