aufräumen

docs/Datenmodell.md

@@ -0,0 +1,73 @@
+# 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.
+
+## 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`
+- 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.