c-stone-invoice-check/README.md
Markus Kruse 4f9bec81fe feat(tools): Qonto-Abgleich, Mailsuche, PDF-Export, Accountable-Helfer
Wiederverwendbare Session-Skripte parametrisiert ins Repo; Cron Wochenlauf in README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Wd9aeEvgYF6ZmZGc5PTULK
2026-11-15 19:25:53 +01:00

69 lines
2.6 KiB
Markdown

# C-Stone Invoice Check
## Zweck
KI-gestütztes Email-Filter-System für Rechnungen mit automatischer PDF-Scanning, lokaler Ablage auf Evo-X2 und Excel-Dokumentation.
## Was das System macht
1. **Email-Filterung** per IMAP (Strato + Gmail) nach Stichworten: "Rechnung", "Invoice", "Receipt"
2. **Anhang-Extraktion** (PDF/DOC) aus erkannten Emails
3. **PDF-Scanning** mit PyMuPDF für Text-Extraktion
4. **Steuer-Erkennung**: Unterscheidung zwischen "mit MwSt" / "ohne MwSt" / "Umsatzsteuer" / "VAT"
5. **Lokale Ablage** auf Evo-X2:
```
Rechnungen/
├── 2025/
│ ├── mit MwSt/
│ └── ohne MwSt/
└── 2026/
├── mit MwSt/
└── ohne MwSt/
```
6. **Excel-Dokumentation** mit Spalten: Datum, Rechnungsausteller, Betrag, Umsatzsteuer, Steuerart, Dateipfad
## Voraussetzungen
```bash
pip3 install fastapi uvicorn python-dotenv sqlalchemy psycopg2-binary openpyxl pymupdf
```
## Konfiguration
1. `.env.example` nach `.env` kopieren
2. IMAP-Credentials für Strato/Gmail eintragen (App-Passwords verwenden!)
3. Ablagepfad auf Evo-X2 anpassen (`INVOICE_STORAGE_PATH`)
## Ablauf
1. System starten: `uvicorn backend.main:app --reload --port 8001`
2. Frontend öffnen: `http://localhost:5173`
3. IMAP-Verbindung wird periodisch geprüft
4. Neue Rechnungen werden automatisch verarbeitet und gespeichert
## DSGVO
- Alle Daten bleiben lokal auf Evo-X2
- Keine Datenverarbeitung in der Cloud
- PyMuPDF läuft vollständig lokal
## Wochenlauf (Cron NucBox)
```
0 6 * * 0 docker exec -w /app -e PYTHONPATH=/app invoice-check-backend python -m backend.grabber --send --report >> /home/c-stone-ai-lab/invoice-check/grabber.log 2>&1
```
## Tools (`tools/`)
| Datei | Zweck | Aufruf |
|-------|-------|--------|
| `qonto_abgleich.py` | Qonto-Auszüge (Text) ↔ Accountable-Export, Monatssummen + Lücken | lokal: `python3 tools/qonto_abgleich.py <ordner> [stichtag]` |
| `mail_suche.py` | Postfächer (alle Ordner) nach Begriffen durchsuchen | Container, s. u. |
| `mail_pdfs.py` | PDF-Anhänge nach Absender/Betreff speichern | Container, s. u. |
| `accountable_helfer.js` | Banktx → neue Ausgabe im Accountable-Tab | Anleitung im Dateikopf |
Container-Skripte (brauchen `backend` + IMAP-Env):
```bash
scp tools/mail_suche.py c-stone-ai-lab@nucbox:/tmp/ && ssh c-stone-ai-lab@nucbox 'docker cp /tmp/mail_suche.py invoice-check-backend:/tmp/ && docker exec -w /app -e PYTHONPATH=/app invoice-check-backend python /tmp/mail_suche.py <begriff>; rm /tmp/mail_suche.py'
```
Danach `/tmp` im Container aufräumen. Ergebnisse (Belege, Listen) nur lokal unter `lokal/` ablegen, nie committen.