# Zeiterfassung

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

<details>
<summary><b>📸 Screenshots</b></summary>

![Screenshot 1](media/screenshots/Screenshot1.png)
*Hauptansicht mit Timer und Monatsübersicht*

![Screenshot 2](media/screenshots/Screenshot2.png)
*Detaillierte Statistiken und Urlaubsverwaltung*

![Screenshot 3](media/screenshots/Screenshot3.png)
*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**