S•U•S•I - Qualitätsmanagement für immoSoR

Die chronologische Ereignisakte

Die Ereignistabelle susi_events speichert nicht nur Endergebnisse. Sie hält jeden fachlich relevanten Übergang fest.

Typische Ereignisse sind:

• offered,
• started,
• deferred,
• declined,
• completed,
• failed,
• generated,
• protocol_written.

Ergänzend können Ereignisse wie resumed, timed_out, retry_scheduled, pdf_failed, hash_created oder followup_created geführt werden.

Ereignisse werden chronologisch angefügt. Sie werden nicht still überschrieben oder nachträglich in ihrer Bedeutung verändert.

Nutzerentscheidung, Laufstatus und Ergebnis bleiben getrennt

Das Tracking unterscheidet ausdrücklich zwischen freiwilliger Nutzerentscheidung, technischem Laufstatus und fachlichem Prüfergebnis.

Deshalb gilt:

declined bedeutet nicht failed.

deferred bedeutet nicht warning.

completed bedeutet nicht automatisch green.

Diese Trennung zeigt eindeutig, was der Nutzer entschieden, was das System ausgeführt und wie der QM-Service den Lauf bewertet hat.

Dadurch entstehen keine falschen negativen Nutzerstatus.

Ereignis 1 · Offered

offered markiert, dass S•U•S•I einen QM-Lauf tatsächlich angeboten hat.

Gespeichert werden können Tages- oder Laufkontext, Nutzer, Mandant, Rolle, Zeitpunkt, Triggergrund, App-Version und Funktionsregister-Version.

Das Ereignis zeigt, dass eine Einladung technisch erzeugt wurde. Es sagt noch nichts darüber aus, wie der Nutzer entschieden hat.

Das Angebot allein ist kein Prüf- oder Qualitätsbefund.

Der Triggergrund gehört zum Angebot

Das System dokumentiert, warum die Einladung erschien.

Mögliche Gründe sind:

• erster Login des Tages,
• manueller Aufruf,
• Rollenwechsel,
• Mandantenwechsel,
• Versionsänderung,
• empfohlene Nachprüfung.

Dadurch lässt sich später prüfen, ob das Angebot fachlich gerechtfertigt war und nicht unnötig wiederholt wurde.

Ein bloßer Seitenwechsel darf keinen neuen offered-Eintrag erzeugen.

Ereignis 2 · Started

started bedeutet, dass der Nutzer den freiwilligen Lauf ausdrücklich gestartet hat.

Das Ereignis bindet Nutzerentscheidung, Run-ID, Tages-Key sowie Rollen- und Mandantenkontext.

Parallelstarts werden verhindert. Ein wiederholter Klick darf keine mehrfachen Starts oder neue parallele Läufe erzeugen.

Der Start markiert den Übergang von der Einladung in die technische Ausführung.

Ereignis 2 · Deferred

deferred dokumentiert die Entscheidung Später erinnern.

Der Zustand ist neutral. Er erzeugt weder Warnung noch Fehler, Zugangsbeschränkung oder negativen Nutzerstatus.

Optional kann ein einmaliger Erinnerungstermin gespeichert werden. Mehrere parallele Erinnerungseinträge werden verhindert.

Der Nutzer bleibt uneingeschränkt arbeitsfähig.

Ereignis 2 · Declined

declined beziehungsweise dismissed_today dokumentiert die Entscheidung Heute nicht.

Die Entscheidung gilt für den gebundenen Tageskontext und ist kein technischer Fehler.

Sie darf nicht als verweigerte Prüfung, mangelnde Compliance oder negative Leistung ausgewertet werden.

Nach diesem Ereignis folgen im selben Tageskontext keine gewöhnlichen weiteren Einladungen. Erst ein neuer relevanter Kontext kann ein neues Angebot rechtfertigen.

Wertneutrale Nachweisbarkeit

