sufw-taetigkeitsnachweise/.github/copilot-tasks.md

SAB Taetigkeitsnachweise Generator - Aufgabenliste

Ziel

Projekt vollstaendig umsetzen: aus PS_PW.xlsx und Stellenbeschreibungen.xlsx monatliche Taetigkeitsnachweise per Template erzeugen.

Arbeitsmodus

• Immer nur genau eine Aufgabe aktiv bearbeiten.
• Nach Abschluss jeder Aufgabe: Ergebnis pruefen und abhaken.
• Bei Blockern: Fehler dokumentieren und naechsten konkreten Schritt notieren.
• Nach jedem erledigten task einen git commit erzeugen

Phase 1 - Planung und Konfiguration

• T1: Plan final im Plan-Dokument pflegen (Scope, Annahmen, Reihenfolge, DoD pro Aufgabe).
• T2: config.json Struktur festlegen
  • Pfade fuer input/, template/, output/
  • Dateinamen der drei Excel-Dateien
  • Sheetnamen und Spaltenzuordnung je Quelle
  • Zielzellen-Mapping fuer Template
  • Dateinamenmuster fuer Ausgaben
  • Regeln fuer Monatsmarker und Datumsformat

Phase 2 - Projektgeruest und Basiskomponenten

• T3: Python-Projektstruktur anlegen
  • Modulaufteilung (cli, parser, matcher, validator, writer, model, util)
  • Gemeinsame Datenmodelle (z. B. dataclasses) definieren
  • Zentrales Logging/Fehlermodell vorbereiten
• T4: Abhaengigkeiten und Laufzeit vorbereiten
  • benoetigte Pakete festlegen (z. B. openpyxl, click)
  • requirements-Datei pflegen
  • Startkommando fuer lokale Ausfuehrung dokumentieren

Phase 3 - Einlesen der Quelldaten

• T5: Parser fuer PS_PW.xlsx implementieren
  • Monatsmarker in Zeile 2 erkennen und parsen (ab 01.MM.YYYY)
  • Zielspalte fuer requested month/year eindeutig bestimmen
  • Mitarbeiterkontext ueber Mehrzeilen-Eintraege vererben
  • Werte normalisieren (-, 0, leer, numerisch)
  • Normalisierte Records erzeugen
• T6: Parser fuer Stellenbeschreibungen.xlsx implementieren
  • Felder ID, Antragsnummer, Name, Qualifikation, Stellenanteil, Funktion, Taetigkeit einlesen
  • Prozentwerte (deutsches Dezimalformat) robust in Zahlen umwandeln
  • Mehrfache Eintraege je Name korrekt behalten

Phase 4 - Matching und Fachlogik

• T7: Foerderquote berechnen
  • Formel: funded_weekly_hours / contract_weekly_hours * 100
  • Rundungs-/Vergleichsregeln definieren
• T8: Matching-Engine bauen
  • Primaerschluessel Name anwenden
  • Kandidaten via Stellenanteil/Foerderquote aufloesen
  • Ambigue und fehlende Treffer sauber markieren
  • Hinweise aus Bemerkungsspalte als Validierungshinweis weitergeben

Phase 5 - Validierung

• T9: Source-Validierung implementieren
  • Dateien vorhanden und lesbar
  • Benoetigte Sheets vorhanden
  • Spalten vorhanden
  • Monatsmarker parsebar
  • Gewuenschter Monat exakt einmal vorhanden
  • Stunden-/Vertragswerte gueltig
• T10: Business-Validierung implementieren
  • Mindestens ein aktiver Fall vorhanden
  • Jeder aktive Fall hat eindeutigen Match oder klaren Fehler
  • Template enthaelt genau ein Quellblatt
  • Dateinamenkollisionen vermeiden
  • Pflicht-Zielzellen vollstaendig konfiguriert

Phase 6 - Ausgabeerzeugung

• T11: Template-Verarbeitung bauen
  • Template-Workbook laden
  • Sheet pro aktiver Zuordnung klonen
  • Inhalte assignment-spezifisch in Zielzellen schreiben
• T12: Dateinamen und Speichern
  • Muster: Taetigkeitsnachweis_YYYY_MM_Vorname_Nachname.xlsx
  • Pro Mitarbeiter genau eine Datei pro Monat erzeugen
  • Bei mehreren Zuordnungen: mehrere Sheets in derselben Datei

Phase 7 - CLI und Benutzerfluss

• T13: CLI in generate.py implementieren
  • Parameter --month und --year
  • Pipeline orchestrieren: parse -> match -> validate -> preview -> write
  • Kontrollierter Exit-Code bei Fehlern
• T14: Vorschau + Bestaetigung vor Schreiben
  • Uebersicht zu Berichtsmonat, aktiven Faellen, Fehlern
  • Liste der geplanten Ausgabedateien
  • Interaktive Bestaetigung (Abbruch ohne Schreibzugriff moeglich)

Phase 8 - Tests und Abnahme

• T15: Smoke-Test fuer End-to-End-Lauf
  • Beispielmonat ausfuehren
  • Dateien in output/ entstehen erwartungsgemaess
• T16: Fachtests definieren und ausfuehren
  • Mehrfachzuordnung eines Mitarbeiters
  • Fehlender Match
  • Ungueltige Monatsmarker
  • Fehlende Pflichtspalte/Sheet
• T17: Ergebnispruefung gegen Template-Regeln
  • Pflichtfelder korrekt befuellt
  • Taetigkeitstext inkl. Zeilenumbrueche korrekt
  • Datums- und Monatsanzeige korrekt

Umsetzungsreihenfolge

1. T1 -> T2
2. T3 -> T4
3. T5 und T6 (danach zusammenfuehren)
4. T7 -> T8
5. T9 -> T10
6. T11 -> T12
7. T13 -> T14
8. T15 -> T16 -> T17

Aktueller Startpunkt

• Naechste aktive Aufgabe: T5 (Parser fuer PS_PW.xlsx implementieren)