kita-planer/docs/NOTDIENSTALARM_PLAN.md

# Notdienstalarm – abgestimmter Funktionsplan

Stand: 09.10.2026 · Branch `codex/notdienstalarm`

Status: Umgesetzt. Dieser Plan hält die abgestimmten Entscheidungen fest. Bedienung, Betriebsanforderungen und Prüfungen stehen in [NOTDIENSTALARM.md](NOTDIENSTALARM.md).

## Festgelegter Umfang

| Thema | Entscheidung |
| --- | --- |
| Zuständigkeit | Nur Kita-Admins und Notdienst-Koordination (`ADMIN`, `KOORDINATOR`) lösen Alarme aus und verwalten sie. |
| Erste Empfänger | Ausschließlich die für das Datum im veröffentlichten Notdienstplan eingeteilte Familie. Alle Elternkonten dieses Haushalts werden einzeln angeschrieben. |
| Rückmeldung | „Wir übernehmen“ oder „Wir können nicht“. Eine Antwort gilt für den gesamten Haushalt. |
| Kanäle | E-Mail und ein deutlich sichtbarer Hinweis in der App. |
| Antwortfrist | Standardmäßig 30 Minuten ab Auslösung; beim Auslösen anpassbar. |
| Einsatzdauer | Wahl zwischen „Ganzer Kita-Tag“ und „Bestimmte Uhrzeiten“ mit Beginn und Ende. |
| Fehlende Übernahme | Absage sofort, ausbleibende Antwort nach Fristablauf: „Klärung erforderlich“. Koordination informieren; Ersatz manuell organisieren. |

## Ablauf in der Oberfläche

### 1. Alarm auslösen

Im veröffentlichten Notdienstplan erhält die Einteilung eine Aktion **Notdienstalarm auslösen**. Eine aktuelle Alarmübersicht ist zusätzlich über das Dashboard erreichbar.

Der Dialog zeigt Datum, eingeteilte Familie und deren Empfängeradressen. Die auslösende Person wählt die Einsatzdauer, prüft die Antwortfrist und bestätigt den Versand. Bei **Bestimmte Uhrzeiten** sind Beginn und Ende Pflicht; Ende liegt nach Beginn. Bei **Ganzer Kita-Tag** sind keine künstlichen Uhrzeitangaben nötig. Die gewählte Dauer erscheint in der E-Mail und auf der Rückmeldeseite.

Ein Alarm ist nur für heutige oder zukünftige Einteilungen eines veröffentlichten Plans der eigenen Kita möglich. Notdienst muss für die Kita aktiviert sein. Fehlende Elternkonten werden vor der Auslösung deutlich angezeigt. Eine aktive Alarmierung verhindert einen zweiten Alarm für dieselbe Einteilung.

Optional kann die ausgefallene Fachkraft intern zugeordnet werden. Dies dient der Zuordnung und erzeugt keine automatische Krankheitsbuchung im Personalbereich. Private interne Notizen und Namen ausgefallener Fachkräfte gehören nicht in die Eltern-E-Mail.

### 2. Familie informieren und Antwort erfassen

Jedes Elternkonto erhält eine eigene E-Mail mit Kita, Datum, Einsatzdauer, Antwortfrist und persönlichem Rückmeldelink. Die Nachricht fragt eindeutig nach einer Übernahme. Alle Elternkonten des Haushalts sehen in der App denselben aktiven Alarm.

Die Rückmeldeseite funktioniert wie bisher ohne Login über einen persönlichen Token. Das Öffnen des Links löst keine Zusage aus. Erst die ausdrückliche Auswahl von **Wir übernehmen** oder **Wir können nicht** mit Bestätigung schreibt die Antwort.

Die Antwort wird am gemeinsamen Haushaltseinsatz gespeichert, einschließlich Zeitpunkt und antwortendem Elternkonto. Alle anderen Links zeigen anschließend die gemeinsame Antwort. Gleichzeitige gegensätzliche Antworten dürfen nicht beide wirksam werden. Eine bereits gespeicherte Antwort lässt sich nicht versehentlich durch einen zweiten Klick überschreiben.

### 3. Stand verfolgen und Ersatz klären

