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. Beim Build laufen die Tests automatisch vor der Versionierung und dem Bauen. Beim Programmstart werden sie nicht ausgeführt.

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

Build und Deployment unter Windows

Alle folgenden Befehle werden im Projekt-Hauptordner ausgeführt:

# Interaktiv: Versionsänderung auswählen
.\1_build-pipeline\build.bat

# Bugfix-Version mit Changelog-Beschreibung
.\1_build-pipeline\build.bat --bump patch --message "Fehler beim Programmstart behoben"

# Ablauf anzeigen, ohne Tests, Build oder Deployment auszuführen
.\1_build-pipeline\build.bat --bump patch --dry-run

# Aktuelle Version mit aktualisiertem Changelog erneut als EXE bauen
.\1_build-pipeline\build.bat --no-bump --no-deploy

# Nur den letzten erfolgreichen Build bereitstellen (kein neuer Build)
.\1_build-pipeline\deploy.bat

# Deployment ohne abschließende Tasteneingabe
.\1_build-pipeline\deploy.bat --no-pause

Die Pipeline führt zuerst alle Tests aus. Bei einem Testfehler bleiben Version und Changelog unverändert; Build und Deployment werden nicht gestartet. Nach erfolgreichen Tests aktualisiert sie die Version, erstellt die EXE und legt sie mit Konfiguration, PDF-Template, README und Changelog in 2_build/ ab. release.json hält die Version und Prüfsummen des erfolgreichen Builds fest. Bei einem Buildfehler wird der Changelog zurückgesetzt.

Danach erzeugt das Deployment Tätigkeitsnachweis-Generator vX.Y.Z.zip und überträgt es an:

j:\Fachbereiche\BO\Produktionsschule\Maßnahmeunterlagen\20_Personal\05_Tätigkeitsnachweise ESF\Nachweise-automatisiert-generieren\

Das Ziel muss bereits vorhanden und über VPN/SMB erreichbar sein. Ist es nicht erreichbar oder fehlen Schreibrechte, bricht das Deployment verständlich ab. Der lokale Build bleibt erhalten. Nach Wiederherstellung der VPN-Verbindung kann deploy.bat die Bereitstellung ohne erneutes Testen, Bauen oder Erhöhen der Versionsnummer wiederholen. Das Skript akzeptiert nur einen bestätigten, unveränderten Build mit release.json; ältere Builds müssen einmal neu gebaut werden.

Das ZIP enthält leere input/- und output/-Ordner; Arbeitsdateien und Testdaten werden nicht mit ausgeliefert. Es wird zunächst als temporäre Datei übertragen, per Prüfsumme geprüft und erst dann unter dem Versionsnamen sichtbar gemacht. Bestehende Versionen mit anderem Inhalt werden nicht überschrieben. Ein identisches Paket kann erneut bereitgestellt werden. Die Neustarttests simulieren Prozesse und Dialogantworten; ein manueller Starttest der fertigen EXE bleibt vor der Weitergabe sinnvoll.