Files
tsumugu/docs/architecture/DATENMODELL_IST.md
T
LarsandClaude Sonnet 5.5 6d7b7c5f85
Deploy Development / deploy (push) Successful in 45s
Test Suite / pytest-backend (push) Successful in 5m20s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 21s
Führe Hauptnutzer und Mitarbeiter ein, damit der Betreiber Kunden und Hauptnutzer ihre Teams verwalten.
Eine Einladung erzeugt jetzt ein Mitarbeiter-Konto mit dem Eigentümer des Raums als Förderer. Mitarbeiter arbeiten nur in den eingeladenen Räumen nach ihrer Rolle, legen keine Räume und im persönlichen Raum nichts an und starten ihre Sitzung im Team-Raum. Einladen darf nur der Eigentümer als Hauptnutzer; nur ein Hauptnutzer kann Raum-Eigentümer sein. Hauptnutzer sehen unter Mein Team die Personen in ihren Räumen und verwalten ihre Mitarbeiter (deaktivieren, Einmal-Passwort, aus Räumen entfernen). Der Betreiber sieht die Team-Übersicht mit CSV-Export und macht einen Mitarbeiter zum Hauptnutzer.

Eine zentrale Prüfstelle für Grenzen (access/limits.py) wird beim Anlegen von Räumen und beim Aufnehmen und Einladen von Mitgliedern aufgerufen; Tarife folgen später.

Die lokale Suite läuft mit 143 Tests grün, der Frontend-Build und 24 Node-Tests ebenfalls. Die Oberfläche wurde noch nicht im Browser bedient.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-22 09:03:40 +02:00

119 lines
11 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:** 19.10.2026, nach den Migrationen in `backend/migrations/` (letzte: `20261022T090000Z_account_kinds.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`), `must_change_password`, `password_changed_at`, `last_login_at`, `disabled_at`, `disabled_by`, `account_kind` (`main`/`employee`), `sponsor_id` (Förderer eines Mitarbeiters; nur bei `employee`) | 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`, `last_seen_at`, `label` (kurzer Gerätehinweis) | der bestätigte Datenraum steht in der Session |
| `auth_invitations` | `email`, `room_id`, `token_hash`, `invited_by`, `expires_at`, `accepted_at`, `role`, `revoked_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`/`reader`), `status` (`active`/`removed`) | – |
| `data_rooms` (Spalten seit 21.10.2026) | `owner_id` (Eigentümer; für persönliche Räume das Konto), `default_visibility` (`private`/`room`, Voreinstellung für neue Akten und Vorgänge) | Bestehende Räume `private`, Eigentümer aus `created_by` |
| `room_shares` | `resource_kind` (`case`/`matter`), `resource_id`, `room_id`, `access` (`read`/`edit`), `created_by` | Freigabe einer Akte oder eines Vorgangs an einen Datenraum (Team); eindeutig je Eintrag und Raum. Endet, wenn der Freigebende den Raum verlässt oder Leser wird |
| `auth_login_attempts` | `bucket` (SHA-256 aus Adresse und E-Mail), `attempted_at` | zählt Fehlversuche; erfolgreicher Login löscht den Bucket |
## 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
```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"
```