Wartungen¶

Eine Wartung (Maintenance) ist ein konkretes, geplantes Event mit Start- und Endzeitpunkt — zum Beispiel "PostgreSQL 15 → 16 Upgrade am 2026-04-22 02:00 bis 04:00 UTC". Wartungen informieren Benutzer proaktiv, werden in der Downtime-Timeline sichtbar und sind die bevorzugte Art, angekündigte Ausfälle von ungeplanten Störungen zu unterscheiden.

Wartungen ≠ Wartungsfenster

Die Wartung (dieses Dokument) ist ein einzelnes, datiertes Event. Das Wartungsfenster ist hingegen eine Policy/Vorlage für erlaubte Wartungsslots (z. B. "jeden Sonntag 02:00–04:00"). Beide Modelle sind getrennt und können, müssen aber nicht, zusammen benutzt werden.

Kernfelder¶

Feld	Bedeutung
`name` / `display_name`	Titel der Wartung
`message`	Beschreibung / Hinweis an Betroffene
`scheduled_start` / `scheduled_end`	Geplanter Zeitraum
`progress_status`	Lebenszyklus — `draft`, `scheduled`, `running`, `completed`, `cancelled`
`draft`	Boolean: `true` unterdrückt Benachrichtigungen (Vorbereitung)
`workspace`	Optional — schränkt den Scope auf einen Workspace ein
`pop`	Optional — schränkt den Scope auf einen PoP ein
`reference_url`	Optional — Link zum Change-Ticket, Playbook o. ä.

Eine Wartung ist immer auf eine Organisation gescoped. workspace und pop sind zwei unabhängige Filter und beide optional.

Kein generischer Ressourcen-M2M

Eine Wartung hat keine Many-to-Many-Relation zu einer freien Liste "betroffener Ressourcen". Der Scope wird über Workspace und/oder PoP festgelegt. Alle Ressourcen, die zum ausgewählten Workspace und/oder PoP gehören, gelten als betroffen. Wer eine feinere Auswahl braucht, legt mehrere Wartungen an.

Lebenszyklus¶

┌────────┐  publish  ┌───────────┐  scheduled_start  ┌─────────┐
│ draft  │──────────▶│ scheduled │──────────────────▶│ running │
└────────┘           └─────┬─────┘                   └────┬────┘
                           │                              │
                           │   cancel                     │ scheduled_end
                           ▼                              ▼
                      ┌──────────┐                  ┌───────────┐
                      │ cancelled│                  │ completed │
                      └──────────┘                  └───────────┘

draft — Die Wartung ist angelegt, aber noch nicht sichtbar für Empfänger. Keine Benachrichtigungen werden versendet.
scheduled — Veröffentlicht; Benachrichtigungen und Timeline-Eintrag entstehen.
running — scheduled_start erreicht; Downtime wird im Dashboard als geplante Phase markiert.
completed — scheduled_end erreicht oder manuell abgeschlossen.
cancelled — Vor Ausführung abgesagt.

Der Übergang zwischen den Phasen erfolgt teils automatisch (Scheduler-Task) und teils manuell (Buttons "Publish", "Cancel", "Close").

Benachrichtigungen¶

Das System erzeugt typisierte Activities, die in Notification-Kanäle laufen:

Activity	Wann	Empfänger
`maintenance_scheduled`	Beim Veröffentlichen aus `draft`	Alle Kontakte des Scopes
`maintenance_started`	Beim Erreichen von `scheduled_start`	Alle Kontakte des Scopes
`maintenance_ended`	Beim Erreichen von `scheduled_end`	Alle Kontakte des Scopes

Wer genau benachrichtigt wird, ergibt sich aus den Contacts auf Organisation/Workspace-Ebene und deren Notification-Präferenzen (E-Mail, Webhook, …).

Draft bleibt still

Solange draft=true, werden keine Benachrichtigungen ausgelöst — egal ob Start oder Ende ankommt. Das ist gewollt, damit Wartungen in Ruhe vorbereitet werden können.

Darstellung in der UI¶

Wartungs-Liste: Ansicht aller Wartungen im Workspace mit Filtern nach Status, PoP, Zeitraum. Drafts sind farblich markiert.
Wartung-Detail: Zeigt Metadaten, Beschreibung, Scope (Workspace/PoP), Activity-Trail (Benachrichtigungen) und Links zu verbundenen Downtimes.
Downtime-Timeline: In der Downtime-Timeline erscheinen Wartungen als geplante Blöcke, deutlich abgegrenzt von ungeplanten Downtimes. Überschneidungen werden visualisiert.
Dashboard: Eine "Nächste Wartungen"-Liste in Organisation- und Workspace-Dashboards zeigt die kommenden Events.

Praxis: Typische Abläufe¶

Geplante Upgrade-Wartung¶

Anlegen einer Wartung als draft mit Titel, Beschreibung, Zeitfenster, Workspace-Scope.
Publish: Alle Kontakte erhalten maintenance_scheduled. Die Wartung taucht auf der Timeline auf.
Durchführen: Das Team arbeitet im Zeitfenster. Falls Alerts während der Wartung auslaufen, sind sie in der Timeline klar als "während geplanter Wartung" markiert.
Ende: Scheduler beendet die Wartung automatisch; maintenance_ended wird verschickt.

Kurzfristige Absage¶

Falls eine Wartung vor Start abgesagt werden muss, wechselt sie auf cancelled. Es gibt keinen separaten "Cancelled"-Notification-Typ; stattdessen werden die Empfänger über die Standard-Update-Activity informiert.

Post-Mortem zur Wartung¶

Wenn während einer geplanten Wartung unerwartete Probleme auftreten, wird eine Note vom Kind post-mortem verfasst und über Links der Wartung und eventuellen Downtimes zugeordnet (siehe Notes → Post-Mortems).

API-Endpunkte¶

GET /api/v1/maintenances/ — Liste (Filter: workspace, pop, progress_status, Zeitraum)
POST /api/v1/maintenances/ — Anlegen (standardmäßig als draft)
PATCH /api/v1/maintenances/{id}/ — Bearbeiten
POST /api/v1/maintenances/{id}/publish/ — aus draft veröffentlichen
POST /api/v1/maintenances/{id}/cancel/ — Absagen

DRF-Router-Basename: maintenance. (Getrennt vom Basename maintenancewindow für Wartungsfenster.)

RBAC¶

Lesen: Wer Leserechte auf den Scope (Workspace/PoP/Organisation) hat, sieht die Wartung.
Anlegen/Bearbeiten: Eigene Permission maintenance.change_maintenance — typisch für Plattform-Admins und On-Call-Teams.
Publish/Cancel: Separate Berechtigungen, damit ein Operator einen Entwurf vorbereiten kann, aber nur ein berechtigter Ops-Lead den "Publish"-Knopf drückt.