# 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
```