Vom JSON zum privaten Report

Diesen Beitrag anhören (14 Min.)

Angenommen, jemand zweifelt eine Zahl auf einer privaten Report-Seite an – etwa die Zahl der Workflow-Läufe in der abgeschlossenen Stunde. Existiert diese Zahl nur im gerenderten HTML, liefert die Seite selbst keinen belastbaren Herkunftsnachweis; ein späterer Abruf der Produkt-APIs kann bereits andere Daten liefern. Genau dieser Prüffall bestimmt die Architektur, die dieser Artikel beschreibt: Ein privater Report beginnt hier nicht als Seite. Zuerst entstehen Quell-Snapshots, danach ein gemeinsamer Faktensatz, eine Analyse und ein Manifest; erst wenn diese Artefakte ihre Schemas, Hashes und Zeitgrenzen erfüllen, wird daraus eine ContentKit-Revision. Diese Kette ist eine Entwurfsentscheidung der hier beschriebenen Installation, kein Produktvertrag. Sie erlaubt später zu prüfen, ob der für den Report verwendete Faktensatz noch zu dem im Manifest gespeicherten Hash passt; eine Herkunftsreferenz für jeden einzelnen Messwert behauptet sie nicht.

Eine fehlerhafte Überschrift erfordert keinen neuen Abruf aller Produkt-APIs. Eine geänderte Analyse kann gegen denselben Faktensatz geprüft werden. Rohdaten und redaktionelle Aussage bleiben getrennt prüfbar, auch wenn ContentKit daraus eine gemeinsame Report-Seite rendert.

Fünf Artefaktarten statt einer großen Datei

Gezählt werden fünf Artefaktarten im Bucket: Quell-Snapshots, Faktensatz, Analyse, Manifest und Latest-Pointer. Die ContentKit-Revision ist keine sechste Bucket-Artefaktart, sondern ein nachgelagertes ContentKit-Artefakt; veröffentlicht wird sie über einen Release. Sie entsteht aus dem Report-Dokument, das die Pipeline aus den geprüften Artefakten erzeugt. In der hier beschriebenen Pipeline erhält jede abgeschlossene Stunde einen eigenen Pfad im privaten Bucket. Die Quellen bleiben getrennt, damit ein Ausfall oder eine Schemaänderung einem Produkt zugeordnet werden kann. Der Faktensatz normalisiert nur jene Felder, die für die gemeinsame Auswertung benötigt werden. Die Analyse benennt Befunde und Lücken. Das Manifest verbindet alles über Pfade, Größen und Hashes und ermöglicht damit die Prüfung, ob alle von ihm erwarteten Artefakte vorhanden sind und zu den angegebenen Hashes passen. Ein kleiner Latest-Pointer verweist auf den neuesten vollständigen Stand; er enthält nicht den Report und überschreibt keine Historie.

flowchart LR
    S["Source Snapshots"] --> F["Fact Set"]
    F --> A["Analysis"]
    S --> M["Manifest<br/>paths · bytes · hashes"]
    F --> M
    A --> M
    M --> P["Latest Pointer"]
    M --> C["ContentKit-Revision"]

Diese Aufteilung ähnelt einem kleinen Build. Eingaben, abgeleitete Daten und veröffentlichte Ausgabe haben getrennte Lebenszyklen. Keine Datei muss gleichzeitig Rohquelle, Analyseprotokoll und UI-Modell sein.

Was sich seit damals geändert hat

Der ältere Beitrag Markdown Reports statt Dashboard-Zwang hat den Report als versioniertes, diffbares Artefakt beschrieben. Damals war die zentrale Abgrenzung: Eine laufend neu berechnete Ansicht beantwortet eine andere Frage als ein festgehaltener Stand. Markdown war das Mittel, um eine Auswertung lesbar, archivierbar und vergleichbar zu machen.

Diese Grundidee ist unverändert. Neu ist, dass der Text weder das einzige Artefakt noch der Beginn der Kette ist. Vor dem Markdown liegen ein maschinenlesbarer Faktensatz, eine getrennte Analyse und ein prüfbares Manifest. Der Report kann dadurch ansprechend dargestellt werden, ohne selbst zur einzigen Wahrheit zu werden. Ein Diagramm ist eine Ansicht auf Zahlen, nicht ihr Ursprungsort.

