Skip to content

claude.md

Latest commit

 

History

History
381 lines (295 loc) · 11.6 KB

claude.md

File metadata and controls

381 lines (295 loc) · 11.6 KB

Dienstplan Bonusrechner - Projekt Übersicht

Projektbeschreibung

Dieses Projekt berechnet Bonuszahlungen für Mitarbeiter basierend auf Wochenend- und Feiertagsdiensten nach spezifischen NRW-Regeln. Es existieren drei verschiedene Implementierungen für unterschiedliche Anwendungsfälle.

Quick Start

Für schnellen Einstieg - Web-App (empfohlen):

  1. Öffne webapp/index.html im Browser
  2. Füge Mitarbeiter hinzu (Tab "Mitarbeiter")
  3. Trage Dienste ein (Tab "Dienste")
  4. Berechne Bonus (Tab "Berechnungen")

Für Python/Excel:

python -m venv .venv
.venv\Scripts\activate  # Windows
pip install -r requirements.txt
python src/fill_plan_dates.py 2025 12

Für Android: Siehe android-app/README.md für Build-Anleitung.

Verfügbare Implementierungen

1. Web-App (empfohlen)

Verzeichnis: webapp/ Technologie: Vanilla JavaScript, HTML5, CSS3 Verwendung: Browser-basiert, keine Installation erforderlich

Die Web-App ist die modernste und benutzerfreundlichste Version. Sie läuft komplett im Browser und speichert Daten lokal im LocalStorage.

2. Python/Excel Version

Verzeichnis: src/ Technologie: Python mit openpyxl Verwendung: Generiert Excel-Dateien mit Formeln

Die ursprüngliche Implementierung, die Excel-Arbeitsmappen mit eingebetteten Formeln erstellt.

3. Android App

Verzeichnis: android-app/ Technologie: Kotlin, Android SDK Verwendung: Native Android-Anwendung

Mobile Version für Android-Geräte.

Berechnungsregeln - Unterschiede

Web-App Logik (Benutzer-Anforderung)

Die Web-App implementiert eine vereinfachte Logik:

  1. Qualifizierende Tage (WE/Feiertag):

    • Freitag, Samstag, Sonntag
    • Feiertage in NRW
    • Tag vor einem Feiertag

  2. Bonusberechnung:

    • Mindestens 2.0 qualifizierende Tage erforderlich
    • Bei Erreichen: 2.0 qualifizierende Tage werden abgezogen
    • Alle übrigen Tage werden bezahlt:
      • Normale Tage (Mo-Do, kein Feiertag): 250€
      • Qualifizierende Tage: 450€
    • Unter Schwellenwert: Keine Bonuszahlung

Python/Android Logik (Variante 2 "streng")

Die ältere Implementierung nutzt eine andere Logik:

  1. Tag-Kategorien:

    • WT-Tag (Werktag): Mo-Do (ohne Feiertag/Vortag)
    • WE-Tag (Weekend): Fr-So + Feiertag + Vortag Feiertag

  2. Bonusberechnung:

    • WT-Tage werden bei Erreichen der Schwelle mit 250€ vergütet
    • WE-Tage nur vergütet wenn ≥ 2.0 WE-Einheiten:
      • Bei Erreichen: 450€ pro WE-Tag
      • Dann Abzug von 2.0 WE-Einheiten (Freitag-Priorität)
      • Unter Schwellenwert: Keine Bonuszahlung (weder WE noch WT)

Wichtiger Unterschied - Beispiel

Szenario: Mitarbeiter arbeitet 1 × Mo, 1 × Di, 1 × Sa

Web-App:

  • Qualifizierende Tage: 1.0 (nur Samstag)
  • Schwellenwert nicht erreicht → 0€ Bonus

Python/Android:

  • WT-Tage: 2.0 (Mo, Di) → 2 × 250€ = 500€
  • WE-Tage: 1.0 (Sa) → Schwelle nicht erreicht → 0€
  • Gesamt: 500€

Die Web-App ist strenger für Mitarbeiter ohne ausreichend WE-Dienste.

Dateistruktur

