Files
tsumugu/docs/product/TSUMUGU_CONNECTOREN_BEFUND_2026-10-17.md
LarsandCursor 27cde035e8
Deploy Development / deploy (push) Successful in 27s
Test Suite / pytest-backend (push) Successful in 1m27s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 9s
Gib ein Uebergabepaket aus der bestaetigten Auswahl aus.
Die Dev-Umgebung soll die hierarchische Auswahl und das Paket pruefen koennen. Vorhandene Symbolaktionen der Inhaltszeilen bleiben im selben Stand.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-17 19:23:50 +02:00

8.9 KiB
Raw Permalink Blame History

Tsumugu – Befund zur Connector-Einbindung

Stand: 17.10.2026 · Zweck: Übergabe an die fachliche Planung. Keine neue Produktentscheidung und kein Implementierungsauftrag.

Geprüft wurde der Bestand in C:/Dev/tsumugu: ob Paperless und IMAP so gebaut sind, dass später weitere Connectoren dazukommen können. Jeder Connector braucht einen Zugang, eine innere Navigation auf die eigenen Inhalte, eine Vorschau und eine eindeutige Referenz auf das Inhaltselement.

1. Befund

Paperless und IMAP sind nicht modular. Sie teilen eine Hülle für Zugang und Referenz. Verhalten, Navigation, Vorschau und die stabile Adresse in der Quelle sind je Quelle fest eingebaut. Ein weiterer Connector lässt sich nicht nur registrieren.

Die Protokollarbeit selbst ist vorhanden und brauchbar: Paperless-Suche und Dateilesen, IMAP-Anmeldung, Fächer, Nachrichtenliste und Briefvorschau. Ein Umbau verschiebt diese Teile hinter eine gemeinsame Naht. Er schreibt sie nicht neu.

2. Was bereits fachlich feststeht

Diese Punkte stammen aus der Produktspezifikation und der UX-Ergänzung. Dieser Befund ändert sie nicht.

  • Paperless-Dokumentdateien bleiben im Archiv und werden referenziert. Tsumugu hält Herkunft und Anzeigedaten.
  • Externe Verweise, etwa auf eine E-Mail im IMAP-Konto, sind grundsätzlich möglich. Eine eigene Ablage gespeicherter E-Mails ist davon getrennt und hier nicht umgesetzt.
  • Eine E-Mail wird vor dem Übernehmen gelesen. Übernommen wird sie erst ausdrücklich. Paperless bleibt ein eigener Vorschauweg.
  • Bidirektionale Paperless-Metadaten und Finanzfunktionen folgen nach dem ersten Schnitt. Dieser Befund betrifft sie nicht.
  • Die UX-Ergänzung verbietet, für die laufende Inhaltsdarstellung eine neue Importplattform zu bauen. Ein späterer Connector-Umbau ist ein eigener Auftrag, keine Folge dieser UX-Vorgabe.

3. Gemeinsame Hülle im Bestand

Schicht Was sie heute leistet Grenze
Tabelle connectors Name, Art, Einstellungen und Geheimnis je Besitzer. Geheimnisse bleiben auf dem Server. Die Art ist auf paperless und imap geprüft.
Element external_ref Gemeinsamer Inhaltsträger, einbindbar wie Notiz und Datei. Die Herkunft steckt in der externen Referenz, nicht in einer Connector-Schnittstelle.
Tabelle external_references Quelle, externe ID, JSON-Detail. Die Art ist auf paperless, url und imap geprüft. Kein Eindeutigkeitsindex. connector_id ist nur bei IMAP ein JSON-Feld, keine Beziehung zum Zugang.
create_external und POST /api/v1/external-refs Erzeugt Element, Referenz, Einbindung und fachliche Daten an einer Stelle. Das Detailobjekt mischt Paperless- und IMAP-Felder.
Rechteprüfung vor dem Lesen Beide Vorschaupfade prüfen das Leserecht am Element. Danach verzweigt der Server nach Quellenname.

Daneben existiert POST /api/v1/sources/link mit einer engeren Quellenliste. Die Oberfläche übernimmt über POST /api/v1/external-refs. Die Art url steht in der Prüfliste und im API-Schema, hat aber weder Zugang noch Navigation noch Vorschau.

4. Fähigkeiten gegen den gewünschten Connector

Fähigkeit Paperless IMAP Gemeinsame Schicht
Zugang Adresse und API-Schlüssel. Ein Paperless pro Konto: ein zweites Speichern überschreibt das erste. Server, Benutzer, Passwort, SSL oder STARTTLS. Mehrere Konten. Dieselbe Tabelle. Die Kardinalität ist im Code fest.
Prüfen Zählt sichtbare Dokumente. Meldet sich am Postfach an. Eine Route POST /api/v1/connectors/{id}/probe, innen eine Verzweigung nach Art.
Innere Navigation Eine Suche. Ohne Zugangs-ID, immer das zuletzt angelegte Paperless. Keine Korrespondenten, Tags oder Ordner. Konto, Fächerbaum, Nachrichtenliste, Suche im offenen Fach, ältere Seiten. Keine gemeinsame Navigation. Eigene Routen unter /api/v1/sources/paperless und /api/v1/sources/imap.
Vorschau vor dem Übernehmen Nur die Trefferliste. Der Inhalt wird erst nach dem Einbinden geladen. Brief mit Absender, Empfänger, Text und Anhangsnamen. Übernehmen ist ein eigener Schritt. Nur der IMAP-Picker hat diese Vorschau.
Vorschau am Element Binärdatei über /api/v1/external-refs/{id}/content. PDF oder Bild. JSON über /api/v1/external-refs/{id}/mail. present.py kennt die Vorschauarten nur für diese beiden Quellen. Der Leser verzweigt auf den Quellnamen.
Referenz external_id ist die Paperless-Dokumentnummer. Der Zugang steht nicht an der Referenz. external_id ist die Message-ID. Fach, UID und connector_id liegen im JSON-Detail. Gleiche Spalten, andere Identität.

