# Task-Cert Modul

Aufgabenverwaltung mit Zielgruppen-Zuweisung, Erledigungsmethoden, Freigabeprozess, Zertifikaten und Eskalationen.

## Schnellstart

```bash
# 1. Schema initialisieren (Erstinstallation)
mysql -u root -p intranet < sql/init.sql

# 2. Migrationen anwenden (bestehende Installation)
mysql -u root -p intranet < sql/migrations/2026-03-17_add_task_responsible.sql
mysql -u root -p intranet < sql/migrations/2026-03-18_add_grace_period.sql
mysql -u root -p intranet < sql/migrations/2026-03-18_add_form_field_prefill.sql

# 3. Cronjobs einrichten (siehe docs/cronjobs.md)
```

## Verzeichnisstruktur

```
tasks/
  bootstrap.php          DI-Container, URL-Mapping, Asset-Helper
  pages/
    admin/               Admin-Views (task_list, task_form, task_detail, ...)
    user/                User-Views (my_tasks, task_detail, Widgets)
  actions/               View-Controller (Datenaufbereitung pro Seite)
  endpoints/
    admin/               Schreibende Admin-Endpunkte (POST/CLI)
    user/                Schreibende User-Endpunkte (POST)
  service/               Business-Logik (10 Services)
  repo/                  DB-Zugriff (Repository-Pattern)
  lib/                   Utility-Klassen (Auth, DB, Request, View, ...)
  sql/
    init.sql             Vollständiges Schema (15 Tabellen)
    migrations/          Inkrementelle Migrationen
  assets/
    css/                 task_cert.css, task_cert_admin.css, task_cert_user.css
    js/                  task_cert_admin_form_wizard.js
    vendor/              MultiSelect-Komponente
  cli/                   Cron-CLI-Skripte
  logs/                  Cron-Logs, Lockfiles, Heartbeat-Dateien
  doc/                   Architektur- und Lifecycle-Dokumentation
  docs/                  Betriebsdokumentation (Cronjobs)
```

## Dokumentation

| Dokument | Inhalt |
|---|---|
| [Architektur & Lifecycle](doc/task-cert-module-lifecycle.md) | Services, Datenmodell, Status-Flows, Troubleshooting |
| [Cronjobs](docs/cronjobs.md) | Einrichtung, Intervalle, CLI-Befehle |
| [Testfälle](doc/task-cert-test-cases.md) | 17 Szenarien mit erwarteten Ergebnissen |

## Services

| Service | Verantwortung |
|---|---|
| `TaskDefinitionService` | Aufgaben CRUD, Zyklen-Reset, Audit-Log |
| `AssignmentResolverService` | Zuweisungen materialisieren & synchronisieren |
| `CycleCalculatorService` | Zyklusberechnung (Kalender- & Erledigungsbasis) |
| `CompletionService` | User-Einreichungen, Methodenabschluss, Completion-Guard |
| `ApprovalService` | Manuelle Freigabe/Ablehnung |
| `CertificateService` | Zertifikate ausstellen/widerrufen |
| `EscalationService` | Eskalationsstufen, Grace-Period-Logik |
| `TaskMonitoringService` | Admin-Dashboard KPIs |
| `TaskCategoryService` | Kategorienverwaltung |
| `TaskLookupService` | Stammdaten-Lookups (Kontakte, Mandanten, ...) |

## Wichtige Konzepte

### Rhythmus-Basis
- **Kalenderbasiert** (`calendar`): Feste Zyklen ab Startdatum (z.B. jeden Monat)
- **Erledigungsbasiert** (`completion`): Nächster Zyklus individuell nach Erledigung

### Karenzzeit (Grace Period)
Neue Zuweisungen erhalten eine `grace_until`-Frist. Die Eskalation greift erst nach `max(due_at, grace_until)`. Konfigurierbar pro Aufgabe in der Erinnerungsrichtlinie (`grace_days`, Default: 7).

### Formular-Vorbefüllung (Prefill)
Textfelder in Formularen können mit Kontaktdaten des Nutzers vorbefüllt werden. Konfigurierbar pro Feld via `prefill_column`. Erlaubte Spalten definiert in `lib/ContactPrefillColumns.php`.

### Completion-Guard
Abgeschlossene Assignments sind gesperrt — erneutes Einreichen wird sowohl im Backend (Exception) als auch im Frontend (disabled Buttons) verhindert.

### Sofortige Folgezyklus-Erstellung
Bei erledigungsbasierten Aufgaben wird der nächste Zyklus direkt nach Completion erstellt (nicht erst beim nächsten Cron-Lauf). Deduplizierung über `createIfNotExists` + Unique-Key.

### Cron-Heartbeat
Erfolgreiche Cron-Läufe schreiben Timestamps nach `logs/heartbeat/*.json`. Status sichtbar am Ende der Admin-Aufgabenliste. Klasse: `lib/CronHeartbeat.php`.

## Cronjobs (Kurzfassung)

```crontab
*/15 * * * * php /path/to/tasks/endpoints/admin/materialize_assignments.php
*/30 * * * * php /path/to/tasks/endpoints/admin/recalculate_escalations.php --apply
0 2 * * *   php /path/to/tasks/endpoints/admin/sync_assignments.php --apply
```

Details: [docs/cronjobs.md](docs/cronjobs.md)