Saltar a contenido

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

Estado: aceptada — Etapa 2 implementada y en producción Fecha: 2026-08-23 (Etapa 1) — actualizado 2026-08-25 (Etapa 2 completa)

Este documento arrancó como la propuesta de Etapa 1 del rediseño de ARI Shopping (auditoría, decisión — ver también ADR 0004 — patrones de UX y datos demo). Etapa 2 fue aprobada y se implementó completa en tres sub-fases (datos/categorías, navegación, componentes visuales) — ver la sección 6 para el detalle de cada sub-fase y sus PRs.

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 (ver sección 6).

6. Etapa 2 — implementada (2026-08-23 a 2026-08-25)

Aprobada y ejecutada en tres sub-fases, cada una validada en vivo contra estos 9 productos demo:

  1. Datos/categorías (2026-08-23/24): fix del bug de Store API que impedía ver la categoría real de un producto (causa raíz del ADR 0004); 21 categorías/9 productos demo creados; legacyProductMeta eliminado (PR #29) — 17 productos legacy con categoría/colección/ marca/rango de edad reales.
  2. Navegación (2026-08-25): navbar y tiles del home pasaron de arrays hardcodeados a data-driven contra el árbol real de categorías (getCategories(), PR #32); guard de CI actualizado (PR #33); fix de tipos (PR #34); home/layout forzados a render dinámico para evitar que quedaran cacheados con datos mock (PR #35).
  3. Componentes visuales (2026-08-25), los 4 patrones de la sección 3 más el breadcrumb/facetas de Amazon: mega-menú "Departamentos" multi-columna (PR #36), badges antes/ahora (PR #37), swatches de variante inline (PR #38), mensaje de urgencia por inventario real (PR #39), breadcrumb real + conteos por filtro en el catálogo (PR #40), tiles promocionales intercalados en la grilla (PR #41, con fix-forward de tipos en PR #42).

El usuario admin temporal [email protected] (creado para la auditoría de la sección 5) fue borrado el 2026-08-27 vía Medusa Admin. Sin próxima etapa definida todavía — este ADR no especifica una Etapa 3.