From 54f7d9bd38c3338ea4e85ed007a54df5d3925122 Mon Sep 17 00:00:00 2001
From: FDS <fds@matrix.schepmann.de>
Date: Mon, 8 Jun 2026 21:03:54 +0200
Subject: [PATCH 1/2] Fix #55: LLM-Verbindungstest mit Diagnoseausgabe
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- LlmService::testConnection() gibt cURL-Fehler, HTTP-Code, Antwortzeit und verfügbare Modelle zurück
- probeOllama() schreibt cURL-Fehler ins PHP-Fehlerlog
- Einstellungsseite: Button "Verbindung testen" mit Inline-Diagnose und Firewall-Hinweis
- Route POST /settings/llm-test
---
 Changes.md                             |  7 +++
 public/index.php                       |  1 +
 src/Controllers/SettingsController.php |  7 +++
 src/Services/LlmService.php            | 59 ++++++++++++++++++++++++--
 src/Views/settings/form.php            | 54 ++++++++++++++++++++++-
 5 files changed, 123 insertions(+), 5 deletions(-)

diff --git a/Changes.md b/Changes.md
index 42ba768..7de518d 100644
--- a/Changes.md
+++ b/Changes.md
@@ -2,6 +2,13 @@
 
 ---
 
+## 2026-06-08 – Fix: KI-Verbindungstest mit Diagnoseinformationen (Issue #55)
+
+- **`LlmService`:** Neue Methode `testConnection()` gibt detaillierte Diagnose zurück (cURL-Fehlernummer/-meldung, HTTP-Code, Antwortzeit, verfügbare Modelle)
+- **`LlmService`:** `probeOllama()` schreibt bei cURL-Fehlern jetzt einen Eintrag ins PHP-Fehlerlog (`docker compose logs web`)
+- **Einstellungsseite:** Neuer Button „Verbindung testen" im KI-Abschnitt; zeigt bei Erfolg verfügbare Modelle, bei Fehler cURL-Fehler, URL und Firewall-Hinweis an
+- **Route:** `POST /settings/llm-test` → `SettingsController::llmTest()`
+
 ## 2026-06-01 – Fix: EN16931-Validierungsfehler in ZUGFeRD-Rechnungen
 
 - **[BR-FX-EN-04]** behoben: `ZugferdService` setzt jetzt BT-72 (Liefer-/Leistungsdatum) via `setDocumentSupplyChainEvent()`; das Datum wird aus dem Feld `leistungszeitraum` geparst (Format `DD.MM.YYYY` → direkt; Format `MM.YYYY` → letzter Tag des Monats; sonst Fallback auf Rechnungsdatum)
diff --git a/public/index.php b/public/index.php
index 1efd2cb..8a9ef53 100644
--- a/public/index.php
+++ b/public/index.php
@@ -165,6 +165,7 @@ $router->post('/settings/mail-test', fn($p) => (new SettingsController())->mailT
 $router->post('/settings/logo', fn($p) => (new SettingsController())->uploadLogo($p));
 $router->post('/settings/logo/delete', fn($p) => (new SettingsController())->deleteLogo($p));
 $router->post('/settings/generate-app-key', fn($p) => (new SettingsController())->generateAppKey($p));
+$router->post('/settings/llm-test',         fn($p) => (new SettingsController())->llmTest($p));
 $router->get('/settings/bankimport',                    fn($p) => (new SettingsController())->bankImport($p));
 $router->post('/settings/bankimport/suggest',            fn($p) => (new SettingsController())->storeSuggestion($p));
 $router->post('/settings/bankimport/create',             fn($p) => (new SettingsController())->createBankImportFormat($p));
diff --git a/src/Controllers/SettingsController.php b/src/Controllers/SettingsController.php
index 40503aa..aec7af0 100644
--- a/src/Controllers/SettingsController.php
+++ b/src/Controllers/SettingsController.php
@@ -126,6 +126,13 @@ class SettingsController extends BaseController
         echo json_encode(['key' => bin2hex(random_bytes(32))]);
     }
 
