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

@@ -245,7 +245,7 @@
</tr>
<tr>
<td><strong>Apps-Engine</strong></td>
<td>Die zentrale Schicht, über die alle externen Systeme (KWP, Gmail, AirCall, Stripe, ...) angebunden werden, einheitlich, austauschbar.</td>
<td>Die zentrale Schicht, über die alle externen Systeme (KWP, Gmail, AirCall, Legacy-Provider, ...) angebunden werden, einheitlich, austauschbar.</td>
</tr>
<tr>
<td><strong>Adapter</strong></td>
@@ -426,7 +426,7 @@
<tr>
<td>M28</td>
<td>Subscriptions / Billing</td>
<td>Stripe-Anbindung, Seat-Modell, Trial, Read-Only-Downgrade</td>
<td>Legacy-Provider-Anbindung, Seat-Modell, Trial, Read-Only-Downgrade</td>
</tr>
<tr>
<td>M29</td>
@@ -550,7 +550,7 @@
<p>A.1.2 <strong>Keine KI-on-the-fly-Übersetzung von Fehlertexten</strong> in Phase 1. Texte sind redaktionell vorgefertigt, durchsuchbar, mehrsprach-fähig (über das i18n-Modul M30).</p>
<p>A.1.3 Kein Feature wird freigegeben, bevor die Klartext-Texte definiert und im Pflichtenheft des jeweiligen Moduls aufgeführt sind.</p>
<h2 id="a2-adapter-schicht-für-jede-integration">A.2 Adapter-Schicht für jede Integration</h2>
<p>A.2.1 Externe Systeme (KWP, Gmail, AirCall, Stripe, PandaDoc, Calendar, ...) werden <strong>nur über die Apps-Engine</strong> (Modul 33a) angebunden, nie direkt aus einem Modul heraus.</p>
<p>A.2.1 Externe Systeme (KWP, Gmail, AirCall, Legacy-Provider, PandaDoc, Calendar, ...) werden <strong>nur über die Apps-Engine</strong> (Modul 33a) angebunden, nie direkt aus einem Modul heraus.</p>
<p>A.2.2 Auch wenn aktuell nur eine konkrete Implementierung existiert (z. B. nur KWP als ERP), wird das Adapter-Interface so gebaut, dass weitere ERPs (Taifun, TopKontor) später ohne Engine-Umbau dazu kommen.</p>
<p>A.2.3 Verbindungs-Status, Sync-Jobs und Klartext-Diagnostik sind <strong>über alle Apps einheitlich</strong>: gleiche Anzeige, gleiche Bedien-Logik.</p>
<h2 id="a3-branchen-templates-deklarativ-nicht-hartkodiert">A.3 Branchen-Templates deklarativ, nicht hartkodiert</h2>
@@ -934,7 +934,7 @@
37.4.2 Mandanten-Verwaltung.
37.4.3 Mandanten-Mitarbeiter-Verwaltung (alle Mitarbeiter aller Mandanten).
37.4.4 Plattform-Admin-Verwaltung (unsere eigenen Konten und Rollen).
37.4.5 Abo-Verwaltung (Anbindung an Stripe).
37.4.5 Abo-Verwaltung (Anbindung an Legacy-Provider).
37.4.6 Funktions-Schalter (siehe Modul 32).
37.4.7 System-Gesundheit (Server, Hintergrund-Aufgaben, KWP-Sync).
37.4.8 Plattform-weites Audit-Protokoll.
@@ -979,10 +979,10 @@
37.9.2 Plattform-Admin anlegen (Email, Name, Anfangs-Rolle), der Eingeladene bekommt einen Einrichtungs-Link mit verpflichtender 2FA-Einrichtung.
37.9.3 Rolle ändern, deaktivieren, zweiten Faktor zurücksetzen (durch anderen Super-Admin), Sitzungen beenden.</p>
<h3 id="3710-abo-verwaltung">37.10 Abo-Verwaltung</h3>
<p>37.10.1 Liste aller Abos mit Mandant, Tarif, Monatsumsatz, Status, Verlängerungs-Datum, Stripe-Sync-Status.
37.10.2 Detail-Ansicht mit Stripe-Verknüpfungen (Direkt-Link zum Stripe-Dashboard), aktuellem Tarif, Sitz-Anzahl (Büro + Monteur), Test-Phase, Rechnungs-Historie, Notizen über manuelle Sonder-Konditionen.
37.10.3 Mögliche Aktionen: Stripe-Abgleich erzwingen, Tarif manuell überschreiben (Enterprise-Sonderpreise mit Begründungs-Pflicht), Test-Phase verlängern, manuelle Rechnung anstoßen, Abo kündigen, Rückzahlung anstoßen.
37.10.4 Wenn die Daten in HiveGrid und in Stripe auseinanderlaufen, wird das im Detail mit Klartext-Vergleich angezeigt.</p>
<p>37.10.1 Liste aller Abos mit Mandant, Tarif, Monatsumsatz, Status, Verlängerungs-Datum, Legacy-Provider-Sync-Status.
37.10.2 Detail-Ansicht mit Legacy-Provider-Verknüpfungen (Direkt-Link zum Legacy-Provider-Dashboard), aktuellem Tarif, Sitz-Anzahl (Büro + Monteur), Test-Phase, Rechnungs-Historie, Notizen über manuelle Sonder-Konditionen.
37.10.3 Mögliche Aktionen: Legacy-Provider-Abgleich erzwingen, Tarif manuell überschreiben (Enterprise-Sonderpreise mit Begründungs-Pflicht), Test-Phase verlängern, manuelle Rechnung anstoßen, Abo kündigen, Rückzahlung anstoßen.
37.10.4 Wenn die Daten in HiveGrid und in Legacy-Provider auseinanderlaufen, wird das im Detail mit Klartext-Vergleich angezeigt.</p>
<h3 id="3711-system-gesundheit">37.11 System-Gesundheit</h3>
<p>37.11.1 Status pro Dienst (Web, API, Hintergrund-Aufgaben, Plan-Job-System, Datenbank, Zwischenspeicher, Datei-Speicher) mit Verfügbarkeit, Antwort-Zeiten, Fehler-Quote.
37.11.2 Hintergrund-Aufgaben-Bereich mit Liste aller Warteschlangen (Automatisierung, Email-Versand, KWP-Sync, Datenschutz-Export …), Status (in Arbeit, wartend, fehlgeschlagen, abgeschlossen), Möglichkeit fehlgeschlagene Aufgaben erneut zu starten oder Warteschlangen zu pausieren.
@@ -1031,12 +1031,12 @@
<h3 id="3718-klartext-hinweise-beispiele">37.18 Klartext-Hinweise (Beispiele)</h3>
<p>37.18.1 Status-Wechsel ohne Begründung: „Bitte Begründung angeben, wird im Audit-Log dauerhaft gespeichert."
37.18.2 Stellvertreter-Anmeldung ohne Begründung: blockiert, gleicher Hinweis.
37.18.3 Sonder-Tarif: „Diese Konditionen weichen vom Standard-Plan ab. Stripe wird nicht angepasst, manuelle Rechnungs-Erstellung erforderlich. [Verstanden, fortfahren]"
37.18.3 Sonder-Tarif: „Diese Konditionen weichen vom Standard-Plan ab. Legacy-Provider wird nicht angepasst, manuelle Rechnungs-Erstellung erforderlich. [Verstanden, fortfahren]"
37.18.4 Doppelte Plattform-Admin-Email: „Diese Email gehört bereits zu einem Plattform-Admin ‚X‘, bitte direkt diesen verwalten."
37.18.5 Letzter Super-Admin: „Du bist der einzige Super-Admin. Rechte-Entzug nicht möglich. Bitte zuerst weiteren Super-Admin anlegen."
37.18.6 Konto gesperrt nach Fehlversuchen: „Account gesperrt nach 10 Fehlversuchen. Bitte anderen Super-Admin um Reaktivierung bitten."
37.18.7 Lösch-Anstoß im Auftrag: „Du startest die Kündigung für Mandant ‚X‘ im Auftrag. Bestätigungs-Email geht an alle Mandanten-Administratoren mit Cancel-Link."
37.18.8 Stripe-Konflikt: „Stripe-Stand und HiveGrid-Stand weichen ab. Bitte manuell prüfen: [Stripe-Wert] vs. [HiveGrid-Wert]."
37.18.8 Legacy-Provider-Konflikt: „Legacy-Provider-Stand und HiveGrid-Stand weichen ab. Bitte manuell prüfen: [Legacy-Provider-Wert] vs. [HiveGrid-Wert]."
37.18.9 Warteschlangen-Pause: „Warteschlange ‚X‘ pausiert. Neue Aufgaben werden eingereiht aber nicht verarbeitet. Vergiss nicht zu reaktivieren!"
37.18.10 Massen-Email an Mandanten-Administratoren: „Diese Email geht an X Mandanten-Administratoren. Bitte nochmal Betreff und Inhalt prüfen. [Senden]"</p>
<h1 id="block-2-stammdaten">Block 2: Stammdaten</h1>
@@ -1899,20 +1899,20 @@
<p>Hier liegt der Wettbewerbsvorteil von HiveGrid gegenüber HubSpot/Quiply: eine einheitliche Anbindungs-Schicht für externe Systeme, eine Automatisierungs-Engine mit KI-Erstellung per Sprache, ein KI-Layer komplett auf europäischen Modellen (DSGVO), und die saubere Anbindung an die Geerkens-Bestands-ERP KWP.</p>
<hr />
<h2 id="modul-33a-apps-engine-einheitliche-anbindungs-schicht">Modul 33a: Apps-Engine (einheitliche Anbindungs-Schicht)</h2>
<p><strong>Was es tut:</strong> Stellt eine einheitliche Anbindungs-Schnittstelle für alle externen Systeme bereit (KWP, Gmail, AirCall, Stripe, Google Calendar, PandaDoc, …). Jedes externe System wird zur „App", mit gleichem Verbindungs-Aufbau, gleichem Status-Verhalten, gleichen Fehler-Texten, gleichem Sync-Verlauf.
<p><strong>Was es tut:</strong> Stellt eine einheitliche Anbindungs-Schnittstelle für alle externen Systeme bereit (KWP, Gmail, AirCall, Legacy-Provider, Google Calendar, PandaDoc, …). Jedes externe System wird zur „App", mit gleichem Verbindungs-Aufbau, gleichem Status-Verhalten, gleichen Fehler-Texten, gleichem Sync-Verlauf.
<strong>Löst ab:</strong> Das individuelle Verdrahten externer Systeme (Zapier, Supabase-Glue, eigens gebaute Adapter).
<strong>Warum es wichtig ist:</strong> Ohne diese Foundation wird jede neue Anbindung wieder Sonder-Code mit Sonder-Fehlern. Die Apps-Engine ist die Plattform-Grundlage, auf der KWP, Telefonie, Mail-Sync und Zahlungs-Anbindung sauber aufsetzen. <strong>Phase 1 ist nur die Auswahl der Apps, die Geerkens braucht</strong> (KWP, Gmail, AirCall, Stripe, Calendar). Marketplace und Drittanbieter-Apps sind ausdrücklich Phase 2.</p>
<strong>Warum es wichtig ist:</strong> Ohne diese Foundation wird jede neue Anbindung wieder Sonder-Code mit Sonder-Fehlern. Die Apps-Engine ist die Plattform-Grundlage, auf der KWP, Telefonie, Mail-Sync und Zahlungs-Anbindung sauber aufsetzen. <strong>Phase 1 ist nur die Auswahl der Apps, die Geerkens braucht</strong> (KWP, Gmail, AirCall, Legacy-Provider, Calendar). Marketplace und Drittanbieter-Apps sind ausdrücklich Phase 2.</p>
<h3 id="33a1-was-eine-app-ist">33a.1 Was eine App ist</h3>
<p>33a.1.1 Eine App ist die Anbindung an ein externes System (Beispiele: KWP, Gmail, AirCall, Stripe, Google Calendar, PandaDoc).
<p>33a.1.1 Eine App ist die Anbindung an ein externes System (Beispiele: KWP, Gmail, AirCall, Legacy-Provider, Google Calendar, PandaDoc).
33a.1.2 Jede App hat einen Namen, eine Kategorie (z.B. ERP, Kommunikation, Kalender, Zahlung), eine Beschreibung und eine eindeutige Anbindungs-Art (z.B. Single-Sign-On per OAuth, API-Schlüssel, lokales Sync-Programm).
33a.1.3 Eine App kann pro Tenant mehrfach verbunden werden (Beispiel: drei Gmail-Postfächer in einem Betrieb, oder zwei KWP-Server an verschiedenen Standorten). Eine Verbindung trägt einen sprechenden Namen, den der Tenant-Admin selber vergibt („Geerkens Hauptbüro KWP").
33a.1.4 Phase 1 sind ausschließlich die für Geerkens benötigten Apps freigeschaltet: KWP, Gmail, AirCall, Stripe, Google Calendar, PandaDoc. Alle weiteren Apps werden bewusst zurückgehalten, bis sie ein zahlender Kunde braucht.
33a.1.4 Phase 1 sind ausschließlich die für Geerkens benötigten Apps freigeschaltet: KWP, Gmail, AirCall, Legacy-Provider, Google Calendar, PandaDoc. Alle weiteren Apps werden bewusst zurückgehalten, bis sie ein zahlender Kunde braucht.
33a.1.5 Eine App kann an einen Funktions-Plan gekoppelt sein (Beispiel: KWP nur in „Cloud Plus"). In tieferen Plänen wird die App im Catalog als „nicht im aktuellen Paket" markiert.</p>
<h3 id="33a2-verbindung-herstellen-setup-wizard">33a.2 Verbindung herstellen (Setup-Wizard)</h3>
<p>33a.2.1 Jede App hat einen geführten Setup-Wizard mit immer derselben Reihenfolge: (1) Voraussetzungs-Check in Klartext, (2) Eingabe der Zugangsdaten oder OAuth-Anmeldung, (3) automatische Prüfung der Verbindung, (4) optionaler Initial-Sync der Bestandsdaten.
33a.2.2 Die nötigen Eingabefelder pro App werden automatisch aus der App-Definition erzeugt, der Tenant-Admin sieht nur das, was die jeweilige App tatsächlich benötigt.
33a.2.3 Vier Anbindungs-Arten werden in Phase 1 unterstützt: (a) Single-Sign-On per OAuth (Gmail, Google Calendar, Microsoft), (b) API-Schlüssel (Stripe, PandaDoc), (c) Benutzername/Passwort (Legacy-Systeme), (d) lokales Sync-Programm beim Kunden vor Ort (KWP, siehe Modul 19).
33a.2.4 Vor Abschluss prüft das System die Verbindung mit einem Probe-Aufruf. Bei Fehlschlag erscheint ein Klartext-Hinweis mit konkretem Lösungsvorschlag (z.B. „Der API-Schlüssel ist falsch oder abgelaufen. Bitte einen neuen Schlüssel im Stripe-Dashboard erstellen und hier einsetzen.").
33a.2.3 Vier Anbindungs-Arten werden in Phase 1 unterstützt: (a) Single-Sign-On per OAuth (Gmail, Google Calendar, Microsoft), (b) API-Schlüssel (Legacy-Provider, PandaDoc), (c) Benutzername/Passwort (Legacy-Systeme), (d) lokales Sync-Programm beim Kunden vor Ort (KWP, siehe Modul 19).
33a.2.4 Vor Abschluss prüft das System die Verbindung mit einem Probe-Aufruf. Bei Fehlschlag erscheint ein Klartext-Hinweis mit konkretem Lösungsvorschlag (z.B. „Der API-Schlüssel ist falsch oder abgelaufen. Bitte einen neuen Schlüssel im Legacy-Provider-Dashboard erstellen und hier einsetzen.").
33a.2.5 Nach erfolgreichem Setup kann der Tenant-Admin auf Wunsch direkt einen ersten Sync der Bestandsdaten anstoßen, mit Klartext-Vorschau („1.247 Kontakte und 384 Aufträge aus KWP übernehmen?").</p>
<h3 id="33a3-verbindungs-status-sichtbar-überall">33a.3 Verbindungs-Status (sichtbar überall)</h3>
<p>33a.3.1 Jede Verbindung hat zu jedem Zeitpunkt genau einen von fünf Zuständen: <strong>wartet auf Setup</strong>, <strong>aktiv</strong>, <strong>eingeschränkt</strong>, <strong>defekt</strong>, <strong>getrennt</strong>.
@@ -2064,7 +2064,7 @@
- Sichtbarkeit pro Vorlage: nur intern (eigener Mandant) / öffentlich-mit-Mandanten-Zustimmung (Marketplace, Phase 2) / öffentlich-kostenfrei / öffentlich-kostenpflichtig.
- Mandanten-eigene Vorlagen sind in Phase 1 nur intern sichtbar; Marketplace-Sichtbarkeit wird in Phase 2 aktiviert.
17.10.4 <strong>Kommerzielle Vorlagen-Anbieterschaft (Phase 1 vorbereitet, Phase 2 aktiviert)</strong>:
- Plattform-Vorlagen können kostenpflichtig sein (Einmalzahlung pro Mandant; alternativ Mini-Abo). Bezahlung läuft über das Subscription-Modul (M28) und Stripe.
- Plattform-Vorlagen können kostenpflichtig sein (Einmalzahlung pro Mandant; alternativ Mini-Abo). Bezahlung läuft über das Subscription-Modul (M28) und Legacy-Provider.
- Mandanten-Vorlagen, die im Marketplace verkauft werden, generieren Umsatz an den anbietenden Mandanten (Revenue-Share). Konkrete Provision wird mit dem Pricing-Modell festgelegt (geparkt, siehe H.1.1).
- Auswertung pro Vorlage: Anzahl Anwendungen, Anzahl bezahlter Käufe, häufige Anpassungen durch Anwender.
17.10.5 <strong>Service-Einsätze und Wartung sind keine Beispiele</strong> (siehe N9): „Wartungstermin-Reminder" wurde durch „Termin-Erinnerung an Endkunden" ersetzt, die für jede Termin-Art (Vor-Ort-Termin, Abnahme, Service) gilt. Ein dediziertes Service-Modul kommt erst in Phase 2.</p>
@@ -2152,7 +2152,7 @@
18.8.5 <strong>Upsell-Logik</strong>:
- Wenn der Aufschlags-Verbrauch in einem Monat höher ist als die Differenz zum nächsten Plan, schlägt das System dem Mandanten-Administrator aktiv vor, das Abo zu upgraden („Du hast diesen Monat 87 Euro Aufschlag bezahlt. Mit Plan Cloud+ (49 Euro/Monat zusätzlich) wäre alles enthalten.").
- Soft-Recommendation, kein Zwang.
18.8.6 <strong>Rechnungsstellung</strong>: Aufschlags-Verbrauch wird in der nächsten Stripe-Rechnung als Zusatzposition ausgewiesen. Mandant sieht in M28 (Subscription) den exakten Verbrauch nachvollziehbar.
18.8.6 <strong>Rechnungsstellung</strong>: Aufschlags-Verbrauch wird in der nächsten Legacy-Provider-Rechnung als Zusatzposition ausgewiesen. Mandant sieht in M28 (Subscription) den exakten Verbrauch nachvollziehbar.
18.8.7 <strong>Notbremse für Missbrauch</strong>: pro Mandant gibt es eine konfigurierbare absolute Obergrenze („nie mehr als X Euro Aufschlag pro Monat"). Wird sie erreicht, geht das System NICHT in Pause, sondern in einen Drosselungs-Modus mit Klartext-Warnung an den Administrator („Notbremse erreicht, ab jetzt nur noch geschäftskritische KI-Aufrufe (Klartext-Diagnostik). Sofortige Reaktion empfohlen."). Damit ist das Kostenrisiko gedeckelt, aber nichts geht schlagartig schwarz.
18.8.8 Reset des Inklusiv-Volumens zum Monatsersten.
18.8.9 Im Verbrauchs-Bereich des Mandanten-Administrators werden gezeigt: Verbrauch pro Anwendungsfall, Verbrauch über Zeit, Top-Verbraucher (welche Module / welche Nutzer), Hochrechnung Monatsende, aktueller Tarif, Notbremse-Stand.</p>
@@ -2968,7 +2968,7 @@
6.11.2 Automatische Erinnerungs-Mails 24h und 1h vor dem Termin.
6.11.3 SMS-Erinnerungen (kostenpflichtige Zusatz-Funktion).
6.11.4 Eigene Domain für Buchungsseiten (<code>termine.geerkens.de</code>).
6.11.5 Vorauszahlung / Anzahlung über Stripe.
6.11.5 Vorauszahlung / Anzahlung über Legacy-Provider.
6.11.6 Gruppen-Termine (mehrere Endkunden für einen Slot).
6.11.7 KI-Buchungs-Assistent.</p>
<h3 id="612-klartext-fehlertexte-beispiele">6.12 Klartext-Fehlertexte (Beispiele)</h3>
@@ -3311,7 +3311,7 @@
<p>15.14.1 Bidirektionale Kommunikation (Chat zwischen Endkunde und Tenant).
15.14.2 Eigenes Portal-Branding (Logo + Farben + eigene Domain <code>kunden.geerkens.de</code>).
15.14.3 Mehrere Portale pro Tenant (Privatkunden vs. Bauträger).
15.14.4 Wartungs-Abos / Service-Pakete im Portal abschließbar mit Stripe.
15.14.4 Wartungs-Abos / Service-Pakete im Portal abschließbar mit Legacy-Provider.
15.14.5 Blog/CMS für redaktionelle Inhalte (Wartungs-Tipps, News).
15.14.6 Push-Notifications über installierbare PWA.
15.14.7 Auto-Deaktivierung nach X Tagen ohne Login.
@@ -3437,7 +3437,7 @@
20.10.3 Veraltete Daten: „Daten zuletzt aktualisiert vor 12 Minuten."
20.10.4 Layout-Reset: „Dein angepasstes Layout wird durch das Standard-Layout deiner Rolle ersetzt."</p>
<h1 id="block-7-plattform-außenseite-betrieb-compliance-zugang">Block 7: Plattform-Außenseite (Betrieb, Compliance, Zugang)</h1>
<p>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.</p>
<p>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.</p>
<hr />
<h2 id="modul-21-audit-log">Modul 21: Audit-Log</h2>
<p><strong>Was es tut:</strong> Schreibt für jeden Mandanten einen lückenlosen Verlauf aller verändernden Aktionen mit Vorher-/Nachher-Vergleich mit. Macht nachvollziehbar, wer wann was geändert hat, von Mitarbeitern, Automationen, KI oder externen Schnittstellen.</p>
@@ -3498,14 +3498,14 @@
21.8.6 Ohne Audit-Recht: „Du hast keine Berechtigung, das Audit-Log zu sehen. Bitte Mandanten-Admin kontaktieren."</p>
<hr />
<h2 id="modul-28-subscriptions-billing">Modul 28: Subscriptions / Billing</h2>
<p><strong>Was es tut:</strong> 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).</p>
<p><strong>Was es tut:</strong> 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).</p>
<p><strong>Warum es wichtig ist:</strong> 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.</p>
<h3 id="281-bezahl-anbieter-stripe">28.1 Bezahl-Anbieter Stripe</h3>
<p>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.
<h3 id="281-bezahl-anbieter-legacyProvider">28.1 Bezahl-Anbieter Legacy-Provider</h3>
<p>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.</p>
<h3 id="282-seat-modell-büromonteur">28.2 Seat-Modell (Büro/Monteur)</h3>
<p>28.2.1 Zwei Sitzplatz-Typen, gespiegelt zur Leitplanke „Büro vs. Baustelle als zwei Erlebnisse":
@@ -3514,7 +3514,7 @@
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.</p>
@@ -3525,16 +3525,16 @@
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.</p>
28.3.7 Trial-Konversion läuft über Marketing-Site, von dort zurück in die App mit Legacy-Provider-Session-Token.</p>
<h3 id="284-read-only-downgrade-bei-nichtzahlung">28.4 Read-Only-Downgrade bei Nichtzahlung</h3>
<p>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".</p>
@@ -3542,14 +3542,14 @@
<p>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.</p>
28.5.4 Reaktivierung über Bezahl-Vorgang in Legacy-Provider.</p>
<h3 id="286-rechnungsstellung">28.6 Rechnungsstellung</h3>
<p>28.6.1 Rechnungs-Übersicht im Mandanten-Admin als Stripe-Kunden-Portal eingebettet (von Stripe gehostet).
<p>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.</p>
28.6.3 Rechnungen werden in HiveGrid als Referenz gespiegelt; Original-Dateien lädt der User aus Legacy-Provider.</p>
<h3 id="287-setup-gebühren">28.7 Setup-Gebühren</h3>
<p>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."</p>
<h3 id="288-verbrauchs-erfassung-automationen-ki-n13-09052026">28.8 Verbrauchs-Erfassung (Automationen, KI) [N13, 09.05.2026]</h3>
@@ -3557,13 +3557,13 @@
28.8.2 Pro Plan ein <strong>Inklusiv-Volumen</strong> plus <strong>Aufschlags-Tarif</strong> 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 <strong>Aufschlags-Verbrauch</strong> wird pro Stripe-Rechnungs-Periode als separate Position ausgewiesen (Detail-Aufschlüsselung pro KI-Funktion und Tag).
28.8.5 <strong>Aufschlags-Verbrauch</strong> wird pro Legacy-Provider-Rechnungs-Periode als separate Position ausgewiesen (Detail-Aufschlüsselung pro KI-Funktion und Tag).
28.8.6 <strong>Notbremse</strong>: 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 <strong>Upsell-Vorschlag</strong>: 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: <em>„Inklusiv-Volumen verbraucht, weitere Anfragen kosten ab jetzt [Aufschlags-Tarif] pro 1.000 Tokens. [Plan-Vergleich auf hivegrid.de]"</em>. Web-App: direkter Link zur Vergleichs-Seite. Mobile-App: Hinweis ohne Upgrade-UI (Apple-Compliance, siehe 28.X.10).</p>
<h3 id="28x-phase-2-bewusst-nicht-in-phase-1">28.X Phase 2 / bewusst NICHT in Phase 1</h3>
<p>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.
@@ -3588,7 +3588,7 @@
<p><strong>Was es tut:</strong> Führt einen frisch angemeldeten Mandanten in 5 Minuten von der nackten Anmeldung in einen einsatzbereiten Workspace, mit branchen-spezifischer Standard-Konfiguration, optionalen Beispieldaten und Mitarbeiter-Einladung.</p>
<p><strong>Warum es wichtig ist:</strong> 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.</p>
<h3 id="291-mandanten-anmeldung-tenant-anlage">29.1 Mandanten-Anmeldung (Tenant-Anlage)</h3>
<p>29.1.1 Anmelde-Pfad: Marketing-Site <code>hivegrid.de/signup</code> → in-App-Account-Anlage → Mandanten-Daten → Plan-Auswahl → Stripe-Bezahlvorgang → Onboarding-Wizard.
<p>29.1.1 Anmelde-Pfad: Marketing-Site <code>hivegrid.de/signup</code> → 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.
@@ -3758,7 +3758,7 @@
<p>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.
@@ -3957,7 +3957,7 @@
- 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.</p>