Finanzmanager/docs/buchungen.md

# Buchungen

Kontoblatt, Buchungsmaske und die Saldenrechnung.

## Umbuchungen: ein Datensatz, zwei Sichten

Eine Umbuchung wird **einmal** gespeichert – als Buchung auf dem Ausgangskonto mit
`gegenkonto_id`. Das Kontoblatt des Gegenkontos zeigt sie mit umgekehrtem Vorzeichen.

Der Grund ist nicht nur Sparsamkeit: Zwei gespiegelte Datensätze laufen früher oder später
auseinander (einer wird geändert, der andere nicht). Und der QIF-Export macht es genauso –
dort steht jede Umbuchung genau einmal, die Gegenseite nur als `L[Zielkonto]`.

`Buchung::kontoblatt()` vereinigt deshalb drei Mengen:

1. Buchungen mit `konto_id = X` (eigene Sicht)
2. Buchungen mit `gegenkonto_id = X` ohne Splitzeilen, Betrag negiert
3. Splitzeilen mit `gegenkonto_id = X`, Betrag negiert

Zeilen aus 2 und 3 tragen `gegensicht = true`. Sie sind nicht bearbeitbar – das geht auf
dem Ursprungskonto –, damit eine Umbuchung nicht aus zwei Richtungen widersprüchlich
geändert wird.

**Beide Sichten nennen das Gegenüber.** In der Kategoriespalte steht das jeweils andere
Konto in eckigen Klammern: auf dem Ausgangskonto das Ziel, auf dem Gegenkonto das
Ursprungskonto. In der Gegensicht liefert die Abfrage dafür `b.konto_id` als
`gegenkonto_id` – dieselbe Spalte, aus der anderen Richtung gelesen. Ohne diese Angabe
stünde auf dem Gegenkonto eine Zeile, die sich „Umbuchung“ nennt und verschweigt, woher
sie kommt.

Dieselbe Dreiteilung gilt für die Salden (`Buchung::saldenJeKonto()`), die alle Konten mit
sechs Abfragen auf einmal berechnet statt je Konto einzeln.

## Mehrfachauswahl im Kontoblatt

Vor dem Datum steht je Zeile ein Ankreuzfeld, in der Titelzeile eines für alle gerade
angezeigten Buchungen. *Auswahl löschen* in der Aktionsleiste schickt die Auswahl an
`POST /konten/{id}/buchungen/loeschen`.

Zwei Punkte, die sich nicht ändern dürfen:

* Der Knopf steht **über** der Tabelle, die Ankreuzfelder stehen **in** ihr. Verbunden sind
  sie über `form="buchungsauswahl"`, nicht über Verschachtelung – ein Formular um die ganze
  Tabelle würde das Filterformular umschließen.
* Zeilen mit `gegensicht = true` bekommen kein Ankreuzfeld, und der Controller prüft
  zusätzlich `konto_id`. Die Gegenseite einer fremden Umbuchung wird nur auf ihrem
  Ursprungskonto gelöscht – dieselbe Regel wie beim Bearbeiten.

Filter und Seite hängen an der Abfragezeichenfolge des Formularziels. Der Controller baut
den Weg zurück aus den bekannten Feldern neu zusammen, statt ein mitgeschicktes Ziel zu
übernehmen; so lässt sich kein fremder Weiterleitungsort einschleusen.

## Kategorie und Gegenkonto in einem Feld

Eine Buchung ist entweder kategorisiert **oder** eine Umbuchung – beides zugleich gibt es
nicht. Deshalb stehen Kategorien und Konten in derselben Auswahlliste; die Konten unten,
in eckigen Klammern, wie das Kategoriefeld im FinanzManager sie schreibt. Das eigene Konto
fehlt in der Liste.

Die Liste steht in `Views/buchungen/zuordnungsliste.php` und wird an vier Stellen
eingebunden: Buchungsmaske, deren Splitzeilen, Schnellzuordnung im Kontoblatt und
Splitdialog. Die Werte tragen ein Präfix, das `BuchungenController::zuordnungAus()` wieder
auseinandernimmt:

| Wert | Bedeutung |
|---|---|
| `` (leer) | keine Zuordnung |
| `kategorie:12` | Kategorie 12 |
| `konto:7` | Umbuchung mit Gegenkonto 7 |
| `split` | Splitdialog öffnen (nur im Kontoblatt) |
| `depot:7` | Wertpapiergeschäft im Depot 7 (Kontoblatt und Buchungsmaske) |

