template-saas/docs/01-modulos/SAAS-008-audit-logs.md

SAAS-008: Audit Logs

Metadata

• Codigo: SAAS-008
• Modulo: Audit
• Prioridad: P1
• Estado: Pendiente
• Fase: 3 - Features Core

Descripcion

Sistema de auditoria completo: registro automatico de acciones, cambios en entidades, accesos de usuario, con busqueda y exportacion para compliance.

Objetivos

1. Registro automatico de acciones
2. Tracking de cambios (before/after)
3. Log de accesos
4. Busqueda y filtrado
5. Exportacion para compliance

Alcance

Incluido

• Logs de CREATE/UPDATE/DELETE
• Diff de cambios (before/after)
• Logs de autenticacion
• IP y user agent
• Retencion configurable
• Busqueda full-text
• Export CSV/JSON

Excluido

• Replay de acciones
• Alertas automaticas por patrones
• Integracion SIEM

Modelo de Datos

Tablas (schema: audit)

audit_logs

• id, tenant_id, user_id
• action (create/update/delete/read/auth)
• entity_type, entity_id
• changes (JSONB: {before, after, diff})
• ip_address, user_agent
• metadata (JSONB)
• created_at

auth_logs

• id, tenant_id, user_id
• action (login/logout/failed/mfa)
• ip_address, user_agent
• location (JSONB: {country, city})
• success, failure_reason
• created_at

Tipos de Eventos

Acciones de Datos

Accion	Descripcion
entity.created	Registro creado
entity.updated	Registro modificado
entity.deleted	Registro eliminado
entity.viewed	Registro consultado
bulk.import	Importacion masiva
bulk.export	Exportacion masiva

Acciones de Auth

Accion	Descripcion
auth.login	Login exitoso
auth.logout	Logout
auth.failed	Login fallido
auth.mfa	MFA verificado
auth.password_change	Password cambiado
auth.session_revoked	Sesion revocada

Endpoints API

Metodo	Endpoint	Descripcion
GET	/audit/logs	Listar logs
GET	/audit/logs/:id	Detalle de log
GET	/audit/entity/:type/:id	Logs de entidad
GET	/audit/user/:id	Logs de usuario
GET	/audit/auth	Logs de auth
GET	/audit/export	Exportar logs
GET	/audit/stats	Estadisticas

Filtros de Busqueda

interface AuditFilters {
  dateFrom?: Date;
  dateTo?: Date;
  userId?: string;
  action?: string;
  entityType?: string;
  entityId?: string;
  ipAddress?: string;
  search?: string; // full-text
}

Implementacion

Interceptor Automatico

@Injectable()
export class AuditInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    const request = context.switchToHttp().getRequest();
    const before = request.body;

    return next.handle().pipe(
      tap(async (result) => {
        await this.auditService.log({
          userId: request.user.id,
          action: this.getAction(request.method),
          entityType: this.getEntityType(request.path),
          entityId: result?.id,
          changes: { before, after: result },
          ip: request.ip,
          userAgent: request.headers['user-agent']
        });
      })
    );
  }
}

Decorator Manual

@AuditLog('custom.action')
async customOperation() {
  // Se registra automaticamente
}

Retencion de Datos

Plan	Retencion
Free	7 dias
Starter	30 dias
Pro	90 dias
Enterprise	1 año (configurable)

Estructura de Log

interface AuditLog {
  id: string;
  tenantId: string;
  userId: string;
  userName: string;
  action: string;
  entityType: string;
  entityId: string;
  changes: {
    before: object | null;
    after: object | null;
    diff: object; // solo campos cambiados
  };
  metadata: {
    ip: string;
    userAgent: string;
    location?: {
      country: string;
      city: string;
    };
    requestId: string;
  };
  createdAt: Date;
}

Entregables

Entregable	Estado	Archivo
audit.module.ts	Pendiente	modules/audit/
audit.service.ts	Pendiente	services/
audit.interceptor.ts	Pendiente	interceptors/
DDL audit schema	Pendiente	ddl/schemas/audit/

Dependencias

Depende de

• SAAS-001 (Auth)
• SAAS-002 (Tenants)
• SAAS-003 (Users)
• SAAS-005 (Plans - retencion)

Bloquea a

• Compliance reports
• Security dashboards

Criterios de Aceptacion

• CRUD se registra automaticamente
• Auth events se registran
• Before/after se captura
• Busqueda funciona
• Export CSV funciona
• Retencion se aplica

Feature Flag

// Solo disponible en Enterprise
@RequiresFeature('audit_logs')
@Get('/audit/logs')
async getAuditLogs() {
  // ...
}

---

Ultima actualizacion: 2026-01-07