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.8.0] – 2026-09-11

Lernzielkontrollen – und die strengste Zusage des ganzen Auftrags eingelöst.

### Hinzugefügt

- **Freigabe durch den Ausbilder**: Vorher sieht der Azubi die Fragen gar
  nicht. Eine Freigabe lässt sich zurücknehmen, solange nicht abgegeben wurde
- **Fragebogen** mit offenen Fragen und Punktzahl je Frage; die Antworten
  werden beim Tippen zwischengespeichert, mit Zeitstempel in der Kopfzeile.
  Eine Kontrolle dauert 45 Minuten – ein verlorener Text wäre nicht
  wiedergutzumachen
- **Musterlösungen erst nach dem Absenden.** Die Sperre sitzt serverseitig in
  `sichtbareKontrolle()`: Die Lösung wird aus den Daten entfernt, **bevor** sie
  in die Ausgabe gelangt – nicht erst in der Oberfläche versteckt. Wer den
  Seitenquelltext liest oder die Serverantwort mitschneidet, findet nichts
- **Korrektur**: Antwort des Azubis und Musterlösung nebeneinander, Punktefeld
  und Anmerkung je Frage, Anmerkung zur ganzen Kontrolle. Summe, Prozentsatz
  und Note laufen beim Verteilen der Punkte mit
- **Notenschlüssel der IHK** (92/81/67/50/30 Prozent). Solange eine Frage ohne
  Punkte ist, gilt das Ergebnis als vorläufig und die Kontrolle nicht als
  korrigiert
- Ergebnis erscheint bei beiden; die Übersicht des Azubis zeigt zusätzlich den
  Schnitt über alle korrigierten Kontrollen
- Abgegebene, noch nicht korrigierte Kontrollen erscheinen beim Ausbilder unter
  „Was auf dich wartet"
- Abgegebene Kontrollen zählen im Wochenfortschritt mit
- 36 Tests, davon 21 allein für die Sichtbarkeit der Musterlösung – für jeden
  Betrachter und jeden Zustand einzeln

### Geprüft

Der Wortlaut der Musterlösungen wurde im rohen Seitenquelltext gesucht, in
jedem Zustand. Vor der Abgabe: kein einziger Treffer. Nach der Abgabe: alle
fünf. Der Prüfaufbau weist sich damit selbst als tauglich aus – er findet die
Lösungen, wenn sie da sein dürfen.

## [0.7.0] – 2026-09-10

Das Berichtsheft – der Teil, ohne den es keine Zulassung zur Abschlussprüfung
gibt.

### Hinzugefügt

- **Tägliche Stichworte**: je Werktag ein eigenes kleines Formular mit Text und
  Stundenzahl. Bewusst je Tag getrennt absendbar, damit es am Handy in zwei
  Minuten geht und nicht die ganze Woche neu geschrieben wird
- **Wochenblatt** mit Berichtszeitraum, betrieblichen Tätigkeiten und
  Unterweisungen (je mit Stundenangabe), Berufsschule (Lernfeld, Themen,
  Stunden) und Sonstiges; Zeilen lassen sich hinzufügen und entfernen
- **Vorschläge aus dem System**: aus den Tagesnotizen der Woche, den in dieser
  Woche abgegebenen oder abgenommenen Praxisaufgaben, den abgeschlossenen
  Checklisten-Durchläufen und den gelesenen Handouts. Ein Klick übernimmt den
  Vorschlag ins Blatt, wo er bearbeitet wird
- **Prüfung vor dem Absenden**, mitlaufend beim Tippen:
  - fehlende oder unglaubwürdige Stundenangaben, Wochensumme
  - Floskeln wie „diverse Arbeiten" oder „wie in der Vorwoche" – aber nur, wenn
    die Floskel den Eintrag ausmacht oder kein Tätigkeitsverb vorkommt
  - IP- und MAC-Adressen, E-Mail-Adressen, Zugangsdaten, Telefonnummern und
    Kundennamen (erkannt an der Rechtsform)
  - **Warnung, keine Sperre.** Der Knopf zum Einreichen bleibt immer bedienbar
- **Formulierungshilfe**: Tätigkeitsverben nach Einsatzfeld gruppiert, sechs
  Regeln und acht Gegenüberstellungen „so besser nicht / so ist es richtig"
  samt Begründung
