Files
tsumugu/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md
StommerandClaude Sonnet 5.5 2f7de33049
Deploy Development / deploy (push) Successful in 46s
Test Suite / pytest-backend (push) Successful in 5m58s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 22s
Ziehe die Fähigkeiten von Paperless und IMAP in ihr Modul und entferne die unbenutzte Filterliste.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-24 22:23:46 +02:00

20 KiB
Raw Permalink Blame History

Abschlussmatrix der Connector-Kapselung

Stand: 19.10.2026. Die Kriterien stehen in TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md und haben Vorrang vor dem Zwischenstand in TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md.

Kein Push und kein Deployment. Die Suite lief gegen tsumugu_local_test: 71 Tests, Exitcode 0. Der Produktionsbau des Frontends ist durchgelaufen. Paperless und IMAP sind in den Tests nachgebildet. Es gab keinen Abruf einer lebenden Anlage.

Korrektur am selben Tag: Der Start hat die Module noch nicht geladen. Bestehende Referenzen ohne gespeicherte Instanz blieben unresolved, Akte und Vorgang zeigten sie als nicht zugeordnet. Die Vorbereitung registriert die Module jetzt vor dem Abgleich. Ein eindeutiger Bestand wird gebunden und lässt sich wieder öffnen. Mehrere Zugänge ohne gespeicherte Instanz bleiben bewusst offen, die Akte selbst bleibt lesbar. Liste, Prüfung und Suche sehen nur Zugänge des angemeldeten Kontos. Ein freigegebener Vorgang nutzt den Zugang des Owners nur für die konkrete Referenz und nur mit use_owner_sources. Die Suite dazu: 74 Tests, Exitcode 0.

Matrix

Kriterium Nachweis Ergebnis
Bestehendes System über die neue Anbindung Suite, darunter test_connector_basis.py, test_owner_sources.py, test_export.py, test_mailboxes.py, test_correspondence.py Bestanden. Einrichten, Prüfen, Suche und Fachnavigation, Lesen, Einbinden, Download und Export laufen über die registrierten Module. Dateien, Notizen, Anlagen, Unterkapitel und Versandfassungen bleiben in derselben Suite grün.
Vollständige Kapselung sourceregistry.py, sources.py, generische Routen in api/sources.py, Reader über preview.media Bestanden für die heute unterstützten Formate. Fähigkeiten beschreiben die ausführbaren Operationen. Nicht erklärte Filter und unbekannte Arten antworten 422.
Weiterer Connector backend/tests/test_sample_source.py Bestanden. Der Testadapter sample sucht, zeigt Text, bindet, öffnet die Bytes erneut und exportiert sie. Fachseiten, Schema, Reader und Export enthalten die Art nicht.
Erweiterungsweg dieselben Testdateien und frontend/src/sources/sample-source.js Bestanden. Anleitung unten. Kein dritter produktiver Dienst und keine Sonderoberfläche.
Rechte derselbe Test plus die bestehende Owner-Suite Bestanden. Fremder Abruf ist 404. Ohne use_owner_sources bleibt das Original unerreichbar. Mit der Freigabe liefert der Zugang des Owners nur diese Referenz. Nach Entzug wieder 404. Eine Notizbearbeitung der Referenz ist serverseitig unsupported.
Storage und Schutzprofil test_connector_basis.py Bestanden als Vertragsnachweis. Zwei Adapter, stabile Referenzen, gesperrtes Profil ohne Klartext. Keine implementierte Verschlüsselung.
Migration und Betrieb Migration 20261019T150000Z_source_registry.sql, bestehende Bestandsfälle, Frontend-Build Bestanden. Prüflisten der Arten sind entfernt. Produktive Datenbanken wurden nicht verwendet.
Reststellen gezielte Suche in Fachseiten, Reader, Export, Schema und Ablage Bereinigt, soweit die Fundstelle eine Typenliste war. Zulässige Fundstellen stehen unten.

Anleitung für einen neuen Connector

Für den Nachweis wurden nur diese Dateien neu angelegt:

  • backend/tests/sample_source.py registriert das Modul im Testprozess und wieder ab.
  • backend/tests/test_sample_source.py prüft Konfiguration, Suche, Vorschau, Einbindung, erneutes Öffnen, Export und Rechte.
  • frontend/src/sources/sample-source.js trägt dasselbe Modul in die Oberflächenregistrierung ein. Die Anwendung importiert diese Datei nicht.

