erp-construccion/docs/02-definicion-modulos/MAI-003-presupuestos-costos/_MAP.md

# _MAP: MAI-003 - Presupuestos y Control de Costos

**Epica:** MAI-003
**Nombre:** Presupuestos y Control de Costos
**Fase:** 1 - Alcance Inicial
**Presupuesto:** $30,000 MXN
**Story Points:** 46 SP
**Estado:** Completo
**Sprint:** Sprint 7-10 (Semanas 13-20)
**Ultima actualizacion:** 2025-11-17
**Prioridad:** P1

---

## Proposito

Sistema integral de presupuestos y control de costos para construccion que permite:
- Catalogo centralizado de 10,000+ conceptos reutilizables con APU (Analisis de Precios Unitarios)
- Presupuestos en 3 niveles (obra, etapa, prototipo) con generadores automaticos
- Control en tiempo real de costos con alertas proactivas
- Analisis de rentabilidad con simulaciones y proyecciones
- Explosion de insumos para optimizacion de compras
- Control presupuestal con desviaciones y planes de accion

**Problema que resuelve:** Las constructoras pierden entre 5-15% de margen por presupuestos imprecisos, falta de control sobre costos reales y desconocimiento de rentabilidad real por prototipo.

**Beneficios esperados:**
- Eficiencia: -80% tiempo elaboracion presupuestos (2h vs 10h)
- Precision: <3% desviacion presupuesto vs real
- Rentabilidad: +2 puntos de margen por mejor control
- Visibilidad: Dashboard actualizado en tiempo real

---

## Contenido

### Requerimientos Funcionales (4)

| ID | Archivo | Titulo | Estado |
|----|---------|--------|--------|
| RF-COST-001 | [RF-COST-001-catalogo-conceptos-precios.md](./requerimientos/RF-COST-001-catalogo-conceptos-precios.md) | Catalogo de Conceptos y Precios Unitarios | Completo |
| RF-COST-002 | [RF-COST-002-presupuestos-maestros.md](./requerimientos/RF-COST-002-presupuestos-maestros.md) | Presupuestos Maestros (Obra, Etapa, Prototipo) | Completo |
| RF-COST-003 | [RF-COST-003-control-costos-reales.md](./requerimientos/RF-COST-003-control-costos-reales.md) | Control de Costos Reales y Desviaciones | Completo |
| RF-COST-004 | [RF-COST-004-analisis-rentabilidad.md](./requerimientos/RF-COST-004-analisis-rentabilidad.md) | Analisis de Rentabilidad y Margenes | Completo |

### Especificaciones Tecnicas (4)

| ID | Archivo | Titulo | RF | Estado |
|----|---------|--------|-------|--------|
| ET-COST-001 | [ET-COST-001-implementacion-catalogo-conceptos.md](./especificaciones/ET-COST-001-implementacion-catalogo-conceptos.md) | Implementacion del Catalogo de Conceptos | RF-COST-001 | Completo |
| ET-COST-002 | [ET-COST-002-implementacion-presupuestos.md](./especificaciones/ET-COST-002-implementacion-presupuestos.md) | Implementacion de Presupuestos | RF-COST-002 | Completo |
| ET-COST-003 | [ET-COST-003-implementacion-control-costos.md](./especificaciones/ET-COST-003-implementacion-control-costos.md) | Implementacion de Control de Costos | RF-COST-003 | Completo |
| ET-COST-004 | [ET-COST-004-implementacion-analisis-rentabilidad.md](./especificaciones/ET-COST-004-implementacion-analisis-rentabilidad.md) | Implementacion de Analisis de Rentabilidad | RF-COST-004 | Completo |

### Historias de Usuario (8)

| ID | Archivo | Titulo | SP | Estado |
|----|---------|--------|----|--------|
| US-COST-001 | [US-COST-001-catalogo-conceptos.md](./historias-usuario/US-COST-001-catalogo-conceptos.md) | Catalogo de Conceptos y Busqueda | 5 | Completo |
| US-COST-002 | [US-COST-002-precios-compuestos.md](./historias-usuario/US-COST-002-precios-compuestos.md) | Precios Unitarios Compuestos | 5 | Completo |
| US-COST-003 | [US-COST-003-actualizacion-precios.md](./historias-usuario/US-COST-003-actualizacion-precios.md) | Actualizacion Masiva de Precios | 3 | Completo |
| US-COST-004 | [US-COST-004-presupuesto-obra.md](./historias-usuario/US-COST-004-presupuesto-obra.md) | Presupuesto de Obra Completo | 8 | Completo |
| US-COST-005 | [US-COST-005-presupuesto-prototipo.md](./historias-usuario/US-COST-005-presupuesto-prototipo.md) | Presupuesto de Prototipo con Generadores | 5 | Completo |
| US-COST-006 | [US-COST-006-dashboard-control-costos.md](./historias-usuario/US-COST-006-dashboard-control-costos.md) | Dashboard de Control de Costos Reales | 5 | Completo |
| US-COST-007 | [US-COST-007-analisis-desviaciones.md](./historias-usuario/US-COST-007-analisis-desviaciones.md) | Analisis de Desviaciones y Plan de Accion | 5 | Completo |
| US-COST-008 | [US-COST-008-analisis-rentabilidad.md](./historias-usuario/US-COST-008-analisis-rentabilidad.md) | Analisis de Rentabilidad y Simulaciones | 5 | Completo |

