[Funcionalidad]: Flujo evaluacion de competencias

[tomiban]

1. Creación de la instancia de evaluación

• Actor: Administrador
• Acción: Usa el comando CreateEvaluationInstanceCommand.
• Qué ocurre:
  • Se crea una nueva entidad CompetencyEvaluationInstance con estado Active.
  • Se asignan competencias a profesores (ProfessorCompetencyAssignment), cada una vinculada a una materia y competencia.
  • Por cada asignación, se generan automáticamente los registros de evaluación de competencias para cada estudiante de la materia (StudentCompetencyAssessment), todos con estado Pending.

---

2. Asignación de profesores

• Actor: Administrador (implícito en el paso anterior)
• Acción: Al crear la instancia, se definen las asignaciones de profesores a materias y competencias.
• Qué ocurre:
  • Cada profesor recibe sus asignaciones y puede ver a qué estudiantes debe evaluar.

---

3. Evaluación de estudiantes por los profesores

• Actor: Profesor
• Acción: Cada profesor accede a su lista de estudiantes asignados y realiza la evaluación de competencias.
• Qué ocurre:
  • Por cada estudiante, el profesor registra el nivel de competencia alcanzado.
  • El estado de cada StudentCompetencyAssessment pasa de Pending a Completed al ser evaluado.
  • El sistema verifica si el profesor completó todas sus evaluaciones para esa asignación y, si es así, marca la asignación como Completed (pero no la instancia de evaluación).

---

4. Finalización manual de la evaluación por el administrador

• Actor: Administrador
• Acción: Cuando lo desee, el administrador hace click en el botón "Finalizar Evaluaciones" para una instancia específica.
• Qué ocurre:
  • El sistema valida dos condiciones:
    1. Que el plazo de la evaluación haya finalizado (PeriodTo < ahora).
    2. Que todas las asignaciones de profesores estén completas (todas en estado Completed).
  • Si ambas condiciones se cumplen:
    • Se cambia el estado de la instancia a Completed.
    • Se dispara la generación de reportes PDF para cada estudiante (usando el servicio de generación de reportes).
    • Se almacenan las rutas de los PDFs en la base de datos.
  • Si alguna condición no se cumple, se muestra un mensaje de error y no se finaliza la evaluación.

---

5. Acceso a los reportes

• Actor: Administrador, estudiantes, coordinadores, etc.
• Acción: Acceden a los reportes generados.
• Qué ocurre:
  • El sistema genera una URL SAS temporal para cada PDF almacenado en Azure, permitiendo la descarga/visualización segura.

---

Resumen visual del flujo

sequenceDiagram
    participant Admin as Administrador
    participant System as Sistema
    participant Prof as Profesor
    participant Azure as Azure Storage

    Admin->>System: Crear instancia de evaluación (con asignaciones)
    System->>System: Crea instancia, asignaciones y evaluaciones de estudiantes

    Prof->>System: Evalúa a sus estudiantes
    System->>System: Marca evaluaciones y asignaciones como completadas

    Admin->>System: Click en \"Finalizar Evaluaciones\"
    System->>System: Valida plazo y asignaciones completas
    alt Condiciones OK
        System->>System: Cambia estado a Completed
        System->>System: Genera PDFs y guarda rutas
        System->>Azure: Sube PDFs
    else Condiciones NO OK
        System->>Admin: Muestra error
    end

    Admin->>System: Accede a reportes
    System->>Azure: Genera URL SAS temporal
    System->>Admin: Devuelve URL para descarga/visualización

Loading

---

¿Te gustaría que te detalle el código de algún paso específico, o necesitas ayuda con la integración frontend/backend para el botón de finalización?

Tipo de Cambio

• Funcionalidad - Nueva funcionalidad
• Corrección de Error - Solución a un bug
• Refactorización - Mejora de código sin cambiar la funcionalidad
• Documentación - Actualización de documentación
• Otro - Otro (especificar en la descripción)

Pruebas

• Este cambio fue probado correctamente

Lista de Verificación

No response

[tomiban]

✅ Repositorios necesarios (Interfaces de Dominio)

Estas interfaces viven en la capa de dominio o aplicación y deben tener sus implementaciones en la capa de infraestructura:

ICompetencyEvaluationInstanceRepository

• Task<CompetencyEvaluationInstance?> GetByIdAsync(Guid id)
• Task AddAsync(CompetencyEvaluationInstance instance)
• Task UpdateAsync(CompetencyEvaluationInstance instance)
• Task<IEnumerable<CompetencyEvaluationInstance>> GetAllAsync()
• Task<IEnumerable<CompetencyEvaluationInstance>> GetPendingToFinalizeAsync()

---

IProfessorCompetencyAssignmentRepository

• Task<IEnumerable<ProfessorCompetencyAssignment>> GetByProfessorIdAsync(Guid professorId)
• Task<IEnumerable<ProfessorCompetencyAssignment>> GetByInstanceIdAsync(Guid instanceId)
• Task UpdateAsync(ProfessorCompetencyAssignment assignment)

---

IStudentCompetencyAssessmentRepository

• Task<IEnumerable<StudentCompetencyAssessment>> GetByAssignmentIdAsync(Guid assignmentId)
• Task<StudentCompetencyAssessment?> GetByIdAsync(Guid id)
• Task UpdateAsync(StudentCompetencyAssessment assessment)
• Task<IEnumerable<StudentCompetencyAssessment>> GetByStudentIdAsync(Guid studentId)

---

IReportStorageService (adaptador hacia Azure Blob Storage, etc.)

• Task<string> SaveReportAsync(byte[] pdfContent, string fileName)
• Task<string> GenerateSasUrlAsync(string blobPath)

---

✅ Endpoints (REST o Minimal API)

Agrupados por rol y propósito:

---

Administrador

POST /evaluations

Descripción: Crea una nueva instancia de evaluación.
Body: { PeriodFrom, PeriodTo, Assignments: [{ ProfessorId, SubjectId, CompetencyId }] }
Handler: CreateEvaluationInstanceCommandHandler

---

POST /evaluations/{id}/finalize

Descripción: Intenta finalizar una instancia de evaluación (verifica condiciones).
Handler: FinalizeEvaluationInstanceCommandHandler

---

GET /evaluations

Descripción: Listado de todas las instancias de evaluación (filtro por estado opcional).

---

GET /reports/{studentId}

Descripción: Devuelve las URLs SAS de los reportes PDF para un estudiante.

---

Profesor

GET /assignments

Descripción: Devuelve todas las asignaciones del profesor autenticado.

---

GET /assignments/{id}/students

Descripción: Devuelve los estudiantes a evaluar en una asignación.

---

POST /assessments/{id}/complete

Descripción: Completa una evaluación de competencia para un estudiante.
Body: { CompetencyLevel: int }

---

Estudiante / Coordinador

GET /students/{id}/reports

Descripción: Devuelve URLs SAS de los reportes generados para el estudiante.

---

✅ Servicios secundarios / utilitarios

• IPdfReportGenerator – Servicio de aplicación para generar el PDF del informe del estudiante.
• IDateTimeProvider – Para testear condiciones como now > PeriodTo.
• INotificationService (opcional) – Para alertar cuando una evaluación ya se puede cerrar.

---

¿Querés ejemplos de los contratos (DTOs) y handlers?

Puedo generarte un ejemplo concreto del comando CreateEvaluationInstanceCommand y su handler, o del endpoint para que un profesor complete la evaluación de un estudiante. ¿Te gustaría eso?