@studious-lms/server 1.23.0 → 1.25.0

package/src/services/attendance.ts

@@ -1,6 +1,7 @@
 /**
- * Attendance service – get and update class attendance records.
- * Auto-creates attendance records for events that don't have them yet.
+ * Attendance service – class attendance + school-admin excusals / stats.
+ * Dual-writes legacy present/late/absent lists and per-student AttendanceRecord.
+ * Active StudentExcusal rows force EXCUSED (locked for teachers).
  */
 import { TRPCError } from "@trpc/server";
 import {
@@ -13,9 +14,52 @@ import {
   createAttendance,
   createAttendanceForEvent,
   updateAttendance,
+  findActiveExcusalsForStudents,
+  listExcusalsForSchool,
+  findExcusalById,
+  createStudentExcusal,
+  updateStudentExcusal,
+  revokeStudentExcusal,
+  applyExcusalToAttendance,
+  clearExcusalLocks,
+  listSchoolStudentMemberships,
+  listAttendanceRecordsForSchoolStudents,
+  listTodaySchoolAttendanceSessions,
+  toDateOnly,
+  startOfUtcDay,
+  endOfUtcDay,
 } from "../models/attendance.js";
+import { findActiveSchoolAdminMembership } from "../models/school.js";
 import { sendToMultiple } from "./notification.js";
 import { logger } from "../utils/logger.js";
+import {
+  buildExcusalLocks,
+  mergeAttendanceUpdateWithLocks,
+  type StudentRef,
+} from "./attendanceMerge.js";
+import {
+  computeAttendancePercentage,
+  emptyAttendanceCounts,
+  tallyAttendanceStatuses,
+} from "./attendanceStats.js";
+
+async function requireSchoolAdmin(schoolId: string, userId: string) {
+  const membership = await findActiveSchoolAdminMembership(schoolId, userId);
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only school admins can perform this action",
+    });
+  }
+  return membership;
+}
+
+function sessionDate(attendance: {
+  date: Date;
+  event?: { startTime: Date } | null;
+}): Date {
+  return attendance.event?.startTime ?? attendance.date;
+}
 
 /** Get attendance for a class (optionally filtered by event). Creates missing records. */
 export async function getAttendance(classId: string, eventId?: string) {
@@ -33,26 +77,127 @@ export async function getAttendance(classId: string, eventId?: string) {
   for (const event of events) {
     const existing = await findAttendanceByEventId(event.id);
     if (!existing) {
+      const locks =
+        classData.schoolId && studentIds.length > 0
+          ? buildExcusalLocks(
+              await findActiveExcusalsForStudents({
+                schoolId: classData.schoolId,
+                studentIds,
+                date: event.startTime,
+              }),
+              studentIds
+            )
+          : [];
+
+      const merged = mergeAttendanceUpdateWithLocks({
+        present: classData.students.map((s) => ({
+          id: s.id,
+          username: s.username,
+        })),
+        late: [],
+        absent: [],
+        locks,
+      });
+
       await createAttendanceForEvent({
         classId,
         eventId: event.id,
-        presentIds: studentIds,
+        date: event.startTime,
+        presentIds: merged.presentIds,
+        lateIds: merged.lateIds,
+        absentIds: merged.absentIds,
+        excusedIds: merged.excusedIds,
+        records: merged.records,
+      });
+    } else if (classData.schoolId && studentIds.length > 0) {
+      // Ensure active excusals are reflected on existing sessions.
+      const locks = buildExcusalLocks(
+        await findActiveExcusalsForStudents({
+          schoolId: classData.schoolId,
+          studentIds,
+          date: event.startTime,
+        }),
+        studentIds
+      );
+      const needsLock = locks.filter((lock) => {
+        const current = existing.records.find((r) => r.studentId === lock.studentId);
+        return !(
+          current?.status === "EXCUSED" &&
+          current.excusedByExcusalId === lock.excusalId
+        );
       });
+      const byExcusal = new Map<string, string[]>();
+      for (const lock of needsLock) {
+        const list = byExcusal.get(lock.excusalId) ?? [];
+        list.push(lock.studentId);
+        byExcusal.set(lock.excusalId, list);
+      }
+      for (const [excusalId, lockedStudentIds] of byExcusal) {
+        await applyExcusalToAttendance({
+          schoolId: classData.schoolId,
+          excusalId,
+          studentIds: lockedStudentIds,
+          startDate: event.startTime,
+          endDate: event.startTime,
+        });
+      }
     }
   }
 
-  return findManyAttendance(classId, eventId);
+  const sessions = await findManyAttendance(classId, eventId);
+  return sessions.map(shapeAttendanceSession);
+}
+
+/** Additive shape: keep present/late/absent; expose excused + lock metadata for UI. */
+function shapeAttendanceSession<
+  T extends {
+    records: Array<{
+      id: string;
+      studentId: string;
+      status: string;
+      note: string | null;
+      excusedByExcusalId: string | null;
+      updatedById: string | null;
+      updatedAt: Date;
+      student: { id: string; username: string };
+      excusedByExcusal: {
+        id: string;
+        reason: string;
+        note: string | null;
+      } | null;
+    }>;
+    present: unknown[];
+    late: unknown[];
+    absent: unknown[];
+  },
+>(session: T) {
+  const records = session.records.map((r) => ({
+    ...r,
+    lockedFromExcusal: Boolean(r.excusedByExcusalId),
+    reason: r.excusedByExcusal?.reason ?? null,
+    excusalNote: r.excusedByExcusal?.note ?? null,
+  }));
+  const excused = records
+    .filter((r) => r.status === "EXCUSED")
+    .map((r) => r.student);
+
+  return {
+    ...session,
+    excused,
+    records,
+  };
 }
 
-/** Update attendance record (present/late/absent). Teacher-only. */
+/** Update attendance record (present/late/absent/excused). Teacher-only. */
 export async function updateAttendanceRecord(
   userId: string,
   classId: string,
   eventId: string | null | undefined,
   attendance: {
-    present: { id: string; username: string }[];
-    late: { id: string; username: string }[];
-    absent: { id: string; username: string }[];
+    present: StudentRef[];
+    late: StudentRef[];
+    absent: StudentRef[];
+    excused?: StudentRef[];
   }
 ) {
   const classData = await findClassWithTeacher(classId, userId);
@@ -64,55 +209,433 @@ export async function updateAttendanceRecord(
   }
 
   const existing = await findAttendanceByClassAndEvent(classId, eventId ?? null);
+  const dateForExcusal = existing
+    ? sessionDate(existing)
+    : new Date();
+
+  const classStudentIds = classData.students.map((s) => s.id);
+  const locks =
+    classData.schoolId && classStudentIds.length > 0
+      ? buildExcusalLocks(
+          await findActiveExcusalsForStudents({
+            schoolId: classData.schoolId,
+            studentIds: classStudentIds,
+            date: dateForExcusal,
+          }),
+          classStudentIds
+        )
+      : [];
+
+  const existingNotes = new Map(
+    (existing?.records ?? []).map((r) => [r.studentId, r.note])
+  );
+
+  const merged = mergeAttendanceUpdateWithLocks({
+    present: attendance.present,
+    late: attendance.late,
+    absent: attendance.absent,
+    excused: attendance.excused,
+    locks,
+    updatedById: userId,
+    existingNotesByStudentId: existingNotes,
+  });
 
-  const presentIds = attendance.present.map((s) => s.id);
-  const lateIds = attendance.late.map((s) => s.id);
-  const absentIds = attendance.absent.map((s) => s.id);
   const previousLateIds = new Set(existing?.late.map((student) => student.id) ?? []);
-  const previousAbsentIds = new Set(existing?.absent.map((student) => student.id) ?? []);
-  const classStudentIds = new Set(classData.students.map((student) => student.id));
+  const previousAbsentIds = new Set(
+    existing?.absent.map((student) => student.id) ?? []
+  );
+  const classStudentIdSet = new Set(classStudentIds);
 
   if (!existing) {
     const created = await createAttendance({
       classId,
       eventId: eventId ?? null,
-      presentIds,
-      lateIds,
-      absentIds,
+      presentIds: merged.presentIds,
+      lateIds: merged.lateIds,
+      absentIds: merged.absentIds,
+      excusedIds: merged.excusedIds,
+      records: merged.records,
+      updatedById: userId,
     });
     await notifyMarkedLateOrAbsent({
       classId,
       className: classData.name,
       eventId: eventId ?? null,
       eventName: created.event?.name ?? null,
-      classStudentIds,
-      lateIds,
-      absentIds,
+      classStudentIds: classStudentIdSet,
+      lateIds: merged.lateIds,
+      absentIds: merged.absentIds,
       previousLateIds,
       previousAbsentIds,
     });
-    return created;
+    return shapeAttendanceSession(created);
   }
 
   const updated = await updateAttendance(existing.id, {
-    presentIds,
-    lateIds,
-    absentIds,
+    presentIds: merged.presentIds,
+    lateIds: merged.lateIds,
+    absentIds: merged.absentIds,
+    records: merged.records,
   });
   await notifyMarkedLateOrAbsent({
     classId,
     className: classData.name,
     eventId: eventId ?? null,
     eventName: existing.event?.name ?? null,
-    classStudentIds,
-    lateIds,
-    absentIds,
+    classStudentIds: classStudentIdSet,
+    lateIds: merged.lateIds,
+    absentIds: merged.absentIds,
     previousLateIds,
     previousAbsentIds,
   });
+  return shapeAttendanceSession(updated);
+}
+
+/**
+ * School-admin: today's attendance rollup across classes.
+ * `percentage` is session-weighted (share of attended class-session records),
+ * not a share of `totalStudents`; a student in six classes contributes six records.
+ */
+export async function listTodayAttendanceSummary(
+  userId: string,
+  schoolId: string
+) {
+  await requireSchoolAdmin(schoolId, userId);
+
+  const today = new Date();
+  const sessions = await listTodaySchoolAttendanceSessions(schoolId, today);
+  const memberships = await listSchoolStudentMemberships(schoolId);
+  const totalStudents = memberships.length;
+
+  const counts = emptyAttendanceCounts();
+  const rows: Array<{
+    attendanceId: string;
+    classId: string;
+    className: string;
+    section: string;
+    subject: string;
+    eventId: string | null;
+    eventName: string | null;
+    date: Date;
+    present: number;
+    late: number;
+    absent: number;
+    excused: number;
+    unmarked: number;
+    classStudentCount: number;
+  }> = [];
+
+  for (const session of sessions) {
+    const tallied = tallyAttendanceStatuses(session.records.map((r) => r.status));
+    counts.present += tallied.present;
+    counts.late += tallied.late;
+    counts.absent += tallied.absent;
+    counts.excused += tallied.excused;
+    const classStudentCount = session.class._count.students;
+    const marked =
+      tallied.present + tallied.late + tallied.absent + tallied.excused;
+    rows.push({
+      attendanceId: session.id,
+      classId: session.classId,
+      className: session.class.name,
+      section: session.class.section,
+      subject: session.class.subject,
+      eventId: session.eventId,
+      eventName: session.event?.name ?? null,
+      date: session.event?.startTime ?? session.date,
+      present: tallied.present,
+      late: tallied.late,
+      absent: tallied.absent,
+      excused: tallied.excused,
+      unmarked: Math.max(0, classStudentCount - marked),
+      classStudentCount,
+    });
+  }
+
+  return {
+    date: toDateOnly(today),
+    totalStudents,
+    totals: counts,
+    percentage: computeAttendancePercentage(counts),
+    sessions: rows,
+  };
+}
+
+/** School-admin: per-student attendance counts + % (excused excluded from %). */
+export async function listStudentAttendanceStats(
+  userId: string,
+  input: {
+    schoolId: string;
+    from?: Date;
+    to?: Date;
+    studentId?: string;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+
+  const memberships = await listSchoolStudentMemberships(input.schoolId);
+  const filtered = input.studentId
+    ? memberships.filter((m) => m.userId === input.studentId)
+    : memberships;
+  const studentIds = filtered.map((m) => m.userId);
+
+  const records = await listAttendanceRecordsForSchoolStudents({
+    schoolId: input.schoolId,
+    studentIds,
+    from: input.from,
+    to: input.to,
+  });
+
+  const byStudent = new Map<string, ReturnType<typeof emptyAttendanceCounts>>();
+  for (const id of studentIds) {
+    byStudent.set(id, emptyAttendanceCounts());
+  }
+  for (const record of records) {
+    const counts = byStudent.get(record.studentId);
+    if (!counts) continue;
+    switch (record.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 filtered.map((membership) => {
+    const counts = byStudent.get(membership.userId) ?? emptyAttendanceCounts();
+    return {
+      studentId: membership.userId,
+      username: membership.user.username,
+      displayName: membership.user.profile?.displayName ?? null,
+      profilePicture: membership.user.profile?.profilePicture ?? null,
+      profilePictureThumbnail:
+        membership.user.profile?.profilePictureThumbnail ?? null,
+      classes: membership.user.studentIn,
+      present: counts.present,
+      late: counts.late,
+      absent: counts.absent,
+      excused: counts.excused,
+      attendancePercentage: computeAttendancePercentage(counts),
+    };
+  });
+}
+
+export async function listExcusals(
+  userId: string,
+  input: {
+    schoolId: string;
+    includeRevoked?: boolean;
+    studentId?: string;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+
+  const excusals = await listExcusalsForSchool(input);
+  const now = toDateOnly(new Date());
+
+  return excusals.map((excusal) => {
+    let status: "ACTIVE" | "UPCOMING" | "EXPIRED" | "REVOKED" = "ACTIVE";
+    if (excusal.revokedAt) {
+      status = "REVOKED";
+    } else if (toDateOnly(excusal.startDate) > now) {
+      status = "UPCOMING";
+    } else if (toDateOnly(excusal.endDate) < now) {
+      status = "EXPIRED";
+    }
+
+    return {
+      id: excusal.id,
+      schoolId: excusal.schoolId,
+      startDate: excusal.startDate,
+      endDate: excusal.endDate,
+      reason: excusal.reason,
+      note: excusal.note,
+      revokedAt: excusal.revokedAt,
+      createdAt: excusal.createdAt,
+      updatedAt: excusal.updatedAt,
+      status,
+      studentIds: excusal.students.map((s) => s.studentId),
+      students: excusal.students.map((s) => ({
+        id: s.student.id,
+        username: s.student.username,
+        displayName: s.student.profile?.displayName ?? null,
+        profilePicture: s.student.profile?.profilePicture ?? null,
+        profilePictureThumbnail:
+          s.student.profile?.profilePictureThumbnail ?? null,
+      })),
+      createdBy: {
+        id: excusal.createdBy.id,
+        username: excusal.createdBy.username,
+        displayName: excusal.createdBy.profile?.displayName ?? null,
+      },
+      revokedBy: excusal.revokedBy
+        ? {
+            id: excusal.revokedBy.id,
+            username: excusal.revokedBy.username,
+            displayName: excusal.revokedBy.profile?.displayName ?? null,
+          }
+        : null,
+    };
+  });
+}
+
+export async function createExcusal(
+  userId: string,
+  input: {
+    schoolId: string;
+    studentIds: string[];
+    startDate: Date;
+    endDate: Date;
+    reason: string;
+    note?: string | null;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+
+  if (toDateOnly(input.endDate) < toDateOnly(input.startDate)) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "endDate must be on or after startDate",
+    });
+  }
+
+  const uniqueStudentIds = [...new Set(input.studentIds)];
+  const memberships = await listSchoolStudentMemberships(input.schoolId);
+  const schoolStudentIds = new Set(memberships.map((m) => m.userId));
+  const invalid = uniqueStudentIds.filter((id) => !schoolStudentIds.has(id));
+  if (invalid.length > 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "One or more students are not active members of this school",
+    });
+  }
+
+  const excusal = await createStudentExcusal({
+    schoolId: input.schoolId,
+    studentIds: uniqueStudentIds,
+    startDate: input.startDate,
+    endDate: input.endDate,
+    reason: input.reason,
+    note: input.note,
+    createdById: userId,
+  });
+
+  await applyExcusalToAttendance({
+    schoolId: input.schoolId,
+    excusalId: excusal.id,
+    studentIds: uniqueStudentIds,
+    startDate: input.startDate,
+    endDate: input.endDate,
+    updatedById: userId,
+  });
+
+  return excusal;
+}
+
+export async function updateExcusal(
+  userId: string,
+  input: {
+    schoolId: string;
+    excusalId: string;
+    studentIds?: string[];
+    startDate?: Date;
+    endDate?: Date;
+    reason?: string;
+    note?: string | null;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+
+  const existing = await findExcusalById(input.excusalId);
+  if (!existing || existing.schoolId !== input.schoolId) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Excusal not found" });
+  }
+  if (existing.revokedAt) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Cannot update a revoked excusal",
+    });
+  }
+
+  const startDate = input.startDate ?? existing.startDate;
+  const endDate = input.endDate ?? existing.endDate;
+  if (toDateOnly(endDate) < toDateOnly(startDate)) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "endDate must be on or after startDate",
+    });
+  }
+
+  let studentIds = input.studentIds
+    ? [...new Set(input.studentIds)]
+    : existing.students.map((s) => s.studentId);
+
+  if (input.studentIds) {
+    const memberships = await listSchoolStudentMemberships(input.schoolId);
+    const schoolStudentIds = new Set(memberships.map((m) => m.userId));
+    const invalid = studentIds.filter((id) => !schoolStudentIds.has(id));
+    if (invalid.length > 0) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "One or more students are not active members of this school",
+      });
+    }
+  }
+
+  // Clear previous locks, then re-apply for the new window/students.
+  await clearExcusalLocks(input.excusalId);
+
+  const updated = await updateStudentExcusal(input.excusalId, {
+    studentIds: input.studentIds ? studentIds : undefined,
+    startDate: input.startDate,
+    endDate: input.endDate,
+    reason: input.reason,
+    note: input.note,
+  });
+
+  await applyExcusalToAttendance({
+    schoolId: input.schoolId,
+    excusalId: updated.id,
+    studentIds,
+    startDate,
+    endDate,
+    updatedById: userId,
+  });
+
   return updated;
 }
 
+export async function revokeExcusal(
+  userId: string,
+  input: { schoolId: string; excusalId: string }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+
+  const existing = await findExcusalById(input.excusalId);
+  if (!existing || existing.schoolId !== input.schoolId) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Excusal not found" });
+  }
+  if (existing.revokedAt) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Excusal is already revoked",
+    });
+  }
+
+  await clearExcusalLocks(input.excusalId);
+  return revokeStudentExcusal(input.excusalId, userId);
+}
+
 /** Notify only students whose late or absent status is newly added. */
 async function notifyMarkedLateOrAbsent(input: {
   classId: string;
@@ -180,3 +703,6 @@ async function sendAttendanceNotification(input: {
     logger.error("Failed to send attendance notifications:", { error });
   }
 }
+
+// Re-export date helpers used by callers/tests.
+export { toDateOnly, startOfUtcDay, endOfUtcDay };