+    public function llmTest(array $params): void
+    {
+        header('Content-Type: application/json');
+        $result = (new \Steuerkram\Services\LlmService())->testConnection();
+        echo json_encode($result);
+    }
+
     public function bankImport(array $params): void
     {
         $formats    = BankSource::all('csv');
diff --git a/src/Services/LlmService.php b/src/Services/LlmService.php
index f144826..a41cd29 100644
--- a/src/Services/LlmService.php
+++ b/src/Services/LlmService.php
@@ -134,9 +134,54 @@ class LlmService
         }
     }
 
+    /**
+     * Liefert Diagnose-Informationen für den Verbindungstest auf der Einstellungsseite.
+     * Gibt ein Array zurück: ['ok' => bool, 'url' => string, 'elapsed' => int, 'error'? => string, 'models'? => string[]]
+     *
+     * @return array<string, mixed>
+     */
+    public function testConnection(): array
+    {
+        if ($this->mode === null) {
+            return ['ok' => false, 'error' => 'Kein LLM-Provider konfiguriert.'];
+        }
+        if ($this->mode === 'openai') {
+            return ['ok' => true, 'url' => $this->url, 'elapsed' => 0, 'info' => 'OpenAI-Modus – kein Verbindungstest möglich.'];
+        }
+
+        $url = $this->url . '/api/tags';
+        $ch  = curl_init($url);
+        curl_setopt_array($ch, [
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_TIMEOUT        => 5,
+            CURLOPT_CONNECTTIMEOUT => 3,
+        ]);
+        $start    = microtime(true);
+        $response = curl_exec($ch);
+        $elapsed  = (int)round((microtime(true) - $start) * 1000);
+        $code     = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        $errno    = curl_errno($ch);
+        $errstr   = curl_error($ch);
+        curl_close($ch);
+
+        if ($errno !== 0) {
+            error_log("[Steuerkram] LlmService::testConnection() cURL-Fehler #{$errno} auf {$url}: {$errstr}");
+            return ['ok' => false, 'url' => $url, 'elapsed' => $elapsed, 'error' => "cURL #{$errno}: {$errstr}"];
+        }
+        if ($code < 200 || $code >= 300) {
+            return ['ok' => false, 'url' => $url, 'elapsed' => $elapsed, 'error' => "HTTP {$code}"];
+        }
+
+        $data   = json_decode($response, true);
+        $models = array_column($data['models'] ?? [], 'name');
+
+        return ['ok' => true, 'url' => $url, 'elapsed' => $elapsed, 'models' => $models];
+    }
+
     private function probeOllama(string $baseUrl): bool
     {
-        $ch = curl_init($baseUrl . '/api/tags');
+        $url = $baseUrl . '/api/tags';
+        $ch  = curl_init($url);
         curl_setopt_array($ch, [
             CURLOPT_RETURNTRANSFER => true,
             CURLOPT_TIMEOUT        => 2,
@@ -144,10 +189,16 @@ class LlmService
             CURLOPT_NOBODY         => false,
         ]);
         curl_exec($ch);
-        $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-        $err  = curl_errno($ch);
+        $code  = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        $errno = curl_errno($ch);
+        $err   = curl_error($ch);
         curl_close($ch);
-        return $err === 0 && $code >= 200 && $code < 300;
+
+        if ($errno !== 0) {
+            error_log("[Steuerkram] LlmService::probeOllama() cURL-Fehler #{$errno} auf {$url}: {$err}");
+        }
+
+        return $errno === 0 && $code >= 200 && $code < 300;
     }
 
     private function callOllama(string $prompt): string
