workspace-v1/projects/gamilit/docs/90-transversal/inventarios-database/inventarios/02-TABLES-INVENTORY.md

Inventario de Tablas - Base de Datos GAMILIT

Fecha generación: 2025-11-07 Última actualización: 2025-11-29 Versión: 1.2 Total tablas: 77+ Método: Análisis de archivos DDL + Validación de entities TypeORM

---

📑 Índice por Schema

Schema	Tablas	% del Total	Actualizado
auth_management	12	17%	2025-11-07
gamification_system	16	22%	2025-11-29
public	5	7% ✅	2025-11-29
social_features	8	11% ✅	2025-11-29
audit_logging	6	8%	2025-11-07
content_management	5	7%	2025-11-07
progress_tracking	5	7%	2025-11-07
educational_content	10+	13%	2025-11-29
system_configuration	3	4%	2025-11-07
notifications	6	8% ✨	2025-11-29
auth	1	1%	2025-11-07
TOTAL	77+	100%

Nota v1.2 (2025-11-29):

• Corregido errores de documentación en schema public (9→5 tablas)
• Agregado schema notifications (6 tablas, EXT-003)
• Movida assignment_classrooms de public a social_features
• Eliminadas tablas fantasma: public.classrooms, public.notifications, public.classroom_students
• Validadas duplicaciones potenciales: NO EXISTEN duplicados reales

---

🔍 Detalle de Tablas por Schema

auth (1 tabla)

Ubicación: apps/database/ddl/schemas/auth/tables/

#	Tabla	Propósito	Estado Doc
1	users	Tabla base de usuarios	✅

Contexto:

• Tabla fundamental del sistema
• Extendida por auth_management.profiles
• Referenciada por todos los schemas

Referencias SIMCO:

• Seeds: apps/database/seeds/auth/
• Backend: apps/backend/src/modules/auth/entities/user.entity.ts

---

auth_management (12 tablas)

Ubicación: apps/database/ddl/schemas/auth_management/tables/

#	Tabla	Propósito	Estado Doc
1	tenants	Multi-tenancy (escuelas, instituciones)	✅
2	auth_attempts	Registro de intentos de autenticación	✅
3	profiles	Perfiles extendidos de usuarios	✅
4	roles	Roles del sistema (admin, teacher, student)	✅
5	auth_providers	Proveedores OAuth (Google, Facebook)	✅
6	email_verification_tokens	Tokens de verificación de email	✅
7	password_reset_tokens	Tokens de reset de contraseña	✅
8	security_events	Eventos de seguridad	✅
9	user_preferences	Preferencias de usuario	✅
10	memberships	Membresías usuario-tenant	✅
11	user_sessions	Sesiones activas de usuarios	✅
12	user_suspensions	Suspensiones de cuentas	✅

Relaciones Clave:

• tenants → Raíz del multi-tenancy
• profiles → Extiende auth.users
• memberships → Liga users ↔ tenants
• roles → Define permisos (admin, teacher, student)

Referencias SIMCO:

• Docs: docs/03-desarrollo/base-de-datos/schemas/auth_management/
• Backend: apps/backend/src/modules/auth/, apps/backend/src/modules/users/
• Seeds: apps/database/seeds/auth_management/

---

gamification_system (16 tablas)

Ubicación: apps/database/ddl/schemas/gamification_system/tables/ Última actualización: 2025-11-29

#	Tabla	Propósito	Estado Doc	Entity TypeORM
1	user_stats	Estadísticas de usuario (puntos, nivel, racha)	✅	✅
2	user_ranks	Historial de rangos del usuario	✅	✅
3	achievements	Catálogo de logros	✅	✅
4	user_achievements	Logros desbloqueados por usuario	✅	✅
5	ml_coins_transactions	Transacciones de monedas ML (Maya Learning)	✅	✅
6	missions	Misiones diarias/semanales	✅	✅
7	comodines_inventory	Inventario de comodines (power-ups)	✅	✅
8	notifications	Notificaciones de gamificación	✅ ⚠️	✅
9	leaderboard_metadata	Metadata de leaderboards	✅	✅
10	achievement_categories	Categorías de logros	✅	✅
11	active_boosts	Boosts activos del usuario	✅	✅
12	inventory_transactions	Historial de transacciones de inventario	✅	✅
13	maya_ranks	[NUEVO] Configuración de rangos Maya (referencia)	✅	✅
14	comodin_usage_log	[NUEVO] Historial detallado de uso de comodines	✅	✅
15	comodin_usage_tracking	[NUEVO] Tracking agregado de uso de comodines	✅	⚠️
16	classroom_missions	[NUEVO] Misiones asignadas por classroom	✅	✅

