refactor(manage): share escape room config fields, i18n, order lock and validation bounds

rschlaefli · rschlaefli · commit 7162c3df2bc3 · 2026-07-10T11:50:12.000+02:00
- Extract EscapeRoomSettingsFields shared component (Checkbox + time limit + hint penalty) used by practice quiz, microlearning, group activity settings steps (M6)
- Extract useEscapeRoomYupFields hook with i18n-backed validation bounds: time limit integer/positive/max 1440min, hint penalty integer/min 0/max 3600s (M4)
- Force sequential order and disable the order selector when escape mode is enabled in practice quiz (M5)
- Add 10 escape room i18n keys to en + de (labels, tooltips, validation messages)
- Sync statsAggregatedAt to apps/analytics prisma schema (prisma:sync drift from B4)
diff --git a/apps/analytics/prisma/schema/quiz.prisma b/apps/analytics/prisma/schema/quiz.prisma
@@ -510,6 +510,11 @@ model EscapeRoomAttempt {
   completedAt    DateTime?
   lockoutUntil   DateTime?
 
+  // Set by the prune job once this attempt has been rolled into instance
+  // statistics. Guards against double-counting across repeated prune runs;
+  // completed/expired attempts are retained as the integrity record.
+  statsAggregatedAt DateTime?
+
   // Individual Play (PracticeQuiz / MicroLearning / LiveQuiz block)
   participant   Participant? @relation(fields: [participantId], references: [id], onDelete: Cascade)
   participantId String?      @db.Uuid
diff --git a/apps/frontend-manage/src/components/activities/creation/EscapeRoomSettingsFields.tsx b/apps/frontend-manage/src/components/activities/creation/EscapeRoomSettingsFields.tsx
@@ -0,0 +1,49 @@
+import { Checkbox, FormikNumberField } from '@uzh-bf/design-system'
+import { useTranslations } from 'next-intl'
+
+interface EscapeRoomSettingsFieldsProps {
+  isEscapeRoom: boolean
+  onToggle: (nextEnabled: boolean) => void
+}
+
+function EscapeRoomSettingsFields({
+  isEscapeRoom,
+  onToggle,
+}: EscapeRoomSettingsFieldsProps) {
+  const t = useTranslations()
+
+  return (
+    <div className="mt-2 flex flex-col gap-2 border-t border-solid border-gray-200 pt-2">
+      <Checkbox
+        label={t('manage.activityWizard.escapeRoomMode')}
+        checked={isEscapeRoom}
+        onCheck={() => onToggle(!isEscapeRoom)}
+        className={{
+          indicator: 'text-xs',
+          root: 'w-4.5 h-4.5',
+        }}
+        data={{ cy: 'toggle-escape-room' }}
+      />
+      {isEscapeRoom && (
+        <>
+          <FormikNumberField
+            name="escapeRoomTimeLimit"
+            label={t('manage.activityWizard.escapeRoomTimeLimit')}
+            required
+            className={{ root: 'w-full', field: 'w-full' }}
+            data={{ cy: 'escape-room-time-limit' }}
+          />
+          <FormikNumberField
+            name="escapeRoomHintPenalty"
+            label={t('manage.activityWizard.escapeRoomHintPenalty')}
+            required
+            className={{ root: 'w-full', field: 'w-full' }}
+            data={{ cy: 'escape-room-hint-penalty' }}
+          />
+        </>
+      )}
+    </div>
+  )
+}
+
+export default EscapeRoomSettingsFields
diff --git a/apps/frontend-manage/src/components/activities/creation/escapeRoomValidation.ts b/apps/frontend-manage/src/components/activities/creation/escapeRoomValidation.ts
@@ -0,0 +1,34 @@
+import { useTranslations } from 'next-intl'
+import * as yup from 'yup'
+
+// note: named with a `use` prefix (and called as a hook) rather than taking
+// `t` as a parameter, since typing the parameter explicitly as
+// `ReturnType<typeof useTranslations>` blows up tsc with TS2590 ("union type
+// too complex") given how large this repo's generated Messages type already is
+export function useEscapeRoomYupFields() {
+  const t = useTranslations()
+
+  return {
+    isEscapeRoom: yup.boolean(),
+    escapeRoomTimeLimit: yup.number().when('isEscapeRoom', {
+      is: true,
+      then: (schema) =>
+        schema
+          .required(t('manage.activityWizard.escapeRoomTimeLimitRequired'))
+          .integer(t('manage.activityWizard.escapeRoomInteger'))
+          .positive(t('manage.activityWizard.escapeRoomTimeLimitPositive'))
+          .max(1440, t('manage.activityWizard.escapeRoomTimeLimitMax')),
+      otherwise: (schema) => schema.notRequired(),
+    }),
+    escapeRoomHintPenalty: yup.number().when('isEscapeRoom', {
+      is: true,
+      then: (schema) =>
+        schema
+          .required(t('manage.activityWizard.escapeRoomHintPenaltyRequired'))
+          .integer(t('manage.activityWizard.escapeRoomInteger'))
+          .min(0, t('manage.activityWizard.escapeRoomHintPenaltyMin'))
+          .max(3600, t('manage.activityWizard.escapeRoomHintPenaltyMax')),
+      otherwise: (schema) => schema.notRequired(),
+    }),
+  }
+}
diff --git a/apps/frontend-manage/src/components/activities/creation/groupActivity/GroupActivitySettingsStep.tsx b/apps/frontend-manage/src/components/activities/creation/groupActivity/GroupActivitySettingsStep.tsx
@@ -1,9 +1,7 @@
 import { faClock, faCrown } from '@fortawesome/free-solid-svg-icons'
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
 import {
-  Checkbox,
   FormikDatetimePicker,
-  FormikNumberField,
   FormikSelectField,
   UserNotification,
 } from '@uzh-bf/design-system'
@@ -14,6 +12,7 @@ import useGroupActivityCourseGrouping from '../../../../lib/hooks/useGroupActivi
 import CourseChangeMonitor from '../CourseChangeMonitor'
 import CreationFormValidator from '../CreationFormValidator'
 import DateChangeMonitor from '../DateChangeMonitor'
+import EscapeRoomSettingsFields from '../EscapeRoomSettingsFields'
 import MultiplierSelector from '../MultiplierSelector'
 import WizardNavigation from '../WizardNavigation'
 import { GroupActivityWizardStepProps } from './GroupActivityWizard'
@@ -150,44 +149,10 @@ function GroupActivitySettingsStep({
                     dataHours={{ cy: 'select-end-date-hours' }}
                     dataMinutes={{ cy: 'select-end-date-minutes' }}
                   />
-                  <div className="mt-2 flex flex-col gap-2 border-t border-solid border-gray-200 pt-2">
-                    <Checkbox
-                      label="Escape Room Mode"
-                      checked={!!values.isEscapeRoom}
-                      onCheck={() =>
-                        setFieldValue('isEscapeRoom', !values.isEscapeRoom)
-                      }
-                      className={{
-                        indicator: 'text-xs',
-                        root: 'w-4.5 h-4.5',
-                      }}
-                      data={{ cy: 'toggle-escape-room' }}
-                    />
-                    {values.isEscapeRoom && (
-                      <>
-                        <FormikNumberField
-                          name="escapeRoomTimeLimit"
-                          label="Time Limit (minutes)"
-                          required
-                          className={{
-                            root: 'w-full',
-                            field: 'w-full',
-                          }}
-                          data={{ cy: 'escape-room-time-limit' }}
-                        />
-                        <FormikNumberField
-                          name="escapeRoomHintPenalty"
-                          label="Hint Penalty (seconds)"
-                          required
-                          className={{
-                            root: 'w-full',
-                            field: 'w-full',
-                          }}
-                          data={{ cy: 'escape-room-hint-penalty' }}
-                        />
-                      </>
-                    )}
-                  </div>
+                  <EscapeRoomSettingsFields
+                    isEscapeRoom={!!values.isEscapeRoom}
+                    onToggle={(next) => setFieldValue('isEscapeRoom', next)}
+                  />
                 </div>
               </div>
             </div>
diff --git a/apps/frontend-manage/src/components/activities/creation/groupActivity/GroupActivityWizard.tsx b/apps/frontend-manage/src/components/activities/creation/groupActivity/GroupActivityWizard.tsx
@@ -17,6 +17,7 @@ import * as yup from 'yup'
 import useCoursesGroupActivitySplit from '../../../../lib/hooks/useCoursesGroupActivitySplit'
 import { ElementSelectCourse } from '../../ActivityCreation'
 import CompletionStep from '../CompletionStep'
+import { useEscapeRoomYupFields } from '../escapeRoomValidation'
 import WizardLayout, {
   GroupActivityClueFormValues,
   GroupActivityFormValues,
@@ -92,6 +93,7 @@ function GroupActivityWizard({
   } = useCoursesGroupActivitySplit({
     courseSelection: courses,
   })
+  const escapeRoomYupFields = useEscapeRoomYupFields()
 
   const nameValidationSchema = yup.object().shape({
     name: yup
@@ -146,25 +148,7 @@ function GroupActivityWizard({
     courseId: yup
       .string()
       .required(t('manage.activityWizard.groupActivityCourse')),
-    isEscapeRoom: yup.boolean(),
-    escapeRoomTimeLimit: yup.number().when('isEscapeRoom', {
-      is: true,
-      then: (schema) =>
-        schema
-          .required('Time limit is required')
-          .integer('Must be an integer')
-          .positive('Must be a positive number of minutes'),
-      otherwise: (schema) => schema.notRequired(),
-    }),
-    escapeRoomHintPenalty: yup.number().when('isEscapeRoom', {
-      is: true,
-      then: (schema) =>
-        schema
-          .required('Hint penalty is required')
-          .integer('Must be an integer')
-          .min(0, 'Must be a non-negative number of seconds'),
-      otherwise: (schema) => schema.notRequired(),
-    }),
+    ...escapeRoomYupFields,
   })
 
   const stackCluesValiationSchema = yup.object().shape({
diff --git a/apps/frontend-manage/src/components/activities/creation/microLearning/MicroLearningSettingsStep.tsx b/apps/frontend-manage/src/components/activities/creation/microLearning/MicroLearningSettingsStep.tsx
@@ -3,9 +3,7 @@ import { faCrown } from '@fortawesome/free-solid-svg-icons'
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
 import useGamifiedCourseGrouping from '@lib/hooks/useGamifiedCourseGrouping'
 import {
-  Checkbox,
   FormikDatetimePicker,
-  FormikNumberField,
   FormikSelectField,
   UserNotification,
 } from '@uzh-bf/design-system'
@@ -16,6 +14,7 @@ import { twMerge } from 'tailwind-merge'
 import CourseSelectionMonitorMicrolearning from '../CourseSelectionMonitorMicrolearning'
 import CreationFormValidator from '../CreationFormValidator'
 import DateChangeMonitor from '../DateChangeMonitor'
+import EscapeRoomSettingsFields from '../EscapeRoomSettingsFields'
 import MultiplierSelector from '../MultiplierSelector'
 import WizardNavigation from '../WizardNavigation'
 import { MicroLearningWizardStepProps } from './MicroLearningWizard'
@@ -162,44 +161,10 @@ function MicroLearningSettingsStep({
                     dataHours={{ cy: 'select-end-date-hours' }}
                     dataMinutes={{ cy: 'select-end-date-minutes' }}
                   />
-                  <div className="mt-2 flex flex-col gap-2 border-t border-solid border-gray-200 pt-2">
-                    <Checkbox
-                      label="Escape Room Mode"
-                      checked={!!values.isEscapeRoom}
-                      onCheck={() =>
-                        setFieldValue('isEscapeRoom', !values.isEscapeRoom)
-                      }
-                      className={{
-                        indicator: 'text-xs',
-                        root: 'w-4.5 h-4.5',
-                      }}
-                      data={{ cy: 'toggle-escape-room' }}
-                    />
-                    {values.isEscapeRoom && (
-                      <>
-                        <FormikNumberField
-                          name="escapeRoomTimeLimit"
-                          label="Time Limit (minutes)"
-                          required
-                          className={{
-                            root: 'w-full',
-                            field: 'w-full',
-                          }}
-                          data={{ cy: 'escape-room-time-limit' }}
-                        />
-                        <FormikNumberField
-                          name="escapeRoomHintPenalty"
-                          label="Hint Penalty (seconds)"
-                          required
-                          className={{
-                            root: 'w-full',
-                            field: 'w-full',
-                          }}
-                          data={{ cy: 'escape-room-hint-penalty' }}
-                        />
-                      </>
-                    )}
-                  </div>
+                  <EscapeRoomSettingsFields
+                    isEscapeRoom={!!values.isEscapeRoom}
+                    onToggle={(next) => setFieldValue('isEscapeRoom', next)}
+                  />
                 </div>
               </div>
             </div>
diff --git a/apps/frontend-manage/src/components/activities/creation/microLearning/MicroLearningWizard.tsx b/apps/frontend-manage/src/components/activities/creation/microLearning/MicroLearningWizard.tsx
@@ -16,6 +16,7 @@ import { Dispatch, SetStateAction, useCallback, useRef, useState } from 'react'
 import * as yup from 'yup'
 import { ElementSelectCourse } from '../../ActivityCreation'
 import CompletionStep from '../CompletionStep'
+import { useEscapeRoomYupFields } from '../escapeRoomValidation'
 import StackCreationStep from '../StackCreationStep'
 import WizardLayout, { MicroLearningFormValues } from '../WizardLayout'
 import MicroLearningDescriptionStep from './MicroLearningDescriptionStep'
@@ -86,6 +87,7 @@ function MicroLearningWizard({
     useCoursesGamificationSplit({
       courseSelection: courses,
     })
+  const escapeRoomYupFields = useEscapeRoomYupFields()
 
   const nameValidationSchema = yup.object().shape({
     name: yup.string().required(t('manage.activityWizard.activityName')),
@@ -137,25 +139,7 @@ function MicroLearningWizard({
     courseId: yup
       .string()
       .required(t('manage.activityWizard.microlearningCourse')),
-    isEscapeRoom: yup.boolean(),
-    escapeRoomTimeLimit: yup.number().when('isEscapeRoom', {
-      is: true,
-      then: (schema) =>
-        schema
-          .required('Time limit is required')
-          .integer('Must be an integer')
-          .positive('Must be a positive number of minutes'),
-      otherwise: (schema) => schema.notRequired(),
-    }),
-    escapeRoomHintPenalty: yup.number().when('isEscapeRoom', {
-      is: true,
-      then: (schema) =>
-        schema
-          .required('Hint penalty is required')
-          .integer('Must be an integer')
-          .min(0, 'Must be a non-negative number of seconds'),
-      otherwise: (schema) => schema.notRequired(),
-    }),
+    ...escapeRoomYupFields,
   })
 
   const stackValiationSchema = yup.object().shape({
diff --git a/apps/frontend-manage/src/components/activities/creation/practiceQuiz/PracticeQuizSettingsStep.tsx b/apps/frontend-manage/src/components/activities/creation/practiceQuiz/PracticeQuizSettingsStep.tsx
@@ -3,7 +3,6 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
 import { ElementOrderType } from '@klicker-uzh/graphql/dist/ops'
 import useGamifiedCourseGrouping from '@lib/hooks/useGamifiedCourseGrouping'
 import {
-  Checkbox,
   FormikNumberField,
   FormikSelectField,
   UserNotification,
@@ -14,6 +13,7 @@ import { useState } from 'react'
 import { twMerge } from 'tailwind-merge'
 import CourseSelectionMonitorPracticeQuiz from '../CourseSelectionMonitorPracticeQuiz'
 import CreationFormValidator from '../CreationFormValidator'
+import EscapeRoomSettingsFields from '../EscapeRoomSettingsFields'
 import MultiplierSelector from '../MultiplierSelector'
 import WizardNavigation from '../WizardNavigation'
 import { PracticeQuizWizardStepProps } from './PracticeQuizWizard'
@@ -157,53 +157,22 @@ function PracticeQuizSettingsStep({
                       }
                     })}
                     required
+                    disabled={!!values.isEscapeRoom}
                     data={{ cy: 'select-order' }}
                     className={{
                       root: 'w-full',
                       tooltip: 'z-20',
                     }}
                   />
-                  <div className="mt-2 flex flex-col gap-2 border-t border-solid border-gray-200 pt-2">
-                    <Checkbox
-                      label="Escape Room Mode"
-                      checked={!!values.isEscapeRoom}
-                      onCheck={() => {
-                        setFieldValue('isEscapeRoom', !values.isEscapeRoom)
-                        if (!values.isEscapeRoom) {
-                          setFieldValue('order', ElementOrderType.Sequential)
-                        }
-                      }}
-                      className={{
-                        indicator: 'text-xs',
-                        root: 'w-4.5 h-4.5',
-                      }}
-                      data={{ cy: 'toggle-escape-room' }}
-                    />
-                    {values.isEscapeRoom && (
-                      <>
-                        <FormikNumberField
-                          name="escapeRoomTimeLimit"
-                          label="Time Limit (minutes)"
-                          required
-                          className={{
-                            root: 'w-full',
-                            field: 'w-full',
-                          }}
-                          data={{ cy: 'escape-room-time-limit' }}
-                        />
-                        <FormikNumberField
-                          name="escapeRoomHintPenalty"
-                          label="Hint Penalty (seconds)"
-                          required
-                          className={{
-                            root: 'w-full',
-                            field: 'w-full',
-                          }}
-                          data={{ cy: 'escape-room-hint-penalty' }}
-                        />
-                      </>
-                    )}
-                  </div>
+                  <EscapeRoomSettingsFields
+                    isEscapeRoom={!!values.isEscapeRoom}
+                    onToggle={(next) => {
+                      setFieldValue('isEscapeRoom', next)
+                      // practice-quiz ONLY: force sequential order when enabling
+                      if (next)
+                        setFieldValue('order', ElementOrderType.Sequential)
+                    }}
+                  />
                 </div>
               </div>
             </div>
diff --git a/apps/frontend-manage/src/components/activities/creation/practiceQuiz/PracticeQuizWizard.tsx b/apps/frontend-manage/src/components/activities/creation/practiceQuiz/PracticeQuizWizard.tsx
diff --git a/packages/i18n/messages/de.ts b/packages/i18n/messages/de.ts
diff --git a/packages/i18n/messages/en.ts b/packages/i18n/messages/en.ts