5. Die Referenz ist nicht stabil auflösbar

Tsumugu vergibt dem Inhaltselement eine eigene ID. Die Adresse in der Quelle ist davon getrennt. Dieselbe Paperless-Nummer oder dieselbe Message-ID kann mehrfach eingebunden werden.

Beim Lesen eines Paperless-Dokuments wählt der Server den zuletzt angelegten Paperless-Zugang des Besitzers. Ein Wechsel des Schlüssels lenkt alle bestehenden Referenzen um. Zwei Paperless-Instanzen kann ein Konto nicht auseinanderhalten.

Bei IMAP reicht die gespeicherte Message-ID nicht für die Vorschau. Aufgelöst wird über Fach und UID. Eine UID gilt nur in einem Fach und überlebt ein Verschieben der Nachricht nicht.

6. Wo ein weiterer Connector heute anstößt

Schicht Geschlossene Stelle Folge
Datenbank Prüflisten connectors_kind und external_references_source Neue Art braucht eine Migration.
API-Schema ConnectorIn.kind und ExternalIn.source Felder beider Quellen liegen in einem Modell.
Serverlogik backend/app/sources.py, backend/app/api/sources.py Suchen, Lesen und Prüfen sind Funktionen je Quelle.
Darstellung backend/app/present.py Die Vorschauart hängt am Quellnamen.
Oberfläche Sources.jsx, ReadingPane.jsx, content.jsx, widgets.jsx, Cases.jsx Bezeichnung, Picker und Leser verzweigen auf paperless und imap.

7. Technischer Zielzuschnitt, falls ein Umbau beauftragt wird

Das ist ein Zuschnitt aus der Codeprüfung, keine fachliche Festlegung.

Jede Quelle liefert fünf Operationen:

  1. Art, Anzeigename und ob ein Konto einen oder viele Zugänge haben darf.
  2. Zugang mit öffentlichen Einstellungen, serverseitigem Geheimnis und Prüfung am konkreten Zugang.
  3. Navigation an diesem Zugang. Sie liefert Knoten oder Inhaltselemente. Suche ist ein Filter darauf.
  4. Eine Vorschau am Element, nach Leserecht. Das Medium ist binär, Text oder strukturiert.
  5. Eine Referenz aus Zugangs-ID und externer ID, die diese Vorschau später wiederfindet.

Die Oberfläche bleibt eine Quellenliste, ein Browser und ein Leser. Der Leser wählt die Darstellung nach dem Medium. Der Fächerbaum bleibt die Darstellung der IMAP-Navigation, nicht ein zweiter API-Weg.

8. Aufwand

Schätzung des Coding-Agenten vom 17.10.2026 für eine Person, die den Bestand kennt. Paperless und IMAP verhalten sich danach wie jetzt. IMAP-Parsing und Paperless-Dateilesen werden verschoben.

Schritt Tage Inhalt
Vertrag und Daten 1–2 Prüflisten öffnen, Zugangs-ID fest an die Referenz binden, bestehende Paperless- und IMAP-Referenzen zuordnen.
Adapter 2 Paperless und IMAP hinter Prüfung, Navigation und Vorschau. Bestehende Tests bleiben grün.
Eine Lese-API 1–2 Navigation und Vorschau über den Zugang beziehungsweise das Element. Alte Quellenrouten danach entfernen.
Oberfläche 2–3 Quellenformulare, Picker und Leser auf das Medium umstellen.
Gesamt 6–9 Verhalten bleibt.

Nur die Servernaht, ohne die Oberfläche umzustellen, liegt bei 3–4 Tagen. Der nächste Connector muss die Oberfläche dann selbst mitbringen.

Nach dem ganzen Schnitt: ein schlichter Connector mit Suche und Dateivorschau etwa 1–2 Tage. Einer mit eigener Navigation, vergleichbar mit IMAP, etwa 3–4 Tage.

Größenordnung des betroffenen Bestands: backend/app/sources.py etwa 700 Zeilen, frontend/src/pages/Sources.jsx etwa 570 Zeilen, Tests backend/tests/test_mailboxes.py und backend/tests/test_paperless_files.py.

9. Was daraus nicht folgt

  • Kein Auftrag, den Umbau jetzt umzusetzen.
  • Keine neue Importplattform und keine Änderung an Paperless-Originalen.
  • Keine bidirektionale Metadatensynchronisation.
  • Keine Entscheidung, ob dieselbe Quelle nur einmal eingebunden werden darf.
  • Keine Entscheidung, ob ein Konto mehrere Paperless-Zugänge haben muss.
  • Keine Aussage, welcher Connector als nächster fachlich gebraucht wird.

10. Nur bei einem Umbauauftrag zu klären

  1. Darf dieselbe externe ID im selben Zugang mehrfach eingebunden werden, oder ist die Referenz je Zugang eindeutig?
  2. Braucht ein Konto mehr als ein Paperless, oder bleibt genau ein Paperless fachlich richtig?
  3. Reicht als stabile IMAP-Adresse die Message-ID, wenn Fach und UID sich ändern können? Die heutige Vorschau hängt an Fach und UID.
  4. Bleibt url eine externe Referenz ohne Zugang, oder fällt die Art aus der Connector-Liste?