Skip to content

Phase 5: Assessments & Assignments #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sbafsk wants to merge 1 commit into
base: phase-4
Choose a base branch
from
Open

Phase 5: Assessments & Assignments #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
366 changes: 366 additions & 0 deletions PHASE5_COMPLETE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,366 @@
# ✅ Fase 5: Assessments & Assignments - COMPLETA

## Resumen

Se ha completado exitosamente la **Fase 5: Assessments & Assignments** del proyecto SUPAP Backend. Esta fase incluye la implementación completa del sistema de tareas (assignments), entregas (submissions), evaluaciones (assessments) e intentos (attempts) para el módulo Aula Virtual.

**Fecha de finalización**: 2025-11-24
**Estado**: ✅ Completada

---

## 🎯 Componentes Implementados

### 1. Entidades JPA ✅

#### Assignment Entity
- ✅ Relación Many-to-One con Lesson (opcional)
- ✅ Campos: title, instructions, dueDate, maxScore
- ✅ Relación One-to-Many con Submission

#### Submission Entity
- ✅ Relación Many-to-One con Assignment y User
- ✅ Enum SubmissionStatus: DRAFT, SUBMITTED, GRADED, RETURNED
- ✅ Campos: content, fileUrl, score, feedback
- ✅ Tracking de calificación: gradedAt, gradedBy

#### Assessment Entity
- ✅ Relación Many-to-One con Lesson (opcional)
- ✅ Campos: title, questions (JSON), timeLimit, passingScore, maxAttempts
- ✅ Relación One-to-Many con AssessmentAttempt

#### AssessmentAttempt Entity
- ✅ Relación Many-to-One con Assessment y User
- ✅ Campos: answers (JSON), score, passed, attemptNumber
- ✅ Tracking: startedAt, completedAt

### 2. Repositorios ✅

#### AssignmentRepository
- ✅ `findByLessonId()` - Asignaciones por lección

#### SubmissionRepository
- ✅ `findByAssignmentIdAndUserId()` - Entrega específica
- ✅ `findByAssignmentId()` - Todas las entregas de una asignación
- ✅ `findByUserId()` - Entregas de un usuario
- ✅ `findByAssignmentIdAndStatus()` - Filtrar por estado

#### AssessmentRepository
- ✅ `findByLessonId()` - Evaluaciones por lección

#### AssessmentAttemptRepository
- ✅ `findByAssessmentIdAndUserId()` - Intentos de un usuario
- ✅ `findByAssessmentId()` - Todos los intentos
- ✅ `countByAssessmentIdAndUserId()` - Contar intentos
- ✅ `findLatestAttemptByAssessmentIdAndUserId()` - Último intento

### 3. Migraciones Flyway ✅

- ✅ `V6__create_assignments_assessments_tables.sql` - Todas las tablas
- Tabla `assignments` con relación a lessons
- Tabla `submissions` con relación a assignments y users
- Tabla `assessments` con relación a lessons
- Tabla `assessment_attempts` con relación a assessments y users
- Índices para optimización

### 4. DTOs ✅

#### Request DTOs:
- ✅ `AssignmentRequest` - Crear/actualizar asignaciones
- ✅ `SubmissionRequest` - Crear/actualizar entregas
- ✅ `GradeSubmissionRequest` - Calificar entregas
- ✅ `AssessmentRequest` - Crear/actualizar evaluaciones
- ✅ `AssessmentAttemptRequest` - Iniciar/enviar intentos

#### Response DTOs:
- ✅ `AssignmentResponse` - Información de asignación
- ✅ `SubmissionResponse` - Información de entrega (con datos de calificación)
- ✅ `AssessmentResponse` - Información de evaluación
- ✅ `AssessmentAttemptResponse` - Información de intento

### 5. Servicios ✅

#### AssignmentService
- ✅ `getAssignmentsByLesson()` - Listar asignaciones por lección
- ✅ `getAssignmentById()` - Obtener asignación
- ✅ `createAssignment()` - Crear asignación
- ✅ `updateAssignment()` - Actualizar asignación
- ✅ `deleteAssignment()` - Eliminar asignación