Ein produktiver Connector folgt demselben Schnitt:

  1. Ein Modul liefert Konfiguration, Prüfung, Suche, optional Navigation und Vorschau, Originalabruf und Export. register_source hängt es im Composition Root ein.
  2. Die Fähigkeiten nennen nur Operationen, die das Modul ausführt. Die generische Suche lehnt andere Filter ab.
  3. Die Oberfläche ruft registerSourceModule auf. Ohne eigenes Formular oder ohne eigene Auswahl gilt die Standardhülle. manual erlaubt die schlichte Referenzerfassung. Eine bereits unterstützte Darstellung (pdf, image, text, email) braucht keinen neuen Reader.
  4. Ein bisher nicht dargestelltes Format braucht eine neue registrierte Darstellung. Das ist kein Eingriff in Akten, Vorgänge oder den Exportablauf.
  5. Die Art kommt nicht in eine Datenbankprüfliste und nicht in ein zentrales Enum.

Zulässige verbleibende Quellkenntnis

  • Protokoll, Konfiguration und Auswahl von Paperless und IMAP in backend/app/sources.py und frontend/src/pages/Sources.jsx.
  • Kompatibilitätsrouten /api/v1/sources/paperless/documents und /api/v1/sources/imap/*. Sie delegieren an dieselbe Suche, Navigation und Vorschau.
  • Die Darstellung email liest über die bestehenden Mail-Endpunkte. Deren Bytes liefert heute das IMAP-Modul. Eine weitere Quelle mit den Darstellungen pdf, image oder text braucht diese Endpunkte nicht.
  • Historische Migrationen, Testdoubles und die Dokumentation.
  • Der Paperless-Dateizugriff auf ein lokales Archiv bleibt im Connector-Modul. Eigene Uploads und Versandfassungen schreiben über den Storage-Port. Die Anfrage räumt danach nur Pfade ab, die der Adapter selbst veröffentlicht hat. Die Fixture-Bereinigung löscht Bestandsdateien an derselben Objektkennung.

Grenzen vor der Nacharbeit

Dieser Absatz beschreibt den Stand vor der Nacharbeit am selben Tag. Die Anfrage-Transaktion umfasste damals noch den Quellabruf. Zugangsdaten liegen als Klartext in connectors.secret. Es gibt keine neue Verschlüsselung und keinen Remote-Speicher. Der Testadapter ist kein produktiver Dienst.

Nacharbeit am 19.10.2026

Auftrag: TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md. Die historische Suite oben bleibt unverändert. Die neue Suite tests lief danach mit 82 Tests, Exitcode 0. Der Paperless-Filtertest wurde nach der Relevanzzuordnung einzeln erneut ausgeführt und ist grün. Der Frontend-Build ist durchgelaufen. Kein Push und kein Deployment.

IMAP, Paperless-Treffer und der Speicheradapter in test_connector_followup.py sind nachgebildet. Das ist kein lebender Postfach- oder Dokumentabruf. Die laufende Paperless-Instanz paperless-webserver-1 wurde nur am Schema gelesen: Paperless-ngx 2.20.6. query ist die Volltextsuche, title__icontains das eigene Titelfeld, tags__id__all die Und-Verknüpfung, created das Dokumentdatum neben added und modified. score ist kein Sortierfeld. Eine Suche ohne ordering ist dort die Relevanzreihenfolge. Dokumentinhalte wurden nicht gelesen.

Paket Nachweis Ergebnis
A Gemeinsamer Zugriff, Darstellung, Speicher sourceaccess.py, Briefkasten-Test ohne IMAP, Speicherstest über adapter_for Bestanden in der nachgebildeten Suite. Upload, erneutes Lesen, Versandfassung, Export und Löschen laufen über die aufgelöste Instanz. Fehlende Instanzzeile bleibt der bisherige lokale Pfad.
B IMAP-Seiten test_large_folder_is_bounded_and_a_late_hit_is_not_empty, Fehler- und UIDVALIDITY-Tests Bestanden gegen den nachgebildeten Server. Ein Fach mit Lücken bleibt seitenweise begrenzt. Ein Treffer hinter der ersten Seite ist kein leeres Fach. NO, abgebrochene Köpfe und ein UIDVALIDITY-Wechsel sind eigene Zustände. Ein lebendes Postfach wurde nicht geprüft.
C Paperless-Suche Filtertest und Schema 2.20.6 Bestanden gegen den nachgebildeten Abruf und das gelesene Schema. Inhalt, Titel, Korrespondent, Typ, mehrere Tags, Dokumentdatum, Seite 3 und zwei Instanzen derselben Dokumentnummer sind getrennt. Eine Suche in den echten Dokumenten steht aus.
D Markdown-Notiz Notiztest und Browser am lokalen Testkonto Bestanden für gemeinsamen Text, Export, Leserecht und Konflikt. Die formatierte Bearbeitung mit @mdxeditor/editor 3.52.4, MIT, ist im Browser geöffnet worden: Leiste, Quelltextumschaltung, gespeicherte Ansicht, Abbrechen. Ein Listenstrich und ein Stern gelten beim Öffnen als dieselbe Liste. Jede andere Abweichung bleibt im Quelltext. markdown_file bleibt aus.

Anleitung für ein weiteres Modul

Ein Quellenmodul registriert sich mit register_source und liefert nur Fähigkeiten, die es ausführt. Die Oberfläche ruft registerSourceModule auf und ersetzt die Registrierung nicht. Eine bekannte Darstellung wird mit registerRepresentation gebunden; die Notiz nutzt markdown → note und erscheint nicht unter Quellen. Ein Speicheradapter kommt in die Fabrik von adapter_for und wird über die gespeicherte Instanz aufgelöst. Ein Editor hängt an derselben Ressourcenansicht. Fachseiten, Rechte und das Schema zählen die Art nicht auf.

Weiterhin zulässige Quellkenntnis

  • Protokoll, Konfiguration, Suche und Auswahl von Paperless und IMAP in backend/app/sources.py und frontend/src/pages/Sources.jsx.
  • Die Kompatibilitätsrouten delegieren an dieselben Dienste.
  • Die Darstellung email öffnet das registrierte Modul und danach den gemeinsamen Mail-Leser.
  • Stammdaten, Seitenzahl und Vorschau bleiben an Instanz und Recht gebunden.
  • Historische Migrationen, Testdoubles und diese Dokumentation.

Laufzeit und Erweiterbarkeit

Der Netzwerkabruf wird vor dem externen Aufruf aus der offenen Fachtransaktion gelöst und danach auf Recht und Instanz geprüft. Große IMAP-Fächer lesen begrenzte UID-Fenster, nicht die gesamte Liste je Seite. Paperless-Seiten sind die eigene Seitennummer, keine weitergereichte Fortsetzungsadresse. Die Erweiterung um eine Quelle, eine Darstellung oder einen Editor braucht kein neues Rechtsschema. Eine neue Speicherart braucht eine Fabrik und bleibt an die gespeicherte Instanz gebunden. Es gibt keine zusätzliche Verschlüsselung und keinen weiteren Produkt-Speicher.

Korrektur am 20.10.2026

Auftrag: TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md. Die Befunde vom selben Tag bleiben unverändert. Die historische Suite oben bleibt unverändert. tests/test_correction_k1_k7.py lief danach mit 7 bestandenen Tests. Export, Connector-Nacharbeit und Connector-Basis liefen in derselben lokalen Testdatenbank mit 26 bestandenen Tests. Die Versandtests liefen mit 3 bestandenen Tests. Der Frontend-Build ist durchgelaufen. Kein Push und kein Deployment.

Die Bedienprüfung lief gegen eine lokale API mit nachgebildetem IMAP und einem verzögerten Paperless-Stellvertreter. Das ist keine Prüfung des bestehenden Postfachs und keine Dokumentabfrage der bestehenden Paperless-Instanz.

Korrektur Geändertes Verhalten Nachweis Ergebnis Grenze
K1 Ordnernamen Fachnamen, die kein IMAP-Atom sind, werden gequotet. INBOX bleibt ungequotet. Ein Fach mit gemeldetem Bestand und leerer abgeschlossener Liste gilt nicht als leer. Synthetisch: test_mailbox_names_are_quoted_protocol_strings, test_a_filled_folder_with_spaces_is_not_reported_empty. Bedienung: der Stellvertreter erhielt INBOX und "Sent Items"; Sent Items zeigte Nachrichten und die Richtung Ausgang. Synthetisch und in der Bedienung bestanden. Das bestehende Postfach mit mehr als 4.000 Nachrichten wurde nicht gelesen.
K2 MIME Eine Auswertung für Vorschau, Leser und Export. Anzeigename und Archivname sind getrennt. HTML wird bereinigt; die Textfassung ist gekennzeichnet. Eine angehängte Nachricht bleibt eine Anlage. Synthetisch: test_parse_mail_keeps_names_html_and_attached_messages, test_preview_below_and_above_the_limit_uses_the_same_parts. Bedienung: Tabelle, A & B, Dateiname Buero Uebergabe.pdf, keine Skripte, keine fremde Bildadresse, Textfassung sichtbar. Synthetisch und am Stellvertreter bestanden. Keine Nutzermail. Bytezahl und SHA-256 zwischen Download, ZIP und Originalanlage einer betroffenen Mail sind nicht verglichen.
K3 Transaktion IMAP-Lesen, Export und Dateiveröffentlichung laufen ohne offene Fachtransaktion. Der Fachabschluss folgt danach. Ein fehlgeschlagener Abschluss lässt weder den Eintrag noch die veröffentlichten Bytes stehen. Synthetisch: test_upload_and_mail_fetch_leave_the_domain_transaction sah IDLE am Upload und am Mailabruf. test_failed_conclusion_keeps_no_partial_file ließ keinen Eintrag und keine Prüfbytes zurück. Die bestehenden Versandtests blieben grün. Für diese beiden Grenzen bestanden. Entzug während der Veröffentlichung und ein gleichzeitiger Versionskonflikt sind nicht eigens geprüft.
K4 Markdown Der Leser nutzt einen Markdown-Renderer für die Ebenen 1–6, verschachtelte Listen und den Listenstart. HTML, javascript:-Links und externe Bilder werden nicht ausgeführt. Markup-Prüfung der Leserhülle. Bedienung: gespeicherte Notiz mit den genannten Strukturen, Vorschau aus dem Quelltext, Abbrechen stellt die Ansicht wieder her. Bei 360 und 390 px kein Überlauf, Schaltfläche 44 px. Lesen und Quelltextvorschau bestanden. Die formatierte Leiste öffnete diese Notiz nicht, weil sie den gespeicherten Text verändert hätte. Der Quelltext blieb maßgeblich.
K5 Registrierung Die Leserhülle ruft die registrierte Darstellung auf. Die Beispielquelle bringt Formular und Registrierung in ihrem eigenen Modul mit und erscheint in der Produktauslieferung nicht. Die Leserhülle rendert die Testdarstellung und speichert über den registrierten Testeditor. Bedienung mit ?probe=1: Beispielquelle verbinden, nach „Proben“ suchen, übernehmen, öffnen, erneut öffnen, Übergabepaket prüfen und herunterladen. Der Download antwortete mit 200; der Prüfstand nannte Probenbrief/Probenbrief.txt. Bestanden in der Testoberfläche. Die Beispielquelle ist kein Produktzugang.
K6 Paperless-Antworten Eine verspätete Suche oder Facette schreibt nicht in die inzwischen gewählte Instanz. Der Instanzwechsel leert Filter und Trefferliste. Bedienung am Stellvertreter: Suche auf „Alt“ starten, zu „Neu“ wechseln, die späte Antwort abwarten. Zugang, leere Suche und Facette blieben bei Neu. Die anschließende Suche zeigte „Treffer Neu“. Schließen während einer laufenden Suche ließ die Vorgangsliste unverändert. In der Bedienung bestanden. Keine echte Paperless-Instanz.
K7 Filter und reale Quellen Der synthetische Paperless-Abruf filtert den Katalog nach Inhalt, Titel, Metadaten, Datum und Seite. test_paperless_filters_change_the_hits: nur der Inhaltstreffer, nur Titel „Vertrag“, die kombinierte Teilmenge und die zweite Seite unterscheiden sich. Synthetisch bestanden. Weder die bestehende Paperless-Dokumentabfrage noch das bestehende Postfach wurden ausgeführt. Schema-Lesen vom 19.10. ersetzt das nicht.

Konfigurationsansicht am 20.10.2026

Die Konfiguration einer Instanz gehört dem Modul. Ein Modul deklariert config_fields (ConfigField in backend/app/sourceregistry.py) und optional normalize_config für Protokollprüfungen. parse_fields validiert Pflicht, Typ, Grenzen und unbekannte Schlüssel; ein leeres Geheimnisfeld behält das gespeicherte. /api/v1/sources/capabilities liefert die Felder unter modules. Die Oberfläche (frontend/src/sources/config-form.jsx, connector-config.jsx, Route sources/:connectorId) rendert sie generisch; ein Modul kann mit Form im UI-Registereintrag eine eigene Maske mitbringen. Paperless (Adresse, API-Schlüssel) und IMAP (Server, Port, Verbindung, Benutzer, Passwort, Standardfach) sind darauf umgestellt; die flachen Felder der ersten Lieferung bleiben nur als Kompatibilität in ConnectorIn.

Neuer Connector: Modul mit config_fields in register_source eintragen, UI-Modul mit registerSourceModule registrieren. Kein Eingriff in ConnectorIn, Sources.jsx oder die Fachseiten.

Nachweis und Grenzen: backend/tests/test_connector_config.py (Manifest, Geheimnis, Instanzerhalt, Fremdzugriff, Prüfstand) und frontend/src/sources/config-core.test.mjs (6 Node-Tests bestanden), Frontend-Build erfolgreich. Die Backend-Tests wurden in dieser Umgebung nicht ausgeführt (kein Python, keine PostgreSQL-Instanz). Keine Bedienprüfung im Browser. Zugangsdaten bleiben im Klartext (R-05); Archivmodus und DataPolicy sind nicht Teil dieses Schnitts.

Paperless-Suche, Erweiterung am 24.10.2026

Auf Wunsch des Nutzers erweitert über den Umfang von Abschnitt C des Nacharbeitsauftrags hinaus: Suchart (Titel und Inhalt als Standard ohne Index, nur Titel, nur Inhalt, Volltextindex), Speicherpfad, Tag-Verknüpfung (alle, mindestens eines, keines), „ohne“ bei Korrespondent, Typ und Pfad, Hinzugefügt-Datum, Archivnummer und Zusatzfelder. Dazu eine Trefferkarte mit Vorschaubild, Textauszug, Tags, Typ und Seitenzahl sowie ein großer Dialog mit Filtern links und Treffern rechts. Zusatzfeld-Abfragen waren im Auftrag ausdrücklich kein Pflichtumfang und sind hier auf Nutzerwunsch dazugekommen.

Verantwortung im Modul: Die Filternamen eines Moduls deklariert SourceModule.search_params (Parametername auf Fähigkeitsflag). Die gemeinsame Suchroute kennt keinen Filternamen mehr. Sie reicht alle übrigen Abfrageparameter weiter und weist jeden ab, den das Modul nicht deklariert oder dessen Fähigkeit nicht wahr ist. Das gilt auch für unbekannte Parameter. Das Vorschaubild ist eine optionale Modulfähigkeit (SourceModule.thumbnail, Route /api/v1/sources/{kind}/thumbnail, Flag search.result_preview). Ein Modul ohne Deklaration lehnt es mit 422 ab.

Verbleibende Quellkenntnis im allgemeinen Code (zulässig): Die Kompatibilitätsrouten /api/v1/sources/paperless/documents und .../preview in backend/app/api/sources.py delegieren nur und tragen keine eigene Protokoll- oder Rechtelogik. Die Fähigkeiten von Paperless und IMAP stehen jetzt in backend/app/sources.py beim jeweiligen Modul; backend/app/sourceport.py enthält nur noch die Editorfähigkeiten und die Nutzlasten. Die unbenutzte Liste UNSUPPORTED_SEARCH und unsupported_filters sind entfernt. In der Oberfläche liegt der Paperless-Auswahldialog in frontend/src/pages/Sources.jsx und wird über registerSourceModule (large: true) eingehängt; Fachseiten und Modal kennen nur das allgemeine Flag.

Nachweis Ergebnis
Backend-Suite gegen tsumugu_local_test (eingebettete PostgreSQL, Wegwerf-Umgebung) 164 Tests bestanden
test_connector_followup.py: Parameterübertragung je Filter, Standardsuche, Textauszug, Namensauflösung, Zusatzfelder samt Ablehnung ungültiger Eingaben, fremder Filter und unbekannter Parameter 422, Vorschaubild nur für Raster, fremde Instanz 404 bestanden, gegen Attrappe
Bedienung im Browser (Chrome headless, Desktop 1440×900 und 390×844) gegen die echte Oberfläche, die echte API und einen nachgebildeten Paperless-HTTP-Server: Dialoggröße, Suche, Vorschaubilder, Textauszug, Ansicht in der Karte, unvollständige Zusatzfeld-Zeile meldet statt zu senden, Zusatzfelder gehen als custom_field_query hinaus, Blättern erhält die Auswahl, Einfügen, keine Konsolenfehler 38 von 38 Prüfungen bestanden. Dabei ist ein Überlappen von Filtern und Treffern auf 390 px gefunden und behoben worden.

Grenze: Keine der Prüfungen lief gegen die echte Paperless-Instanz. Die Parameternamen (title_content, tags__id__none, storage_path__id, added__date__gte, archive_serial_number, custom_field_query) stammen aus der Kenntnis der Paperless-ngx-API und stehen am Stellvertreter, nicht an der Nutzerinstanz belegt. Die Flags custom_fields und result_preview sind damit nur durch Code und Attrappe ausführbar belegt. Offen sind insbesondere der Wert eines Betragsfelds (reine Zahl ohne Währung), der Textauszug im Volltextindex und die Mindestversion für Zusatzfeld-Abfragen. Eine Prüfung an der echten Instanz braucht eine ausdrückliche Freigabe.