---
id: EPIC-MCH-031
type: Epic
title: "MCH-031: Auditoria Empresarial"
code: MCH-031
status: Planificado
phase: 7
priority: P1
created_at: 2026-01-10
updated_at: 2026-01-10
simco_version: "4.0.1"
dependencies:
  blocks: []
  depends_on: []
---

# MCH-031: Auditoria Empresarial

## Metadata
- **Codigo:** MCH-031
- **Fase:** 7 - Expansion
- **Prioridad:** P1
- **Estado:** Planificado
- **Story Points:** 5
- **Sprint Objetivo:** Sprint 7

## Descripcion

Implementar sistema de auditoria completo con registro de todas las acciones CRUD, politica de retencion configurable y capacidad de exportacion para compliance. Permite trazabilidad completa de operaciones y deteccion de actividades sospechosas.

## Objetivos

1. Registrar todas las acciones de usuarios en el sistema
2. Mantener historial de cambios con valores antes/despues
3. Configurar politicas de retencion por tenant
4. Exportar logs para auditorias externas
5. Visualizar actividad en dashboard admin

## Alcance

### Incluido
- Audit logs para CREATE, UPDATE, DELETE
- Activity logs para acciones de usuario (login, logout, view)
- Interceptor global NestJS
- Politica de retencion (30, 90, 365 dias)
- Exportacion CSV
- Visor de logs en admin

### Excluido
- SIEM integration (futuro)
- Real-time alerting (ver notificaciones)
- Forensic analysis tools

## Arquitectura

```
                    ┌─────────────────────────────────────┐
                    │      MCH-031: Auditoria             │
                    └─────────────────────────────────────┘
                                      │
              ┌───────────────────────┴───────────────────────┐
              ▼                                               ▼
   ┌─────────────────────┐                      ┌─────────────────────┐
   │    Audit Logs       │                      │   Activity Logs     │
   │  (data changes)     │                      │  (user actions)     │
   └──────────┬──────────┘                      └──────────┬──────────┘
              │                                            │
              └──────────────────┬─────────────────────────┘
                                 ▼
              ┌─────────────────────────────────────────┐
              │           AuditInterceptor              │
              │    (NestJS Global Interceptor)          │
              └─────────────────────────────────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
        ┌──────────┐      ┌──────────┐      ┌──────────┐
        │  schema  │      │ Retencion│      │  Export  │
        │  audit   │      │  Policy  │      │   CSV    │
        └──────────┘      └──────────┘      └──────────┘
```

## Entregables

| Entregable | Estado | Sprint | Ubicacion |
|------------|--------|--------|-----------|
| Schema audit (DDL) | Planificado | 7 | `database/schemas/14-audit.sql` |
| AuditInterceptor | Planificado | 7 | `apps/backend/src/common/interceptors/` |
| AuditService | Planificado | 7 | `apps/backend/src/modules/audit/` |
| AuditController | Planificado | 7 | `apps/backend/src/modules/audit/` |
| Retention Job | Planificado | 7 | `apps/backend/src/jobs/` |
| UI Visor logs | Planificado | 7 | `apps/web/src/pages/admin/audit/` |

## Dependencias

### Depende de
- Ninguna (puede ejecutarse en paralelo con MCH-029)

### Bloquea a
- Ninguna

---

## Historias de Usuario

### MCH-US-107: Registro de Acciones

**Como** administrador
**Quiero** ver un registro de todas las acciones realizadas en el sistema
**Para** tener trazabilidad y detectar actividades sospechosas

**Story Points:** 3

**Criterios de Aceptacion:**
- [CA-107-1] Registra CREATE, UPDATE, DELETE automaticamente
- [CA-107-2] Incluye: usuario, timestamp, IP, user-agent
- [CA-107-3] Guarda valor anterior y nuevo en cambios (old_value, new_value)
- [CA-107-4] Filtrable por usuario, accion, entidad, rango de fechas
- [CA-107-5] Exportable a CSV con columnas seleccionables

**Tareas:**
| ID | Tarea | Tipo | SP |
|----|-------|------|-----|
| MCH-TT-107-01 | DDL schema audit (audit_logs, activity_logs) | DDL | 0.5 |
| MCH-TT-107-02 | AuditInterceptor global | Backend | 0.5 |
| MCH-TT-107-03 | AuditService con metodos log/query | Backend | 0.5 |
| MCH-TT-107-04 | AuditController (GET /audit/logs) | Backend | 0.25 |
| MCH-TT-107-05 | UI visor de logs con filtros | Frontend | 0.5 |
| MCH-TT-107-06 | Exportacion CSV | Backend | 0.25 |
| MCH-TT-107-07 | Tests | Test | 0.25 |
| MCH-TT-107-08 | Documentacion | Docs | 0.25 |

---

### MCH-US-108: Politica de Retencion

