trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/historias-usuario/US-INV-011-exportar-reporte.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-INV-011	Exportar Reporte a PDF	User Story	Done	Media	OQI-004	trading-platform	3	2025-12-05	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

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

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

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

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

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

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:

{
  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:

{
  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:

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)

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Template PDF diseñado
• 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