MABEA/arbeitskacheln/01_foundation.md

Epic 01 — Foundation

Details zu FOUND-001 … FOUND-008. FOUND-007/008 ergänzt am 2026-09-09 aus HiOrg-Server-Vergleich, offen/ungeplant. Übersichtstabelle mit allen FOUND-Kacheln (auch die noch nicht detaillierten) siehe 00_index.md.

---

FOUND-001 — Repo & Projektstruktur

• Modul: Foundation
• Ziel: Einheitliche, nachvollziehbare Code-Basis, auf der alle weiteren Kacheln aufbauen.
• Beschreibung: Verzeichnisstruktur Backend/Frontend, Namenskonventionen, Formatierungs-/Lint-Regeln, Basis-README.
• Benutzerwert: Keiner direkt (Entwickler-Infrastruktur), aber Voraussetzung für alles.
• Abhängigkeiten: keine
• Datenmodell: keins
• Backend: Grundgerüst (App-Einstiegspunkt, Router-Registrierung leer)
• Frontend: Grundgerüst (Build-Tooling, leere Startseite)
• Mobile: noch nicht relevant
• QR-Code: nein
• Seriennummer: nein
• Inventarnummer: nein
• Akte: nein
• Rechte: keine (noch kein Auth)
• Audit: nein
• Akzeptanzkriterien: Repo klont sich, Backend startet, Frontend baut, Lint läuft ohne Fehler.
• Tests: Smoke-Test „App startet"
• DoD: lauffähiges leeres Grundgerüst, dokumentiert im README.

FOUND-002 — DB-Grundgerüst + Migrationen

• Ziel: Versionierte, reproduzierbare Datenbankstruktur.
• Beschreibung: PostgreSQL-Anbindung, Migrationstool (z.B. Alembic), erste leere Migration.
• Benutzerwert: indirekt (Datenintegrität/Nachvollziehbarkeit für alle Module).
• Abhängigkeiten: FOUND-001
• Datenmodell: Migrations-Metatabelle (vom Tool selbst verwaltet)
• Backend: DB-Session-Handling, Connection-Pool
• Frontend: —
• Mobile: —
• QR-Code / Seriennummer / Inventarnummer / Akte: nein
• Rechte: keine
• Audit: nein
• Akzeptanzkriterien: Migration lässt sich anwenden und zurückrollen, DB-Verbindung aus App funktioniert.
• Tests: Migrations-Up/Down-Test gegen Testdatenbank.
• DoD: Migration reproduzierbar auf frischer DB, CI führt sie aus.

FOUND-003 — Authentication

• Ziel: Sichere Anmeldung als Basis für jede weitere Rechteprüfung.
• Beschreibung: Login mit Passwort (gehashed), Token-Ausgabe (JWT o.ä.), Token-Validierung.
• Benutzerwert: Jeder Nutzer kann sich anmelden — Grundvoraussetzung für alles Weitere.
• Abhängigkeiten: FOUND-002
• Datenmodell: benutzer (login, passwort_hash, aktiv)
• Backend: POST /auth/login, Token-Decode-Dependency
• Frontend: Login-Seite
• Mobile: gleicher Login-Flow
• QR-Code/Seriennummer/Inventarnummer: nein
• Akte: nein
• Rechte: noch keine Rollen, nur „angemeldet/nicht angemeldet"
• Audit: Login-Fehlversuche protokollieren (Brute-Force-Erkennung, optional P2)
• Akzeptanzkriterien: korrektes Passwort → Token; falsches Passwort → 401; abgelaufener Token → 401.
• Tests: Login erfolgreich/fehlgeschlagen, Token-Ablauf.
• DoD: Login funktioniert clientseitig und serverseitig, Passwort niemals im Klartext gespeichert/geloggt.

FOUND-004 — Authorization-Grundgerüst

