From 4165b9fdbc91a00ae7095ddbbdd155f86284f8f1 Mon Sep 17 00:00:00 2001 From: trnq1ll0 Date: Wed, 27 May 2026 09:31:04 +0200 Subject: [PATCH] update readme with actual progress --- README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 102 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d73efad..86269ab 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# SAB Taetigkeitsnachweise Tool +# 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 @@ -9,12 +11,107 @@ pip install -r requirements.txt ``` -## Local run command +## Ausführung -Use module execution from the project root: +Haupteinstiegspunkt ist `generate.py` (Click-basierte CLI): ```bash -python -m src.taetigkeitsnachweis.cli --version +python generate.py --month 5 --year 2026 ``` -Current CLI is a scaffold. Full generation pipeline is implemented in later tasks. +### 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 +```