---
id: "SAAS-017"
title: "Reportes Exportables"
type: "Module"
status: "Specified"
priority: "P2"
module: "reports"
version: "1.0.0"
created_date: "2026-01-24"
updated_date: "2026-01-24"
story_points: 5
---

# SAAS-017: Reportes Exportables

## Metadata
- **Codigo:** SAAS-017
- **Modulo:** Reports
- **Prioridad:** P2
- **Estado:** Especificado
- **Fase:** 3 - Advanced Features
- **Story Points:** 5

## Descripcion

Sistema de generacion y exportacion de reportes en multiples formatos. Permite exportar datos de usuarios, billing, audit logs y uso en PDF (formateados), Excel (tabulares) y CSV (crudos).

## Objetivos

1. Exportar reportes de usuarios en PDF/Excel/CSV
2. Exportar reportes de billing en PDF/Excel
3. Exportar audit logs en CSV
4. Exportar metricas de uso en Excel
5. Templates predefinidos de reportes
6. Base para reportes programados (futuro)

## Alcance

### Incluido
- Generacion de PDF con formato profesional
- Exportacion a Excel con datos tabulares
- Exportacion a CSV con datos crudos
- Templates predefinidos para cada tipo de reporte
- Filtros por fecha y criterios
- Descarga directa o envio por email

### Excluido
- Reportes programados/scheduled (fase posterior)
- Designer de reportes custom
- Reportes con graficos embebidos en PDF
- Integracion con BI tools externos

## Tipos de Reportes

### Reportes de Usuarios
| Reporte | Formatos | Descripcion |
|---------|----------|-------------|
| Lista de Usuarios | PDF, Excel, CSV | Todos los usuarios con roles |
| Usuarios Activos | PDF, Excel | Usuarios activos en periodo |
| Nuevos Registros | PDF, Excel | Usuarios registrados en periodo |
| Usuarios por Plan | PDF, Excel | Distribucion por plan |

### Reportes de Billing
| Reporte | Formatos | Descripcion |
|---------|----------|-------------|
| Resumen Facturacion | PDF | Resumen mensual de billing |
| Invoices | PDF, Excel | Lista de facturas emitidas |
| Revenue | Excel | Ingresos detallados |
| Suscripciones | Excel | Estado de suscripciones |

### Reportes de Auditoria
| Reporte | Formatos | Descripcion |
|---------|----------|-------------|
| Audit Log | CSV | Log completo de acciones |
| Login History | CSV | Historial de logins |
| Changes Log | CSV | Cambios en configuracion |

### Reportes de Uso
| Reporte | Formatos | Descripcion |
|---------|----------|-------------|
| API Usage | Excel | Uso de API por endpoint |
| Storage Usage | Excel | Uso de storage por tipo |
| AI Usage | Excel | Consumo de tokens AI |

## Endpoints API

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET | /reports/users/pdf | Reporte usuarios PDF | JWT |
| GET | /reports/users/excel | Reporte usuarios Excel | JWT |
| GET | /reports/users/csv | Reporte usuarios CSV | JWT |
| GET | /reports/billing/pdf | Reporte billing PDF | JWT |
| GET | /reports/billing/excel | Reporte billing Excel | JWT |
| GET | /reports/audit/csv | Audit log CSV | JWT |
| GET | /reports/usage/excel | Reporte uso Excel | JWT |
| POST | /reports/send-email | Enviar reporte por email | JWT |

### Query Parameters Comunes

```
?start_date=2026-01-01
&end_date=2026-01-31
&filters[status]=active
&filters[plan]=pro
&sort=created_at
&order=desc
```

### Detalle de Endpoints

#### GET /reports/users/pdf
Genera reporte de usuarios en PDF.

**Query params:**
- `start_date`, `end_date`: Rango de fechas
- `status`: active | inactive | all
- `plan`: free | pro | enterprise | all

**Response:** application/pdf (binary)

**Headers:**
```
Content-Type: application/pdf
Content-Disposition: attachment; filename="users-report-2026-01.pdf"
```

#### GET /reports/billing/excel
Genera reporte de billing en Excel.

**Query params:**
- `start_date`, `end_date`: Rango de fechas
- `type`: invoices | subscriptions | revenue

**Response:** application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

#### GET /reports/audit/csv
Exporta audit log en CSV.

**Query params:**
- `start_date`, `end_date`: Rango de fechas
- `action`: login | logout | create | update | delete | all
- `user_id`: Filtrar por usuario especifico

**Response:** text/csv

#### POST /reports/send-email
Genera y envia reporte por email.

**Body:**
```json
{
  "report_type": "users",
  "format": "pdf",
  "filters": {
    "start_date": "2026-01-01",
    "end_date": "2026-01-31",
    "status": "active"
  },
  "recipients": ["admin@company.com"],
  "subject": "Monthly Users Report",
  "message": "Attached is the monthly users report."
}
```

**Response:**
```json
{
  "message": "Report sent successfully",
  "sent_to": ["admin@company.com"],
  "report_type": "users",
  "format": "pdf"
}
```

## Implementacion Backend

### Services
- `ReportsService` - Servicio principal de reportes
- `PdfGeneratorService` - Generacion de PDFs
- `ExcelGeneratorService` - Generacion de Excel
- `CsvGeneratorService` - Generacion de CSV

