# 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
  - **Timer-Metriken** bei laufendem Timer:
    - Läuft seit: Startzeit mit Icon-Styling
    - Soll erreicht: Uhrzeit wann Tagesziel erreicht wird (inkl. Pausen)
    - Zeit bis Soll: Live-Countdown zur Zielzeit
    - Saldo bei Soll: Prognostizierter Gesamtsaldo nach Erreichen der geplanten Zeit
  - **Anpassbare Arbeitszeit**: Dropdown 4h-10h für flexible Arbeitstage
    - Einstellung bleibt über Reloads erhalten (nur während Timer läuft)
    - Wird bei Timer-Stop auf 8h zurückgesetzt
- **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 mit Einträgen)
  - Ist-Stunden (inkl. aktuell laufender Timer)
  - Monatssaldo + Gesamtsaldo mit Vormonatsübertrag
  - Arbeitstage-Zählung
  - **Intelligente Soll-Berechnung**: Berücksichtigt nur Tage mit Einträgen oder laufendem Timer
- **Laufendes Saldo** in Monatsansicht:
  - Spalte "Saldo" zeigt kumulatives Saldo bis zu jedem Tag
  - Live-Updates während Timer läuft
  - Farbcodierung: Grün (positiv) / Rot (negativ)
  - Berücksichtigt Flextime-Tage korrekt (-8h)
- **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)
- **Betriebsfreie Tage**: Wählbar zwischen Heiligabend (24.12.) oder Silvester (31.12.)
  - Toggle in Einstellungen
  - Wird als "Betriebsfrei" markiert
  - Verhindert doppelte Einträge an diesen Tagen
- **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)
  - 💙 Blauer Rand: Heutiger Tag
- **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
- **PDF-Export**: 
  - **Monats-Export**: Nur verfügbar wenn letzter Tag des Monats vollständig erfasst ist
    - Verhindert versehentliche Exports unvollständiger Monate
    - Button wird automatisch angezeigt sobald Bedingung erfüllt
  - **Bulk-Export**: Exportiert ausgewählte Einträge (im Bulk-Modus)
  - Professionelles Layout mit Mitarbeiter-Info und Statistiken
  - Automatische Tabelle mit allen Einträgen
  - Deutsche Formatierung (Datum, Währung, Dezimalstellen)
- **Deutsches Format**: Semikolon-getrennt (CSV), Komma-Dezimal

### 💾 Datenbank-Management
- **Datenbank-Export**: Vollständiger Export aller Daten als JSON
  - Enthält alle Einträge und Einstellungen
  - Versioniert für Kompatibilität
  - Zeitstempel im Dateinamen
- **Datenbank-Import**: Wiederherstellen aus JSON-Backup
  - Validierung der Datenstruktur
  - Bestätigungs-Dialog vor Überschreiben
  - Löscht alte Daten vor Import
  - Importiert Einträge und Einstellungen
- **Instanz-Migration**: Einfaches Wechseln zwischen Servern/Instanzen

### 🎨 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)
- jsPDF mit autoTable Plugin (PDF-Generierung)

**Infrastructure:**
- Docker & Docker Compose
- Multi-Stage Build für optimierte Images
- Gitea Actions CI/CD für automatische Builds
- Gitea Container Registry für Image-Hosting

## 📁 Projektstruktur

```
timetracker/
├── server.js                    # Express Entry Point
├── db/
│   ├── schema.sql              # Datenbankschema
│   └── timetracker.db          # SQLite Datenbank (generiert)
├── public/
│   ├── index.html              # Single-Page Application
│   ├── favicon.svg             # App Icon
│   └── js/
│       ├── state.js            # Globaler State
│       ├── utils.js            # Hilfsfunktionen
│       ├── holidays.js         # Feiertagsberechnung
│       ├── api.js              # Backend-Kommunikation
│       └── main.js             # Hauptlogik (~3700 Zeilen)
├── .gitea/workflows/           # CI/CD Workflows
│   └── docker-build.yml        # Docker Build & Push
├── 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: Vorgefertigtes Docker Image (Empfohlen)

**Voraussetzungen:** Docker (& Docker Compose optional)

```bash
# Image pullen (public registry, kein Login nötig)
docker pull gitea.fx-se.de/maggot/timetracker:latest

