# Tsumugu – Datenmodell (Ist-Stand) **Stand:** 19.10.2026, nach den Migrationen in `backend/migrations/` (letzte: `20261019T150000Z_source_registry.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](TSUMUGU_TECHNICAL_SPEC.md). 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/`; 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) | 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 ```mermaid 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" ```