docs: add fictional Halian invoice and email workflow

docs/beispiel-workflow-halian.md

@@ -0,0 +1,131 @@
+# Beispiel: Halian GmbH – Oktober 2026
+
+Fiktiver Ablauf vom Konsolenaufruf bis zum Versand über dein Mailprogramm.
+Es wird durch diese Dokumentation keine Rechnung erstellt und keine E-Mail versendet.
+
+Für das Beispiel nehmen wir **120 tatsächlich geleistete Stunden** an. „85 EUR
+all in“ bedeutet hier **85 EUR netto pro Stunde einschließlich aller Nebenkosten,
+zuzüglich 19 % Umsatzsteuer**. Falls vertraglich 85 EUR einschließlich Umsatzsteuer
+vereinbart sind, passt dieser Nettopreis nicht; zuerst die Preisbasis klären.
+Die Rechnungsanschrift und etwaige Bestellnummer müssen aus dem Auftrag stammen;
+hier wird keine reale Halian-Anschrift behauptet. `invoice@halian.com` ist die für
+dieses Beispiel von dir vorgegebene Versandadresse, keine unabhängig geprüfte Adresse.
+
+## 1. Rechnung erzeugen
+
+Nach Abschluss des Leistungsmonats, im Beispiel am **31.10.2026**:
+
+```bash
+cd /home/johannes/localdev/einvoice
+
+einvoice --create \
+  --Customer "Halian GmbH" \
+  --Entry "C# Entwicklung Bank Projekt – Geleistete Stunden Oktober 2026" \
+  --Volume 120 \
+  --Price "85,00 €" \
+  --Month 2026-10 \
+  --Date 2026-10-31 \
+  --DueDays 30
+```
+
+Stunden, Preis, Datum und Zahlungsziel für eine echte Rechnung entsprechend dem
+Auftrag anpassen. Bei einem **neuen Kunden** fragt die Konsole Straße/Hausnummer,
+Postleitzahl und Ort ab. Dort die vollständige Rechnungsanschrift laut Auftrag
+angeben. Sie wird lokal gespeichert; bei weiteren Rechnungen reicht derselbe
+Kundenname. Bei Bedarf `--OrderReference "BESTELLNUMMER-LAUT-AUFTRAG"` ergänzen.
+Keine erfundene Bestellnummer übernehmen.
+
+Die Nummer wird automatisch vergeben. Angenommen, die Konsole meldet
+`JR-2026-0001` (deine tatsächliche Nummer kann abweichen):
+
+```text
+Rechnungsdaten vollständig: JR-2026-0001 · Halian 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
+```
+
+Das Zahlungsziel ist im Beispiel **30.11.2026**. Die Konsole nennt zusätzlich den
+Prüfbericht. Bei einem Fehler erst den Entwurf korrigieren und erneut validieren;
+keine Sichtkopie als Ersatz versenden.
+
+## 2. PDF prüfen und im Mailprogramm anhängen
+
+1. Die unter **„PDF zum Anhängen an deine E-Mail“** ausgegebene Datei öffnen.
+   Kundenanschrift, Projekt, tatsächliche Stunden, Leistungszeitraum, Rechnungsnummer,
+   Bankverbindung und Gesamtbetrag prüfen.
+2. Im Mailprogramm eine neue Nachricht mit Absender **johannes@jr-it-services.de**
+   an **invoice@halian.com** anlegen.
+3. Die ausgegebene `Rechnung_<tatsächliche Nummer>.pdf` im Dateimanager markieren
+   und per Drag-and-drop in die Nachricht ziehen. Alternativ über die Büroklammer
+   „Datei anhängen“ auswählen; im Dateiauswahldialog den vollständigen PDF-Pfad aus
+   der Konsole einfügen. **Den Pfad in den Mailtext zu kopieren hängt die Datei nicht an.**
+4. Prüfen, dass die Nachricht einen PDF-Anhang mit dem richtigen Dateinamen enthält.
+   Die Originaldatei anhängen; nicht neu als PDF drucken oder konvertieren. Das
+   strukturierte XML ist bereits eingebettet. `out/invoice.pdf` ist nur die Sichtkopie.
+
+**Betreff** – Rechnungsnummer durch die tatsächlich ausgegebene Nummer ersetzen:
+
+```text
+Rechnung JR-2026-0001 | Oktober 2026 | C# Entwicklung Bank Projekt
+```
+
+**Textvorschlag:**
+
+```text
+Sehr geehrte Damen und Herren,
+
+anbei erhalten Sie meine Rechnung JR-2026-0001 für das Projekt
+„C# Entwicklung Bank Projekt“ im Leistungszeitraum 01.10.2026 bis 31.10.2026.
+
+Abgerechnet werden 120 Stunden zu 85,00 EUR netto pro Stunde.
+Der Rechnungsbetrag beträgt 12.138,00 EUR einschließlich 19 % Umsatzsteuer.
+Bitte überweisen Sie den Betrag bis zum 30.11.2026 unter Angabe der
+Rechnungsnummer auf das in der Rechnung genannte Konto.
+
+Die Rechnung ist als ZUGFeRD/Factur-X-PDF mit eingebetteten strukturierten
+Rechnungsdaten beigefügt.
+
+Vielen Dank und freundliche Grüße
+Johannes Rest
+JR IT Services
+johannes@jr-it-services.de
+```
+
+## 3. Absenden und ablegen
+
+Empfängeradresse mit dem Auftrag abgleichen und Betreff, Text, tatsächliche
+Rechnungsnummer und Anhang noch einmal vergleichen. Bei vereinbartem
+Stundennachweis diesen zusätzlich beifügen. Anschließend im Mailprogramm
+**„Senden“** wählen.
+
+Die gesendete Originalmail samt Anhang und vollständigen Rechnungsordner mit XML,
+Prüfbericht und Prüfsummen in der gesicherten Ablage aufbewahren. Eine Kopie im
+Gesendet-Ordner belegt noch keine Annahme beim Empfänger; Rückläufer bzw.
+Empfangsbestätigungen berücksichtigen. Versandte Rechnungen nicht überschreiben.
+
+## Optional: E-Mail-Entwurf bereits mit Anhang erzeugen
+
+Statt die Datei manuell anzuhängen, kann der vorhandene Rechnungsordner an den
+Mailentwurfsbefehl übergeben werden. Im folgenden Beispiel den Platzhalter durch
+den **vollständigen tatsächlichen Rechnungsordner** ersetzen, nicht durch den PDF-Pfad:
+
+```bash
+/home/johannes/localdev/einvoice/.venv/bin/jr-einvoice email \
+  "/VOLLSTAENDIGER/PFAD/ZUM/RECHNUNGSORDNER" \
+  --to invoice@halian.com
+```
+
+Der Befehl erzeugt und validiert erneut und legt `out/invoice.eml` an. Diese Datei
+im Mailprogramm als Entwurf öffnen (ggf. „Als neue Nachricht bearbeiten“). Absender,
+Empfänger und PDF-Anhang sind vorbereitet; **Projektbetreff und ausführlichen Text
+oben bei Bedarf einsetzen**, denn der automatische Entwurf verwendet einen
+allgemeinen Rechnungsbetreff und einen kürzeren Standardtext. Prüfen und anschließend
+selbst absenden. Der Befehl versendet nicht automatisch.
+
+Wenn dein Mailprogramm EML-Dateien nur anzeigt, den manuellen Ablauf mit einer
+neuen Nachricht verwenden. Zum Erstellen einer Rechnung genügt `einvoice --create`;
+der EML-Schritt ist eine optionale Versandhilfe.