API updadte

2025-11-08 23:21:26 +01:00
parent c0c346a9ed
commit 81374cc659
12 changed files with 477 additions and 37 deletions
--- a/README.md
+++ b/README.md
@@ -5,10 +5,13 @@ Eine moderne Webanwendung zur Immobilienberechnung, entwickelt mit Symfony 7.3,
 ## Features

 - **REST-API**: Vollständige REST-API mit API Platform 4.2
+- **API-Key-Authentifizierung**: Sichere Authentifizierung über eindeutige API-Keys
+- **Rollenbasierte Zugriffskontrolle**: USER, ADMIN, MODERATOR mit feingranularen Berechtigungen
 - **Swagger/OpenAPI**: Automatische interaktive API-Dokumentation (Swagger UI)
 - **Web-Interface**: Benutzerfreundliche Weboberfläche mit Twig-Templates
- **Immobilien-Management**: Vollständige CRUD-Operationen für Immobilien mit automatischen Berechnungen
- **User Management**: Benutzerverwaltung mit Rollenbasierter Zugriffskontrolle (USER, ADMIN, MODERATOR)
+- **Immobilien-Management**: Vollständige CRUD-Operationen mit automatischen Berechnungen
+- **Mandantenfähigkeit**: Jeder User sieht nur seine eigenen Immobilien (außer Admins)
+- **Öffentliche Ressourcen**: Bundesländer und Heizungstypen ohne Authentifizierung abrufbar
 - **Docker-Setup**: Vollständig containerisierte Entwicklungsumgebung
 - **Datenbank-Migrationen**: Versionskontrollierte Datenbankschema-Verwaltung mit Doctrine
 - **CORS-Unterstützung**: Konfigurierbare CORS-Einstellungen für API-Zugriffe
@@ -110,9 +113,22 @@ Wichtigste Endpunkte:
 | id | INT | Primärschlüssel (Auto-Increment) |
 | name | VARCHAR(255) | Benutzername (min. 2 Zeichen) |
 | email | VARCHAR(255) | E-Mail-Adresse (Unique) |
-| role | ENUM | Benutzerrolle (user, admin, moderator) |
+| role | ENUM | Benutzerrolle (user, admin, moderator, technical) |
+| api_key | VARCHAR(64) | API-Key für Authentifizierung (Unique, automatisch generiert) |
 | created_at | DATETIME | Erstellungsdatum |

+**Benutzerrollen:**
+- `user` - Normaler Benutzer (sieht nur eigene Immobilien)
+- `admin` - Administrator (uneingeschränkter Zugriff auf alle Ressourcen)
+- `moderator` - Moderator (erweiterte Rechte)
+- `technical` - Technischer User (kann Bundesländer und Heizungstypen verwalten)
+
+**API-Key:**
+- Wird automatisch beim Erstellen eines Users generiert (SHA256-Hash)
+- Ist eindeutig für jeden User
+- Kann über die Methode `regenerateApiKey()` neu generiert werden
+- Wird für die API-Authentifizierung verwendet
+
 ### Bundesland-Tabelle

 | Feld | Typ | Beschreibung |
@@ -393,6 +409,67 @@ services:

 Die Anwendung nutzt **API Platform** zur automatischen Generierung von OpenAPI/Swagger-Dokumentation. Die interaktive Dokumentation ermöglicht es, alle API-Endpunkte direkt im Browser zu testen.

