workspace/projects/gamilit/docs/90-transversal/deuda-tecnica/DEUDA-TECNICA-ENUMS-H-034.md

Deuda Técnica: ENUMs Sin Uso (H-034)

Fecha: 2025-11-19 Auditoría: DB-124 Hallazgo: H-034 Prioridad: P2 (Mediana) Estado: 📋 DOCUMENTADO (Backlog)

---

Resumen

Se identificaron 10 ENUMs sin uso en schemas audit_logging y social_features que tienen tablas implementadas, pero las tablas usan tipos primitivos (TEXT/VARCHAR) con CHECK constraints en lugar de ENUMs.

---

ENUMs Afectados

audit_logging (6 ENUMs - 0% uso)

ENUM	Valores	Columna Objetivo	Bloqueador
audit_action	create, update, delete, login, logout, access, export, import	audit_logs.action	✅ YA IMPLEMENTADO
alert_severity	info, warning, error, critical	audit_logs.severity, system_alerts.severity	CHECK constraint + índice WHERE
alert_status	active, acknowledged, resolved, ignored	system_alerts.status	CHECK constraint + índice WHERE
log_level	debug, info, warning, error, critical	system_logs.log_level	-
metric_type	engagement, performance, completion, time_spent, accuracy, streak, social_interaction	performance_metrics.metric_type	-
aggregation_period	daily, weekly, monthly, quarterly, yearly	(sin columna)	Sin uso planeado

social_features (4 ENUMs - 25% uso)

ENUM	Valores	Columna Objetivo	Bloqueador
classroom_role	teacher, student, assistant	teacher_classrooms.role	✅ YA IMPLEMENTADO
team_role	leader, member, coordinator	team_members.role	✅ YA IMPLEMENTADO
friendship_status	pending, accepted, blocked	friendships.status	Policy RLS
social_event_type	competition, collaboration, challenge, tournament, workshop	social_interactions.interaction_type	Requiere análisis

Total: 10 ENUMs (3 implementados, 7 pendientes)

---

Problema Técnico

Las tablas usan CHECK constraints en lugar de ENUMs:

-- Ejemplo: system_alerts
ALTER TABLE audit_logging.system_alerts
  ADD CONSTRAINT system_alerts_severity_check
  CHECK (severity = ANY (ARRAY['low'::text, 'medium'::text, 'high'::text, 'critical'::text]));

ALTER TABLE audit_logging.system_alerts
  ADD CONSTRAINT system_alerts_status_check
  CHECK (status = ANY (ARRAY['open'::text, 'acknowledged'::text, 'resolved'::text, 'suppressed'::text]));

Además, hay índices con predicados TEXT:

CREATE INDEX idx_alerts_open
  ON audit_logging.system_alerts(status, severity)
  WHERE status = 'open'::text;

Impacto de migración:

• Requiere DROP constraints (6+ constraints)
• Requiere DROP/CREATE índices con predicados
• Requiere ALTER TYPE con trigger deshabilitado
• Requiere recrear constraints con ENUM values
• ~60-90 minutos de trabajo

---

Razón de NO Implementación Inmediata

1. Tablas vacías: audit_logging tiene 0 registros, social_features solo 5 registros
2. Bajo ROI: Trabajo extenso para beneficio mínimo en entorno actual
3. CHECK constraints suficientes: Validan datos correctamente
4. Índices funcionales: Funcionan correctamente con TEXT

---

Decisión

Mantener ENUMs definidos y documentar como deuda técnica para refactorización futura.

Razones:

• Los ENUMs ya existen y no causan problemas
• Si en futuro se decide refactorizar, ya están definidos
• Eliminarlos y recrearlos después sería trabajo adicional

---

Plan de Refactorización Futura

Cuándo ejecutar

Ejecutar cuando se cumpla cualquiera de estas condiciones:

1. Alta carga de datos: Tablas superan 10,000 registros
2. Performance crítica: Queries de audit_logging/social_features son >10% de carga total
3. Migración mayor: Se planea refactorización de schemas completos
4. Nuevo proyecto: Se implementa auditoría/social features desde cero

Pasos de migración (CUANDO se ejecute)

-- 1. Desactivar triggers
ALTER TABLE audit_logging.system_alerts DISABLE TRIGGER ALL;

-- 2. DROP CHECK constraints
ALTER TABLE audit_logging.system_alerts
  DROP CONSTRAINT system_alerts_severity_check,
  DROP CONSTRAINT system_alerts_status_check;

-- 3. DROP índices con predicados TEXT
DROP INDEX audit_logging.idx_alerts_open;

-- 4. ALTER columnas a ENUM
ALTER TABLE audit_logging.system_alerts
  ALTER COLUMN severity TYPE audit_logging.alert_severity
    USING severity::audit_logging.alert_severity,
  ALTER COLUMN status TYPE audit_logging.alert_status
    USING CASE
      WHEN status = 'open' THEN 'active'::audit_logging.alert_status
      WHEN status::text = ANY(ARRAY['active', 'acknowledged', 'resolved', 'ignored'])
      THEN status::audit_logging.alert_status
      ELSE 'active'::audit_logging.alert_status
    END;

-- 5. RECREAR índices con ENUM
CREATE INDEX idx_alerts_open
  ON audit_logging.system_alerts(status, severity)
  WHERE status = 'active'::audit_logging.alert_status;

-- 6. Reactivar triggers
ALTER TABLE audit_logging.system_alerts ENABLE TRIGGER ALL;

Repetir para todas las tablas afectadas.

Tiempo estimado (cuando se ejecute)

• Análisis de datos existentes: 30 min
• Migración de 6+ tablas: 60-90 min
• Testing: 30 min
• Total: 2-2.5 horas

---

Beneficios de Migración Futura

1. Validación a nivel BD: Imposible insertar valores inválidos
2. Performance: Índices más eficientes con ENUMs
3. Autocomplete: Herramientas de BD muestran valores permitidos
4. Menor storage: ENUMs usan menos espacio que TEXT
5. Type safety: APIs y ORMs detectan errores en compile-time

---

Estado Actual

Implementado:

• ✅ audit_logs.action → audit_action ENUM
• ✅ teacher_classrooms.role → classroom_role ENUM
• ✅ team_members.role → team_role ENUM

Pendiente (backlog):

• ⏳ audit_logs.severity → alert_severity ENUM
• ⏳ system_alerts.severity → alert_severity ENUM
• ⏳ system_alerts.status → alert_status ENUM
• ⏳ system_logs.log_level → log_level ENUM
• ⏳ performance_metrics.metric_type → metric_type ENUM
• ⏳ friendships.status → friendship_status ENUM
• ⏳ social_interactions.interaction_type → social_event_type ENUM (requiere análisis)

Sin uso planeado:

• ❌ aggregation_period → (eliminar si no se usa en 6 meses)

---

Referencias

• Auditoría: orchestration/database/DB-124/
• Hallazgo: H-034
• Scripts parciales:
  • ddl/schemas/_migrations/01-implement-enums-audit-social.sql (v1 - fallida)
  • ddl/schemas/_migrations/02-implement-enums-audit-social-v2.sql (v2 - parcial)
• Documentación: Este archivo

---

Revisión

Próxima revisión: 2025-05 (6 meses) Criterio de cierre:

• Opción A: Migración completa ejecutada
• Opción B: Se decide eliminar ENUMs sin uso si no hay plan de implementación

---

Responsable: Database Agent Estado: 📋 BACKLOG (Deuda Técnica Documentada)