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