Roadmap del Page Converter di WebBlocks CMS

Scopo

Page Converter è una funzionalità di amministrazione riutilizzabile proposta per WebBlocks CMS che converte l'HTML statico incollato o caricato in pagine CMS strutturate composte da blocchi di prima classe.

La funzionalità deve aiutare a migrare in WebBlocks CMS siti statici, pagine HTML scritte a mano, pagine di documentazione, pagine di marketing e contenuti legacy, senza comprimere l'intero corpo della pagina in un unico blocco Safe HTML.

L'obiettivo non è creare un importatore specifico per webblocksui.com. Il convertitore deve essere una funzionalità generica del CMS, utilizzabile per qualsiasi sito gestito da un'installazione di WebBlocks CMS.

Stato attuale dell'implementazione

La prima base di runtime è disponibile: Admin -> Pages -> Page Converter mostra il form delimitato di origine/destinazione e convalida l'input incollato o caricato in .html / .htm, inclusi i conflitti di percorso di destinazione. L'analizzatore normalizza l'HTML inviato, estrae l'area di contenuto più probabile e mostra suggerimenti ordinati di blocchi strutturati con punteggi di affidabilità e avvisi. La schermata di revisione serializza tali suggerimenti in un payload firmato del piano di conversione, quindi Create draft page riconvalida i dati firmati della destinazione e può creare una nuova pagina in bozza con i blocchi supportati dello slot principale. La creazione della bozza supporta header, plain_text, rich-text, code, table, quote, il ripiego esplicito html, button_link, list come Rich Text, callout come Alert, section, content_header, hero, cta e contenitori card espliciti con figli firmati card_header / card_body / card_footer. I frammenti <section> con forma di sezione vengono conservati come blocchi contenitore Section e le loro intestazioni, testi, link, contenuti promozionali, griglie di card e gruppi di details adiacenti utilizzabili vengono emessi come suggerimenti figli anziché essere memorizzati come testo della sezione. I gruppi di <details> adiacenti diventano ora un unico suggerimento accordion firmato con figli accordion_item espliciti e la creazione della bozza scrive tali elementi nel contratto di righe figlie faq esistente quando entrambi i tipi di blocco, accordion e faq, sono pubblicati. I suggerimenti di card privi di figli di regione utilizzabili espliciti e i suggerimenti di accordion privi di un contratto di elementi utilizzabile vengono saltati anziché appiattiti in HTML non sicuro. I suggerimenti basati su media, come image e gallery, vengono ancora saltati e segnalati senza importare media.

Un pilota compatto di fixture in stile WebBlocks UI copre ora un frammento realistico di documentazione/marketing statico con <main>, wrapper di intestazione e corpo del contenuto, promo, griglia di card, pulsanti, codice, tabella, details adiacenti e media immagine remoti. La fixture garantisce che l'analisi produca molti suggerimenti strutturati anziché un unico ripiego Safe HTML, che vengano creati un piano firmato e una pagina in bozza, che le regioni esplicite delle card e i link dei pulsanti nel footer siano conservati quando il contratto dei blocchi attuale può rappresentarli, e che i frammenti basati su media restino solo come avviso o saltati, senza importare file, pubblicare pagine, creare navigazione, toccare gli Shared Slot, scaricare URL remoti o sovrascrivere contenuti.

Principio fondamentale

Il convertitore deve preferire i blocchi CMS strutturati a un unico blocco Safe HTML.

Output errato:

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

Output preferito:

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 è consentito solo come ripiego visibile e verificabile per i frammenti che non possono ancora essere rappresentati da blocchi CMS strutturati.

Posizionamento del prodotto

Posizione consigliata nell'amministrazione:

Admin -> Pages -> Page Converter

Lo strumento va collocato vicino a Pages perché il suo output è una bozza di pagina del CMS. È uno strumento editoriale e di contenuto, non principalmente uno strumento di manutenzione operativa.

Possibile punto di accesso secondario:

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

Tuttavia, il flusso principale di Page Converter dovrebbe avere una schermata propria, perché comprende l'inserimento dell'origine, l'analisi, la revisione, gli avvisi e la creazione finale della bozza.

