From d49bd9ebda4c1b6581bb655bea7b1e86573ea228 Mon Sep 17 00:00:00 2001 From: Eduard Wisch Date: Sun, 10 May 2026 21:37:44 +0200 Subject: [PATCH] Docs: README, CHANGELOG, CLAUDE.md aktualisiert, Version 0.2.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: ODT-Template-System, Widget, Dokumentenmodelle, Template-Variablen, aktualisierter Dateibaum - CHANGELOG.md: Neuer Block [0.2.0] mit allen Aenderungen seit Erstrelease - CLAUDE.md: Projektanweisungen fuer zukuenftige Sessions - modMahnung: Version 0.1.0 → 0.2.0 Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 68 +++++++++++++++++++-------- CLAUDE.md | 28 +++++++++++ README.md | 78 +++++++++++++++++++++++++------ core/modules/modMahnung.class.php | 2 +- 4 files changed, 141 insertions(+), 35 deletions(-) create mode 100644 CLAUDE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 54d3556..54f6757 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,50 @@ # Changelog +## [0.2.0] — 2026-05-10 — ODT-Template-System, Widget, Dokumentenmodelle + +### ODT-Template-System +- Abstrakte Basis-Klasse `ModelePDFMahnung extends CommonDocGenerator` (`core/modules/mahnung/modules_mahnung.php`) +- ODT-Generator `doc_generic_mahnung_odt` mit Stufen-spezifischer Template-Auswahl (mahnung_stufe1/2/3.odt, Fallback mahnung.odt) +- TCPDF-Generator `pdf_standard_mahnung` (refactored aus `mahnungpdf.class.php`) +- `mahnung.class.php`: `generateDocument()` Methode via `commonGenerateDocument()` +- Template-Variablen: Mahnung, Rechnung, Kunde, Bankverbindung, Dolibarr-Standard +- ODT-Template-Upload auf Setup-Seite mit Benennungskonvention-Hinweis + +### Widget +- `box_mahnung_offen`: Offene Kundenrechnungen mit Mahnstufe-Badge (basiert auf box_factures_imp) +- Alle offenen Rechnungen (nicht nur überfällige), Status-Icon wie Original +- Farbige Mahnstufe-Badges (blau/orange/rot) mit Link zur Mahnung-Detailseite +- Strich (—) bei Rechnungen ohne Mahnung + +### Dokumentenliste auf card.php +- Generierte Dokumente zur Mahnung auflisten (aus Rechnungsordner) +- PDF-Vorschau (Lupe), Download-Button +- Modellauswahl-Dropdown bei mehreren aktiven Dokumentenmodellen + +### Setup-Erweiterungen +- Dokumentenmodell-Verwaltung (aktivieren/deaktivieren, Default setzen) +- `admin/templatevars.php`: Referenzseite aller verfügbaren ODT-Template-Variablen +- Link von Setup zur Variablen-Referenz + +### Modul-Descriptor +- `module_parts['models'] = 1` +- Neue Konstanten: `MAHNUNG_ADDON_PDF`, `MAHNUNG_ADDON_PDF_ODT_PATH` +- Document-Model-Registrierung in `init()` (standard_mahnung + generic_mahnung_odt) +- Widget `box_mahnung_offen@mahnung` registriert +- Picto korrigiert: `fa-envelope-open-text` (FA5-Free) + +### Bugfixes +- numero 500037 → 500038 (Kollision mit Eplan behoben) +- `verifCsrf()` entfernt (existiert nicht in Dolibarr, CSRF via `newToken()`) +- `f.statut` → `f.fk_statut` (Dolibarr 22.x Spaltenname) +- `actions_setmoduleoptions.inc.php` vor `llxHeader()` verschoben (ODT-Upload) +- Widget: `require_once mahnung.class.php` an Dateianfang (Fatal Error bei Klassen-Konstanten in SQL) + +### Entfernt +- `class/mahnungpdf.class.php` — Logik in `core/modules/mahnung/doc/pdf_standard_mahnung.modules.php` + +--- + ## [0.1.0] — 2026-05-07 — Erstveröffentlichung (Phase 1–10) ### DB-Schema (Phase 1) @@ -8,7 +53,7 @@ - 3 Default-Stufen werden bei Aktivierung idempotent eingefügt ### Modul-Descriptor (Phase 1) -- numero `500037` (500033–500036 sind durch Bericht belegt), family `financial`, FA-Picto `fa-envelope-open-o` +- numero `500038`, family `financial`, FA-Picto `fa-envelope-open-text` - Modul-Konstanten: `MAHNUNG_BASISZINS`, `MAHNUNG_AUFSCHLAG_B2C`, `MAHNUNG_AUFSCHLAG_B2B`, `MAHNUNG_PAUSCHALE_B2B`, `MAHNUNG_NTFY_TOPIC` - Rechte: `read`, `write`, `send`, `delete`, `setup` - Cron-Job `MahnungCronBuildVorschlag` (täglich, default deaktiviert) @@ -26,14 +71,14 @@ - `list.php` — Vorschlagsliste-UI mit Multi-Select, Filter nach Stufe / Verzugstagen / Kunde, Buttons „Mahnungen erzeugen" und „Sammelbrief" ### PDF-Generator + Erstellen (Phase 4) -- `class/mahnungpdf.class.php` — TCPDF-basierter Generator (DIN-5008 Form A): Adressfenster, Bezugszeichenzeile, Tabelle, Gebührenblock, Verzugszinsen mit Snapshot-Zinssatz, neue Frist, Bankverbindungs-Footer -- PDFs landen in `documents/facture/{ref}/mahnung-{stufe}-{ref-mahn}.pdf` und erscheinen automatisch im Dokumente-Tab der Rechnung +- TCPDF-basierter Generator (DIN-5008 Form A): Adressfenster, Bezugszeichenzeile, Tabelle, Gebührenblock, Verzugszinsen mit Snapshot-Zinssatz, neue Frist, Bankverbindungs-Footer +- PDFs landen in `documents/facture/{ref}/` und erscheinen automatisch im Dokumente-Tab der Rechnung - `ajax/createmahnung.php` — Bulk-Endpoint mit CSRF + Permission-Check, erzeugt Mahnung + PDF, behandelt §288 Abs. 5 Pauschale einmalig pro Rechnung ### Hooks + Trigger (Phase 5) - `core/triggers/interface_99_modMahnung_MahnungTriggers.class.php` — `BILL_PAYED` und `PAYMENT_CUSTOMER_CREATE` setzen offene Mahnungen auf erledigt - `class/actions_mahnung.class.php` — Hook auf Rechnungs- und Kundenkarte: Tab „Mahnungen (n)" mit Badge, Button „Mahnung erstellen" wenn überfällig -- `card.php` — Detailansicht eines Mahnvorgangs mit Storno-Aktion (`formconfirm`-Modal, kein `confirm()`-Dialog) +- `card.php` — Detailansicht eines Mahnvorgangs mit Storno-Aktion (`formconfirm`-Modal) ### E-Mail + Sammelbrief (Phase 6) - `ajax/sendmail.php` — sendet Mahnung-PDF via `CMailFile` an die Kunden-Mail; Subject/Body mit Platzhaltern aus Stufen-Konfig @@ -43,20 +88,5 @@ - GlobalNotify: Cron sendet zusätzlich `actionRequired`-Notification ins Dolibarr-UI (wenn Modul aktiv) - Tab „Mahnungen" auf Kundenkarte (`thirdpartycard`) zusätzlich zur Rechnungskarte -### Audit + Doku (Phase 9) -- Alle in PHP referenzierten Sprach-Keys in de_DE und en_US vorhanden -- Alle SQL-Statements parametrisiert über `(int)`-Cast oder `db->escape()` -- Alle AJAX-Endpoints mit CSRF + Permission-Check -- README + CHANGELOG vollständig - ### Pipeline (Phase 10) - `.forgejo/workflows/deploy.yml` — Deploy auf `/mnt/appdata/firma/dolibarr-202509/modules/mahnung` bei Push auf `main` mit `[deploy]` oder Tag `v*`, Ntfy-Notify auf Topic `vk-builds` - -### Verifizierte Fundamente -- DB-Schema in `dolibarr_test` (192.168.155.11) angelegt, Indizes + Seed-Daten korrekt -- PHP-Lint sauber für alle 16 PHP-Dateien - -### Bekannte Lücken / Folge-Tasks -- ODT-Vorlagen (Pfad in Setup hinterlegbar) für späteren Ausbau — nicht im Erst-Release -- B2C/B2B-Erkennung pragmatisch via `tva_intra` — Setup-Toggle für andere Erkennungsregeln folgt -- Halbjährliche Basiszins-Erinnerung (1.1./1.7.) per Cron-Reminder noch offen diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b7ce7c7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,28 @@ +# CLAUDE.md — Mahnung-Modul + +## Projekt +Dolibarr Custom-Modul: 3-stufiges Mahnwesen nach BGB §288. + +## Technisches +- **numero**: 500038 (NICHT ändern — 500037 ist Eplan) +- **Deploy**: nur via Pipeline (`[deploy]` in Commit-Message), NIEMALS manuell kopieren +- **Prod-Pfad**: /mnt/appdata/firma/dolibarr-202509/modules/mahnung/ +- **Lokal**: Symlink /var/www/dolibarr/custom/mahnung → repo/ +- **Test-DB**: dolibarr_test auf 192.168.155.11 + +## Dokumentenmodell-System +- `commonGenerateDocument()` fügt automatisch `doc_`/`pdf_` Prefix hinzu +- DB-Einträge in `llx_document_model.nom` OHNE Prefix speichern +- `actions_setmoduleoptions.inc.php` MUSS vor `llxHeader()` stehen (Upload) +- ODT-Templates: mahnung_stufe1.odt, mahnung_stufe2.odt, mahnung_stufe3.odt, mahnung.odt (Fallback) + +## Widget +- `box_mahnung_offen` basiert 1:1 auf `box_factures_imp.php` (Standard-Widget) +- Zeigt ALLE offenen Rechnungen, nicht nur überfällige +- Mahnstufe-Badge nur wenn Mahnung existiert, sonst Strich + +## Dolibarr-Versionshinweise +- `f.fk_statut` statt `f.statut` (seit Dolibarr 22.x) +- `verifCsrf()` existiert nicht — CSRF via `newToken()` + GETPOST('token') +- `dol_mkdir()` gibt 0 zurück wenn Verzeichnis bereits existiert (nicht false) +- `dol_dir_list()` gibt `fullname` zurück (nicht `fullpath`) diff --git a/README.md b/README.md index a54ec34..0dcd71c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # 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. +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- und ODT-Mahnschreiben, E-Mail-Versand, Sammelbrief, Trigger auf Zahlungseingang. ## Status -Version **0.1.0** — Erstveröffentlichung, alle 10 Phasen der ROADMAP.md abgeschlossen. +Version **0.2.0** — ODT-Template-System, Widget, Dokumentenmodell-Verwaltung. ## Features @@ -16,17 +16,23 @@ Version **0.1.0** — Erstveröffentlichung, alle 10 Phasen der ROADMAP.md abges | 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 | +| PDF-Mahnschreiben (DIN 5008) | Standard-TCPDF-Generator `pdf_standard_mahnung` | +| ODT-Mahnschreiben (je Stufe) | ODT-Template-Generator `doc_generic_mahnung_odt` mit Stufen-Auswahl | +| Dokumentenmodell-Verwaltung | Setup-Seite: Modelle aktivieren, Default wählen, ODT-Templates hochladen | +| Template-Variablen-Referenz | `admin/templatevars.php` — alle verfügbaren ODT-Variablen | +| Dokumentenliste auf Mahnungs-Karte | Vorschau (Lupe), Download, Modellauswahl | +| Bulk-Erstellung + Sammelbrief | 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` | +| Widget: Offene Rechnungen mit Mahnstufe | `box_mahnung_offen` — wie Standard-Widget, plus Mahnstufe-Badge mit Link | ## Voraussetzungen - Dolibarr ≥ 19 - PHP ≥ 7.4 - TCPDF (Dolibarr-Standard) für PDF +- Optional: ODTPHP (Dolibarr-Standard) für ODT-Templates - 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) @@ -40,11 +46,47 @@ git clone https://git.data-it-solution.de/data/mahnung.git \ 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. +Bei Aktivierung werden `llx_mahnung_mahnung` und `llx_mahnung_stufe` angelegt; drei Default-Stufen werden idempotent eingefügt. Dokumentenmodelle (`standard_mahnung`, `generic_mahnung_odt`) werden in `llx_document_model` registriert. -Nach Aktivierung in **Setup → Mahnwesen Einstellungen** den Basiszins prüfen und die Stufen-Texte (PDF-Intro, E-Mail-Body) anpassen. +Nach Aktivierung in **Setup → Mahnwesen Einstellungen**: +1. Basiszins prüfen +2. Stufen-Texte (PDF-Intro, E-Mail-Body) anpassen +3. Dokumentenmodell wählen und ggf. ODT-Templates hochladen +4. Cron-Job `MahnungCronBuildVorschlag` aktivieren -Den Cron-Job `MahnungCronBuildVorschlag` aktivieren, sobald die Setup-Werte stimmen. +## ODT-Templates + +Templates werden unter **Setup → Mahnwesen Einstellungen → Dokumentenmodelle** hochgeladen. + +### Dateinamen-Konvention + +| Dateiname | Verwendung | +|---|---| +| `mahnung_stufe1.odt` | Zahlungserinnerung (Stufe 1) | +| `mahnung_stufe2.odt` | 1. Mahnung (Stufe 2) | +| `mahnung_stufe3.odt` | Letzte Mahnung (Stufe 3) | +| `mahnung.odt` | Fallback für alle Stufen | + +### Verfügbare Template-Variablen (Auswahl) + +| Variable | Beispiel | +|---|---| +| `{mahnung_ref}` | MAHN2026-0001 | +| `{mahnung_stufe}` | 1 | +| `{mahnung_stufe_label}` | Zahlungserinnerung | +| `{mahnung_date}` | 10.05.2026 | +| `{mahnung_betrag_offen}` | 131,34 | +| `{mahnung_mahngebuehr}` | 5,00 | +| `{mahnung_verzugszinsen}` | 1,23 | +| `{mahnung_summe}` | 137,57 | +| `{mahnung_kundentyp}` | B2C | +| `{facture_ref}` | IN2604-0036 | +| `{facture_total_ttc}` | 131,34 | +| `{company_name}` | Kundenname | +| `{mycompany_name}` | Eigene Firma | +| `{mahnung_bank_iban}` | DE89... | + +Vollständige Liste: **Setup → Mahnwesen → Verfügbare Template-Variablen** ## Rechte @@ -64,9 +106,9 @@ Den Cron-Job `MahnungCronBuildVorschlag` aktivieren, sobald die Setup-Werte stim | `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_ADDON_PDF` | `standard_mahnung` | Standard-Dokumentenmodell | +| `MAHNUNG_ADDON_PDF_ODT_PATH` | `DOL_DATA_ROOT/doctemplates/mahnung` | ODT-Template-Verzeichnis | | `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 @@ -84,7 +126,7 @@ list.php (Vorschlagsliste) | |--> User waehlt aus + klickt "Mahnungen erzeugen" | -> ajax/createmahnung.php berechnet Gebuehr + Verzugszinsen, - | persistiert llx_mahnung_mahnung, generiert PDF + | persistiert llx_mahnung_mahnung, generiert PDF/ODT | |--> Alternativ "Sammelbrief erzeugen" | -> ajax/sammelbrief.php generiert + konkateniert PDFs @@ -99,21 +141,27 @@ Zahlungseingang (BankImport / Manual) ``` mahnung/ -├── core/modules/modMahnung.class.php Descriptor, Rechte, Cron, Hooks +├── core/modules/modMahnung.class.php Descriptor, Rechte, Cron, Hooks, Models +├── core/modules/mahnung/ +│ ├── modules_mahnung.php Abstrakte Basis ModelePDFMahnung +│ └── doc/ +│ ├── pdf_standard_mahnung.modules.php TCPDF-Generator (DIN 5008) +│ └── doc_generic_mahnung_odt.modules.php ODT-Template-Generator ├── core/triggers/interface_99_modMahnung_MahnungTriggers.class.php -├── class/mahnung.class.php CRUD Mahnvorgang +├── core/boxes/box_mahnung_offen.php Widget: Offene Rechnungen + Mahnstufe +├── class/mahnung.class.php CRUD Mahnvorgang + generateDocument() ├── 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 +├── admin/setup.php Setup + Dokumentenmodell-Verwaltung +├── admin/templatevars.php Template-Variablen-Referenz ├── 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 +├── card.php Detailansicht + Dokumentenliste ├── sql/llx_mahnung_*.sql Schema + Seed └── langs/{de_DE,en_US}/mahnung.lang ``` diff --git a/core/modules/modMahnung.class.php b/core/modules/modMahnung.class.php index 6da907f..242de86 100644 --- a/core/modules/modMahnung.class.php +++ b/core/modules/modMahnung.class.php @@ -54,7 +54,7 @@ class modMahnung extends DolibarrModules $this->editor_name = 'Alles Watt laeuft'; $this->editor_url = ''; - $this->version = '0.1.0'; + $this->version = '0.2.0'; $this->const_name = 'MAIN_MODULE_'.strtoupper($this->name);