workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-003-presupuestos-costos/RESUMEN-EPICA-MAI-003.md

RESUMEN EJECUTIVO - MAI-003: Presupuestos y Control de Costos

Versión: 1.0 Fecha: 2025-11-17 Estado: ✅ COMPLETO (100%)

---

📊 Estado del Progreso

Tipo de Documento	Completados	Total	%	Tamaño
Requerimientos Funcionales (RF)	4	4	100% ✅	~120 KB
Especificaciones Técnicas (ET)	4	4	100% ✅	~95 KB
Historias de Usuario (US)	8	8	100% ✅	~40 KB
Total Documentos	16	16	100% ✅	~255 KB

Story Points Totales: 46 SP

---

🎯 Objetivos de Negocio

Problema que Resuelve

Las constructoras pierden entre 5-15% de margen debido a:

• ❌ Presupuestos desactualizados o imprecisos
• ❌ Falta de control sobre costos reales
• ❌ Desconocimiento de rentabilidad por prototipo
• ❌ Reacción tardía ante desviaciones

Solución Propuesta

Sistema integral de presupuestos y costos que permite:

• ✅ Catálogo centralizado de 10,000+ conceptos reutilizables
• ✅ Presupuestos en 3 niveles (obra, etapa, prototipo) con generadores automáticos
• ✅ Control en tiempo real de costos con alertas proactivas
• ✅ Análisis de rentabilidad con simulaciones y proyecciones

Beneficios Esperados

• Eficiencia: -80% tiempo elaboración presupuestos (2h vs 10h)
• Precisión: <3% desviación presupuesto vs real
• Rentabilidad: +2 puntos de margen por mejor control
• Visibilidad: Dashboard actualizado en tiempo real

---

📁 Documentos Generados

Requerimientos Funcionales (4)

✅ RF-COST-001: Catálogo de Conceptos y Precios Unitarios (~35 KB)

Alcance:

• 4 tipos de conceptos: material, mano de obra, maquinaria, compuesto
• Catálogo jerárquico por división CMIC (16 capítulos)
• Análisis de precios unitarios (APU) detallado
• Versionado y historial de precios
• Regionalización de precios
• Importación/exportación Excel, OPUS, Neodata

Componentes Clave:

Concepto Compuesto "Cimentación corrida":
├─ Materiales: $4,548 (concreto, acero, cimbra, alambre)
├─ Mano de Obra: $1,125 (oficial + ayudantes con FSR)
├─ Maquinaria: $226 (vibrador + herramienta menor)
├─ CD: $5,899
├─ Indirectos (12%): $708
├─ Financiamiento (3%): $177
├─ Utilidad (10%): $590
├─ Cargos (2%): $118
└─ PU Final: $7,492/m³ + IVA

✅ RF-COST-002: Presupuestos Maestros (Obra, Etapa, Prototipo) (~38 KB)

Alcance:

• Presupuesto de obra con desglose CMIC
• Presupuesto de etapa por fase constructiva
• Presupuesto de prototipo con generadores automáticos
• Versionado completo (baseline, ajustes, cambios de alcance)
• Análisis de rentabilidad integrado
• Curva S y distribución temporal

Ejemplo Generador:

// Excavación para cimentación
formula: "desplantDepth * buildingPerimeter * 0.60 * 0.80"
inputs: {
  desplantDepth: 0.80m,
  buildingPerimeter: 30m
}
result: 14.40 m³

✅ RF-COST-003: Control de Costos Reales y Desviaciones (~32 KB)

Alcance:

• Registro automático desde compras, nómina, subcontratos
• Dashboard con curva S
• Cálculo de desviaciones (precio, cantidad, mixta)
• Proyecciones EAC (3 métodos)
• Alertas automáticas configurables
• Plan de acción obligatorio para desviaciones >5%

Indicadores Clave:

CPI (Cost Performance Index) = Valor Ganado / Costo Real
SPI (Schedule Performance Index) = Valor Ganado / Valor Planificado
EAC (Estimate at Completion) = Presupuesto / CPI

✅ RF-COST-004: Análisis de Rentabilidad y Márgenes (~15 KB)

Alcance:

• Análisis financiero por proyecto
• Comparación de rentabilidad por prototipo
• Punto de equilibrio y margen de seguridad
• Simulador de escenarios
• Matriz de sensibilidad (precio vs costo)
• ROI y TIR proyectados

Ejemplo Análisis:

Proyecto: 150 viviendas
Ingresos: $165.75M
Costos: $153.70M
Margen: 7.3%
PE: 110 viviendas (73%)
Margen seguridad: 27% ✓

---

Especificaciones Técnicas (4)

✅ ET-COST-001: Implementación del Catálogo de Conceptos (~28 KB)

Stack Técnico:

• DB: PostgreSQL con schema budgets
• Backend: NestJS + TypeORM
• Frontend: React + Zustand

Tablas Principales:

budgets.concept_catalog (conceptos base)
budgets.concept_price_history (historial precios)
budgets.regions (regionalización)

Funcionalidades:

• CRUD completo con validaciones
• Búsqueda full-text (<200ms)
• Actualización masiva de precios
• Cálculo automático PU compuestos
• Triggers para historial automático

✅ ET-COST-002: Implementación de Presupuestos (~25 KB)

Tablas:

budgets.budgets (presupuestos maestros)
budgets.budget_items (partidas jerárquicas)
budgets.budget_versions (versionado)

Funcionalidades:

• Wizard de creación desde prototipos
• Generadores de volumetrías
• Cálculo automático de totales (trigger)
• Versionado con comparación
• Exportación Excel/PDF

✅ ET-COST-003: Implementación de Control de Costos (~25 KB)

Tablas:

budgets.actual_costs (costos reales)
budgets.cost_variances (desviaciones)
budgets.cost_projections (proyecciones)

Funcionalidades:

• Integración con compras/nómina/subcontratos
• Recálculo automático de desviaciones
• Proyección EAC con 3 métodos
• Cron job diario (6:00 AM)
• Dashboard con Chart.js

✅ ET-COST-004: Implementación de Análisis de Rentabilidad (~17 KB)

Tablas:

budgets.profitability_analysis
budgets.prototype_profitability

Funcionalidades:

• Cálculo automático de rentabilidad
• Simulador de escenarios
• Matriz de sensibilidad
• Comparación de prototipos
• Punto de equilibrio visual

---

Historias de Usuario (8)

Sprint 7 (13 SP)

• ✅ US-COST-001: Catálogo de Conceptos y Búsqueda (5 SP)
• ✅ US-COST-002: Precios Unitarios Compuestos (5 SP)
• ✅ US-COST-003: Actualización Masiva de Precios (3 SP)

Sprint 8 (13 SP)

• ✅ US-COST-004: Presupuesto de Obra Completo (8 SP)
• ✅ US-COST-005: Presupuesto de Prototipo con Generadores (5 SP)

Sprint 9 (10 SP)

• ✅ US-COST-006: Dashboard de Control de Costos Reales (5 SP)
• ✅ US-COST-007: Análisis de Desviaciones y Plan de Acción (5 SP)

Sprint 10 (5 SP)

• ✅ US-COST-008: Análisis de Rentabilidad y Simulaciones (5 SP)

---

🏗️ Arquitectura Técnica

Base de Datos

Schema: budgets Tablas: 9 tablas principales

concept_catalog (catálogo de conceptos)
├─ concept_price_history
└─ regions

budgets (presupuestos)
├─ budget_items (partidas)
└─ budget_versions

actual_costs (costos reales)
├─ cost_variances
└─ cost_projections

profitability_analysis
└─ prototype_profitability

Funciones SQL:

• calculate_composite_price(): Calcula PU de concepto compuesto
• calculate_variances(): Genera análisis de desviaciones
• calculate_eac(): Proyección de costo final
• calculate_profitability(): Análisis de rentabilidad

Triggers:

• Auto-actualización de updated_at
• Historial automático de precios
• Recálculo de totales en presupuestos
• Alertas automáticas en desviaciones >5%

Backend (NestJS)

Módulos:

• BudgetsModule
  • ConceptCatalogService
  • BudgetService
  • CostControlService
  • ProfitabilityService

Controllers:

• ConceptCatalogController (9 endpoints)
• BudgetController (12 endpoints)
• CostControlController (8 endpoints)
• ProfitabilityController (6 endpoints)

Cron Jobs:

• CostAnalysisTask.analyzeDailyCosts() - Diario 6:00 AM

Frontend (React + Vite)

Stores (Zustand):

• useConceptCatalogStore
• useBudgetStore
• useCostControlStore
• useProfitabilityStore

Páginas Principales:

• /concept-catalog - Catálogo de conceptos
• /budgets/:id - Detalle de presupuesto
• /cost-control/:projectId - Control de costos
• /profitability/:projectId - Análisis de rentabilidad

Componentes Clave:

• ConceptCatalogList - Lista con búsqueda y filtros
• CreateConceptModal - Formulario de concepto compuesto
• BudgetItemsTree - Árbol jerárquico de partidas
• CurveS - Gráfica de curva S (Chart.js)
• SensitivityMatrix - Matriz de sensibilidad
• ScenarioSimulator - Simulador interactivo

---

📈 Estimación de Sprints

Distribución Propuesta

Sprint 7 (2 semanas) - 13 SP: Catálogo de conceptos base

• US-COST-001: Catálogo de Conceptos (5 SP)
• US-COST-002: Precios Compuestos (5 SP)
• US-COST-003: Actualización Masiva (3 SP)

Sprint 8 (2 semanas) - 13 SP: Presupuestos

• US-COST-004: Presupuesto de Obra (8 SP)
• US-COST-005: Presupuesto de Prototipo (5 SP)

Sprint 9 (2 semanas) - 10 SP: Control de costos

• US-COST-006: Dashboard Control (5 SP)
• US-COST-007: Análisis Desviaciones (5 SP)

Sprint 10 (2 semanas) - 5 SP: Rentabilidad

• US-COST-008: Análisis Rentabilidad (5 SP)

Total: 4 sprints × 2 semanas = 8 semanas de desarrollo

---

⚙️ Configuración SaaS Multi-tenant

Activación del Módulo

MAI-003 es un módulo core incluido en los 3 planes de suscripción:

Plan	Módulo MAI-003	Funcionalidades	Límites
Básico	✅ Incluido	Catálogo + Presupuestos básicos	500 conceptos, 10 presupuestos/proyecto
Profesional	✅ Incluido	Todo + Control de costos	2,000 conceptos, 50 presupuestos
Enterprise	✅ Incluido	Todo + Rentabilidad avanzada	Ilimitado

Activación automática: Este módulo se activa durante el onboarding junto con MAI-002 (Proyectos).

Portal de Administración SaaS

Para Super Admin (Equipo Interno)

Panel de gestión del módulo:

