elterndienstplaner/README.md

# Elterndienstplaner

Automatische Zuteilung von Elterndiensten im Kinderladen unter Berücksichtigung von Fairness und Präferenzen.

## Wie funktioniert die Dienstplanung?

Der Elterndienstplaner verteilt die anfallenden Dienstzuteilungen für einen Monat automatisch auf die Eltern. Dabei werden folgende Ziele berücksichtigt:

### 1. Regeln (Harte Constraints)

Diese Regeln **müssen** immer eingehalten werden:

- **C1: Maximal einmal pro Woche pro Diensttyp** - Niemand muss z.B. zweimal in einer Woche Frühstücksdienst machen
- **C2: Maximal eine Zuteilung pro Tag** - Niemand bekommt mehrere Dienstzuteilungen am selben Tag
- **C3: Nur bei Verfügbarkeit** - Zuteilungen erfolgen nur bei Verfügbarkeit (keine Abwesenheiten)
- **C4: Alle Dienste werden besetzt** - Jeder benötigte Diensttyp wird an jedem Tag besetzt

### 2. Fairness und Präferenzen (Weiche Constraints)

Diese Ziele werden optimiert, können aber nicht immer perfekt erfüllt werden:

**Fairness:**
- **F1: Faire Jahresverteilung** - Über das ganze Kitajahr hinweg werden Zuteilungen fair verteilt (pro Diensttyp)
- **F2: Faire Monatsverteilung** - Innerhalb eines Monats werden Zuteilungen fair verteilt (pro Diensttyp). Um bei längeren Abwesenheiten für mehr Gleichmäßigkeit in der Verteilung zu sorgen, werden Abwesenheiten aus der Dienstpflicht herausgerechnet
- **F3: Ausgewogene Diensttypen (Jahr)** - Verhindert über das ganze Jahr, dass einzelne Familien über alle Diensttypen hinweg zu viele Zuteilungen bekommen
- **F4: Ausgewogene Diensttypen (Monat)** - Verhindert im aktuellen Monat, dass einzelne Familien über alle Diensttypen hinweg zu viele Zuteilungen bekommen

**Präferenzen:**
- **P1: Bevorzugte Tage für Diensttypen** - An bestimmten Tagen bevorzugte Diensttypen werden nach Möglichkeit zugeteilt
- **P2: Vermeiden an bestimmten Tagen** - An bestimmten Tagen abgelehnte Diensttypen werden nach Möglichkeit vermieden

Die Fairness bestimmt **wie viele** Zuteilungen jede Familie erhält, die Präferenzen beeinflussen **an welchen Tagen welcher Diensttyp** zugeteilt wird. Selbst bei Ablehnung kann ein Diensttyp an einem bestimmten Tag zugeteilt werden, wenn das für die faire Verteilung nötig ist.

## Diensttypen

- **F** - Frühstücksdienst (täglich, 1 Person)
- **P** - Putznotdienst (täglich, 1 Person)
- **E** - Essensausgabenotdienst (täglich, 1 Person)
- **K** - Kochen (ca. alle 2 Wochen, 1 Person)
- **A** - Elternabend (nach Bedarf, 2 Personen)

Die Planung erfolgt für einen Kalendermonat.

## Abwesenheiten und Präferenzen angeben (eingabe.csv)

Diese Datei enthält für jeden Tag des Planungsmonats, welche Dienste anfallen und welche Eltern verfügbar sind bzw. Präferenzen haben.

**Format:**
```
Datum,Wochentag,Dienste,Sarah & Tim,Leon,Maya,...
2026-01-06,Montag,FPE,F+,x,,...
2026-01-07,Dienstag,FPE,P-,F+P+,,...
```

**Spalten:**
1. **Datum** (ISO-Format: YYYY-MM-DD)
2. **Wochentag** (zur Information)
3. **Diensttypen** - Welche Diensttypen an diesem Tag benötigt werden (z.B. "FPE" für Frühstück, Putzen, Essen)
4-n. **Eine Spalte pro Kind** - Abwesenheiten und Präferenzen:
   - `x` = nicht verfügbar (Urlaub, Krankheit, etc.)
   - `F+` = Frühstücksdienst bevorzugt
   - `P-` = Putznotdienst abgelehnt
   - `K+` = Kochen bevorzugt
   - Mehrere kombinierbar: `F+P-E+` (Frühstück bevorzugt, Putzen abgelehnt, Essen bevorzugt)
   - Leer = verfügbar, keine Präferenz

**Beispiel:**
```
Datum,Wochentag,Dienste,Sarah & Tim,Leon,Maya
2026-01-06,Montag,FPE,x,,F+
2026-01-07,Dienstag,FPE,,F+P-,
2026-01-10,Freitag,FPEK,F+K+,,P-
```

