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

# MAI-003: Presupuestos y Control de Costos

**ID:** MAI-003
**Fase:** 1 - Alcance Inicial
**Presupuesto:** $30,000 MXN
**Story Points:** 46 SP
**Sprint:** Sprint 7-10 (Semanas 13-20)
**Prioridad:** P1
**Estado:** En documentacion

---

## Resumen Ejecutivo

Este modulo gestiona el ciclo completo de presupuestos de construccion, desde el catalogo de conceptos base hasta el control de costos reales y analisis de rentabilidad. Incluye gestion de Analisis de Precios Unitarios (APU), explosion de insumos, presupuestos multinivel (obra, etapa, prototipo), control presupuestal con curva S, y analisis de desviaciones con proyecciones.

### Problema que Resuelve

Las constructoras **pierden entre 5-15% de margen** debido a:
- Presupuestos desactualizados o imprecisos elaborados en Excel
- Falta de control sobre costos reales vs presupuestados
- Desconocimiento de rentabilidad real por prototipo/proyecto
- Reaccion tardia ante desviaciones de costos
- Dificultad para reutilizar conceptos y precios entre proyectos
- Analisis de precios unitarios manuales propensos a errores

**Sin este modulo:** Elaboracion manual en Excel (8-10 horas por presupuesto), errores de calculo, imposibilidad de controlar costos en tiempo real, perdida de margen por desviaciones no detectadas.

**Con este modulo:** Catalogo centralizado de 10,000+ conceptos reutilizables, presupuestos generados en 2 horas con precision <3%, control de costos en tiempo real, alertas proactivas de desviaciones, +2 puntos de margen por mejor control.

---

## Objetivos

1. **Catalogar conceptos** reutilizables con APU detallados por especialidad
2. **Generar presupuestos** rapidos y precisos en 3 niveles (obra, etapa, prototipo)
3. **Controlar costos reales** vs presupuestados con curva S y alertas automaticas
4. **Analizar rentabilidad** por proyecto/prototipo con simulaciones de escenarios
5. **Visibilidad total** del estado financiero del portafolio de proyectos

---

## Alcance Funcional

### 1. Catalogo de Conceptos y Precios Unitarios

**Catlogo maestro de conceptos reutilizables:**
- 4 tipos de conceptos: Material, Mano de Obra, Maquinaria, Compuesto
- Organizacion jerarquica por division CMIC (16 capitulos estandar)
- Analisis de Precio Unitario (APU) detallado para conceptos compuestos
- Versionado y historial de precios con trazabilidad
- Regionalizacion de precios por zona geografica
- Importacion/exportacion desde/hacia Excel, OPUS, Neodata

**Analisis de Precios Unitarios (APU):**
- Explosion de insumos: materiales + mano de obra + maquinaria
- Factor de Salario Real (FSR) para mano de obra
- Cargos por indirectos (12%), financiamiento (3%), utilidad (10%)
- Calculo automatico de Precio Unitario (PU) final

**Ejemplo de concepto compuesto:**
```
Concepto: "Cimentacion corrida de concreto f'c=200 kg/cm2"
├─ Materiales:
│  ├─ Concreto premezclado f'c=200: 1.05 m3 × $1,850 = $1,943
│  ├─ Acero de refuerzo 3/8": 25 kg × $18 = $450
│  ├─ Cimbra de madera: 6 m2 × $125 = $750
│  └─ Alambre recocido: 0.5 kg × $25 = $13
│  Subtotal Materiales: $3,156
│
├─ Mano de Obra:
│  ├─ Oficial albanil: 0.8 jornadas × $450 = $360
│  ├─ Ayudante general: 1.6 jornadas × $280 = $448
│  ├─ FSR (1.65×): $808 × 1.65 = $1,333
│  Subtotal Mano de Obra: $1,333
│
├─ Maquinaria:
│  ├─ Vibrador de concreto: 2 hrs × $80 = $160
│  ├─ Herramienta menor (3%): $3,156 × 3% = $95
│  Subtotal Maquinaria: $255
│
├─ Costo Directo (CD): $4,744
├─ Indirectos (12%): $569
├─ Financiamiento (3%): $142
├─ Utilidad (10%): $474
├─ Cargos adicionales (2%): $95
│
└─ Precio Unitario Final: $6,024/m3 + IVA
```

