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

Der Tageszustand bildet den aktuellen Prüfstand

Die Tabelle immosor_qm_susi_daily_states hält den aktuell maßgeblichen und eindeutig gebundenen Tageszustand fest.

Der Datensatz beschreibt mindestens Nutzer, Mandant, Rolle, Berliner Tagesdatum, Prüfebene, aktuellen Laufstatus, Gesamtstatus, App-Version, Funktionsregister-Version und den letzten gültigen Run.

Der Tageszustand ist eine Projektion auf den gegenwärtig maßgeblichen Stand. Er ist nicht die vollständige Historie.

Änderungen am Tageszustand müssen durch Ereignisse nachvollziehbar bleiben. Ein neuer Rollen-, Mandanten- oder Versionskontext erzeugt einen neuen eindeutig gebundenen Zustand.

Der Tageszustand darf Altstände nicht vernichten

Wird ein neuer Lauf durchgeführt, darf der frühere Befund nicht spurlos verschwinden. Der aktuelle Tagesstatus kann aktualisiert werden, während die frühere Bewertung über Run-ID, Ereignis, PDF, Hash und Arbeitsprotokoll erhalten bleibt.

Das Datenmodell trennt damit:

aktuellen Zustand

von:

historischer Wahrheit

Ein grüner Folgelauf löscht keinen früheren roten Befund. Er dokumentiert lediglich, dass der Zustand zu einem späteren Zeitpunkt anders bewertet wurde.

Die Ereignisschicht

Die Tabelle immosor_qm_susi_events bildet die zeitliche Prozess- und Änderungsspur.

Jeder relevante Zustandswechsel erzeugt ein eigenes Ereignis, etwa:

• Einladung angeboten,
• Lauf gestartet,
• Lauf verschoben,
• Lauf unterbrochen,
• Lauf fortgesetzt,
• Prüfpunkt abgeschlossen,
• Befund erzeugt,
• Stellungnahme erstellt,
• PDF erzeugt,
• Arbeitsprotokoll geschrieben,
• Nachprüfung angelegt.

Ereignisse werden nachträglich nicht in ihrer Bedeutung umgeschrieben. Korrekturen erzeugen neue Ereignisse.

Die Ereignisschicht erklärt damit, wie der aktuelle Tageszustand entstanden ist.

Eindeutige Korrelation

Jedes Ereignis wird mindestens an Run-ID, Nutzer, Mandant, Rolle, Prüfebene, Ereignistyp, Zeitpunkt und Ergebnis gebunden. Gegebenenfalls wird zusätzlich auf ein Vorgängerereignis verwiesen.

Eine Korrelations-ID kann mehrere technische Teilschritte zu einer gemeinsamen Kette verbinden.

Dadurch lassen sich Cronauftrag, Agentenlauf, QM-Bewertung, S•U•S•I-Stellungnahme, PDF und Arbeitsprotokoll als zusammengehöriger Vorgang rekonstruieren.

Append-only statt Überschreiben

Die Ereignistabelle folgt dem Append-only-Prinzip. Bestehende Ereignisse werden nicht still verändert, um die Historie nachträglich zu glätten.

Muss eine frühere Aussage korrigiert werden, entsteht ein neues Ereignis, beispielsweise:

• Korrektur,
• Widerruf,
• Neubewertung,
• Ersetzung.

Der Bezug auf das frühere Ereignis bleibt erhalten. Dadurch ist sichtbar, was ursprünglich festgestellt wurde, wann die Korrektur erfolgte und auf welcher Grundlage sie beruhte.

Die Arbeitsprotokollschicht

Die Tabelle immosor_qm_work_protocol_entries bildet die verständliche und kompakte Tagesakte.

Sie kann Ereignisart, technische Laufzeit, Berliner Anzeigezeit, Mandant, Rolle, Run-ID, Gesamtstatus, Neutraltest, Wirtschaftsstatus, Kurzstellungnahme, PDF-Verweis und Hash enthalten.

Das Arbeitsprotokoll ist keine vollständige technische Ereignistabelle. Es ist die lesbare Projektion auf den Arbeitsalltag.

Die technischen Rohdaten verbleiben in der Lauf- und Ereignisschicht.

Arbeitsprotokoll und Ereignisspur bleiben getrennt

Ein Ereignis beschreibt einen technischen Zustandswechsel. Ein Arbeitsprotokolleintrag beschreibt dessen fachlich verständliche Bedeutung für den Tageskontext.

