bin/docs/superpowers/specs/2026-09-30-ausbaustufe-14-design.md

Design — Ausbaustufe 14: Szenario-Einträge mit Zeitraum, „Neuer Betrag", szenario-eigene wiederkehrende Zahlungen (v0.14.0)

Status: vom Nutzer im Chat freigegeben (2026-09-30), Abschnitte 1–3. Umsetzungsplan folgt unter docs/superpowers/plans/. Datenschutz-Regel aus CLAUDE.md gilt: konkrete Posten-Namen/Beträge aus der Live-Datenbank stehen nur im Chat, nicht in diesem Dokument, nicht in Tests/Commits/Ledger.

Anlass

Der Nutzer wollte in einem Szenario einen bestehenden monatlichen Fixposten ab einem Stichtag auf 50 % senken. Das ging nicht: Szenario-Einträge (Prozent/Absolut/Entfällt) wirken über die gesamte Laufzeit, „Absolut" ist eine Kürzung (nicht ein neuer Betrag), und ein Szenario kann keine eigenen wiederkehrenden Zahlungen haben — nur Einmalzahlungen. Die Lücke ist eine bewusste Auslassung aus A5 („Ende" als eigene Art statt Gültigkeitszeitraum aller Modifikatoren).

Nutzerentscheidungen (Chat 2026-09-30)

• A — Zeitraum: Prozent, Kürzung (€), Neuer Betrag und Entfällt bekommen optionale Grenzen Gültig ab und Gültig bis (beide leer = unbegrenzt). „Ende" bleibt wie bisher.
• Neue Eintragsart „Neuer Betrag" (ersetzt den Betrag eines Postens). „Absolut" heißt in der GUI künftig „Kürzung (€)".
• B — szenario-eigene wiederkehrende Zahlungen mit denselben Feldern wie Fixposten inkl. optionaler Kategorie; Kategorie-Einträge treffen sie.
• Formular geteilt in „Neue Änderung an Bestehendem" und „Neue Zahlung nur in diesem Szenario" (Szenario-Einmalzahlungen bekommen dabei ebenfalls eine optionale Kategorie).
• A14-Kandidaten aus dem Ledger werden mitgenommen, außer „figcaption nicht fett" — die Bildunterschrift der Torte bleibt fett (ausdrücklicher Nutzerwunsch).
• Das Live-Szenario des Nutzers wird nicht vom Tool-Team angepasst; der Nutzer probiert die Neuerung selbst daran aus.

Teil 1 — Datenmodell (eine Alembic-Revision, down_revision = 'd5e8b3c7a410')

