Saltar al contenido principal

Release — KPIs de Gestión del Almacén (REP-001)

· 5 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Se implementa REP-001 — KPI de Gestión con los cinco requerimientos de la Fase 3: un dashboard que muestra los indicadores operativos del almacén contra una meta y con tendencia mensual, en lugar de las aproximaciones que alimentaban las gráficas anteriores.


🎯 Qué se entrega​

Un nuevo módulo KPIs de Gestión en el menú lateral con cuatro indicadores calculados:

IndicadorDefiniciónMeta
Rotación de inventarioSalidas valorizadas / inventario promedio, proyectado a 365 días4x → 8x por año
Exactitud de inventarioLíneas de conteo sin diferencia / líneas contadas85 % → 98 %
Fill ratePedidos completos / pedidos evaluados75 % → 95 %
Tiempo de cicloSolicitud → último despacho, en completadas5 días → 2 días

Cada tarjeta trae su etiqueta de desempeño (En meta / Sobre la línea base / Bajo la línea base), su barra de avance desde la línea base y sus métricas de apoyo (rotación del período, días de cobertura, exactitud por cantidad, fill rate por unidades, mediana y p90 del ciclo, tiempo de despacho, cumplimiento a tiempo).


🔧 Backend​

Nuevo servicio de KPIs​

ReportesService sigue atendiendo los reportes operativos; los indicadores viven en un servicio nuevo y dedicado, KpiGestionService (src/domains/reportes/services/kpi-gestion.service.ts), con consultas SQL agregadas sobre movimientos_inventario, stock_almacen, detalle_conteo, conteos, solicitudes y detalle_solicitudes.

GET /api/reportes/kpis?fechaInicio=&fechaFin=&idAlmacen=&idOficina=

Período por defecto: año en curso hasta hoy. Resultado cacheado 60 s por combinación de filtros. Las metas viajan dentro de la respuesta, así que el frontend no duplica constantes.

Cómo se calcula el inventario promedio (lo no obvio)​

No existe histórico de stock, pero los movimientos ya lo contienen: stock_antes y stock_despues. Por cada par (producto, almacén) se toma la apertura (stock_antes del primer movimiento del período), el cierre (stock_despues del último) y el promedio es (apertura + cierre) / 2; los productos sin movimiento aportan su stock vigente. Se evita así usar el stock final como proxy del promedio, que sesga la rotación.

Cómo se fecha el cumplimiento (lo no obvio)​

solicitudes no guarda una fecha de cumplimiento. El hito se toma del último movimiento de salida asociado a los detalles (id_detalle_solicitud), que es el dato real que produce el despacho — en lugar de agregar una columna (migración que solo aplicaría hacia adelante) o de usar updated_at. Esta decisión se validó contra la base real: las solicitudes completadas sin movimiento tenían updated_at con una misma marca temporal masiva de carga, muy posterior a su fecha de solicitud, así que habría reportado ciclos de cientos de días.

Para que esa realidad no quede oculta, la respuesta informa completadasEnPeriodo y completadasSinTrazabilidad: el dashboard muestra Medibles / completadas y así se distingue «el almacén es lento» de «hay solicitudes que se cierran sin registrar su despacho».

Brecha de medición también en la exactitud​

La exactitud se calcula sobre conteos cíclicos (INV-005). Como un período puede tener ciclos programados y ninguno contado, la respuesta añade conteosEnPeriodo, y el dashboard muestra Ciclos con lectura (conteosRealizados / conteosEnPeriodo). Sin líneas contadas el indicador es null, no 100 %.

Convención de vacíos​

Un indicador sin datos suficientes es null, nunca 0: «no medido» no es «desempeño nulo». El dashboard muestra «—».

Sin migraciones​

El módulo no agrega tablas ni columnas.


🎨 Frontend​

  • Nueva página /kpis-gestion (src/pages/kpis-gestion.tsx) y entrada de menú KPIs de Gestión, justo debajo de Reportes de Almacén.
  • Dashboard (src/components/reports/kpi-dashboard.tsx): filtros de período, almacén y área; cuatro tarjetas de KPI con meta y avance; resumen operativo; cuatro gráficas de tendencia (Recharts); y tres tablas de desglose (rotación por categoría, exactitud por categoría y fill rate por área).
  • Cliente API src/api/kpis-gestion.ts y tipos en src/models/kpi-gestion.entity.ts.

🧪 Verificación​

  • Backend npx tsc --noEmit: OK · nest build: OK.
  • Backend npm test: 24 pruebas nuevas de REP-001 (una por requerimiento, más los casos de «sin datos», anualización por largo del período, derivación del cumplimiento desde movimientos y brecha de medición).
  • Ejecución real contra la base de datos: las seis consultas del dashboard se corrieron sobre ccf_almacen (sin filtros, con rango amplio y con filtros de almacén y área) sin errores y contrastadas con conteos directos de las tablas.
  • Frontend npx tsc --noEmit: OK · next lint sobre los archivos nuevos: sin warnings.
  • Wiki npm run build: OK.

📁 Archivos clave​

Backend: src/domains/reportes/services/kpi-gestion.service.ts, src/domains/reportes/interfaces/kpis-gestion.interface.ts, src/domains/reportes/dto/kpi-filtros.dto.ts, src/domains/reportes/reportes.controller.ts, src/domains/reportes/reportes.module.ts, src/domains/reportes/services/kpi-gestion.service.spec.ts.

Frontend: src/api/kpis-gestion.ts, src/models/kpi-gestion.entity.ts, src/components/reports/kpi-dashboard.tsx, src/pages/kpis-gestion.tsx, src/components/layouts/sidebar/sidebar-option.ts.


⚠️ Notas​

  • Las gráficas estadísticas previas (pestaña de gráficas del módulo de reportes, alimentadas por /api/movimientos-inventario/estadistica/*) se mantienen: siguen siendo útiles para el detalle operativo. Los KPIs de REP-001 son el cálculo formal con meta; unificar ambas fuentes es trabajo posterior.
  • La exactitud requiere conteos cíclicos (INV-005) en el período; sin ellos el indicador es «Sin datos», no 100 %.

📚 Documentación​