Utenti di riferimento

  • super_admin: può utilizzare Page Converter per tutti i siti.
  • site_admin: può utilizzare Page Converter per i siti assegnati.
  • editor: possibile in seguito; per l'MVP mantenete un approccio prudente e decidete in base ai permessi di creazione delle pagine esistenti.

Le pagine generate devono sempre partire come draft.

Il convertitore non deve mai pubblicare automaticamente.

Ambito dell&#039;MVP

Incluso nell&#039;MVP

  • Schermata di amministrazione nell'area Pages.
  • Selettore del sito di destinazione limitato dagli accessi dell'utente.
  • Selettore della lingua (locale) di destinazione.
  • Selettore del layout della pagina di destinazione.
  • Campo del titolo della pagina.
  • Campo slug/percorso.
  • Area di testo per l'HTML di origine.
  • Caricamento del file HTML di origine per .html e .htm.
  • Azione Analyze che crea un piano di conversione in memoria.
  • Schermata di revisione che mostra i blocchi suggeriti, l'affidabilità, gli avvisi e i ripieghi.
  • Azione finale Create Draft Page.
  • Convalida dei conflitti di percorso.
  • Creazione della pagina solo in bozza.
  • Creazione di blocchi strutturati per le corrispondenze ad alta affidabilità.
  • Segnalazione esplicita dei ripieghi Safe HTML.
  • Test mirati.
  • Aggiornamento della documentazione e del changelog.

Escluso dall&#039;MVP

  • Recupero di URL remoti.
  • Crawling di siti web.
  • Importazione ZIP di più pagine.
  • Conversione in blocco.
  • Confronto tra screenshot.
  • Integrazione con API di IA.
  • Pubblicazione automatica.
  • Sovrascrittura o sostituzione di una pagina esistente.
  • Download/importazione di file multimediali da URL remoti.
  • Pulizia distruttiva di pagine vecchie o di blocchi Safe HTML.

Modalità di input dell&#039;origine

Modalità di input dell&#039;MVP

Modalità di input Stato Note
Incollare HTML MVP Il punto di partenza più sicuro.
Caricare un file .html / .htm MVP Utile per le esportazioni di siti statici.
Recuperare un URL remoto In seguito Richiede protezione da SSRF e una policy di rete.
Caricare uno ZIP di pagine In seguito Richiede revisione in blocco e gestione dei conflitti.
Effettuare il crawling del sito In seguito Richiede controlli di ambito, limiti di frequenza e allowlist di URL.

Flusso di amministrazione

Passo 1: origine e destinazione

L'amministratore sceglie:

  • Sito di destinazione
  • Lingua (locale) di destinazione
  • Layout della pagina
  • Titolo della pagina
  • Slug/percorso della pagina
  • Profilo di conversione
  • HTML di origine incollato o file caricato

Passo 2: Analyze

Il convertitore analizza l'HTML e produce un piano di conversione senza scrivere il contenuto della pagina nel database.

Esempio di riepilogo dell'analisi:

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.

Passo 3: revisione

La schermata di revisione mostra ogni blocco suggerito:

Ordine Frammento di origine Blocco suggerito Affidabilità Avviso
1 Content Header 96%
2 Section 92%
3 Card 94%
4 Code 99%
5 HTML di widget sconosciuto Ripiego HTML 41% È necessaria una revisione manuale

La schermata di revisione deve separare chiaramente:

  • blocchi strutturati ad alta affidabilità
  • suggerimenti a media affidabilità
  • frammenti ignorati
  • frammenti di ripiego Safe HTML
  • contenuto non sicuro rimosso
  • avvisi sui media

Passo 4: Create Draft Page

Solo dopo una conferma esplicita lo strumento crea una nuova pagina in bozza.

L'operazione deve essere transazionale e creare:

  • il record della pagina
  • la traduzione della pagina
  • gli slot necessari della pagina
  • l'albero dei blocchi
  • le traduzioni dei blocchi
  • le impostazioni e le relazioni dei blocchi
  • i metadati di revisione quando i servizi di revisione esistenti lo supportano

