# EPICA: EPIC-MAI-003 - Presupuestos y Costos

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MAI-003 |
| **Nombre** | Presupuestos y Control de Costos |
| **Modulo** | presupuestos-costos |
| **Fase** | Fase 1 - Alcance Inicial |
| **Prioridad** | P0 (Critico) |
| **Estado** | Backlog |
| **Story Points** | 55 |
| **Sprint(s)** | Sprint 3-5 |

---

## Descripcion

Sistema de presupuestos de construccion con estructura jerarquica de conceptos, partidas, Analisis de Precios Unitarios (APU), explosionado automatico de materiales y comparativo presupuesto vs real. Soporta presupuestos base (por prototipo de vivienda) y presupuestos ejecutivos (por proyecto/fraccionamiento).

---

## Objetivo de Negocio

Proveer control presupuestal que:
- Defina costos por concepto de obra con precision
- Permita analisis de precios unitarios (APU)
- Explosione materiales automaticamente para compras
- Compare presupuesto vs ejecutado en tiempo real
- Identifique desviaciones tempranas para toma de decisiones
- Soporte multiples versiones de presupuesto
- Facilite la elaboracion de estimaciones

---

## Stakeholders

| Rol | Nombre/Equipo | Responsabilidad |
|-----|---------------|-----------------|
| Product Owner | Equipo Producto | Definicion de funcionalidades |
| Tech Lead | Equipo Backend | Arquitectura de calculos |
| Presupuestador | Construccion | Elaboracion de APU y presupuestos |
| Residente de Obra | Campo | Control de avance y costos |
| Director de Construccion | Gerencia | Aprobacion y seguimiento |

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MAI003-001 | Como presupuestador, quiero crear presupuestos base por prototipo de vivienda para estandarizar costos | P0 | 8 | Backlog |
| US-MAI003-002 | Como presupuestador, quiero crear partidas y conceptos jerarquicos para organizar el presupuesto | P0 | 5 | Backlog |
| US-MAI003-003 | Como presupuestador, quiero elaborar APU para definir precios unitarios con detalle de insumos | P0 | 8 | Backlog |
| US-MAI003-004 | Como presupuestador, quiero explosionar materiales del presupuesto para planificar compras | P0 | 8 | Backlog |
| US-MAI003-005 | Como residente, quiero crear presupuesto ejecutivo desde base para aplicar a proyecto especifico | P0 | 5 | Backlog |
| US-MAI003-006 | Como residente, quiero comparar presupuesto vs real para detectar desviaciones | P0 | 8 | Backlog |
| US-MAI003-007 | Como presupuestador, quiero importar presupuesto desde Excel para migrar datos existentes | P1 | 5 | Backlog |
| US-MAI003-008 | Como presupuestador, quiero versionar presupuestos para mantener historial de cambios | P1 | 3 | Backlog |
| US-MAI003-009 | Como director, quiero ver dashboard de desviaciones para tomar decisiones oportunas | P1 | 5 | Backlog |

**Total Story Points:** 55 SP

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Estructura jerarquica: Partida -> Subpartida -> Concepto
- [ ] APU con insumos (materiales, mano de obra, equipo, herramienta)
- [ ] Explosionado automatico de materiales por cantidad de viviendas
- [ ] Presupuesto base (por prototipo) y ejecutivo (por proyecto)
- [ ] Comparativo presupuesto vs real con % desviacion
- [ ] Versionado de presupuestos con historial
- [ ] Import/Export Excel con formato estandar
- [ ] Calculo de indirectos y utilidad

**No Funcionales:**
- [ ] Performance: Calculo de explosionado < 5s para 1000 conceptos
- [ ] Precision: 4 decimales en precios unitarios
- [ ] Consistencia: Totales calculados automaticamente

