# 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.*