RF-000 — Plataforma base de tienda (Medusa Next.js Starter stock)¶

Alcance. Documentar únicamente las capacidades provistas por el starter oficial de Medusa para Next.js, del que deriva el repositorio, sin desarrollo propio. Lo construido encima se documenta en los requisitos siguientes y en el Inventario de funcionalidades.

Requisito¶

Disponer de una tienda pública que resuelva sin desarrollo propio el recorrido completo de compra —catálogo, ficha de producto, carrito, checkout por pasos, cuenta de cliente e historial de pedidos— consumiendo la API de tienda de Medusa como única fuente de datos de negocio, sin persistencia propia; y resolver la región del visitante a partir de la URL.

Solución adoptada: partir del starter oficial medusajs/nextjs-starter-medusa sobre Next.js 15 con App Router y React Server Components, Tailwind y la biblioteca de componentes de Medusa, desplegado como contenedor Docker.

Origen y divergencia¶


Upstream	`medusajs/nextjs-starter-medusa`
Commit base	`1277359` — 19/09/2025; `src/` idéntico byte a byte al commit inicial del repositorio
Divergencia	154 archivos · +12.562 / −1.324 líneas en `src/`
Estado del upstream	Deprecado desde abril de 2026; su reemplazo (`dtc-starter`) es un monorepo de arquitectura distinta

Ver Deuda con el upstream: no hay cambios pendientes de incorporar desde el origen.

Arquitectura funcional¶

flowchart LR
    N([Navegador]) --> MW[middleware<br/>resolución de región]
    MW --> RSC[Server Components<br/>+ Server Actions]
    RSC --> SDK[Capa de datos server-only<br/>@medusajs/js-sdk]
    SDK --> MED[(API de tienda · Medusa)]
    RSC --> CACHE[Caché de Next<br/>tags por usuario]
    N -. cookies HTTP-only .-> RSC

Capacidades del starter¶

Área	Alcance de fábrica
Enrutamiento por región	Middleware que resuelve país → región contra `/store/regions`, con mapa cacheado una hora y redirección a `/{countryCode}`
Catálogo	Listado de tienda, categorías anidadas, colecciones, ficha de producto con galería, variantes, pestañas y relacionados
Carrito	Alta, modificación y baja de líneas; persistencia por cookie `_medusa_cart_id`; códigos de promoción; gift cards; traspaso del carrito al iniciar sesión; recálculo por cambio de región
Checkout	Flujo por pasos con `?step=` en la URL: dirección, entrega, pago y revisión; direcciones de envío y facturación separadas; reutilización de direcciones guardadas
Pagos	Integración con los proveedores del backend; el starter incluye Stripe y PayPal
Cuenta de cliente	Registro e inicio de sesión con JWT en cookie `_medusa_jwt`; perfil; libreta de direcciones; historial y detalle de pedidos; rutas paralelas de panel y de acceso
Post-venta	Confirmación de pedido y transferencia de pedido entre cuentas por token
Rendimiento	Server Components por defecto, capa de datos `server-only`, caché con tags por usuario (`_medusa_cache_id`) revalidados tras cada mutación, esqueletos de carga
Publicación	Sitemap y despliegue en contenedor

Reglas heredadas de la plataforma¶

No persistir estado de negocio: todo dato de catálogo, carrito, pedido y cliente vive en Medusa.
Resolver la sesión con cookies HTTP-only, sin exponer tokens al código de navegador.
Ejecutar toda llamada autenticada desde el servidor mediante Server Actions.
Segmentar la caché por usuario, de modo que la revalidación de un carrito no afecte a otro.

Fuera del alcance stock¶

Capacidades requeridas por el negocio que el starter no cubre y que motivan el desarrollo propio documentado en los requisitos siguientes:

Contenido editorial administrado fuera del código — RF-001.
Búsqueda y navegación filtrada del catálogo — RF-002.
Enlace por variante, precio especial y stock por sucursal — RF-003.
Geografía de Paraguay en el checkout — RF-004.
Retiro en sucursal y promesa de entrega — RF-005.
Medios de pago locales — RF-006.
Financiación en cuotas y solicitud de crédito — RF-007.
Inicio de sesión federado — RF-008.
Canal de contacto directo — RF-009.

Criterios de aceptación¶

#	Criterio
1	Resolver la región desde el país del visitante y redirigir a la URL con su código
2	Recorrer catálogo, carrito y checkout hasta confirmar un pedido contra la API de Medusa
3	Registrar, autenticar y operar la cuenta del cliente con la sesión en cookie HTTP-only
4	Reflejar en la interfaz cada mutación mediante revalidación por tag, sin recarga completa
5	Operar sin base de datos propia

Limitaciones conocidas¶

Conservar código inactivo de Stripe y PayPal heredado del starter, dos versiones mayores atrás.
Depender de React 19 RC, cuya salida está pendiente de un upgrade propio de dependencias.