**Total Story Points:** 46 SP

### Implementacion

Inventarios de trazabilidad:
- [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml) - Matriz completa de trazabilidad
- [DATABASE.yml](./implementacion/DATABASE.yml) - Objetos de base de datos
- [BACKEND.yml](./implementacion/BACKEND.yml) - Modulos backend
- [FRONTEND.yml](./implementacion/FRONTEND.yml) - Componentes frontend

### Pruebas

Documentacion de testing:
- [TEST-PLAN.md](./pruebas/TEST-PLAN.md) - Plan de pruebas
- [TEST-CASES.md](./pruebas/TEST-CASES.md) - Casos de prueba

---

## Referencias

- **README:** [README.md](./README.md) - Descripcion detallada de la epica
- **RESUMEN:** [RESUMEN-EPICA-MAI-003.md](./RESUMEN-EPICA-MAI-003.md) - Resumen ejecutivo completo
- **Fase 1:** [../README.md](../README.md) - Informacion de la fase completa
- **Modulo relacionado MVP:** Modulo 3 - Presupuestos y Costos (MVP-APP.md)

---

## Metricas

| Metrica | Valor |
|---------|-------|
| **Presupuesto estimado** | $30,000 MXN |
| **Story Points estimados** | 46 SP |
| **Duracion estimada** | 16 dias (4 sprints x 2 semanas) |
| **Reutilizacion GAMILIT** | 5% (funcionalidad nueva) |
| **RF a implementar** | 4/4 |
| **ET a implementar** | 4/4 |
| **US a completar** | 8/8 |
| **Reduccion tiempo presupuestos** | 80% (2h vs 10h) |
| **Precision objetivo** | <3% desviacion presupuesto vs real |

---

## Modulos Afectados

### Base de Datos

- **Schema:** `budgets`
- **Tablas principales:**
  * `concept_catalog` - Catalogo de conceptos (materiales, mano de obra, maquinaria, compuestos)
  * `concept_components` - Componentes de conceptos compuestos (APU)
  * `concept_price_history` - Historial de precios
  * `regions` - Regiones para ajustes de precios
  * `budgets` - Presupuestos maestros (obra, etapa, prototipo)
  * `budget_items` - Partidas jerarquicas de presupuestos
  * `budget_versions` - Versionado de presupuestos
  * `actual_costs` - Costos reales registrados
  * `cost_variances` - Analisis de desviaciones
  * `cost_projections` - Proyecciones EAC
  * `profitability_analysis` - Analisis de rentabilidad por proyecto
  * `prototype_profitability` - Rentabilidad comparativa por prototipo
- **ENUMs:**
  * `concept_type` (material, labor, machinery, composite)
  * `budget_scope` (project, stage, prototype)
  * `budget_status` (draft, in_review, approved, baseline, closed)
  * `variance_type` (price, quantity, mixed)
  * `cost_classification` (direct, indirect, financing, overhead)
- **Funciones SQL:**
  * `calculate_composite_price()` - Calculo de PU compuestos
  * `calculate_variances()` - Analisis de desviaciones
  * `calculate_eac()` - Proyeccion de costo final (3 metodos)
  * `calculate_profitability()` - Analisis de rentabilidad

### Backend

- **Modulo:** `budgets`
- **Path:** `apps/backend/src/modules/budgets/`
- **Services:**
  * `ConceptCatalogService` - Gestion de catalogo de conceptos
  * `BudgetService` - Creacion y gestion de presupuestos
  * `CostControlService` - Control de costos reales
  * `ProfitabilityService` - Analisis de rentabilidad
  * `BudgetGeneratorService` - Generadores automaticos de volumetrias
  * `PriceUpdateService` - Actualizacion masiva de precios
