# Zeiterfassung

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

## Screenshots

![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*

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

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

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

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

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

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

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

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

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

## Deutsche Pausenregelung

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**

## API-Endpunkte

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

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

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

```bash
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
docker-compose up -d
```

**Logs ansehen:**
```bash
docker-compose logs -f
```

**Stoppen:**
```bash
docker-compose down
```

**Stoppen und Daten löschen:**
```bash
docker-compose down -v
```

Die Anwendung läuft auf:
```
http://localhost:3000
```

### Option 2: Mit Docker (manuell)

**Docker-Image erstellen:**
```bash
docker build -t zeiterfassung .
```

**Container starten:**
```bash
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: Lokale Ausführung (ohne Docker)

**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:
```
http://localhost:3000
```

## 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:**
```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
```
(Tage mit exakt 8,0h werden nicht exportiert)

## Entwicklung

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

### Code-Struktur

**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

**Frontend:**
- `public/app.js` - Haupt-Frontend-Logik
- `public/js/` - Optionale Module (state, utils, api, ui)

## Lizenz

MIT