Beispielsweise:

Ereignis: qm_run_completed

Arbeitsprotokoll: Tagesprüfung im Maklerkontext abgeschlossen. Kernfunktionen bestätigt. Neutraltest 0,00 EUR.

Beide Einträge gehören zusammen, erfüllen jedoch unterschiedliche Aufgaben. Die Verbindung erfolgt über Run-ID und Hash.

Unveränderliche Run-IDs

Jeder Lauf erhält eine einmalige Identität. Die Run-ID ist der zentrale Anker der gesamten Prüfakte.

Sie verbindet Trigger, Tageszustand, technische Prüfschritte, Einzelbefunde, Gesamtbewertung, Stellungnahme, PDF, Arbeitsprotokoll, Audit und Folgemaßnahmen.

Eine Run-ID wird niemals für einen anderen Lauf wiederverwendet.

Ein Retry innerhalb desselben kontrollierten Laufs bleibt an dieselbe Run-ID gebunden. Eine echte Neubewertung erzeugt eine neue Laufidentität.

Run-ID und Revision sind nicht dasselbe

Die Run-ID kennzeichnet den konkreten Prüflauf. Eine Revision kennzeichnet eine neue fachliche oder dokumentarische Fassung.

Ein Lauf kann beispielsweise einen ersten PDF-Erzeugungsversuch und eine kontrollierte Nachweisreparatur enthalten.

Ändert sich jedoch die fachliche Bewertung oder der zugrunde liegende Payload, entsteht eine neue Revision und regelmäßig auch ein neuer Lauf.

Diese Trennung verhindert uneindeutige Nachweise.

Run-ID ist Identität, nicht Berechtigung

Interne Run-IDs können technisch lesbar oder UUID-basiert sein. Öffentliche oder benutzerseitige Abrufe dürfen jedoch nicht allein durch eine erratbare ID geschützt werden.

Zusätzlich erforderlich sind Authentifizierung, Mandantenprüfung sowie Rollen- und Scope-Prüfung.

Die Run-ID identifiziert den Lauf. Sie gewährt keinen Zugriff.

Payload-Hashes

Der Payload-Hash schützt die strukturierten Prüfdaten. Er wird über einen kanonisch geordneten Datensatz gebildet.

Dieser kann Kontext, Funktionsregister-Version, Einzelbefunde, Gesamtstatus, Neutralitätsstatus, wirtschaftliche Wirkung, Maßnahmen und Zeitbezug enthalten.

Der Hash macht nachträgliche Änderungen erkennbar und verbindet die maschinenlesbare Prüfwahrheit mit Stellungnahme und PDF.

Kanonische Datendarstellung

Hashes sind nur belastbar, wenn dieselben Daten immer in derselben Reihenfolge und Form verarbeitet werden.

Deshalb müssen versioniert festgelegt sein:

• Feldreihenfolge,
• Datentypen,
• Nullwertbehandlung,
• Zeitformat,
• Zeichencodierung,
• Rundungsregeln,
• Hashalgorithmus.

Unterschiedliche JSON-Reihenfolgen dürfen nicht zu fachlich falschen Abweichungen führen. Die Kanonisierungsregel gehört deshalb zur Revisionsfassung.

Payload-Änderung erzeugt eine neue Revision

Wird ein fachlich relevantes Feld geändert, ist der bisherige Payload-Hash nicht mehr gültig.

Dazu gehören ein neuer Gesamtstatus, eine andere Befundklasse, eine geänderte Maßnahme, korrigierter Kontext, neue Neutralitätsbewertung oder eine andere Registerversion.

Eine solche Änderung darf nicht in einen bestehenden Nachweis hineingeschrieben werden. Sie erzeugt eine neue Revision.

PDF-Hashes

Neben dem Payload erhält auch die erzeugte PDF-Datei einen eigenen Hash.

Der PDF-Hash bestätigt genau diese Datei, diese Seiten, diese Textfassung und diese Revisionsdaten.

Payload-Hash und PDF-Hash sind nicht austauschbar:

• Der Payload-Hash schützt die strukturierte Prüfwahrheit.
• Der PDF-Hash schützt die konkrete lesbare Ausgabe.

PDF und Payload müssen zusammengehören

In der Datenbank werden Run-ID, Payload-Hash, PDF-Pfad, PDF-Hash und PDF-Version gemeinsam gespeichert.