⚠️ Posible Duplicación:

• notifications existe en gamification_system Y en public
• Acción requerida: Verificar si son tablas diferentes o duplicadas

Sistema de Rangos Maya (Actualizado 2025-11-29): Tabla maya_ranks - Configuración de referencia:

1. Ajaw (Orden 1) - Principiante
2. Nacom (Orden 2) - Guerrero
3. Ah K'in (Orden 3) - Sacerdote
4. Halach Uinic (Orden 4) - Gobernante
5. K'uk'ulkan (Orden 5) - Serpiente Emplumada (Maestro)

Tabla user_ranks - Historial de progresión del usuario con porcentaje de avance.

Comodines (Power-ups): Tabla comodin_usage_log registra uso detallado con:

• Tipo: pistas, vision_lectora, segunda_oportunidad
• Contexto: exercise_id, attempt_id, module_id
• Efecto aplicado y valor proporcionado (JSONB)

Referencias SIMCO:

• Docs: docs/03-desarrollo/base-de-datos/schemas/gamification_system/
• Backend: apps/backend/src/modules/gamification/
• Frontend: apps/frontend/src/features/gamification/
• Seeds: apps/database/seeds/gamification_system/

---

public (5 tablas) - ACTUALIZADO 2025-11-29

Ubicación: apps/database/ddl/schemas/public/tables/ Estado: ✅ VALIDADO - Errores de documentación corregidos Última actualización: 2025-11-29

#	Tabla	Propósito	Estado Doc	Nota
1	assignments	Asignaciones de ejercicios	✅	RF-TEACH-002
2	assignment_exercises	Relación assignments ↔ exercises	✅	RF-TEACH-002
3	assignment_students	Relación assignments ↔ students	✅	RF-TEACH-002
4	assignment_submissions	Entregas de estudiantes	✅	RF-TEACH-002
5	teacher_notes	Notas de profesores	✅	RF-TEACH-002

✅ CORREGIDO (2025-11-29): El inventario anterior tenía errores de documentación.

Tablas que NO existen en public (eliminadas del inventario):

• public.classrooms → Solo existe social_features.classrooms
• public.classroom_students → Solo existe social_features.classroom_members
• public.notifications → Solo existe notifications.notifications (EXT-003)
• public.assignment_classrooms → Movida a social_features.assignment_classrooms

✅ Duplicaciones Resueltas (2025-11-29)

Tabla Reportada	Schema Real	Estado
public.classrooms	social_features.classrooms	✅ NO DUPLICADA - Solo existe en social_features
public.notifications	notifications.notifications	✅ NO DUPLICADA - Solo existe en notifications schema
public.assignment_classrooms	social_features.assignment_classrooms	✅ MOVIDA - Documentado en RF-TEACH-002

Sobre gamification_system.notifications (DEPRECATED)

⚠️ DEPRECATED: gamification_system.notifications
✅ ACTUAL: notifications.notifications (EXT-003)

La tabla gamification_system.notifications existe pero está DEPRECADA.
El sistema consolidado de notificaciones multi-canal usa notifications.notifications.
Ver: modules/notifications/entities/multichannel/notification.entity.ts

Referencias SIMCO:

• RF-TEACH-002-assignment-system.md (documentación de assignments)
• EXT-003 (Sistema Multi-Canal de Notificaciones)

---

social_features (8 tablas)

Ubicación: apps/database/ddl/schemas/social_features/tables/ Última actualización: 2025-11-29

