feat(courses): add faculty courses models and endpoints

dist/clients/student/openapi.yaml

@@ -932,6 +932,39 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/UpdateAssignmentRequest'
+  /courses/{courseId}/assignments/{assignmentId}/removal-request:
+    post:
+      operationId: Courses_requestAssignmentRemoval
+      summary: Request assignment removal | Richiedi rimozione elaborato
+      description: Lo studente richiede al docente la rimozione del proprio elaborato.
+      parameters:
+        - name: courseId
+          in: path
+          required: true
+          schema:
+            type: integer
+        - name: assignmentId
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '204':
+          description: 'There is no content to send for this request, but the headers may be useful. '
+        '400':
+          description: The server could not understand the request due to invalid syntax.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      tags:
+        - Courses
   /courses/{courseId}/files:
     get:
       operationId: Courses_getCourseFiles
@@ -1204,6 +1237,7 @@ paths:
                     publishedAt: '2021-09-22T14:00:00Z'
                     expiresAt: null
                     content: "<p>Dear students,</p>\r\r<p>welcome to the 2021 edition of the Human Computer Interaction course (<strong>HCI</strong>, for short)!</p>\r\r<p>Some useful information to get started...</p>\r\r<p>The <strong>first class</strong> will be on Tuesday, September 28, in Room 7T, from 13:00 to 14:30.<br />\rDon&#39;t forget to <em>book</em> a spot in the room, starting from tomorrow, on the Portale della Didattica: the rooms given to this course are currently bigger than the number of enrolled students, so there should be space for everybody!</p>\r\r<p>All teaching <strong>material</strong>, information, and course schedule will be posted on the page: <a href=\"http://bit.ly/polito-hci\">http://bit.ly/polito-hci</a> (we will <u>not</u>&nbsp;use the Portale della Didattica).</p>\r\r<p>All messages and communications with the teachers, and among students, will be on <strong>Slack</strong>. We will <u>completely</u>&nbsp;avoid email communications.<br />\rPlease, join the <em>HCI Slack workspace</em> at the address:<br />\r&nbsp; <a href=\"https://join.slack.com/t/polito-hci-2021/signup\">https://join.slack.com/t/polito-hci-2021/signup</a><br />\rPlease note: to have access to the workspace, you must use your<em> @studenti.polito.it </em>email address. You are free to choose your nickname as you prefer.&nbsp;</p>\r\r<p>Finally, all lectures &mdash; not labs &mdash; will be <strong>video-recorded</strong> and made available both on YouTube and on the Portale della Didattica. The YouTube playlist is:<br />\r&nbsp; <a href=\"https://www.youtube.com/playlist?list=PLs7DWGc_wmwT-1N2vbRkLWrM6LIker9A-\">https://www.youtube.com/playlist?list=PLs7DWGc_wmwT-1N2vbRkLWrM6LIker9A-</a></p>\r\r<p>See you on Tuesday!</p>\r\r<p>Thanks,</p>\r\r<p>Luigi and Fulvio</p>\r"
+                    status: visible
         '400':
           description: The server could not understand the request due to invalid syntax.
           content:
@@ -5031,13 +5065,20 @@ components:
               year: '2021'
       allOf:
         - $ref: '#/components/schemas/CourseModule'
+    CourseNoticeStatus:
+      type: string
+      enum:
+        - visible
+        - draft
+        - expired
     CourseNotices:
       type: object
       required:
         - id
         - publishedAt
         - expiresAt
         - content
+        - status
       properties:
         id:
           type: integer
@@ -5053,6 +5094,10 @@ components:
         content:
           type: string
           example: <p>Conferma spostamento orario esame:</p><p><b>Ore 15</b></p>
+        status:
+          allOf:
+            - $ref: '#/components/schemas/CourseNoticeStatus'
+          example: visible
     CourseOverview:
       type: object
       required:

src/clients/faculty/main.tsp

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

src/common.tsp

