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

# PLAN DE 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 creación:** 2026-01-08
**Relacionado con:** [TEACHER-PORTAL], [PROGRESS-TRACKING], [MANUAL-REVIEWS]

---

## 🔍 VERIFICACIÓN DE CATÁLOGO

**Funcionalidades a verificar:**
| Funcionalidad | ¿Aplica? | Catálogo | Acción |
|---------------|----------|----------|--------|
| auth/login | No | N/A | N/A |
| multi-tenant | No | N/A | N/A |
| notificaciones | No | N/A | N/A |

**Resultado:** No aplica catálogo

---

## 🎯 OBJETIVO

Corregir la visualización de datos en la página `/teacher/reviews` para que muestre correctamente la información del estudiante, ejercicio y fecha de envío.

**Criterios de Aceptación:**
- [x] El título del ejercicio se muestra correctamente
- [x] El módulo del ejercicio se muestra correctamente
- [x] El nombre del estudiante se muestra correctamente
- [x] La fecha de envío es la del submission, no del review
- [x] El detalle del review muestra los mismos datos correctamente

---

## 📋 ANÁLISIS PREVIO

### Contexto
La página de revisiones del docente muestra fallbacks ("Sin título", "Desconocido") porque el backend no retorna datos enriquecidos de student y exercise.

### Estado Actual
- ManualReviewService retorna reviews con relación `submission` pero sin datos de `student` ni `exercise`
- Frontend espera campos `student.name`, `exercise.title`, `exercise.moduleId` poblados
- Arquitectura cross-database impide JOINs TypeORM entre schemas

### Anti-Duplicación
```bash
# Comandos ejecutados para verificar no-duplicación
grep -rn "enrichReview" apps/backend/src/
# Resultado: No existe función de enriquecimiento previa
```

---

## 📐 DISEÑO DE SOLUCIÓN

### Approach Seleccionado
Inyectar repositorios de Profile y Exercise en ManualReviewService, crear métodos helper para enriquecimiento batch y individual, y modificar los métodos de consulta existentes para usar estos helpers.

### Componentes a Crear/Modificar

**Database:**
- [x] Trigger: 17-trg_create_manual_review_on_update.sql (nuevo - AFTER UPDATE)
- [x] Script: fix-missing-manual-reviews.sql (migración datos existentes)

**Backend:**
- [x] Interface: EnrichedManualReview
- [x] Method: enrichReview (individual)
- [x] Method: enrichReviews (batch)
- [x] Modify: findPendingReviews
- [x] Modify: findById
- [x] Modify: findByTeacher

**Frontend:**
- [x] Interface: ManualReview.exercise (agregar type)
- [x] Interface: ManualReview.submission (agregar submitted_at)
- [x] Component: ReviewList (usar fecha correcta)
- [x] Component: ReviewDetail (usar fecha correcta, fallback email)

---

## 🔄 CICLOS DE EJECUCIÓN

### Ciclo 1: Modificaciones Backend

**Duración estimada:** 1.5 horas
**Objetivo:** Enriquecer datos de reviews en el servicio

**Tareas:**
1. Importar entidades Profile y Exercise
2. Inyectar repositorios profileRepo y exerciseRepo
3. Crear interface EnrichedManualReview
4. Crear método enrichReview() para enriquecimiento individual
5. Crear método enrichReviews() para enriquecimiento batch
6. Modificar findPendingReviews() para enriquecer reviews
7. Modificar findById() para enriquecer review
8. Modificar findByTeacher() para enriquecer reviews

**Artefactos generados:**
- apps/backend/src/modules/teacher/services/manual-review.service.ts (modificado)

**Validación:**
```bash
cd apps/backend && npx tsc --noEmit --skipLibCheck
# Debe compilar sin errores
```

**Criterios de éxito:**
- [x] Compilación exitosa
- [x] Interface EnrichedManualReview definida
- [x] Métodos de enriquecimiento implementados

---

### Ciclo 2: Modificaciones Frontend

**Duración estimada:** 45 minutos
**Objetivo:** Actualizar interfaces y componentes

**Tareas:**
1. Actualizar interface ManualReview en manualReviewApi.ts
2. Agregar campos exercise.type, exercise.exercise_type
3. Agregar campos submission.submittedAt, submission.submitted_at
4. Modificar ReviewList para usar fecha de submission
5. Modificar ReviewDetail para usar fecha de submission
6. Agregar fallback para email del estudiante

**Artefactos generados:**
- apps/frontend/src/shared/api/manualReviewApi.ts (modificado)
- apps/frontend/src/apps/teacher/components/review-panel/ReviewList.tsx (modificado)
- apps/frontend/src/apps/teacher/components/review-panel/ReviewDetail.tsx (modificado)

**Validación:**
```bash
cd apps/frontend && npx tsc --noEmit --skipLibCheck 2>&1 | grep -E "(ReviewList|ReviewDetail|manualReviewApi)"
# No debe haber errores en estos archivos
```

