From eb1dd45e57f17dfb6262817d2235fe55c1313f00 Mon Sep 17 00:00:00 2001 From: Rob Date: Mon, 10 Aug 2026 18:19:59 +0200 Subject: [PATCH] setup README for dev and end user --- 0_application/README-Development.md | 107 ++++++++++++++++++++++++++++ 0_application/README.md | 61 ++-------------- 2 files changed, 112 insertions(+), 56 deletions(-) create mode 100644 0_application/README-Development.md diff --git a/0_application/README-Development.md b/0_application/README-Development.md new file mode 100644 index 0000000..6c3b62d --- /dev/null +++ b/0_application/README-Development.md @@ -0,0 +1,107 @@ + +# 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 + +End-to-End-Tests parsen die reale Input-Datei (`input/2025 JM.xlsx`) und das reale +Template (`template/Tätigkeitsnachweise Stellenförderung.xlsx`) 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/test_e2e.py -v +``` + +Die Tests prüfen: +- Vorhandensein der Input- und Template-Dateien +- Korrekte Parsierung (168 Datensätze, 19 Personen) +- Vollständige Pipeline für die erste Person („Draßdo, Cornelia"): 12 Monats-Sheets + mit allen Zellinhalten (Antragsnummer, Name, Stellenanteil, Qualifikation, Monat, + Funktion, Tätigkeit, Ort, Datum) \ No newline at end of file diff --git a/0_application/README.md b/0_application/README.md index 6c3b62d..5ea09af 100644 --- a/0_application/README.md +++ b/0_application/README.md @@ -1,40 +1,10 @@ - # Tätigkeitsnachweis-Generator -Streamlit-App zur automatisierten Erstellung von Tätigkeitsnachweisen aus Excel-Daten. +Programm zur automatisierten Erstellung von Tätigkeitsnachweisen aus Excel-Daten. +Die aktuellesten Programmversion find sich immer hier: +"j:\Fachbereiche\BO\Produktionsschule\Maßnahmeunterlagen\20_Personal\05_Tätigkeitsnachweise ESF\Nachweise-automatisiert-generieren\" -## 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 -``` +Um das Programm zu starten: Doppelklick auf `Tätigkeitsnachweis-Generator.exe` ## Bedienung @@ -83,25 +53,4 @@ Mapping von Input-Feldern auf Template-Zellen: - 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 - -End-to-End-Tests parsen die reale Input-Datei (`input/2025 JM.xlsx`) und das reale -Template (`template/Tätigkeitsnachweise Stellenförderung.xlsx`) 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/test_e2e.py -v -``` - -Die Tests prüfen: -- Vorhandensein der Input- und Template-Dateien -- Korrekte Parsierung (168 Datensätze, 19 Personen) -- Vollständige Pipeline für die erste Person („Draßdo, Cornelia"): 12 Monats-Sheets - mit allen Zellinhalten (Antragsnummer, Name, Stellenanteil, Qualifikation, Monat, - Funktion, Tätigkeit, Ort, Datum) \ No newline at end of file +- Dateiname: `{Nachname}_{Vorname}_Tätigkeitsnachweis.xlsx` \ No newline at end of file