@studious-lms/server 1.22.0 → 1.24.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

@@ -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,
+      }),
+    } 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 };

package/src/services/fees.ts

@@ -0,0 +1,424 @@
+/**
+ * Fee ledger service — school-admin gated monthly invoicing + payment recording.
+ * Payment gateway intentionally deferred; this is a manual ledger.
+ */
+import { TRPCError } from "@trpc/server";
+import { FeeInvoiceStatus, FeePaymentMethod } from "@prisma/client";
+import { findActiveSchoolAdminMembership } from "../models/school.js";
+import {
+  createFeeInvoices,
+  createFeePayment,
+  createFeePlan,
+  getFeeInvoice,
+  getFeePayment,
+  getFeePlan,
+  listActiveStudentIds,
+  listFeeInvoices,
+  listFeePlans,
+  listPlanEnrollmentIds,
+  listStudentBalances,
+  setFeePlanEnrollments,
+  sumPaymentsForInvoice,
+  updateFeePlan,
+  updateInvoiceStatus,
+} from "../models/fees.js";
+import {
+  buildFeePdf,
+  formatNpr,
+  monthLabel,
+} from "../lib/feePdf.js";
+
+async function requireAdmin(schoolId: string, userId: string) {
+  const membership = await findActiveSchoolAdminMembership(schoolId, userId);
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only school admins can manage fees",
+    });
+  }
+  return membership;
+}
+
+function assertMonth(month: number) {
+  if (month < 1 || month > 12) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "month must be between 1 and 12",
+    });
+  }
+}
+
+function invoicePaidTotal(payments: { amountNpr: number }[]): number {
+  return payments.reduce((s, p) => s + p.amountNpr, 0);
+}
+
+function deriveStatus(
+  amountNpr: number,
+  paidNpr: number,
+  current: FeeInvoiceStatus
+): FeeInvoiceStatus {
+  if (current === "VOID") return "VOID";
+  if (paidNpr <= 0) return "UNPAID";
+  if (paidNpr >= amountNpr) return "PAID";
+  return "PARTIAL";
+}
+
+function withBalance<
+  T extends {
+    amountNpr: number;
+    status: FeeInvoiceStatus;
+    payments: { amountNpr: number }[];
+  },
+>(invoice: T) {
+  const paidNpr = invoicePaidTotal(invoice.payments);
+  return {
+    ...invoice,
+    paidNpr,
+    balanceNpr: Math.max(0, invoice.amountNpr - paidNpr),
+  };
+}
+
+export async function listPlans(userId: string, schoolId: string) {
+  await requireAdmin(schoolId, userId);
+  const plans = await listFeePlans(schoolId);
+  return { plans };
+}
+
+export async function getPlan(userId: string, planId: string) {
+  const plan = await getFeePlan(planId);
+  if (!plan) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Fee plan not found" });
+  }
+  await requireAdmin(plan.schoolId, userId);
+  return { plan };
+}
+
+export async function createPlan(
+  userId: string,
+  input: {
+    schoolId: string;
+    name: string;
+    description?: string | null;
+    amountNpr: number;
+    studentIds?: string[];
+  }
+) {
+  await requireAdmin(input.schoolId, userId);
+  if (input.amountNpr <= 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "amountNpr must be positive",
+    });
+  }
+  const plan = await createFeePlan({
+    schoolId: input.schoolId,
+    name: input.name.trim(),
+    description: input.description?.trim() || null,
+    amountNpr: input.amountNpr,
+  });
+  if (input.studentIds?.length) {
+    const updated = await setFeePlanEnrollments(plan.id, input.studentIds);
+    return { plan: updated };
+  }
+  return { plan };
+}
+
+export async function updatePlan(
+  userId: string,
+  input: {
+    planId: string;
+    name?: string;
+    description?: string | null;
+    amountNpr?: number;
+    isActive?: boolean;
+  }
+) {
+  const existing = await getFeePlan(input.planId);
+  if (!existing) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Fee plan not found" });
+  }
+  await requireAdmin(existing.schoolId, userId);
+  if (input.amountNpr != null && input.amountNpr <= 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "amountNpr must be positive",
+    });
+  }
+  const plan = await updateFeePlan(input.planId, {
+    name: input.name?.trim(),
+    description: input.description,
+    amountNpr: input.amountNpr,
+    isActive: input.isActive,
+  });
+  return { plan };
+}
+
+export async function setPlanStudents(
+  userId: string,
+  input: { planId: string; studentIds: string[] }
+) {
+  const existing = await getFeePlan(input.planId);
+  if (!existing) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Fee plan not found" });
+  }
+  await requireAdmin(existing.schoolId, userId);
+  const plan = await setFeePlanEnrollments(input.planId, input.studentIds);
+  return { plan };
+}
+
+export async function generateMonthlyInvoices(
+  userId: string,
+  input: {
+    schoolId: string;
+    feePlanId: string;
+    year: number;
+    month: number;
+    studentIds?: string[];
+    dueDate?: Date | null;
+  }
+) {
+  await requireAdmin(input.schoolId, userId);
+  assertMonth(input.month);
+
+  const plan = await getFeePlan(input.feePlanId);
+  if (!plan || plan.schoolId !== input.schoolId) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Fee plan not found" });
+  }
+  if (!plan.isActive) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Cannot generate invoices for an inactive fee plan",
+    });
+  }
+
+  let studentIds = input.studentIds;
+  if (!studentIds?.length) {
+    const enrolled = await listPlanEnrollmentIds(plan.id);
+    studentIds = enrolled.length
+      ? enrolled
+      : await listActiveStudentIds(input.schoolId);
+  }
+
+  if (!studentIds.length) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "No students to invoice",
+    });
+  }
+
+  const result = await createFeeInvoices(
+    studentIds.map((studentId) => ({
+      schoolId: input.schoolId,
+      feePlanId: plan.id,
+      studentId,
+      year: input.year,
+      month: input.month,
+      amountNpr: plan.amountNpr,
+      currency: plan.currency,
+      dueDate: input.dueDate ?? null,
+    }))
+  );
+
+  const invoices = await listFeeInvoices({
+    schoolId: input.schoolId,
+    feePlanId: plan.id,
+    year: input.year,
+    month: input.month,
+  });
+
+  return {
+    createdCount: result.count,
+    invoices: invoices.map(withBalance),
+  };
+}
+
+export async function listInvoices(
+  userId: string,
+  input: {
+    schoolId: string;
+    year?: number;
+    month?: number;
+    studentId?: string;
+    feePlanId?: string;
+    status?: FeeInvoiceStatus;
+  }
+) {
+  await requireAdmin(input.schoolId, userId);
+  if (input.month != null) assertMonth(input.month);
+  const invoices = await listFeeInvoices(input);
+  return { invoices: invoices.map(withBalance) };
+}
+
+export async function getInvoice(userId: string, invoiceId: string) {
+  const invoice = await getFeeInvoice(invoiceId);
+  if (!invoice) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Invoice not found" });
+  }
+  await requireAdmin(invoice.schoolId, userId);
+  return { invoice: withBalance(invoice) };
+}
+
+export async function recordPayment(
+  userId: string,
+  input: {
+    invoiceId: string;
+    amountNpr: number;
+    method: FeePaymentMethod;
+    reference?: string | null;
+    paidAt?: Date;
+    notes?: string | null;
+  }
+) {
+  const invoice = await getFeeInvoice(input.invoiceId);
+  if (!invoice) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Invoice not found" });
+  }
+  await requireAdmin(invoice.schoolId, userId);
+
+  if (invoice.status === "VOID") {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Cannot record payment on a void invoice",
+    });
+  }
+  if (input.amountNpr <= 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "amountNpr must be positive",
+    });
+  }
+  if (
+    (input.method === "BANK" || input.method === "ESEWA_REF") &&
+    !input.reference?.trim()
+  ) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "reference is required for BANK and ESEWA_REF payments",
+    });
+  }
+
+  const paidSoFar = invoicePaidTotal(invoice.payments);
+  const balance = Math.max(0, invoice.amountNpr - paidSoFar);
+  if (input.amountNpr > balance) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: `Payment exceeds balance (${formatNpr(balance)})`,
+    });
+  }
+
+  const payment = await createFeePayment({
+    schoolId: invoice.schoolId,
+    invoiceId: invoice.id,
+    amountNpr: input.amountNpr,
+    method: input.method,
+    reference: input.reference?.trim() || null,
+    paidAt: input.paidAt,
+    recordedById: userId,
+    notes: input.notes?.trim() || null,
+  });
+
+  const aggregate = await sumPaymentsForInvoice(invoice.id);
+  const newPaid = aggregate._sum.amountNpr ?? 0;
+  const status = deriveStatus(invoice.amountNpr, newPaid, invoice.status);
+  await updateInvoiceStatus(invoice.id, status);
+
+  const refreshed = await getFeeInvoice(invoice.id);
+  return {
+    payment,
+    invoice: refreshed ? withBalance(refreshed) : null,
+  };
+}
+
+export async function listBalances(userId: string, schoolId: string) {
+  await requireAdmin(schoolId, userId);
+  const balances = await listStudentBalances(schoolId);
+  return { balances };
+}
+
+export async function getInvoicePdf(userId: string, invoiceId: string) {
+  const invoice = await getFeeInvoice(invoiceId);
+  if (!invoice) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Invoice not found" });
+  }
+  await requireAdmin(invoice.schoolId, userId);
+
+  const paidNpr = invoicePaidTotal(invoice.payments);
+  const balanceNpr = Math.max(0, invoice.amountNpr - paidNpr);
+  const studentName =
+    invoice.student.profile?.displayName || invoice.student.username;
+
+  const bytes = await buildFeePdf({
+    schoolName: invoice.school.name,
+    title: "Fee Invoice",
+    subtitle: `${invoice.feePlan.name} · ${monthLabel(invoice.year, invoice.month)}`,
+    letterhead: invoice.school.letterhead
+      ? {
+          path: invoice.school.letterhead.path,
+          type: invoice.school.letterhead.type,
+        }
+      : null,
+    lines: [
+      { label: "Invoice ID", value: invoice.id.slice(0, 8).toUpperCase() },
+      { label: "Student", value: studentName },
+      { label: "Period", value: monthLabel(invoice.year, invoice.month) },
+      { label: "Plan", value: invoice.feePlan.name },
+      { label: "Amount", value: formatNpr(invoice.amountNpr) },
+      { label: "Paid", value: formatNpr(paidNpr) },
+      { label: "Balance", value: formatNpr(balanceNpr) },
+      { label: "Status", value: invoice.status },
+    ],
+    footerNote: "Manual ledger — not a gateway receipt. Keep for school records.",
+  });
+
+  return {
+    fileName: `invoice-${invoice.year}-${String(invoice.month).padStart(2, "0")}-${invoice.id.slice(0, 8)}.pdf`,
+    contentType: "application/pdf",
+    base64: Buffer.from(bytes).toString("base64"),
+  };
+}
+
+export async function getReceiptPdf(userId: string, paymentId: string) {
+  const payment = await getFeePayment(paymentId);
+  if (!payment) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Payment not found" });
+  }
+  await requireAdmin(payment.schoolId, userId);
+
+  const invoice = payment.invoice;
+  const studentName =
+    invoice.student.profile?.displayName || invoice.student.username;
+
+  const bytes = await buildFeePdf({
+    schoolName: invoice.school.name,
+    title: "Payment Receipt",
+    subtitle: `${invoice.feePlan.name} · ${monthLabel(invoice.year, invoice.month)}`,
+    letterhead: invoice.school.letterhead
+      ? {
+          path: invoice.school.letterhead.path,
+          type: invoice.school.letterhead.type,
+        }
+      : null,
+    lines: [
+      { label: "Receipt ID", value: payment.id.slice(0, 8).toUpperCase() },
+      { label: "Student", value: studentName },
+      { label: "Period", value: monthLabel(invoice.year, invoice.month) },
+      { label: "Amount paid", value: formatNpr(payment.amountNpr) },
+      { label: "Method", value: payment.method },
+      {
+        label: "Reference",
+        value: payment.reference?.trim() || "—",
+      },
+      {
+        label: "Paid at",
+        value: payment.paidAt.toISOString().slice(0, 10),
+      },
+    ],
+    footerNote: "Manual ledger receipt — gateway integration deferred.",
+  });
+
+  return {
+    fileName: `receipt-${payment.id.slice(0, 8)}.pdf`,
+    contentType: "application/pdf",
+    base64: Buffer.from(bytes).toString("base64"),
+  };
+}