Zeiterfassung

Eine Full-Stack-Zeiterfassungsanwendung, entwickelt mit Node.js, Express, SQLite und containerisiert mit Docker.

📸 Screenshots

Hauptansicht mit Timer und Monatsübersicht

Detaillierte Statistiken und Urlaubsverwaltung

Eintragsbearbeitung und Bulk-Operationen

Funktionen

⏱️ Zeiterfassung

• Live-Timer mit automatischen Pausen: Start/Stop-Timer erfasst die tägliche Arbeitszeit
  • Automatische Pausen nach 6h (30 Min) oder 9h (45 Min) gemäß deutschem Arbeitszeitgesetz
  • Rundung auf 15-Minuten-Intervalle
  • Timer persistiert über Seiten-Reloads
  • Manuelle Startzeit-Eingabe möglich
  • Visueller Indikator (blinkendes Uhr-Icon) bei laufendem Timer
• Flexible Eingabemodi:
  • Manuelle Eingabe (Datum, Start, Ende, Pause)
  • Inline-Bearbeitung direkt in der Tabelle
  • Schnelles Hinzufügen von Einträgen über Monatsansicht
• Arbeitsort-Tracking: Büro oder Home-Office pro Eintrag
• Sondereinträge:
  • Urlaubstage (werden nicht vom Saldo abgezogen)
  • Gleittage (ziehen 8h vom Saldo ab)

📊 Intelligente Berechnungen

• Automatische Pausenberechnung (deutsches Arbeitszeitgesetz)
• 10-Stunden-Cap für maximale Nettoarbeitszeit pro Tag
• Live-Statistiken mit laufendem Timer:
  • Soll-Stunden (basierend auf Arbeitstagen)
  • Ist-Stunden (inkl. aktuell laufender Timer)
  • Monatssaldo + Gesamtsaldo mit Vormonatsübertrag
  • Arbeitstage-Zählung
• Urlaubsverwaltung:
  • Konfigurierbares Jahres-Kontingent
  • Tracking: Genommen, Geplant, Verfügbar
  • Automatische Jahresberechnung

🗓️ Bundesland-spezifische Feiertage

• 16 Bundesländer mit korrekten regionalen Feiertagen
• Persistente Einstellung (gespeichert in Datenbank)
• Kollisionserkennung: Warnung bei Feiertagen mit bestehenden Einträgen
• Alle Feiertage: Bundeseinheitlich + regional (z.B. Fronleichnam, Reformationstag)

📅 Monatsansicht & Navigation

• Vollständiger Monatskalender mit allen Tagen
• Intuitive Farbcodierung:
  • 🟢 Grün: Home-Office
  • 🟡 Gelb: Urlaub
  • 🔵 Cyan: Gleittage
  • 🔴 Rot: Fehlende Arbeitstage
  • ⚫ Grau: Wochenenden
  • 🔵 Blau: Feiertage (mit Namen)
• Navigation: Vor/Zurück-Buttons zum Monatswechsel
• Auto-Fill: Automatisches Befüllen des Monats mit Standard-Arbeitszeiten (9:00-17:30)
• Quick-Actions: Plus-Buttons für schnelles Hinzufügen von Einträgen

⚡ Bulk-Operationen

• Mehrfachauswahl-Modus mit Checkboxen
• Bulk-Aktionen:
  • Standort setzen (Büro/Home)
  • Urlaub eintragen
  • Gleitzeit eintragen
  • Löschen
• Funktioniert in beiden Ansichten (Monatsansicht + Filteransicht)

🔍 Filter & Export

• Zeitraum-Filter: Von/Bis-Datum (bleibt bei Bulk-Aktionen erhalten)
• Getrennte Ansichten: Monatsnavigation wird bei Filter-Ansicht ausgeblendet
• CSV-Export (Alle): Alle Einträge im gewählten Zeitraum
  • Spalten: Datum, Start, Ende, Pause (Min), Netto (h), Arbeitsort, Abweichung (h)
• CSV-Export (Abweichungen): Nur Tage ≠ 8,0h
  • Ideal für Gleitzeit-Nachweise
• Deutsches Format: Semikolon-getrennt, Komma-Dezimal

🎨 Modernes UI/UX

• Premium Design: Glass-Morphism, Gradients, Schatten, Animationen
• Responsive: Desktop, Tablet, Mobile
• Dark Mode: Augenschonendes dunkles Design
• Toast-Benachrichtigungen: Visuelles Feedback
• Icons: Lucide Icons für klare Symbolik
• Flatpickr: Touch-optimierte Datums-/Zeit-Picker

