Matriz de Dependencias: Student Portal ↔ Teacher Portal
Fecha de creacion: 2025-11-29
Version: 1.0.0
Estado: VIGENTE
Complementa: INTEGRACION-STUDENT-TEACHER.md
1. Proposito
Este documento detalla TODAS las dependencias entre objetos del Student Portal y Teacher Portal para:
- Evaluar impacto antes de cualquier cambio
- Identificar objetos que requieren sincronizacion
- Prevenir errores por cambios no coordinados
2. Dependencias por Capa
2.1 Capa de Base de Datos
Tablas Principales y sus Dependientes
| Tabla Origen |
Dependientes Directos |
Dependientes Indirectos |
auth_management.profiles |
exercise_submissions.user_id, exercise_attempts.user_id, module_progress.user_id, user_stats.user_id, classroom_members.user_id |
Todos los queries de Teacher |
educational_content.exercises |
exercise_submissions.exercise_id, exercise_attempts.exercise_id, assignment_exercises.exercise_id |
module_progress (via triggers) |
educational_content.modules |
module_progress.module_id, exercises.module_id |
Progreso del estudiante |
progress_tracking.exercise_submissions |
TRIGGER: update_module_progress, TRIGGER: update_user_stats, TRIGGER: check_failures |
Teacher views, Alertas |
progress_tracking.module_progress |
Dashboard Teacher, Reportes |
Ninguno |
gamification_system.user_stats |
Leaderboards, Dashboard Teacher |
Rank progress, Achievements |
social_features.classrooms |
classroom_members, teacher_classrooms, assignments |
Todos los datos filtrados por aula |
social_features.classroom_members |
Queries de Teacher (filtro por aula) |
module_progress.classroom_id |
Triggers y sus Efectos
| Trigger |
Tabla Monitoreada |
Tablas Afectadas |
Condicion de Disparo |
trg_update_module_progress |
exercise_submissions |
module_progress |
AFTER INSERT |
trg_update_user_stats |
exercise_submissions |
user_stats, ml_coins_transactions |
AFTER INSERT WHEN score IS NOT NULL |
trg_check_student_failures |
exercise_submissions |
student_intervention_alerts |
AFTER INSERT WHEN score < 60 |
trg_update_missions_progress |
exercise_submissions |
user_missions |
AFTER INSERT |
2.2 Capa de Backend
Services y sus Dependencias
┌─────────────────────────────────────────────────────────────────────────────┐
│ EXERCISE-SUBMISSION.SERVICE.TS │
│ (Punto de entrada principal) │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ EntityManager │ │ExerciseAnswer │ │ModuleProgress │
│ (TypeORM) │ │ Validator │ │ Service │
└───────────────┘ └───────────────┘ └───────────────┘
│ │ │
│ │ ├──► Actualiza module_progress
│ │ │
│ ▼ │
│ Valida estructura │
│ de respuestas │
│ │ │
▼ │ │
Guarda en BD ◄──────────┘ │
│ │
├── DISPARA TRIGGERS ──────────┘
│
├──────────────────────────────────────────────┐
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ UserStats │ │ MLCoins │
│ Service │ │ Service │
└───────────────┘ └───────────────┘
│ │
├──► Actualiza XP │
├──► Verifica level up ├──► Agrega monedas
├──► Verifica achievements ├──► Registra transaccion
└──► Verifica rank up │
│
▼
┌───────────────┐
│ Missions │
│ Service │
└───────────────┘
│
└──► Actualiza progreso mision
DTOs y sus Consumidores
| DTO |
Definido en |
Consumido por Student |
Consumido por Teacher |
CreateSubmissionDto |
progress/dto |
ExercisePage.tsx |
- |
SubmissionResponseDto |
progress/dto |
ExercisePage.tsx |
ExerciseResponsesPage.tsx |
ModuleProgressDto |
progress/dto |
DashboardComplete.tsx |
TeacherProgressPage.tsx |
UserStatsDto |
gamification/dto |
ProfilePage.tsx |
TeacherGamificationPage.tsx |
ExerciseResponseDto |
teacher/dto |
- |
ExerciseResponsesPage.tsx |
2.3 Capa de Frontend
Hooks y APIs que Comparten Datos
| API Service |
Hooks Student |
Hooks Teacher |
Datos Compartidos |
progressAPI |
useDashboardData, useUserModules |
useStudentProgress |
module_progress |
gamificationAPI |
useGamificationData |
useStudentsEconomy, useAchievementsStats |
user_stats, achievements |
submissionsAPI |
useExerciseState |
useExerciseResponses |
exercise_submissions |
missionsAPI |
useMissions |
- (pendiente) |
missions, user_missions |
3. Matriz de Impacto por Cambio
3.1 Si Modificas la Estructura de Respuestas (answer_data)
| Componente |
Impacto |
Accion Requerida |
CrucigramaExercise.tsx (Student) |
ORIGEN |
Modificar estructura de respuestas |
exercise-answer.validator.ts (Backend) |
ALTO |
Actualizar validador del tipo |
validate_and_audit() (DB Function) |
ALTO |
Actualizar logica de comparacion |
SubmissionResponseDto (Backend) |
ALTO |
Actualizar DTO de respuesta |
ExerciseResponsesPage.tsx (Teacher) |
ALTO |
Actualizar renderizado de respuestas |
ResponseDetailModal.tsx (Teacher) |
ALTO |
Actualizar visualizacion detallada |
3.2 Si Modificas el Schema de exercise_submissions
| Componente |
Impacto |
Accion Requerida |
DDL en apps/database/ddl/ |
ORIGEN |
Modificar schema |
exercise-submission.entity.ts |
CRITICO |
Actualizar entity |
ExerciseSubmissionService |
CRITICO |
Actualizar queries |
| Triggers en BD |
CRITICO |
Verificar que no se rompan |
SubmissionResponseDto |
ALTO |
Actualizar DTO |
| Teacher hooks/pages |
MEDIO |
Puede requerir actualizacion |
3.3 Si Modificas los Triggers de BD
| Trigger |
Si lo modificas, afecta a... |
trg_update_module_progress |
Dashboard Teacher (stats incorrectas), Reportes de progreso |
trg_update_user_stats |
Gamification en Teacher, Leaderboards, Rankings |
trg_check_student_failures |
Alertas de intervencion (no se generan) |
trg_update_missions_progress |
Progreso de misiones (Teacher no ve misiones activas) |
3.4 Si Modificas el Calculo de Score
| Componente |
Impacto |
Consecuencia |
autoGrade() en Service |
ORIGEN |
Nuevo calculo |
validate_and_audit() en BD |
POSIBLE |
Si calculo es en BD |
exercise_submissions.score |
ALMACENADO |
Scores nuevos diferentes |
| Teacher Dashboard stats |
VISUALIZADO |
Promedios cambian |
| Triggers de gamificacion |
DEPENDIENTE |
XP/Coins cambian |
| Alertas de bajo rendimiento |
DEPENDIENTE |
Umbrales afectados |
4. Dependencias Criticas por Funcionalidad
4.1 Flujo: Estudiante Envia Ejercicio
ORDEN DE DEPENDENCIAS (no alterar):
1. Student Frontend
└── ExercisePage.tsx hace POST /submissions
│
2. Backend Controller
└── exercises.controller.ts recibe request
│
3. Backend Service
└── ExerciseSubmissionService.submitAndGrade()
│
├── 3a. ExerciseAnswerValidator.validate()
│ └── DEPENDE DE: estructura correcta de answer_data
│
├── 3b. EntityManager.save(submission)
│ └── DEPENDE DE: entity correcta, BD disponible
│
└── 3c. TRIGGERS SE DISPARAN AUTOMATICAMENTE
│
├── trg_update_module_progress
│ └── DEPENDE DE: exercise.module_id existe
│ └── AFECTA A: module_progress (Teacher ve esto)
│
├── trg_update_user_stats
│ └── DEPENDE DE: user_stats existe para user
│ └── AFECTA A: XP, ML Coins (Teacher ve esto)
│
└── trg_check_student_failures
└── DEPENDE DE: score < 60, classroom_members existe
└── AFECTA A: student_intervention_alerts (Teacher ve esto)
4.2 Flujo: Teacher Ve Respuestas
ORDEN DE DEPENDENCIAS:
1. Teacher Frontend
└── TeacherExerciseResponsesPage.tsx
│
2. Teacher Hook
└── useExerciseResponses()
│
└── GET /teacher/exercise-responses
│
3. Backend Controller
└── teacher.controller.ts
│
4. Backend Service
└── ExerciseResponsesService.getResponses()
│
└── DEPENDE DE:
├── exercise_submissions (que Student genero)
├── exercises (para metadata del ejercicio)
├── profiles (para nombre del estudiante)
└── classroom_members (para filtrar por aula del teacher)
5. Objetos que DEBEN Existir Antes de Desarrollo
5.1 Para Desarrollo en Student Portal
| Objeto |
Ubicacion |
Verificar que existe |
| Entity ExerciseSubmission |
backend/progress/entities/ |
exercise_id, user_id, answer_data, score |
| Tabla exercise_submissions |
database/ddl/schemas/progress_tracking/ |
Schema correcto |
| Trigger update_module_progress |
BD |
SELECT * FROM pg_trigger WHERE tgname = 'trg_update_module_progress' |
| Trigger update_user_stats |
BD |
SELECT * FROM pg_trigger WHERE tgname = 'trg_update_user_stats' |
| ExerciseAnswerValidator |
backend/progress/dto/answers/ |
Validador del tipo de ejercicio |
5.2 Para Desarrollo en Teacher Portal
| Objeto |
Ubicacion |
Verificar que existe |
| Endpoint GET /teacher/exercise-responses |
backend/teacher/controllers/ |
Implementado y funcional |
| ExerciseResponseDto |
backend/teacher/dto/ |
Campos necesarios definidos |
| exercise_submissions poblada |
BD |
Hay datos de prueba |
| Relacion classroom_members |
BD |
Estudiantes asignados a aulas |
| Relacion teacher_classrooms |
BD |
Teacher asignado a aulas |
6. Comandos de Verificacion
6.1 Verificar Triggers Activos
-- Listar todos los triggers relacionados con submissions
SELECT
t.tgname AS trigger_name,
c.relname AS table_name,
p.proname AS function_name,
CASE t.tgenabled
WHEN 'O' THEN 'ENABLED (origin)'
WHEN 'D' THEN 'DISABLED'
WHEN 'R' THEN 'ENABLED (replica)'
WHEN 'A' THEN 'ENABLED (always)'
END AS status
FROM pg_trigger t
JOIN pg_class c ON t.tgrelid = c.oid
JOIN pg_proc p ON t.tgfoid = p.oid
WHERE c.relname = 'exercise_submissions';
6.2 Verificar Dependencias de FK
-- Ver todas las foreign keys que apuntan a exercise_submissions
SELECT
tc.table_schema,
tc.table_name,
kcu.column_name,
ccu.table_name AS foreign_table_name,
ccu.column_name AS foreign_column_name
FROM information_schema.table_constraints AS tc
JOIN information_schema.key_column_usage AS kcu
ON tc.constraint_name = kcu.constraint_name
JOIN information_schema.constraint_column_usage AS ccu
ON ccu.constraint_name = tc.constraint_name
WHERE tc.constraint_type = 'FOREIGN KEY'
AND (ccu.table_name = 'exercise_submissions'
OR tc.table_name = 'exercise_submissions');
6.3 Verificar que Teacher Puede Ver Datos
-- Verificar que hay datos para un teacher especifico
SELECT
p.first_name || ' ' || p.last_name AS student_name,
e.title AS exercise_title,
es.score,
es.submitted_at
FROM progress_tracking.exercise_submissions es
JOIN auth_management.profiles p ON p.id = es.user_id
JOIN educational_content.exercises e ON e.id = es.exercise_id
JOIN social_features.classroom_members cm ON cm.user_id = es.user_id
JOIN social_features.teacher_classrooms tc ON tc.classroom_id = cm.classroom_id
WHERE tc.teacher_id = '<TEACHER_PROFILE_ID>'
ORDER BY es.submitted_at DESC
LIMIT 10;
7. Checklist de Impacto
Antes de cualquier cambio, responde estas preguntas:
7.1 Checklist General
7.2 Checklist Especifico Student
7.3 Checklist Especifico Teacher
Documento creado por: Architecture-Analyst
Fecha: 2025-11-29
Estado: VIGENTE
rckrdmrd
ea1879f4ad