---
id: "US-ML-007"
title: "Calculadora de ROI para inversiones"
type: "User Story"
epic: "IAI-008"
status: "Draft"
story_points: 5
priority: "Media"
project: "inmobiliaria-analytics"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---

# US-ML-007: Calculadora de ROI para inversiones

---

## User Story

**Como** inversor inmobiliario
**Quiero** calcular el retorno de inversion proyectado de una propiedad
**Para** tomar decisiones informadas de compra

---

## Descripcion

Implementar calculadora de ROI que considere precio de compra, costos de cierre, potencial de renta, apreciacion proyectada, gastos de mantenimiento e impuestos para generar proyecciones de retorno a 1, 5 y 10 anos.

---

## Criterios de Aceptacion

- [ ] Calcula Cap Rate y Cash-on-Cash return
- [ ] Proyecta apreciacion basada en ML
- [ ] Considera todos los costos (cierre, mantenimiento, impuestos)
- [ ] Muestra comparacion con otras inversiones
- [ ] Genera grafica de flujo de efectivo
- [ ] Permite ajustar parametros interactivamente

---

## Parametros de Entrada

```yaml
purchase:
  price: 4500000
  down_payment_pct: 30
  closing_costs_pct: 5
  renovation_budget: 200000

financing:
  loan_amount: 3150000  # calculado
  interest_rate: 12.5
  term_years: 20

income:
  monthly_rent: 28000
  occupancy_rate: 95  # %
  annual_rent_increase: 4  # %

expenses:
  property_tax_annual: 15000
  insurance_annual: 8000
  maintenance_pct: 1  # % del valor anual
  hoa_monthly: 2500
  management_fee_pct: 8  # % de renta

appreciation:
  use_ml_forecast: true
  manual_rate: null  # si no usa ML
```

---

## Mockup de Resultados

```
+--------------------------------------------------+
|         ANALISIS DE INVERSION                     |
+--------------------------------------------------+
|                                                   |
|  METRICAS CLAVE                                   |
|  ┌────────────────────────────────────────────┐  |
|  │ Cap Rate          │  6.8%                  │  |
|  │ Cash-on-Cash      │  9.2%                  │  |
|  │ ROI Total (5 anos)│  78%                   │  |
|  │ TIR               │  14.3%                 │  |
|  └────────────────────────────────────────────┘  |
|                                                   |
|  FLUJO DE EFECTIVO MENSUAL                        |
|  ┌────────────────────────────────────────────┐  |
|  │ + Renta bruta     │  $28,000               │  |
|  │ - Vacancia (5%)   │  -$1,400               │  |
|  │ - Hipoteca        │  -$35,500              │  |
|  │ - HOA             │  -$2,500               │  |
|  │ - Mantenimiento   │  -$3,750               │  |
|  │ - Administracion  │  -$2,240               │  |
|  │ ═══════════════════════════════════════    │  |
|  │ = Flujo neto      │  -$17,390 (*)          │  |
|  └────────────────────────────────────────────┘  |
|  (*) Flujo negativo compensado por apreciacion   |
|                                                   |
|  PROYECCION A 5 ANOS                              |
|  ┌────────────────────────────────────────────┐  |
|  │ Inversion inicial │  $1,575,000            │  |
|  │ Valor estimado    │  $6,200,000            │  |
|  │ Equity acumulado  │  $2,800,000            │  |
|  │ Renta acumulada   │  $1,512,000            │  |
|  │ Gastos acumulados │  -$780,000             │  |
|  │ Ganancia neta     │  $1,232,000            │  |
|  │ ROI               │  78%                   │  |
|  └────────────────────────────────────────────┘  |
|                                                   |
+--------------------------------------------------+
```

---

## Grafica de Proyeccion

```
Valor de la Inversion (MXN)
    │
 7M │                                    ╭───
    │                               ╭────╯
 6M │                          ╭────╯
    │                     ╭────╯
 5M │                ╭────╯
    │           ╭────╯
 4M │      ╭────╯
    │ ╭────╯
 3M │─╯
    │
    └────────────────────────────────────────
      Ano 1   Ano 2   Ano 3   Ano 4   Ano 5

    ─── Valor Propiedad    ─── Equity    ─── Deuda
```

---

## Tareas Tecnicas

| # | Tarea | Estimacion |
|---|-------|------------|
| 1 | Modelo de calculo financiero | 4h |
| 2 | Integracion con ML de apreciacion | 3h |
| 3 | Componente de entrada interactivo | 4h |
| 4 | Visualizaciones de proyeccion | 4h |
| 5 | Exportar a PDF | 2h |
| 6 | Tests | 2h |

**Total estimado:** 19h (~2.5 dias)

---

## Formulas Clave

```python
# Cap Rate
cap_rate = (net_operating_income / property_value) * 100

# Cash-on-Cash Return
cash_on_cash = (annual_cash_flow / total_cash_invested) * 100

# NOI (Net Operating Income)
noi = gross_rent - vacancy - operating_expenses

# ROI Total
roi = (equity_gain + cash_flow_cumulative) / initial_investment * 100

# TIR (IRR)
irr = npf.irr(cash_flows_array)
```

---

## Definition of Done

- [ ] Calculos financieros correctos
- [ ] ML de apreciacion integrado
- [ ] UI interactiva funcional
- [ ] Graficas renderizan correctamente
- [ ] Tests pasan

---

**Asignado a:** -
**Sprint:** -