# US-INV-011: Exportar Reporte a PDF

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-INV-011 |
| **Épica** | OQI-004 - Cuentas de Inversión |
| **Módulo** | investment |
| **Prioridad** | P2 |
| **Story Points** | 3 |
| **Sprint** | Sprint 7 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** inversor,
**quiero** exportar un reporte completo de mi cuenta en formato PDF,
**para** tener un documento profesional para mis registros personales o fiscales.

## Descripción Detallada

El usuario debe poder generar y descargar un reporte PDF profesional que incluya: resumen de la cuenta, rendimiento histórico, gráficos, lista de transacciones, métricas clave, y disclaimers legales. El PDF debe ser bien formateado, con branding de OrbiQuant IA, y optimizado para impresión.

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────┐
│                    EXPORTAR REPORTE                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  📄 Generar Reporte en PDF                              │   │
│  │                                                           │   │
│  │  Cuenta: Atlas - El Guardián                             │   │
│  │                                                           │   │
│  │  Selecciona el período:                                   │   │
│  │  (*) Último mes                                          │   │
│  │  ( ) Últimos 3 meses                                     │   │
│  │  ( ) Últimos 6 meses                                     │   │
│  │  ( ) Todo el historial                                   │   │
│  │  ( ) Personalizado: [01/06/2025] - [05/12/2025]         │   │
│  │                                                           │   │
│  │  Incluir en el reporte:                                   │   │
│  │  [x] Resumen de cuenta                                   │   │
│  │  [x] Gráfico de rendimiento                              │   │
│  │  [x] Métricas de desempeño                               │   │
│  │  [x] Transacciones detalladas                            │   │
│  │  [x] Posiciones del agente                               │   │
│  │  [x] Distribuciones mensuales                            │   │
│  │  [ ] Comparación con benchmarks                          │   │
│  │                                                           │   │
│  │  Idioma:                                                  │   │
│  │  (*) Español  ( ) English                                │   │
│  │                                                           │   │
│  │  ┌───────────────────────────────────────────────────┐  │   │
│  │  │         GENERAR Y DESCARGAR PDF                   │  │   │
│  │  └───────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  📋 Reportes Generados Recientemente                    │   │
│  │                                                           │   │
│  │  • Reporte_Atlas_Nov2025.pdf (2.3 MB) - Hace 2 días     │   │
│  │    [Descargar] [Eliminar]                                │   │
│  │                                                           │   │
│  │  • Reporte_Atlas_Oct2025.pdf (1.8 MB) - Hace 1 mes      │   │
│  │    [Descargar] [Eliminar]                                │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

                    PREVIEW DEL PDF:
┌─────────────────────────────────────────────────────────────────┐
│                                                                  │
│                      ORBIQUANT IA                                │
│                   Reporte de Inversión                           │
│                                                                  │
│  Cuenta: Atlas - El Guardián                                    │
│  Titular: Juan Pérez                                            │
│  Período: 01 Nov 2025 - 30 Nov 2025                             │
│  Generado: 05 Dic 2025                                          │
│                                                                  │
│  ────────────────────────────────────────────────────────────   │
│                                                                  │
│  RESUMEN EJECUTIVO                                              │
│                                                                  │
│  Balance Inicial:        $1,000.00                              │
│  Balance Final:          $1,048.00                              │
│  Rendimiento:            +$48.00 (+4.8%)                        │
│                                                                  │
│  [Gráfico de evolución del balance]                             │
│                                                                  │
│  ────────────────────────────────────────────────────────────   │
│                                                                  │
│  MÉTRICAS DE DESEMPEÑO                                          │
│                                                                  │
│  Total Trades:           28                                     │
│  Win Rate:               78.6%                                  │
│  Sharpe Ratio:           1.8                                    │
│  Max Drawdown:           -2.3%                                  │
│                                                                  │
│  [Más secciones...]                                             │
│                                                                  │
│  ────────────────────────────────────────────────────────────   │
│  Página 1 de 5                        orbiquant.ai              │
└─────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Generar reporte mensual**
```gherkin
DADO que el usuario tiene cuenta activa con historial
CUANDO selecciona período "Último mes"
Y marca todas las secciones a incluir
Y hace click en "Generar y descargar PDF"
ENTONCES se genera PDF con datos del último mes
Y se descarga archivo "Reporte_Atlas_Nov2025.pdf"
Y el PDF incluye todas las secciones seleccionadas
Y tiene formato profesional con branding
```

