sufw-taetigkeitsnachweise/0_application/README-Development.md

Tätigkeitsnachweis-Generator

Streamlit-App zur automatisierten Erstellung von Tätigkeitsnachweisen aus Excel-Daten.

Setup

1. Python 3.9+ installieren (falls nicht vorhanden): https://python.org
2. Virtuelle Umgebung erstellen und Abhängigkeiten installieren:

python -m venv .venv
.venv\Scripts\activate     # Windows
pip install -r requirements.txt

3. App starten:

streamlit run app.py

Oder einfach start.bat (Windows) bzw. ./start.sh (macOS/Linux) ausführen.

Cold Run – Headless-Generierung

coldrun.py erzeugt ohne GUI einen Tätigkeitsnachweis für die erste Person – automatisch mit der ersten Input- und Template-Datei. Ergebnis wird auf macOS im Finder geöffnet.

# Kommandozeile
.venv/bin/python coldrun.py

# oder per Doppelklick (macOS)
coldrun.command

Bedienung

1. Input-Datei wählen – Dropdown zeigt alle .xlsx-Dateien aus dem input/-Ordner
   • Nach Auswahl wird die Datei sofort validiert
   • Angezeigt werden: Anzahl Mitarbeiter, Antragsnummern, Einträge pro Monat
2. Template wählen – Dropdown zeigt alle .xlsx-Dateien aus dem template/-Ordner
   • Nach Auswahl wird das Template sofort validiert
   • Angezeigt wird: Anzahl gefundener Zielfelder
3. Mitarbeiter auswählen – Multiselect-Liste aller gefundenen Mitarbeiter
   • Standardmäßig sind alle ausgewählt
   • Nicht selektierte Mitarbeiter werden bei der Generierung übersprungen
4. "Tätigkeitsnachweise generieren" klicken
   • Die generierten Dateien werden im output/-Ordner abgelegt

Konfiguration

Alle Einstellungen liegen im config/-Ordner:

settings.ini

• [paths] – Ordner für Input, Template, Output
• [output] – Dateinamen-Pattern ({first_name}, {last_name})
• [parsing] – Monats-Sheet-Erkennung, Leerzeilen-Verhalten

input-fields.json

Definiert die Spalten der Input-Tabelle:

• column: Spaltenbuchstabe (A, B, C…)
• field_name: Exakte Spaltenüberschrift aus der Excel-Datei
• type: string oder number
• required: true oder false

output-fields.json

Mapping von Input-Feldern auf Template-Zellen:

• source_field: Exakte Spaltenüberschrift aus input-fields.json
• target_cell: Zelladresse im Template (z. B. "C16")
• format: Optionaler Format-String (z. B. "%.2f" für Prozentwerte)

Erwartetes Input-Format

• Eine .xlsx-Datei mit einem Sheet pro Monat (z. B. "Januar 2025", "Februar 2025", …)
• Jedes Sheet hat in Zeile 1 die Spaltenüberschriften (laut input-fields.json)
• Daten beginnen ab Zeile 2
• Jede Zeile entspricht einer Mitarbeiter-Funktion-Kombination für diesen Monat

Output

• Pro selektiertem Mitarbeiter wird eine .xlsx-Datei erstellt
• Jeder Monat wird als eigenes Sheet (Kopie des Templates) eingefügt
• Dateiname: {Nachname}_{Vorname}_Tätigkeitsnachweis.xlsx

Tests

Beim Start über start.bat oder die neu gebaute EXE erscheint bei einer bereits laufenden Programminstanz ein Ja/Nein-Dialog. „Ja“ beendet die bisherige Instanz und startet die neue; „Nein“ lässt die bisherige Instanz geöffnet und bricht den neuen Start ab. Aktuelle Auswahlen gehen beim Beenden verloren. Ein fremdes Programm auf Port 8501 wird nicht beendet.

Unter Windows führt test.bat alle Tests im Ordner tests/ aus. Das Skript verwendet die Projektumgebung .venv und installiert bei Bedarf pytest. Per Doppelklick bleibt das Ergebnisfenster geöffnet. Für automatisierte Aufrufe:

.\0_application\test.bat --no-pause

Dieser Aufruf erfolgt aus dem Projekt-Hauptordner. Bei fehlgeschlagenen Tests liefert das Skript einen Fehlercode und führt die übrigen Tests trotzdem aus. Die Tests laufen nicht automatisch beim Programmstart oder Build.

End-to-End-Tests parsen die feste Testdatei (tests/fixture/2026 JM.xlsx) und das PDF-Template (template/Tätigkeitsnachweise Stellenförderung.pdf) und validieren den gesamten Generierungs-Workflow.

# Test-Abhängigkeiten installieren
.venv/bin/pip install pytest

# Tests ausführen
.venv/bin/python -m pytest tests -v

Die Tests prüfen:

• Vorhandensein der Input- und Template-Dateien
• Korrekte Parsierung (100 Datensätze, 17 Personen)
• Vollständige PDF-Pipeline für die erste Person („Bardaus, Madalina“): fünf Monate von Januar bis Mai 2026 mit zehn Seiten, Antragsnummer, Name, Stellenanteil, Monat, Funktion, Tätigkeit, Ort und korrekten Monatsenddaten
• Neustartlogik unter Windows mit simulierten Prozessen