WebBlocks CMS Page-Converter-Roadmap

Zweck

Der Page Converter ist eine vorgeschlagene, wiederverwendbare Admin-Funktion für WebBlocks CMS, die eingefügtes oder hochgeladenes statisches HTML in strukturierte CMS-Seiten aus erstklassigen Blöcken umwandelt.

Die Funktion soll dabei helfen, statische Sites, handgeschriebene HTML-Seiten, Dokumentationsseiten, Marketingseiten und Altinhalte in WebBlocks CMS zu migrieren, ohne den gesamten Seiteninhalt in einen einzigen Safe-HTML-Block zu pressen.

Das Ziel ist nicht, einen sitespezifischen Importer für webblocksui.com zu erstellen. Der Converter soll eine generische CMS-Fähigkeit sein, die für jede von einer WebBlocks-CMS-Installation verwaltete Site genutzt werden kann.

Aktueller Implementierungsstand

Das erste Laufzeit-Fundament steht: Admin -> Pages -> Page Converter rendert das eingeschränkte Ziel-/Quellformular und validiert eingefügte oder hochgeladene .html- / .htm-Eingaben, einschließlich Zielpfadkonflikten. Der Analyzer normalisiert das übermittelte HTML, extrahiert den wahrscheinlichsten Inhaltsbereich und zeigt geordnete Vorschläge für strukturierte Blöcke mit Konfidenzwerten und Warnungen an. Der Review-Bildschirm serialisiert diese Vorschläge in eine signierte Konvertierungsplan-Payload; anschließend validiert Create draft page die signierten Zieldetails erneut und kann eine neue Entwurfsseite mit unterstützten Main-Slot-Blöcken erstellen. Die Entwurfserstellung unterstützt header, plain_text, rich-text, code, table, quote, expliziten html-Fallback, button_link, list als Rich Text, callout als Alert, section, content_header, hero, cta sowie explizite card-Hüllen mit signierten card_header- / card_body- / card_footer-Kindern. Abschnittsartige <section>-Fragmente werden als Section-Containerblöcke erhalten, und ihre verwertbaren Überschriften, Texte, Links, Promo-Inhalte, Kartenraster und benachbarten Details-Gruppen werden als Kindvorschläge ausgegeben, statt als Abschnittstext gespeichert zu werden. Benachbarte <details>-Gruppen werden jetzt zu einem signierten accordion-Vorschlag mit expliziten accordion_item-Kindern, und die Entwurfserstellung schreibt diese Elemente in den bestehenden faq-Kindzeilen-Kontrakt, wenn sowohl der Blocktyp accordion als auch faq veröffentlicht ist. Kartenvorschläge ohne explizite verwertbare Regionskinder und Akkordeonvorschläge ohne verwertbaren Element-Kontrakt werden übersprungen, statt in unsicheres HTML abgeflacht zu werden. Medienbasierte Vorschläge wie image und gallery werden weiterhin übersprungen und gemeldet, ohne Medien zu importieren.

Ein kompakter Fixture-Pilot im WebBlocks-UI-Stil deckt jetzt ein realistisches statisches Doku-/Marketing-Fragment mit <main>, Content-Header-/Body-Wrappern, Promo, Kartenraster, Buttons, Code, Tabelle, benachbarten Details und entfernten Bildmedien ab. Das Fixture stellt sicher, dass die Analyse viele strukturierte Vorschläge statt eines einzigen Safe-HTML-Fallbacks erzeugt, einen signierten Plan und eine Entwurfsseite erstellt, explizite Kartenregionen und Footer-Button-Links erhält, wo der aktuelle Block-Kontrakt sie abbilden kann, und medienbasierte Fragmente nur mit Warnung übersprungen lässt — ohne Dateien zu importieren, Seiten zu veröffentlichen, Navigation zu erstellen, Shared Slots anzufassen, entfernte URLs abzurufen oder Inhalte zu überschreiben.

Grundprinzip

Der Converter muss strukturierte CMS-Blöcke gegenüber einem einzelnen Safe-HTML-Block bevorzugen.

