RF-004 — Bloques comerciales para el armado de páginas¶


Estado	Implementado
Tipo	Bloques propios del layout de `pages`
Ubicación	`src/blocks/Hero/Hero.ts` · `src/blocks/HeroSlider/HeroSlider.ts` · `src/ProductGrid.ts`
Depende de	RF-001 · RF-002 · RF-005
Ver también	ADR-0001 — Bloques sin componente React

Requisito¶

Permitir al editor componer una página combinando piezas comerciales —un banner, un carrusel y una cuadrícula de productos— sin intervención técnica; y describir la cuadrícula como una consulta de catálogo parametrizable (tipo de filtro, valor, cantidad por página y orden) que resuelve el storefront, sin que el CMS consulte productos.

Solución adoptada¶

Declarar tres bloques propios disponibles en el layout de las páginas, definidos como esquema y tipos, sin componente React en este repositorio: el render corresponde al storefront. Los dos primeros no definen contenido propio, sino que referencian entidades reutilizables.

flowchart TB
    PG[Página · layout] --> H[hero]
    PG --> HS[heroSlider]
    PG --> P[productGrid]
    H -->|relación requerida| B[(banners)]
    HS -->|relación requerida| S[(sliders)]
    P --> D[Descriptor de consulta<br/>filterType · filterValue · itemsPerPage · sortBy]
    D -.resuelto por el storefront.-> ALG[(Algolia)]
    PG -.esquema + tipos.-> SF([Storefront · render])

Bloques¶

Bloque	Nombre en el panel	Contenido	Tipo exportado
`hero`	Banner	Relación requerida a `banners`; cuatro campos heredados ocultos	`HeroBlock`
`heroSlider`	Slider	Relación requerida a `sliders`	sin `interfaceName`
`productGrid`	Cuadrícula de Productos	Descriptor de consulta de catálogo	`ProductGridBlock`

Descriptor de la cuadrícula¶

Campo	Regla
`titulo`	`Productos Destacados` por defecto
`filterType`	`tag` por defecto; admite categoría, etiqueta, colección o personalizado (`index`)
`filterValue`	Valor buscado; admite varios separados por coma
`itemsPerPage`	12 por defecto, entre 1 y 100
`sortBy`	`relevance` por defecto; precio ascendente o descendente, fecha de alta descendente, nombre ascendente o descendente
`tagDeBusqueda`	`[OBSOLETO]` — visible solo si la fila ya tenía valor
`filterQuery`	`[Obsoleto]` — oculto

Reglas de negocio¶

Separar contenido de presentación: el CMS define qué mostrar; el storefront decide cómo.
Referenciar entidades en lugar de duplicar contenido, de modo que la pieza se edite en un solo lugar.
No consultar el catálogo desde el CMS: la cuadrícula persiste un descriptor, nunca un resultado.
Exigir la relación en los bloques hero y heroSlider: una página no puede quedar con un bloque vacío.
Conservar ocultos los campos superados del bloque hero, por compatibilidad con las páginas cargadas antes de que pasara a referenciar la colección.

Criterios de aceptación¶

#	Criterio
1	Componer una página con los tres bloques y recuperarla por API con sus relaciones resueltas
2	Rechazar la publicación de un bloque `hero` o `heroSlider` sin entidad referenciada
3	Modificar el banner referenciado y ver el cambio en la página sin editarla
4	Configurar una cuadrícula por etiqueta, con orden y cantidad por página, y recibir el descriptor íntegro en la respuesta

Limitaciones conocidas¶

heroSlider no declara interfaceName: su tipo queda embebido en Page['layout'] dentro de payload-types.ts y el storefront no puede importarlo por nombre. Es una línea de configuración.
Los cuatro campos heredados de hero están ocultos sin la etiqueta [Obsoleto] que sí llevan los demás campos superados del repositorio.
El valor del filtro personalizado difiere del usado en el menú de navegación — ver RF-005.