workspace/projects/gamilit/orchestration/analisis/ANALISIS-COHERENCIA-DATASOURCES-BD-DOC-2025-12-18.md

Analisis de Coherencia: Datasources, Base de Datos y Documentacion

Fecha: 2025-12-18 Autor: Requirements Analyst (Claude Opus 4.5) Estado: COMPLETO Version: 1.0 Relacionado con: ANALISIS-REQUIREMENTS-TEACHER-PORTAL-2025-12-18.md

---

RESUMEN EJECUTIVO

Este documento consolida el analisis de coherencia entre:

• Configuracion de datasources en backend (app.module.ts)
• Definiciones de entidades y schemas de base de datos
• Documentacion (inventarios, trazas, ADRs)

Score de Coherencia Global: 77.6%

Hallazgos Criticos

#	Problema	Severidad	Impacto
1	AssignmentClassroom con datasource incorrecto	CRITICO	Error 500 en /teacher/assignments
2	Documentacion dice 6 datasources, hay 9 reales	ALTO	Documentacion desactualizada
3	5 entidades Admin en schemas diferentes registradas en 'auth'	ALTO	Potencial fallo futuro
4	3 funciones SQL con columnas inexistentes	CRITICO	Funciones no ejecutables
5	RF-TEACH-002 referencia schema 'public' obsoleto	MEDIO	Confusion desarrolladores

---

1. CONFIGURACION DE DATASOURCES

1.1 Datasources Reales vs Documentados

REALIDAD (app.module.ts): 9 datasources

#	Nombre	Schema BD	Path Entidades
1	auth	auth_management	/modules/auth/entities/**/*.entity
2	educational	educational_content	/modules/educational/entities/**/*.entity
3	gamification	gamification_system	/modules/gamification/entities/**/*.entity + notifications/notification.entity
4	progress	progress_tracking	/modules/progress/entities/**/*.entity
5	social	social_features	/modules/social/entities/**/*.entity
6	content	content_management	/modules/content/entities/**/*.entity
7	audit	audit_logging	/modules/audit/entities/**/*.entity
8	notifications	notifications	/modules/notifications/entities/multichannel/**/*.entity
9	communication	communication	/modules/teacher/entities/message*.entity

DOCUMENTACION (BACKEND_INVENTORY.yml): 6 datasources

Faltan en documentacion:

• audit (schema: audit_logging)
• notifications (schema: notifications)
• communication (schema: communication)

---

1.2 PROBLEMA CRITICO: Entidades Assignment

Ubicacion de Entidades

Entidad	Ubicacion	Schema	Datasource Usado	Correcto?
Assignment	/modules/assignments/entities	educational_content	'content'	NO
AssignmentClassroom	/modules/social/entities	social_features	'content'	NO
AssignmentExercise	/modules/assignments/entities	educational_content	'content'	NO
AssignmentStudent	/modules/assignments/entities	educational_content	'content'	NO
AssignmentSubmission	/modules/assignments/entities	educational_content	'content'	NO

Causa Raiz del Error 500

1. AssignmentsModule registra 5 entidades en datasource 'content'
2. Datasource 'content' solo escanea: /modules/content/entities/**/*.entity
3. Entidades de Assignments estan en: /modules/assignments/entities/
4. AssignmentClassroom esta en: /modules/social/entities/
5. TypeORM NO encuentra metadata -> EntityMetadataNotFoundError

---

1.3 PROBLEMA: Entidades Admin Distribuidas

El AdminModule (admin.module.ts:69) registra todas las entidades en datasource 'auth':

TypeOrmModule.forFeature([
  User, Profile, Role, UserRole, Tenant, Membership, AuthAttempt, UserSuspension,
  SystemSetting,          // Schema: system_configuration (NO auth_management)
  FeatureFlag,            // Schema: system_configuration (NO auth_management)
  NotificationSettings,   // Schema: system_configuration (NO auth_management)
  BulkOperation,          // Schema: admin_dashboard (NO auth_management)
  AdminReport             // Schema: admin_dashboard (NO auth_management)
], 'auth')

Impacto: No genera error actualmente porque TypeORM no valida schema a nivel de datasource, pero es una mala practica que puede causar problemas en el futuro.

---

2. INCONSISTENCIAS EN DOCUMENTACION

2.1 Inventarios Desactualizados

