---
id: "US-PFM-014"
title: "Generar Reporte PDF"
type: "User Story"
status: "Ready"
priority: "Alta"
epic: "OQI-008"
project: "trading-platform"
story_points: 5
created_date: "2026-01-25"
updated_date: "2026-01-25"
---

# US-PFM-014: Generar Reporte PDF

**Épica:** OQI-008 - Portfolio Manager
**Story Points:** 5 | **Prioridad:** P0

---

## Historia de Usuario

**Como** inversor
**Quiero** generar reportes PDF de mi portafolio
**Para** análisis offline o compartir con asesores financieros

---

## Criterios de Aceptación

```gherkin
Scenario: Seleccionar período de reporte
  Given estoy en la sección de reportes del portafolio
  And tengo datos de inversión disponibles
  When selecciono un rango de fechas
  Then puedo elegir período predeterminado (mensual, trimestral, anual)
  And puedo ingresar fechas personalizadas
  And el período es validado contra datos disponibles

Scenario: Generar reporte con gráficos
  Given seleccioné un período válido
  When solicito generar reporte PDF
  Then el documento incluye gráficos de:
    - Evolución del valor del portafolio (línea temporal)
    - Distribución por activos (pie chart)
    - Comparativo portafolio vs benchmark
    - Retorno acumulado vs rentabilidad mensual (barras)

Scenario: Incluir métricas de rendimiento
  Given el reporte está siendo generado
  When se incluyen métricas de rendimiento
  Then veo en el documento:
    - Rentabilidad total (%)
    - Rentabilidad anualizada
    - Volatilidad
    - Ratio de Sharpe
    - Máxima pérdida acumulada (drawdown)
    - Ratio ganancia/pérdida

Scenario: Detalle de posiciones
  Given el reporte incluye posiciones
  When se genera la sección de posiciones
  Then veo tabla con:
    - Código/Ticker del activo
    - Cantidad de unidades
    - Precio de compra/Precio actual
    - Valor actual en portafolio
    - Rendimiento (% y valor absoluto)
    - Fecha de compra

Scenario: Descargar reporte
  Given el reporte PDF está listo
  When hago clic en "Descargar"
  Then el archivo se descarga como: Portfolio_[fecha_inicio]_[fecha_fin]_[timestamp].pdf
  And el formato PDF es optimizado (tamaño <5MB)

Scenario: Enviar reporte por email
  Given el reporte PDF está listo
  When hago clic en "Enviar por Email"
  And ingreso dirección(es) de correo
  Then el PDF se envía a los destinatarios
  And recibo confirmación de envío
  And el destinatario recibe el correo con adjunto

Scenario: Reporte multi-cuenta
  Given tengo múltiples cuentas/portafolios
  When selecciono la opción "Consolidado"
  Then el reporte muestra:
    - Resumen general
    - Desglose por cada cuenta
    - Distribución consolidada
    - Rentabilidades combinadas
```

---

## API Endpoint

### POST /api/portfolio/reports/pdf

**Request:**
```json
{
  "portfolioId": "uuid",
  "startDate": "2026-01-01",
  "endDate": "2026-01-25",
  "includeGraphs": true,
  "includeMetrics": true,
  "includePositions": true,
  "benchmark": "SPX",
  "downloadFormat": "pdf",
  "sendEmail": {
    "enabled": false,
    "recipients": []
  },
  "consolidated": false
}
```

**Response (200):**
```json
{
  "id": "report_uuid",
  "status": "generated",
  "downloadUrl": "/api/reports/download/report_uuid",
  "emailStatus": "pending|sent|failed",
  "generatedAt": "2026-01-25T10:30:00Z",
  "fileName": "Portfolio_2026-01-01_2026-01-25_20260125103000.pdf"
}
```

**Response (202 - Async):**
```json
{
  "jobId": "job_uuid",
  "status": "processing",
  "estimatedTime": "30s",
  "checkUrl": "/api/portfolio/reports/pdf/status/job_uuid"
}
```

---

## Dependencias

- RF-PFM-007: Cálculo de métricas de rendimiento
- RF-PFM-008: Integración con servicio de reportes
- RF-PFM-009: Generación de gráficos embebidos en PDF
- ET-PFM-007: Entidad ReportPDF
- US-PFM-012: Reporte Fiscal (complementario)

---

## Notas Técnicas

- Usar librería `pdfkit` o `puppeteer` para generación
- Gráficos embebidos con `chart.js` o `lightweight-charts`
- Queue asíncrona para reportes grandes (>500MB portafolio)
- Implementar retry automático en fallos de email
- Almacenar reportes 30 días máximo
- Validar tamaño de portafolio antes de generar

---

## Aceptación

- [ ] Endpoint POST creado y documentado
- [ ] Generación de PDF con gráficos funcional
- [ ] Descarga de archivos validada
- [ ] Envío por email implementado
- [ ] Tests unitarios y de integración
- [ ] Documentación en Swagger
- [ ] Manual de usuario actualizado

---

*Historia de usuario - Sistema NEXUS*