107 lines
5.3 KiB
Markdown
107 lines
5.3 KiB
Markdown
# 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.
|