Files
tsumugu/docs/architecture/DATENMODELL_IST.md
T
LarsandCursor 3c190c87b4
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Successful in 1m37s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 9s
Halte Anlagen und Versand als eigene Verwendung fest, damit die uebermittelte Fassung und ihre Nachweise spaeter nicht still mit der Arbeitsfassung verschmelzen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-18 09:57:59 +02:00

9.0 KiB
Raw Blame History

Tsumugu – Datenmodell (Ist-Stand)

Stand: 18.10.2026, nach den Migrationen in backend/migrations/ (letzte: 20261018T090000Z_correspondence.sql). Erstellt im Code-Review.

Die Sollfassung steht in der technischen Spezifikation, Abschnitt 4. Diese Datei beschreibt, was tatsächlich angelegt ist. Bei jeder neuen Migration nachziehen.

Migrationsverfahren

  • Dateien YYYYMMDDTHHMMSSZ_name.sql, lexikalisch sortiert.
  • Ledger schema_migrations(version, checksum, applied_at); eine geänderte angewandte Datei bricht den Start ab.
  • Jede Datei läuft mit ihrem Ledger-Eintrag in einer Transaktion.
  • Danach legt migrate die Rolle tsumugu_runtime an bzw. aktualisiert sie: LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT, DML auf alle Tabellen, kein CREATE im Schema, kein Zugriff auf schema_migrations. Das Passwort ist das des Owners (siehe Review R-09).
  • Aufruf beim Containerstart (app.entrypoint) und über python -m app.cli migrate.

Identität und Räume

Tabelle Wesentliche Spalten Regeln
auth_accounts id, email (unique), display_name, password_hash (bcrypt), status (active/disabled), is_superadmin, origin (operator/fixture) Konten mit origin='fixture' entfernt der Start in jeder Umgebung
auth_sessions id, account_id, secret_hash (SHA-256, unique), csrf_token, scope_kind, scope_id, epoch, expires_at, revoked_at der bestätigte Datenraum steht in der Session
auth_invitations email, room_id, token_hash, invited_by, expires_at, accepted_at 7 Tage gültig
data_rooms id, kind (personal/organization), name, status (active/archived), created_by persönlicher Raum: id = account_id
room_memberships PK (room_id, subject_id), role (member/manager), status (active/removed) –

Struktur

Tabelle Wesentliche Spalten Regeln
cases Anker¹, title, parent_case_id, rights_mode (inherit_parent/explicit), record_status (open/closed), content_order (date/position), content_order_dir, content_view (structure/chronology) Wurzelakte immer explicit; Composite-FK (parent_case_id, home_scope_id); Anwendung erlaubt eine Unteraktenebene. content_view ist nur die Arbeitsansicht
matters Anker¹, title, parent_matter_id, record_status, content_order, content_order_dir, content_view Composite-FK für den Elternvorgang im selben Raum; Anwendung erlaubt beim Anlegen eine Teilvorgangsebene
matter_case_links matter_id, case_id, created_by unique (matter_id, case_id); Vererbungskontext
case_link_blocks PK (link_id, element_id) Inhalte, die die zuordnende Person nicht freigeben durfte; im Aktenkontext unsichtbar. Kaskade beim Lösen der Zuordnung
matter_cross_links from_matter_id, to_matter_id kein Selbstverweis, unique
chapters home_scope_id, genau eines von case_id/matter_id, title, position, document_on, parent_chapter_id Composite-FKs zum Behälter; Trigger chapters_parent_guard: gleiches Objekt, gleicher Raum, kein Zyklus, höchstens 32 Ebenen

¹ Anker: id, home_scope_id, owner_subject_id, created_by, version, created_at, updated_at, deleted_at.

Inhalte

