From bd8131f18e1040404eda16e860f0413197435955 Mon Sep 17 00:00:00 2001
From: Felix Schlusche <fschlusche@liva-pms.com>
Date: Thu, 23 Oct 2025 14:32:33 +0200
Subject: [PATCH] Refactor README.md for improved structure and clarity; add
 collapsible sections for screenshots and features

---
 README.md | 369 ++++++++++++++++++++++++++----------------------------
 1 file changed, 178 insertions(+), 191 deletions(-)

diff --git a/README.md b/README.md
index a4587f6..fac3eff 100644
--- a/README.md
+++ b/README.md
@@ -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**