@studious-lms/server 1.21.0 → 1.23.0

package/src/services/adminUser.ts

@@ -0,0 +1,93 @@
+import type { Prisma } from '@prisma/client';
+import { TRPCError } from '@trpc/server';
+import { prisma } from '../lib/prisma.js';
+
+export async function searchUsersForAdmin(input: {
+  page: number;
+  pageSize: number;
+  query?: string;
+}) {
+  const skip = input.page * input.pageSize;
+  const where: Prisma.UserWhereInput = {};
+  const q = input.query?.trim();
+  if (q) {
+    where.OR = [
+      { username: { contains: q, mode: 'insensitive' } },
+      { email: { contains: q, mode: 'insensitive' } },
+    ];
+  }
+
+  const [items, total] = await Promise.all([
+    prisma.user.findMany({
+      where,
+      orderBy: { username: 'asc' },
+      skip,
+      take: input.pageSize,
+      select: {
+        id: true,
+        username: true,
+        email: true,
+        verified: true,
+        school: { select: { id: true, name: true } },
+        _count: {
+          select: { teacherIn: true, studentIn: true, sessions: true },
+        },
+      },
+    }),
+    prisma.user.count({ where }),
+  ]);
+
+  return {
+    items,
+    total,
+    page: input.page,
+    pageSize: input.pageSize,
+    pageCount: Math.max(1, Math.ceil(total / input.pageSize)),
+  };
+}
+
+export async function getUserForAdmin(id: string) {
+  const user = await prisma.user.findUnique({
+    where: { id },
+    select: {
+      id: true,
+      username: true,
+      email: true,
+      verified: true,
+      termsAcceptedAt: true,
+      termsVersion: true,
+      profile: {
+        select: { displayName: true, location: true, createdAt: true },
+      },
+      school: { select: { id: true, name: true, subdomain: true } },
+      schoolMemberships: {
+        select: {
+          id: true,
+          role: true,
+          status: true,
+          createdAt: true,
+          school: { select: { id: true, name: true } },
+        },
+      },
+      sessions: {
+        orderBy: { createdAt: 'desc' },
+        take: 10,
+        select: { id: true, type: true, createdAt: true, expiresAt: true },
+      },
+      _count: {
+        select: {
+          teacherIn: true,
+          studentIn: true,
+          sessions: true,
+          submissions: true,
+          files: true,
+        },
+      },
+    },
+  });
+
+  if (!user) {
+    throw new TRPCError({ code: 'NOT_FOUND', message: 'User not found' });
+  }
+  return user;
+}

package/src/services/gradeCalculation.ts

