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).

```bash
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.

```bash
# 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.

```bash
# 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

```crontab
# 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:**
```bash
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.