docs: Spec + Plan Ausbaustufe 9 (Vorschlags-Algorithmus v2)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/superpowers/specs/2026-07-20-vorschlags-algorithmus-v2-design.md

@@ -0,0 +1,81 @@
+# Design — Ausbaustufe 9: Vorschlags-Algorithmus v2 (v0.9.0)
+
+> Status: vom Nutzer freigegeben (Chat 2026-07-20, Direktdurchlauf). Anlass:
+> Der bisherige `suggest_recurring` gruppiert nach exaktem Betrag (jede
+> Preiserhöhung zerreißt die Serie), erkennt nur monatliche Serien, prüft
+> keine Aktivität (schlägt tote Serien vor) und nutzt Median-Werte. Ein
+> manueller Vollabgleich (A8-Datenpflege, siehe Ledger) fand 16 fehlende
+> Posten — der Algorithmus soll solche Serien künftig selbst finden.
+
+## Anforderungen (Nutzer)
+
+- Betrag = **letzte** Buchung, nicht Median (Preissteigerungen relevant).
+- Erkennung **monatlich, vierteljährlich, jährlich**.
+- Empfänger-Gruppierung robust (Schreibweisen, Preisänderungen,
+  Umfirmierungen); mehrere Verträge desselben Anbieters getrennt.
+- Keine „Leichen": abgerissene Serien werden nicht vorgeschlagen.
+- Kein Wiedervorschlagen bereits gepflegter Posten (auch bei zwischenzeitlich
+  geändertem Betrag).
+
+## Algorithmus (`app/services/suggestions.py`, vollständiger Rewrite)
+
+Parameter als Modul-Konstanten (Toleranzen zentral änderbar):
+`WINDOW_DAYS=460` (~15 Monate), Rhythmen mit Intervallgrenzen und
+Mindestbelegen: monthly 25–36 Tage/≥3, quarterly 80–105/≥3, yearly
+330–400/≥2; `ACTIVITY_FACTOR=1.75`; Betrags-Cluster-Toleranz 35 %;
+Merge-Toleranz 25 %; Bestandsabgleich-Toleranz 10 %.
+
+1. **Datenbasis:** bestätigte Buchungen der letzten `WINDOW_DAYS`, je Konto.
+2. **Gruppierung:** Schlüssel = (account_id, normalisierter Empfänger)
+   (`casefold`, Whitespace kollabiert).
+3. **Betrags-Cluster** innerhalb der Gruppe (chronologisch, greedy gegen das
+   jeweils letzte Cluster-Mitglied, gleiches Vorzeichen, relative Differenz
+   ≤ 35 %) — trennt parallele Verträge, hält Preisdrift zusammen.
+4. **Rhythmus je Cluster:** Median der Buchungsabstände gegen die
+   Intervallgrenzen; Mindestbelege je Rhythmus.
+5. **Aktiv-Check:** letzte Buchung ≤ `ACTIVITY_FACTOR` × Rhythmus-Schrittweite
+   (30/91/365 Tage) her, sonst kein Vorschlag.
+6. **Umfirmierungs-Merge** (über Gruppengrenzen, je Konto): Serie A endet,
+   Serie B beginnt danach (Lücke 0,4–1,6 Schrittweiten), gleicher Rhythmus,
+   Fälligkeitstag ±3, Betrag ±25 % → eine Serie; Name/Betrag der neueren.
+7. **Vorschlagswerte:** Name = Empfänger-Schreibweise der neuesten Buchung;
+   Betrag = neueste Buchung; Fälligkeitstag = Tag der neuesten Buchung;
+   `start_date` = Datum der neuesten Buchung bei quarterly/yearly (Phase!),
+   sonst None; Kategorie = häufigste in der Serie; `hinweis` = Text
+   „Betrag zuletzt gestiegen (vorher X)" wenn die vorletzte Buchung
+   betragskleiner war, sonst leer.
+8. **Bestandsabgleich:** Vorschlag entfällt, wenn ein `RecurringItem`
+   existiert mit (a) Namens-Substring-Match (normalisiert, in beide
+   Richtungen) ODER (b) gleichem Rhythmus + Fälligkeitstag ±2 + Betrag
+   ±10 %.
+
+## API/GUI
+
+- `SuggestionOut` (routers/planning.py): + `start_date: date | None`,
+  + `hinweis: str = ""`.
+- Vorschlags-Tabelle (planning.html): Spalten Rhythmus (`|de_label`) und
+  Start (TT.MM.JJJJ bzw. „–"); `hinweis` als `muted`-Text hinter dem Betrag;
+  „Vorschlag übernehmen" überträgt `start_date` mit (hidden input).
+- Hinweistext unter der Tabelle aktualisiert: monatliche/vierteljährliche/
+  jährliche Serien, Betrag = letzte Buchung.
+
+## Tests (synthetische Daten, keine Fixtures)
+
+Preiserhöhungs-Serie → letzter Betrag + hinweis; Quartals-/Jahres-Serie mit
+korrektem start_date; tote Serie (letzte Buchung zu alt) → kein Vorschlag;
+Umbenennungs-Merge → ein Vorschlag mit neuem Namen; Bestandsabgleich:
+existierender Posten mit altem Betrag verhindert Wiedervorschlag; zwei
+parallele Verträge eines Anbieters → zwei getrennte Vorschläge; bestehende
+drei Suggestion-Tests an die neue Semantik anpassen.
+
+## Release
+
+`VERSION` → 0.9.0, Redeploy, **Live-Gate gegen echte Daten**: kein einziger
+der bestehenden Fixposten darf erneut vorgeschlagen werden; keine als
+beendet bekannten Serien (z.B. gelöschte PayPal-Leiche, ausgelaufene
+WWK-Police) im Ergebnis; verbleibende Vorschläge werden dem Nutzer als
+Kandidatenliste berichtet (nur Chat, kein Commit). Fable-Gate je Task.
+
+**Außerhalb des Scopes:** halbjährliche Rhythmen (nicht im Datenmodell),
+automatische Übernahme ohne Nutzer-Klick, Einnahmen-Prognose des
+Geschäftskontos.