### Controllers
- `ReportsController` - Endpoints de reportes

### Dependencias NPM
```json
{
  "pdfkit": "^0.15.0",
  "exceljs": "^4.4.0"
}
```

### Templates de PDF

Los templates PDF se definen en codigo usando PDFKit:

```typescript
// templates/users-report.template.ts
export const generateUsersReportPdf = (data: UserReportData) => {
  const doc = new PDFDocument();

  // Header
  doc.fontSize(20).text('Users Report', { align: 'center' });
  doc.fontSize(12).text(`Period: ${data.startDate} - ${data.endDate}`);

  // Table
  doc.moveDown();
  drawTable(doc, data.users, ['Name', 'Email', 'Plan', 'Status', 'Created']);

  // Summary
  doc.moveDown();
  doc.fontSize(14).text('Summary');
  doc.fontSize(12).text(`Total Users: ${data.total}`);
  doc.text(`Active: ${data.active}`);
  doc.text(`New in Period: ${data.new}`);

  return doc;
};
```

### Templates de Excel

```typescript
// templates/users-report.excel.ts
export const generateUsersReportExcel = async (data: UserReportData) => {
  const workbook = new ExcelJS.Workbook();
  const sheet = workbook.addWorksheet('Users');

  // Headers
  sheet.columns = [
    { header: 'Name', key: 'name', width: 30 },
    { header: 'Email', key: 'email', width: 35 },
    { header: 'Plan', key: 'plan', width: 15 },
    { header: 'Status', key: 'status', width: 12 },
    { header: 'Created', key: 'createdAt', width: 20 }
  ];

  // Data rows
  data.users.forEach(user => sheet.addRow(user));

  // Styling
  sheet.getRow(1).font = { bold: true };

  return workbook;
};
```

## Implementacion Frontend

### Componentes
- `ReportGenerator` - UI para generar reportes
- `ReportFilters` - Filtros de reportes
- `ReportDownloadButton` - Boton de descarga
- `ReportEmailModal` - Modal para enviar por email

### Paginas
- `/reports` - Lista de reportes disponibles
- `/reports/generate` - Generador de reportes

### Hooks
- `useReportDownload` - Descarga de reportes
- `useReportEmail` - Envio por email

## Flujos

### Descarga Directa
```
1. Usuario selecciona tipo de reporte
2. Configura filtros y formato
3. Click "Download"
4. Backend genera reporte
5. Browser descarga archivo
```

### Envio por Email
```
1. Usuario selecciona tipo de reporte
2. Configura filtros y formato
3. Ingresa destinatarios
4. Click "Send"
5. Backend genera reporte
6. Backend envia email con adjunto
7. Muestra confirmacion
```

## Seguridad

1. **Permisos:** Solo usuarios con rol admin pueden generar reportes
2. **Tenant Isolation:** Reportes solo incluyen datos del tenant
3. **Rate Limiting:** Limitar generacion de reportes (costoso)
4. **Audit Log:** Registrar cada reporte generado
5. **Data Masking:** Ocultar datos sensibles si aplica

## Performance

1. **Limite de registros:** Max 10,000 registros por reporte
2. **Streaming:** PDFs grandes se generan con streaming
3. **Background Jobs:** Reportes muy grandes se procesan async
4. **Cache:** Templates compilados se cachean

## Criterios de Aceptacion

- [ ] Generar PDF de usuarios con formato profesional
- [ ] Generar Excel de usuarios con datos tabulares
- [ ] Generar CSV de audit log
- [ ] Filtros por fecha funcionan correctamente
- [ ] Envio por email funciona
- [ ] Limite de 10,000 registros se respeta
- [ ] Reportes solo muestran datos del tenant
- [ ] Tests unitarios con cobertura >70%

## Dependencias

- SAAS-003 (Users) - Datos de usuarios
- SAAS-004 (Billing) - Datos de billing
- SAAS-008 (Audit) - Datos de auditoria
- SAAS-013 (Email) - Envio de reportes por email
- SAAS-016 (Analytics) - Datos de uso (opcional)

## Wireframes

```
+------------------------------------------+
|  Reports                                 |
+------------------------------------------+
|                                          |
|  Report Type:  [Users        v]          |
|  Format:       [PDF v]                   |
|                                          |
|  +-- Filters ---------------------------+|
|  | Date Range: [2026-01-01] to [01-31]  ||
|  | Status:     [Active v]               ||
|  | Plan:       [All v]                  ||
|  +--------------------------------------+|
|                                          |
|  [Download]  [Send by Email]             |
|                                          |
+------------------------------------------+

+------------------------------------------+
|  Send Report by Email                [X] |
+------------------------------------------+
|                                          |
|  Recipients:                             |
|  [admin@company.com                   ]  |
|  [+ Add recipient]                       |
|                                          |
|  Subject:                                |
|  [Monthly Users Report                ]  |
|                                          |
|  Message (optional):                     |
|  [                                    ]  |
|  [                                    ]  |
|                                          |
|  [Cancel]              [Send Report]     |
|                                          |
+------------------------------------------+
```

---

*SAAS-017 v1.0.0 - Template SaaS*