371 lines
18 KiB
Markdown
371 lines
18 KiB
Markdown
# US-BI-002: Analisis de Desempeno y Margenes
|
||
|
||
**Epica:** MAI-006 - Reportes y Business Intelligence
|
||
**Sprint:** 19
|
||
**Story Points:** 5
|
||
**Prioridad:** Alta
|
||
**Asignado a:** Backend + Frontend
|
||
|
||
---
|
||
|
||
## Historia de Usuario
|
||
|
||
**Como** CFO (Director Financiero)
|
||
**Quiero** analizar margenes de utilidad y rentabilidad por proyecto
|
||
**Para** identificar proyectos mas y menos rentables y tomar decisiones estrategicas de inversion
|
||
|
||
---
|
||
|
||
## Criterios de Aceptacion
|
||
|
||
### 1. Vista de Analisis de Margenes
|
||
- [ ] Puedo acceder al modulo "Analisis de Margenes" desde el menu de BI
|
||
- [ ] Veo una vista consolidada de todos los proyectos con sus margenes
|
||
- [ ] Puedo filtrar por:
|
||
- Periodo (mes, trimestre, ano, rango personalizado)
|
||
- Estado del proyecto (Activo, Completado, Todos)
|
||
- Region geografica
|
||
- Tipo de proyecto
|
||
- Rango de presupuesto
|
||
- [ ] Los datos se actualizan en tiempo real al cambiar filtros
|
||
|
||
### 2. Tabla Comparativa de Rentabilidad
|
||
- [ ] Veo una tabla con todos los proyectos mostrando:
|
||
- Nombre del proyecto
|
||
- Presupuesto original
|
||
- Costo real acumulado
|
||
- Ingresos facturados
|
||
- **Margen Bruto:** (Ingresos - Costos) / Ingresos * 100
|
||
- **Margen Neto:** Considerando gastos indirectos
|
||
- **ROI:** (Utilidad / Inversion) * 100
|
||
- **Variacion vs Presupuesto:** % de desviacion
|
||
- Estado financiero (semaforo)
|
||
- [ ] Puedo ordenar por cualquier columna
|
||
- [ ] Los margenes se resaltan con colores:
|
||
- Verde: Margen > 20%
|
||
- Amarillo: Margen 10-20%
|
||
- Rojo: Margen < 10%
|
||
|
||
### 3. Grafica de Evolucion de Margenes
|
||
- [ ] Veo una grafica de lineas mostrando evolucion mensual de:
|
||
- Margen bruto promedio
|
||
- Margen neto promedio
|
||
- ROI acumulado
|
||
- [ ] Puedo comparar hasta 5 proyectos simultaneamente
|
||
- [ ] Puedo seleccionar el periodo de analisis (6, 12, 24 meses)
|
||
- [ ] La grafica muestra linea de referencia del objetivo corporativo (ej: 18%)
|
||
|
||
### 4. Analisis de Costos por Categoria
|
||
- [ ] Veo un grafico de pastel o barras mostrando distribucion de costos:
|
||
- Materiales (%)
|
||
- Mano de obra (%)
|
||
- Maquinaria y equipo (%)
|
||
- Subcontratos (%)
|
||
- Gastos indirectos (%)
|
||
- [ ] Puedo comparar la distribucion real vs presupuestada
|
||
- [ ] Puedo hacer drill-down a nivel de partida especifica
|
||
- [ ] Veo alertas si alguna categoria excede +15% lo presupuestado
|
||
|
||
### 5. Top Proyectos Rentables y No Rentables
|
||
- [ ] Veo dos listas lado a lado:
|
||
- **Top 5 Mas Rentables:** Proyectos con mayor margen neto
|
||
- **Top 5 Menos Rentables:** Proyectos con menor margen (o perdida)
|
||
- [ ] Cada proyecto muestra:
|
||
- Nombre
|
||
- Margen neto %
|
||
- Utilidad/Perdida en $
|
||
- Factor principal de exito/problema
|
||
- [ ] Puedo hacer clic para ver detalle del proyecto
|
||
|
||
### 6. Analisis de Variaciones
|
||
- [ ] Veo un panel mostrando variaciones clave:
|
||
- **Variacion de Precio:** Cambios en costos unitarios vs presupuesto
|
||
- **Variacion de Cantidad:** Cambios en volumenes ejecutados
|
||
- **Variacion de Eficiencia:** Productividad real vs planeada
|
||
- [ ] Para cada tipo de variacion veo:
|
||
- Monto total de variacion
|
||
- % de impacto en el margen
|
||
- Principales conceptos que contribuyen
|
||
- Tendencia (mejorando/empeorando)
|
||
|
||
### 7. Proyecciones de Margen Final
|
||
- [ ] Veo una proyeccion del margen final esperado basado en:
|
||
- % de avance actual
|
||
- Tendencia de costos
|
||
- Costos comprometidos pendientes
|
||
- [ ] Se muestran 3 escenarios:
|
||
- **Optimista:** Mejor caso (90% confianza)
|
||
- **Esperado:** Escenario mas probable (50% confianza)
|
||
- **Pesimista:** Peor caso (10% confianza)
|
||
- [ ] Veo un grafico de embudo mostrando la proyeccion
|
||
|
||
### 8. Exportacion y Reportes
|
||
- [ ] Puedo exportar analisis completo a Excel con multiples hojas:
|
||
- Resumen ejecutivo
|
||
- Tabla comparativa
|
||
- Evolucion temporal
|
||
- Distribucion de costos
|
||
- Top proyectos
|
||
- [ ] Puedo generar PDF ejecutivo con graficas
|
||
- [ ] Puedo programar envio mensual automatico al equipo financiero
|
||
|
||
---
|
||
|
||
## Mockup / Wireframe
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 💰 Analisis de Margenes y Rentabilidad │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Filtros: [Periodo: 2025 ▼] [Estado: Activos ▼] [Region: Todas ▼] │
|
||
│ │
|
||
│ ┌─ Resumen Consolidado ────────────────────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │ │
|
||
│ │ │ Margen Bruto │ │ Margen Neto │ │ ROI Promedio │ │ Utilidad │ │ │
|
||
│ │ │ Promedio │ │ Promedio │ │ Consolidado │ │ Total │ │ │
|
||
│ │ │ │ │ │ │ │ │ │ │ │
|
||
│ │ │ 🟢 22.5% │ │ 🟢 18.3% │ │ 🟢 21.7% │ │ $44.5 M │ │ │
|
||
│ │ │ ↗ +1.2% │ │ ↗ +0.8% │ │ ↗ +2.1% │ │ ↗ +5.2M │ │ │
|
||
│ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ Tabla Comparativa de Proyectos ────────────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
|
||
│ │ │Proyecto │Presup.│Costo │Ingreso│Mar.B│Mar.N│ROI │Var.│Est│ │ │
|
||
│ │ ├──────────────────────────────────────────────────────────────────┤ │ │
|
||
│ │ │Los Pinos │$45.2M │$38.1M│$45.8M │17.8%│14.2%│20.3%│+2.1│🟢 │ │ │
|
||
│ │ │Vertical Ref. │$38.5M │$35.2M│$38.9M │ 9.5%│ 7.1%│10.5%│-8.2│🔴 │ │ │
|
||
│ │ │Resid. Sur │$52.1M │$43.8M│$53.2M │17.7%│14.8%│21.5%│+1.5│🟢 │ │ │
|
||
│ │ │Conjunto Nte. │$28.7M │$26.1M│$29.1M │ 3.4%│ 2.1%│11.5%│+5.8│🟡 │ │ │
|
||
│ │ │El Bosque │$41.9M │$34.2M│$42.5M │19.5%│16.3%│24.3%│+1.1│🟢 │ │ │
|
||
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ │ Promedio: Mar.Bruto: 22.5% | Mar.Neto: 18.3% | ROI: 21.7% │ │
|
||
│ └──────────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ Evolucion de Margenes ───────────┬─ Distribucion de Costos ──────────┐ │
|
||
│ │ │ │ │
|
||
│ │ % │ Distribucion Real vs Presup. │ │
|
||
│ │ 25│ │ │ │
|
||
│ │ 20│ ╱─────╲ │ Materiales 48% [████] │ │
|
||
│ │ 15│ ╱ ╲─────╲ │ Presup: 45% [███ ] │ │
|
||
│ │ 10│ ╱ ╲ │ │ │
|
||
│ │ 5│╱ ╲ │ Mano Obra 28% [███] │ │
|
||
│ │ 0└───────────────────────── │ Presup: 30% [███ ] │ │
|
||
│ │ E F M A M J J A S O N D │ │ │
|
||
│ │ │ Subcontratos 15% [██] │ │
|
||
│ │ ─── Margen Bruto │ Presup: 15% [██ ] │ │
|
||
│ │ ─── Margen Neto │ │ │
|
||
│ │ ─── Objetivo (18%) │ Indirectos 9% [█] │ │
|
||
│ │ │ Presup: 10% [█ ] │ │
|
||
│ └────────────────────────────────────┴────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ Top 5 Mas Rentables ──────────────┬─ Top 5 Menos Rentables ───────────┐ │
|
||
│ │ │ │ │
|
||
│ │ 1. El Bosque 🟢 16.3% │ 1. Vertical Reforma 🔴 7.1% │ │
|
||
│ │ Utilidad: $6.8M │ Utilidad: $2.7M │ │
|
||
│ │ Factor: Eficiencia en MO │ Factor: Sobrecosto materiales │ │
|
||
│ │ │ │ │
|
||
│ │ 2. Residencial Sur 🟢 14.8% │ 2. Conjunto Norte 🟡 2.1% │ │
|
||
│ │ Utilidad: $7.7M │ Utilidad: $0.6M │ │
|
||
│ │ Factor: Negociacion proveedores │ Factor: Baja productividad │ │
|
||
│ │ │ │ │
|
||
│ │ 3. Los Pinos 🟢 14.2% │ 3. Proyecto Delta 🔴 -1.5% │ │
|
||
│ │ Utilidad: $6.4M │ Perdida: -$0.5M │ │
|
||
│ │ Factor: Economia escala │ Factor: Retrabajos calidad │ │
|
||
│ └─────────────────────────────────────┴────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ Proyeccion Margen Final ────────────────────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ Proyecto: Los Pinos (78% avance) │ │
|
||
│ │ │ │
|
||
│ │ Optimista: 18.5% [$8.4M] ▓▓▓▓▓▓▓▓▓░ │ │
|
||
│ │ Esperado: 16.2% [$7.3M] ▓▓▓▓▓▓▓▓░░ │ │
|
||
│ │ Pesimista: 13.8% [$6.2M] ▓▓▓▓▓▓▓░░░ │ │
|
||
│ │ │ │
|
||
│ │ Rango de confianza 90%: $6.2M - $8.4M │ │
|
||
│ │ Tendencia actual: ↗ Mejorando (ultima semana costos -3%) │ │
|
||
│ └───────────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ [📥 Exportar Excel] [📄 PDF] [📧 Programar] │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Flujo de Trabajo
|
||
|
||
```
|
||
1. ACCEDER AL ANALISIS DE MARGENES
|
||
↓
|
||
Usuario (CFO/Gerente Financiero) → Menu BI → Analisis de Margenes
|
||
↓
|
||
Sistema carga datos financieros de todos los proyectos
|
||
|
||
2. APLICAR FILTROS
|
||
↓
|
||
Usuario selecciona periodo: "2025"
|
||
Usuario filtra estado: "Activos"
|
||
↓
|
||
Sistema re-calcula metricas para proyectos filtrados
|
||
↓
|
||
KPIs y graficas se actualizan dinamicamente
|
||
|
||
3. ANALIZAR TABLA COMPARATIVA
|
||
↓
|
||
Usuario ordena tabla por "Margen Neto" (descendente)
|
||
↓
|
||
Sistema muestra proyectos desde mas rentable a menos rentable
|
||
↓
|
||
Usuario identifica proyecto con margen bajo (Vertical Reforma: 7.1%)
|
||
|
||
4. INVESTIGAR CAUSAS
|
||
↓
|
||
Usuario hace clic en "Vertical Reforma"
|
||
↓
|
||
Sistema muestra detalle de distribucion de costos
|
||
↓
|
||
Usuario ve que Materiales = 55% (presupuestado: 45%)
|
||
↓
|
||
Usuario identifica sobrecosto en materiales como causa principal
|
||
|
||
5. REVISAR EVOLUCION
|
||
↓
|
||
Usuario selecciona "Vertical Reforma" en grafica de evolucion
|
||
↓
|
||
Sistema muestra tendencia: Margen inicio 12% → actual 7.1%
|
||
↓
|
||
Usuario identifica que deterioro inicio hace 3 meses
|
||
|
||
6. ANALIZAR PROYECCION
|
||
↓
|
||
Usuario selecciona "Proyeccion Margen Final"
|
||
↓
|
||
Sistema calcula 3 escenarios basado en tendencia
|
||
↓
|
||
Escenario pesimista: Margen final 5.2%
|
||
↓
|
||
Usuario decide tomar acciones correctivas
|
||
|
||
7. EXPORTAR PARA JUNTA DIRECTIVA
|
||
↓
|
||
Usuario hace clic en "Exportar PDF"
|
||
↓
|
||
Sistema genera reporte ejecutivo con:
|
||
- Resumen de margenes consolidados
|
||
- Tabla comparativa completa
|
||
- Graficas de evolucion y distribucion
|
||
- Top proyectos rentables/no rentables
|
||
- Proyecciones y recomendaciones
|
||
↓
|
||
PDF se descarga para presentacion
|
||
```
|
||
|
||
---
|
||
|
||
## Notas Tecnicas
|
||
|
||
### Formulas de Calculo
|
||
|
||
```typescript
|
||
// 1. Margen Bruto
|
||
const margenBruto = ((ingresosTotales - costoDirecto) / ingresosTotales) * 100;
|
||
|
||
// 2. Margen Neto
|
||
const margenNeto = ((ingresosTotales - costoTotal - gastosIndirectos) / ingresosTotales) * 100;
|
||
|
||
// 3. ROI (Return on Investment)
|
||
const roi = ((utilidadNeta / inversionTotal) * 100);
|
||
|
||
// 4. Variacion de Presupuesto
|
||
const variacion = ((costoReal - presupuestoOriginal) / presupuestoOriginal) * 100;
|
||
|
||
// 5. Distribucion de Costos
|
||
const distribucion = {
|
||
materiales: (costoMateriales / costoTotal) * 100,
|
||
manoObra: (costoManoObra / costoTotal) * 100,
|
||
subcontratos: (costoSubcontratos / costoTotal) * 100,
|
||
indirectos: (gastosIndirectos / costoTotal) * 100
|
||
};
|
||
|
||
// 6. Proyeccion de Margen Final
|
||
function proyectarMargenFinal(proyecto) {
|
||
const avance = proyecto.avanceFisico;
|
||
const costoAcumulado = proyecto.costoReal;
|
||
const presupuestoRestante = proyecto.presupuestoTotal - costoAcumulado;
|
||
|
||
// Tendencia de costo por % de avance
|
||
const costoPorPunto = costoAcumulado / avance;
|
||
const costoProyectado = costoPorPunto * 100;
|
||
|
||
// Escenarios
|
||
const optimista = costoProyectado * 0.95; // 5% mejor
|
||
const esperado = costoProyectado;
|
||
const pesimista = costoProyectado * 1.05; // 5% peor
|
||
|
||
return {
|
||
optimista: calcularMargen(proyecto.ingresos, optimista),
|
||
esperado: calcularMargen(proyecto.ingresos, esperado),
|
||
pesimista: calcularMargen(proyecto.ingresos, pesimista)
|
||
};
|
||
}
|
||
```
|
||
|
||
### Endpoints Necesarios
|
||
|
||
```typescript
|
||
GET /api/analytics/margins // Vista principal
|
||
GET /api/analytics/margins/comparative-table // Tabla comparativa
|
||
GET /api/analytics/margins/evolution // Evolucion temporal
|
||
GET /api/analytics/margins/cost-distribution // Distribucion costos
|
||
GET /api/analytics/margins/top-projects // Top rentables
|
||
GET /api/analytics/margins/projections/:id // Proyecciones
|
||
GET /api/analytics/margins/variances/:id // Analisis variaciones
|
||
POST /api/analytics/margins/export-excel // Export Excel
|
||
POST /api/analytics/margins/export-pdf // Export PDF
|
||
```
|
||
|
||
### Reglas de Negocio
|
||
|
||
1. **Clasificacion de Semaforos:**
|
||
- Verde: Margen neto >= 15%
|
||
- Amarillo: Margen neto 10-14.9%
|
||
- Rojo: Margen neto < 10%
|
||
|
||
2. **Alertas Automaticas:**
|
||
- Alerta si margen < objetivo corporativo (18%)
|
||
- Alerta si tendencia descendente >2% en ultimo mes
|
||
- Alerta si proyeccion pesimista < 10%
|
||
|
||
3. **Calculo de Gastos Indirectos:**
|
||
- Se asignan proporcionalmente segun presupuesto
|
||
- Porcentaje configurable (default: 8%)
|
||
|
||
---
|
||
|
||
## Definicion de "Done"
|
||
|
||
- [ ] Vista de analisis de margenes accesible desde menu BI
|
||
- [ ] Filtros funcionales (periodo, estado, region, tipo)
|
||
- [ ] Tabla comparativa con 9 columnas de metricas
|
||
- [ ] Calculo correcto de margen bruto, neto y ROI
|
||
- [ ] Grafica de evolucion temporal con multiples proyectos
|
||
- [ ] Grafico de distribucion de costos (real vs presupuesto)
|
||
- [ ] Top 5 mas/menos rentables calculados correctamente
|
||
- [ ] Panel de proyecciones con 3 escenarios
|
||
- [ ] Exportacion a Excel con multiples hojas
|
||
- [ ] Exportacion a PDF ejecutivo con graficas
|
||
- [ ] Tests unitarios de formulas financieras
|
||
- [ ] Tests de integracion de endpoints
|
||
- [ ] Validacion con CFO y equipo financiero
|
||
- [ ] Documentacion de formulas y reglas de negocio
|
||
|
||
---
|
||
|
||
**Estimacion:** 5 Story Points
|
||
**Dependencias:** Requiere MAI-002 (Proyectos), MAI-003 (Costos)
|
||
**Fecha:** 2025-11-18
|