epcqr/README.md

# EPC QR-Code Modul für Dolibarr

**Version:** 2.0
**Autor:** DATA IT-Solutions (Eduard Wisch)
**Kompatibilität:** Dolibarr 19.0+
**Lizenz:** GPL-3.0+

---

## Übersicht

Das **EPC QR-Code Modul** generiert automatisch **EPC/GiroCode QR-Codes** für SEPA-Überweisungen auf Dolibarr-Rechnungen. Kunden können den QR-Code mit ihrer Banking-App scannen und die Zahlung sofort ausführen - ohne manuelle Eingabe von IBAN, Betrag oder Verwendungszweck.

### Neu in Version 2.0

- **Admin-Center** mit allen Einstellungen an einem Ort
- **4 Modul-Stile:** Quadrat, Abgerundet, Punkte, Diamant
- **5 Rahmen-Stile:** Kein Rahmen, Einfach, Abgerundet, Doppelt, Gestrichelt
- **Transparenter Hintergrund** möglich
- **Logo-Einbettung** mit konfigurierbarer Größe (5-30%)
- **Individuelle Farben** für Vordergrund und Hintergrund
- **Cache-Verwaltung** direkt im Admin-Center
- **Extrafeld-Sichtbarkeit** konfigurierbar
- **Verbesserte ODT-Integration**

### Was sind EPC-QR-Codes?

EPC-QR-Codes (auch GiroCode genannt) enthalten alle relevanten Zahlungsinformationen:
- Empfänger (Kontoinhaber)
- IBAN
- BIC (optional)
- Betrag
- Verwendungszweck (Rechnungsnummer)

Diese QR-Codes sind mit allen europäischen Banking-Apps kompatibel.

---

## Installation

### Voraussetzungen

- Dolibarr 19.0 oder höher
- PHP 7.1 oder höher
- PHP GD-Extension (für Bildgenerierung)
- TCPDF-Bibliothek (in Dolibarr enthalten)

### Installationsschritte

1. **Modul-Ordner kopieren:**
   ```bash
   cp -r epcqr /path/to/dolibarr/htdocs/custom/
   ```

2. **Modul aktivieren:**
   - Einstellungen → Module/Anwendungen
   - Kategorie "Finanzen" auswählen
   - "EPC QR-Code" aktivieren

3. **Bankdaten konfigurieren:**
   - Einstellungen → Module → EPC QR-Code → Einstellungen
   - Bankverbindung eingeben oder Systembankkonto auswählen

---

## Konfiguration

### Admin-Center

Das Admin-Center erreichen Sie unter:
**Einstellungen → Module → EPC QR-Code → Einstellungen**

Es gibt drei Tabs:
- **Einstellungen** - Alle Konfigurationsoptionen
- **Debug** - QR-Code Testseite
- **Über** - Modul-Informationen

### Bankverbindung

| Einstellung | Beschreibung |
|-------------|--------------|
| **Datenquelle** | "Systembankkonto verwenden" oder "Manuelle Eingabe" |
| **Kontoinhaber** | Name des Kontoinhabers (bei manueller Eingabe) |
| **IBAN** | Internationale Bankkontonummer |
| **BIC** | Bank Identifier Code (optional) |

> **Tipp:** Bei "Systembankkonto verwenden" werden die Bankdaten automatisch aus dem in Dolibarr konfigurierten Bankkonto geladen.

### QR-Code Größe

| Einstellung | Beschreibung |
|-------------|--------------|
| **QR-Code Größe (Verhältnis)** | Größe in ODT-Dokumenten (0.01 - 2.0) |

**Empfohlene Werte:**
| Wert | Größe |
|------|-------|
| 0.03 - 0.05 | sehr klein |
| 0.1 | klein |
| 0.3 | mittel (Standard) |
| 0.5 | groß |

### Styling-Optionen

#### Farben

