apps-registry/workloads/docs-portal/docs/decisiones/0005-rediseno-storefront.md

ADR 0005 — Rediseño del storefront para catálogo multi-categoría

Estado: propuesta — pendiente de aprobación antes de Etapa 2 Fecha: 2026-08-23

Este documento es la propuesta de Etapa 1 del rediseño de ARI Shopping. No incluye código de producción — solo auditoría, decisión (ver también ADR 0004), patrones de UX y datos demo ya creados y visibles en producción como línea base.

1. Resumen de la auditoría

El detalle completo y la evidencia (queries reales contra Admin API y Store API) están en ADR 0004. En corto:

• Medusa nunca tuvo categorías/colecciones reales en uso — toda la taxonomía visible hoy (Figuras, Peluches, Mochilas, Marvel, Toy Story...) viene de una tabla hardcodeada en el frontend (legacyProductMeta en lib/headless/providers/medusa.ts), no de datos vivos.
• La navegación (navbar.tsx) y los tiles de home (category-tiles.tsx) son arrays hardcodeados — no escalan a 10-20 categorías sin redeploy por cada una nueva.
• Bug real descubierto en vivo: /store/products descarta la relación +categories aunque /admin/products sí la devuelve — confirmado creando categorías reales y viéndolas caer al fallback "Variedades" en el storefront público.
• El filtrado es 100% client-side sobre un máximo de 100 productos por request — techo real a la escala proyectada.
• La búsqueda es substring matching en dos capas, sin ranking ni tolerancia a errores.
• El flujo Admin → revalidate-storefront.ts → revalidateTag se confirmó intacto y funcionando en vivo durante la creación de los 9 productos demo de la sección 4 — ninguna propuesta de este documento lo modifica.

2. Decisión de stack

Evolucionar Next.js + Medusa, no reescribir. Detalle completo, opciones evaluadas y justificación en ADR 0004. Resumen de los tres cambios de Etapa 2:

1. Categorías/colecciones reales de Medusa en vez de metadata/legacy-map.
2. Fix de la relación +categories en Store API.
3. Nav y tiles de home data-driven en vez de arrays hardcodeados.

Un motor de búsqueda dedicado (Meilisearch autohospedado) queda identificado como el siguiente paso natural, no parte del alcance inmediato.

3. Patrones de UX de referencia

Se priorizaron patrones implementables con el modelo de datos de Medusa v2 tal cual quedó confirmado en la auditoría (categorías con jerarquía, colecciones, variants[].options, inventory_quantity, compareAtPrice), no patrones que exigirían rediseñar el modelo de datos desde cero.

De Amazon

1. Filtros facetados en sidebar con breadcrumb de categoría. Directamente soportado por la jerarquía parent_category_id / mpath ya confirmada en Medusa — un breadcrumb Inicio > Mochilas > Marvel es una caminata de category.parent_category, sin dato nuevo que agregar.
2. Conteo de resultados por valor de filtro (Marca (12), Mochilas (34)). Requiere agregación — o server-side simple por ahora, o vía facetas de Meilisearch cuando se agregue.
3. Carrusel "Comprados juntos frecuentemente" en la ficha de producto, reutilizando el concepto de collection en vez de inventar una relación nueva. components/product/product-carousel.tsx ya existe en el repo — es extender, no crear.
4. Barra fija de "Agregar al carrito" en móvil. components/product/mobile-add-to-cart.tsx ya existe — validar qué falta en vez de asumir que hay que construirla desde cero.

De Walmart

1. Grid de catálogo con tiles promocionales intercalados, no solo tarjetas de producto homogéneas. components/home/category-tiles.tsx ya es ese mismo primitivo visual — la propuesta es extenderlo al catálogo, no crear un componente nuevo.
2. Mega-menú de "Departamentos" (multi-columna al pasar el mouse o al tocar), en vez de la fila horizontal de 6 píldoras actual. Ataca directamente el problema de escala del nav (hallazgo de la auditoría) — factible una vez el nav lea de /store/product-categories en vez de un array fijo.
3. Badges de "Antes/Ahora" por caída de precio. El tipo Product.compareAtPrice ya existe en lib/headless/types.ts y ya se calcula en medusa.ts (compareAtPrice) — hoy casi no se usa en la UI. Ganancia visual barata, cero cambio de modelo de datos.
4. Accesos directos por categoría desde el home, por encima del hero. ARI ya hace esto con category-tiles.tsx — la propuesta es que la lista deje de ser un array de 4 tiles hardcodeado y pase a ser data-driven, igual que el nav.