Auch die Veröffentlichung ist konkreter geworden. Die Pipeline nutzt Revisionen und Releases heute für regelmäßig erzeugte private Reports. Report-Seiten tragen Frage, Schlussfolgerung, Handlung und semantische Messwerte in einem Dokument; ContentKit erzeugt daraus die responsive Seite und eine begrenzte unveränderliche Historie. Wie weit diese Historie zurückreicht, ist damit nicht zugesichert; für ältere Stände bleibt der Bucket-Bestand die Referenz, soweit ihn die vereinbarte Retention erhält. Der Weg sieht heute so aus:

closed time window
  -> immutable JSON artifacts
  -> validated Markdown revision
  -> authenticated release
  -> readable report with source trail

Neu ist vor allem eine Prüfebene: Der Faktensatz, aus dem die Seite erzeugt wurde, lässt sich gegen den im Manifest gespeicherten Hash prüfen. Selbst wenn sich Layout, Farben oder Renderer später ändern, bleiben Manifest und Faktensatz innerhalb der vereinbarten Aufbewahrungsfrist erhalten. Der alte Artikel fragte: „Wie sah der Report damals aus?“ Die heutige Kette kann zusätzlich beantworten: „Aus welchen zu diesem Manifest passenden Daten wurde er gebaut?“

Das Manifest macht eine Stunde prüfbar

Ein Dateiname allein beweist nicht, dass ein Objekt vollständig geschrieben wurde. Das Manifest wird in dieser Pipeline zuletzt erzeugt und enthält für jedes vom Manifest referenzierte Stundenartefakt den erwarteten SHA-256-Hash. Ein Leser prüft erst das Manifest und danach die referenzierten Objekte. Der Latest-Pointer wird erst aktualisiert, wenn sämtliche referenzierten Objekte lesbar und gültig sind. Dadurch kann ein abgebrochener Lauf einzelne neue Dateien hinterlassen, ohne den zuletzt bekannten vollständigen Stand zu beschädigen. Weil das Manifest im selben Speicher liegt wie die Artefakte, beweist es weder Herkunft noch einen früheren Zustand; es leistet eine Integritätsprüfung – passen die Objekte vollständig und unverändert zu genau diesem Manifest.

Die Validierung prüft mehr als Datentypen, aber nicht alles davon leistet JSON Schema selbst. Dass das Zeitende nach dem Zeitbeginn liegt, stellt in dieser Pipeline eine zusätzliche Anwendungsvalidierung sicher; Produktnamen aus einer bekannten Menge und Pflichtfelder für Befunde – Schweregrad, Belegreferenzen, ein verständlicher Text – stehen im Schema. Unerwartete zusätzliche Felder können abgelehnt werden, damit ein versehentlich übernommenes internes Objekt nicht still im Bucket landet.

Die Ablage liegt in dieser Pipeline in einem privaten Bucket hinter einem S3-kompatiblen Endpunkt. Der Endpunkt bietet hier keine S3-Versionierung; die Unveränderlichkeit entsteht deshalb durch zeit- oder inhaltsgebundene Objektnamen und die Anwendung, nicht durch eine Bucket-Funktion. Ein veröffentlichter Stundenpfad wird nicht inhaltlich umgedeutet. Eine Korrektur erhält eine nachvollziehbare neue Revision oder einen neuen Artefaktpfad. Die Storage-Credentials liegen als Credential der Orchestrierung vor – nicht in der Workflowdefinition, nicht im Manifest und nicht im ContentKit-Dokument.

ContentKit veröffentlicht, speichert aber nicht die Fakten neu

In dieser Pipeline liest der Report-Workflow Faktensatz und Analyse über einen privaten Connector und erzeugt daraus Markdown. ContentKit erzeugt aus dem Report-Dokument die Seite, hält Revision und Release und regelt den Lesezugriff. Der Bucket bleibt die maschinenlesbare Übergabe; die ContentKit-Revision ist die lesbare Fassung.

