364 lines
9.8 KiB
Markdown
364 lines
9.8 KiB
Markdown
---
|
|
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*
|