erp-construccion/docs/02-definicion-modulos/MAI-006-reportes-analytics/historias-usuario/US-BI-005-predicciones-ml.md

542 lines
24 KiB
Markdown

# US-BI-005: Prediccion de Costos y Cronogramas con ML
**Epica:** MAI-006 - Reportes y Business Intelligence
**Sprint:** 21
**Story Points:** 8
**Prioridad:** Media-Alta
**Asignado a:** Backend (Data Science) + Frontend
---
## Historia de Usuario
**Como** Director de Proyecto
**Quiero** ver predicciones de costos finales y fechas de termino basadas en tendencias actuales
**Para** tomar acciones correctivas tempranas y evitar sobrecostos o retrasos
---
## Criterios de Aceptacion
### 1. Prediccion de Costo Final
- [ ] Veo una prediccion del costo final del proyecto basada en:
- Tendencia historica de costos
- % de avance actual
- Velocidad de gasto (burn rate)
- Costos comprometidos pendientes
- Estacionalidad (si aplica)
- [ ] La prediccion se muestra con:
- Costo final estimado ($)
- Variacion vs presupuesto (%, $)
- Rango de confianza (min - max)
- % de confianza de la prediccion
- [ ] La prediccion se actualiza semanalmente automaticamente
### 2. Prediccion de Fecha de Termino
- [ ] Veo una prediccion de la fecha de terminacion basada en:
- Tendencia de avance fisico
- Velocidad actual de ejecucion
- Dias habiles vs no habiles
- Hitos criticos pendientes
- Historial de reprogramaciones
- [ ] La prediccion muestra:
- Fecha estimada de termino
- Dias de adelanto/atraso vs planeado
- Rango de fechas (earliest - latest)
- % de confianza de la prediccion
- [ ] Se considera calendario de dias festivos y clima
### 3. Tres Escenarios de Prediccion
- [ ] Veo predicciones para 3 escenarios:
- **Optimista:** Mejor caso posible (90% confianza)
- **Esperado:** Escenario mas probable (50% confianza)
- **Pesimista:** Peor caso razonable (10% confianza)
- [ ] Cada escenario muestra:
- Costo final estimado
- Fecha de termino estimada
- Factores que lo influencian
- Probabilidad de ocurrencia
- [ ] Los escenarios se presentan visualmente con graficas
### 4. Factores de Riesgo Identificados
- [ ] Veo una lista de factores de riesgo detectados automaticamente:
- **Riesgo Alto:** Partidas con sobrecosto >15%
- **Riesgo Medio:** Actividades en ruta critica atrasadas
- **Riesgo Bajo:** Desviaciones menores detectadas
- [ ] Cada factor muestra:
- Nombre del riesgo
- Nivel de severidad (Alto/Medio/Bajo)
- Impacto estimado en costo ($)
- Impacto estimado en tiempo (dias)
- Probabilidad de ocurrencia (%)
- Accion recomendada
- [ ] Puedo marcar riesgos como "En atencion" o "Mitigado"
### 5. Analisis de Tendencias
- [ ] Veo graficas de tendencias mostrando:
- **Burn Rate Chart:** Velocidad de gasto vs planeado
- **Progress Trend:** Velocidad de avance vs planeado
- **Cost Performance Index (CPI):** Eficiencia de costos en el tiempo
- **Schedule Performance Index (SPI):** Eficiencia de tiempo
- [ ] Las tendencias muestran ultimos 3, 6, 12 meses
- [ ] Puedo comparar tendencia actual vs proyectos similares
### 6. Proyeccion de Flujo de Efectivo
- [ ] Veo una proyeccion del flujo de efectivo futuro:
- Egresos estimados por mes
- Ingresos estimados por facturacion
- Saldo mensual proyectado
- Momento de maxima necesidad de efectivo
- [ ] La proyeccion considera:
- Programacion de obra pendiente
- Estimaciones por aprobar
- Pagos a proveedores comprometidos
- Calendario de facturacion al cliente
- [ ] Puedo exportar proyeccion a Excel para analisis financiero
### 7. Comparacion con Proyectos Similares
- [ ] Veo como se compara mi proyecto con proyectos similares historicos:
- Proyectos del mismo tipo (vertical/horizontal)
- Rango de presupuesto similar
- Misma region geografica
- [ ] La comparacion muestra:
- Desviacion promedio de costos en proyectos similares
- Tiempo promedio de ejecucion
- Factores de exito comunes
- Lecciones aprendidas
- [ ] Uso de Machine Learning para encontrar proyectos mas similares
### 8. Alertas Predictivas
- [ ] Recibo alertas automaticas cuando:
- La prediccion de costo final excede +10% del presupuesto
- La fecha estimada de termino se retrasa >15 dias
- Un nuevo riesgo alto es detectado
- La tendencia cambia significativamente (>5% en una semana)
- [ ] Las alertas se envian por:
- Notificacion en sistema
- Email al Director de Proyecto
- Dashboard de alertas
- [ ] Puedo configurar umbrales de alertas personalizados
### 9. Explicabilidad del Modelo
- [ ] Puedo ver que factores influyen mas en la prediccion:
- Peso de cada variable (% de influencia)
- Graficas de importancia de caracteristicas
- Explicacion en lenguaje natural
- [ ] Ejemplo:
```
La prediccion de costo final esta influenciada principalmente por:
1. Tendencia de sobrecosto en Estructura (40% de peso)
2. Velocidad de gasto actual (30% de peso)
3. Estacionalidad de precios (20% de peso)
4. Otros factores (10% de peso)
```
- [ ] Puedo ajustar manualmente supuestos del modelo
### 10. Historial de Predicciones
- [ ] Veo el historial de predicciones pasadas:
- Prediccion hecha hace 1, 2, 3 meses
- Como ha evolucionado la prediccion
- Precision de predicciones anteriores
- [ ] Puedo comparar:
- Prediccion inicial vs prediccion actual
- Prediccion vs realidad (cuando el proyecto termina)
- [ ] El modelo aprende de errores para mejorar predicciones futuras
---
## Mockup / Wireframe
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 🔮 Predicciones y Analisis Predictivo - Proyecto: Los Pinos │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ Resumen de Predicciones ────────────────────────────────────────────┐ │
│ │ │ │
│ │ Avance Actual: 78% | Presupuesto Original: $45.2M | Plazo: 350d │ │
│ │ Ultima actualizacion: 18/11/2025 06:00 AM (proxima en 7 dias) │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Tres Escenarios de Prediccion ──────────────────────────────────────────┐│
│ │ ││
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ││
│ │ │ 😊 OPTIMISTA │ │ 😐 ESPERADO │ │ 😟 PESIMISTA │ ││
│ │ │ Confianza: 90% │ │ Confianza: 50% │ │ Confianza: 10% │ ││
│ │ │ │ │ │ │ │ ││
│ │ │ Costo Final: │ │ Costo Final: │ │ Costo Final: │ ││
│ │ │ $46.8M │ │ $48.3M │ │ $50.1M │ ││
│ │ │ 🟢 +3.5% │ │ 🟡 +6.9% │ │ 🔴 +10.8% │ ││
│ │ │ │ │ │ │ │ ││
│ │ │ Fecha Termino: │ │ Fecha Termino: │ │ Fecha Termino: │ ││
│ │ │ 20/11/2025 │ │ 05/12/2025 │ │ 22/12/2025 │ ││
│ │ │ 🟢 -11 dias │ │ 🟡 +4 dias │ │ 🔴 +21 dias │ ││
│ │ │ │ │ │ │ │ ││
│ │ │ Factores: │ │ Factores: │ │ Factores: │ ││
│ │ │ • Eficiencia MO │ │ • Tendencia │ │ • Lluvias │ ││
│ │ │ • Negociacion │ │ actual │ │ • Retrabajos │ ││
│ │ │ │ │ • Estacionalidad│ │ • Sobrecostos │ ││
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ││
│ └───────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─ Proyeccion de Costos ────────────┬─ Proyeccion de Cronograma ──────────┐ │
│ │ │ │ │
│ │ $M │ % │ │
│ │ 50│ ┌──┐ │ 100│ ┌──── │ │
│ │ 45│ ┌────┘ │ │ 80│ ┌───╯ │ │
│ │ 40│ ┌───╯ │ │ 60│ ┌──╯ │ │
│ │ 35│ ┌───╯ Rango de │ │ 40│ ┌──╯ │ │
│ │ 30│ ┌───╯ Confianza │ │ 20│ ┌──╯ │ │
│ │ 25│───╯ │ │ 0└──────────────────────── │ │
│ │ 0└──────────────────────── │ │ E F M A M J J A S O N D │ │
│ │ E F M A M J J A S O N D │ │ │ │
│ │ │ │ ─── Planeado │ │
│ │ ─── Real │ │ ─── Real │ │
│ │ ─── Presupuesto │ │ ─── Proyeccion │ │
│ │ ─── Proyeccion Esperada │ │ ▓▓▓ Rango confianza │ │
│ │ ▓▓▓ Rango confianza 80% │ │ │ │
│ └────────────────────────────────┴──────────────────────────────────────────┘ │
│ │
│ ┌─ Factores de Riesgo Detectados ──────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │Riesgo │Sev.│Impacto $│Impacto T│Prob.│Accion │Est.│ │ │
│ │ ├─────────────────────────────────────────────────────────────────────┤ │ │
│ │ │Sobrecosto Acabados │🔴 A│ +$850K │ +12d │ 75% │[Mitigar] │⚠️ │ │ │
│ │ │Retraso Instalaciones│🟡 M│ +$320K │ +8d │ 45% │[Revisar] │⏳ │ │ │
│ │ │Clima epoca lluvias │🟡 M│ +$180K │ +5d │ 60% │[Monitor] │👁️ │ │ │
│ │ │Escasez de MO │🟢 B│ +$95K │ +2d │ 25% │[Prevenir]│✅ │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Impacto Total Estimado: +$1.45M (+3.2%) | +27 dias │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Indicadores de Desempeno ────────────────────────────────────────────┐ │
│ │ │ │
│ │ CPI (Cost Performance Index): 0.96 🟡 Ligeramente sobre presup. │ │
│ │ SPI (Schedule Performance Index): 1.03 🟢 Adelante del programa │ │
│ │ Burn Rate: $2.1M/mes 🟡 +5% vs planeado │ │
│ │ Velocidad de Avance: 8.7% /mes 🟢 Normal │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Explicacion del Modelo ──────────────────────────────────────────────┐ │
│ │ │ │
│ │ La prediccion de costo final esta basada en: │ │
│ │ │ │
│ │ 1. Tendencia de sobrecosto en Acabados ████████████ 40% │ │
│ │ 2. Velocidad de gasto actual (burn rate) ████████ 30% │ │
│ │ 3. Estacionalidad de precios (Q4) ████ 20% │ │
│ │ 4. Riesgos climaticos identificados ██ 10% │ │
│ │ │ │
│ │ Precision historica del modelo: 87% (error promedio: ±2.3%) │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ [📊 Ver Detalles Tecnicos] [📈 Comparar con Similares] [⚙️ Ajustar Modelo] │
│ [📥 Exportar Proyecciones] [🔔 Configurar Alertas] [📚 Historial] │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## Flujo de Trabajo
```
1. SISTEMA EJECUTA PREDICCION AUTOMATICA (CADA SEMANA)
Scheduler ejecuta job: "Actualizar Predicciones"
Para cada proyecto activo:
- Extrae datos historicos (ultimos 6 meses)
- Calcula tendencias de costo y tiempo
- Identifica factores de riesgo
- Ejecuta modelo de ML
Predicciones se almacenan en BD
Si hay cambios significativos → Genera alertas
2. DIRECTOR ACCEDE A PREDICCIONES
Dashboard de Proyecto → Tab "Predicciones"
Sistema muestra ultima prediccion (7 dias antiguedad)
Usuario ve 3 escenarios y factores de riesgo
3. ANALIZAR ESCENARIO PESIMISTA
Usuario hace clic en "Pesimista"
Sistema despliega detalles:
- Costo final: $50.1M (+10.8%)
- Fecha termino: 22/12/2025 (+21 dias)
Muestra factores que llevan a este escenario:
- Lluvias en Nov-Dic: +8 dias
- Retrabajos en Acabados: +$1.2M
- Incremento precios materiales: +$0.5M
4. REVISAR FACTORES DE RIESGO
Usuario revisa tabla de riesgos
Identifica riesgo critico: "Sobrecosto Acabados"
- Probabilidad: 75%
- Impacto: +$850K
Usuario hace clic en [Mitigar]
Sistema abre panel de acciones sugeridas:
- Renegociar contrato con subcontratista
- Revisar especificaciones
- Buscar proveedores alternativos
5. COMPARAR CON PROYECTOS SIMILARES
Usuario hace clic en [Comparar con Similares]
Sistema usa ML para encontrar 5 proyectos mas similares
Muestra comparacion:
- Los Pinos: +6.9% desviacion proyectada
- Promedio similar: +4.2% desviacion real
- Insight: "Proyecto esta 2.7% por encima del promedio"
6. AJUSTAR MODELO MANUALMENTE
Usuario hace clic en [Ajustar Modelo]
Panel de supuestos editables:
- Velocidad de avance futura: [8.5% /mes]
- Incremento de precios esperado: [2.5%]
- Probabilidad de lluvias: [60%]
Usuario ajusta velocidad a 9.0% (mas optimista)
Sistema recalcula prediccion en tiempo real
Nueva prediccion esperada: $47.8M (+5.8%)
7. EXPORTAR PARA JUNTA
Usuario hace clic en [Exportar Proyecciones]
Sistema genera PDF/Excel con:
- Resumen ejecutivo de 3 escenarios
- Graficas de proyeccion
- Tabla de riesgos
- Explicacion del modelo
- Recomendaciones de acciones
Archivo listo para presentacion a cliente/direccion
```
---
## Notas Tecnicas
### Modelo de Machine Learning
```python
# Modelo de prediccion basado en Gradient Boosting
import xgboost as xgb
from sklearn.model_selection import train_test_split
# Caracteristicas (features)
features = [
'progress_percentage', # % avance actual
'spent_to_date', # Gasto acumulado
'days_elapsed', # Dias transcurridos
'burn_rate', # Velocidad de gasto
'progress_rate', # Velocidad de avance
'cost_variance_trend', # Tendencia de desviacion
'schedule_variance_trend', # Tendencia de tiempo
'num_change_orders', # Numero de cambios
'weather_risk_score', # Riesgo climatico
'labor_availability_score', # Disponibilidad MO
'material_price_index', # Indice precios materiales
'historical_cpi', # CPI historico
'historical_spi', # SPI historico
'project_type_encoded', # Tipo de proyecto
'region_encoded' # Region
]
# Target (objetivo a predecir)
target_cost = 'final_cost'
target_date = 'completion_date'
# Entrenamiento del modelo
def train_prediction_model(historical_data):
X = historical_data[features]
y_cost = historical_data[target_cost]
y_date = historical_data[target_date]
X_train, X_test, y_train, y_test = train_test_split(X, y_cost, test_size=0.2)
model = xgb.XGBRegressor(
n_estimators=100,
learning_rate=0.1,
max_depth=6,
random_state=42
)
model.fit(X_train, y_train)
# Evaluar precision
score = model.score(X_test, y_test)
print(f"Model R² score: {score:.3f}")
return model
# Prediccion con intervalos de confianza
def predict_with_confidence(model, current_project_data):
# Prediccion puntual
prediction = model.predict([current_project_data])[0]
# Calcular intervalos usando quantile regression
optimistic = prediction * 0.95 # 5% mejor
expected = prediction
pessimistic = prediction * 1.10 # 10% peor
return {
'optimistic': optimistic,
'expected': expected,
'pessimistic': pessimistic,
'confidence': 0.80 # 80% confidence interval
}
# Explicabilidad con SHAP
import shap
def explain_prediction(model, project_data):
explainer = shap.TreeExplainer(model)
shap_values = explainer.shap_values(project_data)
# Obtener importancia de features
feature_importance = sorted(
zip(features, shap_values[0]),
key=lambda x: abs(x[1]),
reverse=True
)
return feature_importance
```
### Calculo de Indicadores
```typescript
// Cost Performance Index (CPI)
const CPI = earnedValue / actualCost;
// CPI > 1.0: Por debajo del presupuesto
// CPI < 1.0: Por encima del presupuesto
// Schedule Performance Index (SPI)
const SPI = earnedValue / plannedValue;
// SPI > 1.0: Adelantado
// SPI < 1.0: Atrasado
// Estimate at Completion (EAC) - Costo final estimado
const EAC = budgetAtCompletion / CPI;
// Estimate to Complete (ETC) - Costo restante estimado
const ETC = EAC - actualCost;
// Variance at Completion (VAC) - Variacion esperada
const VAC = budgetAtCompletion - EAC;
// Time to Complete - Tiempo restante
const totalDuration = plannedDuration / SPI;
const timeRemaining = totalDuration - daysElapsed;
```
### Endpoints Necesarios
```typescript
// Predicciones
GET /api/predictions/:projectId // Obtener predicciones
POST /api/predictions/:projectId/calculate // Calcular nuevas predicciones
PUT /api/predictions/:projectId/adjust // Ajustar supuestos
GET /api/predictions/:projectId/history // Historial de predicciones
// Riesgos
GET /api/predictions/:projectId/risks // Factores de riesgo
PUT /api/predictions/:projectId/risks/:id/status // Actualizar estado de riesgo
// Comparaciones
GET /api/predictions/:projectId/similar-projects // Proyectos similares
GET /api/predictions/:projectId/benchmarks // Benchmarks
// Exportacion
POST /api/predictions/:projectId/export // Exportar predicciones
```
### Job Programado
```typescript
// Actualizar predicciones semanalmente
import cron from 'node-cron';
// Cada lunes a las 6:00 AM
cron.schedule('0 6 * * 1', async () => {
console.log('Ejecutando actualizacion de predicciones...');
const activeProjects = await getActiveProjects();
for (const project of activeProjects) {
try {
// Extraer datos del proyecto
const data = await extractProjectData(project.id);
// Ejecutar modelo de prediccion
const predictions = await runPredictionModel(data);
// Guardar predicciones
await savePredictions(project.id, predictions);
// Detectar riesgos
const risks = await detectRisks(project.id, predictions);
await saveRisks(project.id, risks);
// Generar alertas si es necesario
if (predictions.expected.variance > 0.10) {
await createAlert(project.id, 'HIGH_COST_VARIANCE');
}
} catch (error) {
console.error(`Error en proyecto ${project.id}:`, error);
}
}
console.log('Predicciones actualizadas correctamente');
});
```
---
## Definicion de "Done"
- [ ] Modelo de ML entrenado con datos historicos
- [ ] Prediccion de costo final funcional
- [ ] Prediccion de fecha de termino funcional
- [ ] Tres escenarios (optimista, esperado, pesimista) calculados
- [ ] Deteccion automatica de factores de riesgo
- [ ] Graficas de proyeccion de costos y cronograma
- [ ] Calculo de CPI, SPI, Burn Rate
- [ ] Proyeccion de flujo de efectivo
- [ ] Comparacion con proyectos similares usando ML
- [ ] Alertas predictivas configurables
- [ ] Explicabilidad del modelo con importancia de features
- [ ] Historial de predicciones almacenado
- [ ] Job programado ejecutando semanalmente
- [ ] Precision del modelo >= 85%
- [ ] Exportacion de predicciones a PDF/Excel
- [ ] Tests del modelo de ML
- [ ] Documentacion del modelo y endpoints
- [ ] Validado con Directores de Proyecto
---
**Estimacion:** 8 Story Points
**Dependencias:** Requiere datos historicos de multiples proyectos
**Fecha:** 2025-11-18