# Container starten
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/db:/app/db \
  --name timetracker \
  gitea.fx-se.de/maggot/timetracker:latest
```

**Oder mit docker-compose.yml:**
```yaml
version: '3.8'
services:
  app:
    image: gitea.fx-se.de/maggot/timetracker:latest
    ports:
      - "3000:3000"
    volumes:
      - ./db:/app/db
    restart: unless-stopped
```

```bash
# 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 bauen)

```bash
# Repository klonen
git clone https://gitea.fx-se.de/maggot/timetracker.git
cd timetracker

# 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
# Repository klonen
git clone https://gitea.fx-se.de/maggot/timetracker.git
cd timetracker

npm install
npm start
```

**App läuft auf:** `http://localhost:3000`

## 📤 Export-Funktionen

Die App bietet mehrere Export-Modi für verschiedene Anwendungsfälle:

### PDF-Export 📄

**Monats-Export:**
- Klicke auf "PDF Export" in der Monatsansicht
- Exportiert alle Einträge des aktuellen Monats
- Professionelles Layout mit:
  - Mitarbeiter-Informationen (Name, Personal-Nr.)
  - Monatsstatistiken (Soll/Ist/Saldo)
  - Vollständige Tabelle aller Einträge
  - Deutsche Formatierung

**Bulk-Export:**
- Aktiviere Bulk-Modus und wähle Einträge aus
- Klicke auf "PDF exportieren"
- Exportiert nur ausgewählte Einträge
- Gleiche Formatierung wie Monats-Export

### CSV-Export 📊

Die App bietet zwei CSV-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

### Datenbank-Backup 💾

**Export:**
1. Gehe zu Einstellungen
2. Klicke auf "Datenbank exportieren"
3. JSON-Datei mit Zeitstempel wird heruntergeladen
4. Enthält: Alle Einträge + Einstellungen + Version

**Import:**
1. Gehe zu Einstellungen
2. Klicke auf "Datenbank importieren"
3. Wähle JSON-Backup-Datei
4. Bestätige Überschreiben der Daten
5. Alte Daten werden gelöscht, neue importiert

**Verwendung:**
- Regelmäßige Backups vor Updates
- Migration zwischen Instanzen/Servern
- Datensicherung

## 📡 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

### Datenbank-Management
- `GET /api/database/export` - Vollständigen DB-Export als JSON
- `POST /api/database/import` - DB-Import aus JSON
- `DELETE /api/entries/all` - Alle Einträge löschen (für Import)

## 🔄 CI/CD & Deployment

Die App verwendet Gitea Actions für automatische Builds und Deployments:

**Automatische Docker Builds:**
- Bei Push zu `main`/`master` Branch
- Nur bei relevanten Änderungen (Server, Frontend, Dependencies)
- Ignoriert README, Workflow-Änderungen
- Erstellt Images mit Tags: `latest` + Commit-SHA

**Container Registry:**
- Gehostet auf Gitea: `gitea.fx-se.de/maggot/timetracker`
- Authentifizierung via Personal Access Token
- Automatischer Push nach erfolgreichem Build

**Workflow-Konfiguration:**
```yaml
# Triggert nur bei:
- server.js, package.json, Dockerfile
- db/**, public/**
- Ignoriert: *.md, .gitea/workflows/**, .gitignore
```

**Siehe:** `.gitea/workflows/docker-build.yml` für Details

## 🛠️ Entwicklung

**Architektur:** Single-Page Application (SPA) mit REST-API Backend

**Tech-Details:**
- Modulare Frontend-Architektur (5 separate JS-Dateien)
- Flatpickr für Touch-optimierte Picker (auch in Tabellen-Inline-Edit)
- Lucide Icons für Symbolik
- jsPDF + autoTable für PDF-Generierung
- 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
- JSON-basierte Backups für Migration

**Code-Organisation:**
- `state.js`: Globaler Application State
- `utils.js`: Hilfsfunktionen (Datum, Zeit, Format)
- `holidays.js`: Feiertagsberechnung (16 Bundesländer)
- `api.js`: Backend-Kommunikation
- `main.js`: Hauptlogik, UI, Event-Handler

## 📄 Lizenz

MIT License - siehe LICENSE Datei

---

**Entwickelt mit ❤️ für deutsches Arbeitszeitrecht**