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). 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

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 (ca. einmal im Monat, 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 Familie - Abwesenheiten und Präferenzen:
   • x = nicht verfügbar (Urlaub, Krankheit, etc.)
   • 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

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

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

./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
• 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
• 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 und nur wenig die Gesamtanzahl der Zuteilungen

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

"Unfaire Verteilung":

• Dienstfaktoren in eltern.csv prüfen
• Sicherstellen, dass vorherige.ausgaben.csv korrekt ist