### 2. Presupuestos Maestros (Obra, Etapa, Prototipo)

**Presupuesto de Obra:**
- Desglose completo por capitulos CMIC
- Volumetrias totales del proyecto
- Distribucion temporal (Curva S)
- Versionado completo (baseline, ajustes, cambios de alcance)

**Presupuesto de Etapa:**
- Subdivision por fases constructivas
- Programacion de recursos por etapa
- Validacion de suma = presupuesto de obra

**Presupuesto de Prototipo:**
- Presupuesto detallado por modelo de vivienda
- Generadores automaticos basados en caracteristicas:
  - Superficie de construccion
  - Perimetro de desplante
  - Numero de niveles
  - Tipo de acabados
- Explosion de insumos por prototipo
- Costo unitario por m2 de construccion

**Ejemplo de generador automatico:**
```javascript
// Excavacion para cimentacion
formula: "desplantDepth * buildingPerimeter * 0.60 * 0.80"
inputs: {
  desplantDepth: 0.80m,      // Profundidad de desplante
  buildingPerimeter: 30m,    // Perimetro de construccion
  widthFactor: 0.60m,        // Ancho de cepa
  wasteFactorr: 0.80         // Factor de abundamiento
}
result: 14.40 m3 de excavacion
```

### 3. Control de Costos Reales y Desviaciones

**Registro automatico de costos reales:**
- Integracion con modulo de Compras (MAI-004) - materiales
- Integracion con modulo de Nomina (MAI-007) - mano de obra
- Integracion con modulo de Subcontratos (MAI-012) - subcontratistas
- Registro manual de otros costos

**Dashboard de control con Curva S:**
- Costo Presupuestado (baseline)
- Costo Real acumulado
- Valor Ganado (Earned Value)
- Proyeccion de costo final (EAC)

**Analisis de desviaciones:**
- Desviacion en precio: (Precio Real - Precio Presupuestado) × Cantidad Real
- Desviacion en cantidad: (Cantidad Real - Cantidad Presupuestada) × Precio Presupuestado
- Desviacion mixta: (Precio Real - Precio Presupuestado) × (Cantidad Real - Cantidad Presupuestada)

**Indicadores de desempeno:**
```
CPI (Cost Performance Index) = Valor Ganado / Costo Real
  CPI > 1.0: Proyecto bajo presupuesto
  CPI < 1.0: Proyecto sobre presupuesto

SPI (Schedule Performance Index) = Valor Ganado / Valor Planificado
  SPI > 1.0: Proyecto adelantado
  SPI < 1.0: Proyecto retrasado

EAC (Estimate at Completion) = Presupuesto / CPI
  Proyeccion de costo final del proyecto
```

**Alertas automaticas configurables:**
- Desviacion >5% en capitulo especifico
- Desviacion >3% en presupuesto total
- Proyeccion EAC excede presupuesto autorizado
- Plan de accion obligatorio para desviaciones >5%

### 4. Analisis de Rentabilidad y Margenes

**Analisis financiero por proyecto:**
- Ingresos totales (precio de venta × unidades)
- Costos totales (presupuesto + desviaciones)
- Margen bruto y margen neto
- Punto de equilibrio (unidades minimas a vender)
- Margen de seguridad

**Comparacion de rentabilidad por prototipo:**
- Costo unitario por m2
- Precio de venta por m2
- Margen por prototipo
- Rentabilidad relativa entre modelos

**Simulador de escenarios:**
- Escenario optimista (-5% costos, +3% precio)
- Escenario base (valores actuales)
- Escenario pesimista (+8% costos, -2% precio)

**Matriz de sensibilidad:**
- Impacto de variaciones de precio de venta (-10% a +10%)
- Impacto de variaciones de costo (-10% a +10%)
- Mapa de calor de rentabilidad

