trading-platform/docs/90-transversal/analisis/FILE-GENERATION-SPEC.md

Especificacion de Generacion de Archivos

Proyecto: trading-platform Fecha: 2026-01-25 Version: 1.0.0

---

1. Generacion de PDF

1.1 Capacidades Actuales

Modulo	Tipo de PDF	Estado	Libreria
Education	Certificados	✅ Implementado	PDFKit
Payments	Facturas	✅ Implementado	Stripe PDF
Portfolio	Reportes	⚠️ Diseño	TBD
Investment	Estados de cuenta	⚠️ Diseño	TBD

1.2 Especificacion Tecnica - Reportes Portfolio

interface PortfolioReportConfig {
  userId: string;
  dateRange: {
    start: Date;
    end: Date;
  };
  sections: {
    summary: boolean;
    positions: boolean;
    performance: boolean;
    riskMetrics: boolean;
    transactions: boolean;
  };
  format: 'pdf' | 'xlsx';
  delivery: 'download' | 'email';
}

1.3 Librerias Recomendadas

Libreria	Uso	Pros	Contras
PDFKit	Server-side PDF	Ligero, flexible	Manual layout
Puppeteer	HTML to PDF	Diseño facil	Pesado
jsPDF	Client-side	Sin servidor	Limitado
ExcelJS	XLSX generation	Completo	Solo Excel

---

2. Generacion de Excel/CSV

2.1 Capacidades Actuales

Modulo	Tipo	Estado	Endpoint
Trading	Trade history CSV	✅	/api/v1/trading/export
Education	Progress report	⚠️	Pendiente
Portfolio	Positions XLSX	⚠️	Diseño
Investment	Transactions CSV	⚠️	Diseño

2.2 Formato de Exportacion

interface ExportConfig {
  format: 'csv' | 'xlsx';
  columns: string[];
  filters?: Record<string, any>;
  dateRange?: { start: Date; end: Date };
  includeHeaders: boolean;
  filename: string;
}

---

3. Manejo de Multimedia

3.1 Imagenes

Tipo	Uso	Almacenamiento	Max Size
Avatar	Perfil usuario	S3/Local	2MB
Course thumbnails	Educacion	S3/Local	5MB
Chart screenshots	Trading	Temporal	10MB

3.2 Videos

Tipo	Uso	Almacenamiento	Streaming
Lecciones	Educacion	S3/Vimeo	HLS
Tutoriales	Onboarding	YouTube embed	iframe

3.3 Audio

Tipo	Uso	Estado
Alertas	Trading signals	✅ Web Audio API
Notificaciones	Push alerts	✅ Browser native

---

4. Endpoints de Generacion

4.1 Existentes

POST /api/v1/trading/export:
  description: Export trade history
  params:
    format: csv|xlsx
    dateRange: { start, end }
  response: File download

POST /api/v1/education/certificate:
  description: Generate course certificate
  params:
    courseId: string
    userId: string
  response: PDF download

4.2 Propuestos

POST /api/v1/portfolio/reports/pdf:
  description: Generate portfolio report
  params:
    config: PortfolioReportConfig
  response: PDF download | email confirmation

POST /api/v1/portfolio/export:
  description: Export positions/history
  params:
    format: csv|xlsx
    type: positions|history|transactions
  response: File download

POST /api/v1/investment/statement:
  description: Generate account statement
  params:
    accountId: string
    period: monthly|quarterly|annual
  response: PDF download

---

5. Implementacion Frontend

5.1 Componentes de Exportacion

// ExportButton.tsx
interface ExportButtonProps {
  endpoint: string;
  format: 'pdf' | 'csv' | 'xlsx';
  params: Record<string, any>;
  filename: string;
  label?: string;
}

// ReportGenerator.tsx
interface ReportGeneratorProps {
  type: 'portfolio' | 'investment' | 'trading';
  onGenerate: (config: ReportConfig) => Promise<void>;
  onDownload: (url: string) => void;
}

5.2 Flujo de Usuario

1. Usuario selecciona tipo de reporte
2. Configura parametros (fecha, secciones)
3. Click "Generar"
4. Backend procesa (async si es grande)
5. Notificacion cuando listo
6. Descarga o envio por email

---

6. Consideraciones de Performance

Operacion	Threshold	Estrategia
PDF < 10 paginas	Sync	Respuesta directa
PDF > 10 paginas	Async	Job queue + notificacion
Excel < 10k rows	Sync	Respuesta directa
Excel > 10k rows	Async	Job queue + notificacion
Bulk export	Async	Background job

---

7. Seguridad

• Todos los endpoints requieren autenticacion
• Rate limiting: 10 exports/hora por usuario
• Archivos temporales eliminados despues de 1 hora
• No incluir datos sensibles en exports sin consentimiento

---

Generado: 2026-01-25 | Sistema: SIMCO v4.0.0