RF-002 — Búsqueda y navegación de catálogo con Algolia
Requisito
Resolver la búsqueda de productos y la navegación filtrada del catálogo con tiempos de respuesta
de buscador dedicado, con autocompletado sobre términos frecuentes, facetas por categoría, precio
y atributos, ordenamiento y paginación; y mantener el estado del filtrado en la URL, de modo que
un resultado filtrado sea compartible y recuperable.
Solución adoptada
Delegar la búsqueda y las grillas a un índice de Algolia replicado del catálogo, y reservar a
Medusa la jerarquía de categorías, las colecciones y la ficha de producto. Las grillas de la
tienda se renderizan con InstantSearch y el enrutador de Next; las grillas de contenido
—portada y bloques del CMS— se resuelven en el servidor con un cliente propio.
flowchart LR
N([Navegador]) -->|autocompletado| SUG[(Índice de sugerencias)]
N -->|InstantSearch| IDX[(Índice de productos)]
SRV[Server Components] -->|descriptores del CMS| IDX
N -->|ficha, categorías, colecciones| MED[(Medusa)]
IDX -.replicado por integración externa.-> MED
Funciones
| Función |
Superficie |
Detalle |
| Búsqueda con autocompletado |
SearchBar, SearchModal |
Consulta simultánea al índice de sugerencias (5 resultados) y al de productos (8 resultados) |
| Grilla de tienda |
instantsearch-store-template |
Resultados con paginación y scroll infinito |
| Filtros facetados |
algolia-sidebar, algolia-store-filters, mobile-filter |
Categorías, rango de precio y atributos, con vista propia para móvil |
| Ordenamiento |
refinement-list/sort-products |
Relevancia, precio ascendente y descendente, novedades y nombre |
| Estado en la URL |
parse-search-params.ts |
Sincronización bidireccional entre la URL y el estado de la búsqueda |
| Grillas de contenido |
lib/algolia-products.ts |
Resolución en servidor de los descriptores del CMS: por categoría, etiqueta, colección o consulta libre |
| Facetas y catálogos auxiliares |
getFacets(), getCategories(), getTags() |
Alimentan los filtros disponibles |
Reglas de negocio
- Resolver contra Algolia toda grilla y todo resultado de búsqueda; consultar Medusa solo para la
ficha, la jerarquía de categorías y las colecciones.
- Traducir el descriptor de filtro del CMS —tipo y valor— a la consulta correspondiente, sin que
el editor conozca la sintaxis del buscador.
- Mantener en la URL el término, las facetas activas, el orden y la página.
- Consultar el índice desde el navegador con la clave de búsqueda pública, de solo lectura.
- Tolerar la ausencia del índice de sugerencias: sin él, el autocompletado se limita a productos.
Configuración
| Variable |
Uso |
NEXT_PUBLIC_ALGOLIA_APP_ID |
Aplicación de Algolia |
NEXT_PUBLIC_ALGOLIA_SEARCH_KEY · NEXT_PUBLIC_ALGOLIA_API_KEY |
Claves de búsqueda usadas por los dos clientes existentes |
NEXT_PUBLIC_ALGOLIA_PRODUCT_INDEX |
Índice de productos |
NEXT_PUBLIC_ALGOLIA_SUGGESTIONS_INDEX |
Índice de términos sugeridos |
Criterios de aceptación
| # |
Criterio |
| 1 |
Obtener sugerencias y productos mientras se escribe, en una misma capa de resultados |
| 2 |
Filtrar por categoría, precio y atributo, y recuperar el mismo resultado al compartir la URL |
| 3 |
Ordenar los resultados y paginarlos sin perder los filtros activos |
| 4 |
Resolver una cuadrícula definida en el CMS por etiqueta, categoría o colección |
| 5 |
Navegar la jerarquía de categorías y las colecciones contra Medusa |
Limitaciones conocidas
- Convivir dos clientes de Algolia con variables de entorno distintas —
lib/algolia.ts, sin
ninguna importación en el repositorio, y lib/search-client.ts, usado por el buscador—; el
primero es código muerto.
- Mantener la plantilla
algolia-store-template, que ningún módulo importa: la tienda usa
instantsearch-store-template.
- Depender de una réplica del catálogo mantenida por una integración externa al repositorio: un
desfasaje del índice se ve como catálogo desactualizado, sin señal en la tienda.
- Registrar por consola el estado del renderizado de la plantilla de tienda en producción.