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.

Kuratierter GPO-Regelkatalog

Ohne weitere Konfiguration startet die Policy-Evaluation mit dem freigegebenen, fachlich leeren Katalog. Ein lokal kuratierter JSON-Katalog wird nur geladen, wenn Pfad und erwarteter SHA-256 gemeinsam gesetzt sind:

ASSESSOR_POLICY_RULE_CATALOG_PATH=C:\geschuetzter-pfad\policy-rules.json
ASSESSOR_POLICY_RULE_CATALOG_SHA256=<64-stelliger SHA-256-Hexwert>

Der Server lädt höchstens 5 MiB aus einer regulären Datei, vergleicht den Inhalt vor dem JSON-Parsing mit dem fest konfigurierten Hash und validiert den vollständigen Katalogvertrag einschließlich Kontextüberschneidungen, Comparatoren, Risiko- und Abhängigkeitsregeln. Fehlende Paarparameter, Hashabweichungen, Symlinks, ungültiges UTF-8/JSON oder fachlich ungültige Regeln verhindern den Serverstart. Die Datei wird weder aus dem Netzwerk bezogen noch durch die Anwendung verändert. Jeder Evaluation Run speichert weiterhin den tatsächlich verwendeten vollständigen Katalog für reproduzierbares Reprocessing.

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.