Feuille de route du Page Converter de WebBlocks CMS

Objectif

Page Converter est une fonctionnalité d'administration réutilisable proposée pour WebBlocks CMS, qui convertit du HTML statique collé ou téléversé en pages CMS structurées composées de blocs de premier ordre.

La fonctionnalité doit faciliter la migration vers WebBlocks CMS de sites statiques, de pages HTML écrites à la main, de pages de documentation, de pages marketing et de contenus hérités, sans réduire tout le corps de la page à un seul bloc Safe HTML.

L'objectif n'est pas de créer un importateur spécifique à webblocksui.com. Le convertisseur doit être une capacité générique du CMS, utilisable pour tout site géré par une installation de WebBlocks CMS.

État actuel de l'implémentation

La première base d'exécution est en place : Admin -> Pages -> Page Converter affiche le formulaire cible/source restreint et valide la saisie collée ou téléversée en .html / .htm, y compris les conflits de chemin cible. L'analyseur normalise le HTML soumis, extrait la zone de contenu la plus probable et affiche des suggestions ordonnées de blocs structurés avec des scores de confiance et des avertissements. L'écran de revue sérialise ces suggestions dans une charge utile signée de plan de conversion, puis Create draft page revalide les informations signées de la cible et peut créer une nouvelle page en brouillon avec les blocs pris en charge du slot principal. La création du brouillon prend en charge header, plain_text, rich-text, code, table, quote, le repli explicite html, button_link, list en tant que Rich Text, callout en tant qu'Alert, section, content_header, hero, cta, ainsi que des conteneurs card explicites avec des enfants signés card_header / card_body / card_footer. Les fragments <section> de type section sont conservés comme blocs conteneurs Section, et leurs titres, textes, liens, contenus promotionnels, grilles de cartes et groupes de details adjacents exploitables sont émis comme suggestions enfants au lieu d'être stockés comme texte de la section. Les groupes de <details> adjacents deviennent désormais une seule suggestion accordion signée avec des enfants accordion_item explicites, et la création du brouillon écrit ces éléments dans le contrat de lignes enfants faq existant lorsque les deux types de blocs, accordion et faq, sont publiés. Les suggestions de cartes dépourvues d'enfants de région exploitables explicites et les suggestions d'accordéon sans contrat d'éléments exploitable sont ignorées plutôt qu'aplaties en HTML non sûr. Les suggestions reposant sur des médias, telles que image et gallery, restent ignorées et signalées, sans importation de médias.

Un pilote compact de fixtures aux couleurs de WebBlocks UI couvre désormais un fragment réaliste de documentation/marketing statique avec <main>, des conteneurs d'en-tête et de corps de contenu, une promo, une grille de cartes, des boutons, du code, un tableau, des details adjacents et des médias image distants. La fixture garantit que l'analyse produit de nombreuses suggestions structurées plutôt qu'un unique repli Safe HTML, qu'un plan signé et une page en brouillon sont créés, que les régions de carte explicites et les liens de bouton en pied de carte sont préservés lorsque le contrat de blocs actuel peut les représenter, et que les fragments reposant sur des médias restent en simple avertissement ou ignorés, sans importer de fichiers, publier de pages, créer de navigation, toucher aux Shared Slots, récupérer des URL distantes ni écraser de contenu.

Principe fondamental

Le convertisseur doit privilégier les blocs CMS structurés plutôt qu'un unique bloc Safe HTML.

Sortie à éviter :

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

Sortie préférée :

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 n'est autorisé que comme repli visible et vérifiable pour les fragments qui ne peuvent pas encore être représentés par des blocs CMS structurés.

Positionnement du produit

Emplacement recommandé dans l'administration :

Admin -> Pages -> Page Converter

L'outil a sa place près de Pages, car sa sortie est un brouillon de page CMS. C'est un outil éditorial et de contenu, et non avant tout un outil de maintenance opérationnelle.

Point d'entrée secondaire possible :

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

