121 lines
3.6 KiB
Markdown
121 lines
3.6 KiB
Markdown
# 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
|