• scenario_modifiers: neue Spalte start_date DATE NULL („Gültig ab"). Die vorhandene Spalte end_date bedeutet künftig bei allen Arten „Gültig bis" (inklusiv); bei ende bleibt sie das Enddatum des Postens. Bestandsdaten: bisherige percent/absolute/remove-Zeilen haben end_date = NULL (API hat es bisher genullt) → gelten unverändert unbegrenzt. Keine Datenmigration nötig.
• Neue Art set (GUI-Label „Neuer Betrag"): value ist der neue Betrag mit Vorzeichen (wie Fixposten-Beträge, z. B. -137.50). Nur mit target_type = "recurring" zulässig.
• Neue Tabelle scenario_recurring_items: id, scenario_id (FK scenarios.id, index), name String(200), amount MONEY, rhythm String(20), due_day Integer, start_date Date NULL, end_date Date NULL, category_id (FK categories.id, NULL). Modell ScenarioRecurringItem in models/tables.py.
• scenario_planned_items: neue Spalte category_id (FK categories.id, NULL).
• Downgrade: löscht set-Zeilen, setzt end_date = NULL für alle Nicht-ende-Zeilen (alte Semantik), droppt start_date, scenario_planned_items.category_id und scenario_recurring_items.

Teil 2 — Rechenlogik (engine/scenario.py, engine/breakdown.py)

• PlainModifier bekommt start_date: date | None = None.
• modified_amount(amount, category_id, recurring_id, modifiers, on: date): ein Modifikator wirkt nur, wenn (start_date is None or on >= start_date) and (end_date is None or on <= end_date) (bei Art ende wird er hier wie bisher übersprungen — Ende wirkt nur über effective_end). Reihenfolge unverändert = Anlage-Reihenfolge (ID). set → amount = value; ein späterer percent/absolute rechnet auf dem neuen Betrag weiter. remove im Zeitraum → None (Fälligkeit entfällt), außerhalb → normal.
• Projektion (build_cashflows): Betrag je Fälligkeit mit on = Fälligkeitsdatum bestimmen (bisher einmal je Posten). Einmalposten: on = due.
• Aufteilung (breakdown_rows): Stichtag je Fixposten = sein Fälligkeitstag im gewählten Monat, auf die Monatslänge geklemmt (gleiche Klemmregel wie recurrence.occurrences); Einmalposten: on = due. Monatsausschluss über start_date/effective_end bleibt wie bisher. Beispiel: Posten fällig am 14., Eintrag „50 % ab 16.10." → Oktober voll, ab November halbiert.
• Szenario-eigene wiederkehrende Zahlungen werden in load_scenario_inputs als PlainRecurring mit id = None geladen (Typ id: int | None), damit Posten-Einträge (target_type="recurring") sie nie treffen — die IDs zweier Tabellen könnten kollidieren. Kategorie-Einträge treffen sie über category_id. Sie zählen immer, unabhängig von include_recurring (Regel wie Szenario-Einmalzahlungen). Für „System-Plan" (scenario=None) gibt es sie nicht.
• Szenario-Einmalzahlungen werden mit ihrer category_id geladen (bisher fest None).
• BreakdownRow.recurring_id bleibt für szenario-eigene Zahlungen None → der Doppelzählungs-Hinweis (Kredit vs. Fixposten) berücksichtigt sie nicht.
• Unberührt: Grafana „Planung nach Kategorie", „System-Plan", v_projection.

Teil 3 — API (routers/scenarios.py)

• ModifierIn: kind: Literal["percent", "absolute", "set", "remove", "ende"], neu start_date: date | None = None. Validator (422, deutsch):
  • ende ohne end_date → „Art »Ende« erfordert ein Datum" (wie bisher); bei ende wird start_date genullt.
  • set mit target_type != "recurring" → „Art »Neuer Betrag« ist nur für Posten möglich".
  • start_date > end_date → „»Gültig ab« liegt nach »Gültig bis«".
  • end_date wird nicht mehr für Nicht-ende-Arten genullt. POST/PATCH bleiben Full-Body.
• Neuer Endpunkt /api/scenarios/{id}/recurring: GET (Liste, sortiert nach Name), POST (201), PATCH /{item_id} (Full-Body), DELETE /{item_id} (204). Schema ScenarioRecurringIn mit den Feldern und Validierungen von RecurringIn (Rhythmus-Literal, due_day 1–31, Ende nicht vor Start); Kategorie-Existenz via _check_category-Muster (404 „Kategorie nicht gefunden"); fremde/fehlende IDs → 404 „Wiederkehrende Zahlung nicht gefunden"; fehlendes Szenario → 404. Keine Doppelzählungs-Prüfung.
• ScenarioPlannedIn: neu category_id: int | None = None mit Kategorie-Existenzprüfung.
• delete_scenario löscht zusätzlich ScenarioRecurringItem-Zeilen.

Teil 4 — GUI (templates/szenarien.html, routers/gui.py, formats.py)

• de_label: absolute → "Kürzung (€)", neu set → "Neuer Betrag". modifier_kinds = percent, absolute, set, remove, ende.
• Tabelle „Einträge", Spalten: Was | Art | Wert/Betrag | Zeitraum | (Aktionen).
  • Modifikator-Zeilen: Wert bei percent/absolute/set; Zeitraum „ab TT.MM.JJJJ", „bis TT.MM.JJJJ", „TT.MM.JJJJ – TT.MM.JJJJ" oder „–"; bei ende das Enddatum.
  • Neue Zeilen für szenario-eigene wiederkehrende Zahlungen: Name (+ Kategorie), Art „Wiederkehrend (monatlich, am 14.)", Betrag, Zeitraum Start–Ende; Inline-Bearbeiten/Löschen (Muster Einmalzahlung).
  • Einmalzahlungs-Zeilen zeigen ggf. die Kategorie; Edit-Zeile bekommt das Kategorie-Feld.
• Formular „Neue Änderung an Bestehendem" (POST /modifiers): Art (Prozent | Kürzung (€) | Neuer Betrag | Entfällt | Ende), Ziel-Typ, Kategorie/Posten, Wert, Gültig ab, Gültig bis.
  • Wert-Label dynamisch: „Prozentsatz (%)" / „Kürzung (€)" / „Neuer Betrag (€)"; bei Entfällt/Ende gesperrt.
  • Neuer Betrag: Ziel-Typ fest auf Posten (Option Kategorie gesperrt).
  • Ende: „Gültig ab" gesperrt, „Gültig bis" heißt „Endet am".
• Formular „Neue Zahlung nur in diesem Szenario": Art (Einmalzahlung | Wiederkehrend), Name, Betrag, Kategorie (optional, „(keine)"), Fällig am (nur Einmal), Rhythmus + Fälligkeitstag + Start + Ende (nur Wiederkehrend). POST-Ziel wechselt /planned ↔ /recurring (Muster data-planned-url).
• Modifikator-Edit-Zeilen bekommen „Gültig ab"/„Gültig bis" und dieselbe Umschaltlogik.
• UX-Regel bleibt: nicht passende Felder sichtbar + disabled + Tooltip, Fehler inline über den bestehenden Response-Error-Handler.
• hilfe.html: Szenario-Absatz um Zeitraum, Neuer Betrag, Kürzung (€) und wiederkehrende Zahlungen ergänzen, mit neutralem Beispiel („ein Posten wird ab 16.10. halbiert").

Teil 5 — A14-Kandidaten aus dem Ledger

1. Nav-Überlauf bei 390 px: nav darf umbrechen (flex-wrap: wrap, Abstände), kein horizontales Scrollen der Seite.
2. Umriss des gewählten Tortensegments zuletzt zeichnen: gewähltes Segment wird im SVG als letztes Element ausgegeben, damit sein Umriss nicht von Nachbarn überdeckt wird.
3. Tilgungsplan-Helfer: die 4 Aufrufe loan_schedule(Decimal(l.principal), Decimal(l.annual_rate_pct), l.term_months, l.payout_date, l.repayment_type) (planning-Router, services/breakdown, projection_service, planning_chart) über einen Helfer schedule_for(loan) führen — verhaltensneutral.
4. .legende-zusatz ohne CSS: eigene Regel (normales Gewicht, gedämpfte Farbe), damit der Zusatz bei gewählter Legendenzeile nicht mit fett wird.
5. term_months-Validierung 1..1200 für Kredite (Anlegen + PATCH), 422 inline.

Ausdrücklich nicht: figcaption der Torte entfetten.

Teil 6 — Tests, Doku, Release

• Engine: Grenzen inklusiv (Tag vor/an/nach ab bzw. bis), set dann percent, remove mit Zeitraum, szenario-eigene Zahlung von Kategorie-Eintrag getroffen / von Posten-Eintrag mit gleicher ID nicht, zählt bei include_recurring = false; Aufteilungs-Stichtag (Okt voll / Nov halbiert, Klemmung am Monatsende) — nur erfundene Beträge.
• API: alle 422/404-Fälle aus Teil 3, CRUD /recurring, Szenario-Löschen räumt /recurring mit ab, Planned mit Kategorie, term_months-Grenzen.
• Migration: Upgrade/Downgrade in Wegwerf-Postgres; Bestandseinträge bleiben gleich.
• GUI/JS: Umschaltmatrix beider Formulare und der Edit-Zeilen (Stil der bestehenden Template-/JS-Tests), Nav-CSS, Torten-Reihenfolge.
• Suite bleibt grün (Basis: 377 passed / 3 skipped).
• Doku: docs/ARCHITEKTUR.md (neue Tabelle, Endpunkt, Stichtag-Regel), CLAUDE.md falls betroffen, fb-Repo (finanz-api- und finanzberatung-Skill).
• Ablauf: Plan docs/superpowers/plans/2026-09-30-ausbaustufe-14.md, direkt auf main; jeder Task mit Fable-Testagent-Gate und Ledger-Eintrag; Release v0.14.0 (VERSION, Backup, Redeploy, Live-Smoke, Fable-Release-Gate).