Cependant, le flux principal de Page Converter doit disposer de son propre écran, car il comprend la saisie de la source, l'analyse, la revue, les avertissements et la création finale du brouillon.

Utilisateurs visés

  • super_admin : peut utiliser Page Converter pour tous les sites.
  • site_admin : peut utiliser Page Converter pour les sites qui lui sont attribués.
  • editor : envisageable plus tard ; pour le MVP, restez prudent et décidez en fonction des permissions existantes de création de pages.

Les pages générées doivent toujours démarrer en draft.

Le convertisseur ne doit jamais publier automatiquement.

Périmètre du MVP

Inclus dans le MVP

  • Écran d'administration dans la zone Pages.
  • Sélecteur du site cible limité par les accès de l'utilisateur.
  • Sélecteur de la langue (locale) cible.
  • Sélecteur du layout de la page cible.
  • Champ du titre de la page.
  • Champ slug/chemin.
  • Zone de texte pour le HTML source.
  • Téléversement d'un fichier HTML source pour .html et .htm.
  • Action Analyze qui crée un plan de conversion en mémoire.
  • Écran de revue affichant les blocs suggérés, la confiance, les avertissements et les replis.
  • Action finale Create Draft Page.
  • Validation des conflits de chemin.
  • Création de page en brouillon uniquement.
  • Création de blocs structurés pour les correspondances à forte confiance.
  • Signalement explicite des replis Safe HTML.
  • Tests ciblés.
  • Mise à jour de la documentation et du changelog.

Exclu du MVP

  • Récupération d'URL distantes.
  • Exploration de sites web.
  • Import ZIP de plusieurs pages.
  • Conversion par lots.
  • Comparaison de captures d'écran.
  • Intégration d'API d'IA.
  • Publication automatique.
  • Écrasement ou remplacement d'une page existante.
  • Téléchargement ou import de fichiers médias depuis des URL distantes.
  • Nettoyage destructif d'anciennes pages ou de blocs Safe HTML.

Modes de saisie de la source

Modes de saisie du MVP

Mode de saisie Statut Notes
Coller du HTML MVP Le point de départ le plus sûr.
Téléverser un fichier .html / .htm MVP Utile pour les exports de sites statiques.
Récupérer une URL distante Plus tard Nécessite une protection contre le SSRF et une politique réseau.
Téléverser un ZIP de pages Plus tard Nécessite une revue par lots et une gestion des conflits.
Explorer le site Plus tard Nécessite des contrôles de périmètre, des limites de débit et des listes d'URL autorisées.

Flux d&#039;administration

Étape 1 : source et cible

L'administrateur choisit :

  • Site cible
  • Langue (locale) cible
  • Layout de la page
  • Titre de la page
  • Slug/chemin de la page
  • Profil de conversion
  • HTML source collé ou fichier téléversé

Étape 2 : Analyze

Le convertisseur analyse le HTML et produit un plan de conversion sans écrire le contenu de la page dans la base de données.

Exemple de résumé d'analyse :

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.

Étape 3 : revue

L'écran de revue affiche chaque bloc suggéré :

Ordre Fragment source Bloc suggéré Confiance Avertissement
1 Content Header 96%
2 Section 92%
3 Card 94%
4 Code 99%
5 HTML de widget inconnu Repli HTML 41% Revue manuelle requise

L'écran de revue doit distinguer clairement :

  • les blocs structurés à forte confiance
  • les suggestions à confiance moyenne
  • les fragments ignorés
  • les fragments de repli Safe HTML
  • le contenu non sûr supprimé
  • les avertissements sur les médias

Étape 4 : Create Draft Page

Ce n'est qu'après une confirmation explicite que l'outil crée une nouvelle page en brouillon.

L'opération doit être transactionnelle et créer :

  • l'enregistrement de la page
  • la traduction de la page
  • les slots requis de la page
  • l'arbre des blocs
  • les traductions des blocs
  • les réglages et relations des blocs
  • les métadonnées de révision lorsque les services de révisions existants le permettent

L'outil ne doit pas publier la page.