@@ -0,0 +1,253 @@
+/**
+ * Grade calculation – pure functions for computing final class grades from
+ * categories, weights, and grade-calculation policies. No I/O; unit-testable.
+ *
+ * Future policies (standards-based grading, etc.) should extend
+ * `GradeCalculationPolicies` and be handled inside `computeFinalGrade` so
+ * callers never need to change.
+ */
+
+export type GradeRoundingMode = "NONE" | "HALF_UP" | "FLOOR" | "CEILING";
+
+export interface GradeCalculationPolicies {
+  /** Count ungraded/missing scores as 0% instead of excluding them. */
+  treatMissingAsZero: boolean;
+  /** How the final percentage is rounded to a whole number. */
+  roundingMode: GradeRoundingMode;
+}
+
+export interface GradeCategoryInput {
+  id: string;
+  name: string;
+  /** Relative weight of this category toward the final grade. */
+  weight: number;
+  /** Number of lowest-percentage scores dropped within this category. */
+  dropLowest: number;
+}
+
+export interface ScoreInput {
+  /** Category the score belongs to; null falls into the default category. */
+  categoryId: string | null;
+  /** Points earned; null means missing/ungraded. */
+  pointsEarned: number | null;
+  /** Maximum points for the item; items with maxPoints <= 0 are ignored. */
+  maxPoints: number;
+  /** Relative weight of the item within its category (defaults to 1). */
+  weight?: number;
+}
+
+export interface CategoryAverage {
+  categoryId: string | null;
+  name: string;
+  weight: number;
+  /** Percentage 0–100, or null when no scores counted. */
+  average: number | null;
+  countedScores: number;
+  droppedScores: number;
+}
+
+export interface FinalGradeResult {
+  /** Final percentage 0–100 (rounded per policy), or null when no data. */
+  percentage: number | null;
+  categories: CategoryAverage[];
+}
+
+/** Synthetic category used for scores without a category. */
+export const DEFAULT_CATEGORY = {
+  id: null,
+  weight: 1,
+  dropLowest: 0,
+} as const;
+
+export function roundPercentage(
+  value: number,
+  mode: GradeRoundingMode
+): number {
+  switch (mode) {
+    case "HALF_UP":
+      return Math.round(value);
+    case "FLOOR":
+      return Math.floor(value);
+    case "CEILING":
+      return Math.ceil(value);
+    case "NONE":
+    default:
+      return value;
+  }
+}
+
+interface CountableScore {
+  percentage: number;
+  weight: number;
+}
+
+function collectCountableScores(
+  scores: ScoreInput[],
+  policies: GradeCalculationPolicies
+): CountableScore[] {
+  const countable: CountableScore[] = [];
+  for (const score of scores) {
+    if (score.maxPoints <= 0) continue;
+    if (score.pointsEarned === null) {
+      if (!policies.treatMissingAsZero) continue;
+      countable.push({ percentage: 0, weight: score.weight ?? 1 });
+      continue;
+    }
+    countable.push({
+      percentage: (score.pointsEarned / score.maxPoints) * 100,
+      weight: score.weight ?? 1,
+    });
+  }
+  return countable;
+}
+
+function averageCategory(
+  countable: CountableScore[],
+  dropLowest: number
+): { average: number | null; counted: number; dropped: number } {
+  // Always keep at least one score so a category never collapses to null
+  // just because dropLowest >= score count.
+  const dropCount = Math.min(Math.max(dropLowest, 0), countable.length - 1);
+  const kept =
+    dropCount > 0
+      ? [...countable]
+          .sort((a, b) => a.percentage - b.percentage)
+          .slice(dropCount)
+      : countable;
+
+  const totalWeight = kept.reduce((sum, s) => sum + s.weight, 0);
+  if (kept.length === 0 || totalWeight <= 0) {
+    return { average: null, counted: 0, dropped: 0 };
+  }
+
+  const weighted = kept.reduce((sum, s) => sum + s.percentage * s.weight, 0);
+  return {
+    average: weighted / totalWeight,
+    counted: kept.length,
+    dropped: dropCount,
+  };
+}
+
+/**
+ * Computes the final class grade as the weighted average of category
+ * averages. Scores with no category fall into a default category with
+ * weight `DEFAULT_CATEGORY.weight`. Categories without counted scores are
+ * excluded from the weighted average.
+ */
+export function computeFinalGrade(
+  policies: GradeCalculationPolicies,
+  categories: GradeCategoryInput[],
+  scores: ScoreInput[],
+  options?: { defaultCategoryName?: string }
+): FinalGradeResult {
+  const knownIds = new Set(categories.map((c) => c.id));
+  const byCategory = new Map<string | null, ScoreInput[]>();
+  for (const score of scores) {
+    const key =
+      score.categoryId !== null && knownIds.has(score.categoryId)
+        ? score.categoryId
+        : null;
+    const bucket = byCategory.get(key);
+    if (bucket) {
+      bucket.push(score);
+    } else {
+      byCategory.set(key, [score]);
+    }
+  }
+
+  const categoryAverages: CategoryAverage[] = [];
+
+  for (const category of categories) {
+    const countable = collectCountableScores(
+      byCategory.get(category.id) ?? [],
+      policies
+    );
+    const { average, counted, dropped } = averageCategory(
+      countable,
+      category.dropLowest
+    );
+    categoryAverages.push({
+      categoryId: category.id,
+      name: category.name,
+      weight: category.weight,
+      average,
+      countedScores: counted,
+      droppedScores: dropped,
+    });
+  }
+
+  const uncategorized = byCategory.get(null) ?? [];
+  if (uncategorized.length > 0) {
+    const countable = collectCountableScores(uncategorized, policies);
+    const { average, counted, dropped } = averageCategory(
+      countable,
+      DEFAULT_CATEGORY.dropLowest
+    );
+    categoryAverages.push({
+      categoryId: DEFAULT_CATEGORY.id,
+      name: options?.defaultCategoryName ?? "Uncategorized",
+      weight: DEFAULT_CATEGORY.weight,
+      average,
+      countedScores: counted,
+      droppedScores: dropped,
+    });
+  }
+
+  const contributing = categoryAverages.filter(
+    (c) => c.average !== null && c.weight > 0
+  );
+  const totalWeight = contributing.reduce((sum, c) => sum + c.weight, 0);
+
+  const percentage =
+    totalWeight > 0
+      ? roundPercentage(
+          contributing.reduce(
+            (sum, c) => sum + (c.average as number) * c.weight,
+            0
+          ) / totalWeight,
+          policies.roundingMode
+        )
+      : null;
+
+  return { percentage, categories: categoryAverages };
+}
+
+interface ParsedBoundary {
+  grade: string;
+  minPercentage: number;
+  maxPercentage: number;
+}
+
+/**
+ * Maps a percentage to a letter grade using a GradingBoundary `structured`
+ * JSON payload (`{ boundaries: [{ grade, minPercentage, maxPercentage }] }`).
+ * Returns null when the payload is unparseable or nothing matches.
+ */
+export function resolveLetterGrade(
+  structured: string,
+  percentage: number
+): string | null {
+  let boundaries: ParsedBoundary[];
+  try {
+    const parsed = JSON.parse(structured) as {
+      boundaries?: ParsedBoundary[];
+    };
+    if (!Array.isArray(parsed.boundaries)) return null;
+    boundaries = parsed.boundaries;
+  } catch {
+    return null;
+  }
+
+  const sorted = [...boundaries].sort(
+    (a, b) => b.minPercentage - a.minPercentage
+  );
+  for (const boundary of sorted) {
+    if (
+      typeof boundary.minPercentage === "number" &&
+      percentage >= boundary.minPercentage
+    ) {
+      return boundary.grade ?? null;
+    }
+  }
+  return null;
+}