Add comprehensive project documentation (claude.md)
Provides detailed overview of the entire Dienstplan project including: - All three implementations (Web-App, Python/Excel, Android) - Calculation logic differences between versions - Complete file structure documentation - Development guidelines and testing scenarios - Code architecture explanation - Deployment options and security notes This document serves as a comprehensive guide for understanding and maintaining the project.
This commit is contained in:
Claude
parent
520e3b62e0
commit
8c436c4aa9
1 changed files with 329 additions and 0 deletions
329
claude.md
Normal file
329
claude.md
Normal file
|
|
@ -0,0 +1,329 @@
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
## 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: **1.0 qualifizierender Tag** wird 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 **immer** mit 250€ vergütet
|
||||||
|
- **WE-Tage** nur vergütet wenn ≥ 2.0 WE-Einheiten:
|
||||||
|
- Bei Erreichen: 450€ pro WE-Tag
|
||||||
|
- Dann Abzug von 1.0 WE-Einheit (Freitag-Priorität)
|
||||||
|
- Unter Schwellenwert: WE-Dienste = 0€ (nicht als WT vergütet)
|
||||||
|
|
||||||
|
### 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)
|
||||||
|
- 1. Weihnachtstag (25. Dezember)
|
||||||
|
- 2. Weihnachtstag (26. Dezember)
|
||||||
|
|
||||||
|
**Abdeckung**: 2025-2030 (Web-App), 2025-2026 (Python/Android)
|
||||||
|
|
||||||
|
## Entwicklungshinweise
|
||||||
|
|
||||||
|
### Web-App erweitern
|
||||||
|
|
||||||
|
**Neue Feiertage hinzufügen** (`webapp/holidays.js`):
|
||||||
|
```javascript
|
||||||
|
2031: [
|
||||||
|
{ date: '2031-01-01', name: 'Neujahr' },
|
||||||
|
// ... weitere Feiertage
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Berechnungsraten ändern** (`webapp/calculator.js`):
|
||||||
|
```javascript
|
||||||
|
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**:
|
||||||
|
```bash
|
||||||
|
python src/fill_plan_dates.py 2025 11 # November 2025
|
||||||
|
```
|
||||||
|
|
||||||
|
### Android App
|
||||||
|
|
||||||
|
**Build & Install**:
|
||||||
|
```bash
|
||||||
|
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 → 1.0 abgezogen → 1.0 × 450€ = **450€**
|
||||||
|
|
||||||
|
### 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 → -1.0 Abzug → 1.0 bezahlt
|
||||||
|
- Bonus: (2 × 250€) + (1 × 450€) = **950€**
|
||||||
|
|
||||||
|
### Testfall 4: Feiertag + Vortag
|
||||||
|
- 1 × Donnerstag vor Karfreitag (qualifizierend!)
|
||||||
|
- 1 × Karfreitag (Feiertag, qualifizierend!)
|
||||||
|
- Erwartung: 2.0 qualifizierende → -1.0 → 1.0 × 450€ = **450€**
|
||||||
|
|
||||||
|
## Häufige Anpassungen
|
||||||
|
|
||||||
|
### Schwellenwert ändern (Web-App)
|
||||||
|
`webapp/calculator.js`, Zeile 10:
|
||||||
|
```javascript
|
||||||
|
this.MIN_QUALIFYING_DAYS = 3.0; // Statt 2.0
|
||||||
|
```
|
||||||
|
|
||||||
|
### Vergütungsraten ändern (Web-App)
|
||||||
|
`webapp/calculator.js`, Zeilen 8-9:
|
||||||
|
```javascript
|
||||||
|
this.RATE_NORMAL = 300; // Statt 250
|
||||||
|
this.RATE_WEEKEND = 500; // Statt 450
|
||||||
|
```
|
||||||
|
|
||||||
|
### Abzug ändern (Web-App)
|
||||||
|
Aktuell ist der Abzug fest auf 1.0 kodiert in `webapp/calculator.js`, Zeile 66:
|
||||||
|
```javascript
|
||||||
|
qualifyingDaysDeducted = 1.0;
|
||||||
|
```
|
||||||
|
|
||||||
|
Um dies flexibel zu machen, könnte man hinzufügen:
|
||||||
|
```javascript
|
||||||
|
this.DEDUCTION_AMOUNT = 1.0; // Im Constructor
|
||||||
|
// Dann verwenden:
|
||||||
|
qualifyingDaysDeducted = this.DEDUCTION_AMOUNT;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
## Versionshistorie
|
||||||
|
|
||||||
|
- **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.
|
||||||
Reference in a new issue