Wartungsbanner

Das Wartungsbanner ermöglicht es Ihnen, Informationsbanner zu planen, die oben im Admin-Client für alle authentifizierten Benutzer angezeigt werden. Verwenden Sie es, um geplante Ausfallzeiten, Bereitstellungen oder andere systemweite Nachrichten anzukündigen.

Wartungsbanner vs Wartungsmodus

Wartungsbanner (diese Seite) zeigt ein ausblendbares Informationsbanner für Admin-Client-Benutzer an. Es beeinflusst nicht den Zugriff der Endbenutzer auf die Bots.

Wartungsmodus (siehe Bot-Einstellungen) deaktiviert einen bestimmten Bot für Endbenutzer auf öffentlichen Kanälen.

Funktionsweise

• Banner werden automatisch angezeigt, wenn active = true und die aktuelle Zeit vor scheduledEnd liegt.
• Jeder Benutzer kann ein Banner individuell ausblenden. Ausgeblendete IDs werden in localStorage gespeichert, sodass sie nach einem Seitenaktualisierung nicht erneut angezeigt werden.
• Banner werden über API-Endpunkte erstellt und verwaltet (siehe unten). Änderungen werden an alle verbundenen Clients weitergegeben, ohne dass eine Seitenaktualisierung erforderlich ist.

API-Referenz

Die vollständige Referenz für diese Endpunkte ist in der API-Dokumentation verfügbar.

Alle Verwaltungsschnittstellen erfordern einen API-Schlüssel mit der Rolle Admin. Der API-Schlüssel muss nicht auf einen bestimmten Bot beschränkt sein — er wird auf Mieterebene aufgelöst.

Fügen Sie den Schlüssel in jede Anfrage ein:

x-api-key: <your-api-key>

Siehe API-Schlüssel für Informationen zum Erstellen und Verwalten von API-Schlüsseln.

---

Datenmodell

Feld	Typ	Beschreibung
_id	string	MongoDB ObjectId der Nachricht
message	string	Bannertext, der den Benutzern angezeigt wird (mindestens 1 Zeichen)
scheduledStart	string (ISO 8601)	Wann das Banner relevant wird
scheduledEnd	string (ISO 8601)	Wann das Banner abläuft und nicht mehr angezeigt wird
active	boolean	Ob das Banner aktiviert ist. Standardmäßig true bei Erstellung
createdAt	string (ISO 8601)	Erstellungszeitstempel (automatisch generiert)
updatedAt	string (ISO 8601)	Letzter Aktualisierungszeitstempel (automatisch generiert)

---

GET /api/maintenance-messages/active

Gibt alle Banner zurück, die derzeit aktiv und noch nicht abgelaufen sind. Dieser Endpunkt wird vom Admin-Client beim Laden aufgerufen und erfordert keinen API-Schlüssel.

Antwort 200 OK

[
  {
    "_id": "6620a1b2c3d4e5f6a7b8c9d0",
    "message": "Geplante Wartung am Samstag, den 19. April von 02:00–04:00 UTC. Das System kann kurzzeitig nicht verfügbar sein.",
    "scheduledStart": "2026-04-19T02:00:00.000Z",
    "scheduledEnd": "2026-04-19T04:00:00.000Z",
    "active": true,
    "createdAt": "2026-04-15T10:00:00.000Z",
    "updatedAt": "2026-04-15T10:00:00.000Z"
  }
]

---

GET /api/maintenance-messages

Gibt alle Wartungsnachrichten für den Mieter zurück (einschließlich inaktiver und abgelaufener), sortiert nach Erstellungsdatum absteigend.

Authentifizierung: API-Schlüssel · Rolle: Admin

curl -X GET https://<your-domain>/api/maintenance-messages \
  -H "x-api-key: <your-api-key>"

Antwort 200 OK — Array von Wartungsnachrichtenobjekten (siehe Datenmodell oben).

---

POST /api/maintenance-messages

Erstellt ein neues Wartungsbanner.

Authentifizierung: API-Schlüssel · Rolle: Admin

Anfragekörper

Feld	Erforderlich	Beschreibung
message	ja	Textinhalt des Banners
scheduledStart	ja	ISO 8601 Datum und Uhrzeit — wann das Banner beginnen soll
scheduledEnd	ja	ISO 8601 Datum und Uhrzeit — wann das Banner abläuft

curl -X POST https://<your-domain>/api/maintenance-messages \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Geplante Wartung am Samstag, den 19. April von 02:00–04:00 UTC.",
    "scheduledStart": "2026-04-19T01:45:00.000Z",
    "scheduledEnd": "2026-04-19T04:00:00.000Z"
  }'

Antwort 201 Created — das erstellte Wartungsnachrichtenobjekt. Das Banner erscheint sofort für alle verbundenen Admin-Benutzer über SSE.

---

PATCH /api/maintenance-messages/:id

Aktualisiert ein bestehendes Wartungsbanner. Alle Felder sind optional — nur die bereitgestellten Felder werden aktualisiert.

Authentifizierung: API-Schlüssel · Rolle: Admin

URL-Parameter: id — die _id der Wartungsnachricht.

Anfragekörper (alle Felder optional)

Feld	Typ	Beschreibung
message	string	Aktualisierter Bannertext
scheduledStart	string (ISO 8601)	Aktualisierte Startzeit
scheduledEnd	string (ISO 8601)	Aktualisierte Endzeit
active	boolean	Auf false setzen, um ohne Löschen zu deaktivieren

# Deaktivieren Sie ein Banner sofort
curl -X PATCH https://<your-domain>/api/maintenance-messages/6620a1b2c3d4e5f6a7b8c9d0 \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

# Verlängern Sie die Endzeit eines Banners
curl -X PATCH https://<your-domain>/api/maintenance-messages/6620a1b2c3d4e5f6a7b8c9d0 \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "scheduledEnd": "2026-04-19T06:00:00.000Z" }'

Antwort 200 OK — das aktualisierte Wartungsnachrichtenobjekt. Verbundene Clients werden in Echtzeit über SSE aktualisiert.

Fehler 404 Not Found — wenn die Nachrichten-ID für den Mieter nicht existiert.

---

DELETE /api/maintenance-messages/:id

Löscht ein Wartungsbanner dauerhaft.

Authentifizierung: API-Schlüssel · Rolle: Admin

URL-Parameter: id — die _id der Wartungsnachricht.

curl -X DELETE https://<your-domain>/api/maintenance-messages/6620a1b2c3d4e5f6a7b8c9d0 \
  -H "x-api-key: <your-api-key>"

Antwort 200 OK

{ "success": true }

Verbundene Clients haben das Banner in Echtzeit über SSE aus ihrer Ansicht entfernt.

---

Tipps

• Setzen Sie scheduledEnd auf eine Zeit, die nach dem tatsächlichen Wartungsfenster endet, damit das Banner noch sichtbar ist, wenn das Fenster vorbei ist.
• Wenn Sie ein bereits aktives Banner stornieren müssen, PATCH es mit { "active": false } anstatt es zu löschen — dies bewahrt den Eintrag im Prüfprotokoll.
• Ausgeblendete Banner werden pro Browser in localStorage gespeichert. Wenn ein Benutzer die Site-Daten löscht, werden zuvor ausgeblendete Banner erneut angezeigt.