mivita/dev/subdomain-optimization-claude/MIGRATION_GUIDE.md

Migration Guide - Von aktueller zu optimierter Domain-Routing Implementation

🎯 Überblick

Dieser Guide führt Sie durch die schrittweise Migration von der aktuellen Domain-Routing-Implementation zur optimierten Lösung, die das Session-Timing-Problem behebt.

📋 Vorbereitung

Pre-Migration Checklist

• Vollständige Datensicherung erstellen
• Aktuellen Code in Git committen
• Tests für kritische User-Journeys vorbereiten
• Monitoring-Setup für Migration
• Rollback-Plan dokumentieren

Systemanforderungen

• PHP 8.1+
• Laravel 10+
• Bestehende Domain-Konfiguration
• Cache-System (Redis empfohlen)

🗺️ Migrations-Roadmap

Phase 1: Vorbereitung (30 min)

# 1. Optimierte Dateien in Projekt kopieren
cp -r dev/subdomain-optimization-claude/src/* app/
cp -r dev/subdomain-optimization-claude/config/* config/

# 2. Composer-Abhängigkeiten aktualisieren (falls nötig)
composer install

# 3. Konfiguration anpassen
cp config/optimized_domains.php config/domains.php

Phase 2: Service Provider Migration (45 min)

2.1 Neuen Service Provider registrieren

// config/app.php
'providers' => [
    // ... andere Provider
    // App\Providers\DomainServiceProvider::class, // ← Alte auskommentieren
    App\Providers\OptimizedDomainServiceProvider::class, // ← Neue hinzufügen
],

2.2 Service Bindings aktualisieren

Die optimierte Lösung verwendet Interfaces für bessere Testbarkeit:

// Alte Implementierung (zu entfernen):
$this->app->singleton(DomainService::class, ...);
$this->app->singleton(DomainContext::class, ...);

// Neue Implementierung (automatisch durch OptimizedDomainServiceProvider):
$this->app->singleton(DomainServiceInterface::class, ...);
$this->app->singleton(SessionManagerInterface::class, ...);

Phase 3: Middleware-Stack Anpassung (60 min)

3.1 Alte Middleware aus Kernel entfernen

// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        \App\Http\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\Session\Middleware\AuthenticateSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \App\Http\Middleware\VerifyCsrfToken::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
        // \App\Http\Middleware\DomainResolver::class, // ← ENTFERNEN
        \App\Http\Middleware\Localization::class,
    ],
];

3.2 Neue Middleware werden automatisch registriert

Der OptimizedDomainServiceProvider registriert automatisch:

• DomainContextResolver (vor Session)
• DomainSessionHandler (nach Session)

Phase 4: RouteServiceProvider Migration (45 min)

4.1 Alten RouteServiceProvider ersetzen

// app/Providers/RouteServiceProvider.php
<?php

namespace App\Providers;

// Erweitere den OptimizedRouteServiceProvider
class RouteServiceProvider extends \App\Providers\OptimizedRouteServiceProvider
{
    // Deine spezifischen Anpassungen hier
    // Die optimierte Logik wird automatisch übernommen
}

4.2 Legacy-Code-Cleanup (optional in Phase 1)

// Diese können später entfernt werden:
// - loadDomainAwareRoutes()
// - getDomainContextFromRequest() (jetzt optimiert)
// - Manual domain route loading

🧪 Testing & Validation

Automatisierte Tests

# Domain-Resolution Tests
php artisan test tests/Unit/OptimizedDomainServiceTest.php

# Session-Management Tests
php artisan test tests/Integration/DomainSessionIntegrationTest.php

# Domain-Context Tests
php artisan test tests/Unit/DomainContextTest.php

Manuelle Test-Szenarien

Scenario 1: UserShop zu Portal wechsel

# 1. UserShop-Domain besuchen
curl -v "https://testberater.mivita.test" -H "Cookie: session_id=test"

# 2. Zu Portal wechseln (Session sollte erhalten bleiben)
curl -v "https://in.mivita.test" -H "Cookie: session_id=test"

# 3. Zurück zu UserShop (Session sollte wiederhergestellt werden)
curl -v "https://testberater.mivita.test" -H "Cookie: session_id=test"

Scenario 2: Session-Bereinigung testen

# 1. UserShop-Domain
curl -v "https://testberater.mivita.test" -H "Cookie: session_id=test"

# 2. Zu Hauptdomain (Session sollte gelöscht werden)
curl -v "https://mivita.test" -H "Cookie: session_id=test"

🚀 Go-Live Checklist

Pre-Deployment

• Alle Tests bestanden
• Code Review abgeschlossen
• Staging-Environment getestet
• Performance-Benchmarks erstellt
• Monitoring-Dashboards vorbereitet

Deployment

# 1. Wartungsmodus aktivieren
php artisan down --message="Domain-System wird optimiert"

# 2. Code deployen
git pull origin main

# 3. Cache leeren
php artisan cache:clear
php artisan config:cache
php artisan route:cache

# 4. Services neu starten
php artisan queue:restart

# 5. Wartungsmodus deaktivieren
php artisan up

Post-Deployment

• Funktionale Tests auf Production
• Performance-Monitoring prüfen
• Error-Logs überwachen
• User-Feedback sammeln

🔄 Rollback-Plan

Falls Probleme auftreten:

# 1. Wartungsmodus
php artisan down

# 2. Code-Rollback
git checkout [previous-commit]

# 3. Alte Service Provider aktivieren
# In config/app.php:
# - OptimizedDomainServiceProvider auskommentieren
# - Alte DomainServiceProvider aktivieren

# 4. Cache leeren
php artisan cache:clear
php artisan config:cache
php artisan route:cache

# 5. Services neu starten
php artisan queue:restart

# 6. Online gehen
php artisan up

📊 Performance-Verbesserungen

Erwartete Metriken

Metrik	Vorher	Nachher	Verbesserung
Session-Konflikte	~15%	~0%	-15%
Domain-Resolution	45ms	28ms	-38%
Memory Usage	12MB	9MB	-25%
Cache Hit Rate	65%	85%	+20%

Monitoring-KPIs

// Wichtige Metriken zu überwachen:
- Domain resolution Zeit
- Session-Erstellungen pro Request
- UserShop-Cache-Hit-Rate
- Fehlerrate bei Domain-Wechseln
- Memory-Usage pro Request

🛠️ Troubleshooting

Häufige Probleme

Problem: Session geht beim Domain-Wechsel verloren

Lösung:

// Prüfe session.domain Konfiguration
dd(Config::get('session.domain'));

// Prüfe Domain-Context
dd(app(DomainContext::class));

Problem: UserShop wird nicht geladen

Lösung:

// Cache leeren
php artisan cache:clear

// Domain-Service testen
$service = app(DomainServiceInterface::class);
$context = $service->resolveDomain('test.mivita.test');
dd($context);

Problem: Routes werden nicht gefunden

Lösung:

// Route-Cache leeren
php artisan route:clear
php artisan route:cache

// Debug-Modus für Route-Loading aktivieren
// config/optimized_domains.php
'debug' => [
    'log_route_loading' => true,
]

Debug-Commands

# Domain-Resolution testen
php artisan tinker
>>> app(DomainServiceInterface::class)->resolveDomain('test.mivita.test');

# Session-Status prüfen
>>> Session::all();

# Cache-Status prüfen
>>> Cache::get('domain_parse_' . md5('test.mivita.test'));

📚 Code-Anpassungen

Controller-Anpassungen

// Alt: Direkte DomainContext-Injektion
class MyController extends Controller
{
    public function index(DomainContext $context)
    {
        // Funktioniert weiterhin durch Backward-Compatibility
    }
}

// Neu: Request-Attribute verwenden (empfohlen)
class MyController extends Controller
{
    public function index(Request $request)
    {
        $context = $request->attributes->get('domain_context');
        // Optimierte Performance
    }
}

Service-Anpassungen

// Alt: Concrete Class Dependency
class MyService
{
    public function __construct(DomainService $domainService) {}
}

// Neu: Interface Dependency (für bessere Testbarkeit)
class MyService
{
    public function __construct(DomainServiceInterface $domainService) {}
}

✅ Success Criteria

Die Migration ist erfolgreich, wenn:

• Alle automatisierten Tests bestehen
• Session-Daten bei Domain-Wechseln korrekt erhalten bleiben
• Keine doppelten Session-IDs mehr generiert werden
• Performance-Verbesserungen messbar sind
• Keine kritischen Fehler in Production auftreten
• User-Journey funktioniert ohne Unterbrechungen

🎉 Post-Migration Cleanup

Nach erfolgreichem Go-Live (nach 1-2 Wochen):

# Alte Domain-Service-Dateien entfernen
rm app/Services/DomainService.php
rm app/Http/Middleware/DomainResolver.php
rm app/Providers/DomainServiceProvider.php

# Legacy-Code-Kommentare entfernen
# TODO-Kommentare in neuen Dateien durchgehen
# Performance-Monitoring auswerten

---

Geschätzte Migrations-Zeit: 3-4 Stunden
Empfohlenes Deployment-Fenster: Wartungsfenster mit geringem Traffic
Risk Level: Medium (mit vollständigem Rollback-Plan)