syncova-backup/docs/web-ui.md

Weboberfläche

Die Konsole, über die man die Anlage bedient — und der Ort, an dem sich am leichtesten etwas vortäuschen ließe.

Sie erreicht 89 von 95 fachlichen Endpunkten. Die sechs offenen sind Detail-Abrufe (GET /alerts/{id}, GET /agents/{id}, GET /proxmox/vms/{id}, GET /security/findings, GET /verification/{id} und dessen Ergebnisse), deren Daten die jeweiligen Listen bereits enthalten.

Die eine Entscheidung, die alles trägt

Semantische Farben ausschließlich für Zustände (PROMPT §106). Die Konsole ist neutral gehalten; wo Farbe erscheint, bedeutet sie etwas. Eine bunte Oberfläche verschleiert, welche Information wirklich dringend ist — und in einer Backup-Konsole ist genau das die einzige Frage, die zählt.

Daraus folgt der Zuschnitt: kein Markenblau als Fläche, der Akzent nur für Bedienelemente. Der Schweregrad einer Kennzahl färbt die Randlinie, nicht die Kachel; zehn farbige Flächen nebeneinander ergeben ein Mosaik, in dem die eine kritische Zahl untergeht.

Die Statuszuordnung steht an genau einer Stelle

components/ui/StatusBadge.tsx bildet jeden Fachbegriff der API auf einen der fünf Töne ab. Wäre diese Abbildung über die Seiten verteilt, erschiene früher oder später irgendwo partial_failure grün — und ein Betreiber hält einen Teilfehler dann für einen Erfolg.

Vier Zuordnungen sind keine Geschmacksfrage:

Wert	Ton	Warum
partial_failure	Warnung	Entwicklungsregel 1: nie SUCCESS
successful (Einstufung)	neutral	Heißt „der Lauf ist durchgelaufen", nicht „wiederherstellbar"
corrupted	kritisch	Nicht zu 70 % wiederherstellbar, sondern gar nicht
advisory (Löschschutz)	Warnung	Der Schutz ist eine Software-Regel, kein Schutz des Dateisystems

Ein unbekannter Wert wird neutral dargestellt, niemals grün. Ein neuer Serverzustand, den die Tabelle nicht kennt, darf nicht als „in Ordnung" durchgehen. StatusBadge.test.tsx hält alle fünf Punkte fest; jeder wurde durch Mutation als fangend bestätigt.

Was nicht da ist, wird benannt

Der Grundsatz aus PROMPT §139 gilt unverändert: Ein Menü, das nur die fertigen Bereiche zeigt, verschweigt den Ausbaustand; eines mit leeren Masken täuscht ihn vor. Jeder Eintrag erscheint, und ein noch nicht verfügbarer nennt, was fehlt.

Konkret sichtbar an vier Stellen:

• Kennzahlen ohne Datengrundlage erscheinen mit Begründung statt mit einer Null. „0 kritische Meldungen" hieße „keine Probleme" und bedeutete „es wird nicht geprüft".
• Ungemessene Eingangsgrößen der Bewertung stehen als „ungemessen" da, nicht als null Punkte. Als 0 zu zeigen bestrafte das Unbekannte.
• Nicht ausgewertete Meldungsregeln werden als solche gekennzeichnet. Eine Regel, die dauerhaft schweigt, ist gefährlicher als keine.
• Ungeprüfte Bereiche im Security Center gehen weder positiv noch negativ in die Rechnung ein; ab drei sagt die Seite, dass die Zahl eine Vermutung ist.

Die achtzehn Seiten

Bereich	Seiten
Betrieb	Übersicht · Sicherungsaufträge · Wiederherstellung · Meldungen
Daten	Wiederherstellungspunkte · Prüfung · Repositories · Aufbewahrung
Infrastruktur	Agenten · Proxmox · Geschützte Systeme
Analyse	Kennzahlen · Berichte · Security Center
Verwaltung	Benutzer · Rollen · Ereignisprotokoll · Einstellungen

Die Gliederung folgt dem Weg durch die Anlage: Was täglich beobachtet wird, steht oben; was einmal eingerichtet und dann selten angefasst wird, unten.

Handlungen, die etwas verändern

Die drei Hürden vor dem Überschreiben

Der Wiederherstellungs-Assistent setzt sie sichtbar um:

