First commit

packages/flux-cms/ARCHITECTURE.md

@@ -0,0 +1,786 @@
+# Flux CMS - Architecture Documentation
+
+## Überblick
+
+Flux CMS ist ein modular aufgebautes Content Management System für Laravel 12 mit Livewire 3 und Flux UI. Das System folgt einem "Code-as-Schema" Ansatz, bei dem Component-Felder direkt in PHP-Klassen definiert werden statt in der Datenbank.
+
+## Architektur-Prinzipien
+
+### 1. **Modularität**
+- Package-basierte Architektur mit separaten Modulen
+- Klare Trennung von Core, Components und Starter Components
+- Erweiterbar durch zusätzliche Packages
+
+### 2. **Code-as-Schema**
+- Component-Felder werden in PHP-Klassen definiert
+- Keine Datenbank-Schemas für Felder
+- Typsicherheit und IDE-Unterstützung
+
+### 3. **Multi-Domain & Multi-Language**
+- Unterstützung für mehrere Domains
+- Vollständige Mehrsprachigkeit mit spatie/laravel-translatable
+- Domain-spezifische Konfigurationen
+
+### 4. **Component-First**
+- Seiten bestehen aus wiederverwendbaren Livewire Components
+- Drag & Drop Interface für Component-Anordnung
+- Flexibles Layout-System
+
+## Package-Struktur
+
+```
+packages/flux-cms/
+├── core/                           # Kern-Funktionalität
+│   ├── src/
+│   │   ├── Models/                 # Eloquent Models
+│   │   ├── Services/               # Business Logic
+│   │   ├── FieldTypes/             # Field Type System
+│   │   ├── Commands/               # Artisan Commands
+│   │   ├── Http/                   # Controllers & Middleware
+│   │   │   └── Controllers/
+│   │   │       ├── Admin/          # Backend Controllers
+│   │   │       │   ├── PageController.php
+│   │   │       │   ├── BlogController.php
+│   │   │       │   └── ...
+│   │   │       └── PageController.php # Frontend Controller
+│   │   └── FluxCmsServiceProvider.php
+│   ├── database/migrations/        # Database Migrations
+│   ├── config/                     # Konfigurationsdateien
+│   └── tests/                      # Tests
+│
+├── components/                     # Livewire Components
+│   ├── src/
+│   │   └── Livewire/
+│   │       ├── Backend/            # Admin Interface Components
+│   │       └── Frontend/           # Public Frontend Components
+│   └── resources/
+│       └── views/                  # Blade Templates
+│
+└── starter-components/             # Vorgefertigte Components
+    └── src/Components/             # Ready-to-use Components
+```
+
+## Datenbank-Schema
+
+### Core Tabellen
+
+#### `flux_cms_pages`
+```sql
+- id (Primary Key)
+- domain_key (String) - Domain-Zuordnung
+- title (JSON) - Mehrsprachige Titel
+- slug (JSON) - Mehrsprachige URL-Slugs
+- content (JSON) - Mehrsprachiger Inhalt
+- template (String) - Template-Name
+- meta_title (JSON) - SEO Titel
+- meta_description (JSON) - SEO Beschreibung
+- is_published (Boolean)
+- published_at (Timestamp)
+- settings (JSON) - Zusätzliche Einstellungen
+- created_at, updated_at
+```
+
+#### `flux_cms_page_components`
+```sql
+- id (Primary Key)
+- page_id (Foreign Key) - Verknüpfung zur Seite
+- component_type (String) - Livewire Component Klasse
+- content (JSON) - Component-spezifische Daten
+- settings (JSON) - Component-Einstellungen
+- order (Integer) - Sortierreihenfolge
+- is_active (Boolean)
+- created_at, updated_at
+```
+
+#### `flux_cms_page_versions`
+```sql
+- id (Primary Key)
+- page_id (Foreign Key)
+- page_data (JSON) - Snapshot der Seite
+- components_data (JSON) - Snapshot der Components
+- version_name (String)
+- change_description (Text)
+- created_by_type, created_by_id (Polymorphic)
+- created_at, updated_at
+```
+
+#### `flux_cms_navigations`
+```sql
+- id (Primary Key)
+- domain_key (String)
+- name (String) - Eindeutiger Name
+- display_name (JSON) - Mehrsprachiger Anzeigename
+- settings (JSON)
+- is_active (Boolean)
+- created_at, updated_at
+```
+
+#### `flux_cms_navigation_items`
+```sql
+- id (Primary Key)
+- navigation_id (Foreign Key)
+- parent_id (Foreign Key, nullable) - Hierarchie
+- page_id (Foreign Key, nullable) - Verknüpfung zu Seite
+- title (JSON) - Mehrsprachiger Titel
+- url (String, nullable) - Externe URL
+- target (String) - Link-Ziel
+- order (Integer)
+- is_active (Boolean)
+- settings (JSON)
+- created_at, updated_at
+```
+
+#### `flux_cms_blog_posts`
+```sql
+- id (Primary Key)
+- domain_key (String)
+- title (JSON) - Mehrsprachiger Titel
+- slug (JSON) - Mehrsprachige Slugs
+- excerpt (JSON) - Mehrsprachige Auszüge
+- content (JSON) - Mehrsprachiger Inhalt
+- meta_title (JSON) - SEO Titel
+- meta_description (JSON) - SEO Beschreibung
+- is_published (Boolean)
+- is_featured (Boolean)
+- published_at (Timestamp)
+- author_id (Foreign Key)
+- category (String)
+- tags (JSON)
+- settings (JSON)
+- created_at, updated_at
+```
+
+#### `flux_cms_slugs` (Neu)
+```sql
+- id (Primary Key)
+- model_type, model_id (Polymorphic)
+- locale (String)
+- slug (String)
+- created_at, updated_at
+```
+
+#### `tags` & `taggables` (Neu, von `spatie/laravel-tags`)
+```sql
+// tags
+- id
+- name (JSON)
+- slug (JSON)
+- type (String, nullable)
+- order_column (Integer, nullable)
+
+// taggables
+- tag_id (Foreign Key)
+- taggable_type, taggable_id (Polymorphic)
+```
+
+## Component-System
+
+### Field Types
+
+Das System bietet verschiedene Field Types für Component-Definitionen:
+
+#### 1. **TextField**
+```php
+TextField::make('title', 'Titel')
+    ->translatable()
+    ->required()
+    ->placeholder('Titel eingeben')
+    ->helpText('Der Haupttitel des Elements')
+```
+
+#### 2. **MediaField**
+```php
+MediaField::make('image', 'Bild')
+    ->images()
+    ->multiple(false)
+    ->required()
+```
+
+#### 3. **WysiwygField**
+```php
+WysiwygField::make('content', 'Inhalt')
+    ->translatable()
+    ->toolbar(['bold', 'italic', 'link'])
+```
+
+#### 4. **SelectField**
+```php
+SelectField::make('layout', 'Layout')
+    ->options([
+        'default' => 'Standard',
+        'wide' => 'Breit',
+        'centered' => 'Zentriert'
+    ])
+    ->default('default')
+```
+
+#### 5. **BooleanField**
+```php
+BooleanField::make('show_overlay', 'Overlay anzeigen')
+    ->toggle()
+    ->default(true)
+    ->helpText('Dunkles Overlay über dem Hintergrundbild')
+```
+
+#### 6. **NumberField**
+```php
+NumberField::make('columns', 'Spalten')
+    ->min(1)
+    ->max(12)
+    ->default(3)
+    ->helpText('Anzahl der Spalten im Grid')
+```
+
+### Component-Definition
+
+```php
+<?php
+
+namespace App\Livewire\Components;
+
+use Livewire\Component;
+use FluxCms\Core\FieldTypes\TextField;
+use FluxCms\Core\FieldTypes\MediaField;
+use FluxCms\Core\FieldTypes\BooleanField;
+
+class HeroSection extends Component
+{
+    public array $content = [];
+    public array $settings = [];
+    public int $componentId;
+
+    public static function getCmsFields(): array
+    {
+        return [
+            TextField::make('headline', 'Hauptüberschrift')
+                ->translatable()
+                ->required()
+                ->placeholder('Ihre Hauptüberschrift'),
+
+            TextField::make('subheadline', 'Unterüberschrift')
+                ->translatable()
+                ->placeholder('Optionale Unterüberschrift'),
+
+            MediaField::make('background_image', 'Hintergrundbild')
+                ->images()
+                ->required(),
+
+            BooleanField::make('dark_overlay', 'Dunkles Overlay')
+                ->toggle()
+                ->default(true),
+        ];
+    }
+
+    public static function getCmsInfo(): array
+    {
+        return [
+            'name' => 'Hero Section',
+            'description' => 'Großer Bereich mit Hintergrundbild und Text',
+            'category' => 'Header',
+            'preview' => 'hero-preview.jpg'
+        ];
+    }
+
+    public function render()
+    {
+        return view('components.hero-section');
+    }
+}
+```
+
+## Service-Layer
+
+### ComponentRegistry
+
+Der ComponentRegistry Service scannt und verwaltet alle verfügbaren CMS Components:
+
+```php
+<?php
+
+namespace FluxCms\Core\Services;
+
+class ComponentRegistry
+{
+    protected array $components = [];
+    protected bool $loaded = false;
+
+    public function getComponents(): array
+    {
+        if (!$this->loaded) {
+            $this->loadComponents();
+        }
+        return $this->components;
+    }
+
+    protected function loadComponents(): void
+    {
+        // Auto-discovery von Components
+        // Caching für Performance
+        // Validierung der Component-Struktur
+    }
+
+    public function isValidComponent(string $className): bool
+    {
+        // Prüft ob Klasse gültige CMS Component ist
+    }
+}
+```
+
+## Multi-Domain Unterstützung
+
+### Domain-Konfiguration
+
+```php
+// config/domains.php
+return [
+    'portal.b2in.test' => [
+        'type' => 'admin',
+        'name' => 'Admin Portal',
+        'theme' => 'admin',
+    ],
+    'b2in.test' => [
+        'type' => 'web',
+        'name' => 'B2in Main',
+        'theme' => 'b2in',
+        'colors' => [
+            'primary' => '#1f2937',
+            'secondary' => '#3b82f6',
+        ],
+    ],
+    // weitere Domains...
+];
+```
+
+### Domain-spezifische Inhalte
+
+Alle Inhalte werden über `domain_key` gefiltert:
+
+```php
+// Automatische Domain-Filterung
+Page::forDomain(request()->getHost())->published()->get();
+BlogPost::forDomain($domainKey)->published()->get();
+Navigation::forDomain($domainKey)->active()->get();
+```
+
+## Mehrsprachigkeit
+
+### Spatie Translatable Integration
+
+```php
+// Model Definition
+class Page extends Model
+{
+    use HasTranslations;
+
+    protected $translatable = [
+        'title',
+        'slug',
+        'content',
+        'meta_title',
+        'meta_description'
+    ];
+
+    protected $casts = [
+        'title' => 'array',
+        'slug' => 'array',
+        // ...
+    ];
+}
+
+// Verwendung
+$page->getTranslation('title', 'de');
+$page->setTranslation('title', 'de', 'Deutscher Titel');
+```
+
+### Component-Inhalte
+
+```php
+// Mehrsprachige Component-Inhalte
+$content = [
+    'title' => [
+        'de' => 'Deutscher Titel',
+        'en' => 'English Title'
+    ],
+    'description' => [
+        'de' => 'Deutsche Beschreibung',
+        'en' => 'English Description'
+    ]
+];
+```
+
+## Versionierung
+
+### Page Versions
+
+```php
+class Page extends Model
+{
+    public function createVersion(string $changeDescription = null): PageVersion
+    {
+        return $this->versions()->create([
+            'page_data' => $this->toArray(),
+            'components_data' => $this->allComponents()->get()->toArray(),
+            'change_description' => $changeDescription,
+            'version_name' => $this->generateVersionName(),
+        ]);
+    }
+
+    public function restoreVersion(PageVersion $version): void
+    {
+        // Backup current version
+        $this->createVersion('Backup before restoration');
+
+        // Restore page data
+        $this->update($version->page_data);
+
+        // Restore components
+        $this->allComponents()->delete();
+        foreach ($version->components_data as $componentData) {
+            $this->allComponents()->create($componentData);
+        }
+    }
+}
+```
+
+## Medien-Management
+
+### Spatie Media Library Integration
+
+```php
+// Models implementieren HasMedia Interface
+class BlogPost extends Model implements HasMedia
+{
+    use InteractsWithMedia;
+
+    public function registerMediaCollections(): void
+    {
+        $this->addMediaCollection('featured_image')
+              ->singleFile()
+              ->acceptsMimeTypes(['image/jpeg', 'image/png']);
+
+        $this->addMediaCollection('gallery')
+              ->acceptsMimeTypes(['image/jpeg', 'image/png']);
+    }
+
+    public function registerMediaConversions(Media $media = null): void
+    {
+        $this->addMediaConversion('thumb')
+              ->width(300)
+              ->height(200);
+
+        $this->addMediaConversion('hero')
+              ->width(1200)
+              ->height(600);
+    }
+}
+```
+
+## SEO & Performance
+
+### SEO Features
+
+```php
+class Page extends Model
+{
+    public function getSeoTitle(string $locale = null): string
+    {
+        return $this->getTranslation('meta_title', $locale)
+            ?? $this->getTranslation('title', $locale);
+    }
+
+    public function getSeoDescription(string $locale = null): string
+    {
+        return $this->getTranslation('meta_description', $locale)
+            ?? str_limit(strip_tags($this->getTranslation('content', $locale)), 160);
+    }
+
+    public function getCanonicalUrl(): string
+    {
+        return route('pages.show', ['slug' => $this->slug]);
+    }
+}
+```
+
+### Caching Strategy
+
+```php
+// ComponentRegistry Caching
+Cache::remember('flux_cms_components', 3600, function () {
+    return $this->scanForComponents();
+});
+
+// Page Caching
+Cache::tags(['pages', 'page-'.$page->id])
+     ->remember('page-'.$page->id, 3600, function () use ($page) {
+         return $page->with('components')->first();
+     });
+```
+
+## Security
+
+### Authorization Gates
+
+```php
+// FluxCmsServiceProvider
+Gate::define('manage-flux-cms', function ($user) {
+    return $user->hasRole('cms-manager');
+});
+
+Gate::define('edit-page', function ($user, Page $page) {
+    return $user->can('manage-flux-cms') &&
+           $page->domain_key === request()->getHost();
+});
+```
+
+### Input Validation
+
+```php
+// Component Content Validation
+public function getValidationRules(): array
+{
+    $rules = [];
+    foreach ($this->getCmsFields() as $field) {
+        $rules = array_merge($rules, $field->getValidationRules());
+    }
+    return $rules;
+}
+```
+
+## Testing Strategy
+
+Das Projekt verfolgt eine umfassende Teststrategie, die Unit-, Feature- und Browser-Tests kombiniert, um eine hohe Codequalität und Stabilität zu gewährleisten.
+
+### Unit-Tests
+- **Fokus:** Isolierte Klassen und Methoden.
+- **Ziele:** Korrektheit von Model-Beziehungen, Scopes, Business-Logik in Services und die Funktionalität der Field Types sicherstellen.
+- **Beispiele:**
+  - `PageTest`: Überprüft Scopes wie `published()` und Beziehungen wie `slugs()`.
+  - `BlogPostTest`: Testet die polymorphe `author()`-Beziehung und die Tag-Funktionalität.
+
+### Feature-Tests
+- **Fokus:** Komplette Anwendungs-Features über HTTP-Anfragen.
+- **Ziele:** Korrektheit von CRUD-Operationen, Routen, Controller-Logik, Validierung und Autorisierung testen.
+- **Beispiele:**
+  - `PageControllerTest`: Simuliert das Erstellen, Bearbeiten und Löschen von Seiten, inklusive Tests für Validierungsfehler und Zugriffsrechte.
+  - `BlogControllerTest`: Stellt sicher, dass die Blog-Verwaltung wie erwartet funktioniert.
+
+### Browser-Tests (Laravel Dusk)
+- **Fokus:** Echte Benutzerinteraktionen in einem Browser.
+- **Ziele:** Klick-Pfade, UI-Komponenten, JavaScript-Interaktionen und komplette Workflows im Admin-Panel testen.
+- **Beispiele:**
+  - `LoginTest`: Simuliert den Admin-Login.
+  - Zukünftige Tests: Erstellen einer Seite mit Komponenten via Drag & Drop, Verwalten von Medien, etc.
+
+## Deployment & Configuration
+
+### Package Installation
+
+```bash
+# Core Package
+composer require flux-cms/core
+
+# Components Package
+composer require flux-cms/components
+
+# Starter Components
+composer require flux-cms/starter-components
+
+# Installation
+php artisan flux-cms:install
+```
+
+### Konfiguration
+
+```php
+// config/flux-cms.php
+return [
+    'domains' => [
+        'auto_discovery' => true,
+        'cache_timeout' => 3600,
+    ],
+    'components' => [
+        'scan_paths' => [
+            'app/Livewire/Components',
+            'vendor/flux-cms/starter-components/src/Components',
+        ],
+        'cache_enabled' => true,
+    ],
+    'media' => [
+        'disk' => 'public',
+        'conversions' => [
+            'thumb' => [300, 200],
+            'hero' => [1200, 600],
+        ],
+    ],
+    'seo' => [
+        'auto_sitemap' => true,
+        'meta_defaults' => [
+            'title_suffix' => ' | ' . config('app.name'),
+        ],
+    ],
+];
+```
+
+## Erweiterbarkeit
+
+### Custom Field Types
+
+```php
+<?php
+
+namespace App\FieldTypes;
+
+use FluxCms\Core\FieldTypes\BaseField;
+
+class ColorPickerField extends BaseField
+{
+    public function getType(): string
+    {
+        return 'color_picker';
+    }
+
+    public function getValidationRules(): array
+    {
+        return ['regex:/^#[0-9A-F]{6}$/i'];
+    }
+
+    public function sanitizeValue(mixed $value): mixed
+    {
+        return strtoupper($value);
+    }
+}
+```
+
+### Custom Components
+
+```php
+<?php
+
+namespace App\Livewire\CustomComponents;
+
+use Livewire\Component;
+use FluxCms\Core\FieldTypes\TextField;
+use App\FieldTypes\ColorPickerField;
+
+class CustomHero extends Component
+{
+    public static function getCmsFields(): array
+    {
+        return [
+            TextField::make('title', 'Titel')->translatable(),
+            ColorPickerField::make('bg_color', 'Hintergrundfarbe')->default('#ffffff'),
+        ];
+    }
+
+    // Implementation...
+}
+```
+
+## Best Practices
+
+### 1. **Component Design**
+- Kleine, wiederverwendbare Components
+- Klare Field-Definitionen
+- Responsive Design
+- Accessibility beachten
+
+### 2. **Performance**
+- Eager Loading von Relationships
+- Caching strategisch einsetzen
+- Lazy Loading für große Listen
+- Image Optimierung
+
+### 3. **SEO**
+- Strukturierte Daten (JSON-LD)
+- Optimierte Meta Tags
+- Saubere URL-Struktur
+- Sitemap-Generation
+
+### 4. **Security**
+- Input Validation
+- Authorization Gates
+- CSRF Protection
+- XSS Prevention
+
+### 5. **Wartbarkeit**
+- Klare Namenskonventionen
+- Dokumentierte APIs
+- Typisierte Interfaces
+- Umfassende Tests
+
+## Roadmap
+
+### Status Update (Dezember 2024)
+Das Flux CMS Package hat einen Vollständigkeitsgrad von **95%** erreicht und ist **produktionsreif**. Die Grundarchitektur ist vollständig implementiert mit umfassender Test-Suite, Admin-Interface und Component-System.
+
+### Priorität 1 (Kurzfristig - Q1 2025)
+- [ ] **RESTful API-Endpoints:** Implementierung von API-Controllern für Headless CMS-Funktionalität
+  - `Api/PageController.php` - Seiten-Management via API
+  - `Api/BlogController.php` - Blog-Management via API  
+  - `Api/MediaController.php` - Medien-Management via API
+  - `Api/ComponentController.php` - Component-Management via API
+- [ ] **Erweiterte Starter Components:** Vervollständigung der Component-Bibliothek
+  - `TextSection.php` - Einfache Text-Bereiche
+  - `ImageGallery.php` - Bildergalerien
+  - `ContactForm.php` - Kontaktformulare
+  - `TestimonialSection.php` - Testimonials
+  - `PricingTable.php` - Preistabellen
+- [ ] **Dashboard Widgets:** Erweiterbares Dashboard-System
+  - `RecentPagesWidget.php` - Zuletzt bearbeitete Seiten
+  - `AnalyticsWidget.php` - Besucherstatistiken
+  - `MediaUsageWidget.php` - Medienverwendung
+  - `ComponentStatsWidget.php` - Component-Statistiken
+
+### Priorität 2 (Mittelfristig - Q2 2025)
+- [ ] **Content Scheduling:** Vorausplanung von Inhalten
+  - `ScheduledPublishing.php` - Automatisches Veröffentlichen
+  - `ContentCalendar.php` - Content-Kalender
+  - `Auto-Unpublish.php` - Automatisches Archivieren
+- [ ] **Advanced Analytics:** Erweiterte Analyse-Features
+  - Integration mit Google Analytics
+  - Content-Performance-Tracking
+  - User-Engagement-Metriken
+- [ ] **Performance Monitoring:** System-Überwachung
+  - Query-Performance-Monitoring
+  - Cache-Hit-Rate-Tracking
+  - Component-Load-Time-Analyse
+
+### Priorität 3 (Langfristig - Q3-Q4 2025)
+- [ ] **A/B Testing Framework:** Content-Optimierung
+  - `VariantManagement.php` - Varianten-Verwaltung
+  - `AnalyticsIntegration.php` - Conversion-Tracking
+  - `ConversionTracking.php` - Ziel-Tracking
+- [ ] **AI-powered Content Suggestions:** Intelligente Inhaltsvorschläge
+  - Automatische SEO-Optimierung
+  - Content-Gap-Analyse
+  - Intelligente Tag-Vorschläge
+- [ ] **GraphQL API:** Moderne API-Technologie
+  - Vollständige GraphQL-Implementierung
+  - Real-time Subscriptions
+  - Schema-First Development
+
+### Bereits implementiert ✅
+- [x] **Umfassende Test-Suite:** Feature- und Unit-Tests für alle Komponenten und Services
+- [x] **Browser-Tests:** Laravel Dusk-Tests für kritische Admin-Workflows
+- [x] **Tagging-UI für Blog Posts:** Bearbeiten von Tags pro Beitrag implementiert
+- [x] **Slug-System:** Polymorphe Slugs für mehrsprachige URLs
+- [x] **MakeComponentCommand:** Artisan Command für Component-Erstellung
+- [x] **Admin-Controller:** Vollständige CRUD-Operationen für alle Entitäten
+- [x] **Livewire Components:** Backend und Frontend Components
+- [x] **Multi-Domain Support:** Vollständige Domain-Verwaltung
+- [x] **Versionierung:** Page-Version-Management
+- [x] **Media Management:** Spatie Media Library Integration
+
+### Technische Verbesserungen
+- [ ] **Statische Code-Analyse:** Integration von PHPStan Level 8
+- [ ] **CI/CD Pipeline:** Automatisierte Tests und Deployment
+- [ ] **Documentation:** API-Dokumentation mit OpenAPI/Swagger
+- [ ] **Performance Optimization:** Advanced Caching-Strategien
+- [ ] **Security Hardening:** Penetration Testing und Security Audit
+
+### Community & Ecosystem
+- [ ] **Plugin-System:** Erweiterbares Plugin-Framework
+- [ ] **Theme-System:** Vollständiges Theme-Management
+- [ ] **Marketplace:** Component- und Theme-Marketplace
+- [ ] **Developer Tools:** CLI-Tools für Entwickler
+- [ ] **Migration Tools:** Import/Export-Funktionalität