Files
laraundfelix/docs/analysen/cms-widget-registry-bericht-2026-11-17.md
T
LarsandClaude Opus 5.5 db4bd30319
Deploy Test / test (push) Successful in 26s
CI Feature / test (push) Successful in 25s
Deploy Test / deploy (push) Successful in 27s
Dokumentiere Umsetzung und Prüfung der Widget-Registry.
Abschlussbericht mit Ist-Befund, Komponenten, Varianten, Testergebnissen,
lokaler Browserprüfung und Prüfung auf der Testinstanz (Bestandsseiten
vor/nach dem Deploy identisch, Referenzseite, Navigation, T8-Messung),
bekannten Einschränkungen und offenen Entscheidungen zu ADR-28/29/30.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 18:19:10 +01:00

14 KiB
Raw Blame History

Abschlussbericht: CMS-Grundsystem, Widget-Registry und Seiteneditor

Stand: 17.11.2026 · Branch feature/cms-widget-registry (Commits 9d936bf, 2dc479a), auf develop gemergt und auf die Testinstanz deployt. Nicht auf main/Produktion. Technische Details: docs/architektur/cms-widget-registry.md.

Eine erfolgreiche technische Umsetzung ist keine fachliche Freigabe von ADR-28/ADR-30. Die UX-Abnahme erfolgt durch den Auftraggeber.

Ist-Befund vor der Umsetzung

Bereich Befund im Code (vor 9d936bf)
Seiten/Revisionen pages mit Zeiger auf veröffentlichte Revision, page_revisions mit Bausteinen als JSON; Speichern = neue Revision, Veröffentlichen = Zeiger, Wiederherstellen = neue Revision. Bestätigt.
Bausteine sechs Arten in einer Klasse BlockRegistry (Regeln per match), flaches JSON ohne Version, Variante oder Kennung. Bestätigt wie beobachtet: Karten = wiederholbare Einträge Titel/Text/Adresse; Bild und Text = Text, Upload, Alternativtext.
Editor ein Repeater, alle Felder aller Arten im selben Formular, per Sichtbarkeitsbedingung ein-/ausgeblendet. Keine Vorschau im Editor.
Vorschau Route vorhanden, aber unter dem Mitglieder-Guard; ein nur in der Verwaltung angemeldeter Redakteur wurde zur Mitgliederanmeldung umgeleitet. Keine Breitenumschaltung.
Navigation Anlegen möglich; Tabelle ohne Bearbeiten-, Löschen- oder Sortieraktion. Adressen ohne Schemaprüfung (javascript: wurde angenommen und ausgegeben).
Medien Upload nach cms_incoming, Übertragung nach media_public in der Queue; nur image_text.
Programme/Module öffentliche Programmliste /programme zeigt Kompositionen der Inhaltsart „programm“ mit Anzeigefreigabe. Öffentliche Profile (ADR-29) existieren nicht; für Module gibt es keine öffentliche Seitenart.
W-P-Prototyp Die Analyse wp-editor-prototyp-2026-03-15.md beschreibt Code, der im Repository nicht existiert (Branch ohne eigene Commits).

Keine grundlegende Unvereinbarkeit mit dem Auftrag; daher ohne Vorabentscheidung umgesetzt.

1. Wiederverwendete Bestandteile

Seiten-/Revisionsmodell und Tabellen (unverändert), PageService (Entwurf/Veröffentlichen/Wiederherstellen), Vorschauroute, Navigationsverwaltung (NavigationItemResource), öffentlicher Medienweg (cms_incoming → PublishPublicMedia → media_public, /medien/cms/…), Anzeigefreigabe der Bibliothek (CompositionDisplayRelease), Stylesheet und Markenwerte, Textwortmarke, Filament-Builder/Repeater/Modal, Policies (PagePolicy, NavigationItemPolicy).

2. Neu implementierte Komponenten

