Development: Add interviewee assessment page (#1700)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Aniruddh Zaveri <92953467+az108@users.noreply.github.com>

Author: 3 people

openapi/openapi.yaml

@@ -1123,6 +1123,49 @@ paths:
               schema:
                 type: array
                 items: {$ref: '#/components/schemas/IntervieweeDTO'}
+  /api/interviews/processes/{processId}/interviewees/{intervieweeId}:
+    get:
+      tags: [interview-resource]
+      operationId: getIntervieweeDetails
+      parameters:
+      - name: processId
+        in: path
+        required: true
+        schema: {type: string, format: uuid}
+      - name: intervieweeId
+        in: path
+        required: true
+        schema: {type: string, format: uuid}
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/IntervieweeDetailDTO'}
+  /api/interviews/processes/{processId}/interviewees/{intervieweeId}/assessment:
+    put:
+      tags: [interview-resource]
+      operationId: updateAssessment
+      parameters:
+      - name: processId
+        in: path
+        required: true
+        schema: {type: string, format: uuid}
+      - name: intervieweeId
+        in: path
+        required: true
+        schema: {type: string, format: uuid}
+      requestBody:
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/UpdateAssessmentDTO'}
+        required: true
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/IntervieweeDetailDTO'}
   /api/interviews/processes/{processId}/send-invitations:
     post:
       tags: [interview-resource]
@@ -2431,6 +2474,21 @@ components:
           type: string
           enum: [UNCONTACTED, INVITED, SCHEDULED, COMPLETED]
         user: {$ref: '#/components/schemas/IntervieweeUserDTO'}
+    IntervieweeDetailDTO:
+      type: object
+      properties:
+        application: {$ref: '#/components/schemas/ApplicationDetailDTO'}
+        applicationId: {type: string, format: uuid}
+        assessmentNotes: {type: string}
+        documents: {$ref: '#/components/schemas/ApplicationDocumentIdsDTO'}
+        id: {type: string, format: uuid}
+        lastInvited: {type: string, format: date-time}
+        rating: {type: integer, format: int32}
+        scheduledSlot: {$ref: '#/components/schemas/InterviewSlotDTO'}
+        state:
+          type: string
+          enum: [UNCONTACTED, INVITED, SCHEDULED, COMPLETED]
+        user: {$ref: '#/components/schemas/IntervieweeUserDTO'}
     IntervieweeUserDTO:
       type: object
       properties:
@@ -2924,6 +2982,12 @@ components:
         projects: {type: string}
         specialSkills: {type: string}
       required: [applicant, applicationId, applicationState]
+    UpdateAssessmentDTO:
+      type: object
+      properties:
+        clearRating: {type: boolean}
+        notes: {type: string}
+        rating: {type: integer, format: int32, maximum: 2, minimum: -2}
     UpdatePasswordDTO:
       type: object
       properties:

package-lock.json

@@ -4,6 +4,7 @@
 import de.tum.cit.aet.application.domain.dto.ApplicationForApplicantDTO;
 import de.tum.cit.aet.core.repository.TumApplyJpaRepository;
 import java.util.List;
+import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
 import org.springframework.data.jpa.repository.Modifying;
@@ -231,4 +232,20 @@ WHERE a.job IN (
         """
     )
     List<Object[]> countApplicationsByJobAndStateForInterviewProcesses(@Param("professorId") UUID professorId);
+
+    /**
+     * Finds an application by ID with applicant and user details fetched.
+     *
+     * @param id the ID of the application
+     * @return the application with details, or empty if not found
+     */
+    @Query(
+        """
+        SELECT a FROM Application a
+        LEFT JOIN FETCH a.applicant ap
+        LEFT JOIN FETCH ap.user
+        WHERE a.applicationId = :id
+        """
+    )
+    Optional<Application> findWithDetailsById(@Param("id") UUID id);
 }

src/main/java/de/tum/cit/aet/application/repository/ApplicationRepository.java

@@ -2,6 +2,7 @@
 
 import de.tum.cit.aet.application.domain.Application;
 import de.tum.cit.aet.core.domain.AbstractAuditingEntity;
+import de.tum.cit.aet.interview.domain.enumeration.AssessmentRating;
 import jakarta.persistence.*;
 import java.time.Instant;
 import java.util.ArrayList;
@@ -12,7 +13,8 @@
 
 /**
  * Entity representing an applicant who has been added to an interview process.
- * Links an Application to an InterviewProcess and tracks interview related state.
+ * Links an Application to an InterviewProcess and tracks interview related
+ * state.
  */
 @Entity
 @Table(
@@ -50,6 +52,22 @@ public class Interviewee extends AbstractAuditingEntity {
     @Column(name = "version")
     private Long version;
 
+    /**
+     * Assessment rating (POOR to EXCELLENT).
+     * Maps to Likert scale integers -2 to 2 in the database.
+     * Null if not yet assessed.
+     */
+    @Column(name = "rating")
+    @Convert(converter = AssessmentRatingConverter.class)
+    private AssessmentRating rating;
+
+    /**
+     * Professor's evaluation notes for this interviewee.
+     * Null if no notes have been entered.
+     */
+    @Column(name = "assessment_notes", columnDefinition = "TEXT")
+    private String assessmentNotes;
+
     /**
      * Gets the currently scheduled interview slot.
      * Currently only one slot per interviewee is supported.
@@ -68,4 +86,18 @@ public InterviewSlot getScheduledSlot() {
     public boolean hasSlot() {
         return !slots.isEmpty();
     }
+
+    @Converter
+    public static class AssessmentRatingConverter implements AttributeConverter<AssessmentRating, Integer> {
+
+        @Override
+        public Integer convertToDatabaseColumn(AssessmentRating attribute) {
+            return attribute == null ? null : attribute.getValue();
+        }
+
+        @Override
+        public AssessmentRating convertToEntityAttribute(Integer dbData) {
+            return AssessmentRating.fromValue(dbData);
+        }
+    }
 }

src/main/java/de/tum/cit/aet/interview/domain/Interviewee.java

@@ -0,0 +1,42 @@
+package de.tum.cit.aet.interview.domain.enumeration;
+
+import java.util.Arrays;
+
+/**
+ * Enumeration for Interviewee Assessment Rating.
+ * Maps Likert scale integer values (-2 to 2) to semantic names.
+ */
+public enum AssessmentRating {
+    POOR(-2),
+    FAIR(-1),
+    SATISFACTORY(0),
+    GOOD(1),
+    EXCELLENT(2);
+
+    private final int value;
+
+    AssessmentRating(int value) {
+        this.value = value;
+    }
+
+    public int getValue() {
+        return value;
+    }
+
+    /**
+     * Converts an integer value to the corresponding AssessmentRating.
+     *
+     * @param value the integer value (-2 to 2)
+     * @return the matching AssessmentRating, or null if value is null
+     * @throws IllegalArgumentException if the value is invalid
+     */
+    public static AssessmentRating fromValue(Integer value) {
+        if (value == null) {
+            return null;
+        }
+        return Arrays.stream(values())
+            .filter(r -> r.value == value)
+            .findFirst()
+            .orElseThrow(() -> new IllegalArgumentException("Invalid rating value: " + value));
+    }
+}

src/main/java/de/tum/cit/aet/interview/domain/enumeration/AssessmentRating.java

@@ -0,0 +1,25 @@
+package de.tum.cit.aet.interview.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import de.tum.cit.aet.application.domain.dto.ApplicationDetailDTO;
+import de.tum.cit.aet.application.domain.dto.ApplicationDocumentIdsDTO;
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * Detailed DTO for a single interviewee with full application context.
+ * Includes application details, documents, and assessment information.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public record IntervieweeDetailDTO(
+    UUID id,
+    UUID applicationId,
+    IntervieweeDTO.IntervieweeUserDTO user,
+    Instant lastInvited,
+    InterviewSlotDTO scheduledSlot,
+    IntervieweeState state,
+    Integer rating,
+    String assessmentNotes,
+    ApplicationDetailDTO application,
+    ApplicationDocumentIdsDTO documents
+) {}

src/main/java/de/tum/cit/aet/interview/dto/IntervieweeDetailDTO.java

@@ -0,0 +1,29 @@
+package de.tum.cit.aet.interview.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+
+/**
+ * DTO for updating interviewee assessment (rating and notes).
+ * At least one field must be provided.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public record UpdateAssessmentDTO(
+    @Min(value = -2, message = "Rating must be between -2 and 2")
+    @Max(value = 2, message = "Rating must be between -2 and 2")
+    Integer rating,
+
+    Boolean clearRating,
+
+    String notes
+) {
+    /**
+     * Checks if the DTO has at least one field set.
+     *
+     * @return true if either rating, clearRating, or notes is provided
+     */
+    public boolean hasContent() {
+        return rating != null || Boolean.TRUE.equals(clearRating) || notes != null;
+    }
+}

src/main/java/de/tum/cit/aet/interview/dto/UpdateAssessmentDTO.java

@@ -96,7 +96,28 @@ public interface IntervieweeRepository extends TumApplyJpaRepository<Interviewee
     List<Interviewee> findByInterviewProcessIdInWithSlots(@Param("processIds") List<UUID> processIds);
 
     /**
-     * Finds all uninvited interviewees for a given interview process.
+     * Finds a single interviewee by ID within a process.
+     *
+     * @param intervieweeId the ID of the interviewee
+     * @param processId     the ID of the interview process
+     * @return the interviewee or empty if not found
+     */
+    @Query(
+        """
+        SELECT DISTINCT i FROM Interviewee i
+        JOIN FETCH i.interviewProcess ip
+        JOIN FETCH ip.job j
+        LEFT JOIN FETCH i.application a
+        LEFT JOIN FETCH a.applicant ap
+        LEFT JOIN FETCH ap.user
+        LEFT JOIN FETCH i.slots
+        WHERE i.id = :intervieweeId
+        AND ip.id = :processId
+        """
+    )
+    Optional<Interviewee> findByIdAndProcessId(@Param("intervieweeId") UUID intervieweeId, @Param("processId") UUID processId);
+
+    /* Finds all uninvited interviewees for a given interview process.
      * Fetches application and user details to avoid N+1 issues when sending emails.
      *
      * @param processId the ID of the interview process