Die Auswahl *Ausgabe / Einnahme* bestimmt seither nur noch die Richtung des Betrags.

Ein Depot steht **zweimal** in der Liste: als gewöhnliche Umbuchung (`konto:7`) und in der
Gruppe *Wertpapiergeschäft im Depot* (`depot:7`). Beides gibt es wirklich – auf ein Depot
lässt sich Geld überweisen, ohne dass etwas gekauft wird. `depot:7` speichert keine
Zuordnung, sondern öffnet die Wertpapiermaske; daraus wird am Ende meist eine Splitbuchung
(siehe `docs/wertpapiere.md`, *Geschäft aus einer Kontobuchung*). In den **Splitzeilen**
fehlt die Gruppe: Dort steht der Betrag der Zeile schon fest, und die Umbuchung ins Depot
ist genau das, was gebraucht wird.

## Schnellzuordnung im Kontoblatt

Ein Klick auf die Kategoriespalte öffnet die Liste in der Zelle; die Auswahl geht an
`POST /buchungen/{id}/zuordnung`, der Eintrag *Splitbuchung* öffnet stattdessen den
Splitdialog (`POST /buchungen/{id}/splitbuchung`). Beide Wege gehen über
`Buchung::zuordnen()` und `Buchung::splitsErsetzen()`, die den Rest der Buchung unberührt
lassen und den Monatsabschluss achten.

Drei Punkte, die sich nicht ändern dürfen:

* Die Auswahlliste gibt es **einmal**; `kontoblatt.js` hängt sie in die angeklickte Zelle
  und danach zurück. Eine Liste je Zeile wären bei hundert Zeilen ebenso viele
  vollständige Kategoriebäume im HTML.
* Ohne JavaScript führt derselbe Klick in die Buchungsmaske – die Zelle ist ein Link, kein
  Knopf.
* Zeilen mit `gegensicht = true` führen zu ihrer Buchung, statt die Auswahl zu öffnen: Sie
  werden auf ihrem Ursprungskonto geändert, wie beim Bearbeiten und Löschen.
  `kontoblatt.js` erkennt sie an der Klasse `gegenseite`.
* Feld und Auswahlliste sind **gleich breit** (`13rem`), und die Zelle zeigt nichts an, was
  nicht auch in der Liste stünde – kein „zuordnen …“. Sonst rückt beim Anklicken die halbe
  Zeile: Die Spalte wüchse auf die Breite der längsten Kategorie, und der Empfänger daneben
  bräche um. Senkrecht rückt nichts, weil die Zeilenhöhe ohnehin feststeht (siehe unten).

Die Auswahl eines Depots (`depot:7`) öffnet statt beider den **Wertpapierdialog**; ohne
JavaScript führt sie auf `/buchungen/{id}/wertpapier?depot=7`, wo dieselben Felder als
gewöhnliches Formular stehen. Auch die Buchungsmaske leitet dorthin, nachdem sie die
Buchung gespeichert hat.

Eine schon gesplittete Buchung öffnet auf Klick **direkt den Splitdialog**, nicht die
Auswahlliste: Deren einziger sinnvoller Eintrag wäre für sie ohnehin *Splitbuchung*
gewesen. Wer eine Aufteilung wieder in eine einzelne Zuordnung wandeln will, löscht sie
im Dialog und ordnet die dann unzugeordnete Buchung anschließend zu – oder geht über die
Buchungsmaske.

### Typeahead (Feature #41)

Sowohl der Kategorie-Filter oben im Kontoblatt als auch die Auswahlliste der
Schnellzuordnung tragen `data-kombobox`. `static/kombobox.js` baut ein so markiertes
`<select>` beim Laden der Seite in ein Eingabefeld mit darunter aufklappender, gefilterter
Liste um – Optgroups bleiben als Überschriften erhalten. Das ursprüngliche `<select>`
bleibt unsichtbar im Formular stehen, Wert, Name und `change`-Ereignis ändern sich nicht;
`kontoblatt.js` liest und setzt weiterhin nur `select.value`.

Beim Öffnen der Schnellzuordnung ruft `kontoblatt.js` `select._kombobox.oeffnen()` statt
`showPicker()` auf – ein verstecktes `<select>` ließe sich weder fokussieren noch mit
`showPicker()` öffnen. Die Klassen-Auswahl bleibt bewusst ein gewöhnliches `<select>` ohne
`data-kombobox`: Ihre Liste ist kurz, ein Typeahead brächte dort nichts.