**Ejemplo de analisis:**
```
Proyecto: Residencial Los Pinos (150 viviendas)
Ingresos: $165.75M (150 × $1.105M)
Costos: $153.70M
Margen Bruto: $12.05M (7.3%)
Punto de Equilibrio: 110 viviendas (73%)
Margen de Seguridad: 27%
Resultado: Proyecto viable con margen saludable
```

---

## Reutilizacion del Core ERP (30%)

Este modulo aprovecha la infraestructura del ERP Core:

| Componente Core | Uso en MAI-003 | % Reutilizacion |
|-----------------|----------------|-----------------|
| **MGN-001 (Usuarios)** | Gestion de usuarios con permisos | 100% |
| **MGN-002 (RBAC)** | Roles: Presupuestista, Director de Costos, Analista | 100% |
| **MGN-003 (Multi-tenant)** | Aislamiento de catalogos por constructora | 100% |
| **MGN-005 (Catalogos)** | Base para catalogo de conceptos | 70% |
| **MGN-007 (Auditoria)** | Trazabilidad de cambios en precios y presupuestos | 100% |
| **MGN-008 (Notificaciones)** | Alertas de desviaciones criticas | 100% |

**Total estimado de reutilizacion:** 30% del codigo proviene del core, 70% es especifico del modulo.

---

## Lista de Requerimientos Funcionales

### Requerimientos Funcionales (4)

1. **[RF-COST-001: Catalogo de Conceptos y Precios Unitarios](./requerimientos/RF-COST-001-catalogo-conceptos-precios.md)**
   - Catalogo maestro de conceptos (material, mano de obra, maquinaria, compuesto)
   - Analisis de Precios Unitarios (APU) detallado
   - Versionado y historial de precios
   - Regionalizacion de precios
   - Importacion/exportacion Excel, OPUS, Neodata

2. **[RF-COST-002: Presupuestos Maestros (Obra, Etapa, Prototipo)](./requerimientos/RF-COST-002-presupuestos-maestros.md)**
   - Presupuesto de obra con desglose CMIC
   - Presupuesto de etapa por fase constructiva
   - Presupuesto de prototipo con generadores automaticos
   - Versionado completo (baseline, ajustes, cambios)
   - Curva S y distribucion temporal

3. **[RF-COST-003: Control de Costos Reales y Desviaciones](./requerimientos/RF-COST-003-control-costos-reales.md)**
   - Registro automatico desde compras, nomina, subcontratos
   - Dashboard con curva S
   - Calculo de desviaciones (precio, cantidad, mixta)
   - Proyecciones EAC (3 metodos)
   - Alertas automaticas y planes de accion

4. **[RF-COST-004: Analisis de Rentabilidad y Margenes](./requerimientos/RF-COST-004-analisis-rentabilidad.md)**
   - Analisis financiero por proyecto
   - Comparacion de rentabilidad por prototipo
   - Punto de equilibrio y margen de seguridad
   - Simulador de escenarios
   - Matriz de sensibilidad

### Especificaciones Tecnicas (4)

1. **[ET-COST-001: Implementacion del Catalogo de Conceptos](./especificaciones/ET-COST-001-implementacion-catalogo.md)**
2. **[ET-COST-002: Implementacion de Presupuestos](./especificaciones/ET-COST-002-implementacion-presupuestos.md)**
3. **[ET-COST-003: Implementacion de Control de Costos](./especificaciones/ET-COST-003-implementacion-control-costos.md)**
4. **[ET-COST-004: Implementacion de Analisis de Rentabilidad](./especificaciones/ET-COST-004-implementacion-rentabilidad.md)**

### Historias de Usuario (8)

**Sprint 7 (13 SP):**
- [US-COST-001: Catalogo de Conceptos y Busqueda](./historias-usuario/US-COST-001-catalogo-conceptos.md) - 5 SP
- [US-COST-002: Precios Unitarios Compuestos](./historias-usuario/US-COST-002-precios-compuestos.md) - 5 SP
- [US-COST-003: Actualizacion Masiva de Precios](./historias-usuario/US-COST-003-actualizacion-precios.md) - 3 SP

**Sprint 8 (13 SP):**
- [US-COST-004: Presupuesto de Obra Completo](./historias-usuario/US-COST-004-presupuesto-obra.md) - 8 SP
- [US-COST-005: Presupuesto de Prototipo con Generadores](./historias-usuario/US-COST-005-presupuesto-prototipo.md) - 5 SP

