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 # 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 ## Features
- **REST-API**: Vollständige REST-API mit API Platform 4.2 ### Frontend (Web-Interface)
- **API-Key-Authentifizierung**: Sichere Authentifizierung über eindeutige API-Keys - 🧮 **Interaktiver Immobilienrechner** mit Live-Berechnungen
- **Rollenbasierte Zugriffskontrolle**: USER, ADMIN, MODERATOR mit feingranularen Berechtigungen - 🔗 **URL-Sharing** für anonyme Nutzer (keine Registrierung nötig)
- **Swagger/OpenAPI**: Automatische interaktive API-Dokumentation (Swagger UI) - 👤 **Benutzer-Registrierung & Login**
- **Web-Interface**: Benutzerfreundliche Weboberfläche mit Twig-Templates - 💾 **Immobilien speichern** (nur für registrierte Nutzer)
- **Immobilien-Management**: Vollständige CRUD-Operationen mit automatischen Berechnungen - 📊 **Automatische Berechnungen**: Grunderwerbsteuer, Gesamtkosten, Abschreibung, etc.
- **Mandantenfähigkeit**: Jeder User sieht nur seine eigenen Immobilien (außer Admins) - 📱 **Responsive Design** (Mobile-optimiert)
- **Ö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
## 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 ### Technologie
- **Framework**: Symfony 7.3 - **Backend**: PHP 8.4, Symfony 7.3
- **Datenbank**: MariaDB (Latest) - **Frontend**: Twig, jQuery, separates CSS/JS
- **Datenbank**: MariaDB
- **Container**: Docker & Docker Compose
- **ORM**: Doctrine 3.0 - **ORM**: Doctrine 3.0
- **API**: API Platform 4.2 - **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) 📚 **Detaillierte Dokumentation:**
- Git
## Installation - **[Installation & Setup](docs/installation.md)** - Schritt-für-Schritt Installationsanleitung
- **[Features & Funktionalität](docs/features.md)** - Übersicht aller Funktionen
### 1. Repository klonen - **[Technische Dokumentation](docs/technical.md)** - Architektur, Datenbank-Schema, Konfiguration
- **[API-Dokumentation](docs/api.md)** - REST-API Endpunkte, Authentifizierung, Beispiele
```bash - **[Entwicklung](docs/development.md)** - Testing, Code Quality, Entwickler-Workflow
git clone <repository-url> - **[Docker](docs/docker.md)** - Docker-Befehle und Container-Management
cd immorechner - **[Fehlerbehebung](docs/troubleshooting.md)** - Lösungen für häufige Probleme
```
### 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
```
## Projekt-Struktur ## Projekt-Struktur
``` ```
immorechner/ immorechner/
├── bin/ # Symfony Console und andere Binaries ├── config/ # Symfony Konfiguration
├── config/ # Symfony Konfigurationsdateien ├── docs/ # Dokumentation
├── docker/ # Docker-Konfigurationsdateien ├── migrations/ # Datenbank-Migrationen
│ └── apache/ # Apache VirtualHost Konfiguration ├── public/ # Web-Root, CSS, JS, Assets
├── migrations/ # Doctrine Datenbank-Migrationen
├── public/ # Web-Root (index.php, Assets)
├── src/ # PHP-Quellcode ├── src/ # PHP-Quellcode
│ ├── Controller/ # Controller │ ├── Controller/ # Controller (Frontend & API)
│ ├── Entity/ # Doctrine Entities │ ├── Entity/ # Doctrine Entities
│ ├── Enum/ # PHP Enums
│ ├── Repository/ # Doctrine Repositories │ ├── Repository/ # Doctrine Repositories
│ └── Kernel.php # Symfony Kernel │ └── Security/ # Authentifizierung
├── templates/ # Twig-Templates ├── 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 ├── docker-compose.yml # Docker Compose-Konfiguration
├── Dockerfile # Docker-Image für PHP/Apache └── Dockerfile # Docker-Image für PHP/Apache
└── README.md # Diese Datei
``` ```
## Umgebungsvariablen ## Verwendung
Die Anwendung verwendet folgende Umgebungsvariablen (definiert in `.env`): ### Frontend
```env **Startseite (Rechner):** http://localhost:8080
# Symfony - Immobiliendaten eingeben
APP_ENV=dev - Live-Berechnungen ansehen
APP_SECRET=<generierter-secret-key> - Link zum Teilen generieren
- Bei Anmeldung: Immobilie speichern
# Datenbank **Registrierung:** http://localhost:8080/register
DATABASE_URL="mysql://immorechner_user:immorechner_pass@db:3306/immorechner?serverVersion=mariadb-11.7.1&charset=utf8mb4"
# CORS **Login:** http://localhost:8080/login
CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
# Routing **Meine Immobilien:** http://localhost:8080/meine-immobilien (nach Login)
DEFAULT_URI=http://localhost
```
## 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 ## Schnelle Befehle
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 ```bash
# Bundle-Assets installieren # Container starten
docker-compose exec web php bin/console assets:install public --symlink --relative docker-compose up -d
# Cache leeren # Container stoppen
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 down
docker-compose up -d --build
```
### "Class not found" Fehler # Logs anzeigen
docker-compose logs -f
```bash # In Container einloggen
# Autoloader neu generieren docker-compose exec web bash
docker-compose exec web composer dump-autoload
# Cache leeren # Cache leeren
docker-compose exec web php bin/console cache:clear docker-compose exec web php bin/console cache:clear
# Container neu starten # Tests ausführen
docker-compose restart web 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 ## Sicherheitshinweise
**Wichtig für Produktion:** **⚠️ Wichtig für Produktion:**
1. Ändern Sie alle Standardpasswörter in `docker-compose.yml` und `.env` 1. Ändern Sie alle Standardpasswörter in `docker-compose.yml` und `.env`
2. Generieren Sie einen neuen `APP_SECRET` für `.env` 2. Generieren Sie einen neuen `APP_SECRET`
3. Setzen Sie `APP_ENV=prod` in der Produktion 3. Setzen Sie `APP_ENV=prod`
4. Konfigurieren Sie CORS entsprechend Ihrer Domain 4. Aktivieren Sie HTTPS
5. Aktivieren Sie HTTPS 5. Entfernen Sie phpMyAdmin
6. Verwenden Sie sichere Datenbank-Credentials 6. Konfigurieren Sie CORS für Ihre Domain
7. Entfernen Sie phpMyAdmin aus der Produktion
Details siehe [Technische Dokumentation](docs/technical.md#sicherheit).
## Lizenz ## Lizenz
[Lizenz hier einfügen] [Lizenz hier einfügen]
## Kontakt ## Support
[Kontaktinformationen hier einfügen] Bei Problemen siehe [Fehlerbehebung](docs/troubleshooting.md) oder öffnen Sie ein Issue.

185
docs/api.md Normal file
View File

@@ -0,0 +1,185 @@
# API-Dokumentation
[← Zurück zur Hauptseite](../README.md)
## Übersicht
Die Immorechner-API ist eine vollständige REST-API basierend auf API Platform 4.2 mit OpenAPI/Swagger-Dokumentation.
**Basis-URL:** `http://localhost:8080/api`
**Formate:**
- `application/ld+json` (Standard, JSON-LD mit Hydra)
- `application/json` (Einfaches JSON)
## Interaktive Dokumentation
**Swagger UI:** http://localhost:8080/api/docs.html
Hier können Sie alle Endpunkte direkt im Browser testen.
## Authentifizierung
### API-Key (für API-Zugriff)
Fügen Sie den API-Key im Header hinzu:
```bash
curl -H "X-API-KEY: ihr-api-key-hier" http://localhost:8080/api/immobilies
```
### API-Key erhalten
```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 apiKey
{
"apiKey": "a1b2c3d4e5f6...", # Diesen Key verwenden
...
}
```
## Endpunkte
### Bundesländer (Öffentlich)
| Methode | Endpoint | Beschreibung | Auth |
|---------|----------|--------------|------|
| GET | `/api/bundeslands` | Alle Bundesländer | Nein |
| GET | `/api/bundeslands/{id}` | Einzelnes Bundesland | Nein |
| POST | `/api/bundeslands` | Neues Bundesland erstellen | ADMIN/TECHNICAL |
| PUT | `/api/bundeslands/{id}` | Bundesland aktualisieren | ADMIN/TECHNICAL |
| DELETE | `/api/bundeslands/{id}` | Bundesland löschen | ADMIN/TECHNICAL |
**Beispiel:**
```bash
curl http://localhost:8080/api/bundeslands
```
### Heizungstypen (Öffentlich)
| Methode | Endpoint | Beschreibung | Auth |
|---------|----------|--------------|------|
| GET | `/api/heizungstyps` | Alle Heizungstypen | Nein |
| GET | `/api/heizungstyps/{id}` | Einzelner Heizungstyp | Nein |
| POST | `/api/heizungstyps` | Neuen Typ erstellen | ADMIN/TECHNICAL |
| PUT | `/api/heizungstyps/{id}` | Typ aktualisieren | ADMIN/TECHNICAL |
| DELETE | `/api/heizungstyps/{id}` | Typ löschen | ADMIN/TECHNICAL |
### Immobilien (Geschützt)
| Methode | Endpoint | Beschreibung | Auth |
|---------|----------|--------------|------|
| GET | `/api/immobilies` | Eigene Immobilien | API-Key |
| GET | `/api/immobilies/{id}` | Einzelne Immobilie | API-Key |
| POST | `/api/immobilies` | Neue Immobilie | API-Key |
| PATCH | `/api/immobilies/{id}` | Immobilie aktualisieren | API-Key |
| DELETE | `/api/immobilies/{id}` | Immobilie löschen | API-Key |
**Beispiel - Immobilie erstellen:**
```bash
curl -X POST http://localhost:8080/api/immobilies \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-api-key" \
-d '{
"verwalter": "/api/users/1",
"adresse": "Hauptstraße 123, 12345 Musterstadt",
"wohnflaeche": 85,
"nutzflaeche": 15,
"zimmer": 3,
"typ": "wohnung",
"kaufpreis": 300000,
"bundesland": "/api/bundeslands/1",
"heizungstyp": "/api/heizungstyps/1"
}'
```
### User (Geschützt)
| Methode | Endpoint | Beschreibung | Auth |
|---------|----------|--------------|------|
| GET | `/api/users` | Alle User | API-Key |
| GET | `/api/users/{id}` | Einzelner User | API-Key |
| POST | `/api/users` | Neuen User erstellen | Nein* |
| PUT | `/api/users/{id}` | User aktualisieren | API-Key |
| DELETE | `/api/users/{id}` | User löschen | API-Key |
*POST ohne Auth zum Registrieren neuer User
## Rollen & Berechtigungen
| Rolle | Rechte |
|-------|--------|
| `user` | Eigene Immobilien verwalten |
| `admin` | Alle Ressourcen, alle Immobilien |
| `technical` | Bundesländer & Heizungstypen verwalten |
| `moderator` | Erweiterte Rechte |
## Enums
### ImmobilienTyp
- `wohnung` - Wohnung
- `haus` - Haus
- `grundstueck` - Grundstück
- `gewerbe` - Gewerbe
- `buero` - Büro
### UserRole
- `user` - Benutzer
- `admin` - Administrator
- `moderator` - Moderator
- `technical` - Technischer User
## Pagination
Alle Collection-Endpunkte unterstützen Pagination:
```bash
# Erste Seite (Standard: 30 Items)
curl http://localhost:8080/api/immobilies
# Zweite Seite
curl http://localhost:8080/api/immobilies?page=2
# Custom Page Size
curl "http://localhost:8080/api/immobilies?itemsPerPage=10"
```
## Filter
```bash
# Nach Typ filtern
curl "http://localhost:8080/api/immobilies?typ=wohnung"
# Nach Bundesland filtern
curl "http://localhost:8080/api/immobilies?bundesland=/api/bundeslands/1"
```
## Fehler-Codes
| Status Code | Bedeutung |
|-------------|-----------|
| 200 | OK - Erfolgreiche Anfrage |
| 201 | Created - Ressource erstellt |
| 204 | No Content - Erfolgreich gelöscht |
| 400 | Bad Request - Ungültige Daten |
| 401 | Unauthorized - Authentifizierung fehlgeschlagen |
| 403 | Forbidden - Keine Berechtigung |
| 404 | Not Found - Ressource nicht gefunden |
| 500 | Internal Server Error - Server-Fehler |
---
**Weitere Informationen:**
- [Features](features.md) - Funktionsübersicht
- [Technical](technical.md) - Datenbank-Schema & Architektur
[← Zurück zur Hauptseite](../README.md)

302
docs/development.md Normal file
View File

@@ -0,0 +1,302 @@
# Entwicklung
[← Zurück zur Hauptseite](../README.md)
## Entwickler-Workflow
### Entwicklungsumgebung einrichten
Siehe [Installation](installation.md)
### Code-Änderungen testen
```bash
# Container starten
docker-compose up -d
# In Web-Container einloggen
docker-compose exec web bash
# Cache leeren nach Änderungen
php bin/console cache:clear
```
## Testing
### PHPUnit Tests
Das Projekt verwendet PHPUnit 12.4 für Tests.
#### Alle Tests ausführen
```bash
docker-compose exec web php bin/phpunit
```
#### Spezifische Tests
```bash
# Nur Entity-Tests
docker-compose exec web php bin/phpunit tests/Entity
# Nur API-Tests
docker-compose exec web php bin/phpunit tests/Api
# Einzelne Testklasse
docker-compose exec web php bin/phpunit tests/Entity/UserTest.php
```
#### Mit Details
```bash
docker-compose exec web php bin/phpunit --verbose
```
#### Code Coverage (optional)
```bash
docker-compose exec web php bin/phpunit --coverage-text
```
### Test-Struktur
```
tests/
├── Entity/
│ ├── UserTest.php # User-Entity Tests
│ ├── ImmobilieTest.php # Immobilie-Entity Tests
│ ├── BundeslandTest.php # Bundesland-Entity Tests
│ └── HeizungstypTest.php # Heizungstyp-Entity Tests
└── Api/
├── BundeslandApiTest.php # Bundesländer-API Tests
├── HeizungstypApiTest.php # Heizungstypen-API Tests
└── ApiDocumentationTest.php # API-Docs Tests
```
## Code Quality
### PHP-CS-Fixer
Für konsistenten Code-Style nach Symfony Standards.
#### 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
```bash
# Nur src/
docker-compose exec web vendor/bin/php-cs-fixer fix src
# Nur tests/
docker-compose exec web vendor/bin/php-cs-fixer fix tests
```
### Code-Style Regeln
Konfiguration in `.php-cs-fixer.dist.php`:
- Symfony Coding Standards
- PSR-12 kompatibel
- Short Array Syntax
- Sortierte Imports
- Trailing Commas in Arrays
## Datenbank
### Neue Entity erstellen
```bash
docker-compose exec web php bin/console make:entity
```
### Migration erstellen
Nach Änderungen an Entities:
```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
```
### Migration rückgängig machen
```bash
# Letzte Migration
docker-compose exec web php bin/console doctrine:migrations:migrate prev
# Zu spezifischer Version
docker-compose exec web php bin/console doctrine:migrations:migrate DoctrineMigrations\\Version20251109100000
```
### Migration-Status
```bash
docker-compose exec web php bin/console doctrine:migrations:status
```
### Datenbank-Schema validieren
```bash
docker-compose exec web php bin/console doctrine:schema:validate
```
## Controller & Routes
### Controller erstellen
```bash
docker-compose exec web php bin/console make:controller
```
### Routes anzeigen
```bash
# Alle Routes
docker-compose exec web php bin/console debug:router
# Spezifische Route
docker-compose exec web php bin/console debug:router app_home
```
## Symfony Console
### Cache
```bash
# Cache leeren
docker-compose exec web php bin/console cache:clear
# Cache warmup
docker-compose exec web php bin/console cache:warmup
```
### Services debuggen
```bash
# Alle Services
docker-compose exec web php bin/console debug:container
# Spezifischer Service
docker-compose exec web php bin/console debug:container UserRepository
```
### Ereignisse anzeigen
```bash
docker-compose exec web php bin/console debug:event-dispatcher
```
### Konfiguration anzeigen
```bash
docker-compose exec web php bin/console debug:config framework
```
## Git Workflow
### Feature-Branch erstellen
```bash
git checkout -b feature/neue-funktion
```
### Änderungen committen
```bash
git add .
git commit -m "Feature: Beschreibung der Änderung"
```
### Pull Request erstellen
1. Push auf Remote Branch
2. Pull Request in GitHub/GitLab erstellen
3. Code Review abwarten
4. Nach Approval mergen
## Best Practices
### Code-Organisation
1. **Controller:** Dünn halten, Logik in Services auslagern
2. **Entities:** Nur Datenmodell, keine Business-Logik
3. **Services:** Wiederverwendbare Business-Logik
4. **Repositories:** Nur Datenbank-Queries
### Namenskonventionen
- **Controller:** `XyzController.php`
- **Entity:** `Xyz.php`
- **Repository:** `XyzRepository.php`
- **Service:** `XyzService.php`
- **Test:** `XyzTest.php`
### Security
- Nie Passwörter im Klartext speichern
- Immer UserPasswordHasher verwenden
- CSRF-Tokens bei allen Forms
- Input-Validierung auf Server-Seite
- Output-Escaping (Twig macht automatisch)
### Performance
- Doctrine Query Cache nutzen
- Eager Loading für Relationen
- Opcache in Produktion aktivieren
- Assets kompilieren für Produktion
## Deployment
### Vorbereitung
```bash
# .env.local für Produktion erstellen
cp .env .env.local
# Produktions-Werte setzen
APP_ENV=prod
APP_SECRET=<neues-secret-generieren>
```
### Build für Produktion
```bash
# Composer Dependencies ohne Dev
composer install --no-dev --optimize-autoloader
# Cache warmup
php bin/console cache:warmup --env=prod
# Assets installieren
php bin/console assets:install public --symlink --relative --env=prod
```
### Database Migration
```bash
php bin/console doctrine:migrations:migrate --no-interaction --env=prod
```
---
**Siehe auch:**
- [Technical](technical.md) - Architektur & Konfiguration
- [Docker](docker.md) - Container-Management
- [Troubleshooting](troubleshooting.md) - Fehler beheben
[← Zurück zur Hauptseite](../README.md)

337
docs/docker.md Normal file
View File

@@ -0,0 +1,337 @@
# Docker
[← Zurück zur Hauptseite](../README.md)
## Container-Übersicht
Das Projekt verwendet 3 Docker-Container:
| Container | Image | Port | Beschreibung |
|-----------|-------|------|--------------|
| `immorechner_web` | Custom (PHP 8.4 + Apache) | 8080 | Web-Server & PHP |
| `immorechner_db` | mariadb:latest | 3306 | Datenbank |
| `immorechner_phpmyadmin` | phpmyadmin:latest | 8081 | DB-Verwaltung |
## Container-Management
### Starten
```bash
# Alle Container starten
docker-compose up -d
# Mit Build (nach Dockerfile-Änderungen)
docker-compose up -d --build
# Im Vordergrund (mit Logs)
docker-compose up
```
### Stoppen
```bash
# Container stoppen
docker-compose stop
# Container stoppen und entfernen
docker-compose down
# Container stoppen, entfernen + Volumes löschen
docker-compose down -v
```
### Neustarten
```bash
# Alle Container
docker-compose restart
# Einzelner Container
docker-compose restart web
docker-compose restart db
```
### Status prüfen
```bash
# Container-Status
docker-compose ps
# Alle Container (auch gestoppte)
docker ps -a
# Resource-Usage
docker stats
```
## Logs
### Container-Logs anzeigen
```bash
# Alle Container (Live)
docker-compose logs -f
# Nur Web-Container
docker-compose logs -f web
# Nur Datenbank
docker-compose logs -f db
# Nur phpMyAdmin
docker-compose logs -f phpmyadmin
# Letzte 100 Zeilen
docker-compose logs --tail=100 web
```
### Apache-Logs
```bash
# Access Log
docker-compose exec web tail -f /var/log/apache2/access.log
# Error Log
docker-compose exec web tail -f /var/log/apache2/error.log
```
### Symfony-Logs
```bash
# Dev Log
docker-compose exec web tail -f /var/www/html/var/log/dev.log
# Prod Log
docker-compose exec web tail -f /var/www/html/var/log/prod.log
```
## Container-Zugriff
### In Container einloggen
```bash
# Web-Container (Bash)
docker-compose exec web bash
# Datenbank-Container
docker-compose exec db bash
# phpMyAdmin-Container
docker-compose exec phpmyadmin bash
```
### Als Root einloggen
```bash
docker-compose exec -u root web bash
```
## Befehle im Container ausführen
### PHP/Symfony
```bash
# Symfony Console
docker-compose exec web php bin/console
# PHP-Version prüfen
docker-compose exec web php -v
# PHP-Module anzeigen
docker-compose exec web php -m
# PHP-Konfiguration
docker-compose exec web php -i
```
### Composer
```bash
# Install
docker-compose exec web composer install
# Update
docker-compose exec web composer update
# Paket hinzufügen
docker-compose exec web composer require vendor/package
# Paket entfernen
docker-compose exec web composer remove vendor/package
# Autoloader neu generieren
docker-compose exec web composer dump-autoload
```
### Datenbank
```bash
# MariaDB-Client öffnen
docker-compose exec db mariadb -u root -proot immorechner
# SQL-Datei importieren
docker-compose exec -T db mariadb -u root -proot immorechner < backup.sql
# Datenbank exportieren
docker-compose exec db mariadb-dump -u root -proot immorechner > backup.sql
# Tabellen anzeigen
docker-compose exec db mariadb -u root -proot -e "SHOW TABLES" immorechner
```
## Volumes
### Volumes anzeigen
```bash
docker volume ls
```
### Volume-Details
```bash
docker volume inspect immorechner_db_data
```
### Volume löschen
```bash
# ACHTUNG: Löscht alle Daten!
docker volume rm immorechner_db_data
```
### Backup erstellen
```bash
# Datenbank-Backup
docker-compose exec db mariadb-dump -u root -proot immorechner > backup_$(date +%Y%m%d).sql
# Volume-Backup
docker run --rm -v immorechner_db_data:/data -v $(pwd):/backup alpine tar czf /backup/db_backup.tar.gz /data
```
## Images
### Images anzeigen
```bash
docker images
```
### Image neu bauen
```bash
docker-compose build web
```
### Image mit Tag
```bash
docker build -t immorechner:latest .
```
### Image löschen
```bash
docker rmi immorechner-web
```
## Netzwerk
### Netzwerke anzeigen
```bash
docker network ls
```
### Netzwerk-Details
```bash
docker network inspect immorechner_immorechner_network
```
### Container im Netzwerk
```bash
docker network inspect immorechner_immorechner_network | grep Name
```
## Cleanup
### Gestoppte Container entfernen
```bash
docker container prune
```
### Ungenutzte Images entfernen
```bash
docker image prune
```
### Ungenutzte Volumes entfernen
```bash
docker volume prune
```
### Alles aufräumen
```bash
# ACHTUNG: Löscht alles Ungenutzte!
docker system prune -a --volumes
```
## Troubleshooting
### Container startet nicht
```bash
# Logs prüfen
docker-compose logs web
# Container im Debug-Modus starten
docker-compose up web
```
### Port bereits belegt
```bash
# Ports prüfen
netstat -ano | findstr :8080 # Windows
lsof -i :8080 # Mac/Linux
# In docker-compose.yml ändern:
ports:
- "8090:80" # Statt 8080:80
```
### Berechtigungsprobleme
```bash
# Berechtigungen setzen
docker-compose exec -u root web chown -R www-data:www-data /var/www/html
# Schreibrechte für var/
docker-compose exec -u root web chmod -R 777 /var/www/html/var
```
### Container-Reset
```bash
# Komplett neu starten
docker-compose down -v
docker-compose up -d --build
docker-compose exec web composer install
docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction
```
---
**Siehe auch:**
- [Installation](installation.md) - Setup-Anleitung
- [Development](development.md) - Entwickler-Workflow
- [Troubleshooting](troubleshooting.md) - Fehler beheben
[← Zurück zur Hauptseite](../README.md)

275
docs/features.md Normal file
View File

@@ -0,0 +1,275 @@
# Features & Funktionalität
[← Zurück zur Hauptseite](../README.md)
## Übersicht
Der Immorechner bietet zwei Hauptkomponenten:
1. **Web-Frontend** - Interaktive Benutzeroberfläche für Endanwender
2. **REST-API** - Programmgesteuerter Zugriff für Integrationen
---
## Frontend-Features
### 1. Immobilienrechner (Startseite)
**URL:** http://localhost:8080/
Der Immobilienrechner ermöglicht die schnelle Berechnung wichtiger Kennzahlen einer Immobilie.
#### Eingabefelder
| Feld | Typ | Beschreibung | Pflicht |
|------|-----|--------------|---------|
| Adresse | Text | Vollständige Adresse der Immobilie | Nein |
| Kaufpreis | Zahl | Kaufpreis in Euro | Empfohlen |
| Wohnfläche | Zahl | Wohnfläche in m² | Ja |
| Nutzfläche | Zahl | Nutzfläche in m² | Nein |
| Zimmer | Zahl | Anzahl der Zimmer | Empfohlen |
| Baujahr | Zahl | Baujahr der Immobilie | Nein |
| Etage | Zahl | Stockwerk | Nein |
| Immobilientyp | Auswahl | Wohnung, Haus oder Gewerbe | Empfohlen |
| Bundesland | Auswahl | Deutsches Bundesland | Empfohlen |
| Heizungstyp | Auswahl | Ölheizung, Gasheizung, Wärmepumpe, Pelletheizung | Nein |
| Abschreibungszeit | Zahl | Jahre für Abschreibung (Standard: 50) | Nein |
| Garage | Checkbox | Garage vorhanden? | Nein |
#### Live-Berechnungen
Alle Werte werden **in Echtzeit** berechnet (ohne Seitenreload):
1. **Gesamtfläche**
- Formel: Wohnfläche + Nutzfläche
- Einheit: m²
2. **Preis pro m² Wohnfläche**
- Formel: Kaufpreis / Wohnfläche
- Einheit: €/m²
3. **Grunderwerbsteuer**
- Formel: Kaufpreis × Grunderwerbsteuersatz des Bundeslandes
- Sätze: 3,5% (Bayern) bis 6,5% (Brandenburg, NRW, Saarland, SH)
- Einheit: €
4. **Gesamtkosten**
- Formel: Kaufpreis + Grunderwerbsteuer
- Einheit: €
5. **Jährliche Abschreibung**
- Formel: Kaufpreis / Abschreibungszeit
- Standard-Abschreibungszeit: 50 Jahre
- Einheit: €/Jahr
6. **Alter der Immobilie**
- Formel: Aktuelles Jahr - Baujahr
- Einheit: Jahre
### 2. URL-Sharing für anonyme Nutzer
**Funktion:** "Link teilen" Button
- Kodiert alle Formulardaten in URL-Parameter
- Ermöglicht Teilen der Berechnung ohne Registrierung
- Link funktioniert auch nach Tagen/Wochen
- Daten werden **nicht** in der Datenbank gespeichert
- Ideal für schnelle Berechnungen und Vergleiche
**Beispiel-URL:**
```
http://localhost:8080/?adresse=Teststr+123&kaufpreis=300000&wohnflaeche=85&...
```
### 3. Benutzer-Authentifizierung
#### Registrierung
**URL:** http://localhost:8080/register
- Name (Pflicht, mind. 2 Zeichen)
- E-Mail (Pflicht, muss gültig und eindeutig sein)
- Passwort (Pflicht, mind. 6 Zeichen)
- Passwort bestätigen
**Sicherheit:**
- Passwort wird mit bcrypt gehasht
- E-Mail muss eindeutig sein
- Validierung auf Client- und Server-Seite
#### Login
**URL:** http://localhost:8080/login
- E-Mail
- Passwort
**Session-basiert:**
- Bleibt aktiv bis zum Logout
- Cookie-basierte Session
- CSRF-Schutz integriert
#### Logout
- Link im Header "Abmelden"
- Beendet Session
- Redirect zur Startseite
### 4. Immobilien speichern (nur eingeloggte Nutzer)
**Funktion:** "Speichern" Button (erscheint nur nach Login)
- Speichert alle eingegebenen Daten in der Datenbank
- Immobilie wird dem eingeloggten Nutzer zugeordnet
- Nutzer kann nur eigene Immobilien sehen
- AJAX-basiert (kein Seitenreload)
- Erfolgs-/Fehlermeldung als Alert
### 5. Meine Immobilien
**URL:** http://localhost:8080/meine-immobilien (nur nach Login)
**Funktionen:**
- Übersicht aller gespeicherten Immobilien
- Anzeige aller Details pro Immobilie
- Berechnete Werte werden angezeigt
- Sortierung nach Erstellungsdatum (neueste zuerst)
**Angezeigt werden:**
- Typ, Kaufpreis, Flächen
- Zimmer, Baujahr, Etage
- Bundesland, Heizungstyp
- Garage (Ja/Nein)
- Erstellungsdatum
---
## API-Features
Vollständige Details siehe [API-Dokumentation](api.md)
### 1. Dual-Authentifizierung
**Session-basiert (Frontend):**
- Form-Login mit E-Mail/Passwort
- Cookie-basierte Sessions
- Für Web-Interface
**API-Key-basiert (API):**
- Header: `X-API-KEY`
- Automatisch generiert bei User-Erstellung
- Für programmatischen Zugriff
### 2. Rollenbasierte Zugriffskontrolle
| Rolle | Rechte |
|-------|--------|
| **USER** | Eigene Immobilien verwalten |
| **ADMIN** | Alle Immobilien verwalten, alle User sehen |
| **MODERATOR** | Erweiterte Rechte |
| **TECHNICAL** | Bundesländer & Heizungstypen verwalten |
### 3. Mandantenfähigkeit
- Jeder User sieht nur eigene Immobilien
- Admins sehen alle Immobilien
- Automatische Filterung auf Basis des eingeloggten Users
- Keine manuelle Filterung nötig
### 4. Öffentliche Ressourcen
**Ohne Authentifizierung verfügbar:**
- `GET /api/bundeslands` - Alle Bundesländer mit Grunderwerbsteuersätzen
- `GET /api/heizungstyps` - Alle Heizungstypen
**Vorbefüllt:**
- 16 deutsche Bundesländer mit aktuellen Steuersätzen
- 4 Heizungstypen (Öl, Gas, Wärmepumpe, Pellet)
### 5. Swagger/OpenAPI-Dokumentation
**URL:** http://localhost:8080/api/docs.html
**Features:**
- Interaktive API-Dokumentation
- "Try it out" Funktion für alle Endpunkte
- Request/Response Beispiele
- Schema-Dokumentation
- Export als JSON/YAML
---
## Technische Features
### 1. Responsive Design
- Mobile-optimiert
- Grid-Layout passt sich an Bildschirmgröße an
- Touch-freundliche Buttons und Formulare
### 2. Performance
- **Live-Berechnungen** ohne Server-Anfragen
- **AJAX** für Speichern-Funktion (kein Reload)
- **Opcache** aktiviert in Produktion
- **Doctrine Query Cache**
### 3. Datenvalidierung
**Frontend:**
- HTML5-Validierung
- Required-Felder
- Type-Checking (number, email, etc.)
**Backend:**
- Symfony Validator
- Doctrine Constraints
- Custom Validation Rules
### 4. Sicherheit
- **CSRF-Protection** für alle Forms
- **Passwort-Hashing** mit bcrypt
- **SQL-Injection-Schutz** durch Doctrine ORM
- **XSS-Schutz** durch Twig Auto-Escaping
- **CORS-Konfiguration** für API
### 5. Separation of Concerns
- **CSS** in separaten Dateien (`public/css/`)
- **JavaScript** in separaten Dateien (`public/js/`)
- **Templates** mit Twig
- **Controller** für Logik
- **Entities** für Datenmodell
---
## Berechnungslogik
### Grunderwerbsteuer
Bundesland-spezifisch (Stand 2025):
| Bundesland | Steuersatz |
|------------|-----------|
| Bayern | 3,5% |
| Baden-Württemberg, Bremen, Niedersachsen, Rheinland-Pfalz, Sachsen-Anhalt, Thüringen | 5,0% |
| Hamburg, Sachsen | 5,5% |
| Berlin, Hessen, Mecklenburg-Vorpommern | 6,0% |
| Brandenburg, NRW, Saarland, Schleswig-Holstein | 6,5% |
### Kaufnebenkosten (nur API)
Bei API-Anfragen werden zusätzlich berechnet:
- **Notarkosten:** ca. 1,5% des Kaufpreises
- **Grundbuchkosten:** ca. 0,5% des Kaufpreises
- **Grunderwerbsteuer:** siehe oben
- **Gesamt:** Summe aller Nebenkosten
---
**Siehe auch:**
- [Technische Dokumentation](technical.md) - Architektur & Datenbank
- [API-Dokumentation](api.md) - REST-API Details
- [Installation](installation.md) - Setup-Anleitung
[← Zurück zur Hauptseite](../README.md)

291
docs/installation.md Normal file
View File

@@ -0,0 +1,291 @@
# Installation & Setup
[← Zurück zur Hauptseite](../README.md)
## Voraussetzungen
- **Docker Desktop** (Windows/Mac) oder **Docker Engine + Docker Compose** (Linux)
- **Git**
- Mindestens 2GB freier RAM für Docker
- Ports 8080, 8081 und 3306 verfügbar
## Installations-Schritte
### 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 Container
- Startet phpMyAdmin Container
- Startet den Apache-Webserver
**Hinweis:** Der erste Build kann 5-10 Minuten dauern.
### 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
```
Diese Migration erstellt:
- Users-Tabelle mit Passwort- und API-Key-Feldern
- Bundesländer-Tabelle (vorbefüllt mit allen 16 deutschen Bundesländern)
- Heizungstypen-Tabelle (vorbefüllt mit Ölheizung, Gasheizung, Wärmepumpe, Pelletheizung)
- Immobilien-Tabelle mit allen Relationen
### 6. Cache leeren
```bash
docker-compose exec web php bin/console cache:clear
```
## Überprüfung der Installation
### Anwendung testen
Öffnen Sie die folgenden URLs in Ihrem Browser:
1. **Frontend (Rechner):** http://localhost:8080
- Sie sollten den Immobilienrechner sehen
- Bundesländer-Dropdown sollte befüllt sein
- Heizungstypen-Dropdown sollte befüllt sein
2. **API-Dokumentation:** http://localhost:8080/api/docs.html
- Swagger UI sollte mit CSS/Styling laden
- Alle API-Endpunkte sollten sichtbar sein
3. **phpMyAdmin:** http://localhost:8081
- Server: `db`
- Benutzer: `root`
- Passwort: `root`
- Datenbank `immorechner` sollte existieren
### Datenbank überprüfen
```bash
# In Container einloggen
docker-compose exec db bash
# MariaDB-Client starten
mariadb -u root -proot immorechner
# Tabellen anzeigen
SHOW TABLES;
# Bundesländer überprüfen (sollte 16 Einträge haben)
SELECT COUNT(*) FROM bundeslaender;
# Heizungstypen überprüfen (sollte 4 Einträge haben)
SELECT COUNT(*) FROM heizungstypen;
# Beenden
EXIT;
```
## Erste Schritte nach der Installation
### 1. Testbenutzer anlegen
#### Via Frontend (Empfohlen)
1. Öffnen Sie http://localhost:8080/register
2. Registrieren Sie sich mit:
- Name: "Test User"
- E-Mail: "test@example.com"
- Passwort: "test123" (min. 6 Zeichen)
3. Nach der Registrierung werden Sie zum Login weitergeleitet
4. Melden Sie sich an
#### Via API
```bash
curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{
"name": "Test User",
"email": "test@example.com",
"role": "user"
}'
```
**Hinweis:** Die API-Response enthält den `apiKey`, den Sie für API-Anfragen benötigen.
### 2. Erste Immobilie berechnen
#### Via Frontend
1. Gehen Sie zu http://localhost:8080/
2. Füllen Sie das Formular aus (mindestens: Adresse, Kaufpreis, Wohnfläche)
3. Sehen Sie die Live-Berechnungen rechts
4. Optional: Klicken Sie auf "Link teilen" zum Teilen
5. Wenn angemeldet: Klicken Sie auf "Speichern"
#### Via API
```bash
# Ersetzen Sie YOUR_API_KEY mit dem API-Key aus Schritt 1
curl -X POST http://localhost:8080/api/immobilies \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{
"verwalter": "/api/users/1",
"adresse": "Teststraße 123, 12345 Teststadt",
"wohnflaeche": 85,
"nutzflaeche": 15,
"zimmer": 3,
"typ": "wohnung",
"kaufpreis": 300000,
"bundesland": "/api/bundeslands/1"
}'
```
## Umgebungsvariablen anpassen
Die Datei `.env` enthält alle wichtigen Konfigurationen:
```env
# Symfony
APP_ENV=dev # Für Produktion: prod
APP_SECRET=<generiert> # Für Produktion: neu generieren
# Datenbank
DATABASE_URL="mysql://immorechner_user:immorechner_pass@db:3306/immorechner?serverVersion=mariadb-11.7.1&charset=utf8mb4"
# CORS (nur für API relevant)
CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
```
### Für Produktion
Erstellen Sie eine `.env.local` Datei (wird von Git ignoriert):
```env
APP_ENV=prod
APP_SECRET=<neue-generierte-secret-hier>
DATABASE_URL="mysql://prod_user:sichere_passwort@db-host:3306/prod_db?serverVersion=mariadb-11.7.1&charset=utf8mb4"
CORS_ALLOW_ORIGIN='^https?://(ihre-domain\.com)(:[0-9]+)?$'
```
## Ports anpassen
Falls die Standard-Ports bereits belegt sind, können Sie diese in `docker-compose.yml` ändern:
```yaml
services:
web:
ports:
- "8090:80" # Statt 8080:80
db:
ports:
- "3307:3306" # Statt 3306:3306
phpmyadmin:
ports:
- "8091:80" # Statt 8081:80
```
## Häufige Probleme bei der Installation
### Container starten nicht
```bash
# Container-Logs prüfen
docker-compose logs
# Spezifischen Container-Log prüfen
docker-compose logs web
docker-compose logs db
# Container-Status prüfen
docker ps -a
```
### "Permission Denied" Fehler
```bash
# Container neu bauen und Berechtigungen setzen
docker-compose down
docker-compose up -d --build
# Berechtigungen im Container setzen
docker-compose exec web chown -R www-data:www-data /var/www/html/var
```
### Datenbank-Verbindungsfehler
```bash
# Prüfen ob DB-Container läuft
docker ps | grep db
# DB-Logs prüfen
docker-compose logs db
# Warten bis DB bereit ist (kann 30-60 Sekunden dauern)
docker-compose exec web php bin/console doctrine:query:sql "SELECT 1"
```
### Composer-Fehler
```bash
# Composer Cache leeren
docker-compose exec web composer clear-cache
# Dependencies neu installieren
docker-compose exec web rm -rf vendor
docker-compose exec web composer install
```
## Deinstallation
### Nur Container stoppen
```bash
docker-compose down
```
### Container und Volumes löschen (Datenbank wird gelöscht!)
```bash
docker-compose down -v
```
### Alles entfernen (inkl. Images)
```bash
docker-compose down -v --rmi all
```
---
**Nächste Schritte:**
- [Features & Funktionalität](features.md) - Übersicht aller Funktionen
- [API-Dokumentation](api.md) - REST-API verwenden
- [Entwicklung](development.md) - Development-Workflow
[← Zurück zur Hauptseite](../README.md)

424
docs/technical.md Normal file
View File

@@ -0,0 +1,424 @@
# Technische Dokumentation
[← Zurück zur Hauptseite](../README.md)
## Technologie-Stack
- **Backend**: PHP 8.4
- **Framework**: Symfony 7.3
- **Datenbank**: MariaDB 11.7
- **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
- **Frontend**: jQuery 3.7.1, separates CSS/JS
## Architektur
### Schichtenmodell
```
┌─────────────────────────────────────┐
│ Presentation Layer │
│ (Twig Templates, CSS, JavaScript) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Controller Layer │
│ (HomeController, AuthController, │
│ ImmobilienSaveController) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Service Layer │
│ (Security, Validation, Business │
│ Logic) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Persistence Layer │
│ (Doctrine ORM, Repositories) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Database Layer │
│ (MariaDB) │
└─────────────────────────────────────┘
```
### Komponenten
#### Frontend
- **Templates:** `templates/` (Twig)
- **CSS:** `public/css/` (calculator.css, auth.css)
- **JavaScript:** `public/js/` (calculator.js mit jQuery)
#### Backend
- **Controller:** `src/Controller/` (Request Handling)
- **Entity:** `src/Entity/` (Datenmodelle)
- **Repository:** `src/Repository/` (Datenbank-Queries)
- **Security:** `src/Security/` (Authentifizierung)
- **Enum:** `src/Enum/` (PHP Enums)
## Datenbank-Schema
### Entity-Relationship-Diagram
```
┌──────────────┐ ┌────────────────┐
│ User │ 1 * │ Immobilie │
│──────────────│◄────────│────────────────│
│ id │ │ id │
│ name │ │ verwalter_id │
│ email │ │ adresse │
│ password │ │ wohnflaeche │
│ role │ │ nutzflaeche │
│ api_key │ │ zimmer │
│ created_at │ │ kaufpreis │
└──────────────┘ │ typ │
│ ... │
└────────────────┘
│
┌──────────────┴──────────────┐
│ │
▼ ▼
┌───────────────┐ ┌─────────────────┐
│ Bundesland │ │ Heizungstyp │
│───────────────│ │─────────────────│
│ id │ │ id │
│ name │ │ name │
│ grunderwerbst.│ └─────────────────┘
└───────────────┘
```
### Tabellen-Details
#### User-Tabelle
| Feld | Typ | Constraints | Beschreibung |
|------|-----|-------------|--------------|
| id | INT | PK, AUTO_INCREMENT | Eindeutige ID |
| name | VARCHAR(255) | NOT NULL | Benutzername |
| email | VARCHAR(255) | NOT NULL, UNIQUE | E-Mail-Adresse |
| password | VARCHAR(255) | NULL | Bcrypt-Hash des Passworts |
| role | VARCHAR(255) | NOT NULL | Benutzerrolle (Enum) |
| api_key | VARCHAR(64) | NOT NULL, UNIQUE | SHA256 API-Key |
| created_at | DATETIME | NOT NULL | Erstellungsdatum |
**Benutzerrollen (Enum):**
- `user` - Normaler Benutzer
- `admin` - Administrator
- `moderator` - Moderator
- `technical` - Technischer User
#### Bundesland-Tabelle
| Feld | Typ | Constraints | Beschreibung |
|------|-----|-------------|--------------|
| id | INT | PK, AUTO_INCREMENT | Eindeutige ID |
| name | VARCHAR(100) | NOT NULL, UNIQUE | Name des Bundeslandes |
| grunderwerbsteuer | DECIMAL(4,2) | NOT NULL | Steuersatz in % |
**Vorbefüllt mit 16 deutschen Bundesländern**
#### Heizungstyp-Tabelle
| Feld | Typ | Constraints | Beschreibung |
|------|-----|-------------|--------------|
| id | INT | PK, AUTO_INCREMENT | Eindeutige ID |
| name | VARCHAR(100) | NOT NULL, UNIQUE | Name des Heizungstyps |
**Vorbefüllt mit:** Ölheizung, Gasheizung, Wärmepumpe, Pelletheizung
#### Immobilien-Tabelle
| Feld | Typ | Constraints | Beschreibung |
|------|-----|-------------|--------------|
| id | INT | PK, AUTO_INCREMENT | Eindeutige ID |
| verwalter_id | INT | FK → users.id, NOT NULL | Besitzer der Immobilie |
| bundesland_id | INT | FK → bundeslaender.id, NULL | Bundesland |
| heizungstyp_id | INT | FK → heizungstypen.id, NULL | Heizungstyp |
| adresse | VARCHAR(255) | NOT NULL | Vollständige Adresse |
| wohnflaeche | INT | NOT NULL | Wohnfläche in m² |
| nutzflaeche | INT | NOT NULL | Nutzfläche in m² |
| garage | BOOLEAN | NOT NULL, DEFAULT false | Garage vorhanden? |
| zimmer | INT | NOT NULL | Anzahl Zimmer |
| baujahr | INT | NULL | Baujahr (1800-2100) |
| typ | VARCHAR(255) | NOT NULL | Immobilientyp (Enum) |
| beschreibung | TEXT | NULL | Freitextbeschreibung |
| etage | INT | NULL | Stockwerk (0-10) |
| kaufpreis | INT | NULL | Kaufpreis in Euro |
| abschreibungszeit | INT | NULL | Abschreibungszeit in Jahren |
| created_at | DATETIME | NOT NULL | Erstellungsdatum |
| updated_at | DATETIME | NOT NULL | Letzte Änderung |
**Immobilientyp (Enum):**
- `wohnung` - Wohnung
- `haus` - Haus
- `grundstueck` - Grundstück
- `gewerbe` - Gewerbe
- `buero` - Büro
### Indizes
```sql
-- User
CREATE UNIQUE INDEX UNIQ_1483A5E9E7927C74 ON users (email);
CREATE UNIQUE INDEX UNIQ_1483A5E9C912ED9D ON users (api_key);
-- Bundesland
CREATE UNIQUE INDEX UNIQ_DF7DFAB25E237E06 ON bundeslaender (name);
-- Heizungstyp
CREATE UNIQUE INDEX UNIQ_6161C2A65E237E06 ON heizungstypen (name);
-- Immobilie
CREATE INDEX IDX_2C789D3E5F66D3 ON immobilien (verwalter_id);
CREATE INDEX IDX_2C789DC1B4DB52 ON immobilien (heizungstyp_id);
CREATE INDEX IDX_2C789DB74FDBEB ON immobilien (bundesland_id);
```
## Konfiguration
### Umgebungsvariablen (.env)
```env
# Symfony
APP_ENV=dev # Umgebung: dev | prod | test
APP_SECRET=<32-zeichen-hex> # Symfony Secret für Verschlüsselung
# Datenbank
DATABASE_URL="mysql://immorechner_user:immorechner_pass@db:3306/immorechner?serverVersion=mariadb-11.7.1&charset=utf8mb4"
# Routing
DEFAULT_URI=http://localhost
# CORS (für API)
CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
```
### Services (config/services.yaml)
```yaml
services:
_defaults:
autowire: true
autoconfigure: true
App\:
resource: '../src/'
exclude:
- '../src/Entity/'
- '../src/Repository/'
- '../src/Kernel.php'
App\Controller\:
resource: '../src/Controller/'
tags: ['controller.service_arguments']
App\Repository\:
resource: '../src/Repository/'
```
### Security (config/packages/security.yaml)
```yaml
security:
password_hashers:
Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'
providers:
app_user_provider:
entity:
class: App\Entity\User
property: email
firewalls:
# API mit API-Key
api:
pattern: ^/api
stateless: true
custom_authenticators:
- App\Security\ApiKeyAuthenticator
# Frontend mit Form-Login
main:
lazy: true
provider: app_user_provider
form_login:
login_path: app_login
check_path: app_login
default_target_path: app_home
logout:
path: app_logout
target: app_home
```
### API Platform (config/packages/api_platform.yaml)
```yaml
api_platform:
title: 'Immorechner API'
version: 1.0.0
mapping:
paths: ['%kernel.project_dir%/src/Entity']
defaults:
stateless: true
formats:
jsonld: ['application/ld+json']
json: ['application/json']
```
## Docker-Konfiguration
### docker-compose.yml
```yaml
services:
web:
build: .
container_name: immorechner_web
ports:
- "8080:80"
volumes:
- .:/var/www/html
depends_on:
- db
db:
image: mariadb:latest
container_name: immorechner_db
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: immorechner
MYSQL_USER: immorechner_user
MYSQL_PASSWORD: immorechner_pass
ports:
- "3306:3306"
volumes:
- db_data:/var/lib/mysql
phpmyadmin:
image: phpmyadmin:latest
container_name: immorechner_phpmyadmin
ports:
- "8081:80"
environment:
PMA_HOST: db
PMA_USER: root
PMA_PASSWORD: root
```
### Dockerfile
```dockerfile
FROM php:8.4-apache
# Install dependencies
RUN apt-get update && apt-get install -y \
libpng-dev libonig-dev libxml2-dev libicu-dev \
libzip-dev git curl unzip
# Install PHP extensions
RUN docker-php-ext-install pdo_mysql mbstring exif \
pcntl bcmath gd zip intl opcache
# Enable Apache modules
RUN a2enmod rewrite headers
# Copy Composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
# Set working directory
WORKDIR /var/www/html
# Copy application
COPY . /var/www/html
# Set permissions
RUN chown -R www-data:www-data /var/www/html
```
## Performance-Optimierungen
### Opcache (Produktion)
In Produktion ist Opcache aktiviert:
```ini
opcache.enable=1
opcache.memory_consumption=256
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0
```
### Doctrine Query Cache
Doctrine nutzt automatisch Query-Cache in Produktion.
### Asset Compilation
Assets werden bei Deployment kompiliert:
```bash
php bin/console assets:install public --symlink --relative
```
## Sicherheit
### CSRF-Schutz
Alle Forms verwenden CSRF-Tokens:
```twig
<input type="hidden" name="_csrf_token" value="{{ csrf_token('authenticate') }}">
```
### Passwort-Hashing
Passwörter werden mit bcrypt gehasht:
```php
$hashedPassword = $passwordHasher->hashPassword($user, $password);
```
### API-Key-Generierung
API-Keys sind SHA256-Hashes:
```php
return hash('sha256', random_bytes(32).microtime(true));
```
### SQL-Injection-Schutz
Doctrine ORM verhindert SQL-Injection durch Prepared Statements.
### XSS-Schutz
Twig escaped automatisch alle Ausgaben.
## Migrations
Migrationen werden mit Doctrine Migrations verwaltet:
```bash
# Neue Migration erstellen
php bin/console doctrine:migrations:diff
# Migrationen ausführen
php bin/console doctrine:migrations:migrate
# Migration-Status anzeigen
php bin/console doctrine:migrations:status
```
---
**Siehe auch:**
- [Installation](installation.md) - Setup-Anleitung
- [Development](development.md) - Entwickler-Workflow
- [Docker](docker.md) - Container-Management
[← Zurück zur Hauptseite](../README.md)

432
docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,432 @@
# Fehlerbehebung
[← Zurück zur Hauptseite](../README.md)
## Häufige Probleme
### Frontend-Probleme
#### Seite lädt ohne CSS/JavaScript
**Problem:** Seite wird angezeigt, aber ohne Styling oder JavaScript-Funktionalität.
**Lösung:**
```bash
# 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
# Browser-Cache leeren (Strg+F5)
```
#### Live-Berechnungen funktionieren nicht
**Problem:** Formular-Eingaben triggern keine Berechnungen.
**Lösung:**
```bash
# Browser-Konsole öffnen (F12)
# Nach JavaScript-Fehlern suchen
# Prüfen ob jQuery geladen wurde
# Sollte in Netzwerk-Tab sichtbar sein: jquery-3.7.1.min.js
# calculator.js prüfen
curl http://localhost:8080/js/calculator.js
```
#### Login funktioniert nicht
**Problem:** Login-Formular gibt Fehler oder leitet nicht weiter.
**Lösung:**
```bash
# Cache leeren
docker-compose exec web php bin/console cache:clear
# Prüfen ob User existiert
docker-compose exec db mariadb -u root -proot -e "SELECT email FROM users" immorechner
# Session-Verzeichnis prüfen
docker-compose exec web ls -la /var/www/html/var/cache/dev/sessions
```
---
### API-Probleme
#### Swagger UI lädt ohne CSS
**Problem:** http://localhost:8080/api/docs.html lädt, aber ohne Formatierung.
**Lösung:**
```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
# Prüfen ob Assets existieren
docker-compose exec web ls -la /var/www/html/public/bundles/apiplatform
```
#### API gibt 401 Unauthorized
**Problem:** API-Anfrage mit API-Key schlägt fehl.
**Lösung:**
```bash
# API-Key prüfen
docker-compose exec db mariadb -u root -proot -e "SELECT id, email, api_key FROM users" immorechner
# Korrekten Header verwenden
curl -H "X-API-KEY: ihr-api-key" http://localhost:8080/api/immobilies
# Nicht "Authorization" Header!
```
#### API gibt 500 Internal Server Error
**Problem:** API-Anfrage schlägt mit Server-Fehler fehl.
**Lösung:**
```bash
# Logs prüfen
docker-compose logs web
# Symfony Logs prüfen
docker-compose exec web tail -f /var/www/html/var/log/dev.log
# Datenbank-Verbindung testen
docker-compose exec web php bin/console doctrine:query:sql "SELECT 1"
```
---
### Datenbank-Probleme
#### Connection refused
**Problem:** Kann nicht zur Datenbank verbinden.
**Lösung:**
```bash
# DB-Container läuft?
docker ps | grep db
# DB-Container-Logs
docker-compose logs db
# Warten (DB braucht ~30-60 Sekunden)
sleep 60
# DB-Verbindung testen
docker-compose exec db mariadb -u root -proot -e "SELECT 1"
# Neustart
docker-compose restart db
```
#### Migrations schlagen fehl
**Problem:** `doctrine:migrations:migrate` gibt Fehler.
**Lösung:**
```bash
# Migration-Status prüfen
docker-compose exec web php bin/console doctrine:migrations:status
# Datenbank droppen und neu erstellen
docker-compose exec web php bin/console doctrine:database:drop --force
docker-compose exec web php bin/console doctrine:database:create
docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction
# Oder: Container komplett neu aufsetzen
docker-compose down -v
docker-compose up -d --build
docker-compose exec web composer install
docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction
```
#### Tabellen fehlen
**Problem:** "Table 'immorechner.users' doesn't exist"
**Lösung:**
```bash
# Migrations ausführen
docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction
# Tabellen prüfen
docker-compose exec db mariadb -u root -proot -e "SHOW TABLES" immorechner
# Falls leer: Migration erneut ausführen
docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction
```
---
### Docker-Probleme
#### Container starten nicht
**Problem:** `docker-compose up` schlägt fehl.
**Lösung:**
```bash
# Logs prüfen
docker-compose logs
# Alte Container stoppen
docker-compose down
# Neu starten mit Build
docker-compose up -d --build
# Docker neu starten
# Windows: Docker Desktop neu starten
# Linux: sudo systemctl restart docker
```
#### Port bereits belegt
**Problem:** "Port 8080 is already allocated"
**Lösung 1 - Port freigeben:**
```bash
# Windows
netstat -ano | findstr :8080
taskkill /PID <prozess-id> /F
# Linux/Mac
lsof -i :8080
kill -9 <prozess-id>
```
**Lösung 2 - Port ändern:**
```yaml
# In docker-compose.yml
services:
web:
ports:
- "8090:80" # Statt 8080:80
```
#### Volumes löschen nicht möglich
**Problem:** "Volume is in use"
**Lösung:**
```bash
# Alle Container stoppen
docker-compose down
# Volume prüfen
docker volume ls
# Container mit Volume finden
docker ps -a --filter volume=immorechner_db_data
# Container löschen
docker rm <container-id>
# Volume löschen
docker volume rm immorechner_db_data
```
---
### Composer-Probleme
#### "Class not found" Fehler
**Problem:** PHP kann Klasse nicht finden.
**Lösung:**
```bash
# Autoloader neu generieren
docker-compose exec web composer dump-autoload
# Cache leeren
docker-compose exec web php bin/console cache:clear
# Dependencies neu installieren
docker-compose exec web rm -rf vendor
docker-compose exec web composer install
```
#### Composer sehr langsam
**Problem:** `composer install` braucht ewig.
**Lösung:**
```bash
# Im Container ausführen (schneller als via Volume)
docker-compose exec web composer install
# Cache leeren
docker-compose exec web composer clear-cache
# Parallel Downloads aktivieren
docker-compose exec web composer config --global process-timeout 2000
docker-compose exec web composer config --global repos.packagist composer https://packagist.org
```
---
### Berechtigungs-Probleme
#### "Permission denied" in var/
**Problem:** Kann nicht in `var/cache` oder `var/log` schreiben.
**Lösung:**
```bash
# Berechtigungen setzen
docker-compose exec -u root web chown -R www-data:www-data /var/www/html/var
# Oder: 777 Rechte (nur Development!)
docker-compose exec -u root web chmod -R 777 /var/www/html/var
# Cache neu erstellen
docker-compose exec web php bin/console cache:clear
```
---
### Performance-Probleme
#### Seite lädt sehr langsam
**Problem:** Frontend/API antwortet langsam.
**Lösung:**
```bash
# Opcache Status prüfen
docker-compose exec web php -i | grep opcache
# Cache warmup
docker-compose exec web php bin/console cache:warmup
# Für Produktion: APP_ENV=prod setzen in .env
# Opcache aktiviert sich automatisch
# Docker-Resources erhöhen
# Docker Desktop -> Settings -> Resources -> Memory: 4GB+
```
#### Datenbank-Queries langsam
**Problem:** API-Anfragen langsam bei vielen Datensätzen.
**Lösung:**
```bash
# Indizes prüfen
docker-compose exec web php bin/console doctrine:schema:validate
# Query-Log aktivieren (temporär)
# In config/packages/doctrine.yaml:
logging: true
profiling: true
# Slow Query Log in MariaDB aktivieren
docker-compose exec db mariadb -u root -proot -e "SET GLOBAL slow_query_log = 'ON'"
```
---
### Browser-Probleme
#### Alte Daten werden angezeigt
**Problem:** Änderungen werden nicht sichtbar.
**Lösung:**
```bash
# Browser-Cache leeren
# Chrome/Firefox: Strg+Shift+Delete
# Hard Reload
# Chrome/Firefox: Strg+F5
# Mac: Cmd+Shift+R
# Server-Cache leeren
docker-compose exec web php bin/console cache:clear
```
---
## Debug-Modus aktivieren
```bash
# .env
APP_ENV=dev
APP_DEBUG=true
# Cache leeren
docker-compose exec web php bin/console cache:clear
# Symfony Profiler in Browser verwenden
# Unten auf der Seite erscheint Toolbar
```
## Komplett-Reset (Letzter Ausweg)
**WARNUNG:** Löscht alle Daten!
```bash
# Alles stoppen und löschen
docker-compose down -v
# Docker-Images löschen
docker rmi immorechner-web
# Neu aufbauen
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
# Cache leeren
docker-compose exec web php bin/console cache:clear
```
---
## Support
Wenn das Problem weiterhin besteht:
1. **Logs sammeln:**
```bash
docker-compose logs > debug_logs.txt
```
2. **Systeminfo sammeln:**
```bash
docker version > system_info.txt
docker-compose version >> system_info.txt
php -v >> system_info.txt
```
3. **Issue erstellen** mit:
- Problembeschreibung
- Fehlermeldung
- Logs (debug_logs.txt)
- Systeminfo (system_info.txt)
- Schritte zum Reproduzieren
---
**Siehe auch:**
- [Docker](docker.md) - Container-Management
- [Development](development.md) - Entwickler-Workflow
- [Installation](installation.md) - Setup-Anleitung
[← Zurück zur Hauptseite](../README.md)