Mängel
Zweck
Mängel werden waehrend Prüfungen, Kontrollen oder Wartungen an Anlagen festgestellt und nachverfolgt. Sie haengen polymorph an einem Auftrag, einer Anlage, einer Checkliste oder einem Checklisten-Item — abhaengig vom Erfassungsort.
Voraussetzungen
Berechtigungen (CASL)
Frontend-Page-Guard:
| Action | Subject | Keycloak-Rolle |
|---|---|---|
view | FE_Defect | — |
view | Defect | APP_SPEAMCORE_VIEW_DEFECT |
API-Datenzugriff:
| Action | Subject | Endpoint | Keycloak-Rolle |
|---|---|---|---|
view | Defect | GET /api/defects, GET /api/defects/:id | APP_SPEAMCORE_VIEW_DEFECT |
update | Defect | PATCH /api/defects/:id | APP_SPEAMCORE_UPDATE_DEFECT |
delete | Defect | DELETE /api/defects/:id | APP_SPEAMCORE_DELETE_DEFECT |
POST /api/defects ist nicht verfuegbar — Mängel werden über das Prüf-/Wartungs-Modul erzeugt.
Schritt-für-Schritt-Anleitung
Mangel bearbeiten
- Mängel (
/defects) öffnen oder direkt aus dem Auftrag-Tab Mängel. - Mangel anklicken.
- Felder pflegen — insbesondere
description,action,deadline, Klassifizierung (defectTypeCategoryId,defectTypeOperatorId,defectTypePriorityId). - Speichern.
Mangel abschliessen
Der Lifecycle eines Mangels (in Bearbeitung / behoben / nicht behoben / offen) wird nicht über ein eigenes Status-Feld am Defect selbst gesteuert, sondern aus dem Kontext abgeleitet: über parentType + parentId (typisch Workorder/Checklist), workorderDefectId (Pruefungs-Verknuepfung) und ggf. deadline. Der „behobene" Status ergibt sich aus dem Workorder-Status und ggf. einem Folge-Workorder.
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
Button: „Speichern"
Detailseite. Erfordert update:Defect.
Button: „Löschen"
Detailseite. Erfordert delete:Defect. Soft-Delete.
Felder und Eingaben
| Feldname | Pflicht | Datentyp | Wirkung beim Ausfuellen | Voraussetzung |
|---|---|---|---|---|
defectNo | automatisch | NumberCircleAssignment | Identifiziert den Mangel in Reports und in der Prüf-Historie. | Nummernkreis konfiguriert. |
defectTypeId | ja | UUID | Klassifizierung der Mangelart. Disabled — wird vom System (Prüf-Modul) gesetzt. | view:DefectType. |
parentId + parentType | ja | polymorph | Verknuepft mit Workorder, WorkorderSystem, Checklist oder ChecklistTileItem. Steuert den Anzeige-Kontext. | view auf den jeweiligen Parent-Typ. |
workorderDefectId | ja | UUID | Verknuepfung zur konkreten Prüfung. | Prüfung muss existieren. |
defectNumber | nein | String | Externe Mangelnummer (z. B. aus Prüf-Bericht). | — |
title | nein | String | Kurztitel — erscheint in Listen und Mangel-Reports. | — |
description | nein | TEXT | Detail-Beschreibung des Mangels für Berichte. | — |
action | nein | TEXT | Erforderliche Massnahme zur Behebung. | — |
deadline | nein | DATE | Frist zur Behebung. Bei Ueberschreitung wird der Mangel als überfällig markiert. | Validierung: deadline >= heute. |
deadlineDays | nein | INTEGER | Frist in Tagen ab Erfassung — alternativ zu deadline. | Validierung: >= 0. |
countryId | nein | UUID | Land für regulatorische Auswertung (z. B. ArbStaettV-Reports). | view:Country. |
defectTypeCategoryId | nein | UUID | Kategorie (z. B. „Sicherheit", „Funktion"). Filter in Reports. | view:DefectTypeCategory. |
defectTypeOperatorId | nein | UUID | Operator/Wartungsverantwortlicher für Eskalation. | view:DefectTypeOperator. |
defectTypePriorityId | nein | UUID | Prioritaet — bestimmt SLA-Reaktionszeit und Sortierung in Listen. | view:DefectTypePriority. |
Workflows und Zustaende
Mängel kennen kein eigenes Status-Enum am Datensatz. Lifecycle ergibt sich aus der zugehörigen Prüfung (workorderDefectId) und der gepflegten deadline/action.
Stand der Doku: Der oben dargestellte Lifecycle ist aus dem Brandschutz-Branchen-Verstaendnis abgeleitet — er ist nicht durch ein zentrales Defect.status-Feld erzwungen. Im Code wird der Mangel-Status aus Workorder-Status + Folge-Workorders abgeleitet. Wenn fachlich noetig, koennte ein eigenes Defect.status mit harter Validierung ergaenzt werden.
Wiederverwendbare Konzepte
- Polymorpher Parent-Pattern —
parentType ∈ {Workorder, WorkorderSystem, Checklist, ChecklistTileItem}. - Berechtigungen verstehen (CASL)
Verknuepfungen zu anderen Modulen
- Auftrag (
Workorder) — typischer Parent. - Anlage (
WorkorderSystem) — bei Anlagen-spezifischen Maengeln. - Checkliste / ChecklistTileItem — bei Prüf-Checklisten.
- Stammdaten:
DefectType,DefectTypeCategory,DefectTypeOperator,DefectTypePriority.
Häufige Fehler und Lösungen
| Fehler | Lösung |
|---|---|
| Mangel kann nicht angelegt werden | POST ist deaktiviert — Mangel über die Prüfung im Wartungs-Modul anlegen. |
deadline Validierung schlaegt fehl | Frist liegt in der Vergangenheit. deadline >= heute setzen. |
| Mangel im Auftragstab nicht sichtbar | Defect:view fehlt oder parentType ≠ Workorder. |
API/Schnittstellen
| Methode | Endpoint | Zweck | CASL |
|---|---|---|---|
GET | /api/defects | Liste | view Defect |
GET | /api/defects/:id | Detail | view Defect |
PATCH | /api/defects/:id | Ändern | update Defect |
DELETE | /api/defects/:id | Soft-Delete | delete Defect |
POST /api/defects existiert im Router, ist aber auskommentiert/deaktiviert.
Versionshinweise
- 2026-04-29: Initiale Veroeffentlichung.