Exam Model

Problem Overview

MaMpf needs a formal representation of exams that can:

• Act as a registration target with capacity limits and eligibility checks (see Student Performance)
• Track which students are registered for which exam dates/locations
• Link to the assessment system for grading
• Support multiple exam dates per lecture (e.g., Hauptklausur, Nachklausur, Wiederholungsklausur)

Solution Architecture

We introduce a new Exam model that:

• Belongs to a Lecture: Each exam is scoped to a specific lecture offering
• Implements Registration::Registerable: Acts as a registration target (students register for the exam)
• Implements Rosters::Rosterable: Manages the list of registered students
• Implements Assessment::Pointable and Assessment::Gradable: Links to an Assessment::Assessment for points and grades. Both concerns include Assessment::Assessable, so the exam gets the shared assessment interface through them rather than directly

The parent Lecture (which implements Registration::Campaignable) hosts the registration campaigns. Each exam (Hauptklausur, Nachklausur, etc.) gets its own campaign with that exam as the sole registerable item.

Exam (ActiveRecord Model)

Key Attributes

There is deliberately no registration_deadline column: the deadline belongs to the campaign. Exam#registration_deadline is an attr_accessor that carries the value between the form and the campaign — see Exam Registration Flow.

Role in the System

1. As Registerable (Registration Target)

# Creating the exam is the whole step: an after_create hook adds the campaign,
# hosted by the parent lecture, and the single item pointing back at the exam.
exam = lecture.exams.create!(
  title: "Hauptklausur",
  date: 3.weeks.from_now,
  capacity: 200
)

exam.registration_campaign            # draft, first_come_first_served
exam.registration_campaign.registration_deadline  # exam date minus three days

Passing registration_deadline: to the exam overrides that default, and skip_campaigns: true suppresses the campaign entirely — for exams whose participants are managed by hand.

2. As Rosterable (Student Tracking)

# After allocation, students are materialized into the exam roster
exam.allocated_user_ids # => [101, 102, 103, ...]

3. As Pointable and Gradable (Grading Container)

# Nothing to link: the assessment came into being with the exam
exam.assessment                  # => Assessment::Assessment
exam.assessment.requires_points  # => true

Example Implementation

class Exam < ApplicationRecord
  belongs_to :lecture

  include Registration::Registerable
  include Rosters::Rosterable
  include Assessment::Pointable
  include Assessment::Gradable

  attr_accessor :registration_deadline, :reopen_after_deadline_fix

  validates :title, presence: true
  validates :capacity, numericality: { greater_than: 0, allow_nil: true }
  validate :registration_deadline_before_exam_date
  validate :registration_deadline_in_future

  after_create :setup_assessment, if: -> { Flipper.enabled?(:assessment_grading) }
  after_create :create_registration_campaign,
               if: -> { !skip_campaigns && Flipper.enabled?(:registration_campaigns) }
  after_update :update_campaign_deadline, if: -> { registration_deadline.present? && ... }
  before_destroy :destroy_draft_campaign

  # ...

  private

    def setup_assessment
      ensure_pointbook!(requires_submission: false)
    end
end

materialize_allocation! and the roster methods come from Rosters::Rosterable; the exam only overrides add_user_to_roster! and remove_user_from_roster!. Note that date carries no presence validation — an exam may be entered before its date is fixed.

Database Migration

class CreateExams < ActiveRecord::Migration[7.0]
  def change
    create_table :exams do |t|
      t.references :lecture, null: false, foreign_key: true
      t.string :title, null: false
      t.datetime :date
      t.text :location
      t.integer :capacity
      t.text :description
      t.boolean :skip_campaigns, default: false, null: false
      t.integer :self_materialization_mode, default: 0

      t.timestamps
    end

    add_index :exams, [:lecture_id, :date]
    add_index :exams, :self_materialization_mode
  end
end

Exam Registration Flow

Setup (Staff Actions)

Student Experience

1. Student visits exam registration campaign page
2. System checks eligibility via Registration::PolicyEngine (queries StudentPerformance::Certification.status)
3. If ineligible, student sees error message explaining why (e.g., "Certification pending" or "Certification failed")
4. If eligible (status IN passed/forced_passed), student sees registration interface
5. Student submits registration
6. Registration is confirmed immediately — exam campaigns are always first-come-first-served
7. After registration closes, materialize_allocation! updates exam roster (allocation filtered to only certified students)

Exam Grading Flow

After Exam is Administered

Usage Scenarios

Scenario 1: Regular Final Exam

exam = lecture.exams.create!(
  title: "Final Exam",
  date: Date.new(2025, 2, 15),
  location: "Main Hall",
  capacity: 200,
  registration_deadline: Date.new(2025, 2, 1)
)

campaign = exam.registration_campaigns.create!(
  title: "Final Exam Registration",
  allocation_mode: :first_come_first_served,
  registration_deadline: exam.registration_deadline
)

campaign.registration_policies.create!(
  kind: :student_performance,
  config: { lecture_id: lecture.id }
)

# Teacher creates certifications for eligible students
lecture.active_users.find_each do |user|
  evaluator = StudentPerformance::Evaluator.new(lecture: lecture, user: user)
  proposal = evaluator.proposal

  StudentPerformance::Certification.create!(
    lecture: lecture,
    user: user,
    status: proposal[:status],  # :passed or :failed
    rule_snapshot: proposal[:rule_snapshot],
    notes: proposal[:notes]
  )
end

# Pre-flight check before opening
campaign.validate_certifications!  # raises if missing certifications

Scenario 2: Multiple Exam Dates (Regular + Retake)

Each exam carries its own campaign; there is no campaign that offers both and lets students rank them. Sitting the regular exam and the retake are separate decisions, so registering for one says nothing about the other.

regular_exam = lecture.exams.create!(
  title: "Regular Exam",
  date: Date.new(2025, 2, 15),
  capacity: 200
)

retake_exam = lecture.exams.create!(
  title: "Retake Exam",
  date: Date.new(2025, 3, 15),
  capacity: 50
)

# Creating the exam creates its campaign and the single item pointing at it.
regular_exam.registration_campaign  # first_come_first_served, one item
retake_exam.registration_campaign   # a separate campaign, likewise

Lifecycle

An exam outlives its registration campaign. The campaign ends at finalization; the exam then still has to be sat, marked, and released to the students. That whole arc is what Exam#status_phase returns, and it is the only place the teacher sees it — the status column of the exam list on the lecture's edit page.

stateDiagram-v2
    [*] --> draft
    draft --> registration_open : campaign opened
    registration_open --> registration_closed : campaign closed
    registration_closed --> finalized : campaign finalized
    finalized --> conducted : exam date passed
    conducted --> grading : first participation marked
    grading --> graded : results published
    graded --> [*]

Where each phase comes from

Three sources feed the phase, not one. While the campaign is still running it decides alone; once it is finalized — or was never created — the calendar and the assessment take over.

Note the fallback: an exam with skip_campaigns: true never has a campaign, so it reports finalized until its date passes. Nothing was ever finalized there — the phase only means "not open for registration, not yet sat".

Proposed File Structure

app/
└── models/
    └── exam.rb