docs(decisiones): ADR 0004 (stack multi-categoria) y 0005 (rediseno storefront)

Fase 5 Etapa 1: auditoria del catalogo actual (categorias/colecciones
de Medusa sin uso real, nav hardcodeado, bug de +categories en Store
API), decision de evolucionar el stack en vez de reescribirlo,
patrones UX de Amazon/eBay/Walmart y taxonomia de 21 categorias ya
creada en Medusa junto con 9 productos [DEMO] validados en vivo en
shop.cruzcloud.net como linea base pre-rediseno.

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

@@ -0,0 +1,266 @@
+# 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](0004-evaluacion-stack-multi-categoria.md)),
+> 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](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 `[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.