Die Alarmübersicht zeigt Datum, Dauer, Familie, Antwortfrist, gemeinsamen Rückmeldestatus und den Versandstand je Empfänger. Offene Alarme für heute werden besonders hervorgehoben.

| Anzeige | Bedeutung und nächste Aktion |
| --- | --- |
| Antwort ausstehend | Familie wurde angefragt; die Antwortfrist läuft. |
| Übernahme bestätigt | Der Haushalt hat rechtzeitig zugesagt. Koordination und Admins sehen die Zusage. |
| Klärung erforderlich – Absage | Der Haushalt kann nicht übernehmen. Koordination organisiert Ersatz. |
| Klärung erforderlich – Frist abgelaufen | Es liegt keine Antwort vor. Koordination fasst nach oder organisiert Ersatz. |
| Storniert | Einsatz entfällt; Rückmeldelinks erlauben keine weitere Antwort. |

Versandfehler sind ein eigener Zustand und dürfen nicht als Absage der Familie erscheinen. Eine fehlgeschlagene E-Mail wird deutlich angezeigt und kann erneut versendet werden; andere Empfänger werden trotzdem bedient.

Bei Absage oder Fristablauf erhalten zuständige Koordinations- und Admin-Konten derselben Kita einen Hinweis in der App und eine E-Mail. Die Fristmeldung wird je Alarm einmal erzeugt. Die Koordination organisiert Ersatz in dieser Version manuell; weitere Familien werden nicht automatisch alarmiert.

## Vorgeschlagene Ausgestaltung für Sonderfälle

Diese Details ergänzen die Nutzerentscheidungen als Umsetzungsvorschlag:

- **Verspätete Zusage:** Nach Fristablauf bleibt eine Rückmeldung möglich, solange der Einsatz läuft und der Alarm nicht storniert ist. Eine verspätete Zusage wird als solche angezeigt und muss von der Koordination bestätigt werden, damit sie nicht mit bereits organisiertem Ersatz kollidiert.
- **Telefonische Rückmeldung:** Admin oder Koordination kann eine Zusage bzw. Absage für den Haushalt dokumentieren. Herkunft, handelndes Konto und Zeitpunkt bleiben nachvollziehbar.
- **Antwort ändern:** Eine bereits dokumentierte Antwort wird nur durch Admin oder Koordination korrigiert. Eltern erhalten auf der Rückmeldeseite einen Hinweis, die Kita bei Änderungen zu kontaktieren.
- **Stornieren:** Admin oder Koordination storniert mit einer internen Begründung. Alle angeschriebenen Elternkonten werden informiert; offene Links werden unwirksam. Eine neue Alarmierung derselben Einteilung ist danach als neuer Vorgang möglich.
- **Token-Ende:** Für einen ganzen Kita-Tag endet die Rückmeldemöglichkeit spätestens mit dem Datum in Europe/Berlin; bei bestimmten Uhrzeiten mit dem Einsatzende. Die 30-Minuten-Frist für Eskalation ist davon unabhängig.
- **Planänderungen und Tausch:** Aktive Alarme schützen die zugehörige Einteilung vor einem unbemerkten Familienwechsel oder Diensttausch. Ersatz darf nicht durch Änderung eines noch aktiven Alarms auf eine andere Familie übertragen werden.
- **Erinnerung und erneuter Versand:** Eine Wiederholung startet die Antwortfrist nicht automatisch neu. E-Mail-Annahme durch den Versanddienst, Rückmeldung und tatsächliche Anwesenheit bleiben getrennte Informationen.

## Technische Umsetzung

Der bestehende `NotdienstAlert` speichert pro Elternkonto einen unabhängigen Status. Für die gemeinsame Haushaltsantwort wird ein übergeordneter Alarmvorgang benötigt; Empfänger, Tokens und Versandversuche sind untergeordnet. Bestehende Datensätze müssen bei der Schemaumstellung berücksichtigt werden, ohne widersprüchliche Einzelantworten als sichere Haushaltszusage zu übernehmen.

Am Vorgang werden Einteilung und Haushalt, auslösendes Konto, Zeitpunkt, Einsatzart, gegebenenfalls Uhrzeiten, Antwortfrist, gemeinsame Antwort, interne Zuordnung und Stornierungsdaten festgehalten. Empfängerdatensätze führen persönliche Tokens und deren Gültigkeit. Historie und Versandaufträge erlauben Wiederholung und nachvollziehbare Änderungen.

