MABEA/arbeitskacheln/20_ui_redesign.md

# Epic 20 — UI-Redesign (moderne BOS-Plattform-Optik)

Ausgangspunkt: externer Redesign-Prompt vom 2026-09-06 (Nutzer-Vorgabe, siehe
Referenzen). **Keine Neuentwicklung, keine Entfernung bestehender Funktionen** —
bestehende API/Fachlogik/PWA/Offline-Sync bleiben unverändert, nur die Darstellung
wird modernisiert. React/Vite/TypeScript bleibt, kein Framework-Wechsel.

Aktueller Stand vor Redesign: 39 Seiten-/Komponenten-Dateien, ~7.000 Zeilen, einfaches
`global.css` (560 Zeilen) ohne Designsystem, keine UI-Bibliothek.

---

## UI-001 — Designsystem-Grundlage

- **Ziel:** Ein zentrales Set an Design-Tokens (Farben, Typografie, Abstände,
  Radien, Schatten) statt verstreuter Inline-Styles.
- **Beschreibung:** CSS-Variablen (Light + Dark), zentrale Status-Farben
  (einsatzbereit/eingeschränkt/nicht einsatzbereit/unbekannt), Basis-Komponenten
  (Button, Card, Input, Badge, Table) vereinheitlicht.
- **Benutzerwert:** Konsistentes, hochwertiges Erscheinungsbild in der ganzen App.
- **Abhängigkeiten:** keine
- **Backend:** keins
- **Frontend:** `styles/tokens.css`, überarbeitetes `global.css`, Dark-Mode via
  `prefers-color-scheme` + manuellem Umschalter
- **Mobile:** Basis für alle Folge-Kacheln
- **Rechte:** keine Änderung
- **Akzeptanzkriterien:** Dark Mode umschaltbar, alle Basis-Elemente nutzen Tokens
  statt Hardcoded-Werten.
- **Tests:** keine (reines Styling), visuelle Kontrolle.
- **DoD:** offen — noch nicht begonnen.

## UI-002 — App-Shell & Navigation

- **Ziel:** Moderne Sidebar (Desktop) / kompakte Navigation (Mobile) statt
  bisheriger einfacher Navigation in `AppShell.tsx`.
- **Beschreibung:** Bereiche Dashboard/Objekte/Fahrzeuge/Material/Lager/
  Kontrollen/Prüfungen/Mängel/Personal/Administration. Globale Suche `Ctrl/⌘+K`.
  Quick Actions (QR scannen, Kontrolle starten, Mangel melden, Material buchen).
- **Benutzerwert:** Schnelle Orientierung, weniger Klicks zu Kernaktionen.
- **Abhängigkeiten:** UI-001
- **Backend:** keins (Suche client-seitig über bereits geladene Objekt-/Material-Listen,
  kein neuer Such-Endpunkt in Phase 1)
- **Frontend:** `AppShell.tsx` umgebaut, neue `CommandPalette`-Komponente
- **Mobile:** Bottom-Navigation oder Drawer statt Sidebar
- **Rechte:** Navigationspunkte nach Rolle gefiltert (bereits vorhandene Rollen-Logik
  wiederverwenden)
- **Akzeptanzkriterien:** alle bestehenden Routen weiter erreichbar, Suche findet
  Objekte per Name/Code.
- **Tests:** keine neuen (reines Routing/UI).
- **DoD:** umgesetzt (2026-09-06). Sidebar/Mobile-Nav blieb wie in UI-001 vorgefunden
  (bereits responsiv), stattdessen: `CommandPalette` (Strg/⌘+K, auch per Button
  "🔍 Suche" erreichbar) mit Objekt-Suche (Name/Code) + Quick Actions
  (QR scannen → `/objekte?scan=1`, Material/Lager/Personal/Verwaltung).
  `AdminPage`-Tab jetzt in der URL (`?tab=...`) statt nur lokalem State, damit
  die Palette gezielt auf einen Tab verlinken kann - keine Routen-Duplizierung.
  "Fahrzeuge/Kontrollen/Prüfungen" bekamen bewusst keine eigenen Nav-Punkte:
  es gibt dafür keine eigenständigen Listen-Seiten in MABEA (Fahrzeuge sind ein
  Objekttyp unter "Objekte", Kontrolle/Prüfung laufen objektbezogen über die
  Akte) - ein Nav-Punkt ohne Zielseite wäre Fake-Navigation.

