LehrerApp/docs/Datenmodell.md

Datenmodell und Begriffe

Dieses Dokument beschreibt die fachliche Bedeutung der zentralen Datensätze. Es soll verhindern, dass technisch ähnliche Felder als unterschiedliche Sachverhalte interpretiert oder dieselben Informationen mehrfach gespeichert werden.

Lerngruppe (LearningGroup)

Eine Lerngruppe ist die konkrete Unterrichtsgruppe eines Fachs in genau einem Schuljahr. Sie kann als Klasse oder Kurs organisiert sein.

• Name: frei gewählte Bezeichnung, zum Beispiel 5b NAT (BEN) oder Mathe G
• SubjectId: Verweis auf das unterrichtete Fach
• SchoolYear: Schuljahr dieser konkreten Lerngruppe
• GradeLevel: Klassen- beziehungsweise Jahrgangsstufe

Der Fachname wird ausschließlich im Subject-Stammdatensatz gepflegt. Die Lerngruppe speichert keine zweite Kopie des Fachnamens.

Gruppenzuordnung (GroupMembership)

Eine Gruppenzuordnung verbindet einen Schüler mit einer Lerngruppe. Sie ist keine Aufnahme oder Einschreibung an der Schule.

• StudentId: Schüler
• GroupId: Lerngruppe
• AddedOn: Tag, an dem die Zuordnung in der App angelegt wurde
• Period: ganzes Schuljahr, erstes Halbjahr, zweites Halbjahr oder eigener Zeitraum
• JoinedAt / LeftAt: Grenzen eines eigenen Teilnahmezeitraums
• Niveau: optionale Niveaudifferenzierung

Das Schuljahr wird über die Lerngruppe ermittelt und deshalb nicht zusätzlich in der Gruppenzuordnung gespeichert. Für eine spätere echte Schulaufnahme wäre ein eigenes Feld wie Student.SchoolEntryDate zu verwenden.

Pro Kombination aus Schüler und Lerngruppe darf es höchstens eine Zuordnung geben.

Gewichtungsschema (GradingScheme)

Legt die prozentuale Gewichtung von Klausuren, Mitarbeit und sonstigen Leistungen für die Zeugnisnote fest (Kapitel 2.3/2.4). Ein Datensatz ist entweder:

• gruppenspezifisch (GroupId gesetzt, GroupType leer), oder
• eine Voreinstellung je Gruppentyp (GroupType gesetzt, GroupId leer, in den Einstellungen gepflegt).

Bei der Zeugnisnotenberechnung wird zuerst nach einem gruppenspezifischen Schema gesucht, sonst nach der Voreinstellung des Gruppentyps, sonst greift ein fest codierter Fallback (50/40/10).

Zeugnisnote (ReportGrade)

Eine Zeugnisnote gehört zu genau einem Schüler, einer Lerngruppe und einem Zeitraum (Period: "Gesamtes Schuljahr" / "1. Halbjahr" / "2. Halbjahr" — freier Text, keine Verknüpfung zu MembershipPeriod). CalculatedValue ist das zuletzt berechnete Ergebnis, OverrideValue überschreibt es bei pädagogischem Ermessen und erfordert OverrideReason. Nach dem Festschreiben (IsLocked) wird der Datensatz bei einer Neuberechnung nicht mehr verändert.

Bewusst gespeicherte Momentaufnahmen

Einige berechnete Werte bleiben absichtlich gespeichert:

• ExamResult.TotalPoints und ExamResult.Grade halten das zuletzt berechnete Klausurergebnis fest.
• Exam.GradingKey hält den für die konkrete Klausur verwendeten Notenschlüssel fest und ist unabhängig von später geänderten Vorlagen.
• Exam.Tasks hält die Aufgabenstruktur der konkreten Klausur fest.

Änderungen an Aufgaben oder Notenschlüssel müssen die betroffenen Ergebnisse kontrolliert neu berechnen. Diese Werte sind daher fachliche Momentaufnahmen und nicht bloß unkontrollierte Kopien.

Bewusste Denormalisierung

Lesson.GroupId bleibt zusätzlich zu Lesson.UnitId gespeichert. Dadurch kann der häufige Kalenderzugriff auf alle Stunden einer Lerngruppe direkt indiziert werden. Beim späteren Ausbau der Unterrichtsplanung muss sichergestellt werden, dass Lesson.GroupId mit der Lerngruppe der zugehörigen Einheit übereinstimmt.

Eindeutige Schlüssel

Die Datenbank schützt folgende Kombinationen mit eindeutigen Indizes:

• Gruppenzuordnung: StudentId + GroupId
• Klausurergebnis: ExamId + StudentId
• Mitarbeitseintrag: SessionId + StudentId
• Zeugnisnote: StudentId + GroupId + Period
• Fach: normalisierter Fachname

Altdaten werden beim Öffnen der Datenbank automatisch migriert. Die Migration verknüpft bisherige Fachtexte mit den Fachstammdaten, benennt die bisherige enrollments-Collection in group_memberships um und entfernt daraus das doppelt gespeicherte Schuljahr.