# 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 `Authorization: Bearer <token>`.
- 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]]