• Ziel: Zentrale Stelle, an der jeder Endpunkt Rechte prüfen kann.
• Beschreibung: Rollen-Modell (fest, kein granulares System — das kommt erst in Personnel/Readiness-Phase oder eigener späterer Kachel), Dependency/Middleware für Rollenprüfung.
• Benutzerwert: Schützt sensible Aktionen (z.B. nur Materialwart darf Material anlegen).
• Abhängigkeiten: FOUND-003
• Datenmodell: rolle, benutzer_rolle
• Backend: require_roles()-Dependency
• Frontend: Rollenbasiertes Ein-/Ausblenden von UI-Elementen
• Mobile: gleiches Prinzip
• Akte/QR/SN/Inv: nein
• Rechte: dies IST das Rechte-Grundgerüst
• Audit: Rollenänderungen protokollieren
• Akzeptanzkriterien: Endpunkt ohne passende Rolle → 403; mit passender Rolle → 200.
• Tests: je Rolle ein Zugriffstest.
• DoD: mind. 2 Rollen (z.B. Administrator, Helfer) funktionieren nachweisbar unterschiedlich.

FOUND-005 — API-Grundgerüst

• Ziel: Konsistente API für alle künftigen Module.
• Beschreibung: Einheitliches Fehlerformat, Versionierungs-Präfix (/api/v1), OpenAPI-Dokumentation automatisch.
• Benutzerwert: indirekt — konsistente, vorhersehbare API für Frontend/Mobile/ Drittsysteme.
• Abhängigkeiten: FOUND-002
• Datenmodell: keins
• Backend: Fehler-Handler, Health-Endpoint
• Frontend: generischer API-Client mit einheitlicher Fehlerbehandlung
• Mobile: gleicher Client
• Akte/QR/SN/Inv: nein
• Rechte: keine (Health-Endpoint öffentlich)
• Audit: nein
• Akzeptanzkriterien: /health antwortet 200, ein absichtlich provozierter Fehler liefert einheitliches JSON-Fehlerformat.
• Tests: Health-Check-Test, Fehlerformat-Test.
• DoD: OpenAPI-Doku ist unter /docs erreichbar.

FOUND-006 — Logging & Audit-Grundgerüst

• Ziel: Jede sicherheits-/fachlich relevante Aktion muss später nachvollziehbar sein.
• Beschreibung: Zentrale Audit-Tabelle (append-only), generische Log-Funktion (wer/wann/was/alter Wert/neuer Wert).
• Benutzerwert: Nachvollziehbarkeit für Zugführer/Administrator, Vertrauenswürdigkeit des Systems.
• Abhängigkeiten: FOUND-002
• Datenmodell: audit_log (id, zeitpunkt, benutzer_id, ereignistyp, entitaet_typ, entitaet_id, alter_wert, neuer_wert)
• Backend: log()-Service-Funktion, von anderen Modulen aufrufbar
• Frontend: Änderungslog-Ansicht (rudimentär, volle UI evtl. später eigene Kachel)
• Mobile: —
• Akte/QR/SN/Inv: nein direkt, aber Grundlage für FILE-005/007
• Rechte: Lesen nur privilegierte Rollen
• Audit: ist selbst das Audit-System
• Akzeptanzkriterien: eine Testaktion erzeugt einen Log-Eintrag mit korrektem Vorher/Nachher-Wert.
• Tests: Log-Eintrag wird bei simulierter Aktion erzeugt und ist abrufbar.
• DoD: mind. ein reales Ereignis (z.B. Login) wird bereits geloggt.

FOUND-007 — CSV/XLS-Import/Export für Objekt- und Materialstammdaten (P2, neu,

Scope geklärt 2026-09-09)

