workspace-v1/orchestration/analisis/ANALISIS-BUG-TEACHER-REVIEWS-002-2026-01-08.md

ANÁLISIS PRE-EJECUCIÓN: BUG-TEACHER-REVIEWS-002 - Datos faltantes en página teacher/reviews

Agente: Backend-Agent + Frontend-Agent Tipo de tarea: Bug Prioridad: P1 Fecha análisis: 2026-01-08 Relacionado con: [TEACHER-PORTAL], [PROGRESS-TRACKING], [MANUAL-REVIEWS]

---

📋 CONTEXTO DE LA TAREA

Solicitud Original

En la página /teacher/reviews los datos del ejercicio se muestran incorrectamente:

• "Ejercicio sin título"
• "Módulo: N/A"
• "Estudiante desconocido"
• "Fecha no disponible"

A pesar de que sí detecta que hay una respuesta, no parece estar obteniendo bien los datos. El error también se replica cuando se abre el detalle de la respuesta.

Objetivo Final

Corregir la visualización de datos en la página de revisiones del docente para que muestre correctamente:

• Título del ejercicio
• Módulo al que pertenece
• Nombre del estudiante
• Fecha de envío del submission

Módulo Relacionado

Módulo MVP: Teacher Portal - Manual Reviews Sección en MVP-APP.md: Módulos 4-5 que requieren evaluación manual

Justificación

Los docentes necesitan ver información completa de los estudiantes y ejercicios para poder realizar evaluaciones manuales. Sin esta información, el flujo de trabajo de evaluación manual está comprometido.

---

🔍 INVENTARIO ACTUAL

Consultas Realizadas

Inventarios revisados:

• MASTER_INVENTORY.yml
• DATABASE_INVENTORY.yml
• BACKEND_INVENTORY.yml
• FRONTEND_INVENTORY.yml

Comandos ejecutados:

# Búsqueda de componentes de review
grep -rn "ManualReview" apps/backend/src/modules/teacher/
grep -rn "ReviewList\|ReviewDetail" apps/frontend/src/apps/teacher/

# Resultado:
# ✅ Existen componentes y servicios relacionados

Objetos Existentes Relacionados

Base de Datos:

• Schema: progress_tracking → EXISTE
• Tabla: manual_reviews → EXISTE
• Tabla: exercise_submissions → EXISTE
• Vista: teacher_pending_reviews → EXISTE (con JOINs correctos)
• Schema: auth_management → EXISTE
• Tabla: profiles → EXISTE
• Schema: educational_content → EXISTE
• Tabla: exercises → EXISTE

Backend:

• Módulo: teacher → EXISTE
• Entity: ManualReview → EXISTE (progress/entities)
• Entity: ExerciseSubmission → EXISTE (progress/entities)
• Service: ManualReviewService → EXISTE
• Controller: ManualReviewController → EXISTE

Frontend:

• Página: TeacherReviewPanelPage → EXISTE
• Componente: ReviewList → EXISTE
• Componente: ReviewDetail → EXISTE
• API Client: manualReviewApi → EXISTE
• Hook: useManualReviews → EXISTE

Objetos a Crear/Modificar

Nuevos objetos:

• Interface: EnrichedManualReview (backend)
• Trigger: trg_create_manual_review_on_submission_update (database)
• Script: fix-missing-manual-reviews.sql (migración datos)

Objetos a modificar:

• Service: ManualReviewService (agregar métodos enrichReview, enrichReviews)
• Service: ManualReviewService (modificar findPendingReviews, findById, findByTeacher)
• Interface: ManualReview (frontend - agregar campos exercise.type, submission.submitted_at)
• Component: ReviewList (usar fecha de submission)
• Component: ReviewDetail (usar fecha de submission, fallback email)

---

⚠️ ANÁLISIS DE RIESGOS

Riesgo de Duplicación

Verificación:

• NO existe schema similar
• NO existe tabla similar
• NO existe módulo/entity similar
• NO existe componente similar

Decisión:

• Modificar objeto existente: ManualReviewService

Otros Riesgos Identificados

Riesgo	Probabilidad	Impacto	Mitigación
Breaking change en API response	Baja	Medio	Agregar campos opcionales, no cambiar estructura existente
Performance con queries adicionales	Media	Bajo	Usar batch queries con IN clause en lugar de queries individuales
Cross-database TypeORM limitation	Alta	Alto	Usar queries directas a repositorios separados, no JOINs TypeORM

---

🔗 ANÁLISIS DE IMPACTO

Archivos Afectados

A crear:

• apps/database/ddl/schemas/progress_tracking/triggers/17-trg_create_manual_review_on_update.sql
• apps/database/scripts/fix-missing-manual-reviews.sql

A modificar:

• apps/backend/src/modules/teacher/services/manual-review.service.ts
• apps/frontend/src/shared/api/manualReviewApi.ts
• apps/frontend/src/apps/teacher/components/review-panel/ReviewList.tsx
• apps/frontend/src/apps/teacher/components/review-panel/ReviewDetail.tsx

Total archivos:

• Crear: 2
• Modificar: 4

Dependencias

Esta tarea depende de:

• Ninguna tarea bloqueadora

Bloqueadores actuales:

• Ninguno

Esta tarea bloquea:

• Ninguna

Módulos Afectados

Impacto directo:

• Módulo: teacher (ManualReviewService)
• Stack: Backend + Frontend

Impacto indirecto:

• Módulos que consumen: API de manual reviews
• Módulos relacionados: progress, auth, educational

---

🎯 DECISIÓN DE APPROACH

Approach Seleccionado

Enriquecer los datos en el servicio backend inyectando repositorios de Profile y Exercise, y creando métodos helper que:

1. Para listas: Hacer batch queries optimizadas con IN clause
2. Para detalle: Hacer queries individuales por ID

Razones:

1. La arquitectura cross-database impide usar JOINs TypeORM entre schemas
2. La vista SQL teacher_pending_reviews existe pero solo se usa con filtro de módulo
3. Enriquecer en backend evita múltiples llamadas HTTP desde frontend

Alternativas Consideradas

Alternativa 1: Usar siempre la vista SQL teacher_pending_reviews

• Pros: Ya tiene todos los JOINs correctos, mejor performance
• Contras: Requiere mapear resultado de vista a formato de entidad, solo funciona para listados
• Razón de descarte: No resuelve el problema del detalle individual

Alternativa 2: Enriquecer en frontend con queries adicionales

• Pros: Backend sin cambios
• Contras: Múltiples llamadas HTTP, mayor complejidad en frontend, peor UX
• Razón de descarte: Ineficiente, mala experiencia de usuario

---

🔄 NECESIDAD DE SUBAGENTES

Análisis de Complejidad

Criterios:

• Número de pasos: 4 → Media (3-5)
• Módulos afectados: 2 (backend, frontend) → Media (2-3)
• Archivos a crear: 0 → Simple (<5)
• Coordinación entre capas: Sí

Decisión:

• NO usar subagentes - Tarea ejecutable directamente con coordinación backend/frontend

---

📊 ESTIMACIÓN PRELIMINAR

Tiempo Estimado por Fase

Fase	Duración Estimada	Notas
Análisis	1h	Este documento
Planificación	30min	Plan de ejecución
Ejecución	2h	Backend + Frontend
Validación	30min	Compilación + verificación
Documentación	30min	Inventarios + trazas
TOTAL	4.5h

Recursos Necesarios

Agentes:

• Agente principal: Backend-Agent + Frontend-Agent coordinados

Herramientas:

• TypeScript compiler
• TypeORM
• React

Información adicional requerida:

• Ninguna

---

📚 REFERENCIAS CONSULTADAS

Documentación del Proyecto

• Estructura de schemas de base de datos
• Vista teacher_pending_reviews
• Arquitectura cross-database

Código Existente

Archivos de referencia:

• apps/database/ddl/schemas/progress_tracking/views/02-teacher_pending_reviews.sql - Vista con JOINs correctos
• apps/backend/src/modules/progress/entities/exercise-submission.entity.ts - Estructura del submission
• apps/backend/src/modules/auth/entities/profile.entity.ts - Estructura del profile

---

✅ CONCLUSIÓN DEL ANÁLISIS

Resumen

El problema raíz es que el backend retorna ManualReview con solo la relación submission cargada (mismo schema), pero sin los datos de student y exercise que residen en schemas diferentes. La arquitectura cross-database de TypeORM impide usar JOINs directos. La solución es enriquecer los datos en el servicio usando queries adicionales a los repositorios de Profile y Exercise.

Decisiones Clave

1. Approach: Enriquecer en backend con batch queries
2. Subagentes: No usar
3. Objetos a crear: 1 interface (EnrichedManualReview)
4. Duración estimada: 4.5h

Recomendaciones

1. Usar batch queries con IN clause para optimizar performance
2. Mantener compatibilidad con la estructura de respuesta existente (agregar campos, no cambiar)
3. Soportar ambos formatos de fecha (snake_case y camelCase) en frontend

Aprobación para Proceder

• Análisis completo y documentado
• Sin bloqueadores identificados
• Recursos disponibles
• Estimaciones validadas
• APROBADO PARA EJECUCIÓN

---

🚀 PRÓXIMO PASO

Acción: Crear documento de ejecución

Template: PLAN-BUG-TEACHER-REVIEWS-002-2026-01-08.md

---

Analizado por: Claude Code - Tech Lead Agent Fecha: 2026-01-08 Versión: 1.0 Estado: Aprobado