Das KALENDER-Plugin zeigt die Termine Ihrer Mandanten-Daten zentral als
Unified Calendar (/kalender) in einem gemeinsamen 4-Wochen-Raster und
stellt die Termine über ICS-Feeds (ICS-Export, /kalender/export) für
externe Kalender-Programme bereit (Outlook, Apple Kalender, Google Kalender …).

Der Kalender ist ebenenbasiert (Layer): Jede Ebene stammt von einer
CalendarSourceProvider des jeweiligen Plugins und zeigt deren Termine
miteinander kombiniert:

• Verträge (Plugin VERTRAG) — Leihfristen als mehr-tägige Events
• Zeiterfassung (Plugin BUCHUNG) — Zeit-Einträge als Tages-Events

Weitere Plugins können über dieselbe CalendarSourceProvider-Schnittstelle
eigene Ebenen beisteuern (Details: How-To/PLUGIN-DEVELOPMENT.md, Abschnitt
„Einen Kalender beisteuern (Unified Calendar)").

> Der Kalender braucht keine eigene Datenbank-Tabelle – er liest direkt
> aus den Quell-Plugins. Voraussetzung ist mindestens ein aktives Plugin mit
> Kalender-Quelle (z. B. VERTRAG oder BUCHUNG).

• Kalenderansicht öffnen
• Ebenen (Layers) ein-/ausblenden
• ICS-Einstellungen (Sichtbarkeit, Felder) konfigurieren
• ICS-Feeds anlegen und verwalten (Kalender → ICS-Export)
• ICS-Link an Mitarbeiter geben, damit Outlook/Apple/Google die Termine zieht

1) Kalenderansicht

1. Kalender im Menü öffnen (/kalender).
2. Alle aktiven Ebenen erscheinen im 42-Tage-Raster: Verträge als
mehr-tägige Events, Zeiterfassung als Tages-Events.
3. Über die Layer-Leiste lassen sich Ebenen ein-/ausblenden — die
Einstellung wird pro User gespeichert (Pref `kalender.layer.
`,
z. B. kalender.layer.VERTRAG / kalender.layer.BUCHUNG). Standard ist
an.

> Zeiterfassung: Ohne die Berechtigung buchung.entry.view_all sieht ein
> User im Raster nur die eigenen Einträge; mit view_all die Einträge
> aller User (fremde Einträge sind im Subtitle mit dem User-Namen präfixiert).

2) ICS-Einstellungen

1. Admin → Kalender → ICS (/settings/admin/kalender/ics).
2. Konfigurieren Sie (Content-Settings, betreffen nur die Verträge-Ebene):

• welche Felder im Termin-Titel/-Body stehen (Include-Checkboxen:

Zweck, Mieter-Name, Mieter-Adresse, Zeitraum, Abholort, Rückgabeort,
Inventar-Liste, Techniker, Link)

• den LOCATION-Modus: Abholort / Rückgabeort / Mieter-Adresse / kein Ort
• die Base URL (daraus wird der Link zum Vertrag gebaut; leer = automatisch)

Weitere Ebenen (z. B. Zeiterfassung) werden generisch exportiert
(Titel, Datum, Link) — es gibt keine Filter nach Vertragstatus und
kein Zeitfenster. Die Einstellungen gelten global für alle Feeds der Verträge-Ebene (Kalender → ICS-Export).
3. Speichern (POST /settings/admin/kalender/ics).

> Hinweis: Diese Content-Settings betreffen alle Feeds. Die Vorschau
> gibt es jetzt pro Feed auf der ICS-Export-Seite (siehe Abschnitt 3).

3) ICS-Feeds anlegen und verwalten (Kalender → ICS-Export)

Die Export-Seite /kalender/export verwaltet die mandantenweiten Feeds
(Ansehen: Berechtigung kalender.kalender.view, Bearbeiten: Berechtigung
kalender.ics.edit):

• Mehrere benannte Feeds pro Tenant möglich – jeder Feed hat eine

eigene tokenbasierte URL und eine eigene Ebenen-Auswahl (standardmäßig
alle Ebenen).

• Dynamische Generierung: Der Feed-Inhalt wird **bei jedem Abruf frisch

generiert** – es gibt keine Feed-Datei mehr, die aktuell gehalten werden
müsste, und keinen AUTOMATE-Task mehr.

• Aktiv-Badge: grün „Aktiv", wenn der Feed in den letzten 7 Tagen

abgerufen wurde, sonst grau „Inaktiv" (Tooltip: letzter Abruf bzw.
„noch nie").

• Token-Rotation pro Feed (Berechtigung kalender.ics.edit): macht die

alte Feed-URL sofort ungültig (404).

• Legacy-Migration: Vorhandene K6-Feed-Tokens (Issue #351) werden

automatisch zum Feed „Standard-Feed" migriert – bestehende Abos
funktionieren weiter.

4) ICS in externen Kalender einbinden

