SAB Tätigkeitsnachweise Tool

Automatisierte Generierung monatlicher Tätigkeitsnachweise (SAB Stellenförderung). Das Tool liest eine zentrale Stundenzuordnung und Stammdaten aus Excel-Dateien, ordnet Mitarbeiter zu Projekten zu und erzeugt pro Mitarbeiter eine vorausgefüllte Excel-Datei auf Basis der SAB-Vorlage.

Setup

1. Create and activate a virtual environment.
2. Install dependencies:

pip install -r requirements.txt

Ausführung

Haupteinstiegspunkt ist generate.py (Click-basierte CLI):

python generate.py --month 5 --year 2026

CLI-Optionen

Option	Typ	Pflicht	Beschreibung
--month	1–12	Ja	Berichtsmonat
--year	2000–2100	Ja	Berichtsjahr
--yes	Flag	Nein	Interaktive Bestätigung überspringen
--skip-errors	Flag	Nein	Generierung trotz nicht-zuordenbarer Einträge fortsetzen

Implementierte Features

Pipeline (generate.py)

Vollständige Generierungs-Pipeline mit folgenden Schritten:

1. Konfiguration laden – config.json wird eingelesen
2. Quellvalidierung – Prüfung der Eingabedateien auf Existenz, Sheets, Spalten, Monatsmarker
3. Parsing – Stundenzuordnung und Stammdaten aus Excel einlesen
4. Matching – Zuordnung der Mitarbeiter über normalisierte Namensabgleiche
5. Geschäftsregel-Validierung – Duplikate, fehlende Template-Sheets, Output-Kollisionen
6. Vorschau – Zusammenfassung der geplanten Ausgabe (Dry-Run-Ansicht)
7. Bestätigung – Interaktive Abfrage (überspringbar mit --yes)
8. Generierung – Excel-Workbooks erstellen und in output/ speichern

Parser (src/taetigkeitsnachweis/parser.py)

• Stundenzuordnung parsen (parse_allocation_records): Liest PS_PW.xlsx, erkennt Monatsspalte über Datumsmarker (ab DD.MM.YYYY), vererbt Mitarbeiter-/Vertragsstunden-Kontext über Zeilen
• Stammdaten parsen (parse_masterdata_records): Liest Stellenbeschreibungen.xlsx mit Antragsnummer, Qualifikation, Funktion, Tätigkeiten etc.
• Erkennung inaktiver Werte (Elternzeit, Kündigung, etc.)

Matcher (src/taetigkeitsnachweis/matcher.py)

• Namens-Normalisierung: Trimming, Akzente entfernen, Casefolding, Leerzeichenbereinigung
• Flexible Namens-Zuordnung: Unterstützt „Nachname, Vorname" ↔ „Vorname Nachname"
• Disambiguierung: Bei mehreren Stammdaten-Treffern wird über project_scope aufgelöst
• Förderquote-Berechnung: (geförderte Stunden / Vertragsstunden) × 100
• Erzeugt Validierungsmeldungen: MISSING_MASTERDATA, AMBIGUOUS_MASTERDATA, ALLOCATION_NOTE

Validator (src/taetigkeitsnachweis/validator.py)

Zweistufige Validierung:

• Quellvalidierung (validate_sources): Datei-Existenz, Sheet-Existenz, Spaltenprüfung, Monatsmarker-Parsebarkeit, Vertragsstunden-Prüfung
• Geschäftsregel-Validierung (validate_business_rules): Keine aktiven Zuordnungen, doppelte Matches, Template-Sheet-Existenz, Template-Targets-Vollständigkeit, Dateinamen-Kollisionen

Writer (src/taetigkeitsnachweis/writer.py)

• Workbook-Generierung (build_employee_workbooks): Lädt SAB-Vorlage, erstellt pro Zuordnung ein Sheet, befüllt konfigurierte Zielzellen (Antragsnummer, Name, Qualifikation, Funktion, Tätigkeiten, Berichtsmonat, Förderquote, Erstelldatum)
• Dateinamen-Generierung (build_output_filename): Pattern-basiert mit {year}, {month}, {first_name}, {last_name}
• Speicherung (save_employee_workbooks): Schreibt in output/, erkennt Dateinamen-Kollisionen

Datenmodelle (src/taetigkeitsnachweis/models.py)

• AllocationRecord – Mitarbeitername, Vertragsstunden, Projektkürzel, geförderte Stunden, Anmerkungen
• MasterDataRecord – Antragsnummer, Name, Qualifikation, Projektumfang, Stellenanteil, Funktion, Tätigkeit
• MatchedAssignment – Verknüpfung Zuordnung + Stammdaten + berechnete Förderquote
• ValidationIssue – Code, Meldung, Schweregrad, Kontext

Fehlerbehandlung (src/taetigkeitsnachweis/errors.py)

Exception-Hierarchie: TaetigkeitsnachweisError → ConfigurationError, ValidationError, MatchingError

Konfiguration (config.json)

Zentrale Konfigurationsdatei mit:

• Pfade: Input-, Template- und Output-Verzeichnisse
• Dateien: Zuordnungs-Workbook, Stammdaten-Workbook, Template-Workbook
• Sheet-Namen: Pro Workbook konfigurierbar
• Parsing-Regeln: Spalten-Mappings, Monatsmarker-Format, inaktive Werte
• Matching-Einstellungen: Normalisierung, Toleranz
• Output-Einstellungen: Dateinamen-Pattern, ein Workbook pro Mitarbeiter, ein Sheet pro Zuordnung
• Template-Targets: Zielzellen-Adressen in der Vorlage

Projektstruktur

Tool/
├── generate.py          # Haupteinstiegspunkt (Click CLI)
├── config.json          # Zentrale Konfiguration
├── start.sh             # Shell-Wrapper
├── requirements.txt     # Python-Abhängigkeiten
├── input/               # Eingabe-Excel-Dateien (PS_PW.xlsx, Stellenbeschreibungen.xlsx)
├── output/              # Generierte Tätigkeitsnachweise
├── template/            # SAB-Vorlage (Tätigkeitsnachweis Stellenförderung.xlsx)
└── src/taetigkeitsnachweis/
    ├── cli.py           # Legacy-Scaffold (argparse)
    ├── errors.py        # Exception-Klassen
    ├── logging_utils.py # Logging-Konfiguration
    ├── matcher.py       # Namenszuordnung & Förderquote
    ├── models.py        # Datenklassen
    ├── parser.py        # Excel-Parsing
    ├── util.py          # Utilities (noch leer)
    ├── validator.py     # Zwei-Phasen-Validierung
    └── writer.py        # Excel-Ausgabe