awo-hamburg-intranet/module/tasks

Task-Cert Modul

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

Schnellstart

# 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	Services, Datenmodell, Status-Flows, Troubleshooting
Cronjobs	Einrichtung, Intervalle, CLI-Befehle
Testfälle	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)

*/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