Initial version of the E-Invoice solution of JR IT Services

Documentation.md

@@ -0,0 +1,120 @@
+# Documentation
+
+## Resilienz & Logs
+- YAML wird strikt validiert (Pydantic) -> frühzeitige, klare Fehler.
+- Pro Run: `out/logs/run.log` (DEBUG-level File Log, inkl. Stacktraces).
+- Mustang stdout/stderr wird ebenfalls geloggt.
+
+## PDF Rendering
+Priorität:
+1) WeasyPrint (wenn installiert)
+2) wkhtmltopdf (wenn vorhanden)
+
+Wenn beides fehlt -> klarer Fehler.
+
+## Combine + Validate (Mustang) – standardmäßig aktiv
+Combine:
+`java -jar Mustang-CLI.jar --action combine --source invoice.pdf --source-xml factur-x.xml --out invoice.facturx.pdf --profile E`
+
+Validate:
+`java -jar Mustang-CLI.jar --no-notices --action validate --source invoice.facturx.pdf`
+
+## YAML Schema
+Siehe `examples/invoice.sample.yaml`
+
+## Hinweis zum XML
+Aktuell erzeugt `facturx.py` ein **minimal stabiles** EN16931 XML (Nummer/Datum/Währung/Gesamt).
+Für maximale Empfänger-Kompatibilität erweitere `facturx.py` um Seller/Buyer/Lines/Tax breakdown etc.
+
+
+## Init Command
+
+`jr-einvoice init <invoice_dir>` erstellt:
+
+- `invoice.yaml` (Vorlage)
+- optional `assets/` Ordner (für Logos etc.)
+- `.gitkeep` Dateien damit Git die Ordner behält
+
+Damit kannst du pro Rechnung einen neuen Ordner anlegen und direkt editieren.
+
+
+## Presets
+
+- `presets/seller.default.yaml`: deine Standard-Seller- und Payment-Daten
+- `presets/customers.yaml`: Kunden-Vorlagen (case-insensitive Keys)
+
+Init merge order:
+1) `examples/invoice.init.yaml` (Basis)
+2) `presets/seller.default.yaml`
+3) `presets/customers.yaml` (wenn --customer gesetzt)
+4) Smart defaults (heutiges Datum, due_days, reference)
+
+## Assets / Logo
+
+`jr-einvoice init` kopiert standardmäßig `assets/logo.svg` nach `<invoice_dir>/assets/logo.svg`.
+Das Template referenziert `assets/logo.svg` relativ – WeasyPrint bekommt dafür `base_url=<invoice_dir>`.
+
+## Setup Mustang
+
+`jr-einvoice setup-mustang` lädt das Jar von Maven Central (repo1.maven.org) und prüft optional die `.sha1` Datei.
+
+
+## Auto-Rechnungsnummer
+
+Wenn du bei `init` **keine** `--invoice-number` angibst, aber `--invoices-root` setzt, dann wird die nächste Nummer vorgeschlagen.
+
+Standard-Pattern: `YYYY-NNNN` (z.B. 2026-0007). Gesucht wird in Ordnernamen unter `--invoices-root`.
+
+Implementierung: `jr_einvoice/invoice_number.py`.
+
+## Customer Presets (Datei pro Kunde)
+
+Bevorzugt: `presets/customers/<customer>.yaml`
+
+Fallback: `presets/customers.yaml` (Map `customers:`)
+
+## Mustang Update Check
+
+`jr-einvoice mustang-update` liest Maven metadata und vergleicht mit `tools/mustang/VERSION.txt`.
+Mit `--apply` wird die neueste Version geladen und installiert (inkl. optional SHA1-Check).
+
+
+## Auto Folder Name
+
+Mit `jr-einvoice init invoices --auto-folder --customer unicredit` wird ein Unterordner erzeugt:
+
+`Rechnung_<invoice_number>_<customer>`
+
+Sanitizing/slugging in `jr_einvoice/folder_naming.py`.
+
+## Open Editor
+
+Mit `--open` wird `invoice.yaml` nach dem Init in `$EDITOR` geöffnet.
+Fallback-Reihenfolge: `code`, `codium`, `nano`, `vim`, `vi`.
+
+
+## Script output
+
+- `--print-path` prints the created folder path after the panel
+- `--print-path-only` prints only the path (no rich output)
+
+## Auto open
+
+- `--open` opens unconditionally (needs an editor available)
+- `--open-auto` opens only when a GUI session is detected (DISPLAY/WAYLAND_DISPLAY) and stdout is a TTY
+
+
+## Generate artifact output
+
+Options:
+
+- `--print-artifacts`: prints paths after the rich OK output
+- `--print-artifacts-only`: prints only the paths (one per line) in this order:
+  1) invoice.pdf
+  2) factur-x.xml
+  3) invoice.facturx.pdf
+  4) validation/validate_report.xml
+  5) out/logs/run.log
+
+- `--json`: prints a JSON object with keys:
+  - invoice_dir, out_dir, invoice_pdf, facturx_xml, facturx_pdf, validate_report, log