• Ziel: Massenpflege von Objekt- UND Materialstammdaten statt Einzelanlage per UI.
• Scope (entschieden 2026-09-09): beide Ebenen — Objekt (Behälter-Stammdaten: Rucksack/Fahrzeug/Standort) UND GeraetInstanz (Einzelgeräte mit Seriennummer darin). Passt zum Ursprungsfall Excel-Rucksackliste, wo beide Ebenen typischerweise in einer Tabelle stehen.
• Beschreibung: Export bestehender Objekte+Geräteinstanzen als CSV, Import mit Validierung (Duplikat-Erkennung über Inventarnummer/Seriennummer, Fehlerliste bei ungültigen Zeilen statt Alles-oder-Nichts-Abbruch). Ein Import-Vorgang kann beide Ebenen in einer Datei abdecken (verschachtelte Struktur: Objekt-Zeile + zugehörige Geräte-Zeilen) oder zwei getrennte Dateien — Implementierungsdetail, nicht mehr Scope-Frage.
• Benutzerwert: Direkter Nutzen für den Ursprungsfall von MABEA — Migration bestehender Excel-Rucksacklisten in Massenpflege statt Zeile für Zeile manuell nacherfassen, inklusive der darin enthaltenen Einzelgeräte.
• Abhängigkeiten: ASSET-003, GeraetInstanz-Modell
• Datenmodell: keins neu (nutzt bestehende Objekt-/GeraetInstanz-Tabellen)
• Backend: POST /objekte/import + POST /geraete/import (oder kombinierter Endpunkt, je nach gewählter Dateistruktur), jeweils Dry-Run-Modus + Commit-Modus; GET /objekte/export + GET /geraete/export
• Frontend: Upload-Dialog mit Fehlerliste-Anzeige vor endgültigem Import, Export-Button in Objektliste UND Geräte-/Materialansicht
• Mobile: nein (Desktop-Verwaltungsaufgabe)
• QR-Code/Seriennummer/Inventarnummer: Duplikat-Prüfung läuft darüber
• Akte: nein direkt
• Rechte: Administrator/Materialverantwortlicher
• Audit: Import als Sammel-Ereignis geloggt (nicht jede Zeile einzeln)
• Akzeptanzkriterien: Import mit teilweise fehlerhaften Zeilen zeigt genau welche Zeilen fehlschlugen, gültige Zeilen werden trotzdem übernommen (kein Alles-oder- Nichts); Export re-importierbar (Round-Trip-Test), sowohl für Objekte als auch für Geräteinstanzen; Geräte-Zeilen ohne zugehöriges Objekt werden abgelehnt (referenzielle Konsistenz).
• Tests: Round-Trip-Test (Export→Import ergibt identischen Bestand) für beide Ebenen, Fehlerzeilen-Test (gemischt gültig/ungültig), Test für Objekt+zugehörige-Geräte in einem Import-Vorgang.
• DoD: offen. Referenz (HiOrg-Server-Vergleich 2026-09-09): HiOrg bietet Import/Export für praktisch alle Datentypen (CSV/XLS/vCard/iCal) — MABEA hat dafür aktuell keinen erkennbaren Mechanismus außer direkter API-Nutzung.

FOUND-008 — Generischer Fristen-Dienst (P3, neu, Schnittstelle geklärt 2026-09-09)