Vor einer Ausgabe kann geprüft werden:

• Existiert die Datei?
• Stimmt ihr Hash?
• Gehört sie zum gespeicherten Payload?

Eine PDF mit abweichendem Hash wird nicht still ausgeliefert. Der Zustand wird als Nachweisproblem behandelt.

Neue PDF, neue Dokumentrevision

Selbst wenn der technische Befund gleich bleibt, kann eine neu erzeugte PDF eine neue Dokumentrevision erfordern.

Gründe können ein korrigiertes Layout, eine geänderte Stellungnahme, eine ergänzte Revisionsangabe oder ein neuer PDF-Generator sein.

Die frühere PDF bleibt erhalten. Die neue Fassung erhält eine neue Versionskennung, einen neuen PDF-Hash, einen neuen Erstellungszeitpunkt und einen Verweis auf die Vorgängerfassung.

UTC für technische Integrität

Technische Zeitstempel werden vorzugsweise in UTC gespeichert.

UTC eignet sich für Vergleichbarkeit, Sortierung, verteilte Systeme, Cron, Agent und technische Reconciliation.

Start, Ende, Ereignisse und Finalisierung erhalten eindeutige UTC-Werte. Dadurch entstehen keine Mehrdeutigkeiten durch Sommer- und Winterzeit.

Europe/Berlin für Anzeige und Tagesbezug

Für Nutzeransicht und Arbeitsprotokoll gilt Europe/Berlin.

Diese Zeitzone bestimmt den fachlichen Kalendertag, sichtbare Uhrzeiten, Tages-Key, Tagesgruß und lokale Protokollanzeige.

Sommer- und Winterzeit werden korrekt aufgelöst. Der Nutzer muss keine UTC-Zeiten selbst umrechnen.

Zwei Zeitdarstellungen, ein Zeitpunkt

UTC und Berliner Zeit beschreiben denselben Zeitpunkt in zwei unterschiedlichen Darstellungen.

Gespeichert werden der technische UTC-Wert und gegebenenfalls die aufgelöste Anzeigezeit beziehungsweise Zeitzone.

Die Umrechnung muss reproduzierbar sein. Abweichende Angaben wären ein Revisions- oder Konfigurationsbefund.

Die lokale Anzeige darf nicht unabhängig manuell verändert werden.

Das Berliner Tagesdatum als fachlicher Schlüssel

Ein Lauf um 23:59 Uhr und ein Lauf um 00:01 Uhr können zu unterschiedlichen fachlichen Tagen gehören.

Maßgeblich ist das Datum in Europe/Berlin. Der UTC-Zeitpunkt bleibt dennoch der technische Primäranker.

Diese Kombination verhindert falsche Tageszuordnungen rund um Mitternacht und Zeitumstellungen.

Jede Neubewertung erzeugt eine neue Revision

Eine Neubewertung liegt vor, wenn der Gesamtstatus neu berechnet wird, neue Befunde hinzukommen, eine Befundklasse geändert, die wirtschaftliche Wirkung neu bewertet oder eine Schutzbedingung anders bestätigt wird.

Die frühere Bewertung bleibt erhalten.

Die neue Bewertung erhält:

• neue Run-ID oder Revisions-ID,
• neuen Payload-Hash,
• neue Stellungnahme,
• neue PDF,
• neue Auditereignisse.

Altstände werden nicht still überschrieben

Kein früheres PDF wird ersetzt. Kein früherer Befund wird gelöscht. Kein früherer Hash wird neu belegt. Kein früheres Ereignis wird inhaltlich umgeschrieben.

Stattdessen entstehen neue Revisionen, Korrekturereignisse und Vorgänger- beziehungsweise Nachfolgerbezüge.

Dadurch bleibt die Entwicklung vollständig nachvollziehbar.

Korrektur statt Löschung

Fachliche oder technische Fehler in einem Nachweis werden nicht durch Löschung bereinigt.

Der ursprüngliche Datensatz bleibt bestehen und wird beispielsweise als fehlerhaft, widerrufen, ersetzt oder nicht mehr gültig markiert.

Die korrigierte Fassung wird separat gespeichert.

Diese Logik schützt vor nachträglicher Geschichtsveränderung.

Beispiel einer Funktionshistorie

Run 100 → Rot-Konfiguration → fehlende Rollenbindung

Konfiguration ergänzt → Ereignis config_fixed

