Detailansichten, Wasserfaelle und vollstaendige Rechenweg-Offenlegung

Roadmap Nr. 43 (Detailansichten) und Nr. 41 (Berechnungslogiken offenlegen). Systemparameter-Ansicht: - SYSTEM_PARAMETERS in constants.ts: Wert, Bedeutung, Herleitung, Quelle, Stand -- aus derselben Datei, aus der gerechnet wird Detailansichten (nur lesen, per Expand-Icon): - Element: Verlauf ueber ALLE Planjahre (neu ElementPhaseComputed.yearly), bei Immobilien Verkehrswert/Restschuld/Eigenkapital getrennt - Phase: Vermoegensaufteilung + zwei Wasserfaelle Zwei getrennte Wasserfaelle (WealthBridge / CashBridge): - Sparraten, Amortisationen und Investitionen sind UMBUCHUNGEN und erscheinen nur im Cash-Wasserfall -- als Vermoegensabgang gezeichnet wuerden sie einen Verlust vortaeuschen, den es nicht gibt - PK-Beitraege dagegen sind ein echter Vermoegenszugang (belasten kein Cash), Verrentung ein echter Abgang (Kapital verlaesst die Bilanz) - residual als Kontrollgroesse fuer die Vollstaendigkeit der Zerlegung Rechenweg-Protokoll, vollstaendige Abdeckung: - computePlan(plan, sample?, { explain }) protokolliert die Schritte, die es ohnehin ausfuehrt -- die Erklaerung IST die Rechnung, statt einer zweiten Formel-Implementierung im UI, die still abdriften koennte - standardmaessig aus (Monte Carlo bleibt unberuehrt) - Arithmetik nicht umgestellt: Zwischengroessen werden als Differenz abgeleitet, damit die 43 Golden Tests bitgleich bleiben - jeder Trace verlinkt in die SPEZIFIKATION; ein Test prueft gegen die echte Datei, dass alle Verweise eine existierende Ueberschrift treffen SPEZIFIKATION auf 0.11: neue Kapitel 3.6.7, 3.6.8, 4.14, 9.20, 9.21. 12 Tests ergaenzt (80 -> 92). Keine DB-Aenderung. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-18 17:12:55 +02:00
parent 1836cad7f3
commit 4791dccf93
9 changed files with 2066 additions and 33 deletions
@@ -4,10 +4,10 @@
 | | |
 |---|---|
 | **Dokument** | Funktionale und Technische Spezifikation FPT |
-| **Version** | 0.10 |
+| **Version** | 0.11 |
 | **Datum** | 2026-07-18 |
 | **Status** | Lebendes Dokument |
-| **Codestand** | Arbeitsstand nach `d203e50` inkl. Szenario-Vergleich in der Monte-Carlo-Simulation und Sensitivitätsanalyse (Branch `main`) |
+| **Codestand** | Arbeitsstand nach `1836cad` inkl. Detailansichten, Wasserfall-Zerlegungen und vollständiger Rechenweg-Offenlegung (Branch `main`) |
 | **Ersetzt** | `FDD_TDD_FPT.docx` (v1–v5) im Ordner `Info Dateien` – diese sind ab Version 0.1 dieses Dokuments obsolet |
 | **Geltungsbereich** | Gesamter Code im Verzeichnis `FPT` |

@@ -17,6 +17,7 @@

 | Version | Datum | Autor | Änderung |
 |---|---|---|---|