## Klasse im Kontoblatt

Die Klassenspalte ist nach derselben Bauart anklickbar: eine zweite Liste
(`#klassenauswahl`), die `kontoblatt.js` in die angeklickte Zelle hängt. Ihr erster Eintrag
*— keine —* löscht die vorhandene Klasse, jeder andere setzt sie; gespeichert wird sofort
beim Anklicken, über `POST /buchungen/{id}/klasse` und `Buchung::klasseSetzen()`.

Die Klasse steht **neben** der Zuordnung, nicht in ihr: Sie ist die zweite
Auswertungsdimension. Anders als `Buchung::zuordnen()` rührt `klasseSetzen()` deshalb weder
Kategorie noch Gegenkonto noch Splitzeilen an – auch eine gesplittete Buchung bleibt beim
Wechsel der Klasse gesplittet. Den Monatsabschluss achtet die Methode wie alle anderen.

Bei einer **Splitbuchung** zählen die Klassen ihrer Zeilen (`Buchung::splitKlasse()`):
Tragen alle Zeilen dieselbe Klasse, steht sie in der Spalte; unterscheiden sie sich – eine
Zeile ohne Klasse zählt dabei als eigene Angabe –, steht dort die Marke *Splitbuchung*, und
der Tooltip nennt je Zeile Kategorie (oder Gegenkonto) und Klasse. Hat keine Zeile eine
Klasse, bleibt es bei der Klasse der Buchung selbst. Ein Klick auf die Klassenzelle einer
Splitbuchung öffnet den Splitdialog statt der Klassenliste (`data-split`): Dort stehen ihre
Klassen.

## Zeilenhöhe und Tooltips im Kontoblatt

Jede Buchungszeile ist **zwei Textzeilen hoch**, gleich wie viel in ihr steht, und ihr
Inhalt steht senkrecht in der Mitte. Eine Zeile, die mit ihrem Text wächst, ließe die Liste
beim Blättern hüpfen; eine, die auf eine Zeile schrumpft, machte lange Empfänger unlesbar.
Die Höhe hängt an `table.kontoblatt td`, das Abschneiden an `.zellentext` (zwei Zeilen,
danach Auslassungspunkte). Empfänger und Buchungstext stehen deshalb in einem `<div>` und
nicht unmittelbar in der Zelle: Abschneiden kann nur ein Element, das kein Tabellenfeld ist.

Die Marke der Umbuchungs-Gegenseite steht **neben** dem abgeschnittenen Kasten
(`.zellenreihe`), nicht darin – sonst zählte sie als eine der beiden Zeilen und die Zeile
würde höher als die übrigen.

Den vollständigen Text zeigt der Tooltip:

* **Empfänger und Buchungstext**: `kontoblatt.js` setzt den Tooltip nach dem Laden und nach
  jeder Größenänderung des Fensters – aber nur dort, wo wirklich etwas abgeschnitten ist.
  Ob das der Fall ist, weiß erst der Browser nach dem Umbruch, und das hängt an der
  Fensterbreite. Ein Tooltip, der bloß wiederholt, was ohnehin dasteht, wäre lästig.
* **Kategorie und Klasse** tragen ihren Tooltip vom Server. Bei einer **Splitbuchung** nennt
  er die Zeilen der Aufteilung: je Zeile Kategorie (oder Gegenkonto) und Betrag, sonst
  nichts. Notiz und Klasse stünden nur im Weg; die Klassen nennt bei verschiedenen Klassen
  der Tooltip der Klassenspalte (siehe oben).

## Splitbuchungen

Eine Buchung ist entweder einfach zugeordnet **oder** gesplittet. Sobald Splitzeilen
vorliegen, räumt das Model `kategorie_id` und `gegenkonto_id` der Buchung; die Zuordnung
steckt dann ausschließlich in den Zeilen.

Die Summe der Zeilen muss dem Buchungsbetrag entsprechen – geprüft im Model (Toleranz ein
halber Cent, für Rundungen aus der Betragsumrechnung) und in beiden Masken als
Restbetragsanzeige. Beide rechnen mit `public/static/betrag.js`; die Regel für das
deutsche Zahlenformat steht damit einmal im Browser und einmal in PHP, nicht dreimal. Eine
Splitzeile darf ein Gegenkonto tragen; dann erscheint auf jenem Konto nur der Betrag dieser
Zeile. Auf das eigene Konto darf sie nicht zeigen – die Buchung zählte dort doppelt.

