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>
This commit is contained in:
1 parent
f21c64a944
commit
3c190c87b4
27 files changed
+3953
-71
No files matched your search
@@ -0,0 +1,195 @@
|
||||
# Tsumugu – API-Referenz (Ist-Stand)
|
||||
|
||||
**Stand:** 18.10.2026. Erstellt im Code-Review aus `backend/app/main.py`, `api/routes.py`, `api/sources.py`, `api/export.py` und `api/correspondence.py`.
|
||||
|
||||
Diese Datei beschreibt die tatsächlich registrierten Endpunkte. Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 6.2](TSUMUGU_TECHNICAL_SPEC.md). OpenAPI ist in allen Umgebungen abgeschaltet (`docs_url=None`, `openapi_url=None`). Diese Datei ist deshalb die einzige Übersicht. Sie wird bei jeder Routenänderung mitgepflegt.
|
||||
|
||||
## Gemeinsame Regeln
|
||||
|
||||
| Thema | Regel im Code |
|
||||
|---|---|
|
||||
| Sitzung | Cookie `__Host-jinkendo-session` (Produktion, HTTPS) bzw. `jinkendo-session` (Development über HTTP). Gültigkeit `SESSION_TTL_HOURS`, Default 336 h |
|
||||
| Schreibschutz | Alle Methoden außer GET/HEAD/OPTIONS unter `/api/` verlangen einen `Origin` aus `ALLOWED_ORIGINS` (Middleware) und den Header `X-CSRF-Token` der Session |
|
||||
| Datenraum | Fachrouten verlangen `X-Scope-Kind` (`personal` oder `organization`) und `X-Scope-Id`. Beide müssen mit dem in der Session bestätigten Raum übereinstimmen, die Mitgliedschaft wird je Request geprüft |
|
||||
| Handlungskontext | Lesend als Query `context_kind` und `context_id` (`case`/`matter` + UUID), schreibend als `context: {kind, id}` im JSON. Ohne Kontext gelten nur Owner und direkte Grants |
|
||||
| Eingaben | JSON ohne unbekannte Felder (`extra="forbid"`); Upload als Multipart |
|
||||
| Fehler | `application/problem+json` mit `type`, `title`, `status`, `detail`, `instance`, `code`. 401 keine Session, 403 fehlendes Recht bei sichtbarem Objekt, 404 unsichtbar oder nicht vorhanden, 409 Versionskonflikt, 422 ungültige Eingabe, 429 Login-Begrenzung, 503 Speicher nicht verfügbar |
|
||||
| Versionen | Ändernde Aufrufe tragen `expected_version` des geänderten Ankers (Akte, Vorgang, Element, Aufgabe, Frist). Kapitel- und Ordnungsänderungen erhöhen die Version des Behälters |
|
||||
| Listen | Antwort `{items, next_cursor}`. `next_cursor` ist außer in der Chronologie immer `null` |
|
||||
|
||||
Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R** Session und Datenraum-Header, **B** Betreiber (`is_superadmin`), **M** Verwalter des Raums. Alle Tabellen ohne Spalte „Auth“ verlangen **S+R**; die Objektrechte prüft danach die Rechteauswertung ([RECHTEMODELL_IST.md](RECHTEMODELL_IST.md)).
|
||||
|
||||
## Betrieb
|
||||
|
||||
| Methode | Pfad | Auth | Zweck |
|
||||
|---|---|---|---|
|
||||
| GET | `/api/health` | – | `{status, app}`; 503 bei DB-Fehler |
|
||||
| GET | `/health/live` | – | Prozess lebt |
|
||||
| GET | `/health/ready` | – | DB antwortet |
|
||||
|
||||
## Anmeldung, Session, Konten
|
||||
|
||||
| Methode | Pfad | Auth | Zweck |
|
||||
|---|---|---|---|
|
||||
| POST | `/api/v1/auth/login` | – | E-Mail, Passwort → Session-Sicht und Cookie. 8 Versuche je IP+E-Mail in 10 min (Prozessspeicher) |
|
||||
| POST | `/api/v1/auth/logout` | S | Session widerrufen, Cookie löschen, 204 |
|
||||
| GET | `/api/v1/auth/session` | S | Konto, bestätigter Datenraum, Räume, CSRF-Token, Epoche |
|
||||
| POST | `/api/v1/auth/session/scope` | S | Datenraum wechseln (`kind`, `id`); erhöht die Epoche |
|
||||
| GET | `/api/v1/auth/bootstrap` | – | `{available: true}`, solange kein Betreiber existiert, sonst 404 |
|
||||
| POST | `/api/v1/auth/bootstrap` | – | erstes Konto als Betreiber anlegen, nur ohne vorhandenen Betreiber |
|
||||
| GET | `/api/v1/auth/demo` | – | Beispielkonten; nur Development mit Datenbank `*_test` und `SEED_DEMO=true`, sonst 404 |
|
||||
| GET | `/api/v1/accounts` | S+R, B | aktive Betreiberkonten (`origin='operator'`) |
|
||||
| POST | `/api/v1/accounts` | S+R, B | Konto mit Passwort anlegen, erhält persönlichen Raum |
|
||||
| GET | `/api/v1/principals?email=` | S+R | aktives Konto per E-Mail auflösen (ID, Anzeigename) |
|
||||
| POST | `/api/v1/invitations` | S+R, M | Einladung in einen gemeinsamen Raum; Antwort enthält das Token einmalig. Keine Oberfläche |
|
||||
| POST | `/api/v1/invitations/{id}/accept` | – | Token, Anzeigename, Passwort → Konto, Mitgliedschaft, Session |
|
||||
|
||||
## Datenräume
|
||||
|
||||
| Methode | Pfad | Auth | Zweck |
|
||||
|---|---|---|---|
|
||||
| GET | `/api/v1/rooms` | S+R | wählbare Räume |
|
||||
| POST | `/api/v1/rooms` | S+R | gemeinsamen Raum anlegen, Anlegende Person wird Verwalter |
|
||||
| GET | `/api/v1/rooms/{id}/members` | S+R, M | Mitglieder |
|
||||
| POST | `/api/v1/rooms/{id}/members` | S+R, M | bestehendes Konto als `member` oder `manager` aufnehmen |
|
||||
| DELETE | `/api/v1/rooms/{id}/members/{subject_id}` | S+R, M | Mitgliedschaft beenden; letzter Verwalter bleibt. Keine Oberfläche |
|
||||
|
||||
## Akten
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| GET | `/api/v1/cases` | lesbare Akten und Unterakten |
|
||||
| POST | `/api/v1/cases` | Akte anlegen (`title`, optional `parent_case_id`, `rights_mode`, `home_scope_id`) |
|
||||
| GET | `/api/v1/cases/{id}` | Akte mit Trail, Kapiteln, Unterakten, Vorgangsbaum, direkten Einbindungen, `contained` (Inhalte zugeordneter Vorgänge), Aufgaben, Fristen, Grants (für Freigebende) |
|
||||
| PATCH | `/api/v1/cases/{id}` | Titel, Status `open`/`closed` |
|
||||
| POST | `/api/v1/cases/{id}/delete` | Akte löschen (`deleted_at`); nur ohne Unterakten und Vorgangszuordnungen. Verlangt `edit` (siehe Review R-01) |
|
||||
| POST | `/api/v1/cases/{id}/grants` | Grant per E-Mail (`can_read`, `can_edit`, `can_share`) |
|
||||
| POST | `/api/v1/cases/{id}/chapters` | Kapitel anlegen, optional `parent_chapter_id`, `document_on` |
|
||||
| POST | `/api/v1/cases/{id}/chapters/order` | Geschwisterreihenfolge |
|
||||
| PATCH | `/api/v1/cases/{id}/content-order` | Ordnungsart `date`/`position`, Richtung |
|
||||
| POST | `/api/v1/cases/{id}/bindings/order` | eigene Reihenfolge der sichtbaren Einbindungen |
|
||||
| POST | `/api/v1/cases/{id}/bindings/chapters` | mehrere Einbindungen in ein Kapitel |
|
||||
| GET | `/api/v1/cases/{id}/course` | fachlicher Verlauf |
|
||||
| GET | `/api/v1/cases/{id}/chronology?cursor=` | Änderungsprotokoll, 40 Einträge je Seite |
|
||||
|
||||
## Vorgänge
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| GET | `/api/v1/matters` | lesbare Vorgänge mit lesbaren Kontexten |
|
||||
| POST | `/api/v1/matters` | Vorgang oder Teilvorgang (`parent_matter_id`, `context`) |
|
||||
| GET | `/api/v1/matters/{id}` | Vorgang mit Trail, Zuordnungen (`placements`, `case_links`), Teilvorgängen, Querverweisen, Einbindungen, Aufgaben, Fristen |
|
||||
| PATCH | `/api/v1/matters/{id}` | Titel, Status |
|
||||
| POST | `/api/v1/matters/{id}/delete` | Vorgang löschen; nur ohne Teilvorgänge. Verlangt `edit` (Review R-01) |
|
||||
| POST | `/api/v1/matters/{id}/move` | Akte wechseln (`case_id`), Elternvorgang setzen oder lösen |
|
||||
| POST | `/api/v1/matters/{id}/case-links` | Akte zuordnen; Freigaberecht am Vorgang und Bearbeitungsrecht an der Akte |
|
||||
| DELETE | `/api/v1/matter-case-links/{id}` | Zuordnung lösen |
|
||||
| POST | `/api/v1/matters/{id}/cross-links` | Querverweis (`target_matter_id`, `target_context`) |
|
||||
| DELETE | `/api/v1/matter-cross-links/{id}` | Querverweis lösen |
|
||||
| POST | `/api/v1/matters/{id}/grants` | Grant am Vorgang |
|
||||
| POST | `/api/v1/matters/{id}/chapters` | Kapitel (Kontext als Query) |
|
||||
| POST | `/api/v1/matters/{id}/chapters/order` | Geschwisterreihenfolge |
|
||||
| PATCH | `/api/v1/matters/{id}/content-order` | Ordnungsart |
|
||||
| POST | `/api/v1/matters/{id}/bindings/order` | eigene Reihenfolge |
|
||||
| POST | `/api/v1/matters/{id}/bindings/chapters` | mehrere Einbindungen in ein Kapitel |
|
||||
| GET | `/api/v1/matters/{id}/course` | fachlicher Verlauf |
|
||||
| GET | `/api/v1/matters/{id}/chronology?cursor=` | Änderungsprotokoll |
|
||||
|
||||
## Kapitel
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| PATCH | `/api/v1/chapters/{id}` | Kapiteldatum |
|
||||
| PATCH | `/api/v1/chapters/{id}/title` | umbenennen |
|
||||
| POST | `/api/v1/chapters/{id}/parent` | umhängen, `parent_chapter_id: null` = oberste Ebene |
|
||||
| POST | `/api/v1/chapters/{id}/delete` | auflösen; Inhalte und Kinder rücken eine Ebene nach oben |
|
||||
|
||||
## Inhalte und Einbindungen
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| POST | `/api/v1/notes` | Notiz mit Einbindung (`context`, optional `placement`, `chapter_id`, `dates`, `communication_direction`) |
|
||||
| PATCH | `/api/v1/notes/{id}` | gemeinsamen Text ändern; Antwort mit `visible_bindings` und `notice` |
|
||||
| POST | `/api/v1/files` | Datei hochladen (Multipart: `title`, `context_kind`, `context_id`, `upload`, optional Platzierung, Kapitel, Daten, Richtung); PDF, PNG, JPEG, WebP bis 20 MiB |
|
||||
| GET | `/api/v1/files/{id}/content` | Datei als `attachment`, `no-store` |
|
||||
| POST | `/api/v1/external-refs` | externe Referenz (`paperless`, `imap`, `url`) mit `detail` |
|
||||
| POST | `/api/v1/sources/link` | wie oben, nur `paperless`/`imap` (doppelter Weg, siehe Connectoren-Befund) |
|
||||
| GET | `/api/v1/elements` | eigene, nicht eingebundene Elemente (max. 100) |
|
||||
| POST | `/api/v1/elements/{id}/delete` | überall löschen; nur Element-Owner |
|
||||
| PATCH | `/api/v1/elements/{id}/title` | Titel |
|
||||
| PATCH | `/api/v1/elements/{id}/summary` | Kurzbeschreibung (≤ 400 Zeichen) |
|
||||
| PATCH | `/api/v1/elements/{id}/dates` | Dokument-, Versand-, Zugangsdatum |
|
||||
| POST | `/api/v1/elements/{id}/references` | Bezug auf eine andere Unterlage (zyklusfrei) |
|
||||
| DELETE | `/api/v1/elements/{id}/references/{target}` | Bezug lösen |
|
||||
| POST | `/api/v1/bindings` | Element in weiteren Kontext einbinden (`share` an der Quelle, `edit` am Ziel) |
|
||||
| DELETE | `/api/v1/bindings/{id}` | Einbindung lösen |
|
||||
| PATCH | `/api/v1/bindings/{id}/chapter` | Kapitel einer Einbindung |
|
||||
| PATCH | `/api/v1/bindings/{id}/communication` | Richtung `in`/`out`/`local`/`null` |
|
||||
| POST | `/api/v1/bindings/{id}/annotations` | kontextbezogene Anmerkung |
|
||||
| PUT | `/api/v1/exceptions` | Kontextausnahme am Element, Vorgang, Aufgabe oder Frist setzen bzw. löschen; nur Owner |
|
||||
| DELETE | `/api/v1/grants/{id}` | Grant entziehen |
|
||||
|
||||
## Aufgaben, Fristen, Übersichten, Suche
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| POST | `/api/v1/tasks` | Aufgabe, optional mit Vorgang und Kontext |
|
||||
| PATCH | `/api/v1/tasks/{id}` | Titel, Arbeitstermin, Status `open`/`done` |
|
||||
| POST | `/api/v1/tasks/{id}/assignee` | zuweisen (E-Mail) oder lösen; legt begrenztes Grant an. Keine Oberfläche |
|
||||
| POST | `/api/v1/tasks/{id}/deadline-links` | Frist verknüpfen |
|
||||
| PUT | `/api/v1/tasks/{id}/elements` | verknüpfte Inhalte ersetzen (max. 40) |
|
||||
| POST | `/api/v1/tasks/{id}/dependencies` | Abhängigkeit von anderer Aufgabe (zyklusfrei) |
|
||||
| DELETE | `/api/v1/tasks/{id}/dependencies/{other}` | Abhängigkeit lösen |
|
||||
| POST | `/api/v1/deadlines` | Frist |
|
||||
| PATCH | `/api/v1/deadlines/{id}` | Titel, Datum |
|
||||
| POST | `/api/v1/deadlines/{id}/fulfill` | als erfüllt kennzeichnen |
|
||||
| GET | `/api/v1/views/open-tasks` | offene sichtbare Aufgaben (siehe Review R-11) |
|
||||
| GET | `/api/v1/views/open-deadlines` | offene sichtbare Fristen (siehe Review R-11) |
|
||||
| GET | `/api/v1/views/recent-matters` | acht zuletzt geänderte sichtbare Vorgänge |
|
||||
| GET | `/api/v1/placement-targets` | bearbeitbare Akten und Vorgänge als Ziele |
|
||||
| GET | `/api/v1/search?q=` | Akten, Vorgänge, Elemente (Titel und Notiztext), max. 50 |
|
||||
|
||||
## Quellen
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| GET | `/api/v1/connectors` | eigene Zugänge ohne Secret |
|
||||
| POST | `/api/v1/connectors` | Paperless (überschreibt den vorhandenen) oder IMAP anlegen |
|
||||
| DELETE | `/api/v1/connectors/{id}` | Zugang löschen |
|
||||
| POST | `/api/v1/connectors/{id}/probe` | Zugang prüfen |
|
||||
| GET | `/api/v1/sources/paperless/documents?q=` | Paperless-Suche (letzter eigener Zugang) |
|
||||
| GET | `/api/v1/sources/imap/mailboxes?connector_id=` | IMAP-Fächer |
|
||||
| GET | `/api/v1/sources/imap/messages?connector_id=&mailbox=&q=&before=` | Nachrichtenliste, 30 je Seite |
|
||||
| GET | `/api/v1/sources/imap/message?connector_id=&mailbox=&uid=` | Vorschau vor dem Übernehmen |
|
||||
| GET | `/api/v1/external-refs/{id}/content` | Paperless-Datei zum Ansehen (`inline`) |
|
||||
| GET | `/api/v1/external-refs/{id}/mail` | vollständige E-Mail als JSON, Identität per Message-ID geprüft |
|
||||
| GET | `/api/v1/external-refs/{id}/mail/original` | EML |
|
||||
| GET | `/api/v1/external-refs/{id}/mail/attachments/{index}` | Anlage (`inline`, siehe Review R-03) |
|
||||
|
||||
Quelleninhalte werden mit den Zugängen der **anfragenden** Person geladen (Review R-10).
|
||||
|
||||
## Übergabepaket
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| GET | `/api/v1/matters/{id}/export-tree` | Auswahlbaum mit `exportable` und Grund |
|
||||
| POST | `/api/v1/matters/{id}/export/review` | Prüfung: `ready`, `issues`, `notices`, `entries` mit Paketpfaden |
|
||||
| POST | `/api/v1/matters/{id}/export` | ZIP nur bei `ready`; Audit `export_created`. Knoten `attachment`, `dispatch-item` und `evidence` gehören zur Auswahl |
|
||||
|
||||
## Anlagen und Versand
|
||||
|
||||
Alle schreibenden Aufrufe prüfen den Handlungskontext, `expected_version` und den Behälter (`placement`, sonst der Kontext). Fremde oder unlesbare IDs antworten mit 404. Ohne Bearbeitungsrecht mit 403.
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| POST | `/api/v1/elements/{id}/attachments` | Anlagen zuordnen, optional nur als Anlagenansicht |
|
||||
| POST | `/api/v1/elements/{id}/attachments/order` | Reihenfolge |
|
||||
| POST | `/api/v1/elements/{id}/attachments/{attachment_id}/detach` | nur diese Zuordnung lösen |
|
||||
| PATCH | `/api/v1/bindings/{id}/fold` | Vorkommen als Anlage, Nachweis oder wieder eigenständig |
|
||||
| POST | `/api/v1/elements/{id}/dispatches` | Versand dokumentieren und Fassung sichern oder als Lücke kennzeichnen |
|
||||
| POST | `/api/v1/dispatches/{id}/evidence` | Nachweis ergänzen |
|
||||
| POST | `/api/v1/dispatches/{id}/correct` | Weg, Datum oder Gegenüber berichtigen |
|
||||
| GET | `/api/v1/dispatches/{id}` | Manifest, Nachweise, Berichtigungen |
|
||||
| GET | `/api/v1/dispatches/{id}/items/{item_id}/content` | gesicherte Bytes; eine Lücke liefert 404 und nicht die aktuelle Datei |
|
||||
|
||||
Eingabe für beide POST-Aufrufe: `{context, selected: [Knoten-IDs], assignments: {Knoten-ID: connector_id}}`.
|
||||
@@ -0,0 +1,114 @@
|
||||
# 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"
|
||||
```
|
||||
@@ -6,6 +6,10 @@
|
||||
|
||||
**Technische Grundlagen:** Jinkendo-Referenzarchitektur A/B/C v0.3 vom 16.10.2026 sowie die Blueprints Auth/Session/Scope, Release/Betrieb/Recovery und Medien/Dateien. KI-Gateway, Prompt-/Workflow-Laufzeit und Entitlements gelten nur als Grenze, nicht als MVP-Pflicht.
|
||||
|
||||
### Hinweis zum Ist-Stand (Code-Review 18.10.2026)
|
||||
|
||||
Diese Fassung ist der Entwurf vom 16.10.2026 mit späteren punktuellen Ergänzungen (Ordnung, Richtung, Unterkapitel). Abschnitt 1.3 („keine Fachanwendung“) und der Satz in Abschnitt 8, der erste Auftrag solle nur P0 umfassen, beschreiben den damaligen Ausgangspunkt. Die Anwendung umfasst inzwischen P0–P3, P4a und P5a sowie die Folgeaufträge F-06 bis F-08. P7 fehlt. Den tatsächlichen Stand beschreiben [API_REFERENZ.md](API_REFERENZ.md), [DATENMODELL_IST.md](DATENMODELL_IST.md) und [RECHTEMODELL_IST.md](RECHTEMODELL_IST.md). Abweichungen zwischen dieser Spezifikation und dem Code stehen im [Code-Review](../review/04_TECHNISCHE_SPEZIFIKATION.md).
|
||||
|
||||
### Änderungsnotiz 0.3
|
||||
|
||||
F-05a bestätigt die erste benutzbare Lieferung „Organisieren und Nachverfolgen“. Finanzfunktionen und bidirektionaler Paperless-Abgleich folgen anschließend, ohne gestrichen zu werden. Die zuvor kombinierten Pakete P4 und P5 sind dafür in unabhängig lieferbare Teile aufgeteilt; P7 sichert schon den ersten echten Betrieb ab. Die technische Präzisierung des Akten-Handlungskontexts ist in Abschnitt 6.2 ergänzt. Diese Angleichung ist keine pauschale Freigabe der offenen Rechte-/Löschvorschläge und kein Implementierungsauftrag.
|
||||
@@ -217,7 +221,9 @@ Gemeinsame Spalten der fachlichen Ankerobjekte `cases`, `matters`, `elements`, `
|
||||
|
||||
Auth-Tabellen `auth_accounts` und `auth_sessions` folgen dem Auth-Blueprint. Ein Anzeigename ist kein Identitätsbeweis.
|
||||
|
||||
Akten und Vorgänge speichern `content_order` (`date` oder `position`) und `content_order_dir` (`asc` oder `desc`). Bestehende Zeilen bleiben auf `position`, damit eine schon gesetzte Einbindungsreihenfolge nicht ersetzt wird. Neue Akten und Vorgänge beginnen mit fachlichem Datum aufsteigend. `bindings.position` gehört zur Einbindung. Die Datumssortierung schreibt sie nicht um. `PATCH /api/v1/cases/{id}/content-order` und `POST /api/v1/cases/{id}/bindings/order` sowie die gleichen Pfade unter `matters` prüfen das Bearbeitungsrecht im Handlungskontext und `expected_version`. Der fachliche Verlauf liest die Datumsfelder der sichtbaren Unterlagen einmal je Element. Das Änderungsprotokoll bleibt `GET .../chronology`, seitenweise über `cursor`. Der Breadcrumb eines Vorgangs ist der Objektpfad `Vorgänge` und gegebenenfalls der lesbare Elternvorgang; lesbare Aktenzuordnungen stehen separat in `placements` und wechseln den Handlungskontext nur bei bewusster Auswahl. `elements.summary` ist eine optionale gemeinsame Kurzbeschreibung. Ein Textauszug entsteht nur aus vorhandenem Notiztext. Bild- und PDF-Vorschauen verwenden denselben berechtigten Dateiabruf wie das Öffnen.
|
||||
Akten und Vorgänge speichern `content_order` (`date` oder `position`) und `content_order_dir` (`asc` oder `desc`). Bestehende Zeilen bleiben auf `position`, damit eine schon gesetzte Einbindungsreihenfolge nicht ersetzt wird. Neue Akten und Vorgänge beginnen mit fachlichem Datum aufsteigend. `bindings.position` gehört zur Einbindung. Die Datumssortierung schreibt sie nicht um. `PATCH /api/v1/cases/{id}/content-order` und `POST /api/v1/cases/{id}/bindings/order` sowie die gleichen Pfade unter `matters` prüfen das Bearbeitungsrecht im Handlungskontext und `expected_version`. Der fachliche Verlauf liest die Datumsfelder der sichtbaren Unterlagen einmal je Element. Das Änderungsprotokoll bleibt `GET .../chronology`, seitenweise über `cursor`. `content_view` ist `structure` oder `chronology` und nur eine Darstellung. Sie schreibt Kapitel, Positionen und Datumssortierung nicht um. Der Breadcrumb eines Vorgangs ist der Objektpfad `Vorgänge` und gegebenenfalls der lesbare Elternvorgang; lesbare Aktenzuordnungen stehen separat in `placements` und wechseln den Handlungskontext nur bei bewusster Auswahl. `elements.summary` ist eine optionale gemeinsame Kurzbeschreibung. Ein Textauszug entsteht nur aus vorhandenem Notiztext. Bild- und PDF-Vorschauen verwenden denselben berechtigten Dateiabruf wie das Öffnen.
|
||||
|
||||
Anlagen, Versand und Nachweise sind eigene Verwendungen im Behälter der Einbindung, nicht im geerbten Aktenkontext. `attachment_uses` ordnet ein vorhandenes Element einem Hauptschriftstück zu, mit eigener Reihenfolge je Behälter und ohne Dateikopie. `bindings.list_fold` blendet nur dieses Vorkommen als Anlage oder Nachweis aus; andere Einbindungen bleiben. `dispatches` hält Weg, Versanddatum, Gegenüber, Vollständigkeit und Herkunft (`captured` oder `reconstructed`). `dispatch_items` ist das Manifest. Eine sicherbare Fassung liegt als Bytes unter `MEDIA_ROOT/dispatch/<id>` in `dispatch_snapshots`, bei Notizen zusätzlich als JSON im Manifest. Eine fehlende historische Fassung bleibt `gap` und wird nicht durch die aktuelle Arbeitsdatei ersetzt. `dispatch_evidence` verknüpft einen vorhandenen Beleg in der Rolle E-Mail, Einlieferung, Zustellung oder sonstiger Nachweis. Einlieferung setzt keinen Zustellstatus. Berichtigungen stehen in `dispatch_corrections` und ändern die gesicherten Bytes nicht. Löschen eines Elements entfernt die Bytes seiner Versandfassungen über denselben Löschpfad wie die Arbeitsdatei. Lesen des Hauptschriftstücks öffnet keine gesperrte Anlage. Exportknoten `attachment`, `dispatch_item` und `evidence` unterscheiden Arbeitsstand, gesicherte Fassung und Nachweis. Eine unvollständige Auswahl ist ein Auszug. Eine ausgewählte E-Mail bleibt das vollständige Original.
|
||||
|
||||
### 4.3 Überblick
|
||||
|
||||
|
||||
Reference in new issue
Block a user