180 lines
6.8 KiB
Markdown
180 lines
6.8 KiB
Markdown
|
||
# 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:**
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
.venv\Scripts\activate # Windows
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
3. **App starten:**
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```powershell
|
||
.\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.
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```powershell
|
||
# 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"
|
||
|
||
|
||
# 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:
|
||
|
||
```text
|
||
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.
|