Run 101 → Grün → neue PDF und neue Hashes

Run 100 bleibt sichtbar. Run 101 ersetzt den aktuellen Status. Die Historie erklärt, wann und warum sich der Zustand verändert hat.

Tabellen- und Beziehungsmodell

Die fachliche Grundstruktur kann wie folgt gegliedert werden:

immosor_qm_susi_daily_states
aktueller Tageszustand je gebundenem Kontext

immosor_qm_susi_events
unveränderliche Zustands- und Prozessereignisse

immosor_qm_work_protocol_entries
verständliche Arbeitsprotokollprojektion

Ergänzend sind beispielsweise sinnvoll:

immosor_qm_runs
immosor_qm_findings
immosor_qm_documents
immosor_qm_revisions
immosor_qm_followup_tasks

Die genaue Benennung kann variieren. Entscheidend ist die Trennung von Zustand, Ereignis, Dokument, Befund und Revision.

Möglicher Daily State

Ein Tageszustand kann folgende Felder enthalten:

id
user_id
company_id
role_code
business_date_berlin
current_run_id
app_version
function_registry_version
invitation_status
run_status
overall_status
updated_at_utc

Pro eindeutigem Tages-Key existiert ein aktueller Zustand. Historische Veränderungen bleiben über Events und Runs erhalten.

Mögliches Event

Ein Ereignis kann folgende Felder enthalten:

id
run_id
event_key
company_id
user_id
role_code
occurred_at_utc
payload_json
payload_hash
correlation_id
previous_event_id
created_at

Events sind append-only. Der Payload-Hash schützt den konkreten Ereignisinhalt.

Möglicher Arbeitsprotokolleintrag

Ein Eintrag kann folgende Felder enthalten:

id
run_id
event_id
company_id
user_id
role_code
displayed_at_berlin
duration_ms
overall_status
statement_short
neutral_test_amount
economic_status
pdf_document_id
payload_hash
pdf_hash
created_at

Der Eintrag bildet die verständliche Projektion auf den Tagesablauf.

Dokument- und Revisionsobjekte

Ein Dokumentdatensatz kann folgende Felder führen:

id
run_id
revision_no
document_type
file_path
payload_hash
file_hash
generator_version
created_at_utc
supersedes_document_id
status

supersedes_document_id verbindet Vorgänger und Nachfolger. Der Vorgänger wird nicht gelöscht.

Die vollständige Auditspur

Die Auditspur verbindet alle Schichten:

Tageszustand erkannt → Triggerereignis → Run angelegt → Prüfschritte → Befunde → Bewertung → Stellungnahme → PDF → Arbeitsprotokoll → Folgemaßnahme

Jede Stufe besitzt Run-ID, Zeit, Kontext, Ergebnis und gegebenenfalls Hash.

Dadurch kann der gesamte Lebenszyklus rekonstruiert werden.

Auditspur ist nicht Betriebslog

Technische Serverlogs können rotieren, gekürzt oder nur vorübergehend gespeichert werden.

Die fachliche Auditspur ist dagegen gezielt, strukturiert und revisionsfähig.

Ein Serverlog ersetzt weder Run-ID noch Quittung, Befundklassifikation oder PDF-Verknüpfung.

Betriebslogs unterstützen die Diagnose. Die Auditspur bildet den Nachweis.

Jede relevante Änderung erzeugt ein Auditereignis

Statuswechsel, Neubewertung, PDF-Erzeugung, Widerruf, Reparatur, Download und Zugriff auf sensible Detaildaten werden protokolliert.

Reine Lesezugriffe können je nach Schutzbedarf ebenfalls auditiert werden.

Besonders mandantenübergreifende Super-Admin-Zugriffe benötigen einen sichtbaren Prüfkontext.

Datenbankintegrität

Fremdschlüssel und eindeutige Schlüssel sichern Run-Zuordnung, Mandant, Nutzer, Dokumentrevision und Ereignisfolge.

Eine PDF darf nicht auf einen nicht existierenden Run verweisen. Ein Arbeitsprotokolleintrag darf nicht ohne gültigen Kontext bestehen.

Hashfelder müssen gegen stille Ersetzung geschützt sein.

Mandanten- und Rollenbindung

Jede Abfrage filtert serverseitig nach company_id, Rolle, Capability und Scope.

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

Der Nutzer sieht eigene Nachweise. Technik und Revision sehen nur die für ihren Zweck freigegebenen Schichten.