@@ -85,6 +85,13 @@ alias NoContentResponse = {
   @statusCode statusCode: 204;
 };
 
+alias AcceptedResponse = {
+  @statusCode statusCode: 202;
+  @body body: {
+    message?: string;
+  };
+};
+
 alias RedirectResponse = {
   @statusCode statusCode: 302;
 };
@@ -94,6 +101,11 @@ alias BadRequest = {
   @body body: ErrorResponse;
 };
 
+alias NotAuthorized = {
+  @statusCode statusCode: 401;
+  @body body: ErrorResponse;
+};
+
 alias NotFound = {
   @statusCode statusCode: 404;
   @body body: ErrorResponse;

src/examples/common/courses.tsp

@@ -1259,6 +1259,7 @@ const _ex_getCourseNotices_resp = #{
           publishedAt: utcDateTime.fromISO("2021-09-22T14:00:00Z"),
           expiresAt: null,
           content: "<p>Dear students,</p>\r\r<p>welcome to the 2021 edition of the Human Computer Interaction course (<strong>HCI</strong>, for short)!</p>\r\r<p>Some useful information to get started...</p>\r\r<p>The <strong>first class</strong> will be on Tuesday, September 28, in Room 7T, from 13:00 to 14:30.<br />\rDon&#39;t forget to <em>book</em> a spot in the room, starting from tomorrow, on the Portale della Didattica: the rooms given to this course are currently bigger than the number of enrolled students, so there should be space for everybody!</p>\r\r<p>All teaching <strong>material</strong>, information, and course schedule will be posted on the page: <a href=\"http://bit.ly/polito-hci\">http://bit.ly/polito-hci</a> (we will <u>not</u>&nbsp;use the Portale della Didattica).</p>\r\r<p>All messages and communications with the teachers, and among students, will be on <strong>Slack</strong>. We will <u>completely</u>&nbsp;avoid email communications.<br />\rPlease, join the <em>HCI Slack workspace</em> at the address:<br />\r&nbsp; <a href=\"https://join.slack.com/t/polito-hci-2021/signup\">https://join.slack.com/t/polito-hci-2021/signup</a><br />\rPlease note: to have access to the workspace, you must use your<em> @studenti.polito.it </em>email address. You are free to choose your nickname as you prefer.&nbsp;</p>\r\r<p>Finally, all lectures &mdash; not labs &mdash; will be <strong>video-recorded</strong> and made available both on YouTube and on the Portale della Didattica. The YouTube playlist is:<br />\r&nbsp; <a href=\"https://www.youtube.com/playlist?list=PLs7DWGc_wmwT-1N2vbRkLWrM6LIker9A-\">https://www.youtube.com/playlist?list=PLs7DWGc_wmwT-1N2vbRkLWrM6LIker9A-</a></p>\r\r<p>See you on Tuesday!</p>\r\r<p>Thanks,</p>\r\r<p>Luigi and Fulvio</p>\r",
+          status: CourseNoticeStatus.visible,
         }
       ],
     },

src/examples/faculty/courses.tsp