+### API-Authentifizierung
+
+Die API verwendet **API-Key-basierte Authentifizierung**. Jeder User erhält automatisch beim Erstellen einen eindeutigen API-Key.
+
+#### API-Key verwenden
+
+Fügen Sie den API-Key im Header `X-API-KEY` zu allen API-Anfragen hinzu:
+
+```bash
+curl -H "X-API-KEY: your-api-key-here" http://localhost:8080/api/immobilies
+```
+
+#### API-Key erhalten
+
+Der API-Key wird automatisch generiert, wenn ein neuer User erstellt wird. Sie können ihn abrufen über:
+
+```bash
+# User erstellen
+curl -X POST http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Max Mustermann",
+    "email": "max@example.com",
+    "role": "user"
+  }'
+
+# Response enthält den API-Key
+{
+  "@context": "/api/contexts/User",
+  "@id": "/api/users/1",
+  "@type": "User",
+  "id": 1,
+  "name": "Max Mustermann",
+  "email": "max@example.com",
+  "role": "user",
+  "apiKey": "a1b2c3d4e5f6...",  // Verwenden Sie diesen Key für die Authentifizierung
+  "createdAt": "2025-11-08T22:00:00+00:00"
+}
+```
+
+### Zugriffsrechte
+
+Die API implementiert folgende Zugriffsrechte:
+
+| Ressource | Aktion | Berechtigung |
+|-----------|--------|--------------|
+| **Bundesländer** | GET (Lesen) | Öffentlich (keine Authentifizierung) |
+| **Bundesländer** | POST, PUT, DELETE | ADMIN oder TECHNICAL |
+| **Heizungstypen** | GET (Lesen) | Öffentlich (keine Authentifizierung) |
+| **Heizungstypen** | POST, PUT, DELETE | ADMIN oder TECHNICAL |
+| **Immobilien** | GET, POST, PATCH, DELETE | Authentifiziert |
+| **Immobilien** | Sichtbarkeit | User sehen nur eigene Immobilien |
+| **Immobilien** | Admin-Zugriff | ADMIN sieht alle Immobilien |
+| **Users** | Alle Aktionen | Authentifiziert |
+
+**Wichtig:**
+- Normale User sehen und verwalten nur ihre eigenen Immobilien
+- Admins haben uneingeschränkten Zugriff auf alle Ressourcen
+- Technische User können Bundesländer und Heizungstypen anlegen, ändern und löschen
+- Bundesländer und Heizungstypen können ohne API-Key gelesen werden
+
 ### Swagger UI (Interaktive Dokumentation)

 Die **Swagger UI** bietet eine vollständige, interaktive Dokumentation aller API-Endpunkte:
@@ -494,32 +571,53 @@ curl -H "Accept: application/ld+json" http://localhost:8080/api/users

 ### Beispiele

-#### Bundesland erstellen
+#### Bundesländer abrufen (Öffentlich, kein API-Key benötigt)
+
+```bash
+curl http://localhost:8080/api/bundeslands
+```
+
+#### Bundesland erstellen (Admin oder Technical User)

 ```bash
 curl -X POST http://localhost:8080/api/bundeslands \
  -H "Content-Type: application/json" \
+  -H "X-API-KEY: admin-or-technical-api-key" \
  -d '{
    "name": "Bayern",
    "grunderwerbsteuer": 3.5
  }'
 ```

-#### Heizungstyp erstellen
+#### Heizungstyp erstellen (Admin oder Technical User)

 ```bash
 curl -X POST http://localhost:8080/api/heizungstyps \
  -H "Content-Type: application/json" \
+  -H "X-API-KEY: admin-or-technical-api-key" \
  -d '{
    "name": "Wärmepumpe"
  }'
 ```

-#### Immobilie erstellen
+#### Technischen User erstellen
+
+```bash
+curl -X POST http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Technical User",
+    "email": "technical@example.com",
+    "role": "technical"
+  }'
+```
+
+#### Immobilie erstellen (Mit API-Key)

 ```bash
 curl -X POST http://localhost:8080/api/immobilies \
  -H "Content-Type: application/json" \
+  -H "X-API-KEY: your-api-key-here" \
  -d '{
    "verwalter": "/api/users/1",
    "adresse": "Hauptstraße 123, 12345 Musterstadt",
@@ -549,21 +647,25 @@ curl -X POST http://localhost:8080/api/users \
  }'
 ```

-#### Immobilien mit Filter abrufen (Pagination)
+#### Eigene Immobilien abrufen (Mit API-Key)

 ```bash
-# Erste Seite (Standard)
-curl http://localhost:8080/api/immobilies
+# Erste Seite (Standard) - User sieht nur eigene Immobilien
+curl -H "X-API-KEY: your-api-key-here" http://localhost:8080/api/immobilies

 # Zweite Seite
-curl http://localhost:8080/api/immobilies?page=2
+curl -H "X-API-KEY: your-api-key-here" http://localhost:8080/api/immobilies?page=2
+
+# Als Admin: Sieht alle Immobilien
+curl -H "X-API-KEY: admin-api-key-here" http://localhost:8080/api/immobilies
 ```

-#### Einzelne Immobilie aktualisieren (PATCH)
+#### Einzelne Immobilie aktualisieren (PATCH, Mit API-Key)

 ```bash
 curl -X PATCH http://localhost:8080/api/immobilies/1 \
  -H "Content-Type: application/merge-patch+json" \
+  -H "X-API-KEY: your-api-key-here" \
  -d '{
    "wohnflaeche": 90,
    "kaufpreis": 360000,
@@ -596,6 +698,7 @@ Die API verwendet folgende Enums:
 - `user` - Benutzer
 - `admin` - Administrator
 - `moderator` - Moderator
+- `technical` - Technischer User

 ### Relationen