UI-Gesamtumbau: Du-Form, Inspector-Panel, Onboarding-Assistent, Tour, Palette

Rein an der Oberflaeche -- Berechnung, Datenmodell und API-Semantik unveraendert (103 Tests unveraendert gruen). Paket A (Fundament): - durchgehend Du-Form und echte Umlaute in allen sichtbaren Texten, inkl. API-Fehlermeldungen (vorher Mix aus Sie/Du und ae/oe/ue) - neue UI-Primitiven (ui.tsx): Button, Modal mit ESC/Fokus-Falle/Animation, Bestaetigungs-Dialog statt window.confirm, Toasts statt alert, Skeleton-Loader, EmptyState - eigene Attention-Farbe (Amber) fuer offene Entscheide, getrennt vom Akzent - Micro-Interactions mit prefers-reduced-motion-Fallback Paket B (Onboarding, Roadmap Nr. 10): - gefuehrter Plan-Assistent in 5 Schritten; Einkommen bewusst pro Person (raeumt die 9.9-AHV-Falle aus); reine Orchestrierung bestehender Endpunkte - Beispielplan mit einem Klick; Uebergaenge absichtlich offen - interaktive Tour ueber die Planansicht (localStorage, jederzeit neu startbar) - abgeleitete "Naechste Schritte"-Karte (offene Entscheide, fehlende Elemente, fehlende Pensionsphase, Ruin -> Einflussfaktoren) Paket C (Struktur): - Inspector-Panel rechts statt Modals fuer alle Einzel-Bearbeitungen; Matrix bleibt sichtbar, Zellklick wechselt den Inhalt - Phasenkopf auf vier Kern-Infos entschlackt (Rest in der 0.11-Detailansicht) - Matrix mit eigenem Scrollbereich, Koepfe beidachsig fixiert - Sidebar-Gruppen "Meine Plaene" / "Wissen"; "So rechnet FPT" statt SPEZIFIKATION; "Szenario-Profil" statt "Plan-Einstellungen" - Aktions-Icons ohne Hover sichtbar (Touch) Paket D (Extras): - Sparklines je Element-Zeile aus den 0.11-Verlaufswerten - Befehls-Palette (Ctrl/Cmd+K) - Ruin-Banner verlinkt auf die Einflussfaktoren Nebenbei: der ProfileMenu-Lint-Fehler und der Selection-Rest (9.17) sind behoben -- npm run lint laeuft erstmals fehlerfrei. SPEZIFIKATION auf 0.13: neue Kapitel 3.2.8, 3.7.6-3.7.9, 9.23, 9.24; 3.6.3 und 3.7.1 ueberarbeitet, 9.17 bereinigt. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-19 07:40:42 +02:00
parent e1f74fca95
commit c2fb82b0de
60 changed files with 2915 additions and 1210 deletions
@@ -4,10 +4,10 @@
 | | |
 |---|---|
 | **Dokument** | Funktionale und Technische Spezifikation FPT |
-| **Version** | 0.12 |
+| **Version** | 0.13 |
 | **Datum** | 2026-07-18 |
 | **Status** | Lebendes Dokument |
