maggot/timetracker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor README.md for improved structure and clarity; add collapsible sections for screenshots and features

Browse Source
This commit is contained in:
Felix Schlusche
2025-10-23 14:32:33 +02:00
parent b0dd773fba
commit bd8131f18e
1 changed files with 178 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

369
README.md
View File

@@ -2,7 +2,8 @@
Eine Full-Stack-Zeiterfassungsanwendung, entwickelt mit Node.js, Express, SQLite und containerisiert mit Docker.
## Screenshots
<details>
<summary><b>📸 Screenshots</b></summary>
![Screenshot 1](media/screenshots/Screenshot1.png)
*Hauptansicht mit Timer und Monatsübersicht*
@@ -13,254 +14,240 @@ Eine Full-Stack-Zeiterfassungsanwendung, entwickelt mit Node.js, Express, SQLite
![Screenshot 3](media/screenshots/Screenshot3.png)
*Eintragsbearbeitung und Bulk-Operationen*
</details>
## Funktionen
### Zeiterfassung
- ✅ **Start/Stop Timer**: Live-Timer mit automatischer Zeiterfassung für den aktuellen Tag
- Pause nach 6 Stunden (30 Min) oder 9 Stunden (45 Min) gemäß deutschem Arbeitszeitgesetz
- Automatische Rundung auf 15-Minuten-Intervalle
- Timer läuft auch nach Seiten-Reload weiter
- ✅ **Manuelle Eingabe**: Erfassung von Arbeitszeiten (Datum, Startzeit, Endzeit, Pause)
- ✅ **Inline-Bearbeitung**: Schnelle Änderung von Zeiten durch Klick in die Tabelle
- ✅ **Standort-Tracking**: Home-Office oder Büro pro Eintrag
- ✅ **Urlaub eintragen**: Urlaubstage werden nicht vom Saldo abgezogen
- ✅ **Gleittage eintragen**: Gleittage ziehen 8 Stunden vom Saldo ab
### ⏱️ 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** nach deutschem Arbeitszeitgesetz:
- \> 6 Stunden: 30 Minuten Pause
- \> 9 Stunden: 45 Minuten Pause
- ✅ **Maximum von 10 Stunden Nettoarbeitszeit** pro Tag
- ✅ **Monatliche Statistiken**: Soll-Stunden, Ist-Stunden, Saldo (Monat + Gesamt)
- ✅ **Arbeitstage-Berechnung**: Automatische Erkennung von Wochenenden und Feiertagen
### 📊 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**: Auswahl des Bundeslandes für korrekte Feiertagsberechnung
- ✅ **Persistente Einstellung**: Bundesland-Auswahl wird gespeichert
- ✅ **Kollisionserkennung**: Warnung bei Feiertagen, die mit bestehenden Einträgen kollidieren
- ✅ **Alle regionalen Feiertage**: Heilige Drei Könige, Fronleichnam, Reformationstag, etc.
### 🗓️ 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
- ✅ **Monatskalender**: Vollständige Ansicht aller Tage des Monats
- ✅ **Farbcodierung**:
- Grün: Home-Office Tage
- Gelb: Urlaub
- Cyan: Gleittage
- Rot: Fehlende Einträge an Arbeitstagen
- Grau: Wochenenden
- Blau: Feiertage mit Namen
- ✅ **Vor/Zurück Navigation**: Einfaches Wechseln zwischen Monaten
- ✅ **Auto-Fill Funktion**: Automatisches Ausfüllen des gesamten Monats mit Standard-Arbeitszeiten
### 📅 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**: Checkbox-Modus für schnelle Massenbearbeitung
- ✅ **Bulk-Standort setzen**: Mehrere Einträge auf einmal auf Home/Büro setzen
- ✅ **Bulk-Löschen**: Mehrere Einträge auf einmal löschen
### ⚡ 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**: Filterung nach Datum (Von/Bis)
- ✅ **CSV-Export (Alle)**: Export aller Einträge im gewählten Zeitraum
- ✅ **CSV-Export (Abweichungen)**: Export nur der Tage mit Abweichungen von 8,0 Stunden
- Ideal für Arbeitszeitnachweise bei Gleitzeit
- Zeigt nur relevante Über-/Unterschreitungen
- ✅ **Deutsches Format**: Komma als Dezimaltrennzeichen, DD.MM.YYYY Datumsformat
### 🔍 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
### Benutzerfreundlichkeit
- ✅ **Responsive Design**: Optimiert für Desktop, Tablet und Smartphone
- ✅ **Dark Mode**: Modernes dunkles Design für augenschonende Arbeit
- ✅ **Toast-Benachrichtigungen**: Visuelles Feedback bei Aktionen
- ✅ **Flatpickr**: Moderne Datums- und Zeitauswahl mit Touch-Support
- ✅ **Persistente Daten**: SQLite-Datenbank mit automatischer Migration
### 🎨 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
## 🏗️ 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
**Backend:**
- Node.js 18+ mit Express.js
- SQLite (better-sqlite3) für dateibasierte Persistenz
- Modulare Architektur (config, utils, routes)
## Projektstruktur
**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
├── 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
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 Pausenregelung
## ⚙️ Deutsche Arbeitszeitregelungen
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**
Die App implementiert deutsches Arbeitszeitgesetz (ArbZG):
## API-Endpunkte
- **> 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
### Zeiteinträge
- `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
## 🚀 Installation & Ausführung
### Export
- `GET /api/export?from=YYYY-MM-DD&to=YYYY-MM-DD` - Alle Einträge als CSV exportieren
- `GET /api/export-deviations?from=YYYY-MM-DD&to=YYYY-MM-DD` - Nur Abweichungen als CSV exportieren
### 🐳 Option 1: Docker Compose (Empfohlen)
### Einstellungen
- `GET /api/settings/:key` - Einstellung abrufen
- `POST /api/settings` - Einstellung speichern (key, value)
- `GET /api/settings` - Alle Einstellungen abrufen
## Installation & Ausführung
### Repository klonen
**Voraussetzungen:** Docker & Docker Compose
```bash
# 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:**
```bash
# Starten
docker-compose up -d
```
**Logs ansehen:**
```bash
# Logs
docker-compose logs -f
```
**Stoppen:**
```bash
# Stoppen
docker-compose down
```
**Stoppen und Daten löschen:**
```bash
# Stoppen + Daten löschen
docker-compose down -v
```
Die Anwendung läuft auf:
```
http://localhost:3000
```
**App läuft auf:** `http://localhost:3000`
### Option 2: Mit Docker (manuell)
### 🐋 Option 2: Docker (manuell)
**Docker-Image erstellen:**
```bash
# Image bauen
docker build -t zeiterfassung .
```
**Container starten:**
```bash
# Container starten (mit Daten-Persistenz)
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: Lokal (ohne Docker)
### Option 3: Lokale Ausführung (ohne Docker)
**Voraussetzungen:** Node.js 18+
**Voraussetzungen:**
- Node.js 18+ installiert
**Installation:**
1. Abhängigkeiten installieren:
```bash
npm install
```
2. Server starten:
```bash
npm start
```
3. Browser öffnen und navigieren zu:
**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:**
```
http://localhost:3000
Datum;Start;Ende;Pause (min);Netto (h);Arbeitsort;Abweichung (h)
```
## CSV-Export-Format
Die Anwendung bietet zwei Export-Optionen:
### 1. Vollständiger Export (📥 Button)
Exportiert alle Einträge im gewählten Zeitraum (oder alle, wenn kein Filter gesetzt).
### 2. Export nur Abweichungen (⚠️ Button)
Exportiert **nur** Tage, die von der Standard-Arbeitszeit (8,0 Stunden) abweichen.
- **Zweck**: Ideal für Arbeitszeitnachweise bei Gleitzeit-Modellen
- **Inhalt**: Nur Über- und Unterschreitungen der 8-Stunden-Marke
- **Vorteil**: Übersichtlicher Nachweis für HR/Verwaltung ohne irrelevante Standard-Tage
### CSV-Spalten:
- **Datum**: TT.MM.JJJJ (z.B. 23.10.2025)
- **Typ**: Arbeit / Urlaub / Gleitzeit
- **Startzeit**: HH:MM (z.B. 08:00, bei Urlaub/Gleitzeit: -)
- **Endzeit**: HH:MM (z.B. 17:00, bei Urlaub/Gleitzeit: -)
- **Pause in Minuten**: Ganzzahl (z.B. 30)
- **Gesamtstunden**: Nettostunden mit Komma als Dezimaltrennzeichen (z.B. 8,50)
**Beispiel Abweichungs-Export:**
**Beispiel:**
```csv
Datum,Startzeit,Endzeit,Pause in Minuten,Gesamtstunden
21.10.2025,08:00,18:30,45,9,75
22.10.2025,09:00,15:30,30,6,00
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
```
(Tage mit exakt 8,0h werden nicht exportiert)
## Entwicklung
### Export Abweichungen (⚠️)
Exportiert **nur** Tage mit ≠ 8,0 Stunden.
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
**Zweck:** Gleitzeit-Nachweise für HR (nur relevante Über-/Unterschreitungen)
### Code-Struktur
**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)*
**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
**Format:** Semikolon-getrennt, Komma-Dezimal, YYYY-MM-DD Datum
**Frontend:**
- `public/app.js` - Haupt-Frontend-Logik
- `public/js/` - Optionale Module (state, utils, api, ui)
## 📡 API-Endpunkte
## Lizenz
### 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
MIT
### 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**