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:**
- [x] MASTER_INVENTORY.yml
- [x] DATABASE_INVENTORY.yml
- [x] BACKEND_INVENTORY.yml
- [x] FRONTEND_INVENTORY.yml

**Comandos ejecutados:**
```bash
# 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:**
- [x] Interface: EnrichedManualReview (backend)
- [x] Trigger: trg_create_manual_review_on_submission_update (database)
- [x] Script: fix-missing-manual-reviews.sql (migración datos)

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

---

## ⚠️ ANÁLISIS DE RIESGOS

### Riesgo de Duplicación

**Verificación:**
- [x] NO existe schema similar
- [x] NO existe tabla similar
- [x] NO existe módulo/entity similar
- [x] NO existe componente similar

**Decisión:**
- [x] 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:**
- [x] **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
- [x] Estructura de schemas de base de datos
- [x] Vista teacher_pending_reviews
- [x] 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
- [x] Análisis completo y documentado
- [x] Sin bloqueadores identificados
- [x] Recursos disponibles
- [x] Estimaciones validadas
- [x] **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