- Sarah & Tim sind am 6.1. nicht verfügbar
- Leon bevorzugt am 7.1. Frühstück, lehnt Putzen ab
- Maya bevorzugt am 6.1. Frühstück
- Am 10.1. bevorzugen Sarah & Tim Frühstück oder Kochen

## Weitere Eingabedateien

### eltern.csv

### eltern.csv

Dienstfaktoren (= Anzahl betreuter Kinder) pro Elternteil und Zeitraum.

**Format:**
```
Eltern,Beginn,Ende,Faktor,Beginn,Ende,Faktor,...
Sarah & Tim,2024-09-01,2025-07-31,2
Leon,2024-09-01,2024-12-31,1,2025-01-01,2025-07-31,0
Maya,2024-09-01,2025-07-31,1
```

**Spalten:**
1. **Kind-Name(n)** - Bei mehreren Kindern durch & verbunden (z.B. "Sarah & Tim")
2-4. **Zeitraum 1:** Beginn (Datum), Ende (Datum), Dienstfaktor
5-7. **Zeitraum 2:** Beginn, Ende, Dienstfaktor (optional, für Änderungen während des Jahres)
...

**Hinweise:**
- Der Dienstfaktor entspricht der Anzahl der Kinder in der Familie (z.B. 2 für "Sarah & Tim", 1 für "Leon")
- Familien mit mehreren Kindern werden als ein Eintrag mit entsprechendem Dienstfaktor geführt
- Bei überlappenden Zeiträumen gilt der letzte Eintrag
- Außerhalb definierter Zeiträume: Faktor = 0 (keine Dienstpflicht)
- Faktor = 0 bedeutet: Befreiung von Diensten (z.B. durch Vorstandsamt)

**Beispiel:** Sarah & Tim (Dienstfaktor 2), Leon (Dienstfaktor 1, aber ab Januar 2025 keine Dienstpflicht), Maya (Dienstfaktor 1).

### vorherige-ausgaben.csv (optional)

Frühere Ausgaben des Programms zur Berechnung der Jahres-Fairness.

**Format:** Wie `ausgabe.csv` (siehe unten).

**Verwendung:**
- Zu Beginn des Kita-Jahres (September): Keine Datei nötig
- Ab Oktober: Vorherige Ausgaben anhängen für kumulative Fairness über das Jahr
- Im Jahresverlauf sammeln sich die Ausgaben an

## Ausgabedatei

### ausgabe.csv

Dienstzuteilungen pro Tag. Diese Datei wird vom Programm erstellt.

**Format:**
```
Datum,Wochentag,Frühstücksdienst,Putznotdienst,Essensausgabenotdienst,Kochen,Elternabend
2026-01-06,Montag,Sarah & Tim,Leon,Maya,,
2026-01-07,Dienstag,Maya,Sarah & Tim,Leon,,
```

Jede Zeile entspricht einem Tag, die Spalten enthalten die Kindernamen, denen die jeweiligen Diensttypen zugeteilt wurden.

## Verwendung

```bash
./elterndienstplaner.py <eingabe.csv> <eltern.csv> <ausgabe.csv> [<vorherige-ausgaben.csv>]
```

**Parameter:**
- `eingabe.csv`: Benötigte Diensttypen und Eltern-Präferenzen für den Planungsmonat
- `eltern.csv`: Dienstfaktoren der Eltern (Anzahl betreuter Kinder)
- `ausgabe.csv`: Hier werden die Zuteilungen geschrieben
- `vorherige-ausgaben.csv` (optional): Historische Zuteilungen für Fairness über das Jahr

## Wie werden die Constraints umgesetzt?

Dieser Abschnitt erklärt die technische Umsetzung für technisch interessierte Eltern.

### Mathematisches Optimierungsproblem

Der Elterndienstplaner formuliert die Dienstverteilung als **lineares Optimierungsproblem**. Das bedeutet: Es gibt viele mögliche Dienstverteilungen, die alle die harten Constraints (C1-C4) erfüllen. Das Programm sucht diejenige, die die Fairness-Ziele am besten erfüllt und Präferenzen berücksichtigt.

**Entscheidungsvariablen:** Für jeden Tag, jeden Eintrag und jeden Diensttyp gibt es eine Variable: "Wird Sarah & Tim am 6. Januar der Frühstücksdienst zugeteilt?" (Ja/Nein)

**Constraints (Nebenbedingungen):** Diese schränken die möglichen Lösungen ein:

- **C1 (Wöchentliches Limit):** Für jeden Eintrag und jeden Diensttyp: Die Summe der Zuweisungen pro Woche ≤ 1
- **C2 (Tageslimit):** Für jeden Eintrag und jeden Tag: Die Summe aller Zuweisungen ≤ 1
- **C3 (Verfügbarkeit):** Wenn im Feld "x" steht, wird die entsprechende Variable auf 0 gesetzt
- **C4 (Bedarfsdeckung):** Für jeden Tag und Diensttyp: Summe der Zuweisungen = benötigte Personenzahl

