@studious-lms/server 1.23.0 → 1.24.0

package/src/models/attendance.ts

@@ -1,9 +1,26 @@
 /**
- * Attendance model – attendance records, present/late/absent students per event.
+ * Attendance model – session-level lists + per-student AttendanceRecord,
+ * and school-scoped StudentExcusal persistence.
  */
+import { AttendanceStatus, Prisma } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
 import { classTeacherOrSchoolAdminWhere } from "./access.js";
 
+const studentProfileSelect = {
+  id: true,
+  username: true,
+  profile: {
+    select: {
+      displayName: true,
+      profilePicture: true,
+      profilePictureThumbnail: true,
+      bio: true,
+      location: true,
+      website: true,
+    },
+  },
+} as const;
+
 const attendanceInclude = {
   event: {
     select: {
@@ -15,50 +32,27 @@ const attendanceInclude = {
       color: true,
     },
   },
-  present: {
+  present: { select: studentProfileSelect },
+  late: { select: studentProfileSelect },
+  absent: { select: studentProfileSelect },
+  records: {
     select: {
       id: true,
-      username: true,
-      profile: {
-        select: {
-          displayName: true,
-          profilePicture: true,
-          profilePictureThumbnail: true,
-          bio: true,
-          location: true,
-          website: true,
-        },
-      },
-    },
-  },
-  late: {
-    select: {
-      id: true,
-      username: true,
-      profile: {
+      studentId: true,
+      status: true,
+      note: true,
+      excusedByExcusalId: true,
+      updatedById: true,
+      updatedAt: true,
+      student: { select: studentProfileSelect },
+      excusedByExcusal: {
         select: {
-          displayName: true,
-          profilePicture: true,
-          profilePictureThumbnail: true,
-          bio: true,
-          location: true,
-          website: true,
-        },
-      },
-    },
-  },
-  absent: {
-    select: {
-      id: true,
-      username: true,
-      profile: {
-        select: {
-          displayName: true,
-          profilePicture: true,
-          profilePictureThumbnail: true,
-          bio: true,
-          location: true,
-          website: true,
+          id: true,
+          reason: true,
+          note: true,
+          startDate: true,
+          endDate: true,
+          revokedAt: true,
         },
       },
     },
@@ -78,15 +72,28 @@ const attendanceUpdateInclude = {
   present: { select: { id: true, username: true } },
   late: { select: { id: true, username: true } },
   absent: { select: { id: true, username: true } },
+  records: {
+    select: {
+      id: true,
+      studentId: true,
+      status: true,
+      note: true,
+      excusedByExcusalId: true,
+      updatedById: true,
+      updatedAt: true,
+      student: { select: { id: true, username: true } },
+      excusedByExcusal: {
+        select: { id: true, reason: true, note: true },
+      },
+    },
+  },
 } as const;
 
-/** @returns Class with students for attendance. */
-export function findClassWithStudents(classId: string) {
-  return prisma.class.findUnique({
-    where: { id: classId },
+const excusalInclude = {
+  students: {
     select: {
-      id: true,
-      students: {
+      studentId: true,
+      student: {
         select: {
           id: true,
           username: true,
@@ -95,14 +102,39 @@ export function findClassWithStudents(classId: string) {
               displayName: true,
               profilePicture: true,
               profilePictureThumbnail: true,
-              bio: true,
-              location: true,
-              website: true,
             },
           },
         },
       },
     },
+  },
+  createdBy: {
+    select: {
+      id: true,
+      username: true,
+      profile: { select: { displayName: true } },
+    },
+  },
+  revokedBy: {
+    select: {
+      id: true,
+      username: true,
+      profile: { select: { displayName: true } },
+    },
+  },
+} as const;
+
+/** @returns Class with students for attendance. */
+export function findClassWithStudents(classId: string) {
+  return prisma.class.findUnique({
+    where: { id: classId },
+    select: {
+      id: true,
+      schoolId: true,
+      students: {
+        select: studentProfileSelect,
+      },
+    },
   });
 }
 
@@ -116,6 +148,7 @@ export function findClassWithTeacher(classId: string, teacherId: string) {
     select: {
       id: true,
       name: true,
+      schoolId: true,
       students: { select: { id: true } },
     },
   });
@@ -132,6 +165,15 @@ export function findEventsByClassId(classId: string) {
 export function findAttendanceByEventId(eventId: string) {
   return prisma.attendance.findFirst({
     where: { eventId },
+    include: {
+      records: {
+        select: {
+          studentId: true,
+          status: true,
+          excusedByExcusalId: true,
+        },
+      },
+    },
   });
 }
 
@@ -147,10 +189,19 @@ export function findAttendanceByClassAndEvent(classId: string, eventId: string |
         select: {
           id: true,
           name: true,
+          startTime: true,
         },
       },
       late: { select: { id: true } },
       absent: { select: { id: true } },
+      records: {
+        select: {
+          studentId: true,
+          status: true,
+          excusedByExcusalId: true,
+          note: true,
+        },
+      },
     },
   });
 }
@@ -167,26 +218,60 @@ export function findManyAttendance(classId: string, eventId?: string) {
   });
 }
 
-/** Create an attendance record. */
+/** Create an attendance session with legacy lists + per-student records. */
 export function createAttendance(data: {
   classId: string;
   eventId?: string | null;
+  date?: Date;
   presentIds: string[];
   lateIds?: string[];
   absentIds?: string[];
+  excusedIds?: string[];
+  records?: Array<{
+    studentId: string;
+    status: AttendanceStatus;
+    note?: string | null;
+    excusedByExcusalId?: string | null;
+    updatedById?: string | null;
+  }>;
+  updatedById?: string | null;
 }) {
+  const lateIds = data.lateIds ?? [];
+  const absentIds = data.absentIds ?? [];
+  const excusedIds = data.excusedIds ?? [];
+  const records: Array<{
+    studentId: string;
+    status: AttendanceStatus;
+    note?: string | null;
+    excusedByExcusalId?: string | null;
+    updatedById?: string | null;
+  }> =
+    data.records ??
+    buildRecordsFromLists({
+      presentIds: data.presentIds,
+      lateIds,
+      absentIds,
+      excusedIds,
+      updatedById: data.updatedById,
+    });
+
   return prisma.attendance.create({
     data: {
       classId: data.classId,
       eventId: data.eventId ?? undefined,
-      date: new Date(),
+      date: data.date ?? new Date(),
       present: { connect: data.presentIds.map((id) => ({ id })) },
-      late: data.lateIds?.length
-        ? { connect: data.lateIds.map((id) => ({ id })) }
-        : undefined,
-      absent: data.absentIds?.length
-        ? { connect: data.absentIds.map((id) => ({ id })) }
-        : undefined,
+      late: lateIds.length ? { connect: lateIds.map((id) => ({ id })) } : undefined,
+      absent: absentIds.length ? { connect: absentIds.map((id) => ({ id })) } : undefined,
+      records: {
+        create: records.map((record) => ({
+          studentId: record.studentId,
+          status: record.status,
+          note: record.note ?? undefined,
+          excusedByExcusalId: record.excusedByExcusalId ?? undefined,
+          updatedById: record.updatedById ?? data.updatedById ?? undefined,
+        })),
+      },
     },
     include: attendanceUpdateInclude,
   });
@@ -196,29 +281,575 @@ export function createAttendance(data: {
 export function createAttendanceForEvent(data: {
   classId: string;
   eventId: string;
+  date?: Date;
   presentIds: string[];
+  lateIds?: string[];
+  absentIds?: string[];
+  excusedIds?: string[];
+  records?: Array<{
+    studentId: string;
+    status: AttendanceStatus;
+    note?: string | null;
+    excusedByExcusalId?: string | null;
+    updatedById?: string | null;
+  }>;
 }) {
-  return prisma.attendance.create({
+  return createAttendance({
+    classId: data.classId,
+    eventId: data.eventId,
+    date: data.date,
+    presentIds: data.presentIds,
+    lateIds: data.lateIds,
+    absentIds: data.absentIds,
+    excusedIds: data.excusedIds,
+    records: data.records,
+  });
+}
+
+/** Update attendance present/late/absent lists and sync per-student records. */
+export async function updateAttendance(
+  id: string,
+  data: {
+    presentIds: string[];
+    lateIds: string[];
+    absentIds: string[];
+    records: Array<{
+      studentId: string;
+      status: AttendanceStatus;
+      note?: string | null;
+      excusedByExcusalId?: string | null;
+      updatedById?: string | null;
+    }>;
+  }
+) {
+  const studentIds = data.records.map((r) => r.studentId);
+
+  return prisma.$transaction(async (tx) => {
+    // Replace per-student rows for students in this update set.
+    await tx.attendanceRecord.deleteMany({
+      where: {
+        attendanceId: id,
+        studentId: { in: studentIds },
+      },
+    });
+
+    if (data.records.length > 0) {
+      await tx.attendanceRecord.createMany({
+        data: data.records.map((record) => ({
+          attendanceId: id,
+          studentId: record.studentId,
+          status: record.status,
+          note: record.note ?? null,
+          excusedByExcusalId: record.excusedByExcusalId ?? null,
+          updatedById: record.updatedById ?? null,
+        })),
+      });
+    }
+
+    return tx.attendance.update({
+      where: { id },
+      data: {
+        present: { set: data.presentIds.map((id) => ({ id })) },
+        late: { set: data.lateIds.map((id) => ({ id })) },
+        absent: { set: data.absentIds.map((id) => ({ id })) },
+      },
+      include: attendanceUpdateInclude,
+    });
+  });
+}
+
+function buildRecordsFromLists(input: {
+  presentIds: string[];
+  lateIds: string[];
+  absentIds: string[];
+  excusedIds: string[];
+  updatedById?: string | null;
+}) {
+  const records: Array<{
+    studentId: string;
+    status: AttendanceStatus;
+    updatedById?: string | null;
+  }> = [];
+  for (const studentId of input.presentIds) {
+    records.push({ studentId, status: "PRESENT", updatedById: input.updatedById });
+  }
+  for (const studentId of input.lateIds) {
+    records.push({ studentId, status: "LATE", updatedById: input.updatedById });
+  }
+  for (const studentId of input.absentIds) {
+    records.push({ studentId, status: "ABSENT", updatedById: input.updatedById });
+  }
+  for (const studentId of input.excusedIds) {
+    records.push({ studentId, status: "EXCUSED", updatedById: input.updatedById });
+  }
+  return records;
+}
+
+/** Active (non-revoked) excusals covering a calendar date for given students. */
+export function findActiveExcusalsForStudents(input: {
+  schoolId: string;
+  studentIds: string[];
+  date: Date;
+}) {
+  if (input.studentIds.length === 0) {
+    return Promise.resolve([]);
+  }
+
+  const day = toDateOnly(input.date);
+
+  return prisma.studentExcusal.findMany({
+    where: {
+      schoolId: input.schoolId,
+      revokedAt: null,
+      startDate: { lte: day },
+      endDate: { gte: day },
+      students: { some: { studentId: { in: input.studentIds } } },
+    },
+    include: {
+      students: { select: { studentId: true } },
+    },
+  });
+}
+
+/** Active excusals overlapping a date range for school students. */
+export function findActiveExcusalsInRange(input: {
+  schoolId: string;
+  studentIds?: string[];
+  startDate: Date;
+  endDate: Date;
+}) {
+  const start = toDateOnly(input.startDate);
+  const end = toDateOnly(input.endDate);
+
+  return prisma.studentExcusal.findMany({
+    where: {
+      schoolId: input.schoolId,
+      revokedAt: null,
+      startDate: { lte: end },
+      endDate: { gte: start },
+      ...(input.studentIds?.length
+        ? { students: { some: { studentId: { in: input.studentIds } } } }
+        : {}),
+    },
+    include: {
+      students: { select: { studentId: true } },
+    },
+  });
+}
+
+export function listExcusalsForSchool(input: {
+  schoolId: string;
+  includeRevoked?: boolean;
+  studentId?: string;
+}) {
+  return prisma.studentExcusal.findMany({
+    where: {
+      schoolId: input.schoolId,
+      ...(input.includeRevoked ? {} : { revokedAt: null }),
+      ...(input.studentId
+        ? { students: { some: { studentId: input.studentId } } }
+        : {}),
+    },
+    include: excusalInclude,
+    orderBy: [{ startDate: "desc" }, { createdAt: "desc" }],
+  });
+}
+
+export function findExcusalById(excusalId: string) {
+  return prisma.studentExcusal.findUnique({
+    where: { id: excusalId },
+    include: {
+      ...excusalInclude,
+      students: { select: { studentId: true } },
+    },
+  });
+}
+
+export function createStudentExcusal(data: {
+  schoolId: string;
+  studentIds: string[];
+  startDate: Date;
+  endDate: Date;
+  reason: string;
+  note?: string | null;
+  createdById: string;
+}) {
+  return prisma.studentExcusal.create({
     data: {
-      class: { connect: { id: data.classId } },
-      event: { connect: { id: data.eventId } },
-      present: { connect: data.presentIds.map((id) => ({ id })) },
+      schoolId: data.schoolId,
+      startDate: toDateOnly(data.startDate),
+      endDate: toDateOnly(data.endDate),
+      reason: data.reason,
+      note: data.note ?? null,
+      createdById: data.createdById,
+      students: {
+        create: data.studentIds.map((studentId) => ({ studentId })),
+      },
     },
+    include: excusalInclude,
   });
 }
 
-/** Update attendance present/late/absent lists. */
-export function updateAttendance(
-  id: string,
-  data: { presentIds: string[]; lateIds: string[]; absentIds: string[] }
+export function updateStudentExcusal(
+  excusalId: string,
+  data: {
+    studentIds?: string[];
+    startDate?: Date;
+    endDate?: Date;
+    reason?: string;
+    note?: string | null;
+  }
 ) {
-  return prisma.attendance.update({
-    where: { id },
+  return prisma.$transaction(async (tx) => {
+    if (data.studentIds) {
+      await tx.studentExcusalStudent.deleteMany({ where: { excusalId } });
+      await tx.studentExcusalStudent.createMany({
+        data: data.studentIds.map((studentId) => ({ excusalId, studentId })),
+      });
+    }
+
+    return tx.studentExcusal.update({
+      where: { id: excusalId },
+      data: {
+        ...(data.startDate !== undefined
+          ? { startDate: toDateOnly(data.startDate) }
+          : {}),
+        ...(data.endDate !== undefined ? { endDate: toDateOnly(data.endDate) } : {}),
+        ...(data.reason !== undefined ? { reason: data.reason } : {}),
+        ...(data.note !== undefined ? { note: data.note } : {}),
+      },
+      include: excusalInclude,
+    });
+  });
+}
+
+export function revokeStudentExcusal(excusalId: string, revokedById: string) {
+  return prisma.studentExcusal.update({
+    where: { id: excusalId },
     data: {
-      present: { set: data.presentIds.map((id) => ({ id })) },
-      late: { set: data.lateIds.map((id) => ({ id })) },
-      absent: { set: data.absentIds.map((id) => ({ id })) },
+      revokedAt: new Date(),
+      revokedById,
     },
-    include: attendanceUpdateInclude,
+    include: excusalInclude,
+  });
+}
+
+/** Apply EXCUSED status for an excusal across matching class attendance sessions. */
+export async function applyExcusalToAttendance(input: {
+  schoolId: string;
+  excusalId: string;
+  studentIds: string[];
+  startDate: Date;
+  endDate: Date;
+  updatedById?: string | null;
+}) {
+  if (input.studentIds.length === 0) {
+    return { sessionsTouched: 0, recordsUpserted: 0 };
+  }
+
+  const start = startOfUtcDay(input.startDate);
+  const end = endOfUtcDay(input.endDate);
+
+  const events = await prisma.event.findMany({
+    where: {
+      class: {
+        schoolId: input.schoolId,
+        students: { some: { id: { in: input.studentIds } } },
+      },
+      startTime: { gte: start, lte: end },
+    },
+    select: {
+      id: true,
+      classId: true,
+      startTime: true,
+      class: {
+        select: {
+          id: true,
+          students: {
+            where: { id: { in: input.studentIds } },
+            select: { id: true },
+          },
+        },
+      },
+    },
+  });
+
+  let sessionsTouched = 0;
+  let recordsUpserted = 0;
+
+  for (const event of events) {
+    if (!event.classId || !event.class) continue;
+    const classStudentIds = event.class.students.map((s) => s.id);
+    if (classStudentIds.length === 0) continue;
+
+    let attendance = await prisma.attendance.findFirst({
+      where: { classId: event.classId, eventId: event.id },
+      include: {
+        present: { select: { id: true } },
+        late: { select: { id: true } },
+        absent: { select: { id: true } },
+        records: {
+          select: {
+            studentId: true,
+            status: true,
+            excusedByExcusalId: true,
+            note: true,
+          },
+        },
+      },
+    });
+
+    if (!attendance) {
+      // Default everyone present, then override excused students.
+      const allStudentIds = await prisma.class
+        .findUnique({
+          where: { id: event.classId },
+          select: { students: { select: { id: true } } },
+        })
+        .then((c) => c?.students.map((s) => s.id) ?? []);
+
+      const excusedSet = new Set(classStudentIds);
+      const presentIds = allStudentIds.filter((id) => !excusedSet.has(id));
+
+      attendance = await createAttendance({
+        classId: event.classId,
+        eventId: event.id,
+        date: event.startTime,
+        presentIds,
+        lateIds: [],
+        absentIds: [],
+        records: [
+          ...presentIds.map((studentId) => ({
+            studentId,
+            status: "PRESENT" as const,
+            updatedById: input.updatedById,
+          })),
+          ...classStudentIds.map((studentId) => ({
+            studentId,
+            status: "EXCUSED" as const,
+            note: null,
+            excusedByExcusalId: input.excusalId,
+            updatedById: input.updatedById,
+          })),
+        ],
+      });
+      sessionsTouched += 1;
+      recordsUpserted += classStudentIds.length;
+      continue;
+    }
+
+    const presentIds = attendance.present
+      .map((s) => s.id)
+      .filter((id) => !classStudentIds.includes(id));
+    const lateIds = attendance.late
+      .map((s) => s.id)
+      .filter((id) => !classStudentIds.includes(id));
+    const absentIds = attendance.absent
+      .map((s) => s.id)
+      .filter((id) => !classStudentIds.includes(id));
+
+    const recordByStudent = new Map(
+      attendance.records.map((r) => [r.studentId, r])
+    );
+    const nextRecords: Array<{
+      studentId: string;
+      status: AttendanceStatus;
+      note?: string | null;
+      excusedByExcusalId?: string | null;
+      updatedById?: string | null;
+    }> = [];
+
+    for (const [studentId, existing] of recordByStudent) {
+      if (classStudentIds.includes(studentId)) {
+        nextRecords.push({
+          studentId,
+          status: "EXCUSED",
+          note: existing.note,
+          excusedByExcusalId: input.excusalId,
+          updatedById: input.updatedById,
+        });
+      } else {
+        nextRecords.push({
+          studentId,
+          status: existing.status,
+          note: existing.note,
+          excusedByExcusalId: existing.excusedByExcusalId,
+        });
+      }
+    }
+
+    for (const studentId of classStudentIds) {
+      if (!recordByStudent.has(studentId)) {
+        nextRecords.push({
+          studentId,
+          status: "EXCUSED",
+          excusedByExcusalId: input.excusalId,
+          updatedById: input.updatedById,
+        });
+      }
+    }
+
+    await updateAttendance(attendance.id, {
+      presentIds,
+      lateIds,
+      absentIds,
+      records: nextRecords,
+    });
+    sessionsTouched += 1;
+    recordsUpserted += classStudentIds.length;
+  }
+
+  return { sessionsTouched, recordsUpserted };
+}
+
+/** Clear EXCUSED locks tied to a revoked/updated excusal (leave status EXCUSED unless cleared). */
+export async function clearExcusalLocks(excusalId: string) {
+  return prisma.attendanceRecord.updateMany({
+    where: { excusedByExcusalId: excusalId },
+    data: { excusedByExcusalId: null },
+  });
+}
+
+export function listSchoolStudentMemberships(schoolId: string) {
+  return prisma.schoolMembership.findMany({
+    where: {
+      schoolId,
+      role: "STUDENT",
+      status: "ACTIVE",
+    },
+    select: {
+      userId: true,
+      user: {
+        select: {
+          id: true,
+          username: true,
+          profile: {
+            select: {
+              displayName: true,
+              profilePicture: true,
+              profilePictureThumbnail: true,
+            },
+          },
+          studentIn: {
+            where: { schoolId },
+            select: { id: true, name: true, section: true, subject: true },
+          },
+        },
+      },
+    },
+    orderBy: { createdAt: "asc" },
+  });
+}
+
+export function listAttendanceRecordsForSchoolStudents(input: {
+  schoolId: string;
+  studentIds: string[];
+  from?: Date;
+  to?: Date;
+}) {
+  if (input.studentIds.length === 0) {
+    return Promise.resolve([]);
+  }
+
+  return prisma.attendanceRecord.findMany({
+    where: {
+      studentId: { in: input.studentIds },
+      attendance: {
+        class: { schoolId: input.schoolId },
+        ...(input.from || input.to
+          ? {
+              date: {
+                ...(input.from ? { gte: input.from } : {}),
+                ...(input.to ? { lte: input.to } : {}),
+              },
+            }
+          : {}),
+      },
+    },
+    select: {
+      studentId: true,
+      status: true,
+      attendance: {
+        select: {
+          id: true,
+          date: true,
+          classId: true,
+          eventId: true,
+          class: { select: { id: true, name: true } },
+          event: { select: { id: true, name: true, startTime: true } },
+        },
+      },
+    },
+  });
+}
+
+export function listTodaySchoolAttendanceSessions(schoolId: string, day: Date) {
+  const start = startOfUtcDay(day);
+  const end = endOfUtcDay(day);
+
+  return prisma.attendance.findMany({
+    where: {
+      class: { schoolId },
+      OR: [
+        { date: { gte: start, lte: end } },
+        { event: { startTime: { gte: start, lte: end } } },
+      ],
+    },
+    select: {
+      id: true,
+      date: true,
+      classId: true,
+      eventId: true,
+      class: {
+        select: {
+          id: true,
+          name: true,
+          section: true,
+          subject: true,
+          _count: { select: { students: true } },
+        },
+      },
+      event: {
+        select: { id: true, name: true, startTime: true, endTime: true },
+      },
+      records: {
+        select: {
+          studentId: true,
+          status: true,
+        },
+      },
+    },
+    orderBy: { date: "asc" },
   });
 }
+
+export function toDateOnly(date: Date): Date {
+  return new Date(
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
+  );
+}
+
+export function startOfUtcDay(date: Date): Date {
+  return new Date(
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), 0, 0, 0, 0)
+  );
+}
+
+export function endOfUtcDay(date: Date): Date {
+  return new Date(
+    Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+      23,
+      59,
+      59,
+      999
+    )
+  );
+}
+
+export type { AttendanceStatus };
+export type AttendanceIncludeResult = Prisma.AttendanceGetPayload<{
+  include: typeof attendanceInclude;
+}>;