# Kivitendo ZUGFeRD Fixes

Patches und Skripte für Kivitendo zur Behebung von ZUGFeRD-Kompatibilitätsproblemen.

## Übersicht

| Fix | Beschreibung | Betrifft |
|-----|--------------|----------|
| [Einheiten-Migration](#einheiten-migration-sql) | m3 → m³ in Datenbank | SQL |
| [MTQ Mapping](#mtq-mapping-perl) | m³ → MTQ Code hinzufügen | Perl |

---

## Einheiten-Migration (SQL)

### 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

# 2. Skript ausführen
sudo -u postgres psql -d <datenbankname> -f change_m3_to_m_hoch_3.sql
```

---

## 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