**Sprint 9 (10 SP):**
- [US-COST-006: Dashboard de Control de Costos Reales](./historias-usuario/US-COST-006-dashboard-control.md) - 5 SP
- [US-COST-007: Analisis de Desviaciones y Plan de Accion](./historias-usuario/US-COST-007-analisis-desviaciones.md) - 5 SP

**Sprint 10 (5 SP):**
- [US-COST-008: Analisis de Rentabilidad y Simulaciones](./historias-usuario/US-COST-008-analisis-rentabilidad.md) - 5 SP

---

## Dependencias con Otros Modulos

### Modulos que MAI-003 Consume (Input)

| Modulo | Relacion | Datos Compartidos |
|--------|----------|-------------------|
| **MAI-001 (Fundamentos)** | Lee configuracion base | Catalogos generales, parametros de sistema |
| **MAI-002 (Proyectos)** | Lee estructura de proyectos | Proyectos, etapas, prototipos, caracteristicas |
| **MAI-004 (Compras)** | Lee ordenes de compra | Costos reales de materiales, precios de proveedores |
| **MAI-005 (Control de Obra)** | Lee avances fisicos | Porcentaje de avance por partida, volumenes ejecutados |
| **MAI-012 (Contratos)** | Lee subcontratos | Costos de subcontratistas, alcances contratados |

### Modulos que Consumen MAI-003 (Output)

| Modulo | Relacion | Datos Compartidos |
|--------|----------|-------------------|
| **MAI-002 (Proyectos)** | Provee costos unitarios | Costo por prototipo, margen esperado |
| **MAI-004 (Compras)** | Provee presupuesto de materiales | Alertas de precios fuera de presupuesto |
| **MAI-005 (Control de Obra)** | Provee presupuesto base | Cantidades presupuestadas por partida |
| **MAI-008 (Estimaciones)** | Provee precios unitarios | Conceptos y PU para generacion de estimaciones |
| **MAI-006 (Reportes)** | Provee datos financieros | Indicadores de rentabilidad, desviaciones |

### Diagrama de Dependencias

```
┌─────────────────────────────────────────────────────────────┐
│                      MAI-003: Presupuestos                  │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Catalogo   │  │ Presupuestos │  │   Control    │     │
│  │  Conceptos   │→→│   Maestros   │→→│    Costos    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│         ↓                 ↓                   ↓             │
│  ┌─────────────────────────────────────────────────┐       │
│  │         Analisis de Rentabilidad                │       │
│  └─────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────┘
          ↑                    ↑                    ↑
          │                    │                    │
    ┌─────┴──────┐      ┌─────┴──────┐      ┌─────┴──────┐
    │  MAI-002   │      │  MAI-004   │      │  MAI-005   │
    │ Proyectos  │      │  Compras   │      │   Control  │
    └────────────┘      └────────────┘      └────────────┘
```

---

## Diagrama de Arquitectura

### Arquitectura de 3 Capas

