--- id: "US-INV-011" title: "Exportar Reporte a PDF" type: "User Story" status: "Done" priority: "Media" epic: "OQI-004" project: "trading-platform" story_points: 3 created_date: "2025-12-05" updated_date: "2026-01-04" --- # 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 Trading Platform, 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 trading.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 Trading Platform" - [ ] 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 Trading Platform - 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