wip: update membership system

Author: brage-andreas

apps/rpc/src/modules/user/membership-service.ts

@@ -3,10 +3,14 @@ import { differenceInMonths, subYears } from "date-fns"
 import invariant from "tiny-invariant"
 import type { NTNUGroup } from "../feide/feide-groups-repository"
 import { getLogger } from "@dotkomonline/logger"
+import { getCurrentUTC } from "@dotkomonline/utils"
+import type { TZDate } from "@date-fns/tz"
 
 export interface MembershipService {
-  findMasterStartYearDelta(courses: NTNUGroup[]): number
-  findBachelorStartYearDelta(courses: NTNUGroup[]): number
+  findEstimatedStudyStart(
+    study: "BACHELOR" | "MASTER",
+    courses: NTNUGroup[]
+  ): { start: TZDate; semester: number; grade: number }
 }
 
 const BACHELOR_STUDY_PLAN = [
@@ -84,9 +88,9 @@ export function getMembershipService(): MembershipService {
   }
 
   /**
-   * Find the approximate start year based on a student's courses against a hard-coded set of courses.
+   * Find the approximate semester based on a student's courses against a hard-coded set of courses.
    */
-  function findApproximateStartYear(studentCourses: NTNUGroup[], courseSet: StudyPlanCourseSet): number {
+  function findEstimatedSemester(courseSet: StudyPlanCourseSet, studentCourses: NTNUGroup[]): number {
     logger.info("Searching for applicable membership based on courses %o and study plan %o", studentCourses, courseSet)
     let largestSemester = 0
     for (let i = 0; i < courseSet.length; i++) {
@@ -168,21 +172,37 @@ export function getMembershipService(): MembershipService {
       }
     }
 
-    // Give the value back in years (two school semesters in a year).
-    // We use Math#round because it will give us the correct year delta:
-    //   Year 1 fall (value 0)  : round(0 / 2) = 0 (Start year = current year)
-    //   Year 1 spring (value 1): round(1 / 2) = 1 (Start year = current - 1, since spring is in the next calendar year)
-    //   Year 2 fall (value 2)  : round(2 / 2) = 1 (Start year = current - 1)
-    //   Year 2 spring (value 3): round(3 / 2) = 2 (Start year = current - 2)
-    return Math.round(largestSemester / 2)
+    return largestSemester
   }
-  return {
-    findMasterStartYearDelta(courses) {
-      return findApproximateStartYear(courses, MASTER_STUDY_PLAN)
-    },
 
-    findBachelorStartYearDelta(courses) {
-      return findApproximateStartYear(courses, BACHELOR_STUDY_PLAN)
+  return {
+    findEstimatedStudyStart(study, courses) {
+      const studyPlan = study === "MASTER" ? MASTER_STUDY_PLAN : BACHELOR_STUDY_PLAN
+      const semester = findEstimatedSemester(studyPlan, courses)
+
+      // We use Math#round because it will give us the correct year delta:
+      //   Year 1 autumn (value 0)  : round(0 / 2) = 0 (Start year = current year)
+      //   Year 1 spring (value 1): round(1 / 2) = 1 (Start year = current - 1, since spring is in the next calendar year)
+      //   Year 2 autumn (value 2)  : round(2 / 2) = 1 (Start year = current - 1)
+      //   Year 2 spring (value 3): round(3 / 2) = 2 (Start year = current - 2)
+      //   ...
+      const yearOffset = Math.round(semester / 2)
+      const start = subYears(getAcademicStart(getCurrentUTC()), yearOffset)
+
+      // A school year consists of two semesters (Autumn and Spring). So this formula will give us the year:
+      //   Year 1 autumn (value 0): floor(0 / 2) + 1 = 1 (Year 1)
+      //   Year 1 spring (value 1): floor(1 / 2) + 1 = 1 (Year 1)
+      //   Year 2 autumn (value 2): floor(2 / 2) + 1 = 2 (Year 2)
+      //   Year 2 spring (value 3): floor(3 / 2) + 1 = 2 (Year 2)
+      //   Year 3 autumn (value 4): floor(4 / 2) + 1 = 3 (Year 3)
+      //   ...
+      const grade = Math.floor(semester / 2) + 1
+
+      return {
+        semester,
+        start,
+        grade,
+      }
     },
   }
 }

apps/rpc/src/modules/user/user-service.ts

@@ -18,6 +18,8 @@ import {
   findActiveMembership,
   getAcademicStart,
   getNextAcademicStart,
+  getNextSemesterStart,
+  getCurrentSemesterStart,
 } from "@dotkomonline/types"
 import { createS3PresignedPost, getCurrentUTC, slugify } from "@dotkomonline/utils"
 import { trace } from "@opentelemetry/api"
@@ -120,15 +122,31 @@ export function getUserService(
     }
 
     // Master degree always takes precedence over bachelor every single time.
-    const isMasterStudent = masterProgramme !== undefined
-    const distanceFromStartInYears = isMasterStudent
-      ? membershipService.findMasterStartYearDelta(courses)
-      : membershipService.findBachelorStartYearDelta(courses)
-    const estimatedStudyStart = subYears(getAcademicStart(getCurrentUTC()), distanceFromStartInYears)
-
-    // NOTE: We grant memberships for at most one year at a time. If you are granted membership after new-years, you
-    // will only keep the membership until the start of the next school year.
-    const endDate = getNextAcademicStart()
+    const study = masterProgramme !== undefined ? "MASTER" : "BACHELOR"
+    const estimatedStudyStart = membershipService.findEstimatedStudyStart(study, courses)
+
+    // We grant memberships for one semester at a time. This has some trade-offs, and natural alternative end dates are:
+    //   1. One semester (what we use)
+    //   2. School year (one or two semesters--until next Autumn semester, earlier referred to as the next
+    //      "academic start")
+    //   3. Entire degree (three years for Bachelor's and two years for Master's)
+    //
+    // The longer each membership lasts, the fewer times you need to calculate the grade and other information. This
+    // reduces the number of opportunities for wrong calculations, but also make the system less flexible. Sometimes
+    // students take a Bachelor's degree over a span of two years. Other times they change study. We choose the tradeoff
+    // where you have this flexibility, even though it costs us an increase in manual adjustments. You most often need
+    // to manually adjust someone's membership if someone:
+    //   a) Failed at least one of their courses a semester.
+    //   b) Has a very weird study plan due to previous studies.
+    //   c) Have been an exchange student and therefore not have done all their courses in the "correct" order
+    //      (according to our system anyway), where they have a "hole" in their course list exposed to us.
+    //
+    // We have decided it is best to manually adjust the membership in any nonlinear case, versus trying to correct for
+    // fairly common cases like exchange students automatically. We never want this heuristic to overestimate someone's
+    // grade. This is because we deem it generally less beneficial to be in a lower grade (because in practice the older
+    // students usually have priority for attendance), increasing their chances of reaching out to correct the error.
+    const endDate = getNextSemesterStart()
+    const startDate = getCurrentSemesterStart()
 
     // Master's programme takes precedence over bachelor's programme.
     if (masterProgramme !== undefined) {
@@ -148,18 +166,22 @@ export function getUserService(
       logger.info("Estimated end date for the master's programme to be %s", endDate.toUTCString())
       return {
         type: "MASTER_STUDENT",
-        start: estimatedStudyStart,
+        start: startDate,
         end: endDate,
         specialization: code,
+        grade: estimatedStudyStart.grade,
+        semester: estimatedStudyStart.semester,
       }
     }
 
     logger.info("Estimated end date for the bachelor's programme to be %s", endDate.toUTCString())
     return {
       type: "BACHELOR_STUDENT",
-      start: estimatedStudyStart,
+      start: startDate,
       end: endDate,
       specialization: null,
+      grade: estimatedStudyStart.grade,
+      semester: estimatedStudyStart.semester,
     }
   }
 

packages/db/prisma/schema.prisma

@@ -45,12 +45,18 @@ enum MembershipSpecialization {
 
 model Membership {
   id             String                    @id @default(uuid())
-  userId         String                    @map("user_id")
-  user           User                      @relation(fields: [userId], references: [id])
   type           MembershipType
   specialization MembershipSpecialization? @default(UNKNOWN)
   start          DateTime                  @db.Timestamptz(3)
   end            DateTime                  @db.Timestamptz(3)
+  /// The study grade (year) of the student. Freshman (first year) means grade 1.
+  grade          Int
+  /// The semester the student is in. 0-indexed. This value is meant to be used to calculate study start date easier
+  /// with membership start.
+  semester       Int
+
+  userId String @map("user_id")
+  user   User   @relation(fields: [userId], references: [id])
 
   @@map("membership")
 }

packages/types/src/user.ts

@@ -1,7 +1,7 @@
-import type { TZDate } from "@date-fns/tz"
+import { TZDate } from "@date-fns/tz"
 import { schemas } from "@dotkomonline/db/schemas"
 import { getCurrentUTC, slugify } from "@dotkomonline/utils"
-import { addYears, isAfter, isBefore, setMonth, startOfMonth } from "date-fns"
+import { addYears, interval, isAfter, isBefore, isWithinInterval, setMonth, startOfMonth } from "date-fns"
 import { z } from "zod"
 import { buildSearchFilter } from "./filters"
 
@@ -154,10 +154,15 @@ export function getSpecializationName(specialization: MembershipSpecialization)
   }
 }
 
+const JANUARY = 0
+const AUGUST = 7
+const getSpringSemesterStart = (year: number) => new TZDate(year, JANUARY, 1)
+const getAutumnSemesterStart = (year: number) => new TZDate(year, AUGUST, 1)
+
 /** Get the start of the academic year, which is by our convention August 1st. */
 export function getAcademicStart(date: TZDate | Date): TZDate {
-  // August is the 8th month, so we set the month to 7 (0-indexed)
-  return startOfMonth(setMonth(date, 7))
+  // August 1st -- <year>-08-01T00:00:00.000Z
+  return new TZDate(date.getFullYear(), AUGUST, 1)
 }
 
 export function getNextAcademicStart(): TZDate {
@@ -167,6 +172,31 @@ export function getNextAcademicStart(): TZDate {
   return isBeforeAugust ? firstAugust : addYears(firstAugust, 1)
 }
 
+export function getCurrentSemesterStart(): TZDate {
+  const now = getCurrentUTC()
+  const year = now.getFullYear()
+
+  const springSemesterStart = getSpringSemesterStart(year)
+  const autumnSemesterStart = getAutumnSemesterStart(year)
+
+  if (isWithinInterval(now, { start: springSemesterStart, end: autumnSemesterStart })) {
+    return springSemesterStart
+  }
+
+  return autumnSemesterStart
+}
+
+export function getNextSemesterStart(): TZDate {
+  const now = getCurrentUTC()
+  const autumnSemesterStart = getAutumnSemesterStart(now.getFullYear())
+
+  if (isBefore(now, autumnSemesterStart)) {
+    return autumnSemesterStart
+  }
+
+  return getSpringSemesterStart(addYears(now, 1).getFullYear())
+}
+
 /**
  * Calculates how many academic years have passed since the start date.
  * If start is "last August" (current academic year), returns 1.