@studious-lms/server 1.22.0 → 1.24.0

package/src/routers/parent.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { createTRPCRouter, protectedProcedure } from "../trpc.js";
+import {
+  getChildAttendance,
+  getChildGrades,
+  linkParentToStudent,
+  listMyChildren,
+  listParentLinks,
+  unlinkParentFromStudent,
+} from "../services/parentPortal.js";
+
+export const parentRouter = createTRPCRouter({
+  linkStudent: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        parentUserId: z.string(),
+        studentUserId: z.string(),
+      })
+    )
+    .mutation(({ ctx, input }) => linkParentToStudent(ctx.user!.id, input)),
+
+  unlinkStudent: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        parentUserId: z.string(),
+        studentUserId: z.string(),
+      })
+    )
+    .mutation(({ ctx, input }) => unlinkParentFromStudent(ctx.user!.id, input)),
+
+  listLinks: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        parentUserId: z.string().optional(),
+        studentUserId: z.string().optional(),
+      })
+    )
+    .query(({ ctx, input }) => listParentLinks(ctx.user!.id, input)),
+
+  listMyChildren: protectedProcedure
+    .input(z.object({ schoolId: z.string() }))
+    .query(({ ctx, input }) => listMyChildren(ctx.user!.id, input.schoolId)),
+
+  getChildAttendance: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        studentUserId: z.string(),
+        classId: z.string().optional(),
+        from: z.date().optional(),
+        to: z.date().optional(),
+      })
+    )
+    .query(({ ctx, input }) => getChildAttendance(ctx.user!.id, input)),
+
+  getChildGrades: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        studentUserId: z.string(),
+        classId: z.string().optional(),
+      })
+    )
+    .query(({ ctx, input }) => getChildGrades(ctx.user!.id, input)),
+});

package/src/routers/school.ts

