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

API-01 – Connect-Konfigurationsoberfläche: Prüfprotokoll

Stand: 2026-10-16, Branch feature/api-01-01-connect-konfigurationsoberflaeche-connectoren-einrichten, geprüft auf Entwicklungshost 204 (eigene Wegwerf-DBs api01_connect/api01_connect_a11y, Rolle api01_connect_test; archivdms unberührt).

Umsetzung

• Backend: connect/internal/connectorcatalog (neu) ist der statische Katalog der Connector-Typen (erp, crm, m365, backup, datev), je mit Zugangsdaten-Art (API-Key/OAuth2) und NEXARCH-Feld-Schema für fieldmapping. connect/internal/credential bekommt ListForTenant und die reine Funktion Mask (feste Maske •••• + letzte 4 Zeichen, ab 8 Zeichen Länge vollständig verdeckt) — Erweiterung von ENG-02, kein Eingriff in dessen bestehende Methoden. connect/internal/connectorsetupapi (neu) bindet beides an HTTP: Katalog lesen, Verbindungen anlegen/maskiert auflisten (ENG-02), Feld-Mapping lesen/speichern (ENG-04). Identität übergangsweise über X-User-Id/X-Tenant-Slug, gleiches Muster wie statusapi/dms2importapi.
• Schlüsselverwaltung: connect-app braucht für credential.Store einen KEK-Provider. Da API-10/API-12 (Core-KMS-Client) noch nicht existieren, liest connect-app einen einzigen, operatorseitig vorgegebenen Schlüssel aus NEXARCH_CONNECT_APP_KEK (base64, 32 Byte) — übergangsweise, bis der echte KMS-Client existiert, nie im Code.
• Oberfläche: web/connect-setup (Next.js/React, @nexarch/shl-Design-System, gleiches Turbopack-Symlink→Kopie-Muster wie web/connect-status). Eine Seite /setup: Formular „Neue Verbindung" (Connector-Typ, Instanz-Kennung, Zugangsdaten je nach Art), Tabelle „Eingerichtete Verbindungen" mit maskierten Zugangsdaten, Feld-Mapping-Editor je Verbindung (ein Textfeld je Schema-Feld, Pflichtfelder markiert).
• Test-Fixture: connect/cmd/setup-a11y-fixture — CORS-Kopie von connect-app, analog status-a11y-fixture. Der Produktionsdienst bleibt ohne CORS.

Akzeptanzkriterien

1. Connector lässt sich vollständig über die Oberfläche einrichten, ohne Konfigurationsdatei — erfüllt. Connector-Typ, Instanz-Kennung, Zugangsdaten und Feld-Mapping werden ausschließlich über Formulare erfasst und per HTTP an connectorsetupapi gesendet; keine YAML-/Env-Datei pro Connector-Instanz nötig.
2. Zugangsdaten werden nur maskiert angezeigt, nie im Klartext — erfüllt. credential.Mask liefert serverseitig nur •••• + höchstens 4 Zeichen; die Oberfläche zeigt ausschließlich diesen Wert, Eingabefelder für neue Zugangsdaten werden nach dem Speichern geleert statt den Wert zurückzuspiegeln.
3. Feld-Mapping ist über die Oberfläche bearbeitbar — erfüllt. Mapping-Editor liest den aktiven Stand (fieldmapping.Store.GetActive) und speichert Änderungen als neue Version (Save), inklusive Ablehnung bei ungültigem Mapping (ENG-04 AC2).

Prüfungen

Alle drei Prüfungen wurden sowohl als automatisierter Test (Go-Integrationstest gegen echte Postgres-Wegwerf-DB, Vitest mit echtem Komponenten-Rendering) als auch in einem echten Browserlauf durchgeführt.

1. Vollständige Einrichtung eines Testconnectors über die Oberfläche erfolgreich — bestanden.
   • Go: TestFullConnectorSetup_WithoutConfigFile (connect/internal/connectorsetupapi) — Katalog abrufen, Verbindung erp/acme-erp-1 per PUT anlegen, Mapping speichern, Verbindung in der Liste wiederfinden.
   • Vitest: richtet einen Testconnector vollstaendig ueber das Formular ein — Formular ausgefüllt, abgesendet, neue Zeile in der Tabelle sichtbar.
   • Echter Browserlauf (web/a11y-audit/connect-setup-run.sh, Chrome stable via puppeteer-core, echter setup-a11y-fixture-Dienst gegen echte Postgres-Daten): Connector-Typ „ERP-System" gewählt, Instanz-Kennung browser-test-erp-1 und ein synthetischer API-Schlüssel eingegeben, Formular abgesendet — Ergebnis OK: Pruefung 1.
2. Zugangsdaten in der Oberfläche im Test nachweislich maskiert — bestanden.
   • Go: TestListConnections_CredentialsAreMasked — Antwortkörper der Verbindungsliste enthält das eingegebene Geheimnis an keiner Stelle (strings.Contains-Prüfung), maskierter Wert beginnt mit ••••.
   • Vitest: zeigt Zugangsdaten in der Verbindungsliste nur maskiert.
   • Echter Browserlauf: nach dem Anlegen der Verbindung enthält das gerenderte DOM (page.content()) das eingegebene Geheimnis testconnector-geheimnis-7788991100 nachweislich nicht; die Tabelle zeigt ••••1100 — Ergebnis OK: Pruefung 2.