```
┌────────────────────────────────────────────────────────────────┐
│                   CAPA DE PRESENTACION                         │
│                      (React + Vite)                            │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐     │
│  │   Catalogo    │  │ Presupuestos  │  │   Control     │     │
│  │  Conceptos    │  │   Maestros    │  │    Costos     │     │
│  │               │  │               │  │               │     │
│  │ - Lista con   │  │ - Wizard de   │  │ - Dashboard   │     │
│  │   busqueda    │  │   creacion    │  │   Curva S     │     │
│  │ - Formulario  │  │ - Generadores │  │ - Analisis de │     │
│  │   APU         │  │   automaticos │  │   desviaciones│     │
│  │ - Historial   │  │ - Versionado  │  │ - Alertas     │     │
│  └───────────────┘  └───────────────┘  └───────────────┘     │
│                                                                │
└────────────────────────────────────────────────────────────────┘
                              ↓ REST API
┌────────────────────────────────────────────────────────────────┐
│                     CAPA DE NEGOCIO                            │
│                       (NestJS)                                 │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  ┌──────────────────────────────────────────────────────┐     │
│  │              BudgetsModule                           │     │
│  ├──────────────────────────────────────────────────────┤     │
│  │                                                      │     │
│  │  Services:                                           │     │
│  │  - ConceptCatalogService (CRUD conceptos)            │     │
│  │  - APUCalculatorService (calculo PU compuestos)      │     │
│  │  - BudgetService (CRUD presupuestos)                 │     │
│  │  - BudgetGeneratorService (generadores automaticos)  │     │
│  │  - CostControlService (registro costos reales)       │     │
│  │  - VarianceAnalysisService (analisis desviaciones)   │     │
│  │  - ProfitabilityService (analisis rentabilidad)      │     │
│  │                                                      │     │
│  │  Controllers:                                        │     │
│  │  - ConceptCatalogController (9 endpoints)            │     │
│  │  - BudgetController (12 endpoints)                   │     │
│  │  - CostControlController (8 endpoints)               │     │
│  │  - ProfitabilityController (6 endpoints)             │     │
│  │                                                      │     │
│  │  Cron Jobs:                                          │     │
│  │  - CostAnalysisTask.analyzeDailyCosts() (6:00 AM)    │     │
│  │                                                      │     │
│  └──────────────────────────────────────────────────────┘     │
│                                                                │
└────────────────────────────────────────────────────────────────┘
                              ↓ TypeORM
┌────────────────────────────────────────────────────────────────┐
│                     CAPA DE DATOS                              │
│                   (PostgreSQL 14+)                             │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  Schema: budgets                                               │
│  ┌──────────────────────────────────────────────────────┐     │
│  │                                                      │     │
│  │  Tablas Principales:                                 │     │
│  │  - concept_catalog (conceptos base)                  │     │
│  │  - concept_price_history (historial precios)         │     │
│  │  - regions (regionalizacion)                         │     │
│  │  - budgets (presupuestos maestros)                   │     │
│  │  - budget_items (partidas jerarquicas)               │     │
│  │  - budget_versions (versionado)                      │     │
│  │  - actual_costs (costos reales)                      │     │
│  │  - cost_variances (desviaciones)                     │     │
│  │  - cost_projections (proyecciones EAC)               │     │
│  │  - profitability_analysis (analisis rentabilidad)    │     │
│  │  - prototype_profitability (rentabilidad prototipo)  │     │
│  │                                                      │     │
│  │  Funciones SQL:                                      │     │
│  │  - calculate_composite_price() (calculo PU)          │     │
│  │  - calculate_variances() (desviaciones)              │     │
│  │  - calculate_eac() (proyeccion costo final)          │     │
│  │  - calculate_profitability() (rentabilidad)          │     │
│  │                                                      │     │
│  │  Triggers:                                           │     │
│  │  - Auto-actualizacion de updated_at                  │     │
│  │  - Historial automatico de precios                   │     │
│  │  - Recalculo de totales en presupuestos              │     │
│  │  - Alertas en desviaciones >5%                       │     │
│  │                                                      │     │
│  └──────────────────────────────────────────────────────┘     │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

### Modelo de Datos Simplificado

```sql
-- Schema principal
CREATE SCHEMA budgets;

-- Tipos ENUM
CREATE TYPE budgets.concept_type AS ENUM ('material', 'labor', 'equipment', 'composite');
CREATE TYPE budgets.budget_scope AS ENUM ('project', 'stage', 'prototype');
CREATE TYPE budgets.budget_status AS ENUM ('draft', 'in_review', 'approved', 'active', 'completed');