#	Tabla	Propósito	Estado Doc
1	friendships	Relaciones de amistad entre usuarios	✅
2	schools	Escuelas	✅
3	classrooms	Aulas/Clases	✅ ⚠️
4	classroom_members	Miembros de clases	✅ ⚠️
5	teams	Equipos de estudiantes	✅
6	team_members	Miembros de equipos	✅
7	team_challenges	Desafíos entre equipos	✅
8	assignment_classrooms	[MOVIDA 2025-11-29] Relación assignments ↔ classrooms	✅

✅ Sin conflictos (Validado 2025-11-29):

• social_features.classrooms es la ÚNICA tabla de classrooms (no existe en public)
• social_features.classroom_members es la ÚNICA tabla de miembros (no existe en public)
• social_features.assignment_classrooms fue movida desde public (2025-11-29)

Referencias SIMCO:

• Docs: docs/03-desarrollo/base-de-datos/schemas/social_features/
• Backend: apps/backend/src/modules/social/
• Frontend: apps/frontend/src/features/social/

---

audit_logging (6 tablas)

Ubicación: apps/database/ddl/schemas/audit_logging/tables/

#	Tabla	Propósito	Estado Doc
1	audit_logs	Logs de auditoría general	✅
2	performance_metrics	Métricas de performance del sistema	✅
3	system_alerts	Alertas del sistema	✅
4	system_logs	Logs del sistema	✅
5	user_activity_logs	Logs de actividad de usuarios	✅
6	user_activity	Actividad reciente de usuarios	✅

Patrón:

• Todas las tablas de auditoría son append-only
• Requieren particionamiento por fecha para escalabilidad
• RLS: Solo admins pueden leer

Referencias SIMCO:

• Docs: docs/03-desarrollo/base-de-datos/schemas/audit_logging/
• Backend: apps/backend/src/modules/audit/

---

content_management (5 tablas)

Ubicación: apps/database/ddl/schemas/content_management/tables/

#	Tabla	Propósito	Estado Doc
1	content_templates	Plantillas de contenido	✅
2	marie_curie_content	Contenido de Marie Curie (personaje guía)	✅
3	media_files	Archivos multimedia	✅
4	content_versions	Versionado de contenido	✅
5	flagged_content	Contenido reportado/moderado	✅

Integración con storage:

• media_files se integra con schema storage
• Files almacenados en MinIO/S3
• BD solo guarda metadata

Referencias SIMCO:

• Docs: docs/03-desarrollo/base-de-datos/schemas/content_management/
• Backend: apps/backend/src/modules/content/
• Storage: Schema storage, MinIO/S3

---

progress_tracking (5 tablas)

Ubicación: apps/database/ddl/schemas/progress_tracking/tables/

#	Tabla	Propósito	Estado Doc
1	module_progress	Progreso por módulo	✅
2	learning_sessions	Sesiones de aprendizaje	✅
3	exercise_attempts	Intentos de ejercicios	✅
4	exercise_submissions	Entregas de ejercicios	✅
5	scheduled_missions	Misiones programadas	✅

Tabla de alto tráfico:

• exercise_attempts y learning_sessions son las más escritas
• Requiere indexes optimizados por usuario y fecha
• Candidatas para particionamiento

Referencias SIMCO:

• Docs: docs/03-desarrollo/base-de-datos/schemas/progress_tracking/
• Backend: apps/backend/src/modules/progress/
• Frontend: apps/frontend/src/features/student-dashboard/

---

educational_content (15+ tablas)

Ubicación: apps/database/ddl/schemas/educational_content/tables/ Última actualización: 2025-11-29