#### SubmissionService
- ✅ `createOrUpdateSubmission()` - Crear o actualizar entrega
- Crea nueva si no existe, actualiza si ya existe
- ✅ `submitAssignment()` - Enviar entrega (cambia estado a SUBMITTED)
- ✅ `gradeSubmission()` - Calificar entrega (Instructor/Admin)
- Actualiza score, feedback, estado a GRADED
- Registra quién calificó y cuándo
- ✅ `getMySubmissions()` - Mis entregas
- ✅ `getSubmissionById()` - Obtener entrega (con validación de propiedad)
- ✅ `getSubmissionsByAssignment()` - Entregas de una asignación (Instructor/Admin)
- ✅ `getSubmissionsByAssignmentAndStatus()` - Filtrar por estado

#### AssessmentService
- ✅ `getAssessmentsByLesson()` - Listar evaluaciones por lección
- ✅ `getAssessmentById()` - Obtener evaluación
- ✅ `createAssessment()` - Crear evaluación
- ✅ `updateAssessment()` - Actualizar evaluación
- ✅ `deleteAssessment()` - Eliminar evaluación
- ✅ `startAttempt()` - Iniciar intento
- Validación de máximo de intentos
- Asignación automática de attemptNumber
- ✅ `submitAttempt()` - Enviar intento
- Cálculo de score (placeholder - requiere implementación de lógica de scoring)
- Determinación de passed basado en passingScore
- ✅ `getMyAttempts()` - Mis intentos
- ✅ `getAssessmentAttempts()` - Todos los intentos (Instructor/Admin)

### 6. Controladores ✅

#### AssignmentController
- ✅ `GET /api/v1/assignments/lesson/{lessonId}` - Asignaciones por lección
- ✅ `GET /api/v1/assignments/{id}` - Obtener asignación
- ✅ `POST /api/v1/assignments` - Crear asignación (Admin/Instructor)
- ✅ `PUT /api/v1/assignments/{id}` - Actualizar asignación (Admin/Instructor)
- ✅ `DELETE /api/v1/assignments/{id}` - Eliminar asignación (Admin/Instructor)
- ✅ `POST /api/v1/assignments/submissions` - Crear/actualizar entrega (Usuario)
- ✅ `POST /api/v1/assignments/submissions/{id}/submit` - Enviar entrega (Usuario)
- ✅ `GET /api/v1/assignments/submissions/my` - Mis entregas (Usuario)
- ✅ `GET /api/v1/assignments/submissions/{id}` - Obtener entrega (Usuario)
- ✅ `GET /api/v1/assignments/{assignmentId}/submissions` - Entregas de asignación (Admin/Instructor)
- ✅ `POST /api/v1/assignments/submissions/{id}/grade` - Calificar entrega (Admin/Instructor)

#### AssessmentController
- ✅ `GET /api/v1/assessments/lesson/{lessonId}` - Evaluaciones por lección
- ✅ `GET /api/v1/assessments/{id}` - Obtener evaluación
- ✅ `POST /api/v1/assessments` - Crear evaluación (Admin/Instructor)
- ✅ `PUT /api/v1/assessments/{id}` - Actualizar evaluación (Admin/Instructor)
- ✅ `DELETE /api/v1/assessments/{id}` - Eliminar evaluación (Admin/Instructor)
- ✅ `POST /api/v1/assessments/attempts/start` - Iniciar intento (Usuario)
- ✅ `POST /api/v1/assessments/attempts/{id}/submit` - Enviar intento (Usuario)
- ✅ `GET /api/v1/assessments/{assessmentId}/attempts/my` - Mis intentos (Usuario)
- ✅ `GET /api/v1/assessments/{assessmentId}/attempts` - Todos los intentos (Admin/Instructor)

### 7. Excepciones ✅

