Prüf-Checklisten

Zweck

Prüf-Checklisten sind Vorlagen, die im Aussendienst auf Anlagen, Komponenten oder im Auftrag ausgefuellt werden. Sie sind die zentrale Quelle, aus der Mängel (Defect) entstehen — siehe Maengel. Pro Checkliste pflegen Sie ein hierarchisches Schema aus Tiles (Sektionen) und Items (Pruefpunkten) mit Aktionen und Bewertungs-Logik.

Voraussetzungen

- Berechtigung `create:Checklist`. - Für Produkt-Zuordnung zusaetzlich `view:ProductAssignment`.

Berechtigungen (CASL)

Frontend-Page-Guard:

Action	Subject	Keycloak-Rolle
view	FE_Checklist	—
view	Checklist, ChecklistTile, ChecklistTileItem, ChecklistTileItemType, ChecklistTileItemAction	APP_SPEAMCORE_VIEW_CHECKLIST, CHECKLIST_TILE, CHECKLIST_TILE_ITEM, CHECKLIST_TILE_ITEM_TYPE, CHECKLIST_TILE_ITEM_ACTION

Tab-Subjects:

Tab	Sub-Pfad	Subject
Allgemein	/checklists/:id	Checklist:view
Produktzuordnung	/checklists/:id/products	ProductAssignment:view

Schritt-für-Schritt-Anleitung

Checkliste anlegen

1. Prüf-Checklisten (/checklists) → + Neu.
2. Listenseite filtert auf MasterDefaultChecklist ohne Parent — Master-Vorlagen.
3. Detail-Seite: Name eingeben.
4. Im ChecklistBuilder (editMode=true) Tiles und Items pflegen — Drag & Drop, Aktionen je Item.
5. Änderungen werden automatisch gespeichert (formik.handleSubmit() on change).

Builder-Modus (Edit) — Aufbau einer Checkliste

Die Checkliste wird im Builder-Modus aus Rastern (= ChecklistTile = Sektionen mit Items) zusammengesetzt. Jedes Raster enthält ein- oder mehrere Items (= ChecklistTileItem = einzelne Prüfpunkte).

Header-Aktionen (oberhalb des Rasters)

Button/Element	Funktion
Name (Input)	Pflicht. Anzeigename der Checkliste — erscheint im Auftrag, im Bericht, in Auswahllisten.
Neues Feld (Dropdown)	Fügt der Checkliste ein Custom-Feld hinzu (z. B. „Prüf-Standard", „Norm-Referenz"). Siehe Custom-Fields und AttributeFields.
Raster hinzufügen (großer lila/orange Button)	Erzeugt ein neues ChecklistTile am Ende der Liste.
Vorschau (großer lila Button)	Wechselt in den Read-Only-Vorschau-Modus — zeigt die Checkliste so wie der prüfende Mitarbeiter sie später sieht.

Raster-Toolbar (pro Raster, nach Hinzufügen)

Jedes Raster hat eine eigene Mini-Toolbar mit 5 Icons:

Icon	Funktion
✥ Bewegen-Griff (links)	Drag-and-Drop-Anker zum Umsortieren der Raster.
🗑 Trash	Löscht das gesamte Raster mit allen Items.
▦ Layout (rechts)	Wählt Raster-Layout: 1-Spaltig, 2-Spaltig, 4-Spaltig — beeinflusst wie Items im Bericht angeordnet werden.
⚙ Filter/Settings	Eigenschaften des Rasters: Pflicht-Raster (nicht überspringbar), Gruppen-Header, optionale Sichtbarkeits-Bedingung.
🔊 Lautsprecher	Sprachausgabe-Modus aktivieren — bei Mobile-Vor-Ort-Prüfung werden Item-Texte vorgelesen (Hands-Free-Bedienung).

Item-Typen (innerhalb eines Rasters)

Pro Raster können verschiedene Item-Typen hinzugefügt werden — jeder Typ hat eine andere Eingabemöglichkeit beim Prüfvorgang:

Item-Typ	Eingabe	Verwendung
Boolean (Ja/Nein)	Toggle	„Funktioniert Sirene?"
Auswahl (Single)	Radio-Button-Liste	„Anlagentyp: A / B / C"
Auswahl (Multi)	Checkbox-Liste	„Mängel-Kategorien: Sichtbar/Funktion/Sicherheit"
Text (kurz)	Single-Line-Input	„Seriennummer eingeben"
Text (lang)	Multi-Line-Textarea	„Anmerkungen zur Anlage"
Zahl	Numerisches Input	„Druckmessung in bar"
Datum	Date-Picker	„Datum letzte Wartung"
Foto	Kamera-/Upload-Button	Vor-Ort-Foto-Beleg
Mangel-Erfassung	Trigger-Button	Öffnet Mangel-Modal (siehe Auftrags-Quick-Buttons)

Im **Auftrag-Tab Anlagen** wird die Checkliste **instanziiert** — eine Kopie der Master-Checkliste mit `parentId = WorkorderSystem.id` wird angelegt. Beim Vor-Ort-Prüfen füllt der Mitarbeiter diese Instanz aus; die Master-Checkliste bleibt unverändert. Items mit Mangel-Erfassung legen automatisch einen `Defect` an, der mit dem Auftrag verknüpft ist.

