doc/CONCEPT.md aktualisiert

This commit is contained in:
thomas committed 2026-11-21 21:39:19 +00:00
1 parent a3004ca573
commit 051c1f3005
1 file changed
+315
View File
@@ -0,0 +1,315 @@
# 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; optionaler Freitext-Ort |
| `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
**Übersichtlicher Plan (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. Sondergottesdienste
zeigen zusätzlich ihren freien Ort.
- Automatischer Seitenumbruch mit wiederholtem Kopf und Fuß („Seite n“).
**Kompakte Gottesdienstliste (A4 hoch)**
- Nur Tage mit Gottesdiensten, eine Zeile pro Gottesdienst.
- Spalten: verkürztes Datum (nur einmal pro Tag, links), Gottesdienst mit
Kirche bzw. freiem Ort und Uhrzeit, Lektoren und Kommunionhelfer mit
Nachnamen.
- Offene Plätze werden als „offen“ ausgewiesen; Hochfeste und
Sondergottesdienste erhalten einen kurzen Hinweis.
- Sonntage und Hochfeste sind zart hinterlegt; Kopf, Fuß und Seitenzahlen
wiederholen sich auf jeder Seite.
**Gemeinsam**
- Vorschau über PDFKit mit Aktionen „Sichern“ und „Drucken“.
- Druck über `NSPrintInfo`; die Ausrichtung folgt dem Seitenformat
(quer bzw. hoch), 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.
- Sondergottesdienste mit Kirche/Zuordnung und optionalem Freitext-Ort
(Open-Air, Sonderorte).
- PDF-Vorschau in zwei Varianten, Druck und App-Bundle.
- Datenverwaltung: Demo-Daten zurücksetzen oder alle Inhalte löschen; nach dem
Löschen wird der Demo-Bestand beim nächsten Start nicht automatisch
wiederhergestellt.
**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.