Die Ereignisspur kann belegen, dass das Angebot angezeigt wurde, der Nutzer tatsächlich entscheiden konnte und seine Entscheidung technisch respektiert wurde.

Diese Nachweisbarkeit darf jedoch nicht für Personalbewertung, Anwesenheitskontrolle, Leistungsranking oder Vergütungsentscheidungen verwendet werden.

Nachweisbarkeit und Neutralität müssen gleichzeitig bestehen.

Ereignis 3 · Completed

completed bedeutet, dass der technische Prüflauf einen definierten Abschluss erreicht hat.

Das Ereignis kann Start- und Endzeit, Dauer, Prüfebene, Gesamtstatus, Neutralitätsstatus, Versionsbezug und Payload-Hash enthalten.

completed bedeutet jedoch nicht automatisch Grün.

Ein abgeschlossener Lauf kann Grün, Gelb, Rot-Kritisch, Rot-Technisch, Rot-Nachweis oder Rot-Konfiguration ergeben.

Abschluss und Bewertung bleiben getrennte Felder.

Ereignis 3 · Failed

failed dokumentiert, dass der technische Lauf nicht kontrolliert abgeschlossen werden konnte.

Typische Ursachen sind HTTP 500, Timeout, Worker-Ausfall, Datenbankfehler, ungültige Antwort oder fehlgeschlagene Finalisierung.

Dokumentiert werden Fehlerklasse, letzter sicherer Schritt, technischer Kontext und mögliche Fortsetzung.

Ein technischer Fehler ist kein Nutzerfehler. Die wirtschaftliche Wirkung bleibt ausgeschlossen.

Abbruch und Timeout exakt lokalisieren

Die Ereignisfolge zeigt, welcher Schritt zuletzt erfolgreich war, welcher nicht mehr abgeschlossen wurde, wann der Heartbeat endete und ob ein Retry sinnvoll ist.

Dadurch muss ein Lauf nicht blind vollständig neu gestartet werden.

Eine sichere Fortsetzung kann am letzten bestätigten Zustand ansetzen.

Weitere technische Ereignisse

Zwischen Start und Abschluss können zusätzliche Ereignisse geführt werden, etwa:

• step_started,
• step_completed,
• heartbeat,
• lease_acquired,
• lease_expired,
• retry_started,
• resumed,
• finalization_started.

Die Detailtiefe richtet sich nach der Prüfebene. Ein kurzer Tagescheck benötigt weniger Einzelereignisse als ein vollständiges Rollen-Audit oder Hintergrundlauf.

Ereignis 4 · Generated

generated bedeutet, dass das PDF-Protokoll erzeugt wurde.

Der Eintrag enthält Run-ID, Dokument-ID, PDF-Version, Dateipfad, PDF-Hash, Generator-Version und Erstellungszeit.

Die PDF-Erzeugung ist vom technischen Prüflauf getrennt. Ein Lauf kann abgeschlossen sein, während die Dokumenterzeugung fehlschlägt.

In diesem Fall entsteht ein Nachweisbefund.

Generated bedeutet nicht automatisch gültig

Nach der Erzeugung wird geprüft, ob die Datei vorhanden, technisch lesbar und vollständig ist, die richtige Run-ID enthält, ein Hash gebildet wurde und die Datenbankverknüpfung besteht.

Erst danach gilt die PDF als revisionsfähig erzeugt.

Ein fehlerhaftes Dokument wird nicht still ausgeliefert.

Neue PDF, neue Dokumentrevision

Wird eine PDF neu erzeugt, erhält sie eine neue Dokumentrevision, einen neuen PDF-Hash und einen neuen Zeitstempel.

Frühere Fassungen bleiben erhalten.

Der neue generated-Eintrag verweist gegebenenfalls auf die Vorgängerfassung. Dadurch bleibt die Dokumenthistorie vollständig.

Ereignis 5 · Protocol Written

protocol_written bestätigt, dass der kompakte Arbeitsprotokolleintrag erstellt wurde.

