Docs: MTQ Mapping für m³ dokumentiert + Patch-Datei

- 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

@@ -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
-```bash
-sudo -u postgres pg_dumpall > /root/postgres_backup_$(date +%Y%m%d_%H%M%S).sql
-```
+### Problem
+Kivitendo erkennt beim ZUGFeRD-Export nur Unicode-Hochzahlen als valide Einheiten:
+- ✅ `m²` (Unicode) 
+- ❌ `m2` oder `MTK` (Text)
 
-### Skript ausführen
-```bash
-sudo -u postgres psql -d <datenbankname> -f change_m3_to_m_hoch_3.sql
-```
+### Lösung
+**`change_m3_to_m_hoch_3.sql`** - Ändert `m3` → `m³` in der Datenbank
 
-**Beispiel für Datenbank "hemi":**
-```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
-```
-
-## 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)
+### Betroffene Tabellen
+- `units` (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
+- `units_language` (Übersetzungen)
 
-## Sicherheit
+### Anwendung
+```bash
+# 1. Backup erstellen!
+sudo -u postgres pg_dumpall > /root/postgres_backup_$(date +%Y%m%d_%H%M%S).sql
 
-✅ **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
+# 2. Skript ausführen
+sudo -u postgres psql -d <datenbankname> -f change_m3_to_m_hoch_3.sql
 ```
 
-## Erstellt am
-2026-01-31
+---
 
-## Version
-1.0
+## 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
+# 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 ],
+```
+
+**Automatisch (Patch-Datei):**
+```bash
+patch -p1 < add_mtq_mapping.patch
+```
+
+### Unterstützte Schreibweisen nach dem Fix
+| Eingabe | UN/ECE Code |
+|---------|-------------|
+| `m³` | MTQ |
+| `cbm` | MTQ |
+| `kubik meter` | MTQ |
+| `cubic meter` | MTQ |
+
+### 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

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 ],
+ );