@studious-lms/server 1.21.0 → 1.23.0

package/src/services/gradebook.ts

@@ -0,0 +1,383 @@
+/**
+ * Gradebook service – grade categories, custom columns/entries, class
+ * grade-calculation policies, the computed gradebook, and CSV export.
+ *
+ * All grade math lives in `gradeCalculation.ts` (pure, unit-tested); this
+ * service only assembles inputs and persists configuration.
+ */
+import { GradeRoundingMode as PrismaGradeRoundingMode } from "@prisma/client";
+import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
+import { isTeacherInClass } from "../models/class.js";
+import {
+  findGradeCategoriesByClassId,
+  findGradeCategory,
+  findCustomGradeColumnsByClassId,
+  findCustomGradeColumn,
+  findClassForGradebook,
+  findClassGradePolicies,
+} from "../models/gradebook.js";
+import {
+  computeFinalGrade,
+  resolveLetterGrade,
+  type FinalGradeResult,
+  type GradeCategoryInput,
+  type ScoreInput,
+} from "./gradeCalculation.js";
+
+// ===== Categories =====
+
+export async function listGradeCategories(classId: string) {
+  return findGradeCategoriesByClassId(classId);
+}
+
+export async function createGradeCategory(
+  classId: string,
+  data: { name: string; weight: number; dropLowest?: number; position?: number }
+) {
+  return prisma.gradeCategory.create({
+    data: {
+      classId,
+      name: data.name,
+      weight: data.weight,
+      dropLowest: data.dropLowest ?? 0,
+      position: data.position ?? (await findGradeCategoriesByClassId(classId)).length,
+    },
+  });
+}
+
+export async function updateGradeCategory(
+  categoryId: string,
+  classId: string,
+  data: {
+    name?: string;
+    weight?: number;
+    dropLowest?: number;
+    position?: number;
+  }
+) {
+  const category = await findGradeCategory(categoryId, classId);
+  if (!category) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Category not found" });
+  }
+  return prisma.gradeCategory.update({
+    where: { id: categoryId },
+    data,
+  });
+}
+
+export async function deleteGradeCategory(categoryId: string, classId: string) {
+  const category = await findGradeCategory(categoryId, classId);
+  if (!category) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Category not found" });
+  }
+  return prisma.gradeCategory.delete({ where: { id: categoryId } });
+}
+
+export async function assignAssignmentCategory(
+  classId: string,
+  assignmentId: string,
+  gradeCategoryId: string | null
+) {
+  if (gradeCategoryId) {
+    const category = await findGradeCategory(gradeCategoryId, classId);
+    if (!category) {
+      throw new TRPCError({ code: "NOT_FOUND", message: "Category not found" });
+    }
+  }
+  return prisma.assignment.update({
+    where: { id: assignmentId, classId },
+    data: { gradeCategoryId },
+  });
+}
+
+// ===== Custom columns =====
+
+export async function listCustomGradeColumns(classId: string) {
+  return findCustomGradeColumnsByClassId(classId);
+}
+
+export async function createCustomGradeColumn(
+  classId: string,
+  data: {
+    name: string;
+    maxPoints: number;
+    gradeCategoryId?: string | null;
+    position?: number;
+  }
+) {
+  if (data.gradeCategoryId) {
+    const category = await findGradeCategory(data.gradeCategoryId, classId);
+    if (!category) {
+      throw new TRPCError({ code: "NOT_FOUND", message: "Category not found" });
+    }
+  }
+  return prisma.customGradeColumn.create({
+    data: {
+      classId,
+      name: data.name,
+      maxPoints: data.maxPoints,
+      gradeCategoryId: data.gradeCategoryId ?? null,
+      position:
+        data.position ?? (await findCustomGradeColumnsByClassId(classId)).length,
+    },
+  });
+}
+
+export async function updateCustomGradeColumn(
+  columnId: string,
+  classId: string,
+  data: {
+    name?: string;
+    maxPoints?: number;
+    gradeCategoryId?: string | null;
+    position?: number;
+  }
+) {
+  const column = await findCustomGradeColumn(columnId, classId);
+  if (!column) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Column not found" });
+  }
+  if (data.gradeCategoryId) {
+    const category = await findGradeCategory(data.gradeCategoryId, classId);
+    if (!category) {
+      throw new TRPCError({ code: "NOT_FOUND", message: "Category not found" });
+    }
+  }
+  return prisma.customGradeColumn.update({
+    where: { id: columnId },
+    data,
+  });
+}
+
+export async function deleteCustomGradeColumn(
+  columnId: string,
+  classId: string
+) {
+  const column = await findCustomGradeColumn(columnId, classId);
+  if (!column) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Column not found" });
+  }
+  return prisma.customGradeColumn.delete({ where: { id: columnId } });
+}
+
+export async function setCustomGradeEntry(
+  classId: string,
+  columnId: string,
+  studentId: string,
+  points: number | null,
+  note?: string | null
+) {
+  const column = await findCustomGradeColumn(columnId, classId);
+  if (!column) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Column not found" });
+  }
+  if (points === null) {
+    await prisma.customGradeEntry.deleteMany({
+      where: { columnId, studentId },
+    });
+    return null;
+  }
+  return prisma.customGradeEntry.upsert({
+    where: { columnId_studentId: { columnId, studentId } },
+    create: { columnId, studentId, points, note: note ?? null },
+    update: { points, ...(note !== undefined ? { note } : {}) },
+  });
+}
+
+// ===== Policies =====
+
+export async function getGradePolicies(classId: string) {
+  const policies = await findClassGradePolicies(classId);
+  if (!policies) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Class not found" });
+  }
+  return policies;
+}
+
+export async function updateGradePolicies(
+  classId: string,
+  data: {
+    treatMissingAsZero?: boolean;
+    gradeRoundingMode?: PrismaGradeRoundingMode;
+  }
+) {
+  return prisma.class.update({
+    where: { id: classId },
+    data,
+    select: {
+      id: true,
+      treatMissingAsZero: true,
+      gradeRoundingMode: true,
+    },
+  });
+}
+
+// ===== Computed gradebook =====
+
+export interface GradebookStudentRow {
+  studentId: string;
+  studentName: string;
+  assignmentScores: Record<string, number | null>;
+  customScores: Record<string, { points: number | null; note: string | null }>;
+  result: FinalGradeResult;
+  letterGrade: string | null;
+}
+
+export async function getComputedGradebook(classId: string, userId: string) {
+  const [classData, categories, columns, isTeacher] = await Promise.all([
+    findClassForGradebook(classId),
+    findGradeCategoriesByClassId(classId),
+    findCustomGradeColumnsByClassId(classId),
+    isTeacherInClass(classId, userId),
+  ]);
+  if (!classData) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Class not found" });
+  }
+
+  // Students only ever see their own row.
+  const students = isTeacher
+    ? classData.students
+    : classData.students.filter((student) => student.id === userId);
+
+  const policies = {
+    treatMissingAsZero: classData.treatMissingAsZero,
+    roundingMode: classData.gradeRoundingMode,
+  };
+  const categoryInputs: GradeCategoryInput[] = categories.map((category) => ({
+    id: category.id,
+    name: category.name,
+    weight: category.weight,
+    dropLowest: category.dropLowest,
+  }));
+  const boundary = classData.gradingBoundaries[0] ?? null;
+
+  const rows: GradebookStudentRow[] = students.map((student) => {
+    const assignmentScores: Record<string, number | null> = {};
+    const scores: ScoreInput[] = [];
+
+    for (const assignment of classData.assignments) {
+      const submission = assignment.submissions.find(
+        (item) => item.studentId === student.id
+      );
+      const pointsEarned = submission?.gradeReceived ?? null;
+      assignmentScores[assignment.id] = pointsEarned;
+      scores.push({
+        categoryId: assignment.gradeCategoryId,
+        pointsEarned,
+        maxPoints: assignment.maxGrade ?? 0,
+        weight: assignment.weight,
+      });
+    }
+
+    const customScores: GradebookStudentRow["customScores"] = {};
+    for (const column of columns) {
+      const entry = column.entries.find(
+        (item) => item.studentId === student.id
+      );
+      customScores[column.id] = {
+        points: entry?.points ?? null,
+        note: entry?.note ?? null,
+      };
+      scores.push({
+        categoryId: column.gradeCategoryId,
+        pointsEarned: entry?.points ?? null,
+        maxPoints: column.maxPoints,
+      });
+    }
+
+    const result = computeFinalGrade(policies, categoryInputs, scores);
+    const letterGrade =
+      boundary && result.percentage !== null
+        ? resolveLetterGrade(boundary.structured, result.percentage)
+        : null;
+
+    return {
+      studentId: student.id,
+      studentName: student.profile?.displayName || student.username,
+      assignmentScores,
+      customScores,
+      result,
+      letterGrade,
+    };
+  });
+
+  return {
+    policies,
+    categories,
+    assignments: classData.assignments.map((assignment) => ({
+      id: assignment.id,
+      title: assignment.title,
+      maxGrade: assignment.maxGrade,
+      weight: assignment.weight,
+      gradeCategoryId: assignment.gradeCategoryId,
+      dueDate: assignment.dueDate,
+    })),
+    customColumns: columns.map((column) => ({
+      id: column.id,
+      name: column.name,
+      maxPoints: column.maxPoints,
+      gradeCategoryId: column.gradeCategoryId,
+      position: column.position,
+    })),
+    gradingBoundary: boundary,
+    students: rows,
+  };
+}
+
+// ===== CSV export =====
+
+function escapeCsvCell(value: string): string {
+  if (/[",\n\r]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+export async function exportGradebookCsv(classId: string, userId: string) {
+  const gradebook = await getComputedGradebook(classId, userId);
+
+  const header = [
+    "Student",
+    ...gradebook.assignments.map(
+      (assignment) => `${assignment.title} (/${assignment.maxGrade ?? 0})`
+    ),
+    ...gradebook.customColumns.map(
+      (column) => `${column.name} (/${column.maxPoints})`
+    ),
+    ...gradebook.categories.map((category) => `${category.name} Avg (%)`),
+    "Final (%)",
+    "Letter",
+  ];
+
+  const lines = [header.map(escapeCsvCell).join(",")];
+
+  for (const row of gradebook.students) {
+    const categoryCells = gradebook.categories.map((category) => {
+      const average = row.result.categories.find(
+        (item) => item.categoryId === category.id
+      )?.average;
+      return average === null || average === undefined
+        ? ""
+        : average.toFixed(2);
+    });
+
+    const cells = [
+      row.studentName,
+      ...gradebook.assignments.map((assignment) => {
+        const points = row.assignmentScores[assignment.id];
+        return points === null || points === undefined ? "" : String(points);
+      }),
+      ...gradebook.customColumns.map((column) => {
+        const points = row.customScores[column.id]?.points;
+        return points === null || points === undefined ? "" : String(points);
+      }),
+      ...categoryCells,
+      row.result.percentage === null ? "" : row.result.percentage.toFixed(2),
+      row.letterGrade ?? "",
+    ];
+    lines.push(cells.map(escapeCsvCell).join(","));
+  }
+
+  return { csv: lines.join("\n") };
+}

package/src/services/school.ts

@@ -23,17 +23,24 @@ import {
   countActiveAdmins,
   createSchoolInvite,
   createSchoolWithAdmin,
+  deleteSchoolClassRecord,
   findActiveSchoolAdminMembership,
   findPendingInviteByToken,
+  findSchoolClass,
   findSchoolMembership,
   getSchoolById,
+  getSchoolMemberDetail,
   getSchoolOverview,
+  listActiveSchoolMemberships,
+  listMemberClasses,
+  listRecentSchoolMembers,
   listSchoolClasses,
   listSchoolInvites,
   listSchoolMembers,
   listUserSchoolMemberships,
   removeSchoolMembershipPreservingContent,
   revokeSchoolInvite,
+  updateSchoolClassMembers,
   updateSchoolMembershipRole,
   updateSchoolRecord,
   upsertSchoolMembership,
@@ -133,7 +140,10 @@ export async function updateSchoolDetails(
 
 export async function getAdminOverview(userId: string, schoolId: string) {
   await requireSchoolAdmin(schoolId, userId);
-  const school = await getSchoolOverview(schoolId);
+  const [school, recentMembers] = await Promise.all([
+    getSchoolOverview(schoolId),
+    listRecentSchoolMembers(schoolId),
+  ]);
   if (!school) {
     throw new TRPCError({ code: "NOT_FOUND", message: "School not found" });
   }
@@ -159,6 +169,7 @@ export async function getAdminOverview(userId: string, schoolId: string) {
       },
       recentClasses: school.classes,
       recentInvites: school.invites,
+      recentMembers,
     },
   };
 }
@@ -265,6 +276,172 @@ export async function updateMemberRole(
   return { membership };
 }
 
+export async function getMemberDetail(
+  userId: string,
+  input: { schoolId: string; memberUserId: string }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const membership = await getSchoolMemberDetail(
+    input.schoolId,
+    input.memberUserId
+  );
+  if (!membership) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Member not found" });
+  }
+
+  const [teachingClasses, enrolledClasses] = await listMemberClasses(
+    input.schoolId,
+    input.memberUserId
+  );
+
+  const toClassSummary = (cls: (typeof teachingClasses)[number]) => ({
+    id: cls.id,
+    name: cls.name,
+    section: cls.section,
+    subject: cls.subject,
+    color: cls.color,
+    teacherCount: cls._count.teachers,
+    studentCount: cls._count.students,
+  });
+
+  return {
+    membership,
+    teachingClasses: teachingClasses.map(toClassSummary),
+    enrolledClasses: enrolledClasses.map(toClassSummary),
+  };
+}
+
+export async function bulkUpdateMemberRoles(
+  userId: string,
+  input: {
+    schoolId: string;
+    memberUserIds: string[];
+    role: SchoolMembershipRole;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const memberships = await listActiveSchoolMemberships(
+    input.schoolId,
+    input.memberUserIds
+  );
+  if (memberships.length === 0) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "No members found" });
+  }
+
+  if (input.role !== "ADMIN") {
+    const demotedAdmins = memberships.filter((m) => m.role === "ADMIN").length;
+    if (demotedAdmins > 0) {
+      const adminCount = await countActiveAdmins(input.schoolId);
+      if (adminCount - demotedAdmins < 1) {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: "A school must have at least one active admin",
+        });
+      }
+    }
+  }
+
+  await prisma.schoolMembership.updateMany({
+    where: {
+      schoolId: input.schoolId,
+      userId: { in: memberships.map((m) => m.userId) },
+      status: "ACTIVE",
+    },
+    data: { role: input.role },
+  });
+  return { updatedCount: memberships.length };
+}
+
+export async function bulkRemoveMembers(
+  userId: string,
+  input: { schoolId: string; memberUserIds: string[] }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const targetIds = input.memberUserIds.filter((id) => id !== userId);
+  const memberships = await listActiveSchoolMemberships(
+    input.schoolId,
+    targetIds
+  );
+  if (memberships.length === 0) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "No members found" });
+  }
+
+  const removedAdmins = memberships.filter((m) => m.role === "ADMIN").length;
+  if (removedAdmins > 0) {
+    const adminCount = await countActiveAdmins(input.schoolId);
+    if (adminCount - removedAdmins < 1) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "A school must have at least one active admin",
+      });
+    }
+  }
+
+  for (const membership of memberships) {
+    await removeSchoolMembershipPreservingContent(
+      input.schoolId,
+      membership.userId
+    );
+  }
+  return { removedCount: memberships.length };
+}
+
+export async function deleteSchoolClass(
+  userId: string,
+  input: { schoolId: string; classId: string }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const cls = await findSchoolClass(input.schoolId, input.classId);
+  if (!cls) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Class not found" });
+  }
+  await deleteSchoolClassRecord(input.schoolId, input.classId);
+  return { deletedClass: { id: input.classId } };
+}
+
+export async function updateClassMembers(
+  userId: string,
+  input: {
+    schoolId: string;
+    classId: string;
+    addTeacherIds?: string[];
+    removeTeacherIds?: string[];
+    addStudentIds?: string[];
+    removeStudentIds?: string[];
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const cls = await findSchoolClass(input.schoolId, input.classId);
+  if (!cls) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Class not found" });
+  }
+
+  const addTeacherIds = input.addTeacherIds ?? [];
+  const addStudentIds = input.addStudentIds ?? [];
+  const addedIds = [...addTeacherIds, ...addStudentIds];
+  if (addedIds.length > 0) {
+    const memberships = await listActiveSchoolMemberships(
+      input.schoolId,
+      addedIds
+    );
+    const activeIds = new Set(memberships.map((m) => m.userId));
+    if (addedIds.some((id) => !activeIds.has(id))) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "All added users must be active members of this school",
+      });
+    }
+  }
+
+  const updated = await updateSchoolClassMembers(input.classId, {
+    addTeacherIds,
+    removeTeacherIds: input.removeTeacherIds ?? [],
+    addStudentIds,
+    removeStudentIds: input.removeStudentIds ?? [],
+  });
+  return { class: updated };
+}
+
 export async function removeMember(
   userId: string,
   input: { schoolId: string; memberUserId: string }