┌─────────────────────────────────────────────────────────┐
│  Módulo MAI-003: Presupuestos y Costos                 │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  📊 Uso Global (Todos los Tenants)                     │
│  ────────────────────────────────────────              │
│  Tenants con módulo activo:    234/234 (100%)          │
│  Presupuestos totales:         5,678                    │
│  Conceptos en catálogos:       1,234,567               │
│  Costos reales registrados:    $2.4B MXN acum.         │
│                                                         │
│  🔧 Feature Flags                                      │
│  ────────────────────────────────────────              │
│  ☑️ budgets.composite_concepts (ENABLED)              │
│     Conceptos compuestos con APU                        │
│                                                         │
│  ☑️ budgets.cost_control_dashboard (ENABLED)          │
│     Dashboard de control de costos reales               │
│                                                         │
│  ☑️ budgets.profitability_analysis (ENABLED)          │
│     Análisis de rentabilidad y simulaciones             │
│                                                         │
│  ☐ budgets.ai_cost_prediction (BETA)                  │
│     Predicción de costos con ML (Beta)                  │
│                                                         │
│  📈 Métricas de Rendimiento                            │
│  ────────────────────────────────────────              │
│  Búsqueda conceptos (p95):        178 ms ✅             │
│  Cálculo PU compuesto (p95):       45 ms ✅             │
│  Generación presupuesto (100 partidas): 1.8s ✅         │
│  Actualización masiva (500 conceptos): 4.2s ✅          │
│                                                         │
└─────────────────────────────────────────────────────────┘

Para Tenant Admin (Cliente/Constructora)

Panel de configuración del módulo:

┌─────────────────────────────────────────────────────────┐
│  Configuración: Módulo de Presupuestos                 │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  📊 Uso Actual (Constructora ABC)                      │
│  ────────────────────────────────────────              │
│  Plan: Profesional ($799/mes)                           │
│  Conceptos en catálogo: 842 / 2,000  (42%)             │
│  Presupuestos activos: 23                               │
│  Proyectos con control de costos: 8 / 12               │
│                                                         │
│  ⚙️ Configuraciones Personalizadas                     │
│  ────────────────────────────────────────              │
│  Indirectos por defecto: [12%___]                       │
│  Financiamiento: [3%___]                                │
│  Utilidad esperada: [10%___]                            │
│  Cargos adicionales: [2%___]                            │
│                                                         │
│  ☑️ Alertar cuando desviación > [5%___]                │
│  ☑️ Requerir plan de acción para desviaciones >5%      │
│  ☐ Enviar reporte semanal de costos                    │
│                                                         │
│  📂 Catálogo de Conceptos                              │
│  ────────────────────────────────────────              │
│  Materiales: 423 conceptos                              │
│  Mano de Obra: 156 conceptos                            │
│  Maquinaria: 89 conceptos                               │
│  Compuestos: 174 conceptos                              │
│                                                         │
│  [Importar Catálogo OPUS]  [Exportar a Excel]          │
│                                                         │
│  🌍 Regionalización de Precios                         │
│  ────────────────────────────────────────              │
│  Regiones configuradas: 3                               │
│  • Región Centro (base)                                 │
│  • Región Norte (+8% en materiales)                    │
│  • Región Sur (-3% en mano de obra)                    │
│                                                         │
│  [Gestionar Regiones]                                   │
│                                                         │
│  ⚠️ Límites del Plan                                   │
│  ────────────────────────────────────────              │
│  Estás usando 842 de 2,000 conceptos permitidos.       │
│  ¿Necesitas catálogo más grande?                       │
│  [Actualizar a Plan Enterprise] (ilimitados)            │
│                                                         │
└─────────────────────────────────────────────────────────┘

Provisioning Automático

Durante el onboarding, el sistema ejecuta:

-- 1. Activar módulo MAI-003
INSERT INTO constructoras.constructora_modules (
  constructora_id,
  module_code,
  is_active,
  plan_included
) VALUES (
  $constructora_id,
  'MAI-003',
  true,
  true
);

-- 2. Crear regiones base
INSERT INTO budgets.regions (
  constructora_id,
  code,
  name,
  description
) VALUES
  ($constructora_id, 'CENTRO', 'Región Centro', 'Región base sin ajustes'),
  ($constructora_id, 'NORTE', 'Región Norte', 'Ajuste +8% materiales'),
  ($constructora_id, 'SUR', 'Región Sur', 'Ajuste -3% mano de obra');