In der **Buchungsmaske** sperren sich beide Wege gegenseitig (`public/static/buchungsmaske.js`):
Sobald in einer Splitzeile irgendetwas steht, sind *Kategorie / Gegenkonto* und *Klasse*
gesperrt; steht dort umgekehrt eine Kategorie, ein Gegenkonto oder eine Klasse, sind alle
Splitzeilen gesperrt. Gesperrte Felder schickt der Browser nicht mit. Stehen beim Öffnen
beide Seiten voll, gilt wie im Model die Splitbuchung. Der Knopf *Splitbuchungen löschen*
rechts über der Splittabelle erscheint, sobald eine Splitzeile belegt ist; er leert alle
Zeilen und gibt die direkten Felder wieder frei. Gespeichert wird erst mit dem Formular.

Der Knopf *Splitbuchung löschen* im Dialog schickt `POST /buchungen/{id}/splitbuchung` mit
`aktion=loeschen`; der Controller ruft dann `Buchung::splitsErsetzen($id, [])`, ganz gleich
was in den Feldern steht. Gelöscht werden die Zeilen samt Zuordnung, nicht die Buchung –
sie steht danach mit ihrem Betrag und ohne Kategorie im Kontoblatt, und die Gegenseite
einer Zeile mit Gegenkonto verschwindet von jenem Konto.

## Salden

| Spalte | Bedeutung |
|---|---|
| Online-Saldo | Stand des letzten Bankabrufs (`konten.saldo_online`, ab Phase 5) |
| Aktueller Saldo | Anfangssaldo plus alle Buchungen bis heute |
| Erwarteter Saldo | zusätzlich die künftig datierten Buchungen |

In die **Summe der Kontostände** zählen nur Konten mit `in_summe = 1` – das entspricht der
Σ-Spalte im FinanzManager. Durchlaufende Auslagen und Rentenversicherungen bleiben so
außen vor, erscheinen aber weiter in der Liste. Der QIF-Export kennt das Kennzeichen
nicht; es wird im Kontoformular gepflegt.

## Beträge in der Oberfläche

Eingegeben wird immer ein **positiver** Betrag; die Richtung bestimmt die Auswahl
*Ausgabe / Einnahme*. `KontenController::zahl()` liest das deutsche Format und
entscheidet bei einem Punkt ohne Komma nach der Stellenzahl: drei Ziffern dahinter heißt
Tausendertrenner (`1.500`), sonst Dezimaltrenner (`1234.56`).

## Bestätigungen und die Content-Security-Policy

Die CSP erlaubt keine Inline-Skripte (`script-src 'self'`). Rückfragen vor dem Löschen
dürfen deshalb **nicht** als `onsubmit="return confirm(…)"` im HTML stehen – der Browser
verwirft sie stillschweigend, und gelöscht wird ohne Nachfrage. Stattdessen:

```html
<form method="post" action="…" data-bestaetigen="Buchung wirklich löschen?">
```

`public/static/app.js` hängt den Dialog daran. Ein E2E-Test besteht auf dem Dialog, damit
das nicht unbemerkt zurückfällt.

## Abgleich mit dem Bargeld-Tool

Bargeldausgaben werden in einem zweiten Programm (FSCash) erfasst; im Finanzmanager kommen
sie als Kartenumsatz oder Abhebung an. Wer einer solchen Buchung eine Kategorie zuweist,
soll sehen, ob sie dort schon steht.

**Eingerichtet wird das unter Verwaltung → Bargeld-Tool**: Adresse, Benutzerkennung,
Passwort (AES-verschlüsselt wie die FinTS-PIN), Suchzeitraum in Tagen und die Auswahl der
Kategorien, die überhaupt abgeglichen werden. Die Auswahl steht als `bargeld_abgleich` an
der Kategorie selbst und nicht als Liste von Nummern in den Einstellungen – so verschwindet
sie mit der Kategorie, statt als tote Nummer liegenzubleiben. Die übrigen Angaben liegen im
Einstellungsbereich `bargeld`, der bewusst keinen Reiter im Einstellungsdialog hat; er steht
dafür in `Einstellung::EIGENE_SEITEN` (Test 02 prüft, dass jeder Bereich erreichbar bleibt).

