README.md aktualisiert

Aktualisiert: - ./compile.sh - *.applescript versus *.scpt
2026-08-17 13:39:39 +00:00
parent 77bdff24fb
commit a3c500f2aa
1 changed files with 98 additions and 106 deletions
@@ -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.
+**Hinweis**: Dieses System ist eine AppleScript-Automatisierung und stark abhängig von macOS und DEVONthink-APIs. Änderungen am System können Anpassungen erfordern.