179 lines
4.9 KiB
Markdown
179 lines
4.9 KiB
Markdown
# Zeiterfassung
|
|
|
|
Eine Full-Stack-Zeiterfassungsanwendung, entwickelt mit Node.js, Express, SQLite und containerisiert mit Docker.
|
|
|
|
## Funktionen
|
|
|
|
- ✅ Erfassung von Arbeitszeiten (Datum, Startzeit, Endzeit)
|
|
- ✅ Automatische Pausenberechnung nach deutschem Arbeitszeitgesetz
|
|
- ✅ Maximum von 10 Stunden Nettoarbeitszeit
|
|
- ✅ Filterung nach Zeitraum
|
|
- ✅ CSV-Export mit deutscher Formatierung
|
|
- ✅ Responsive Benutzeroberfläche mit Tailwind CSS
|
|
- ✅ Moderner Datums-/Zeitauswahl (Flatpickr)
|
|
- ✅ Docker-Containerisierung
|
|
|
|
## 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
|
|
|
|
- `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
|
|
- `GET /api/export?from=YYYY-MM-DD&to=YYYY-MM-DD` - Einträge als CSV exportieren
|
|
|
|
## 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 exportierte CSV-Datei enthält folgende Spalten:
|
|
- **Datum**: Datum im Format TT.MM.JJJJ
|
|
- **Startzeit**: Startzeit im Format HH:MM
|
|
- **Endzeit**: Endzeit im Format HH:MM
|
|
- **Pause in Minuten**: Pausenzeit in Minuten
|
|
- **Gesamtstunden**: Nettostunden mit Komma als Dezimaltrennzeichen (z.B. 8,50)
|
|
|
|
## 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
|