maggot/timetracker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1cc8dc3b6c1dcec8762b381a49047a21156293cc
timetracker/README.md

7.3 KiB
Raw Blame History

Zeiterfassung

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

📸 Screenshots

Screenshot 1 Hauptansicht mit Timer und Monatsübersicht

Screenshot 2 Detaillierte Statistiken und Urlaubsverwaltung

Screenshot 3 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

Reference in New Issue View Git Blame Copy Permalink