Dienstplan/
├── webapp/                          # Web-Anwendung (Browser)
│   ├── index.html                   # Haupt-UI
│   ├── styles.css                   # Styling (Gradient-Design)
│   ├── app.js                       # UI-Logik, Event-Handling
│   ├── calculator.js                # Bonusberechnungs-Engine
│   ├── holidays.js                  # NRW-Feiertage (2025-2030)
│   ├── storage.js                   # LocalStorage-Verwaltung
│   └── README.md                    # Web-App Dokumentation
│
├── src/                             # Python/Excel Version
│   ├── build_template.py            # Excel-Vorlage erstellen
│   ├── fill_plan_dates.py           # Monatspläne generieren
│   └── read_excel.py                # Excel-Dateien lesen
│
├── android-app/                     # Android App
│   ├── app/src/main/java/com/dienstplan/nrw/
│   │   ├── MainActivity.kt          # Haupt-Activity
│   │   ├── data/
│   │   │   ├── PayrollCalculator.kt # Bonusberechnung
│   │   │   ├── HolidayProvider.kt   # Feiertagsdaten
│   │   │   └── DutyDataStore.kt     # Datenverwaltung
│   │   └── model/                   # Datenmodelle
│   └── README.md                    # Android-Dokumentation
│
├── templates/                       # Excel-Vorlagen
├── output/                          # Generierte Excel-Dateien
├── README.md                        # Projekt-Hauptdokumentation
├── SPECIFICATION.md                 # Detaillierte Regelspezifikation
├── claude.md                        # Diese Datei
└── requirements.txt                 # Python-Abhängigkeiten

NRW Feiertage

Alle Implementierungen nutzen die gleichen NRW-Feiertage:

  • Neujahr (1. Januar)
  • Karfreitag (variabel)
  • Ostermontag (variabel)
  • Tag der Arbeit (1. Mai)
  • Christi Himmelfahrt (variabel)
  • Pfingstmontag (variabel)
  • Fronleichnam (variabel)
  • Tag der Deutschen Einheit (3. Oktober)
  • Allerheiligen (1. November)
  • Heiligabend (24. Dezember) - Python/Android 2025-2026
    1. Weihnachtstag (25. Dezember)
    1. Weihnachtstag (26. Dezember)
  • Silvester (31. Dezember) - Python/Android 2025-2026

Abdeckung: 2025-2030 (Web-App), 2025-2026 (Python/Android)

Hinweis: Heiligabend und Silvester wurden kürzlich zur Python/Android-Version hinzugefügt, sind aber noch nicht in der Web-App implementiert.

Letzte Änderungen & Verbesserungen

Dezember 2025

  • ✅ Export-Verbesserung: Abgezogene Tage werden in der Export-Ansicht speziell markiert
  • ✅ UI-Verbesserung: Euro-Werte werden für abgezogene Tage ausgeblendet (klarere Darstellung)
  • ✅ Neue Feiertage: Heiligabend (24.12.) und Silvester (31.12.) für Python/Android-Version
  • ✅ Bugfix: Entfernung ungenutzter isPartiallyDeducted-Variable
  • ✅ Korrektur: Alle Abzugsreferenzen auf 2.0 (statt 1.0) aktualisiert

Bekannte Unterschiede zwischen Versionen

  • Web-App: Hat Heiligabend/Silvester noch nicht als Feiertage
  • Python/Android: Vollständige Feiertage-Liste inklusive Heiligabend/Silvester
  • Berechnungslogik: Web-App nutzt vereinfachte Logik (siehe "Berechnungsregeln - Unterschiede")

Entwicklungshinweise

Web-App erweitern

Neue Feiertage hinzufügen (webapp/holidays.js):

2031: [
    { date: '2031-01-01', name: 'Neujahr' },
    // ... weitere Feiertage
]

Berechnungsraten ändern (webapp/calculator.js):

this.RATE_NORMAL = 250;          // Normale Tage
this.RATE_WEEKEND = 450;         // WE/Feiertag Tage
this.MIN_QUALIFYING_DAYS = 2.0;  // Schwellenwert

Python Version erweitern

Neue Monate generieren:

python src/fill_plan_dates.py 2025 11  # November 2025

Android App

Build & Install:

cd android-app
./gradlew assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk

Testing-Szenarien

Testfall 1: Schwellenwert genau erreicht

  • 1 × Freitag (1.0)
  • 1 × Samstag (1.0)
  • Erwartung: 2.0 qualifizierende Tage → 2.0 abgezogen → 0.0 × 450€ = 0€

Testfall 2: Schwellenwert nicht erreicht

  • 1 × Samstag (1.0)
  • 1 × Sonntag (0.5 - halber Dienst)
  • Erwartung: 1.5 qualifizierende Tage → 0€ (Schwelle nicht erreicht)

Testfall 3: Mit normalen Tagen

  • 2 × Montag (2.0)
  • 2 × Samstag (2.0)
  • Erwartung:
    • 2.0 qualifizierende → -2.0 Abzug → 0.0 bezahlt
    • Bonus: (2 × 250€) + (0 × 450€) = 500€

Testfall 4: Feiertag + Vortag

  • 1 × Donnerstag vor Karfreitag (qualifizierend!)
  • 1 × Karfreitag (Feiertag, qualifizierend!)
  • Erwartung: 2.0 qualifizierende → -2.0 → 0.0 × 450€ = 0€

Häufige Anpassungen