@@ -7,13 +7,17 @@ import {
 import {
   acceptInvite,
   addMember,
+  bulkRemoveMembers,
+  bulkUpdateMemberRoles,
   confirmSchoolAssetUpload,
   createInvite,
   createSchoolClass,
   createSchoolRecord,
+  deleteSchoolClass,
   getAdminOverview,
   getCurrentSchool,
   getInvite,
+  getMemberDetail,
   getMemberTimeline,
   getSchoolAssetUploadUrl,
   getStudentTimeline,
@@ -24,17 +28,47 @@ import {
   removeMember,
   revokeInvite,
   searchMembers,
+  updateClassMembers,
   updateMemberRole,
   updateSchoolDetails,
 } from "../services/school.js";
 import { getSchoolAiUsage } from "../services/aiUsage.js";
+import {
+  listTodayAttendanceSummary,
+  listStudentAttendanceStats,
+  listExcusals,
+  createExcusal,
+  updateExcusal,
+  revokeExcusal,
+} from "../services/attendance.js";
+import { generateStudentIdCards } from "../services/idCard.js";
+import {
+  generateTranscript,
+  generateTranscripts,
+} from "../services/transcript.js";
+import { importStudentsCsv } from "../services/studentImport.js";
 
-const schoolRoleSchema = z.enum(["ADMIN", "TEACHER", "STUDENT"]);
+const schoolRoleSchema = z.enum([
+  "ADMIN",
+  "TEACHER",
+  "STUDENT",
+  "ACCOUNTANT",
+  "PARENT",
+]);
 
 const schoolIdSchema = z.object({
   schoolId: z.string(),
 });
 
+/** Interim period params until AcademicTerm (C1) exists. */
+const transcriptPeriodSchema = z.object({
+  schoolId: z.string(),
+  from: z.date().optional(),
+  to: z.date().optional(),
+  /** Free-text school year label (e.g. "2082 BS"). Prefer AcademicTerm (C1) later. */
+  schoolYear: z.string().max(64).optional(),
+});
+
 export const schoolRouter = createTRPCRouter({
   getCurrent: protectedProcedure
     .input(z.object({ schoolId: z.string().optional() }).optional())
@@ -61,6 +95,7 @@ export const schoolRouter = createTRPCRouter({
         description: z.string().nullable().optional(),
         subdomain: z.string().nullable().optional(),
         logoId: z.string().nullable().optional(),
+        letterheadFileId: z.string().nullable().optional(),
       })
     )
     .mutation(({ ctx, input }) => updateSchoolDetails(ctx.user!.id, input)),
@@ -143,6 +178,66 @@ export const schoolRouter = createTRPCRouter({
     .input(schoolIdSchema)
     .query(({ ctx, input }) => getAdminOverview(ctx.user!.id, input.schoolId)),
 
+  /** School-admin: today's attendance rollup across classes. */
+  listTodayAttendanceSummary: protectedProcedure
+    .input(schoolIdSchema)
+    .query(({ ctx, input }) =>
+      listTodayAttendanceSummary(ctx.user!.id, input.schoolId)
+    ),
+
+  /** School-admin: per-student attendance counts + % (excused excluded from %). */
+  listStudentAttendanceStats: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        from: z.date().optional(),
+        to: z.date().optional(),
+        studentId: z.string().optional(),
+      })
+    )
+    .query(({ ctx, input }) => listStudentAttendanceStats(ctx.user!.id, input)),
+
+  listExcusals: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        includeRevoked: z.boolean().optional(),
+        studentId: z.string().optional(),
+      })
+    )
+    .query(({ ctx, input }) => listExcusals(ctx.user!.id, input)),
+
+  createExcusal: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        studentIds: z.array(z.string()).min(1),
+        startDate: z.date(),
+        endDate: z.date(),
+        reason: z.string().min(1),
+        note: z.string().nullable().optional(),
+      })
+    )
+    .mutation(({ ctx, input }) => createExcusal(ctx.user!.id, input)),
+
+  updateExcusal: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        excusalId: z.string(),
+        studentIds: z.array(z.string()).min(1).optional(),
+        startDate: z.date().optional(),
+        endDate: z.date().optional(),
+        reason: z.string().min(1).optional(),
+        note: z.string().nullable().optional(),
+      })
+    )
+    .mutation(({ ctx, input }) => updateExcusal(ctx.user!.id, input)),
+
+  revokeExcusal: protectedProcedure
+    .input(z.object({ schoolId: z.string(), excusalId: z.string() }))
+    .mutation(({ ctx, input }) => revokeExcusal(ctx.user!.id, input)),
+
   getAiUsage: protectedProcedure
     .input(
       z.object({
@@ -174,6 +269,23 @@ export const schoolRouter = createTRPCRouter({
     )
     .mutation(({ ctx, input }) => createSchoolClass(ctx.user!.id, input)),
 
+  deleteClass: protectedProcedure
+    .input(z.object({ schoolId: z.string(), classId: z.string() }))
+    .mutation(({ ctx, input }) => deleteSchoolClass(ctx.user!.id, input)),
+
+  updateClassMembers: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        classId: z.string(),
+        addTeacherIds: z.array(z.string()).optional(),
+        removeTeacherIds: z.array(z.string()).optional(),
+        addStudentIds: z.array(z.string()).optional(),
+        removeStudentIds: z.array(z.string()).optional(),
+      })
+    )
+    .mutation(({ ctx, input }) => updateClassMembers(ctx.user!.id, input)),
+
   listMembers: protectedProcedure
     .input(schoolIdSchema)
     .query(({ ctx, input }) => listMembers(ctx.user!.id, input.schoolId)),
@@ -202,6 +314,66 @@ export const schoolRouter = createTRPCRouter({
     .input(z.object({ schoolId: z.string(), memberUserId: z.string() }))
     .mutation(({ ctx, input }) => removeMember(ctx.user!.id, input)),
 
+  getMemberDetail: protectedProcedure
+    .input(z.object({ schoolId: z.string(), memberUserId: z.string() }))
+    .query(({ ctx, input }) => getMemberDetail(ctx.user!.id, input)),
+
+  /**
+   * Generate a branded transcript / progress-report PDF for one student.
+   * School admin only. Uses gradebook + attendance (present/late/absent).
+   * No AcademicTerm yet — pass schoolYear and/or from/to (C1 dependency).
+   */
+  generateTranscript: protectedProcedure
+    .input(
+      transcriptPeriodSchema.extend({
+        studentId: z.string(),
+      })
+    )
+    .mutation(({ ctx, input }) => generateTranscript(ctx.user!.id, input)),
+
+  /**
+   * Bulk generate transcripts for multiple students (max 50).
+   * Returns per-student PDFs plus any per-student errors.
+   */
+  generateTranscripts: protectedProcedure
+    .input(
+      transcriptPeriodSchema.extend({
+        studentIds: z.array(z.string()).min(1).max(50),
+      })
+    )
+    .mutation(({ ctx, input }) => generateTranscripts(ctx.user!.id, input)),
+
+  bulkUpdateMemberRoles: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        memberUserIds: z.array(z.string()).min(1).max(200),
+        role: schoolRoleSchema,
+      })
+    )
+    .mutation(({ ctx, input }) => bulkUpdateMemberRoles(ctx.user!.id, input)),
+
+  bulkRemoveMembers: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        memberUserIds: z.array(z.string()).min(1).max(200),
+      })
+    )
+    .mutation(({ ctx, input }) => bulkRemoveMembers(ctx.user!.id, input)),
+
+  /** Generate a bulk PDF of front-side student ID cards for selected members. */
+  generateIdCards: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        studentUserIds: z.array(z.string()).min(1).max(100),
+      })
+    )
+    .mutation(({ ctx, input }) =>
+      generateStudentIdCards(ctx.user!.id, input)
+    ),
+
   listInvites: protectedProcedure
     .input(schoolIdSchema)
     .query(({ ctx, input }) => listInvites(ctx.user!.id, input.schoolId)),