Der Eintrag verbindet Run-ID, Gesamtstatus, Kurzstellungnahme, PDF, Payload-Hash, PDF-Hash und Berliner Anzeigezeit.

Das Arbeitsprotokoll ist die sichtbare Tagesprojektion des technischen Laufs. Es ersetzt weder Ereignisspur noch PDF.

Arbeitsprotokoll erst nach vollständiger Bindung

Der Eintrag gilt erst dann als vollständig, wenn der Lauf abgeschlossen, die Bewertung gespeichert, die Stellungnahme erzeugt, der PDF- oder Nachweisstatus eindeutig und die Hashbindung hergestellt ist.

Fehlt eine Komponente, wird der Eintrag als unvollständig oder nachweisbezogen markiert.

Ein grüner Arbeitsprotokolleintrag ohne gültigen PDF- oder Payload-Bezug ist unzulässig.

Payload-Hash je Ereignis

Jeder Ereignispayload enthält die für den jeweiligen Schritt maßgeblichen Daten, etwa Triggergrund, Nutzerentscheidung, technischen Status, Fehlerklasse, Bewertung oder Dokumentreferenz.

Der Payload-Hash macht nachträgliche Veränderungen erkennbar.

Ereignistyp und Payload müssen gemeinsam interpretiert werden. Ein Hash ohne kanonische Datendarstellung wäre nicht belastbar.

Kanonisierung der Ereignisdaten

Für die Hashbildung werden Feldreihenfolge, Zeitformat, Nullwertbehandlung, Zeichencodierung, Datentypen und Hashalgorithmus versioniert festgelegt.

Derselbe Ereignispayload muss reproduzierbar denselben Hash ergeben.

Eine neue Kanonisierungsregel verändert frühere Ereignisse nicht.

Verkettete Ereignishashes

Ereignisse können zusätzlich über den Hash des vorherigen Datensatzes miteinander verkettet werden.

Beispielsweise:

event_1_hash → event_2(previous_hash = event_1_hash) → event_3(previous_hash = event_2_hash)

Eine spätere Entfernung oder Veränderung wird dadurch leichter erkennbar.

Die Hashkette ersetzt jedoch nicht Mandanten-, Rollen- und Zugriffsschutz.

Zulässige chronologische Abläufe

Eine reguläre Ereignisfolge lautet:

offered → started → completed → generated → protocol_written

Freiwillige Alternativen sind:

offered → deferred

oder:

offered → declined

Ein technischer Fehlerweg kann lauten:

offered → started → failed → retry_scheduled → resumed → completed → generated → protocol_written

Unzulässige Ereignisfolgen

Unzulässig wären beispielsweise:

• completed ohne vorherigen Start oder zulässigen automatischen Trigger,
• protocol_written ohne Run-ID,
• generated ohne gespeicherten Bewertungsstand,
• declined und started gleichzeitig für denselben Entscheidungsstand,
• mehrere parallele started-Ereignisse für denselben Lauf.

Solche Widersprüche erzeugen einen Nachweis- oder Konfigurationsbefund.

Zustandsautomat statt freier Statuswechsel

Erlaubte Übergänge werden als versionierter Zustandsautomat definiert.

Jeder Übergang prüft aktuellen Zustand, zulässiges Folgeereignis, Akteur oder Auslöser, Kontext und Idempotenzschlüssel.

Dadurch können Statuswerte nicht beliebig direkt in der Datenbank verändert werden.

Korrekturen erfolgen über neue Ereignisse.

Run-ID und Tages-Key

Sämtliche Ereignisse eines Prüflaufs tragen dieselbe Run-ID. Dadurch werden Nutzerentscheidung, technischer Lauf, Bewertung, PDF und Arbeitsprotokoll miteinander verbunden.

Ein Retry bleibt innerhalb derselben Run-ID, solange derselbe fachliche Lauf fortgesetzt wird. Eine echte Neubewertung erzeugt eine neue Run-ID.

