mercadodevida/work/artifacts/INVENTORY-OPT/architect.md

Arquitectura — INVENTORY-OPT

Problema

La pantalla admin de inventario no escala a 10k+ productos porque hoy:

• pide productsApi.list(limit=100)
• por cada producto hace getVariants
• por cada fila hace getAvailability
• por cada fila hace getVariantPrice

Eso introduce N+1 HTTP + N+1 SQL y además no tiene paginación real del inventario.

Diseño propuesto

1) Nuevo endpoint backend optimizado

Crear GET /inventory/admin/overview en el módulo inventory.

Query params:

• q
• filter
• limit
• offset

Respuesta:

• items[] con fila ya enriquecida (producto + variante + stock + precio + caducidad)
• total
• stats con conteos globales (inStock, lowStock, outOfStock)

2) Query única paginada

La query leerá directamente:

• catalog_products
• catalog_product_variants
• inventory_stock
• pricing_variant_prices

Con esto evitamos las múltiples rondas actuales desde el admin.

3) Filtros server-side

Mover al backend los filtros ya visibles en UI:

• all
• in_stock
• low_stock
• out_of_stock
• expiring
• low_margin

4) UI admin

Actualizar project/apps/admin/src/app/(dashboard)/inventory/page.tsx para:

• consumir el nuevo endpoint
• usar paginación real
• mantener búsqueda debounced
• mantener filtros existentes
• evitar llamadas por fila

No entra

• Refactor de módulos no relacionados
• Reescritura de pricing o inventory core
• Cambios en TPV/storefront

Validación

• typecheck backend/admin
• build backend/admin
• verify.sh
• prueba funcional manual de búsqueda/filtros/paginación