# TerraFlow CMS - Route System Dokumentation

## Übersicht

Das TerraFlow CMS verwendet ein flexibles, datenbankbasiertes Route-System, das es ermöglicht, URLs für verschiedene Content-Typen zentral zu verwalten und anzupassen.

## Architektur

### Datenbank-Struktur

Die Route-Informationen werden in der `routes` Tabelle gespeichert:

```sql
CREATE TABLE routes (
    id INT AUTO_INCREMENT NOT NULL,
    path VARCHAR(255) NOT NULL,
    entity_type VARCHAR(50) NOT NULL,
    entity_id INT NOT NULL,
    active TINYINT(1) NOT NULL,
    is_landing TINYINT(1) NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME DEFAULT NULL,
    UNIQUE INDEX UNIQ_PATH (path),
    INDEX IDX_ENTITY (entity_type, entity_id),
    PRIMARY KEY(id)
)
```

### Wichtige Komponenten

#### 1. Route Entity (`src/Entity/Route.php`)

Die Route-Entity repräsentiert eine einzelne Route im System:

- `path`: Der URL-Pfad (z.B. "about-us" oder "category/news")
- `entityType`: Der Typ des verlinkten Inhalts ("page" oder "category")
- `entityId`: Die ID der verlinkten Entity
- `active`: Ob die Route aktiv ist
- `isLanding`: Ob dies die Landing Page (/) ist

#### 2. RouteService (`src/Service/RouteService.php`)

Der RouteService ist die zentrale Schnittstelle für alle Route-Operationen:

**Hauptmethoden:**

```php
// Route-Lookup
public function findEntityByPath(string $path): ?array
public function findLandingPage(): ?array

// Route-Management
public function createOrUpdatePageRoute(Page $page, string $path, bool $isLanding = false): Route
public function createOrUpdateCategoryRoute(Category $category, string $path): Route
public function deleteRoute(string $entityType, int $entityId): void

// Hilfsfunktionen
public function generateSlug(string $text): string
public function generateUniquePath(string $basePath): string
```

#### 3. Twig Extension (`src/Twig/RouteExtension.php`)

Bietet Twig-Funktionen für Templates:

```twig
{# Hole den Route-Pfad #}
{{ get_page_route(page) }}
{{ get_category_route(category) }}

{# Hole die vollständige URL #}
{{ get_page_url(page) }}
{{ get_category_url(category) }}

{# Prüfe ob Landing Page #}
{% if is_landing_page(page) %}
    <!-- Special handling -->
{% endif %}
```

## Verwendung

### Pages

#### Neue Page erstellen

Wenn eine neue Page über den Admin-Bereich erstellt wird:

1. User gibt Titel und optional einen Route-Path ein
2. Wenn kein Path angegeben wurde, wird er aus dem Titel generiert
3. Bei Landing Pages ist der Path leer (`''`)
4. Der RouteService erstellt automatisch eine Route-Entity

```php
// Im AdminController
$routePath = $form->get('routePath')->getData();
$isLanding = $form->get('isLanding')->getData();

$page->setCreatedAt(new \DateTime());
$entityManager->persist($page);
$entityManager->flush();

$finalPath = $isLanding ? '' : ($routePath ?: $this->routeService->generateUniquePath($page->getTitle()));
$this->routeService->createOrUpdatePageRoute($page, $finalPath, $isLanding);
```

#### Page bearbeiten

Das gleiche Prinzip gilt beim Bearbeiten - die Route wird über den RouteService aktualisiert.

### Categories

Categories funktionieren ähnlich, können aber keine Landing Pages sein:

```php
$routePath = $form->get('routePath')->getData();
$this->routeService->createOrUpdateCategoryRoute($category, $routePath);
```

### Im Storefront-Controller

Der StorefrontController nutzt den RouteService für Content-Lookup:

```php
public function page(string $route): Response
{
    $routeData = $this->routeService->findEntityByPath($route);
    
    if (!$routeData) {
        return $this->redirect('/404');
    }
    
    return match($routeData['type']) {
        'page' => $this->renderPage($pageRepository->find($routeData['id'])),
        'category' => $this->renderCategory($categoryRepository->find($routeData['id'])),
        default => $this->redirect('/404')
    };
}
```

### Landing Page

Die Landing Page (`/`) wird speziell behandelt:

```php
public function index(): Response
{
    $landingPageData = $this->routeService->findLandingPage();
    
    if (!$landingPageData) {
        // Zeige Default-Welcome-Page
    }
    
    // Route zu entsprechendem Entity
}
```

## Migration von altem System

Die Migration erfolgte automatisch durch den `MigrateRoutesCommand`:

```bash
php bin/console terraflow:routes:migrate
```

Dieser Command:
1. Erstellt die `routes` Tabelle
2. Migriert alle bestehenden Pages mit ihren Routes
3. Migriert alle Categories mit generierten Routes
4. Setzt automatisch die erste Page als Landing Page

## Best Practices

### 1. Eindeutige Paths

- Paths müssen eindeutig sein
- Der RouteService hat eingebaute Collision-Detection
- `generateUniquePath()` fügt automatisch Suffixe hinzu wenn nötig

### 2. URL-Struktur

Empfohlene Konventionen:
- Pages: `about-us`, `contact`, `services/web-development`
- Categories: `category/news`, `category/blog/tech`
- Landing Page: leer (`''`)

### 3. Cache-Invalidierung

Nach Route-Änderungen sollte der Cache invalidiert werden:

```php
$this->cacheService->invalidateTags(['routes', 'page_' . $page->getId()]);
```

### 4. Slug-Generierung

Der RouteService generiert SEO-freundliche Slugs:
- Umlaute werden konvertiert (ä → ae, ö → oe)
- Sonderzeichen werden entfernt
- Leerzeichen werden durch Bindestriche ersetzt
- Alles wird kleingeschrieben

## Fehlerbehandlung

### Route-Konflikte

Bei doppelten Paths wirft der RouteService eine Exception:

```php
try {
    $this->routeService->createOrUpdatePageRoute($page, $path, false);
} catch (\Exception $e) {
    $this->addFlash('error', 'Fehler beim Erstellen der Route: ' . $e->getMessage());
}
```

### 404-Handling

Wenn keine Route gefunden wird:
1. Prüfe auf Redirects in der `Redirect`-Entity
2. Wenn kein Redirect existiert, zeige 404-Page
3. 404-Page kann selbst eine Route haben (`/404`)

## Performance

### Caching

- Routes werden gecacht für schnellen Lookup
- Cache-Keys: `routes`, `route_{path}`
- TTL: Konfigurierbar über CacheService

### Datenbank-Indizes

Die Tabelle hat optimierte Indizes:
- `UNIQUE INDEX` auf `path` für schnelle Lookups
- `INDEX` auf `(entity_type, entity_id)` für Entity-Queries

## Erweiterbarkeit

### Neue Entity-Typen

Um neue Content-Typen zu unterstützen:

1. Füge entsprechende Methoden im RouteService hinzu:
```php
public function createOrUpdateCustomRoute(CustomEntity $entity, string $path): Route
{
    return $this->createOrUpdateRoute('custom', $entity->getId(), $path);
}
```

2. Erweitere den StorefrontController:
```php
return match($routeData['type']) {
    'page' => ...,
    'category' => ...,
    'custom' => $this->renderCustom(...),
    default => $this->redirect('/404')
};
```

3. Füge Twig-Funktionen hinzu wenn nötig

## Zusammenfassung

Das neue Route-System bietet:
- ✅ Zentrale Verwaltung aller URLs
- ✅ Flexible Content-Zuordnung
- ✅ SEO-freundliche Slug-Generierung
- ✅ Landing Page Support
- ✅ Einfache Erweiterbarkeit
- ✅ Performance durch Caching
- ✅ Template-Integration via Twig-Extension