Der Tages-Key beschreibt den gebundenen Kontext aus Datum, Mandant, Rolle, Nutzer, App-Version und Funktionsregister-Version.

Die Run-ID bezeichnet den konkreten Lauf innerhalb dieses Kontexts. Mehrere historische Runs können zum selben Tages-Key gehören, aber nur einer bildet den aktuell maßgeblichen Stand.

Korrelations-ID für technische Teilsysteme

Zusätzlich kann eine Korrelations-ID Cronauftrag, Agentenlauf, Worker, QM-Service, PDF-Erzeugung und Arbeitsprotokoll verbinden.

Sie erleichtert die technische Fehleranalyse über mehrere Services hinweg.

Die Run-ID bleibt die fachliche Laufidentität. Die Korrelations-ID beschreibt die technische Prozesskette.

Exakte Fehlerlokalisierung

Die Ereignisspur zeigt den letzten bestätigten Zustand.

Beispielsweise:

offered → started → context_checked → session_checked → dashboard_checked → callback_started → timeout

Daraus wird sichtbar, dass Kontext, Sitzung und Dashboard erfolgreich geprüft wurden und der Fehler erst im Rückrufdienst auftrat.

Der Agent kann gezielt ansetzen, und der Nutzer erhält eine präzise Stellungnahme.

Keine pauschale Aussage „Lauf fehlgeschlagen“

Ein Gesamtfehler ohne Stufenbezug erschwert Analyse, Wiederaufnahme, Maßnahme und Nutzerinformation.

Das Ereignis-Tracking benennt betroffene Funktion, Zeitpunkt, Fehlerklasse und letzten sicheren Stand.

Unbetroffene Bereiche bleiben erkennbar.

Timeout-Analyse

Für Timeouts können gestarteter Prüfschritt, erlaubte Laufzeit, tatsächliche Laufzeit, letzter Heartbeat, Workerkennung und Retry-Zähler gespeichert werden.

Dadurch lässt sich unterscheiden zwischen langsamem Dienst, abgebrochenem Worker, fehlender Antwort und Finalisierungsproblem.

Freiwilligkeit revisionsfähig nachweisen

Die Ereignisse offered, deferred und declined zeigen, dass der Nutzer tatsächlich Wahlmöglichkeiten hatte.

Die Spur kann bestätigen:

• keine automatische Zwangsausführung,
• Entscheidung technisch respektiert,
• keine permanenten Wiederholungshinweise,
• Systemnutzung blieb offen.

Diese Nachweisbarkeit ist Teil der Governance, darf aber nicht zur Bewertung der Nutzerentscheidung verwendet werden.

Keine negative Umdeutung

declined bleibt ein neutraler Ereignistyp.

Er darf nicht nachträglich in failed, non_compliant, access_violation oder performance_issue umgedeutet werden.

Die Bedeutungen der Ereignistypen sind versioniert und verbindlich. Neue Regeln dürfen frühere Ereignisse nicht rückwirkend anders bewerten.

Technische Ausführung revisionsfähig belegen

started allein beweist keine erfolgreiche Prüfung.

completed zeigt den kontrollierten Abschluss. generated dokumentiert die PDF-Erzeugung. protocol_written belegt die Einbindung in den Arbeitskontext.

Erst die vollständige Ereigniskette bestätigt den revisionsfähigen Abschluss.

Fehlende Ereignisse machen die Lücke sichtbar.

Positive und negative Prüffälle

Auch abgewiesene oder fehlgeschlagene Tests werden dokumentiert.

Beispiele sind:

• fremde company_id abgewiesen,
• unbekannte Capability abgewiesen,
• fremde Ressource nicht geöffnet,
• manipulierter Fortsetzungstoken abgelehnt.

Diese negativen Ereignisse bestätigen, dass Schutzmechanismen tatsächlich wirken.

Ein Audit dokumentiert deshalb nicht nur erfolgreiche Standardwege.

Mögliche Mindestfelder

Eine Ereignistabelle kann mindestens folgende Felder enthalten:

