feat(web): add degree report starting term parser (#95)

Co-authored-by: Chenxin Yan <[email protected]>

Author: yiminliu2004

apps/web/src/app/dashboard/plan/components/plan-table.tsx

@@ -21,6 +21,7 @@ import {
 import { cn } from "@/lib/utils";
 import DegreeProgreeUpload from "@/modules/report-parsing/components/degree-progress-upload";
 import type { UserCourse } from "@/modules/report-parsing/types";
+import type { StartingTerm } from "@/modules/report-parsing/utils/parse-starting-term";
 import type { Term, TermYear } from "@/utils/term";
 import {
   buildAcademicTimeline,
@@ -52,13 +53,22 @@ export default function PlanTable({ courses, student }: PlanTableProps) {
 
   const importUserCourses = useMutation(api.userCourses.importUserCourses);
 
+  const updateStudent = useMutation(api.students.updateCurrentStudent);
+
   const courseSearchId = useId();
 
-  const handleImportConfirm = async (coursesToImport: UserCourse[]) => {
+  const handleImportConfirm = async (
+    coursesToImport: UserCourse[],
+    startingTerm: StartingTerm | null,
+  ) => {
     if (coursesToImport.length === 0) {
       return;
     }
 
+    if (startingTerm) {
+      await updateStudent({ startingDate: startingTerm });
+    }
+
     const result = await importUserCourses({
       courses: coursesToImport,
     });

apps/web/src/app/onboarding/component/onboarding-form.tsx

@@ -40,6 +40,7 @@ import {
 } from "@/components/ui/select";
 import DegreeProgreeUpload from "@/modules/report-parsing/components/degree-progress-upload";
 import type { UserCourse } from "@/modules/report-parsing/types";
+import type { StartingTerm } from "@/modules/report-parsing/utils/parse-starting-term";
 
 const dateSchema = z.object({
   year: z.number().int().min(2000).max(2100),
@@ -199,11 +200,18 @@ export function OnboardingForm() {
     },
   });
 
-  function handleConfirmImport(coursesToImport: UserCourse[]) {
+  function handleConfirmImport(
+    coursesToImport: UserCourse[],
+    startingTerm: StartingTerm | null,
+  ) {
     if (coursesToImport.length === 0) {
       return;
     }
 
+    if (startingTerm) {
+      form.setFieldValue("startingDate", startingTerm);
+    }
+
     form.setFieldValue("userCourses", coursesToImport);
     setIsFileLoaded(true);
   }

apps/web/src/modules/report-parsing/components/confirm-modal.tsx

@@ -65,18 +65,16 @@ export default function ConfirmModal({
   return (
     <Dialog open={open} onOpenChange={handleOpenChange}>
       <DialogContent className="flex flex-col gap-0 p-0 sm:max-h-[min(640px,80vh)] sm:max-w-2xl [&>button:last-child]:top-6">
-        <DialogHeader className="shrink-0 space-y-0 text-left">
-          <DialogTitle className="px-6 pt-6 text-xl">
+        <DialogHeader className="px-6 gap-1 pb-3">
+          <DialogTitle className="pt-6 text-xl">
             Confirm Course History
           </DialogTitle>
           <DialogDescription asChild>
-            <div className="px-6 py-3">
-              <p className="text-sm text-muted-foreground">
-                We found {courses.length} course
-                {courses.length !== 1 ? "s" : ""} in your Degree Progress
-                Report. Please review and confirm.
-              </p>
-            </div>
+            <p className="text-sm text-muted-foreground">
+              We found {courses.length} course
+              {courses.length !== 1 ? "s" : ""} in your Degree Progress Report.
+              Please review and confirm.
+            </p>
           </DialogDescription>
         </DialogHeader>
 

apps/web/src/modules/report-parsing/components/degree-progress-upload.tsx

@@ -9,12 +9,19 @@ import {
   isDegreeProgressReport,
 } from "../utils/extract-pdf-text";
 import { parseCourseHistory } from "../utils/parse-course-history";
+import {
+  extractStartingTerm,
+  type StartingTerm,
+} from "../utils/parse-starting-term";
 import { transformToUserCourses } from "../utils/transform-to-user-courses";
 import ConfirmModal from "./confirm-modal";
 
 type FileUploadButtonProps = {
   maxSizeMB?: number;
-  onConfirm: (courses: UserCourse[]) => Promise<void> | void;
+  onConfirm: (
+    courses: UserCourse[],
+    startingTerm: StartingTerm | null,
+  ) => Promise<void> | void;
   showFileLoaded?: boolean;
   onFileClick?: () => void;
 };
@@ -27,6 +34,7 @@ export default function DegreeProgreeUpload({
 }: FileUploadButtonProps) {
   const maxSize = maxSizeMB * 1024 * 1024;
   const [parsedCourses, setParsedCourses] = useState<UserCourse[]>([]);
+  const [startingTerm, setStartingTerm] = useState<StartingTerm | null>(null);
   const [isModalOpen, setIsModalOpen] = useState(false);
   const [isImporting, setIsImporting] = useState(false);
   const [fileName, setFileName] = useState("");
@@ -51,6 +59,8 @@ export default function DegreeProgreeUpload({
       const file = fileData.file;
       if (!(file instanceof File)) return;
 
+      setStartingTerm(null);
+
       // Verify it's a Degree Progress Report
       try {
         const ok = await isDegreeProgressReport(file);
@@ -59,6 +69,15 @@ export default function DegreeProgreeUpload({
           removeFile(fileData.id);
           return;
         }
+
+        try {
+          const startingTerm = await extractStartingTerm(file);
+          console.log(startingTerm);
+
+          setStartingTerm(startingTerm);
+        } catch (e) {
+          console.warn("Could not find starting term:", e);
+        }
       } catch (err) {
         console.error("Error verifying PDF:", err);
         toast.error("Could not verify the PDF file.");
@@ -85,7 +104,7 @@ export default function DegreeProgreeUpload({
   const handleConfirm = async () => {
     setIsImporting(true);
     try {
-      await onConfirm(parsedCourses);
+      await onConfirm(parsedCourses, startingTerm);
 
       setIsModalOpen(false);
 

apps/web/src/modules/report-parsing/utils/parse-starting-term.ts

@@ -0,0 +1,52 @@
+import { extractPdfText } from "./extract-pdf-text";
+
+export interface StartingTerm {
+  year: number;
+  term: "spring" | "fall";
+}
+
+/**
+ * Parses the Requirement Term for "Undergraduate Career" from a full PDF.
+ * @param file PDF file (Degree Progress Report)
+ * @returns StartingTerm or null if not found
+ */
+export async function extractStartingTerm(
+  file: File,
+): Promise<StartingTerm | null> {
+  const text = await extractPdfText(file);
+
+  // Normalize whitespace and line breaks
+  const normalized = text.replace(/\s+/g, " ").toLowerCase();
+
+  //only look for patter like: "undergraduate/graduate career fall 2023"
+  const match = normalized.match(
+    /(undergraduate|graduate)\s+career\s+(fall|spr)(?:g)?\s*(20\d{2})/,
+  );
+
+  if (!match) {
+    return null;
+  }
+
+  const [, , termAbbr, yearStr] = match;
+
+  const year = parseInt(yearStr, 10);
+  const lower = termAbbr.toLowerCase();
+
+  let term: "spring" | "fall";
+  switch (lower) {
+    case "spr":
+    case "spring":
+      term = "spring";
+      break;
+    case "fall":
+      term = "fall";
+      break;
+    default:
+      term = "fall";
+  }
+
+  return {
+    year,
+    term,
+  };
+}

packages/server/convex/_generated/api.d.ts

@@ -35,14 +35,6 @@ import type {
   FunctionReference,
 } from "convex/server";
 
-/**
- * A utility for referencing Convex functions in your app's API.
- *
- * Usage:
- * ```js
- * const myFunctionReference = api.myModule.myFunction;
- * ```
- */
 declare const fullApi: ApiFromModules<{
   appConfigs: typeof appConfigs;
   courseOfferings: typeof courseOfferings;
@@ -65,14 +57,30 @@ declare const fullApi: ApiFromModules<{
   userCourseOfferings: typeof userCourseOfferings;
   userCourses: typeof userCourses;
 }>;
-declare const fullApiWithMounts: typeof fullApi;
 
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
 export declare const api: FilterApi<
-  typeof fullApiWithMounts,
+  typeof fullApi,
   FunctionReference<any, "public">
 >;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
 export declare const internal: FilterApi<
-  typeof fullApiWithMounts,
+  typeof fullApi,
   FunctionReference<any, "internal">
 >;
 

packages/server/convex/_generated/server.d.ts

@@ -10,7 +10,6 @@
 
 import {
   ActionBuilder,
-  AnyComponents,
   HttpActionBuilder,
   MutationBuilder,
   QueryBuilder,
@@ -19,15 +18,9 @@ import {
   GenericQueryCtx,
   GenericDatabaseReader,
   GenericDatabaseWriter,
-  FunctionReference,
 } from "convex/server";
 import type { DataModel } from "./dataModel.js";
 
-type GenericCtx =
-  | GenericActionCtx<DataModel>
-  | GenericMutationCtx<DataModel>
-  | GenericQueryCtx<DataModel>;
-
 /**
  * Define a query in this Convex app's public API.
  *
@@ -92,11 +85,12 @@ export declare const internalAction: ActionBuilder<DataModel, "internal">;
 /**
  * Define an HTTP action.
  *
- * This function will be used to respond to HTTP requests received by a Convex
- * deployment if the requests matches the path and method where this action
- * is routed. Be sure to route your action in `convex/http.js`.
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
  *
- * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
  * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
  */
 export declare const httpAction: HttpActionBuilder;

packages/server/convex/_generated/server.js

@@ -16,7 +16,6 @@ import {
   internalActionGeneric,
   internalMutationGeneric,
   internalQueryGeneric,
-  componentsGeneric,
 } from "convex/server";
 
 /**
@@ -81,10 +80,14 @@ export const action = actionGeneric;
 export const internalAction = internalActionGeneric;
 
 /**
- * Define a Convex HTTP action.
+ * Define an HTTP action.
  *
- * @param func - The function. It receives an {@link ActionCtx} as its first argument, and a `Request` object
- * as its second.
- * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`.
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
  */
 export const httpAction = httpActionGeneric;

packages/server/convex/students.ts

@@ -1,5 +1,7 @@
+import { ConvexError } from "convex/values";
 import { omit } from "convex-helpers";
 import { getOneFrom } from "convex-helpers/server/relationships";
+import { partial } from "convex-helpers/validators";
 import { protectedMutation, protectedQuery } from "./helpers/auth";
 import { students } from "./schemas/students";
 
@@ -49,3 +51,20 @@ export const upsertCurrentStudent = protectedMutation({
     }
   },
 });
+
+export const updateCurrentStudent = protectedMutation({
+  args: partial(omit(students, ["userId"])),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("students")
+      .withIndex("by_user_id", (q) => q.eq("userId", ctx.user.subject))
+      .unique();
+
+    if (!existing) {
+      throw new ConvexError("Student not found");
+    }
+
+    await ctx.db.patch(existing._id, args);
+    return existing._id;
+  },
+});