erp-core/docs/02-fase-core-business/MGN-007-audit/requerimientos/RF-AUDIT-004.md

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:

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:

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

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:

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

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

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

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

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

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