---
kind: page
layout: composition
composition:
  format: report
  intent: status
  question: Did the latest closed hour complete, and does an exception require action?
  thesis: The closed hour is complete and no selected failure counter is above zero.
  conclusion: No technical intervention is required for this window.
  action: Review the next closed hour.
reportCadence: hourly
title: Hourly Report 2026-07-18 14:00 UTC
locale: en
slug: report-2026-07-18-14
---

::metric{label="Workflow runs" value="11" period="closed hour" tone="neutral"}

Der Markdown-Vertrag ist bewusst kleiner als eine Chart-Bibliothekskonfiguration. Er beschreibt Bedeutung und Erzählabsicht – Frage, These, Schlussfolgerung, Handlung – aber keine Koordinaten. Kennzahlen, Status und Tabellen entstehen aus kontrollierten Direktiven; ContentKit löst daraus Komposition, Layout und Ausgabe auf.

Die Trennung hilft auch bei fehlenden Daten. Der Generator kann einen Abschnitt als unavailable markieren und erklären, warum. ContentKit entscheidet nicht, ob ein Wert fachlich fehlt; es stellt den geprüften Text und die vorhandenen Zahlen zuverlässig dar.

Zugriff gilt auf jeder Route, nicht nur auf der HTML-Seite

Eine nicht verlinkte URL ist kein Zugriffsschutz. Wer eine Seite lediglich aus der Navigation entfernt, hat ihre Erreichbarkeit nicht verändert – nur ihre Auffindbarkeit über die Navigation. Privat bedeutet mehr: Auch Suche, Feeds, Maschinenausgaben und Medien müssen dieselbe Freigabegrenze beachten.

ContentKit modelliert das über release-gebundene Regeln. Einzelne Dokumente, Pfadbereiche und Medien werden geschützt; geschützte Titel und Inhalte bleiben vor der Anmeldung aus Navigation, Suche, Sitemap, Feeds, llms.txt und JSON-LD ausgeschlossen. Weil die Zugriffsregel Teil des Releases ist, wechseln Seite und Sichtbarkeit gemeinsam.

flowchart TD
    Q["Request"] --> T{"Welche Route?"}
    T -->|geschütztes Objekt| G{"Zugriffsregel erfüllt?"}
    G -->|nein| L["Login oder abgelehnt"]
    G -->|ja| O["HTML, Markdown oder Medien"]
    T -->|öffentliche Discovery| S["Antwort ohne geschützte Einträge"]

Genauso wichtig ist die Trennung der Zugänge. Das ContentKit-Cockpit ist der menschliche Verwaltungszugang zu Revisionen und Releases – mit einer Browser-Sitzung und den Rechten einer Person. Automatisierte Leser laufen nicht über diesen Weg. Ein Site-gebundener Maschinenzugang mit content:read kann denselben privaten, unveränderlichen Release lesen, ohne eine Browser-Sitzung oder Publisher-Rechte zu erhalten. Ein Auswertungsagent, der den Stundenreport der Vorwoche zitieren soll, braucht Lesezugriff auf genau diese Site – nicht die Fähigkeit, Releases zu aktivieren oder Regeln zu ändern. Browser-Sitzung und Maschinenschlüssel werden getrennt authentifiziert und berechtigt.

Der Produktionstest dieser Installation folgt dieser Logik – als lokale Testsuite, nicht als Produktzusage. Er beginnt anonym: Die geschützte Startseite muss zum Login führen, direkte Objektwege müssen ohne Anmeldung scheitern, und öffentliche Discovery-Ausgaben dürfen geschützte Einträge nicht enthalten. Danach meldet er sich als echter Leser an und öffnet Startseite und Report. Ein HTTP 200 auf der gerenderten Seite beweist noch keinen vollständigen Schutz – erst die Kombination aus anonymer Ablehnung auf den tatsächlich geprüften Objektrouten, gefilterten öffentlichen Ausgaben und authentifiziertem Erfolg trägt diese Aussage, und auch nur für diese Routen.

Wie man einen Report liest

Eine private Auswertung soll nicht voraussetzen, dass jemand die gesamte Architektur kennt. Deshalb beginnt jeder Report mit einer kurzen Einordnung des Zeitraums und der Datenlage. Vier Anforderungen muss er dafür erfüllen.

