workspace/projects/gamilit/orchestration/reportes/coherencia-2025-12-15/FASE-1-PLAN-ANALISIS.md

FASE 1: PLANEACIÓN DEL ANÁLISIS

Análisis de Coherencia BD-Backend-Frontend

Fecha: 2025-12-15 Estado: EN PROGRESO Responsable: Tech-Leader

---

1. OBJETIVOS DEL ANÁLISIS

1.1 Objetivo Principal

Identificar y documentar TODAS las discrepancias entre:

• Base de datos (DDL, funciones, seeds)
• Backend (entities, services, constants)
• Frontend (types, stores, components)

1.2 Objetivos Específicos

1. Validar que cada columna en DDL tenga su correspondiente campo en Entity
2. Validar que cada ENUM en DDL tenga valores idénticos en Backend y Frontend
3. Validar que las funciones SQL referencien columnas existentes
4. Validar que los seeds usen valores válidos de ENUMs y FKs existentes
5. Validar que los tipos Frontend sean compatibles con DTOs Backend

---

2. ALCANCE DETALLADO

2.1 Objetos de Base de Datos

Tablas Prioritarias (P0)

Tabla	Schema	Razón
user_stats	gamification_system	Central para achievements
achievements	gamification_system	Catálogo de logros
user_achievements	gamification_system	Logros por usuario
module_progress	progress_tracking	Progreso de módulos
exercise_attempts	progress_tracking	Intentos de ejercicios

Tablas Secundarias (P1)

Tabla	Schema	Razón
users	auth	Usuario base
profiles	auth_management	Perfil extendido
modules	educational_content	Módulos educativos
exercises	educational_content	Ejercicios
classroom_members	social_features	Condiciones sociales

ENUMs a Validar

ENUM	Schema	Usado En
maya_rank	gamification_system	user_stats.current_rank
achievement_category	gamification_system	achievements.category
achievement_type	gamification_system	achievements DDL
comodin_type	gamification_system	comodines
progress_status	progress_tracking	module_progress, exercise_attempts
difficulty_level	educational_content	exercises, modules

Funciones SQL Críticas

Función	Schema	Impacto
update_leaderboard_streaks	gamification_system	Actualiza rachas
check_and_award_achievements	gamification_system	Otorga logros
award_ml_coins	gamification_system	Otorga monedas
calculate_user_rank	gamification_system	Calcula rango Maya
process_exercise_completion	gamification_system	Procesa completado

2.2 Objetos de Backend

Entities

Entity	Módulo	Tabla DDL
UserStats	gamification	gamification_system.user_stats
Achievement	gamification	gamification_system.achievements
UserAchievement	gamification	gamification_system.user_achievements
ModuleProgress	progress	progress_tracking.module_progress
ExerciseAttempt	progress	progress_tracking.exercise_attempts

Services con Queries SQL

Service	Módulo	Queries Embebidos
AchievementsService	gamification	meetsConditions(), detectAndGrantEarned()
ShopService	gamification	purchase(), getBalance()
ExerciseAttemptService	progress	updateModuleProgress(), incrementStats()
ExerciseSubmissionService	progress	grade(), submit()

Constants

Archivo	Contenido
enums.constants.ts	Todos los ENUMs del sistema
database.constants.ts	Nombres de schemas y tablas

2.3 Objetos de Frontend

Types Principales

Archivo	Tipos
achievement.types.ts	Achievement, AchievementCategory, AchievementReward
achievementsTypes.ts	AchievementWithProgress, AchievementStats
userStats.types.ts	UserStats (si existe)

Stores

Store	Feature
achievementsStore.ts	Estado de achievements
ranksStore.ts	Estado de rangos

API Services

