feat: month closures, tariff rules, vacation entitlement engine, and NC32 compatibility

Adds MonthClosure system with auto-finalize, revision history, and PDF export;
TariffRuleSet/Module for tariff-based vacation policies; VacationEntitlementEngine
with snapshot service; admin notifications; NC32 migration steps (1014-1019);
accessibility and responsive UI improvements; updated docs and release notes.

Made-with: Cursor

Author: aSoftwareByDesignRepository

.eslintrc.cjs

@@ -17,11 +17,38 @@ module.exports = {
     sourceType: 'module',
   },
   ignorePatterns: ['node_modules/', 'vendor/'],
+  overrides: [
+    {
+      files: ['js/**/*.test.js'],
+      rules: {
+        'no-restricted-syntax': 'off',
+      },
+    },
+  ],
   rules: {
     'no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
     'no-undef': ['error', { typeof: true }],
     'no-inner-declarations': 'off',
     'no-dupe-keys': 'warn',
     'no-useless-escape': 'warn',
+    'no-restricted-syntax': [
+      'error',
+      {
+        selector: "CallExpression[callee.name='fetch'] > Literal:first-child[value=/^\\/apps\\/arbeitszeitcheck\\//]",
+        message: 'Do not call fetch() with raw /apps/arbeitszeitcheck paths. Use ArbeitszeitCheckUtils.resolveUrl(...) or Utils.ajax(...).',
+      },
+      {
+        selector: "CallExpression[callee.name='fetch'] > TemplateLiteral:first-child > TemplateElement[value.raw=/^\\/apps\\/arbeitszeitcheck\\//]",
+        message: 'Do not call fetch() with raw /apps/arbeitszeitcheck paths. Use ArbeitszeitCheckUtils.resolveUrl(...) or Utils.ajax(...).',
+      },
+      {
+        selector: "CallExpression[callee.name='fetch'] > Literal:first-child[value=/^(https?:)?\\/\\//]",
+        message: 'External fetch() URLs are disallowed by default. Route through ArbeitszeitCheckUtils.ajax(..., { allowExternal: true }) with justification.',
+      },
+      {
+        selector: "CallExpression[callee.name='fetch'] > TemplateLiteral:first-child > TemplateElement[value.raw=/^(https?:)?\\/\\//]",
+        message: 'External fetch() URLs are disallowed by default. Route through ArbeitszeitCheckUtils.ajax(..., { allowExternal: true }) with justification.',
+      },
+    ],
   },
 }

.gitignore

@@ -34,6 +34,9 @@ config/config.php
 # Build output
 build/
 
