Notes¶

Polycrate verwendet ein einheitliches Note-Modell für alle Arten von textuellen Beiträgen: Hinweise, Todos, Kommentare, Meeting-Protokolle, Post-Mortems, Provider-Status-Meldungen und mehr. Das ganze System basiert auf einer Tabelle mit einem diskriminierenden Feld kind, das bestimmt, was die Note darstellt und welche Zusatzfelder relevant sind.

Damit sind Notes die gemeinsame Ablage für "alles, was man an ein Objekt oder Projekt heften kann".

Note-Kinds auf einen Blick¶

Alle Notes haben gemeinsam:

• Titel, Body (Markdown)
• Author: wer sie angelegt hat
• created_at / updated_at
• organization / workspace: der Kontext
• labels: freie Tags für Filter und Suche
• attachments: Dateien (S3) können angehängt werden

Erweiterungen pro Kind¶

Comments & Timetracking¶

Nur Notes mit kind=comment tragen das Feld time_tracked_hours. Eine "Kommentar-Note" ist damit gleichzeitig ein Zeitbuchungseintrag — z. B. "2h Ticket-Abarbeitung bei Kunde XYZ".

• time_tracked_hours ist ein Decimal-Feld.
• Optional FK project — damit wird die Stunde auf ein Projekt gebucht.
• Report-Endpunkte aggregieren die Summe pro User/Projekt/Zeitraum.

Todos¶

Eine Note mit kind=todo trägt:

• is_done: bool
• due_date: date (optional)

Im UI erscheinen offene Todos in einer eigenen Todo-Liste und werden mit der Erledigt-Quote pro Workspace als Metrik exportiert (siehe Prometheus-Metriken).

Post-Mortems¶

Ein Post-Mortem ist formal nur eine Note mit kind=post-mortem. Konvention:

• Titel trägt den Incident-Namen.
• Body folgt der internen Post-Mortem-Vorlage (Zeitachse, Root-Cause, Follow-Ups).
• Labels verlinken auf Incident-IDs und betroffene Systeme.

Über object-note-Attachments oder direkte Links lassen sich die ursächlichen Downtimes und Wartungen referenzieren.

Meeting Notes + Vydeo¶

Notes mit kind=meeting erhalten eine Vydeo-Integration:

• Beim Anlegen einer Meeting-Note wird (optional) ein Vydeo-Meeting-Raum erstellt.
• Die Note speichert den Meeting-Link.
• Teilnehmer sind über eine Many-to-Many-Relation zu User-Objekten abgebildet.
• Ein Sync-Task hält Teilnehmer-Listen und Anwesenheitsdaten zwischen Polycrate und Vydeo konsistent.

Damit ist eine Meeting-Note gleichzeitig Einladung, Protokoll und Archiv — alles an einer Stelle.

Embedded Object-Notes¶

Jedes ManagedObject (K8s-Cluster, S3-Bucket, LoadBalancer, Host, …) kann über EmbeddedNoteMixin eine angeheftete Note tragen (kind=object-note). Sie erscheint im Detail-View oben und dient als laufendes Protokoll:

• "Dieser Cluster läuft bis Q2/27, danach Migration auf aycloud."
• "Letzter Firmware-Upgrade am 2026-01-12; nächster spätestens in 6 Monaten."

Die Embedded-Note ist pro Objekt eindeutig und wird im UI als prominente Infobox angezeigt.

Provider-Status & News¶

Die beiden Kinds provider-status und news entstehen typischerweise automatisch aus einer DataSource:

• Ein RSS-Feed einer Provider-Statusseite wird auf eine DataSource mit provider_entity gelegt — erzeugte Notes bekommen kind=provider-status und eine Rückreferenz auf den Provider.
• Allgemeine News-Feeds (ohne Provider-Zuordnung) erzeugen Notes mit kind=news.

Über den datasource-FK an der Note lässt sich nachvollziehen, aus welchem Feed ein Eintrag stammt.

Zusammenhang zu Projekten und DataSources¶

                ┌─────────────┐
                │   Project   │
                └──────┬──────┘
                       │ FK: project
                       │
   ┌──────────────────▶│
   │                   │
┌──┴──┐   FK:       ┌──┴──┐  generic FK  ┌─────────────────┐
│Note │─────────────│Note │─────────────▶│  ManagedObject  │
│todo │             │comm │              │ (per Embedded/  │
└─────┘             │ ent │              │  object-note)   │
                    └──┬──┘              └─────────────────┘
                       ▲
                       │ FK: datasource
                       │
                ┌──────┴──────┐
                │ DataSource  │
                │ (rss/api)   │
                └─────────────┘

• Notes können an ein Projekt gehängt werden — pro Projekt entsteht so eine natürliche Pinnwand, auf der Todos, Kommentare und Post-Mortems versammelt sind.
• Notes können von einer DataSource erzeugt werden — dann trägt die Note einen datasource-FK und wir wissen, dass sie nicht von einem User stammt.
• Notes können an ein beliebiges ManagedObject heften — direkt (via object-note) oder indirekt über die generische ManagedObject-Referenz.

RBAC¶

Notes folgen dem allgemeinen RBAC-System:

• Wer Leserechte auf Organisation/Workspace hat, sieht alle zugehörigen Notes.
• Wer Schreibrechte hat, kann Notes erstellen, bearbeiten und löschen.
• Der Autor einer Note hat immer mindestens Lese-/Schreibrechte auf die eigene Note.
• Notes vom Kind provider-status und news sind read-only für Nicht-Superuser, weil ihre Quelle eine DataSource ist.

API-Endpunkte (kurz)¶

• GET /api/v1/notes/ — gefiltert nach workspace, kind, project, Autor, Label etc.
• POST /api/v1/notes/ — Note anlegen (inklusive Kind-spezifische Felder).
• Für Meetings: ein Unter-Endpunkt erzeugt oder aktualisiert den Vydeo-Meeting-Raum.
• Zeit-Reports: aggregierte Endpunkte fassen time_tracked_hours auf Comments zusammen.

Verwandte Themen¶

• Projekte — wie Projekte aggregierte Notes und Time-Tracking erhalten.
• DataSources — Herkunft von Feed-basierten Notes.
• PoPs & Provider — Kontext für Provider-Status-Notes.
• Downtime & Timeline — häufig Ziel von Post-Mortem-Notes.