Schwellenwert ändern (Web-App)

webapp/calculator.js, Zeile 10:

this.MIN_QUALIFYING_DAYS = 3.0;  // Statt 2.0

Vergütungsraten ändern (Web-App)

webapp/calculator.js, Zeilen 8-9:

this.RATE_NORMAL = 300;   // Statt 250
this.RATE_WEEKEND = 500;  // Statt 450

Abzug ändern (Web-App)

Der Abzug ist als Konstante in webapp/calculator.js definiert:

this.DEDUCTION_AMOUNT = 2.0;  // Im Constructor

Um den Abzugswert zu ändern, einfach diesen Wert anpassen.

Code-Architektur

Web-App (MVC-ähnlich)

Model (storage.js):

  • Datenverwaltung
  • LocalStorage-Persistenz
  • CRUD-Operationen für Mitarbeiter & Dienste

Controller (app.js):

  • Event-Handling
  • Koordination zwischen Model, View, Calculator
  • UI-State-Management

Business Logic (calculator.js):

  • Bonusberechnung
  • Tag-Klassifizierung (qualifizierend/normal)
  • Formatierung

Data Provider (holidays.js):

  • Feiertagsdaten
  • Datum-Utilities

View (index.html + styles.css):

  • UI-Layout (Tabs)
  • Styling
  • Responsives Design

Datenfluss (Web-App)

User Action (UI)
    ↓
Event Handler (app.js)
    ↓
Storage Operation (storage.js) ←→ LocalStorage
    ↓
Data Retrieved
    ↓
Calculator Processing (calculator.js) → Holiday Check (holidays.js)
    ↓
Results
    ↓
UI Update (app.js)
    ↓
View Rendering (HTML)

Browser-Kompatibilität (Web-App)

  • Chrome/Edge: ✅ Vollständig unterstützt
  • Firefox: ✅ Vollständig unterstützt
  • Safari: ✅ Vollständig unterstützt
  • Opera: ✅ Vollständig unterstützt

Mindestanforderungen:

  • LocalStorage API
  • ES6 JavaScript (Arrow Functions, Classes, Template Literals)
  • CSS Grid & Flexbox
  • Date API

Deployment-Optionen (Web-App)

Option 1: Lokale Datei

Einfach index.html im Browser öffnen - funktioniert sofort!

Option 2: Statischer Webserver

# Python
python -m http.server 8000

# Node.js
npx http-server -p 8000

# PHP
php -S localhost:8000

Option 3: Cloud-Hosting

Geeignet für Plattformen wie:

  • GitHub Pages: Kostenlos, einfach via Git
  • Netlify: Drag & Drop, kostenloser Plan
  • Vercel: Automatisches Deployment
  • AWS S3: Static Website Hosting

Da die App rein client-seitig läuft (keine Server-Logik), ist jeder Static-Hosting-Service geeignet.

Sicherheitshinweise

LocalStorage-Daten

  • Daten sind nicht verschlüsselt
  • Für produktive Nutzung mit sensiblen Daten ggf. Verschlüsselung hinzufügen
  • Regelmäßige Backups via Export-Funktion empfohlen

CORS (bei Web-Hosting)

  • LocalStorage funktioniert nur auf gleicher Domain
  • Beim Testen via file:// können CORS-Einschränkungen auftreten
  • Lösung: Lokaler Webserver (siehe Deployment-Optionen)

Lizenz

MIT License - Siehe Hauptprojekt

Export-Funktion (Web-App)

Die Web-App bietet eine Export-Funktion für Mitarbeiterdaten:

Features

  • Export-Format: JSON-Datei mit allen Mitarbeiter- und Dienstdaten
  • Import-Funktion: Wiederherstellen gespeicherter Daten
  • Verbesserte Darstellung (v3.1):
    • Abgezogene Tage werden speziell markiert
    • Euro-Werte werden für abgezogene Tage ausgeblendet
    • Klarere Unterscheidung zwischen bezahlten und abgezogenen Diensten

Verwendung

  1. Im Tab "Mitarbeiter" auf "Export" klicken
  2. JSON-Datei wird heruntergeladen
  3. Zum Importieren: "Import" klicken und Datei auswählen

Tipp: Regelmäßige Exports als Backup nutzen, da LocalStorage browser-abhängig ist.

Versionshistorie

  • v3.1 (Dezember 2025): Verbesserte Export-Darstellung, Heiligabend/Silvester für Python/Android
  • v3.0 (2025): Web-App hinzugefügt mit vereinfachter Berechnungslogik
  • v2.0 (2024): Android-App implementiert
  • v1.0: Python/Excel Version (Variante 2 "streng")

Kontakt & Support

Für Fragen zum Projekt siehe README.md der jeweiligen Implementierung.