diff --git a/docs/analysen/cms-widget-registry-bericht-2026-11-17.md b/docs/analysen/cms-widget-registry-bericht-2026-11-17.md new file mode 100644 index 0000000..03276c1 --- /dev/null +++ b/docs/analysen/cms-widget-registry-bericht-2026-11-17.md @@ -0,0 +1,136 @@ +# 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/.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“. |