+# Generated by occ integrity:sign-app during release signing
+appinfo/signature.json
+
 # Release tarballs / signatures (docs + CHECKSUMS-*.txt may be committed)
 release/*.tar.gz
 release/*.tar.gz.asc

CHANGELOG.de.md

@@ -1,5 +1,45 @@
 ## [Unreleased]
 
+### Hinzugefügt
+
+- **Auto-Fallback mit Nachvollziehbarkeit**: Zeiteinträge speichern jetzt `ended_reason` und `policy_applied` (z. B. `manual_clock_out` oder `auto_break_fallback`) für klare Audit-/Export-Nachweise.
+- **Einmalige Nutzerinfo nach Auto-Ausstempeln**: Beim nächsten Statusabruf wird eine neutrale, konkrete Meldung mit Uhrzeit und Regel eingeblendet.
+- **Urlaubsanspruch-Policy-Engine**: Neue berechnungslogikbasierte Anspruchsermittlung mit Modi `manual_fixed`, `model_based_simple`, `tariff_rule_based` und `manual_exception` inkl. Simulations-Endpunkt für Admins.
+- **Tarifregel-Datenmodell und APIs**: Versionierte Tarif-Regelwerke/Module sowie Admin-Endpunkte zum Erstellen, Aktualisieren, Aktivieren, Stilllegen und Zuweisen von Urlaubs-Policies.
+- **Snapshots der Anspruchsberechnung**: Persistente Snapshots (`at_entitlement_snapshots`) mit Berechnungstrace/Policy-Fingerprint für Nachvollziehbarkeit und Diagnose.
+- **Neue Admin-Seite „Benachrichtigungen“**: Eigene Oberfläche für HR-Empfänger und Ereignis-Matrix inkl. dedizierter Notifications-API.
+
+### Geändert
+
+- **Fallback-Logik differenziert nach Einsatzart**: Für Schichtarbeit gilt standardmäßig eine strikte Fallback-Regel; für Nicht-Schichtmodelle eine flexible Regel mit tagsüber konfigurierbarem Ruhefenster (z. B. Familien-/Mittagsunterbrechung ohne Auto-Ausstempeln).
+- **Export-Transparenz**: CSV/JSON-Zeilen enthalten jetzt `ended_reason` und `policy_applied`, damit automatische Beendigungen in Reports eindeutig erkennbar sind.
+- **Urlaubsallokation integriert**: Jahresallokation nutzt nun die neue `VacationEntitlementEngine` und liefert Quelle/Regelwerk/Trace in der Ergebnisstruktur zurück.
+- **Migrations-Kompatibilität**: Bestehende Urlaubswerte aus Nutzer-Modellzuweisungen werden in Policy-Zuordnungen überführt (`Version1018Date20260420123000`), damit Bestandsinstallationen konsistent weiterlaufen.
+- **Admin-Einstellungsfluss für Abwesenheiten**: Carryover-/Rollover-, Vertretungs- und E-Mail-Schalter sind zentral über die neue Notifications-Seite/API steuerbar.
+- **Schema Arbeitszeitmodelle**: `at_models` enthält jetzt `work_days_per_week` (`Version1019Date20260420150000`) als Grundlage für Formeln.
+
+### Behoben
+
+- **Aufräumen bei Nutzerlöschung**: Beim Entfernen eines Nutzers werden jetzt auch Urlaubs-Policy-Zuordnungen und Entitlement-Snapshots gelöscht (keine verwaisten Policy-/Berechnungsdaten).
+
+## 1.2.0 – 2026-04-15
+
+### Behoben
+
+- **Zeitzonen-Konsistenz (Europe/Berlin)**: Server-/PHP-Zeitzone für ArbeitszeitCheck auf Deutschland ausgerichtet; neue Migration `Version1015Date20260415120000` konvertiert bestehende UTC-DATETIME-Werte in App-Tabellen nach `Europe/Berlin` und setzt `app_timezone` explizit.
+- **Ausstempeln-Semantik korrigiert**: `clockOut()` finalisiert Einträge nun zuverlässig mit `end_time` und `status=completed` (statt `paused` ohne Endzeit). Dadurch sind Exporte/Reports wieder vollständig und konsistent.
+- **Historische Pausiert-Einträge repariert**: Migration schließt verwaiste Einträge mit `status=paused` und `end_time IS NULL` automatisch über `end_time = updated_at` und Statuswechsel auf `completed`.
+- **Mehrfach-Pausen ohne Datenverlust**: Beim Start einer weiteren Pause wird die zuvor abgeschlossene Pause zuerst in `breaks` (JSON) archiviert; Break-Dauern bleiben vollständig für ArbZG-Prüfungen erhalten.
+- **Break-Status-Berechnung korrigiert**: `getBreakStatus()` zählt aktive Sitzungszeit nicht mehr doppelt; Warnstufen und Restpausen-Hinweise sind wieder korrekt.
+- **Export-Spalten korrigiert**: `duration_hours` liefert jetzt Brutto-Dauer (Wall-Clock), `working_hours` Netto-Arbeitszeit (abzgl. Pausen). Vorher waren beide Spalten identisch.
+
+### Geändert
+
+- **Export-Transparenz**: CSV/JSON-Exporte enthalten jetzt explizite Zeitzonen-Metadaten (`timezone`, `exported_at`), damit nachgelagerte Systeme die Uhrzeiten eindeutig interpretieren.
+- **UI-Klarheit**: Dashboard zeigt sichtbaren Zeitzonen-Hinweis (`Europe/Berlin (MEZ/MESZ)`), Export-Hinweis auf der Zeiteintragsseite nennt die verwendete Zeitzone.
+- **Bediensicherheit**: Vor `Clock Out` erscheint eine Bestätigungsabfrage mit klarer Abgrenzung zwischen „Pause starten“ und „Ausstempeln“.
+- **Admin-Transparenz**: In den Admin-Einstellungen wird die konfigurierte Zeitzone sichtbar angezeigt.
+
 ## 1.1.14 – 2026-04-14
 
 ### Behoben

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Vacation entitlement policy engine**: New policy-driven calculation flow with support for `manual_fixed`, `model_based_simple`, `tariff_rule_based`, and `manual_exception`, plus admin simulation endpoint.
+- **Tariff rule data model and APIs**: Added versioned tariff rule sets/modules and admin endpoints to create, update, activate, retire, and assign policies to users.
+- **Entitlement computation snapshots**: Added persistent entitlement snapshots (`at_entitlement_snapshots`) with calculation trace/policy fingerprint for auditability and diagnostics.
+- **Admin notifications page**: New dedicated admin UI (`/admin/notifications`) with HR recipient + event matrix management and a dedicated notifications settings API.
+
+### Changed
+
+- **Vacation allocation integration**: Year allocation now resolves entitlement via `VacationEntitlementEngine` and returns entitlement source/rule-set/trace metadata in allocation payloads.
+- **Policy migration compatibility**: Existing user model vacation values are backfilled into policy assignments during migration (`Version1018Date20260420123000`) to keep legacy installs consistent.
+- **Admin settings flow**: Absence notification-related controls (carryover expiry/cap, rollover switches, substitute-required types, iCal and substitution-mail toggles) are centralized on admin notifications APIs/UI.
+- **Working time model schema**: Added `work_days_per_week` to `at_models` (`Version1019Date20260420150000`) to support entitlement formulas.
+
+### Fixed
+
+- **User deletion cleanup**: Deleting a user now also removes vacation policy assignments and entitlement snapshots, preventing orphaned policy/computation data.
+
 ## 1.1.14 - 2026-04-14
 
 ### Fixed

README.md

@@ -13,10 +13,12 @@ Die App läuft vollständig innerhalb Ihrer selbst gehosteten Nextcloud‑Instan
   - Ruhezeiten (11h) mit Blockierung von Clock‑In und manuellen Einträgen
   - Erkennung von Nacht‑, Sonn‑ und Feiertagsarbeit inkl. Dokumentation
 - **Abwesenheitsmanagement**: Urlaub, Krankheit, Sonderurlaub, unbezahlter Urlaub mit Genehmigungsworkflow; **Resturlaub / Vorjahres‑Tage** mit konfigurierbarem Ablaufdatum (z. B. 31.03.), FIFO‑Verbrauch, Admin‑Pflege und optional CSV‑Import (`occ arbeitszeitcheck:import-vacation-balance`)
+- **Urlaubsanspruch-Engine (neu erweitert)**: Pro Mitarbeitenden konfigurierbarer Modus (manuell, modellbasiert oder tarif-/regelbasiert), zeitlich gültige Policy-Zuordnungen, aktive Regelwerk-Versionierung und nachvollziehbare Berechnungs-Trace-Daten inkl. Snapshot-Ablage für Auswertungen
 - **Team‑ und Manager‑Ansicht**: Genehmigungen, Team‑Übersichten, Compliance‑Status
 - **Berichte & Exporte**: Tages/Wochen/Monats‑Reports, Overtime‑Reports, Absenzberichte, DATEV‑Export
 - **Audit‑Logs**: Lückenlose Nachvollziehbarkeit von Änderungen an Zeiten, Abwesenheiten und Einstellungen
 - **Revisionssichere Monatsfinalisierung** (optional, Admin‑Schalter): Kalendermonat mit Snapshot, Hash und PDF‑Nachweis abschließen; finalisierte Monate bleiben gesperrt, bis eine Administratorin/ein Administrator mit Begründung wieder öffnet
+- **Admin-Benachrichtigungen (neu erweitert)**: Eigene Admin-Seite für HR-E-Mail-Matrix (pro Abwesenheitstyp und Ereignis), Empfänger-Validierung/Deduplizierung sowie zentrale Steuerung von Carryover-/Rollover- und Substitutions-Mail-Einstellungen
 - **DSGVO‑Support**: Exporte, Löschkonzepte (unter Beachtung der gesetzlichen Aufbewahrung), DPIA‑/Verarbeitungsverzeichnis‑Vorlagen
 
 > **Rechtlicher Hinweis (DE):**  

appinfo/info.xml

@@ -54,7 +54,7 @@ gehosteten Nextcloud.
 - PHP 8.1–8.4
 	]]></description>
 
-	<version>1.1.14</version>
+	<version>1.2.0</version>
 	<licence>AGPL-3.0-or-later</licence>
 	<author mail="info@software-by-design.de" homepage="https://software-by-design.de">Alexander Mäule</author>
 

appinfo/routes.php

@@ -81,6 +81,10 @@
 		['name' => 'manager#dashboard', 'url' => '/manager', 'verb' => 'GET'],
 		['name' => 'manager#employeeTimeEntriesPage', 'url' => '/manager/time-entries', 'verb' => 'GET'],
 		['name' => 'manager#employeeAbsencesPage', 'url' => '/manager/absences', 'verb' => 'GET'],
+		['name' => 'manager#monthClosuresPage', 'url' => '/manager/month-closures', 'verb' => 'GET'],
+		['name' => 'manager#revisionPdfUsers', 'url' => '/api/manager/revision-pdf/users', 'verb' => 'GET'],
+		['name' => 'manager#revisionPdfAvailableMonths', 'url' => '/api/manager/revision-pdf/available-months', 'verb' => 'GET'],
+		['name' => 'manager#revisionPdfUsersForMonth', 'url' => '/api/manager/revision-pdf/users-for-month', 'verb' => 'GET'],
 		['name' => 'manager#getTeamOverview', 'url' => '/api/manager/team-overview', 'verb' => 'GET'],
 		['name' => 'manager#getEmployeeTimeEntries', 'url' => '/api/manager/employee-time-entries', 'verb' => 'GET'],
 		['name' => 'manager#getEmployeeAbsences', 'url' => '/api/manager/employee-absences', 'verb' => 'GET'],
@@ -134,11 +138,14 @@
 		['name' => 'admin#dashboard', 'url' => '/admin', 'verb' => 'GET'],
 		['name' => 'admin#users', 'url' => '/admin/users', 'verb' => 'GET'],
 		['name' => 'admin#settings', 'url' => '/admin/settings', 'verb' => 'GET'],
+		['name' => 'admin#notifications', 'url' => '/admin/notifications', 'verb' => 'GET'],
 		['name' => 'admin#holidays', 'url' => '/admin/holidays', 'verb' => 'GET'],
 		['name' => 'admin#workingTimeModels', 'url' => '/admin/working-time-models', 'verb' => 'GET'],
 		['name' => 'admin#auditLog', 'url' => '/admin/audit-log', 'verb' => 'GET'],
 		['name' => 'admin#getAdminSettings', 'url' => '/api/admin/settings', 'verb' => 'GET'],
 		['name' => 'admin#updateAdminSettings', 'url' => '/api/admin/settings', 'verb' => 'POST'],
+		['name' => 'admin#getNotificationSettings', 'url' => '/api/admin/notifications/settings', 'verb' => 'GET'],
+		['name' => 'admin#updateNotificationSettings', 'url' => '/api/admin/notifications/settings', 'verb' => 'POST'],
 		// Legacy company_holidays JSON (kept for backward compatibility; new code should use state-holidays endpoints)
 		['name' => 'admin#getCompanyHolidays', 'url' => '/api/admin/holidays', 'verb' => 'GET'],
 		['name' => 'admin#saveCompanyHoliday', 'url' => '/api/admin/holidays', 'verb' => 'POST'],
@@ -161,6 +168,13 @@
 		['name' => 'admin#createWorkingTimeModel', 'url' => '/api/admin/working-time-models', 'verb' => 'POST'],
 		['name' => 'admin#updateWorkingTimeModel', 'url' => '/api/admin/working-time-models/{id}', 'verb' => 'PUT'],
 		['name' => 'admin#deleteWorkingTimeModel', 'url' => '/api/admin/working-time-models/{id}', 'verb' => 'DELETE'],
+		['name' => 'admin#getTariffRuleSets', 'url' => '/api/admin/tariff-rule-sets', 'verb' => 'GET'],
+		['name' => 'admin#createTariffRuleSet', 'url' => '/api/admin/tariff-rule-sets', 'verb' => 'POST'],
+		['name' => 'admin#updateTariffRuleSet', 'url' => '/api/admin/tariff-rule-sets/{id}', 'verb' => 'PUT'],
+		['name' => 'admin#activateTariffRuleSet', 'url' => '/api/admin/tariff-rule-sets/{id}/activate', 'verb' => 'POST'],
+		['name' => 'admin#retireTariffRuleSet', 'url' => '/api/admin/tariff-rule-sets/{id}/retire', 'verb' => 'POST'],
+		['name' => 'admin#assignVacationPolicy', 'url' => '/api/admin/users/{userId}/vacation-policy', 'verb' => 'PUT'],
+		['name' => 'admin#simulateVacationPolicy', 'url' => '/api/admin/vacation-policy/simulate', 'verb' => 'POST'],
 
 		// Admin teams (app-owned teams/departments)
 		['name' => 'admin#teams', 'url' => '/admin/teams', 'verb' => 'GET'],
@@ -195,5 +209,14 @@
 
 		// Health check route
 		['name' => 'health#check', 'url' => '/health', 'verb' => 'GET'],
+
+		// Revision-safe month closure
+		['name' => 'month_closure#feature', 'url' => '/api/month-closure/feature', 'verb' => 'GET'],
+		['name' => 'month_closure#periods', 'url' => '/api/month-closure/periods', 'verb' => 'GET'],
+		['name' => 'month_closure#status', 'url' => '/api/month-closure/status', 'verb' => 'GET'],
+		['name' => 'month_closure#finalize', 'url' => '/api/month-closure/finalize', 'verb' => 'POST'],
+		['name' => 'month_closure#pdf', 'url' => '/api/month-closure/pdf', 'verb' => 'GET'],
+		['name' => 'month_closure#finalizedMonths', 'url' => '/api/month-closure/finalized-months', 'verb' => 'GET'],
+		['name' => 'month_closure#reopen', 'url' => '/api/month-closure/reopen', 'verb' => 'POST'],
 	],
 ];