Arquitectura — Compulandia Integrador¶

Visión general¶

El Integrador es el punto medio entre los proveedores y los canales de venta de Compulandia. Ingresa catálogos crudos de proveedores por API (y un consumidor Kafka para ítems enriquecidos desde SAP), los unifica en un catálogo propio con matching, precios calculados y contenido generado con IA, y sincroniza el resultado hacia las plataformas de e-commerce. Todo el trabajo pesado corre en colas Redis gestionadas por Laravel Horizon, con sincronizaciones programadas por el scheduler de Laravel.

Componentes¶

Componente	Responsabilidad	Tecnología
Aplicación web (panel)	Gestión de productos unificados, matching, pendientes, categorías	Laravel 11, Livewire 3, Vite
Scheduler	Dispara los syncs de entrada y tareas de mantenimiento (`routes/console.php`)	`php artisan schedule:work` / cron
Workers de cola	Ejecutan jobs de sync de salida, precios, imágenes, IA y Algolia	Laravel Horizon sobre Redis, colas separadas por canal
Comandos de sync de entrada	Traen catálogos de proveedores a `supplier_products` (`app:sync-cl-api`, `app:sync-fx-api`, `app:sync-ngo-api`, `app:sync-pc-manager`, `app:sync-tn-products`, `app:sync-contimarket-api`, `app:sync-xz-api`)	Comandos Artisan + servicios en `app/Services/{CL,Fastrax,NGO,PCM,TiendaNaranja,Contimarket,...}`
Jobs de sync de salida	Publican productos unificados en cada canal (`SyncToWooCommerceJob`, `SyncToMedusaJob`, `SyntToTiendaNaranjaJob`, `SyncToContimarketJob`, `SyncToUMarketJob`, `SyncToPcManagerJob`)	Jobs en `app/Jobs/` con timeout 120s y backoff exponencial (ver ADR-0003)
Consumidor Kafka	Consume ítems enriquecidos desde SAP (`app/Console/Commands/ConsumeSapEnrichedItems.php`, con dead-letter en `app/Support/Kafka/`)	`mateusjunges/laravel-kafka`
Generación de contenido IA	Nombres y descripciones de producto (`GenerateProductContentJob`, `app/Services/AIContentGeneration/`)	Google Gemini (también hay servicios `OpenIA/` y `Perplexity/`)
Búsqueda	Indexación de productos para búsqueda del panel	Laravel Scout + Algolia (`algolia:index-product-items`)
Imágenes	Hosting de imágenes de producto	Cloudflare Images (`app/Services/Cloudflare/`)

Modelos de dominio centrales¶

SupplierProduct — producto crudo tal como llega del proveedor.
ProductItem — producto unificado que se publica a los canales.
MatchProduct — vincula productos de proveedor con el producto unificado.
ProductItemView — vista de base de datos con la representación consolidada por canal. El acceso por producto se hace vía ProductItemView::forProduct() (ver ADR-0002).

Dependencias externas¶

Dependencia	Uso	¿Qué pasa si no está?
MariaDB/MySQL 10+	Base de datos principal	Caída total
Redis	Colas de Horizon y caché	No se procesan syncs ni jobs; el panel puede degradarse
APIs de proveedores (Compulandia API, Fastrax, NGO, PC Manager, Contimarket, TiendaNaranja, Xiaomizone)	Ingreso de catálogo, precio y stock	El catálogo queda desactualizado; los syncs programados fallan y reintentan
APIs de canales (WooCommerce, Medusa, TiendaNaranja, Contimarket, UMarket, PC Manager)	Publicación de productos	Los jobs de salida reintentan con backoff; los cambios no se reflejan en el canal
Medusa (consulta de precios)	`ProductPriceService` consulta precios/price lists	Fallback a precio local; si responde lento puede encolar los jobs de salida (ver runbook, falla 1)
Algolia	Índice de búsqueda del panel	La búsqueda devuelve resultados desactualizados o falla
Kafka (broker SAP)	Consumo de ítems enriquecidos de SAP	Se detiene ese flujo de enriquecimiento; el resto sigue
Google Gemini	Generación de nombres/descripciones	Falla `GenerateProductContentJob`; el resto sigue
Cloudflare Images	Hosting de imágenes	Fallan las subidas de imágenes en los syncs
Sentry	Monitoreo de errores y de tareas programadas (`sentryMonitor()`)	Se pierde visibilidad de errores; sin impacto funcional

Diagrama¶

flowchart LR
    subgraph Proveedores
        CL[Compulandia API]
        FX[Fastrax]
        OTROS[NGO / PCM / TN / Contimarket / XZ]
        SAP[SAP via Kafka]
    end

    subgraph Integrador
        SCHED[Scheduler] --> CMD[Comandos de sync de entrada]
        CMD --> SP[(supplier_products)]
        SAP -->|Kafka consumer| SP
        SP --> MATCH[Matching / evaluación] --> PI[(product_items)]
        PI --> Q[[Colas Redis / Horizon]]
    end

    subgraph Canales
        WOO[WooCommerce]
        MED[Medusa]
        TN[TiendaNaranja]
        CM[Contimarket]
        UM[UMarket]
    end

    CL -->|HTTP| CMD
    FX -->|HTTP| CMD
    OTROS -->|HTTP| CMD
    Q -->|jobs de salida HTTP| WOO & MED & TN & CM & UM
    Q -->|indexación| ALG[Algolia]

Flujo principal¶

Sincronización de un producto de proveedor hasta el canal de venta:

El scheduler ejecuta el comando de sync del proveedor (ej.: app:sync-cl-api cada hora) que trae el catálogo y actualiza supplier_products.
El producto del proveedor se vincula a un ProductItem unificado (matching automático o confirmación manual desde el panel; los no reconocidos pasan por el flujo de productos pendientes).
Se recalculan precios (CalculatePricesJob) y, si falta contenido, se genera nombre/descripción con IA (GenerateProductContentJob).
Se despachan los jobs de salida a las colas por canal; cada job arma el payload leyendo ProductItemView::forProduct() y llama a la API del canal.
ReindexInAlgoliaJob actualiza el índice de búsqueda del panel.