@studious-lms/server 1.25.0 → 1.27.0

package/src/services/module.ts

@@ -0,0 +1,683 @@
+/**
+ * Module service – Canvas-style modules ("pathways") for classes.
+ *
+ * Modules are ordered groups of content items (assignments, worksheets,
+ * files, announcements, discussions, external URLs, sub-headers) with
+ * completion requirements, prerequisites, unlock dates and optional
+ * sequential progression.
+ */
+import { TRPCError } from "@trpc/server";
+import {
+  CourseModuleItemType as ModuleItemType,
+  ModuleItemRequirementType,
+  ModuleItemProgressStatus,
+  Prisma,
+} from "@prisma/client";
+import { prisma } from "../lib/prisma.js";
+import { logger } from "../utils/logger.js";
+import {
+  findClassWithTeacher,
+  findModulesByClassId,
+  findModuleByClassAndId,
+  findModuleItemInClass,
+  findStudentProgressForClass,
+  upsertItemProgress,
+  moduleInclude,
+} from "../models/module.js";
+
+async function assertTeacher(userId: string, classId: string) {
+  const classData = await findClassWithTeacher(classId, userId);
+  if (!classData) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Class not found or you are not a teacher",
+    });
+  }
+  return classData;
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Module CRUD                                   */
+/* -------------------------------------------------------------------------- */
+
+export async function listModulesRecord(userId: string, classId: string) {
+  await assertTeacher(userId, classId);
+  return findModulesByClassId(classId);
+}
+
+export async function createModuleRecord(
+  userId: string,
+  input: { classId: string; title: string; unlockAt?: Date | null; requireSequential?: boolean }
+) {
+  await assertTeacher(userId, input.classId);
+  const last = await prisma.module.findFirst({
+    where: { classId: input.classId },
+    orderBy: { position: "desc" },
+    select: { position: true },
+  });
+  return prisma.module.create({
+    data: {
+      classId: input.classId,
+      title: input.title,
+      position: (last?.position ?? 0) + 1,
+      unlockAt: input.unlockAt ?? null,
+      requireSequential: input.requireSequential ?? false,
+    },
+    include: moduleInclude,
+  });
+}
+
+export async function updateModuleRecord(
+  userId: string,
+  input: {
+    id: string;
+    classId: string;
+    title?: string;
+    unlockAt?: Date | null;
+    requireSequential?: boolean;
+    published?: boolean;
+    prerequisiteIds?: string[];
+  }
+) {
+  await assertTeacher(userId, input.classId);
+  const module = await findModuleByClassAndId(input.id, input.classId);
+  if (!module) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Module not found" });
+  }
+
+  if (input.prerequisiteIds) {
+    const prereqs = await prisma.module.findMany({
+      where: { id: { in: input.prerequisiteIds }, classId: input.classId },
+      select: { id: true, position: true },
+    });
+    if (prereqs.length !== input.prerequisiteIds.length) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Prerequisite module not found in this class",
+      });
+    }
+    // Like Canvas, only earlier modules can be prerequisites (prevents cycles).
+    if (prereqs.some((p) => p.id === input.id || p.position >= module.position)) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Prerequisites must be modules positioned before this one",
+      });
+    }
+  }
+
+  return prisma.$transaction(async (tx) => {
+    if (input.prerequisiteIds) {
+      await tx.modulePrerequisite.deleteMany({ where: { moduleId: input.id } });
+      if (input.prerequisiteIds.length) {
+        await tx.modulePrerequisite.createMany({
+          data: input.prerequisiteIds.map((prerequisiteId) => ({
+            moduleId: input.id,
+            prerequisiteId,
+          })),
+        });
+      }
+    }
+    return tx.module.update({
+      where: { id: input.id },
+      data: {
+        ...(input.title !== undefined && { title: input.title }),
+        ...(input.unlockAt !== undefined && { unlockAt: input.unlockAt }),
+        ...(input.requireSequential !== undefined && {
+          requireSequential: input.requireSequential,
+        }),
+        ...(input.published !== undefined && { published: input.published }),
+      },
+      include: moduleInclude,
+    });
+  });
+}
+
+export async function deleteModuleRecord(
+  userId: string,
+  input: { id: string; classId: string }
+) {
+  await assertTeacher(userId, input.classId);
+  const module = await findModuleByClassAndId(input.id, input.classId);
+  if (!module) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Module not found" });
+  }
+  await prisma.module.delete({ where: { id: input.id } });
+  return { id: input.id };
+}
+
+export async function reorderModulesRecord(
+  userId: string,
+  input: { classId: string; orderedIds: string[] }
+) {
+  await assertTeacher(userId, input.classId);
+  const modules = await prisma.module.findMany({
+    where: { classId: input.classId },
+    select: { id: true },
+  });
+  const classIds = new Set(modules.map((m) => m.id));
+  if (
+    input.orderedIds.length !== classIds.size ||
+    input.orderedIds.some((id) => !classIds.has(id))
+  ) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "orderedIds must contain every module of the class exactly once",
+    });
+  }
+  await prisma.$transaction(
+    input.orderedIds.map((id, index) =>
+      prisma.module.update({ where: { id }, data: { position: index + 1 } })
+    )
+  );
+  return findModulesByClassId(input.classId);
+}
+
+/* -------------------------------------------------------------------------- */
+/*                             Module items                                   */
+/* -------------------------------------------------------------------------- */
+
+const CONTENT_TYPES: ModuleItemType[] = [
+  ModuleItemType.ASSIGNMENT,
+  ModuleItemType.WORKSHEET,
+  ModuleItemType.FILE,
+  ModuleItemType.ANNOUNCEMENT,
+  ModuleItemType.DISCUSSION,
+];
+
+const SUBMITTABLE_TYPES: ModuleItemType[] = [
+  ModuleItemType.ASSIGNMENT,
+  ModuleItemType.WORKSHEET,
+];
+
+async function validateItemInput(
+  classId: string,
+  input: {
+    itemType: ModuleItemType;
+    itemId?: string | null;
+    externalUrl?: string | null;
+    title?: string | null;
+    requirementType?: ModuleItemRequirementType | null;
+    requiredScore?: number | null;
+  }
+) {
+  const { itemType, itemId, externalUrl, title, requirementType } = input;
+
+  if (itemType === ModuleItemType.SUB_HEADER) {
+    if (!title) {
+      throw new TRPCError({ code: "BAD_REQUEST", message: "Sub-header requires a title" });
+    }
+    if (requirementType) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Sub-headers cannot have completion requirements",
+      });
+    }
+    return;
+  }
+
+  if (itemType === ModuleItemType.EXTERNAL_URL) {
+    if (!externalUrl || !title) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "External URL items require a URL and a title",
+      });
+    }
+  } else if (CONTENT_TYPES.includes(itemType)) {
+    if (!itemId) {
+      throw new TRPCError({ code: "BAD_REQUEST", message: "itemId is required" });
+    }
+    const exists =
+      itemType === ModuleItemType.ASSIGNMENT
+        ? await prisma.assignment.findFirst({ where: { id: itemId, classId } })
+        : itemType === ModuleItemType.WORKSHEET
+          ? await prisma.worksheet.findFirst({ where: { id: itemId, classId } })
+          : itemType === ModuleItemType.ANNOUNCEMENT
+            ? await prisma.announcement.findFirst({ where: { id: itemId, classId } })
+            : itemType === ModuleItemType.DISCUSSION
+              ? await prisma.discussion.findFirst({ where: { id: itemId, classId } })
+              : await prisma.file.findUnique({ where: { id: itemId } });
+    if (!exists) {
+      throw new TRPCError({
+        code: "NOT_FOUND",
+        message: "Referenced content not found in this class",
+      });
+    }
+  }
+
+  if (
+    (requirementType === ModuleItemRequirementType.SUBMIT ||
+      requirementType === ModuleItemRequirementType.SCORE_AT_LEAST) &&
+    !SUBMITTABLE_TYPES.includes(itemType)
+  ) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Submit/score requirements only apply to assignments and worksheets",
+    });
+  }
+  if (
+    requirementType === ModuleItemRequirementType.SCORE_AT_LEAST &&
+    (input.requiredScore == null || input.requiredScore < 0)
+  ) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "requiredScore is required for score requirements",
+    });
+  }
+}
+
+export async function createModuleItemRecord(
+  userId: string,
+  input: {
+    classId: string;
+    moduleId: string;
+    itemType: ModuleItemType;
+    itemId?: string;
+    externalUrl?: string;
+    title?: string;
+    indent?: number;
+    requirementType?: ModuleItemRequirementType;
+    requiredScore?: number;
+  }
+) {
+  await assertTeacher(userId, input.classId);
+  const module = await findModuleByClassAndId(input.moduleId, input.classId);
+  if (!module) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Module not found" });
+  }
+  await validateItemInput(input.classId, input);
+
+  const last = await prisma.courseModuleItem.findFirst({
+    where: { moduleId: input.moduleId },
+    orderBy: { position: "desc" },
+    select: { position: true },
+  });
+
+  return prisma.courseModuleItem.create({
+    data: {
+      moduleId: input.moduleId,
+      position: (last?.position ?? 0) + 1,
+      indent: input.indent ?? 0,
+      itemType: input.itemType,
+      itemId: input.itemId ?? null,
+      externalUrl: input.externalUrl ?? null,
+      title: input.title ?? null,
+      requirementType: input.requirementType ?? null,
+      requiredScore:
+        input.requirementType === ModuleItemRequirementType.SCORE_AT_LEAST
+          ? input.requiredScore
+          : null,
+    },
+  });
+}
+
+export async function updateModuleItemRecord(
+  userId: string,
+  input: {
+    classId: string;
+    id: string;
+    title?: string | null;
+    externalUrl?: string;
+    indent?: number;
+    requirementType?: ModuleItemRequirementType | null;
+    requiredScore?: number | null;
+  }
+) {
+  await assertTeacher(userId, input.classId);
+  const item = await findModuleItemInClass(input.id, input.classId);
+  if (!item) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Module item not found" });
+  }
+
+  const requirementType =
+    input.requirementType !== undefined ? input.requirementType : item.requirementType;
+  const requiredScore =
+    input.requiredScore !== undefined ? input.requiredScore : item.requiredScore;
+
+  await validateItemInput(input.classId, {
+    itemType: item.itemType,
+    itemId: item.itemId,
+    externalUrl: input.externalUrl !== undefined ? input.externalUrl : item.externalUrl,
+    title: input.title !== undefined ? input.title : item.title,
+    requirementType,
+    requiredScore,
+  });
+
+  return prisma.courseModuleItem.update({
+    where: { id: input.id },
+    data: {
+      ...(input.title !== undefined && { title: input.title }),
+      ...(input.externalUrl !== undefined && { externalUrl: input.externalUrl }),
+      ...(input.indent !== undefined && { indent: input.indent }),
+      ...(input.requirementType !== undefined && {
+        requirementType: input.requirementType,
+      }),
+      requiredScore:
+        requirementType === ModuleItemRequirementType.SCORE_AT_LEAST
+          ? requiredScore
+          : null,
+    },
+  });
+}
+
+export async function deleteModuleItemRecord(
+  userId: string,
+  input: { classId: string; id: string }
+) {
+  await assertTeacher(userId, input.classId);
+  const item = await findModuleItemInClass(input.id, input.classId);
+  if (!item) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Module item not found" });
+  }
+  await prisma.courseModuleItem.delete({ where: { id: input.id } });
+  return { id: input.id };
+}
+
+/**
+ * Reorder items, supporting drag-and-drop across modules. `items` is the full
+ * new ordering: for every affected module, its items in display order.
+ */
+export async function reorderModuleItemsRecord(
+  userId: string,
+  input: { classId: string; items: { id: string; moduleId: string }[] }
+) {
+  await assertTeacher(userId, input.classId);
+
+  const itemIds = input.items.map((i) => i.id);
+  const moduleIds = [...new Set(input.items.map((i) => i.moduleId))];
+
+  const [dbItems, dbModules] = await Promise.all([
+    prisma.courseModuleItem.findMany({
+      where: { id: { in: itemIds }, module: { classId: input.classId } },
+      select: { id: true },
+    }),
+    prisma.module.findMany({
+      where: { id: { in: moduleIds }, classId: input.classId },
+      select: { id: true },
+    }),
+  ]);
+  if (dbItems.length !== itemIds.length || dbModules.length !== moduleIds.length) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Item or module not found in this class",
+    });
+  }
+
+  const positionByModule = new Map<string, number>();
+  await prisma.$transaction(
+    input.items.map((item) => {
+      const next = (positionByModule.get(item.moduleId) ?? 0) + 1;
+      positionByModule.set(item.moduleId, next);
+      return prisma.courseModuleItem.update({
+        where: { id: item.id },
+        data: { moduleId: item.moduleId, position: next },
+      });
+    })
+  );
+  return findModulesByClassId(input.classId);
+}
+
+/* -------------------------------------------------------------------------- */
+/*                        Student state & progress                            */
+/* -------------------------------------------------------------------------- */
+
+type ModuleWithItems = Prisma.ModuleGetPayload<{
+  include: typeof moduleInclude;
+}>;
+
+function isModuleComplete(
+  module: ModuleWithItems,
+  completedItemIds: Set<string>
+) {
+  const required = module.items.filter((i) => i.requirementType);
+  return required.every((i) => completedItemIds.has(i.id));
+}
+
+/**
+ * Compute the full module state for a student: lock status, per-item
+ * completion/accessibility and per-module progress percentages.
+ */
+export async function getStudentModulesState(classId: string, studentId: string) {
+  const [modules, progress] = await Promise.all([
+    findModulesByClassId(classId, true),
+    findStudentProgressForClass(classId, studentId),
+  ]);
+
+  const completedItemIds = new Set(
+    progress
+      .filter((p) => p.status === ModuleItemProgressStatus.COMPLETE)
+      .map((p) => p.moduleItemId)
+  );
+
+  // Students open worksheets through the assignment they are attached to, so
+  // resolve each worksheet item to its containing assignment for navigation.
+  const worksheetIds = [
+    ...new Set(
+      modules
+        .flatMap((m) => m.items)
+        .filter((i) => i.itemType === ModuleItemType.WORKSHEET && i.itemId)
+        .map((i) => i.itemId as string)
+    ),
+  ];
+  const worksheets = worksheetIds.length
+    ? await prisma.worksheet.findMany({
+        where: { id: { in: worksheetIds } },
+        select: { id: true, assignments: { select: { id: true }, take: 1 } },
+      })
+    : [];
+  const assignmentIdByWorksheetId = new Map(
+    worksheets.map((w) => [w.id, w.assignments[0]?.id ?? null])
+  );
+
+  const completeModuleIds = new Set<string>();
+  for (const module of modules) {
+    if (isModuleComplete(module, completedItemIds)) {
+      completeModuleIds.add(module.id);
+    }
+  }
+
+  const now = new Date();
+  let continueItemId: string | null = null;
+  let continueModuleId: string | null = null;
+
+  const result = modules.map((module) => {
+    const publishedPrereqIds = module.prerequisites
+      .map((p) => p.prerequisiteId)
+      .filter((id) => modules.some((m) => m.id === id));
+    const lockedByPrerequisite = publishedPrereqIds.some(
+      (id) => !completeModuleIds.has(id)
+    );
+    const lockedByDate = !!module.unlockAt && module.unlockAt > now;
+    const locked = lockedByPrerequisite || lockedByDate;
+
+    const required = module.items.filter((i) => i.requirementType);
+    const completedRequired = required.filter((i) => completedItemIds.has(i.id));
+    const percentComplete = required.length
+      ? Math.round((completedRequired.length / required.length) * 100)
+      : completeModuleIds.has(module.id)
+        ? 100
+        : 0;
+
+    // With sequential progression, items after the first incomplete required
+    // item are not yet accessible.
+    let sequentialBlocked = false;
+    const items = module.items.map((item) => {
+      const completed = completedItemIds.has(item.id);
+      const accessible =
+        !locked && (!module.requireSequential || !sequentialBlocked);
+      if (
+        module.requireSequential &&
+        item.requirementType &&
+        !completed &&
+        !sequentialBlocked
+      ) {
+        sequentialBlocked = true;
+      }
+      if (
+        !continueItemId &&
+        !locked &&
+        accessible &&
+        item.requirementType &&
+        !completed
+      ) {
+        continueItemId = item.id;
+        continueModuleId = module.id;
+      }
+      return {
+        ...item,
+        completed,
+        accessible,
+        worksheetAssignmentId:
+          item.itemType === ModuleItemType.WORKSHEET && item.itemId
+            ? (assignmentIdByWorksheetId.get(item.itemId) ?? null)
+            : null,
+      };
+    });
+
+    return {
+      ...module,
+      items,
+      locked,
+      lockedByPrerequisite,
+      lockedByDate,
+      completed: completeModuleIds.has(module.id),
+      requiredCount: required.length,
+      completedRequiredCount: completedRequired.length,
+      percentComplete,
+    };
+  });
+
+  return {
+    modules: result,
+    continueItemId,
+    continueModuleId,
+  };
+}
+
+/**
+ * Mark a module item as viewed by a student. Completes VIEW requirements;
+ * for other requirement types this only records that a progress row exists.
+ */
+export async function markItemViewedRecord(
+  studentId: string,
+  input: { classId: string; itemId: string }
+) {
+  const item = await findModuleItemInClass(input.itemId, input.classId);
+  if (!item || !item.module.published) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Module item not found" });
+  }
+
+  const state = await getStudentModulesState(input.classId, studentId);
+  const moduleState = state.modules.find((m) => m.id === item.moduleId);
+  const itemState = moduleState?.items.find((i) => i.id === item.id);
+  if (!moduleState || !itemState || moduleState.locked || !itemState.accessible) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "This module item is locked",
+    });
+  }
+
+  if (item.requirementType === ModuleItemRequirementType.VIEW) {
+    return upsertItemProgress(item.id, studentId, "COMPLETE");
+  }
+  return upsertItemProgress(item.id, studentId, "INCOMPLETE");
+}
+
+/* -------------------------------------------------------------------------- */
+/*                    Automatic completion hooks                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Update module progress for a student's assignment after a submission event
+ * (submitted or returned/graded). Safe to call from any flow; never throws.
+ */
+export async function syncAssignmentModuleProgress(
+  studentId: string,
+  assignmentId: string
+) {
+  try {
+    const items = await prisma.courseModuleItem.findMany({
+      where: {
+        itemType: ModuleItemType.ASSIGNMENT,
+        itemId: assignmentId,
+        requirementType: {
+          in: [
+            ModuleItemRequirementType.SUBMIT,
+            ModuleItemRequirementType.SCORE_AT_LEAST,
+          ],
+        },
+      },
+    });
+    if (!items.length) return;
+
+    const submission = await prisma.submission.findFirst({
+      where: { assignmentId, studentId },
+      select: { submitted: true, returned: true, gradeReceived: true },
+    });
+    if (!submission) return;
+
+    for (const item of items) {
+      const complete =
+        item.requirementType === ModuleItemRequirementType.SUBMIT
+          ? !!submission.submitted
+          : !!submission.returned &&
+            submission.gradeReceived != null &&
+            submission.gradeReceived >= (item.requiredScore ?? 0);
+      if (complete) {
+        await upsertItemProgress(item.id, studentId, "COMPLETE");
+      }
+    }
+  } catch (error) {
+    logger.error("Failed to sync assignment module progress", {
+      error,
+      studentId,
+      assignmentId,
+    });
+  }
+}
+
+/**
+ * Update module progress for a student's worksheet after grading completes.
+ * SUBMIT requirements complete immediately; SCORE_AT_LEAST compares the sum
+ * of earned points across the worksheet response. Never throws.
+ */
+export async function syncWorksheetModuleProgress(
+  studentId: string,
+  worksheetId: string
+) {
+  try {
+    const items = await prisma.courseModuleItem.findMany({
+      where: {
+        itemType: ModuleItemType.WORKSHEET,
+        itemId: worksheetId,
+        requirementType: {
+          in: [
+            ModuleItemRequirementType.SUBMIT,
+            ModuleItemRequirementType.SCORE_AT_LEAST,
+          ],
+        },
+      },
+    });
+    if (!items.length) return;
+
+    const earned = await prisma.studentQuestionProgress.aggregate({
+      where: { studentId, question: { worksheetId } },
+      _sum: { points: true },
+    });
+    const totalPoints = earned._sum.points ?? 0;
+
+    for (const item of items) {
+      const complete =
+        item.requirementType === ModuleItemRequirementType.SUBMIT ||
+        totalPoints >= (item.requiredScore ?? 0);
+      if (complete) {
+        await upsertItemProgress(item.id, studentId, "COMPLETE");
+      }
+    }
+  } catch (error) {
+    logger.error("Failed to sync worksheet module progress", {
+      error,
+      studentId,
+      worksheetId,
+    });
+  }
+}