Finanzmanager/docs/nebenmodule.md

# Nebenmodule und Zahlungsverkehr

Was in Phase 7 dazugekommen ist: Buchungsvorlagen, regelmäßige Buchungen mit
Finanzkalender, Erinnerungen, Adressen, Verträge, Sparziele, Kredite und der
Zahlungsverkehr.

## Buchungsvorlagen

Eine Vorlage ist eine fertige Buchung ohne Datum. Sie kommt aus dem QIF
(`!Type:Memorized` – im Beispielexport 579 Stück, vom FinanzManager automatisch gemerkt)
oder entsteht aus einer vorhandenen Buchung.

**Splitzeilen werden mitskaliert.** Weicht der Betrag beim Buchen von dem der Vorlage ab,
ziehen die Splitzeilen im gleichen Verhältnis mit; die letzte bekommt den Rest, damit die
Summe auf den Cent zum Buchungsbetrag passt. Ohne das ließe sich eine Vorlage mit Splits
nur zu ihrem ursprünglichen Betrag buchen.

Die Liste sortiert nach Häufigkeit: Wer eine Vorlage sucht, sucht meist eine, die er schon
oft gebraucht hat.

Beim Import entsteht der **Name** aus Empfänger und Betrag – die QIF-Sektion führt keinen.
Kommt derselbe Name mehrfach vor, zählt ein Zähler hoch, statt Vorlagen stillschweigend zu
verschlucken.

## Regelmäßige Buchungen

Jede Reihe führt ihre **nächste Fälligkeit** mit sich. Der Fälligkeitslauf holt, was
ansteht, bucht es und schreibt das Datum fort. Eine Tabelle vorausberechneter Termine gibt
es bewusst nicht: Sie wäre bei jeder Änderung neu zu erzeugen.

Zwei Betriebsarten:

* **automatisch** – wird ohne Rückfrage gebucht. Für Miete und Gehalt, wo Betrag und
  Termin feststehen.
* **auf Bestätigung** – wird nur gemeldet und wartet auf Knopfdruck. Für alles, dessen
  Betrag schwankt.

Unabhängig davon legt **automatisch abgleichen** (Vorgabe: eingeschaltet) fest, ob die
entstandene Buchung gleich als abgeglichen markiert wird. Die Übersicht zeigt den Schalter
in der Spalte „Abgleichen“.

Der Lauf ist gutmütig gegenüber langen Pausen: Liegen mehrere Termine zurück, wird **jeder
einzeln** gebucht, nicht einer für alle – nur so stimmen die Monatssummen. Nach dem Buchen
rückt die Fälligkeit so weit vor, bis sie in der Zukunft liegt.

In einen **abgeschlossenen Monat** wird nicht hineingebucht: Die Reihe bleibt stehen und
meldet sich, statt den ganzen Lauf mit einer Ausnahme abzubrechen.

*Überspringen* rückt vor, ohne zu buchen – für den Monat, in dem die Zahlung einmal
ausgesetzt wurde.

## Finanzkalender

Zusammengetragen aus vier Quellen: fällige regelmäßige Buchungen, offene Erinnerungen,
ablaufende Kündigungsfristen und terminierte Überweisungen. Alles gerechnet, nichts
gespeichert – eine Änderung an einer Reihe wirkt sich sofort aus.

Überfälliges bleibt sichtbar und wird markiert, statt aus der Liste zu fallen.

## Adressen und IBAN-Prüfung

Das Adressbuch speist die Empfängerauswahl im Zahlungsverkehr. **IBANs werden geprüft**
(ISO 13616: Länge je Land, Prüfziffer modulo 97). Das fängt Zahlendreher ab, bevor eine
Überweisung hinausgeht – die häufigste und ärgerlichste Fehlerquelle im Zahlungsverkehr.

Gerechnet wird stückweise mit `%` statt mit `bcmod`: Die BC-Erweiterung ist keine
Standardausstattung, und ein Modulo über sieben Ziffern lange Blöcke kommt ohne sie aus.