**Escenario 2: Personalizar período**
```gherkin
DADO que el usuario quiere reporte personalizado
CUANDO selecciona "Personalizado"
Y elige fecha inicio "01/06/2025" y fin "05/12/2025"
ENTONCES se genera reporte para ese período exacto
Y el título refleja "Período: 01 Jun 2025 - 05 Dic 2025"
```

**Escenario 3: Excluir secciones opcionales**
```gherkin
DADO que el usuario solo quiere resumen básico
CUANDO desmarca "Transacciones detalladas"
Y desmarca "Posiciones del agente"
ENTONCES el PDF NO incluye esas secciones
Y el archivo es más liviano
```

**Escenario 4: Generar en inglés**
```gherkin
DADO que el usuario necesita reporte en inglés
CUANDO selecciona idioma "English"
Y genera el reporte
ENTONCES todo el contenido está en inglés
Y el archivo se nombra "Report_Atlas_Nov2025.pdf"
```

**Escenario 5: Ver reportes generados previamente**
```gherkin
DADO que el usuario generó reportes anteriormente
CUANDO navega a sección de exportar
ENTONCES ve lista de reportes recientes (últimos 5)
Y puede descargar o eliminar cada uno
```

**Escenario 6: Reporte sin datos suficientes**
```gherkin
DADO que el usuario tiene cuenta recién creada
Y no hay historial de 30 días
CUANDO intenta generar reporte mensual
ENTONCES se muestra advertencia "Datos insuficientes"
Y se sugiere generar reporte personalizado desde fecha de apertura
```

## Criterios Adicionales

- [ ] PDF optimizado para impresión (tamaño A4)
- [ ] Incluir tabla de contenidos en reportes largos
- [ ] Marca de agua "Generado por OrbiQuant IA"
- [ ] Footer con disclaimers legales
- [ ] Compresión de imágenes para tamaño óptimo
- [ ] Límite de 10 MB por archivo

---

## Tareas Técnicas

**Database:**
- [ ] DB-INV-001: Tabla investment.generated_reports
- [ ] DB-INV-002: Guardar metadata de reportes generados

**Backend:**
- [ ] BE-INV-001: Endpoint POST /investment/accounts/:id/reports/generate
- [ ] BE-INV-002: Implementar ReportService.generatePDF()
- [ ] BE-INV-003: Integración con librería PDF (pdfkit, puppeteer, o jsPDF)
- [ ] BE-INV-004: Template HTML para renderizar PDF
- [ ] BE-INV-005: Generar gráficos como imágenes (Chart.js headless)
- [ ] BE-INV-006: Endpoint GET /investment/accounts/:id/reports
- [ ] BE-INV-007: Endpoint GET /investment/reports/:id/download
- [ ] BE-INV-008: Endpoint DELETE /investment/reports/:id
- [ ] BE-INV-009: Cleanup job para eliminar reportes antiguos (>30 días)

**Frontend:**
- [ ] FE-INV-001: Crear página ExportReportPage.tsx
- [ ] FE-INV-002: Crear componente ReportConfigForm.tsx
- [ ] FE-INV-003: Crear componente DateRangePicker.tsx
- [ ] FE-INV-004: Crear componente ReportPreview.tsx
- [ ] FE-INV-005: Crear componente RecentReports.tsx
- [ ] FE-INV-006: Loading state durante generación
- [ ] FE-INV-007: Implementar reportsStore

**Tests:**
- [ ] TEST-INV-001: Test generación de PDF
- [ ] TEST-INV-002: Test personalización de secciones
- [ ] TEST-INV-003: Test multi-idioma
- [ ] TEST-INV-004: Test cleanup de reportes antiguos
- [ ] TEST-INV-005: Test E2E flujo completo

