enchiriadis/DEVONthink-Belegversand-Automatisation
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README.md aktualisiert

Browse Source 
finale Version
This commit is contained in:
enchiriadis
2026-08-18 11:36:33 +00:00
parent 4943f1b0a9
commit 81868ef5a3
1 changed files with 99 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+99 -92
View File
@@ -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)
---