E-Rechnung/README.md

# README

## Description

Dieses Tool konvertiert Rechnungen im PDF-Format über eine Weboberfläche in die offiziellen E-Rechnungsformate XRechnung (UBL) und ZUGFeRD 2.4 (hybride PDF mit eingebettetem CII-XML). Die Datenextraktion ist vollständig deterministisch (Regex und Zeilen-Auswertung) – es wird kein LLM und kein externer Dienst verwendet, sensible Finanzdaten verlassen das lokale Netzwerk nicht.

## Zugriff

Die Anwendung läuft als Docker-Container und ist im lokalen Firmennetzwerk erreichbar unter:

http://erechnung

## Aufbau

| Datei | Zweck |
|---|---|
| `main.py` | Streamlit-Oberfläche für die Einzelrechnung, Export |
| `invoice_logic.py` | Extraktion, Berechnung, XML-Erzeugung (UBL und CII), PDF-Helfer |
| `batch_folder.py` | Ordner-Anbindung und Ampel-Bewertung des Stapelbetriebs (ohne Streamlit) |
| `batch_mode.py` | Oberfläche des Stapelbetriebs |
| `intro_overlay.py` | Intro-Video beim ersten Besuch |

## Installation (Docker)

### 1. Repository holen

```cmd
git clone https://gitea.scitech-gmbh.de:8443/dfuhrmann/E-Rechnung.git
cd E-Rechnung
```

### 2. Austauschordner einbinden (optional)

**Für den Stapelbetrieb nicht erforderlich** – dort können die PDFs einfach hochgeladen werden. Dieser Schritt ist nur sinnvoll, wenn die Rechnungen ohnehin auf einer Netzwerkfreigabe liegen und Sie sich das Hoch- und Herunterladen sparen wollen.

Ist ein Verzeichnis eingebunden, liest der Stapelbetrieb Rechnungen direkt daraus und schreibt die fertigen E-Rechnungen zurück. Die Netzwerkfreigabe wird dafür in `docker-compose.yml` eingetragen – der Container arbeitet dann **direkt** auf ihr, es wird nichts kopiert oder synchronisiert.

Der Windows-Pfad wird dabei in Docker-Schreibweise angegeben: aus `\\FS01\Daten\Technik\AI` wird `//FS01/Daten/Technik/AI`.

**1. Zugangsdaten hinterlegen** – nicht in `docker-compose.yml`, sondern in einer `.env`-Datei. Diese ist in `.gitignore` eingetragen und landet nicht im Repository:

```cmd
copy .env.example .env
```

Dann `.env` öffnen und Benutzer, Passwort und Domäne des Dienstkontos eintragen. Das Konto braucht Lese- **und** Schreibrechte auf der Freigabe.

**2. Volume aktivieren** – in `docker-compose.yml` den Block am Dateiende einkommentieren sowie beim Service `- datev_austausch:/data` statt `- ./batch_data:/data` verwenden. Beides steht dort vorbereitet.

Wichtig: Binden Sie den **übergeordneten** Ordner ein, nicht einen einzelnen Unterordner. `Test1`, `Test2` und jeder künftige Unterordner sind dann in der Oberfläche frei wählbar, ohne dass diese Datei erneut angefasst werden muss.

Ist die Freigabe auf dem Docker-Host bereits eingehängt, genügt stattdessen ein einfacher Bind-Mount ohne Zugangsdaten (`- /mnt/fs01/Daten/Technik/AI:/data`).

Ein Eintippen des Pfads in der Oberfläche ist nicht möglich: Die Anwendung läuft auf dem Server, der Browser auf Ihrem PC – ein dort gewählter Pfad wäre für den Server bedeutungslos, und Browser geben Web-Anwendungen aus Sicherheitsgründen keine Dateipfade.

Wird nichts eingebunden, funktioniert die Einzelrechnung uneingeschränkt; der Stapelbetrieb weist dann auf den fehlenden Mount hin.

### 3. Container bauen und starten

```cmd
docker compose up -d --build
```

Die Anwendung ist danach unter `http://localhost:8040` (bzw. im Firmennetz unter `http://erechnung`) erreichbar.

---

## Use

Die Betriebsart wird links in der Seitenleiste gewählt.