API	Endpoints
achievementsAPI.ts	/achievements/*
ranksAPI.ts	/ranks/*
shopAPI.ts	/shop/*

---

3. SUBAGENTES Y PROMPTS

3.1 Database-Auditor

Rol: Analizar coherencia interna de la base de datos

Prompt:

Eres un Database-Auditor especializado en PostgreSQL. Tu tarea es analizar la coherencia de los objetos DDL del proyecto GAMILIT.

CONTEXTO:
- Proyecto: GAMILIT (plataforma educativa gamificada)
- Base de datos: PostgreSQL 16
- Ubicación DDL: /home/isem/workspace/projects/gamilit/apps/database/ddl/
- Ubicación Seeds: /home/isem/workspace/projects/gamilit/apps/database/seeds/

TAREAS:
1. Para cada función SQL en gamification_system/functions/:
   - Listar todas las columnas referenciadas
   - Verificar que cada columna existe en la tabla correspondiente
   - Identificar discrepancias

2. Para cada seed en seeds/dev/gamification_system/:
   - Verificar que los valores de ENUMs son válidos
   - Verificar que las FKs referencian registros existentes
   - Identificar UUIDs hardcodeados que podrían no existir

3. Para cada trigger:
   - Verificar que la tabla existe
   - Verificar que las columnas referenciadas existen

ENTREGABLES:
- MATRIZ-FUNCTIONS-COLUMNS.md: Tabla función → columnas referenciadas → existe (sí/no)
- MATRIZ-SEEDS-VALIDATION.md: Validación de seeds
- LISTA-DISCREPANCIAS-DDL.md: Lista priorizada de problemas

CRITERIOS DE SEVERIDAD:
- P0: Columna/tabla referenciada no existe (error en runtime)
- P1: Valor ENUM inválido (error en insert)
- P2: FK a registro que podría no existir
- P3: Nomenclatura inconsistente

3.2 Backend-Auditor

Rol: Analizar coherencia entre Entities y DDL, y queries embebidos

Prompt:

Eres un Backend-Auditor especializado en NestJS y TypeORM. Tu tarea es analizar la coherencia entre las Entities del backend y el DDL de base de datos.

CONTEXTO:
- Proyecto: GAMILIT (plataforma educativa gamificada)
- Framework: NestJS con TypeORM
- Ubicación Entities: /home/isem/workspace/projects/gamilit/apps/backend/src/modules/*/entities/
- Ubicación Services: /home/isem/workspace/projects/gamilit/apps/backend/src/modules/*/services/
- Ubicación Constants: /home/isem/workspace/projects/gamilit/apps/backend/src/shared/constants/

TAREAS:
1. Para cada Entity en módulos gamification y progress:
   - Comparar cada @Column con la columna DDL correspondiente
   - Verificar: nombre, tipo, nullable, default
   - Identificar campos faltantes en Entity o DDL

2. Para cada Service que tenga queries SQL embebidos:
   - Extraer todas las queries raw SQL
   - Listar columnas/tablas referenciadas
   - Verificar existencia en DDL

3. Para ENUMs en enums.constants.ts:
   - Comparar valores con ENUM DDL correspondiente
   - Identificar valores faltantes o extras

ENTREGABLES:
- MATRIZ-ENTITY-DDL.md: Comparación campo por campo
- MATRIZ-QUERIES-VALIDATION.md: Validación de queries embebidos
- MATRIZ-ENUMS-BACKEND.md: Comparación ENUMs
- LISTA-DISCREPANCIAS-BACKEND.md: Lista priorizada de problemas

CRITERIOS DE SEVERIDAD:
- P0: Campo en Entity no existe en DDL (error en runtime)
- P1: Tipo incorrecto (posible pérdida de datos)
- P2: Nullable incorrecto (posible error en insert)
- P3: Default diferente (comportamiento inesperado)

3.3 Frontend-Auditor

Rol: Analizar coherencia entre Types Frontend y DTOs/Entities Backend

Prompt:

Eres un Frontend-Auditor especializado en React y TypeScript. Tu tarea es analizar la coherencia entre los tipos del frontend y el backend.

CONTEXTO:
- Proyecto: GAMILIT (plataforma educativa gamificada)
- Framework: React con TypeScript
- Ubicación Types: /home/isem/workspace/projects/gamilit/apps/frontend/src/shared/types/
- Ubicación Feature Types: /home/isem/workspace/projects/gamilit/apps/frontend/src/features/*/types/
- Ubicación API Services: /home/isem/workspace/projects/gamilit/apps/frontend/src/features/*/api/

TAREAS:
1. Para tipos en achievement.types.ts y achievementsTypes.ts:
   - Comparar interfaces con Entity Achievement del backend
   - Verificar que AchievementCategory tiene mismos valores que ENUM backend
   - Identificar campos faltantes o extras

2. Para API services:
   - Verificar que los endpoints llamados existen en backend
   - Verificar que los tipos de request/response coinciden

3. Identificar tipos duplicados o conflictivos entre archivos

ENTREGABLES:
- MATRIZ-TYPES-ENTITY.md: Comparación tipos frontend vs entities backend
- MATRIZ-API-CONTRACTS.md: Validación de contratos API
- LISTA-DISCREPANCIAS-FRONTEND.md: Lista priorizada de problemas

CRITERIOS DE SEVERIDAD:
- P0: Tipo referencia campo que no existe en backend
- P1: Tipo union tiene valores que no existen en ENUM backend
- P2: Campo opcional en frontend pero required en backend
- P3: Nomenclatura diferente (camelCase vs snake_case)

3.4 Architecture-Analyst

Rol: Análisis cross-capa y validación de dependencias

Prompt:

Eres un Architecture-Analyst especializado en sistemas full-stack. Tu tarea es analizar las dependencias entre capas y validar la integridad del sistema.

CONTEXTO:
- Proyecto: GAMILIT (plataforma educativa gamificada)
- Capas: PostgreSQL → NestJS → React
- Reportes de otros auditores ya disponibles

TAREAS:
1. Consolidar hallazgos de Database-Auditor, Backend-Auditor y Frontend-Auditor

2. Identificar dependencias transitivas:
   - Si se corrige X en DDL, ¿qué entities/types deben actualizarse?
   - Si se agrega valor a ENUM, ¿dónde más debe agregarse?

3. Crear grafo de dependencias de correcciones:
   - ¿Qué correcciones deben ir primero?
   - ¿Hay ciclos de dependencias?

4. Identificar gaps no cubiertos por otros auditores

ENTREGABLES:
- CONSOLIDADO-HALLAZGOS.md: Todos los hallazgos unificados
- GRAFO-DEPENDENCIAS.md: Dependencias entre correcciones
- ORDEN-CORRECCION.md: Secuencia ordenada de correcciones
- GAPS-IDENTIFICADOS.md: Áreas no cubiertas

CRITERIOS:
- Priorizar por impacto en runtime
- Agrupar correcciones relacionadas
- Minimizar cantidad de deploys necesarios

---

4. FORMATO DE MATRICES

4.1 MATRIZ-ENTITY-DDL (Ejemplo)

| Entity Field | DDL Column | Entity Type | DDL Type | Nullable (E/D) | Default (E/D) | Status |
|--------------|------------|-------------|----------|----------------|---------------|--------|
| user_id | user_id | uuid | uuid | false/NOT NULL | - | ✅ |
| current_rank | current_rank | text | maya_rank ENUM | true/NULL | 'Ajaw' | ⚠️ Tipo |

4.2 MATRIZ-ENUM-ALIGNMENT (Ejemplo)

| Valor | DDL ENUM | Backend Enum | Frontend Type | Status |
|-------|----------|--------------|---------------|--------|
| progress | ✅ | ✅ | ✅ | ✅ |
| collection | ❌ | ❌ | ✅ | ⚠️ Frontend extra |

4.3 LISTA-DISCREPANCIAS (Ejemplo)

discrepancias:
  - id: DISC-001
    severidad: P0
    capa: database
    objeto: update_leaderboard_streaks
    problema: "Referencia columna last_activity_date que no existe"
    columna_esperada: last_activity_at
    accion: "Cambiar referencia en función SQL"

---

5. CRITERIOS DE ACEPTACIÓN FASE 1

• Alcance documentado (tablas, entities, types)
• Subagentes definidos con prompts específicos
• Formato de entregables establecido
• Criterios de severidad definidos
• Revisión y aprobación del plan

---

6. PRÓXIMOS PASOS

1. Aprobar Plan: Confirmar que el alcance y criterios son correctos
2. Ejecutar Fase 2: Lanzar subagentes en paralelo para análisis
3. Consolidar: Architecture-Analyst consolida hallazgos

---

Estado: LISTO PARA APROBACIÓN Siguiente Fase: FASE 2 - Ejecución del Análisis