fix(inventory-opt): inventory optimization: pagination, queries, filters for 10k+ products

work/artifacts/INVENTORY-OPT/architect.md

@@ -0,0 +1,63 @@
+# 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