EW-Sys API

Backend-API für EW-Sys auf Basis von FastAPI, SQLModel und PostgreSQL. Die Anwendung bildet Authentifizierung, Benutzerverwaltung sowie CRUD-Endpunkte für Artikel, Hersteller, Projekte, Anfragen und Rückfragen ab.

Überblick

• JWT-basierte Authentifizierung mit Access- und Refresh-Token
• Invite-Flow für neue Benutzer und Passwort-Reset durch Manager
• Rollen- und gruppenbasierte Zugriffssteuerung
• CRUD-Endpunkte für Benutzer, Artikel, Hersteller, Projekte, Anfragen und Rückfragen
• PDF-Anhänge für Anfragen
• QR-Code-Erzeugung für Artikel
• Status-Endpunkt mit Datenbank-Check und Uptime
• Swagger UI mit eigener Darkmode-CSS

Technologie-Stack

• Python 3.10+
• FastAPI
• SQLModel / SQLAlchemy
• PostgreSQL mit asyncpg
• PyJWT
• Pydantic Settings
• qrcode
• Pillow
• pwdlib mit Argon2
• Alembic
• Ruff

Projektstruktur

• main.py: FastAPI-App, Router-Registrierung, /status, eigene Swagger-UI
• source/auth.py: Login, Passwort-Setup, Token-Refresh, Logout
• source/users.py: Benutzerverwaltung und Invite-/Reset-Flow
• source/items.py: Artikelverwaltung und QR-Code-Endpunkte
• source/manufacturers.py: Herstellerverwaltung
• source/projects.py: Projektverwaltung
• source/requests.py: Anfragenverwaltung und PDF-Anhänge
• source/inquiries.py: Rückfragenverwaltung
• source/models.py: SQLModel-Modelle und Enums
• source/rbac.py: Authentifizierung und Rollenprüfung
• source/config.py: Laden und Validieren der Umgebungsvariablen
• source/database.py: Async-Engine, Session-Handling, Verbindungsprüfung

Voraussetzungen

• Python 3.10 oder neuer
• PostgreSQL
• Eine .env-Datei im Projektverzeichnis

Konfiguration

Pflichtvariablen in .env:

DATABASE_URL=postgresql://user:passwort@localhost:5432/ewsys
SECRET_KEY=ein-langes-geheimes-token
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_MINUTES=10080

Optionale Variablen:

VERSION=0.3
ENVIRONMENT=development

Hinweise:

• DATABASE_URL wird automatisch von postgresql://... auf postgresql+asyncpg://... umgeschrieben.
• CORS_ALLOW_ORIGINS ist standardmaessig auf [*] gesetzt.
• Die Anwendung erwartet statische Dateien unter static/, unter anderem fuer Favicon und Swagger-Darkmode.

Rollenmodell

Hierarchische Rollenstufen:

Stufe	Rolle
1	Azubi
2	Geselle
3	Einkauf
4	Abteilungsleiter
5	Admin

Gruppen für Berechtigungen:

• MANAGER: Abteilungsleiter, Admin
• EINKAUF: Einkauf, Abteilungsleiter, Admin
• ADMIN: nur Admin

Die Rollenprüfung erfolgt je nach Endpunkt über Mindeststufe, Gruppe oder beides.

Authentifizierung und Invite-Flow

Neue Benutzer können ohne gesetztes Passwort angelegt werden. Der typische Ablauf ist:

1. Manager erstellt einen Benutzer über POST /users/.
2. Die Antwort enthält einen invite_token.
3. Der Benutzer setzt sein Passwort über POST /auth/setup.
4. Danach erfolgt der Login ueber POST /auth/login.
5. Access-Tokens können über POST /auth/refresh erneuert werden.
6. Refresh-Tokens werden über POST /auth/logout invalidiert.

Wichtige Sicherheitsdetails aus der Implementierung:

• Login löscht vorhandene Refresh-Tokens des Benutzers vor dem Ausstellen eines neuen Tokens.
• Refresh-Tokens werden nur gehasht in der Datenbank gespeichert.
• Invite-Tokens sind JWTs mit type="invite" und werden zusätzlich roh im Benutzerdatensatz geprüft.

Endpunkte nach Bereich

Status

• GET /status: API-Status, Version, Environment, Uptime und Datenbankstatus

Auth

• POST /auth/login: Login per OAuth2-Form (username, password)
• POST /auth/setup: Passwort über Invite-Token setzen
• POST /auth/refresh: neues Access- und Refresh-Token anfordern
• POST /auth/logout: Refresh-Token invalidieren

Benutzer

• GET /users/me: aktueller Benutzer
• POST /users/: Benutzer anlegen, nur MANAGER
• GET /users/: Benutzerliste, nur MANAGER
• DELETE /users/{user_id}: Benutzer loeschen, nur MANAGER
• POST /users/{user_id}/reset: Passwort zurücksetzen und neuen Invite-Token erzeugen, nur MANAGER

Artikel

• POST /items/: Artikel anlegen
• GET /items/: Artikelliste
• GET /items/search: Artikelsuche
• GET /items/{item_id}: einzelnen Artikel lesen
• PATCH /items/{item_id}: Artikel aktualisieren
• DELETE /items/{item_id}: Artikel loeschen
• GET /items/{item_id}/qrcode: QR-Code für Artikel als PNG
• GET /items/by-qr/{qr_uuid}: Artikel über QR-UUID abrufen

Hersteller

• POST /manufacturers/: Hersteller anlegen
• GET /manufacturers/: Herstellerliste
• GET /manufacturers/search: Herstellersuche
• GET /manufacturers/{manufacturer_id}: einzelnen Hersteller lesen
• PATCH /manufacturers/{manufacturer_id}: Hersteller aktualisieren
• DELETE /manufacturers/{manufacturer_id}: Hersteller loeschen

Projekte

• POST /projects/: Projekt anlegen
• GET /projects/: Projektliste
• GET /projects/search: Projektsuche
• GET /projects/{project_id}: einzelnes Projekt lesen
• PATCH /projects/{project_id}: Projekt aktualisieren
• DELETE /projects/{project_id}: Projekt loeschen

Anfragen

• POST /requests/: Anfrage anlegen
• GET /requests/: Anfrageliste
• GET /requests/{request_id}: einzelne Anfrage lesen
• PATCH /requests/{request_id}: Anfrage aktualisieren
• DELETE /requests/{request_id}: Anfrage loeschen
• POST /requests/{request_id}/attachments: PDF-Anhang hochladen
• GET /requests/{request_id}/attachments: Anhänge einer Anfrage auflisten
• GET /requests/{request_id}/attachments/{attachment_id}: PDF-Anhang herunterladen
• DELETE /requests/{request_id}/attachments/{attachment_id}: Anhang loeschen

Rückfragen

• POST /inquiries/: Rückfrage anlegen, nur Gruppe EINKAUF
• GET /inquiries/: Rückfragenliste
• GET /inquiries/{inquiry_id}: einzelne Rückfrage lesen
• PATCH /inquiries/{inquiry_id}: Rückfrage aktualisieren
• DELETE /inquiries/{inquiry_id}: Rückfrage löschen

Betriebsverhalten

• /status meldet die Datenbank als online oder offline.
• Uptime basiert auf der Startzeit der App in main.py.
• Es gibt laut Projektvorgaben kein Testframework; für Prüfungen dienen vor allem /status, /test falls vorhanden, und die Swagger UI.

Lizenz

Dieses Projekt steht unter der GPLv3.