Hoja de ruta del Page Converter de WebBlocks CMS

Propósito

Page Converter es una función de administración reutilizable propuesta para WebBlocks CMS que convierte HTML estático pegado o subido en páginas del CMS estructuradas y compuestas por bloques de primer nivel.

La función debe ayudar a migrar sitios estáticos, páginas HTML escritas a mano, páginas de documentación, páginas de marketing y contenido heredado a WebBlocks CMS sin colapsar todo el cuerpo de la página en un único bloque Safe HTML.

El objetivo no es crear un importador específico para webblocksui.com. El conversor debe ser una capacidad genérica del CMS que pueda utilizarse con cualquier sitio gestionado por una instalación de WebBlocks CMS.

Estado actual de la implementación

La primera base en tiempo de ejecución ya está disponible: Admin -> Pages -> Page Converter muestra el formulario acotado de origen/destino y valida la entrada pegada o subida en .html / .htm, incluidos los conflictos de rutas de destino. El analizador normaliza el HTML enviado, extrae el área de contenido más probable y muestra sugerencias ordenadas de bloques estructurados con puntuaciones de confianza y advertencias. La pantalla de revisión serializa esas sugerencias en una carga útil firmada de plan de conversión y, a continuación, Create draft page vuelve a validar los datos firmados del destino y puede crear una nueva página en borrador con los bloques admitidos del slot principal. La creación del borrador admite header, plain_text, rich-text, code, table, quote, el respaldo explícito html, button_link, list como Rich Text, callout como Alert, section, content_header, hero, cta y contenedores card explícitos con hijos firmados card_header / card_body / card_footer. Los fragmentos <section> con forma de sección se conservan como bloques contenedores Section, y sus encabezados, textos, enlaces, contenido promocional, cuadrículas de tarjetas y grupos de details adyacentes utilizables se emiten como sugerencias hijas en lugar de almacenarse como texto de la sección. Los grupos de <details> adyacentes se convierten ahora en una única sugerencia accordion firmada con hijos accordion_item explícitos, y la creación del borrador escribe esos elementos en el contrato de filas hijas faq existente cuando ambos tipos de bloque, accordion y faq, están publicados. Las sugerencias de tarjeta sin hijos de región utilizables explícitos y las sugerencias de acordeón sin un contrato de elementos utilizable se omiten en lugar de aplanarse en HTML inseguro. Las sugerencias basadas en medios, como image y gallery, se siguen omitiendo y notificando sin importar medios.

Un piloto compacto de fixtures con el estilo de WebBlocks UI cubre ahora un fragmento realista de documentación/marketing estático con <main>, envoltorios de encabezado y cuerpo de contenido, promo, cuadrícula de tarjetas, botones, código, tabla, details adyacentes y medios de imagen remotos. El fixture garantiza que el análisis produzca muchas sugerencias estructuradas en lugar de un único respaldo Safe HTML, que se cree un plan firmado y una página en borrador, que se conserven las regiones de tarjeta explícitas y los enlaces de botón del pie cuando el contrato de bloques actual pueda representarlos, y que los fragmentos basados en medios se mantengan solo como advertencia u omitidos, sin importar archivos, publicar páginas, crear navegación, tocar Shared Slots, descargar URL remotas ni sobrescribir contenido.

Principio fundamental

El conversor debe preferir los bloques estructurados del CMS a un único bloque Safe HTML.

Salida incorrecta:

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

Salida preferida:

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 solo se permite como respaldo visible y revisable para los fragmentos que todavía no pueden representarse mediante bloques estructurados del CMS.

Posicionamiento del producto

Ubicación recomendada en la administración:

Admin -> Pages -> Page Converter

La herramienta debe situarse cerca de Pages porque su resultado es un borrador de página del CMS. Es una herramienta editorial y de contenido, no principalmente una herramienta de mantenimiento operativo.

Posible punto de entrada secundario:

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

Sin embargo, el flujo principal de Page Converter debe tener su propia pantalla, porque incluye la entrada del origen, el análisis, la revisión, las advertencias y la creación final del borrador.

Usuarios de destino

super_admin: puede utilizar Page Converter para todos los sitios.
site_admin: puede utilizar Page Converter para los sitios asignados.
editor: posible más adelante; para el MVP, mantenga un criterio conservador y decida en función de los permisos de creación de páginas existentes.

Las páginas generadas deben empezar siempre como draft.

El conversor nunca debe publicar automáticamente.

Alcance del MVP

Incluido en el MVP