Komponente Datei(en)
Widget-Vertrag und Register app/Domain/Cms/Widgets/WidgetType.php, WidgetRegistry.php, config/cms.php
Gemeinsamer Renderer app/Domain/Cms/Widgets/WidgetRenderer.php, resources/views/widgets/*
8 Widget-Arten app/Domain/Cms/Widgets/Types/*
Hilfen (sichere Links, bereinigter Text, öffentliche Medien, Bildauswahl) app/Domain/Cms/Widgets/Support/*
Katalog-Lesesicht app/Domain/Cms/Catalog/PublicCatalogReader.php (auch von /programme genutzt)
Editor-Adapter app/Filament/Support/WidgetEditor.php, WidgetBlock.php
Geräte-Vorschau /redaktion/vorschau/{revision}/geraete, resources/views/public/preview-devices.blade.php
Basislayout resources/views/components/site/{brand,header,footer}, site/templates/standard, PageTemplates
Navigation Bearbeiten, Aus-/Einblenden, Löschen, Ziehen zum Sortieren, Gruppen Kopf/Fuß; Migration is_visible (ergänzend)

3. Registry und Erweiterungsschnittstelle

Jede Widget-Art ist eine Klasse mit Typkennung, Name, Beschreibung, Schemaversion, Prüfregeln für data/refs, freigegebenen Varianten, optionalen Aufzählungs-Einstellungen, Editorfeldern, Blade-Ansicht, Verweisauflösung, Medienliste und Zusammenfassung. Gespeichert wird die Hülle {id, type, v, variant, settings, data, refs} aus dem Architekturentwurf. Editor, Speicherung, Vorschau und öffentliche Seite lesen alles aus dem Register; der Editor enthält keine Sonderfälle je Art. Altbestand wird beim Lesen angehoben, gespeicherte Revisionen bleiben unverändert.

4. Widget-Arten und Varianten

Art Varianten Bemerkung
Einstieg (Hero) – neu Standard (Bild neben Text), Hervorgehoben (Markenfläche) optionales Bild und Handlungsaufruf
Bild und Text – erweitert (v2) Bild links, Bild rechts optionaler Titel, formatierter Text (fett, kursiv, Link, Listen), Bild aus vorhandenen Website-Bildern oder neu, Alternativtext; mobil untereinander
Redaktionelle Karten – erweitert Raster, Kompakte Liste Titel, Beschreibung, Linkziel, optionales Bild, sortierbar
Programm- und Modulkarten – neu Karten mit Kurzbeschreibung, Kompakte Liste nur Verweise; Inhalte aus den Fachdaten
Überschrift und Einleitung, Fließtext, Handlungsaufruf, FAQ Standard unverändert übernommen (v1)

5. Weiteres Widget hinzufügen

Klasse in app/Domain/Cms/Widgets/Types/ (von WidgetType ableiten), Ansicht resources/views/widgets/<kennung>.blade.php, Eintrag in config/cms.php, Tests. Ablauf und Regeln: docs/architektur/cms-widget-registry.md, Abschnitt 5.

6. Testergebnisse

  • Lokal: 145 Tests, 996 Assertions grün; Pint sauber. Neu: tests/Unit/WidgetRegistryTest.php (Registrierung, Validierung, Varianten, Einstellungen, Bereinigung, Versionierung, Altformat, Kennungen, neues Widget allein über den Vertrag), tests/Feature/CmsWidgetRenderingTest.php (Bestandsseiten im flachen Altformat textgleich zum Stand vor der Umstellung, Rundlauf durch den Editor, Varianten, Medienveröffentlichung, Katalogregeln inkl. Rücknahme der Freigabe), tests/Feature/CmsEditorTest.php (Anlegen, Bearbeiten, Sortieren, Duplizieren, Fehleranzeige, Vorschauzugriff, Navigation).
  • CI-Gate ci-feature.yml (Pint, Suite, Migrationen gegen Wegwerf-Postgres): Läufe #53 und #54 erfolgreich.
  • deploy-test.yml: siehe Abschnitt 7.
  • Entfernt: tests/Unit/BlockRegistryTest.php; beide Prüfungen (Alternativtext, javascript:-Links) stecken erweitert in WidgetRegistryTest.

7. Browserprüfungen

Lokal (Playwright, Kopie der Anwendung mit Prüfbestand)

Szenario Ergebnis
Neue Seite anlegen; Widgets aus der Auswahl (Name, Beschreibung, Schema) wählen und konfigurieren bestanden
Bild hochladen, formatierter Text, Variante „Bild rechts“ bestanden
Programm und Modul per Suche referenzieren bestanden (Programm öffentlich, Modul nur in der Vorschau mit Hinweis)
Variante wechseln, Blockvorschau ohne Speichern bestanden
Abschnitte sortieren (Pfeile), duplizieren bestanden
Vorschau 390/768/1440 px bestanden
Vor Veröffentlichung nicht öffentlich (404), danach sichtbar; keine horizontale Scrollbar in allen drei Breiten bestanden
Redaktionelle Änderung: Entwurf ändert Live-Seite nicht; nach Veröffentlichen geändert bestanden
Frühere Revision wiederherstellen und veröffentlichen bestanden
Navigation: anlegen mit interner Seite, bearbeiten, ausblenden/einblenden, per Ziehen sortieren bestanden
Acht Bestandsseiten bei 390 px erreichbar bestanden
T9: Bild ohne Alternativtext → Meldung „Abschnitt 5 (Einstieg (Hero)): …“, nichts gespeichert; leeres Pflichtfeld hält den Dialog offen bestanden (nach Nachbesserung)

Im Browser gefundene und behobene Fehler: Pfadfehler wurden nicht angezeigt (Speichern blieb wirkungslos), doppelter Pfad hätte einen Serverfehler ausgelöst, Kopfzeile der Vorschau zeigte die Personal- statt der Besucheransicht, Registry-Fehler waren bei geschlossenen Dialogen unsichtbar, „Seite anlegen“ verwarf gewählte Säulen.

Testinstanz (http://192.168.2.144:3011, nach deploy-test.yml #4805, erfolgreich)

Prüfung Ergebnis
Bestandsseiten vor/nach dem Deploy (/, /angebote, /datenschutz, /impressum, /materialien, /praevention, /trainer, /ueber, /programme, /themen): Status, Seitentitel und Text des Inhaltsbereichs 10/10 identisch (Daten im Altformat aus der Testdatenbank)
Referenzseite /praevention-im-alltag anlegen mit Hero, Bild und Text, redaktionellen Karten, Programm-/Modulkarten (Programm „Programm Abstand“, Modul „Modul Abstand“), Säule „Sicher handeln im Alltag“ bestanden
Variante wechseln, sortieren, Vorschau 390/768/1440, Veröffentlichen, Änderung, Wiederherstellen 22/22 bestanden
Öffentlich: Programmkarte aus den Fachdaten mit Link auf die Programmseite, Modul ausgeblendet, Bild aus /medien/cms/, keine horizontale Scrollbar in drei Breiten bestanden
Navigation: Eintrag „Themenseite Prävention“ angelegt, bearbeitet (und zurückgesetzt), aus-/eingeblendet, per Ziehen an Position 2 sortiert; Bestandsseiten bei 390 px 14/14 bestanden
T8: Seite mit 20 Abschnitten öffnen, einen Text ändern, übernehmen, speichern Öffnen 1,3 s · Dialog 0,3 s · Übernehmen 1,1 s · Speichern 1,0 s (Grenze 3 s je Vorgang)

Auf der Testinstanz angelegte bzw. geänderte Daten: veröffentlichte Seite /praevention-im-alltag (Bild: neutrales Platzhalterbild mit entsprechendem Alternativtext, da kein Bildmaterial freigegeben ist), unveröffentlichte Messseite /pruefung-zwanzig-abschnitte, Navigationseintrag „Themenseite Prävention“ (Kopfzeile, Position 2), Zwei-Faktor-Einrichtung für das Prüfkonto vibecoder@example.de. Auf Test ist noch kein Themenbereich veröffentlicht; die Zuordnung zur Säule wird erst mit dessen Veröffentlichung unter /themen sichtbar.

Nicht automatisiert geprüft: die Bedienaufgaben T1–T9 mit dem Betreiber und Zeitmessung (UX-Abnahme), Bildschirmleser, echte Mobilgeräte.

8. Bekannte Einschränkungen

  • Rollback: Nach dem Deploy im Editor gespeicherte Seiten liegen im neuen Format; ein reiner Code-Rollback stellt sie nicht dar (Fehler 500 auf diesen Seiten). Abhilfe: Revision aus der Zeit vor dem Deploy veröffentlichen oder wieder vorwärts deployen. Vor dem Merge nach main beachten.
  • Module öffentlich: erst mit öffentlichen Profilen (ADR-29). Bis dahin nur Redaktionsvorschau.
  • Vorschaubilder von Programmen/Modulen werden öffentlich nicht gezeigt (geschützt, Paket 6); die Karte zeigt eine Inhaltsart-Fläche.
  • Archivierte Programme erscheinen in der Liste /programme weiterhin (Bestandsverhalten), im Katalog-Widget nicht.
  • Verwaiste Uploads: Wird ein Dialog mit neuem Bild verworfen oder die Seite nicht gespeichert, bleibt die Datei in cms_incoming liegen (kein Aufräumen).
  • Kartenbilder gelten als dekorativ (alt="").
  • Bildauswahl zeigt Dateinamen, keine Miniaturen; die Blockvorschau zeigt das gewählte Bild sofort.
  • Unbekannte Widget-Arten (zum Beispiel nach einem Code-Rollback) entfallen beim nächsten Speichern im Editor.
  • Markenzeichen: Textwortmarke; laut Brand-UI-Kit gibt es keine freigegebene Logodatei und ungeklärte Bildrechte. Es wurden keine Kit-Dateien übernommen.
  • Settings (Flächenton, Breite, Abstand) sind im Vertrag vorgesehen und geprüft, aber von keiner Art genutzt.
  • In der Automatisierung musste nach einer Auswahl im Katalog-Widget kurz gewartet werden, bevor der nächste Eintrag hinzugefügt wurde; bei menschlicher Bedienung nicht beobachtet, aber in der UX-Abnahme zu beachten.

9. Offene fachliche Entscheidungen

  1. Öffentliche Fachobjektprofile (ADR-29): Listungsentscheidung, gezeigte Fassung, öffentlich freigegebenes Bild – Voraussetzung für öffentliche Modulkarten und Bilder auf Programmkarten.
  2. Soll eine Anzeigefreigabe für Programme weiterhin automatisch öffentliche Sichtbarkeit bedeuten (heutiges Verhalten von /programme, im Widget übernommen), bis ADR-29 umgesetzt ist?
  3. Freigabe einer Logodatei und von Bildmaterial (Brand-UI-Kit) für die öffentliche Website.
  4. Seitentypen/Vorlagen und globale Abschnitte (ADR-28 Variante D): technisch vorbereitet (PageTemplates), fachlich nicht entschieden.
  5. Sollen archivierte Programme aus /programme verschwinden?
  6. Medienbibliothek für Website-Bilder mit Alternativtext je Bild statt je Verwendung.

ADR-28 / ADR-30: bestätigt bzw. widerlegt

Vorschlag Ergebnis der Umsetzung und Prüfung
ADR-30: codebasiertes Register mit Hülle {id, type, v, variant, settings, data, refs} bestätigt. Umgesetzt; eine nur im Test definierte Art läuft ohne Änderung an Editor oder Darstellung.
ADR-30: alte Revisionen über Schema-Aufwärtsfunktion lesbar bestätigt. Flache Altrevisionen und image_text v1→v2 werden beim Lesen angehoben; textgleich zur alten Darstellung.
ADR-30: Vorschau und öffentliche Darstellung mit derselben Rendererlogik bestätigt. Ein Renderer; die Blockvorschau braucht dafür ein isoliertes iframe, weil Website- und Verwaltungsstile kollidieren.
ADR-30: Katalogbausteine speichern nur Kennungen; nicht öffentliche Objekte erscheinen nicht bestätigt mit Übergangsregel (Abschnitt 8 und 9).
ADR-28: Ausbau des Eigen-CMS mit Filament-Bordmitteln ist bedienbar technisch bestätigt, UX-Abnahme offen. Builder mit Vorschau, Dialog, Sortieren, Duplizieren funktioniert ohne Zusatzpaket (K4). Die neun Bedienaufgaben mit dem Betreiber (Zeitmessung T1–T9) stehen aus; T8 siehe Abschnitt 7.
ADR-28: Vorlagen und globale Abschnitte nicht geprüft (nicht beauftragt).
Zielarchitektur 5.4: blockPreviews() rendert die öffentliche Blade-Ansicht mit Einschränkung bestätigt: Stilisolation per iframe nötig; Felder im Dialog erfordern eine zusätzliche Fehlermeldung beim Speichern.
Zielarchitektur 5.4: Auswahl nur öffentlich geschalteter Objekte teilweise widerlegt für den Übergang: Damit Module überhaupt kuratiert werden können, bietet der Editor auch nur zur Anzeige freigegebene Module an und kennzeichnet sie „nur Redaktionsvorschau“.