Laufzettel/docs/issues/013-laeufe-abarbeitung.md

#013 M8 – Läufe: Service und Abarbeitung

Status: erledigt Meilenstein: v0.1.0 Labels: phase-1, backend, frontend Geschätzt: 14 h Tatsächlich: 3 h 05 min

Ziel

Das Herz der Anwendung: ein Lauf wird vorbereitet, abgearbeitet, abgeschlossen und archiviert. Der Archiv-Schreibschutz sitzt an genau einer Stelle.

Aufgaben

• laufAnlegenService: aus veröffentlichter Version, Kunde per kundeErmitteln(), optional Mitarbeiter (Verzeichnis oder Freitext mitarbeiterName), optional Gerät, Ticket, Variablen, Zuweisung, Fälligkeit
• Ein Lauf kann als OFFEN angelegt werden, ohne ihn zu starten — das ist der Zuweisungs-Mechanismus, keine eigene Tabelle
• gestartetAm und IN_ARBEIT erst beim ersten Öffnen zur Bearbeitung
• Titelvorschlag <Vorlage> – <Hostname oder Mitarbeiter> – <Datum>
• schrittergebnisSetzenService: einzeln je Schritt (kein Gesamtformular), zustand, wert, notiz, aktualisiertVonId, Protokoll-Eintrag
• NICHT_ZUTREFFEND und FEHLGESCHLAGEN verlangen eine Notiz, sonst LaufFehler
• abschnittNichtZutreffendService: setzt alle Schritte eines Abschnitts mit einer Notiz auf NICHT_ZUTREFFEND (für die beiden Konto-Abschnitte im Onboarding)
• laufAbschliessenService: nur wenn alle Pflichtschritte ERLEDIGT oder NICHT_ZUTREFFEND sind; setzt abgeschlossenAm, abgeschlossenVonId
• laufArchivierenService und laufZurueckholenService (nur ADMIN), beide mit Protokoll-Eintrag
• laufMussVeraenderbarSein(lauf) zentral, aufgerufen vor jeder Änderung an Kopfdaten, Schrittergebnis und Kommentar
• Kommentare je Lauf und je Schrittergebnis
• „Mit AD-Konto verknüpfen“: ein Lauf mit mitarbeiterName wird nachträglich über UPN oder Name mit einem Mitarbeiter verbunden
• Start-Dialog: Vorlage → Mitarbeiter → Gerät (wählen, neu anlegen oder scannen) → Ticket, Variablen, Zuweisung, Fälligkeit; Vorbelegung je Aufrufort, Besitzer des Geräts als Mitarbeiter vorgeschlagen; Vorschläge aus den Namensregeln für upn, sam, mail — bis auf „neu anlegen oder scannen“, siehe unten
• Abarbeitungsansicht: einklappbare Abschnitte mit 01 ·-Nummerierung, Fortschrittsbalken in Lime, je Schritt Zustand, Wert, Notiz, Kommentare und „wer wann“
• Erledigte Schritte durchgestrichen in Nebentext-Farbe, Checkbox erledigt als Lime-Kachel mit dunklem Haken, Pflichtschritte mit rotem Stern
• BEFEHL-Schritte als Codeblock auf #0B0D10 mit Lime-Schrift, Kopier-Knopf, Warnung wenn ein Platzhalter unaufgelöst ist; je Abschnitt „Alle Befehle als Skript kopieren“
• ZAHL außerhalb von Min/Max wird markiert, aber nicht blockiert
• Route Handler GET /api/laeufe/[id]/zustand, Client pollt alle 10 s und pausiert bei verstecktem Tab
• Umschalter „Kompakt / Ausführlich“, ausführlich klappt alle Hilfetexte auf
• Abschließen und Archivieren als getrennte Aktionen
• Screenshots Start-Dialog, Lauf Desktop, Lauf Handy, Befehlsschritt in docs/screenshots/m8/

Akzeptanzkriterien

• Test: ein Lauf ohne Mitarbeiter und ohne Gerät lässt sich anlegen, abschließen und archivieren
• Test: Abschließen scheitert, solange ein Pflichtschritt OFFEN ist
• Test: NICHT_ZUTREFFEND ohne Notiz wird abgelehnt, mit Notiz akzeptiert
• Test: an einem archivierten Lauf schlagen Änderung eines Schrittergebnisses, eines Kommentars und der Kopfdaten fehl
• Test: nur ADMIN holt einen archivierten Lauf auf ABGESCHLOSSEN zurück, mit Protokoll-Eintrag
• Test: gestartetAm bleibt leer, solange der Lauf nur OFFEN ist
• Test: jede Änderung an einem Schrittergebnis, jeder Statuswechsel und jedes Veröffentlichen steht im Protokoll
• Test: die Abschnitts-Aktion setzt alle Schritte des Abschnitts mit derselben Notiz
• Zwei Browser auf demselben Lauf sehen die Änderung des anderen nach höchstens 10 s
• Am Handy bei 390 px kein horizontales Scrollen

Offen, verschoben nach #014

Ein Gerät direkt im Start-Dialog anlegen oder scannen. Beides hängt am QR-Einstieg, der dort gebaut wird; der Dialog nimmt ?geraet= schon heute entgegen, die Geräteseite füllt es dann.

Ergebnis

Erledigt am 2026-09-25. 879 Tests (vorher 810) und 37 Ende-zu-Ende-Tests grün, Screenshots in docs/screenshots/m8/.

Dazugekommen, weil sie sonst Zusagen ohne Deckung gewesen wären:

• Die Aktualisierung alle zehn Sekunden lädt die Seite nicht von selbst neu, wenn ein generiertes Passwort darauf steht. Die Antwort des Pollings trägt zwar keine Befehle — aber ein Neuaufbau der Seite hätte das Passwort genauso ausgetauscht. Jetzt fragt sie.
• Ein Abschnitt, in dem nichts mehr zu tun ist, klappt zu; der Zustand liegt im Browser.
• Die Oberfläche zu „Mit AD-Konto verknüpfen“ — den Dienst gab es, aber keinen Weg dorthin.

Der unabhängige Review

Zwei Blocker, zwölf Befunde, acht Anmerkungen. Alle abgearbeitet, die wichtigsten:

• Ein Befehl konnte zwei verschiedene Passwörter tragen — je Vorkommen entstand ein neues. Das Konto hätte A bekommen und der Benutzer B erfahren. Jetzt ein Passwort je Seitenaufbau, für alle Befehle des Laufs. Ein eigener Test meines Vorgängerstands hatte das falsche Verhalten sogar festgeschrieben.
• „Nicht zutreffend“ ließ sich nicht zurücknehmen, und die Oberfläche behauptete dabei, nichts sei gewählt, während in der Datenbank der alte Zustand stand.
• Bearbeiter fremder Kunden standen im Start-Dialog zur Auswahl — der Dienst lehnte die Zuweisung danach ab.
• Kommentare und Kopfdaten lösten keine Aktualisierung aus; Akzeptanzkriterium 9 galt nur für Schrittzustände.
• Abschnitte wurden über den Array-Index gepaart, obwohl (versionId, position) nicht eindeutig ist: „Abschnitt trifft nicht zu“ hätte den falschen treffen können.
• Der Route Handler war nicht geprüft, nur die Abfrage darunter. Dabei fiel auf, dass der Proxy eine API-Anfrage ohne Anmeldung auf die Anmeldeseite umlenkte statt mit 401 zu antworten.