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.

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.

### SEPA-XML von Hand

php-fints erwartet die fertige **pain.001.001.03**-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.

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.

### 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.