michangarrito/docs/01-epicas/MCH-031-auditoria-empresarial.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	dependencies
EPIC-MCH-031	Epic	MCH-031: Auditoria Empresarial	MCH-031	Planificado	7	P1	2026-01-10	2026-01-10	4.0.1	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

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

// En tenant_settings
{
  "audit": {
    "retention_days": 90,
    "archive_before_delete": true,
    "notify_before_purge": true
  }
}

ADRs Relacionados

• ADR-0008: Audit Log Retention

---

Ultima actualizacion: 2026-01-10 Autor: Architecture Team