nexarch/connect/docs/API-02-PRUEFPROTOKOLL.md

API-02 – Verbindungsstatus-Übersicht & Diagnose: Prüfprotokoll

Stand: 2026-09-23, Branch feature/api-02-connect-verbindungsstatus-diagnose, geprüft auf Entwicklungshost 204 (Wegwerf-Datenbank, archivdms unberührt).

Umsetzung

• Backend: connect/internal/syncjob.Store.ListForTenant (neu) liest alle Sync-Jobs eines Mandanten mit dem jeweils letzten Lauf in einer Abfrage (LEFT JOIN LATERAL). connect/internal/statusapi ist die HTTP-Bindung (GET /connectors/status), Identität übergangsweise über X-User-Id/X-Tenant-Slug (Muster wie workflow/internal/approvalapi vor der zentralen Core-JWT-Anbindung).
• Dienst: connect/cmd/connect-app ist der erste laufende HTTP-Dienst des Connect-Moduls (Port 9500, aus dem bereits reservierten Bereich deploy/ports.tsv), gehärtete Timeouts nach dem httpharden-Muster.
• Betrieb: connect/cmd/migrate wendet die Migrationen an (Gegenstück zu dms/cmd/migrate).
• Oberfläche: web/connect-status (Next.js/React, @nexarch/shl-Design-System, Bearer-/Identitäts-Muster wie UX-10, Fokus- und Theme-Härtung wie in UX-07/UX-08 auf web/mail-search gelernt).
• Test-Fixture: connect/cmd/status-a11y-fixture — Kopie von connect-app mit CORS-Freigabe, genau wie dms/cmd/a11y-fixture. Der Produktionsdienst connect-app bleibt ohne CORS (Annahme: same-origin Reverse-Proxy wie bei allen anderen Modulen).

Akzeptanzkriterien

1. Verbindungsstatus je Connector auf einen Blick — erfüllt. Tabelle zeigt Status farbig hervorgehoben je Zeile.
2. Letzter Sync-Lauf mit Ergebnis einsehbar — erfüllt. Zeitpunkt und Auslöser (geplant/manuell) je Zeile.
3. Fehlerdiagnose zeigt Ursache aus dem Fehlerprotokoll — erfüllt. last_error aus sync_job_runs wird unverändert angezeigt.

Prüfungen

1. Statusanzeige korrekt für erfolgreichen und fehlgeschlagenen Lauf — bestanden. Go-Test TestListForTenant_ReturnsJobsWithLastRun (echte Postgres-Wegwerf-DB) und Vitest zeigt den Status für erfolgreichen und fehlgeschlagenen Lauf korrekt an.
2. Diagnoseansicht zeigt reale Testfehler nachvollziehbar — bestanden. Go-Test prüft LastError byteidentisch gegen den eingegebenen Fehlertext; Vitest zeigt die Fehlerursache aus dem Fehlerprotokoll; echter Browserlauf (siehe unten) zeigt den Text verbindung zu drittsystem abgelehnt im gerenderten DOM.
3. Aktualisierung nach neuem Sync-Lauf korrekt — bestanden. Vitest zeigt nach Klick auf Aktualisieren den neuen Status eines inzwischen abgeschlossenen Laufs (Oberfläche hat dafür eine Aktualisieren-Schaltfläche bekommen, echter erneuter Abruf, kein Caching).

Läufe auf 204

• go build ./..., go vet ./..., gofmt -l .: sauber.
• go test -count=1 ./... (echte Postgres-Wegwerf-DB, TEST_TENANT_DSN): alle Pakete ok, inkl. statusapi (neu) und syncjob (erweitert).
• web/connect-status: tsc --noEmit sauber, vitest run 5/5, next build erfolgreich (Routen /, /status).
• Echter Browserlauf (web/a11y-audit/connect-status-run.sh, Chrome stable, echter connect-Dienst gegen echte Postgres-Daten, zwei synthetische Connectoren mit je einem erfolgreichen und einem fehlgeschlagenen Lauf): axe 0 Verstöße in hell und dunkel, kein horizontaler Überlauf, sichtbarer Fokusring, Tabelle mit den echten Daten gerendert (tableCount: 1, 12 Zellen = 2 Zeilen × 6 Spalten).
• check-port-defaults.sh, check-route-prefixes.sh: ok.
• Rückbau: Ports 9590/4190 (Testlauf) sind nach Skriptende frei, kein Prozess- oder Verzeichnisrest auf 204.

QA und Entscheidungen

• Aktualisieren-Schaltfläche statt automatischem Polling: Bewusste, kleinste Lösung für Prüfung 3 — ein Intervall-Polling wäre außerhalb des Ticket-Scopes (Ticket verlangt nur, dass eine Aktualisierung korrekt ist, kein Echtzeit-Update).
• CORS nur im Test-Fixture: Der echte connect-app-Dienst bekommt keine CORS-Freigabe, weil kein anderes Modul das für den Produktionsbetrieb tut (alle verlassen sich auf denselben Ursprung über den Reverse Proxy). Ein eigenes Fixture-Binary (Muster dms/cmd/a11y-fixture) hält diese Testbequemlichkeit vom Produktionscode fern.
• Migrationswerkzeug ergänzt (connect/cmd/migrate): War nötig, um die Migrationen überhaupt real anwenden zu können (Voraussetzung für den echten Browserlauf), ist aber auch als Betriebswerkzeug außerhalb dieses Tickets sinnvoll — analog zu dms/cmd/migrate.
• 4 Fix-Iterationen (von bis zu 20 erlaubten): Vitest-Reload-Test ursprünglich mit zwei parallelen Renders statt einer Aktualisieren-Schaltfläche (behoben), fehlendes afterEach(cleanup) (SHL-01-Erfahrung, führte zu „mehrere Elemente gefunden"), fehlende @testing-library/jest-dom-Abhängigkeit, CORS-Fehler im Browserlauf (gelöst durch eigenes Test-Fixture-Binary statt Änderung am Produktionsdienst).

Nicht Teil dieser Kachel

• QA-02 Prüfgate Connector-Engine (folgt).
• Bildschirmleser-Stichprobe: nicht durchgeführt, gleiche organisatorische Lücke wie bei UX-06/UX-07 (kein NVDA/VoiceOver auf dem Testhost).