@studious-lms/server 1.20.0 → 1.22.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/tests/unit/services/gradeCalculation.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect } from "vitest";
+import {
+  computeFinalGrade,
+  resolveLetterGrade,
+  roundPercentage,
+  type GradeCalculationPolicies,
+  type GradeCategoryInput,
+  type ScoreInput,
+} from "../../../src/services/gradeCalculation.js";
+
+const noPolicies: GradeCalculationPolicies = {
+  treatMissingAsZero: false,
+  roundingMode: "NONE",
+};
+
+const categories: GradeCategoryInput[] = [
+  { id: "hw", name: "Homework", weight: 40, dropLowest: 0 },
+  { id: "exam", name: "Exams", weight: 60, dropLowest: 0 },
+];
+
+describe("computeFinalGrade", () => {
+  it("returns null percentage with no scores", () => {
+    const result = computeFinalGrade(noPolicies, categories, []);
+    expect(result.percentage).toBeNull();
+    expect(result.categories).toHaveLength(2);
+    expect(result.categories[0].average).toBeNull();
+  });
+
+  it("computes weighted average of category averages", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 8, maxPoints: 10 }, // 80%
+      { categoryId: "exam", pointsEarned: 50, maxPoints: 100 }, // 50%
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    // 80 * 0.4 + 50 * 0.6 = 62
+    expect(result.percentage).toBeCloseTo(62);
+  });
+
+  it("puts uncategorized scores into a default category with weight 1", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 10, maxPoints: 10 }, // 100%
+      { categoryId: null, pointsEarned: 5, maxPoints: 10 }, // 50%
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    // (100 * 40 + 50 * 1) / 41
+    expect(result.percentage).toBeCloseTo((100 * 40 + 50) / 41);
+    const fallback = result.categories.find((c) => c.categoryId === null);
+    expect(fallback?.average).toBeCloseTo(50);
+    expect(fallback?.weight).toBe(1);
+  });
+
+  it("treats unknown category ids as uncategorized", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "deleted", pointsEarned: 5, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(
+      result.categories.find((c) => c.categoryId === null)?.average
+    ).toBeCloseTo(50);
+  });
+
+  it("excludes missing scores by default", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 8, maxPoints: 10 },
+      { categoryId: "hw", pointsEarned: null, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(
+      result.categories.find((c) => c.categoryId === "hw")?.average
+    ).toBeCloseTo(80);
+  });
+
+  it("counts missing scores as zero when treatMissingAsZero is set", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 8, maxPoints: 10 },
+      { categoryId: "hw", pointsEarned: null, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(
+      { ...noPolicies, treatMissingAsZero: true },
+      categories,
+      scores
+    );
+    expect(
+      result.categories.find((c) => c.categoryId === "hw")?.average
+    ).toBeCloseTo(40);
+  });
+
+  it("respects per-score weights within a category", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 10, maxPoints: 10, weight: 3 }, // 100%
+      { categoryId: "hw", pointsEarned: 0, maxPoints: 10, weight: 1 }, // 0%
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(
+      result.categories.find((c) => c.categoryId === "hw")?.average
+    ).toBeCloseTo(75);
+  });
+
+  it("drops the lowest N scores in a category", () => {
+    const dropCategories: GradeCategoryInput[] = [
+      { id: "hw", name: "Homework", weight: 1, dropLowest: 1 },
+    ];
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 10, maxPoints: 10 }, // 100%
+      { categoryId: "hw", pointsEarned: 2, maxPoints: 10 }, // 20% (dropped)
+      { categoryId: "hw", pointsEarned: 6, maxPoints: 10 }, // 60%
+    ];
+    const result = computeFinalGrade(noPolicies, dropCategories, scores);
+    expect(result.percentage).toBeCloseTo(80);
+    expect(result.categories[0].droppedScores).toBe(1);
+    expect(result.categories[0].countedScores).toBe(2);
+  });
+
+  it("never drops every score in a category", () => {
+    const dropCategories: GradeCategoryInput[] = [
+      { id: "hw", name: "Homework", weight: 1, dropLowest: 5 },
+    ];
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 4, maxPoints: 10 },
+      { categoryId: "hw", pointsEarned: 8, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, dropCategories, scores);
+    expect(result.percentage).toBeCloseTo(80);
+    expect(result.categories[0].droppedScores).toBe(1);
+  });
+
+  it("ignores scores with non-positive maxPoints", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 5, maxPoints: 0 },
+      { categoryId: "hw", pointsEarned: 9, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(
+      result.categories.find((c) => c.categoryId === "hw")?.average
+    ).toBeCloseTo(90);
+  });
+
+  it("excludes empty categories from the weighted average", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 9, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(result.percentage).toBeCloseTo(90);
+  });
+
+  it("applies the rounding mode to the final percentage", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 5, maxPoints: 6 }, // 83.33%
+    ];
+    expect(
+      computeFinalGrade(
+        { ...noPolicies, roundingMode: "FLOOR" },
+        categories,
+        scores
+      ).percentage
+    ).toBe(83);
+    expect(
+      computeFinalGrade(
+        { ...noPolicies, roundingMode: "CEILING" },
+        categories,
+        scores
+      ).percentage
+    ).toBe(84);
+    expect(
+      computeFinalGrade(
+        { ...noPolicies, roundingMode: "HALF_UP" },
+        categories,
+        scores
+      ).percentage
+    ).toBe(83);
+  });
+});
+
+describe("roundPercentage", () => {
+  it("rounds according to mode", () => {
+    expect(roundPercentage(89.5, "HALF_UP")).toBe(90);
+    expect(roundPercentage(89.9, "FLOOR")).toBe(89);
+    expect(roundPercentage(89.1, "CEILING")).toBe(90);
+    expect(roundPercentage(89.123, "NONE")).toBeCloseTo(89.123);
+  });
+});
+
+describe("resolveLetterGrade", () => {
+  const structured = JSON.stringify({
+    boundaries: [
+      { grade: "A", minPercentage: 90, maxPercentage: 100 },
+      { grade: "B", minPercentage: 80, maxPercentage: 89 },
+      { grade: "C", minPercentage: 70, maxPercentage: 79 },
+    ],
+  });
+
+  it("maps percentages to letters", () => {
+    expect(resolveLetterGrade(structured, 95)).toBe("A");
+    expect(resolveLetterGrade(structured, 85)).toBe("B");
+    expect(resolveLetterGrade(structured, 70)).toBe("C");
+  });
+
+  it("returns null below all boundaries", () => {
+    expect(resolveLetterGrade(structured, 10)).toBeNull();
+  });
+
+  it("returns null for malformed payloads", () => {
+    expect(resolveLetterGrade("not json", 90)).toBeNull();
+    expect(resolveLetterGrade("{}", 90)).toBeNull();
+  });
+});