techadmin
76c3a991df
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>
118 lines
4.5 KiB
Markdown
118 lines
4.5 KiB
Markdown
# 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)
|