Initial standalone bundle release (sanitized history)

2026-04-01 11:05:34 +02:00
commit 42a94a2dd9
21 changed files with 1924 additions and 0 deletions
@@ -0,0 +1,224 @@
+# mummert/ks-nossenerland-bundle
+
+Contao-Bundle fuer projektspezifische Erweiterungen rund um Veranstaltungen im Kirchspiel Nossener Land.
+
+Ziel dieses Bundles ist die Kapselung bestehender, produktiver Logik (ohne fachliche Aenderung) als installierbares Paket.
+
+## Funktionsueberblick
+
+Das Bundle erweitert vor allem die Event-Verwaltung und den Event-Output in Contao:
+
+- DCA-Erweiterung fuer `tl_calendar_events` (zusatzliche Felder, Palettenanpassung, Callback fuer Aliasbildung)
+- Template-Hooks zur Anreicherung von Event-, Orts- und Angebotsdaten
+- iCal-Hook zur Anpassung von VEvent-Daten
+- CLI-Commands fuer
+  - Export von Events zum EVLKS-Kalender (SOAP + Aufraeumen nicht mehr vorhandener Eintraege)
+  - Export von Events in eine JSON-Datei fuer externe Nutzung
+
+## Technische Bestandteile
+
+### 1) DCA-Anpassungen fuer Kalender-Events
+
+Datei: `contao/dca/tl_calendar_events.php`
+
+- Fuegt u. a. Felder hinzu:
+  - `catalog_ort`
+  - `catalog_kontakt`
+  - `catalog_pfarrbereiche`
+  - `godi_options`
+  - `subtitle`
+  - `contributors`
+  - `evlkscalendar`
+  - `export`
+  - `external_location`
+- Passt Paletten an (Legenden/Felder) und entfernt Standard-Location-Felder aus der Default-Palette.
+- Aktiviert Alias-Neuaufbau ueber `onsubmit_callback`.
+
+### 2) Alias-Bildung fuer Events
+
+Datei: `src/EventListener/CalendarAliasListener.php`
+
+- Erzeugt beim Speichern eines Events einen sprechenden Alias aus:
+  - Eventtitel
+  - Ortstitel (`ctlg_orte`)
+  - Datum
+- Nutzt Transliterations-/Kuerzungslogik und sorgt fuer Eindeutigkeit durch Suffix `-1`, `-2`, ...
+
+### 3) Backend-Listing/Options-Callbacks
+
+Datei: `src/DataContainer/CalendarEvents.php`
+
+- Formatiert Kinddatensaetze im Event-Backend-Listing.
+- Liefert Select-Optionen aus:
+  - `ctlg_orte`
+  - `ctlg_contacts`
+  - `ctlg_districts`
+
+### 4) Template-Hooks (parseTemplate)
+
+Dateien:
+
+- `src/EventListener/EventFullListener.php`
+  - Reichert `event_full` um Ort, Alias, Koordinaten, District-Informationen an.
+- `src/EventListener/EventJsonDataListener.php`
+  - Laedt JSON aus `https://ics.mummert.dev/kirchenjahr.json` und injiziert passenden Datensatz nach Datum in `event_full` und `event_upcoming_all`.
+- `src/EventListener/OfferListener.php`
+  - Reichert Angebots-/Kontakt-Templates (`cm_master_angebote`, `cm_master_contacts`, `cm_listing_angebote`) mit Gemeinde-/District-Daten an.
+- `src/EventListener/PlaceListener.php`
+  - Reichert Orts-Listing (`cm_listing_orte`) mit Gemeinde-IDs und District-Aliases an.
+
+### 5) iCal-Anpassung
+
+Datei: `src/EventListener/ModifyIcalDataListener.php`
+
+Hook: `editVEvent`
+
+- Setzt/normalisiert iCal-Felder wie `DTSTART`, `DESCRIPTION`, `LOCATION`, `GEO`, `ORGANIZER`.
+- Verarbeitet Kontakt- und Mitwirkendeninformationen aus Eventfeldern.
+
+### 6) Event-Export zum EVLKS-Kalender
+
+Dateien:
+
+- `src/Command/ExportEventsCommand.php`
+- `src/Service/SoapClientService.php`
+
+Command: `nossener-land:export-events`
+
+Ablauf:
+
+1. Holt zukuenftige Events aus `tl_calendar_events` (derzeit `pid IN (1,2,3)` und `evlkscalendar != 1`).
+2. Mappt Eventdaten fuer EVLKS (inkl. Place-Mapping, Eventtyp, Personen/Kontakt, Zeiten).
+3. Exportiert per SOAP.
+4. Holt Remote-Events per JSON (`vid`) und loescht externe Events, die lokal nicht mehr im Exportlauf enthalten sind.
+
+Hinweis:
+
+- Das Place-Mapping ist statisch in `SoapClientService` hinterlegt.
+- Der SOAP-Zugang ist aktuell in `config/services.yml` konfiguriert.
+
+### 7) JSON-Export fuer Website/Consumer
+
+Datei: `src/Command/ExportEventsJsonCommand.php`
+
+Command: `nossener-land:export-eventstojson`
+
+Ablauf:
+
+1. Liest Events mit `export=1 AND published=1`.
+2. Wandelt `singleSRC` UUID in absolute URL um.
+3. Vergibt bei Bedarf Alias.
+4. Schreibt JSON nach:
+   - `/srv/www/ks-nossener-land/public/kirchspiel-nossener-land.de/public/events.json`
+
+## Voraussetzungen
+
+- Contao 5.7
+- PHP >= 8.3
+- Tabellen aus dem Umfeld von Catalog Manager, u. a.:
+  - `ctlg_orte`
+  - `ctlg_contacts`
+  - `ctlg_gemeinden`
+  - `ctlg_districts`
+  - `ctlg_angebote`
+- Netzwerkzugriff auf:
+  - EVLKS SOAP/JSON Endpunkte
+  - JSON-Quelle `ics.mummert.dev`
+
+## Konfiguration per Environment-Variablen
+
+Die folgenden Variablen werden fuer produktiven Betrieb erwartet:
+
+- `KS_NOSSENERLAND_SOAP_WSDL_URL`
+- `KS_NOSSENERLAND_SOAP_ENDPOINT_URL`
+- `KS_NOSSENERLAND_SOAP_API_KEY`
+- `KS_NOSSENERLAND_SOAP_VID`
+- `KS_NOSSENERLAND_KIRCHENJAHR_JSON_URL` (optional, Default vorhanden)
+- `KS_NOSSENERLAND_EXTERNAL_DB_DSN`
+- `KS_NOSSENERLAND_EXTERNAL_DB_USER`
+- `KS_NOSSENERLAND_EXTERNAL_DB_PASSWORD`
+
+Beispiel DSN:
+
+```text
+mysql:host=localhost;dbname=nossener-land_1;charset=utf8mb4
+```
+
+## Console-Commands (manuell)
+
+Im Contao-Projektverzeichnis ausfuehren:
+
+```bash
+php bin/console nossener-land:export-events
+php bin/console nossener-land:export-eventstojson
+```
+
+## Cronjobs
+
+Die folgenden Beispiele sind direkt anwendbar. Pfade bitte auf das jeweilige Projekt anpassen.
+
+### A) EVLKS-Export (inkrementell, inkl. Aufraeumen)
+
+Empfohlenes Intervall: alle 15 Minuten.
+
+```cron
+*/15 * * * * cd /srv/www/contao57 && /usr/bin/flock -n /tmp/ks-nossenerland-export-events.lock php bin/console nossener-land:export-events --env=prod --no-interaction >> var/log/cron-export-events.log 2>&1
+```
+
+Warum 15 Minuten:
+
+- gute Balance zwischen Aktualitaet und Last
+- robust bei redaktionellen Aenderungen waehrend des Tages
+- vermeidet zu haeufige externe API-Aufrufe
+
+Alternative Intervalle:
+
+- alle 5 Minuten: wenn sehr zeitkritische Publikation noetig ist
+- alle 30 Minuten: wenn Last reduziert werden soll
+
+### B) JSON-Export fuer externe Anzeige
+
+Empfohlenes Intervall: alle 30 Minuten.
+
+```cron
+*/30 * * * * cd /srv/www/contao57 && /usr/bin/flock -n /tmp/ks-nossenerland-export-json.lock php bin/console nossener-land:export-eventstojson --env=prod --no-interaction >> var/log/cron-export-json.log 2>&1
+```
+
+Warum 30 Minuten:
+
+- Daten aendern sich typischerweise weniger haeufig als EVLKS-Sync-Anforderungen
+- reduziert I/O und Dateischreiblast
+
+Alternative Intervalle:
+
+- stuendlich: fuer sehr geringe Aenderungsfrequenz
+- alle 10-15 Minuten: wenn JSON als nahezu Live-Feed genutzt wird
+
+### C) Startzeiten staffeln
+
+Empfehlung fuer stabilen Betrieb:
+
+- EVLKS-Export auf Viertelstunden
+- JSON-Export zeitversetzt, z. B. Minute 7 und 37
+
+Beispiel:
+
+```cron
+*/15 * * * * cd /srv/www/contao57 && /usr/bin/flock -n /tmp/ks-nossenerland-export-events.lock php bin/console nossener-land:export-events --env=prod --no-interaction >> var/log/cron-export-events.log 2>&1
+7,37 * * * * cd /srv/www/contao57 && /usr/bin/flock -n /tmp/ks-nossenerland-export-json.lock php bin/console nossener-land:export-eventstojson --env=prod --no-interaction >> var/log/cron-export-json.log 2>&1
+```
+
+## Empfohlene Betriebsregeln
+
+- Immer `flock` nutzen, um Ueberlappungen bei langen Laufzeiten zu verhindern.
+- Ausgabe in getrennte Logdateien schreiben.
+- Nach Deployment einmal manuell beide Commands ausfuehren.
+- Bei API-Problemen zuerst Logs pruefen und dann betroffene Command-Intervalle temporaer erhoehen.
+
+## Bekannte projektbezogene Punkte (kein Bugfix in diesem Schritt)
+
+- In `ExternalLocationModel` sind externe DB-Zugangsdaten fest hinterlegt.
+- `ExportEventsJsonCommand` nutzt einen fest codierten Zielpfad fuer `events.json`.
+- SOAP-API-Zugangsdaten liegen aktuell in `config/services.yml`.
+
+Diese Punkte sind bewusst unveraendert geblieben (Ziel: keine Funktionsaenderung beim Bundle-Umbau).