awo-hamburg-intranet/module/tasks/docs/cronjobs.md

Cronjobs — Task-Modul

Das Task-Modul benötigt drei Cronjobs, die regelmäßig laufen müssen:

1. Assignments materialisieren — erstellt neue Aufgaben-Zuweisungen für aktive Zyklen
2. Assignments synchronisieren — gleicht Zuweisungen mit aktuellen Zielgruppen-Regeln ab
3. Eskalationen berechnen — markiert überfällige Aufgaben und erhöht Eskalationsstufen

Alle CLI-Skripte liegen in cli/ und nutzen CronRuntime mit:

• Locking (verhindert parallele Läufe)
• Strukturiertes Log (logs/task_cert_cron.log, JSON-Lines)
• Heartbeat (logs/heartbeat/{job}.json für Admin-UI)
• Exit-Codes (0 = OK, 1 = Fehler, 2 = ungültige Parameter, 3 = Lock aktiv)
• CLI-Ausgabe ([OK]/[SKIP]/[ERROR] auf stdout/stderr)

---

1. Assignments materialisieren

Erstellt für alle aktiven Aufgaben die Zuweisungen im aktuellen Zyklus (z.B. neuer Monat = neue Assignments).

php cli/task_cert_materialize_assignments.php

Optionen:

• --no-lock — Locking deaktivieren (nur Debug)
• --json — JSON-Ausgabe zusätzlich auf stdout
• --help — Hilfe anzeigen

Empfohlenes Intervall: alle 15 Minuten

Was passiert:

• Ermittelt den aktuellen Zyklus jeder aktiven Aufgabe (Tag/Woche/Monat/Jahr)
• Erstellt fehlende Assignments für alle Zielkontakte
• Bei completion-based Tasks: erstellt den nächsten Zyklus nach Abschluss
• Operation ist idempotent (kein --apply nötig)

---

2. Assignments synchronisieren

Gleicht bestehende Assignments mit den aktuellen Zielgruppen-Regeln ab. Nützlich wenn sich Abteilungszugehörigkeiten oder Rollen ändern.

# Alle aktiven Aufgaben (Anwenden)
php cli/task_cert_sync_assignments.php --apply

# Dry-Run (nur Vorschau)
php cli/task_cert_sync_assignments.php --dry-run

# Einzelne Aufgabe
php cli/task_cert_sync_assignments.php --apply --task_id=42

Optionen:

• --apply — Mutierender Lauf (Zuweisungen anlegen/entfernen)
• --dry-run — Nur Vorschau, keine DB-Änderungen
• --task_id=<id> — Optional: nur eine Aufgabe verarbeiten
• --no-lock — Locking deaktivieren (nur Debug)
• --json — JSON-Ausgabe zusätzlich auf stdout
• --help — Hilfe anzeigen

Empfohlenes Intervall: täglich nachts (z.B. 02:00)

Was passiert:

• Vergleicht Soll-Zielgruppe (Regeln + Overrides) mit Ist-Zuweisungen
• Erstellt fehlende Assignments, entfernt veraltete
• Schützt abgeschlossene Assignments und solche mit Zertifikaten vor Löschung

---

3. Eskalationen berechnen

Prüft alle offenen Assignments auf Überfälligkeit und berechnet Eskalationsstufen.

# Alle Aufgaben (Anwenden)
php cli/task_cert_recalculate_escalations.php --apply

# Dry-Run
php cli/task_cert_recalculate_escalations.php --dry-run

# Einzelne Aufgabe
php cli/task_cert_recalculate_escalations.php --apply --task_id=42

Optionen:

• --apply — Mutierender Lauf (Status/Eskalationslevel schreiben)
• --dry-run — Nur Vorschau, keine DB-Änderungen
• --task_id=<id> — Optional: nur eine Aufgabe verarbeiten
• --no-lock — Locking deaktivieren (nur Debug)
• --json — JSON-Ausgabe zusätzlich auf stdout
• --help — Hilfe anzeigen

Empfohlenes Intervall: alle 30 Minuten

Was passiert:

