Skip to content

README.md

Latest commit

 

History

History
123 lines (91 loc) · 8.22 KB

README.md

File metadata and controls

123 lines (91 loc) · 8.22 KB

ArbeitszeitCheck (TimeGuard) – ArbZG- und DSGVO-konforme Zeiterfassung für Nextcloud

ArbeitszeitCheck ist eine Zeiterfassungs‑App für Nextcloud, die explizit auf deutsches Arbeitszeitgesetz (ArbZG) und DSGVO/ GDPR ausgerichtet ist.
Die App läuft vollständig innerhalb Ihrer selbst gehosteten Nextcloud‑Instanz – keine externen Cloud‑Dienste, keine Telemetrie.

Kernfunktionen

  • Rechtskonforme Zeiterfassung: Kommen/Gehen, Pausen, manuelle Einträge mit Begründung
  • ArbZG‑Compliance:
    • Max. tägliche Arbeitszeit (8h, erweiterbar auf 10h, reine Arbeitszeit ohne Pausen)
    • Wöchentliche 48‑Stunden‑Durchschnittsprüfung (6‑Monats‑Zeitraum, Manager‑Warnungen)
    • Automatische Pausenberechnung nach ArbZG §4 (30/45 Minuten, nur Pausen ≥ 15 Minuten)
    • 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)
  • 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
  • DSGVO‑Support: Exporte, Löschkonzepte (unter Beachtung der gesetzlichen Aufbewahrung), DPIA‑/Verarbeitungsverzeichnis‑Vorlagen

Rechtlicher Hinweis (DE):
ArbeitszeitCheck unterstützt Arbeitgeber und Administratoren bei der technisch sauberen Umsetzung von ArbZG‑ und DSGVO‑Anforderungen (z. B. Höchstarbeitszeit, Pausen, Ruhezeiten, Aufzeichnungspflichten).
Die App ersetzt keine individuelle Rechtsberatung. Arbeitgeber bleiben rechtlich dafür verantwortlich,

  • wie Arbeitszeitmodelle, Betriebsvereinbarungen und Tarifverträge gestaltet sind,
  • wie Konfigurationen (Grenzwerte, Ausnahmen, Aufbewahrungsfristen) gewählt werden und
  • wie die erfassten Daten ausgewertet und für arbeitsrechtliche Entscheidungen verwendet werden.
    Prüfen Sie Konfiguration, Prozesse und Texte bei Bedarf mit Ihrer Rechtsabteilung oder einem Fachanwalt für Arbeitsrecht.

Legal notice (EN):
ArbeitszeitCheck helps organizations implement technical controls for German working time law (ArbZG) and GDPR (e.g. maximum working hours, breaks, rest periods, record‑keeping).
The app is not a substitute for legal advice. Employers remain legally responsible for:

  • the design of working time models, collective agreements and internal policies,
  • the chosen configuration (limits, exceptions, retention periods), and
  • how recorded data is interpreted and used for HR / legal decisions.
    Always review your setup with your legal counsel if in doubt.

Installation

Aus dem Nextcloud App Store (empfohlen)

  1. Als Nextcloud‑Administrator anmelden
  2. „Apps“ → „Organisation“ / „Produktivität“ öffnen
  3. Nach „ArbeitszeitCheck“ oder „TimeGuard“ suchen
  4. App herunterladen und aktivieren

Manuelle Installation aus Git

git clone https://github.com/aSoftwareByDesignRepository/nextcloud-arbeitszeitcheck.git /path/to/nextcloud/apps/arbeitszeitcheck
cd /path/to/nextcloud
# Optional: PHP‑/JS‑Abhängigkeiten (falls nicht über Release‑Tarball installiert)
# cd apps/arbeitszeitcheck && composer install && npm install
php occ app:enable arbeitszeitcheck

Unterstützte Umgebungen:

  • Nextcloud 32, 33, 34, 35, 36
  • PHP 8.1–8.4
  • Datenbanken: MySQL/MariaDB, PostgreSQL, SQLite (für kleinere Installationen)

Dokumentation

  • Versionshistorie: CHANGELOG.md (EN) / CHANGELOG.de.md (DE) — Release- und Änderungsübersicht (Keep a Changelog).