@@ -232,4 +404,15 @@ export const schoolRouter = createTRPCRouter({
   acceptInvite: protectedProcedure
     .input(z.object({ token: z.string() }))
     .mutation(({ ctx, input }) => acceptInvite(ctx.user!.id, input.token)),
+
+  /** C3: Bulk student CSV onboarding (username/password generated when omitted). */
+  importStudentsCsv: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        csvText: z.string().min(1).max(2_000_000),
+        dryRun: z.boolean().optional(),
+      })
+    )
+    .mutation(({ ctx, input }) => importStudentsCsv(ctx.user!.id, input)),
 });

package/src/routers/worksheet.ts

@@ -33,6 +33,7 @@ import {
   regradeAll,
   gradeAnswer,
   addCommentToResponse,
+  getWorksheetQuestionStats,
 } from "../services/worksheet.js";
 
 const directFileSchema = z.object({
@@ -235,6 +236,7 @@ export const worksheetRouter = createTRPCRouter({
           "ESSAY",
         ]),
         order: z.number().int().min(0).optional(),
+        parentQuestionId: z.string().nullable().optional(),
       })
     )
     .mutation(({ ctx, input }) =>
@@ -246,9 +248,16 @@ export const worksheetRouter = createTRPCRouter({
         markScheme: input.markScheme,
         type: input.type,
         order: input.order,
+        parentQuestionId: input.parentQuestionId,
       })
     ),
 
+  getQuestionStats: protectedProcedure
+    .input(z.object({ worksheetId: z.string() }))
+    .query(({ ctx, input }) =>
+      getWorksheetQuestionStats(input.worksheetId, ctx.user!.id)
+    ),
+
   reorderQuestions: protectedProcedure
     .input(
       z.object({
@@ -288,6 +297,7 @@ export const worksheetRouter = createTRPCRouter({
             "ESSAY",
           ])
           .optional(),
+        parentQuestionId: z.string().nullable().optional(),
       })
     )
     .mutation(({ ctx, input }) =>
@@ -302,6 +312,7 @@ export const worksheetRouter = createTRPCRouter({
           options: input.options,
           markScheme: input.markScheme,
           type: input.type,
+          parentQuestionId: input.parentQuestionId,
         }
       )
     ),

package/src/services/academicCalendar.ts

