9b99020686
Gateway - InsufficientBalanceException: billingModel, userAction (TOP_UP_SELF / CONTACT_MANDATE_ADMIN), DE/EN-Texte, toClientDict(), fromBalanceCheck() - HTTP 402 + JSON detail für globale API-Fehlerbehandlung - AI/Chatbot: vor Raise ggf. E-Mail an BillingSettings.notifyEmails (PREPAY_MANDATE, Throttle 1h/Mandat) via billingExhaustedNotify - Agent-Loop & Workspace-Route: SSE-ERROR mit strukturiertem Billing-Payload - datamodelBilling: notifyEmails-Doku für Pool-Alerts frontend_nyla - useWorkspace: SSE onError für INSUFFICIENT_BALANCE mit messageDe/En und Hinweis auf Billing-Pfad bei TOP_UP_SELF
227 lines
8.9 KiB
Markdown
227 lines
8.9 KiB
Markdown
# Monetarisierung der Features — interaktives Klärungs-Playbook
|
||
|
||
Dieses Dokument ist für **Live-Workshops** gedacht (Product, Sales, Tech). Du kannst es in Cursor/VS Code oder GitHub öffnen: **Checkboxen** (`- [ ]`) und **leere Tabellenzellen** werden direkt im Editor abgehakt bzw. ausgefüllt.
|
||
|
||
---
|
||
|
||
## 1. Ausgangslage aus `frontend_nyla` (gemeinsames Bild)
|
||
|
||
Die App denkt in **Mandanten → Features → Instanzen → Rechte (Views)**. Nutzer haben keinen direkten „Mandanten-Login“, sondern **Zugriff auf Feature-Instanzen** (`featureStore`).
|
||
|
||
| Baustein | Bedeutung für Pricing |
|
||
|----------|------------------------|
|
||
| **Feature-Code** (z. B. `chatbot`, `workspace`) | logische Produktlinie / Modul |
|
||
| **Instanz** | oft Kunde, Abteilung, Bot, “Organisation” — **horizontale Skalierung** (mehr Instanzen = mehr Wert oder mehr Kosten) |
|
||
| **Views / Berechtigungen** | micro-Segmente im Produkt (**Add-ons**, Rollenpakete, „Light vs Pro“) |
|
||
| **Feature Store** (`Store.tsx`) | Self-Service-Aktivierung (z. B. `automation`, `teamsbot`) — Kandidaten für **Freemium / Trial / Upsell** |
|
||
| **Billing im Frontend** (`billingApi.ts`) | Modelle `PREPAY_MANDATE`, `PREPAY_USER`, `UNLIMITED`; Transaktionen mit u. a. `featureCode`, `featureInstanceId`, Provider/Modell |
|
||
|
||
**Leitidee:** Preis = *was* (Feature/View) × *wie viel* (Instanz, Nutzer, Volumen) × *wie abgerechnet* (Pauschale, Credits, Nachzahlung).
|
||
|
||
---
|
||
|
||
## 2. Schnell-Check: Welches Geschäftsmodell passt grob?
|
||
|
||
Arbeite die Fragen der Reihe nach durch und hake ab.
|
||
|
||
- [ ] **Primärer Käufer:** zahlt der **Mandant** (Firma), der **Endnutzer**, oder ein **Partner**?
|
||
- [ ] **Value Metric:** was korreliert am ehesten mit Kundennutzen? (z. B. Mandanten, Instanzen, aktive Nutzer, gespeicherte Dokumente, API-Calls, AI-Tokens/CHF-Verbrauch)
|
||
- [ ] **Margen-Risiko:** wo sind **variable Kosten** (LLM, Storage, Third-Party) — müssen die **durchgereicht** oder **gepuffert** werden?
|
||
- [ ] **Go-to-Market:** brauchst du **Selbstbedienung** (Store) oder nur **Sales / Onboarding** (Admin legt Instanzen an)?
|
||
- [ ] **Fairness:** soll ein Power-User **pro Nutzer** limitiert sein oder **Kontingent pro Mandant**?
|
||
|
||
### Entscheidungsbaum (Diskussionsvorlage)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Nutzerwert skaliert primär mit Volumen?] -->|Ja| B[Usage / Credits / Nachzahlung]
|
||
A -->|Nein| C[Festpreis / Seat / Instanz]
|
||
B --> D[Pro Feature oder globaler Credit-Pool?]
|
||
C --> E[Wer zählt als Seat: Login oder aktive Nutzung?]
|
||
D --> F[Sichtbar im Billing-Dashboard pro FeatureCode?]
|
||
E --> G[Wie viele Instanzen sind inkludiert?]
|
||
```
|
||
|
||
Trage Ergebnis hier ein (ein Satz):
|
||
|
||
> **Entscheidung Grobmodell:** …
|
||
|
||
---
|
||
|
||
## 3. Billing-Modelle (Anknüpfung an `billingApi.ts`)
|
||
|
||
Ordnet euer **Angebot** den technisch vorhandenen **BillingModel**-Werten zu (Namen aus dem Frontend):
|
||
|
||
| `BillingModel` | Typische Kundenstory | Wann sinnvoll? |
|
||
|----------------|---------------------|----------------|
|
||
| `PREPAY_MANDATE` | „Wir laden ein Konto auf, alle ziehen daraus.“ | Gemeinsamer Pool, ein Rechnungsempfänger |
|
||
| `PREPAY_USER` | „Jeder Nutzer hat ein Kontingent.“ | faire Verteilung bei heterogenem Nutzungsverhalten |
|
||
| `UNLIMITED` | „Flat rate / Enterprise-Vertrag.“ | Paketpreis deckt erwarteten Mix |
|
||
|
||
**Workshop-Aufgabe**
|
||
|
||
- [ ] Standard für **SMB**:
|
||
- [ ] Standard für **Enterprise**:
|
||
- [ ] Ausnahme / Piloten:
|
||
|
||
---
|
||
|
||
## 4. Feature-Inventar (aus `FEATURE_REGISTRY`)
|
||
|
||
Die folgende Tabelle ist die **Checkliste pro Modul**. Pro Zeile: **was** verkaufen wir, **woran** messen wir, **was** ist Inhalt eines Pakets?
|
||
|
||
| `featureCode` | Produktname (DE) | Hauptnutzen (1 Satz) | Typische „Einheit“ für Preis (*Seat / Instanz / Request / GB / CHF-Verbrauch*) | Im **Feature Store** relevant? | Variable Kosten? (ja/nein/klein) | Notizen |
|
||
|---------------|------------------|----------------------|----------------------------------------------------------------------------------|-------------------------------|-----------------------------------|---------|
|
||
| `trustee` | Treuhand | | | ☐ ja ☐ nein | | |
|
||
| `realestate` | Immobilien | | | ☐ ja ☐ nein | | |
|
||
| `chatbot` | Chatbot | | | ☐ ja ☐ nein | | |
|
||
| `chatworkflow` | Workflow | | | ☐ ja ☐ nein | | |
|
||
| `automation` | Automatisierung | | | ☐ ja ☐ nein | | |
|
||
| `teamsbot` | Teams Bot | | | ☐ ja ☐ nein | | |
|
||
| `neutralization` | Neutralisierung | | | ☐ ja ☐ nein | | |
|
||
| `commcoach` | Kommunikations-Coach | | | ☐ ja ☐ nein | | |
|
||
| `workspace` | AI Workspace | | | ☐ ja ☐ nein | | |
|
||
|
||
> **Hinweis Store:** In `Store.tsx` sind derzeit u. a. `automation` und `teamsbot` als Self-Service beschrieben — weitere Features können folgen, sobald Backend/Policy das erlaubt.
|
||
|
||
---
|
||
|
||
## 5. Views als Upsell-Stufen (fein granulare Monetarisierung)
|
||
|
||
Viele **Views** sind Kandidaten für „Basic / Pro“ oder Add-ons (technisch: Rechte pro View).
|
||
|
||
**Vorgehen pro Feature:** Liste die Views und markiere: **Base** (muss rein), **Upsell**, **Admin-only** (meist kein direkter Upsell).
|
||
|
||
### `trustee`
|
||
|
||
- [ ] `dashboard` — Base / Upsell / Admin-only
|
||
- [ ] `positions` — …
|
||
- [ ] `documents` — …
|
||
- [ ] `position-documents` — …
|
||
- [ ] `expense-import` — …
|
||
- [ ] `scan-upload` — …
|
||
- [ ] `instance-roles` (adminOnly) — …
|
||
- [ ] `settings` — …
|
||
|
||
### `chatbot`
|
||
|
||
- [ ] `conversations` — …
|
||
- [ ] `settings` — …
|
||
|
||
### `automation`
|
||
|
||
- [ ] `definitions` — …
|
||
- [ ] `templates` — …
|
||
- [ ] `logs` — …
|
||
|
||
### `teamsbot`
|
||
|
||
- [ ] `dashboard` — …
|
||
- [ ] `sessions` — …
|
||
- [ ] `settings` — …
|
||
|
||
### `neutralization`
|
||
|
||
- [ ] `playground` / `dashboard` — …
|
||
- [ ] `config` — …
|
||
- [ ] `attributes` — …
|
||
|
||
### `commcoach`
|
||
|
||
- [ ] `dashboard` — …
|
||
- [ ] `coaching` — …
|
||
- [ ] `dossier` — …
|
||
- [ ] `settings` — …
|
||
|
||
### `workspace`
|
||
|
||
- [ ] `dashboard` — …
|
||
- [ ] `editor` — …
|
||
- [ ] `settings` — …
|
||
|
||
### `realestate`
|
||
|
||
- [ ] `dashboard` — …
|
||
- [ ] `instance-roles` (adminOnly) — …
|
||
|
||
### `chatworkflow`
|
||
|
||
- [ ] `dashboard` — …
|
||
- [ ] `runs` — …
|
||
- [ ] `files` — …
|
||
|
||
**Paket-Entscheid (freies Feld):**
|
||
|
||
| Paketname | Enthaltene `featureCode`s | Enthaltene Views / Ausnahmen | Limits (Instanzen, Nutzer, Speicher, Credits) |
|
||
|-----------|---------------------------|------------------------------|-----------------------------------------------|
|
||
| Starter | | | |
|
||
| Business | | | |
|
||
| Enterprise | | | |
|
||
|
||
---
|
||
|
||
## 6. Nutzungsmessung vs. Produktversprechen
|
||
|
||
Transaktionen im Billing können unter anderem **`featureCode`**, **`featureInstanceId`**, **`aicoreProvider`**, **`aicoreModel`** tragen — gut für **trans-parente** oder **Feature-spezifische** Auswertung.
|
||
|
||
**Abgleich (interaktiv):**
|
||
|
||
- [ ] Welche Features sollen im Kunden-UI **getrennt** sichtbar sein (`costByFeature` im Usage-Report)?
|
||
- [ ] Welche Kosten werden **in einen Topf** gelegt (einfacheres Pricing, weniger Erklärungsbedarf)?
|
||
- [ ] Gibt es **überproportionale** Kostenfaktoren (z. B. Web-Recherche beim Chatbot), die ein **Aufsatz** oder **Limit** brauchen?
|
||
|
||
**Policy-Sätze (ausfüllen):**
|
||
|
||
1. Wenn Guthaben **`warningThreshold`** unterschreitet, dann: …
|
||
2. Wenn **`blockOnZeroBalance`** aktiv ist, dann welche Features blocken wir zuerst: …
|
||
3. **Trial:** welche Features sind zeitlich / volumenmäßig limitiert: …
|
||
|
||
---
|
||
|
||
## 7. Angebots-Builder (1 Seite für Sales)
|
||
|
||
_Kopiere diesen Block pro Lead._
|
||
|
||
- **Kunde / Segment:** …
|
||
- **Mandanten-Setup:** # Instanzen geplant pro Feature: …
|
||
- **Nutzer / Rollen:** …
|
||
- **Inkludierte Module (`featureCode`):** …
|
||
- **Add-ons (Views):** …
|
||
- **BillingModel:** `PREPAY_MANDATE` / `PREPAY_USER` / `UNLIMITED`
|
||
- **Kontingente:** CHF/Monat, Tokens, API-Calls, Speicher: …
|
||
- **Preisgestaltung:** Listenpreis, Rabatt %, Laufzeit: …
|
||
- **Risiken / Sonderkosten (LLM, Integrationen):** …
|
||
|
||
**Einwand-Notizen:**
|
||
|
||
| Einwand | Antwort / Kompromiss |
|
||
|---------|----------------------|
|
||
| „Wir wollen unbegrenzt.“ | |
|
||
| „Wir haben viele Abteilungen (Instanzen).“ | |
|
||
| „Wir brauchen nur eine View.“ | |
|
||
|
||
---
|
||
|
||
## 8. Definition of Done (Pricing ist „fertig“ besprochen)
|
||
|
||
- [ ] Jedes `featureCode` hat **Paket** + **Messgröße** + **Ausnahmen**
|
||
- [ ] Jede revenue-relevante View ist **Base/Upsell** zugeordnet
|
||
- [ ] Store-Features haben **Activation Policy** (wer darf, was passiert nach Trial)
|
||
- [ ] Billing-Model pro Segment ist festgelegt inkl. **Warn-/Block-Verhalten**
|
||
- [ ] Sales-Template (Abschnitt 7) ist befüllt für **Pilotkunde 1**
|
||
|
||
---
|
||
|
||
## 9. Referenz im Repo (für Technik-Abgleich)
|
||
|
||
| Thema | Datei |
|
||
|-------|--------|
|
||
| Feature-Definitionen (Codes, Views) | `src/types/mandate.ts` (`FEATURE_REGISTRY`) |
|
||
| Mandant → Instanzen → Rechte | `src/stores/featureStore.tsx` |
|
||
| Self-Service Store | `src/pages/Store.tsx`, `src/api/storeApi.ts` |
|
||
| Billing-Typen & Reports | `src/api/billingApi.ts` |
|
||
| UI-Komponenten / Routing-Helfer | `src/config/pageRegistry.tsx` |
|
||
|
||
---
|
||
|
||
*Version: 2026-03-20 — ausgerichtet auf den Stand von `frontend_nyla`; bei neuen Features die Tabellen in Abschnitt 4–5 ergänzen.*
|