@@ -0,0 +1,273 @@
+namespace PolitoAPI;
+
+const _ex_publishCourseNotice_req = #{
+  parameters: #{
+    courseId: 251007,
+    isDraft: false,
+    body: #{
+      content: "<p>Lezione di domani spostata in aula 7T.</p>",
+      publishedDate: utcDateTime.fromISO("2025-10-14T09:00:00Z"),
+      expiresAt: utcDateTime.fromISO("2025-10-20T23:59:59Z"),
+      isAlwaysVisible: true,
+    },
+  },
+  returnType: #{ statusCode: 204 },
+};
+
+const _ex_updateCourseNotice_resp = #{
+  parameters: #{
+    courseId: 251007,
+    noticeId: 360724,
+    body: #{
+      content: "<p>Aggiornamento: lezione spostata in aula 10T.</p>",
+      publishedDate: utcDateTime.fromISO("2025-10-14T09:00:00Z"),
+      expiresAt: utcDateTime.fromISO("2025-10-22T23:59:59Z"),
+      isAlwaysVisible: false,
+    },
+  },
+  returnType: #{ statusCode: 204 },
+};
+
+const _ex_createCourseFolder_resp = #{
+  parameters: #{
+    courseId: 251007,
+    body: #{ name: "Laboratori", parentId: null },
+  },
+  returnType: #{ statusCode: 204 },
+};
+
+const _ex_updateCourseFolder_resp = #{
+  parameters: #{
+    courseId: 251007,
+    folderId: "33352562",
+    body: #{ name: "Laboratori 2024" },
+  },
+  returnType: #{ statusCode: 204 },
+};
+
+const _ex_updateCourseFile_resp = #{
+  parameters: #{
+    courseId: 251007,
+    fileId: "2",
+    body: #{ name: "Lecture1_rev.pdf", parentId: "33352562" },
+  },
+  returnType: #{ statusCode: 204 },
+};
+
+const _ex_moveCourseItems_resp = #{
+  parameters: #{
+    courseId: 251007,
+    body: #{ itemIds: #["2", "33352562"], destinationFolderId: "44463673" },
+  },
+  returnType: #{ statusCode: 204 },
+};
+
+const _ex_deleteCourseNotice_resp = #{
+  parameters: #{ courseId: 251007, noticeId: 360724 },
+  returnType: #{ statusCode: 204 },
+};
+
+const _ex_listFacultyCourseStudents_resp = #{
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #[
+        #{
+          id: "s123456",
+          firstName: "Mario",
+          lastName: "Rossi",
+          username: "s123456",
+          email: "s123456@studenti.polito.it",
+          picture: #{ url: "https://didattica.polito.it/photos/s123456.jpg" },
+        },
+        #{
+          id: "s234567",
+          firstName: "Luigi",
+          lastName: "Verdi",
+          username: "s234567",
+          email: "s234567@studenti.polito.it",
+          picture: #{ url: "https://didattica.polito.it/photos/s234567.jpg" },
+        }
+      ],
+    },
+  },
+};
+
+const _ex_searchEnrollableStudents_resp = #{
+  parameters: #{ courseId: 251007, search: "Federica" },
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #[
+        #{
+          id: "s123456",
+          firstName: "Federica",
+          lastName: "Bianchi",
+          username: "s123456",
+          email: "s123456@studenti.polito.it",
+          picture: #{ url: "https://didattica.polito.it/photos/s123456.jpg" },
+        },
+        #{
+          id: "s123457",
+          firstName: "Federica",
+          lastName: "Rossi",
+          username: "s123457",
+          email: "s123457@studenti.polito.it",
+          picture: #{ url: "https://didattica.polito.it/photos/s123457.jpg" },
+        },
+        #{
+          id: "s123458",
+          firstName: "Federica",
+          lastName: "Verdi",
+          username: "s123458",
+          email: "s123458@studenti.polito.it",
+          picture: #{ url: "https://didattica.polito.it/photos/s123458.jpg" },
+        }
+      ],
+    },
+  },
+};
+
+const _ex_enrollStudents_resp = #{
+  parameters: #{
+    courseId: 251007,
+    body: #{ studentIds: #["s123456", "s123458"] },
+  },
+  returnType: #{ statusCode: 204 },
+};
+
+const _ex_sendStudentsMessage_resp = #{
+  parameters: #{
+    courseId: 251007,
+    body: #{
+      studentIds: #["s123456", "s123457", "s123458"],
+      channel: MessageChannel.email,
+      title: "Lezione di recupero",
+      message: "Si avvisano gli studenti che la lezione di recupero si terrà venerdì alle 14:00 in aula 7T.",
+    },
+  },
+  returnType: #{ statusCode: 202, body: #{ message: "Message accepted" } },
+};
+
+const _ex_getCourseStudentsStats_resp = #{
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #{
+        totalEnrolled: 204,
+        withAttendanceIssues: 10,
+        tookExam: 0,
+        withExamDebts: 42,
+        eligibleForExam: 194,
+        firstTimeInAcademicYear: 152,
+      },
+    },
+  },
+};
+
+const _ex_getFacultyCourseStudent_resp = #{
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #{
+        id: "s123456",
+        firstName: "Stefania",
+        lastName: "Sassi",
+        username: "s123456",
+        email: "s123456@studenti.polito.it",
+        picture: #{ url: "https://didattica.polito.it/photos/s123456.jpg" },
+        course: #{ shortcode: "02JSKPD", cfu: 6 },
+        degreeCode: "CINZT3",
+        degreeName: "COMPUTER ENGINEERING",
+        examResult: #{ date: plainDate.fromISO("2025-02-23"), grade: "30L" },
+        subscription: "2025/2026",
+        citizenship: "Italian",
+        hasSpecialNeeds: true,
+      },
+    },
+  },
+};
+
+const _ex_getCourseStudentSpecialNeeds_resp = #{
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #{
+        content: "<p>List of compensatory measures granted to Stefania Sassi</p><ul><li><b>Calculator</b> allowed</li><li><b>Readability criteria</b> (Arial, 12-point font, 1.5 line spacing, non-justified text, expanded spacing)</li><li><b>Cheat sheet for formulas</b> for written and oral exams</li><li><b>30% additional time for completing exams</b></li><li><b>Assessment of content vs. form</b></li></ul>",
+        moreDetailsUrl: "https://didattica.polito.it/special-needs/requests?courseId=251007",
+        handbook: #{
+          name: "Reporting procedure handbook",
+          url: "https://didattica.polito.it/docs/reporting-procedure-handbook.pdf",
+        },
+      },
+    },
+  },
+};
+
+const _ex_listFacultyCourseAssignments_resp = #{
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #[
+        #{
+          id: 947503,
+          filename: "PresentationGroup03.zip",
+          student: #{
+            id: "s348759",
+            firstName: "Giuliana",
+            lastName: "Annone",
+          },
+          status: FacultyAssignmentStatus.new,
+        },
+        #{
+          id: 947502,
+          filename: "PresentationGroup02.zip",
+          student: #{
+            id: "s345658",
+            firstName: "Lorenzo",
+            lastName: "Ciovenco",
+          },
+          status: FacultyAssignmentStatus.seen,
+        },
+        #{
+          id: 947501,
+          filename: "PresentationGroup01.zip",
+          student: #{ id: "s345600", firstName: "Marco", lastName: "Bruno" },
+          status: FacultyAssignmentStatus.removalRequested,
+        }
+      ],
+    },
+  },
+};
+
+const _ex_getFacultyCourseAssignment_resp = #{
+  parameters: #{ courseId: 251007, assignmentId: 947503 },
+  returnType: #{
+    statusCode: 200,
+    body: #{
+      data: #{
+        id: 947503,
+        description: "A presentation on advanced robotics and automation. Group 03.",
+        mimeType: "application/x-zip-compressed",
+        filename: "PresentationGroup03.zip",
+        uploadedAt: utcDateTime.fromISO("2025-11-17T14:00:00Z"),
+        deletedAt: null,
+        url: "https://file.didattica.polito.it/down/ELABORATI_PRE/1003948/S348759/6791f0016c78599138828211522fa84d/62cebc94",
+        sizeInKiloBytes: 305,
+        student: #{ id: "s348759", firstName: "Giuliana", lastName: "Annone" },
+        status: FacultyAssignmentStatus.new,
+      },
+    },
+  },
+};
+
+const _ex_answerCourseAssignment_resp = #{
+  parameters: #{
+    courseId: 251007,
+    assignmentId: 947503,
+    body: #{
+      message: "Dear student, I cannot open the file you uploaded. Please try again to upload the folder in another format. Thank you!",
+    },
+  },
+  returnType: #{ statusCode: 202, body: #{ message: "Answer accepted" } },
+};