Inventario	Discrepancia
BACKEND_INVENTORY.yml	Dice 6 datasources, hay 9
BACKEND_INVENTORY.yml	No documenta datasources 7-9
DATABASE_INVENTORY.yml	No refleja cambios de schema para assignments

2.2 Referencias Rotas en Documentacion

Documento	Referencia Rota	Realidad
RF-TEACH-002-assignment-system.md	Schema: public	Schema: educational_content, social_features
TRACEABILITY EXT-001	Schema assignments en public	Migrado a educational_content (2025-11-08)

2.3 Funciones SQL con Errores

Funcion	Columna Incorrecta	Columna Correcta	Estado
update_leaderboard_streaks.sql	last_activity_date	last_activity_at	CORREGIDO 2025-12-15
update_leaderboard_streaks.sql	longest_streak	max_streak	CORREGIDO 2025-12-15
get_user_rank_progress.sql	missions_completed	modules_completed	✅ CORREGIDO 2025-12-18
update_leaderboard_global.sql	missions_completed	modules_completed	✅ CORREGIDO 2025-12-18
get_classroom_analytics.sql	missions_completed	modules_completed	✅ CORREGIDO 2025-12-18
grant_mission_completion_rewards.sql	missions_completed	modules_completed	✅ CORREGIDO 2025-12-18

---

3. PLAN DE CORRECCION CONSOLIDADO

3.1 SPRINT 1: Correcciones Criticas (P0)

CORRECCION 1: Arreglar AssignmentsModule datasources

Archivo: /modules/assignments/assignments.module.ts

ANTES:

TypeOrmModule.forFeature([
  Assignment,
  AssignmentClassroom,
  AssignmentExercise,
  AssignmentStudent,
  AssignmentSubmission,
], 'content')

DESPUES (Opcion A - Recomendada):

// Entidades educational_content -> datasource 'educational'
TypeOrmModule.forFeature([
  Assignment,
  AssignmentExercise,
  AssignmentStudent,
  AssignmentSubmission,
], 'educational'),

// AssignmentClassroom -> datasource 'social' (importar desde SocialModule)
TypeOrmModule.forFeature([
  AssignmentClassroom,
], 'social'),

DESPUES (Opcion B - Alternativa):

Agregar path de assignments al datasource 'educational' en app.module.ts:

TypeOrmModule.forRootAsync({
  name: 'educational',
  entities: [
    __dirname + '/modules/educational/entities/**/*.entity{.ts,.js}',
    __dirname + '/modules/assignments/entities/**/*.entity{.ts,.js}', // AGREGAR
  ],
}),

---

CORRECCION 2: Arreglar AssignmentsService inyecciones

Archivo: /modules/assignments/services/assignments.service.ts

ANTES (linea 32):

@InjectRepository(AssignmentClassroom, 'content')

DESPUES:

@InjectRepository(AssignmentClassroom, 'social')

---

CORRECCION 3: Arreglar TeacherModule datasources

Archivo: /modules/teacher/teacher.module.ts

ANTES (linea 146):

TypeOrmModule.forFeature([Assignment, AssignmentSubmission, TeacherContent], 'content')

DESPUES:

TypeOrmModule.forFeature([Assignment, AssignmentSubmission, TeacherContent], 'educational')

---

CORRECCION 4: Arreglar 3 funciones SQL pendientes

Archivos:

• /apps/database/ddl/schemas/gamification_system/functions/get_user_rank_progress.sql
• /apps/database/ddl/schemas/gamification_system/functions/update_leaderboard_global.sql
• /apps/database/ddl/schemas/progress_tracking/functions/05-get_classroom_analytics.sql

Cambio: Reemplazar missions_completed por modules_completed

---

3.2 SPRINT 2: Actualizacion Documentacion (P1)

#	Tarea	Archivo
1	Actualizar conteo datasources a 9	BACKEND_INVENTORY.yml
2	Documentar datasources 7-9	BACKEND_INVENTORY.yml
3	Actualizar schema de assignments	RF-TEACH-002-assignment-system.md
4	Actualizar TRACEABILITY EXT-001	TRACEABILITY.yml
5	Crear documento de inconsistencias	INCONSISTENCIAS-DOCUMENTADAS.md

---

3.3 SPRINT 3: Mejoras Estructurales (P2)