@@ -0,0 +1,299 @@
+/**
+ * Academic year / term service (C1) + student promotion (C2).
+ */
+import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
+import {
+  createAcademicTerm,
+  createAcademicYear,
+  deleteAcademicTerm,
+  deleteAcademicYear,
+  getAcademicYearById,
+  getCurrentAcademicYear,
+  listAcademicYears,
+  updateAcademicTerm,
+  updateAcademicYear,
+} from "../models/academicCalendar.js";
+import {
+  findActiveSchoolAdminMembership,
+  findSchoolClass,
+  listActiveSchoolMemberships,
+} from "../models/school.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;
+}
+
+export async function listYears(userId: string, schoolId: string) {
+  await requireSchoolAdmin(schoolId, userId);
+  return { years: await listAcademicYears(schoolId) };
+}
+
+export async function getCurrentYear(userId: string, schoolId: string) {
+  await requireSchoolAdmin(schoolId, userId);
+  return { year: await getCurrentAcademicYear(schoolId) };
+}
+
+export async function createYear(
+  userId: string,
+  input: {
+    schoolId: string;
+    name: string;
+    startDate: Date;
+    endDate: Date;
+    isCurrent?: boolean;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  if (input.endDate < input.startDate) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "endDate must be on or after startDate",
+    });
+  }
+  try {
+    const year = await createAcademicYear(input);
+    return { year };
+  } catch (err: unknown) {
+    if (
+      err &&
+      typeof err === "object" &&
+      "code" in err &&
+      (err as { code: string }).code === "P2002"
+    ) {
+      throw new TRPCError({
+        code: "CONFLICT",
+        message: "An academic year with this name already exists",
+      });
+    }
+    throw err;
+  }
+}
+
+export async function updateYear(
+  userId: string,
+  input: {
+    schoolId: string;
+    yearId: string;
+    name?: string;
+    startDate?: Date;
+    endDate?: Date;
+    isCurrent?: boolean;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const year = await updateAcademicYear(input.yearId, input.schoolId, {
+    name: input.name,
+    startDate: input.startDate,
+    endDate: input.endDate,
+    isCurrent: input.isCurrent,
+  });
+  if (!year) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Academic year not found" });
+  }
+  return { year };
+}
+
+export async function removeYear(
+  userId: string,
+  input: { schoolId: string; yearId: string }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const result = await deleteAcademicYear(input.yearId, input.schoolId);
+  if (result.count === 0) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Academic year not found" });
+  }
+  return { ok: true as const };
+}
+
+export async function createTerm(
+  userId: string,
+  input: {
+    schoolId: string;
+    yearId: string;
+    name: string;
+    startDate: Date;
+    endDate: Date;
+    isCurrent?: boolean;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const year = await getAcademicYearById(input.yearId, input.schoolId);
+  if (!year) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Academic year not found" });
+  }
+  if (input.endDate < input.startDate) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "endDate must be on or after startDate",
+    });
+  }
+  try {
+    const term = await createAcademicTerm({
+      academicYearId: input.yearId,
+      name: input.name,
+      startDate: input.startDate,
+      endDate: input.endDate,
+      isCurrent: input.isCurrent,
+    });
+    return { term };
+  } catch (err: unknown) {
+    if (
+      err &&
+      typeof err === "object" &&
+      "code" in err &&
+      (err as { code: string }).code === "P2002"
+    ) {
+      throw new TRPCError({
+        code: "CONFLICT",
+        message: "A term with this name already exists in the year",
+      });
+    }
+    throw err;
+  }
+}
+
+export async function updateTerm(
+  userId: string,
+  input: {
+    schoolId: string;
+    yearId: string;
+    termId: string;
+    name?: string;
+    startDate?: Date;
+    endDate?: Date;
+    isCurrent?: boolean;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const year = await getAcademicYearById(input.yearId, input.schoolId);
+  if (!year) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Academic year not found" });
+  }
+  const term = await updateAcademicTerm(input.termId, input.yearId, {
+    name: input.name,
+    startDate: input.startDate,
+    endDate: input.endDate,
+    isCurrent: input.isCurrent,
+  });
+  if (!term) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Academic term not found" });
+  }
+  return { term };
+}
+
+export async function removeTerm(
+  userId: string,
+  input: { schoolId: string; yearId: string; termId: string }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+  const year = await getAcademicYearById(input.yearId, input.schoolId);
+  if (!year) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Academic year not found" });
+  }
+  const result = await deleteAcademicTerm(input.termId, input.yearId);
+  if (result.count === 0) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Academic term not found" });
+  }
+  return { ok: true as const };
+}
+
+/**
+ * C2: Promote / move students from one class to another (basic rollover).
+ * Disconnects from `fromClassId` and connects to `toClassId`.
+ */
+export async function promoteStudents(
+  userId: string,
+  input: {
+    schoolId: string;
+    fromClassId: string;
+    toClassId: string;
+    studentUserIds: string[];
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+
+  if (input.fromClassId === input.toClassId) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "fromClassId and toClassId must differ",
+    });
+  }
+  if (input.studentUserIds.length === 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Select at least one student",
+    });
+  }
+
+  const [fromClass, toClass] = await Promise.all([
+    findSchoolClass(input.schoolId, input.fromClassId),
+    findSchoolClass(input.schoolId, input.toClassId),
+  ]);
+  if (!fromClass || !toClass) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Source or destination class not found in this school",
+    });
+  }
+
+  const memberships = await listActiveSchoolMemberships(
+    input.schoolId,
+    input.studentUserIds
+  );
+  const studentIds = memberships
+    .filter((m) => m.role === "STUDENT")
+    .map((m) => m.userId);
+  if (studentIds.length === 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "No active student memberships found for the given users",
+    });
+  }
+
+  // Only move students currently enrolled in the source class.
+  const enrolled = await prisma.class.findFirst({
+    where: {
+      id: input.fromClassId,
+      schoolId: input.schoolId,
+    },
+    select: {
+      students: {
+        where: { id: { in: studentIds } },
+        select: { id: true },
+      },
+    },
+  });
+  const moveIds = (enrolled?.students ?? []).map((s) => s.id);
+  if (moveIds.length === 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "None of the selected students are in the source class",
+    });
+  }
+
+  await prisma.$transaction([
+    prisma.class.update({
+      where: { id: input.fromClassId },
+      data: { students: { disconnect: moveIds.map((id) => ({ id })) } },
+    }),
+    prisma.class.update({
+      where: { id: input.toClassId },
+      data: { students: { connect: moveIds.map((id) => ({ id })) } },
+    }),
+  ]);
+
+  return {
+    promotedCount: moveIds.length,
+    studentUserIds: moveIds,
+    fromClassId: input.fromClassId,
+    toClassId: input.toClassId,
+  };
+}