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

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.