Incentive-Modul (CRM)

Übersichtliche Beschreibung des wiederverwendbaren Incentive-Systems in mivita: zeitlich begrenzte Challenges (z. B. Reise-Anreize), eigenes Punkte- und Ranking-Modell, getrennt von MLM-Provisionsberechnung (BusinessPlan / TreeCalcBot).

Zweck

Mehrere Incentives parallel oder nacheinander (pro Jahr/Kampagne anlegbar).
Berater opt-in mit Teilnahmebedingungen; Punkte, Mindestqualifikation (Partner + Kundenabos) und Top-N-Gewinner sind pro Incentive konfigurierbar.
Transparenz für Berater: Live-Rangliste, Detailansicht mit Aufschlüsselung nach Neupartnern und Kundenabos (inkl. Monaten).

Architektur in Kürze

Schicht	Inhalt
Konfiguration	`incentives` – Zeiträume, Punkte, Mindestwerte, `max_winners`, Status, Slug, Übersetzungen
Teilnahme	`incentive_participants` – Opt-in, aggregierte Werte, Rang, Qualifikations-Flags
Tracking	`incentive_new_partners`, `incentive_new_abos` – welche Neupartner/Abos einem Teilnehmer zugeordnet sind
Historie	`incentive_points_log` – Einmal- und Akkumpunkte, optional Verknüpfung zu `UserSalesVolume`, Stornos

Kernservice: App\Services\Incentive\IncentiveTracker – wird aus Zahlungsfluss, Rechnung/Sales Volume und Storno aufgerufen.

Batch: php artisan incentive:calculate (IncentiveCalculate) + optional IncentiveCalculationService / Neuaufbau aus Quellen.

Datenfluss (Events)

Neupartner mit Starterpaket – bezahlte Wizard-Registrierung (payment_for = 1), Bestellung enthält mindestens ein Produkt ohne „reine Mitgliedschaft“ (Product::is_membership_only = false). → Eintrag in incentive_new_partners, Einmalpunkte im Log, Neuberechnung.
Abo aktiviert – nach AboHelper::setAboActive: Kundenabo is_for = 'ot' (Berater = member_id) oder Berater-Eigenabo is_for = 'me' (Berater = user_id). → incentive_new_abos, Einmalpunkte, Neuberechnung. Beim Neuaufbau zählen Kundenabos über member_id im Qualifikationszeitraum; Eigenabos (me) neu im Zeitraum oder bereits vor Qualifikationsbeginn aktiv (dann Einmalpunkte mit Wirkung ab Qualifikationsstart).
Akkumulierte Punkte – bei neuer UserSalesVolume-Zeile (Rechnung): Umsatzpunkte von getrackten Neupartnern (SV gehört zur User-ID des Partners) bzw. im Neuabo-Pfad über Bestellung/Kundenkontext. → Log points_accumulated, Neuberechnung.
Storno – Gegenbuchung im Log, Neuberechnung.

Details und Integrationsstellen: entwicklungsplan.md.

UI

Bereich	Beschreibung
Admin	CRUD Incentives, Konfiguration, Teilnehmer-Ranking-Tabelle
Berater	Teaser/Show (Info, Live-Ranking, Teilnahme), Details mit Monatsaufschlüsselung
Navigation	Einträge z. B. über Dashboard / Sidenav (je nach Rolle)

Content-Texte (Marketing) für eine konkrete Kampagne liegen separat in site.md.

Wichtige Geschäftsregeln (implementiert)

Rangliste (User): Sortierung: zuerst qualifizierte Teilnehmer (Mindest-Partner/Abos), dann nach Rang, Teilnehmer ohne Rang unten, Tiebreaker Gesamtpunkte; Anzeige begrenzt auf max_winners; optional nur Teilnehmer mit Aktivität (Partner, Abo oder Punkte > 0) – Scope withRankingActivity().
Neupartner zählen nur mit Starterpaket – keine reine Mitgliedschafts-Bestellung allein; technisch: ShoppingOrder::wherePaidRegistrationIncludesStarterKit() / qualifiesForIncentiveTrackedPartner().

Dokumente in diesem Ordner

Datei	Inhalt
README.md (diese Datei)	Modulübersicht
entwicklungsplan.md	Datenmodell, Services, Hooks, Phasen, Dateiliste, Architektur-Tracking
tasks.md	Anforderungen, Aufgaben- und Statusübersicht
site.md	Vorgefertigte Textbausteine / Nutzungsbedingungen (Content Montenegro 2026)

Relevante Code-Pfade (Referenz)

app/Models/Incentive.php
app/Models/IncentiveParticipant.php
app/Models/IncentivePointsLog.php
app/Models/IncentiveNewPartner.php
app/Models/IncentiveNewAbo.php
app/Services/Incentive/IncentiveTracker.php
app/Services/Incentive/IncentiveCalculationService.php
app/Services/Incentive/IncentivePointsLogRepairService.php
app/Http/Controllers/Admin/IncentiveController.php
app/Http/Controllers/User/IncentiveController.php
resources/lang/{de,en,es}/incentive.php
tests/Feature/Incentive/
tests/Unit/Incentive/
tests/Unit/Services/Incentive/

Letzte inhaltliche Aktualisierung der Modul-Doku: März 2026.

4.6 KiB Raw Blame History Unescape Escape