From a59d2af5c1646e19228d5c7d383f060a6fd43466 Mon Sep 17 00:00:00 2001 From: clawdbot Date: Sun, 1 Mar 2026 23:12:06 +0000 Subject: [PATCH] =?UTF-8?q?Docs:=20MTQ=20Mapping=20f=C3=BCr=20m=C2=B3=20do?= =?UTF-8?q?kumentiert=20+=20Patch-Datei?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md komplett überarbeitet - Beide Fixes dokumentiert (SQL + Perl) - add_mtq_mapping.patch hinzugefügt - Server-Referenz und Changelog ergänzt Fix angewendet auf: vrlnx-03-hemi (116.203.121.112) Getestet: Kivitendo 3.5.6 --- README.md | 166 ++++++++++++++++++++++++++++-------------- add_mtq_mapping.patch | 12 +++ 2 files changed, 124 insertions(+), 54 deletions(-) create mode 100644 add_mtq_mapping.patch diff --git a/README.md b/README.md index f2aea92..a56145b 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,130 @@ -# Kivitendo Einheiten-Migration für ZUGFeRD +# Kivitendo ZUGFeRD Fixes -## Zweck -Diese Skripte ändern Einheiten in Kivitendo von Text-Format zu Unicode-Hochzahlen für ZUGFeRD-Kompatibilität. +Patches und Skripte für Kivitendo zur Behebung von ZUGFeRD-Kompatibilitätsproblemen. -## Hintergrund -Kivitendo erkennt beim ZUGFeRD-Export nur bestimmte Einheiten als valide. -Die korrekten Formate sind: -- `m²` (mit hochgestellter 2) statt `m2` oder `MTK` -- `m³` (mit hochgestellter 3) statt `m3` oder `MTQ` +## Übersicht -## Dateien -- `change_m3_to_m_hoch_3.sql` - Ändert m3 → m³ +| Fix | Beschreibung | Betrifft | +|-----|--------------|----------| +| [Einheiten-Migration](#einheiten-migration-sql) | m3 → m³ in Datenbank | SQL | +| [MTQ Mapping](#mtq-mapping-perl) | m³ → MTQ Code hinzufügen | Perl | -## Anwendung +--- -### Voraussetzungen -- PostgreSQL Zugriff -- Backup der Datenbank (empfohlen!) +## Einheiten-Migration (SQL) -### Backup erstellen +### Problem +Kivitendo erkennt beim ZUGFeRD-Export nur Unicode-Hochzahlen als valide Einheiten: +- ✅ `m²` (Unicode) +- ❌ `m2` oder `MTK` (Text) + +### Lösung +**`change_m3_to_m_hoch_3.sql`** - Ändert `m3` → `m³` in der Datenbank + +### Betroffene Tabellen +- `units` (Stammdaten) +- `parts` (Artikel) +- `invoice` (Rechnungspositionen) +- `orderitems` (Auftragspositionen) +- `delivery_order_items` (Lieferscheinpositionen) +- `units_language` (Übersetzungen) + +### Anwendung ```bash +# 1. Backup erstellen! sudo -u postgres pg_dumpall > /root/postgres_backup_$(date +%Y%m%d_%H%M%S).sql -``` -### Skript ausführen -```bash +# 2. Skript ausführen sudo -u postgres psql -d -f change_m3_to_m_hoch_3.sql ``` -**Beispiel für Datenbank "hemi":** +--- + +## MTQ Mapping (Perl) + +### Problem +Kivitendo 3.5.6 hat kein Mapping für Kubikmeter (m³) im UN/ECE Recommendation 20 Helper: +- ✅ `m²` → `MTK` (funktioniert) +- ❌ `m³` → ??? (fehlt!) + +**Fehlermeldung:** +``` +Die ZUGFeRD-Rechnungsdaten können nicht erzeugt werden, da die Validierung +fehlschlug. Eine der verwendeten Einheiten (m³) kann keinem der bekannten +Einheiten-Codes aus der Liste UN/ECE Recommendation 20 zugeordnet werden. +``` + +### Lösung +Eintrag in `SL/Helper/UNECERecommendation20.pm` hinzufügen: + +```perl +# cubic volumes +[ 'MTQ', qr{^(?:m³|cbm|kubik *meter|kubik *metre|cubic *meter|cubic *metre)$}i ], +``` + +### Anwendung + +**Manuell:** ```bash -cp change_m3_to_m_hoch_3.sql /tmp/ -chmod 644 /tmp/change_m3_to_m_hoch_3.sql -sudo -u postgres psql -d hemi -f /tmp/change_m3_to_m_hoch_3.sql +# 1. Backup +cp /var/www/html/kivitendo-erp/SL/Helper/UNECERecommendation20.pm \ + /var/www/html/kivitendo-erp/SL/Helper/UNECERecommendation20.pm.bak + +# 2. Datei bearbeiten +vi /var/www/html/kivitendo-erp/SL/Helper/UNECERecommendation20.pm + +# 3. Nach der LTR-Zeile einfügen: +# # cubic volumes +# [ 'MTQ', qr{^(?:m³|cbm|kubik *meter|kubik *metre|cubic *meter|cubic *metre)$}i ], ``` -## Was wird geändert? - -Das Skript führt folgende Schritte aus: -1. Entfernt temporär Foreign Key Constraints -2. Aktualisiert Einheit in folgenden Tabellen: - - `units` (Einheiten-Stammdaten) - - `parts` (Artikel) - - `invoice` (Rechnungspositionen) - - `orderitems` (Auftragspositionen) - - `delivery_order_items` (Lieferscheinpositionen) - - `units_language` (Einheiten-Übersetzungen) -3. Stellt Foreign Key Constraints wieder her -4. Zeigt Statistik der geänderten Datensätze - -## Sicherheit - -✅ **Transaction-basiert:** Bei Fehler wird automatisch zurückgerollt (ROLLBACK) -✅ **Alle referenzierten Tabellen werden aktualisiert** -⚠️ **Historische Daten werden ebenfalls geändert** (Foreign Keys erzwingen das) - -## Beispiel-Ausgabe -``` -Fertig! m3 -> m³ geändert - tabelle | anzahl --------------+-------- - Artikel: | 31 - Rechnungen: | 194 - Aufträge: | 162 +**Automatisch (Patch-Datei):** +```bash +patch -p1 < add_mtq_mapping.patch ``` -## Erstellt am -2026-01-31 +### Unterstützte Schreibweisen nach dem Fix +| Eingabe | UN/ECE Code | +|---------|-------------| +| `m³` | MTQ | +| `cbm` | MTQ | +| `kubik meter` | MTQ | +| `cubic meter` | MTQ | -## Version -1.0 +### Getestet auf +- Kivitendo 3.5.6 +- Server: vrlnx-03-hemi (116.203.121.112) +- Datum: 2026-03-01 + +--- + +## Server-Referenz + +| Server | IP | Datenbank | Kivitendo | +|--------|-----|-----------|-----------| +| vrlnx-03-hemi | 116.203.121.112 | hemi | 3.5.6 | + +--- + +## Changelog + +### 2026-03-01 +- **NEU:** MTQ Mapping für m³ hinzugefügt (Perl-Fix) +- Root-Cause-Analyse: `SL/Helper/UNECERecommendation20.pm` fehlte MTQ + +### 2026-01-31 +- **NEU:** SQL-Skript für m3 → m³ Migration + +--- + +## Hinweise + +⚠️ **Backup vor jeder Änderung erstellen!** + +⚠️ **Nach Kivitendo-Updates prüfen:** Diese Fixes könnten überschrieben werden. Nach einem Kivitendo-Update sollte geprüft werden, ob: +1. Das MTQ-Mapping in der neuen Version enthalten ist +2. Falls nicht: Patch erneut anwenden + +## Lizenz + +MIT diff --git a/add_mtq_mapping.patch b/add_mtq_mapping.patch new file mode 100644 index 0000000..cfa70bd --- /dev/null +++ b/add_mtq_mapping.patch @@ -0,0 +1,12 @@ +--- a/SL/Helper/UNECERecommendation20.pm ++++ b/SL/Helper/UNECERecommendation20.pm +@@ -36,6 +36,9 @@ my @mappings = ( + [ 'MLT', qr{^(?:ml|milli *liter|milli *litre)$}i ], + [ 'LTR', qr{^(?:l|liter|litre)$}i ], + ++ # cubic volumes ++ [ 'MTQ', qr{^(?:m³|cbm|kubik *meter|kubik *metre|cubic *meter|cubic *metre)$}i ], ++ + # miscellaneous + [ 'C62', qr{^(?:stck|stück|pieces?|pc|psch|pauschal)$}i ], + );