Assessor_2.0/docs/LOCAL_BACKEND.md

Lokales ASSESSOR-Backend

Zweck und Betriebsform

Phase 10 führt die spätere Firmenarchitektur zunächst vollständig auf einem Entwicklungsrechner aus. Ein Node.js-Prozess liefert sowohl die gebaute React-Anwendung als auch die versionierte API aus. Dadurch bleiben Browser und API auf demselben Ursprung.

Browser -> http://127.0.0.1:4173 -> ASSESSOR-Backend -> AssessorRepository

Der Server bindet standardmäßig ausschließlich an 127.0.0.1. Eine Freigabe im Firmennetz ist damit ausdrücklich noch nicht erfolgt. ASSESSOR_HOST und ASSESSOR_PORT sind Betriebsparameter; eine Bindung an eine Netzwerkschnittstelle darf erst zusammen mit Phase 14, HTTPS, Authentifizierung und Berechtigungen erfolgen.

Start

• npm run dev startet den vollständigen lokalen Entwicklungsstack. Der Starter prüft zuerst /api/v1/health, baut und startet ein fehlendes Backend auf 127.0.0.1:4173 und öffnet den Vite-Client erst danach auf 127.0.0.1:5173.

• npm run dev:client startet bewusst nur den Client und ist für die seltenen Fälle gedacht, in denen das Backend separat verwaltet wird.

• npm run build baut Browser-App und Backend.

• npm run start:local lädt eine vorhandene .env.postgres und startet den zuvor gebauten Server auf Port 4173.

• npm run serve:local führt beide Schritte nacheinander aus.

• Der Vite-Entwicklungsserver leitet /api an Port 4173 weiter; dadurch funktioniert der Datahub auch unter http://127.0.0.1:5173, wenn das Backend parallel läuft.

Die App zeigt Server verbunden, wenn /api/v1/health erreichbar ist. Ohne Backend läuft sie vorübergehend im bisherigen Browser-/Tauri-Modus weiter.

API-Grenze

Alle Endpunkte liegen unter /api/v1. Der Vertrag umfasst:

• Health und rein metadatenbasiertes Audit-Log
• Projekte und Assessments
• Finding-Abfragen und Assessment-Modelle
• Reviews, Profile und lokale Vergleichsregeln
• gespeicherte Vergleiche, Projektexport und kontrollierte Projektlöschung
• atomare Importsitzungen mit Stage, Commit und Rollback
• Dateimetadatenprüfung und serverseitiges Parsen von CSV, JSON, XML, HTML, XLSX und XLS

Fehler besitzen immer code, message und requestId. Schreibzugriffe verlangen die Kopfzeile X-Assessor-Request: 1; vorhandene Origin-Header müssen zum Serverursprung passen. Der Server setzt keine CORS-Freigabe.

Importdatenfluss

Die React-App prüft beim Start die lokale API. Bei bestehender Verbindung liest der API-Client die ausgewählte Datei als Bytes und übermittelt sie base64-kodiert an den gleichen lokalen Server. Dort gelten derzeit folgende Grenzen:

• unterstützte Erweiterungen: CSV, JSON, XML, HTML/HTM, XLSX und XLS
• maximale Quelldateigröße: 100 MiB
• maximales JSON-Anfragevolumen: 140 MiB wegen Base64-Overhead
• Metadaten und dekodierte Byteanzahl müssen übereinstimmen
• maximal 50 Dateien je Vorschau; Vorschaucache 15 Minuten, 10 Batches und 256 MiB
• dokumentierte Tabellen-, Zeilen-, Spalten-, Zell-, Markup-, JSON- und ZIP-Grenzen

Die vorhandene plattformneutrale Importengine übernimmt Parsing, Profilwahl und Erkennung. Im Serverbetrieb läuft jeder Parserauftrag in einem isolierten Worker; Standardwerte sind 30 Sekunden Laufzeit, 512 MiB Old-Generation-Speicher, zwei parallele Aufträge und acht wartende Aufträge. Der Node-Markupadapter führt keine importierten Skripte aus und entfernt aktive HTML-Elemente vor der Tabellenauswertung. Alle Grenzwerte und konfigurierbaren Workerparameter stehen in docs/IMPORT_SECURITY_LIMITS.md.

Persistenzstand

Mit ASSESSOR_DATABASE_URL verwendet das Backend den dauerhaften PostgresAssessorRepository. Migrationen laufen beim Start automatisch und Health meldet persistence: postgresql. Ohne Datenbank-URL bleibt ein LocalAssessorRepository als ausdrücklich flüchtiger Entwicklungsmodus verfügbar. Ist eine URL gesetzt und die Datenbank nicht erreichbar, bricht der Start ab; es findet kein stiller Fallback statt.

Ein vollständiges lokales PostgreSQL-Setup, Schema-, Migrations-, Backup- und Restore-Regeln stehen in docs/POSTGRESQL.md.

Originaldateien werden aktuell nicht als separate Serverartefakte abgelegt. Die API verarbeitet die Bytes und speichert die daraus erzeugten kanonischen Fachobjekte. Eine spätere Aufbewahrung von Originalartefakten bleibt eine eigene Datenschutz- und Betriebsentscheidung.