- ✅ `ResourceNotFoundException` - Recurso no encontrado
- ✅ `EventRegistrationException` - Reutilizada para errores de autorización
- ✅ Manejo en `GlobalExceptionHandler`

### 8. Seguridad ✅

- ✅ Endpoints públicos para lectura de assignments y assessments
- ✅ Endpoints protegidos para estudiantes (requiere autenticación)
- ✅ Endpoints protegidos para instructores (requiere ROLE_INSTRUCTOR o ROLE_ADMIN)
- ✅ Validación de propiedad de recursos (solo el dueño puede acceder)

---

## 📊 Funcionalidades Implementadas

### Assignments (Tareas)
- ✅ Crear asignaciones asociadas a lecciones
- ✅ Actualizar y eliminar asignaciones
- ✅ Fecha de vencimiento y puntaje máximo
- ✅ Instrucciones detalladas

### Submissions (Entregas)
- ✅ Crear o actualizar entregas (borrador)
- ✅ Enviar entregas (cambia estado a SUBMITTED)
- ✅ Calificar entregas (Instructor/Admin)
- ✅ Feedback y puntaje
- ✅ Tracking de quién calificó y cuándo
- ✅ Estados: DRAFT, SUBMITTED, GRADED, RETURNED

### Assessments (Evaluaciones/Quizzes)
- ✅ Crear evaluaciones con preguntas (JSON)
- ✅ Límite de tiempo
- ✅ Puntaje de aprobación
- ✅ Límite de intentos máximo
- ✅ Actualizar y eliminar evaluaciones

### Assessment Attempts (Intentos)
- ✅ Iniciar intentos de evaluación
- ✅ Validación de máximo de intentos
- ✅ Enviar respuestas (JSON)
- ✅ Cálculo de score y estado passed
- ✅ Tracking de intentos (attemptNumber)
- ✅ Historial de intentos

---

## 🚀 Endpoints Disponibles

### Públicos
- `GET /api/v1/assignments/lesson/{lessonId}` - Asignaciones por lección
- `GET /api/v1/assignments/{id}` - Obtener asignación
- `GET /api/v1/assessments/lesson/{lessonId}` - Evaluaciones por lección
- `GET /api/v1/assessments/{id}` - Obtener evaluación

### Autenticados (Usuario)
- `POST /api/v1/assignments/submissions` - Crear/actualizar entrega
- `POST /api/v1/assignments/submissions/{id}/submit` - Enviar entrega
- `GET /api/v1/assignments/submissions/my` - Mis entregas
- `GET /api/v1/assignments/submissions/{id}` - Obtener entrega
- `POST /api/v1/assessments/attempts/start` - Iniciar intento
- `POST /api/v1/assessments/attempts/{id}/submit` - Enviar intento
- `GET /api/v1/assessments/{assessmentId}/attempts/my` - Mis intentos

### Admin/Instructor
- `POST /api/v1/assignments` - Crear asignación
- `PUT /api/v1/assignments/{id}` - Actualizar asignación
- `DELETE /api/v1/assignments/{id}` - Eliminar asignación
- `GET /api/v1/assignments/{assignmentId}/submissions` - Entregas de asignación
- `POST /api/v1/assignments/submissions/{id}/grade` - Calificar entrega
- `POST /api/v1/assessments` - Crear evaluación
- `PUT /api/v1/assessments/{id}` - Actualizar evaluación
- `DELETE /api/v1/assessments/{id}` - Eliminar evaluación
- `GET /api/v1/assessments/{assessmentId}/attempts` - Todos los intentos

---

## 📝 Ejemplos de Uso

### Crear Asignación (Instructor)
```bash
curl -X POST http://localhost:8080/api/v1/assignments \
-H "Authorization: Bearer INSTRUCTOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"lessonId": 5,
"title": "Tarea: Análisis de caso clínico",
"instructions": "Analizar el caso presentado y responder las preguntas...",
"dueDate": "2025-12-20T23:59:59",
"maxScore": 100
}'
```

