@studious-lms/server 1.23.0 → 1.25.0

package/src/services/attendanceMerge.ts

@@ -0,0 +1,139 @@
+/**
+ * Pure helpers for merging teacher attendance updates with excusal locks.
+ */
+import type { AttendanceStatus } from "@prisma/client";
+
+export type StudentRef = { id: string; username: string };
+
+export type AttendanceLock = {
+  studentId: string;
+  excusalId: string;
+  reason?: string | null;
+  note?: string | null;
+};
+
+export type MergedAttendanceUpdate = {
+  presentIds: string[];
+  lateIds: string[];
+  absentIds: string[];
+  excusedIds: string[];
+  records: Array<{
+    studentId: string;
+    status: AttendanceStatus;
+    note?: string | null;
+    excusedByExcusalId?: string | null;
+    updatedById?: string | null;
+  }>;
+  /** Students whose status was forced to EXCUSED by an active excusal. */
+  lockedStudentIds: string[];
+};
+
+/**
+ * Build present/late/absent/excused lists + per-student records.
+ * Active excusal locks always win (status EXCUSED + excusedByExcusalId set).
+ */
+export function mergeAttendanceUpdateWithLocks(input: {
+  present: StudentRef[];
+  late: StudentRef[];
+  absent: StudentRef[];
+  excused?: StudentRef[];
+  locks: AttendanceLock[];
+  updatedById?: string | null;
+  /** Preserve notes for locked students when available. */
+  existingNotesByStudentId?: Map<string, string | null | undefined>;
+}): MergedAttendanceUpdate {
+  const lockByStudent = new Map(input.locks.map((lock) => [lock.studentId, lock]));
+  const lockedStudentIds = [...lockByStudent.keys()];
+
+  const stripLocked = (students: StudentRef[]) =>
+    students.filter((s) => !lockByStudent.has(s.id));
+
+  const presentIds = stripLocked(input.present).map((s) => s.id);
+  const lateIds = stripLocked(input.late).map((s) => s.id);
+  const absentIds = stripLocked(input.absent).map((s) => s.id);
+  const manualExcusedIds = stripLocked(input.excused ?? []).map((s) => s.id);
+  const excusedIds = [...new Set([...manualExcusedIds, ...lockedStudentIds])];
+
+  const records: MergedAttendanceUpdate["records"] = [];
+
+  for (const studentId of presentIds) {
+    records.push({
+      studentId,
+      status: "PRESENT",
+      updatedById: input.updatedById,
+    });
+  }
+  for (const studentId of lateIds) {
+    records.push({
+      studentId,
+      status: "LATE",
+      updatedById: input.updatedById,
+    });
+  }
+  for (const studentId of absentIds) {
+    records.push({
+      studentId,
+      status: "ABSENT",
+      updatedById: input.updatedById,
+    });
+  }
+  for (const studentId of manualExcusedIds) {
+    records.push({
+      studentId,
+      status: "EXCUSED",
+      excusedByExcusalId: null,
+      updatedById: input.updatedById,
+    });
+  }
+  for (const lock of input.locks) {
+    records.push({
+      studentId: lock.studentId,
+      status: "EXCUSED",
+      note:
+        input.existingNotesByStudentId?.get(lock.studentId) ?? lock.note ?? null,
+      excusedByExcusalId: lock.excusalId,
+      updatedById: input.updatedById,
+    });
+  }
+
+  return {
+    presentIds,
+    lateIds,
+    absentIds,
+    excusedIds,
+    records,
+    lockedStudentIds,
+  };
+}
+
+/** Map active excusals (with student join rows) to per-student locks. */
+export function buildExcusalLocks(
+  excusals: Array<{
+    id: string;
+    reason?: string | null;
+    note?: string | null;
+    students: Array<{ studentId: string }>;
+  }>,
+  studentIds?: Iterable<string>
+): AttendanceLock[] {
+  const allow =
+    studentIds === undefined ? null : new Set(studentIds);
+  const locks: AttendanceLock[] = [];
+  const seen = new Set<string>();
+
+  for (const excusal of excusals) {
+    for (const row of excusal.students) {
+      if (allow && !allow.has(row.studentId)) continue;
+      if (seen.has(row.studentId)) continue;
+      seen.add(row.studentId);
+      locks.push({
+        studentId: row.studentId,
+        excusalId: excusal.id,
+        reason: excusal.reason,
+        note: excusal.note,
+      });
+    }
+  }
+
+  return locks;
+}

package/src/services/attendanceRate.ts

