Release — KPIs de Gestión del Almacén (REP-001)
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:
| Indicador | Definición | Meta |
|---|---|---|
| Rotación de inventario | Salidas valorizadas / inventario promedio, proyectado a 365 días | 4x → 8x por año |
| Exactitud de inventario | Líneas de conteo sin diferencia / líneas contadas | 85 % → 98 % |
| Fill rate | Pedidos completos / pedidos evaluados | 75 % → 95 % |
| Tiempo de ciclo | Solicitud → último despacho, en completadas | 5 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.tsy tipos ensrc/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 lintsobre 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
- Documento funcional: REP-001: KPIs de Gestión del Almacén.
- Manual de usuario: KPIs de Gestión.
- Requerimientos: Mejoras propuestas al módulo de almacén.