Schlechte Ausgabe:

Page
└── Main Slot
    └── Safe HTML Block
        └── entire page main HTML

Bevorzugte Ausgabe:

Page
└── Main Slot
    ├── Content Header
    ├── Hero
    │   └── Button
    ├── Section
    │   └── Columns
    │       ├── Column Item
    │       ├── Column Item
    │       └── Column Item
    ├── Rich Text
    ├── Code
    ├── Table
    ├── Card
    │   ├── Card Header
    │   ├── Card Body
    │   └── Card Footer
    └── Accordion

Safe HTML ist nur als sichtbarer, überprüfbarer Fallback für Fragmente erlaubt, die noch nicht durch strukturierte CMS-Blöcke dargestellt werden können.

Produktpositionierung

Empfohlener Ort im Admin-Bereich:

Admin -> Pages -> Page Converter

Das Werkzeug gehört in die Nähe von Seiten, weil seine Ausgabe ein CMS-Seitenentwurf ist. Es ist ein redaktionelles Inhaltswerkzeug, nicht in erster Linie ein operatives Wartungswerkzeug.

Möglicher sekundärer Einstiegspunkt:

Admin -> Pages -> Import Page -> Convert HTML

Der Haupt-Flow des Page Converters sollte jedoch einen eigenen Bildschirm haben, da er Quelleingabe, Analyse, Review, Warnungen und die finale Entwurfserstellung umfasst.

Zielnutzer

super_admin: kann den Page Converter für alle Sites verwenden.
site_admin: kann den Page Converter für zugewiesene Sites verwenden.
editor: später möglich; für das MVP konservativ bleiben und anhand der bestehenden Berechtigungen zur Seitenerstellung entscheiden.

Erzeugte Seiten müssen immer als draft beginnen.

Der Converter darf niemals automatisch veröffentlichen.

MVP-Umfang

Im MVP enthalten

Admin-Bildschirm im Bereich Seiten.
Ziel-Site-Auswahl, begrenzt durch den Benutzerzugriff.
Ziel-Sprachauswahl (Locale).
Auswahl des Ziel-Seitenlayouts.
Feld für den Seitentitel.
Slug-/Pfadfeld.
Textbereich für Quell-HTML.
Datei-Upload für Quell-HTML mit .html und .htm.
Analyze-Aktion, die einen Konvertierungsplan im Arbeitsspeicher erstellt.
Review-Bildschirm mit vorgeschlagenen Blöcken, Konfidenz, Warnungen und Fallbacks.
Finale Create Draft Page-Aktion.
Pfadkonflikt-Validierung.
Seitenerstellung ausschließlich als Entwurf.
Erstellung strukturierter Blöcke für Zuordnungen mit hoher Konfidenz.
Explizite Berichterstattung über Safe-HTML-Fallbacks.
Fokussierte Tests.
Aktualisierungen von Dokumentation und Changelog.

Nicht im MVP enthalten

Abruf entfernter URLs.
Website-Crawling.
Mehrseitiger ZIP-Import.
Stapelkonvertierung.
Screenshot-Vergleich.
AI-API-Integration.
Automatisches Veröffentlichen.
Überschreiben oder Ersetzen einer bestehenden Seite.
Download/Import von Mediendateien von entfernten URLs.
Destruktives Aufräumen alter Seiten oder Safe-HTML-Blöcke.

Quelleingabemodi

MVP-Eingabemodi

Eingabemodus	Status	Anmerkungen
HTML einfügen	MVP	Sicherster Ausgangspunkt.
.html- / .htm-Datei hochladen	MVP	Nützlich für statische Site-Exporte.
Entfernte URL abrufen	Später	Erfordert SSRF-Schutz und Netzwerkrichtlinie.
ZIP mit Seiten hochladen	Später	Erfordert Stapel-Review und Konfliktbehandlung.
Site crawlen	Später	Erfordert Umfangskontrollen, Ratenbegrenzungen und URL-Allowlists.

Admin-Ablauf

Schritt 1: Quelle und Ziel

Der Admin wählt:

Ziel-Site
Ziel-Sprache (Locale)
Seitenlayout
Seitentitel
Seiten-Slug/Pfad
Konvertierungsprofil
Quell-HTML als Einfügung oder hochgeladene Datei

Schritt 2: Analysieren

Der Converter analysiert das HTML und erzeugt einen Konvertierungsplan, ohne Seiteninhalte in die Datenbank zu schreiben.

Beispiel für eine Analysezusammenfassung:

Detected page title: Admin Standards
Suggested path: /patterns/admin-standards
Suggested layout: docs
Detected blocks:
- 1 Content Header
- 8 Header blocks
- 12 Rich Text blocks
- 4 Card blocks
- 2 Table blocks
- 3 Code blocks
- 0 Safe HTML fallbacks
Warnings:
- Theme switcher controls ignored.
- Sidebar navigation detected; review whether it belongs in a Shared Slot.

Schritt 3: Review

Der Review-Bildschirm zeigt jeden vorgeschlagenen Block:

Reihenfolge	Quellfragment	Vorgeschlagener Block	Konfidenz	Warnung
1		Content Header	96%
2		Section	92%
3		Card	94%
4		Code	99%
5	Unbekanntes Widget-HTML	HTML-Fallback	41%	Manuelle Überprüfung erforderlich

Der Review-Bildschirm sollte klar trennen:

strukturierte Blöcke mit hoher Konfidenz
Vorschläge mit mittlerer Konfidenz
ignorierte Fragmente
Safe-HTML-Fallback-Fragmente
entfernte unsichere Inhalte
Medienwarnungen

Schritt 4: Entwurfsseite erstellen

Erst nach expliziter Bestätigung erstellt das Werkzeug eine neue Entwurfsseite.

Der Vorgang sollte transaktional sein und Folgendes erstellen:

Seitendatensatz
Seitenübersetzung
erforderliche Seiten-Slots
Blockbaum
Blockübersetzungen
Blockeinstellungen und -beziehungen
Revisionsmetadaten, wo bestehende Revisionsdienste dies unterstützen

Das Werkzeug darf die Seite nicht veröffentlichen.

Konvertierungsprofile

Profile ermöglichen unterschiedliche Strenge bei der Zuordnung, ohne den Converter sitespezifisch zu machen.

Generische Marketingseite

Am besten für Landingpages und Produktseiten geeignet.

Priorisiert:

Hero
Section
Columns und Column Item, wo eine spätere strukturierte Zuordnung die Quelle sicher abbilden kann
Card
Button Link
CTA
Image
Gallery
Quote

Generische Doku-Seite

Am besten für Dokumentation und Langform-Inhalte geeignet.

Priorisiert:

Content Header
Header
Rich Text
Code
Table
List
Callout
Accordion
TOC

HTML im WebBlocks-UI-Stil

Am besten für Seiten geeignet, die bereits WebBlocks-UI-Klassennamen verwenden.

Priorisiert klassenbasierte Zuordnung für:

wb-section
wb-content-header
wb-promo
wb-card
wb-grid
wb-btn
wb-alert
wb-gallery
wb-rich-text
wb-link-list

Dieses Profil sollte generisch und wiederverwendbar bleiben. Es darf keine bestimmte Domain wie ui.webblocksui.com voraussetzen.

Konservativ

Am besten geeignet, wenn das Quell-HTML unordentlich oder unbekannt ist.

Priorisiert:

weniger Vermutungen
mehr Rich-Text-Gruppierung
explizite Warnungen
sichtbare Fallbacks

Regeln für die Zuordnung von HTML zu CMS-Blöcken

Generische semantische Regeln

HTML-Muster	CMS-Block
h1-h6	header
einfacher Absatz	plain_text oder rich-text
mehrere Absätze mit Inline-Formatierung	rich-text
ul, ol, li	list oder rich-text je nach Kontext
pre > code	code
table	table
blockquote	quote
figure > img	image-Platzhalter plus Medienwarnung, wenn kein Medienimport verfügbar ist
wiederholte Karten oder wiederholte Zellen	explizite card-Regionen, wo vorhanden; columns + column_item bleibt eine spätere strukturierte Zuordnung
details > summary-Gruppen	accordion, wo möglich
unbekanntes, aber sicheres redaktionelles Markup	html-Fallback

