epcqr/doc/BILDER_IN_ODT.md

# Bilder in ODT-Dokumenten mit EPCQR-Modul

## Übersicht

Das EPCQR-Modul bietet eine **wiederverwendbare Lösung** zum Einfügen von Bildern in ODT-Dokumentvorlagen. Die Implementierung ist generisch und kann für beliebige Bilder verwendet werden, nicht nur für QR-Codes.

## Funktionsweise

### 1. QR-Code Keyword: `{qrcode}`

Das neue Keyword `{qrcode}` kann in jedem ODT-Dokumenttemplate verwendet werden und wird automatisch durch ein QR-Code-Bild ersetzt.

**Beispiel in ODT-Template:**
```
Rechnung: {ref}
Betrag: {total_ttc}

Bitte überweisen Sie den Betrag mit folgendem QR-Code:
{qrcode}
```

### 2. Generische Bildintegration

Das System unterstützt auch **beliebige andere Bilder**:

- Erstellen Sie ein Extrafeld mit dem Suffix `_imagepath`
- Speichern Sie den Dateipfad zum Bild im Extrafeld
- Verwenden Sie das Keyword `{FELDNAME}` im ODT-Template

**Beispiel:**
1. Extrafeld: `logo_imagepath` (Typ: varchar)
2. Speichern: `/pfad/zum/logo.png` im Extrafeld
3. Im Template: `{logo}`

## Installation und Konfiguration

### Schritt 1: Modul aktualisieren

Das Modul muss deaktiviert und neu aktiviert werden, damit die neuen Funktionen verfügbar sind:

1. **Home → Setup → Modules/Applications**
2. **EPCQR-Modul deaktivieren**
3. **EPCQR-Modul aktivieren**

### Schritt 2: Extrafeld erstellen (automatisch)

Das SQL-Update-Script erstellt automatisch das Extrafeld `qrcodepath`:

```sql
-- Wird automatisch bei Modulaktivierung ausgeführt
INSERT INTO llx_extrafields (name, label, type, elementtype, ...)
VALUES ('qrcodepath', 'QR-Code Bildpfad (lokal)', 'varchar', 'facture', ...);
```

### Schritt 3: Konfiguration anpassen (optional)

Bankverbindung in [admin/setup.php](admin/setup.php) konfigurieren:

- **EPCQR_ACCOUNT_HOLDER**: Kontoinhaber Name
- **EPCQR_IBAN**: IBAN
- **EPCQR_BIC**: BIC

*Aktuell noch hardcoded im Trigger, wird in Version 1.6 konfigurierbar.*

## Verwendung in ODT-Templates

### QR-Code in Rechnung einfügen

1. **ODT-Template bearbeiten** (z.B. `invoice_template.odt`)
2. **Keyword einfügen**: `{qrcode}` an gewünschter Stelle
3. **Template speichern** in Dolibarr
4. **Rechnung validieren** → QR-Code wird automatisch generiert
5. **Dokument generieren** (ODT) → QR-Code wird eingefügt

### Eigene Bilder einfügen

**Beispiel: Firmenlogo**

1. **Extrafeld erstellen**:
   - Name: `company_logo_imagepath`
   - Typ: `varchar(255)`
   - Element: `facture`

2. **Bild speichern**:
   ```php
   $invoice->array_options['options_company_logo_imagepath'] = '/pfad/zum/logo.png';
   $invoice->insertExtraFields();
   ```

3. **Template verwenden**:
   ```
   {company_logo}
   ```

## Technische Details

### Architektur

```
┌─────────────────────────────────────┐
│  1. BILL_VALIDATE Trigger           │
│     - Rechnung validiert             │
│     - QR-Code generieren             │
│     - Pfad in Extrafeld speichern    │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  2. ODT-Generierung                  │
│     - Template laden                 │
│     - Felder ersetzen                │
│     - ODT-Datei erstellen            │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  3. afterODTCreation Hook            │
│     - ODT entpacken (ZIP)            │
│     - Bild in Pictures/ kopieren     │
│     - manifest.xml aktualisieren     │
│     - {qrcode} durch <draw:frame>    │
│       XML ersetzen                   │
│     - ODT neu packen                 │
└─────────────────────────────────────┘
```

### Wichtige Dateien

