Wartungen & Fälligkeits-Radar (Modul)

Das Modul Wartungen & Fälligkeits-Radar ermöglicht Handwerksbetrieben und Serviceunternehmen die professionelle Organisation von wiederkehrenden Wartungen und Servicevereinbarungen. Es schützt vor vergessenen Prüfterminen, sichert wiederkehrende Jahresumsätze und verbindet Anlagenstammdaten, Prüfchecklisten und Monteurzuweisungen direkt mit der operativen Einsatzplanung.

1. Modul aktivieren (`/settings/modules`)

Das Wartungsmodul ist als konfigurierbares Zusatzmodul im hwr-System integriert:

Aktivierung: Unter Einstellungen -> Module (/settings/modules) kann das Modul Wartungen & Fälligkeits-Radar mit einem Schalter aktiviert oder deaktiviert werden.
Navigation: Nach der Aktivierung erscheint der Eintrag Wartungen (/maintenance) in der Hauptnavigation des Managers.
Granulare Rechteverwaltung: Die Berechtigungen werden in den Rolleneinstellungen (/organization/roles) verwaltet:
- maintenance:view: Berechtigt zur Ansicht des Dashboards, des Fälligkeits-Radars und der Wartungen.
- maintenance:manage: Berechtigt zum Anlegen, Bearbeiten, Löschen von Wartungen und zur Generierung von Wartungsaufträgen.
- maintenance:view_prices: Berechtigt zur Ansicht von Abrechnungspreisen, Pauschalen und ARR in Wartungen.
- In der Rollenmatrix wird die Kategorie Wartungen dynamisch nur angezeigt, wenn das Modul für die Organisation aktiv ist.

2. Fälligkeits-Radar & Dashboard (`/maintenance`)

Das Wartungs-Dashboard bietet eine strukturierte Übersicht über alle fälligen Serviceeinsätze des Betriebs:

Radar-Kennzahlen (KPI-Kacheln)

Überfällig: Zeigt alle aktiven Wartungen an, deren Fälligkeitsdatum vor dem heutigen Tag liegt. Ein Warnindikator signalisiert sofortigen Handlungsbedarf.
Diesen Monat fällig: Listet Wartungen auf, deren Service im aktuellen Kalendermonat ansteht.
Nächste 90 Tage: Dient der vorausschauenden Kapazitäts- und Tourenplanung für das kommende Quartal.
Aktive Wartungen: Gesamtzahl aller laufenden Wartungsvereinbarungen der Organisation.
Jährliches Volumen: Aggregiertes jährliches Netto-Auftragsvolumen aller aktiven Pauschalen (tabular-nums, wird bei fehlender Preissichtbarkeit automatisch ausgeblendet).

Schnelle Filterung, Suche & Preisschutz

Volltextsuche: Sucht verzögerungsfrei nach Wartungsnummern, Bezeichnungen, Kunden oder individuellen Notizen (SearchInput).
Segmented Control: Wechseln Sie mit einem Klick zwischen Alle Fälligkeiten, Überfällig, Diesen Monat, Nächste 90 Tage und Pausiert.
Preisschutz via Rechteverwaltung: Die Sichtbarkeit von Abrechnungskonditionen und Beträgen wird strikt über die Berechtigung maintenance:view_prices geregelt. Für reine Monteure und Techniker vor Ort ohne diese Berechtigung sind Kalkulationen, Abrechnungsspalten und ARR-Kacheln automatisch vollständig ausgeblendet.
Getrennte Spalten: Kunde und Einsatzort werden übersichtlich in zwei separaten Tabellenspalten geführt.

3. Wartungen anlegen & verwalten

Beim Anlegen oder Bearbeiten eines Wartungsvertrags werden alle organisatorischen und technischen Rahmenbedingungen hinterlegt:

Vertragsstammdaten

