template-saas/docs/01-modulos/SAAS-017-reports.md

id	title	type	status	priority	module	version	created_date	updated_date	story_points
SAAS-017	Reportes Exportables	Module	Specified	P2	reports	1.0.0	2026-01-24	2026-01-24	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:

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

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

{
  "pdfkit": "^0.15.0",
  "exceljs": "^4.4.0"
}

Templates de PDF

Los templates PDF se definen en codigo usando PDFKit:

// 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

// 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