Profils de conversion

Les profils permettent différents niveaux de rigueur de correspondance sans rendre le convertisseur spécifique à un site.

Page marketing générique

Adapté aux pages d'atterrissage et aux pages produit.

Donne la priorité à :

  • Hero
  • Section
  • Columns et Column Item lorsqu'une correspondance structurée ultérieure peut représenter la source en toute sécurité
  • Card
  • Button Link
  • CTA
  • Image
  • Gallery
  • Quote

Page de documentation générique

Adapté à la documentation et aux contenus longs.

Donne la priorité à :

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

HTML aux couleurs de WebBlocks UI

Adapté aux pages qui utilisent déjà les noms de classe de WebBlocks UI.

Donne la priorité à la correspondance basée sur les classes pour :

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

Ce profil doit rester générique et réutilisable. Il ne doit pas présupposer un domaine particulier tel que ui.webblocksui.com.

Prudent

Adapté lorsque le HTML source est désordonné ou inconnu.

Donne la priorité à :

  • moins de suppositions
  • davantage de regroupement en rich-text
  • des avertissements explicites
  • des replis visibles

Règles de correspondance du HTML vers les blocs du CMS

Règles sémantiques génériques

Motif HTML Bloc du CMS
h1-h6 header
paragraphe simple plain_text ou rich-text
plusieurs paragraphes avec mise en forme en ligne rich-text
ul, ol, li list ou rich-text selon le contexte
pre > code code
table table
blockquote quote
figure > img espace réservé image plus un avertissement sur les médias si l'import de médias n'est pas disponible
cartes répétées ou cellules répétées régions card explicites lorsqu'elles existent ; columns + column_item reste une correspondance structurée ultérieure
groupes details > summary accordion lorsque c'est possible
balisage éditorial inconnu mais sûr repli html

Règles basées sur les classes de WebBlocks UI

Motif HTML Bloc du CMS
.wb-section section
.wb-content-header content_header
.wb-promo hero ou 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 les enfants directs .wb-card deviennent des plans card explicites ; les colonnes génériques restent pour plus tard
ancre/bouton .wb-btn button_link lorsqu'il peut être représenté en toute sécurité, y compris dans les pieds de carte
.wb-alert, .wb-callout callout
.wb-gallery gallery
.wb-rich-text rich-text
.wb-link-list futur toc ou liste structurée selon le contexte
cartes répétées .wb-stat futures columns avec des éléments de type statistiques lorsque cela est pris en charge

Politique de repli Safe HTML

Safe HTML doit être un dernier recours, et non la sortie de conversion par défaut.

Cas de repli autorisés

  • Le CMS ne dispose pas encore d'un bloc de premier ordre pour ce fragment.
  • Le balisage est trop complexe pour être mis en correspondance de façon sûre dans la version actuelle.
  • La confiance du convertisseur est faible.
  • L'administrateur accepte explicitement le repli pendant la revue.

Exigences relatives au repli

Chaque repli doit apparaître dans l'écran de revue avec :

  • un aperçu du fragment source
  • le motif
  • le score de confiance
  • le texte d'avertissement
  • l'emplacement approximatif dans la page

Anti-objectif du repli

Le convertisseur ne doit pas créer un seul grand bloc Safe HTML pour tout le contenu main lorsque des correspondances significatives vers des blocs structurés sont disponibles.

Assainissement et sécurité

Le convertisseur doit assainir de façon stricte la conversion du texte structuré.

Supprimer ou rejeter :

  • <script>
  • les attributs d'événement tels que onclick
  • les URL javascript:
  • iframe
  • object
  • embed
  • les styles en ligne dangereux lorsqu'ils ne sont pas explicitement pris en charge
  • les attributs exécutables inconnus

La récupération d'URL distantes est exclue du MVP afin d'éviter les risques de SSRF. Si elle est ajoutée plus tard, elle devra bloquer :

  • localhost
  • les plages d'IP privées
  • les adresses link-local
  • les services de métadonnées
  • les noms d'hôtes internes
  • les redirections vers des adresses bloquées

