update readme with actual progress

2026-05-27 09:31:04 +02:00
1 parent 716b8b5567
commit 4165b9fdbc
@@ -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
+```