Add morning meeting planner design spec

2026-04-07 16:28:09 +02:00
commit 72891f770f
1 changed files with 148 additions and 0 deletions
--- a/docs/superpowers/specs/2026-04-07-morning-meeting-planner-design.md
+++ b/docs/superpowers/specs/2026-04-07-morning-meeting-planner-design.md
@@ -0,0 +1,148 @@
+# Morning Meeting Planner — Design Spec
+**Datum:** 2026-04-07
+
+## Überblick
+
+Web-App zur Verteilung von Mitarbeitern auf die Werktage eines Monats für die Moderation des täglichen Morning Meetings. Die Verteilung erfolgt quasi-zufällig mit konfigurierbaren Einschränkungen pro Mitarbeiter und monatsübergreifendem Fairness-Ausgleich.
+
+---
+
+## Architektur
+
+**Technologie:** Reines HTML + Vanilla JavaScript + CSS. Keine Frameworks, kein Build-Schritt. Direkt im Browser öffenbar.
+
+**Bibliotheken (via CDN):**
+- `SheetJS` — Excel lesen (.xlsx Import der Mitarbeiterliste) und schreiben (Export des Ergebnisses)
+
+**Deployment:** Statische Dateien, kein Server nötig. Für spätere Mehrbenutzer-Nutzung via einfachem Webhosting (z.B. Netlify, GitHub Pages, internes Hosting).
+
+**Dateistruktur:**
+```
+morning-planner/
+├── index.html       # Haupt-App
+├── app.js           # Logik (Algorithmus, Import/Export)
+├── style.css        # Styling
+```
+
+**Erster Start:** Die App startet mit leerem Zustand (keine `.json`-Datei nötig). Mitarbeiter können direkt manuell hinzugefügt oder per Excel importiert werden. Beim ersten "Speichern" wird eine neue `.json`-Datei erstellt.
+
+**Datenfluss:**
+1. Nutzer lädt optional eine `.json`-Datei → App lädt Mitarbeiterliste, Einschränkungen, Verlauf
+2. Nutzer konfiguriert Monat (Feiertage, Betriebsurlaub markieren) und generiert Plan
+3. App speichert generierten Plan im internen Verlauf
+4. Nutzer exportiert: a) Ergebnis als `.xlsx`, b) App-Stand als `.json` zum Wiederverwenden
+
+---
+
+## Datenmodell
+
+Die gespeicherte `.json`-Datei enthält drei Bereiche:
+
+```json
+{
+  "employees": [
+    {
+      "id": "uuid",
+      "name": "Max Mustermann",
+      "constraints": {
+        "neverDays": [5],
+        "lowPriorityDays": [5],
+        "onlyDays": [1, 2, 3],
+        "maxPerMonth": 2,
+        "minGapDays": 5,
+        "vacations": [
+          { "from": "2026-03-01", "to": "2026-03-07" }
+        ]
+      }
+    }
+  ],
+  "calendar": {
+    "holidays": ["2026-01-01", "2026-04-03"],
+    "companyClosures": ["2026-12-24"]
+  },
+  "history": [
+    { "date": "2026-03-04", "employeeId": "uuid", "manual": false }
+  ]
+}
+```
+
+**Wochentage:** 1 = Montag, 2 = Dienstag, 3 = Mittwoch, 4 = Donnerstag, 5 = Freitag
+
+**Constraint-Typen:**
+- `neverDays` — Mitarbeiter kann an diesen Wochentagen nie eingeteilt werden
+- `lowPriorityDays` — Niedrigere Priorität (z.B. Home-Office-Tag)
+- `onlyDays` — Mitarbeiter kann nur an diesen Wochentagen eingeteilt werden
+- `maxPerMonth` — Maximale Einsätze pro Monat
+- `minGapDays` — Mindestabstand in Tagen zwischen zwei Einsätzen
+- `vacations` — Urlaubszeiträume (von/bis, inklusive)
+
+---
+
+## UI & Screens
+
+Die App hat **3 Tabs**:
+
+### Tab 1: Mitarbeiter
+- Excel-Datei importieren (liest erste Spalte als Namen, erste Zeile = Header wird übersprungen)
+- Liste aller Mitarbeiter mit Übersicht ihrer Einschränkungen
+- Pro Mitarbeiter: Einschränkungen bearbeiten (Formular mit allen Constraint-Typen)
+- Mitarbeiter manuell hinzufügen / entfernen
+
+### Tab 2: Monatsplanung
+- Monatsauswahl (Monat + Jahr, Bereich: 2026)
+- Kalenderansicht des Monats: Werktage anzeigen, Wochenenden automatisch grau
+- Feiertage / Betriebsurlaub per Klick markieren (gesperrt, werden nicht belegt)
+- Button "Plan generieren" → füllt Kalender mit zugewiesenen Mitarbeiternamen
+- Manuelles Überschreiben einzelner Tage via Dropdown
+- Export-Button → `.xlsx` herunterladen
+
+**Excel-Export-Format:**
+- Zeile 1: Mitarbeiternamen
+- Zeile 2: Datum im Format `dd.mm.yyyy`
+- Leere Tage (kein Mitarbeiter verfügbar) werden ausgelassen
+
+### Tab 3: Daten
+- App-Stand als `.json` exportieren ("Speichern")
+- `.json`-Datei importieren ("Laden")
+- Verlauf anzeigen (Tabelle: Datum + Mitarbeiter + manuell/automatisch)
+- Verlauf manuell bereinigen (einzelne Einträge löschen)
+
+---
+
+## Algorithmus
+
+**Ziel:** Jeden Werktag des Monats einem verfügbaren Mitarbeiter zuweisen mit fairem monatsübergreifendem Ausgleich.
+
+**Ablauf pro Tag (aufsteigend):**
+
+1. **Filtern** — Mitarbeiter ausschließen wenn:
+   - Urlaub an dem Tag
+   - Tag in `neverDays`
+   - `onlyDays` definiert und Tag nicht enthalten
+   - `maxPerMonth` bereits erreicht (im aktuellen Monat)
+   - Letzter Einsatz liegt weniger als `minGapDays` zurück
+
+2. **Score berechnen** für jeden verbleibenden Kandidaten:
+   - Basis-Score = max. Einsätze im Verlauf − eigene Einsätze im Verlauf (weniger Einsätze = höherer Score)
+   - Abzug wenn Tag in `lowPriorityDays`: Score × 0.5
+   - Zufallskomponente: Score × (0.9 bis 1.1)
+
+3. **Zuweisung** — Kandidat mit höchstem Score bekommt den Tag
+
+4. **Kein Kandidat** → Tag bleibt leer (im Export ausgelassen)
+
+**Manuelle Korrekturen** überschreiben den Algorithmus und werden mit `"manual": true` im Verlauf gespeichert. Sie fließen dennoch in den Fairness-Ausgleich ein.
+
+---
+
+## Kalender 2026
+
+Der Kalender für 2026 ist fest eingebaut (keine externe API). Wochenenden werden automatisch erkannt. Gesetzliche Feiertage und Betriebsurlaub werden manuell vom Nutzer im Tool markiert und in der `.json`-Datei gespeichert.
+
+---
+
+## Offene Punkte / Nicht im Scope
+
+- Keine Benutzerauthentifizierung (einzelner Nutzer)
+- Keine automatische Synchronisation zwischen mehreren Nutzern (manueller JSON-Austausch)
+- Kein Support für Jahre außer 2026 (kann später erweitert werden)