From 5e91c87c99e43e326309ef9e56f43b407c5c251f Mon Sep 17 00:00:00 2001 From: Eduard Wisch Date: Mon, 11 May 2026 13:28:36 +0200 Subject: [PATCH] Docs: README + CLAUDE.md auf Stand nach Phasen 1-6 bringen README: - Feature-Tabelle um Phase 1-6 erweitert: Select2-Filter, Versand-Erfassung, Sendebeleg-Upload, Tracking-Patterns + Live-Vorschau, Beleg-Scan, Versand-Reminder Cron, Bonitaets-Workflow. - Neue Sektionen Datenbank, AJAX-Endpoints, Hooks & Trigger. - MAHNUNG_VERSAND_REMINDER_DAYS zu Konstanten ergaenzt. - Workflow-ASCII-Diagramm aktualisiert: Filter + Versand-Block + Belege-Scan + Uneinbringlich-Pfad + Steuer-Modul-Kompatibilitaet. - Dateibaum: neue Files (mahnungtrackingpattern, tracking_patterns admin, regex_preview ajax) + Methoden in actions_mahnung dokumentiert. CLAUDE.md: - Schema-Migration-Sektion (migrateVersandFelder beim Setup-Aufruf). - Hooks-Stolperfallen: completeTabsHead mehrfach-Trigger. - Filter-Syntax-Stolperfallen: USC-Syntax bei select_company, search_socid=-1 als "nichts ausgewaehlt". - Pipeline-Stolperfallen: ${{ commit_message }} via env: durchreichen. - Versand & Bonitaet Sektion mit Kreuzverweisen auf KB #601-#609. - Dolibarr-Versionshinweise um formconfirm-Textarea ergaenzt. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 30 ++++++++++++++- README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 125 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b7ce7c7..daff55e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # CLAUDE.md — Mahnung-Modul ## Projekt -Dolibarr Custom-Modul: 3-stufiges Mahnwesen nach BGB §288. +Dolibarr Custom-Modul: 3-stufiges Mahnwesen nach BGB §288 + Versand-Tracking + Forderungsausfall-Workflow. ## Technisches - **numero**: 500038 (NICHT ändern — 500037 ist Eplan) @@ -9,6 +9,13 @@ Dolibarr Custom-Modul: 3-stufiges Mahnwesen nach BGB §288. - **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 +- **Forgejo-Repo**: data/mahnung (NICHT data-it/ — historisch, soll bleiben) + +## Schema-Migration +- `modMahnung::migrateVersandFelder()` läuft automatisch beim Setup-Page-Aufruf +- Idempotent via `SHOW COLUMNS LIKE` → fehlende Spalten via `ALTER TABLE ADD COLUMN` +- Default-Tracking-Patterns werden via `MahnungTrackingPattern::seedDefaults()` geseedet (Check: `COUNT(*) > 0` → skip) +- **Nach Deploy: User muss Setup-Page einmal aufrufen**, sonst fehlen die neuen Spalten ## Dokumentenmodell-System - `commonGenerateDocument()` fügt automatisch `doc_`/`pdf_` Prefix hinzu @@ -21,8 +28,29 @@ Dolibarr Custom-Modul: 3-stufiges Mahnwesen nach BGB §288. - Zeigt ALLE offenen Rechnungen, nicht nur überfällige - Mahnstufe-Badge nur wenn Mahnung existiert, sonst Strich +## Hooks-Stolperfallen +- **`completeTabsHead`** wird bei jedem Aufruf von `complete_head_from_modules()` getriggert — pro Karte mehrfach (core + external + remove). Filter auf `mode=add` + `filterorigmodule=external`, sonst doppelter Tab. (KB #601) +- Hook-Kontexte: `invoicecard`, `thirdpartycard`, `ordercard` — letztere für Bonitäts-Warnings. + +## Filter-Syntax-Stolperfallen +- **`$form->select_company($selected, $htmlname, $filter, ...)`**: der `$filter`-Parameter erwartet **USC-Syntax** `(feld:operator:wert)`, NICHT plain SQL. Beispiel B2C: `(s.tva_intra:is:NULL) OR (s.tva_intra:=:'')`. Sonst SQL-Syntax-Error + 500. (KB #602) +- **`search_socid=-1`** wird von `select_company` als "nichts ausgewählt" geliefert → im Filter-Check `> 0` statt `!empty()` nutzen. + +## Pipeline-Stolperfallen +- **`${{ github.event.head_commit.message }}` NIE direkt in `run:`-Skript interpolieren** — bei Sonderzeichen (Klammern, Backticks) bricht Bash. Immer via `env:` durchreichen. (KB #603) +- `[deploy]`-Tag im Commit nötig, sonst kein Auto-Deploy. + +## Versand & Bonität (Phase 6) +- Versand-Felder: `date_versand`, `versandweg`, `tracking_nr`, `tracking_provider` an `llx_mahnung_mahnung` +- Tracking-URLs aus DB (`llx_mahnung_trackingpattern`) via `MahnungTrackingPattern::urlFor()`, Fallback: `Mahnung::trackingUrl()` (hardcoded) +- Beleg-Upload: `formfile->showdocuments('mahnung', $ref, $filedir, ...)` — `$conf->mahnung->dir_output` wird von Dolibarr automatisch gesetzt (KB #605), kein Custom-Setup nötig +- Beleg-Scan: `pdftotext` ist im `90-Dolibarr-Prod-Custom`-Container drin (`/usr/bin/pdftotext`); Pattern-Match via `MahnungTrackingPattern::detectFromText()` +- Uneinbringlich-Klassifikation: `Facture::setCanceled($user, CommonInvoice::CLOSECODE_BADDEBT, $note)` → setzt `fk_statut=3` + `close_code='badcustomer'` (KB #606) +- Steuer-Modul kompatibel: EÜR ignoriert (liest nur `llx_paiement`), UStVA filtert `fk_statut IN (1,2)` automatisch (KB #607) + ## 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`) +- `$form->formconfirm()` unterstützt textarea-Feld via `$formquestion`-Array (KB #609) diff --git a/README.md b/README.md index 0dcd71c..522533f 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,13 @@ Mahnwesen-Modul für Dolibarr ERP: tägliche Vorschlagsliste überfälliger Rech ## Status -Version **0.2.0** — ODT-Template-System, Widget, Dokumentenmodell-Verwaltung. +Version **0.2.0 + Phasen 1-6 (Unreleased)** — UX-Vorschlagsliste, Versand-Erfassung, Sendebeleg-Upload, konfigurierbare Tracking-Patterns mit Live-Vorschau, Beleg-Scan via pdftotext, Versand-Reminder, Bonitäts-Workflow + Uneinbringlich-Klassifikation. ## Features | Feature | Implementierung | |---|---| -| Tägliche Vorschlagsliste überfälliger Rechnungen | Cron `MahnungCronBuildVorschlag` (default deaktiviert) | +| Tägliche Vorschlagsliste überfälliger Rechnungen | Cron `MahnungCronBuildVorschlag` | | 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` | @@ -24,8 +24,20 @@ Version **0.2.0** — ODT-Template-System, Widget, Dokumentenmodell-Verwaltung. | 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 | +| Tab "Mahnungen (n)" auf Rechnungs- + Kundenkarte | Hook `completeTabsHead` (filtert auf add/external) | +| Widget: Offene Rechnungen mit Mahnstufe | `box_mahnung_offen` | +| **Vorschlagsliste-Filter** (Mahnstufe, Tage Verzug, Mindestbetrag, Kundentyp B2B/B2C, Kunden-Select2 mit Ajax) | `list.php` — Kundentyp-Wechsel filtert das Kunden-Dropdown sofort per Auto-Submit | +| **Kontakt-Spalte** in Vorschlagsliste (Telefon-/Mail-Icons mit Direktlink) | tel:/mailto: aus `llx_societe.phone/email` | +| **Versand-Erfassung** pro Mahnung (Datum, Versandweg, Sendungsnummer, Tracking-Provider) | `card.php` Versand-Block; setzt automatisch Status auf VERSENDET | +| **Tracking-Deep-Links** für DHL, DPAG, DPD, Hermes, UPS | konfigurierbar via Tracking-Pattern-Tabelle | +| **Sendebeleg-Upload** pro Mahnung | Dolibarrs `formfile->showdocuments('mahnung', ...)` → `DOL_DATA_ROOT/mahnung//` | +| **Konfigurierbare Tracking-Patterns** (Regex + URL-Template, Priorität, Aktivierung) | `admin/tracking_patterns.php` CRUD + Live-Vorschau | +| **Live-Regex-Vorschau** (Treffer + URL-Preview während Eingabe) | `ajax/regex_preview.php` (debounced 300ms, ReDoS-Schutz) | +| **Beleg-Scan** (pdftotext + Pattern-Matching → Sendungsnummer-Vorschlag) | Button "Belege scannen" auf `card.php` | +| **Versand-Reminder** (Mahnung > N Tage unversendet → Ntfy-Push) | Cron `MahnungCronVersandReminder`, Schwellenwert via `MAHNUNG_VERSAND_REMINDER_DAYS` | +| **Bonitäts-Box auf Kundenkarte** (Anzahl + Summe + letztes Datum der `badcustomer` abandoned Rechnungen) | Hook `tabContentViewThirdparty` | +| **Bonitäts-Warning** bei Auftrag-/Rechnungs-Karte | Hook `formObjectOptions` (invoicecard + ordercard) | +| **"Als uneinbringlich klassifizieren"-Button** auf Mahnung Stufe 3 | Bestätigungs-Dialog mit Begründung → `Facture::setCanceled($user, CommonInvoice::CLOSECODE_BADDEBT, $note)` | ## Voraussetzungen @@ -109,11 +121,47 @@ Vollständige Liste: **Setup → Mahnwesen → Verfügbare Template-Variablen** | `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_VERSAND_REMINDER_DAYS` | `2` | Schwelle (Tage) für Versand-Reminder Ntfy-Push | + +## Datenbank + +| Tabelle | Zweck | +|---|---| +| `llx_mahnung_mahnung` | Mahnvorgänge — inkl. Versand-Felder `date_versand`, `versandweg`, `tracking_nr`, `tracking_provider` (idempotente Migration via `migrateVersandFelder()` beim Setup-Aufruf) | +| `llx_mahnung_stufe` | Stufen-Konfiguration (Stufe 1/2/3 mit Fristen, Gebühren, Templates) | +| `llx_mahnung_trackingpattern` | Konfigurierbare Tracking-Regex + URL-Template pro Provider, Default-Seed mit DHL/DPAG/DPD/Hermes/UPS | + +## AJAX-Endpoints + +| Endpoint | Zweck | Parameter | Auth | +|---|---|---|---| +| `ajax/createmahnung.php` | Bulk-Mahnung-Erzeugung | `facture_ids[]`, `stufe`, `token` | `mahnung.write` | +| `ajax/sammelbrief.php` | Sammelbrief-PDF | `facture_ids[]`, `token` | `mahnung.send` | +| `ajax/sendmail.php` | E-Mail-Versand | `mahnung_id`, `token` | `mahnung.send` | +| `ajax/regex_preview.php` | Live-Vorschau für Tracking-Patterns | `regex`, `sample`, `url_template` (POST) | `mahnung.setup` oder Admin | + +## Hooks & Trigger + +**Hook-Klasse:** `class/actions_mahnung.class.php` — registriert für `invoicecard`, `thirdpartycard`, `ordercard`. + +| Hook | Zweck | +|---|---| +| `addMoreActionsButtons` | "Mahnung erstellen"-Button auf Rechnungs-Karte | +| `completeTabsHead` | Tab "Mahnungen (n)" — filtert auf `mode=add` + `filterorigmodule=external` (sonst doppelter Tab, siehe KB #601) | +| `tabContentViewThirdparty` | Bonitäts-Warnbox auf Kundenkarte wenn `badcustomer` abandoned Rechnungen existieren | +| `formObjectOptions` | Bonitäts-Warning bei Auftrag-/Rechnungs-Karten | + +**Trigger:** `core/triggers/interface_99_modMahnung_MahnungTriggers.class.php` +- `BILL_PAYED` + `BILL_VALIDATE` + `PAYMENT_CUSTOMER_CREATE` → setzt offene Mahnungen auf `STATUS_ERLEDIGT` + +**Cron-Jobs:** +- `MahnungCronBuildVorschlag` — täglich, Vorschlagsliste aufbauen + Ntfy-Push +- `MahnungCronVersandReminder` — täglich, Reminder für unversendete Mahnungen ## Workflow ``` -Cron 06:00 +Cron 06:00 (MahnungCronBuildVorschlag) | |--> ueberfaellige Rechnungen einsammeln |--> Stufe ermitteln (Stufe 1 ab frist_tage Verzug, @@ -123,6 +171,9 @@ Cron 06:00 | v list.php (Vorschlagsliste) + | Filter: Mahnstufe, min. Verzug, min. Betrag, Kundentyp (B2B/B2C), Kunde (Select2) + | Spalten: Rechnung, Kunde, Kontakt (tel/mail), Typ, Faelligkeit, Verzug, + | Betrag, letzte Mahnung, vorgeschlagene Stufe | |--> User waehlt aus + klickt "Mahnungen erzeugen" | -> ajax/createmahnung.php berechnet Gebuehr + Verzugszinsen, @@ -131,10 +182,33 @@ list.php (Vorschlagsliste) |--> Alternativ "Sammelbrief erzeugen" | -> ajax/sammelbrief.php generiert + konkateniert PDFs | + v +card.php (Mahnung-Detailansicht) + | Documents: generierte PDFs + Modellauswahl + Regenerate + | Versand: Datum, Versandweg, Sendungsnummer, Tracking-Provider -> Deep-Link + | Sendebelege: Upload (formfile->showdocuments), Scan-Button + | Aktionen: Stornieren | Als uneinbringlich klassifizieren (nur Stufe 3) + | +Cron 06:00 (MahnungCronVersandReminder) + |--> Mahnungen mit Status=ERSTELLT > N Tage unversendet -> Ntfy-Push + | Zahlungseingang (BankImport / Manual) | v Trigger BILL_PAYED / PAYMENT_CUSTOMER_CREATE |--> alle offenen Mahnvorgaenge zur Rechnung -> status=erledigt + | +Endgueltig uneinbringlich (Mahnbescheid + Vollstreckung erfolglos) + | + v Stufe-3-Mahnung -> Button "Als uneinbringlich klassifizieren" + |--> Facture::setCanceled($user, CLOSECODE_BADDEBT, $note) + | -> fk_statut=3 (ABANDONED), close_code='badcustomer' + | -> Mahnung wird storniert, Begruendung in note_private + |--> Auf Kundenkarte erscheint rote Bonitaets-Warnbox + |--> Beim Anlegen neuer Auftraege/Rechnungen: Warning-Banner + | +Steuerlich (Steuer-Modul): + |--> EÜR ignoriert (liest llx_paiement, keine Zahlung = keine Einnahme) + |--> UStVA filtert fk_statut IN (1,2) -> abandoned automatisch ausgeschlossen ``` ## Dateibaum @@ -142,6 +216,7 @@ Zahlungseingang (BankImport / Manual) ``` mahnung/ ├── core/modules/modMahnung.class.php Descriptor, Rechte, Cron, Hooks, Models +│ (migrateVersandFelder + Pattern-Seed) ├── core/modules/mahnung/ │ ├── modules_mahnung.php Abstrakte Basis ModelePDFMahnung │ └── doc/ @@ -150,18 +225,28 @@ mahnung/ ├── core/triggers/interface_99_modMahnung_MahnungTriggers.class.php ├── core/boxes/box_mahnung_offen.php Widget: Offene Rechnungen + Mahnstufe ├── class/mahnung.class.php CRUD Mahnvorgang + generateDocument() +│ + setVersand + trackingUrl + defaultProviderForWeg ├── class/mahnungstufe.class.php CRUD Stufen-Konfig -├── class/mahnungvorschlag.class.php Vorschlags-Service (Stufenermittlung) -├── class/mahnungcron.class.php Cron-Job +├── class/mahnungvorschlag.class.php Vorschlags-Service (Stufenermittlung, +│ kundentyp/min_betrag-Filter, soc_phone/email) +├── class/mahnungtrackingpattern.class.php CRUD Tracking-Patterns + detectFromText +├── class/mahnungcron.class.php buildVorschlagsliste + versandReminder ├── class/mahnungntfy.class.php Ntfy-Wrapper -├── class/actions_mahnung.class.php Hook-Klasse (invoicecard + thirdpartycard) -├── admin/setup.php Setup + Dokumentenmodell-Verwaltung +├── class/actions_mahnung.class.php Hook-Klasse: +│ - addMoreActionsButtons (invoicecard) +│ - completeTabsHead (invoice+thirdparty) +│ - tabContentViewThirdparty (Bonitaets-Box) +│ - formObjectOptions (invoice+ordercard Warning) +├── admin/setup.php Setup + Dokumentenmodell + Auto-Migration ├── admin/templatevars.php Template-Variablen-Referenz +├── admin/tracking_patterns.php CRUD + Live-Vorschau fuer Tracking-Patterns ├── 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 + Dokumentenliste +├── ajax/regex_preview.php Live-Vorschau-Endpoint fuer Pattern-Setup +├── list.php Vorschlagsliste / Archiv (Select2-Filter) +├── card.php Detailansicht: Versand, Belege, Tracking, +│ Uneinbringlich-Workflow ├── sql/llx_mahnung_*.sql Schema + Seed └── langs/{de_DE,en_US}/mahnung.lang ```