3. Mapping-Änderung über die Oberfläche im Test korrekt übernommen — bestanden.
   • Go: TestMapping_ChangeIsPickedUpOnNextRead — Mapping speichern (Version 1), ändern (Version 2), erneut lesen liefert den geänderten Wert.
   • Vitest: uebernimmt eine Mapping-Aenderung korrekt — Feld geändert, gespeichert, saveMapping mit den erwarteten Einträgen aufgerufen, neue Version angezeigt.
   • Echter Browserlauf: Feld kundennummer auf debitorennummer gesetzt, gespeichert, Seite neu geladen (nicht nur lokaler React-State) und Mapping-Editor erneut geöffnet — der Wert debitorennummer ist weiterhin im Eingabefeld sichtbar — Ergebnis OK: Pruefung 3.

Läufe auf 204

• go build ./..., go vet ./..., gofmt -l . (für die neu/ geänderten Dateien): sauber.
• go test -count=1 -p 1 ./... (echte Postgres-Wegwerf-DB api01_connect, Rolle api01_connect_test): alle 30 Pakete ok, inkl. connectorcatalog, connectorsetupapi (neu) und credential (erweitert).
• web/connect-setup: tsc --noEmit sauber, vitest run 4/4, next build erfolgreich (Routen /, /setup).
• Echter Browserlauf (web/a11y-audit/connect-setup-run.sh, DB api01_connect_a11y): alle drei Formular-Interaktionsprüfungen OK, anschließender axe-Audit 0 Verstöße, 0 offene Befunde in hell und dunkel, kein horizontaler Überlauf, Tastaturerreichbarkeit 5/5 interaktive Elemente, sichtbarer Fokusring, lang="de".
• Rückbau: Ports 9591/4191 (Testlauf) sind nach Skriptende frei (ss -ltnp leer), kein Prozess- oder Verzeichnisrest auf 204.

QA und Entscheidungen

• Connector-Katalog als statische Liste im neuen Backend-Paket statt Erweiterung von registry.Connector: ENG-01s Registrierungsschnittstelle kennt pro Instanz nur Metadata() (Name/Version/Operationen), kein Feld-Schema. Eine Erweiterung dieser Schnittstelle oder der bestehenden Connector-Pakete (erpconnector, crmconnector, …) hätte deren Scope verlassen (kein Teil von API-01). Der Katalog ist reine Beschreibungsdaten für die Oberfläche, ohne Datenbanktabelle — kleinste Lösung.
• Übergangsweiser env-basierter KEK statt echtem KMS-Client: credential.Store war seit ENG-02 nur in Tests verdrahtet, nie in einem laufenden Dienst — ohne einen KEKProvider lässt sich die Oberfläche nicht real betreiben. API-10/API-12 (echter Core-KMS-Client) sind eigene, noch nicht gemergte Tickets; ein einzelner, aus NEXARCH_CONNECT_APP_KEK gelesener Schlüssel schließt genau diese Lücke, ohne deren Scope vorzugreifen.
• Maskierung als feste Zeichenkette (•••• + max. 4 Zeichen, ab 8 Zeichen Länge volle Verdeckung) statt reiner Längenangabe: verhindert, dass die maskierte Anzeige selbst die Geheimnislänge verrät, und bleibt trotzdem erkennbar genug, um mehrere Verbindungen gleichen Typs zu unterscheiden.
• Eigener Browser-Interaktions-Lauf (connect-setup-interaction-check.js) zusätzlich zum bestehenden audit.js: audit.js lädt nur Seiten und prüft sie statisch; API-01 verlangt aber reale Dateneingabe (Formular ausfüllen, Connector anlegen, Mapping ändern). Das neue Skript nutzt dieselbe puppeteer-core-Infrastruktur, führt aber echte Klick-/Eingabeinteraktionen aus und prüft danach das gerenderte DOM — stärkerer Nachweis als ein reiner Vitest-Mock-Test.
• 2 Fix-Iterationen (von bis zu 20 erlaubten): aria-label auf einem <span> ohne passende Rolle löste eine axe-incomplete-Meldung aus (behoben durch data-masked="true" statt aria-label); A11Y_NODE_MODULES-Pfad auf 204 liegt unter /usr/lib/..., nicht dem im bestehenden audit.js-Kommentar vermuteten /usr/local/lib/... (per Env-Variable korrigiert, kein Code-Eingriff in audit.js nötig).

Fazit

Alle drei Akzeptanzkriterien und alle drei geforderten Prüfungen sind erfüllt und belegt (automatisierter Test plus echter Browserlauf je Kriterium). API-01 gilt als vollständig umgesetzt.

Nicht Teil dieser Kachel

• API-02 Verbindungsstatus-Übersicht & Diagnose (bereits fertig, nicht hier dupliziert).
• Verbindungs-Widerruf über die Oberfläche: ENG-02s Store.Revoke existiert bereits, ist aber kein Akzeptanzkriterium dieser Kachel und wurde daher nicht an die Oberfläche angebunden.
• Bildschirmleser-Stichprobe: nicht durchgeführt, gleiche organisatorische Lücke wie bei UX-06/UX-07/API-02 (kein NVDA/VoiceOver auf dem Testhost).