--- 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) --- **Ultima actualizacion:** 2026-01-10 **Autor:** Architecture Team