294 lines
12 KiB
Markdown
294 lines
12 KiB
Markdown
# LektorenPlan – Grobkonzept
|
||
|
||
**Pfarreiengemeinschaft Bad Godesberg · Erzbistum Köln**
|
||
Planung von Lektorinnen, Lektoren und Kommunionhelferinnen/-helfern für
|
||
St. Andreas, St. Evergislus, Herz Jesu und St. Hildegard.
|
||
|
||
---
|
||
|
||
## 1. Zielbild
|
||
|
||
LektorenPlan unterstützt das Pfarrbüro und das ehrenamtliche Planungsteam dabei,
|
||
Gottesdienste über einen frei wählbaren Zeitraum mit den passenden Diensten zu
|
||
besetzen. Die Anwendung verbindet drei Perspektiven:
|
||
|
||
1. **Kalender** – jeder Tag des Zeitraums mit Liturgie, Lesungen und allen
|
||
Gottesdiensten der vier Kirchen.
|
||
2. **Planung** – automatische Verteilung unter harten Randbedingungen und
|
||
weichen Präferenzen, mit manueller Nachsteuerung.
|
||
3. **Auswertung** – Einsatzhäufigkeit, Verteilung auf Orte, Fairness und
|
||
Präferenztreffer für beliebige vergangene oder künftige Zeitfenster.
|
||
|
||
Die Planung ist lokal, offline nutzbar und speichert alle Daten in einer
|
||
SQLite-Datenbank. Liturgische Daten werden bevorzugt aus dem mitgelieferten
|
||
Bestand gelesen und können online aktualisiert werden.
|
||
|
||
---
|
||
|
||
## 2. Nutzer und typische Abläufe
|
||
|
||
| Rolle | Aufgabe |
|
||
|---|---|
|
||
| Planungsteam | Zeitraum wählen, Dienste erzeugen, automatisch planen, Lücken manuell schließen, Ergebnis drucken |
|
||
| Ressourcenverwaltung | Personen, Rollen, Präferenzen, Abwesenheiten und Monatslimits pflegen |
|
||
| Gottesdienstordnung | Wiederkehrende Termine, Ausnahmen und Sondergottesdienste pflegen |
|
||
| Austausch | Planungsabschnitte oder Stammdaten als JSON zwischen Installationen übergeben |
|
||
|
||
Typischer Ablauf eines Quartals:
|
||
|
||
1. Zeitraum über den Zeitstrahl oder eine Zeitmarke (Quartal, Osterzeit,
|
||
Weihnachtszeit, Kirchenjahr) wählen.
|
||
2. Gottesdienste aus den Vorlagen erzeugen und Sondertermine ergänzen.
|
||
3. „Offene Dienste besetzen“ oder „Zeitraum neu planen“ ausführen.
|
||
4. Offene Dienste im Ergebnis prüfen und im Detaildialog manuell besetzen.
|
||
5. Statistik prüfen, PDF-Vorschau öffnen, drucken oder sichern.
|
||
6. Bei Bedarf Plan oder Ressourcen exportieren.
|
||
|
||
---
|
||
|
||
## 3. Architektur
|
||
|
||
```
|
||
LektorenPlan.app
|
||
├── LektorenPlan (SwiftUI, macOS 14+)
|
||
│ ├── RootView / Sidebar
|
||
│ ├── PlanningView Kalender & Tagesplanung
|
||
│ ├── ServiceOrderView Gottesdienstordnung
|
||
│ ├── TeamView Lektoren & Kommunionhelfer
|
||
│ ├── StatisticsView Auswertung (Swift Charts)
|
||
│ ├── ExchangeView Import/Export
|
||
│ ├── SettingsView Kalender, Planung, Datenhaltung
|
||
│ ├── Sheets Personen, Vorlagen, Sondertermine, Detail, PDF
|
||
│ └── PlanModel beobachtbarer App-Zustand und Aktionen
|
||
└── LektorenPlanCore
|
||
├── Models Domänenmodelle und Statistiktypen
|
||
├── DateUtils Tagesnormalisierung, Zeiträume, deutsche Formate
|
||
├── LiturgicalCalendar Osterdatum, Kirchenjahr, Hochfeste, Offline-Fallback
|
||
├── LiturgicalAPI Abruf und Parser für eucharistiefeier.de
|
||
├── SQLiteDatabase schlanker SQLite-Wrapper
|
||
├── AppDatabase Schema, CRUD, Erzeugung, Austausch, Demo-Daten
|
||
├── Planner Regel- und scorebasierte Verteilung
|
||
└── Statistics Kennzahlen und Präferenzauswertung
|
||
```
|
||
|
||
**Technische Entscheidungen**
|
||
|
||
- Swift Package Manager statt handgepflegtem Xcode-Projekt; `Package.swift`
|
||
lässt sich direkt in Xcode öffnen.
|
||
- Keine externen Abhängigkeiten. SQLite über das Systemmodul `SQLite3`.
|
||
- Core-Logik und UI sind getrennt, damit Planung und Statistik testbar bleiben.
|
||
- macOS 14 als Mindestversion, Swift-5-Sprachmodus.
|
||
- Das App-Bundle wird über `Scripts/build-app.sh` erzeugt.
|
||
|
||
---
|
||
|
||
## 4. Datenmodell
|
||
|
||
Alle Tabellen liegen in `~/Library/Application Support/LektorenPlan/lektorenplan.sqlite`.
|
||
|
||
| Tabelle | Inhalt |
|
||
|---|---|
|
||
| `churches` | Kirchen mit Kürzel, Kirchensymbol, Farbe, Adresse, Sortierung |
|
||
| `people` | Personen mit Rollen, Kontakt, Präferenzen, Monatslimit, Aktivstatus |
|
||
| `absences` | Abwesenheitszeiträume je Person inkl. Grund |
|
||
| `service_templates` | Wiederkehrende Gottesdienste (Wochentag, Uhrzeit, benötigte Dienste, Gültigkeit) |
|
||
| `service_exceptions` | Ausgesetzte Termine einer Vorlage (z. B. wegen Fest oder Ferien) |
|
||
| `services` | Konkrete Termine, erzeugt aus Vorlagen oder als Sondergottesdienst |
|
||
| `assignments` | Einsatz einer Person in einer Rolle, optional gesperrt |
|
||
| `liturgical_days` | Liturgischer Tag, Rang, Farbe, Lesungen, Quelle |
|
||
| `settings` | Zeitraum, Filter, Kalender- und Planungseinstellungen |
|
||
|
||
Zeiträume werden als Tagesbereich (`DayRange`) geführt. Alle Datumsangaben
|
||
werden auf 12:00 Uhr Europe/Berlin normalisiert, um Sommerzeit- und
|
||
Mitternachtsprobleme zu vermeiden. Schlüssel sind `yyyy-MM-dd`.
|
||
|
||
**Stabile IDs** (UUIDs) verbinden Datensätze beim Import. Ein Zusammenführen
|
||
aktualisiert vorhandene Kirchen, Personen und Vorlagen und ergänzt neue
|
||
Gottesdienste und Einsätze; es wird nichts gelöscht.
|
||
|
||
---
|
||
|
||
## 5. Liturgischer Kalender
|
||
|
||
- Quelle: `https://www.eucharistiefeier.de/lk/api.php` mit `kal=koeln`,
|
||
`format=json`, `info=wdtrflu`, `dup=e`, `bahn=j`.
|
||
- Für 2025–2028 liegt ein Offline-Snapshot bei (1461 Tage), damit die App
|
||
sofort und ohne Netz funktioniert.
|
||
- Beim Start wird höchstens einmal pro Tag der Jahrgang des aktuellen
|
||
Zeitraums aktualisiert. Manuelle Aktualisierung ist jederzeit möglich.
|
||
- Der lokale Rechner (`LiturgicalCalendarEngine`) bestimmt Ostern, Advent,
|
||
Kirchenjahr, Sonntage, Hochfeste und gebotene Feiertage. Er dient als
|
||
Fallback und zur Plausibilisierung.
|
||
- Angezeigt werden Tagesliturgie, Rang, liturgische Farbe, Kurzlesungen
|
||
(erste Lesung, Psalm, zweite Lesung, Evangelium) und Quellenhinweis.
|
||
|
||
**Attribution:** „Daten von www.eucharistiefeier.de“ ist in App, PDF und
|
||
Einstellungen sichtbar. Die Daten werden nur zur Anzeige genutzt; die Quelle
|
||
bleibt Eigentümerin der Daten.
|
||
|
||
---
|
||
|
||
## 6. Planungsalgorithmus
|
||
|
||
Die Planung arbeitet deterministisch und nachvollziehbar.
|
||
|
||
### Harte Ausschlüsse
|
||
|
||
Eine Person wird für einen Dienst nicht vorgeschlagen, wenn
|
||
|
||
- sie die benötigte Rolle nicht hat,
|
||
- sie im Zeitraum abwesend ist,
|
||
- sie an diesem Tag bereits eingeteilt ist,
|
||
- ihr Monatslimit erreicht ist,
|
||
- ihr bevorzugter Einsatztag nicht passt (optional, standardmäßig aktiv),
|
||
- sie bereits im selben Gottesdienst eingeplant ist.
|
||
|
||
Gesperrte Einsätze werden bei einer Neuplanung nie verändert.
|
||
|
||
### Weiche Bewertung
|
||
|
||
Jede verbleibende Person erhält einen Score:
|
||
|
||
- Grundwert,
|
||
- Bonus für bevorzugte Kirche,
|
||
- Bonus für passenden Gottesdiensttitel,
|
||
- Bonus für bevorzugten Wochentag,
|
||
- Malus für viele bisherige Einsätze (Fairness),
|
||
- Malus für viele Einsätze an derselben Kirche,
|
||
- Bonus für eine längere Pause seit dem letzten Einsatz,
|
||
- kleiner stabiler Tie-Break, damit die Verteilung reproduzierbar bleibt.
|
||
|
||
Die Gewichte sind in den Einstellungen justierbar (Fairness-Gewicht,
|
||
Einsatztage als Ausschluss). Der Planer besetzt zuerst alle Dienste des
|
||
Zeitraums und dokumentiert für offene Dienste den häufigsten Ausschlussgrund
|
||
(z. B. „Monatslimit erreicht (4 ausgeschlossen)“).
|
||
|
||
### Manuelle Nachsteuerung
|
||
|
||
Im Detaildialog eines Gottesdienstes werden Kandidaten mit Eignung, bisherigen
|
||
Einsätzen im Zeitraum, Präferenztreffer und Warnhinweisen angezeigt. Ein Klick
|
||
teilt die Person ein oder entfernt sie. Einsätze können gesperrt werden, damit
|
||
sie bei der nächsten Automatik erhalten bleiben.
|
||
|
||
---
|
||
|
||
## 7. Oberfläche und Interaktion
|
||
|
||
- **Ruhige Papieroptik** mit warmen Hintergründen, Akzentgrün, Gold und
|
||
Burgunder; Serif-Überschriften, klare Piktogramme. Das App-Icon greift die
|
||
Gestaltung auf: eine Kirchen-Silhouette hinter einer Kalenderkarte.
|
||
- **Kalender als Tabelle:** eine Zeile pro Tag, feste Spalten für Datum,
|
||
Liturgie/Lesungen und die vier Kirchen. Sonntage, Hochfeste und gebotene
|
||
Feiertage sind farblich hinterlegt; liturgische Farbbalken markieren den Tag.
|
||
- **Kirchen-Strichzeichnungen** (Basilika, Saalkirche, Jugendstilkirche,
|
||
moderne Kirche). Der Name erscheint im Tooltip und in der Spaltenüberschrift.
|
||
- **Symbole für Hochfeste** und Rangabzeichen (GEDENKTAG, FEST, HOCHFEST,
|
||
GEBOTEN).
|
||
- **Zeitstrahl** mit zwei Griffen, Jahresrastern und Marken für Quartale,
|
||
Osterzeit, Weihnachtszeit und Kirchenjahr. Der gewählte Bereich wird sofort
|
||
auf Tabelle und Statistik angewendet.
|
||
- **Filter** „Alle Tage“, „Mit Gottesdiensten“, „Nur offene“ und
|
||
„Sonn- & Feiertage“; Suche über Person, Ort und Lesung.
|
||
- **Servicekarten** zeigen Uhrzeit, Titel, offene Plätze und die eingeteilten
|
||
Personen. Ein Klick öffnet den Detaildialog.
|
||
- **Dialoge** für Personen, Vorlagen, Sondergottesdienste, Importvorschau und
|
||
PDF-Vorschau. Alle Dialoge haben dieselbe Kopf-/Fußstruktur.
|
||
- **Statistik** mit Kennzahlen, Balken-, Linien- und Donut-Diagrammen sowie
|
||
einer Einsatzübersicht je Person.
|
||
- **Dark Mode** ist nicht Teil des Prototyps; das Farbsystem ist bewusst auf
|
||
die helle Papieroptik ausgelegt.
|
||
|
||
---
|
||
|
||
## 8. Statistik
|
||
|
||
Für den gewählten Zeitraum werden berechnet:
|
||
|
||
- Anzahl Gottesdienste, benötigter und besetzter Dienste, offene Dienste,
|
||
- Besetzungsquote,
|
||
- Einsätze pro Person (Lektor/Kommunionhelfer, Sonntage, Kirchen),
|
||
- Fairness: Durchschnitt, Minimum, Maximum und Spannweite,
|
||
- Verlauf nach Monat (auch Monate ohne Einsätze),
|
||
- Verteilung auf die Kirchen inkl. offener Dienste,
|
||
- Präferenztreffer: Nur Einsätze von Personen mit hinterlegten Präferenzen
|
||
zählen als bewertbar; die Quote ist Treffer / bewertbare Einsätze.
|
||
- Abwesenheitstage im Zeitraum.
|
||
|
||
Die Statistik nutzt denselben Datenbestand wie die Planung und aktualisiert
|
||
sich beim Wechsel des Zeitraums, bei Planungsänderungen und beim Import.
|
||
|
||
---
|
||
|
||
## 9. Import und Export
|
||
|
||
Das Austauschformat ist lesbares JSON mit:
|
||
|
||
- Format- und App-Version,
|
||
- Exportzeitpunkt und Notiz,
|
||
- Umfang (`plan` oder `resources`),
|
||
- Zeitraum,
|
||
- Kirchen, Personen, Abwesenheiten, Vorlagen, Ausnahmen,
|
||
- bei `plan` zusätzlich Gottesdienste, Einsätze und liturgische Tage.
|
||
|
||
Beim Import wird die Datei zuerst gelesen und in einer Vorschau mit Anzahl der
|
||
enthaltenen Datensätze angezeigt. Erst nach Bestätigung werden die Daten
|
||
zusammengeführt. Der Import ist idempotent über stabile IDs und löscht keine
|
||
vorhandenen Daten.
|
||
|
||
---
|
||
|
||
## 10. PDF und Druck
|
||
|
||
- A4 quer, eigener Renderer mit AppKit/CoreGraphics.
|
||
- Kopfbereich mit Zeitraum, Erstellungsdatum und Quellenhinweis; wiederholte
|
||
Kirchenspalten auf jeder Seite.
|
||
- Ein Tagesblock mit Datum, Liturgie, Lesungen und den Diensten aller vier
|
||
Kirchen. Hochfeste und Sonntage sind farblich hinterlegt.
|
||
- Automatischer Seitenumbruch mit wiederholtem Kopf und Fuß
|
||
(„Seite n“).
|
||
- Vorschau über PDFKit mit Aktionen „Sichern“ und „Drucken“.
|
||
- Druck über `NSPrintInfo` in Querformat, ohne zusätzliche Ränder.
|
||
|
||
---
|
||
|
||
## 11. Prototyp – Stand und Grenzen
|
||
|
||
**Umgesetzt**
|
||
|
||
- Vollständiges Domänenmodell, SQLite-Schema, CRUD und Demo-Daten.
|
||
- 22 fiktive Personen, 13 wiederkehrende Vorlagen, Sondertermine und
|
||
Ausnahmen für 2025–2028.
|
||
- Liturgischer Snapshot, Online-Aktualisierung, lokaler Fallback.
|
||
- Planer mit harten Regeln, Scoring, Fairness und Begründungen für Lücken.
|
||
- Kalender, Zeitstrahl, Filter, Suche, Detaildialog und manuelle Planung.
|
||
- Gottesdienstordnung, Teamverwaltung, Statistik, Austausch und Einstellungen.
|
||
- PDF-Vorschau, Druck und App-Bundle.
|
||
|
||
**Bewusste Grenzen**
|
||
|
||
- Einzelplatz-Anwendung ohne Benutzerkonten und Server-Synchronisation.
|
||
- Keine automatische E-Mail-Benachrichtigung an Eingeteilte.
|
||
- Keine Kalender-Exporte (ICS) und keine iCloud-Synchronisation.
|
||
- Dark Mode, VoiceOver-Feinschliff und Lokalisierung über Deutsch hinaus sind
|
||
noch nicht ausgearbeitet.
|
||
- Die Demo-Personen und -Kontaktdaten sind fiktiv.
|
||
|
||
**Nächste Schritte**
|
||
|
||
1. Reale Stammdaten importieren und Planungsregeln mit dem Team kalibrieren.
|
||
2. Benachrichtigungen und ICS-Export ergänzen.
|
||
3. Mehrbenutzerbetrieb über einen gemeinsamen Speicherort oder Server prüfen.
|
||
4. Bedienungshilfen, Dark Mode und Tastaturnavigation ausbauen.
|
||
5. Signierung/Notarisierung und Update-Mechanismus für die Verteilung.
|
||
|
||
---
|
||
|
||
## 12. Datenschutz und Betrieb
|
||
|
||
- Alle Daten bleiben lokal auf dem Mac; keine Cloud im Prototyp.
|
||
- Exportdateien enthalten personenbezogene Daten und sollten geschützt
|
||
weitergegeben werden.
|
||
- Die liturgische Quelle wird sparsam und nur zur Aktualisierung abgefragt.
|
||
- Vor einem produktiven Einsatz sind Löschkonzept, Zugriffsrechte und
|
||
Einwilligungen der ehrenamtlich Tätigen zu klären.
|