Mahnwesen — Einstellungen

Zweck

Diese Seite konfiguriert das Mahnwesen: ob es aktiv ist, über welche Mailbox Mahnungen versendet werden, ob ein täglicher Auto-Lauf läuft und wie die Mahnstufen definiert sind. Die operative Durchführung (Mahnläufe starten, Mahnungen versenden) findet auf der Seite Mahnläufe statt.

Voraussetzungen

- Berechtigung `view:FE_PaymentReminder` + `update:PaymentReminder`. - Eine konfigurierte Mailbox (für den Versand), siehe [System-Mail-Einstellungen](/settings/system-mail).

Berechtigungen (CASL)

Action	Subject	Wirkung
view	FE_PaymentReminder	Einstellungsseite aufrufbar
view	PaymentReminder	Einstellungen und Stufen lesen
update	PaymentReminder	Einstellungen und Mahnstufen ändern

Globale Einstellungen

Die Einstellungen werden im Settings-Modell unter keyGroup = paymentReminder gespeichert und automatisch gespeichert (debounced, ca. 800 ms nach der letzten Änderung).

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfüllen	Voraussetzung
enabled	ja	Boolean	Mahnwesen global aktiv?	schaltet Vorschau, manuelle Läufe und Auto-Lauf frei	—
senderMailboxId	konditional	UUID (Mailbox)	Absender-Mailbox für Mahn-E-Mails	ohne diese Mailbox schlägt jeder Versand fehl (failed)	Mailbox muss existieren
autoDailyRun	nein	Boolean	täglicher Auto-Lauf aktiv?	erzeugt täglich automatisch einen Mahnlauf	enabled = true
runTime	nein	String HH:mm	Uhrzeit des Auto-Laufs (Default 06:00)	legt die Cron-Zeit fest (Zeitzone Europe/Berlin)	greift erst nach Server-Neustart

Mahnstufen

Pro Mahnstufe (PaymentReminderLevel) lassen sich folgende Felder über PATCH /payment-reminder-levels/:id pflegen:

Feldname	Datentyp	Beschreibung	Wirkung
level	Integer	Stufennummer (1, 2, 3 …)	Eskalationsreihenfolge; je Stufe genau ein Eintrag
active	Boolean	Stufe aktiv?	nur aktive Stufen werden bei Läufen berücksichtigt
daysOverdue	Integer	Tage nach Fälligkeit	ab dieser Überfälligkeit greift die Stufe (z. B. 14 / 30 / 60)
surchargeAmount	Decimal(10,2)	Mahngebühr (€)	wird in der E-Mail ausgewiesen, nicht gebucht
attachInvoices	Boolean	Rechnungs-PDFs anhängen?	hängt die betroffenen Belege an die Mahn-E-Mail
autoSend	Boolean	im Auto-Lauf direkt senden?	beim täglichen Lauf wird diese Stufe sofort versendet, sonst bleibt sie pending

`surchargeAmount` ist ein reiner Anzeigewert in der Mahn-E-Mail. Es entsteht **keine** Buchung und **kein** zusätzlicher offener Posten. Wer Mahngebühren tatsächlich fordern will, muss sie separat als Beleg erfassen.

E-Mail-Texte (Templates)

Die Mahn-E-Mail-Texte stammen aus Textbausteinen mit emailCategory = dunning; die Position entspricht der Mahnstufe. Platzhalter werden im Format {{ variable }} ersetzt. Ist für eine Stufe kein Template hinterlegt, verwendet das System einen deutschen Standardtext.

Verknüpfungen zu anderen Modulen

• Mahnläufe — operative Durchführung und Datenmodell.
• System-Mail-Einstellungen — Mailboxen für den Versand.
• Offene Posten — Datenbasis der Mahnungen.

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/payment-reminder-settings	Einstellungen lesen	view PaymentReminder
PATCH	/payment-reminder-settings	Einstellungen ändern	update PaymentReminder
GET	/payment-reminder-levels	Mahnstufen auflisten	view PaymentReminder
PATCH	/payment-reminder-levels/:id	Mahnstufe ändern	update PaymentReminder

Versionshinweise

• 2026-06-11: Initiale Veröffentlichung — Mahnwesen-Einstellungen (globale Aktivierung, Absender-Mailbox, Auto-Lauf, Mahnstufen). Verifiziert an SettingsPaymentReminderPage.tsx, paymentReminder.router.ts und paymentReminder.service.ts.