@studious-lms/server 1.4.9 → 1.6.0

package/src/pipelines/gradeWorksheet.ts

@@ -2,7 +2,7 @@
  * Grade worksheet pipeline – AI-powered grading of worksheet responses.
  * Grades questions via inference API, broadcasts status via Pusher (pending/completed/failed/cancelled).
  */
-import { GenerationStatus, WorksheetQuestionType } from "@prisma/client";
+import { JobStatus, WorksheetQuestionType } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
 import { logger } from "../utils/logger.js";
 import z from "zod";
@@ -113,11 +113,11 @@ const gradeWorksheetQuestion = async (worksheetResponseId: string, worksheetQues
         const updatedStudentQuestionProgress = await prisma.studentQuestionProgress.update({
             where: { id: studentQuestionProgress.id, status: {
                 not: {
-                    in: ['CANCELLED'],
+                    in: [JobStatus.CANCELLED],
                 },
             } },
             data: {
-                status: GenerationStatus.COMPLETED,
+                status: JobStatus.COMPLETED,
                 isCorrect: (apiResponse as { isCorrect: boolean }).isCorrect,
                 points: (apiResponse as { points: number }).points,
                 markschemeState: (apiResponse as {
@@ -143,13 +143,23 @@ const gradeWorksheetQuestion = async (worksheetResponseId: string, worksheetQues
         return updatedStudentQuestionProgress;
     } catch (error) {
         logger.error('Failed to grade worksheet response', { error, worksheetResponseId });
+        const { count } = await prisma.studentQuestionProgress.updateMany({
+            where: {
+                id: studentQuestionProgress.id,
+                status: { not: JobStatus.CANCELLED },
+            },
+            data: { status: JobStatus.FAILED },
+        });
+        if (count === 0) {
+            logger.info('Skipping failed status update for cancelled worksheet question', {
+                worksheetResponseId,
+                worksheetQuestionProgressId,
+            });
+            return;
+        }
         pusher.trigger(worksheetChannel(worksheetResponse.id), `set-failed`, {
             id: studentQuestionProgress.id,
         });
-        await prisma.studentQuestionProgress.update({
-            where: { id: studentQuestionProgress.id },
-            data: { status: GenerationStatus.FAILED },
-        });
         throw error;
     }
 }
@@ -160,7 +170,7 @@ const gradeWorksheetQuestion = async (worksheetResponseId: string, worksheetQues
  * @returns updated worksheet response
  */
 
-const DO_NOT_INFERENCE_STATUSES = [GenerationStatus.CANCELLED, GenerationStatus.PENDING, GenerationStatus.COMPLETED];
+const DO_NOT_INFERENCE_STATUSES = [JobStatus.CANCELLED, JobStatus.PENDING, JobStatus.COMPLETED];
 
 export const gradeWorksheetPipeline = async (worksheetResponseId: string) => {
     logger.info('Grading worksheet response', { worksheetResponseId });
@@ -200,17 +210,20 @@ export const gradeWorksheetPipeline = async (worksheetResponseId: string) => {
     for (const response of worksheetResponse.responses) {
         logger.info('Grading question', { questionId: response.questionId });
 
-        const studentQuestionProgress = await prisma.studentQuestionProgress.update({
-            where: { id: response.id, status: {
-                not: {
-                    in: DO_NOT_INFERENCE_STATUSES,
-                }
-            } },
-            data: { status: GenerationStatus.PENDING },
+        const { count } = await prisma.studentQuestionProgress.updateMany({
+            where: {
+                id: response.id,
+                status: {
+                    not: {
+                        in: DO_NOT_INFERENCE_STATUSES,
+                    },
+                },
+            },
+            data: { status: JobStatus.PENDING },
         });
 
-        if (studentQuestionProgress.status !== GenerationStatus.PENDING) {
-            return;
+        if (count === 0) {
+            continue;
         }
 
         await gradeWorksheetQuestion(worksheetResponseId, response.id);
@@ -233,7 +246,7 @@ export const cancelGradePipeline = async (worksheetResponseId: string, worksheet
     }
     const updatedStudentQuestionProgress = await prisma.studentQuestionProgress.update({
         where: { id: worksheetQuestionProgressId },
-        data: { status: GenerationStatus.CANCELLED },
+        data: { status: JobStatus.CANCELLED },
     });
 
     await removeAllPreviousAIComments(worksheetQuestionProgressId);
@@ -255,26 +268,51 @@ export const regradeWorksheetPipeline = async (worksheetResponseId: string, work
         },
     });
     
-    await removeAllPreviousAIComments(worksheetQuestionProgressId);
-
     if (!worksheetResponse) {
         logger.error('Worksheet response not found');
         throw new Error('Worksheet response not found');
     }
 
-    const updatedStudentQuestionProgress = await prisma.studentQuestionProgress.update({
+    const { count } = await prisma.studentQuestionProgress.updateMany({
+        where: {
+            id: worksheetQuestionProgressId,
+            status: { not: JobStatus.CANCELLED },
+        },
+        data: { status: JobStatus.PENDING },
+    });
+
+    if (count === 0) {
+        logger.info('Skipping regrade for cancelled worksheet question', {
+            worksheetResponseId,
+            worksheetQuestionProgressId,
+        });
+        return null;
+    }
+
+    const updatedStudentQuestionProgress = await prisma.studentQuestionProgress.findUnique({
         where: { id: worksheetQuestionProgressId },
-        data: { status: GenerationStatus.PENDING },
     });
 
+    await removeAllPreviousAIComments(worksheetQuestionProgressId);
+
     await gradeWorksheetQuestion(worksheetResponseId, worksheetQuestionProgressId);
 
     return updatedStudentQuestionProgress;
     } catch (error) {
-        await prisma.studentQuestionProgress.update({
-            where: { id: worksheetQuestionProgressId },
-            data: { status: GenerationStatus.FAILED },
+        const { count } = await prisma.studentQuestionProgress.updateMany({
+            where: {
+                id: worksheetQuestionProgressId,
+                status: { not: JobStatus.CANCELLED },
+            },
+            data: { status: JobStatus.FAILED },
         });
+        if (count === 0) {
+            logger.info('Skipping failed status update for cancelled worksheet question regrade', {
+                worksheetResponseId,
+                worksheetQuestionProgressId,
+            });
+            return null;
+        }
         const worksheetResponse = await prisma.studentWorksheetResponse.findUnique({
             where: { id: worksheetResponseId, },
             include: {

package/src/pipelines/pdfToWorksheet.ts

@@ -1,12 +1,25 @@
 /**
  * PDF URL → worksheet: send a remote PDF URL to structured inference,
  * then persist a Worksheet and WorksheetQuestion rows.
+ *
+ * Normally driven by a BullMQ worker, so the producer (e.g.
+ * `createWorksheetFromUploadedPdf`) creates a placeholder Worksheet row up
+ * front and passes its id in via `worksheetId`. The pipeline broadcasts
+ * `Worksheet.status` transitions on the per-worksheet job Pusher channel
+ * (`set-pending` / `set-completed` / `set-failed` / `set-cancelled`) — same
+ * convention as `gradeWorksheet`.
+ *
+ * The legacy `pdfToWorksheet(gcsUrl, classId)` signature is preserved for
+ * direct/synchronous callers (such as tests): when no `worksheetId` is
+ * supplied the pipeline creates the row itself.
  */
 import { z } from "zod";
 import type { ResponseInput } from "openai/resources/responses/responses.js";
+import { JobStatus, Prisma } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
 import { inference } from "../utils/inference.js";
 import { logger } from "../utils/logger.js";
+import { pusher, worksheetJobChannel } from "../lib/pusher.js";
 
 /** Restrict remote fetches to Google-hosted object URLs. */
 function isProbablyGoogleCloudUrl(url: string): boolean {
@@ -41,6 +54,61 @@ function sanitizeUrlForLogs(url: string): string {
   }
 }
 
+/**
+ * Pusher event names mirror `gradeWorksheet`'s convention so clients can
+ * share the same JobStatus → event-name mapping.
+ */
+const STATUS_EVENT_NAMES: Record<JobStatus, string> = {
+  NOT_STARTED: 'set-not-started',
+  PENDING: 'set-pending',
+  COMPLETED: 'set-completed',
+  FAILED: 'set-failed',
+  CANCELLED: 'set-cancelled',
+};
+
+/**
+ * Realtime payload for the per-worksheet job channel.
+ *
+ * On COMPLETED we ship the new title and question count so clients can
+ * patch their card optimistically and side-step replica lag on the next
+ * refetch. Error strings are intentionally NOT broadcast — they may carry
+ * server internals; the full error stays on `RunJob.error` for ops only.
+ */
+export interface WorksheetJobStatusEvent {
+  worksheetId: string;
+  status: JobStatus;
+  /** Filled on COMPLETED so clients can avoid a replica-lagged refetch. */
+  name?: string;
+  questionCount?: number;
+}
+
+/**
+ * Fire-and-forget broadcast of a `Worksheet.status` transition. We never let
+ * a Pusher outage break the actual pipeline: the persisted `Worksheet.status`
+ * is the source of truth, the channel just nudges clients.
+ */
+async function emitStatus(
+  worksheetId: string | undefined,
+  status: JobStatus,
+  extras: Pick<WorksheetJobStatusEvent, 'name' | 'questionCount'> = {},
+): Promise<void> {
+  if (!worksheetId) return;
+
+  try {
+    await pusher.trigger(
+      worksheetJobChannel(worksheetId),
+      STATUS_EVENT_NAMES[status],
+      { worksheetId, status, ...extras } satisfies WorksheetJobStatusEvent,
+    );
+  } catch (error) {
+    logger.warn('pdfToWorksheet: failed to broadcast status update', {
+      worksheetId,
+      status,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
 /** LLM output shape (validated by inference). */
 const worksheetDraftSchema = z.object({
   title: z.string(),
@@ -104,20 +172,74 @@ const schemaInstructions = `Return ONLY valid JSON matching this schema:
 Rules: "questions" is an array ([] if none). Non-MCQ "options" can be []. Use "order" 1,2,3,… in reading order. No markdown or extra keys.
 If no answer is provided for a multiple-choice or true/false question, determine the answer from the options.`;
 
+export interface PdfToWorksheetOptions {
+  /**
+   * Pre-existing Worksheet row id. When supplied, the pipeline fills in this
+   * row instead of creating a new one and broadcasts progress on its job
+   * channel. This is the path used by the BullMQ worker.
+   */
+  worksheetId?: string;
+}
+
 /**
  * Sends a PDF URL to the model for remote retrieval, extracts a worksheet via
- * structured inference, and inserts worksheet + questions in one DB transaction.
+ * structured inference, and inserts (or back-fills) worksheet + questions.
+ *
+ * When called with `options.worksheetId` the pipeline:
+ *   - keeps that row's id stable (the client already routed to it),
+ *   - drives `status` PENDING → COMPLETED / FAILED,
+ *   - fans out `set-*` Pusher events on `worksheetJobChannel`.
  */
-export async function pdfToWorksheet(gcsUrl: string, classId: string) {
-  const sanitizedUrl = sanitizeUrlForLogs(gcsUrl);
+export async function pdfToWorksheet(
+  gcsUrl: string,
+  classId: string,
+  options: PdfToWorksheetOptions = {},
+) {
+  const sourceUrl = sanitizeUrlForLogs(gcsUrl);
+  const placeholderWorksheetId = options.worksheetId;
+
+  await emitStatus(placeholderWorksheetId, JobStatus.PENDING);
 
   if (!isProbablyGoogleCloudUrl(gcsUrl)) {
     logger.warn("pdfToWorksheet: rejected unsupported PDF URL", {
-      sanitizedUrl,
+      sanitizedUrl: sourceUrl,
     });
+    await markWorksheetFailed(
+      placeholderWorksheetId,
+      "Only Google Cloud Storage URLs are supported",
+    );
     throw new Error("Only Google Cloud Storage URLs are supported");
   }
 
+  // Look for a previously-completed worksheet pointing at the same source PDF.
+  // If there is one (and it's not the placeholder we were handed) we reuse it,
+  // mark the placeholder CANCELLED so the editor stops spinning, and return
+  // the canonical worksheet.
+  const existingForSource = await prisma.worksheet.findUnique({
+    where: { classId_sourceUrl: { classId, sourceUrl } },
+  });
+
+  if (existingForSource && existingForSource.id !== placeholderWorksheetId) {
+    logger.info("pdfToWorksheet: reusing existing worksheet for source PDF", {
+      worksheetId: existingForSource.id,
+      classId,
+      sourceUrl,
+    });
+
+    if (placeholderWorksheetId) {
+      await prisma.worksheet
+        .update({
+          where: { id: placeholderWorksheetId },
+          data: { status: JobStatus.CANCELLED },
+        })
+        .catch(() => undefined);
+
+      await emitStatus(placeholderWorksheetId, JobStatus.CANCELLED);
+    }
+
+    return existingForSource;
+  }
+
   const filename = getFilenameFromUrl(gcsUrl);
   const prompt = `Read the attached PDF and convert it into a single worksheet JSON object.\n\n${schemaInstructions}`;
 
@@ -132,46 +254,162 @@ export async function pdfToWorksheet(gcsUrl: string, classId: string) {
     },
   ];
 
-  const draft = await inference<WorksheetDraft>(
-    input,
-    worksheetDraftSchema,
-    {
-      reason: 'pdf_to_worksheet_draft',
-      metadata: {
-        classId,
-        filename,
-      },
-    }
-  );
+  let draft: WorksheetDraft | null;
+  try {
+    draft = await inference<WorksheetDraft>(
+      input,
+      worksheetDraftSchema,
+      {
+        reason: 'pdf_to_worksheet_draft',
+        metadata: {
+          classId,
+          filename,
+        },
+      }
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await markWorksheetFailed(placeholderWorksheetId, message);
+    throw error;
+  }
 
   if (!draft) {
     logger.warn("pdfToWorksheet: no model output", { filename });
+    await markWorksheetFailed(
+      placeholderWorksheetId,
+      "Model returned no parseable worksheet output",
+    );
     return null;
   }
 
-  return prisma.$transaction(async (tx) => {
-    const worksheet = await tx.worksheet.create({
-      data: { classId, name: draft.title },
-    });
+  try {
+    const worksheet = await prisma.$transaction(async (tx) => {
+      const created = placeholderWorksheetId
+        ? await tx.worksheet.update({
+            where: { id: placeholderWorksheetId },
+            data: {
+              classId,
+              name: draft!.title,
+              sourceUrl,
+              status: JobStatus.PENDING,
+            },
+          })
+        : await tx.worksheet.create({
+            data: {
+              classId,
+              name: draft!.title,
+              sourceUrl,
+              status: JobStatus.PENDING,
+            },
+          });
 
-    if (draft.questions.length > 0) {
-      await tx.worksheetQuestion.createMany({
-        data: draft.questions.map((question) => ({
-          worksheetId: worksheet.id,
-          type: question.type,
-          question: question.question,
-          answer: question.answer,
-          points: Math.round(question.points ?? 0),
-          options: question.options ?? [],
-          markScheme: (question.markScheme ?? []).map((item) => ({
-            ...item,
-            points: Math.round(item.points),
+      if (draft!.questions.length > 0) {
+        // When re-running against an existing placeholder, drop any prior
+        // questions so we don't accumulate duplicates from retries.
+        if (placeholderWorksheetId) {
+          await tx.worksheetQuestion.deleteMany({
+            where: { worksheetId: created.id },
+          });
+        }
+
+        await tx.worksheetQuestion.createMany({
+          data: draft!.questions.map((question) => ({
+            worksheetId: created.id,
+            type: question.type,
+            question: question.question,
+            answer: question.answer,
+            points: Math.round(question.points ?? 0),
+            options: question.options ?? [],
+            markScheme: (question.markScheme ?? []).map((item) => ({
+              ...item,
+              points: Math.round(item.points),
+            })),
+            order: Math.round(question.order),
           })),
-          order: Math.round(question.order),
-        })),
+        });
+      }
+
+      return tx.worksheet.update({
+        where: { id: created.id },
+        data: { status: JobStatus.COMPLETED },
       });
-    }
+    });
+
+    await emitStatus(placeholderWorksheetId, JobStatus.COMPLETED, {
+      name: worksheet.name,
+      questionCount: draft.questions.length,
+    });
 
     return worksheet;
+  } catch (error) {
+    if (
+      error instanceof Prisma.PrismaClientKnownRequestError &&
+      error.code === "P2002"
+    ) {
+      const worksheet = await prisma.worksheet.findUnique({
+        where: {
+          classId_sourceUrl: {
+            classId,
+            sourceUrl,
+          },
+        },
+      });
+
+      if (worksheet) {
+        logger.info("pdfToWorksheet: reused worksheet created by concurrent retry", {
+          worksheetId: worksheet.id,
+          classId,
+          sourceUrl,
+        });
+
+        if (placeholderWorksheetId && placeholderWorksheetId !== worksheet.id) {
+          await prisma.worksheet
+            .update({
+              where: { id: placeholderWorksheetId },
+              data: { status: JobStatus.CANCELLED },
+            })
+            .catch(() => undefined);
+
+          await emitStatus(placeholderWorksheetId, JobStatus.CANCELLED);
+        }
+
+        return worksheet;
+      }
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    await markWorksheetFailed(placeholderWorksheetId, message);
+    throw error;
+  }
+}
+
+async function markWorksheetFailed(
+  worksheetId: string | undefined,
+  errorMessage: string,
+) {
+  if (!worksheetId) return;
+
+  await prisma.worksheet
+    .update({
+      where: { id: worksheetId },
+      data: { status: JobStatus.FAILED },
+    })
+    .catch((updateError) => {
+      logger.error('pdfToWorksheet: failed to mark worksheet FAILED', {
+        worksheetId,
+        error:
+          updateError instanceof Error
+            ? updateError.message
+            : String(updateError),
+      });
+    });
+
+  // The full error is logged + persisted on `RunJob.error`; the broadcast
+  // intentionally carries no error payload to avoid leaking internals.
+  logger.error('pdfToWorksheet: marking worksheet FAILED', {
+    worksheetId,
+    error: errorMessage,
   });
+
+  await emitStatus(worksheetId, JobStatus.FAILED);
 }

package/src/routers/assignment.ts

@@ -5,7 +5,6 @@ import { prisma } from "../lib/prisma.js";
 import { createDirectUploadFiles, type DirectUploadFile, confirmDirectUpload, updateUploadProgress, type UploadedFile } from "../lib/fileUpload.js";
 import { deleteFile } from "../lib/googleCloudStorage.js";
 import { logger } from "../utils/logger.js";
-import { gradeWorksheetPipeline } from "../pipelines/gradeWorksheet.js";
 import {
   classMemberOrSchoolAdminWhere,
   classTeacherOrSchoolAdminWhere,
@@ -35,6 +34,15 @@ import {
 } from "../services/assignment.js";
 import { sendToMultiple } from "../services/notification.js";
 
+function getCommenterName(comment: {
+  author: {
+    username: string;
+    profile: { displayName: string | null } | null;
+  };
+}) {
+  return comment.author.profile?.displayName || comment.author.username;
+}
+
 // DEPRECATED: This schema is no longer used - files are uploaded directly to GCS
 // Use directFileSchema instead
 
@@ -369,7 +377,18 @@ export const assignmentRouter = createTRPCRouter({
     .mutation(async ({ ctx, input }) => {
       const assignment = await prisma.assignment.findFirst({
         where: { id: input.assignmentId, classId: input.classId },
-        select: { id: true },
+        select: {
+          id: true,
+          title: true,
+          class: {
+            select: {
+              id: true,
+              name: true,
+              students: { select: { id: true } },
+              teachers: { select: { id: true } },
+            },
+          },
+        },
       });
       if (!assignment) {
         throw new TRPCError({
@@ -405,6 +424,24 @@ export const assignmentRouter = createTRPCRouter({
         include: commentInclude,
       });
 
+      const authorId = ctx.user!.id;
+      const receiverIds = Array.from(
+        new Set([
+          ...assignment.class.students.map((s) => s.id),
+          ...assignment.class.teachers.map((t) => t.id),
+        ])
+      ).filter((id) => id !== authorId);
+
+      if (receiverIds.length > 0) {
+        sendToMultiple({
+          receiverIds,
+          title: `New comment on ${assignment.title}`,
+          content: `${getCommenterName(comment)} commented in ${assignment.class.name}:\n\n${input.content}\n\n[View assignment](/class/${assignment.class.id}/assignments/${assignment.id})`,
+        }).catch((error) => {
+          logger.error("Failed to send assignment comment notifications:", error);
+        });
+      }
+
       return { comment };
     }),
 
@@ -458,7 +495,23 @@ export const assignmentRouter = createTRPCRouter({
             { assignment: { class: classTeacherOrSchoolAdminWhere(ctx.user!.id) } },
           ],
         },
-        select: { id: true },
+        select: {
+          id: true,
+          studentId: true,
+          assignment: {
+            select: {
+              id: true,
+              title: true,
+              class: {
+                select: {
+                  id: true,
+                  name: true,
+                  teachers: { select: { id: true } },
+                },
+              },
+            },
+          },
+        },
       });
       if (!submission) {
         throw new TRPCError({
@@ -493,6 +546,24 @@ export const assignmentRouter = createTRPCRouter({
         include: commentInclude,
       });
 
+      const authorId = ctx.user!.id;
+      const receiverIds = Array.from(
+        new Set([
+          submission.studentId,
+          ...submission.assignment.class.teachers.map((t) => t.id),
+        ])
+      ).filter((id) => id !== authorId);
+
+      if (receiverIds.length > 0) {
+        sendToMultiple({
+          receiverIds,
+          title: `New private comment on ${submission.assignment.title}`,
+          content: `${getCommenterName(comment)} commented on a submission in ${submission.assignment.class.name}:\n\n${input.content}\n\n[View submission](/class/${submission.assignment.class.id}/assignments/${submission.assignment.id}/submissions/${submission.id})`,
+        }).catch((error) => {
+          logger.error("Failed to send submission comment notifications:", error);
+        });
+      }
+
       return { comment };
     }),
 

package/src/routers/school.ts

@@ -104,6 +104,11 @@ export const schoolRouter = createTRPCRouter({
         schoolId: z.string(),
         email: z.string().email(),
         role: schoolRoleSchema,
+        username: z
+          .string()
+          .min(3, "Username must be at least 3 characters")
+          .optional(),
+        displayName: z.string().min(1).optional(),
       })
     )
     .mutation(({ ctx, input }) => createInvite(ctx.user!.id, input)),

package/src/routers/worksheet.ts

@@ -127,8 +127,18 @@ export const worksheetRouter = createTRPCRouter({
     ),
 
   createFromPdf: protectedTeacherProcedure
-    .input(z.object({ classId: z.string(), url: z.string().url() }))
-    .mutation(({ input }) => createWorksheetFromPdf(input.classId, input.url)),
+    .input(
+      z.object({
+        classId: z.string(),
+        url: z.string().url(),
+        name: z.string().optional(),
+      }),
+    )
+    .mutation(({ ctx, input }) =>
+      createWorksheetFromPdf(input.classId, input.url, ctx.user!.id, {
+        name: input.name,
+      }),
+    ),
 
   getWorksheetUploadUrls: protectedTeacherProcedure
     .input(getWorksheetUploadUrlsSchema)
@@ -190,9 +200,20 @@ export const worksheetRouter = createTRPCRouter({
     }),
 
   createFromUploadedPdf: protectedTeacherProcedure
-    .input(z.object({ classId: z.string(), fileId: z.string() }))
+    .input(
+      z.object({
+        classId: z.string(),
+        fileId: z.string(),
+        name: z.string().optional(),
+      }),
+    )
     .mutation(({ ctx, input }) =>
-      createWorksheetFromUploadedPdf(input.classId, input.fileId, ctx.user!.id)
+      createWorksheetFromUploadedPdf(
+        input.classId,
+        input.fileId,
+        ctx.user!.id,
+        { name: input.name },
+      )
     ),
 
   addQuestion: protectedProcedure