| Einstellung | Beschreibung |
|-------------|--------------|
| **Vordergrundfarbe** | Farbe der QR-Code-Module (Standard: #000000 schwarz) |
| **Hintergrundfarbe** | Hintergrundfarbe oder "Transparent" aktivieren |

> **Hinweis:** Bei transparentem Hintergrund sollte die Vordergrundfarbe ausreichend Kontrast zum Dokumenthintergrund haben.

#### Logo

| Einstellung | Beschreibung |
|-------------|--------------|
| **Logo (optional)** | Absoluter Pfad zum Logo-Bild (PNG, JPG, GIF) |
| **Logo-Größe** | 5% - 30% der QR-Code-Größe (Standard: 20%) |

**Beispiel-Pfade:**
```
/var/www/dolibarr/documents/mycompany/logos/logo.png
/srv/http/dolibarr/htdocs/custom/epcqr/img/mylogo.png
```

> **Wichtig:** Bei Verwendung eines Logos wird automatisch die höchste Fehlerkorrektur (H = 30%) verwendet, um die Scanbarkeit zu gewährleisten.

#### Modul-Stil

| Stil | Beschreibung |
|------|--------------|
| **Quadrat** | Standard QR-Code-Module (klassisch) |
| **Abgerundet** | Module mit abgerundeten Ecken |
| **Punkte** | Kreisförmige Module |
| **Diamant** | Rautenförmige Module |

#### Rahmen-Stil

| Stil | Beschreibung |
|------|--------------|
| **Kein Rahmen** | Standard - ohne Rahmen |
| **Einfach** | Schlichte Linie um den QR-Code |
| **Abgerundet** | Rahmen mit runden Ecken |
| **Doppelt** | Zwei parallele Linien |
| **Gestrichelt** | Unterbrochene Linie |

### Cache-Verwaltung

QR-Codes werden lokal gecached für optimale Performance. Nach Änderung der Styling-Einstellungen:

**Cache leeren** - Klicken Sie auf den Button, um alle gecachten QR-Codes zu löschen. Neue QR-Codes werden mit den aktuellen Einstellungen generiert.

### Extrafeld-Sichtbarkeit

Kontrollieren Sie, welche QR-Code-Felder im Rechnungsformular angezeigt werden:

| Einstellung | Beschreibung |
|-------------|--------------|
| **QR-Code (HTML) ausblenden** | Versteckt das Bild-Feld |
| **QR-Code URL ausblenden** | Versteckt den URL-Link |
| **QR-Code Pfad ausblenden** | Versteckt den lokalen Dateipfad |

---

## Verwendung

### Automatische Generierung

Der QR-Code wird **automatisch generiert**, wenn:
1. Eine neue Rechnung erstellt wird
2. Eine bestehende Rechnung validiert wird

Der Trigger läuft beim Event `BILL_VALIDATE`.

### Extrafelder

Das Modul erstellt drei Extrafelder auf Rechnungen:

| Feld | Typ | Inhalt |
|------|-----|--------|
| `qrcode` | HTML | `<img>`-Tag zur Anzeige im Formular |
| `qrcodepfad` | HTML | URL zum QR-Code-Bild (klickbar) |
| `qrcodepath` | varchar | Lokaler Dateipfad (für ODT-Integration) |

### ODT-Integration

Um den QR-Code in ODT-Dokumentvorlagen einzufügen:

1. **Platzhalter einfügen:**
   ```
   {qrcode}
   ```

2. **Der QR-Code wird automatisch** beim Generieren des Dokuments eingefügt.

3. **Größe anpassen:** Die Größe wird über die "QR-Code Größe (Verhältnis)" Einstellung im Admin-Center gesteuert.

> **Hinweis:** Der Platzhalter muss exakt `{qrcode}` lauten.

### Beispiel Template-Position

```
┌─────────────────────────────────┐
│ RECHNUNG RE2501-0001            │
│                                 │
│ Gesamtbetrag: 1.234,56 EUR      │
│                                 │
│         ┌──────────┐            │
│         │ {qrcode} │            │
│         └──────────┘            │
│                                 │
│ Bitte überweisen Sie den       │
│ Betrag unter Angabe der        │
│ Rechnungsnummer.                │
└─────────────────────────────────┘
```

---

## Technische Details

### EPC/GiroCode Format

Der generierte QR-Code enthält folgende Daten im EPC-Standard:

```
BCD                     # Service Tag
002                     # Version
1                       # Character set (UTF-8)
SCT                     # SEPA Credit Transfer
[BIC]                   # Bank Identifier Code
[Kontoinhaber]          # Empfänger Name
[IBAN]                  # Empfänger IBAN
EUR[Betrag]             # Währung und Betrag
                        # Purpose (leer)
[Rechnungsnummer]       # Verwendungszweck
                        # Info (leer)
```

### Dateispeicherung

QR-Codes werden gespeichert unter:
```
/documents/epcqr/qrcodes/epc_[hash].png
```

Der Hash basiert auf:
- Bankdaten (Kontoinhaber, IBAN, BIC)
- Rechnungsdaten (Betrag, Referenz)
- Styling-Einstellungen (Farben, Logo, Modul-Stil, Rahmen-Stil)

### Hooks

Das Modul verwendet folgende Dolibarr-Hooks:

| Hook | Funktion |
|------|----------|
| `invoicecard` | QR-Code bei Rechnungsvalidierung generieren |
| `odtgeneration` | QR-Code-Bild in ODT einfügen (beforeODTSave) |
| `pdfgeneration` | Substitutionsvariablen für PDF |

### Substitutionsvariablen

Für ODT/PDF-Dokumente stehen folgende Substitutionen zur Verfügung:

| Variable | Inhalt |
|----------|--------|
| `{qrcode}` | QR-Code als Bild |
| `{options_qrcodepath}` | Lokaler Dateipfad |

### Modul-Struktur

```
epcqr/
├── admin/
│   ├── setup.php          # Einstellungen
│   └── about.php          # Über-Seite
├── class/
│   └── actions_epcqr.class.php  # Hook-Aktionen
├── core/
│   ├── modules/
│   │   └── modEpcqr.class.php   # Modul-Deskriptor
│   ├── substitutions/
│   │   └── functions_epcqr.lib.php  # Substitutionen
│   └── triggers/
│       └── interface_99_modEpcqr_EpcqrTriggers.class.php
├── langs/
│   ├── de_DE/
│   │   └── epcqr.lang     # Deutsche Übersetzung
│   └── en_US/
│       └── epcqr.lang     # Englische Übersetzung
├── lib/
│   ├── epcqr.lib.php      # Bibliotheksfunktionen
│   └── qrcode.class.php   # QR-Code Generator
├── sql/
│   ├── llx_epcqr_extrafields.sql  # Extrafelder
│   └── dolibarr_allversions.sql   # Upgrade-Script
├── test_qrcode.php        # Debug-Seite
└── README.md              # Diese Dokumentation
```

---

## Fehlerbehebung

### QR-Code wird nicht generiert

1. **Bankdaten prüfen:** Sind Kontoinhaber und IBAN konfiguriert?
2. **Modul aktiv?** Ist das EPC QR-Code Modul aktiviert?
3. **Rechnung validiert?** QR-Codes werden erst bei Validierung generiert.
4. **Logs prüfen:** Einstellungen → Logs auf Fehlermeldungen prüfen.
   - Suche nach "EPCQR" in den Logs

### QR-Code nicht scannbar

1. **Größe erhöhen:** Mindestens 2x2 cm für zuverlässiges Scannen.
2. **Kontrast prüfen:** Dunkle Vordergrundfarbe auf hellem Hintergrund.
3. **Logo verkleinern:** Maximale Logo-Größe 30% (besser 20% oder weniger).
4. **Modul-Stil:** Bei Problemen "Quadrat" (Standard) verwenden.

### ODT: QR-Code erscheint nicht

1. **Platzhalter korrekt?** Muss exakt `{qrcode}` sein.
2. **Pfad existiert?** Prüfen ob die Datei unter `qrcodepath` existiert.
3. **Cache leeren:** Nach Änderungen den Cache leeren.
4. **Extrafeld vorhanden?** `qrcodepath` muss als Extrafeld existieren.

### Styling-Änderungen haben keine Wirkung

Nach Änderung der Styling-Einstellungen:
1. **Cache leeren** im Admin-Center klicken
2. Rechnung erneut generieren (auf Draft setzen → Validieren)
3. Oder neuen QR-Code durch neue Rechnung testen

### Extra-Felder fehlen

Falls die Extrafelder nicht automatisch erstellt wurden:
1. Modul **deaktivieren**
2. Modul wieder **aktivieren**
3. Prüfen unter: Einstellungen → Wörterbücher → Zusatzattribute → Rechnungen

---

## Changelog

### Version 2.0 (Januar 2025)

**Neue Funktionen:**
- Vollständiges Admin-Center mit allen Einstellungen
- Modul-Stile: Quadrat, Abgerundet, Punkte, Diamant
- Rahmen-Stile: Kein Rahmen, Einfach, Abgerundet, Doppelt, Gestrichelt
- Transparenter Hintergrund
- Logo-Einbettung mit konfigurierbarer Größe (5-30%)
- Cache-Verwaltung im Admin-Center
- Extrafeld-Sichtbarkeit konfigurierbar
- Verbesserte ODT-Integration mit beforeODTSave Hook
- Kleinere QR-Code-Größen möglich (ab 0.01)
- Systembankkonto-Unterstützung

**Verbesserungen:**
- Neues Icon (fa-qrcode)
- Deutsche und englische Übersetzungen vollständig
- Bessere Fehlerbehandlung und Logging
- Performance-Optimierungen durch intelligentes Caching
- SQL-Scripts für automatische Extrafeld-Erstellung

**Technische Änderungen:**
- Komplette Überarbeitung der QRCodeGenerator-Klasse
- Neue Methoden für Modul-Stile und Rahmen
- Hash-basiertes Caching mit Styling-Berücksichtigung
- Verbesserte Transparenz-Unterstützung

### Version 1.5 (Januar 2025)

- Lokales QR-Code-Caching
- Extrafeld `qrcodepath` für ODT-Integration
- Grundlegende Farbkonfiguration
- {qrcode} Keyword für ODT-Templates
- Hook-basierte ODT-Verarbeitung

### Version 1.0 (2025)

- Initiale Version
- Automatische EPC QR-Code-Generierung
- Extra-Felder für Rechnungen
- Externe QR-Service Integration

---

## API / Entwickler

### QR-Code manuell generieren

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

$qrGen = new QRCodeGenerator($db);
$filepath = $qrGen->generateEPCQRCode(
    'Max Mustermann',    // Kontoinhaber
    'DE89370400440532013000',  // IBAN
    'COBADEFFXXX',       // BIC
    1234.56,             // Betrag
    'RE2501-0001'        // Verwendungszweck
);
```

### Cache leeren

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

$qrGen = new QRCodeGenerator($db);
$deleted = $qrGen->clearCache();
echo "Gelöscht: $deleted QR-Codes";
```

### Styling programmatisch setzen

Die Styling-Optionen werden aus der Dolibarr-Konfiguration geladen:

```php
// In llx_const Tabelle:
// EPCQR_FG_COLOR = '#000000'
// EPCQR_BG_COLOR = '#FFFFFF' oder 'transparent'
// EPCQR_LOGO_PATH = '/path/to/logo.png'
// EPCQR_LOGO_SIZE = 20
// EPCQR_MODULE_STYLE = 'square' | 'rounded' | 'dots' | 'diamond'
// EPCQR_BORDER_STYLE = 'none' | 'simple' | 'rounded' | 'double' | 'dashed'
```

---

## Support

Bei Fragen oder Problemen:

- **E-Mail:** data@data-it-solution.de
- **Website:** https://data-it-solution.de

### Bei Problemen

1. **Log-Dateien prüfen:** `documents/dolibarr.log`
2. **Debug-Seite nutzen:** Admin-Center → Debug Tab
3. **EPCQR in Logs suchen:** Alle Meldungen beginnen mit "EPCQR:"

---

## Lizenz

**GNU General Public License v3.0 oder höher**

Copyright (C) 2025 Eduard Wisch / DATA IT-Solutions

Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GNU General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren; entweder Version 3 der Lizenz oder (nach Ihrer Wahl) jede spätere Version.

Dieses Programm wird in der Hoffnung verteilt, dass es nützlich sein wird, aber OHNE JEDE GEWÄHRLEISTUNG; sogar ohne die implizite Gewährleistung der MARKTGÄNGIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.

Die vollständige Lizenz finden Sie unter: https://www.gnu.org/licenses/gpl-3.0.html