Titel / Bezeichnung: Prägnante Beschreibung des Serviceumfangs (z. B. Jährliche Wartung Wärmepumpe Vitocal).
Vertragsnummer: Eindeutige Nummerierung (z. B. WV-2026-1042). Bleibt das Feld leer, vergibt hwr automatisch eine fortlaufende Kennung.
Kunde & Einsatzort: Zuordnung zum Auftraggeber und optional zum konkreten Leistungsort.
Kundenanlage (Asset): Direkte Verknüpfung mit der registrierten Anlage des Kunden (inklusive Seriennummer, Hersteller und Standort).
Checklisten-Vorlage: Automatische Zuweisung einer Prüfliste (z. B. Wartung Gasbrennwert VDI 2035), die bei der Auftragserstellung direkt als Pflichtprüfpfad angehängt wird.
Bevorzugter Techniker: Zuweisung eines festen Monteurs oder Kundendiensttechnikers für diesen Vertrag.

Intervall, Fälligkeit & Saisonwartung

Frequenz: Wählbar zwischen Jährlich, Monatlich, Wöchentlich oder Täglich.
Schrittweite / Intervall: Beliebige Intervalle definierbar (z. B. alle 2 Jahre für Großrevisionen, alle 6 Monate für Filterwechsel).
Bevorzugter Monat (Saisonwartung): Fester Zielmonat im Jahr (z. B. September vor Beginn der Heizperiode), um Wartungen saisonal zu bündeln.
Nächste Fälligkeit: Stichtag für den nächsten fälligen Einsatz.
Planmäßige Dauer: Voraussichtliche Arbeitszeit in Minuten (z. B. 90 Minuten) zur präzisen Belegung im Kalender der Einsatzplanung.

Abrechnung & Konditionen

Abrechnungsart:
- Pauschale (flat_rate): Fester Betrag mit flexibler Zahlungsweise.
- Nach Aufwand (time_and_material): Abrechnung nach tatsächlich geleisteten Monteurstunden und verbrauchtem Material.
- In Miete enthalten (included_in_rent): Wartung ist Bestandteil eines Miet- oder Vollservicevertrags.
Zahlungsweise & Abrechnungsintervall (billing_interval):
- Je Wartungseinsatz (per_service): Betrag wird pro Vor-Ort-Einsatz fällig (Standard).
- Monatlich (monthly): Monatliches Service-Abo (z. B. 19,90 € / Monat), fließt mit Faktor 12 in das Jahresvolumen (ARR) ein.
- Vierteljährlich (quarterly): Quartalsweise Abrechnung (Faktor 4 für ARR).
- Jährlich (yearly): Jährliche Vorauszahlung der Service-Pauschale.
Vertragslaufzeit & Stichtage:
- Vertragsbeginn (starts_at): Gültigkeitsstart des Wartungsvertrags.
- Gesamtlaufzeit (contract_duration_months): Wählbar als unbefristet (fortlaufend) oder mit fester Laufzeit (12, 24, 36, 48, 60 Monate sowie frei definierbare Monatsanzahl).
- Vertragsende (ends_at): Wird bei fester Laufzeit automatisch berechnet oder läuft bei unbefristeten Verträgen bis zur Kündigung.
Kündigungsfrist: Angabe der Frist in Monaten zur sauberen Vertragsüberwachung.
Status: Aktiv, Pausiert (z. B. bei temporärem Stillstand) oder Gekündigt.
Wartungsvereinbarungen & Sprach-Diktat: Freitextfeld für Zugangsdaten, Schlüsselvereinbarungen oder Monteurhinweise inklusive integrierter Sprachtranskription zur freihändigen Spracheingabe.

4. 1-Klick-Auftragsgenerierung & Intervall-Weiterschaltung

Die Auftragserstellung erfolgt auf Knopfdruck ohne manuelles Abtippen von Daten:

Einzel-Auftragserstellung

