Merge pull request #714 from devwums/fix/assigned-issues

Add moderation transition guard, review queue query bounds, reviewer claim lock, and rubric validator helpers

Author: MaryammAli

BackendAcademy/src/submissions/moderation-guard.ts

@@ -0,0 +1,45 @@
+export type ModerationState = 'NONE' | 'FLAGGED' | 'ESCALATED' | 'RESOLVED' | 'DISMISSED';
+export type ModerationAction = 'flag' | 'dismiss' | 'escalate' | 'resolve';
+
+const LEGAL_TRANSITIONS: Record<ModerationAction, ModerationState[]> = {
+  flag: ['NONE'],
+  dismiss: ['FLAGGED'],
+  escalate: ['FLAGGED'],
+  resolve: ['FLAGGED', 'ESCALATED'],
+};
+
+const NEXT_STATE: Record<ModerationAction, ModerationState> = {
+  flag: 'FLAGGED',
+  dismiss: 'DISMISSED',
+  escalate: 'ESCALATED',
+  resolve: 'RESOLVED',
+};
+
+export interface ModerationAuditRecord {
+  action: ModerationAction;
+  actorId: string;
+  fromState: ModerationState;
+  toState: ModerationState;
+  reason: string;
+  at: Date;
+}
+
+/** Validates a moderation transition and returns its immutable audit record. */
+export function applyModerationTransition(
+  current: ModerationState,
+  action: ModerationAction,
+  actorId: string,
+  reason: string,
+): ModerationAuditRecord {
+  if (!LEGAL_TRANSITIONS[action].includes(current)) {
+    throw new Error(`Illegal moderation transition: ${action} from ${current}`);
+  }
+  return {
+    action,
+    actorId,
+    fromState: current,
+    toState: NEXT_STATE[action],
+    reason,
+    at: new Date(),
+  };
+}

BackendAcademy/src/submissions/review-queue-query.util.ts

@@ -0,0 +1,29 @@
+export interface ReviewQueueFilters {
+  status?: string;
+  maxAgeHours?: number;
+  slaBreachedOnly?: boolean;
+}
+
+export interface ReviewQueueQuery {
+  filters: ReviewQueueFilters;
+  page: number;
+  pageSize: number;
+  sortBy: 'createdAt' | 'slaDeadline';
+}
+
+export const MAX_PAGE_SIZE = 100;
+
+/** Builds a bounded, deterministic review-queue query from raw params. */
+export function buildReviewQueueQuery(
+  filters: ReviewQueueFilters,
+  page = 1,
+  pageSize = 25,
+  sortBy: ReviewQueueQuery['sortBy'] = 'slaDeadline',
+): ReviewQueueQuery {
+  return {
+    filters,
+    page: Math.max(1, page),
+    pageSize: Math.min(Math.max(1, pageSize), MAX_PAGE_SIZE),
+    sortBy,
+  };
+}

BackendAcademy/src/submissions/reviewer-claim.util.ts

@@ -0,0 +1,25 @@
+export interface ClaimableSubmission {
+  submissionId: string;
+  claimedBy?: string;
+  claimedAt?: Date;
+}
+
+export class AlreadyClaimedError extends Error {
+  constructor(submissionId: string) {
+    super(`Submission ${submissionId} is already claimed`);
+  }
+}
+
+/**
+ * Atomically claims a submission for review. Callers must pass the
+ * current record read within the same transaction/lock to avoid races.
+ */
+export function claimForReview(
+  current: ClaimableSubmission,
+  reviewerId: string,
+): ClaimableSubmission {
+  if (current.claimedBy && current.claimedBy !== reviewerId) {
+    throw new AlreadyClaimedError(current.submissionId);
+  }
+  return { ...current, claimedBy: reviewerId, claimedAt: new Date() };
+}

BackendAcademy/src/submissions/rubric-validator.util.ts

@@ -0,0 +1,32 @@
+export interface RubricCriterion {
+  weight: number;
+  score: number;
+  maxScore: number;
+}
+
+export class InvalidRubricError extends Error {}
+
+const EPSILON = 0.001;
+
+/** Validates rubric weights sum to 1 and each score is within bounds. */
+export function validateRubric(criteria: RubricCriterion[]): void {
+  const totalWeight = criteria.reduce((sum, c) => sum + c.weight, 0);
+  if (Math.abs(totalWeight - 1) > EPSILON) {
+    throw new InvalidRubricError(`Rubric weights must sum to 1, got ${totalWeight}`);
+  }
+  for (const c of criteria) {
+    if (c.score < 0 || c.score > c.maxScore) {
+      throw new InvalidRubricError(`Score ${c.score} out of bounds [0, ${c.maxScore}]`);
+    }
+  }
+}
+
+/** Computes the weighted total score, rounded to two decimal places. */
+export function computeTotalScore(criteria: RubricCriterion[]): number {
+  validateRubric(criteria);
+  const total = criteria.reduce(
+    (sum, c) => sum + (c.score / c.maxScore) * c.weight * 100,
+    0,
+  );
+  return Math.round(total * 100) / 100;
+}