92 lines
4.6 KiB
Markdown
92 lines
4.6 KiB
Markdown
# 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.*
|