10.April 2026

dev/Incentive-Modul/README.md

@@ -0,0 +1,92 @@
+# 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)
+
+1. **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.
+2. **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).
+3. **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.
+4. **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.*