csv-dbf-converter/README.md

CSV zu DBF Konverter für Hausverwaltung

Ein Python-Tool zur Konvertierung von CSV-Bankauszügen in DBF-Dateien für Hausverwaltungssoftware.

📋 Beschreibung

Dieses Programm konvertiert CSV-Exporte von Bankauszügen in das DBF-Format (dBase III), das von vielen älteren Hausverwaltungsprogrammen benötigt wird. Es analysiert automatisch Buchungstexte und ordnet diese den entsprechenden Konten, Gegenkonten und Kostenstellen zu.

Hauptfunktionen

• Automatische Kontenzuordnung: Erkennt Mieter und Kostenkonten anhand konfigurierbarer Suchbegriffe
• Mehrmandantenfähig: Unterstützt beliebig viele Mandanten mit eigenen Konfigurationen
• Projektzuordnung: Automatische Zuordnung zu Kostenstellen/Projekten
• Monatliche Trennung: Erstellt separate DBF-Dateien pro Monat
• Flexible Filterung: Auswahl von Monaten und Jahren für die Konvertierung
• GUI und CLI: Verfügbar als grafische Oberfläche und Kommandozeilenversion

🖥️ Systemanforderungen

Python-Version

• Python 3.8 oder höher

Betriebssysteme

• Linux: Ubuntu, Debian, Fedora, etc.
• Windows: Windows 10/11

Abhängigkeiten

• tkinter (für GUI-Version, meist vorinstalliert)
• Alle anderen verwendeten Module sind Teil der Python-Standardbibliothek

📦 Installation

Linux (Ubuntu/Debian)

# Python und tkinter installieren
sudo apt update
sudo apt install python3 python3-tk

# Repository klonen
git clone https://github.com/IHR-BENUTZERNAME/csv-dbf-converter.git
cd csv-dbf-converter

# Optional: Für Build als Standalone-Executable
pip3 install pyinstaller

Windows

1. Python von python.org herunterladen und installieren
   • Bei der Installation "Add Python to PATH" aktivieren
2. Repository herunterladen oder klonen
3. Optional: Für Build als Executable

   pip install pyinstaller
   

🚀 Nutzung

GUI-Version (Empfohlen)

# Linux
python3 csv_dbf_converter_gui.py

# Windows
python csv_dbf_converter_gui.py

Die grafische Oberfläche führt Sie durch folgende Schritte:

1. Mandant auswählen
2. CSV-Datei auswählen
3. Zeitraum (Monate/Jahre) festlegen
4. Konvertierung starten

CLI-Version (Kommandozeile)

# Linux
python3 csv_dbf_converter.py

# Windows
python csv_dbf_converter.py

Die Kommandozeilenversion führt interaktiv durch den Prozess und zeigt detaillierte Informationen zur Verarbeitung an.

⚙️ Konfiguration

Das Programm verwendet JSON-Konfigurationsdateien. Beim ersten Start werden Beispieldateien erstellt.

Verzeichnisstruktur der Konfigurationsdateien

./
├── mandanten_config.json          # Mandanten-Übersicht
├── identitaeten_mieter_XXX.json   # Mieter pro Mandant (XXX = Mandantennummer)
├── identitaeten_kosten_XXX.json   # Kostenkonten pro Mandant
└── projekte_XXX.json              # Projekte/Kostenstellen pro Mandant

mandanten_config.json

Definiert die verfügbaren Mandanten:

{
    "mandanten": [
        {
            "name": "Mein Mandant",
            "nummer": "001",
            "konto": "1200",
            "standard_gegenkonto": "1300",
            "standard_bank_kto": "1200",
            "beleg_index": 1
        }
    ]
}

Feld	Beschreibung
name	Name des Mandanten
nummer	Eindeutige Mandantennummer (3-stellig)
konto	Standard-Bankkonto
standard_gegenkonto	Gegenkonto für nicht zugeordnete Buchungen
standard_bank_kto	Bankkonto für Buchungen
beleg_index	Fortlaufende Belegnummer (wird automatisch erhöht)

identitaeten_mieter_XXX.json

Definiert Mieter mit Suchbegriffen für automatische Erkennung:

{
    "mandant": "Mein Mandant",
    "mandantennummer": "001",
    "mieter": [
        {
            "suchbegriffe": ["Müller", "Thomas Müller", "MUELLER"],
            "konto": "10010",
            "beschreibung": "Thomas Müller"
        }
    ]
}

identitaeten_kosten_XXX.json

Definiert Kostenkonten für Ausgaben:

{
    "kostenkonten": [
        {
            "gegenkonto": 4002,
            "bezeichnung": "Be- und Entwässerung",
            "suchbegriffe": ["Berliner Wasser", "WASSERBETRIEBE"]
        }
    ]
}

