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