1073 lines
22 KiB
Markdown
1073 lines
22 KiB
Markdown
# Firefly Import Preprocessor - Dokumentation
|
|
|
|
**Version:** 1.0.0
|
|
**Datum:** 02. May 2026
|
|
**Status:** Production Ready
|
|
|
|
---
|
|
|
|
## 📋 Inhaltsverzeichnis
|
|
|
|
1. [Überblick](#überblick)
|
|
2. [Installation & Setup](#installation--setup)
|
|
3. [Schnellstart](#schnellstart)
|
|
4. [Konfiguration](#konfiguration)
|
|
5. [Transformationstypen](#transformationstypen)
|
|
6. [CLI-Referenz](#cli-referenz)
|
|
7. [Debug-Modus](#debug-modus)
|
|
8. [Firefly III Integration](#firefly-iii-integration)
|
|
9. [Architektur](#architektur)
|
|
10. [Fehlerbehandlung](#fehlerbehandlung)
|
|
|
|
---
|
|
|
|
## Überblick
|
|
|
|
Der **Firefly Import Preprocessor** ist ein produktionsreifer PHP-Preprocessor für Banken-CSV-Exportdateien. Er transformiert Bankdaten in ein standardisiertes Format und kann sie optional in Firefly III importieren.
|
|
|
|
### Kernfeatures
|
|
|
|
✅ **Vollständige CSV-Transformation** mit komplexen Pipelines
|
|
✅ **Metadaten-Extraktion** mit Regex (IBAN, Währung, Kontoname)
|
|
✅ **11 Transformationstypen** für flexible Datenverarbeitung
|
|
✅ **Firefly III Integration** mit Docker-Support
|
|
✅ **Debug-Modus** für Transparenz bei Verarbeitung
|
|
✅ **Production Ready** mit vollständiger Fehlerbehandlung
|
|
✅ **Zero Dependencies** für Core-Funktionalität
|
|
|
|
### Workflow
|
|
|
|
```
|
|
Input CSV
|
|
↓
|
|
Metadaten extrahieren (Regex)
|
|
↓
|
|
Datenzeilen transformieren (Pipeline)
|
|
↓
|
|
Output CSV schreiben
|
|
↓
|
|
[Optional] In Firefly III importieren
|
|
```
|
|
|
|
---
|
|
|
|
## Installation & Setup
|
|
|
|
### Voraussetzungen
|
|
|
|
- PHP 8.1+
|
|
- Composer (empfohlen)
|
|
- [Optional] Docker für Firefly III Integration
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# 1. Repository clonen/kopieren
|
|
cd ff-imp-preprocessor
|
|
|
|
# 2. Abhängigkeiten installieren (optional)
|
|
composer install
|
|
|
|
# 3. Konfiguration erstellen
|
|
cp config/config.example.json config/config.json
|
|
# Bearbeite config/config.json mit deinen Einstellungen
|
|
|
|
# 4. Directories erstellen
|
|
mkdir -p config/import/{source,output,archive,error}
|
|
chmod 755 config/import/{source,output,archive,error}
|
|
|
|
# 5. Test durchführen
|
|
php bin/transformer.php validate config/config.json input.csv
|
|
```
|
|
|
|
---
|
|
|
|
## Schnellstart
|
|
|
|
### 1. Konfiguration anpassen
|
|
|
|
Bearbeite `config/config.json` und stelle sicher, dass die Extraction-Rules zu deinem CSV-Format passen:
|
|
|
|
```json
|
|
{
|
|
"metadata": {
|
|
"extractionRules": [
|
|
{
|
|
"name": "account_iban",
|
|
"lineNumber": 2,
|
|
"regex": "IBAN:\\s*([A-Z0-9 ]+)",
|
|
"captureGroup": 1
|
|
}
|
|
]
|
|
},
|
|
"csvStructure": {
|
|
"headerLine": 5,
|
|
"delimiter": ";",
|
|
"encoding": "UTF-8"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. CSV validieren
|
|
|
|
```bash
|
|
php bin/transformer.php validate config/config.json input.csv
|
|
```
|
|
|
|
Output:
|
|
```
|
|
✓ CSV ist valid
|
|
IBAN: CH9300777222666888999
|
|
Währung: CHF
|
|
Zeilen: 150
|
|
```
|
|
|
|
### 3. Transformation durchführen
|
|
|
|
```bash
|
|
php bin/transformer.php process config/config.json input.csv
|
|
|
|
# Mit Debug-Modus für Fehlersuche
|
|
php bin/transformer.php process config/config.json input.csv --debug
|
|
```
|
|
|
|
### 4. Output prüfen
|
|
|
|
```bash
|
|
# Transformierte Datei
|
|
cat config/import/output/transformed.csv
|
|
|
|
# Oder mit Debug-Ausgabe
|
|
php bin/transformer.php test config/config.json input.csv --debug
|
|
# Zeigt max. 10 transformierte Zeilen und Debug-Logs
|
|
```
|
|
|
|
---
|
|
|
|
## Konfiguration
|
|
|
|
### config.json Struktur
|
|
|
|
#### `metadata` - Metadaten-Extraktion
|
|
|
|
```json
|
|
{
|
|
"metadata": {
|
|
"extractionRules": [
|
|
{
|
|
"name": "account_iban",
|
|
"lineNumber": 2,
|
|
"regex": "IBAN:\\s*([A-Z0-9 ]+)",
|
|
"captureGroup": 1
|
|
},
|
|
{
|
|
"name": "currency_code",
|
|
"lineNumber": 3,
|
|
"regex": "Währung:\\s*([A-Z]{3})",
|
|
"captureGroup": 1
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
| Feld | Typ | Beschreibung |
|
|
|------|-----|-------------|
|
|
| `name` | string | Name der Metadaten-Variable (verwendet in constantvalue) |
|
|
| `lineNumber` | int | Zeilennummer in CSV (1-basiert, menschenlesbar) |
|
|
| `regex` | string | Regex-Pattern zur Extraktion (ohne Delimiter) |
|
|
| `captureGroup` | int | Nummer der Klammer-Gruppe (0=komplett, 1=erste Klammer, etc.) |
|
|
|
|
**Beispiel Regex:**
|
|
- Pattern: `IBAN:\s*([A-Z0-9 ]+)`
|
|
- Input: `IBAN: CH93 0077 2020 6262 5252 7`
|
|
- Capture Group 1: `CH93 0077 2020 6262 5252 7`
|
|
|
|
#### `csvStructure` - CSV-Format
|
|
|
|
```json
|
|
{
|
|
"csvStructure": {
|
|
"headerLine": 5,
|
|
"delimiter": ";",
|
|
"encoding": "UTF-8",
|
|
"hasBom": false
|
|
}
|
|
}
|
|
```
|
|
|
|
| Feld | Typ | Default | Beschreibung |
|
|
|------|-----|---------|-------------|
|
|
| `headerLine` | int | 5 | Zeilennummer der Header (1-basiert) |
|
|
| `delimiter` | string | `;` | CSV-Delimiter |
|
|
| `encoding` | string | `UTF-8` | Zeichenkodierung (UTF-8, ISO-8859-1, CP1252) |
|
|
| `hasBom` | bool | false | Hat die Datei BOM (Byte Order Mark)? |
|
|
|
|
#### `columnTransformations` - Spalten-Transformationen
|
|
|
|
```json
|
|
{
|
|
"columnTransformations": [
|
|
{
|
|
"sourceColumn": "Buchungsdatum",
|
|
"transformations": [
|
|
{
|
|
"type": "dateformat",
|
|
"fromFormat": "d.m.Y",
|
|
"toFormat": "Y-m-d"
|
|
}
|
|
],
|
|
"outputColumn": "date",
|
|
"outputAction": "overwrite"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**outputAction:**
|
|
- `overwrite` - Überschreibe sourceColumn
|
|
- `create` - Erstelle neue Spalte (für Regex-Extract, Split, etc.)
|
|
|
|
#### `directories` - Dateisystem
|
|
|
|
```json
|
|
{
|
|
"directories": {
|
|
"source": "/opt/ff-imp-preprocessor/import/source",
|
|
"output": "/opt/ff-imp-preprocessor/import/output",
|
|
"archive": "/opt/ff-imp-preprocessor/import/archive",
|
|
"error": "/opt/ff-imp-preprocessor/import/error"
|
|
}
|
|
}
|
|
```
|
|
|
|
| Feld | Beschreibung |
|
|
|------|-------------|
|
|
| `source` | Eingabe-Verzeichnis |
|
|
| `output` | Ausgabe-Verzeichnis |
|
|
| `archive` | Archiv für verarbeitete Dateien |
|
|
| `error` | Error-Verzeichnis für ungültige Dateien |
|
|
|
|
#### `fireflyImport` - Firefly III Integration
|
|
|
|
```json
|
|
{
|
|
"fireflyImport": {
|
|
"jsonConfig": "/opt/firefly/import-config.json",
|
|
"importerCommand": "docker exec -it firefly-importer php artisan importer:import",
|
|
"autoImport": false,
|
|
"deleteAfterImport": false,
|
|
"timeout": 300,
|
|
"environment": {
|
|
"FIREFLY_III_URL": "https://your-firefly.com",
|
|
"FIREFLY_III_ACCESS_TOKEN": "your-token-here"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Transformationstypen
|
|
|
|
Es gibt **13 unterstützte Transformationstypen**, die als Pipeline kombiniert werden können:
|
|
|
|
### 1. **trim** - Leerzeichen entfernen
|
|
|
|
Entfernt Leerzeichen am Anfang und Ende.
|
|
|
|
```json
|
|
{
|
|
"type": "trim"
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- Input: ` Coop Pronto `
|
|
- Output: `Coop Pronto`
|
|
|
|
---
|
|
|
|
### 2. **lowercase** - Zu Kleinbuchstaben
|
|
|
|
Wandelt in Kleinbuchstaben um (UTF-8 safe).
|
|
|
|
```json
|
|
{
|
|
"type": "lowercase"
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- Input: `COOP PRONTO CHUR`
|
|
- Output: `coop pronto chur`
|
|
|
|
---
|
|
|
|
### 3. **uppercase** - Zu Grossbuchstaben
|
|
|
|
Wandelt in Grossbuchstaben um (UTF-8 safe).
|
|
|
|
```json
|
|
{
|
|
"type": "uppercase"
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- Input: `Coop Pronto Chur`
|
|
- Output: `COOP PRONTO CHUR`
|
|
|
|
---
|
|
|
|
### 4. **ucwordsfirst** - Grossschreibung nach Trennzeichen
|
|
|
|
Grossschreibt ersten Buchstaben nach Worttrennzeichen.
|
|
|
|
```json
|
|
{
|
|
"type": "ucwordsfirst"
|
|
}
|
|
```
|
|
|
|
**Beispiele:**
|
|
- `COOP PRONTO CHUR` → `Coop Pronto Chur`
|
|
- `migros-rail city` → `Migros-Rail City`
|
|
- `O'NEILL STORE` → `O'Neill Store`
|
|
- `SAINT-JEAN-DE-MAURIENNE` → `Saint-Jean-De-Maurienne`
|
|
|
|
Trennzeichen: Leerzeichen, Bindestrich, Apostroph, Slash, Punkt, Komma, Semikolon, Doppelpunkt, Klammern.
|
|
|
|
---
|
|
|
|
### 5. **replace** - String-Replacement
|
|
|
|
Ersetzt Substring durch anderen String (case-sensitive).
|
|
|
|
```json
|
|
{
|
|
"type": "replace",
|
|
"search": " ",
|
|
"replace": " "
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- Input: `Coop Pronto` (2 Leerzeichen)
|
|
- Output: `Coop Pronto` (1 Leerzeichen)
|
|
|
|
---
|
|
|
|
### 6. **split** - Spalte teilen
|
|
|
|
Teilt einen Wert bei Delimiter und behält einen definierten Teil.
|
|
|
|
```json
|
|
{
|
|
"type": "split",
|
|
"delimiter": ";",
|
|
"part": 0
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- Input: `Coop Pronto Chur;7007 Chur`
|
|
- Config: `delimiter=";"`, `part=0`
|
|
- Output: `Coop Pronto Chur`
|
|
|
|
---
|
|
|
|
### 7. **regex** - Regex-Ersetzung
|
|
|
|
Ersetzt Teile des Strings per regulärem Ausdruck. Nutzt PHP `preg_replace`.
|
|
|
|
```json
|
|
{
|
|
"type": "regex",
|
|
"pattern": "^(.*?);.*$",
|
|
"replace": "$1"
|
|
}
|
|
```
|
|
|
|
**Beispiel — mit Match:**
|
|
- Input: `Meier, Anna; Zahlung UBS TWINT`
|
|
- Pattern: `^(.*?);.*$`, Replace: `$1`
|
|
- Output: `Meier, Anna`
|
|
|
|
**Beispiel — kein Match (pass-through):**
|
|
- Input: `Coop Pronto Chur` (kein Semikolon)
|
|
- Output: `Coop Pronto Chur` ← Wert bleibt **unverändert**
|
|
|
|
**Beispiel — Pattern ohne Anchors (ersetzt nur den gematchten Teil):**
|
|
- Input: `Zahlung UBS TWINT; Referenz 12345`
|
|
- Pattern: `UBS TWINT`, Replace: `TWINT`
|
|
- Output: `Zahlung TWINT; Referenz 12345`
|
|
|
|
**Hinweise:**
|
|
- **Kein Match → Originalwert wird unverändert weitergegeben** (pipeline-sicher)
|
|
- Capture Groups als `$1`, `$2`, … im `replace` referenzieren
|
|
- Pattern ohne `^`/`$`-Anchors ersetzt nur den gematchten Teilstring, nicht den ganzen Wert
|
|
|
|
---
|
|
|
|
### 8. **regexextract** - Regex-Extraktion
|
|
|
|
Extrahiert eine Capture Group per regulärem Ausdruck und gibt **nur diese** zurück. Nutzt PHP `preg_match`.
|
|
|
|
```json
|
|
{
|
|
"sourceColumn": "Mitteilungen",
|
|
"transformations": [
|
|
{
|
|
"type": "regexextract",
|
|
"pattern": "(\\d{4,} [^;]+)"
|
|
}
|
|
],
|
|
"outputColumn": "location",
|
|
"outputAction": "create"
|
|
}
|
|
```
|
|
|
|
**Beispiel — mit Match:**
|
|
- Input: `Coop Pronto Chur, 7007 Chur`
|
|
- Pattern: `(\d{4,} [^;]+)`
|
|
- Output: `7007 Chur` ← nur Capture Group 1
|
|
|
|
**Beispiel — kein Match:**
|
|
- Input: `Dauerauftrag Miete`
|
|
- Output: `` (leerer String)
|
|
|
|
**Hinweise:**
|
|
- **Kein Match → leerer String** (vorherige Pipeline-Schritte gehen verloren)
|
|
- Nutzt Capture Group 1 wenn vorhanden, sonst komplettes Match
|
|
- **⚠ Nicht pipeline-sicher:** Nur als einzigen oder letzten Schritt verwenden. Wenn bei Kein-Match der bisherige Wert erhalten bleiben soll, `regex` verwenden.
|
|
|
|
---
|
|
|
|
### 9. **dateformat** - Datum-Umformat
|
|
|
|
Konvertiert zwischen Datum-Formaten.
|
|
|
|
```json
|
|
{
|
|
"type": "dateformat",
|
|
"fromFormat": "d.m.Y",
|
|
"toFormat": "Y-m-d"
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- Input: `10.12.2025`
|
|
- Output: `2025-12-10`
|
|
|
|
**Supported Formate:** Alle PHP DateTime-Formate (d, m, Y, H, i, s, etc.)
|
|
|
|
---
|
|
|
|
### 10. **truncate** - String kürzen
|
|
|
|
Kürzt String auf maximale Länge.
|
|
|
|
```json
|
|
{
|
|
"type": "truncate",
|
|
"maxLength": 100
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- Input: `Dieser sehr lange Text...` (150 Zeichen)
|
|
- Output: `Dieser sehr lange Text...` (100 Zeichen)
|
|
|
|
---
|
|
|
|
### 11. **constantvalue** - Konstanten-Wert aus Metadaten
|
|
|
|
Nutzt extrahierte Metadaten als konstanten Wert.
|
|
|
|
```json
|
|
{
|
|
"sourceColumn": "_constant_",
|
|
"transformations": [
|
|
{
|
|
"type": "constantvalue",
|
|
"metadataKey": "account_iban"
|
|
}
|
|
],
|
|
"outputColumn": "account_iban",
|
|
"outputAction": "create"
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- metadataKey: `account_iban` (aus Extraktion)
|
|
- Wert: `CH9300777222666888999`
|
|
- Jede Zeile erhält diesen Wert in neuer Spalte
|
|
|
|
---
|
|
|
|
### 12. **map** - Spalte kopieren (Standard)
|
|
|
|
Kopiert oder benannt eine Spalte um.
|
|
|
|
```json
|
|
{
|
|
"sourceColumn": "Buchungstext",
|
|
"transformations": [
|
|
{
|
|
"type": "map"
|
|
}
|
|
],
|
|
"outputColumn": "description",
|
|
"outputAction": "overwrite"
|
|
}
|
|
```
|
|
|
|
**Beispiel:**
|
|
- Input Spalte: `Buchungstext`
|
|
- Output Spalte: `description` mit gleichem Inhalt
|
|
|
|
---
|
|
|
|
### 13. **pipeline** - Verschachtelte Pipeline
|
|
|
|
Führt eine Unter-Pipeline innerhalb eines Transformationsschritts aus. Ermöglicht das Gruppieren von Schritten als Einheit.
|
|
|
|
```json
|
|
{
|
|
"type": "pipeline",
|
|
"steps": [
|
|
{ "type": "trim" },
|
|
{ "type": "lowercase" },
|
|
{ "type": "ucwordsfirst" }
|
|
]
|
|
}
|
|
```
|
|
|
|
**Hinweis:** In der Praxis werden mehrere Schritte direkt als `transformations`-Array aufgelistet. `pipeline` als Typ ist nützlich wenn innerhalb einer `transformations`-Liste eine Gruppe von Schritten bedingt oder als Einheit behandelt werden soll.
|
|
|
|
---
|
|
|
|
### Pipeline-Beispiel
|
|
|
|
Mehrere Transformationen hintereinander:
|
|
|
|
```json
|
|
{
|
|
"sourceColumn": "Buchungstext",
|
|
"transformations": [
|
|
{ "type": "trim" },
|
|
{ "type": "replace", "search": " ", "replace": " " },
|
|
{ "type": "lowercase" },
|
|
{ "type": "ucwordsfirst" }
|
|
],
|
|
"outputColumn": "description",
|
|
"outputAction": "overwrite"
|
|
}
|
|
```
|
|
|
|
**Verarbeitung:**
|
|
1. `" COOP PRONTO "` → trim → `"COOP PRONTO"`
|
|
2. `"COOP PRONTO"` → replace → `"COOP PRONTO"`
|
|
3. `"COOP PRONTO"` → lowercase → `"coop pronto"`
|
|
4. `"coop pronto"` → ucwordsfirst → `"Coop Pronto"`
|
|
|
|
---
|
|
|
|
## CLI-Referenz
|
|
|
|
Der Transformer wird über `bin/transformer.php` aufgerufen:
|
|
|
|
```bash
|
|
php bin/transformer.php <command> <config> <input> [options]
|
|
```
|
|
|
|
### Kommandos
|
|
|
|
#### `process` - Führe Transformation aus
|
|
|
|
```bash
|
|
php bin/transformer.php process config/config.json input.csv [--debug]
|
|
```
|
|
|
|
- Transformiert CSV-Datei komplett
|
|
- Schreibt in `directories.output` (aus config)
|
|
- Optional: `--debug` für Debug-Logs
|
|
|
|
**Output:**
|
|
```
|
|
✓ Transformation erfolgreich
|
|
Input: input.csv
|
|
Output: config/import/output/transformed.csv
|
|
Zeilen: 245
|
|
Sample:
|
|
- [Datum: 2025-01-10, Beschreibung: ...]
|
|
```
|
|
|
|
---
|
|
|
|
#### `validate` - Validiere CSV
|
|
|
|
```bash
|
|
php bin/transformer.php validate config/config.json input.csv
|
|
```
|
|
|
|
- Prüft CSV-Format
|
|
- Extrahiert Metadaten
|
|
- Validiert erforderliche Felder
|
|
|
|
**Output:**
|
|
```
|
|
✓ CSV ist valid
|
|
Zeilen: 245
|
|
IBAN: CH9300777222666888999
|
|
Währung: CHF
|
|
```
|
|
|
|
---
|
|
|
|
#### `test` - Test-Run mit Beispieldaten
|
|
|
|
```bash
|
|
php bin/transformer.php test config/config.json input.csv [--debug]
|
|
```
|
|
|
|
- Transformiert maximal 10 Zeilen
|
|
- Zeigt Metadaten und Beispiel-Output
|
|
- Schnell zur Prüfung von Konfiguration
|
|
|
|
**Output:**
|
|
```
|
|
✓ Test erfolgreich
|
|
Max 10 Zeilen verarbeitet: 10
|
|
Metadaten:
|
|
- IBAN: CH93...
|
|
- Währung: CHF
|
|
Beispiel (Zeile 1):
|
|
- date: 2025-01-10
|
|
- description: coop pronto chur
|
|
- amount: 25.50
|
|
```
|
|
|
|
---
|
|
|
|
#### `help` - Zeige Hilfe
|
|
|
|
```bash
|
|
php bin/transformer.php help
|
|
```
|
|
|
|
---
|
|
|
|
### Optionen
|
|
|
|
| Option | Beschreibung | Beispiel |
|
|
|--------|-------------|---------|
|
|
| `--debug` | Aktiviere Debug-Modus | `process config.json input.csv --debug` |
|
|
| `--test` | Führe nur Test mit 10 Zeilen aus | `process config.json input.csv --test` |
|
|
|
|
---
|
|
|
|
## Debug-Modus
|
|
|
|
Der Debug-Modus bietet maximale Transparenz über die Verarbeitung.
|
|
|
|
### Aktivierung
|
|
|
|
```bash
|
|
php bin/transformer.php process config/config.json input.csv --debug
|
|
```
|
|
|
|
### Ausgegabene Informationen
|
|
|
|
Der Debug-Modus protokolliert:
|
|
|
|
**1. Transformer Level**
|
|
- Transformation gestartet (Input-Datei, maxRows)
|
|
- Transformation abgeschlossen
|
|
- Fehler
|
|
|
|
**2. CSV Reader Level**
|
|
- Metadaten-Zeilen gelesen (Anzahl)
|
|
- Datenzeilen gelesen (Anzahl)
|
|
|
|
**3. Metadata Extraction Level**
|
|
- Extraktion-Regel angewendet
|
|
- IBAN extrahiert
|
|
- Währung extrahiert
|
|
- Fehlerhafte Regex
|
|
- Fehlende Zeilen
|
|
|
|
**4. Transformation Level**
|
|
- Split-Transformation angewendet
|
|
- RegexExtract-Transformation angewendet
|
|
- Fehlerhafte Transformationen
|
|
|
|
**5. CSV Writer Level**
|
|
- Transformierte Daten geschrieben
|
|
- Output-Datei-Pfad
|
|
|
|
### JSON-Output mit Debug-Logs
|
|
|
|
Mit `--debug` wird das Ergebnis erweitert:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"inputFile": "input.csv",
|
|
"outputFile": "output/transformed.csv",
|
|
"rowsProcessed": 245,
|
|
"metadata": { "account_iban": "CH93...", "currency_code": "CHF" },
|
|
"debug_logs": [
|
|
{
|
|
"timestamp": 1702200120.5432,
|
|
"category": "transformer",
|
|
"message": "Transformation started",
|
|
"data": { "inputFile": "input.csv", "maxRows": 0 }
|
|
},
|
|
{
|
|
"timestamp": 1702200120.5445,
|
|
"category": "metadata",
|
|
"message": "Extraction rule applied",
|
|
"data": { "rule_name": "account_iban", "value": "CH93..." }
|
|
}
|
|
// ... weitere Logs
|
|
]
|
|
}
|
|
```
|
|
|
|
### Debug-Log-Kategorien
|
|
|
|
| Kategorie | Beispiel | Wann |
|
|
|-----------|---------|------|
|
|
| `transformer` | Transformation gestartet | Anfang/Ende Transformation |
|
|
| `csv_reader` | Zeilen gelesen | Beim CSV lesen |
|
|
| `metadata` | IBAN extrahiert | Bei Metadaten-Extraktion |
|
|
| `metadata_warning` | Regex matched nicht | Bei Problemen |
|
|
| `transformation` | Split angewendet | Bei jeder Transformation |
|
|
| `csv_writer` | Daten geschrieben | Beim CSV schreiben |
|
|
|
|
---
|
|
|
|
## Firefly III Integration
|
|
|
|
Der Transformer kann transformierte Daten automatisch in Firefly III importieren.
|
|
|
|
### Setup
|
|
|
|
1. **Firefly III laufen lassen**
|
|
|
|
```bash
|
|
docker-compose up -d firefly-iii
|
|
docker-compose up -d firefly-importer
|
|
```
|
|
|
|
2. **Konfiguration anpassen**
|
|
|
|
```json
|
|
{
|
|
"fireflyImport": {
|
|
"autoImport": true,
|
|
"environment": {
|
|
"FIREFLY_III_URL": "https://your-firefly.local",
|
|
"FIREFLY_III_ACCESS_TOKEN": "your-personal-access-token"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
3. **Import-Konfiguration erstellen**
|
|
|
|
`/opt/firefly/import-config.json`:
|
|
```json
|
|
{
|
|
"accounts": [
|
|
{
|
|
"name": "UBS Checking",
|
|
"iban": "CH9300777222666888999",
|
|
"account_type": "asset"
|
|
}
|
|
],
|
|
"column_mapping": {
|
|
"date": "date",
|
|
"amount": "amount",
|
|
"description": "description"
|
|
}
|
|
}
|
|
```
|
|
|
|
4. **Auto-Import aktivieren**
|
|
|
|
```bash
|
|
php bin/transformer.php process config/config.json input.csv
|
|
# Wenn autoImport=true, wird die transformierte Datei automatisch importiert
|
|
```
|
|
|
|
### Manueller Import
|
|
|
|
```bash
|
|
docker exec -it firefly-importer php artisan importer:import
|
|
```
|
|
|
|
---
|
|
|
|
## Architektur
|
|
|
|
### Komponenten
|
|
|
|
```
|
|
bin/transformer.php (CLI Entry Point)
|
|
↓
|
|
TransformerEngine (Orchestrierung)
|
|
├─ ConfigurationLoader (Config laden/validieren)
|
|
├─ CsvReader (CSV einlesen)
|
|
├─ MetadataExtractor (Metadaten mit Regex)
|
|
├─ ColumnTransformer (Transformationen anwenden)
|
|
├─ CsvWriter (CSV schreiben)
|
|
├─ FireflyImporter (Firefly III Integration)
|
|
└─ DebugLogger (Debug-Protokolle)
|
|
```
|
|
|
|
### Datenfluss
|
|
|
|
```
|
|
Input CSV
|
|
↓
|
|
CsvReader::readMetadataLines() → Array von Zeilen
|
|
↓
|
|
MetadataExtractor::extract() → {iban: "...", currency: "..."}
|
|
↓
|
|
CsvReader::readCsvData() → Array von Zeilen
|
|
↓
|
|
ColumnTransformer::transformRow() → Transformierte Zeile (Pipeline)
|
|
↓
|
|
CsvWriter::write() → Output CSV
|
|
```
|
|
|
|
### Klassen
|
|
|
|
| Klasse | Verantwortung |
|
|
|--------|---------------|
|
|
| `TransformerEngine` | Orchestriert gesamten Workflow |
|
|
| `ConfigurationLoader` | Lädt JSON/YAML Konfiguration |
|
|
| `CsvReader` | Liest CSV mit Metadaten |
|
|
| `MetadataExtractor` | Extrahiert mit Regex |
|
|
| `ColumnTransformer` | Transformiert Spalten (Pipeline) |
|
|
| `CsvWriter` | Schreibt CSV |
|
|
| `FireflyImporter` | Importiert in Firefly III |
|
|
| `DebugLogger` | Statischer Logger für Debug |
|
|
|
|
---
|
|
|
|
## Fehlerbehandlung
|
|
|
|
### Häufige Fehler
|
|
|
|
#### 1. "Input-Datei nicht gefunden"
|
|
|
|
```bash
|
|
Error: Input-Datei nicht gefunden: input.csv
|
|
```
|
|
|
|
**Ursache:** Dateipfad falsch oder Datei nicht vorhanden
|
|
|
|
**Lösung:**
|
|
```bash
|
|
# Prüfe Dateipfad
|
|
ls -la input.csv
|
|
|
|
# Nutze absoluten Pfad wenn relativ nicht funktioniert
|
|
php bin/transformer.php process config.json /absolute/path/input.csv
|
|
```
|
|
|
|
---
|
|
|
|
#### 2. "Fehlende Metadaten: account_iban"
|
|
|
|
```bash
|
|
Error: Fehlende Metadaten: account_iban
|
|
```
|
|
|
|
**Ursache:** IBAN konnte nicht extrahiert werden (Regex oder Zeile falsch)
|
|
|
|
**Lösung:**
|
|
```bash
|
|
# Debugging mit --debug
|
|
php bin/transformer.php validate config.json input.csv
|
|
|
|
# Prüfe erste 5 Zeilen des CSV
|
|
head -5 input.csv
|
|
|
|
# Überprüfe lineNumber und regex in config.json
|
|
# lineNumber sollte auf Zeile mit IBAN zeigen
|
|
```
|
|
|
|
---
|
|
|
|
#### 3. "Ungültiges JSON"
|
|
|
|
```bash
|
|
Error: Ungültiges JSON: Syntax error, malformed JSON
|
|
```
|
|
|
|
**Ursache:** JSON-Syntax-Fehler in config.json
|
|
|
|
**Lösung:**
|
|
```bash
|
|
# Validiere JSON
|
|
php -r "json_decode(file_get_contents('config/config.json'), true) or die('JSON invalid');"
|
|
|
|
# Oder nutze online JSON validator
|
|
# https://jsonlint.com/
|
|
```
|
|
|
|
---
|
|
|
|
#### 4. "CSV-Struktur-Fehler"
|
|
|
|
```bash
|
|
Error: 'csvStructure.headerLine' erforderlich
|
|
```
|
|
|
|
**Ursache:** Erforderliche Konfigurationsfelder fehlen
|
|
|
|
**Lösung:**
|
|
```bash
|
|
# Vergleiche mit config.example.json
|
|
diff config/config.json config/config.example.json
|
|
|
|
# Stellen Sie sicher, dass folgende Felder vorhanden sind:
|
|
# - csvStructure.headerLine (Zeilennummer der Kopfzeile)
|
|
# - csvStructure.delimiter (CSV-Trennzeichen)
|
|
# - metadata.extractionRules (mindestens 1)
|
|
# - columnTransformations (mindestens 1)
|
|
```
|
|
|
|
---
|
|
|
|
### Exception-Handling
|
|
|
|
Der Transformer nutzt Try-Catch für robuste Fehlerbehandlung:
|
|
|
|
```php
|
|
try {
|
|
$result = $engine->transform($inputFile);
|
|
if (!$result['success']) {
|
|
echo "Fehler: " . $result['error'];
|
|
}
|
|
} catch (Exception $e) {
|
|
echo "Fatal Error: " . $e->getMessage();
|
|
}
|
|
```
|
|
|
|
### Debug-Modus für Fehlersuche
|
|
|
|
Der Debug-Modus zeigt detailliert wo der Fehler liegt:
|
|
|
|
```bash
|
|
php bin/transformer.php process config/config.json input.csv --debug 2>&1 | tail -50
|
|
```
|
|
|
|
---
|
|
|
|
## Besonderheiten & Tipps
|
|
|
|
### UTF-8 Handling
|
|
|
|
Der Transformer nutzt UTF-8 safe Funktionen:
|
|
- `mb_strtolower()` statt `strtolower()`
|
|
- `mb_strtoupper()` statt `strtoupper()`
|
|
- `mb_strlen()` für korrektes Character-Counting
|
|
|
|
Unterstützte Encodings: UTF-8, ISO-8859-1, CP1252
|
|
|
|
### Regex-Tipps
|
|
|
|
**Pattern ohne Delimiter:**
|
|
```json
|
|
"pattern": "IBAN:\\s*([A-Z0-9 ]+)"
|
|
// Wird zu: /IBAN:\s*([A-Z0-9 ]+)/u
|
|
```
|
|
|
|
**Mit Flags:**
|
|
```json
|
|
"pattern": "/IBAN:\\s*([A-Z0-9 ]+)/iu"
|
|
// Case-insensitive
|
|
```
|
|
|
|
**Spezielle Zeichen escapen:**
|
|
```json
|
|
"pattern": "\\(\\d{4}\\)"
|
|
// Matcht: (1234)
|
|
```
|
|
|
|
### Performance
|
|
|
|
- **Max. Dateigröße:** Abhängig von RAM (typically 100MB+)
|
|
- **Optimiert für:** Bis zu 1 Million Zeilen
|
|
- **Typical:** 10-100k Zeilen pro Datei
|
|
|
|
### Batch-Processing
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
for file in import/source/*.csv; do
|
|
php bin/transformer.php process config/config.json "$file"
|
|
if [ $? -eq 0 ]; then
|
|
mv "$file" import/archive/
|
|
else
|
|
mv "$file" import/error/
|
|
fi
|
|
done
|
|
```
|
|
|
|
---
|
|
|
|
## Support & Troubleshooting
|
|
|
|
### Logging aktivieren
|
|
|
|
Nutze den Built-in Debug-Logger:
|
|
|
|
```bash
|
|
php bin/transformer.php test config/config.json input.csv --debug > debug.log 2>&1
|
|
cat debug.log | grep -i error
|
|
```
|
|
|
|
### Nützliche Kommandos
|
|
|
|
```bash
|
|
# Test CSV-Validität
|
|
php bin/transformer.php validate config.json input.csv
|
|
|
|
# Test nur mit 10 Zeilen
|
|
php bin/transformer.php test config.json input.csv
|
|
|
|
# Mit voller Debug-Ausgabe
|
|
php bin/transformer.php process config.json input.csv --debug
|
|
|
|
# Prüfe PHP-Syntax aller Dateien
|
|
php -l bin/transformer.php
|
|
php -l src/*.php
|
|
|
|
# Validiere Konfiguration
|
|
php -r "require 'src/ConfigurationLoader.php'; new UbsCsvTransformer\ConfigurationLoader('config/config.json');"
|
|
```
|
|
|
|
---
|
|
|
|
## Version & Änderungen
|
|
|
|
**v1.0.0 (10. Dezember 2025)**
|
|
- ✅ Initial Release
|
|
- ✅ 11 Transformationstypen
|
|
- ✅ Metadaten-Extraktion mit Regex
|
|
- ✅ Debug-Modus
|
|
- ✅ Firefly III Integration
|
|
- ✅ Vollständige Dokumentation
|
|
|
|
---
|
|
|
|
**Lizenz:** MIT
|
|
**Author:** PHP CSV Transformer Project
|
|
**Repository:** https://git.andare.ch/david.reindl/ff-imp-preprocessor |