Lo strumento non deve pubblicare la pagina.

Profili di conversione

I profili consentono diversi livelli di rigore nella mappatura senza rendere il convertitore specifico per un sito.

Pagina di marketing generica

Ideale per landing page e pagine di prodotto.

Dà priorità a:

  • Hero
  • Section
  • Columns e Column Item quando una futura mappatura strutturata può rappresentare l'origine in modo sicuro
  • Card
  • Button Link
  • CTA
  • Image
  • Gallery
  • Quote

Pagina di documentazione generica

Ideale per la documentazione e i contenuti lunghi.

Dà priorità a:

  • Content Header
  • Header
  • Rich Text
  • Code
  • Table
  • List
  • Callout
  • Accordion
  • TOC

HTML in stile WebBlocks UI

Ideale per pagine che utilizzano già i nomi di classe di WebBlocks UI.

Dà priorità alla mappatura basata sulle classi per:

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

Questo profilo deve restare generico e riutilizzabile. Non deve presupporre un dominio specifico come ui.webblocksui.com.

Prudente

Ideale quando l'HTML di origine è disordinato o sconosciuto.

Dà priorità a:

  • meno supposizioni
  • maggiore raggruppamento in rich-text
  • avvisi espliciti
  • ripieghi visibili

Regole di mappatura da HTML a blocchi del CMS

Regole semantiche generiche

Pattern HTML Blocco del CMS
h1-h6 header
paragrafo semplice plain_text o rich-text
più paragrafi con formattazione inline rich-text
ul, ol, li list o rich-text a seconda del contesto
pre > code code
table table
blockquote quote
figure > img segnaposto image più un avviso sui media se l'importazione dei media non è disponibile
card ripetute o celle ripetute regioni card esplicite dove presenti; columns + column_item resta una mappatura strutturata successiva
gruppi details > summary accordion dove possibile
markup editoriale sconosciuto ma sicuro ripiego html

Regole basate sulle classi di WebBlocks UI

Pattern HTML Blocco del CMS
.wb-section section
.wb-content-header content_header
.wb-promo hero o 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 i figli diretti .wb-card diventano piani card espliciti; le colonne generiche restano per il futuro
ancora/pulsante .wb-btn button_link quando è rappresentabile in modo sicuro, anche dentro i footer delle card
.wb-alert, .wb-callout callout
.wb-gallery gallery
.wb-rich-text rich-text
.wb-link-list futuro toc o lista strutturata a seconda del contesto
card ripetute .wb-stat future columns con elementi in stile statistiche dove supportato

Policy di ripiego su Safe HTML

Safe HTML deve essere l'ultima risorsa, non l'output di conversione predefinito.

Casi di ripiego consentiti

  • Il CMS non dispone ancora di un blocco di prima classe per il frammento.
  • Il markup è troppo complesso per essere mappato in sicurezza nella versione attuale.
  • L'affidabilità del convertitore è bassa.
  • L'amministratore accetta esplicitamente il ripiego durante la revisione.

Requisiti del ripiego

Ogni ripiego deve essere mostrato nella schermata di revisione con:

  • anteprima del frammento di origine
  • motivo
  • punteggio di affidabilità
  • testo dell'avviso
  • posizione approssimativa nella pagina

Anti-obiettivo del ripiego

Il convertitore non deve creare un unico grande blocco Safe HTML per l'intero contenuto main quando sono disponibili mappature significative verso blocchi strutturati.

Sanificazione e sicurezza

Il convertitore deve sanificare in modo rigoroso la conversione del testo strutturato.

Rimuovere o rifiutare:

  • <script>
  • attributi di evento come onclick
  • URL javascript:
  • iframe
  • object
  • embed
  • stili inline pericolosi dove non esplicitamente supportati
  • attributi eseguibili sconosciuti