---

## Dependencias

**Depende de:**
- [ ] US-INV-004: Ver dashboard - Estado: Pendiente
- [ ] US-INV-005: Ver rendimiento - Estado: Pendiente
- [ ] US-INV-007: Ver transacciones - Estado: Pendiente

**Bloquea:**
- Ninguna

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | /investment/accounts/:id/reports/generate | Generar PDF |
| GET | /investment/accounts/:id/reports | Listar reportes |
| GET | /investment/reports/:id/download | Descargar PDF |
| DELETE | /investment/reports/:id | Eliminar reporte |

**Entidades/Tablas:**
- `investment.generated_reports`: Metadata de reportes
- Storage (S3/local): Archivos PDF generados

**Request Body POST /reports/generate:**
```typescript
{
  period: "last_month" | "last_3_months" | "last_6_months" | "all" | "custom",
  startDate?: "2025-06-01",
  endDate?: "2025-12-05",
  sections: {
    summary: true,
    chart: true,
    metrics: true,
    transactions: true,
    positions: true,
    distributions: true,
    benchmarks: false
  },
  language: "es" | "en"
}
```

**Response:**
```typescript
{
  report: {
    id: "uuid",
    accountId: "uuid",
    filename: "Reporte_Atlas_Nov2025.pdf",
    fileSize: 2359296, // bytes
    period: {
      start: "2025-11-01",
      end: "2025-11-30"
    },
    sections: ["summary", "chart", "metrics", "transactions"],
    language: "es",
    generatedAt: "2025-12-05T10:30:00Z",
    downloadUrl: "/api/investment/reports/uuid/download"
  }
}
```

**Estructura del PDF:**

1. **Portada**
   - Logo OrbiQuant IA
   - Título "Reporte de Inversión"
   - Nombre de cuenta y titular
   - Período del reporte
   - Fecha de generación

2. **Resumen Ejecutivo**
   - Balance inicial vs final
   - Rendimiento total
   - Gráfico de evolución

3. **Métricas de Desempeño**
   - Total trades, win rate
   - Sharpe ratio, max drawdown
   - Rendimiento mensual promedio

4. **Transacciones Detalladas** (opcional)
   - Tabla con todas las transacciones
   - Fecha, tipo, descripción, monto

5. **Posiciones del Agente** (opcional)
   - Trades realizados en el período
   - Símbolo, dirección, P&L

6. **Distribuciones Mensuales** (opcional)
   - Historial de distribuciones
   - Tabla y gráfico

7. **Comparación con Benchmarks** (opcional)
   - Gráfico comparativo
   - Tabla de rendimientos

8. **Footer Legal**
   - Disclaimers
   - "Los rendimientos pasados no garantizan resultados futuros"
   - Información de contacto

**Tecnología para PDF:**
- Opción 1: **Puppeteer** (renderizar HTML a PDF)
  - Pros: HTML/CSS familiar, fácil styling
  - Cons: Requiere Chrome headless

- Opción 2: **pdfkit** (generar PDF programáticamente)
  - Pros: Ligero, no requiere browser
  - Cons: Más código para layouts complejos

**Nombre de Archivo:**
```typescript
const filename = `${language === 'es' ? 'Reporte' : 'Report'}_${productName}_${period}_${date}.pdf`;
// Ejemplo: Reporte_Atlas_Nov2025.pdf
```

**Límites:**
- Tamaño máximo: 10 MB
- Reportes guardados: Últimos 30 días
- Máximo 5 reportes por cuenta

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita
- [x] Criterios de aceptación definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [ ] Template PDF diseñado
- [x] API spec disponible

## Definition of Done (DoD)

- [ ] Código implementado según criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integración pasando
- [ ] PDF con formato profesional
- [ ] Multi-idioma funcionando
- [ ] Gráficos renderizados correctamente
- [ ] Cleanup job configurado
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] QA aprobado (validar PDFs generados)
- [ ] Desplegado en ambiente de pruebas

---

## Historial de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creación | Requirements-Analyst |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Última actualización:** 2025-12-05