Gestion des médias

Le MVP ne doit pas tenter un import complet des médias.

Pour les images :

  • détecter les références d'images
  • créer un espace réservé d'image uniquement si la correspondance avec les médias existants du CMS est implémentée
  • sinon, signaler un avertissement sur les médias
  • conserver les suggestions de texte alternatif et de légende pour un usage manuel

Les phases ultérieures peuvent ajouter :

  • le téléversement de fichiers image locaux avec une archive HTML
  • la mise en correspondance des médias existants par nom de fichier ou empreinte
  • l'import d'images depuis des paquets ZIP
  • la réécriture des blocs image vers les ID de médias du CMS

Architecture technique suggérée

Contrôleurs et requests

PageConverterController
PageConverterAnalyzeRequest
PageConverterCreateRequest

Les contrôleurs doivent rester légers et déléguer l'analyse et la conversion aux services.

Services

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

DTO / Objets valeur

ConvertedPagePlan
ConvertedSlotPlan
ConvertedBlockPlan
ConversionWarning
ConversionSourceFragment
ConversionProfile
ConversionConfidence

Flux d&#039;exécution

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

Règles de création des données

Lors de la création de la page en brouillon :

  • utiliser des transactions de base de données
  • créer uniquement une nouvelle page
  • ne jamais écraser de pages existantes dans le MVP
  • créer la page en draft
  • créer la traduction par défaut pour la langue (locale) sélectionnée
  • créer les slots requis pour le layout sélectionné
  • ne créer, dans le MVP, que des blocs appartenant à la page
  • ne pas créer de Shared Slots automatiquement
  • ne pas publier automatiquement
  • enregistrer les métadonnées de révision lorsque les services existants le permettent

Règles d&#039;autorisation

Le MVP doit suivre les règles existantes de création de pages et d'accès aux sites.

Accès recommandé :

  • super_admin : tous les sites
  • site_admin : les sites attribués
  • editor : à reporter, ou à autoriser uniquement si la création normale de pages le permet

Tous les sélecteurs de site doivent être restreints aux sites accessibles à l'utilisateur authentifié.

Règles de chemin et de conflit

Le convertisseur doit valider :

  • que le site sélectionné existe et est accessible
  • que la langue (locale) sélectionnée existe et est activée pour le site
  • que le layout sélectionné existe et est actif
  • que le titre est renseigné
  • que le chemin/slug est valide
  • que le chemin n'entre pas en conflit avec la traduction d'une page existante pour le même site et la même langue

Le MVP ne doit pas remplacer une page existante, y fusionner du contenu ni la mettre à jour.

Standards de l&#039;interface d&#039;administration

Utilisez les modèles d'administration existants de WebBlocks CMS :

  • formulaires sous forme de cartes
  • tableaux de revue compacts
  • avertissements clairs
  • modale uniquement lorsqu'elle est utile
  • pas de confirmation du navigateur pour les actions destructrices
  • pas de CSS/JS personnalisé sauf nécessité
  • uniquement des classes WebBlocks UI

L'écran de revue doit permettre de répondre facilement à ces questions :

  • Qu'est-ce qui va être créé ?
  • Quelles parties sont des blocs structurés ?
  • Quelles parties sont du HTML de repli ?
  • Quelles parties ont été ignorées ?
  • Qu'est-ce qui nécessite une revue manuelle ?

Plan de tests

Des tests fonctionnels ciblés doivent couvrir :

  • les utilisateurs autorisés peuvent ouvrir Page Converter
  • les utilisateurs non autorisés ne peuvent pas accéder aux sites inaccessibles
  • le HTML collé peut être analysé
  • le fichier .html téléversé peut être analysé
  • les types de fichiers non pris en charge sont rejetés
  • les scripts et les attributs non sûrs sont retirés de la conversion structurée
  • h1/h2 correspond à une suggestion de bloc header
  • les paragraphes correspondent à des suggestions rich-text/plain_text
  • pre > code correspond à une suggestion code
  • table correspond à une suggestion table
  • .wb-card correspond à une suggestion card
  • les éléments de carte de .wb-grid correspondent à des suggestions explicites de région card
  • les fragments inconnus sont signalés comme repli, et non supprimés silencieusement
  • un conflit de chemin cible empêche la création du brouillon
  • la page en brouillon n'est créée qu'après un envoi explicite
  • la page créée n'est pas publiée
  • aucune page existante n'est écrasée