Pantalla de administración dentro del área Pages.
Selector de sitio de destino limitado por el acceso del usuario.
Selector de idioma (locale) de destino.
Selector de layout de la página de destino.
Campo de título de la página.
Campo de slug/ruta.
Área de texto para el HTML de origen.
Subida de archivo HTML de origen para .html y .htm.
Acción Analyze que crea un plan de conversión en memoria.
Pantalla de revisión que muestra los bloques sugeridos, la confianza, las advertencias y los respaldos.
Acción final Create Draft Page.
Validación de conflictos de ruta.
Creación de páginas solo en borrador.
Creación de bloques estructurados para las correspondencias de alta confianza.
Informe explícito de los respaldos Safe HTML.
Pruebas específicas.
Actualización de la documentación y del changelog.

Excluido del MVP

Descarga desde URL remotas.
Rastreo de sitios web.
Importación ZIP de varias páginas.
Conversión por lotes.
Comparación de capturas de pantalla.
Integración con API de IA.
Publicación automática.
Sobrescritura o sustitución de una página existente.
Descarga o importación de archivos de medios desde URL remotas.
Limpieza destructiva de páginas antiguas o de bloques Safe HTML.

Modos de entrada del origen

Modos de entrada del MVP

Modo de entrada	Estado	Notas
Pegar HTML	MVP	El punto de partida más seguro.
Subir un archivo .html / .htm	MVP	Útil para exportaciones de sitios estáticos.
Descargar una URL remota	Más adelante	Requiere protección frente a SSRF y una política de red.
Subir un ZIP de páginas	Más adelante	Requiere revisión por lotes y gestión de conflictos.
Rastrear el sitio	Más adelante	Requiere controles de alcance, límites de tasa y listas de URL permitidas.

Flujo de administración

Paso 1: origen y destino

El administrador elige:

Sitio de destino
Idioma (locale) de destino
Layout de la página
Título de la página
Slug/ruta de la página
Perfil de conversión
HTML de origen pegado o archivo subido

Paso 2: Analyze

El conversor analiza el HTML y genera un plan de conversión sin escribir el contenido de la página en la base de datos.

Ejemplo de resumen del análisis:

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.

Paso 3: revisión

La pantalla de revisión muestra cada bloque sugerido:

Orden	Fragmento de origen	Bloque sugerido	Confianza	Advertencia
1		Content Header	96%
2		Section	92%
3		Card	94%
4		Code	99%
5	HTML de widget desconocido	Respaldo HTML	41%	Se requiere revisión manual

La pantalla de revisión debe separar con claridad:

bloques estructurados de alta confianza
sugerencias de confianza media
fragmentos ignorados
fragmentos de respaldo Safe HTML
contenido inseguro eliminado
advertencias sobre medios

Paso 4: Create Draft Page

Solo tras una confirmación explícita, la herramienta crea una nueva página en borrador.

La operación debe ser transaccional y crear:

el registro de la página
la traducción de la página
los slots necesarios de la página
el árbol de bloques
las traducciones de los bloques
los ajustes y las relaciones de los bloques
los metadatos de revisión cuando los servicios de revisiones existentes lo admitan

La herramienta no debe publicar la página.

Perfiles de conversión

Los perfiles permiten distintos niveles de rigor en la correspondencia sin hacer que el conversor sea específico de un sitio.

Página de marketing genérica

Recomendado para páginas de destino y páginas de producto.

Prioriza:

Hero
Section
Columns y Column Item cuando una correspondencia estructurada posterior pueda representar el origen de forma segura
Card
Button Link
CTA
Image
Gallery
Quote

Página de documentación genérica

Recomendado para documentación y contenido extenso.

Prioriza:

Content Header
Header
Rich Text
Code
Table
List
Callout
Accordion
TOC

HTML con el estilo de WebBlocks UI

Recomendado para páginas que ya utilizan los nombres de clase de WebBlocks UI.

Prioriza la correspondencia basada en clases para:

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

Este perfil debe seguir siendo genérico y reutilizable. No debe dar por supuesto un dominio concreto como ui.webblocksui.com.

Conservador

Recomendado cuando el HTML de origen es desordenado o desconocido.

Prioriza:

menos conjeturas
más agrupación en rich-text
advertencias explícitas
respaldos visibles

Reglas de correspondencia de HTML a bloques del CMS

Reglas semánticas genéricas

Patrón HTML	Bloque del CMS
h1-h6	header
párrafo simple	plain_text o rich-text
varios párrafos con formato en línea	rich-text
ul, ol, li	list o rich-text según el contexto
pre > code	code
table	table
blockquote	quote
figure > img	marcador de posición image más una advertencia de medios si la importación de medios no está disponible
tarjetas repetidas o celdas repetidas	regiones card explícitas cuando existan; columns + column_item sigue siendo una correspondencia estructurada posterior
grupos details > summary	accordion cuando sea posible
marcado editorial desconocido pero seguro	respaldo html