- **Abzeichnen**: Der Ausbilder sieht eingereichte Blätter unter „Was auf dich
  wartet", liest sie in einer Nur-Lese-Ansicht mit derselben Prüfung und kann
  abzeichnen oder zur Nacharbeit zurückgeben. Zurückgeben verlangt eine
  Anmerkung – ohne sie weiß der Azubi nicht, was zu ändern ist
- Abgezeichnete Blätter sind **gesperrt**: keine Bearbeitung, keine Vorschläge,
  kein Einreichen mehr
- **Fehlende Wochen** werden benannt: Für jede vergangene Woche ohne Blatt gibt
  es einen Knopf zum Nachtragen. Die laufende Nummer richtet sich nach dem
  Zeitraum, nicht nach dem Anlegen – wer nachträgt, bekommt die richtige Nummer
- **PDF im Layout eines üblichen IHK-Ausbildungsnachweises**: Kopffeld mit Name,
  Beruf, Ausbildungsjahr und Berichtszeitraum, gerahmte Kästen mit
  Stundenspalte und Zwischensummen, Anmerkung des Ausbilders,
  Unterschriftenzeilen für Auszubildenden und Ausbilder. Einzeln oder als
  ganzer Zeitraum mit einem Blatt je Seite
- Das Ausbildungsjahr wird aus dem Ausbildungsbeginn gerechnet
- 55 Tests für Prüfung, Vorschläge und PDF-Erzeugung

### Behoben

- Im Kopffeld des PDF liefen die beiden Spalten auseinander: `dokument.y`
  wandert bei jedem Schreibvorgang weiter und taugte nicht als Bezugspunkt
  innerhalb der Schleife
- Das Abzeichnen-Formular hatte keine `action` – der Knopf hätte nichts getan.
  Aufgefallen ist das nur, weil ESLint die ungenutzte Serveraktion gemeldet hat

## [0.6.0] – 2026-09-10

Checklisten mit Durchläufen – und der erste PDF-Export.

### Hinzugefügt

- Aus einer Checklistenvorlage wird ein **Durchlauf**, der zu einem Datum und
  wahlweise zu einem Ticket und einem Kunden oder Bereich gehört
- Schritt für Schritt abhaken, je Schritt eine Bemerkung
- Fortschritt gesamt **und je Gruppe** (Vorbereiten, Durchführen, Prüfen,
  Abschließen), jeweils als Balken mit Zahlen
- Ein Durchlauf lässt sich erst abschließen, wenn jeder Schritt abgehakt ist;
  die Meldung nennt, wie viele Schritte noch offen sind
- Abgeschlossene Durchläufe sind gesperrt und lassen sich nicht löschen – sie
  sind der Nachweis. Wieder öffnen geht, verwerfen nur, solange nichts abgehakt ist
- **PDF-Export** eines Durchlaufs: Kopfangaben, alle Gruppen mit gezeichneten
  Ankreuzkästchen, Bemerkungen, Unterschriftenzeilen für Bearbeiter und
  Ausbilder, Fußzeile mit Herkunft und Seitenzahl
- Gemeinsame PDF-Grundlage (`src/lib/pdf/grundlage.ts`) für alle künftigen
  Ausgaben – das Berichtsheft setzt darauf auf
- Der Ausbilder sieht die Durchläufe seiner Azubis und kann das PDF abrufen,
  hakt aber nichts für sie ab: Im Nachweis soll keine Arbeit stehen, die der
  Azubi nicht gemacht hat
- Titel und Schritttexte werden beim Start aus der Vorlage **kopiert**. Ein
  abgeschlossener Durchlauf bleibt damit lesbar, auch wenn die Vorlage im
  Repository später geändert oder gelöscht wird
- Abgeschlossene Durchläufe zählen im Wochenfortschritt mit
- 29 Tests für Gruppenfortschritt, Abschlussregel, PDF-Erzeugung und
  Zeichenvorrat

### Angemerkt

- Die PDF-Ausgabe nutzt die Standardschriften jedes Betrachters (Helvetica).
  Das spart eine eingebettete Schriftdatei, beschränkt den Zeichenvorrat aber
  auf WinAnsi. Umlaute, ß, €, § und ° sind enthalten; Zeichen wie ✓, ○ oder ▲
  nicht. `fuerPdf()` ersetzt sie, Ankreuzkästchen und Haken werden **gezeichnet**

## [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.8.0]: #080--2026-09-11
[0.7.0]: #070--2026-09-10
[0.6.0]: #060--2026-09-10
[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