Initiale fachliche Konzeption MABEA (Prompts 01-23, Arbeitskarten 01-13)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L85hmKbvX7Cqkq47KnQhFt

ergebnisse/21_api.md

@@ -0,0 +1,107 @@
+# 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 → 422 oder Warnung (fachlich zu entscheiden bei Umsetzung, aus Prompt 02 nicht explizit als Fehler definiert – konservativ: erlauben, aber als „Überbestand“-Info kennzeichnen, kein Fehlbestand).
+- 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]]