**Tecnicos:**
- [ ] Cobertura de tests > 80%
- [ ] Funciones de calculo en PostgreSQL para performance
- [ ] Documentacion de formulas de APU

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-MAI-001 Fundamentos | Backlog | Si |
| EPIC-MAI-002 Proyectos | Backlog | Si |
| MGN-005 Catalogs (materiales) | Backlog | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-MAI-004 Compras | Explosion de materiales |
| EPIC-MAI-005 Control Obra | Avance por concepto |
| EPIC-MAI-008 Estimaciones | Base para facturacion |
| EPIC-MAE-014 Finanzas | Control de costos |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `budget_management`
- [ ] Tablas: 12 (budgets, budget_versions, partidas, concepts, apu, apu_items, materials_explosion, budget_vs_actual, indirectos, rendimientos, etc.)
- [ ] Funciones: 5 (calcular_apu, explosionar_materiales, comparar_real, recalcular_totales, versionar_presupuesto)
- [ ] Triggers: Recalculo automatico de totales
- [ ] RLS Policies: Si (por tenant y proyecto)

**Backend:**
- [ ] Modulo: `budgets`
- [ ] Entities: 12 (Budget, BudgetVersion, Partida, Concept, APU, APUItem, MaterialExplosion, etc.)
- [ ] Services: BudgetService, APUService, ExplosionService, ComparisonService
- [ ] Endpoints: 30+ (CRUD budgets, partidas, conceptos, APU, explosion, comparison)
- [ ] Jobs: ExplosionCalculationJob
- [ ] Tests: 45+

**Frontend:**
- [ ] Paginas: 7 (Budgets, BudgetDetail, PartidaEditor, APUEditor, Explosion, Comparison, Dashboard)
- [ ] Componentes: 25+ (BudgetTree, APUForm, ExplosionTable, ComparisonChart, PartidaDragDrop)
- [ ] Stores: 1 (budgetsStore)

---

## Estructura de Presupuesto

```
Presupuesto (Casa Tipo A - Fraccionamiento Las Palmas)
├── Partida 1: PRELIMINARES
│   ├── 1.1 Limpieza de terreno
│   │   └── APU: Peones + Herramienta
│   └── 1.2 Trazo y nivelacion
│       └── APU: Topografo + Equipo
├── Partida 2: CIMENTACION
│   ├── 2.1 Excavacion
│   │   └── APU: Retroexcavadora + Operador
│   └── 2.2 Zapatas aisladas
│       └── APU: Concreto fc=250 + Acero + MO
├── Partida 3: ESTRUCTURA
│   ├── 3.1 Columnas
│   ├── 3.2 Trabes
│   └── 3.3 Losa
├── ...
└── Partida N: LIMPIEZA FINAL
    └── Total = Suma de conceptos + Indirectos + Utilidad
```

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Formulas de APU incorrectas | Media | Alto | Validacion con presupuestadores expertos |
| Performance en explosionado | Media | Alto | Calculo en DB, batch processing |
| Importacion Excel corrupta | Alta | Medio | Validacion estricta, preview antes de importar |
| Desviaciones no detectadas | Media | Alto | Alertas automaticas, dashboard |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Formato de APU estandar definido
- [ ] Catalogo de partidas SAT mapeado
- [ ] Template Excel de importacion definido
- [x] Sin bloqueadores activos

## Definition of Done (DoD)

- [ ] Codigo implementado y revisado
- [ ] Tests pasando (unit, integration, e2e)
- [ ] APU calculando correctamente
- [ ] Explosionado funcionando
- [ ] Comparativo mostrandose
- [ ] Documentacion actualizada
- [ ] Inventarios actualizados
- [ ] Trazas registradas
- [ ] Demo realizada con presupuestador
- [ ] Product Owner aprobo

---

## Documentacion Relacionada

- Modulo: `docs/02-definicion-modulos/MAI-003-presupuestos-costos/`
- User Stories: `docs/05-user-stories/mai-003/`
- DDL Spec: `docs/04-modelado/database-design/schemas/budget_management.sql`
- Especificaciones: `docs/02-definicion-modulos/MAI-003-presupuestos-costos/especificaciones/`

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creacion de epica | Requirements-Analyst |
| 2025-12-05 | Agregado Stakeholders, Riesgos, DoR/DoD | Requirements-Analyst |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Ultima actualizacion:** 2025-12-05