feat(quizzes): module quiz history, archive endpoint, and quiz analytics

src/modules/courses/admin-course.routes.ts

@@ -10,6 +10,7 @@ import {
   adminUpdateQuizSchema,
   authoredQuestionSchema,
   authoredQuizSchema,
+  archiveModuleQuizSchema,
 } from "../quizzes/quiz.types.js";
 import {
   createCourseSchema,
@@ -811,6 +812,66 @@ export async function adminCourseRoutes(app: FastifyInstance): Promise<void> {
     (request, reply) => quizController.deleteModuleQuiz(request, reply),
   );
 
+  app.post<{
+    Params: { id: string; moduleId: string; quizId: string };
+    Body: import("../quizzes/quiz.types.js").ArchiveModuleQuizBody;
+  }>(
+    "/:id/modules/:moduleId/quizzes/:quizId/archive",
+    {
+      preHandler: [
+        validate({
+          params: adminQuizParamsSchema,
+          body: archiveModuleQuizSchema,
+        }),
+      ],
+      schema: {
+        description:
+          "Archive a quiz: hides it from user-facing quiz lists while preserving the quiz and its submissions. Send { \"archived\": false } to unarchive. A thin wrapper over the same atomic, audit-logged write POST .../quizzes/:quizId performs with an `archived` field — this gives the action its own discoverable URL (admin only, #416)",
+        tags: ["admin", "courses", "quizzes"],
+        security: [{ bearerAuth: [] }],
+        params: {
+          type: "object",
+          required: ["id", "moduleId", "quizId"],
+          properties: {
+            id: { type: "string", format: "uuid" },
+            moduleId: { type: "string", minLength: 1, maxLength: 100 },
+            quizId: { type: "string", format: "uuid" },
+          },
+        },
+        body: {
+          type: "object",
+          properties: {
+            archived: { type: "boolean", default: true },
+          },
+        },
+      } as FastifySchema,
+    },
+    (request, reply) => quizController.archiveModuleQuiz(request, reply),
+  );
+
+  app.get<{ Params: { id: string; moduleId: string; quizId: string } }>(
+    "/:id/modules/:moduleId/quizzes/:quizId/analytics",
+    {
+      preHandler: [validate({ params: adminQuizParamsSchema })],
+      schema: {
+        description:
+          "Detailed analytics for one quiz: question-by-question correct rate and most common wrong answer, score distribution, and attempt patterns (current vs superseded retries). Per-question timing is not tracked at the data layer today and is always reported as unavailable rather than fabricated (admin only, cached 5 minutes, #417)",
+        tags: ["admin", "courses", "quizzes"],
+        security: [{ bearerAuth: [] }],
+        params: {
+          type: "object",
+          required: ["id", "moduleId", "quizId"],
+          properties: {
+            id: { type: "string", format: "uuid" },
+            moduleId: { type: "string", minLength: 1, maxLength: 100 },
+            quizId: { type: "string", format: "uuid" },
+          },
+        },
+      } as FastifySchema,
+    },
+    (request, reply) => quizController.getQuizAnalytics(request, reply),
+  );
+
   app.delete<{ Params: { id: string; moduleId: string; contentId: string } }>(
     "/:id/modules/:moduleId/content/:contentId",
     {

src/modules/courses/course.routes.ts

@@ -503,4 +503,30 @@ export async function courseRoutes(app: FastifyInstance): Promise<void> {
     },
     (request, reply) => waitlistController.getStatus(request, reply)
   );
+
+  app.get<{ Params: { id: string; moduleId: string } }>(
+    "/:id/modules/:moduleId/quiz-history",
+    {
+      preHandler: [
+        authGuard,
+        adminGuard,
+        validate({ params: moduleParamsSchema }),
+      ],
+      schema: {
+        description:
+          "Aggregate quiz stats for every quiz in a course module across all users: average score, pass rate, total attempts, score distribution (admin only, cached 5 minutes, #415)",
+        tags: ["courses", "admin", "quizzes"],
+        security: [{ bearerAuth: [] }],
+        params: {
+          type: "object",
+          required: ["id", "moduleId"],
+          properties: {
+            id: { type: "string", format: "uuid" },
+            moduleId: { type: "string", minLength: 1, maxLength: 100 },
+          },
+        },
+      } as FastifySchema,
+    },
+    (request, reply) => quizController.getModuleQuizHistory(request, reply)
+  );
 }

src/modules/quizzes/quiz.controller.ts

@@ -14,6 +14,7 @@ import type {
   AdminQuizUpdateBody,
   AuthoredQuizBody,
   AuthoredQuestion,
+  ArchiveModuleQuizBody,
 } from "./quiz.types.js";
 
 export class QuizController {
@@ -244,6 +245,22 @@ export class QuizController {
 
   /**
    * POST /api/v1/admin/courses/:id/modules/:moduleId/quizzes/:quizId/archive
+   * Archive (or unarchive) a quiz via its own endpoint (admin only, #416).
+   */
+  async archiveModuleQuiz(
+    request: FastifyRequest<{
+      Params: AdminQuizParams;
+      Body: ArchiveModuleQuizBody;
+    }>,
+    reply: FastifyReply
+  ): Promise<void> {
+    const { id, moduleId, quizId } = request.params;
+    const quiz = await quizService.archiveModuleQuiz(
+      id,
+      moduleId,
+      quizId,
+      request.body.archived,
+    );
    * Archive a quiz without deleting it (admin only, #416). Thin wrapper
    * around the same archive path updateModuleQuizDetails already supports.
    */
@@ -261,6 +278,7 @@ export class QuizController {
 
   /**
    * GET /api/v1/courses/:id/modules/:moduleId/quiz-history
+   * Aggregate quiz stats for every quiz in a course module (admin only, #415).
    * Aggregate quiz performance across a module's quizzes (admin only, #415).
    */
   async getModuleQuizHistory(
@@ -275,6 +293,7 @@ export class QuizController {
 
   /**
    * GET /api/v1/admin/courses/:id/modules/:moduleId/quizzes/:quizId/analytics
+   * Detailed question-by-question analytics for one quiz (admin only, #417).
    * Question-by-question analytics for a single quiz (admin only, #417).
    */
   async getQuizAnalytics(