erp-construccion/docs/02-definicion-modulos/MAI-006-reportes-analytics/requerimientos/RF-BI-001-reportes-ejecutivos-consolidados.md

580 lines
24 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# RF-BI-001: Reportes Ejecutivos Consolidados
**Épica:** MAI-006 - Reportes y Business Intelligence
**Módulo:** Reportes Ejecutivos
**Responsable:** Product Owner
**Fecha:** 2025-11-17
**Versión:** 1.0
---
## 1. Objetivo
Proveer reportes ejecutivos consolidados que integren información de múltiples proyectos, permitiendo a la dirección general tener visibilidad completa del portafolio de obras con KPIs corporativos, análisis de desviaciones y comparativos históricos.
---
## 2. Casos de Uso
### CU-BI-001: Dashboard Corporativo Multi-Proyecto
**Actor:** Director General, CFO, Gerente de Operaciones
**Precondiciones:**
- Usuario tiene rol de dirección o ejecutivo
- Existen proyectos activos en el sistema
**Flujo Principal:**
1. Usuario accede al dashboard corporativo
2. Sistema muestra vista consolidada de todos los proyectos
3. Usuario ve KPIs principales:
- Total de proyectos activos: 12
- Inversión total en curso: $850M MXN
- Avance físico promedio: 68%
- Avance financiero promedio: 65%
- Margen operativo consolidado: 18.5%
- Viviendas en construcción: 450
- Viviendas terminadas este mes: 35
4. Usuario ve gráfica de distribución de proyectos por estado:
- Planeación: 3 proyectos
- En construcción: 8 proyectos
- En cierre: 1 proyecto
5. Usuario ve ranking de proyectos por desempeño (SPI, CPI)
6. Usuario puede filtrar por:
- Región geográfica
- Tipo de proyecto (fraccionamiento, vertical, mixto)
- Rango de presupuesto
- Período de construcción
**Postcondiciones:**
- Dashboard muestra información actualizada al día
- Métricas se actualizan en tiempo real
**Wireframe:**
```
┌────────────────────────────────────────────────────────────────────────┐
│ 📊 Dashboard Corporativo - Grupo Constructor ABC │
├────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ Resumen Global ──────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │ │
│ │ │Proyectos │Inversión │Av. Físico│Av. Financ│Margen Op.│ │ │
│ │ ├──────────┼──────────┼──────────┼──────────┼──────────┤ │ │
│ │ │ 12 │ $850M │ 68% │ 65% │ 18.5% │ │ │
│ │ │ 🟢 +2 │ 🟡 +$50M │ 🟡 -3% │ 🟡 -5% │ 🟢 +1.2% │ │ │
│ │ └──────────┴──────────┴──────────┴──────────┴──────────┘ │ │
│ │ │ │
│ │ ┌──────────┬──────────┬──────────┬──────────┐ │ │
│ │ │Viviendas │Terminadas│En Proceso│Vendidas │ │ │
│ │ ├──────────┼──────────┼──────────┼──────────┤ │ │
│ │ │ 450 │ 35 │ 180 │ 230 │ │ │
│ │ │(Este mes)│(Este mes)│ │ (51%) │ │ │
│ │ └──────────┴──────────┴──────────┴──────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Proyectos por Estado ─────────┐ ┌─ Top 5 Proyectos por SPI ──────┐ │
│ │ │ │ │ │
│ │ ┌───┐ │ │ 1. Fracc. Del Valle 1.15 ✅ │ │
│ │ 8 │ │ En Construcción │ │ 2. Torres Sol 1.08 ✅ │ │
│ │ └───┘ │ │ 3. Privada Roble 0.98 🟡 │ │
│ │ 3 ┌─┐ Planeación │ │ 4. Fracc. Pinos 0.92 🟡 │ │
│ │ └─┘ │ │ 5. Residencial Lago 0.85 🔴 │ │
│ │ 1 ┌┐ En Cierre │ │ │ │
│ │ └┘ │ │ [Ver Todos los Proyectos] │ │
│ └─────────────────────────────────┘ └─────────────────────────────────┘ │
│ │
│ ┌─ Distribución de Inversión por Tipo de Proyecto ──────────────────┐ │
│ │ │ │
│ │ Fraccionamientos: $520M (61%) ████████████████████ │ │
│ │ Edificios Verticales: $250M (29%) ████████████ │ │
│ │ Mixtos: $80M (10%) ████ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Alertas Corporativas ────────────────────────────────────────────┐ │
│ │ │ │
│ │ 🔴 2 proyectos con SPI < 0.90 (retraso crítico) │ │
│ │ 🟡 3 proyectos con sobrecosto > 5% │ │
│ │ 🟡 1 proyecto con liquidez < 30 días │ │
│ │ 5 proyectos próximos a hito de financiamiento │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ [Exportar Reporte] [Configurar] │
└────────────────────────────────────────────────────────────────────────┘
```
---
### CU-BI-002: Reporte de Desempeño por Proyecto
**Actor:** Director General, Gerente de Operaciones
**Precondiciones:**
- Proyectos tienen datos históricos (al menos 1 mes)
**Flujo Principal:**
1. Usuario solicita reporte de desempeño
2. Sistema muestra tabla comparativa de todos los proyectos:
```
┌───────────────────────────────────────────────────────────────────────────┐
│ Proyecto │Presupuesto│Av.Fís│Av.Fin│ SPI │ CPI │Margen│Alertas│
├───────────────────────────────────────────────────────────────────────────┤
│Fracc. Del Valle │ $120M │ 85% │ 82% │1.15 │1.08 │ 22% │ 0🔴 │
│Torres del Sol │ $95M │ 72% │ 70% │1.08 │1.02 │ 19% │ 0🔴 │
│Privada Roble │ $80M │ 65% │ 68% │0.98 │0.95 │ 17% │ 1🟡 │
│Fracc. Los Pinos │ $150M │ 58% │ 60% │0.92 │0.94 │ 16% │ 3🟡 │
│Residencial Lago │ $110M │ 45% │ 52% │0.85 │0.88 │ 12% │ 2🔴 │
│... │ │ │ │ │ │ │ │
└───────────────────────────────────────────────────────────────────────────┘
Leyenda:
SPI > 1.0: Adelantado | SPI = 1.0: En tiempo | SPI < 1.0: Retrasado
CPI > 1.0: Bajo presupuesto | CPI < 1.0: Sobre presupuesto
```
3. Usuario puede ordenar por cualquier columna
4. Usuario puede hacer clic en un proyecto para ver drill-down
5. Usuario puede exportar a Excel/PDF
**Postcondiciones:**
- Reporte generado y disponible para descarga
---
### CU-BI-003: Análisis de Márgenes Consolidado
**Actor:** CFO, Director General
**Precondiciones:**
- Proyectos tienen presupuestos y costos registrados
**Flujo Principal:**
1. Usuario accede a módulo de análisis de márgenes
2. Sistema calcula y muestra:
- **Margen Bruto Consolidado:**
```
Ingresos Totales: $950M
Costos Directos: $720M
Margen Bruto: $230M (24.2%)
```
- **Margen Operativo Consolidado:**
```
Margen Bruto: $230M
Gastos Indirectos: -$45M
Margen Operativo: $185M (19.5%)
```
- **Margen Neto Consolidado:**
```
Margen Operativo: $185M
Gastos Financieros: -$12M
Margen Neto: $173M (18.2%)
```
3. Usuario ve gráfica de evolución de márgenes por trimestre:
```
30%│
25%│ ●─────● Margen Bruto
20%│ ● ●───●───● Margen Operativo
15%│● ● Margen Neto
10%│
└────────────────────────────────→
Q1 Q2 Q3 Q4 Q1 Q2
2024 2024 2024 2024 2025 2025
```
4. Usuario ve desglose de márgenes por tipo de proyecto
5. Usuario identifica proyectos con margen < umbral (ej: <15%)
**Postcondiciones:**
- Análisis muestra oportunidades de mejora
---
### CU-BI-004: Reporte de Flujo de Efectivo Consolidado
**Actor:** CFO, Director Financiero
**Precondiciones:**
- Proyectos tienen estimaciones, pagos y facturación registrados
**Flujo Principal:**
1. Usuario solicita reporte de flujo de efectivo
2. Sistema genera proyección de flujo consolidado:
```
┌─────────────────────────────────────────────────────────────┐
│ Flujo de Efectivo Consolidado - Próximos 6 Meses │
├─────────────────────────────────────────────────────────────┤
│ │
│ $50M│ ╱──╲ │
│ $40M│ ╱───╱ ╲ │
│ $30M│ ╱───╱ ╲─╲ │
│ $20M│ ╱───╱ ╲ │
│ $10M│ ╲ │
│ $0M├──────────────────────────────────────────→ │
│ -$10M│ │
│ Ene Feb Mar Abr May Jun │
│ │
│ ─ Ingresos Esperados ─ Egresos Proyectados │
│ │
│ Análisis: │
│ • Liquidez actual: $45M │
│ • Saldo mínimo proyectado: $8M (Abril) │
│ • ⚠️ Requiere línea de crédito: $15M para Abril-Mayo │
│ • Recuperación esperada: Junio (+$25M por entrega Fracc) │
└─────────────────────────────────────────────────────────────┘
```
3. Usuario ve detalle de ingresos esperados:
- Por estimaciones aprobadas no cobradas
- Por anticipos contratados
- Por entrega de viviendas
4. Usuario ve detalle de egresos proyectados:
- Nómina
- Proveedores (OCs pendientes)
- Subcontratistas (estimaciones por pagar)
- Otros gastos operativos
5. Usuario identifica meses con déficit de liquidez
6. Sistema sugiere acciones (acelerar cobros, diferir pagos, línea de crédito)
**Postcondiciones:**
- CFO tiene visibilidad de necesidades de financiamiento
---
### CU-BI-005: Comparativo Histórico de Proyectos
**Actor:** Director General, Gerente de Operaciones
**Precondiciones:**
- Existen proyectos terminados en el sistema
**Flujo Principal:**
1. Usuario selecciona opción "Comparativo Histórico"
2. Usuario selecciona proyectos a comparar (hasta 5)
3. Sistema muestra tabla comparativa:
```
┌──────────────────────────────────────────────────────────────────────┐
│ Métrica │Fracc. │Torres │Privada │Fracc. │Promedio│
│ │Del Valle│Sol │Roble │Pinos │ │
├──────────────────────────────────────────────────────────────────────┤
│ Presupuesto Original │$120M │$95M │$80M │$150M │$111M │
│ Costo Final │$115M │$97M │$83M │$158M │$113M │
│ Varianza de Costo │-4.2% │+2.1% │+3.8% │+5.3% │+1.75% │
│ │ │
│ Duración Planificada │18 meses │15 meses│12 meses│24 meses│17.25m │
│ Duración Real │17 meses │16 meses│13 meses│26 meses│18m │
│ Varianza de Tiempo │-5.6% │+6.7% │+8.3% │+8.3% │+4.4% │
│ │ │
│ Viviendas Entregadas │50 │80 │40 │60 │57.5 │
│ Costo por Vivienda │$2.3M │$1.21M │$2.08M │$2.63M │$1.96M │
│ │ │
│ Margen Neto Final │22% │19% │17% │12% │17.5% │
│ ROI │31% │26% │23% │16% │24% │
└──────────────────────────────────────────────────────────────────────┘
```
4. Usuario identifica patrones:
- Proyectos de fraccionamientos tienden a tener sobrecosto de +2-5%
- Proyectos verticales son más rentables (menor costo/unidad)
- Proyectos >$100M tienen mayor riesgo de retraso
5. Usuario ve gráficas de benchmarking
6. Sistema sugiere mejores prácticas basadas en proyectos exitosos
**Postcondiciones:**
- Lecciones aprendidas documentadas
---
## 3. Requerimientos Funcionales
### RF-BI-001.1: Dashboard Corporativo
- El sistema DEBE mostrar dashboard consolidado con KPIs de todos los proyectos
- El sistema DEBE actualizar métricas en tiempo real
- El sistema DEBE permitir filtrado por región, tipo, presupuesto
- El sistema DEBE mostrar alertas corporativas prioritarias
### RF-BI-001.2: Reportes de Desempeño
- El sistema DEBE generar tabla comparativa de proyectos con SPI, CPI, margen
- El sistema DEBE permitir ordenamiento por cualquier métrica
- El sistema DEBE permitir drill-down a detalle de proyecto
- El sistema DEBE permitir exportación a Excel y PDF
### RF-BI-001.3: Análisis de Márgenes
- El sistema DEBE calcular margen bruto, operativo y neto consolidado
- El sistema DEBE mostrar evolución histórica de márgenes
- El sistema DEBE identificar proyectos con margen < umbral configurable
- El sistema DEBE desglosar márgenes por tipo de proyecto
### RF-BI-001.4: Flujo de Efectivo Consolidado
- El sistema DEBE proyectar flujo de efectivo consolidado para 6 meses
- El sistema DEBE identificar meses con déficit de liquidez
- El sistema DEBE detallar ingresos esperados (estimaciones, anticipos, entregas)
- El sistema DEBE detallar egresos proyectados (nómina, proveedores, subcontratistas)
- El sistema DEBE sugerir acciones para cerrar gaps de liquidez
### RF-BI-001.5: Comparativo Histórico
- El sistema DEBE permitir comparar hasta 5 proyectos simultáneamente
- El sistema DEBE calcular varianzas de costo y tiempo
- El sistema DEBE calcular métricas de eficiencia (costo/vivienda, ROI)
- El sistema DEBE identificar patrones y tendencias
- El sistema DEBE sugerir mejores prácticas
---
## 4. Modelo de Datos
```typescript
// Dashboard Corporativo
interface CorporateDashboard {
totalProjects: number;
totalInvestment: number;
avgPhysicalProgress: number;
avgFinancialProgress: number;
operatingMargin: number;
unitsUnderConstruction: number;
unitsCompletedThisMonth: number;
unitsSold: number;
projectsByStatus: {
planning: number;
construction: number;
closing: number;
};
topProjectsBySPI: {
projectId: string;
projectName: string;
spi: number;
}[];
investmentByType: {
type: 'fraccionamiento' | 'vertical' | 'mixto';
amount: number;
percentage: number;
}[];
corporateAlerts: {
critical: number;
warning: number;
info: number;
};
}
// Reporte de Desempeño
interface ProjectPerformanceReport {
projects: {
projectId: string;
projectName: string;
budget: number;
physicalProgress: number;
financialProgress: number;
spi: number;
cpi: number;
margin: number;
criticalAlerts: number;
warningAlerts: number;
}[];
summary: {
totalProjects: number;
avgSPI: number;
avgCPI: number;
avgMargin: number;
projectsOnTrack: number; // SPI >= 0.95
projectsDelayed: number; // SPI < 0.95
projectsOverBudget: number; // CPI < 0.95
};
}
// Análisis de Márgenes
interface MarginAnalysis {
consolidated: {
totalRevenue: number;
directCosts: number;
grossMargin: number;
grossMarginPct: number;
indirectCosts: number;
operatingMargin: number;
operatingMarginPct: number;
financialExpenses: number;
netMargin: number;
netMarginPct: number;
};
quarterlyTrend: {
quarter: string; // "Q1-2024"
grossMarginPct: number;
operatingMarginPct: number;
netMarginPct: number;
}[];
byProjectType: {
projectType: string;
avgGrossMargin: number;
avgOperatingMargin: number;
avgNetMargin: number;
}[];
lowMarginProjects: {
projectId: string;
projectName: string;
netMarginPct: number;
threshold: number;
}[];
}
// Flujo de Efectivo Consolidado
interface CashFlowProjection {
currentLiquidity: number;
monthlyProjection: {
month: string; // "2025-01"
expectedIncome: number;
projectedExpenses: number;
netCashFlow: number;
cumulativeCashFlow: number;
}[];
incomeBreakdown: {
month: string;
estimationsReceivable: number;
anticipations: number;
unitDeliveries: number;
other: number;
}[];
expenseBreakdown: {
month: string;
payroll: number;
suppliers: number;
subcontractors: number;
otherOperating: number;
}[];
analysis: {
minProjectedBalance: number;
minBalanceMonth: string;
creditLineNeeded: number;
suggestedActions: string[];
};
}
// Comparativo Histórico
interface HistoricalComparison {
projects: {
projectId: string;
projectName: string;
budgetOriginal: number;
finalCost: number;
costVariance: number;
costVariancePct: number;
plannedDuration: number; // meses
actualDuration: number;
timeVariance: number;
timeVariancePct: number;
unitsDelivered: number;
costPerUnit: number;
netMarginPct: number;
roi: number;
}[];
averages: {
avgCostVariancePct: number;
avgTimeVariancePct: number;
avgCostPerUnit: number;
avgNetMarginPct: number;
avgROI: number;
};
patterns: {
pattern: string; // "Fraccionamientos > $100M tienden a +5% sobrecosto"
confidence: number; // 0-100%
sampleSize: number;
}[];
bestPractices: {
practice: string;
basedOnProjects: string[]; // project IDs
}[];
}
```
---
## 5. Criterios de Aceptación
### Generales
- [ ] Dashboard corporativo muestra información consolidada de todos los proyectos
- [ ] Métricas se actualizan en tiempo real (<5 minutos de latencia)
- [ ] Todos los reportes permiten exportación a Excel y PDF
- [ ] Sistema maneja correctamente proyectos en diferentes etapas
- [ ] Cálculos de SPI, CPI, márgenes son matemáticamente correctos
### Dashboard Corporativo
- [ ] Muestra KPIs principales con tendencia vs mes anterior
- [ ] Gráfica de distribución de proyectos por estado es precisa
- [ ] Ranking de proyectos se actualiza automáticamente
- [ ] Filtros funcionan correctamente
- [ ] Alertas corporativas son relevantes y priorizadas
### Análisis de Márgenes
- [ ] Cálculo de margen bruto = (Ingresos - Costos Directos) / Ingresos
- [ ] Cálculo de margen operativo = (Margen Bruto - Gastos Indirectos) / Ingresos
- [ ] Cálculo de margen neto = (Margen Operativo - Gastos Financieros) / Ingresos
- [ ] Gráfica de tendencia muestra correctamente evolución trimestral
- [ ] Proyectos con margen < umbral se identifican correctamente
### Flujo de Efectivo
- [ ] Proyección de flujo es precisa 10% de valores reales históricos)
- [ ] Sistema identifica meses con liquidez < 30 días operativos
- [ ] Detalle de ingresos incluye todas las fuentes
- [ ] Detalle de egresos incluye todas las categorías
- [ ] Sugerencias de acciones son relevantes
### Comparativo Histórico
- [ ] Se pueden seleccionar hasta 5 proyectos
- [ ] Varianzas de costo y tiempo se calculan correctamente
- [ ] Costo por unidad = Costo Total / Unidades Entregadas
- [ ] ROI = (Ingresos - Costos) / Costos × 100
- [ ] Patrones identificados tienen confianza > 70%
---
## 6. Notas Técnicas
### Cálculo de Métricas Consolidadas
```typescript
// Promedio Ponderado de SPI
const consolidatedSPI = projects.reduce((sum, p) => sum + (p.spi * p.budget), 0) /
projects.reduce((sum, p) => sum + p.budget, 0);
// Margen Operativo Consolidado
const totalRevenue = projects.reduce((sum, p) => sum + p.revenue, 0);
const totalDirectCosts = projects.reduce((sum, p) => sum + p.directCosts, 0);
const totalIndirectCosts = overhead + adminExpenses + salesExpenses;
const operatingMargin = ((totalRevenue - totalDirectCosts - totalIndirectCosts) / totalRevenue) * 100;
// Proyección de Flujo de Efectivo
const projectedIncome = estimationsReceivable + anticipations + unitDeliveries;
const projectedExpenses = payroll + suppliers + subcontractors + other;
const netCashFlow = projectedIncome - projectedExpenses;
```
---
**Fecha:** 2025-11-17
**Preparado por:** Equipo de Producto
**Versión:** 1.0
**Estado:** ✅ Listo para Revisión