id
run_id
correlation_id
company_id
user_id
role_code
event_key
event_status
occurred_at_utc
display_time_europe_berlin
payload_json
payload_hash
previous_event_hash
trigger_source
actor_type
actor_id
created_at

Die konkrete Tabellenbezeichnung kann variieren. Entscheidend ist die vollständige fachliche und technische Bindung.

Akteur und Auslöser getrennt speichern

Ein Ereignis kann durch Nutzer, Cron, Agent, QM-Service, S•U•S•I oder Systemjob ausgelöst werden.

actor_type und trigger_source müssen getrennt geführt werden.

So bleibt nachvollziehbar, dass Cron einen Auftrag erzeugt, der Agent einen Heartbeat schreibt, der Nutzer entscheidet und S•U•S•I eine Stellungnahme erstellt.

Idempotenzschlüssel

Wiederholte Requests dürfen keine doppelten Ereignisse erzeugen.

Ein geeigneter Idempotenzschlüssel kann aus Run-ID, Ereignistyp, Prüfschritt sowie Versuch oder Revision bestehen.

Ein mehrfacher Browserklick darf nicht mehrfach started schreiben. Eine wiederholte PDF-Anfrage darf keine identischen generated-Ereignisse erzeugen.

Zugriff und Datenschutz

Ereignisse sind mandantengebunden. Jede Abfrage filtert serverseitig nach Mandant, Rolle, Capability und Zweck.

Run-ID oder Ereignis-ID allein gewähren keinen Zugriff.

Nutzer sehen nur die für sie vorgesehene Projektion. Technik und Revision erhalten zweckgebundene Detailansichten.

Ereignisse sind keine Personenakte

Die Ereignisspur dokumentiert Systemzustände, freiwillige Nutzerentscheidungen und technische Übergänge.

Sie dokumentiert nicht Leistung, Anwesenheit, Arbeitsgeschwindigkeit oder Verhalten.

Laufzeiten beziehen sich ausschließlich auf das System. Freiwillige Entscheidungen bleiben wertneutral.

Datenminimierung

Ereignispayloads enthalten nur Daten, die für Prozessnachweis, Fehlerlokalisierung, Revision und Fortsetzung erforderlich sind.

Vollständige fachliche Inhalte oder unnötige personenbezogene Daten gehören nicht in jedes Ereignis.

Sensible Detaildaten können über geschützte Referenzen statt als Klartext gespeichert werden.

Korrektur ohne Löschung

Ein fehlerhaftes Ereignis bleibt erhalten und wird durch ein neues Korrekturereignis ergänzt.

Beispiele sind event_corrected, event_revoked oder assessment_revised.

Das Korrekturereignis verweist auf den Vorgänger. So bleibt sichtbar, was ursprünglich gespeichert wurde.

Neubewertung erzeugt eine neue Ereigniskette

Ändert sich der fachliche Gesamtstatus, entsteht ein neuer Lauf oder eine neue Revision.

Die alte Kette bleibt unverändert. Die neue kann auf die frühere Run-ID verweisen.

Alt- und Neuzustand bleiben dadurch vergleichbar.

Technische Trendanalysen

Über viele Läufe lassen sich häufige Timeouts, wiederkehrende PDF-Fehler, instabile Prüfschritte, fehlende Protokolle oder Konfigurationsdrift erkennen.

Die Auswertung richtet sich auf Dienste, Funktionen, Versionen und Mandantenkonfigurationen.

Sie darf nicht auf Beschäftigtenleistung zielen.

Freiwilligkeitsstatistik nur für die Systemgestaltung

Aggregiert kann untersucht werden, ob das Angebot zu häufig erscheint, Später erinnern sinnvoll funktioniert oder die Einladung den Arbeitsfluss stört.

Solche Daten dienen ausschließlich der UX- und Prozessverbesserung.

Sie dürfen einzelnen Nutzern nicht als Compliance- oder Leistungswert zugeordnet werden.