RF-000 — Plataforma base de comercio (Medusa v2 stock)¶

Alcance. Documentar únicamente las capacidades provistas por Medusa v2.15.5 sin desarrollo propio. Las extensiones construidas sobre esta base se documentan en Inventario del desarrollo custom y en los requisitos siguientes de esta serie.

Requisito¶

Disponer de una plataforma de comercio headless que resuelva sin desarrollo propio la gestión de catálogo, precios, inventario, carrito, pedido, pago, envío, promociones, impuestos y clientes; exponer dichas capacidades como API HTTP versionada para el storefront y para integradores; y proveer una interfaz de administración para la operación comercial.

Solución adoptada: adoptar Medusa v2.15.5 sobre Node 20, PostgreSQL 15 y Redis 7, desplegado como proceso único (workerMode: shared) que sirve API de tienda, API de administración, dashboard de admin y procesamiento asíncrono.

Dominios cubiertos¶

flowchart LR
    subgraph CAT[Catálogo]
        P[Product]
        PR[Pricing]
        INV[Inventory]
        SL[Stock Location]
        SC[Sales Channel]
    end
    subgraph VEN[Venta]
        C[Cart]
        O[Order]
        PROM[Promotion]
        TAX[Tax]
    end
    subgraph OPS[Operación]
        PAY[Payment]
        FUL[Fulfillment]
    end
    subgraph IDE[Identidad]
        CUS[Customer]
        AUTH[Auth]
        USR[User]
        AK[API Key]
    end
    subgraph CFG[Configuración]
        REG[Region]
        ST[Store]
        CUR[Currency]
    end

    C --> O --> PAY
    O --> FUL
    P --> C
    PR --> C
    INV --> FUL
    PROM --> C
    TAX --> C
    CUS --> C
    REG --> C

Módulos de comercio¶

Módulo	Capacidad cubierta de fábrica
Product	Productos, variantes, opciones, colecciones, categorías, tipos, tags e imágenes
Pricing	Precios por moneda y región, reglas de precio, listas de precios y precios por cantidad
Inventory	Ítems de inventario, niveles por ubicación, reservas y control de stock
Stock Location	Ubicaciones físicas y su asociación a canales de venta y perfiles de envío
Sales Channel	Segmentación de catálogo y stock por canal
Cart	Carrito, líneas, cálculo de totales, direcciones, envío y promociones aplicadas
Order	Pedido, edición de pedido, devoluciones, cambios, reclamos y borradores
Payment	Sesiones y colecciones de pago, autorización, captura y reembolso vía providers
Fulfillment	Perfiles de envío, zonas de servicio, opciones de envío, cálculo de tarifa y preparación
Promotion	Promociones y campañas por reglas, con descuentos de importe fijo o porcentual
Tax	Regiones fiscales, tasas y cálculo de impuesto sobre el carrito y el pedido
Customer	Clientes, grupos de clientes y libreta de direcciones
Auth	Registro, autenticación y emisión de tokens para clientes y usuarios de admin
User	Usuarios de administración e invitaciones
API Key	Claves publicables para el storefront y claves secretas para integradores
Region / Store / Currency	Regiones, países, monedas y configuración de la tienda
Notification	Despacho de notificaciones por canal vía providers
File	Carga y resolución de archivos vía providers

Módulos de infraestructura¶

Módulo	Implementación configurada
Cache	`cache-redis`
Event Bus	`event-bus-redis`
Workflow Engine	`workflow-engine-redis`
Locking	`locking-redis` (default)

Providers stock habilitados¶

Tipo	Provider	Origen
Auth	`auth-emailpass`	Stock
Auth	`auth-google`	Stock, configurado con credenciales propias
Fulfillment	`fulfillment-manual`	Stock

Los providers de pago, el provider de fulfillment calculado y el provider de notificación en uso son desarrollo propio y quedan fuera de este requisito.

Superficies expuestas¶

Superficie	Prefijo	Autenticación	Consumidor
API de tienda	`/store/*`	Clave publicable + sesión o JWT de cliente	Storefront, navegador
API de administración	`/admin/*`	Sesión o JWT de usuario, o clave secreta	Dashboard, integradores
Autenticación	`/auth/*`	Credenciales o proveedor federado	Storefront, dashboard
Dashboard de admin	`/app`	Sesión de usuario	Equipo comercial

Flujo base de compra¶

sequenceDiagram
    participant SF as Storefront
    participant API as API de tienda
    participant WF as Motor de workflows
    participant PP as Payment provider
    SF->>API: Crear carrito en región y canal
    API-->>SF: Carrito con precios y stock resueltos
    SF->>API: Agregar líneas, dirección y opción de envío
    API-->>SF: Totales con impuesto y promociones
    SF->>API: Iniciar sesión de pago
    API->>PP: Autorizar
    PP-->>API: Estado de autorización
    SF->>API: Completar carrito
    API->>WF: Ejecutar workflow de creación de pedido
    WF-->>API: Pedido creado y reserva de inventario
    API-->>SF: Pedido

Puntos de extensión provistos¶

Punto	Uso previsto
Módulos propios	Encapsular dominio nuevo o implementar providers de pago, envío, notificación y archivo
Rutas API	Endpoints propios bajo `/store`, `/admin` o rutas libres, con ruteo por archivos
Workflows y hooks	Orquestación transaccional con compensación e injerto sobre workflows nativos
Suscriptores	Reacción asíncrona a eventos de dominio publicados en el event bus
Jobs programados	Tareas recurrentes ejecutadas por el worker
Widgets y páginas de admin	Extensión del dashboard con React y el Admin SDK
Module links	Asociación entre módulos sin acoplar sus esquemas

Fuera del alcance stock¶

Capacidades requeridas por el negocio que Medusa no cubre de fábrica y que motivan el desarrollo propio documentado en los requisitos siguientes:

Medios de pago locales y su confirmación asincrónica — RF-001, RF-003, RF-004.
Descuento condicionado al medio de pago — RF-002.
Cálculo de flete por tipo de bulto, geozona y categoría de producto — RF-005, RF-006.
Notificación transaccional por correo con plantillas propias en castellano — RF-007.
Pantallas de administración de listas de precios, geozonas y configuración de envíos — RF-006, RF-008.
Búsqueda y facetas de catálogo (resueltas fuera del backend, contra Algolia).
Gestión de contenido editorial (resuelta en el CMS).

Criterios de aceptación¶

#	Criterio
1	Publicar y consultar catálogo segmentado por canal de venta y región desde `/store/*`
2	Resolver precio e impuesto de una variante según región y lista de precios vigente
3	Completar un carrito hasta pedido con reserva de inventario, sin código propio de orquestación
4	Autenticar clientes por email y contraseña y por proveedor federado
5	Operar catálogo, pedidos, clientes y promociones desde el dashboard sin acceso a base de datos
6	Registrar providers propios de pago, envío y notificación sin modificar el núcleo