MABEA/arbeitskacheln/01_foundation.md

Epic 01 — Foundation

Details zu FOUND-001 … FOUND-006. Ü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.

---

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.