+| 0.11 | 2026-07-18 | Claude (Opus 4.8) | **Detailansichten (Roadmap Nr. 43)** und **vollständige Offenlegung der Berechnungslogiken (Roadmap Nr. 41)**. (1) Neue **Systemparameter-Ansicht** in der Seitenleiste: alle fest hinterlegten Grössen mit Wert, Bedeutung, Herleitung, Quelle und Stand – als strukturierte Daten aus `constants.ts`, also aus derselben Quelle, aus der gerechnet wird. (2) **Nur-Lese-Detailansicht** je Element und je Lebensphase über ein Expand-Icon: Element mit Verlaufsgrafik über **alle Planjahre** (dafür führt `computePlan` neu `ElementPhaseComputed.yearly` je Element mit), Phase mit Vermögensaufteilung und **zwei Wasserfällen**. (3) Die **Wasserfälle** sind bewusst getrennt: Der Vermögens-Wasserfall zeigt nur echte Zu- und Abgänge (Quote, Kapitalerträge, Wertsteigerung, PK-Beiträge, Steuern, Verrentung, Einmalposten); Sparraten, Amortisationen und Investitionen sind **Umbuchungen** und erscheinen ausschliesslich im Cash-Wasserfall – als Vermögensabgang gezeichnet würden sie einen Verlust vortäuschen, den es nicht gibt. Neue Strukturen `WealthBridge` / `CashBridge` inkl. Restposten als Kontrollgrösse. (4) **Rechenweg-Protokoll**: `computePlan(plan, sample?, { explain })` protokolliert die Schritte, die es ohnehin ausführt – Formel, eingesetzte Zahlen, Ergebnis und Hinweis auf geltende Vereinfachungen. Abdeckung über **alle** Ebenen (Element je Phase, Element je Übergang, Phasen-Kennzahlen, Plan-Ebene). Standardmässig aus, damit die Monte-Carlo-Simulation unberührt bleibt. Jeder Rechenweg verlinkt in das passende Kapitel dieser Spezifikation; ein Test prüft, dass alle Verweise eine existierende Überschrift treffen. Neue Kapitel 3.6.7, 3.6.8, 4.14, 9.20, 9.21; 12 Tests ergänzt (80 → 92). Keine DB-Änderung; die 43 Golden Tests laufen unverändert. |
 | 0.10 | 2026-07-18 | Claude (Opus 4.8) | **Szenario-Vergleich in der Monte-Carlo-Simulation** und **Sensitivitätsanalyse / Tornado** (Roadmap Nr. 20). (1) Die MC-Simulation rechnet neu **mehrere Szenarien desselben Plans in einem Lauf**. Die historischen Annahmen werden dabei nur **einmal je logischem Element** erfasst – die Zuordnung über die Herkunfts-Kette `sourceElementId`, dieselbe Grundlage wie beim Diff (neue Funktionen `resolveRootElementId`, `buildElementGroups`, `paramsForScenario`, `runMonteCarloMulti`). Alle Szenarien laufen mit **demselben Seed** (Common Random Numbers), damit Unterschiede strukturell und nicht zufällig sind. Der **Zielbetrag bleibt szenario-eigen** (vorbelegt mit dem jeweils geplanten Endvermögen) – nur so misst die Erfolgswahrscheinlichkeit, wie oft ein Szenario sein *eigenes* Versprechen hält. Ergebnis als Vergleichstabelle plus Median-Linien je Szenario; bei einem einzelnen Szenario unverändert der bisherige Fächer. (2) Neuer Bereich **Einflussfaktoren** (eigener Button, eigener Dialog) mit einem **Tornado-Chart** nach dem One-at-a-time-Verfahren: neues reines Modul `sensitivity.ts` mit sieben Treibern, je Treiber an-/abwählbar und mit **pflichtiger, frei definierbarer Bandbreite ohne Default**. Das **Pensionsalter ist bewusst nicht enthalten** (Begründung: 9.18). Neue Kapitel 3.6.6, 4.12.6, 4.13, 9.18; 20 Tests ergänzt (60 → 80). Keine DB-Änderung, keine Verhaltensänderung bestehender Pläne. **Ausserdem vier Dokumentationsfehler korrigiert:** Kap. 1.2 nannte noch Monte-Carlo, Hypothekarzinsen und Immobilien-Wertsteigerung als nicht umgesetzt (seit 0.5/0.7 vorhanden); Kap. 4.6.5 endete mit einem widersprüchlichen Restsatz zur fehlenden Wertsteigerung; Kap. 5.2/5.3/5.5.2/8.1 waren bei Migrationszahl, Dateiliste, Komponentenliste und Testzahlen veraltet; der Glossar-Eintrag „Szenario" beschrieb noch das Modell vor V6. |
 | 0.9 | 2026-07-18 | Claude (Opus 4.8) | **UI-Umbau und Planstart.** (1) Die Grafiken liegen neu im eigenen Bereich **Grafiken** (Dialog, Button oben) statt unter der Matrix. (2) Kennzahl **Geschätzter Nachlass** entfernt – sie war identisch mit dem nominalen Endvermögen. (3) **Monte-Carlo-Button** nach oben zu den Szenario-Aktionen verschoben. (4) Neues Profilfeld **Planstart (Jahr)** (`Scenario.startYear`, Migration; reine Anzeige, Berechnung bleibt in relativen Jahren) – erscheint auf der Zeitachse. (5) Zeitachse zeigt neu die **Lebensphasen als Segmente** (Breite = Dauer, Einfärbung nach Phasentyp, Jahresspanne). (6) **Lebensphase bearbeiten** neu als Popup statt Panel unter der Tabelle. (7) **Vermögensverlauf** über **alle Jahre** statt nur über die Phasengrenzen – dafür führt `computePlan` das Vermögen neu pro Jahr mit (`YearPoint.wealthNominal/wealthReal`). Zwei Tests ergänzt (58 → 60). |
 | 0.8 | 2026-07-18 | Claude (Opus 4.8) | **Szenario-Hierarchie (V6)** – grösste Umstrukturierung bisher. Der **Plan** ist neu ein schlanker Behälter ohne Finanzdaten; die berechenbare Einheit ist das **Szenario**, das Grundprofil (inkl. **Pensionsalter** → Frühpensionierungs-Szenarien), Phasen und Elemente trägt. Jeder Plan erhält beim Anlegen automatisch ein **Basisszenario**; weitere Szenarien entstehen als vollständige Kopie eines beliebigen Szenarios und hängen als **Baum** darunter (Sidebar zeigt die Verschachtelung). Kopierte Phasen/Elemente tragen Herkunfts-Verweise (`sourcePhaseId`, `sourceElementId`) – darauf beruht die **Abweichungs-Markierung**: geändert = gelb, neu = grün, entfernt = graue Geisterzeile (eigene Theme-Tokens für alle drei Farbschemata). Charts vergleichen neu die Geschwister-Szenarien. Datenmodell: neue Tabelle `Plan`, bisheriger `Plan` → `Scenario` (IDs erhalten), `planId` → `scenarioId` in Person/Phase/FinancialElement. API neu unter `/api/scenarios/*`. Neue Kapitel 2.1, 3.2, 4.13; 9 Diff-Tests + Migrations-Test (48 → 58). **Migration mit echtem Postgres (PGlite) verifiziert**, inkl. verschachtelter Szenarien und Cascade. |