1. Das Kennzeichen overwrite_existing muss gesetzt werden.
2. Die Berechtigung restores.overwrite prüft der Server — sie steckt bewusst nicht in restores.execute.
3. confirm_overwrite verlangt den wörtlich wiederholten Zielpfad.

Läuft die dritte ins Leere, weil das Ziel leer ist, entfällt sie. Ein Ritual ohne Anlass gewöhnt das Wegklicken an — und dann wirkt es dort nicht mehr, wo es zählt. Dieselbe Überlegung trägt die wörtliche Bestätigung beim Löschen eines Wiederherstellungspunkts, eines Auftrags und beim Anwenden einer Aufbewahrungsregel.

Die Vorabprüfung ist ein eigener Schritt

Sie schreibt nichts und stellt fest, ob jeder benötigte Block noch da ist. Ein Manifest allein belegt nur, dass jemand einmal etwas gesichert hat. Fehlende Blöcke stehen ganz oben und in Rot; sie sind der einzige Befund, bei dem feststeht, dass die Wiederherstellung nicht vollständig gelingen kann.

Ein 409 ist eine Auskunft, kein Fehler

Ein zweiter Anstoß bei laufendem Auftrag erscheint als Hinweis, nicht als Fehlschlag. Der Auftrag läuft ja — und genau das wollte der Betreiber wissen.

Was Löschen wirklich bewirkt, steht dabei

• Ein gelöschter Auftrag nimmt seine Wiederherstellungspunkte nicht mit. Sie gehören zum Repository. Ohne diesen Hinweis löscht jemand einen Auftrag in der Annahme, Platz zu schaffen.
• Wird beim Löschen kein Speicher frei, ist das kein Fehler, sondern Deduplizierung: Die Blöcke werden von einem anderen Backup gebraucht.

Geheimnisse gehen nur hinein

Das Aufnahme-Token eines Agenten erscheint genau einmal, mit ausdrücklichem Hinweis und ohne Weg, den Dialog versehentlich zu schließen. Das API-Token eines Proxmox-Verbunds wird nach dem Anlegen nie wieder ausgeliefert — das ist kein Mangel, sondern der Grund, warum ein Lesezugriff auf die Konfiguration ungefährlich ist.

Aussehen

Farben, Radien, Schatten und Schrift stammen aus dem Preset b5vnF8SMi (tweakcn): violett als Handlungsfarbe, Radius 0, schattenlos, durchgehend Geist Mono. Kantig und ruhig.

Drei Abweichungen, begründet in styles/theme.css:

• Die Statusfarben bleiben. Das Preset kennt nur destructive und fünf Diagrammfarben; §106 verlangt fünf Bedeutungen. Ohne sie ließe sich ein Teilfehler nicht von einem Erfolg unterscheiden.
• Das dunkle Thema hängt an [data-theme='dark'], nicht an .dark — der Umschalter setzt dieses Attribut. .dark funktioniert zusätzlich.
• Geist Mono lädt nicht nach. Sie steht zuerst im Stapel; liegt sie nicht auf dem Gerät, greift die System-Monospace. Eine Schrift von einem fremden Host zu holen verbietet die CSP — und ein Backup-Server, der für seine Oberfläche ins Internet greift, wäre auch ohne CSP falsch.

Eine Zuordnung ist die Stolperstelle: In shadcn ist accent die dezente Hover-Fläche und primary die Farbe der Handlung. Sie zu verwechseln macht jede Schaltfläche grau.

Die Benennung bleibt semantisch (--surface-card, --text-primary) statt shadcn-typisch: Die Zuordnung steht an genau einer Stelle, und ein Wechsel des Presets fasst keine einzige Komponente an.

Technik