De eBay

1. Selector de variante inline en la tarjeta de producto (no solo en la ficha), ej. swatches de talla/color en el grid. La forma variants[].options[].{option.title, value} que ya devuelve Medusa (confirmado en el detalle de Cybertron Sentinel, opción "Tamaño"/"Estándar") ya trae exactamente ese dato — falta renderizarlo en product-card.tsx, no traerlo.
2. Mensaje de urgencia por inventario real ("Quedan 3"). Medusa ya expone inventory_quantity por variante — hoy el frontend lo colapsa a un booleano available; la propuesta es exponer el número cuando sea bajo, sin cambiar el dato de origen.
3. Badges de vendedor/condición (nuevo/usado). Explícitamente descartado — ARI es un solo vendedor con inventario 100% nuevo; este patrón de eBay no aplica al modelo de negocio real y se incluye aquí solo para dejar constancia de que se evaluó y se descartó, no que se pasó por alto.
4. Watchlist con contador visible. Ya implementado — el storefront tiene wishlist-drawer.tsx y useWishlistStore funcionando. Se lista como confirmación de que este patrón ya está adoptado, no como pendiente.

Wireframes en texto

Home (mega-menú Walmart + tiles Amazon/Walmart):

┌─────────────────────────────────────────────────┐
│ [Logo]     [Buscador predictivo]      ♡  🛒      │
├─────────────────────────────────────────────────┤
│ ☰ Juguetes ▾  Mochilas ▾  Educativos  Bebés  ... │  ← mega-menú, no píldoras
├─────────────────────────────────────────────────┤
│  [Hero / banner promocional]                     │
├───────────┬───────────┬───────────┬──────────────┤
│ Juguetes  │ Mochilas  │Educativos │ Acción/avent. │  ← tiles, data-driven
├───────────┴───────────┴───────────┴──────────────┤
│  Destacados: [card][card][card][card]            │
└─────────────────────────────────────────────────┘

Categoría con facetas (Amazon) + breadcrumb:

Inicio > Mochilas > Marvel                            ← breadcrumb real (mpath)
┌────────────┬──────────────────────────────────────┐
│ Categoría  │  [card+swatch][card+swatch][card]     │
│ ☐ Marvel(6)│  [card+swatch][card+swatch][card]     │
│ ☐ Frozen(4)│                                        │
│ Marca      │  Antes $139.900  Ahora $109.900        │  ← badge Walmart
│ ☐ Disney   │                                        │
│ Precio     │                                        │
│ [====○===] │                                        │
└────────────┴──────────────────────────────────────┘

Tarjeta de producto (eBay: variante inline + urgencia):

┌───────────────────┐
│   [imagen]         │
│ [S][M][L]          │  ← swatches de variante inline
│ Mochila Marvel      │
│ $119.900            │
│ ⚠ Quedan 3           │  ← inventario real, no booleano
└───────────────────┘

4. Taxonomía de categorías propuesta

Basada en las categorías ya visibles hoy (Juguetes para bebés, Educativos, Muñecas y peluches, Acción y aventura, Mochilas, Variedades) y en cómo ya se agrupan los productos actuales por franquicia (Marvel, Frozen, Disney, Bob Esponja bajo Mochilas). Se creó realmente en Medusa — no es solo texto de este documento — vía Admin API, con jerarquía real (parent_category_id), 6 categorías raíz y 15 subcategorías (21 nodos totales, dentro del rango de 10-20 que se buscaba escalar):

Juguetes
├── Figuras de acción
├── Muñecas y peluches
├── Juegos de mesa y rompecabezas
└── Vehículos y control remoto

Bebés y primera infancia
├── Juguetes para bebés (0-3 años)
└── Accesorios de cuna y paseo