projekte_XXX.json

Definiert Projekte/Kostenstellen:

{
    "mandant": "Mein Mandant",
    "mandantennummer": "001",
    "default_projekt": "001",
    "projekte": [
        {
            "suchbegriffe": ["Hauptstraße", "Hauptstr"],
            "kst": "001",
            "beschreibung": "Objekt Hauptstraße"
        }
    ]
}

📄 CSV-Format

Das Programm erwartet CSV-Dateien mit Semikolon als Trennzeichen und folgenden Spalten:

Erwartete Spalte	Alternative Namen
Buchungstag	Datum
Buchungstext	Verwendungszweck, Text
Betrag	Amount

Beispiel CSV-Datei

Buchungstag;Buchungstext;Betrag
01.01.2024;Miete Thomas Müller Januar;750,00
02.01.2024;Berliner Wasserbetriebe Abschlag;-125,50

🔨 Build (Standalone Executable)

Linux

cd scripts
chmod +x build_linux.sh
./build_linux.sh

Die ausführbare Datei befindet sich dann in dist/csv_dbf_converter_gui.

Windows

cd scripts
build_windows.bat

Die EXE-Datei befindet sich dann in dist\CSV_DBF_Konverter.exe.

📁 Projektstruktur

csv-dbf-converter/
├── csv_dbf_converter.py       # CLI-Version (Hauptprogramm)
├── csv_dbf_converter_gui.py   # GUI-Version mit tkinter
├── config/
│   └── examples/              # Beispiel-Konfigurationsdateien
│       ├── mandanten_config.json
│       ├── identitaeten_mieter_*.json
│       ├── identitaeten_kosten_*.json
│       └── projekte_*.json
├── scripts/
│   ├── build_linux.sh         # Linux Build-Script
│   └── build_windows.bat      # Windows Build-Script
├── requirements.txt           # Python-Abhängigkeiten
├── LICENSE                    # MIT-Lizenz
└── README.md                  # Diese Datei

🔍 Funktionsweise

Zuordnungslogik

1. Mieternummer-Parsing: Das Programm sucht zunächst nach 5-stelligen Zahlen beginnend mit "1" im Buchungstext, die auf ein Mieterkonto verweisen könnten.

2. Suchbegriff-Matching: Falls keine Mieternummer gefunden wird, werden die konfigurierten Suchbegriffe geprüft:

   • Zuerst Mieter-Suchbegriffe
   • Dann Kostenkonten-Suchbegriffe

3. Projekt-Zuordnung: Bei Kostenkonten wird zusätzlich nach Projekt-Suchbegriffen gesucht. Falls kein Projekt gefunden wird, wird das Default-Projekt verwendet.

Text-Normalisierung

Für den Vergleich werden Texte normalisiert:

• Kleinschreibung
• Umlaute: ü→ue, ö→oe, ä→ae, ß→ss

📝 Beispiele

Beispiel-Workflow

1. Mandanten konfigurieren in mandanten_config.json
2. Mieter anlegen in identitaeten_mieter_001.json
3. Kostenkonten anlegen in identitaeten_kosten_001.json
4. CSV-Datei von Bank exportieren
5. Konverter starten und CSV-Datei auswählen
6. Monate/Jahre auswählen für die Konvertierung
7. DBF-Dateien werden pro Monat erstellt

Ausgabe-Dateien

Die generierten DBF-Dateien folgen dem Namensschema:

buchungen_[MANDANTENNR]_[MONAT][JAHR_KURZ].dbf

Beispiel: buchungen_001_0124.dbf (Mandant 001, Januar 2024)

🐛 Fehlerbehebung

Häufige Probleme

"tkinter nicht gefunden"

# Ubuntu/Debian
sudo apt install python3-tk

# Fedora
sudo dnf install python3-tkinter

"CSV-Spalte nicht gefunden"

• Prüfen Sie, ob die CSV-Datei Semikolon als Trennzeichen verwendet
• Prüfen Sie die Spaltennamen (Buchungstag, Buchungstext, Betrag)

"Keine Buchungen für den gewählten Zeitraum"

• Prüfen Sie das Datumsformat in der CSV (DD.MM.YYYY)
• Prüfen Sie die gewählten Monate und Jahre

📜 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Siehe LICENSE für Details.

👤 Autor

Sebastian Zell

• E-Mail: sebastian.zell@zell-aufmass.de

🤝 Beitragen

Beiträge sind willkommen! Bitte erstellen Sie einen Pull Request oder öffnen Sie ein Issue für Verbesserungsvorschläge.

---

Erstellt für die Hausverwaltung mit ❤️ und Python