diff --git a/README.md b/README.md index 1a32b7f..256559a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ # 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 @@ -10,7 +13,10 @@ 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 +- **About-Dialog**: Integrierte Hilfe im DEVONthink-Menü + ## Systemanforderungen + - macOS 10.13+ - DEVONthink 3.x - Apple Mail @@ -22,16 +28,11 @@ Automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVO **LIES DAS!** -Im Repository liegen AppleScript-Dateien. +Im Repository findest du zwei Arten von AppleScript-Dateien: | Dateiendung | Bedeutung | Nutzung | |---|---|---| | `.applescript` | **Quelldateien (Lesbar)** | Nur für Entwicklung/Versionskontrolle | - -DEVONthink arbeitet mit den ***kompilierten Versionen*** dieser Dateien! - -| Dateiendung | Bedeutung | Nutzung | -|---|---|---| | `.scpt` | **Kompilierte Skripte (Binär)** | Werden von DEVONthink ausgeführt | **Kritisch:** Die `.applescript`-Quelldateien funktionieren **NICHT** direkt in DEVONthink, weil: @@ -39,7 +40,7 @@ DEVONthink arbeitet mit den ***kompilierten Versionen*** dieser Dateien! - 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 **einmalig** ausgeführt werden. Dieses: +**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 @@ -51,19 +52,25 @@ DEVONthink arbeitet mit den ***kompilierten Versionen*** dieser Dateien! --- ## 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 cd Belegversand ``` + Alternativ: ZIP von der Gitea-Website herunterladen und entpacken. ### Schritt 3: Scripts kompilieren (NOTWENDIG!) + ```bash chmod +x compile.sh ./compile.sh @@ -90,18 +97,23 @@ Nach erfolgreicher Kompilierung: - ✓ 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 -├── compile.sh # Kompilierungs-Skript (nach Nutzung nicht mehr nötig) -├── Change.log # Changelog +├── START.scpt # Einstiegspunkt (sichtbar in DEVONthink-Menü) +├── About.scpt # About-Dialog (sichtbar in DEVONthink-Menü) +├── README.md # Diese Datei +├── 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 -│ ├── uuid_anzeigen.scpt # Utility zum Anzeigen von Record-UUIDs +│ ├── about.scpt # About-Dialog (Menü) +│ ├── 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/ +│ ├── _text_about.scpt # Zentrale About-Text-Generierung │ ├── _belegversand_setup.scpt # Initialisierung & Konfiguration │ └── _belegversand.scpt # Hauptlogik (Versand, Logging) └── [weitere Dateien nach erster Ausführung] @@ -110,15 +122,22 @@ Belegversand/ **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 @@ -127,16 +146,19 @@ _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 | | `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 | +| `MAIL_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 | @@ -147,9 +169,15 @@ 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) ↓ @@ -161,8 +189,18 @@ Die E-Mail-Adressen werden automatisch geparst und in Apple Mail einzeln eingef ↓ 5. Echtlauf → ZIP + Mail-Draft + Logging + Tagging ``` + +### Menü-Befehle + +| Befehl | Funktion | +|--------|----------| +| `START` | Haupteinstiegspunkt — startet Setup oder Versand | +| `About...` | About-Dialog mit Versionsinformation und Links | + ### 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 @@ -177,10 +215,12 @@ Belege/ ├── 2027/ │ ├── 01_Januar/ [Belege hier] │ ├── Versendet/ [← Logs landen HIER für 2027er-Versand] -└── Provisionsabrechnungen/ [Outsider-Dokumenty] +└── Provisionsabrechnungen/ [Outsider-Dokumente] └── [← 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 @@ -188,29 +228,41 @@ Vor jedem echten Versand wird ein simulierter Durchlauf durchgeführt: 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 @@ -224,121 +276,76 @@ Mensch-lesbare Dokumentation mit Übersichten: - 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 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. +## Dokumentation -**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" | `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 | +Ausführliche Dokumentation im Wiki: +**[Belegversand-Wiki](https://wiki.tuxi.ddnss.de/wiki/Belegversand)** -### 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). - -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/ ``` + 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 - 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. + +--- + +## Versionshistorie + +Siehe [CHANGELOG](./CHANGELOG.txt) + +--- + ## Support -Für technische Fragen: Siehe `_config/README-Belegversand` in DEVONthink (interne Dokumentation) oder erstelle ein Issue im Gitea-Repository. + +Für technische Fragen: +- Siehe [Wiki-Dokumentation](https://wiki.tuxi.ddnss.de/wiki/Belegversand) +- Oder erstelle ein Issue im Gitea-Repository (falls Zugriff vorhanden) ---