einvoice/README.md

# einvoice – Rechnung mit einem Konsolenaufruf

Kundenname, Leistung, Menge und Nettopreis eingeben: `einvoice --create` erledigt
Rechnungsnummer, Berechnung, PDF/A-Erstellung, Einbettung des EN16931-XML und
technische Validierung. Das fertige ZUGFeRD/Factur-X-PDF kannst du direkt an eine
E-Mail anhängen. Alles läuft lokal.

## Direkt loslegen

Auf diesem Rechner sind Python-Umgebung, Absenderdaten und Mustang eingerichtet.

```bash
cd /home/johannes/localdev/einvoice
python3 scripts/install_commands.py  # einmalig; auf diesem Rechner bereits eingerichtet

einvoice --create \
  --Customer "Meine Kundenfirma GmbH" \
  --Entry "Geleistete Stunden Oktober 2026" \
  --Volume 120 \
  --Price "85,00 €"
```

Bei einem **neuen Kunden** fragt die Konsole einmalig Straße/Hausnummer, Postleitzahl
und Ort ab. Bei späteren Rechnungen genügt der gleiche Kundenname. Groß- und
Kleinschreibung sind beim Kundennamen gleichgültig. `einvoice --customers` listet
die gespeicherten Kunden samt Schlüssel auf. Es ist kein Standardkunde vorgewählt.
IDV ist ausschließlich ein historisches Beispiel aus früheren Rechnungen.

Der Preis ist **netto je Einheit**. Standard: Stunden (`HUR`), 19 % USt, heute als
Rechnungsdatum und 30 Tage Zahlungsziel. Im Beispiel entstehen 10.200,00 EUR netto,
1.938,00 EUR USt und **12.138,00 EUR brutto**. „Oktober 2026“ in der Beschreibung
wird als Leistungsmonat erkannt. Für Teilmonate/andere Leistungen `--Month` oder
`--ServiceDate` ausdrücklich setzen und die tatsächlichen Leistungsdaten verwenden.

```text
Rechnungsdaten vollständig: JR-2026-0001 · Meine Kundenfirma GmbH
PDF/A und strukturierte Rechnungsdaten werden erzeugt …
Rechnung validiert: PDF/A und EN16931-XML technisch gültig.
Rechnung erzeugt · Netto: 10.200,00 EUR · USt: 1.938,00 EUR · Brutto: 12.138,00 EUR
Leistung: 2026-10-01 bis 2026-10-31
PDF zum Anhängen an deine E-Mail:
…/Rechnung_JR-2026-0001_…/Rechnung_JR-2026-0001.pdf
Prüfbericht: …/out/validation/validate_report.xml
Vor Versand Leistungsdaten, Betrag und Empfänger prüfen.
```

**Die ausgegebene `Rechnung_<Nummer>.pdf` ist die vollständige E-Rechnung**, inklusive
XML. Direkt anhängen; nicht über einen PDF-Drucker neu drucken, weil dabei das XML
verloren gehen kann. Die Ausgabe bestätigt die erfolgreiche technische Prüfung.
Sie garantiert nicht pauschal die sachliche oder steuerliche Richtigkeit deiner
Eingaben. Details: [Rechtsstand und Grenzen](docs/e-rechnung-2027.md).

Ein vollständiger Ablauf mit Projektbeschreibung, PDF-Anhang, Mailbetreff,
Textvorlage und Versand steht im [fiktiven Halian-Beispiel](docs/beispiel-workflow-halian.md).

## Optionen für Alltag und Skripte

```bash
# Neue Kundenanschrift ohne Rückfragen übergeben:
einvoice --create --Customer "Neue Firma GmbH" \
  --Street "Kundenstraße 12" --PostalCode 10115 --City Berlin \
  --Email rechnung@empfaenger.example \
  --Entry "IT-Beratung" --Volume "7,5" --Price "120,00 EUR" \
  --ServiceDate 2026-10-15 --non-interactive

# Bekannter Kunde, expliziter Monat und Bestellbezug:
einvoice --create --Customer "Meine Kundenfirma GmbH" \
  --Entry "Softwareentwicklung" --Volume 120 --Price "85,00 €" \
  --Month 2026-10 --OrderReference "PO-12345" --DueDays 14

# Beispiel für eine Stückposition:
einvoice --create --Customer "Meine Kundenfirma GmbH" \
  --Entry "Dokumentationspaket" --Volume 1 --Unit C62 --Price "500,00 €"
```