Ein Klick auf Auftrag erstellen in der Tabellenzeile erzeugt unmittelbar den Arbeitsauftrag.
Das System generiert eine offizielle Auftragsnummer über den hinterlegten Nummernkreis (generate_next_number).
Alle hinterlegten Parameter werden atomar übertragen:
- Kunde und Einsatzort
- Verknüpfung der Kundenanlage (job_assets)
- Anbindung der Prüfcheckliste (job_checklists)
- Zuweisung des Monteurs (job_assignments)
- Übernahme der geschätzten Arbeitszeit und des Fälligkeitstermins

Serien- & Batch-Lauf

Mehrere oder alle fälligen Verträge können per Checkbox markiert werden.
Über die Aktionsleiste X Aufträge generieren werden alle markierten Wartungen in einem Durchlauf erzeugt.
Eine Erfolgsrückmeldung fasst die generierten Auftragsnummern übersichtlich zusammen.

Automatische Intervall-Weiterschaltung (GoBD-konform)

Nach erfolgreicher Auftragsgenerierung setzt das System den Zeitstempel last_generated_at = now().
Das Fälligkeitsdatum next_due_at wird automatisch gemäß des vertraglichen Rhythmus auf den nächsten Zyklus weitergeschaltet (z. B. exakt +1 Jahr).
Der generierte Auftrag bleibt über jobs.maintenance_schedule_id dauerhaft und revisionssicher mit dem Wartungsvertrag verknüpft.

5. Vollwertige Detailseite (`/maintenance/[id]`)

Jeder Wartungsvertrag verfügt über eine dedizierte, direkt verlinkbare Detailseite (/maintenance/[id]):

Kopfbereich & Schnellübersicht:
- Titel, Vertragsnummer, Status-Badge (Aktiv, Pausiert, Gekündigt) und Fälligkeits-Indikator (Überfällig, Diesen Monat, Geplant).
- Direkte Aktionsbuttons für Auftrag erstellen, Bearbeiten und Löschen.
- 4 KPI-Karten mit Vertragsnummer, Fälligkeit, verknüpftem Kunden / Einsatzort und Abrechnungskonditionen.
Tab 1: Übersicht & Konditionen:
- Vollständige Aufschlüsselung der Stammdaten, Kundenanlage, Prüfliste und Monteurzuweisung.
- Zeitplan mit Frequenz, Saisonmonat und planmäßiger Einsatzdauer.
- Abrechnungsdaten mit Pauschalbetrag, Intervall, Laufzeit, Kündigungsfrist und Stichtagen (nur bei aktiver Preissichtbarkeit).
- Freitextfeld für Wartungsvereinbarungen und Notizen.
Tab 2: Auftragshistorie (jobs):
- Lückenlose Auflistung aller jemals aus diesem Wartungsvertrag erzeugten Arbeitsaufträge.
- Anzeige von Auftragsnummer, Betreff, Bearbeitungsstatus, Fälligkeitsdatum und eingesetztem Techniker.
- Direkte Verlinkung zum jeweiligen Auftrag (/jobs/[id]).
Tab 3: Dokumente & Verträge:
- Revisionssichere Dateiablage via CustomFileUpload.
- Upload von signierten PDF-Wartungsverträgen, Abnahmeprotokollen, Messberichten und technischen Datenblättern.
- Direkte Vorschau-, Download- und Löschfunktionen.

6. Rollenbasierte Preissichtbarkeit vor Ort

Gemäß den Workspace-Richtlinien schützt das System sensible betriebliche Kalkulationsdaten:

Monteure vor Ort (hwr.mobile): Techniker sehen im mobilen Arbeitsauftrag die Anlage, technische Daten, Checklisten und Arbeitsanweisungen. Vertragskonditionen und Pauschalpreise sind für Monteure ausgeblendet.
Büro & Kalkulation (hwr.manager): Meister, Planer und Disponenten haben vollständige Einsicht in Abrechnungsarten, Pauschalbeträge und Umsatzstatistiken.