feat(doku): Anleitung, PDF und Ende-zu-Ende-Abnahme (#36)

docs/anleitung/08-fehlerbehebung.md

@@ -0,0 +1,229 @@
+# Fehlerbehebung
+
+Symptom, Ursache, was zu tun ist. Jede Meldung steht hier so, wie Laufzettel sie zeigt.
+
+## „E-Mail-Adresse oder Passwort stimmt nicht.“
+
+**Ursache:** falsche Zugangsdaten — **oder** ein deaktiviertes Konto. Die Meldung unterscheidet das
+nicht, weil sie sonst verriete, welche Adressen es gibt.
+
+**Was tun:** Zugangsdaten prüfen. Bist du sicher, dass sie stimmen, lass einen Administrator unter
+**Admin → Benutzer** nachsehen, ob dein Konto auf **aktiv** steht. Ein deaktiviertes Konto wird auch
+mit noch gültiger Anmeldung abgewiesen.
+
+## „Der Anbieter war nicht erreichbar. Bitte später erneut versuchen.“
+
+**Ursache:** der Anmeldeanbieter antwortet nicht.
+
+**Was tun:** Gibt es ein lokales Konto, melde dich damit an — genau dafür ist es da. Sonst hilft nur
+warten und die Störung melden. Der Notfallzugang steht unter **Admin → Benutzer → Lokales Konto
+anlegen** und sollte eingerichtet sein, *bevor* der Anbieter ausfällt.
+
+## „Dafür fehlt dir die Berechtigung“
+
+**Ursache:** deine Rolle darf diese Seite nicht.
+
+**Was tun:** In der Seitenleiste steht ohnehin nur, was du darfst — die Meldung kommt meist von einem
+Link, den jemand weitergegeben hat. Brauchst du den Bereich wirklich, lass dir vom Administrator eine
+stärkere Rolle geben. Kommt die Rolle vom Anmeldeanbieter, muss sie dort in der Gruppenzuordnung
+geändert werden; eine hier gesetzte Rolle wird beim nächsten Anmelden überschrieben.
+
+## „Deine Anmeldung gilt nicht mehr.“
+
+**Ursache:** die Sitzung ist abgelaufen, während das Formular offen stand.
+
+**Was tun:** Genau das, was die Meldung sagt: in einem **zweiten Tab** neu anmelden und dann hier
+noch einmal klicken. Was du eingegeben hast, steht weiterhin auf der Seite — **lade sie nicht neu**,
+das würde die Eingaben verwerfen.
+
+## Ein Schritt lässt sich nicht speichern
+
+**Ursache und was tun**, in dieser Reihenfolge prüfen:
+
+1. **„… ist archiviert und damit schreibgeschützt.“** — der Lauf ist archiviert. Siehe unten.
+2. **„Ein Schritt, der nicht zutrifft, braucht eine Begründung“** oder **„Ein fehlgeschlagener
+   Schritt braucht eine Notiz“** — füll das Feld **Begründung** und drück **Mit Begründung
+   speichern**. Ohne Begründung stünde im Archiv ein übersprungener Schritt ohne Grund.
+3. **Die Pille springt zurück, ohne Meldung** — die Verbindung war weg. Tippe noch einmal. Jeder
+   Schritt speichert einzeln, es geht also nur dieser eine Klick verloren.
+4. **Nichts passiert, gar nichts** — lade die Seite neu. Ist die Anmeldung abgelaufen, siehst du
+   danach die Anmeldeseite und kommst nach dem Anmelden auf dieselbe Stelle zurück.
+5. **Deine Rolle ist Leser** — dann gibt es die Pillen nicht, sondern nur die Anzeige des Zustands.
+   Läufe bearbeiten darf erst der Techniker.
+
+## Der Lauf lässt sich nicht abschließen
+
+**Ursache:** es ist noch ein Pflichtschritt offen. Der Knopf ist dann gesperrt, und darunter steht,
+wie viele es sind; die Meldung nennt die Titel: „Der Lauf lässt sich noch nicht abschließen. Offen
+sind: …“
+
+**Was tun:** Die genannten Schritte erledigen — oder, wenn sie nicht zutreffen, mit Begründung als
+**nicht zutreffend** eintragen. **Ein fehlgeschlagener Schritt zählt nicht als erledigt:** er ist
+entweder zu beheben oder mit Begründung als nicht zutreffend einzutragen. Trifft ein ganzer Abschnitt
+nicht zu, nimm **Abschnitt trifft nicht zu** — eine Begründung für achtzehn Schritte.
+
+## Der Lauf ist archiviert
+
+**Ursache:** jemand hat ihn archiviert. Damit ist er schreibgeschützt: kein Haken, kein Wert, keine
+Notiz, kein Kommentar geht mehr. Das ist die Zusage, für die das Archiv da ist.
+
+**Was tun:** Prüf zuerst, ob du es wirklich brauchst. Für eine Ergänzung genügt oft ein neuer Lauf,
+der auf den alten verweist — das ist der ehrlichere Weg, weil er datiert ist.
+
+Muss es der alte Lauf sein, bittet du einen **Administrator**: nur er sieht auf der Laufseite **aus
+dem Archiv zurückholen**. Der Lauf steht danach wieder auf „abgeschlossen“ und lässt sich ändern; das
+Zurückholen wird protokolliert.
+
+**Vorbeugen:** archiviere erst, wenn wirklich alles drinsteht. Es gibt keinen Grund zur Eile — ein
+abgeschlossener Lauf steht auch schon im Archiv und ist durchsuchbar.
+
+## „Kein Laufzettel-Tag“ nach dem Scannen
+
+**Ursache:** einer von drei Fällen, und Laufzettel unterscheidet sie absichtlich nicht — die
+Unterscheidung verriete, welche Codes es gibt:
+
+- Es gibt den Code nicht.
+- Der Code hat nicht die richtige Form.
+- Der Code gehört zu einem **anderen Kunden**.
+
+**Was tun:** Lies den Code unter dem QR ab und vergleich ihn. Ein Laufzettel-Code beginnt mit `LZ-`
+und hat sechs Zeichen dahinter, **ohne** die Zeichen `0`, `O`, `1` und `I`. Wer `O` statt `Q` liest,
+tippt einen Code, den es nicht geben kann — das ist Absicht, denn ein „verbessertes“ Zeichen könnte
+auf ein anderes, vorhandenes Gerät führen.
+
+Stimmt der Code und du siehst trotzdem nichts, gehört der Aufkleber zu einem Kunden, den du nicht
+sehen darfst. Frag einen Administrator.
+
+## Der Scanner startet nicht
+
+| Meldung | Ursache | Was tun |
+|---|---|---|
+| „Die Kamera gibt es nur über HTTPS.“ | die Seite läuft unverschlüsselt | Die verschlüsselte Adresse verwenden. Bis dahin: Code eintippen. |
+| „Die Kamera ist nicht freigegeben.“ | Berechtigung verweigert | In den Einstellungen des Browsers die Kamera für diese Seite freigeben und neu laden. |
+| „Dieser Browser gibt keine Kamera frei.“ | kein Kamerazugriff möglich | Code eintippen. |
+| „Der QR-Leser lässt sich nicht starten.“ | der Decoder ließ sich nicht laden | Seite neu laden. Bleibt es dabei, einem Administrator melden; bis dahin Code eintippen. |
+| „Das ist kein Laufzettel-Tag.“ | ein fremder QR-Code im Bild | Den richtigen Aufkleber ins Bild halten — den mit `LZ-…`. |
+
+In allen Fällen gilt: unter dem Kamerabild steht das Feld **Code eintippen**. Der Code steht lesbar
+unter dem QR. Ein Scanner, der nicht startet, ist keine Sackgasse.
+
+## Das Etikett wird nicht gelesen
+
+**Ursache und was tun:**
+
+1. **Falsch skaliert gedruckt.** Im Druckdialog **Skalierung auf 100 %** stellen und **Kopf- und
+   Fußzeilen abschalten**. „An Seite anpassen“ verkleinert den QR-Code und frisst die Ruhezone am
+   Rand, die der Leser braucht.
+2. **Der Drucker hat gespart.** Manche Treiber lassen Flächen weg oder drucken sie grau. Ein QR-Code
+   braucht harten Schwarz-Weiß-Kontrast; stell den Farbmodus auf normal, nicht auf Toner-Sparen.
+3. **Der Aufkleber ist beschädigt oder verschmutzt.** Tipp den Code darunter ein und drucke das
+   Etikett neu: auf der Geräteseite **Etikett drucken**. Der Code bleibt derselbe.
+4. **Das Etikett sitzt neben der Stanzung.** Dann war die Skalierung falsch — siehe Punkt 1. Das
+   Raster des A4-Bogens füllt das Blatt genau aus und verträgt keinen Seitenrand.
+5. **Der QR-Code führt ins Leere.** Dann war beim Drucken die Adresse der Anwendung nicht gesetzt
+   (die Druckansicht warnt davor in Rot). Ein geklebter Aufkleber lässt sich nicht berichtigen: die
+   Adresse eintragen lassen, Etiketten neu drucken und **überkleben**. Der Tag-Code selbst bleibt
+   gültig.
+
+## „APP_URL ist nicht gesetzt“
+
+**Ursache:** die Anwendung weiß nicht, unter welcher Adresse sie erreichbar ist. Die QR-Codes zeigen
+dann auf `http://localhost:3000` und führen von keinem anderen Gerät irgendwohin.
+
+**Was tun:** **Nicht drucken.** Ein Administrator trägt die Adresse in der Umgebung der Anwendung ein;
+in der Oberfläche geht das nicht, weil gedruckte Aufkleber sonst ins Leere zeigen würden. Unter
+**Admin → Einstellungen** steht ganz unten, welche Adresse gerade gilt.
+
+## Der Verzeichnisabgleich meldet einen Fehler
+
+| Meldung | Ursache | Was tun |
+|---|---|---|
+| „… ist keine LDAP-Adresse.“ | Schema fehlt oder falsch | `ldaps://host:636`, `ldap+starttls://host:389` oder `ldap://host:389` eintragen. |
+| „In … fehlt der Rechnername.“ | nur das Schema eingetragen | Rechner und Port ergänzen. |
+| „… enthält einen Pfad.“ | der Basis-DN steht in der Adresse | Adresse auf Schema, Rechner und Port kürzen; der Basis-DN hat sein eigenes Feld. |
+| „… enthält Zugangsdaten.“ | `benutzer@host` in der Adresse | Bind-DN und Passwort in ihre eigenen Felder. |
+| „Das Bind-Passwort fehlt.“ | leeres Passwortfeld beim Anlegen | Passwort eintragen; ein anonymer Bind wird nicht unterstützt. |
+| Fehler beim Verbinden oder Anmelden | Netz, Firewall, Zertifikat, falsches Dienstkonto | Erreichbarkeit und Port prüfen. Bei einem Zertifikat aus eigener CA das **PEM** hinterlegen. Dann **Verbindung testen**. |
+| „Niemand wurde deaktiviert. Prüf die Attributzuordnung, besonders das Kennungsattribut.“ | kein einziger Eintrag ließ sich zuordnen | Das ist die Notbremse: es wurde **nichts** abgeschaltet. Unter **Attributzuordnung anpassen** die **Kennung (dauerhaft)** prüfen — im Active Directory `objectGUID`, im OpenLDAP meist `entryUUID`. |
+| „Für … läuft gerade schon ein Abgleich.“ | ein zweiter Lauf, oft der Zeitplan | Abwarten und das **Abgleich-Log** ansehen. |
+| „Das CA-Zertifikat muss im PEM-Format vorliegen …“ | falscher Text eingefügt | Der Text muss mit `-----BEGIN CERTIFICATE-----` beginnen. |
+
+**Übersprungene Einträge** im Log sind kein Fehler der Quelle, sondern einzelne krumme Konten. Steigt
+die Zahl, prüf die Attributzuordnung.
+
+**Der Abgleich lief, hat aber nichts getan** („0 angelegt, 0 aktualisiert“): das ist die Auskunft,
+dass sich im Verzeichnis nichts geändert hat. Alles in Ordnung.
+
+## „Der Entwurf wurde zwischenzeitlich von jemand anderem gespeichert.“
+
+**Ursache:** zwei Redakteure am selben Entwurf.
+
+**Was tun:** **Lade die Seite nicht neu** — deine Eingaben stehen noch da und wären danach weg. Öffne
+den Entwurf in einem zweiten Tab, sieh dir die fremde Fassung an und trag deine Änderungen dort nach.
+Wird es viel, hilft **Aufbau als JSON herauskopieren** unten an der Speicherleiste: damit rettest du
+deinen Stand als Text heraus.
+
+Denselben Ausweg gibt es bei **jedem** fehlgeschlagenen Speichern im Editor, egal woran es lag.
+
+## Der Lauf zeigt einen Platzhalter wie `{{ad_gruppe}}`
+
+**Ursache:** der Platzhalter gehört zu keiner Variablen und zu keinem eingebauten Wert. Im Lauf bleibt
+er als Text stehen — sichtbar, aber nutzlos. Meist ein Tippfehler in der Vorlage.
+
+**Was tun:** Im Befehl vor dem Ausführen von Hand ersetzen (der Kasten warnt davor: „konnte nicht
+eingesetzt werden und steht so im Befehl“). Dann sag es dem Redakteur: im Editor steht die Warnung
+oben, und die Vorlage braucht entweder die Variable oder den richtigen Schlüssel. Das wirkt erst in
+der **nächsten** Version — laufende Läufe hängen an ihrer.
+
+## Das Passwort ist weg
+
+**Ursache:** `{{generiertes_passwort}}` wird bei jeder Anzeige neu erzeugt und **nirgends
+gespeichert**. Sobald sich die Seite neu aufbaut — auch nach dem Speichern eines Schritts — steht dort
+ein anderes. Auf dem Ausdruck steht `[Passwort – nicht gespeichert]`.
+
+**Was tun:** Es gibt keinen Weg, es nachzuschlagen; es existiert nicht mehr. Setz im Zielsystem ein
+neues Passwort und gib es weiter. Beim nächsten Mal: **kopieren und sofort weiterreichen**, bevor du
+etwas anderes anklickst. Meldet der Streifen oben „Beim Neuladen entsteht ein neues Passwort“,
+kopiere das angezeigte erst.
+
+## Ein Gerät lässt sich nicht löschen
+
+**Ursache:** an dem Gerät hängt mindestens ein Lauf — die Meldung nennt die Zahl. Ein Lauf muss für
+immer nachvollziehbar bleiben. Oder deine Rolle ist nicht **Administrator**; nur er sieht den Knopf.
+
+**Was tun:** **archivieren** statt löschen. Das Gerät verschwindet aus allen Auswahllisten und nimmt
+keine neue Arbeit an, bleibt aber in jeder Historie — und lässt sich mit **wieder freigeben**
+zurückholen.
+
+Und bedenke: eine echte Löschung **verbrennt den Tag-Code für immer**. Ein schon gedruckter Aufkleber
+dieses Codes ist danach wertlos.
+
+## Eine Vorlage steht nicht zur Wahl
+
+**Ursache:** eine von vier, in dieser Reihenfolge zu prüfen:
+
+1. Sie hat **keine veröffentlichte Version** — ein Entwurf ist noch niemandes Arbeitsanweisung.
+2. Sie ist **archiviert**.
+3. Sie gehört **einem anderen Kunden** („nur Musterfirma GmbH“).
+4. Auf der Geräteseite: sie verlangt **Pflichtangaben**. Dann steht sie mit dem Zusatz „fragt noch
+   nach Angaben“ dabei und führt in den Start-Dialog, statt sofort zu starten — hier wird ja niemand
+   gefragt.
+
+**Was tun:** Fall 1 und 2 löst ein Redakteur auf der Vorlagenseite (**Veröffentlichen**
+beziehungsweise **wieder freigeben**), Fall 3 ein Administrator über die Kundenzuordnung in den
+Kopfdaten. Fall 4 ist kein Fehler: nimm den Start-Dialog.
+
+## Ein Lauf oder ein Gerät ist nicht auffindbar
+
+**Ursache und was tun:**
+
+- **Die Liste ist gekappt.** Die Laufliste zeigt höchstens 200 Läufe, die Archivsuche höchstens 100
+  Treffer, die Gerätehistorie die letzten 20. Steht das dabei, such genauer statt zu blättern:
+  Titel, Ticket, Hostname, Person oder Tag-Code.
+- **Der Lauf ist archiviert.** Archivierte Läufe stehen **nicht** in der Laufliste. Nimm das
+  **Archiv** — dort auch das Häkchen **auch offene und laufende Läufe**, wenn du beides zugleich
+  suchst.
+- **Die Person ist deaktiviert.** Setz in der Personenliste das Häkchen **auch deaktivierte**.
+- **Das Gerät ist archiviert.** Setz in der Geräteliste das Häkchen **auch archivierte**.
+- **Es gehört einem anderen Kunden.** Dann ist es für dich nicht vorhanden, und daran ändert auch ein
+  weitergegebener Link nichts.