Klassenbasierte WebBlocks-UI-Regeln

HTML-Muster	CMS-Block
.wb-section	section
.wb-content-header	content_header
.wb-promo	hero oder cta
.wb-card	card
.wb-card-header	card_header
.wb-card-body	card_body
.wb-card-footer	card_footer
.wb-grid, .wb-grid-2, .wb-grid-3, .wb-grid-4	direkte .wb-card-Kinder werden zu expliziten card-Plänen; generische Spalten bleiben späteren Versionen vorbehalten
.wb-btn Anchor/Button	button_link, wenn sicher darstellbar, einschließlich innerhalb von Karten-Footern
.wb-alert, .wb-callout	callout
.wb-gallery	gallery
.wb-rich-text	rich-text
.wb-link-list	zukünftiges toc oder strukturierte Liste je nach Kontext
wiederholte .wb-stat-Karten	zukünftige columns mit statistikartigen Elementen, wo unterstützt

Safe-HTML-Fallback-Richtlinie

Safe HTML muss ein letztes Mittel sein, nicht die Standard-Konvertierungsausgabe.

Zulässige Fallback-Fälle

Das CMS hat noch keinen erstklassigen Block für das Fragment.
Das Markup ist zu komplex, um es in der aktuellen Version sicher zuzuordnen.
Die Konfidenz des Converters ist niedrig.
Der Admin akzeptiert den Fallback während des Reviews ausdrücklich.

Fallback-Anforderungen

Jeder Fallback muss im Review-Bildschirm angezeigt werden mit:

Vorschau des Quellfragments
Begründung
Konfidenzwert
Warntext
ungefährer Position auf der Seite

Fallback-Anti-Ziel

Der Converter darf keinen einzigen großen Safe-HTML-Block für den gesamten main-Inhalt erstellen, wenn sinnvolle strukturierte Blockzuordnungen verfügbar sind.

Bereinigung und Sicherheit

Der Converter sollte die strukturierte Textkonvertierung aggressiv bereinigen.

Entfernen oder ablehnen:

<script>
Ereignisattribute wie onclick
javascript:-URLs
iframe
object
embed
gefährliche Inline-Styles, wo nicht ausdrücklich unterstützt
unbekannte ausführbare Attribute

Der Abruf entfernter URLs ist vom MVP ausgeschlossen, um SSRF-Risiken zu vermeiden. Wird er später hinzugefügt, muss er Folgendes blockieren:

localhost
private IP-Bereiche
Link-Local-Adressen
Metadatendienste
interne Hostnamen
Weiterleitungen zu blockierten Adressen

Medienbehandlung

Das MVP sollte keinen vollständigen Medienimport versuchen.

Für Bilder:

Bildreferenzen erkennen
Bildplatzhalter nur erstellen, wenn ein Abgleich mit bestehenden CMS-Medien implementiert ist
andernfalls eine Medienwarnung melden
Alt-/Beschriftungsvorschläge für die manuelle Verwendung erhalten

Spätere Phasen können ergänzen:

Hochladen lokaler Bilddateien mit einem HTML-Archiv
Abgleich bestehender Medien über Dateiname/Hash
Import von Bildern aus ZIP-Bundles
Umschreiben von Bildblöcken auf CMS-Medien-IDs

Vorgeschlagene technische Architektur

Controller und Requests

PageConverterController
PageConverterAnalyzeRequest
PageConverterCreateRequest

Controller sollten schlank bleiben und Parsing/Konvertierung an Services delegieren.

Services

Services/PageConverter/PageHtmlNormalizer
Services/PageConverter/PageHtmlSegmenter
Services/PageConverter/PageConversionEngine
Services/PageConverter/PageConversionProfileRegistry
Services/PageConverter/BlockSuggestionMapper
Services/PageConverter/ConvertedPageDraftCreator
Services/PageConverter/HtmlSafetySanitizer

