sufw-taetigkeitsnachweise/.copilot/PLAN.md

Ziel

Eine Python + Streamlit App für Windows, die aus einer Input-Excel-Datei (ein Sheet pro Monat mit Mitarbeiterdaten) und einem Excel-Template pro Mitarbeiter eine Excel-Datei generiert (ein Sheet pro Monat, befüllt mit dessen Daten).

Ansatz: Wiederverwendung der bewährten openpyxl-Patterns aus dem Vorgängerprojekt (1_Erstes-Tool-Komplizert), aber vereinfacht für Single-Input-File + Streamlit-UI statt CLI.

Aufgabe

Erstelle eine Windows App in dessen Oberfläche aus folgenden Bestandteilen aufgebaut ist:

• mittels einem DropDown-Menü kann eine Datei aus dem inputfolder gewählt werden
• mittels einem DropDown-Menü kann ein Template aus dem Templatefolder gewählt werden
• ein Button um den Vorgang zu starten

Die Funktion der App besteht darin, das Templatefile mit Daten aus dem Input-File zu befüllen. Im Inputfile ist für alle Monate eines Jahres eine Liste aller Mitarbeitenden und in den Spalten alle Daten zur Befüllung des Template files.

Aufbau Input Datei

• In der Input Datei ist für jeden Monat eines Jahres ein Sheet gespeichert.
• In jedem Sheet befindet sich eine Tabelle (felder speichern in Input Schema json) mit Mitarbeitenden.
• Für jeden Mitarbeitenden soll aus dem Template eine neue ExcelDatei erzeugt werden, welche auch wieder für jeden Monat ein Sheet des Templates enthält und alle Daten des Mitarbeiters für dieses Monat aus der Inputliste enthält.

README

In der README.md ist ein kleine Doku wie das Programm zu benutzen ist und welche Konfigurationsparameter es gibt.

---

Phasen-Plan

Phase 1: Projekt-Grundgerüst & Konfiguration

1. requirements.txt befüllen — streamlit, openpyxl
2. config/settings.ini befüllen — Pfade, Standardwerte
   • Abschnitte: [paths] (input_dir, template_dir, output_dir), [output] (filename_pattern)
3. config/input-fields.json Schema definieren — Spaltennamen und Typen der Input-Tabelle
   • Muss durch Analyse der Datei input/2025 JM.xlsx ermittelt werden (Spalten A–?)
   • JSON-Array mit name, column, type, required
4. config/output-fields.json Mapping definieren — Welche Input-Felder in welche Template-Zellen
   • JSON-Array mit source_field, target_cell, format (optional)
   • Muss durch Analyse des Templates template/Tätigkeitsnachweise Stellenförderung.xlsx ermittelt werden

Phase 2: Core-Module (src/)

5. src/__init__.py + src/models.py — Datenklassen
   • EmployeeRecord: name, vorname, nachname, antragsnummer, qualifikation, funktion, taetigkeit, stellenanteil, monat, jahr, … (Felder aus input-fields.json)
   • AppConfig: geladene settings.ini + input/output-schemas
   • Referenz: 1_Erstes-Tool-Komplizert/src/taetigkeitsnachweis/models.py
6. src/config.py — Konfigurations-Loader
   • load_settings(): liest config/settings.ini mit configparser
   • load_input_schema(): liest config/input-fields.json
   • load_output_mapping(): liest config/output-fields.json
   • get_available_input_files(): listet .xlsx-Dateien in input/
   • get_available_templates(): listet .xlsx-Dateien in template/
7. src/parser.py — Input-Datei einlesen
   • parse_input_file(filepath, schema): öffnet Workbook, iteriert über alle Sheets (Monate)
   • Extrahiert Monat/Jahr aus Sheet-Namen oder Sheet-Inhalt
   • Für jedes Sheet: liest Zeilen anhand des Schemas, erzeugt EmployeeRecord-Liste
   • Rückgabe: dict[str, list[EmployeeRecord]] (key = Mitarbeiter-Name)
   • Referenz: 1_Erstes-Tool-Komplizert/src/taetigkeitsnachweis/parser.py

Phase 3: Writer & Validierung

8. src/writer.py — Output generieren
   • generate_workbooks(employee_records, template_path, mapping, config):
     • Gruppiert Records nach Mitarbeiter
     • Für jeden Mitarbeiter: lädt Template, erstellt für jeden Monat ein Sheet (kopiert Template-Sheet)
     • Befüllt Zielzellen gemäß output-fields.json Mapping
     • Benennt Sheets nach Monat (z.B. "01_Januar", "02_Februar", …)
     • Speichert als {nachname}_{vorname}_Tätigkeitsnachweis.xlsx in output/
   • Referenz: 1_Erstes-Tool-Komplizert/src/taetigkeitsnachweis/writer.py