Vorschau-Modus

Klick auf Vorschau schaltet auf eine Read-Only-Ansicht — zeigt die Checkliste exakt so, wie der prüfende Mitarbeiter sie auf dem Vor-Ort-Tablet sehen wird. Sehr nützlich um Layout, Item-Reihenfolge und Pflicht-Erfassung zu validieren, bevor die Checkliste produktiv eingesetzt wird.

Checkliste klonen

1. In der Listen-Seite eine bestehende Checkliste markieren.
2. Klonen klicken — POST /api/checklists/:id/clone.
3. Eine Kopie wird angelegt (alle Tiles/Items dupliziert, parentId = null).

Produkte zuordnen

Tab Produktzuordnung verknuepft die Checkliste mit Produkten — beim Anlegen einer WorkorderSystem mit diesem Produkt wird die Checkliste automatisch instanziiert.

Toolbar (Detail-Seite)

Schlanke Toolbar oben rechts:

Icon	Aktion (aria-label)	CASL	Wirkung
←	Zurückgehen	—	Zurück zur Liste.
🏠	Zur Startseite gehen	—	Springt auf das Dashboard / /.
⏮/◀/▶/⏭	Pagination	—	Navigation durch die gefilterte Liste — Massen-Bearbeitung ohne Liste-Sprung.

Globale Floating-Drawer (links)

Wie auf jeder Detail-Seite verfuegbar — siehe Floating-Quickbar:

• KAL. (Mini-Kalender)
• ZEIT (Persoenliche Wochen-Arbeitszeit)
• ARBEIT (Eigene bevorstehende Aufträge)

UI-Elemente

Komponente: ChecklistBuilder

Visueller Editor für Tiles und Items (editMode = true). Erlaubt Hinzufuegen, Verschieben und Löschen pro Element.

Button: „Klonen"

Listenseite. Erfordert create:Checklist. Erzeugt eine Kopie inklusive Tiles/Items.

Button: „Löschen"

Listenseite. Erfordert delete:Checklist. Soft-Delete.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
name	ja	String	Bezeichnung der Checklisten-Vorlage.	Wird in Auswahl-Selects (Anlagen, Aufträge, Produktzuordnung) angezeigt.	—
checklistType	automatisch	Enum	MasterDefaultChecklist, DefaultChecklist, ComponentChecklist.	Steuert, wo die Checkliste auswählbar ist. Master-Vorlagen sind Templates für alle Mandanten-Checklisten.	—
parentId + parentType	optional	polymorph	Service, System, Checklist, WorkorderSystem, ProjectRequest.	Verknuepft die Checkliste mit dem Verwendungs-Kontext. Bei Master-Vorlagen leer.	view:<ParentType> je nach Verwendung.
operationalStatus	nein	Enum	ok, neutral, nok. Default neutral.	Steuert Warn-/Erfolg-Anzeige bei der Anlagen-Prüfung. Wird bei Item-Aktionen automatisch hochgesetzt.	—
operationalAt	nein	DATE	Zeitpunkt der letzten Prüfung.	Wird automatisch beim Abschluss einer Prüfung gesetzt.	—

Die eigentlichen Pruefpunkte (ChecklistTile, ChecklistTileItem) werden im Builder verwaltet, nicht in der Felder-Tabelle.

Workflows und Zustaende

Wiederverwendbare Konzepte

• Polymorpher Parent-Pattern — Checklist.parentType ist 5-fach polymorph.
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Anlagen / Systems — Checklist.parentType = 'System' als Prüf-Vorlage je Anlage.
• Aufträge — WorkorderSystem instanziiert die Checkliste für einen konkreten Auftrag.
• Mängel — Defect.parentType = 'Checklist' oder 'ChecklistTileItem'. Bei nicht bestandenen Items entstehen Mängel.
• Produkte — Produktzuordnung steuert automatische Instanziierung.

Häufige Fehler und Lösungen

Fehler	Lösung
Checkliste nicht in Anlagen-Auswahl sichtbar	parentType nicht passend (System vs. Service etc.). Prüfen oder neu klonen mit korrektem Typ.
Klonen erzeugt Kopie ohne Tiles	Kopie muss parentId = null haben — sonst greift der MasterDefaultChecklist-Filter. Bug-Verdacht.
operationalStatus falsch	Wird durch Item-Aktionen gesetzt — Bewertungs-Logik im Builder prüfen.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/checklists	Liste	view Checklist
GET	/api/checklists/:id	Detail	view Checklist
POST	/api/checklists	Anlegen	create Checklist
PUT	/api/checklists/:id	Ändern	update Checklist
DELETE	/api/checklists/:id	Soft-Delete	delete Checklist
POST	/api/checklists/:id/clone	Vollständige Kopie inkl. Tiles/Items	create Checklist

Versionshinweise

• 2026-04-29: Initiale Veroeffentlichung mit FE-Tiefen-Standard.