feat: add faculty exams models and endpoints

dist/clients/student/openapi.yaml

@@ -5642,19 +5642,9 @@ components:
     Exam:
       type: object
       required:
-        - id
-        - courseId
-        - courseShortcode
-        - courseName
         - teacherId
-        - type
         - status
         - bookingStartsAt
-        - bookingEndsAt
-        - examStartsAt
-        - examEndsAt
-        - bookedCount
-        - availableCount
         - question
         - feedback
         - isReschedulable
@@ -5663,51 +5653,18 @@ components:
         - requestReason
         - requestDetails
       properties:
-        id:
-          type: integer
-        courseId:
-          type: number
-        courseShortcode:
-          type: string
-        courseName:
-          type: string
         teacherId:
           type: integer
-        type:
-          type: string
         places:
           type: array
           items:
             $ref: '#/components/schemas/PlaceRef'
         status:
-          type: string
-          enum:
-            - available
-            - booked
-            - requestable
-            - requested
-            - requestAccepted
-            - requestRejected
-            - unavailable
+          $ref: '#/components/schemas/ExamStatus'
         bookingStartsAt:
           type: string
           format: date-time
           nullable: true
-        bookingEndsAt:
-          type: string
-          format: date-time
-        examStartsAt:
-          type: string
-          format: date-time
-          nullable: true
-        examEndsAt:
-          type: string
-          format: date-time
-          nullable: true
-        bookedCount:
-          type: integer
-        availableCount:
-          type: integer
         question:
           type: object
           properties:
@@ -5742,6 +5699,51 @@ components:
         requestDetails:
           type: string
           nullable: true
+      allOf:
+        - $ref: '#/components/schemas/ExamBase'
+    ExamBase:
+      type: object
+      required:
+        - id
+        - courseId
+        - courseShortcode
+        - courseName
+        - type
+        - bookingEndsAt
+        - examStartsAt
+        - examEndsAt
+        - bookedCount
+        - availableCount
+      properties:
+        id:
+          type: integer
+        courseId:
+          type: number
+        courseShortcode:
+          type: string
+        courseName:
+          type: string
+        type:
+          type: string
+        places:
+          type: array
+          items:
+            $ref: '#/components/schemas/PlaceRef'
+        bookingEndsAt:
+          type: string
+          format: date-time
+        examStartsAt:
+          type: string
+          format: date-time
+          nullable: true
+        examEndsAt:
+          type: string
+          format: date-time
+          nullable: true
+        bookedCount:
+          type: integer
+        availableCount:
+          type: integer
     ExamGrade:
       type: object
       required:
@@ -5787,6 +5789,16 @@ components:
           type: boolean
           description: Defines whether the credits from the exam count toward the total required for graduation
           example: true
+    ExamStatus:
+      type: string
+      enum:
+        - available
+        - booked
+        - requestable
+        - requested
+        - requestAccepted
+        - requestRejected
+        - unavailable
     FcmRegistrationRequest:
       type: object
       properties:

src/clients/faculty/main.tsp

@@ -14,6 +14,7 @@ import "../../routes/common/people.tsp";
 import "../../routes/common/places.tsp";
 
 // Faculty routes
+import "../../routes/faculty/exams.tsp";
 
 import "./version.tsp";
 

src/common.tsp

@@ -85,6 +85,11 @@ alias NoContentResponse = {
   @statusCode statusCode: 204;
 };
 
+alias AcceptedResponse<T = null> = {
+  @statusCode statusCode: 202;
+  @body body: T;
+};
+
 alias RedirectResponse = {
   @statusCode statusCode: 302;
 };
@@ -99,6 +104,11 @@ alias NotFound = {
   @body body: ErrorResponse;
 };
 
+alias NotAuthorized = {
+  @statusCode statusCode: 401;
+  @body body: ErrorResponse;
+};
+
 alias ServerError = {
   @statusCode statusCode: 500;
   @body body: ErrorResponse;

src/examples/faculty/exams.tsp

@@ -0,0 +1,123 @@
+import "@typespec/http";
+
+using Http;
+
+namespace PolitoAPI;
+
+// List exams example
+const _ex_getExams_resp = #{
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #[
+        #{
+          id: 888122,
+          courseId: 262147,
+          courseShortcode: "02JSKOV",
+          courseName: "Human Computer Interaction",
+          type: "Esami scritti a risposta aperta o chiusa tramite PC",
+          places: #[
+            #{
+              buildingId: "TO_CIT22",
+              floorId: "XPTE",
+              name: "Aula 1P",
+              roomId: "30",
+              siteId: "TO_CIT",
+            },
+          ],
+          bookingEndsAt: utcDateTime.fromISO("2026-08-31T14:00:00Z"),
+          examStartsAt: utcDateTime.fromISO("2026-09-02T14:00:00Z"),
+          examEndsAt: utcDateTime.fromISO("2026-09-02T17:00:00Z"),
+          bookedCount: 42,
+          availableCount: 8,
+        },
+      ],
+    },
+  },
+};
+
+// List students in exam example (with attendance + extra time info)
+const _ex_listStudentsInExam_resp = #{
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #[
+        #{
+          username: "290683",
+          name: "Mario",
+          surname: "Rossi",
+          needsExtraTime: true,
+          extraTimeMinutes: 30,
+          isPresent: false,
+        },
+        #{
+          username: "291045",
+          name: "Laura",
+          surname: "Bianchi",
+          needsExtraTime: false,
+          extraTimeMinutes: null,
+          isPresent: false,
+        },
+      ],
+    },
+  },
+};
+
+// Check exam attendance example
+const _ex_checkAttendance_resp = #{
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #[
+        #{
+          username: "290683",
+          name: "Mario",
+          surname: "Rossi",
+          needsExtraTime: true,
+          extraTimeMinutes: 30,
+          isPresent: true,
+        },
+        #{
+          username: "291045",
+          name: "Laura",
+          surname: "Bianchi",
+          needsExtraTime: false,
+          extraTimeMinutes: null,
+          isPresent: true,
+        },
+      ],
+    },
+  },
+};
+
+// Notify exam subscribers example
+const _ex_notifyExamSubscribers_resp = #{
+  returnType: #{
+    statusCode: 202,
+    body: #{
+      data: #{
+        status: "accepted",
+        trackingId: "track-abc-123",
+      },
+    },
+  },
+};
+
+// Add student to exam example (201 - created)
+const _ex_addStudentToExam_resp = #{
+  returnType: #{
+    statusCode: 201,
+    body: #{
+      data: #{
+        username: "292145",
+        name: "Anna",
+        surname: "Ferrari",
+      },
+    },
+  },
+};
+
+// Enroll / check student enrollment example (204 - no content)
+const _ex_enrollStudentToExam_resp = #{
+  returnType: #{ statusCode: 204 },
+};

src/routes/common/exams.tsp

@@ -0,0 +1,22 @@
+import "@typespec/http";
+import "@typespec/openapi3";
+
+import "../../common.tsp";
+
+using Http;
+
+namespace PolitoAPI;
+
+model ExamBase {
+  id: integer;
+  courseId: numeric;
+  courseShortcode: string;
+  courseName: string;
+  type: string;
+  places?: PlaceRef[];
+  bookingEndsAt: utcDateTime;
+  examStartsAt: utcDateTime | null;
+  examEndsAt: utcDateTime | null;
+  bookedCount: integer;
+  availableCount: integer;
+}