Aktualisiere die Dokumentation für Download-Regel, HTML-Mail, Bilder und R-11.
Deploy Development / deploy (push) Successful in 41s
Test Suite / pytest-backend (push) Canceled after 3m21s
Test Suite / smoke-dev (push) Canceled after 0s
Test Suite / frontend-build (push) Canceled after 0s

This commit is contained in:
Stommer committed 2026-10-23 13:02:36 +02:00
1 parent 7a1206b18c
commit e2475555c0
7 files changed
+25 -13

No files matched your search

+12 -9
View File
@@ -1,6 +1,6 @@
# Tsumugu – API-Referenz (Ist-Stand)
**Stand:** 18.10.2026, ergänzt am 19.10.2026 um Quelleninstanzen, Fähigkeiten und Zuordnung. Erstellt im Code-Review aus `backend/app/main.py`, `api/routes.py`, `api/sources.py`, `api/export.py` und `api/correspondence.py`.
**Stand:** 18.10.2026, ergänzt am 19.10.2026 um Quelleninstanzen, Fähigkeiten und Zuordnung und am 23.10.2026 um Download-Regeln, HTML-Mail mit Bildern, Übersicht und Suche. 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.
@@ -33,6 +33,7 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
|---|---|---|---|
| POST | `/api/v1/auth/login` | – | E-Mail, Passwort → Session-Sicht und Cookie. 8 Fehlversuche je Bucket (Hash aus IP und E-Mail) in 10 min, gezählt in `auth_login_attempts` |
| POST | `/api/v1/auth/logout` | S | Session widerrufen, Cookie löschen, 204 |
| GET / PUT | `/api/v1/auth/download-defaults` | S+R, Hauptnutzer | Voreinstellung je Rolle und `direct` (direkt freigegebene Personen); neue Räume übernehmen die drei Rollenwerte. Audit `download_defaults_changed` |
| 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 |
@@ -59,6 +60,7 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
| GET | `/api/v1/rooms` | S+R | wählbare Räume; `include_archived=true` ergänzt die archivierten Räume der Person |
| POST | `/api/v1/rooms` | S+R | gemeinsamen Raum anlegen, Anlegende Person wird Verwalter |
| PATCH | `/api/v1/rooms/{id}` | S+R, M / E | `name` (Verwalter); `status` und `default_visibility` nur der Eigentümer (E). Archivieren setzt Sitzungen im Raum auf den persönlichen Raum zurück |
| GET / PUT | `/api/v1/rooms/{id}/download-policy` | S+R, Mitglied / E | je Rolle (`manager`, `member`, `reader`), ob das Original gespeichert oder geöffnet werden darf; `can_change` nennt, ob die Person ändern darf. Fremde und unbekannte Räume: 404. Audit `room_download_policy_changed` |
| GET | `/api/v1/rooms/{id}/members` | S+R, M | Mitglieder mit Rolle und Kontostatus |
| POST | `/api/v1/rooms/{id}/members` | S+R, M | bestehendes Konto als `member`, `manager` oder `reader` aufnehmen oder dessen Rolle setzen |
| PATCH | `/api/v1/rooms/{id}/members/{subject_id}` | S+R, M | Rolle ändern; letzter Verwalter bleibt. Rückstufung auf `reader` entzieht Bearbeiten- und Freigeben-Grants auf Objekte des Raums |
@@ -142,7 +144,7 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
| 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` |
| GET | `/api/v1/files/{id}/content` | Datei als `attachment` mit Dateiname (UTF-8, `filename*`), `no-store`. Mit `save=true` zusätzlich das Download-Recht, sonst 403 |
| 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) |
@@ -174,8 +176,8 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
| 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/open-tasks` | offene sichtbare Aufgaben, höchstens 200. Gelesen wird in Blöcken mit Rechteprüfung je Zeile (R-11 behoben) |
| GET | `/api/v1/views/open-deadlines` | offene sichtbare Fristen, wie oben |
| 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 |
@@ -198,10 +200,11 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
| 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, Fortsetzung über `before` |
| GET | `/api/v1/sources/imap/message?connector_id=&mailbox=&uid=` | Vorschau vor dem Übernehmen |
| GET | `/api/v1/external-refs/{id}/content` | Original der gebundenen Instanz über das registrierte Modul (`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) |
| GET | `/api/v1/external-refs/{id}/content` | Original der gebundenen Instanz über das registrierte Modul (`inline`, mit Dateiname). Mit `save=true` zusätzlich das Download-Recht |
| GET | `/api/v1/external-refs/{id}/mail` | vollständige E-Mail als JSON, Identität per Message-ID geprüft; `html` ist bereinigt, `remote_images` zählt Bilder fremder Server |
| GET | `/api/v1/external-refs/{id}/mail/html-with-images` | dieselbe bereinigte Mail, die Bilder fremder Server lädt der Server auf Anforderung und liefert sie eingebettet (`loaded`, `failed`) |
| GET | `/api/v1/external-refs/{id}/mail/original` | EML unter dem Betreff als Name; verlangt das Download-Recht (403 sonst) |
| GET | `/api/v1/external-refs/{id}/mail/attachments/{index}` | Anlage (`inline`, siehe Review R-03); mit `save=true` das Download-Recht |
| POST | `/api/v1/external-refs/{id}/assignment` | Owner ordnet eine mehrdeutige oder ungebundene Referenz bewusst einer eigenen Instanz zu |
Quelleninhalte einer eigenen Referenz laufen über die gebundene Instanz. Eine freigegebene Referenz mit `use_owner_sources` nutzt den gebundenen Zugang des Owners. Zugangsdaten und die übrigen Treffer dieses Zugangs werden nicht ausgeliefert. Eine Suche ohne `connector_id` wählt bei mehreren eigenen Instanzen nicht den zuletzt angelegten Zugang (Review R-10).
@@ -212,7 +215,7 @@ Quelleninhalte einer eigenen Referenz laufen über die gebundene Instanz. Eine f
|---|---|---|
| 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 |
| POST | `/api/v1/matters/{id}/export` | ZIP nur bei `ready` und mit Download-Recht am Vorgang (403 sonst); Audit `export_created`. Knoten `attachment`, `dispatch-item` und `evidence` gehören zur Auswahl |
## Anlagen und Versand
+4
View File
@@ -112,3 +112,7 @@ Die Mail wird formatiert (Standard) oder als Text gezeigt. Der Server bereinigt
### Bilder in E-Mails nachladen
Bilder von fremden Servern bleiben standardmäßig draußen. „Bilder nachladen“ (oder die Einstellung „Automatisch nachladen“ unter „Mein Konto“, getrennt für Computer und Touch-Geräte, gespeichert im Browser; die Gerätegruppe folgt `pointer: coarse`) ruft `GET /external-refs/{id}/mail/html-with-images` auf. Der Server lädt die Bilder selbst und liefert sie eingebettet zurück, das Gerät kontaktiert den Absender nicht. Schutz (`app/remoteimages.py`): nur `https` auf Port 443, keine Zugangsdaten in der Adresse, Auflösung der Adresse einmal und Verbindung genau dorthin (kein DNS-Rebinding), alle Ergebnisse müssen öffentliche Adressen sein (kein Loopback, privat, Link-Local, Metadaten), höchstens drei Weiterleitungen mit gleicher Prüfung, 5 Sekunden, 1,5 MB je Bild, 12 Bilder und 6 MB je Nachricht, Prüfung des Inhalts an der Dateikennung (PNG, JPEG, GIF, WebP; kein SVG). Restrisiko: Der Absender sieht den Abruf und weiß damit, dass die Nachricht geöffnet wurde.
### Handy
PDFs werden auf iPhone und iPad seitenweise mit pdf.js (Legacy-Build) gezeichnet, weil Safari PDFs in einem Rahmen nicht zuverlässig anzeigt (`pages/DocumentView.jsx`); die PDF-Vorschau in der Liste ist dort weiterhin eingeschränkt, die Leseansicht funktioniert. Der Rahmen der Ablage begrenzt die Höhe, damit die Liste in Akte und Vorgang scrollt, und der Kopf der Leseansicht ist am Handy kompakt.
+2
View File
@@ -21,6 +21,8 @@ Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 4](TSUMUGU_TE
| `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`) | – |
| `auth_accounts` (Spalte seit 23.10.2026) | `download_defaults` (jsonb: `manager`, `member`, `reader`, `direct`; Voreinstellung für das Herunterladen von Originalen, Standard überall erlaubt) | Neue Räume übernehmen die drei Rollenwerte |
| `data_rooms` (Spalte seit 23.10.2026) | `download_roles` (jsonb: `manager`, `member`, `reader`) | Regel je Raum, nur der Eigentümer ändert sie |
| `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 |
+2 -2
View File
@@ -14,7 +14,7 @@ Der Datenraum bestimmt, **wo neue Objekte entstehen**. Er ist nicht der Rechtepf
## 2. Rechte und Antwortcodes
Ein Ergebnis `Rights(read, edit, share, delete)` entsteht je Objekt und Handlungskontext. `_require` übersetzt:
Ein Ergebnis `Rights(read, edit, share, delete, download)` entsteht je Objekt und Handlungskontext. `download` (Original speichern oder öffnen, Übergabepaket) hat der Owner immer; über einen Raum folgt es `data_rooms.download_roles` der Rolle, bei direkten Grants dem Wert `direct` im Konto des Owners. Es setzt Leserecht voraus, und eine Ausnahme, die das Lesen entzieht, entzieht auch das Herunterladen. Verweigert wird mit 403 und einem erklärenden Text; Lesen in der App bleibt möglich. `_require` übersetzt:
- `read` fehlt → **404** (das Objekt existiert für diese Person nicht)
- `read` vorhanden, verlangte Fähigkeit fehlt → **403**
@@ -100,4 +100,4 @@ Danach Abzug der jeweiligen Ausnahme.
## 6. Bekannte Abweichungen
Siehe [Review-Befunde](../review/06_BEFUNDE.md): R-01 (Behälter löschen), R-02 (Detach/Anmerkung), R-07 (Vorgangsausnahme), R-11 (Übersicht/Suche), R-12 (Teilvorgangstiefe), R-15 (Fristen im Elternkontext).
Siehe [Review-Befunde](../review/06_BEFUNDE.md): R-01 (Behälter löschen), R-02 (Detach/Anmerkung), R-07 (Vorgangsausnahme), R-12 (Teilvorgangstiefe), R-15 (Fristen im Elternkontext).