From dd5ce09b634b2767bd2295c1bb0e637e41248383 Mon Sep 17 00:00:00 2001 From: enchiriadis Date: Sat, 15 Aug 2026 15:11:05 +0000 Subject: [PATCH] README.md aktualisiert MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ausführliche README. --- README.md | 348 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 347 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b2f9ad1..b421a9e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,348 @@ -# DEVONthink-Belegversand-Automatisation +# Belegversand-Automatisation für DEVONthink v1.4 +Automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Ermöglicht die Auswahl von Belegen, deren Verpackung in ZIP-Archive (optional mit Passwort), automatische Mail-Drafts mit konfigurierbaren Empfängern und strukturierte Logging/Tagging-Mechanismen. + +## Features v1.4 + +- **Booking-Jahr Enforcement**: Verhindert versehentliche Vermischung von Belegen aus verschiedenen Buchungsjahren in einem Versand +- **Intelligente Versand-Logs**: Separate NDJSON- und Markdown-Logs mit Jahres-Kontext +- **Automatische Pfadverwaltung**: Absolute Pfade via Home-Verzeichnis — funktioniert unabhängig vom Script-Speicherort +- **Template-basierte Mail-Vorlagen**: Dynamische Mailbody-Auswahl aus DEVONthink-Verzeichnis +- **CSV-Email-Parser**: Unterstützung mehrerer TO und CC Empfänger +- **ZIP-Verschlüsselung**: Optional mit benutzerdefinierten Passwörtern +- **Dokumenten-Tagging**: Automatisches Markieren versendeter Belege +- **Dry-Run Modus**: Vorschau vor echtem Versand +- **Fehlerprotokollierung**: Detaillierte Logs für Auditing und Troubleshooting + +## Systemanforderungen + +- macOS 10.13+ +- DEVONthink 3.x +- Apple Mail +- AppleScript-Zugriff aktiviert + +## Installation + +### Schritt 1: Verzeichnisstruktur anlegen + +```bash +mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/ +cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/ +``` + +### Schritt 2: Repository clonen + +```bash +git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand_1-4 +cd Belegversand_1-4 +``` + +Alternativ: ZIP von der Gitea-Website herunterladen und entpacken. + +### Schritt 3: Verzeichnisstruktur prüfen + +Nach Installation sollte folgende Struktur vorhanden sein: + +``` +Belegversand_1-4/ +├── START.scpt # Einstiegspunkt (sichtbar in DEVONthink-Menü) +├── README.md # Diese Datei +├── Änderungshistorie.txt # Changelog +├── Helpers/ +│ ├── show_mail_templates.scpt # Dialog für Template-Auswahl +│ ├── create-year-cycle.scpt # Erstellt Jahres-Ordnerstruktur +│ ├── uuid_anzeigen.scpt # Utility zum Anzeigen von Record-UUIDs +│ └── scripts/ +│ ├── _belegversand_setup.scpt # Initialisierung & Konfiguration +│ └── _belegversand.scpt # Hauptlogik (Versand, Logging) +└── [weitere Dateien nach erster Ausführung] +``` + +### Schritt 4: Erste Ausführung + +1. DEVONthink öffnen +2. Ein Objekt in der gewünschten Datenbank auswählen +3. Scripts → `START` aufrufen +4. Dialog folgen → Setup wird durchgeführt + +Das Setupscript erstellt automatisch notwendige Ordnerstrukturen und Konfigurationsdateien. + +## Konfiguration + +### Automatische Initialisierung + +Nach erster Ausführung wird folgende Struktur in DEVONthink angelegt: + +``` +_config/ +├── belegversand.conf # Konfigurationsdatei +├── mail_vorlagen/ # Mail-Templates +│ └── belegversand # Default-Template +├── README-Belegversand # Interne Dokumentation +└── [Logging-Verzeichnisse nach Bedarf] +``` + +### Konfigurationsdatei (belegversand.conf) + +Zugänglich über DEVONthink → `_config` → `belegversand.conf` + +Wichtigste Einträge: + +| Key | Beispiel | Bedeutung | +| ---------------------- | ----------------------- | ----------------------------------- | +| `SHOW_README` | `true` | Zeigt Willkommens-Dialog beim Start | +| `MAIL_TO_DEFAULT` | `recipient@example.com` | Standard TO-Empfänger | +| `MAIL_CC_TO_DEFAULT` | `cc@example.com` | Standard CC-Empfänger | +| `SUBJECT_PREFIX` | `Belegversand` | Mail-Betreff Präfix | +| `ZIP_PASSWORD_DEFAULT` | `12345` | Default ZIP-Passwort | +| `SENT_TAG_FOR_DOCS` | `gesendet` | Tag für versendete Belege | +| `LOG_SENT_GROUP_NAME` | `Versendet` | Ordner für Versand-Logs | +| `WRITE_DEBUG_LOG` | `false` | Debug-Ausgaben aktivieren | + +**CSV-Format für multiple Empfänger:** +``` +MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com +MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com +``` + +Die E-Mail-Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt. + +## Verwendung + +### Grundablauf + +``` +1. Belege in DEVONthink auswählen (Mehrfach-Selektion möglich) + ↓ +2. Scripts → START aufrufen + ↓ +3. Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?) + ↓ +4. Dry-Run Vorschau (optional) + ↓ +5. Echtlauf → ZIP + Mail-Draft + Logging + Tagging +``` + +### Spezielle Verhaltensweisen + +#### Booking-Jahr Enforcement (v1.4) + +Das Script ordnet alle ausgewählten Belege automatisch ihrem Buchungsjahr zu: + +- **Mixed-Year Selection**: Wenn Sie Belege aus verschiedenen Jahren auswählen, wird das Script einen Fehler zurückweisen +- **Outsider Documents**: Belege außerhalb definierter Jahresordonner (z.B. unter `Provisionsabrechnungen`) werden separat gehandhabt +- **Separate Logging**: Jedes Buchungsjahr hat sein eigenes `Versendet`-Verzeichnis mit separaten Logs + +Beispiel-Struktur: +``` +Belege/ +├── 2026/ +│ ├── 01_Januar/ [Belege hier] +│ ├── Versendet/ [← Logs landen HIER für 2026er-Versand] +├── 2027/ +│ ├── 01_Januar/ [Belege hier] +│ ├── Versendet/ [← Logs landen HIER für 2027er-Versand] +└── Provisionsabrechnungen/ [Outsider-Dokumenty] + └── [← Logs landen in entsprechend eigenen Outsider-Log] +``` + +#### Dry-Run Modus + +Vor jedem echten Versand wird ein simulierter Durchlauf durchgeführt: + +1. Listet alle zu versendenden Belege auf +2. Erstellt Vorschau-Datei mit Details +3. Zeigt Dialog mit Zusammenfassung +4. User bestätigt oder bricht ab + +Die Vorschaudatei wird im DEVONthink-Verzeichnis gespeichert (konfigurierbar). + +#### Mail-Draft Vorbereitung + +Das Script erstellt keinen echten Versand, sondern einen **Mail-Draft**: + +1. ZIP-Archive mit Belegen werden erstellt +2. Apple Mail öffnet mit neuem Draft (nicht gesendet!) +3. User kann Template ändern, weitere Empfänger hinzufügen +4. Benutzerdefinierter Versand per Knopfdruck + +### Template-System + +Mail-Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`): + +``` +Hello, + +Here are your documents. + +Best regards +``` + +Das Script zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind. + +## Logging & Dokumentation + +### NDJSON-Logs + +Maschinell lesbare Logs im JSON-Lines Format: + +```json +{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"...","record_name":"Invoice-001","status":"sent"} +{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"...","status":"created"} +{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"...","tag":"gesendet","status":"applied"} +``` + +### Markdown-Logs + +Mensch-lesbare Dokumentation mit Übersichten: + +```markdown +# 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] + +### Versandte Dokumente +- Invoice-001 (UUID: abc123...) +- Invoice-002 (UUID: def456...) +... +``` + +Logs werden automatisch in `_config → Versendet` gespeichert. + +## Verzeichnisse und ihre Rollen + +| Pfad | Funktion | +| ------------------------------------------ | -------------------------------------------------------- | +| `START.scpt` | Einstiegspunkt, delegiert zu Setup/Hauptscript | +| `Helpers/show_mail_templates.scpt` | Dialog-Utility für Template-Auswahl | +| `Helpers/create-year-cycle.scpt` | Erstellt 12-Monats-Struktur + Versendet-Ordner | +| `Helpers/uuid_anzeigen.scpt` | Debug-Utility: zeigt UUIDs von Records | +| `Helpers/scripts/_belegversand_setup.scpt` | Konfiguration, Initialisierung, Verzeichnis-Vorbereitung | +| `Helpers/scripts/_belegversand.scpt` | Hauptlogik: Auswahl, ZIP, Mail, Logging, Tagging | + +## Pfadverwaltung + +Das System verwendet **absolute Pfade basierend auf dem Home-Verzeichnis**: + +```applescript +set basePath to (do shell script "echo ~") & "/Library/Application Scripts/com.devon-technologies.think/Menu/Belegversand_1-4" +``` + +**Vorteil:** Das Script funktioniert unabhängig davon, wo es sich befindet oder von welchem Verzeichnis aus es aufgerufen wird. + +## Fehlerbehandlung + +### Häufige Fehler + +| Fehler | Ursache | Lösung | +| --------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- | +| "Script nicht gefunden" | Falsche Verzeichnisstruktur | Verzeichnisse überprüfen, Scripts neu platzieren | +| "Keine Konfiguration gefunden" | Kein `_config` in DB | Erneut `START` aufrufen → Setup durchlaufen | +| "Mixed-Year selection" | Belege aus verschiedenen Jahren | Nur Belege aus einem Jahr auswählen | +| "Mail kann nicht erstellt werden" | Apple Mail läuft nicht oder Script-Zugriff verweigert | Mail öffnen, Systemeinstellungen → Sicherheit → Script-Zugriff prüfen | + +### Debug-Informationen aktivieren + +In `belegversand.conf`: +``` +WRITE_DEBUG_LOG=true +``` + +Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log` mit detaillierten Informationen. + +## Versionshistorie + +### v1.4 (aktuell) + +- **Booking-Jahr Enforcement**: Verhindert Mixed-Year-Versende +- **Separate Year-Logs**: Jedes Jahr bekommt eigene `Versendet`-Gruppe +- **Outsider Handling**: Belege außerhalb Jahresstruktur unterstützen +- **Code-Refactoring**: Robustere Pfadverwaltung +- **Kommentar-Cleanup**: Alle bekannten AppleScript-Fallstricke dokumentiert + +### v1.3 + +- Dry Run mit Vorschau-Datei +- Markdown-Logs mit besserer Strukturierung +- Enhanced README in DEVONthink + +### v1.2 + +- Mailbody in DEVONthink Storage verlagert +- Config-Management erweitert + +### v1.1 + +- Konfigurationssystem eingeführt +- Setup-Script hinzugefügt + +### v1.0 + +- Initiale Version +- ZIP-Erzeugung +- Mail-Draft-Erstellung +- Tagging und Logging + +## Entwicklung und Beiträge + +Vollständiger Quellcode in AppleScript. Alle Scripts sind kommentiert und dokumentieren: + +- Funktionale Schritte +- Parameter und Rückgabewerte +- Bekannte AppleScript-Fallstricke (reserved words, Pfadverwaltung, etc.) + +Für Beiträge oder Probleme: Issues im Gitea-Repository erstellen. + +## Troubleshooting + +### Script funktioniert in DEVONthink-Menü nicht + +1. Verzeichnisstruktur überprüfen: +```bash +ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand_1-4/ +``` + +2. Script-Zugriff in Systemeinstellungen überprüfen: + 2. System Settings → Privacy & Security → Automation + 3. DEVONthink sollte dort mit entsprechenden Rechten gelistet sein + +3. Script Editor öffnen und manuell testen: + 2. \~/Library/Application Scripts/... → START.scpt öffnen + 3. Compile (⌘K) — sollte ohne Fehler durchlaufen + 4. Run (⌘R) für manuellen Test + +### ZIP wird nicht erstellt + +- ZIP-Passwort in Config überprüfen (keine Sonderzeichen!) +- Festplatte hat genug Platz +- Stagings-Ordner im DEVONthink existiert und ist beschreibbar + +### Mail-Draft öffnet sich nicht + +- Apple Mail ist geöffnet? +- Script-Zugriff für Mail in Systemeinstellungen aktiviert? +- Mail-Templates-Ordner vorhanden und Konfiguration korrekt? + +### "Mixed-Year-Selection"-Fehler + +Das ist kein Fehler, sondern Schutz vor Versandvermischung: + +- Nur Belege aus **einem** Buchungsjahr auswählen +- Oder Belege in separaten Versänden verteilen + +## Lizenz + +Intern entwickelt für Privatgebrauch. + +## Support + +Für technische Fragen: Siehe `_config/README-Belegversand` in DEVONthink (interne Dokumentation) oder erstelle ein Issue im Gitea-Repository. + +--- + +**Hinweis**: Dieses System ist eine AppleScript-Automatisierung und stark abhängig von macOS und DEVONthink-APIs. Änderungen am System können Anpassungen erfordern. \ No newline at end of file