17 KiB
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
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:
- Verbindungseinrichtung mit gemeinsamer Hülle und quellenspezifischen Zugangsfeldern.
- Quellenbrowser: Navigation, Suchbereich, Filter, Ergebnisse, Paging, erhaltene Auswahl und Vorschau.
- Übernahme: gewählte Ressourcen, aktiver Vorgang/Akte, Kapitel und sichtbare Wirkung; erfolgreiche Teilübernahmen und Wiederholungen nachvollziehbar behandeln.
- Ressourcenleser nach Darstellungsart: PDF, Bild, Text/Markdown, E-Mail einschließlich Anlagen und Metadatenformular.
- 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
- Aktuellen Bestand und Tests erfassen; nur betroffene Schutz- und Blueprint-Abweichungen in den Schnitt aufnehmen.
- Registrierten Source-Vertrag mit vorhandenen Paperless-/IMAP-Funktionen implementieren. Alte Routen bei Bedarf als kurzlebige delegierende Kompatibilitätsadapter erhalten; keine doppelte Fachlogik.
- 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.
- 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.
- 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.
- 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.