diff --git a/README.md b/README.md index b421a9e..eba33fc 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,6 @@ # 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 @@ -13,41 +10,88 @@ Automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVO - **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 +--- + +## ⚠️ WICHTIG: Quelldateien vs. Kompilierte Skripte + +**LIES DAS!** + +Im Repository findest du zwei Arten von AppleScript-Dateien: + +| Dateiendung | Bedeutung | Nutzung | +|---|---|---| +| `.applescript` | **Quelldateien (Lesbar)** | Nur für Entwicklung/Versionskontrolle | +| `.scpt` | **Kompilierte Skripte (Binär)** | Werden von DEVONthink ausgeführt | + +**Kritisch:** Die `.applescript`-Quelldateien funktionieren **NICHT** direkt in DEVONthink, weil: +- Interne Pfade sind relativ (z.B. `"Library/Application Scripts/..."`) +- Zur Laufzeit werden diese Pfade mit `echo ~` zu absoluten Pfaden expandiert +- Unkompilierte `.applescript`-Dateien führen zu Fehler wie **"Scriptdatei nicht gefunden"** + +**Lösung:** Nach dem Clone **MUSS** das `compile.sh`-Skript ausgeführt werden. Dieses: +1. Kompiliert alle `.applescript` zu `.scpt` +2. Löscht danach die `.applescript`-Quelldateien +3. Hinterlässt nur funktionsfähige `.scpt`-Dateien + +**Falls du die `.applescript`-Dateien siehst:** +→ `./compile.sh` wurde nicht ausgeführt oder ist fehlgeschlagen! +→ Siehe Schritt 3 der Installation unten. + +--- + ## 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 +git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand +cd Belegversand ``` - Alternativ: ZIP von der Gitea-Website herunterladen und entpacken. -### Schritt 3: Verzeichnisstruktur prüfen - -Nach Installation sollte folgende Struktur vorhanden sein: - +### Schritt 3: Scripts kompilieren (NOTWENDIG!) +```bash +chmod +x compile.sh +./compile.sh ``` -Belegversand_1-4/ + +**Erwartete Ausgabe:** +``` +Compiliere Belegversand AppleScripts... +✓ Fertig! +``` + +**Wenn Fehler auftritt:** +```bash +# Sicherstellen, dass bash vorhanden ist (sollte bei macOS Standard sein) +which bash + +# Oder manuell mit osacompile testen: +osacompile -o START.scpt START.applescript +``` + +Nach erfolgreicher Kompilierung: +- ✓ Alle `.applescript`-Quelldateien sind gelöscht +- ✓ Alle `.scpt`-Skripte sind vorhanden und einsatzbereit +- ✓ DEVONthink kann die Skripte ausführen + +### Schritt 4: Verzeichnisstruktur prüfen +Nach Installation sollte folgende Struktur vorhanden sein: +``` +Belegversand/ ├── START.scpt # Einstiegspunkt (sichtbar in DEVONthink-Menü) ├── README.md # Diese Datei -├── Änderungshistorie.txt # Changelog +├── compile.sh # Kompilierungs-Skript (nach Nutzung nicht mehr nötig) +├── Change.log # Changelog ├── Helpers/ │ ├── show_mail_templates.scpt # Dialog für Template-Auswahl │ ├── create-year-cycle.scpt # Erstellt Jahres-Ordnerstruktur @@ -58,21 +102,18 @@ Belegversand_1-4/ └── [weitere Dateien nach erster Ausführung] ``` -### Schritt 4: Erste Ausführung +**Hinweis:** `.applescript`-Dateien sollten NICHT vorhanden sein. Falls doch → `./compile.sh` erneut ausführen. +### Schritt 5: 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 @@ -81,13 +122,10 @@ _config/ ├── 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 | @@ -104,13 +142,9 @@ Wichtigste Einträge: 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) ↓ @@ -122,13 +156,9 @@ Die E-Mail-Adressen werden automatisch geparst und in Apple Mail einzeln eingef ↓ 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 @@ -145,204 +175,166 @@ Belege/ └── 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 | +| `compile.sh` | Kompiliert `.applescript` zu `.scpt` (nach Installation) | | `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" +set expandedPath to (do shell script "echo ~") & "/" & basePath +``` + +wobei `basePath` relativ definiert ist: +```applescript +property basePath : "Library/Application Scripts/com.devon-technologies.think/Menu/Belegversand" ``` **Vorteil:** Das Script funktioniert unabhängig davon, wo es sich befindet oder von welchem Verzeichnis aus es aufgerufen wird. +**Wichtig für Entwickler:** Nach Änderungen an `basePath` **MUSS** `compile.sh` erneut ausgeführt werden, damit die Pfade korrekt in die kompilierten `.scpt`-Dateien übernommen werden. ## Fehlerbehandlung - ### Häufige Fehler - | Fehler | Ursache | Lösung | | --------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- | -| "Script nicht gefunden" | Falsche Verzeichnisstruktur | Verzeichnisse überprüfen, Scripts neu platzieren | +| "Script nicht gefunden" | `compile.sh` nicht ausgeführt oder `.applescript` noch vorhanden | Siehe Schritt 3 der Installation — `./compile.sh` ausführen | | "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 +- **Kompilierungs-Automation**: `compile.sh` für automatisierte Vorbereitung - **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 +Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich). -Vollständiger Quellcode in AppleScript. Alle Scripts sind kommentiert und dokumentieren: +Zur lokalen Entwicklung: +1. Quelldateien editieren (`.applescript`) +2. `./compile.sh` ausführen +3. In DEVONthink testen +4. Bei Änderungen: `./compile.sh` erneut ausführen +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/ +ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/ ``` - -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 - +2. Sicherstellen, dass `.scpt`-Dateien vorhanden sind (NICHT `.applescript`): +```bash +ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/ +# Sollte zeigen: _belegversand.scpt, _belegversand_setup.scpt +# Sollte NICHT zeigen: _belegversand.applescript, _belegversand_setup.applescript +``` +3. Falls nur `.applescript`-Dateien vorhanden → `./compile.sh` ausführen! +4. Script-Zugriff in Systemeinstellungen überprüfen: + - System Settings → Privacy & Security → Automation + - DEVONthink sollte dort mit entsprechenden Rechten gelistet sein +5. Script Editor öffnen und manuell testen: + - ~/Library/Application Scripts/... → START.scpt öffnen + - Compile (⌘K) — sollte ohne Fehler durchlaufen + - 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 - +- Staging-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 +**Hinweis**: Dieses System ist eine AppleScript-Automatisierung und stark abhängig von macOS und DEVONthink-APIs. Änderungen am System können Anpassungen erfordern.