# US-MGN007-004: Consultar y Generar Reportes de Auditoria

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN007-004 |
| **Modulo** | MGN-007 Audit |
| **Sprint** | Sprint 5 |
| **Prioridad** | P1 - Alta |
| **Story Points** | 6 |
| **Estado** | Ready |
| **RF Relacionado** | RF-AUDIT-004 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** administrador del sistema
**Quiero** buscar en logs y generar reportes de auditoria
**Para** realizar analisis forense, cumplir con normativas y monitorear operaciones

---

## Descripcion

El sistema proporciona busqueda avanzada en todos los tipos de logs, generacion de reportes en multiples formatos, reportes programados por email y dashboard de metricas. Incluye archivado automatico de logs antiguos.

### Contexto

- Busqueda avanzada con multiples filtros
- Exportacion a CSV, XLSX, PDF, JSON
- Reportes programados automaticos
- Dashboard con metricas en tiempo real
- Archivado para cumplimiento normativo

---

## Criterios de Aceptacion

### Escenario 1: Busqueda avanzada en logs

```gherkin
Given un administrador con permiso "audit.search"
When envia POST /api/v1/audit/search con filtros:
  | from | "2025-12-01" |
  | to | "2025-12-05" |
  | entityType | "users" |
  | action | ["update", "delete"] |
Then retorna logs que coinciden con todos los filtros
  And incluye meta con total, page, queryTime
```

### Escenario 2: Busqueda de texto libre

```gherkin
Given logs con diferentes descripciones
When busca con searchText = "email change"
Then retorna logs donde description o metadata contienen el texto
  And soporta busqueda case-insensitive
```

### Escenario 3: Exportar a CSV

```gherkin
Given resultados de busqueda
When solicita exportar con format = "csv"
  And cantidad <= 100,000 registros
Then el sistema genera archivo CSV
  And retorna downloadUrl con expiracion
```

### Escenario 4: Exportar a PDF

```gherkin
Given resultados de busqueda
When solicita exportar con format = "pdf"
  And cantidad > 1,000 registros
Then el sistema responde con error
  And indica limite de 1,000 para PDF
```

### Escenario 5: Generar reporte asincrono

```gherkin
Given una busqueda con muchos resultados
When solicita POST /api/v1/audit/reports
Then retorna:
  | jobId | "uuid" |
  | status | "processing" |
  | estimatedTime | 30 |
  And se puede consultar progreso con GET /reports/:jobId
```

### Escenario 6: Crear reporte programado

```gherkin
Given administrador con permiso "audit.reports.schedule"
When crea POST /api/v1/audit/reports/scheduled
  | name | "Reporte Semanal" |
  | schedule | "0 8 * * 1" |
  | recipients | ["admin@company.com"] |
Then el reporte se guarda
  And se calcula nextRunAt = proximo lunes 8am
```

### Escenario 7: Ejecutar reporte programado

```gherkin
Given reporte programado activo
When llega la hora programada
Then el sistema genera el reporte
  And lo envia por email a los recipients
  And actualiza lastRunAt y nextRunAt
```

### Escenario 8: Ver dashboard de auditoria

```gherkin
Given logs de diferentes tipos
When accede a GET /api/v1/audit/dashboard
Then retorna:
  | totalRecords | numero total |
  | recordsToday | registros de hoy |
  | topUsers | usuarios mas activos |
  | activityTrend | tendencia por fecha |
```

### Escenario 9: Configurar alerta de auditoria

```gherkin
Given administrador con permiso "audit.alerts.manage"
When crea alerta:
  | condition | { logType: "audit", action: "delete", threshold: 100 } |
  | windowMinutes | 5 |
  | notify | ["admin@company.com"] |
Then la alerta se activa
  And notifica si hay > 100 deletes en 5 minutos
```

### Escenario 10: Consultar politicas de retencion