### Zielfunktion: Fairness und Präferenzen

Die **Zielfunktion** bewertet, wie gut eine Dienstverteilung ist. Das Programm minimiert Abweichungen von fairer Verteilung und berücksichtigt Präferenzen.

**F1 (Globale Fairness):**
- Berechnung: Für jeden Eintrag und jeden Diensttyp wird gezählt, wie viele Zuteilungen bisher über das Jahr verteilt wurden (aus `vorherige-ausgaben.csv`)
- Ziel: Die Gesamtanzahl soll proportional zum Dienstfaktor sein
- Beispiel: Sarah & Tim (Dienstfaktor 2) hatten bisher 10 Zuteilungen, Leon (Dienstfaktor 1) hatte 8 Zuteilungen. Das ist unfair (sollte 2:1 sein, also z.B. 12:6). Im aktuellen Monat sollte Leon bevorzugt werden, um das auszugleichen.
**F2 (Lokale Fairness):**
- Berechnung: Nur für den aktuellen Planungsmonat
- Ziel: Die Anzahl der Zuteilungen im aktuellen Monat soll proportional zum Dienstfaktor sein
- Beispiel: Im Januar sollten Sarah & Tim ca. 2× so viele Zuteilungen erhalten wie Leon

**F3 (Dienstübergreifende Fairness - Global):**
- Berechnung: Gesamtanzahl aller Zuteilungen (über alle Diensttypen) pro Eintrag über das ganze Jahr
- Ziel: Verhindert, dass einzelne Familien über verschiedene Diensttypen hinweg zu viele Zuteilungen bekommen
- Beispiel: Sarah & Tim hatten bisher 10 Zuteilungen über alle Diensttypen, Leon nur 3. Das Verhältnis sollte 2:1 sein (12:6). F3 würde Leon im aktuellen Monat bevorzugen.

**F4 (Dienstübergreifende Fairness - Lokal):**
- Berechnung: Gesamtanzahl aller Zuteilungen (über alle Diensttypen) pro Eintrag im aktuellen Monat
- Ziel: Verhindert, dass einzelne Familien im aktuellen Monat über verschiedene Diensttypen hinweg zu viele Zuteilungen bekommen
- Beispiel: Im Januar werden Sarah & Tim 3× Frühstück, 2× Putzen, 2× Essen = 7 Zuteilungen zugeteilt. Leon bekommt nur 1× Frühstück, 1× Putzen = 2 Zuteilungen. F4 würde Leon weitere Zuteilungen zuweisen, um die Gesamtzahl im Monat anzugleichen.

**P1 und P2 (Präferenzen):**
- An bestimmten Tagen bevorzugte Diensttypen (`+`) bekommen einen Bonus in der Zielfunktion
- An bestimmten Tagen abgelehnte Diensttypen (`-`) bekommen eine Strafe in der Zielfunktion
- Diese Effekte sind **schwächer** als die Fairness-Terme, d.h. Fairness hat Vorrang
- **Wichtig:** Präferenzen beeinflussen nur, an welchen Tagen welcher Diensttyp zugeteilt wird, nicht die Gesamtanzahl der Zuteilungen

### Gewichtung

Die verschiedenen Fairness-Ziele werden gewichtet:
- **F1 (global): 40%** - Wichtig für Ausgleich über das Jahr (pro Diensttyp)
- **F2 (lokal): 60%** - Wichtiger für den aktuellen Monat (pro Diensttyp)
- **F3 (global): 10%** - Verhindert extreme Ungleichverteilung über Diensttypen im Jahr
- **F4 (lokal): 15%** - Verhindert extreme Ungleichverteilung über Diensttypen im Monat
- **P1/P2: niedrig** - Präferenzen werden berücksichtigt, wenn Fairness gewahrt ist

## Programmausgabe und Statistiken

Das Programm zeigt nach der Optimierung:

1. **Zuteilungen pro Eintrag**: Übersicht der zugeteilten Diensttypen für jeden Eintrag
2. **Dienstfaktoren**: Summe der Dienstfaktoren im Planungszeitraum
3. **Verteilungsvergleich**:
   - Soll-Werte (lokal und global) basierend auf Fairness
   - Ist-Werte (tatsächlich zugeteilte Diensttypen)
   - Abweichungen zwischen Soll und Ist
4. **Präferenz-Verletzungen**: Wie oft wurden abgelehnte Diensttypen (`-`) trotzdem zugeteilt
## Troubleshooting

**"Keine optimale Lösung gefunden":**
- Zu viele Eltern nicht verfügbar
- Nicht genug Eltern für alle benötigten Diensttypen
- Widersprüchliche Präferenzen

**"Unfaire Verteilung":**
- Prüfen Sie die Dienstfaktoren in `eltern.csv`
- Stellen Sie sicher, dass `vorherige-ausgaben.csv` korrekt ist
- Mehr Eltern verfügbar machen