commit 7662661641df34833f454b3fcab090d5a16b986c Author: enchiriadis Date: Tue Aug 18 13:05:45 2026 +0000 Automatisierter Belegversand für DEVONthink hinzugefügt diff --git a/Automatisierter-Belegversand-f%C3%BCr-DEVONthink.md b/Automatisierter-Belegversand-f%C3%BCr-DEVONthink.md new file mode 100644 index 0000000..8983012 --- /dev/null +++ b/Automatisierter-Belegversand-f%C3%BCr-DEVONthink.md @@ -0,0 +1,311 @@ += Belegversand = + +== Übersicht == + +'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen. + +; Version: 1.4 +; Plattform: macOS 10.13+ +; Abhängigkeiten: DEVONthink 3.x, Apple Mail +; Lizenz: Privatgebrauch +; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation + +== Installation == + +=== Voraussetzungen === + +* macOS 10.13 oder neuer +* DEVONthink 3.x +* Apple Mail +* AppleScript-Zugriff in Systemeinstellungen aktiviert +* Git (zum Klonen des Repositories) + +=== Schritt-für-Schritt Anleitung === + +==== 1. Verzeichnisstruktur anlegen ==== + + +mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/ +cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/ + + +==== 2. Repository klonen ==== + + +git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand +cd Belegversand + + +==== 3. Scripts kompilieren ==== + +Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden! + + +chmod +x compile.sh +./compile.sh + + +Erwartete Ausgabe: + +Compiliere Belegversand AppleScripts... +✓ Fertig! + + +==== 4. Erste Ausführung ==== + +# DEVONthink öffnen +# Ein Objekt in der gewünschten Datenbank auswählen +# Scripts → START aufrufen +# Dialog folgen → Setup wird durchgeführt + +Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink. + +== Wichtig: .applescript vs. .scpt Dateien == + +Im Repository gibt es zwei Arten von AppleScript-Dateien: + +; .applescript: Quelldateien (lesbar, nur für Entwicklung) +; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt) + +'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen. + +Das `compile.sh`-Script: +# Kompiliert alle `.applescript` zu `.scpt` +# Löscht anschließend die `.applescript`-Dateien +# Hinterlässt nur funktionsfähige `.scpt`-Dateien + +Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten. + +== Konfiguration == + +=== Automatische Initialisierung === + +Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink: + + +_config/ +├── belegversand.conf # Konfigurationsdatei +├── mail_vorlagen/ # Mail-Templates +│ └── belegversand # Standard-Template +├── README-Belegversand # Interne Hilfe +└── [weitere Dateien nach Versand] + + +=== Konfigurationsdatei === + +Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`. + +==== Wichtigste Parameter ==== + +; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com) +; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional) +; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand") +; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen) +; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet") +; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet") +; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false) +; SHOW_README: Willkommensdialog beim Start anzeigen (true/false) +; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen") +; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand") +; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei + +==== Multiple Empfänger (CSV-Format) ==== + +Mehrere E-Mail-Adressen können durch Kommas getrennt werden: + + +MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com +MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com + + +Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt. + +== Verwendung == + +=== Grundablauf === + +# Belege in DEVONthink auswählen (Mehrfachauswahl möglich) +# Scripts → START aufrufen +# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?) +# Dry-Run Vorschau anschauen (optional) +# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt + +=== Menü-Befehle === + +; START: Haupteinstiegspunkt — startet Setup oder Versand +; About...: About-Dialog mit Versionsinformation und Links + +=== Booking-Jahr Enforcement === + +Das System verhindert Versandvermischung über mehrere Jahre: + +; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen +; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs +; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt + +Beispiel-Struktur: + + +Belege/ +├── 2026/ +│ ├── 01_Januar/ +│ ├── [weitere Monate] +│ └── Versendet/ [← Logs für 2026-Versand] +├── 2027/ +│ ├── 01_Januar/ +│ ├── [weitere Monate] +│ └── Versendet/ [← Logs für 2027-Versand] +└── Provisionsabrechnungen/ + └── [← Separate Outsider-Logs] + + +=== Dry-Run Modus === + +Vor jedem echten Versand kann ein Dry-Run durchgeführt werden: + +# Simuliert den kompletten Versandprozess +# Erstellt Vorschau-Datei mit allen Details +# Zeigt Dialog mit Zusammenfassung +# User kann bestätigen oder abbrechen + +Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar). + +=== Mail-Drafts === + +Das System erstellt keinen automatischen Versand, sondern Mail-Drafts: + +# ZIP-Archive werden erzeugt +# Apple Mail öffnet mit neuem Draft (nicht gesendet!) +# User kann Template prüfen, weitere Empfänger hinzufügen +# Benutzerdefinierter Versand per Knopfdruck in Mail + +Dies ermöglicht volle Kontrolle über den Versand. + +=== Mail-Templates === + +Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`). + +Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind. + +Beispiel-Template: + + +Sehr geehrte/r Frau/Herr, + +beiliegend erhalten Sie die angeforderten Unterlagen. + +Mit freundlichen Grüßen + + +== Protokollierung == + +=== NDJSON-Logs === + +Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung: + + +{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"} +{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"} +{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"} + + +=== Markdown-Logs === + +Menschlich lesbar mit Übersichten nach Versandlauf: + + +# Belegversand Logs — 2026 + +## Versandlauf 2026-01-15 10:30 +**Versendete Belege:** 5 Stück +**Empfänger:** recipient@example.com +**ZIP-Datei:** belegversand_2026-01-15_103045.zip +**Passwort:** [konfiguriert] +**Status:** Erfolgreich + +### Versandte Dokumente +- Invoice-001 (UUID: abc123...) +- Invoice-002 (UUID: def456...) +... + + +== Troubleshooting == + +=== Scripts funktionieren nicht === + +==== Problem: "Script nicht gefunden" ==== + +Häufigste Ursache: `compile.sh` wurde nicht ausgeführt. + +Lösung: +# Prüfen ob `.scpt`-Dateien vorhanden sind: ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/ +# Falls nur `.applescript`-Dateien vorhanden → ./compile.sh erneut ausführen +# Auf Fehlermeldungen achten + +==== Problem: Script-Zugriff verweigert ==== + +Lösung: +# System Settings → Privacy & Security → Automation +# DEVONthink sollte mit entsprechenden Rechten gelistet sein +# Script Editor öffnen und START.scpt öffnen +# Compile (⌘K) — sollte ohne Fehler durchlaufen + +=== ZIP wird nicht erstellt === + +* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!) +* Ausreichend Festplatte vorhanden? +* Staging-Ordner in DEVONthink beschreibbar? + +=== Mail-Draft öffnet sich nicht === + +* Apple Mail ist geöffnet? +* Script-Zugriff für Mail aktiviert? +* Mail-Templates-Ordner vorhanden? + +=== "Mixed-Year-Selection"-Fehler === + +Dies ist kein Fehler, sondern Schutz vor Versandvermischung: + +; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen +; Lösung 2: Belege in mehreren Versänden verteilen + +=== Debug-Informationen aktivieren === + +In `belegversand.conf`: + + +WRITE_DEBUG_LOG=true + + +Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`. + +== Versionshistorie == + +; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration +; 1.3: Dry-Run Verbesserungen, Markdown-Logs +; 1.2: Mail-Templates in DEVONthink, interne README +; 1.1: Konfigurationssystem +; 1.0: Erste funktionale Version + +== Entwicklung == + +Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich). + +Zur lokalen Entwicklung: +# Quelldateien (`.applescript`) editieren +# `./compile.sh` ausführen +# In DEVONthink testen +# Bei Änderungen: `./compile.sh` erneut ausführen + +== Support == + +Für technische Fragen oder Probleme: +* Wiki-Dokumentation durchlesen (diese Seite) +* Debug-Log aktivieren und analysieren +* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden) + +== Externe Links == + +* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff) +* [https://www.devontechnologies.com DEVONthink Homepage] +* [https://support.apple.com/mail Apple Mail Documentation]