## UI-003 — Zentrale Statuskomponenten

- **Ziel:** Wiederverwendbare Status-Anzeigen statt an mehreren Stellen dupliziertem
  Badge-Markup.
- **Beschreibung:** `ReadinessBadge` (einsatzbereit/eingeschränkt/nicht
  einsatzbereit/unbekannt — „unbekannt" NIE als einsatzbereit darstellen),
  `SyncStatus` (online/offline/synchronisiert), `InspectionStatus`,
  `InventoryStatus`. Jede Komponente kapselt Farbe+Icon+Text an einer Stelle.
- **Benutzerwert:** Konsistente, sofort verständliche Statusdarstellung überall.
- **Abhängigkeiten:** UI-001
- **Backend:** keins
- **Frontend:** `components/status/ReadinessBadge.tsx` etc., bestehende Ad-hoc-Badges
  (`DashboardPage.tsx`, `AktePage.tsx`, `ObjektListPage.tsx`) darauf umgestellt
- **Rechte:** keine Änderung
- **Akzeptanzkriterien:** kein Status mehr als Inline-`<span className="badge...">`
  dupliziert.
- **Tests:** ggf. kleiner Komponententest je Status-Mapping.
- **DoD:** umgesetzt (2026-09-06). `components/status/ReadinessBadge.tsx`
  (ready/limited/not-ready/unknown, eigene Farben/Icons, "unbekannt" sieht nie
  wie "einsatzbereit" aus), `FristBadge.tsx` als gemeinsame Basis für
  `InspectionStatus.tsx`/`InventoryStatus.tsx` (beide Backend-Endpunkte liefern
  dieselben zwei Fristzustände), `SyncStatus.tsx` neu in `AppShell` verdrahtet
  - Online/Offline/Queue-Länge war zuvor NIRGENDS sichtbar, obwohl
    `useOnlineStatus`/Offline-Queue seit Prompt 17 existieren. In `DashboardPage`
  eingesetzt (Einsatzbereitschaft-Chips, Prüftermine, Ablaufdaten).
  `objekt.status` (aktiv/ausser_dienst/in_wartung, ObjektListPage/AktePage)
  bewusst NICHT auf ReadinessBadge umgestellt - anderes Konzept
  (Objekt-Lebenszyklus statt Einsatzbereitschaft), Vermischung wäre fachlich
  falsch. Echte Einsatzbereitschaft pro Objekt (mit Begründung) kommt in UI-005.

## UI-004 — Dashboard neu

- **Ziel:** „Was ist einsatzbereit und was muss ich jetzt tun?" in 5 Sekunden
  beantwortbar.
- **Beschreibung:** Einsatzbereitschaft-Übersicht (einsatzbereit/eingeschränkt/
  nicht einsatzbereit/unbekannt), offene Mängel, fällige Kontrollen/Prüfungen,
  fehlendes Material, aktuelle Aufgaben — alles aus bereits vorhandenen
  Dashboard-/Fehlbestand-/Mangel-Endpunkten, keine Fake-Daten.
- **Benutzerwert:** Kernversprechen der Kachel — sofortiger Überblick.
- **Abhängigkeiten:** UI-001, UI-003
- **Backend:** keins zusätzlich (bestehende Dashboard-Kennzahlen wiederverwenden)
- **Frontend:** `DashboardPage.tsx` neu strukturiert, Card-Grid statt Liste
- **Mobile:** gestapeltes Layout
- **Rechte:** keine Änderung
- **Akzeptanzkriterien:** alle geforderten Kennzahlen sichtbar, keine Platzhalter-/
  Fake-Werte.
- **Tests:** bestehende Dashboard-Tests bleiben grün.
- **DoD:** umgesetzt (2026-09-06). Neue Karte "Was ist jetzt zu tun?" ganz oben
  (volle Breite), fasst offene Fehlbestände/kritische Mängel/überfällige
  Prüfungen/abgelaufene Chargen/nie kontrollierte Objekte aus bereits
  geladenen Daten zusammen, mit Direktlinks - keine neuen Endpunkte, keine
  Fake-Daten. Leerzustand "✅ Nichts Dringendes offen." statt leerer Karte.
  Restliche Karten (Einsatzbereitschaft mit ReadinessBadge-Chips aus UI-003,
  Prüftermine/Ablaufdaten mit InspectionStatus/InventoryStatus, Kennzahlen,
  Mängel, Qualifikationsablauf) bleiben als Card-Grid bestehen. Nebenbei
  behobene Vorab-Lücke: `.text-success`/`.text-danger` fehlten in
  `global.css`, obwohl in `AktePage.tsx` bereits referenziert.

## UI-005 — Objektakte modernisiert

- **Ziel:** `AktePage.tsx` (bereits FILE-006/Akte-Aggregation) optisch/strukturell
  aufwerten, inkl. begründeter Einsatzbereitschafts-Anzeige.
- **Beschreibung:** Status mit Begründung (z. B. „🔴 Nicht einsatzbereit — Funkgerät
  defekt, 2 Beladungspositionen fehlen, Prüfung überfällig"), Tabs oder klar
  getrennte Bereiche für Beladung/Kontrollen/Mängel/Prüfungen/Wartungen/
  Dokumente/Historie.
- **Benutzerwert:** Sofort verständlich, WARUM ein Objekt nicht einsatzbereit ist.
- **Abhängigkeiten:** UI-001, UI-003
- **Backend:** ggf. kleine Ergänzung am `/akte/objekt/{id}`-Endpunkt, falls die
  Begründungs-Texte nicht schon aus den Einzelfeldern ableitbar sind (prüfen vor
  Umsetzung)
- **Frontend:** `AktePage.tsx` Umbau, bisherige 6 gleichartigen Card-Blöcke
  (bereits als Simplification-Fund dokumentiert) auf gemeinsame Komponente
  vereinheitlichen
- **Rechte:** keine Änderung
- **Akzeptanzkriterien:** „unbekannt/nie kontrolliert" wird nie als einsatzbereit
  dargestellt (harte Regel, Akzeptanzkriterium testbar).
- **Tests:** Begründungslogik testen (welche Bedingungen führen zu welchem Status).
- **DoD:** umgesetzt (2026-09-06). Backend: `objekt_readiness()` in
  `app/services/dashboard.py` - Fallunterscheidung aus `einsatzbereitschaft()`
  in `_kategorie_und_gruende()` extrahiert, keine Duplizierung, für ein
  einzelnes Objekt statt aller. Neue Felder `einsatzbereitschaft_status`/
  `einsatzbereitschaft_gruende` an `/akte/objekt/{id}`. Frontend:
  `ReadinessBadge` + Gründeliste (gemeinsames `GRUND_TEXT`-Mapping mit
  Dashboard) statt des rohen `objekt.status`-Badges - Objekt-Lebenszyklus-
  Status (aktiv/ausser_dienst/in_wartung) bleibt separat als Text sichtbar,
  keine Vermischung. Getestet: kritischer Mangel -> "not-ready", nie
  kontrolliert ohne sonstige Auffälligkeit -> "unknown" (nie "ready").
  Nebenbei (Nutzer-Nachfrage): Dokumente in der Akte waren bisher nur Text
  ohne jede Interaktion - jetzt `DokumentePanel` eingebunden (Upload/Liste/
  Löschen wie in Mängel/Admin), plus neuer "Ansehen"-Klick (`ladeDokumentAnsehen`
  öffnet PDF/Bild im neuen Tab) zusätzlich zum bisherigen Zwangs-Download.

## UI-006 — Kontrolle & Beladung modernisiert

- **Ziel:** Bestehenden Kontrollworkflow (QR/Objekt → Kontrolle starten → Position
  prüfen → OK/Abweichung → speichern → Abschluss) beibehalten, Fortschritt
  (`38 / 40 geprüft`) und fehlerhafte Positionen visuell hervorheben.
- **Benutzerwert:** Schnellere, fehlerfreiere Kontrolle vor Ort.
- **Abhängigkeiten:** UI-001, UI-003
- **Backend:** keins
- **Frontend:** `KontrollPage.tsx` + `pages/kontrolle/*` Fortschrittsanzeige,
  hervorgehobene Abweichungen
- **Mobile:** Priorität — Haupteinsatzort dieses Screens
- **Rechte:** keine Änderung
- **Akzeptanzkriterien:** Fortschritt live sichtbar, Abweichungen nicht zu übersehen.
- **Tests:** bestehende Kontroll-Tests bleiben grün.
- **DoD:** umgesetzt (2026-09-06). Fortschrittsanzeige ("X von Y Positionen
  bestätigt" + Balken) existierte bereits. Neu: `PositionCard` bekommt eine
  farbige linke Randlinie je Zustand (grün = passt & gespeichert, gelb =
  Abweichung/Fehlbestand, rot = Übertragungsfehler) - Abweichung war bisher nur
  während des kurz offenen Nachfüll-Dialogs sichtbar, danach nicht mehr von
  einer normalen Bestätigung zu unterscheiden. Nebenbei: hartkodierte Hex-
  Fallbackfarben (`var(--color-x, #hex)`, aus der Zeit vor UI-001) durch reine
  Token-Referenzen ersetzt.

## UI-007 — QR-Scan-Aktionsleiste

- **Ziel:** Nach Scan direkt Aktionen anbieten (Kontrolle starten/Mangel melden/
  Informationen), nicht nur Direkt-Navigation.
- **Beschreibung:** Baut auf MOBILE-002-Fix (Scan → Akte) auf, ergänzt auf der
  Akte-Seite eine hervorgehobene Aktionsleiste statt nur einem Button.
- **Benutzerwert:** Weniger Klicks nach dem Scan.
- **Abhängigkeiten:** UI-005, MOBILE-002 (bereits erledigt)
- **Backend:** keins
- **Frontend:** Aktionsleiste in `AktePage.tsx`
- **Rechte:** je Aktion bestehende Rollenprüfung wiederverwenden
- **Akzeptanzkriterien:** alle drei Aktionen von der Akte aus erreichbar.
- **Tests:** keine neuen.
- **DoD:** offen.

## UI-008 — Restliche Module (Material, Lager, Personal, Administration)

- **Ziel:** Verbleibende Seiten im neuen Designsystem angleichen.
- **Beschreibung:** Admin-Tabs (`LagerSection.tsx` u.a.), `MangelListePage.tsx`,
  `FehlbestandListePage.tsx` auf Tokens/Statuskomponenten umstellen.
- **Benutzerwert:** Durchgängiges Erscheinungsbild, keine Stilbrüche.
- **Abhängigkeiten:** UI-001..003
- **Backend:** keins
- **Frontend:** verbleibende Seiten
- **Rechte:** keine Änderung
- **Akzeptanzkriterien:** keine Seite mehr im alten Stil.
- **Tests:** bestehende Tests bleiben grün.
- **DoD:** offen.

---

**Reihenfolge (zwingend, laut Vorgabe):** UI-001 → UI-002 → UI-003 → UI-004 → UI-005
→ UI-006 → UI-007 → UI-008. Jede Stufe wird einzeln abgeschlossen und bestätigt,
bevor die nächste beginnt (Arbeitskacheln-Methodik: kein Direktcoden ohne Freigabe
je Schritt).

**Nicht-Ziele:** kein Framework-Wechsel, keine Breaking Changes an API/Fachlogik,
keine Fake-Daten, Offline/PWA/IndexedDB-Sync bleibt unangetastet, bestehende Tests
bleiben grün und werden erweitert wo sinnvoll.

**WCAG 2.2 AA:** als Leitplanke bei UI-001 (Kontraste/Fokus-Stile) und UI-002
(Tastaturbedienung Command Palette) mitgedacht, kein separater Prüf-Task.

## Referenzen
Externer Redesign-Prompt, vom Nutzer am 2026-09-06 eingebracht (kompakte Version
für Coding-KI, Zielrepo MABEA).