Educativos
├── STEM y ciencia
└── Libros y aprendizaje

Mochilas y morrales
├── Marvel
├── Frozen
├── Disney
├── Bob Esponja
└── Escolares sin licencia

Acción y aventura
├── Bicicletas y patinetas
└── Juegos al aire libre

Variedades

Además de las categorías (jerarquía exclusiva, "el pasillo del producto"), se crearon 2 colecciones reales para franquicias que cruzan varias categorías a la vez (ej. "Marvel" aparece tanto en Figuras de acción como en Mochilas): Universo Marvel y Reino de Frozen. Esta distinción categoría-vs-colección es intencional: categoría es dónde vive el producto en el árbol, colección es una vitrina temática que puede cruzar categorías — el mismo patrón que ya usa Medusa nativamente y que la auditoría confirmó operativo.

5. Productos demo creados (línea base en producción)

Creados vía Admin API de Medusa, mismo flujo validado con Cybertron Sentinel (Admin → MinIO → media.cruzcloud.net → frontend), precio real en la región Colombia (reg_01KZT86WPAH7A7ZZRDSX3350V2, COP), con descripción e imagen. Prefijo [DEMO] para identificarlos y poder limpiarlos después. Validados en vivo en el storefront actual (antes de cualquier cambio de código) el 2026-08-23 — los 9 responden HTTP 200 en su página de producto y aparecen listados en /catalog:

Producto	Categoría	Colección	Precio COP	URL
[DEMO] Guerrero Cósmico X-7	Juguetes > Figuras de acción	Universo Marvel	$89.900	/product/demo-guerrero-cosmico-x-7
[DEMO] Mochila Escudo Vengador	Mochilas > Marvel	Universo Marvel	$119.900	/product/demo-mochila-escudo-vengador
[DEMO] Mochila Reino Helado	Mochilas > Frozen	Reino de Frozen	$109.900	/product/demo-mochila-reino-helado
[DEMO] Kit de Robótica Junior	Educativos > STEM y ciencia	—	$149.900	/product/demo-kit-de-robotica-junior
[DEMO] Set de Bloques Lógicos	Educativos > STEM y ciencia	—	$69.900	/product/demo-set-de-bloques-logicos
[DEMO] Sonajero Suave Nubes	Bebés > Juguetes para bebés	—	$39.900	/product/demo-sonajero-suave-nubes
[DEMO] Patineta Urbana Flash	Acción y aventura > Bicicletas y patinetas	—	$199.900	/product/demo-patineta-urbana-flash
[DEMO] Set de Camping Junior	Acción y aventura > Juegos al aire libre	—	$89.900	/product/demo-set-de-camping-junior
[DEMO] Caja Sorpresa ARI	Variedades	—	$49.900	/product/demo-caja-sorpresa-ari

Comportamiento observado en la línea base actual (importante para Etapa 2): los 9 productos muestran su marca (metadata.brand) y precio correctamente en el storefront de hoy, pero su categoría real no se refleja todavía — aparecen bajo "Variedades" por el bug de Store API descrito en la sección 1 y en el ADR 0004. Esto es evidencia en vivo, no hipotética, de por qué el fix de esa relación es el primer paso de Etapa 2: sin él, ninguna categoría real se verá nunca en el storefront público, sin importar qué tan bien esté modelada en Medusa Admin.

Imágenes: subidas vía /admin/uploads (mismo pipeline S3/MinIO que Cybertron Sentinel), placeholders claramente marcados como DEMO en el texto de la imagen — no fotos reales de producto, ya que el objetivo es validar la tubería Admin → MinIO → NPM → frontend, no el contenido visual final.

Usuario admin temporal [email protected] usado para esta auditoría — pendiente de borrar una vez aprobada esta propuesta.

6. Próximos pasos

Pendiente de tu aprobación explícita antes de iniciar Etapa 2. Cuando apruebes, Etapa 2 se dividirá en sub-fases (datos/categorías primero, luego navegación, luego componentes visuales), validando en cada paso contra estos 9 productos demo que precio/descripción/imágenes siguen actualizándose correctamente desde Admin.