# 🚀 Route-Refactoring Guide für TerraFlow CMS

## ✅ Was wurde implementiert:

### 1. Neue Route Entity (`src/Entity/Route.php`)
- Zentrale Verwaltung aller URLs im System
- Unterstützt Pages und Categories
- Automatische Landing-Page-Verwaltung
- URL-Validierung und Normalisierung

### 2. Route Repository (`src/Repository/RouteRepository.php`)
- Optimierte Abfragen für Route-Lookups
- Duplikat-Erkennung
- Entity-Typ-spezifische Queries

### 3. Route Service (`src/Service/RouteService.php`)
- High-Level API für Route-Verwaltung
- Automatische Slug-Generierung
- Eindeutigkeits-Prüfung
- Landing-Page-Koordination

### 4. Datenbank-Migration (`migrations/Version20251017171100.php`)
- Erstellt `routes` Tabelle
- Migriert existierende Page-Routen
- Migriert Category-Routen
- Entfernt alte route/landingPage Felder

### 5. Entity-Updates
- **Page**: Entfernt `route` und `landingPage` Felder
- **Category**: Vorbereitet für Route-Integration

---

## 📋 Nächste Schritte (TODOs):

### Phase 1: Datenbank-Migration ausführen

```bash
# Migration ausführen
php bin/console doctrine:migrations:migrate

# Prüfen ob alles geklappt hat
php bin/console doctrine:schema:validate
```

### Phase 2: Controller Updates

#### StorefrontController aktualisieren:

```php
// Alt:
$page = $entityManager->getRepository(Page::class)->findOneBy(['route' => $route]);

// Neu:
$routeEntity = $routeService->findEntityByPath($route);
if ($routeEntity && $routeEntity['type'] === 'page') {
    $page = $entityManager->getRepository(Page::class)->find($routeEntity['id']);
}
```

#### AdminController Page-Methoden aktualisieren:

```php
// newPage() - Route erstellen:
public function newPage(Request $request, EntityManagerInterface $em, RouteService $routeService): Response
{
    // ... Form-Handling ...
    
    if ($form->isSubmitted() && $form->isValid()) {
        $em->persist($page);
        $em->flush();
        
        // Route erstellen
        $path = $form->get('routePath')->getData();
        $isLanding = $form->get('isLanding')->getData();
        $routeService->createOrUpdatePageRoute($page, $path, $isLanding);
        
        // ...
    }
}
```

### Phase 3: Form-Updates

#### PageType.php anpassen:

```php
$builder
    ->add('routePath', TextType::class, [
        'label' => 'form.page.route',
        'required' => false,
        'mapped' => false
    ])
    ->add('isLanding', CheckboxType::class, [
        'label' => 'form.page.landing_page',
        'required' => false,
        'mapped' => false
    ])
    // ... rest bleibt gleich
```

#### CategoryType.php anpassen:

```php
$builder
    ->add('routePath', TextType::class, [
        'label' => 'form.category.route',
        'required' => true,
        'mapped' => false
    ])
    // ... rest bleibt gleich
```

### Phase 4: Template-Updates

#### edit_page.html.twig:

```twig
{# Ersetze route-Feld durch routePath #}
<div class="mb-4">
    {{ form_label(form.routePath, 'form.page.route'|trans) }}
    {{ form_widget(form.routePath, {'attr': {'class': 'form-control'}}) }}
</div>

<div class="mb-4 form-check">
    {{ form_widget(form.isLanding, {'attr': {'class': 'form-check-input'}}) }}
    {{ form_label(form.isLanding, 'form.page.landing_page'|trans) }}
</div>
```

#### edit_category.html.twig:

```twig
{# Füge Route-Feld hinzu #}
<div class="mb-4">
    {{ form_label(form.routePath, 'form.category.route'|trans) }}
    {{ form_widget(form.routePath, {'attr': {'class': 'form-control'}}) }}
    <small class="text-muted">Beispiel: immobilien/wohnungen</small>
</div>
```

### Phase 5: Twig Extension Update

#### Neue Helper-Funktionen hinzufügen:

```php
// src/Twig/RouteExtension.php
class RouteExtension extends AbstractExtension
{
    public function __construct(private RouteService $routeService) {}
    
    public function getFunctions(): array
    {
        return [
            new TwigFunction('get_page_route', [$this, 'getPageRoute']),
            new TwigFunction('get_category_route', [$this, 'getCategoryRoute']),
        ];
    }
    
    public function getPageRoute(Page $page): ?string
    {
        $route = $this->routeService->getPageRoute($page);
        return $route?->getFullPath();
    }
    
    public function getCategoryRoute(Category $category): ?string
    {
        $route = $this->routeService->getCategoryRoute($category);
        return $route?->getFullPath();
    }
}
```

