118 lines
5.6 KiB
Markdown
118 lines
5.6 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## Ausführung
|
||
|
||
Haupteinstiegspunkt ist `generate.py` (Click-basierte CLI):
|
||
|
||
```bash
|
||
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
|
||
```
|