DTOs / Value Objects

ConvertedPagePlan
ConvertedSlotPlan
ConvertedBlockPlan
ConversionWarning
ConversionSourceFragment
ConversionProfile
ConversionConfidence

Laufzeitablauf

HTML input
→ normalize
→ extract body/main
→ segment meaningful regions
→ map segments to block suggestions
→ calculate confidence and warnings
→ render review screen
→ create draft page in transaction

Regeln für die Datenerstellung

Beim Erstellen der Entwurfsseite:

Datenbanktransaktionen verwenden
nur eine neue Seite erstellen
im MVP niemals bestehende Seiten überschreiben
Seite als draft erstellen
Standardübersetzung für die gewählte Sprache (Locale) erstellen
erforderliche Slots für das gewählte Layout erstellen
im MVP nur seiteneigene Blöcke erstellen
keine Shared Slots automatisch erstellen
nicht automatisch veröffentlichen
Revisionsmetadaten aufzeichnen, wenn bestehende Services dies unterstützen

Autorisierungsregeln

Das MVP sollte den bestehenden Regeln für Seitenerstellung und Site-Zugriff folgen.

Empfohlener Zugriff:

super_admin: alle Sites
site_admin: zugewiesene Sites
editor: zurückstellen oder nur erlauben, wenn die normale Seitenerstellung es zulässt

Alle Site-Auswahlfelder müssen auf die für den authentifizierten Benutzer zugänglichen Sites beschränkt sein.

Pfad- und Konfliktregeln

Der Converter muss validieren:

die gewählte Site existiert und ist zugänglich
die gewählte Sprache (Locale) existiert und ist für die Site aktiviert
das gewählte Layout existiert und ist aktiv
der Titel ist vorhanden
der Pfad/Slug ist gültig
der Pfad kollidiert nicht mit einer bestehenden Seitenübersetzung für dieselbe Site und Sprache (Locale)

Das MVP darf eine bestehende Seite nicht ersetzen, in sie hineinmergen oder sie aktualisieren.

Admin-UI-Standards

Bestehende WebBlocks-CMS-Admin-Muster verwenden:

kartenbasierte Formulare
kompakte Review-Tabellen
klare Warnungen
Modal nur, wenn sinnvoll
kein Browser-Confirm für destruktive Aktionen
kein eigenes CSS/JS, sofern nicht notwendig
ausschließlich WebBlocks-UI-Klassen

Der Review-Bildschirm sollte es leicht machen, folgende Fragen zu beantworten:

Was wird erstellt?
Welche Teile sind strukturierte Blöcke?
Welche Teile sind Fallback-HTML?
Welche Teile wurden ignoriert?
Was erfordert eine manuelle Überprüfung?

Testplan

Fokussierte Feature-Tests sollten abdecken:

autorisierte Benutzer können den Page Converter öffnen
nicht autorisierte Benutzer können nicht auf unzugängliche Sites zugreifen
eingefügtes HTML kann analysiert werden
eine hochgeladene .html-Datei kann analysiert werden
nicht unterstützte Dateitypen werden abgelehnt
Skripte und unsichere Attribute werden aus der strukturierten Konvertierung entfernt
h1/h2 wird einem Header-Block-Vorschlag zugeordnet
Absätze werden Rich-Text-/plain_text-Vorschlägen zugeordnet
pre > code wird einem Code-Vorschlag zugeordnet
table wird einem Tabellen-Vorschlag zugeordnet
.wb-card wird einem Karten-Vorschlag zugeordnet
.wb-grid-Kartenelemente werden expliziten Kartenregion-Vorschlägen zugeordnet
unbekannte Fragmente werden als Fallback gemeldet, nicht stillschweigend verworfen
ein Zielpfadkonflikt blockiert die Entwurfserstellung
eine Entwurfsseite wird nur nach explizitem Absenden erstellt
die erstellte Seite wird nicht veröffentlicht
keine bestehende Seite wird überschrieben

Dokumentationsaktualisierungen

