Files
laraundfelix/docs/architektur/cms-widget-registry.md
T
LarsandCursor 7b325f0d66
CI Feature / test (push) Successful in 53s
Deploy Test / test (push) Successful in 48s
Deploy Test / deploy (push) Successful in 22s
Lasse Präsentationsmedien ohne Inhaltsfassung zu.
Bilder, Filme und Hörstücke lassen sich zuordnen und für die Website freigeben, ohne eine fachliche Fassung anzulegen. Unterrichtsfilme behalten die Teaserfassung an ihrer bereitgestellten Fassung.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-19 08:20:35 +01:00

335 lines
39 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CMS: Widget-Registry, Abschnitte, Seiteneditor und Website-Gerüst
Stand: 17.11.2026, Iteration 2 (Branch `feature/cms-sections`, baut auf Iteration 1 `feature/cms-widget-registry` auf). Bezug: ADR-22, ADR-28, ADR-29, ADR-30, ADR-32, ADR-36 (`12_Entscheidungsprotokoll_ADR.md`), Website-CMS-Zielarchitektur §§5.3–5.6, 6.2. Designsystem: `docs/architektur/designsystem.md`.
Dieses Dokument beschreibt den **umgesetzten** Stand für Entwickler. Es ist keine fachliche Freigabe der ADRs.
## 1. Überblick
```
Seite → Abschnitte (Raster, Gestaltung) → Plätze → je Platz höchstens ein Widget aus dem Register
config/cms.php ──► WidgetRegistry ──► PageSections (Lesen, Prüfen, Rollback-Fassung)
│ │
│ ▼
│ SectionRenderer ──► WidgetRenderer ──► widgets/<typ>.blade.php
│ ▲ ▲
│ │ └── Widget-Vorschau im Editor (WidgetBlock)
│ ├── öffentliche Seite (PageController::show)
│ └── Vorschau einer Revision (PageController::preview)
└──► SectionEditor + WidgetEditor (Filament: Abschnitte, Raster, Plätze, Widget-Dialoge)
```
| Baustein | Datei | Aufgabe |
|---|---|---|
| Vertrag | `app/Domain/Cms/Widgets/WidgetType.php` | abstrakte Basisklasse jeder Widget-Art, einschließlich Mindestbreite |
| Register | `app/Domain/Cms/Widgets/WidgetRegistry.php` | Registrierung, Lesen (Anheben älterer Fassungen), Prüfen und Bereinigen je Widget |
| Abschnitte | `app/Domain/Cms/Sections/PageSections.php` | Abschnitts- und Platzmodell: Lesen, Prüfen, flache Rollback-Fassung, Medien |
| Raster und Gestaltung | `app/Domain/Cms/Sections/SectionLayouts.php`, `SectionStyle.php` | freigegebene Raster und Gestaltungswerte (Aufzählungen) |
| Darstellung | `app/Domain/Cms/Sections/SectionRenderer.php`, `Widgets/WidgetRenderer.php` | einziger Renderweg für Seite, Vorschau und Editor |
| Editor-Adapter | `app/Filament/Support/SectionEditor.php`, `WidgetEditor.php`, `WidgetBlock.php`, `ReportsSectionErrors.php` | Abschnitte, Rasterauswahl, Plätze, Widget-Dialoge, Fehlermeldungen |
| Navigation | `app/Domain/Cms/SiteNavigation.php` | Kopf- und Fußnavigation aus dem CMS-Navigationsmodell |
| Katalog-Lesesicht | `app/Domain/Cms/Catalog/PublicCatalogReader.php` | einzige Stelle, die entscheidet, welche Programme/Module öffentlich erscheinen |
| Hilfen | `app/Domain/Cms/Widgets/Support/*` | sichere Links, bereinigter formatierter Text, öffentlicher Medienbereich, Bildauswahl |
| Seitenvorlagen | `app/Domain/Cms/PageTemplates.php`, `resources/views/site/templates/` | derzeit nur `standard` (Abschnitte untereinander) |
| Layout | `resources/views/layouts/site.blade.php`, `resources/views/components/site/*` | Kopfzeile, Wortmarke, Navigation, Inhaltsfläche, Fußbereich |
| Designsystem | `resources/css/{tokens,base,components,site,sections,widgets}.css` | Tokens, Grundkomponenten, Gerüst, Abschnitte, Widgets |
| Wiederherstellung | `app/Console/Commands/RevertPublishedPages.php` | `cms:revert-published` vor einem Code-Rollback (Abschnitt 9) |
## 2. Widget-Vertrag
Jede Widget-Instanz (in einem Platz von `page_revisions.sections` und in der flachen Liste `page_revisions.blocks`) hat dieselbe Hülle:
| Feld | Inhalt |
|---|---|
| `id` | stabile Kennung (UUID), bleibt beim Bearbeiten erhalten; Duplikate erhalten beim Speichern eine neue (seitenweit geprüft) |
| `type` | Typkennung aus dem Register; ändert sich nie |
| `v` | Schemaversion der Art |
| `variant` | eine der für die Art registrierten Varianten |
| `settings` | nur registrierte Aufzählungswerte (`WidgetType::settingOptions()`, einschließlich der gemeinsamen Höhe `height`); freie Werte werden abgewiesen. Fehlt ein Wert, gilt die Vorgabe der Darstellung |
| `data` | redaktionelle Inhalte |
| `refs` | Verweise auf Fachobjekte oder Medien, nur Kennungen bzw. Pfade im öffentlichen Bereich `cms/` |
Gespeichert werden nur Schlüssel, für die die Art Prüfregeln deklariert. Felder mit führendem `_` (zum Beispiel `_upload`) sind Editorhilfen und werden nie gespeichert.
## 3. Versionierung und Altbestand
- **Altformat** (vor der Registry: `{type, heading, intro, …}` ohne `v`) wird beim Lesen als Version 1 interpretiert (`WidgetType::fromLegacy`).
- Liegt `v` unter der aktuellen Version, hebt `WidgetType::upgrade($widget, $from)` schrittweise an.
- **Revisionen ohne Abschnitte** (`sections = null`, alles vor Iteration 2) werden als einspaltige Abschnitte mit kompaktem Abstand gelesen (`PageSections::read`).
- Gespeicherte Revisionen werden **nicht** umgeschrieben. Erst eine neue Revision aus dem Editor speichert Abschnitte und aktuelle Hüllen.
- „Wiederherstellen“ kopiert Abschnitte und flache Liste einer Revision unverändert.
- Unbekannte Widget-Arten werden ausgelassen; unbekannte Raster- oder Gestaltungswerte fallen beim Lesen auf Vorgaben zurück. Eine Hülle mit höherer Version als im Code wird bestmöglich dargestellt, aber nicht gespeichert.
- Regel: Optionale neue Felder brauchen keine neue Version. Umbenennen, Umdeuten oder Verschieben von Feldern braucht eine neue Version mit `upgrade()` und einen Test. Gleiches gilt für die Abschnittshülle (`PageSections::VERSION`).
Beispiele:
- `image_text` Version 1 `{image, alt, body (Klartext)}` → Version 2 `data {title, body (bereinigtes HTML), alt}`, `refs {image}`, Variante `image_left` → Version 3 (Kit v1.6): `settings.format` entfällt, `settings.focus` wird zu `data.focus_x/focus_y` (Prozent).
- `hero` Version 1 → Version 2 (Kit v1.6): Varianten `standard`/`stage` → `photo_split`, `highlight`/`editorial` → `editorial_solid`; `settings.focus` wird zu `data.focus_x/focus_y`, `settings.text_side` entfällt. Die data-Schlüssel (`heading`, `text`, `cta_*`, `alt`) bleiben, damit ein Code-Rollback darstellbar bleibt.
## 4. Registrierte Widget-Arten
| Kennung | Name | Version | Varianten | Breiten (Einheiten) | Höhen | Verweise |
|---|---|---|---|---|---|---|
| `hero` | Einstieg (Hero), Premium nach Kit v1.6 | 2 | `photo_split` (Foto mit Textfläche), `editorial_solid` (Navy-Markenfläche) | 3, 4 | `compact` (mind. 400 px), `normal` (512 px, Vorgabe), `large` (640 px) | `refs.image` |
| `heading` | Überschrift und Einleitung | 1 | `standard` | 1–4 | – | – |
| `prose` | Fließtext | 1 | `standard` | 1–4 | – | – |
| `image_text` | Bild und Text, Premium nach Kit v1.6 | 3 | `image_left`, `image_right` (Bildseite) | 1–4 | `compact`, `normal` (Vorgabe), `spacious` | `refs.image` |
| `cards` | Redaktionelle Karten | 1 | `standard` (Raster), `compact` (Liste), `featured` (erste Karte hervorgehoben) | 1–4 | – | Bild je Karte in `data.items[].image` |
| `catalog_cards` | Programm- und Modulkarten | 1 | `standard`, `compact` | 1–4 | – | `refs.items[] = {type: composition, id}` |
| `topic_card` | Themenkarte, Premium-Karte nach Kit v1.7 | 1 | `adaptive`, `stacked` | 1–4 | `auto` (Vorgabe), `fill` | `refs.pillar`, `refs.image` |
| `media_card` | Medien- und Materialkarte, Kit v1.7 | 1 | `adaptive`, `stacked` | 1–4 | `auto` (Vorgabe), `fill` | `refs.element`, `refs.image` |
| `program_card` | Programm- oder Modulkarte, Kit v1.7 | 1 | `adaptive`, `stacked` | 1–4 | `auto` (Vorgabe), `fill` | `refs.composition`, `refs.image` |
| `call_to_action` | Handlungsaufruf | 1 | `standard` | 1–4 | `auto` (Vorgabe), `fill` (Abschnittshöhe füllen) | – |
| `faq` | FAQ | 1 | `standard` | 2–4 | – | – |
Darstellungsklassen an der Widget-Hülle: `widget widget-<typ> widget-variant-<variante>` und, wenn die Art Höhen anbietet, `widget-height-<höhe>`. Premium-Ansichten: `lf-hero lf-hero--{photo-split|editorial-solid} lf-hero--height-<höhe> lf-hero--accent-<akzent>` und `lf-bt lf-bt--{cream|clear|navy} lf-bt--image-{left|right} lf-bt--height-<höhe>`.
**Premium-Widgets (Kit v1.6).** Ansichten `resources/views/widgets/hero.blade.php` und `image_text.blade.php`, Stylesheets `resources/css/components/lf-hero.css` und `lf-bild-text.css` (aus `12_premium_widgets_adaptiv_v1.6/components/*.v1.6.css` übernommen und angepasst; sie ersetzen das frühere Hero- und Bild-und-Text-CSS und werden nicht parallel geladen). Gemeinsame Felder in `App\Domain\Cms\Widgets\Support\PremiumFields`:
| Feld | Gespeichert als | Hinweis |
|---|---|---|
| Label | `data.eyebrow` | höchstens 80 Zeichen |
| Überschrift | `data.heading` (Einstieg), `data.title` (Bild und Text) | |
| Beschreibung | `data.text` (Klartext, Einstieg), `data.body` (bereinigter formatierter Text, Bild und Text) | |
| Schaltflächen | `data.cta_label/cta_url`, `data.cta2_label/cta2_url` | Linkziele über `SafeUrl` |
| Bild, Alternativtext | `refs.image`, `data.alt` | öffentlicher Bereich `cms/`; Alternativtext Pflicht bei Bild |
| Bildfokus | `data.focus_x`, `data.focus_y` | ganze Zahlen 0–100; Vorgabe Einstieg 68/50, Bild und Text 64/43 |
| Überschriftenebene | `settings.heading_level` | `auto` (Vorgabe), `h2`, `h3`; das erste Widget der Seite ist immer H1 |
| Akzent (Einstieg) | `settings.accent` | `underline` (Vorgabe), `rays`, `none` |
| Fläche (Bild und Text) | `settings.surface` | `cream` (Vorgabe), `clear` (übernimmt den Abschnitt), `navy` |
| Höhe | `settings.height` | gemeinsamer Layoutvertrag (§12) |
**Abweichungen vom Kit (bewusst):**
- Kennungen bleiben `hero` und `image_text`, nicht `lf-brand-hero`/`lf-editorial-bild-text`; Varianten `photo_split`/`editorial_solid` mit Unterstrich, weil Variantenkennungen `^[a-z][a-z0-9_]*$` folgen.
- Bildseite von Bild und Text bleibt die Variante (`image_left/right`), nicht zusätzlich `settings.image_side`, damit es keine doppelte Einstellung gibt.
- Bildfokus in `data` statt `settings.image_focus`, weil Einstellungen nur Aufzählungswerte tragen.
- Überschriftenebene ohne frei wählbare H1 (Regel: genau eine H1 je Seite, erstes Widget).
- Linkziele: Seitenpfad, `#Anker`, `http` und `https` (bestehende `SafeUrl`-Regel); das Kit erlaubt nur `https`.
- Das Kit lädt das Einstiegsbild immer sofort; hier nur beim ersten Widget der Seite, alle anderen verzögert.
- Kit-CSS ergänzt: Überschriften erben Farbe (globale h1–h3-Regeln), Unterstreichung als Block, Fläche `clear` übernimmt die Farben dunkler Abschnitte, Strahlen-Akzent aus `components/brand/rays.blade.php`, Fokusfarbe aus den Tokens.
## 5. Neues Widget hinzufügen
1. Klasse unter `app/Domain/Cms/Widgets/Types/` anlegen, von `WidgetType` ableiten. Pflicht: `key()`, `label()`, `description()`, `dataRules()`, `dataFields()`. Je nach Bedarf: `variants()`, Layoutvertrag `supportedUnits()`/`preferredUnits()`/`heights()`/`stages()`/`narrowBehavior()` (Abschnitt 12), `settings()`/`settingLabels()`/`optionIcons()`, `mediaSchema()` für den Reiter „Medien“, `refRules()`, `refFields()`, `clean()` (Links mit `SafeUrl`, Text mit `RichText::sanitize`, Bilder mit `ImageRefFields::clean`), `resolve()`, `mediaPaths()`, `summary()`, `schematic()`, `icon()`.
2. Ansicht `resources/views/widgets/<kennung>.blade.php` anlegen. Verfügbar: `$data`, `$refs`, `$variant`, `$settings`, `$first`, `$context` (Vorschau ja/nein) und die Rückgabe von `resolve()`. Kein `{!! !!}` außer für mit `RichText::sanitize` bereinigten Text. Breitenabhängige Regeln als Container-Abfrage `@container slot (…)`, nicht als Fenster-Medienabfrage; Farben nur über Bedeutungs-Tokens.
3. Klasse in `config/cms.php` unter `widgets` eintragen.
4. Tests ergänzen (Registrierung und Prüfregeln in `tests/Unit/WidgetRegistryTest.php`, Darstellung in `tests/Feature/CmsWidgetRenderingTest.php` bzw. `CmsSectionRenderingTest.php`).
Editor, Plätze, Vorschau, Speicherung und öffentliche Darstellung brauchen keine Änderung. `WidgetRegistryTest::test_a_new_widget_type_works_through_the_contract_alone` belegt das mit einer nur im Test definierten Art.
**Fachobjekt-Widgets** (künftig Angebote, Lizenzartikel, Kampagnen) speichern ausschließlich Kennungen in `refs` und lesen Anzeigeinhalte über eine Lesesicht wie `PublicCatalogReader`. Preise, Rechte und Angebotsbedingungen werden nie in `data` kopiert.
## 6. Öffentliche Freigabe von Programmen und Modulen (Übergangsregel)
ADR-29 (öffentliche Fachobjektprofile) ist nicht umgesetzt. Deshalb gilt in `PublicCatalogReader`:
| Objekt | Im Editor wählbar | Öffentlich sichtbar | Redaktionsvorschau |
|---|---|---|---|
| Thema (Säule), veröffentlicht mit öffentlicher Adresse | ja (Themenkarte) | ja, mit Link auf `/themen/{slug}` | ja |
| Thema, nicht veröffentlicht | ja (Themenkarte) | nein | ja, mit Hinweis „Nur Redaktionsvorschau“ |
| Medium/Material, nicht archiviert, mit bereitgestellter Fassung, Bestandteil der gezeigten Fassung eines öffentlichen Programms, keine Traineranleitung | ja (Medienkarte) | ja, mit Link auf die Programmseite (dort ist es bereits öffentlich genannt) | ja |
| Medium/Material ohne öffentliches Programm, nur mit Entwurfsfassung oder Traineranleitung | ja (nicht gesperrt) | **nein** | ja, mit Hinweis |
| Programm oder Modul mit bereitgestellter Fassung, ohne Anzeigefreigabe | ja (nur Programm-/Modulkarte, nicht Katalogkarten) | nein | ja, mit Hinweis |
| Programm mit Anzeigefreigabe, nicht archiviert | ja | ja, mit Link auf `/programme/{id}` (dieselbe Regel wie die bestehende Programmliste) | ja |
| Modul mit Anzeigefreigabe, nicht archiviert | ja | **nein** | ja, mit Hinweis „Nur in der Redaktionsvorschau sichtbar“ |
| Fassung ohne Anzeigefreigabe, Entwurf, archiviert, ohne Inhaltsart | nein (Speichern wird abgewiesen) | nein | nein |
Die Prüfung erfolgt bei jeder Darstellung, nicht nur beim Speichern: Wird eine Anzeigefreigabe zurückgenommen, verschwindet die Karte ohne Seitenänderung. Vorschaubilder der Bibliothek sind geschützt (Paket 6) und werden nicht gezeigt; die Karte zeigt eine Inhaltsart-Fläche.
**Offener Integrationsschritt:** Mit ADR-29 ersetzt die Profilprüfung (Status „gelistet“, gezeigte Fassung, freigegebenes Bild) die Übergangsregel in `PublicCatalogReader::isPublic()`/`entries()`. Daten der Widgets ändern sich dadurch nicht.
## 7. Medien
Alle Bilder kommen aus dem zentralen Medienmanager (`docs/architektur/medienzugriff-fuer-komponenten.md`, Abschnitt
„Umsetzung im CMS“). Gespeichert wird die Kennung des Mediums in `refs.image`, `data.items[].image` bzw.
`style.image`; öffentlich erscheint ein Bild nur mit Website-Freigabe (`WebsiteMedia`, Route `website.media`).
Gemeinsame Felder: `ImageRefFields` (Auswahl mit Vorschaubild und Status, Upload über `WebsiteIntake`, Anzeige des
gewählten Mediums). Frühere Pfade unter `cms/` gelten über `WebsiteMediaAlias` als das übernommene Medium, ohne
Zuordnung weiter als öffentliches CMS-Bild. Bibliotheksmedien ohne Website-Freigabe erscheinen öffentlich nie.
## 8. Editor und Vorschau
- Arbeitsfläche in voller Breite (`maxContentWidth = Full`); „Seite und Suchmaschinen“ ist beim Bearbeiten eingeklappt.
- **Abschnitte** (Repeater): Kopfzeile „Abschnitt N · Raster 1 + 3 · Fläche · Widgets“; Aktionen Ziehen, nach oben/unten, Duplizieren, Löschen (mit Rückfrage), Einklappen, jeweils mit Tooltip.
- **Raster**: grafische Auswahl mit sechs Kacheln. Raster mit weniger Plätzen als eingesetzten Widgets sind gesperrt. Beim Wechsel entfallen zuerst leere Plätze; Widgets behalten ihre Reihenfolge (`SectionEditor::arrangeSlots`). Kein Wechsel entfernt ein Widget.
- **Gestaltung des Abschnitts** (eingeklappt, Zusammenfassung im Kopf): Hintergrund, Breite, **Abstand oben**, **Abstand unten**, **Widget-Abstand** (je Kein Abstand / Kompakt / Normal / Großzügig, siehe §11), Trenner; bei Hintergrundbild zusätzlich Bild (Auswahl oder Upload), Fokuspunkt und Überlagerung. Abschnitts- und Widget-Einstellungen sind getrennt.
- **Plätze** stehen im Verhältnis des Desktop-Rasters nebeneinander; Widgets lassen sich per Ziehen zwischen Plätzen tauschen. Der Platzkopf nennt Breite und warnt, wenn das Widget breiter sein müsste. Ein freier Platz bietet „Widget einsetzen“ (Auswahl mit Name, Beschreibung, Symbolbild, Mindestbreite), danach öffnet der Widget-Dialog. Ein Klick auf die Vorschau öffnet denselben Dialog: eine Dialogebene.
- **Widget-Dialog**: Arten mit Darstellungsoptionen oder Medien gliedern den Dialog in die Reiter **Inhalt**, **Medien** und **Darstellung** (generisch aus der Registry: `editorSchema()`, `mediaSchema()`, Varianten und `settingOptions()`); andere Arten zeigen ihre Felder direkt. Varianten und Höhen sind sichtbare Auswahlknöpfe mit Symbol, Bildfokus zwei Schieberegler (0–100). „Darstellung“ nennt die zulässigen Platzbreiten und das Verhalten bei wenig Platz.
- **Live-Vorschau im Dialog**: rendert den ungespeicherten Zustand mit derselben Ansicht wie die Website (`WidgetEditor::renderPreview`) in einer wählbaren logischen Platzbreite (Smartphone 390 px und die zulässigen Einheiten: 310/640/960/1300 px, entsprechend dem Standardabschnitt bei 1440 px Fensterbreite) und verkleinert sie auf die Dialogbreite. Die Breitenwahl wird nicht gespeichert.
- **Widget-Vorschau im Platz**: dieselbe Ansicht im isolierten `iframe` in der Breite des Platzes im Editor; über 28 rem gekürzt mit Hinweis „vollständig in der Seitenvorschau“.
- „Entwurf speichern“ erzeugt eine Revision (bei unverändertem Stand keine weitere). „Veröffentlichen“ speichert zuerst den aktuellen Stand im Editor und veröffentlicht genau diesen; enthält er Fehler, wird nichts veröffentlicht. Vorher veröffentlichte „Veröffentlichen“ nur die zuletzt gespeicherte Revision, sodass übernommene, aber ungespeicherte Änderungen (etwa ein gewähltes Bild) verloren gingen.
- Verlassen oder Neuladen mit ungespeicherten Änderungen löst eine Warnung des Browsers aus.
- Ganzseitige Vorschau: `/redaktion/vorschau/{revision}/geraete` mit Umschaltern 390/768/1440 px; zeigt Kopfzeile, Navigation, Abschnitte, Flächen, Trenner und Fußbereich mit demselben Renderer wie die öffentliche Seite; `noindex`.
- Revisionen: Vorschau, Veröffentlichen, Wiederherstellen (legt eine neue Revision an).
- Seitenliste: zuletzt bearbeitete Seiten zuerst (Spalte „Zuletzt bearbeitet“, deutsche Zeit; jede gespeicherte Revision und jede Veröffentlichung zählt), Pfad und Datum sortierbar, 25/50/100 Einträge je Seite, Suche nach Pfad. „Duplizieren“ legt eine unveröffentlichte Kopie des zuletzt gespeicherten Stands unter neuer Adresse an; die Vorlage bleibt unverändert.
Fehler beim Speichern erscheinen als Meldung „Abschnitt N, Platz M (Widget-Art): …“ und als Zusammenfassung am Platzraster des Abschnitts, auch wenn das Feld im geschlossenen Widget-Dialog liegt (Registry-Fehler über `SectionEditor::mapErrors`, Formularfehler über `ReportsSectionErrors`).
## 9. Rollback und Datenformat (wichtig vor dem Merge nach `main`)
**Medien aus dem Medienmanager (ADR-40).** Revisionen, die nach der Umstellung gespeichert werden, enthalten im
Bildschlüssel eine Kennung (Zahl) statt eines Pfads. Ein Code-Rollback auf eine Fassung davor zeigt diese Bilder nicht
(die ältere Fassung kennt nur `cms/`-Pfade); Texte und Gestaltung bleiben. Die Dateien unter `cms/` und frühere
Revisionen bleiben unverändert, die Zuordnungstabelle `website_media_aliases` ist additiv.
**Speicherung.** Jede neue Revision schreibt zwei Spalten:
| Spalte | Inhalt | Wer liest sie |
|---|---|---|
| `page_revisions.sections` (neu, ergänzend, nullable) | Abschnitte mit Raster, Gestaltung und Plätzen | Code ab Iteration 2 |
| `page_revisions.blocks` (bestehend) | alle Widgets in Lesereihenfolge als flache Hüllenliste | Code der Iteration 1; Iteration 2 nur bei `sections = null` |
**Was ein reiner Code-Rollback bewirkt** (`scripts/deploy.sh` setzt nur den Code zurück):
| Rollback auf | Seiten, die nach dem Deploy gespeichert wurden | Sicher? |
|---|---|---|
| Iteration 1 (Widget-Registry ohne Abschnitte) | zeigen alle Widgets untereinander; Raster, Flächen, Hintergrundbilder, Trenner und Untermenüs entfallen | darstellbar, aber **nicht gleichwertig** |
| Stand vor der Widget-Registry (derzeitiger Stand `main`/Prod) | `blocks` liegt im Hüllenformat vor, das dieser Code nicht lesen kann: Fehler auf genau diesen Seiten | **nicht sicher** |
**Wiederherstellungsweg** (vor dem Code-Rollback, solange der neue Code läuft):
1. Probelauf: `php artisan cms:revert-published --before="<Zeitpunkt des Deployments>"` listet jede veröffentlichte Seite, deren Revision danach entstand, und die Revision, auf die zurückgesetzt würde.
2. Ausführen mit `--apply`: Nur der Veröffentlichungszeiger wechselt auf die letzte Revision vor dem Zeitpunkt (Altformat). Seiten ohne ältere Revision werden zurückgezogen, nicht gelöscht. Keine Revision wird geändert oder gelöscht.
3. Danach den Code zurückrollen. Nach einem erneuten Vorwärts-Deploy lassen sich die neueren Revisionen in der Revisionsliste wieder veröffentlichen.
Ist der neue Code nicht mehr lauffähig, entspricht Schritt 2 dieser Anweisung (nur nach bestätigtem Backup, PostgreSQL; `:deploy` ersetzen):
```sql
UPDATE pages p SET published_revision_id = (
SELECT r.id FROM page_revisions r
WHERE r.page_id = p.id AND r.created_at < :deploy ORDER BY r.id DESC LIMIT 1)
WHERE p.published_revision_id IN (SELECT id FROM page_revisions WHERE created_at >= :deploy);
```
Die Migrationen (`sections`, `parent_id`) sind ergänzend und müssen beim Rollback nicht zurückgenommen werden; älterer Code ignoriert beide Spalten.
**Abschnittshülle Version 2 (Abstände)** bringt keine Migration der Datenbank; ältere Hüllen werden beim Lesen übersetzt. Ein Code-Rollback auf eine Fassung vor Version 2 zeigt neue Hüllen mit den alten Vorgaben (Abstand normal), weil sie `spacing_bottom` und `gap` nicht kennt; Speichern im alten Editor weist diese Schlüssel ab. Der Wiederherstellungsweg oben gilt.
**Adaptive Widgets (ADR-38)** bringen keine Migration. Gespeichert werden ab jetzt `hero` Version 2 und `image_text` Version 3. Ein Code-Rollback auf Designiteration 1 stellt diese Hüllen „bestmöglich“ dar (höhere Version als im Code): unbekannte Varianten fallen auf die Vorgabe zurück, die data-Schlüssel sind unverändert; Höhe, Fläche, Label und Fokus werden nicht dargestellt, aber nicht gelöscht. Speichern im alten Editor ist für diese Hüllen nicht möglich, bis der neue Code wieder läuft.
**Designiteration 1** bringt keine Migration. Bei einem Code-Rollback auf Iteration 2 fallen die neuen Varianten beim Lesen auf die Vorgabe zurück (`stage`/`editorial` → `standard`, `featured` → `standard`); die neuen Einstellungen und `cta2_*` werden nicht dargestellt, aber nicht gelöscht. Seiten bleiben darstellbar; der Wiederherstellungsweg oben ist dafür nicht nötig. Ein reiner Code-Rollback ist nach redaktionellen Änderungen im neuen Editor **nicht** als sicher anzusehen; der Weg oben ist Teil jedes Rollbacks.
## 10. Navigation
`NavigationItemResource`: Einträge bearbeiten, aus-/einblenden (`is_visible`), löschen, Reihenfolge per Ziehen („Reihenfolge ändern“), interne Seite oder geprüfte Adresse.
- **Plätze**: `header` (Hauptnavigation), `footer` (Fußbereich: Service), `footer_contact` (Kontakt), `footer_legal` (Rechtliches). Die Fußbereichsgruppen sind Werte derselben Spalte, keine zweite Verwaltung. Leere Gruppen erscheinen nicht.
- **Untermenü**: eine Ebene über `parent_id` (ergänzende Migration), nur in der Hauptnavigation und nur unter Einträgen der obersten Ebene. Ist der übergeordnete Eintrag ausgeblendet, sind seine Untereinträge es auch; wird er gelöscht, rücken sie nach oben. Ein Eintrag mit Untereinträgen darf ohne eigenes Ziel nur das Untermenü öffnen.
- **Aktiver Eintrag**: aus dem angefragten Pfad (`aria-current="page"`; der übergeordnete Eintrag wird als aktiver Pfad markiert).
- Die Ausgabe hängt nie vom Anmeldestatus ab (ADR-32). Der Kontozugang „Mitgliederbereich“ ist für alle gleich und leitet Gäste zur Anmeldung.
## 11. Abschnitte und Plätze
Gespeicherte Hülle eines Abschnitts (`sections[]`, Version 2):
```json
{"id": "uuid", "v": 2, "layout": "u1_3",
"style": {"background": "dark", "image": null, "focus": "center", "overlay": "light", "width": "standard",
"spacing_top": "compact", "spacing_bottom": "compact", "gap": "normal", "divider": "line"},
"slots": [{"id": "…", "type": "cards", "v": 1, "…": "…"}, null]}
```
| Raster | Einheiten | Desktop (Abschnitt ab 60 rem) | Tablet (40–60 rem) | Smartphone |
|---|---|---|---|---|
| `u4` | 4 | volle Breite | volle Breite | volle Breite |
| `u2_2` | 2 + 2 | 1 : 1 | zwei Spalten | gestapelt |
| `u1_3` / `u3_1` | 1 + 3 / 3 + 1 | 1 : 3 / 3 : 1 | gestapelt | gestapelt |
| `u1_2_1` | 1 + 2 + 1 | 1 : 2 : 1 | gestapelt | gestapelt |
| `u1_1_1_1` | 1 + 1 + 1 + 1 | vier Spalten | 2 × 2 | gestapelt |
| `u1_1_2` / `u2_1_1` | 1 + 1 + 2 / 2 + 1 + 1 | 1 : 1 : 2 / 2 : 1 : 1 | gestapelt | gestapelt |
- Die Einheiten werden als Spaltenverhältnis (`fr`) umgesetzt, nicht als zweites CSS-Grundraster. Der Umbruch richtet sich nach der Breite des Abschnitts (Container-Abfrage `section`); ein schmaler Abschnitt stapelt deshalb früher.
- Gestapelt wird immer in Platzreihenfolge; Lese- und Fokusreihenfolge bleiben gleich (keine visuelle Umordnung).
- **Leere Plätze** gibt es im Editor. Öffentlich entfallen sie; die übrigen Plätze teilen sich die Breite im Verhältnis ihrer Einheiten. Ein Abschnitt ohne darstellbares Widget entfällt samt Fläche und Trenner.
- **Gestaltung**: nur Aufzählungswerte (`SectionStyle`), abgebildet auf Tokens. Freie Werte (Farbcodes, CSS, unbekannte Schlüssel) werden abgewiesen.
- Hintergrund: Standard, helle Markenfläche, dunkle Markenfläche, Markenakzent, Hintergrundbild. Jede Fläche setzt die Bedeutungs-Tokens neu (`scope-dark`, `scope-accent`, `scope-light`).
- Breite: schmal (45 rem), Standard (75 rem), breit (90 rem), volle Breite. Der Hintergrund reicht immer über die ganze Bildschirmbreite.
- **Abstände (Version 2): genau drei unabhängige Werte**, je Kein Abstand / Kompakt / Normal / Großzügig:
| Wert | Bedeutung | Stufen (390 px → 1440 px) |
|---|---|---|
| `spacing_top` | Abstand oben (vor dem Inhalt) | 0 / 24 → 45 / 48 → 90 / 72 → 120 px (`--section-space-*`) |
| `spacing_bottom` | Abstand unten (nach dem Inhalt) | wie oben |
| `gap` | Widget-Abstand zwischen den Plätzen des Rasters, nebeneinander und gestapelt | 0 / 12 → 18 / 20 → 36 / 32 → 56 px (`--section-gap-*`) |
- Zwischen zwei Abschnitten addieren sich „unten“ des ersten und „oben“ des zweiten; 0 + 0 = 0. Es gibt keine weitere Vorgabe aus Seiten- oder Rasterhüllen (geprüft: kein Außenabstand der Abschnitte, `main` ohne Innenabstand).
- Oben und unten sind der Innenabstand des Abschnitts. Bei eigener Fläche (dunkel, Akzent, Bild) liegen sie innerhalb der Fläche, damit Hintergründe nahtlos anschließen.
- Vorgabe neuer Abschnitte: oben und unten Kompakt, Widget-Abstand Normal. Damit entspricht der Abstand zwischen zwei neuen Abschnitten dem bisherigen Normalabstand.
- Abstände innerhalb eines Widgets (zum Beispiel zwischen Karten, `--grid-gap`) bleiben Sache des Widgets.
- Trenner „Linie“ und „Markenakzent“ sind sichtbare Elemente zwischen zwei Abschnitten und bringen ihren eigenen kleinen Rand um die Linie mit (24 bzw. 8 px oben und unten).
- **Version 1 → 2** (`SectionStyle::migrateSpacing`, beim Lesen; gespeicherte Revisionen bleiben):
- „Abstand oben und unten“ wird zu oben und unten mit demselben Wert.
- Die Abweichung „Abstand oben“ ersetzt nur oben: „kein“ → Kein Abstand, „gering“ → Kompakt. Die Stufe „gering“ gibt es nicht mehr; das ist die einzige sichtbare Änderung, auf der Testinstanz nur bei `/praevention-im-alltag`, +24 px.
- Die frühere versteckte Regel „Abschnitt ohne Fläche direkt nach Abschnitt ohne Fläche: oben 0“ (ohne Linien- oder Akzenttrenner dazwischen, leere Abschnitte zählen nicht) wird als „oben: Kein Abstand“ ausgeschrieben.
- Der Trenner „Zusätzlicher Abstand“ entfällt; er wird zu „Abstand unten“ eine Stufe höher.
- Der Widget-Abstand wird Normal (der bisher feste Rasterabstand).
- Messung auf der Testinstanz: sieben Seiten bei 1440 und 390 px vor und nach dem Deploy pixelgleich, außer der genannten Stelle.
- Hintergrundbild: nur aus `cms/`, Fokuspunkt als `object-position` (neun Positionen), Überlagerung hell (84 % Weiß) oder dunkel (78 % Navy) oder keine. Das Bild des ersten Abschnitts lädt sofort, alle übrigen verzögert.
- **Trenner** stehen zwischen Abschnitten, nie nach dem letzten: dezente Linie, Markenakzent (kurzer gelber Balken).
- **Erstes Widget** der Seite ist der Seiteneinstieg (Überschrift erster Ordnung); seitenweit genau eine.
- **Grenzen**: höchstens 30 Abschnitte und 60 Widgets je Seite; keine Verschachtelung.
## 12. Responsive Widget-Regeln und gemeinsamer Layoutvertrag (ADR-38)
Jede Widget-Art erklärt in `WidgetType`:
- `supportedUnits()`: zulässige Platzbreiten (1–4); `minUnits()` ist daraus abgeleitet. Ein Platz mit anderer Breite wird beim Speichern abgewiesen („… ist für Plätze mit 3 oder 4 Rastereinheiten vorgesehen“); der Platzkopf im Editor warnt vorher („passt nicht“), die Widget-Auswahl nennt die zulässigen Breiten.
- `heights()`: angebotene Höhen aus `WidgetType::HEIGHTS` (`auto`, `compact`, `normal`, `large`, `spacious`, `fill`), gespeichert als `settings.height`; `defaultHeight()` gilt ohne Angabe. Höhen sind Mindesthöhen oder Proportionen, nie Begrenzungen. `fill` streckt das Widget auf die Höhe der Abschnittszeile, wenn Plätze nebeneinander stehen.
- `stages()` und `narrowBehavior()`: Darstellungsmodi nach Containerbreite und Verhalten bei wenig Platz.
Jeder Platz ist ein Container (`slot`); die Premium-Widgets haben zusätzlich eigene Container (`lf-hero`, `lf-bt`). Entscheidend ist die tatsächliche Breite, nicht die Einheitenzahl.
| Widget | Breiten | Höhen | Darstellung nach Containerbreite |
|---|---|---|---|
| Einstieg (Hero) | 3, 4 | compact/normal/large | ab 860 px Foto über die Fläche, Text links, Mindesthöhe 400/512/640 px; darunter Sicherheitsumbruch: Foto 16:9 über dem Text, Höhe nach Inhalt; unter 440 px Schaltflächen untereinander |
| Bild und Text | 1–4 | compact/normal/spacious | unter 540 px gestapelt, Schaltflächen in voller Breite; 540–899 px flacher Bildstreifen (2,5 : 1 / 2,15 : 1 / 1,8 : 1) über dem Text; ab 900 px zweispaltig, Bild links oder rechts |
| Überschrift | 1–4 | – | Größe folgt der Platzbreite, lange Wörter werden getrennt |
| Fließtext | 1–4 | – | Zeilenlänge höchstens etwa 70 Zeichen, lange Adressen brechen um |
| Redaktionelle Karten | 1–4 | – | so viele Karten nebeneinander, wie bei 15 rem Kartenbreite passen; hervorgehobene Karte ab 44 rem mit Bild neben dem Text |
| Programm- und Modulkarten | 1–4 | – | ab 17 rem Kartenbreite mehrspaltig; eine einzelne Karte ab 40 rem mit Tafel neben dem Text |
| Premium-Karten (Thema, Medium, Programm) | 1–4 | auto/fill | unter 520 px Platzbreite Bild oder Tafel über dem Text; ab 520 px Bild links (42 %), Text rechts (58 %), außer Variante „Bild immer über dem Text“; nutzbar ab etwa 240 px, empfohlen ab 280 px |
| Handlungsaufruf | 1–4 | auto/fill | unter 20 rem Schaltfläche in voller Breite; Beschriftungen brechen um |
| FAQ | 2–4 | – | Fragen untereinander, Antworten auf Lesebreite |
Gemessene Platzbreiten im Standardabschnitt (82 rem) bei 1440 px Fensterbreite: 1 Einheit etwa 301–319 px, 2 Einheiten 638 px, 3 Einheiten 957 px, 4 Einheiten 1312 px. Bei 1200 px Fensterbreite hat ein Platz mit 3 Einheiten 807 px; der Einstieg zeigt dort den Sicherheitsumbruch.
Ableitung: Bild und Text funktioniert dank gestapelter Darstellung auch in einer Einheit; der Einstieg braucht für seine Komposition mindestens etwa 860 px und ist deshalb nur für 3 oder 4 Einheiten freigegeben. Auf Tablet und Smartphone stapeln die Plätze; dort gelten die Breitenregeln nicht, die Widgets reagieren auf ihre Containerbreite.
## 13. Premium-Karten (Brand-UI-Kit v1.7, ADR-39)
Drei Widget-Arten auf der gemeinsamen Basis `App\Domain\Cms\Widgets\Types\PremiumCardWidget`, Ansicht `resources/views/widgets/premium_card.blade.php`, Stylesheet `resources/css/components/lf-premium-card.css` (aus `13_premium_karten_v1.7_entwurf/components/lf-premium-card.css` übernommen und angepasst). Das Kit ist ein **Entwurf zur visuellen Freigabe**; die Freigabe steht aus. Stand nach der fachlichen Nachbesserung vom 18.11.2026.
| Art | Fachobjekt (Lesesicht) | Wählbar | Gelesen | Bildbereich ohne Kartenbild | Aktion |
|---|---|---|---|---|---|
| Themenkarte `topic_card` | Säule (`Pillar`) | alle Säulen | Name, Text für die Website, Zahl veröffentlichter Seiten zum Thema | keiner | „Thema entdecken“ → `/themen/{slug}`, nur veröffentlicht |
| Medien- und Materialkarte `media_card` | Inhaltselement (`PublicMaterialReader`) | nicht archiviert, mindestens eine nicht gesperrte Fassung | Anzeigetitel (sonst Arbeitstitel), Kurzbeschreibung, Inhaltsart, Ausgabeart, Programmzugehörigkeit; Film: Hinweis auf den geschützten vollständigen Film | Film: Filmtafel (Navy, Filmstreifen, kein Abspielsymbol); Material: Materialsymbol (Creme); Redaktionsvorschau: Vorschaubild der Bibliothek, markiert | „Im Programm ansehen“ → Programmseite, nur öffentlich |
| Programm- oder Modulkarte `program_card` | Komposition (`PublicCatalogReader::subject`) | Programm/Modul, nicht archiviert, bereitgestellte Fassung | Anzeigetitel, Kurzbeschreibung (sonst Lernziel), Art, Zahl der Module, Dauer | Navy-Tafel mit Art; Redaktionsvorschau: Vorschaubild der Bibliothek, markiert | „Programm ansehen“ → `/programme/{id}`, nur Programme mit Anzeigefreigabe; Module ohne Link |
**Darstellung der Medienkarte nach Ausgabeart:** Film → Variante `lf-pc--media` (grüne Aktion, Metadatenband, Filmtafel); Dokument, Text, Hörstück, Bild → `lf-pc--material` (Materialsymbol). Die Unterscheidung folgt `output_class`, nicht einer redaktionellen Einstellung.
**Gespeichert** (Hülle wie jedes Widget): `refs.{pillar|element|composition}` (Kennung), `refs.image` (Kennung eines Medienmanager-Bildes, früher ein Pfad unter `cms/`), `data.action_label`, `data.note`, `data.alt` (Abweichung vom Alternativtext des Mediums), `data.heading` und `data.summary` (optionale Abweichung nur für diese Karte; leer übernimmt den zentralen Anzeigenamen bzw. Teaser oder Kurzbeschreibung), `data.focus_x/focus_y` (0–100, Vorgabe 66/45). Kein kopierter Lehrtext, kein Linkziel, kein Preis.
Ist `refs.image` leer, verwendet die Programm- und die Medienkarte das zentral zugeordnete Titelbild des Fachobjekts (`PresentationMedia`, zuerst Titelbild, dann Hero, Hover, alternatives Titelbild, Galerie). Gelesen wird es über `WebsiteImage`. Ohne Website-Freigabe erscheint öffentlich kein Bild; die Texte bleiben. Hat ein Widget danach keinen darstellbaren Inhalt, entfällt es. Eine eingetragene Bildkennung hat Vorrang vor dem zentralen Titelbild. Öffentliche Fachobjektprofile nach ADR-29 bleiben offen. Ein Titelbild kann ein Bild ohne Inhaltsfassung sein.
**Darstellung** (Reiter „Darstellung“): Variante `adaptive` (ab 520 px Bild neben Text) oder `stacked` (Bild immer oben); Höhe `auto` oder `fill` („An die Zeile angleichen“); `settings.format` (`landscape` 16:9 Vorgabe, `square`, `portrait` 3:4); `settings.fit` (`cover` Vorgabe, `contain` für Dokumente und Poster); `settings.heading_level` (`h3` Vorgabe, `h2`, `h4`); Anzeigen/Ausblenden von Kurzbeschreibung, Art (nicht bei Programm/Modul), Zusatzangaben und Aktion. Bildhöhe höchstens min(70vh, 640 px).
**Redaktionsvorschau.** Nicht öffentliche Karten tragen die Marke „Nur Redaktionsvorschau“. Fehlende Inhalte (Kurzbeschreibung, Text für die Website, Anzeigetitel, Dauer, Laufzeit, Kartenbild) stehen eingeklappt unter „Hinweise für die Redaktion“, mit dem Ort, an dem sie gepflegt werden. Öffentlich erscheinen weder Marke noch Hinweise noch Bibliotheksbilder.
**Raster.** Eine Karte je Platz. Gemischte Raster entstehen über die Abschnittsraster, zum Beispiel 1 + 1 + 2 (`u1_1_2`), 2 + 2, 1 + 1 + 1 + 1. Gleiche Höhe: alle Karten einer Zeile auf „An die Zeile angleichen“ stellen; die Aktion steht dann am unteren Rand. Eine öffentlich nicht sichtbare Karte lässt ihren Platz entfallen; die übrigen Plätze teilen sich die Breite. Solche Karten daher in einen eigenen Abschnitt setzen oder mit einem Platz kombinieren, der allein gut aussieht.
**Sicherheit.** Der einzuhaltende Weg steht in `medienzugriff-fuer-komponenten.md`. Vorschaubilder der Bibliothek (Filmstandbilder, Modulvorschau) nur über `editorial.card` (Redaktionsanmeldung) und nur in der Redaktionsvorschau; öffentlich nie. Keine Adressen unter `/bereich/` oder `/redaktion/` auf öffentlichen Seiten, kein Abspielen, kein Download, kein Preis, keine Kaufaktion. Nie öffentlich: Beschreibung, Einsatzhinweis, Lizenzvermerk, Lehrtexte, Traineranleitungen. Eine Karte begründet keine Berechtigung (Tests `CmsPremiumCardsTest`).
**Erweiterungsbedarf für öffentliche Vorschaubilder und Filmvorschauen (nicht umgesetzt, minimal):**
1. *Vorschaubild für die Website freigeben:* je `ContentElement` und `Composition` ein Freigabevermerk (`thumbnail_public_at`, `thumbnail_public_by`, Bezug auf `thumbnail_source`), gesetzt nur durch eine ausdrückliche Aktion „Vorschaubild für die Website freigeben“ in der Medien- bzw. Modulbearbeitung. Die Hintergrundverarbeitung kopiert das freigegebene Standbild nach `media_public` (eigener Pfad, zum Beispiel `katalog/`), Zurücknehmen löscht die Kopie. Die Karte nimmt dieses Bild, wenn kein Kartenbild gewählt ist. Der Web-Prozess schreibt weiterhin nicht in den Medienbestand.
2. *Öffentliche Filmvorschau (Trailer, Ausschnitt):* eine eigene Ausgabe (`MediaRendition` mit Rolle `preview`) und eine eigene Freigabe je Fassung, getrennt vom lizenzpflichtigen Film; ausgeliefert ohne Signatur nur nach dieser Freigabe. Bis dahin hat die Karte keine Abspielfunktion.
3. *Laufzeit:* ein Feld in den Mediendaten der Fassung (zum Beispiel `metadata.duration_seconds`, beim Transkodieren mit ffprobe ermittelt).
Alle drei Erweiterungen hängen mit ADR-29 (öffentliche Profile) zusammen und brauchen eine Entscheidung von Lars.
**Abweichungen vom Kit (bewusst):**
- Kein `.lf-pc-grid`/`.lf-pc-section`/Spannweitenklassen: Das Abschnittsraster ist das einzige Raster.
- Umschaltung bei 520 px über den Platz-Container `slot` statt eines eigenen Kartencontainers.
- Überschriftenebene ohne H1 (Karten sind nie Seiteneinstieg).
- Gelber Akzent der Tafel als `components/brand/underline` (SVG); Schriftgewichte 600 statt 750 (vorhandene Schnitte).
- Zusätzlich Filmtafel und Materialsymbol für Medien ohne freigegebenes Bild; Tafel neben dem Text mittig statt gestreckt.
**Grenzen.** Module haben keine öffentliche Seite (ADR-29) und erscheinen nur in der Vorschau. Medien öffentlich nur über ein öffentliches Programm. Keine öffentlichen Vorschaubilder ohne die oben beschriebene Freigabe. Eine **kaufbare Angebotskarte** gibt es nicht; sie braucht ein eigenes Fachobjekt „Angebot“ mit Umfang, Zweck und Lizenzbedingungen und wird gesondert konzipiert.