Index und Kurzbeschreibungen: docs/README.md. Mitgelieferte Dokumente im Ordner docs/:

  • Nutzer
    • User-Manual.de.md / User-Manual.en.md — Kurzanleitung (u. a. Kalenderansicht in der App vs. Nextcloud-Kalender-App; keine CalDAV-Synchronisation)
  • Compliance
    • Compliance-Implementation.de.md / Compliance-Implementation.en.md — technische Umsetzung der ArbZG‑Regeln
    • GDPR-Compliance-Guide.en.md — Betrieb der App im Einklang mit DSGVO/GDPR
  • Entwicklung
    • Developer-Documentation.en.md — Architekturüberblick und Hinweise für Beitragende

Weitere interne Arbeits‑ und Compliance‑Dokumente (z. B. erweiterte Rollenmatrix, Store‑Publishing‑How‑to) können in einem separaten Repository gepflegt werden.

Hinweis Kalender: ArbeitszeitCheck synchronisiert nicht mit der Nextcloud-Kalender-App (CalDAV). Die integrierte Monatsansicht gehört zur App; optional können E-Mails mit .ics-Anhang zum manuellen Import versendet werden.

Projekt & Support

ArbeitszeitCheck wird von Software by Design entwickelt und gepflegt.
Weitere Informationen zu Projekten, Leistungen und Kontaktmöglichkeiten finden Sie auf der Website: https://software-by-design.de/
Für Anfragen per E-Mail erreichen Sie uns unter: info@software-by-design.de

Maintainer & Support (EN):
ArbeitszeitCheck is developed and maintained by Software by Design.
For more information about projects, services and how to get in touch, visit: https://software-by-design.de/
You can also contact us via e-mail: info@software-by-design.de

Nextcloud App Store Assets

  • App‑Metadaten: appinfo/info.xml (Name, Beschreibung, Version, Abhängigkeiten)
  • Lizenz: LICENSE (AGPL‑3.0 oder kompatibel, siehe Datei)
  • Icon: app.svg bzw. img/app.svg
  • Screenshots: im Verzeichnis screenshots/
    • Beschreibung und erwartete Dateien in screenshots/README.md

Diese Dateien werden vom Nextcloud App Store für Listung, Detailseite und Review verwendet.

Entwicklung & Tests

Voraussetzungen: Node.js 20 oder 22 und npm 10+ (siehe package.json → engines), Composer, PHPUnit über composer.json.

  • PHP: composer test (alle Suites), composer test:unit, composer test:integration (Integration unter tests/Integration/), optional composer test:coverage
  • PHP im Docker‑Stack dieses Monorepos: vom Nextcloud‑Server‑Root ./docker/run-app-phpunit.sh arbeitszeitcheck oder in der App composer test:docker bzw. npm run test:php:docker
  • JavaScript (Vitest): npm test, bei Bedarf npm run test:watch
  • Lint: npm run lint, npm run stylelint (sowie composer lint für PHP‑Syntaxcheck unter lib/)
  • E2E (Playwright): npm run e2e — erfordert laufende Nextcloud‑Instanz und Umgebungsvariablen (NC_BASE_URL, Testnutzer); siehe docs/Developer-Documentation.en.md
  • Alle Tests im Container (Hilfsskript): scripts/run-tests-docker.sh vom App‑ bzw. Repo‑Kontext

Hinweis: npm run build ist ein Platzhalter (kein Bundler‑Build; Frontend ist Vanilla‑JS mit PHP‑Templates).

Frontend Runtime & UX Guardrails

  • One URL resolution path: Frontend requests should use ArbeitszeitCheckUtils.ajax(...) (or ArbeitszeitCheckUtils.resolveUrl(...) when using fetch explicitly) to normalize app URLs reliably on both pretty-URL and /index.php installations.
  • Strict external-call policy: ArbeitszeitCheckUtils.ajax(...) blocks cross-origin URLs by default. External calls require explicit opt-in via allowExternal: true.
  • Lint enforcement: ESLint rejects raw fetch('/apps/arbeitszeitcheck/...') and implicit external fetch(...) patterns outside approved abstractions.
  • Mobile/iPhone consistency: Shared layout styles in css/common/ include safe-area-aware spacing and touch-target improvements (WCAG 2.1 AA focus) for user and manager pages.

Weitere Details zur Architektur und zu Beitrag‑Richtlinien finden sich in docs/Developer-Documentation.en.md.