Hinzufügen oder aktualisieren:

docs/page-converter.md
docs/index.md
README.md
CHANGELOG.md

Die Dokumentation sollte enthalten:

Zweck der Funktion
Quelleingabemodi
Konvertierungsprofile
Safe-HTML-Fallback-Richtlinie
Sicherheitsausschlüsse
MVP-Einschränkungen
zukünftige Roadmap

Formulierungsentwurf für das Changelog

## Unreleased

- Add a reusable admin Page Converter foundation for turning pasted or uploaded static HTML into draft CMS pages made from structured blocks, with an analysis/review step, Safe HTML fallback reporting, and draft-only creation.

Implementierungsphasen

Phase 0: Nur Dokumentation

Diese Roadmap erstellen und eine kanonische CMS-Dokumentationsseite für die Page-Converter-Planung hinzufügen.

Keine Laufzeitänderungen.

Phase 1: Schreibgeschützter Analyzer

Nur Admin-Bildschirm und Analyseablauf hinzufügen.

Eingefügtes HTML akzeptieren.
Konvertierungsplan erzeugen.
Review-Bildschirm anzeigen.
Noch keine Seiten erstellen.

Phase 2: Entwurfsersteller

Explizite Erstellen-Aktion hinzufügen.

Entwurfsseite erstellen.
Main-Slot-Blöcke erstellen.
Pfadkonflikte validieren.
Warnungen in der Benutzeroberfläche erhalten.

Phase 3: HTML-Datei-Upload

Upload-Unterstützung für .html / .htm hinzufügen.

Phase 4: Bessere strukturierte Zuordnungen

Zuordnungen verbessern für:

tiefere Kartenregion-Kinder
Spalten
reichhaltigere Darstellung von Akkordeon-Elementen über den aktuellen Klartext-faq-Kindkontrakt hinaus
Tabellen
Listen
Callouts
verwaltete Button-Kinder für Hero/CTA

Phase 5: Medienbewusste Konvertierung

Optionale Unterstützung für lokale Bildpakete oder den Abgleich bestehender Medien hinzufügen.

Phase 6: Stapelkonvertierung

Mehrseitige Workflows hinzufügen:

ZIP-Upload
Seiteninventar
Review pro Seite
Stapel-Entwurfserstellung

Phase 7: Optionaler URL-Abruf

Erst nachdem strikte SSRF- und Netzwerksicherheitsregeln implementiert wurden.

Abnahmekriterien für das MVP

Das MVP ist erfolgreich, wenn:

Der Admin eine statische HTML-Seite einfügen oder hochladen kann.
Das CMS einen überprüfbaren Konvertierungsplan anzeigt.
Gängige HTML-Strukturen zu strukturierten CMS-Blöcken werden.
Der Safe-HTML-Fallback sichtbar und begrenzt ist.
Der Admin eine neue Entwurfsseite erstellen kann.
Die erstellte Seite im normalen Page Builder bearbeitet werden kann.
Keine Seite automatisch veröffentlicht wird.
Keine bestehende Seite überschrieben wird.
Tests das zentrale Konvertierungs- und Sicherheitsverhalten abdecken.

Hinweise zur Migration der statischen WebBlocks-UI-Site

Die Migration der statischen WebBlocks-UI-Site sollte der erste reale Einsatz dieses generischen Page Converters werden.

Empfohlene Pilotseite:

pattern-admin-standards.html

Warum diese Seite:

sie enthält viele WebBlocks-UI-Muster
sie testet das Verhalten des Doku-Layouts
sie umfasst Inhaltshülle, Karten, Tabellen, Statushinweise und codeartige Beispiele
sie hilft, die klassenbasierte WebBlocks-UI-Zuordnung zu validieren

Die Migration sollte kein WebBlocks-UI-spezifisches Verhalten direkt in den CMS-Kern einbringen. Wird zusätzliche Zuordnungsintelligenz benötigt, sollte sie als wiederverwendbares Profil wie WebBlocks UI-flavored HTML hinzugefügt werden, oder später als optionales Operator-/Plugin-Profil.