-- 3. Importar catálogo seed (100 conceptos básicos)
INSERT INTO budgets.concept_catalog (
  constructora_id,
  code,
  name,
  concept_type,
  category,
  unit,
  base_price
) SELECT
  $constructora_id,
  seed_code,
  seed_name,
  seed_type,
  seed_category,
  seed_unit,
  seed_price
FROM budgets.seed_concept_catalog;

-- 4. Configurar límites por plan
INSERT INTO constructoras.constructora_limits (
  constructora_id,
  limit_key,
  limit_value
) VALUES
  ($constructora_id, 'max_concepts', 2000),  -- Plan Profesional
  ($constructora_id, 'max_budgets_per_project', 50),
  ($constructora_id, 'max_regions', 5);

-- 5. Configurar parámetros por defecto
INSERT INTO budgets.constructora_budget_config (
  constructora_id,
  indirect_percentage,
  financing_percentage,
  utility_percentage,
  additional_charges_percentage
) VALUES (
  $constructora_id,
  12.00,  -- 12% indirectos
  3.00,   -- 3% financiamiento
  10.00,  -- 10% utilidad
  2.00    -- 2% cargos
);

Aislamiento de Datos (RLS)

Garantía de seguridad multi-tenant:

-- Configuración de contexto por sesión
SET app.current_constructora_id = 'uuid-de-constructora-abc';
SET app.current_user_role = 'budget_manager';

-- Toda query automáticamente filtra por constructora
SELECT * FROM budgets.concept_catalog;
-- Internamente ejecuta:
-- SELECT * FROM budgets.concept_catalog
-- WHERE constructora_id = current_setting('app.current_constructora_id')::UUID;

-- Imposible ver conceptos de otras constructoras
SELECT * FROM budgets.concept_catalog WHERE constructora_id = 'otra-uuid';
-- Retorna: 0 rows (bloqueado por RLS policy)

Políticas RLS completas: Ver implementacion/ET-COST-001-002-rls-policies.sql

Migraciones y Actualizaciones

Actualización de catálogo nacional (semestral):

// Cron job: Actualizar precios según índices INPC/CMIC
@Cron('0 0 1 */6 *')  // Cada 6 meses, día 1 a medianoche
async updateNationalCatalogPrices() {
  // Solo actualizar conceptos que usen índice nacional
  await this.db.query(`
    UPDATE budgets.concept_catalog
    SET base_price = base_price * (1 + $index_increase / 100),
        price_update_source = 'auto_inpc_cmic',
        updated_at = NOW()
    WHERE constructora_id = ANY($constructora_ids)
      AND use_national_index = true
  `, {
    index_increase: 5.2,  // 5.2% incremento semestral
    constructora_ids: allConstructoraIds
  });

  // Crear registro en historial de precios
  await this.createPriceHistoryEntries();
}

Monitoreo por Tenant

Métricas capturadas:

// Evento de auditoría
{
  "event": "budget.created",
  "timestamp": "2025-11-20T10:30:00Z",
  "constructora_id": "uuid-constructora-abc",
  "user_id": "uuid-user-123",
  "budget_id": "uuid-budget-456",
  "metadata": {
    "budget_code": "PRES-PROJ-2025-001",
    "project_id": "uuid-project",
    "scope": "project",  // project | stage | prototype
    "total_amount": 15750000.00,
    "items_count": 247,
    "generation_time_ms": 1842
  }
}

Dashboard de métricas:

• Presupuestos generados por mes
• Conceptos más utilizados
• Desviación promedio presupuesto vs real
• Tiempo promedio de generación
• Alertas de costos activadas

Upgrade de Plan

Desbloqueo de límites:

-- Actualizar de Profesional a Enterprise
UPDATE constructoras.constructora_limits
SET limit_value = -1  -- -1 = ilimitado
WHERE constructora_id = $tenant_id
  AND limit_key IN ('max_concepts', 'max_budgets_per_project');

-- Activar feature de análisis avanzado
UPDATE constructoras.constructora_feature_flags
SET is_enabled = true
WHERE constructora_id = $tenant_id
  AND flag_key = 'budgets.profitability_analysis';