#	Tabla	Propósito	Estado Doc	Entity TypeORM
1	modules	Módulos educativos	✅	✅
2	exercises	Ejercicios/Actividades	✅	✅
3	assessment_rubrics	Rúbricas de evaluación	✅	✅
4	media_resources	Recursos multimedia educativos	✅	✅
5	assignments	Tareas asignadas por profesores	✅	✅
6	assignment_exercises	Ejercicios en una tarea	✅	✅
7	assignment_students	Tareas asignadas a estudiantes	✅	✅
8	assignment_submissions	Entregas de estudiantes	✅	✅
9	content_approvals	Aprobaciones de contenido	✅	✅
10	difficulty_criteria	[NUEVO] Criterios CEFR (A1-C2+)	✅	✅
11	exercise_mechanic_mapping	Mapeo ejercicio → mecánica	✅	✅
12	exercise_validation_config	Configuración de validación	✅	⚠️
13	classroom_modules	Módulos asignados a classrooms	✅	⚠️
14	teacher_content	Contenido personalizado de profesor	✅	✅
15+	otros	Tablas deprecadas/migradas	⚠️	-

Tabla difficulty_criteria (CEFR Levels): Define criterios por nivel de dificultad:

• Niveles: A1, A2, B1, B2, B2+, C1, C2, C2+
• Criterios: vocab_range, sentence_length, time_multiplier
• Recompensas: base_xp, base_coins por nivel
• Promoción: success_rate requerido, min_exercises

Referencias SIMCO:

• Docs: docs/03-desarrollo/base-de-datos/schemas/educational_content/
• Backend: apps/backend/src/modules/educational/, apps/backend/src/modules/assignments/
• Frontend: apps/frontend/src/features/learning/, apps/frontend/src/features/assignments/

---

system_configuration (3 tablas)

Ubicación: apps/database/ddl/schemas/system_configuration/tables/

#	Tabla	Propósito	Estado Doc
1	system_settings	Configuración global del sistema	✅
2	feature_flags	Feature flags (A/B testing, rollout)	✅
3	notification_settings	Configuración de notificaciones	✅

Patrón Key-Value:

• Tablas diseñadas con patrón key-value para flexibilidad
• RLS: Solo role admin puede modificar
• Backend cachea estos valores

Referencias SIMCO:

• Docs: docs/03-desarrollo/base-de-datos/schemas/system_configuration/
• Backend: apps/backend/src/modules/config/

---

notifications (6 tablas) ✨ NUEVO - EXT-003

Ubicación: apps/database/ddl/schemas/notifications/tables/ Estado: ✅ Sistema Multi-Canal de Notificaciones Última actualización: 2025-11-29

#	Tabla	Propósito	Estado Doc
1	notifications	Notificaciones multi-canal (in_app, email, push)	✅
2	notification_preferences	Preferencias de usuario por tipo/canal	✅
3	notification_logs	Historial de envíos y resultados	✅
4	notification_templates	Plantillas de notificaciones	✅
5	notification_queue	Cola de procesamiento asíncrono	✅
6	user_devices	Dispositivos registrados para push	✅

Arquitectura EXT-003:

• Sistema consolidado que reemplaza gamification_system.notifications (deprecated)
• Soporte multi-canal: in_app, email, push
• Procesamiento asíncrono mediante cola
• Templates con variables dinámicas

Referencias SIMCO:

• Docs: docs/03-fase-extensiones/EXT-003-notificaciones/
• Backend: apps/backend/src/modules/notifications/
• Entity: modules/notifications/entities/multichannel/

---

📊 Análisis Estadístico

Distribución por Schema (Actualizado 2025-11-29)

gamification_system  ████████████████████ 16 (20%)
auth_management      ████████████████ 12 (15%)
educational_content  ██████████████ 10+ (13%)
social_features      ██████████ 8 (10%)
audit_logging        ████████ 6 (8%)
notifications        ████████ 6 (8%) ✨ NUEVO EXT-003
content_management   ██████ 5 (6%)
progress_tracking    ██████ 5 (6%)
public               ██████ 5 (6%) ✅ CORREGIDO
system_config        ████ 3 (4%)
auth                 ██ 1 (1%)

Total estimado: 77+ tablas

Por Tipo de Funcionalidad

Tipo	Tablas	Schemas
Core/Auth	13	auth, auth_management
Features	33	gamification, educational, progress, content, social
System	9	system_config, audit
Legacy/Unclear	9	public ⚠️

Tablas de Alto Tráfico (Writes)