@@ -858,6 +859,47 @@ Tornado Pflichteingaben braucht. Ein Hinweis am Ende der Parameterliste benennt,

 Referenz: `src/components/SensitivityDialog.tsx`, `src/components/AppShell.tsx`.

+### 3.6.7 Detailansichten je Element und je Lebensphase
+
+Jede Element-Zeile und jeder Phasenkopf trägt oben rechts ein **Expand-Icon** (erscheint beim
+Überfahren). Es öffnet eine **Nur-Lese-Detailansicht** mit Reitern.
+
+**Element** – zwei Reiter:
+
+| Reiter | Inhalt |
+|---|---|
+| Verlauf | Liniendiagramm über **alle Planjahre**, nicht nur die Phasengrenzen. Bei einer Immobilie drei Reihen (Eigenkapital, Verkehrswert, Restschuld). Darunter eine Tabelle Beginn/Ende je Lebensphase. |
+| Rechenweg | Die Herleitung je Phase und je Übergang (siehe [4.14](#414-verlaufswerte-brücken-und-rechenwege)) |
+
+**Lebensphase** – drei Reiter:
+
+| Reiter | Inhalt |
+|---|---|
+| Übersicht | Typ, Dauer, Vermögen Beginn/Ende; Vermögensaufteilung als gestapelter Balken (Beginn und Ende) |
+| Wasserfall | Vermögens- und Cash-Wasserfall ([4.14.2](#4142-die-beiden-wasserfälle)) |
+| Rechenweg | Quote, Spar-/Verzehrrate, Cash-Fortschreibung, Vermögen, Phasentyp, Cash-Übergang |
+
+Der Phasenkopf reagiert bereits auf Klick (öffnet das Bearbeiten-Popup); das Expand-Icon stoppt
+deshalb die Ereignis-Weitergabe, sonst gingen beide Dialoge gleichzeitig auf.
+
+Zusätzlich öffnet der Button **Rechenwege** in der Aktionsleiste die **plan-weiten** Grössen:
+Deflatoren, AHV-Beitragskarriere je Person und Ruinalter.
+
+Referenz: `src/components/DetailView.tsx`, `src/components/PlanView.tsx`.
+
+### 3.6.8 Systemparameter-Ansicht
+
+Eigener Eintrag in der Seitenleiste (über der SPEZIFIKATION). Zeigt alle fest hinterlegten
+Systemgrössen, gruppiert nach AHV, Vorsorge und Steuern, je mit **Wert, Bedeutung, Herleitung,
+Quelle und Stand**.
+
+Die Einträge stammen aus `SYSTEM_PARAMETERS` in `src/lib/constants.ts` – **derselben Datei, aus
+der die Berechnung liest**. Ein Auseinanderlaufen von angezeigtem und gerechnetem Wert ist damit
+konstruktiv ausgeschlossen. Abgeleitete Grössen wie `AHV_MAX_ANNUAL_SINGLE` zeigen ihre
+Herleitung (`2 × R0 × 13`) statt nur das Ergebnis.
+
+Referenz: `src/components/SystemParametersView.tsx`, `src/lib/constants.ts`.
+
 ## 3.7 Bedienoberfläche

 ### 3.7.1 Layout
@@ -1764,6 +1806,127 @@ spannt deshalb über `min…max`; welche Eingabe zu welchem Ende gehört, zeigt

 Referenz: `src/lib/sensitivity.ts`, `src/components/SensitivityDialog.tsx`.

+## 4.14 Verlaufswerte, Brücken und Rechenwege
+
+Dieses Kapitel beschreibt, was `computePlan` über die reinen Ergebniswerte hinaus mitführt –
+die Grundlage der Detailansichten (Roadmap Nr. 43) und der Transparenz-Offenlegung (Nr. 41).
+
+### 4.14.1 Verlaufswerte je Element
+
+`ElementPhaseComputed.yearly` hält einen Punkt **pro Phasenjahr** je Element (Jahr, Alter, Wert;
+bei Immobilien zusätzlich Verkehrswert und Restschuld).
+
+Der Grund ist derselbe wie beim Vermögensverlauf in Version 0.9: Nur Start- und Endwert zu kennen
+reicht nicht. Eine Anlage mit 5 % über 20 Jahre wächst **konvex** – eine Gerade zwischen den
+Phasengrenzen wäre sichtbar falsch und würde den Zinseszins optisch unterschlagen. Der Punkt wird
+am **Jahresende** erfasst, nach Verzinsung und Tilgung, konsistent zum `YearPoint`.
+
+### 4.14.2 Die beiden Wasserfälle
+
+Ein Wasserfall zerlegt eine Veränderung in ihre Summanden. Der entscheidende Punkt ist, **welche
+Posten dazugehören** – und hier liegt eine Falle:
+
+> **Sparraten, Amortisationen und Zusatzinvestitionen sind Umbuchungen, keine Verluste.** Eine
+> 3a-Einzahlung verlässt das Cash und erhöht im selben Zug das 3a-Guthaben; das Vermögen bleibt
+> unverändert. Eine Amortisation senkt das Cash und die Hypothek – das Eigenkapital steigt sogar.
+> Als Abgang im Vermögens-Wasserfall gezeichnet würden diese Posten eine Vermögensminderung
+> vortäuschen, die es nicht gibt.
+
+Deshalb gibt es **zwei** Zerlegungen mit unterschiedlichen Fragestellungen:
+
+**`WealthBridge` – „Warum hat sich mein Vermögen so entwickelt?"**
+
+```
+Vermögen Ende Vorphase
+  + einmaliger Zufluss  −  einmalige Kosten          ⎫
+  − Steuern am Übergang (Kapitalbezug, Grundstückgewinn) ⎬ Vermögensänderungen
+  − verrentetes PK-Kapital (verlässt die Bilanz)     ⎪ AN der Phasengrenze
+  ± Verkaufspreis minus Verkehrswert                  ⎭
+= Vermögen zu Phasenbeginn
+  + Spar-/Verzehrquote (Summe über alle Phasenjahre)  ⎫
+  + Kapitalerträge (PK, 3a, Sonstiges Vermögen)       ⎬ INNERHALB der Phase
+  + Wertsteigerung der Liegenschaft                   ⎪
+  + PK-Beiträge                                       ⎭
+= Vermögen am Phasenende
+```
+
+Zwei Posten verdienen eine Erläuterung:
+- **PK-Beiträge sind ein echter Zugang.** Sie belasten das Cash nicht (im Nettolohn bereits
+  abgezogen), erhöhen aber das Vorsorgekapital – anders als 3a-Beiträge, die aus dem Cash fliessen
+  und deshalb reine Umbuchung sind.
+- **Verrentetes PK-Kapital verlässt die Bilanz.** Bei der Verrentung wird Kapital in einen
+  Rentenstrom umgewandelt; der Saldo fällt auf 0. Ohne diesen Posten ginge die Brücke am
+  Pensions-Übergang nicht auf.
+
+**`CashBridge` – „Wohin ist mein Cash geflossen?"**
+
+```
+Cash Ende Vorphase (Phase 1: Cash-Anfangswert)
+  + Kapitalzufluss + einmaliger Zufluss
+  − Sofort-Tilgung/Sonderamortisation − einmalige Kosten
+  − Investitionen am Phasenanfang
+= Cash zu Phasenbeginn
+  + Spar-/Verzehrquote − Sparraten − Amortisationen/Tilgungen + Bezugsraten
+= Cash am Phasenende
+```
+
+Beide Strukturen führen einen **Restposten** (`residual`) mit: die Differenz zwischen dem
+gerechneten Endwert und der Summe der Summanden. Er entsteht nur durch die Rundung der einzelnen
+Posten auf ganze Franken und liegt im einstelligen Bereich; ein grösserer Wert wäre ein Hinweis
+auf eine unvollständige Zerlegung. Zwei Tests prüfen ihn über einen Plan, der alle Element-Arten
+und Übergangs-Entscheide enthält.
+
+### 4.14.3 Rechenweg-Protokoll
+
+`computePlan(plan, sample?, { explain: true })` legt zu jedem Ergebnis die Herleitung ab:
+
+```ts
+interface TraceStep { label; formula?; substituted?; result; unit?; note? }
+interface Trace     { title; specAnchor?; steps: TraceStep[] }
+```
+
+`formula` ist die abstrakte Regel, `substituted` dieselbe Regel **mit den eingesetzten Zahlen**,
+`note` benennt eine an dieser Stelle geltende Vereinfachung.
+
+**Der Architekturentscheid dahinter ist der wichtigste Teil dieses Kapitels.** Die naheliegende
+Alternative wäre, die Formeln im UI nachzurechnen und anzuzeigen. Das ergäbe eine **zweite
+Implementierung jeder Formel** – und damit die Möglichkeit, dass die angezeigte Herleitung still
+von der tatsächlichen Rechnung abdriftet. Bei einem Tool, dessen Kernversprechen die rechnerische
+Korrektheit ist, wäre das die gefährlichste Variante überhaupt: Ein Nutzer, der nachrechnet und
+eine Abweichung findet, verliert mehr Vertrauen, als eine Black Box je gekostet hätte.
+
+Deshalb entstehen die Schritte **innerhalb** von `computePlan`, als Nebenprodukt der Rechnung, die
+ohnehin läuft. Die Erklärung *ist* die Rechnung.
+
+Zwei Konsequenzen daraus:
+- **Standardmässig aus.** Die Monte-Carlo-Simulation ruft `computePlan` zehntausendfach auf und
+  darf von der Protokollierung nichts merken. Ein Test prüft, dass `explain` die Ergebniswerte
+  nicht verschiebt.
+- **Die Arithmetik wird nicht umgestellt.** Wo für das Protokoll eine Zwischengrösse gebraucht
+  wird (etwa der Renditeanteil eines Jahres), wird sie als **Differenz** abgeleitet statt die
+  Formel umzuformen – `a × (1 + r)` und `a + a × r` sind in Gleitkomma-Arithmetik nicht bitgleich.
+  Die 43 Golden Tests laufen unverändert.
+
+**Abdeckung.** Vollständig über alle Ebenen: Element je Phase (Einkommen, Ausgaben, PK, 3a,
+Immobilie, Sonstiges Vermögen, Schulden, AHV-/PK-Renten), Element je Übergang (Bezugsarten,
+Verkauf inkl. Grundstückgewinnsteuer, Teilverkauf, Sonderamortisation, Sofort-Tilgung),
+Phasen-Kennzahlen (Quote, Spar-/Verzehrrate, Cash-Fortschreibung, Vermögen, Phasentyp,
+Cash-Übergang) und Plan-Ebene (Deflatoren, AHV-Karriere je Person, Ruinalter).
+
+**Verweis in die Spezifikation.** Jeder Trace trägt optional einen `specAnchor` auf das zugehörige
+Kapitel dieses Dokuments; die App springt von dort in die eingebaute SPEZIFIKATION-Ansicht (die
+Anker erzeugt `rehype-slug`). Ein Test liest `SPEZIFIKATION.md` und prüft, dass **jeder** Verweis
+eine existierende Überschrift trifft – sonst würden die Links bei einer Umbenennung still ins
+Leere zeigen.
+
+**Wo die Erklärung gerechnet wird.** Nicht auf dem Server: `computePlan` ist rein und läuft im
+Browser (wie schon bei Monte Carlo und Sensitivitätsanalyse), und der Client hält den
+`PlanInput` ohnehin. Die Detailansicht rechnet die erklärte Fassung beim Öffnen lokal – kein
+API-Umbau, keine grössere Antwort, keine Serverlast, und per Konstruktion identisch zum
+Serverergebnis.
+
+Referenz: `src/lib/calculations.ts`, `src/components/DetailView.tsx`.
+
 ---

 # 5. Technische Spezifikation
@@ -1804,7 +1967,7 @@ FPT/
 │   │   ├── page.tsx             Einstiegsseite (lädt /api/auth/me → AppShell)
 │   │   ├── layout.tsx           Root-Layout, Theme-Init-Script, Metadata
 │   │   └── globals.css          Tailwind + semantische Farb-Tokens (3 Themes)
-│   ├── components/              15 React-Komponenten (alle "use client")
+│   ├── components/              17 React-Komponenten (alle "use client")
 │   ├── generated/prisma/        Generierter Prisma-Client (nicht editieren)
 │   ├── lib/                     Domänenlogik (siehe 5.3)
 │   └── middleware.ts            Zugriffsschutz (Edge-Runtime)
@@ -1837,6 +2000,7 @@ PlanComputed             ← an den Client geliefert
 | `constants.ts` | Schweizer Systemparameter |
 | `montecarlo.ts` | Monte-Carlo-Simulation (Sampler + Treiber), Szenario-Vergleich und Element-Gruppierung über die Herkunfts-Kette. Keine I/O, läuft im Browser. |
 | `sensitivity.ts` | Sensitivitätsanalyse / Tornado: Treiber-Katalog, Parameter-Transformationen, `computeTornado`. Rein, läuft im Browser. |
+| `constants.ts` (erweitert) | zusätzlich `SYSTEM_PARAMETERS`: dieselben Werte maschinenlesbar mit Bedeutung, Herleitung, Quelle und Stand – Grundlage der Systemparameter-Ansicht |
 | `diff.ts` | Abweichungs-Erkennung eines Szenarios gegen sein Eltern-Szenario (Kap. 3.2.6) |
 | `queries.ts` | Prisma-Includes, `toPlanInput()`, Ownership-Abfragen |
 | `db.ts` | Prisma-Singleton (Global-Cache im Dev, verhindert Connection-Leak bei HMR) |
@@ -2092,7 +2256,9 @@ wird der Plan neu geladen; die Berechnung kommt immer vom Server.
 | `SparquoteChart` | 64 | Einkommen/Ausgaben pro Jahr mit Spar-/Verzehrbändern |
 | `MonteCarloDialog` | ~600 | Monte-Carlo-Dialog: Erklärung, Szenario-Auswahl, Eingaben, Lauf, Vergleichstabelle + Fächer |
 | `SensitivityDialog` | ~330 | Einflussfaktoren: Erklärung, Treiber-Auswahl mit Bandbreiten, Tornado + Tabelle |
-| `SpecView` | 50 | Rendert `SPEZIFIKATION.md` (via `/api/spec`) als lesbares Dokument |
+| `DetailView` | ~470 | Detailansichten Element/Phase, Wasserfall-Darstellung, Rechenweg-Blöcke, plan-weite Rechenwege |
+| `SystemParametersView` | ~90 | Systemparameter mit Wert, Bedeutung, Herleitung, Quelle und Stand |
+| `SpecView` | 65 | Rendert `SPEZIFIKATION.md` (via `/api/spec`) als lesbares Dokument, inkl. Sprungmarken aus den Rechenwegen |
 | `InfoBubble` | 28 | Hilfe-Tooltip |

 ### 5.5.3 Wiederverwendungsmuster
@@ -2322,10 +2488,11 @@ Include `src/**/*.test.ts`). Es gibt **keine** Komponenten-, API- oder E2E-Tests
 |---|---|---|
 | `calculations.test.ts` | 43 | AHV-Rentenformel, Immobilie, Teilverkauf, Sonderamortisation, AHV einkommensabhängig, „V5 Golden Tests" |
 | `sensitivity.test.ts` | 14 | Treiber-Transformationen (Reinheit, Einheiten, Kappung), Verfügbarkeit, Tornado-Sortierung und -Richtung |
+| `explain.test.ts` | 12 | Verlaufswerte je Element, Vollständigkeit beider Wasserfall-Zerlegungen, Rechenweg-Protokoll, Gültigkeit der Spezifikations-Verweise |
 | `montecarlo.test.ts` | 13 | Determinismus, Volatilität/Vol-Drag, Böden, Reproduzierbarkeit; Element-Gruppierung und Szenario-Vergleich |
 | `diff.test.ts` | 9 | Abweichungs-Erkennung gegen das Eltern-Szenario |
 | `migrations.test.ts` | 1 | spielt alle Migrationen gegen echtes PostgreSQL (PGlite) ein |
-| **Total** | **80** | |
+| **Total** | **92** | |

 ## 8.2 Testfälle

@@ -2361,6 +2528,18 @@ Include `src/**/*.test.ts`). Es gibt **keine** Komponenten-, API- oder E2E-Tests
 | **Tornado: Lebensdauer** | verschiebt nur die letzte Phase; Kappung bei mindestens 1 Jahr |
 | **Tornado: Verfügbarkeit** | Treiber ohne passende Elemente werden ausgeblendet (z. B. Immobilien-Wertsteigerung ohne Immobilie) |
 | **Tornado: Sortierung/Richtung** | absteigend nach Spannweite; Treiber ohne Bandbreite hat Spannweite 0 und steht zuunterst; höhere Ausgaben → tieferes, höhere Rendite → höheres Endvermögen |
+| **Verlauf: ein Punkt je Jahr** | je aktivem Element genau `durationYears` Punkte pro Phase |
+| **Verlauf: Konvexität** | 200'000 @ 5 % + 10'000 Sparbeitrag: Jahr 1 = 220'000, und die **Jahreszuwächse wachsen** – eine Gerade zwischen den Phasengrenzen hätte konstante Zuwächse |
+| **Verlauf: Immobilie** | Verkehrswert, Restschuld und Eigenkapital werden getrennt geführt; Eigenkapital = Verkehrswert − Restschuld |
+| **Brücke: Vermögen geht auf** | Restposten ≤ 5 CHF über einen Plan mit allen Element-Arten und Übergangs-Entscheiden |
+| **Brücke: Cash geht auf** | dito; Start- und Endwert stimmen mit `cashStart`/`cashEnd` überein |
+| **Brücke: Umbuchung** | 5 × 12'000 Sparbeitrag: Cash −60'000, Vermögen **unverändert** – die Sparrate erscheint nur im Cash-Wasserfall |
+| **Brücke: PK-Beiträge** | 4 × 10'000 PK-Beitrag: Vermögen +40'000, Cash unbelastet |
+| **Brücke: Übergangsposten** | Verrentung, Kapitalbezugssteuer und Einmalposten erscheinen in der Brücke der **Folge**phase |
+| **explain: Standardmässig aus** | ohne Option keine Traces; mit Option identische Ergebniswerte (Endvermögen, Cash, Ruinalter) |
+| **explain: Abdeckung** | Traces auf Element-, Übergangs-, Phasen- und Plan-Ebene vorhanden |
+| **explain: eingesetzte Zahlen** | jeder Schritt trägt die Formel **und** die substituierte Fassung; das Resultat stimmt mit dem Ergebniswert überein |
+| **explain: Spec-Verweise** | jeder `specAnchor` trifft eine existierende Überschrift in `SPEZIFIKATION.md` (gegen die echte Datei geprüft) |
 | **Vermögen je Jahr** | 100k @ 10 % über 3 J. → 110k/121k/133.1k je Jahrespunkt; Endjahr = Phasen-Endvermögen |
 | **Vermögen real** | 100k bei 10 % Inflation → real 90'909 |
 | Test 1 – Ansparen | Einkommen +2 % nominal, Ausgaben real flach: Endvermögen 761'654 nominal / 565'928 real (±1 %), kein negatives Cash |
@@ -2623,6 +2802,39 @@ Migration), hat aber den Preis, dass eine Analyse bei jedem Öffnen neu parametr
 Bei der Monte-Carlo-Simulation über mehrere Szenarien fällt das stärker ins Gewicht als zuvor,
 weil dort mehr Eingaben zusammenkommen.

+---
+## 9.20 Transparenz legt auch die Vereinfachungen offen
+
+Die vollständige Offenlegung der Rechenwege macht sichtbar, was das Modell **nicht** kann: die
+nach der Pensionierung nicht indexierte AHV-Rente ([9.11](#911-ahv-rente-wird-nach-der-pensionierung-nicht-indexiert)),
+den pauschalen Netto-Brutto-Faktor 1.12 ([4.4.5](#445-netto-brutto-umrechnung-für-die-ahv)), die
+nicht indexierten Spar- und Bezugsraten ([9.6](#96-spar--und-bezugsraten-werden-nicht-indexiert))
+und die fehlende Steuerberechnung ([9.14](#914-keine-steuerschätzung)).
+
+Das ist der eigentliche Wert der Offenlegung und kein Nebeneffekt. Entscheidend ist aber, dass die
+Erklärtexte die Grenze **mitnennen**, statt sie zu übergehen – dafür ist das Feld `note` je
+Rechenschritt da. Ein fachkundiger Nutzer, der eine Vereinfachung selbst entdeckt, nachdem ihm
+volle Transparenz zugesagt wurde, zieht den härteren Schluss.
+
+## 9.21 Wasserfall: die Zuordnung ist eine Interpretation
+
+Welcher Posten in welchen Wasserfall gehört, ist eine **fachliche Entscheidung** und nicht aus den
+Zahlen ableitbar. Die hier getroffene – Umbuchungen nur im Cash-Wasserfall, echte Zu- und Abgänge
+nur im Vermögens-Wasserfall ([4.14.2](#4142-die-beiden-wasserfälle)) – ist begründet, aber nicht
+die einzig denkbare. Wer die Sparrate als „gebundenes Geld" verstanden wissen will, würde sie
+anders einordnen.
+
+Konkret uneindeutig sind zwei Fälle:
+- **Amortisation** senkt Cash und Hypothek. Im Vermögens-Wasserfall taucht sie nicht auf, obwohl
+  sie das *Eigenkapital* erhöht – die Erhöhung ist bereits im unveränderten Vermögenssaldo
+  enthalten.
+- **Verrentung** erscheint als Vermögensabgang, obwohl der Gegenwert als Rentenstrom weiterlebt.
+  Der Rentenstrom ist im Modell aber kein Bilanzposten, sondern Einkommen; er taucht in den
+  Folgejahren über die Quote wieder auf.
+
+Der Restposten (`residual`) ist die Kontrollgrösse dafür, dass die gewählte Zerlegung wenigstens
+**vollständig** ist – nicht dafür, dass sie die einzig sinnvolle ist.
+
 ---

 # 10. Glossar
@@ -2633,6 +2845,10 @@ weil dort mehr Eingaben zusammenkommen.
 | **Szenario** | Die berechenbare Einheit (seit V6): trägt Grundprofil, Phasenkette und Elemente. Jeder Plan hat genau ein Basisszenario; weitere entstehen als vollständige Kopie eines beliebigen Szenarios und hängen als Baum darunter |
 | **Logisches Element** | Dasselbe finanzielle Element über Szenariogrenzen hinweg, erkannt über die Herkunfts-Kette `sourceElementId` – Grundlage der einmaligen Parametereingabe im Szenario-Vergleich ([4.12.6](#4126-mehrere-szenarien-im-vergleich)) |
 | **Spannweite (Tornado)** | Differenz zwischen dem Ergebnis beim tiefen und beim hohen Wert eines Treibers; bestimmt Balkenlänge und Rangfolge |
+| **Umbuchung** | Bewegung, die Geld zwischen Cash und einem Vermögenswert verschiebt, ohne das Vermögen zu verändern (Sparrate, Amortisation, Zusatzinvestition). Erscheint nur im Cash-Wasserfall |
+| **Vermögens-/Cash-Brücke** | Zerlegung der Vermögens- bzw. Cash-Veränderung einer Phase in ihre Summanden (`WealthBridge` / `CashBridge`) |
+| **Restposten** | Differenz zwischen gerechnetem Endwert und der Summe der Brücken-Summanden; reine Rundung, Kontrollgrösse für die Vollständigkeit |
+| **Rechenweg (Trace)** | Protokoll der Rechenschritte mit Formel, eingesetzten Zahlen, Ergebnis und geltender Vereinfachung; entsteht innerhalb von `computePlan` |
 | **Grundprofil** | Haushaltsform, Personen (Alter, Pensionsalter, Name), Inflationsannahme |
 | **Lebensphase** | Zeitabschnitt mit fester Dauer; darf keine Pensionierung überspannen |
 | **Phasentyp** | `ERWERB` / `PENSION` / `MIXED`; abgeleitet, nie gespeichert |
@@ -2661,4 +2877,4 @@ weil dort mehr Eingaben zusammenkommen.

 ---

-*Ende der Spezifikation v0.10*
+*Ende der Spezifikation v0.11*