Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -1,6 +1,6 @@
# Block 7: Plattform-Außenseite (Betrieb, Compliance, Zugang)
Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbares Produkt machen: das Audit-Log für Nachvollziehbarkeit, Stripe-basierte Abrechnung, Onboarding für neue Mandanten, eine Lese-API mit Webhooks für Drittanbieter, der DSGVO-Export, die Mobile-App auf Capacitor-Basis, das öffentliche Hilfe-Center und der interne Help-Desk.
Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbares Produkt machen: das Audit-Log für Nachvollziehbarkeit, Legacy-Provider-basierte Abrechnung, Onboarding für neue Mandanten, eine Lese-API mit Webhooks für Drittanbieter, der DSGVO-Export, die Mobile-App auf Capacitor-Basis, das öffentliche Hilfe-Center und der interne Help-Desk.
---
@@ -76,16 +76,16 @@ Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbare
## Modul 28: Subscriptions / Billing
**Was es tut:** Verbindet HiveGrid mit Stripe als Bezahl-Anbieter und steuert den gesamten Abo-Lebenszyklus jedes Mandanten, vom Trial über aktive Bezahlung, Pausen, Mahnwesen bis zur Kündigung. Zählt Sitzplätze (Büro vs. Monteur) und nutzungsbasierten Verbrauch (Automationen, KI-Verbrauch).
**Was es tut:** Verbindet HiveGrid mit Legacy-Provider als Bezahl-Anbieter und steuert den gesamten Abo-Lebenszyklus jedes Mandanten, vom Trial über aktive Bezahlung, Pausen, Mahnwesen bis zur Kündigung. Zählt Sitzplätze (Büro vs. Monteur) und nutzungsbasierten Verbrauch (Automationen, KI-Verbrauch).
**Warum es wichtig ist:** Ohne stabile, regelkonforme Abrechnung verdient die Plattform kein Geld. Die Mechanik muss flexibel genug sein, dass Preise später angepasst werden können, ohne den Code zu ändern. Apple-Compliance (siehe 28.X) ist dabei ein hartes Tabu, das die ganze Architektur prägt.
### 28.1 Bezahl-Anbieter Stripe
28.1.1 Stripe ist exklusiver Bezahl-Anbieter in Phase 1, Vertragspartner ist die EU-Tochter Stripe Payments Europe (Irland), DSGVO-Auftragsverarbeitungsvertrag elektronisch unterzeichnet beim Signup.
28.1.2 Steuern werden über Stripe Tax mit EU-Reverse-Charge-Logik abgewickelt.
### 28.1 Bezahl-Anbieter Legacy-Provider
28.1.1 Legacy-Provider ist exklusiver Bezahl-Anbieter in Phase 1, Vertragspartner ist die EU-Tochter Legacy-Provider Payments Europe (Irland), DSGVO-Auftragsverarbeitungsvertrag elektronisch unterzeichnet beim Signup.
28.1.2 Steuern werden über Legacy-Provider Tax mit EU-Reverse-Charge-Logik abgewickelt.
28.1.3 Zahlungsarten in Phase 1: SEPA-Lastschrift (Default Deutschland/EU) und Kreditkarte.
28.1.4 Stripe sendet Ereignisse (Webhooks) an HiveGrid: erfolgreicher Bezahlvorgang, Rechnung erstellt, Zahlung gescheitert, Plan geändert, Subscription gelöscht, Trial-Ende-Vorwarnung.
28.1.5 Jedes Stripe-Ereignis wird genau einmal verarbeitet (Doppel-Schutz über eindeutige Stripe-Event-Kennung).
28.1.4 Legacy-Provider sendet Ereignisse (Webhooks) an HiveGrid: erfolgreicher Bezahlvorgang, Rechnung erstellt, Zahlung gescheitert, Plan geändert, Subscription gelöscht, Trial-Ende-Vorwarnung.
28.1.5 Jedes Legacy-Provider-Ereignis wird genau einmal verarbeitet (Doppel-Schutz über eindeutige Legacy-Provider-Event-Kennung).
28.1.6 Plan-Konfiguration ist nicht im Code festgenagelt, sondern in Daten-Strukturen, neue Pläne, Preise und Quotas sind ohne Code-Release änderbar.
### 28.2 Seat-Modell (Büro/Monteur)
@@ -95,7 +95,7 @@ Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbare
28.2.2 Bei jeder Mitarbeiter-Einladung wählt der Mandanten-Admin den Sitzplatz-Typ, Pflichtfeld.
28.2.3 Sitzplatz-Typ ist Lizenz-Konzept, Rolle ist Rechte-Konzept, getrennt.
28.2.4 Monteur-Sitzplatz darf nur Rollen mit Default-Modus „Baustelle" bekommen (Validierungs-Regel).
28.2.5 Sitzplatz-Zähler werden bei jeder Einladung/Aktivierung/Deaktivierung mit Stripe synchronisiert.
28.2.5 Sitzplatz-Zähler werden bei jeder Einladung/Aktivierung/Deaktivierung mit Legacy-Provider synchronisiert.
28.2.6 Plan-Quotas (z.B. „max. 10 Büro-Sitzplätze, max. 50 Monteur-Sitzplätze") sind pro Plan konfigurierbar.
28.2.7 Quota-Verhalten: Default „Hartes Limit", neue Einladung blockiert mit Klartext-Hinweis. Optional „weiches Limit", zusätzliche Sitzplätze werden automatisch nutzungsbasiert abgerechnet.
28.2.8 Verbrauchs-Übersicht im Mandanten-Admin zeigt aktuelle Sitzplätze pro Typ, verfügbare Sitzplätze laut Plan, Trend-Chart.
@@ -107,17 +107,17 @@ Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbare
28.3.4 Zahlungsmethode ist im Vertriebs-Modus nicht zwingend zu Trial-Beginn.
28.3.5 3 Tage und 1 Tag vor Trial-Ende: In-App-Banner und E-Mail-Benachrichtigung mit Klartext-Hinweis und Verweis auf Marketing-Site (NICHT auf In-App-Upgrade, siehe Apple-Compliance 28.X).
28.3.6 Trial-Ende ohne Konversion: Mandant geht in 30-Tage-Lösch-Vorlauf (siehe Modul 35.6).
28.3.7 Trial-Konversion läuft über Marketing-Site, von dort zurück in die App mit Stripe-Session-Token.
28.3.7 Trial-Konversion läuft über Marketing-Site, von dort zurück in die App mit Legacy-Provider-Session-Token.
### 28.4 Read-Only-Downgrade bei Nichtzahlung
28.4.1 Wenn der Mandant nicht bezahlt, kann er nur noch ansehen, nichts mehr ändern, bis er bezahlt, das ist die Klartext-Idee dahinter.
28.4.2 Auslöser: Stripe meldet Zahlung gescheitert.
28.4.3 Stripe-Standard-Mahnwesen: 3 automatische Wiederholungs-Versuche über 14 Tage (typisch Tag 0, 3, 7, 14).
28.4.2 Auslöser: Legacy-Provider meldet Zahlung gescheitert.
28.4.3 Legacy-Provider-Standard-Mahnwesen: 3 automatische Wiederholungs-Versuche über 14 Tage (typisch Tag 0, 3, 7, 14).
28.4.4 Während Mahnwesen wechselt der Mandant in den Status „Zahlung überfällig" → kompletter Workspace ist Read-Only:
- Anmeldung, Daten lesen, Kunden-Portal-Zugang (Endkunden) und Stripe-Kunden-Portal-Zugang bleiben möglich.
- Anmeldung, Daten lesen, Kunden-Portal-Zugang (Endkunden) und Legacy-Provider-Kunden-Portal-Zugang bleiben möglich.
- Stammdaten-Edits, neue Datensätze, E-Mail-/WhatsApp-/Push-Versand, Automationen-Ausführung, eingehende Webhooks und API-Schreiboperationen sind blockiert.
- Eingehende Trigger werden verworfen (nicht in Warteschlange), sonst stauen sich Aktionen auf, die mit gepausten Zahlungen kollidieren.
28.4.5 Klartext-Banner: „Zahlung fehlgeschlagen, Konto in 14 Tagen gesperrt, [Zahlungsmethode aktualisieren]" mit Direkt-Link zum Stripe-Kunden-Portal.
28.4.5 Klartext-Banner: „Zahlung fehlgeschlagen, Konto in 14 Tagen gesperrt, [Zahlungsmethode aktualisieren]" mit Direkt-Link zum Legacy-Provider-Kunden-Portal.
28.4.6 E-Mail-Benachrichtigungen an Mandanten-Admins bei jedem Zustand: erste Zahlung gescheitert, 2. Versuch gescheitert, 1 Tag vor finalem Cancel.
28.4.7 Nach 3 Fehlversuchen + 14 Tagen ohne Erfolg: Status wechselt auf „gekündigt".
28.4.8 Sobald Zahlung nachgereicht: automatischer Wechsel zurück auf „aktiv".
@@ -126,16 +126,16 @@ Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbare
28.5.1 Der Mandant kann seinen Workspace freiwillig pausieren statt zu kündigen, gedacht für Saison-Pausen kleiner Betriebe.
28.5.2 Reduzierte Gebühr (Default ca. 1/10 des Standardpreises, exakte Werte gehören in die Pricing-Festlegung), Workspace Read-Only, jederzeit reaktivierbar, Daten bleiben erhalten.
28.5.3 Pause-Bestätigung erfordert Eingabe der Phrase „PAUSIEREN" als Schutz gegen Versehen.
28.5.4 Reaktivierung über Bezahl-Vorgang in Stripe.
28.5.4 Reaktivierung über Bezahl-Vorgang in Legacy-Provider.
### 28.6 Rechnungsstellung
28.6.1 Rechnungs-Übersicht im Mandanten-Admin als Stripe-Kunden-Portal eingebettet (von Stripe gehostet).
28.6.1 Rechnungs-Übersicht im Mandanten-Admin als Legacy-Provider-Kunden-Portal eingebettet (von Legacy-Provider gehostet).
28.6.2 Funktionen dort: Rechnungs-Historie als PDF herunterladen, Zahlungsmethode aktualisieren, Steuer-Daten/USt-IdNr. editieren.
28.6.3 Rechnungen werden in HiveGrid als Referenz gespiegelt; Original-Dateien lädt der User aus Stripe.
28.6.3 Rechnungen werden in HiveGrid als Referenz gespiegelt; Original-Dateien lädt der User aus Legacy-Provider.
### 28.7 Setup-Gebühren
28.7.1 Pro Plan optional eine einmalige Setup-Gebühr.
28.7.2 Im Stripe-Bezahlvorgang erscheinen zwei Posten, wiederkehrender Plan-Preis plus einmalige Setup-Gebühr.
28.7.2 Im Legacy-Provider-Bezahlvorgang erscheinen zwei Posten, wiederkehrender Plan-Preis plus einmalige Setup-Gebühr.
28.7.3 Bei Plan-Wechsel zu höherem Plan wird nur die Differenz der Setup-Gebühr berechnet.
28.7.4 Klartext-Hinweis im Bezahlvorgang: „Bei Buchung wird zusätzlich eine einmalige Setup-Gebühr von [Betrag] berechnet."
@@ -144,14 +144,14 @@ Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbare
28.8.2 Pro Plan ein **Inklusiv-Volumen** plus **Aufschlags-Tarif** für Mehrverbrauch (Pay-as-you-go). KI-Funktionen werden NICHT pausiert (siehe M18.8). Konkrete Schwellen und Stückpreise mit Pricing-Festlegung (geparkt, siehe H.1.1).
28.8.3 Verbrauchs-Sicht im Mandanten-Admin: aktuelle Periode, Inklusiv-Menge, Verbrauch in Prozent, Trend, Historie der letzten 12 Perioden, aktueller Aufschlags-Verbrauch in Euro, voraussichtlicher Monats-Aufschlag, CSV-Export.
28.8.4 KI-Inklusiv-Menge verfällt am Periodenende. Manuelle Boni vom Vertrieb bleiben.
28.8.5 **Aufschlags-Verbrauch** wird pro Stripe-Rechnungs-Periode als separate Position ausgewiesen (Detail-Aufschlüsselung pro KI-Funktion und Tag).
28.8.5 **Aufschlags-Verbrauch** wird pro Legacy-Provider-Rechnungs-Periode als separate Position ausgewiesen (Detail-Aufschlüsselung pro KI-Funktion und Tag).
28.8.6 **Notbremse**: pro Mandant konfigurierbar, max. Aufschlags-Betrag pro Monat. Bei Erreichen wird in Drosselungs-Modus geschaltet (nur Klartext-Diagnostik bleibt aktiv), nicht in Komplett-Pause. Klartext-Warnung an Administrator (siehe M18.8.7).
28.8.7 **Upsell-Vorschlag**: wenn Aufschlag in 2 aufeinanderfolgenden Monaten höher liegt als die Differenz zum nächsten Plan, schlägt das System aktiv ein Upgrade vor. Soft-Recommendation, kein Zwang.
28.8.8 Bei aufgebrauchtem Inklusiv-Volumen: Klartext im Banner: *„Inklusiv-Volumen verbraucht, weitere Anfragen kosten ab jetzt [Aufschlags-Tarif] pro 1.000 Tokens. [Plan-Vergleich auf hivegrid.de]"*. Web-App: direkter Link zur Vergleichs-Seite. Mobile-App: Hinweis ohne Upgrade-UI (Apple-Compliance, siehe 28.X.10).
### 28.X Phase 2 / bewusst NICHT in Phase 1
28.X.1 In-App-Plan-Wechsel und Add-On-Käufe (alles muss zur Marketing-Site, Apple-Compliance Phase 1).
28.X.2 Mehr-Mandanten-Abrechnung für Konzerne (mehrere Mandanten in einer Stripe-Subscription gebündelt).
28.X.2 Mehr-Mandanten-Abrechnung für Konzerne (mehrere Mandanten in einer Legacy-Provider-Subscription gebündelt).
28.X.3 Individual-Pricing pro Mandant durch Plattform-Admin (Enterprise-Verhandlung).
28.X.4 Promo-Code-System mit Rabatt-Codes im Bezahlvorgang.
28.X.5 Jahres-Abrechnung mit konfigurierbarem Jahres-Rabatt.
@@ -182,7 +182,7 @@ Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbare
**Warum es wichtig ist:** Wenn der Mandant nach Anmeldung in einer leeren App landet und nicht weiß, wo er anfangen soll, ist er weg. Onboarding entscheidet über die Aktivierungs-Quote. Branchen-Templates müssen so abgelegt sein, dass Phase 2 weitere Branchen ohne Code-Patch möglich macht.
### 29.1 Mandanten-Anmeldung (Tenant-Anlage)
29.1.1 Anmelde-Pfad: Marketing-Site `hivegrid.de/signup` → in-App-Account-Anlage → Mandanten-Daten → Plan-Auswahl → Stripe-Bezahlvorgang → Onboarding-Wizard.
29.1.1 Anmelde-Pfad: Marketing-Site `hivegrid.de/signup` → in-App-Account-Anlage → Mandanten-Daten → Plan-Auswahl → Legacy-Provider-Bezahlvorgang → Onboarding-Wizard.
29.1.2 Beim ersten Login auf der Mandanten-Adresse: automatische Weiterleitung in den Wizard.
29.1.3 Wizard läuft im Vollbild-Modus ohne Sidebar, mit Fortschritts-Anzeige.
29.1.4 Wizard ist resumable, bei Abbruch wird beim nächsten Login zum letzten Schritt zurückgekehrt.
@@ -378,7 +378,7 @@ Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbare
35.3.1 Mandanten-Kündigung läuft als Multi-Step-Workflow:
- Schritt 1: Klartext-Erklärung was passiert (Status wechselt sofort auf „Lösch-Vorlauf", Workspace bleibt 30 Tage Read-Only sichtbar, danach Hard-Delete aller Daten unwiderruflich).
- Schritt 2: Datensicherungs-Hinweis mit Direkt-Link zum Mandanten-Export.
- Schritt 3: Stripe-Hinweis (Restbetrag, Pro-rata-Erstattung, letzte Rechnung).
- Schritt 3: Legacy-Provider-Hinweis (Restbetrag, Pro-rata-Erstattung, letzte Rechnung).
- Schritt 4: Identitäts-Bestätigung (Passwort + 2FA).
- Schritt 5: Final-Klick mit Eingabe des Mandanten-Slugs als Confirm-Phrase.
35.3.2 30-Tage-Grace-Period: jeder Mandanten-Admin kann mit einem Klick zurückziehen, Status zurück auf „aktiv". Audit dokumentiert wer kündigte und wer zurückzog.
@@ -601,7 +601,7 @@ Acht Module, die HiveGrid als bezahlbares, regelkonformes und sicher betreibbare
- Mitarbeiter: HR-Hub-Übersicht, Krankmeldung/Urlaubsantrag stellen.
- Integrationen: KWP-Setup, Google-Kalender verbinden, AirCall-Setup, E-Mail-Integration (Gmail/Outlook).
- Mobile: Mobile-App-Setup, Offline-Modus auf Baustelle.
- Abrechnung: Stripe-Setup, Plan wechseln, Rechnungen einsehen.
- Abrechnung: Legacy-Provider-Setup, Plan wechseln, Rechnungen einsehen.
- Tutorials: Form-Builder-Tutorial, Automation-Builder-Tutorial.
38.2.2 Phase 1 nur Deutsch. Andere Sprachen: 404 mit Klartext-Banner „Englischsprachige Hilfe ist in Vorbereitung. Hier ist die deutsche Version." plus automatischer Redirect auf DE.
38.2.3 Performance Phase 1: Client-side Volltext-Index (FlexSearch oder ähnlich, ca. 50 KB für 20 Artikel) ODER Server-side Postgres-FTS, Tooling-Wahl beim Bau.