# 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