### Phase 6: Cache-Invalidierung

Nach Route-Änderungen Cache leeren:

```php
// Nach Route-Update:
$this->cacheService->invalidateTags(['routes', 'navigation', 'page_' . $page->getId()]);
```

---

## 🔧 Verwendungsbeispiele:

### 1. Page mit Route erstellen:

```php
$page = new Page();
$page->setTitle('Meine neue Seite');
$page->setContent('Inhalt...');
$page->setActive(true);

$em->persist($page);
$em->flush();

// Route erstellen
$routeService->createOrUpdatePageRoute($page, 'meine-neue-seite', false);
```

### 2. Landing Page setzen:

```php
$routeService->createOrUpdatePageRoute($page, '', true);
```

### 3. Category mit Route:

```php
$category = new Category();
$category->setTitle('Immobilien');
$category->setActive(true);

$em->persist($category);
$em->flush();

$routeService->createOrUpdateCategoryRoute($category, 'immobilien');
```

### 4. Route finden:

```php
// Im StorefrontController:
$routeData = $routeService->findEntityByPath($path);

if ($routeData) {
    match($routeData['type']) {
        'page' => $this->renderPage($em->getRepository(Page::class)->find($routeData['id'])),
        'category' => $this->renderCategory($em->getRepository(Category::class)->find($routeData['id'])),
    };
}
```

---

## ⚠️ Breaking Changes:

### 1. **Page Entity**:
- ❌ `$page->getRoute()` - Nicht mehr verfügbar
- ❌ `$page->setRoute()` - Nicht mehr verfügbar  
- ❌ `$page->isLandingPage()` - Nicht mehr verfügbar
- ✅ Use: `$routeService->getPageRoute($page)`

### 2. **Category Entity**:
- ❌ `$category->getRoute()` - Gibt jetzt Route-String zurück statt zu generieren
- ✅ Use: `$routeService->getCategoryRoute($category)`

### 3. **Templates**:
- Ersetze `{{ page.route }}` durch `{{ get_page_route(page) }}`
- Ersetze `{{ category.route }}` durch `{{ get_category_route(category) }}`

---

## 🎯 Vorteile des neuen Systems:

✅ **Zentrale Verwaltung**: Alle Routen an einem Ort
✅ **Duplikat-Prävention**: Automatische Prüfung auf doppelte URLs
✅ **Einfache Umleitung**: Alt-Routen können beibehalten werden
✅ **Performance**: Optimierte DB-Queries mit Indizes
✅ **Flexibilität**: Einfach erweiterbar für neue Entity-Typen
✅ **SEO**: Bessere URL-Verwaltung und 301-Redirects
✅ **Maintenance**: Einfacheres Debugging von Routing-Problemen

---

## 📝 Zusätzliche Features (Optional):

### 1. Route History Tracking:
```sql
CREATE TABLE route_history (
    id INT AUTO_INCREMENT PRIMARY KEY,
    old_path VARCHAR(255),
    new_path VARCHAR(255),
    entity_type VARCHAR(50),
    entity_id INT,
    changed_at DATETIME
);
```

### 2. Automatic 301 Redirects:
Wenn eine Route geändert wird, automatisch Redirect erstellen.

### 3. Route Analytics:
Tracking welche Routen am meisten aufgerufen werden.

---

## 🐛 Troubleshooting:

### Problem: Migration schlägt fehl
```bash
# Prüfe existierende Daten:
SELECT COUNT(*) FROM page WHERE route IS NULL;

# Fixe NULL-Werte:
UPDATE page SET route = CONCAT('content/', id) WHERE route IS NULL;
```

### Problem: Doppelte Routen
```bash
# Finde Duplikate:
php bin/console doctrine:query:sql "SELECT path, COUNT(*) as count FROM routes GROUP BY path HAVING count > 1"

# Bereinige manuell oder mit Script
```

### Problem: 404 Fehler nach Migration
```bash
# Cache leeren:
php bin/console cache:clear

# Routes neu erstellen:
php bin/console app:rebuild-routes
```

---

## 📞 Support:

Bei Fragen oder Problemen:
1. Prüfe die Logs: `var/log/dev.log`
2. Validiere DB-Schema: `php bin/console doctrine:schema:validate`
3. Prüfe Migration-Status: `php bin/console doctrine:migrations:status`

**Version**: 1.0.0  
**Erstellt**: 2025-10-17  
**Autor**: Claude (AI Assistant)