Weitere Optionen: `--Number`, `--Date`, `--Tax`, `--BuyerReference`, `--Country`,
`--VatId`, `--root`, `--json`. Alle Fachoptionen haben auch kleingeschriebene
Varianten (`--customer`, `--entry`, …); `einvoice --help` zeigt sie an.
`--json` liefert Artefaktpfade und den technischen Prüfstatus ohne Fragen.

Die Nummer lautet automatisch `JR-JJJJ-NNNN` und wird im Rechnungsstamm unter
Dateisperre vergeben. `--Number` setzt eine ausdrücklich gewählte freie Nummer.
Vorhandene PDF-Rechnungen außerhalb dieses Stamms werden nicht automatisch
eingelesen. Das Präfix JR trennt die neue Serie von früheren `JJJJ-MM`-Nummern.
Bei einem technischen Fehler bleibt der reservierte Entwurf samt Log zur Diagnose
erhalten; zum Wiederholen `jr-einvoice generate <Rechnungsordner>` verwenden.

## Abhängigkeiten sicher aktualisieren

```bash
cd /home/johannes/localdev/einvoice
python3 scripts/update.py           # neueste kompatible Pakete + Mustang aufbauen und testen
python3 scripts/update.py --apply   # testen, aktivieren, nochmals prüfen
python3 scripts/update.py --status  # aktiven Stand anzeigen (offline)
python3 scripts/update.py --rollback # vorherigen Stand prüfen und wieder aktivieren (offline)
```

Der Ablauf prüft Python-Paketabhängigkeiten, WeasyPrint/PDF-Erzeugung, beide CLIs
und die vollständige Testsuite einschließlich echter Mustang-Validierung und
ungültiger Gegenbeispiele. Schlägt ein Test vor Aktivierung fehl, bleibt die bisherige
Laufzeit aktiv. Schlägt die Prüfung danach fehl, wird automatisch zurückgeschaltet.
Die Konsole zeigt Schritte, Versionsänderungen und Fehler; vollständige Logs liegen
in `.runtime/logs/`. Netzwerk ist nur für neue Kandidaten nötig. Ohne `--apply`
werden Downloads, Installation und Tests ausgeführt, aber keine Umschaltung.

**Konsolenbefehle einmalig im Benutzer-Suchpfad einrichten:**

```bash
python3 scripts/install_commands.py
# Danach aus jedem Verzeichnis, ohne venv-Aktivierung:
einvoice --customers
einvoice --update --apply
einvoice --update --rollback
jr-einvoice --help
```

