DEVONthink-Belegversand-Automatisation/README.md

# Belegversand-Automatisation für DEVONthink v1.5

Automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Ermöglicht die Auswahl von Belegen, deren Versand als ZIP-Archiv (optional mit Passwort) **oder als einzelne Anhänge** (z.B. für DATEV), automatische Mail-Drafts mit konfigurierbaren Empfängern, automatische Aufteilung großer Sendungen auf mehrere Mails sowie strukturierte Logging/Tagging-Mechanismen.

Ausführliche Dokumentation hier im Wiki, sowie auf:
https://wiki.tuxi.ddnss.de/wiki/Belegversand

DEVONthink (c) Datenbank-Software:
https://www.devontechnologies.com/de/apps/devonthink

**Hinweis:**
Dieses Projekt ist als privates Projekt mit Hilfe verschiedener KI-Modelle entstanden. Es wurde mit AI-Support getestet, ge-debuggt und dokumentiert.
Der Projektersteller nutzt die Skripte als Hilfe bei Buchhaltung und nicht-sicherheitsrelevanter Belegübermittlung an's Steuerberatungsbüro. Sie unterstützen aber jeden Kontext, bei dem aus DEVONthink heraus Dokumente per Mail geteilt werden sollen.

## Neu in v1.5

- **Zwei Versandmodi** (`ZIP_ARCHIVE=true/false`): wie bisher als ZIP-Archiv – oder jeder Beleg als eigener Anhang, z.B. für DATEV-Belegtransfer per Mail. Im Einzeldatei-Modus entfällt der Passwort-Dialog.
- **Automatische Aufteilung nach Mailgröße** (`MAX_MAIL_SIZE_MB`): Zu große Sendungen werden auf mehrere Mails verteilt – mit Puffer für die Base64-Kodierung von Mail-Anhängen. Betreff und Batch-ID werden durchnummeriert („(1/2)", `…-1`).
- **Dateityp-Prüfung** (`SUPPORTED_FILE_TYPES_FOR_SENDING`): Nicht erlaubte Dateitypen (z.B. JPG) werden vor dem Versand gemeldet – Abbrechen oder ohne diese weiter.
- **Smart Rule „Fotos → PDF"**: Fertige DEVONthink-Regel in `extras/`, die Fotos von Quittungen beim Import automatisch in (durchsuchbare) PDFs umwandelt und die Originale in die Gruppe `Originale` verschiebt.
- **Stage-Ordner** jetzt unter `~/Library/Caches/DT-Belegversand/`. Er wird nicht mehr sofort gelöscht (Mail lädt Anhänge evtl. verzögert); Läufe älter als 7 Tage werden beim nächsten Start aufgeräumt.
- **Setup verbessert**: verständlichere Dialoge, Abfrage des Versandmodus, Jahres-/Monatsordner werden geprüft und nur ergänzt statt dupliziert, Gruppe `Originale` wird angelegt, Anleitung für die Smart Rule am Ende der Einrichtung.
- **Bugfixes**: doppelter Home-Pfad in `START` (trat bei `SHOW_README=true` auf), verschachtelte Gruppe `Belege/Belege` im Setup, Loggruppe im Jahresordner ignorierte `LOG_SENT_GROUP_NAME`.
- **Rückwärtskompatibel**: Fehlen die neuen Schlüssel in einer bestehenden `belegversand.conf`, verhält sich alles wie in v1.4 (ZIP-Modus).

## Features

- **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
- **Template-basierte Mail-Vorlagen**: Dynamische Mailbody-Auswahl aus DEVONthink-Verzeichnis
- **CSV-Email-Parser**: Unterstützung mehrerer TO und CC Empfänger
- **ZIP-Verschlüsselung**: Optional mit benutzerdefinierten Passwörtern (siehe Sicherheitshinweise!)
- **Einzeldatei-Versand**: Alternative zum ZIP, z.B. für DATEV
- **Größenprüfung & Aufteilung**: Mehrere Mails statt einer zu großen
- **Dateityp-Prüfung**: Nur erlaubte Formate werden versendet
- **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 4.x
- Apple Mail
- AppleScript-Zugriff aktiviert
- Für die Smart Rule mit OCR: eine DEVONthink-Edition mit OCR (sonst einfache PDF-Konvertierung)

## ☢️ Sicherheitsrelevante Einschränkungen

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.
- Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
- Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird – **auch in Version 1.5 noch** – über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.
- **Neu in 1.5:** Im Einzeldatei-Modus (`ZIP_ARCHIVE=false`) gehen die Belege **gar nicht verschlüsselt** raus. Geschützt sind sie dann nur durch die Transportverschlüsselung (TLS) des Mailservers. Beim DATEV-Belegtransfer ist das so vorgegeben.

**Ganz deutlich:** Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken!
Dafür sind sie prima!
Der Umstieg von zip -P auf eine starke AES-Verschlüsselung (und das Passwort als Hash-Wert in der Config-Datei) steht weiterhin auf der Liste – Version 1.5 hatte einen anderen Schwerpunkt (Einzeldatei-Versand für DATEV).

Bis dahin gilt ganz klar:
Wer mit diesen Skripten sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

---

## ⚠️ WICHTIG: Quelldateien vs. Kompilierte Skripte

**LIES DAS!**

In diesem Repository findest du AppleScript-Dateien.

| Dateiendung | Bedeutung | Nutzung |
|---|---|---|
| `.applescript` | **Quelldateien (Lesbar)** | Nur für Entwicklung/Versionskontrolle |

*.applescript-Files sind reine Textdateien. Sie können von Git versioniert und getrackt werden.
Innerhalb von DEVONthink werden allerdings die kompilierten Versionen dieser Dateien verwendet!

| Dateiendung | Bedeutung | Nutzung |
|---|---|---|
| `.scpt` | **Kompilierte Skripte (Binär)** | Werden von DEVONthink ausgeführt |

Um die *.scpt-Files zu erzeugen, verwendest du bitte die Datei:
compile.sh

DETAILS hierzu:

**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 dem Home-Verzeichnis 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
cd Belegversand
```

### Schritt 3: Scripts kompilieren (NOTWENDIG!)

```bash
chmod +x compile.sh
./compile.sh
```

**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ü)
├── 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
├── extras/
│   └── Belege-Foto-zu-PDF.dtSmartRule # Smart Rule: Fotos → PDF (siehe Schritt 6)
├── 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]
```

**Hinweis:** `.applescript`-Dateien sollten NICHT vorhanden sein. Falls doch → `./compile.sh` erneut ausführen.

### Schritt 5: Erste Ausführung

1. DEVONthink öffnen
2. Ein beliebiges Objekt in der gewünschten Datenbank auswählen – am einfachsten die Gruppe „Belege"
3. Im DEVONthink Scripte-Menü <img src=".gitea/dt-scripts.webp" width="16" height="22" alt="DEVONthink-Script-Symbol">  → `Belegversand->START` aufrufen
4. Dialog folgen → Setup wird durchgeführt

Das Setupscript erstellt die notwendigen Ordnerstrukturen und Konfigurationsdateien innerhalb der DEVONthink-Datenbank. Dabei wird u.a. abgefragt, ob als **ZIP-Archiv** oder als **Einzeldateien** versendet werden soll – das lässt sich später jederzeit in der `belegversand.conf` ändern.

### Schritt 6: Smart Rule „Fotos → PDF" einrichten (empfohlen)

Versendet werden standardmäßig nur PDF- und TIFF-Dateien. Damit Fotos von Quittungen (JPG, HEIC, PNG) gar nicht erst stören, wandelt eine DEVONthink-Smart-Rule sie beim Import automatisch um.

Smart Rules lassen sich nicht per AppleScript anlegen – aber importieren:

1. `extras/Belege-Foto-zu-PDF.dtSmartRule` in DEVONthink importieren (Doppelklick bzw. Import der Smart Rule).
2. **Wichtig:** Die Regel verweist intern per UUID auf Datenbank und Gruppen des Rechners, auf dem sie exportiert wurde. Nach dem Import daher in der Regel neu auswählen:
   - **Suchen in:** die eigene Gruppe `Belege` (inkl. Untergruppen)
   - **Verschieben nach:** die Gruppe `Originale` (legt das Setup an)
3. Mit einem einzelnen Test-Foto prüfen: Das PDF sollte im Monatsordner liegen, das Foto in `Originale`.

<details>
<summary>Alternative: Regel von Hand anlegen</summary>

1. In DEVONthink eine neue intelligente Regel (Smart Rule) anlegen.
2. Name: z.B. „Belege: Fotos → PDF".
3. Suchen in: Gruppe „Belege" (inkl. Untergruppen).
4. Bedingung: Art ist Bild.
5. Ausführen: beim Importieren (optional zusätzlich: beim Hinzufügen).
6. Aktion: in durchsuchbares PDF umwandeln (OCR) – oder, falls OCR nicht verfügbar: in PDF konvertieren.
7. Aktion: Original verschieben nach Gruppe „Originale".

Die Bezeichnungen können je nach DEVONthink-Version leicht abweichen.
</details>

**Hinweise:**
- Die Gruppe `Originale` liegt bewusst auf oberster Ebene der Datenbank, also **außerhalb** der Belege. So erfasst die Regel ihre eigenen Originale nicht erneut.
- Smart Rules gehören zur DEVONthink-Installation, nicht zur Datenbank. Auf jedem weiteren Mac muss die Regel erneut importiert werden.
- **Office-Dokumente** (Word, Excel …) bitte direkt aus der jeweiligen Anwendung als PDF exportieren. Eine Konvertierung in DEVONthink ist möglich, das Layout von Rechnungen kann dabei aber verrutschen.

---

## Konfiguration

### Automatische Initialisierung

Nach erster Ausführung wird folgende Struktur in DEVONthink angelegt:

```
DB-Wurzel/
├── _config/
│   ├── belegversand.conf       # Konfigurationsdatei
│   ├── mail_vorlagen/          # Mail-Templates
│   │   └── belegversand        # Default-Template
│   └── README-Belegversand     # Interne Dokumentation
├── Versendet_Outsider/         # Logs für Belege außerhalb von Jahresordnern
├── Originale/                  # Original-Fotos nach PDF-Umwandlung (Smart Rule)
└── Belege/                     # optional: Jahres- und Monatsordner
    └── 2026/
        ├── 01_Januar/ … 12_Dezember/
        ├── Versendet/          # Logs für dieses Buchungsjahr
        └── Provisionsabrechnungen/
```

Vorhandene Jahres- und Monatsordner werden dabei nicht verändert – fehlende werden nur ergänzt.

### 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                                |
| `MAIL_SUBJECT_PREFIX`              | `Belegversand`          | Mail-Betreff Präfix                                  |
| `ZIP_ARCHIVE`                      | `true` / `false`        | **Neu:** ZIP-Archiv oder Einzeldateien               |
| `ZIP_PASSWORD_DEFAULT`             | `12345`                 | Default ZIP-Passwort (nur im ZIP-Modus)              |
| `MAX_MAIL_SIZE_MB`                 | `20`                    | **Neu:** max. Mailgröße, darüber Aufteilung          |
| `SUPPORTED_FILE_TYPES_FOR_SENDING` | `pdf, tif, tiff`        | **Neu:** erlaubte Dateitypen                         |
| `SENT_TAG_FOR_DOCS`                | `gesendet`              | Tag für versendete Belege                            |
| `LOG_SENT_GROUP_NAME`              | `Versendet`             | Gruppe für Versand-Logs im Jahresordner              |
| `WRITE_DEBUG_LOG`                  | `false`                 | Debug-Ausgaben aktivieren                            |
| `PATH_TO_DRYRUN_PREVIEW`           | `/tmp/DT-Belegversand-preview.txt` | Ablage der Dry-Run-Vorschau               |

Optional, wird vom Setup **nicht** geschrieben:

| Key         | Default                              | Bedeutung                  |
| ----------- | ------------------------------------ | -------------------------- |
| `STAGE_DIR` | `~/Library/Caches/DT-Belegversand/`  | Arbeitsordner für Export   |

**Bestehende Installation auf v1.5 aktualisieren:** Das Setup schreibt die Konfiguration nur bei der Ersteinrichtung. In einer vorhandenen `belegversand.conf` die neuen Zeilen bei Bedarf von Hand ergänzen:

```
ZIP_ARCHIVE=false
MAX_MAIL_SIZE_MB=20
SUPPORTED_FILE_TYPES_FOR_SENDING=pdf, tif, tiff
```

Fehlen sie, gelten die Defaults: ZIP-Modus, 20 MB, `pdf, tif, tiff`.

**CSV-Format für multiple Empfänger:**
```
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)
   ↓
2. Scripts → START aufrufen
   ↓
3. Automatische Prüfungen:
   – Buchungsjahr einheitlich?
   – bereits versendet (Tag)? → werden übersprungen
   – Dateityp erlaubt?        → sonst Hinweis: Abbrechen / ohne diese weiter
   – Größe?                   → Aufteilung auf mehrere Mails
   ↓
4. Dialoge: Dry-Run oder Senden, Empfänger, CC, ggf. ZIP-Passwort
   ↓
5. Dry-Run Vorschau (optional)
   ↓
6. Echtlauf → je Mail: Export, ggf. ZIP, Mail-Draft – danach Tagging + Logging
```

### Menü-Befehle

| Befehl | Funktion |
|--------|----------|
| `START` | Haupteinstiegspunkt — startet Setup oder Versand |
| `About...` | About-Dialog mit Versionsinformation und Links |

### Spezielle Verhaltensweisen

#### Booking-Jahr Enforcement (seit 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 Jahresordner werden separat gehandhabt
- **Separate Logging**: Jedes Buchungsjahr hat sein eigenes `Versendet`-Verzeichnis mit separaten Logs

Beispiel-Struktur:
```
Belege/
├── 2026/
│   ├── 01_Januar/ [Belege hier]
│   ├── Versendet/  [← Logs landen HIER für 2026er-Versand]
├── 2027/
│   ├── 01_Januar/ [Belege hier]
│   ├── Versendet/  [← Logs landen HIER für 2027er-Versand]
└── [Belege ohne Jahresordner]
    └── [← Logs landen in Versendet_Outsider auf oberster Ebene]
```

#### Versandmodus: ZIP-Archiv oder Einzeldateien (neu in v1.5)

- `ZIP_ARCHIVE=true`: Alle Belege einer Mail landen in einem ZIP-Archiv, optional mit Passwort.
- `ZIP_ARCHIVE=false`: Jeder Beleg wird als eigener Anhang angefügt – so erwartet es z.B. der DATEV-Belegtransfer per Mail. Der Passwort-Dialog entfällt.

Beide Modi sind gleichberechtigt; der Wechsel erfolgt über eine Zeile in der Config.

#### Mailgröße & Aufteilung (neu in v1.5)

Mail kodiert Anhänge per Base64, dadurch werden sie um rund ein Drittel größer. Eine Mailgrenze von 20 MB bedeutet also nur etwa 14 MB an Dateien. Das Script rechnet deshalb mit **70 % von `MAX_MAIL_SIZE_MB`** als Budget für Anhänge.

- Die Belege werden auf möglichst wenige Mails verteilt (größte zuerst).
- Bei mehreren Mails: Betreff „Präfix (1/2)", „Präfix (2/2)" usw., Batch-IDs `…-1`, `…-2`.
- Ein einzelner Beleg, der allein schon über dem Budget liegt, wird gemeldet (Abbrechen / ohne diesen weiter).
- Die Prüfung greift in beiden Modi; im ZIP-Modus bekommt jede Mail ihr eigenes ZIP.

#### Dateityp-Prüfung (neu in v1.5)

Vor dem Versand wird jede Datei anhand ihrer Dateiendung gegen `SUPPORTED_FILE_TYPES_FOR_SENDING` geprüft. Nicht erlaubte Dateien werden aufgelistet; man kann abbrechen oder ohne sie fortfahren. Fotos lassen sich am bequemsten per Smart Rule (siehe Installation, Schritt 6) umwandeln.

Die Prüfung erfolgt über die Dateiendung, weil DEVONthink z.B. JPG und TIFF beide als „Bild" führt.

#### Dry-Run Modus

Vor jedem echten Versand kann ein simulierter Durchlauf durchgeführt werden:
1. Listet alle zu versendenden Belege auf – aufgeteilt nach Mails, mit Größen
2. Erstellt Vorschau-Datei mit Details
3. Zeigt Dialog mit Zusammenfassung
4. User bestätigt oder bricht ab

Die Vorschaudatei liegt standardmäßig unter `/tmp/DT-Belegversand-preview.txt` (konfigurierbar über `PATH_TO_DRYRUN_PREVIEW`).

#### Mail-Draft Vorbereitung

Das Script erstellt keinen echten Versand, sondern einen oder mehrere **Mail-Drafts**:
1. Belege werden in den Stage-Ordner exportiert (ggf. als ZIP gepackt)
2. Apple Mail öffnet mit neuem Draft (nicht gesendet!)
3. User kann Template ändern, weitere Empfänger hinzufügen
4. Benutzerdefinierter Versand per Knopfdruck

**Hinweis:** Das Tag `gesendet` wird vergeben, sobald die Entwürfe erstellt sind – nicht erst beim tatsächlichen Absenden. Entwürfe also bitte auch wirklich verschicken.

#### Stage-Ordner (neu in v1.5)

Exportierte Belege und ZIP-Archive liegen unter `~/Library/Caches/DT-Belegversand/<Batch-ID>/mail-1/…`. Der Ordner bleibt nach dem Lauf bewusst stehen, weil Apple Mail Anhänge evtl. verzögert lädt. Läufe, die älter als 7 Tage sind, werden beim nächsten Start automatisch gelöscht. Aus Sicherheitsgründen räumt das Script nur in Pfaden auf, die „Belegversand" enthalten.

Bitte keine Dateien von Hand in den Stage-Ordner legen: Was versendet wird, entscheidet die Auswahl in DEVONthink – nur so stimmen Tags und Logs.

### 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. Bei mehreren Mails wird die Vorlage nur einmal abgefragt.

---

## Logging & Dokumentation

Logs werden im Jahresordner unter `Versendet` gespeichert (Name über `LOG_SENT_GROUP_NAME` änderbar), für Belege außerhalb von Jahresordnern in `Versendet_Outsider` auf oberster Ebene. Dort liegt außerdem `!Ergebnis` mit einer Zusammenfassung des letzten Sendelaufs.

### NDJSON-Logs

Maschinell lesbare Logs im JSON-Lines Format, eine Zeile pro Beleg:
```json
{"ts":"2026-10-12T21:30:45+02:00","batch":"20261012-213045-1","mail":"1/2","mode":"single","to":"belege@example.com","zip":"","uuid":"…","ref":"x-devonthink-item://…","name":"Tankquittung","filename":"Tankquittung.pdf"}
```

Neu in v1.5: `mail` (Mail x von y) und `mode` (`zip` oder `single`).

### Markdown-Logs

Mensch-lesbare Dokumentation mit einer Tabelle je Sendelauf:
```markdown
# Belegversand-Log 2026

## Sendelauf am 12. Oktober 2026, Uhrzeit 21:30:45

| Zeit | Batch | Empfänger | ZIP | DEVONthink-Name | Dateiname | DEVONthink |
|---|---|---|---|---|---|---|
| 2026-10-12T21:30:45+02:00 | `20261012-213045-1` | belege@example.com | einzeln | Tankquittung | Tankquittung.pdf | [öffnen](x-devonthink-item://…) |
```

Im Einzeldatei-Modus steht in der Spalte „ZIP" der Eintrag `einzeln`.

---

## Dokumentation

Ausführliche Dokumentation im Wiki:
**[Belegversand-Wiki](https://wiki.tuxi.ddnss.de/wiki/Belegversand)**

---

## 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

### „Scriptdatei nicht gefunden" mit doppeltem Pfad

Meldung wie `/Users/name//Users/name/Library/…`: Das war ein Bug in `START` bis v1.4, der bei `SHOW_README=true` auftrat. Mit v1.5 behoben – `START` neu kompilieren.

### ZIP wird nicht erstellt

- ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
- Festplatte hat genug Platz
- Stage-Ordner `~/Library/Caches/DT-Belegversand/` 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?

### Hinweis „Dateityp wird nicht versendet"

- Die betroffenen Belege sind keine PDF/TIFF-Dateien (oder nicht in `SUPPORTED_FILE_TYPES_FOR_SENDING` aufgeführt).
- Fotos: Smart Rule einrichten (Installation, Schritt 6) oder manuell in DEVONthink zu PDF konvertieren.
- Office-Dateien: in der jeweiligen Anwendung als PDF exportieren.

### Hinweis „Beleg allein schon zu groß für eine Mail"

- PDF verkleinern (z.B. Vorschau → Exportieren → Quartz-Filter „Reduce File Size") oder getrennt versenden.
- Ggf. `MAX_MAIL_SIZE_MB` prüfen – der Wert muss zum Limit des Empfängers passen.

### "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

### Debug-Log

Mit `WRITE_DEBUG_LOG=true` schreibt das Script ein ausführliches Protokoll nach `/tmp/DT-Belegversand-debug.log`. Bei Problemen ist das die erste Anlaufstelle.

---

## Versionshistorie

Siehe [CHANGELOG]

---

## Support

Für technische Fragen:
- Siehe [Wiki-Dokumentation](https://wiki.tuxi.ddnss.de/wiki/Belegversand)
- Oder erstelle ein Issue im Gitea-Repository (falls Zugriff vorhanden)

---

**Hinweis**: Dieses System ist eine AppleScript-Automatisierung und stark abhängig von macOS und DEVONthink-APIs. Änderungen am System können Anpassungen erfordern.