workspace-v1/projects/gamilit/orchestration/agentes/architecture-analyst/PLAN-VALIDACION-CLEAN-CREATION-2025-11-29.md

Plan de Validación: Directiva de Creación Limpia

Fecha: 2025-11-29 Versión: 1.0.0 Estado: EN VALIDACIÓN Fase Actual: PLANIFICACIÓN

---

1. Resumen Ejecutivo

Este documento detalla el plan de corrección basado en la validación de la directiva de creación/recreación limpia de base de datos.

Resultado del Análisis

Área	Cumplimiento	Acciones Requeridas
DDL Base de Datos	96.4%	1 corrección menor
Migraciones DB	100%	Ninguna
Migraciones Backend	⚠️ Excepción	Integrar P0-001 a DDL
Documentación	85%	Actualizar 5 archivos
Trazabilidad	85%	Actualizar inventarios

---

2. Hallazgos Detallados

2.1 Violación DDL: archivo 24-alter_assignment_students.sql

Ubicación: /apps/database/ddl/schemas/educational_content/tables/24-alter_assignment_students.sql

Problema:

• Contiene 17 sentencias ALTER TABLE ... ADD COLUMN
• Nombre sugiere migración cuando es parte del DDL
• Viola semánticamente la política de creación limpia

Impacto Real: BAJO

• El archivo se ejecuta correctamente en recreación limpia
• Las columnas se crean con IF NOT EXISTS
• No hay pérdida de datos ni errores

Solución Propuesta:

1. Renombrar archivo a 09-assignment_students_grading.sql
2. Convertir ALTERs a definición de tabla extendida
3. Documentar como "extensión de tabla" en comentarios

2.2 Migración Backend P0-001

Ubicación: /apps/backend/migrations/P0-001-migrate-maya-rank-values.sql

Problema:

• Migración de datos P0 para corregir valores de Maya Rank
• No se ejecuta automáticamente
• Requiere intervención manual

Impacto: MEDIO

• Datos legacy necesitan corrección
• No afecta nuevas instalaciones

Solución Propuesta:

1. Integrar corrección de valores en seed de gamification_system.user_stats
2. Crear función de corrección en DDL como opcional
3. Documentar en README de seeds
4. Deprecar archivo de migración

2.3 Documentación Faltante

Archivos que requieren actualización:

Archivo	Problema	Acción
MASTER_INVENTORY.yml	Desactualizado (2025-11-24)	Regenerar de inventarios actuales
TEST_COVERAGE.yml	Esqueleto sin datos	Poblar con datos de cobertura real
TRAZA-TAREAS-INTEGRATION.md	Solo 506 bytes	Expandir con tareas de integración
DEPENDENCY_GRAPH.yml	Incompleto	Actualizar con dependencias actuales

2.4 Trazabilidad

Gaps identificados:

1. Sin documentación de flujo de datos Student→Teacher en pruebas E2E

   • No hay test cases documentados
   • Impacta validación de integración

2. Tipos duplicados en frontend

   • Achievement, UserStats, UserRank tienen 3-7 definiciones
   • Impacta mantenibilidad

---

3. Plan de Corrección

3.1 Prioridad P0 (Crítico - Inmediato)

CORR-CLEAN-001: Renombrar archivo DDL

# Acción
mv apps/database/ddl/schemas/educational_content/tables/24-alter_assignment_students.sql \
   apps/database/ddl/schemas/educational_content/tables/09-assignment_students_grading.sql

# Actualizar create-database.sh si es necesario
# Verificar que el nuevo nombre mantiene el orden de ejecución

Criterio de Aceptación:

• Archivo renombrado
• Script create-database.sh funciona sin errores
• Base de datos se recrea correctamente

3.2 Prioridad P1 (Alto - Esta Semana)

CORR-CLEAN-002: Integrar P0-001 a seeds

-- Agregar a: apps/database/seeds/prod/16-9-gamification/03-maya-ranks-correction.sql

-- Descripción: Corrección de valores Maya Rank para datos legacy
-- Este archivo solo se ejecuta si existen valores incorrectos

DO $$
BEGIN
    -- Solo ejecutar si hay valores legacy
    IF EXISTS (
        SELECT 1 FROM gamification_system.user_stats
        WHERE current_rank IN ('NACOM', 'BATAB', 'HOLCATTE')
    ) THEN
        -- Aplicar correcciones
        UPDATE gamification_system.user_stats
        SET current_rank = CASE current_rank
            WHEN 'NACOM' THEN 'Nacom'
            WHEN 'BATAB' THEN 'Batab'
            -- etc.
        END
        WHERE current_rank IN ('NACOM', 'BATAB', 'HOLCATTE');
    END IF;
END $$;

Criterio de Aceptación:

• Seed file creado
• Corrección es idempotente
• P0-001 movido a _deprecated/

3.3 Prioridad P2 (Medio - Próxima Semana)

CORR-CLEAN-003: Actualizar inventarios

1. MASTER_INVENTORY.yml

   • Regenerar desde inventarios actuales
   • Agregar timestamp de última actualización
   • Incluir métricas de completitud