- **Controllers:**
  * `ConceptCatalogController` (9 endpoints)
  * `BudgetController` (12 endpoints)
  * `CostControlController` (8 endpoints)
  * `ProfitabilityController` (6 endpoints)
- **Cron Jobs:**
  * `CostAnalysisTask.analyzeDailyCosts()` - Analisis diario 6:00 AM
  * `PriceIndexTask.updateNationalPrices()` - Actualizacion semestral INPC/CMIC
- **Middlewares:** BudgetAuthGuard, ProjectAccessGuard

### Frontend

- **Features:** `budgets`, `cost-control`, `profitability`
- **Path:** `apps/frontend/src/features/budgets/`
- **Componentes principales:**
  * `ConceptCatalogList` - Lista con busqueda y filtros
  * `ConceptForm` - Formulario de conceptos (simple/compuesto)
  * `APUEditor` - Editor de analisis de precios unitarios
  * `BudgetItemsTree` - Arbol jerarquico de partidas
  * `BudgetWizard` - Asistente de creacion de presupuestos
  * `VolumetryGenerator` - Generador automatico de volumetrias
  * `CurveSChart` - Grafica de curva S (Chart.js)
  * `CostDashboard` - Dashboard de control de costos
  * `VarianceAnalysis` - Analisis de desviaciones
  * `SensitivityMatrix` - Matriz de sensibilidad precio/costo
  * `ScenarioSimulator` - Simulador de escenarios
  * `PrototypeComparison` - Comparativa de rentabilidad por prototipo
- **Stores (Zustand):**
  * `useConceptCatalogStore`
  * `useBudgetStore`
  * `useCostControlStore`
  * `useProfitabilityStore`

---

## Flujo de Documentacion RF → ET → US → Codigo

### RF-COST-001: Catalogo de Conceptos y Precios Unitarios

```
RF-COST-001 (Requerimiento Funcional)
    ↓
ET-COST-001 (Especificacion Tecnica)
    ↓
├── US-COST-001: Catalogo de Conceptos y Busqueda (5 SP)
│   └── Codigo:
│       ├── DB: budgets.concept_catalog, budgets.regions
│       ├── Backend: ConceptCatalogService, ConceptCatalogController
│       └── Frontend: ConceptCatalogList, ConceptForm
│
├── US-COST-002: Precios Unitarios Compuestos (5 SP)
│   └── Codigo:
│       ├── DB: budgets.concept_components, calculate_composite_price()
│       ├── Backend: ConceptCatalogService.createComposite()
│       └── Frontend: APUEditor, ConceptForm
│
└── US-COST-003: Actualizacion Masiva de Precios (3 SP)
    └── Codigo:
        ├── DB: budgets.concept_price_history
        ├── Backend: PriceUpdateService, PriceIndexTask (cron)
        └── Frontend: PriceUpdateModal, PriceHistoryTimeline
```

### RF-COST-002: Presupuestos Maestros

```
RF-COST-002 (Requerimiento Funcional)
    ↓
ET-COST-002 (Especificacion Tecnica)
    ↓
├── US-COST-004: Presupuesto de Obra Completo (8 SP)
│   └── Codigo:
│       ├── DB: budgets.budgets, budgets.budget_items, budgets.budget_versions
│       ├── Backend: BudgetService, BudgetController
│       └── Frontend: BudgetWizard, BudgetItemsTree, BudgetDetail
│
└── US-COST-005: Presupuesto de Prototipo con Generadores (5 SP)
    └── Codigo:
        ├── DB: budgets.budget_items (con formulas)
        ├── Backend: BudgetGeneratorService
        └── Frontend: VolumetryGenerator, PrototypeBudgetForm
```

### RF-COST-003: Control de Costos Reales

```
RF-COST-003 (Requerimiento Funcional)
    ↓
ET-COST-003 (Especificacion Tecnica)
    ↓
├── US-COST-006: Dashboard de Control de Costos Reales (5 SP)
│   └── Codigo:
│       ├── DB: budgets.actual_costs, calculate_variances()
│       ├── Backend: CostControlService, CostAnalysisTask (cron)
│       └── Frontend: CostDashboard, CurveSChart
│
└── US-COST-007: Analisis de Desviaciones y Plan de Accion (5 SP)
    └── Codigo:
        ├── DB: budgets.cost_variances, budgets.cost_projections
        ├── Backend: CostControlService.analyzeVariances()
        └── Frontend: VarianceAnalysis, ActionPlanForm
```

### RF-COST-004: Analisis de Rentabilidad

