Florian WildeandClaude Opus 5
c61d5711e0
docs/ANLEITUNG.md: 20 Abschnitte, 27 Bildschirmfotos, getrennt fuer Ausbilder und Azubi, dazu "Wenn etwas nicht geht". Die Bilder entstehen automatisiert ueber npm run screenshots - was dort steht, ist gemessen und nicht gemalt. scripts/pruefungen/abnahme.mjs (npm run abnahme) laeuft gegen eine frische, leere Datenbank in einem Wegwerfverzeichnis: aufsetzen, Konten anlegen, arbeiten, abnehmen, sichern, beschaedigen, zurueckspielen. Eine Sicherung, die nie zurueckgespielt wurde, ist keine Sicherung. 33 von 33 Pruefungen erfuellt, Protokoll in docs/ABNAHME.md. Dabei drei echte Fehler gefunden, alle in Wegen, die nie ausgefuehrt worden waren: - Die Sicherungsskripte liefen nicht in Git Bash, obwohl das in ihrem Kopf stand: tar deutet den Doppelpunkt in "C:\..." als Rechnernamen. Beide wechseln jetzt erst ins Verzeichnis und uebergeben einen blossen Dateinamen. - Auf einer frischen Datenbank gibt es noch kein Wochenblatt; der Weg jedes neuen Azubis war nie durchlaufen worden. - Der Abnahmelauf selbst liess unter Windows seinen Server ueberleben (kill() beendet nur die cmd.exe) und prueft deshalb jetzt vorher, ob der Port frei ist - sonst haette er gegen fremde Daten geprueft. Fassung 1.0.0: package.json stand noch auf 0.1.0, waehrend das Aenderungsprotokoll bei 0.9.0 war. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
413 lines
14 KiB
Markdown
413 lines
14 KiB
Markdown
# Lern-Bar – Anleitung
|
||
|
||
Diese Anleitung zeigt die Anwendung so, wie sie im Betrieb benutzt wird: erst
|
||
der Ausbilder, dann der Azubi. Wer die Lern-Bar aufsetzen will, findet das im
|
||
[README](../README.md) – hier geht es um den Umgang damit.
|
||
|
||
Die Bilder stammen aus einer laufenden Anwendung mit den Beispielinhalten und
|
||
werden mit `npm run screenshots` neu erzeugt. Was hier steht, ist also nicht
|
||
gemalt, sondern gemessen.
|
||
|
||
---
|
||
|
||
## Inhalt
|
||
|
||
**Für den Ausbilder**
|
||
|
||
1. [Anmelden](#1-anmelden)
|
||
2. [Ein Azubikonto anlegen](#2-ein-azubikonto-anlegen)
|
||
3. [Den Wochenplan festlegen](#3-den-wochenplan-festlegen)
|
||
4. [Eine Praxisaufgabe abnehmen](#4-eine-praxisaufgabe-abnehmen)
|
||
5. [Das Berichtsheft abzeichnen](#5-das-berichtsheft-abzeichnen)
|
||
6. [Eine Lernzielkontrolle korrigieren](#6-eine-lernzielkontrolle-korrigieren)
|
||
7. [Die Rahmenplanabdeckung lesen](#7-die-rahmenplanabdeckung-lesen)
|
||
8. [Ein Feedbackgespräch führen](#8-ein-feedbackgespräch-führen)
|
||
|
||
**Für den Azubi**
|
||
|
||
9. [Die Woche](#9-die-woche)
|
||
10. [Handouts lesen und suchen](#10-handouts-lesen-und-suchen)
|
||
11. [Merkkarten lernen](#11-merkkarten-lernen)
|
||
12. [Eine Praxisaufgabe abgeben](#12-eine-praxisaufgabe-abgeben)
|
||
13. [Eine Checkliste abarbeiten](#13-eine-checkliste-abarbeiten)
|
||
14. [Das Berichtsheft führen](#14-das-berichtsheft-führen)
|
||
15. [Eine Lernzielkontrolle schreiben](#15-eine-lernzielkontrolle-schreiben)
|
||
|
||
**Überall**
|
||
|
||
16. [Auf dem Handy](#16-auf-dem-handy)
|
||
17. [Ohne Netz](#17-ohne-netz)
|
||
18. [Hell und dunkel](#18-hell-und-dunkel)
|
||
19. [Drucken](#19-drucken)
|
||
20. [Wenn etwas nicht geht](#20-wenn-etwas-nicht-geht)
|
||
|
||
---
|
||
|
||
## Für den Ausbilder
|
||
|
||
### 1. Anmelden
|
||
|
||
|
||
|
||
Es gibt **keine Selbstregistrierung**. Das erste Ausbilderkonto legst du auf der
|
||
Kommandozeile an (siehe README, Abschnitt *In fünf Minuten zum laufenden
|
||
System*), alle weiteren Konten entstehen in der Verwaltung.
|
||
|
||
Nach dem Anmelden landest du auf deinem Überblick: was in dieser Woche ansteht,
|
||
was offen ist, was auf dich wartet.
|
||
|
||
|
||
|
||
---
|
||
|
||
### 2. Ein Azubikonto anlegen
|
||
|
||
**Verwaltung → Neues Azubikonto**
|
||
|
||
|
||
|
||
Du gibst Name, E-Mail-Adresse, ein erstes Passwort (mindestens 10 Zeichen) und
|
||
den Ausbildungsbeginn an; Probezeit und geplantes Ende sind freiwillig.
|
||
|
||
Das Passwort gibst du dem Azubi **persönlich** weiter – er kann es danach selbst
|
||
ändern. Einsehbar ist es danach nirgends mehr, auch für dich nicht: In der
|
||
Datenbank liegt nur ein Argon2id-Hash. Hat jemand sein Passwort vergessen,
|
||
setzt du in der Verwaltung ein neues; das alte lässt sich nicht anzeigen.
|
||
|
||
Der Ausbildungsbeginn ist wichtiger, als er aussieht. Aus ihm ergeben sich das
|
||
Ausbildungsjahr und damit die Wochennummern im Berichtsheft.
|
||
|
||
> **Ein Azubi hat genau einen Ausbilder.** Das ist keine Einschränkung, die sich
|
||
> später aufheben ließe, sondern die Grundlage der Rechteprüfung: Der Azubi
|
||
> sieht ausschließlich seine eigenen Daten, der Ausbilder die seiner Azubis.
|
||
|
||
---
|
||
|
||
### 3. Den Wochenplan festlegen
|
||
|
||
**Wochenplan**
|
||
|
||
|
||
|
||
Die Wochen selbst stehen als Dateien unter `content/wochen/`. Hier legst du
|
||
fest, **wann** welche Woche läuft, und kannst sie verschieben – Urlaub,
|
||
Berufsschulblock, ein Projekt, das dazwischenkommt.
|
||
|
||
Verschiebst du eine Woche, wandern die folgenden mit. Was der Azubi schon
|
||
erledigt hat, bleibt erledigt.
|
||
|
||
---
|
||
|
||
### 4. Eine Praxisaufgabe abnehmen
|
||
|
||
**Aufgaben → eine abgegebene Aufgabe öffnen**
|
||
|
||
|
||
|
||
Der Azubi gibt eine Aufgabe mit seiner Lösung und optional mit Anhängen ab –
|
||
meist Fotos vom Handy. Du siehst die Abnahmekriterien aus der Aufgabendatei und
|
||
hakst ab, was erfüllt ist.
|
||
|
||
Eine Aufgabe ist **abgenommen**, wenn du sie abgenommen hast. Nicht, wenn der
|
||
Azubi sie abgegeben hat. Genau dieser Unterschied macht sie später in der
|
||
Rahmenplanabdeckung zu einem belastbaren Nachweis.
|
||
|
||
Reicht etwas nicht, gibst du sie mit einer Bemerkung zurück. Der Azubi sieht,
|
||
was fehlt, und kann nachbessern.
|
||
|
||
---
|
||
|
||
### 5. Das Berichtsheft abzeichnen
|
||
|
||
**Berichtshefte → ein Wochenblatt öffnen**
|
||
|
||
|
||
|
||
Der Ausbildungsnachweis ist der einzige Teil dieser Anwendung, den das Gesetz
|
||
verlangt. Deshalb ist er der sorgfältigste.
|
||
|
||
Du liest das Blatt, siehst die Warnhinweise (leere Tage, Floskeln, mögliche
|
||
Betriebs- oder Personennamen) und zeichnest ab. **Nach dem Abzeichnen ist das
|
||
Blatt unveränderlich** – auch für dich. Willst du eine Änderung, gibst du es
|
||
frei; das wird protokolliert.
|
||
|
||
Über *Als PDF* bekommst du das Blatt im IHK-Layout, mit Unterschriftenfeldern.
|
||
Ein Beispiel liegt unter [`docs/beispiel-ausbildungsnachweis.pdf`](beispiel-ausbildungsnachweis.pdf).
|
||
|
||
---
|
||
|
||
### 6. Eine Lernzielkontrolle korrigieren
|
||
|
||
**Kontrollen**
|
||
|
||
|
||
|
||
Du gibst eine Kontrolle frei, der Azubi schreibt sie, du korrigierst. Punkte je
|
||
Frage, daraus Prozent, daraus die Note nach dem **IHK-Notenschlüssel**
|
||
(92/81/67/50/30 %).
|
||
|
||
|
||
|
||
> **Die Musterlösung bekommt der Azubi erst nach dem Absenden zu sehen.** Vorher
|
||
> ist sie über keine Schnittstelle abrufbar – nicht im HTML, nicht in der
|
||
> Nachladung, nirgends. Das wird serverseitig entschieden, nicht in der
|
||
> Oberfläche, und mit einem eigenen Prüfskript nachgewiesen
|
||
> (`scripts/pruefungen/musterloesung-dichtheit.mjs`).
|
||
|
||
---
|
||
|
||
### 7. Die Rahmenplanabdeckung lesen
|
||
|
||
**Auswertung**
|
||
|
||
|
||
|
||
Das ist die Ansicht, die gegenüber der IHK zählt. Sie beantwortet die Frage, die
|
||
im Prüfungsausschuss gestellt wird: *Ist der Ausbildungsrahmenplan abgedeckt?*
|
||
|
||
Statt „erledigt / offen" gibt es **vier Lagen**:
|
||
|
||
| Lage | Bedeutung |
|
||
|---|---|
|
||
| **vermittelt** | eine abgenommene Praxisaufgabe oder ein abgeschlossener Checklisten-Durchlauf, **oder** mindestens zwei gelesene Handouts |
|
||
| **angefangen** | etwas erledigt, aber noch nicht genug – ein gelesenes Handout allein genügt bewusst nicht |
|
||
| **geplant** | Material vorhanden, aber unbearbeitet |
|
||
| **ohne Inhalt** | zu dieser Position gibt es im ganzen Lehrgang nichts |
|
||
|
||
Die vierte Lage ist die wichtigste und wird rot ausgewiesen:
|
||
|
||
|
||
|
||
**Das ist keine Lücke beim Azubi, sondern eine im Lehrgang.** Dort hilft kein
|
||
Lernen, sondern nur ein neues Handout oder eine neue Aufgabe unter `content/`.
|
||
In den Beispielinhalten betrifft das fünf Positionen: A4, A10, C1, C2 und C5.
|
||
|
||
Jede Position führt ihre einzelnen Nachweise mit Kürzel und Zustand auf und
|
||
nennt ihre amtliche Fundstelle in der Verordnung. Wenn jemand fragt, worauf sich
|
||
die Bewertung stützt, steht die Antwort da.
|
||
|
||
---
|
||
|
||
### 8. Ein Feedbackgespräch führen
|
||
|
||
**Feedback → Neues Gespräch anlegen**
|
||
|
||
|
||
|
||
Monatlich, mit Leitfaden und Bewertungsbogen. Der Ablauf:
|
||
|
||
1. Du legst das Gespräch an und trägst **deine** Einschätzung ein: acht Kriterien
|
||
auf einer Skala von 1 bis 5, dazu Stärken, Entwicklungsfelder und die
|
||
vereinbarten Ziele.
|
||
2. Der Azubi trägt **seine** Selbsteinschätzung ein. Er sieht deine Freitexte,
|
||
kann sie aber nicht ändern – und du kannst seine Selbsteinschätzung nicht
|
||
eintragen. Eine Selbsteinschätzung, die der Ausbilder eintragen könnte, wäre
|
||
keine.
|
||
3. Wo beide um **zwei Stufen oder mehr** auseinanderliegen, wird das
|
||
hervorgehoben. Genau darüber lohnt das Gespräch – nicht über die Zahlen,
|
||
sondern über die Stellen, an denen sie auseinandergehen.
|
||
4. Beide bestätigen. Danach ist das Gespräch **unveränderlich**.
|
||
|
||
|
||
|
||
*Als PDF für die Akte* gibt beide Einschätzungen nebeneinander aus, mit
|
||
Unterschriftenfeldern. Abweichungen sind auch dort markiert.
|
||
|
||
> Die Kriterien und der Leitfaden stehen in
|
||
> `content/feedbackgespraech.yaml` und lassen sich an den eigenen Betrieb
|
||
> anpassen. Ein bereits geführtes Gespräch behält seine Fassung, auch wenn du
|
||
> die Vorlage später änderst.
|
||
|
||
---
|
||
|
||
## Für den Azubi
|
||
|
||
### 9. Die Woche
|
||
|
||
|
||
|
||
Die Startseite zeigt genau eine Woche: das Thema, was diese Woche zu tun ist,
|
||
was schon erledigt ist, was drängt. Kein Dashboard mit zwölf Kacheln – die
|
||
Frage lautet „Was mache ich jetzt?", nicht „Wie ist meine Gesamtlage?".
|
||
|
||
---
|
||
|
||
### 10. Handouts lesen und suchen
|
||
|
||
|
||
|
||
Die Handouts sind der Lesestoff: kurz, mit Beispielen, jeweils einem Thema
|
||
zugeordnet. Die Suche geht über Titel und Volltext.
|
||
|
||
|
||
|
||
|
||
|
||
Unten markierst du ein Handout als gelesen. Das ist keine Spielerei: In der
|
||
Auswertung zählen gelesene Handouts als **stützende** Nachweise für die
|
||
Rahmenplanabdeckung.
|
||
|
||
Fachbegriffe, die dir unterwegs begegnen, stehen im **Glossar** – kurz erklärt,
|
||
mit Querverweisen.
|
||
|
||
|
||
|
||
---
|
||
|
||
### 11. Merkkarten lernen
|
||
|
||
|
||
|
||
Die Karten gehören zu den Handouts und kommen nach dem Prinzip der
|
||
**Wiederholung nach Zeitabstand** wieder: Was sitzt, kommt später wieder; was
|
||
nicht sitzt, heute noch einmal.
|
||
|
||
Im Lernmodus:
|
||
|
||
- **Antippen** oder **Leertaste** – Karte umdrehen
|
||
- **1 / 2 / 3** – nochmal / unsicher / sitzt
|
||
- **Wischen** nach rechts für „sitzt", nach links für „nochmal"
|
||
|
||
Zehn Minuten am Tag reichen. Wer das durchhält, hat vor der Prüfung nichts
|
||
nachzuholen.
|
||
|
||
---
|
||
|
||
### 12. Eine Praxisaufgabe abgeben
|
||
|
||
|
||
|
||
|
||
|
||
Du liest den Auftrag, siehst die Abnahmekriterien vorher – du weißt also, woran
|
||
du gemessen wirst –, schreibst deine Lösung und hängst an, was dazugehört.
|
||
Fotos vom Handy gehen direkt.
|
||
|
||
Dann gibst du ab. Der Ausbilder nimmt ab oder gibt zurück, mit Bemerkung.
|
||
|
||
---
|
||
|
||
### 13. Eine Checkliste abarbeiten
|
||
|
||
|
||
|
||
Checklisten sind für Abläufe, die immer gleich gehen: einen Arbeitsplatz
|
||
übergeben, Windows installieren, einen Rechner zerlegen. Du startest einen
|
||
Durchlauf und hakst Schritt für Schritt ab.
|
||
|
||
|
||
|
||
Ein Durchlauf **kopiert die Schritte bei seinem Start**. Ändert jemand die
|
||
Checkliste, während du sie abarbeitest, bleibt dein Durchlauf so, wie du ihn
|
||
begonnen hast. Am Ende gibt es ein PDF – ein Beispiel liegt unter
|
||
[`docs/beispiel-checkliste.pdf`](beispiel-checkliste.pdf).
|
||
|
||
---
|
||
|
||
### 14. Das Berichtsheft führen
|
||
|
||
|
||
|
||
Pro Kalenderwoche ein Blatt, gegliedert nach Tagen, mit Stunden. Die Anwendung
|
||
hilft an drei Stellen:
|
||
|
||
- **Vorschläge** aus dem, was du in der Woche tatsächlich gemacht hast:
|
||
abgenommene Aufgaben, abgeschlossene Checklisten, gelesene Handouts.
|
||
- **Prüfung vor dem Abgeben**: leere Tage, Floskeln („diverse Tätigkeiten",
|
||
„wie immer"), verdächtige Namen von Firmen oder Personen. Der
|
||
Ausbildungsnachweis geht an die IHK – da haben Kundennamen nichts verloren.
|
||
- **Formulierungshilfe**: aus „Drucker repariert" wird „Fehlerbild aufgenommen,
|
||
Fixiereinheit getauscht, Testdruck geprüft, Ticket dokumentiert".
|
||
|
||
Nach dem Abzeichnen ist das Blatt unveränderlich.
|
||
|
||
---
|
||
|
||
### 15. Eine Lernzielkontrolle schreiben
|
||
|
||
Der Ausbilder gibt die Kontrolle frei, du siehst sie unter *Kontrollen*. Du
|
||
schreibst deine Antworten und sendest ab.
|
||
|
||
**Erst nach dem Absenden** siehst du die Musterlösung – vorher nicht, und auch
|
||
nicht über Umwege. Das ist keine Gängelei, sondern der Sinn der Sache: Eine
|
||
Kontrolle, deren Lösung vorher abrufbar wäre, misst nichts.
|
||
|
||
---
|
||
|
||
## Überall
|
||
|
||
### 16. Auf dem Handy
|
||
|
||
Die Anwendung ist für das Handy gebaut, nicht dafür angepasst. Der Azubi hat es
|
||
in der Tasche, nicht den Laptop.
|
||
|
||
| Handout | Lernmodus, Frage | Lernmodus, Antwort |
|
||
|---|---|---|
|
||
|  |  |  |
|
||
|
||
**Auf den Startbildschirm legen:** Die Lern-Bar ist eine installierbare
|
||
Anwendung.
|
||
|
||
- *Android (Chrome):* Menü → **App installieren**
|
||
- *iPhone (Safari):* Teilen → **Zum Home-Bildschirm**
|
||
|
||
Danach startet sie ohne Adresszeile und mit eigenem Symbol.
|
||
|
||
---
|
||
|
||
### 17. Ohne Netz
|
||
|
||
Im Serverraum, im Keller, im Zug gibt es kein Netz. Deshalb:
|
||
|
||
- **Merkkarten** und **Handouts, die du schon einmal geöffnet hattest**,
|
||
funktionieren weiter.
|
||
- Deine **Bewertungen werden gemerkt** und gehen ab, sobald du wieder verbunden
|
||
bist. Eine schmale Leiste sagt dir, wie viele warten – und meldet sich, wenn
|
||
sie angekommen sind.
|
||
- Der Tag zählt, an dem du **gelernt** hast, nicht der Tag des Absendens.
|
||
|
||
Was **nicht** offline liegt: Lernzielkontrollen, Berichtsheft, Bewertungen,
|
||
Feedbackgespräche, Anhänge und jedes PDF. Das ist Absicht. Diese Dinge stehen
|
||
hinter einer eigenen Rechteprüfung, und was im Browserspeicher liegt, ist an
|
||
dieser Prüfung vorbei.
|
||
|
||
Auf einem geteilten Gerät wird beim Abmelden alles Zwischengespeicherte
|
||
weggeräumt.
|
||
|
||
---
|
||
|
||
### 18. Hell und dunkel
|
||
|
||
|
||
|
||
Oben rechts in der Kopfzeile schaltest du um. Die Einstellung bleibt auf dem
|
||
Gerät. Beim Drucken wird immer hell gedruckt, auch wenn du dunkel eingestellt
|
||
hast – sonst käme schwarzes Papier aus dem Drucker.
|
||
|
||
---
|
||
|
||
### 19. Drucken
|
||
|
||
Für die Dokumente, die eine Unterschrift tragen, gibt es **PDFs**:
|
||
Wochenblatt, Checklisten-Durchlauf, Feedbackgespräch.
|
||
|
||
Für alles andere gibt es einen **Druckknopf**: Handout, Glossar, Auswertung. Die
|
||
Navigation, Knöpfe und Hinweise werden nicht mitgedruckt, Karten werden nicht
|
||
mitten durchgeschnitten, aufklappbare Abschnitte drucken aufgeklappt.
|
||
|
||
---
|
||
|
||
### 20. Wenn etwas nicht geht
|
||
|
||
| Beobachtung | Woran es liegt |
|
||
|---|---|
|
||
| „Diese Seite gibt es nicht" bei fremden Daten | Kein Fehler, sondern die Rechteprüfung. Ob es zu einer Kennung überhaupt Daten gibt, geht Unbefugte nichts an – deshalb 404 und nicht „kein Zugriff". |
|
||
| Die Anwendung startet nicht, nennt aber Datei und Zeile | Ein Inhaltsfehler unter `content/`. Die Meldung sagt genau, wo. `npm run inhalte:pruefen` prüft ohne Start. |
|
||
| Ein Anhang lässt sich nicht hochladen | Über 25 MB. Bei einem Reverse Proxy zusätzlich `client_max_body_size 30m` setzen (siehe README). |
|
||
| Ein abgezeichnetes Blatt lässt sich nicht ändern | So gewollt. Der Ausbilder kann es freigeben; das wird protokolliert. |
|
||
| Offline erscheint „Kein Netz" | Diese Seite lag nicht auf dem Gerät. Merkkarten und schon geöffnete Handouts gehen weiter. |
|
||
|
||
Bleibt etwas offen: `docker compose logs -f` zeigt, was der Server sagt, und
|
||
`/api/gesundheit` antwortet nur dann mit 200, wenn die Datenbank ansprechbar
|
||
ist.
|