### Einzelrechnung

1. **Dokumenten-Upload:** Laden Sie die Rechnungs-PDF über die Weboberfläche hoch. Die PDF wird direkt zur Kontrolle angezeigt.
2. **Leistungsnachweise (optional):** Bis zu drei weitere PDFs anhängen. Ihre Seiten werden beim ZUGFeRD-Export ans Ende der Rechnung gehängt, sodass eine einzelne PDF entsteht. Aus diesen Dateien werden keine Daten ausgelesen.
3. **Extraktion:** Starten Sie die Analyse über den Button "Daten extrahieren".
4. **Validierung:** Prüfen Sie die extrahierten Kopfdaten und die Positionstabelle. Alle Felder sind editierbar. Pflichtfelder sind mit :red[*] markiert; der Export wird blockiert, solange Pflichtangaben fehlen.
5. **Export:** Wählen Sie das Format (XRechnung-XML oder ZUGFeRD-PDF) und starten Sie den Download.

### Stapel

Mehrere Rechnungen in einem Durchgang. Es ist **keine Einrichtung nötig** – der Stapel funktioniert direkt.

1. **Dateien auswählen:** Markieren Sie im Explorer alle gewünschten Rechnungs-PDFs und ziehen Sie sie in das Upload-Feld. Lokale Ordner und Netzlaufwerke funktionieren gleichermaßen.
2. **Prüfen:** Die Übersicht zeigt je Rechnung eine Ampel. ✅ bedeutet, dass alle Pflichtangaben vorliegen **und** die Summe der erkannten Positionen zur ausgewiesenen Bemessungsgrundlage passt. ⚠️ markierte Rechnungen nennen im Klartext, was fehlt; sie werden übersprungen und lassen sich in der Betriebsart *Einzelrechnung* korrigieren.
3. **Nachweise zuordnen (optional):** Ist ein Leistungsnachweis mit hochgeladen, ordnen Sie ihn der zugehörigen Rechnung zu. Er zählt dann nicht mehr als eigene Rechnung, sondern wird hinten angehängt.
4. **Konvertieren:** Alle grünen Rechnungen werden in einem Zug verarbeitet und als ZIP zum Download angeboten.

**Optional: Ordner auf dem Server.** Ist ein Austauschverzeichnis eingebunden (siehe Installation), erscheint zusätzlich die Quelle „Ordner auf dem Server". Dann werden Ein- und Ausgabeordner ausgewählt, die Ergebnisse landen direkt im Ausgabeordner und die Quelldateien wandern nach `verarbeitet` – gelöscht wird nichts. Das spart das Herunterladen, ist aber nicht Voraussetzung für den Stapelbetrieb.

## Notes

### Kontrolle durch den Sachbearbeiter

Das Tool ist ein Automations-Assistent, kein Ersatz für die fachliche Prüfung.

Im **Einzelmodus** liegen alle extrahierten Werte zur Sichtprüfung und Korrektur offen; der Export wird blockiert, solange Pflichtangaben fehlen.

Im **Stapelmodus** tritt an die Stelle der Sichtprüfung jeder einzelnen Rechnung eine Sammelfreigabe: Es werden nur Rechnungen exportiert, bei denen alle Pflichtfelder belegt sind und die Summe der erkannten Positionen exakt der auf der Rechnung ausgewiesenen Bemessungsgrundlage entspricht. Dieser Summen-Abgleich ist das entscheidende Sicherheitsnetz – er deckt eine unvollständige Positionserkennung zuverlässig auf. Alles Auffällige wird markiert und übersprungen, nie stillschweigend exportiert.

Die Verantwortung für die inhaltliche Richtigkeit der Rechnung bleibt in beiden Betriebsarten beim Sachbearbeiter.

### GoBD-Konformität

Das Tool generiert ausschließlich das strukturierte XML- bzw. hybride PDF-Format. Für die Einhaltung der GoBD-Richtlinien (u. a. die revisionssichere Archivierung der Original-PDF sowie der generierten E-Rechnung über den gesetzlichen Zeitraum von 10 Jahren) ist der Betreiber der Software selbst verantwortlich. Der Stapelbetrieb löscht keine Quelldateien, sondern verschiebt sie nach `verarbeitet`.