Mises à jour de la documentation

Ajoutez ou mettez à jour :

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

La documentation doit comprendre :

  • objectif de la fonctionnalité
  • modes d'entrée de la source
  • profils de conversion
  • politique de repli Safe HTML
  • exclusions de sécurité
  • limites du MVP
  • feuille de route future

Projet de formulation du 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.

Phases d'implémentation

Phase 0 : documentation uniquement

Créez cette feuille de route et ajoutez une page de documentation CMS canonique pour la planification de Page Converter.

Aucun changement à l'exécution.

Phase 1 : analyseur en lecture seule

N'ajoutez que l'écran d'administration et le flux d'analyse.

  • Accepter du HTML collé.
  • Produire un plan de conversion.
  • Afficher l'écran de revue.
  • Ne pas encore créer de pages.

Phase 2 : créateur de brouillons

Ajoutez une action de création explicite.

  • Créer la page en brouillon.
  • Créer les blocs du slot principal.
  • Valider les conflits de chemin.
  • Conserver les avertissements dans l'interface.

Phase 3 : téléversement de fichiers HTML

Ajoutez la prise en charge du téléversement de fichiers .html / .htm.

Phase 4 : meilleures correspondances structurées

Améliorez les correspondances pour :

  • les enfants plus profonds des régions card
  • les colonnes
  • un rendu plus riche des éléments d'accordéon, au-delà de l'actuel contrat d'enfant faq en texte brut
  • les tableaux
  • les listes
  • les encadrés
  • les boutons enfants gérés de hero/cta

Phase 5 : conversion tenant compte des médias

Ajoutez une prise en charge facultative des lots d'images locales ou de la correspondance avec les médias existants.

Phase 6 : conversion par lots

Ajoutez des flux de travail multi-pages :

  • téléversement de ZIP
  • inventaire des pages
  • revue page par page
  • création de brouillons par lots

Phase 7 : récupération facultative par URL

Uniquement après la mise en place de règles strictes de SSRF et de sécurité réseau.

Critères d'acceptation du MVP

Le MVP est réussi lorsque :

  • L'administrateur peut coller ou téléverser une page HTML statique.
  • Le CMS affiche un plan de conversion consultable.
  • Les structures HTML courantes deviennent des blocs CMS structurés.
  • Le repli Safe HTML est visible et limité.
  • L'administrateur peut créer une nouvelle page en brouillon.
  • La page créée peut être modifiée dans le Page Builder habituel.
  • Aucune page n'est publiée automatiquement.
  • Aucune page existante n'est écrasée.
  • Les tests couvrent le comportement principal de conversion et de sécurité.

Notes pour la migration du site statique WebBlocks UI

La migration du site statique WebBlocks UI devrait devenir la première utilisation réelle de ce Page Converter générique.

Page pilote recommandée :

pattern-admin-standards.html

Pourquoi cette page :

  • elle contient de nombreux modèles WebBlocks UI
  • elle met à l'épreuve le comportement du layout de documentation
  • elle comprend une structure de contenu, des cartes, des tableaux, des indications d'état et des exemples proches du code
  • elle aide à valider la correspondance fondée sur les classes WebBlocks UI

La migration ne doit pas ajouter de comportement propre à WebBlocks UI directement dans le cœur du CMS. Si une intelligence de correspondance supplémentaire est nécessaire, ajoutez-la sous forme de profil réutilisable, par exemple WebBlocks UI-flavored HTML, ou plus tard comme profil facultatif d'opérateur/plugin.