Il recupero di URL remoti è escluso dall'MVP per evitare rischi di SSRF. Se verrà aggiunto in seguito, dovrà bloccare:

  • localhost
  • intervalli di IP privati
  • indirizzi link-local
  • servizi di metadati
  • nomi host interni
  • redirect verso indirizzi bloccati

Gestione dei media

L'MVP non deve tentare un'importazione completa dei media.

Per le immagini:

  • rilevare i riferimenti alle immagini
  • creare un segnaposto immagine solo se è implementata la corrispondenza con i media esistenti del CMS
  • altrimenti segnalare un avviso sui media
  • conservare i suggerimenti di testo alternativo e didascalia per l'uso manuale

Le fasi successive possono aggiungere:

  • il caricamento di file immagine locali insieme a un archivio HTML
  • la corrispondenza dei media esistenti per nome file o hash
  • l'importazione di immagini da pacchetti ZIP
  • la riscrittura dei blocchi immagine con gli ID dei media del CMS

Architettura tecnica suggerita

Controller e request

PageConverterController
PageConverterAnalyzeRequest
PageConverterCreateRequest

I controller devono restare leggeri e delegare parsing e conversione ai servizi.

Servizi

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

DTO / Value Object

ConvertedPagePlan
ConvertedSlotPlan
ConvertedBlockPlan
ConversionWarning
ConversionSourceFragment
ConversionProfile
ConversionConfidence

Flusso di runtime

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

Regole di creazione dei dati

Durante la creazione della pagina in bozza:

  • usare transazioni di database
  • creare solo una nuova pagina
  • non sovrascrivere mai pagine esistenti nell'MVP
  • creare la pagina come draft
  • creare la traduzione predefinita per la lingua (locale) selezionata
  • creare gli slot necessari per il layout selezionato
  • creare nell'MVP solo blocchi di proprietà della pagina
  • non creare automaticamente Shared Slot
  • non pubblicare automaticamente
  • registrare i metadati di revisione quando i servizi esistenti lo supportano

Regole di autorizzazione

L'MVP deve seguire le regole esistenti di creazione delle pagine e di accesso ai siti.

Accesso consigliato:

  • super_admin: tutti i siti
  • site_admin: i siti assegnati
  • editor: rinviare oppure consentire solo se la normale creazione di pagine lo permette

Tutti i selettori di sito devono essere limitati ai siti accessibili all'utente autenticato.

Regole su percorsi e conflitti

Il convertitore deve convalidare:

  • che il sito selezionato esista e sia accessibile
  • che la lingua (locale) selezionata esista e sia abilitata per il sito
  • che il layout selezionato esista e sia attivo
  • che il titolo sia presente
  • che il percorso/slug sia valido
  • che il percorso non sia in conflitto con la traduzione di una pagina esistente per lo stesso sito e la stessa lingua

L'MVP non deve sostituire, unire né aggiornare una pagina esistente.

Standard dell&#039;interfaccia di amministrazione

Utilizzate i pattern di amministrazione esistenti di WebBlocks CMS:

  • moduli basati su card
  • tabelle di revisione compatte
  • avvisi chiari
  • modale solo quando è utile
  • nessuna conferma del browser per le azioni distruttive
  • nessun CSS/JS personalizzato se non necessario
  • solo classi WebBlocks UI

La schermata di revisione deve rendere facile rispondere a queste domande:

  • Che cosa verrà creato?
  • Quali parti sono blocchi strutturati?
  • Quali parti sono HTML di fallback?
  • Quali parti sono state ignorate?
  • Che cosa richiede una revisione manuale?

Piano di test

I test funzionali mirati devono coprire:

  • gli utenti autorizzati possono aprire Page Converter
  • gli utenti non autorizzati non possono accedere a siti non accessibili
  • l'HTML incollato può essere analizzato
  • il file .html caricato può essere analizzato
  • i tipi di file non supportati vengono rifiutati
  • gli script e gli attributi non sicuri vengono rimossi dalla conversione strutturata
  • h1/h2 viene mappato su un suggerimento di blocco header
  • i paragrafi vengono mappati su suggerimenti rich-text/plain_text
  • pre > code viene mappato su un suggerimento code
  • table viene mappato su un suggerimento table
  • .wb-card viene mappato su un suggerimento card
  • gli elementi card di .wb-grid vengono mappati su suggerimenti espliciti di regione card
  • i frammenti sconosciuti vengono segnalati come fallback, non scartati in silenzio
  • un conflitto nel percorso di destinazione impedisce la creazione della bozza
  • la pagina in bozza viene creata solo dopo un invio esplicito
  • la pagina creata non viene pubblicata
  • nessuna pagina esistente viene sovrascritta

