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.

## Bildungsplan-Version (`CompetencyCatalogVersion`)

Bildet ab, dass für ein Fach mehrere Kompetenzkataloge parallel gültig sein können — typischerweise
weil ein neuer Bildungsplan klassenstufenweise hochwächst (z.B. beginnend in Klasse 5, ein Jahrgang
pro Schuljahr) und deshalb über mehrere Schuljahre hinweg sowohl der alte als auch der neue Plan
gleichzeitig unterrichtet werden.

- `SubjectId`: Fach, zu dem die Version gehört
- `Name`: frei gewählte Bezeichnung, z.B. `Bildungsplan 2016` oder `Bildungsplan 2026`
- `IsDefault`: je Fach höchstens eine Version — Kurse ohne explizite Wahl (siehe
  `LearningGroup.CompetencyCatalogVersionId`) nutzen sie. `CompetencyCatalogVersionRepository.Save`
  nimmt beim Setzen automatisch die bisherige Standardversion desselben Fachs zurück.

`CompetencyDomain.VersionId` verweist auf die Version, zu der ein Kompetenzbereich gehört — derselbe
Katalog-Slot (Fach + Klassenstufe) kann also mehrfach existieren, einmal je Version.
`LearningGroup.CompetencyCatalogVersionId` (`Guid?`) wählt je Kurs/Klasse, welche Version gilt.
Analog zum Verhältnis von `GroupMembership` zu `LearningGroup.SchoolYear` (siehe oben) ist dieses
Feld bewusst nullable mit einer Sonderbedeutung: `null` heißt nicht "keine Version", sondern "die
Standardversion des Fachs" — so brauchen bestehende Kurse und Kompetenzkataloge beim Einführen der
Versionierung keine Migration außer dem einmaligen Anlegen je einer Standardversion pro Fach
(`LiteDbContext.MigrateCompetencyCatalogVersions`, Schema-Version 5).

`CompetencyCatalogVersionRepository.Delete` blockiert (statt in den Papierkorb zu verschieben, siehe
14.2), wenn die Version noch von einem Kompetenzbereich oder einem Kurs referenziert wird, oder wenn
sie die Standardversion ihres Fachs ist — erst eine andere Version des Fachs muss zum Standard
werden, damit nie ein Fach ganz ohne Standardversion dasteht.

Bewusst **nicht** Teil dieser Versionierung: die Verknüpfung von Kompetenzcodes zu Unterrichtseinheiten,
Einzelstunden und Klausuraufgaben (`Unit.Competencies`, `Lesson.Competencies`, `ExamTask.CompetencyCodes`)
bleibt Freitext-Code-basiert, nicht auf `CompetencyItem.Id` umgestellt — ein vorbestehendes, unabhängiges
Thema (siehe TODO 16.5).

## 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.

Die beiden Halbjahre werden jeweils aus den Einzelleistungen ihres Zeitraums berechnet und sind
voneinander unabhängig. "Gesamtes Schuljahr" wird dagegen aus den Halbjahresnoten verrechnet
(gleich gewichtet), nicht aus allen Einzelleistungen des Jahres.

Vier Felder sind nur am Jahres-Datensatz einer 10. Klasse belegt und halten Prüfungsnoten fest,
soweit die Prüfung in diesem Fach abgelegt wurde:

- `WrittenExamGrade` / `OralExamGrade`: schriftliche bzw. mündliche Abschlussprüfung. Ein Fach
  hat höchstens eine von beiden. Die Prüfungsleistung geht mit einem Drittel in die Endnote ein,
  die unterrichtliche Leistung (beide Halbjahre) mit zwei Dritteln — § 14 Abs. 3 der Verordnung
  über die Sekundarstufe I der Oberschule.
- `AdditionalOralExamGrade`: zusätzliche mündliche Prüfung ("Nachprüfung"). Im schriftlichen
  Prüfungsfach wird sie 1:1 mit der schriftlichen Prüfung zur Prüfungsleistung verrechnet
  (§ 13 Abs. 2 PrüfV Sek. I). In einem Fach ohne Abschlussprüfung ist sie selbst die
  Prüfungsleistung, also 2:1 (§ 13 Abs. 3 PrüfV Sek. I).
- `ProjectExamGrade`: Projektprüfung, zählt wie ein weiteres Halbjahr. Das ist die Praxis der
  Schule; der Wortlaut der Verordnung (§ 4a Abs. 3: fließt in die Halbjahresnote des
  zugeordneten Fachs ein) wird bewusst nicht nachgebildet.