1. progress_tracking.exercise_attempts - Alta escritura
2. progress_tracking.learning_sessions - Alta escritura
3. gamification_system.ml_coins_transactions - Media-Alta escritura
4. audit_logging.user_activity_logs - Alta escritura
5. auth_management.user_sessions - Media escritura

Recomendación: Considerar particionamiento por fecha para estas tablas.

---

🚨 Discrepancias y Problemas Identificados

1. Duplicación de Tablas (CRÍTICO)

Tabla	Schema 1	Schema 2	Acción
classrooms	social_features	public	Consolidar
classroom_members/students	social_features	public	Consolidar
notifications	gamification_system	public	Consolidar

2. Tablas en Schema Incorrecto

Tabla	Schema Actual	Schema Sugerido	Razón
assignments	public	educational_content	Funcionalidad educativa
assignment_* (5 tablas)	public	educational_content	Funcionalidad educativa
teacher_notes	public	educational_content	Funcionalidad educativa

3. Conteo de Tablas Documentadas

Documentado originalmente: 48 tablas Real: 64 tablas Diferencia: +16 tablas

Las 16+ tablas no documentadas probablemente son:

1. Las 9 tablas de public (todas sin documentar)
2. Posibles tablas nuevas en otros schemas

4. Schema public - Análisis Requerido

Total de tablas en public: 9 tablas (14% del total)

Estado: Todas sin documentar

Posibles escenarios:

1. Legacy de migración: Tablas del sistema anterior no migradas
2. Desarrollo temporal: Tablas creadas durante desarrollo
3. Funcionalidad activa: Sistema de assignments que debería moverse

Recomendación:

• Investigar uso actual: Consultar backend para ver si hay EntityORMentities usando estas tablas
• Si activo: Migrar a schemas correctos
• Si legacy: Crear plan de deprecación
• Si duplicado: Consolidar con tablas existentes

---

🎯 Plan de Acción

Fase 2A: Análisis de Duplicación (Urgente)

• Comparar esquemas:

  -- Comparar public.classrooms vs social_features.classrooms
  \d public.classrooms
  \d social_features.classrooms
  
  -- Comparar public.notifications vs gamification_system.notifications
  \d public.notifications
  \d gamification_system.notifications
  

• Verificar uso en backend:

  # Buscar referencias a public.classrooms
  grep -r "public.classrooms" apps/backend/
  grep -r "social_features.classrooms" apps/backend/
  

• Contar registros:

  SELECT 'public.classrooms' as tabla, count(*) FROM public.classrooms
  UNION ALL
  SELECT 'social_features.classrooms', count(*) FROM social_features.classrooms;
  

Fase 2B: Documentar Tablas Faltantes

• Documentar las 9 tablas de public
• Identificar cualquier otra tabla no documentada
• Crear diagramas ERD completos

Fase 2C: Plan de Consolidación

Una vez identificadas las duplicaciones:

1. Determinar tabla "correcta" (la más usada, mejor diseño)
2. Migrar datos de tabla incorrecta a correcta
3. Actualizar referencias en backend
4. Deprecar tabla antigua (no eliminar inmediatamente)
5. Validar en QA/staging
6. Eliminar tabla deprecated después de período de gracia

---

📎 Referencias SIMCO

Este documento es parte del sistema SIMCO (Sistema Indexado Modular por Contexto)

Referencias Cruzadas

• Inventario anterior: 01-SCHEMAS-INVENTORY.md
• Siguiente inventario: 03-ENUMS-INVENTORY.md
• Plan maestro: apps/database/PLAN-ACTUALIZACION-DOCUMENTACION.md
• Documentación schemas: docs/03-desarrollo/base-de-datos/schemas/

Scripts Relacionados

• Script de inventario: apps/database/scripts/inventory/list-tables.sh
• DDL Source: apps/database/ddl/schemas/*/tables/*.sql
• Seeds: apps/database/seeds/*/

---

Generado por: Sistema de inventario automatizado SIMCO Método: Análisis de estructura DDL + scripts bash Estado: ⚠️ Requiere validación de duplicaciones y consolidación de public schema Próxima acción: Análisis de duplicación de tablas + inventario de ENUMs