Download- und Zugriffsspur

Der Abruf eines PDF-Protokolls kann protokolliert werden.

Erfasst werden Dokument, Nutzer, Mandant, Zeitpunkt, Zweck beziehungsweise Kontext und der ausgelieferte Dateihash.

Dadurch bleibt nachvollziehbar, welche Fassung tatsächlich abgerufen wurde. Der Download verändert den ursprünglichen Nachweis nicht.

Fehlerfall: Payload-Hash stimmt nicht

Ein abweichender Payload-Hash kann auf eine Veränderung oder unterschiedliche Kanonisierung des strukturierten Datensatzes hinweisen.

Die PDF darf dann nicht ungeprüft als gültig dargestellt werden.

Der Befund lautet Rot-Nachweis oder bei Manipulationsverdacht Rot-Kritisch.

Der ursprüngliche Stand wird gesichert und eine Revisionsprüfung eingeleitet.

Fehlerfall: PDF-Hash stimmt nicht

Weicht der PDF-Hash ab, entspricht die Datei nicht mehr der registrierten Fassung.

Der Download wird gesperrt oder die Datei eindeutig als ungültig markiert.

Eine neue PDF wird nicht still über denselben Datensatz geschrieben.

Geprüft werden mögliche Ursachen wie Dateibeschädigung, falscher Pfad, unkontrollierter Austausch oder Generatorfehler.

Fehlerfall: Ereignis fehlt

Verweisen Tageszustand oder Arbeitsprotokoll auf einen Lauf mit unvollständiger Ereigniskette, kann die fachliche Funktion zwar ausgeführt worden sein, die Revisionsspur bleibt jedoch unvollständig.

Es entsteht Rot-Nachweis.

Eine Rekonstruktion ist nur aus belegbaren Daten zulässig.

Fehlerfall: Zeitangaben widersprechen sich

Ergeben UTC- und Berlin-Zeit nicht denselben Zeitpunkt, kann auch der Tages-Key falsch sein.

Der Befund wird als Konfigurations- oder Nachweisproblem behandelt.

Eine manuelle Korrektur überschreibt den früheren Wert nicht. Sie erzeugt eine neue korrigierende Revision.

Revisionssicherheit schützt beide Seiten

Der Nutzer kann nachweisen, welcher Systemzustand ihm angezeigt wurde.

Der Betreiber kann nachvollziehen, was geprüft wurde, welche Version aktiv war und welche Maßnahmen folgten.

Technik kann frühere Fehlerstände rekonstruieren. Revision kann Payload, PDF und Ereignisse vergleichen.

Niemand kann einen Altstand unbemerkt durch eine spätere günstigere Fassung ersetzen.

Keine Leistungs- oder Personenakte

Die Revisionsspur dokumentiert Systemzustände, Funktionen, Schutz und technische Abläufe.

Sie dokumentiert nicht Produktivität, Anwesenheit, Arbeitsgeschwindigkeit oder persönliche Leistung.

Die eindeutige user_id dient der Kontextbindung und nicht der Beschäftigtenbewertung.

Diese Zweckgrenze muss in Auswertungen und Zugriffsrechten erhalten bleiben.

Aufbewahrung und Archivierung

Aufbewahrungsregeln richten sich nach Nachweiszweck, technischer Erforderlichkeit, rechtlichen Vorgaben und Datenschutz.

Eine Archivierung darf Hash- und Referenzbeziehungen nicht zerstören.

Gelöschte operative Daten können gegebenenfalls durch minimierte Nachweisreferenzen ersetzt werden.

Eine vollständige Lösch- und Aufbewahrungsordnung benötigt eine gesonderte Governance-Regel.

Praktisches Revisionsbeispiel

Erstbewertung

Run-ID: QM-2026-07-22-001
Status: Gelb
Grund: PDF-Hash noch nicht bestätigt
Payload-Hash: A1…
PDF-Hash: offen

Nachweisreparatur

Ereignis: pdf_hash_rebuilt
Ursache: Der PDF-Generator lieferte die Datei, die Hashspeicherung brach jedoch ab.

Neue Revision

Run-ID: QM-2026-07-22-002
Status: Grün
Payload-Hash: B2…
PDF-Hash: C3…
Vorgänger: QM-2026-07-22-001

Die erste Bewertung bleibt erhalten. Die zweite dokumentiert den korrigierten Stand. Die Historie bleibt vollständig.