Schließe die Connector-Kapselung ab, damit Paperless, IMAP und weitere Quellen über dieselbe Anbindung laufen.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
75a3949f7c
commit
d6b70d8f92
75 files changed
+9477
-414
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# 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`.
|
||||
**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`.
|
||||
|
||||
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.
|
||||
|
||||
@@ -153,20 +153,26 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
|
||||
|
||||
| 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 |
|
||||
| GET | `/api/v1/connectors` | eigene Zugänge ohne Secret, mit Fähigkeiten der registrierten Quelle |
|
||||
| POST | `/api/v1/connectors` | neue Instanz einer registrierten Quelle; unbekannte Art wird abgewiesen; ersetzt keinen vorhandenen Zugang |
|
||||
| PATCH | `/api/v1/connectors/{id}` | Name, Einstellungen und Zugangsdaten derselben Instanz |
|
||||
| DELETE | `/api/v1/connectors/{id}` | Zugang löschen; bestehende Referenzen bleiben und werden nicht umgehängt |
|
||||
| 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/capabilities` | erklärte Such-, Lese- und Editorfähigkeiten; nicht Vorhandenes bleibt falsch |
|
||||
| GET | `/api/v1/sources/{kind}/search` | Suche der registrierten Quelle im erklärten Umfang; unbekannte Art und nicht erklärte Filter antworten `422` |
|
||||
| GET | `/api/v1/sources/{kind}/navigate?connector_id=` | Fachnavigation, wenn die Quelle sie erklärt |
|
||||
| GET | `/api/v1/sources/{kind}/preview` | Vorschau vor dem Übernehmen, wenn die Quelle sie erklärt |
|
||||
| GET | `/api/v1/sources/paperless/documents?q=&connector_id=` | Kompatibilitätshülle der Paperless-Suche; delegiert an dieselbe Suche |
|
||||
| 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/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` | Paperless-Datei zum Ansehen (`inline`) |
|
||||
| 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) |
|
||||
| POST | `/api/v1/external-refs/{id}/assignment` | Owner ordnet eine mehrdeutige oder ungebundene Referenz bewusst einer eigenen Instanz zu |
|
||||
|
||||
Quelleninhalte werden mit den Zugängen der **anfragenden** Person geladen (Review R-10).
|
||||
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).
|
||||
|
||||
## Übergabepaket
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Tsumugu – Datenmodell (Ist-Stand)
|
||||
|
||||
**Stand:** 18.10.2026, nach den Migrationen in `backend/migrations/` (letzte: `20261018T090000Z_correspondence.sql`). Erstellt im Code-Review.
|
||||
**Stand:** 19.10.2026, nach den Migrationen in `backend/migrations/` (letzte: `20261019T150000Z_source_registry.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.
|
||||
|
||||
@@ -42,17 +42,17 @@ Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 4](TSUMUGU_TE
|
||||
| `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 |
|
||||
| `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 | Datei unter `MEDIA_ROOT/dispatch/<id>`; fällt in den Löschpfad des Elements |
|
||||
| `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`) | Bytes unter `MEDIA_ROOT/<asset_id>` |
|
||||
| `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
|
||||
@@ -75,7 +75,8 @@ Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 4](TSUMUGU_TE
|
||||
|
||||
| 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) |
|
||||
| `connectors` | `owner_id`, `kind` (`paperless`/`imap`), `name`, `settings` (JSON), `secret` (Klartext, Review R-05) | 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)
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
# Tsumugu – Rechteauswertung (Ist-Stand)
|
||||
|
||||
**Stand:** 18.10.2026, Commit `f21c64a`, ergänzt am 19.10.2026 um die Quellenauflösung. Erstellt im Code-Review aus `backend/app/access/policy.py`, `api/deps.py` und `ops.py`.
|
||||
|
||||
Fachlich gelten die bestätigten Entscheidungen der [Produktspezifikation](../product/TSUMUGU_PRODUCT_SPEC.md) (F-01a–f, S-01b–d) und die vorläufigen [MVP-Annahmen](../MVP_ANNAHMEN.md). Den Sollentwurf beschreibt die [technische Spezifikation, Abschnitt 4.5 und 5](TSUMUGU_TECHNICAL_SPEC.md). Diese Datei beschreibt, wie der Code entscheidet.
|
||||
|
||||
## 1. Vor jeder Fachroute
|
||||
|
||||
1. **Session** (`deps._session_row`): Cookie-Hash muss zu einer nicht widerrufenen, nicht abgelaufenen Session eines aktiven Kontos gehören, sonst 401. Bei unsicheren Methoden muss `X-CSRF-Token` gleich dem Session-Token sein, sonst 403.
|
||||
2. **Origin** (Middleware in `main.py`): unsichere Methoden unter `/api/` nur mit `Origin` aus `ALLOWED_ORIGINS`.
|
||||
3. **Datenraum** (`deps.get_principal`): `X-Scope-Kind` und `X-Scope-Id` müssen vorhanden sein und dem in der Session bestätigten Raum entsprechen. Persönlicher Raum nur der eigene, gemeinsamer Raum nur bei aktiver Mitgliedschaft. Sonst 403.
|
||||
|
||||
Der Datenraum bestimmt, **wo neue Objekte entstehen**. Er ist nicht der Rechtepfad. Objekte anderer Räume bleiben über Grants und Einbindungen erreichbar.
|
||||
|
||||
## 2. Rechte und Antwortcodes
|
||||
|
||||
Ein Ergebnis `Rights(read, edit, share, delete)` entsteht je Objekt und Handlungskontext. `_require` übersetzt:
|
||||
|
||||
- `read` fehlt → **404** (das Objekt existiert für diese Person nicht)
|
||||
- `read` vorhanden, verlangte Fähigkeit fehlt → **403**
|
||||
|
||||
Ausnahmen (`access_grants.is_exception`) **entfernen** Fähigkeiten im genannten Kontext. Sie gelten für alle Personen (`grantee_subject_id IS NULL`), auch für den Owner. Nur der Owner des Objekts setzt sie (`PUT /exceptions`).
|
||||
|
||||
## 3. Auswertung je Objektart
|
||||
|
||||
### Akte (`case_rights`)
|
||||
|
||||
| Fall | Basis |
|
||||
|---|---|
|
||||
| Unterakte mit `inherit_parent` | Rechte der Elternakte |
|
||||
| Owner | alle Rechte |
|
||||
| sonst | direkter Grant `resource_kind='case'` |
|
||||
|
||||
Danach Abzug von Akten-Ausnahmen ohne Kontext (im Code vorgesehen, über die API nicht setzbar).
|
||||
|
||||
### Vorgang (`matter_rights`)
|
||||
|
||||
| Handlungskontext | Basis | Bedingung |
|
||||
|---|---|---|
|
||||
| keiner | Owner = alle Rechte, sonst direkter Grant | – |
|
||||
| Akte C | Rechte der Akte C | Vorgang ist C zugeordnet, oder sein Elternvorgang ist C zugeordnet (dann Elternrechte in C) |
|
||||
| Vorgang P | direkte Rechte an P | Vorgang ist Teilvorgang von P |
|
||||
|
||||
Danach Abzug der Vorgangsausnahme genau in diesem Kontext. Ein Querverweis erzeugt keine Rechte.
|
||||
|
||||
### Element (`element_rights`)
|
||||
|
||||
| Handlungskontext | Basis | Bedingung |
|
||||
|---|---|---|
|
||||
| keiner | Owner = alle Rechte, sonst direkter Grant | – |
|
||||
| Akte C | Rechte der Akte C | Element ist direkt in C eingebunden **oder** in einem Vorgang, der C erreicht. Im zweiten Fall darf kein `case_link_blocks`-Eintrag bestehen |
|
||||
| Vorgang M | direkte Rechte an M | Element ist in M oder in einem Teilvorgang von M eingebunden |
|
||||
|
||||
Danach Abzug der Elementausnahme in diesem Kontext.
|
||||
|
||||
**Grenze:** Eine Ausnahme am **Vorgang** im Aktenkontext wird für Elemente dieses Vorgangs nicht abgezogen (Review R-07).
|
||||
|
||||
### Aufgabe und Frist (`task_rights`, `deadline_rights`)
|
||||
|
||||
| Fall | Basis |
|
||||
|---|---|
|
||||
| zugewiesene Person, ohne Kontext | Lesen; Aufgabe zusätzlich `edit`, falls ein Grant es gibt. Status ändern über `can_change_status` |
|
||||
| ohne Kontext | Owner = alle Rechte, sonst direkter Grant |
|
||||
| Kontext = eigener Vorgang | direkte Rechte am Vorgang |
|
||||
| Kontext = Akte | Rechte des Vorgangs in dieser Akte |
|
||||
| Kontext = Elternvorgang | nur Aufgaben; bei Fristen fehlt dieser Zweig (Review R-15) |
|
||||
|
||||
Danach Abzug der jeweiligen Ausnahme.
|
||||
|
||||
## 4. Schreibende Aktionen
|
||||
|
||||
| Aktion | Verlangte Rechte |
|
||||
|---|---|
|
||||
| Inhalt in Behälter anlegen | `edit` am Zielbehälter im Kontext (`require_container_edit`) |
|
||||
| Gemeinsamen Notiztext ändern | `edit` am Element im Kontext |
|
||||
| In weiteren Kontext einbinden | `share` am Element im Quellkontext und `edit` am Ziel |
|
||||
| Vorgang einer Akte zuordnen | `share` am Vorgang und `edit` an der Akte. Inhalte, die die Person nicht freigeben darf, landen in `case_link_blocks` |
|
||||
| Zuordnung lösen | `edit` an der Akte oder `share` am Vorgang |
|
||||
| Querverweis | `edit` am Quellvorgang, `read` am Ziel in einem eigenen Kontext |
|
||||
| Grant erteilen | Owner oder `share`; `can_edit` nur mit eigenem `edit`, `can_share` nur mit eigenem `share` |
|
||||
| Grant entziehen | Owner der Ressource oder `share` |
|
||||
| Einbindung lösen | `edit` am Element im Kontext (Kontextzugehörigkeit unscharf geprüft, Review R-02) |
|
||||
| Element überall löschen | nur Owner des Elements |
|
||||
| Akte oder Vorgang löschen | `edit` (Review R-01: laut Rollentabelle nur Owner) |
|
||||
| Reihenfolge, Kapitel, Ordnungsart | `edit` am Behälter im Kontext; nur sichtbare Einbindungen; verborgene behalten ihre Position |
|
||||
| Aufgabe zuweisen | Owner oder `share`; legt ein Lese-Grant für die zugewiesene Person an |
|
||||
| Export | je ausgewähltem Inhalt `read` und `share` im Kontext |
|
||||
|
||||
## 5. Sichtbarkeit in Listen und Antworten
|
||||
|
||||
- Listen (`list_cases`, `list_matters`) filtern grob im SQL und prüfen danach jedes Objekt einzeln.
|
||||
- Einbindungen, Anmerkungen, Bezüge, Zuordnungen, Querverweise, Teilvorgänge und Elternnamen erscheinen nur, wenn die Person sie im jeweiligen Kontext lesen darf. Verborgenes wird weder benannt noch gezählt (`visible_bindings_for_element`, `matter_title_if_readable`).
|
||||
- Die Chronologie zeigt nur Ereignisse, deren Ressource im Seitenkontext lesbar ist (`_event_title`).
|
||||
- Breadcrumbs nennen nur lesbare Stationen. Bei mehreren lesbaren Aktenzuordnungen ohne gewählten Kontext erscheint keine Hauptakte.
|
||||
- Betreiber- und Verwalterrolle verleihen kein Leserecht auf persönliche Inhalte.
|
||||
- Ein Quellabruf prüft zuerst das Leserecht im Kontext. Danach wird nur der an der Referenz gebundene Zugang des Owners verwendet. Eine Suche ohne `connector_id` nimmt bei mehreren eigenen Instanzen nicht die zuletzt angelegte. Ein Empfänger erhält weder Zugangsdaten noch die übrigen Treffer des Owners. Ein Entzug gilt beim nächsten Abruf, weil jedes Lesen die Rechte erneut prüft.
|
||||
|
||||
## 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).
|
||||
@@ -0,0 +1,133 @@
|
||||
# Tsumugu – Connector- und Storage-Vertrag
|
||||
|
||||
**Version:** 0.1 · **Stand:** 19.10.2026
|
||||
**Status:** Technischer Umsetzungsvorschlag mit Migrationsplan; hier wurde keine Anwendung geändert. Der begleitende Cursor-Auftrag wird erst durch seine Übergabe zur Umsetzung erteilt.
|
||||
**Ziel:** Kleine produktlokale Grundlage für Paperless, IMAP und die bestehende eigene Dateiablage. Bestehende Fachfunktionen und Daten bleiben erhalten.
|
||||
|
||||
## 1. Verbindliche Grundlage und Liefergrenze
|
||||
|
||||
Fachlich führen die aktuelle Produktspezifikation und die jüngsten Nutzerentscheidungen. Die Connector Suite v0.2 vom 19.10.2026 ist die Grundlage für die Connector-Zielarchitektur. Ihre Vorschläge und offenen Punkte werden nicht pauschal zu bestätigten Beschlüssen. Architekturverträge aus `C:/Dev/tsumugu/docs/reference` gelten; konkrete Dateinamen und Vertragsbezeichnungen unten sind lokale Umsetzungsvorschläge.
|
||||
|
||||
Bestätigt sind: vollständiges Self-Hosting und spätere SaaS-Nutzung; Quellen als regelhafter Ort externer Originale; Fähigkeiten je Quelle/Ressource; gemeinsame UI mit möglichen Spezialansichten; getrennte Freigaben für Speicherung und Verarbeitung; optional vollständig deaktivierbare dauerhafte Cloud-Inhaltsspeicherung. SaaS-Nutzer müssen ihre Entschlüsselungsschlüssel auf eigenen Geräten beziehungsweise ihrer lokalen Runtime halten können. Diese Option ist Zielanforderung, noch kein nachgewiesenes Produktmerkmal.
|
||||
|
||||
**Primäres Nutzerziel:** Tsumugu wird aktuell vorwiegend privat genutzt und kontinuierlich erweitert. Der erste Schnitt legt tragfähige Grundlagen und vermeidet später großflächige Änderungen an Datenidentitäten, Berechtigungspfaden und Modulgrenzen. Funktionale Vollständigkeit der späteren SaaS-Plattform ist keine Voraussetzung. Daraus folgt keine Garantie, dass neue Anforderungen ohne jede Anpassung bleiben; Änderungen sollen überwiegend in den zuständigen Adaptern und Komponenten möglich sein.
|
||||
|
||||
**Erste Lieferung – Grundlagen:** Bestehende Paperless-/IMAP-Zugänge gemeinsam hinter Source-Verträge bringen, eigene Dateien und Versandfassungen über einen kleinen Storage-Vertrag anbinden und eine gemeinsame Frontend-Zugriffsschicht mit registrierten Darstellungs-/Quellmodulen einführen. Heutige Picker, Leser und Notizbearbeitung bleiben nutzbar. Keine vollständige Neugestaltung aller Dialoge als Fertigkriterium; gemeinsame Zustands-/Auswahlverträge dort einführen, wo dadurch bestehende Quellverzweigungen aus Fachseiten entfernt werden.
|
||||
|
||||
**Nächster Funktionsausbau:** Der Quellenbrowser wird auf den gemeinsamen Bausteinen vervollständigt und die Paperless-Suche gemäß Abschnitt 6 deutlich erweitert. Neue Text-/Markdown-Dateieditoren folgen anschließend auf denselben Verträgen. Diese Fähigkeiten bleiben eingeplant und werden nicht allein für eine scheinbar kleine Basis gestrichen; sie sind separat lieferbar.
|
||||
|
||||
**Spätere Lieferungen:** lokale Remote-Runtime, produktive kundenseitige Schlüsselhaltung, automatische lokale EML-Sicherung, dynamische Quellsammlungen, Dateisystem-/NAS-Source, Banking und KI. Text-/MD-Dateibearbeitung wird im Vertragsmodell berücksichtigt; die erste Lieferung implementiert vorhandene Notizbearbeitung und sichere Anzeige unterstützter Dateien. Neue MD-Dateischreibfunktionen benötigen anschließend einen konkret beauftragten Schnitt.
|
||||
|
||||
## 2. Geprüfter Ausgangspunkt
|
||||
|
||||
Gezielter statischer Abgleich am 19.10.2026, keine ausgeführten Anwendungstests oder Live-Quellenzugriffe:
|
||||
|
||||
| Bestand | Verwendung und erforderliche Anpassung |
|
||||
|---|---|
|
||||
| `backend/app/sources.py`, `api/sources.py` | Vorhandene Paperless-/IMAP-Protokollarbeit wiederverwenden. Quelle und Operation sind heute an mehreren Stellen fest verzweigt. |
|
||||
| `backend/app/retrieval.py`, `mailpack.py` | Vollständigen Originalabruf, EML-Parsing, Identitätsprüfung und Fehlerfälle in die gemeinsame Lesestrecke überführen. |
|
||||
| `frontend/src/pages/Sources.jsx` | Zwei Picker und Quellenformulare auf gemeinsame Hülle mit quellenspezifischen Ergänzungen umstellen. |
|
||||
| `ReadingPane.jsx`, `content.jsx`, `markdown.jsx` | Leser nach Darstellungsart anbinden; vorhandenen Markdown-Notizeditor weiterverwenden. |
|
||||
| `media/storage.py`, `ops.create_file`, `api/routes.py` | Browserupload kopiert PDF/Fotos in die eigene Ablage. Das Ursprungsverzeichnis wird danach nicht mehr benötigt. Ablage erfolgt derzeit über `MEDIA_ROOT`, im Compose-Betrieb `/data/media`. |
|
||||
| `correspondence.py`, `dispatch_snapshots` | Anlagen, Versandereignisse und gespeicherte Fassungen erhalten. Direkte Dateioperationen ebenfalls an Storage anbinden. |
|
||||
| `access.policy`, `use_owner_sources` | Kontextrechte und ausdrücklichen Owner-vermittelten Abruf verknüpfter Inhalte erhalten. Keine Erweiterung auf Browsen des übrigen Owner-Quellenbestands. |
|
||||
|
||||
Die heute konfigurierbare lokale Serverablage ist noch keine kundenseitige Remote-Ablage in einem SaaS-Modell. Anwendungseigene Dateiverschlüsselung ist im gelesenen Speicherpfad nicht implementiert; darunterliegende Laufwerksverschlüsselung wurde nicht geprüft. Frühere Prüfberichte belegen nur ihren jeweiligen Stand und werden nicht als aktueller Testlauf ausgegeben.
|
||||
|
||||
## 3. Verantwortlichkeiten
|
||||
|
||||
```text
|
||||
Quellenbrowser / Ressourcenleser / Editor / Export
|
||||
-> Tsumugu-Anwendungsdienst: Identität, Kontext, Objekt- und Quellrechte, DataPolicy
|
||||
-> Source-Port -> Paperless-Adapter oder IMAP-Adapter
|
||||
-> Content-Zugriff -> geschützter Storage-Port -> lokaler Ablageadapter
|
||||
-> Fachrepository: bestehende Elemente, Einbindungen, Aufgaben, Versandstände
|
||||
```
|
||||
|
||||
Die erste Adapterausführung bleibt im bestehenden Backend. Aufrufe verwenden einen expliziten Operationskontext und wohldefinierte Ein-/Ausgaben; Adapter erhalten keine Browser-Session oder frei verwendbare Fach-DB-Verbindung. Ein späterer Runtime-Transport kann dieselbe Verantwortung übernehmen. Ein Netzwerkprotokoll wird jetzt nicht implementiert.
|
||||
|
||||
Authentifizierung, Kontext-/Objektprüfung und fachliche Freigabe liegen im Anwendungsdienst. Ein Adapter kann Fähigkeiten und Quellrechte zusätzlich einschränken. Der Storage-Adapter entscheidet nicht selbst, wer einen Vorgang lesen darf. Fachliches Linking bleibt Tsumugu-Funktion.
|
||||
|
||||
## 4. Source-Vertrag
|
||||
|
||||
Ein kleiner registrierter Adaptervertrag umfasst:
|
||||
|
||||
| Operation | Ein-/Ausgabe und Zusage |
|
||||
|---|---|
|
||||
| Verbindung beschreiben und prüfen | Konkrete Instanz-ID, Typ, Name, Fähigkeiten und serverseitig geprüfter Verbindungszustand. Zugangsdaten bleiben im zuständigen Secret-/Transportadapter. |
|
||||
| Navigieren | Parent-/Navigationskennung, begrenzter Cursor; Ergebnis sind Navigationsknoten und/oder Ressourcen. Keine beliebigen Serverpfade vom Browser übernehmen. |
|
||||
| Suchen | Typisierte Suchanfrage, Suchbereich, Filter, Sortierung, Cursor; begrenzte Ergebnisseite und Fortsetzungsinformation. Nicht unterstützte Filter ausdrücklich melden. |
|
||||
| Ressource auflösen | Instanzgebundene Referenz; Metadaten, Quellstand, Darstellungsarten und aktuell zulässige Operationen. Fehlendes Original löscht die Referenz nicht. |
|
||||
| Inhalt lesen | Original, Vorschau, Text oder bestimmte Anlage getrennt anfordern; Typ, Größe, Quellstand und vollständiger/gekürzter Zustand sind erkennbar. |
|
||||
| Bearbeiten, wenn unterstützt | Inhalts- und Metadatenänderung sind getrennte Operationen mit erwartbarem Quellstand und Konfliktbehandlung. Im ersten Source-Schnitt nicht angeboten. |
|
||||
|
||||
Fähigkeiten werden je Connector und Ressource bestimmt. Die tatsächliche Ausführung prüft erneut Quelle, aktuelle Rechte und DataPolicy. Ein UI-Flag ist keine Autorität. Fehlende Fähigkeit bleibt fehlend; ein Original darf nicht durch eine gekürzte Vorschau ersetzt werden.
|
||||
|
||||
Ergebnisse beschreiben mindestens Instanz und externe Ressourcenkennung, Typ, Titel, vorhandene fachliche Daten, knappen erlaubten Auszug und Darstellungsarten. Paging-Cursor sind an die konkrete Verbindung und Suchanfrage gebunden. Suchtreffer allein erzeugen keine dauerhaften Elemente. Erst ausdrückliches Einbinden schreibt Fachreferenzen.
|
||||
|
||||
Bestehende Element- und Binding-IDs bleiben erhalten. Gleiche externe IDs verschiedener Instanzen sind verschieden. Eine instanzgebundene Quellkennung ist kein Anlass zum automatischen Zusammenführen bereits vorhandener Elemente. IMAP-ID, fachliches Element und Dateihash bleiben unterscheidbare Begriffe.
|
||||
|
||||
Einheitliche Zustände: nicht erreichbar, nicht berechtigt, nicht auffindbar, mehrdeutig, veraltet, Konflikt, Entsperrung erforderlich, nicht unterstützte Fähigkeit/Schutzprofil, Größenlimit und Verarbeitungsfehler. Geheimnisse und verborgene Quelleninformationen gehören nicht in Fehlermeldungen.
|
||||
|
||||
## 5. Gemeinsame UI und Fähigkeiten
|
||||
|
||||
Produktlokale, registrierte Komponenten:
|
||||
|
||||
1. Verbindungseinrichtung mit gemeinsamer Hülle und quellenspezifischen Zugangsfeldern.
|
||||
2. Quellenbrowser: Navigation, Suchbereich, Filter, Ergebnisse, Paging, erhaltene Auswahl und Vorschau.
|
||||
3. Übernahme: gewählte Ressourcen, aktiver Vorgang/Akte, Kapitel und sichtbare Wirkung; erfolgreiche Teilübernahmen und Wiederholungen nachvollziehbar behandeln.
|
||||
4. Ressourcenleser nach Darstellungsart: PDF, Bild, Text/Markdown, E-Mail einschließlich Anlagen und Metadatenformular.
|
||||
5. Editorhülle: Laden, Berechtigungszustand, ungesicherte Eingaben, Speichern/Abbrechen und Konfliktanzeige; bestehende Notizbearbeitung als erster konkreter Editor.
|
||||
|
||||
Filter und Spezialansichten können als Tsumugu-eigene registrierte Ergänzungen eingebunden werden. Vom Connector gelieferter ausführbarer Frontend-Code und ein universeller Formulargenerator gehören nicht zur Lieferung. Dieselben Browserkomponenten funktionieren als Dialog oder vollständige schmale Ansicht. Tastaturfokus, Rückkehr, Abbruch und unveränderte Eingaben bei Layoutwechseln gehören zur Hülle.
|
||||
|
||||
Ressourcen-ID, Zielcontainer und Handlungskontext bleiben getrennt. Mehrfachauswahl verwendet die Verbindung als Teil der Identität und bleibt bei Such-/Seitenwechsel erhalten. Ein unbemerkter Wechsel des Zielkapitels oder Datenraums darf keine Übernahme auslösen.
|
||||
|
||||
## 6. Paperless: funktionaler Suchausbau
|
||||
|
||||
Der unmittelbar folgende Funktionsausbau umfasst kombinierbare Freitext-/Titelsuche, Filter für Korrespondenten, Dokumenttypen und Tags, Dokumentdatumsbereich, Sortierung und vollständiges Paging im berechtigten Bestand. Auswahlwerte aus der konkreten Quelle beziehen. Bei Tagkombinationen UND/ODER-Bedeutung sichtbar machen; tatsächlich unterstützte Kombinationen gegen die eingesetzte Paperless-Version prüfen. In der Grundlagenlieferung werden dafür Anfrage-/Ergebnisvertrag, Capability-Angaben und instanzgebundene Fortsetzungsinformation festgelegt; noch nicht implementierte Suchfähigkeiten bleiben ausdrücklich nicht verfügbar.
|
||||
|
||||
Dokumentdatum und Erfassungsdatum bleiben getrennt. Wenn ein weiterer Datumsfilter angeboten wird, passend beschriften. Treffer vor Einbindung lesen können. Mehrfachauswahl über mehrere Seiten/Suchläufe erhalten. Keine feste Begrenzung auf die ersten 20 Treffer und kein vollständiger lokaler Dokumentindex als Voraussetzung.
|
||||
|
||||
Typgerechte Filter für benutzerdefinierte Felder bleiben der nächste Suchausbau. Der Vertrag muss sie aufnehmen können, ohne eine generische Abfragesprache oder Finanzfunktion jetzt einzuführen. Bestandsfelder nicht mit ungeprüften API-Schlüsseln gleichsetzen.
|
||||
|
||||
## 7. Storage, Inhaltsrevision und Verschlüsselung
|
||||
|
||||
Der kleine Storage-Port speichert, öffnet, beschreibt und löscht begrenzte Byteinhalte. Er arbeitet mit opaken Speicherreferenzen. Diese binden Speicherinstanz, Generation, Objektkennung und Inhaltsrevision. Namensanzeige und Medientyp sind Metadaten; Dateiname oder beliebiger Clientpfad sind keine Speicheradresse.
|
||||
|
||||
Der lokale Adapter übernimmt zunächst bestehende Medien und Versandfassungen. Bisherige Dateien bleiben lesbar, ohne Neu-Upload oder Umbenennung im Bestand. Alte Referenzen dürfen durch Ändern des konfigurierten Wurzelverzeichnisses nicht unbemerkt auf einen anderen Speicher zeigen.
|
||||
|
||||
Neue Inhalte erst nach erfolgreicher geprüfter Ablage als verfügbar melden. Dateiablage und DB sind keine gemeinsame atomare Transaktion: kurze DB-Phasen, nachvollziehbare Operationskennung/Receipts und Wiederherstellung unvollständiger Abläufe nach dem Medien-Blueprint verwenden. Bestehende Größenlimits erhalten. Externe Aufrufe und größere Dateioperationen außerhalb offener Fachtransaktionen durchführen, Zugriffs-/Versionszustand vor abschließender Veröffentlichung erneut prüfen.
|
||||
|
||||
Neue Inhaltsstände erhalten neue Revisionen. Versandfassungen bleiben an ihren festgehaltenen Stand gebunden. Ein interner Bytehash prüft die jeweilige Repräsentation; er ist keine allgemeine Ressourcenidentität und wird nicht als öffentliches Fingerprint-API angeboten.
|
||||
|
||||
**Speicherort und Entschlüsselung sind getrennte Verträge:**
|
||||
|
||||
- Der Storage-Port verarbeitet opake Bytes und benötigt keinen Entschlüsselungsschlüssel.
|
||||
- Ein versioniertes Schutzprofil bezeichnet Klartextbestand, verwaltet verschlüsselte Inhalte oder kundenseitig verschlüsselte Inhalte. Schlüsselreferenz und Schlüsselzuständigkeit sind getrennt vom Speicherort; geheime Schlüssel werden nicht in die fachliche Speicherreferenz geschrieben.
|
||||
- Ein gesonderter Content-/Crypto-Zugriff bestimmt, ob die konkrete Ausführungsstelle entschlüsseln darf. Der Core darf nicht voraussetzen, dass SaaS Inhalte immer lesen kann. Kundenseitig geschützte Inhalte können als verschlüsselt/gesperrt bekannt sein, ohne einen Klartextpfad anzubieten.
|
||||
- Der Dateispeicher erzwingt keine PDF-/Bildinterpretation. Typprüfung und Reader benötigen autorisierten Klartext an der passenden Stelle; spätere Browser-/Runtime-Entschlüsselung muss dort anschließbar sein.
|
||||
- Der vorhandene unverschlüsselte Bestand wird als Legacy-Zustand ausdrücklich beschrieben. Die erste Basislieferung verspricht noch keine Dateiverschlüsselung. Verschlüsselte Speicherung erst nach abgeschlossenem Schlüssel-/Recovery-Entwurf und passenden Nachweisen aktivieren. Bis dahin keine Datenschutz- oder SaaS-Freigabe daraus ableiten.
|
||||
|
||||
Die Vorbereitung wird durch Vertragsprüfungen mit zwei Ablageadaptern und einem gesperrten Inhaltszugriff belegt. Opake Testbytes sind kein Nachweis realer Kryptografie. Eine produktive Browser-Schlüsselhaltung wird damit nicht behauptet.
|
||||
|
||||
DataPolicy unterscheidet dauerhafte Ablage, temporären Cache, Übertragung für Live-Funktionen und externe Verarbeitung. Diese Trennung gilt auch für Leser, Exporte und Versandfassungen. Die erste Ausführung bleibt im vorhandenen Self-Hosting-Betrieb; für Hybridbetrieb ist anschließend der lokale Kommunikationskanal auszuarbeiten. EML-Archivkopien bleiben nach v0.2 ausschließlich im Kundenbereich. Eine verschlüsselte SaaS-Ablage ändert diese Sonderregel nicht.
|
||||
|
||||
## 8. Migrationsfolge und Erhaltung
|
||||
|
||||
1. Aktuellen Bestand und Tests erfassen; nur betroffene Schutz- und Blueprint-Abweichungen in den Schnitt aufnehmen.
|
||||
2. Registrierten Source-Vertrag mit vorhandenen Paperless-/IMAP-Funktionen implementieren. Alte Routen bei Bedarf als kurzlebige delegierende Kompatibilitätsadapter erhalten; keine doppelte Fachlogik.
|
||||
3. Bestehende Referenzen einer konkreten Connector-Instanz zuordnen. Eindeutige Bestände migrieren; mehrdeutige oder nicht auflösbare Einträge erhalten und zur Zuordnung markieren. Niemals auf die zuletzt angelegte Verbindung zurückfallen. Credentialwechsel innerhalb derselben Quelle ist von einem Wechsel der Quellinstanz zu unterscheiden.
|
||||
4. Speicherinstanz/-generation für heutige Medien und Versandstände einführen; bestehende IDs, Pfade und Bytes erhalten. Reads zuerst kompatibel machen, danach neue Writes auf den Vertrag umstellen.
|
||||
5. Frontend-Zugriff, registrierte Quell-/Darstellungsmodule und Ressourcenzugriff umstellen. Auch Export, Anlagen und Nachweise über die gemeinsame autorisierte Lesestrecke führen. Quellenbrowser und erweiterte Paperless-Suche danach als eigenen nutzbaren Funktionsausbau liefern. Keine neuen Quellverzweigungen in Akten-/Vorgangsseiten ergänzen; bestehende während der Migration gezielt in die zuständigen Quellmodule überführen.
|
||||
6. Fachspec, technische Beschreibung und Ist-Dokumentation gezielt nachziehen. F-02b/c bleibt bis zu einer ausdrücklichen späteren Entscheidung erhalten; dieser lesende Source-Schnitt entscheidet keinen Ersatz der bidirektionalen Feldanforderung.
|
||||
|
||||
Keine automatische Umdeutung von Kapiteln, Anlagenrollen oder virtuellen Freigabezusammenstellungen. Bestehende Kontextrechte, gemeinsame Notizänderungen, lokale Ordnung, unabhängige Aufgaben/Fristen und vollständige EML-Exporte bleiben erhalten. Ein Owner-vermittelter Dokumentabruf ist weiterhin auf ausdrücklich freigegebene Ressourcen begrenzt.
|
||||
|
||||
## 9. Quellen und weitere Prüfaufträge
|
||||
|
||||
Projekt: `C:/Dev/tsumugu/AGENTS.md`, aktuelle Fachspec 0.38 und technische/Ist-Dateien unter `docs/architecture`; Connector Suite v0.2; vorhandene Export-, Unterkapitel- und Schreiben/Anlagen/Versand-Aufträge. Die unveränderte Connector Suite v0.2 wird dem Paket als Quelle beigelegt; vorgesehener Repositorypfad: `C:/Dev/tsumugu/docs/architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md`.
|
||||
|
||||
Familienreferenzen ausschließlich aus den Projektkopien unter `C:/Dev/tsumugu/docs/reference`: A/B/C v0.3, Auth/Session/Scope, Medien/Dateien/sicheres Rendering und Release/Betrieb/Recovery. KI-Gateway, Workflow und Entitlements nur bei konkretem Bedarf. Bestehende Varianten bleiben gemäß A0 zulässig; keine Frameworkmigration oder neue familienweite Referenzarchitektur.
|
||||
|
||||
Begleitend: `TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md` und `TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md`. Der Schlüssel-Prüfauftrag geht an die bestehende Architektur-Session, ohne sie hier automatisch zu kontaktieren.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Begrenzter Prüfauftrag an die bestehende Jinkendo-Architektur-Session
|
||||
|
||||
**Stand:** 19.10.2026 · **Status:** Vorbereitet, nicht versandt. Keine Implementierung und keine neue parallele Referenzarchitektur.
|
||||
|
||||
## Bedarf und Eingaben
|
||||
|
||||
Tsumugu entwickelt eine kleine Source-/Storage-Basis aus Paperless, IMAP und eigener Dateiablage. Die spätere SaaS-Nutzung muss sowohl kundenseitig gehaltene Schlüssel als auch optional verwaltete Verschlüsselung unterstützen. Lokale Ablage und verschlüsselte zentrale Ablage sind getrennte Speicheroptionen. Speicherung, Live-Übertragung und externe Verarbeitung haben getrennte Freigaben. EML-Archivkopien bleiben gemäß Connector Suite v0.2 lokal im Kundenbereich.
|
||||
|
||||
Lies die aktuellen Projektkopien unter `C:/Dev/tsumugu/docs/reference`, besonders A/B/C, Auth/Session/Scope, Medien/Dateien/sicheres Rendering und Release/Recovery. Ergänzend die Connector Suite v0.2 und `C:/Dev/tsumugu/docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md`. Prüfe vorhandene Implementierungen nur für tatsächlich wiederverwendbare Mechanismen. Ein Konzept oder vorhandener Test ist noch kein erfolgreicher Produktnachweis.
|
||||
|
||||
## Eng begrenzte Fragen
|
||||
|
||||
1. Passt die Trennung aus opakem Storage-Port, versionierter Speicherreferenz und gesondertem Content-/Crypto-Zugriff zum Medien-Blueprint? Benenne notwendige Korrekturen am kleinen ersten Vertrag.
|
||||
2. Skizziere einen überprüfbaren Einstieg für verwaltete Dateiverschlüsselung: Secret-/Schlüsselreferenz, Schutzprofil, Inhaltsrevision, Wiederherstellung, Rotation und Backupbindung. Nutze etablierte Mechanismen; keine eigene Kryptografie entwickeln.
|
||||
3. Welche Metadaten des Inhalts-/Schutzformats müssen schon jetzt berücksichtigt werden, damit spätere kundenseitige Verschlüsselung vor dem Upload möglich bleibt? Der Core darf Entschlüsselung nicht voraussetzen. Benenne bewusst, welche Metadaten weiterhin zentral lesbar sein dürfen beziehungsweise einer späteren fachlichen Festlegung bedürfen.
|
||||
4. Prüfe die Grenzen eines späteren Browsermodus: Gerätebindung, Wiederherstellung, Mehrgerätezugang und Freigabe an weitere Personen. Browserausführung und Schlüsselhaltung allein nicht als Schutz gegen jede Änderung am ausgelieferten Anwendungscode darstellen. Gib Sicherheitsannahmen ausdrücklich an.
|
||||
5. Definiere höchstens eine spätere Anschlussstelle für lokale Runtime beziehungsweise KI-Processing. Kein Netzwerkprotokoll, keine Providerwahl und keine multimodale Pipeline jetzt ausarbeiten.
|
||||
|
||||
## Erwartetes Ergebnis
|
||||
|
||||
Eine kurze Ergänzung beziehungsweise Zuordnung zu den vorhandenen Blueprints: wiederverwendbare Mechanismen mit aktuellem Nachweisgrad, vorgeschlagene Schutz-/Schlüsselgrenzen, erforderliche Erstimplementierungsentscheidungen und eine kleine Negativtestliste. Klar trennen: Was kann die erste Connector-/Storage-Basis bereits vorbereiten, was muss vor realer Verschlüsselung fertig entschieden sein, was bleibt bis zur späteren Kunden-Runtime offen?
|
||||
|
||||
Kein allgemeines SaaS-Framework, neues Identitätssystem, Schlüsselserver, DMS oder vollständiges E2EE-Produkt entwerfen. Ungeklärte Schlüsselwiederherstellung darf nicht durch Betreiber-Klartextzugriff oder stillen Schlüsselupload ersetzt werden. Keine Anwendung, Secrets, Datenbank, Konfiguration oder Deployments ändern. Rückgabe an die fachliche Tsumugu-Planung; durch diesen Text wird keine andere Session kontaktiert.
|
||||
@@ -485,6 +485,8 @@ Erster Dateischnitt, Vorschlag der registrierten Profile: JPEG, PNG, WebP und PD
|
||||
|
||||
Upload startet nur bei Bearbeitungsrecht am Zielkontext. Der Download nutzt den Readplan: Sessioncookie, geprüfter Scope, lesbare Einbindung, lesbares Asset, aktuelle Revision. Kein öffentlicher `/media`-Mount und keine Session in der URL.
|
||||
|
||||
**Stand 19.10.2026, Implementierung der Grundlage:** Eigene Dateien und Versandfassungen laufen über einen kleinen Storage-Port mit lokalem Adapter. Die Speicherreferenz trägt Instanz, Generation, Objektkennung und Inhaltsrevision. Das Schutzprofil und die Schlüsselzuständigkeit liegen daneben; geheime Schlüssel stehen nicht in der Referenz. Der vorhandene Bestand ist `legacy-plaintext`. Profile `managed-encrypted` und `client-encrypted` werden geschlossen abgelehnt und nicht entschlüsselt. Paperless und IMAP sind registrierte Source-Adapter. Die Art prüft die Registrierung, nicht eine Datenbankliste. Ein dritter Testadapter belegt, dass Fachseiten, Reader und Export dafür nicht erweitert werden. Eine Referenz bindet eine konkrete Instanz. Dieselbe externe Nummer in zwei Instanzen bleibt getrennt. Mehrdeutiger Altbestand wird nicht auf den zuletzt angelegten Zugang gelegt. F-02b und F-02c bleiben offen und werden durch diesen lesenden Schnitt nicht ersetzt. Zugangsdaten liegen weiterhin im Adapter, derzeit als Klartext in `connectors.secret`. Das ist kein Nachweis von Verschlüsselung oder SaaS-Reife.
|
||||
|
||||
Ausfall des Storage: neue Uploads und Downloads antworten 503 `storage_unavailable`. Bereits gespeicherte fachliche Metadaten bleiben lesbar. Die Oberfläche zeigt den Dateizustand `unavailable`, ohne einen leeren Erfolg zu melden.
|
||||
|
||||
### 7.2 Paperless-Felder
|
||||
|
||||
@@ -0,0 +1,306 @@
|
||||
# Tsumugu – Connector Suite: Architekturkonzept
|
||||
|
||||
**Version:** 0.2 · **Stand:** 19.10.2026
|
||||
**Status:** Konsolidierter fachlich-technischer Konzeptstand, **keine Implementierungsfreigabe**
|
||||
**Geltungsbereich:** Tsumugu; mögliche spätere Wiederverwendung in Jinkendo nach gesonderter Prüfung
|
||||
**Grundlage:** Fortgeschriebene Festlegungen in dieser Unterhaltung vom 18.–19.10.2026 und `Tsumugu_Product_Recovery_Baseline_v0.1.md` (16.10.2026).
|
||||
|
||||
## 1. Zielbild und Abgrenzung
|
||||
|
||||
Tsumugu ist ein **universeller Vorgangs-, Akten- und Informationsmanager**. Es führt Ressourcen und Informationen zu Vorgängen zusammen, ohne die angeschlossenen Systeme zu ersetzen. Aktenstruktur, Beziehungen, Notizen, Aufgaben, Fristen, Chronologie und fachliche Zuordnungen sind Tsumugu-eigene Informationen. Dokumente, E-Mails, Dateien und Bankbuchungen verbleiben grundsätzlich in ihren Quellen.
|
||||
|
||||
Die **Connector Suite** erschließt externe Ressourcen und Dienste über eine einheitliche Integrationsarchitektur. Sie ermöglicht Navigation, Suche, Lesen, Metadaten, Darstellung, bei geeigneter Quelle Bearbeitung und selektive Aktualisierung. Sie ist **keine generelle Import-, Spiegelungs- oder Archivierungsplattform**.
|
||||
|
||||
**Geschäftliches Ziel:** Dasselbe Produkt soll sowohl **vollständig selbst gehostet** als auch als **SaaS mit kundenseitig betriebener Connector Runtime** angeboten werden können. Eine SaaS-Variante mit zentralen Connectoren bleibt möglich. Self-Hosting ist insbesondere für datenschutz- und selbsthostingaffine Paperless-Nutzer relevant. Die kommerzielle Nachfrage ist eine Hypothese, keine nachgewiesene Tatsache.
|
||||
|
||||
**Leitprinzipien:**
|
||||
- *Source of Truth:* Externe Quelldaten bleiben im jeweiligen führenden System.
|
||||
- *Reference first:* Tsumugu speichert primär Referenzen, eigene Fachdaten und nötige, freigegebene Metadaten.
|
||||
- *Least privilege:* Rechte aus Quellsystem **und** Tsumugu gelten gemeinsam.
|
||||
- *Policy-based placement:* Pro Connector-Instanz und Datenklasse bestimmen, was gespeichert, übertragen oder verarbeitet werden darf. Lokale Speicherung ist eine Option, keine pauschale Pflicht.
|
||||
- *Cloud content opt-out:* SaaS-Kunden können die dauerhafte Cloud-Speicherung von Dokumentinhalten und KI-Artefakten vollständig deaktivieren.
|
||||
- *Capability based:* Verschiedene Connectoren bieten verschiedene Operationen, Ressourcentypen und Darstellungsarten an.
|
||||
- *Pragmatic UI:* Generische Tsumugu-Komponenten vor beliebig ladbarem Connector-Frontend-Code.
|
||||
- *Demand driven:* Keine allgemeine Plattformkomplexität oder zusätzliche Blueprints ohne konkreten Modulbedarf.
|
||||
|
||||
## 2. Logische Gesamtarchitektur
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ Tsumugu UI │
|
||||
│ Akten | Ressourcenbrowser | Suche | Preview │
|
||||
│ Metadatenansicht/-editor | Aufgaben/Fristen │
|
||||
└───────────────────┬──────────────────────────┘
|
||||
│ standardisierte Ressourcen-/UI-Verträge
|
||||
┌───────────────────▼──────────────────────────┐
|
||||
│ Tsumugu Core │
|
||||
│ Akten, Links, Notizen, Metadatenindex, │
|
||||
│ CollectionBindings, Rechte, Daten-Policies │
|
||||
└───────────────────┬──────────────────────────┘
|
||||
│ autorisierte Connector-Operationen
|
||||
┌───────────────────▼──────────────────────────┐
|
||||
│ Connector Runtime / Adapter │
|
||||
│ Fähigkeiten, Quellzugang, Mapping, Sync, │
|
||||
│ Export, Zugriffskontrolle, lokale Ablage │
|
||||
└─────┬──────────┬──────────┬───────────┬─────┘
|
||||
│ │ │ │
|
||||
Paperless IMAP Dateien Bank/API
|
||||
│
|
||||
Lokales NAS
|
||||
Processing-Dienste (z.B. KI) als
|
||||
eigener Fähigkeitsvertrag
|
||||
```
|
||||
|
||||
### Betriebsformen
|
||||
|
||||
**A – Self-Hosted:** Tsumugu Core und Connector Runtime laufen in einer selbst betriebenen Umgebung, gegebenenfalls auf separaten lokalen Systemen.
|
||||
|
||||
**B – Hybrid-SaaS (bevorzugte Zielrichtung):** Tsumugu Core läuft beim Anbieter, die Connector Runtime optional beim Kunden. Sie verbindet lokale/zugängliche Quellsysteme und setzt Datenfreigaben durch. Tsumugu persistiert nur freigegebene Referenzen/Metadaten und eigene Fachdaten. Originaldokumente müssen nicht im SaaS-Speicher liegen.
|
||||
|
||||
**C – SaaS mit zentralen Connectoren:** Für Nutzer ohne lokale Infrastruktur grundsätzlich möglich, aber nicht als Voraussetzung für die erste Umsetzung.
|
||||
|
||||
**Grenze:** Eine lokale Runtime schützt Daten nicht automatisch vor Cloud-Übertragung. Vorschau, Live-Suche, KI-Anfragen, Protokolle und temporäre Verarbeitung unterliegen ebenfalls einer expliziten Datenfluss-Policy. Der sichere Kommunikationskanal (Initiierung, Authentisierung, Autorisierung, Verbindungsausfall) ist noch technisch auszugestalten.
|
||||
|
||||
## 3. Connector-Kategorien
|
||||
|
||||
| Kategorie | Wesentliche Aufgabe | Erste Anwendungsfälle | Architektonische Einordnung |
|
||||
|---|---|---|---|
|
||||
| **Source** | Datenbestand navigieren, suchen, lesen, optional bearbeiten | Paperless, IMAP, Dateien | Gemeinsamer Ressourcenkontrakt |
|
||||
| **Financial** | Buchungen und Kontoinformationen strukturiert lesen | Banken / Kontoinformationsanbieter | Spezialisierte Source-Fähigkeiten, zunächst read-only |
|
||||
| **Processing** | Inhalte auswerten und strukturierte Ergebnisse erzeugen | KI, perspektivisch OCR/Konvertierung | **Kein gewöhnlicher Ressourcenbrowser**; eigener Eingabe-/Ergebnisvertrag |
|
||||
| **Storage** | Konfiguriert ablegen und wiederfinden | NAS-/Dateiablage, `.eml`-Archiv | Eigener Ablage-/Abrufvertrag; kann Infrastruktur mit Datei-Source teilen |
|
||||
|
||||
Die vier Kategorien sind **Ordnungsbegriffe**, keine Verpflichtung zu vier separaten Servern, Frameworks oder vollständigen APIs. Gemeinsamkeiten werden nur dort standardisiert, wo sie bereits benötigt werden.
|
||||
|
||||
### 3.1 Source: Paperless
|
||||
- Vollständige Suche/Navigation im durch Quellidentität berechtigten Bestand, nicht nur in bereits aktenverknüpften Elementen.
|
||||
- Dokumentreferenz, Quelle, Metadaten, OCR-/Textabruf auf Anfrage, Original-/Vorschauzugriff.
|
||||
- Bearbeitung **führender Paperless-Metadaten** über Paperless, wenn Connector- und Quellrechte dies erlauben; Tsumugu-eigene Felder separat.
|
||||
- Selektiver Metadatenindex, nicht generelle Dokument-/Volltextreplikation.
|
||||
- Navigation etwa über Dokumenttypen, Korrespondenten und Tags; konkrete UI-Komponenten noch zu spezifizieren.
|
||||
|
||||
### 3.2 Source: IMAP
|
||||
- Postfächer und Ordner navigieren, Nachrichten suchen, Header, Inhalt und Anhänge zugänglich machen.
|
||||
- **Explizite Einzelreferenzen bleiben bei Ordnerwechsel als Aktenverknüpfung bestehen.** IMAP-UID ist typischerweise ordnerbezogen; der Adapter braucht eine belastbare Wiedererkennungsstrategie bzw. meldet nicht auflösbare Referenzen, ohne sie zu löschen.
|
||||
- Ordner können als **dynamische Sammlung** referenziert werden, auch für künftige passende Nachrichten.
|
||||
- Optionales lokales `.eml`-Archiv, Details in Abschnitt 7.
|
||||
- Umfang einer vollständigen E-Mail-Bearbeitung (Versenden, Verschieben etc.) ist **nicht** festgelegt und kein Grund für eine komplette E-Mail-Client-Nachbildung.
|
||||
|
||||
### 3.3 Source: Dateien
|
||||
- Zugriff auf explizit freigegebene Verzeichnisse / Netzlaufwerke, Navigation, Suche, Lesezugriff, Vorschau, Metadaten.
|
||||
- Pfad und Ressource nach Möglichkeit getrennt modellieren; Verschieben/Umbenennen darf nicht ungeprüft Aktenverknüpfungen löschen.
|
||||
- Schreiboperationen nur bei ausdrücklicher Fähigkeit und Berechtigung.
|
||||
|
||||
### 3.4 Financial: Banken (beschlossenes Grundmodell)
|
||||
- Financial ist technisch eine **spezialisierte Source-Integration**, keine eigene Banking-Plattform.
|
||||
- Es werden **bestehende Banking-/Kontoinformationsdienste** integriert; zu Beginn ausschließlich **lesender Zugriff auf Einzelbuchungen**. Keine Überweisungen oder Zahlungsinitiierung.
|
||||
- Vollständige Abfrage des freigegebenen Buchungsbestands ist möglich; Tsumugu speichert **standardmäßig keine komplette Umsatzhistorie**.
|
||||
- Dauerhaft verbleiben insbesondere explizit zugeordnete Buchungsreferenzen und die für Rechnung, Zahlung, Teilzahlung, Sammelzahlung oder Erstattung benötigten Metadaten (etwa Betrag, Datum, Gegenpartei, Verwendungszweck), sofern durch die Datenrichtlinie freigegeben.
|
||||
- Rechnungs-/Zahlungszuordnungen sind **Tsumugu-eigene Viele-zu-viele-Beziehungen** und bleiben auch erhalten, wenn der Banking-Anbieter eine frühere Buchung nicht mehr abrufen kann.
|
||||
- Providerwahl, konkrete Einwilligungs-/Zugangsmechanik und Buchungsidentitäten sind integrationsbezogene Umsetzungsfragen.
|
||||
|
||||
### 3.5 Processing / KI (beschlossenes Grundmodell)
|
||||
- Processing Connectoren sind **Verarbeitungsdienste**, keine normale Ressourcenquelle; eigener Eingabe-/Ergebnisvertrag statt erzwungenem Source-Interface.
|
||||
- Wesentliche fachliche Fähigkeiten: **Extraktion, Klassifikation, Zusammenfassung, informationsgestützte Fragen, Beziehungsanalyse und Handlungsvorschläge**. Diese Fähigkeiten sind Aufgabenarten, nicht zwingend eigenständige APIs.
|
||||
- Eingaben können **Text, strukturierte Daten, Bilder und PDF-Dokumente** sein. Moderne multimodale APIs bzw. lokale Modelle können Original-PDFs/Fotos interpretieren; ein separater OCR-Dienst ist **optional, keine Pflicht**. Vorhandene Paperless-OCR-Texte sollen bei Eignung bevorzugt wiederverwendet werden.
|
||||
- Ausführung **lokal oder extern** entsprechend Datenfreigabe, unterstützter Modellfähigkeit und geeigneter Kosten-/Leistungsabwägung.
|
||||
- Verarbeitungsschritte dürfen **kombinierbar** sein. Keine neue umfassende KI-Agenten- oder Workflow-Plattform als Voraussetzung; bestehende Jinkendo-KI-Gateway-/Workflow-Blueprints bei konkret benötigten Modulen prüfen.
|
||||
- Ergebnisse umfassen nachvollziehbare **Quellreferenz, Quellstand, Verarbeitungsart und Prüfstatus**. Vorschläge (insbesondere Fristen und finanzielle Aussagen) werden nicht ungeprüft zu bestätigten Fakten oder automatischen Aktionen.
|
||||
- Wiederverwendbare Ergebnisse können persistiert werden; **reine Zwischenstände werden gelöscht**. Speicherort nach Datenrichtlinie, nicht generell lokal.
|
||||
- Die **Freigabe zur temporären externen Verarbeitung** ist ausdrücklich getrennt von der **Freigabe zur dauerhaften Cloud-Speicherung**.
|
||||
- Konkrete priorisierte KI-Use-Cases bleiben Produktentscheidungen; Beispiele begründen noch keine umfassende Workflow-Engine.
|
||||
|
||||
### 3.6 Storage (erweiterter Fähigkeitenbereich)
|
||||
- Storage dient der **konfigurierbaren, sicheren Ablage und dem autorisierten Abruf** von Artefakten: z.B. `.eml`-Archivkopien, strukturierte KI-Extraktionen, Zusammenfassungen, OCR-Volltexte oder temporäre Verarbeitungsdateien.
|
||||
- Storage ist **kein eigenes DMS**, keine Pflichtspiegelung aller Quelldaten und keine Wissens- oder Workflow-Engine.
|
||||
- Physische Speicherdienste können **lokal** (z.B. NAS, Dateisystem, objektbasierter Speicher) oder **zentral** bereitgestellt werden, soweit Datenrichtlinien dies zulassen.
|
||||
- Fachliche Zuordnung, Herkunft und Prüfstatus verwaltet Tsumugu als **Result Management**; die Storage-Schicht verwaltet Ablage, Abruf, Integrität, Lebensdauer und Löschanforderungen. Result Management ist zunächst eine logische Funktion, **kein neuer Pflicht-Microservice**.
|
||||
- Sonderregel IMAP bleibt bestehen: Aktivierte `.eml`-Archivkopien liegen **nur an einem konfigurierbaren lokalen Ablageort**, auch bei SaaS-Nutzung.
|
||||
|
||||
## 4. Ressourcen- und Referenzmodell
|
||||
|
||||
**Logische Konzepte – kein endgültiges Datenbankschema:**
|
||||
|
||||
| Konzept | Bedeutung |
|
||||
|---|---|
|
||||
| `Resource` | Tsumugu-interne stabile Identität eines referenzierten fachlichen Elements |
|
||||
| `ResourceLocator` | Einer von mehreren Zugriffswegen zur Ressource (z.B. IMAP-Original, NAS-Archivkopie) |
|
||||
| `ResourceMetadata` | Quellmetadaten, normalisierte Suchfelder und Herkunft; Tsumugu-eigene Metadaten fachlich getrennt |
|
||||
| `CollectionBinding` | Referenz auf Container/gespeicherte Abfrage mit Zuordnung zu einer Akte und dynamischer Mitgliedschaft |
|
||||
| `ConnectorInstance` | Konkrete konfigurierte Verbindung samt Identität, Fähigkeiten und Datenrichtlinien |
|
||||
| `DataPolicy` | Erlaubte Speicherung, Übertragung und Verarbeitung je Datenklasse/Connector-Instanz |
|
||||
|
||||
**Ressourcen-Lebenszyklus:** Eine live entdeckte Ressource muss nicht automatisch dauerhaft gespeichert werden. Eine explizit zugeordnete Ressource erhält eine stabile Referenz. Ressourcen können zusätzlich durch ausdrücklich konfigurierte Indexierung aufgenommen werden.
|
||||
|
||||
**Identität und Kopie:** IMAP-Original und gesicherte `.eml`-Kopie können mehrere Locator derselben Tsumugu-Ressource sein. Ein E-Mail-Anhang, der separat in Paperless eingegangen ist, ist grundsätzlich eine **eigene**, möglicherweise verknüpfte Ressource, nicht automatisch identisch. Ähnliche Inhalte werden nicht ungeprüft zusammengelegt.
|
||||
|
||||
**Änderungen:** Externe Pfade sind nicht notwendigerweise stabile IDs. Bei fehlendem Original bleibt die Aktenreferenz erhalten und zeigt einen differenzierten Auflösungs-/Verfügbarkeitsstatus; wo vorhanden wird eine autorisierte alternative Repräsentation genutzt.
|
||||
|
||||
## 5. Aktenzuordnung und dynamische Sammlungen
|
||||
|
||||
Festgelegt sind drei Grundfälle:
|
||||
|
||||
1. **Einzelreferenz:** bewusstes, dauerhaftes Verknüpfen einer Ressource mit einer oder mehreren Akten; bei Quellverschiebung bleibt die Verknüpfung bestehen.
|
||||
2. **Statische Auswahl:** aktuell ausgewählte Elemente werden einzeln referenziert; sie sind unabhängig von späterer Sammlungsmitgliedschaft.
|
||||
3. **Dynamische Sammlung:** Ordner, Sammlungen oder geeignete gespeicherte Suchregeln können Akten zugeordnet werden. Aktuelle und später hinzukommende passende Ressourcen werden dynamisch angezeigt, **ohne Originaldaten zu importieren**.
|
||||
|
||||
**Wichtige Abgrenzung:** Eine dynamische Sammlung erzeugt nicht zwingend dauerhafte Einzelreferenzen. Explizite Einzelreferenzen bleiben auch dann erhalten, wenn eine Ressource die Sammlung verlässt. Automatische KI-Bearbeitung/Fristauslösung wird daraus nicht abgeleitet.
|
||||
|
||||
**Noch offen:** Ob einzelne `CollectionBindings` bei Verlassen der Sammlung optional ein dauerhaftes Referenzieren aller bisherigen Mitglieder erlauben. Die zuletzt besprochene Empfehlung war *live/dynamisch als Standard, dauerhafte Übernahme optional*; dieser Zusatz wurde **nicht ausdrücklich endgültig entschieden**.
|
||||
|
||||
## 6. Datenhoheit, selektiver Index und temporäre Verarbeitung
|
||||
|
||||
| Datenklasse | Grundverhalten |
|
||||
|---|---|
|
||||
| Originaldokumente, E-Mail-Original, Dateien | Verbleiben in führender Quelle |
|
||||
| Quellreferenzen und technische IDs | Bei Verknüpfung dauerhaft in Tsumugu |
|
||||
| Tsumugu-eigene Akten, Notizen, Beziehungen, Aufgaben, Fristen, Finanzzuordnungen | Dauerhafte Tsumugu-Daten |
|
||||
| Relevante Quellmetadaten | Selektiv und freigegeben indexierbar für Suche/Fristen/Navigation |
|
||||
| Volltexte, OCR, PDFs, Vorschauen | Kein generelles permanentes Spiegeln; auf Abruf, bei Bedarf temporär |
|
||||
| KI-Arbeitstexte/-Zwischenergebnisse | Zweckgebunden und kurzlebig; definierter Standort, Aufbewahrung und Löschung |
|
||||
| KI-abgeleitete Metadaten | Vorschlag mit Herkunft/Prüfstatus; selektiv bestätigte Fakten in Tsumugu nutzbar |
|
||||
| Wiederverwendbare KI-Artefakte / Analysen | Optional dauerhaft im lokalen oder zentralen Artifact Storage, gemäß Daten- und Verarbeitungsrichtlinie |
|
||||
| `.eml`-Archivkopie | Nur am konfigurierten lokalen Ablageort, nicht im SaaS-Dateispeicher |
|
||||
| Zugangsdaten einer lokalen Quelle | Vertrauenswürdige lokale Connector Runtime; nicht als Nutzdaten an SaaS senden |
|
||||
|
||||
**Verbindliche SaaS-Option:** Kunden können **jede dauerhafte Cloud-Speicherung von Dokumentinhalten und KI-Artefakten deaktivieren**. Dann verbleiben zentral nur Tsumugu-eigene Akteninformationen, freigegebene Metadaten und Referenzen. Dies bedeutet **nicht**, dass bei gesondert genehmigter externer Analyse niemals Daten übertragen werden. Temporäre Übertragungen, Caches und Logs sind separat zu kontrollieren.
|
||||
|
||||
**Datenrichtlinien** gelten **pro Connector-Instanz und Datenklasse** und unterscheiden mindestens: *dauerhaft speichern*, *temporär zwischenspeichern*, *für Live-Funktion übertragen*, *an externen Processor weitergeben*. Konkrete Feldlisten/Schutzprofile werden **bei Implementierung des jeweiligen Connectors** festgelegt, nicht als globales Vollschema aller Quellen.
|
||||
|
||||
**Metadatenhoheit (bestätigt):** Quellmetadaten werden bei vorhandenen Schreibrechten **im führenden Quellsystem** bearbeitet; nach Erfolg wird der Tsumugu-Index aktualisiert. Tsumugu-eigene Felder bleiben separat. Kein automatisches Zurückschreiben von Tsumugu-Feldern in die Quelle. Bei konkurrierenden Änderungen möglichst Konflikterkennung statt stiller Überschreibung.
|
||||
|
||||
**Aktualisierung (bestätigte Richtung):** Bedarfsgesteuert beim Öffnen, ereignisbasiert wenn möglich und/oder periodisch. Standardmäßig referenzierte Ressourcen und dynamische Sammlungen; optionale umfassendere Indexierung. Live-Suche des gesamten berechtigten Quellbestands bleibt unabhängig davon möglich.
|
||||
|
||||
## 7. IMAP: dauerhafte Referenzen und optionale `.eml`-Sicherung
|
||||
|
||||
**Verbindlich beschlossen:** Jede IMAP-Connector-Instanz erhält eine Archivierungsoption:
|
||||
|
||||
| Modus | Verhalten |
|
||||
|---|---|
|
||||
| `automatic` (**Standard**) | Explizite Zuordnung einer E-Mail zu einer Akte löst lokale `.eml`-Sicherung aus |
|
||||
| `manual` | Sicherung nur auf Nutzeraktion |
|
||||
| `disabled` | Keine `.eml`-Archivierung |
|
||||
|
||||
- Bloße Mitgliedschaft in einer dynamischen Sammlung löst **keine automatische Sicherung** aus.
|
||||
- `.eml` wird über lokale Runtime am konfigurierbaren Ablageort, z.B. NAS, gesichert; nicht im zentralen SaaS.
|
||||
- Akteneintrag kann IMAP-Original und lokale Archivkopie als alternative Locator derselben Ressource kennen.
|
||||
- Erfolg erst nach geprüfter Ablage melden; Integritätsmerkmal (z.B. Prüfsumme), Zeitpunkt und Fehlerstatus festhalten.
|
||||
- Archivkopie ist **nicht automatisch revisionssicheres Archiv oder vollständige Backupstrategie**.
|
||||
- Der Zugriff auf lokale Archivkopien ist ebenfalls zu autorisieren; keine Erhöhung von Berechtigungen durch bloße Existenz einer Kopie.
|
||||
|
||||
## 8. Berechtigungs- und Sichtbarkeitsmodell
|
||||
|
||||
Der effektive Zugriff auf eine externe Ressource setzt voraus:
|
||||
|
||||
1. die Erlaubnis durch **Tsumugu** (Datenraum, Akte, Freigabe bzw. Connector-Nutzung), **und**
|
||||
2. die Berechtigung der **verwendeten Quellidentität** sowie die jeweilige Connector-Fähigkeit.
|
||||
|
||||
Pro Connector-Instanz können **individuelle Benutzerzugänge** oder ein **verwalteter gemeinsamer Zugang** genutzt werden. Bei gemeinsamem API-Key/Service-Konto darf dessen technischer Zugriff nicht unkontrolliert auf alle Tsumugu-Nutzer übertragen werden. Der Kontext des aufrufenden Nutzers und die zulässige Delegation sind bei jeder Operation relevant.
|
||||
|
||||
Die Suche und Navigation umfassen grundsätzlich den **vollständigen durch diese Rechte erreichbaren Quellbestand**, nicht bloß bereits gespeicherte Referenzen. Eine Aktenfreigabe allein darf keine unberechtigten externen Inhalte offenlegen. Offline-Status und fehlende Quellrechte müssen unterscheidbar angezeigt werden.
|
||||
|
||||
## 9. Präsentationsvertrag und UI-Grenze
|
||||
|
||||
Connectoren sollen neben Daten und Fähigkeiten **deklarative UI-Metadaten** liefern können (Ressourcentyp, Felder und Feldtypen, Labels, erlaubte Operationen, Navigationsstruktur, verfügbare Vorschau- oder Editorarten).
|
||||
|
||||
**Bevorzugte Stufen:**
|
||||
1. **Generische Tsumugu-Komponenten:** Baum/Navigation, Liste/Tabelle, Suche/Filter, Detail/Metadaten, Vorschau, Formular/Metadateneditor.
|
||||
2. **Registrierte, Tsumugu-eigene Spezialansichten:** z.B. E-Mail-Thread, Buchungsdetails oder PDF-Viewer, soweit fachlich nötig.
|
||||
3. **Von Connectoren gelieferter ausführbarer Frontend-Code:** **nicht Bestandteil der anfänglichen Zielarchitektur**; später nur bei nachgewiesenem Bedarf und mit eigenem Sicherheitskonzept.
|
||||
|
||||
Ziel ist **kein universeller Low-Code-UI-Generator** und keine vollständige Nachbildung der Oberflächen von Paperless, E-Mail-Clients oder Bankportalen. Der volle **berechtigte Datenbestand** ist navigier-/durchsuchbar; Bearbeitung wird nur für konkret angebotene Fähigkeiten umgesetzt.
|
||||
|
||||
## 10. Querschnittsfähigkeiten und Vertragsgrenzen
|
||||
|
||||
**Gemeinsamer Minimalvertrag für Source-artige Connectoren (konzeptionell):**
|
||||
- Identität, Instanz und angebotene Fähigkeiten ermitteln.
|
||||
- Navigation/Listen und Suche innerhalb der Quellrechte.
|
||||
- Ressource auflösen, Metadaten lesen, Inhalt/Vorschau bei Fähigkeit abrufen.
|
||||
- Unterstützte Schreib-/Exportoperationen autorisiert ausführen.
|
||||
- Änderungen erkennen bzw. selektiven Index aktualisieren, soweit unterstützt.
|
||||
- Verständliche Zustände melden: nicht erreichbar, nicht berechtigt, nicht auffindbar, veraltet, Konflikt, Fehler.
|
||||
|
||||
**Kein falscher Universalvertrag:** Banking benötigt transaktionale Semantik, KI einen Processing-Vertrag und lokaler Storage einen Ablage-/Abrufvertrag. Gemeinsame Technik wird nur bei konkret gemeinsamem Bedarf herausgezogen.
|
||||
|
||||
**Sicherheitsgrenzen:** Quellzugangsdaten geschützt verwahren; starke Authentisierung der lokalen Runtime gegenüber SaaS; Autorisierung pro Operation; keine willkürlichen Dateipfade und keine überprivilegierten Service-Accounts; sichere Vorschau/Rendering; kontrolliertes Egress und Löschung temporärer Daten. Konkrete Technologieentscheidungen werden in den zuständigen technischen Blueprints geprüft.
|
||||
|
||||
## 11. Storage- und Result-Management-Architektur (konsolidiert v0.2)
|
||||
|
||||
### 11.1 Verantwortlichkeiten
|
||||
|
||||
| Baustein | Verantwortlichkeit | Nicht seine Aufgabe |
|
||||
|---|---|---|
|
||||
| **Tsumugu Core / Result Management** | Verknüpft Ergebnis mit Akte/Ressource, kennt Herkunft, Quellstand, Status, Zugriffsrechte, Wiederverwendbarkeit und Speicherreferenz | Große Artefakte ungefragt in die Core-Datenbank aufnehmen |
|
||||
| **Artifact Storage** | Speichert/liest/löscht Inhalte, gewährleistet Integritätsprüfung, Version-/Ablagebezug und geregelte Retention | Fachliche Rechnungsinterpretation oder KI-Entscheidungen |
|
||||
| **Connector Runtime** | Autorisierter Zugriff auf lokale Quellen/Speicher; führt lokal erlaubte Ablage und Abholung aus | Umgehung von Quellrechten oder Datenrichtlinien |
|
||||
| **Processing Connector** | Erzeugt Ergebnisse aus explizit autorisierten Eingaben | Legt Datenresidenz oder Aufbewahrung eigenmächtig fest |
|
||||
|
||||
Das Modell unterstützt **eine fachliche Ressource mit mehreren Zugriffspfaden** (z.B. IMAP und gesicherte `.eml`-Kopie) und **mehrere aus ihr abgeleitete Artefakte** (z.B. OCR-Text, Extraktions-JSON, Zusammenfassung). Diese sind nicht mit dem Original identisch und müssen nicht im selben Speicher liegen.
|
||||
|
||||
### 11.2 Speicherentscheidung
|
||||
|
||||
**Kein pauschaler Vorrang lokaler Ablage.** Eine lokale Runtime kann langsam oder zeitweise unerreichbar sein; bei externer KI-Verarbeitung werden erlaubte Inhalte ohnehin zeitweise übertragen. Die Datenschutzwirkung hängt daher stärker vom **gesamten Datenfluss, Schlüsselzugriff und Verarbeitungsort** als nur vom physischen Speicherort ab.
|
||||
|
||||
Grundsätzliche Speicheroptionen:
|
||||
- **SaaS-/Managed-Storage:** Für ausdrücklich freigegebene abgeleitete Ergebnisse; gute serverseitige Verfügbarkeit. Verschlüsselung und kontrollierte Löschung sind Pflicht. Serverseitige Verschlüsselung allein bedeutet nicht, dass der Betreiber keine Klartextzugriffsmöglichkeit besitzt.
|
||||
- **Lokaler Storage:** Für sensible Inhalte oder Nutzerpräferenzen; lokale Verfügbarkeit hängt von Runtime/NAS und Verbindung ab. Lokale Verarbeitung kann tatsächliche Übertragung vermeiden.
|
||||
- **Hybrid:** Auswahl nach Datenklasse und Connector-Instanz, getrennt nach Speicherung, temporärem Zugriff und externer Verarbeitung.
|
||||
|
||||
**SaaS-Cloud-Content-Opt-out ist verbindlich:** Originalinhalte und KI-Artefakte müssen ohne dauerhafte Cloud-Speicherung verwendbar sein. Die dafür benötigten Tsumugu-eigenen Akteninformationen und freigegebenen Metadaten bleiben separat behandelbar.
|
||||
|
||||
### 11.3 Mindestfähigkeiten des Storage-Vertrags
|
||||
|
||||
1. **`put/get/delete`** für typisierte Artefakte (Dateien, Text, JSON etc.), nur nach Autorisierung und Policy-Prüfung.
|
||||
2. **Referenzen und alternative Speicherorte** statt ungefragter Binärkopien im Core; stabile Zuordnung zu Quellressource und ggf. Verarbeitungsstand.
|
||||
3. **Integrität und nachvollziehbarer Status:** Prüfsumme, erfolgreiche bestätigte Ablage, Unterscheidung zwischen vorhanden, nicht erreichbar, nicht autorisiert und nicht mehr vorhanden.
|
||||
4. **Version und Herkunft:** Ergebnis kann einem bestimmten Quell-/Analysezustand zugeordnet und bei Quelländerung als möglicherweise veraltet erkannt werden.
|
||||
5. **Aufbewahrung und Löschung:** Dauerhaft vs. befristet, Löschung inklusive geregelter Cache-/Backup-Fristen; keine falsche Garantie sofortiger physischer Löschung aller Sicherungskopien.
|
||||
6. **Sichere lokale Speicherpfade und Schlüsselverwaltung:** Kein vom Client frei vorgebbarer Dateisystempfad, keine Rechteausweitung durch Archivkopien.
|
||||
7. **Kontrollierbare Abrufwege:** Bei lokaler Ablage kann SaaS die Referenz anzeigen, aber Inhalte nur bei erreichbarer und autorisierter lokaler Runtime ausliefern.
|
||||
|
||||
Keine Pflicht zur universellen Dateiversionierung, geografischen Replikation, komplexen Storage-Abstraktion oder zentralen Search-Index-Engine für den MVP.
|
||||
|
||||
### 11.4 Wiederverwendung von KI-Ergebnissen
|
||||
|
||||
Ein Analyseergebnis darf nur dann als aktuell wiederverwendet werden, wenn Verarbeitungsaufgabe, Quellstand und Prüfstatus geeignet sind. Der Core verwaltet knappe, relevante Ergebnis-Metadaten; das größere Artefakt kann lokal oder zentral liegen. Fachliche Bestätigungen (z.B. ein akzeptierter Rechnungsbetrag) werden als Tsumugu-Daten geführt und nicht mit unbestätigten KI-Vorschlägen vermischt.
|
||||
|
||||
### 11.5 Betriebliche Mindestfragen – zur Umsetzung, nicht jetzt als Plattformprojekt
|
||||
|
||||
Für den Hybridbetrieb bleiben drei technische Klärungen: **(a)** sicherer SaaS-zu-Lokal-Kanal, vorzugsweise ohne eingehende Kundenports, **(b)** Autorisierung jeder Aktion einschließlich gemeinsamer Quellkonten, **(c)** Einrichtung, Updates und Verbindungs-/Versionskompatibilität der lokalen Runtime. Verfügbarkeit und erwartbare Abrufgeschwindigkeit sind bei der ersten produktiven Hybridstrecke praktisch zu messen.
|
||||
|
||||
---
|
||||
|
||||
## 12. Technische Referenzarchitektur und Umsetzungsmodus
|
||||
|
||||
Der separate Jinkendo-Architektur-Workstream betreut technische Standards/Blueprints (u.a. Auth/Scopes, Release/Recovery, KI-Gateway/Privacy, Workflows, Entitlements/Quotas, Medien/Rendering). **Tsumugu** liefert die fachlichen Modulanforderungen. Bei größeren Modulen wird zunächst geprüft, ob vorhandene Jinkendo-Implementierungen und Blueprints anwendbar sind. Neue Spezial-Blueprints nur **bei Bedarf**; keine pauschale Blueprint-Produktion. Konzepte sind nicht automatisch getestet oder produktionsreif.
|
||||
|
||||
**Schlanker Realisierungspfad (Vorschlag, keine freigegebene Roadmap):**
|
||||
1. Erstes durchgängiges Source-Szenario mit Paperless: Navigation/Suche → Referenzieren → Metadaten → Akte/Preview → Quell-Edit, falls nötig.
|
||||
2. Gemeinsame `Resource`/`Locator`/Berechtigungs-/Datenpolicy-Prinzipien anhand IMAP inkl. optionaler `.eml`-Sicherung validieren.
|
||||
3. Dynamische CollectionBindings, lokale Hybrid-Runtime und selektiver Index nach echten Use Cases absichern.
|
||||
4. Banking read-only und KI/Processing jeweils als begrenzte eigene Integrationen ergänzen.
|
||||
|
||||
Die Reihenfolge steht unter fachlichem MVP-Vorbehalt und ist keine Verpflichtung, alles vor dem ersten Release zu bauen.
|
||||
|
||||
## 13. Nur noch wesentliche offene Architekturfragen
|
||||
|
||||
| Thema | Klärung bei | Warum relevant |
|
||||
|---|---|---|
|
||||
| Hybrid-SaaS ↔ lokale Runtime: Verbindung, Vertrauensgrenze, Live-Zugriff | Vor Hybrid-Implementierung | Sicherheit, Erreichbarkeit, Datenschutz |
|
||||
| Datenprofile pro konkreter Connector-Instanz, inkl. Vorschau, Suche, Cache/Logs | Je Connector-Implementierung | Wirkliche Datenkontrolle statt nur Marketingversprechen |
|
||||
| Identität/Recovery beim Verschieben von IMAP-/Datei-Ressourcen | Bei IMAP-/Datei-Anbindung | Haltbare explizite Referenzen |
|
||||
| Rechte auf Akten-/Unterakten-/Ressourcenebene und Delegation gemeinsam genutzter Quellzugänge | Vor Mehrnutzer-Freigabe | Keine Datenlecks |
|
||||
| Dynamische Sammlung: optionale dauerhafte Übernahme bei Austritt | Wenn benötigt | Bewusst nicht festgelegt |
|
||||
| Konkrete KI-Use-Case-Priorität, Eingabe-/Ergebnisumfang und Freigaben | Vor KI-Funktion | Verarbeitung und fachliche Korrektheit |
|
||||
| Artifact-Storage-Adapter, Verschlüsselung/Schlüsselmodell, Retention und tatsächliche Löschwege | Vor Storage-Implementierung | Datenhoheit, Verfügbarkeit und Compliance |
|
||||
| Banking-Anbieter/Einwilligung und Datenfeldumfang | Vor Banking-Funktion | Technische und rechtliche Realisierbarkeit |
|
||||
|
||||
**Bewusst nicht jetzt vertiefen:** generisches Plugin-Sandboxing für UI-Code, universelle Editor-DSL, vollautomatisches Daten-Mirroring, jede mögliche Synchronisationskonfliktklasse, universelle KI-Workflow-Engine, zentraler Lizenz-/Billingdienst.
|
||||
|
||||
## 14. Status- und Entscheidungsspur
|
||||
|
||||
**Festgelegt in der aktuellen Unterhaltung (einschließlich Entscheidungen nach v0.1):** Dualer Betriebsansatz Self-Hosted/SaaS; Hybrid mit lokaler Runtime als bevorzugte Richtung; Daten überwiegend in Quellen; vollständige berechtigte Navigation/Suche; Rechte aus Quellsystem und Tsumugu; individuelle und gemeinsam verwaltete Quellzugänge; unterschiedliche Connector-Fähigkeiten; generische UI vor Connector-Frontend-Code; eigene Notizen/selektive Metadaten in Tsumugu; zeitweise Textverarbeitung; Referenzen und dynamische Sammlungen; explizite Referenzen trotz Ordnerwechsel; IMAP `.eml`-Archivmodi mit `automatic` als Standard, Archiv ausschließlich lokal; Quellmetadaten im Quellsystem editieren, eigene Tsumugu-Felder getrennt; standardmäßig referenzierte Ressourcen und dynamische Sammlungen aktualisieren, Vollindex optional; Banking zunächst read-only, keine gesamte Buchungshistorie standardmäßig, nur zugeordnete Buchungsreferenzen/-metadaten persistent; KI-Processing mit Text, Bild, PDF und strukturierten Daten sowie lokalen/externen Anbietern; bestehende OCR bevorzugt, multimodale PDF-/Bildinterpretation möglich; sechs grundlegende KI-Aufgaben, kombinierbare Verarbeitungsschritte, Wiederverwendung mit Herkunft/Prüfstatus; Ergebnisse lokal **oder** zentral nach Policy speicherbar; separate Datenfreigabe für externe Verarbeitung; ausdrücklicher SaaS-Schalter zum vollständigen Verbot dauerhafter Cloud-Speicherung von Dokumentinhalten und KI-Artefakten; Storage mit Artifact-Ablage, Integrität, Retention und Result Management.
|
||||
|
||||
**Architekturvorschläge, noch keine eigenständigen Beschlüsse:** Namen der logischen Objekte und APIs; konkrete UI-Deklarationsstruktur; drei konkrete Betriebsvarianten als technische Deployments; technischer Umsetzungsplan; Cache-TTLs, Protokolle und Feldlisten; optionale Sticky-Sammlung; konkrete API-Signaturen und Speichertechnologien, Verschlüsselungs-/Schlüsselimplementierung und Retrieval-/Verfügbarkeits-SLOs.
|
||||
|
||||
**Dokumentpflege:** Jede neue Entscheidung soll gezielt im betroffenen Abschnitt und in dieser Entscheidungsspur ergänzt werden. Keine stillschweigende Umdeutung der Tsumugu-Produkt-Baseline oder Erhebung einer Tsumugu-Lösung zum allgemeinen Jinkendo-Standard.
|
||||
Reference in new issue
Block a user