#	Tarea	Descripcion
1	Refactorizar AdminModule	Separar por schemas (system_configuration, admin_dashboard)
2	Crear datasource 'system'	Para entidades de system_configuration
3	Crear datasource 'admin_dashboard'	Para BulkOperation, AdminReport

---

4. MATRIZ DE ARCHIVOS AFECTADOS

Archivos a Modificar (P0 - Inmediato)

BACKEND:
- apps/backend/src/modules/assignments/assignments.module.ts (lineas 24-33)
- apps/backend/src/modules/assignments/services/assignments.service.ts (linea 32)
- apps/backend/src/modules/teacher/teacher.module.ts (linea 146)

BASE DE DATOS:
- apps/database/ddl/schemas/gamification_system/functions/get_user_rank_progress.sql
- apps/database/ddl/schemas/gamification_system/functions/update_leaderboard_global.sql
- apps/database/ddl/schemas/progress_tracking/functions/05-get_classroom_analytics.sql

Archivos a Actualizar (P1 - Documentacion)

INVENTARIOS:
- orchestration/inventarios/BACKEND_INVENTORY.yml (lineas 1169-1196)
- orchestration/inventarios/MASTER_INVENTORY.yml

DOCUMENTACION:
- docs/03-fase-extensiones/EXT-001-portal-maestros/requerimientos/RF-TEACH-002-assignment-system.md
- docs/03-fase-extensiones/EXT-001-portal-maestros/implementacion/TRACEABILITY.yml

---

5. VALIDACIONES POST-IMPLEMENTACION

Checklist de Verificacion

BACKEND:
[ ] npm run build - Sin errores
[ ] npm run lint - Sin errores criticos
[ ] GET /api/v1/teacher/assignments - Retorna 200
[ ] GET /api/v1/teacher/classrooms - Retorna 200
[ ] POST /api/v1/teacher/assignments - Crea assignment

BASE DE DATOS:
[ ] SELECT gamilit.get_user_rank_progress(...) - Sin errores
[ ] SELECT gamilit.update_leaderboard_global() - Sin errores
[ ] SELECT progress_tracking.get_classroom_analytics(...) - Sin errores

DOCUMENTACION:
[ ] BACKEND_INVENTORY.yml - 9 datasources documentados
[ ] RF-TEACH-002 - Schema actualizado a educational_content
[ ] TRACEABILITY EXT-001 - Referencias actualizadas

---

6. DEPENDENCIAS ENTRE CORRECCIONES

CORRECCION 1 (AssignmentsModule)
    |
    +---> CORRECCION 2 (AssignmentsService) [DEPENDE DE 1]
    |
    +---> CORRECCION 3 (TeacherModule) [PUEDE SER PARALELO]

CORRECCION 4 (Funciones SQL) [INDEPENDIENTE]

SPRINT 2 (Documentacion) [DESPUES DE VALIDAR SPRINT 1]

SPRINT 3 (Refactorizacion Admin) [OPCIONAL, DESPUES DE SPRINT 2]

---

7. RESUMEN DE IMPACTO

Antes de Correcciones

Endpoint	Estado	Error
GET /api/v1/teacher/assignments	500	EntityMetadataNotFoundError
GET /api/v1/teacher/classrooms	OK	-
POST /api/v1/teacher/assignments	500	EntityMetadataNotFoundError

Despues de Correcciones

Endpoint	Estado Esperado
GET /api/v1/teacher/assignments	200 OK
GET /api/v1/teacher/classrooms	200 OK
POST /api/v1/teacher/assignments	201 Created

---

CONCLUSION

El analisis de coherencia ha identificado que el problema principal del Portal de Teacher (Error 500 en assignments) se debe a una configuracion incorrecta de datasources donde las entidades de assignments estan registradas en un datasource ('content') que no escanea sus directorios.

Adicionalmente, se identificaron:

• 3 discrepancias entre documentacion y codigo real
• 3 funciones SQL con columnas inexistentes
• 5 entidades admin registradas en datasource incorrecto (riesgo futuro)

Recomendacion: Implementar correcciones P0 de manera inmediata para resolver el error critico del portal Teacher.

---

Fin del Documento de Analisis de Coherencia

Autor: Requirements Analyst (Claude Opus 4.5) Fecha: 2025-12-18 Estado: COMPLETO - Listo para revision y aprobacion