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

work/artifacts/INVENTORY-OPT/implementer.md

@@ -0,0 +1,79 @@
+# Implementer evidence — INVENTORY-OPT
+
+## Cambios realizados
+
+### 1) Nuevo endpoint backend optimizado
+Añadí `GET /inventory/admin/overview` en:
+- `project/src/modules/inventory/api/inventory.routes.ts`
+
+El endpoint:
+- pagina server-side (`limit`, `offset`)
+- busca por `nombre`, `SKU` o `EAN`
+- aplica filtros server-side:
+  - `all`
+  - `in_stock`
+  - `low_stock`
+  - `out_of_stock`
+  - `expiring`
+  - `low_margin`
+- devuelve filas ya enriquecidas con:
+  - producto
+  - variante
+  - stock
+  - precio
+  - margen
+  - caducidad
+- devuelve además `stats` agregados para cards del dashboard de inventario
+
+### 2) Eliminación del N+1 en admin inventory
+Antes la página hacía:
+- `productsApi.list(limit=100)`
+- `getVariants()` por producto
+- `getAvailability()` por fila
+- `getVariantPrice()` por fila
+
+Ahora la página consume una única llamada paginada:
+- `inventoryApi.listOverview(...)`
+
+### 3) UI admin paginada
+Actualicé:
+- `project/apps/admin/src/app/(dashboard)/inventory/page.tsx`
+- `project/apps/admin/src/lib/api-client.ts`
+- `project/apps/admin/src/types/index.ts`
+
+La página ahora:
+- usa búsqueda debounced server-side
+- usa filtros server-side
+- muestra paginación real
+- sigue permitiendo editar inline:
+  - stock
+  - EAN
+  - caducidad
+
+### 4) Test de integración real PostgreSQL
+Añadí:
+- `project/src/app/tests/inventory-admin-overview.itest.ts`
+
+Valida:
+- paginación
+- búsqueda por EAN
+- filtro `low_margin`
+- filtro `expiring`
+- stats agregados
+
+## Validación
+- `cd project && npm run typecheck` ✅
+- `cd project && npm run build` ✅
+- `cd project/apps/admin && npm run build` ✅
+- `cd project && TEST_DATABASE_URL=postgres://mdv:mdv_dev_only@localhost:5432/mercadodevida_test npx vitest run src/app/tests/inventory-admin-overview.itest.ts --no-file-parallelism` ✅
+- `./scripts/verify.sh` ✅
+- `git diff --check` ✅
+
+## Decisiones técnicas
+- No introduje un módulo nuevo: reutilicé `inventory.routes.ts` porque el problema principal era de lectura agregada para admin.
+- El inventario se optimiza a nivel de query y tráfico HTTP, que era el cuello de botella real para 10k+ productos.
+- Mantuve edición inline en la UI para no romper el flujo actual del admin.
+
+## Deuda / siguiente paso
+- Si el volumen sigue creciendo, el siguiente paso natural sería añadir índices específicos para búsquedas admin por nombre/SKU/EAN o una vista materializada/consulta especializada.
+- La build del admin sigue mostrando warnings preexistentes de Turbopack sobre acceso dinámico a ficheros en uploads; no están relacionados con INVENTORY-OPT.