• Prüft due_at aller offenen/laufenden Assignments
• Setzt status = 'overdue' wenn Deadline überschritten
• Berechnet escalation_level anhand der Erinnerungsrichtlinie:
  • first_escalation_days: Tage nach Fälligkeit bis erste Eskalation
  • step_days: Tage zwischen Eskalationsstufen
  • max_level: Maximale Eskalationsstufe
• Protokolliert Eskalations-Events in task_escalation_event
• Setzt Eskalation zurück wenn Aufgabe nicht mehr überfällig ist

---

Crontab-Einrichtung

# Assignments materialisieren — alle 15 Minuten
*/15 * * * * cd /var/www/intranet/html/module/tasks && /usr/bin/php cli/task_cert_materialize_assignments.php >> /var/www/intranet/html/module/tasks/logs/task_cert_cron.log 2>&1

# Eskalationen berechnen — alle 30 Minuten
*/30 * * * * cd /var/www/intranet/html/module/tasks && /usr/bin/php cli/task_cert_recalculate_escalations.php --apply >> /var/www/intranet/html/module/tasks/logs/task_cert_cron.log 2>&1

# Assignments synchronisieren — täglich um 02:00
0 2 * * * cd /var/www/intranet/html/module/tasks && /usr/bin/php cli/task_cert_sync_assignments.php --apply >> /var/www/intranet/html/module/tasks/logs/task_cert_cron.log 2>&1

Hinweis: Den Pfad /var/www/intranet/html/module/tasks ggf. an die tatsächliche Installation anpassen. PHP-Binary-Pfad mit which php prüfen.

---

Reihenfolge

Wenn alle Jobs gleichzeitig laufen sollen, ist die empfohlene Reihenfolge:

1. task_cert_materialize_assignments.php — erst Assignments anlegen
2. task_cert_sync_assignments.php --apply — dann synchronisieren
3. task_cert_recalculate_escalations.php --apply — dann Eskalationen berechnen

Bei getrennten Intervallen (wie oben) ist die Reihenfolge unkritisch.

---

Exit-Codes

Code	Bedeutung
0	Erfolg
1	Fehler (Exception)
2	Ungültige CLI-Parameter
3	Lock aktiv, Job übersprungen

---

Logging

CLI-Ausgabe (stdout/stderr)

Jeder Lauf schreibt eine Zeile auf stdout bzw. stderr:

• [OK] sync_assignments (apply) abgeschlossen in 312ms.
• [SKIP] sync_assignments: Lock aktiv, Job wird übersprungen.
• [ERROR] sync_assignments (apply): DB-Verbindung fehlgeschlagen

Bei --json wird stattdessen ein JSON-Objekt auf stdout ausgegeben.

Strukturiertes Log

Alle Läufe (Erfolg, Fehler, Skip) werden in logs/task_cert_cron.log als JSON-Lines geschrieben — unabhängig von der Crontab-Umleitung.

Locking

Lockfiles liegen in logs/locks/:

• task_cert_materialize_assignments.lock
• task_cert_sync_assignments.lock
• task_cert_recalculate_escalations.lock

---

Monitoring (Heartbeat)

Jeder erfolgreiche Apply-Lauf schreibt einen Timestamp nach logs/heartbeat/{job}.json.

Status prüfen:

cat logs/heartbeat/materialize_assignments.json
cat logs/heartbeat/recalculate_escalations.json
cat logs/heartbeat/sync_assignments.json

Admin-Ansicht: Die Admin-Aufgabenliste zeigt automatisch den letzten erfolgreichen Lauf jedes Jobs am unteren Rand an. Wenn ein Job noch nie gelaufen ist, wird dies rot markiert.

Hinweis: Heartbeat-Dateien werden nur bei erfolgreichem Lauf geschrieben. Fehler sind am Ausbleiben des Timestamps erkennbar.

---

Legacy-Endpoints

Die alten Endpoint-Skripte (endpoints/admin/) bleiben als HTTP-Endpoints für die Admin-UI erhalten, sollten aber nicht mehr per Cron aufgerufen werden:

• endpoints/admin/materialize_assignments.php
• endpoints/admin/sync_assignments.php
• endpoints/admin/recalculate_escalations.php

Diese haben kein Locking und keine strukturierte CLI-Ausgabe.