feat: filter student grades by academic year level

doc/api.yml

@@ -442,11 +442,7 @@ paths:
       summary: Get student grades.
       operationId: getStudentGrades
       parameters:
-        - name: student_id
-          in: path
-          required: true
-          schema:
-            type: string
+        - $ref: '#/components/parameters/PathStudentId'
         - name: page
           in: query
           schema:
@@ -458,6 +454,7 @@ paths:
           description: Set value to 15 by default if null is provided
           schema:
             $ref: '#/components/schemas/PageSize'
+        - $ref: '#/components/parameters/AcademicYearLevel'
       responses:
         '200':
           description: List of a student's grades, showing the exam and the course of these grades.
@@ -5913,6 +5910,17 @@ components:
       description: Filter by student first name or last name
       schema:
         type: string
+    AcademicYearLevel:
+      name: academic_year_level
+      in: query
+      required: false
+      description: Filter by group academic year level
+      schema:
+        type: string
+        enum:
+          - L1
+          - L2
+          - L3
     PathExamId:
       name: exams_id
       in: path

src/main/java/school/hei/haapi/model/Group.java

@@ -2,6 +2,9 @@
 
 import static jakarta.persistence.FetchType.LAZY;
 import static jakarta.persistence.GenerationType.IDENTITY;
+import static school.hei.haapi.model.fee.StudentGrade.L1;
+import static school.hei.haapi.model.fee.StudentGrade.L2;
+import static school.hei.haapi.model.fee.StudentGrade.L3;
 
 import jakarta.persistence.Entity;
 import jakarta.persistence.GeneratedValue;
@@ -12,6 +15,8 @@
 import jakarta.persistence.Table;
 import java.io.Serializable;
 import java.time.Instant;
+import java.time.LocalDate;
+import java.time.Period;
 import java.util.List;
 import java.util.Objects;
 import lombok.AllArgsConstructor;
@@ -22,6 +27,7 @@
 import lombok.ToString;
 import org.hibernate.Hibernate;
 import org.hibernate.annotations.CreationTimestamp;
+import school.hei.haapi.model.fee.StudentGrade;
 
 @Entity
 @Table(name = "\"group\"")
@@ -86,4 +92,19 @@ public boolean equals(Object o) {
   public int hashCode() {
     return getClass().hashCode();
   }
+
+  public StudentGrade getStudentGradeAtInstant(LocalDate localDate) {
+    int promotionYearAge =
+        Period.between(LocalDate.from(this.getPromotion().getStartDatetime()), localDate)
+            .getYears();
+    return switch (promotionYearAge) {
+      case 0 -> L1;
+      case 1 -> L2;
+      case 2 -> L3;
+      default ->
+          throw new IllegalArgumentException(
+              "Invalid promotion at instant '%s': the group with ID '%s' cannot have a valid promotion for year %d at this time"
+                  .formatted(localDate, this.id, promotionYearAge));
+    };
+  }
 }

src/test/java/school/hei/haapi/integration/GradeIT.java

@@ -77,7 +77,7 @@ void manager_read_ok() throws ApiException {
     TeachingApi api = new TeachingApi(manager1Client);
 
     List<String> actualAwardedCourseExamGradesId =
-        api.getStudentGrades(STUDENT1_ID, 1, 10).stream()
+        api.getStudentGrades(STUDENT1_ID, 1, 10, null).stream()
             .map(AwardedCourseExam::getId)
             .collect(toUnmodifiableList());
 
@@ -91,7 +91,7 @@ void teacher_read_ok() throws ApiException {
     ApiClient teacher1Client = anApiClient(TEACHER1_TOKEN);
     TeachingApi api = new TeachingApi(teacher1Client);
 
-    List<AwardedCourseExam> actual = api.getStudentGrades(STUDENT1_ID, 1, 10);
+    List<AwardedCourseExam> actual = api.getStudentGrades(STUDENT1_ID, 1, 10, null);
 
     assertTrue(actual.contains(awardedCourseExam1()));
     assertTrue(actual.contains(awardedCourseExam2()));
@@ -104,7 +104,7 @@ void student_read_his_grade_ok() throws ApiException {
     TeachingApi api = new TeachingApi(student1Client);
 
     List<String> actualIds =
-        api.getStudentGrades(STUDENT1_ID, 1, 10).stream()
+        api.getStudentGrades(STUDENT1_ID, 1, 10, null).stream()
             .map(AwardedCourseExam::getId)
             .collect(toUnmodifiableList());
 
@@ -117,7 +117,7 @@ void student_read_his_grade_ok() throws ApiException {
   void student_read_other_grade_ko() {
     ApiClient student1Client = anApiClient(STUDENT1_TOKEN);
     TeachingApi api = new TeachingApi(student1Client);
-    assertThrowsForbiddenException(() -> api.getStudentGrades(STUDENT2_ID, 1, 10));
+    assertThrowsForbiddenException(() -> api.getStudentGrades(STUDENT2_ID, 1, 10, null));
     assertThrowsForbiddenException(() -> api.getParticipantGrade(GROUP1_ID, EXAM1_ID));
   }