# 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.

```text
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:

```text
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.