9. src/validator.py — Eingabevalidierung
   • validate_input_file(filepath, schema): prüft Datei-Existenz, Sheet-Anzahl, Spalten laut Schema
   • validate_template(template_path, mapping): prüft ob alle target_cells im Template existieren
   • Referenz: 1_Erstes-Tool-Komplizert/src/taetigkeitsnachweis/validator.py

Phase 4: Streamlit UI

10. app.py — Streamlit-Oberfläche
    • Layout:
      • Titel + Beschreibung
      • st.selectbox für Input-Datei (aus input/-Folder)
      • st.selectbox für Template (aus template/-Folder)
      • st.button("Tätigkeitsnachweise generieren")
    • Bei Button-Click:
      1. Lade Konfiguration
      2. Validiere Input-Datei + Template (zeige Fehler/Warnungen via st.warning/st.error)
      3. Parse Input → Employee Records
      4. Gruppiere nach Mitarbeiter (zeige Vorschau: N Mitarbeiter gefunden)
      5. Generiere Workbooks und speichere in output/
      6. Zeige Erfolgsmeldung mit Liste der erstellten Dateien via st.success
    • Status-Anzeige mit st.spinner und st.progress

Phase 5: Start-Skript & Doku

11. start.bat — Windows Batch-Startdatei
    • Prüft ob Python verfügbar ist
    • Installiert Requirements (falls nötig)
    • Startet streamlit run app.py
12. README.md aktualisieren — Vollständige Doku
    • Setup-Anleitung (Python, venv, pip install)
    • Konfiguration (settings.ini, input-fields.json, output-fields.json)
    • Bedienung (Datei auswählen, Template wählen, Button klicken)
    • Erwartetes Input-Format (Spalten, monatliche Sheets)
    • Output-Beschreibung (Dateiname, Struktur)

---

Relevante Dateien (zu erstellen/ändern)

Datei	Aktion
requirements.txt	Neu befüllen
config/settings.ini	Neu befüllen
config/input-fields.json	Neu befüllen (nach Analyse Input-Datei)
config/output-fields.json	Neu befüllen (nach Analyse Template)
src/__init__.py	Neu (leer)
src/models.py	Neu
src/config.py	Neu
src/parser.py	Neu
src/writer.py	Neu
src/validator.py	Neu
app.py	Neu
start.bat	Neu
README.md	Überschreiben mit vollständiger Doku

Referenz-Code (Vorgängerprojekt)

• 1_Erstes-Tool-Komplizert/src/taetigkeitsnachweis/parser.py — Parsing-Patterns für openpyxl
• 1_Erstes-Tool-Komplizert/src/taetigkeitsnachweis/writer.py — Template-Befüllung, Sheet-Kopie
• 1_Erstes-Tool-Komplizert/src/taetigkeitsnachweis/validator.py — Source-Validierung
• 1_Erstes-Tool-Komplizert/src/taetigkeitsnachweis/models.py — Dataclass-Patterns
• 1_Erstes-Tool-Komplizert/config.json — Konfigurationsstruktur

Projektstruktur

/
├── .copilot/
│   ├── PLAN.md             ← diese Datei
│   └── TASKS.md            ← Aufgabenliste
├── input/
│   └── *.xlsx              ← Tabelle mit den Input-daten
├── config/
│   ├── settings.ini        ← Einstellungen der App
│   ├── input-fields.json   ← Schema der Inputdaten-Tabelle
│   └── output-fields.json  ← Schema der Outputdaten-Tabelle
├── output/                 ← Zielordner für generierte Dateien
├── src/
│   ├── __init__.py
│   ├── models.py
│   ├── config.py
│   ├── parser.py
│   ├── writer.py
│   └── validator.py
├── app.py                  ← Streamlit-App
├── start.bat               ← Windows batch zum Start der App
├── README.md               ← README für Programmbenutzer
└── requirements.txt        ← streamlit, openpyxl

Verifikation

1. Input-Datei-Analyse: 2025 JM.xlsx mit openpyxl öffnen, Sheet-Namen prüfen, Spaltenüberschriften ausgeben → input-fields.json ableiten
2. Template-Analyse: Tätigkeitsnachweise Stellenförderung.xlsx öffnen, belegte Zellen inspizieren → output-fields.json ableiten
3. Unit-Test: App mit vorhandener Input-Datei und Template ausführen, prüfen ob Output-Dateien korrekt befüllt sind
4. Edge Cases: Leere Input-Zeilen, fehlende Monate, Mitarbeiter ohne Vorname, Sonderzeichen in Namen