Alle Aktionen prüfen aktuelle Datenbankrolle, Kita-Zugehörigkeit und Zugriff serverseitig. Auslösung und gemeinsame Rückmeldung laufen transaktional. Eine Datenbanksicherung verhindert mehrere aktive Alarme für dieselbe Einteilung sowie widersprüchliche parallele Antworten.

Der Versand verwendet die vorhandene Resend-Anbindung mit persistenten Versandaufträgen. Elternmails enthalten ausschließlich notwendige Einsatzdaten. Interne Begründungen, Krankheitsdetails und Daten aus Personalzeitkonten werden nicht übernommen. Alarm-E-Mails sind unabhängig von der Abschalteinstellung für Personal-Entscheidungsmails.

Die Fristüberwachung braucht eine regelmäßig aufgerufene serverseitige Prüfung, auch wenn niemand die App geöffnet hat. Vorgesehen ist ein geschützter, einmal pro Minute aufgerufener Serverjob. Die Anzeige berechnet Fristablauf zusätzlich direkt aus der gespeicherten Antwortfrist. Die Benachrichtigung kann durch das Prüfintervall und den Mailtransport etwas nach Ablauf eintreffen. Für die Einführung muss der Job in der Hosting-Umgebung eingerichtet werden.

## Umsetzungsschritte

1. Gemeinsamen Alarmvorgang, Empfänger, Tokens, Verlauf und Schemaumstellung ergänzen.
2. Auslösung, Haushaltsantwort, Korrektur, Stornierung und erneuten Versand absichern.
3. E-Mail-Vorlagen, Versandaufträge und Benachrichtigung der Koordination anbinden.
4. Alarmdialog, Rückmeldeseite, Dashboard-Hinweise und Statusübersicht umsetzen.
5. Fristprüfung, Hosting-Konfiguration und Einführungsdokumentation ergänzen.
6. Gemeinsame Haushaltsantworten, Fristen, Rollen, Versandfehler und Browserabläufe prüfen.

## Abnahmefälle

- Admin und Koordination dürfen auslösen; Eltern, Fachkräfte und Konten anderer Kitas dürfen es nicht.
- Nur die im veröffentlichten Plan eingeteilte Familie wird zunächst angeschrieben.
- Ganzer Kita-Tag und bestimmte Uhrzeiten erscheinen in E-Mail, App und Rückmeldeseite konsistent.
- Eine Zusage oder Absage wirkt auf den gesamten Haushalt; weitere persönliche Links zeigen denselben Stand.
- Zwei gleichzeitige Antworten, doppelte Auslösung und Fristprüfung erzeugen keine doppelten Vorgänge oder widersprüchlichen Zusagen.
- Absage erzeugt sofort Klärungsbedarf; Fristablauf nach 30 Minuten erzeugt ihn auch bei geschlossener App.
- Versandfehler verhindern keine Speicherung, unterbrechen nicht den Versand an weitere Empfänger und lassen sich gezielt wiederholen.
- Verspätete Antwort, telefonisch dokumentierte Antwort und Stornierung bleiben nachvollziehbar.
- Stornierte und zeitlich abgelaufene Links können keinen aktiven Einsatz zusagen.
- Aktive Alarme schützen Einteilungen vor unbemerktem Tausch oder Familienwechsel.

## Vorhandene Grundlage

- `src/app/dashboard/actions.ts`: Auslösung und E-Mail-Versand, bisher ein separater Alarm pro Elternkonto.
- `src/app/dashboard/alert-button.tsx`: Vorbereiteter, noch nicht eingebundener Auslösebutton.
- `src/app/alert/[token]/`: Rückmeldeseite und Bestätigung, bisher nur Zusage und ohne zeitliche Token-Gültigkeit.
- `src/app/dashboard/kalender/actions.ts`: Bestehender Tauschausschluss für aktive Alarmierungen.
- `src/lib/mail.ts` und `src/lib/staff/email.ts`: Mailtransport sowie Vorlage für persistente, wiederholbare Versandaufträge.

Die Planung löst keine Alarme aus und versendet keine E-Mails.