```gherkin
Given diferentes tipos de logs
When consulta politicas de retencion
Then muestra:
  | Audit Trail | 1 año online, 7 años archivo |
  | Access Logs | 90 dias online, 1 año archivo |
  | Security Events | 2 años online, 7 años archivo |
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  BUSQUEDA DE AUDITORIA                                            |
+------------------------------------------------------------------+

FILTROS
+------------------------------------------------------------------+
| Desde: [2025-12-01]  Hasta: [2025-12-05]                         |
| Tipo de Log: [Audit Trail v]  Tipo Entidad: [users v]            |
| Acciones: [✓ Create] [✓ Update] [✓ Delete] [ ] Restore           |
| Usuario: [_______________]  IP: [_______________]                 |
| Buscar: [email change________________________]                    |
|                                                                   |
|                    [Limpiar]  [=== Buscar ===]                   |
+------------------------------------------------------------------+

RESULTADOS (250 encontrados, 45ms)
+------------------------------------------------------------------+
| [Exportar: CSV v] [Crear Reporte Programado]                     |
+------------------------------------------------------------------+
| FECHA              | TIPO    | ENTIDAD  | ACCION | USUARIO      |
+------------------------------------------------------------------+
| 2025-12-05 10:30   | audit   | users    | update | admin@...    |
| 2025-12-05 10:00   | audit   | users    | delete | hr@...       |
| 2025-12-04 15:00   | audit   | contacts | update | sales@...    |
+------------------------------------------------------------------+
                                              [< Anterior] [1] [Siguiente >]

Modal: Crear Reporte Programado
+------------------------------------------------------------------+
| NUEVO REPORTE PROGRAMADO                                    [X]  |
+------------------------------------------------------------------+
| Nombre*                                                           |
| [Reporte Semanal de Actividad                              ]     |
|                                                                   |
| Tipo de Reporte: [Actividad v]                                   |
| Formato: ( ) CSV  (•) XLSX  ( ) PDF                              |
|                                                                   |
| Programacion                                                      |
| Frecuencia: [Semanal v]  Dia: [Lunes v]  Hora: [08:00 v]        |
|                                                                   |
| Destinatarios*                                                    |
| [admin@company.com                                           ] [+]|
| [auditor@company.com                                         ] [x]|
|                                                                   |
|                              [Cancelar]  [=== Guardar ===]       |
+------------------------------------------------------------------+

DASHBOARD
+------------------------------------------------------------------+
| METRICAS DE AUDITORIA                              [Periodo: 7d v]|
+------------------------------------------------------------------+
|                                                                   |
| +-------------+  +-------------+  +-------------+  +-------------+|
| | Total Logs  |  | Hoy         |  | Usuarios    |  | Eventos Seg ||
| | 125,430     |  | 1,234       |  | 45 activos  |  | 7 pendiente ||
| +-------------+  +-------------+  +-------------+  +-------------+|
|                                                                   |
| [GRAFICO: Actividad por dia - ultimos 7 dias]                    |
|     ^                                                             |
|   1500|     ___                                                   |
|   1000|___ /   \___                                               |
|    500|            \___                                           |
|      +---+---+---+---+---+---+---+                                |
|        L   M   M   J   V   S   D                                  |
|                                                                   |
| TOP USUARIOS                    | TOP ENTIDADES                   |
| 1. admin@...  (234 acciones)    | 1. users (450 cambios)         |
| 2. hr@...     (156 acciones)    | 2. contacts (320 cambios)      |
| 3. sales@...  (89 acciones)     | 3. settings (45 cambios)       |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| POST | /audit/search | Busqueda avanzada |
| POST | /audit/reports | Generar reporte |
| GET | /audit/reports/:jobId | Estado de reporte |
| POST | /audit/reports/scheduled | Crear programado |
| GET | /audit/reports/scheduled | Listar programados |
| GET | /audit/dashboard | Dashboard metricas |
| POST | /audit/alerts | Crear alerta |

### Limites de Exportacion

| Formato | Limite |
|---------|--------|
| CSV | 100,000 registros |
| XLSX | 50,000 registros |
| PDF | 1,000 registros |
| JSON | 100,000 registros |

### Retencion

| Tipo | Online | Archivo |
|------|--------|---------|
| Audit Trail | 1 año | 7 años (S3/Glacier) |
| Access Logs | 90 dias | 1 año |
| Security Events | 2 años | 7 años |

---

## Definicion de Done

- [ ] Busqueda avanzada con multiples filtros
- [ ] Exportacion CSV, XLSX, PDF, JSON
- [ ] Jobs asincronos para reportes grandes
- [ ] Reportes programados con cron
- [ ] Envio por email
- [ ] Dashboard con metricas
- [ ] Sistema de alertas configurables
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| US-MGN007-001 | Audit trail (datos) |
| US-MGN007-002 | Access logs (datos) |
| US-MGN007-003 | Security events (datos) |
| Bull Queue | Para jobs asincronos |
| MGN-008 Notifications | Para envio email |

### Bloquea

| Item | Descripcion |
|------|-------------|
| Ninguno | Modulo final de audit |

---

## Historial

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | Requirements-Analyst | Creacion inicial |
