REP-005 — Análisis de Consumo
Implementación de la mejora REP-005 (Análisis de Consumo), dentro de 4.2 Analítica Avanzada: el módulo deja de mostrar solo lo que pasó y empieza a explicar quién consume qué, cómo evoluciona y cuándo se sale del patrón.
📋 Alcance
| RF | Entregable |
|---|---|
| RF-REP-005-01 | Patrones de consumo por área y período, con granularidad día/semana/mes |
| RF-REP-005-02 | Consulta de consumo por área, categoría y rango de fechas, paginada y exportable |
| RF-REP-005-03 | Detección de anomalías y variaciones significativas con línea base |
| RF-REP-005-04 | Tablero de consumo y exportación a Excel y PDF |
Una sola definición de consumo recorre los cuatro: movimientos de salida valorizados,
atribuidos al área solicitante por clave foránea
(id_detalle_solicitud → detalle_solicitudes → solicitudes → oficinas), con respaldo por
referencia_documento_origen para los movimientos legados.
🔌 API
Bajo /api/reportes/consumo, autenticados y documentados en Swagger:
| Endpoint | RF |
|---|---|
GET /consumo/patrones | 005-01 |
GET /consumo/detalle | 005-02 |
GET /consumo/anomalias | 005-03 |
GET /consumo/dashboard | 005-04 |
GET /consumo/detalle/exportar/excel | /pdf | 005-04 |
Se cachean 60 s por combinación de filtros (prefijo reportes:consumo:, que la invalidación
existente ya limpia). Período por defecto: los 12 meses calendario completos anteriores al mes en
curso.
🧠 Detección de anomalías
Z-score robusto sobre mediana y MAD (σ̂ = 1.4826 × MAD), con la línea base leave-one-out:
el período evaluado nunca participa en su propia base, así un pico no se justifica a sí mismo. Se
eligió frente a media/desviación estándar porque estas últimas quedan enmascaradas por los propios
valores atípicos que se buscan.
- Si la base no tiene dispersión (
MAD = 0) se aplica la regla de razón sobre la magnitud de la variación, de modo que una caída fuerte pese igual que un aumento fuerte. - Cada serie arranca su historia en su primer mes con datos: los meses intermedios sin consumo son ceros reales, pero una serie no hereda ceros ficticios anteriores a su existencia.
- Series con menos de 4 períodos base no se evalúan y se informan en
seriesConMuestraInsuficiente: la brecha se hace visible en lugar de silenciarse. - Guarda de volumen (
minimoUnidades, 5 por defecto) para no alertar sobre 1–2 unidades.
Cada anomalía informa valor observado, línea base, variación, z-score, método, tipo y severidad.
🖥️ Tablero
Nueva ruta /analisis-consumo (menú lateral, junto a KPIs de Gestión):
- Filtros de rango, área (oficina), clasificación, categoría y agrupación.
- Seis tarjetas de resumen, incluida la dispersión (CV) y las anomalías por severidad.
- Gráficas Recharts: serie por período, barras por área con participación y pastel por categoría.
- Tabla de productos de mayor consumo y panel de anomalías explicadas.
- Tabla de detalle consultable con buscador y paginación, más exportación a Excel y PDF.
🗄️ Base de datos
Migración 026-add-consumo-indexes.ts (aplicada): cuatro índices de apoyo (tipo+fecha+producto,
id_detalle_solicitud, referencia_documento_origen y oficina+fecha en solicitudes). Hacían falta
porque PostgreSQL no indexa automáticamente las claves foráneas y no existía ninguno orientado a
estas consultas. No se crean tablas ni columnas: el feature es de solo lectura.
✅ Verificación
- Backend
npx tsc --noEmit: EXIT 0. - Backend: 24 pruebas nuevas del servicio en verde; suite completa con 216 pruebas en verde.
- Frontend
npx tsc --noEmit --incremental falseynext lint: sin errores. - Frontend: 10 pruebas en verde (4 suites), incluidas 3 del tablero (con datos, vacío y error).
- Wiki
npm run build: OK. - Migración
026aplicada y verificación contra la base real: el propio servicio se ejecutó contraccf_almaceny los ocho contrastes de totales coincidieron con conteos directos de las tablas (unidades, movimientos, serie, desgloses por área y categoría, participaciones, tablero y consumo sin área).
Dos hallazgos de la verificación real
- La atribución de área depende hoy del respaldo por referencia. De 77 salidas, solo 2
tienen
id_detalle_solicitud; las 77 traenreferencia_documento_origen. Sin ese respaldo el análisis habría visto 2 movimientos en lugar de 77. Esto también afecta a REP-001: su tiempo de ciclo une porid_detalle_solicitud, así que su muestra queda casi vacía. Vale la pena revisar el flujo de despacho para que registre el detalle. - El plan de ejecución sigue siendo
Seq Scan, y es lo correcto: la tabla tiene 275 filas. Los índices de la migración existen para cuando el volumen crezca; a este tamaño no aportan una mejora medible.
El guardián de «muestra insuficiente» se dispara con datos reales: 22 series evaluadas y 4 informadas como sin historia suficiente.
🔗 Referencias
- Diseño y decisiones: REP-005: Análisis de Consumo
- Manual de usuario: Análisis de Consumo
- Patrón heredado: REP-001: KPIs de Gestión
- Requerimientos: Mejoras propuestas al módulo de almacén
