MABEA/ergebnisse/21_api.md

Prompt 21 – API-Konzept

Bezug: 19_technische_architektur, 20_datenbank_schema, 05_rollen_rechte. Basis: FastAPI, REST, API-first (Web-PWA + spätere native App als Clients).

1. Grundprinzipien

• REST, JSON, versioniert unter /api/v1/....
• Auth: Login liefert Token (JWT), jede weitere Anfrage mit Header Authorization: Bearer gefolgt vom Token-String.
• Jede Route deklariert benötigte Rolle(n) (Prompt 05) über FastAPI-Dependency, zentral geprüft.
• Fehlerformat einheitlich: { "error": { "code": "...", "message": "..." } }, HTTP-Status passend (400/401/403/404/409/422).
• Historieneinträge (Prompt 13) werden serverseitig automatisch bei jeder relevanten Statusänderung erzeugt, nicht über eigene API-Aufrufe des Clients.

2. Auth

Methode	Pfad	Rolle	Zweck
POST	/api/v1/auth/login	-	Login (Login-Name+Passwort/PIN), liefert Token
POST	/api/v1/auth/logout	alle	Token invalidieren
GET	/api/v1/auth/me	alle	eigene Benutzerdaten+Rollen

3. Stammdaten (Ressourcen)

Methode	Pfad	Rolle	Zweck
GET/POST	/api/v1/bereiche	Administration (POST), alle (GET)	Bereiche
GET/POST	/api/v1/kategorien	Administration (POST), alle (GET)	Kategorien
GET/POST	/api/v1/standorte	Administration (POST), alle (GET)	Standorte
GET/POST	/api/v1/objekttypen	Administration (POST), alle (GET)	Objekttypen
GET/POST/PATCH	/api/v1/materialien	Administration	Materialstamm (Prompt 07)
GET	/api/v1/materialien/{id}	alle	Detail

4. Beladungsvorlagen

Methode	Pfad	Rolle	Zweck
GET	/api/v1/vorlagen	alle	Liste, filterbar nach Objekttyp/Status
POST	/api/v1/vorlagen	Administration, Materialverantwortlicher	neue Vorlage/Version anlegen (Prompt 08)
GET	/api/v1/vorlagen/{id}	alle	Detail inkl. Positionen
POST	/api/v1/vorlagen/{id}/positionen	Administration, Materialverantwortlicher	Position hinzufügen
PATCH	/api/v1/vorlagen/{id}/positionen/{pos_id}	Administration, Materialverantwortlicher	Sollmenge ändern (führt zu neuer Version, Prompt 08)
GET	/api/v1/vorlagen/{id}/diff-vorschlaege	Materialverantwortlicher, Leitung	Diff zu bestehenden Objekten (Prompt 08 Punkt 6)

5. Objekte

Methode	Pfad	Rolle	Zweck
GET	/api/v1/objekte	alle	Liste, Filter Standort/Typ, Suche nach Code
GET	/api/v1/objekte/{id}	alle	Detail inkl. Objektpositionen
GET	/api/v1/objekte/code/{code}	alle	Lookup per QR/Barcode-Code (Karte 10) — Route muss in FastAPI VOR /objekte/{id} registriert werden, sonst greift die generische ID-Route zuerst
POST	/api/v1/objekte	Administration	neu anlegen
POST	/api/v1/objekte/{id}/duplizieren	Administration	Duplizieren (Prompt 09), Body: neuer Name/Code/Standort
PATCH	/api/v1/objekte/{id}/positionen/{pos_id}	Materialverantwortlicher	Sollmengen-Override/Material hinzufügen/entfernen (Prompt 10)

6. Kontrolle

Methode	Pfad	Rolle	Zweck
POST	/api/v1/objekte/{id}/kontrollen	Mitarbeiter+	Kontrolle starten (Prompt 02)
GET	/api/v1/kontrollen/{id}	Mitarbeiter+	Status/Fortschritt
PUT	/api/v1/kontrollen/{id}/positionen/{material_id}	Mitarbeiter+	Ist-Menge erfassen/bestätigen (idempotent, wichtig für Prompt 17 Wiederholung nach Netzausfall)
POST	/api/v1/kontrollen/{id}/abschliessen	Mitarbeiter+	Abschluss (Prompt 16), löst Kontrollnachweis aus
POST	/api/v1/kontrollen/{id}/abbrechen	Mitarbeiter+	Abbruch (Prompt 16), optional Grund im Body

