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

115 lines
9.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](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) | 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
```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"
```