Aggiornamenti della documentazione

Aggiungete o aggiornate:

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

La documentazione deve includere:

  • scopo della funzionalità
  • modalità di input della sorgente
  • profili di conversione
  • politica di fallback Safe HTML
  • esclusioni di sicurezza
  • limitazioni dell'MVP
  • roadmap futura

Bozza di testo per il 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.

Fasi di implementazione

Fase 0: solo documentazione

Create questa roadmap e aggiungete una pagina di documentazione canonica del CMS per la pianificazione di Page Converter.

Nessuna modifica a runtime.

Fase 1: analizzatore in sola lettura

Aggiungete solo la schermata di amministrazione e il flusso di analisi.

  • Accettare HTML incollato.
  • Produrre un piano di conversione.
  • Mostrare la schermata di revisione.
  • Non creare ancora pagine.

Fase 2: creatore di bozze

Aggiungete un'azione di creazione esplicita.

  • Creare la pagina in bozza.
  • Creare i blocchi dello slot principale.
  • Validare i conflitti di percorso.
  • Conservare gli avvisi nell'interfaccia.

Fase 3: caricamento di file HTML

Aggiungete il supporto al caricamento di file .html / .htm.

Fase 4: mappature strutturate migliori

Migliorate le mappature per:

  • figli più profondi delle regioni card
  • colonne
  • rendering più ricco degli elementi accordion, oltre all'attuale contratto di figlio faq in testo semplice
  • tabelle
  • elenchi
  • callout
  • pulsanti figli gestiti di hero/cta

Fase 5: conversione consapevole dei media

Aggiungete il supporto opzionale ai pacchetti di immagini locali o alla corrispondenza con i media esistenti.

Fase 6: conversione in blocco

Aggiungete flussi di lavoro multi-pagina:

  • caricamento ZIP
  • inventario delle pagine
  • revisione per singola pagina
  • creazione di bozze in blocco

Fase 7: recupero opzionale da URL

Solo dopo aver implementato regole rigorose su SSRF e sicurezza di rete.

Criteri di accettazione per l'MVP

L'MVP ha successo quando:

  • L'amministratore può incollare o caricare una pagina HTML statica.
  • Il CMS mostra un piano di conversione revisionabile.
  • Le strutture HTML comuni diventano blocchi CMS strutturati.
  • Il fallback Safe HTML è visibile e limitato.
  • L'amministratore può creare una nuova pagina in bozza.
  • La pagina creata può essere modificata nel normale Page Builder.
  • Nessuna pagina viene pubblicata automaticamente.
  • Nessuna pagina esistente viene sovrascritta.
  • I test coprono il comportamento principale di conversione e sicurezza.

Note per la migrazione del sito statico WebBlocks UI

La migrazione del sito statico WebBlocks UI dovrebbe diventare il primo utilizzo reale di questo Page Converter generico.

Pagina pilota consigliata:

pattern-admin-standards.html

Perché questa pagina:

  • contiene molti pattern di WebBlocks UI
  • mette alla prova il comportamento del layout della documentazione
  • include struttura dei contenuti, card, tabelle, indicazioni di stato ed esempi simili a codice
  • aiuta a validare la mappatura basata sulle classi di WebBlocks UI

La migrazione non deve aggiungere comportamenti specifici di WebBlocks UI direttamente al core del CMS. Se serve maggiore intelligenza di mappatura, aggiungetela come profilo riutilizzabile, ad esempio WebBlocks UI-flavored HTML, o in seguito come profilo opzionale operatore/plugin.