Erstens muss der Zeitraum eindeutig sein. Bei einem Stundenreport sind das etwa 14

bis 15

UTC – nicht die seit 15

eingetroffenen Ereignisse. Der Zeitstempel beschreibt das Datenfenster, nicht den Moment des Seitenbaus.

Zweitens muss die Datenlage sichtbar sein. Eine grün gemeldete technische Ausführung bedeutet noch nicht, dass jede Produkt-API verwertbare Daten geliefert hat. Der Bereich Datenqualität nennt vorhandene, fehlende und veraltete Quellen getrennt. Unavailable bedeutet, dass für diese Aussage gerade eine belastbare Beobachtung fehlt; daraus darf kein Wert 0 abgeleitet werden.

Drittens muss der Report Messung und Einordnung trennen. Metrikkarten und Tabellen stammen aus dem validierten Faktensatz. Befunde fassen mehrere Fakten zusammen oder weisen auf eine auffällige Veränderung hin – mit Belegreferenzen. So bleibt eine Einordnung nützlich, ohne mit einem gemessenen Wert verwechselt zu werden.

Viertens muss erkennbar sein, ob etwas folgen soll. Dieser stündliche Report löst selbst keinen Alarm aus. Ein einzelner Ausschlag darf sichtbar bleiben, ohne sofort eine Handlung auszulösen. Erst wiederholte Lücken, nachvollziehbare Trends oder klar formulierte Befunde werden zu Kandidaten für eine Entscheidung. Das hält die Seite ruhig genug für regelmäßiges Lesen und konkret genug für eine spätere Prüfung.

Kurze Hinweise direkt an Tabellen und Diagrammen benennen, was gezeigt wird und wie fehlende Daten zu verstehen sind. Gerade bei wöchentlichen oder jährlichen Berichten zählt das: Wer sie selten öffnet, sollte die Bedeutung einer Farbe nicht erst rekonstruieren müssen.

Eine Reportseite kann valide sein und trotzdem ins Leere laufen: wenn die Startseite sie nicht auflistet, wenn in einer Berichtsreihe ein Zeitraum fehlt oder wenn gemischte Datumsformate die Sortierung der Karten verfälschen. Deshalb gehört Navigation in dieser Installation zur geprüften Erwartung. Die Startseite führt die Zeiträume mit jeweils dem neuesten privaten Report auf und trennt sie vom Stundenverlauf. Der Test prüft nicht Linktexte, sondern Verhalten: höchstens eine aktuelle Karte pro Berichtsreihe, ein Link auf einen geschützten 200-Report und eine Sortierung nach Reportdatum.

Löschen und Aufbewahren bleiben getrennt

Stundenartefakte wachsen regelmäßig. Aufbewahrung darf jedoch keinen halb geschriebenen Lauf zum Anlass nehmen, den letzten vollständigen Stand zu löschen. Der Retention-Lauf dieser Installation folgt darum einer einfachen lokalen Policy: Entfernt werden nur Artefakte außerhalb der vereinbarten Frist; der Latest-Pointer und die von ihm referenzierten Manifeste bleiben stehen. Eine belastbare Garantie unter konkurrierenden Läufen ist das nicht – wer parallel schreibt und löscht, braucht einen expliziten Mechanismus zur Referenzprüfung. Für Backups gilt dieselbe Vorsicht: Erst ein geprüfter, als vollständig markierter neuer Satz erlaubt das Entfernen eines älteren. „Die jüngste Datei“ ist kein Ersatz für „der jüngste vollständige Satz“.

So bleibt der Weg vom JSON zur Seite klein, aber nicht leichtfertig. Der Bucket hält maschinenlesbare, gehashte Stände. ContentKit hält Revisionen und Releases samt Zugriffsregeln. Das Cockpit bleibt der menschliche Verwaltungszugang, content:read der minimal berechtigte Maschinenweg. Bucket-Artefakte und ContentKit-Release lassen sich dadurch getrennt prüfen: die einen gegen Manifest und Hashes, der andere gegen die release-gebundenen Zugriffsregeln.

Weiterführende Quellen

Wie fandest du diesen Beitrag?