Die Rundungsvorgaben der Verordnungen sind bewusst nicht umgesetzt: Noten sind
Leistungsbewertungen, die Entscheidung zwischen zwei Noten ist pädagogisch. Eine Prüfungsleistung
zwischen zwei Noten geht ungerundet in die Rechnung ein; für die Endnote gilt die von der
Lehrkraft gewählte Rundung, und der Assistent weist darauf hin, wenn der Wert genau zwischen
zwei Noten liegt. Stand der Verordnungen: Oberschulverordnung in der Fassung von Juni 2025.

## Zwischenstand (`InterimGrade`)

Ein Zwischenstand ist eine vorläufige Note zu einem Stichtag (`Date`), wie sie zu einem Anlass
(`Occasion`, freier Text wie "Sprechtag" oder "Elternanfrage: Frau Muster") genannt wurde. Er ist
bewusst kein Zustand der Zeugnisnote, sondern ein eigener Datensatz: es kann mehrere je Halbjahr
geben, und keiner beeinflusst `ReportGrade`. Zwischenstände einer Lerngruppe mit gleichem `Date`
und `Occasion` bilden zusammen einen Durchgang — es gibt dafür keinen eigenen Datensatz.

`WrittenValue`, `OralValue` und `OverallValue` sind die tatsächlich genannten Noten, nicht der
berechnete Vorschlag; die Lehrkraft kann sie beim Notieren anpassen. `OralValue` meint die
Mitarbeit inklusive des am Stichtag laufenden, noch nicht abgeschlossenen Abschnitts.

## 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.
- `ExamTask.Variant` ist bei gemeinsamen Aufgaben null, sonst `A` oder `B`.
  `ExamResult.Variant` wählt die Fassung je Schüler. `ExamTask.IsBonus` nimmt die
  Maximalpunkte aus dem Grundwert des Notenschlüssels; erreichte Bonuspunkte zählen
  weiterhin zum Ergebnis.
- `Exam.RepeatOfExamId` verweist auf die ursprüngliche Arbeit derselben Gruppe.
  `RepeatGradeRule` legt fest, ob die bessere, die wiederholte oder die erste Note
  zählt. Beide Ergebnisse bleiben sichtbar, gehen aber als ein Wert in die
  berechneten Durchschnitts- und Zeugnisnoten ein.
- `CompetencyReference` (`Unit.Competencies`, `Lesson.Competencies`, `ExamTask.Competencies`,
  `ParticipationSession.Competencies`) verweist über `ItemId` auf ein `CompetencyItem`, hält aber
  zusätzlich `Code`/`Description` zum Zuordnungszeitpunkt fest (TODO 16.5, abgelöst von einer reinen
  Freitext-Code-Zuordnung). Solange `ItemId` noch im Katalog auflösbar ist, zeigt die Anwendung die
  **live** Fassung (ein Rename im Katalog wirkt sich überall sofort aus); wird das Item gelöscht,
  bleibt die hier gespeicherte historische Fassung lesbar statt spurlos zu verschwinden.
  `ItemId == Guid.Empty` markiert eine nie aufgelöste Referenz (z.B. aus einem
  plattformübergreifenden `PlanningExchangeService`-Import, der bewusst keine installationsfremden
  IDs überträgt) — Code/Description sind dann die einzige Information.
  `CompetencyRating.ItemId` (Mitarbeit, je Schüler) referenziert ebenso per Id, aber ohne eigenen
  Snapshot — die Identität kommt aus der Zuordnungsliste der zugehörigen `ParticipationSession`,
  die bereits eine Momentaufnahme trägt.

Ä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.

Umgesetzt in `PlanningTabViewModel` (Kapitel 4.1/4.2): Beim Kopieren einer Einheit
als Vorlage in eine andere Gruppe (4.1.4) wird `Lesson.GroupId` auf jeder neu
erzeugten Stunde explizit auf die Zielgruppe gesetzt, nicht von der Quell-Lesson
übernommen. Beim Verschieben einer Stunde inkl. Nachrücken der Folgestunden (4.2.4)
ändert sich ausschließlich `Lesson.Date` — `UnitId`/`GroupId` bleiben unangetastet.

## Stundenverlaufsplan (`Lesson.Phases`)

Eine Stunde hat statt eines einzelnen `Phase`-Textfelds plus Methoden-/Materialien-Listen eine
geordnete Liste `Lesson.Phases: List<LessonPhaseStep>` (Name, Dauer in Minuten, Tätigkeit,
Material, Kurzsymbol `Shorthand`). `DurationMinutes` ist die primäre, vom Nutzer gepflegte Größe;
die im Editor angezeigte Uhrzeit je Phase ist rein abgeleitet (kumulierte Dauer ab
`Lesson.StartTime`, sofern gesetzt) und wird nirgends persistiert — es gibt also keine
Konsistenzpflicht zwischen gespeicherter Dauer und einer gespeicherten Uhrzeit, weil Letztere gar
nicht gespeichert wird.