🏗️ Technologie-Stack

Backend:

• Node.js 18+ mit Express.js
• SQLite (better-sqlite3) für dateibasierte Persistenz
• Modulare Architektur (config, utils, routes)

Frontend:

• Vanilla JavaScript (ES6+)
• Tailwind CSS (CDN)
• Lucide Icons
• Flatpickr (Datums-/Zeit-Picker)

Infrastructure:

• Docker & Docker Compose
• Multi-Stage Build für optimierte Images

📁 Projektstruktur

timetracker/
├── server.js                    # Express Entry Point
├── db/
│   ├── schema.sql              # Datenbankschema
│   └── timetracker.db          # SQLite Datenbank (generiert)
├── public/
│   ├── index.html              # Single-Page Application
│   └── app.js                  # Frontend-Logik (~2700 Zeilen)
├── media/screenshots/          # App-Screenshots
├── Dockerfile                  # Container-Image
├── docker-compose.yml          # Orchestrierung
└── package.json

⚙️ Deutsche Arbeitszeitregelungen

Die App implementiert deutsches Arbeitszeitgesetz (ArbZG):

• > 6h Arbeit → 30 Min Pause (automatisch)
• > 9h Arbeit → 45 Min Pause (automatisch)
• Maximale Nettoarbeitszeit: 10,0h pro Tag
• Rundung: Alle Zeiten auf 15-Minuten-Intervalle

🚀 Installation & Ausführung

🐳 Option 1: Docker Compose (Empfohlen)

Voraussetzungen: Docker & Docker Compose

# Repository klonen
git clone https://gitea.fx-se.de/maggot/timetracker.git
cd timetracker

# Starten
docker-compose up -d

# Logs
docker-compose logs -f

# Stoppen
docker-compose down

# Stoppen + Daten löschen
docker-compose down -v

App läuft auf: http://localhost:3000

🐋 Option 2: Docker (manuell)

# Image bauen
docker build -t zeiterfassung .

# Container starten (mit Daten-Persistenz)
docker run -p 3000:3000 -v $(pwd)/db:/app/db zeiterfassung

💻 Option 3: Lokal (ohne Docker)

Voraussetzungen: Node.js 18+

npm install
npm start

App läuft auf: http://localhost:3000

📤 CSV-Export

Die App bietet zwei Export-Modi über die Filter-Ansicht:

Export Alle (📥)

Exportiert alle Einträge im gewählten Zeitraum.

Spalten:

Datum;Start;Ende;Pause (min);Netto (h);Arbeitsort;Abweichung (h)

Beispiel:

2025-10-21;08:00;17:00;30;8,50;Büro;+0,50
2025-10-22;09:00;18:00;45;8,25;Home;+0,25
2025-10-23;08:30;16:30;30;7,50;Büro;-0,50

Export Abweichungen (⚠️)

Exportiert nur Tage mit ≠ 8,0 Stunden.

Zweck: Gleitzeit-Nachweise für HR (nur relevante Über-/Unterschreitungen)

Beispiel:

2025-10-21;08:00;18:30;45;9,75;Büro;+1,75
2025-10-23;09:00;15:30;30;6,00;Home;-2,00

(Tage mit exakt 8,0h fehlen)

Format: Semikolon-getrennt, Komma-Dezimal, YYYY-MM-DD Datum

📡 API-Endpunkte

Einträge

• GET /api/entries?from=YYYY-MM-DD&to=YYYY-MM-DD - Einträge abrufen
• POST /api/entries - Eintrag erstellen
• PUT /api/entries/:id - Eintrag aktualisieren
• DELETE /api/entries/:id - Eintrag löschen

Einstellungen

• GET /api/settings/:key - Setting abrufen
• POST /api/settings - Setting speichern {key, value}
• GET /api/settings - Alle Settings

🛠️ Entwicklung

Architektur: Single-Page Application (SPA) mit REST-API Backend

Tech-Details:

• Flatpickr für Touch-optimierte Picker
• Lucide Icons für Symbolik
• SQLite für dateibasierte Persistenz
• Server-seitige Berechnungen für Datenintegrität
• Responsive Design (Tailwind CSS via CDN)

Datenpersistenz:

• SQLite-Datenbank: db/timetracker.db
• Automatische Migrations beim Start
• Volume-Mounting in Docker für Persistenz

📄 Lizenz

MIT License - siehe LICENSE Datei

---

Entwickelt mit ❤️ für deutsches Arbeitszeitrecht