inmobiliaria-analytics/docs/01-fase-alcance-inicial/IAI-008-ml-analytics/requerimientos/RF-ML-004.md

---
id: "RF-ML-004"
title: "Reportes Profesionales Automatizados"
type: "Functional Requirement"
epic: "IAI-008"
priority: "Media"
status: "Draft"
project: "inmobiliaria-analytics"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---

# RF-IA-008-004: Reportes Profesionales Automatizados

---

## Descripcion

El sistema debe generar reportes profesionales automatizados para distintos segmentos de usuarios (agentes, inversores, desarrolladores), integrando datos de mercado, predicciones ML y visualizaciones.

---

## Justificacion

Los reportes profesionales son un diferenciador clave y fuente de valor para clientes. Automatizar su generacion permite escalar el servicio y ofrecer insights consistentes basados en datos.

---

## Requisitos Funcionales

### RF-004.1: Tipos de Reportes

| ID | Requisito | Prioridad |
|----|-----------|-----------|
| RF-004.1.1 | El sistema debe generar reportes CMA para agentes | Alta |
| RF-004.1.2 | El sistema debe generar reportes de inversion | Alta |
| RF-004.1.3 | El sistema debe generar market snapshots | Media |
| RF-004.1.4 | El sistema debe generar estudios de factibilidad | Media |

### RF-004.2: Formatos

| ID | Requisito | Prioridad |
|----|-----------|-----------|
| RF-004.2.1 | El sistema debe exportar a PDF | Alta |
| RF-004.2.2 | El sistema debe exportar a HTML interactivo | Media |
| RF-004.2.3 | El sistema debe exportar a PowerPoint | Baja |
| RF-004.2.4 | El sistema debe soportar branding personalizado | Alta |

### RF-004.3: Contenido

| ID | Requisito | Prioridad |
|----|-----------|-----------|
| RF-004.3.1 | Los reportes deben incluir datos de mercado actualizados | Alta |
| RF-004.3.2 | Los reportes deben incluir predicciones ML | Alta |
| RF-004.3.3 | Los reportes deben incluir visualizaciones (graficas, mapas) | Alta |
| RF-004.3.4 | Los reportes deben incluir comparables relevantes | Alta |

---

## Tipos de Reportes

### CMA (Comparative Market Analysis)

```yaml
reporte: CMA
audiencia: Agentes (para clientes vendedores)
secciones:
  1_resumen_ejecutivo:
    - valor_estimado
    - rango_precio
    - tiempo_estimado_venta
    - recomendacion_precio

  2_informacion_propiedad:
    - datos_basicos
    - fotos
    - caracteristicas

  3_analisis_comparables:
    - tabla_comparables
    - mapa_ubicacion
    - ajustes_precio

  4_condiciones_mercado:
    - tendencia_precios_zona
    - inventario_activo
    - absorcion

  5_estrategia_venta:
    - precio_recomendado
    - timeline_sugerido
    - tips_preparacion

formato: PDF (8-12 paginas)
branding: logo_inmobiliaria, datos_agente
```

### Investment Analysis

```yaml
reporte: Investment_Analysis
audiencia: Inversores
secciones:
  1_resumen_ejecutivo:
    - roi_proyectado
    - cash_flow_mensual
    - recomendacion

  2_descripcion_propiedad:
    - datos_basicos
    - ubicacion
    - estado_actual

  3_analisis_mercado:
    - tendencias_zona
    - comparables
    - proyeccion_apreciacion

  4_proyecciones_financieras:
    - flujo_caja_5_anos
    - escenarios_sensibilidad
    - metricas:
        - cap_rate
        - cash_on_cash
        - irr
        - payback

  5_analisis_riesgo:
    - factores_riesgo
    - mitigaciones
    - score_riesgo

  6_recomendacion:
    - go_no_go
    - proximos_pasos

formato: PDF (15-20 paginas)
```

### Market Snapshot

```yaml
reporte: Market_Snapshot
audiencia: Agentes (semanal)
secciones:
  1_indicadores_clave:
    - precio_promedio_m2
    - variacion_semanal
    - inventario
    - absorcion

  2_tendencias:
    - grafica_precios_30d
    - top_zonas_movimiento

  3_oportunidades:
    - propiedades_destacadas
    - zonas_emergentes

  4_prediccion:
    - outlook_corto_plazo

formato: PDF (4-6 paginas) o Email
frecuencia: Semanal
```

---

## Personalizacion (White-Label)

```yaml
branding:
  logo:
    posicion: header_right
    tamano_max: 200x80px
    formatos: [png, svg]

  colores:
    primario: hex_color
    secundario: hex_color
    acento: hex_color

  tipografia:
    headings: font_family
    body: font_family

  footer:
    texto: string
    contacto: string
    disclaimer: string

  cover_page:
    background_image: url
    titulo_custom: string

por_tenant: true
```

---

## API Endpoints

```yaml
POST /api/v1/ml/reports/cma:
  description: Generar reporte CMA
  request:
    property_id: string
    branding:
      logo_url: string
      agent_name: string
      agent_phone: string
    format: "pdf" | "html"
  response:
    report_id: string
    download_url: string
    expires_at: timestamp

POST /api/v1/ml/reports/investment-analysis:
  description: Generar reporte de inversion
  request:
    property_id: string
    financing:
      down_payment_pct: number
      interest_rate: number
      term_years: number
    assumptions:
      vacancy_rate: number
      appreciation_rate: number
  response:
    report_id: string
    download_url: string

POST /api/v1/ml/reports/market-snapshot:
  description: Generar market snapshot
  request:
    zone_id: string
    period: "weekly" | "monthly"
  response:
    report_id: string
    download_url: string

GET /api/v1/ml/reports/:id:
  description: Obtener estado/URL de reporte
  response:
    status: "processing" | "ready" | "failed"
    download_url: string
    expires_at: timestamp
```

---

## Criterios de Aceptacion

- [ ] CMA se genera en < 30 segundos
- [ ] PDFs tienen calidad profesional
- [ ] Branding se aplica correctamente
- [ ] Datos de mercado son actuales (< 24 horas)
- [ ] Predicciones ML se incluyen con confianza
- [ ] Graficas se renderizan correctamente
- [ ] Links de descarga expiran en 24 horas

---

## Dependencias

- IA-008-001 (AVM): Valuaciones
- IA-008-002 (Time-to-Sell): Predicciones
- Puppeteer/Playwright para PDF rendering
- Chart.js o similar para visualizaciones
- S3 para storage de reportes

---

## Historias de Usuario Relacionadas

- US-ML-006: Generacion reporte CMA
- US-ML-007: Analisis ROI para inversores

---

**Autor:** Product Lead
**Fecha:** 2026-01-04