-- Tabla principal de conceptos
CREATE TABLE budgets.concept_catalog (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  constructora_id UUID NOT NULL REFERENCES constructoras.constructoras(id),
  code VARCHAR(50) NOT NULL,
  name VARCHAR(255) NOT NULL,
  concept_type budgets.concept_type NOT NULL,
  category VARCHAR(100),
  unit VARCHAR(20),
  base_price DECIMAL(12,2),
  region_id UUID REFERENCES budgets.regions(id),
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Tabla de presupuestos
CREATE TABLE budgets.budgets (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  constructora_id UUID NOT NULL REFERENCES constructoras.constructoras(id),
  project_id UUID REFERENCES projects.projects(id),
  code VARCHAR(50) NOT NULL,
  scope budgets.budget_scope NOT NULL,
  status budgets.budget_status DEFAULT 'draft',
  total_amount DECIMAL(14,2),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Tabla de partidas del presupuesto
CREATE TABLE budgets.budget_items (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  budget_id UUID NOT NULL REFERENCES budgets.budgets(id),
  concept_id UUID REFERENCES budgets.concept_catalog(id),
  parent_id UUID REFERENCES budgets.budget_items(id),
  quantity DECIMAL(12,4),
  unit_price DECIMAL(12,2),
  total_amount DECIMAL(14,2),
  level INTEGER DEFAULT 0
);

-- Tabla de costos reales
CREATE TABLE budgets.actual_costs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  budget_item_id UUID NOT NULL REFERENCES budgets.budget_items(id),
  source_type VARCHAR(50), -- 'purchase', 'payroll', 'subcontract', 'manual'
  source_id UUID,
  quantity DECIMAL(12,4),
  unit_cost DECIMAL(12,2),
  total_cost DECIMAL(14,2),
  cost_date DATE,
  created_at TIMESTAMP DEFAULT NOW()
);
```

---

## Stack Tecnologico

### Backend
- **Framework:** NestJS 10+
- **ORM:** TypeORM con PostgreSQL
- **Validacion:** class-validator, class-transformer
- **Documentacion API:** Swagger/OpenAPI
- **Testing:** Jest

### Frontend
- **Framework:** React 18+ con TypeScript
- **Build Tool:** Vite 5+
- **Estado:** Zustand (stores por modulo)
- **UI Components:** shadcn/ui + Tailwind CSS
- **Formularios:** React Hook Form + Zod
- **Graficos:** Chart.js para Curva S
- **Tablas:** TanStack Table v8

### Base de Datos
- **DBMS:** PostgreSQL 14+
- **Schema:** `budgets`
- **RLS:** Row Level Security para multi-tenant
- **Triggers:** Auto-actualizacion de totales y alertas
- **Funciones:** Calculos complejos en SQL

### DevOps
- **Contenedores:** Docker + Docker Compose
- **CI/CD:** GitHub Actions
- **Migraciones:** TypeORM migrations
- **Monitoreo:** Logs estructurados con Winston

---

## Enlaces a Documentacion

### Documentacion Tecnica Detallada

- **[RESUMEN-EPICA-MAI-003.md](./RESUMEN-EPICA-MAI-003.md)** - Resumen ejecutivo completo de la epica

### Requerimientos Funcionales
- [RF-COST-001: Catalogo de Conceptos y Precios Unitarios](./requerimientos/RF-COST-001-catalogo-conceptos-precios.md)
- [RF-COST-002: Presupuestos Maestros](./requerimientos/RF-COST-002-presupuestos-maestros.md)
- [RF-COST-003: Control de Costos Reales](./requerimientos/RF-COST-003-control-costos-reales.md)
- [RF-COST-004: Analisis de Rentabilidad](./requerimientos/RF-COST-004-analisis-rentabilidad.md)

### Especificaciones Tecnicas
- [ET-COST-001: Implementacion del Catalogo](./especificaciones/ET-COST-001-implementacion-catalogo.md)
- [ET-COST-002: Implementacion de Presupuestos](./especificaciones/ET-COST-002-implementacion-presupuestos.md)
- [ET-COST-003: Implementacion de Control de Costos](./especificaciones/ET-COST-003-implementacion-control-costos.md)
- [ET-COST-004: Implementacion de Rentabilidad](./especificaciones/ET-COST-004-implementacion-rentabilidad.md)

### Historias de Usuario
- [Todas las historias de usuario (US-COST-001 a US-COST-008)](./historias-usuario/)

### Implementacion
- [Archivos de implementacion (SQL, migrations, seeds)](./implementacion/)

---

## Indicadores Clave (KPIs)

### Metricas de Adopcion
- **Proyectos con presupuesto formal:** >95%
- **Conceptos reutilizados del catalogo:** >90%
- **Conceptos duplicados:** <5%

### Metricas de Eficiencia
- **Tiempo de elaboracion de presupuesto:** <2 horas (vs 8-10h manual)
- **Busqueda de conceptos:** <200ms
- **Actualizacion masiva de precios:** <5 seg (500 conceptos)
- **Generacion de presupuesto:** <2 seg (100 partidas)

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

### Metricas de Rentabilidad
- **Proyectos con margen >= target:** >80%
- **Incremento de margen promedio:** +2 puntos anuales
- **ROI del portafolio:** >=12% anual

---

## Puntos Criticos

1. **Calidad del catalogo de conceptos** - Base de todo el sistema, requiere revision y depuracion continua
2. **Precision de generadores automaticos** - Formulas deben validarse contra casos reales
3. **Integracion con compras/nomina** - Registro automatico de costos reales depende de otros modulos
4. **Alertas de desviaciones** - Configuracion de umbrales critica para evitar spam
5. **Performance en calculos masivos** - Optimizacion de queries para presupuestos grandes (>1000 partidas)

---

## Roles y Permisos

| Rol | Permisos |
|-----|----------|
| **Presupuestista** | Crear/editar conceptos y presupuestos, actualizar precios |
| **Director de Costos** | Aprobar presupuestos, ver analisis de rentabilidad, configurar alertas |
| **Analista de Costos** | Registrar costos reales, analizar desviaciones, crear planes de accion |
| **Director General** | Ver dashboard global, aprobar presupuestos criticos (>$10M) |
| **Solo Lectura** | Ver presupuestos y reportes, sin edicion |

---

## Flujos de Trabajo

### Flujo 1: Creacion de Presupuesto de Obra

```
1. [Presupuestista] Crea nuevo presupuesto desde proyecto
2. [Sistema] Sugiere conceptos del catalogo segun tipo de proyecto
3. [Presupuestista] Agrega partidas y conceptos, define cantidades
4. [Sistema] Calcula automaticamente PU compuestos con APU
5. [Sistema] Genera totales por capitulo CMIC
6. [Presupuestista] Revisa y envia a aprobacion
7. [Director de Costos] Valida margenes y rentabilidad esperada
8. [Director General] Aprueba presupuesto (si >$10M)
9. [Sistema] Marca presupuesto como "Aprobado" (baseline)
10. [Sistema] Habilita control de costos reales para el proyecto
```

### Flujo 2: Control de Costos y Alertas

```
1. [Sistema] Registra automaticamente costos reales desde:
   - Modulo de Compras (materiales)
   - Modulo de Nomina (mano de obra)
   - Modulo de Subcontratos (subcontratistas)
2. [Cron Job Diario] Recalcula desviaciones y proyecciones
3. [Sistema] Detecta desviacion >5% en capitulo "Estructura"
4. [Sistema] Envia alerta a Director de Costos y Analista
5. [Analista de Costos] Investiga causa de desviacion
6. [Analista] Crea plan de accion correctivo (obligatorio)
7. [Director de Costos] Revisa y aprueba plan de accion
8. [Sistema] Monitorea ejecucion de plan de accion
9. [Sistema] Actualiza proyeccion EAC con nuevas estimaciones
```

### Flujo 3: Analisis de Rentabilidad

```
1. [Director de Costos] Accede a dashboard de rentabilidad
2. [Sistema] Muestra analisis actualizado:
   - Margen bruto por proyecto
   - Comparacion de rentabilidad por prototipo
   - Punto de equilibrio
3. [Director] Ejecuta simulador de escenarios
4. [Sistema] Calcula impacto de:
   - Reducir costo de estructura 5%
   - Incrementar precio de venta 2%
5. [Sistema] Muestra matriz de sensibilidad
6. [Director] Identifica prototipos con baja rentabilidad
7. [Director] Solicita optimizacion de presupuesto de prototipo
8. [Presupuestista] Ajusta concepto y crea nueva version
9. [Sistema] Recalcula rentabilidad con nuevo presupuesto
```

---

**Generado:** 2025-12-06
**Estado:** Completo
**Mantenedores:** @tech-lead @backend-team @frontend-team