254 lines
7.3 KiB
Markdown
254 lines
7.3 KiB
Markdown
# Zeiterfassung
|
|
|
|
Eine Full-Stack-Zeiterfassungsanwendung, entwickelt mit Node.js, Express, SQLite und containerisiert mit Docker.
|
|
|
|
<details>
|
|
<summary><b>📸 Screenshots</b></summary>
|
|
|
|
|
|
*Hauptansicht mit Timer und Monatsübersicht*
|
|
|
|
|
|
*Detaillierte Statistiken und Urlaubsverwaltung*
|
|
|
|
|
|
*Eintragsbearbeitung und Bulk-Operationen*
|
|
|
|
</details>
|
|
|
|
## 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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+
|
|
|
|
```bash
|
|
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:**
|
|
```csv
|
|
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:**
|
|
```csv
|
|
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**
|