# Modul Mahnung — 3-stufiges Mahnwesen für Dolibarr

Mahnwesen-Modul für Dolibarr ERP: tägliche Vorschlagsliste überfälliger Rechnungen, 3-stufiger Workflow (Erinnerung → Mahnung → Letzte Mahnung), Mahngebühren + tagesgenaue Verzugszinsen nach **BGB §288**, PDF-Mahnschreiben (DIN 5008), E-Mail-Versand, Sammelbrief, Trigger auf Zahlungseingang.

## Status

Version **0.1.0** — Erstveröffentlichung, alle 10 Phasen der ROADMAP.md abgeschlossen.

## Features

| Feature | Implementierung |
|---|---|
| Tägliche Vorschlagsliste überfälliger Rechnungen | Cron `MahnungCronBuildVorschlag` (default deaktiviert) |
| Push-Benachrichtigung mit Anzahl je Stufe | Ntfy + GlobalNotify |
| 3 Stufen pflegbar (Frist, neue Frist, Gebühr B2C/B2B, Versandart, E-Mail-Template, PDF-Intro) | `admin/setup.php` |
| B2C / B2B-Erkennung | über `llx_societe.tva_intra` |
| Verzugszinsen | tagesgenau, B2C: Basiszins +5 %, B2B: +9 %; Override pro Stufe möglich |
| §288 Abs. 5 Pauschale 40 € | nur bei B2B, einmalig pro Rechnung |
| PDF-Mahnschreiben | DIN 5008 Form A, im Doc-Ordner der Rechnung (erscheint im Dokumente-Tab) |
| Bulk-Erstellung + Sammelbrief (alle PDFs in einer Datei) | TCPDI-basiert |
| E-Mail-Versand mit PDF-Anhang | `CMailFile`, Subject/Body mit Platzhaltern |
| Auto-Erledigung bei Zahlungseingang | Trigger `BILL_PAYED` + `PAYMENT_CUSTOMER_CREATE` |
| Tab "Mahnungen (n)" auf Rechnungs- + Kundenkarte | Hook `completeTabsHead` |

## Voraussetzungen

- Dolibarr ≥ 19
- PHP ≥ 7.4
- TCPDF (Dolibarr-Standard) für PDF
- Optional: TCPDI (Dolibarr `includes/tcpdf/tcpdi.php`) für Sammelbrief-Konkatenation
- Optional: `GlobalNotify` für In-App-Notification-Badges
- Empfohlen: `BankImport` (automatischer Zahlungseingang via FinTS triggert die Mahnungs-Erledigung sauber)

## Installation

```bash
git clone https://git.data-it-solution.de/data/mahnung.git \
  /pfad/zu/dolibarr/htdocs/custom/mahnung
```

Dann **Startseite → Setup → Module → Finanzwesen → Mahnung** aktivieren.

Bei Aktivierung werden `llx_mahnung_mahnung` und `llx_mahnung_stufe` angelegt; drei Default-Stufen werden idempotent eingefügt.

Nach Aktivierung in **Setup → Mahnwesen Einstellungen** den Basiszins prüfen und die Stufen-Texte (PDF-Intro, E-Mail-Body) anpassen.

Den Cron-Job `MahnungCronBuildVorschlag` aktivieren, sobald die Setup-Werte stimmen.

## Rechte

| Recht | Standard | Bedeutung |
|---|---|---|
| `mahnung.read`   | aktiv | Mahnungen einsehen |
| `mahnung.write`  | inaktiv | Mahnungen erstellen / bearbeiten |
| `mahnung.send`   | inaktiv | Mahnungen versenden (E-Mail / Druck) |
| `mahnung.delete` | inaktiv | Mahnungen stornieren |
| `mahnung.setup`  | inaktiv | Stufen, Basiszins, Versand konfigurieren |

## Modul-Konstanten

| Name | Default | Bedeutung |
|---|---|---|
| `MAHNUNG_BASISZINS`     | `1.27`      | BGB-Basiszins (%) — halbjährlich pflegen (1.1./1.7.) |
| `MAHNUNG_AUFSCHLAG_B2C` | `5.0`       | Verzugszins-Aufschlag B2C (BGB §288 Abs. 1) |
| `MAHNUNG_AUFSCHLAG_B2B` | `9.0`       | Verzugszins-Aufschlag B2B (BGB §288 Abs. 2) |
| `MAHNUNG_PAUSCHALE_B2B` | `40.00`     | Pauschale B2B (EUR, BGB §288 Abs. 5, einmalig) |
| `MAHNUNG_NTFY_TOPIC`    | `vk-builds` | Ntfy-Topic für Vorschlags-Push |
| `MAHNUNG_NTFY_URL`      | `https://notify.data-it-solution.de` | Ntfy-Endpoint |
| `MAHNUNG_NTFY_AUTH`     | leer        | Optional: `Basic ...` Authorization-Header |

## Workflow

```
Cron 06:00
   |
   |--> ueberfaellige Rechnungen einsammeln
   |--> Stufe ermitteln (Stufe 1 ab frist_tage Verzug,
   |                     Folgestufen nach neue_frist_tage seit Vor-Mahnung)
   |--> Ntfy-Push mit Anzahl je Stufe + Gesamt-EUR
   |--> GlobalNotify "actionRequired" (wenn Modul aktiv)
   |
   v
list.php (Vorschlagsliste)
   |
   |--> User waehlt aus + klickt "Mahnungen erzeugen"
   |    -> ajax/createmahnung.php berechnet Gebuehr + Verzugszinsen,
   |       persistiert llx_mahnung_mahnung, generiert PDF
   |
   |--> Alternativ "Sammelbrief erzeugen"
   |    -> ajax/sammelbrief.php generiert + konkateniert PDFs
   |
Zahlungseingang (BankImport / Manual)
   |
   v Trigger BILL_PAYED / PAYMENT_CUSTOMER_CREATE
   |--> alle offenen Mahnvorgaenge zur Rechnung -> status=erledigt
```

## Dateibaum

```
mahnung/
├── core/modules/modMahnung.class.php           Descriptor, Rechte, Cron, Hooks
├── core/triggers/interface_99_modMahnung_MahnungTriggers.class.php
├── class/mahnung.class.php                     CRUD Mahnvorgang
├── class/mahnungstufe.class.php                CRUD Stufen-Konfig
├── class/mahnungvorschlag.class.php            Vorschlags-Service (Stufenermittlung)
├── class/mahnungcron.class.php                 Cron-Job
├── class/mahnungpdf.class.php                  PDF-Generator (DIN 5008)
├── class/mahnungntfy.class.php                 Ntfy-Wrapper
├── class/actions_mahnung.class.php             Hook-Klasse (invoicecard + thirdpartycard)
├── admin/setup.php                             Setup
├── ajax/createmahnung.php                      Bulk-Mahnung-Erzeugung
├── ajax/sammelbrief.php                        Sammelbrief-PDF-Konkatenation
├── ajax/sendmail.php                           E-Mail-Versand
├── list.php                                    Vorschlagsliste / Archiv
├── card.php                                    Detailansicht
├── sql/llx_mahnung_*.sql                       Schema + Seed
└── langs/{de_DE,en_US}/mahnung.lang
```

## Lizenz

GPL-3.0