# 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

```typescript
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

```typescript
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

```yaml
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

```yaml
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

```typescript
// 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*