ks-nossenerland-bundle/README.md

# 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).