Housekeeping¶

Das Housekeeping-System bereinigt automatisch alte Daten im System. Es laeuft als geplanter Task ueber den Laravel Scheduler und kann ueber die Einstellungen konfiguriert werden.

Uebersicht¶

Housekeeping umfasst fuenf unabhaengige Bereinigungs-Jobs:

Job	Einstellungen-Tab	Was wird bereinigt
Exports	System	Alte Export-Dateien vom S3-Bucket (`export/`)
Rechnungen	Rechnungen	Rechnungen aus der DB + PDF/XML-Dateien vom S3
Zahlungen	Zahlungen	Zahlungen aus der DB (nur wenn Rechnung bereits geloescht)
E-Mails	E-Mail	E-Mails aus der DB (alle ausser Status `error`)
Services	System	Beendete CustomerServices (Soft-Delete)

Jeder Job hat einen eigenen Aktiv/Inaktiv-Schalter und einen konfigurierbaren Zeitraum.

Konfiguration¶

Gesamteinstellungen¶

Navigation: Admin > Konfiguration > Einstellungen > System > Housekeeping

Feld	Beschreibung	Standard
Housekeeping aktiv	Gesamtschalter fuer alle Jobs	`Aus`
Ausfuehrungsfrequenz	Taeglich / Woechentlich (Montags) / Monatlich (1. des Monats)	`Taeglich`
Uhrzeit	Ausfuehrungszeitpunkt im Format HH:MM	`04:00`

Gesamtschalter

Wenn Housekeeping aktiv deaktiviert ist, werden keine Jobs ausgefuehrt — auch nicht bei manuellem Aufruf via php artisan housekeeping:run.

Exports bereinigen¶

Navigation: Admin > Konfiguration > Einstellungen > System > Housekeeping: Exports bereinigen

Feld	Beschreibung	Standard
Export-Bereinigung aktiv	Aktiviert die Bereinigung alter Exports	`Aus`
Exports loeschen nach	Anzahl Tage nach denen Exports geloescht werden	`30`

Loescht Dateien aus dem S3-Bucket unter export/ anhand ihres Aenderungsdatums.

Rechnungen bereinigen¶

Navigation: Admin > Konfiguration > Einstellungen > Rechnungen > Housekeeping: Rechnungen bereinigen

Feld	Beschreibung	Standard
Rechnungs-Bereinigung aktiv	Aktiviert die Bereinigung alter Rechnungen	`Aus`
Rechnungen loeschen nach	Anzahl Jahre (Minimum: 10)	`10`

Gesetzliche Aufbewahrungsfrist

Das Minimum von 10 Jahren ist fest vorgegeben und kann nicht unterschritten werden (gesetzliche Aufbewahrungsfrist fuer Rechnungen in Deutschland).

Was wird geloescht:

PDF-Datei vom S3 (pdf_path)
XML-Datei vom S3 (xml_path)
Zugehoerige Rechnungspositionen (InvoiceItems)
Rechnungs-Datensatz (Soft-Delete)

Zahlungen bereinigen¶

Navigation: Admin > Konfiguration > Einstellungen > Zahlungen > Housekeeping: Zahlungen bereinigen

Feld	Beschreibung	Standard
Zahlungs-Bereinigung aktiv	Aktiviert die Bereinigung alter Zahlungen	`Aus`
Zahlungen loeschen nach	Anzahl Jahre (Minimum: 10)	`10`

Sicherheitsmechanismus

Zahlungen werden nur geloescht, wenn die zugehoerige Rechnung bereits soft-deleted wurde. Zahlungen zu aktiven Rechnungen bleiben unangetastet.

E-Mails bereinigen¶

Navigation: Admin > Konfiguration > Einstellungen > E-Mail > Housekeeping: E-Mails bereinigen

Feld	Beschreibung	Standard
E-Mail-Bereinigung aktiv	Aktiviert die Bereinigung alter E-Mails	`Aus`
E-Mails loeschen nach	Anzahl Tage	`90`

Fehler-E-Mails bleiben erhalten

E-Mails mit dem Status error werden nicht geloescht, damit Fehler nachvollzogen werden koennen.

Beendete Services bereinigen¶

Navigation: Admin > Konfiguration > Einstellungen > System > Housekeeping: Beendete Services

Feld	Beschreibung	Standard
Service-Bereinigung aktiv	Aktiviert die Bereinigung beendeter Services	`Aus`
Beendete Services loeschen nach	Anzahl Tage nach Beendigung	`90`

