Dokumentation

README.md

@@ -21,7 +21,7 @@ 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
+- **F2: Faire Monatsverteilung** - Innerhalb eines Monats werden Zuteilungen fair verteilt (pro Diensttyp). **Besonderheit:** Abwesenheitstage werden aus der Dienstpflicht herausgerechnet, um eine gleichmäßigere Verteilung zu erreichen. Die "verpassten" Dienste werden über F1 im Jahresverlauf ausgeglichen.
 - **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
 
@@ -37,7 +37,7 @@ Die Fairness bestimmt **wie viele** Zuteilungen jede Familie erhält, die Präfe
 - **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)
+- **A** - Elternabend (ca. einmal im Monat, 2 Personen)
 
 Die Planung erfolgt für einen Kalendermonat.
 
@@ -56,11 +56,10 @@ Datum,Wochentag,Dienste,Sarah & Tim,Leon,Maya,...
 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:
+4-n. **Eine Spalte pro Familie** - Abwesenheiten und Präferenzen:
    - `x` = nicht verfügbar (Urlaub, Krankheit, etc.)
-   - `F+` = Frühstücksdienst bevorzugt
-   - `P-` = Putznotdienst abgelehnt
-   - `K+` = Kochen bevorzugt
+   - `Kürzel+` = diesen Dienst bevorzugt (z.B. `F+` für Frühstücksdienst bevorzugt)
+   - `Kürzel-` = diesen Dienst abgelehnt (z.B. `P-` für Putznotdienst abgelehnt)
    - Mehrere kombinierbar: `F+P-E+` (Frühstück bevorzugt, Putzen abgelehnt, Essen bevorzugt)
    - Leer = verfügbar, keine Präferenz
 
@@ -81,8 +80,6 @@ Datum,Wochentag,Dienste,Sarah & Tim,Leon,Maya
 
 ### eltern.csv
 
-### eltern.csv
-
 Dienstfaktoren (= Anzahl betreuter Kinder) pro Elternteil und Zeitraum.
 
 **Format:**
@@ -174,7 +171,10 @@ Die **Zielfunktion** bewertet, wie gut eine Dienstverteilung ist. Das Programm m
 **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
+- **Besonderheit Abwesenheiten:** Abwesenheitstage werden aus der Dienstpflicht herausgerechnet (Dienstfaktor = 0). Das bedeutet: Bei einer 2-wöchigen Abwesenheit werden in den verbleibenden 2 Wochen keine zusätzlichen Dienste zugeteilt, um die Abwesenheit auszugleichen.
+- **Warum?** Dies führt zu einer gleichmäßigeren Verteilung im aktuellen Monat und verhindert, dass Familien in den wenigen verfügbaren Tagen überproportional viele Dienste bekommen müssen.
+- **Ausgleich:** Die durch Abwesenheit "verpassten" Dienste werden über F1 (globale Fairness) im Jahresverlauf ausgeglichen.
+- Beispiel: Im Januar sollten Sarah & Tim ca. 2× so viele Zuteilungen erhalten wie Leon (sofern beide den ganzen Monat verfügbar sind)
 
 **F3 (Dienstübergreifende Fairness - Global):**
 - Berechnung: Gesamtanzahl aller Zuteilungen (über alle Diensttypen) pro Eintrag über das ganze Jahr
@@ -221,6 +221,6 @@ Das Programm zeigt nach der Optimierung:
 
 **"Unfaire Verteilung":**
 - Prüfen Sie die Dienstfaktoren in `eltern.csv`
-- Stellen Sie sicher, dass `vorherige-ausgaben.csv` korrekt ist
+- Stellen Sie sicher, dass `vorherige.ausgaben.csv` korrekt ist
 - Mehr Eltern verfügbar machen
 

elterndienstplaner.py

@@ -107,11 +107,20 @@ class Elterndienstplaner:
 
     def berechne_faire_zielverteilung_lokal(self) -> Zielverteilung:
         """Berechnet die lokale faire Zielanzahl von Diensten pro Eltern-Dienst-Kombination
-        basierend auf Dienstfaktoren und benoetigten Diensten im aktuellen Planungszeitraum"""
+        basierend auf Dienstfaktoren und benoetigten Diensten im aktuellen Planungszeitraum
+
+        WICHTIG: Bei der lokalen Fairness werden Abwesenheitstage NICHT in die Dienstpflicht
+        eingerechnet (Dienstfaktor = 0 an Abwesenheitstagen). Das führt zu einer gleichmäßigeren
+        Verteilung im aktuellen Monat und verhindert, dass Familien mit längeren Abwesenheiten
+        in den wenigen verfügbaren Tagen überproportional viele Dienste bekommen.
+
+        Die "verpassten" Dienste werden dann über die globale Fairness (F1) im Jahresverlauf
+        ausgeglichen."""
 
         ziel_dienste_lokal: Zielverteilung = defaultdict(lambda: defaultdict(float))
 
         print("\nBerechne lokale faire Zielverteilung für aktuellen Planungszeitraum...")
+        print("  (Abwesenheitstage werden aus der Dienstpflicht herausgerechnet)")
 
         summe_dienstfaktor_planungszeitraum_alle_eltern = sum(
             sum(self.daten.dienstfaktoren[e][tag] for tag in self.daten.planungszeitraum)