### Crear Entrega (Estudiante)
```bash
curl -X POST http://localhost:8080/api/v1/assignments/submissions \
-H "Authorization: Bearer USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assignmentId": 1,
"content": "Mi análisis del caso...",
"fileUrl": "https://storage.example.com/submission.pdf"
}'
```

### Enviar Entrega
```bash
curl -X POST http://localhost:8080/api/v1/assignments/submissions/1/submit \
-H "Authorization: Bearer USER_TOKEN"
```

### Calificar Entrega (Instructor)
```bash
curl -X POST http://localhost:8080/api/v1/assignments/submissions/1/grade \
-H "Authorization: Bearer INSTRUCTOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"score": 85,
"feedback": "Excelente análisis. Considera profundizar en..."
}'
```

### Crear Evaluación (Instructor)
```bash
curl -X POST http://localhost:8080/api/v1/assessments \
-H "Authorization: Bearer INSTRUCTOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"lessonId": 5,
"title": "Quiz: Fundamentos de Psicoterapias",
"questions": "{\"questions\": [...]}",
"timeLimit": 30,
"passingScore": 70,
"maxAttempts": 3
}'
```

### Iniciar Intento de Evaluación
```bash
curl -X POST http://localhost:8080/api/v1/assessments/attempts/start \
-H "Authorization: Bearer USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assessmentId": 1
}'
```

### Enviar Intento
```bash
curl -X POST http://localhost:8080/api/v1/assessments/attempts/1/submit \
-H "Authorization: Bearer USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assessmentId": 1,
"answers": "{\"q1\": \"answer1\", \"q2\": \"answer2\"}"
}'
```

---

## ✅ Checklist de Fase 5

- [x] Assignment entity & submission
- [x] Assessment/Quiz entity
- [x] Grading system
- [x] Validación de intentos máximos
- [x] Tracking de calificaciones
- [x] Estados de entregas
- [x] Cálculo de score (placeholder)

---

## 📝 Próximos Pasos (Fase 6)

La siguiente fase incluirá:
- [ ] Payment entity completo
- [ ] MercadoPago integration
- [ ] Payment webhooks
- [ ] Receipt generation
- [ ] Refund handling

---

## 🔧 Notas Técnicas

### Características Implementadas
1. **Estados de Entrega**: DRAFT → SUBMITTED → GRADED → RETURNED
2. **Validación de Intentos**: Control de máximo de intentos por evaluación
3. **Tracking de Calificaciones**: Registro de quién calificó y cuándo
4. **JSON para Preguntas/Respuestas**: Estructura flexible para evaluaciones
5. **Borradores**: Los estudiantes pueden guardar borradores antes de enviar

### Consideraciones
- El cálculo de score en assessments es un placeholder - requiere implementación de lógica de scoring real
- Las preguntas y respuestas se almacenan como JSON - requiere validación y parsing en el frontend
- Los archivos de entrega se almacenan como URLs - requiere integración con servicio de almacenamiento (S3, Cloudinary)
- Los instructores pueden ver todas las entregas de sus asignaciones
- Los estudiantes solo pueden ver sus propias entregas

### Pendiente para Producción
- Implementar lógica real de scoring para assessments
- Integración con servicio de almacenamiento de archivos
- Validación y parsing de JSON de preguntas/respuestas
- Notificaciones por email al calificar entregas
- Sistema de comentarios en entregas

---

## 📚 Documentación

- **Arquitectura**: `BACKEND_ARCHITECTURE_GUIDE.md`
- **Fase 1**: `PHASE1_COMPLETE.md`
- **Fase 2**: `PHASE2_COMPLETE.md`
- **Fase 3**: `PHASE3_COMPLETE.md`
- **Fase 4**: `PHASE4_COMPLETE.md`
- **API Docs**: Swagger UI en `/swagger-ui.html`

---

**Fase 5 Completada** ✅
**Fecha**: 2025-11-24
**Próxima Fase**: Fase 6 - Payments Integration

Loading