**Geprüft wird beim Zuweisen einer Kategorie** – aus der Schnellzuordnung des Kontoblatts
ebenso wie aus der Buchungsmaske. `Services\BargeldAbgleich::pruefe()` verlangt drei Dinge:
eine Kategorie an der Buchung (keine Umbuchung, keine Splitbuchung), diese Kategorie
vorgemerkt, eine Adresse konfiguriert. Fällt eines weg, wird der Status gelöscht – auch beim
Umkategorisieren, sonst bliebe ein alter Haken an einer Buchung stehen, die niemand mehr
abgleicht. Gesucht wird über `Services\BargeldTool` mit dem Betrag der Buchung, rückwärts ab
ihrem Datum: Bargeld wird ausgegeben, bevor der Umsatz auf dem Konto ankommt, nie danach.

Das Ergebnis steht als `bargeld_status`, `bargeld_hinweis` und `bargeld_geprueft_am` an der
Buchung. Das Kontoblatt liest es von dort und geht nicht bei jedem Blättern erneut übers
Netz. In der schmalen Spalte zwischen Klasse und Betrag steht:

| Symbol | Status | Bedeutung |
|---|---|---|
| ● grau | `NULL` | Die Buchung wird nicht abgeglichen |
| ✓ grün | `gefunden` | Im Bargeld-Tool steht eine Buchung mit demselben Betrag |
| ✗ rot | `fehlt` | Dort steht keine |
| ! | `fehler` | Der Abruf ist gescheitert |

Das Ausrufezeichen behält ausdrücklich die Textfarbe des Farbschemas: Der Fehler liegt beim
Abruf, nicht bei der Buchung – rot oder grün wäre eine Aussage über die Buchung, die niemand
treffen kann. Der Tooltip nennt den Treffer bzw. die Meldung der Gegenstelle. Ist keine
Adresse hinterlegt, entfällt die Spalte ganz; sie zeigte sonst in jeder Zeile denselben
grauen Kreis.

Buchungen mit dem Status `fehler` zählen im Cockpit als offener Vorgang „Bargeld-Tool-Prüfung
fehlgeschlagen“ (siehe `docs/cockpit.md`) – ein Klick führt auf
`/verwaltung/bargeld/fehler`, die kontoübergreifende Liste dieser Buchungen
(`Buchung::mitBargeldFehler()`). Der Status `fehlt` erscheint dort bewusst nicht: Er ist ein
Ergebnis, kein offenes Problem – eine erneute Zuordnung fragt einfach wieder ohne Erfolg.

**Ein Fehlschlag ist ein Ergebnis, kein Abbruch.** Weder ein abgeschaltetes Bargeld-Tool
noch ein Netzfehler darf verhindern, dass die Kategorie gespeichert wird; der Abruf bricht
nach acht Sekunden ab. Null Treffer sind ausdrücklich kein Fehler – ein 404 dagegen schon,
denn er kann ebenso gut heißen, dass es den Endpunkt nicht gibt.

### Die Schnittstelle

Zwei lesende Aufrufe, beschrieben im Ticket „automatischer Abgleich mit Bargeld-Tool“:

```
GET {adresse}/api/v1/buchungen?von=2026-08-09&bis=2026-08-19&betrag=-12.50&waehrung=EUR&limit=20
GET {adresse}/api/v1/status
```

Beide mit HTTP Basic Auth. Die Suche antwortet mit `{"anzahl": n, "buchungen": [...]}`; je
Buchung sind `id`, `datum` und `betrag` nötig, `zweck`, `empfaenger`, `waehrung`, `kategorie`
und `konto` gehen in den Tooltip. Der Statusaufruf ist freiwillig – kennt die Gegenstelle ihn
nicht (404), prüft der Verbindungstest über eine Suchabfrage.

Der Betrag geht vorzeichenbehaftet über die Leitung, so wie er im Finanzmanager steht:
Ausgaben negativ. Führt das Bargeld-Tool seine Beträge positiv, muss es umrechnen.

`{adresse}` ist die Basisadresse **ohne** Schnittstellenpfad. Steht am Ende der eingetragenen
Adresse trotzdem `/api` oder `/api/v1`, kürzt der Finanzmanager sie beim Speichern – die
Adresse aus der Browserzeile zu kopieren ist der naheliegende Weg und führte sonst zu
`/api/v1/api/v1/status` und einem 404 im Verbindungstest.