**Adressverwaltung.** Eine eigene Kachel in der Verwaltung führt zur Adressliste
(`/vertraege/adressen`, weiter über `VertraegeController` gepflegt) – neben, nicht nur
innerhalb der Verträge-Kachel: Das Adressbuch bedient auch den Zahlungsverkehr, der mit
Verträgen nichts zu tun hat. Zu jeder Adresse klappt ein `<details>`-Element ihre letzten
Buchungen auf, kontenübergreifend nach dem exakten Empfängernamen gesucht
(`Buchung::letzteFuerEmpfaenger()`) – die Buchung führt kein Fremdschlüsselfeld auf die
Adresse, nur den Freitext-Empfänger.

**Typeahead im Zahlungsverkehr.** Die Empfängerauswahl (`<select data-adressauswahl>`) trägt
zusätzlich `data-kombobox` und wird wie die Kategorie im Kontoblatt (`kombobox.js`, siehe
`docs/`-Test 35) zu einem Eingabefeld mit gefilterter Liste. Die Auswahl füllt Name, IBAN und
BIC; geändert werden darf danach alles.

**Der Empfänger landet wirklich im Adressbuch**, wenn beim Erfassen einer Überweisung
„Empfänger ins Adressbuch übernehmen“ angekreuzt ist – `ZahlungsverkehrController::anlegen()`
ruft dafür `Adresse::anlegen()` auf, nachdem der Zahlungsauftrag erfolgreich angelegt wurde;
gibt es die Adresse schon, bleibt der Fehler von `Adresse::anlegen()` (Duplikat) ohne Wirkung.

## Verträge

Der Nutzen liegt in der **Kündigungsfrist**: Die Übersicht zeigt, bis wann gekündigt sein
muss, damit sich ein Vertrag nicht stillschweigend verlängert. Verträge, deren Frist in den
nächsten 90 Tagen abläuft, stehen oben auf der Seite und im Finanzkalender.

Der **Jahresbetrag** rechnet verschieden getaktete Verträge vergleichbar: monatlich × 12,
vierteljährlich × 4 und so fort.

Ein Vertrag kann mit einer regelmäßigen Buchung verbunden sein, die seine Zahlung erledigt.

## Sparziele

Der erreichte Stand kommt **aus dem Kontosaldo**, nicht aus einem eigenen Zähler – ein
zweiter, gepflegter Wert liefe früher oder später von den Buchungen weg. Der Startbetrag
zieht ab, was zu Beginn schon auf dem Konto lag.

Zum Zieldatum rechnet die Anwendung aus, welche Monatsrate nötig wäre, um den Termin noch
zu halten.

Der Fortschrittsbalken ist ein `<progress>`-Element: Ein eigener Balken bräuchte seine
Breite als `style`-Attribut, und das verbietet die Content-Security-Policy.

## Kredite

Gerechnet wird als **Annuitätendarlehen**: gleichbleibende Rate, sinkender Zinsanteil,
wachsende Tilgung. Zinsen fallen je Periode auf die Restschuld an.

Der Tilgungsplan wird **gerechnet, nicht gespeichert** – er ergibt sich vollständig aus
Betrag, Zins, Rate und Beginn. Eine jährliche Sondertilgung wird im Dezember verrechnet.

Deckt die Rate nicht einmal die Zinsen der ersten Periode, entsteht kein Plan, sondern ein
Hinweis: So ein Kredit würde wachsen statt zu schrumpfen, und eine Endlosschleife wäre die
schlechtere Antwort darauf.

Bei langen Laufzeiten zeigt die Tabelle die nächsten zwei Jahre und das Ende; dazwischen
steht, wie viele Raten ausgelassen wurden.

## Zahlungsverkehr

**Erst die Bank, dann die Buchung.** Ein Zahlungsauftrag ist zunächst ein Entwurf. Die
Buchung auf dem Auftragskonto entsteht erst, wenn die Bank den Auftrag angenommen hat –
vorher wäre sie eine Behauptung, die man nach einer abgelehnten TAN wieder einsammeln
müsste.

Ein gesendeter Auftrag lässt sich weder ändern noch löschen: Er bleibt als Beleg stehen.
Fehlgeschlagene tragen die Meldung der Bank daneben.

Ohne Ausführungstermin geht die Überweisung sofort hinaus, mit Termin als
Terminüberweisung; sie erscheint dann im Finanzkalender.

