b0dd773fba
- Created 'entries' table to track time entries with fields for date, start time, end time, pause minutes, location, and entry type. - Created 'settings' table to store key-value pairs for application settings with an updated timestamp.
267 lines
8.9 KiB
Markdown
267 lines
8.9 KiB
Markdown
# Zeiterfassung
|
|
|
|
Eine Full-Stack-Zeiterfassungsanwendung, entwickelt mit Node.js, Express, SQLite und containerisiert mit Docker.
|
|
|
|
## Screenshots
|
|
|
|
|
|
*Hauptansicht mit Timer und Monatsübersicht*
|
|
|
|
|
|
*Detaillierte Statistiken und Urlaubsverwaltung*
|
|
|
|
|
|
*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
|