`Shorthand` ist bewusst ein einzelnes Freitextfeld statt einer erzwungenen Von/Nach-Struktur: in
der Praxis ist es mal ein Materialfluss-Pfeil ("AB001->S"), mal nur eine Sozialform ohne Pfeil
("Plenum", "LDE"). Der Kürzel-Katalog (`ShorthandCode`, Einstellungen) und bereits in anderen
Stunden verwendete Werte dienen nur als Autovervollständigungs-Vorschläge, erzwingen aber keine
Struktur.

`AlternativePathId` (`Guid?`, `null` = Hauptweg) verweist auf einen Eintrag im eigenständigen
Katalog `AlternativeLessonPath` (Name + optionale `Description`, verwaltet über
`IAlternativeLessonPathRepository`) — anders als `Shorthand` bewusst kein Freitext direkt am
Phasen-Datensatz: die Zuordnung muss zuverlässig gruppierbar sein (`LessonViewerViewModel`
gruppiert danach für die Anzeige) und soll eine wiederverwendbare Erklärung tragen können ("wann
nimmt man diesen Weg"), was ein reines Freitextfeld nicht sauber leisten kann. Kein
Fork-Punkt-Bezug zum Hauptweg: jede Gruppe wird beim Anzeigen unabhängig ab `Lesson.StartTime`
durchgerechnet, nicht ab einer gemeinsamen Verzweigungsstelle.

`LiteDbContext`-Schema-Version 4 führt drei aufeinanderfolgende, unabhängig versionierte
Migrationsschritte für dieses Feld bzw. seine Vorstufen:
- **v1→v2** (`MigrateLessonPhases()`): führt bereits gespeicherte alte Stunden (einzelnes
  `Phase`-Feld, `Methods`/`Materials`-Listen) verlustfrei in eine einzige synthetisierte
  `LessonPhaseStep`-Zeile zusammen (`Name` = altes `Phase`, `Activity` = alte `Methods` verbunden,
  `Material` = alte `Materials` verbunden, `DurationMinutes = 0` da unbekannt).
- **v2→v3** (`MigrateLessonShorthand()`): das ursprünglich als Von/Nach-Paar (`ShorthandFrom`/
  `ShorthandTo`) modellierte Kurzsymbol wird auf das einzelne Freitextfeld zusammengeführt (beide
  gesetzt → `"Von->Nach"`, nur eines gesetzt → dieser Einzelwert).
- **v3→v4** (`MigrateLessonAlternativePaths()`): das ursprünglich als Freitext (`AlternativePath`,
  string) modellierte Kennzeichen für den alternativen Ablauf wird pro distinktem Namen zu einem
  `AlternativeLessonPath`-Katalogeintrag zusammengeführt (derselbe Name über mehrere Stunden hinweg
  referenziert denselben, wiederverwendeten Eintrag) und die Phase auf `AlternativePathId`
  umgestellt.

Alle drei Migrationen lesen dafür die rohe `BsonDocument`-Repräsentation der `lessons`-Collection
statt der typisierten `Lessons`-Collection — nach jeder Modelländerung kennt die typisierte
`Lesson`-Klasse die alten Feldnamen nicht mehr, ein Zugriff darüber hätte sie beim Deserialisieren
bereits verworfen, bevor sie gelesen werden können.

`LessonPhaseStep.MaterialPrompt` (4.5.36, Nachtrag zu 4.5.20) ist kein von Hand gepflegtes Feld:
`AiPlanningService.ApplyResponse` befüllt es automatisch mit dem vollständigen, lokal erzeugten
Prompt (`BuildMaterialPrompt`), sobald die KI beim letzten "Übernehmen" für diese Phase einen
Medienvorschlag gemacht hatte — ursprünglich (4.5.20) bewusst NICHT persistiert, weil der Vorschlag
nur für die Review-Anzeige gedacht war; Nutzer-Feedback nach erstem Einsatz war, dass der Prompt
auch nach dem Übernehmen noch abrufbar bleiben soll. Kein neues "Material"-Domänenmodell dafür (das
gibt es weiterhin nicht, siehe 4.5.26) — der Prompt hängt einfach als zusätzliches Freitextfeld an
der bereits bestehenden `LessonPhaseStep`-Zeile.

## 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.