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)

```bash
# 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](https://www.python.org/downloads/) herunterladen und installieren
   - Bei der Installation "Add Python to PATH" aktivieren
2. Repository herunterladen oder klonen
3. Optional: Für Build als Executable
   ```cmd
   pip install pyinstaller
   ```

## 🚀 Nutzung

### GUI-Version (Empfohlen)

```bash
# 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)

```bash
# 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:

```json
{
    "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:

```json
{
    "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:

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

### projekte_XXX.json

Definiert Projekte/Kostenstellen:

```json
{
    "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

```csv
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

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

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

### Windows

```cmd
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"**
```bash
# 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](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*