694 lines
64 KiB
Markdown
694 lines
64 KiB
Markdown
# 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.
|
||
|
||
---
|
||
|
||
## Modul 21: Audit-Log
|
||
|
||
**Was es tut:** 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.
|
||
|
||
**Warum es wichtig ist:** Pflicht für DSGVO-Auskünfte, interne Kontrolle, Sicherheits-Forensik und Streitfälle vor Gericht. Ohne Audit-Log kann der Betrieb im Zweifelsfall nicht beweisen, was passiert ist.
|
||
|
||
### 21.1 Was wird protokolliert
|
||
21.1.1 Jede schreibende Aktion in jedem Modul erzeugt einen Audit-Eintrag, Pflicht-Vorschrift, kein Modul ist befreit.
|
||
21.1.2 Erfasste Bereiche umfassen: Anmeldungen und Abmeldungen, Passwort- und 2FA-Änderungen, Einladungen, Rollen- und Rechtevergabe, Anlegen/Ändern/Löschen von Kontakten, Firmen, Leads, Deals, Projekten, Aufgaben, das Versenden von E-Mails und Marketing-Kampagnen, Telefonate, Datei-Uploads, Anlegen und Aktivieren von Automationen, KI-Aktionen, Änderungen an Einstellungen und Integrationen sowie das Anlegen oder Widerrufen von API-Schlüsseln.
|
||
21.1.3 Das Audit-Log loggt sich selbst, Exporte, das Setzen eines Legal Hold (siehe 21.4) und Änderungen an der Aufbewahrungsdauer werden ebenfalls erfasst.
|
||
21.1.4 Bewusst NICHT erfasst: reine Lese-Aktionen (Liste anschauen, Detail öffnen), häufige Bearbeitungen wie Chat-Nachrichten-Edits sowie der Lese-Status von Benachrichtigungen, sonst würde das Log überflutet.
|
||
21.1.5 Sensible Lese-Vorgänge (HR-Daten lesen, DSGVO-Export herunterladen) werden trotzdem erfasst.
|
||
21.1.6 Pro Eintrag werden u.a. erfasst: Datum/Uhrzeit, ausführende Person bzw. System (Mitarbeiter, Automation, KI, API-Schlüssel, Plattform-Admin), betroffenes Objekt, Kurzbeschreibung in Klartext-Deutsch, IP-Adresse und Browser-Kennung bei Mitarbeiter-Aktionen.
|
||
|
||
### 21.2 Diff-Anzeige
|
||
21.2.1 Jeder Eintrag zeigt im Detail Vorher- und Nachher-Stand der geänderten Felder.
|
||
21.2.2 Bei einfachen Werten direkt nebeneinander, bei verschachtelten Daten als strukturierter Vergleich (Hinzufügungen, Löschungen, Änderungen).
|
||
21.2.3 Sensible Felder (Passwörter, Geheimnisse) werden nicht im Klartext angezeigt, nur die Information „Wert wurde geändert".
|
||
21.2.4 Bei einer Massen-Aktion (z.B. 50 Kontakte gleichzeitig getaggt) wird ein Sammel-Eintrag plus die Einzeleinträge gezeigt; auf Klick aufklappbar.
|
||
21.2.5 Wenn das betroffene Objekt inzwischen gelöscht ist, wird der gespeicherte Name als Klartext-Snapshot angezeigt.
|
||
21.2.6 Bei Aktionen aus Automation oder KI: Verlinkung zur ausführenden Automation bzw. zum KI-Prompt.
|
||
|
||
### 21.3 Filter und Suche
|
||
21.3.1 Pflicht-Filter (immer sichtbar): Zeitraum (Default: letzte 30 Tage), Akteur (Mehrfachauswahl: einzelne Mitarbeiter, System, Automation, KI, API-Schlüssel), Aktions-Kategorie gruppiert (Anmeldung, CRM, Projekte, Kommunikation, Einstellungen).
|
||
21.3.2 Erweiterte Filter: Objekt-Typ, IP-Adresse (Sicherheits-Forensik), Akteur-Art, Bulk-Operation-ID, Request-ID (für Support-Korrelation).
|
||
21.3.3 Volltext-Suche über die Klartext-Zusammenfassung jedes Eintrags.
|
||
21.3.4 Mitarbeiter können Filter-Kombinationen als „Gespeicherte Ansicht" speichern (max. 5 pro Person).
|
||
21.3.5 Vorgefertigte Default-Ansichten: „Anmelde-Aktivität letzte 7 Tage", „Rechte-Änderungen letzte 30 Tage", „Endgültige Löschungen letzte 90 Tage", „API-Schlüssel-Aktionen".
|
||
21.3.6 In jedem Detail-Bildschirm (Kontakt, Deal, Projekt) gibt es eine Audit-Schublade, die die Aktionen genau dieses Objekts zeigt, sichtbar für Personen mit Audit-Leserecht.
|
||
|
||
### 21.4 Aufbewahrungsfristen (24 Monate)
|
||
21.4.1 Default-Aufbewahrung: 24 Monate ab Erfassung.
|
||
21.4.2 Der Mandanten-Admin kann die Frist anpassen, minimal 6 Monate, maximal 120 Monate.
|
||
21.4.3 Ein täglicher automatischer Lösch-Job räumt ältere Einträge ab, außer es ist ein „Legal Hold" gesetzt.
|
||
21.4.4 Legal Hold = Pause der automatischen Löschung für den gesamten Mandanten, z.B. bei Rechtsstreit oder Behörden-Anforderung. Setzen erfordert Pflicht-Begründung (mind. 20 Zeichen Freitext) und ist nur dem Mandanten-Admin mit Audit-Admin-Recht erlaubt.
|
||
21.4.5 Bei Reduzierung der Aufbewahrungsfrist erscheint Klartext-Bestätigung: „Wenn du die Frist auf 12 Monate setzt, werden ca. X Audit-Einträge älter als 12 Monate beim nächsten automatischen Lauf entfernt."
|
||
21.4.6 Die Audit-Tabelle ist technisch gegen nachträgliche Änderungen geschützt, auch der Plattform-Anbieter kann Einträge nicht editieren (nur das automatische Lösch-Programm darf gemäß Frist entfernen).
|
||
|
||
### 21.5 Compliance-Export
|
||
21.5.1 Ein Export-Job kann mit identischen Filtern wie die Listen-Ansicht angelegt werden, Format wählbar (CSV, JSON, PDF).
|
||
21.5.2 Pflicht-Eingabe: Zweck-Begründung (Freitext), wird selbst geloggt.
|
||
21.5.3 Vor Submit: Vorschau der zu exportierenden Anzahl Einträge.
|
||
21.5.4 Verarbeitung asynchron, Benachrichtigung bei Fertigstellung.
|
||
21.5.5 Download-Link gültig 7 Tage; danach wird die Export-Datei automatisch gelöscht.
|
||
21.5.6 Jeder Export wird selbst auditiert und ist sichtbar für andere Mandanten-Admins (kein blinder Fleck).
|
||
|
||
### 21.6 Berechtigungen
|
||
21.6.1 Recht „Audit lesen", Audit-Trail einsehen, Detail, Filter, Suche.
|
||
21.6.2 Recht „Audit administrieren", Exporte anlegen, Aufbewahrungsfristen ändern, Legal Hold setzen.
|
||
21.6.3 HR-Audit-Diffs voll sichtbar nur mit zusätzlichem HR-Vollleserecht oder Audit-Admin.
|
||
21.6.4 Mandanten-Daten sind strikt getrennt, keine Cross-Mandanten-Sicht außer für Plattform-Admin (mit eigenem Audit).
|
||
|
||
### 21.7 Phase 2 / bewusst NICHT in Phase 1
|
||
21.7.1 Hash-Kette für nachweisbare Manipulations-Sicherheit (jeder Eintrag verkettet kryptografisch mit dem vorherigen).
|
||
21.7.2 Externes Zeitstempeln über RFC-3161-EU-Provider.
|
||
21.7.3 PDF-Bericht mit digitaler Signatur via PandaDoc.
|
||
21.7.4 KI-basierte Anomalie-Erkennung (verdächtige Login-Zeiten, Massen-Lösch-Aktionen, Rechte-Eskalation).
|
||
21.7.5 Live-Feed (Server-Sent-Events) für Mandanten-Admin-Echtzeit-Monitoring.
|
||
21.7.6 Self-Audit für jeden Mitarbeiter (eigene Aktivitäten der letzten 90 Tage in Kontoeinstellungen).
|
||
|
||
### 21.8 Klartext-Fehlertexte (Beispiele)
|
||
21.8.1 Leerer Trail (frischer Mandant): „Noch keine Aktionen erfasst, Audit-Einträge erscheinen, sobald jemand schreibend tätig wird."
|
||
21.8.2 Filter ohne Treffer: „Keine Einträge passen zu deinen Filtern. [Filter zurücksetzen]"
|
||
21.8.3 Gelöschtes Objekt: „Das betroffene Objekt wurde inzwischen gelöscht. Snapshot-Name: ‚X'."
|
||
21.8.4 Sensibler Diff: „Aus Datenschutz-Gründen wird nur ‚Wert geändert' angezeigt."
|
||
21.8.5 Legal Hold aktiv: „Legal Hold aktiv seit [Datum], keine automatische Löschung. Begründung: [Text]. [Bei Bedarf aufheben]"
|
||
21.8.6 Ohne Audit-Recht: „Du hast keine Berechtigung, das Audit-Log zu sehen. Bitte Mandanten-Admin kontaktieren."
|
||
|
||
---
|
||
|
||
## 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).
|
||
|
||
**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.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.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)
|
||
28.2.1 Zwei Sitzplatz-Typen, gespiegelt zur Leitplanke „Büro vs. Baustelle als zwei Erlebnisse":
|
||
- **Büro-Sitzplatz**: Vollzugang, Default-Modus „Büro", alle Module gemäß Rechten.
|
||
- **Monteur-Sitzplatz**: eingeschränkter Zugang, Default-Modus „Baustelle", reduzierte Modul-Sicht (Projekt-Detail, Aufgaben, Acceptance, Foto-Forms, Chat in eigenen Räumen, eigene HR-Dokumente).
|
||
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.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.
|
||
|
||
### 28.3 Trial-Phase
|
||
28.3.1 Trial-Dauer 5–7 Tage pro Plan konfigurierbar.
|
||
28.3.2 In Phase 1 nur Vertriebs-freigegebene Trials, der Vertrieb (Plattform-Admin) muss den Trial manuell aktivieren, um Spam-Anmeldungen zu verhindern.
|
||
28.3.3 Voller Funktionsumfang während Trial, kein Read-Only.
|
||
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.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.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.
|
||
- 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.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".
|
||
|
||
### 28.5 Frozen-Modus (User-Pause)
|
||
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.6 Rechnungsstellung
|
||
28.6.1 Rechnungs-Übersicht im Mandanten-Admin als Stripe-Kunden-Portal eingebettet (von Stripe 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.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.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."
|
||
|
||
### 28.8 Verbrauchs-Erfassung (Automationen, KI) [N13, 09.05.2026]
|
||
28.8.1 Erfasst werden: Anzahl Automation-Trigger pro Periode, KI-Verbrauch (normalisiert über Provider).
|
||
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.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.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.
|
||
28.X.6 Self-Service-Trial ohne Vertriebs-Freigabe (mit Zahlungsmethoden-Pflicht).
|
||
28.X.7 Reseller-Modell (Agentur kauft Subscription für Endkunden-Mandanten mit eigener Marge).
|
||
28.X.8 KI-basierte Verbrauchs-Vorhersage („bei aktuellem Verbrauch wirst du den Plan in 7 Tagen sprengen").
|
||
28.X.9 Self-Service-Kündigungs-Umfrage mit Auto-Discount-Angebot.
|
||
28.X.10 Apple-Compliance-Sonderregel: keine Pricing-Tabelle, keine Plan-Vergleichs-UI, keine Upgrade-Buttons, keine Add-On-Käufe und keine Werbe-Banner für höhere Pläne in der Mobile-App. Stattdessen Hinweis-Box: „Plan-Wechsel über deinen Account-Manager oder hivegrid.de" mit externem Link in neuem Tab.
|
||
|
||
### 28.Y Klartext-Fehlertexte (Beispiele)
|
||
28.Y.1 Trial freigeschaltet: „Dein HiveGrid-Trial ist freigeschaltet. Bis [Datum] kannst du alles testen."
|
||
28.Y.2 Trial endet bald: „Dein Trial endet in 3 Tagen am [Datum]. Plan wählen unter hivegrid.de"
|
||
28.Y.3 Trial abgelaufen: „Dein Trial ist abgelaufen. Workspace ist Read-Only. Plan wählen unter hivegrid.de"
|
||
28.Y.4 Erste Zahlung gescheitert: „Zahlung gescheitert für Rechnung vom [Datum]. Wir versuchen es in [N] Tagen erneut. [Zahlungsmethode aktualisieren]"
|
||
28.Y.5 Letzte Mahnstufe: „Letzter Zahlungsversuch fehlgeschlagen. Konto wird in 24h gesperrt. [Zahlungsmethode aktualisieren]"
|
||
28.Y.6 Pause aktiv: „Workspace pausiert seit [Datum]. Reaktivieren um wieder zu schreiben."
|
||
28.Y.7 Klick auf Schreib-Button im Read-Only-Modus: „Diese Aktion ist nicht möglich, weil dein Workspace pausiert ist. [Reaktivieren]"
|
||
28.Y.8 Sitzplatz-Limit erreicht: „Plan-Limit von [N] [Typ]-Sitzplätzen erreicht. Plan-Wechsel über hivegrid.de"
|
||
28.Y.9 Trigger-Limit: „Automation-Trigger-Limit erreicht für diese Periode. Eingehende Trigger werden verworfen bis [Periodenstart]."
|
||
28.Y.10 Bezahl-Session abgelaufen: „Die Bezahl-Session ist abgelaufen. Bitte Plan-Wahl wiederholen." + Direkt-Link.
|
||
|
||
---
|
||
|
||
## Modul 29: Onboarding
|
||
|
||
**Was es tut:** 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.
|
||
|
||
**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.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.
|
||
29.1.5 Pro Schritt sofortige Validierung; Pflicht-Felder sind als solche gekennzeichnet.
|
||
29.1.6 Rückwärts-Navigation möglich, außer bei irreversiblen Schritten wie der Beispieldaten-Anlage.
|
||
|
||
### 29.2 Schritte des Wizards
|
||
29.2.1 Willkommens-Begrüßung mit Vorschau der nächsten Schritte und geschätzter Dauer.
|
||
29.2.2 Firmendaten bestätigen, Firmenname, USt-IdNr., Adresse.
|
||
29.2.3 Branche bestätigen (siehe 29.3).
|
||
29.2.4 Größe bestätigen, Auswahl 1–10 / 11–25 / 26–50 / 51–100 / 100+ Mitarbeiter.
|
||
29.2.5 Logo (optional), Upload mit Format-Hinweis (PNG/JPG/SVG, max. 2 MB).
|
||
29.2.6 Smart-Setup-Vorschau, Klartext welche Pipelines, Rollen, Custom-Felder, Form-Templates angelegt werden, mit Toggle pro Template-Gruppe.
|
||
29.2.7 Beispieldaten, Klartext-Frage mit Default „Ja" (siehe 29.4).
|
||
29.2.8 Mitarbeiter einladen, siehe 29.5.
|
||
29.2.9 Erste-Schritte-Liste, Klartext-Erklärung der Checkliste, kein Eingabe-Schritt.
|
||
29.2.10 Fertig, Klartext-Bestätigung, Direkt-Link ins Mandanten-Dashboard, Hinweis auf KI-Walkthrough.
|
||
|
||
### 29.3 Branchen-Wahl (SHK pre-selected)
|
||
29.3.1 SHK ist beim Signup vorausgewählt und zeigt sich als die einzige aktive Branche im Wizard.
|
||
29.3.2 Andere Branchen (Elektro, Maler, Sanitär, Tischlerei, Dachdecker) sind als „Coming soon" sichtbar und deaktiviert.
|
||
29.3.3 Bei Auswahl einer „Coming soon"-Branche im Signup-Formular: Klartext-Hinweis „Diese Branche ist noch in Vorbereitung. Wir richten dir vorerst die SHK-Konfiguration ein, du kannst alles anpassen."
|
||
29.3.4 Anforderung: Branchen-Templates sind deklarativ in einer Verzeichnis-Struktur abgelegt, pro Branche ein Ordner mit YAML-Dateien für Pipelines, Rollen, Form-Templates, Custom-Felder, Beispieldaten, Erste-Schritte-Checkliste. Eine neue Branche aufzunehmen heißt: einen neuen Ordner mit Templates anlegen, kein Code-Patch nötig.
|
||
29.3.5 Templates werden beim System-Start eingelesen; beim Anlegen eines Mandanten mit gewählter Branche wird das passende Template angewandt.
|
||
29.3.6 Alle geseedeten Inhalte sind nach Setup vom Mandanten-Admin frei änderbar, kein „Locked Template".
|
||
|
||
### 29.4 Demo-Daten-Provisioning
|
||
29.4.1 Beispieldaten geben dem User sofort etwas zum Anschauen, keine leere App.
|
||
29.4.2 SHK-Default: ca. 10 Beispiel-Kontakte (Privat/B2B-Mix), 3 Beispiel-Firmen, 5 Beispiel-Deals in unterschiedlichen Stages, 1 aktives Beispiel-Projekt mit Chat-Verlauf, Aufgaben und Foto-Checkliste, 1 Beispiel-Lead in der Inbox, ca. 5 Beispiel-Dateien (PDFs, JPGs), Beispiel-Tags und eine Beispiel-Booking-Page.
|
||
29.4.3 Alle Beispieldaten sind als „Demo" markiert. In allen Listen-Ansichten gibt es einen Filter „Demo-Daten ausblenden".
|
||
29.4.4 Nach 30 Tagen werden die Demo-Daten NICHT automatisch gelöscht, sie bleiben als reguläre Daten und können vom User manuell entfernt werden.
|
||
29.4.5 Im Mandanten-Admin gibt es eine Bulk-Lösch-Funktion „Alle Demo-Daten löschen" mit Multi-Step-Bestätigung.
|
||
29.4.6 Klartext im Wizard: „Wir legen Beispiel-Kontakte und ein Beispiel-Projekt an, damit du sofort siehst wie HiveGrid funktioniert. Du kannst sie jederzeit löschen."
|
||
|
||
### 29.5 Rolle Admin → erste Nutzer einladen
|
||
29.5.1 Wizard-Schritt 8 nutzt das normale Mitarbeiter-Einladungs-System: E-Mail + Rolle pro Zeile, beliebig viele Zeilen, optional persönliche Nachricht.
|
||
29.5.2 Eingeladene Mitarbeiter erhalten eine E-Mail mit Magic-Link und können sofort starten.
|
||
29.5.3 Rollen-Vorauswahl: erste Zeile Default „Vertriebler" (häufigster Fall), per Dropdown änderbar.
|
||
29.5.4 E-Mail-Format wird live geprüft, Duplikate innerhalb des Formulars werden abgefangen.
|
||
29.5.5 „Später einladen"-Skip-Button überspringt den Schritt komplett.
|
||
29.5.6 Klartext: „Eingeladene Mitarbeiter erhalten eine E-Mail mit Magic-Link. Sie können sofort anfangen, du musst nicht warten." und „Die Rolle bestimmt, was deine Mitarbeiter in HiveGrid dürfen. Du kannst sie jederzeit ändern."
|
||
29.5.7 Bulk-CSV-Import von Mitarbeitern ist Phase 2.
|
||
|
||
### 29.6 Erste-Schritte-Checkliste
|
||
29.6.1 Nach Wizard-Abschluss erscheint im Mandanten-Dashboard eine Status-getrackte Checkliste.
|
||
29.6.2 Default-Items für SHK Phase 1: KWP-Verbindung einrichten, E-Mail-Postfach verbinden, AirCall verbinden, Booking-Page anlegen, Mitarbeiter einladen, erste Automation testen, erstes Form anlegen, erste Sales-Pipeline-Bewegung.
|
||
29.6.3 Pro Item: Klartext-Titel, Beschreibung, Direkt-Link in den Modul-Bereich.
|
||
29.6.4 Status wird automatisch erkannt aus dem Tenant-Stand (z.B. mindestens eine aktive Automation = erledigt).
|
||
29.6.5 Mitarbeiter können Items manuell als „erledigt" markieren oder die Liste dauerhaft ausblenden.
|
||
29.6.6 Nach 100% Erledigung automatisches Ausblenden mit Glückwunsch-Klartext: „Alle Erste-Schritte erledigt, viel Erfolg mit HiveGrid!"
|
||
|
||
### 29.7 KI-Walkthrough
|
||
29.7.1 Nach Wizard-Abschluss optional ein KI-geführter Rundgang.
|
||
29.7.2 Auf User-Klick: KI fragt „Was willst du heute zuerst machen, einen Lead bearbeiten, ein Projekt erstellen oder Mitarbeiter einrichten?" und navigiert in den entsprechenden Modul-Bereich mit Kontext-Hinweisen.
|
||
29.7.3 KI hat Zugriff auf Mandanten-Stand, Erste-Schritte-Checkliste und Hilfe-Center-Artikel, keine schreibenden Aktionen ohne explizite User-Bestätigung.
|
||
29.7.4 Permanent abschaltbar in den User-Einstellungen.
|
||
|
||
### 29.X Phase 2 / bewusst NICHT in Phase 1
|
||
29.X.1 Branchen-Templates für Elektro, Maler, Sanitär, Tischlerei, Dachdecker (deklarativ, gleiche Verzeichnis-Struktur).
|
||
29.X.2 Migrations-Tools für HubSpot, Quiply und KWP-Bestandsdaten.
|
||
29.X.3 CSV-Bulk-Import für Bestandsdaten als optionaler Wizard-Schritt.
|
||
29.X.4 KI-gestützter Onboarding-Coach, der aus dem Mandanten-Verhalten lernt.
|
||
29.X.5 Re-Onboarding für bestehende Mandanten bei neuen Templates.
|
||
29.X.6 Multi-Branchen-Mandant (SHK plus Elektro gleichzeitig).
|
||
29.X.7 Onboarding-Analytics für Plattform-Admin (Skip-Quote, Abbruch-Punkte, durchschnittliche Dauer).
|
||
29.X.8 Custom-Onboarding pro Mandant für die internen Mitarbeiter-Schulungen.
|
||
|
||
### 29.Y Klartext-Fehlertexte (Beispiele)
|
||
29.Y.1 Welcome: „Willkommen bei HiveGrid! Wir helfen dir, dein Workspace in 5 Minuten einsatzbereit zu machen."
|
||
29.Y.2 Smart-Setup-Fehler: „Wir konnten die Pipeline nicht anlegen. Wir versuchen es nochmal, falls es wieder fehlschlägt, kontaktiere bitte den Support." + Retry-Button.
|
||
29.Y.3 Logo zu groß: „Das Logo ist zu groß (max. 2 MB). Bitte kleineres Bild wählen."
|
||
29.Y.4 Logo-Format ungültig: „Logo muss PNG, JPG oder SVG sein."
|
||
29.Y.5 Ungültige Mitarbeiter-E-Mail: Inline-Hinweis pro Zeile „Diese Email ist nicht gültig."
|
||
29.Y.6 Mitarbeiter ist bereits Mitglied: „[Email] ist bereits Mitglied, Rolle: [Rolle]"
|
||
29.Y.7 Branchen-Template nicht ladbar (Edge-Case): „Konnte SHK-Template nicht laden. Plattform-Admin wurde benachrichtigt." + Auto-Alert.
|
||
|
||
---
|
||
|
||
## Modul 34: Public API & Webhooks
|
||
|
||
**Was es tut:** Stellt Drittanbietern eine begrenzte Schnittstelle zur Verfügung, um HiveGrid-Daten zu lesen und um Webhooks zu empfangen, wenn etwas im Mandanten passiert. Außerdem ein Eingangs-Tor für Lead-Push aus externen Form-Anbietern.
|
||
|
||
**Warum es wichtig ist:** Webseiten, externe Form-Anbieter und ERPs müssen Leads in HiveGrid einkippen können. Andere Tools wollen sich abonnieren, wenn z.B. ein Deal gewonnen wurde. Wir bauen Phase 1 bewusst klein, Lese-Zugriff plus Webhooks reichen erstmal.
|
||
|
||
### 34.1 Read-API für Drittanbieter
|
||
34.1.1 Zugriff per API-Schlüssel (Verwaltung im Mandanten-Admin); Header `Authorization: Bearer hg_<Schlüssel>`.
|
||
34.1.2 Bereitgestellte Lese-Endpunkte für: Kontakte, Firmen, Deals, Projekte, Aufgaben, Leads, jeweils Liste und Detail.
|
||
34.1.3 Standard-Funktionen: Cursor-Pagination (Default 50, max. 200 pro Seite), Filterung per Query-Parameter (auch Datums-Bereiche und Custom-Felder), Sortierung, sparse fieldsets (nur bestimmte Felder zurückgeben), eingebettete Beziehungen (z.B. Deal mit Pipeline und Stage als Sub-Objekte; Tiefe maximal 1 in Phase 1).
|
||
34.1.4 Berechtigungs-Modell („Scopes"): „Read-Only" gibt Zugriff auf nicht-sensible Felder; „Read-Full" inkl. Notizen, sensiblen Custom-Feldern, Activities; „Webhook-Inbound" nur für Eingangs-Webhooks; „Automation-Trigger" für externe Event-Pushes an die Automation-Engine.
|
||
34.1.5 Phase 1: ein Schlüssel = ein Scope. Mehrfach-Scope-Schlüssel und granulare Modul-Scopes erst Phase 2.
|
||
34.1.6 Sensible Felder werden bei „Read-Only" automatisch aus Antwort entfernt, nicht 403, sondern Feld wird einfach weggelassen (im OpenAPI-Schema dokumentiert).
|
||
34.1.7 Antwort-Format einheitlich: `{ data, meta }` bei Erfolg, `{ error: { code, message, details } }` bei Fehler, Klartext-Fehlertexte in Deutsch.
|
||
34.1.8 OpenAPI-Spezifikation auto-generiert (`/api/v1/openapi.json`), Swagger-UI öffentlich verfügbar mit „Try it out"-Funktion.
|
||
34.1.9 Versionierung über URL (`/api/v1/...`); Major-Bump nur bei Breaking Changes; Deprecation-Phase und Sunset-Header bei Alt-Endpunkten.
|
||
34.1.10 Statt Tenant fünf-vor-zwölf-Frozen wird auf API-Schreiboperationen mit 402 (Bezahl-Pflicht) geantwortet, Lesen bleibt erlaubt.
|
||
|
||
### 34.2 Webhooks (signiert)
|
||
34.2.1 Eingehende Webhooks (Lead-Push aus Web-Formularen):
|
||
- Pro Mandant beliebig viele „Slugs" konfigurierbar (z.B. `website-kontaktformular`).
|
||
- Authentifizierung wahlweise: API-Schlüssel im Header, HMAC-Signatur über Body, oder Token in der URL (mit Klartext-Warnung, dass das weniger sicher ist).
|
||
- Eingangs-Webhook erzeugt einen Lead (oder direkt Kontakt, je nach Slug-Konfiguration), wendet Default-Tags und Default-Zuordnung an, prüft auf Duplikate (gleiche E-Mail).
|
||
- Verarbeitungs-Logs sichtbar im Mandanten-Admin: letzte 100 Eingangs-Events mit Status, Fehler-Klartext und Replay-Button (Replay Phase 2).
|
||
34.2.2 Ausgehende Webhooks (Subscription-Modell):
|
||
- Mandant abonniert beliebige Event-Typen wie `contact.created`, `deal.stage_changed`, `project.completed`, `lead.qualified`.
|
||
- Pro Subscription: eindeutige Ziel-URL, system-generiertes HMAC-Geheimnis (einmalig sichtbar bei Anlage), optionaler Filter pro Event.
|
||
- Auslieferung mit HMAC-SHA256-Signatur im Header `X-HiveGrid-Signature`, Event-ID-Header für Idempotenz beim Empfänger.
|
||
- Retry mit exponentiellem Backoff (1min, 5min, 30min, 2h, 12h), max. 5 Versuche bei 5xx/Timeout. 4xx wird nicht wiederholt.
|
||
- Nach 10 aufeinanderfolgenden Fehl-Auslieferungen wird die Subscription automatisch deaktiviert mit Klartext-Hinweis.
|
||
- Test-Funktion „Test-Event senden" im Subscription-Detail.
|
||
- Statistik-Sicht: letzte 100 Auslieferungen, Aggregat „letzte 7 Tage X von Y erfolgreich".
|
||
34.2.3 Allgemeine Event-Ingestion (`POST /api/v1/integrations/events`) für externe Systeme, die Custom-Events in die Automation-Engine pushen wollen, Phase 1 nur als Trigger, keine direkte Datenmanipulation.
|
||
|
||
### 34.3 Rate-Limiting und Logs
|
||
34.3.1 Standard-Limit pro API-Schlüssel: 1.000 Anfragen/Stunde, kurzfristig 50/Sekunde tolerabel.
|
||
34.3.2 Pro Mandant aggregiert: 10.000 Anfragen/Stunde.
|
||
34.3.3 Eingangs-Webhooks pro Slug: 100/Minute.
|
||
34.3.4 Mandanten-Admin kann Limit pro Schlüssel auf max. 10.000/h erhöhen ohne Plattform-Admin-Approval.
|
||
34.3.5 Antwort-Header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` bei jeder Antwort. Bei Überschreitung 429 mit Klartext und `Retry-After`-Header.
|
||
34.3.6 API-Request-Logs im Mandanten-Admin sichtbar: 90 Tage erfolgreiche, 180 Tage Fehler-Requests.
|
||
|
||
### 34.4 Anti-Liste: kein Schreib-API in Phase 1
|
||
34.4.1 Kein POST/PUT/PATCH/DELETE auf Hauptentitäten in Phase 1, nur Lese-Endpunkte und Webhooks.
|
||
34.4.2 Kein GraphQL.
|
||
34.4.3 Kein OAuth2-Provider-Modus für Drittanbieter-Apps (3-Legged-OAuth).
|
||
34.4.4 Keine granularen Modul-spezifischen Scopes.
|
||
34.4.5 Keine Bulk-Export-Endpunkte über die API (Vollexport läuft über Modul 35 DSGVO-Export).
|
||
34.4.6 Kein API-Schlüssel-Rotation-Workflow mit Übergangs-Fenster.
|
||
34.4.7 Keine Plattform-Admin-API.
|
||
|
||
### 34.X Phase 2 / spätere Features
|
||
34.X.1 Voll-CRUD-API für alle Hauptentitäten.
|
||
34.X.2 GraphQL-Endpunkt als zweite Schnittstelle.
|
||
34.X.3 OAuth2-Provider-Modus für Drittanbieter-Apps.
|
||
34.X.4 Granulare Scopes pro Modul-Aktion.
|
||
34.X.5 Webhook-Replay-Tool im UI.
|
||
34.X.6 Bulk-Export-Endpunkt über die API.
|
||
34.X.7 Komplexe Filter über JSON-Query-Tree.
|
||
34.X.8 Rate-Limit-Tier-Erhöhung über Plan (Cloud+ = 5.000/h).
|
||
34.X.9 API-Schlüssel-Rotations-Workflow.
|
||
|
||
### 34.Y Klartext-Fehlertexte (Beispiele)
|
||
34.Y.1 Header fehlt (401): „API-Key fehlt. Setze Header: `Authorization: Bearer hg_<dein_key>`"
|
||
34.Y.2 Schlüssel ungültig (401): „API-Key ist ungültig oder widerrufen."
|
||
34.Y.3 Falscher Scope (403): „Dieser API-Key hat Scope `[X]`, benötigt wird `[Y]`. Tenant-Admin kann Scope ändern."
|
||
34.Y.4 Eingehender Webhook ungültiges Payload: „Pflichtfeld `email` fehlt im Payload. Erwartetes Schema: [Link zur Mapping-Doku]"
|
||
34.Y.5 Webhook deaktiviert: „Webhook ‚[Name]' ist nach 10 fehlgeschlagenen Auslieferungen deaktiviert. Letzter Fehler: HTTP 502 vom Endpoint. [Reaktivieren]"
|
||
34.Y.6 Rate-Limit: „Rate-Limit erreicht: 1.000 Anfragen/Stunde. Reset um [timestamp]. Tenant-Admin kann Limit erhöhen."
|
||
34.Y.7 Validierung: „Filter `created_at_gte` muss ISO-8601 sein, z.B. `2026-01-01`. Erhalten: `[Wert]`."
|
||
|
||
---
|
||
|
||
## Modul 35: DSGVO-Export / Account-Löschung
|
||
|
||
**Was es tut:** Erfüllt zwei rechtliche Pflichten gleichzeitig: das DSGVO-Auskunfts- und Datenportabilitäts-Recht (Daten-Export) und die Apple-Pflicht aus 2022, dass jede iOS-App eine Account-Löschung anbieten muss. Außerdem den Mandanten-Lösch-Workflow nach Kündigung, AVV-Vertrag im Onboarding und die Subprozessoren-Liste.
|
||
|
||
**Warum es wichtig ist:** Pflicht durch Apple und durch DSGVO. Ohne dieses Modul kann die App nicht in den App-Store, und Behörden-Auskünfte sind nicht erfüllbar. Außerdem: glaubwürdige Datenportabilität ist Marketing-Argument gegen den Vendor-Lock-in vieler CRMs.
|
||
|
||
### 35.1 Export aller Daten eines Kontakts/Mitarbeiters
|
||
35.1.1 Jeder Mitarbeiter darf jederzeit alle Daten, die mit seiner Person verknüpft sind, in maschinenlesbarem Format anfordern (DSGVO Art. 15 + Art. 20).
|
||
35.1.2 Inhalt des User-Daten-Exports:
|
||
- Stammdaten: E-Mail, Name, Sprache, 2FA-Status, OAuth-Verknüpfungen, Benachrichtigungs-Einstellungen, aktive Sitzungen (gekürzt: nur Geräte-Liste, keine Tokens).
|
||
- Mandanten-Mitgliedschaft: Rollen, Gruppen, Beitritts-Datum, Rechte-Snapshot.
|
||
- Eigene Inhalte: Aktivitäten, Notizen, Chat-Nachrichten, Aufgaben, Termine, hochgeladene Dateien (Metadaten + Originale), Form-Submissions, eigene HR-Daten (eigene Krankmeldungen, Urlaubsanträge, Lohnzettel, NICHT die der Kollegen).
|
||
- Kommunikation: gesendete und empfangene E-Mails inkl. Anhänge.
|
||
- Eigene KI-Konversations-Historie und Audit-Spuren als Akteur.
|
||
35.1.3 Format: ZIP-Archiv mit klar strukturierten Unterordnern (Profil, Mitgliedschaften, Aktivitäten, Chat, Notizen, Aufgaben, Termine, Dateien, E-Mails, HR, KI-Konversationen, Audit). README im ZIP erklärt Klartext, was drin ist.
|
||
35.1.4 Export-Job läuft asynchron, bei großem Datenbestand in Häppchen mit Progress-Update.
|
||
35.1.5 Download-Link gültig 7 Tage; danach automatische Löschung der ZIP-Datei. Magic-Link gegen Auth-Bypass.
|
||
35.1.6 Maximal 3 aktive User-Daten-Export-Jobs pro Person pro 24 Stunden (Schutz vor Missbrauch).
|
||
|
||
35.1.7 Mandanten-Admin-Daten-Export (komplettes Mandanten-Volumen):
|
||
- Inhalt: alle Mandanten-Daten als JSON-Files plus alle Original-Dateien (CRM, Pipelines, Projekte, Aufgaben, Forms, Bookings, E-Mails, Chats, Telefonate, HR-Hub, Customer-Portal, Automationen, KI-Konversationen, KWP-Sync-Daten, Audit-Trail, Mitarbeiter-Liste, Rollen, Tags).
|
||
- Anwendungsfall: DSGVO-Auskunft für die Firma als Verantwortlicher und Vendor-Lock-in-Vermeidung beim Wechsel weg von HiveGrid.
|
||
- ZIP kann mehrere Gigabyte groß sein, bei sehr großen Mandanten Multi-Part-ZIP.
|
||
- Vor Submit: Klartext-Hinweis mit geschätzter Größe und Dauer.
|
||
- Maximal 1 aktiver Mandanten-Export pro Mandant.
|
||
- Mandant in „pausiert" oder „Zahlung überfällig": Export bleibt erlaubt, Lese-Recht hat Vorrang.
|
||
- Mandant in 30-Tage-Lösch-Vorlauf: Export erlaubt mit Klartext-Hinweis „Letzte Möglichkeit, Daten zu sichern bevor Tenant gelöscht wird."
|
||
|
||
### 35.2 Account-Löschung (Apple-Pflicht)
|
||
35.2.1 Apple-Pflicht seit 2022, jede iOS-App MUSS eine Account-Löschung in der App selbst anbieten. Pflicht durch Apple und durch DSGVO.
|
||
35.2.2 Sichtbarer Pfad: in den Konto-Einstellungen auf gleicher Ebene wie das Profil (Reviewer prüft Sichtbarkeit aktiv).
|
||
35.2.3 Multi-Step-Bestätigung gegen Versehen:
|
||
- Schritt 1: Klartext-Erklärung was passiert (Daten weg, Mandanten-Mitgliedschaften beendet, Login-Möglichkeit weg).
|
||
- Schritt 1.5: Angebot, vorher die eigenen Daten zu exportieren (siehe 35.1).
|
||
- Schritt 2: Identitäts-Bestätigung (Passwort + 2FA falls aktiv).
|
||
- Schritt 3: Final-Klick mit Tipp-Eingabe einer Confirm-Phrase.
|
||
35.2.4 Was technisch passiert: Mandanten-Mitgliedschaften werden gelöscht, persönliche Daten mit Platzhalter überschrieben, Audit-Spuren behalten die User-ID (für Nachvollziehbarkeit), 2FA-Geheimnisse, aktive Sitzungen, Push-Tokens, OAuth-Konten und Avatar werden entfernt.
|
||
35.2.5 24-Stunden-Reverse-Window: nach Klick erhält der User eine Bestätigungs-E-Mail an die Lösch-Adresse, kann innerhalb 24h zurückziehen. Erst danach unwiderruflich.
|
||
35.2.6 In der Mobile-App werden zusätzlich alle lokalen Daten gelöscht (lokaler Cache, Biometrie-Token, Push-Token revoke).
|
||
|
||
### 35.3 Aufbewahrungsfrist nach Löschung (Mandanten-Lösch-Workflow)
|
||
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 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.
|
||
35.3.3 Banner im Workspace während Grace-Period: „Konto wird in X Tagen gelöscht, [Kündigung zurückziehen]"
|
||
35.3.4 Hard-Delete-Cron läuft täglich nach Ablauf der Grace-Period:
|
||
- Reihenfolge: Dateien im Storage rekursiv löschen → Embeddings → Worker-Queues für diesen Mandanten verwerfen → Webhook-Subscriptions deaktivieren → DB-Daten in FK-konformer Reihenfolge → Cache-Keys purgen.
|
||
- Nach Hard-Delete bleibt nur Metadaten im Plattform-Audit-Log (Lösch-Datum, Akteur, Grund), keine PII, keine User-Inhalte mehr.
|
||
- Bestätigungs-E-Mail an den AVV-Unterzeichner: „Tenant ‚X' wurde am [Datum] vollständig gelöscht. DSGVO-Auftrag erfüllt."
|
||
35.3.5 Andere Lösch-Gründe außer freiwillig:
|
||
- Nichtzahlung, automatisch nach 30 Tagen „Zahlung überfällig" (siehe Modul 28.4).
|
||
- AGB-Verstoß, Plattform-Admin kündigt manuell, ggf. verkürzte Grace-Period.
|
||
- Admin-initiiert auf Anfrage des Mandanten-Admin per E-Mail mit Bestätigungs-Link.
|
||
|
||
### 35.4 AVV-Vertrag und Subprozessoren-Liste
|
||
35.4.1 Beim Signup ist die AVV-Akzeptanz Pflicht-Checkbox. Beim Klick: dynamisch generiertes PDF mit Mandanten-spezifischen Daten (Firma, Anschrift, GF-Name, Datum, aktuelle Subprozessoren-Liste, Versionsnummer).
|
||
35.4.2 Bei jedem AVV-Update wird Re-Akzeptanz beim nächsten Login verlangt (Modal mit Klartext-Änderungen). Nach 14 Tagen ohne Re-Akzeptanz: Read-Only-Modus.
|
||
35.4.3 Mandanten-Admin sieht in den Datenschutz-Einstellungen alle akzeptierten AVV-Versionen mit Datum und Unterzeichner; PDF-Download jederzeit möglich.
|
||
35.4.4 Subprozessoren-Liste:
|
||
- Sichtbar im Datenschutz-Bereich des Mandanten-Admins.
|
||
- Pro Eintrag: Name, Land, EU/EEA-Indikator, Zweck-Klartext, Datenkategorien, Link zum AVV-Template, „Aktiv seit"-Datum.
|
||
- Bei neuem Subprozessor: E-Mail an alle Mandanten-Admins, 14-Tage-Widerspruchs-Frist (gesetzliche AVV-Pflicht).
|
||
- Phase 1 EU-Stack: Liste enthält ausschließlich EU/EEA-Anbieter (Scaleway etc.), keine Drittland-Transfers.
|
||
35.4.5 Privacy-Manifest für die Mobile-App (Apple-Pflicht seit 2024) wird aus einer zentralen Master-Liste beim Build generiert; öffentliche Privacy-Manifest-Seite verfügbar.
|
||
|
||
### 35.5 Berechtigungen
|
||
35.5.1 Eigener User-Daten-Export: jeder eingeloggte Mitarbeiter implizit.
|
||
35.5.2 Mandanten-Daten-Export: Mandanten-Admin oder spezielles Recht.
|
||
35.5.3 Mandanten-Lösch-Workflow: Mandanten-Admin.
|
||
35.5.4 Subprozessoren-Liste lesen: jeder Mandanten-Admin.
|
||
35.5.5 AVV (re-)akzeptieren: jeder Mandanten-Admin.
|
||
35.5.6 Phase 1: Mandanten-Admin kann NICHT für andere Mitarbeiter Daten exportieren, jeder nur für sich. Vertretungsfall ist Phase 2.
|
||
|
||
### 35.X Phase 2 / spätere Features
|
||
35.X.1 Pseudonymisierungs-Toggle pro Modul (z.B. E-Mail-Adressen im Export gehasht).
|
||
35.X.2 Drittland-Audit-Log mit Begründung pro Datentransfer.
|
||
35.X.3 DSFA-Generator (Datenschutz-Folgeabschätzung) als automatisch generiertes PDF pro Mandant.
|
||
35.X.4 Scope-gefilterter Export (nur CRM, nur HR, etc.) statt immer Vollexport.
|
||
35.X.5 Inkrementelle Exports „nur seit letztem Export".
|
||
35.X.6 Auto-Delete-Schedules pro Entity-Typ (z.B. „Lost-Leads automatisch nach 90 Tagen löschen").
|
||
35.X.7 User-Daten-Export für andere Mitarbeiter durch Mandanten-Admin (Vertretungsfall).
|
||
35.X.8 Verschlüsselter Export mit User-Passwort (AES).
|
||
35.X.9 Export-API für regelmäßige automatische Backups durch den Mandanten.
|
||
35.X.10 Konsolidierte Privacy-Center-Page mit allen DSGVO-Aspekten in einer Übersicht.
|
||
|
||
### 35.Y Klartext-Fehlertexte (Beispiele)
|
||
35.Y.1 Export dauert lange: „Dein Export dauert länger als erwartet. Wir versuchen es weiter, du bekommst eine Email sobald fertig."
|
||
35.Y.2 Export abgelaufen: „Dieser Export ist abgelaufen und wurde gelöscht. [Neuen Export starten]"
|
||
35.Y.3 Concurrent-Limit: „Du hast bereits 3 aktive Export-Anforderungen in den letzten 24 Stunden. Bitte warte bis einer fertig ist."
|
||
35.Y.4 Trial-Kündigung: „Dein Tenant ist im Trial, Kündigung beendet sofort den Zugang ohne Grace-Period. [Trotzdem fortfahren]"
|
||
35.Y.5 AVV-Re-Akzeptanz blockiert: „Bitte unsere aktualisierte AVV akzeptieren, um den Workspace weiter zu nutzen."
|
||
35.Y.6 Subprozessor-Widerspruch verstrichen: „Du hast nicht widersprochen. Der neue Subprozessor wird ab [Datum] wirksam."
|
||
|
||
---
|
||
|
||
## Modul 36: Mobile-App (Capacitor)
|
||
|
||
**Was es tut:** Eine native iOS- und Android-App, die in Wirklichkeit die mobile-first Web-App in einen App-Store-tauglichen Container verpackt, App auf Web-Basis, ins iOS-/Android-Format verpackt. Drei Pflicht-Native-Features (Push-Benachrichtigungen, Face-ID/Touch-ID-Anmeldung, Kamera) plus ein vollwertiger Offline-Modus für die Baustelle.
|
||
|
||
**Warum es wichtig ist:** Monteure draußen ohne Empfang müssen weiterarbeiten können, Acceptance-Protokolle, Foto-Checklisten, Aufgaben-Statusen. Apple stellt strikte Compliance-Anforderungen, die ohne Mobile-App-Strategie zu Reject-Risiko führen. Account-Löschung in der App ist Apple-Pflicht.
|
||
|
||
### 36.1 Capacitor-Wrapper iOS+Android
|
||
36.1.1 Eine einzige Code-Basis: die mobile-first responsive Web-App ist die Quelle der Wahrheit. Capacitor packt diese Web-App in ein natives Hülle für iOS und Android.
|
||
36.1.2 Native Plugins werden über eine zentrale Schnittstelle aufgerufen, im Browser geben sie nichts zurück, im Capacitor-Container den echten nativen Aufruf.
|
||
36.1.3 CI/CD: Tag `mobile-vX.Y.Z` triggert separate Pipelines für Web-Build, iOS-Build (TestFlight-Upload) und Android-Build (Google-Play-Upload).
|
||
36.1.4 Versionierung getrennt: Wrapper-Version (im App-Store sichtbar, semantic versioning) und Web-Bundle-Version. Eine vom Server gepflegte Mindest-Wrapper-Version erzwingt bei zu alten Apps einen Force-Update-Screen.
|
||
36.1.5 Lokale Dev-Umgebung mit Capacitor-CLI Live-Reload, Push-Test-Tools, Biometrie-Simulation.
|
||
|
||
### 36.2 Native Features (Pflicht für Apple-Compliance)
|
||
36.2.1 Push-Benachrichtigungen:
|
||
- Bei erstem Login auf Gerät: Pre-Prompt-Erklärung „HiveGrid sendet dir Benachrichtigungen, wenn dir eine Aufgabe zugewiesen wird oder wichtige Updates passieren, möchtest du das aktivieren?" mit Funktionen „Ja, aktivieren" und „Später" VOR dem System-Dialog.
|
||
- Bei Zustimmung: Push-Token holen und im Mandanten registrieren.
|
||
- App im Vordergrund: visualisiert in der App. App im Hintergrund: System-Notification-Center.
|
||
- Klick auf Push öffnet die App auf der entsprechenden Tiefenroute.
|
||
36.2.2 Face-ID / Touch-ID-Anmeldung:
|
||
- Setup in den Sicherheits-Einstellungen: Toggle aktivieren → Passwort eingeben → wird im sicheren Apple-/Android-Speicher hinterlegt.
|
||
- Beim nächsten Login: „Mit Face-ID anmelden"-Funktion. Bei 3 Fehl-Versuchen: Fallback auf Passwort.
|
||
- 2FA bleibt trotzdem aktiv, Biometrie ersetzt nur das Passwort, nicht den 2. Faktor.
|
||
- Auth-Geheimnis bleibt nur lokal im OS-Keychain, nicht auf dem Server.
|
||
36.2.3 Kamera:
|
||
- Pre-Prompt-Erklärung „HiveGrid braucht Zugriff auf deine Kamera, um Fotos für Acceptance-Protokolle und Checklisten aufzunehmen, möchtest du das erlauben?"
|
||
- Foto-Capture-Optionen: direkt aufnehmen oder aus Galerie auswählen.
|
||
- Lokales Foto-Resize (max. 2400×2400, JPEG-Qualität 85) vor Upload zur Bandbreiten-Schonung.
|
||
- Online: direkter Upload. Offline: Foto in lokalem Speicher mit Upload-Auftrag (siehe 36.3).
|
||
36.2.4 Phase 1 keine: Geolocation, Bluetooth, NFC, Mikrofon, alle Phase 2.
|
||
|
||
### 36.3 Offline-Modus (Phase-1-Pflicht für Baustelle)
|
||
36.3.1 Architektur: Offline-Speicher auf dem Gerät plus Synchronisation bei Wiederverbindung. Service-Worker für statische App-Inhalte, lokaler Datenspeicher für eigene Daten und für Fotos.
|
||
36.3.2 Beim Login wird automatisch vorgeladen:
|
||
- Heutige zugewiesene Projekte des Users.
|
||
- Heute fällige und offene Aufgaben.
|
||
- Stammdaten (Kontakte verknüpft mit aktiven Projekten, eigenes Profil, Berechtigungen).
|
||
- Acceptance-Protokoll-Templates und Foto-Checklisten für aktive Projekte.
|
||
- Klartext beim Pre-Cache: „Lade Daten für offline-Nutzung, bitte einen Moment Geduld..." mit Fortschritts-Anzeige.
|
||
36.3.3 Was funktioniert offline:
|
||
- Anzeige der vorgeladenen Daten und Navigation in allen vorgeladenen Bereichen.
|
||
- Anzeige eigener offline-erzeugter Einträge.
|
||
36.3.4 Was NICHT offline funktioniert:
|
||
- Suche über nicht-gecachte Daten (z.B. CRM-Vollsuche).
|
||
- Server-side gerenderte Reports und KI-Antworten.
|
||
- E-Mail-Inbox (Phase 2 erweitert).
|
||
- Chat-Echtzeit-Updates (Lesen vorhandener Threads ja; Senden geht in die Warteschlange).
|
||
36.3.5 Was kann offline geschrieben werden (landet in einer lokalen Warteschlange und wird später synchronisiert):
|
||
- Fotos hochladen zu Acceptance, Projekt-Dateien, Aufgaben.
|
||
- Notizen, Aufgaben-Status (Offen → In Bearbeitung → Erledigt), Checklist-Items abhaken, Acceptance-Protokoll erstellen und abschließen, manuelle Activity-Einträge, Termin-Status setzen, Datei-Anhänge, Chat-Nachricht in Projekt-Channel.
|
||
36.3.6 Bewusst NICHT offline:
|
||
- Anlegen neuer Kontakte/Firmen (zu hohes Konflikt-Risiko bei CRM-Stammdaten).
|
||
- Lead-Bearbeitung (Vertriebs-Use-Case ist online-zentriert).
|
||
- Berechtigungs- und User-Aktionen (sicherheitsrelevant).
|
||
36.3.7 Sichtbarer Sync-Status: Anzahl wartender Änderungen, Klick öffnet Warteschlange-Übersicht mit Status pro Eintrag und manuellem Retry.
|
||
36.3.8 Synchronisation bei Wiederverbindung:
|
||
- Wird ausgelöst durch Netzwerk-Status-Wechsel, App-Vordergrund-Resume, manuellen Sync, periodisch alle 60s wenn online und Warteschlange nicht leer, beim Login.
|
||
- Reihenfolge: Lese-Cache aktualisieren → Schreib-Warteschlange in Eingangs-Reihenfolge abarbeiten → Lese-Cache erneut aktualisieren.
|
||
- Pro Eintrag mit Idempotenz-Schlüssel, Doppel-Sync wird sauber abgefangen.
|
||
36.3.9 Konflikt-Strategien:
|
||
- Append-Daten (Fotos, Notizen, neue Activities, neue Chat-Messages, Acceptance-Erstellung): keine Konflikte möglich.
|
||
- Status-/Felder-Updates (Aufgaben-Status, Checklist-Items, Acceptance-Abschluss): Letzter-Schreibt-Gewinnt mit User-Sichtbarkeit. Bei Konflikt erscheint Klartext-Hinweis: „Es gab einen Konflikt, deine Änderung wurde übernommen, der vorherige Stand war: [Klartext]. [OK] [Vorherigen Stand wiederherstellen]"
|
||
- Audit dokumentiert beide Stände.
|
||
36.3.10 Storage-Limits: lokale Warteschlange max. 1.000 Einträge, lokaler Foto-Speicher max. 500 MB. Bei Überschreitung Klartext-Hinweis und Block weiterer Aktionen bis Sync.
|
||
|
||
### 36.4 Apple-Compliance ohne Pricing-UI
|
||
36.4.1 Strikte Verbote in der App: keine Pricing-Page, keine Upgrade-Buttons, keine Links auf hivegrid.de/pricing oder Billing-Seiten, keine Werbe-Banner für höhere Pläne.
|
||
36.4.2 Statt-dessen bei Feature-Gate-Block: Klartext „Diese Funktion ist im Cloud+-Plan verfügbar. Bitte deinen Workspace-Admin kontaktieren oder hivegrid.de besuchen.", ohne Klick-Link.
|
||
36.4.3 Subscription-Status anzeigen ist erlaubt (Read-Only-Information): Status-Badge, Trial-Verbleibend-Text, ohne CTA-Button.
|
||
36.4.4 Technisch: in der Mobile-App ist ein Bau-Flag aktiv, der die gesamte Pricing-/Upgrade-UI ausblendet.
|
||
36.4.5 Sign-in-with-Apple-Umgehung: Login als „Enterprise SSO" positioniert. Phase 1 nur E-Mail/Passwort + Magic-Link (umgeht SIWA-Trigger automatisch). App-Store-Listing als „Business, Enterprise-CRM für Handwerk" mit Klartext-Reviewer-Notes „This is an enterprise B2B CRM application. Authentication is exclusively via the customer organization's account, per Guideline 4.8 enterprise/business apps exception."
|
||
36.4.6 Falls Reviewer doch SIWA fordert: Backup-Implementation in ~1 Tag aktivierbar.
|
||
36.4.7 Reviewer-Demo-Account: dedizierter Mandant `apple-review` mit Beispiel-Daten (5–10 Kontakte, 2–3 Projekte, Beispiel-Acceptance), Login-Credentials in App-Review-Notes.
|
||
36.4.8 Privacy-Manifest (Apple-Pflicht seit 2024) wird beim Build aus Master-Liste generiert. Datentypen, Tracking-Domains (keine in Phase 1, EU-Stack), Required-Reason-APIs deklariert.
|
||
36.4.9 Native-Tab-Bar im Capacitor-Wrapper für Top-Level-Navigation (Apple-Guideline 4.2 verlangt native Navigations-Elemente). Konfiguration je nach UI-Modus:
|
||
- Baustelle-Modus (Default Mobile): Heutige Aufträge / Projekte / Aufgaben / Chat / Mehr.
|
||
- Büro-Modus: Dashboard / CRM / Pipeline / Inbox / Mehr.
|
||
|
||
### 36.5 Account-Löschung in App (Pflicht)
|
||
36.5.1 Apple-Pflicht seit 2022, die App MUSS eine Account-Löschung in der App selbst anbieten. Vollständige Spec siehe Modul 35.2.
|
||
36.5.2 Sichtbarer Pfad in den Konto-Einstellungen auf gleicher Ebene wie Profil, Reviewer prüft das aktiv.
|
||
36.5.3 Multi-Step-Bestätigung funktioniert in der Mobile-App vollständig (kein Web-Browser-Workaround).
|
||
36.5.4 Bei Löschung in der Mobile-App werden zusätzlich alle lokalen Daten gelöscht (lokaler Cache, Biometrie-Token, Push-Token revoke), App startet danach mit leerem Login-Screen.
|
||
36.5.5 Vor-Lösch-Optional: User-Daten-Export anbieten, auf Mobile mit Klartext „Export wird per Email an dich gesendet, Download bitte am Computer." (ZIP kann groß sein).
|
||
|
||
### 36.6 Tiefenrouten (Universal Links)
|
||
36.6.1 Die Domain `app.hivegrid.de` ist als Universal Link (iOS) und App Link (Android) registriert.
|
||
36.6.2 Klick auf eine Push-Benachrichtigung mit Tiefenroute öffnet die App direkt auf dem Ziel-Bildschirm, nicht den Browser.
|
||
36.6.3 Bei nicht eingeloggtem User: Tiefenroute wird geparkt, Login zuerst, danach automatische Navigation.
|
||
36.6.4 Bei Tiefenroute zu falschem Mandanten: Mandanten-Switch-Prompt.
|
||
36.6.5 Bei fehlender Berechtigung: Klartext-Hinweis und Fallback aufs Mandanten-Dashboard.
|
||
|
||
### 36.7 Update-Mechanik
|
||
36.7.1 Web-Bundle-Updates: App prüft beim Start die Server-Version. Bei neuer Version: Download im Hintergrund, Klartext-Hinweis „Update verfügbar, beim nächsten App-Start aktiviert", Atomic-Swap beim nächsten Cold-Start.
|
||
36.7.2 Wrapper-Updates: regulär über App-Stores. Frequenz 1–2 Releases pro Quartal Default.
|
||
36.7.3 Force-Update bei zu alter Wrapper-Version, Sicherheits-Update oder OS-Mindestversion-Erhöhung, Modal ohne Schließen-Funktion mit Klartext-Grund und App-Store-Link.
|
||
|
||
### 36.8 Submission-Strategie
|
||
36.8.1 Reihenfolge: Google Play zuerst (niedrigere Hürde, schneller Feedback-Loop), dann Apple.
|
||
36.8.2 Vor Apple-Submit Pflicht-Checkliste: Demo-Account in Review-Notes, Privacy-Policy-URL, Privacy-Manifest aktuell, Account-Löschung sichtbar getestet, kein Pricing-UI im Build, Native-Features funktional, Screenshots zeigen ausschließlich tatsächlich vorhandene Funktionen.
|
||
36.8.3 Vor Google-Play-Submit: Data-Safety-Form, Account-Löschung in App + externe Lösch-URL, Privacy-Policy-URL, Permissions-Erklärungen.
|
||
36.8.4 Reject-Recovery-Playbook nach Apple-Guideline-Nummer (4.2 Minimum-Functionality, 3.1.1 IAP, 4.8 SIWA, 5.1.1 Account-Löschung, 2.1 Login).
|
||
|
||
### 36.X Phase 2 / bewusst NICHT in Phase 1
|
||
36.X.1 NFC für Zeiterfassung (Tap-to-Clock-In).
|
||
36.X.2 Bluetooth für Beacon-basierte Standort-Erkennung (Baustellen-Auto-Check-In).
|
||
36.X.3 Geolocation mit User-Consent für Einsatzort-Auto-Tagging.
|
||
36.X.4 CodePush / Capacitor Live Updates für Web-Code-Live-Updates ohne App-Store-Roundtrip.
|
||
36.X.5 CRDT-basierte Konflikt-Auflösung für Multi-User-Co-Editing.
|
||
36.X.6 Erweiterte Offline-Funktionen: CRM-Offline-Suche, Inbox-Cache, Booking-Bestätigungen, Lead-Bearbeitung.
|
||
36.X.7 Silent-Push-Capability für Hintergrund-Sync.
|
||
36.X.8 Watch-App-Companion (Apple Watch / Wear OS).
|
||
36.X.9 Mikrofon-Permission für Voice-Notes / Diktier-Funktion.
|
||
36.X.10 Tablet-spezifische UI-Optimierung (Side-by-Side-Layout im Büro-Modus).
|
||
|
||
### 36.Y Klartext-Fehlertexte (Beispiele)
|
||
36.Y.1 Push-Permission verweigert: „Push ist auf diesem Gerät deaktiviert. Du verpasst möglicherweise wichtige Updates. [Geräte-Einstellungen]"
|
||
36.Y.2 Face-ID-Fehler: „Face-ID nicht erkannt, bitte erneut versuchen oder Passwort eingeben."
|
||
36.Y.3 3x Biometrie-Fehlschlag: „Face-ID temporär gesperrt. Bitte mit Passwort anmelden."
|
||
36.Y.4 Hardware nicht da: „Dieses Gerät unterstützt kein Face-ID/Touch-ID."
|
||
36.Y.5 Kamera verweigert: „Kamera-Zugriff verweigert. [Geräte-Einstellungen öffnen]"
|
||
36.Y.6 Offline-Banner: „Du bist offline, gespeicherte Änderungen werden später hochgeladen."
|
||
36.Y.7 Sync-Erfolg: „Alle 7 Änderungen wurden synchronisiert."
|
||
36.Y.8 Sync-Fehler: „2 Änderungen konnten nicht hochgeladen werden. [Details]"
|
||
36.Y.9 Warteschlange voll: „Lokale Warteschlange voll (1.000 Einträge), bitte mit Internet verbinden."
|
||
36.Y.10 Foto-Speicher voll: „Foto-Speicher voll (500 MB), bitte Sync starten oder Fotos später aufnehmen."
|
||
36.Y.11 Force-Update: „Bitte aktualisiere die HiveGrid-App, diese Version wird nicht mehr unterstützt. [App-Store]"
|
||
36.Y.12 Apple-Compliance bei Feature-Block: „Diese Funktion ist im Cloud+-Plan verfügbar. Bitte Workspace-Admin kontaktieren oder am Computer aktivieren."
|
||
|
||
---
|
||
|
||
## Modul 38: Help-Center (öffentlich)
|
||
|
||
**Was es tut:** Eine öffentlich erreichbare Hilfeseite mit Erste-Schritte-Artikeln, Setup-Anleitungen und FAQ. Nicht zu verwechseln mit einer internen Wissens-Datenbank des Mandanten, dieses Help-Center gehört HiveGrid und ist für alle User gleich.
|
||
|
||
**Warum es wichtig ist:** Senkt die Support-Last und gibt Mitarbeitern und Mandanten-Admins Selbsthilfe-Inhalte. Auch SEO-relevant. Phase 1 bewusst minimal.
|
||
|
||
### 38.1 Öffentliche Markdown-Artikel
|
||
38.1.1 Inhalte werden als Markdown-Dateien im Repository gepflegt, nicht in einer Datenbank. Pflege erfolgt über Git-PRs durch das Plattform-Team. Keine Editor-UI in Phase 1.
|
||
38.1.2 Verzeichnis-Struktur pro Sprache und pro Kategorie:
|
||
- `content/help/de/erste-schritte/`, `content/help/de/vertrieb/`, `content/help/de/integrationen/` etc.
|
||
- Pro Kategorie ein Metadaten-File mit Label, Beschreibung, Icon, Sortier-Reihenfolge.
|
||
38.1.3 Pflicht-Felder pro Artikel-Frontmatter: Slug, Title, Kategorie, Sortier-Reihenfolge, Beschreibung, Datum letzte Aktualisierung. Optional: verwandte Artikel, Keywords, Veraltet-Marker, Redirect-Ziel.
|
||
38.1.4 Markdown-Body mit Standard-Formatierung: Überschriften (H2–H4), Listen, Code-Blöcke, Tabellen, Bilder, Links, Hinweis-Blocks (Info/Warnung).
|
||
38.1.5 Build-Schritt erzeugt: Volltext-Index, Kategorien-Manifest, Sitemap. Build-Validierung prüft alle Kategorie-Referenzen und alle Verlinkungen, bei Fehler bricht der Build ab.
|
||
38.1.6 Routen:
|
||
- `app.hivegrid.de/help/` → Sprach-Redirect (Phase 1 immer auf `/de/`).
|
||
- `app.hivegrid.de/help/de/` → Help-Home mit Kategorien-Übersicht und zentraler Suche.
|
||
- `app.hivegrid.de/help/de/{kategorie}/` → Liste der Artikel in dieser Kategorie.
|
||
- `app.hivegrid.de/help/de/{kategorie}/{slug}` → Einzel-Artikel.
|
||
- `app.hivegrid.de/help/de/search?q=...` → Such-Ergebnisse.
|
||
- `app.hivegrid.de/help/sitemap.xml` für SEO.
|
||
38.1.7 Öffentlich zugänglich, kein Login erforderlich, kein Mandanten-Kontext.
|
||
38.1.8 SEO: statisches Rendering mit langen Cache-Headern, pro Artikel Title und Description aus Frontmatter, Open-Graph-Tags, Canonical-URL.
|
||
38.1.9 In jedem App-Bereich kann ein optionales Hilfe-Icon mit Tiefenroute auf den passenden Help-Center-Artikel verlinken (Mapping pro Route konfiguriert).
|
||
38.1.10 Suche mit Title-Match zuerst, dann Description, Keywords, Body. Treffer-Snippet mit Highlight. Empty-State: „Nichts gefunden zu '{Query}'. Schreib uns: support@hivegrid.de"
|
||
38.1.11 Artikel-Detail bietet: Titel, Beschreibung, letzte-Aktualisierung-Datum, Markdown-Body, Inhaltsverzeichnis aus H2-Überschriften, verwandte Artikel als Liste am Ende, optionales „War dieser Artikel hilfreich?"-Feedback (Daumen hoch/runter, anonym).
|
||
38.1.12 Veraltete Artikel: Banner „Dieser Artikel ist veraltet, siehe stattdessen [neuer Link]"
|
||
38.1.13 404 (Slug nicht gefunden): „Diesen Artikel gibt's nicht mehr. Vielleicht hilft die Suche?"
|
||
|
||
### 38.2 Phase 1: 10–20 Artikel
|
||
38.2.1 Initial-Inventar (konkrete Liste mit Plattform-Team beim Bau finalisiert):
|
||
- Erste Schritte: Willkommen, Tenant einrichten, Erste Mitarbeiter einladen, Magic-Link-Login-FAQ.
|
||
- Vertrieb: Kontakte und Firmen, Lead-Inbox-Workflow, Sales-Pipeline-Grundlagen.
|
||
- Aufträge: Projekt anlegen, Plantafel nutzen, Acceptance-Protokoll-Anleitung.
|
||
- 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.
|
||
- 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.
|
||
|
||
### 38.X Phase 2 / spätere Features
|
||
38.X.1 DB-getriebene Pflege durch Plattform-Admin mit Editor-UI auf admin.hivegrid.de.
|
||
38.X.2 Mehrsprachigkeit: EN/TR/PL via DeepL-Pipeline aus DE-Quelltext, manuell verifiziert.
|
||
38.X.3 KI-gestützte Artikel-Suche (Help-Center-Inhalte als Embeddings-Korpus für KI-Assistent in der App).
|
||
38.X.4 View-Counts und Helpful-Votes-Statistik für das Plattform-Team.
|
||
38.X.5 Versionierung mit Sicht auf alte Artikel-Versionen bei Deprecation.
|
||
38.X.6 Kontextuelle Inline-Hilfe, Side-Panel direkt in der App statt Tab-Wechsel.
|
||
38.X.7 Video-Tutorials einbettbar (YouTube/Loom).
|
||
38.X.8 „Was ist neu?"-Changelog-Feed auf Help-Home.
|
||
|
||
### 38.Y Klartext-Fehlertexte (Beispiele)
|
||
38.Y.1 Sprache nicht da: „Englischsprachige Hilfe ist in Vorbereitung. Hier ist die deutsche Version." + Auto-Redirect.
|
||
38.Y.2 Empty-Search: „Nichts gefunden zu '{Query}'. Probier andere Begriffe, oder schreib uns direkt an support@hivegrid.de."
|
||
38.Y.3 Artikel 404: „Diese Hilfe-Seite gibt's nicht mehr. [Zur Übersicht] oder [Suche starten]."
|
||
|
||
---
|
||
|
||
## Modul 39: Help-Desk / Support
|
||
|
||
**Was es tut:** Ein einfaches In-App-„Problem melden"-Widget plus eine Support-E-Mail-Adresse, dahinter ein simples Ticket-System für das Plattform-Team. Kein Live-Chat, kein User-facing-Status-Tracking, Phase 1 bewusst klein.
|
||
|
||
**Warum es wichtig ist:** Die niedrige Hürde, „Wir hören zu" zu signalisieren, ist Teil der Anti-Agentur-Positionierung. Mandanten-User sollen Probleme schnell melden können, das Plattform-Team braucht eine sortierbare Eingangs-Liste.
|
||
|
||
### 39.1 In-App-Feedback-Widget
|
||
39.1.1 „Problem melden"-Trigger ist von jeder Mandanten-Route aus erreichbar (Designer entscheidet die genaue Platzierung, global in der Top-Bar, als Floating-Button oder ähnlich).
|
||
39.1.2 Im öffentlichen Help-Center gibt es einen identischen Trigger, der zu mailto:support@hivegrid.de verlinkt (kein Login → kein Mandanten-Kontext für ein Ticket).
|
||
39.1.3 Eingabe-Modal mit:
|
||
- Hinweis-Text „Was hakt? Wir lesen jedes Feedback persönlich."
|
||
- Anzeige der aktuellen Route, Transparenz, dass wir das mit-erfassen.
|
||
- DSGVO-Hinweis, dass Browser-Info und App-Version mitgeschickt werden.
|
||
- Mehrzeiliges Eingabefeld (Pflicht, mindestens 10 Zeichen).
|
||
- Anhang-Upload (Drag&Drop und Datei-Wähler), max. 5 Dateien zu je 10 MB. Erlaubte Formate: PNG, JPG, WEBP, PDF.
|
||
- „Screenshot der aktuellen Seite anhängen"-Funktion (One-Click, optional, mit User-Bestätigung).
|
||
- Senden-Button (deaktiviert bis ≥ 10 Zeichen).
|
||
39.1.4 Bei Senden automatisch erfasst: Mandant, User, aktuelle Route (ohne sensible Query-Parameter), Browser-Info (User-Agent, Viewport, Sprache, Timezone), App-Version, Zeitstempel.
|
||
39.1.5 Klartext bei Erfolg: „Danke. Wir haben dein Feedback bekommen und melden uns falls nötig."
|
||
39.1.6 Klartext bei Fehler: „Senden hat nicht geklappt, du kannst uns auch direkt schreiben: support@hivegrid.de"
|
||
39.1.7 Rate-Limit: max. 10 Submissions pro User pro Stunde. Body max. 10.000 Zeichen.
|
||
39.1.8 Jeder eingeloggte Mandanten-User kann Feedback senden, keine spezielle Berechtigung. „Problem melden" ist basale Funktion, kein Premium-Feature.
|
||
|
||
### 39.2 Email-basiertes Ticket-System Phase 1
|
||
39.2.1 Inbound-Mailbox: `support@hivegrid.de` läuft auf Google Workspace oder Scaleway-Mail.
|
||
39.2.2 Phase 1: das Plattform-Team liest die Mailbox außerhalb der App (Gmail-Web). Keine eigene Mail-Sync-Implementierung in HiveGrid für die Support-Mailbox.
|
||
39.2.3 Im Plattform-Admin-Bereich gibt es einen Direkt-Link zur externen Mailbox plus Klartext-Hinweis „Externe Support-Mailbox via Google Workspace".
|
||
39.2.4 Keine automatische Verknüpfung Mail ↔ Feedback in Phase 1, manuelle Pflege.
|
||
39.2.5 In-App-Feedback-Submissions landen im Plattform-Admin-Bereich „Feedback / Support":
|
||
- Liste mit Eingangs-Datum, Mandant, User, ersten 100 Zeichen Body, Anzahl Anhänge, Route, Status, zugewiesener Bearbeiter.
|
||
- Filter nach Status (offen / in Bearbeitung / gelöst / wontfix), Mandant, Bearbeiter, Zeitraum.
|
||
- Volltext-Suche über Body + Mandanten-Name + User-Name.
|
||
- Bulk-Status-Wechsel und Bulk-Zuweisung.
|
||
- CSV-Export der gefilterten Auswahl.
|
||
39.2.6 Detail-Ansicht pro Feedback:
|
||
- Vollständiger Body, Anhänge mit Vorschau.
|
||
- Mandanten-Block mit Plan, Status, Direktlink ins Mandanten-Admin.
|
||
- User-Block mit Rolle, Direktlink ins Mandanten-Admin.
|
||
- Route klickbar (für Plattform-Admin mit Impersonation-Recht).
|
||
- Browser-Info ausklappbar.
|
||
- Inline-Edit für Status und Bearbeiter.
|
||
- Interne Notizen (Markdown, nur Plattform-Admin-sichtbar).
|
||
- Aktivitäts-Log: alle Status-Wechsel, Bearbeiter-Wechsel, Notizen-Änderungen.
|
||
- Hard-Delete nur in Ausnahmefällen mit Klartext-Warnung.
|
||
39.2.7 Status-Lebenszyklus: offen → in Bearbeitung → gelöst oder wontfix; Re-Open jederzeit möglich.
|
||
39.2.8 Phase 1: KEINE Notifications zurück an den Mandanten-User über Status-Änderungen.
|
||
39.2.9 Berechtigungen Plattform-Admin-Seite: spezielle Plattform-Admin-Rechte für Lesen, Schreiben, Löschen.
|
||
39.2.10 Anhänge nutzen die zentrale Datei-Infrastruktur, Storage-Pfad pro Feedback im Mandanten-Storage.
|
||
|
||
### 39.X Phase 2 / spätere Features
|
||
39.X.1 In-App-Live-Chat mit Support (Intercom-/Crisp-Style oder Eigen-Implementierung).
|
||
39.X.2 Vollständiges Ticket-System mit Status-Tracking und Notifications zurück an User.
|
||
39.X.3 User-facing-Status-Page im Mandanten: Liste der eigenen Feedbacks mit Status, kann antworten.
|
||
39.X.4 NPS-Surveys (1×/Quartal, anonymisiert).
|
||
39.X.5 CSAT-Tracking (1–5 Sterne nach Resolution).
|
||
39.X.6 Support-Mailbox-Sync direkt in HiveGrid über die E-Mail-Integration (Modul 9).
|
||
39.X.7 Auto-Triage durch KI: Klassifikation Bug / Feature-Request / Frage / Beschwerde, Bearbeiter-Vorschlag.
|
||
39.X.8 Feedback-Voting: ähnliche Feedbacks zusammenfassen, andere Mandanten können „+1" geben (Public-Roadmap-Feel).
|
||
39.X.9 Integration mit Bug-Tracker (Linear / Jira / GitHub-Issues).
|
||
39.X.10 Slack-Notification an Plattform-Team-Channel bei neuem Feedback.
|
||
|
||
### 39.Y Klartext-Fehlertexte (Beispiele)
|
||
39.Y.1 Beschreibung zu kurz: „Bitte mindestens 10 Zeichen, je mehr Details, desto schneller können wir helfen."
|
||
39.Y.2 Anhang zu groß: „Datei zu groß (max. 10 MB). Beschneide sie oder lass sie weg, wir können trotzdem helfen."
|
||
39.Y.3 Senden gescheitert: „Senden hat nicht geklappt, Internet-Verbindung prüfen oder direkt an support@hivegrid.de mailen."
|
||
39.Y.4 Rate-Limit: „Du hast schon einige Meldungen in kurzer Zeit gesendet. Bitte warte kurz oder schreib uns direkt."
|
||
39.Y.5 Mandant pausiert: „Dein Workspace ist derzeit pausiert. Schreib uns direkt: support@hivegrid.de"
|
||
39.Y.6 Tenant inzwischen gelöscht (Plattform-Admin-Sicht): „Dieser Tenant wurde inzwischen gelöscht, Daten zu User/Tenant nur noch eingeschränkt verfügbar."
|