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.