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

docs/anleitung/04-vorlagen.md

@@ -0,0 +1,240 @@
+# Vorlagen bauen
+
+Eine Vorlage ist die Checkliste selbst: was bei einer PC-Neuinstallation zu tun ist, in welcher
+Reihenfolge, mit welchen Hilfetexten und welchen Befehlen. Vorlagen anlegen, bearbeiten und
+veröffentlichen darf die Rolle **Redakteur** oder **Administrator**.
+
+Die wichtigste Regel steht am Anfang, weil alles andere daraus folgt:
+
+> **Eine veröffentlichte Version wird nie verändert.** Sonst zeigte ein alter Lauf Schritte, die es
+> damals nicht gab. „Bearbeiten“ legt deshalb eine vollständige Kopie als **Entwurf** an. Je Vorlage
+> gibt es höchstens einen Entwurf. Läufe starten nur an veröffentlichten Versionen und hängen für
+> immer an der Version, mit der sie gestartet wurden.
+
+## Die Vorlagenliste
+
+![Die Vorlagenliste mit Filtern und Kennzeichen je Vorlage](bilder/vorlagen-liste-desktop.png)
+
+Gefiltert wird nach **Suche**, **Kategorie**, **Schlagwort** und mit dem Häkchen **auch
+archivierte**, dann **Filtern**.
+
+Die Kennzeichen an einer Zeile sagen den Zustand:
+
+| Kennzeichen | Bedeutung |
+|---|---|
+| **v3** | Version 3 ist veröffentlicht und gültig |
+| **noch nicht veröffentlicht** | es gibt nur einen Entwurf; daran lässt sich kein Lauf starten |
+| **Entwurf vorhanden** | es wird gerade an einer neuen Version gearbeitet |
+| **archiviert** | aus dem Angebot genommen |
+| **nur …** | gilt nur für einen Kunden (Modus Dienstleistung) |
+
+Gibt es einen Entwurf, führt **Entwurf öffnen** direkt in den Editor — der häufigste Fall ist,
+weiterzuarbeiten an dem, was man gestern angefangen hat.
+
+Unten auf der Seite steht **Vorlage anlegen**: **Name**, **Beschreibung (optional)**, **Kategorie
+(optional)**, **Schlagworte, mit Komma getrennt** und im Modus Dienstleistung **Nur für einen
+Kunden (optional)**. Die neue Vorlage beginnt als Entwurf. Namen sind nicht eindeutig; zwei
+Vorlagen dürfen gleich heißen.
+
+## Die Vorlagenseite
+
+![Die Seite einer Vorlage mit Versionsgeschichte, Kopfdaten und weiteren Aktionen](bilder/vorlagen-seite-desktop.png)
+
+Sie beantwortet drei Fragen auf einen Blick: Was ist gerade gültig? Wird gerade daran gearbeitet?
+Was wurde wann veröffentlicht?
+
+**Bearbeiten** ist der wichtigste Knopf. Er erzeugt eine tiefe Kopie der letzten veröffentlichten
+Version als neuen Entwurf und führt in den Editor. Gibt es schon einen Entwurf, heißt der Knopf
+**Entwurf weiter bearbeiten** und führt genau dorthin — auch wenn zwei Redakteure gleichzeitig
+klicken.
+
+Unter **Versionen** steht die Geschichte: Nummer, Veröffentlichungszeitpunkt und -person, die Zahl
+der Läufe und die Änderungsnotiz. Je Zeile **Ansehen** (beziehungsweise **Im Editor öffnen** beim
+Entwurf) und **Als JSON exportieren**.
+
+Unter **Kopfdaten** stehen Name, Beschreibung, Kategorie, Schlagworte und die Kundenzuordnung. Sie
+hängen an der Vorlage, nicht an einer Version — ein Tippfehler im Namen kostet also keine neue
+Version. **Kopfdaten speichern** übernimmt sie.
+
+Unter **Weiteres**:
+
+- **Duplizieren** — legt eine neue Vorlage an, mit dem Inhalt der neuesten Version als Entwurf.
+  Gut als Ausgangspunkt für eine Abwandlung.
+- **archivieren** / **wieder freigeben** — archiviert wird, was nicht mehr angeboten werden soll.
+  Gelöscht wird nichts: an einer Vorlage hängen Läufe. Ein Entwurf einer archivierten Vorlage lässt
+  sich noch bearbeiten, aber nicht veröffentlichen.
+- **Entwurf verwerfen** — mit Rückfrage. Der Entwurf ist danach weg und nicht wiederherstellbar;
+  die veröffentlichte Version bleibt unberührt.
+
+## Der Editor
+
+![Der Vorlagen-Editor mit Variablen, Abschnitten und Schritten](bilder/vorlagen-editor-desktop.png)
+
+Oben stehen Name, **Version N** und der Zustand — **Entwurf** oder **veröffentlicht** — und daneben
+**Nicht gespeichert** oder **gespeichert**.
+
+Unten klebt eine Leiste mit **Speichern** und derselben Auskunft in Worten. **Es gibt kein
+automatisches Speichern**: eine halb umgebaute Vorlage soll nicht nebenbei zur Wahrheit werden.
+Solange etwas nicht gespeichert ist, fragt der Browser vor dem Verlassen der Seite nach.
+
+Eine veröffentlichte Version öffnet der Editor nur lesend — mit denselben Feldern, nur
+schreibgeschützt. Oben steht dann, warum.
+
+### Abschnitte
+
+Ein Abschnitt fasst die Schritte zusammen, die zusammengehören. **Abschnitt hinzufügen** legt einen
+an; er bekommt einen **Titel des Abschnitts** und darunter seine Schritte.
+
+Die zweistellige Nummer (`01 · Vorbereitung`) kommt aus der Position und wird **nie gespeichert**.
+Schreib sie also nicht in den Titel — beim ersten Umsortieren wäre sie falsch.
+
+Sortiert wird auf zwei Wegen: mit dem Anfasser links ziehen, oder über die Pfeile **nach oben** und
+**nach unten** an der Zeile. Der zweite Weg ist am Handy der bessere. Schritte werden innerhalb
+ihres Abschnitts sortiert und lassen sich nicht in einen anderen ziehen.
+
+Höchstens 200 Abschnitte, höchstens 500 Schritte je Abschnitt.
+
+### Schritte und ihre Typen
+
+Jeder Schritt hat **Titel**, **Typ** und das Häkchen **Pflichtschritt**. Dazu je nach Typ:
+
+| Typ | Was der Techniker tut | Einstellungen |
+|---|---|---|
+| **Haken** | abhaken | keine |
+| **Text** | Text eintragen | **Mehrzeiliges Feld** |
+| **Zahl** | Zahl eintragen | **Mindestens**, **Höchstens**, **Einheit** |
+| **Auswahl** | aus einer Liste wählen | **Optionen** (mindestens eine) |
+| **Datum** | Datum wählen | keine |
+| **Befehl** | Befehl kopieren und ausführen | **Shell** (powershell, bash, cmd), **Befehl** |
+
+Mindestens und Höchstens sind **Hinweise, kein Verbot**: ein Wert außerhalb wird im Lauf markiert
+und trotzdem gespeichert.
+
+**Pflichtschritt** heißt: der Lauf lässt sich nicht abschließen, solange dieser Schritt weder
+erledigt noch ausdrücklich als nicht zutreffend eingetragen ist. Setz das sparsam — sind alle
+Schritte Pflicht, ist keiner Pflicht.
+
+Beim Wechsel des Typs räumt der Editor die Einstellungen auf, damit nicht der Befehl eines
+ehemaligen Befehlsschritts unsichtbar mitwandert.
+
+### Hilfetext und Doku-Link
+
+Der **Hilfetext** ist in der Abarbeitungsansicht ausklappbar und darf **Markdown** enthalten:
+`**fett**`, Listen, Links, `` `Code` ``. **Kein HTML.** Hier steht das, was jemand beim ersten Mal
+wissen muss — im Modus „Kompakt“ blendet der Techniker ihn später aus.
+
+Der **Doku-Link** erscheint im Lauf als **Anleitung öffnen**. Nur `http`- und `https`-Adressen.
+
+### Variablen
+
+Variablen werden **beim Start eines Laufs abgefragt** und füllen die Platzhalter. **Variable
+hinzufügen** legt eine an:
+
+- **Schlüssel** — der Name im Platzhalter `{{schluessel}}`. Ein Variablenschlüssel beginnt mit einem
+  Kleinbuchstaben und besteht aus Kleinbuchstaben, Ziffern und Unterstrich, höchstens 40 Zeichen.
+  `vorname`, `ad_gruppe` und `raum2` gehen; `Vorname`, `mit-strich` und `2te_wahl` nicht. Die
+  Strenge hat einen Grund: derselbe Schlüssel steht in PowerShell-Befehlen, und `{{Vor-Name}}` ließe
+  sich dort nicht mehr von der Syntax der Shell trennen.
+- **Beschriftung** — was im Startformular über dem Feld steht.
+- **Typ** — Text, Zahl, Auswahl oder Datum.
+- **Pflichtangabe beim Start** — ohne Eingabe lässt sich der Lauf nicht anlegen.
+- **Optionen** — nur bei Auswahl.
+
+Ein Schlüssel darf nur einmal vorkommen; der Editor markiert eine Doppelung sofort. Eine Variable,
+die nirgends verwendet wird, ist erlaubt — sie wird trotzdem beim Start abgefragt.
+
+Fünf Namen sind als Variable gesperrt: `techniker`, `datum`, `kunde`, `kundenkuerzel` und
+`generiertes_passwort`. Sie sagen, **wer, wann und für wen** — eine Variable dafür hieße, dass in
+einem fertigen Befehl ein fremder Name oder ein falsches Datum stehen kann, ohne dass es auffällt.
+
+Höchstens 200 Variablen.
+
+### Platzhalter
+
+Ein Platzhalter `{{schluessel}}` in **Titel, Hilfetext oder Befehl** wird beim Abarbeiten ersetzt.
+Leerzeichen in den Klammern sind erlaubt: `{{ vorname }}` wird erkannt.
+
+Er wird aus einer Variablen der Vorlage gefüllt — oder aus einem der **eingebauten** Werte. Welche
+es gibt, steht im Editor hinter **Welche Platzhalter gibt es?**, nach Quelle gruppiert:
+
+| Quelle | Platzhalter |
+|---|---|
+| Gerät und Lauf | `hostname`, `seriennummer`, `inventarnummer`, `ticket`, `datum`, `techniker`, und im Modus Dienstleistung `kunde`, `kundenkuerzel` |
+| Mitarbeiter | `mitarbeiter`, `benutzer`, `vorname`, `nachname`, `upn`, `sam`, `mail`, `abteilung`, `titel`, `vorgesetzter`, `vorgesetzter_sam`, `dn` |
+| Abteilung | `ou` (Ziel-Container), `gruppen` (Standardgruppen, kommagetrennt) |
+| Einstellungen | `ou_gesperrt` (Ziel-OU für deaktivierte Konten) |
+| Besonders | `generiertes_passwort` |
+
+`{{generiertes_passwort}}` ist der Sonderfall: **20 Zeichen, bei jeder Anzeige neu erzeugt und
+nirgends gespeichert** — nicht im Lauf, nicht im Kommentar, nicht im Protokoll, nicht im Ausdruck.
+Auf einem Ausdruck steht an seiner Stelle `[Passwort – nicht gespeichert]`. Bau also keinen Ablauf,
+der davon ausgeht, dass man das Passwort später nachschlagen kann.
+
+Ein Platzhalter, der zu keiner Variablen und keinem eingebauten Wert passt, wird oben im Editor
+**gewarnt**, aber nicht abgewiesen: ein Tippfehler soll hier auffallen und nicht erst dem Techniker
+im Lauf — es kann aber sein, dass die Variable gleich noch kommt. Im Lauf bleibt ein unbekannter
+Platzhalter als Text stehen.
+
+Für Befehlsschritte gilt eine zusätzliche Regel: **die Anführungszeichen gehören in die Vorlage,
+nicht in den Wert.** Schreib also `New-ADUser -Name "{{vorname}} {{nachname}}"`. Steht ein
+Platzhalter in einem Befehl nicht zwischen den erwarteten Anführungszeichen, wird der Schritt im
+Lauf abgewiesen, statt einen halb maskierten Befehl zum Kopieren anzubieten.
+
+### Vorschau
+
+**Vorschau** zeigt die Vorlage so, wie sie im Lauf aussieht: mit Beispielwerten in allen
+Platzhaltern, abgeschalteten Feldern und nummerierten Abschnitten. Gespeichert wird dabei nichts,
+und für `{{generiertes_passwort}}` entsteht **kein** Passwort — dort steht
+`BEISPIEL-PASSWORT-NICHT-ECHT`.
+
+Nutz sie vor dem Veröffentlichen, besonders bei Befehlen: erst hier sieht man, ob der fertige Befehl
+so aussieht, wie er aussehen soll.
+
+## Veröffentlichen
+
+Im Abschnitt **Veröffentlichen** trägst du eine **Änderungsnotiz (optional)** ein — ein Satz, was
+sich gegenüber der letzten Version geändert hat; sie steht später in der Versionsgeschichte. Dann
+**Veröffentlichen**.
+
+**Veröffentlicht wird das Gespeicherte, nicht das, was auf dem Bildschirm steht.** Gibt es nicht
+gespeicherte Änderungen, warnt der Editor — erst speichern, dann veröffentlichen.
+
+Danach ist die Version unveränderlich, und Läufe können daran starten. Der Editor schaltet in den
+Lesemodus.
+
+Willst du weiter daran arbeiten, drückst du auf der Vorlagenseite wieder **Bearbeiten**: es entsteht
+ein neuer Entwurf mit der nächsthöheren Nummer.
+
+## Export und Import
+
+**Als JSON exportieren** auf der Vorlagenseite lädt eine Version als Datei herunter. Das Dokument
+enthält Kopfdaten, Variablen, Abschnitte und Schritte — und ausdrücklich keine Kennungen,
+Zeitstempel, Läufe oder Kundenzuordnung. Damit lässt es sich in eine **andere**
+Laufzettel-Installation einspielen.
+
+Eingespielt wird in der Vorlagenliste unter **Vorlage aus einer Datei einspielen**: Datei wählen
+oder den Inhalt einfügen, dann **Einspielen**. Zu wissen:
+
+- Es entsteht immer eine **neue** Vorlage; der Import schreibt nie in eine bestehende hinein.
+- Sie bekommt genau eine Version als **Entwurf**. Erst nach dem Ansehen und Veröffentlichen lässt
+  sich ein Lauf daran starten.
+- Die Versionsnummer der Quelle wandert nicht mit: hier fängt die Vorlage wieder bei 1 an.
+- Eine eingespielte Vorlage gilt zunächst für alle Kunden. Die Zuordnung setzt du danach in den
+  Kopfdaten.
+- Schlägt die Prüfung fehl, wird **nichts** geschrieben, und die Meldung nennt die erste
+  Beanstandung mit ihrem Pfad, etwa
+  `struktur.abschnitte.1.schritte.2.titel: Ein Schritt braucht einen Titel.`
+
+Das Format ist vollständig beschrieben in [docs/vorlagen-format.md](../vorlagen-format.md) — für
+den Fall, dass jemand eine Vorlage von Hand schreiben oder ein Skript dafür bauen will.
+
+## Vorlagen einem Gerätetyp zuordnen
+
+Damit auf der Geräteseite ein **Schnellstart** erscheint, muss für den Gerätetyp eine Vorlage
+hinterlegt sein — etwa „PC Neuinstallation“ für den Typ PC. Diese Zuordnung wird beim Einrichten der
+Anwendung gesetzt und lässt sich in der Oberfläche noch nicht ändern; wende dich dafür an die
+Person, die Laufzettel betreibt.
+
+Ohne Zuordnung bleibt der Schnellstart leer, und das ist kein Mangel: unter **Vorlage zuweisen**
+steht auf der Geräteseite jede Vorlage, die zu diesem Gerät passt, und der Start-Dialog kennt sie
+ohnehin alle.