# Feature-Konzept: Abrechnung (PDF-Template-basiert)

## Ziel

Das Feature `Abrechnung` soll für verschiedene Vereine funktionieren, obwohl sich die PDF-Formulare im Aufbau unterscheiden. Die Lösung basiert daher auf konfigurierbaren Vorlagen mit Feld-Mapping statt auf einem festen Formular.

## Ausgangssituation

- Beispielformular: `Abrechungen_Übungsstunden_blanko.pdf`
- Typische Felder:
  - Übungsleiter/in
  - Gleiches Konto wie letzte Abrechnung (Checkbox)
  - IBAN (optional ohne Länderkennung)
  - Übungsstunden-Zeilen (Datum, Bezeichnung, Dauer)
  - Summenformel (`Ü-Stdn. * € = €`)
  - Ort, Datum
  - Belegnummer, Buchungsanweisung
- Vereinsabhängig abweichende Layouts und Feldpositionen müssen unterstützt werden.

## Kernanforderungen

1. PDF-Vorlage pro Verein hochladen und versionieren.
2. Felder frei definieren und Datenquellen zuordnen.
3. Bearbeitbare und nicht bearbeitbare PDFs unterstützen.
4. Monats- oder Monatsbereich für den Abrechnungslauf auswählbar machen.
5. Empfänger ist immer der eingeloggte Nutzer (eigene Abrechnung).
6. Stunden-Gehalt pro Abrechnungslauf erfassen.
7. Ort und Datum pro Lauf erfassen.
8. Sonderwerte und Formatierungen erlauben (`X`, IBAN ohne Länderkennung).
9. Optionalen Scanner/OCR als Vorschlagslogik für Feldpositionen vorsehen.

## Technischer Ansatz

### 1) Template-Verwaltung

- Entität `billing_template` enthält PDF-Datei und Metadaten.
- Mehrere Vorlagen pro Verein möglich (Versionierung).

### 2) Felddefinition und Mapping

- Entität `billing_template_field` beschreibt je Feld:
  - Feldtyp (Text, Zahl, Checkbox, Formel, Wiederholungszeile)
  - Quelle (manuell, Trainer, Mitglied, Verein, Konstante, Formel)
  - Formatierer (z. B. `iban_no_country`)
  - Mapping-Art:
    - `acroform`: via PDF-Formularfeldname
    - `overlay`: manuelle Position (`page`, `x`, `y`, `width`, `height`, Schriftgröße)

### 3) Abrechnungslauf

- Entität `billing_run` enthält Zeitraum, Ort, Datum, Stunden-Gehalt und den aktuellen Nutzer als festen Empfänger.
- Pro Lauf wird ein eigenes `billing_document` für den Nutzer erzeugt.
- Verwendete Werte werden in `billing_document_value` gespeichert (Audit/Nachvollziehbarkeit).

## Scanner/OCR-Option

- Scanner soll nur als Assistenz dienen:
  - erkennt Textanker wie `IBAN`, `Ort, Datum`, `Belegnummer`
  - schlägt Feldpositionen vor
- Nutzer kann und soll Vorschläge im Mapping-Editor korrigieren.
- Das finale Mapping wird immer gespeichert und hat Vorrang vor neuen OCR-Ergebnissen.

## Feld-Keys für das Beispiel-PDF

Empfohlene standardisierte `field_key`-Namen:

- `trainer_name`
- `same_account_checkbox`
- `iban`
- `lessons_rows`
- `hours_total`
- `hourly_rate`
- `amount_total`
- `self_recipient_name`
- `location_text`
- `document_date`
- `receipt_number`
- `booking_instruction`

## Geplante API (MVP)

- `POST /api/billing/templates`
- `GET /api/billing/templates`
- `GET /api/billing/templates/:id`
- `PUT /api/billing/templates/:id/fields`
- `POST /api/billing/runs`
- `POST /api/billing/runs/:id/generate`
- `GET /api/billing/runs/:id/documents`
- `GET /api/billing/documents/:id/download`
- `GET /api/billing/runs/:id/download-zip`

## MVP-Umfang

1. Migrationen für Abrechnungs-Tabellen
2. Template-Upload
3. Manueller Feld-Mapping-Editor (Overlay + AcroForm)
4. Lauf-Erstellung mit Zeitraum, Ort, Datum
5. Lauf-Erstellung mit Zeitraum, Stunden-Gehalt, Ort, Datum
6. PDF-Erzeugung und Download

## Erweiterungen nach MVP

- OCR-gestützter Positionsvorschlag
- Sammelunterschrift-Workflows
- Export für externe Buchhaltung
- Freigabeprozess (`draft -> generated -> finalized`)
