immorechner/README.md

# Immorechner

Eine moderne Webanwendung zur Immobilienberechnung, entwickelt mit Symfony 7.3, PHP 8.4 und MariaDB.

## 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
- **CORS-Unterstützung**: Konfigurierbare CORS-Einstellungen für API-Zugriffe
- **phpMyAdmin**: Integriertes Datenbank-Verwaltungstool

## Technologie-Stack

- **Backend**: PHP 8.4
- **Framework**: Symfony 7.3
- **Datenbank**: MariaDB (Latest)
- **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

- Docker Desktop (Windows/Mac) oder Docker Engine + Docker Compose (Linux)
- Git

## 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%)

## 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
```

## 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)
├── src/                   # PHP-Quellcode
│   ├── Controller/       # Controller
│   ├── Entity/           # Doctrine Entities
│   ├── Enum/             # PHP Enums
│   ├── Repository/       # Doctrine Repositories
│   └── Kernel.php        # Symfony Kernel
├── 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
```

## Umgebungsvariablen

Die Anwendung verwendet folgende Umgebungsvariablen (definiert in `.env`):

```env
# Symfony
APP_ENV=dev
APP_SECRET=<generierter-secret-key>

# Datenbank
DATABASE_URL="mysql://immorechner_user:immorechner_pass@db:3306/immorechner?serverVersion=mariadb-11.7.1&charset=utf8mb4"

# CORS
CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'

# Routing
DEFAULT_URI=http://localhost
```

## Konfiguration

### CORS anpassen

CORS-Einstellungen können in `config/packages/nelmio_cors.yaml` angepasst werden.

### Datenbank-Verbindung ändern

Datenbank-Verbindung in `.env` anpassen:

```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:

```bash
# Bundle-Assets installieren
docker-compose exec web php bin/console assets:install public --symlink --relative

# 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
docker-compose down
docker-compose up -d --build
```

### "Class not found" Fehler

```bash
# Autoloader neu generieren
docker-compose exec web composer dump-autoload

# Cache leeren
docker-compose exec web php bin/console cache:clear

# Container neu starten
docker-compose restart web
```

### 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:**

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

## Lizenz

[Lizenz hier einfügen]

## Kontakt

[Kontaktinformationen hier einfügen]