lernbar/CHANGELOG.md

# Änderungsprotokoll

Alle nennenswerten Änderungen an der Lern-Bar stehen hier.
Aufbau nach [Keep a Changelog](https://keepachangelog.com/de/1.1.0/),
Versionsnummern nach [Semantischer Versionierung](https://semver.org/lang/de/).

## Wie versioniert wird

- **Patch** (0.1.**x**) – Fehlerbehebungen, Textkorrekturen, Inhaltsänderungen
- **Minor** (0.**x**.0) – ein neuer Baustein aus dem [Fahrplan](ROADMAP.md)
- **Major** (**x**.0.0) – 1.0.0 ist die erste abnahmefähige Fassung; danach
  nur noch bei Änderungen, die einen Eingriff beim Betrieb erfordern
  (Datenformat, Umgebungsvariablen, Betriebsablauf)

Eine Fassung wird so festgeschrieben:

```bash
npm version minor -m "Fassung %s"   # hebt package.json und setzt ein Git-Etikett
git push --follow-tags
```

Vor `npm version` wandert der Abschnitt „Unveröffentlicht" unter eine neue
Überschrift mit Nummer und Datum.

---

## [Unveröffentlicht]

## [0.5.0] – 2026-09-10

Praxisaufgaben: bearbeiten, belegen, abnehmen.

### Hinzugefügt

- Bearbeitungsstand je Aufgabe: *offen*, *in Arbeit*, *zur Abnahme*,
  *abgenommen*; Beginn und Abgabe werden mit Zeitstempel vermerkt
- Notizfeld für den Azubi (bis 8000 Zeichen) – dieselben Notizen helfen später
  beim Berichtsheft
- **Dateianhänge**: Fotos vom Aufbau, Bildschirmfotos, ein Netzplan als PDF.
  Bis 25 MB je Datei, Positivliste erlaubter Typen (JPEG, PNG, WebP, GIF, HEIC,
  PDF, Text, CSV)
  - Der Speicherpfad wird ausschließlich aus einer selbst erzeugten UUID
    gebildet, nie aus dem übermittelten Dateinamen
  - Ausgeliefert wird nur über `/anhaenge/<kennung>`, mit Rechteprüfung bei
    **jedem** Abruf und `Content-Security-Policy: sandbox`, damit ein Anhang
    nicht im Kontext der Anwendung ausgeführt werden kann
  - SVG ist ausdrücklich nicht erlaubt – es kann Skripte enthalten
- Der Ausbilder hakt die Bewertungskriterien einzeln ab, vergibt eine Note oder
  kurze Bewertung und schreibt eine Rückmeldung
- Abnehmen sperrt die Aufgabe für den Azubi; Zurückgeben setzt sie auf
  „in Arbeit", damit er nacharbeiten kann
- „Was auf dich wartet" auf der Ausbilderstartseite zeigt die offenen Abnahmen
  mit Azubi und Abgabezeitpunkt
- Abgenommene Aufgaben zählen im Wochenfortschritt mit
- Eigene Seite „Nicht gefunden" für den angemeldeten Bereich
- 24 Tests für Dateiprüfung, Namenssäuberung, Speicherpfad und Pfadausbruch

### Behoben

- **Anhänge über 1 MB scheiterten stillschweigend.** Next.js deckelt
  Serveraktionen ab Werk bei 1 MB – damit wäre kein einziges Handyfoto
  durchgekommen, obwohl die Anwendung 25 MB zusagt. `bodySizeLimit` steht jetzt
  auf 30 MB, und zu große Dateien werden schon im Browser abgefangen, bevor sie
  übertragen werden. Im Beispiel für den Reverse Proxy steht
  `client_max_body_size` entsprechend auf 30m

### Geändert

- Seiten verweigern fremde Daten jetzt mit **404** statt mit einem Fehler.
  Damit verrät die Anwendung nicht, ob es die angefragten Daten überhaupt gibt –
  und der Benutzer sieht einen deutschen Satz statt „Application error".
  Serveraktionen brechen weiterhin hart ab

## [0.4.0] – 2026-09-10

Merkkarten mit Wiederholung nach Zeitabstand – der tägliche kleine Stapel
statt aller Karten auf einmal.

### Hinzugefügt

- **Wiederholungsverfahren** als abgespecktes SM-2: drei Bewertungsstufen
  statt sechs (*sitzt*, *unsicher*, *nochmal*), weil im Alltag niemand
  zwischen „fast richtig" und „mit Mühe richtig" unterscheidet
  - Erste beiden Abstände fest bei 1 und 3 Tagen, danach greift die
    Leichtigkeit (1,3 bis 2,8)
  - Abstände wachsen zu 1, 3, 8, 22, 62, 174 Tagen, gedeckelt bei einem
    halben Jahr
  - „nochmal" setzt die Zählung zurück und bringt die Karte **noch in
    derselben Sitzung** wieder – sonst wäre die Bewertung folgenlos
- Täglich fälliger Stapel, gedeckelt auf 20 Karten. Überfällige zuerst, nie
  gelernte zuletzt: Wer drei Wochen ausgesetzt hat, findet nicht 52 Karten vor,
  sondern die dringendsten 20
- Fünf Fächer im Sinne der Leitner-Kartei, nur zur Anzeige – abgeleitet aus dem
  Abstand, damit niemand über Leichtigkeitswerte nachdenken muss
- Filter nach Themenblock, für gezieltes Üben vor einer Lernzielkontrolle
- **Lernmodus fürs Handy**: ganzflächige Karte, Antippen zum Umdrehen, Wischen
  nach rechts für „sitzt" und nach links für „nochmal", drei Knöpfe mit
  mindestens 76 Pixeln Höhe, kein Überfahren mit der Maus
- Am Rechner zusätzlich Leertaste zum Umdrehen und die Tasten 1, 2, 3
- Kartenübersicht: heute fällig, Stand je Themenblock, Verteilung über die
  Fächer, die nächsten fünf fälligen Karten
- Tabellen `karte` (Lernstand) und `karten_verlauf` (jede einzelne Bewertung
  mit Zeitstempel, Grundlage der späteren Auswertung)
- Merkkarten zählen im Wochenfortschritt mit; als gelernt gilt eine Karte ab
  Fach 4, also wenn sie mindestens eine Woche weggelegt wurde
- 29 Tests für Abstände, Leichtigkeitsgrenzen, Fächer und Stapelauswahl

### Geändert

- Kopfzeile auf schmalen Bildschirmen: Marke und Bedienung in einer Zeile,
  Navigation darunter in einer schiebbaren Zeile statt über drei Zeilen umbrechend
- `-webkit-tap-highlight-color` abgeschaltet – der Browser legte beim Antippen
  eine blaue Fläche über die Lernkarte

## [0.3.0] – 2026-09-10

Der Wochenplan wird zur Startseite, und der Ausbilder kann ihn umplanen.

### Hinzugefügt

- **Wochenplan als Startseite des Azubis**: Woche, Thema, Leitfrage, Wochenziel,
  die fünf Tage mit Theorie- und Praxisteil, hervorgehobener heutiger Tag,
  Fortschrittsbalken und eine Liste dessen, was noch offen ist
- Der Ausbilder sieht auf seiner Startseite je Azubi die laufende Woche mit
  Fortschritt und offenen Punkten, mit Sprung in die Wocheneinzelansicht
- `/woche/<nr>` zeigt jede beliebige Woche; der Ausbilder wählt über `?azubi=`,
  wessen Stand er sieht – geprüft wird das serverseitig bei jedem Aufruf
- Tabelle `wochenplanung` mit geplantem und tatsächlichem Datum, Zustand
  (`geplant` / `laufend` / `abgeschlossen`) und einer Notiz für den Azubi
- Wochenplanseite für den Ausbilder:
  - Plan aus den Wochen des Repositorys erzeugen und fehlende Wochen anhängen
  - Woche auf ein neues Datum verlegen, wahlweise mit allen folgenden Wochen;
    ein beliebiges Datum wird auf den Montag seiner Woche gerundet
  - Reihenfolge per Ziehen und Ablegen ändern – die Terminfolge bleibt fest,
    nur die Zuordnung wechselt, damit der Plan lückenlos bleibt
  - Dasselbe mit der Tastatur über Alt + Pfeil hoch/runter, damit die Funktion
    nicht auf die Maus angewiesen ist
  - Zustand je Woche setzen; beim Start wird das tatsächliche Datum vermerkt
  - Notiz je Woche, die der Azubi in seiner Wochenansicht sieht
  - Warnung, wenn sich nach einem Einzelverschieben Termine überlappen
- Der Wochenplan entsteht automatisch, sobald ein Azubikonto angelegt wird
- Fortschrittsrechnung als reine Funktion über Zählwerte, damit sie mit den
  weiteren Bausteinen wachsen kann, ohne sich zu verzweigen
- 36 Tests für Planerzeugung, Verschieben, Umsortieren, „welche Woche ist dran"
  und die Fortschrittsrechnung

### Angemerkt

- Praxisaufgaben, Checklisten und Lernzielkontrollen erscheinen im
  Fortschritt bereits mit ihrer Sollzahl, lassen sich aber erst mit den
  Bausteinen 5 bis 8 abhaken. Das ist Absicht: Die Woche zeigt, was ansteht,
  auch wenn die Anwendung es noch nicht mitzählen kann

## [0.2.0] – 2026-09-10

Die Inhalte kommen ins Spiel: Handouts, Suche, Glossar – alles aus Dateien
im Repository, beim Start geprüft.

### Hinzugefügt

- Inhaltslader für `content/`: YAML und Markdown mit YAML-Kopf, Prüfung über
  Zod-Schemata, Aufbau aller Querverweise
- **Fehlermeldungen mit Datei und Zeile.** Fehler werden gesammelt statt beim
  ersten geworfen – wer zehn Tippfehler eingebaut hat, sieht sie in einem
  Durchgang. Die Zeilennummer stammt aus dem YAML-Dokumentmodell, nicht aus
  einer Schätzung
- Geprüft wird unter anderem: Existenz jeder referenzierten Kennung, Zugehörigkeit
  jedes Handouts zu genau einer Woche (in beide Richtungen), Kürzel passend zum
  Themenblock, Berufsbildpositionen und Lernfelder gegen `rahmenplan.yaml`,
  lückenlose Wochennummerierung, doppelte Kennungen, Glossarverweise ins Leere
- `npm run inhalte:pruefen` prüft ohne Start und meldet zusätzlich, welche
  Berufsbildpositionen bisher von keinem Inhalt berührt werden
- Handout-Ansicht mit dem festen Aufbau: Kürzel, Titel, „Worum es geht",
  Das Wesentliche, Übersicht, hervorgehobener Merksatz, eingeklappte
  Prüfungsfrage; dazu die Zuordnung zu Rahmenplan, Lernfeld und Woche
- Handout-Übersicht nach Themenblöcken, Filter je Block, Lesestand je Block
- Volltextsuche über Titel, Kurzbeschreibung, Merksatz, Merkkarten und
  Fließtext – mit Gewichtung und Trefferausschnitt, unempfindlich gegen
  Umlaute und Großschreibung
- „Als gelesen markieren" je Handout, gespeichert je Benutzer
- Glossar mit Suche; Begriffe werden in den Handouts automatisch verlinkt –
  höchstens einmal je Seite, nie in Code, Überschriften oder bestehenden
  Verweisen. Der Verweis ist ein echter Link mit Erklärung im title-Attribut,
  damit er auch am Handy und mit der Tastatur nutzbar ist
- Neu einlesen bei Dateiänderung im Entwicklungsbetrieb; schlägt das fehl,
  bleibt der bisherige Stand aktiv und der Fehler steht im Protokoll
- Beispielinhalte: 4 Wochen, 12 Handouts mit 24 Merkkarten, 4 Praxisaufgaben,
  4 Checklisten, 2 Lernzielkontrollen mit Musterlösungen, 24 Glossareinträge
- `content/rahmenplan.yaml` mit allen Berufsbildpositionen der FIAusbV 2020
  (Abschnitte A, C und F, hier als A1–A10, B1–B3, C1–C5) samt amtlicher
  Fundstelle sowie allen zwölf Lernfeldern des KMK-Rahmenlehrplans
- `npm run screenshots` nimmt die Bilder für die Anleitung automatisiert auf

### Geändert

- `gray-matter` entfernt: Der YAML-Kopf wird selbst herausgelöst. Die Bibliothek
  merkt sich Ergebnisse und lieferte beim zweiten Einlesen desselben Textes ein
  anderes Objekt; außerdem stimmt der Zeilenversatz für Fehlermeldungen jetzt
  garantiert

## [0.1.0] – 2026-09-10

Erster Baustein: das Fundament steht, die Anwendung lässt sich starten,
anmelden und verwalten.

### Hinzugefügt

- Projektgerüst mit Next.js 15 (App Router), React 19, TypeScript
- SQLite über Drizzle ORM; der gesamte Datenzugriff liegt hinter einer
  Repository-Schicht, damit ein späterer Wechsel auf PostgreSQL kein Umbau ist
- Eigener Migrationslauf: `src/lib/db/migrationen/*.sql` werden beim Start
  einmalig angewendet und mit Prüfsumme vermerkt; nachträgliche Änderungen an
  bereits angewendeten Dateien lassen die Anwendung mit klarer Meldung abbrechen
- Anmeldung mit Argon2id, serverseitigen Sitzungen, HttpOnly-Cookie und
  `SameSite=Lax`; im Cookie steht nur ein Zufallswert, gespeichert wird dessen
  SHA-256-Abdruck
- Zwei Rollen (`ausbilder`, `azubi`); die Rechteregeln liegen als reine
  Funktionen in `src/lib/auth/regeln.ts` und sind vollständig testbar
- Verwaltungsbereich für den Ausbilder: Azubikonto samt Ausbildung anlegen,
  Eckdaten ändern, Passwort setzen, Konto sperren und entsperren
- Gestaltung in Petrol/Bernstein, helle und dunkle Darstellung mit Umschalter
  in der Kopfzeile, nur Systemschriften, keine Ressourcen von außen
- Zeitrechnung für Europe/Berlin und Kalenderwochen nach ISO 8601
- Mehrstufiges Dockerfile, `docker-compose.yml` mit einem Dienst und einem
  Volume, Lebenszeichen unter `/api/gesundheit`
- `update.sh` für den Linux-Server: sichert, holt den Quelltext, baut, schaltet
  um und fällt bei fehlendem Lebenszeichen automatisch auf die vorherige
  Fassung zurück
- `sicherung.sh` und `wiederherstellen.sh` für Datenbank und Anhänge
- `npm run konto:anlegen` für das erste Ausbilderkonto

[Unveröffentlicht]: #unveröffentlicht
[0.5.0]: #050--2026-09-10
[0.4.0]: #040--2026-09-10
[0.3.0]: #030--2026-09-10
[0.2.0]: #020--2026-09-10
[0.1.0]: #010--2026-09-10