**Echtzeitüberweisung.** Das Häkchen „Echtzeitüberweisung“ im Überweisungsdialog
(Spalte `zahlungsauftraege.echtzeit`) macht aus dem Auftrag eine SEPA-Echtzeitüberweisung
(SCT Inst): Das Geld ist binnen Sekunden beim Empfänger. SEPA behandelt sie als eigenes
Verfahren – über FinTS geht sie als Geschäftsvorfall **HKIPZ** hinaus statt als HKCCS, in
der pain.001-Nachricht steht zusätzlich die Zahlungsart `PmtTpInf/LclInstrm/Cd = INST`.
Einen Ausführungstermin gibt es dafür nicht; der Dialog sperrt das Feld, das Modell weist
einen Termin in der Zukunft ab. Bietet die Bank keine Echtzeitüberweisung an (kein
Segment HIIPZS in den Bankparametern), scheitert der Auftrag mit einer klaren Meldung.
Eine Umwandlung in eine gewöhnliche Überweisung erlaubt der Finanzmanager der Bank
ausdrücklich nicht – wer Echtzeit wählt, soll erfahren, wenn es nicht klappt.

**Ausgang offen (3045).** Antwortet die Bank des Empfängers nicht rechtzeitig, quittiert
die eigene Bank die TAN mit 3045 („noch keine Rückmeldung zum Status“) und nennt in HIIPZ
eine Auftragsidentifikation. Der Auftrag liegt dann bei der Bank: Er gilt als gesendet und
wird gebucht – erneutes Senden wäre eine Doppelzahlung. Den Ausgang fragt der Finanzmanager
mit **HKIPS** nach (php-fints-Fork ab v4.1.7, `GetSEPARealtimeTransferStatus`). Die Bank
nennt dafür in HIIPSS eine Mindestwartezeit (DKB 5 s, comdirect 99 s). Die Nachfrage läuft
in einem eigenen Hintergrundprozess (`scripts/echtzeit-status.php <benutzer> <auftrag>`):
Er wartet die Mindestwartezeit ab und fragt höchstens fünfmal; eine Sperrdatei je Auftrag
verhindert doppelte Läufe. Bis dahin steht der Auftrag in der Liste mit „Ausgang offen“.
Verlangt die Bank für die Abfrage eine TAN oder bleibt der Ausgang offen, wird die
automatische Abfrage eingestellt (`status_abfrage_ab` leer). Nach einem Neustart des
Containers stößt die Zahlungsverkehrsliste fällige Abfragen erneut an.
Status 4 und 7 gelten als ausgeführt, 2, 6, 8 und 9 als abgelehnt – dann verschwindet die
Buchung wieder und der Auftrag lässt sich korrigieren und erneut senden. Wird beim
Umsatzabruf ein Umsatz mit der Buchung verbunden, ist der Ausgang ebenfalls geklärt.
Spalten: `bank_auftrag_id`, `echtzeit_status`, `status_abfrage_ab` (Migration 026).

**Welches Konto bei der Bank gemeint ist**, entscheidet dieselbe Zuordnung wie beim
Umsatzabruf: die Zeile in `bank_konten`, die dem Konto zugewiesen ist (IBAN, ersatzweise
Kontonummer). Die IBAN am Konto selbst ist optional und wird nur herangezogen, wenn keine
Zuordnung besteht – sonst müsste man dieselbe Angabe zweimal pflegen.

### SEPA-XML von Hand

php-fints erwartet die fertige **pain.001**-Nachricht und erzeugt sie nicht. Die üblichen
Erzeuger wären zwei weitere Abhängigkeiten für ein Dokument von sechzig Zeilen –
`Services\SepaXml` schreibt es deshalb selbst.

**Welches Format, sagt die Bank.** Die einen nehmen das ISO-Format `pain.001.001.03`, die
anderen nur das ältere DK-Format `pain.001.003.03` – und weisen alles andere schon beim
Einreichen ab. Welche Formate eine Bank führt, steht in den Bankparametern (Segment
HISPAS); `SepaXml::schemaWaehlen()` sucht daraus das passende aus, ISO bevorzugt. Für die
Einzelüberweisung sind beide Fassungen im Aufbau gleich, es genügt der andere Namensraum.
Die Echtzeitüberweisung gibt es nur im ISO-Format: Das DK-Format kennt die Zahlungsart
`LclInstrm` nicht. Ihre Formate nennt die Bank in HIIPZS, ersatzweise gelten die aus HISPAS.