Reglas basadas en las clases de WebBlocks UI

Patrón HTML	Bloque 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	los hijos directos .wb-card se convierten en planes card explícitos; las columnas genéricas quedan para más adelante
ancla/botón .wb-btn	button_link cuando pueda representarse de forma segura, incluso dentro de los pies de tarjeta
.wb-alert, .wb-callout	callout
.wb-gallery	gallery
.wb-rich-text	rich-text
.wb-link-list	futuro toc o lista estructurada según el contexto
tarjetas repetidas .wb-stat	futuras columns con elementos de estilo estadístico donde se admita

Política de respaldo con Safe HTML

Safe HTML debe ser el último recurso, no el resultado de conversión predeterminado.

Casos de respaldo permitidos

El CMS todavía no tiene un bloque de primer nivel para el fragmento.
El marcado es demasiado complejo para asignarlo con seguridad en la versión actual.
La confianza del conversor es baja.
El administrador acepta explícitamente el respaldo durante la revisión.

Requisitos del respaldo

Todo respaldo debe mostrarse en la pantalla de revisión con:

una vista previa del fragmento de origen
el motivo
la puntuación de confianza
el texto de advertencia
la ubicación aproximada en la página

Antiobjetivo del respaldo

El conversor no debe crear un único bloque Safe HTML grande para todo el contenido main cuando existan correspondencias significativas con bloques estructurados.

Saneamiento y seguridad

El conversor debe sanear la conversión de texto estructurado de forma estricta.

Eliminar o rechazar:

<script>
atributos de evento como onclick
URL javascript:
iframe
object
embed
estilos en línea peligrosos cuando no se admitan explícitamente
atributos ejecutables desconocidos

La descarga desde URL remotas queda excluida del MVP para evitar riesgos de SSRF. Si se añade más adelante, debe bloquear:

localhost
rangos de IP privadas
direcciones link-local
servicios de metadatos
nombres de host internos
redirecciones a direcciones bloqueadas

Gestión de medios

El MVP no debe intentar una importación completa de medios.

Para las imágenes:

detectar las referencias a imágenes
crear un marcador de posición de imagen solo si está implementada la correspondencia con los medios existentes del CMS
en caso contrario, informar de una advertencia de medios
conservar las sugerencias de texto alternativo y de pie de foto para su uso manual

Las fases posteriores pueden añadir:

subir archivos de imagen locales junto con un archivo HTML
emparejar los medios existentes por nombre de archivo o hash
importar imágenes desde paquetes ZIP
reescribir los bloques de imagen con los ID de medios del CMS

Arquitectura técnica sugerida

Controladores y requests

PageConverterController
PageConverterAnalyzeRequest
PageConverterCreateRequest

Los controladores deben mantenerse ligeros y delegar el análisis y la conversión en los servicios.

Servicios

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

DTO / Objetos de valor

ConvertedPagePlan
ConvertedSlotPlan
ConvertedBlockPlan
ConversionWarning
ConversionSourceFragment
ConversionProfile
ConversionConfidence

Flujo en tiempo de ejecución

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

Reglas de creación de datos

Al crear la página en borrador:

utilizar transacciones de base de datos
crear únicamente una página nueva
no sobrescribir nunca páginas existentes en el MVP
crear la página como draft
crear la traducción predeterminada para el idioma (locale) seleccionado
crear los slots necesarios para el layout seleccionado
crear en el MVP solo bloques propios de la página
no crear Shared Slots automáticamente
no publicar automáticamente
registrar los metadatos de revisión cuando los servicios existentes lo admitan

Reglas de autorización

El MVP debe seguir las reglas existentes de creación de páginas y de acceso a los sitios.

Acceso recomendado:

super_admin: todos los sitios
site_admin: los sitios asignados
editor: aplazar o permitir solo si la creación normal de páginas lo permite

Todos los selectores de sitio deben limitarse a los sitios accesibles para el usuario autenticado.

Reglas de rutas y conflictos

El conversor debe validar:

que el sitio seleccionado existe y es accesible
que el idioma (locale) seleccionado existe y está habilitado para el sitio
que el layout seleccionado existe y está activo
que hay un título
que la ruta/slug es válida
que la ruta no entra en conflicto con la traducción de una página existente para el mismo sitio e idioma

El MVP no debe sustituir una página existente, ni fusionarse con ella, ni actualizarla.

Estándares de la interfaz de administración

Utilice los patrones de administración existentes de WebBlocks CMS:

