greggy/immorechner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

API updadte

Browse Source
This commit is contained in:
Martin
2025-11-09 11:27:21 +01:00
parent 77206224a2
commit 4953d192c0
8 changed files with 2343 additions and 784 deletions
Download Patch File Download Diff File Expand all files Collapse all files

881
README.md
View File

@@ -1,841 +1,154 @@
# Immorechner
Eine moderne Webanwendung zur Immobilienberechnung, entwickelt mit Symfony 7.3, PHP 8.4 und MariaDB.
Eine moderne Webanwendung zur Immobilienberechnung mit interaktivem Frontend und vollständiger REST-API.
## Schnellstart
```bash
# Repository klonen
git clone <repository-url>
cd immorechner
# Docker-Container starten
docker-compose up -d --build
# Dependencies installieren
docker-compose exec web composer install
# Datenbank initialisieren
docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction
# Anwendung öffnen
# Frontend: http://localhost:8080
# API-Docs: http://localhost:8080/api/docs.html
# phpMyAdmin: http://localhost:8081
```
## 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 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
- **Testing**: Umfassende Test-Suite mit PHPUnit für Unit- und Funktions-Tests
- **Code Quality**: PHP-CS-Fixer für konsistenten Code-Style nach Symfony Standards
- **CORS-Unterstützung**: Konfigurierbare CORS-Einstellungen für API-Zugriffe
- **phpMyAdmin**: Integriertes Datenbank-Verwaltungstool
### Frontend (Web-Interface)
- 🧮 **Interaktiver Immobilienrechner** mit Live-Berechnungen
- 🔗 **URL-Sharing** für anonyme Nutzer (keine Registrierung nötig)
- 👤 **Benutzer-Registrierung & Login**
- 💾 **Immobilien speichern** (nur für registrierte Nutzer)
- 📊 **Automatische Berechnungen**: Grunderwerbsteuer, Gesamtkosten, Abschreibung, etc.
- 📱 **Responsive Design** (Mobile-optimiert)
## Technologie-Stack
### Backend (REST-API)
- 🔌 **Vollständige REST-API** mit API Platform 4.2
- 🔐 **Dual-Authentifizierung**: Session-basiert (Frontend) & API-Key (API)
- 🔑 **Rollenbasierte Zugriffskontrolle**: USER, ADMIN, MODERATOR, TECHNICAL
- 📖 **Swagger/OpenAPI** Dokumentation
- 🏢 **Mandantenfähigkeit**: Jeder User sieht nur seine eigenen Immobilien
- 🌍 **Öffentliche Ressourcen**: Bundesländer und Heizungstypen ohne Authentifizierung
- **Backend**: PHP 8.4
- **Framework**: Symfony 7.3
- **Datenbank**: MariaDB (Latest)
### Technologie
- **Backend**: PHP 8.4, Symfony 7.3
- **Frontend**: Twig, jQuery, separates CSS/JS
- **Datenbank**: MariaDB
- **Container**: Docker & Docker Compose
- **ORM**: Doctrine 3.0
- **API**: API Platform 4.2
- **Template Engine**: Twig 3.22
- **Webserver**: Apache 2.4 mit mod_rewrite
- **Container**: Docker & Docker Compose
- **Datenbank-Tool**: phpMyAdmin
## Voraussetzungen
## Dokumentation
- Docker Desktop (Windows/Mac) oder Docker Engine + Docker Compose (Linux)
- Git
📚 **Detaillierte Dokumentation:**
## Installation
### 1. Repository klonen
```bash
git clone <repository-url>
cd immorechner
```
### 2. Docker-Container starten
```bash
docker-compose up -d --build
```
Dieser Befehl:
- Baut das PHP 8.4 Image mit allen benötigten Extensions
- Startet MariaDB
- Startet phpMyAdmin
- Startet den Apache-Webserver
### 3. Dependencies installieren
```bash
docker-compose exec web composer install
```
### 4. Bundle-Assets installieren
```bash
docker-compose exec web php bin/console assets:install public --symlink --relative
```
Dieser Schritt ist wichtig für die Swagger UI (CSS, JS, Bilder).
### 5. Datenbank-Schema erstellen
```bash
docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction
```
### 6. Cache leeren
```bash
docker-compose exec web php bin/console cache:clear
```
## Verwendung
### Anwendung aufrufen
- **Web-Interface**: http://localhost:8080
- **API-Dokumentation (Swagger UI)**: http://localhost:8080/api/docs.html
- **API Entrypoint (Hydra)**: http://localhost:8080/api
- **OpenAPI Spezifikation (JSON)**: http://localhost:8080/api/docs?format=json
- **phpMyAdmin**: http://localhost:8081
- Server: `db`
- Benutzer: `root`
- Passwort: `root`
### Schnellstart API
Die vollständige API-Dokumentation mit allen Endpunkten, Beispielen und interaktiven Tests finden Sie im Abschnitt **[API-Dokumentation](#api-dokumentation)** weiter unten.
Wichtigste Endpunkte:
- **Immobilien**: `/api/immobilies` (GET, POST, PATCH, DELETE)
- **Benutzer**: `/api/users` (GET, POST, PUT, DELETE)
- **Bundesländer**: `/api/bundeslands` (GET, POST, PUT, DELETE)
- **Heizungstypen**: `/api/heizungstyps` (GET, POST, PUT, DELETE)
## Datenbank-Schema
### User-Tabelle
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| 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, 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 |
|------|-----|--------------|
| id | INT | Primärschlüssel (Auto-Increment) |
| name | VARCHAR(100) | Name des Bundeslandes (Unique) |
| grunderwerbsteuer | DECIMAL(4,2) | Grunderwerbsteuer in Prozent |
**Grunderwerbsteuer-Sätze (Stand 2025):**
- Baden-Württemberg, Bremen, Niedersachsen, Rheinland-Pfalz, Sachsen-Anhalt, Thüringen: 5,0%
- Bayern: 3,5%
- Hamburg, Sachsen: 5,5%
- Berlin, Hessen, Mecklenburg-Vorpommern: 6,0%
- Brandenburg, Nordrhein-Westfalen, Saarland, Schleswig-Holstein: 6,5%
### Heizungstyp-Tabelle
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| id | INT | Primärschlüssel (Auto-Increment) |
| name | VARCHAR(100) | Name des Heizungstyps (Unique) |
**Beispiele:** Gasheizung, Wärmepumpe, Ölheizung, Fernwärme, etc.
### Immobilien-Tabelle
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| id | INT | Primärschlüssel (Auto-Increment) |
| verwalter_id | INT | Foreign Key zu User (Verwalter der Immobilie) |
| adresse | VARCHAR(255) | Vollständige Adresse (5-255 Zeichen) |
| wohnflaeche | INT | Wohnfläche in m² (ganze Zahl) |
| nutzflaeche | INT | Nutzfläche in m² (ganze Zahl) |
| garage | BOOLEAN | Hat Garage? (Standard: false) |
| zimmer | INT | Anzahl Zimmer (> 0) |
| baujahr | INT | Baujahr (1800-2100, optional) |
| typ | ENUM | Immobilientyp (wohnung, haus, grundstueck, gewerbe, buero) |
| beschreibung | TEXT | Freitextbeschreibung (optional) |
| etage | INT | Stockwerk (0-10, optional) |
| heizungstyp_id | INT | Foreign Key zu Heizungstyp (optional) |
| abschreibungszeit | INT | Abschreibungszeit in Jahren (0-100, optional) |
| bundesland_id | INT | Foreign Key zu Bundesland (optional) |
| kaufpreis | INT | Kaufpreis in Euro (ganze Zahl, optional) |
| created_at | DATETIME | Erstellungsdatum |
| updated_at | DATETIME | Letzte Aktualisierung |
**Berechnete Felder (nicht in DB gespeichert):**
- `gesamtflaeche`: Wohnfläche + Nutzfläche
- `kaufnebenkosten`: Objekt mit Notar, Grundbuch, Grunderwerbsteuer und Gesamtsumme
- Notarkosten: ca. 1,5% des Kaufpreises
- Grundbuchkosten: ca. 0,5% des Kaufpreises
- Grunderwerbsteuer: abhängig vom Bundesland (3,5% - 6,5%)
## Testing & Code Quality
Das Projekt verwendet **PHPUnit** für Unit- und Funktionstests sowie **PHP-CS-Fixer** für Code-Qualität und Linting.
### Tests ausführen
#### Alle Tests ausführen
```bash
docker-compose exec web php bin/phpunit
```
#### Tests mit Ausgabedetails
```bash
docker-compose exec web php bin/phpunit --verbose
```
#### Nur bestimmte Testklassen ausführen
```bash
# Entity-Tests
docker-compose exec web php bin/phpunit tests/Entity
# API-Tests
docker-compose exec web php bin/phpunit tests/Api
# Einzelne Testklasse
docker-compose exec web php bin/phpunit tests/Entity/UserTest.php
```
#### Code Coverage Report (optional)
```bash
docker-compose exec web php bin/phpunit --coverage-text
```
### Code-Linting mit PHP-CS-Fixer
#### Code-Style prüfen (Dry-Run)
```bash
docker-compose exec web vendor/bin/php-cs-fixer fix --dry-run --diff
```
#### Code automatisch formatieren
```bash
docker-compose exec web vendor/bin/php-cs-fixer fix
```
#### Bestimmte Verzeichnisse prüfen
```bash
# Nur src/ Verzeichnis
docker-compose exec web vendor/bin/php-cs-fixer fix src --dry-run
# Nur tests/ Verzeichnis
docker-compose exec web vendor/bin/php-cs-fixer fix tests --dry-run
```
### Test-Struktur
```
tests/
├── Entity/ # Unit-Tests für Entities
│ ├── UserTest.php # User-Entity Tests
│ ├── ImmobilieTest.php # Immobilie-Entity Tests (inkl. Kaufnebenkosten)
│ ├── BundeslandTest.php # Bundesland-Entity Tests
│ └── HeizungstypTest.php # Heizungstyp-Entity Tests
└── Api/ # Funktions-/API-Tests
├── BundeslandApiTest.php # Bundesländer API-Tests
├── HeizungstypApiTest.php # Heizungstypen API-Tests
└── ApiDocumentationTest.php # API-Dokumentations-Tests
```
### Test-Abdeckung
Die Tests decken folgende Bereiche ab:
**Entity-Tests:**
- User-Entity: API-Key-Generierung, Rollen, UserInterface-Methoden
- Immobilie-Entity: Gesamtflächen-Berechnung, Kaufnebenkosten-Berechnung
- Bundesland-Entity: Grunderwerbsteuer-Werte für alle Bundesländer
- Heizungstyp-Entity: CRUD-Operationen
**API-Tests:**
- Öffentlicher Zugriff auf Bundesländer und Heizungstypen (GET)
- Authentifizierung für CREATE-Operationen
- API-Dokumentation Zugänglichkeit
### Code-Style Regeln
Die PHP-CS-Fixer-Konfiguration (`.php-cs-fixer.dist.php`) verwendet:
- Symfony Coding Standards
- Short Array Syntax
- Sortierte Imports
- Trailing Commas in Multiline Arrays
- Und weitere PSR-12 kompatible Regeln
## Entwicklung
### Neue Entity erstellen
```bash
docker-compose exec web php bin/console make:entity
```
### Migration erstellen
```bash
docker-compose exec web php bin/console doctrine:migrations:diff
```
### Migration ausführen
```bash
docker-compose exec web php bin/console doctrine:migrations:migrate
```
### Controller erstellen
```bash
docker-compose exec web php bin/console make:controller
```
### Cache leeren
```bash
docker-compose exec web php bin/console cache:clear
```
### Symfony Console aufrufen
```bash
docker-compose exec web php bin/console
```
## Docker-Befehle
### Container starten
```bash
docker-compose up -d
```
### Container stoppen
```bash
docker-compose down
```
### Container neu bauen
```bash
docker-compose up -d --build
```
### Container-Logs anzeigen
```bash
# Alle Container
docker-compose logs -f
# Nur Web-Container
docker-compose logs -f web
# Nur Datenbank-Container
docker-compose logs -f db
```
### In Container einloggen
```bash
# Web-Container (PHP/Apache)
docker-compose exec web bash
# Datenbank-Container
docker-compose exec db bash
```
### Composer-Befehle ausführen
```bash
docker-compose exec web composer require <paket-name>
docker-compose exec web composer update
docker-compose exec web composer dump-autoload
```
- **[Installation & Setup](docs/installation.md)** - Schritt-für-Schritt Installationsanleitung
- **[Features & Funktionalität](docs/features.md)** - Übersicht aller Funktionen
- **[Technische Dokumentation](docs/technical.md)** - Architektur, Datenbank-Schema, Konfiguration
- **[API-Dokumentation](docs/api.md)** - REST-API Endpunkte, Authentifizierung, Beispiele
- **[Entwicklung](docs/development.md)** - Testing, Code Quality, Entwickler-Workflow
- **[Docker](docs/docker.md)** - Docker-Befehle und Container-Management
- **[Fehlerbehebung](docs/troubleshooting.md)** - Lösungen für häufige Probleme
## Projekt-Struktur
```
immorechner/
├── bin/ # Symfony Console und andere Binaries
├── config/ # Symfony Konfigurationsdateien
├── docker/ # Docker-Konfigurationsdateien
│ └── apache/ # Apache VirtualHost Konfiguration
├── migrations/ # Doctrine Datenbank-Migrationen
├── public/ # Web-Root (index.php, Assets)
├── config/ # Symfony Konfiguration
├── docs/ # Dokumentation
├── migrations/ # Datenbank-Migrationen
├── public/ # Web-Root, CSS, JS, Assets
├── src/ # PHP-Quellcode
│ ├── Controller/ # Controller
│ ├── Controller/ # Controller (Frontend & API)
│ ├── Entity/ # Doctrine Entities
│ ├── Enum/ # PHP Enums
│ ├── Repository/ # Doctrine Repositories
│ └── Kernel.php # Symfony Kernel
│ └── Security/ # Authentifizierung
├── templates/ # Twig-Templates
│ ├── base.html.twig # Basis-Template
│ └── home/ # Homepage-Templates
├── var/ # Cache, Logs
├── vendor/ # Composer Dependencies
├── .env # Umgebungsvariablen
├── .env.example # Beispiel-Umgebungsvariablen
├── .gitignore # Git Ignore-Datei
├── composer.json # Composer-Konfiguration
├── docker-compose.yml # Docker Compose-Konfiguration
├── Dockerfile # Docker-Image für PHP/Apache
└── README.md # Diese Datei
└── Dockerfile # Docker-Image für PHP/Apache
```
## Umgebungsvariablen
## Verwendung
Die Anwendung verwendet folgende Umgebungsvariablen (definiert in `.env`):
### Frontend
```env
# Symfony
APP_ENV=dev
APP_SECRET=<generierter-secret-key>
**Startseite (Rechner):** http://localhost:8080
- Immobiliendaten eingeben
- Live-Berechnungen ansehen
- Link zum Teilen generieren
- Bei Anmeldung: Immobilie speichern
# Datenbank
DATABASE_URL="mysql://immorechner_user:immorechner_pass@db:3306/immorechner?serverVersion=mariadb-11.7.1&charset=utf8mb4"
**Registrierung:** http://localhost:8080/register
# CORS
CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
**Login:** http://localhost:8080/login
# Routing
DEFAULT_URI=http://localhost
```
**Meine Immobilien:** http://localhost:8080/meine-immobilien (nach Login)
## Konfiguration
### API
### CORS anpassen
**API-Dokumentation (Swagger UI):** http://localhost:8080/api/docs.html
CORS-Einstellungen können in `config/packages/nelmio_cors.yaml` angepasst werden.
**API Entrypoint:** http://localhost:8080/api
### Datenbank-Verbindung ändern
**Öffentliche Endpunkte (ohne Authentifizierung):**
- `GET /api/bundeslands` - Alle Bundesländer
- `GET /api/heizungstyps` - Alle Heizungstypen
Datenbank-Verbindung in `.env` anpassen:
**Geschützte Endpunkte (API-Key erforderlich):**
- `/api/immobilies` - Immobilien-Management
- `/api/users` - Benutzer-Management
```env
DATABASE_URL="mysql://user:password@host:port/database?serverVersion=mariadb-11.7.1"
```
### Apache-Konfiguration
Apache-VirtualHost-Konfiguration befindet sich in `docker/apache/000-default.conf`.
## Fehlerbehebung
### Swagger UI lädt ohne CSS/JS (Assets fehlen)
Wenn die Swagger UI unter http://localhost:8080/api/docs.html zwar lädt, aber keine Styles/Formatierung hat:
## Schnelle Befehle
```bash
# Bundle-Assets installieren
docker-compose exec web php bin/console assets:install public --symlink --relative
# Container starten
docker-compose up -d
# Cache leeren
docker-compose exec web php bin/console cache:clear
```
Danach sollten alle CSS-, JS- und Bilddateien unter `/bundles/apiplatform/` verfügbar sein.
### Container starten nicht
```bash
# Container-Logs prüfen
docker-compose logs
# Container-Status prüfen
docker ps -a
# Container neu bauen
# Container stoppen
docker-compose down
docker-compose up -d --build
```
### "Class not found" Fehler
# Logs anzeigen
docker-compose logs -f
```bash
# Autoloader neu generieren
docker-compose exec web composer dump-autoload
# In Container einloggen
docker-compose exec web bash
# Cache leeren
docker-compose exec web php bin/console cache:clear
# Container neu starten
docker-compose restart web
# Tests ausführen
docker-compose exec web php bin/phpunit
```
### Datenbank-Verbindungsfehler
```bash
# Prüfen ob DB-Container läuft
docker ps | grep db
# DB-Logs prüfen
docker-compose logs db
# In DB-Container einloggen und testen
docker-compose exec db mysql -u root -proot
```
### Port bereits belegt
Wenn Port 8080, 8081 oder 3306 bereits belegt ist, können die Ports in `docker-compose.yml` angepasst werden:
```yaml
services:
web:
ports:
- "8090:80" # Statt 8080:80
```
## API-Dokumentation
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:
**URL**: http://localhost:8080/api/docs.html
Features:
- Übersicht aller verfügbaren Endpunkte
- Interaktives Testen direkt im Browser
- Detaillierte Request/Response-Schemas
- Automatische Validierung von Parametern
- Try-it-out Funktion für alle Operationen
### OpenAPI Spezifikation
Die OpenAPI-Spezifikation (ehemals Swagger) kann in verschiedenen Formaten abgerufen werden:
#### OpenAPI JSON-Format
```bash
curl "http://localhost:8080/api/docs?format=json"
```
#### JSON-LD Format (Hydra)
```bash
curl http://localhost:8080/api/docs.jsonld
```
#### HTML Format (Swagger UI)
```bash
curl http://localhost:8080/api/docs.html
# oder im Browser öffnen: http://localhost:8080/api/docs.html
```
### API-Formate
Die API unterstützt mehrere Content-Type-Formate:
| Format | Content-Type | Beschreibung |
|--------|--------------|--------------|
| **JSON-LD** | `application/ld+json` | Standard-Format mit Linked Data Kontext (Hydra) |
| **JSON** | `application/json` | Einfaches JSON-Format |
| **HTML** | `text/html` | HTML-Darstellung (Swagger UI) |
#### Beispiel: JSON-Format verwenden
```bash
curl -H "Accept: application/json" http://localhost:8080/api/users
```
#### Beispiel: JSON-LD Format (Standard)
```bash
curl http://localhost:8080/api/users
# oder explizit:
curl -H "Accept: application/ld+json" http://localhost:8080/api/users
```
### Verfügbare Ressourcen
#### Immobilien-Endpunkte
| Methode | Endpoint | Beschreibung |
|---------|----------|--------------|
| GET | `/api/immobilies` | Alle Immobilien abrufen (mit Pagination) |
| GET | `/api/immobilies/{id}` | Einzelne Immobilie abrufen |
| POST | `/api/immobilies` | Neue Immobilie erstellen |
| PATCH | `/api/immobilies/{id}` | Immobilie teilweise aktualisieren |
| DELETE | `/api/immobilies/{id}` | Immobilie löschen |
#### User-Endpunkte
| Methode | Endpoint | Beschreibung |
|---------|----------|--------------|
| GET | `/api/users` | Alle User abrufen (mit Pagination) |
| GET | `/api/users/{id}` | Einzelnen User abrufen |
| POST | `/api/users` | Neuen User erstellen |
| PUT | `/api/users/{id}` | User vollständig ersetzen |
| DELETE | `/api/users/{id}` | User löschen |
#### Bundesland-Endpunkte
| Methode | Endpoint | Beschreibung |
|---------|----------|--------------|
| GET | `/api/bundeslands` | Alle Bundesländer abrufen (mit Pagination) |
| GET | `/api/bundeslands/{id}` | Einzelnes Bundesland abrufen |
| POST | `/api/bundeslands` | Neues Bundesland erstellen |
| PUT | `/api/bundeslands/{id}` | Bundesland vollständig ersetzen |
| DELETE | `/api/bundeslands/{id}` | Bundesland löschen |
#### Heizungstyp-Endpunkte
| Methode | Endpoint | Beschreibung |
|---------|----------|--------------|
| GET | `/api/heizungstyps` | Alle Heizungstypen abrufen (mit Pagination) |
| GET | `/api/heizungstyps/{id}` | Einzelnen Heizungstyp abrufen |
| POST | `/api/heizungstyps` | Neuen Heizungstyp erstellen |
| PUT | `/api/heizungstyps/{id}` | Heizungstyp vollständig ersetzen |
| DELETE | `/api/heizungstyps/{id}` | Heizungstyp löschen |
### Beispiele
#### 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 (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"
}'
```
#### 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",
"wohnflaeche": 85,
"nutzflaeche": 15,
"zimmer": 3,
"typ": "wohnung",
"garage": true,
"baujahr": 2020,
"heizungstyp": "/api/heizungstyps/1",
"bundesland": "/api/bundeslands/1",
"kaufpreis": 350000,
"abschreibungszeit": 50,
"etage": 3
}'
```
#### User erstellen
```bash
curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{
"name": "Max Mustermann",
"email": "max@example.com",
"role": "user"
}'
```
#### Eigene Immobilien abrufen (Mit API-Key)
```bash
# 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 -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, 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,
"heizungstyp": "/api/heizungstyps/2"
}'
```
### Berechnete Felder
Die Immobilien-Entity bietet automatisch berechnete Felder:
- **gesamtflaeche**: Berechnet die Gesamtfläche (Wohnfläche + Nutzfläche)
- **kaufnebenkosten**: Berechnet die Kaufnebenkosten basierend auf Kaufpreis und Bundesland
- Enthält: Notarkosten (1,5%), Grundbuchkosten (0,5%), Grunderwerbsteuer (abhängig vom Bundesland) und Gesamtsumme
Diese Felder sind schreibgeschützt (read-only) und werden automatisch bei jeder Abfrage berechnet.
### Enums
Die API verwendet folgende Enums:
**ImmobilienTyp:**
- `wohnung` - Wohnung
- `haus` - Haus
- `grundstueck` - Grundstück
- `gewerbe` - Gewerbe
- `buero` - Büro
**UserRole:**
- `user` - Benutzer
- `admin` - Administrator
- `moderator` - Moderator
- `technical` - Technischer User
### Relationen
**Bundesland und Heizungstyp** sind eigene Entities, die über Foreign Keys mit Immobilien verknüpft sind:
- Bei der Erstellung einer Immobilie muss eine IRI verwendet werden (z.B. `/api/bundeslands/1`)
- Diese Entities können über ihre eigenen Endpunkte verwaltet werden
- Bundesländer enthalten die Grunderwerbsteuer-Sätze für die Kaufnebenkosten-Berechnung
### Hydra-Unterstützung
Bei Verwendung des JSON-LD Formats (Standard) bietet die API Hydra-Unterstützung:
- **@context**: Beschreibt die Linked Data Struktur
- **@id**: IRI (Internationalized Resource Identifier) der Ressource
- **@type**: Typ der Ressource
- **hydra:member**: Array der Ressourcen in Collections
- **hydra:totalItems**: Gesamtanzahl der Elemente
- **hydra:view**: Pagination-Links (first, last, next, previous)
## Sicherheitshinweise
**Wichtig für Produktion:**
**⚠️ Wichtig für Produktion:**
1. Ändern Sie alle Standardpasswörter in `docker-compose.yml` und `.env`
2. Generieren Sie einen neuen `APP_SECRET` für `.env`
3. Setzen Sie `APP_ENV=prod` in der Produktion
4. Konfigurieren Sie CORS entsprechend Ihrer Domain
5. Aktivieren Sie HTTPS
6. Verwenden Sie sichere Datenbank-Credentials
7. Entfernen Sie phpMyAdmin aus der Produktion
2. Generieren Sie einen neuen `APP_SECRET`
3. Setzen Sie `APP_ENV=prod`
4. Aktivieren Sie HTTPS
5. Entfernen Sie phpMyAdmin
6. Konfigurieren Sie CORS für Ihre Domain
Details siehe [Technische Dokumentation](docs/technical.md#sicherheit).
## Lizenz
[Lizenz hier einfügen]
## Kontakt
## Support
[Kontaktinformationen hier einfügen]
Bei Problemen siehe [Fehlerbehebung](docs/troubleshooting.md) oder öffnen Sie ein Issue.