Tabelle Wesentliche Spalten Regeln
elements Anker¹, title, kind (note/file/external_ref), summary (≤ 400) gemeinsamer Inhaltsträger
note_bodies element_id, document_json, version ein Text je Notiz; Format {version: 1, blocks: [...]} mit Absatz- oder einem Markdown-Block
correspondence_dates element_id, document_on, sent_on, received_on getrennte Datumssachen; Erfassung = elements.created_at
external_references element_id, source (paperless/url/imap), external_id, detail (JSON) IMAP: Message-ID als external_id, connector_id, mailbox, uid im JSON; kein Eindeutigkeitsindex
bindings element_id, context_kind (case/matter), context_id, chapter_id, position, communication_direction (in/out/local/NULL), direction_explicit, list_fold (attachment/evidence/NULL) unique (element_id, context_kind, context_id); kein FK auf den Kontext (polymorph). list_fold gilt nur für dieses Vorkommen
attachment_uses Behälter, host_element_id, attachment_element_id, position, optionales label flache Zuordnung je Hauptschriftstück und Behälter; keine Dateikopie; kein Selbstbezug
dispatches Behälter, host_element_id, channel, sent_on, counterpart, completeness, provenance, version mehrere Versände je Schreiben; sent_on leer bleibt undatiert
dispatch_items Rolle host/attachment, Titel, Dokumentdatum, source_state snapshot/gap, Hash, optionales Notiz-JSON Manifest der übermittelten Fassung; Lücke ersetzt nicht die Arbeitsdatei
dispatch_snapshots Bytes, Hash, Dateiname Datei unter MEDIA_ROOT/dispatch/<id>; fällt in den Löschpfad des Elements
dispatch_evidence element_id, Rolle email/submission/delivery/other, Identitätsprüfung, comparisons manuelle Zuordnung; Einlieferung ist keine Zustellung
dispatch_corrections Zeitpunkt, Zusammenfassung Berichtigung ohne stilles Umschreiben der Bytes
context_annotations binding_id, body (≤ 4 000), author_subject_id Kaskade mit der Einbindung
element_references PK (element_id, refers_to_element_id) kein Selbstbezug; Zyklusprüfung in der Anwendung; FK-Kaskade greift nur bei physischem Löschen, Elemente werden aber nur markiert (Review R-13)
media_assets id, element_id (unique), Owner, Heimatraum, original_filename, content_type, byte_size, sha256, revision, status (active/purging/purged) Bytes unter MEDIA_ROOT/<asset_id>
media_operations element_id, asset_id, phase, status derzeit reines Protokoll

Rechte

Tabelle Wesentliche Spalten Regeln
access_grants grantee_subject_id (NULL bei Kontextausnahme), resource_kind (case/matter/element/task/deadline), resource_id, context_kind/context_id, can_read/edit/share/delete, is_exception Grant: is_exception=false, ohne Kontext. Ausnahme: is_exception=true, Kontext gesetzt, die Flags bedeuten „entfernt“. Eindeutigkeitsindex über Ressource, Empfänger, Kontext und Art

Nachverfolgung

Tabelle Wesentliche Spalten Regeln
tasks Anker¹, title, matter_id, assignee_subject_id, due_on, task_status (open/done) ohne Vorgang ist die Aufgabe selbst der Rechteanker
deadlines Anker¹, title, matter_id, element_id (ungenutzt), assignee_subject_id, due_on, deadline_status (open/fulfilled), fulfilled_at –
task_deadline_links PK (task_id, deadline_id) keine Statuskopplung
task_element_links PK (task_id, element_id) nicht in der Spezifikation
task_dependencies PK (task_id, depends_on_task_id) kein Selbstbezug, Zyklusprüfung in der Anwendung; nicht in der Spezifikation

Quellen und Audit

Tabelle Wesentliche Spalten Regeln
connectors owner_id, kind (paperless/imap), name, settings (JSON), secret (Klartext, Review R-05) Paperless höchstens einmal je Konto (in der Anwendung)
domain_events actor_subject_id, scope_id, action, resource_kind, resource_id, context_kind/id, occurred_on, occurred_at, result append-only; Grundlage von Chronologie und fachlichem Verlauf

Nicht angelegt (bewusst)

compilations, release_state, Finanztabellen (invoices, payments, …), external_field_states, retain_until, Auth-Tabellen für Flows, MFA, Recovery-Codes und Rate-Limits. Sie gehören zu späteren Paketen bzw. zu offenen Befunden.

Beziehungen

erDiagram
  auth_accounts ||--|| data_rooms : "persoenlicher Raum"
  auth_accounts }o--o{ data_rooms : "room_memberships"
  data_rooms ||--o{ cases : "Heimat"
  data_rooms ||--o{ matters : "Heimat"
  data_rooms ||--o{ elements : "Heimat"
  cases ||--o{ cases : "Unterakte"
  matters ||--o{ matters : "Teilvorgang"
  matters }o--o{ cases : "matter_case_links"
  matters }o--o{ matters : "matter_cross_links"
  cases ||--o{ chapters : "Gliederung"
  matters ||--o{ chapters : "Gliederung"
  chapters ||--o{ chapters : "Unterkapitel"
  elements ||--o{ bindings : "Einbindung"
  bindings ||--o{ context_annotations : "Anmerkung"
  elements ||--o| note_bodies : "Text"
  elements ||--o| correspondence_dates : "Daten"
  elements ||--o| external_references : "Referenz"
  elements ||--o| media_assets : "Datei"
  elements }o--o{ elements : "element_references"
  matters ||--o{ tasks : "optional"
  matters ||--o{ deadlines : "optional"
  tasks }o--o{ deadlines : "task_deadline_links"
  tasks }o--o{ elements : "task_element_links"
  tasks }o--o{ tasks : "task_dependencies"
  auth_accounts ||--o{ connectors : "Zugang"