Der Feed ist tokenbasiert – jede Feed-URL ist ein individueller, nicht ratbarer
Schlüssel (Issue #351):

`https://
/ical-feed/<32-hex-Token>
/calendar.ics`

1. Die Feed-URL unter Kalender → ICS-Export kopieren (Button „Kopieren“ am Feed).
2. Im externen Kalender als „Kalender-Abo“ oder „Internetkalender hinzufügen“ einfügen.
3. Outlook / Apple / Google aktualisieren die Termine periodisch automatisch – der Feed-Inhalt wird bei jedem Abruf aktuell generiert.

> Jeder Feed ist mandantenweit für seine gewählten Ebenen: alle Termine
> dieser Ebenen, ohne Monats- und User-Filterung — die Layer-Toggles des
> Users betreffen nur das Raster.
>
> Bei Apple-/Google-Kalendern dauert die Aktualisierung gelegentlich mehrere Stunden – das ist normal.
>
> Reimport nach Token-Rotation: „Token drehen“ macht die alte Feed-URL sofort
> ungültig (404). Betroffene Abonnenten müssen die neue Feed-URL erneut
> importieren – das ist der beabsichtigte Schutz: nur wer die URL hat, sieht
> die Termine.

5) Termine korrigieren

Termine kommen aus den Quell-Plugins. Wenn ein Termin im Kalender falsch ist,
korrigieren Sie ihn an der Quelle (z. B. am Vertrag, Plugin VERTRAG, oder
am Zeiteintrag, Plugin BUCHUNG), nicht am Kalender.

„Im externen Kalender erscheint nichts“

• Stimmt die ICS-URL?
• Liefert die Feed-URL etwas (im Browser öffnen)? Falscher Token → 404.
• Im externen Kalender Aktualisierung erzwingen.

„Es taucht ein alter Termin auf, den es längst nicht mehr gibt“

• Verträge soft-gelöscht? Der Feed-Inhalt wird bei jedem Abruf neu generiert –

der Termin verschwindet nach der nächsten Aktualisierung im externen
Kalender.

• Im externen Kalender manuell eine Aktualisierung erzwingen.

„Termin-Titel ist nichtssagend“

• ICS-Einstellungen → Titel-Feldformat anpassen.

„Ich sehe im Kalender nicht alle Zeiterfassung-Einträge“

• Ohne die Berechtigung buchung.entry.view_all sind nur eigene Einträge

sichtbar — das ist beabsichtigt. Wer alle Einträge sehen darf, benötigt die
Berechtigung (vergeben über ROLLEN).

„Eine Ebene fehlt im Kalender / im ICS“

• Im Raster fehlt sie? Ebene über die Layer-Leiste ausgeblendet? Pref

`kalender.layer.
` des Users prüfen (Standard ist an). Die
Layer-Toggles betreffen nur das Raster.

• Im Feed fehlt sie? Ebenen-Auswahl des Feeds prüfen (Kalender → ICS-Export,

Feed bearbeiten).

• Quell-Plugin im Tenant aktiviert? Nur aktive Plugins liefern Ebenen.

Nutzerbereich:

• GET /kalender – Unified-Calendar-Ansicht (Ebenen: Verträge, Zeiterfassung)
• POST /kalender/toggle-layer – Ebene ein-/ausblenden (Pref kalender.layer., nur aktive Provider)
• GET /kalender/export – ICS-Export-Seite (benannte Feeds, Ebenen-Auswahl, Vorschau)
• POST /kalender/export/create – Feed anlegen (Berechtigung kalender.ics.edit)
• POST /kalender/export/{uuid}/update – Feed umstellen (Name, Ebenen; Berechtigung kalender.ics.edit)
• POST /kalender/export/{uuid}/rotate-token – Feed-Token rotieren (alte URL → 404; Berechtigung kalender.ics.edit)
• POST /kalender/export/{uuid}/delete – Feed löschen (Berechtigung kalender.ics.edit)
• GET /kalender/export/{uuid}/preview – Feed-Vorschau (Berechtigung kalender.kalender.view)
• GET /ical-feed/{token}/calendar.ics – ICS-Feed (öffentlich, tokenbasiert, bei jedem Abruf dynamisch generiert, Issue #351)
• GET /ical/{filename:.+} – deaktiviert (404, altes öffentliches Format)

Admin:

• GET /settings/admin/kalender/ics – Content-Settings (Verträge-Ebene)
• POST /settings/admin/kalender/ics – Content-Settings speichern

• Jeder ICS-Feed ist mandantenweit für seine gewählten Ebenen: alle

Termine dieser Ebenen, ohne Monats- und User-Filterung. Der Feed-Inhalt
wird bei jedem Abruf aktuell generiert (keine Feed-Datei, kein
AUTOMATE-Task).

• Die Layer-Toggles im Kalender sind pro User (Pref kalender.layer.,

Standard an) und betreffen nur das Raster, nicht die Feeds; die
Ebenen-Auswahl pro Feed steht auf der Export-Seite (/kalender/export).

• Neue Ebenen kommen von CalendarSourceProvider-Beans der jeweiligen

Plugins — KALENDER selbst filtert nur nach Tenant und User-Prefs;
Sichtbarkeits-Logik (z. B. Zeiterfassung) bleibt im Quell-Plugin.

• KALENDER funktioniert mit den aktiven Plugin-Quellen (z. B. VERTRAG,

BUCHUNG).

• Legacy: Vorhandene K6-Feed-Tokens (Issue #351) werden automatisch zum

Feed „Standard-Feed" migriert – bestehende Abos und Feed-URLs bleiben
gültig, solange der Feed nicht gelöscht oder dessen Token gedreht wird.

• Die Feed-Verwaltung (Anlegen, Ebenen-Auswahl, Token-Rotation, Löschen,

Vorschau) läuft über die ICS-Export-Seite (/kalender/export). Der
frühere AUTOMATE-Task KALENDER_ICS (statische Feed-Datei) entfällt:
Feeds werden jetzt dynamisch pro Anfrage generiert.