diff --git a/src/Views/settings/form.php b/src/Views/settings/form.php
index facb00f..b558032 100644
--- a/src/Views/settings/form.php
+++ b/src/Views/settings/form.php
@@ -256,7 +256,7 @@
                 $reachable     = $providerLabel !== null ? $llm->isReachable() : false;
                 $ollamaUrlEnv  = getenv('OLLAMA_URL') ?: ($_ENV['OLLAMA_URL'] ?? '');
                 ?>
-                <p class="text-sm" style="margin:0 0 0 1.75rem;color:<?= $reachable ? 'var(--color-success,#16a34a)' : '#dc2626' ?>">
+                <p class="text-sm" style="margin:0 0 .5rem 1.75rem;color:<?= $reachable ? 'var(--color-success,#16a34a)' : '#dc2626' ?>">
                     <?php if ($reachable): ?>
                         ✓ Provider erreichbar: <?= $h($providerLabel) ?>
                     <?php elseif ($providerLabel): ?>
@@ -269,6 +269,11 @@
                         — Kein LLM-Provider konfiguriert (Auto-Discovery localhost:11434 fehlgeschlagen)
                     <?php endif; ?>
                 </p>
+                <div style="margin-left:1.75rem;display:flex;align-items:center;gap:.5rem;flex-wrap:wrap">
+                    <button type="button" class="btn btn-secondary btn-sm" id="btn-llm-test">Verbindung testen</button>
+                    <span id="llm-test-result" style="font-size:.8rem"></span>
+                </div>
+                <div id="llm-test-detail" style="margin:.5rem 0 0 1.75rem;font-size:.8rem;display:none"></div>
             </div>
         </div>
 
@@ -477,6 +482,53 @@
     </div>
 </div>
 