Der **SEPA-Zeichenvorrat** ist eng: `a–z A–Z 0–9 / - ? : ( ) . , ' +` und Leerzeichen.
Umlaute werden umgeschrieben (ä → ae), alles Übrige fällt weg. Ohne diese Umschrift weist
die Bank den Auftrag zurück – und zwar erst nach dem Absenden.

Der Verwendungszweck endet bei 140 Zeichen; das ist das SEPA-Maß, alles darüber würde die
Bank ohnehin abschneiden.

### Namensabgleich (Verification of Payee)

Seit Oktober 2025 gleicht die Bank vor der Ausführung den Empfängernamen mit dem
Kontoinhaber ab. Der Ablauf ist eine Stufe vor der TAN:

1. Der Auftrag geht zusammen mit dem Prüfauftrag (Segment HKVPP) hinaus.
2. Braucht die Bank für den Abgleich einen Moment, wird nachgefragt, bis das Ergebnis da
   ist – wie lange sie braucht, sagt sie selbst.
3. **Stimmt der Name überein, bestätigt der Finanzmanager selbst** und geht direkt zur
   TAN. Eine Rückfrage ohne Erkenntnis erspart das dem Nutzer.
4. **Weicht der Name ab**, ist er nur nahezu gleich oder konnte die Bank nicht prüfen,
   kommt die Maske `zahlungsverkehr/vop.php`: das Ergebnis in einem deutschen Satz, der
   Aufklärungstext der Bank als Klartext (ihr HTML wird abgeräumt), Empfänger und IBAN aus
   dem Auftrag, und die Wahl zwischen *Trotzdem senden* und *Abbrechen*.

Stimmt der Name nur **nahezu** überein, nennt die Bank den bei ihr hinterlegten
Kontoinhaber – er steht dann in der Maske neben dem angegebenen Namen. Weicht der Name
ganz ab, bleibt er geheim: Sonst ließen sich über beliebige IBANs Kontoinhaber ausspähen.
Die Spezifikation erlaubt die Angabe ausdrücklich nur beim Close Match.

Wer trotz Abweichung sendet, verliert den Erstattungsanspruch – deshalb steht das auch in
der Maske. Beim Abbrechen bleibt der Auftrag als Entwurf stehen, der Empfängername lässt
sich korrigieren und der Auftrag erneut senden.

Meldet die Bank die **schrittweise Lieferung** des Prüfberichts (BPD-Parameter „Art der
Lieferung Payment Status Report" = `S`, etwa bei comdirect), betrifft das nur sehr große
Sammler, bei denen die Bank den Bericht über mehrere Runden schickt. php-fints lehnte
solche Banken bisher pauschal ab; der Fork auf Codeberg prüft das erst, wenn wirklich eine
Teillieferung kommt (siehe `docs/banking.md`).

### TAN

Für Überweisungen verlangt jede Bank eine TAN. Der Dialog wird genauso über die Sitzung
fortgesetzt wie beim Abruf (siehe `docs/banking.md`): Zustand sichern, Maske zeigen, nach
der Eingabe weitermachen.

Beim Abbrechen bleibt der Auftrag als Entwurf stehen und lässt sich erneut senden.

## Tests

`tests/18_NebenmoduleTest.php` – Vorlagen mit skalierten Splits und aus Buchungen,
QIF-Vorlagenimport samt Idempotenz, Terminrechnung und Fortschreiben der Fälligkeit,
Fälligkeitslauf (nur automatische Reihen, wartende rücken nicht vor), Erinnerungen,
IBAN-Prüfung mit gültigen und falschen Nummern, Kündigungsfristen und Jahresbeträge,
Sparfortschritt aus dem Konto, Tilgungsplan (Annuität, letzte Rate, Sondertilgung,
zu kleine Rate), Zahlungsaufträge (Buchung erst nach Annahme, Unveränderlichkeit,
Eingabeprüfungen), SEPA-XML (Schema, Zeichensatz, Wohlgeformtheit) und der Finanzkalender.

`tests/39_SepaSchemaTest.php` – Formatwahl nach den Angaben der Bank; die erzeugte
Nachricht wird gegen das beiliegende DK-Schema `tests/schemata/pain.001.003.03.xsd`
validiert.

`tests/40_NamensabgleichTest.php` – deutsche Sätze zu jedem Prüfergebnis, Aufbereitung des
Banktexts und die Absicherung, dass ohne wartenden Vorgang nichts bestätigt werden kann.