13-05-2026 implementation FR

dev/2026-05-13-backoffice/ENTWICKLUNGSKONZEPT-BACKOFFICE.md

@@ -0,0 +1,417 @@
+# Entwicklungskonzept: Backoffice Dashboard & Interaktivität
+
+Datum: 13.05.2026
+
+Quelle: `docs/salescenter/Todos Backoffice.md`
+
+## Zielbild
+
+Das Partner-Backoffice soll von einer statischen Monats-Kachelansicht zu einer klickbaren, linienbasierten Statistik ausgebaut werden. Führungskräfte sollen von der Gesamtübersicht über Linien und Generationen bis zu einzelnen Kunden, Partnern und Abos navigieren können.
+
+Kernziel ist eine einheitliche Datenbasis für:
+
+- Dashboard-Kennzahlen pro Linie 1 bis 8 inklusive Summenzeile
+- Detailansichten je Linie, Firstline und Kennzahl
+- Kundenabos, Teamabos, Kundenabos im Team, Umsatz und Punkte
+- neue Spezial-Kennzahl "1000 Punkte Shop"
+- saubere Begrifflichkeit und rechtssichere Sichtbarkeit in Incentive-Ranglisten
+
+## Bestandsaufnahme im System
+
+### Dashboard
+
+Aktueller Einstieg:
+
+- Route: `GET /home`
+- Controller: `App\Http\Controllers\HomeController@show`
+- View: `resources/views/home.blade.php`
+- Statistik-Partial: `resources/views/dashboard/_statistics.blade.php`
+
+Die aktuelle Statistik wird direkt im Blade-Partial berechnet. Sie nutzt unter anderem:
+
+- `App\Models\UserBusiness` für gespeicherte Monatswerte und Payline-Punkte
+- `App\Models\UserSalesVolume` für Kunden-/Shop-Punkte
+- `App\Models\UserAbo` für eigene Abos, Kundenabos und Teamabos
+- rekursive Sponsor-Abfragen über `users.m_sponsor`
+
+Bewertung:
+
+- Die vorhandene Ansicht ist ein guter Einstieg, aber fachlich zu grob.
+- Es gibt noch keine Linien 1 bis 8, keine Summenzeile und keine Drill-down-Routen.
+- Die Kennzahl "Kundenabos" vermischt aktuell eigene Abos und Kundenabos.
+- "Team-Abos" zählt aktuell Beraterabos im Team, aber nicht die separat geforderten Kundenabos im Team.
+
+### Team- und Abo-Bereich
+
+Relevante Routen und Controller:
+
+- `User\TeamController@structure` für Strukturansicht
+- `User\TeamController@show` und `datatableOptimized` für Teamliste
+- `User\TeamController@showAbos` für Team-Beraterabos
+- `User\TeamController@showTeamCustomerAbos` für Kundenabos im Team
+- `User\TeamController@detailAbo` für Abo-Details
+
+Relevante Daten:
+
+- `UserAbo::is_for = 'me'` bedeutet Berater-/Eigenabo
+- `UserAbo::is_for = 'ot'` bedeutet Kundenabo
+- `UserAbo::user_id` ist der Bestell-/Abo-User
+- `UserAbo::member_id` ist der zugeordnete Berater
+- `UserAbo::next_date` liefert die nächste Abo-Ausführung
+- `UserAbo::getTotalPoints()` berechnet Punkte aus Abo-Items und Produkten
+- `AboHelper::getTeamUserIds()` liefert Downline-User-IDs
+- `AboHelper::getMonthlyAboCounts()` kennt bereits die Scopes `team_abos` und `team_cust_abos`
+
+Bewertung:
+
+- Viele Datenquellen für die geforderten Listen existieren bereits.
+- Die Logik ist aber auf mehrere Controller, Blades und Helper verteilt.
+- Für das neue Dashboard sollte die Logik zentralisiert werden, statt weitere Berechnungen in Blade-Dateien zu ergänzen.
+
+### Business- und Punkteberechnung
+
+Relevante Bausteine:
+
+- `App\Services\BusinessPlan\TreeCalcBotOptimized`
+- `App\Models\UserBusiness`
+- `App\Models\UserSalesVolume`
+- `App\Services\BusinessPlan\SalesPointsVolume`
+
+Bewertung:
+
+- Für Monats- und Teamwerte sollte bevorzugt auf gespeicherte Businessdaten zurückgegriffen werden.
+- Live-Berechnung über TreeCalcBot ist als Fallback sinnvoll, darf aber nicht bei jedem Seitenaufruf ungefiltert große Strukturen neu berechnen.
+- Die neue Drill-down-Logik benötigt klare Regeln, ob sie Live-Daten oder gespeicherte Monats-Snapshots zeigt.
+
+### Incentives
+
+Relevante Dateien:
+
+- `App\Http\Controllers\User\IncentiveController`
+- `resources/views/user/incentive/show.blade.php`
+- `App\Models\IncentiveParticipant`
+- `App\Services\Incentive\IncentiveTracker`
+
+Status:
+
+- Teilnahme-Opt-in existiert über `accepted_terms_at`.
+- Ranking wird aktuell mit `paginate(100)` angezeigt.
+- Nicht zustimmende Teilnehmer werden für normale User anonymisiert.
+- VIP-Ansicht sieht zusätzliche Hinweise zur Zustimmung.
+
+Lücke zum Briefing:
+
+- Es gibt noch keine separate Zustimmung "Name/Fotos/Land in Rangliste sichtbar".
+- Foto und Land sind in der aktuellen Rangliste nicht als sichtbare Standardspalten umgesetzt.
+- Rechtliche Freigabe muss fachlich vor der technischen Umsetzung geklärt werden.
+
+### Checkout-Herkunft
+
+Relevante Dateien:
+
+- `App\Http\Controllers\Web\CheckoutController`
+- `App\Repositories\CheckoutRepository`
+- `App\Models\ShoppingUser`
+
+Status:
+
+- `CheckoutController::validateCheckoutData()` validiert Basisdaten, aber keine Pflichtfrage "Von wem hast du von Mivita erfahren?"
+- `ShoppingUser` nutzt `is_from` für den technischen Ursprung wie `shopping`, `homeparty` oder `collection`.
+- Ein fachliches Herkunfts-/Empfehlungsfeld existiert nicht als sauber getrennte Datenquelle.
+
+### Storno und Punkterückführung
+
+Relevante Dateien:
+
+- `App\Repositories\InvoiceRepository`
+- `App\Services\BusinessPlan\SalesPointsVolume`
+- `App\Services\Incentive\IncentiveTracker`
+
+Status:
+
+- Beim Erstellen einer Stornorechnung ruft `InvoiceRepository::createCancellation()` die Punktekorrektur auf.
+- `SalesPointsVolume::cancelSalesPointsVolume()` erstellt einen negativen `UserSalesVolume`-Eintrag mit Status `6`.
+- Danach wird der Monat neu berechnet und `IncentiveTracker::trackStorno()` informiert.
+
+Risiken:
+
+- Wenn zur Originalrechnung kein `UserSalesVolume` existiert, wird nur geloggt und keine Punktekorrektur erstellt.
+- Der negative Storno-Eintrag wird aktuell dem aktuellen Monat zugeordnet, nicht zwingend dem ursprünglichen Umsatzmonat.
+- Fachlich muss entschieden werden, ob Stornos im Stornomonat oder im Ursprungsmonat wirken sollen.
+
+## Fachliche Prüfung der To-dos
+
+### 1. Überarbeitetes Dashboard & KPI-Übersicht
+
+Umsetzung sinnvoll, aber nicht als Erweiterung des bestehenden Blade-Partials. Benötigt wird ein dedizierter Service, der die Kennzahlen pro Linie liefert.
+
+Vorgeschlagene Tabelle Stufe 1:
+
+- Linie
+- Anzahl Berater
+- Umsatz gesamt
+- Eigen-/Beraterabos im Team
+- eigene Kundenabos
+- Kundenabos im Team
+- Neupartner
+- 1000 Punkte Shop
+- Summe
+
+Wichtig:
+
+- "Teamkundenabos" sollte als Begriff für Kundenabos der Downline verwendet werden.
+- "Teamabos" sollte nur für Berater-/Eigenabos im Team verwendet werden.
+- Eigene Abos dürfen nicht in Kundenabos eingerechnet werden.
+
+### 2. Interaktivität & Deep Dive
+
+Umsetzung über eigene Backoffice-Statistik-Routen statt über große Modals im Dashboard.
+
+Vorgeschlagene Stufen:
+
+- Stufe 1: Linienübersicht `/user/backoffice/statistics`
+- Stufe 2: Linien-/Firstline-Detail `/user/backoffice/statistics/line/{line}`
+- Stufe 3: Kennzahlenliste `/user/backoffice/statistics/details?line=...&metric=...&user=...`
+
+Jede Zahl erhält einen Link auf eine gefilterte Detailansicht. Die Detailansicht sollte die Query-Parameter sichtbar halten, damit Support und Fachbereich Ergebnisse reproduzieren können.
+
+### 3. Spezial-Kennzahl "1000 Punkte Shop"
+
+Definition muss vor Umsetzung final geklärt werden.
+
+Vorschlag für Version 1:
+
+- Zeitraum: gewählter Monat/Jahr des Dashboards
+- Personenkreis: Downline des eingeloggten Users
+- Schwelle: `UserSalesVolume` Shop-/KP-Summe pro Partner >= 1000 Punkte
+- Sortierung: Volumen absteigend
+- Detailspalten: Name, Account, Linie/Generation, Shop-Punkte, Gesamt-KP, Umsatz netto
+
+Offene Fachfrage:
+
+- Meint "Kundenumsatz" nur Shop-Umsatz (`month_shop_points`) oder alle Kundenpunkte inklusive Abo-/Beraterkontext?
+
+### 4. Bestellformular: "Von wem hast du von Mivita erfahren?"
+
+Technisch sollte ein neues fachliches Feld eingeführt werden, nicht `is_from` zweckentfremdet werden.
+
+Vorschlag:
+
+- Migration für `shopping_users.referral_source_name` oder ähnliches Feld
+- optional zusätzlich auf `shopping_orders`, wenn die Information revisionssicher pro Bestellung eingefroren werden soll
+- Pflichtvalidierung in `CheckoutController::validateCheckoutData()`
+- Anzeige im Checkout-Formular und optional im Admin-/Bestelldetail
+- später exportierbar für Marketingauswertung
+
+Zu klären:
+
+- Freitext oder Auswahl plus Freitext?
+- Pflicht nur im Webshop/Bestelllink oder auch bei Salescenter-, Homeparty- und Collection-Flows?
+- Soll eine konkrete Beraterzuordnung daraus entstehen oder nur Tracking?
+
+### 5. Stornoprozess
+
+Die Grundlogik existiert. Vor einer fachlichen Freigabe braucht es Tests und eine Periodenentscheidung.
+
+Prüfpunkte:
+
+- Storno einer Beraterbestellung erzeugt negative Punkte beim richtigen Berater.
+- Storno einer Kunden-/Shopbestellung erzeugt negative Punkte im richtigen Umsatztyp.
+- Storno einer Abo-Bestellung wirkt korrekt auf Incentive-Logs.
+- Storno ohne vorhandenen `UserSalesVolume` ist sichtbar und lösbar, nicht nur ein Log-Eintrag.
+- Businessdaten nach Storno werden für betroffenen Monat/Jahr aktualisiert oder als neu zu berechnen markiert.
+
+### 6. Rechtliches & Sichtbarkeit in Incentives
+
+Die bestehende Teilnahmezustimmung sollte nicht automatisch als Freigabe für öffentliche Namens-/Fotoanzeige interpretiert werden.
+
+Vorschlag:
+
+- eigenes Feld auf `incentive_participants`, z. B. `ranking_visibility_accepted_at`
+- Button/Checkbox in der Incentive-Seite: "Ich stimme zu, dass mein Name, Foto und Land in der Rangliste sichtbar sind"
+- Anzeige von Name, Foto und Land nur, wenn die Zustimmung vorliegt oder ein Admin/VIP die Ansicht nutzt
+- nach juristischer Klärung kann die Regel angepasst werden
+
+Technische Ergänzungen:
+
+- Ranking um Foto und Land erweitern
+- Pagination/Limit bewusst definieren: alle Teilnehmer anzeigen, aber paginiert
+- Übersetzungen in `resources/lang/*/incentive.php` ergänzen
+
+### 7. Multimedia-Bereich / Event-Archiv
+
+Es gibt bereits Dashboard-News und ein News-Archiv. Für Events sind zwei Varianten möglich:
+
+Variante A: `DashboardNews` um Typ "event" erweitern
+
+- weniger Aufwand
+- bestehendes Admin-Modul kann wiederverwendet werden
+- geeignet, wenn Events im gleichen Format wie News funktionieren
+
+Variante B: eigenes Event-Modul
+
+- sauberere Trennung
+- eigene Felder für Galerie, Eventdatum, Call-/Foto-Typ
+- sinnvoll, wenn Uploads, mehrere Bilder pro Event oder Kategorien benötigt werden
+
+Empfehlung: Variante A als MVP, falls keine komplexe Galerieverwaltung benötigt wird.
+
+## Technisches Zielkonzept
+
+### Neue zentrale Services
+
+Empfohlen:
+
+- `App\Services\Backoffice\BackofficeDashboardService`
+- `App\Services\Backoffice\BackofficeDrilldownService`
+
+Aufgaben `BackofficeDashboardService`:
+
+- Zeitraum normalisieren
+- Downline pro Linie aufbauen
+- Summen pro Linie berechnen
+- Daten für Stufe 1 und Stufe 2 liefern
+- Caching-/Snapshot-Strategie kapseln
+
+Aufgaben `BackofficeDrilldownService`:
+
+- Kennzahlenfilter aus Request validieren
+- Personen-/Abo-/Umsatzlisten erzeugen
+- Berechtigungen gegen Downline prüfen
+- einheitliche Summary für Listen liefern
+
+### Controller und Views
+
+Empfohlen:
+
+- `App\Http\Controllers\User\BackofficeStatisticsController`
+- Views unter `resources/views/user/backoffice/statistics/`
+
+Geplante Actions:
+
+- `index()` für Stufe 1
+- `line(int $line)` für Stufe 2
+- `details()` für Stufe 3
+- optional `export()` für CSV/Excel später
+
+Die vorhandenen Team-Views bleiben bestehen. Das neue Dashboard verweist für Detailseiten aber auf eigene, schlankere Statistik-Views.
+
+### Datenmodell und Definitionen
+
+Einheitliche Metriken:
+
+- `consultants`: aktive Berater in Linie
+- `own_abos`: eigene Beraterabos des eingeloggten Users
+- `team_partner_abos`: Beraterabos im Team (`is_for = 'me'`)
+- `direct_customer_abos`: Kundenabos des betrachteten Beraters (`member_id = user_id`, `is_for = 'ot'`)
+- `team_customer_abos`: Kundenabos der Downline-Berater (`member_id in teamUserIds`, `is_for = 'ot'`)
+- `new_partners`: neue aktive Partner im Zeitraum
+- `turnover_points`: Punkte aus `UserSalesVolume`/`UserBusiness`
+- `turnover_net`: Netto-Umsatz aus `UserSalesVolume`/`UserBusiness`
+- `shop_1000`: Partner mit Kunden-/Shop-Punkten >= 1000
+
+### Berechtigungen
+
+Jede Detailansicht muss sicherstellen:
+
+- Der eingeloggte User sieht nur eigene Downline-Daten.
+- Ein direkt angefragter `user_id` muss per Sponsor-Hierarchie im Team liegen.
+- Kundenabos werden nur in dem Umfang angezeigt, der fachlich für Berater vorgesehen ist.
+- Datenschutzrelevante Kundendaten sollten auf das notwendige Minimum reduziert werden.
+
+## Umsetzungsphasen
+
+### Phase 1: Begriffe, Datenbasis und MVP Dashboard
+
+- Fachliche Definitionen finalisieren
+- `BackofficeDashboardService` erstellen
+- Stufe-1-Linienübersicht mit Linien 1 bis 8 und Summenzeile bauen
+- bestehende Dashboard-Kachel durch Link auf neue Statistikseite ergänzen oder neue Seite im Menü aufnehmen
+- Kennzahlen noch ohne vollständigen Deep Dive, aber bereits sauber berechnet
+
+### Phase 2: Drill-down Stufe 2 und Stufe 3
+
+- Linien-Detailansicht pro Firstline bauen
+- Detailansichten je Kennzahl bauen
+- Abo-Listen mit Name, Punktewert, nächster Ausführung und Anzahl Lieferungen anzeigen
+- Links aus jeder Kennzahl setzen
+- leere Zustände und Summenzeilen ergänzen
+
+### Phase 3: 1000 Punkte Shop
+
+- fachliche Definition final bestätigen
+- Query und Summary implementieren
+- Widget in Übersicht ergänzen
+- Detailansicht mit Sortierung nach Volumen absteigend bauen
+
+### Phase 4: Herkunftsabfrage im Checkout
+
+- Migration und Model-Fillable ergänzen
+- Checkout-Formular erweitern
+- Validierung und Speicherung ergänzen
+- Admin-/Bestelldetail oder Export um Feld erweitern
+
+### Phase 5: Storno-Qualitätssicherung
+
+- Tests für vorhandene Storno-Punktepfade ergänzen
+- Fachentscheidung zur Periodenlogik dokumentieren
+- Fehlerfall ohne Original-`UserSalesVolume` sichtbar machen
+- ggf. Businessdaten-Neuberechnung nach Storno anstoßen
+
+### Phase 6: Incentive-Sichtbarkeit und Event-Archiv
+
+- rechtliche Entscheidung einarbeiten
+- separates Ranking-Sichtbarkeits-Opt-in ergänzen
+- Foto/Land im Ranking anzeigen
+- Event-Archiv als `DashboardNews`-Typ oder eigenes Modul umsetzen
+
+## Teststrategie
+
+Feature-Tests:
+
+- Dashboard zeigt nur Daten der eigenen Downline.
+- Linien 1 bis 8 werden korrekt gruppiert.
+- Summenzeile entspricht Summe der Linien.
+- Klick auf Teamabos zeigt nur `is_for = 'me'` in der Downline.
+- Klick auf Kundenabos im Team zeigt nur `is_for = 'ot'` mit `member_id` in der Downline.
+- 1000-Punkte-Shop listet nur Partner über Schwelle und sortiert absteigend.
+- Checkout verlangt die Herkunftsabfrage und speichert sie.
+- Storno erzeugt negativen `UserSalesVolume`-Eintrag und aktualisiert Monatswerte.
+- Incentive-Ranking zeigt Name/Foto/Land nur nach passender Zustimmung.
+
+Unit-Tests:
+
+- Service aggregiert Linien korrekt.
+- Service verhindert Zugriff auf fremde Team-User.
+- Metrikdefinitionen liefern stabile Counts bei aktiven, gekündigten und zukünftigen Abos.
+
+Regressionsprüfung:
+
+- bestehende Teamseiten `user.team.*`
+- bestehende Abo-Seiten
+- bestehendes Incentive-Ranking
+- Checkout für Webshop, Bestelllink und Salescenter-Flows
+
+## Offene Fachfragen
+
+1. Soll die neue Statistik die aktuelle Monatslogik nutzen oder standardmäßig den letzten abgeschlossenen Monat zeigen?
+2. Sollen Stornos im Stornomonat oder im ursprünglichen Umsatzmonat gegengerechnet werden?
+3. Wie genau wird "1000 Punkte Shop" definiert: nur Shop-Punkte, alle Kundenpunkte oder Kundenabos plus Einzelbestellungen?
+4. Welche Kundendaten dürfen Berater in Deep-Dive-Listen sehen?
+5. Ist die Herkunftsabfrage Freitext, Auswahlfeld oder Kombination?
+6. Gilt die Herkunftsabfrage für alle Checkout-Flows oder nur für externe Kundenbestellungen?
+7. Darf eine Incentive-Teilnahme bereits Name/Foto/Land freigeben oder braucht es ein separates Opt-in?
+8. Soll das Event-Archiv nur Bilder und Texte enthalten oder eine echte Galerie mit Mehrfachuploads?
+
+## Empfehlung
+
+Die Backoffice-Statistik sollte als eigenes kleines Modul im User-Bereich umgesetzt werden, nicht als weitere Logik in `dashboard/_statistics.blade.php`. Die vorhandenen Datenquellen sind ausreichend für ein MVP, aber sie müssen zentral aggregiert, fachlich sauber benannt und über berechtigte Drill-down-Routen zugänglich gemacht werden.
+
+Priorität für die erste Umsetzung:
+
+1. Daten- und Begriffsdefinitionen finalisieren
+2. zentrale Services und Stufe-1-Linienübersicht
+3. Drill-down für Abos und Neupartner
+4. 1000-Punkte-Shop
+5. Checkout-Herkunft und Storno-Tests
+6. Incentive-Sichtbarkeit und Event-Archiv