Saltar al contenido principal

REP-005 — Análisis de Consumo

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

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​

RFEntregable
RF-REP-005-01Patrones de consumo por área y período, con granularidad día/semana/mes
RF-REP-005-02Consulta de consumo por área, categoría y rango de fechas, paginada y exportable
RF-REP-005-03Detección de anomalías y variaciones significativas con línea base
RF-REP-005-04Tablero 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:

EndpointRF
GET /consumo/patrones005-01
GET /consumo/detalle005-02
GET /consumo/anomalias005-03
GET /consumo/dashboard005-04
GET /consumo/detalle/exportar/excel | /pdf005-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 false y next 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 026 aplicada y verificación contra la base real: el propio servicio se ejecutó contra ccf_almacen y 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​

  1. La atribución de área depende hoy del respaldo por referencia. De 77 salidas, solo 2 tienen id_detalle_solicitud; las 77 traen referencia_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 por id_detalle_solicitud, así que su muestra queda casi vacía. Vale la pena revisar el flujo de despacho para que registre el detalle.
  2. 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​