formularios basados en tarjetas
tablas de revisión compactas
advertencias claras
modal solo cuando resulte útil
sin confirmación del navegador para acciones destructivas
sin CSS/JS personalizado salvo que sea necesario
solo clases de WebBlocks UI

La pantalla de revisión debe facilitar la respuesta a estas preguntas:

¿Qué se va a crear?
¿Qué partes son bloques estructurados?
¿Qué partes son HTML de reserva?
¿Qué partes se han ignorado?
¿Qué requiere revisión manual?

Plan de pruebas

Las pruebas de funcionalidad específicas deben cubrir:

los usuarios autorizados pueden abrir Page Converter
los usuarios no autorizados no pueden acceder a sitios inaccesibles
el HTML pegado puede analizarse
el archivo .html subido puede analizarse
los tipos de archivo no admitidos se rechazan
los scripts y los atributos inseguros se eliminan de la conversión estructurada
h1/h2 se asigna a una sugerencia de bloque header
los párrafos se asignan a sugerencias rich-text/plain_text
pre > code se asigna a una sugerencia code
table se asigna a una sugerencia table
.wb-card se asigna a una sugerencia card
los elementos de tarjeta de .wb-grid se asignan a sugerencias explícitas de región card
los fragmentos desconocidos se notifican como reserva, no se descartan en silencio
un conflicto en la ruta de destino impide la creación del borrador
la página en borrador se crea solo tras un envío explícito
la página creada no se publica
no se sobrescribe ninguna página existente

Actualizaciones de la documentación

Añada o actualice:

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

La documentación debe incluir:

finalidad de la funcionalidad
modos de entrada de origen
perfiles de conversión
política de reserva Safe HTML
exclusiones de seguridad
limitaciones del MVP
hoja de ruta futura

Borrador de redacción del 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.

Fases de implementación

Fase 0: solo documentación

Cree esta hoja de ruta y añada una página de documentación canónica del CMS para la planificación de Page Converter.

Sin cambios en tiempo de ejecución.

Fase 1: analizador de solo lectura

Añada únicamente la pantalla de administración y el flujo de análisis.

Aceptar HTML pegado.
Producir un plan de conversión.
Mostrar la pantalla de revisión.
Todavía no crear páginas.

Fase 2: creador de borradores

Añada una acción de creación explícita.

Crear la página en borrador.
Crear los bloques del slot principal.
Validar los conflictos de ruta.
Conservar las advertencias en la interfaz.

Fase 3: subida de archivos HTML

Añada compatibilidad con la subida de archivos .html / .htm.

Fase 4: mejores asignaciones estructuradas

Mejore las asignaciones para:

elementos hijos más profundos de las regiones card
columnas
renderizado más rico de los elementos de acordeón, más allá del contrato actual de hijo faq en texto plano
tablas
listas
avisos destacados
botones hijos gestionados de hero/cta

Fase 5: conversión con reconocimiento de medios

Añada compatibilidad opcional con paquetes de imágenes locales o con la coincidencia con medios existentes.

Fase 6: conversión por lotes

Añada flujos de trabajo de varias páginas:

subida de ZIP
inventario de páginas
revisión por página
creación de borradores por lotes

Fase 7: obtención opcional por URL

Solo después de implementar reglas estrictas de SSRF y de seguridad de red.

Criterios de aceptación del MVP

El MVP tiene éxito cuando:

El administrador puede pegar o subir una página HTML estática.
El CMS muestra un plan de conversión revisable.
Las estructuras HTML habituales se convierten en bloques CMS estructurados.
La reserva Safe HTML es visible y limitada.
El administrador puede crear una nueva página en borrador.
La página creada puede editarse en el Page Builder normal.
Ninguna página se publica automáticamente.
No se sobrescribe ninguna página existente.
Las pruebas cubren el comportamiento principal de conversión y seguridad.

Notas para la migración del sitio estático de WebBlocks UI

La migración del sitio estático de WebBlocks UI debería convertirse en el primer uso real de este Page Converter genérico.

Página piloto recomendada:

pattern-admin-standards.html

Por qué esta página:

contiene muchos patrones de WebBlocks UI
pone a prueba el comportamiento del layout de documentación
incluye estructura de contenido, tarjetas, tablas, indicaciones de estado y ejemplos similares a código
ayuda a validar la asignación basada en clases de WebBlocks UI

La migración no debe añadir comportamiento específico de WebBlocks UI directamente al núcleo del CMS. Si se necesita más inteligencia de asignación, añádala como un perfil reutilizable, por ejemplo WebBlocks UI-flavored HTML, o más adelante como un perfil opcional de operador/plugin.