Soporte y Troubleshooting

Queries de diagnóstico:

-- Ver estado de presupuestos de un tenant
SELECT
  c.name AS constructora,
  COUNT(DISTINCT b.id) AS total_budgets,
  COUNT(DISTINCT cc.id) AS total_concepts,
  SUM(CASE WHEN b.status = 'approved' THEN 1 ELSE 0 END) AS approved_budgets,
  AVG(b.total_amount) AS avg_budget_amount,
  cl.limit_value AS max_concepts_allowed
FROM constructoras.constructoras c
LEFT JOIN budgets.budgets b ON b.constructora_id = c.id
LEFT JOIN budgets.concept_catalog cc ON cc.constructora_id = c.id
LEFT JOIN constructoras.constructora_limits cl ON cl.constructora_id = c.id
  AND cl.limit_key = 'max_concepts'
WHERE c.subdomain = 'constructora-abc'
GROUP BY c.id, c.name, cl.limit_value;

-- Análisis de performance de generación de presupuestos
SELECT
  constructora_id,
  AVG(generation_time_ms) AS avg_generation_time,
  MAX(generation_time_ms) AS max_generation_time,
  COUNT(*) AS budgets_generated,
  AVG(items_count) AS avg_items_per_budget
FROM audit.budget_generation_logs
WHERE created_at > NOW() - INTERVAL '30 days'
  AND constructora_id = $tenant_id
GROUP BY constructora_id;

---

🔗 Integraciones

Módulos que Consume (Input)

• MAI-002 (Proyectos):
  • Estructura de proyectos/etapas
  • Prototipos de vivienda
  • Características para generadores
• MAI-004 (Compras):
  • Órdenes de compra → Costos reales
  • Precios de proveedores
• MAI-007 (RR.HH.):
  • Nómina → Costos de mano de obra
• MAI-008 (Configuración):
  • Índices INPC/CMIC
  • Regiones/plazas

Módulos que Alimenta (Output)

• MAI-002 (Proyectos):
  • Costo unitario por prototipo
• MAI-004 (Compras):
  • Presupuesto de materiales
  • Alertas de precios fuera de presupuesto
• MAI-006 (Reportes):
  • Datos financieros
  • Indicadores de rentabilidad
  • Análisis de desviaciones

---

✅ Criterios de Éxito

Métricas de Adopción

• 100% de proyectos con presupuesto formal
• 90% de presupuestos usan catálogo estándar
• <5% de conceptos duplicados en catálogo

Métricas de Eficiencia

• Reducción 80% tiempo de elaboración (-8h por presupuesto)
• Búsqueda de conceptos <200ms
• Actualización masiva de precios <5 seg para 500 conceptos

Métricas de Calidad

• Precisión presupuesto vs real <3% de desviación
• 100% de alertas críticas con plan de acción en 48h
• Proyección EAC vs costo final <2% de error

Métricas de Rentabilidad

• 80% de proyectos con margen ≥ target
• Incremento de margen promedio +2 puntos anuales
• ROI portafolio ≥ 12% anual

---

🚀 Próximos Pasos

Opción 1: Comenzar Implementación (Recomendado)

El equipo de desarrollo puede iniciar Sprint 7 con la documentación completa. Prioridad alta debido a impacto directo en rentabilidad.

Opción 2: Continuar Documentación

Generar épica siguiente:

• MAI-004: Compras e Inventarios (45 SP estimados)
• MAI-005: Control de Obra y Avances (50 SP estimados)

Opción 3: Enfoque Paralelo

• Equipo A: Implementa MAI-003
• Equipo B: Documenta MAI-004

---

📋 Documentos Pendientes

Ninguno - Épica 100% Completa ✅

---

Última Actualización: 2025-11-17 Responsable: Equipo de Producto Estado: ✅ LISTO PARA DESARROLLO