7. Fehlbestand / Nachfüllung / Mindermenge

Methode	Pfad	Rolle	Zweck
GET	/api/v1/fehlbestaende	Materialverantwortlicher, Leitung, Administration	Liste, Filter Standort/Objekt/Material/Alter/Status (Prompt 12)
GET	/api/v1/fehlbestaende/{id}	s.o. + Mitarbeiter (eigene)	Detail inkl. Historie
POST	/api/v1/fehlbestaende/{id}/nachfuellungen	Mitarbeiter+	Nachfüllung erfassen (Prompt 02), aktualisiert Fehlmenge/Status automatisch
POST	/api/v1/fehlbestaende/{id}/mindermenge	Materialverantwortlicher, Leitung	Mindermenge genehmigen, Body: Begründung (Prompt 04)
DELETE	/api/v1/fehlbestaende/{id}/mindermenge	-	NICHT vorgesehen – Genehmigung läuft nur automatisch ab (Prompt 04), kein manuelles Löschen

7a. Verwaltung (Administration) – ergänzt nach Gesamtprüfung

Fehlte bisher, obwohl in der Berechtigungsmatrix (Prompt 05) gefordert.

Methode	Pfad	Rolle	Zweck
GET/POST	/api/v1/benutzer	Administration	Benutzer verwalten
PATCH	/api/v1/benutzer/{id}	Administration	Rollen zuweisen, aktiv/inaktiv setzen
GET/POST	/api/v1/zustaendigkeiten	Administration	Zuständigkeits-Zuordnung (Karte 04)
DELETE	/api/v1/zustaendigkeiten/{id}	Administration	Zuordnung entfernen
GET/POST	/api/v1/kontrollverantwortung	Administration, Materialverantwortlicher (eigener Bereich)	Kontrollverantwortung zuweisen (Karte 01)
GET/POST	/api/v1/systemknoten	Administration	Satelliten-Server anlegen/verwalten (Karte 13)
POST	/api/v1/objekte/{id}/auslagern	Administration	Objekt einem Satelliten zuordnen
POST	/api/v1/objekte/{id}/zurueckholen	Administration	Rücksynchronisation anstoßen, Zuordnung zurück auf Hauptserver

8. Dashboard/Historie

Methode	Pfad	Rolle	Zweck
GET	/api/v1/dashboard/kennzahlen	Materialverantwortlicher, Leitung, Administration	Kennzahlen (Prompt 12)
GET	/api/v1/dashboard/ablaufdaten	s.o.	bevorstehende Ablaufdaten (Prompt 14)
GET	/api/v1/historie	s.o. (gefiltert nach Zuständigkeit)	globale Audit-Suche (Prompt 13)
GET	/api/v1/objekte/{id}/historie	alle (eigene Objekte)	objektbezogene Historie

9. Validierung/Fehlerfälle (Beispiele)

• Mindermenge genehmigen ohne Begründung → 422, Feld begruendung Pflicht (Prompt 04).
• Mindermenge genehmigen durch Mitarbeiter-Rolle → 403 (Prompt 05).
• Nachfüllung mit Menge, die Ist über Soll hebt → entschieden: erlauben (kein 422), Response kennzeichnet den Fall als „Überbestand"-Info (Prompt 02.4), löst keinen Fehlbestand aus.
• Kontrolle abschließen, obwohl Positionen unbearbeitet → 409, Liste fehlender Positionen im Response.
• Doppeltes Duplizieren mit gleichem Code → 409 (Code muss eindeutig sein, Prompt 09).

10. Auditierung auf API-Ebene

• Jede schreibende Aktion protokolliert automatisch Server-Zeitstempel + Benutzer-ID aus Token (nie Client-Wert) in historie (Prompt 13/20).

Referenzen

Bezug: 19_technische_architektur, 20_datenbank_schema, 05_rollen_rechte