README.md aktualisiert

finale Version

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ü)
+├── 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/
+│   ├── 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.
+Ausführliche Dokumentation im Wiki:
-## Fehlerbehandlung
+**[Belegversand-Wiki](https://wiki.tuxi.ddnss.de/wiki/Belegversand)**
-### 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 |
 
-### 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)
 
 ---