Netzwerksolution Documentation Report

EP-001B-PERSISTENCE-MODEL

EP-001B – MariaDB-Persistenzmodell#

Zweck#

Dieses Dokument materialisiert das kanonische Domain Model aus MVP-001-domain-model.md als relationales Persistence Model für MariaDB.

Das Persistence Model ist nicht das Domain Model. Tabellen, Fremdschlüssel und Indizes dienen der dauerhaften Speicherung und dürfen die fachlichen Begriffe nicht neu definieren.

Verbindliche Grundsätze#

Zustände verwendet werden. Sie ist kein Ersatz für den führenden MariaDB-Arbeitszustand und keine zweite fachliche Wahrheit.

abgeschlossener lokaler Schreibvorgang entweder vollständig nachvollziehbar ist oder beim letzten vollständigen Zustand bleibt.

kontrollierte Migration in MariaDB.

Schemastruktur#

Für das wird ein gemeinsames Datenbankschema verwendet. Die Tabellen bleiben nach Building-Block-Verantwortung geordnet.

Identity & Access#

Artifact Management#

Relationship Management#

Dimensions#

Terminology and Translation#

Review, Audit and Roundtrip#

Identitätsstrategie#

Fachliche IDs werden als CHAR(36) gespeichert und enthalten UUIDs in kanonischer Schreibweise.

Die erste Implementierung darf UUIDv7 oder UUIDv4 verwenden. Die Wahl wird im Application Layer zentral gekapselt. Datenbankfunktionen erzeugen keine fachlichen IDs selbst.

Jede fachliche Tabelle besitzt zusätzlich:

Zeitstempel werden in UTC gespeichert.

Revisionierungsstrategie#

artifacts, artifact_localizations und relationships halten die stabile Identität und Referenzen auf die aktuelle Revision.

Die eigentlichen Inhalte liegen ausschließlich in Revisionstabellen:

artifacts.current_revision_id
                    → artifact_revisions.id

                artifact_localizations.current_revision_id
                    → artifact_localization_revisions.id

                relationships.current_revision_id
                    → relationship_revisions.id

Eine Revision wird nie aktualisiert. Korrekturen erzeugen eine neue Revision.

Mehrsprachigkeit#

Die Tabelle artifact_localizations besitzt eine Eindeutigkeitsregel auf:

artifact_id + language_code

language_code ist im MVP auf de, en, uk beschränkt.

Die konkrete Sprachfassung liegt in artifact_localization_revisions. Dort werden außerdem gespeichert:

Ein Fallback darf nur in der Anwendung erfolgen und verändert nicht den gespeicherten Sprachcode.

Dimensionen#

Dimensionen werden kontrolliert und nicht als unvalidierte JSON-Key-Value-Sammlung gespeichert.

dimension_assignments kann genau eines der folgenden Zielobjekte referenzieren:

Ein Check Constraint stellt sicher, dass genau ein Ziel gesetzt ist.

Audit#

audit_events ist append-only und enthält mindestens:

Audit-Nutzdaten werden als begrenztes JSON gespeichert. Secrets oder vollständige sensible Inhalte dürfen nicht aufgenommen werden.

Outbox#

outbox_events stellt sicher, dass Hintergrundverarbeitung, Reporting, Translation und Roundtrip keine fachlichen Änderungen verlieren.

Ein Outbox-Ereignis wird in derselben Transaktion wie die fachliche Änderung geschrieben. Ein Worker verarbeitet und markiert es anschließend.

Minimale Zustände:

pending → processing → processed
                                     └→ failed

Transaktionsgrenzen#

Artefaktänderung#

Eine Artefaktänderung schreibt atomar:

  1. neue ArtifactRevision oder LocalizationRevision,
  2. Aktualisierung der aktuellen Revisionsreferenz,
  3. AuditEvent,
  4. OutboxEvent.

Übersetzungsauftrag#

Das manuelle Anstoßen einer Übersetzung schreibt atomar:

  1. TranslationJob mit Status requested,
  2. AuditEvent,
  3. OutboxEvent translation.requested.

Roundtrip-Vorbereitung#

Ein Roundtrip-Export schreibt atomar:

  1. RoundtripJob,
  2. RoundtripJobItems mit Ausgangsrevisionen,
  3. AuditEvent,
  4. OutboxEvent roundtrip.prepare-requested.

Ownership und Tabellenzugriff#

Tabellenbereich Schreibender Andere Blocks
users, roles, permissions BB-EP-002 Identity & Access nur über Ports/Services
artifacts, artifact_revisions BB-EP-003 Artifact Management keine direkten Writes
relationships, relationship_revisions BB-EP-004 Relationship Management keine direkten Writes
artifact_localizations, localization_revisions BB-EP-005 Localization keine direkten Writes
terminology_contexts BB-EP-006 Terminology lesbar über Port
translation_jobs BB-EP-007 Translation keine direkten Writes
audit_events, review_decisions BB-EP-008 Audit & Traceability schreiben über Audit-Port
roundtrip_* BB-EP-009 Roundtrip Orchestration keine direkten Writes
outbox_events BB-EP-010 Persistence Infrastructure Erzeugung über Transaktionsport

Gemeinsame Datenbank bedeutet nicht gemeinsame Tabellenverantwortung.

Migrationsregeln#

Zusätzliche lokale SQLite-Persistenz#

SQLite ist eine dateibasierte relationale Datenbank, die ohne separaten Datenbankserver durch einen Prozess verwendet werden kann. In dieser Solution ist sie ausschließlich für einen bewusst abgegrenzten lokalen technischen Zustand zulässig. Ihre konkrete Zuordnung erfolgt durch den verantwortlichen Building Block; sie darf keine konkurrierende Quelle für Artefakte, Revisionen, Relationships oder fachliche Entscheidungen bilden.

WAL schreibt Änderungen zunächst in ein vorausgeschriebenes Log und übernimmt sie kontrolliert in die Hauptdatenbank. Der Modus unterstützt einen wiederaufnehmbaren lokalen Zustand, ersetzt aber keine Recovery- oder Backup-Strategie. Konkrete Dateipfade, Größen, Hosts, Secrets und Runtime-Konfigurationen gehören nicht in diesen Vertrag.

Traceability#

Write-Ahead Logging (WAL) aus SolutionArchitecture.

solutionweite Einordnung steht in diesem Abschnitt.

Traceability#

Dieses Persistence Model materialisiert insbesondere:

und die Solution Building Blocks BB-EP-002 bis BB-EP-010.

Akzeptanzkriterien EP-001B#

EP-001B ist erfüllt, wenn:

UAM-Persistenzgrenze#

MariaDB materialisiert den führenden produktiven Arbeitszustand, ist aber nicht die Quelle universeller Artifact- oder Identity-Semantik. Das physische Schema muss stabile fachliche Identifier, unveränderliche Revisionen, Relationship-Identität und gemäß erhalten.

↑