# 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](0004-evaluacion-stack-multi-categoria.md) — > 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](0004-evaluacion-stack-multi-categoria.md). 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](0004-evaluacion-stack-multi-categoria.md). 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 `demo-audit@ari.local` 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 `demo-audit@ari.local` (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.