@studious-lms/server 1.23.0 → 1.25.0

package/src/services/fees.ts

@@ -0,0 +1,447 @@
+/**
+ * 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;
+}
+
+async function assertActiveSchoolStudents(
+  schoolId: string,
+  studentIds: string[]
+) {
+  const activeIds = new Set(await listActiveStudentIds(schoolId));
+  const invalid = studentIds.filter((id) => !activeIds.has(id));
+  if (invalid.length > 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "One or more students are not active members of this school",
+    });
+  }
+}
+
+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) {
+    await assertActiveSchoolStudents(input.schoolId, input.studentIds);
+    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);
+  await assertActiveSchoolStudents(existing.schoolId, input.studentIds);
+  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) {
+    await assertActiveSchoolStudents(input.schoolId, studentIds);
+  } else {
+    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: new Intl.DateTimeFormat("en-CA", {
+          timeZone: "Asia/Kathmandu",
+          year: "numeric",
+          month: "2-digit",
+          day: "2-digit",
+        }).format(payment.paidAt),
+      },
+    ],
+    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"),
+  };
+}

package/src/services/feesAuthz.ts

@@ -0,0 +1,73 @@
+/**
+ * C7: Fees authorization stubs for ACCOUNTANT (+ ADMIN).
+ *
+ * A2 owns full fee models; this module only provides reusable gates that
+ * fee routers can call once they land.
+ */
+import { SchoolMembershipRole } from "@prisma/client";
+import { TRPCError } from "@trpc/server";
+import { findActiveSchoolMembership } from "../models/school.js";
+
+const FEE_WRITE_ROLES: SchoolMembershipRole[] = ["ADMIN", "ACCOUNTANT"];
+const FEE_READ_ROLES: SchoolMembershipRole[] = [
+  "ADMIN",
+  "ACCOUNTANT",
+  "TEACHER",
+  "PARENT",
+  "STUDENT",
+];
+
+export async function requireSchoolRoles(
+  schoolId: string,
+  userId: string,
+  allowed: SchoolMembershipRole[],
+  message = "You do not have permission for this action"
+) {
+  const membership = await findActiveSchoolMembership(schoolId, userId);
+  if (!membership || !allowed.includes(membership.role)) {
+    throw new TRPCError({ code: "FORBIDDEN", message });
+  }
+  return membership;
+}
+
+/** Admin or accountant may create/update fee structures and record payments. */
+export async function requireFeeWriteAccess(schoolId: string, userId: string) {
+  return requireSchoolRoles(
+    schoolId,
+    userId,
+    FEE_WRITE_ROLES,
+    "Only school admins or accountants can manage fees"
+  );
+}
+
+/** Broad read access stub — parents/students should be scoped to own records by A2. */
+export async function requireFeeReadAccess(schoolId: string, userId: string) {
+  return requireSchoolRoles(
+    schoolId,
+    userId,
+    FEE_READ_ROLES,
+    "You are not a member of this school"
+  );
+}
+
+export function canManageFees(role: SchoolMembershipRole) {
+  return FEE_WRITE_ROLES.includes(role);
+}
+
+/** Returns capability flags so the client can show/hide fee UI. */
+export async function getFeeCapabilities(userId: string, schoolId: string) {
+  const membership = await findActiveSchoolMembership(schoolId, userId);
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "You are not a member of this school",
+    });
+  }
+  return {
+    role: membership.role,
+    canManageFees: canManageFees(membership.role),
+    canViewFees: FEE_READ_ROLES.includes(membership.role),
+    feesImplemented: true as const,
+    message: "Fee features are available.",
+  };
+}

package/src/services/gradebook.ts

@@ -325,6 +325,76 @@ export async function getComputedGradebook(classId: string, userId: string) {
   };
 }
 
+/**
+ * Compute one student's final grade in a class without teacher-auth filtering.
+ * Used by school-admin transcripts (caller must enforce school admin separately).
+ */
+export async function computeStudentGradeInClass(
+  classId: string,
+  studentId: string
+): Promise<{
+  result: FinalGradeResult;
+  letterGrade: string | null;
+  gradingBoundary: { id: string; name: string | null; structured: string } | null;
+  studentName: string | null;
+} | null> {
+  const [classData, categories, columns] = await Promise.all([
+    findClassForGradebook(classId),
+    findGradeCategoriesByClassId(classId),
+    findCustomGradeColumnsByClassId(classId),
+  ]);
+  if (!classData) return null;
+
+  const student = classData.students.find((s) => s.id === studentId);
+  if (!student) return null;
+
+  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 scores: ScoreInput[] = [];
+  for (const assignment of classData.assignments) {
+    const submission = assignment.submissions.find(
+      (item) => item.studentId === studentId
+    );
+    scores.push({
+      categoryId: assignment.gradeCategoryId,
+      pointsEarned: submission?.gradeReceived ?? null,
+      maxPoints: assignment.maxGrade ?? 0,
+      weight: assignment.weight,
+    });
+  }
+  for (const column of columns) {
+    const entry = column.entries.find((item) => item.studentId === studentId);
+    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 {
+    result,
+    letterGrade,
+    gradingBoundary: boundary,
+    studentName: student.profile?.displayName || student.username,
+  };
+}
+
 // ===== CSV export =====
 
 function escapeCsvCell(value: string): string {