Files
tsumugu/docs/architecture/DATENMODELL_IST.md
T
LarsandClaude Sonnet 5.5 eb58dce4cd
Deploy Development / deploy (push) Successful in 40s
Test Suite / pytest-backend (push) Successful in 3m12s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 21s
Führe die Konfigurationsansicht der Connectoren ein, damit Paperless und IMAP ihre Felder selbst deklarieren.
Das Modul liefert ein Feldmanifest und validiert es; ein leeres Geheimnisfeld behält das gespeicherte. Die Oberfläche rendert die Felder generisch in einer Detailansicht je Zugang mit Prüfstand, Fähigkeiten und Verwendung. Die providerspezifischen Formulare in Sources.jsx entfallen, die flachen API-Felder bleiben als Kompatibilität. Das Standardfach eines IMAP-Kontos öffnet der Picker zuerst.

Die Backend-Tests wurden in der Entwicklungsumgebung nicht ausgeführt; der Lauf auf develop steht aus.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 09:34:37 +02:00

10 KiB
Raw Blame History

Tsumugu – Datenmodell (Ist-Stand)

Stand: 19.10.2026, nach den Migrationen in backend/migrations/ (letzte: 20261020T120000Z_connector_probe_status.sql). Entstanden im Code-Review vom 18.10.2026 und für die Connector-Grundlage nachgezogen. Die Arten connectors.kind und external_references.source prüft die Registrierung. Die früheren Prüflisten in der Datenbank sind entfernt. url bleibt eine Referenz ohne Connector.

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), connector_id, resolution (bound/ambiguous/unresolved/none) IMAP: Message-ID als external_id, mailbox und uid im JSON. connector_id ist keine Fremdschlüsselbeziehung: ein gelöschter Zugang lässt die Referenz stehen und hängt sie nicht um. Mehrdeutiger Bestand bleibt ambiguous, bis der Owner zuordnet
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, Speicherinstanz, Generation, Objektkennung, Inhaltsrevision, Schutzprofil Datei unter der gebundenen Wurzel als dispatch/<id>; fällt in den Löschpfad des Elements. Ein späterer Wurzelwechsel liest die alte Generation weiter am gebundenen Ort
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), Speicherinstanz, Generation, object_key, content_revision, protection_profile, key_responsibility Bytes über den lokalen Storage-Port. Bestandsgeneration legacy-local-1, Schlüsselzuständigkeit none, Profil legacy-plaintext. Der Bytehash bleibt intern
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), last_probe_at/last_probe_ok/last_probe_detail (nur Anzeige des letzten Prüfstands) Mehrere Instanzen je Art sind möglich. Ein POST legt eine neue Instanz an. Ein PATCH ändert Zugangsdaten derselben Id. Das Secret bleibt im Adapter und ist keine SaaS-Schlüsselhaltung
storage_instances kind (local), generation (eindeutig), root_path Die Bestandsgeneration legacy-local-1 wird einmal an die Wurzel gebunden. Ein späterer Wurzelwechsel erzeugt eine neue Generation und hängt alte Referenzen nicht um
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"