• Ziel: EINE Berechnungslogik für „läuft etwas bald ab/wird etwas bald fällig" statt mehrfach separat implementiert.
• Beschreibung: MABEA hat Ablauf-/Fälligkeitslogik aktuell an drei Stellen unabhängig voneinander gebaut: Chargen-Ablaufdatum (INV-005), Qualifikations- Ablaufwarnung (PERS-007), Wartungsfälligkeit (MAINT-002/NOTIF-003). Ein gemeinsamer Fristen-Dienst (Interface: „gib mir alle Objekte mit Frist-Typ X, die den Dringlichkeitsgrad Y erreicht haben" — siehe Schnittstelle unten) würde die Berechnungslogik einmal statt dreimal pflegen.
• Benutzerwert: Kein direkter Nutzerwert (reines Refactoring), aber weniger Wartungsaufwand/Inkonsistenz-Risiko bei künftigen Fristen-Arten (z.B. Vertrags- laufzeiten, TÜV-Termine).
• Abhängigkeiten: INV-005, PERS-007, MAINT-002 (bestehende Implementierungen als Migrationsbasis)
• Datenmodell: keins neu, gemeinsame FristTyp-Enum als Kategorisierung (charge_ablauf/qualifikation_ablauf/wartung_faellig/...)
• Schnittstelle (entschieden 2026-09-09, korrigiert 2026-09-10): „Tage bis fällig" als gemeinsamer Nenner funktioniert NICHT für km/Betriebsstunden-Fristen — MABEA verfolgt keine Verbrauchsrate über Zeit (nur den aktuellen Zählerstand), eine Tage-Schätzung wäre erfunden/unbegründet. Stattdessen: gemeinsame FristTreffer-Struktur mit Dringlichkeits-Ampel statt einheitlicher Zeiteinheit — {objekt_id, frist_typ, bezeichnung, dringlichkeit: enum (ok/bald/kritisch/ueberfaellig), rest_anzeige: str}. rest_anzeige bleibt je Typ in seiner nativen Einheit (z.B. „in 12 Tagen" bei Datum-Fristen, „noch 340 km" bei Kilometer-Fristen, „noch 15 Bh" bei Betriebsstunden) — nur die Ampel-Einstufung (ok/bald/kritisch/überfällig) ist typübergreifend einheitlich vergleichbar, die Restanzeige selbst bleibt nativ und ehrlich statt einer erfundenen Tage-Umrechnung. Jede der drei Implementierungen bringt ihre eigene Schwellenwert-Logik mit (z.B. „< 10% der Sollstrecke übrig" = kritisch bei km), fristen.py normalisiert nur auf die gemeinsame Ampel, nicht auf eine gemeinsame Zeiteinheit.
• Backend: app/services/fristen.py als gemeinsame Schnittstelle, bestehende drei Implementierungen (app/services/dashboard.py, app/services/akte.py, app/services/personal.py, app/services/wartung.py:faellige_wartungen_fuer_objekt) schrittweise darauf umstellen (nicht big-bang) — jede liefert intern weiter ihre Rohdaten, fristen.py übernimmt nur die Normalisierung auf FristTreffer.
• Frontend: keine Änderung sichtbar (reines Backend-Refactoring)
• Mobile: keins
• QR-Code/Seriennummer/Inventarnummer: nein
• Akte: nein direkt
• Rechte: keine Änderung
• Audit: keine Änderung
• Akzeptanzkriterien: alle drei bestehenden Fristen-Arten liefern nach Umstellung identische Ergebnisse wie vorher (Regressionstest), neue Fristen-Art ohne Duplikation der Kernlogik hinzufügbar.
• Tests: Regressionstests der drei bestehenden Fristen-Berechnungen gegen die neue gemeinsame Implementierung.
• DoD: offen, P3 — reines Refactoring, kein MVP-Bestandteil. Schnittstelle geklärt (2026-09-09), bereit für Implementierung. Referenz (HiOrg-Server-Vergleich 2026-09-09): HiOrg berücksichtigt Qualifikations-Ablauf generisch bei der Diensteinteilung — technische Entsprechung wäre bei MABEA ein gemeinsamer Fristen-Mechanismus statt drei getrennter Implementierungen.

---

MABEA-Ist-Stand-Abgleich: FOUND-001…006 sind in MABEA vollständig vorhanden (FastAPI-Grundgerüst, Alembic-Migrationen, JWT-Login, require_roles()-Dependency, einheitliches Fehlerformat + /docs, historie-Tabelle als Audit-Log). FOUND-007…012 (Konfiguration/Docker/CI/Backup/Tests/Doku) ebenfalls größtenteils vorhanden (app_settings.py, .env, Gitea-CI ci.yml, pytest, README/DEVLOG) — kein Nachholbedarf in diesem Epic.