REP-006 — Proyección de Necesidades
Implementación de la mejora REP-006 (Proyección de Necesidades), dentro de 4.2 Analítica Avanzada: el sistema proyecta las necesidades futuras de productos —no solo la demanda—, permite consultarlas por producto, área y período, mide la precisión de sus propias proyecciones y puede usar la proyección como insumo del punto de reorden.
📋 Alcance
| RF | Entregable |
|---|---|
| RF-REP-006-01 | Proyección de necesidades por tendencia: tendencia lineal amortiguada, modelo=auto por backtesting y necesidades netas frente al stock |
| RF-REP-006-02 | Consulta por producto, área y período: dimensión área y consulta agregada paginada |
| RF-REP-006-03 | Precisión: backtesting walk-forward con MAE, RMSE, sesgo, MASE y MAPE |
| RF-REP-006-04 | Insumo del punto de reorden: origen de demanda activable por producto y almacén |
Se extiende INV-009 (Demanda Predictiva) en lugar de crear un segundo motor: dos motores de pronóstico en el mismo sistema terminan divergiendo, y el requerimiento pide usar las proyecciones, no tener dos verdades.
🧠 Proyección (RF-006-01)
- Tendencia lineal amortiguada (
tendencia_lineal) con φ configurable (0.8 por defecto): el nivel parte del final de la serie y la tendencia acumula cada vez menos, para que una recta empinada no se dispare en horizontes largos. - Guardián de tendencia: la recta solo se aplica si es demostrable —al menos 6 períodos con consumo, pendiente distinta de cero y R² ≥ 0.3—. Cuando no lo es, el pronóstico cae a media móvil y lo declara. Se prefiere un pronóstico plano y honesto a una recta inventada sobre tres puntos.
modelo=auto: evalúa los tres modelos por backtesting y aplica el de menor MAE, devolviendo la comparación completa.- Período en curso: se excluye del entrenamiento por estar incompleto (entraría como un mes
parcial y hundiría el promedio) y se informa aparte en
periodoEnCurso. - Necesidades, no solo demanda:
demandaProyectada = unidades esperadas del período
necesidadNeta(h) = max(0, Σ demandaProyectada hasta h − stockDisponible)
La necesidad es acumulada y el stock de seguridad no entra aquí: es un parámetro de la política de reposición (INV-006), y mezclarlos haría que un cambio de política alterara la proyección.
🔌 API
| Endpoint | RF |
|---|---|
GET /api/reorden/pronostico (ampliado) | 006-01 |
GET /api/reorden/pronostico/proyecciones | 006-02 |
GET /api/reorden/pronostico/precision | 006-03 |
PUT /api/reorden/metodo-demanda | 006-04 |
Todos son retrocompatibles: el alcance gana idOficina, idAlmacen pasa a ser opcional (sin
él se consolidan las bodegas) y los campos existentes se conservan.
📏 Precisión (RF-006-03)
Backtesting con origen móvil (walk-forward) a un paso: para cada uno de los últimos k períodos se entrena solo con lo anterior y se pronostica el siguiente. Evaluar sobre el mismo tramo con el que se entrenó reportaría una precisión ficticia.
| Métrica | Para qué |
|---|---|
mae | Error absoluto medio, en unidades (métrica de selección) |
rmse | Penaliza los errores grandes |
sesgo | Sesgo medio con signo: detecta sobre/sub-pronóstico sistemático |
mase | Error escalado contra el pronóstico ingenuo: robusto con ceros |
mape | Solo sobre períodos con consumo real > 0: con demanda intermitente dividir por cero lo vuelve inútil |
muestra y periodosConConsumo viajan siempre. Con menos de 4 pronósticos evaluables no se
reporta precisión: confiable: false, métricas en null y el motivo explicado.
🔁 Insumo del punto de reorden (RF-006-04)
puntos_reorden gana metodo_demanda (promedio_historico | proyeccion) y
mensaje_confiabilidad, con valor por defecto promedio_historico: si nadie la activa, el
punto de reorden se calcula exactamente como en INV-006.
demandaDiariaProyectada = unidadesProyectadasDelPeríodo / díasDelPeríodo
demandaLeadTime = demandaDiariaProyectada × leadTimeDias
puntoReorden = ceil(demandaLeadTime + stockSeguridad)
El prorrateo por día permite cruzar un lead time en días con una proyección mensual sin inventar unidades. Si la proyección no es confiable —o falla— se usa el promedio histórico y el motivo queda registrado con el punto: degradar es correcto, recalcular en silencio sobre un pronóstico dudoso no lo sería. El ajuste manual sigue prevaleciendo y el cálculo nunca se rompe por el pronóstico.
Las sugerencias de reposición exponen origenDemanda y mensajeConfiabilidad.
🗄️ Base de datos
Migración 027-add-metodo-demanda-punto-reorden.ts: dos columnas nuevas (con su CHECK) sobre
puntos_reorden. Idempotente y reversible. No se crean tablas.
✅ Verificación
Ver §8 del diseño y decisiones para el detalle.
- Backend
npx tsc --noEmit: EXIT 0. - Backend: 44 pruebas nuevas —19 de la matemática de los modelos, 18 de cableado (área, almacén
opcional,
auto, respaldo de tendencia, necesidades, período en curso, precisión y consulta agregada) y 7 de la integración con el punto de reorden— sobre 285 pruebas en verde y 0 fallos en la suite completa. - Las 24 pruebas de REP-005 siguen en verde tras extraer el consumo canónico compartido. También se
reparó el spec de
solicitudes(INV-002 Fase 3), que fallaba por inyección y no por su lógica. - Frontend
npx tsc --noEmit --incremental falseynext lint: sin errores; 13 pruebas en verde (5 suites), con 3 nuevas del panel de precisión y la tabla de proyección. - Migración
027aplicada y comprobada: 215 puntos de reorden, los 215 enpromedio_historicoy 0 en proyección — ninguna alerta de compra cambió de comportamiento. - Verificación contra la base real (solo lectura): 9/9 contrastes OK ejecutando el propio
servicio contra
ccf_almacen.
🔗 Referencias
- Diseño y decisiones: REP-006: Proyección de Necesidades
- Motor que se extiende: INV-009: Demanda Predictiva
- Reposición que se alimenta: INV-006: Punto de Reorden
- Consumo compartido: REP-005: Análisis de Consumo