**Como** administrador
**Quiero** configurar cuanto tiempo se guardan los logs
**Para** cumplir con politicas de retencion y optimizar almacenamiento

**Story Points:** 2

**Criterios de Aceptacion:**
- [CA-108-1] Configuracion de dias de retencion: 30, 90, 180, 365
- [CA-108-2] Job automatico de limpieza (cron diario)
- [CA-108-3] Opcion de archivar a storage antes de eliminar
- [CA-108-4] Notificacion por email antes de purga (7 dias antes)

**Tareas:**
| ID | Tarea | Tipo | SP |
|----|-------|------|-----|
| MCH-TT-108-01 | Configuracion de retencion en tenant_settings | Backend | 0.25 |
| MCH-TT-108-02 | Job de limpieza con BullMQ (cron) | Backend | 0.5 |
| MCH-TT-108-03 | Archivado opcional a storage (S3) | Backend | 0.5 |
| MCH-TT-108-04 | Tests | Test | 0.25 |
| MCH-TT-108-05 | Documentacion de politica de retencion | Docs | 0.5 |

---

## Resumen de Story Points

| Historia | SP | Sprint |
|----------|-----|--------|
| MCH-US-107: Registro de Acciones | 3 | 7 |
| MCH-US-108: Politica de Retencion | 2 | 7 |
| **TOTAL** | **5** | 7 |

---

## Criterios de Aceptacion de Epica

- [ ] Todas las acciones CRUD se registran automaticamente
- [ ] Logs visibles en dashboard admin
- [ ] Exportacion CSV funcional
- [ ] Job de limpieza ejecutandose diariamente
- [ ] Cobertura de tests >80%

## Notas Tecnicas

### Schema audit

```sql
CREATE SCHEMA IF NOT EXISTS audit;

CREATE TABLE audit.audit_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    user_id UUID,
    action VARCHAR(20) NOT NULL, -- CREATE, UPDATE, DELETE
    entity_type VARCHAR(100) NOT NULL, -- Product, Order, User
    entity_id UUID NOT NULL,
    old_value JSONB,
    new_value JSONB,
    ip_address INET,
    user_agent TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_audit_logs_tenant_date ON audit.audit_logs(tenant_id, created_at DESC);
CREATE INDEX idx_audit_logs_entity ON audit.audit_logs(entity_type, entity_id);
```

### Configuracion de Retencion
```typescript
// En tenant_settings
{
  "audit": {
    "retention_days": 90,
    "archive_before_delete": true,
    "notify_before_purge": true
  }
}
```

## ADRs Relacionados

- [ADR-0008: Audit Log Retention](../97-adr/ADR-0008-audit-log-retention.md)

---

## Especificaciones Tecnicas Detalladas (Ref: SAAS-008)

Esta seccion documenta las especificaciones del modulo de auditoria segun template-saas para garantizar alineacion arquitectonica.

### Estructura de Tabla audit_logs

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador unico |
| tenant_id | UUID | Tenant al que pertenece |
| user_id | UUID | Usuario que realizo la accion |
| action | VARCHAR | Tipo de accion (create/update/delete/read/auth) |
| entity_type | VARCHAR | Tipo de entidad afectada |
| entity_id | UUID | ID de la entidad afectada |
| changes | JSONB | Objeto con {before, after, diff} |
| ip_address | INET | Direccion IP del cliente |
| user_agent | TEXT | User agent del navegador |
| metadata | JSONB | Datos adicionales (requestId, location) |
| created_at | TIMESTAMP | Fecha de creacion |

### Tabla Adicional: auth_logs

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador unico |
| tenant_id | UUID | Tenant al que pertenece |
| user_id | UUID | Usuario relacionado |
| action | VARCHAR | Tipo (login/logout/failed/mfa) |
| ip_address | INET | Direccion IP |
| user_agent | TEXT | User agent |
| location | JSONB | {country, city} |
| success | BOOLEAN | Si fue exitoso |
| failure_reason | TEXT | Razon de fallo si aplica |
| created_at | TIMESTAMP | Fecha de creacion |

### Endpoints API del Modulo

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /audit/logs | Listar logs con paginacion y filtros |
| GET | /audit/logs/:id | Detalle de un log especifico |
| GET | /audit/entity/:type/:id | Logs de una entidad especifica |
| GET | /audit/user/:id | Logs de un usuario especifico |
| GET | /audit/auth | Logs de autenticacion |
| GET | /audit/export | Exportar logs (CSV/JSON) |
| GET | /audit/stats | Estadisticas de auditoria |

### Tipos de Acciones Soportadas

#### 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 Autenticacion
| 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 |

### Politica de Retencion por Plan

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

### Estructura de Log Completa

```typescript
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;
}
```

### Referencia

> Documentacion fuente: `/projects/template-saas/docs/01-modulos/SAAS-008-audit-logs.md`
> Version: 1.0.0

---

**Ultima actualizacion:** 2026-01-13
**Autor:** Architecture Team