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