115 lines
9.0 KiB
Markdown
115 lines
9.0 KiB
Markdown
# 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"
|
||
```
|