| Datei | Funktion |
|-------|----------|
| [lib/qrcode.class.php](../lib/qrcode.class.php) | QR-Code-Generator mit Caching |
| [lib/epcqr.lib.php](../lib/epcqr.lib.php) | Hilfsfunktionen für QR-Codes und Bilder |
| [core/substitutions/functions_epcqr.lib.php](../core/substitutions/functions_epcqr.lib.php) | Substitutionsfunktionen für ODT |
| [class/actions_epcqr.class.php](../class/actions_epcqr.class.php) | Hook-Klasse für ODT-Verarbeitung |
| [core/triggers/interface_99_modEpcqr_EpcqrTriggers.class.php](../core/triggers/interface_99_modEpcqr_EpcqrTriggers.class.php) | Trigger für BILL_VALIDATE |

### Extrafelder

| Feldname | Typ | Beschreibung |
|----------|-----|--------------|
| `qrcode` | HTML | QR-Code als `<img>`-Tag (Kompatibilität) |
| `qrcodepfad` | varchar | URL zum QR-Code über viewimage.php |
| `qrcodepath` | varchar | **NEU**: Lokaler Dateipfad für ODT-Integration |

### Bildverarbeitung

**ODT ist ein ZIP-Archiv:**

```
invoice.odt
├── mimetype (unkomprimiert!)
├── META-INF/
│   └── manifest.xml (Bild-Referenzen)
├── content.xml (Dokument-Inhalt)
├── styles.xml
└── Pictures/
    ├── qrcode.png
    └── logo.png
```

**Ablauf:**

1. **ODT entpacken**: `ZipArchive::extractTo()`
2. **Bild kopieren**: `copy($source, $tmpDir.'/Pictures/img.png')`
3. **Manifest aktualisieren**:
   ```xml
   <manifest:file-entry
       manifest:media-type="image/png"
       manifest:full-path="Pictures/img.png"/>
   ```
4. **Content.xml anpassen**:
   ```xml
   <draw:frame draw:name="QRCode"
               text:anchor-type="as-char"
               svg:width="2cm"
               svg:height="2cm">
     <draw:image xlink:href="Pictures/img.png"
                 xlink:type="simple"
                 xlink:show="embed"/>
   </draw:frame>
   ```
5. **ODT neu packen**: `ZipArchive::addFile()` mit `mimetype` unkomprimiert

## QR-Code-Generierung

### Aktueller Stand (Version 1.5)

QR-Codes werden **lokal generiert** und gecached:

```php
$qrGen = new QRCodeGenerator($db);
$qrCodePath = $qrGen->generateEPCQRCode(
    'Eduard Wisch',           // Kontoinhaber
    'DE70217625500013438147', // IBAN
    'GENODEF1HUM',           // BIC
    150.00,                  // Betrag
    'IN26-0001'              // Verwendungszweck
);
// Ergebnis: /srv/http/dolibarr/documents/epcqr/qrcodes/epc_abc123.png
```

**Caching:**
- QR-Codes werden im Verzeichnis `documents/epcqr/qrcodes/` gespeichert
- Dateiname basiert auf MD5-Hash der Parameter
- Wiederverwendung bei identischen Parametern

### Migration von externem Service

**Alt (bis Version 1.4):**
```php
$qrurl = "https://qr.data-it-solution.de/epc?...";
$invoice->array_options['options_qrcode'] = "<img src='".$qrurl."'>";
```

**Neu (ab Version 1.5):**
```php
$qrCodePath = $qrGen->generateEPCQRCode(...);
$invoice->array_options['options_qrcodepath'] = $qrCodePath;
$invoice->array_options['options_qrcode'] = "<img src='".DOL_URL_ROOT."/viewimage.php?...'>";
```

**Kompatibilität:**
- Bestehende Extrafelder bleiben erhalten
- Alte Rechnungen mit extern gehosteten QR-Codes funktionieren weiter
- Neue Rechnungen verwenden lokale QR-Codes

## Erweiterte Verwendung

### Eigene QR-Codes generieren

