b2in/packages/flux-cms/ARCHITECTURE.md
2025-10-20 17:50:35 +02:00

786 lines
20 KiB
Markdown

# 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