Zeiterfassung

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

Funktionen

• ✅ Erfassung von Arbeitszeiten (Datum, Startzeit, Endzeit)
• ✅ Automatische Pausenberechnung nach deutschem Arbeitszeitgesetz
• ✅ Maximum von 10 Stunden Nettoarbeitszeit
• ✅ Filterung nach Zeitraum
• ✅ CSV-Export mit deutscher Formatierung
• ✅ Responsive Benutzeroberfläche mit Tailwind CSS
• ✅ Moderner Datums-/Zeitauswahl (Flatpickr)
• ✅ Docker-Containerisierung

Technologie-Stack

• Backend: Node.js, Express.js (modular aufgebaut)
  • Config: Datenbank-Setup & Migrationen
  • Utils: Zeitberechnungen nach deutschem Arbeitszeitgesetz
  • Routes: Separate Module für API-Endpunkte
• Datenbank: SQLite (better-sqlite3)
• Frontend: Vanilla JavaScript, HTML, Tailwind CSS
• Containerisierung: Docker, Docker Compose

Projektstruktur

/timetracker
  ├── src/                 # Backend-Code (refactored)
  │   ├── config/
  │   │   └── database.js      # Datenbank-Initialisierung & Migrationen
  │   ├── utils/
  │   │   └── timeCalculator.js # Zeitberechnungen (Pausen, Caps)
  │   └── routes/
  │       ├── entries.js       # CRUD API-Endpunkte
  │       └── export.js        # CSV-Export
  ├── public/              # Frontend
  │   ├── index.html       # Hauptbenutzeroberfläche
  │   ├── app.js           # Frontend-Logik
  │   └── js/              # Frontend-Module (optional)
  │       ├── state.js         # State Management
  │       ├── utils/           # Utilities
  │       ├── api/             # API-Client
  │       └── ui/              # UI-Komponenten
  ├── db/
  │   └── schema.sql       # Datenbankschema
  ├── server.js            # Express-Server (22 Zeilen - Entry Point)
  ├── Dockerfile           # Multi-Stage Docker Build
  ├── docker-compose.yml   # Docker Compose Konfiguration
  ├── package.json
  └── README.md

Deutsche Pausenregelung

Die Anwendung berechnet automatisch die Pausenzeiten gemäß deutschem Arbeitszeitgesetz:

• > 6 Stunden Arbeitszeit: 30 Minuten Pause werden abgezogen
• > 9 Stunden Arbeitszeit: 45 Minuten Pause werden abgezogen
• Nettostunden sind auf maximal 10,0 Stunden begrenzt

API-Endpunkte

• GET /api/entries?from=YYYY-MM-DD&to=YYYY-MM-DD - Alle Einträge im Zeitraum abrufen
• POST /api/entries - Neuen Eintrag erstellen
• PUT /api/entries/:id - Bestehenden Eintrag aktualisieren
• DELETE /api/entries/:id - Eintrag löschen
• GET /api/export?from=YYYY-MM-DD&to=YYYY-MM-DD - Einträge als CSV exportieren

Installation & Ausführung

Repository klonen

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

Option 1: Mit Docker Compose (Empfohlen)

Voraussetzungen:

• Docker und Docker Compose installiert

Starten:

docker-compose up -d

Logs ansehen:

docker-compose logs -f

Stoppen:

docker-compose down

Stoppen und Daten löschen:

docker-compose down -v

Die Anwendung läuft auf:

http://localhost:3000

Option 2: Mit Docker (manuell)

Docker-Image erstellen:

docker build -t zeiterfassung .

Container starten:

docker run -p 3000:3000 -v $(pwd)/db:/app/db zeiterfassung

Das -v Flag bindet das Datenbankverzeichnis ein, um Daten zwischen Container-Neustarts zu erhalten.

Option 3: Lokale Ausführung (ohne Docker)

Voraussetzungen:

• Node.js 18+ installiert

Installation:

1. Abhängigkeiten installieren:

npm install

2. Server starten:

npm start

3. Browser öffnen und navigieren zu:

http://localhost:3000

CSV-Export-Format

Die exportierte CSV-Datei enthält folgende Spalten:

• Datum: Datum im Format TT.MM.JJJJ
• Startzeit: Startzeit im Format HH:MM
• Endzeit: Endzeit im Format HH:MM
• Pause in Minuten: Pausenzeit in Minuten
• Gesamtstunden: Nettostunden mit Komma als Dezimaltrennzeichen (z.B. 8,50)

Entwicklung

Die Anwendung verwendet:

• Flatpickr für die Datums- und Zeitauswahl mit mobilfreundlichen Oberflächen
• Tailwind CSS für das Styling (geladen über CDN)
• SQLite für leichtgewichtige, dateibasierte Datenpersistenz
• Modulare Backend-Architektur für bessere Wartbarkeit und Testbarkeit
• Alle Berechnungen werden serverseitig durchgeführt, um die Datenintegrität zu gewährleisten

Code-Struktur

Backend:

• server.js - Express-Setup und Routing (22 Zeilen)
• src/config/database.js - Datenbank-Initialisierung
• src/utils/timeCalculator.js - Geschäftslogik für Zeitberechnungen
• src/routes/entries.js - CRUD-Endpunkte
• src/routes/export.js - CSV-Export

Frontend:

• public/app.js - Haupt-Frontend-Logik
• public/js/ - Optionale Module (state, utils, api, ui)

Lizenz

MIT