```php
require_once DOL_DOCUMENT_ROOT.'/custom/epcqr/lib/qrcode.class.php';

$qrGen = new QRCodeGenerator($db);

// Generischer QR-Code
$qrPath = $qrGen->generateQRCode('https://example.com', 'url');

// EPC-QR-Code
$qrPath = $qrGen->generateEPCQRCode(
    'Firma GmbH',
    'DE89370400440532013000',
    'COBADEFFXXX',
    99.99,
    'Rechnung 2026-001'
);
```

### Cache-Verwaltung

```php
// Alte QR-Codes löschen (älter als 30 Tage)
$qrGen = new QRCodeGenerator($db);
$deleted = $qrGen->cleanCache(30);
echo "Gelöscht: ".$deleted." QR-Codes";
```

### Bildgröße anpassen

Die Bildgröße wird automatisch berechnet und an die ODT-Vorgaben angepasst:

```php
// In functions_epcqr.lib.php, Zeile ~180
$widthCm = round(($imageWidth / 96) * 2.54, 2);  // Pixel → cm (96 DPI)
$heightCm = round(($imageHeight / 96) * 2.54, 2);

// Maximale Größe begrenzen
$maxWidth = 6;  // cm
$maxHeight = 6; // cm
```

**Anpassen:**
Bearbeiten Sie `epcqr_insertImagesIntoODT()` in [core/substitutions/functions_epcqr.lib.php](../core/substitutions/functions_epcqr.lib.php#L180)

## Fehlerbehebung

### Problem: QR-Code wird nicht angezeigt

**Ursache 1: Extrafeld fehlt**
```bash
# Prüfen ob Extrafeld existiert
mysql> SELECT name, label FROM llx_extrafields WHERE name = 'qrcodepath';
```

**Lösung:**
```bash
# SQL-Update manuell ausführen
mysql dolibarr < sql/update_1.5.0.sql
```

**Ursache 2: Verzeichnis nicht beschreibbar**
```bash
# Prüfen
ls -la /srv/http/dolibarr/documents/epcqr/

# Berechtigungen setzen
chmod 755 /srv/http/dolibarr/documents/epcqr/
chmod 755 /srv/http/dolibarr/documents/epcqr/qrcodes/
```

**Ursache 3: Hook nicht aktiviert**
```bash
# Prüfen
grep -r "hooks.*array" core/modules/modEpcqr.class.php

# Sollte enthalten:
'hooks' => array(
    'data' => array('pdfgeneration', 'odtgeneration', ...),
```

### Problem: Bild wird im ODT nicht korrekt eingebettet

**Diagnose:**
1. ODT als ZIP öffnen
2. Prüfen ob `Pictures/qrcode.png` existiert
3. Prüfen ob `META-INF/manifest.xml` Eintrag enthält

**Lösung:**
- `manifest.xml` muss Bild-Referenz enthalten
- `mimetype` muss unkomprimiert sein
- `content.xml` muss `<draw:frame>` Element enthalten

### Debug-Modus aktivieren

```php
// In lib/epcqr.lib.php oder functions_epcqr.lib.php
dol_syslog("EPCQR: Debug-Info", LOG_DEBUG);

// Dolibarr syslog Levels:
// LOG_ERR    - Fehler
// LOG_WARNING - Warnungen
// LOG_INFO   - Informationen
// LOG_DEBUG  - Debug-Informationen
```

**Logs ansehen:**
```bash
tail -f /srv/http/dolibarr/documents/dolibarr.log | grep EPCQR
```

## Roadmap

### Version 1.6 (geplant)
- [ ] Native PHP-QR-Code-Generierung (ohne externen Service)
- [ ] Konfigurierbare Bankverbindung in Admin-Panel
- [ ] Unterstützung für mehrere Bankkonten
- [ ] Bildgröße per Konfiguration anpassbar

### Version 1.7 (geplant)
- [ ] Unterstützung für DOCX-Dokumente
- [ ] Batch-Verarbeitung für mehrere Rechnungen
- [ ] QR-Code Vorschau im Rechnungsformular

## Support und Beiträge

**Autor:** Eduard Wisch (data@data-it-solution.de)
**Lizenz:** GPL v3
**GitHub:** (falls vorhanden)

**Bei Problemen:**
1. Prüfen Sie die Logs: `documents/dolibarr.log`
2. Aktivieren Sie Debug-Modus
3. Erstellen Sie ein Issue mit Logs und Screenshots