Der Installer verlinkt beide Starter nach `~/.local/bin` und prüft ihre Funktion.
Dort vorhandene andere Befehle werden vor dem Ersetzen gesichert. Wiederholtes
Ausführen ist möglich. Auf diesem Rechner ist das Verzeichnis bereits im PATH.
Bei einem gespeicherten alten Shell-Pfad einmal `rehash` (zsh) bzw. `hash -r`
(bash) ausführen. Eine aktivierte `.venv` kann die Befehle überdecken: dann
`deactivate` ausführen. Direkte Aufrufe von `.venv/bin/einvoice` verwenden weiterhin
die ursprüngliche Entwicklerumgebung.
Java und native Bibliotheken werden mitgetestet, aber über den Systempaketmanager
aktualisiert; dessen Änderungen kann dieser Updater nicht zurückrollen.
Details und Grenzen: [Update-Betrieb](Documentation.md#updates-und-rollback).

## Ohne Microsoft Office / Microsoft 365

Die Rechnungslösung benötigt weder Word, Excel, Outlook noch Microsoft 365.
Es gibt keine DOC/DOCX-, XLS/XLSX- oder PPT/PPTX-Vorlagen und keine Office-Automation.
Auch LibreOffice muss zur Rechnungserstellung nicht installiert sein.

| Zweck | Verwendetes Format |
| --- | --- |
| Rechnungsdaten und Stammdaten | YAML (`.yaml`) |
| Layout | HTML/Jinja2 (`.html.j2`), Logo als SVG |
| Fertige E-Rechnung | PDF/A-3 mit eingebettetem EN16931-XML |
| Optionaler Mailentwurf | EML (`.eml`), ohne Outlook-Anbindung |
| Dokumentation | Markdown (`.md`) |

Ein Wechsel auf LibreOffice erfordert für dieses Projekt keine Dateikonvertierung.
ODT-/ODS-Dateien werden aktuell weder eingelesen noch erzeugt. Layoutänderungen
finden in der HTML-Vorlage statt. Das fertige E-Rechnungs-PDF direkt versenden;
nicht zum Bearbeiten konvertieren oder neu als PDF exportieren, da eingebettete
Rechnungsdaten oder die geprüfte PDF/A-Struktur verloren gehen können.
Die tatsächliche E-Mail-Zustellung erfolgt weiterhin über dein separat eingerichtetes
Mailprogramm bzw. Konto; sie wird von diesem Tool nicht bereitgestellt.

## Daten und Einrichtung

- Absender: **johannes@jr-it-services.de**, lokale Vorlage `private/presets/seller.default.yaml`.
- Kunden: `private/presets/customers/`; neue Kunden werden dort mit geschützter Dateiberechtigung gespeichert.
- Rechnungen: `private/invoices/`, jeweils in einem eigenen geschützten Ordner.
- Eigenes Logo optional: `private/presets/logo.svg`, sonst mitgeliefertes JR-Logo.
- Persönliche Daten, Rechnungen und Ausgabeordner werden nicht mit Git veröffentlicht.

Andere Datenablage: `JR_EINVOICE_HOME=/absoluter/pfad`; nur die Vorlagen umleiten:
`JR_EINVOICE_PRESETS=/absoluter/pfad`. Nach Wheel-Installation ist der Standard
`~/.local/share/jr-einvoice/`. Bei einem frischen Checkout zuerst die vollständigen
eigenen Absender-/Zahlungsdaten lokal konfigurieren; `create` verwendet keine
versionierten Musteradressen als echte Geschäftsdaten.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[pdf]'
jr-einvoice setup-mustang --version 2.26.0
```

Java und die WeasyPrint-Systembibliotheken müssen installiert sein; für Arch siehe
`scripts/arch_install.sh`. Die bisherigen `jr-einvoice`-Befehle bleiben verfügbar:
YAML-Entwürfe, mehrere Positionen, Neuerzeugung, Eingangskontrolle und optionaler
EML-Mailentwurf mit Absender aus den eigenen Stammdaten.

```bash
jr-einvoice email /pfad/zum/rechnungsordner --to rechnung@empfaenger.example
jr-einvoice validate /pfad/eingangsrechnung.xml --report private/eingang-pruefung.xml
python -m unittest discover -s tests -v
JR_EINVOICE_INTEGRATION=1 python -m unittest discover -s tests -v
```

Unterstützt werden normale positive EUR-Rechnungen mit positiver Umsatzsteuer.
Steuerbefreiungen/Kleinunternehmer, Reverse Charge, Gutschriften/Storno und
XRechnung-Ausgabe sind noch nicht implementiert. Archivierung, DATEV-/Peppol-
Anbindung und Versandnachweis bleiben im betrieblichen Ablauf. Nach dem Versand
PDF, strukturierte Daten, Prüfbericht und Versandnachweis gesichert aufbewahren.

[Ausführliche Dokumentation](Documentation.md) ·
[Rechtsstand und Abgleich mit der INTEGRA-Mail](docs/e-rechnung-2027.md)