Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- platform-admin-tips [2026/10/22 07:39] – angelegt adminwiki
+++ platform-admin-tips [2026/10/22 08:28] (aktuell) – [Abonnements konfigurieren] adminwiki
@@ Zeile 1: / Zeile 1: @@
 ===== Plattform Admin-Tipps =====
+{{INLINETOC 3}}
+==== Abonnements konfigurieren ====
+**Leitfaden: Produkt-Konfiguration im Abo-System (Entitlements & Credits)**
+Mit dem "Credit & Entitlement"-Architektur konfigurieren wir Produkte im Backend so, dass sie unsere interne Business-Logik (Kosten, Gutschriften, Feature-Freischaltungen) direkt steuern. Das System unterstützt dabei nahtlose Wechsel zwischen verschiedenen Ausbaustufen (Upgrades und Downgrades).
+=== 1. Die wichtigsten Felder im Produkt ===
+  * **''creditPrice'' (Das "Chamäleon"-Feld für Credits)**: Dieses Feld steuert die Credit-Transaktionen, verhält sich aber abhängig von der Bezahlmethode und dem Abo-Typ unterschiedlich:
+    * **Kauf per internem Wallet (''paidWithCredits = true''):** Der Wert definiert die reinen **Kosten**. Der Betrag wird vom Wallet abgebucht (bei Einmalkäufen oder zyklisch beim automatischen Renewal von internen Abos).
+    * **Kauf per Stripe / Echtgeld (''paidWithCredits = false''):** Der Wert definiert das **Credit-Äquivalent** zur Echtgeldzahlung. Hierbei unterscheidet das System nach Typ:
+      * //Bei Credit-Abos (Auflade-Abos):// Der Wert agiert als reines **Auftanken** und wird dem Wallet automatisch als ''WALLET_TOP_UP'' gutgeschrieben.
+      * //Bei Feature-Abos:// Das System führt quasi einen **Währungswechsel mit direkter Ausgabe** durch. Der Betrag wird dem Wallet gutgeschrieben und im selben Zug für die Aktivierung des Features wieder abgebucht. Zudem bildet dieser Wert die zwingende Berechnungsgrundlage für anteilige Erstattungen (Proration Refunds) bei zukünftigen Level-Wechseln (Up- oder Downgrades).
+  * **''billingInterval'' (Zyklus)**: Optional. Gibt an, ob es sich um ein Abo handelt (z. B. ''"month"'' oder ''"year"'').
+  * **''additionalProperties'' -> ''subscriptionInfo'' (Das Feature-Herzstück)**: Ein JSON-Objekt, das definiert, was das ''Entitlement'' (internes Abo) dem Nutzer exakt freischaltet.
+=== 2. Aufbau der subscriptionInfo (JSON) ===
+Die ''subscriptionInfo'' steuert direkt die Berechtigungen (''HostFeature'') des Nutzers.
+  * ''type'': Die Kategorieklammer (z.B. ''"credit"'', ''"licence"'', ''"visualizer"''). Pro User und ''type'' gibt es immer maximal ein aktives Entitlement.
+  * ''level'': Die Ausbaustufe. Höhere Level überschreiben niedrigere Level des gleichen Typs (und umgekehrt bei Downgrades).
+  * ''features'': Ein Key-Value-Objekt für spezifische Rechte. Das Backend verarbeitet die Werte typisiert:
+    * **Boolean (''true''):** Wird 1:1 als Flag übernommen (z. B. ''"panorama.model3ds": true'' wird zu ''panorama.model3ds = "true"'').
+    * **Number (''Integer''):** Das Backend kombiniert den Key und die Number zu einem neuen Flag-String (z. B. ''"host.licences.visualizer": 3'' wird zu ''host.licences.visualizer3 = "true"'').
+=== 3. Konfigurations-Beispiele ===
+== Fall A: Ein reguläres Feature-Abo (z. B. Visualizer Level 3) ==
+Ein typisches Produkt für den Neueinstieg oder für Level-Wechsel (Up- und Downgrades).
+  * ''creditPrice'': ''50'' (Kosten bei Wallet-Zahlung / Äquivalent-Wert bei Stripe-Zahlung für Währungswechsel und spätere Refunds)
+  * ''billingInterval'': ''"month"''
+  * ''subscriptionInfo'':
+  "subscriptionInfo": {
+    "type": "visualizer",
+    "level": 3,
+    "features": {
+      "host.licences.visualizer": 3,
+      "panorama.model3ds": true
+    }
+  }
+**Was passiert?** Das Backend bucht das Entitlement auf Typ ''"visualizer"'' und schaltet in den HostFeatures ''host.licences.visualizer3 = "true"'' sowie ''panorama.model3ds = "true"'' frei. Alte Visualizer-Keys eines vorherigen Levels (z.B. ''visualizer2'') werden dabei automatisch aufgeräumt.
+== Fall B: Analog zum visualizer Abo (Licence Level 2) ==
+Ein anderes levelbasiertes Abo mit jährlichem Abbuchungsinterval.
+  * ''creditPrice'': ''150''
+  * ''billingInterval'': ''"year"''
+  * ''subscriptionInfo'':
+  "subscriptionInfo": {
+    "type": "licence",
+    "level": 2,
+    "features": {
+      "host.licences.licence": 2
+    }
+  }
+== Fall C: Das Credit-Auflade-Abo (Reines Stripe-Produkt) ==
+Dieses Produkt existiert, um regelmäßig über Stripe bezahlt zu werden und dafür dem Nutzer Credits im Wallet gutzuschreiben.
+  * ''creditPrice'': ''100'' (Da es ein "credit" Typ ist, dient dies als reiner Auflade-Wert)
+  * ''billingInterval'': ''"month"''
+  * ''subscriptionInfo'':
+  "subscriptionInfo": {
+    "type": "credit",
+    "features": {}
+  }
+**Was passiert?** Der Nutzer bezahlt echtes Geld über Stripe. Der Webhook erkennt den Typ ''"credit"'' und überspringt die direkte Wiederabbuchung. Der ''creditPrice'' von ''100'' bleibt als ''WALLET_TOP_UP'' im Wallet des Nutzers liegen. Proration-Refunds sind für diesen Typ automatisch deaktiviert.