Initial commit: PDF OCR Hotfolder v0.1.0

Komplettes Rewrite des alten Bash-Tools `pdf-tool` in Python. - ocrmypdf als Library, watchdog für Hotfolder, ThreadPool für Parallelität - Upload-Targets: folder, Nextcloud (WebDAV), SFTP - E-Mail-Notify, optional veraPDF - Interaktiver Installer mit Service-User-Support (lokal + AD via SSSD) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-08 00:22:31 +02:00
commit 76c3a991df
16 changed files with 1261 additions and 0 deletions
@@ -0,0 +1,117 @@
+# AI Agent Briefing — PDF OCR Hotfolder
+
+**Zuletzt aktualisiert:** 2026-04-08
+**Version:** 0.1.0
+**Status:** Initiale Implementation, nicht produktiv getestet
+
+## 🎯 Projektziel
+
+Eingehende gescannte PDFs werden automatisch durch OCR (ocrmypdf + Tesseract) in durchsuchbare PDFs (optional PDF/A) umgewandelt und nach Wahl in einen Ordner / Nextcloud / per SFTP weitergegeben. Ersetzt das alte Bash-Tool `pdf-tool` (im Workspace).
+
+## 📁 Projekt-Struktur
+
+```
+pdf-ocr-hotfolder/
+├── pdf_ocr_hotfolder/
+│   ├── __init__.py        # Versionsstring
+│   ├── __main__.py        # CLI-Entrypoint (argparse, --once, --config)
+│   ├── config.py          # TOML-Loader, Dataclasses
+│   ├── service.py         # Hauptservice (watchdog + ThreadPool)
+│   ├── processor.py       # ocrmypdf + veraPDF
+│   └── uploaders.py       # folder, nextcloud (WebDAV), sftp, email
+├── systemd/
+│   └── pdf-ocr-hotfolder.service  # Template (Platzhalter __SERVICE_USER__/__SERVICE_GROUP__)
+├── config.example.toml
+├── install.sh             # Interaktiver Installer
+├── update.sh              # Update aus Repo
+├── requirements.txt
+├── VERSION
+├── CHANGELOG.md
+└── README.md
+```
+
+## 🔧 Stack
+
+| Komponente | Technologie |
+|------------|-------------|
+| Sprache | Python 3.11+ (für `tomllib` aus stdlib) |
+| OCR | `ocrmypdf` (als Library, nicht via Subprozess) |
+| Engine | Tesseract |
+| Watcher | `watchdog` |
+| HTTP | `requests` (Nextcloud WebDAV) |
+| SFTP | `paramiko` |
+| Email | `smtplib` (stdlib) |
+| Service | systemd |
+
+## 🖥️ Installations-Layout
+
+| Pfad | Inhalt |
+|------|--------|
+| `/opt/pdf-ocr-hotfolder/` | Code + venv (`venv/bin/python`) |
+| `/etc/pdf-ocr-hotfolder/config.toml` | Konfiguration (mode 640, root:<service-group>) |
+| `/var/lib/pdf-ocr-hotfolder/{incoming,working,outgoing,error}/` | Datenverzeichnisse |
+| `/var/log/pdf-ocr-hotfolder/` | Logs (zusätzlich zu journald) |
+| `/etc/systemd/system/pdf-ocr-hotfolder.service` | systemd-Unit |
+| `/var/backups/pdf-ocr-hotfolder/` | Update-Backups |
+
+## 👤 Service-User
+
+Der Installer fragt interaktiv:
+1. Username (default `pdfocr`)
+2. Falls User existiert (lokal oder AD via SSSD/Winbind): wird übernommen, primäre Gruppe automatisch erkannt
+3. Falls nicht: Frage nach lokaler Anlage als System-User
+
+**Wichtig:** Bei AD-Usern mit lokaler UID werden Datei-Berechtigungen über die UID gesetzt — funktioniert transparent.
+
+## 🔄 Verarbeitungs-Flow
+
+1. `watchdog` triggert auf Datei-Event in `incoming/`
+2. `_wait_until_stable()` wartet, bis Datei nicht mehr wächst (Scanner schreibt mehrmals)
+3. Move nach `working/`
+4. `ocrmypdf.ocr()` als **Library-Call** (kein Subprozess-Start pro PDF — schneller)
+5. Optional: veraPDF-Validierung (CLI-Subprozess)
+6. Move nach `outgoing/` als `OCR_<originalname>.pdf`
+7. Aktive Upload-Targets ausführen (folder/nextcloud/sftp)
+8. Optional E-Mail-Notify
+
+Fehler → Move nach `error/`, Service läuft weiter (kein `exit 1` wie im alten Bash-Tool).
+
+## 🧠 Performance-Entscheidungen
+
+- **ocrmypdf als Library** statt `subprocess`: spart Python-Interpreter-Start pro PDF
+- **ThreadPool** mit `max_workers` (default 2) — selbst wenn selten >1 PDF gleichzeitig kommt, blockiert ein langsamer Scan keinen schnellen
+- **`--jobs` an ocrmypdf**: Tesseract parallelisiert Seiten innerhalb eines PDFs
+- **`skip_text=True`**: bereits OCR-haltige Seiten werden nicht neu verarbeitet
+- **Stabilitäts-Check** statt magic-file `new` (alte Bash-Krücke)
+- veraPDF nur wenn `enabled=true` (JVM-Start ist teuer)
+
+## 🛠️ Entwicklung
+
+Lokaler Test ohne Installation:
+```bash
+cd ~/dev/gitea.sonith.de/pdf-ocr-hotfolder
+python3 -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+cp config.example.toml /tmp/config.toml
+# Pfade in /tmp/config.toml auf Test-Verzeichnisse anpassen
+python -m pdf_ocr_hotfolder --config /tmp/config.toml
+```
+
+## 📋 Roadmap / TODO
+
+- [ ] Tests (`pytest`) für `processor` und `uploaders`
+- [ ] Prometheus-Metriken (verarbeitete PDFs, Fehlerquote, Laufzeit)
+- [ ] CLI-Subkommandos: `pdf-ocr-hotfolder reprocess <error-file>`
+- [ ] Optional: S3/MinIO Upload-Target
+- [ ] Docker-Image für Setups ohne systemd
+
+## 🔑 Repo
+
+- **Repo:** https://gitea.sonith.de/sonith_ug/pdf-ocr-hotfolder
+- **Owner:** sonith_ug
+- **Versionierung:** Semver (PATCH bei jedem Build, MINOR bei Features, MAJOR manuell)
+- **Tags:** `v{VERSION}`, automatischer Push nach Commit
+
+## 📞 Kontakt
+
+**Maintainer:** Dominik Höfling (Sonith GmbH)