108 lines
6.7 KiB
Markdown
108 lines
6.7 KiB
Markdown
# 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]]
|