From f8648313bfb75ed1e5288f50176ecafbd8958057 Mon Sep 17 00:00:00 2001 From: Jan Hoheisel Date: Sat, 17 Jan 2026 23:38:11 +0100 Subject: [PATCH] Dokumentation --- README.md | 53 +++++++++++++++++++++---------------------- elterndienstplaner.py | 11 ++++++++- 2 files changed, 36 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 021ca5f..4aad1ef 100644 --- a/README.md +++ b/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. @@ -47,29 +47,28 @@ Diese Datei enthält für jeden Tag des Planungsmonats, welche Dienste anfallen **Format:** ``` -Datum,Wochentag,Dienste,Sarah & Tim,Leon,Maya,... -2026-01-06,Montag,FPE,F+,x,,... -2026-01-07,Dienstag,FPE,P-,F+P+,,... +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: +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 **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- +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 @@ -81,16 +80,14 @@ Datum,Wochentag,Dienste,Sarah & Tim,Leon,Maya ### 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 +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:** @@ -127,9 +124,9 @@ 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,, +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. @@ -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 @@ -217,10 +217,9 @@ Das Programm zeigt nach der Optimierung: **"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 +- Dienstfaktoren in `eltern.csv` prüfen +- Sicherstellen, dass `vorherige.ausgaben.csv` korrekt ist + diff --git a/elterndienstplaner.py b/elterndienstplaner.py index 6829a5b..107c518 100755 --- a/elterndienstplaner.py +++ b/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)