-| **Codestand** | Arbeitsstand nach `4791dcc` inkl. lesbarer Wasserfälle und Verkaufspreis-Abgleich (Branch `main`) |
+| **Codestand** | Arbeitsstand nach `e1f74fc` inkl. UI-Gesamtumbau (Pakete A–D) und geführtem Onboarding (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.13 | 2026-07-18 | Claude (Fable 5) | **UI-Gesamtumbau** – rein an der Oberfläche, Berechnung, Datenmodell und API-Semantik unverändert. **(A) Fundament:** durchgehende **Du-Form** und **echte Umlaute** in allen sichtbaren Texten (inkl. API-Fehlermeldungen); neue UI-Primitiven in `ui.tsx` (Button, Modal mit ESC/Fokus-Falle/Animation, Bestätigungs-Dialog statt `window.confirm`, Toasts statt `alert`, Skeleton-Loader, EmptyState); eigene **Attention-Farbe** (Amber) für offene Entscheide, getrennt vom Akzent; Micro-Interactions mit `prefers-reduced-motion`-Fallback. **(B) Onboarding (Roadmap Nr. 10):** geführter **Plan-Assistent** in fünf Schritten (reine Orchestrierung bestehender Endpunkte, Einkommen bewusst pro Person – räumt die 9.9-Falle aus), **Beispielplan mit einem Klick** (Übergänge absichtlich offen – die Ampel lehrt sich selbst), **interaktive Tour** über die Planansicht, abgeleitete **«Nächste Schritte»**-Karte. **(C) Struktur:** Einzel-Bearbeitungen laufen neu über ein rechtes **Inspector-Panel** statt Modals (Matrix bleibt sichtbar; Klick auf andere Zelle wechselt den Inhalt); **Phasenkopf entschlackt** auf vier Kern-Infos (Rest wohnt in der Detailansicht aus 0.11); Matrix mit eigenem Scrollbereich und **beidachsig fixierten Köpfen**; Sidebar-Gruppen «Meine Pläne»/«Wissen» («So rechnet FPT», Systemparameter); Terminologie-Fix «Szenario-Profil» statt «Plan-Einstellungen»; Aktions-Icons auch ohne Hover sichtbar (Touch). **(D) Extras:** **Sparklines** je Element-Zeile (aus den 0.11-Verlaufswerten, keine Neuberechnung), **Befehls-Palette** (Ctrl/Cmd+K), Ruin-Banner verlinkt auf die Einflussfaktoren. Neue Kapitel 3.2.8, 3.7.6–3.7.9, 9.23, 9.24; 9.17 bereinigt (der `Selection`-Rest und der ProfileMenu-Lint-Fehler sind behoben – `npm run lint` ist erstmals fehlerfrei). Testbestand unverändert 103. |
 | 0.12 | 2026-07-18 | Claude (Opus 4.8) | **Lesbarkeit der Wasserfälle, Verkaufspreis-Abgleich und Erklärung wirkungsloser Tornado-Treiber.** (1) Die beiden Wasserfälle werden **nicht mehr mit Recharts** gezeichnet, sondern als eigene liegende Darstellung: Verbindungslinien zwischen den Balken, Wertbeschriftung an jedem Schritt, Abschnitts-Überschriften („Am Übergang" / „Innerhalb der Phase") und eine aufklappbare Tabelle mit **laufendem Zwischenstand**. Anlass war, dass die bisherige Darstellung faktisch nicht lesbar war – die Zahlen waren korrekt, die Grafik nicht. (2) Der Restposten beider Brücken wird bei Abweichung neu als **Fehlermeldung** ausgewiesen statt als beiläufige „Rundungsdifferenz"; eine nicht aufgehende Zerlegung ist ein Rechenfehler und kein Schönheitsproblem. (3) **Verkaufspreis einer Immobilie** wird beim Wechsel auf „Verkaufen" neu mit dem **modellierten Verkehrswert** vorbelegt; der Dialog weist Verkehrswert und Abweichung aus und warnt ab 10 % Differenz (Kap. 3.5.8, 9.22). Damit fällt auf, wenn angenommene Wertsteigerung und erwarteter Verkaufspreis nicht zusammenpassen. (4) Der Tornado erklärt neu **Nullbalken** statt sie stumm zu zeigen – insbesondere den Fall, dass die Immobilien-Wertsteigerung bei einem Verkauf nachweislich wirkungslos ist (`ineffectiveReason`, Kap. 4.13.5). Neue Kapitel 3.5.8, 4.13.5, 9.22; 11 Tests ergänzt (92 → 103), darunter die Invariante `residual === 0` über sieben Plankonstellationen. Keine DB-Änderung, keine Änderung an der Berechnung. |
 | 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. |
@@ -245,7 +246,15 @@ Zweistufig:

 ### 3.2.1 Plan erstellen

-Dialog mit Name plus dem vollständigen Grundprofil:
+Der «+»-Knopf öffnet eine Auswahl mit drei Wegen:
+
+| Weg | Für wen | Was passiert |
+|---|---|---|
+| **Geführt erstellen** (empfohlen) | neue Nutzer | der Assistent aus [3.2.8](#328-geführter-assistent-und-beispielplan) |
+| **Leer starten** | geübte Nutzer | der bisherige Dialog (unten) – nur Grundprofil, keine Phasen/Elemente |
+| **Beispielplan ansehen** | Erkunden | legt einen fiktiven, voll ausgefüllten Plan an ([3.2.8](#328-geführter-assistent-und-beispielplan)) |
+
+Der Dialog «Leer starten» fragt Name plus das vollständige Grundprofil:

 | Feld | Typ | Default | Wertebereich |
 |---|---|---|---|
@@ -353,6 +362,32 @@ und Grafiken beschriften damit Jahre statt nur Alter. Die Berechnung rechnet unv
 Beim Anlegen wird das laufende Jahr vorbelegt; bestehende Szenarien wurden per Migration darauf
 gesetzt. Kalenderjahr eines Planjahrs: `startYear + (Jahr − 1)`.

+### 3.2.8 Geführter Assistent und Beispielplan
+
+**Der Plan-Assistent** (Roadmap Nr. 10: «Schritt für Schritt statt leerer Matrix») fragt in
+fünf Schritten in Alltagssprache: (1) Grundprofil, (2) Lebensphasen – vom Tool anhand des
+Pensionsalters **vorgeschlagen** (dieselbe Kappungslogik `maxPhaseDuration` wie beim manuellen
+Anlegen; bei Paaren mit unterschiedlichem Pensionsalter inkl. Übergangsphase), Dauer editierbar,
+(3) Einkommen und Ausgaben plus Kontostand, (4) Vorsorge und Vermögen als Checkliste (PK, 3a,
+Wertschriften, Wohneigentum, Schulden – nur Angehaktes fragt Details; die AHV wird automatisch
+je Person angelegt), (5) Zusammenfassung.
+
+Zwei bewusste Entscheide:
+- **Einkommen wird pro Person erfasst**, nie als «Gemeinsam» – in Paar-Plänen zählt
+  Haushalts-Einkommen nicht für die AHV ([9.9](#99-gemeinsames-einkommen-zählt-bei-paaren-nicht-für-die-ahv));
+  der Assistent räumt diese Falle von Anfang an aus.
+- Technisch ist der Assistent **reine Orchestrierung bestehender Endpunkte** (Plan → Phase 1 →
+  Elemente samt Werten → Folgephasen; die Reihenfolge stellt sicher, dass die Phasen-Route die
+  Folgephasen korrekt vorbelegt). Kein neuer Endpunkt, keine Berechnungsänderung. Grenze: 9.23.
+
+**Der Beispielplan** («Beispiel: Alex Muster», `src/lib/demoplan.ts`) ist ein fiktiver, voll
+ausgefüllter Plan per Ein-Klick – ebenfalls reine Orchestrierung. Die Übergangs-Entscheide
+bleiben **absichtlich offen**: Der neue Nutzer sieht die Ampel («N offen») in Aktion und lernt
+das wichtigste Konzept am Beispiel statt aus einer Erklärung.
+
+Nach dem ersten Öffnen eines Plans mit Phasen startet einmalig die **Tour**
+([3.7.8](#378-tour-und-nächste-schritte)).
+
 ## 3.3 Lebensphasen

 ### 3.3.1 Phase anlegen
@@ -403,7 +438,7 @@ Referenz: `src/components/PhaseDetail.tsx`.
 ### 3.3.3 Phase löschen

 **Nur die letzte Phase** kann gelöscht werden – serverseitig geprüft (HTTP 400: „Nur die letzte
-Phase kann geloescht werden."). Damit bleibt die Kette der `sequenceNumber` lückenlos. Der
+Phase kann gelöscht werden."). Damit bleibt die Kette der `sequenceNumber` lückenlos. Der
 Löschen-Button erscheint im Detail-Panel nur bei der letzten Phase.

 Referenz: `src/app/api/phases/[phaseId]/route.ts` Zeilen 55–77.
@@ -797,27 +832,23 @@ Referenz: `src/components/Timeline.tsx`.

 ### 3.6.3 Phasenkopf-Kennzahlen

-Jeder Phasenkopf zeigt kompakt:
+Seit 0.13 ist der Phasenkopf bewusst **schlank** – zwölf Kennzahlen in 10-Pixel-Schrift liest
+niemand (Progressive Disclosure):

 | Kennzahl | Bedeutung |
 |---|---|
 | Name + Status-Icon | grünes Häkchen oder rotes Warnsymbol (Liquiditätslücke) |
 | Typ-Badge + Dauer | Erwerb / Pension / Misch, „N J." |
 | Alter je Person | `<Name> <StartAlter> → <EndAlter>` |
-| Einkommen | Jahr 1 → letztes Jahr |
-| Ausgaben | Jahr 1 → letztes Jahr (nominal) |
-| **Quote** bzw. **Verzehr** | Einkommen − Ausgaben; Label wechselt auf „Verzehr", wenn Jahr 1 negativ |
-| Geplante Sparrate | 3a + Sparbeitrag + Amortisation + Tilgung, im **ersten** Phasenjahr |
-| Geplante Verzehrrate | Summe der Bezugsraten |
-| Kapitalzufluss | nur wenn > 0: Verkäufe + PK-/3a-Bezüge aus dem Übergang **in** diese Phase |
-| Kapitalinvestitionen | nur wenn > 0: Zusatzinvestitionen + Sofort-Tilgungen |
-| **Einmaliger Zufluss** | nur wenn > 0: Bezeichnung + Betrag (grün), aus dem Übergang in diese Phase |
-| **Einmalige Kosten** | nur wenn > 0: Bezeichnung + Betrag (rot) |
-| Vermögen | Start → Ende (inkl. Cash) |
+| **Quote** bzw. **Verzehr** | Einkommen − Ausgaben; Label wechselt auf „Verzehr", wenn Jahr 1 negativ; rot bei Verzehr |
+| Vermögen | Start → Ende (inkl. Cash), hervorgehoben |
+| Einmalposten | nur als Kurzhinweis (Bezeichnung), wenn vorhanden |

-Die Einmalposten stehen bewusst **getrennt** von Kapitalzufluss/-investitionen: Eine Erbschaft
-ist kein Verkaufserlös und ein Poolbau keine Kapitalinvestition – eine Vermischung würde die
-Kennzahl falsch beschriften.
+Alles Weitere – Einkommen/Ausgaben Jahr 1 → letztes Jahr, geplante Spar-/Verzehrrate,
+Kapitalzufluss und -investitionen, die vollen Einmalposten – wohnt in der
+**Phasen-Detailansicht** (seit 0.11, [3.6.7](#367-detailansichten-je-element-und-je-lebensphase)),
+erreichbar über das Expand-Icon im Kopf. Die Kennzahlen selbst sind unverändert berechnet; nur
+der Anzeigeort hat gewechselt.

 Referenz: `src/components/PlanView.tsx` Zeilen 701–769.

@@ -931,11 +962,17 @@ Referenz: `src/components/SystemParametersView.tsx`, `src/lib/constants.ts`.

 ### 3.7.1 Layout

- **Sidebar** (Desktop ab `lg` fix, mobil als Overlay): Logo, „Übersicht", Planliste mit
-  Phasenanzahl, „+"-Button für neuen Plan.
+- **Sidebar** (Desktop ab `lg` fix, mobil als Overlay): Logo, Ctrl-K-Hinweis, „Übersicht",
+  Gruppe **«Meine Pläne»** (Szenario-Baum, «+»), Gruppe **«Wissen»** («So rechnet FPT» =
+  gerenderte Spezifikation, «Systemparameter»).
 - **Header**: Menü-Button (mobil), Plantitel, Profilmenü.
- **Hauptbereich**: Übersicht (Plan-Kacheln) oder Planansicht (Umschalter, Zeitachse,
-  Grundprofil-Leiste, Aktionsbuttons, Ruin-Banner, Matrix, Detail-Panel, Dashboard).
+- **Hauptbereich**: Übersicht (Plan-Kacheln bzw. EmptyState mit «Geführt starten» /
+  «Beispielplan») oder Planansicht (Umschalter, Zeitachse, Szenario-Profil-Leiste,
+  «Nächste Schritte», Ruin-Banner, Matrix, Inspector-Panel rechts).
+- Die **Matrix** hat einen eigenen Scrollbereich (max. 75 vh): Phasen-Köpfe (oben) und
+  Elementnamen (links) bleiben beim Scrollen in **beiden Achsen** fixiert.
+- Alle Aktions-Icons (Kopieren, Löschen, Detailansicht) sind auch ohne Hover leicht sichtbar –
+  auf Touch-Geräten gibt es kein Hover.

 ### 3.7.2 Farbschemata

@@ -975,7 +1012,75 @@ gefolgt von `onChanged()` → `loadDetail(planId, silent = true)`. Der „silent
 und Berechnung neu, ohne die `PlanView` zu demontieren – so bleibt die Scrollposition nach dem
 Schliessen eines Popups erhalten.

-Referenz: `src/components/AppShell.tsx` Zeilen 46–74.
+Referenz: `src/components/AppShell.tsx`.
+
+### 3.7.6 Sprache und UI-Primitiven
+
+Seit 0.13 gilt durchgehend die **Du-Form** (wie moderne CH-Finanz-Apps) und es werden überall
+**echte Umlaute** verwendet – zuvor mischte das UI «Übergang prüfen» mit «Uebersicht» und
+Sie- mit Du-Anrede. Der Sweep umfasst auch die API-Fehlermeldungen (z. B. „Nur die letzte
+Phase kann gelöscht werden.").
+
+Alle Bausteine liegen zentral in `src/components/ui.tsx`:
+
+| Baustein | Ersetzt / leistet |
+|---|---|
+| `Button` | vier Varianten (primary/secondary/danger/ghost), einheitliche Hover-/Active-Zustände |
+| `Modal` | Dialog mit ESC, Fokus-Falle, `aria-modal`, Einblend-Animation |
+| `ConfirmProvider` / `useConfirm` | ersetzt `window.confirm()` – Browser-Systemdialoge folgen keinem Farbschema |
+| `ToastProvider` / `useToast` | ersetzt `alert()`; Erfolgs- und Fehlermeldungen unten rechts |
+| `Skeleton` / `PlanSkeleton` | Struktur-Platzhalter statt «Lädt…»-Text |
+| `EmptyState` | einheitliche leere Zustände mit Erklärung und Aktion |
+| `InspectorShell` | das rechte Bearbeiten-Panel (3.7.7) |
+
+Mehrere Schichten (Panel + Dialog) teilen sich einen **ESC-Stapel**: ESC schliesst immer nur
+die oberste. Animationen (150–220 ms) respektieren `prefers-reduced-motion`.
+
+**Attention-Farbe:** Offene Entscheide tragen neu einen eigenen Amber-Ton (`--attention`,
+je Farbschema abgestimmt) statt der Akzentfarbe – «hier fehlt eine Eingabe» und «hier kannst
+du klicken» sind damit unterscheidbar.
+
+### 3.7.7 Inspector-Panel statt Modals
+
+Alle **Einzel-Bearbeitungen** – Phasenzelle, Übergangszelle, Cash-Übergang, Cash-Anfangswert,
+Phase (Name/Dauer), Szenario-Profil – öffnen sich als rechtes Seitenpanel (`InspectorShell`,
+26 rem, mobil volle Breite) statt als Modal. Bewusst **ohne Backdrop**: Die Matrix bleibt
+sichtbar und klickbar, ein Klick auf eine andere Zelle wechselt einfach den Panel-Inhalt –
+der Kontext, den Modals nehmen, bleibt erhalten. Genau ein Panel kann offen sein (eine
+`Panel`-Union ersetzt die früheren Einzel-Zustände); der `key` erzwingt beim Wechsel den
+Neuaufbau des Formulars wie zuvor bei den Dialogen.
+
+**Modals bleiben** für Erstell-Flows (Element, Phase, Plan, Assistent), den geführten
+Übergang (mehrere Objekte auf einmal), die Analysen und die Detailansichten.
+
+Der frühere Dialog «Plan-Einstellungen» heisst im Panel korrekt **«Szenario-Profil»** – er
+bearbeitet seit V6 das Szenario, nicht den Plan.
+
+### 3.7.8 Tour und «Nächste Schritte»
+
+Die **Tour** (`Tour.tsx`) startet einmalig beim ersten Öffnen eines Plans mit Phasen
+(localStorage `fpt-tour-done`) und führt in bis zu sechs Schritten über Profil, Zeitachse,
+Matrix, Übergänge, Cash und Analysen – als Karte am unteren Rand plus pulsierender Rahmen um
+das Ziel (`data-tour`-Attribute). Schritte ohne vorhandenes Ziel werden übersprungen; der
+«Tour»-Knopf in der Werkzeugleiste startet sie jederzeit neu. Grenze: 9.24.
+
+Die Karte **«Nächste Schritte»** über der Matrix leitet aus den vorhandenen Daten ab, was
+sinnvollerweise als Nächstes ansteht – offene Übergangs-Entscheide (mit Direktsprung in den
+geführten Übergang), fehlendes Einkommen/fehlende Ausgaben, ein Plan, der vor der
+Pensionierung endet, und bei Ruin der Sprung zu den Einflussfaktoren. Kein eigener Zustand,
+kein API-Aufruf; die Karte verschwindet von selbst, wenn nichts offen ist. Auch das
+**Ruin-Banner** verlinkt neu auf die Einflussfaktoren («Wirksamsten Hebel finden»).
+
+### 3.7.9 Befehls-Palette und Sparklines
+
+**Ctrl/Cmd+K** öffnet die Befehls-Palette (`CommandPalette.tsx`): Springen zu jedem
+Plan/Szenario und die wichtigsten Aktionen (Analysen, neues Szenario, neuer Plan), mit
+Tastatur-Navigation – der Effizienz-Pfad für geübte Nutzer.
+
+Jede Element-Zeile der Matrix trägt eine **Sparkline** (`Sparkline.tsx`): der Wertverlauf
+über alle Planjahre als Mini-SVG, gespeist aus den per-Jahr-Werten der Detailansichten
+(`ElementPhaseComputed.yearly`, seit 0.11) – keine Neuberechnung, reine Darstellung. Flache
+Verläufe werden nicht gezeichnet (keine Information).

 ---

@@ -2042,7 +2147,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/              17 React-Komponenten (alle "use client")
+│   ├── components/              22 React-Komponenten (alle "use client")
 │   ├── generated/prisma/        Generierter Prisma-Client (nicht editieren)
 │   ├── lib/                     Domänenlogik (siehe 5.3)
 │   └── middleware.ts            Zugriffsschutz (Edge-Runtime)
@@ -2335,6 +2440,11 @@ wird der Plan neu geladen; die Berechnung kommt immer vom Server.
 | `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 |
+| `ui` | ~370 | UI-Primitiven: Button, Modal, InspectorShell, Confirm, Toast, Skeleton, EmptyState ([3.7.6](#376-sprache-und-ui-primitiven)/[3.7.7](#377-inspector-panel-statt-modals)) |
+| `PlanWizard` | ~400 | Geführter Plan-Assistent in fünf Schritten ([3.2.8](#328-geführter-assistent-und-beispielplan)) |
+| `Tour` | ~140 | Interaktive Kurz-Tour über die Planansicht ([3.7.8](#378-tour-und-nächste-schritte)) |
+| `CommandPalette` | ~130 | Befehls-Palette Ctrl/Cmd+K ([3.7.9](#379-befehls-palette-und-sparklines)) |
+| `Sparkline` | ~45 | Mini-Verlaufskurve je Element-Zeile ([3.7.9](#379-befehls-palette-und-sparklines)) |

 ### 5.5.3 Wiederverwendungsmuster

@@ -2470,7 +2580,7 @@ Hängt eine Phase am Ende an, kappt die Dauer, vergibt Default-Name, legt vorbel
 → 200 `{ phase: { id } }`

 ### `DELETE /api/phases/<phaseId>`
-Nur die letzte Phase. → 200 `{ ok }` · 400 „Nur die letzte Phase kann geloescht werden."
+Nur die letzte Phase. → 200 `{ ok }` · 400 „Nur die letzte Phase kann gelöscht werden."

 ### `PUT /api/phases/<phaseId>/cash-transition`
 Body = `CashTransitionData` (siehe 5.4.5). Speichert den Cash-Entscheid für den Übergang **nach**
@@ -2834,15 +2944,13 @@ Verwandt: Wird ein Element in der Vorlage gelöscht, gilt das Gegenstück im Kin
 ## 9.17 Kleinere Beobachtungen

 - `planToCsv(plan, computed)` erhält den `plan`-Parameter, verwendet ihn aber nicht.
- Der Typ `Selection` in `PlanView` hat nur eine Variante (`{ type: "phase" }`) – ein Rest der
-  früheren Struktur mit mehreren Auswahlarten.
 - `Plan.branchFromPhaseId` hat keine Fremdschlüssel-Constraint; die Phase kann gelöscht werden,
  ohne dass das Feld bereinigt wird.
 - Die Element-Umbenennung ist als API vorhanden, im UI aber nicht erreichbar.
 - Die `README.md` ist noch der unveränderte `create-next-app`-Text.
- `npm run lint` meldet einen bestehenden Fehler in `ProfileMenu.tsx` Zeile 15
-  (`react-hooks/set-state-in-effect`); an vergleichbaren Stellen ist die Regel andernorts
-  bewusst per `eslint-disable` deaktiviert.
+
+(Der frühere `Selection`-Rest in `PlanView` und der ProfileMenu-Lint-Fehler sind seit 0.13
+behoben – `npm run lint` läuft fehlerfrei.)

 ## 9.18 Tornado: was der Chart nicht leistet

@@ -2934,6 +3042,23 @@ seit 0.12 erklärt wird ([4.13.5](#4135-wirkungslose-treiber-werden-erklärt));
 Vermögensbrücke erscheint stattdessen die Differenz `Verkaufspreis − Verkehrswert` als eigener
 Posten.

+## 9.23 Assistent: Teilzustand bei Abbruch
+
+Der Plan-Assistent und der Beispielplan senden am Ende eine **Sequenz** bestehender API-Aufrufe
+(Plan → Phase 1 → Elemente → Folgephasen). Bricht die Sequenz mittendrin ab (Netzfehler),
+existiert ein **Teil-Plan**. Der ist normal weiterbearbeitbar und der Fehlerhinweis sagt das
+auch – aber es gibt kein automatisches Rollback. Das wäre nur mit Backend-Unterstützung
+(Transaktion über mehrere Requests oder Batch-Endpunkt) sauber lösbar und ist bewusst nicht
+gebaut: Der seltene Fehlerfall rechtfertigt keinen neuen Endpunkt.
+
+## 9.24 Tour ohne Spotlight-Engine
+
+Die Tour hebt ihr Ziel per Rahmen-Puls und `scrollIntoView` hervor – bewusst ohne
+Spotlight-Overlay und Positionierungs-Engine (die Karte sitzt fix unten). Bei stark
+verschachtelten Scroll-Situationen kann das Ziel teilweise verdeckt sein. Der Einfachheit
+halber in Kauf genommen; eine echte Coach-Mark-Bibliothek wäre der nächste Schritt, wenn die
+Tour sich bewährt.
+
 ---

 # 10. Glossar
@@ -2976,4 +3101,4 @@ Posten.

 ---

-*Ende der Spezifikation v0.12*
+*Ende der Spezifikation v0.13*