+<script>
+document.getElementById('btn-llm-test')?.addEventListener('click', function () {
+    var btn    = this;
+    var result = document.getElementById('llm-test-result');
+    var detail = document.getElementById('llm-test-detail');
+    btn.disabled = true;
+    result.textContent = 'Teste…';
+    result.style.color = '';
+    detail.style.display = 'none';
+    fetch('/settings/llm-test', { method: 'POST', headers: { 'X-Requested-With': 'XMLHttpRequest' } })
+        .then(function (r) { return r.json(); })
+        .then(function (data) {
+            if (data.ok) {
+                result.textContent = '✓ Verbindung OK (' + (data.elapsed || 0) + ' ms)';
+                result.style.color = 'green';
+                if (data.models && data.models.length > 0) {
+                    detail.textContent = 'Modelle: ' + data.models.join(', ');
+                    detail.style.display = 'block';
+                    detail.style.color = '#374151';
+                } else if (data.info) {
+                    detail.textContent = data.info;
+                    detail.style.display = 'block';
+                    detail.style.color = '#374151';
+                }
+            } else {
+                result.textContent = '✗ Verbindung fehlgeschlagen';
+                result.style.color = 'red';
+                if (data.error) {
+                    var lines = ['Fehler: ' + data.error];
+                    if (data.url) lines.push('URL: ' + data.url);
+                    if (data.elapsed) lines.push('Nach ' + data.elapsed + ' ms');
+                    lines.push('Tipp: sudo ufw allow from 172.16.0.0/12 to any port 11434 (oder firewall prüfen)');
+                    lines.push('Logs: docker compose logs web');
+                    detail.innerHTML = lines.map(function (l) { return '<div>' + l + '</div>'; }).join('');
+                    detail.style.display = 'block';
+                    detail.style.color = '#dc2626';
+                }
+            }
+        })
+        .catch(function () {
+            result.textContent = '✗ Netzwerkfehler';
+            result.style.color = 'red';
+        })
+        .finally(function () { btn.disabled = false; });
+});
+</script>
+
 <script>
 document.getElementById('btn-mail-test')?.addEventListener('click', function () {
     var btn = this;

From 1a23b3e11d209420d1a2423c7779c952f53474a1 Mon Sep 17 00:00:00 2001
From: FDS <fds@matrix.schepmann.de>
Date: Mon, 8 Jun 2026 21:20:33 +0200
Subject: [PATCH 2/2] =?UTF-8?q?Fix=20#55:=20Verbindungsfehler-Fallback=20?=
 =?UTF-8?q?=E2=80=93=20kein=20Retry-Loop,=20spezifische=20Fehlermeldung?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Changes.md                            |  2 +
 src/Controllers/BelegController.php   | 13 ++++++-
 src/Views/belege/detail.php           | 11 ++++++
 tests/43_KiConnectionFallbackTest.php | 54 +++++++++++++++++++++++++++
 4 files changed, 78 insertions(+), 2 deletions(-)
 create mode 100644 tests/43_KiConnectionFallbackTest.php

diff --git a/Changes.md b/Changes.md
index 7de518d..9b34645 100644
--- a/Changes.md
+++ b/Changes.md
@@ -8,6 +8,8 @@
 - **`LlmService`:** `probeOllama()` schreibt bei cURL-Fehlern jetzt einen Eintrag ins PHP-Fehlerlog (`docker compose logs web`)
 - **Einstellungsseite:** Neuer Button „Verbindung testen" im KI-Abschnitt; zeigt bei Erfolg verfügbare Modelle, bei Fehler cURL-Fehler, URL und Firewall-Hinweis an
 - **Route:** `POST /settings/llm-test` → `SettingsController::llmTest()`
+- **`BelegController`:** Bei Verbindungsfehler wird jetzt `[]` statt `null` gespeichert (verhindert endlose Auto-Retry-Schleife); Fehlermeldung differenziert zwischen „Ollama nicht erreichbar" und „kein Vorschlag generiert"
+- **Beleg-Detailseite:** Zeigt bei Verbindungsfehler spezifische Meldung „Ollama nicht erreichbar" mit Link zu den Einstellungen statt der generischen Warnung
 
 ## 2026-06-01 – Fix: EN16931-Validierungsfehler in ZUGFeRD-Rechnungen
 
diff --git a/src/Controllers/BelegController.php b/src/Controllers/BelegController.php
index b89cf76..4d145f9 100644
--- a/src/Controllers/BelegController.php
+++ b/src/Controllers/BelegController.php
@@ -378,8 +378,17 @@ class BelegController extends BaseController
 
         $svc       = new KontierungsvorschlagService();
         $vorschlag = $svc->generateForBeleg($beleg);
-        Beleg::saveKiVorschlag($id, $vorschlag);
-        echo json_encode($vorschlag ?? ['error' => 'Kein Vorschlag generiert']);
+        // [] = "verarbeitet, kein Ergebnis"; null würde endlose Auto-Retry-Schleife auslösen
+        Beleg::saveKiVorschlag($id, $vorschlag ?? []);
+        if ($vorschlag === null) {
+            $llm = new \Steuerkram\Services\LlmService();
+            echo json_encode($llm->isReachable()
+                ? ['error' => 'Kein Vorschlag generiert']
+                : ['connection_error' => true]
+            );
+            return;
+        }
+        echo json_encode($vorschlag);
     }
 
     public function resetVorschlag(array $params): void
diff --git a/src/Views/belege/detail.php b/src/Views/belege/detail.php
index d05ea6c..ef5bb6e 100644
--- a/src/Views/belege/detail.php
+++ b/src/Views/belege/detail.php
@@ -1101,6 +1101,16 @@ function _showKiBadgeError() {
         '<button class="btn btn-secondary btn-sm" onclick="_startKiAnalyse()">Erneut versuchen</button></div>';
 }
 
+function _showKiBadgeConnectionError() {
+    const neuBtn = _kiAktiv
+        ? ' <button class="btn btn-secondary btn-sm" onclick="_startKiAnalyse()">Erneut versuchen</button>'
+        : '';
+    document.getElementById('ki-badge').innerHTML =
+        '<div class="flash flash-warning">Ollama nicht erreichbar.' + neuBtn +
+        ' <a href="/settings" style="color:inherit;text-decoration:underline">Einstellungen / Verbindung testen</a>' +
+        '</div>';
+}
+
 // Normalisiert _kiVorschlag zu einem Array (Objekt oder Array aus DB möglich).
 // Gibt null zurück wenn kein Ergebnis vorhanden.
 // Gibt leeres Array [] zurück wenn verarbeitet aber kein Ergebnis erzeugt.
@@ -1119,6 +1129,7 @@ async function _startKiAnalyse() {
     try {
         const r   = await fetch('/belege/' + _belegId + '/vorschlag/generate', {method: 'POST'});
         const raw = await r.json();
+        if (raw && raw.connection_error) { _showKiBadgeConnectionError(); return; }
         const arr = _normalizeKiArr(raw);
         if (arr && arr.length > 0) { _applyKiVorschlag(arr[0]); _showKiBadgeDone(arr); }
         else _showKiBadgeNoResult();
diff --git a/tests/43_KiConnectionFallbackTest.php b/tests/43_KiConnectionFallbackTest.php
new file mode 100644
index 0000000..b240532
--- /dev/null
+++ b/tests/43_KiConnectionFallbackTest.php
@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+use Steuerkram\Database;
+use Steuerkram\Models\Beleg;
+
+class KiConnectionFallbackTest extends TestCase
+{
+    protected string $testName = 'Test 43: KI-Verbindungsfehler-Fallback';
+
+    public function run(): void
+    {
+        $belegId = $this->createTestBeleg();
+
+        // [] = "verarbeitet, kein Ergebnis" – verhindert endlose Auto-Retry-Schleife
+        Beleg::saveKiVorschlag($belegId, []);
+        $beleg = Beleg::find($belegId);
+        $this->assertNotEmpty($beleg['ki_vorschlag'], 'Leeres Array muss als JSON gespeichert werden, nicht als SQL NULL');
+
+        $decoded = json_decode($beleg['ki_vorschlag'], true);
+        $this->assert(is_array($decoded) && count($decoded) === 0, 'Gespeicherter Wert muss leeres Array sein');
+
+        // null = "noch nicht verarbeitet" – löst Auto-Retry auf der Beleg-Seite aus
+        Beleg::saveKiVorschlag($belegId, null);
+        $beleg = Beleg::find($belegId);
+        $this->assert($beleg['ki_vorschlag'] === null, 'saveKiVorschlag(null) muss SQL NULL ergeben');
+
+        // Nicht-leeres Array wird korrekt gespeichert und zurückgelesen
+        $vorschlag = [[
+            'buchungstyp'        => 'Ausgabe',
+            'kategorie_konto_id' => 5,
+            'zahlungskonto_id'   => 2,
+            'ust_satz'           => 19,
+            'betrag_netto'       => 99.00,
+            'buchungstext'       => 'Fallback-Test',
+        ]];
+        Beleg::saveKiVorschlag($belegId, $vorschlag);
+        $beleg   = Beleg::find($belegId);
+        $decoded = json_decode($beleg['ki_vorschlag'], true);
+        $this->assert(is_array($decoded) && count($decoded) === 1, 'Vorschlag-Array korrekt gespeichert');
+        $this->assertEquals('Ausgabe', $decoded[0]['buchungstyp'], 'buchungstyp korrekt');
+    }
+
+    private function createTestBeleg(): int
+    {
+        Database::execute(
+            "INSERT INTO belege (beleg_nr, filename, storage_path, mime_type, file_hash, belegtyp)
+             VALUES ('TEST-KI-FALLBACK-001', 'test.pdf', 'static/uploads/test/test.pdf', 'application/pdf',
+                     SHA2('fallback-test', 256), 'Eingangsrechnung')"
+        );
+        return (int)Database::lastInsertId();
+    }
+}