Automatisierter Belegversand für DEVONthink hinzugefügt

2026-08-18 13:05:45 +00:00
commit 7662661641
1 changed files with 311 additions and 0 deletions
@@ -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 ====
+
+<source lang="bash">
+mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
+cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
+</source>
+
+==== 2. Repository klonen ====
+
+<source lang="bash">
+git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
+cd Belegversand
+</source>
+
+==== 3. Scripts kompilieren ====
+
+Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!
+
+<source lang="bash">
+chmod +x compile.sh
+./compile.sh
+</source>
+
+Erwartete Ausgabe:
+<source>
+Compiliere Belegversand AppleScripts...
+✓ Fertig!
+</source>
+
+==== 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:
+
+<source>
+_config/
+├── belegversand.conf              # Konfigurationsdatei
+├── mail_vorlagen/                 # Mail-Templates
+│   └── belegversand               # Standard-Template
+├── README-Belegversand            # Interne Hilfe
+└── [weitere Dateien nach Versand]
+</source>
+
+=== 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:
+
+<source>
+MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
+MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
+</source>
+
+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:
+
+<source>
+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]
+</source>
+
+=== 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:
+
+<source>
+Sehr geehrte/r Frau/Herr,
+
+beiliegend erhalten Sie die angeforderten Unterlagen.
+
+Mit freundlichen Grüßen
+</source>
+
+== Protokollierung ==
+
+=== NDJSON-Logs ===
+
+Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:
+
+<source lang="json">
+{"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"}
+</source>
+
+=== Markdown-Logs ===
+
+Menschlich lesbar mit Übersichten nach Versandlauf:
+
+<source>
+# 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...)
+...
+</source>
+
+== 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: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
+# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> 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`:
+
+<source>
+WRITE_DEBUG_LOG=true
+</source>
+
+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]