**Criterios de éxito:**
- [x] Compilación de archivos modificados sin errores
- [x] Interfaces actualizadas con campos necesarios

---

### Ciclo 3: Validación Final

**Duración estimada:** 30 minutos
**Objetivo:** Validar integración completa

**Validaciones:**
```bash
# Backend
cd apps/backend && npm run build
# Debe compilar sin errores

# Frontend (archivos modificados)
cd apps/frontend && npx tsc --noEmit --skipLibCheck 2>&1 | grep -E "(ReviewList|ReviewDetail|manualReviewApi)"
# No debe haber errores
```

**Checklist de Validación:**
- [x] Backend compila sin errores
- [x] Frontend (archivos modificados) compila sin errores
- [x] Documentación actualizada
- [x] Inventarios actualizados (N/A - no requiere cambios en inventarios de configuración)
- [x] Sin errores de compilación en archivos modificados
- [x] Sin duplicaciones creadas
- [x] Cumple estándares de código

---

## 🔗 DEPENDENCIAS

### Depende de:
- Ninguna

### Bloquea:
- Ninguna

### Requerimientos externos:
- Ninguno

---

## ⚠️ RIESGOS IDENTIFICADOS

| Riesgo | Probabilidad | Impacto | Mitigación |
|--------|-------------|---------|------------|
| Performance con queries adicionales | Media | Bajo | Usar batch queries con IN clause |
| Incompatibilidad de nombres de campos (snake_case vs camelCase) | Media | Medio | Soportar ambos formatos en interface |

---

## 📊 ESTIMACIONES

**Tiempo total estimado:** 4 horas

**Desglose:**
- Análisis: 1h
- Desarrollo Backend: 1.5h
- Desarrollo Frontend: 0.5h
- Testing: 0.5h
- Documentación: 0.5h

**Recursos necesarios:**
- Agentes: Backend-Agent, Frontend-Agent
- Herramientas: TypeScript, TypeORM, React

---

## 📝 DOCUMENTACIÓN A GENERAR

**Durante ejecución:**
- [x] Comentarios inline con tag FIX BUG-TEACHER-REVIEWS-002

**Post-ejecución:**
- [x] ANALISIS-BUG-TEACHER-REVIEWS-002-2026-01-08.md
- [x] PLAN-BUG-TEACHER-REVIEWS-002-2026-01-08.md
- [x] Actualización de MASTER_INVENTORY.yml (N/A - cambios de código, no de configuración)

---

## 🎯 CRITERIOS DE ÉXITO

La tarea se considera **COMPLETADA** cuando:

- [x] Backend compila sin errores
- [x] Frontend (archivos modificados) compila sin errores
- [x] Datos de student poblados correctamente
- [x] Datos de exercise poblados correctamente
- [x] Fecha de envío usa submitted_at del submission
- [x] Sin duplicaciones creadas
- [x] Cumple estándares de código
- [x] Documentación completa

---

## 📁 ARCHIVOS MODIFICADOS

### Database

| Archivo | Cambio | Ubicación |
|---------|--------|-----------|
| `17-trg_create_manual_review_on_update.sql` | Nuevo trigger AFTER UPDATE | ddl/schemas/progress_tracking/triggers/ |
| `fix-missing-manual-reviews.sql` | Script migración datos | scripts/ |

### Backend

| Archivo | Cambio | Líneas |
|---------|--------|--------|
| `manual-review.service.ts` | Import Profile, Exercise | 13-15 |
| `manual-review.service.ts` | Interface EnrichedManualReview | 61-77 |
| `manual-review.service.ts` | Inyección repositorios | 105-109 |
| `manual-review.service.ts` | Método enrichReview() | 117-168 |
| `manual-review.service.ts` | Método enrichReviews() | 170-239 |
| `manual-review.service.ts` | findPendingReviews() enriquece | 284-288, 319-323 |
| `manual-review.service.ts` | findById() retorna enriched | 660-681 |
| `manual-review.service.ts` | findByTeacher() retorna enriched | 683-711 |

### Frontend

| Archivo | Cambio | Líneas |
|---------|--------|--------|
| `manualReviewApi.ts` | exercise.type, exercise_type | 84-85 |
| `manualReviewApi.ts` | submission.submitted_at | 89 |
| `ReviewList.tsx` | Fecha usa submitted_at | 170-174 |
| `ReviewDetail.tsx` | Email con fallback | 164-170 |
| `ReviewDetail.tsx` | Fecha usa submitted_at | 173-180 |

---

## 📚 REFERENCIAS

**Documentación del proyecto:**
- Vista SQL: apps/database/ddl/schemas/progress_tracking/views/02-teacher_pending_reviews.sql

**Archivos de referencia:**
- Entity Profile: apps/backend/src/modules/auth/entities/profile.entity.ts
- Entity Exercise: apps/backend/src/modules/educational/entities/exercise.entity.ts

---

**Versión:** 1.0
**Última actualización:** 2026-01-08
**Estado:** COMPLETADO