• Tailwind v4 und Radix-Primitive nach shadcn-Muster. Alles gebündelt; die CSP der Auslieferung lässt externe Ressourcen ohnehin nicht zu.
• Farben als CSS-Variablen, damit dieselbe Komponente in beiden Themen funktioniert, ohne dass jede Klasse eine dark:-Variante braucht.
• Fehlergrenze um den Seiteninhalt. Ohne sie reißt ein Fehler in einer Komponente den gesamten Baum ab; übrig bleibt eine leere Seite — im dunklen Thema ein schwarzer Bildschirm ohne Hinweis. Menü und Kopfzeile bleiben stehen, der Fehlertext ist lesbar.
• Dark Mode über ein Attribut am Wurzelelement, nicht allein über die Medienabfrage: Eine Konsole, die nachts während einer Störung von selbst umschaltet, ist lästig. Das Attribut sitzt am Wurzelelement, weil ein Dialog im Portal sonst im falschen Thema erschiene.
• Navigation über die History-API, keine Router-Bibliothek. Zwei Ebenen — Seite und optional ein Objekt darauf — reichen für diese Konsole.
• useMutation für schreibende Aufrufe: Doppelklickschutz, Vorgangsnummer bis in die Meldung, kein setState nach dem Aushängen.
• Idempotency-Key an allen anlegenden und zerstörenden Aufrufen. Ohne ihn erzeugt ein Doppelklick zwei Aufträge — und bei einer Wiederherstellung zwei gleichzeitige Läufe in dasselbe Ziel.
• Die Servermeldung hat Vorrang vor der allgemeinen Erklärung zum Fehlercode. Sie kennt den Einzelfall, und diese Genauigkeit ist mehr wert.
• Berechtigungen im Menü sind Anzeige, keine Sicherung. Sie verhindern Sackgassen; geprüft wird auf dem Server.

Sitzung

Sie überlebt ein Neuladen. Die Tokens liegen im sessionStorage des Tabs — nicht im localStorage, der ein Schließen des Browsers überstünde. Begrenzt wird sie durch zwei Uhren:

Harte Obergrenze	30 Minuten ab Anmeldung, durch keine Interaktion verschiebbar
Untätigkeitsgrenze	30 Minuten ohne Eingabe

Maßgeblich ist die frühere der beiden. Die verbleibende Zeit steht neben „Abmelden" und wird unter fünf Minuten auffällig.

Dass die Tokens überhaupt abgelegt werden, kehrt eine frühere Entscheidung um: Vorher lagen sie nur im Arbeitsspeicher, und jedes Neuladen warf den Betreiber auf die Anmeldemaske. Mitten in einer Störung ist das kein Sicherheitsgewinn, sondern ein Hindernis. Was den Rest trägt, ist nicht der Speicherort, sondern der sofortige serverseitige Widerruf: Die Tokens sind opak, kein JWT, und genau dafür wurden sie gewählt.

• Jede Fehleranzeige nennt request_id, kopierbar. Ohne sie bleibt „es hat nicht funktioniert".

Betriebsfolge

Das Bundle braucht einen SPA-Fallback (try_files $uri /index.html), sonst ergibt ein Neuladen auf /recovery-points einen 404. setup.sh richtet das mit ein.

Nachgewiesen

Gegen Debian 12 mit echtem PostgreSQL und nginx, über genau die Aufrufe, die die Konsole macht:

• Repository übernommen, Durchsetzungsstufe gemessen (advisory — auf overlayfs richtig)
• Auftrag angelegt, Lauf 202, zweiter Anstoß 409
• Sicherung erfolgreich: 2 Objekte, 3.000.006 Byte, 0 übergangen
• Blockprüfung clean, 5 Blöcke
• Vorabprüfung: „wiederherstellbar, 2 Dateien, 2,9 MiB"
• Wiederherstellung nach /etc abgewiesen
• Alle 18 Seiten liefern über HTTPS 200; das Design-System steckt samt Dark-Mode-Regeln im ausgelieferten CSS

76 Tests, tsc sauber, eslint ohne Warnung. Bundle 466 KB (136 KB gzip), CSS 30 KB (6 KB gzip).

Bekannte Grenzen

• Sechs Detail-Endpunkte haben keine eigene Ansicht; ihre Daten stehen in den Listen.
• Die Suche im Ereignisprotokoll filtert im Browser über die letzten 100 Einträge. Bei größeren Beständen gehört sie auf den Server.
• Geist Mono wird nicht mitgeliefert. Ohne die Schrift auf dem Gerät sieht die Oberfläche in der System-Monospace anders aus als im Preset.
• Kein Live-Fortschritt. /api/v1/events/stream steht in SYNCOVA_API.md, ist aber auch serverseitig nicht umgesetzt — es fehlt nicht nur die Anbindung. Laufende Sicherungen und Wiederherstellungen aktualisieren sich beim Neuladen, nicht von selbst.
• Kein Simple Mode. Der Plan trennt Simple und Advanced Mode; umgesetzt ist eine Ansicht.
• Proxmox ist nicht auf echter Hardware freigegeben. Die Seite sagt das ausdrücklich.