```
RF-COST-004 (Requerimiento Funcional)
    ↓
ET-COST-004 (Especificacion Tecnica)
    ↓
└── US-COST-008: Analisis de Rentabilidad y Simulaciones (5 SP)
    └── Codigo:
        ├── DB: budgets.profitability_analysis, budgets.prototype_profitability
        ├── Backend: ProfitabilityService, ProfitabilityController
        └── Frontend: SensitivityMatrix, ScenarioSimulator, PrototypeComparison
```

---

## Quick Links

### Catalogo de Conceptos

**Objetivo:** Catalogo centralizado de 10,000+ conceptos reutilizables

- **RF:** [RF-COST-001](./requerimientos/RF-COST-001-catalogo-conceptos-precios.md)
- **ET:** [ET-COST-001](./especificaciones/ET-COST-001-implementacion-catalogo-conceptos.md)
- **US:**
  * [US-COST-001: Catalogo base](./historias-usuario/US-COST-001-catalogo-conceptos.md)
  * [US-COST-002: Conceptos compuestos (APU)](./historias-usuario/US-COST-002-precios-compuestos.md)
  * [US-COST-003: Actualizacion masiva](./historias-usuario/US-COST-003-actualizacion-precios.md)
- **Codigo:**
  * DB: `budgets.concept_catalog`, `budgets.concept_components`
  * Backend: `ConceptCatalogService`
  * Frontend: `ConceptCatalogList`, `APUEditor`

**Funcionalidades clave:**
- 4 tipos de conceptos: material, mano de obra, maquinaria, compuesto
- Analisis de Precios Unitarios (APU) detallado
- Busqueda full-text por codigo/nombre/categoria (<200ms)
- Versionado y historial de precios
- Regionalizacion de precios
- Importacion/exportacion Excel, OPUS, Neodata
- Actualizacion masiva por indices INPC/CMIC

**Ejemplo APU:**
```
Concepto Compuesto "Cimentacion 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
```

### Analisis de Precios Unitarios (APU)

**Objetivo:** Desglose detallado de componentes de conceptos compuestos