2. TEST_COVERAGE.yml

   • Extraer datos de cobertura de Jest/Vitest
   • Mapear tests a requerimientos
   • Incluir resultados de ejecución

3. DEPENDENCY_GRAPH.yml

   • Actualizar con dependencias de Student-Teacher
   • Incluir servicios de gamificación
   • Agregar dependencias de frontend

Criterio de Aceptación:

• 3 archivos actualizados
• Timestamps correctos
• Datos verificables

---

4. Verificación de Creación Limpia

4.1 Comandos de Verificación

# 1. Drop y recreate completo
cd apps/database
./drop-and-recreate-database.sh $DATABASE_URL

# 2. Verificar estructura
psql $DATABASE_URL -c "\dt+ progress_tracking.*"
psql $DATABASE_URL -c "\dt+ gamification_system.*"

# 3. Verificar triggers
psql $DATABASE_URL -c "SELECT tgname FROM pg_trigger WHERE tgrelid = 'progress_tracking.exercise_submissions'::regclass"

# 4. Verificar seeds
psql $DATABASE_URL -c "SELECT COUNT(*) FROM educational_content.modules"
psql $DATABASE_URL -c "SELECT COUNT(*) FROM gamification_system.maya_ranks"

# 5. Verificar funciones
psql $DATABASE_URL -c "\df gamilit.*"

4.2 Checklist de Validación Post-Corrección

• Base de datos se recrea sin errores
• Todos los schemas existen (17 esperados)
• Todas las tablas existen (115 esperadas)
• Todos los triggers están activos (45 esperados)
• Seeds se cargan correctamente (40+ archivos)
• Backend conecta sin errores
• Tests pasan

---

5. Cronograma

Fase	Tarea	Responsable	Estado
ANÁLISIS	Validar DDL structure	Architecture-Analyst	✅ COMPLETADO
ANÁLISIS	Buscar migraciones	Architecture-Analyst	✅ COMPLETADO
ANÁLISIS	Verificar documentación	Architecture-Analyst	✅ COMPLETADO
ANÁLISIS	Mapear dependencias	Architecture-Analyst	✅ COMPLETADO
PLANIFICACIÓN	Crear plan corrección	Architecture-Analyst	✅ COMPLETADO
VALIDACIÓN	Validar plan	Architecture-Analyst	🔄 EN CURSO
EJECUCIÓN	CORR-CLEAN-001	Database-Agent	⏳ PENDIENTE
EJECUCIÓN	CORR-CLEAN-002	Database-Agent	⏳ PENDIENTE
EJECUCIÓN	CORR-CLEAN-003	Workspace-Manager	⏳ PENDIENTE
VALIDACIÓN	Verificar ejecución	Architecture-Analyst	⏳ PENDIENTE

---

6. Riesgos y Mitigación

Riesgo	Probabilidad	Impacto	Mitigación
Renombrar DDL rompe orden de ejecución	Media	Alto	Verificar prefijo numérico correcto
Seed de corrección afecta datos correctos	Baja	Alto	Usar condición IF EXISTS con valores legacy
Inventarios desactualizados nuevamente	Alta	Bajo	Crear script de actualización automática

---

7. Aprobación

Fase 3: Validación del Plan (DIRECTA)

Validador: Architecture-Analyst Fecha de Validación: 2025-11-29 09:15 CST

Criterios de Aprobación:

1. Plan cubre todos los hallazgos del análisis
2. Correcciones son reversibles o idempotentes
3. Cronograma es realista
4. Riesgos están identificados y mitigados

Resultado: ✅ APROBADO CON MODIFICACIONES

Modificaciones Aprobadas:

Tarea Original	Prioridad Original	Nueva Prioridad	Justificación
CORR-CLEAN-001 (Renombrar DDL)	P0	P2	Archivo funciona correctamente, problema es solo semántico
CORR-CLEAN-002 (Integrar P0-001)	P1	P1	Aprobado con modificación: separar funciones (DDL) de datos (deprecated)
CORR-CLEAN-003 (Inventarios)	P2	P1	Elevar prioridad por impacto en trazabilidad

Decisiones Específicas:

1. DDL 24-alter_assignment_students.sql:

   • NO renombrar inmediatamente
   • El archivo es idempotente y funciona en recreación limpia
   • Agregar al backlog para refactorización futura (Sprint N+3)

2. Migración P0-001:

   • ✅ Integrar funciones calculate_maya_rank_from_xp() y calculate_rank_progress() al DDL
   • ✅ Mover archivo de migración a _deprecated/
   • ❌ NO crear seed de corrección de datos (innecesario para nuevas instalaciones)

3. Inventarios:

   • ✅ Actualizar MASTER_INVENTORY.yml
   • ✅ Verificar TEST_COVERAGE.yml tiene estructura válida

---

Creado por: Architecture-Analyst Agent Versión del documento: 1.1.0 Estado: ✅ VALIDADO - LISTO PARA EJECUCIÓN (FASE 4)