Regeln fuer die Service-Bereinigung:

Nur Services mit Status Beendet (terminated) und einem stopped_at-Datum aelter als die konfigurierte Frist
Child-Services werden nur geloescht, wenn sie ebenfalls den Status terminated haben
Parent-Services mit aktiven Children werden uebersprungen — es werden keine aktiven, gesperrten oder gekuendigten Child-Services geloescht
Verwaiste Child-Services (deren Parent bereits geloescht wurde) werden einzeln bereinigt
Alle Loeschungen sind Soft-Deletes (wiederherstellbar)

Ausfuehrung¶

Automatisch (Scheduler)¶

Das Housekeeping wird automatisch vom Scheduler-Container ausgefuehrt, basierend auf der konfigurierten Frequenz und Uhrzeit.

# Scheduler-Eintrag pruefen
docker compose exec app php artisan schedule:list

Manuell¶

# Housekeeping ausfuehren
docker compose exec app php artisan housekeeping:run

# Dry-Run: Zeigt was geloescht wuerde, ohne tatsaechlich zu loeschen
docker compose exec app php artisan housekeeping:run --dry-run

Dry-Run zuerst

Bei der Ersteinrichtung empfiehlt es sich, zuerst einen --dry-run durchzufuehren, um zu pruefen welche Daten betroffen waeren.

Logging¶

Alle Housekeeping-Aktionen werden im Laravel-Log protokolliert:

# Log pruefen
docker compose exec app cat storage/logs/laravel.log | grep Housekeeping

Log-Format:

[2025-01-15 04:00:01] local.INFO: Housekeeping gestartet
[2025-01-15 04:00:01] local.INFO: Housekeeping Exports: 5 Datei(en) geloescht (aelter als 30 Tage)
[2025-01-15 04:00:02] local.INFO: Housekeeping Rechnungen: 12 Rechnung(en) geloescht (aelter als 10 Jahre)
[2025-01-15 04:00:02] local.INFO: Housekeeping Zahlungen: 8 Zahlung(en) geloescht (aelter als 10 Jahre)
[2025-01-15 04:00:03] local.INFO: Housekeeping E-Mails: 245 E-Mail(s) geloescht (aelter als 90 Tage, ausser 'error')
[2025-01-15 04:00:03] local.INFO: Housekeeping Services: 3 Service(s) geloescht (Status 'Beendet', aelter als 90 Tage)
[2025-01-15 04:00:03] local.INFO: Housekeeping abgeschlossen

Im Dry-Run-Modus werden alle Log-Eintraege mit [DRY-RUN] gekennzeichnet.

Technische Details¶

Settings-Keys¶

Alle Housekeeping-Einstellungen verwenden den Praefix housekeeping_ und werden in der Gruppe housekeeping gespeichert.

Setting-Key	Typ	Beschreibung
`housekeeping_active`	boolean	Gesamtschalter
`housekeeping_frequency`	string	`daily`, `weekly`, `monthly`
`housekeeping_time`	string	Uhrzeit (HH:MM)
`housekeeping_export_active`	boolean	Export-Job aktiv
`housekeeping_export_days`	integer	Tage fuer Exports
`housekeeping_invoices_active`	boolean	Rechnungs-Job aktiv
`housekeeping_invoices_years`	integer	Jahre fuer Rechnungen (min. 10)
`housekeeping_payments_active`	boolean	Zahlungs-Job aktiv
`housekeeping_payments_years`	integer	Jahre fuer Zahlungen (min. 10)
`housekeeping_emails_active`	boolean	E-Mail-Job aktiv
`housekeeping_emails_days`	integer	Tage fuer E-Mails
`housekeeping_services_active`	boolean	Service-Job aktiv
`housekeeping_services_days`	integer	Tage fuer beendete Services

Artisan Command¶

housekeeping:run [--dry-run]

Option	Beschreibung
`--dry-run`	Zeigt was geloescht wuerde, ohne Aenderungen vorzunehmen

Loeschverhalten¶

Datentyp	Loeschmethode	Wiederherstellbar
S3-Dateien (Exports, PDFs, XMLs)	Hard-Delete	Nein
Rechnungen	Soft-Delete	Ja
Rechnungspositionen	Hard-Delete	Nein
Zahlungen	Hard-Delete	Nein
E-Mails	Soft-Delete	Ja
Services	Soft-Delete	Ja