- **RF:** [RF-COST-001, seccion APU](./requerimientos/RF-COST-001-catalogo-conceptos-precios.md#analisis-de-precios-unitarios-apu)
- **ET:** [ET-COST-001, seccion APU](./especificaciones/ET-COST-001-implementacion-catalogo-conceptos.md#calculo-de-precios-compuestos)
- **US:** [US-COST-002](./historias-usuario/US-COST-002-precios-compuestos.md)
- **Codigo:**
  * DB: `budgets.concept_components`, funcion `calculate_composite_price()`
  * Backend: `ConceptCatalogService.createComposite()`
  * Frontend: `APUEditor`

**Componentes de un APU:**
1. **Costo Directo (CD):**
   - Materiales
   - Mano de obra (con FSR: Factor de Salario Real)
   - Maquinaria y equipo
2. **Costos Indirectos:** 12% sobre CD
3. **Financiamiento:** 3% sobre (CD + Indirectos)
4. **Utilidad:** 10% sobre subtotal
5. **Cargos adicionales:** 2% sobre subtotal
6. **IVA:** 16% sobre precio final

**Formula de calculo:**
```
CD = Materiales + Mano de Obra + Maquinaria
Indirectos = CD * 0.12
Financiamiento = (CD + Indirectos) * 0.03
Subtotal = CD + Indirectos + Financiamiento
Utilidad = Subtotal * 0.10
Cargos = Subtotal * 0.02
PU sin IVA = Subtotal + Utilidad + Cargos
PU con IVA = PU sin IVA * 1.16
```

### Explosion de Insumos

**Objetivo:** Desglose de todos los insumos necesarios para el proyecto

- **RF:** [RF-COST-002, seccion Explosion](./requerimientos/RF-COST-002-presupuestos-maestros.md#explosion-de-insumos)
- **ET:** [ET-COST-002](./especificaciones/ET-COST-002-implementacion-presupuestos.md)
- **US:** [US-COST-004](./historias-usuario/US-COST-004-presupuesto-obra.md)
- **Codigo:**
  * DB: Vista materializada `budgets.budget_materials_explosion`
  * Backend: `BudgetService.explodeMaterials()`
  * Frontend: `MaterialsExplosionTable`

**Funcionalidades:**
- Desglose automatico de materiales desde conceptos compuestos
- Agregacion por tipo de material
- Cantidad total necesaria por proyecto/etapa
- Valor total por material
- Exportacion a Excel para compras
- Optimizacion de lotes de compra

**Ejemplo:**
```
Proyecto: 150 viviendas
└─ Cimentacion (150 viviendas × 14.40 m³/viv = 2,160 m³)
    ├─ Concreto f'c=150: 2,160 m³ × 1.05 = 2,268 m³
    ├─ Acero fy=4200: 2,160 m³ × 80 kg/m³ = 172,800 kg
    ├─ Cimbra: 2,160 m³ × 5.2 m²/m³ = 11,232 m²
    └─ Alambre recocido: 2,160 m³ × 1.5 kg/m³ = 3,240 kg

Total Materiales Cimentacion: $9,826,560
```

### Control Presupuestal

**Objetivo:** Control en tiempo real de costos vs presupuesto

- **RF:** [RF-COST-003](./requerimientos/RF-COST-003-control-costos-reales.md)
- **ET:** [ET-COST-003](./especificaciones/ET-COST-003-implementacion-control-costos.md)
- **US:**
  * [US-COST-006: Dashboard control](./historias-usuario/US-COST-006-dashboard-control-costos.md)
  * [US-COST-007: Analisis desviaciones](./historias-usuario/US-COST-007-analisis-desviaciones.md)
- **Codigo:**
  * DB: `budgets.actual_costs`, `budgets.cost_variances`, `budgets.cost_projections`
  * Backend: `CostControlService`, `CostAnalysisTask` (cron diario 6:00 AM)
  * Frontend: `CostDashboard`, `CurveSChart`, `VarianceAnalysis`

**Indicadores clave:**
- **CPI (Cost Performance Index):** Valor Ganado / Costo Real
  * CPI > 1.0: Bajo presupuesto
  * CPI = 1.0: En presupuesto
  * CPI < 1.0: Sobre presupuesto
- **SPI (Schedule Performance Index):** Valor Ganado / Valor Planificado
  * SPI > 1.0: Adelantado
  * SPI = 1.0: A tiempo
  * SPI < 1.0: Retrasado
- **EAC (Estimate at Completion):** Proyeccion de costo final
  * Metodo 1: Presupuesto / CPI
  * Metodo 2: Costo Real + (Presupuesto - Valor Ganado)
  * Metodo 3: Costo Real + ((Presupuesto - Valor Ganado) / (CPI × SPI))

**Tipos de desviacion:**
1. **Desviacion de precio:** (Precio Real - Precio Presupuestado) × Cantidad Real
2. **Desviacion de cantidad:** (Cantidad Real - Cantidad Presupuestada) × Precio Presupuestado
3. **Desviacion mixta:** (Precio Real - Precio Presupuestado) × (Cantidad Real - Cantidad Presupuestada)

**Alertas automaticas:**
- Alerta amarilla: Desviacion >3%
- Alerta roja: Desviacion >5%
- Plan de accion obligatorio para desviaciones >5%

### Presupuestos por Nivel

**Objetivo:** Presupuestos en 3 niveles jerarquicos

- **RF:** [RF-COST-002](./requerimientos/RF-COST-002-presupuestos-maestros.md)
- **ET:** [ET-COST-002](./especificaciones/ET-COST-002-implementacion-presupuestos.md)
- **US:**
  * [US-COST-004: Presupuesto obra](./historias-usuario/US-COST-004-presupuesto-obra.md)
  * [US-COST-005: Presupuesto prototipo](./historias-usuario/US-COST-005-presupuesto-prototipo.md)
- **Codigo:**
  * DB: `budgets.budgets`, `budgets.budget_items`
  * Backend: `BudgetService`, `BudgetGeneratorService`
  * Frontend: `BudgetWizard`, `BudgetItemsTree`

**Niveles de presupuesto:**

1. **Presupuesto de Obra:**
   - Presupuesto maestro completo del proyecto
   - Desglose por division CMIC (16 capitulos)
   - Suma de todos los prototipos × cantidades
   - Curva S de distribucion temporal
   - Versionado completo (baseline, ajustes)

2. **Presupuesto de Etapa:**
   - Presupuesto por fase constructiva
   - Ej: Cimentacion, Estructura, Albañileria, Instalaciones, Acabados
   - Se vincula con cronograma de obra
   - Permite control por avance fisico

3. **Presupuesto de Prototipo:**
   - Costo unitario por tipo de vivienda
   - Generadores automaticos de volumetrias
   - Plantilla reutilizable
   - Base para calculo de presupuesto de obra

**Ejemplo jerarquia:**
```
Proyecto: Conjunto 150 viviendas
├─ Prototipo A (80 viviendas): $1,105,000 c/u
│   ├─ Cimentacion: $65,472
│   ├─ Estructura: $220,500
│   ├─ Albañileria: $198,450
│   └─ ...
├─ Prototipo B (50 viviendas): $890,000 c/u
└─ Prototipo C (20 viviendas): $750,000 c/u

Presupuesto Obra Total: $165,750,000
```

### Analisis de Rentabilidad

**Objetivo:** Analisis financiero y simulaciones de escenarios

- **RF:** [RF-COST-004](./requerimientos/RF-COST-004-analisis-rentabilidad.md)
- **ET:** [ET-COST-004](./especificaciones/ET-COST-004-implementacion-analisis-rentabilidad.md)
- **US:** [US-COST-008](./historias-usuario/US-COST-008-analisis-rentabilidad.md)
- **Codigo:**
  * DB: `budgets.profitability_analysis`, `budgets.prototype_profitability`
  * Backend: `ProfitabilityService`
  * Frontend: `SensitivityMatrix`, `ScenarioSimulator`, `PrototypeComparison`

**Analisis incluidos:**
1. **Analisis financiero por proyecto:**
   - Ingresos totales
   - Costos totales (directos + indirectos)
   - Margen bruto y neto
   - ROI (Return on Investment)
   - TIR (Tasa Interna de Retorno)

2. **Punto de equilibrio:**
   - Numero de unidades para cubrir costos fijos
   - Margen de seguridad
   - Grafica visual

3. **Rentabilidad por prototipo:**
   - Comparacion de margenes entre prototipos
   - Identificacion de prototipos mas rentables
   - Optimizacion de mix de producto

4. **Simulador de escenarios:**
   - Escenario optimista: Costos -5%, Precio +3%
   - Escenario base: Valores actuales
   - Escenario pesimista: Costos +8%, Precio -2%
   - Impacto en margen y rentabilidad

5. **Matriz de sensibilidad:**
   - Impacto de variacion de precio (±10%)
   - Impacto de variacion de costos (±10%)
   - Mapa de calor de rentabilidad

**Ejemplo analisis:**
```
Proyecto: 150 viviendas
Ingresos: $165.75M (150 × $1,105,000 promedio)
Costos: $153.70M
Margen: $12.05M (7.3%)
ROI: 7.8%
TIR: 12.4%

Punto de Equilibrio:
- Unidades: 110 viviendas (73%)
- Margen de seguridad: 27% ✓

Rentabilidad por prototipo:
- Prototipo A: 8.2% margen
- Prototipo B: 7.1% margen
- Prototipo C: 5.8% margen
```

---

## Flujo de Trabajo Completo

### 1. Setup Inicial (Sprint 7)

**Paso 1: Crear catalogo de conceptos**
- Importar catalogo base (OPUS/Neodata/Excel)
- Crear conceptos personalizados
- Definir APU de conceptos compuestos
- Configurar regionalizacion de precios

**Paso 2: Configurar parametros**
- Definir % indirectos (default: 12%)
- Definir % financiamiento (default: 3%)
- Definir % utilidad esperada (default: 10%)
- Definir % cargos adicionales (default: 2%)

### 2. Presupuesto de Prototipo (Sprint 8)

**Paso 1: Crear prototipo en MAI-002**
- Definir caracteristicas: area, perimetro, altura, etc.
- Asignar tipo de vivienda

**Paso 2: Generar presupuesto con generadores**
- Seleccionar plantilla de prototipo
- Ejecutar generadores automaticos de volumetrias
- Revisar y ajustar cantidades
- Aprobar presupuesto de prototipo

**Ejemplo generador:**
```javascript
// Excavacion para cimentacion
formula: "desplantDepth * buildingPerimeter * 0.60 * 0.80"
inputs: {
  desplantDepth: 0.80m,
  buildingPerimeter: 30m
}
result: 14.40 m³
```

### 3. Presupuesto de Obra (Sprint 8)

**Paso 1: Crear presupuesto maestro**
- Seleccionar proyecto
- Asignar prototipos y cantidades
- Generar presupuesto automaticamente

**Paso 2: Crear baseline**
- Revisar presupuesto generado
- Ajustar si es necesario
- Aprobar como baseline

**Paso 3: Gestionar versiones**
- Crear nueva version por cambios de alcance
- Comparar versiones
- Mantener historial completo

### 4. Control de Costos (Sprint 9)

**Paso 1: Registro automatico de costos reales**
- Desde ordenes de compra (MAI-004)
- Desde nomina (MAI-007)
- Desde subcontratos (MAI-012)

**Paso 2: Analisis diario (cron 6:00 AM)**
- Calcular desviaciones
- Actualizar proyecciones EAC
- Generar alertas

**Paso 3: Gestion de desviaciones**
- Revisar dashboard de control
- Analizar desviaciones >5%
- Crear plan de accion obligatorio
- Dar seguimiento

### 5. Analisis de Rentabilidad (Sprint 10)

**Paso 1: Dashboard de rentabilidad**
- Ver margen actual vs objetivo
- Comparar prototipos
- Analizar tendencias

**Paso 2: Simulaciones**
- Ejecutar escenarios optimista/base/pesimista
- Analizar matriz de sensibilidad
- Tomar decisiones informadas

**Paso 3: Reportes ejecutivos**
- Generar reporte financiero
- Exportar a Excel/PDF
- Presentar a direccion

---

## Integraciones

### Modulos que Consume (Input)

- **MAI-002 (Proyectos):**
  - Estructura de proyectos/etapas
  - Prototipos de vivienda y caracteristicas
  - Datos para generadores de volumetrias
- **MAI-004 (Compras):**
  - Ordenes de compra → Costos reales de materiales
  - Precios reales de proveedores
- **MAI-007 (RR.HH.):**
  - Nomina → Costos reales de mano de obra
  - Factores de salario real (FSR)
- **MAI-012 (Contratos):**
  - Subcontratos → Costos reales de subcontratistas
- **MGN-005 (Catalogos):**
  - Unidades de medida
  - Clasificaciones CMIC

### Modulos que Alimenta (Output)

- **MAI-002 (Proyectos):**
  - Costo unitario por prototipo
  - Presupuesto total del proyecto
- **MAI-004 (Compras):**
  - Explosion de insumos
  - Presupuesto de materiales
  - Alertas de precios fuera de presupuesto
- **MAI-005 (Control de Obra):**
  - Presupuesto por partida
  - Valor ganado por avance
- **MAI-008 (Estimaciones):**
  - Montos presupuestados por concepto
  - Volumetrias para estimaciones
- **MAE-014 (Finanzas):**
  - Datos de rentabilidad
  - Proyecciones de costos
  - Indicadores financieros (CPI, SPI, EAC)
- **MAI-009 (Reportes):**
  - Analisis de desviaciones
  - Curva S
  - Reportes de rentabilidad

---

## Puntos Criticos

1. **Precision de APU:**
   - APU mal calculados → Presupuestos imprecisos → Perdida de margen
   - Validar todos los componentes (materiales, MO, maquinaria)
   - Considerar desperdicios y factores de abundamiento

2. **Actualizacion de precios:**
   - Precios desactualizados → Desviaciones no detectadas
   - Actualizar catalogo cada 6 meses (minimo)
   - Usar indices INPC/CMIC para ajustes

3. **Registro oportuno de costos:**
   - Retrasos en registro → Dashboard no refleja realidad
   - Integracion automatica desde compras/nomina/subcontratos
   - Validacion diaria

4. **Gestion de desviaciones:**
   - Desviaciones no atendidas → Problemas mayores
   - Plan de accion obligatorio para >5%
   - Seguimiento semanal

5. **Versionado de presupuestos:**
   - Cambios sin control → Perdida de baseline
   - Siempre crear nueva version (no editar aprobados)
   - Documentar razon de cambio

---

## Casos de Uso Reales

### Caso 1: Constructora con Desarrollo de 150 Viviendas

**Contexto:**
- 3 prototipos: A (80 unidades), B (50 unidades), C (20 unidades)
- Precio venta promedio: $1,105,000
- Ingresos totales: $165.75M

**Flujo completo:**

1. **Setup inicial (Semana 1):**
   - Importar catalogo OPUS con 5,000 conceptos
   - Crear 150 conceptos personalizados
   - Configurar 3 regiones de precios
   - Tiempo: 8 horas (vs 20 horas manual)

2. **Presupuesto prototipos (Semana 2):**
   - Prototipo A: 247 partidas, $1,105,000, 2 horas
   - Prototipo B: 223 partidas, $890,000, 1.5 horas
   - Prototipo C: 198 partidas, $750,000, 1.5 horas
   - Tiempo total: 5 horas (vs 30 horas manual)

3. **Presupuesto obra (Semana 2):**
   - Generacion automatica desde prototipos
   - 658 partidas totales
   - Presupuesto: $153.7M
   - Tiempo: 30 minutos (vs 10 horas manual)

4. **Control mensual (Meses 1-18):**
   - Dashboard actualizado diariamente
   - 3 alertas criticas detectadas y resueltas
   - Desviacion final: 2.1% (excelente)

5. **Resultado final:**
   - Costo real: $155.9M
   - Margen real: 6.0% (vs 7.3% objetivo)
   - Razon: Cambio de alcance no presupuestado
   - Sin sistema: Margen hubiera sido 3.5% (perdida $6M)

### Caso 2: Actualizacion Semestral de Precios

**Contexto:**
- Catalogo de 2,000 conceptos
- INPC semestre: +3.2%
- CMIC construccion: +4.8%

**Proceso:**
1. Seleccionar conceptos a actualizar (1,500 usan indices)
2. Aplicar incremento diferenciado:
   - Materiales: +4.8%
   - Mano de obra: +3.2%
   - Maquinaria: +3.5%
3. Recalculo automatico de APU compuestos
4. Generar reporte de cambios
5. Tiempo total: 15 minutos (vs 8 horas manual)

### Caso 3: Deteccion y Correccion de Desviacion

**Contexto:**
- Partida "Estructura de concreto": $2.5M presupuestado
- Semana 8: Costo real $1.8M, Avance 60%
- Proyeccion EAC: $3.0M (desviacion +20%)

**Alerta generada:**
- Tipo: Critica (desviacion >5%)
- CPI: 0.83 (bajo presupuesto)
- SPI: 1.05 (adelantado en programa)

**Accion tomada:**
- Analisis: Precio de acero +15% vs presupuesto
- Plan: Negociar con proveedor, buscar alternativas
- Resultado: Descuento 8%, desviacion final +5%

**Ahorro:** $375K por deteccion temprana

---

## Criterios de Exito

### Metricas de Adopcion
- 100% de proyectos con presupuesto formal
- 90% de presupuestos usan catalogo estandar
- <5% de conceptos duplicados en catalogo

### Metricas de Eficiencia
- Reduccion 80% tiempo de elaboracion (-8h por presupuesto)
- Busqueda de conceptos <200ms
- Actualizacion masiva de precios <5 seg para 500 conceptos
- Generacion de presupuesto <2 seg para 100 partidas

### Metricas de Calidad
- Precision presupuesto vs real <3% de desviacion
- 100% de alertas criticas con plan de accion en 48h
- Proyeccion EAC vs costo final <2% de error

### Metricas de Rentabilidad
- 80% de proyectos con margen ≥ target
- Incremento de margen promedio +2 puntos anuales
- ROI portafolio ≥ 12% anual

---

## Distribucion de Sprints

### Sprint 7 (2 semanas) - 13 SP: Catalogo de Conceptos
- US-COST-001: Catalogo de Conceptos y Busqueda (5 SP)
- US-COST-002: Precios Unitarios Compuestos (5 SP)
- US-COST-003: Actualizacion Masiva de Precios (3 SP)

**Entregables:**
- Catalogo de conceptos funcionando
- CRUD completo con busqueda
- Editor de APU
- Importacion/exportacion Excel

### Sprint 8 (2 semanas) - 13 SP: Presupuestos
- US-COST-004: Presupuesto de Obra Completo (8 SP)
- US-COST-005: Presupuesto de Prototipo con Generadores (5 SP)

**Entregables:**
- Wizard de creacion de presupuestos
- Generadores automaticos de volumetrias
- Arbol jerarquico de partidas
- Versionado de presupuestos
- Explosion de insumos

### Sprint 9 (2 semanas) - 10 SP: Control de Costos
- US-COST-006: Dashboard de Control de Costos Reales (5 SP)
- US-COST-007: Analisis de Desviaciones y Plan de Accion (5 SP)

**Entregables:**
- Dashboard con curva S
- Integracion con compras/nomina/subcontratos
- Calculo automatico de desviaciones
- Sistema de alertas
- Gestion de planes de accion

### Sprint 10 (2 semanas) - 5 SP: Rentabilidad
- US-COST-008: Analisis de Rentabilidad y Simulaciones (5 SP)

**Entregables:**
- Analisis financiero por proyecto
- Comparacion de prototipos
- Simulador de escenarios
- Matriz de sensibilidad
- Punto de equilibrio visual

**Duracion total:** 8 semanas (4 sprints × 2 semanas)

---

## Siguiente Paso

Comenzar implementacion en Sprint 7 con la documentacion completa.

Equipo de desarrollo puede iniciar con:
1. Setup de schema `budgets` en base de datos
2. Implementacion de `ConceptCatalogService`
3. Componente `ConceptCatalogList` en frontend

---

**Generado:** 2025-11-17
**Mantenedores:** @tech-lead @backend-team @frontend-team @database-team
**Estado:** Completo