@@ -0,0 +1,41 @@
+/**
+ * Attendance rate helpers for transcripts / progress reports.
+ *
+ * Reads the current Attendance M2M shape only (present / late / absent).
+ * Do NOT write Attendance schema here — A1 may introduce EXCUSED /
+ * AttendanceRecord; keep rate logic in this one place so A1 can extend it.
+ */
+
+export type AttendanceStatus = "PRESENT" | "LATE" | "ABSENT";
+
+export interface AttendanceRateSummary {
+  present: number;
+  late: number;
+  absent: number;
+  total: number;
+  /** (present + late) / total * 100, or null when total is 0. */
+  percent: number | null;
+}
+
+/**
+ * Computes attendance counts and rate from shaped status records.
+ * Late counts toward attendance (present for rate purposes).
+ */
+export function computeAttendanceRate(
+  records: { status: AttendanceStatus }[]
+): AttendanceRateSummary {
+  let present = 0;
+  let late = 0;
+  let absent = 0;
+
+  for (const record of records) {
+    if (record.status === "PRESENT") present += 1;
+    else if (record.status === "LATE") late += 1;
+    else if (record.status === "ABSENT") absent += 1;
+  }
+
+  const total = present + late + absent;
+  const percent = total === 0 ? null : ((present + late) / total) * 100;
+
+  return { present, late, absent, total, percent };
+}

package/src/services/attendanceStats.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure attendance percentage helpers.
+ * EXCUSED days are excluded from both numerator and denominator.
+ */
+import type { AttendanceStatus } from "@prisma/client";
+
+export type AttendanceStatusCount = {
+  present: number;
+  late: number;
+  absent: number;
+  excused: number;
+};
+
+export function emptyAttendanceCounts(): AttendanceStatusCount {
+  return { present: 0, late: 0, absent: 0, excused: 0 };
+}
+
+export function tallyAttendanceStatuses(
+  statuses: Iterable<AttendanceStatus | string>
+): AttendanceStatusCount {
+  const counts = emptyAttendanceCounts();
+  for (const status of statuses) {
+    switch (status) {
+      case "PRESENT":
+        counts.present += 1;
+        break;
+      case "LATE":
+        counts.late += 1;
+        break;
+      case "ABSENT":
+        counts.absent += 1;
+        break;
+      case "EXCUSED":
+        counts.excused += 1;
+        break;
+      default:
+        break;
+    }
+  }
+  return counts;
+}
+
+/**
+ * Attendance rate as a percentage.
+ * Formula: (present + late) / (present + late + absent) * 100
+ * Excused records are ignored entirely.
+ * Returns null when there are no countable (non-excused) records.
+ */
+export function computeAttendancePercentage(
+  counts: Pick<AttendanceStatusCount, "present" | "late" | "absent">
+): number | null {
+  const countable = counts.present + counts.late + counts.absent;
+  if (countable === 0) {
+    return null;
+  }
+  return ((counts.present + counts.late) / countable) * 100;
+}
+
+export function computeAttendancePercentageFromStatuses(
+  statuses: Iterable<AttendanceStatus | string>
+): number | null {
+  return computeAttendancePercentage(tallyAttendanceStatuses(statuses));
+}

package/src/services/class.ts

@@ -2,7 +2,7 @@
  * Class service – CRUD for classes, members, grades, mark schemes, grading boundaries,
  * syllabus, lab drafts, and invite codes.
  */
-import { SessionType } from "@prisma/client";
+import { Prisma, SessionType } from "@prisma/client";
 import { TRPCError } from "@trpc/server";
 import { prisma } from "../lib/prisma.js";
 import { generateInviteCode } from "../utils/generateInviteCode.js";
@@ -196,6 +196,7 @@ export async function updateClass(
     discussionsEnabled?: boolean;
     studentsCanCreateDiscussions?: boolean;
     studentsCanReply?: boolean;
+    sidebarFeatures?: Record<string, boolean> | null;
   }
 ) {
   if (data.departmentId !== undefined) {
@@ -226,7 +227,29 @@ export async function updateClass(
 
   const updatedClass = await prisma.class.update({
     where: { id: classId },
-    data,
+    // Prisma Exact<> rejects mixed relation/unchecked shapes; pass unchecked scalars.
+    data: {
+      ...(data.name !== undefined && { name: data.name }),
+      ...(data.section !== undefined && { section: data.section }),
+      ...(data.subject !== undefined && { subject: data.subject }),
+      ...(data.color !== undefined && { color: data.color }),
+      ...(data.symbol !== undefined && { symbol: data.symbol }),
+      ...(data.departmentId !== undefined && {
+        departmentId: data.departmentId,
+      }),
+      ...(data.discussionsEnabled !== undefined && {
+        discussionsEnabled: data.discussionsEnabled,
+      }),
+      ...(data.studentsCanCreateDiscussions !== undefined && {
+        studentsCanCreateDiscussions: data.studentsCanCreateDiscussions,
+      }),
+      ...(data.studentsCanReply !== undefined && {
+        studentsCanReply: data.studentsCanReply,
+      }),
+      ...(data.sidebarFeatures !== undefined && {
+        sidebarFeatures: data.sidebarFeatures ?? Prisma.DbNull,
+      }),
+    } as Parameters<typeof prisma.class.update>[0]["data"],
     select: {
       id: true,
       name: true,
@@ -238,6 +261,7 @@ export async function updateClass(
       discussionsEnabled: true,
       studentsCanCreateDiscussions: true,
       studentsCanReply: true,
+      sidebarFeatures: true,
     },
   });
   return { updatedClass };