# RF-AUDIT-004: Consulta y Reportes de Auditoria

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-AUDIT-004 |
| **Modulo** | MGN-007 Audit |
| **Titulo** | Consulta y Reportes de Auditoria |
| **Prioridad** | P1 - Alta |
| **Estado** | Draft |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe proporcionar capacidades avanzadas de consulta, busqueda y generacion de reportes sobre los logs de auditoria, permitiendo analisis forense, cumplimiento normativo y monitoreo operacional.

---

## Requisitos Funcionales

### RF-AUDIT-004.1: Busqueda Avanzada

El sistema permite buscar en todos los tipos de logs:

```typescript
interface AuditSearchQuery {
  // Filtros temporales
  from: Date;
  to: Date;

  // Filtros de entidad
  entityType?: string;
  entityId?: UUID;

  // Filtros de usuario
  userId?: UUID;
  userEmail?: string;

  // Filtros de accion
  action?: AuditAction[];
  eventType?: SecurityEventType[];
  severity?: Severity[];

  // Filtros de origen
  ipAddress?: string;
  countryCode?: string;

  // Busqueda de texto
  searchText?: string;  // Busca en description, metadata

  // Paginacion
  page: number;
  limit: number;
  sortBy: string;
  sortOrder: 'asc' | 'desc';
}
```

### RF-AUDIT-004.2: Tipos de Reportes

| Reporte | Descripcion | Programable |
|---------|-------------|-------------|
| Activity Report | Actividad por usuario/periodo | Si |
| Security Report | Eventos de seguridad | Si |
| Compliance Report | Accesos a datos sensibles | Si |
| Change Report | Cambios en entidades criticas | Si |
| Access Report | Accesos por recurso | Si |

### RF-AUDIT-004.3: Exportacion de Datos

Formatos soportados:

```typescript
enum ExportFormat {
  CSV = 'csv',
  XLSX = 'xlsx',
  PDF = 'pdf',
  JSON = 'json'
}

// Limites
const EXPORT_LIMITS = {
  csv: 100000,    // 100k registros max
  xlsx: 50000,    // 50k registros max
  pdf: 1000,      // 1k registros max
  json: 100000    // 100k registros max
};
```

### RF-AUDIT-004.4: Reportes Programados

```typescript
interface ScheduledReport {
  id: UUID;
  name: string;
  reportType: ReportType;
  filters: AuditSearchQuery;
  format: ExportFormat;
  schedule: CronExpression;  // "0 8 * * 1" = Lunes 8am
  recipients: string[];      // Emails
  isActive: boolean;
  lastRunAt: TIMESTAMPTZ;
  nextRunAt: TIMESTAMPTZ;
}
```

### RF-AUDIT-004.5: Dashboard de Auditoria

Metricas en tiempo real:

```typescript
interface AuditDashboard {
  // Volumetria
  totalRecords: number;
  recordsToday: number;
  recordsThisWeek: number;

  // Actividad
  activeUsers: number;
  topUsers: { userId: UUID; name: string; count: number }[];

  // Cambios
  entitiesModified: number;
  topEntities: { type: string; count: number }[];

  // Seguridad
  securityEventsCount: number;
  unresolvedEvents: number;

  // Tendencias
  activityTrend: { date: string; count: number }[];
}
```

### RF-AUDIT-004.6: Retencion y Archivado

Politicas de retencion:

| Tipo de Log | Retencion Online | Archivo |
|-------------|------------------|---------|
| Audit Trail | 1 año | 7 años |
| Access Logs | 90 dias | 1 año |
| Security Events | 2 años | 7 años |

```typescript
// Proceso de archivado
interface ArchiveJob {
  logType: 'audit' | 'access' | 'security';
  olderThan: Date;
  destination: 's3' | 'glacier';
  compression: 'gzip' | 'zstd';
  encryption: boolean;
}
```

### RF-AUDIT-004.7: Alertas de Auditoria

Alertas configurables basadas en patrones:

```typescript
interface AuditAlert {
  id: UUID;
  name: string;
  condition: {
    logType: 'audit' | 'access' | 'security';
    field: string;
    operator: '=' | '>' | '<' | 'contains';
    value: any;
    windowMinutes: number;
    threshold: number;
  };
  actions: {
    notify: string[];  // Emails
    webhook?: string;
    severity: Severity;
  };
  isActive: boolean;
}

// Ejemplo: Alertar si hay mas de 100 deletes en 5 minutos
{
  condition: {
    logType: 'audit',
    field: 'action',
    operator: '=',
    value: 'delete',
    windowMinutes: 5,
    threshold: 100
  }
}
```

---

## Operaciones

### Busqueda en Logs

```typescript
POST /api/v1/audit/search
{
  "from": "2025-12-01",
  "to": "2025-12-05",
  "entityType": "users",
  "action": ["update", "delete"],
  "page": 1,
  "limit": 50
}

Response:
{
  "data": [...],
  "meta": {
    "total": 250,
    "page": 1,
    "limit": 50,
    "queryTime": 45  // ms
  }
}
```

### Generar Reporte

```typescript
POST /api/v1/audit/reports
{
  "reportType": "activity",
  "filters": { ... },
  "format": "xlsx"
}

Response:
{
  "jobId": "uuid",
  "status": "processing",
  "estimatedTime": 30  // segundos
}

// Luego:
GET /api/v1/audit/reports/:jobId

Response:
{
  "jobId": "uuid",
  "status": "completed",
  "downloadUrl": "https://...",
  "expiresAt": "2025-12-05T12:00:00Z"
}
```

### Crear Reporte Programado

```typescript
POST /api/v1/audit/reports/scheduled
{
  "name": "Reporte Semanal de Actividad",
  "reportType": "activity",
  "filters": { "entityType": "users" },
  "format": "pdf",
  "schedule": "0 8 * * 1",
  "recipients": ["admin@company.com"]
}
```

---

## Reglas de Negocio

| ID | Regla | Severidad |
|----|-------|-----------|
| BR-001 | Exportaciones grandes son asincronas | Performance |
| BR-002 | Reportes PDF limitados a 1000 registros | Performance |
| BR-003 | Archivos expirados se eliminan despues de 24h | Storage |
| BR-004 | Solo admins pueden crear reportes programados | Security |
| BR-005 | Archivado respeta politicas de retencion legal | Compliance |

---

## Criterios de Aceptacion

- [ ] Busqueda con multiples filtros
- [ ] Exportacion a CSV, XLSX, PDF, JSON
- [ ] Reportes programados con email
- [ ] Dashboard con metricas en tiempo real
- [ ] Archivado automatico de logs antiguos
- [ ] Alertas configurables
- [ ] Performance < 1s para consultas tipicas

---

## Historial

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